custom bg

# Conflicts:
#	apps/examples/desktop-app/sidecar/commands.ts

.clinerules/debug-harness.md

@@ -8,8 +8,9 @@ HTTP-controlled debugger for the VSCode extension at `src/dev/debug-harness/serv
 # Build extension first if needed (protos + esbuild):
 bun run protos && IS_DEV=true bun esbuild.mjs
 
-# Launch (skip-build if already built):
-bun src/dev/debug-harness/server.ts --skip-build --auto-launch
+# Launch (skip-build if already built). Run with node, NOT bun — Playwright's
+# Electron launch times out under bun:
+node src/dev/debug-harness/server.ts --skip-build --auto-launch
 
 # In another terminal:
 curl localhost:19229/api -d '{"method":"status"}'

.clinerules/general.md

@@ -16,6 +16,7 @@ This file is the secret sauce for working effectively in this codebase. It captu
 - The whole repo (including `apps/vscode`) uses **bun** for package management and task running. Emit `bun run X` / `bun install` / `bunx <bin>` / `bun file.ts`, never npm/npx. Node remains the *runtime* (VS Code's extension host and the standalone cline-core are Node), so Node-runtime tokens are legitimate and must not be "fixed" to bun — see @.clinerules/bun-and-node.md for the keep-list vs rewrite-list.
 - Avoid provider-specific string matching / hardcoded provider branches when fixing provider/config plumbing. Prefer provider metadata, shared catalog/defaults, explicit protocol/client capabilities, or centralized normalization utilities that apply by data shape rather than `providerId === "..."`. If a provider exception seems necessary, stop and explain why instead of adding ad-hoc string matching.
 - This is a VS Code extension—check `package.json` for available scripts before trying to verify builds (e.g., `bun run compile`, not `bun run build`).
+- When reading a configuration files that users may edit, use `readFileStrippingUtf8Bom`, `readFileSyncStrippingUtf8Bom`, or `stripUtf8Bom` from `@cline/shared/node`. DON'T strip byte order marks of user files handled by tools/passed to models.
 - When creating PRs, contributors should not create changelog-entry files. Maintainers handle release versioning and changelog curation during the release process.
 - When adding new feature flags, see this PR as a reference https://github.com/cline/cline/pull/7566
 - Additional instructions about making requests: @.clinerules/network.md

.github/workflows/ext-vscode-ab-package.yml

@@ -0,0 +1,205 @@
+name: ext-vscode-ab-package
+
+# Build (and optionally publish) the combined A/B VSIX: a tiny loader plus two
+# complete extension bundles — `next/` from the SDK-based apps/vscode on main,
+# `legacy/` from the legacy-extension branch. Cohort selection happens at
+# runtime via PostHog flags; see apps/vscode-rollout/README.md for the design
+# and the rollout runbook.
+
+on:
+    workflow_dispatch:
+        inputs:
+            version:
+                description: "Combined VSIX version — must exceed every previously published version (e.g. 4.1.0)"
+                required: true
+                type: string
+            next-ref:
+                description: "Ref to build the next (SDK) bundle from"
+                required: true
+                default: "main"
+                type: string
+            legacy-ref:
+                description: "Ref to build the legacy bundle from"
+                required: true
+                default: "legacy-extension"
+                type: string
+            publish:
+                description: "Publish to the VS Code Marketplace (unchecked: just build the .vsix artifact)"
+                required: true
+                default: false
+                type: boolean
+
+permissions:
+    contents: read
+
+concurrency:
+    group: ext-vscode-ab-package-${{ github.event.inputs.version }}
+    cancel-in-progress: false
+
+jobs:
+    package:
+        name: Build combined (legacy + next) VSIX
+        runs-on: ubuntu-latest
+        environment: publish
+        steps:
+            - name: Checkout next (SDK) source
+              uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.inputs.next-ref }}
+                  path: next-src
+                  lfs: true
+
+            - name: Checkout legacy source
+              uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.inputs.legacy-ref }}
+                  path: legacy-src
+                  lfs: true
+
+            - uses: oven-sh/setup-bun@v2
+              with:
+                  bun-version: 1.3.14
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 22
+
+            - name: Install next workspace dependencies
+              working-directory: next-src
+              run: bun install
+
+            # @cline/* are local workspace symlinks to source packages; apps/vscode's
+            # `package` script does NOT build them, so without this the esbuild step
+            # fails on a fresh checkout. (The nightly workflow already does this.)
+            - name: Build SDK packages
+              working-directory: next-src
+              run: bun run build:sdk
+
+            # Stamp the combined version into each bundle's package.json AFTER
+            # install and BEFORE its build: the About tab and telemetry
+            # extension_version read the bundle's own manifest, so without this
+            # the VSIX reports three different versions depending on where you
+            # look. (The nightly workflow gets the same alignment via nightlify.mjs.)
+            - name: Align next bundle version
+              working-directory: next-src/apps/vscode-rollout
+              run: node scripts/set-version.mjs --dir "$GITHUB_WORKSPACE/next-src/apps/vscode" --version "${{ github.event.inputs.version }}"
+
+            - name: Build next bundle
+              working-directory: next-src/apps/vscode
+              env:
+                  CLINE_ENVIRONMENT: production
+                  TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+                  ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
+                  # Inlined by esbuild: attributes every telemetry event with
+                  # extension_variant and unlocks the bundle's authoritative
+                  # extension.rollout.bundle_activated capture. Rollout builds only.
+                  CLINE_ROLLOUT_VARIANT: next
+                  # Match the stable publish workflow's OpenTelemetry production defaults.
+                  OTEL_TELEMETRY_ENABLED: ${{ secrets.OTEL_TELEMETRY_ENABLED }}
+                  OTEL_LOGS_EXPORTER: otlp
+                  OTEL_METRICS_EXPORTER: otlp
+                  OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
+                  OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
+                  OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
+              run: bun run package
+
+            - name: Install legacy dependencies
+              working-directory: legacy-src
+              run: |
+                  npm --prefix apps/vscode install --include=optional
+                  npm --prefix apps/vscode/webview-ui install --include=optional
+
+            - name: Align legacy bundle version
+              working-directory: next-src/apps/vscode-rollout
+              run: node scripts/set-version.mjs --dir "$GITHUB_WORKSPACE/legacy-src/apps/vscode" --version "${{ github.event.inputs.version }}"
+
+            - name: Build legacy bundle
+              working-directory: legacy-src/apps/vscode
+              env:
+                  CLINE_ENVIRONMENT: production
+                  TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+                  ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
+                  CLINE_ROLLOUT_VARIANT: legacy
+                  # Match the stable publish workflow's OpenTelemetry production defaults.
+                  OTEL_TELEMETRY_ENABLED: ${{ secrets.OTEL_TELEMETRY_ENABLED }}
+                  OTEL_LOGS_EXPORTER: otlp
+                  OTEL_METRICS_EXPORTER: otlp
+                  OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
+                  OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
+                  OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
+              run: npm run package
+
+            - name: Build loader and run rollout tests
+              working-directory: next-src/apps/vscode-rollout
+              env:
+                  TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+              run: |
+                  bun run typecheck
+                  bun run test
+                  bun run build:production
+
+            - name: Stitch combined VSIX staging
+              working-directory: next-src/apps/vscode-rollout
+              run: |
+                  node scripts/stitch.mjs \
+                    --next "$GITHUB_WORKSPACE/next-src/apps/vscode" \
+                    --legacy "$GITHUB_WORKSPACE/legacy-src/apps/vscode" \
+                    --loader dist/extension.js \
+                    --version "${{ github.event.inputs.version }}" \
+                    --out "$GITHUB_WORKSPACE/staging"
+
+            - name: Smoke-test loader against staging
+              working-directory: next-src/apps/vscode-rollout
+              run: node scripts/smoke-loader.mjs "$GITHUB_WORKSPACE/staging"
+
+            # This workflow publishes the STABLE identity. If nightlify ever leaks
+            # into this path the union manifest would ship under the wrong name.
+            # The bundle sub-manifest checks guard the set-version.mjs stamping:
+            # the About tab and telemetry extension_version read those files.
+            - name: Assert stable manifest identity
+              working-directory: staging
+              env:
+                  EXPECTED_VERSION: ${{ github.event.inputs.version }}
+              run: |
+                  node -e '
+                    const assert = require("node:assert");
+                    const expected = process.env.EXPECTED_VERSION;
+                    const pkg = require("./package.json");
+                    assert.equal(pkg.name, "claude-dev", `unexpected name ${pkg.name}`);
+                    assert.equal(pkg.publisher, "saoudrizwan", `unexpected publisher ${pkg.publisher}`);
+                    assert.equal(pkg.version, expected, `unexpected union version ${pkg.version}`);
+                    for (const bundle of ["next", "legacy"]) {
+                      const sub = require(`./${bundle}/package.json`);
+                      assert.equal(sub.version, expected, `unexpected ${bundle} bundle version ${sub.version}`);
+                    }
+                    console.log(`stable identity ok: ${pkg.publisher}.${pkg.name}@${pkg.version} (bundle versions aligned)`);
+                  '
+
+            - name: Package VSIX
+              working-directory: staging
+              run: |
+                  npm install -g @vscode/vsce
+                  # Preserve the narrowly scoped VSCE `sendgrid` scanner exemption used by
+                  # both standalone bundle workflows. No SendGrid credential is intentionally
+                  # supplied here; inspect the reported artifact before widening the exemption.
+                  vsce package --no-dependencies --allow-package-secrets sendgrid --out "claude-dev-${{ github.event.inputs.version }}.vsix"
+
+            - name: Upload VSIX artifact
+              uses: actions/upload-artifact@v4
+              with:
+                  name: claude-dev-${{ github.event.inputs.version }}
+                  path: staging/claude-dev-${{ github.event.inputs.version }}.vsix
+                  if-no-files-found: error
+
+            - name: Publish to Marketplace
+              if: ${{ github.event.inputs.publish == 'true' }}
+              working-directory: staging
+              env:
+                  VSCE_PAT: ${{ secrets.VSCE_PAT }}
+              run: |
+                  if [[ -z "$VSCE_PAT" ]]; then
+                    echo "Error: VSCE_PAT is required to publish."
+                    exit 1
+                  fi
+                  vsce publish --no-dependencies --packagePath "claude-dev-${{ github.event.inputs.version }}.vsix"

.github/workflows/ext-vscode-publish-nightly.yml

@@ -1,17 +1,40 @@
 name: ext-vscode-publish-nightly
 
+# Publishes saoudrizwan.cline-nightly as the COMBINED A/B VSIX: the rollout
+# loader plus two complete extension bundles — `next/` from this ref's
+# apps/vscode (SDK-based) and `legacy/` from the legacy-extension branch.
+# Cohort selection happens at runtime via PostHog flags; see
+# apps/vscode-rollout/README.md for the design and rollout runbook.
+#
+# The stable-identity equivalent of this pipeline is ext-vscode-ab-package.yml
+# (manual dispatch, publishes claude-dev). Shared logic lives in
+# apps/vscode-rollout/scripts (nightlify/gen-manifest/stitch/smoke) so both
+# workflows stay thin. The single-bundle nightly path this replaced
+# (apps/vscode/scripts/publish-nightly.mjs) remains for manual feature-branch
+# pre-release publishes.
+
 on:
   schedule:
     # Every day at 4:00 AM PST (12:00 UTC)
     - cron: "0 12 * * *"
   workflow_dispatch:
+    inputs:
+      legacy-ref:
+        description: "Ref to build the legacy bundle from"
+        required: false
+        default: "legacy-extension"
+        type: string
+      dry-run:
+        description: "Build and upload the .vsix artifact without publishing or tagging"
+        required: false
+        default: false
+        type: boolean
 
-run-name: "Publish Nightly from ${{ github.ref_name }} @ ${{ github.sha }}"
+run-name: "Publish Combined Nightly from ${{ github.ref_name }} @ ${{ github.sha }}"
 
-# Prevent concurrent publish runs on the same branch. The nightly publish script
-# generates the extension version from a seconds-resolution timestamp, so parallel
-# runs on the same ref can collide on the same version and cause publish failures
-# or inconsistent tagging. Runs on different branches proceed independently.
+# Prevent concurrent publish runs on the same branch: the version is generated
+# from a seconds-resolution timestamp, so parallel runs on the same ref can
+# collide on the same version and cause publish failures or inconsistent tagging.
 concurrency:
   group: ext-vscode-publish-nightly-${{ github.ref }}
   cancel-in-progress: false
@@ -20,7 +43,7 @@ permissions: {}
 
 jobs:
   test:
-    if: github.repository == 'cline/cline' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dpc/sdk-migration-simpler-login')
+    if: github.repository == 'cline/cline'
     permissions:
       contents: read
       pull-requests: read
@@ -30,60 +53,79 @@ jobs:
     needs: test
     permissions:
       contents: write
-    name: Publish Cline (Nightly) Extension
-    if: github.repository == 'cline/cline' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dpc/sdk-migration-simpler-login')
+    name: Publish Cline (Nightly) Combined Extension
+    # Defense in depth: only protected main may enter the publishing environment.
+    # This `if` is advisory because a dispatched branch runs its own copy of this
+    # file; the enforced gate is the PublishNightly environment's deployment-branch
+    # policy, which must also allow only main.
+    if: github.repository == 'cline/cline' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     environment: PublishNightly
-    # The VS Code extension's package.json and lockfiles live under apps/vscode/
-    # (the repo root has no package.json). Mirror ext-vscode-test.yml so install
-    # and publish steps run in the correct workspace.
-    defaults:
-      run:
-        working-directory: apps/vscode
 
     steps:
-      - name: Checkout selected branch
+      - name: Checkout next (SDK) source
         uses: actions/checkout@v4
         with:
           ref: ${{ github.sha }}
+          path: next-src
           lfs: true
           persist-credentials: false
 
-      - name: Show build source
-        working-directory: ${{ github.workspace }}
+      - name: Checkout legacy source
+        uses: actions/checkout@v4
+        with:
+          # NOTE: inputs are empty strings on `schedule` events, so the ||
+          # fallback (not the input's declared default) is what the cron uses.
+          ref: ${{ inputs.legacy-ref || 'legacy-extension' }}
+          path: legacy-src
+          lfs: true
+          persist-credentials: false
+
+      - name: Show build sources
+        env:
+          # Routed through env rather than interpolated into the script body so
+          # a crafted dispatch input can't inject shell (hygiene: dispatchers
+          # need write access anyway, but keep the pattern clean).
+          LEGACY_REF: ${{ inputs.legacy-ref || 'legacy-extension' }}
         run: |
-          echo "Building ref: $GITHUB_REF"
-          echo "Building sha: $GITHUB_SHA"
-          git --no-pager log -1 --oneline
+          echo "next:   $(git -C next-src rev-parse HEAD)"
+          echo "legacy: $(git -C legacy-src rev-parse HEAD) ($LEGACY_REF)"
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
           bun-version: 1.3.14
 
-      # Node is still REQUIRED in the publish job (not just for install): the publish
-      # scripts run as `node ./scripts/publish-*.mjs` and shell out to `npx ovsx`.
-      # setup-bun does not provide a Node runtime, so keep setup-node here.
-      # Pinned to Node 22 because newer LTS (Node 24 / npm 11) can make vsce's
-      # `npm list` dependency detection fail with ELSPROBLEMS during packaging.
+      # Node is required beyond install: the rollout scripts run under node and
+      # publishing shells out to vsce/ovsx. Pinned to Node 22 because newer LTS
+      # (Node 24 / npm 11) can make vsce's dependency detection fail.
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 22
 
-      # Single root install resolves the whole bun workspace at once (replaces the
-      # per-package `npm ci` steps for apps/vscode + webview-ui).
-      - name: Install workspace dependencies
-        working-directory: ${{ github.workspace }}
+      # ONE version for the next bundle, the legacy bundle, and the union
+      # manifest: gen-manifest hard-fails if the bundle identities diverge.
+      # Same scheme as the standalone nightly: <major>.<minor>.<unix-seconds>
+      # from next's base version, so it keeps outranking earlier nightlies.
+      - name: Compute nightly version
+        id: version
+        run: |
+          BASE=$(node -p "require('./next-src/apps/vscode/package.json').version")
+          VERSION="$(echo "$BASE" | cut -d. -f1,2).$(date +%s)"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Combined nightly version: $VERSION (base $BASE)"
+
+      - name: Install next workspace dependencies
+        working-directory: next-src
         run: bun install --frozen-lockfile
 
-      # @cline/* are local workspace symlinks to source packages; build dist/ before
-      # packaging/publishing the extension.
       - name: Build SDK packages
-        working-directory: ${{ github.workspace }}
+        working-directory: next-src
         run: bun run build:sdk
 
       - name: Assert better-sqlite3 native binary present
+        working-directory: next-src/apps/vscode
         run: |
           NODE_FILE="node_modules/better-sqlite3/build/Release/better_sqlite3.node"
           if [ ! -f "$NODE_FILE" ]; then
@@ -93,20 +135,24 @@ jobs:
           fi
           echo "Found better-sqlite3 native binary: $NODE_FILE"
 
-      # vsce is now a workspace devDependency (on node_modules/.bin), but ovsx is not
-      # vendored and the publish script invokes it via `npx ovsx`, so install ovsx
-      # globally here (npm is available via setup-node). vsce is installed globally
-      # too to preserve the script's existing PATH expectations.
-      - name: Install Publishing Tools
-        run: npm install -g @vscode/vsce ovsx
+      # Rewrite each bundle's package.json to the cline-nightly identity BEFORE
+      # its build (runtime command/config IDs derive from the manifest) and
+      # AFTER dependency install (workspace self-links key off the original
+      # package name).
+      - name: Nightlify next bundle manifest
+        working-directory: next-src/apps/vscode-rollout
+        run: node scripts/nightlify.mjs --dir "$GITHUB_WORKSPACE/next-src/apps/vscode" --version "${{ steps.version.outputs.version }}"
 
-      - name: Publish Nightly Extension
+      - name: Build next bundle
+        working-directory: next-src/apps/vscode
         env:
-          VSCE_PAT: ${{ secrets.VSCE_PAT }}
-          OVSX_PAT: ${{ secrets.OVSX_PAT }}
+          CLINE_ENVIRONMENT: production
           TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
           ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
-          CLINE_ENVIRONMENT: production
+          # Inlined by esbuild: attributes every telemetry event with
+          # extension_variant and unlocks the bundle's authoritative
+          # extension.rollout.bundle_activated capture. Rollout builds only.
+          CLINE_ROLLOUT_VARIANT: next
           # OpenTelemetry production defaults (can be overridden at runtime)
           OTEL_TELEMETRY_ENABLED: ${{ secrets.OTEL_TELEMETRY_ENABLED }}
           OTEL_LOGS_EXPORTER: otlp
@@ -114,12 +160,129 @@ jobs:
           OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
           OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
           OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
-        # The script itself runs under `node ./scripts/publish-nightly.mjs`; bun run
-        # just launches it. Node + npm (for `npx ovsx`) are provided by setup-node above.
-        run: bun run publish:marketplace:nightly
+        run: bun run package
+
+      - name: Install legacy dependencies
+        working-directory: legacy-src
+        run: |
+          npm --prefix apps/vscode install --include=optional
+          npm --prefix apps/vscode/webview-ui install --include=optional
+
+      - name: Nightlify legacy bundle manifest
+        working-directory: next-src/apps/vscode-rollout
+        run: node scripts/nightlify.mjs --dir "$GITHUB_WORKSPACE/legacy-src/apps/vscode" --version "${{ steps.version.outputs.version }}"
+
+      - name: Build legacy bundle
+        working-directory: legacy-src/apps/vscode
+        env:
+          CLINE_ENVIRONMENT: production
+          TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+          ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
+          CLINE_ROLLOUT_VARIANT: legacy
+          # Legacy's esbuild inlines these too (its own publish workflow passes
+          # them) — omitting them here would ship the legacy bundle with the
+          # OTel pipeline dead, unlike what legacy users get today.
+          OTEL_TELEMETRY_ENABLED: ${{ secrets.OTEL_TELEMETRY_ENABLED }}
+          OTEL_LOGS_EXPORTER: otlp
+          OTEL_METRICS_EXPORTER: otlp
+          OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
+          OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
+          OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
+        run: npm run package
+
+      - name: Build loader and run rollout tests
+        working-directory: next-src/apps/vscode-rollout
+        env:
+          TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+        run: |
+          bun run typecheck
+          bun run test
+          bun run build:production
+
+      - name: Stitch combined VSIX staging
+        working-directory: next-src/apps/vscode-rollout
+        run: |
+          node scripts/stitch.mjs \
+            --next "$GITHUB_WORKSPACE/next-src/apps/vscode" \
+            --legacy "$GITHUB_WORKSPACE/legacy-src/apps/vscode" \
+            --loader dist/extension.js \
+            --version "${{ steps.version.outputs.version }}" \
+            --out "$GITHUB_WORKSPACE/staging"
+
+      - name: Smoke-test loader against staging
+        working-directory: next-src/apps/vscode-rollout
+        run: node scripts/smoke-loader.mjs "$GITHUB_WORKSPACE/staging"
+
+      # The nightly identity must have fully propagated (nightlify -> both
+      # bundle manifests -> union manifest) or we'd publish over the stable
+      # extension ID. The bundle sub-manifest checks guard the version
+      # stamping: the About tab and telemetry extension_version read those.
+      - name: Assert nightly manifest identity
+        working-directory: staging
+        env:
+          EXPECTED_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          node -e '
+            const assert = require("node:assert");
+            const expected = process.env.EXPECTED_VERSION;
+            const pkg = require("./package.json");
+            assert.equal(pkg.name, "cline-nightly", `unexpected name ${pkg.name}`);
+            assert.equal(pkg.publisher, "saoudrizwan", `unexpected publisher ${pkg.publisher}`);
+            assert.equal(pkg.version, expected, `unexpected union version ${pkg.version}`);
+            for (const bundle of ["next", "legacy"]) {
+              const sub = require(`./${bundle}/package.json`);
+              assert.equal(sub.name, "cline-nightly", `unexpected ${bundle} bundle name ${sub.name}`);
+              assert.equal(sub.version, expected, `unexpected ${bundle} bundle version ${sub.version}`);
+            }
+            console.log(`nightly identity ok: ${pkg.publisher}.${pkg.name}@${pkg.version} (bundle identities aligned)`);
+          '
+
+      - name: Install Publishing Tools
+        run: npm install -g @vscode/vsce ovsx
+
+      - name: Package VSIX
+        working-directory: staging
+        # Preserve the narrowly scoped VSCE `sendgrid` scanner exemption used by
+        # both standalone bundle workflows. No SendGrid credential is intentionally
+        # supplied here; inspect the reported artifact before widening the exemption.
+        run: vsce package --no-dependencies --allow-package-secrets sendgrid --out "cline-nightly-${{ steps.version.outputs.version }}.vsix"
+
+      - name: Upload VSIX artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cline-nightly-${{ steps.version.outputs.version }}
+          path: staging/cline-nightly-${{ steps.version.outputs.version }}.vsix
+          if-no-files-found: error
+
+      # The job is main-only; step-level dry-run gating still permits a build-only
+      # rehearsal without publishing or tagging.
+      - name: Publish to VS Code Marketplace and Open VSX
+        if: github.ref == 'refs/heads/main' && inputs.dry-run != true
+        working-directory: staging
+        env:
+          VSCE_PAT: ${{ secrets.VSCE_PAT }}
+          OVSX_PAT: ${{ secrets.OVSX_PAT }}
+        run: |
+          if [[ -z "$VSCE_PAT" ]]; then
+            echo "Error: VSCE_PAT is required to publish."
+            exit 1
+          fi
+          vsce publish --no-dependencies --packagePath "cline-nightly-${{ steps.version.outputs.version }}.vsix"
+          if [[ -n "$OVSX_PAT" ]]; then
+            npx ovsx publish --packagePath "cline-nightly-${{ steps.version.outputs.version }}.vsix" --pat "$OVSX_PAT"
+          else
+            echo "WARNING: OVSX_PAT not set; skipping Open VSX publish."
+          fi
 
       - name: Tag published commit
-        working-directory: ${{ github.workspace }}
+        if: github.ref == 'refs/heads/main' && inputs.dry-run != true
+        # Best-effort bookkeeping: the default GITHUB_TOKEN cannot create a ref
+        # whose commit modifies workflow files (no workflows permission exists
+        # for it), so this step fails whenever HEAD touched .github/workflows.
+        # The publish already succeeded by this point — don't mark the run red;
+        # push the tag manually with user credentials when it matters.
+        continue-on-error: true
+        working-directory: next-src
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
@@ -127,10 +290,11 @@ jobs:
           SHORT_SHA=$(git rev-parse --short=12 HEAD)
           TIMESTAMP=$(date -u +"%Y%m%d%H%M%S")
           TAG="nightly-${SAFE_REF}-${TIMESTAMP}-${SHORT_SHA}"
+          LEGACY_SHA=$(git -C "$GITHUB_WORKSPACE/legacy-src" rev-parse HEAD)
 
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a "$TAG" -m "Cline Nightly published from ${GITHUB_REF_NAME} at ${GITHUB_SHA}"
+          git tag -a "$TAG" -m "Cline Nightly (combined A/B) published from ${GITHUB_REF_NAME} at ${GITHUB_SHA} (legacy bundle: ${LEGACY_SHA})"
           # Use an explicit HTTPS remote with GH_TOKEN because checkout was run with
           # persist-credentials: false, so actions/checkout did not persist a git credential helper.
           git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "refs/tags/${TAG}"

.github/workflows/ext-vscode-test.yml

@@ -126,7 +126,7 @@ jobs:
         needs: [detect-changes, quality-checks]
         if: needs.detect-changes.outputs.vscode == 'true'
         env:
-            VSCODE_TEST_VERSION: 1.103.0
+            VSCODE_TEST_VERSION: 1.101.0
         strategy:
             fail-fast: false
             matrix:

.github/workflows/sdk-publish.yml

@@ -260,6 +260,41 @@ jobs:
             git push origin "refs/tags/${TAG}"
           done
 
+      - name: Get Previous SDK Tag
+        if: steps.check_commits.outputs.skip != 'true' && steps.channel.outputs.channel == 'latest'
+        id: prev_tag
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          # The checkout is shallow and tagless, so fetch the release tags explicitly.
+          git fetch origin "+refs/tags/sdk/sdk/v*:refs/tags/sdk/sdk/v*"
+          PREV_TAG=$(git tag -l 'sdk/sdk/v*' | grep -vx "sdk/sdk/v${VERSION}" | sort -V | tail -1 || echo "")
+          echo "prev_tag=$PREV_TAG" >> $GITHUB_OUTPUT
+
+      - name: Get Changelog Entry
+        if: steps.check_commits.outputs.skip != 'true' && steps.channel.outputs.channel == 'latest'
+        id: changelog
+        run: |
+          # Grab content between the first "## " header and the next one in sdk/CHANGELOG.md
+          CONTENT=$(awk '/^## [0-9]/{if(found) exit; found=1; next} found{print}' sdk/CHANGELOG.md)
+          DELIMITER=$(openssl rand -hex 8)
+          echo "content<<${DELIMITER}" >> $GITHUB_OUTPUT
+          echo "$CONTENT" >> $GITHUB_OUTPUT
+          echo "${DELIMITER}" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        if: steps.check_commits.outputs.skip != 'true' && steps.channel.outputs.channel == 'latest'
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: sdk/sdk/v${{ steps.version.outputs.version }}
+          name: "SDK v${{ steps.version.outputs.version }}"
+          body: |
+            ${{ steps.changelog.outputs.content }}
+
+            ${{ steps.prev_tag.outputs.prev_tag != '' && format('**Full Changelog**: https://github.com/{0}/compare/{1}...sdk/sdk/v{2}', github.repository, steps.prev_tag.outputs.prev_tag, steps.version.outputs.version) || '' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
       - name: Summary
         if: steps.check_commits.outputs.skip != 'true'
         env:
@@ -280,3 +315,26 @@ jobs:
             echo "  - sdk/core/v${VERSION}"
             echo "  - sdk/sdk/v${VERSION}"
           fi
+
+      - name: Post release to Slack
+        if: steps.check_commits.outputs.skip != 'true' && steps.channel.outputs.channel == 'latest'
+        uses: slackapi/slack-github-action@v3.0.1
+        with:
+          method: chat.postMessage
+          token: ${{ secrets.SLACK_RELEASE_BOT_TOKEN }}
+          payload: |
+            channel: "C0APVKGGZFC"
+            text: "Cline SDK v${{ steps.version.outputs.version }}"
+            blocks:
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: "Cline SDK v${{ steps.version.outputs.version }}"
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: ${{ toJSON(steps.changelog.outputs.content) }}
+              - type: "context"
+                elements:
+                  - type: "mrkdwn"
+                    text: "<https://www.npmjs.com/package/@cline/sdk/v/${{ steps.version.outputs.version }}|View on npm>${{ steps.prev_tag.outputs.prev_tag != '' && format(' | Full Changelog: https://github.com/{0}/compare/{1}...sdk/sdk/v{2}', github.repository, steps.prev_tag.outputs.prev_tag, steps.version.outputs.version) || '' }}"

.greptile/rules.md

@@ -42,6 +42,8 @@ event names. It exports:
    "emits X as a normal opt-out-respecting event"). Events that intentionally bypass
    opt-out must use `captureRequired` and assert that explicitly.
 
+**All events should be named using snake_case and so should their properties**
+
 ## The Activation Funnel
 
 The canonical funnel that downstream analytics depends on:

.vscode/tasks.json

@@ -123,7 +123,7 @@
 					"background": {
 						"activeOnStart": true,
 						"beginsPattern": "^Building webview for|^\\s*VITE",
-						"endsPattern": "^.*Local:\\s+http://localhost:[0-9]+/"
+						"endsPattern": "^.*Local:\\s+http://127\\.0\\.0\\.1:[0-9]+/"
 					}
 				}
 			],

apps/cli/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Cline CLI Changelog
 
+## 3.0.44
+
+- Improved max output token handling across providers (gateway routing, OpenAI vendor, and reasoning models) (from SDK v0.0.64)
+- Frontmatter and configuration files that start with a UTF-8 byte order mark (e.g. saved by Windows editors) now parse correctly (from SDK v0.0.64)
+
+## 3.0.43
+
+- The CLI now automatically trusts your operating system's certificate store, so it works behind corporate proxies and TLS-inspecting firewalls without manually setting `NODE_EXTRA_CA_CERTS` (fixes "unable to get local issuer certificate" errors, including Windows intermediate CA stores)
+
+## 3.0.42
+
+- Fixed Ollama native API routing so context window and timeout settings work again
+
+## 3.0.41
+
+- Compaction now shows progress status in the TUI
+- Model IDs are now suggested from OpenAI-compatible endpoints when configuring a provider
+- Workspace git info (branch/remote) is now persisted and refreshed across sessions
+- Compaction no longer runs during an active turn
+- Fixed a crash when the terminal title was updated during TUI teardown
+- The API key fallback hint is now highlighted for better visibility
+- Benign git states are no longer reported as workspace initialization errors
+
+## 3.0.40
+
+- Added a manual API key escape hatch for Cline OAuth providers, so you can enter a key by hand from settings
+- Fixed provider config not reloading when switching models
+- Fixed auto-update failing to detect Bun global installs after symlink resolution
+- Fixed unexpected logouts caused by transient network or server errors during token refresh
+- The ClinePass usage-limit error is now surfaced clearly when you hit the limit
+- Session id is now preserved when continuing within the same session
+- Hardened context compaction budget handling
+
+## 3.0.39
+
+- You can now select Cline free models on the ClinePass provider in the model picker
+- Removed the retired ClinePass GLM 5.1 model
+- Fixed OpenAI Codex model metadata under the GPT Subscription provider
+- `str_replace` edits now report accurate diffs
+- Fixed context compaction so canonical session history is preserved
+- The detached hub daemon now emits telemetry, and telemetry identity now includes `user_id`
+- Cline provider requests now send versioned client-identity headers
+
 ## 3.0.38
 
 - New plan/act accent palette: act mode is now blue (`#79b8ff`) and plan mode amber, replacing the old cyan/yellow — applied across dialogs, the model selector, config, onboarding, markdown, and syntax highlighting, with light-theme variants tuned for contrast

apps/cli/README.md

@@ -346,9 +346,24 @@ Desktop-integrated approval mode is also supported via env wiring (`CLINE_TOOL_A
 - `CLINE_LOG_LEVEL` - Runtime log level (`trace|debug|info|warn|error|fatal|silent`, default `info`)
 - `CLINE_LOG_PATH` - Runtime log file path (default `<CLINE_DATA_DIR>/logs/cline.log`)
 - `CLINE_LOG_NAME` - Logger name embedded in runtime log records
+- `CLINE_DEBUG` - Set to `1`/`true` to print wrapper diagnostics (e.g. the CA bundle summary)
 
 `--key` takes precedence over environment variables.
 
+## Certificate trust
+
+The CLI automatically trusts your operating system's certificate store, so it
+works behind corporate TLS-inspecting proxies and with self-signed/internal
+endpoints without any setup. On launch the `cline` wrapper harvests the OS trust
+anchors and writes them to `~/.cline/cli-node-extra-ca-certs.pem`, then points
+the runtime's `NODE_EXTRA_CA_CERTS` at that bundle. The file is regenerated when
+it changes and is safe to delete (it is rebuilt on the next run).
+
+If you set `NODE_EXTRA_CA_CERTS` yourself, your certificates are **merged** into
+that bundle alongside the system store rather than replacing it. Run with
+`CLINE_DEBUG=1` to see how many OS and user CAs were loaded and where the bundle
+was written.
+
 ## Contributing
 
 See [DEVELOPMENT.md](./DEVELOPMENT.md) for local development setup, monorepo structure, and TUI architecture. See [DISTRIBUTION.md](./DISTRIBUTION.md) for how the CLI is packaged and distributed.

apps/cli/bin/ca-certs.cjs

@@ -0,0 +1,281 @@
+// Auto-discovery of OS trust anchors for the Cline CLI.
+//
+// Bun does not read the OS trust store, so the 3.x CLI cannot see corporate
+// MITM / self-signed CAs out of the box. This runs in the Node `bin/cline`
+// wrapper (not Bun), reads the full OS store via tls.getCACertificates("system")
+// (Node >= 22, no --use-system-ca flag), and hands the certs to the Bun child
+// via NODE_EXTRA_CA_CERTS, which both runtimes honor. Mirrors the JetBrains
+// plugin's configureCertificates(), sourcing from the OS instead of the IDE.
+//
+// Dependency-free CommonJS with injectable modules so it is unit-testable and
+// ships verbatim in the published wrapper package.
+
+const PEM_MARKER = "-----BEGIN CERTIFICATE-----";
+const CERT_BLOCK =
+	/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g;
+
+/**
+ * Returns only the complete certificate blocks from PEM text, or null when
+ * there are none. User files may also hold private keys (combined cert+key
+ * PEMs) or other sections, which must never be copied into the managed
+ * bundle. Files that contain nothing but certificates pass through verbatim
+ * so unchanged bundles keep hash-skipping the rewrite.
+ */
+function sanitizePem(text) {
+	const blocks = text.match(CERT_BLOCK) ?? [];
+	if (blocks.length === 0) {
+		return null;
+	}
+	const rest = text.replace(CERT_BLOCK, "");
+	if (/^\s*$/.test(rest)) {
+		return text;
+	}
+	return `${blocks.join("\n")}\n`;
+}
+
+/**
+ * Returns OS-trusted certificates as PEM strings, or [] when unavailable.
+ * tls.getCACertificates("system") requires Node >= 22.
+ */
+function harvestSystemCerts(tlsModule) {
+	try {
+		const tls = tlsModule || require("node:tls");
+		if (typeof tls.getCACertificates !== "function") {
+			return [];
+		}
+		const certs = tls.getCACertificates("system");
+		if (!Array.isArray(certs)) {
+			return [];
+		}
+		return certs.filter(
+			(cert) => typeof cert === "string" && cert.includes(PEM_MARKER),
+		);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Returns the file's certificate blocks as PEM text, or null when missing,
+ * unreadable, or holding no complete certificate block.
+ */
+function readUserBundle(fsModule, userPath) {
+	if (!userPath) {
+		return null;
+	}
+	try {
+		const fs = fsModule || require("node:fs");
+		const stat = fs.statSync(userPath, { throwIfNoEntry: false });
+		if (!stat || !stat.isFile()) {
+			return null;
+		}
+		// Binary DER would not have loaded in the runtime either; require PEM.
+		return sanitizePem(fs.readFileSync(userPath, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Reads the user's NODE_EXTRA_CA_CERTS value into PEM strings. Node treats the
+ * value as a single file, but some users set an OS-path-delimited list; the
+ * whole value is tried as one file first, then split.
+ * The managed bundle is excluded so reading it back never re-appends its certs.
+ */
+function readUserCerts(fsModule, pathModule, value, managedPath) {
+	if (!value) {
+		return [];
+	}
+	const fs = fsModule || require("node:fs");
+	const path = pathModule || require("node:path");
+	const candidates = [];
+	const whole = readUserBundle(fs, value);
+	if (whole) {
+		candidates.push({ filePath: value, pem: whole });
+	} else if (value.includes(path.delimiter)) {
+		for (const segment of value.split(path.delimiter)) {
+			const trimmed = segment.trim();
+			if (!trimmed) {
+				continue;
+			}
+			const pem = readUserBundle(fs, trimmed);
+			if (pem) {
+				candidates.push({ filePath: trimmed, pem });
+			}
+		}
+	}
+	const pems = [];
+	for (const candidate of candidates) {
+		const isManaged =
+			managedPath &&
+			path.resolve(candidate.filePath) === path.resolve(managedPath);
+		if (!isManaged) {
+			pems.push(candidate.pem);
+		}
+	}
+	return pems;
+}
+
+/**
+ * Concatenates the user PEMs (if any) and the system certificates into one
+ * bundle. A separating newline is inserted between parts so adjacent END/BEGIN
+ * markers cannot fuse into one invalid line.
+ */
+function buildBundle({ systemCerts, userPems }) {
+	const parts = [...(userPems ?? []), ...systemCerts];
+	return parts
+		.map((part) => (part.endsWith("\n") ? part : `${part}\n`))
+		.join("");
+}
+
+/** Counts individual PEM certificates across the given bundle strings. */
+function countCerts(pems) {
+	let count = 0;
+	for (const pem of pems) {
+		count += pem.split(PEM_MARKER).length - 1;
+	}
+	return count;
+}
+
+function readFileIfExists(fs, filePath) {
+	try {
+		return fs.readFileSync(filePath, "utf8");
+	} catch {
+		return null;
+	}
+}
+
+function resolveClineDir(env, os, path) {
+	return env.CLINE_DIR?.trim() || path.join(os.homedir(), ".cline");
+}
+
+/**
+ * True when the api-unavailable warning should print. Stamped per Node version
+ * in the cline dir so the nudge shows once rather than on every command; a
+ * version change (upgrade that still falls short, or downgrade) re-arms it.
+ * When the stamp cannot be read or written, warn — bookkeeping failures must
+ * never suppress a real diagnostic.
+ */
+function shouldWarnApiUnavailable(env, deps = {}) {
+	const fs = deps.fs || require("node:fs");
+	const os = deps.os || require("node:os");
+	const path = deps.path || require("node:path");
+	const version = deps.nodeVersion || process.versions.node;
+	const dir = resolveClineDir(env, os, path);
+	const stamp = path.join(dir, `.ca-api-warned-${version}`);
+	try {
+		if (fs.existsSync(stamp)) {
+			return false;
+		}
+		fs.mkdirSync(dir, { recursive: true });
+		fs.writeFileSync(stamp, "", { mode: 0o600 });
+		return true;
+	} catch {
+		return true;
+	}
+}
+
+/** Atomically writes [content] to [target]; returns true on success. */
+function writeBundle(fs, dir, target, content) {
+	const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		fs.mkdirSync(dir, { recursive: true });
+		// Owner read/write: the bundle holds public CA material, not secrets,
+		// but there is no reason to make it world-writable.
+		fs.writeFileSync(tmp, content, { mode: 0o600 });
+		try {
+			fs.renameSync(tmp, target);
+		} catch {
+			// Windows can reject rename over a file a concurrent child holds open.
+			fs.rmSync(target, { force: true });
+			fs.renameSync(tmp, target);
+		}
+		return true;
+	} catch {
+		// Never leave a partial temp file behind (e.g. ENOSPC mid-write).
+		try {
+			fs.rmSync(tmp, { force: true });
+		} catch {
+			// Ignore: best-effort cleanup.
+		}
+		return false;
+	}
+}
+
+/**
+ * Harvests OS trust anchors, merges them with any user NODE_EXTRA_CA_CERTS, and
+ * points env.NODE_EXTRA_CA_CERTS at a single managed PEM bundle. Mutates `env`
+ * in place. Returns an outcome the caller can log; `action` is one of
+ * "unchanged" | "written" | "write-failed-reused" | "write-failed" |
+ * "no-system-certs" | "api-unavailable".
+ */
+function configureNodeExtraCaCerts(env, deps = {}) {
+	const fs = deps.fs || require("node:fs");
+	const os = deps.os || require("node:os");
+	const path = deps.path || require("node:path");
+	const tls = deps.tls || require("node:tls");
+
+	// tls.getCACertificates("system") needs Node >= 22.15; on older Nodes the
+	// harvest cannot run at all, which the caller should surface to the user.
+	if (typeof tls.getCACertificates !== "function") {
+		return {
+			action: "api-unavailable",
+			path: null,
+			systemCertCount: 0,
+			userCertCount: 0,
+		};
+	}
+
+	const systemCerts = harvestSystemCerts(tls);
+	if (systemCerts.length === 0) {
+		// Nothing to add: leave any user-provided NODE_EXTRA_CA_CERTS untouched
+		// and let the runtime fall back to its bundled CAs.
+		return {
+			action: "no-system-certs",
+			path: null,
+			systemCertCount: 0,
+			userCertCount: 0,
+		};
+	}
+
+	const managedDir = resolveClineDir(env, os, path);
+	const managedPath = path.join(managedDir, "cli-node-extra-ca-certs.pem");
+	const userValue = (env.NODE_EXTRA_CA_CERTS || "").trim() || null;
+	const userPems = readUserCerts(fs, path, userValue, managedPath);
+	const bundle = buildBundle({ systemCerts, userPems });
+	const base = {
+		path: managedPath,
+		systemCertCount: systemCerts.length,
+		userCertCount: countCerts(userPems),
+	};
+
+	// Skip the rewrite when the bundle is already current. Avoids per-launch I/O
+	// and the concurrent-rename race in the steady state.
+	if (readFileIfExists(fs, managedPath) === bundle) {
+		env.NODE_EXTRA_CA_CERTS = managedPath;
+		return { ...base, action: "unchanged" };
+	}
+
+	if (writeBundle(fs, managedDir, managedPath, bundle)) {
+		env.NODE_EXTRA_CA_CERTS = managedPath;
+		return { ...base, action: "written" };
+	}
+
+	// Write failed: fall back to a previously-written bundle if one exists.
+	if (readFileIfExists(fs, managedPath)) {
+		env.NODE_EXTRA_CA_CERTS = managedPath;
+		return { ...base, action: "write-failed-reused" };
+	}
+	return { ...base, path: null, action: "write-failed" };
+}
+
+module.exports = {
+	harvestSystemCerts,
+	sanitizePem,
+	readUserBundle,
+	readUserCerts,
+	buildBundle,
+	countCerts,
+	configureNodeExtraCaCerts,
+	shouldWarnApiUnavailable,
+};

apps/cli/bin/cline

@@ -23,6 +23,48 @@ const childEnv = {
 	CLINE_WRAPPER_PATH: scriptPath,
 };
 
+// Auto-discover OS trust anchors and pass them to the Bun child via
+// NODE_EXTRA_CA_CERTS. The Bun runtime does not read the OS store on its own,
+// so corporate/self-signed CAs would otherwise fail. This wrapper runs on
+// Node, which can read the full store here.
+try {
+	const caCerts = require("./ca-certs.cjs");
+	const outcome = caCerts.configureNodeExtraCaCerts(childEnv);
+	const debug =
+		process.env.CLINE_DEBUG === "1" || process.env.CLINE_DEBUG === "true";
+	// Not debug-gated: on old Nodes the harvest silently doing nothing is
+	// indistinguishable from a broken corporate proxy. Stamped per Node
+	// version so the nudge shows once, not on every command.
+	if (
+		outcome &&
+		outcome.action === "api-unavailable" &&
+		!childEnv.NODE_EXTRA_CA_CERTS &&
+		caCerts.shouldWarnApiUnavailable(childEnv)
+	) {
+		console.warn(
+			`[cline] Node ${process.versions.node} cannot read the OS trust store (needs >= 22.15); ` +
+				"corporate or self-signed CAs may fail TLS. Upgrade Node or set NODE_EXTRA_CA_CERTS.",
+		);
+	}
+	if (debug && outcome) {
+		if (outcome.action === "no-system-certs") {
+			console.warn(
+				"[cline] No OS trust anchors found; relying on the runtime's bundled CAs.",
+			);
+		} else if (outcome.action === "write-failed") {
+			console.warn(
+				"[cline] Could not write the managed CA bundle; relying on the runtime's bundled CAs.",
+			);
+		} else {
+			console.warn(
+				`[cline] Trust: ${outcome.systemCertCount} OS + ${outcome.userCertCount} user CAs (${outcome.action}) -> ${outcome.path}`,
+			);
+		}
+	}
+} catch {
+	// Best effort: fall back to the runtime's default trust on any failure.
+}
+
 function run(target) {
 	const result = childProcess.spawnSync(target, process.argv.slice(2), {
 		stdio: "inherit",

apps/cli/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@cline/cli",
 	"displayName": "cline",
-	"version": "3.0.38",
+	"version": "3.0.44",
 	"description": "Autonomous coding agent CLI - capable of creating/editing files, running commands, using the browser, and more",
 	"type": "module",
 	"publishConfig": {

apps/cli/src/bin/ca-certs.test.ts

@@ -0,0 +1,367 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+// The helper ships as CommonJS in the published wrapper package, so it is
+// loaded via require rather than an ESM import.
+const caCerts = require("../../bin/ca-certs.cjs") as {
+	harvestSystemCerts: (tls?: unknown) => string[];
+	readUserBundle: (fs: unknown, p: string | null) => string | null;
+	readUserCerts: (
+		fs: unknown,
+		path: unknown,
+		value: string | null,
+		managedPath: string | null,
+	) => string[];
+	buildBundle: (input: {
+		systemCerts: string[];
+		userPems?: string[];
+	}) => string;
+	countCerts: (pems: string[]) => number;
+	configureNodeExtraCaCerts: (
+		env: Record<string, string>,
+		deps?: { tls?: unknown; fs?: unknown },
+	) => {
+		action: string;
+		path: string | null;
+		systemCertCount: number;
+		userCertCount: number;
+	};
+	shouldWarnApiUnavailable: (
+		env: Record<string, string>,
+		deps?: { fs?: unknown; nodeVersion?: string },
+	) => boolean;
+};
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const certSystem =
+	"-----BEGIN CERTIFICATE-----\nSYSTEM\n-----END CERTIFICATE-----\n";
+const certUser = "-----BEGIN CERTIFICATE-----\nUSER\n-----END CERTIFICATE-----";
+
+function fakeTls(certs: unknown) {
+	return { getCACertificates: () => certs };
+}
+
+describe("ca-certs", () => {
+	let dir: string;
+
+	beforeEach(() => {
+		dir = mkdtempSync(join(tmpdir(), "cline-ca-"));
+	});
+
+	afterEach(() => {
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	describe("harvestSystemCerts", () => {
+		it("returns only PEM strings from the system store", () => {
+			expect(
+				caCerts.harvestSystemCerts(fakeTls([certSystem, "not-a-cert", 42])),
+			).toEqual([certSystem]);
+		});
+
+		it("returns [] when getCACertificates is unavailable", () => {
+			expect(caCerts.harvestSystemCerts({})).toEqual([]);
+		});
+
+		it("returns [] when getCACertificates throws", () => {
+			expect(
+				caCerts.harvestSystemCerts({
+					getCACertificates: () => {
+						throw new Error("nope");
+					},
+				}),
+			).toEqual([]);
+		});
+	});
+
+	describe("readUserBundle", () => {
+		it("returns PEM contents for a PEM file", () => {
+			const p = join(dir, "user.pem");
+			writeFileSync(p, certUser);
+			expect(caCerts.readUserBundle(fs, p)).toBe(certUser);
+		});
+
+		it("returns null for a non-PEM (DER) file", () => {
+			const p = join(dir, "user.der");
+			writeFileSync(p, Buffer.from([0x30, 0x82, 0x01, 0x02]));
+			expect(caCerts.readUserBundle(fs, p)).toBeNull();
+		});
+
+		it("returns null for a missing file and for null path", () => {
+			expect(caCerts.readUserBundle(fs, join(dir, "nope.pem"))).toBeNull();
+			expect(caCerts.readUserBundle(fs, null)).toBeNull();
+		});
+
+		it("strips non-certificate sections such as private keys", () => {
+			// Combined cert+key files (nginx/haproxy style) are common; the key
+			// must never reach the managed bundle.
+			const p = join(dir, "combined.pem");
+			writeFileSync(
+				p,
+				`${certUser}\n-----BEGIN PRIVATE KEY-----\nSECRET\n-----END PRIVATE KEY-----\n`,
+			);
+			const out = caCerts.readUserBundle(fs, p);
+			expect(out).toContain("USER");
+			expect(out).not.toContain("PRIVATE KEY");
+			expect(out).not.toContain("SECRET");
+		});
+
+		it("keeps certificates-only files verbatim", () => {
+			// Byte-identical passthrough keeps the unchanged-skip hash stable.
+			const p = join(dir, "clean.pem");
+			writeFileSync(p, `${certUser}\n${certSystem}`);
+			expect(caCerts.readUserBundle(fs, p)).toBe(`${certUser}\n${certSystem}`);
+		});
+
+		it("returns null for a BEGIN marker without a complete block", () => {
+			const p = join(dir, "truncated.pem");
+			writeFileSync(p, "-----BEGIN CERTIFICATE-----\ntruncated");
+			expect(caCerts.readUserBundle(fs, p)).toBeNull();
+		});
+	});
+
+	describe("readUserCerts", () => {
+		it("reads a single PEM file path", () => {
+			const p = join(dir, "corp.pem");
+			writeFileSync(p, certUser);
+			expect(caCerts.readUserCerts(fs, path, p, null)).toEqual([certUser]);
+		});
+
+		it("splits a legacy OS-path-delimited value and reads each PEM", () => {
+			// Legacy footgun: NODE_EXTRA_CA_CERTS="a.pem;b.pem".
+			const a = join(dir, "a.pem");
+			const b = join(dir, "b.pem");
+			writeFileSync(a, certUser);
+			writeFileSync(b, certSystem);
+			expect(
+				caCerts.readUserCerts(fs, path, [a, b].join(delimiter), null),
+			).toEqual([certUser, certSystem]);
+		});
+
+		it("skips missing segments in a delimited value", () => {
+			const a = join(dir, "a.pem");
+			writeFileSync(a, certUser);
+			const value = [a, join(dir, "missing.pem")].join(delimiter);
+			expect(caCerts.readUserCerts(fs, path, value, null)).toEqual([certUser]);
+		});
+
+		it("excludes the managed bundle from user certs", () => {
+			const managed = join(dir, "cli-node-extra-ca-certs.pem");
+			writeFileSync(managed, certUser);
+			expect(caCerts.readUserCerts(fs, path, managed, managed)).toEqual([]);
+		});
+
+		it("returns [] for empty value", () => {
+			expect(caCerts.readUserCerts(fs, path, null, null)).toEqual([]);
+		});
+	});
+
+	describe("buildBundle", () => {
+		it("merges user PEMs before system certs", () => {
+			expect(
+				caCerts.buildBundle({
+					systemCerts: [certSystem],
+					userPems: [certUser],
+				}),
+			).toBe(`${certUser}\n${certSystem}`);
+		});
+
+		it("inserts a separating newline so END/BEGIN markers do not fuse", () => {
+			// certUser has no trailing newline, so this proves the boundary fix.
+			const merged = caCerts.buildBundle({
+				systemCerts: [certSystem],
+				userPems: [certUser],
+			});
+			expect(merged).not.toContain(
+				"-----END CERTIFICATE----------BEGIN CERTIFICATE-----",
+			);
+		});
+
+		it("handles no user PEMs", () => {
+			expect(caCerts.buildBundle({ systemCerts: [certSystem] })).toBe(
+				certSystem,
+			);
+		});
+	});
+
+	describe("configureNodeExtraCaCerts", () => {
+		it("writes a managed bundle and points the env var at it", () => {
+			const env: Record<string, string> = { CLINE_DIR: dir };
+			const out = caCerts.configureNodeExtraCaCerts(env, {
+				tls: fakeTls([certSystem]),
+			});
+			expect(out.action).toBe("written");
+			expect(out.path).toBe(join(dir, "cli-node-extra-ca-certs.pem"));
+			expect(env.NODE_EXTRA_CA_CERTS).toBe(out.path);
+			expect(readFileSync(out.path as string, "utf8")).toContain("SYSTEM");
+		});
+
+		it("merges a user-supplied NODE_EXTRA_CA_CERTS with system certs", () => {
+			const userPath = join(dir, "corp.pem");
+			writeFileSync(userPath, certUser);
+			const env: Record<string, string> = {
+				CLINE_DIR: dir,
+				NODE_EXTRA_CA_CERTS: userPath,
+			};
+			const out = caCerts.configureNodeExtraCaCerts(env, {
+				tls: fakeTls([certSystem]),
+			});
+			expect(out.userCertCount).toBe(1);
+			const written = readFileSync(env.NODE_EXTRA_CA_CERTS, "utf8");
+			expect(written).toContain("USER");
+			expect(written).toContain("SYSTEM");
+		});
+
+		it("reports unchanged and skips rewrite on the second run", () => {
+			const env: Record<string, string> = { CLINE_DIR: dir };
+			expect(
+				caCerts.configureNodeExtraCaCerts(env, { tls: fakeTls([certSystem]) })
+					.action,
+			).toBe("written");
+			expect(
+				caCerts.configureNodeExtraCaCerts(env, { tls: fakeTls([certSystem]) })
+					.action,
+			).toBe("unchanged");
+		});
+
+		it("does not re-append when the user already points at the managed bundle", () => {
+			const env: Record<string, string> = { CLINE_DIR: dir };
+			const first = caCerts.configureNodeExtraCaCerts(env, {
+				tls: fakeTls([certSystem]),
+			}).path as string;
+			const env2: Record<string, string> = {
+				CLINE_DIR: dir,
+				NODE_EXTRA_CA_CERTS: first,
+			};
+			caCerts.configureNodeExtraCaCerts(env2, { tls: fakeTls([certSystem]) });
+			const written = readFileSync(env2.NODE_EXTRA_CA_CERTS, "utf8");
+			expect(written.match(/SYSTEM/g)?.length).toBe(1);
+		});
+
+		it("no-ops when no system certs are available", () => {
+			const env: Record<string, string> = {
+				CLINE_DIR: dir,
+				NODE_EXTRA_CA_CERTS: "/user/corp.pem",
+			};
+			const out = caCerts.configureNodeExtraCaCerts(env, { tls: fakeTls([]) });
+			expect(out.action).toBe("no-system-certs");
+			expect(out.path).toBeNull();
+			expect(env.NODE_EXTRA_CA_CERTS).toBe("/user/corp.pem");
+		});
+
+		it("reports api-unavailable on Nodes without getCACertificates", () => {
+			const env: Record<string, string> = {
+				CLINE_DIR: dir,
+				NODE_EXTRA_CA_CERTS: "/user/corp.pem",
+			};
+			const out = caCerts.configureNodeExtraCaCerts(env, { tls: {} });
+			expect(out.action).toBe("api-unavailable");
+			expect(out.path).toBeNull();
+			expect(env.NODE_EXTRA_CA_CERTS).toBe("/user/corp.pem");
+		});
+
+		it("reports write-failed when the bundle cannot be written", () => {
+			const realFs = require("node:fs");
+			const failingFs = {
+				...realFs,
+				mkdirSync: () => {
+					throw new Error("EACCES");
+				},
+				writeFileSync: () => {
+					throw new Error("EACCES");
+				},
+			};
+			const env: Record<string, string> = { CLINE_DIR: dir };
+			const out = caCerts.configureNodeExtraCaCerts(env, {
+				tls: fakeTls([certSystem]),
+				fs: failingFs,
+			});
+			expect(out.action).toBe("write-failed");
+			expect(out.path).toBeNull();
+			expect(env.NODE_EXTRA_CA_CERTS).toBeUndefined();
+		});
+
+		it("reuses a stale bundle when the rewrite fails", () => {
+			// First run writes the bundle normally.
+			const env: Record<string, string> = { CLINE_DIR: dir };
+			const managedPath = caCerts.configureNodeExtraCaCerts(env, {
+				tls: fakeTls([certSystem]),
+			}).path as string;
+
+			// Second run: writes fail, but the stale bundle is still readable.
+			const realFs = require("node:fs");
+			const failingFs = {
+				...realFs,
+				mkdirSync: () => {
+					throw new Error("EACCES");
+				},
+				writeFileSync: () => {
+					throw new Error("EACCES");
+				},
+			};
+			const env2: Record<string, string> = { CLINE_DIR: dir };
+			const out = caCerts.configureNodeExtraCaCerts(env2, {
+				// A different system cert forces a rewrite attempt (not "unchanged").
+				tls: fakeTls([certUser]),
+				fs: failingFs,
+			});
+
+			expect(out.action).toBe("write-failed-reused");
+			expect(env2.NODE_EXTRA_CA_CERTS).toBe(managedPath);
+		});
+	});
+
+	describe("countCerts", () => {
+		it("counts individual certificates, not files", () => {
+			// One file holding two certs must report 2, not 1.
+			const twoInOne = `${certUser}\n${certSystem}`;
+			expect(caCerts.countCerts([twoInOne])).toBe(2);
+			expect(caCerts.countCerts([certUser, certSystem])).toBe(2);
+			expect(caCerts.countCerts([])).toBe(0);
+		});
+	});
+
+	describe("shouldWarnApiUnavailable", () => {
+		it("warns once per Node version, then stays quiet", () => {
+			const env = { CLINE_DIR: dir };
+			const deps = { nodeVersion: "22.1.0" };
+			expect(caCerts.shouldWarnApiUnavailable(env, deps)).toBe(true);
+			expect(caCerts.shouldWarnApiUnavailable(env, deps)).toBe(false);
+		});
+
+		it("re-arms when the Node version changes", () => {
+			const env = { CLINE_DIR: dir };
+			expect(
+				caCerts.shouldWarnApiUnavailable(env, { nodeVersion: "22.1.0" }),
+			).toBe(true);
+			expect(
+				caCerts.shouldWarnApiUnavailable(env, { nodeVersion: "22.14.0" }),
+			).toBe(true);
+			expect(
+				caCerts.shouldWarnApiUnavailable(env, { nodeVersion: "22.1.0" }),
+			).toBe(false);
+		});
+
+		it("still warns when the stamp cannot be written", () => {
+			const realFs = require("node:fs");
+			const failingFs = {
+				...realFs,
+				mkdirSync: () => {
+					throw new Error("EACCES");
+				},
+				writeFileSync: () => {
+					throw new Error("EACCES");
+				},
+			};
+			const env = { CLINE_DIR: dir };
+			const deps = { fs: failingFs, nodeVersion: "22.1.0" };
+			// Bookkeeping failure must never suppress the diagnostic.
+			expect(caCerts.shouldWarnApiUnavailable(env, deps)).toBe(true);
+			expect(caCerts.shouldWarnApiUnavailable(env, deps)).toBe(true);
+		});
+	});
+});

apps/cli/src/commands/config.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, extname, join } from "node:path";
 import {
@@ -15,6 +15,7 @@ import {
 	type SkillConfig,
 	type WorkflowConfig,
 } from "@cline/core";
+import { readFileSyncStrippingUtf8Bom } from "@cline/shared/node";
 import { Command } from "commander";
 import { getToolCatalog } from "../runtime/tools";
 import { loadInteractiveConfigData } from "../tui/interactive-config";
@@ -209,7 +210,7 @@ async function runAgentsConfigCommand(
 					continue;
 				}
 				const filePath = join(directory, entry.name);
-				const raw = readFileSync(filePath, "utf8");
+				const raw = readFileSyncStrippingUtf8Bom(filePath);
 				const frontmatterMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
 				const frontmatter = frontmatterMatch?.[1] ?? "";
 				const nameMatch = frontmatter.match(/^\s*name:\s*(.+?)\s*$/m);

apps/cli/src/commands/update.test.ts

@@ -101,6 +101,22 @@ describe("getInstallationInfo", () => {
 		});
 	});
 
+	it("detects bun global installs from the resolved install path", () => {
+		// bun symlinks ~/.bun/bin/cline -> ~/.bun/install/global/node_modules/...,
+		// and realpathSync resolves through the symlink before detection runs.
+		const wrapperPath = createTempFile(
+			".bun/install/global/node_modules/cline/bin/cline",
+		);
+		process.env.CLINE_WRAPPER_PATH = wrapperPath;
+		process.argv = ["bun", "/$bunfs/root/cline", "update", "--verbose"];
+
+		expect(getInstallationInfo("1.2.3")).toEqual({
+			packageManager: PackageManager.BUN,
+			packageName: "cline",
+			updateCommand: "bun add -g cline@latest",
+		});
+	});
+
 	it("falls back to unknown when only Bun's virtual compiled path is available", () => {
 		delete process.env.CLINE_WRAPPER_PATH;
 		process.argv = ["bun", "/$bunfs/root/cline", "update", "--verbose"];

apps/cli/src/commands/update.ts

@@ -118,7 +118,12 @@ export function getInstallationInfo(currentVersion: string): InstallationInfo {
 				updateCommand: `yarn global add ${DEFAULT_PACKAGE_NAME}@${tag}`,
 			};
 		}
-		if (scriptPath.includes("/.bun/bin")) {
+		// `bun add -g` symlinks bins into ~/.bun/bin, but realpathSync resolves
+		// them to ~/.bun/install/global/node_modules/..., so match both.
+		if (
+			scriptPath.includes("/.bun/bin") ||
+			scriptPath.includes("/.bun/install/global/")
+		) {
 			return {
 				packageManager: PackageManager.BUN,
 				packageName: DEFAULT_PACKAGE_NAME,

apps/cli/src/main.test.ts

@@ -158,8 +158,9 @@ vi.mock("./runtime/run-interactive", () => {
 });
 vi.mock("./utils/session", () => sessionMocks);
 vi.mock("./session/session", () => sessionMocks);
-vi.mock("@cline/core", () => {
+vi.mock("@cline/core", async () => {
 	return {
+		...(await vi.importActual("@cline/core")),
 		resolveProviderConfig: llmMocks.resolveProviderConfig,
 		createTeamName: vi.fn(() => "team-test"),
 		createUserInstructionConfigService: vi.fn(() => ({

apps/cli/src/main.ts

@@ -928,6 +928,17 @@ export async function runCli(): Promise<void> {
 		runAgent,
 	} = await loadCliRuntimeModules();
 
+	// Register the SDK early logger as early as possible — before any
+	// provider settings reads — so the full startup sequence is captured.
+	// These components operate before/outside ClineCore sessions, so the
+	// session-scoped logger can't reach them.
+	const { createCliLoggerAdapter } = await import("./logging/adapter");
+	const loggerAdapter = createCliLoggerAdapter({
+		runtime: "cli",
+		component: "main",
+	});
+	coreServer.setSdkLogger(loggerAdapter.core);
+
 	const userInstructionService = createUserInstructionConfigService({
 		skills: {
 			workspacePath: workspaceRoot,
@@ -971,9 +982,15 @@ export async function runCli(): Promise<void> {
 		// and cannot be retroactively updated; this is by design for
 		// lightweight subcommand and pre-auth CLI flows. See CLINE-2406.
 		if (provider === "cline") {
-			const savedAccountId = selectedProviderSettings?.auth?.accountId;
-			if (savedAccountId) {
-				identifyTelemetryAccount({ id: savedAccountId, provider: "cline" });
+			const savedAuth = selectedProviderSettings?.auth;
+			if (savedAuth?.accountId) {
+				identifyTelemetryAccount({
+					id: savedAuth.accountId,
+					provider: "cline",
+					organizationId: savedAuth.organizationId,
+					organizationName: savedAuth.organizationName,
+					memberId: savedAuth.memberId,
+				});
 			}
 		}
 

apps/cli/src/runtime/interactive/compaction.test.ts

@@ -106,7 +106,7 @@ describe("compactInteractiveMessages", () => {
 		}));
 		const config = createConfig();
 		const compact = vi.fn((context: CoreCompactionContext) => {
-			expect(context.maxInputTokens).toBe(400_000);
+			expect(context.budget.request.maxInputTokens).toBe(400_000);
 			return { messages: [messages[0]] };
 		});
 		config.knownModels = {
@@ -130,7 +130,7 @@ describe("compactInteractiveMessages", () => {
 		expect(result.compactionState?.messages).toEqual([messages[0]]);
 	});
 
-	it("falls back to legacy contextWindow for manual compaction", async () => {
+	it("uses 90 percent of legacy contextWindow for manual compaction", async () => {
 		const longText = "x".repeat(16_000);
 		const messages = Array.from({ length: 10 }, (_, index) => ({
 			role: index % 2 === 0 ? ("user" as const) : ("assistant" as const),
@@ -138,7 +138,7 @@ describe("compactInteractiveMessages", () => {
 		}));
 		const config = createConfig();
 		const compact = vi.fn((context: CoreCompactionContext) => {
-			expect(context.maxInputTokens).toBe(400_000);
+			expect(context.budget.request.maxInputTokens).toBe(360_000);
 			return { messages: [messages[0]] };
 		});
 		config.knownModels = {

apps/cli/src/runtime/interactive/compaction.ts

@@ -61,11 +61,15 @@ export async function compactInteractiveMessages(input: {
 	compactionState?: SessionCompactionState;
 }> {
 	const modelInfo = input.config.knownModels?.[input.config.modelId];
-	const maxInputTokens =
-		input.config.compaction?.maxInputTokens ??
-		modelInfo?.maxInputTokens ??
-		modelInfo?.contextWindow ??
-		FALLBACK_MANUAL_COMPACTION_MAX_INPUT_TOKENS;
+	const compactionModelInfo = modelInfo
+		? {
+				...modelInfo,
+				id: modelInfo.id ?? input.config.modelId,
+			}
+		: {
+				id: input.config.modelId,
+				maxInputTokens: FALLBACK_MANUAL_COMPACTION_MAX_INPUT_TOKENS,
+			};
 	const compact = createContextCompactionPrepareTurn(
 		{
 			providerConfig: resolveCompactionProviderConfig(
@@ -106,11 +110,7 @@ export async function compactInteractiveMessages(input: {
 		model: {
 			id: input.config.modelId,
 			provider: input.config.providerId,
-			info: {
-				...(modelInfo ?? {}),
-				id: modelInfo?.id ?? input.config.modelId,
-				maxInputTokens: maxInputTokens,
-			},
+			info: compactionModelInfo,
 		},
 	});
 	if (!result?.messages) {

apps/cli/src/runtime/interactive/mode.ts

@@ -107,38 +107,13 @@ export async function sendTurnWithActModeContinuation<
 	};
 }
 
-export type ModeSwitchNotice = {
-	from: InteractiveUiMode;
-	to: InteractiveUiMode;
-};
-
-/**
- * Tracks a user-initiated mode switch so the next user message can carry a
- * <mode_notice> marking it. Only UI toggles are recorded: the model-initiated
- * switch_to_act_mode path already announces itself via the continuation
- * prompt. A round trip (plan -> act -> plan before sending anything) cancels
- * out, since the mode the model last saw never effectively changed.
- */
-export function createModeSwitchNoticeTracker() {
-	let pending: ModeSwitchNotice | null = null;
-	return {
-		record(from: InteractiveUiMode, to: InteractiveUiMode): void {
-			if (from === to) {
-				return;
-			}
-			if (pending) {
-				pending = pending.from === to ? null : { from: pending.from, to };
-				return;
-			}
-			pending = { from, to };
-		},
-		consume(): ModeSwitchNotice | null {
-			const notice = pending;
-			pending = null;
-			return notice;
-		},
-	};
-}
+// The tracker moved to @cline/shared so the VSCode extension can share the
+// exact round-trip-cancelling semantics; re-exported here to keep the CLI's
+// import surface stable.
+export {
+	createModeSwitchNoticeTracker,
+	type ModeSwitchNotice,
+} from "@cline/shared";
 
 export async function applyInteractiveModeConfig(input: {
 	config: Config;

apps/cli/src/runtime/interactive/session-runtime.test.ts

@@ -157,6 +157,7 @@ function makeManager() {
 		ingestHookEvent: vi.fn(),
 		subscribe: vi.fn(),
 		updateSessionModel: vi.fn(),
+		updateSessionConnection: vi.fn(async () => {}),
 		pendingPrompts: {
 			update: vi.fn(),
 		},
@@ -814,6 +815,83 @@ describe("createInteractiveSessionRuntime", () => {
 		expect(runtime.getActiveSessionId()).toBe("session-2");
 	});
 
+	it("preserves the session id and applies changed provider config when restarting with the current messages", async () => {
+		const manager = makeManager();
+		const config = {
+			...createConfig(),
+			providerId: "cline",
+			modelId: "anthropic/claude-sonnet-4.6",
+			apiKey: "cline-key",
+		};
+		const messages: Message[] = [
+			{ role: "user", content: [{ type: "text", text: "hello" }] },
+		];
+		manager.readMessages.mockResolvedValue(messages);
+		const runtime = await makeRuntime(manager, { config });
+
+		await runtime.ensureReady();
+		expect(manager.start).toHaveBeenNthCalledWith(
+			1,
+			expect.objectContaining({
+				config: expect.objectContaining({
+					providerId: "cline",
+					modelId: "anthropic/claude-sonnet-4.6",
+					apiKey: "cline-key",
+				}),
+			}),
+		);
+		config.providerId = "openai-compatible";
+		config.modelId = "custom-model";
+		config.apiKey = "new-key";
+		await runtime.restartWithCurrentMessages();
+
+		expect(manager.start).toHaveBeenCalledTimes(2);
+		expect(manager.start).toHaveBeenNthCalledWith(
+			2,
+			expect.objectContaining({
+				config: expect.objectContaining({
+					sessionId: "session-1",
+					providerId: "openai-compatible",
+					modelId: "custom-model",
+					apiKey: "new-key",
+				}),
+				initialMessages: messages,
+			}),
+		);
+	});
+
+	it("updates the active session connection in place without restarting", async () => {
+		const manager = makeManager();
+		const runtime = await makeRuntime(manager);
+
+		await runtime.ensureReady();
+		await runtime.updateCurrentSessionConnection({
+			providerId: "openai",
+			modelId: "codex-test",
+		});
+
+		expect(manager.updateSessionConnection).toHaveBeenCalledWith("session-1", {
+			providerId: "openai",
+			modelId: "codex-test",
+		});
+		expect(manager.start).toHaveBeenCalledTimes(1);
+		expect(runtime.getActiveSessionId()).toBe("session-1");
+	});
+
+	it("does not reuse the session id when restarting empty", async () => {
+		const manager = makeManager();
+		const runtime = await makeRuntime(manager);
+
+		await runtime.ensureReady();
+		await runtime.restartEmpty();
+
+		expect(manager.start).toHaveBeenCalledTimes(2);
+		const secondStart = manager.start.mock.calls[1]?.[0] as {
+			config?: { sessionId?: string };
+		};
+		expect(secondStart?.config?.sessionId).toBeUndefined();
+	});
+
 	it("recovers empty read-driven restarts when the active interactive session disappeared", async () => {
 		const manager = makeManager();
 		manager.readMessages.mockRejectedValueOnce(

apps/cli/src/runtime/interactive/session-runtime.ts

@@ -49,6 +49,9 @@ type RuntimeHooks = ReturnType<typeof createRuntimeHooks>;
 type StartedSession = Awaited<ReturnType<CliCore["start"]>>;
 type CurrentTurnInput = Omit<Parameters<CliCore["send"]>[0], "sessionId">;
 type CurrentTurnResult = Awaited<ReturnType<CliCore["send"]>>;
+export type SessionConnectionUpdate = Parameters<
+	CliCore["updateSessionConnection"]
+>[1];
 type AskQuestionRef = {
 	current: ((question: string, options: string[]) => Promise<string>) | null;
 };
@@ -210,12 +213,18 @@ export function createInteractiveSessionRuntime(input: {
 		initial: Message[] = [],
 		sessionMetadata?: Record<string, unknown>,
 		initialCompactionState?: SessionCompactionState,
+		// Restarting an old session associate with this ID,
+		// For continuing the same conversation, e.g. after a config change.
+		sessionId?: string,
 	): Promise<void> => {
 		const generation = sessionStartGeneration;
 		const manager = await ensureSessionManager();
 		const started = await manager.start({
 			source: SessionSource.CLI,
-			config: buildSessionConfig(),
+			config: {
+				...buildSessionConfig(),
+				...(sessionId ? { sessionId } : {}),
+			},
 			toolPolicies: input.config.toolPolicies,
 			interactive: true,
 			initialMessages: initial,
@@ -415,7 +424,14 @@ export function createInteractiveSessionRuntime(input: {
 		messages: Message[],
 		sessionMetadata?: Record<string, unknown>,
 		initialCompactionState?: SessionCompactionState,
+		options?: { preserveSessionId?: boolean },
 	): Promise<void> => {
+		// Config-only restarts (model/mode/account changes) continue the same
+		// conversation, so they must keep the session id — otherwise each
+		// restart mints a new session history entry for the same conversation.
+		const reuseSessionId = options?.preserveSessionId
+			? activeSessionId || undefined
+			: undefined;
 		sessionStartGeneration += 1;
 		pendingResumeSessionId = undefined;
 		startupError = undefined;
@@ -431,6 +447,7 @@ export function createInteractiveSessionRuntime(input: {
 				messages,
 				sessionMetadata,
 				initialCompactionState,
+				reuseSessionId,
 			);
 		})().catch((error) => {
 			startupError = error;
@@ -473,9 +490,24 @@ export function createInteractiveSessionRuntime(input: {
 						systemPrompt: compactionState?.system_prompt,
 					})
 				: undefined,
+			{ preserveSessionId: true },
 		);
 	};
 
+	const updateCurrentSessionConnection = async (
+		update: SessionConnectionUpdate,
+	): Promise<void> => {
+		await ensureReady();
+		const manager = sessionManager;
+		const sessionId = activeSessionId;
+		if (!manager || !sessionId) {
+			// No live session to update; the next startup builds its config from
+			// the already-mutated CLI config, so nothing else is needed.
+			return;
+		}
+		await manager.updateSessionConnection(sessionId, update);
+	};
+
 	const restartEmpty = async (): Promise<void> => {
 		await restartWithMessages([]);
 	};
@@ -609,7 +641,22 @@ export function createInteractiveSessionRuntime(input: {
 					})
 				: undefined,
 		);
-		return { forkedFromSessionId, newSessionId: activeSessionId };
+		// Report carried context from what the new session actually accepted:
+		// the host can reject the inherited state (e.g. stale anchor), and the
+		// UI must not claim a carry-over that did not happen.
+		const acceptedState = projectedMessages
+			? await readCompactionState(activeSessionId)
+			: undefined;
+		return {
+			forkedFromSessionId,
+			newSessionId: activeSessionId,
+			carriedWorkingContext: acceptedState
+				? {
+						workingContextMessages: acceptedState.messages.length,
+						canonicalMessages: messages.length,
+					}
+				: undefined,
+		};
 	};
 
 	const resumeSession = async (sessionId: string): Promise<Message[]> => {
@@ -840,6 +887,7 @@ export function createInteractiveSessionRuntime(input: {
 		resetForNewSession,
 		restartWithMessages,
 		restartWithCurrentMessages,
+		updateCurrentSessionConnection,
 		resumeSession,
 		forkCurrentSession,
 		compactCurrentSession,

apps/cli/src/runtime/prompt.ts

@@ -9,23 +9,6 @@ import {
 import { type AgentMode, buildClineSystemPrompt } from "@cline/shared";
 import { isImagePath, loadImageAsDataUrl } from "../utils/image-attachments";
 
-const MODE_TAG_INSTRUCTIONS = `# Plan / Act Modes
-
-User messages arrive wrapped in a <user_input mode="..."> tag. The mode attribute is the interaction mode the user was in when they sent that message: "plan" means plan-mode constraints applied (explore, analyze, and align on a plan -- no edits or state-changing commands), while "act" (or "yolo") means implementation was allowed. If the mode attribute changes between messages, the user switched modes -- the newest message's mode is what governs right now, regardless of what earlier messages allowed. A <mode_notice> block inside a message marks exactly when such a switch happened.`;
-
-const PLAN_MODE_INSTRUCTIONS = `# Plan Mode
-
-You are in Plan mode. Your role is to explore, analyze, and plan -- not to execute.
-
-- Read files, search the codebase, and gather context to understand the problem
-- Ask clarifying questions when requirements are ambiguous
-- Present your plan as a structured outline with clear steps
-- Explain tradeoffs between different approaches when they exist
-- Do NOT edit files, write code, run destructive commands, or make any changes
-- Do NOT implement anything -- focus on understanding and alignment first
-
-Once the user has reviewed your plan and explicitly approved it in a follow-up message, use the switch_to_act_mode tool to switch to act mode and begin implementation. Calling switch_to_act_mode immediately starts execution, so never call it in the same turn you present a plan and never treat the original task request as approval -- end your turn after presenting the plan and wait for the user's response.`;
-
 export async function resolveSystemPrompt(input: {
 	cwd: string;
 	explicitSystemPrompt?: string;
@@ -34,15 +17,10 @@ export async function resolveSystemPrompt(input: {
 	mode?: AgentMode;
 }): Promise<string> {
 	const metadata = await buildWorkspaceMetadata(input.cwd);
-	let rules = mergeRulesForSystemPrompt(undefined, input.rules);
-	// Both modes get the mode-tag explanation: after a switch, the transcript
-	// still contains messages tagged with the other mode.
-	rules = rules
-		? `${rules}\n\n${MODE_TAG_INSTRUCTIONS}`
-		: MODE_TAG_INSTRUCTIONS;
-	if (input.mode === "plan") {
-		rules = `${rules}\n\n${PLAN_MODE_INSTRUCTIONS}`;
-	}
+	// Mode-tag and plan-mode instructions are appended by the shared prompt
+	// builder itself (see MODE_TAG_INSTRUCTIONS / PLAN_MODE_INSTRUCTIONS in
+	// @cline/shared), so only the caller-specific rules are merged here.
+	const rules = mergeRulesForSystemPrompt(undefined, input.rules);
 	return buildClineSystemPrompt({
 		ide: "Terminal Shell",
 		workspaceRoot: input.cwd,

apps/cli/src/runtime/run-agent.test.ts

@@ -43,6 +43,15 @@ const CLI_SUBSCRIPTION_URL =
 	"https://app.cline.bot/promo?code=CLI-8OFF&personal=true";
 const SDK_CLINE_PASS_SUBSCRIPTION_MESSAGE = `No access to ClinePass subscription models yet. Subscribe to ClinePass, the low cost open weights model coding plan: ${CLINE_PASS_SUBSCRIPTION_URL}`;
 const CLI_CLINE_PASS_SUBSCRIPTION_MESSAGE = `No access to ClinePass subscription models yet. Subscribe to ClinePass, the low cost open weights model coding plan: ${CLI_SUBSCRIPTION_URL}`;
+const CLINE_PASS_LIMIT_DETAIL_MESSAGE =
+	"You have reached your 5-hour Clinepass limit. The limit resets in 5h, please try again later.";
+const CLI_CLINE_PASS_LIMIT_MESSAGE = [
+	"ClinePass limit reached",
+	CLINE_PASS_LIMIT_DETAIL_MESSAGE,
+	"Switch to Cline usage-based billing and retry with the Cline provider.",
+	"Interactive CLI: open the model selector with /model, choose Cline, then retry.",
+	"Headless CLI: rerun with --provider cline.",
+].join("\n");
 const CLINE_ORG_INDIVIDUAL_INFERENCE_SUBSCRIPTION_MESSAGE =
 	"Organization accounts cannot use ClinePass subscriptions. Go to /account -> change account to switch to your personal account for ClinePass";
 
@@ -65,6 +74,30 @@ vi.mock("@cline/core", () => ({
 			.includes(
 				"organization accounts cannot use individual model inference subscriptions",
 			),
+	isClinePassLimitError: (error: unknown) =>
+		error instanceof Error && error.name === "ClinePassLimitError",
+	extractClinePassLimitMessage: (text: string) => {
+		const normalized = text.toLowerCase();
+		const prefix = "you have reached your";
+		const suffix = "please try again later.";
+		const start = normalized.indexOf(prefix);
+		if (start === -1) return undefined;
+		const suffixStart = normalized.indexOf(suffix, start);
+		if (suffixStart === -1) return undefined;
+		const end = suffixStart + suffix.length;
+		if (!normalized.slice(start, end).includes("clinepass limit")) {
+			return undefined;
+		}
+		return text.slice(start, end);
+	},
+	isClinePassLimitMessage: (text: string) => {
+		const normalized = text.toLowerCase();
+		return (
+			normalized.includes("you have reached your") &&
+			normalized.includes("clinepass limit") &&
+			normalized.includes("please try again later.")
+		);
+	},
 	prewarmFileIndex: vi.fn(async () => undefined),
 	SessionSource: {
 		CLI: "cli",
@@ -769,6 +802,126 @@ describe("runAgent", () => {
 		expect(outputMocks.writeErr).not.toHaveBeenCalled();
 	});
 
+	it("formats ClinePass limit errors with usage-based billing guidance", async () => {
+		const startedAt = new Date("2026-03-22T00:00:00.000Z");
+		const endedAt = new Date("2026-03-22T00:00:01.000Z");
+		sessionManagerMocks.start.mockResolvedValue({
+			sessionId: "session-1",
+			manifestPath: "/tmp/manifest.json",
+			messagesPath: "/tmp/messages.json",
+			manifest: { session_id: "session-1" },
+			result: {
+				text: `Error: ${CLINE_PASS_LIMIT_DETAIL_MESSAGE}`,
+				usage: {
+					inputTokens: 0,
+					outputTokens: 0,
+					cacheReadTokens: 0,
+					cacheWriteTokens: 0,
+					totalCost: 0,
+				},
+				messages: [],
+				toolCalls: [],
+				iterations: 1,
+				finishReason: "error",
+				model: { id: "premium-model", provider: "cline-pass", info: {} },
+				startedAt,
+				endedAt,
+				durationMs: 1000,
+			},
+		});
+		sessionManagerMocks.getAccumulatedUsage.mockResolvedValue(undefined);
+
+		const { runAgent } = await import("./run-agent");
+
+		await expect(
+			runAgent("test prompt", {
+				cwd: process.cwd(),
+				enableAgentTeams: false,
+				enableSpawnAgent: false,
+				enableTools: [],
+				execution: { maxConsecutiveMistakes: 3 },
+				logger: undefined,
+				mode: "yolo",
+				modelId: "premium-model",
+				outputMode: "text",
+				providerId: "cline-pass",
+				systemPrompt: "system",
+				thinking: false,
+				toolPolicies: { "*": { autoApprove: true } },
+				verbose: false,
+				workspaceRoot: process.cwd(),
+			} as never),
+		).resolves.toBeUndefined();
+
+		expect(process.exitCode).toBe(1);
+		expect(outputMocks.writeErr).toHaveBeenCalledWith(
+			CLI_CLINE_PASS_LIMIT_MESSAGE,
+		);
+	});
+
+	it("does not duplicate ClinePass limit errors already displayed by agent events", async () => {
+		const startedAt = new Date("2026-03-22T00:00:00.000Z");
+		const endedAt = new Date("2026-03-22T00:00:01.000Z");
+		sessionManagerMocks.start.mockImplementation(async () => {
+			sessionEventsMocks.listener?.({
+				type: "error",
+				error: new Error(`Error: ${CLINE_PASS_LIMIT_DETAIL_MESSAGE}`),
+				recoverable: false,
+			});
+
+			return {
+				sessionId: "session-1",
+				manifestPath: "/tmp/manifest.json",
+				messagesPath: "/tmp/messages.json",
+				manifest: { session_id: "session-1" },
+				result: {
+					text: `Error: ${CLINE_PASS_LIMIT_DETAIL_MESSAGE}`,
+					usage: {
+						inputTokens: 0,
+						outputTokens: 0,
+						cacheReadTokens: 0,
+						cacheWriteTokens: 0,
+						totalCost: 0,
+					},
+					messages: [],
+					toolCalls: [],
+					iterations: 1,
+					finishReason: "error",
+					model: { id: "premium-model", provider: "cline-pass", info: {} },
+					startedAt,
+					endedAt,
+					durationMs: 1000,
+				},
+			};
+		});
+		sessionManagerMocks.getAccumulatedUsage.mockResolvedValue(undefined);
+
+		const { runAgent } = await import("./run-agent");
+
+		await expect(
+			runAgent("test prompt", {
+				cwd: process.cwd(),
+				enableAgentTeams: false,
+				enableSpawnAgent: false,
+				enableTools: [],
+				execution: { maxConsecutiveMistakes: 3 },
+				logger: undefined,
+				mode: "yolo",
+				modelId: "premium-model",
+				outputMode: "text",
+				providerId: "cline-pass",
+				systemPrompt: "system",
+				thinking: false,
+				toolPolicies: { "*": { autoApprove: true } },
+				verbose: false,
+				workspaceRoot: process.cwd(),
+			} as never),
+		).resolves.toBeUndefined();
+
+		expect(process.exitCode).toBe(1);
+		expect(outputMocks.writeErr).not.toHaveBeenCalled();
+	});
+
 	it("surfaces post-run bookkeeping failures after a completed result", async () => {
 		const startedAt = new Date("2026-03-22T00:00:00.000Z");
 		const endedAt = new Date("2026-03-22T00:00:01.000Z");

apps/cli/src/runtime/run-interactive.test.ts

@@ -1,5 +1,9 @@
-import { describe, expect, it } from "vitest";
-import { resolveReasoningForModelChange } from "./run-interactive";
+import { describe, expect, it, vi } from "vitest";
+import type { Config } from "../utils/types";
+import {
+	applyInteractiveModelChange,
+	resolveReasoningForModelChange,
+} from "./run-interactive";
 
 describe("resolveReasoningForModelChange", () => {
 	it("persists disabled reasoning only when thinking is explicitly false", () => {
@@ -38,3 +42,69 @@ describe("resolveReasoningForModelChange", () => {
 		).toEqual({ enabled: true, effort: "medium" });
 	});
 });
+
+describe("applyInteractiveModelChange", () => {
+	it("restarts with the current transcript so a provider switch reloads its complete configuration", async () => {
+		const config = {
+			providerId: "openai-compatible",
+			modelId: "custom-model",
+			apiKey: "new-key",
+			thinking: undefined,
+			reasoningEffort: undefined,
+		} as Config;
+		const getProviderSettings = vi.fn(() => ({
+			provider: "openai-compatible",
+			apiKey: "new-key",
+			baseUrl: "https://example.com/v1",
+			headers: { "X-Custom-Header": "custom-value" },
+			client: "openai-compatible" as const,
+			protocol: "openai-chat" as const,
+			model: "old-model",
+		}));
+		const saveProviderSettings = vi.fn(() => ({
+			version: 1 as const,
+			providers: {},
+		}));
+		const ensureReady = vi.fn(async () => {});
+		const restartWithCurrentMessages = vi.fn(async () => {});
+		const updateCurrentSessionConnection = vi.fn(async () => {});
+
+		await applyInteractiveModelChange({
+			config,
+			providerSettingsManager: {
+				getProviderSettings,
+				saveProviderSettings,
+			},
+			sessionRuntime: {
+				ensureReady,
+				restartWithCurrentMessages,
+				updateCurrentSessionConnection,
+			},
+		});
+
+		expect(saveProviderSettings).toHaveBeenCalledWith({
+			provider: "openai-compatible",
+			apiKey: "new-key",
+			baseUrl: "https://example.com/v1",
+			headers: { "X-Custom-Header": "custom-value" },
+			client: "openai-compatible",
+			protocol: "openai-chat",
+			model: "custom-model",
+		});
+		expect(ensureReady).toHaveBeenCalledOnce();
+		expect(restartWithCurrentMessages).toHaveBeenCalledOnce();
+		expect(updateCurrentSessionConnection).toHaveBeenCalledWith({
+			providerId: "openai-compatible",
+			modelId: "custom-model",
+		});
+		expect(ensureReady.mock.invocationCallOrder[0]).toBeLessThan(
+			restartWithCurrentMessages.mock.invocationCallOrder[0] ?? 0,
+		);
+		expect(saveProviderSettings.mock.invocationCallOrder[0]).toBeLessThan(
+			restartWithCurrentMessages.mock.invocationCallOrder[0] ?? 0,
+		);
+		expect(restartWithCurrentMessages.mock.invocationCallOrder[0]).toBeLessThan(
+			updateCurrentSessionConnection.mock.invocationCallOrder[0] ?? 0,
+		);
+	});
+});

apps/cli/src/runtime/run-interactive.ts

@@ -82,6 +82,51 @@ export function resolveReasoningForModelChange(
 	return existing.reasoning;
 }
 
+export async function applyInteractiveModelChange(input: {
+	config: Config;
+	providerSettingsManager: Pick<
+		ProviderSettingsManager,
+		"getProviderSettings" | "saveProviderSettings"
+	>;
+	sessionRuntime: Pick<
+		ReturnType<typeof createInteractiveSessionRuntime>,
+		| "ensureReady"
+		| "restartWithCurrentMessages"
+		| "updateCurrentSessionConnection"
+	>;
+}): Promise<void> {
+	const { config, providerSettingsManager, sessionRuntime } = input;
+	await sessionRuntime.ensureReady();
+	await onProviderChange({
+		config,
+		providerId: config.providerId,
+	});
+	const existing = providerSettingsManager.getProviderSettings(
+		config.providerId,
+	) ?? {
+		provider: config.providerId,
+	};
+	const reasoning = resolveReasoningForModelChange(config, existing);
+	providerSettingsManager.saveProviderSettings({
+		...existing,
+		model: config.modelId,
+		...(reasoning === undefined ? {} : { reasoning }),
+	});
+
+	// Provider changes affect more than the model connection: startup resolves
+	// the endpoint, headers, provider-specific options, tools, and plugins. Rebuild
+	// the runtime with the existing transcript so all of that state changes
+	// together. restartWithCurrentMessages preserves the session ID.
+	await sessionRuntime.restartWithCurrentMessages();
+	// A same-ID restart reuses the existing manifest. Sync its connection label
+	// after the fully configured runtime is live so session history reflects the
+	// provider/model that will handle subsequent turns.
+	await sessionRuntime.updateCurrentSessionConnection({
+		providerId: config.providerId,
+		modelId: config.modelId,
+	});
+}
+
 export async function runInteractive(
 	config: Config,
 	userInstructionService?: UserInstructionConfigService,
@@ -687,25 +732,12 @@ export async function runInteractive(
 		onNewSession: async () => {
 			await sessionRuntime.resetForNewSession();
 		},
-		onModelChange: async () => {
-			await sessionRuntime.ensureReady();
-			await onProviderChange({
+		onModelChange: () =>
+			applyInteractiveModelChange({
 				config,
-				providerId: config.providerId,
-			});
-			const existing = providerSettingsManager.getProviderSettings(
-				config.providerId,
-			) ?? {
-				provider: config.providerId,
-			};
-			const reasoning = resolveReasoningForModelChange(config, existing);
-			providerSettingsManager.saveProviderSettings({
-				...existing,
-				model: config.modelId,
-				...(reasoning === undefined ? {} : { reasoning }),
-			});
-			await sessionRuntime.restartWithCurrentMessages();
-		},
+				providerSettingsManager,
+				sessionRuntime,
+			}),
 		onSessionRestart: async () => {
 			await sessionRuntime.ensureReady();
 			await sessionRuntime.restartEmpty();

apps/cli/src/tui/cline-account.ts

@@ -151,6 +151,38 @@ export async function createClineAccountService(input: {
 	});
 }
 
+/**
+ * Persist the active organization so headless runs and the hub daemon can
+ * attach it to telemetry identity. Personal account clears stale org fields.
+ */
+function persistClineOrganizationContext(
+	activeOrganization: ClineAccountOrganization | null,
+	userId: string,
+): void {
+	try {
+		const manager = new ProviderSettingsManager();
+		const persisted = manager.getProviderSettings("cline");
+		if (!persisted) {
+			return;
+		}
+		manager.saveProviderSettings(
+			{
+				...persisted,
+				auth: {
+					...persisted.auth,
+					accountId: persisted.auth?.accountId ?? userId,
+					organizationId: activeOrganization?.organizationId,
+					organizationName: activeOrganization?.name,
+					memberId: activeOrganization?.memberId,
+				},
+			},
+			{ setLastUsed: false },
+		);
+	} catch {
+		// Best-effort only.
+	}
+}
+
 export async function loadClineAccountSnapshot(input: {
 	config: ClineAccountConfig;
 	clineApiBaseUrl?: string;
@@ -183,6 +215,7 @@ export async function loadClineAccountSnapshot(input: {
 		memberId: activeOrganization?.memberId,
 	};
 	identifyTelemetryAccount(accountContext, input.config.logger);
+	persistClineOrganizationContext(activeOrganization, user.id);
 
 	return {
 		user,

apps/cli/src/tui/components/chat-entry.tsx

@@ -5,9 +5,11 @@ import { useEffect, useState } from "react";
 import "opentui-spinner/react";
 import {
 	getClineOrgIndividualInferenceSubscriptionMessage,
+	getClinePassLimitDetailMessage,
 	getCliSubscriptionUrl,
 	getIndividualPlanFeatures,
 	isClineOrgIndividualInferenceSubscriptionErrorMessage,
+	isClinePassLimitErrorMessage,
 	isClinePassSubscriptionError,
 } from "../../utils/cline-pass-errors";
 import {
@@ -23,6 +25,7 @@ import {
 	type TerminalTheme,
 } from "../palette";
 import type { ChatEntry } from "../types";
+import { formatCompactionDividerLabel } from "../utils/compaction-status";
 import { getSyntaxStyle, type SyntaxAccentMode } from "../utils/syntax-style";
 import { isWarningToolError } from "../utils/tool-errors";
 import {
@@ -131,7 +134,7 @@ function formatToolParams(
 				const el = f.endLine != null ? String(f.endLine) : "undefined";
 				const sep = i > 0 ? "; " : "";
 				return (
-					<span key={f.path}>
+					<span key={`${i}:${f.path}`}>
 						{sep}
 						{shortenPath(f.path)}
 						<span fg="gray">
@@ -419,6 +422,86 @@ function ClineOrgIndividualInferenceSubscriptionErrorView(props: {
 	);
 }
 
+function CompactionDividerRow(props: {
+	entry: Extract<ChatEntry, { kind: "compaction" }>;
+}) {
+	const { entry } = props;
+	const { width: terminalWidth } = useTerminalDimensions();
+	const inProgress = entry.status === "started";
+	const labelColor = inProgress
+		? "cyan"
+		: entry.status === "failed"
+			? "red"
+			: entry.status === "cancelled" || entry.status === "skipped"
+				? "gray"
+				: "cyan";
+	const label = `✻ ${formatCompactionDividerLabel(entry)} ✻`;
+	// Fill the remaining line with a plain rule instead of a flexGrow bordered
+	// box: a single fixed-content text row keeps the renderer's diffing stable.
+	const ruleWidth = Math.max(2, Math.min(40, terminalWidth - label.length - 8));
+	return (
+		<box flexDirection="row">
+			{inProgress ? (
+				<box width={2}>
+					<spinner name="dots" color={labelColor} />
+				</box>
+			) : (
+				<text fg="gray" content="── " />
+			)}
+			<text fg={labelColor} selectable content={label} />
+			<text fg="gray" content={` ${"─".repeat(ruleWidth)}`} />
+		</box>
+	);
+}
+
+function ClinePassLimitErrorView(props: {
+	message: string;
+	defaultFg?: string;
+	terminalTheme: TerminalTheme;
+}) {
+	const detail = getClinePassLimitDetailMessage(props.message) ?? props.message;
+
+	return (
+		<box flexDirection="row">
+			<text fg={palette.act} content="* " />
+			<box
+				flexDirection="column"
+				border
+				borderStyle="rounded"
+				borderColor={palette.act}
+				paddingX={1}
+			>
+				<text fg="red">ClinePass limit reached</text>
+				<text fg={props.defaultFg} selectable content={detail} />
+				<text
+					fg={props.defaultFg}
+					selectable
+					content="Switch to Cline usage-based billing and retry with the Cline provider."
+				/>
+				<box flexDirection="row">
+					<text fg="gray">Interactive CLI: </text>
+					<text
+						fg={props.defaultFg}
+						selectable
+						content="type /model, press tab to change provider, choose Cline, then retry."
+					/>
+				</box>
+				<box flexDirection="row">
+					<text fg="gray">Headless CLI: </text>
+					<text fg={props.defaultFg} selectable content="rerun with " />
+					<code
+						content="--provider cline"
+						filetype="bash"
+						syntaxStyle={getSyntaxStyle(props.terminalTheme)}
+						selectable
+					/>
+					<text fg={props.defaultFg} selectable content="." />
+				</box>
+			</box>
+		</box>
+	);
+}
+
 export function ChatEntryView(props: {
 	entry: ChatEntry;
 	accent?: string;
@@ -534,6 +617,15 @@ export function ChatEntryView(props: {
 					/>
 				);
 			}
+			if (isClinePassLimitErrorMessage(entry.text)) {
+				return (
+					<ClinePassLimitErrorView
+						message={entry.text}
+						defaultFg={defaultFg}
+						terminalTheme={terminalTheme}
+					/>
+				);
+			}
 			return (
 				<box flexDirection="row">
 					<text fg="red" content="* " />
@@ -557,6 +649,9 @@ export function ChatEntryView(props: {
 				</box>
 			);
 
+		case "compaction":
+			return <CompactionDividerRow entry={entry} />;
+
 		case "done": {
 			const parts: string[] = [];
 			if (entry.elapsed) parts.push(`${entry.elapsed}s`);

apps/cli/src/tui/components/dialogs/provider-picker-helpers.ts

@@ -1,8 +1,50 @@
+import {
+	getProviderAuthStorageId,
+	type ProviderSettingsManager,
+	saveLocalProviderSettings,
+} from "@cline/core";
 import { CLI_PROMO_CODE } from "../../../utils/cline-pass-errors";
 
 const CLINE_PASS_SUBSCRIPTION_PATH = "/dashboard/subscription";
 const DEFAULT_APP_BASE_URL = "https://app.cline.bot";
 
+/**
+ * Persist a manually entered API key for an OAuth-capable provider — the
+ * escape hatch for when OAuth login isn't working. Any stored OAuth tokens
+ * are cleared: the auth handler prefers auth.accessToken over apiKey, so a
+ * stale token would otherwise keep winning over the manual key.
+ *
+ * The key is written both to the provider's auth storage entry (cline-pass
+ * stores credentials under "cline") and to the provider's own entry: settings
+ * resolution lets a direct entry shadow the storage entry, and provider
+ * switching copies merged settings (including auth) into direct entries, so
+ * both must be updated for the manual key to reliably take effect.
+ */
+export function saveManualProviderApiKey(
+	manager: ProviderSettingsManager,
+	providerId: string,
+	apiKey: string,
+): void {
+	// Empty strings delete these keys from the stored auth object.
+	const clearedAuth = { accessToken: "", refreshToken: "", apiKey: "" };
+	const storageProviderId = getProviderAuthStorageId(providerId) ?? providerId;
+	saveLocalProviderSettings(manager, {
+		providerId: storageProviderId,
+		apiKey,
+		auth: clearedAuth,
+	});
+	if (
+		providerId !== storageProviderId &&
+		manager.read().providers[providerId]
+	) {
+		saveLocalProviderSettings(manager, {
+			providerId,
+			apiKey,
+			auth: clearedAuth,
+		});
+	}
+}
+
 export function buildClinePassSubscriptionPageUrl(
 	appBaseUrl: string | undefined,
 ): string {

apps/cli/src/tui/components/dialogs/provider-picker.test.ts

@@ -1,5 +1,16 @@
-import { describe, expect, it } from "vitest";
-import { buildClinePassSubscriptionPageUrl } from "./provider-picker-helpers";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ProviderSettingsManager } from "@cline/core";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	getPersistedProviderApiKey,
+	isProviderConfigured,
+} from "../../../utils/provider-auth";
+import {
+	buildClinePassSubscriptionPageUrl,
+	saveManualProviderApiKey,
+} from "./provider-picker-helpers";
 
 describe("buildClinePassSubscriptionPageUrl", () => {
 	it("opens the personal subscription page on production by default", () => {
@@ -16,3 +27,99 @@ describe("buildClinePassSubscriptionPageUrl", () => {
 		);
 	});
 });
+
+describe("saveManualProviderApiKey", () => {
+	const tempDirs: string[] = [];
+
+	afterEach(() => {
+		for (const dir of tempDirs.splice(0)) {
+			rmSync(dir, { force: true, recursive: true });
+		}
+	});
+
+	function createManager(): ProviderSettingsManager {
+		const dir = mkdtempSync(join(tmpdir(), "cline-cli-provider-picker-"));
+		tempDirs.push(dir);
+		return new ProviderSettingsManager({
+			filePath: join(dir, "providers.json"),
+		});
+	}
+
+	it("clears stored OAuth tokens so the manual key takes effect", () => {
+		const manager = createManager();
+		manager.saveProviderSettings({
+			provider: "cline",
+			auth: {
+				accessToken: "stale-access-token",
+				refreshToken: "stale-refresh-token",
+				accountId: "acct_123",
+			},
+		});
+
+		saveManualProviderApiKey(manager, "cline", "manual-api-key");
+
+		const settings = manager.getProviderSettings("cline");
+		expect(settings?.apiKey).toBe("manual-api-key");
+		expect(settings?.auth?.accessToken).toBeUndefined();
+		expect(settings?.auth?.refreshToken).toBeUndefined();
+		expect(settings?.auth?.accountId).toBe("acct_123");
+		expect(getPersistedProviderApiKey("cline", settings)).toBe(
+			"manual-api-key",
+		);
+		expect(isProviderConfigured("cline", settings)).toBe(true);
+	});
+
+	it("saves cline-pass keys to the shared cline auth storage entry", () => {
+		const manager = createManager();
+		manager.saveProviderSettings({
+			provider: "cline",
+			auth: {
+				accessToken: "stale-access-token",
+				refreshToken: "stale-refresh-token",
+			},
+		});
+
+		saveManualProviderApiKey(manager, "cline-pass", "manual-api-key");
+
+		// cline-pass inherits auth storage from the "cline" entry, so the key
+		// must land there and the stale tokens must be gone for both providers.
+		const clineSettings = manager.getProviderSettings("cline");
+		expect(clineSettings?.apiKey).toBe("manual-api-key");
+		expect(clineSettings?.auth?.accessToken).toBeUndefined();
+
+		const clinePassSettings = manager.getProviderSettings("cline-pass");
+		expect(getPersistedProviderApiKey("cline-pass", clinePassSettings)).toBe(
+			"manual-api-key",
+		);
+		expect(isProviderConfigured("cline-pass", clinePassSettings)).toBe(true);
+	});
+
+	it("clears stale credentials copied into a direct cline-pass entry", () => {
+		const manager = createManager();
+		manager.saveProviderSettings({
+			provider: "cline",
+			auth: {
+				accessToken: "stale-access-token",
+				refreshToken: "stale-refresh-token",
+			},
+		});
+		// Provider switching copies the merged settings (including auth) into
+		// a direct cline-pass entry, which shadows the shared "cline" entry.
+		manager.saveProviderSettings({
+			provider: "cline-pass",
+			apiKey: "stale-copied-key",
+			auth: {
+				accessToken: "stale-access-token",
+				refreshToken: "stale-refresh-token",
+			},
+		});
+
+		saveManualProviderApiKey(manager, "cline-pass", "manual-api-key");
+
+		const clinePassSettings = manager.getProviderSettings("cline-pass");
+		expect(clinePassSettings?.auth?.accessToken).toBeUndefined();
+		expect(getPersistedProviderApiKey("cline-pass", clinePassSettings)).toBe(
+			"manual-api-key",
+		);
+	});
+});

apps/cli/src/tui/components/dialogs/provider-picker.tsx

@@ -37,7 +37,10 @@ import {
 	getSearchableListRowsWindow,
 	type SearchableItem,
 } from "../searchable-list";
-import { buildClinePassSubscriptionPageUrl } from "./provider-picker-helpers";
+import {
+	buildClinePassSubscriptionPageUrl,
+	saveManualProviderApiKey,
+} from "./provider-picker-helpers";
 
 interface ProviderItem {
 	id: string;
@@ -724,13 +727,27 @@ export function CodexCliStatusContent(
 	);
 }
 
+/**
+ * Resolves `true` on successful login, `"use_api_key"` when the user opts
+ * into manual API key entry (only offered with `allowApiKeyFallback`).
+ */
+export type OAuthLoginResult = boolean | "use_api_key";
+
 export function OAuthLoginContent(
-	props: ChoiceContext<boolean> & {
+	props: ChoiceContext<OAuthLoginResult> & {
 		providerId: string;
 		providerName: string;
+		allowApiKeyFallback?: boolean;
 	},
 ) {
-	const { resolve, dismiss, dialogId, providerId, providerName } = props;
+	const {
+		resolve,
+		dismiss,
+		dialogId,
+		providerId,
+		providerName,
+		allowApiKeyFallback,
+	} = props;
 	const [mode, setMode] = useState<"browser" | "device">(
 		providerId === "cline" ? "device" : "browser",
 	);
@@ -863,9 +880,19 @@ export function OAuthLoginContent(
 		if (key.name === "escape") {
 			cancelAuthAttempt();
 			dismiss();
+			return;
+		}
+		if (key.name === "k" && allowApiKeyFallback) {
+			cancelAuthAttempt();
+			resolve("use_api_key");
 		}
 	}, dialogId);
 
+	const escapeHint = allowApiKeyFallback
+		? "K to enter an API key instead, Esc to cancel"
+		: "Esc to cancel";
+	const escapeHintColor = allowApiKeyFallback ? "white" : "gray";
+
 	if (mode === "device") {
 		return (
 			<box flexDirection="column" paddingX={1} gap={1}>
@@ -892,8 +919,8 @@ export function OAuthLoginContent(
 
 				{deviceError && <text fg="red">{deviceError}</text>}
 
-				<text fg="gray">
-					<em>Esc to cancel</em>
+				<text fg={escapeHintColor}>
+					<em>{escapeHint}</em>
 				</text>
 			</box>
 		);
@@ -915,8 +942,83 @@ export function OAuthLoginContent(
 
 			{error && <text fg="red">{error}</text>}
 
+			<text fg={escapeHintColor}>
+				<em>{escapeHint}</em>
+			</text>
+		</box>
+	);
+}
+
+/**
+ * Manual API key entry for OAuth-capable providers — the escape hatch for
+ * when OAuth login isn't working. Saving clears any stored OAuth tokens so
+ * the manual key takes effect (see saveManualProviderApiKey).
+ */
+export function OAuthApiKeyInputContent(
+	props: ChoiceContext<boolean> & {
+		providerId: string;
+		providerName: string;
+		providerSettingsManager: ProviderSettingsManager;
+	},
+) {
+	const {
+		resolve,
+		dismiss,
+		dialogId,
+		providerId,
+		providerName,
+		providerSettingsManager,
+	} = props;
+	const [value, setValue] = useState("");
+
+	const submit = () => {
+		const apiKey = value.trim();
+		if (!apiKey) return;
+		saveManualProviderApiKey(providerSettingsManager, providerId, apiKey);
+		resolve(true);
+	};
+
+	useDialogKeyboard((key) => {
+		if (key.name === "escape") {
+			dismiss();
+			return;
+		}
+		if (key.name === "return") {
+			submit();
+		}
+	}, dialogId);
+
+	return (
+		<box flexDirection="column" paddingX={1} gap={1}>
+			<text fg={palette.act}>
+				<strong>{providerName}</strong>
+			</text>
+
 			<text fg="gray">
-				<em>Esc to cancel</em>
+				Use an API key from your Cline dashboard instead of OAuth login. This
+				replaces any saved login tokens.
+			</text>
+
+			<box flexDirection="column">
+				<text fg="gray">API key</text>
+				<box
+					border
+					borderStyle="rounded"
+					borderColor={palette.act}
+					paddingX={1}
+				>
+					<input
+						value={value}
+						onInput={setValue}
+						placeholder="Paste your API key"
+						flexGrow={1}
+						focused
+					/>
+				</box>
+			</box>
+
+			<text fg="gray">
+				<em>Enter to save, Esc to go back</em>
 			</text>
 		</box>
 	);

apps/cli/src/tui/hooks/local-command-actions.ts

@@ -3,6 +3,7 @@ import type { OpenConfigOptions } from "./use-config-panel";
 
 export interface LocalSlashCommandActionInput {
 	name: string;
+	isRunning: boolean;
 	openAccount: () => void;
 	openConfig: (options?: OpenConfigOptions) => void;
 	openMcpManager: () => Promise<boolean>;
@@ -46,7 +47,12 @@ export function runLocalSlashCommandAction(
 		return true;
 	}
 	if (normalized === "compact") {
-		input.runCompact();
+		// Autocomplete can invoke local commands while a turn is running. Keep
+		// /compact handled, but do not let it take ownership of the active turn's
+		// shared running state.
+		if (!input.isRunning) {
+			input.runCompact();
+		}
 		return true;
 	}
 	if (normalized === "fork") {

apps/cli/src/tui/hooks/use-account-dialog.tsx

@@ -7,7 +7,10 @@ import {
 	type AccountDialogAction,
 	AccountDialogContent,
 } from "../components/dialogs/account-dialog";
-import { OAuthLoginContent } from "../components/dialogs/provider-picker";
+import {
+	OAuthLoginContent,
+	type OAuthLoginResult,
+} from "../components/dialogs/provider-picker";
 import type { OpenModelSelectorOptions } from "./use-model-selector";
 
 export function useAccountDialog(opts: {
@@ -60,14 +63,14 @@ export function useAccountDialog(opts: {
 			return;
 		}
 		if (action === "login") {
-			const saved = await dialog.choice<boolean>({
+			const saved = await dialog.choice<OAuthLoginResult>({
 				style: { maxHeight: termHeight - 2 },
 				closeOnEscape: false,
-				content: (ctx: ChoiceContext<boolean>) => (
+				content: (ctx: ChoiceContext<OAuthLoginResult>) => (
 					<OAuthLoginContent {...ctx} providerId="cline" providerName="Cline" />
 				),
 			});
-			if (saved) {
+			if (saved === true) {
 				await onAccountChange?.();
 				await openAccountDialog();
 				return;

apps/cli/src/tui/hooks/use-agent-events.ts

@@ -6,13 +6,14 @@ import type {
 	PendingPromptSubmittedEvent,
 } from "../../runtime/session-events";
 import { formatCliErrorMessage } from "../../utils/cline-pass-errors";
-import { resolveStatusNoticeLabel } from "../../utils/events";
+import { resolveNonCompactionStatusLabel } from "../../utils/events";
 import {
 	formatToolInput,
 	formatToolOutput,
 	truncate,
 } from "../../utils/helpers";
 import type { ChatEntry, InlineStream, TuiProps } from "../types";
+import { parseCompactionNoticeMetadata } from "../utils/compaction-status";
 
 interface AgentEventDeps {
 	appendEntry: (entry: ChatEntry) => void;
@@ -32,6 +33,7 @@ interface AgentEventDeps {
 }
 
 export function useAgentEventHandlers(deps: AgentEventDeps) {
+	const openCompactionEntryRef = useRef(false);
 	const {
 		appendEntry,
 		updateLastEntry,
@@ -45,6 +47,47 @@ export function useAgentEventHandlers(deps: AgentEventDeps) {
 		verbose,
 	} = deps;
 
+	// Compaction dividers that arrived while an assistant message was still
+	// streaming. Appending them immediately would split the message in two, so
+	// they are held until the active content block closes (or the turn ends).
+	const pendingCompactionEntriesRef = useRef<
+		Extract<ChatEntry, { kind: "compaction" }>[]
+	>([]);
+
+	const flushPendingCompactionEntries = useCallback(() => {
+		const pending = pendingCompactionEntriesRef.current;
+		if (pending.length === 0) return;
+		pendingCompactionEntriesRef.current = [];
+		for (const entry of pending) {
+			if (entry.status !== "started" && openCompactionEntryRef.current) {
+				updateEntry((current) =>
+					current.kind === "compaction" && current.status === "started"
+						? { ...current, ...entry }
+						: current,
+				);
+				openCompactionEntryRef.current = false;
+			} else {
+				appendEntry(entry);
+				if (entry.status === "started") {
+					openCompactionEntryRef.current = true;
+				}
+			}
+		}
+	}, [appendEntry, updateEntry]);
+
+	const finalizeDanglingCompactionEntry = useCallback(
+		(status: "failed" | "cancelled") => {
+			if (!openCompactionEntryRef.current) return;
+			openCompactionEntryRef.current = false;
+			updateEntry((entry) =>
+				entry.kind === "compaction" && entry.status === "started"
+					? { ...entry, status }
+					: entry,
+			);
+		},
+		[updateEntry],
+	);
+
 	const closeToolEntry = useCallback(
 		(event: AgentEvent & { type: "content_end" }) => {
 			const error = event.error ?? undefined;
@@ -84,9 +127,11 @@ export function useAgentEventHandlers(deps: AgentEventDeps) {
 					setIsRunning(true);
 					setIsStreaming(true);
 					closeInlineStream();
+					flushPendingCompactionEntries();
 					break;
 				case "iteration_end":
 					closeInlineStream();
+					flushPendingCompactionEntries();
 					break;
 				case "content_start": {
 					setIsStreaming(false);
@@ -165,11 +210,15 @@ export function useAgentEventHandlers(deps: AgentEventDeps) {
 					setIsRunning(false);
 					setIsStreaming(false);
 					closeInlineStream();
+					flushPendingCompactionEntries();
+					finalizeDanglingCompactionEntry("cancelled");
 					break;
 				case "error":
 					setIsRunning(false);
 					setIsStreaming(false);
 					closeInlineStream();
+					flushPendingCompactionEntries();
+					finalizeDanglingCompactionEntry("failed");
 					turnErrorReportedRef.current = true;
 					onTurnErrorReported(true);
 					if (!event.recoverable || verbose) {
@@ -181,8 +230,40 @@ export function useAgentEventHandlers(deps: AgentEventDeps) {
 					break;
 				case "notice":
 					if (event.displayRole === "status") {
-						closeInlineStream();
-						const label = resolveStatusNoticeLabel(event);
+						const compaction = parseCompactionNoticeMetadata(event.metadata);
+						if (!compaction) {
+							closeInlineStream();
+						}
+						if (compaction) {
+							if (activeInlineStreamRef.current) {
+								// An assistant message is still streaming; appending now
+								// would split it around the divider. Hold the divider (final
+								// state until the content block closes, then reconcile it
+								// with the same open divider atomically.
+								pendingCompactionEntriesRef.current.push({
+									kind: "compaction",
+									...compaction,
+								});
+								break;
+							}
+							if (compaction.status === "started") {
+								appendEntry({ kind: "compaction", ...compaction });
+								openCompactionEntryRef.current = true;
+							} else if (openCompactionEntryRef.current) {
+								// Finalize the in-progress divider in place, wherever it
+								// sits in the transcript.
+								updateEntry((entry) =>
+									entry.kind === "compaction" && entry.status === "started"
+										? { ...entry, ...compaction }
+										: entry,
+								);
+								openCompactionEntryRef.current = false;
+							} else {
+								appendEntry({ kind: "compaction", ...compaction });
+							}
+							break;
+						}
+						const label = resolveNonCompactionStatusLabel(event);
 						if (label) {
 							appendEntry({ kind: "status", text: label });
 						}
@@ -200,6 +281,7 @@ export function useAgentEventHandlers(deps: AgentEventDeps) {
 		[
 			appendEntry,
 			updateLastEntry,
+			updateEntry,
 			closeInlineStream,
 			activeInlineStreamRef,
 			setIsRunning,
@@ -208,6 +290,8 @@ export function useAgentEventHandlers(deps: AgentEventDeps) {
 			onTurnErrorReported,
 			verbose,
 			closeToolEntry,
+			finalizeDanglingCompactionEntry,
+			flushPendingCompactionEntries,
 		],
 	);
 

apps/cli/src/tui/hooks/use-local-command-actions.test.ts

@@ -9,6 +9,7 @@ function makeActions(
 	overrides: Partial<Omit<LocalSlashCommandActionInput, "name">> = {},
 ): Omit<LocalSlashCommandActionInput, "name"> {
 	return {
+		isRunning: false,
 		openAccount: vi.fn(),
 		openConfig: vi.fn(),
 		openMcpManager: vi.fn(async () => false),
@@ -58,6 +59,32 @@ describe("runLocalSlashCommandAction", () => {
 		expect(openConfig).toHaveBeenCalledWith({ initialTab: "plugins" });
 	});
 
+	it("does not start compaction while a turn is running", () => {
+		const runCompact = vi.fn();
+		const actions = makeActions({ isRunning: true, runCompact });
+
+		const handled = runLocalSlashCommandAction({
+			name: "compact",
+			...actions,
+		});
+
+		expect(handled).toBe(true);
+		expect(runCompact).not.toHaveBeenCalled();
+	});
+
+	it("starts compaction while the session is idle", () => {
+		const runCompact = vi.fn();
+		const actions = makeActions({ runCompact });
+
+		const handled = runLocalSlashCommandAction({
+			name: "compact",
+			...actions,
+		});
+
+		expect(handled).toBe(true);
+		expect(runCompact).toHaveBeenCalledOnce();
+	});
+
 	it("waits for clear to reset the runtime session", async () => {
 		let resolveClear: (() => void) | undefined;
 		const clearConversation = vi.fn(

apps/cli/src/tui/hooks/use-local-command-actions.tsx

@@ -9,7 +9,6 @@ import { HelpDialogContent } from "../components/dialogs/help-dialog";
 import { withLoadingDialog } from "../components/dialogs/loading-dialog";
 import { useSession } from "../contexts/session-context";
 import type { AppView, TuiProps } from "../types";
-import { formatCompactionStatus } from "../utils/compaction-status";
 import { hydrateSessionMessages } from "../utils/hydrate-messages";
 import type { LocalSlashCommandInvocation } from "../utils/skill-command-input";
 import { HistoryDialogContent } from "../views/history-view";
@@ -116,21 +115,42 @@ export function useLocalCommandActions(input: {
 	}, [dialog, refocusTextarea, termHeight]);
 
 	const runCompact = useCallback(async () => {
+		session.setIsRunning(true);
 		session.appendEntry({
-			kind: "status",
-			text: "Compacting context...",
+			kind: "compaction",
+			compactionMode: "manual",
+			status: "started",
 		});
 		try {
 			const result = await onCompact();
-			session.updateLastEntry(() => ({
-				kind: "status",
-				text: formatCompactionStatus(result),
-			}));
+			session.updateLastEntry((entry) =>
+				entry.kind === "compaction" && entry.status === "started"
+					? {
+							...entry,
+							status: result.compacted ? "completed" : "skipped",
+							messagesBefore: result.messagesBefore,
+							messagesAfter:
+								result.workingContextMessagesAfter ?? result.messagesAfter,
+						}
+					: entry,
+			);
 		} catch (error) {
-			session.appendEntry({
-				kind: "error",
-				text: `Compaction failed: ${error instanceof Error ? error.message : String(error)}`,
-			});
+			const cancelled =
+				error instanceof Error &&
+				(error.name === "AbortError" || /abort/i.test(error.message));
+			session.updateLastEntry((entry) =>
+				entry.kind === "compaction" && entry.status === "started"
+					? { ...entry, status: cancelled ? "cancelled" : "failed" }
+					: entry,
+			);
+			if (!cancelled) {
+				session.appendEntry({
+					kind: "error",
+					text: `Compaction failed: ${error instanceof Error ? error.message : String(error)}`,
+				});
+			}
+		} finally {
+			session.setIsRunning(false);
 		}
 	}, [onCompact, session]);
 
@@ -159,6 +179,15 @@ export function useLocalCommandActions(input: {
 					kind: "status",
 					text: `Forked into new session ${result.newSessionId}. This is now the active session. Use /history to switch sessions.`,
 				}));
+				if (result.carriedWorkingContext) {
+					session.appendEntry({
+						kind: "compaction",
+						compactionMode: "inherited",
+						status: "completed",
+						messagesBefore: result.carriedWorkingContext.canonicalMessages,
+						messagesAfter: result.carriedWorkingContext.workingContextMessages,
+					});
+				}
 			} else {
 				session.updateLastEntry(() => ({
 					kind: "error",
@@ -181,6 +210,7 @@ export function useLocalCommandActions(input: {
 			}
 			return runLocalSlashCommandAction({
 				name: resolved.name,
+				isRunning: session.isRunning,
 				invocation,
 				openAccount,
 				openConfig,
@@ -209,6 +239,7 @@ export function useLocalCommandActions(input: {
 			openSkills,
 			runCompact,
 			runFork,
+			session.isRunning,
 			slashCommandRegistry,
 		],
 	);

apps/cli/src/tui/hooks/use-model-selector.tsx

@@ -6,6 +6,7 @@ import {
 	refreshProviderModelsFromSource,
 	resolveProviderConfig,
 } from "@cline/core";
+import { isClineProvider } from "@cline/shared";
 import type { ChoiceContext } from "@opentui-ui/dialog";
 import type { DialogActions } from "@opentui-ui/dialog/react";
 import { useCallback } from "react";
@@ -21,7 +22,9 @@ import {
 	ClinePassSubscriptionContent,
 	CodexCliStatusContent,
 	type ExistingProviderOption,
+	OAuthApiKeyInputContent,
 	OAuthLoginContent,
+	type OAuthLoginResult,
 	ProviderConfigInputContent,
 	ProviderPickerContent,
 	UseExistingOrReconfigureContent,
@@ -79,6 +82,51 @@ function usesModelIdInput(providerId: string): boolean {
 	return providerId === "openai-compatible";
 }
 
+/**
+ * Ask an OpenAI-compatible endpoint for its model list (`GET <baseUrl>/models`)
+ * using the provider's stored API key and headers, mirroring the extension's
+ * refreshOpenAiModels handler. Returns [] on any failure so callers fall back
+ * to manual model-id entry.
+ */
+async function fetchOpenAiCompatibleModelIds(
+	providerId: string,
+): Promise<string[]> {
+	try {
+		const manager = new ProviderSettingsManager();
+		const config = manager.getProviderConfig(providerId, {
+			includeKnownModels: false,
+		});
+		const baseUrl = config?.baseUrl?.trim().replace(/\/+$/, "");
+		if (!baseUrl || !URL.canParse(baseUrl)) return [];
+
+		const headers: Record<string, string> = { ...(config?.headers ?? {}) };
+		const apiKey = config?.apiKey?.trim();
+		if (
+			apiKey &&
+			!Object.keys(headers).some((h) => h.toLowerCase() === "authorization")
+		) {
+			headers.Authorization = `Bearer ${apiKey}`;
+		}
+
+		const response = await fetch(`${baseUrl}/models`, {
+			headers,
+			signal: AbortSignal.timeout(5_000),
+		});
+		if (!response.ok) return [];
+		const payload = (await response.json()) as { data?: unknown };
+		const list = Array.isArray(payload?.data) ? payload.data : [];
+		const ids = list
+			.map((model) => {
+				const id = (model as { id?: unknown } | null)?.id;
+				return typeof id === "string" ? id.trim() : "";
+			})
+			.filter(Boolean);
+		return [...new Set(ids)];
+	} catch {
+		return [];
+	}
+}
+
 function providerToExistingProviderOptions(input: {
 	providerId: string;
 	providerName: string;
@@ -131,6 +179,23 @@ async function runProviderChange(
 	);
 	const existingSettings = manager.getProviderSettings(newProviderId);
 
+	// Manual API key entry is the escape hatch for when OAuth login isn't
+	// working; only the Cline providers accept a dashboard API key.
+	const supportsManualApiKey = isClineProvider(newProviderId);
+	const openManualApiKeyDialog = async (): Promise<boolean | undefined> =>
+		await dialog.choice<boolean>({
+			style: { maxHeight: termHeight - 2 },
+			closeOnEscape: false,
+			content: (ctx: ChoiceContext<boolean>) => (
+				<OAuthApiKeyInputContent
+					{...ctx}
+					providerId={newProviderId}
+					providerName={displayName}
+					providerSettingsManager={manager}
+				/>
+			),
+		});
+
 	let needsAuth = true;
 	if (isProviderConfigured(newProviderId, existingSettings)) {
 		let option: ExistingProviderOption | undefined;
@@ -165,17 +230,22 @@ async function runProviderChange(
 	if (needsAuth) {
 		let saved: boolean | undefined;
 		if (isOAuthProvider(newProviderId)) {
-			saved = await dialog.choice<boolean>({
+			const loginResult = await dialog.choice<OAuthLoginResult>({
 				style: { maxHeight: termHeight - 2 },
 				closeOnEscape: false,
-				content: (ctx: ChoiceContext<boolean>) => (
+				content: (ctx: ChoiceContext<OAuthLoginResult>) => (
 					<OAuthLoginContent
 						{...ctx}
 						providerId={newProviderId}
 						providerName={displayName}
+						allowApiKeyFallback={supportsManualApiKey}
 					/>
 				),
 			});
+			saved =
+				loginResult === "use_api_key"
+					? await openManualApiKeyDialog()
+					: loginResult;
 		} else if (isOpenAICodexCliProvider(newProviderId)) {
 			saved = await dialog.choice<boolean>({
 				style: { maxHeight: termHeight - 2 },
@@ -275,12 +345,28 @@ export function useModelSelector(opts: {
 				config.knownModels as Record<string, Llms.ModelInfo>,
 			);
 			let providerDisplayName = config.providerId;
+			let endpointModelOptions: ModelOption[] = [];
 
 			const refreshProviderContext = async () => {
 				modelOptions = buildModelOptions(
 					config.knownModels as Record<string, Llms.ModelInfo>,
 				);
 				providerDisplayName = await getProviderDisplayName(config.providerId);
+				// Free-text providers (openai-compatible) can still suggest model
+				// ids when their endpoint answers /models; otherwise they keep the
+				// manual input.
+				endpointModelOptions = usesModelIdInput(config.providerId)
+					? buildModelOptions(
+							Object.fromEntries(
+								(await fetchOpenAiCompatibleModelIds(config.providerId)).map(
+									(id) => [id, { id, name: id }],
+								),
+							),
+						)
+					: [];
+				if (endpointModelOptions.length > 0) {
+					modelOptions = endpointModelOptions;
+				}
 			};
 
 			if (!options?.startWithProviderChange) {
@@ -316,7 +402,10 @@ export function useModelSelector(opts: {
 			let pickingModel = true;
 
 			while (pickingModel) {
-				if (usesModelIdInput(config.providerId)) {
+				if (
+					usesModelIdInput(config.providerId) &&
+					endpointModelOptions.length === 0
+				) {
 					const modelId = await dialog.choice<string>({
 						style: { maxHeight: termHeight - 2 },
 						content: (ctx: ChoiceContext<string>) => (

apps/cli/src/tui/hooks/use-terminal-title.test.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	type TerminalTitleRenderer,
+	useTerminalTitle,
+} from "./use-terminal-title";
+
+const reactMock = vi.hoisted(() => {
+	const cleanups: Array<() => void> = [];
+	return {
+		cleanups,
+		// Run effect bodies now, but retain their cleanups so each test can move
+		// the renderer across the native destruction boundary before unmount.
+		useEffect: vi.fn((effect: () => undefined | (() => void)) => {
+			const cleanup = effect();
+			if (cleanup) {
+				cleanups.push(cleanup);
+			}
+		}),
+	};
+});
+
+vi.mock("react", () => ({
+	useEffect: reactMock.useEffect,
+}));
+
+function createTitleRenderer() {
+	let destroyed = false;
+	const setTerminalTitle = vi.fn(() => {
+		if (destroyed) {
+			throw new Error("setTerminalTitle called after renderer destruction");
+		}
+	});
+	const renderer: TerminalTitleRenderer = {
+		get isDestroyed() {
+			return destroyed;
+		},
+		setTerminalTitle,
+	};
+
+	return {
+		destroy: () => {
+			destroyed = true;
+		},
+		renderer,
+		setTerminalTitle,
+	};
+}
+
+beforeEach(() => {
+	reactMock.cleanups.length = 0;
+	reactMock.useEffect.mockClear();
+});
+
+describe("useTerminalTitle", () => {
+	it("sets and resets the title while the renderer is active", () => {
+		const titleRenderer = createTitleRenderer();
+
+		useTerminalTitle(titleRenderer.renderer, "Cline");
+		expect(titleRenderer.setTerminalTitle).toHaveBeenNthCalledWith(1, "Cline");
+
+		for (const cleanup of reactMock.cleanups) {
+			cleanup();
+		}
+
+		expect(titleRenderer.setTerminalTitle).toHaveBeenCalledTimes(2);
+		expect(titleRenderer.setTerminalTitle).toHaveBeenNthCalledWith(2, "");
+	});
+
+	it("does not set the title when its effect runs after renderer destruction", () => {
+		const titleRenderer = createTitleRenderer();
+		titleRenderer.destroy();
+
+		useTerminalTitle(titleRenderer.renderer, "Cline");
+
+		expect(titleRenderer.setTerminalTitle).not.toHaveBeenCalled();
+	});
+
+	it("does not reset the title when cleanup runs after renderer destruction", () => {
+		const titleRenderer = createTitleRenderer();
+
+		useTerminalTitle(titleRenderer.renderer, "Cline");
+		expect(titleRenderer.setTerminalTitle).toHaveBeenCalledOnce();
+
+		titleRenderer.destroy();
+		for (const cleanup of reactMock.cleanups) {
+			cleanup();
+		}
+
+		expect(titleRenderer.setTerminalTitle).toHaveBeenCalledOnce();
+	});
+});

apps/cli/src/tui/hooks/use-terminal-title.ts

@@ -0,0 +1,29 @@
+import { useEffect } from "react";
+
+export interface TerminalTitleRenderer {
+	readonly isDestroyed: boolean;
+	setTerminalTitle(title: string): void;
+}
+
+export function useTerminalTitle(
+	renderer: TerminalTitleRenderer,
+	terminalTitle: string,
+): void {
+	// setTerminalTitle writes into memory owned by the native renderer, so it
+	// must never run after destroy. React can flush passive effects after the
+	// renderer's memory has been freed.
+	useEffect(() => {
+		if (renderer.isDestroyed) {
+			return;
+		}
+		renderer.setTerminalTitle(terminalTitle);
+	}, [renderer, terminalTitle]);
+
+	useEffect(() => {
+		return () => {
+			if (!renderer.isDestroyed) {
+				renderer.setTerminalTitle("");
+			}
+		};
+	}, [renderer]);
+}

apps/cli/src/tui/index.test.ts

@@ -8,7 +8,9 @@ const rendererMock = vi.hoisted(() => ({
 		defaultBackground: null,
 		defaultForeground: null,
 	})),
+	isDestroyed: false,
 	on: vi.fn(),
+	setTerminalTitle: vi.fn(),
 }));
 
 const rootMock = vi.hoisted(() => ({
@@ -37,7 +39,9 @@ describe("renderOpenTui", () => {
 
 	beforeEach(() => {
 		destroyHandlers.length = 0;
+		rendererMock.isDestroyed = false;
 		rendererMock.destroy.mockReset();
+		rendererMock.setTerminalTitle.mockReset();
 		rendererMock.on.mockReset();
 		rendererMock.on.mockImplementation((event: string, handler: () => void) => {
 			if (event === "destroy") {
@@ -96,4 +100,37 @@ describe("renderOpenTui", () => {
 		expect(rendererMock.destroy).toHaveBeenCalledTimes(1);
 		expect(rootMock.unmount).toHaveBeenCalledTimes(1);
 	});
+
+	it("resets the terminal title before destroying the renderer", async () => {
+		const { renderOpenTui } = await import("./index");
+		const tui = await renderOpenTui({} as TuiProps);
+
+		tui.destroy();
+		await Promise.resolve();
+
+		expect(rendererMock.setTerminalTitle).toHaveBeenCalledWith("");
+		expect(rendererMock.destroy).toHaveBeenCalledTimes(1);
+		const titleCallOrder =
+			rendererMock.setTerminalTitle.mock.invocationCallOrder[0];
+		const destroyCallOrder = rendererMock.destroy.mock.invocationCallOrder[0];
+		expect(titleCallOrder).toBeLessThan(destroyCallOrder);
+	});
+
+	it("skips the title reset when the renderer is destroyed before the teardown microtask runs", async () => {
+		const { renderOpenTui } = await import("./index");
+		const tui = await renderOpenTui({} as TuiProps);
+
+		tui.destroy();
+		// Simulate OpenTUI's own signal handler destroying the renderer in the
+		// same dispatch (e.g. an idle SIGTERM fires both our handler and
+		// OpenTUI's exitHandler before microtasks drain).
+		rendererMock.isDestroyed = true;
+		for (const handler of destroyHandlers) {
+			handler();
+		}
+
+		await Promise.resolve();
+
+		expect(rendererMock.setTerminalTitle).not.toHaveBeenCalled();
+	});
 });

apps/cli/src/tui/index.tsx

@@ -67,6 +67,14 @@ export async function renderOpenTui(
 		unmountRoot();
 		// Let OpenTUI finish parsing the current stdin batch before teardown.
 		queueMicrotask(() => {
+			// Reset the title while the native renderer is still alive; the
+			// unmount cleanup in root.tsx skips it once the renderer is destroyed.
+			// Re-check here: OpenTUI's own signal handlers can destroy the
+			// renderer between destroy() queuing this microtask and it running
+			// (e.g. an idle SIGTERM dispatches to both our handler and OpenTUI's).
+			if (!renderer.isDestroyed) {
+				renderer.setTerminalTitle("");
+			}
 			renderer.destroy();
 		});
 	};

apps/cli/src/tui/interactive-config.ts

@@ -27,6 +27,7 @@ import {
 	type UserInstructionConfigService,
 	type WorkflowConfig,
 } from "@cline/core";
+import { readFileSyncStrippingUtf8Bom } from "@cline/shared/node";
 import { getToolCatalog } from "../runtime/tools";
 import {
 	type InteractiveSlashCommand,
@@ -195,7 +196,7 @@ function loadAgentConfigItems(workspaceRoot: string): InteractiveConfigItem[] {
 					continue;
 				}
 				const filePath = join(directory, entry.name);
-				const raw = readFileSync(filePath, "utf8");
+				const raw = readFileSyncStrippingUtf8Bom(filePath);
 				const frontmatterMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
 				const frontmatter = frontmatterMatch?.[1] ?? "";
 				const nameMatch = frontmatter.match(/^\s*name:\s*(.+?)\s*$/m);

apps/cli/src/tui/root.tsx

@@ -53,6 +53,7 @@ import { useRootKeyboard } from "./hooks/use-root-keyboard";
 import { useRuntimeDialogBridge } from "./hooks/use-runtime-dialog-bridge";
 import { useSlashCommands } from "./hooks/use-slash-commands";
 import { TerminalColorsContext } from "./hooks/use-terminal-background";
+import { useTerminalTitle } from "./hooks/use-terminal-title";
 import type { AppView, TuiProps } from "./types";
 import { hydrateSessionMessages } from "./utils/hydrate-messages";
 import { isProviderConfigured } from "./utils/provider-configured";
@@ -472,15 +473,7 @@ function App(props: TuiProps) {
 		};
 	}, [renderer, showToast]);
 
-	useEffect(() => {
-		renderer.setTerminalTitle(terminalTitle);
-	}, [renderer, terminalTitle]);
-
-	useEffect(() => {
-		return () => {
-			renderer.setTerminalTitle("");
-		};
-	}, [renderer]);
+	useTerminalTitle(renderer, terminalTitle);
 
 	useEffect(() => {
 		return () => {

apps/cli/src/tui/types.ts

@@ -44,6 +44,15 @@ export type ChatEntry = (
 	  }
 	| { kind: "error"; text: string }
 	| { kind: "status"; text: string }
+	| {
+			kind: "compaction";
+			compactionMode: "auto" | "manual" | "inherited";
+			status: "started" | "completed" | "skipped" | "failed" | "cancelled";
+			tokensBefore?: number;
+			tokensAfter?: number;
+			messagesBefore?: number;
+			messagesAfter?: number;
+	  }
 	| { kind: "team"; text: string }
 	| { kind: "user_submitted"; text: string; delivery?: "queue" | "steer" }
 	| {
@@ -186,7 +195,15 @@ export interface TuiProps {
 	onResumeSession: (sessionId: string) => Promise<ResumedSessionResult>;
 	onCompact: () => Promise<InteractiveCompactionResult>;
 	onFork: () => Promise<
-		{ forkedFromSessionId: string; newSessionId: string } | undefined
+		| {
+				forkedFromSessionId: string;
+				newSessionId: string;
+				carriedWorkingContext?: {
+					workingContextMessages: number;
+					canonicalMessages: number;
+				};
+		  }
+		| undefined
 	>;
 	getCheckpointData: () => Promise<
 		{ messages: Message[]; checkpointHistory: CheckpointEntry[] } | undefined

apps/cli/src/tui/utils/compaction-status.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import {
+	formatCompactionDividerLabel,
+	formatTokenCount,
+	parseCompactionNoticeMetadata,
+} from "./compaction-status";
+
+describe("parseCompactionNoticeMetadata", () => {
+	it("extracts a divider entry from a completed auto-compaction notice", () => {
+		expect(
+			parseCompactionNoticeMetadata({
+				kind: "auto_compaction",
+				reason: "auto_compaction",
+				phase: "completed",
+				tokensBefore: 25_101,
+				tokensAfter: 6_300,
+				messagesBefore: 142,
+				messagesAfter: 9,
+			}),
+		).toEqual({
+			compactionMode: "auto",
+			status: "completed",
+			tokensBefore: 25_101,
+			tokensAfter: 6_300,
+			messagesBefore: 142,
+			messagesAfter: 9,
+		});
+	});
+
+	it("extracts a streaming divider entry from a started notice", () => {
+		expect(
+			parseCompactionNoticeMetadata({
+				kind: "auto_compaction",
+				phase: "started",
+			}),
+		).toEqual({ compactionMode: "auto", status: "started" });
+	});
+
+	it("maps manual compaction notices to manual mode", () => {
+		expect(
+			parseCompactionNoticeMetadata({
+				kind: "manual_compaction",
+				phase: "completed",
+			})?.compactionMode,
+		).toBe("manual");
+	});
+
+	it("maps a benign no-result terminal notice to skipped", () => {
+		expect(
+			parseCompactionNoticeMetadata({
+				kind: "auto_compaction",
+				phase: "skipped",
+			}),
+		).toEqual({ compactionMode: "auto", status: "skipped" });
+	});
+
+	it("ignores non-compaction metadata", () => {
+		expect(
+			parseCompactionNoticeMetadata({ kind: "recovery", phase: "completed" }),
+		).toBeUndefined();
+		expect(
+			parseCompactionNoticeMetadata({ kind: "auto_compaction" }),
+		).toBeUndefined();
+		expect(parseCompactionNoticeMetadata(undefined)).toBeUndefined();
+	});
+
+	it("drops non-numeric counters instead of rendering garbage", () => {
+		const parsed = parseCompactionNoticeMetadata({
+			kind: "auto_compaction",
+			phase: "completed",
+			tokensBefore: "25000",
+			tokensAfter: Number.NaN,
+		});
+		expect(parsed?.tokensBefore).toBeUndefined();
+		expect(parsed?.tokensAfter).toBeUndefined();
+	});
+});
+
+describe("formatTokenCount", () => {
+	it("formats counts into compact units", () => {
+		expect(formatTokenCount(999)).toBe("999");
+		expect(formatTokenCount(6_300)).toBe("6.3k");
+		expect(formatTokenCount(25_000)).toBe("25k");
+		expect(formatTokenCount(1_200_000)).toBe("1.2M");
+	});
+});
+
+describe("formatCompactionDividerLabel", () => {
+	it("includes token and message deltas when present", () => {
+		expect(
+			formatCompactionDividerLabel({
+				kind: "compaction",
+				compactionMode: "auto",
+				status: "completed",
+				tokensBefore: 25_101,
+				tokensAfter: 6_300,
+				messagesBefore: 142,
+				messagesAfter: 9,
+			}),
+		).toBe("Context compacted · 25.1k → 6.3k tokens · 142 → 9 messages");
+	});
+
+	it("labels in-progress compaction", () => {
+		expect(
+			formatCompactionDividerLabel({
+				kind: "compaction",
+				compactionMode: "auto",
+				status: "started",
+			}),
+		).toBe("Auto compacting messages");
+		expect(
+			formatCompactionDividerLabel({
+				kind: "compaction",
+				compactionMode: "manual",
+				status: "started",
+			}),
+		).toBe("Compacting messages");
+	});
+
+	it("labels failed and cancelled compaction", () => {
+		expect(
+			formatCompactionDividerLabel({
+				kind: "compaction",
+				compactionMode: "auto",
+				status: "failed",
+			}),
+		).toBe("Compaction failed");
+		expect(
+			formatCompactionDividerLabel({
+				kind: "compaction",
+				compactionMode: "auto",
+				status: "cancelled",
+			}),
+		).toBe("Compaction cancelled");
+	});
+
+	it("labels skipped compaction without calling it cancelled", () => {
+		expect(
+			formatCompactionDividerLabel({
+				kind: "compaction",
+				compactionMode: "auto",
+				status: "skipped",
+			}),
+		).toBe("Compaction skipped");
+	});
+
+	it("labels inherited working context from forks and restarts", () => {
+		expect(
+			formatCompactionDividerLabel({
+				kind: "compaction",
+				compactionMode: "inherited",
+				status: "completed",
+				messagesBefore: 60,
+				messagesAfter: 15,
+			}),
+		).toBe("Compacted working context carried over · 60 → 15 messages");
+	});
+
+	it("labels manual compaction and omits missing counters", () => {
+		expect(
+			formatCompactionDividerLabel({
+				kind: "compaction",
+				compactionMode: "manual",
+				status: "completed",
+			}),
+		).toBe("Context compacted (manual)");
+	});
+});

apps/cli/src/tui/utils/compaction-status.ts

@@ -1,9 +1,106 @@
-import type { InteractiveCompactionResult } from "../types";
+import type { ChatEntry, InteractiveCompactionResult } from "../types";
+
+export type CompactionDividerEntry = Extract<ChatEntry, { kind: "compaction" }>;
 
 function formatMessageCount(count: number): string {
 	return `${count} ${count === 1 ? "message" : "messages"}`;
 }
 
+function asFiniteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value)
+		? value
+		: undefined;
+}
+
+/**
+ * Extracts a compaction divider entry from a status notice's metadata.
+ * "started" notices produce a streaming (in-progress) divider; "completed"
+ * notices produce the final divider with counters. Returns undefined for
+ * non-compaction notices.
+ */
+export function parseCompactionNoticeMetadata(
+	metadata: Record<string, unknown> | undefined,
+): Omit<CompactionDividerEntry, "kind"> | undefined {
+	if (
+		!metadata ||
+		(metadata.phase !== "started" &&
+			metadata.phase !== "completed" &&
+			metadata.phase !== "skipped")
+	) {
+		return undefined;
+	}
+	const kind = metadata.kind ?? metadata.reason;
+	if (kind !== "auto_compaction" && kind !== "manual_compaction") {
+		return undefined;
+	}
+	const compactionMode = kind === "manual_compaction" ? "manual" : "auto";
+	if (metadata.phase === "started") {
+		return { compactionMode, status: "started" };
+	}
+	if (metadata.phase === "skipped") {
+		return { compactionMode, status: "skipped" };
+	}
+	return {
+		compactionMode,
+		status: "completed",
+		tokensBefore: asFiniteNumber(metadata.tokensBefore),
+		tokensAfter: asFiniteNumber(metadata.tokensAfter),
+		messagesBefore: asFiniteNumber(metadata.messagesBefore),
+		messagesAfter: asFiniteNumber(metadata.messagesAfter),
+	};
+}
+
+export function formatTokenCount(count: number): string {
+	if (count < 1_000) {
+		return `${count}`;
+	}
+	if (count < 1_000_000) {
+		return `${(count / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
+	}
+	return `${(count / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+}
+
+export function formatCompactionDividerLabel(
+	entry: CompactionDividerEntry,
+): string {
+	if (entry.status === "started") {
+		return entry.compactionMode === "manual"
+			? "Compacting messages"
+			: "Auto compacting messages";
+	}
+	if (entry.status === "failed") {
+		return "Compaction failed";
+	}
+	if (entry.status === "cancelled") {
+		return "Compaction cancelled";
+	}
+	if (entry.status === "skipped") {
+		return "Compaction skipped";
+	}
+	const parts: string[] = [
+		entry.compactionMode === "manual"
+			? "Context compacted (manual)"
+			: entry.compactionMode === "inherited"
+				? "Compacted working context carried over"
+				: "Context compacted",
+	];
+	if (
+		typeof entry.tokensBefore === "number" &&
+		typeof entry.tokensAfter === "number"
+	) {
+		parts.push(
+			`${formatTokenCount(entry.tokensBefore)} → ${formatTokenCount(entry.tokensAfter)} tokens`,
+		);
+	}
+	if (
+		typeof entry.messagesBefore === "number" &&
+		typeof entry.messagesAfter === "number"
+	) {
+		parts.push(`${entry.messagesBefore} → ${entry.messagesAfter} messages`);
+	}
+	return parts.join(" · ");
+}
+
 export function formatCompactionStatus(
 	result: InteractiveCompactionResult,
 ): string {

apps/cli/src/utils/chat-commands.ts

@@ -14,6 +14,15 @@ export type ChatCommandState = {
 export type ForkSessionResult = {
 	forkedFromSessionId: string;
 	newSessionId: string;
+	/**
+	 * Present when the source session had valid compaction state that was
+	 * re-anchored onto the forked session, so the UI can surface why the
+	 * next request is smaller than the canonical history.
+	 */
+	carriedWorkingContext?: {
+		workingContextMessages: number;
+		canonicalMessages: number;
+	};
 };
 
 export type MuteCommandInput = {

apps/cli/src/utils/cline-pass-errors.test.ts

@@ -1,10 +1,13 @@
 import { describe, expect, it } from "vitest";
 import {
 	formatCliErrorMessage,
+	getCliClinePassLimitMessage,
 	getCliNotSubscribedMessage,
 	getClineOrgIndividualInferenceSubscriptionMessage,
+	getClinePassLimitDetailMessage,
 	getCliSubscriptionUrl,
 	isClineOrgIndividualInferenceSubscriptionErrorMessage,
+	isClinePassLimitErrorMessage,
 	isClinePassSubscriptionError,
 } from "./cline-pass-errors";
 
@@ -46,4 +49,22 @@ describe("cline-pass-errors", () => {
 		).toBe(true);
 		expect(formatCliErrorMessage(new Error(raw))).toBe(formatted);
 	});
+
+	it("recognizes and formats ClinePass period limit errors with usage-billing guidance", () => {
+		const raw =
+			"Error: You have reached your 5-hour Clinepass limit. The limit resets in 5h, please try again later.";
+		const detail =
+			"You have reached your 5-hour Clinepass limit. The limit resets in 5h, please try again later.";
+
+		expect(isClinePassLimitErrorMessage(raw)).toBe(true);
+		expect(isClinePassLimitErrorMessage(new Error(raw))).toBe(true);
+		expect(getClinePassLimitDetailMessage(raw)).toBe(detail);
+		expect(formatCliErrorMessage(new Error(raw))).toBe(
+			getCliClinePassLimitMessage(raw),
+		);
+		expect(formatCliErrorMessage(new Error(raw))).toContain(
+			"Switch to Cline usage-based billing",
+		);
+		expect(formatCliErrorMessage(new Error(raw))).toContain("--provider cline");
+	});
 });

apps/cli/src/utils/cline-pass-errors.ts

@@ -1,10 +1,13 @@
 import {
 	type ClineSubscriptionPlan,
+	extractClinePassLimitMessage,
 	getClineOrgIndividualInferenceSubscriptionMessage,
 	isClineNotSubscribedError,
 	isClineNotSubscribedMessage,
 	isClineOrgIndividualInferenceSubscriptionError,
 	isClineOrgIndividualInferenceSubscriptionMessage,
+	isClinePassLimitError,
+	isClinePassLimitMessage,
 } from "@cline/core";
 
 import { getClineEnvironmentConfig } from "@cline/shared";
@@ -24,6 +27,18 @@ export function getCliNotSubscribedMessage(): string {
 	return `No access to ClinePass subscription models yet. Subscribe to ClinePass, the low cost open weights model coding plan: ${getCliSubscriptionUrl()}`;
 }
 
+export function getCliClinePassLimitMessage(message: string): string {
+	const detail = getClinePassLimitDetailMessage(message) ?? message.trim();
+	const lines = [
+		"ClinePass limit reached",
+		detail,
+		"Switch to Cline usage-based billing and retry with the Cline provider.",
+		"Interactive CLI: open the model selector with /model, choose Cline, then retry.",
+		"Headless CLI: rerun with --provider cline.",
+	];
+	return lines.filter((line) => line.trim().length > 0).join("\n");
+}
+
 export function getIndividualPlanFeatures(
 	plans: ClineSubscriptionPlan[],
 ): string[] {
@@ -78,6 +93,27 @@ export function isClineOrgIndividualInferenceSubscriptionErrorMessage(
 	);
 }
 
+export function getClinePassLimitDetailMessage(
+	error: unknown,
+): string | undefined {
+	return extractClinePassLimitMessage(
+		error instanceof Error ? error.message : String(error),
+	);
+}
+
+export function isClinePassLimitErrorMessage(error: unknown): boolean {
+	if (isClinePassLimitError(error)) {
+		return true;
+	}
+	if (error instanceof Error) {
+		return (
+			error.name === "ClinePassLimitError" ||
+			isClinePassLimitMessage(error.message)
+		);
+	}
+	return typeof error === "string" && isClinePassLimitMessage(error);
+}
+
 export function formatCliErrorMessage(error: unknown): string {
 	if (isClinePassSubscriptionError(error)) {
 		return getCliNotSubscribedMessage();
@@ -85,6 +121,11 @@ export function formatCliErrorMessage(error: unknown): string {
 	if (isClineOrgIndividualInferenceSubscriptionErrorMessage(error)) {
 		return getClineOrgIndividualInferenceSubscriptionMessage();
 	}
+	if (isClinePassLimitErrorMessage(error)) {
+		return getCliClinePassLimitMessage(
+			error instanceof Error ? error.message : String(error),
+		);
+	}
 	if (error instanceof Error) {
 		return error.message;
 	}

apps/cli/src/utils/compaction-mode.test.ts

@@ -26,20 +26,20 @@ describe("CLI compaction mode helpers", () => {
 	});
 
 	it("maps basic and off modes to core compaction config", () => {
-		const config = createConfig({ enabled: true, maxInputTokens: 123 });
+		const config = createConfig({ enabled: true, preserveRecentTokens: 123 });
 
 		applyCliCompactionMode(config, "basic");
 		expect(config.compaction).toEqual({
 			enabled: true,
 			strategy: "basic",
-			maxInputTokens: 123,
+			preserveRecentTokens: 123,
 		});
 		expect(getCliCompactionMode(config)).toBe("basic");
 
 		applyCliCompactionMode(config, "off");
 		expect(config.compaction).toEqual({
 			enabled: false,
-			maxInputTokens: 123,
+			preserveRecentTokens: 123,
 		});
 		expect(getCliCompactionMode(config)).toBe("off");
 	});

apps/cli/src/utils/events.test.ts

@@ -1,19 +1,64 @@
 import type { AgentEvent, TeamEvent } from "@cline/core";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { handleEvent, handleTeamEvent } from "./events";
+import {
+	handleEvent,
+	handleTeamEvent,
+	resolveStatusNoticeLabel,
+} from "./events";
 import { setCurrentOutputMode } from "./output";
 import type { Config } from "./types";
 
+describe("resolveStatusNoticeLabel", () => {
+	it("maps compaction status reasons to stable labels", () => {
+		expect(
+			resolveStatusNoticeLabel({
+				type: "notice",
+				noticeType: "status",
+				displayRole: "status",
+				message: "auto-compacting",
+				reason: "auto_compaction",
+			} as AgentEvent),
+		).toBe("auto-compacting");
+		expect(
+			resolveStatusNoticeLabel({
+				type: "notice",
+				noticeType: "status",
+				displayRole: "status",
+				message: "manual",
+				reason: "manual_compaction",
+			} as AgentEvent),
+		).toBe("compacting");
+		expect(
+			resolveStatusNoticeLabel({
+				type: "notice",
+				noticeType: "status",
+				displayRole: "status",
+				message: "compaction-budget-adjusted",
+				reason: "compaction_budget_emergency",
+			} as AgentEvent),
+		).toBe("context budget adjusted");
+	});
+});
+
 describe("handleEvent text formatting", () => {
 	let output = "";
+	let errorOutput = "";
 
 	beforeEach(() => {
 		output = "";
+		errorOutput = "";
 		setCurrentOutputMode("text");
 		vi.spyOn(process.stdout, "write").mockImplementation((chunk: unknown) => {
 			output += String(chunk);
 			return true;
 		});
+		vi.spyOn(process.stderr, "write").mockImplementation((chunk: unknown) => {
+			errorOutput += String(chunk);
+			return true;
+		});
+		vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+			errorOutput += `${args.map(String).join(" ")}\n`;
+		});
 	});
 
 	it("adds a ⎿ before text that follows a tool block", () => {
@@ -160,6 +205,23 @@ describe("handleEvent text formatting", () => {
 		expect(output).toContain("── aborted (2 iterations) ──");
 	});
 
+	it("formats ClinePass limit agent errors before writing to stderr", () => {
+		handleEvent(
+			{
+				type: "error",
+				error: new Error(
+					"Error: You have reached your 5-hour Clinepass limit. The limit resets in 5h, please try again later.",
+				),
+				recoverable: false,
+			} as unknown as AgentEvent,
+			{} as Config,
+		);
+
+		expect(errorOutput).toContain("ClinePass limit reached");
+		expect(errorOutput).toContain("Switch to Cline usage-based billing");
+		expect(errorOutput).toContain("--provider cline");
+	});
+
 	it("suppresses heartbeat-only team progress messages", () => {
 		handleTeamEvent({
 			type: "run_progress",

apps/cli/src/utils/events.ts

@@ -1,4 +1,9 @@
 import type { AgentEvent, TeamEvent } from "@cline/core";
+import {
+	formatCompactionDividerLabel,
+	parseCompactionNoticeMetadata,
+} from "../tui/utils/compaction-status";
+import { formatCliErrorMessage } from "./cline-pass-errors";
 import { formatToolInput, formatToolOutput, truncate } from "./helpers";
 import {
 	c,
@@ -27,8 +32,31 @@ export function resolveStatusNoticeLabel(
 	if (event.type !== "notice" || event.displayRole !== "status") {
 		return undefined;
 	}
-	if (event.reason === "auto_compaction") {
-		return "auto-compacting";
+	const compaction = parseCompactionNoticeMetadata(event.metadata);
+	if (compaction) {
+		return formatCompactionDividerLabel({ kind: "compaction", ...compaction });
+	}
+	return resolveNonCompactionStatusLabel(event);
+}
+
+/**
+ * Label for a status notice already known not to be a compaction notice.
+ * Callers that have parsed the compaction metadata themselves use this to
+ * avoid re-parsing.
+ */
+export function resolveNonCompactionStatusLabel(
+	event: AgentEvent,
+): string | undefined {
+	if (event.type !== "notice" || event.displayRole !== "status") {
+		return undefined;
+	}
+	switch (event.reason) {
+		case "auto_compaction":
+			return "auto-compacting";
+		case "manual_compaction":
+			return "compacting";
+		case "compaction_budget_emergency":
+			return "context budget adjusted";
 	}
 	return event.message.trim() || undefined;
 }
@@ -176,7 +204,7 @@ export function handleEvent(event: AgentEvent, config: Config): void {
 		case "error":
 			closeInlineStreamIfNeeded();
 			if (!event.recoverable || config.verbose) {
-				writeErr(event.error.message);
+				writeErr(formatCliErrorMessage(event.error));
 			}
 			break;
 		case "notice":

apps/cli/src/utils/provider-auth.ts

@@ -42,11 +42,12 @@ export function getPersistedProviderApiKey(
  * or endpoint config for the provider. Used by the picker to decide whether
  * to offer "Use existing configuration?" before opening the configure dialog.
  *
- * Treats OAuth providers as configured when an access token is present; for
- * everything else, any persisted API key, base URL, or model id counts. We
- * don't enforce required fields here — the runtime no longer pre-flights
- * credentials, so a missing key only matters when the API call actually
- * runs and the provider's own auth error is surfaced.
+ * Treats OAuth providers as configured when an access token or a manually
+ * saved API key is present (the /settings escape hatch for when OAuth isn't
+ * working); for everything else, any persisted API key, base URL, or model id
+ * counts. We don't enforce required fields here — the runtime no longer
+ * pre-flights credentials, so a missing key only matters when the API call
+ * actually runs and the provider's own auth error is surfaced.
  */
 export function isProviderConfigured(
 	providerId: string,
@@ -54,7 +55,8 @@ export function isProviderConfigured(
 ): boolean {
 	if (!settings) return false;
 	if (isOAuthProvider(providerId)) {
-		return Boolean(settings.auth?.accessToken?.trim());
+		// getPersistedProviderApiKey covers both auth.accessToken and apiKey.
+		return Boolean(getPersistedProviderApiKey(providerId, settings));
 	}
 	if (getPersistedProviderApiKey(providerId, settings)) return true;
 	if (settings.baseUrl?.trim()) return true;

apps/cline-hub/src/server/user-instructions.ts

@@ -18,6 +18,7 @@ import {
 	resolvePluginConfigSearchPaths,
 	resolveAgentConfigSearchPaths as resolveSharedAgentConfigSearchPaths,
 } from "@cline/core";
+import { readFileSyncStrippingUtf8Bom } from "@cline/shared/node";
 import { readMcpServersResponse } from "./mcp";
 import type { JsonRecord } from "./types";
 
@@ -114,7 +115,7 @@ export async function listUserInstructionConfigs(
 					const ext = extname(entry.name).toLowerCase();
 					if (ext !== ".yml" && ext !== ".yaml") continue;
 					const filePath = join(directory, entry.name);
-					const raw = readFileSync(filePath, "utf8");
+					const raw = readFileSyncStrippingUtf8Bom(filePath);
 					const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
 					const fm = fmMatch?.[1] ?? "";
 					const nameMatch = fm.match(/^\s*name:\s*(.+?)\s*$/m);

apps/cline-hub/src/webview/src/components/ai-elements/streamdown.tsx

@@ -20,10 +20,13 @@ import { cn } from "@/lib/utils";
 
 type MarkdownCodeProps = ComponentProps<"code"> & {
 	"data-block"?: boolean | string;
+	// react-markdown/streamdown pass the hast `Element` here, whose
+	// `properties` is a broad `Record`. Keep this assignable from that type
+	// (rather than a narrow `{ metastring?: string }`) so the component stays
+	// compatible with `Components` regardless of how strict the resolved
+	// hast/streamdown types are; the metastring value is validated at read time.
 	node?: {
-		properties?: {
-			metastring?: string;
-		};
+		properties?: Record<string, unknown>;
 	};
 };
 
@@ -67,7 +70,8 @@ const MarkdownCode = ({
 		);
 	}
 
-	const meta = node?.properties?.metastring;
+	const metaValue = node?.properties?.metastring;
+	const meta = typeof metaValue === "string" ? metaValue : undefined;
 	const startLineMatch = meta?.match(START_LINE_PATTERN);
 	const startLine = startLineMatch ? Number.parseInt(startLineMatch[1], 10) : 1;
 	const showLineNumbers = meta ? !NO_LINE_NUMBERS_PATTERN.test(meta) : true;

apps/examples/desktop-app/README.md

@@ -16,6 +16,15 @@ From `apps/examples/desktop-app/`:
 - `bun run package:desktop` - package the current OS desktop app into `dist/desktop/`
 - `bun run typecheck` - TypeScript check
 
+## Web Visual System
+
+The framework-neutral color, typography, radius, and navigation contract lives
+in the internal [`@cline/ui`](../../../sdk/packages/ui/README.md) workspace
+package. Other Cline web surfaces can take only its tokens or opt into the
+Tailwind adapter and shared base styles without depending on the desktop
+runtime. See [`webview/styles/README.md`](./webview/styles/README.md) for the
+desktop integration notes.
+
 ## Shareable Desktop Packages
 
 Tauri desktop bundles are OS-specific, so build each package on the target OS:

apps/examples/desktop-app/package.json

@@ -24,7 +24,9 @@
 		"@cline/core": "workspace:*",
 		"@cline/llms": "workspace:*",
 		"@cline/shared": "workspace:*",
-		"@fontsource-variable/geist": "^5.2.8",
+		"@cline/ui": "workspace:*",
+		"@fontsource-variable/schibsted-grotesk": "^5.2.8",
+		"@fontsource/azeret-mono": "^5.2.9",
 		"@hookform/resolvers": "^3.9.1",
 		"@radix-ui/react-accordion": "1.2.12",
 		"@radix-ui/react-alert-dialog": "1.1.15",
@@ -53,6 +55,9 @@
 		"@radix-ui/react-toggle": "1.1.10",
 		"@radix-ui/react-toggle-group": "1.1.11",
 		"@radix-ui/react-tooltip": "1.2.8",
+		"@shikijs/langs": "^4.2.0",
+		"@shikijs/themes": "^4.2.0",
+		"@streamdown/cjk": "^1.0.3",
 		"@tauri-apps/api": "^2.0.0",
 		"@vercel/analytics": "1.6.1",
 		"autoprefixer": "^10.4.20",
@@ -63,7 +68,6 @@
 		"embla-carousel-react": "8.6.0",
 		"input-otp": "1.4.2",
 		"lucide-react": "^0.564.0",
-		"marked": "^17.0.3",
 		"next": "16.2.6",
 		"next-themes": "^0.4.6",
 		"radix-ui": "^1.4.3",
@@ -71,11 +75,11 @@
 		"react-day-picker": "9.13.2",
 		"react-dom": "19.2.4",
 		"react-hook-form": "^7.54.1",
-		"react-markdown": "^10.1.0",
 		"react-resizable-panels": "^2.1.7",
 		"recharts": "2.15.0",
-		"remark-gfm": "^4.0.1",
+		"shiki": "^4.0.2",
 		"sonner": "^1.7.1",
+		"streamdown": "^2.5.0",
 		"tailwind-merge": "^3.3.1",
 		"vaul": "^1.1.2",
 		"zod": "^3.24.1"
@@ -85,6 +89,7 @@
 		"@tailwindcss/postcss": "^4.2.0",
 		"@types/react": "19.2.14",
 		"@types/react-dom": "19.2.3",
+		"jsdom": "^26.0.0",
 		"postcss": "^8.5",
 		"tailwindcss": "^4.2.0",
 		"tw-animate-css": "1.3.3",

apps/examples/desktop-app/sidecar/chat-session.test.ts

@@ -1,5 +1,13 @@
-import { describe, expect, it } from "vitest";
-import { buildSessionConnectionUpdate } from "./chat-session";
+import { describe, expect, it, vi } from "vitest";
+import {
+	buildSessionConnectionUpdate,
+	consumeWorkspaceMetadata,
+	handleChatSessionCommand,
+	prewarmWorkspaceMetadata,
+	shouldUpdateSessionConnection,
+	WORKSPACE_METADATA_PREWARM_TTL_MS,
+} from "./chat-session";
+import type { SidecarContext } from "./types";
 
 describe("buildSessionConnectionUpdate", () => {
 	it("does not clear reasoning settings when config omits reasoning fields", () => {
@@ -49,3 +57,188 @@ describe("buildSessionConnectionUpdate", () => {
 		expect(Object.hasOwn(update, "thinkingBudgetTokens")).toBe(false);
 	});
 });
+
+describe("shouldUpdateSessionConnection", () => {
+	it("skips the redundant connection update on the first send", () => {
+		const config = {
+			provider: "cline",
+			model: "anthropic/claude-sonnet-4.6",
+			thinking: true,
+			reasoningEffort: "high",
+		};
+
+		expect(shouldUpdateSessionConnection(config, { ...config })).toBe(false);
+	});
+
+	it("updates the connection when the selected reasoning level changes", () => {
+		const current = {
+			provider: "cline",
+			model: "anthropic/claude-sonnet-4.6",
+			thinking: true,
+			reasoningEffort: "low",
+		};
+
+		expect(
+			shouldUpdateSessionConnection(current, {
+				...current,
+				reasoningEffort: "high",
+			}),
+		).toBe(true);
+	});
+});
+
+describe("first-send connection updates", () => {
+	const baseConfig = {
+		provider: "cline",
+		model: "anthropic/claude-sonnet-4.6",
+		thinking: true,
+		reasoningEffort: "high",
+	};
+
+	function createContext(options?: {
+		attachedViaHub?: boolean;
+		config?: Record<string, unknown>;
+	}) {
+		const updateSessionConnection = vi.fn(async () => undefined);
+		const send = vi.fn(async () => ({
+			text: "done",
+			finishReason: "completed",
+			messages: [],
+		}));
+		const sessionId = "session-connection-test";
+		const ctx = {
+			liveSessions: new Map([
+				[
+					sessionId,
+					{
+						config: options?.config ?? baseConfig,
+						messages: [],
+						promptsInQueue: [],
+						busy: false,
+						startedAt: Date.now(),
+						status: "idle",
+						attachedViaHub: options?.attachedViaHub ?? false,
+					},
+				],
+			]),
+			sessionManager: { send, updateSessionConnection },
+		} as unknown as SidecarContext;
+		return { ctx, send, sessionId, updateSessionConnection };
+	}
+
+	it("skips an identical update for a locally-created session", async () => {
+		const { ctx, send, sessionId, updateSessionConnection } = createContext();
+
+		await handleChatSessionCommand(ctx, {
+			action: "send",
+			sessionId,
+			prompt: "hello",
+			config: { ...baseConfig },
+		});
+
+		expect(updateSessionConnection).not.toHaveBeenCalled();
+		expect(send).toHaveBeenCalledTimes(1);
+	});
+
+	it("updates a changed connection before sending", async () => {
+		const { ctx, send, sessionId, updateSessionConnection } = createContext({
+			config: { ...baseConfig, reasoningEffort: "low" },
+		});
+
+		await handleChatSessionCommand(ctx, {
+			action: "send",
+			sessionId,
+			prompt: "hello",
+			config: { ...baseConfig },
+		});
+
+		expect(updateSessionConnection).toHaveBeenCalledTimes(1);
+		expect(updateSessionConnection.mock.invocationCallOrder[0]).toBeLessThan(
+			send.mock.invocationCallOrder[0] ?? 0,
+		);
+	});
+
+	it("refreshes hub-attached sessions even when the cached config matches", async () => {
+		const { ctx, sessionId, updateSessionConnection } = createContext({
+			attachedViaHub: true,
+		});
+
+		await handleChatSessionCommand(ctx, {
+			action: "send",
+			sessionId,
+			prompt: "hello",
+			config: { ...baseConfig },
+		});
+
+		expect(updateSessionConnection).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe("workspace metadata prewarming", () => {
+	it("reuses one in-flight scan and consumes it only once", async () => {
+		let resolveFirst: ((value: string) => void) | undefined;
+		const firstResult = new Promise<string>((resolve) => {
+			resolveFirst = resolve;
+		});
+		const load = vi
+			.fn<(cwd: string) => Promise<string>>()
+			.mockImplementationOnce(async () => await firstResult)
+			.mockResolvedValueOnce("fresh metadata");
+		const cwd = "/tmp/cline-desktop-prewarm-reuse";
+
+		prewarmWorkspaceMetadata(cwd, load);
+		const consumed = consumeWorkspaceMetadata(cwd, load);
+		expect(load).toHaveBeenCalledTimes(1);
+		resolveFirst?.("prewarmed metadata");
+
+		await expect(consumed).resolves.toBe("prewarmed metadata");
+		await expect(consumeWorkspaceMetadata(cwd, load)).resolves.toBe(
+			"fresh metadata",
+		);
+		expect(load).toHaveBeenCalledTimes(2);
+	});
+
+	it("evicts failed scans so the next session can retry", async () => {
+		const load = vi
+			.fn<(cwd: string) => Promise<string>>()
+			.mockRejectedValueOnce(new Error("git unavailable"))
+			.mockResolvedValueOnce("recovered metadata");
+		const cwd = "/tmp/cline-desktop-prewarm-retry";
+
+		prewarmWorkspaceMetadata(cwd, load);
+		await expect(consumeWorkspaceMetadata(cwd, load)).rejects.toThrow(
+			"git unavailable",
+		);
+		await expect(consumeWorkspaceMetadata(cwd, load)).resolves.toBe(
+			"recovered metadata",
+		);
+		expect(load).toHaveBeenCalledTimes(2);
+	});
+
+	it("keeps different workspaces in separate single-flight entries", () => {
+		const load = vi.fn(async (cwd: string) => `metadata for ${cwd}`);
+
+		prewarmWorkspaceMetadata("/tmp/cline-desktop-prewarm-a", load);
+		prewarmWorkspaceMetadata("/tmp/cline-desktop-prewarm-b", load);
+
+		expect(load).toHaveBeenCalledTimes(2);
+	});
+
+	it("refreshes a prewarm that is older than the startup window", async () => {
+		const load = vi
+			.fn<(cwd: string) => Promise<string>>()
+			.mockResolvedValueOnce("startup metadata")
+			.mockResolvedValueOnce("current metadata");
+		const cwd = "/tmp/cline-desktop-prewarm-expired";
+
+		prewarmWorkspaceMetadata(cwd, load, () => 0);
+		await expect(
+			consumeWorkspaceMetadata(
+				cwd,
+				load,
+				() => WORKSPACE_METADATA_PREWARM_TTL_MS + 1,
+			),
+		).resolves.toBe("current metadata");
+		expect(load).toHaveBeenCalledTimes(2);
+	});
+});

apps/examples/desktop-app/sidecar/chat-session.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import {
+	buildConnectionUpdate,
 	buildWorkspaceMetadata,
 	type ClineCore,
 	type CoreSessionConfig,
@@ -24,6 +26,69 @@ type SessionConnectionUpdate = Parameters<
 	ClineCore["updateSessionConnection"]
 >[1];
 
+type WorkspaceMetadataLoader = (cwd: string) => Promise<string>;
+type WorkspaceMetadataCacheEntry = {
+	createdAt: number;
+	promise: Promise<string>;
+};
+export const WORKSPACE_METADATA_PREWARM_TTL_MS = 60_000;
+const workspaceMetadataPromises = new Map<
+	string,
+	WorkspaceMetadataCacheEntry
+>();
+
+function getWorkspaceMetadataPromise(
+	cwd: string,
+	load: WorkspaceMetadataLoader,
+	now: () => number,
+): { key: string; promise: Promise<string> } {
+	const key = resolve(cwd);
+	const existing = workspaceMetadataPromises.get(key);
+	const createdAt = now();
+	if (
+		existing &&
+		createdAt - existing.createdAt <= WORKSPACE_METADATA_PREWARM_TTL_MS
+	) {
+		return { key, promise: existing.promise };
+	}
+	const promise = load(key);
+	workspaceMetadataPromises.set(key, { createdAt, promise });
+	void promise.catch(() => {
+		if (workspaceMetadataPromises.get(key)?.promise === promise) {
+			workspaceMetadataPromises.delete(key);
+		}
+	});
+	return { key, promise };
+}
+
+export function prewarmWorkspaceMetadata(
+	cwd: string,
+	load: WorkspaceMetadataLoader = buildWorkspaceMetadata,
+	now: () => number = Date.now,
+): void {
+	void getWorkspaceMetadataPromise(cwd, load, now).promise.catch(() => {});
+}
+
+export async function consumeWorkspaceMetadata(
+	cwd: string,
+	load: WorkspaceMetadataLoader = buildWorkspaceMetadata,
+	now: () => number = Date.now,
+): Promise<string> {
+	const { key, promise } = getWorkspaceMetadataPromise(cwd, load, now);
+	try {
+		return await promise;
+	} finally {
+		if (workspaceMetadataPromises.get(key)?.promise === promise) {
+			workspaceMetadataPromises.delete(key);
+		}
+	}
+}
+
+export function refreshWorkspaceMetadata(cwd: string): void {
+	workspaceMetadataPromises.delete(resolve(cwd));
+	prewarmWorkspaceMetadata(cwd);
+}
+
 // ---------------------------------------------------------------------------
 // Session data helpers
 // ---------------------------------------------------------------------------
@@ -179,58 +244,53 @@ function buildCoreSessionConfig(config: JsonRecord): JsonRecord {
 export function buildSessionConnectionUpdate(
 	config: JsonRecord,
 ): SessionConnectionUpdate {
-	const thinking =
-		typeof config.thinking === "boolean" ? config.thinking : undefined;
-	const reasoningEffort = readReasoningEffort(config.reasoningEffort);
-	const thinkingBudgetTokens = readPositiveInteger(
-		config.thinkingBudgetTokens ?? config.thinking_budget_tokens,
-	);
-	const updates: SessionConnectionUpdate = {};
+	// Coerce the untrusted webview JSON (snake_case aliases, blank strings)
+	// into typed fields; the thinking/reasoning transition rules live in the
+	// shared @cline/core builder.
 	const providerId = String(config.provider ?? config.providerId ?? "").trim();
-	if (providerId) {
-		updates.providerId = providerId;
-	}
 	const modelId = String(config.model ?? config.modelId ?? "").trim();
-	if (modelId) {
-		updates.modelId = modelId;
-	}
-	const apiKey =
+	const rawApiKey =
 		typeof config.apiKey === "string"
 			? config.apiKey.trim()
 			: typeof config.api_key === "string"
 				? config.api_key.trim()
 				: undefined;
-	if (apiKey) {
-		updates.apiKey = apiKey;
-	}
-	if (typeof config.baseUrl === "string" && config.baseUrl.trim()) {
-		updates.baseUrl = config.baseUrl.trim();
-	}
-	if (config.headers && typeof config.headers === "object") {
-		updates.headers = config.headers as Record<string, string>;
-	}
-	if (config.providerConfig && typeof config.providerConfig === "object") {
-		updates.providerConfig =
-			config.providerConfig as SessionConnectionUpdate["providerConfig"];
-	}
-	if (thinking === false) {
-		updates.thinking = false;
-		updates.reasoningEffort = null;
-		updates.thinkingBudgetTokens = null;
-		return updates;
-	}
-	if (thinking === true) {
-		updates.thinking = true;
-	}
-	if (reasoningEffort) {
-		updates.thinking = true;
-		updates.reasoningEffort = reasoningEffort;
-	}
-	if (thinkingBudgetTokens !== undefined) {
-		updates.thinking = true;
-		updates.thinkingBudgetTokens = thinkingBudgetTokens;
-	}
-	return updates;
+	const baseUrl =
+		typeof config.baseUrl === "string" ? config.baseUrl.trim() : undefined;
+	const reasoningEffort = readReasoningEffort(config.reasoningEffort);
+	const thinkingBudgetTokens = readPositiveInteger(
+		config.thinkingBudgetTokens ?? config.thinking_budget_tokens,
+	);
+	return buildConnectionUpdate({
+		...(providerId ? { providerId } : {}),
+		...(modelId ? { modelId } : {}),
+		...(rawApiKey ? { apiKey: rawApiKey } : {}),
+		...(baseUrl ? { baseUrl } : {}),
+		...(config.headers && typeof config.headers === "object"
+			? { headers: config.headers as Record<string, string> }
+			: {}),
+		...(config.providerConfig && typeof config.providerConfig === "object"
+			? {
+					providerConfig:
+						config.providerConfig as SessionConnectionUpdate["providerConfig"],
+				}
+			: {}),
+		...(typeof config.thinking === "boolean"
+			? { thinking: config.thinking }
+			: {}),
+		...(reasoningEffort ? { reasoningEffort } : {}),
+		...(thinkingBudgetTokens !== undefined ? { thinkingBudgetTokens } : {}),
+	});
+}
+
+export function shouldUpdateSessionConnection(
+	currentConfig: JsonRecord,
+	nextConfig: JsonRecord,
+): boolean {
+	return !isDeepStrictEqual(
+		buildSessionConnectionUpdate(currentConfig),
+		buildSessionConnectionUpdate(nextConfig),
+	);
 }
 
 async function resolveSystemPrompt(config: JsonRecord): Promise<string> {
@@ -246,7 +306,7 @@ async function resolveSystemPrompt(config: JsonRecord): Promise<string> {
 		: config.mode === "plan"
 			? "plan"
 			: "act";
-	const metadata = await buildWorkspaceMetadata(cwd);
+	const metadata = await consumeWorkspaceMetadata(cwd);
 	const inlineRules =
 		typeof config.rules === "string" && config.rules.trim().length > 0
 			? config.rules
@@ -461,8 +521,14 @@ async function handleSend(
 	const manager = getSessionManager(ctx);
 	const session = ctx.liveSessions.get(sessionId);
 	if (request.config) {
-		const connectionUpdate = buildSessionConnectionUpdate(request.config);
-		await manager.updateSessionConnection(sessionId, connectionUpdate);
+		if (
+			!session ||
+			session.attachedViaHub ||
+			shouldUpdateSessionConnection(session.config, request.config)
+		) {
+			const connectionUpdate = buildSessionConnectionUpdate(request.config);
+			await manager.updateSessionConnection(sessionId, connectionUpdate);
+		}
 		if (session) {
 			session.config = { ...session.config, ...request.config };
 		}

apps/examples/desktop-app/sidecar/commands.ts

@@ -1,5 +1,12 @@
 import { execFileSync, spawn } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import {
+	existsSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	statSync,
+} from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, extname, join } from "node:path";
 import type {
 	ClineAccountActionRequest,
@@ -28,6 +35,7 @@ import {
 	markLocalProviderEnabled,
 	normalizeOAuthProvider,
 	ProviderSettingsManager,
+	RuntimeOAuthTokenManager,
 	readGlobalSettings,
 	resolveLocalClineAuthToken,
 	resolvePluginConfigSearchPaths,
@@ -44,6 +52,8 @@ import {
 	updateMcpSettingsFileSync,
 } from "@cline/core";
 import { getClineEnvironmentConfig } from "@cline/shared";
+import { readFileSyncStrippingUtf8Bom } from "@cline/shared/node";
+import packageJson from "../package.json";
 import {
 	connectorChannelsPayload,
 	startConnectorChannel,
@@ -178,6 +188,31 @@ function removePathIfExists(
 	return true;
 }
 
+// Cline access tokens expire between app launches, so account requests must
+// resolve through the refresh-aware OAuth manager instead of reading the
+// persisted token directly. A single shared instance keeps concurrent account
+// requests single-flight; the refresh token is single-use, so parallel
+// refreshes would invalidate each other.
+let clineOAuthTokenManager: RuntimeOAuthTokenManager | undefined;
+
+async function resolveFreshClineAuthToken(
+	manager: ProviderSettingsManager,
+): Promise<string | undefined> {
+	try {
+		clineOAuthTokenManager ??= new RuntimeOAuthTokenManager();
+		const resolution = await clineOAuthTokenManager.resolveProviderApiKey({
+			providerId: "cline",
+		});
+		if (resolution?.apiKey) {
+			return resolution.apiKey;
+		}
+	} catch {
+		// Fall back to the persisted token; the account request surfaces the
+		// auth failure to the caller.
+	}
+	return resolveLocalClineAuthToken(manager.getProviderSettings("cline"));
+}
+
 async function listSessionsFromSidecarManager(
 	ctx: SidecarContext,
 	limit: number,
@@ -552,7 +587,7 @@ async function listUserInstructionConfigs(
 					const ext = extname(entry.name).toLowerCase();
 					if (ext !== ".yml" && ext !== ".yaml") continue;
 					const filePath = join(directory, entry.name);
-					const raw = readFileSync(filePath, "utf8");
+					const raw = readFileSyncStrippingUtf8Bom(filePath);
 					const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
 					const fm = fmMatch?.[1] ?? "";
 					const nameMatch = fm.match(/^\s*name:\s*(.+?)\s*$/m);
@@ -750,7 +785,13 @@ export async function handleCommand(
 
 	// ── Process context ───────────────────────────────────────────────
 	if (command === "get_process_context") {
-		return { workspaceRoot: ctx.workspaceRoot, cwd: ctx.workspaceRoot };
+		return {
+			workspaceRoot: ctx.workspaceRoot,
+			cwd: ctx.workspaceRoot,
+			homeDir: homedir(),
+			platform: process.platform,
+			appVersion: packageJson.version,
+		};
 	}
 	if (command === "get_chat_ws_endpoint") {
 		return "";
@@ -947,7 +988,7 @@ export async function handleCommand(
 		const accountService = new ClineAccountService({
 			apiBaseUrl:
 				settings?.baseUrl?.trim() || getClineEnvironmentConfig().apiBaseUrl,
-			getAuthToken: async () => resolveLocalClineAuthToken(settings),
+			getAuthToken: async () => resolveFreshClineAuthToken(manager),
 		});
 		return await executeClineAccountAction(
 			args as ClineAccountActionRequest,
@@ -1163,10 +1204,13 @@ export async function handleCommand(
 
 	// ── Git operations ─────────────────────────────────────────────────
 	if (command === "get_git_branch") {
-		const branches = listGitBranches(
-			ctx,
-			typeof args?.cwd === "string" ? args.cwd : undefined,
-		);
+		const cwd =
+			typeof args?.cwd === "string" && args.cwd.trim()
+				? args.cwd.trim()
+				: ctx.workspaceRoot;
+		const branches = listGitBranches(ctx, cwd);
+		const { prewarmWorkspaceMetadata } = await import("./chat-session");
+		prewarmWorkspaceMetadata(cwd);
 		return { branch: branches.current };
 	}
 	if (command === "list_git_branches") {
@@ -1179,11 +1223,14 @@ export async function handleCommand(
 		const cwd = typeof args?.cwd === "string" ? args.cwd : undefined;
 		const branch = String(args?.branch ?? "").trim();
 		if (!branch) throw new Error("branch is required");
+		const targetCwd = cwd?.trim() || ctx.workspaceRoot;
 		execFileSync("git", ["checkout", branch], {
-			cwd: cwd?.trim() || ctx.workspaceRoot,
+			cwd: targetCwd,
 			encoding: "utf8",
 			stdio: ["ignore", "pipe", "pipe"],
 		});
+		const { refreshWorkspaceMetadata } = await import("./chat-session");
+		refreshWorkspaceMetadata(targetCwd);
 		return { branch };
 	}
 
@@ -1252,6 +1299,15 @@ export async function handleCommand(
 	}
 
 	// ── Native OS commands ────────────────────────────────────────────
+	if (command === "validate_workspace_directory") {
+		const workspacePath = String(args?.path ?? "").trim();
+		if (!workspacePath) return { valid: false };
+		try {
+			return { valid: statSync(workspacePath).isDirectory() };
+		} catch {
+			return { valid: false };
+		}
+	}
 	if (command === "pick_workspace_directory") {
 		return pickWorkspaceDirectory();
 	}

apps/examples/desktop-app/sidecar/index.ts

@@ -1,3 +1,4 @@
+import { prewarmWorkspaceMetadata } from "./chat-session";
 import {
 	createSidecarContext,
 	disposeSidecarContext,
@@ -5,7 +6,7 @@ import {
 } from "./context";
 import { resolveWorkspaceRoot } from "./paths";
 import { startServer } from "./server";
-import { BunRuntime, SIDECAR_MODE, SIDECAR_PORT } from "./types";
+import { BunRuntime, SIDECAR_HOST, SIDECAR_MODE, SIDECAR_PORT } from "./types";
 
 const SHUTDOWN_TIMEOUT_MS = 5_000;
 
@@ -34,6 +35,7 @@ async function main() {
 	const workspaceRoot = resolveWorkspaceRoot(process.cwd());
 	const ctx = createSidecarContext(workspaceRoot);
 
+	prewarmWorkspaceMetadata(workspaceRoot);
 	await initializeSessionManager(ctx);
 
 	let shuttingDown = false;
@@ -59,8 +61,10 @@ async function main() {
 
 	const { port } = startServer(ctx, SIDECAR_PORT, shutdown);
 
-	const endpoint = `http://127.0.0.1:${port}`;
-	const wsEndpoint = `ws://127.0.0.1:${port}/transport`;
+	// A wildcard bind isn't a dialable address; advertise loopback instead.
+	const dialHost = SIDECAR_HOST === "0.0.0.0" ? "127.0.0.1" : SIDECAR_HOST;
+	const endpoint = `http://${dialHost}:${port}`;
+	const wsEndpoint = `ws://${dialHost}:${port}/transport`;
 	process.stdout.write(
 		`${JSON.stringify({
 			type: "ready",

apps/examples/desktop-app/sidecar/server.ts

@@ -4,6 +4,7 @@ import { sendEvent } from "./context";
 import { fetchMarketplaceCatalog } from "./marketplace";
 import {
 	BunRuntime,
+	SIDECAR_HOST,
 	SIDECAR_MODE,
 	SIDECAR_PORT,
 	type SidecarContext,
@@ -15,12 +16,20 @@ type SidecarServer = {
 	upgrade(req: Request): boolean;
 };
 
+// Comma-separated extra origins (e.g. a dev server on a nonstandard port when
+// the sidecar runs inside a container). Origin validation itself stays on.
+const EXTRA_TRUSTED_ORIGINS = (process.env.CLINE_SIDECAR_TRUSTED_ORIGINS ?? "")
+	.split(",")
+	.map((origin) => origin.trim())
+	.filter(Boolean);
+
 const TRUSTED_BROWSER_ORIGINS = new Set([
 	"tauri://localhost",
 	"http://tauri.localhost",
 	"https://tauri.localhost",
 	"http://localhost:3125",
 	"http://127.0.0.1:3125",
+	...EXTRA_TRUSTED_ORIGINS,
 ]);
 
 const JSON_HEADERS = {
@@ -115,7 +124,7 @@ export function startServer(
 	for (const candidate of candidates) {
 		try {
 			server = BunRuntime.serve({
-				hostname: "127.0.0.1",
+				hostname: SIDECAR_HOST,
 				port: candidate,
 				fetch: createFetchHandler(ctx, onShutdown),
 				websocket: createWebSocketHandler(ctx),

apps/examples/desktop-app/sidecar/types.ts

@@ -115,4 +115,8 @@ export type BunRuntimeApi = {
 export const BunRuntime = (globalThis as { Bun?: BunRuntimeApi }).Bun;
 
 export const SIDECAR_PORT = Number(process.env.CLINE_SIDECAR_PORT) || 3126;
+// Loopback-only by default. Set CLINE_SIDECAR_HOST=0.0.0.0 to accept
+// connections from outside the local host (e.g. Docker port publishing).
+export const SIDECAR_HOST =
+	process.env.CLINE_SIDECAR_HOST?.trim() || "127.0.0.1";
 export const SIDECAR_MODE = "sidecar";

apps/examples/desktop-app/src-tauri/Cargo.toml

@@ -9,7 +9,7 @@ tauri-build = { version = "2.0.0", features = [] }
 [dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-tauri = { version = "2.11.1", features = [] }
+tauri = { version = "2.11.1", features = ["macos-private-api", "tray-icon"] }
 rfd = "0.15"
 
 [features]

apps/examples/desktop-app/src-tauri/src/main.rs

@@ -8,7 +8,9 @@ use std::process::{Child, Command, Stdio};
 use std::sync::{Arc, Mutex};
 use std::thread;
 use std::time::Duration;
-use tauri::{Manager, RunEvent, State};
+use tauri::menu::{Menu, MenuItem};
+use tauri::tray::TrayIconBuilder;
+use tauri::{Manager, RunEvent, State, WindowEvent};
 
 #[derive(Clone)]
 struct AppContext {
@@ -473,6 +475,51 @@ fn open_mcp_settings_file() -> Result<String, String> {
     Ok(settings_path.to_string_lossy().to_string())
 }
 
+/// Begin an OS-level drag of the calling window (used by the floating pet so it
+/// can be dragged anywhere on screen without window decorations).
+#[tauri::command]
+fn start_pet_drag(window: tauri::WebviewWindow) -> Result<(), String> {
+    window.start_dragging().map_err(|e| e.to_string())
+}
+
+/// Show the floating pet window and (re)assert its always-on-top / all-Spaces
+/// presence so it floats above other apps even when the main window is hidden.
+#[tauri::command]
+fn show_pet(app: tauri::AppHandle) -> Result<(), String> {
+    if let Some(pet) = app.get_webview_window("pet") {
+        pet.show().map_err(|e| e.to_string())?;
+        let _ = pet.set_always_on_top(true);
+        let _ = pet.set_visible_on_all_workspaces(true);
+    }
+    Ok(())
+}
+
+/// Hide the floating pet window (its dismiss button and the settings toggle).
+#[tauri::command]
+fn hide_pet(app: tauri::AppHandle) -> Result<(), String> {
+    if let Some(pet) = app.get_webview_window("pet") {
+        pet.hide().map_err(|e| e.to_string())?;
+    }
+    Ok(())
+}
+
+#[tauri::command]
+fn is_pet_visible(app: tauri::AppHandle) -> bool {
+    app.get_webview_window("pet")
+        .and_then(|pet| pet.is_visible().ok())
+        .unwrap_or(false)
+}
+
+/// Bring the main window back after it was hidden by closing it.
+#[tauri::command]
+fn show_main_window(app: tauri::AppHandle) -> Result<(), String> {
+    if let Some(main) = app.get_webview_window("main") {
+        main.show().map_err(|e| e.to_string())?;
+        let _ = main.set_focus();
+    }
+    Ok(())
+}
+
 fn main() {
     let desktop_backend = Arc::new(DesktopBackendState::default());
     let launch_cwd = std::env::current_dir()
@@ -502,13 +549,63 @@ fn main() {
                     eprintln!("[desktop-backend] health check failed: {error}");
                 }
             });
+
+            // Tray icon so the app can keep running after the main window is
+            // closed, with explicit Show / Quit actions.
+            if let Some(icon) = app.default_window_icon().cloned() {
+                let show_item =
+                    MenuItem::with_id(app, "show_window", "Show Window", true, None::<&str>)?;
+                let quit_item =
+                    MenuItem::with_id(app, "quit", "Quit Cline Code", true, None::<&str>)?;
+                let tray_menu = Menu::with_items(app, &[&show_item, &quit_item])?;
+                TrayIconBuilder::with_id("cline-tray")
+                    .icon(icon)
+                    .tooltip("Cline Code")
+                    .menu(&tray_menu)
+                    .show_menu_on_left_click(true)
+                    .on_menu_event(|app, event| match event.id().as_ref() {
+                        "show_window" => {
+                            if let Some(main) = app.get_webview_window("main") {
+                                let _ = main.show();
+                                let _ = main.set_focus();
+                            }
+                        }
+                        "quit" => app.exit(0),
+                        _ => {}
+                    })
+                    .build(app)?;
+            }
+
+            // Keep the pet floating above other apps and on every Space, so it
+            // stays visible even when the main window is minimized or hidden.
+            if let Some(pet) = app.get_webview_window("pet") {
+                let _ = pet.set_always_on_top(true);
+                let _ = pet.set_visible_on_all_workspaces(true);
+            }
+
             Ok(())
         })
         .invoke_handler(tauri::generate_handler![
             get_desktop_backend_endpoint,
             pick_workspace_directory,
-            open_mcp_settings_file
+            open_mcp_settings_file,
+            start_pet_drag,
+            show_pet,
+            hide_pet,
+            is_pet_visible,
+            show_main_window
         ])
+        .on_window_event(|window, event| {
+            // Closing the main window hides it and keeps the app (and sidecar)
+            // running in the background; the tray or Dock reopens it, and
+            // Cmd+Q / the tray Quit item performs the real shutdown.
+            if let WindowEvent::CloseRequested { api, .. } = event {
+                if window.label() == "main" {
+                    api.prevent_close();
+                    let _ = window.hide();
+                }
+            }
+        })
         .build(tauri::generate_context!())
         .expect("error while building tauri app")
         .run(|app_handle, event| match event {
@@ -518,6 +615,13 @@ fn main() {
                     .inner()
                     .stop();
             }
+            // Clicking the Dock icon on macOS reopens the hidden main window.
+            RunEvent::Reopen { .. } => {
+                if let Some(main) = app_handle.get_webview_window("main") {
+                    let _ = main.show();
+                    let _ = main.set_focus();
+                }
+            }
             _ => {}
         });
 }

apps/examples/desktop-app/src-tauri/tauri.conf.json

@@ -10,6 +10,7 @@
 		"frontendDist": "../webview/out"
 	},
 	"app": {
+		"macOSPrivateApi": true,
 		"windows": [
 			{
 				"label": "main",
@@ -17,6 +18,21 @@
 				"width": 1500,
 				"height": 980,
 				"resizable": true
+			},
+			{
+				"label": "pet",
+				"title": "Nyan Pet",
+				"width": 184,
+				"height": 120,
+				"resizable": false,
+				"transparent": true,
+				"decorations": false,
+				"alwaysOnTop": true,
+				"skipTaskbar": true,
+				"shadow": false,
+				"focus": false,
+				"maximizable": false,
+				"minimizable": false
 			}
 		],
 		"security": {

apps/examples/desktop-app/vitest.config.ts

@@ -1,6 +1,12 @@
+import { fileURLToPath } from "node:url";
 import { defineConfig } from "vitest/config";
 
 export default defineConfig({
+	resolve: {
+		alias: {
+			"@": fileURLToPath(new URL("./webview", import.meta.url)),
+		},
+	},
 	test: {
 		environment: "node",
 	},

apps/examples/desktop-app/webview/app/globals.css

@@ -1,123 +1,10 @@
-@import "@fontsource-variable/geist";
+@import "@fontsource-variable/schibsted-grotesk";
+@import "@fontsource/azeret-mono/latin.css";
 @import "tailwindcss";
 @import "tw-animate-css";
+@import "@cline/ui/theme/index.css";
 
-@custom-variant dark (&:is(.dark *));
-
-:root {
-	--font-geist-sans: "Geist Variable";
-	--font-geist-mono:
-		ui-monospace, SFMono-Regular, "SF Mono", Consolas, "Liberation Mono", Menlo,
-		monospace;
-	--background: oklch(1 0 0);
-	--foreground: oklch(0.145 0 0);
-	--card: oklch(1 0 0);
-	--card-foreground: oklch(0.145 0 0);
-	--popover: oklch(1 0 0);
-	--popover-foreground: oklch(0.145 0 0);
-	--primary: oklch(0.398 0.195 277.366);
-	--primary-foreground: oklch(0.962 0.018 272.314);
-	--secondary: oklch(0.97 0 0);
-	--secondary-foreground: oklch(0.205 0 0);
-	--muted: oklch(0.97 0 0);
-	--muted-foreground: oklch(0.556 0 0);
-	--accent: oklch(0.97 0 0);
-	--accent-foreground: oklch(0.205 0 0);
-	--destructive: oklch(0.577 0.245 27.325);
-	--destructive-foreground: oklch(0.985 0 0);
-	--border: oklch(0.922 0 0);
-	--input: oklch(0.922 0 0);
-	--ring: oklch(0.708 0 0);
-	--chart-1: oklch(0.646 0.222 41.116);
-	--chart-2: oklch(0.6 0.118 184.704);
-	--chart-3: oklch(0.398 0.07 227.392);
-	--chart-4: oklch(0.828 0.189 84.429);
-	--chart-5: oklch(0.769 0.188 70.08);
-	--radius: 0.5rem;
-	--sidebar: oklch(0.985 0 0);
-	--sidebar-foreground: oklch(0.145 0 0);
-	--sidebar-primary: oklch(0.205 0 0);
-	--sidebar-primary-foreground: oklch(0.985 0 0);
-	--sidebar-accent: oklch(0.97 0 0);
-	--sidebar-accent-foreground: oklch(0.205 0 0);
-	--sidebar-border: oklch(0.922 0 0);
-	--sidebar-ring: oklch(0.708 0 0);
-}
-
-.dark {
-	--background: oklch(0.145 0 0);
-	--foreground: oklch(0.985 0 0);
-	--card: oklch(0.205 0 0);
-	--card-foreground: oklch(0.985 0 0);
-	--popover: oklch(0.205 0 0);
-	--popover-foreground: oklch(0.985 0 0);
-	--primary: oklch(0.398 0.195 277.366);
-	--primary-foreground: oklch(0.962 0.018 272.314);
-	--secondary: oklch(0.274 0.006 286.033);
-	--secondary-foreground: oklch(0.985 0 0);
-	--muted: oklch(0.269 0 0);
-	--muted-foreground: oklch(0.708 0 0);
-	--accent: oklch(0.269 0 0);
-	--accent-foreground: oklch(0.985 0 0);
-	--destructive: oklch(0.704 0.191 22.216);
-	--border: oklch(1 0 0 / 10%);
-	--input: oklch(1 0 0 / 15%);
-	--ring: oklch(0.556 0 0);
-	--chart-1: oklch(0.87 0 0);
-	--chart-2: oklch(0.556 0 0);
-	--chart-3: oklch(0.439 0 0);
-	--chart-4: oklch(0.371 0 0);
-	--chart-5: oklch(0.269 0 0);
-	--sidebar: oklch(0.205 0 0);
-	--sidebar-foreground: oklch(0.985 0 0);
-	--sidebar-primary: oklch(0.585 0.233 277.117);
-	--sidebar-primary-foreground: oklch(0.962 0.018 272.314);
-	--sidebar-accent: oklch(0.269 0 0);
-	--sidebar-accent-foreground: oklch(0.985 0 0);
-	--sidebar-border: oklch(1 0 0 / 10%);
-	--sidebar-ring: oklch(0.556 0 0);
-}
-
-@theme inline {
-	--font-sans: var(--font-geist-sans), "Geist Fallback";
-	--font-mono: var(--font-geist-mono), "Geist Mono Fallback";
-	--color-background: var(--background);
-	--color-foreground: var(--foreground);
-	--color-card: var(--card);
-	--color-card-foreground: var(--card-foreground);
-	--color-popover: var(--popover);
-	--color-popover-foreground: var(--popover-foreground);
-	--color-primary: var(--primary);
-	--color-primary-foreground: var(--primary-foreground);
-	--color-secondary: var(--secondary);
-	--color-secondary-foreground: var(--secondary-foreground);
-	--color-muted: var(--muted);
-	--color-muted-foreground: var(--muted-foreground);
-	--color-accent: var(--accent);
-	--color-accent-foreground: var(--accent-foreground);
-	--color-destructive: var(--destructive);
-	--color-destructive-foreground: var(--destructive-foreground);
-	--color-border: var(--border);
-	--color-input: var(--input);
-	--color-ring: var(--ring);
-	--color-chart-1: var(--chart-1);
-	--color-chart-2: var(--chart-2);
-	--color-chart-3: var(--chart-3);
-	--color-chart-4: var(--chart-4);
-	--color-chart-5: var(--chart-5);
-	--radius-sm: calc(var(--radius) - 4px);
-	--radius-md: calc(var(--radius) - 2px);
-	--radius-lg: var(--radius);
-	--radius-xl: calc(var(--radius) + 4px);
-	--color-sidebar: var(--sidebar);
-	--color-sidebar-foreground: var(--sidebar-foreground);
-	--color-sidebar-primary: var(--sidebar-primary);
-	--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-	--color-sidebar-accent: var(--sidebar-accent);
-	--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-	--color-sidebar-border: var(--sidebar-border);
-	--color-sidebar-ring: var(--sidebar-ring);
-}
+@source "../../node_modules/streamdown/dist";
 
 @layer base {
 	html,
@@ -126,83 +13,203 @@
 		min-height: 100vh;
 		overflow: hidden;
 	}
+
 	#__next {
 		height: 100%;
 	}
-	* {
-		@apply border-border outline-ring/50;
+}
+
+/* Hero heading cycling verb (components/views/chat/welcome-chat.tsx) */
+@keyframes hero-word-in {
+	0% {
+		opacity: 0;
+		transform: translateY(0.42em);
+		filter: blur(6px);
 	}
-	body {
-		@apply m-0 bg-background text-foreground;
+	60% {
+		filter: blur(0);
+	}
+	100% {
+		opacity: 1;
+		transform: translateY(0);
+		filter: blur(0);
 	}
 }
 
-@layer components {
-	.markdown {
-		@apply leading-relaxed;
-	}
-	.markdown * {
-		@apply text-sm leading-relaxed;
-	}
-	.markdown + .markdown {
-		@apply mt-2;
-	}
-	.markdown p {
-		@apply my-2 first:mt-0 last:mb-0;
-	}
-	.markdown a {
-		@apply underline;
-	}
-	.markdown blockquote {
-		@apply border-l-2 border-border pl-3;
-	}
-	.markdown code {
-		@apply space-y-1 rounded bg-muted px-1 py-0.5;
-	}
-	.markdown h1 {
-		@apply text-lg font-bold;
-	}
-	.markdown h2,
-	.markdown h3 {
-		@apply text-lg font-semibold;
-	}
-	.markdown ul {
-		@apply list-disc space-y-1;
-	}
-	.markdown ol {
-		@apply list-decimal space-y-1;
-	}
-	.markdown li {
-		@apply ml-5;
-	}
-	.markdown pre {
-		@apply space-y-1 overflow-x-auto rounded bg-muted p-3;
-	}
-	.markdown div {
-		@apply space-y-1;
+.hero-word-char {
+	display: inline-block;
+	white-space: pre;
+	/* Solid fallback so the word is never invisible if text clipping is unsupported. */
+	color: var(--brand-violet);
+	animation: hero-word-in 0.5s cubic-bezier(0.2, 0.65, 0.3, 1) both;
+}
+
+/*
+ * Gradient fill per character. The clip lives on each animated span (not a
+ * shared parent) because WebKit — used by the Tauri webview on macOS — drops
+ * the parent's background when a child paints on its own transform/filter
+ * layer, which would leave the animating letters blank. The -webkit- prefixes
+ * are required by WebKit; @supports keeps the solid fallback above otherwise.
+ */
+@supports ((-webkit-background-clip: text) or (background-clip: text)) {
+	.hero-word-char {
+		background-image: linear-gradient(
+			135deg,
+			var(--brand-periwinkle),
+			var(--brand-violet) 55%,
+			var(--brand-magenta)
+		);
+		-webkit-background-clip: text;
+		background-clip: text;
+		-webkit-text-fill-color: transparent;
+		color: transparent;
 	}
 }
 
-/* Custom scrollbar for dark theme */
-::-webkit-scrollbar {
-	width: 6px;
-	height: 6px;
+@media (prefers-reduced-motion: reduce) {
+	.hero-word-char {
+		/* biome-ignore lint/complexity/noImportantStyles: reduced motion must override inline animation delay */
+		animation: none !important;
+	}
 }
 
-::-webkit-scrollbar-track {
-	background: transparent;
+/* Aurora background (components/ui/aurora-bg.tsx) */
+@keyframes aurora-drift {
+	0% {
+		opacity: 0.55;
+		transform: translate3d(-8%, 5%, 0) rotate(-5deg) scale(0.94);
+	}
+	50% {
+		opacity: 0.92;
+		transform: translate3d(13%, -10%, 0) rotate(6deg) scale(1.11);
+	}
+	100% {
+		opacity: 0.62;
+		transform: translate3d(-5%, -2%, 0) rotate(-3deg) scale(1.02);
+	}
 }
 
-::-webkit-scrollbar-thumb {
-	background: oklch(0.3 0.005 260);
-	border-radius: 3px;
+@keyframes aurora-drift-reverse {
+	0% {
+		opacity: 0.62;
+		transform: translate3d(10%, -6%, 0) rotate(5deg) scale(1.08);
+	}
+	50% {
+		opacity: 0.9;
+		transform: translate3d(-12%, -12%, 0) rotate(-6deg) scale(0.96);
+	}
+	100% {
+		opacity: 0.58;
+		transform: translate3d(6%, 2%, 0) rotate(3deg) scale(1.04);
+	}
 }
 
-::-webkit-scrollbar-thumb:hover {
-	background: oklch(0.4 0.005 260);
+@keyframes aurora-horizon-breathe {
+	0% {
+		opacity: 0.48;
+		transform: translate3d(-3%, 9%, 0) scale(0.96, 0.84);
+	}
+	50% {
+		opacity: 0.88;
+		transform: translate3d(3%, -5%, 0) scale(1.08, 1.16);
+	}
+	100% {
+		opacity: 0.58;
+		transform: translate3d(-1%, 2%, 0) scale(1.02, 0.96);
+	}
 }
 
-/* Selection color */
-::selection {
-	background: oklch(0.75 0.12 165 / 0.25);
+@keyframes aurora-current-sweep {
+	0% {
+		opacity: 0.28;
+		transform: translate3d(-16%, 8%, 0) rotate(-8deg) scaleX(0.84);
+	}
+	50% {
+		opacity: 0.72;
+		transform: translate3d(17%, -8%, 0) rotate(4deg) scaleX(1.08);
+	}
+	100% {
+		opacity: 0.38;
+		transform: translate3d(28%, 4%, 0) rotate(-2deg) scaleX(0.94);
+	}
+}
+
+@keyframes aurora-twinkle {
+	0%,
+	100% {
+		opacity: 0.15;
+		transform: translate3d(0, 4px, 0) rotate(0deg) scale(0.78);
+	}
+	50% {
+		opacity: 0.78;
+		transform: translate3d(var(--aurora-star-x, 5px), -8px, 0) rotate(35deg)
+			scale(1.08);
+	}
+}
+
+.aurora-horizon {
+	animation: aurora-horizon-breathe 8s ease-in-out -3s infinite alternate;
+	transform-origin: center bottom;
+	will-change: opacity, transform;
+}
+
+.aurora-current {
+	animation-name: aurora-current-sweep;
+	animation-timing-function: ease-in-out;
+	animation-iteration-count: infinite;
+	animation-direction: alternate;
+	will-change: opacity, transform;
+}
+
+.aurora-current-reverse {
+	animation-direction: alternate-reverse;
+}
+
+.aurora-motion {
+	animation-name: aurora-drift;
+	animation-timing-function: ease-in-out;
+	animation-iteration-count: infinite;
+	animation-direction: alternate;
+}
+
+.aurora-motion-reverse {
+	animation-name: aurora-drift-reverse;
+}
+
+.aurora-star {
+	--aurora-star-x: 5px;
+	animation-name: aurora-twinkle;
+	animation-timing-function: ease-in-out;
+	animation-iteration-count: infinite;
+}
+
+.aurora-star:nth-of-type(2n) {
+	--aurora-star-x: -6px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.aurora-current,
+	.aurora-horizon,
+	.aurora-motion,
+	.aurora-star {
+		/* biome-ignore lint/complexity/noImportantStyles: reduced motion must override inline animation timing */
+		animation: none !important;
+	}
+
+	.aurora-horizon {
+		opacity: 0.68;
+		transform: translate3d(0, -1%, 0) scale(1.05);
+	}
+
+	.aurora-current,
+	.aurora-motion {
+		opacity: 0.58;
+		transform: none;
+	}
+
+	.aurora-current,
+	.aurora-horizon,
+	.aurora-motion {
+		will-change: auto;
+	}
 }

apps/examples/desktop-app/webview/app/layout.tsx

@@ -3,9 +3,8 @@ import type { Metadata } from "next";
 import "./globals.css";
 
 export const metadata: Metadata = {
-	title: "Agent Desktop",
-	description: "AI coding agent interface",
-	generator: "v0.app",
+	title: "Cline",
+	description: "Build software with Cline.",
 	icons: {
 		icon: [
 			{

apps/examples/desktop-app/webview/app/page.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { AgentHeader } from "@/components/agent-header";
 import { AgentSidebar } from "@/components/agent-sidebar";
+import { NyanCat, PetWindowView } from "@/components/nyan-cat";
 import {
 	AlertDialog,
 	AlertDialogAction,
@@ -18,25 +19,45 @@ import {
 	SidebarInset,
 	SidebarProvider,
 	SidebarRail,
+	SidebarTrigger,
 } from "@/components/ui/sidebar";
 import { ChatInputBar } from "@/components/views/chat/chat-input-bar";
 import { ChatMessages } from "@/components/views/chat/chat-messages";
 import { DiffView } from "@/components/views/chat/diff-view";
+import { WelcomeScreen } from "@/components/views/chat/welcome-chat";
 import { SessionsView } from "@/components/views/sessions/sessions-view";
-import { SettingsView } from "@/components/views/settings/settings-view";
+import {
+	type SettingsSection,
+	SettingsView,
+} from "@/components/views/settings/settings-view";
+import { AccountProvider } from "@/contexts/account-context";
 import { WorkspaceProvider } from "@/contexts/workspace-context";
 import type { PromptInQueue } from "@/hooks/chat-session/types";
 import { useChatSession } from "@/hooks/use-chat-session";
 import { useSessionHistory } from "@/hooks/use-session-history";
 import { toast } from "@/hooks/use-toast";
+import {
+	readChatBackground,
+	subscribeChatBackground,
+} from "@/lib/chat-background";
 import type { ChatSessionConfig } from "@/lib/chat-schema";
 import { desktopClient } from "@/lib/desktop-client";
+import { syncDesktopWindowTitle } from "@/lib/desktop-window-title";
+import { getCurrentWindowLabel, isTauri } from "@/lib/pet-window";
 import {
 	getSessionMetadataTitle,
 	type SessionHistoryItem,
 	type SessionMetadata,
 } from "@/lib/session-history";
 import { syncHubTheme, watchSystemHubTheme } from "@/lib/theme";
+import {
+	filterWorkspacePaths,
+	mergeWorkspacePaths,
+	normalizeWorkspacePath,
+	readWorkspaceSelectionFromWindow,
+	workspacePathsFromSessions,
+	writeWorkspaceSelectionToWindow,
+} from "@/lib/workspace-paths";
 
 function makeThreadId(): string {
 	return `thread_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
@@ -45,24 +66,9 @@ function makeThreadId(): string {
 type Thread = {
 	id: string;
 	historySession?: SessionHistoryItem;
+	hasStarted?: boolean;
 };
 
-type WorkspaceSessionItem = {
-	cwd?: string;
-	workspaceRoot?: string;
-};
-
-function normalizeWorkspacePath(path: string): string {
-	const normalized = path.trim().replace(/[\\/]+$/, "");
-	if (!normalized) {
-		return "";
-	}
-	if (/^[A-Za-z]:/.test(normalized)) {
-		return normalized.toLowerCase();
-	}
-	return normalized;
-}
-
 function toThreadTitle(options: { title?: string; prompt?: string }): string {
 	const preferredTitle = options.title?.trim();
 	if (preferredTitle) {
@@ -74,7 +80,38 @@ function toThreadTitle(options: { title?: string; prompt?: string }): string {
 }
 
 export default function Home() {
+	// Both the main and the floating-pet windows load this same page; branch on
+	// the Tauri window label so the pet window renders only the pet. Render
+	// nothing until resolved so the client-only branches never hydrate wrong.
+	const [windowKind, setWindowKind] = useState<"pending" | "main" | "pet">(
+		"pending",
+	);
+
+	useEffect(() => {
+		let active = true;
+		void getCurrentWindowLabel().then((label) => {
+			if (active) {
+				setWindowKind(label === "pet" ? "pet" : "main");
+			}
+		});
+		return () => {
+			active = false;
+		};
+	}, []);
+
+	if (windowKind === "pending") {
+		return null;
+	}
+	if (windowKind === "pet") {
+		return <PetWindowView />;
+	}
+	return <MainApp />;
+}
+
+function MainApp() {
 	const [view, setView] = useState<"chat" | "sessions" | "settings">("chat");
+	const [settingsSection, setSettingsSection] =
+		useState<SettingsSection>("General");
 	const [threads, setThreads] = useState<Thread[]>(() => [
 		{ id: makeThreadId() },
 	]);
@@ -87,6 +124,10 @@ export default function Home() {
 		return watchSystemHubTheme();
 	}, []);
 
+	useEffect(() => {
+		void syncDesktopWindowTitle();
+	}, []);
+
 	const handleNewThread = useCallback(() => {
 		const id = makeThreadId();
 		setThreads((prev) => [...prev, { id }]);
@@ -102,11 +143,15 @@ export default function Home() {
 				const next = [...prev];
 				next[existingIdx] = {
 					...next[existingIdx],
+					hasStarted: true,
 					historySession: session,
 				};
 				return next;
 			}
-			return [...prev, { id: threadId, historySession: session }];
+			return [
+				...prev,
+				{ id: threadId, hasStarted: true, historySession: session },
+			];
 		});
 		setActiveThreadId(threadId);
 		setView("chat");
@@ -188,70 +233,113 @@ export default function Home() {
 			?.sessionId ?? null;
 	const activeThread =
 		threads.find((thread) => thread.id === activeThreadId) ?? threads[0];
+	const handleHome = useCallback(() => {
+		if (activeThread?.historySession || activeThread?.hasStarted) {
+			handleNewThread();
+			return;
+		}
+		setView("chat");
+	}, [activeThread, handleNewThread]);
+	const handleThreadStarted = useCallback((threadId: string) => {
+		setThreads((current) =>
+			current.map((thread) =>
+				thread.id === threadId && !thread.hasStarted
+					? { ...thread, hasStarted: true }
+					: thread,
+			),
+		);
+	}, []);
 	const sessionHistory = useSessionHistory({
 		activeSessionId: activeHistorySessionId,
 		onDeleteSession: handleDeleteSession,
 		onOpenSession: handleOpenSession,
 		onUpdateSessionMetadata: handleUpdateSessionMetadata,
 	});
+	const historyWorkspacePaths = useMemo(
+		() => workspacePathsFromSessions(sessionHistory.sessions),
+		[sessionHistory.sessions],
+	);
 
 	return (
-		<>
+		<AccountProvider>
 			<SidebarProvider>
 				<div className="flex h-screen w-full overflow-hidden bg-background text-foreground">
+					{!isTauri() ? <NyanCat /> : null}
 					<Sidebar
 						className="border-r border-sidebar-border"
 						collapsible="icon"
 					>
 						<AgentSidebar
 							activeSessionId={activeHistorySessionId}
+							isHomeActive={
+								view === "chat" &&
+								!activeThread?.historySession &&
+								!activeThread?.hasStarted
+							}
+							onHome={handleHome}
 							onNewThread={handleNewThread}
+							onSettingsSectionChange={setSettingsSection}
 							sessionHistory={sessionHistory}
 							setView={setView}
+							settingsSection={settingsSection}
+							view={view}
 						/>
 						<SidebarRail />
 					</Sidebar>
 					<SidebarInset className="min-h-0 min-w-0 overflow-hidden">
+						<SidebarTrigger className="absolute left-3 top-3 z-40 md:hidden" />
 						{view === "sessions" ? (
 							<SessionsView
 								activeSessionId={activeHistorySessionId}
 								history={sessionHistory}
 							/>
 						) : activeThread ? (
-							<div className="flex min-h-0 flex-1 flex-col">
+							<div
+								aria-hidden={view === "settings" ? true : undefined}
+								className="flex min-h-0 flex-1 flex-col"
+								inert={view === "settings" ? true : undefined}
+							>
 								<ChatThreadPane
 									key={activeThread.id}
 									historySession={activeThread.historySession}
+									knownWorkspacePaths={historyWorkspacePaths}
 									onUpdateSessionMetadata={handleUpdateSessionMetadata}
 									threadId={activeThread.id}
 									onDeleteSession={handleDeleteSession}
 									onNewThread={handleNewThread}
 									onOpenSession={handleOpenSession}
+									onThreadStarted={handleThreadStarted}
+								/>
+							</div>
+						) : null}
+						{view === "settings" ? (
+							<div className="absolute inset-0 z-30 bg-background text-foreground">
+								<SettingsView
+									onNavigateSection={setSettingsSection}
+									section={settingsSection}
 								/>
 							</div>
 						) : null}
 					</SidebarInset>
 				</div>
 			</SidebarProvider>
-			{view === "settings" ? (
-				<div className="fixed inset-0 z-50 bg-background text-foreground">
-					<SettingsView onClose={() => setView("chat")} />
-				</div>
-			) : null}
-		</>
+		</AccountProvider>
 	);
 }
 
 function ChatThreadPane({
 	threadId,
 	historySession,
+	knownWorkspacePaths,
 	onUpdateSessionMetadata,
 	onDeleteSession,
 	onNewThread,
 	onOpenSession,
+	onThreadStarted,
 }: {
 	threadId: string;
 	historySession?: SessionHistoryItem;
+	knownWorkspacePaths: string[];
 	onUpdateSessionMetadata?: (
 		sessionId: string,
 		metadata: SessionMetadata,
@@ -259,6 +347,7 @@ function ChatThreadPane({
 	onDeleteSession?: (sessionId: string, threadId?: string) => void;
 	onNewThread?: () => void;
 	onOpenSession?: (session: SessionHistoryItem) => void;
+	onThreadStarted?: (threadId: string) => void;
 }) {
 	const {
 		sessionId,
@@ -300,11 +389,28 @@ function ChatThreadPane({
 		string | null
 	>(null);
 	const [gitBranch, setGitBranch] = useState("no-git");
+	const [chatBackground, setChatBackground] = useState<string | null>(null);
+
+	useEffect(() => {
+		setChatBackground(readChatBackground());
+		return subscribeChatBackground(() =>
+			setChatBackground(readChatBackground()),
+		);
+	}, []);
 	const [providerCredentials, setProviderCredentials] = useState<
 		Record<string, { apiKey: string }>
 	>({});
 	const [providersLoaded, setProvidersLoaded] = useState(false);
-	const [workspaces, setWorkspaces] = useState<string[]>([]);
+	// History paths lead each merge: they are ordered by session recency, so
+	// stored or stale entries only append after them.
+	const [workspaces, setWorkspaces] = useState<string[]>(() =>
+		filterWorkspacePaths(
+			mergeWorkspacePaths(
+				knownWorkspacePaths,
+				readWorkspaceSelectionFromWindow().workspaces,
+			),
+		),
+	);
 	const [workspacesLoaded, setWorkspacesLoaded] = useState(false);
 	const hydratedSessionRef = useRef<string | null>(null);
 	const resetThreadRef = useRef<string | null>(null);
@@ -318,6 +424,26 @@ function ChatThreadPane({
 		workspaceRoot: config.workspaceRoot,
 	};
 
+	useEffect(() => {
+		setWorkspaces((current) => {
+			const merged = filterWorkspacePaths(
+				mergeWorkspacePaths(knownWorkspacePaths, current),
+			);
+			return current.length === merged.length &&
+				current.every((workspace, index) => workspace === merged[index])
+				? current
+				: merged;
+		});
+	}, [knownWorkspacePaths]);
+
+	useEffect(() => {
+		const lastWorkspace = (config.workspaceRoot || config.cwd || "").trim();
+		writeWorkspaceSelectionToWindow({
+			lastWorkspace,
+			workspaces: mergeWorkspacePaths(workspaces, [lastWorkspace]),
+		});
+	}, [config.cwd, config.workspaceRoot, workspaces]);
+
 	useEffect(() => {
 		let cancelled = false;
 
@@ -438,52 +564,33 @@ function ChatThreadPane({
 
 	const listWorkspaces = useCallback(
 		async (preferredWorkspace?: string): Promise<string[]> => {
-			const roots = new Set<string>();
 			const preferred = (preferredWorkspace || "").trim();
-			if (preferred) {
-				roots.add(preferred);
-			}
 			const current = (
 				workspaceRef.current.workspaceRoot ||
 				workspaceRef.current.cwd ||
 				""
 			).trim();
-			if (current) {
-				roots.add(current);
-			}
-
-			try {
-				const discovered = await desktopClient
-					.invoke<WorkspaceSessionItem[]>("list_discovered_sessions", {
-						limit: 20,
-					})
-					.catch(() => []);
-
-				for (const session of discovered) {
-					const candidate = (session.workspaceRoot || session.cwd || "").trim();
-					if (candidate) {
-						roots.add(candidate);
-					}
-				}
-			} catch {
-				// Keep fallback to current workspace when history is unavailable.
-			}
-
-			return [...roots].sort((a, b) => a.localeCompare(b));
+			// The active workspace can be an excluded path (restored session,
+			// process cwd fallback); it renders via its own registration in the
+			// selector and welcome screen instead of joining the catalog.
+			return filterWorkspacePaths(
+				mergeWorkspacePaths(knownWorkspacePaths, [preferred, current]),
+			);
 		},
-		[],
+		[knownWorkspacePaths],
 	);
 
 	const refreshWorkspaces = useCallback(
 		async (preferredWorkspace?: string) => {
 			try {
 				const results = await listWorkspaces(preferredWorkspace);
-				setWorkspaces((current) =>
-					current.length === results.length &&
-					current.every((workspace, index) => workspace === results[index])
+				setWorkspaces((current) => {
+					const merged = mergeWorkspacePaths(results, current);
+					return current.length === merged.length &&
+						current.every((workspace, index) => workspace === merged[index])
 						? current
-						: results,
-				);
+						: merged;
+				});
 			} finally {
 				setWorkspacesLoaded(true);
 			}
@@ -508,17 +615,23 @@ function ChatThreadPane({
 			if (normalizedNext === normalizedCurrent) {
 				return true;
 			}
+			const validation = await desktopClient
+				.invoke<{ valid?: boolean }>("validate_workspace_directory", {
+					path: nextWorkspace,
+				})
+				.catch(() => ({ valid: false }));
+			if (validation.valid !== true) {
+				return false;
+			}
 
 			setConfig((prev) => ({
 				...prev,
 				workspaceRoot: nextWorkspace,
 				cwd: nextWorkspace,
 			}));
-			setWorkspaces((prev) => {
-				const next = new Set(prev);
-				next.add(nextWorkspace);
-				return [...next].sort((a, b) => a.localeCompare(b));
-			});
+			setWorkspaces((prev) =>
+				filterWorkspacePaths(mergeWorkspacePaths(prev, [nextWorkspace])),
+			);
 
 			// Fire git branch + workspace list refresh in the background
 			desktopClient
@@ -533,7 +646,7 @@ function ChatThreadPane({
 					setGitBranch("no-git");
 				});
 
-			// Re-fetch workspace list so the new root appears
+			// Refresh the merged history, stored, and current workspace catalog.
 			void refreshWorkspaces(nextWorkspace);
 
 			return true;
@@ -618,11 +731,12 @@ function ChatThreadPane({
 		if (!trimmed && pendingAttachments.length === 0) {
 			return;
 		}
+		onThreadStarted?.(threadId);
 		setPromptInput("");
 		const toSend = [...pendingAttachments];
 		setPendingAttachments([]);
 		await sendPrompt(trimmed, toSend);
-	}, [pendingAttachments, promptInput, sendPrompt]);
+	}, [onThreadStarted, pendingAttachments, promptInput, sendPrompt, threadId]);
 
 	const handleReasoningChange = useCallback(
 		(next: Pick<ChatSessionConfig, "thinking" | "reasoningEffort">) => {
@@ -826,6 +940,8 @@ function ChatThreadPane({
 	const displayedIsSwitching = hideDeletedSessionUi
 		? false
 		: isHydratingSession;
+	const isWelcomeState =
+		displayedMessages.length === 0 && !displayedIsSwitching && !displayedError;
 
 	const handleRenameTitle = useCallback(
 		async (nextTitle: string) => {
@@ -913,150 +1029,169 @@ function ChatThreadPane({
 		);
 	}
 
+	const composer = (
+		<ChatInputBar
+			attachments={attachmentList}
+			onAbort={() => void abort()}
+			onAttachFiles={(files) => {
+				setPendingAttachments((prev) => {
+					const existing = new Set(
+						prev.map(
+							(file) => `${file.name}:${file.size}:${file.lastModified}`,
+						),
+					);
+					const next = [...prev];
+					for (const file of files) {
+						const key = `${file.name}:${file.size}:${file.lastModified}`;
+						if (!existing.has(key)) {
+							existing.add(key);
+							next.push(file);
+						}
+					}
+					return next;
+				});
+			}}
+			onListGitBranches={listGitBranches}
+			onRemoveAttachment={(id) => {
+				setPendingAttachments((prev) =>
+					prev.filter((file, index) => {
+						const fileId = `${file.name}:${file.size}:${file.lastModified}:${index}`;
+						return fileId !== id;
+					}),
+				);
+			}}
+			onSwitchGitBranch={switchGitBranch}
+			onModelChange={(nextModel) =>
+				setConfig((prev) =>
+					prev.model === nextModel ? prev : { ...prev, model: nextModel },
+				)
+			}
+			onModeToggle={() =>
+				setConfig((prev) => ({
+					...prev,
+					mode: prev.mode === "plan" ? "act" : "plan",
+				}))
+			}
+			onPromptInputChange={setPromptInput}
+			onReasoningChange={handleReasoningChange}
+			onSteerPromptInQueue={(promptId) => {
+				void steerPromptInQueue(promptId);
+			}}
+			onEditPromptInQueue={(promptId, prompt) => {
+				void updatePromptInQueue(promptId, prompt);
+			}}
+			onUndoPromptInQueue={(item) => {
+				void handleUndoQueuedPrompt(item);
+			}}
+			onProviderChange={(nextProvider) =>
+				setConfig((prev) => {
+					const selected = providerCredentials[nextProvider];
+					const nextApiKey = selected?.apiKey ?? "";
+					if (prev.provider === nextProvider && prev.apiKey === nextApiKey) {
+						return prev;
+					}
+					return {
+						...prev,
+						provider: nextProvider,
+						apiKey: nextApiKey,
+					};
+				})
+			}
+			onSend={() => void handleSend()}
+			gitBranch={gitBranch}
+			model={config.model}
+			mode={config.mode}
+			promptsInQueue={promptsInQueue}
+			promptInput={promptInput}
+			provider={config.provider}
+			reasoningEffort={config.reasoningEffort}
+			status={status}
+			summary={summary}
+			thinking={config.thinking}
+			variant={isWelcomeState ? "welcome" : "conversation"}
+		/>
+	);
+
 	return (
 		<WorkspaceProvider value={workspaceContextValue}>
-			<div className="grid h-full min-h-0 flex-1 grid-rows-[auto_minmax(0,1fr)_auto] overflow-hidden">
-				<div className="z-20">
-					<AgentHeader
-						canEditTitle={Boolean(activeSessionForTitle)}
-						canDeleteSession={Boolean(activeSessionToDelete)}
-						deletingSession={deletingSession}
-						diff={{
-							additions: summary.additions,
-							deletions: summary.deletions,
-						}}
-						onDeleteSession={requestDeleteSession}
-						onNewThread={onNewThread}
-						onOpenDiff={() => {
-							if (hasDiffChanges) {
-								setShowDiffView(true);
-							}
-						}}
-						onRenameTitle={handleRenameTitle}
-						renamingTitle={renamingSession}
-						status={status}
-						title={threadTitle}
-					/>
-				</div>
-				<div className="h-full min-h-0 overflow-hidden">
-					{showDiffView ? (
-						<DiffView
-							fileDiffs={fileDiffs}
-							onClose={() => setShowDiffView(false)}
+			<div className="relative flex h-full min-h-0 flex-1 flex-col overflow-hidden">
+				{chatBackground ? (
+					<>
+						<div
+							aria-hidden="true"
+							className="pointer-events-none absolute inset-0 bg-cover bg-center"
+							style={{ backgroundImage: `url("${chatBackground}")` }}
 						/>
-					) : (
-						<ChatMessages
-							onAnswerAskQuestion={handleAnswerAskQuestion}
-							onApproveToolApproval={handleApproveToolApproval}
-							onRejectToolApproval={handleRejectToolApproval}
-							onStartChat={(prompt) => {
-								setPromptInput(prompt);
-							}}
-							chatTransportState={chatTransportState}
-							error={displayedError}
-							messages={displayedMessages}
-							model={config.model}
-							onRestoreCheckpoint={(runCount) =>
-								void restoreCheckpoint(runCount)
-							}
-							onForkSession={handleForkSession}
-							pendingToolApprovals={pendingToolApprovals}
-							pendingAskQuestions={pendingAskQuestions}
-							provider={config.provider}
-							sessionId={displayedSessionId}
-							streamingMessageId={activeAssistantMessageId}
-							isSessionSwitching={displayedIsSwitching}
-							status={displayedStatus}
+						<div
+							aria-hidden="true"
+							className="pointer-events-none absolute inset-0 bg-background/80"
 						/>
-					)}
-				</div>
-				<div className="z-20 shrink-0">
-					<ChatInputBar
-						attachments={attachmentList}
-						onAbort={() => void abort()}
-						onAttachFiles={(files) => {
-							setPendingAttachments((prev) => {
-								const existing = new Set(
-									prev.map(
-										(file) => `${file.name}:${file.size}:${file.lastModified}`,
-									),
-								);
-								const next = [...prev];
-								for (const file of files) {
-									const key = `${file.name}:${file.size}:${file.lastModified}`;
-									if (!existing.has(key)) {
-										existing.add(key);
-										next.push(file);
+					</>
+				) : null}
+				<div
+					className={
+						isWelcomeState
+							? "relative z-10 grid min-h-0 flex-1 grid-rows-[minmax(0,1fr)] overflow-hidden"
+							: "relative z-10 grid min-h-0 flex-1 grid-rows-[auto_minmax(0,1fr)_auto] overflow-hidden"
+					}
+				>
+					{!isWelcomeState ? (
+						<div className="z-20 border-b border-border/70 bg-background/85 backdrop-blur-sm">
+							<AgentHeader
+								canEditTitle={Boolean(activeSessionForTitle)}
+								canDeleteSession={Boolean(activeSessionToDelete)}
+								deletingSession={deletingSession}
+								diff={{
+									additions: summary.additions,
+									deletions: summary.deletions,
+								}}
+								onDeleteSession={requestDeleteSession}
+								onNewThread={onNewThread}
+								onOpenDiff={() => {
+									if (hasDiffChanges) setShowDiffView(true);
+								}}
+								onRenameTitle={handleRenameTitle}
+								renamingTitle={renamingSession}
+								status={status}
+								title={threadTitle}
+							/>
+						</div>
+					) : null}
+					<WelcomeScreen
+						active={isWelcomeState}
+						body={
+							showDiffView ? (
+								<DiffView
+									fileDiffs={fileDiffs}
+									onClose={() => setShowDiffView(false)}
+								/>
+							) : (
+								<ChatMessages
+									onAnswerAskQuestion={handleAnswerAskQuestion}
+									onApproveToolApproval={handleApproveToolApproval}
+									onRejectToolApproval={handleRejectToolApproval}
+									chatTransportState={chatTransportState}
+									error={displayedError}
+									messages={displayedMessages}
+									onRestoreCheckpoint={(runCount) =>
+										void restoreCheckpoint(runCount)
 									}
-								}
-								return next;
-							});
-						}}
-						onListGitBranches={listGitBranches}
-						onRemoveAttachment={(id) => {
-							setPendingAttachments((prev) =>
-								prev.filter((file, index) => {
-									const fileId = `${file.name}:${file.size}:${file.lastModified}:${index}`;
-									return fileId !== id;
-								}),
-							);
-						}}
-						onSwitchGitBranch={switchGitBranch}
-						onRefreshGitBranch={() => void refreshGitBranch()}
-						onModelChange={(nextModel) =>
-							setConfig((prev) =>
-								prev.model === nextModel ? prev : { ...prev, model: nextModel },
+									onForkSession={handleForkSession}
+									pendingToolApprovals={pendingToolApprovals}
+									pendingAskQuestions={pendingAskQuestions}
+									sessionId={displayedSessionId}
+									streamingMessageId={activeAssistantMessageId}
+									isSessionSwitching={displayedIsSwitching}
+									status={displayedStatus}
+								/>
 							)
 						}
-						onModeToggle={() =>
-							setConfig((prev) => ({
-								...prev,
-								mode: prev.mode === "plan" ? "act" : "plan",
-							}))
-						}
-						onPromptInputChange={setPromptInput}
-						onReasoningChange={handleReasoningChange}
-						onSteerPromptInQueue={(promptId) => {
-							void steerPromptInQueue(promptId);
-						}}
-						onEditPromptInQueue={(promptId, prompt) => {
-							void updatePromptInQueue(promptId, prompt);
-						}}
-						onUndoPromptInQueue={(item) => {
-							void handleUndoQueuedPrompt(item);
-						}}
-						onProviderChange={(nextProvider) =>
-							setConfig((prev) => {
-								const selected = providerCredentials[nextProvider];
-								const nextApiKey = selected?.apiKey ?? "";
-								if (
-									prev.provider === nextProvider &&
-									prev.apiKey === nextApiKey
-								) {
-									return prev;
-								}
-								return {
-									...prev,
-									provider: nextProvider,
-									apiKey: nextApiKey,
-								};
-							})
-						}
-						onReset={() => {
-							setPendingAttachments([]);
-							void reset();
-						}}
-						onSend={() => void handleSend()}
+						composer={composer}
 						gitBranch={gitBranch}
-						model={config.model}
-						mode={config.mode}
-						promptsInQueue={promptsInQueue}
-						promptInput={promptInput}
-						provider={config.provider}
-						reasoningEffort={config.reasoningEffort}
-						status={status}
-						summary={summary}
-						thinking={config.thinking}
+						onListGitBranches={listGitBranches}
+						onStartChat={setPromptInput}
+						onSwitchGitBranch={switchGitBranch}
+						quickActions={[]}
 					/>
 				</div>
 			</div>

apps/examples/desktop-app/webview/components/agent-header.tsx

@@ -24,6 +24,7 @@ type AgentHeaderProps = {
 	canDeleteSession?: boolean;
 	deletingSession?: boolean;
 	onOpenDiff?: () => void;
+	showSessionActions?: boolean;
 	status?: ChatSessionStatus;
 	diff?: {
 		additions: number;
@@ -41,6 +42,7 @@ export function AgentHeader({
 	canDeleteSession,
 	deletingSession,
 	onOpenDiff,
+	showSessionActions = true,
 	status,
 	diff,
 }: AgentHeaderProps) {
@@ -80,12 +82,13 @@ export function AgentHeader({
 	const triggerDeleteSession = () => onDeleteSession?.();
 
 	return (
-		<header className="flex h-12 items-center justify-between px-4">
+		<header className="flex h-12 items-center justify-between gap-2 px-4 max-md:pl-12">
 			{/* Left: thread title */}
-			<div className="flex items-center gap-2">
-				<span
+			<div className="flex min-w-0 flex-1 items-center gap-2">
+				<output
+					aria-label={`Session status: ${status}`}
 					className={cn(
-						"rounded w-2 h-2 font-mono",
+						"size-2 shrink-0 rounded font-mono",
 						status === "running"
 							? "bg-green-500"
 							: status === "failed"
@@ -95,7 +98,7 @@ export function AgentHeader({
 				/>
 				{isEditingTitle ? (
 					<form
-						className="m-0"
+						className="m-0 min-w-0 flex-1"
 						onSubmit={(event) => {
 							event.preventDefault();
 							void submitTitle();
@@ -103,7 +106,7 @@ export function AgentHeader({
 					>
 						<Input
 							autoFocus
-							className="h-7 w-64 text-sm"
+							className="h-7 w-64 max-w-full text-sm"
 							disabled={renamingTitle}
 							onBlur={() => {
 								void submitTitle();
@@ -122,7 +125,7 @@ export function AgentHeader({
 				) : (
 					<button
 						className={cn(
-							"text-sm font-medium text-foreground",
+							"min-w-0 truncate text-sm font-medium text-foreground",
 							canEditTitle &&
 								"rounded px-1 py-0.5 transition-colors hover:bg-accent",
 						)}
@@ -135,6 +138,7 @@ export function AgentHeader({
 							setIsEditingTitle(true);
 						}}
 						type="button"
+						title={threadTitle}
 					>
 						{threadTitle}
 					</button>
@@ -142,7 +146,8 @@ export function AgentHeader({
 				<DropdownMenu>
 					<DropdownMenuTrigger asChild>
 						<Button
-							className="text-muted-foreground hover:text-foreground transition-colors"
+							aria-label="Session actions"
+							className="shrink-0 text-muted-foreground transition-colors hover:text-foreground"
 							id="show-more-btn"
 							variant="ghost"
 							size="icon-sm"
@@ -164,34 +169,37 @@ export function AgentHeader({
 				</DropdownMenu>
 			</div>
 
-			{/* Right: actions */}
-			<div className="flex items-center gap-2">
-				{/* DIFF */}
-				<Button
-					className={cn(
-						"flex items-center gap-1 rounded-md bg-secondary px-2 py-1 text-xs font-mono transition-colors",
-						hasChanges ? "hover:bg-secondary/80" : "cursor-default opacity-60",
-					)}
-					disabled={!hasChanges}
-					id="diff-stats"
-					onClick={() => onOpenDiff?.()}
-					size="sm"
-					type="button"
-					variant="secondary"
-				>
-					<span className="text-chart-2">+{additions}</span>
-					<span className="text-destructive">-{deletions}</span>
-				</Button>
-				{/* New Chat Button */}
-				<Button
-					className="flex items-center gap-1 rounded-md text-sm text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
-					onClick={() => onNewThread?.()}
-					size="icon-sm"
-					variant="ghost"
-				>
-					<Plus />
-				</Button>
-			</div>
+			{showSessionActions ? (
+				<div className="flex shrink-0 items-center gap-2">
+					<Button
+						aria-label={`Open diff: ${additions} additions, ${deletions} deletions`}
+						className={cn(
+							"flex items-center gap-1 rounded-md bg-secondary px-2 py-1 text-xs font-mono transition-colors",
+							hasChanges
+								? "hover:bg-secondary/80"
+								: "cursor-default opacity-60",
+						)}
+						disabled={!hasChanges}
+						id="diff-stats"
+						onClick={() => onOpenDiff?.()}
+						size="sm"
+						type="button"
+						variant="secondary"
+					>
+						<span className="text-chart-2">+{additions}</span>
+						<span className="text-destructive">-{deletions}</span>
+					</Button>
+					<Button
+						aria-label="New session"
+						className="flex items-center gap-1 rounded-md text-sm text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
+						onClick={() => onNewThread?.()}
+						size="icon-sm"
+						variant="ghost"
+					>
+						<Plus />
+					</Button>
+				</div>
+			) : null}
 		</header>
 	);
 }

apps/examples/desktop-app/webview/components/agent-sidebar.test.tsx

@@ -0,0 +1,333 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AgentSidebar } from "@/components/agent-sidebar";
+import { SidebarProvider } from "@/components/ui/sidebar";
+import { AccountProvider } from "@/contexts/account-context";
+import type {
+	SessionThread,
+	UseSessionHistoryResult,
+} from "@/hooks/use-session-history";
+
+const { invoke } = vi.hoisted(() => ({ invoke: vi.fn() }));
+vi.mock("@/lib/desktop-client", () => ({ desktopClient: { invoke } }));
+
+let container: HTMLDivElement;
+let root: Root;
+
+function makeThread(project: string, index: number): SessionThread {
+	return {
+		id: `${project}-${index}`,
+		title: `${project} session ${index}`,
+		codebase: project,
+		workspacePath: `/projects/${project}`,
+		time: `${index}m`,
+		provider: "cline",
+		model: "test-model",
+		status: "completed",
+	};
+}
+
+function makeSessionHistory(
+	threads: SessionThread[],
+	loadMoreSessions: ReturnType<typeof vi.fn>,
+	options: {
+		loadOlderSessions?: ReturnType<typeof vi.fn>;
+		mayHaveMoreSessions?: boolean;
+	} = {},
+): UseSessionHistoryResult {
+	return {
+		deleteThread: vi.fn(),
+		forkThread: vi.fn(),
+		isLoadingHistory: false,
+		isLoadingMore: false,
+		loadOlderSessions: options.loadOlderSessions ?? vi.fn(),
+		loadMoreSessions,
+		mayHaveMoreSessions: options.mayHaveMoreSessions ?? false,
+		openThread: vi.fn(),
+		pendingAction: null,
+		renameThread: vi.fn(),
+		threads,
+		unreadSessionIds: new Set<string>(),
+	} as unknown as UseSessionHistoryResult;
+}
+
+async function click(element: Element): Promise<void> {
+	await act(async () => {
+		element.dispatchEvent(
+			new MouseEvent("pointerdown", { bubbles: true, cancelable: true }),
+		);
+		element.dispatchEvent(
+			new MouseEvent("click", { bubbles: true, cancelable: true }),
+		);
+		await Promise.resolve();
+	});
+}
+
+function buttonWithText(text: string, rootNode: ParentNode = container) {
+	const button = [
+		...rootNode.querySelectorAll<HTMLButtonElement>("button"),
+	].find((candidate) => candidate.textContent?.includes(text));
+	expect(button).toBeDefined();
+	return button as HTMLButtonElement;
+}
+
+function sessionIsVisible(title: string): boolean {
+	return [...container.querySelectorAll<HTMLButtonElement>("button")].some(
+		(button) => button.querySelector("span")?.textContent === title,
+	);
+}
+
+beforeEach(() => {
+	Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+	window.localStorage.clear();
+	invoke.mockReset();
+	invoke.mockRejectedValue(new Error("No Cline account auth token found"));
+	Object.defineProperty(window, "matchMedia", {
+		configurable: true,
+		value: vi.fn(() => ({
+			matches: false,
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+		})),
+	});
+	HTMLElement.prototype.hasPointerCapture = vi.fn(() => false);
+	HTMLElement.prototype.setPointerCapture = vi.fn();
+	HTMLElement.prototype.releasePointerCapture = vi.fn();
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+});
+
+afterEach(async () => {
+	await act(async () => root.unmount());
+	container.remove();
+	vi.restoreAllMocks();
+});
+
+describe("AgentSidebar session organization", () => {
+	it("defaults to time and keeps project expansion scoped to one project", async () => {
+		const threads = [
+			...Array.from({ length: 12 }, (_, index) =>
+				makeThread("alpha", index + 1),
+			),
+			...Array.from({ length: 12 }, (_, index) =>
+				makeThread("beta", index + 1),
+			),
+		];
+		const loadMoreSessions = vi.fn(async () => undefined);
+		const loadOlderSessions = vi.fn(async () => undefined);
+		const sessionHistory = makeSessionHistory(threads, loadMoreSessions, {
+			loadOlderSessions,
+			mayHaveMoreSessions: true,
+		});
+
+		await act(async () => {
+			root.render(
+				<SidebarProvider>
+					<AgentSidebar
+						activeSessionId={null}
+						isHomeActive
+						onHome={vi.fn()}
+						onNewThread={vi.fn()}
+						sessionHistory={sessionHistory}
+						setView={vi.fn()}
+						view="chat"
+					/>
+				</SidebarProvider>,
+			);
+		});
+
+		expect(
+			container.querySelector('[aria-label="Sort sessions: Time"]'),
+		).not.toBeNull();
+		expect(sessionIsVisible("alpha session 10")).toBe(true);
+		expect(sessionIsVisible("alpha session 11")).toBe(false);
+		expect(sessionIsVisible("beta session 1")).toBe(false);
+
+		await click(buttonWithText("Show more"));
+		expect(sessionIsVisible("alpha session 11")).toBe(true);
+		expect(loadMoreSessions).toHaveBeenCalledWith(20);
+
+		await click(
+			container.querySelector('[aria-label="Sort sessions: Time"]') as Element,
+		);
+		const projectOption = await vi.waitFor(() => {
+			const option = [
+				...document.querySelectorAll<HTMLElement>('[role="menuitemradio"]'),
+			].find((candidate) => candidate.textContent?.includes("Sort by project"));
+			expect(option).toBeDefined();
+			return option as HTMLElement;
+		});
+		await click(projectOption);
+
+		await vi.waitFor(() => {
+			expect(
+				container.querySelector('[aria-label="Sort sessions: Project"]'),
+			).not.toBeNull();
+		});
+		expect(container.textContent).toContain("alpha");
+		expect(container.textContent).toContain("beta");
+		expect(sessionIsVisible("alpha session 11")).toBe(false);
+		expect(sessionIsVisible("beta session 11")).toBe(false);
+
+		await click(buttonWithText("Show more in alpha"));
+		expect(sessionIsVisible("alpha session 11")).toBe(true);
+		expect(sessionIsVisible("beta session 11")).toBe(false);
+
+		await click(buttonWithText("Load older projects"));
+		expect(loadOlderSessions).toHaveBeenCalledOnce();
+	});
+
+	it("shows the signed-in account and active organization in the footer", async () => {
+		invoke.mockResolvedValue({
+			id: "user-1",
+			email: "beatrix@cline.bot",
+			displayName: "Beatrix",
+			photoUrl: "",
+			createdAt: "2024-01-01T00:00:00Z",
+			updatedAt: "2024-01-01T00:00:00Z",
+			organizations: [
+				{
+					active: true,
+					memberId: "member-1",
+					name: "Cline Bot Inc",
+					organizationId: "org-1",
+					roles: ["admin"],
+				},
+			],
+		});
+
+		await act(async () => {
+			root.render(
+				<AccountProvider>
+					<SidebarProvider>
+						<AgentSidebar
+							activeSessionId={null}
+							isHomeActive
+							onHome={vi.fn()}
+							onNewThread={vi.fn()}
+							onSettingsSectionChange={vi.fn()}
+							sessionHistory={makeSessionHistory([], vi.fn())}
+							setView={vi.fn()}
+							settingsSection="General"
+							view="chat"
+						/>
+					</SidebarProvider>
+				</AccountProvider>,
+			);
+		});
+
+		await vi.waitFor(() => {
+			expect(container.textContent).toContain("Beatrix");
+			expect(container.textContent).toContain("Cline Bot Inc");
+		});
+		expect(container.textContent).not.toContain("Cline Desktop");
+		expect(container.textContent).not.toContain("Local");
+	});
+
+	it("opens the Account settings section when the footer account row is clicked", async () => {
+		const setView = vi.fn();
+		const onSettingsSectionChange = vi.fn();
+
+		await act(async () => {
+			root.render(
+				<AccountProvider>
+					<SidebarProvider>
+						<AgentSidebar
+							activeSessionId={null}
+							isHomeActive
+							onHome={vi.fn()}
+							onNewThread={vi.fn()}
+							onSettingsSectionChange={onSettingsSectionChange}
+							sessionHistory={makeSessionHistory([], vi.fn())}
+							setView={setView}
+							settingsSection="General"
+							view="chat"
+						/>
+					</SidebarProvider>
+				</AccountProvider>,
+			);
+		});
+
+		const accountButton = container.querySelector(
+			'[aria-label="Account settings"]',
+		);
+		expect(accountButton).not.toBeNull();
+		await click(accountButton as Element);
+
+		expect(onSettingsSectionChange).toHaveBeenCalledWith("Account");
+		expect(setView).toHaveBeenCalledWith("settings");
+	});
+
+	it("shows the desktop app version in a popover when the Cline logo is clicked", async () => {
+		const onHome = vi.fn();
+		invoke.mockImplementation(async (command: string) => {
+			if (command === "get_process_context") {
+				return { appVersion: "1.2.3" };
+			}
+			throw new Error("No Cline account auth token found");
+		});
+
+		await act(async () => {
+			root.render(
+				<AccountProvider>
+					<SidebarProvider>
+						<AgentSidebar
+							activeSessionId={null}
+							isHomeActive
+							onHome={onHome}
+							onNewThread={vi.fn()}
+							onSettingsSectionChange={vi.fn()}
+							sessionHistory={makeSessionHistory([], vi.fn())}
+							setView={vi.fn()}
+							settingsSection="General"
+							view="chat"
+						/>
+					</SidebarProvider>
+				</AccountProvider>,
+			);
+		});
+
+		const logoButton = container.querySelector('[aria-label="Cline home"]');
+		expect(logoButton).not.toBeNull();
+		expect(document.body.textContent).not.toContain("Version 1.2.3");
+
+		await click(logoButton as Element);
+
+		await vi.waitFor(() => {
+			expect(document.body.textContent).toContain("Version 1.2.3");
+		});
+		expect(onHome).toHaveBeenCalled();
+		expect(invoke).toHaveBeenCalledWith("get_process_context");
+	});
+
+	it("falls back to a signed-out footer without account data", async () => {
+		await act(async () => {
+			root.render(
+				<AccountProvider>
+					<SidebarProvider>
+						<AgentSidebar
+							activeSessionId={null}
+							isHomeActive
+							onHome={vi.fn()}
+							onNewThread={vi.fn()}
+							onSettingsSectionChange={vi.fn()}
+							sessionHistory={makeSessionHistory([], vi.fn())}
+							setView={vi.fn()}
+							settingsSection="General"
+							view="chat"
+						/>
+					</SidebarProvider>
+				</AccountProvider>,
+			);
+		});
+
+		await vi.waitFor(() => {
+			expect(container.textContent).toContain("Cline Desktop");
+		});
+		expect(container.textContent).not.toContain("Local");
+	});
+});

apps/examples/desktop-app/webview/components/agent-sidebar.tsx

@@ -1,8 +1,14 @@
 "use client";
 
 import {
+	ArrowDownUp,
+	Blocks,
+	Bot,
 	ChevronDown,
+	CircleUserRound,
+	Clock3,
 	Filter,
+	FolderTree,
 	GitFork,
 	Loader2,
 	MessageSquare,
@@ -10,8 +16,12 @@ import {
 	Pencil,
 	Pin,
 	Plus,
+	Radio,
 	Search,
+	Server,
 	Settings,
+	SlidersHorizontal,
+	Store,
 	Trash2,
 } from "lucide-react";
 import {
@@ -22,6 +32,7 @@ import {
 	useRef,
 	useState,
 } from "react";
+import { ClineLogo } from "@/components/cline-logo";
 import {
 	AlertDialog,
 	AlertDialogAction,
@@ -52,40 +63,135 @@ import {
 	HoverCardTrigger,
 } from "@/components/ui/hover-card";
 import { Input } from "@/components/ui/input";
+import {
+	Popover,
+	PopoverContent,
+	PopoverTrigger,
+} from "@/components/ui/popover";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import { useSidebar } from "@/components/ui/sidebar";
 import { normalizeTitle } from "@/components/utils";
+import {
+	SETTINGS_SECTIONS,
+	type SettingsSection,
+} from "@/components/views/settings/settings-view";
+import { useAccount } from "@/contexts/account-context";
 import type {
 	SessionThread,
 	UseSessionHistoryResult,
 } from "@/hooks/use-session-history";
 import { formatCostUsd, formatTokenCount } from "@/hooks/use-session-history";
+import { desktopClient } from "@/lib/desktop-client";
+import {
+	groupThreadsByProject,
+	INITIAL_VISIBLE_THREAD_COUNT,
+	workspaceDisplayName,
+} from "@/lib/sidebar-session-organization";
 import { cn } from "@/lib/utils";
 
 type Thread = SessionThread;
+type AppView = "chat" | "sessions" | "settings";
 
 const filterOptions = ["All", "Running", "Recent", "Pinned"] as const;
 type FilterOption = (typeof filterOptions)[number];
-const INITIAL_VISIBLE_THREAD_COUNT = 10;
+type SidebarSortMode = "time" | "project";
+const SETTINGS_SECTION_ICONS = {
+	General: SlidersHorizontal,
+	Models: Bot,
+	"MCP Servers": Server,
+	"MCP Marketplace": Store,
+	Customizations: Blocks,
+	Channels: Radio,
+	Schedules: Clock3,
+	Account: CircleUserRound,
+} satisfies Record<SettingsSection, typeof Settings>;
+
+function SettingsSectionNavigation({
+	activeSection,
+	collapsed,
+	onSelect,
+}: {
+	activeSection: SettingsSection;
+	collapsed: boolean;
+	onSelect: (section: SettingsSection) => void;
+}) {
+	return (
+		<nav
+			aria-label="Settings sections"
+			className={cn(
+				"flex h-full min-h-0 flex-col gap-0.5 overflow-y-auto",
+				collapsed ? "w-full items-center" : "w-full",
+			)}
+		>
+			{!collapsed ? (
+				<p className="px-2 pb-2 text-sm font-medium text-muted-foreground">
+					Settings
+				</p>
+			) : null}
+			{SETTINGS_SECTIONS.map((section) => {
+				const Icon = SETTINGS_SECTION_ICONS[section];
+				return (
+					<Button
+						aria-current={activeSection === section ? "page" : undefined}
+						aria-label={section}
+						className={cn(
+							"min-w-0 justify-start",
+							activeSection === section &&
+								"bg-sidebar-accent text-sidebar-accent-foreground",
+							collapsed && "mx-auto size-9 justify-center px-0",
+						)}
+						key={section}
+						onClick={() => onSelect(section)}
+						title={section}
+						type="button"
+						variant="sidebarItem"
+					>
+						<Icon className="size-4 shrink-0" />
+						{!collapsed ? <span className="truncate">{section}</span> : null}
+					</Button>
+				);
+			})}
+		</nav>
+	);
+}
 
 export function AgentSidebar({
+	isHomeActive,
+	onHome,
 	onNewThread,
+	onSettingsSectionChange,
 	setView,
+	settingsSection,
+	view,
 	activeSessionId,
 	sessionHistory,
 }: {
+	isHomeActive: boolean;
+	onHome: () => void;
 	onNewThread?: () => void;
-	setView: (view: "chat" | "sessions" | "settings") => void;
+	onSettingsSectionChange: (section: SettingsSection) => void;
+	setView: (view: AppView) => void;
+	settingsSection: SettingsSection;
+	view: AppView;
 	activeSessionId?: string | null;
 	sessionHistory: UseSessionHistoryResult;
 }) {
-	const { isMobile, setOpen, state } = useSidebar();
+	const { isMobile, setOpen, setOpenMobile, state } = useSidebar();
 	const isCollapsed = !isMobile && state === "collapsed";
+	const { user, activeOrganization } = useAccount();
+	const { displayName, email } = user || {};
+	const username = displayName?.split(" ")?.[0] || email?.split("@")?.[0];
+	const accountName = username?.trim() || "Cline Desktop";
+	const accountScope = user
+		? (activeOrganization?.name ?? "Personal")
+		: undefined;
+	const accountInitial = accountName.charAt(0).toUpperCase();
 	const {
 		deleteThread: deleteHistoryThread,
 		forkThread: forkHistoryThread,
 		isLoadingHistory,
 		isLoadingMore,
+		loadOlderSessions,
 		loadMoreSessions,
 		mayHaveMoreSessions,
 		openThread: openHistoryThread,
@@ -96,6 +202,7 @@ export function AgentSidebar({
 	} = sessionHistory;
 	const activeThread = activeSessionId ?? "";
 	const [filter, setFilter] = useState<FilterOption>("All");
+	const [sortMode, setSortMode] = useState<SidebarSortMode>("time");
 	const [searchOpen, setSearchOpen] = useState(false);
 	const [searchQuery, setSearchQuery] = useState("");
 	const [showMoreCount, setShowMoreCount] = useState(
@@ -106,6 +213,32 @@ export function AgentSidebar({
 	const [deleteConfirmThread, setDeleteConfirmThread] = useState<Thread | null>(
 		null,
 	);
+	const [collapsedProjects, setCollapsedProjects] = useState<Set<string>>(
+		() => new Set(),
+	);
+	const [projectVisibleCounts, setProjectVisibleCounts] = useState<
+		Record<string, number>
+	>({});
+	const [appVersion, setAppVersion] = useState<string | null>(null);
+
+	const loadAppVersion = useCallback(async () => {
+		try {
+			const context = await desktopClient.invoke<{ appVersion?: unknown }>(
+				"get_process_context",
+			);
+			const version =
+				typeof context?.appVersion === "string"
+					? context.appVersion.trim()
+					: "";
+			setAppVersion(version || null);
+		} catch {
+			// Leave the version hidden; an older sidecar build has no appVersion.
+		}
+	}, []);
+
+	useEffect(() => {
+		void loadAppVersion();
+	}, [loadAppVersion]);
 
 	useEffect(() => {
 		if (isCollapsed && searchOpen) {
@@ -120,7 +253,8 @@ export function AgentSidebar({
 			filtered = filtered.filter(
 				(t) =>
 					t.title.toLowerCase().includes(q) ||
-					t.codebase.toLowerCase().includes(q),
+					t.codebase.toLowerCase().includes(q) ||
+					t.workspacePath.toLowerCase().includes(q),
 			);
 		}
 		switch (filter) {
@@ -134,19 +268,44 @@ export function AgentSidebar({
 				return filtered;
 		}
 	}, [filter, searchQuery, threads]);
+	const closeMobileSidebar = useCallback(() => {
+		if (isMobile) setOpenMobile(false);
+	}, [isMobile, setOpenMobile]);
 
 	const openThread = useCallback(
 		(threadId: string) => {
 			setView("chat");
 			openHistoryThread(threadId);
+			closeMobileSidebar();
 		},
-		[openHistoryThread, setView],
+		[closeMobileSidebar, openHistoryThread, setView],
 	);
 
 	const openNewThread = useCallback(() => {
 		setView("chat");
 		onNewThread?.();
-	}, [onNewThread, setView]);
+		closeMobileSidebar();
+	}, [closeMobileSidebar, onNewThread, setView]);
+	const openHome = useCallback(() => {
+		onHome();
+		closeMobileSidebar();
+	}, [closeMobileSidebar, onHome]);
+	const openSessions = useCallback(() => {
+		setView("sessions");
+		closeMobileSidebar();
+	}, [closeMobileSidebar, setView]);
+	const openSettings = useCallback(() => {
+		setView("settings");
+		closeMobileSidebar();
+	}, [closeMobileSidebar, setView]);
+	const openSettingsSection = useCallback(
+		(section: SettingsSection) => {
+			onSettingsSectionChange(section);
+			setView("settings");
+			closeMobileSidebar();
+		},
+		[closeMobileSidebar, onSettingsSectionChange, setView],
+	);
 
 	const startRenameThread = useCallback((thread: Thread) => {
 		setEditingSessionId(thread.id);
@@ -202,8 +361,30 @@ export function AgentSidebar({
 				: [...pinnedThreads, ...sessionThreads].slice(0, showMoreCount),
 		[filter, pinnedThreads, sessionThreads, showMoreCount],
 	);
-	const showShowMore =
-		sessionThreads.length > showMoreCount || mayHaveMoreSessions;
+	const showTimeShowMore =
+		sessionThreads.length > showMoreCount ||
+		(filter === "All" && !searchQuery && mayHaveMoreSessions);
+	const projectGroups = useMemo(
+		() => groupThreadsByProject([...pinnedThreads, ...sessionThreads]),
+		[pinnedThreads, sessionThreads],
+	);
+
+	const toggleProject = useCallback((project: string) => {
+		setCollapsedProjects((current) => {
+			const next = new Set(current);
+			if (next.has(project)) next.delete(project);
+			else next.add(project);
+			return next;
+		});
+	}, []);
+	const showMoreForProject = useCallback((project: string) => {
+		setProjectVisibleCounts((current) => ({
+			...current,
+			[project]:
+				(current[project] ?? INITIAL_VISIBLE_THREAD_COUNT) +
+				INITIAL_VISIBLE_THREAD_COUNT,
+		}));
+	}, []);
 
 	const filterMenu = (
 		<DropdownMenu>
@@ -222,6 +403,7 @@ export function AgentSidebar({
 					onValueChange={(value) => {
 						setFilter(value as FilterOption);
 						setShowMoreCount(INITIAL_VISIBLE_THREAD_COUNT);
+						setProjectVisibleCounts({});
 					}}
 					value={filter}
 				>
@@ -234,29 +416,136 @@ export function AgentSidebar({
 			</DropdownMenuContent>
 		</DropdownMenu>
 	);
+	const sortMenu = (
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button
+					aria-label={`Sort sessions: ${sortMode === "time" ? "Time" : "Project"}`}
+					className="m-0! inline-flex size-8 items-center justify-center rounded-md p-0! text-muted-foreground transition-colors hover:bg-sidebar-accent hover:text-sidebar-foreground"
+					size="icon"
+					title={sortMode === "time" ? "Sort by time" : "Sort by project"}
+					variant="ghost"
+				>
+					<ArrowDownUp className="size-3.5" />
+				</Button>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="end" className="w-44">
+				<DropdownMenuRadioGroup
+					onValueChange={(value) => {
+						if (value === "time" || value === "project") {
+							setSortMode(value);
+						}
+					}}
+					value={sortMode}
+				>
+					<DropdownMenuRadioItem value="time">
+						<Clock3 className="size-4" />
+						Sort by time
+					</DropdownMenuRadioItem>
+					<DropdownMenuRadioItem value="project">
+						<FolderTree className="size-4" />
+						Sort by project
+					</DropdownMenuRadioItem>
+				</DropdownMenuRadioGroup>
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+	const threadItem = (thread: Thread) => (
+		<ThreadItem
+			editTitle={editingTitle}
+			editing={editingSessionId === thread.id}
+			isActive={activeThread === thread.id}
+			key={thread.id}
+			onCancelRename={cancelRenameThread}
+			onClick={() => openThread(thread.id)}
+			onCommitRename={() => void commitRenameThread(thread)}
+			onDelete={() => requestDeleteThread(thread)}
+			onEditTitleChange={setEditingTitle}
+			onFork={() => void forkThread(thread)}
+			onRename={() => startRenameThread(thread)}
+			pendingAction={
+				pendingAction?.sessionId === thread.id ? pendingAction.action : null
+			}
+			thread={thread}
+			unread={unreadSessionIds.has(thread.id)}
+		/>
+	);
 
 	return (
 		<>
 			<div className="flex h-full min-h-0 w-full min-w-0 shrink-0 flex-col overflow-hidden bg-sidebar text-sidebar-foreground">
-				<div className="mt-2 flex w-full min-w-0 flex-col gap-1">
+				<div
+					className={cn(
+						"flex h-16 shrink-0 items-center px-4",
+						isCollapsed && "justify-center px-0",
+					)}
+				>
+					<Popover
+						onOpenChange={(open) => {
+							if (open && !appVersion) {
+								void loadAppVersion();
+							}
+						}}
+					>
+						<PopoverTrigger asChild>
+							<button
+								aria-label="Cline home"
+								className="flex items-center gap-2 rounded-md p-1 text-sidebar-foreground transition-transform hover:scale-105 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sidebar-ring"
+								type="button"
+								onClick={openHome}
+								title="Home"
+							>
+								<ClineLogo className="h-6 w-6" />
+							</button>
+						</PopoverTrigger>
+						<PopoverContent align="start" className="w-52 p-3" side="bottom">
+							<p className="text-sm font-medium">Cline Code</p>
+							<p className="mt-0.5 text-xs text-muted-foreground">
+								{appVersion ? `Version ${appVersion}` : "Version unavailable"}
+							</p>
+						</PopoverContent>
+					</Popover>
+				</div>
+
+				<div className={cn("shrink-0 px-3", isCollapsed && "px-1.5")}>
 					<Button
 						className={cn(
-							"justify-start min-w-0",
+							"min-w-0 justify-start",
+							view === "chat" &&
+								isHomeActive &&
+								"bg-sidebar-accent text-sidebar-accent-foreground",
 							isCollapsed && "mx-auto size-9 justify-center px-0",
 						)}
 						aria-label="New Session"
-						onClick={openNewThread}
+						onClick={openHome}
 						title="New Session"
-						variant="sidebar"
+						variant="sidebarItem"
 					>
-						{isCollapsed ? (
-							<MessageSquare className="size-4" />
-						) : (
-							<Plus className="size-4" />
-						)}
+						<Plus className="size-4" />
 						{!isCollapsed ? "New Session" : null}
 					</Button>
-					{isCollapsed ? (
+				</div>
+
+				{isCollapsed ? (
+					<div className="mt-2 flex min-h-0 flex-1 flex-col items-center gap-1 px-1.5">
+						{view === "settings" ? (
+							<SettingsSectionNavigation
+								activeSection={settingsSection}
+								collapsed
+								onSelect={openSettingsSection}
+							/>
+						) : (
+							<Button
+								aria-label="New session"
+								className="mx-auto size-9 justify-center px-0"
+								onClick={openNewThread}
+								title="New session"
+								type="button"
+								variant="sidebarItem"
+							>
+								<MessageSquare className="size-4" />
+							</Button>
+						)}
 						<Button
 							aria-label="Expand sidebar"
 							className="mx-auto size-9 justify-center px-0"
@@ -267,139 +556,211 @@ export function AgentSidebar({
 						>
 							<PanelLeftOpen className="size-4" />
 						</Button>
-					) : null}
-				</div>
-
-				{!isCollapsed ? (
-					<div className="flex w-full min-w-0 flex-col gap-1">
-						{searchOpen ? (
-							<div className="flex min-w-0 items-center gap-2 overflow-hidden rounded-md bg-sidebar-accent px-2 py-1.5">
-								<Search className="size-4 shrink-0" />
-								<Input
-									className="min-w-0 flex-1 bg-transparent text-sm text-sidebar-foreground outline-none placeholder:text-muted-foreground"
-									onBlur={() => {
-										if (!searchQuery) setSearchOpen(false);
-									}}
-									autoFocus={true}
-									onChange={(e) => setSearchQuery(e.target.value)}
-									placeholder="Search sessions..."
-									value={searchQuery}
-								/>
-							</div>
-						) : (
-							<Button
-								className="py-1.5 min-w-0"
-								onClick={() => setSearchOpen(true)}
-								title="Search sessions"
-								type="button"
-								variant="sidebarItem"
-							>
-								<Search className="size-4 shrink-0" />
-								<span>Search</span>
-							</Button>
-						)}
 					</div>
-				) : null}
-
-				{!isCollapsed ? (
-					<div className="mt-2 min-h-0 w-full flex-1">
-						<ScrollArea className="h-full min-h-0 w-full min-w-0">
-							<div className="flex min-w-0 flex-col gap-0.5 pb-3 px-3">
-								{isLoadingHistory && threads.length === 0 ? (
-									<div className="p-4 text-xs text-muted-foreground">
-										Loading session history...
-									</div>
-								) : (
-									<>
-										{displayedThreads.length > 0 && (
-											<ThreadSection
-												action={filterMenu}
-												label={filter === "All" ? "Sessions" : filter}
-												onClick={() => setView("sessions")}
-											>
-												{displayedThreads.map((thread) => (
-													<ThreadItem
-														editTitle={editingTitle}
-														editing={editingSessionId === thread.id}
-														isActive={activeThread === thread.id}
-														key={thread.id}
-														onCancelRename={cancelRenameThread}
-														onClick={() => openThread(thread.id)}
-														onCommitRename={() =>
-															void commitRenameThread(thread)
-														}
-														onDelete={() => requestDeleteThread(thread)}
-														onEditTitleChange={setEditingTitle}
-														onFork={() => void forkThread(thread)}
-														onRename={() => startRenameThread(thread)}
-														pendingAction={
-															pendingAction?.sessionId === thread.id
-																? pendingAction.action
-																: null
-														}
-														thread={thread}
-														unread={unreadSessionIds.has(thread.id)}
-													/>
-												))}
-											</ThreadSection>
-										)}
-
-										{displayedThreads.length === 0 && (
-											<div className="p-4 text-xs text-muted-foreground">
-												{searchQuery
-													? "No sessions match your search."
-													: "No sessions found in history."}
-											</div>
-										)}
-									</>
-								)}
-								{showShowMore && (
-									<Button
-										className="pl-0"
-										disabled={isLoadingMore}
-										onClick={() => {
-											const nextCount =
-												showMoreCount + INITIAL_VISIBLE_THREAD_COUNT;
-											setShowMoreCount(nextCount);
-											void loadMoreSessions(nextCount);
-										}}
-										type="button"
-										variant="sidebarText"
-									>
-										{isLoadingMore ? (
-											<>
-												<Loader2 className="size-3 animate-spin" />
-												Loading...
-											</>
-										) : (
-											<>
-												Show more
-												<ChevronDown className="size-3" />
-											</>
-										)}
-									</Button>
-								)}
-							</div>
-						</ScrollArea>
+				) : view === "settings" ? (
+					<div className="mt-5 min-h-0 flex-1 px-3">
+						<SettingsSectionNavigation
+							activeSection={settingsSection}
+							collapsed={false}
+							onSelect={openSettingsSection}
+						/>
 					</div>
 				) : (
-					<div className="min-h-0 w-full flex-1" />
+					<>
+						<div className="mt-5 shrink-0 px-3">
+							<div className="flex h-8 items-center justify-between gap-2">
+								<button
+									className={cn(
+										"min-w-0 truncate text-sm font-medium text-muted-foreground transition-colors hover:text-sidebar-foreground",
+										view === "sessions" && "text-sidebar-foreground",
+									)}
+									onClick={openSessions}
+									type="button"
+								>
+									{sortMode === "time" ? "Sessions" : "Projects"}
+								</button>
+								<div className="flex shrink-0 items-center gap-0.5">
+									<Button
+										aria-label="Search sessions"
+										className="m-0! size-8 p-0! text-muted-foreground hover:text-sidebar-foreground"
+										onClick={() => setSearchOpen((current) => !current)}
+										size="icon"
+										title="Search sessions"
+										type="button"
+										variant="ghost"
+									>
+										<Search className="size-3.5" />
+									</Button>
+									{sortMenu}
+									{filterMenu}
+								</div>
+							</div>
+							{searchOpen ? (
+								<div className="mt-1 flex min-w-0 items-center gap-2 overflow-hidden rounded-md border border-sidebar-border bg-background/70 px-2 py-1">
+									<Search className="size-4 shrink-0" />
+									<Input
+										className="h-7 min-w-0 flex-1 border-0 bg-transparent px-0 text-sm text-sidebar-foreground shadow-none outline-none placeholder:text-muted-foreground focus-visible:ring-0"
+										autoFocus={true}
+										onChange={(e) => setSearchQuery(e.target.value)}
+										placeholder="Search sessions..."
+										value={searchQuery}
+									/>
+								</div>
+							) : null}
+						</div>
+
+						<div className="mt-1 min-h-0 w-full flex-1">
+							<ScrollArea className="h-full min-h-0 w-full min-w-0">
+								<div className="flex min-w-0 flex-col gap-0.5 pb-3 px-3">
+									{isLoadingHistory && threads.length === 0 ? (
+										<div className="p-4 text-xs text-muted-foreground">
+											Loading session history...
+										</div>
+									) : (
+										<>
+											{sortMode === "time"
+												? displayedThreads.map(threadItem)
+												: projectGroups.map((project) => {
+														const visibleCount =
+															projectVisibleCounts[project.id] ??
+															INITIAL_VISIBLE_THREAD_COUNT;
+														return (
+															<ProjectSection
+																collapsed={collapsedProjects.has(project.id)}
+																key={project.id}
+																label={project.label}
+																onToggle={() => toggleProject(project.id)}
+															>
+																{project.threads
+																	.slice(0, visibleCount)
+																	.map(threadItem)}
+																{project.threads.length > visibleCount ? (
+																	<Button
+																		className="pl-2"
+																		onClick={() =>
+																			showMoreForProject(project.id)
+																		}
+																		type="button"
+																		variant="sidebarText"
+																	>
+																		Show more in {project.label}
+																		<ChevronDown className="size-3" />
+																	</Button>
+																) : null}
+															</ProjectSection>
+														);
+													})}
+
+											{(sortMode === "time"
+												? displayedThreads.length === 0
+												: projectGroups.length === 0) && (
+												<div className="px-2 py-4 text-xs text-muted-foreground">
+													{searchQuery
+														? "No sessions match your search."
+														: "No sessions found in history."}
+												</div>
+											)}
+										</>
+									)}
+									{sortMode === "time" && showTimeShowMore && (
+										<Button
+											className="pl-0"
+											disabled={isLoadingMore}
+											onClick={() => {
+												const nextCount =
+													showMoreCount + INITIAL_VISIBLE_THREAD_COUNT;
+												setShowMoreCount(nextCount);
+												void loadMoreSessions(nextCount);
+											}}
+											type="button"
+											variant="sidebarText"
+										>
+											{isLoadingMore ? (
+												<>
+													<Loader2 className="size-3 animate-spin" />
+													Loading...
+												</>
+											) : (
+												<>
+													Show more
+													<ChevronDown className="size-3" />
+												</>
+											)}
+										</Button>
+									)}
+									{sortMode === "project" &&
+										filter === "All" &&
+										!searchQuery &&
+										mayHaveMoreSessions && (
+											<Button
+												className="pl-0"
+												disabled={isLoadingMore}
+												onClick={() => void loadOlderSessions()}
+												type="button"
+												variant="sidebarText"
+											>
+												{isLoadingMore ? (
+													<>
+														<Loader2 className="size-3 animate-spin" />
+														Loading older projects...
+													</>
+												) : (
+													<>
+														Load older projects
+														<ChevronDown className="size-3" />
+													</>
+												)}
+											</Button>
+										)}
+								</div>
+							</ScrollArea>
+						</div>
+					</>
 				)}
 
-				<div className="shrink-0 px-2 py-3">
-					<Button
-						type="button"
-						variant="sidebarItem"
-						className={cn(
-							"justify-start min-w-0",
-							isCollapsed && "mx-auto size-9 justify-center px-0",
-						)}
-						onClick={() => setView("settings")}
-						title="Settings"
-					>
-						<Settings className="size-4" />
-						{!isCollapsed ? "Settings" : null}
-					</Button>
+				<div className="shrink-0 border-t border-sidebar-border/70 px-2 py-3">
+					{view !== "settings" && (
+						<Button
+							aria-label="Settings"
+							type="button"
+							variant="sidebarItem"
+							className={cn(
+								"min-w-0 justify-start",
+								isCollapsed && "mx-auto size-9 justify-center px-0",
+							)}
+							onClick={openSettings}
+							title="Settings"
+						>
+							<Settings className="size-4" />
+							{!isCollapsed ? "Settings" : null}
+						</Button>
+					)}
+					{!isCollapsed ? (
+						<button
+							aria-label="Account settings"
+							className={cn(
+								"flex w-full items-center gap-2 rounded-md px-3 py-2 text-left text-sidebar-foreground transition-colors hover:bg-sidebar-accent/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sidebar-ring",
+								view === "settings" &&
+									settingsSection === "Account" &&
+									"bg-sidebar-accent text-sidebar-accent-foreground",
+							)}
+							onClick={() => openSettingsSection("Account")}
+							title={user?.email || undefined}
+							type="button"
+						>
+							<span className="min-w-0 flex gap-2 items-center">
+								<span className="flex size-4 shrink-0 items-center justify-center rounded-full bg-primary text-[11px] font-semibold text-primary-foreground">
+									{accountInitial}
+								</span>
+								<span className="block truncate text-sm font-medium">
+									{accountName}
+									<span className="pl-1 truncate text-[11px] text-muted-foreground">
+										{accountScope}
+									</span>
+								</span>
+							</span>
+						</button>
+					) : null}
 				</div>
 			</div>
 			<AlertDialog
@@ -451,33 +812,35 @@ export function AgentSidebar({
 	);
 }
 
-function ThreadSection({
+function ProjectSection({
 	label,
-	action,
-	onClick,
+	collapsed,
+	onToggle,
 	children,
 }: {
 	label: string;
-	action?: ReactNode;
-	onClick?: () => void;
+	collapsed: boolean;
+	onToggle: () => void;
 	children: ReactNode;
 }) {
 	return (
-		<div className={cn("mb-1 min-w-0")}>
-			<div className="flex h-9 w-full min-w-0 flex-nowrap items-center gap-1 text-sm font-medium text-muted-foreground">
-				<button
-					aria-label={`Open ${label} sessions view`}
-					className="flex min-w-0 flex-1 items-center self-stretch rounded-md pl-0 pr-2 text-left transition-colors hover:bg-sidebar-accent hover:text-sidebar-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-					onClick={onClick}
-					type="button"
-				>
-					<span className="block min-w-0 shrink truncate">{label}</span>
-				</button>
-				{action ? (
-					<div className="flex shrink-0 items-center">{action}</div>
-				) : null}
-			</div>
-			{children}
+		<div className="mb-1 min-w-0">
+			<button
+				aria-expanded={!collapsed}
+				className="flex h-8 w-full min-w-0 items-center gap-1.5 rounded-md px-1 text-left text-sm font-medium text-sidebar-foreground transition-colors hover:bg-sidebar-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sidebar-ring"
+				onClick={onToggle}
+				title={label}
+				type="button"
+			>
+				<ChevronDown
+					className={cn(
+						"size-3.5 shrink-0 transition-transform",
+						collapsed && "-rotate-90",
+					)}
+				/>
+				<span className="block min-w-0 truncate">{label}</span>
+			</button>
+			{!collapsed ? <div className="pl-3">{children}</div> : null}
 		</div>
 	);
 }
@@ -515,6 +878,7 @@ function ThreadItem({
 	const costLabel = formatCostUsd(thread.totalCostUsd);
 	const title = normalizeTitle(thread.title);
 	const pending = pendingAction !== null;
+	const workspacePath = thread.workspacePath || thread.codebase;
 	const statusDotClass = pending
 		? "bg-yellow-400"
 		: thread.status === "running"
@@ -522,16 +886,20 @@ function ThreadItem({
 			: unread
 				? "bg-blue-500"
 				: "";
-	const infoItems: Array<[string, string | null | undefined]> = [
+	const infoItems: Array<[string, string | null | undefined, string?]> = [
 		["ID", thread.id],
-		["Workspace", thread.codebase],
+		[
+			"Workspace",
+			workspaceDisplayName(workspacePath),
+			workspacePath || undefined,
+		],
 		["Status", thread.status],
 		["Updated", thread.time],
 		["Provider", thread.provider],
 		["Model", thread.model],
 		["Tokens", tokenLabel],
 		["Cost", costLabel],
-	].filter((item): item is [string, string] => Boolean(item[1]));
+	].filter((item): item is [string, string, string?] => Boolean(item[1]));
 
 	if (editing) {
 		return (
@@ -564,7 +932,7 @@ function ThreadItem({
 					<HoverCardTrigger asChild>
 						<button
 							className={cn(
-								"group grid h-8 w-full max-w-full min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-2 overflow-hidden rounded-md px-2 text-left text-sm font-normal transition-colors",
+								"group grid h-8 w-full max-w-full min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-1 overflow-hidden rounded-md px-2 text-left text-sm font-normal transition-colors",
 								isActive
 									? "bg-sidebar-accent text-sidebar-accent-foreground"
 									: "text-sidebar-foreground/80 hover:bg-sidebar-accent/50",
@@ -573,20 +941,20 @@ function ThreadItem({
 							onClick={onClick}
 							type="button"
 						>
-							<span className="block max-w-full min-w-0 overflow-hidden text-ellipsis whitespace-nowrap text-sm font-semibold leading-tight">
+							<span className="block max-w-full min-w-0 overflow-hidden text-ellipsis whitespace-nowrap text-sm font-normal leading-tight">
 								{title}
 							</span>
-							{thread.pinned ? (
-								<Pin
-									aria-label="Pinned"
-									className="size-3 shrink-0 text-muted-foreground"
-								/>
-							) : statusDotClass ? (
-								<span
-									aria-hidden="true"
-									className={cn("size-2 rounded-full", statusDotClass)}
-								/>
-							) : null}
+							<span className="flex shrink-0 items-center gap-1.5 text-[11px] text-muted-foreground">
+								{thread.pinned ? (
+									<Pin aria-label="Pinned" className="size-3" />
+								) : statusDotClass ? (
+									<span
+										aria-hidden="true"
+										className={cn("size-1.5 rounded-full", statusDotClass)}
+									/>
+								) : null}
+								<span>{thread.time}</span>
+							</span>
 						</button>
 					</HoverCardTrigger>
 				</ContextMenuTrigger>
@@ -600,10 +968,15 @@ function ThreadItem({
 					<div className="min-w-0 space-y-2">
 						<div className="truncate text-sm font-medium">{title}</div>
 						<div className="grid grid-cols-[72px_minmax(0,1fr)] gap-x-2 gap-y-1 text-xs">
-							{infoItems.map(([label, value]) => (
+							{infoItems.map(([label, value, fullValue]) => (
 								<div className="contents" key={label}>
 									<span className="text-muted-foreground">{label}</span>
-									<span className="min-w-0 truncate font-mono">{value}</span>
+									<span
+										className="min-w-0 truncate font-mono"
+										title={fullValue}
+									>
+										{value}
+									</span>
 								</div>
 							))}
 						</div>

apps/examples/desktop-app/webview/components/cline-logo.tsx

@@ -0,0 +1,20 @@
+import { cn } from "@/lib/utils";
+
+export function ClineLogo({ className }: { className?: string }) {
+	return (
+		<span
+			aria-hidden="true"
+			className={cn("inline-block shrink-0 bg-current", className)}
+			style={{
+				maskImage: "url('/cline-logo-filled.svg')",
+				maskPosition: "center",
+				maskRepeat: "no-repeat",
+				maskSize: "contain",
+				WebkitMaskImage: "url('/cline-logo-filled.svg')",
+				WebkitMaskPosition: "center",
+				WebkitMaskRepeat: "no-repeat",
+				WebkitMaskSize: "contain",
+			}}
+		/>
+	);
+}

apps/examples/desktop-app/webview/components/nyan-cat.tsx

@@ -0,0 +1,238 @@
+"use client";
+
+import { AppWindow, X } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	DEFAULT_NYAN_PET_SRC,
+	getNyanPetSrc,
+	subscribeNyanPet,
+} from "@/lib/nyan-pet";
+import { hidePet, showMainWindow, startPetDrag } from "@/lib/pet-window";
+
+const NYAN_WIDTH = 160;
+const NYAN_HEIGHT = 96;
+const MARGIN = 32;
+
+/**
+ * Shared pet media: the current gif source (kept in sync with Settings) plus an
+ * audio element that plays only while the pet is hovered or being dragged.
+ */
+function useNyanPetMedia() {
+	const audioRef = useRef<HTMLAudioElement | null>(null);
+	const [petSrc, setPetSrc] = useState(DEFAULT_NYAN_PET_SRC);
+	const [hovering, setHovering] = useState(false);
+	const [dragging, setDragging] = useState(false);
+
+	useEffect(() => {
+		setPetSrc(getNyanPetSrc());
+		return subscribeNyanPet(() => setPetSrc(getNyanPetSrc()));
+	}, []);
+
+	useEffect(() => {
+		const audio = audioRef.current;
+		if (!audio) {
+			return;
+		}
+		if (hovering || dragging) {
+			void audio.play().catch(() => {});
+		} else {
+			audio.pause();
+			audio.currentTime = 0;
+		}
+	}, [hovering, dragging]);
+
+	return { audioRef, petSrc, hovering, setHovering, dragging, setDragging };
+}
+
+/**
+ * In-page pet used in plain web/dev mode (no Tauri). Free-floating and draggable
+ * within the window; its theme song plays while hovered or dragged. In the
+ * desktop app the pet lives in its own always-on-top window (see PetWindowView).
+ */
+export function NyanCat() {
+	const [visible, setVisible] = useState(true);
+	const [position, setPosition] = useState({ x: MARGIN, y: MARGIN });
+	const { audioRef, petSrc, dragging, setDragging, setHovering } =
+		useNyanPetMedia();
+	const dragOffsetRef = useRef<{ x: number; y: number } | null>(null);
+
+	useEffect(() => {
+		setPosition({
+			x: Math.max(MARGIN, window.innerWidth - NYAN_WIDTH - MARGIN),
+			y: Math.max(MARGIN, window.innerHeight - NYAN_HEIGHT - MARGIN),
+		});
+	}, []);
+
+	const clamp = useCallback((x: number, y: number) => {
+		const maxX = Math.max(0, window.innerWidth - NYAN_WIDTH);
+		const maxY = Math.max(0, window.innerHeight - NYAN_HEIGHT);
+		return {
+			x: Math.min(Math.max(0, x), maxX),
+			y: Math.min(Math.max(0, y), maxY),
+		};
+	}, []);
+
+	useEffect(() => {
+		if (!dragging) {
+			return;
+		}
+		const handleMove = (event: PointerEvent) => {
+			const offset = dragOffsetRef.current;
+			if (!offset) {
+				return;
+			}
+			setPosition(clamp(event.clientX - offset.x, event.clientY - offset.y));
+		};
+		const stop = () => {
+			dragOffsetRef.current = null;
+			setDragging(false);
+		};
+		window.addEventListener("pointermove", handleMove);
+		window.addEventListener("pointerup", stop);
+		window.addEventListener("pointercancel", stop);
+		return () => {
+			window.removeEventListener("pointermove", handleMove);
+			window.removeEventListener("pointerup", stop);
+			window.removeEventListener("pointercancel", stop);
+		};
+	}, [dragging, clamp, setDragging]);
+
+	useEffect(() => {
+		const handleResize = () =>
+			setPosition((current) => clamp(current.x, current.y));
+		window.addEventListener("resize", handleResize);
+		return () => window.removeEventListener("resize", handleResize);
+	}, [clamp]);
+
+	if (!visible) {
+		return null;
+	}
+
+	return (
+		<div
+			className="group fixed z-50 cursor-grab select-none active:cursor-grabbing"
+			onPointerDown={(event) => {
+				if ((event.target as HTMLElement).closest("[data-nyan-control]")) {
+					return;
+				}
+				event.preventDefault();
+				dragOffsetRef.current = {
+					x: event.clientX - position.x,
+					y: event.clientY - position.y,
+				};
+				setDragging(true);
+			}}
+			onPointerEnter={() => setHovering(true)}
+			onPointerLeave={() => setHovering(false)}
+			style={{ left: position.x, top: position.y, width: NYAN_WIDTH }}
+		>
+			<button
+				aria-label="Hide Nyan Cat"
+				className="absolute -right-2 -top-2 hidden size-5 items-center justify-center rounded-full bg-background/90 text-foreground shadow ring-1 ring-border group-hover:flex"
+				data-nyan-control=""
+				onClick={() => setVisible(false)}
+				type="button"
+			>
+				<X className="size-3" />
+			</button>
+			{/* biome-ignore lint/performance/noImgElement: static public asset, not statically optimizable */}
+			<img
+				alt="Desktop pet"
+				className="pointer-events-none w-full drop-shadow-lg"
+				draggable={false}
+				height={NYAN_HEIGHT}
+				src={petSrc}
+				width={NYAN_WIDTH}
+			/>
+			{/* biome-ignore lint/a11y/useMediaCaption: decorative background music */}
+			<audio loop preload="auto" ref={audioRef} src="/nyantune.mp3" />
+		</div>
+	);
+}
+
+/**
+ * The pet as rendered inside its own transparent, always-on-top Tauri window.
+ * Dragging moves the OS window (so it can go anywhere on screen, even when the
+ * main window is minimized), and the dismiss button hides the window.
+ */
+export function PetWindowView() {
+	const { audioRef, petSrc, dragging, setDragging, setHovering } =
+		useNyanPetMedia();
+
+	// Make the window chrome see-through so only the pet shows.
+	useEffect(() => {
+		const root = document.documentElement;
+		const body = document.body;
+		const prevRoot = root.style.background;
+		const prevBody = body.style.background;
+		root.style.background = "transparent";
+		body.style.background = "transparent";
+		return () => {
+			root.style.background = prevRoot;
+			body.style.background = prevBody;
+		};
+	}, []);
+
+	// The OS drag can swallow the pointerup; reset on any pointer release.
+	useEffect(() => {
+		if (!dragging) {
+			return;
+		}
+		const stop = () => setDragging(false);
+		window.addEventListener("pointerup", stop);
+		window.addEventListener("pointercancel", stop);
+		return () => {
+			window.removeEventListener("pointerup", stop);
+			window.removeEventListener("pointercancel", stop);
+		};
+	}, [dragging, setDragging]);
+
+	return (
+		<div className="group fixed inset-0 flex select-none items-center justify-center">
+			<div
+				className="relative cursor-grab active:cursor-grabbing"
+				onPointerDown={(event) => {
+					if ((event.target as HTMLElement).closest("[data-nyan-control]")) {
+						return;
+					}
+					setDragging(true);
+					void startPetDrag();
+				}}
+				onPointerEnter={() => setHovering(true)}
+				onPointerLeave={() => setHovering(false)}
+			>
+				<button
+					aria-label="Open Cline window"
+					className="absolute -left-1 -top-1 hidden size-5 items-center justify-center rounded-full bg-background/90 text-foreground shadow ring-1 ring-border group-hover:flex"
+					data-nyan-control=""
+					onClick={() => void showMainWindow()}
+					title="Open Cline"
+					type="button"
+				>
+					<AppWindow className="size-3" />
+				</button>
+				<button
+					aria-label="Hide desktop pet"
+					className="absolute -right-1 -top-1 hidden size-5 items-center justify-center rounded-full bg-background/90 text-foreground shadow ring-1 ring-border group-hover:flex"
+					data-nyan-control=""
+					onClick={() => void hidePet()}
+					title="Hide pet"
+					type="button"
+				>
+					<X className="size-3" />
+				</button>
+				{/* biome-ignore lint/performance/noImgElement: static public asset, not statically optimizable */}
+				<img
+					alt="Desktop pet"
+					className="pointer-events-none drop-shadow-lg"
+					draggable={false}
+					height={NYAN_HEIGHT}
+					src={petSrc}
+					width={NYAN_WIDTH}
+				/>
+			</div>
+			{/* biome-ignore lint/a11y/useMediaCaption: decorative background music */}
+			<audio loop preload="auto" ref={audioRef} src="/nyantune.mp3" />
+		</div>
+	);
+}

apps/examples/desktop-app/webview/components/ui/aurora-bg.tsx

@@ -0,0 +1,139 @@
+"use client";
+
+import { useMemo } from "react";
+
+interface Star {
+	left: string;
+	top: string;
+	size: number;
+	delay: string;
+	duration: string;
+	opacity: number;
+	color: string;
+}
+
+// Big blurred gradient blobs that slowly drift/rotate to fake an aurora.
+const BLOBS = [
+	{
+		id: "periwinkle-left",
+		position: "left-[-20%] bottom-[-40%] w-[70%] h-[80%]",
+		gradient:
+			"radial-gradient(ellipse at center, color-mix(in oklab, var(--brand-periwinkle) 64%, transparent), transparent 70%)",
+		duration: "11s",
+		delay: "0s",
+		reverse: false,
+	},
+	{
+		id: "violet-right",
+		position: "right-[-15%] bottom-[-40%] w-[65%] h-[85%]",
+		gradient:
+			"radial-gradient(ellipse at center, color-mix(in oklab, var(--brand-violet) 58%, transparent), transparent 70%)",
+		duration: "12.5s",
+		delay: "-12s",
+		reverse: true,
+	},
+] as const;
+
+function seededUnit(index: number, salt: number): number {
+	let value =
+		Math.imul(index + 1, 0x9e3779b1) ^ Math.imul(salt + 1, 0x85ebca6b);
+	value ^= value >>> 16;
+	value = Math.imul(value, 0x7feb352d);
+	value ^= value >>> 15;
+	value = Math.imul(value, 0x846ca68b);
+	value ^= value >>> 16;
+	return (value >>> 0) / 0x1_0000_0000;
+}
+
+/**
+ * A decorative aurora background built entirely from CSS: blurred gradient
+ * blobs drifting on keyframe animations, plus twinkling star dots. No canvas,
+ * no WebGL, no per-frame JS. Absolutely positioned to fill its nearest
+ * positioned parent; pointer events pass through.
+ *
+ * Keyframes (`aurora-drift`, `aurora-twinkle`) live in app/globals.css.
+ */
+export function AuroraBackground({ starCount = 48 }: { starCount?: number }) {
+	// The field is deterministic so server and browser markup always agree.
+	const stars = useMemo<Star[]>(
+		() =>
+			Array.from({ length: starCount }, (_, index) => {
+				// Squared skew biases stars toward the bottom, where the glow lives.
+				const r = seededUnit(index, 1);
+				const sizeRoll = seededUnit(index, 3);
+				return {
+					left: `${seededUnit(index, 2) * 100}%`,
+					top: `${100 - (1 - r * r) * 45}%`,
+					size: sizeRoll < 0.14 ? 4 : sizeRoll < 0.52 ? 3 : 2,
+					delay: `${seededUnit(index, 4) * -5}s`,
+					duration: `${3.5 + seededUnit(index, 5) * 3.5}s`,
+					opacity: 0.35 + seededUnit(index, 6) * 0.6,
+					color:
+						seededUnit(index, 7) > 0.78
+							? "var(--brand-cyan)"
+							: "color-mix(in oklab, white 92%, var(--brand-lilac))",
+				};
+			}),
+		[starCount],
+	);
+
+	return (
+		<div
+			aria-hidden="true"
+			className="pointer-events-none absolute inset-0 overflow-hidden"
+		>
+			<div
+				className="aurora-horizon absolute inset-x-[-8%] bottom-[-3%] h-[40%] opacity-60 blur-[64px]"
+				style={{
+					background:
+						"linear-gradient(90deg, color-mix(in oklab, var(--brand-lilac) 58%, transparent), color-mix(in oklab, var(--brand-magenta) 62%, transparent) 42%, color-mix(in oklab, var(--brand-periwinkle) 72%, transparent) 78%, color-mix(in oklab, var(--brand-cyan) 58%, transparent))",
+				}}
+			/>
+			<div
+				className="aurora-current absolute bottom-[3%] left-[-45%] h-[30%] w-[125%] opacity-50 blur-[46px]"
+				style={{
+					animationDelay: "-2s",
+					animationDuration: "9s",
+					background:
+						"linear-gradient(105deg, transparent 12%, color-mix(in oklab, var(--brand-magenta) 66%, transparent) 38%, color-mix(in oklab, var(--brand-periwinkle) 72%, transparent) 58%, transparent 82%)",
+				}}
+			/>
+			<div
+				className="aurora-current aurora-current-reverse absolute bottom-[-5%] right-[-42%] h-[34%] w-[120%] opacity-45 blur-[52px]"
+				style={{
+					animationDelay: "-6s",
+					animationDuration: "12s",
+					background:
+						"linear-gradient(75deg, transparent 10%, color-mix(in oklab, var(--brand-cyan) 62%, transparent) 42%, color-mix(in oklab, var(--brand-violet) 70%, transparent) 64%, transparent 88%)",
+				}}
+			/>
+			{BLOBS.map((blob) => (
+				<div
+					key={blob.id}
+					className={`aurora-motion absolute blur-[64px] ${blob.reverse ? "aurora-motion-reverse" : ""} ${blob.position}`}
+					style={{
+						background: blob.gradient,
+						animationDuration: blob.duration,
+						animationDelay: blob.delay,
+					}}
+				/>
+			))}
+			{stars.map((s) => (
+				<span
+					key={`${s.left}-${s.top}`}
+					className="aurora-star absolute rounded-[1px]"
+					style={{
+						left: s.left,
+						top: s.top,
+						width: s.size,
+						height: s.size,
+						background: s.color,
+						opacity: s.opacity,
+						animationDelay: s.delay,
+						animationDuration: s.duration,
+					}}
+				/>
+			))}
+		</div>
+	);
+}

apps/examples/desktop-app/webview/components/ui/markdown-highlighter.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "vitest";
+import {
+	markdownCodeHighlighter,
+	SUPPORTED_MARKDOWN_LANGUAGES,
+} from "./markdown-highlighter";
+
+function highlight(code: string, language: "typescript") {
+	return new Promise<
+		NonNullable<ReturnType<typeof markdownCodeHighlighter.highlight>>
+	>((resolve) => {
+		const immediate = markdownCodeHighlighter.highlight(
+			{ code, language, themes: ["github-light", "github-dark"] },
+			resolve,
+		);
+		if (immediate) resolve(immediate);
+	});
+}
+
+describe("markdownCodeHighlighter", () => {
+	test("keeps the syntax bundle to the shared supported language set", () => {
+		expect(SUPPORTED_MARKDOWN_LANGUAGES).toEqual([
+			"bash",
+			"css",
+			"diff",
+			"html",
+			"javascript",
+			"json",
+			"jsonc",
+			"jsx",
+			"markdown",
+			"python",
+			"shellscript",
+			"tsx",
+			"typescript",
+			"yaml",
+		]);
+		expect(markdownCodeHighlighter.supportsLanguage("ts")).toBe(true);
+		expect(markdownCodeHighlighter.supportsLanguage("rust")).toBe(false);
+	});
+
+	test("loads a supported grammar and returns themed tokens", async () => {
+		const result = await highlight("const answer: number = 42;", "typescript");
+
+		expect(
+			result.tokens
+				.flat()
+				.map((token) => token.content)
+				.join(""),
+		).toBe("const answer: number = 42;");
+		expect(result.tokens.flat().some((token) => token.htmlStyle?.color)).toBe(
+			true,
+		);
+	});
+});

apps/examples/desktop-app/webview/components/ui/markdown-highlighter.ts

@@ -0,0 +1,237 @@
+import type {
+	HighlighterCore,
+	LanguageRegistration,
+	ThemeRegistration,
+} from "shiki/core";
+import type { CodeHighlighterPlugin } from "streamdown";
+
+type HighlightResult = NonNullable<
+	ReturnType<CodeHighlighterPlugin["highlight"]>
+>;
+
+export const SUPPORTED_MARKDOWN_LANGUAGES = [
+	"bash",
+	"css",
+	"diff",
+	"html",
+	"javascript",
+	"json",
+	"jsonc",
+	"jsx",
+	"markdown",
+	"python",
+	"shellscript",
+	"tsx",
+	"typescript",
+	"yaml",
+] as const;
+
+type SupportedMarkdownLanguage = (typeof SUPPORTED_MARKDOWN_LANGUAGES)[number];
+
+const SUPPORTED_LANGUAGE_SET = new Set<string>(SUPPORTED_MARKDOWN_LANGUAGES);
+
+const LANGUAGE_ALIASES: Record<string, SupportedMarkdownLanguage> = {
+	cjs: "javascript",
+	console: "shellscript",
+	htm: "html",
+	js: "javascript",
+	json5: "jsonc",
+	md: "markdown",
+	mjs: "javascript",
+	py: "python",
+	sh: "shellscript",
+	shell: "shellscript",
+	ts: "typescript",
+	yml: "yaml",
+};
+
+const LANGUAGE_LOADERS: Record<
+	SupportedMarkdownLanguage,
+	() => Promise<LanguageRegistration[]>
+> = {
+	bash: () => import("@shikijs/langs/bash").then((module) => module.default),
+	css: () => import("@shikijs/langs/css").then((module) => module.default),
+	diff: () => import("@shikijs/langs/diff").then((module) => module.default),
+	html: () => import("@shikijs/langs/html").then((module) => module.default),
+	javascript: () =>
+		import("@shikijs/langs/javascript").then((module) => module.default),
+	json: () => import("@shikijs/langs/json").then((module) => module.default),
+	jsonc: () => import("@shikijs/langs/jsonc").then((module) => module.default),
+	jsx: () => import("@shikijs/langs/jsx").then((module) => module.default),
+	markdown: () =>
+		import("@shikijs/langs/markdown").then((module) => module.default),
+	python: () =>
+		import("@shikijs/langs/python").then((module) => module.default),
+	shellscript: () =>
+		import("@shikijs/langs/shellscript").then((module) => module.default),
+	tsx: () => import("@shikijs/langs/tsx").then((module) => module.default),
+	typescript: () =>
+		import("@shikijs/langs/typescript").then((module) => module.default),
+	yaml: () => import("@shikijs/langs/yaml").then((module) => module.default),
+};
+
+const LIGHT_THEME = "github-light";
+const DARK_THEME = "github-dark";
+const MAX_CACHED_RESULTS = 256;
+
+let highlighterPromise: Promise<HighlighterCore> | undefined;
+let themesPromise: Promise<void> | undefined;
+const languagePromises = new Map<SupportedMarkdownLanguage, Promise<void>>();
+const resultCache = new Map<string, HighlightResult>();
+const pendingHighlights = new Map<string, Promise<HighlightResult>>();
+const loggedFailures = new Set<string>();
+
+function normalizeLanguage(language: string): SupportedMarkdownLanguage | null {
+	const normalized = language.trim().toLowerCase();
+	if (!normalized) return null;
+	const aliased = LANGUAGE_ALIASES[normalized] ?? normalized;
+	return SUPPORTED_LANGUAGE_SET.has(aliased)
+		? (aliased as SupportedMarkdownLanguage)
+		: null;
+}
+
+function getHighlighter(): Promise<HighlighterCore> {
+	if (!highlighterPromise) {
+		highlighterPromise = Promise.all([
+			import("shiki/core"),
+			import("shiki/engine/javascript"),
+		]).then(([core, engine]) =>
+			core.createHighlighterCore({
+				engine: engine.createJavaScriptRegexEngine({ forgiving: true }),
+			}),
+		);
+	}
+	return highlighterPromise;
+}
+
+function ensureThemes(highlighter: HighlighterCore): Promise<void> {
+	if (!themesPromise) {
+		themesPromise = Promise.all([
+			import("@shikijs/themes/github-light").then((module) => module.default),
+			import("@shikijs/themes/github-dark").then((module) => module.default),
+		]).then((themes: ThemeRegistration[]) => highlighter.loadTheme(...themes));
+	}
+	return themesPromise;
+}
+
+function ensureLanguage(
+	highlighter: HighlighterCore,
+	language: SupportedMarkdownLanguage,
+): Promise<void> {
+	const existing = languagePromises.get(language);
+	if (existing) return existing;
+
+	const loading = LANGUAGE_LOADERS[language]().then((registrations) =>
+		highlighter.loadLanguage(...registrations),
+	);
+	languagePromises.set(language, loading);
+	return loading;
+}
+
+function rawHighlight(code: string): HighlightResult {
+	return {
+		bg: "transparent",
+		fg: "inherit",
+		tokens: code.split("\n").map((line) =>
+			line
+				? [
+						{
+							bgColor: "transparent",
+							color: "inherit",
+							content: line,
+							htmlStyle: {},
+							offset: 0,
+						},
+					]
+				: [],
+		),
+	};
+}
+
+function cacheResult(key: string, result: HighlightResult): void {
+	resultCache.delete(key);
+	resultCache.set(key, result);
+	if (resultCache.size <= MAX_CACHED_RESULTS) return;
+
+	const oldestKey = resultCache.keys().next().value;
+	if (oldestKey !== undefined) resultCache.delete(oldestKey);
+}
+
+function reportHighlightFailure(
+	language: SupportedMarkdownLanguage,
+	error: unknown,
+): void {
+	if (loggedFailures.has(language)) return;
+	loggedFailures.add(language);
+	console.warn(
+		`Syntax highlighting unavailable for ${language}; rendering plain code.`,
+		error,
+	);
+}
+
+function loadHighlight(
+	code: string,
+	language: SupportedMarkdownLanguage,
+): Promise<HighlightResult> {
+	const cacheKey = `${language}\0${code}`;
+	const cached = resultCache.get(cacheKey);
+	if (cached) return Promise.resolve(cached);
+
+	const pending = pendingHighlights.get(cacheKey);
+	if (pending) return pending;
+
+	const loading = getHighlighter()
+		.then(async (highlighter) => {
+			await ensureThemes(highlighter);
+			await ensureLanguage(highlighter, language);
+			const result = highlighter.codeToTokens(code, {
+				lang: language,
+				themes: {
+					dark: DARK_THEME,
+					light: LIGHT_THEME,
+				},
+			});
+			return {
+				bg: result.bg,
+				fg: result.fg,
+				rootStyle: result.rootStyle,
+				tokens: result.tokens,
+			} satisfies HighlightResult;
+		})
+		.catch((error: unknown) => {
+			reportHighlightFailure(language, error);
+			return rawHighlight(code);
+		})
+		.then((result) => {
+			cacheResult(cacheKey, result);
+			return result;
+		})
+		.finally(() => {
+			pendingHighlights.delete(cacheKey);
+		});
+
+	pendingHighlights.set(cacheKey, loading);
+	return loading;
+}
+
+export const markdownCodeHighlighter = {
+	getSupportedLanguages: () => [...SUPPORTED_MARKDOWN_LANGUAGES],
+	getThemes: () => [LIGHT_THEME, DARK_THEME],
+	highlight: ({ code, language }, callback) => {
+		const normalizedLanguage = normalizeLanguage(language);
+		if (!normalizedLanguage) return rawHighlight(code);
+
+		const cacheKey = `${normalizedLanguage}\0${code}`;
+		const cached = resultCache.get(cacheKey);
+		if (cached) return cached;
+
+		const loading = loadHighlight(code, normalizedLanguage);
+		if (callback) {
+			void loading.then((result) => callback(result));
+		}
+		return null;
+	},
+	name: "shiki",
+	supportsLanguage: (language) => normalizeLanguage(language) !== null,
+	type: "code-highlighter",
+} satisfies CodeHighlighterPlugin;

apps/examples/desktop-app/webview/components/ui/markdown.interactions.test.tsx

@@ -0,0 +1,208 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { MarkdownLinkSafetyModal, MemoizedMarkdown } from "./markdown";
+
+const originalClipboard = Object.getOwnPropertyDescriptor(
+	navigator,
+	"clipboard",
+);
+
+let writeText: ReturnType<typeof vi.fn>;
+let openWindow: ReturnType<typeof vi.fn<typeof window.open>>;
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+	writeText = vi.fn().mockResolvedValue(undefined);
+	Object.defineProperty(navigator, "clipboard", {
+		configurable: true,
+		value: { writeText },
+	});
+	openWindow = vi.fn<typeof window.open>(() => null);
+	vi.spyOn(window, "open").mockImplementation(openWindow);
+});
+
+afterEach(async () => {
+	await act(async () => root.unmount());
+	container.remove();
+	vi.restoreAllMocks();
+	if (originalClipboard) {
+		Object.defineProperty(navigator, "clipboard", originalClipboard);
+	} else {
+		Reflect.deleteProperty(navigator, "clipboard");
+	}
+});
+
+async function renderMarkdown(
+	props: Parameters<typeof MemoizedMarkdown>[0],
+): Promise<void> {
+	await act(async () => root.render(<MemoizedMarkdown {...props} />));
+}
+
+async function click(element: Element): Promise<void> {
+	await act(async () => {
+		element.dispatchEvent(
+			new MouseEvent("click", { bubbles: true, cancelable: true }),
+		);
+		await new Promise((resolve) => setTimeout(resolve, 0));
+	});
+}
+
+async function dispatchMouseEvent(
+	element: Element,
+	type: "auxclick" | "contextmenu",
+	button: number,
+): Promise<void> {
+	await act(async () => {
+		element.dispatchEvent(
+			new MouseEvent(type, { bubbles: true, button, cancelable: true }),
+		);
+		await new Promise((resolve) => setTimeout(resolve, 0));
+	});
+}
+
+function getButton(label: string): HTMLButtonElement {
+	const button = [
+		...document.querySelectorAll<HTMLButtonElement>("button"),
+	].find((candidate) => candidate.textContent?.trim() === label);
+	expect(button).toBeDefined();
+	return button as HTMLButtonElement;
+}
+
+describe("MemoizedMarkdown interactions", () => {
+	test("confirms and closes an external link dialog exactly once", async () => {
+		const onClose = vi.fn();
+		const onConfirm = vi.fn();
+		await act(async () => {
+			root.render(
+				<MarkdownLinkSafetyModal
+					isOpen
+					onClose={onClose}
+					onConfirm={onConfirm}
+					url="https://example.com/review"
+				/>,
+			);
+		});
+
+		await click(getButton("Open link"));
+		await vi.waitFor(() => {
+			expect(onConfirm).toHaveBeenCalledOnce();
+			expect(onClose).toHaveBeenCalledOnce();
+		});
+	});
+
+	test("requires confirmation before opening an external link", async () => {
+		const url = "https://example.com/review?source=cline";
+		await renderMarkdown({ content: `[Review docs](${url})` });
+		const link = await vi.waitFor(() => {
+			const renderedLink = container.querySelector<HTMLElement>(
+				'[data-streamdown="link"]',
+			);
+			expect(renderedLink).not.toBeNull();
+			return renderedLink as HTMLElement;
+		});
+		expect(link.tagName).toBe("A");
+		expect(link.getAttribute("href")).toBe("#confirm-external-link");
+
+		await dispatchMouseEvent(link, "contextmenu", 2);
+		expect(openWindow).not.toHaveBeenCalled();
+		expect(document.querySelector('[role="alertdialog"]')).toBeNull();
+
+		await dispatchMouseEvent(link, "auxclick", 1);
+		await vi.waitFor(() => {
+			expect(document.querySelector('[role="alertdialog"]')).not.toBeNull();
+		});
+		await click(getButton("Cancel"));
+
+		await click(link);
+		await vi.waitFor(() => {
+			expect(document.querySelector('[role="alertdialog"]')).not.toBeNull();
+			expect(document.body.textContent).toContain(url);
+		});
+
+		await click(getButton("Cancel"));
+		await vi.waitFor(() => {
+			expect(document.querySelector('[role="alertdialog"]')).toBeNull();
+		});
+		expect(openWindow).not.toHaveBeenCalled();
+
+		await click(link);
+		await vi.waitFor(() => {
+			expect(document.querySelector('[role="alertdialog"]')).not.toBeNull();
+		});
+		await click(getButton("Open link"));
+
+		expect(openWindow).toHaveBeenCalledTimes(1);
+		expect(openWindow).toHaveBeenCalledWith(url, "_blank", "noreferrer");
+		await vi.waitFor(() => {
+			expect(document.querySelector('[role="alertdialog"]')).toBeNull();
+		});
+	});
+
+	test("keeps same-document links navigable without a confirmation", async () => {
+		await renderMarkdown({ content: "[Details](#details)" });
+		const link = container.querySelector<HTMLAnchorElement>(
+			'[data-streamdown="link"]',
+		);
+
+		expect(link?.getAttribute("href")).toBe("#details");
+		await click(link as HTMLAnchorElement);
+		expect(document.querySelector('[role="alertdialog"]')).toBeNull();
+		expect(openWindow).not.toHaveBeenCalled();
+	});
+
+	test("copies fenced code through the Clipboard API", async () => {
+		const source = "const answer = 42;";
+		await renderMarkdown({
+			content: `\`\`\`text\n${source}\n\`\`\``,
+		});
+		const copyButton = await vi.waitFor(() => {
+			const button = container.querySelector<HTMLButtonElement>(
+				'[data-streamdown="code-block-copy-button"]',
+			);
+			expect(button).not.toBeNull();
+			return button as HTMLButtonElement;
+		});
+
+		await click(copyButton);
+		await vi.waitFor(() => {
+			expect(writeText).toHaveBeenCalledWith(`${source}\n`);
+		});
+	});
+
+	test("rerenders incomplete streaming Markdown as completed static Markdown", async () => {
+		await renderMarkdown({
+			content: "```text\nconst answer =",
+			streaming: true,
+		});
+
+		await vi.waitFor(() => {
+			const codeBlock = container.querySelector(
+				'[data-streamdown="code-block"]',
+			);
+			expect(codeBlock?.getAttribute("data-incomplete")).toBe("true");
+		});
+
+		await renderMarkdown({
+			content: "```text\nconst answer = 42;\n```\n\nCompleted.",
+			streaming: false,
+		});
+
+		await vi.waitFor(() => {
+			const codeBlock = container.querySelector(
+				'[data-streamdown="code-block"]',
+			);
+			expect(codeBlock).not.toBeNull();
+			expect(codeBlock?.getAttribute("data-incomplete")).toBeNull();
+			expect(container.textContent).toContain("const answer = 42;");
+			expect(container.textContent).toContain("Completed.");
+		});
+	});
+});

apps/examples/desktop-app/webview/components/ui/markdown.test.tsx

@@ -0,0 +1,105 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, test } from "vitest";
+import { MemoizedMarkdown } from "./markdown";
+
+describe("MemoizedMarkdown", () => {
+	test("renders structured GFM content and blocks remote images", () => {
+		const html = renderToStaticMarkup(
+			<MemoizedMarkdown
+				content={`# Review
+
+| Surface | Status |
+| --- | --- |
+| Code | Ready |
+
+\`\`\`typescript
+const ready = true;
+\`\`\`
+
+![remote image](https://example.com/tracker.png)`}
+			/>,
+		);
+
+		expect(html).toContain('data-streamdown="heading-1"');
+		expect(html).toContain('data-streamdown="table-wrapper"');
+		expect(html).toContain('data-streamdown="code-block"');
+		expect(html).toContain('data-streamdown="blocked-image"');
+		expect(html).toContain("External image blocked for privacy");
+		expect(html).not.toContain("<img");
+	});
+
+	test("renders app-local images", () => {
+		const html = renderToStaticMarkup(
+			<MemoizedMarkdown
+				content={`![local](/images/local.png)
+
+![second local](/images/second-local.png)`}
+			/>,
+		);
+
+		expect(html.match(/<img/g)).toHaveLength(2);
+		expect(html).toContain('src="/images/local.png"');
+		expect(html).toContain('src="/images/second-local.png"');
+		expect(html).not.toContain('data-streamdown="blocked-image"');
+	});
+
+	test("repairs an unfinished code fence while streaming", () => {
+		const html = renderToStaticMarkup(
+			<MemoizedMarkdown
+				content={"```typescript\nconst stillStreaming = true;"}
+				streaming
+			/>,
+		);
+
+		expect(html).toContain('data-streamdown="code-block"');
+		expect(html).toContain("stillStreaming");
+	});
+
+	test("routes external links through confirmation controls", () => {
+		const html = renderToStaticMarkup(
+			<MemoizedMarkdown content="[Review](https://example.com/review)" />,
+		);
+
+		expect(html).toContain('data-streamdown="link"');
+		expect(html).toContain("Review");
+		expect(html).toContain('href="#confirm-external-link"');
+		expect(html).toContain('aria-haspopup="dialog"');
+		expect(html).not.toContain('href="https://example.com/review"');
+	});
+
+	test("leaves app-local and fragment links navigable", () => {
+		const html = renderToStaticMarkup(
+			<MemoizedMarkdown content="[Details](#details) [Home](/)" />,
+		);
+
+		expect(html).toContain('href="#details"');
+		expect(html).toContain('href="/"');
+		expect(html).not.toContain('aria-haspopup="dialog"');
+	});
+
+	test("blocks scheme-less hostnames before they reach link rendering", () => {
+		const html = renderToStaticMarkup(
+			<MemoizedMarkdown content="[Review](example.com/path)" />,
+		);
+
+		expect(html).toContain("Review");
+		expect(html).toContain("blocked");
+		expect(html).not.toContain("<a");
+		expect(html).not.toContain('data-streamdown="link"');
+	});
+
+	test("does not expose unsafe script URLs or raw scripts", () => {
+		const html = renderToStaticMarkup(
+			<MemoizedMarkdown
+				content={
+					'[unsafe](javascript:alert("no"))\n\n![embedded](data:image/png;base64,iVBORw0KGgo=)\n\n![file](file:///etc/passwd)\n\n<script>window.pwned = true</script>'
+				}
+			/>,
+		);
+
+		expect(html).not.toContain("javascript:");
+		expect(html).not.toContain("data:image");
+		expect(html).not.toContain("file:///etc/passwd");
+		expect(html).not.toContain("<script");
+	});
+});

apps/examples/desktop-app/webview/components/ui/markdown.tsx

@@ -1,45 +1,216 @@
-import { marked } from "marked";
-import { memo, useMemo } from "react";
-import ReactMarkdown from "react-markdown";
-import remarkGfm from "remark-gfm";
+import { cjk } from "@streamdown/cjk";
+import type { ComponentProps, MouseEvent } from "react";
+import { memo, useState } from "react";
+import {
+	type Components,
+	type ControlsConfig,
+	type ExtraProps,
+	type LinkSafetyModalProps,
+	Streamdown,
+} from "streamdown";
+import {
+	AlertDialog,
+	AlertDialogAction,
+	AlertDialogCancel,
+	AlertDialogContent,
+	AlertDialogDescription,
+	AlertDialogFooter,
+	AlertDialogHeader,
+	AlertDialogTitle,
+} from "./alert-dialog";
+import { markdownCodeHighlighter } from "./markdown-highlighter";
 
-const MemoizedMarkdownBlock = memo(
-	({ content }: { content: string }) => {
-		return (
-			<div className="markdown">
-				<ReactMarkdown remarkPlugins={[remarkGfm]}>{content}</ReactMarkdown>
-			</div>
-		);
-	},
-	(prevProps, nextProps) => {
-		if (prevProps.content !== nextProps.content) return false;
-		return true;
-	},
-);
+const streamdownPlugins = { cjk, code: markdownCodeHighlighter };
+const streamdownControls = {
+	code: { copy: true, download: false },
+	mermaid: false,
+	table: false,
+} satisfies ControlsConfig;
 
-MemoizedMarkdownBlock.displayName = "MemoizedMarkdownBlock";
-
-export function parseMarkdownIntoBlocks(markdown: string): string[] {
-	const tokens = marked.lexer(markdown);
-	return tokens.map((token) => token.raw);
+export function MarkdownLinkSafetyModal({
+	isOpen,
+	onClose,
+	onConfirm,
+	url,
+}: LinkSafetyModalProps) {
+	return (
+		<AlertDialog
+			onOpenChange={(open) => {
+				if (!open) onClose();
+			}}
+			open={isOpen}
+		>
+			<AlertDialogContent>
+				<AlertDialogHeader>
+					<AlertDialogTitle>Open external link?</AlertDialogTitle>
+					<AlertDialogDescription>
+						You are about to leave Cline and visit this address.
+					</AlertDialogDescription>
+				</AlertDialogHeader>
+				<div className="max-h-32 overflow-y-auto wrap-break-word rounded-md bg-muted p-3 font-mono text-sm">
+					{url}
+				</div>
+				<AlertDialogFooter>
+					<AlertDialogCancel>Cancel</AlertDialogCancel>
+					<AlertDialogAction onClick={onConfirm}>Open link</AlertDialogAction>
+				</AlertDialogFooter>
+			</AlertDialogContent>
+		</AlertDialog>
+	);
 }
 
-export const MemoizedMarkdown = memo(
-	({ content, id }: { content: string; id: string }) => {
-		const blocks = useMemo(() => parseMarkdownIntoBlocks(content), [content]);
-		const occurrences = new Map<string, number>();
+type MarkdownLinkProps = ComponentProps<"a"> & ExtraProps;
 
-		return blocks.map((block) => {
-			const occurrence = (occurrences.get(block) ?? 0) + 1;
-			occurrences.set(block, occurrence);
-			return (
-				<MemoizedMarkdownBlock
-					content={block}
-					key={`${id}-block_${occurrence}-${block}`}
-				/>
-			);
-		});
-	},
+function SafeMarkdownLink({
+	children,
+	className,
+	href,
+	node: _node,
+	rel: _rel,
+	target: _target,
+	title,
+	...props
+}: MarkdownLinkProps) {
+	const [isOpen, setIsOpen] = useState(false);
+	const isIncomplete = href === "streamdown:incomplete-link";
+	const url = isIncomplete ? undefined : href;
+
+	if (!url) {
+		return (
+			<span
+				className={className}
+				data-incomplete={isIncomplete}
+				data-streamdown="link"
+			>
+				{children}
+			</span>
+		);
+	}
+
+	const isAppLink =
+		url.startsWith("#") ||
+		(url.startsWith("/") && !url.startsWith("//")) ||
+		url.startsWith("./") ||
+		url.startsWith("../") ||
+		(!/^[a-z][a-z\d+.-]*:/i.test(url) && !url.startsWith("//"));
+
+	if (isAppLink) {
+		return (
+			<a
+				{...props}
+				className={`wrap-anywhere font-medium text-primary underline ${className ?? ""}`}
+				data-streamdown="link"
+				href={url}
+				title={title}
+			>
+				{children}
+			</a>
+		);
+	}
+
+	const openConfirmation = (event: MouseEvent<HTMLAnchorElement>) => {
+		event.preventDefault();
+		setIsOpen(true);
+	};
+	const confirmMiddleClick = (event: MouseEvent<HTMLAnchorElement>) => {
+		if (event.button === 1) openConfirmation(event);
+	};
+
+	return (
+		<>
+			{/* biome-ignore lint/a11y/useValidAnchor: External Markdown retains native link semantics while confirmation withholds the live destination. */}
+			<a
+				{...props}
+				aria-haspopup="dialog"
+				className={`wrap-anywhere font-medium text-primary underline ${className ?? ""}`}
+				data-streamdown="link"
+				href="#confirm-external-link"
+				onAuxClick={confirmMiddleClick}
+				onClick={openConfirmation}
+				title={title ?? url}
+			>
+				{children}
+			</a>
+			<MarkdownLinkSafetyModal
+				isOpen={isOpen}
+				onClose={() => setIsOpen(false)}
+				onConfirm={() => window.open(url, "_blank", "noreferrer")}
+				url={url}
+			/>
+		</>
+	);
+}
+
+type MarkdownImageProps =
+	| (ComponentProps<"img"> & ExtraProps)
+	| (Record<string, unknown> & ExtraProps);
+
+const remoteImagePattern = /^(?:https?:)?[\\/]{2}/i;
+
+function isSafeMarkdownImageSource(source: string): boolean {
+	const normalized = source.trim();
+	if (!normalized || remoteImagePattern.test(normalized)) return false;
+
+	// Streamdown's hardened URL policy accepts app-root paths. Keeping the rule
+	// this narrow prevents model-authored Markdown from making hidden requests.
+	return normalized.startsWith("/");
+}
+
+function MarkdownImage({ alt, height, src, title, width }: MarkdownImageProps) {
+	const label = typeof alt === "string" ? alt.trim() : "";
+	const source = typeof src === "string" ? src.trim() : "";
+
+	if (source && isSafeMarkdownImageSource(source)) {
+		return (
+			// biome-ignore lint/performance/noImgElement: Markdown can reference runtime app assets that Next Image cannot statically optimize.
+			<img
+				alt={label}
+				className="my-4 max-w-full rounded-lg"
+				data-streamdown="image"
+				height={typeof height === "number" ? height : undefined}
+				loading="lazy"
+				src={source}
+				title={typeof title === "string" ? title : undefined}
+				width={typeof width === "number" ? width : undefined}
+			/>
+		);
+	}
+
+	return (
+		<span data-streamdown="blocked-image" role="note">
+			External image blocked for privacy{label ? `: ${label}` : ""}
+		</span>
+	);
+}
+
+const markdownComponents = {
+	a: SafeMarkdownLink,
+	img: MarkdownImage,
+} satisfies Components;
+
+export const MemoizedMarkdown = memo(
+	({
+		content,
+		streaming = false,
+	}: {
+		content: string;
+		streaming?: boolean;
+	}) => (
+		<Streamdown
+			className="cline-markdown"
+			components={markdownComponents}
+			controls={streamdownControls}
+			dir="auto"
+			isAnimating={streaming}
+			lineNumbers
+			mode={streaming ? "streaming" : "static"}
+			normalizeHtmlIndentation
+			parseIncompleteMarkdown={streaming}
+			plugins={streamdownPlugins}
+		>
+			{content}
+		</Streamdown>
+	),
 );
 
 MemoizedMarkdown.displayName = "MemoizedMarkdown";

apps/examples/desktop-app/webview/components/ui/sidebar.tsx

@@ -26,7 +26,7 @@ import { cn } from "@/lib/utils";
 
 const SIDEBAR_COOKIE_NAME = "sidebar_state";
 const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
-const SIDEBAR_WIDTH = 256;
+const SIDEBAR_WIDTH = 240;
 const SIDEBAR_WIDTH_MOBILE = "18rem";
 const SIDEBAR_WIDTH_ICON = "3rem";
 const SIDEBAR_KEYBOARD_SHORTCUT = "b";
@@ -313,8 +313,8 @@ function Sidebar({
 				className={cn(
 					"fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex",
 					side === "left"
-						? "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]"
-						: "right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",
+						? "left-0 group-data-[collapsible=offcanvas]:-left-(--sidebar-width)"
+						: "right-0 group-data-[collapsible=offcanvas]:-right-(--sidebar-width)",
 					// Adjust the padding for floating and inset variants.
 					variant === "floating" || variant === "inset"
 						? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"

apps/examples/desktop-app/webview/components/ui/slider.tsx

@@ -26,6 +26,7 @@ function Slider({
 
 	return (
 		<SliderPrimitive.Root
+			data-interactive=""
 			data-slot="slider"
 			defaultValue={defaultValue}
 			value={value}

apps/examples/desktop-app/webview/components/views/chat/chat-input-bar.test.tsx

@@ -0,0 +1,209 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { WorkspaceProvider } from "@/contexts/workspace-context";
+import type { ChatSessionStatus } from "@/lib/chat-schema";
+import { ChatInputBar } from "./chat-input-bar";
+
+const { loadProviderModelCatalogMock, loadProviderModelsMock } = vi.hoisted(
+	() => ({
+		loadProviderModelCatalogMock: vi.fn(),
+		loadProviderModelsMock: vi.fn(),
+	}),
+);
+
+vi.mock("@/lib/provider-model-catalog", () => ({
+	loadProviderModelCatalog: loadProviderModelCatalogMock,
+	loadProviderModels: loadProviderModelsMock,
+}));
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+	loadProviderModelCatalogMock.mockReset().mockResolvedValue({
+		providers: [],
+		enabledProviderIds: ["cline"],
+		providerModels: { cline: ["test-model"] },
+		providerReasoningModels: { cline: [] },
+	});
+	loadProviderModelsMock.mockReset().mockResolvedValue([]);
+	HTMLElement.prototype.scrollIntoView = vi.fn();
+	HTMLElement.prototype.hasPointerCapture = vi.fn(() => false);
+	HTMLElement.prototype.setPointerCapture = vi.fn();
+	HTMLElement.prototype.releasePointerCapture = vi.fn();
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+});
+
+afterEach(async () => {
+	await act(async () => root.unmount());
+	container.remove();
+	vi.restoreAllMocks();
+});
+
+describe("ChatInputBar", () => {
+	it("preserves an explicit High selection across capability and status updates", async () => {
+		const onReasoningChange = vi.fn();
+		const render = async (status: ChatSessionStatus) => {
+			await act(async () => {
+				root.render(
+					<WorkspaceProvider
+						value={{
+							workspaceRoot: "/workspace/cline",
+							workspaces: ["/workspace/cline"],
+							listWorkspaces: vi.fn(async () => ["/workspace/cline"]),
+							refreshWorkspaces: vi.fn(async () => undefined),
+							switchWorkspace: vi.fn(async () => true),
+							pickWorkspaceDirectory: vi.fn(async () => null),
+						}}
+					>
+						<ChatInputBar
+							attachments={[]}
+							gitBranch="main"
+							mode="act"
+							model="test-model"
+							onAbort={vi.fn()}
+							onAttachFiles={vi.fn()}
+							onEditPromptInQueue={vi.fn()}
+							onListGitBranches={vi.fn(async () => ({
+								current: "main",
+								branches: ["main"],
+							}))}
+							onModeToggle={vi.fn()}
+							onModelChange={vi.fn()}
+							onPromptInputChange={vi.fn()}
+							onProviderChange={vi.fn()}
+							onReasoningChange={onReasoningChange}
+							onRemoveAttachment={vi.fn()}
+							onSend={vi.fn()}
+							onSteerPromptInQueue={vi.fn()}
+							onSwitchGitBranch={vi.fn(async () => true)}
+							onUndoPromptInQueue={vi.fn()}
+							promptInput=""
+							promptsInQueue={[]}
+							provider="cline"
+							reasoningEffort="high"
+							status={status}
+							summary={{ toolCalls: 0, tokensIn: 0, tokensOut: 0 }}
+							thinking
+						/>
+					</WorkspaceProvider>,
+				);
+				await Promise.resolve();
+			});
+		};
+
+		await render("idle");
+		await vi.waitFor(() => {
+			const trigger = container.querySelector<HTMLButtonElement>(
+				'[aria-label="Thinking level"]',
+			);
+			expect(trigger?.textContent).toContain("High");
+			expect(trigger?.disabled).toBe(true);
+		});
+		await render("starting");
+		expect(container.querySelector('[aria-label="Stop agent"]')).toBeNull();
+		await render("running");
+		expect(container.querySelector('[aria-label="Stop agent"]')).not.toBeNull();
+
+		expect(onReasoningChange).not.toHaveBeenCalled();
+		const workspaceTrigger = container.querySelector("#git-branch-btn");
+		expect(workspaceTrigger?.parentElement?.parentElement?.className).toContain(
+			"overflow-visible",
+		);
+		expect(
+			workspaceTrigger?.parentElement?.parentElement?.className,
+		).not.toContain("truncate");
+	});
+
+	it("selects High from the supported model thinking menu", async () => {
+		loadProviderModelCatalogMock.mockResolvedValue({
+			providers: [],
+			enabledProviderIds: ["cline"],
+			providerModels: { cline: ["test-model"] },
+			providerReasoningModels: { cline: ["test-model"] },
+		});
+		const onReasoningChange = vi.fn();
+		await act(async () => {
+			root.render(
+				<WorkspaceProvider
+					value={{
+						workspaceRoot: "/workspace/cline",
+						workspaces: ["/workspace/cline"],
+						listWorkspaces: vi.fn(async () => ["/workspace/cline"]),
+						refreshWorkspaces: vi.fn(async () => undefined),
+						switchWorkspace: vi.fn(async () => true),
+						pickWorkspaceDirectory: vi.fn(async () => null),
+					}}
+				>
+					<ChatInputBar
+						attachments={[]}
+						gitBranch="main"
+						mode="act"
+						model="test-model"
+						onAbort={vi.fn()}
+						onAttachFiles={vi.fn()}
+						onEditPromptInQueue={vi.fn()}
+						onListGitBranches={vi.fn(async () => ({
+							current: "main",
+							branches: ["main"],
+						}))}
+						onModeToggle={vi.fn()}
+						onModelChange={vi.fn()}
+						onPromptInputChange={vi.fn()}
+						onProviderChange={vi.fn()}
+						onReasoningChange={onReasoningChange}
+						onRemoveAttachment={vi.fn()}
+						onSend={vi.fn()}
+						onSteerPromptInQueue={vi.fn()}
+						onSwitchGitBranch={vi.fn(async () => true)}
+						onUndoPromptInQueue={vi.fn()}
+						promptInput=""
+						promptsInQueue={[]}
+						provider="cline"
+						reasoningEffort="low"
+						status="idle"
+						summary={{ toolCalls: 0, tokensIn: 0, tokensOut: 0 }}
+						thinking
+					/>
+				</WorkspaceProvider>,
+			);
+		});
+		const trigger = await vi.waitFor(() => {
+			const element = container.querySelector<HTMLButtonElement>(
+				'[aria-label="Thinking level"]',
+			);
+			expect(element?.disabled).toBe(false);
+			return element as HTMLButtonElement;
+		});
+		await act(async () => {
+			trigger.dispatchEvent(
+				new MouseEvent("pointerdown", { bubbles: true, cancelable: true }),
+			);
+			trigger.click();
+		});
+		const highOption = await vi.waitFor(() => {
+			const element = [
+				...document.querySelectorAll<HTMLElement>('[role="option"]'),
+			].find((option) => option.textContent?.includes("High"));
+			expect(element).toBeDefined();
+			return element as HTMLElement;
+		});
+		await act(async () => {
+			highOption.dispatchEvent(
+				new MouseEvent("pointerup", { bubbles: true, cancelable: true }),
+			);
+			highOption.click();
+		});
+
+		expect(onReasoningChange).toHaveBeenCalledWith({
+			thinking: true,
+			reasoningEffort: "high",
+		});
+	});
+});

apps/examples/desktop-app/webview/components/views/chat/chat-input-bar.tsx

@@ -7,22 +7,19 @@ import {
 	ChevronDown,
 	CircleStop,
 	Coins,
-	Mic,
 	Paperclip,
 	Pencil,
-	RotateCcw,
 	Undo2,
 	X,
 } from "lucide-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
-	Combobox,
-	ComboboxContent,
-	ComboboxEmpty,
-	ComboboxInput,
-	ComboboxItem,
-	ComboboxList,
-} from "@/components/ui/combobox";
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "@/components/ui/select";
 import { useWorkspace } from "@/contexts/workspace-context";
 import type { PromptInQueue } from "@/hooks/chat-session/types";
 import type { ChatSessionConfig, ChatSessionStatus } from "@/lib/chat-schema";
@@ -37,6 +34,7 @@ import {
 	loadProviderModels,
 } from "@/lib/provider-model-catalog";
 import { cn } from "@/lib/utils";
+import { SearchableSelect } from "./searchable-select";
 import { WorkspaceSelector } from "./workspace-selector";
 
 type ActiveMention = {
@@ -188,6 +186,7 @@ function getActiveSlash(input: string, cursor: number): ActiveSlash | null {
 }
 
 type ChatInputBarProps = {
+	variant?: "conversation" | "welcome";
 	status: ChatSessionStatus;
 	provider: string;
 	model: string;
@@ -203,12 +202,10 @@ type ChatInputBarProps = {
 	onReasoningChange: (
 		next: Pick<ChatSessionConfig, "thinking" | "reasoningEffort">,
 	) => void;
-	onRefreshGitBranch: () => void;
 	onListGitBranches: () => Promise<{ current: string; branches: string[] }>;
 	onSwitchGitBranch: (branch: string) => Promise<boolean>;
 	onSend: () => void;
 	onAbort: () => void;
-	onReset: () => void;
 	promptsInQueue: PromptInQueue[];
 	attachments: Array<{ id: string; name: string; isImage: boolean }>;
 	onAttachFiles: (files: File[]) => void;
@@ -227,6 +224,7 @@ type ChatInputBarProps = {
 };
 
 export function ChatInputBar({
+	variant = "conversation",
 	status,
 	provider,
 	model,
@@ -240,12 +238,10 @@ export function ChatInputBar({
 	onModelChange,
 	onModeToggle,
 	onReasoningChange,
-	onRefreshGitBranch,
 	onListGitBranches,
 	onSwitchGitBranch,
 	onSend,
 	onAbort,
-	onReset,
 	promptsInQueue,
 	attachments,
 	onAttachFiles,
@@ -264,10 +260,33 @@ export function ChatInputBar({
 	} = useWorkspace();
 	const isBusy =
 		status === "starting" || status === "running" || status === "stopping";
+	const canAbort = status === "running" || status === "stopping";
 	const hasDraft = promptInput.trim().length > 0 || attachments.length > 0;
 
-	const [modelSupportsReasoning, setModelSupportsReasoning] = useState(() =>
-		hasReasoningCapability(FALLBACK_PROVIDER_REASONING_MODELS, provider, model),
+	const [reasoningCapability, setReasoningCapability] = useState<{
+		provider: string;
+		model: string;
+		supported: boolean | null;
+	} | null>(null);
+	const modelSupportsReasoning =
+		reasoningCapability?.provider === provider &&
+		reasoningCapability.model === model
+			? reasoningCapability.supported
+			: null;
+	const handleModelSupportsReasoningChange = useCallback(
+		(supported: boolean | null) => {
+			setReasoningCapability((current) => {
+				if (
+					current?.provider === provider &&
+					current.model === model &&
+					current.supported === supported
+				) {
+					return current;
+				}
+				return { provider, model, supported };
+			});
+		},
+		[model, provider],
 	);
 	const canSend = hasDraft;
 	const fileInputRef = useRef<HTMLInputElement | null>(null);
@@ -312,32 +331,50 @@ export function ChatInputBar({
 		() => resolveEffortIndex(thinking, reasoningEffort),
 		[reasoningEffort, thinking],
 	);
-	const effortLabel = modelSupportsReasoning
-		? (EFFORT_LEVELS[effortIndex]?.label ?? "Low")
-		: "None";
-	const handleEffortCycle = useCallback(() => {
-		if (!modelSupportsReasoning) {
-			return;
-		}
-		const nextOption = EFFORT_LEVELS[(effortIndex + 1) % EFFORT_LEVELS.length];
-		if (!nextOption) {
-			return;
-		}
-		onReasoningChange(buildReasoningConfig(nextOption));
-	}, [effortIndex, modelSupportsReasoning, onReasoningChange]);
+	const hasExplicitReasoningSelection =
+		thinking !== undefined || reasoningEffort !== undefined;
+	const effortLabel =
+		!hasExplicitReasoningSelection && modelSupportsReasoning === null
+			? "Reasoning"
+			: !hasExplicitReasoningSelection && modelSupportsReasoning === false
+				? "None"
+				: (EFFORT_LEVELS[effortIndex]?.label ?? "Reasoning");
+	const handleEffortChange = useCallback(
+		(value: string) => {
+			if (modelSupportsReasoning !== true) {
+				return;
+			}
+			const nextOption = EFFORT_LEVELS.find((option) => option.value === value);
+			if (nextOption) {
+				onReasoningChange(buildReasoningConfig(nextOption));
+			}
+		},
+		[modelSupportsReasoning, onReasoningChange],
+	);
 
 	useEffect(() => {
-		if (!modelSupportsReasoning) {
-			if (thinking !== false || reasoningEffort !== undefined) {
-				onReasoningChange({ thinking: false, reasoningEffort: undefined });
-			}
-			return;
-		}
-		if (thinking === undefined && reasoningEffort === undefined) {
+		if (
+			modelSupportsReasoning === true &&
+			thinking === undefined &&
+			reasoningEffort === undefined
+		) {
 			onReasoningChange(buildReasoningConfig(DEFAULT_REASONING_EFFORT));
 		}
 	}, [modelSupportsReasoning, onReasoningChange, reasoningEffort, thinking]);
 
+	useEffect(() => {
+		const input = promptInputRef.current;
+		if (!input) return;
+		if (
+			variant === "conversation" ||
+			(variant === "welcome" &&
+				promptInput.trim().length > 0 &&
+				document.activeElement !== input)
+		) {
+			input.focus();
+		}
+	}, [promptInput, variant]);
+
 	const startQueuedPromptEdit = useCallback((item: PromptInQueue) => {
 		setEditingQueuedPromptId(item.id);
 		setEditingQueuedPromptValue(item.prompt);
@@ -589,9 +626,16 @@ export function ChatInputBar({
 	);
 
 	return (
-		<div className="border-t border-border bg-card">
+		<div
+			className={cn(
+				"bg-card",
+				variant === "welcome"
+					? "overflow-visible rounded-xl border border-border/90 bg-card/90 shadow-[0_24px_80px_-56px_color-mix(in_oklab,var(--primary)_72%,transparent)] backdrop-blur-md"
+					: "border-t border-border bg-card/95 backdrop-blur-sm",
+			)}
+		>
 			{/* Input area */}
-			<div className="px-4 py-3">
+			<div className={cn("px-4 py-3", variant === "welcome" && "pb-2 pt-4")}>
 				{promptsInQueue.length > 0 && (
 					<div className="mb-3 rounded-lg border border-border bg-background/70 p-2">
 						<div className="mb-2 flex items-center justify-between gap-2">
@@ -734,7 +778,11 @@ export function ChatInputBar({
 				)}
 				<div className="relative">
 					{slashOpen && (
-						<div className="absolute inset-x-0 bottom-full z-50 mb-1 max-h-56 overflow-y-auto rounded-lg border border-border bg-popover p-1 shadow-xl">
+						<div
+							className="absolute inset-x-0 bottom-full z-50 mb-1 max-h-56 overflow-y-auto rounded-lg border border-border bg-popover p-1 shadow-xl"
+							id="slash-command-suggestions"
+							role="listbox"
+						>
 							{filteredSlashCommands.length === 0 ? (
 								<div className="px-3 py-2 text-xs text-muted-foreground">
 									{slashLoading
@@ -745,6 +793,7 @@ export function ChatInputBar({
 								<>
 									{filteredSlashCommands.map((cmd, index) => (
 										<button
+											aria-selected={index === slashSelectedIndex}
 											className={cn(
 												"flex w-full flex-col rounded-md px-3 py-2 text-left text-xs transition-colors",
 												index === slashSelectedIndex
@@ -752,7 +801,9 @@ export function ChatInputBar({
 													: "text-muted-foreground hover:bg-accent hover:text-foreground",
 											)}
 											key={cmd.name}
+											id={`slash-command-option-${index}`}
 											onClick={() => insertSlashCommandItem(cmd.name)}
+											role="option"
 											type="button"
 										>
 											<span className="font-medium">/{cmd.name}</span>
@@ -773,7 +824,11 @@ export function ChatInputBar({
 						</div>
 					)}
 					{mentionOpen && (
-						<div className="absolute inset-x-0 bottom-full z-50 mb-1 max-h-56 overflow-y-auto rounded-lg border border-border bg-popover p-1 shadow-xl">
+						<div
+							className="absolute inset-x-0 bottom-full z-50 mb-1 max-h-56 overflow-y-auto rounded-lg border border-border bg-popover p-1 shadow-xl"
+							id="mention-file-suggestions"
+							role="listbox"
+						>
 							{mentionFiles.length === 0 ? (
 								<div className="px-3 py-2 text-xs text-muted-foreground">
 									{mentionLoading ? "Searching files..." : "No matching files"}
@@ -782,6 +837,7 @@ export function ChatInputBar({
 								<>
 									{mentionFiles.map((filePath, index) => (
 										<button
+											aria-selected={index === mentionSelectedIndex}
 											className={cn(
 												"block w-full rounded-md px-3 py-2 text-left text-xs transition-colors",
 												index === mentionSelectedIndex
@@ -789,7 +845,9 @@ export function ChatInputBar({
 													: "text-muted-foreground hover:bg-accent hover:text-foreground",
 											)}
 											key={filePath}
+											id={`mention-file-option-${index}`}
 											onClick={() => insertMentionFile(filePath)}
+											role="option"
 											type="button"
 										>
 											{filePath}
@@ -804,8 +862,31 @@ export function ChatInputBar({
 							)}
 						</div>
 					)}
-					<div className="flex items-end gap-2 rounded-lg border border-border bg-background px-3 py-2.5 transition-all focus-within:border-primary/50 focus-within:ring-1 focus-within:ring-primary/20">
+					<div
+						className={cn(
+							"flex items-end gap-2 rounded-lg border border-border bg-background px-3 py-2.5 transition-all focus-within:border-primary/50 focus-within:ring-1 focus-within:ring-primary/20",
+							variant === "welcome" &&
+								"min-h-16 items-start rounded-none border-0 bg-transparent px-0 py-0 focus-within:ring-0",
+						)}
+					>
 						<textarea
+							aria-activedescendant={
+								slashOpen && filteredSlashCommands.length > 0
+									? `slash-command-option-${slashSelectedIndex}`
+									: mentionOpen && mentionFiles.length > 0
+										? `mention-file-option-${mentionSelectedIndex}`
+										: undefined
+							}
+							aria-autocomplete="list"
+							aria-controls={
+								slashOpen
+									? "slash-command-suggestions"
+									: mentionOpen
+										? "mention-file-suggestions"
+										: undefined
+							}
+							aria-expanded={slashOpen || mentionOpen}
+							aria-haspopup="listbox"
 							className="max-h-60 min-h-5 flex-1 resize-none overflow-y-auto bg-transparent text-sm leading-5 text-foreground placeholder:text-muted-foreground outline-none"
 							onChange={(e) => {
 								onPromptInputChange(e.target.value);
@@ -893,15 +974,20 @@ export function ChatInputBar({
 								)
 							}
 							placeholder={
-								isBusy
-									? "Agent is working... submit to queue another message"
-									: "Enter your question or type / for commands or @ for context"
+								variant === "welcome"
+									? "Ask to make changes, @mention files, reference #PRs, or run /commands."
+									: isBusy
+										? "Agent is working... submit to queue another message"
+										: "Enter your question or type / for commands or @ for context"
 							}
 							ref={promptInputRef}
+							role="combobox"
 							rows={
-								promptInputFocused
-									? PROMPT_INPUT_FOCUSED_ROWS
-									: PROMPT_INPUT_COLLAPSED_ROWS
+								variant === "welcome"
+									? 2
+									: promptInputFocused
+										? PROMPT_INPUT_FOCUSED_ROWS
+										: PROMPT_INPUT_COLLAPSED_ROWS
 							}
 							value={promptInput}
 						/>
@@ -916,6 +1002,7 @@ export function ChatInputBar({
 							>
 								{attachment.isImage ? "image:" : "file:"} {attachment.name}
 								<button
+									aria-label={`Remove ${attachment.name}`}
 									className="rounded-sm p-0.5 text-muted-foreground hover:bg-accent hover:text-foreground"
 									onClick={() => onRemoveAttachment(attachment.id)}
 									type="button"
@@ -928,11 +1015,12 @@ export function ChatInputBar({
 				)}
 			</div>
 
-			{/* Controls row */}
-			<div className="flex items-center justify-between px-4 pb-2">
-				<div className="flex items-center gap-1">
+			{/* Composer settings and submit */}
+			<div className="flex min-w-0 flex-wrap items-center justify-between gap-x-3 gap-y-2 border-t border-border px-3 py-2 text-[11px] text-muted-foreground max-[560px]:grid max-[560px]:grid-cols-[auto_auto_minmax(0,1fr)_auto] max-[560px]:items-center">
+				<div className="flex min-w-0 flex-1 flex-wrap items-center gap-2 max-[560px]:contents">
 					<button
-						className="rounded-md p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
+						aria-label="Attach files"
+						className="rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground max-[560px]:col-start-1 max-[560px]:row-start-1"
 						onClick={() => fileInputRef.current?.click()}
 						type="button"
 					>
@@ -944,97 +1032,137 @@ export function ChatInputBar({
 						multiple
 						onChange={(event) => {
 							const files = Array.from(event.target.files ?? []);
-							if (files.length > 0) {
-								onAttachFiles(files);
-							}
+							if (files.length > 0) onAttachFiles(files);
 							event.currentTarget.value = "";
 						}}
 						ref={fileInputRef}
 						type="file"
 					/>
-
-					<ModelSelector
-						isBusy={isBusy}
-						model={model}
-						onModelChange={onModelChange}
-						onModelSupportsReasoningChange={setModelSupportsReasoning}
-						onProviderChange={onProviderChange}
-						provider={provider}
-					/>
-				</div>
-
-				<div className="flex items-center gap-1">
-					<button
-						className="hidden rounded-md p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
-						type="button"
-					>
-						<Mic className="h-4 w-4" />
-					</button>
-					{isBusy && (
+					<div className="hidden flex shrink-0 items-center rounded-md bg-muted p-0.5 max-[560px]:col-start-2 max-[560px]:row-start-1">
 						<button
-							className="rounded-full bg-foreground p-1.5 text-background hover:bg-foreground/80 transition-colors"
-							onClick={onAbort}
+							aria-pressed={mode === "plan"}
+							className={cn(
+								"rounded px-2 py-1 transition-colors",
+								mode === "plan"
+									? "bg-background text-foreground shadow-xs"
+									: "hover:text-foreground",
+							)}
+							onClick={() => {
+								if (mode !== "plan") onModeToggle();
+							}}
 							type="button"
 						>
-							<CircleStop className="h-4 w-4" />
+							Plan
 						</button>
-					)}
-					{(!isBusy || canSend) && (
 						<button
-							className="rounded-full bg-foreground p-1.5 text-background hover:bg-foreground/80 transition-colors disabled:cursor-not-allowed disabled:opacity-60"
-							disabled={!canSend}
-							onClick={onSend}
+							aria-pressed={mode === "act"}
+							className={cn(
+								"rounded px-2 py-1 transition-colors",
+								mode === "act"
+									? "bg-background text-foreground shadow-xs"
+									: "hover:text-foreground",
+							)}
+							onClick={() => {
+								if (mode !== "act") onModeToggle();
+							}}
 							type="button"
 						>
-							<ArrowUp className="h-4 w-4" />
+							Act
 						</button>
-					)}
+					</div>
+					<div className="min-w-0 shrink-0 max-[560px]:col-start-3 max-[560px]:col-end-5 max-[560px]:row-start-1">
+						<ModelSelector
+							isBusy={isBusy}
+							model={model}
+							onModelChange={onModelChange}
+							onModelSupportsReasoningChange={
+								handleModelSupportsReasoningChange
+							}
+							onProviderChange={onProviderChange}
+							provider={provider}
+						/>
+					</div>
+					<Select
+						disabled={modelSupportsReasoning !== true}
+						onValueChange={handleEffortChange}
+						value={EFFORT_LEVELS[effortIndex]?.value ?? "low"}
+					>
+						<SelectTrigger
+							aria-label="Thinking level"
+							className="h-7 gap-1.5 border-0 bg-muted px-2 text-[11px] shadow-none data-[size=sm]:h-7 [&>svg:last-child]:hidden max-[560px]:col-span-2 max-[560px]:col-start-1 max-[560px]:row-start-2"
+							size="sm"
+							title={
+								modelSupportsReasoning === false
+									? "The selected model does not report reasoning support"
+									: undefined
+							}
+						>
+							<Brain className="size-3" />
+							<SelectValue>{effortLabel}</SelectValue>
+						</SelectTrigger>
+						<SelectContent align="start">
+							{EFFORT_LEVELS.map((option) => (
+								<SelectItem key={option.value} value={option.value}>
+									{option.label}
+								</SelectItem>
+							))}
+						</SelectContent>
+					</Select>
+					{tokensSummary ? (
+						<span className="max-[900px]:hidden">
+							<StatusItem
+								icon={Coins}
+								label={tokensSummary}
+								hasOption={false}
+							/>
+						</span>
+					) : null}
 				</div>
-			</div>
 
-			{/* Status bar */}
-			<div className="flex items-center justify-between border-t border-border px-4 py-1.5 text-[11px] text-muted-foreground">
-				<div className="flex items-center gap-3">
-					<StatusItem
-						label={mode === "act" ? "Act" : "Plan"}
-						onClick={onModeToggle}
-					/>
-					<StatusItem
-						disabled={!modelSupportsReasoning}
-						icon={Brain}
-						label={effortLabel}
-						onClick={handleEffortCycle}
-					/>
-					{tokensSummary && (
-						<StatusItem icon={Coins} label={tokensSummary} hasOption={false} />
-					)}
-				</div>
-				{/* GIT BRANCH */}
-				<div className="flex items-center gap-3">
-					<WorkspaceSelector
-						currentBranch={gitBranch}
-						onListGitBranches={onListGitBranches}
-						onRefreshWorkspaces={onRefreshWorkspaces}
-						onPickWorkspaceDirectory={onPickWorkspaceDirectory}
-						onSwitchGitBranch={onSwitchGitBranch}
-						onSwitchWorkspace={onSwitchWorkspace}
-						workspaces={workspaces}
-						workspaceRoot={workspaceRoot}
-					/>
-					<button
-						className="hidden items-center gap-1 hover:text-foreground transition-colors"
-						onClick={onRefreshGitBranch}
-						type="button"
-					>
-						<RotateCcw className="h-3 w-3" />
-					</button>
-					<button
-						className="hidden items-center gap-1 hover:text-foreground transition-colors"
-						onClick={onReset}
-						type="button"
-					>
-						<RotateCcw className="h-4 w-4" />
-					</button>
+				<div className="ml-auto flex min-w-0 shrink-0 items-center gap-2 max-[560px]:contents">
+					<div className="hidden max-w-48 overflow-visible max-[720px]:max-w-36 max-[560px]:col-start-3 max-[560px]:row-start-2">
+						<WorkspaceSelector
+							currentBranch={gitBranch}
+							onListGitBranches={onListGitBranches}
+							onRefreshWorkspaces={onRefreshWorkspaces}
+							onPickWorkspaceDirectory={onPickWorkspaceDirectory}
+							onSwitchGitBranch={onSwitchGitBranch}
+							onSwitchWorkspace={onSwitchWorkspace}
+							workspaces={workspaces}
+							workspaceRoot={workspaceRoot}
+						/>
+					</div>
+					<div className="flex shrink-0 items-center gap-2 max-[560px]:col-start-4 max-[560px]:row-start-2">
+						{canAbort && (
+							<button
+								aria-label="Stop agent"
+								className={cn(
+									"bg-foreground p-1.5 text-background transition-colors hover:bg-foreground/80",
+									variant === "welcome" ? "rounded-md" : "rounded-full",
+								)}
+								onClick={onAbort}
+								type="button"
+							>
+								<CircleStop className="h-4 w-4" />
+							</button>
+						)}
+						{(!isBusy || canSend) && (
+							<button
+								aria-label="Send message"
+								className={cn(
+									"p-1.5 transition-colors disabled:cursor-not-allowed disabled:opacity-50",
+									variant === "welcome"
+										? "rounded-md bg-[linear-gradient(145deg,var(--primary-emphasis),var(--primary))] text-white shadow-sm hover:brightness-110"
+										: "rounded-full bg-foreground text-background hover:bg-foreground/80",
+								)}
+								disabled={!canSend}
+								onClick={onSend}
+								type="button"
+							>
+								<ArrowUp className="h-4 w-4" />
+							</button>
+						)}
+					</div>
 				</div>
 			</div>
 		</div>
@@ -1054,7 +1182,7 @@ function ModelSelector({
 	isBusy: boolean;
 	onProviderChange: (provider: string) => void;
 	onModelChange: (model: string) => void;
-	onModelSupportsReasoningChange: (supportsReasoning: boolean) => void;
+	onModelSupportsReasoningChange: (supportsReasoning: boolean | null) => void;
 }) {
 	const normalizedProvider = normalizeProviderId(provider);
 	const [providerModels, setProviderModels] = useState<
@@ -1063,6 +1191,9 @@ function ModelSelector({
 	const [providerReasoningModels, setProviderReasoningModels] = useState<
 		Record<string, string[]>
 	>(FALLBACK_PROVIDER_REASONING_MODELS);
+	const [reasoningCapabilitySource, setReasoningCapabilitySource] = useState<
+		"loading" | "catalog" | "fallback"
+	>("loading");
 	const [enabledProviderIds, setEnabledProviderIds] = useState<string[]>([]);
 	const [lastSelection, setLastSelection] = useState(() =>
 		readModelSelectionStorageFromWindow(),
@@ -1120,6 +1251,7 @@ function ModelSelector({
 
 	useEffect(() => {
 		let cancelled = false;
+		setReasoningCapabilitySource("loading");
 
 		async function loadCatalog() {
 			try {
@@ -1129,6 +1261,7 @@ function ModelSelector({
 				}
 				setProviderModels(payload.providerModels);
 				setProviderReasoningModels(payload.providerReasoningModels);
+				setReasoningCapabilitySource("catalog");
 				setEnabledProviderIds((current) => {
 					const nextProviderIds = new Set(payload.enabledProviderIds);
 					if (normalizedProvider) {
@@ -1142,7 +1275,7 @@ function ModelSelector({
 					return Array.from(nextProviderIds);
 				});
 			} catch {
-				// Keep local fallback values when provider catalog is unavailable.
+				if (!cancelled) setReasoningCapabilitySource("fallback");
 			}
 		}
 
@@ -1180,6 +1313,7 @@ function ModelSelector({
 					...current,
 					[normalizedProvider]: reasoningModelIds,
 				}));
+				setReasoningCapabilitySource("catalog");
 				setEnabledProviderIds((current) =>
 					current.includes(normalizedProvider)
 						? current
@@ -1246,6 +1380,16 @@ function ModelSelector({
 	]);
 
 	useEffect(() => {
+		if (reasoningCapabilitySource === "loading") {
+			return;
+		}
+		if (
+			reasoningCapabilitySource === "fallback" &&
+			!(FALLBACK_PROVIDER_MODELS[normalizedProvider] ?? []).includes(model)
+		) {
+			onModelSupportsReasoningChange(null);
+			return;
+		}
 		onModelSupportsReasoningChange(
 			hasReasoningCapability(
 				providerReasoningModels,
@@ -1258,16 +1402,17 @@ function ModelSelector({
 		onModelSupportsReasoningChange,
 		normalizedProvider,
 		providerReasoningModels,
+		reasoningCapabilitySource,
 	]);
 
 	return (
-		<div className="flex items-center gap-1 text-xxs">
-			<Combobox
+		<div className="flex min-w-0 shrink-0 items-center gap-0.5 text-[11px]">
+			<SearchableSelect
+				ariaLabel="Provider"
+				disabled={isBusy || providers.length === 0}
+				emptyLabel="No providers found."
 				items={providers}
-				onValueChange={(value) => {
-					if (!value) {
-						return;
-					}
+				onSelect={(value) => {
 					onProviderChange(value);
 					const rememberedModel = lastSelection.lastModelByProvider[value];
 					const providerModelIds = visibleProviderModels[value] ?? [];
@@ -1284,55 +1429,23 @@ function ModelSelector({
 						onModelChange(firstModel);
 					}
 				}}
+				placeholder="Provider"
+				searchPlaceholder="Search providers"
+				triggerClassName="max-w-28 text-[11px]"
 				value={resolvedProvider}
-			>
-				<ComboboxInput
-					className="h-7 text-xxs"
-					disabled={isBusy || providers.length === 0}
-					readOnly
-					showClear={false}
-					showTrigger
-				/>
-				<ComboboxContent>
-					<ComboboxEmpty>No providers found.</ComboboxEmpty>
-					<ComboboxList>
-						{(item) => (
-							<ComboboxItem className="text-xxs" key={item} value={item}>
-								{item}
-							</ComboboxItem>
-						)}
-					</ComboboxList>
-				</ComboboxContent>
-			</Combobox>
-
-			<Combobox
+			/>
+			<span className="text-muted-foreground/50">/</span>
+			<SearchableSelect
+				ariaLabel="Model"
+				disabled={isBusy || modelsForProvider.length === 0}
+				emptyLabel="No models found."
 				items={modelsForProvider}
-				onValueChange={(value) => {
-					if (!value) {
-						return;
-					}
-					onModelChange(value);
-				}}
+				onSelect={(value) => onModelChange(value)}
+				placeholder="Model"
+				searchPlaceholder="Search models"
+				triggerClassName="max-w-52 text-[11px]"
 				value={resolvedModel}
-			>
-				<ComboboxInput
-					className="h-7"
-					disabled={isBusy || modelsForProvider.length === 0}
-					readOnly
-					showClear={false}
-					showTrigger
-				/>
-				<ComboboxContent>
-					<ComboboxEmpty>No models found.</ComboboxEmpty>
-					<ComboboxList>
-						{(item) => (
-							<ComboboxItem className="text-xxs" key={item} value={item}>
-								{item}
-							</ComboboxItem>
-						)}
-					</ComboboxList>
-				</ComboboxContent>
-			</Combobox>
+			/>
 		</div>
 	);
 }
@@ -1350,6 +1463,16 @@ function StatusItem({
 	disabled?: boolean;
 	hasOption?: boolean;
 }) {
+	const content = (
+		<>
+			{Icon ? <Icon className="h-3 w-3" /> : null}
+			<span className="max-[560px]:sr-only">{label}</span>
+			{hasOption ? <ChevronDown className="h-2.5 w-2.5" /> : null}
+		</>
+	);
+	if (!onClick) {
+		return <span className="flex items-center gap-1">{content}</span>;
+	}
 	return (
 		<button
 			className={cn(
@@ -1360,9 +1483,7 @@ function StatusItem({
 			onClick={onClick}
 			type="button"
 		>
-			{Icon ? <Icon className="h-3 w-3" /> : null}
-			<span>{label}</span>
-			{hasOption ? <ChevronDown className="h-2.5 w-2.5" /> : null}
+			{content}
 		</button>
 	);
 }

apps/examples/desktop-app/webview/components/views/chat/chat-messages.test.tsx

@@ -0,0 +1,93 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ChatMessage } from "@/lib/chat-schema";
+import { ChatMessages } from "./chat-messages";
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+	HTMLElement.prototype.scrollTo = vi.fn();
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+});
+
+afterEach(async () => {
+	await act(async () => root.unmount());
+	container.remove();
+	vi.restoreAllMocks();
+});
+
+async function renderMessages(messages: ChatMessage[]) {
+	await act(async () => {
+		root.render(
+			<ChatMessages
+				chatTransportState="connected"
+				error={null}
+				messages={messages}
+				onAnswerAskQuestion={vi.fn()}
+				onApproveToolApproval={vi.fn()}
+				onRejectToolApproval={vi.fn()}
+				pendingAskQuestions={[]}
+				pendingToolApprovals={[]}
+				sessionId="session-1"
+				status="completed"
+			/>,
+		);
+	});
+}
+
+describe("ChatMessages tool disclosures", () => {
+	it("renders a detail-less tool summary as static text", async () => {
+		await renderMessages([
+			{
+				id: "tool-static",
+				sessionId: "session-1",
+				role: "tool",
+				content: "not-json",
+				createdAt: 1,
+				meta: { toolName: "search" },
+			},
+		]);
+
+		const summary = [...container.querySelectorAll("span")].find((element) =>
+			element.textContent?.includes("Explored"),
+		);
+		expect(summary).toBeDefined();
+		expect(summary?.closest("button")).toBeNull();
+	});
+
+	it("exposes and toggles expandable tool details", async () => {
+		await renderMessages([
+			{
+				id: "tool-expandable",
+				sessionId: "session-1",
+				role: "tool",
+				content: JSON.stringify({
+					toolName: "search",
+					input: { queries: ["workspace selector"] },
+					result: {},
+				}),
+				createdAt: 1,
+			},
+		]);
+
+		const trigger = [...container.querySelectorAll("button")].find((element) =>
+			element.textContent?.includes("Explored 1 search"),
+		);
+		expect(trigger?.getAttribute("aria-expanded")).toBe("false");
+		const panelId = trigger?.getAttribute("aria-controls");
+		expect(panelId).toBeTruthy();
+
+		await act(async () => trigger?.click());
+		expect(trigger?.getAttribute("aria-expanded")).toBe("true");
+		expect(document.getElementById(panelId ?? "")?.textContent).toContain(
+			"workspace selector",
+		);
+	});
+});

apps/examples/desktop-app/webview/components/views/chat/chat-messages.tsx

@@ -24,6 +24,7 @@ import {
 	memo,
 	useCallback,
 	useEffect,
+	useId,
 	useLayoutEffect,
 	useRef,
 	useState,
@@ -34,8 +35,7 @@ import type { ChatMessage, ChatSessionStatus } from "@/lib/chat-schema";
 import { parseApplyPatchInput } from "@/lib/session-diff";
 import { cn } from "@/lib/utils";
 import { MemoizedMarkdown } from "../../ui/markdown";
-import { normalizeTitle } from "../../utils";
-import { WelcomeScreen } from "./welcome-chat";
+import { formatChatMessageContent } from "./message-content";
 
 type ChatMessagesProps = {
 	sessionId: string | null;
@@ -46,8 +46,6 @@ type ChatMessagesProps = {
 		| "connected"
 		| "unavailable";
 	isSessionSwitching?: boolean;
-	provider: string;
-	model: string;
 	messages: ChatMessage[];
 	error: string | null;
 	streamingMessageId?: string | null;
@@ -61,7 +59,6 @@ type ChatMessagesProps = {
 	) => void | Promise<void>;
 	onRestoreCheckpoint?: (runCount: number) => void | Promise<void>;
 	onForkSession?: () => void | Promise<void>;
-	onStartChat?: (prompt: string) => void;
 };
 
 type ToolApprovalRequestItem = {
@@ -97,8 +94,6 @@ function ChatMessagesImpl({
 	status,
 	chatTransportState = "connecting",
 	isSessionSwitching = false,
-	provider,
-	model,
 	messages,
 	error,
 	streamingMessageId = null,
@@ -109,9 +104,9 @@ function ChatMessagesImpl({
 	onAnswerAskQuestion,
 	onRestoreCheckpoint,
 	onForkSession,
-	onStartChat,
 }: ChatMessagesProps) {
 	const scrollAreaRef = useRef<HTMLDivElement | null>(null);
+	const scrollContentRef = useRef<HTMLDivElement | null>(null);
 	const shouldStickToBottomRef = useRef(true);
 	const hasMessages = messages.length > 0;
 	const lastErrorMessage = [...messages]
@@ -208,6 +203,17 @@ function ChatMessagesImpl({
 		scrollToBottom("auto");
 	}, [scrollToBottom]);
 
+	useEffect(() => {
+		const content = scrollContentRef.current;
+		if (!content || typeof ResizeObserver === "undefined") return;
+
+		const resizeObserver = new ResizeObserver(() => {
+			if (shouldStickToBottomRef.current) scrollToBottom("auto");
+		});
+		resizeObserver.observe(content);
+		return () => resizeObserver.disconnect();
+	}, [scrollToBottom]);
+
 	useEffect(() => {
 		const activeRequestIds = new Set(
 			pendingToolApprovals.map((item) => item.requestId),
@@ -376,16 +382,15 @@ function ChatMessagesImpl({
 				className="h-full min-h-0 min-w-0 overflow-x-hidden overflow-y-auto"
 				ref={scrollAreaRef}
 			>
-				<div className="relative mx-auto w-full min-w-0 max-w-full overflow-x-hidden px-6 py-6">
-					{showIdleDetails ? (
-						<WelcomeScreen
-							provider={provider}
-							model={model}
-							onStartChat={onStartChat ?? (() => {})}
-							quickActions={[]}
-						/>
-					) : (
-						<div className="flex h-full w-full min-w-0 flex-col gap-2 overflow-x-hidden">
+				<div
+					className={cn(
+						"relative mx-auto min-h-full w-full min-w-0 max-w-full overflow-x-hidden",
+						showIdleDetails ? "p-0" : "px-6 py-6",
+					)}
+					ref={scrollContentRef}
+				>
+					{showIdleDetails ? null : (
+						<div className="flex min-h-full w-full min-w-0 flex-col gap-2 overflow-x-hidden">
 							{pendingToolApprovals.length > 0 ? (
 								<ToolApprovalPanel
 									items={pendingToolApprovals}
@@ -748,7 +753,10 @@ function MessageBubble({
 		return <ToolMessageBlock message={message} />;
 	}
 
-	const normalizedContent = normalizeTitle(message.content);
+	const displayContent = formatChatMessageContent(
+		message.role,
+		message.content,
+	);
 	const reasoningContent = message.reasoning?.trim() || "";
 
 	return (
@@ -761,7 +769,7 @@ function MessageBubble({
 			<div
 				className={cn(
 					"group max-w-full min-w-0 wrap-break-word text-sm",
-					isUser && "flex max-w-[50%] flex-col items-end gap-1",
+					isUser && "flex max-w-[85%] flex-col items-end gap-1 md:max-w-[50%]",
 					!isUser && "flex flex-col items-start gap-2 overflow-hidden",
 					!isUser && !isError && "text-foreground",
 					isError &&
@@ -774,35 +782,20 @@ function MessageBubble({
 						isUser && "rounded-sm bg-card p-2 text-foreground/80",
 					)}
 				>
-					{isStreaming && message.role === "assistant" ? (
-						<>
-							{reasoningContent || message.reasoningRedacted ? (
-								<ReasoningBlock
-									content={reasoningContent}
-									redacted={message.reasoningRedacted === true}
-								/>
-							) : null}
-							<div className="whitespace-pre-wrap wrap-break-word leading-relaxed">
-								{normalizedContent || " "}
-							</div>
-						</>
-					) : (
-						<>
-							{reasoningContent || message.reasoningRedacted ? (
-								<ReasoningBlock
-									content={reasoningContent}
-									redacted={message.reasoningRedacted === true}
-								/>
-							) : null}
+					{reasoningContent || message.reasoningRedacted ? (
+						<ReasoningBlock
+							content={reasoningContent}
+							redacted={message.reasoningRedacted === true}
+							streaming={isStreaming}
+						/>
+					) : null}
 
-							<div className="my-1 ml-3 min-w-0 max-w-full overflow-x-hidden wrap-break-word **:max-w-full [&_code]:whitespace-pre-wrap [&_code]:wrap-break-word [&_pre]:overflow-x-hidden [&_pre]:whitespace-pre-wrap [&_pre]:wrap-break-word">
-								<MemoizedMarkdown
-									content={normalizedContent || " "}
-									id={message.id}
-								/>
-							</div>
-						</>
-					)}
+					<div className="my-1 min-w-0 max-w-full wrap-break-word">
+						<MemoizedMarkdown
+							content={displayContent || " "}
+							streaming={isStreaming && message.role === "assistant"}
+						/>
+					</div>
 				</div>
 				{shouldRenderUserActions ? (
 					<div className="space-y-1">
@@ -926,11 +919,14 @@ function MessageBubble({
 function ReasoningBlock({
 	content,
 	redacted,
+	streaming = false,
 }: {
 	content: string;
 	redacted: boolean;
+	streaming?: boolean;
 }) {
 	const [expanded, setExpanded] = useState(false);
+	const panelId = useId();
 	const displayContent = content || (redacted ? "[redacted]" : "");
 	if (!displayContent) {
 		return null;
@@ -939,17 +935,35 @@ function ReasoningBlock({
 	return (
 		<div className="my-2">
 			<Button
-				className="h-auto min-h-0 max-w-full justify-start gap-2 whitespace-normal px-0 py-1 text-left text-sm font-medium text-foreground/70 hover:bg-transparent hover:text-foreground dark:hover:bg-transparent dark:hover:text-foreground"
+				aria-controls={panelId}
+				aria-expanded={expanded}
+				className="h-auto min-h-0 max-w-full justify-start gap-2 whitespace-normal px-0 py-1 text-left text-sm font-medium text-foreground/70 hover:bg-transparent hover:text-foreground has-[>svg]:px-0 dark:hover:bg-transparent dark:hover:text-foreground"
 				onClick={() => setExpanded((current) => !current)}
 				type="button"
 				variant="ghost"
 			>
-				<BrainIcon className="size-4" />
-				Thinking
+				<BrainIcon aria-hidden="true" className="size-4" />
+				<span>{streaming ? "Thinking" : "Thought process"}</span>
+				<span
+					aria-live="polite"
+					className="text-xs font-normal text-muted-foreground"
+				>
+					{streaming ? "In progress" : "Complete"}
+				</span>
+				<span aria-hidden="true" className="shrink-0 text-muted-foreground">
+					{expanded ? (
+						<ChevronDown className="size-4" />
+					) : (
+						<ChevronRight className="size-4" />
+					)}
+				</span>
 			</Button>
 			{expanded ? (
-				<div className="mt-1.5 whitespace-pre-wrap rounded-lg border border-border/70 bg-muted/30 p-3 text-sm leading-relaxed text-muted-foreground">
-					{displayContent}
+				<div
+					className="mt-1.5 min-w-0 max-w-full rounded-lg border border-border/70 bg-muted/30 p-3 text-sm leading-relaxed text-muted-foreground"
+					id={panelId}
+				>
+					<MemoizedMarkdown content={displayContent} streaming={streaming} />
 				</div>
 			) : null}
 		</div>
@@ -1334,6 +1348,7 @@ function buildToolSummaryFromMeta(
 
 function ToolMessageBlock({ message }: { message: ChatMessage }) {
 	const [expanded, setExpanded] = useState(false);
+	const panelId = useId();
 	const payload = parseToolPayload(message.content);
 	const toolName = message.meta?.toolName || payload?.toolName || "tool";
 	const hookEventName = message.meta?.hookEventName;
@@ -1365,33 +1380,38 @@ function ToolMessageBlock({ message }: { message: ChatMessage }) {
 	const resultPreview = payload?.isError ? formatToolValue(payload.result) : "";
 	const hasExpandedSections =
 		details.length > 0 || Boolean(inputPreview || resultPreview);
+	const summaryContent = (
+		<>
+			{payload?.isError ? (
+				<AlertCircle className="size-4 text-destructive/80" />
+			) : (
+				<Icon className="size-4" />
+			)}
+			<span className="min-w-0 wrap-break-word">{summary.label}</span>
+			{summary.diff ? (
+				<span className="shrink-0 font-mono text-xs">
+					<span className="text-chart-2">+{summary.diff.additions}</span>{" "}
+					<span className="text-destructive">-{summary.diff.deletions}</span>
+				</span>
+			) : null}
+		</>
+	);
 
 	return (
 		<div className="my-2 flex w-full min-w-0 justify-start">
 			<div
 				className={cn("min-w-0 max-w-full overflow-hidden rounded-xl text-sm")}
 			>
-				<Button
-					className="h-auto min-h-0 max-w-full justify-start gap-2 whitespace-normal px-0 py-1 text-left text-sm font-medium text-primary hover:bg-transparent hover:text-primary/80 dark:hover:bg-transparent dark:hover:text-primary/80"
-					onClick={() => setExpanded((current) => !current)}
-					type="button"
-					variant="ghost"
-				>
-					{payload?.isError ? (
-						<AlertCircle className="size-4 text-destructive/80" />
-					) : (
-						<Icon className="size-4" />
-					)}
-					<span className="min-w-0 wrap-break-word">{summary.label}</span>
-					{summary.diff ? (
-						<span className="shrink-0 font-mono text-xs">
-							<span className="text-chart-2">+{summary.diff.additions}</span>{" "}
-							<span className="text-destructive">
-								-{summary.diff.deletions}
-							</span>
-						</span>
-					) : null}
-					{hasExpandedSections ? (
+				{hasExpandedSections ? (
+					<Button
+						aria-controls={panelId}
+						aria-expanded={expanded}
+						className="h-auto min-h-0 max-w-full justify-start gap-2 whitespace-normal px-0 py-1 text-left text-sm font-medium text-primary hover:bg-transparent hover:text-primary/80 has-[>svg]:px-0 dark:hover:bg-transparent dark:hover:text-primary/80"
+						onClick={() => setExpanded((current) => !current)}
+						type="button"
+						variant="ghost"
+					>
+						{summaryContent}
 						<span className="shrink-0 text-muted-foreground">
 							{expanded ? (
 								<ChevronDown className="size-4" />
@@ -1399,10 +1419,17 @@ function ToolMessageBlock({ message }: { message: ChatMessage }) {
 								<ChevronRight className="size-4" />
 							)}
 						</span>
-					) : null}
-				</Button>
+					</Button>
+				) : (
+					<div className="flex max-w-full items-center justify-start gap-2 py-1 text-left text-sm font-medium text-primary">
+						{summaryContent}
+					</div>
+				)}
 				{expanded ? (
-					<div className="mt-1.5 min-w-0 max-w-full overflow-x-hidden pl-8 text-sm text-muted-foreground">
+					<div
+						className="mt-1.5 min-w-0 max-w-full overflow-x-hidden pl-8 text-sm text-muted-foreground"
+						id={panelId}
+					>
 						{hasExpandedSections ? (
 							<div className="space-y-1">
 								{details.map((detail) => (
@@ -1417,7 +1444,7 @@ function ToolMessageBlock({ message }: { message: ChatMessage }) {
 						) : null}
 						{inputPreview ? (
 							<div className="space-y-1">
-								<div className="text-xxs uppercase tracking-wide text-muted-foreground/80">
+								<div className="text-[11px] uppercase tracking-wide text-muted-foreground/80">
 									Input
 								</div>
 								<pre className="max-h-52 max-w-full overflow-x-hidden overflow-y-auto whitespace-pre-wrap wrap-break-word rounded-md border border-border/70 bg-background/60 p-2 text-sm leading-relaxed text-foreground">

apps/examples/desktop-app/webview/components/views/chat/message-content.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "vitest";
+import { formatChatMessageContent } from "./message-content";
+
+describe("formatChatMessageContent", () => {
+	test("unwraps transport envelopes only for user messages", () => {
+		expect(
+			formatChatMessageContent(
+				"user",
+				"  <user_input>\nPlease fix the tests\n</user_input>  ",
+			),
+		).toBe("Please fix the tests");
+	});
+
+	test("preserves assistant examples that contain transport tags", () => {
+		const content =
+			"<user_input>\nThis tag is part of the explanation.\n</user_input>";
+		expect(formatChatMessageContent("assistant", content)).toBe(content);
+	});
+
+	test("preserves assistant mode notices instead of stripping them", () => {
+		const content = "<mode_notice>\nPlan mode details\n</mode_notice>";
+		expect(formatChatMessageContent("assistant", content)).toBe(content);
+	});
+
+	test("trims outer whitespace for non-user roles", () => {
+		expect(formatChatMessageContent("error", "  Request failed  \n")).toBe(
+			"Request failed",
+		);
+	});
+});

apps/examples/desktop-app/webview/components/views/chat/message-content.ts

@@ -0,0 +1,10 @@
+import { formatDisplayUserInput } from "@cline/shared/browser";
+import type { ChatMessage } from "@/lib/chat-schema";
+
+export function formatChatMessageContent(
+	role: ChatMessage["role"],
+	content: string,
+): string {
+	const trimmed = content.trim();
+	return role === "user" ? formatDisplayUserInput(trimmed) : trimmed;
+}

apps/examples/desktop-app/webview/components/views/chat/searchable-select.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import { Check, Search } from "lucide-react";
+import { type ReactNode, useEffect, useMemo, useRef, useState } from "react";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+
+/**
+ * A button-styled select whose menu is a searchable, filterable list — the same
+ * interaction the workspace and branch pickers use. The trigger shows the
+ * current value with no chevron; clicking it opens the popover.
+ */
+export function SearchableSelect({
+	value,
+	items,
+	onSelect,
+	disabled = false,
+	ariaLabel,
+	searchPlaceholder = "Search...",
+	emptyLabel = "No results",
+	placeholder = "Select",
+	icon,
+	triggerClassName,
+	align = "start",
+	placement = "top",
+}: {
+	value: string;
+	items: string[];
+	onSelect: (value: string) => void;
+	disabled?: boolean;
+	ariaLabel: string;
+	searchPlaceholder?: string;
+	emptyLabel?: string;
+	placeholder?: string;
+	icon?: ReactNode;
+	triggerClassName?: string;
+	align?: "start" | "end";
+	placement?: "top" | "bottom";
+}) {
+	const [open, setOpen] = useState(false);
+	const [search, setSearch] = useState("");
+	const containerRef = useRef<HTMLDivElement>(null);
+
+	// Close on outside click; reset the filter each time the menu opens.
+	useEffect(() => {
+		if (!open) {
+			setSearch("");
+			return;
+		}
+		const handlePointerDown = (event: PointerEvent) => {
+			if (
+				containerRef.current &&
+				!containerRef.current.contains(event.target as Node)
+			) {
+				setOpen(false);
+			}
+		};
+		// pointerdown in the capture phase so we still fire before a portaled menu
+		// (e.g. the Radix effort Select) handles its own trigger's pointerdown and
+		// calls preventDefault, which would otherwise suppress a mousedown listener.
+		document.addEventListener("pointerdown", handlePointerDown, true);
+		return () =>
+			document.removeEventListener("pointerdown", handlePointerDown, true);
+	}, [open]);
+
+	const filtered = useMemo(
+		() =>
+			items.filter((item) => item.toLowerCase().includes(search.toLowerCase())),
+		[items, search],
+	);
+
+	const handleSelect = (item: string) => {
+		if (item !== value) onSelect(item);
+		setOpen(false);
+	};
+
+	return (
+		<div className="relative" ref={containerRef}>
+			<button
+				aria-expanded={open}
+				aria-haspopup="listbox"
+				aria-label={ariaLabel}
+				className={cn(
+					"inline-flex items-center gap-1.5 rounded-md px-2 py-1 font-medium text-foreground transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+					triggerClassName,
+				)}
+				disabled={disabled}
+				onClick={() => setOpen((current) => !current)}
+				title={value}
+				type="button"
+			>
+				{icon}
+				<span className="truncate">{value || placeholder}</span>
+			</button>
+
+			{open && (
+				<div
+					className={cn(
+						"absolute z-50 w-64 rounded-lg border border-border bg-popover shadow-xl",
+						align === "end" ? "right-0" : "left-0",
+						placement === "top" ? "bottom-full mb-2" : "top-full mt-2",
+					)}
+				>
+					<div className="border-b border-border p-2">
+						<div className="flex items-center gap-2 rounded-md bg-background px-2.5 py-1.5">
+							<Search className="size-3 shrink-0 text-muted-foreground" />
+							{/* eslint-disable-next-line jsx-a11y/no-autofocus */}
+							<Input
+								autoFocus
+								className="h-auto flex-1 border-0 bg-transparent px-0 py-0 text-xs shadow-none focus-visible:ring-0"
+								onChange={(event) => setSearch(event.target.value)}
+								placeholder={searchPlaceholder}
+								value={search}
+							/>
+						</div>
+					</div>
+					<div className="flex max-h-56 flex-col gap-0.5 overflow-y-auto p-1.5">
+						{filtered.length === 0 ? (
+							<div className="px-2 py-2 text-xs text-muted-foreground">
+								{emptyLabel}
+							</div>
+						) : (
+							filtered.map((item) => (
+								<button
+									className={cn(
+										"flex items-center justify-between gap-2 rounded-md px-2 py-1.5 text-left transition-colors",
+										item === value ? "bg-accent" : "hover:bg-accent/50",
+									)}
+									key={item}
+									onClick={() => handleSelect(item)}
+									type="button"
+								>
+									<span className="truncate text-xs text-foreground">
+										{item}
+									</span>
+									{item === value && (
+										<Check className="ml-2 size-3 shrink-0 text-foreground" />
+									)}
+								</button>
+							))
+						)}
+					</div>
+				</div>
+			)}
+		</div>
+	);
+}

apps/examples/desktop-app/webview/components/views/chat/welcome-chat.test.tsx

@@ -0,0 +1,37 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import { WorkspaceProvider } from "@/contexts/workspace-context";
+import { WelcomeScreen } from "./welcome-chat";
+
+describe("WelcomeScreen", () => {
+	it("renders every known project instead of capping the project strip", () => {
+		const workspaces = Array.from(
+			{ length: 6 },
+			(_, index) => `/projects/project-${index + 1}`,
+		);
+		const html = renderToStaticMarkup(
+			<WorkspaceProvider
+				value={{
+					workspaceRoot: workspaces[0] ?? "",
+					workspaces,
+					listWorkspaces: vi.fn(async () => workspaces),
+					refreshWorkspaces: vi.fn(async () => undefined),
+					switchWorkspace: vi.fn(async () => true),
+					pickWorkspaceDirectory: vi.fn(async () => null),
+				}}
+			>
+				<WelcomeScreen
+					active
+					body={null}
+					composer={null}
+					onStartChat={vi.fn()}
+					quickActions={[]}
+				/>
+			</WorkspaceProvider>,
+		);
+
+		for (let index = 1; index <= workspaces.length; index += 1) {
+			expect(html).toContain(`project-${index}`);
+		}
+	});
+});

apps/examples/desktop-app/webview/components/views/chat/welcome-chat.tsx

@@ -1,17 +1,12 @@
 "use client";
 
-import { Check, FolderOpen } from "lucide-react";
-import { useCallback, useEffect, useMemo, useState } from "react";
-import {
-	Command,
-	CommandEmpty,
-	CommandGroup,
-	CommandInput,
-	CommandItem,
-	CommandList,
-} from "@/components/ui/command";
-import { Label } from "@/components/ui/label";
+import { ArrowRight } from "lucide-react";
+import type { ReactNode } from "react";
+import { useEffect, useState } from "react";
+import { AuroraBackground } from "@/components/ui/aurora-bg";
 import { useWorkspace } from "@/contexts/workspace-context";
+import { cn } from "@/lib/utils";
+import { WelcomeWorkspaceControls } from "./welcome-workspace-controls";
 
 interface QuickAction {
 	id: string;
@@ -20,177 +15,178 @@ interface QuickAction {
 	prompt: string;
 }
 
-function normalizeWorkspacePath(path: string): string {
-	const normalized = path.trim().replace(/[\\/]+$/, "");
-	if (!normalized) {
-		return "";
-	}
-	if (/^[A-Za-z]:/.test(normalized)) {
-		return normalized.toLowerCase();
-	}
-	return normalized;
-}
-function toWorkspaceName(path: string): string {
-	const trimmed = path.trim().replace(/[\\/]+$/, "");
-	if (!trimmed) return "workspace";
-	const parts = trimmed.split(/[\\/]/);
-	return parts[parts.length - 1] || "workspace";
-}
+const HERO_VERBS = ["build", "create", "fix", "know"] as const;
+const HERO_CYCLE_MS = 2600;
 
-function formatWorkspaceLabel(workspacePath: string): string {
-	const trimmed = workspacePath.trim();
-	if (!trimmed) return workspacePath;
-	const unixHome = trimmed.match(/^\/Users\/[^/]+\/(.*)$/);
-	if (unixHome) return unixHome[1] ? `~/${unixHome[1]}` : "~";
-	const linuxHome = trimmed.match(/^\/home\/[^/]+\/(.*)$/);
-	if (linuxHome) return linuxHome[1] ? `~/${linuxHome[1]}` : "~";
-	const windowsHome = trimmed.match(/^[A-Za-z]:\\Users\\[^\\]+\\(.*)$/);
-	if (windowsHome) {
-		const tail = windowsHome[1]?.replaceAll("\\", "/") || "";
-		return tail ? `~/${tail}` : "~";
-	}
-	return workspacePath;
+const DEFAULT_QUICK_ACTIONS: QuickAction[] = [
+	{
+		id: "review-changes",
+		label: "Review changes",
+		description: "Review the current changes and call out anything risky.",
+		prompt: "Review the current changes and call out anything risky.",
+	},
+	{
+		id: "check-build",
+		label: "Check for build errors",
+		description: "Run the relevant checks and help me fix any failures.",
+		prompt: "Check this project for build errors and help me fix any failures.",
+	},
+];
+
+function HeroHeading() {
+	const [verbIndex, setVerbIndex] = useState(0);
+
+	useEffect(() => {
+		const media = window.matchMedia("(prefers-reduced-motion: reduce)");
+		if (media.matches) return;
+		const interval = setInterval(() => {
+			setVerbIndex((prev) => (prev + 1) % HERO_VERBS.length);
+		}, HERO_CYCLE_MS);
+		return () => clearInterval(interval);
+	}, []);
+
+	const verb = HERO_VERBS[verbIndex];
+
+	return (
+		<h1
+			id="hero-header"
+			className="text-balance text-left text-[clamp(2rem,3vw,2.6rem)] font-semibold leading-[1.12] tracking-tight text-foreground"
+		>
+			<span className="sr-only">What would you like to build?</span>
+			<span aria-hidden="true">
+				What would you like to{" "}
+				{/* key remounts the word each cycle so the chars re-trigger their entrance */}
+				<span key={verb}>
+					{verb.split("").map((char, index) => (
+						<span
+							className="hero-word-char"
+							// biome-ignore lint/suspicious/noArrayIndexKey: the word remounts via the parent key each cycle, so char position is a stable, non-reordering identity
+							key={`${verb}-${index}`}
+							style={{ animationDelay: `${index * 45}ms` }}
+						>
+							{char}
+						</span>
+					))}
+				</span>
+				?
+			</span>
+		</h1>
+	);
 }
 
 export function WelcomeScreen({
+	active,
+	body,
+	composer,
+	onStartChat,
 	quickActions,
+	gitBranch,
+	onListGitBranches,
+	onSwitchGitBranch,
 }: {
-	provider: string;
-	model: string;
+	active: boolean;
+	body: ReactNode;
+	composer: ReactNode;
 	onStartChat: (prompt: string) => void;
 	quickActions: QuickAction[];
+	gitBranch: string;
+	onListGitBranches: () => Promise<{ current: string; branches: string[] }>;
+	onSwitchGitBranch: (branch: string) => Promise<boolean>;
 }) {
-	const { workspaceRoot, workspaces, refreshWorkspaces, switchWorkspace } =
-		useWorkspace();
-	const [switchingWorkspace, setSwitchingWorkspace] = useState(false);
-	const availableWorkspaces = useMemo(() => {
-		const next = new Map<string, string>();
-		const register = (path: string) => {
-			const trimmed = path.trim();
-			if (!trimmed) {
-				return;
-			}
-			next.set(normalizeWorkspacePath(trimmed), trimmed);
-		};
-		register(workspaceRoot);
-		for (const workspacePath of workspaces) {
-			register(workspacePath);
-		}
-		return [...next.values()];
-	}, [workspaceRoot, workspaces]);
+	const {
+		workspaceRoot,
+		workspaces,
+		refreshWorkspaces,
+		switchWorkspace,
+		pickWorkspaceDirectory,
+	} = useWorkspace();
+	const actions =
+		quickActions.length > 0 ? quickActions : DEFAULT_QUICK_ACTIONS;
 
 	useEffect(() => {
-		void refreshWorkspaces();
-	}, [refreshWorkspaces]);
-
-	const handleSelectWorkspace = useCallback(
-		async (path: string) => {
-			if (
-				normalizeWorkspacePath(path) ===
-					normalizeWorkspacePath(workspaceRoot) ||
-				switchingWorkspace
-			)
-				return;
-			setSwitchingWorkspace(true);
-			await switchWorkspace(path);
-			setSwitchingWorkspace(false);
-		},
-		[workspaceRoot, switchWorkspace, switchingWorkspace],
-	);
-
-	const handleQuickAction = (action: QuickAction) => {
-		// TODO: wire up quick action prompt to chat input
-		void action;
-	};
+		if (active) void refreshWorkspaces();
+	}, [active, refreshWorkspaces]);
 
 	return (
-		<div className="flex flex-1 flex-col items-center overflow-hidden bg-background">
-			<div className="relative z-10 flex w-full max-w-3xl flex-1 flex-col items-center px-6 py-12">
-				<div className="mb-8 flex flex-col items-center">
-					<h1 className="text-balance text-center text-3xl font-bold tracking-tight text-foreground">
-						What can I do for you?
-					</h1>
-					<p className="mt-2 text-balance text-center text-muted-foreground">
-						Let's explore, edit, and ship code together!
-					</p>
-				</div>
+		<div
+			className={cn(
+				active
+					? "relative h-full min-h-0 overflow-hidden bg-background"
+					: "contents",
+			)}
+		>
+			{active ? <AuroraBackground /> : null}
+			<div
+				className={cn(
+					active
+						? "relative z-10 h-full w-full overflow-x-hidden overflow-y-auto"
+						: "contents",
+				)}
+			>
+				<div
+					className={cn(
+						active
+							? "mx-auto flex w-full max-w-240 flex-col px-6 pb-32 pt-[clamp(8rem,26vh,17rem)] max-[720px]:px-4 max-[720px]:pb-20 max-[720px]:pt-16"
+							: "contents",
+					)}
+				>
+					{active ? (
+						<>
+							<HeroHeading />
 
-				{/* Workspace selector */}
-				<div className="mb-8 w-full max-w-md">
-					<Label className="mb-2 block text-xs font-medium text-muted-foreground">
-						Workspace
-					</Label>
-					<Command className="rounded-xl border border-border bg-card">
-						<CommandInput placeholder="Search workspaces..." />
-						<CommandList>
-							<CommandEmpty>No workspaces found.</CommandEmpty>
-							<CommandGroup>
-								{availableWorkspaces.map((wsPath) => {
-									const isActive =
-										normalizeWorkspacePath(wsPath) ===
-										normalizeWorkspacePath(workspaceRoot);
-									return (
-										<CommandItem
-											key={wsPath}
-											value={wsPath}
-											onSelect={() => {
-												void handleSelectWorkspace(wsPath);
-											}}
-											disabled={switchingWorkspace}
-											className="gap-3 py-2.5"
-										>
-											<div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-secondary">
-												<FolderOpen className="h-3.5 w-3.5 text-muted-foreground" />
-											</div>
-											<div className="min-w-0 flex-1">
-												<div className="flex items-center gap-2">
-													<p className="truncate text-sm font-medium text-foreground">
-														{toWorkspaceName(wsPath)}
-													</p>
-													{isActive && (
-														<span className="rounded-full bg-primary/20 px-1.5 py-0.5 text-[10px] font-medium text-primary">
-															Active
-														</span>
-													)}
-												</div>
-												<p className="truncate text-xs text-muted-foreground">
-													{formatWorkspaceLabel(wsPath)}
-												</p>
-											</div>
-											{isActive && (
-												<Check className="ml-auto h-4 w-4 text-primary" />
-											)}
-										</CommandItem>
-									);
-								})}
-							</CommandGroup>
-						</CommandList>
-					</Command>
-				</div>
+							<div className="mt-11 flex min-w-0 items-center">
+								<WelcomeWorkspaceControls
+									currentBranch={gitBranch}
+									onListGitBranches={onListGitBranches}
+									onPickWorkspaceDirectory={pickWorkspaceDirectory}
+									onRefreshWorkspaces={refreshWorkspaces}
+									onSwitchGitBranch={onSwitchGitBranch}
+									onSwitchWorkspace={switchWorkspace}
+									workspaceRoot={workspaceRoot}
+									workspaces={workspaces}
+								/>
+							</div>
+						</>
+					) : null}
 
-				{/* Quick actions */}
-				<div className="mb-8 w-full">
-					<div className="grid grid-cols-2 gap-3 sm:grid-cols-3">
-						{quickActions?.map((action) => {
-							return (
-								<button
-									type="button"
-									key={action.id}
-									onClick={() => handleQuickAction(action)}
-									className="group flex flex-col items-start gap-2 rounded-xl border border-border bg-card/50 p-4 text-left transition-all hover:border-primary/30 hover:bg-card"
-								>
-									<div>
-										<p className="text-sm font-medium text-foreground">
-											{action.label}
-										</p>
-										<p className="mt-0.5 text-xs text-muted-foreground line-clamp-2">
-											{action.description}
-										</p>
-									</div>
-								</button>
-							);
-						})}
+					<div
+						className={active ? "hidden" : "h-full min-h-0 overflow-hidden"}
+						key="conversation-body"
+					>
+						{body}
 					</div>
+
+					<div
+						className={active ? "mt-4 w-full" : "z-20 shrink-0"}
+						key="persistent-composer"
+					>
+						{composer}
+					</div>
+
+					{active ? (
+						<div className="mt-11 w-full divide-y divide-border/80 overflow-hidden rounded-xl border border-border/60 bg-background/95 px-2 shadow-sm">
+							{actions.map((action) => (
+								<button
+									className="group flex w-full items-center justify-between gap-5 px-3 py-3 text-left transition-colors hover:bg-background/55 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
+									key={action.id}
+									onClick={() => onStartChat(action.prompt)}
+									type="button"
+								>
+									<span className="min-w-0">
+										<span className="block text-[15px] font-medium text-foreground">
+											{action.label}
+										</span>
+										<span className="mt-0.5 block truncate text-sm text-muted-foreground">
+											{action.description}
+										</span>
+									</span>
+									<span className="flex size-7 shrink-0 items-center justify-center rounded-md bg-primary/10 text-primary transition-colors group-hover:bg-primary group-hover:text-primary-foreground">
+										<ArrowRight className="size-3" />
+									</span>
+								</button>
+							))}
+						</div>
+					) : null}
 				</div>
 			</div>
 		</div>

apps/examples/desktop-app/webview/components/views/chat/welcome-workspace-controls.tsx

@@ -0,0 +1,400 @@
+"use client";
+
+import { Check, Folder, GitBranch, Plus, Search } from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import { normalizeWorkspacePath } from "@/lib/workspace-paths";
+
+function formatWorkspacePath(path: string): string {
+	const unixHome = path.match(/^\/Users\/[^/]+\/(.*)$/);
+	if (unixHome) return unixHome[1] ? `~/${unixHome[1]}` : "~";
+	const linuxHome = path.match(/^\/home\/[^/]+\/(.*)$/);
+	if (linuxHome) return linuxHome[1] ? `~/${linuxHome[1]}` : "~";
+	const windowsHome = path.match(/^[A-Za-z]:\\Users\\[^\\]+\\(.*)$/);
+	if (windowsHome) {
+		const tail = windowsHome[1]?.replaceAll("\\", "/") || "";
+		return tail ? `~/${tail}` : "~";
+	}
+	return path;
+}
+
+function workspaceName(path: string): string {
+	const trimmed = path.trim().replace(/[\\/]+$/, "");
+	if (!trimmed) return "workspace";
+	const parts = trimmed.split(/[\\/]/);
+	return parts[parts.length - 1] || "workspace";
+}
+
+const TRIGGER_CLASS =
+	"inline-flex items-center gap-1.5 rounded-md border border-border/70 bg-background/80 px-3 py-1.5 text-sm font-medium text-foreground transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+const PANEL_CLASS =
+	"absolute left-0 top-full z-50 mt-2 w-72 rounded-lg border border-border bg-popover shadow-xl";
+
+function SearchInput({
+	value,
+	onChange,
+	placeholder,
+}: {
+	value: string;
+	onChange: (value: string) => void;
+	placeholder: string;
+}) {
+	return (
+		<div className="border-b border-border p-2">
+			<div className="flex items-center gap-2 rounded-md bg-background px-2.5 py-1.5">
+				<Search className="size-3 shrink-0 text-muted-foreground" />
+				{/* eslint-disable-next-line jsx-a11y/no-autofocus */}
+				<Input
+					autoFocus
+					className="h-auto flex-1 border-0 bg-transparent px-0 py-0 text-xs shadow-none focus-visible:ring-0"
+					onChange={(event) => onChange(event.target.value)}
+					placeholder={placeholder}
+					value={value}
+				/>
+			</div>
+		</div>
+	);
+}
+
+function WorkspacePicker({
+	open,
+	onToggle,
+	onClose,
+	workspaceRoot,
+	workspaces,
+	onRefreshWorkspaces,
+	onSwitchWorkspace,
+	onPickWorkspaceDirectory,
+}: {
+	open: boolean;
+	onToggle: () => void;
+	onClose: () => void;
+	workspaceRoot: string;
+	workspaces: string[];
+	onRefreshWorkspaces: () => Promise<void>;
+	onSwitchWorkspace: (workspacePath: string) => Promise<boolean>;
+	onPickWorkspaceDirectory: (initialPath?: string) => Promise<string | null>;
+}) {
+	const [search, setSearch] = useState("");
+	const [switching, setSwitching] = useState(false);
+	const [picking, setPicking] = useState(false);
+
+	const normalizedWorkspaceRoot = useMemo(
+		() => normalizeWorkspacePath(workspaceRoot),
+		[workspaceRoot],
+	);
+
+	// Refresh the catalog and clear the filter each time the menu opens.
+	useEffect(() => {
+		if (!open) return;
+		setSearch("");
+		void onRefreshWorkspaces();
+	}, [open, onRefreshWorkspaces]);
+
+	// The active workspace can be an excluded path (restored session, process
+	// cwd fallback); register it explicitly so it stays visible while active.
+	const availableWorkspaces = useMemo(() => {
+		const byNormalizedPath = new Map<string, string>();
+		const register = (path: string) => {
+			const trimmed = path.trim();
+			if (trimmed)
+				byNormalizedPath.set(normalizeWorkspacePath(trimmed), trimmed);
+		};
+		register(workspaceRoot);
+		for (const path of workspaces) register(path);
+		return [...byNormalizedPath.values()];
+	}, [workspaceRoot, workspaces]);
+
+	const filteredWorkspaces = availableWorkspaces.filter((path) =>
+		path.toLowerCase().includes(search.toLowerCase()),
+	);
+
+	const handleSelect = async (path: string) => {
+		const next = path.trim();
+		if (!next || normalizeWorkspacePath(next) === normalizedWorkspaceRoot) {
+			onClose();
+			return;
+		}
+		if (switching) return;
+		setSwitching(true);
+		const switched = await onSwitchWorkspace(next);
+		setSwitching(false);
+		if (switched) onClose();
+	};
+
+	const handleAddWorkspace = async () => {
+		if (picking || switching) return;
+		setPicking(true);
+		try {
+			const picked = await onPickWorkspaceDirectory(workspaceRoot || undefined);
+			if (picked?.trim()) await handleSelect(picked.trim());
+		} finally {
+			setPicking(false);
+		}
+	};
+
+	return (
+		<div className="relative shrink-0">
+			<button
+				aria-expanded={open}
+				aria-haspopup="menu"
+				className={TRIGGER_CLASS}
+				onClick={onToggle}
+				title={workspaceRoot}
+				type="button"
+			>
+				<Folder className="size-4 shrink-0 text-muted-foreground" />
+				<span className="max-w-44 truncate">
+					{workspaceName(workspaceRoot)}
+				</span>
+			</button>
+
+			{open && (
+				<div className={PANEL_CLASS}>
+					<SearchInput
+						onChange={setSearch}
+						placeholder="Search workspaces"
+						value={search}
+					/>
+					<div className="p-1.5">
+						<div className="flex max-h-48 flex-col gap-0.5 overflow-y-auto">
+							{filteredWorkspaces.length === 0 ? (
+								<div className="px-2 py-2 text-xs text-muted-foreground">
+									No workspaces found
+								</div>
+							) : (
+								filteredWorkspaces.map((path) => {
+									const isActive =
+										normalizeWorkspacePath(path) === normalizedWorkspaceRoot;
+									return (
+										<Button
+											className={cn(
+												"flex h-auto w-full items-center justify-between rounded-md p-2 text-left",
+												isActive ? "bg-accent" : "hover:bg-accent/50",
+											)}
+											disabled={switching}
+											key={path}
+											onClick={() => void handleSelect(path)}
+											variant="ghost"
+										>
+											<span className="flex min-w-0 items-center gap-2">
+												<Folder className="size-3 shrink-0 text-muted-foreground" />
+												<span className="truncate text-xs text-foreground">
+													{formatWorkspacePath(path)}
+												</span>
+											</span>
+											{isActive && (
+												<Check className="ml-2 size-3 shrink-0 text-foreground" />
+											)}
+										</Button>
+									);
+								})
+							)}
+						</div>
+						<Button
+							className="mt-0.5 w-full justify-start text-xs text-muted-foreground"
+							disabled={switching || picking}
+							onClick={() => void handleAddWorkspace()}
+							size="sm"
+							variant="ghost"
+						>
+							<Plus className="size-3" />
+							{picking ? "Opening folder picker..." : "Add project..."}
+						</Button>
+					</div>
+				</div>
+			)}
+		</div>
+	);
+}
+
+function BranchPicker({
+	open,
+	onToggle,
+	onClose,
+	currentBranch,
+	onListGitBranches,
+	onSwitchGitBranch,
+}: {
+	open: boolean;
+	onToggle: () => void;
+	onClose: () => void;
+	currentBranch: string;
+	onListGitBranches: () => Promise<{ current: string; branches: string[] }>;
+	onSwitchGitBranch: (branch: string) => Promise<boolean>;
+}) {
+	const [search, setSearch] = useState("");
+	const [branches, setBranches] = useState<string[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [switching, setSwitching] = useState(false);
+
+	// Load branches fresh each time the menu opens.
+	useEffect(() => {
+		if (!open) return;
+		let cancelled = false;
+		setSearch("");
+		setLoading(true);
+		onListGitBranches()
+			.then((payload) => {
+				if (!cancelled) setBranches(payload.branches);
+			})
+			.finally(() => {
+				if (!cancelled) setLoading(false);
+			});
+		return () => {
+			cancelled = true;
+		};
+	}, [open, onListGitBranches]);
+
+	const hasGit = currentBranch !== "no-git";
+	const branchLabel = hasGit ? currentBranch : "No branch";
+
+	const filteredBranches = branches.filter((branch) =>
+		branch.toLowerCase().includes(search.toLowerCase()),
+	);
+
+	const handleSelect = async (branch: string) => {
+		if (branch === currentBranch) {
+			onClose();
+			return;
+		}
+		if (switching) return;
+		setSwitching(true);
+		const switched = await onSwitchGitBranch(branch);
+		setSwitching(false);
+		if (switched) onClose();
+	};
+
+	return (
+		<div className="relative min-w-0">
+			<button
+				aria-expanded={open}
+				aria-haspopup="menu"
+				className={cn(TRIGGER_CLASS, "min-w-0 max-w-full")}
+				onClick={onToggle}
+				title={branchLabel}
+				type="button"
+			>
+				<GitBranch className="size-4 shrink-0 text-muted-foreground" />
+				<span className="min-w-0 truncate">{branchLabel}</span>
+			</button>
+
+			{open && (
+				<div className={PANEL_CLASS}>
+					<SearchInput
+						onChange={setSearch}
+						placeholder="Search branches"
+						value={search}
+					/>
+					<div className="p-1.5">
+						{loading ? (
+							<div className="px-2 py-4 text-xs text-muted-foreground">
+								Loading...
+							</div>
+						) : (
+							<div className="flex max-h-56 flex-col gap-0.5 overflow-y-auto">
+								{filteredBranches.length === 0 ? (
+									<div className="px-2 py-2 text-xs text-muted-foreground">
+										No branches found
+									</div>
+								) : (
+									filteredBranches.map((branch) => (
+										<Button
+											className={cn(
+												"flex h-auto items-center gap-2 rounded-md px-2 py-2 text-left",
+												currentBranch === branch
+													? "bg-accent"
+													: "hover:bg-accent/50",
+											)}
+											disabled={switching}
+											key={branch}
+											onClick={() => void handleSelect(branch)}
+											variant="ghost"
+										>
+											<GitBranch className="size-3 shrink-0 text-muted-foreground" />
+											<span className="min-w-0 flex-1 truncate text-xs font-medium text-foreground">
+												{branch}
+											</span>
+											{currentBranch === branch && (
+												<Check className="ml-auto size-3 shrink-0 text-foreground" />
+											)}
+										</Button>
+									))
+								)}
+							</div>
+						)}
+					</div>
+				</div>
+			)}
+		</div>
+	);
+}
+
+export function WelcomeWorkspaceControls({
+	workspaceRoot,
+	workspaces,
+	onRefreshWorkspaces,
+	onSwitchWorkspace,
+	onPickWorkspaceDirectory,
+	currentBranch,
+	onListGitBranches,
+	onSwitchGitBranch,
+}: {
+	workspaceRoot: string;
+	workspaces: string[];
+	onRefreshWorkspaces: () => Promise<void>;
+	onSwitchWorkspace: (workspacePath: string) => Promise<boolean>;
+	onPickWorkspaceDirectory: (initialPath?: string) => Promise<string | null>;
+	currentBranch: string;
+	onListGitBranches: () => Promise<{ current: string; branches: string[] }>;
+	onSwitchGitBranch: (branch: string) => Promise<boolean>;
+}) {
+	const [openMenu, setOpenMenu] = useState<"workspace" | "branch" | null>(null);
+	const containerRef = useRef<HTMLDivElement>(null);
+
+	// Close whichever menu is open when clicking outside the control row.
+	useEffect(() => {
+		if (!openMenu) return;
+		const handlePointerDown = (event: MouseEvent) => {
+			if (
+				containerRef.current &&
+				!containerRef.current.contains(event.target as Node)
+			) {
+				setOpenMenu(null);
+			}
+		};
+		document.addEventListener("mousedown", handlePointerDown);
+		return () => document.removeEventListener("mousedown", handlePointerDown);
+	}, [openMenu]);
+
+	return (
+		<div className="flex min-w-0 items-center gap-2" ref={containerRef}>
+			<WorkspacePicker
+				onClose={() => setOpenMenu(null)}
+				onPickWorkspaceDirectory={onPickWorkspaceDirectory}
+				onRefreshWorkspaces={onRefreshWorkspaces}
+				onSwitchWorkspace={onSwitchWorkspace}
+				onToggle={() =>
+					setOpenMenu((current) =>
+						current === "workspace" ? null : "workspace",
+					)
+				}
+				open={openMenu === "workspace"}
+				workspaceRoot={workspaceRoot}
+				workspaces={workspaces}
+			/>
+			<BranchPicker
+				currentBranch={currentBranch}
+				onClose={() => setOpenMenu(null)}
+				onListGitBranches={onListGitBranches}
+				onSwitchGitBranch={onSwitchGitBranch}
+				onToggle={() =>
+					setOpenMenu((current) => (current === "branch" ? null : "branch"))
+				}
+				open={openMenu === "branch"}
+			/>
+		</div>
+	);
+}

apps/examples/desktop-app/webview/components/views/chat/workspace-selector.test.tsx

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { WorkspaceSelector } from "./workspace-selector";
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+	Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+	container = document.createElement("div");
+	document.body.appendChild(container);
+	root = createRoot(container);
+});
+
+afterEach(async () => {
+	await act(async () => root.unmount());
+	container.remove();
+	vi.restoreAllMocks();
+});
+
+async function click(element: Element): Promise<void> {
+	await act(async () => {
+		element.dispatchEvent(
+			new MouseEvent("click", { bubbles: true, cancelable: true }),
+		);
+		await Promise.resolve();
+	});
+}
+
+function buttonWithText(text: string): HTMLButtonElement {
+	const button = [
+		...container.querySelectorAll<HTMLButtonElement>("button"),
+	].find((candidate) => candidate.textContent?.includes(text));
+	expect(button).toBeDefined();
+	return button as HTMLButtonElement;
+}
+
+describe("WorkspaceSelector", () => {
+	it("switches both workspace and branch choices from the opened menu", async () => {
+		const onSwitchWorkspace = vi.fn(async () => true);
+		const onSwitchGitBranch = vi.fn(async () => true);
+		await act(async () => {
+			root.render(
+				<WorkspaceSelector
+					currentBranch="main"
+					onListGitBranches={vi.fn(async () => ({
+						current: "main",
+						branches: ["main", "feature/review"],
+					}))}
+					onPickWorkspaceDirectory={vi.fn(async () => null)}
+					onRefreshWorkspaces={vi.fn(async () => undefined)}
+					onSwitchGitBranch={onSwitchGitBranch}
+					onSwitchWorkspace={onSwitchWorkspace}
+					workspaceRoot="/workspace/one"
+					workspaces={["/workspace/one", "/workspace/two"]}
+				/>,
+			);
+		});
+
+		await click(container.querySelector("#git-branch-btn") as Element);
+		await vi.waitFor(() => {
+			expect(container.textContent).toContain("/workspace/two");
+			expect(container.textContent).toContain("feature/review");
+		});
+		await click(buttonWithText("/workspace/two"));
+		await vi.waitFor(() => {
+			expect(onSwitchWorkspace).toHaveBeenCalledWith("/workspace/two");
+		});
+
+		await click(container.querySelector("#git-branch-btn") as Element);
+		await vi.waitFor(() => {
+			expect(container.textContent).toContain("feature/review");
+		});
+		await click(buttonWithText("feature/review"));
+		await vi.waitFor(() => {
+			expect(onSwitchGitBranch).toHaveBeenCalledWith("feature/review");
+		});
+	});
+
+	it("lists the active workspace even when the catalog excludes it", async () => {
+		await act(async () => {
+			root.render(
+				<WorkspaceSelector
+					currentBranch="main"
+					onListGitBranches={vi.fn(async () => ({
+						current: "main",
+						branches: ["main"],
+					}))}
+					onPickWorkspaceDirectory={vi.fn(async () => null)}
+					onRefreshWorkspaces={vi.fn(async () => undefined)}
+					onSwitchGitBranch={vi.fn(async () => true)}
+					onSwitchWorkspace={vi.fn(async () => true)}
+					workspaceRoot="/Users/beatrix/Desktop"
+					workspaces={["/workspace/one"]}
+				/>,
+			);
+		});
+
+		await click(container.querySelector("#git-branch-btn") as Element);
+		await vi.waitFor(() => {
+			expect(container.textContent).toContain("~/Desktop");
+			expect(container.textContent).toContain("/workspace/one");
+		});
+	});
+});

apps/examples/desktop-app/webview/components/views/chat/workspace-selector.tsx

@@ -5,6 +5,7 @@ import { useMemo, useState } from "react";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { cn } from "@/lib/utils";
+import { normalizeWorkspacePath } from "@/lib/workspace-paths";
 
 function formatWorkspacePath(path: string): string {
 	const unixHome = path.match(/^\/Users\/[^/]+\/(.*)$/);
@@ -19,17 +20,6 @@ function formatWorkspacePath(path: string): string {
 	return path;
 }
 
-function normalizeWorkspacePath(path: string): string {
-	const normalized = path.trim().replace(/[\\/]+$/, "");
-	if (!normalized) {
-		return "";
-	}
-	if (/^[A-Za-z]:/.test(normalized)) {
-		return normalized.toLowerCase();
-	}
-	return normalized;
-}
-
 export function WorkspaceSelector({
 	currentBranch,
 	workspaceRoot,
@@ -181,7 +171,20 @@ export function WorkspaceSelector({
 		b.toLowerCase().includes(search.toLowerCase()),
 	);
 
-	const filteredWorkspaces = workspaces.filter((w) =>
+	// The catalog excludes non-project paths (home, Desktop, ~/.cline), but an
+	// explicitly opened workspace must stay visible while it is active.
+	const availableWorkspaces = useMemo(() => {
+		const byNormalizedPath = new Map<string, string>();
+		const register = (path: string) => {
+			const trimmed = path.trim();
+			if (trimmed) byNormalizedPath.set(normalizeWorkspacePath(trimmed), trimmed);
+		};
+		register(workspaceRoot);
+		for (const path of workspaces) register(path);
+		return [...byNormalizedPath.values()];
+	}, [workspaceRoot, workspaces]);
+
+	const filteredWorkspaces = availableWorkspaces.filter((w) =>
 		w.toLowerCase().includes(search.toLowerCase()),
 	);
 
@@ -215,6 +218,7 @@ export function WorkspaceSelector({
 						variant="ghost"
 						aria-label="Close menu"
 						className="fixed inset-0 z-40 cursor-default h-auto rounded-none opacity-0"
+						data-cursor="default"
 						onClick={() => {
 							setOpen(false);
 							setShowWorkspacePathInput(false);

apps/examples/desktop-app/webview/components/views/marketplace-view.tsx

@@ -59,7 +59,7 @@ type InstalledStatusState = "loading" | "ready";
 const INSTALL_TIMEOUT_MS = 300_000;
 const CODE_FONT_STYLE: CSSProperties = {
 	fontFamily:
-		'ui-monospace, "SFMono-Regular", Menlo, Consolas, "Liberation Mono", monospace',
+		'"Azeret Mono", ui-monospace, "SFMono-Regular", Menlo, Consolas, "Liberation Mono", monospace',
 };
 
 const primitivePageDetails = {

apps/examples/desktop-app/webview/components/views/sessions/sessions-view.tsx

@@ -195,10 +195,12 @@ export function SessionsView({ activeSessionId, history }: SessionsViewProps) {
 
 	return (
 		<div className="flex h-full min-h-0 flex-col overflow-hidden bg-background text-foreground">
-			<header className="flex shrink-0 items-center justify-between gap-4 border-b px-6 py-4">
+			<header className="flex shrink-0 items-end justify-between gap-6 px-18 pb-7 pt-10 max-[1200px]:px-8 max-md:pl-12 max-[720px]:flex-col max-[720px]:items-stretch max-[720px]:pr-4 max-[720px]:pt-5">
 				<div className="min-w-0">
-					<h1 className="text-lg font-semibold leading-tight">Sessions</h1>
-					<p className="mt-1 text-sm text-muted-foreground">
+					<h1 className="text-[32px] font-semibold leading-[1.15] tracking-normal">
+						Sessions
+					</h1>
+					<p className="mt-3 text-[15px] leading-6 text-muted-foreground">
 						Recent sessions across clients and workspaces.
 					</p>
 				</div>
@@ -228,10 +230,10 @@ export function SessionsView({ activeSessionId, history }: SessionsViewProps) {
 						</DropdownMenuTrigger>
 						<DropdownMenuContent align="end" sideOffset={6}>
 							<DropdownMenuItem onClick={() => setSortDirection("newest")}>
-								{sortDirection === "newest" ? "Newest first" : "Newest first"}
+								Newest first
 							</DropdownMenuItem>
 							<DropdownMenuItem onClick={() => setSortDirection("oldest")}>
-								{sortDirection === "oldest" ? "Oldest first" : "Oldest first"}
+								Oldest first
 							</DropdownMenuItem>
 						</DropdownMenuContent>
 					</DropdownMenu>
@@ -284,7 +286,7 @@ export function SessionsView({ activeSessionId, history }: SessionsViewProps) {
 				</div>
 			</header>
 
-			<section className="min-h-0 flex-1 overflow-auto px-6 py-5">
+			<section className="min-h-0 flex-1 overflow-auto px-18 pb-10 max-[1200px]:px-8 max-[720px]:px-4">
 				<div className="min-w-240 overflow-hidden rounded-lg border bg-card">
 					<div className="grid grid-cols-[minmax(14rem,1.35fr)_minmax(9rem,0.8fr)_minmax(12rem,1fr)_7rem_5rem_6rem_2.5rem] gap-x-4 bg-muted/40 px-4 py-3 text-sm font-medium text-muted-foreground">
 						<span>Session</span>
@@ -293,7 +295,7 @@ export function SessionsView({ activeSessionId, history }: SessionsViewProps) {
 						<span>Tokens</span>
 						<span>Cost</span>
 						<span>Updated</span>
-						<span />
+						<span className="sr-only">Actions</span>
 					</div>
 					<div>
 						{history.isLoadingHistory && history.threads.length === 0 ? (
@@ -412,12 +414,15 @@ export function SessionsView({ activeSessionId, history }: SessionsViewProps) {
 											type="button"
 										>
 											<span className="flex min-w-0 items-center gap-3 font-semibold">
+												<span className="sr-only">Open session: </span>
 												<span
 													className={cn(
 														"size-1.5 shrink-0 rounded-full",
 														statusTone(thread.status),
 													)}
+													aria-hidden="true"
 												/>
+												<span className="sr-only">{thread.status}: </span>
 												<span className="truncate">{thread.title}</span>
 											</span>
 											<span className="flex min-w-0 items-center gap-2 text-muted-foreground">
@@ -440,42 +445,44 @@ export function SessionsView({ activeSessionId, history }: SessionsViewProps) {
 											</span>
 										</button>
 									)}
-									<DropdownMenu>
-										<DropdownMenuTrigger asChild>
-											<button
-												aria-label={`Session actions for ${thread.title}`}
-												className="grid size-7 place-items-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-												disabled={Boolean(pendingKind)}
-												type="button"
-											>
-												{pendingKind ? (
-													<Loader2 className="size-4 animate-spin" />
-												) : (
-													<MoreHorizontal className="size-4" />
-												)}
-											</button>
-										</DropdownMenuTrigger>
-										<DropdownMenuContent align="end" sideOffset={6}>
-											<DropdownMenuItem onClick={() => startRename(thread)}>
-												<Pencil className="size-4" />
-												Rename
-											</DropdownMenuItem>
-											<DropdownMenuItem
-												onClick={() => void history.forkThread(thread.id)}
-											>
-												<GitFork className="size-4" />
-												Fork
-											</DropdownMenuItem>
-											<DropdownMenuSeparator />
-											<DropdownMenuItem
-												onClick={() => setDeleteCandidate(thread)}
-												variant="destructive"
-											>
-												<Trash2 className="size-4" />
-												Delete
-											</DropdownMenuItem>
-										</DropdownMenuContent>
-									</DropdownMenu>
+									<div>
+										<DropdownMenu>
+											<DropdownMenuTrigger asChild>
+												<button
+													aria-label={`Session actions for ${thread.title}`}
+													className="grid size-7 place-items-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+													disabled={Boolean(pendingKind)}
+													type="button"
+												>
+													{pendingKind ? (
+														<Loader2 className="size-4 animate-spin" />
+													) : (
+														<MoreHorizontal className="size-4" />
+													)}
+												</button>
+											</DropdownMenuTrigger>
+											<DropdownMenuContent align="end" sideOffset={6}>
+												<DropdownMenuItem onClick={() => startRename(thread)}>
+													<Pencil className="size-4" />
+													Rename
+												</DropdownMenuItem>
+												<DropdownMenuItem
+													onClick={() => void history.forkThread(thread.id)}
+												>
+													<GitFork className="size-4" />
+													Fork
+												</DropdownMenuItem>
+												<DropdownMenuSeparator />
+												<DropdownMenuItem
+													onClick={() => setDeleteCandidate(thread)}
+													variant="destructive"
+												>
+													<Trash2 className="size-4" />
+													Delete
+												</DropdownMenuItem>
+											</DropdownMenuContent>
+										</DropdownMenu>
+									</div>
 								</div>
 							);
 						})}

apps/examples/desktop-app/webview/components/views/settings/settings-view.tsx

@@ -1,9 +1,19 @@
-import { X } from "lucide-react";
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { Button } from "@/components/ui/button";
-import { ScrollArea } from "@/components/ui/scroll-area";
 import { Switch } from "@/components/ui/switch";
+import {
+	MAX_CHAT_BACKGROUND_BYTES,
+	readChatBackground,
+	setChatBackground,
+} from "@/lib/chat-background";
 import { desktopClient } from "@/lib/desktop-client";
+import {
+	DEFAULT_NYAN_PET_SRC,
+	MAX_NYAN_PET_BYTES,
+	readStoredPetGif,
+	setStoredPetGif,
+} from "@/lib/nyan-pet";
+import { hidePet, isPetVisible, isTauri, showPet } from "@/lib/pet-window";
 import type {
 	Provider,
 	ProviderCatalogResponse,
@@ -16,7 +26,6 @@ import {
 	readSystemHubTheme,
 	setStoredHubTheme,
 } from "@/lib/theme";
-import { cn } from "@/lib/utils";
 import { PageFrame, PageHeader } from "../page-layout";
 import { AccountView } from "./account-view";
 import { AddProviderContent, type AddProviderPayload } from "./add-provider";
@@ -34,18 +43,22 @@ import { toSettingsPatch } from "./settings-patch";
 // Settings nav categories
 // -----------------------------------------------------------
 
-const navCategories = [
+export const SETTINGS_SECTIONS = [
 	"General",
-	"Providers",
-	"MCP",
-	"Marketplace",
-	"Extensions",
+	"Models",
+	"MCP Servers",
+	"MCP Marketplace",
+	"Customizations",
 	"Channels",
 	"Schedules",
 	"Account",
 ] as const;
 
-export type SettingsSection = (typeof navCategories)[number];
+export type SettingsSection = (typeof SETTINGS_SECTIONS)[number];
+type GlobalSettingsResponse = {
+	telemetryOptOut: boolean;
+	autoUpdateEnabled: boolean;
+};
 
 const PROVIDER_CATALOG_CACHE_TTL_MS = 60_000;
 
@@ -59,17 +72,13 @@ let providerCatalogCache: {
 // -----------------------------------------------------------
 
 export function SettingsView({
-	chrome = "full",
-	initialSection = "General",
-	onClose,
+	section,
 	onNavigateSection,
 }: {
-	chrome?: "full" | "content";
-	initialSection?: SettingsSection;
-	onClose: () => void;
-	onNavigateSection?: (section: SettingsSection) => void;
+	section: SettingsSection;
+	onNavigateSection: (section: SettingsSection) => void;
 }) {
-	const [activeNav, setActiveNav] = useState<SettingsSection>(initialSection);
+	const activeNav = section;
 	const [providers, setProviders] = useState<Provider[]>(
 		() => providerCatalogCache?.providers ?? [],
 	);
@@ -93,6 +102,13 @@ export function SettingsView({
 	);
 	const [addingProvider, setAddingProvider] = useState(false);
 
+	useEffect(() => {
+		if (section !== "Models") {
+			setSelectedProviderId(null);
+			setAddingProvider(false);
+		}
+	}, [section]);
+
 	const setProvidersWithCache = useCallback(
 		(next: Provider[] | ((prev: Provider[]) => Provider[])) => {
 			setProviders((prev) => {
@@ -139,7 +155,7 @@ export function SettingsView({
 	}, [setProvidersWithCache]);
 
 	useEffect(() => {
-		if (activeNav !== "Providers") {
+		if (activeNav !== "Models") {
 			return;
 		}
 		const timeoutId = window.setTimeout(() => {
@@ -288,8 +304,7 @@ export function SettingsView({
 	};
 
 	const openProviderDetail = (id: string) => {
-		setActiveNav("Providers");
-		onNavigateSection?.("Providers");
+		onNavigateSection("Models");
 		setSelectedProviderId(id);
 	};
 
@@ -310,7 +325,7 @@ export function SettingsView({
 	}, [loadProviderModels, providers, selectedProviderId]);
 
 	const backToProviderList = () => {
-		onNavigateSection?.("Providers");
+		onNavigateSection("Models");
 		setSelectedProviderId(null);
 		setAddingProvider(false);
 	};
@@ -337,18 +352,11 @@ export function SettingsView({
 	);
 
 	const openAddProvider = () => {
-		onNavigateSection?.("Providers");
+		onNavigateSection("Models");
 		setSelectedProviderId(null);
 		setAddingProvider(true);
 	};
 
-	const selectSection = (section: SettingsSection) => {
-		setActiveNav(section);
-		onNavigateSection?.(section);
-		setSelectedProviderId(null);
-		setAddingProvider(false);
-	};
-
 	const providerContent = addingProvider ? (
 		<AddProviderContent
 			existingProviderIds={providers.map((provider) => provider.id)}
@@ -403,13 +411,13 @@ export function SettingsView({
 	);
 
 	const content =
-		activeNav === "Providers" ? (
+		activeNav === "Models" ? (
 			providerContent
-		) : activeNav === "MCP" ? (
+		) : activeNav === "MCP Servers" ? (
 			<McpServersContent />
-		) : activeNav === "Marketplace" ? (
+		) : activeNav === "MCP Marketplace" ? (
 			<CustomizationSectionView catalogPrimitive="mcp" section="MCP" />
-		) : activeNav === "Extensions" ? (
+		) : activeNav === "Customizations" ? (
 			<RulesView />
 		) : activeNav === "Channels" ? (
 			<ChannelsContent />
@@ -427,57 +435,10 @@ export function SettingsView({
 			</div>
 		);
 
-	if (chrome === "content") {
-		return (
-			<div className="h-full overflow-hidden bg-background">{content}</div>
-		);
-	}
-
 	return (
-		<div className="flex h-full flex-col overflow-hidden bg-background">
-			{/* Header bar */}
-			<div className="flex shrink-0 items-center justify-between border-b border-border px-6 py-3">
-				<h1 className="text-lg font-semibold text-foreground">Settings</h1>
-				<Button
-					aria-label="Close settings"
-					className="justify-start"
-					onClick={onClose}
-					variant="ghost"
-				>
-					<X className="size-3" />
-				</Button>
-			</div>
-
-			{/* Body */}
-			<div className="flex flex-1 overflow-hidden">
-				{/* Settings sidebar nav */}
-				<nav className="w-56 shrink-0 border-r border-border">
-					<ScrollArea className="h-full">
-						<div className="flex flex-col gap-0.5 p-3">
-							{navCategories.map((cat) => (
-								<Button
-									className={cn(
-										"justify-start",
-										activeNav === cat
-											? "bg-accent text-accent-foreground font-medium"
-											: "text-muted-foreground hover:bg-accent/50 hover:text-foreground",
-									)}
-									key={cat}
-									onClick={() => {
-										selectSection(cat);
-									}}
-									variant="ghost"
-								>
-									{cat}
-								</Button>
-							))}
-						</div>
-					</ScrollArea>
-				</nav>
-
-				{/* Content area */}
-				<div className="flex-1 overflow-hidden">{content}</div>
-			</div>
+		<div className="grid h-full grid-rows-[3rem_minmax(0,1fr)] overflow-hidden bg-background md:block">
+			<div aria-hidden="true" className="md:hidden" />
+			<div className="min-h-0 overflow-hidden md:h-full">{content}</div>
 		</div>
 	);
 }
@@ -487,6 +448,82 @@ function GeneralSettingsContent() {
 		if (typeof window === "undefined") return "light";
 		return readStoredHubTheme() ?? readSystemHubTheme();
 	});
+	const [telemetryOptOut, setTelemetryOptOut] = useState(false);
+	const [telemetryLoading, setTelemetryLoading] = useState(true);
+	const [telemetrySaving, setTelemetrySaving] = useState(false);
+	const [telemetryError, setTelemetryError] = useState<string | null>(null);
+	const [autoUpdateEnabled, setAutoUpdateEnabled] = useState(true);
+	const [autoUpdateLoading, setAutoUpdateLoading] = useState(true);
+	const [autoUpdateSaving, setAutoUpdateSaving] = useState(false);
+	const [autoUpdateError, setAutoUpdateError] = useState<string | null>(null);
+
+	const loadGlobalSettings = useCallback(async () => {
+		setTelemetryLoading(true);
+		setTelemetryError(null);
+		setAutoUpdateLoading(true);
+		setAutoUpdateError(null);
+		try {
+			const settings = await desktopClient.invoke<GlobalSettingsResponse>(
+				"get_global_settings",
+			);
+			setTelemetryOptOut(settings.telemetryOptOut);
+			setAutoUpdateEnabled(settings.autoUpdateEnabled);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			setTelemetryError(message);
+			setAutoUpdateError(message);
+		} finally {
+			setTelemetryLoading(false);
+			setAutoUpdateLoading(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		const timeoutId = window.setTimeout(() => {
+			void loadGlobalSettings();
+		}, 0);
+		return () => window.clearTimeout(timeoutId);
+	}, [loadGlobalSettings]);
+
+	const updateTelemetryOptOut = async (nextValue: boolean) => {
+		const previousValue = telemetryOptOut;
+		setTelemetryOptOut(nextValue);
+		setTelemetrySaving(true);
+		setTelemetryError(null);
+		try {
+			const settings = await desktopClient.invoke<GlobalSettingsResponse>(
+				"set_telemetry_opt_out",
+				{ telemetry_opt_out: nextValue },
+			);
+			setTelemetryOptOut(settings.telemetryOptOut);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			setTelemetryOptOut(previousValue);
+			setTelemetryError(message);
+		} finally {
+			setTelemetrySaving(false);
+		}
+	};
+
+	const updateAutoUpdateEnabled = async (nextValue: boolean) => {
+		const previousValue = autoUpdateEnabled;
+		setAutoUpdateEnabled(nextValue);
+		setAutoUpdateSaving(true);
+		setAutoUpdateError(null);
+		try {
+			const settings = await desktopClient.invoke<GlobalSettingsResponse>(
+				"set_auto_update_enabled",
+				{ auto_update_enabled: nextValue },
+			);
+			setAutoUpdateEnabled(settings.autoUpdateEnabled);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			setAutoUpdateEnabled(previousValue);
+			setAutoUpdateError(message);
+		} finally {
+			setAutoUpdateSaving(false);
+		}
+	};
 
 	const updateTheme = (darkModeEnabled: boolean) => {
 		const nextTheme = darkModeEnabled ? "dark" : "light";
@@ -515,7 +552,303 @@ function GeneralSettingsContent() {
 						onCheckedChange={updateTheme}
 					/>
 				</div>
+				<div className="flex min-h-20 items-center justify-between gap-5 border-b max-[720px]:flex-col max-[720px]:items-stretch max-[720px]:py-4">
+					<div>
+						<p className="text-[17px] font-semibold text-foreground">
+							Auto update
+						</p>
+						<p className="mt-1 text-[15px] text-muted-foreground">
+							Automatically install Cline CLI updates on startup.
+						</p>
+						{autoUpdateError ? (
+							<p className="mt-2 text-xs text-destructive" role="alert">
+								Failed to update auto update setting: {autoUpdateError}
+							</p>
+						) : null}
+					</div>
+					<Switch
+						aria-label="Auto update"
+						checked={autoUpdateEnabled}
+						disabled={autoUpdateLoading || autoUpdateSaving}
+						onCheckedChange={(checked) => void updateAutoUpdateEnabled(checked)}
+					/>
+				</div>
+				<div className="flex min-h-20 items-center justify-between gap-5 border-b max-[720px]:flex-col max-[720px]:items-stretch max-[720px]:py-4">
+					<div>
+						<p className="text-[17px] font-semibold text-foreground">
+							Telemetry
+						</p>
+						<p className="mt-1 text-[15px] text-muted-foreground">
+							Enable error and usage reports to help improve Cline.
+						</p>
+						{telemetryError ? (
+							<p className="mt-2 text-xs text-destructive" role="alert">
+								Failed to update telemetry setting: {telemetryError}
+							</p>
+						) : null}
+					</div>
+					<Switch
+						aria-label="Telemetry"
+						checked={!telemetryOptOut}
+						disabled={telemetryLoading || telemetrySaving}
+						onCheckedChange={(checked) => void updateTelemetryOptOut(!checked)}
+					/>
+				</div>
+				<NyanPetSetting />
+				<PetWindowToggle />
+				<ChatBackgroundSetting />
 			</section>
 		</PageFrame>
 	);
 }
+
+function ChatBackgroundSetting() {
+	const inputRef = useRef<HTMLInputElement | null>(null);
+	const [background, setBackground] = useState<string | null>(null);
+	const [error, setError] = useState<string | null>(null);
+
+	useEffect(() => {
+		setBackground(readChatBackground());
+	}, []);
+
+	const handleFile = useCallback((file: File | undefined) => {
+		if (!file) {
+			return;
+		}
+		setError(null);
+		if (!file.type.startsWith("image/")) {
+			setError("Please choose an image file.");
+			return;
+		}
+		if (file.size > MAX_CHAT_BACKGROUND_BYTES) {
+			setError("That image is too large. Please pick one under 3 MB.");
+			return;
+		}
+		const reader = new FileReader();
+		reader.onload = () => {
+			const dataUrl = typeof reader.result === "string" ? reader.result : null;
+			if (!dataUrl) {
+				setError("Could not read that image.");
+				return;
+			}
+			try {
+				setChatBackground(dataUrl);
+				setBackground(dataUrl);
+			} catch {
+				setError("Could not save that image — it may be too large to store.");
+			}
+		};
+		reader.onerror = () => setError("Could not read that image.");
+		reader.readAsDataURL(file);
+	}, []);
+
+	const handleReset = useCallback(() => {
+		setChatBackground(null);
+		setBackground(null);
+		setError(null);
+		if (inputRef.current) {
+			inputRef.current.value = "";
+		}
+	}, []);
+
+	return (
+		<div className="flex min-h-20 items-center justify-between gap-5 border-b max-[720px]:flex-col max-[720px]:items-stretch max-[720px]:py-4">
+			<div>
+				<p className="text-[17px] font-semibold text-foreground">
+					Chat background
+				</p>
+				<p className="mt-1 text-[15px] text-muted-foreground">
+					Upload an image to show behind your chat conversation.
+				</p>
+				{error ? (
+					<p className="mt-2 text-xs text-destructive" role="alert">
+						{error}
+					</p>
+				) : null}
+			</div>
+			<div className="flex shrink-0 items-center gap-3 max-[720px]:justify-end">
+				<div className="flex h-14 w-24 items-center justify-center overflow-hidden rounded-md border bg-muted/40">
+					{background ? (
+						// biome-ignore lint/performance/noImgElement: user-provided data URL, not statically optimizable
+						<img
+							alt="MCP background preview"
+							className="h-full w-full object-cover"
+							src={background}
+						/>
+					) : (
+						<span className="text-xs text-muted-foreground">None</span>
+					)}
+				</div>
+				<input
+					accept="image/gif,image/png,image/jpeg,image/webp"
+					className="hidden"
+					onChange={(event) => {
+						handleFile(event.target.files?.[0]);
+						event.target.value = "";
+					}}
+					ref={inputRef}
+					type="file"
+				/>
+				<Button
+					onClick={() => inputRef.current?.click()}
+					type="button"
+					variant="outline"
+				>
+					Upload image
+				</Button>
+				{background ? (
+					<Button onClick={handleReset} type="button" variant="ghost">
+						Reset
+					</Button>
+				) : null}
+			</div>
+		</div>
+	);
+}
+
+function PetWindowToggle() {
+	const [inDesktopApp, setInDesktopApp] = useState(false);
+	const [visible, setVisible] = useState(false);
+
+	useEffect(() => {
+		if (!isTauri()) {
+			return;
+		}
+		setInDesktopApp(true);
+		void isPetVisible().then(setVisible);
+	}, []);
+
+	const toggle = useCallback(async (next: boolean) => {
+		setVisible(next);
+		if (next) {
+			await showPet();
+		} else {
+			await hidePet();
+		}
+	}, []);
+
+	// Only meaningful in the desktop app, where the pet is its own OS window.
+	if (!inDesktopApp) {
+		return null;
+	}
+
+	return (
+		<div className="flex min-h-20 items-center justify-between gap-5 border-b max-[720px]:flex-col max-[720px]:items-stretch max-[720px]:py-4">
+			<div>
+				<p className="text-[17px] font-semibold text-foreground">
+					Show floating pet
+				</p>
+				<p className="mt-1 text-[15px] text-muted-foreground">
+					Float the pet on top of your screen so it stays visible even when this
+					window is minimized or closed.
+				</p>
+			</div>
+			<Switch
+				aria-label="Show floating pet"
+				checked={visible}
+				onCheckedChange={(checked) => void toggle(checked)}
+			/>
+		</div>
+	);
+}
+
+function NyanPetSetting() {
+	const inputRef = useRef<HTMLInputElement | null>(null);
+	const [petGif, setPetGif] = useState<string | null>(null);
+	const [error, setError] = useState<string | null>(null);
+
+	useEffect(() => {
+		setPetGif(readStoredPetGif());
+	}, []);
+
+	const handleFile = useCallback((file: File | undefined) => {
+		if (!file) {
+			return;
+		}
+		setError(null);
+		if (!file.type.startsWith("image/")) {
+			setError("Please choose an image file — an animated GIF works best.");
+			return;
+		}
+		if (file.size > MAX_NYAN_PET_BYTES) {
+			setError("That image is too large. Please pick one under 3 MB.");
+			return;
+		}
+		const reader = new FileReader();
+		reader.onload = () => {
+			const dataUrl = typeof reader.result === "string" ? reader.result : null;
+			if (!dataUrl) {
+				setError("Could not read that image.");
+				return;
+			}
+			try {
+				setStoredPetGif(dataUrl);
+				setPetGif(dataUrl);
+			} catch {
+				setError("Could not save that image — it may be too large to store.");
+			}
+		};
+		reader.onerror = () => setError("Could not read that image.");
+		reader.readAsDataURL(file);
+	}, []);
+
+	const handleReset = useCallback(() => {
+		setStoredPetGif(null);
+		setPetGif(null);
+		setError(null);
+		if (inputRef.current) {
+			inputRef.current.value = "";
+		}
+	}, []);
+
+	const previewSrc = petGif ?? DEFAULT_NYAN_PET_SRC;
+
+	return (
+		<div className="flex min-h-20 items-center justify-between gap-5 border-b max-[720px]:flex-col max-[720px]:items-stretch max-[720px]:py-4">
+			<div>
+				<p className="text-[17px] font-semibold text-foreground">Desktop pet</p>
+				<p className="mt-1 text-[15px] text-muted-foreground">
+					Replace Nyan Cat with your own GIF. It floats on top of the app, and
+					its tune plays while you hover or drag it.
+				</p>
+				{error ? (
+					<p className="mt-2 text-xs text-destructive" role="alert">
+						{error}
+					</p>
+				) : null}
+			</div>
+			<div className="flex shrink-0 items-center gap-3 max-[720px]:justify-end">
+				<div className="flex h-14 w-20 items-center justify-center overflow-hidden rounded-md border bg-muted/40">
+					{/* biome-ignore lint/performance/noImgElement: user-provided data URL, not statically optimizable */}
+					<img
+						alt="Desktop pet preview"
+						className="max-h-full max-w-full object-contain"
+						src={previewSrc}
+					/>
+				</div>
+				<input
+					accept="image/gif,image/png,image/jpeg,image/webp"
+					className="hidden"
+					onChange={(event) => {
+						handleFile(event.target.files?.[0]);
+						event.target.value = "";
+					}}
+					ref={inputRef}
+					type="file"
+				/>
+				<Button
+					onClick={() => inputRef.current?.click()}
+					type="button"
+					variant="outline"
+				>
+					Upload GIF
+				</Button>
+				{petGif ? (
+					<Button onClick={handleReset} type="button" variant="ghost">
+						Reset
+					</Button>
+				) : null}
+			</div>
+		</div>
+	);
+}