chore(desktop): release v0.0.24

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBdgHNDCfm7WKP8qbvn7cr

.changeset/text-only-model-image-warning.md

@@ -0,0 +1,5 @@
+---
+"claude-dev": patch
+---
+
+Warn when attached images will be ignored because the selected model does not support image input: image thumbnails get a warning badge and the composer offers to switch to an image-capable model, instead of the images being silently dropped before the API call

.cline/skills/publish-cli/SKILL.md

@@ -7,7 +7,7 @@ description: Use when preparing, tagging, and publishing an apps/cli npm release
 
 Use this skill when the user asks to release the CLI, publish `cline`, bump the CLI version, draft release notes, create a `cli-vX.Y.Z` tag, or trigger the CLI publish workflow.
 
-The CLI is npm-only. Do not add alternate distribution or signing steps.
+The CLI is npm-only. Do not add alternate distribution channels. Windows binaries are Authenticode-signed automatically by the publish workflow via Azure Trusted Signing (see the `.github/actions/sign-windows-cli` composite action and "Windows code signing" in `apps/cli/DISTRIBUTION.md`); if the signing secrets are not configured the workflow warns and publishes unsigned binaries. Local publishes (`bun release cli`) do not sign — prefer the GitHub Actions publish path for releases users run on Windows.
 
 > Working directory: run every command below from the repository root. Paths and scripts (e.g. `apps/cli/package.json`, `sdk/packages/`, `bun release cli`, `bun run version`) are written relative to the repo root.
 

.cline/skills/publish-desktop/SKILL.md

@@ -9,7 +9,7 @@ Use this skill when the user asks to release the desktop app, publish the Cline
 
 > Working directory: run every command below from the repository root.
 
-Desktop releases are macOS-only today (a single signed + notarized universal DMG that runs natively on both Apple Silicon and Intel) and are built entirely in GitHub Actions — there is no local publish path. Installed apps discover new releases automatically through the Tauri updater, so publishing a release is what ships the update to every existing user **on that channel**.
+Desktop releases ship two platforms, built entirely in GitHub Actions — there is no local publish path. macOS: a single signed + notarized universal DMG that runs natively on both Apple Silicon and Intel. Windows: an Authenticode-signed NSIS installer (`<Product>_<version>_x64-setup.exe`), signed via Azure Trusted Signing in the `build-windows` job (jsign through Tauri's `signCommand`, see `apps/examples/desktop-app/scripts/tauri-sign-windows.ps1`; requires the repo-level `AZURE_*` secrets including `AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_DESKTOP`, plus a `PublishDesktop`-environment federated credential on the `cline-cli-signing` Entra app). Installed apps discover new releases automatically through the Tauri updater, so publishing a release is what ships the update to every existing user **on that channel**.
 
 ## Release contract
 
@@ -21,7 +21,7 @@ Desktop releases are macOS-only today (a single signed + notarized universal DMG
 - Release prep includes approved release notes, the version bumps, and an `apps/examples/desktop-app/CHANGELOG.md` update — committed on `main` for stable, on `desktop-experimental` for beta.
 - Publish path: `.github/workflows/desktop-publish.yml` (workflow_dispatch, requires the tag to exist, point at the checked-out commit, and be reachable from the channel's branch — `origin/main` for stable, `origin/desktop-experimental` for beta).
 - **Both channels dispatch from `main`.** This is a security invariant, not a convenience: the run executes `main`'s workflow copy and only the checkout points at the tag, so the signing-secret gates (the `github.ref == main` check and the PublishDesktop environment's main-only deployment-branch policy) hold for beta too. Never add `desktop-experimental` to the PublishDesktop deployment-branch policy.
-- The workflow creates the tag's GitHub release (universal DMG + updater artifact + `latest.json`; marked prerelease for beta) and refreshes the channel's rolling feed release, which is the static auto-update feed every installed app on that channel polls. Never delete the `desktop-latest` or `desktop-beta` release or tag.
+- The workflow creates the tag's GitHub release (universal DMG + macOS updater artifact + Windows NSIS installer with its updater signature + `latest.json`; marked prerelease for beta) and refreshes the channel's rolling feed release, which is the static auto-update feed every installed app on that channel polls. Never delete the `desktop-latest` or `desktop-beta` release or tag.
 - The changelog's `## <version>` section (exact-match, not "topmost") is extracted verbatim into the GitHub release body, the Slack announcement, and the updater manifest notes.
 - Always ask before pushing commits or tags.
 
@@ -120,7 +120,7 @@ gh api repos/cline/cline/actions/runs/<run-id>/pending_deployments \
 
 Nothing after `validate` runs — and no signing key is readable — until then.
 
-The workflow builds one universal macOS bundle (`tauri build --target universal-apple-darwin` lipos the aarch64 + x86_64 Rust binaries; the Bun sidecar is lipo'd by `build-sidecar-bin.ts`; beta adds the `tauri.beta.conf.json` overlay), verifies every Mach-O in the bundle carries both slices and that the compiled binary embeds exactly its own channel's feed URL, signs with the Developer ID certificate, notarizes with the App Store Connect API key, signs the updater artifact with the Tauri updater key, creates the GitHub release (prerelease for beta), refreshes the channel's feed (`desktop-latest/latest.json` or `desktop-beta/latest.json`), and posts to Slack. Notarization typically adds 2–10 minutes.
+The workflow builds one universal macOS bundle (`tauri build --target universal-apple-darwin` lipos the aarch64 + x86_64 Rust binaries; the Bun sidecar is lipo'd by `build-sidecar-bin.ts`; beta adds the `tauri.beta.conf.json` overlay), verifies every Mach-O in the bundle carries both slices and that the compiled binary embeds exactly its own channel's feed URL, signs with the Developer ID certificate, notarizes with the App Store Connect API key, and signs the updater artifact with the Tauri updater key. In parallel, `build-windows` builds the x64 NSIS installer on a Windows runner, Authenticode-signs every binary via Azure Trusted Signing (Tauri `signCommand` -> `scripts/tauri-sign-windows.ps1`), runs the same feed-endpoint and telemetry guardrails, and verifies the shipped installer with `Get-AuthenticodeSignature`. The release job then creates the GitHub release (prerelease for beta), refreshes the channel's feed (`desktop-latest/latest.json` or `desktop-beta/latest.json`), and posts to Slack. Notarization typically adds 2–10 minutes.
 
 If the workflow fails on missing credentials, see "Publish secrets (one-time setup)" below.
 
@@ -131,7 +131,7 @@ curl -sL https://github.com/cline/cline/releases/download/desktop-latest/latest.
 curl -sL https://github.com/cline/cline/releases/download/desktop-beta/latest.json | head -30    # beta
 ```
 
-The `version` field must be the new release and both `darwin-aarch64` and `darwin-x86_64` entries must point at the same new universal `.app.tar.gz` asset under the release tag (each slice of the fat binary requests its own arch key at runtime, so both keys serve the one artifact). Installed apps on that channel — including older per-arch installs — pick the update up on next launch or within 2 hours.
+The `version` field must be the new release; both `darwin-aarch64` and `darwin-x86_64` entries must point at the same new universal `.app.tar.gz` asset under the release tag (each slice of the fat binary requests its own arch key at runtime, so both keys serve the one artifact), and the `windows-x86_64` entry must point at the new `*_x64-setup.exe` asset. Installed apps on that channel — including older per-arch installs — pick the update up on next launch or within 2 hours.
 
 After a **beta** publish, also confirm the stable feed was not touched: `desktop-latest/latest.json` must still serve the previous stable version. (The workflow guards this fail-closed, but it is cheap to verify and catastrophic to miss — the updater comparator is a plain semver "newer than", so a beta manifest on `desktop-latest` would auto-update every stable install onto the beta.)
 

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -15,6 +15,8 @@ body:
         - VSCode Extension
         - JetBrains Plugin
         - CLI
+        - Desktop App
+        - Cloud Platform
       default: 0
     validations:
       required: true
@@ -62,13 +64,15 @@ body:
   - type: textarea
     id: ide-diagnostics
     attributes:
-      label: IDE / CLI Diagnostics
+      label: Diagnostics
       description: |
-        Paste the "About" diagnostics for your Cline surface. This captures the IDE build, runtime, and host details we need.
+        Paste the diagnostics for your Cline surface. This captures the build, runtime, and host details we need.
         - VSCode Extension: open `Help → About` (Windows/Linux) or `Code → About Visual Studio Code` (macOS), then copy the info.
         - JetBrains Plugin: open `Help → About` (Windows/Linux) or `<IDE name> → About` (macOS), then click `Copy` to grab build, runtime, OS, memory, and cores.
         - CLI: there is no About dialog. Run `cline --version` and paste the output.
-      placeholder: Paste the copied About info or `cline --version` output here.
+        - Desktop App: paste the app version from the Settings view.
+        - Cloud Platform: paste your browser name and version, plus the page URL where the issue occurred.
+      placeholder: Paste the copied About info, `cline --version` output, or browser/app details here.
     validations:
       required: false
   - type: textarea

.github/actions/sign-windows-cli/action.yml

@@ -0,0 +1,155 @@
+name: Sign Windows CLI binaries
+description: >
+  Authenticode-signs the compiled Windows CLI executables with Azure Trusted
+  Signing (via jsign, so it runs on Linux runners) and verifies the resulting
+  signatures. If the Azure Trusted Signing secrets are not configured, the
+  action logs a warning and exits successfully so releases keep working while
+  signing infrastructure is being provisioned.
+
+inputs:
+  azure-client-id:
+    description: Client ID of the Entra app with the Trusted Signing Certificate Profile Signer role (OIDC federated credential, no client secret).
+    required: false
+    default: ""
+  azure-tenant-id:
+    description: Entra tenant ID.
+    required: false
+    default: ""
+  azure-subscription-id:
+    description: Azure subscription ID containing the Trusted Signing account.
+    required: false
+    default: ""
+  endpoint:
+    description: Trusted Signing account endpoint, for example https://eus.codesigning.azure.net.
+    required: false
+    default: ""
+  account:
+    description: Trusted Signing account name.
+    required: false
+    default: ""
+  certificate-profile:
+    description: Trusted Signing certificate profile name.
+    required: false
+    default: ""
+  files:
+    description: Newline-separated list of PE files to sign.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Check signing configuration
+      id: check
+      shell: bash
+      env:
+        AZURE_CLIENT_ID: ${{ inputs.azure-client-id }}
+        AZURE_TENANT_ID: ${{ inputs.azure-tenant-id }}
+        AZURE_SUBSCRIPTION_ID: ${{ inputs.azure-subscription-id }}
+        SIGNING_ENDPOINT: ${{ inputs.endpoint }}
+        SIGNING_ACCOUNT: ${{ inputs.account }}
+        SIGNING_PROFILE: ${{ inputs.certificate-profile }}
+      run: |
+        missing=()
+        set_count=0
+        for var in AZURE_CLIENT_ID AZURE_TENANT_ID AZURE_SUBSCRIPTION_ID SIGNING_ENDPOINT SIGNING_ACCOUNT SIGNING_PROFILE; do
+          if [ -z "${!var}" ]; then
+            missing+=("$var")
+          else
+            set_count=$((set_count + 1))
+          fi
+        done
+
+        if [ "${#missing[@]}" -eq 0 ]; then
+          echo "Azure Trusted Signing is configured; Windows binaries will be signed."
+          echo "enabled=true" >> "$GITHUB_OUTPUT"
+        elif [ "$set_count" -eq 0 ]; then
+          echo "::warning::Azure Trusted Signing is not configured; publishing UNSIGNED Windows binaries. Set the AZURE_* and AZURE_TRUSTED_SIGNING_* repository secrets to enable signing."
+          echo "enabled=false" >> "$GITHUB_OUTPUT"
+        else
+          # Partial configuration is almost certainly a typo'd or renamed
+          # secret. Fail loudly instead of silently publishing unsigned.
+          echo "::error::Azure Trusted Signing is PARTIALLY configured; refusing to publish. Missing: ${missing[*]}"
+          exit 1
+        fi
+
+    - name: Azure login (OIDC)
+      if: steps.check.outputs.enabled == 'true'
+      uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2.3.0
+      with:
+        client-id: ${{ inputs.azure-client-id }}
+        tenant-id: ${{ inputs.azure-tenant-id }}
+        subscription-id: ${{ inputs.azure-subscription-id }}
+
+    - name: Sign Windows binaries
+      if: steps.check.outputs.enabled == 'true'
+      shell: bash
+      env:
+        SIGNING_ENDPOINT: ${{ inputs.endpoint }}
+        SIGNING_ACCOUNT: ${{ inputs.account }}
+        SIGNING_PROFILE: ${{ inputs.certificate-profile }}
+        FILES: ${{ inputs.files }}
+        JSIGN_VERSION: "7.5"
+        JSIGN_SHA256: "602a51c3545a6dc4fb99bd2ea7152b26d1345916d0c93ddfbd5936cb735af91c"
+      run: |
+        set -euo pipefail
+
+        JSIGN_JAR="${RUNNER_TEMP}/jsign-${JSIGN_VERSION}.jar"
+        curl -fsSL -o "$JSIGN_JAR" "https://github.com/ebourg/jsign/releases/download/${JSIGN_VERSION}/jsign-${JSIGN_VERSION}.jar"
+        echo "${JSIGN_SHA256}  ${JSIGN_JAR}" | sha256sum --check --strict
+
+        JSIGN_STOREPASS=$(az account get-access-token --resource https://codesigning.azure.net --query accessToken --output tsv)
+        echo "::add-mask::${JSIGN_STOREPASS}"
+        export JSIGN_STOREPASS
+
+        # jsign expects the endpoint host, not the URL. Tolerate both the
+        # portal's display form (trailing slash) and the bare form.
+        KEYSTORE="${SIGNING_ENDPOINT#https://}"
+        KEYSTORE="${KEYSTORE%/}"
+
+        while IFS= read -r file; do
+          [ -z "$file" ] && continue
+          echo "Signing ${file}"
+          java -jar "$JSIGN_JAR" \
+            --storetype TRUSTEDSIGNING \
+            --keystore "$KEYSTORE" \
+            --storepass env:JSIGN_STOREPASS \
+            --alias "${SIGNING_ACCOUNT}/${SIGNING_PROFILE}" \
+            --alg SHA-256 \
+            --tsaurl http://timestamp.acs.microsoft.com \
+            --tsmode RFC3161 \
+            --replace \
+            "$file"
+        done <<< "$FILES"
+
+    - name: Verify signatures
+      if: steps.check.outputs.enabled == 'true'
+      shell: bash
+      env:
+        FILES: ${{ inputs.files }}
+        # Authenticode chains anchor to the Microsoft Identity Verification
+        # Root CA 2020, which is not in the Mozilla TLS bundle, so fetch it
+        # explicitly (pinned) for osslsigncode chain validation.
+        MS_ROOT_URL: "https://www.microsoft.com/pkiops/certs/Microsoft%20Identity%20Verification%20Root%20Certificate%20Authority%202020.crt"
+        MS_ROOT_SHA256: "5367f20c7ade0e2bca790915056d086b720c33c1fa2a2661acf787e3292e1270"
+      run: |
+        set -euo pipefail
+
+        if ! command -v osslsigncode >/dev/null; then
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq osslsigncode
+        fi
+
+        MS_ROOT_DER="${RUNNER_TEMP}/ms-identity-root-2020.crt"
+        MS_ROOT_PEM="${RUNNER_TEMP}/ms-identity-root-2020.pem"
+        curl -fsSL -o "$MS_ROOT_DER" "$MS_ROOT_URL"
+        echo "${MS_ROOT_SHA256}  ${MS_ROOT_DER}" | sha256sum --check --strict
+        openssl x509 -inform DER -in "$MS_ROOT_DER" -out "$MS_ROOT_PEM"
+
+        while IFS= read -r file; do
+          [ -z "$file" ] && continue
+          echo "Verifying signature on ${file}"
+          # Timestamp countersignature chain is checked separately by Windows;
+          # -ignore-timestamp only skips TSA chain validation here, not the
+          # Authenticode chain itself.
+          osslsigncode verify -in "$file" -CAfile "$MS_ROOT_PEM" -ignore-timestamp
+        done <<< "$FILES"

.github/workflows/cli-publish.yml

@@ -190,6 +190,19 @@ jobs:
             ls -lh "$dir/bin/"
           done
 
+      - name: Sign Windows binaries
+        uses: ./.github/actions/sign-windows-cli
+        with:
+          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          endpoint: ${{ secrets.AZURE_TRUSTED_SIGNING_ENDPOINT }}
+          account: ${{ secrets.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
+          certificate-profile: ${{ secrets.AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_CLI }}
+          files: |
+            apps/cli/dist/cli-windows-x64/bin/cline.exe
+            apps/cli/dist/cli-windows-arm64/bin/cline.exe
+
       - name: Publish to NPM with latest tag
         env:
           NPM_CONFIG_PROVENANCE: "true"
@@ -447,6 +460,20 @@ jobs:
             ls -lh "$dir/bin/"
           done
 
+      - name: Sign Windows binaries
+        if: steps.check_commits.outputs.skip != 'true'
+        uses: ./.github/actions/sign-windows-cli
+        with:
+          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          endpoint: ${{ secrets.AZURE_TRUSTED_SIGNING_ENDPOINT }}
+          account: ${{ secrets.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
+          certificate-profile: ${{ secrets.AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_CLI }}
+          files: |
+            apps/cli/dist/cli-windows-x64/bin/cline.exe
+            apps/cli/dist/cli-windows-arm64/bin/cline.exe
+
       - name: Publish to NPM with nightly tag
         if: steps.check_commits.outputs.skip != 'true'
         env:

.github/workflows/desktop-publish.yml

@@ -462,9 +462,282 @@ jobs:
           path: apps/examples/desktop-app/dist/publish/*
           if-no-files-found: error
 
+  build-windows:
+    name: Build Windows (x64)
+    needs: validate
+    # Same gate rationale as the macOS build job above. This job additionally
+    # needs id-token: write for Azure OIDC: Windows binaries are
+    # Authenticode-signed with Azure Trusted Signing, authenticated through the
+    # PublishDesktop-environment federated credential on the cline-cli-signing
+    # Entra app (subject repo:cline/cline:environment:PublishDesktop).
+    if: github.ref == 'refs/heads/main'
+    environment: PublishDesktop
+    runs-on: windows-latest
+    timeout-minutes: 90
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      # All-or-nothing: an unsigned Windows desktop build is never acceptable
+      # (Smart App Control / WDAC block unsigned exes and SmartScreen flags
+      # unsigned installers), and Tauri would skip updater-artifact signing
+      # silently if the updater key were missing. Unlike the CLI pipeline
+      # there is no unsigned fallback here.
+      - name: Verify signing secrets are present
+        shell: bash
+        env:
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+          AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+          AZURE_TRUSTED_SIGNING_ENDPOINT: ${{ secrets.AZURE_TRUSTED_SIGNING_ENDPOINT }}
+          AZURE_TRUSTED_SIGNING_ACCOUNT_NAME: ${{ secrets.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
+          AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_DESKTOP: ${{ secrets.AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_DESKTOP }}
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+        run: |
+          missing=()
+          for name in AZURE_CLIENT_ID AZURE_TENANT_ID AZURE_SUBSCRIPTION_ID \
+                      AZURE_TRUSTED_SIGNING_ENDPOINT AZURE_TRUSTED_SIGNING_ACCOUNT_NAME \
+                      AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_DESKTOP \
+                      TAURI_SIGNING_PRIVATE_KEY TAURI_SIGNING_PRIVATE_KEY_PASSWORD; do
+            [ -n "${!name}" ] || missing+=("$name")
+          done
+
+          if [ ${#missing[@]} -gt 0 ]; then
+            echo "Missing signing secrets for the Windows desktop build:"
+            printf '  - %s\n' "${missing[@]}"
+            echo
+            echo "The AZURE_* names are repository secrets; the TAURI_* names"
+            echo "live in the PublishDesktop environment. Refusing to build an"
+            echo "unsigned Windows desktop release."
+            exit 1
+          fi
+
+          echo "All Windows signing secrets are present."
+
+      # Every action in this job is SHA-pinned (unlike elsewhere in this
+      # file): they run with id-token: write and the updater signing key in
+      # scope, so a hijacked upstream tag must not be able to reach the
+      # signing identity or tamper with what gets signed and uploaded.
+      - name: Checkout code
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ needs.validate.outputs.tag }}
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: "1.3.13"
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable branch
+        with:
+          # With a SHA-pinned action the toolchain no longer comes from the
+          # ref name, so it must be set explicitly.
+          toolchain: stable
+
+      # No Rust build cache, mirroring the macOS job: this job holds the
+      # updater signing key and an Azure signing session, and a restored cache
+      # archive is attacker-controlled if the Actions cache is poisoned.
+
+      - name: Install dependencies
+        run: bun install
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build SDK packages
+        run: bun run build:sdk
+        env:
+          TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+          ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
+          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 }}
+
+      - name: Azure login (OIDC)
+        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5 # v2.3.0
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      # Tauri invokes signCommand once per staged binary (main exe, sidecar,
+      # NSIS uninstaller, and the installer itself). The overlay is generated
+      # here rather than committed because signCommand needs an absolute path
+      # to the signing script on this runner.
+      - name: Write signing config overlay
+        shell: bash
+        run: |
+          SCRIPT_PATH="${GITHUB_WORKSPACE//\\//}/apps/examples/desktop-app/scripts/tauri-sign-windows.ps1"
+          SIGN_CONF="${RUNNER_TEMP//\\//}/tauri-windows-sign.conf.json"
+          cat > "$SIGN_CONF" <<EOF
+          {
+            "\$schema": "https://schema.tauri.app/config/2",
+            "bundle": {
+              "windows": {
+                "signCommand": "pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File ${SCRIPT_PATH} %1"
+              }
+            }
+          }
+          EOF
+          cat "$SIGN_CONF"
+          echo "SIGN_CONF=${SIGN_CONF}" >> "$GITHUB_ENV"
+
+      - name: Build and sign desktop bundle
+        shell: bash
+        working-directory: apps/examples/desktop-app
+        # NSIS only: the MSI (WiX) target adds nothing for direct-download
+        # distribution and the updater uses the NSIS artifact. $CONFIG_ARGS is
+        # deliberately unquoted: it must word-split into separate flags.
+        run: bunx tauri build --bundles nsis $CONFIG_ARGS --config "$SIGN_CONF"
+        env:
+          CONFIG_ARGS: ${{ needs.validate.outputs.channel == 'beta' && '--config src-tauri/tauri.release.conf.json --config src-tauri/tauri.beta.conf.json' || '--config src-tauri/tauri.release.conf.json' }}
+          # Telemetry inlined into the sidecar at compile time, same as macOS.
+          TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+          ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
+          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 }}
+          # Authenticode signing via scripts/tauri-sign-windows.ps1 (jsign +
+          # Azure Trusted Signing; the token comes from the azure/login session)
+          AZURE_TRUSTED_SIGNING_ENDPOINT: ${{ secrets.AZURE_TRUSTED_SIGNING_ENDPOINT }}
+          AZURE_TRUSTED_SIGNING_ACCOUNT_NAME: ${{ secrets.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
+          AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE: ${{ secrets.AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_DESKTOP }}
+          # Updater artifact signing (minisign keypair, same key as macOS)
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+
+      # Same guardrail as the macOS job: assert the compiled binary embeds
+      # this channel's updater feed URL and not the other channel's. Checked
+      # on the unbundled main exe because NSIS compresses the installer
+      # contents, which defeats a string search on the installer itself.
+      - name: Verify updater feed endpoint
+        shell: bash
+        working-directory: apps/examples/desktop-app
+        env:
+          CHANNEL: ${{ needs.validate.outputs.channel }}
+        run: |
+          case "$CHANNEL" in
+            stable)
+              WANT="releases/download/desktop-latest/latest.json"
+              FORBID="releases/download/desktop-beta/latest.json"
+              ;;
+            beta)
+              WANT="releases/download/desktop-beta/latest.json"
+              FORBID="releases/download/desktop-latest/latest.json"
+              ;;
+            *)
+              echo "unknown channel: ${CHANNEL}"
+              exit 1
+              ;;
+          esac
+
+          found=0
+          for bin in src-tauri/target/release/*.exe; do
+            if grep -a "$FORBID" "$bin" >/dev/null; then
+              echo "$bin embeds the other channel's feed URL (${FORBID})"
+              exit 1
+            fi
+            if grep -a "$WANT" "$bin" >/dev/null; then
+              found=1
+            fi
+          done
+
+          if [ "$found" -ne 1 ]; then
+            echo "No exe in src-tauri/target/release embeds ${WANT}."
+            echo "The updater endpoint overlay did not apply; check the"
+            echo "--config flags on the build step and tauri.beta.conf.json."
+            exit 1
+          fi
+          echo "Updater endpoint verified: ${WANT}"
+
+      # Same guardrail as the macOS job, run natively on the Windows sidecar.
+      - name: Verify sidecar telemetry config was inlined
+        shell: bash
+        working-directory: apps/examples/desktop-app
+        run: |
+          SELFCHECK=$(./src-tauri/bin/code-sidecar-x86_64-pc-windows-msvc.exe --telemetry-selfcheck)
+          echo "$SELFCHECK"
+          if ! printf '%s' "$SELFCHECK" | grep -q '"enabled":true'; then
+            echo "Packaged sidecar reports telemetry disabled."
+            echo "Check the OTEL_* / TELEMETRY_SERVICE_API_KEY env on the"
+            echo "'Build and sign desktop bundle' step and the --define"
+            echo "inlining in scripts/build-sidecar-bin.ts."
+            exit 1
+          fi
+          if printf '%s' "$SELFCHECK" | grep -Eq '"otlp_endpoint_host":"(invalid-endpoint-url)?"'; then
+            echo "Packaged sidecar reports telemetry enabled but its OTLP"
+            echo "endpoint is missing, unparseable, or not an http(s) URL."
+            echo "Check the OTEL_EXPORTER_OTLP_ENDPOINT secret."
+            exit 1
+          fi
+
+      - name: Collect artifacts
+        shell: bash
+        working-directory: apps/examples/desktop-app
+        env:
+          VERSION: ${{ needs.validate.outputs.version }}
+          PRODUCT: ${{ needs.validate.outputs.product }}
+        run: |
+          BUNDLE_DIR="src-tauri/target/release/bundle"
+          OUT="dist/publish"
+          mkdir -p "$OUT"
+
+          # "Cline" -> Cline, "Cline Beta" -> Cline-Beta
+          PREFIX="${PRODUCT// /-}"
+
+          SETUP=$(find "$BUNDLE_DIR/nsis" -name '*-setup.exe' -print -quit)
+          if [ -z "$SETUP" ]; then
+            echo "no NSIS installer produced under $BUNDLE_DIR/nsis"
+            exit 1
+          fi
+          # The .sig is the updater (minisign) signature; without it the
+          # manifest generator cannot publish a windows-x86_64 entry.
+          if [ ! -f "${SETUP}.sig" ]; then
+            echo "updater signature missing next to $SETUP"
+            exit 1
+          fi
+          cp "$SETUP" "$OUT/${PREFIX}_${VERSION}_x64-setup.exe"
+          cp "${SETUP}.sig" "$OUT/${PREFIX}_${VERSION}_x64-setup.exe.sig"
+
+          ls -lh "$OUT"
+
+      # Independent Authenticode gate on the exact artifact users download.
+      # The signing script already verifies each file it signs, but this step
+      # would still catch an installer that skipped signCommand entirely.
+      - name: Verify Authenticode signatures
+        shell: pwsh
+        working-directory: apps/examples/desktop-app
+        run: |
+          # The Tauri bundler signs the sidecar in place, so check it here too;
+          # a WDAC-locked machine blocks the app at runtime if the sidecar it
+          # spawns is unsigned, even when the installer itself is fine.
+          $files = @(Get-ChildItem dist/publish/*.exe) + @(Get-Item src-tauri/bin/code-sidecar-x86_64-pc-windows-msvc.exe)
+          if ($files.Count -lt 2) { throw "expected at least the installer and the sidecar to verify" }
+          foreach ($file in $files) {
+            $sig = Get-AuthenticodeSignature $file.FullName
+            if ($sig.Status -ne "Valid") {
+              throw "Invalid Authenticode signature for $($file.Name): $($sig.Status) - $($sig.StatusMessage)"
+            }
+            Write-Host "$($file.Name): Valid ($($sig.SignerCertificate.Subject))"
+          }
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: desktop-windows-x64
+          path: apps/examples/desktop-app/dist/publish/*
+          if-no-files-found: error
+
   release:
     name: Create GitHub release
-    needs: [validate, build]
+    needs: [validate, build, build-windows]
     runs-on: ubuntu-latest
     permissions:
       contents: write

.github/workflows/desktop-test.yml

@@ -0,0 +1,50 @@
+name: desktop-test
+
+on:
+  push:
+    branches:
+      - main
+      - desktop-experimental
+    paths:
+      - "apps/examples/desktop-app/package.json"
+      - "apps/examples/desktop-app/scripts/dmg-background.ts"
+      - "apps/examples/desktop-app/scripts/dmg-background.test.ts"
+      - "apps/examples/desktop-app/src-tauri/dmg/background.png"
+      - "apps/examples/desktop-app/src-tauri/dmg/background@2x.png"
+      - ".github/workflows/desktop-test.yml"
+  pull_request:
+    branches:
+      - main
+      - desktop-experimental
+    paths:
+      - "apps/examples/desktop-app/package.json"
+      - "apps/examples/desktop-app/scripts/dmg-background.ts"
+      - "apps/examples/desktop-app/scripts/dmg-background.test.ts"
+      - "apps/examples/desktop-app/src-tauri/dmg/background.png"
+      - "apps/examples/desktop-app/src-tauri/dmg/background@2x.png"
+      - ".github/workflows/desktop-test.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  dmg-background:
+    name: Test DMG background tooling
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/examples/desktop-app
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.13"
+
+      # The suite only uses Bun/Node built-ins and committed artwork, so it does
+      # not need a workspace dependency install or macOS runner.
+      - name: Test DMG background tooling
+        run: bun run test:dmg-background

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

@@ -14,9 +14,12 @@ name: ext-vscode-publish-nightly
 # pre-release publishes.
 
 on:
-  schedule:
-    # Every day at 4:00 AM PST (12:00 UTC)
-    - cron: "0 12 * * *"
+  # Manual dispatch only. The nightly cron was removed deliberately: the
+  # PublishNightly environment gained required reviewers, and an unattended
+  # cron run would just sit `waiting` on that approval, hold this workflow's
+  # concurrency group, and silently cancel every later scheduled run behind it
+  # (that is exactly what happened between 2026-07-31 and 2026-08-21, killing
+  # 20 consecutive nightlies). Cut a nightly by dispatching this workflow.
   workflow_dispatch:
     inputs:
       legacy-ref:
@@ -74,8 +77,9 @@ jobs:
       - 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.
+          # NOTE: the || fallback is retained so this stays correct if a
+          # non-dispatch trigger is ever added back (inputs are empty strings
+          # on e.g. `schedule` events, where the declared default does not apply).
           ref: ${{ inputs.legacy-ref || 'legacy-extension' }}
           path: legacy-src
           lfs: true

.gitignore

@@ -88,6 +88,7 @@ apps/vscode/tsconfig.test.generated.json
 .next/dev/static
 **/src-tauri/target/debug/.fingerprint
 apps/examples/desktop-app/src-tauri/target
+apps/examples/desktop-app/src-tauri/dmg/background.gen.tiff
 apps/examples/desktop-app/webview/.next
 
 # Next.js generated type shim (churns between dev and build)

.greptile/rules.md

@@ -61,8 +61,9 @@ Emission ownership:
 
 - `user.extension_activated`: emitted **once per host process** by host-specific helpers
   (`captureCliExtensionActivated` for the CLI, `captureExtensionActivated` for VS Code).
-- `workspace.initialized` / `workspace.init_error`: emitted by a per-process de-duplicated
-  emitter in `prepareLocalRuntimeBootstrap`. Hosts must NOT re-emit these.
+- `workspace.initialized` / `workspace.init_error`: emitted by a de-duplicated emitter in
+  `prepareLocalRuntimeBootstrap`. A dedicated host emits once per workspace; a shared Hub emits
+  once per client surface and workspace. Hosts must NOT re-emit these.
 - `workspace.path_resolved`: emitted from default tool executors **only when**
   `WorkspaceManager` exposes more than one root.
 - `task.*`: emitted by core session lifecycle code in `sdk/packages/core/src/cline-core/` and
@@ -104,6 +105,19 @@ hub-backed session, so the daemon must own its own `ITelemetryService`. It build
 identifies from the cached cline account (re-resolved periodically, since the daemon often
 starts before login) and flushes on every shutdown path, including startup failure.
 
+The Hub transport forwards the serializable `ExtensionContext.client` and
+`ExtensionContext.user` values with session create/restore requests. The daemon wraps its
+process-owned service with `createClientScopedTelemetryService()` so lifecycle events use the
+originating client's `cline_type`, platform/version, and current account/organization without
+mutating the singleton shared by concurrent clients. Keep canonical task fields named
+`provider` and `model`; do not reintroduce host-specific aliases such as `apiProvider` or
+`modelId` for `task.created`, `task.restarted`, or `task.completed`.
+
+`UserContext.distinctId` may be an anonymous machine ID. Set `UserContext.accountId` to the
+authenticated account ID (or `null` for an explicitly signed-out client) whenever a client
+forwards user context; this prevents machine IDs and stale daemon identity from becoming
+`user_id` / `organization_id` on task events.
+
 Flag changes that remove this wiring, construct runtime hosts inside the daemon without
 passing its telemetry handle, or add daemon exit paths that skip the flush — hub-backed
 sessions would silently drop their lifecycle telemetry (this exact bug shipped once).

CHANGELOG.md

@@ -1,5 +1,132 @@
 # Changelog
 
+## [4.1.17]
+
+Everything here lands through the SDK bundle, so it applies to windows running that bundle.
+
+### Added
+
+- ClinePass is now surfaced across the app: a card on the account page describing what the plan covers, a hint in provider settings, and a banner on the home screen. Dismissed banners stay dismissed.
+
+### Fixed
+
+- Fixed the background Hub process ballooning in memory during long sessions. Session status updates broadcast a full copy of the conversation transcript to every connected client, so on a large task each status change shipped megabytes and could grow the process to tens of gigabytes. Snapshots now carry state only.
+- Hook scripts that fail to spawn no longer crash the extension's core process and take the running task down with them.
+- Fixed a chat render crash on malformed `api_req` payloads.
+- Cost estimates no longer appear in task history for subscription-billed tasks (ClinePass, ChatGPT via Codex, and Claude Code), matching the task header.
+- Pasted provider API keys are now stripped of the invisible characters clipboards smuggle in (newlines, zero-width spaces, BOM). A key corrupted that way was hidden by the masked field and rejected by the provider with a 401 indistinguishable from a genuinely wrong key. Credential rejections now say that the API key is the problem and point at its configuration, keeping the provider's raw response as a diagnostic tail.
+- Signing in to OpenAI Codex (ChatGPT subscription) now fails with a clear "port in use" error when callback port 1455 is occupied. Previously the button opened a browser to a flow whose callback could never arrive, and nothing else happened. OAuth redirect errors such as `access_denied` are surfaced instead of being reported as a missing authorization code.
+- A transient network failure while refreshing OpenAI Codex or OpenAI-compatible-account tokens no longer signs you out. Only a genuinely rejected refresh token now requires re-authentication.
+- Fixed tool calling being silently disabled for Dify, SAP AI Core, opencode, and Codex CLI models. Their catalog entries declare no capabilities, and the empty list was read as an authoritative denial that stripped every tool from the request.
+- Fixed images being dropped from file reads on models whose capability list is empty.
+- Restoring a checkpoint now refuses to run when commits were made after it, instead of silently knocking them off the branch where only the reflog could recover them. Chat-only restore is unaffected.
+- `apply_patch` now preserves a file's existing CRLF line endings.
+- Global rules are now also read from `~/Cline/Rules`, which is where the Rules tab writes them on WSL and headless installs whose Documents folder resolves to the home directory.
+- An enabled but unreachable remote (SSE or streamable HTTP) MCP server no longer stalls session startup; remote connects now have a 10 second budget.
+- Aborting a task now also cancels the delegated subagents and teammates it spawned, instead of leaving their work running.
+- Langfuse tracing now works in released builds. Detection identified the OpenTelemetry provider by class name, which minification renames, so tracing silently initialized as not ready in every published build while working in development.
+- Cline provider models are now read from the live catalog, so newly published models appear without an extension update.
+- Hook execution telemetry now fires; the task id was not threaded into hook runner creation, so those events were dropped.
+
+### Changed
+
+- Refreshed the built-in model catalog. Adds ten providers (Bothub, OpenReason, SenseNova (China), TokenGo, TokenRouter, Vancine, Volcengine Ark, Volcengine Ark Coding Plan, above.dev, and klokintegration.se) and updates model lists and pricing throughout. This is an unusually wide refresh: the resolved default model changes for 57 providers, most consequentially Anthropic, which now resolves to Claude Fable 5.1 instead of Claude Opus 5, with Amazon Bedrock, Vertex, OpenRouter, Vercel AI Gateway, Kilo Gateway, LLM Gateway, DevPass, DigitalOcean, CrossModel, Eden AI, and NanoGPT following. If you use a provider without pinning a model, expect a different default.
+- The message the model receives when you reject a tool call now names the rejected tool and reads as your decision rather than an error.
+
+## [4.1.16]
+
+Everything here lands through the SDK bundle, so it applies to windows running that bundle.
+
+### Fixed
+
+- Cost estimates are no longer shown for providers billed by a flat-rate subscription (ClinePass, ChatGPT via Codex, and Claude Code). The task header and model pricing rows rendered API-rate dollar figures that read as real charges on top of the subscription, including a flash of them on every chat-view mount while provider listings were loading.
+- Signing back in no longer moves your last-used provider off ClinePass on credential refresh.
+- Hooks now resolve their workspace from the VS Code window instead of shared global state in `~/.cline`. With a second window open on another project, a workspace's `.clinerules/hooks` scripts were never discovered, and hook cwd and the workspace paths passed to hook scripts resolved against whatever project some other or older Cline instance last recorded.
+- New files are now created with your platform's native line endings.
+- Fixed the codebase search tool crashing on files containing a single enormous line.
+- Credentials embedded in git remote URLs are now redacted from the workspace information sent to the model, which also now carries richer workspace metadata.
+- Installing an MCP server from the marketplace no longer misreads the catalog's `--` separator as part of the server command.
+- The hub's event log can no longer grow until it fills your disk.
+
+### Changed
+
+- The per-tool MCP auto-approve checkboxes are hidden. MCP auto-approval is governed solely by the global "Use MCP servers" toggle — the per-tool checkboxes were no-ops that implied granularity the approval path does not have.
+
+## [4.1.15]
+
+Everything here lands through the SDK bundle, so it applies to windows running that bundle.
+
+### Fixed
+
+- Auto-approve every MCP tool call while the "Use MCP servers" toggle is on. The toggle only took effect on tools that had also been opted in individually, so turning it on appeared to do nothing; it now governs all MCP tools on its own.
+
+## [4.1.14]
+
+Everything here lands through the SDK bundle, so it applies to windows running that bundle.
+
+### Added
+
+- Refresh the built-in model catalog. New entries include Claude Fable 5, Grok 4.6 on Vertex, several DeepSeek V4 Flash variants (including the vision preview), MiMo v2.5, Qwen3.8 27B, Gemma 4 26B, LongCat 2.0, Nemotron 3.5 Lightning, and Thinking Machines' Inkling models.
+
+### Fixed
+
+- Restore task completion telemetry for interactive sessions. A share of interactive stops routed through a teardown path that never reported completion after 4.1.11 changed how session status is tracked; every session now reports it exactly once.
+
+## [4.1.13]
+
+Everything here lands through the SDK bundle, so it applies to windows running that bundle.
+
+### Fixed
+
+- Restore tool calling for custom OpenAI-Compatible models whose capability list was inferred from convenience flags like `supportsReasoning`. The inferred list read as an authoritative denial and stripped every tool from the request; an explicitly authored capability list still decides.
+- Keep Hub-backed sessions intact across a Hub restart or upgrade. Clients replay the events they missed while disconnected, and the same event is no longer delivered twice when the replay and live streams overlap.
+- Carry session and client identity into Langfuse traces for Hub-backed and delegated-agent runs, which previously arrived without their session grouping or client version.
+
+## [4.1.12]
+
+Everything here lands through the SDK bundle, so it applies to windows running that bundle.
+
+### Fixed
+
+- Enforce enterprise MCP controls on the Customize marketplace. MCP entries are now hidden when remote config disables the marketplace, and limited to `allowedMCPServers` when an allowlist is configured.
+- Restore tool calling for custom OpenAI-Compatible models whose stored capability list was empty.
+
+## [4.1.11]
+
+Everything here lands through the SDK bundle, so it applies to windows running that bundle — except the last section, which is a legacy-bundle fix.
+
+### Added
+
+- Let models that support it generate images during a task. Generated images render inline in the conversation.
+
+### Fixed
+
+- Fix code actions failing with "command not found" on VS Code 1.134.
+- Fix `@` file mentions breaking on paths that contain spaces.
+- Show the diff edit view for multi-line edits in files with CRLF line endings.
+- Continue the surviving session when resuming a task, instead of rebuilding it from the original task text.
+- Clear the task-scoped settings overlay when the task view is cleared or switched, so one task's overrides no longer leak into the next.
+- Honor the classic truncation range when migrating legacy tasks.
+- Preserve LiteLLM input token limits instead of overwriting them with catalog values.
+- Restore custom base URLs for Gemini, and normalize legacy host-root values so they keep working.
+- Point provider signup links at each provider's API key page instead of a generic landing page.
+- Load skill slash commands through the skills tool instead of pasting their instructions into your message, which previously delivered them twice.
+- Stop offering image, voice, and other non-chat models in chat model pickers.
+- Deliver a `PreToolUse` hook's `contextModification` to the model again, and wait for `PostToolUse` hooks so their output and `cancel` control are honored.
+- Show tool activity a provider runs itself — every tool the Claude Code provider executes inside its own session — instead of dropping it from the conversation.
+- Fix `run_commands` failing with ENOENT when a structured command carried a full command line with no arguments.
+- Run PowerShell commands fail-fast, so a pipeline erroring per item stops at the first error instead of flooding output and still reporting success.
+- Keep remote configuration in step with the SDK: coordinated refreshes, session gating, and a fail-closed opt-out.
+
+### Changed
+
+- Show the billed cost for Cline gateway usage.
+- Refresh the model catalog, which adds AMD, Arcee, Echo, Jalapeno, Kosmik, LLM Gateway, RunInfra, and SCNet as providers and updates model lists, pricing, and per-provider default models across the board.
+
+### Fixed (legacy bundle)
+
+- Only treat an Anthropic `invalid_request_error` as a context-overflow when its message says so. An unrelated invalid request (bad tool schema, oversized image, unknown model id) no longer triggers context-overflow recovery.
+
 ## [4.1.10]
 
 Everything in this release lands through the SDK bundle, so it applies to windows running that bundle and not the legacy one. The legacy bundle is unchanged from 4.1.9.

README.md

@@ -5,7 +5,7 @@
 <h1 align="center">Cline</h1>
 
 <p align="center">
-The open source coding agent in your IDE and terminal.
+The open source coding agent in your IDE, terminal, and desktop.
 </p>
 
 <div align="center">
@@ -57,17 +57,13 @@ npm i -g cline
 </td>
 <td align="center" width="50%">
 
-### Kanban
+### Desktop App
 
-Run many agents in parallel from a
-web-based task board. Each card gets its own
-worktree, auto-commit, and dependency chains.
+Cline as a native app for macOS and Windows.
+Run agent sessions in any folder, schedule
+routines, and manage models, plugins, and MCP servers.
 
-```
-npm i -g kanban
-```
-
-<a href="https://github.com/cline/kanban">Learn more</a>
+<a href="https://github.com/cline/cline/releases?q=desktop-v&expanded=true">Download for macOS and Windows</a>
 <br><br>
 
 </td>
@@ -108,7 +104,7 @@ the JetBrains family.
 
 ### SDK
 
-Build your own AI agents and integrations powered by the same engine that runs the CLI, Kanban, VS Code extension, and JetBrains plugin. Custom tools, multi-agent teams, connectors, scheduled automations, and more.
+Build your own AI agents and integrations powered by the same engine that runs the CLI, desktop app, VS Code extension, and JetBrains plugin. Custom tools, multi-agent teams, connectors, scheduled automations, and more.
 
 ```
 npm install @cline/sdk
@@ -131,8 +127,8 @@ npm install @cline/sdk
 | **SDK** | Node.js programmatic agent API and extension exports. | [`sdk/`](https://github.com/cline/cline/tree/main/sdk) | [CHANGELOG.md](https://github.com/cline/cline/blob/main/sdk/CHANGELOG.md) |
 | **CLI** | Terminal UI, headless mode, shell commands, and CLI-specific flows. | [`apps/cli/`](https://github.com/cline/cline/tree/main/apps/cli) | [CHANGELOG.md](https://github.com/cline/cline/blob/main/apps/cli/CHANGELOG.md) |
 | **VS Code Extension** | The Marketplace extension and extension host integration. | [`/`](https://github.com/cline/cline/tree/main) (WIP migrating) | [CHANGELOG.md](https://github.com/cline/cline/blob/main/CHANGELOG.md) |
+| **Desktop App** | Native macOS and Windows app (Tauri shell, Bun sidecar, Next.js UI). | [`apps/examples/desktop-app/`](https://github.com/cline/cline/tree/main/apps/examples/desktop-app) | [CHANGELOG.md](https://github.com/cline/cline/blob/main/apps/examples/desktop-app/CHANGELOG.md) |
 | **JetBrains Plugin** | JetBrains-hosted client that talks to the shared agent core. | Currently we are not open-sourcing JetBrains plugins | - |
-| **Kanban** | Web-based multi-agent task board. | [`cline/kanban`](https://github.com/cline/kanban) | [CHANGELOG.md](https://github.com/cline/kanban/blob/main/CHANGELOG.md) |
 | **Docs site** | Public documentation pages. | [`docs/`](https://docs.cline.bot/) | - |
 
 ## Edits Code Across Your Project

apps/cli/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Cline CLI Changelog
 
+## 3.0.61
+
+- Cline now handles a running Hub that is older than your CLI. Instead of quietly talking to a hub executing stale code, you get a prompt showing how many active sessions a replacement would interrupt, with enter-to-replace or escape-to-keep. The replacement drains the Hub first so in-flight turns finish, and a hub too old or wedged to accept the drain is left alone rather than killed
+- Windows binaries are now Authenticode-signed via Azure Trusted Signing, and a launch blocked by application-control policy now prints an actionable error instead of failing bare
+- Fixed the CLI dying when an enabled remote (SSE/streamable HTTP) MCP server is unreachable. The connect now has a 10s budget, so an offline server no longer stalls session startup past the Hub's deadline and tears the session down — previously the interactive TUI exited and one-shot runs failed
+- Fixed tool calling being silently disabled for Dify, SAP AI Core, opencode, and Codex CLI models. Their catalog entries declare no capabilities, and the empty list was read as an authoritative denial that stripped every tool from the request
+- Fixed images being dropped from file reads on models whose capability list is empty
+- Langfuse tracing now works in released builds. Detection identified the OpenTelemetry provider by class name, which minification renames, so tracing silently initialized as not-ready in every published binary while working in dev
+- Restoring a checkpoint now refuses to run when you have made commits after it, instead of silently knocking them off the branch where only the reflog could recover them. Chat-only restore is unaffected
+- `apply_patch` now preserves a file's existing CRLF line endings
+- Global rules are now also read from `~/Cline/Rules`, which is where the VS Code Rules tab writes them on WSL and headless installs
+- Signing in to OpenAI Codex (ChatGPT subscription) now fails with a clear "port in use" error when 1455 is occupied, instead of opening a browser to a flow that can never complete
+- A transient network failure while refreshing Codex or OpenAI-compatible-account tokens no longer logs you out
+- Aborting a session now also cancels the delegated subagents and teammates it spawned, instead of leaving their work running
+- Agent-created schedules now live in `~/.cline/schedules` instead of inheriting whichever chat folder they were created in. Schedules you create with `--workspace` are unchanged
+- Fixed scheduled tasks disappearing after a hub restart
+- Fixed markdown flashing as it settled at the end of a streamed response
+- The message the model sees when you reject a tool call now names the tool and reads as your decision rather than an error
+- Cline provider models now come from the live catalog, so newly published models show up without a CLI update
+- Refreshed the model catalog. Adds ten providers (Bothub, OpenReason, SenseNova (China), TokenGo, TokenRouter, Vancine, Volcengine Ark, Volcengine Ark Coding Plan, above.dev, and klokintegration.se) and updates model lists and pricing across providers. This is an unusually wide refresh: the resolved default model changes for 57 providers. Most consequentially, Anthropic now resolves to Claude Fable 5.1 instead of Claude Opus 5, and Amazon Bedrock, Vertex, OpenRouter, Vercel AI Gateway, Kilo Gateway, LLM Gateway, DevPass, DigitalOcean, CrossModel, Eden AI, and NanoGPT follow it to Fable 5.1. If you use any provider without pinning a model, expect a different default
+
+## 3.0.60
+
+- The config screen now separates Cline Plugins from Agent Plugins discovered by the Hub. Agent Plugins can be enabled or disabled with Space; the Hub persists the state and their skills and MCP servers follow it when the interactive runtime is rebuilt
+- Fixed the background hub process ballooning in memory during long sessions — session status updates were broadcasting a full copy of the conversation transcript to every connected client, which on a large task could grow the process to tens of gigabytes. Upgrading retires the running hub so the fix takes effect on the next command
+- New files are now created with your platform's native line endings
+- Fixed the codebase search tool crashing on files that contain a single enormous line
+- Cost estimates are no longer shown for Claude Code. Its usage is typically covered by a Claude Pro/Max subscription, but its models reuse Anthropic API pricing, so Cline was showing charges you were not being billed
+- Credentials embedded in git remote URLs are now redacted from the workspace information sent to the model
+- Installing an MCP server no longer misreads a `--` separator in the install arguments as part of the server command
+- Refreshed the model catalog. Adds seven providers (Agnes AI, Aixy, IteraCompute, LLM Tech, NeoSmith, Pendra, and Standard Compute) and updates model lists and pricing across providers. The resolved default model changes for ClinePass (now GLM 5.3), Z.ai, Hugging Face, evroc, LLM Gateway, NanoGPT, and Weights & Biases, so if you use one of those without pinning a model you will get a different default
+
+## 3.0.58
+
+- The first-launch "Try ClinePass" dialog no longer advertises the $4.99 first-month promo, which is ending
+- The hub's event log is now capped at 64 MiB on disk. Events carrying full session snapshots could previously grow the log to tens of gigabytes on a long-running hub, since deleting rows never shrinks the file. Oldest events are dropped first and the space is returned, and pruning runs on volume as well as on a timer
+- Refreshed the model catalog. Adds two providers (AgentRouter and Opper) and updates model lists and pricing across providers. The resolved default model changes for Aki.io and NanoGPT, so if you use one of those without pinning a model you will get a different default
+
+## 3.0.57
+
+- Added `cline hub drain`, which stops a hub from accepting new mutating work while it finishes what it is already running, and `cline hub drain --off` to lift it
+- Added `cline hub upgrade`, which drains the hub, waits for it to go idle, stops it, and starts a fresh one on the current build. An aborted upgrade lifts the drain again, so the hub is never left refusing work
+- Sessions now survive a hub restart. A reconnecting client replays the events it missed while disconnected, deduped by event id so nothing is delivered twice
+- Fixed tool calling being silently disabled for custom OpenAI-Compatible models whose capability list was inferred from convenience flags like `supportsReasoning`. The inferred list read as an authoritative denial and stripped every tool from the request
+- Langfuse traces now carry session and client identity for hub-backed and delegated-agent runs, instead of arriving without their session grouping or client version
+- Refreshed the model catalog, which updates model lists and pricing across providers and changes the resolved default model for several of them (DeepSeek, Crof, CrossModel, Eden AI, Kilo, and NanoGPT)
+
 ## 3.0.56
 
 - Models that support image generation can now produce media during a turn. The TUI saves each generated file to a temporary path and prints it so you can open it with your usual tools, HTML session exports embed images inline, and ACP clients receive generated images as image content

apps/cli/DISTRIBUTION.md

@@ -270,6 +270,9 @@ The postinstall script runs in diverse environments (CI, Docker, restricted perm
 ### Windows
 Windows binaries are `.exe` files. The build script appends `.exe` to the output filename on Windows targets. The resolver handles this. npm on Windows generates `.cmd` shims for bin entries automatically.
 
+### Windows code signing
+Windows application control (Smart App Control, WDAC, AppLocker) blocks unsigned executables at launch, regardless of how they were installed — npm distribution gets no exemption ([#12934](https://github.com/cline/cline/issues/12934)). The publish workflow Authenticode-signs `cli-windows-x64/bin/cline.exe` and `cli-windows-arm64/bin/cline.exe` with Azure Trusted Signing before publishing, via the `.github/actions/sign-windows-cli` composite action. Signing runs on the Linux publish runner using [jsign](https://ebourg.github.io/jsign/) (`--storetype TRUSTEDSIGNING`) with an OIDC-federated Entra app, then verifies the signature chain with `osslsigncode` against the Microsoft Identity Verification Root CA 2020. If all `AZURE_*` / `AZURE_TRUSTED_SIGNING_*` repository secrets are absent, the action logs a warning and the release ships unsigned rather than failing; if only some resolve (a typo'd or renamed secret), the release fails loudly instead. The certificate profile secret is suffixed `_CLI` because the desktop app will later get its own profile; the other five secrets are shared. Note that signing bun-compiled executables requires Bun >= 1.2.23 (earlier versions located the embedded bundle relative to the end of the file, which signing corrupts).
+
 ### File permissions
 Compiled binaries need to be executable (`chmod 755`). The build script sets this after copying. The postinstall also sets permissions on the cached binary. Some npm packaging steps can strip permissions, so both handle this defensively.
 

apps/cli/bin/cline

@@ -72,6 +72,29 @@ function run(target) {
 	});
 	if (result.error) {
 		console.error(result.error.message);
+		// Windows application control (Smart App Control, WDAC, AppLocker)
+		// blocks the child exe at launch, which Node surfaces only as an
+		// opaque "spawnSync ... UNKNOWN" error. Point users at the real cause.
+		const code = result.error.code;
+		if (
+			os.platform() === "win32" &&
+			(code === "UNKNOWN" || code === "EACCES" || code === "EPERM")
+		) {
+			console.error(
+				"\nWindows refused to start the Cline binary:\n  " +
+					target +
+					"\n\n" +
+					"This usually means an application control policy (Smart App Control,\n" +
+					"WDAC, or AppLocker) or antivirus blocked the executable. To confirm,\n" +
+					"run the path above directly in a terminal and check the error Windows\n" +
+					"reports, or inspect its signature with:\n\n" +
+					'  Get-AuthenticodeSignature "' +
+					target +
+					'"\n\n' +
+					"If it was blocked by policy, allow the file or ask your administrator\n" +
+					"to trust it. See https://github.com/cline/cline/issues for known issues.",
+			);
+		}
 		process.exit(1);
 	}
 	if (typeof result.status === "number") {

apps/cli/package.json

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

apps/cli/src/commands/config.ts

@@ -19,6 +19,7 @@ import {
 import { readFileSyncStrippingUtf8Bom } from "@cline/shared/node";
 import { Command } from "commander";
 import { getToolCatalog } from "../runtime/tools";
+import { createCliCore } from "../session/session";
 import { loadInteractiveConfigData } from "../tui/interactive-config";
 import type { CliOutputMode } from "../utils/types";
 
@@ -423,8 +424,20 @@ async function loadInteractiveConfigDataForCommand(
 	cwd: string,
 ): Promise<Awaited<ReturnType<typeof loadInteractiveConfigData>>> {
 	const userInstructionService = createConfigUserInstructionService(cwd);
+	const core = await createCliCore({
+		backendMode: "auto",
+		cwd,
+		workspaceRoot: cwd,
+	});
 	try {
-		await userInstructionService.start();
+		const [, agentPluginSettings] = await Promise.all([
+			userInstructionService.start(),
+			core.settings.list({
+				cwd,
+				workspaceRoot: cwd,
+				includePluginTools: true,
+			}),
+		]);
 		return await loadInteractiveConfigData({
 			userInstructionService,
 			cwd,
@@ -432,9 +445,11 @@ async function loadInteractiveConfigDataForCommand(
 			availabilityContext: {
 				mode: "act",
 			},
+			agentPluginSettings,
 		});
 	} finally {
 		userInstructionService.stop();
+		await core.dispose("cli_config_command_complete");
 	}
 }
 

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

@@ -3,16 +3,20 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 const {
 	mockClearHubDiscovery,
 	mockEnsureDetachedHubServer,
+	mockLocalHubHasNoActiveSessions,
 	mockProbeHubServer,
 	mockReadHubDiscovery,
+	mockRequestHubDrain,
 	mockResolveProductionHubOwnerContext,
 	mockResolveSharedHubOwnerContext,
 	mockStopLocalHubServerGracefully,
 } = vi.hoisted(() => ({
 	mockClearHubDiscovery: vi.fn(),
 	mockEnsureDetachedHubServer: vi.fn(),
+	mockLocalHubHasNoActiveSessions: vi.fn(),
 	mockProbeHubServer: vi.fn(),
 	mockReadHubDiscovery: vi.fn(),
+	mockRequestHubDrain: vi.fn(),
 	mockResolveProductionHubOwnerContext: vi.fn(() => ({
 		ownerId: "hub-production",
 		discoveryPath: "/tmp/cline-data/locks/hub/production.json",
@@ -27,8 +31,10 @@ const {
 vi.mock("@cline/core", () => ({
 	clearHubDiscovery: mockClearHubDiscovery,
 	ensureDetachedHubServer: mockEnsureDetachedHubServer,
+	localHubHasNoActiveSessions: mockLocalHubHasNoActiveSessions,
 	probeHubServer: mockProbeHubServer,
 	readHubDiscovery: mockReadHubDiscovery,
+	requestHubDrain: mockRequestHubDrain,
 	resolveProductionHubOwnerContext: mockResolveProductionHubOwnerContext,
 	resolveSharedHubOwnerContext: mockResolveSharedHubOwnerContext,
 	stopLocalHubServerGracefully: mockStopLocalHubServerGracefully,
@@ -95,6 +101,147 @@ describe("createHubCommand", () => {
 		});
 	});
 
+	function createCommand() {
+		const output: string[] = [];
+		const errors: string[] = [];
+		let exitCode = 0;
+		const cmd = createHubCommand(
+			{
+				writeln: (text) => {
+					output.push(text ?? "");
+				},
+				writeErr: (text) => {
+					errors.push(text);
+				},
+			},
+			(code) => {
+				exitCode = code;
+			},
+		);
+		return {
+			cmd,
+			output,
+			errors,
+			exitCode: () => exitCode,
+		};
+	}
+
+	it("sends an un-drain request with drain --off", async () => {
+		mockReadHubDiscovery.mockResolvedValue({
+			url: "ws://127.0.0.1:25463/hub",
+			authToken: "token",
+		});
+		mockRequestHubDrain.mockResolvedValue(true);
+
+		const { cmd, output, exitCode } = createCommand();
+		await cmd.parseAsync(["drain", "--off"], { from: "user" });
+
+		expect(exitCode()).toBe(0);
+		expect(mockRequestHubDrain).toHaveBeenCalledWith(
+			"ws://127.0.0.1:25463/hub",
+			"token",
+			"cline hub drain --off",
+			{ off: true },
+		);
+		expect(JSON.parse(output[0] || "")).toEqual({
+			draining: false,
+			url: "ws://127.0.0.1:25463/hub",
+		});
+	});
+
+	it("drains without the off flag by default", async () => {
+		mockReadHubDiscovery.mockResolvedValue({
+			url: "ws://127.0.0.1:25463/hub",
+			authToken: "token",
+		});
+		mockRequestHubDrain.mockResolvedValue(true);
+
+		const { cmd, output, exitCode } = createCommand();
+		await cmd.parseAsync(["drain"], { from: "user" });
+
+		expect(exitCode()).toBe(0);
+		expect(mockRequestHubDrain).toHaveBeenCalledWith(
+			"ws://127.0.0.1:25463/hub",
+			"token",
+			"cline hub drain",
+			{ off: false },
+		);
+		expect(JSON.parse(output[0] || "")).toEqual({
+			draining: true,
+			url: "ws://127.0.0.1:25463/hub",
+		});
+	});
+
+	it("replaces an idle hub with upgrade --wait 0 instead of skipping the idle check", async () => {
+		mockReadHubDiscovery.mockResolvedValue({
+			url: "ws://127.0.0.1:25463/hub",
+			authToken: "token",
+		});
+		mockRequestHubDrain.mockResolvedValue(true);
+		mockLocalHubHasNoActiveSessions.mockResolvedValue(true);
+		mockStopLocalHubServerGracefully.mockResolvedValue(true);
+		mockEnsureDetachedHubServer.mockResolvedValue({
+			url: "ws://127.0.0.1:25463/hub",
+			authToken: "new-token",
+		});
+
+		const { cmd, output, errors, exitCode } = createCommand();
+		await cmd.parseAsync(["upgrade", "--wait", "0"], { from: "user" });
+
+		expect(errors).toEqual([]);
+		expect(exitCode()).toBe(0);
+		expect(mockLocalHubHasNoActiveSessions).toHaveBeenCalled();
+		expect(mockStopLocalHubServerGracefully).toHaveBeenCalled();
+		expect(mockEnsureDetachedHubServer).toHaveBeenCalled();
+		// The drain was never lifted manually: the drained hub was replaced.
+		expect(mockRequestHubDrain).toHaveBeenCalledTimes(1);
+		expect(JSON.parse(output[0] || "")).toEqual({
+			upgraded: true,
+			url: "ws://127.0.0.1:25463/hub",
+		});
+	});
+
+	it("un-drains the hub when upgrade aborts because sessions are still active", async () => {
+		mockReadHubDiscovery.mockResolvedValue({
+			url: "ws://127.0.0.1:25463/hub",
+			authToken: "token",
+		});
+		mockRequestHubDrain.mockResolvedValue(true);
+		mockLocalHubHasNoActiveSessions.mockResolvedValue(false);
+
+		const { cmd, errors, exitCode } = createCommand();
+		await cmd.parseAsync(["upgrade", "--wait", "0"], { from: "user" });
+
+		expect(exitCode()).toBe(1);
+		expect(errors[0]).toContain("still serving sessions");
+		expect(mockStopLocalHubServerGracefully).not.toHaveBeenCalled();
+		expect(mockEnsureDetachedHubServer).not.toHaveBeenCalled();
+		expect(mockRequestHubDrain).toHaveBeenCalledTimes(2);
+		expect(mockRequestHubDrain).toHaveBeenLastCalledWith(
+			"ws://127.0.0.1:25463/hub",
+			"token",
+			"cline hub upgrade aborted",
+			{ off: true },
+		);
+	});
+
+	it("rejects a non-numeric upgrade --wait instead of treating it as an expired deadline", async () => {
+		mockReadHubDiscovery.mockResolvedValue({
+			url: "ws://127.0.0.1:25463/hub",
+			authToken: "token",
+		});
+
+		const { cmd } = createCommand();
+		cmd.configureOutput({ writeErr: () => {} });
+		for (const sub of cmd.commands) {
+			sub.configureOutput({ writeErr: () => {} });
+		}
+		await expect(
+			cmd.parseAsync(["upgrade", "--wait", "soon"], { from: "user" }),
+		).rejects.toThrow("--wait requires a non-negative number of seconds.");
+		expect(mockRequestHubDrain).not.toHaveBeenCalled();
+	});
+
 	it("passes the selected owner to graceful stop", async () => {
 		process.env.CLINE_BUILD_ENV = "development";
 		mockReadHubDiscovery.mockResolvedValue({

apps/cli/src/commands/hub.ts

@@ -1,14 +1,16 @@
 import {
 	clearHubDiscovery,
 	ensureDetachedHubServer,
+	localHubHasNoActiveSessions,
 	probeHubServer,
 	readHubDiscovery,
+	requestHubDrain,
 	resolveProductionHubOwnerContext,
 	resolveSharedHubOwnerContext,
 	stopLocalHubServerGracefully,
 } from "@cline/core";
 import { formatUptime, resolveClineBuildEnv } from "@cline/shared";
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 import { version as cliVersion } from "../../package.json";
 
 interface HubCommandIo {
@@ -54,6 +56,16 @@ function resolveCliHubOwnerContext() {
 		: resolveSharedHubOwnerContext();
 }
 
+function parseWaitSeconds(value: string): number {
+	const parsed = Number.parseInt(value, 10);
+	if (Number.isNaN(parsed) || parsed < 0) {
+		throw new InvalidArgumentError(
+			"--wait requires a non-negative number of seconds.",
+		);
+	}
+	return parsed;
+}
+
 export function createHubCommand(
 	io: HubCommandIo,
 	setExitCode: (code: number) => void,
@@ -150,5 +162,117 @@ export function createHubCommand(
 		}),
 	);
 
+	hub
+		.command("drain")
+		.description("Refuse new mutating work while accepted runs finish")
+		.option("--reason <text>", "Why the hub is draining")
+		.option("--off", "Lift the drain and accept new mutating work again")
+		.action(
+			action(async (cmdOptions: { reason?: string; off?: boolean }) => {
+				const owner = resolveCliHubOwnerContext();
+				const discovery = await readHubDiscovery(owner.discoveryPath);
+				if (!discovery?.url) {
+					io.writeErr("No hub is running.");
+					fail();
+					return;
+				}
+				const draining = cmdOptions.off !== true;
+				const ok = await requestHubDrain(
+					discovery.url,
+					discovery.authToken,
+					cmdOptions.reason ??
+						(draining ? "cline hub drain" : "cline hub drain --off"),
+					{ off: !draining },
+				);
+				if (!ok) {
+					io.writeErr(
+						draining
+							? "Hub drain request failed."
+							: "Hub un-drain request failed.",
+					);
+					fail();
+					return;
+				}
+				io.writeln(JSON.stringify({ draining, url: discovery.url }));
+			}),
+		);
+
+	hub
+		.command("upgrade")
+		.description(
+			"Drain, wait for the hub to go idle, stop it, and start a fresh one",
+		)
+		.option(
+			"--wait <seconds>",
+			"How long to wait for the hub to go idle",
+			parseWaitSeconds,
+			120,
+		)
+		.action(
+			action(async (cmdOptions: { wait: number }) => {
+				const opts = hub.opts<{
+					cwd: string;
+					host?: string;
+					port?: number;
+					pathname?: string;
+				}>();
+				const owner = resolveCliHubOwnerContext();
+				const discovery = await readHubDiscovery(owner.discoveryPath);
+				if (discovery?.url) {
+					const drained = await requestHubDrain(
+						discovery.url,
+						discovery.authToken,
+						"cline hub upgrade",
+					).catch(() => false);
+					// An aborted upgrade must hand the hub back: leaving it
+					// draining refuses all new mutating work until a restart.
+					const undrain = async (): Promise<void> => {
+						if (!drained) {
+							return;
+						}
+						await requestHubDrain(
+							discovery.url,
+							discovery.authToken,
+							"cline hub upgrade aborted",
+							{ off: true },
+						).catch(() => false);
+					};
+					try {
+						const deadline = Date.now() + cmdOptions.wait * 1_000;
+						let idle = false;
+						// Check at least once so --wait 0 still observes an idle hub.
+						for (;;) {
+							idle = await localHubHasNoActiveSessions(
+								discovery.url,
+								discovery.authToken,
+							).catch(() => true);
+							if (idle || Date.now() >= deadline) {
+								break;
+							}
+							await new Promise((resolve) => setTimeout(resolve, 1_000));
+						}
+						if (!idle) {
+							await undrain();
+							io.writeErr(
+								"Hub is still serving sessions after the wait window; not replacing it. Re-run with a longer --wait, or finish the sessions first.",
+							);
+							fail();
+							return;
+						}
+						await stopHubServer(opts.cwd);
+					} catch (error) {
+						await undrain();
+						throw error;
+					}
+				}
+				const { url } = await ensureDetachedHubServer(opts.cwd, {
+					host: opts.host,
+					port: opts.port,
+					pathname: opts.pathname,
+				});
+				io.writeln(JSON.stringify({ upgraded: true, url }));
+			}),
+		);
+
 	return hub;
 }

apps/cli/src/connectors/adapters/discord.ts

@@ -2,7 +2,8 @@ import {
 	createDiscordAdapter,
 	type DiscordAdapter,
 } from "@chat-adapter/discord";
-// TODO: Remove the root Undici 6 override when discord.js no longer requires Undici ^6.27.0.
+// Note: discord.js@14 declares undici ^6.27.0, but the root package.json
+// override ("undici": ">=7.29.0 <8") forces undici 7.x for CVE-2026-1525.
 import type { ChatStartSessionRequest } from "@cline/core";
 import {
 	createUserInstructionConfigService,

apps/cli/src/kanban-migration/notice-dialog.tsx

@@ -71,7 +71,6 @@ export function MigrationNoticeContent(
 					latest open-weight coding models with enough quota for day-to-day
 					work, at a much lower cost than paying API costs directly.
 				</text>
-				<text selectable>Try it now with a limited-time promo for $4.99.</text>
 			</box>
 			<box flexDirection="row">
 				<text fg={palette.act} selectable>

apps/cli/src/runtime/interactive/config-data.test.ts

@@ -17,6 +17,7 @@ import {
 import {
 	applyPluginFailures,
 	type InteractiveConfigItem,
+	isToggleableInteractiveConfigItem,
 } from "../../tui/interactive-config";
 import type { Config } from "../../utils/types";
 import { createInteractiveConfigDataLoader } from "./config-data";
@@ -113,6 +114,172 @@ describe("interactive config data loader", () => {
 		return pluginPath;
 	}
 
+	it("merges the hub-owned Agent Plugin inventory into the config view", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "cli-config-agent-plugin-"));
+		tempRoots.push(tempRoot);
+		const pluginRoot = "/remote/home/.agents/plugins/portable-review";
+		const calls: unknown[] = [];
+		const loader = createInteractiveConfigDataLoader({
+			config: createConfig(tempRoot),
+			loadCoreSettings: async (input) => {
+				calls.push(input);
+				return {
+					workflows: [],
+					rules: [],
+					tools: [],
+					plugins: [
+						{
+							id: "agent-plugin:portable-review",
+							name: "portable-review",
+							path: pluginRoot,
+							kind: "plugin",
+							source: "global-plugin",
+							enabled: true,
+							toggleable: true,
+							agentPlugin: true,
+						},
+					],
+					skills: [
+						{
+							id: "portable-review:review",
+							name: "review",
+							path: `${pluginRoot}/skills/review/SKILL.md`,
+							kind: "skill",
+							source: "global-plugin",
+							enabled: true,
+							toggleable: false,
+							agentPlugin: true,
+							pluginName: "portable-review",
+							pluginPath: pluginRoot,
+						},
+					],
+					mcp: [
+						{
+							id: "portable-review.docs",
+							name: "portable-review.docs",
+							path: `${pluginRoot}/mcp.json`,
+							kind: "mcp",
+							source: "global-plugin",
+							enabled: true,
+							toggleable: false,
+							agentPlugin: true,
+							pluginName: "portable-review",
+							pluginPath: pluginRoot,
+						},
+					],
+				};
+			},
+		});
+
+		const data = await loader.loadConfigData({ includePluginTools: false });
+
+		expect(calls).toEqual([
+			expect.objectContaining({
+				includePluginTools: false,
+			}),
+		]);
+		expect(data.plugins).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					name: "portable-review",
+					agentPlugin: true,
+					toggleable: true,
+					deletable: false,
+				}),
+			]),
+		);
+		const skill = data.skills.find(
+			(item) => item.id === "portable-review:review",
+		);
+		expect(skill).toMatchObject({
+			pluginName: "portable-review",
+			agentPlugin: true,
+		});
+		expect(skill && isToggleableInteractiveConfigItem(skill)).toBe(false);
+		expect(data.mcp).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({ id: "portable-review.docs" }),
+			]),
+		);
+	});
+
+	it("toggles Agent Plugins through the hub without mutating client settings", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "cli-config-agent-toggle-"));
+		tempRoots.push(tempRoot);
+		const globalSettingsPath = join(tempRoot, "global-settings.json");
+		process.env.CLINE_GLOBAL_SETTINGS_PATH = globalSettingsPath;
+		const pluginRoot = "/hub/home/.agents/plugins/portable-review";
+		const toggleCalls: unknown[] = [];
+		const loader = createInteractiveConfigDataLoader({
+			config: {
+				...createConfig(tempRoot),
+				agentPluginPaths: ["./portable-review"],
+			},
+			toggleCoreSettings: async (input) => {
+				toggleCalls.push(input);
+				return {
+					changedTypes: ["plugins", "skills", "mcp"],
+					snapshot: {
+						workflows: [],
+						rules: [],
+						tools: [],
+						skills: [],
+						mcp: [],
+						plugins: [
+							{
+								id: "agent-plugin:portable-review",
+								name: "portable-review",
+								path: pluginRoot,
+								kind: "plugin",
+								source: "global-plugin",
+								enabled: false,
+								toggleable: true,
+								agentPlugin: true,
+							},
+						],
+					},
+				};
+			},
+		});
+
+		const data = await loader.onToggleConfigItem(
+			{
+				id: "agent-plugin:portable-review",
+				name: "portable-review",
+				path: pluginRoot,
+				kind: "plugin",
+				source: "global-plugin",
+				enabled: true,
+				toggleable: true,
+				deletable: false,
+				agentPlugin: true,
+			},
+			{ includePluginTools: false },
+		);
+
+		expect(toggleCalls).toEqual([
+			expect.objectContaining({
+				type: "plugins",
+				id: "agent-plugin:portable-review",
+				path: pluginRoot,
+				name: "portable-review",
+				enabled: false,
+				agentPluginPaths: ["./portable-review"],
+				includePluginTools: false,
+			}),
+		]);
+		expect(data?.plugins).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					name: "portable-review",
+					enabled: false,
+					agentPlugin: true,
+				}),
+			]),
+		);
+		await expect(readFile(globalSettingsPath, "utf8")).rejects.toThrow();
+	});
+
 	it("toggles a skill item to the opposite enabled state and refreshes before reload", async () => {
 		const tempRoot = await mkdtemp(join(tmpdir(), "cli-config-data-"));
 		tempRoots.push(tempRoot);

apps/cli/src/runtime/interactive/config-data.ts

@@ -1,4 +1,8 @@
 import {
+	type CoreSettingsListInput,
+	type CoreSettingsMutationResult,
+	type CoreSettingsSnapshot,
+	type CoreSettingsToggleInput,
 	createCoreSettingsService,
 	disablePluginMcpServersInSettings,
 	setDisabledPlugin,
@@ -10,6 +14,7 @@ import {
 import {
 	type InteractiveConfigData,
 	type InteractiveConfigItem,
+	isToggleableInteractiveConfigItem,
 	type LoadInteractiveConfigDataOptions,
 	loadInteractiveConfigData,
 } from "../../tui/interactive-config";
@@ -18,6 +23,12 @@ import type { Config } from "../../utils/types";
 export function createInteractiveConfigDataLoader(input: {
 	config: Config;
 	userInstructionService?: UserInstructionConfigService;
+	loadCoreSettings?: (
+		input: CoreSettingsListInput,
+	) => Promise<CoreSettingsSnapshot>;
+	toggleCoreSettings?: (
+		input: CoreSettingsToggleInput,
+	) => Promise<CoreSettingsMutationResult>;
 }) {
 	const workspaceRoot = () =>
 		input.config.workspaceRoot?.trim() || input.config.cwd;
@@ -28,16 +39,36 @@ export function createInteractiveConfigDataLoader(input: {
 		enableSpawnAgent: input.config.enableSpawnAgent,
 		enableAgentTeams: input.config.enableAgentTeams,
 	});
-	const loadConfigData = async (
+	const buildSettingsInput = (
 		options: LoadInteractiveConfigDataOptions = {},
-	): Promise<InteractiveConfigData> =>
-		await loadInteractiveConfigData({
+	): CoreSettingsListInput => ({
+		cwd: input.config.cwd,
+		workspaceRoot: workspaceRoot(),
+		availabilityContext: availabilityContext(),
+		agentPluginPaths: input.config.agentPluginPaths,
+		includePluginTools: options.includePluginTools,
+	});
+	const buildConfigData = async (
+		options: LoadInteractiveConfigDataOptions,
+		agentPluginSettings: CoreSettingsSnapshot | undefined,
+	): Promise<InteractiveConfigData> => {
+		return await loadInteractiveConfigData({
 			userInstructionService: input.userInstructionService,
 			cwd: input.config.cwd,
 			workspaceRoot: workspaceRoot(),
 			availabilityContext: availabilityContext(),
 			includePluginTools: options.includePluginTools,
+			agentPluginSettings,
 		});
+	};
+	const loadConfigData = async (
+		options: LoadInteractiveConfigDataOptions = {},
+	): Promise<InteractiveConfigData> => {
+		const agentPluginSettings = await input
+			.loadCoreSettings?.(buildSettingsInput(options))
+			.catch(() => undefined);
+		return await buildConfigData(options, agentPluginSettings);
+	};
 
 	const refreshUserInstructionConfigs = async (): Promise<void> => {
 		const service = input.userInstructionService;
@@ -55,6 +86,9 @@ export function createInteractiveConfigDataLoader(input: {
 		item: InteractiveConfigItem,
 		options: LoadInteractiveConfigDataOptions = {},
 	): Promise<InteractiveConfigData | undefined> => {
+		if (!isToggleableInteractiveConfigItem(item)) {
+			return undefined;
+		}
 		const settings = createCoreSettingsService();
 		if (item.kind === "skill" && typeof item.enabled === "boolean") {
 			await settings.toggle({
@@ -72,6 +106,22 @@ export function createInteractiveConfigDataLoader(input: {
 		}
 
 		if (item.kind === "plugin" && typeof item.enabled === "boolean") {
+			if (item.agentPlugin === true) {
+				if (!input.toggleCoreSettings) {
+					throw new Error(
+						"Agent Plugin settings require a connected Cline Hub.",
+					);
+				}
+				const result = await input.toggleCoreSettings({
+					...buildSettingsInput(options),
+					type: "plugins",
+					id: item.id,
+					path: item.path,
+					name: item.name,
+					enabled: !item.enabled,
+				});
+				return await buildConfigData(options, result.snapshot);
+			}
 			if (item.enabled) {
 				disablePluginMcpServersInSettings({ pluginPaths: [item.path] });
 				setDisabledPlugin(item.path, true);
@@ -150,7 +200,11 @@ export function createInteractiveConfigDataLoader(input: {
 		item: InteractiveConfigItem,
 		options: LoadInteractiveConfigDataOptions = {},
 	): Promise<InteractiveConfigData | undefined> => {
-		if (item.kind !== "plugin") {
+		if (
+			item.kind !== "plugin" ||
+			item.agentPlugin === true ||
+			item.deletable === false
+		) {
 			return undefined;
 		}
 		await uninstallPlugin({

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

@@ -2,6 +2,10 @@ import {
 	type AgentEvent,
 	type AgentHooks,
 	type CheckpointEntry,
+	type CoreSettingsListInput,
+	type CoreSettingsMutationResult,
+	type CoreSettingsSnapshot,
+	type CoreSettingsToggleInput,
 	createSessionCompactionState,
 	isSessionNotFoundError,
 	type PendingPromptMutationResult,
@@ -299,6 +303,19 @@ export function createInteractiveSessionRuntime(input: {
 		return await startupPromise;
 	};
 
+	const listCoreSettings = async (
+		settingsInput: CoreSettingsListInput,
+	): Promise<CoreSettingsSnapshot> => {
+		const manager = await ensureSessionManager();
+		return await manager.settings.list(settingsInput);
+	};
+	const toggleCoreSettings = async (
+		settingsInput: CoreSettingsToggleInput,
+	): Promise<CoreSettingsMutationResult> => {
+		const manager = await ensureSessionManager();
+		return await manager.settings.toggle(settingsInput);
+	};
+
 	const readCurrentMessages = async (): Promise<CurrentMessagesRead> => {
 		const manager = sessionManager;
 		const sessionId = activeSessionId;
@@ -883,6 +900,8 @@ export function createInteractiveSessionRuntime(input: {
 
 	return {
 		ensureReady,
+		listCoreSettings,
+		toggleCoreSettings,
 		sendCurrentTurn,
 		updatePendingPrompt,
 		getAccumulatedUsage,

apps/cli/src/runtime/prompt.test.ts

@@ -1,8 +1,17 @@
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { buildUserInputMessage } from "./prompt";
+import { basename, join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildUserInputMessage, resolveSystemPrompt } from "./prompt";
+
+const workspaceDirectories: string[] = [];
+
+afterEach(() => {
+	for (const directory of workspaceDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
 
 describe("buildUserInputMessage", () => {
 	it("extracts image mentions into userImages", async () => {
@@ -43,3 +52,43 @@ describe("buildUserInputMessage", () => {
 		expect(result.userFiles).toEqual([filePath]);
 	});
 });
+
+describe("resolveSystemPrompt workspace metadata", () => {
+	it("includes git remotes and the latest commit for Cline requests", async () => {
+		const cwd = mkdtempSync(join(tmpdir(), "cline-prompt-"));
+		workspaceDirectories.push(cwd);
+		execFileSync("git", ["init"], { cwd });
+		execFileSync("git", ["config", "user.email", "test@cline.bot"], { cwd });
+		execFileSync("git", ["config", "user.name", "Cline Test"], { cwd });
+		writeFileSync(join(cwd, "README.md"), "test\n");
+		execFileSync("git", ["add", "README.md"], { cwd });
+		execFileSync("git", ["commit", "-m", "initial"], { cwd });
+		execFileSync(
+			"git",
+			["remote", "add", "origin", "https://example.com/cline/repo.git"],
+			{ cwd },
+		);
+		const commit = execFileSync("git", ["rev-parse", "HEAD"], {
+			cwd,
+			encoding: "utf8",
+		}).trim();
+
+		const prompt = await resolveSystemPrompt({ cwd, providerId: "cline" });
+
+		expect(prompt).toContain("origin: https://example.com/cline/repo.git");
+		expect(prompt).toContain(commit);
+	});
+
+	it("includes parseable metadata outside a project", async () => {
+		const cwd = mkdtempSync(join(tmpdir(), "cline-prompt-"));
+		workspaceDirectories.push(cwd);
+
+		const prompt = await resolveSystemPrompt({ cwd, providerId: "cline" });
+
+		expect(prompt).toContain("# Workspace Configuration");
+		expect(prompt).toContain(JSON.stringify(cwd));
+		expect(prompt).toContain(`"hint": "${basename(cwd)}"`);
+		expect(prompt).not.toContain("associatedRemoteUrls");
+		expect(prompt).not.toContain("latestGitCommitHash");
+	});
+});

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

@@ -200,10 +200,6 @@ export async function runInteractive(
 	let pluginChatCommandHostPromise:
 		| Promise<InteractiveSlashCommand[]>
 		| undefined;
-	const configDataLoader = createInteractiveConfigDataLoader({
-		config,
-		userInstructionService,
-	});
 	const ensurePluginChatCommandHost = async (): Promise<
 		InteractiveSlashCommand[]
 	> => {
@@ -302,6 +298,12 @@ export async function runInteractive(
 			uiEvents.emit("pending-prompt-submitted", event);
 		},
 	});
+	const configDataLoader = createInteractiveConfigDataLoader({
+		config,
+		userInstructionService,
+		loadCoreSettings: sessionRuntime.listCoreSettings,
+		toggleCoreSettings: sessionRuntime.toggleCoreSettings,
+	});
 	let modeChangePromise: Promise<void> | undefined;
 	let modeChangeTarget: "plan" | "act" | undefined;
 	const modeSwitchNotice = createModeSwitchNoticeTracker();

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

@@ -11,6 +11,8 @@ import {
 	getValidClineCredentials,
 	type ProviderSettings,
 	ProviderSettingsManager,
+	persistClineAccountTelemetryIdentity,
+	resolveClineAccountTelemetryIdentity,
 	saveLocalProviderOAuthCredentials,
 	type UserCurrentPlan,
 } from "@cline/core";
@@ -158,38 +160,6 @@ 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;
@@ -213,16 +183,12 @@ export async function loadClineAccountSnapshot(input: {
 	const displayedBalance = activeOrganization
 		? (organizationBalance?.balance ?? balance.balance)
 		: balance.balance;
-	const accountContext = {
-		id: user.id,
-		email: user.email,
-		provider: "cline",
-		organizationId: activeOrganization?.organizationId,
-		organizationName: activeOrganization?.name,
-		memberId: activeOrganization?.memberId,
-	};
+	const accountContext = resolveClineAccountTelemetryIdentity(user);
 	identifyTelemetryAccount(accountContext, input.config.logger);
-	persistClineOrganizationContext(activeOrganization, user.id);
+	persistClineAccountTelemetryIdentity(
+		new ProviderSettingsManager(),
+		accountContext,
+	);
 
 	return {
 		user,

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

@@ -657,11 +657,18 @@ export function ChatEntryView(props: {
 						 * token identity, so settled content never re-renders.
 						 * tableOptions preserves the bordered table style that coalesced
 						 * mode used by default (top-level defaults to borderless columns).
+						 *
+						 * streaming stays true even after the entry settles: flipping the
+						 * prop makes MarkdownRenderable rebuild every block from scratch
+						 * (updateBlocks(true) skips all reuse paths), so the finished
+						 * message flashes back to unhighlighted text while tree-sitter
+						 * re-highlights. opencode's TUI keeps streaming={true} for the
+						 * same reason. entry.streaming still drives the spinner glyph.
 						 */}
 						<markdown
 							content={content}
 							syntaxStyle={getSyntaxStyle(theme, mode)}
-							streaming={entry.streaming}
+							streaming={true}
 							internalBlockMode="top-level"
 							tableOptions={{ style: "grid" }}
 							fg={defaultFg}

apps/cli/src/tui/components/dialogs/config-dialogs-helpers.ts

@@ -47,7 +47,10 @@ export function shouldCloseExtDetailForKey(keyName: string): boolean {
 
 export function shouldToggleExtDetailForKey(
 	keyName: string,
-	item: Pick<InteractiveConfigItem, "kind" | "source" | "enabled">,
+	item: Pick<
+		InteractiveConfigItem,
+		"kind" | "source" | "enabled" | "pluginName" | "toggleable"
+	>,
 ): boolean {
 	return (
 		keyName === "space" &&
@@ -57,7 +60,10 @@ export function shouldToggleExtDetailForKey(
 }
 
 export function getExtDetailFooterText(
-	item: Pick<InteractiveConfigItem, "kind" | "source" | "enabled">,
+	item: Pick<
+		InteractiveConfigItem,
+		"kind" | "source" | "enabled" | "pluginName" | "toggleable"
+	>,
 ): string {
 	return typeof item.enabled === "boolean" &&
 		isToggleableInteractiveConfigItem(item)

apps/cli/src/tui/components/dialogs/hub-update-required-helpers.ts

@@ -14,6 +14,27 @@ export function resolveHubUpdateRequiredKeyAction(
 	return "ignore";
 }
 
+/**
+ * Human phrase for the live work an outdated Hub is serving, used by the
+ * "Hub update required" dialog. Falls back to an unquantified phrase when the
+ * Hub could not answer the activity query.
+ */
+export function describeOutdatedHubSessions(counts: {
+	activeSessionCount?: number;
+	participantClientCount?: number;
+}): string {
+	const sessions = counts.activeSessionCount;
+	if (typeof sessions !== "number" || sessions <= 0) {
+		return "active sessions from other Cline clients";
+	}
+	const sessionsPhrase = `${sessions} active session${sessions === 1 ? "" : "s"}`;
+	const clients = counts.participantClientCount;
+	if (typeof clients !== "number" || clients <= 0) {
+		return sessionsPhrase;
+	}
+	return `${sessionsPhrase} from ${clients} connected Cline client${clients === 1 ? "" : "s"}`;
+}
+
 /**
  * Yolo and sandbox sessions force the local backend and never attach to the
  * shared managed Hub (see the forceLocalBackend condition in the interactive

apps/cli/src/tui/components/dialogs/hub-update-required.tsx

@@ -2,12 +2,21 @@
 import type { ChoiceContext } from "@opentui-ui/dialog";
 import { useDialogKeyboard } from "@opentui-ui/dialog/react";
 import { useDialogPalette } from "../../hooks/use-theme";
-import { resolveHubUpdateRequiredKeyAction } from "./hub-update-required-helpers";
+import {
+	describeOutdatedHubSessions,
+	resolveHubUpdateRequiredKeyAction,
+} from "./hub-update-required-helpers";
 
 export interface HubUpdateRequiredDetails {
 	hubCoreVersion?: string;
 }
 
+/**
+ * Shown only for `unsupported_protocol`: the running Hub speaks a protocol
+ * this CLI cannot, so nothing hub-backed works until the CLI updates. The
+ * softer `build_mismatch` case (newer Hub, compatible protocol) is a toast
+ * in root.tsx, not this modal.
+ */
 export function HubUpdateRequiredContent(
 	props: ChoiceContext<boolean> & HubUpdateRequiredDetails,
 ) {
@@ -29,13 +38,12 @@ export function HubUpdateRequiredContent(
 			<text fg="yellow">Cline Hub was updated</text>
 			<box flexDirection="column">
 				<text selectable>
-					Another Cline installation restarted the shared Cline Hub
-					{hubCoreVersion ? ` (core ${hubCoreVersion})` : ""}, and it no longer
-					matches this CLI.
+					Another Cline installation updated the shared Cline Hub
+					{hubCoreVersion ? ` (core ${hubCoreVersion})` : ""} to a version this
+					CLI cannot talk to.
 				</text>
 				<text selectable>
-					Update and restart Cline so this CLI and the Hub run the same version
-					again.
+					Update and restart Cline to reconnect to the running Hub.
 				</text>
 			</box>
 			<box flexDirection="row">
@@ -49,3 +57,64 @@ export function HubUpdateRequiredContent(
 		</box>
 	);
 }
+
+export interface HubOutdatedDetails {
+	hubCoreVersion?: string;
+	activeSessionCount?: number;
+	participantClientCount?: number;
+}
+
+/**
+ * Shown when this CLI is the newer build and the shared Hub was left running
+ * an older one because it is still serving other clients' sessions. Enter
+ * replaces the Hub now (interrupting that work); Esc keeps it running.
+ */
+export function HubOutdatedContent(
+	props: ChoiceContext<boolean> & HubOutdatedDetails,
+) {
+	const {
+		activeSessionCount,
+		dialogId,
+		dismiss,
+		participantClientCount,
+		resolve,
+	} = props;
+	const palette = useDialogPalette();
+
+	useDialogKeyboard((key) => {
+		const action = resolveHubUpdateRequiredKeyAction(key);
+		if (action === "ignore") return;
+		if (action === "update") {
+			resolve(true);
+			return;
+		}
+		dismiss();
+	}, dialogId);
+
+	return (
+		<box flexDirection="column" paddingX={1} gap={1}>
+			<text fg="yellow">Cline Hub update required</text>
+			<box flexDirection="column">
+				<text selectable>
+					This CLI needs a newer Cline Hub, but the running one is still serving{" "}
+					{describeOutdatedHubSessions({
+						activeSessionCount,
+						participantClientCount,
+					})}
+					.
+				</text>
+				<text selectable>
+					Updating stops that Hub and interrupts its sessions.
+				</text>
+			</box>
+			<box flexDirection="row">
+				<box paddingX={1} backgroundColor={palette.act}>
+					<text fg={palette.textOnSelection}>Update Now</text>
+				</box>
+			</box>
+			<text fg={palette.muted}>
+				Press Enter to update now, Esc to keep the Hub running
+			</text>
+		</box>
+	);
+}

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

@@ -3,7 +3,6 @@ import {
 	type ProviderSettingsManager,
 	saveLocalProviderSettings,
 } from "@cline/core";
-import { CLI_PROMO_CODE } from "../../../utils/cline-pass-errors";
 import {
 	type DialogDismissKey,
 	isAnyKeyDismiss,
@@ -77,8 +76,5 @@ export function buildClinePassSubscriptionPageUrl(
 		appBaseUrl || DEFAULT_APP_BASE_URL,
 	);
 	url.searchParams.set("personal", "true");
-	if (CLI_PROMO_CODE) {
-		url.searchParams.set("code", CLI_PROMO_CODE);
-	}
 	return url.toString();
 }

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

@@ -1,6 +1,7 @@
 import {
 	completeClineDeviceAuth,
 	getProviderConfigFields,
+	isLocalAuthProvider,
 	isOAuthProvider,
 	loginLocalProvider,
 	type ProviderConfigFieldKey,
@@ -15,11 +16,10 @@ import type { ChoiceContext } from "@opentui-ui/dialog";
 import { useDialogKeyboard } from "@opentui-ui/dialog/react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
-	CODEX_CLI_INSTALL_URL,
-	type CodexCliStatus,
-	checkCodexCliInstalled,
-	isOpenAICodexCliProvider,
-} from "../../../utils/codex-cli";
+	checkLocalCliInstalled,
+	type LocalCliStatus,
+	type ProviderLocalCli,
+} from "../../../utils/local-cli";
 import open from "../../../utils/open";
 import { listLocalProviders } from "../../../utils/provider-catalog";
 import { useDialogPalette } from "../../hooks/use-theme";
@@ -33,6 +33,7 @@ import {
 	updateProviderConfigValue,
 } from "../../utils/provider-config-values";
 import { getProviderSection } from "../../utils/provider-sections";
+import { canContinueLocalCliSetup } from "../../views/onboarding/model";
 import {
 	getSearchableListRowsWindow,
 	type SearchableItem,
@@ -82,7 +83,7 @@ export function ProviderPickerContent(
 					// just a model id and base URL) still render as configured.
 					isConfigured: p.enabled === true,
 					isOAuth: isOAuthProvider(p.id),
-					isLocalAuth: isOpenAICodexCliProvider(p.id),
+					isLocalAuth: isLocalAuthProvider(p.id),
 					capabilities: p.capabilities,
 				}));
 				setProviders(providerItems);
@@ -654,29 +655,25 @@ export function ProviderConfigInputContent(
 	);
 }
 
-export function CodexCliStatusContent(
+export function LocalCliStatusContent(
 	props: ChoiceContext<boolean> & {
+		cli?: ProviderLocalCli;
 		providerName: string;
 	},
 ) {
-	const { resolve, dismiss, dialogId, providerName } = props;
+	const { resolve, dismiss, dialogId, cli, providerName } = props;
 	const palette = useDialogPalette();
-	const [status, setStatus] = useState<CodexCliStatus | undefined>();
+	const [status, setStatus] = useState<LocalCliStatus | undefined>();
 	const [checking, setChecking] = useState(false);
 
 	const refresh = useCallback(() => {
+		if (!cli) return;
 		setStatus(undefined);
 		setChecking(true);
-		checkCodexCliInstalled()
+		checkLocalCliInstalled(cli)
 			.then(setStatus)
-			.catch((error: unknown) => {
-				setStatus({
-					installed: false,
-					reason: error instanceof Error ? error.message : String(error),
-				});
-			})
 			.finally(() => setChecking(false));
-	}, []);
+	}, [cli]);
 
 	useEffect(() => {
 		refresh();
@@ -691,7 +688,7 @@ export function CodexCliStatusContent(
 			refresh();
 			return;
 		}
-		if (key.name === "return" && status?.installed) {
+		if (key.name === "return" && canContinueLocalCliSetup(cli, status)) {
 			resolve(true);
 		}
 	}, dialogId);
@@ -702,31 +699,37 @@ export function CodexCliStatusContent(
 				<strong>{providerName}</strong>
 			</text>
 
-			{checking && <text fg="gray">Checking for Codex CLI...</text>}
+			{checking && <text fg="gray">Checking for {providerName}...</text>}
 
 			{status?.installed && (
 				<box flexDirection="column" gap={1}>
-					<text fg={palette.success}>{"\u25cf"} Codex CLI installed</text>
+					<text fg={palette.success}>
+						{"\u25cf"} {providerName} installed
+					</text>
 					<text fg="gray">{status.version}</text>
 				</box>
 			)}
 
 			{status && !status.installed && (
 				<box flexDirection="column" gap={1}>
-					<text fg="yellow">Codex CLI was not found</text>
+					<text fg="yellow">{providerName} was not found</text>
 					<text fg="gray">{status.reason}</text>
-					<text fg="gray">Install Codex CLI from:</text>
-					<text fg={palette.act} selectable>
-						{CODEX_CLI_INSTALL_URL}
-					</text>
+					{cli?.docsUrl && (
+						<box flexDirection="column">
+							<text fg="gray">Install {providerName} from:</text>
+							<text fg={palette.act} selectable>
+								{cli.docsUrl}
+							</text>
+						</box>
+					)}
 				</box>
 			)}
 
 			<text fg="gray">
 				<em>
-					{status?.installed
+					{cli
 						? "Enter to continue, R to recheck, Esc to go back"
-						: "R to recheck, Esc to go back"}
+						: "Enter to continue, Esc to go back"}
 				</em>
 			</text>
 		</box>

apps/cli/src/tui/components/toast.tsx

@@ -23,6 +23,9 @@ export function Toast(props: { toast: ToastState | null }) {
 	};
 	const availableWidth = Math.max(1, width - 4);
 	const maxWidth = Math.min(44, availableWidth);
+	// Border and horizontal padding take four columns. An explicit width (not
+	// maxWidth) is what makes the text wrap instead of clipping at the edge.
+	const boxWidth = Math.min(maxWidth, props.toast.message.length + 4);
 	const right = width < 32 ? 0 : 2;
 	const color = variantColor[props.toast.variant];
 
@@ -32,7 +35,7 @@ export function Toast(props: { toast: ToastState | null }) {
 			zIndex={100}
 			top={1}
 			right={right}
-			maxWidth={maxWidth}
+			width={boxWidth}
 			border
 			borderStyle="rounded"
 			borderColor={color}

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

@@ -10,7 +10,7 @@ import { isClineProvider } from "@cline/shared";
 import type { ChoiceContext } from "@opentui-ui/dialog";
 import type { DialogActions } from "@opentui-ui/dialog/react";
 import { useCallback } from "react";
-import { isOpenAICodexCliProvider } from "../../utils/codex-cli";
+import { getLocalCliInfo } from "../../utils/local-cli";
 import {
 	getPersistedProviderApiKey,
 	isOAuthProvider,
@@ -20,8 +20,8 @@ import type { Config } from "../../utils/types";
 import { withLoadingDialog } from "../components/dialogs/loading-dialog";
 import {
 	ClinePassSubscriptionContent,
-	CodexCliStatusContent,
 	type ExistingProviderOption,
+	LocalCliStatusContent,
 	OAuthApiKeyInputContent,
 	OAuthLoginContent,
 	type OAuthLoginResult,
@@ -43,6 +43,7 @@ import {
 	type ThinkingLevel,
 	ThinkingLevelContent,
 } from "../components/model-selector/model-selector";
+import { resolveProviderSetupRoute } from "../views/onboarding/model";
 
 export interface OpenModelSelectorOptions {
 	onCancel?: () => Promise<void> | void;
@@ -178,6 +179,9 @@ async function runProviderChange(
 		async () => await getProviderDisplayName(newProviderId),
 	);
 	const existingSettings = manager.getProviderSettings(newProviderId);
+	const needsLocalCliSetup =
+		resolveProviderSetupRoute(newProviderId) === "local_cli";
+	const localCliProvider = getLocalCliInfo(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.
@@ -246,12 +250,16 @@ async function runProviderChange(
 				loginResult === "use_api_key"
 					? await openManualApiKeyDialog()
 					: loginResult;
-		} else if (isOpenAICodexCliProvider(newProviderId)) {
+		} else if (needsLocalCliSetup) {
 			saved = await dialog.choice<boolean>({
 				style: { maxHeight: termHeight - 2 },
 				closeOnEscape: false,
 				content: (ctx: ChoiceContext<boolean>) => (
-					<CodexCliStatusContent {...ctx} providerName={displayName} />
+					<LocalCliStatusContent
+						{...ctx}
+						cli={localCliProvider}
+						providerName={displayName}
+					/>
 				),
 			});
 			if (saved) {

apps/cli/src/tui/hooks/use-runtime-dialog-bridge.tsx

@@ -1,5 +1,9 @@
 import type { AgentMode } from "@cline/core";
-import type { ToolApprovalRequest, ToolApprovalResult } from "@cline/shared";
+import {
+	type ToolApprovalRequest,
+	type ToolApprovalResult,
+	USER_REJECTED_TOOL_REASON,
+} from "@cline/shared";
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { RuntimeToolInteraction, TuiProps } from "../types";
 
@@ -36,16 +40,16 @@ function toRuntimeToolInteraction(
 	};
 }
 
-function deniedToolResult(request: ToolApprovalRequest): ToolApprovalResult {
+function deniedToolResult(): ToolApprovalResult {
 	return {
 		approved: false,
-		reason: `Tool "${request.toolName}" was denied by user`,
+		reason: USER_REJECTED_TOOL_REASON,
 	};
 }
 
 function dismissPendingInteraction(pending: PendingRuntimeToolInteraction) {
 	if (pending.kind === "tool_approval") {
-		pending.resolve(deniedToolResult(pending.request));
+		pending.resolve(deniedToolResult());
 		return;
 	}
 	pending.resolve("[User dismissed the question]");
@@ -111,9 +115,7 @@ export function useRuntimeDialogBridge(input: {
 			if (!pending || pending.id !== id || pending.kind !== "tool_approval") {
 				return;
 			}
-			pending.resolve(
-				approved ? { approved: true } : deniedToolResult(pending.request),
-			);
+			pending.resolve(approved ? { approved: true } : deniedToolResult());
 			const hasNext = finishActive(id);
 			if (!hasNext) {
 				refocusTextarea();

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

@@ -9,6 +9,8 @@ import {
 } from "node:path";
 import {
 	type BuiltinToolAvailabilityContext,
+	type CoreSettingsItem,
+	type CoreSettingsSnapshot,
 	DEFAULT_MCP_CONNECT_TIMEOUT_MS,
 	discoverPluginModulePaths,
 	getPluginDisplayName,
@@ -80,6 +82,12 @@ export interface InteractiveConfigItem {
 		| "global-plugin"
 		| "workspace-plugin";
 	description?: string;
+	/** True when the hub discovered this through agent-plugins.org. */
+	agentPlugin?: boolean;
+	/** Explicitly overrides the default toggle policy for this item. */
+	toggleable?: boolean;
+	/** Explicitly overrides the default delete policy for this item. */
+	deletable?: boolean;
 }
 
 export interface InteractiveConfigData {
@@ -100,8 +108,14 @@ export interface LoadInteractiveConfigDataOptions {
 }
 
 export function isToggleableInteractiveConfigItem(
-	item: Pick<InteractiveConfigItem, "kind" | "source" | "pluginName">,
+	item: Pick<
+		InteractiveConfigItem,
+		"kind" | "source" | "pluginName" | "toggleable"
+	>,
 ): boolean {
+	if (item.toggleable !== undefined) {
+		return item.toggleable;
+	}
 	if (item.kind === "mcp") {
 		return !item.pluginName;
 	}
@@ -324,12 +338,53 @@ export function applyPluginFailures(
 	}
 }
 
+function toAgentPluginInteractiveItem(
+	item: CoreSettingsItem,
+): InteractiveConfigItem {
+	return {
+		id: item.id,
+		name: item.name,
+		path: item.path,
+		enabled: item.enabled,
+		kind: item.kind,
+		source: item.source,
+		description: item.description,
+		pluginName: item.pluginName,
+		pluginPath: item.pluginPath,
+		loadError: item.loadError,
+		agentPlugin: true,
+		toggleable: item.toggleable ?? false,
+		deletable: false,
+		...(item.kind === "plugin" ? { configKind: "plugin" as const } : {}),
+	};
+}
+
+function appendAgentPluginSnapshotItems(
+	target: InteractiveConfigItem[],
+	items: readonly CoreSettingsItem[],
+): void {
+	const existing = new Set(
+		target.map((item) => `${item.kind}\0${item.id}\0${item.path}`),
+	);
+	for (const item of items) {
+		if (item.agentPlugin !== true) {
+			continue;
+		}
+		const key = `${item.kind}\0${item.id}\0${item.path}`;
+		if (!existing.has(key)) {
+			target.push(toAgentPluginInteractiveItem(item));
+			existing.add(key);
+		}
+	}
+}
+
 export async function loadInteractiveConfigData(input: {
 	userInstructionService?: UserInstructionConfigService;
 	cwd: string;
 	workspaceRoot: string;
 	availabilityContext?: BuiltinToolAvailabilityContext;
 	includePluginTools?: boolean;
+	agentPluginSettings?: CoreSettingsSnapshot;
 }): Promise<InteractiveConfigData> {
 	const workflows: InteractiveConfigItem[] = [];
 	const rules: InteractiveConfigItem[] = [];
@@ -518,14 +573,23 @@ export async function loadInteractiveConfigData(input: {
 		}
 	}
 
+	if (input.agentPluginSettings) {
+		appendAgentPluginSnapshotItems(plugins, input.agentPluginSettings.plugins);
+		appendAgentPluginSnapshotItems(skills, input.agentPluginSettings.skills);
+		appendAgentPluginSnapshotItems(mcp, input.agentPluginSettings.mcp);
+	}
+
+	const existsLocallyOrComesFromHub = (item: InteractiveConfigItem) =>
+		item.agentPlugin === true || existsSync(item.path);
+
 	return {
-		workflows: toSorted(workflows.filter((item) => existsSync(item.path))),
-		rules: toSorted(rules.filter((item) => existsSync(item.path))),
-		skills: toSorted(skills.filter((item) => existsSync(item.path))),
-		hooks: toSorted(hooks.filter((item) => existsSync(item.path))),
-		agents: toSorted(agents.filter((item) => existsSync(item.path))),
-		plugins: toSorted(plugins.filter((item) => existsSync(item.path))),
-		mcp: toSorted(mcp.filter((item) => existsSync(item.path))),
+		workflows: toSorted(workflows.filter(existsLocallyOrComesFromHub)),
+		rules: toSorted(rules.filter(existsLocallyOrComesFromHub)),
+		skills: toSorted(skills.filter(existsLocallyOrComesFromHub)),
+		hooks: toSorted(hooks.filter(existsLocallyOrComesFromHub)),
+		agents: toSorted(agents.filter(existsLocallyOrComesFromHub)),
+		plugins: toSorted(plugins.filter(existsLocallyOrComesFromHub)),
+		mcp: toSorted(mcp.filter(existsLocallyOrComesFromHub)),
 		tools: toSorted(tools),
 		workflowSlashCommands,
 		pluginDiagnosticsLoaded: input.includePluginTools !== false,

apps/cli/src/tui/root.tsx

@@ -2,6 +2,7 @@ import {
 	getCurrentContextSize,
 	type ManagedHubBuildMismatchEvent,
 	summarizeUsageFromMessages,
+	upgradeManagedHub,
 	watchManagedHubBuildMismatch,
 } from "@cline/core";
 import { formatDisplayUserInput } from "@cline/shared";
@@ -40,7 +41,10 @@ import {
 	buildCommandPaletteItems,
 	findCommandPaletteShortcut,
 } from "./components/dialogs/command-palette-items";
-import { HubUpdateRequiredContent } from "./components/dialogs/hub-update-required";
+import {
+	HubOutdatedContent,
+	HubUpdateRequiredContent,
+} from "./components/dialogs/hub-update-required";
 import { shouldWatchManagedHubBuild } from "./components/dialogs/hub-update-required-helpers";
 import {
 	SKILLS_MARKETPLACE_ACTION,
@@ -586,17 +590,85 @@ function App(props: TuiProps) {
 		setHubBuildMismatch(null);
 		const hubCoreVersion = hubBuildMismatch.hubCoreVersion;
 		if (hubBuildMismatch.reason === "outdated_hub") {
-			// This CLI is already the newer build. The Hub is behind only because
-			// retiring it would kill the sessions it is serving, and it is
-			// replaced on its own at the next launch. Nothing is wrong, nothing is
-			// asked, and nothing the user can act on differs - so say nothing, the
-			// same conclusion the desktop surface reached.
-			//
-			// The classification still earns its keep here: it is what stops the
-			// update-and-restart prompt below from firing at someone who has
-			// nothing to update.
+			// This CLI is already the newer build; the Hub is behind only because
+			// retiring it would kill the sessions it is serving. Left alone it
+			// would stay behind for as long as those sessions run, so put the
+			// choice to the user: replace it now (interrupting that work), or
+			// keep it running and update later. This session itself is safe
+			// either way - a CLI that could not attach to the outdated Hub is
+			// running on the local backend.
+			const details = {
+				hubCoreVersion,
+				activeSessionCount: hubBuildMismatch.activeSessionCount,
+				participantClientCount: hubBuildMismatch.participantClientCount,
+			};
+			void dialog
+				.choice<boolean>({
+					content: (ctx: ChoiceContext<boolean>) => (
+						<HubOutdatedContent {...ctx} {...details} />
+					),
+				})
+				.then(async (update) => {
+					if (!update) {
+						// choice() resolves undefined on Esc; it does not reject.
+						showToast(
+							"The running Cline Hub stays on the older version. Run 'cline hub upgrade' once its sessions finish.",
+							"info",
+						);
+						refocusTextareaRef.current();
+						return;
+					}
+					showToast("Updating the Cline Hub…", "info");
+					try {
+						const result = await upgradeManagedHub({
+							force: true,
+							reason: "cline TUI hub update",
+						});
+						if (result.outcome === "still_busy") {
+							showToast(
+								"The Hub picked up new sessions before it could be replaced. Try again in a moment.",
+								"info",
+							);
+						} else {
+							showToast(
+								result.outcome === "replaced" || result.outcome === "started"
+									? "Cline Hub updated."
+									: "Cline Hub is already up to date.",
+								"success",
+							);
+						}
+					} catch (error) {
+						showToast(
+							error instanceof Error && error.message
+								? error.message
+								: "Updating the Cline Hub failed. Run 'cline doctor fix' and try again.",
+							"error",
+						);
+					}
+					refocusTextareaRef.current();
+				})
+				.catch(() => {
+					refocusTextareaRef.current();
+				});
 			return;
 		}
+		if (hubBuildMismatch.reason === "build_mismatch") {
+			// The Hub is newer but still speaks this CLI's protocol, so the
+			// session keeps working and parity is advisable rather than urgent.
+			// A modal mid-session is too heavy for advice; a toast (once per
+			// observed Hub build, the watcher dedupes) says what changed and
+			// how to catch up without stealing focus.
+			showToast(
+				`The shared Cline Hub was updated${
+					hubCoreVersion ? ` (core ${hubCoreVersion})` : ""
+				}. Run 'cline update' and restart when convenient.`,
+				"info",
+			);
+			return;
+		}
+		// unsupported_protocol: this CLI cannot speak the running Hub's
+		// protocol at all, so nothing hub-backed can work until it updates.
+		// That is worth a blocking prompt.
 		void dialog
 			.choice<boolean>({
 				content: (ctx: ChoiceContext<boolean>) => (

apps/cli/src/tui/utils/provider-configured.ts

@@ -1,5 +1,4 @@
-import { ProviderSettingsManager } from "@cline/core";
-import { isProviderSettingsUsable } from "../../utils/provider-readiness";
+import { isProviderSettingsUsable, ProviderSettingsManager } from "@cline/core";
 import type { TuiProps } from "../types";
 
 export function isProviderConfigured(config: TuiProps["config"]): boolean {

apps/cli/src/tui/views/config-view-helpers.ts

@@ -128,12 +128,61 @@ export function resolveActiveConfigItems(
 	}
 }
 
+export interface ConfigPluginSection {
+	label: string;
+	items: InteractiveConfigItem[];
+}
+
+export function getConfigPluginSections(
+	items: readonly InteractiveConfigItem[],
+): ConfigPluginSection[] {
+	const clinePlugins = items.filter((item) => item.agentPlugin !== true);
+	const agentPlugins = items.filter((item) => item.agentPlugin === true);
+	return [
+		...(clinePlugins.length > 0
+			? [
+					{
+						label: `Cline Plugins (${clinePlugins.length})`,
+						items: clinePlugins,
+					},
+				]
+			: []),
+		...(agentPlugins.length > 0
+			? [
+					{
+						label: `Agent Plugins (${agentPlugins.length})`,
+						items: agentPlugins,
+					},
+				]
+			: []),
+	];
+}
+
+export function getConfigTabCountHeading(
+	tab: InteractiveConfigTab,
+	itemCount: number,
+): string | undefined {
+	return tab === "plugins" ? undefined : `${toTabLabel(tab)} (${itemCount})`;
+}
+
+export function shouldRenderConfigItemAsEnabled(
+	item: InteractiveConfigItem,
+	enabledState: "enabled" | "disabled" | "partial",
+): boolean {
+	return (
+		enabledState === "enabled" &&
+		(isToggleableInteractiveConfigItem(item) || item.agentPlugin === true)
+	);
+}
+
 export function isToggleableConfigItem(item: InteractiveConfigItem): boolean {
 	return isToggleableInteractiveConfigItem(item);
 }
 
 export function isDeletableConfigItem(item: InteractiveConfigItem): boolean {
-	return item.kind === "plugin";
+	return (
+		item.deletable ?? (item.kind === "plugin" && item.agentPlugin !== true)
+	);
 }
 
 export function resolveConfigItemSelectAction(

apps/cli/src/tui/views/config-view.test.ts

@@ -5,11 +5,16 @@ import {
 	getAdjacentConfigTab,
 	getConfigFooterText,
 	getConfigItemDisplayName,
+	getConfigPluginSections,
+	getConfigTabCountHeading,
+	isDeletableConfigItem,
 	isInlineConfigAction,
 	isToggleableConfigItem,
+	resolveConfigItemDeleteAction,
 	resolveConfigItemSelectAction,
 	resolveConfigItemToggleAction,
 	resolveInitialConfigTab,
+	shouldRenderConfigItemAsEnabled,
 } from "./config-view-helpers";
 
 function createItem(
@@ -71,6 +76,65 @@ describe("config view helpers", () => {
 		).toBe(false);
 	});
 
+	it("lets users toggle hub-discovered Agent Plugins without deleting them", () => {
+		const plugin = createItem({
+			kind: "plugin",
+			agentPlugin: true,
+			toggleable: true,
+			deletable: false,
+			source: "global-plugin",
+		});
+
+		expect(isToggleableConfigItem(plugin)).toBe(true);
+		expect(isDeletableConfigItem(plugin)).toBe(false);
+		expect(resolveConfigItemToggleAction(plugin)).toEqual({
+			kind: "toggle-item",
+			item: plugin,
+		});
+		expect(resolveConfigItemDeleteAction(plugin)).toBeUndefined();
+		expect(resolveConfigItemSelectAction(plugin)).toEqual({
+			kind: "toggle-item",
+			item: plugin,
+		});
+	});
+
+	it("separates Cline and Agent Plugins into labeled sections", () => {
+		const clinePlugin = createItem({
+			kind: "plugin",
+			name: "cline-plugin",
+			source: "workspace-plugin",
+		});
+		const agentPlugin = createItem({
+			kind: "plugin",
+			name: "portable-plugin",
+			source: "global-plugin",
+			agentPlugin: true,
+		});
+
+		expect(getConfigPluginSections([clinePlugin, agentPlugin])).toEqual([
+			{ label: "Cline Plugins (1)", items: [clinePlugin] },
+			{ label: "Agent Plugins (1)", items: [agentPlugin] },
+		]);
+	});
+
+	it("uses section counts instead of a combined Plugins heading", () => {
+		expect(getConfigTabCountHeading("plugins", 10)).toBeUndefined();
+		expect(getConfigTabCountHeading("skills", 20)).toBe("Skills (20)");
+	});
+
+	it("renders a loaded Agent Plugin as enabled", () => {
+		const agentPlugin = createItem({
+			kind: "plugin",
+			agentPlugin: true,
+			toggleable: true,
+		});
+
+		expect(shouldRenderConfigItemAsEnabled(agentPlugin, "enabled")).toBe(true);
+		expect(shouldRenderConfigItemAsEnabled(agentPlugin, "disabled")).toBe(
+			false,
+		);
+	});
+
 	it("resolves Enter/Tab on a skill row to details", () => {
 		const skill = createItem({
 			kind: "skill",

apps/cli/src/tui/views/config-view.tsx

@@ -25,6 +25,8 @@ import {
 	getAdjacentConfigTab,
 	getConfigFooterText,
 	getConfigItemDisplayName,
+	getConfigPluginSections,
+	getConfigTabCountHeading,
 	getConfigTabs,
 	getPluginDiagnosticsLoadingText,
 	isInlineConfigAction,
@@ -34,6 +36,7 @@ import {
 	resolveConfigItemSelectAction,
 	resolveConfigItemToggleAction,
 	resolveInitialConfigTab,
+	shouldRenderConfigItemAsEnabled,
 	toTabLabel,
 } from "./config-view-helpers";
 
@@ -298,6 +301,16 @@ function appendSkillRows(
 	}
 }
 
+function appendPluginRows(
+	rows: ConfigRow[],
+	items: InteractiveConfigItem[],
+): void {
+	for (const section of getConfigPluginSections(items)) {
+		rows.push({ kind: "head", label: section.label });
+		appendExtRows(rows, section.items);
+	}
+}
+
 function withOptimisticToggle(
 	data: InteractiveConfigData,
 	item: InteractiveConfigItem,
@@ -477,10 +490,13 @@ export function ConfigPanelContent(props: ConfigPanelProps) {
 			r.push({ kind: "toggle", id: "verbose", label: "Verbose" });
 		} else {
 			const activeItems = resolveActiveConfigItems(configData, activeTab);
-			r.push({
-				kind: "head",
-				label: `${toTabLabel(activeTab)} (${activeItems.length})`,
-			});
+			const countHeading = getConfigTabCountHeading(
+				activeTab,
+				activeItems.length,
+			);
+			if (countHeading) {
+				r.push({ kind: "head", label: countHeading });
+			}
 
 			if (activeItems.length === 0 && !pluginToolsLoading) {
 				r.push({
@@ -504,6 +520,21 @@ export function ConfigPanelContent(props: ConfigPanelProps) {
 				}
 			} else if (activeTab === "skills") {
 				appendSkillRows(r, activeItems);
+			} else if (activeTab === "plugins") {
+				appendPluginRows(r, activeItems);
+				if (pluginToolsLoading) {
+					const loadingText = getPluginDiagnosticsLoadingText(activeTab);
+					r.push({
+						kind: "detail",
+						text: loadingText ?? "Loading plugin diagnostics...",
+					});
+				}
+				if (pluginToolsError) {
+					r.push({
+						kind: "detail",
+						text: pluginToolsError,
+					});
+				}
 			} else {
 				for (const item of activeItems) {
 					r.push({
@@ -523,19 +554,6 @@ export function ConfigPanelContent(props: ConfigPanelProps) {
 								: getPluginLoadErrorLabel(item),
 					});
 				}
-				if (activeTab === "plugins" && pluginToolsLoading) {
-					const loadingText = getPluginDiagnosticsLoadingText(activeTab);
-					r.push({
-						kind: "detail",
-						text: loadingText ?? "Loading plugin diagnostics...",
-					});
-				}
-				if (activeTab === "plugins" && pluginToolsError) {
-					r.push({
-						kind: "detail",
-						text: pluginToolsError,
-					});
-				}
 			}
 
 			if (activeTab === "mcp") {
@@ -871,11 +889,10 @@ export function ConfigPanelContent(props: ConfigPanelProps) {
 											: "○ "
 								: "";
 						const rightLabel = row.rightLabel ?? "";
-						const toggleable = isToggleableConfigItem(row.item);
 						const prefix = " ".repeat(row.indent ?? 0);
 						const rowColor = row.item.loadError
 							? "red"
-							: toggleable && enabledState === "enabled"
+							: shouldRenderConfigItemAsEnabled(row.item, enabledState)
 								? palette.success
 								: enabledState === "partial"
 									? "yellow"

apps/cli/src/tui/views/onboarding/controller.ts

@@ -17,10 +17,11 @@ import {
 	getIndividualPlanFeatures,
 } from "../../../utils/cline-pass-errors";
 import {
-	type CodexCliStatus,
-	checkCodexCliInstalled,
-	isOpenAICodexCliProvider,
-} from "../../../utils/codex-cli";
+	checkLocalCliInstalled,
+	getLocalCliInfo,
+	type LocalCliStatus,
+	type ProviderLocalCli,
+} from "../../../utils/local-cli";
 import open from "../../../utils/open";
 import { getPersistedProviderApiKey } from "../../../utils/provider-auth";
 import { listLocalProviders } from "../../../utils/provider-catalog";
@@ -59,6 +60,7 @@ import { useOnboardingKeyboard } from "./keyboard";
 import {
 	CLINE_PASS_SUBSCRIPTION_OPTIONS,
 	type ClinePassSubscriptionStatus,
+	canContinueLocalCliSetup,
 	DEFAULT_THINKING_LEVEL_INDEX,
 	getMainMenuOptions,
 	type ModelEntry,
@@ -66,6 +68,7 @@ import {
 	type OnboardingStep,
 	type ProviderEntry,
 	type ReasoningEffort,
+	resolveProviderSetupRoute,
 	shouldUseFeaturedClineModelPicker,
 	type ThinkingLevel,
 	toModelEntriesFromKnownModels,
@@ -103,6 +106,10 @@ export function useOnboardingController(props: OnboardingControllerProps) {
 	const [authError, setAuthError] = useState("");
 	const [activeProviderId, setActiveProviderId] = useState("");
 	const [activeProviderName, setActiveProviderName] = useState("");
+	const localCli = useMemo(
+		() => getLocalCliInfo(activeProviderId),
+		[activeProviderId],
+	);
 	const [byoFields, setByoFields] = useState<ProviderConfigFields["fields"]>(
 		{},
 	);
@@ -110,10 +117,11 @@ export function useOnboardingController(props: OnboardingControllerProps) {
 	const [byoValues, setByoValues] = useState<ProviderConfigValues>({});
 	const [byoFocusedField, setByoFocusedField] =
 		useState<ProviderConfigFieldKey>("apiKey");
-	const [codexCliStatus, setCodexCliStatus] = useState<
-		CodexCliStatus | undefined
+	const [localCliStatus, setLocalCliStatus] = useState<
+		LocalCliStatus | undefined
 	>();
-	const [codexCliChecking, setCodexCliChecking] = useState(false);
+	const [localCliChecking, setLocalCliChecking] = useState(false);
+	const localCliProbeRef = useRef(0);
 	const authAbortRef = useRef(false);
 
 	// Device code flow
@@ -486,18 +494,23 @@ export function useOnboardingController(props: OnboardingControllerProps) {
 		}
 	}, [step, clinePassSubscriptionStatus, transitionToModelPicker]);
 
-	const refreshCodexCliStatus = useCallback(() => {
-		setCodexCliStatus(undefined);
-		setCodexCliChecking(true);
-		checkCodexCliInstalled()
-			.then(setCodexCliStatus)
-			.catch((error: unknown) => {
-				setCodexCliStatus({
-					installed: false,
-					reason: error instanceof Error ? error.message : String(error),
-				});
+	const refreshLocalCliStatus = useCallback((provider: ProviderLocalCli) => {
+		// Probing spawns the provider's CLI, so a result can land long after the
+		// user moved on. Two local-CLI providers share this single status, so an
+		// unlabelled result could mark the selected provider ready off a probe of
+		// the previous one (or block it off a stale failure). Only the newest
+		// probe may write.
+		const probeId = ++localCliProbeRef.current;
+		const isCurrentProbe = () => localCliProbeRef.current === probeId;
+		setLocalCliStatus(undefined);
+		setLocalCliChecking(true);
+		checkLocalCliInstalled(provider)
+			.then((status) => {
+				if (isCurrentProbe()) setLocalCliStatus(status);
 			})
-			.finally(() => setCodexCliChecking(false));
+			.finally(() => {
+				if (isCurrentProbe()) setLocalCliChecking(false);
+			});
 	}, []);
 
 	const selectProvider = useCallback(
@@ -510,12 +523,14 @@ export function useOnboardingController(props: OnboardingControllerProps) {
 				}
 				return;
 			}
-			if (provider.isLocalAuth || isOpenAICodexCliProvider(provider.id)) {
+			if (resolveProviderSetupRoute(provider.id) === "local_cli") {
 				setActiveProviderId(provider.id);
 				setActiveProviderName(provider.name);
-				setCodexCliStatus(undefined);
-				setStep("codex_cli_setup");
-				refreshCodexCliStatus();
+				setStep("local_cli_setup");
+				// Only providers that name a CLI have something to probe; the
+				// rest reach the screen with readiness simply unknown.
+				const localCliProvider = getLocalCliInfo(provider.id);
+				if (localCliProvider) refreshLocalCliStatus(localCliProvider);
 				return;
 			}
 			const config = getProviderConfigFields(provider.id);
@@ -575,11 +590,17 @@ export function useOnboardingController(props: OnboardingControllerProps) {
 			setByoFocusedField(firstField ?? "apiKey");
 			setStep("byo_apikey");
 		},
-		[providers, startOAuthFlow, refreshCodexCliStatus, providerSettingsManager],
+		[providers, startOAuthFlow, refreshLocalCliStatus, providerSettingsManager],
 	);
 
-	const saveCodexCliConfig = useCallback(() => {
-		if (!codexCliStatus?.installed) {
+	const recheckLocalCli = useCallback(() => {
+		if (localCli) {
+			refreshLocalCliStatus(localCli);
+		}
+	}, [localCli, refreshLocalCliStatus]);
+
+	const saveLocalCliConfig = useCallback(() => {
+		if (!canContinueLocalCliSetup(localCli, localCliStatus)) {
 			return;
 		}
 		saveLocalProviderSettings(providerSettingsManager, {
@@ -588,7 +609,8 @@ export function useOnboardingController(props: OnboardingControllerProps) {
 		transitionToModelPicker(activeProviderId);
 	}, [
 		activeProviderId,
-		codexCliStatus,
+		localCli,
+		localCliStatus,
 		providerSettingsManager,
 		transitionToModelPicker,
 	]);
@@ -798,13 +820,13 @@ export function useOnboardingController(props: OnboardingControllerProps) {
 			deviceAbortRef.current = true;
 		},
 		resetAuth,
-		refreshCodexCliStatus,
+		refreshLocalCliStatus: recheckLocalCli,
 		startOAuthFlow,
 		startDeviceCodeFlow,
 		selectProvider,
 		loadModelsForProvider,
 		saveClineModelSelection,
-		saveCodexCliConfig,
+		saveLocalCliConfig,
 		saveByoConfig,
 		saveModelSelection,
 		saveThinkingLevel,
@@ -820,8 +842,9 @@ export function useOnboardingController(props: OnboardingControllerProps) {
 		byoFields,
 		byoFocusedField,
 		byoValues,
-		codexCliChecking,
-		codexCliStatus,
+		localCli,
+		localCliChecking,
+		localCliStatus,
 		clineEntries,
 		clineModelSelected,
 		clinePassCurrentPlanName,
@@ -860,7 +883,7 @@ export function useOnboardingController(props: OnboardingControllerProps) {
 		providersLoading,
 		recommendedLoading: recommended.loading,
 		saveByoConfig,
-		saveCodexCliConfig,
+		saveLocalCliConfig,
 		saveCustomModelId,
 		selectedModelName,
 		step,

apps/cli/src/tui/views/onboarding/keyboard.ts

@@ -51,13 +51,13 @@ export function useOnboardingKeyboard(input: {
 	abortOAuth: () => void;
 	abortDeviceCode: () => void;
 	resetAuth: () => void;
-	refreshCodexCliStatus: () => void;
+	refreshLocalCliStatus: () => void;
 	startOAuthFlow: (providerId: OnboardingOAuthProviderId) => void;
 	startDeviceCodeFlow: (providerId: OnboardingOAuthProviderId) => void;
 	selectProvider: (providerId: string) => void;
 	loadModelsForProvider: (providerId: string) => void;
 	saveClineModelSelection: (modelId: string, modelName: string) => void;
-	saveCodexCliConfig: () => void;
+	saveLocalCliConfig: () => void;
 	saveByoConfig: () => void;
 	saveModelSelection: () => void;
 	saveThinkingLevel: (level: ThinkingLevel) => void;
@@ -98,7 +98,7 @@ export function useOnboardingKeyboard(input: {
 				input.setMenuSelected(0);
 				return;
 			}
-			if (input.step === "codex_cli_setup") {
+			if (input.step === "local_cli_setup") {
 				input.setStep("byo_provider");
 				return;
 			}
@@ -227,13 +227,13 @@ export function useOnboardingKeyboard(input: {
 			return;
 		}
 
-		if (input.step === "codex_cli_setup") {
+		if (input.step === "local_cli_setup") {
 			if (key.name === "r") {
-				input.refreshCodexCliStatus();
+				input.refreshLocalCliStatus();
 				return;
 			}
 			if (key.name === "return") {
-				input.saveCodexCliConfig();
+				input.saveLocalCliConfig();
 			}
 			return;
 		}

apps/cli/src/tui/views/onboarding/model.test.ts

@@ -1,7 +1,15 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
+import { getLocalCliInfo } from "../../../utils/local-cli";
+
+vi.mock("../../../utils/local-cli", () => ({
+	getLocalCliInfo: () => undefined,
+}));
+
 import {
+	canContinueLocalCliSetup,
 	getMainMenuOptions,
 	getOAuthProviderLabel,
+	resolveProviderSetupRoute,
 	shouldUseFeaturedClineModelPicker,
 	toModelEntriesFromKnownModels,
 	toModelEntry,
@@ -77,6 +85,20 @@ describe("onboarding model helpers", () => {
 		});
 	});
 
+	it("marks the Claude Code provider as local auth", () => {
+		expect(
+			toProviderEntry({
+				id: "claude-code",
+				name: "Claude Code",
+				models: null,
+			}),
+		).toMatchObject({
+			id: "claude-code",
+			isOAuth: false,
+			isLocalAuth: true,
+		});
+	});
+
 	it("maps model names and reasoning support strictly", () => {
 		expect(
 			toModelEntry({
@@ -166,3 +188,31 @@ describe("onboarding model helpers", () => {
 		expect(shouldUseFeaturedClineModelPicker("anthropic")).toBe(false);
 	});
 });
+
+describe("local-auth setup routing", () => {
+	// A provider can declare `local-auth` without naming a CLI we can probe.
+	// Routing must follow the capability; the descriptor is only for probing.
+	// Otherwise it falls through to the API-key form, which renders no fields
+	// for a local-auth provider.
+	it("routes a local-auth provider with no CLI descriptor to local setup", () => {
+		expect(getLocalCliInfo("claude-code")).toBeUndefined();
+		expect(resolveProviderSetupRoute("claude-code")).toBe("local_cli");
+	});
+
+	it("routes OAuth and API-key providers unchanged", () => {
+		expect(resolveProviderSetupRoute("anthropic")).toBe("api_key");
+	});
+
+	// The probe only looks on PATH, while the runtime also accepts an explicit
+	// pathToClaudeCodeExecutable and a bundled platform binary. A PATH miss
+	// therefore means "not on PATH", not "unusable", so it must not block.
+	it("lets the user continue when the CLI is not found on PATH", () => {
+		const cli = { command: "claude", docsUrl: "https://example.invalid" };
+		expect(
+			canContinueLocalCliSetup(cli, {
+				installed: false,
+				reason: "The claude executable was not found on PATH.",
+			}),
+		).toBe(true);
+	});
+});

apps/cli/src/tui/views/onboarding/model.ts

@@ -4,8 +4,14 @@ import type {
 	ModelOperation,
 } from "@cline/shared";
 import { isChatProviderModel } from "../../../utils/chat-models";
-import { isOpenAICodexCliProvider } from "../../../utils/codex-cli";
-import { isOAuthProvider } from "../../../utils/provider-auth";
+import type {
+	LocalCliStatus,
+	ProviderLocalCli,
+} from "../../../utils/local-cli";
+import {
+	isLocalAuthProvider,
+	isOAuthProvider,
+} from "../../../utils/provider-auth";
 
 export type OnboardingStep =
 	| "menu"
@@ -13,7 +19,7 @@ export type OnboardingStep =
 	| "device_code"
 	| "byo_provider"
 	| "byo_apikey"
-	| "codex_cli_setup"
+	| "local_cli_setup"
 	| "cline_pass_subscription"
 	| "cline_model"
 	| "model_picker"
@@ -85,6 +91,35 @@ export const MAIN_MENU: MenuOption[] = [
 	},
 ];
 
+/**
+ * Which setup flow a provider needs. Keyed off how the provider authenticates,
+ * so every caller routes the same way.
+ */
+export type ProviderSetupRoute = "oauth" | "local_cli" | "api_key";
+
+export function resolveProviderSetupRoute(
+	providerId: string,
+): ProviderSetupRoute {
+	if (isOAuthProvider(providerId)) return "oauth";
+	if (isLocalAuthProvider(providerId)) return "local_cli";
+	return "api_key";
+}
+
+/**
+ * Whether the local-CLI setup screen lets the user connect.
+ */
+export function canContinueLocalCliSetup(
+	_cli: ProviderLocalCli | undefined,
+	_status: LocalCliStatus | undefined,
+): boolean {
+	// The probe only looks on PATH, while the runtime also accepts an explicit
+	// pathToClaudeCodeExecutable and a bundled platform binary, and Codex falls
+	// back through `npx`. A PATH miss therefore means "not on PATH", not
+	// "unusable", so the screen reports it without blocking — a provider that
+	// really cannot start says so on the first turn, in its own words.
+	return true;
+}
+
 export function getMainMenuOptions(options?: {
 	isClinePassEnabled?: boolean;
 }): MenuOption[] {
@@ -174,7 +209,7 @@ export function toProviderEntry(provider: ProviderCatalogItem): ProviderEntry {
 		id: provider.id,
 		name: provider.name,
 		isOAuth: isOAuthProvider(provider.id),
-		isLocalAuth: isOpenAICodexCliProvider(provider.id),
+		isLocalAuth: isLocalAuthProvider(provider.id),
 		hasAuth:
 			Boolean(provider.apiKey) || provider.oauthAccessTokenPresent === true,
 		...(provider.capabilities ? { capabilities: provider.capabilities } : {}),

apps/cli/src/tui/views/onboarding/screens.tsx

@@ -2,10 +2,10 @@ import "opentui-spinner/react";
 import type { ScrollBoxRenderable } from "@opentui/core";
 import type { ReactNode } from "react";
 import { useEffect, useRef } from "react";
-import {
-	CODEX_CLI_INSTALL_URL,
-	type CodexCliStatus,
-} from "../../../utils/codex-cli";
+import type {
+	LocalCliStatus,
+	ProviderLocalCli,
+} from "../../../utils/local-cli";
 import {
 	ClineModelPicker,
 	type ClineModelPickerEntry,
@@ -25,6 +25,7 @@ import { FIELD_ORDER } from "./fields";
 import {
 	type ClinePassSubscriptionOption,
 	type ClinePassSubscriptionStatus,
+	canContinueLocalCliSetup,
 	type MenuOption,
 	THINKING_LEVELS,
 } from "./model";
@@ -362,18 +363,20 @@ export function OnboardingProviderConfigScreen(props: {
 	);
 }
 
-export function OnboardingCodexCliScreen(props: {
+export function OnboardingLocalCliScreen(props: {
 	activeProviderName: string;
 	checking: boolean;
+	cli?: ProviderLocalCli;
 	compact: boolean;
 	contentWidth: number;
 	mouse: MouseTrackerState;
-	status?: CodexCliStatus;
+	status?: LocalCliStatus;
 }) {
 	const defaultFg = useDefaultFg();
 	const colors = useOnboardingColors();
 	const installedStatus =
 		props.status?.installed === true ? props.status : undefined;
+	const canContinue = canContinueLocalCliSetup(props.cli, props.status);
 	return (
 		<OnboardingFrame
 			compact={props.compact}
@@ -386,31 +389,37 @@ export function OnboardingCodexCliScreen(props: {
 				{props.checking && (
 					<box flexDirection="row" gap={1}>
 						<spinner name="dots" color="gray" />
-						<text fg="gray">Checking for Codex CLI...</text>
+						<text fg="gray">Checking for {props.activeProviderName}...</text>
 					</box>
 				)}
 
 				{installedStatus && (
 					<box flexDirection="column" gap={1} alignItems="center">
-						<text fg={colors.success}>{"\u25cf"} Codex CLI installed</text>
+						<text fg={colors.success}>
+							{"\u25cf"} {props.activeProviderName} installed
+						</text>
 						<text fg="gray">{installedStatus.version}</text>
 					</box>
 				)}
 
-				{props.status && !props.status.installed && (
+				{props.cli && props.status && !props.status.installed && (
 					<box flexDirection="column" gap={1} width={props.contentWidth}>
-						<text fg="yellow">Codex CLI was not found</text>
+						<text fg="yellow">{props.activeProviderName} was not found</text>
 						<text fg="gray">{props.status.reason}</text>
-						<text fg="gray">Install Codex CLI from:</text>
-						<text fg={colors.accent} selectable>
-							{CODEX_CLI_INSTALL_URL}
-						</text>
+						{props.cli.docsUrl && (
+							<box flexDirection="column">
+								<text fg="gray">Install {props.activeProviderName} from:</text>
+								<text fg={colors.accent} selectable>
+									{props.cli.docsUrl}
+								</text>
+							</box>
+						)}
 					</box>
 				)}
 
 				<text fg="gray">
 					<em>
-						{installedStatus
+						{canContinue
 							? "Enter to continue, R to recheck, Esc to go back, Ctrl+C to exit"
 							: "R to recheck, Esc to go back, Ctrl+C to exit"}
 					</em>

apps/cli/src/tui/views/onboarding/view.tsx

@@ -7,10 +7,10 @@ import { getOAuthProviderLabel, type OnboardingResult } from "./model";
 import {
 	OnboardingClineModelScreen,
 	OnboardingClinePassSubscriptionScreen,
-	OnboardingCodexCliScreen,
 	OnboardingCustomModelIdScreen,
 	OnboardingDeviceCodeScreen,
 	OnboardingDoneScreen,
+	OnboardingLocalCliScreen,
 	OnboardingMainMenuScreen,
 	OnboardingModelPickerScreen,
 	OnboardingOAuthPendingScreen,
@@ -83,15 +83,16 @@ export function OnboardingView(props: OnboardingViewProps) {
 		);
 	}
 
-	if (state.step === "codex_cli_setup") {
+	if (state.step === "local_cli_setup" && state.localCli) {
 		return (
-			<OnboardingCodexCliScreen
+			<OnboardingLocalCliScreen
 				activeProviderName={state.activeProviderName}
-				checking={state.codexCliChecking}
+				checking={state.localCliChecking}
+				cli={state.localCli}
 				compact={compact}
 				contentWidth={contentWidth}
 				mouse={mouse}
-				status={state.codexCliStatus}
+				status={state.localCliStatus}
 			/>
 		);
 	}

apps/cli/src/utils/approval.ts

@@ -1,5 +1,9 @@
 import { createInterface } from "node:readline";
-import type { ToolApprovalRequest, ToolApprovalResult } from "@cline/shared";
+import {
+	type ToolApprovalRequest,
+	type ToolApprovalResult,
+	USER_REJECTED_TOOL_REASON,
+} from "@cline/shared";
 import { truncate } from "./helpers";
 import { c, getActiveCliSession, write } from "./output";
 
@@ -91,7 +95,7 @@ async function requestTerminalToolApproval(
 	}
 	return {
 		approved: false,
-		reason: `Tool "${request.toolName}" was denied by user`,
+		reason: USER_REJECTED_TOOL_REASON,
 	};
 }
 

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

@@ -18,20 +18,11 @@ import { getClineEnvironmentConfig } from "@cline/shared";
 
 export { getClineOrgIndividualInferenceSubscriptionMessage };
 
-export const CLI_PROMO_CODE = "";
-
 export function getCliSubscriptionUrl(): string {
-	if (!CLI_PROMO_CODE) {
-		return new URL(
-			`/dashboard/subscription?personal=true`,
-			getClineEnvironmentConfig().appBaseUrl,
-		).toString();
-	}
-
-	return `${new URL(
-		`/promo?code=${CLI_PROMO_CODE}&personal=true`,
+	return new URL(
+		`/dashboard/subscription?personal=true`,
 		getClineEnvironmentConfig().appBaseUrl,
-	).toString()}`;
+	).toString();
 }
 
 export function getCliNotSubscribedMessage(): string {

apps/cli/src/utils/codex-cli.ts

@@ -1,55 +0,0 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFile);
-
-export const OPENAI_CODEX_CLI_PROVIDER_ID = "openai-codex-cli";
-export const CODEX_CLI_INSTALL_URL = "https://developers.openai.com/codex/cli";
-
-export type CodexCliStatus =
-	| {
-			installed: true;
-			version: string;
-	  }
-	| {
-			installed: false;
-			reason: string;
-	  };
-
-export function isOpenAICodexCliProvider(providerId: string): boolean {
-	return providerId.trim().toLowerCase() === OPENAI_CODEX_CLI_PROVIDER_ID;
-}
-
-export async function checkCodexCliInstalled(): Promise<CodexCliStatus> {
-	try {
-		const result = await execFileAsync("codex", ["--version"], {
-			timeout: 3000,
-			windowsHide: true,
-		});
-		const version = (result.stdout || result.stderr).trim();
-		return {
-			installed: true,
-			version: version || "codex",
-		};
-	} catch (error) {
-		const details =
-			error && typeof error === "object"
-				? (error as { code?: unknown; message?: unknown })
-				: undefined;
-		const code = typeof details?.code === "string" ? details.code : "";
-		if (code === "ENOENT") {
-			return {
-				installed: false,
-				reason: "The codex executable was not found on PATH.",
-			};
-		}
-		const message =
-			typeof details?.message === "string"
-				? details.message
-				: "Could not run codex --version.";
-		return {
-			installed: false,
-			reason: message,
-		};
-	}
-}

apps/cli/src/utils/local-cli.test.ts

@@ -0,0 +1,30 @@
+import { isLocalAuthProvider } from "@cline/core";
+import { describe, expect, it } from "vitest";
+import { getLocalCliInfo } from "./local-cli";
+
+describe("local CLI providers", () => {
+	it("reads the CLI a local-auth provider borrows credentials from", () => {
+		expect(getLocalCliInfo("openai-codex-cli")).toEqual({
+			command: "codex",
+			docsUrl: "https://developers.openai.com/codex/cli",
+		});
+		expect(getLocalCliInfo("claude-code")).toEqual({
+			command: "claude",
+			docsUrl: "https://code.claude.com/docs/en/setup",
+		});
+	});
+
+	it("names no CLI for providers that authenticate with an API key", () => {
+		expect(getLocalCliInfo("anthropic")).toBeUndefined();
+		expect(getLocalCliInfo("openai-codex")).toBeUndefined();
+	});
+
+	// Routing is keyed off the capability alone, so a local-auth provider whose
+	// credentials come from somewhere unprobeable still reaches the local setup
+	// screen instead of an empty API-key form.
+	it("routes on the capability, not on knowing a CLI", () => {
+		expect(isLocalAuthProvider("claude-code")).toBe(true);
+		expect(isLocalAuthProvider("openai-codex-cli")).toBe(true);
+		expect(isLocalAuthProvider("anthropic")).toBe(false);
+	});
+});

apps/cli/src/utils/local-cli.ts

@@ -0,0 +1,59 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Llms } from "@cline/core";
+
+const execFileAsync = promisify(execFile);
+
+export type ProviderLocalCli = Llms.ProviderLocalCli;
+
+export type LocalCliStatus =
+	| {
+			installed: true;
+			version: string;
+	  }
+	| {
+			installed: false;
+			reason: string;
+	  };
+
+/**
+ * The CLI a `local-auth` provider borrows credentials from, as declared in
+ * the provider catalog. `undefined` for providers that name none — those are
+ * connected without a readiness check rather than probing a guessed command.
+ */
+export function getLocalCliInfo(
+	providerId: string,
+): ProviderLocalCli | undefined {
+	return Llms.resolveProviderLocalCli(providerId);
+}
+
+export async function checkLocalCliInstalled(
+	cli: ProviderLocalCli,
+): Promise<LocalCliStatus> {
+	try {
+		const result = await execFileAsync(cli.command, ["--version"], {
+			timeout: 3000,
+			windowsHide: true,
+		});
+		const version = (result.stdout || result.stderr).trim();
+		return {
+			installed: true,
+			version: version || cli.command,
+		};
+	} catch (error) {
+		const details = error as NodeJS.ErrnoException | undefined;
+		if (details?.code === "ENOENT") {
+			return {
+				installed: false,
+				reason: `The ${cli.command} executable was not found on PATH.`,
+			};
+		}
+		return {
+			installed: false,
+			reason:
+				error instanceof Error
+					? error.message
+					: `Could not run ${cli.command} --version.`,
+		};
+	}
+}

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

@@ -1,6 +1,7 @@
 import {
 	formatProviderOAuthApiKey,
 	getPersistedProviderApiKey as getCorePersistedProviderApiKey,
+	isLocalAuthProvider,
 	isOAuthProvider,
 	Llms,
 	type ProviderOAuthCredentials,
@@ -21,7 +22,7 @@ export function normalizeAuthProviderId(providerId: string): string {
 	return normalizeProviderId(normalized);
 }
 
-export { isOAuthProvider };
+export { isLocalAuthProvider, isOAuthProvider };
 
 export function toProviderApiKey(
 	providerId: string,

apps/cline-hub/src/server/desktop-commands.ts

@@ -264,6 +264,19 @@ export async function handleDesktopCommand(
 	) {
 		return [...ctx.sessions.values()].map(toWebviewSessionSummary);
 	}
+	if (command === "search_sessions") {
+		if (!ctx.uiClient) throw new Error("Hub is not connected");
+		const query = String(args?.query ?? "").trim();
+		if (!query) return [];
+		return await ctx.uiClient.searchSessions({
+			query,
+			limit: typeof args?.limit === "number" ? args.limit : 50,
+			workspaceRoot:
+				typeof args?.workspaceRoot === "string"
+					? args.workspaceRoot
+					: undefined,
+		});
+	}
 	if (command === "read_session_hooks") {
 		return [];
 	}

apps/cline-hub/src/webview/package.json

@@ -29,7 +29,7 @@
 		"embla-carousel-react": "^8.6.0",
 		"lucide-react": "^0.577.0",
 		"media-chrome": "^4.18.1",
-		"mermaid": "11.16.0",
+		"mermaid": "11.16.1",
 		"motion": "^12.38.0",
 		"nanoid": "^5.1.7",
 		"next-themes": "^0.4.6",

apps/cline-hub/src/webview/src/App.tsx

@@ -15,6 +15,7 @@ import {
 	PlugIcon,
 	RotateCcwIcon,
 	RssIcon,
+	SearchIcon,
 	ServerIcon,
 	SettingsIcon,
 	Trash2Icon,
@@ -63,6 +64,7 @@ import type {
 import { PageFrame, PageHeader } from "./components/views/page-layout";
 import type { CustomizationSection } from "./components/views/settings/extensions-view";
 import type { SettingsSection } from "./components/views/settings/settings-view";
+import { desktopClient } from "./lib/desktop-client";
 import { syncHubTheme } from "./lib/theme";
 import { postToHost } from "./vscode";
 
@@ -740,7 +742,18 @@ function SessionsView({
 	onRenameSession: (sessionId: string, title: string) => Promise<void> | void;
 	sessions: WebviewSessionSummary[];
 }) {
+	type SearchHit = {
+		sessionId: string;
+		documentId: string;
+		title: string;
+		workspaceRoot: string;
+		role: string;
+		snippet: string;
+	};
 	const [sessionFilters, setSessionFilters] = useState<string[]>([]);
+	const [searchQuery, setSearchQuery] = useState("");
+	const [searchHits, setSearchHits] = useState<SearchHit[]>([]);
+	const [searching, setSearching] = useState(false);
 	const [editingSessionId, setEditingSessionId] = useState<string | null>(null);
 	const [editingTitle, setEditingTitle] = useState("");
 	const [deleteSessionCandidate, setDeleteSessionCandidate] =
@@ -772,6 +785,34 @@ function SessionsView({
 		});
 	}, [sessions, sessionFilters, sortDirection]);
 
+	useEffect(() => {
+		const query = searchQuery.trim();
+		if (!query) {
+			setSearchHits([]);
+			setSearching(false);
+			return;
+		}
+		let cancelled = false;
+		setSearching(true);
+		const timer = setTimeout(() => {
+			void desktopClient
+				.invoke<SearchHit[]>("search_sessions", { query, limit: 50 })
+				.then((hits) => {
+					if (!cancelled) setSearchHits(hits);
+				})
+				.catch(() => {
+					if (!cancelled) setSearchHits([]);
+				})
+				.finally(() => {
+					if (!cancelled) setSearching(false);
+				});
+		}, 200);
+		return () => {
+			cancelled = true;
+			clearTimeout(timer);
+		};
+	}, [searchQuery]);
+
 	const startRenameSession = (session: WebviewSessionSummary) => {
 		setEditingSessionId(session.sessionId);
 		setEditingTitle(session.title || shortId(session.sessionId));
@@ -894,6 +935,52 @@ function SessionsView({
 					</>
 				}
 			/>
+			<div className="relative mb-3">
+				<SearchIcon className="pointer-events-none absolute left-3 top-2.5 size-4 text-muted-foreground" />
+				<Input
+					aria-label="Search all session history"
+					className="pl-9"
+					onChange={(event) => setSearchQuery(event.target.value)}
+					placeholder="Search messages, commands, errors, and file paths across all sessions…"
+					value={searchQuery}
+				/>
+			</div>
+
+			{searchQuery.trim() ? (
+				<section className="mb-4 overflow-hidden rounded-lg border bg-card">
+					{searching ? (
+						<p className="px-4 py-5 text-sm text-muted-foreground">
+							Searching…
+						</p>
+					) : searchHits.length === 0 ? (
+						<p className="px-4 py-5 text-sm text-muted-foreground">
+							No matching session history.
+						</p>
+					) : (
+						searchHits.map((hit) => (
+							<button
+								className="block w-full border-b px-4 py-3 text-left last:border-b-0 hover:bg-accent/40"
+								key={hit.documentId}
+								onClick={() => onOpenSession(hit.sessionId)}
+								type="button"
+							>
+								<div className="flex items-center gap-2 text-sm font-medium">
+									<span className="truncate">{hit.title}</span>
+									<span className="text-xs font-normal text-muted-foreground">
+										{hit.role}
+									</span>
+								</div>
+								<p className="mt-1 line-clamp-2 text-sm text-muted-foreground">
+									{hit.snippet}
+								</p>
+								<p className="mt-1 truncate text-xs text-muted-foreground">
+									{hit.workspaceRoot}
+								</p>
+							</button>
+						))
+					)}
+				</section>
+			) : null}
 
 			<section className="w-full min-w-0 overflow-x-auto">
 				<div className="grid w-full min-w-[56rem] grid-cols-[minmax(12rem,1.35fr)_minmax(7rem,0.85fr)_minmax(10rem,1.1fr)_5rem_5rem_4.5rem_5.5rem_2rem] gap-x-4 bg-muted/40 px-4 py-3 text-[15px] font-medium text-muted-foreground">

apps/cline-hub/src/webview/src/Chat.tsx

@@ -1,6 +1,9 @@
 "use client";
 
-import type { GeneratedMedia } from "@cline/shared/browser";
+import {
+	type GeneratedMedia,
+	USER_REJECTED_TOOL_REASON,
+} from "@cline/shared/browser";
 import { GeneratedMediaContent } from "@cline/ui";
 import {
 	CheckIcon,
@@ -1182,7 +1185,7 @@ export default function Chat({
 			type: "approval_response",
 			approvalId,
 			approved,
-			reason: approved ? "Approved in Cline Hub." : "Rejected in Cline Hub.",
+			reason: approved ? "Approved in Cline Hub." : USER_REJECTED_TOOL_REASON,
 		});
 		setStatus(approved ? "Approval sent." : "Rejection sent.");
 	};

apps/examples/desktop-app/CHANGELOG.md

@@ -1,5 +1,156 @@
 # Cline Desktop Changelog
 
+## 0.0.24
+
+- Fixed the live chat stream doubling text and dropping messages mid-turn. The sidecar had two pipes into the same emitter — the core session subscription and the Hub observer — and a session that streams without a local send first (a run already in flight when you open the task, a resumed run, a scheduled run) got every delta emitted twice. The core pipe is now the primary and the observer stands down while it is serving, for the whole busy run rather than a 5s window, so long commands, slow first tokens, and unanswered tool approvals no longer let a duplicate through. Separately, when the sidecar was replaced under a live webview (crash-respawn, Hub drain-and-replace, stale-sidecar swap) its stream counter restarted at 1 and the webview silently discarded everything until the new process counted past the old run — this dropped your own message bubbles and tool rows, not just assistant text, which is why rows appeared to vanish mid-turn and come back afterwards
+- Cline no longer stops silently mid-task when a model gets stuck repeating itself. The loop detector stops a run after 5 identical tool calls and the mistake tracker after 6 consecutive failures, but the desktop never registered a decision callback, so the run just ended and the composer went idle with no message. You are now asked how to continue — "Try a different approach" or "Stop this run" — and the guidance is steered into the running turn so the model knows why it was paused instead of repeating the same call
+- The `editor` tool's error message now names the file, says whether `old_text` was null or omitted, and states how to recover. Models that fill optional parameters with null (seen with kimi-k3) hit a terse "old_text is required" and re-sent the identical call until the loop detector stopped the run
+- Fixed your Cline Pass model selection being replaced when you start a new chat. Catalogs are discovery data, not validation — the bundled catalog can omit live Cline Pass models and refreshes can return partial lists, so a model missing from the catalog was treated as invalid and silently swapped for a default
+- Cline Desktop now has a custom title bar on Windows, with caption controls that follow the compact title-bar height in narrow windows and stay above overlays. The Windows taskbar icon was also updated
+- Token counts and costs now fill in for every session you can see. The sessions view only ever hydrated the four most recent rows, so every other row showed "-" and paging never asked for more; the visible page is now hydrated on demand, with reads capped and re-run when a session's status changes underneath them
+- Sessions imported from Claude Code, Codex, and opencode now say so in the chat, and their foreign history is summarized on the first resumed turn. Imported transcripts keep the source tool's own tool names and schemas, which a model continuing them may try to call — the summary runs once, the original transcript stays intact, and the "Thinking..." indicator reads "Summarizing the imported <tool> history..." while it happens
+- Fixed session history rendering empty when one session had many subagent or team-task children. Child rows always sort after the root that spawned them, so a single busy session could hide itself and every older session from the sidebar with no way to load more
+- Checkpoints no longer re-hash every untracked file before each message. Checkpoint creation rebuilt a throwaway git index each turn, so multi-GB untracked data blocked every message for seconds to minutes (~90s in one report on a cloud-synced Windows workspace). One snapshot index is now kept per session, so from the second turn the cost is roughly git process overhead. Snapshot contents are byte-identical to before
+- Commands that background a child process (`cmd &`, `nohup`, and the same from Git Bash) no longer hang until the timeout. The inherited stdio pipes stay open after the shell exits, so the completion event never arrived even though the command was done; these now settle with the real exit code and a note that background output is no longer captured
+- Typing an `@` mention from your home directory no longer indexes your entire home folder. That could take memory into the gigabytes and get the process killed; the home directory and filesystem root are now skipped entirely
+- Web search is now enabled by default outside YOLO mode, and tool settings fail closed if they cannot be loaded
+- Claude Code no longer asks for an API key it never reads. It authenticates from the local `claude` CLI's own credential store, but was reported as an API-key provider, so a keyless entry was refused and the workaround was to save a dummy key
+- Pasted credentials with invisible characters no longer persist corrupted. A BOM or zero-width character carried in from a copy-paste produced 401s indistinguishable from a wrong key; credential fields are now stripped of control and format characters on save
+- The model picker keeps section headers visible while you search. Cline Pass lists the same model in both the Subscribed and Free tiers, so flattening the sections during search produced two identical-looking rows
+- `apply_patch` "Add File" now refuses to overwrite an existing file instead of silently replacing it
+- Fixed session import paths resolving incorrectly on Windows
+- The desktop backend now starts off the command path, so startup no longer blocks the UI
+- The SDK can now connect to authenticated remote Hubs
+
+## 0.0.23
+
+- Agent Plugins are now discovered and run by the shared Hub. Packages under `~/.agents/plugins` are validated from their `plugin.json`, their valid Agent Skills become available to the agent, and their stdio / Streamable HTTP / SSE MCP servers start automatically. Settings → Customize lists Agent Plugins separately from Cline Plugins, with each plugin's description, badge, and contributed tools, and enable/disable is Hub-managed per plugin. Workspace `.agents/plugins` directories are intentionally ignored
+- The "Cline Hub was updated" dialog no longer appears on every launch and reconnect. The app no longer prompts about a Hub running the same core version it does — a desktop and CLI release cut from different commits bundle the same core but never share a build fingerprint, so anyone with both installed got a dialog whose "Update and restart" looped on "no app update available". The build-mismatch dialog now also waits until an app update is actually staged, and "Later" sticks across session switches, reloads, and relaunches instead of resurfacing every time. A Hub the app genuinely cannot talk to still warns every time
+- Signing in now shows the device confirmation code in the app while you wait on the browser, so you can match it against the code the browser asks you to confirm — in onboarding, Account settings, and the provider list
+- Voice input failures caused by provider setup — missing credentials, transcription config — now take you straight to voice settings instead of a toast you cannot act on. Genuine microphone permission failures still toast, with a clearer message
+- Fixed the scheduled-task report vanishing when a finished run's step collapsed
+- Fixed one wedged MCP server blocking the rest from shutting down, leaking their processes
+
+## 0.0.22
+
+- Import your history from Claude Code, Codex, and opencode. An Import button in the Sessions header (and a row in Settings → General) scans your local stores from all three tools and turns the conversations you pick into fully resumable Cline sessions. Sessions are grouped per tool with select-all and a search across title, folder, and first prompt; already-imported ones are shown as such so re-opening the dialog is safe. Imported sessions resume on your configured provider and model, not the source tool's. If you have history from any of these tools, onboarding now offers the import as a step
+- Runs of a schedule now fold into a single collapsible sidebar row named after the schedule, with its run count, instead of one row per run all carrying the same prompt title. Expanding lists them newest-first as "Run N" with the usual status dot, time, hover card, context menu, and delete; the group holding the active session opens on its own
+- Voice input now works on macOS. The app shipped without a microphone usage description or entitlement, so dictation failed silently
+- Web search is now on by default
+- The marketplace detail panel now opens on click rather than hover, with left-aligned content, a single "Learn more" link, and the selected entry staying open while you filter the list
+- When the Hub is older than the app, you are now offered a choice — replace it, with a count of the sessions that would be interrupted, or keep it running — instead of the app quietly working against stale code. Replacing drains the Hub first so in-flight turns finish
+- Editing and resending a message now works on sessions with no checkpoint history, such as imported ones, instead of failing with "No checkpoint found at or before run N"
+- Fixed tool calling being silently disabled for Dify, SAP AI Core, opencode, and Codex CLI models. Their catalog entries declare no capabilities, and the empty list was read as an authoritative denial that stripped every tool from the request
+- Fixed images being dropped from file reads on models whose capability list is empty
+- The message the model receives when you reject a tool call now names the tool and reads as your decision rather than an error
+- Refreshed the model catalog. Adds eight providers (Bothub, OpenReason, SenseNova (China), TokenRouter, Vancine, Volcengine Ark Coding Plan, above.dev, and klokintegration.se) and changes the resolved default model for 36 providers — most consequentially Anthropic, which now resolves to Claude Fable 5.1 instead of Claude Opus 5, with Amazon Bedrock, Vertex, OpenRouter, Kilo Gateway, DevPass, DigitalOcean, CrossModel, and Eden AI following. If you use a provider without pinning a model, expect a different default
+
+## 0.0.21
+
+- Marketplace is now a two-pane explorer: a browsable list on the left and full catalog metadata for the selected item on the right, with category tag filters that collapse behind a "more" toggle
+- Stopping a session now actually stops everything it started. Stop stays available while child agents are running, and an abort propagates to delegated subagents and to teammates instead of leaving orphaned work running in the background; cancelled teammate tasks now persist as cancelled
+- Fixed the ask-a-question tool's option text overflowing instead of wrapping
+- You can now drop file attachments anywhere over the chat input, not just on the small attach target
+- Cline provider models now refresh from the live catalog, so newly released models show up without waiting for an app update
+- Provider 401/403 responses are now classified as authentication errors rather than generic request failures, so a bad or missing API key is distinguishable from a real provider outage
+- Fixed Langfuse tracing never initializing in release builds — the minified bundle broke tracer detection, so telemetry worked in dev and silently did nothing in the shipped app. Also updated for AI SDK 7's telemetry API
+- Refreshed the model catalog. Adds TokenGo and Volcengine Ark, and updates model lists, pricing, and the resolved default model for ~36 providers (including Hugging Face, Mistral, OpenRouter, Together, NanoGPT, Requesty, Baseten, Cloudflare Workers AI, and DigitalOcean) — if you use one of those without pinning a model, you will get a different default
+
+## 0.0.20
+
+- Customize now separates Cline Plugins from Agent Plugins discovered by the Hub. Agent Plugin switches use Hub-managed enablement, contributed skills appear in the Skills inventory, and connected desktop views refresh when Hub settings change
+- Cline Desktop now ships on Windows: releases include a code-signed x64 installer, and installed apps auto-update on the same feed macOS does
+- Windows shell fixes: background processes (the sidecar, git) no longer pop visible console windows; updates now download in the background and install when you restart the app; the MCP settings path falls back to `USERPROFILE` when `HOME` is unset
+- Tool results that return images — screenshots from browser or MCP tools — now render as inline images you can click to expand, with a carousel for stepping through multiple images, instead of raw base64 text
+- Session search now covers your full indexed history. The sidebar search icon opens the command bar (Cmd/Ctrl+P) with server-ranked results, instead of a sidebar-local dialog that first loaded every session into memory
+- Onboarding has a new GitHub integration step
+- Fixed scheduled tasks disappearing after the app updated — hub-managed schedules were being wiped by cron reconciliation on restart
+- Agent-created schedules now live in one user-level home (`~/.cline/schedules`) instead of being scattered across whichever chat folder created them, and they now appear on the Schedules page
+- A finished scheduled session now surfaces its final answer: the completing step auto-expands, is labeled "Scheduled task completed" (or failed), and its summary renders as markdown
+- Suggested routine templates now ask for a specific final report, so a scheduled run ends with something readable
+- Providers no longer show as "Configured" on the strength of a leftover settings entry with no real credentials, and the badge now updates live after connecting or saving credentials instead of waiting for a remount
+- Fixed OpenAI Codex (ChatGPT subscription) sign-in silently dead-ending when callback port 1455 was already in use — it now fails immediately with an actionable error, and OAuth redirect errors surface instead of a confusing "Missing authorization code"
+- Codex and OCA sign-ins are no longer dropped when a token refresh hits a transient network failure or server error
+- Checkpoint restore now refuses to reset your workspace when commits were made after the checkpoint, instead of silently knocking them off the branch
+- Fixed an enabled-but-offline remote MCP server stalling session startup until the session was torn down
+- Global rules stored at `~/Cline/Rules` are now discovered (previously only `~/Documents/Cline/Rules`), fixing rules that never reached the model on WSL and headless installs
+- `apply_patch` now preserves a file's own CRLF line endings
+- The window title bar stays draggable across every view
+- Voice input's Live and After recording badges now have tooltips explaining them
+- Removed the box shadow from the chat message actions row
+- The hub no longer watches agenda spec directories while the todo tool is disabled, dropping an OS watch handle per known workspace
+
+## 0.0.19
+
+- Fixed the background Cline process ballooning in memory during long sessions — session status updates were carrying a full copy of the conversation transcript to every connected client, which on a multi-megabyte task could grow the process to tens of gigabytes. Status updates now carry only state (status, usage, model, workspace, checkpoint); the transcript is fetched on demand
+- Refreshed the model catalog. Adds seven providers (Agnes AI, Aixy, IteraCompute, LLM Tech, NeoSmith, Pendra, and Standard Compute) and updates model lists and pricing across providers. The resolved default model changes for ClinePass (now GLM 5.3), Z.ai, Hugging Face, evroc, LLM Gateway, NanoGPT, and Weights & Biases, so if you use one of those without pinning a model you will get a different default
+
+## 0.0.18
+
+- The sidebar is time-sorted again by default, with collapsible Pinned / Scheduled / Tasks sections and a one-click toggle to switch to project grouping (the old dropdown is gone). Scheduled sessions are marked with a clock icon, and the list starts taller and grows to fill the sidebar instead of stranding rows over empty space
+- Session rows now show a trash button on hover for quick deletion, with the same confirmation the row's context menu uses
+- Customize is now your installed inventory only. Browsing moved to a dedicated Marketplace page — one list across plugins, MCP servers, and skills with type-filter and tag chips — and the two pages link to each other from their headers and from sidebar sub-tabs
+- Schedule cards are now click targets: clicking a card anywhere outside its controls opens its details, the redundant eye button is gone, and the edit / run / pause / delete buttons are large enough to hit
+- Schedule details are one scrollable view instead of Overview/Runs tabs, showing the meta grid, the configuration, and the most recent runs with a "Show all N runs" expander
+- "Run now" now hands you into the session it starts
+- Scheduled and automation runs no longer render their internal `[SYSTEM]` steering messages as if you had typed them — a finished scheduled session reads as prompt, work summary, answer
+- Fixed opening a scheduled session while it runs leaving it stuck on the thinking shimmer until you switched away and back
+- Fixed installing plugins and MCP servers from the Marketplace failing with `Executable not found in $PATH: "cline"` — installs now run in-process and no longer require a Cline CLI on your machine
+- Fixed quitting the app beach-balling for several seconds
+- Cost estimates are no longer shown for subscription-billed providers (ClinePass, ChatGPT via Codex, and Claude Code), where an API-rate dollar figure read as a real charge on top of your subscription
+- Fixed hover cards flashing closed and reopening when clicked
+- The macOS DMG install window now has custom Cline artwork and layout
+- Credentials embedded in git remote URLs are now redacted from the workspace information sent to the model
+
+## 0.0.17
+
+- Plugins, MCP, Skills, Rules, Hooks, and Tools are now one Customize hub with tabbed sections and live counts. Catalog-backed tabs show what you have installed followed by an inline Browse section, so installing something from the catalog immediately appears above — the separate Marketplace page is gone
+- Redesigned the Models page: providers are grouped into Connected, Popular, and All with their auth kind and configuration status instead of per-row toggles. OAuth providers now offer a browser sign-in rather than an API key field, with a collapsed manual-key escape hatch where supported, and explicit Connect / Disconnect / Sign out actions
+- Voice input moved to its own Settings → Voice page that only offers connected transcription-capable providers and preselects a default model. The composer's microphone button now appears only once a voice model is configured
+- Sidebar sessions are always grouped by project, with pinned sessions leading each group and scheduled sessions marked by an inline clock. The Favorite action is now called Pin
+- New, Schedule, and Customize each got their own labeled row below the logo. New starts a fresh task and puts your cursor straight in the composer
+- Session search moved into a dialog behind the search icon in the logo row, and it now searches your full history instead of only the sessions already loaded in the sidebar
+- Added suggested schedule templates to the Schedule page
+- Add Provider opens a dialog instead of swapping out the page
+- Desktop notifications are now a single section under General, so the Event/Notify/Sound matrix no longer reads as a peer of settings like Dark mode
+- The agent's todo tool and the Agenda panel have been removed; scheduled tasks are unaffected
+- Fixed the provider list being unscrollable while a provider detail panel was open
+- Fixed a failed settings save leaving the Models page claiming a provider configuration that was never written to disk
+- Fixed Uninstall buttons collapsing to a broken square next to Install
+- Fixed unreadable selected text inside input fields
+- New files are now created with your platform's native line endings
+- Fixed the codebase search tool crashing the app on files containing a single enormous line
+- The hub's event log can no longer grow until it fills your disk
+
+## 0.0.16
+
+- The agent can now be handed off between Hub instances without losing work: a Hub that is restarting refuses new work while it finishes what it is running, and the app replays anything it missed while disconnected instead of dropping it
+- Fixed tool calling being silently disabled for custom OpenAI-Compatible models whose capability list was inferred from convenience flags like `supportsReasoning`
+- Refreshed the model catalog, which updates model lists and pricing across providers and changes the resolved default model for several of them (DeepSeek, Crof, CrossModel, Eden AI, Kilo, and NanoGPT)
+- The app now honors server-side feature flags, refreshing them when your account changes
+
+## 0.0.15
+
+- The app is now called Cline, renamed from Cline Code. Your settings, sessions, and credentials carry over untouched — only the name and icon change
+- Refreshed app icons and branding
+- Reskinned the first-run onboarding, with an interactive welcome graphic
+- Plugins, MCP servers, and Skills are now one Plugins hub with a dedicated Marketplace page
+- The composer's model selector now leads with Recommended and Free tiers (Subscribed and Free on ClinePass), labeled by display name with descriptions, instead of an alphabetized list of raw model ids. Provider settings show the same badges and descriptions
+- Agents can now create and manage durable todos and one-time or recurring schedules
+- Fixed checkpoint restore wedging permanently. Sessions that were never prompted — and persistence-only updates — reported a bogus "running" status, so anything gated on an active turn stayed blocked forever
+- Fixed "No sessions found" flashing while session history was still loading
+- Fixed the work summary undercounting elapsed time when thinking before a tool call attached to the answer instead of the run
+- Fixed the settings gear keeping its hover state while the Account screen is open
+- Fixed ClinePass not being recognized as OAuth-managed in the chat credential gate, which asked for credentials it already had
+- Fixed copying a user message bringing along its internal envelope
+- Fixed multi-line code blocks collapsing onto a single line
+- Image, voice, and other non-chat models are no longer offered in chat model pickers
+- Fixed `PreToolUse` hook `contextModification` never reaching the model, and `PostToolUse` hook output and `cancel` control being discarded
+- Fixed provider-executed tool activity — every tool the Claude Code provider runs inside its own session — being dropped instead of shown
+- PowerShell commands now fail fast on the first error instead of flooding output and still reporting success
+- Usage now displays the billed gateway cost
+- Refreshed the model catalog, which adds AMD, Arcee, Echo, Jalapeno, Kosmik, LLM Gateway, RunInfra, and SCNet as providers and updates model lists, pricing, and per-provider default models across the board
+
 ## 0.0.14
 
 - The app now posts native macOS notifications when a task finishes or needs your input, so you can leave Cline working in the background. Configure them under Settings → Notifications.

apps/examples/desktop-app/README.md

@@ -17,6 +17,38 @@ From `apps/examples/desktop-app/`:
 - `bun run package:desktop` - package the current OS desktop app into `dist/desktop/`
 - `bun run typecheck` - TypeScript check
 
+## Customizing the macOS Install Window
+
+The drag-to-Applications window is configured by `bundle.macOS.dmg` in
+[`src-tauri/tauri.conf.json`](./src-tauri/tauri.conf.json). Its artwork comes
+from the PNG sources in [`src-tauri/dmg/`](./src-tauri/dmg/); the
+`background.gen.tiff` Finder actually renders is a gitignored build artifact
+regenerated from them on every build.
+
+1. The current source artwork is `640x400`. Export `background.png` at 1x and
+   `background@2x.png` at 2x.
+2. Currently the app icons are centered at `(140, 200)` and
+   the Applications folder centered at `(500, 200)`. If updating artwork, update `appPosition`
+   and `applicationFolderPosition` to reposition the app icons.
+3. Build with `bun run build:binary`. Before compiling, the build validates
+   both PNG dimensions, combines them with `tiffutil` into the Retina-aware
+   `src-tauri/dmg/background.gen.tiff`, and verifies the TIFF contains the
+   expected 1x and 2x representations. Run `bun run dmg:background` to do just
+   that step, e.g. to sanity-check new artwork without a full build. The DMG
+   is written beneath `src-tauri/target/release/bundle/dmg/`.
+
+Run `bun run test:dmg-background` for the cross-platform checks covering the
+committed PNG dimensions and TIFF validation logic.
+
+The configured `640x432` Finder window is intentionally 32 points taller than
+the `640x400` background. That extra height matches the Finder chrome in the
+currently verified packaged layout; re-check it after material macOS or Finder
+changes. The project deliberately uses a multi-resolution TIFF even though
+Tauri's documented background formats are PNG, JPG, and GIF: Finder renders
+both the 1x and 2x representations from a single background file. Re-check the
+packaged DMG after upgrading Tauri in case its background validation changes.
+
+
 ## Login Shell PATH Resolution
 
 Apps launched from Finder/the Dock inherit launchd's minimal `PATH`

apps/examples/desktop-app/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cline/code",
-	"version": "0.0.14",
+	"version": "0.0.24",
 	"private": true,
 	"scripts": {
 		"build:ui": "bun -F @cline/ui build",
@@ -15,6 +15,8 @@
 		"build:sidecar": "mkdir -p dist/sidecar && bun build ./sidecar/index.ts --outfile ./dist/sidecar/index.js --target bun",
 		"build:sidecar:bin": "bun run scripts/build-sidecar-bin.ts",
 		"build:binary": "tauri build",
+		"dmg:background": "bun run scripts/dmg-background.ts",
+		"test:dmg-background": "bun test scripts/dmg-background.test.ts",
 		"package": "bun run package:desktop",
 		"package:desktop": "bun run scripts/package-desktop.ts",
 		"package:desktop:mac": "bun run scripts/package-desktop.ts --platform mac",
@@ -33,10 +35,10 @@
 		"@cline/llms": "workspace:*",
 		"@cline/shared": "workspace:*",
 		"@cline/ui": "workspace:*",
-		"@pierre/diffs": "^1.3.0",
 		"@fontsource-variable/geist-mono": "^5.2.8",
 		"@fontsource-variable/inter": "^5.2.8",
 		"@hookform/resolvers": "^3.9.1",
+		"@pierre/diffs": "^1.3.0",
 		"@radix-ui/react-accordion": "1.2.12",
 		"@radix-ui/react-alert-dialog": "1.1.15",
 		"@radix-ui/react-aspect-ratio": "1.1.8",
@@ -80,6 +82,7 @@
 		"next": "16.2.11",
 		"next-themes": "^0.4.6",
 		"pino": "^10.3.1",
+		"posthog-node": "^5.8.0",
 		"radix-ui": "^1.4.3",
 		"react": "19.2.4",
 		"react-day-picker": "9.13.2",

apps/examples/desktop-app/scripts/dev-headless.ts

@@ -15,9 +15,7 @@ async function reserveAvailablePort(): Promise<number> {
 				reject(new Error("Failed to reserve a sidecar port"));
 				return;
 			}
-			server.close((error) =>
-				error ? reject(error) : resolve(address.port),
-			);
+			server.close((error) => (error ? reject(error) : resolve(address.port)));
 		});
 	});
 }

apps/examples/desktop-app/scripts/dmg-background.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import {
+	parseTiffInfo,
+	readPngDimensions,
+	validateTiffRepresentations,
+} from "./dmg-background";
+
+const DMG_ROOT = path.resolve(import.meta.dir, "..", "src-tauri", "dmg");
+
+const EXPECTED_REPRESENTATIONS = [
+	{ width: 640, height: 400, dpiX: 72, dpiY: 72 },
+	{ width: 1280, height: 800, dpiX: 144, dpiY: 144 },
+];
+
+const TIFF_INFO = `Directory at 0x1
+  Image Width: 640 Image Length: 400
+  Resolution: 72, 72
+  Resolution Unit: pixels/inch
+Directory at 0x2
+  Image Width: 1280 Image Length: 800
+  Resolution: 144, 144
+  Resolution Unit: pixels/inch
+`;
+
+describe("parseTiffInfo", () => {
+	test("reads the dimensions and DPI of every TIFF representation", () => {
+		expect(parseTiffInfo(TIFF_INFO)).toEqual(EXPECTED_REPRESENTATIONS);
+	});
+
+	test("rejects representations without pixel-per-inch resolution", () => {
+		expect(() =>
+			parseTiffInfo(TIFF_INFO.replace("pixels/inch", "pixels/cm")),
+		).toThrow(/could not parse TIFF representation/);
+	});
+});
+
+describe("DMG source artwork", () => {
+	test("has the expected 1x and 2x dimensions", async () => {
+		const [dimensions1x, dimensions2x] = await Promise.all([
+			readPngDimensions(path.join(DMG_ROOT, "background.png")),
+			readPngDimensions(path.join(DMG_ROOT, "background@2x.png")),
+		]);
+
+		expect(dimensions1x).toEqual({ width: 640, height: 400 });
+		expect(dimensions2x).toEqual({ width: 1280, height: 800 });
+	});
+});
+
+describe("validateTiffRepresentations", () => {
+	test("accepts the expected representations", () => {
+		expect(() =>
+			validateTiffRepresentations(EXPECTED_REPRESENTATIONS),
+		).not.toThrow();
+	});
+
+	test("rejects the wrong number of representations", () => {
+		expect(() =>
+			validateTiffRepresentations(EXPECTED_REPRESENTATIONS.slice(0, 1)),
+		).toThrow(/exactly two image representations/);
+	});
+
+	test("rejects incorrect representation dimensions", () => {
+		expect(() =>
+			validateTiffRepresentations([
+				EXPECTED_REPRESENTATIONS[0],
+				{ ...EXPECTED_REPRESENTATIONS[1], width: 1279 },
+			]),
+		).toThrow(/must be 1280x800/);
+	});
+
+	test("rejects incorrect representation DPI", () => {
+		expect(() =>
+			validateTiffRepresentations([
+				{ ...EXPECTED_REPRESENTATIONS[0], dpiX: 73 },
+				EXPECTED_REPRESENTATIONS[1],
+			]),
+		).toThrow(/must be 72x72 DPI/);
+	});
+});

apps/examples/desktop-app/scripts/dmg-background.ts

@@ -0,0 +1,175 @@
+import { copyFile, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { $ } from "bun";
+
+type Dimensions = {
+	width: number;
+	height: number;
+};
+
+type TiffRepresentation = Dimensions & {
+	dpiX: number;
+	dpiY: number;
+};
+
+const APP_ROOT = path.resolve(import.meta.dir, "..");
+const DMG_ROOT = path.join(APP_ROOT, "src-tauri", "dmg");
+const BACKGROUND_1X = path.join(DMG_ROOT, "background.png");
+const BACKGROUND_2X = path.join(DMG_ROOT, "background@2x.png");
+// Gitignored build artifact; only the PNG sources are committed.
+const BACKGROUND_TIFF = path.join(DMG_ROOT, "background.gen.tiff");
+
+const EXPECTED_1X = { width: 640, height: 400 };
+const EXPECTED_2X = { width: 1280, height: 800 };
+const EXPECTED_TIFF_REPRESENTATIONS: TiffRepresentation[] = [
+	{ ...EXPECTED_1X, dpiX: 72, dpiY: 72 },
+	{ ...EXPECTED_2X, dpiX: 144, dpiY: 144 },
+];
+
+const PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+
+// PNG stores its big-endian width and height in the fixed IHDR fields at
+// byte offsets 16 and 20, so dimensions can be checked without an image library.
+export const readPngDimensions = async (
+	filePath: string,
+): Promise<Dimensions> => {
+	const contents = await readFile(filePath);
+	const hasPngSignature = PNG_SIGNATURE.every(
+		(byte, index) => contents[index] === byte,
+	);
+	if (
+		contents.length < 24 ||
+		!hasPngSignature ||
+		contents.toString("ascii", 12, 16) !== "IHDR"
+	) {
+		throw new Error(`${filePath} is not a valid PNG with an IHDR header`);
+	}
+
+	return {
+		width: contents.readUInt32BE(16),
+		height: contents.readUInt32BE(20),
+	};
+};
+
+const assertDimensions = (
+	label: string,
+	actual: Dimensions,
+	expected: Dimensions,
+): void => {
+	if (actual.width !== expected.width || actual.height !== expected.height) {
+		throw new Error(
+			`${label} must be ${expected.width}x${expected.height}, got ${actual.width}x${actual.height}`,
+		);
+	}
+};
+
+// tiffutil prints one "Directory at ..." block for each image representation
+// embedded in the TIFF.
+export const parseTiffInfo = (output: string): TiffRepresentation[] =>
+	output
+		.split(/(?=Directory at )/)
+		.filter((block) => block.startsWith("Directory at "))
+		.map((block) => {
+			const dimensions = block.match(
+				/Image Width:\s*(\d+)\s+Image Length:\s*(\d+)/,
+			);
+			const resolution = block.match(/Resolution:\s*([\d.]+),\s*([\d.]+)/);
+			if (
+				!dimensions ||
+				!resolution ||
+				!block.includes("Resolution Unit: pixels/inch")
+			) {
+				throw new Error(`could not parse TIFF representation:\n${block}`);
+			}
+
+			return {
+				width: Number(dimensions[1]),
+				height: Number(dimensions[2]),
+				dpiX: Number(resolution[1]),
+				dpiY: Number(resolution[2]),
+			};
+		});
+
+export const validateTiffRepresentations = (
+	representations: TiffRepresentation[],
+	label = "TIFF",
+): void => {
+	const sortedRepresentations = [...representations].sort(
+		(left, right) => left.width - right.width,
+	);
+
+	if (sortedRepresentations.length !== EXPECTED_TIFF_REPRESENTATIONS.length) {
+		throw new Error(
+			`${label} must contain exactly two image representations, got ${sortedRepresentations.length}`,
+		);
+	}
+
+	for (const [index, expected] of EXPECTED_TIFF_REPRESENTATIONS.entries()) {
+		const actual = sortedRepresentations[index];
+		assertDimensions(`${label} representation ${index + 1}`, actual, expected);
+		if (actual.dpiX !== expected.dpiX || actual.dpiY !== expected.dpiY) {
+			throw new Error(
+				`${label} representation ${index + 1} must be ${expected.dpiX}x${expected.dpiY} DPI, got ${actual.dpiX}x${actual.dpiY} DPI`,
+			);
+		}
+	}
+};
+
+const assertTiffRepresentations = async (filePath: string): Promise<void> => {
+	const representations = parseTiffInfo(
+		await $`tiffutil -info ${filePath}`.quiet().text(),
+	);
+	validateTiffRepresentations(representations, filePath);
+};
+
+const assertSourceDimensions = async (): Promise<void> => {
+	const [dimensions1x, dimensions2x] = await Promise.all([
+		readPngDimensions(BACKGROUND_1X),
+		readPngDimensions(BACKGROUND_2X),
+	]);
+	assertDimensions("background.png", dimensions1x, EXPECTED_1X);
+	assertDimensions("background@2x.png", dimensions2x, EXPECTED_2X);
+};
+
+const generateTiff = async (outputPath: string): Promise<void> => {
+	// Finder's .DS_Store references one background file. A multi-representation
+	// TIFF lets AppKit select the 1x or 2x bitmap without relying on it to discover
+	// a separate @2x companion beside that referenced file.
+	await $`tiffutil -cathidpicheck ${BACKGROUND_1X} ${BACKGROUND_2X} -out ${outputPath}`.quiet();
+	await assertTiffRepresentations(outputPath);
+};
+
+const main = async (): Promise<void> => {
+	if (process.argv.length > 2) {
+		throw new Error("usage: bun run dmg:background");
+	}
+	if (process.platform !== "darwin") {
+		// Runs from beforeBuildCommand on every platform, but only macOS builds
+		// bundle a DMG and only macOS ships tiffutil.
+		console.log("Skipping DMG background generation on non-macOS host.");
+		return;
+	}
+
+	await assertSourceDimensions();
+	// Generate and validate in scratch space so the configured build artifact is
+	// replaced only after tiffutil has produced a complete, verified TIFF.
+	const scratchRoot = await mkdtemp(
+		path.join(tmpdir(), "cline-dmg-background-"),
+	);
+	const generatedTiff = path.join(scratchRoot, "background.tiff");
+	try {
+		await generateTiff(generatedTiff);
+		await copyFile(generatedTiff, BACKGROUND_TIFF);
+		console.log(`Generated ${path.relative(APP_ROOT, BACKGROUND_TIFF)}.`);
+	} finally {
+		await rm(scratchRoot, { force: true, recursive: true });
+	}
+};
+
+if (import.meta.main) {
+	main().catch((error: unknown) => {
+		console.error(error instanceof Error ? error.message : error);
+		process.exitCode = 1;
+	});
+}

apps/examples/desktop-app/scripts/generate-update-manifest.test.ts

@@ -77,6 +77,66 @@ describe("buildUpdateManifest", () => {
 		expect(Object.keys(manifest.platforms)).toHaveLength(2);
 	});
 
+	test("maps a Windows NSIS setup artifact to windows-x86_64", () => {
+		const dir = makeUniversalArtifactDir();
+		writeFileSync(path.join(dir, "Cline-Code_0.1.0_x64-setup.exe"), "nsis");
+		writeFileSync(
+			path.join(dir, "Cline-Code_0.1.0_x64-setup.exe.sig"),
+			"sig-windows-x64\n",
+		);
+		const manifest = buildUpdateManifest({
+			version: "0.1.0",
+			tag: "desktop-v0.1.0",
+			dir,
+			repo: "cline/cline",
+			notes: "notes",
+			pubDate: "2026-07-21T00:00:00.000Z",
+		});
+
+		expect(manifest.platforms["windows-x86_64"]).toEqual({
+			signature: "sig-windows-x64",
+			url: "https://github.com/cline/cline/releases/download/desktop-v0.1.0/Cline-Code_0.1.0_x64-setup.exe",
+		});
+		// darwin entries from the universal artifact are unaffected.
+		expect(Object.keys(manifest.platforms).sort()).toEqual([
+			"darwin-aarch64",
+			"darwin-x86_64",
+			"windows-x86_64",
+		]);
+	});
+
+	test("ignores non-updater exe files without a setup arch suffix", () => {
+		const dir = makeUniversalArtifactDir();
+		writeFileSync(path.join(dir, "Cline-Code_0.1.0_x64.exe"), "exe");
+		const manifest = buildUpdateManifest({
+			version: "0.1.0",
+			tag: "desktop-v0.1.0",
+			dir,
+			repo: "cline/cline",
+			notes: "notes",
+			pubDate: "2026-07-21T00:00:00.000Z",
+		});
+		expect(Object.keys(manifest.platforms).sort()).toEqual([
+			"darwin-aarch64",
+			"darwin-x86_64",
+		]);
+	});
+
+	test("throws when a Windows setup artifact is missing its signature", () => {
+		const dir = makeUniversalArtifactDir();
+		writeFileSync(path.join(dir, "Cline-Code_0.1.0_x64-setup.exe"), "nsis");
+		expect(() =>
+			buildUpdateManifest({
+				version: "0.1.0",
+				tag: "desktop-v0.1.0",
+				dir,
+				repo: "cline/cline",
+				notes: "notes",
+				pubDate: "2026-07-21T00:00:00.000Z",
+			}),
+		).toThrow();
+	});
+
 	test("throws when universal and per-arch artifacts claim the same platform", () => {
 		const dir = makePerArchArtifactDir();
 		writeFileSync(

apps/examples/desktop-app/scripts/generate-update-manifest.ts

@@ -24,17 +24,25 @@ export type UpdateManifest = {
 	platforms: Record<string, UpdaterPlatformEntry>;
 };
 
-// Maps the arch token embedded in artifact file names (see the "Collect
+// Maps the arch token embedded in macOS artifact file names (see the "Collect
 // artifacts" workflow step) to the platform keys the Tauri updater requests.
 // A universal (fat) bundle serves both macOS architectures: each slice of the
 // installed app requests its own compile-time arch key at runtime, and both
 // keys point at the same artifact and signature.
-const PLATFORM_KEYS_BY_ARCH_SUFFIX: Record<string, string[]> = {
+const MACOS_PLATFORM_KEYS_BY_ARCH_SUFFIX: Record<string, string[]> = {
 	aarch64: ["darwin-aarch64"],
 	x86_64: ["darwin-x86_64"],
 	universal: ["darwin-aarch64", "darwin-x86_64"],
 };
 
+// On Windows the updater artifact is the NSIS installer itself
+// (createUpdaterArtifacts signs the setup exe with the updater key), named
+// `<Product>_<version>_<arch>-setup.exe` by the Tauri bundler.
+const WINDOWS_PLATFORM_KEYS_BY_ARCH_SUFFIX: Record<string, string[]> = {
+	x64: ["windows-x86_64"],
+	arm64: ["windows-aarch64"],
+};
+
 const getArgValue = (args: string[], name: string): string | undefined => {
 	const index = args.indexOf(name);
 	if (index >= 0 && args[index + 1] && !args[index + 1].startsWith("--")) {
@@ -45,13 +53,22 @@ const getArgValue = (args: string[], name: string): string | undefined => {
 	return inline?.slice(prefix.length);
 };
 
-const archOfUpdaterArtifact = (fileName: string): string | undefined => {
-	if (!fileName.endsWith(".app.tar.gz")) {
-		return undefined;
+const platformKeysOfUpdaterArtifact = (
+	fileName: string,
+): string[] | undefined => {
+	if (fileName.endsWith(".app.tar.gz")) {
+		const arch = Object.keys(MACOS_PLATFORM_KEYS_BY_ARCH_SUFFIX).find(
+			(candidate) => fileName.includes(`_${candidate}`),
+		);
+		return arch ? MACOS_PLATFORM_KEYS_BY_ARCH_SUFFIX[arch] : undefined;
 	}
-	return Object.keys(PLATFORM_KEYS_BY_ARCH_SUFFIX).find((arch) =>
-		fileName.includes(`_${arch}`),
-	);
+	if (fileName.endsWith("-setup.exe")) {
+		const arch = Object.keys(WINDOWS_PLATFORM_KEYS_BY_ARCH_SUFFIX).find(
+			(candidate) => fileName.endsWith(`_${candidate}-setup.exe`),
+		);
+		return arch ? WINDOWS_PLATFORM_KEYS_BY_ARCH_SUFFIX[arch] : undefined;
+	}
+	return undefined;
 };
 
 export const buildUpdateManifest = (options: {
@@ -65,8 +82,8 @@ export const buildUpdateManifest = (options: {
 	const platforms: Record<string, UpdaterPlatformEntry> = {};
 
 	for (const fileName of readdirSync(options.dir).sort()) {
-		const arch = archOfUpdaterArtifact(fileName);
-		if (!arch) {
+		const platformKeys = platformKeysOfUpdaterArtifact(fileName);
+		if (!platformKeys) {
 			continue;
 		}
 		const signaturePath = path.join(options.dir, `${fileName}.sig`);
@@ -74,7 +91,7 @@ export const buildUpdateManifest = (options: {
 		if (!signature) {
 			throw new Error(`empty updater signature at ${signaturePath}`);
 		}
-		for (const platformKey of PLATFORM_KEYS_BY_ARCH_SUFFIX[arch]) {
+		for (const platformKey of platformKeys) {
 			if (platforms[platformKey]) {
 				throw new Error(
 					`multiple updater artifacts claim platform ${platformKey}; found ${fileName} after ${platforms[platformKey].url}`,
@@ -89,7 +106,7 @@ export const buildUpdateManifest = (options: {
 
 	if (Object.keys(platforms).length === 0) {
 		throw new Error(
-			`no updater artifacts (*.app.tar.gz with a known arch suffix) found in ${options.dir}`,
+			`no updater artifacts (*.app.tar.gz or *-setup.exe with a known arch suffix) found in ${options.dir}`,
 		);
 	}
 

apps/examples/desktop-app/scripts/tauri-sign-windows.ps1

@@ -0,0 +1,77 @@
+# Authenticode-signs one PE file with Azure Trusted Signing via jsign.
+#
+# Invoked by the Tauri bundler through `bundle > windows > signCommand` (the
+# desktop-publish workflow generates a config overlay pointing here), once per
+# binary it stages: the main app exe, the code-sidecar external binary, the
+# NSIS uninstaller, and the NSIS installer itself.
+#
+# Requirements (all provided by the desktop-publish Windows job):
+# - an azure/login OIDC session (jsign's token comes from `az account get-access-token`)
+# - AZURE_TRUSTED_SIGNING_ENDPOINT / _ACCOUNT_NAME / _CERTIFICATE_PROFILE env vars
+# - java on PATH (preinstalled on GitHub Windows runners)
+#
+# Mirrors the CLI pipeline (.github/actions/sign-windows-cli): same jsign
+# version and flags, same Microsoft timestamp service. Kept as a standalone
+# script so the signing behavior is reviewable in the repo rather than inlined
+# in a generated config string.
+
+param(
+  [Parameter(Mandatory = $true, Position = 0)]
+  [string] $Path
+)
+
+$ErrorActionPreference = "Stop"
+
+$jsignVersion = "7.5"
+$jsignSha256 = "602A51C3545A6DC4FB99BD2EA7152B26D1345916D0C93DDFBD5936CB735AF91C"
+
+$endpoint = $env:AZURE_TRUSTED_SIGNING_ENDPOINT
+$account = $env:AZURE_TRUSTED_SIGNING_ACCOUNT_NAME
+$certProfile = $env:AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE
+if (-not $endpoint -or -not $account -or -not $certProfile) {
+  throw "Azure Trusted Signing env vars are not set (AZURE_TRUSTED_SIGNING_ENDPOINT/_ACCOUNT_NAME/_CERTIFICATE_PROFILE)"
+}
+
+$resolved = (Resolve-Path $Path).Path
+
+# jsign expects the endpoint host; tolerate the portal's trailing-slash form.
+$keystore = $endpoint -replace '^https://', '' -replace '/$', ''
+
+$jar = Join-Path $env:RUNNER_TEMP "jsign-$jsignVersion.jar"
+if (-not (Test-Path $jar)) {
+  Invoke-WebRequest -Uri "https://github.com/ebourg/jsign/releases/download/$jsignVersion/jsign-$jsignVersion.jar" -OutFile $jar
+}
+$actualHash = (Get-FileHash -Algorithm SHA256 $jar).Hash
+if ($actualHash -ne $jsignSha256) {
+  Remove-Item $jar -Force
+  throw "jsign jar checksum mismatch: expected $jsignSha256, got $actualHash"
+}
+
+# Short-lived bearer token from the azure/login OIDC session. Fetched per
+# invocation (signCommand runs once per file) so a long Rust build beforehand
+# can never leave us with an expired token. Passed to jsign via env, not argv.
+$env:JSIGN_STOREPASS = (az account get-access-token --resource https://codesigning.azure.net --query accessToken --output tsv)
+if (-not $env:JSIGN_STOREPASS) {
+  throw "failed to acquire an Azure access token; is azure/login configured on this job?"
+}
+
+Write-Host "Signing $resolved"
+java -jar $jar `
+  --storetype TRUSTEDSIGNING `
+  --keystore $keystore `
+  --storepass env:JSIGN_STOREPASS `
+  --alias "$account/$certProfile" `
+  --alg SHA-256 `
+  --tsaurl http://timestamp.acs.microsoft.com `
+  --tsmode RFC3161 `
+  --replace `
+  $resolved
+if ($LASTEXITCODE -ne 0) {
+  throw "jsign failed for $resolved (exit $LASTEXITCODE)"
+}
+
+$signature = Get-AuthenticodeSignature $resolved
+if ($signature.Status -ne "Valid") {
+  throw "signature verification failed for ${resolved}: $($signature.Status) - $($signature.StatusMessage)"
+}
+Write-Host "Signed and verified: $resolved ($($signature.SignerCertificate.Subject))"

apps/examples/desktop-app/sidecar/ARCHITECTURE.md

@@ -16,6 +16,7 @@ sidecar/
 ├── index.ts              # Entry point: starts HTTP+WS server
 ├── server.ts             # Bun HTTP server + WebSocket handlers
 ├── context.ts            # SidecarContext type and factory
+├── client-context.ts     # Desktop client/account identity for shared telemetry
 ├── commands.ts           # Command router
 ├── chat-session.ts       # Shared-Hub chat session adapter
 ├── session-data/         # Shared discovery, messages, artifacts, search helpers
@@ -81,6 +82,15 @@ The compiled sidecar also recognizes Core's Hub-daemon launch mode. This lets
 the desktop start the same detached Hub when no CLI process has started it yet.
 Startup discovery and locking ensure concurrent clients converge on one Hub.
 
+Every create, restart, fork, and restore also attaches the serializable Desktop
+`ExtensionContext.client` and current `ExtensionContext.user`. Core forwards
+that context across the Hub transport and scopes the daemon-owned telemetry
+service to the originating surface. This keeps lifecycle events centralized in
+Core while reporting Desktop dimensions (`cline_type: "desktop"`, `platform:
+"Cline Desktop"`, and the Desktop app version) and the current account and
+organization. The shared Hub telemetry singleton is never mutated per session,
+so concurrent CLI and Desktop tasks retain their own attribution.
+
 ### 2. Tool Approval — Client-Owned Promise Resolution
 
 The shared Hub routes approval requests back to the client that created the

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

@@ -13,6 +13,8 @@ import { materializeUserFiles } from "./attachments";
 import {
 	buildSessionConnectionUpdate,
 	consumeWorkspaceMetadata,
+	createDesktopMistakeLimitPrompt,
+	createDesktopMistakeRecovery,
 	handleChatSessionCommand,
 	hasProviderChanged,
 	mergeSessionConfig,
@@ -22,7 +24,11 @@ import {
 	shouldUpdateSessionConnection,
 	WORKSPACE_METADATA_PREWARM_TTL_MS,
 } from "./chat-session";
-import { handleCoreSessionEvent } from "./context";
+import {
+	handleCoreSessionEvent,
+	requestSidecarAskQuestion,
+	resolveSidecarAskQuestion,
+} from "./context";
 import type { SidecarContext } from "./types";
 
 describe("resolveDesktopSessionMode", () => {
@@ -195,25 +201,49 @@ describe("hasProviderChanged", () => {
 
 describe("pathless session starts", () => {
 	it("omits workspace paths and returns the SDK-resolved chat workspace", async () => {
-		const start = vi.fn(async (input: { config: Record<string, unknown> }) => {
-			expect(input.config).not.toHaveProperty("cwd");
-			expect(input.config).not.toHaveProperty("workspaceRoot");
-			expect(input.config).not.toHaveProperty("enableSpawnAgent");
-			expect(input.config).not.toHaveProperty("enableAgentTeams");
-			return {
-				sessionId: "session-pathless",
-				manifest: {
-					cwd: "/home/host/.cline/data/workspaces/chat",
-					workspace_root: "/home/host/.cline/data/workspaces/chat",
-				},
-				manifestPath: "/tmp/session-pathless.json",
-				messagesPath: "/tmp/session-pathless.messages.json",
-			};
-		});
+		const start = vi.fn(
+			async (input: {
+				config: Record<string, unknown>;
+				localRuntime?: {
+					extensionContext?: {
+						client?: Record<string, unknown>;
+						user?: Record<string, unknown>;
+					};
+				};
+			}) => {
+				expect(input.config).not.toHaveProperty("cwd");
+				expect(input.config).not.toHaveProperty("workspaceRoot");
+				expect(input.config).not.toHaveProperty("enableSpawnAgent");
+				expect(input.config).not.toHaveProperty("enableAgentTeams");
+				expect(input.localRuntime?.extensionContext?.client).toMatchObject({
+					name: "cline-desktop",
+					platform: "Cline Desktop",
+				});
+				expect(input.localRuntime?.extensionContext?.user).toEqual({
+					distinctId: "account-1",
+					accountId: "account-1",
+					organizationId: "org-1",
+				});
+				return {
+					sessionId: "session-pathless",
+					manifest: {
+						cwd: "/home/host/.cline/data/workspaces/chat",
+						workspace_root: "/home/host/.cline/data/workspaces/chat",
+					},
+					manifestPath: "/tmp/session-pathless.json",
+					messagesPath: "/tmp/session-pathless.messages.json",
+				};
+			},
+		);
 		const ctx = {
 			liveSessions: new Map(),
 			restoringWorkspacePaths: new Set(),
 			sessionManager: { start },
+			telemetryUser: {
+				distinctId: "account-1",
+				accountId: "account-1",
+				organizationId: "org-1",
+			},
 		} as unknown as SidecarContext;
 
 		const result = (await handleChatSessionCommand(ctx, {
@@ -308,6 +338,7 @@ describe("session forks", () => {
 				start,
 			},
 			streamIndices: new Map(),
+			coreStreamActivity: new Map(),
 			wsClients: new Set(),
 		} as unknown as SidecarContext;
 
@@ -429,6 +460,7 @@ describe("session forks", () => {
 				send,
 			},
 			streamIndices: new Map(),
+			coreStreamActivity: new Map(),
 			wsClients: new Set(),
 		} as unknown as SidecarContext;
 
@@ -462,7 +494,91 @@ describe("session forks", () => {
 		expect(ctx.restoringWorkspacePaths.size).toBe(0);
 	});
 
-	it("keeps a full-history fork on the current workspace without restoring", async () => {
+	it("forks trimmed messages without restoring when the edited run has no checkpoint", async () => {
+		const sourceSessionId = `source-imported-fork-${Date.now()}`;
+		const sourceMessages = [
+			{ role: "user" as const, content: "imported prompt" },
+			{ role: "assistant" as const, content: "imported response" },
+			{ role: "user" as const, content: "prompt to edit" },
+			{ role: "assistant" as const, content: "response to replace" },
+		];
+		const expectedMessages = sourceMessages.slice(0, 2);
+		const start = vi.fn(async () => ({ sessionId: "imported-fork" }));
+		const restore = vi.fn(async () => {
+			throw new Error("restore must not run without a checkpoint");
+		});
+		const readMessages = vi.fn(async () => expectedMessages);
+		const ctx = {
+			liveSessions: new Map([
+				[
+					sourceSessionId,
+					{
+						config: {
+							provider: "cline",
+							model: "anthropic/claude-sonnet-4.6",
+						},
+						messages: sourceMessages,
+						promptsInQueue: [],
+						busy: false,
+						startedAt: Date.now(),
+						status: "completed",
+					},
+				],
+			]),
+			restoringWorkspacePaths: new Set(),
+			sessionManager: {
+				get: vi.fn(async () => ({
+					sessionId: sourceSessionId,
+					source: "desktop",
+					status: "completed",
+					provider: "cline",
+					model: "anthropic/claude-sonnet-4.6",
+					cwd: "/workspace/project",
+					workspaceRoot: "/workspace/project",
+					metadata: {
+						importedFrom: { tool: "codex", sourceId: "cdx-1" },
+					},
+				})),
+				readMessages,
+				restore,
+				start,
+			},
+			streamIndices: new Map(),
+			coreStreamActivity: new Map(),
+			wsClients: new Set(),
+		} as unknown as SidecarContext;
+
+		const result = (await handleChatSessionCommand(ctx, {
+			action: "fork",
+			sessionId: sourceSessionId,
+			forkBeforeRunCount: 2,
+			config: {
+				provider: "cline",
+				model: "anthropic/claude-sonnet-4.6",
+			},
+		})) as { sessionId: string };
+
+		expect(restore).not.toHaveBeenCalled();
+		expect(start).toHaveBeenCalledWith(
+			expect.objectContaining({
+				initialMessages: expectedMessages,
+				sessionMetadata: expect.objectContaining({
+					fork: expect.objectContaining({
+						forkedFromSessionId: sourceSessionId,
+						beforeRunCount: 2,
+					}),
+				}),
+			}),
+		);
+		expect(result.sessionId).toBe("imported-fork");
+		expect(ctx.liveSessions.has(sourceSessionId)).toBe(false);
+		expect(ctx.liveSessions.get("imported-fork")?.messages).toEqual(
+			expectedMessages,
+		);
+		expect(ctx.restoringWorkspacePaths.size).toBe(0);
+	});
+
+	it("keeps a full-history fork on the current workspace and cancels source questions", async () => {
 		const sourceSessionId = `source-full-fork-${Date.now()}`;
 		const sourceMessages = [
 			{ role: "user" as const, content: "first prompt" },
@@ -504,9 +620,21 @@ describe("session forks", () => {
 				start,
 			},
 			streamIndices: new Map(),
+			coreStreamActivity: new Map(),
 			wsClients: new Set(),
+			pendingQuestions: new Map(),
 		} as unknown as SidecarContext;
 
+		const pendingDecision = createDesktopMistakeLimitPrompt(
+			ctx,
+			() => sourceSessionId,
+		)({
+			iteration: 5,
+			consecutiveMistakes: 6,
+			maxConsecutiveMistakes: 6,
+			reason: "tool_execution_failed",
+		});
+		expect(ctx.pendingQuestions.size).toBe(1);
 		await handleChatSessionCommand(ctx, {
 			action: "fork",
 			sessionId: sourceSessionId,
@@ -516,6 +644,8 @@ describe("session forks", () => {
 			},
 		});
 
+		await expect(pendingDecision).resolves.toMatchObject({ action: "stop" });
+		expect(ctx.pendingQuestions.size).toBe(0);
 		expect(restore).not.toHaveBeenCalled();
 		expect(start).toHaveBeenCalledWith(
 			expect.objectContaining({ initialMessages: sourceMessages }),
@@ -672,6 +802,7 @@ describe("session forks", () => {
 				]),
 				restoringWorkspacePaths: new Set(),
 				streamIndices: new Map(),
+				coreStreamActivity: new Map(),
 				wsClients: new Set(),
 				sessionManager: { restore },
 			} as unknown as SidecarContext;
@@ -795,6 +926,7 @@ describe("first-send connection updates", () => {
 			]),
 			restoringWorkspacePaths: new Set(),
 			streamIndices: new Map(),
+			coreStreamActivity: new Map(),
 			wsClients: new Set(),
 			sessionManager: {
 				readMessages,
@@ -1518,6 +1650,7 @@ Follow the desktop send workflow instructions.`,
 			liveSessions: new Map([[sessionId, session]]),
 			restoringWorkspacePaths: new Set(),
 			streamIndices: new Map(),
+			coreStreamActivity: new Map(),
 			wsClients: new Set(),
 			sessionManager: {
 				send,
@@ -1670,3 +1803,488 @@ Follow the desktop send workflow instructions.`,
 		);
 	});
 });
+
+describe("mistake-limit prompt", () => {
+	function createPromptContext() {
+		const send = vi.fn();
+		const steer = vi.fn(async () => undefined);
+		const ctx = {
+			wsClients: new Set([{ send }]),
+			streamIndices: new Map(),
+			coreStreamActivity: new Map(),
+			pendingQuestions: new Map(),
+			liveSessions: new Map(),
+			sessionManager: {
+				send: steer,
+				stop: vi.fn(async () => {}),
+				abort: vi.fn(async () => {}),
+			},
+		} as unknown as SidecarContext;
+		const readQuestionRequest = () => {
+			const raw = send.mock.calls
+				.map(
+					([encoded]) =>
+						JSON.parse(String(encoded)) as {
+							event: { name: string; payload: Record<string, unknown> };
+						},
+				)
+				.find((message) => message.event.name === "ask_question_requested");
+			return raw?.event.payload as
+				| {
+						requestId: string;
+						sessionId: string;
+						question: string;
+						options: string[];
+				  }
+				| undefined;
+		};
+		return { ctx, steer, readQuestionRequest };
+	}
+	const limitContext = {
+		iteration: 15,
+		consecutiveMistakes: 6,
+		maxConsecutiveMistakes: 6,
+		reason: "tool_execution_failed" as const,
+		details:
+			"Detected 5 consecutive identical calls to `editor`; stopping to avoid a loop.",
+	};
+
+	it("holds tool and model hooks until Continue has queued recovery guidance", async () => {
+		const { ctx, steer, readQuestionRequest } = createPromptContext();
+		let finishSteering!: () => void;
+		steer.mockImplementationOnce(
+			() =>
+				new Promise<undefined>((resolve) => {
+					finishSteering = () => resolve(undefined);
+				}),
+		);
+		const recovery = createDesktopMistakeRecovery(ctx, () => "session-1");
+		const decision = recovery.onConsecutiveMistakeLimitReached(limitContext);
+		expect(recovery.onConsecutiveMistakeLimitReached(limitContext)).toBe(
+			decision,
+		);
+		let released = false;
+		const waiting = Promise.all([
+			recovery.hooks.beforeModel(),
+			recovery.hooks.beforeTool(),
+			recovery.hooks.afterTool(),
+		]).then((results) => {
+			released = true;
+			return results;
+		});
+		await Promise.resolve();
+		expect(released).toBe(false);
+		expect(ctx.pendingQuestions.size).toBe(1);
+		resolveSidecarAskQuestion(
+			ctx,
+			readQuestionRequest()?.requestId ?? "",
+			"Try a different approach",
+		);
+		await Promise.resolve();
+		expect(steer).toHaveBeenCalledTimes(1);
+		expect(released).toBe(false);
+		finishSteering();
+		await expect(decision).resolves.toMatchObject({ action: "continue" });
+		await expect(waiting).resolves.toEqual([undefined, undefined, undefined]);
+		expect(released).toBe(true);
+		await expect(recovery.hooks.beforeModel()).resolves.toBeUndefined();
+	});
+
+	it("leaves ordinary questions alone when cancelling a mistake prompt", async () => {
+		const { ctx, readQuestionRequest } = createPromptContext();
+		const decision = createDesktopMistakeLimitPrompt(
+			ctx,
+			() => "session-1",
+		)(limitContext);
+		const mistakeRequestId = readQuestionRequest()?.requestId;
+		const normalQuestion = requestSidecarAskQuestion(
+			ctx,
+			"Which file?",
+			["a", "b"],
+			{ sessionId: "session-1", agentId: "desktop", iteration: 1 },
+		);
+		await handleChatSessionCommand(ctx, {
+			action: "abort",
+			sessionId: "session-1",
+		});
+		await expect(decision).resolves.toMatchObject({ action: "stop" });
+		expect(ctx.pendingQuestions.size).toBe(1);
+		const remaining = [...ctx.pendingQuestions.values()][0];
+		expect(remaining.item.requestId).not.toBe(mistakeRequestId);
+		resolveSidecarAskQuestion(ctx, remaining.item.requestId, "a");
+		await expect(normalQuestion).resolves.toBe("a");
+	});
+
+	it.each([
+		"answer",
+		"abort",
+	] as const)("releases waiting hooks with Stop on %s", async (action) => {
+		const { ctx, steer, readQuestionRequest } = createPromptContext();
+		const recovery = createDesktopMistakeRecovery(ctx, () => "session-1");
+		const decision = recovery.onConsecutiveMistakeLimitReached(limitContext);
+		const waiting = Promise.all([
+			recovery.hooks.beforeModel(),
+			recovery.hooks.beforeTool(),
+			recovery.hooks.afterTool(),
+		]);
+		if (action === "answer") {
+			resolveSidecarAskQuestion(
+				ctx,
+				readQuestionRequest()?.requestId ?? "",
+				"Stop this run",
+			);
+		} else {
+			await handleChatSessionCommand(ctx, {
+				action: "abort",
+				sessionId: "session-1",
+			});
+		}
+		await expect(decision).resolves.toMatchObject({ action: "stop" });
+		for (const control of await waiting)
+			expect(control).toMatchObject({ stop: true });
+		expect(ctx.pendingQuestions.size).toBe(0);
+		expect(steer).not.toHaveBeenCalled();
+	});
+
+	it("asks the active session's user instead of stopping silently", async () => {
+		const { ctx, readQuestionRequest } = createPromptContext();
+		// Session ids are only known after start() resolves; the prompt must
+		// read the id at prompt time, not at construction time.
+		let sessionId = "";
+		const decide = createDesktopMistakeLimitPrompt(ctx, () => sessionId);
+		sessionId = "session-late";
+
+		const decision = decide(limitContext);
+		const request = readQuestionRequest();
+		expect(request).toMatchObject({
+			sessionId: "session-late",
+			options: ["Try a different approach", "Stop this run"],
+		});
+		expect(request?.question).toContain("repeated mistakes or tool calls");
+		expect(request?.question).toContain("identical calls to `editor`");
+
+		expect(
+			resolveSidecarAskQuestion(ctx, request?.requestId ?? "", "Stop this run"),
+		).toBe(true);
+		await expect(decision).resolves.toEqual({
+			action: "stop",
+			reason: "stopped after mistake_limit_reached prompt",
+		});
+	});
+
+	it("delivers recovery guidance only through steering", async () => {
+		const { ctx, steer, readQuestionRequest } = createPromptContext();
+		const decide = createDesktopMistakeLimitPrompt(ctx, () => "session-1");
+
+		const decision = decide(limitContext);
+		const request = readQuestionRequest();
+		resolveSidecarAskQuestion(
+			ctx,
+			request?.requestId ?? "",
+			"Try a different approach",
+		);
+
+		const result = await decision;
+		expect(result).toEqual({ action: "continue" });
+		expect(steer).toHaveBeenCalledExactlyOnceWith({
+			sessionId: "session-1",
+			prompt: expect.stringContaining("Do not repeat the same call"),
+			delivery: "steer",
+		});
+		expect(steer).toHaveBeenCalledWith(
+			expect.objectContaining({
+				prompt: expect.stringContaining("identical calls to `editor`"),
+			}),
+		);
+	});
+
+	it.each([
+		"stop",
+		" STOP THIS RUN ",
+		"2",
+		"no",
+	])("treats the free-text answer %s as Stop, like the CLI", async (answer) => {
+		const { ctx, steer, readQuestionRequest } = createPromptContext();
+		const decision = createDesktopMistakeLimitPrompt(
+			ctx,
+			() => "session-1",
+		)(limitContext);
+		resolveSidecarAskQuestion(
+			ctx,
+			readQuestionRequest()?.requestId ?? "",
+			answer,
+		);
+		await expect(decision).resolves.toMatchObject({ action: "stop" });
+		expect(steer).not.toHaveBeenCalled();
+	});
+
+	it.each([
+		"rejected",
+		"unavailable",
+	])("stops waiting hooks when steering is %s", async (failure) => {
+		const { ctx, steer, readQuestionRequest } = createPromptContext();
+		if (failure === "rejected")
+			steer.mockRejectedValueOnce(new Error("Disconnected"));
+		else ctx.sessionManager = null;
+		const recovery = createDesktopMistakeRecovery(ctx, () => "session-1");
+		const decision = recovery.onConsecutiveMistakeLimitReached(limitContext);
+		const waiting = Promise.all([
+			recovery.hooks.beforeModel(),
+			recovery.hooks.beforeTool(),
+			recovery.hooks.afterTool(),
+		]);
+		resolveSidecarAskQuestion(
+			ctx,
+			readQuestionRequest()?.requestId ?? "",
+			"Try a different approach",
+		);
+		await expect(decision).resolves.toMatchObject({
+			action: "stop",
+			reason: expect.stringContaining("Could not send recovery guidance"),
+		});
+		for (const result of await waiting)
+			expect(result).toMatchObject({ stop: true });
+		expect(ctx.pendingQuestions.size).toBe(0);
+	});
+
+	it("passes free-text answers through as user guidance", async () => {
+		const { ctx, steer, readQuestionRequest } = createPromptContext();
+		const decide = createDesktopMistakeLimitPrompt(ctx, () => "session-1");
+		const decision = decide(limitContext);
+		resolveSidecarAskQuestion(
+			ctx,
+			readQuestionRequest()?.requestId ?? "",
+			"read the file first, then edit",
+		);
+		await expect(decision).resolves.toEqual({ action: "continue" });
+		expect(steer).toHaveBeenCalledExactlyOnceWith({
+			sessionId: "session-1",
+			prompt: expect.stringContaining(
+				"User guidance: read the file first, then edit",
+			),
+			delivery: "steer",
+		});
+	});
+
+	it("reuses Continue for already-started iterations and asks again for new mistakes", async () => {
+		const { ctx, steer } = createPromptContext();
+		ctx.liveSessions.set("session-1", {
+			config: {},
+			messages: [],
+			promptsInQueue: [],
+			busy: true,
+			startedAt: 0,
+			status: "running",
+		});
+		const startIteration = (iteration: number) =>
+			handleCoreSessionEvent(ctx, {
+				type: "agent_event",
+				payload: {
+					sessionId: "session-1",
+					event: { type: "iteration_start", iteration },
+				},
+			});
+		const answer = (value: string) => {
+			const pending = [...ctx.pendingQuestions.values()][0];
+			expect(pending).toBeDefined();
+			resolveSidecarAskQuestion(ctx, pending.item.requestId, value);
+		};
+		const decide = createDesktopMistakeLimitPrompt(ctx, () => "session-1");
+		startIteration(15);
+		const first = decide(limitContext);
+		// The model can advance while the client decision is pending.
+		startIteration(20);
+		// Do not extend the covered iterations while waiting for the hub's
+		// steering acknowledgement: a newer step may already have the guidance.
+		steer.mockImplementationOnce(async () => {
+			startIteration(21);
+			return undefined;
+		});
+		answer("Try a different approach");
+		await expect(first).resolves.toMatchObject({ action: "continue" });
+
+		// A batch can have many failures in one iteration, followed by more
+		// failures queued before the user answered. None needs another prompt.
+		for (const iteration of [
+			...Array<number>(20).fill(15),
+			16,
+			17,
+			18,
+			19,
+			20,
+		]) {
+			await expect(decide({ ...limitContext, iteration })).resolves.toEqual({
+				action: "continue",
+			});
+		}
+		expect(ctx.pendingQuestions.size).toBe(0);
+		expect(steer).toHaveBeenCalledTimes(1);
+
+		startIteration(21);
+		const next = decide({ ...limitContext, iteration: 21 });
+		answer("Try a different approach");
+		await expect(next).resolves.toMatchObject({ action: "continue" });
+		expect(steer).toHaveBeenCalledTimes(2);
+
+		// A new user run must not inherit the previous run's decision, even
+		// though its iteration numbers start over.
+		startIteration(1);
+		startIteration(5);
+		const newRun = decide({ ...limitContext, iteration: 5 });
+		answer("Stop this run");
+		await expect(newRun).resolves.toMatchObject({ action: "stop" });
+		expect(ctx.pendingQuestions.size).toBe(0);
+		expect(steer).toHaveBeenCalledTimes(2);
+	});
+
+	it("falls back to stopping when no session owns the question", async () => {
+		const { ctx, steer } = createPromptContext();
+		const decide = createDesktopMistakeLimitPrompt(ctx, () => "");
+		await expect(decide(limitContext)).resolves.toEqual({
+			action: "stop",
+			reason: `mistake_limit_reached: ${limitContext.details}`,
+		});
+		expect(steer).not.toHaveBeenCalled();
+	});
+
+	it("removes an aborted run's question and rejects late answers", async () => {
+		const { ctx, steer, readQuestionRequest } = createPromptContext();
+		const decide = createDesktopMistakeLimitPrompt(ctx, () => "session-1");
+		const decision = decide(limitContext);
+		const request = readQuestionRequest();
+		expect(ctx.pendingQuestions.size).toBe(1);
+		await handleChatSessionCommand(ctx, {
+			action: "abort",
+			sessionId: "session-1",
+		});
+		await expect(decision).resolves.toMatchObject({ action: "stop" });
+		expect(ctx.pendingQuestions.size).toBe(0);
+		expect(
+			resolveSidecarAskQuestion(
+				ctx,
+				request?.requestId ?? "",
+				"Try a different approach",
+			),
+		).toBe(false);
+		expect(steer).not.toHaveBeenCalled();
+	});
+
+	it.each([
+		"stop",
+		"abort",
+		"reset",
+	] as const)("cancels only the owning session's questions on %s", async (action) => {
+		const { ctx } = createPromptContext();
+		const decide = createDesktopMistakeLimitPrompt(ctx, () => "session-1");
+		const other = createDesktopMistakeLimitPrompt(
+			ctx,
+			() => "session-2",
+		)(limitContext);
+		const decision = decide(limitContext);
+		await handleChatSessionCommand(ctx, { action, sessionId: "session-1" });
+		await expect(decision).resolves.toMatchObject({ action: "stop" });
+		expect(
+			[...ctx.pendingQuestions.values()].map((p) => p.item.sessionId),
+		).toEqual(["session-2"]);
+		await handleChatSessionCommand(ctx, {
+			action: "abort",
+			sessionId: "session-2",
+		});
+		await other;
+		expect(ctx.pendingQuestions.size).toBe(0);
+	});
+
+	it("times out an unanswered question and removes it from polling", async () => {
+		vi.useFakeTimers();
+		try {
+			const { ctx, steer } = createPromptContext();
+			const decide = createDesktopMistakeLimitPrompt(ctx, () => "session-1");
+			const decision = decide(limitContext);
+			await vi.advanceTimersByTimeAsync(5 * 60_000);
+			await expect(decision).resolves.toMatchObject({ action: "stop" });
+			expect(ctx.pendingQuestions.size).toBe(0);
+			expect(steer).not.toHaveBeenCalled();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it.each([
+		"run",
+		"session",
+	])("cancels the question when the %s ends externally", async (kind) => {
+		const { ctx, steer, readQuestionRequest } = createPromptContext();
+		const decision = createDesktopMistakeLimitPrompt(
+			ctx,
+			() => "session-1",
+		)(limitContext);
+		const requestId = readQuestionRequest()?.requestId ?? "";
+		if (kind === "session")
+			handleCoreSessionEvent(ctx, {
+				type: "ended",
+				payload: { sessionId: "session-1", reason: "stopped", ts: Date.now() },
+			});
+		else
+			handleCoreSessionEvent(ctx, {
+				type: "agent_event",
+				payload: {
+					sessionId: "session-1",
+					event: {
+						type: "done",
+						reason: "aborted",
+						text: "",
+						iterations: 5,
+						usage: { inputTokens: 0, outputTokens: 0 },
+					},
+				},
+			});
+		await expect(decision).resolves.toMatchObject({ action: "stop" });
+		expect(ctx.pendingQuestions.size).toBe(0);
+		expect(
+			resolveSidecarAskQuestion(ctx, requestId, "Try a different approach"),
+		).toBe(false);
+		expect(steer).not.toHaveBeenCalled();
+	});
+
+	it("is wired into freshly started sessions as a local runtime option", async () => {
+		const start = vi.fn(
+			async (input: {
+				config: Record<string, unknown>;
+				localRuntime?: Record<string, unknown>;
+			}) => {
+				expect(input.config).not.toHaveProperty(
+					"onConsecutiveMistakeLimitReached",
+				);
+				expect(
+					typeof input.localRuntime?.onConsecutiveMistakeLimitReached,
+				).toBe("function");
+				expect(input.config).not.toHaveProperty("hooks");
+				expect(input.localRuntime?.hooks).toMatchObject({
+					beforeModel: expect.any(Function),
+					beforeTool: expect.any(Function),
+					afterTool: expect.any(Function),
+				});
+				return {
+					sessionId: "session-limit",
+					manifest: { cwd: "/tmp/ws", workspace_root: "/tmp/ws" },
+					manifestPath: "/tmp/session-limit.json",
+					messagesPath: "/tmp/session-limit.messages.json",
+				};
+			},
+		);
+		const ctx = {
+			liveSessions: new Map(),
+			restoringWorkspacePaths: new Set(),
+			sessionManager: { start },
+		} as unknown as SidecarContext;
+		await handleChatSessionCommand(ctx, {
+			action: "start",
+			config: {
+				provider: "cline",
+				model: "anthropic/claude-sonnet-4.6",
+				cwd: "/tmp/ws",
+			},
+		});
+		expect(start).toHaveBeenCalledTimes(1);
+	});
+});

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

@@ -8,10 +8,12 @@ import {
 	type ClineCoreStartConfig,
 	createSessionCompactionState,
 	createUserInstructionConfigService,
+	findCheckpointForRun,
 	getCoreBuiltinToolCatalog,
 	isSkillsToolAvailable,
 	projectSessionCompactionState,
 	readGlobalSettings,
+	readSessionCheckpointHistory,
 	type SessionCompactionState,
 	type SessionPendingPrompt,
 	type SessionRecord,
@@ -20,14 +22,27 @@ import {
 	trimMessagesBeforeUserRun,
 } from "@cline/core";
 import type { MessageWithMetadata } from "@cline/llms";
-import { buildClineSystemPrompt, formatUserCommandBlock } from "@cline/shared";
+import {
+	buildClineSystemPrompt,
+	type ConsecutiveMistakeLimitContext,
+	type ConsecutiveMistakeLimitDecision,
+	formatUserCommandBlock,
+} from "@cline/shared";
 import {
 	deleteMaterializedAttachments,
 	discardAllTrackedAttachments,
 	materializeUserFiles,
 	trackQueuedAttachments,
 } from "./attachments";
-import { emitChunk, nowMs, sendEvent } from "./context";
+import { createDesktopExtensionContext } from "./client-context";
+import {
+	cancelSidecarMistakeQuestions,
+	emitChunk,
+	forgetCorePipe,
+	nowMs,
+	requestSidecarAskQuestion,
+	sendEvent,
+} from "./context";
 import { readSessionManifest, sharedSessionDataDir } from "./paths";
 import { persistSessionMessages } from "./session-data/messages";
 import type {
@@ -399,7 +414,177 @@ function readPositiveInteger(value: unknown): number | undefined {
 	return undefined;
 }
 
-function buildCoreSessionConfig(config: JsonRecord): JsonRecord {
+type MistakeLimitDecider = (
+	context: ConsecutiveMistakeLimitContext,
+) => Promise<ConsecutiveMistakeLimitDecision>;
+
+const MISTAKE_LIMIT_CONTINUE_OPTION = "Try a different approach";
+const MISTAKE_LIMIT_STOP_OPTION = "Stop this run";
+const MISTAKE_LIMIT_DETAIL_MAX_CHARS = 600;
+
+/**
+ * Desktop counterpart of the CLI's mistake-limit prompt
+ * (apps/cli/src/runtime/interactive/mistakes.ts).
+ *
+ * When the core's loop detector or mistake tracker trips, it asks the client
+ * how to proceed. Without a decision callback the default is "stop", which
+ * reaches the webview as a plain aborted turn: indistinguishable from the
+ * user pressing Stop, with no explanation. A model stuck re-issuing the same
+ * failing tool call therefore looked like Cline randomly gave up mid-task.
+ * Route the decision through the existing ask-question channel instead so
+ * the user sees what went wrong and can choose.
+ *
+ * `getSessionId` is read at prompt time: for fresh starts the session id is
+ * only known after `manager.start()` resolves, and the webview matches the
+ * prompt to its active session by id.
+ */
+export function createDesktopMistakeLimitPrompt(
+	ctx: SidecarContext,
+	getSessionId: () => string,
+): MistakeLimitDecider {
+	return async (context) => {
+		const sessionId = getSessionId().trim();
+		const recovery = ctx.liveSessions.get(sessionId)?.mistakeRecovery;
+		if (
+			recovery?.continuedThroughIteration !== undefined &&
+			context.iteration <= recovery.continuedThroughIteration
+		) {
+			// The tracker serializes decisions, so old failures can arrive after
+			// Continue. The user has already answered for these in-flight steps.
+			return { action: "continue" };
+		}
+		const detail = context.details?.trim() ?? "";
+		const truncatedDetail =
+			detail.length > MISTAKE_LIMIT_DETAIL_MAX_CHARS
+				? `${detail.slice(0, MISTAKE_LIMIT_DETAIL_MAX_CHARS)}…`
+				: detail;
+		const question = [
+			"Cline detected repeated mistakes or tool calls and needs your guidance.",
+			truncatedDetail ? `Latest: ${truncatedDetail}` : "",
+			"How should Cline continue?",
+		]
+			.filter((line) => line.length > 0)
+			.join("\n");
+
+		let answer: string;
+		try {
+			answer = await requestSidecarAskQuestion(
+				ctx,
+				question,
+				[MISTAKE_LIMIT_CONTINUE_OPTION, MISTAKE_LIMIT_STOP_OPTION],
+				{
+					sessionId,
+					agentId: "desktop-mistake-limit",
+					iteration: context.iteration,
+				},
+			);
+		} catch (error) {
+			// Prompt timed out or the session was torn down: fall back to the
+			// core's default decision, but keep the reason so the stop is
+			// attributable.
+			ctx.logger?.log("Mistake-limit prompt unanswered; stopping run", {
+				sessionId,
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return {
+				action: "stop",
+				reason: `mistake_limit_reached: ${detail || context.reason}`,
+			};
+		}
+
+		const normalized = answer.trim().toLowerCase();
+		if (["2", "stop this run", "stop", "n", "no"].includes(normalized)) {
+			return {
+				action: "stop",
+				reason: "stopped after mistake_limit_reached prompt",
+			};
+		}
+		const customGuidance =
+			normalized.length > 0 &&
+			normalized !== "1" &&
+			normalized !== MISTAKE_LIMIT_CONTINUE_OPTION.toLowerCase()
+				? answer.trim()
+				: "";
+		const guidance = [
+			"The run reached the limit for repeated mistakes or tool calls.",
+			truncatedDetail ? `Latest: ${truncatedDetail}` : "",
+			"Do not repeat the same call. Re-check the tool's parameter requirements, fix the call, and try a different approach.",
+			customGuidance ? `User guidance: ${customGuidance}` : "",
+		]
+			.filter((line) => line.length > 0)
+			.join(" ");
+		// Use the existing steering queue so the running model receives the
+		// guidance, including any instructions entered in the desktop prompt.
+		const manager = ctx.sessionManager;
+		try {
+			if (!manager) throw new Error("Desktop session manager is unavailable");
+			const continuedThroughIteration = Math.max(
+				context.iteration,
+				recovery?.latestIteration ?? context.iteration,
+			);
+			await manager.send({ sessionId, prompt: guidance, delivery: "steer" });
+			if (recovery) {
+				recovery.continuedThroughIteration = continuedThroughIteration;
+			}
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			ctx.logger?.log("Failed to steer mistake-limit guidance", {
+				sessionId,
+				error: detail,
+			});
+			// Releasing the hooks without the guidance would resume the same
+			// failing loop. Only Continue after the steering request succeeds.
+			return {
+				action: "stop",
+				reason: `Could not send recovery guidance: ${detail}`,
+			};
+		}
+		// Steering already delivers the guidance; do not also append it via
+		// the mistake tracker's recovery-notice path.
+		return { action: "continue" };
+	};
+}
+
+export function createDesktopMistakeRecovery(
+	ctx: SidecarContext,
+	getSessionId: () => string,
+) {
+	const prompt = createDesktopMistakeLimitPrompt(ctx, getSessionId);
+	let pendingDecision: Promise<ConsecutiveMistakeLimitDecision> | undefined;
+	const waitForDecision = async () => {
+		const decision = await pendingDecision;
+		return decision?.action === "stop"
+			? { stop: true, reason: decision.reason }
+			: undefined;
+	};
+	return {
+		onConsecutiveMistakeLimitReached: (
+			context: ConsecutiveMistakeLimitContext,
+		) => {
+			if (!pendingDecision) {
+				pendingDecision = prompt(context).finally(() => {
+					pendingDecision = undefined;
+				});
+			}
+			return pendingDecision;
+		},
+		hooks: {
+			// The decision callback alone does not pause the SDK. These existing
+			// awaited hooks hold desktop runs at tool/model boundaries until the
+			// user answers. afterTool holds before the next iteration consumes
+			// the recovery guidance queued by the prompt's Continue action.
+			beforeModel: waitForDecision,
+			beforeTool: waitForDecision,
+			afterTool: waitForDecision,
+		},
+	};
+}
+
+function buildCoreSessionConfig(
+	config: JsonRecord,
+	telemetryUser?: SidecarContext["telemetryUser"],
+	mistakeRecovery?: ReturnType<typeof createDesktopMistakeRecovery>,
+): JsonRecord {
 	const rawWorkspaceRoot = config.workspaceRoot ?? config.workspace_root;
 	const workspaceRoot =
 		typeof rawWorkspaceRoot === "string" ? rawWorkspaceRoot.trim() : "";
@@ -442,6 +627,8 @@ function buildCoreSessionConfig(config: JsonRecord): JsonRecord {
 		checkpoint: { enabled: true },
 		sessions: config.sessions,
 		initialMessages: config.initialMessages,
+		extensionContext: createDesktopExtensionContext(telemetryUser),
+		...mistakeRecovery,
 	};
 }
 
@@ -672,8 +859,14 @@ async function handleStart(
 			: requestedSessionId
 				? (readPersistedChatMessages(requestedSessionId) ?? undefined)
 				: undefined;
+	// Resolved once start() returns; the mistake-limit prompt reads it lazily.
+	let startedSessionId = requestedSessionId;
 	const coreConfig: JsonRecord = {
-		...buildCoreSessionConfig(request.config),
+		...buildCoreSessionConfig(
+			request.config,
+			ctx.telemetryUser,
+			createDesktopMistakeRecovery(ctx, () => startedSessionId),
+		),
 		systemPrompt,
 		...(initialMessages ? { initialMessages } : {}),
 	};
@@ -695,6 +888,7 @@ async function handleStart(
 		toolPolicies: resolveToolPolicies(request.config),
 	});
 	const sessionId = startResult.sessionId;
+	startedSessionId = sessionId;
 	const workspaceRoot = startResult.manifest.workspace_root;
 	const cwd = startResult.manifest.cwd;
 	ctx.logger?.log("Desktop chat session started", { sessionId });
@@ -792,6 +986,7 @@ async function handleAttach(
 
 async function startRebuiltSession(
 	manager: ClineCore,
+	ctx: SidecarContext,
 	sessionId: string,
 	config: JsonRecord,
 	systemPrompt: string,
@@ -803,11 +998,15 @@ async function startRebuiltSession(
 		: undefined;
 	const restarted = await manager.start({
 		...splitCoreSessionConfig(
-			buildCoreSessionConfig({
-				...config,
-				sessionId,
-				systemPrompt,
-			}) as unknown as ClineCoreStartConfig,
+			buildCoreSessionConfig(
+				{
+					...config,
+					sessionId,
+					systemPrompt,
+				},
+				ctx.telemetryUser,
+				createDesktopMistakeRecovery(ctx, () => sessionId),
+			) as unknown as ClineCoreStartConfig,
 		),
 		source: SessionSource.DESKTOP,
 		interactive: true,
@@ -852,11 +1051,14 @@ async function rebuildSessionForProviderChange(
 			resolveSystemPrompt(nextConfig),
 		]);
 
+	cancelSidecarMistakeQuestions(ctx, sessionId, "Session provider changed");
 	await manager.stop(sessionId);
+	forgetCorePipe(ctx, sessionId);
 	let replacementStarted = false;
 	try {
 		await startRebuiltSession(
 			manager,
+			ctx,
 			sessionId,
 			nextConfig,
 			nextSystemPrompt,
@@ -875,9 +1077,11 @@ async function rebuildSessionForProviderChange(
 		try {
 			if (replacementStarted) {
 				await manager.stop(sessionId);
+				forgetCorePipe(ctx, sessionId);
 			}
 			await startRebuiltSession(
 				manager,
+				ctx,
 				sessionId,
 				previousConfig,
 				previousSystemPrompt,
@@ -1131,7 +1335,11 @@ async function handleStop(
 ): Promise<unknown> {
 	const sessionId = request.sessionId?.trim();
 	if (!sessionId) throw new Error("sessionId is required");
+	cancelSidecarMistakeQuestions(ctx, sessionId, "Session stopped");
 	await getSessionManager(ctx).stop(sessionId);
+	// stop() disposes the ClineCore subscription; the observer must be free to
+	// serve any later run another client starts on this session.
+	forgetCorePipe(ctx, sessionId);
 	const session = ctx.liveSessions.get(sessionId);
 	if (session) {
 		session.busy = false;
@@ -1146,6 +1354,7 @@ async function handleAbort(
 ): Promise<unknown> {
 	const sessionId = request.sessionId?.trim();
 	if (!sessionId) throw new Error("sessionId is required");
+	cancelSidecarMistakeQuestions(ctx, sessionId, "Run aborted");
 	await getSessionManager(ctx).abort(sessionId, "user_abort");
 	const session = ctx.liveSessions.get(sessionId);
 	if (session) {
@@ -1287,20 +1496,35 @@ async function handleForkUnlocked(
 		},
 	};
 	const systemPrompt = await resolveSystemPrompt(forkConfig);
+	// Assigned below once the forked session exists; read lazily by the prompt.
+	let newSessionId = "";
 	const startInput = {
 		...splitCoreSessionConfig(
-			buildCoreSessionConfig({
-				...forkConfig,
-				systemPrompt,
-			}) as unknown as ClineCoreStartConfig,
+			buildCoreSessionConfig(
+				{
+					...forkConfig,
+					systemPrompt,
+				},
+				ctx.telemetryUser,
+				createDesktopMistakeRecovery(ctx, () => newSessionId),
+			) as unknown as ClineCoreStartConfig,
 		),
 		source: SessionSource.DESKTOP,
 		interactive: true,
 		sessionMetadata: forkMetadata,
 		toolPolicies: resolveToolPolicies(forkConfig),
 	};
-	let newSessionId: string;
-	if (forkBeforeRunCount !== undefined) {
+	// Sessions without a checkpoint at or before the edited run (imported
+	// transcripts, checkpoints disabled) have no workspace state to roll back,
+	// so fork the trimmed messages onto the current workspace instead of
+	// failing the edit.
+	const canRestoreWorkspace =
+		forkBeforeRunCount !== undefined &&
+		findCheckpointForRun(
+			readSessionCheckpointHistory({ metadata: sourceMetadata }),
+			forkBeforeRunCount,
+		) !== undefined;
+	if (forkBeforeRunCount !== undefined && canRestoreWorkspace) {
 		const cwd =
 			restoreWorkspacePath ||
 			(typeof forkConfig.cwd === "string" && forkConfig.cwd.trim()) ||
@@ -1342,6 +1566,11 @@ async function handleForkUnlocked(
 		sourceSessionId,
 		ctx.liveSessions.get(sourceSessionId),
 	);
+	cancelSidecarMistakeQuestions(
+		ctx,
+		sourceSessionId,
+		"Session replaced by fork",
+	);
 	ctx.liveSessions.delete(sourceSessionId);
 	ctx.liveSessions.set(
 		newSessionId,
@@ -1366,6 +1595,7 @@ async function handleReset(
 ): Promise<unknown> {
 	const sessionId = request.sessionId?.trim();
 	if (sessionId) {
+		cancelSidecarMistakeQuestions(ctx, sessionId, "Session reset");
 		const session = ctx.liveSessions.get(sessionId);
 		if (
 			session?.busy ||
@@ -1375,6 +1605,7 @@ async function handleReset(
 		) {
 			await getSessionManager(ctx).stop(sessionId);
 		}
+		forgetCorePipe(ctx, sessionId);
 		discardAllTrackedAttachments(sessionId, session);
 		ctx.liveSessions.delete(sessionId);
 		sendPromptsInQueueSnapshot(ctx, sessionId);
@@ -1404,6 +1635,8 @@ async function handleRestoreCheckpoint(
 	if (!cwd) throw new Error("config.cwd or config.workspaceRoot is required");
 	const manager = getSessionManager(ctx);
 	return withWorkspaceRestoreLock(ctx, cwd, async () => {
+		// Updated once restore() returns; read lazily by the mistake-limit prompt.
+		let restoredSessionId = sourceSessionId;
 		const restored = await manager.restore({
 			sessionId: sourceSessionId,
 			checkpointRunCount: runCount,
@@ -1411,10 +1644,14 @@ async function handleRestoreCheckpoint(
 			restore: { messages: true, workspace: true },
 			start: {
 				...splitCoreSessionConfig(
-					buildCoreSessionConfig({
-						...config,
-						systemPrompt: await resolveSystemPrompt(config),
-					}) as unknown as ClineCoreStartConfig,
+					buildCoreSessionConfig(
+						{
+							...config,
+							systemPrompt: await resolveSystemPrompt(config),
+						},
+						ctx.telemetryUser,
+						createDesktopMistakeRecovery(ctx, () => restoredSessionId),
+					) as unknown as ClineCoreStartConfig,
 				),
 				source: SessionSource.DESKTOP,
 				interactive: true,
@@ -1426,10 +1663,16 @@ async function handleRestoreCheckpoint(
 		if (!sessionId || !restoredMessages) {
 			throw new Error("Checkpoint restore did not return a new session");
 		}
+		restoredSessionId = sessionId;
 		discardAllTrackedAttachments(
 			sourceSessionId,
 			ctx.liveSessions.get(sourceSessionId),
 		);
+		cancelSidecarMistakeQuestions(
+			ctx,
+			sourceSessionId,
+			"Session checkpoint restored",
+		);
 		ctx.liveSessions.delete(sourceSessionId);
 		ctx.liveSessions.set(
 			sessionId,

apps/examples/desktop-app/sidecar/client-context.ts

@@ -0,0 +1,56 @@
+import * as os from "node:os";
+import { resolveCoreDistinctId } from "@cline/core";
+import type {
+	ClientContext,
+	ExtensionContext,
+	TelemetryMetadata,
+	UserContext,
+} from "@cline/shared";
+import { version } from "../package.json";
+
+/** Shared identity for request headers, Hub attribution, and telemetry. */
+export const DESKTOP_CLIENT_CONTEXT = {
+	name: "cline-desktop",
+	version,
+	platform: "Cline Desktop",
+	platformVersion: version,
+	isMultiRoot: false,
+} as const satisfies ClientContext;
+
+export const DESKTOP_TELEMETRY_METADATA = {
+	extension_version: version,
+	cline_type: "desktop",
+	platform: DESKTOP_CLIENT_CONTEXT.platform,
+	platform_version: DESKTOP_CLIENT_CONTEXT.platformVersion,
+	os_type: os.platform(),
+	os_version: os.version(),
+} satisfies TelemetryMetadata;
+
+export function resolveDesktopTelemetryUser(input?: {
+	accountId?: string;
+	email?: string;
+	organizationId?: string;
+}): UserContext {
+	const accountId = input?.accountId?.trim();
+	return accountId
+		? {
+				distinctId: accountId,
+				accountId,
+				email: input?.email,
+				organizationId: input?.organizationId,
+			}
+		: {
+				distinctId: resolveCoreDistinctId(),
+				accountId: null,
+			};
+}
+
+/** Serializable context attached to every Desktop session sent to the Hub. */
+export function createDesktopExtensionContext(
+	user?: UserContext,
+): ExtensionContext {
+	return {
+		client: DESKTOP_CLIENT_CONTEXT,
+		...(user ? { user: { ...user } } : {}),
+	};
+}

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

@@ -5,6 +5,8 @@ import type { SidecarContext } from "./types";
 const clineAccountServiceCtorMock = vi.hoisted(() => vi.fn());
 const executeClineAccountActionMock = vi.hoisted(() => vi.fn());
 const getProviderSettingsMock = vi.hoisted(() => vi.fn());
+const saveProviderSettingsMock = vi.hoisted(() => vi.fn());
+const persistProviderSettingsMock = vi.hoisted(() => vi.fn());
 const resolveProviderApiKeyMock = vi.hoisted(() => vi.fn());
 
 vi.mock("@cline/core", async () => {
@@ -20,7 +22,9 @@ vi.mock("@cline/core", async () => {
 		executeClineAccountAction: executeClineAccountActionMock,
 		ProviderSettingsManager: class {
 			getProviderSettings = getProviderSettingsMock;
+			saveProviderSettings = persistProviderSettingsMock;
 		},
+		saveLocalProviderSettings: saveProviderSettingsMock,
 		RuntimeOAuthTokenManager: class {
 			resolveProviderApiKey = resolveProviderApiKeyMock;
 		},
@@ -29,11 +33,13 @@ vi.mock("@cline/core", async () => {
 
 function createContext() {
 	const capture = vi.fn();
+	const setDistinctId = vi.fn();
+	const updateCommonProperties = vi.fn();
 	const ctx = {
-		telemetry: { capture },
+		telemetry: { capture, setDistinctId, updateCommonProperties },
 		logger: { debug: vi.fn(), log: vi.fn(), error: vi.fn() },
 	} as unknown as SidecarContext;
-	return { ctx, capture };
+	return { ctx, capture, setDistinctId, updateCommonProperties };
 }
 
 const FETCH_ME_ARGS = {
@@ -50,12 +56,15 @@ beforeEach(() => {
 	clineAccountServiceCtorMock.mockReset();
 	executeClineAccountActionMock.mockReset();
 	getProviderSettingsMock.mockReset();
+	saveProviderSettingsMock.mockReset();
+	persistProviderSettingsMock.mockReset();
 	resolveProviderApiKeyMock.mockReset();
 });
 
 describe("cline_account command auth states", () => {
-	it("returns a typed not-authenticated result when signed out, without telemetry or a thrown error", async () => {
-		const { ctx, capture } = createContext();
+	it("returns a typed not-authenticated result and restores anonymous telemetry when signed out", async () => {
+		const { ctx, capture, setDistinctId, updateCommonProperties } =
+			createContext();
 		resolveProviderApiKeyMock.mockResolvedValue(null);
 		getProviderSettingsMock.mockReturnValue(undefined);
 
@@ -69,6 +78,14 @@ describe("cline_account command auth states", () => {
 		expect(executeClineAccountActionMock).not.toHaveBeenCalled();
 		expect(clineAccountServiceCtorMock).not.toHaveBeenCalled();
 		expect(capture).not.toHaveBeenCalled();
+		expect(setDistinctId).toHaveBeenCalledWith(expect.any(String));
+		expect(updateCommonProperties).toHaveBeenCalledWith(
+			expect.objectContaining({
+				user_id: undefined,
+				account_id: undefined,
+				organization_id: undefined,
+			}),
+		);
 	});
 
 	it("runs the account action unchanged when a fresh token resolves", async () => {
@@ -140,3 +157,252 @@ describe("cline_account command auth states", () => {
 		});
 	});
 });
+
+/**
+ * Feature-flag identity is otherwise resolved once at sidecar startup, so these
+ * cover the mid-session transitions that would otherwise keep evaluating flags
+ * against a stale account (or the device).
+ */
+describe("cline_account keeps feature-flag identity in sync", () => {
+	async function currentFlagsUserId(): Promise<string | undefined> {
+		const { getDesktopFeatureFlagsContext } = await import("./feature-flags");
+		return getDesktopFeatureFlagsContext().userId ?? undefined;
+	}
+
+	async function runOperation(ctx: SidecarContext, operation: string) {
+		const { handleCommand } = await import("./commands");
+		return handleCommand(ctx, "cline_account", {
+			action: "clineAccount",
+			operation,
+		});
+	}
+
+	beforeEach(async () => {
+		const { resetDesktopFeatureFlagsForTesting } = await import(
+			"./feature-flags"
+		);
+		resetDesktopFeatureFlagsForTesting();
+	});
+
+	it("adopts the account identity on login", async () => {
+		const { ctx, setDistinctId, updateCommonProperties } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue({ apiKey: "token" });
+		getProviderSettingsMock.mockReturnValue({});
+		executeClineAccountActionMock.mockResolvedValue({
+			id: "acct-1",
+			email: "dev@example.com",
+		});
+
+		await runOperation(ctx, "fetchMe");
+
+		expect(await currentFlagsUserId()).toBe("acct-1");
+		expect(setDistinctId).toHaveBeenCalledWith("acct-1");
+		expect(updateCommonProperties).toHaveBeenCalledWith(
+			expect.objectContaining({ user_id: "acct-1", account_id: "acct-1" }),
+		);
+		expect(ctx.telemetryUser).toEqual({
+			distinctId: "acct-1",
+			accountId: "acct-1",
+			email: "dev@example.com",
+			organizationId: undefined,
+		});
+	});
+
+	it("applies and persists the active organization for task telemetry", async () => {
+		const { ctx, updateCommonProperties } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue({ apiKey: "token" });
+		getProviderSettingsMock.mockReturnValue({
+			provider: "cline",
+			auth: { accountId: "acct-1", accessToken: "token" },
+		});
+		executeClineAccountActionMock.mockResolvedValue({
+			id: "acct-1",
+			email: "dev@example.com",
+			organizations: [
+				{
+					active: true,
+					memberId: "member-1",
+					name: "Acme",
+					organizationId: "org-1",
+					roles: ["member"],
+				},
+			],
+		});
+
+		await runOperation(ctx, "fetchMe");
+
+		expect(updateCommonProperties).toHaveBeenCalledWith(
+			expect.objectContaining({
+				user_id: "acct-1",
+				organization_id: "org-1",
+			}),
+		);
+		expect(persistProviderSettingsMock).toHaveBeenCalledWith(
+			expect.objectContaining({
+				auth: expect.objectContaining({
+					organizationId: "org-1",
+					memberId: "member-1",
+				}),
+			}),
+			{ setLastUsed: false },
+		);
+		expect(ctx.telemetryUser).toEqual({
+			distinctId: "acct-1",
+			accountId: "acct-1",
+			email: "dev@example.com",
+			organizationId: "org-1",
+		});
+	});
+
+	it("leaves the signed-in identity intact across an organization switch", async () => {
+		const { ctx } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue({ apiKey: "token" });
+		getProviderSettingsMock.mockReturnValue({});
+		executeClineAccountActionMock.mockResolvedValue({ id: "acct-1" });
+		await runOperation(ctx, "fetchMe");
+		expect(await currentFlagsUserId()).toBe("acct-1");
+
+		executeClineAccountActionMock.mockResolvedValue(undefined);
+		getProviderSettingsMock.mockReturnValue({
+			auth: { accountId: "stale-acct" },
+		});
+
+		await runOperation(ctx, "switchAccount");
+
+		expect(await currentFlagsUserId()).toBe("acct-1");
+	});
+
+	it("adopts the identity from the refetch that follows a switch", async () => {
+		const { ctx } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue({ apiKey: "token" });
+		getProviderSettingsMock.mockReturnValue({});
+		executeClineAccountActionMock.mockResolvedValue({ id: "acct-1" });
+		await runOperation(ctx, "fetchMe");
+
+		executeClineAccountActionMock.mockResolvedValue(undefined);
+		await runOperation(ctx, "switchAccount");
+
+		executeClineAccountActionMock.mockResolvedValue({ id: "acct-2" });
+		await runOperation(ctx, "fetchMe");
+
+		expect(await currentFlagsUserId()).toBe("acct-2");
+	});
+
+	it("clears the account identity on logout", async () => {
+		const { ctx, setDistinctId, updateCommonProperties } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue({ apiKey: "token" });
+		getProviderSettingsMock.mockReturnValue({});
+		executeClineAccountActionMock.mockResolvedValue({ id: "acct-1" });
+		await runOperation(ctx, "fetchMe");
+		expect(await currentFlagsUserId()).toBe("acct-1");
+
+		// Signed out: no token resolves.
+		resolveProviderApiKeyMock.mockResolvedValue(null);
+		getProviderSettingsMock.mockReturnValue(undefined);
+
+		await runOperation(ctx, "fetchMe");
+
+		expect(await currentFlagsUserId()).toBeUndefined();
+		expect(ctx.telemetryUser).toEqual(
+			expect.objectContaining({
+				accountId: null,
+				distinctId: expect.any(String),
+			}),
+		);
+		expect(setDistinctId).toHaveBeenLastCalledWith(
+			ctx.telemetryUser?.distinctId,
+		);
+		expect(ctx.telemetryUser?.distinctId).not.toBe("acct-1");
+		expect(updateCommonProperties).toHaveBeenLastCalledWith(
+			expect.objectContaining({
+				user_id: undefined,
+				account_id: undefined,
+				account_email: undefined,
+				organization_id: undefined,
+			}),
+		);
+	});
+
+	it("clears the identity when sign-out blanks the cline auth settings", async () => {
+		const { ctx, setDistinctId, updateCommonProperties } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue({ apiKey: "token" });
+		getProviderSettingsMock.mockReturnValue({});
+		executeClineAccountActionMock.mockResolvedValue({ id: "acct-1" });
+		await runOperation(ctx, "fetchMe");
+		expect(await currentFlagsUserId()).toBe("acct-1");
+
+		// What the Sign Out button actually sends: a settings write that blanks
+		// the auth block. No account command is involved.
+		getProviderSettingsMock.mockReturnValue({ auth: { accountId: "" } });
+		saveProviderSettingsMock.mockReturnValue({
+			providerId: "cline",
+			enabled: true,
+			settingsPath: "/tmp/settings.json",
+		});
+		const { handleCommand } = await import("./commands");
+		await handleCommand(ctx, "save_provider_settings", {
+			provider: "cline",
+			api_key: "",
+			settings: { auth: { accessToken: "", refreshToken: "", accountId: "" } },
+		});
+
+		expect(await currentFlagsUserId()).toBeUndefined();
+		expect(ctx.telemetryUser).toEqual(
+			expect.objectContaining({
+				accountId: null,
+				distinctId: expect.any(String),
+			}),
+		);
+		expect(setDistinctId).toHaveBeenLastCalledWith(
+			ctx.telemetryUser?.distinctId,
+		);
+		expect(updateCommonProperties).toHaveBeenLastCalledWith(
+			expect.objectContaining({
+				user_id: undefined,
+				account_id: undefined,
+				organization_id: undefined,
+			}),
+		);
+	});
+
+	it("ignores settings writes for other providers", async () => {
+		const { ctx } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue({ apiKey: "token" });
+		getProviderSettingsMock.mockReturnValue({});
+		executeClineAccountActionMock.mockResolvedValue({ id: "acct-1" });
+		await runOperation(ctx, "fetchMe");
+
+		saveProviderSettingsMock.mockReturnValue({
+			providerId: "anthropic",
+			enabled: true,
+			settingsPath: "/tmp/settings.json",
+		});
+		const { handleCommand } = await import("./commands");
+		await handleCommand(ctx, "save_provider_settings", {
+			provider: "anthropic",
+			api_key: "sk-test",
+		});
+
+		// Saving an unrelated provider must not disturb the Cline identity.
+		expect(await currentFlagsUserId()).toBe("acct-1");
+	});
+
+	it("falls back to the device distinct ID after logout", async () => {
+		const { ctx } = createContext();
+		const { getDesktopFeatureFlagsContext } = await import("./feature-flags");
+		const deviceId = getDesktopFeatureFlagsContext().distinctId;
+
+		resolveProviderApiKeyMock.mockResolvedValue({ apiKey: "token" });
+		getProviderSettingsMock.mockReturnValue({});
+		executeClineAccountActionMock.mockResolvedValue({ id: "acct-1" });
+		await runOperation(ctx, "fetchMe");
+		expect(getDesktopFeatureFlagsContext().distinctId).toBe("acct-1");
+
+		resolveProviderApiKeyMock.mockResolvedValue(null);
+		getProviderSettingsMock.mockReturnValue(undefined);
+		await runOperation(ctx, "fetchMe");
+
+		// Not left on the previous account's ID.
+		expect(getDesktopFeatureFlagsContext().distinctId).toBe(deviceId);
+	});
+});

apps/examples/desktop-app/sidecar/commands-hub-upgrade.test.ts

@@ -0,0 +1,95 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { SidecarContext, SidecarWebSocketClient } from "./types";
+
+const upgradeManagedHubMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@cline/core", async () => {
+	const actual =
+		await vi.importActual<typeof import("@cline/core")>("@cline/core");
+	return {
+		...actual,
+		upgradeManagedHub: upgradeManagedHubMock,
+	};
+});
+
+function createContext(): SidecarContext {
+	return {
+		workspaceRoot: "/workspace",
+		wsClients: new Set(),
+		hubBuildMismatch: {
+			url: "ws://127.0.0.1:25463/hub",
+			reason: "outdated_hub",
+			expectedBuildId: "current-build",
+		},
+		logger: { debug: vi.fn(), log: vi.fn(), error: vi.fn() },
+	} as unknown as SidecarContext;
+}
+
+function connection(canApproveTools: boolean): SidecarWebSocketClient {
+	return { data: { canApproveTools } } as unknown as SidecarWebSocketClient;
+}
+
+beforeEach(() => {
+	upgradeManagedHubMock.mockReset();
+});
+
+describe("hub_upgrade command", () => {
+	it("rejects connections without the approval token, before touching the hub", async () => {
+		const { handleCommand } = await import("./commands");
+		const ctx = createContext();
+
+		await expect(
+			handleCommand(ctx, "hub_upgrade", {}, { connection: connection(false) }),
+		).rejects.toThrow(/trusted desktop connection/);
+		await expect(handleCommand(ctx, "hub_upgrade", {}, {})).rejects.toThrow(
+			/trusted desktop connection/,
+		);
+		expect(upgradeManagedHubMock).not.toHaveBeenCalled();
+		// The pending mismatch must survive a refused request.
+		expect(ctx.hubBuildMismatch).not.toBeNull();
+	});
+
+	it("forces the upgrade for the trusted webview connection and clears the mismatch", async () => {
+		upgradeManagedHubMock.mockResolvedValue({
+			outcome: "replaced",
+			url: "ws://127.0.0.1:25463/hub",
+			authToken: "new-token",
+			activeSessionCount: 2,
+		});
+		const { handleCommand } = await import("./commands");
+		const ctx = createContext();
+
+		const result = await handleCommand(
+			ctx,
+			"hub_upgrade",
+			{},
+			{ connection: connection(true) },
+		);
+
+		expect(upgradeManagedHubMock).toHaveBeenCalledWith({
+			workspaceRoot: "/workspace",
+			force: true,
+			reason: "Cline Desktop hub update",
+		});
+		expect(result).toEqual({
+			outcome: "replaced",
+			url: "ws://127.0.0.1:25463/hub",
+			interruptedSessionCount: 2,
+		});
+		expect(ctx.hubBuildMismatch).toBeNull();
+	});
+
+	it("surfaces a newer running hub as an error instead of replacing it", async () => {
+		upgradeManagedHubMock.mockResolvedValue({
+			outcome: "hub_not_older",
+			url: "ws://127.0.0.1:25463/hub",
+		});
+		const { handleCommand } = await import("./commands");
+		const ctx = createContext();
+
+		await expect(
+			handleCommand(ctx, "hub_upgrade", {}, { connection: connection(true) }),
+		).rejects.toThrow(/newer than this app/);
+		expect(ctx.hubBuildMismatch).not.toBeNull();
+	});
+});

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

@@ -0,0 +1,280 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { isClineAccountNotAuthenticatedResult } from "../webview/lib/cline-account-state";
+import {
+	listClineGitHubRepositories,
+	listClineIntegrations,
+	resolveGitHubInstallUrl,
+} from "./commands-integrations";
+import type { SidecarContext } from "./types";
+
+const getProviderSettingsMock = vi.hoisted(() => vi.fn());
+const resolveProviderApiKeyMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@cline/core", async () => {
+	const actual =
+		await vi.importActual<typeof import("@cline/core")>("@cline/core");
+	return {
+		...actual,
+		ProviderSettingsManager: class {
+			getProviderSettings = getProviderSettingsMock;
+		},
+		RuntimeOAuthTokenManager: class {
+			resolveProviderApiKey = resolveProviderApiKeyMock;
+		},
+	};
+});
+
+function createContext() {
+	const capture = vi.fn();
+	const ctx = {
+		telemetry: { capture },
+		logger: { debug: vi.fn(), log: vi.fn(), error: vi.fn() },
+	} as unknown as SidecarContext;
+	return { ctx, capture };
+}
+
+const REQUEST_OPTIONS = {
+	apiBaseUrl: "https://api.example.com",
+	appBaseUrl: "https://app.example.com",
+	authToken: "test-token",
+} as const;
+
+function requestOptions(fetchImpl: ReturnType<typeof vi.fn>) {
+	return {
+		...REQUEST_OPTIONS,
+		fetchImpl: fetchImpl as unknown as typeof fetch,
+	};
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+beforeEach(() => {
+	getProviderSettingsMock.mockReset();
+	resolveProviderApiKeyMock.mockReset();
+});
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+});
+
+describe("listClineIntegrations", () => {
+	it("lists integrations through the envelope with a bearer token", async () => {
+		const fetchImpl = vi
+			.fn()
+			.mockResolvedValue(
+				jsonResponse({ success: true, data: [{ provider: "github" }] }),
+			);
+
+		const result = await listClineIntegrations(requestOptions(fetchImpl));
+
+		expect(result).toEqual([{ provider: "github" }]);
+		const [url, init] = fetchImpl.mock.calls[0] as [URL, RequestInit];
+		expect(String(url)).toBe("https://api.example.com/api/v1/integrations");
+		expect((init.headers as Record<string, string>).Authorization).toBe(
+			"Bearer test-token",
+		);
+	});
+});
+
+describe("listClineGitHubRepositories", () => {
+	it("lists GitHub repositories from the repositories endpoint", async () => {
+		const fetchImpl = vi
+			.fn()
+			.mockResolvedValue(
+				jsonResponse({ success: true, data: [{ full_name: "cline/cline" }] }),
+			);
+
+		const result = await listClineGitHubRepositories(requestOptions(fetchImpl));
+
+		expect(result).toEqual([{ full_name: "cline/cline" }]);
+		expect(String(fetchImpl.mock.calls[0][0])).toBe(
+			"https://api.example.com/api/v1/integrations/github/repositories",
+		);
+	});
+
+	it("surfaces the API envelope error message on failures", async () => {
+		const fetchImpl = vi
+			.fn()
+			.mockResolvedValue(
+				jsonResponse(
+					{ success: false, error: "failed to list integrations" },
+					500,
+				),
+			);
+
+		await expect(
+			listClineIntegrations(requestOptions(fetchImpl)),
+		).rejects.toThrow("failed to list integrations");
+	});
+});
+
+describe("resolveGitHubInstallUrl", () => {
+	it("resolves the GitHub install URL from the redirect location", async () => {
+		const fetchImpl = vi.fn().mockResolvedValue(
+			new Response(null, {
+				status: 302,
+				headers: {
+					location: "https://github.com/apps/cline/installations/new?state=abc",
+				},
+			}),
+		);
+
+		const result = await resolveGitHubInstallUrl(requestOptions(fetchImpl));
+
+		expect(result).toEqual({
+			url: "https://github.com/apps/cline/installations/new?state=abc",
+		});
+		const [url, init] = fetchImpl.mock.calls[0] as [URL, RequestInit];
+		expect(url.origin + url.pathname).toBe(
+			"https://api.example.com/api/v1/integrations/github/install",
+		);
+		// The post-install browser hop must land on the Cline dashboard.
+		expect(url.searchParams.get("redirect")).toBe(
+			"https://app.example.com/dashboard/integrations",
+		);
+		// The redirect must be read, not followed: the Location URL is the result.
+		expect(init.redirect).toBe("manual");
+	});
+
+	it("resolves a relative redirect location against the request URL", async () => {
+		const fetchImpl = vi.fn().mockResolvedValue(
+			new Response(null, {
+				status: 302,
+				headers: { location: "//github.com/apps/cline/installations/new" },
+			}),
+		);
+
+		const result = await resolveGitHubInstallUrl(requestOptions(fetchImpl));
+
+		// A bare relative Location would blow up later in the URL opener.
+		expect(result).toEqual({
+			url: "https://github.com/apps/cline/installations/new",
+		});
+	});
+
+	it.each([
+		["https://evil.example/apps/cline", "evil.example"],
+		["https://github.com.evil.example/apps/cline", "github.com.evil.example"],
+		// Subdomains are not part of the install flow, so they are not allowed
+		// either -- the host must be exactly github.com.
+		["https://gist.github.com/apps/cline", "gist.github.com"],
+	])("rejects a redirect to a non-GitHub host (%s)", async (location, host) => {
+		const fetchImpl = vi
+			.fn()
+			.mockResolvedValue(
+				new Response(null, { status: 302, headers: { location } }),
+			);
+
+		await expect(
+			resolveGitHubInstallUrl(requestOptions(fetchImpl)),
+		).rejects.toThrow(`unexpected host: ${host}`);
+	});
+
+	it("rejects a redirect that does not use https", async () => {
+		const fetchImpl = vi.fn().mockResolvedValue(
+			new Response(null, {
+				status: 302,
+				headers: { location: "http://github.com/apps/cline" },
+			}),
+		);
+
+		await expect(
+			resolveGitHubInstallUrl(requestOptions(fetchImpl)),
+		).rejects.toThrow("must use https");
+	});
+
+	it("rejects a redirect location that is not a usable URL", async () => {
+		const fetchImpl = vi.fn().mockResolvedValue(
+			new Response(null, {
+				status: 302,
+				headers: { location: "http://" },
+			}),
+		);
+
+		await expect(
+			resolveGitHubInstallUrl(requestOptions(fetchImpl)),
+		).rejects.toThrow("not a valid URL");
+	});
+
+	it("throws when the install endpoint does not answer with a redirect", async () => {
+		const fetchImpl = vi
+			.fn()
+			.mockResolvedValue(
+				jsonResponse({ error: "authentication required" }, 401),
+			);
+
+		await expect(
+			resolveGitHubInstallUrl(requestOptions(fetchImpl)),
+		).rejects.toThrow("authentication required");
+	});
+});
+
+describe("cline_integrations command auth states", () => {
+	it("returns a typed not-authenticated result when signed out, without calling the API", async () => {
+		const { ctx, capture } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue(null);
+		getProviderSettingsMock.mockReturnValue(undefined);
+		const fetchMock = vi.fn();
+		vi.stubGlobal("fetch", fetchMock);
+
+		const { handleCommand } = await import("./commands");
+		const result = await handleCommand(ctx, "cline_integrations", {
+			operation: "list",
+		});
+
+		expect(isClineAccountNotAuthenticatedResult(result)).toBe(true);
+		expect(fetchMock).not.toHaveBeenCalled();
+		expect(capture).not.toHaveBeenCalled();
+	});
+
+	it("calls the Cline API with the resolved fresh token when signed in", async () => {
+		const { ctx } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue({
+			apiKey: "fresh-token",
+			refreshed: true,
+		});
+		getProviderSettingsMock.mockReturnValue(undefined);
+		const fetchMock = vi
+			.fn()
+			.mockResolvedValue(
+				jsonResponse({ success: true, data: [{ provider: "github" }] }),
+			);
+		vi.stubGlobal("fetch", fetchMock);
+
+		const { handleCommand } = await import("./commands");
+		const result = await handleCommand(ctx, "cline_integrations", {
+			operation: "list",
+		});
+
+		expect(result).toEqual([{ provider: "github" }]);
+		const [url, init] = fetchMock.mock.calls[0] as [URL, RequestInit];
+		expect(String(url)).toContain("/api/v1/integrations");
+		expect((init.headers as Record<string, string>).Authorization).toBe(
+			"Bearer fresh-token",
+		);
+	});
+
+	it("rejects unknown operations", async () => {
+		const { ctx } = createContext();
+		resolveProviderApiKeyMock.mockResolvedValue({
+			apiKey: "fresh-token",
+			refreshed: true,
+		});
+		getProviderSettingsMock.mockReturnValue(undefined);
+		const fetchMock = vi.fn();
+		vi.stubGlobal("fetch", fetchMock);
+
+		const { handleCommand } = await import("./commands");
+		await expect(
+			handleCommand(ctx, "cline_integrations", {
+				operation: "dropIntegrations",
+			}),
+		).rejects.toThrow("Unsupported Cline integrations operation");
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+});

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

@@ -0,0 +1,183 @@
+import type {
+	ClineGitHubRepository,
+	ClineIntegration,
+} from "../webview/lib/cline-integrations-types";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+const GITHUB_INSTALL_HOST = "github.com";
+
+function resolveInstallRedirect(location: string, requestUrl: URL): string {
+	let resolved: URL;
+	try {
+		resolved = new URL(location, requestUrl);
+	} catch {
+		throw new Error(`GitHub install redirect is not a valid URL: ${location}`);
+	}
+	if (resolved.protocol !== "https:") {
+		throw new Error(
+			`GitHub install redirect must use https, got: ${resolved.protocol}`,
+		);
+	}
+	if (resolved.hostname !== GITHUB_INSTALL_HOST) {
+		throw new Error(
+			`GitHub install redirect pointed at an unexpected host: ${resolved.hostname}`,
+		);
+	}
+	return resolved.toString();
+}
+
+export interface ClineIntegrationsRequestOptions {
+	apiBaseUrl: string;
+	/** Frontend origin the browser install flow returns to when it finishes. */
+	appBaseUrl: string;
+	authToken: string;
+	requestTimeoutMs?: number;
+	fetchImpl?: typeof fetch;
+}
+
+export async function listClineIntegrations(
+	options: ClineIntegrationsRequestOptions,
+): Promise<ClineIntegration[]> {
+	const data = await requestClineApiJson("/api/v1/integrations", options);
+	return Array.isArray(data) ? (data as ClineIntegration[]) : [];
+}
+
+export async function listClineGitHubRepositories(
+	options: ClineIntegrationsRequestOptions,
+): Promise<ClineGitHubRepository[]> {
+	const data = await requestClineApiJson(
+		"/api/v1/integrations/github/repositories",
+		options,
+	);
+	return Array.isArray(data) ? (data as ClineGitHubRepository[]) : [];
+}
+
+export async function resolveGitHubInstallUrl(
+	options: ClineIntegrationsRequestOptions,
+): Promise<{ url: string }> {
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const installUrl = new URL(
+		"/api/v1/integrations/github/install",
+		options.apiBaseUrl,
+	);
+	installUrl.searchParams.set(
+		"redirect",
+		new URL("/dashboard/integrations", options.appBaseUrl).toString(),
+	);
+
+	const controller = new AbortController();
+	const timeout = setTimeout(
+		() => controller.abort(),
+		options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+	);
+	try {
+		const response = await fetchImpl(installUrl, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${options.authToken}` },
+			redirect: "manual",
+			signal: controller.signal,
+		});
+
+		const location = response.headers.get("location");
+		if (response.status >= 300 && response.status < 400 && location?.trim()) {
+			return { url: resolveInstallRedirect(location.trim(), installUrl) };
+		}
+
+		const text = await response.text().catch(() => "");
+		let parsed: unknown;
+		try {
+			parsed = text.trim() ? JSON.parse(text) : undefined;
+		} catch {
+			parsed = undefined;
+		}
+		throw new Error(formatRequestFailure(response.status, text, parsed));
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
+function getEnvelopeError(parsed: unknown): string | undefined {
+	if (typeof parsed !== "object" || parsed === null || !("error" in parsed)) {
+		return undefined;
+	}
+	const error = (parsed as { error?: unknown }).error;
+	return typeof error === "string" && error.trim() ? error : undefined;
+}
+
+function formatRequestFailure(
+	status: number,
+	bodyText: string,
+	parsed: unknown,
+): string {
+	const envelopeError = getEnvelopeError(parsed);
+	if (envelopeError) {
+		return envelopeError;
+	}
+	const body = bodyText.trim();
+	if (body) {
+		const preview = body.length > 200 ? `${body.slice(0, 200)}...` : body;
+		return `Cline integrations request failed with status ${status}: ${preview}`;
+	}
+	return `Cline integrations request failed with status ${status}`;
+}
+
+async function requestClineApiJson(
+	endpoint: string,
+	options: ClineIntegrationsRequestOptions,
+): Promise<unknown> {
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const controller = new AbortController();
+	const timeout = setTimeout(
+		() => controller.abort(),
+		options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+	);
+	try {
+		const response = await fetchImpl(new URL(endpoint, options.apiBaseUrl), {
+			method: "GET",
+			headers: {
+				Authorization: `Bearer ${options.authToken}`,
+				"Content-Type": "application/json",
+			},
+			signal: controller.signal,
+		});
+
+		const text = await response.text();
+		let parsed: unknown;
+		if (text.trim()) {
+			try {
+				parsed = JSON.parse(text);
+			} catch {
+				if (!response.ok) {
+					throw new Error(
+						formatRequestFailure(response.status, text, undefined),
+					);
+				}
+				throw new Error("Cline integrations response was not valid JSON");
+			}
+		}
+
+		if (!response.ok) {
+			throw new Error(formatRequestFailure(response.status, text, parsed));
+		}
+
+		if (typeof parsed === "object" && parsed !== null && "success" in parsed) {
+			const envelope = parsed as {
+				success?: unknown;
+				error?: unknown;
+				data?: unknown;
+			};
+			if (typeof envelope.success === "boolean") {
+				if (!envelope.success) {
+					throw new Error(
+						getEnvelopeError(parsed) || "Cline integrations request failed",
+					);
+				}
+				return envelope.data ?? null;
+			}
+		}
+		return parsed ?? null;
+	} finally {
+		clearTimeout(timeout);
+	}
+}

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

@@ -15,7 +15,9 @@ import type {
 import {
 	addLocalProvider,
 	ClineAccountService,
+	type ClineAccountUser,
 	captureAuthRefreshSoftFailure,
+	clearAccountTelemetryIdentity,
 	createConfiguredStreamingTranscriptionSession,
 	createUserInstructionConfigService,
 	ensureCustomProvidersLoaded,
@@ -23,18 +25,25 @@ import {
 	fetchClineRecommendedModels,
 	getCoreBuiltinToolCatalog,
 	getLocalProviderModels,
+	identifyAccount,
 	listHookConfigFiles,
 	listLocalProviders,
 	normalizeOAuthProvider,
 	ProviderSettingsManager,
 	parseMcpServerRegistration,
+	persistClineAccountTelemetryIdentity,
 	probeMcpServerConnection,
 	RuntimeOAuthTokenManager,
 	readGlobalSettings,
+	resolveClineAccountTelemetryIdentity,
 	resolveLocalClineAuthToken,
 	resolveMcpServerRegistration,
 	resolveSessionBackend,
 	resolveAgentConfigSearchPaths as resolveSharedAgentConfigSearchPaths,
+	SESSION_IMPORT_TOOLS,
+	type SessionImportRequest,
+	SessionImportService,
+	type SessionImportTool,
 	SqliteSessionStore,
 	saveLocalProviderSettings,
 	saveVoiceInputSettings,
@@ -45,10 +54,13 @@ import {
 	transcribeConfiguredVoiceInput,
 	updateLocalProvider,
 	updateMcpSettingsFileSync,
+	upgradeManagedHub,
 } from "@cline/core";
 import { resolveAudioTranscriptionRoute } from "@cline/llms";
 import {
 	CLINE_DEFAULT_MODEL_ID,
+	formatSessionSearchPreview,
+	formatSessionSearchTitle,
 	getClineEnvironmentConfig,
 	isCanonicalBase64,
 	ONE_TIME_SCHEDULE_CRON_PATTERN,
@@ -59,6 +71,12 @@ import { readFileSyncStrippingUtf8Bom } from "@cline/shared/node";
 import packageJson from "../package.json";
 import { CLINE_ACCOUNT_NOT_AUTHENTICATED_RESULT } from "../webview/lib/cline-account-state";
 import { MAX_RECORDED_AUDIO_BYTES } from "../webview/lib/voice-input-limits";
+import { resolveDesktopTelemetryUser } from "./client-context";
+import {
+	listClineGitHubRepositories,
+	listClineIntegrations,
+	resolveGitHubInstallUrl,
+} from "./commands-integrations";
 import {
 	connectorChannelsPayload,
 	startConnectorChannel,
@@ -70,6 +88,10 @@ import {
 	resolveSidecarAskQuestion,
 	sendEventToClient,
 } from "./context";
+import {
+	identifyDesktopFeatureFlagsAccount,
+	refreshDesktopFeatureFlags,
+} from "./feature-flags";
 import {
 	installMarketplaceEntryForDesktopCommand,
 	listMarketplaceInstalledEntries,
@@ -294,6 +316,69 @@ function removePathIfExists(
 // refreshes would invalidate each other.
 let clineOAuthTokenManager: RuntimeOAuthTokenManager | undefined;
 
+function syncAccountContextFromResult(
+	ctx: SidecarContext,
+	manager: ProviderSettingsManager,
+	operation: string,
+	result: unknown,
+): void {
+	if (operation === "fetchMe") {
+		const user = result as ClineAccountUser | undefined;
+		if (user?.id) {
+			const identity = resolveClineAccountTelemetryIdentity(user);
+			ctx.telemetryUser = resolveDesktopTelemetryUser({
+				accountId: identity.id,
+				email: identity.email,
+				organizationId: identity.organizationId,
+			});
+			identifyAccount(ctx.telemetry, identity);
+			persistClineAccountTelemetryIdentity(manager, identity);
+			void identifyDesktopFeatureFlagsAccount(
+				{ id: user.id, email: user.email },
+				{ logger: ctx.logger, telemetry: ctx.telemetry },
+			);
+		}
+		return;
+	}
+}
+
+function syncAccountContextFromSettings(
+	ctx: SidecarContext,
+	manager: ProviderSettingsManager,
+): void {
+	const auth = manager.getProviderSettings("cline")?.auth;
+	const accountId = auth?.accountId?.trim();
+	if (!auth || !accountId) {
+		syncSignedOutAccountContext(ctx);
+		return;
+	}
+	ctx.telemetryUser = resolveDesktopTelemetryUser({
+		accountId,
+		organizationId: auth.organizationId,
+	});
+	identifyAccount(ctx.telemetry, {
+		id: accountId,
+		provider: "cline",
+		organizationId: auth.organizationId,
+		organizationName: auth.organizationName,
+		memberId: auth.memberId,
+	});
+	void identifyDesktopFeatureFlagsAccount(
+		{ id: accountId },
+		{ logger: ctx.logger, telemetry: ctx.telemetry },
+	);
+}
+
+function syncSignedOutAccountContext(ctx: SidecarContext): void {
+	const telemetryUser = resolveDesktopTelemetryUser();
+	ctx.telemetryUser = telemetryUser;
+	clearAccountTelemetryIdentity(ctx.telemetry, telemetryUser.distinctId);
+	void identifyDesktopFeatureFlagsAccount(
+		{},
+		{ logger: ctx.logger, telemetry: ctx.telemetry },
+	);
+}
+
 async function resolveFreshClineAuthToken(
 	ctx: SidecarContext,
 	manager: ProviderSettingsManager,
@@ -503,6 +588,67 @@ async function listSessionsFromSidecarManager(
 		.slice(0, max);
 }
 
+async function withSearchDeadline<T>(
+	promise: Promise<T>,
+	timeoutMs: number,
+): Promise<T> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		return await Promise.race([
+			promise,
+			new Promise<never>((_, reject) => {
+				timer = setTimeout(
+					() => reject(new Error("Session search timed out")),
+					timeoutMs,
+				);
+			}),
+		]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+function metadataSessionSearchHits(
+	value: unknown,
+	query: string,
+): JsonRecord[] {
+	if (!Array.isArray(value)) return [];
+	const normalizedQuery = query.toLocaleLowerCase();
+	return value.flatMap((item) => {
+		if (!item || typeof item !== "object") return [];
+		const session = item as JsonRecord;
+		const metadata =
+			session.metadata && typeof session.metadata === "object"
+				? (session.metadata as JsonRecord)
+				: {};
+		const sessionId = String(session.sessionId ?? "").trim();
+		if (!sessionId) return [];
+		const rawTitle = String(
+			metadata.title ?? session.title ?? session.prompt ?? sessionId,
+		).trim();
+		const prompt = String(session.prompt ?? metadata.prompt ?? "");
+		const title = formatSessionSearchTitle(rawTitle) || sessionId;
+		const workspaceRoot = String(session.workspaceRoot ?? session.cwd ?? "");
+		const searchable = [rawTitle, prompt, workspaceRoot, session.model]
+			.join("\n")
+			.toLocaleLowerCase();
+		if (!searchable.includes(normalizedQuery)) return [];
+		return [
+			{
+				sessionId,
+				documentId: `${sessionId}:metadata`,
+				ordinal: -1,
+				role: "session",
+				startedAt: String(session.startedAt ?? session.createdAt ?? ""),
+				workspaceRoot,
+				title,
+				snippet: formatSessionSearchPreview("session", prompt || title),
+				score: 0,
+			},
+		];
+	});
+}
+
 // ---------------------------------------------------------------------------
 // Git helpers
 // ---------------------------------------------------------------------------
@@ -585,7 +731,15 @@ async function handleRoutineScheduleCommand(
 		hubCommand: string,
 		payload?: Record<string, unknown>,
 	) => {
-		const reply = await hubClient.command(hubCommand as never, payload);
+		// The desktop app runs chats (and therefore agent-created schedules)
+		// across many workspace folders, while this hub client is registered
+		// against the app's own launch directory. Ask the hub for schedules
+		// across all workspaces so the Schedules page manages every schedule
+		// on this machine, not just the launch-directory scope.
+		const reply = await hubClient.command(hubCommand as never, {
+			...payload,
+			allWorkspaces: true,
+		});
 		if (!reply.ok) {
 			throw new Error(
 				reply.error?.message ?? `hub command failed: ${hubCommand}`,
@@ -924,6 +1078,34 @@ async function listUserInstructionConfigs(
 	} finally {
 		userInstructionService.stop();
 	}
+	const knownSkillPaths = new Set(
+		skills.flatMap((skill) => {
+			if (!skill || typeof skill !== "object") return [];
+			const path = (skill as JsonRecord).path;
+			return typeof path === "string" ? [path] : [];
+		}),
+	);
+	for (const skill of hubSettings.skills) {
+		if (
+			skill.agentPlugin !== true ||
+			skill.enabled === false ||
+			knownSkillPaths.has(skill.path)
+		) {
+			continue;
+		}
+		skills.push({
+			id: skill.id,
+			name: skill.name,
+			description: skill.description,
+			instructions: "",
+			path: skill.path,
+			enabled: true,
+			source: skill.source,
+			agentPlugin: true,
+			pluginName: skill.pluginName,
+		});
+		knownSkillPaths.add(skill.path);
+	}
 
 	const disabledTools = new Set(readGlobalSettings().disabledTools ?? []);
 	// Pin spawn/teams availability so this listing matches the hub's
@@ -943,9 +1125,15 @@ async function listUserInstructionConfigs(
 		runtimeCommands,
 		agents: loadAgents(),
 		plugins: hubSettings.plugins.map((plugin) => ({
+			id: plugin.id,
 			name: plugin.name,
 			path: plugin.path,
 			enabled: plugin.enabled !== false,
+			source: plugin.source,
+			toggleable: plugin.toggleable === true,
+			agentPlugin: plugin.agentPlugin === true,
+			description: plugin.description,
+			loadError: plugin.loadError,
 			contributions: plugin.contributions,
 		})),
 		tools: [
@@ -1276,6 +1464,45 @@ export async function handleCommand(
 		return "";
 	}
 
+	// ── Managed hub upgrade ───────────────────────────────────────────
+	if (command === "hub_upgrade") {
+		// Replacing the shared Hub interrupts other clients' sessions, so it
+		// carries the same per-connection gate as the tool-approval commands:
+		// only the webview connection dialed with the approval token may ask,
+		// never an arbitrary local WebSocket client.
+		if (!options?.connection?.data?.canApproveTools) {
+			throw new Error("hub upgrade requires a trusted desktop connection");
+		}
+		// Only reached after the user accepted the blocking "Hub update
+		// required" dialog, so force: the old Hub is replaced even though it
+		// is still serving other clients' sessions. Drain-first semantics
+		// still give in-flight turns the wait window to finish.
+		const result = await upgradeManagedHub({
+			workspaceRoot: ctx.workspaceRoot,
+			force: true,
+			reason: "Cline Desktop hub update",
+		});
+		if (result.outcome === "hub_not_older") {
+			throw new Error(
+				"The running Cline Hub is newer than this app, so it was not replaced. Update Cline instead.",
+			);
+		}
+		if (result.outcome === "still_busy") {
+			throw new Error(
+				"The running Cline Hub picked up new sessions before it could be replaced, so it was left running. Try again.",
+			);
+		}
+		// The mismatch is resolved: a null broadcast closes the dialog in
+		// every connected webview and stops the replay-on-connect.
+		ctx.hubBuildMismatch = null;
+		broadcastEvent(ctx, "hub_build_mismatch", null);
+		return {
+			outcome: result.outcome,
+			url: result.url ?? null,
+			interruptedSessionCount: result.activeSessionCount ?? 0,
+		};
+	}
+
 	// ── Tool approvals (in-memory) ────────────────────────────────────
 	if (command === "poll_tool_approvals") {
 		const sessionId = String(args?.sessionId ?? "").trim();
@@ -1359,11 +1586,105 @@ export async function handleCommand(
 			typeof args?.limit === "number" ? args.limit : 300,
 		);
 	}
+	if (command === "search_sessions") {
+		const query = String(args?.query ?? "").trim();
+		if (!query) return [];
+		const limit =
+			typeof args?.limit === "number" && Number.isFinite(args.limit)
+				? Math.max(1, Math.min(200, Math.trunc(args.limit)))
+				: 50;
+		const workspaceRoot =
+			typeof args?.workspaceRoot === "string"
+				? args.workspaceRoot.trim() || undefined
+				: undefined;
+		if (ctx.hubClient) {
+			try {
+				const reply = await withSearchDeadline(
+					ctx.hubClient.command("session.search", {
+						query,
+						limit,
+						workspaceRoot,
+					}),
+					750,
+				);
+				if (
+					reply.ok &&
+					Array.isArray(reply.payload?.hits) &&
+					reply.payload.hits.length > 0
+				) {
+					return reply.payload.hits.slice(0, limit).map((hit) => ({
+						...hit,
+						title: formatSessionSearchTitle(hit.title),
+						snippet: formatSessionSearchPreview(hit.role, hit.snippet),
+					}));
+				}
+			} catch {
+				// Fall back to metadata-only search when the index is unavailable.
+			}
+		}
+
+		const sessions = await withSearchDeadline(
+			listSessionsFromSidecarManager(ctx, 500),
+			1_000,
+		).catch(() => []);
+		return metadataSessionSearchHits(sessions, query).slice(0, limit);
+	}
 	if (command === "get_discovered_session") {
 		const sessionId = String(args?.sessionId ?? args?.session_id ?? "").trim();
 		if (!sessionId) throw new Error("session id is required");
 		return (await getSessionFromSidecarManager(ctx, sessionId)) ?? null;
 	}
+
+	// ── Session import from other coding tools ────────────────────────
+	if (command === "list_importable_sessions") {
+		const backend = await resolveSessionBackend({ backendMode: "local" });
+		const importer = new SessionImportService(backend);
+		return {
+			installedTools: importer.installedTools(),
+			sessions: await importer.discover(),
+		};
+	}
+	if (command === "import_sessions") {
+		const rawSelections = Array.isArray(args?.selections)
+			? args.selections
+			: [];
+		const requests: SessionImportRequest[] = [];
+		for (const selection of rawSelections) {
+			if (!selection || typeof selection !== "object") continue;
+			const tool = String((selection as JsonRecord).tool ?? "").trim();
+			const sourceId = String((selection as JsonRecord).sourceId ?? "").trim();
+			if (!sourceId) continue;
+			if (!(SESSION_IMPORT_TOOLS as readonly string[]).includes(tool)) {
+				continue;
+			}
+			requests.push({ tool: tool as SessionImportTool, sourceId });
+		}
+		if (requests.length === 0) {
+			throw new Error("at least one { tool, sourceId } selection is required");
+		}
+		const backend = await resolveSessionBackend({ backendMode: "local" });
+		const importer = new SessionImportService(backend);
+		// Opening a history session resumes on the row's provider/model, so the
+		// UI passes what a new chat would run on; the source tool's own
+		// provider/model stay in metadata.importedFrom.
+		// Never let the source tool's provider become the resume target: when
+		// the caller sends no selection, use the app default like other
+		// server-started sessions do.
+		const provider = asTrimmedString(args?.provider) ?? "cline";
+		const model = asTrimmedString(args?.model) ?? CLINE_DEFAULT_MODEL_ID;
+		const results = await importer.importMany(
+			requests,
+			(result, index) => {
+				broadcastEvent(ctx, "session_import_progress", {
+					index,
+					total: requests.length,
+					result,
+				});
+			},
+			{ provider, model },
+		);
+		return { results };
+	}
 	if (command === "update_chat_session_title") {
 		const sessionId = String(args?.sessionId ?? "").trim();
 		if (!sessionId) throw new Error("session id is required");
@@ -1403,7 +1724,7 @@ export async function handleCommand(
 		const result = await backend.updateSession({ sessionId, metadata: merged });
 		if (!result.updated) throw new Error(`Session ${sessionId} not found`);
 		// Annotating a session is not session activity. updateSession stamps
-		// updated_at, which clients sort and label rows by, so a favorite would
+		// updated_at, which clients sort and label rows by, so a pin would
 		// otherwise make an old session look like it just ran.
 		if (existing?.updatedAt) {
 			store.run("UPDATE sessions SET updated_at = ? WHERE session_id = ?", [
@@ -1548,6 +1869,11 @@ export async function handleCommand(
 		// would be captured as error telemetry and shown raw to the user.
 		const authToken = await resolveFreshClineAuthToken(ctx, manager);
 		if (!authToken) {
+			// Backstop for credentials that go away without a settings write —
+			// an expired or server-revoked token. Explicit sign-out is handled
+			// at its source in `save_provider_settings`; this catches the rest
+			// so a stale account never keeps serving its rollout cohort.
+			syncSignedOutAccountContext(ctx);
 			return CLINE_ACCOUNT_NOT_AUTHENTICATED_RESULT;
 		}
 		const settings = manager.getProviderSettings("cline");
@@ -1556,10 +1882,43 @@ export async function handleCommand(
 				settings?.baseUrl?.trim() || getClineEnvironmentConfig().apiBaseUrl,
 			getAuthToken: async () => authToken,
 		});
-		return await executeClineAccountAction(
+		const result = await executeClineAccountAction(
 			args as ClineAccountActionRequest,
 			accountService,
 		);
+		syncAccountContextFromResult(ctx, manager, operation, result);
+		return result;
+	}
+
+	// ── Cline integrations (GitHub App) ────────────────────────────────
+	if (command === "cline_integrations") {
+		const operation = String(args?.operation ?? "").trim();
+		if (!operation) throw new Error("operation is required");
+		const manager = new ProviderSettingsManager();
+
+		const authToken = await resolveFreshClineAuthToken(ctx, manager);
+		if (!authToken) {
+			return CLINE_ACCOUNT_NOT_AUTHENTICATED_RESULT;
+		}
+		const settings = manager.getProviderSettings("cline");
+		const environment = getClineEnvironmentConfig();
+		const requestOptions = {
+			apiBaseUrl: settings?.baseUrl?.trim() || environment.apiBaseUrl,
+			appBaseUrl: environment.appBaseUrl,
+			authToken,
+		};
+		switch (operation) {
+			case "list":
+				return await listClineIntegrations(requestOptions);
+			case "listGitHubRepositories":
+				return await listClineGitHubRepositories(requestOptions);
+			case "githubInstallUrl":
+				return await resolveGitHubInstallUrl(requestOptions);
+			default:
+				throw new Error(
+					`Unsupported Cline integrations operation: ${operation}`,
+				);
+		}
 	}
 
 	// ── Provider management ────────────────────────────────────────────
@@ -1718,13 +2077,21 @@ export async function handleCommand(
 	}
 	if (command === "save_provider_settings") {
 		const manager = new ProviderSettingsManager();
-		return saveLocalProviderSettings(manager, {
+		const saved = saveLocalProviderSettings(manager, {
 			...readProviderSettingsUpdate(args),
 			providerId: String(args?.provider ?? ""),
 			enabled: typeof args?.enabled === "boolean" ? args.enabled : undefined,
 			apiKey: typeof args?.api_key === "string" ? args.api_key : undefined,
 			baseUrl: typeof args?.base_url === "string" ? args.base_url : undefined,
 		});
+		// Sign-out is a `save_provider_settings` that blanks the cline auth block
+		// (see signOut in webview settings/account-view.tsx), so this is the
+		// authoritative signal — it fires the moment credentials are cleared
+		// rather than waiting for the next account fetch.
+		if (saved.providerId === "cline" || saved.providerId === "cline-pass") {
+			syncAccountContextFromSettings(ctx, manager);
+		}
+		return saved;
 	}
 	if (command === "add_provider") {
 		const manager = new ProviderSettingsManager();
@@ -1790,7 +2157,16 @@ export async function handleCommand(
 					);
 				});
 			},
-			{ owner: options?.connection },
+			{
+				owner: options?.connection,
+				// Push the device sign-in confirmation code so the webview can
+				// show it while the user confirms it in the browser.
+				onUserCode: (userCode) =>
+					broadcastEvent(ctx, "provider_oauth_user_code", {
+						provider: providerId,
+						userCode,
+					}),
+			},
 		);
 	}
 	if (command === "cancel_provider_oauth_login") {
@@ -1827,6 +2203,18 @@ export async function handleCommand(
 		return readGlobalSettings();
 	}
 
+	// ── Feature flags ──────────────────────────────────────────────────
+	// Flags are evaluated here, not in the webview: the sidecar already has
+	// the PostHog key inlined at build time and evaluates against the same
+	// distinct ID it reports telemetry with. The client just reads the
+	// resolved values.
+	if (command === "get_feature_flags") {
+		return await refreshDesktopFeatureFlags({
+			logger: ctx.logger,
+			telemetry: ctx.telemetry,
+		});
+	}
+
 	// ── Connector channels ─────────────────────────────────────────────
 	if (command === "list_connector_channels") {
 		return connectorChannelsPayload();

apps/examples/desktop-app/sidecar/context.test.ts

@@ -210,6 +210,157 @@ describe("Code sidecar runtime capabilities", () => {
 		expect(connectMock).toHaveBeenCalledOnce();
 	});
 
+	it("returns indexed search results without listing every session", async () => {
+		const { handleCommand } = await import("./commands");
+		const { createSidecarContext } = await import("./context");
+		const ctx = createSidecarContext("/workspace/project");
+		const oversizedPrompt = `<user_input mode="act">${"generate an image ".repeat(3_000)}</user_input>`;
+		const hits = [
+			{
+				sessionId: "session-1",
+				documentId: "session-1:0",
+				ordinal: 0,
+				role: "user",
+				startedAt: "2026-08-27T12:00:00.000Z",
+				workspaceRoot: "/workspace/project",
+				title: oversizedPrompt,
+				snippet: oversizedPrompt,
+				score: -1,
+			},
+		];
+		const command = vi.fn(async () => ({ ok: true, payload: { hits } }));
+		const list = vi.fn(async () => []);
+		ctx.hubClient = { command } as never;
+		ctx.sessionManager = { list } as never;
+
+		const results = (await handleCommand(ctx, "search_sessions", {
+			query: "generate",
+		})) as Array<{ title: string; snippet: string }>;
+		expect(results).toEqual([
+			expect.objectContaining({
+				sessionId: "session-1",
+				documentId: "session-1:0",
+			}),
+		]);
+		expect(results[0]?.title.length).toBeLessThanOrEqual(240);
+		expect(results[0]?.snippet.length).toBeLessThanOrEqual(480);
+		expect(results[0]?.title).not.toContain("user_input");
+		expect(results[0]?.snippet).not.toContain("user_input");
+		expect(command).toHaveBeenCalledWith("session.search", {
+			query: "generate",
+			limit: 50,
+			workspaceRoot: undefined,
+		});
+		expect(list).not.toHaveBeenCalled();
+	});
+
+	it("falls back to session metadata while the index has no hits", async () => {
+		const { handleCommand } = await import("./commands");
+		const { createSidecarContext } = await import("./context");
+		const ctx = createSidecarContext("/workspace/project");
+		const command = vi.fn(async () => ({ ok: true, payload: { hits: [] } }));
+		const oversizedPrompt = `<user_input mode="act">${"generate an image ".repeat(3_000)}</user_input>`;
+		const list = vi.fn(async () => [
+			{
+				sessionId: "session-1",
+				startedAt: "2026-08-27T12:00:00.000Z",
+				workspaceRoot: "/workspace/project",
+				prompt: oversizedPrompt,
+				metadata: { title: oversizedPrompt },
+			},
+		]);
+		ctx.hubClient = { command } as never;
+		ctx.sessionManager = { list } as never;
+
+		const results = (await handleCommand(ctx, "search_sessions", {
+			query: "generate",
+		})) as Array<{ title: string; snippet: string }>;
+		expect(results).toEqual([
+			expect.objectContaining({
+				sessionId: "session-1",
+				documentId: "session-1:metadata",
+			}),
+		]);
+		expect(results[0]?.title.length).toBeLessThanOrEqual(240);
+		expect(results[0]?.snippet.length).toBeLessThanOrEqual(480);
+		expect(results[0]?.title).not.toContain("user_input");
+		expect(results[0]?.snippet).not.toContain("user_input");
+		expect(list).toHaveBeenCalledOnce();
+	});
+
+	it("falls back to session metadata when the hub search call rejects", async () => {
+		const { handleCommand } = await import("./commands");
+		const { createSidecarContext } = await import("./context");
+		const ctx = createSidecarContext("/workspace/project");
+		const command = vi.fn(async () => {
+			throw new Error("hub connection lost");
+		});
+		const list = vi.fn(async () => [
+			{
+				sessionId: "session-1",
+				startedAt: "2026-08-27T12:00:00.000Z",
+				workspaceRoot: "/workspace/project",
+				prompt: "generate an image of a puppy",
+				metadata: { title: "generate an image of a puppy" },
+			},
+		]);
+		ctx.hubClient = { command } as never;
+		ctx.sessionManager = { list } as never;
+
+		const results = (await handleCommand(ctx, "search_sessions", {
+			query: "generate",
+		})) as Array<{ sessionId: string; documentId: string }>;
+
+		expect(results).toEqual([
+			expect.objectContaining({
+				sessionId: "session-1",
+				documentId: "session-1:metadata",
+			}),
+		]);
+		expect(command).toHaveBeenCalledOnce();
+		expect(list).toHaveBeenCalledOnce();
+	});
+
+	it("falls back to session metadata when the hub search call exceeds the deadline", async () => {
+		vi.useFakeTimers();
+		try {
+			const { handleCommand } = await import("./commands");
+			const { createSidecarContext } = await import("./context");
+			const ctx = createSidecarContext("/workspace/project");
+			// Never resolves: exercises the withSearchDeadline race timing out
+			// rather than the hub call rejecting.
+			const command = vi.fn(() => new Promise(() => {}));
+			const list = vi.fn(async () => [
+				{
+					sessionId: "session-1",
+					startedAt: "2026-08-27T12:00:00.000Z",
+					workspaceRoot: "/workspace/project",
+					prompt: "generate an image of a puppy",
+					metadata: { title: "generate an image of a puppy" },
+				},
+			]);
+			ctx.hubClient = { command } as never;
+			ctx.sessionManager = { list } as never;
+
+			const pending = handleCommand(ctx, "search_sessions", {
+				query: "generate",
+			}) as Promise<Array<{ sessionId: string; documentId: string }>>;
+			await vi.advanceTimersByTimeAsync(750);
+			const results = await pending;
+
+			expect(results).toEqual([
+				expect.objectContaining({
+					sessionId: "session-1",
+					documentId: "session-1:metadata",
+				}),
+			]);
+			expect(command).toHaveBeenCalledOnce();
+			expect(list).toHaveBeenCalledOnce();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
 	it("forwards raw hub tool updates to attached desktop sessions", async () => {
 		const { createSidecarContext, handleHubLiveEvent } = await import(
 			"./context"
@@ -929,6 +1080,7 @@ describe("Code sidecar runtime capabilities", () => {
 			schedule: { scheduleId: "schedule-1", enabled: false },
 		});
 		expect(hubCommandMock).toHaveBeenCalledWith("schedule.disable", {
+			allWorkspaces: true,
 			scheduleId: "schedule-1",
 		});
 	});
@@ -1041,6 +1193,33 @@ describe("Code sidecar runtime capabilities", () => {
 			},
 		]);
 	});
+
+	it("forwards Hub settings changes so open desktop views can refresh", async () => {
+		const { createSidecarContext, handleHubLiveEvent } = await import(
+			"./context"
+		);
+		const ctx = createSidecarContext("/workspace/project");
+		ctx.wsClients.add({ send: vi.fn() } as never);
+
+		handleHubLiveEvent(ctx, {
+			event: "settings.changed",
+			payload: {
+				types: ["plugins", "skills", "mcp"],
+			},
+		});
+
+		expect(readEvents(ctx)).toEqual([
+			{
+				type: "event",
+				event: {
+					name: "settings.changed",
+					payload: {
+						types: ["plugins", "skills", "mcp"],
+					},
+				},
+			},
+		]);
+	});
 });
 
 describe("disposeSidecarContext attachment cleanup", () => {
@@ -1092,3 +1271,276 @@ describe("disposeSidecarContext attachment cleanup", () => {
 		expect(ctx.liveSessions.size).toBe(0);
 	});
 });
+
+describe("Chat chunk pipe selection", () => {
+	async function createStreamingContext(sessionId: string) {
+		const { createSidecarContext } = await import("./context");
+		const ctx = createSidecarContext("/workspace/project");
+		ctx.wsClients.add({ send: vi.fn() });
+		ctx.liveSessions.set(sessionId, {
+			config: {},
+			messages: [],
+			promptsInQueue: [],
+			busy: true,
+			startedAt: Date.now(),
+			status: "running",
+			attachedViaHub: true,
+		});
+		return ctx;
+	}
+
+	function coreTextEvent(sessionId: string, text: string) {
+		return {
+			type: "agent_event",
+			payload: {
+				sessionId,
+				event: { type: "content_start", contentType: "text", text },
+			},
+		} as never;
+	}
+
+	function chunksFor(ctx: SidecarContext, stream: string): string[] {
+		return readEvents(ctx)
+			.filter(
+				(message) =>
+					message.event.name === "chat_event" &&
+					(message.event.payload as { stream?: string }).stream === stream,
+			)
+			.map((message) =>
+				String((message.event.payload as { chunk?: string }).chunk),
+			);
+	}
+
+	it("emits one copy when both pipes carry the same delta", async () => {
+		const { handleCoreSessionEvent, handleHubLiveEvent } = await import(
+			"./context"
+		);
+		const ctx = await createStreamingContext("session-1");
+
+		// Opening a session arms both pipes, so the hub publishes each delta to
+		// the ClineCore session subscription and to the observer client.
+		handleCoreSessionEvent(ctx, coreTextEvent("session-1", "Pack "));
+		handleHubLiveEvent(ctx, {
+			event: "assistant.delta",
+			sessionId: "session-1",
+			payload: { text: "Pack " },
+		});
+		handleCoreSessionEvent(ctx, coreTextEvent("session-1", "my box"));
+		handleHubLiveEvent(ctx, {
+			event: "assistant.delta",
+			sessionId: "session-1",
+			payload: { text: "my box" },
+		});
+
+		expect(chunksFor(ctx, "chat_text")).toEqual(["Pack ", "my box"]);
+	});
+
+	it("still streams sessions only the observer delivers", async () => {
+		const { handleHubLiveEvent } = await import("./context");
+		const ctx = await createStreamingContext("session-1");
+
+		handleHubLiveEvent(ctx, {
+			event: "assistant.delta",
+			sessionId: "session-1",
+			payload: { text: "remote " },
+		});
+		handleHubLiveEvent(ctx, {
+			event: "assistant.delta",
+			sessionId: "session-1",
+			payload: { text: "run" },
+		});
+
+		expect(chunksFor(ctx, "chat_text")).toEqual(["remote ", "run"]);
+	});
+
+	it("stands down for every stream the core pipe serves, not just text", async () => {
+		const { handleCoreSessionEvent, handleHubLiveEvent } = await import(
+			"./context"
+		);
+		const ctx = await createStreamingContext("session-1");
+
+		// One text delta on the core pipe is enough to prove it is subscribed,
+		// so the observer's tool rows are duplicates too.
+		handleCoreSessionEvent(ctx, coreTextEvent("session-1", "working"));
+		handleHubLiveEvent(ctx, {
+			event: "tool.started",
+			sessionId: "session-1",
+			payload: { toolCallId: "call-1", toolName: "run_commands" },
+		});
+
+		expect(chunksFor(ctx, "chat_tool_call_start")).toEqual([]);
+	});
+
+	it("stays stood down through a quiet gap while the run is busy", async () => {
+		vi.useFakeTimers();
+		try {
+			const { handleCoreSessionEvent, handleHubLiveEvent } = await import(
+				"./context"
+			);
+			const ctx = await createStreamingContext("session-1");
+
+			handleCoreSessionEvent(ctx, coreTextEvent("session-1", "local"));
+
+			// A long command or an unanswered tool approval stalls both pipes.
+			// The observer's copy of the first event afterwards still arrives
+			// ahead of the core copy, so it must stay muted for the whole run.
+			vi.advanceTimersByTime(60_000);
+			handleHubLiveEvent(ctx, {
+				event: "tool.started",
+				sessionId: "session-1",
+				payload: { toolCallId: "call-1", toolName: "run_commands" },
+			});
+			handleHubLiveEvent(ctx, {
+				event: "assistant.delta",
+				sessionId: "session-1",
+				payload: { text: "after gap" },
+			});
+
+			expect(chunksFor(ctx, "chat_tool_call_start")).toEqual([]);
+			expect(chunksFor(ctx, "chat_text")).toEqual(["local"]);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("takes over after stop when another client starts the next run", async () => {
+		const { forgetCorePipe, handleCoreSessionEvent, handleHubLiveEvent } =
+			await import("./context");
+		const ctx = await createStreamingContext("session-1");
+
+		handleCoreSessionEvent(ctx, coreTextEvent("session-1", "local"));
+
+		// The desktop stops the session: ClineCore disposes its subscription
+		// without any local `ended` event, so the stop path forgets the mark.
+		forgetCorePipe(ctx, "session-1");
+		const stopped = ctx.liveSessions.get("session-1");
+		if (stopped) stopped.busy = false;
+
+		// Another client (CLI, schedule) runs the session; the observer is the
+		// only pipe left and its run.started marks the session busy again.
+		handleHubLiveEvent(ctx, {
+			event: "run.started",
+			sessionId: "session-1",
+			payload: {},
+		});
+		handleHubLiveEvent(ctx, {
+			event: "assistant.delta",
+			sessionId: "session-1",
+			payload: { text: "remote run" },
+		});
+
+		expect(ctx.liveSessions.get("session-1")?.busy).toBe(true);
+		expect(chunksFor(ctx, "chat_text")).toEqual(["local", "remote run"]);
+	});
+
+	it("takes over once the run has ended and the core pipe goes silent", async () => {
+		vi.useFakeTimers();
+		try {
+			const { handleCoreSessionEvent, handleHubLiveEvent } = await import(
+				"./context"
+			);
+			const ctx = await createStreamingContext("session-1");
+
+			handleCoreSessionEvent(ctx, coreTextEvent("session-1", "local"));
+			handleHubLiveEvent(ctx, {
+				event: "assistant.delta",
+				sessionId: "session-1",
+				payload: { text: "muted" },
+			});
+			expect(chunksFor(ctx, "chat_text")).toEqual(["local"]);
+
+			handleCoreSessionEvent(ctx, {
+				type: "status",
+				payload: { sessionId: "session-1", status: "completed" },
+			} as never);
+			vi.advanceTimersByTime(6_000);
+			handleHubLiveEvent(ctx, {
+				event: "assistant.delta",
+				sessionId: "session-1",
+				payload: { text: "takeover" },
+			});
+
+			expect(chunksFor(ctx, "chat_text")).toEqual(["local", "takeover"]);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("tracks the core pipe per session", async () => {
+		const { createSidecarContext, handleCoreSessionEvent, handleHubLiveEvent } =
+			await import("./context");
+		const ctx = createSidecarContext("/workspace/project");
+		ctx.wsClients.add({ send: vi.fn() });
+		for (const sessionId of ["session-1", "session-2"]) {
+			ctx.liveSessions.set(sessionId, {
+				config: {},
+				messages: [],
+				promptsInQueue: [],
+				busy: true,
+				startedAt: Date.now(),
+				status: "running",
+				attachedViaHub: true,
+			});
+		}
+
+		// ClineCore serves session-1; session-2 is still observer-only.
+		handleCoreSessionEvent(ctx, coreTextEvent("session-1", "one"));
+		handleHubLiveEvent(ctx, {
+			event: "assistant.delta",
+			sessionId: "session-1",
+			payload: { text: "one" },
+		});
+		handleHubLiveEvent(ctx, {
+			event: "assistant.delta",
+			sessionId: "session-2",
+			payload: { text: "two" },
+		});
+
+		expect(chunksFor(ctx, "chat_text")).toEqual(["one", "two"]);
+	});
+
+	it("never drops chunks the sidecar produces itself", async () => {
+		const { broadcastChunk, handleHubLiveEvent } = await import("./context");
+		const ctx = await createStreamingContext("session-1");
+
+		// The observer is serving this session; a locally synthesized chunk is
+		// not part of either relay and must always reach the webview.
+		handleHubLiveEvent(ctx, {
+			event: "assistant.delta",
+			sessionId: "session-1",
+			payload: { text: "remote" },
+		});
+		broadcastChunk(ctx, "session-1", "chat_queued_prompt_start", "{}");
+
+		expect(chunksFor(ctx, "chat_queued_prompt_start")).toEqual(["{}"]);
+	});
+
+	it("stamps chunks with a stable per-process boot id", async () => {
+		const { createSidecarContext, handleHubLiveEvent } = await import(
+			"./context"
+		);
+		const first = await createStreamingContext("session-1");
+		handleHubLiveEvent(first, {
+			event: "assistant.delta",
+			sessionId: "session-1",
+			payload: { text: "a" },
+		});
+		handleHubLiveEvent(first, {
+			event: "assistant.delta",
+			sessionId: "session-1",
+			payload: { text: "b" },
+		});
+
+		const boots = readEvents(first)
+			.filter((message) => message.event.name === "chat_event")
+			.map((message) => (message.event.payload as { boot?: string }).boot);
+		expect(boots).toHaveLength(2);
+		expect(boots[0]).toBeTruthy();
+		expect(boots[1]).toBe(boots[0]);
+
+		// A replacement sidecar restarts `index` at 1, so it must be
+		// distinguishable by boot id.
+		const second = createSidecarContext("/workspace/project");
+		expect(second.bootId).not.toBe(first.bootId);
+	});
+});

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

@@ -26,8 +26,13 @@ import {
 	markQueuedAttachmentsSubmitted,
 	reconcileQueuedAttachments,
 } from "./attachments";
+import {
+	disposeDesktopFeatureFlagsService,
+	getDesktopFeatureFlagsService,
+} from "./feature-flags";
 import { sessionLogPath } from "./paths";
 import type {
+	ChunkSource,
 	LiveSession,
 	PendingAskQuestion,
 	PendingToolApproval,
@@ -110,23 +115,25 @@ export function syncSidecarApprovalReadiness(
 	ctx: SidecarContext,
 ): Promise<void> {
 	const previous = approvalReadinessUpdates.get(ctx) ?? Promise.resolve();
-	const update = previous.catch(() => undefined).then(async () => {
-		const hubClient = ctx.hubClient;
-		if (!hubClient) return;
-		await hubClient.updateCapabilities(
-			[...ctx.wsClients].some(
-				(client) => client.data?.canApproveTools === true,
-			)
-				? [
-						{
-							name: HUB_CLIENT_TOOL_APPROVAL_CAPABILITY,
-							description:
-								"Cline Code has a live user surface for tool review.",
-						},
-					]
-				: [],
-		);
-	});
+	const update = previous
+		.catch(() => undefined)
+		.then(async () => {
+			const hubClient = ctx.hubClient;
+			if (!hubClient) return;
+			await hubClient.updateCapabilities(
+				[...ctx.wsClients].some(
+					(client) => client.data?.canApproveTools === true,
+				)
+					? [
+							{
+								name: HUB_CLIENT_TOOL_APPROVAL_CAPABILITY,
+								description:
+									"Cline Code has a live user surface for tool review.",
+							},
+						]
+					: [],
+			);
+		});
 	approvalReadinessUpdates.set(ctx, update);
 	return update.finally(() => {
 		if (approvalReadinessUpdates.get(ctx) === update) {
@@ -165,13 +172,76 @@ function appendSessionChunk(
 	});
 }
 
+/**
+ * How long an idle session stays "served by ClineCore" after its last event
+ * before the observer projection may take over.
+ *
+ * This window only applies between runs. While a run is busy, silence on the
+ * core pipe is not evidence that its subscription died: a long command, a
+ * slow first token, or a tool-approval prompt the user takes a while to answer
+ * all stall both pipes together. Expiring the mark mid-turn let the observer's
+ * copy of the first post-gap event through ahead of the core copy, doubling a
+ * delta or orphaning a duplicate tool row every time a turn paused for longer
+ * than the window.
+ */
+const CORE_PIPE_ACTIVE_MS = 5_000;
+
+/**
+ * Records that the ClineCore subscription is serving this session.
+ *
+ * The sidecar has two pipes into `emitChunk`: the ClineCore session
+ * subscription and the hub observer client. Opening a session arms both (the
+ * hydrate's `pending_prompts` call makes ClineCore subscribe to the session,
+ * and `attach` sets `attachedViaHub`), so for a session streaming through the
+ * hub each delta arrived twice — and since both copies go through `emitChunk`
+ * each gets its own increasing `index`, which is exactly what the webview's
+ * replay guard compares, so it could not tell them apart.
+ *
+ * The two pipes are not peers: ClineCore's subscription is the primary, and
+ * the observer projection exists to cover sessions ClineCore is not subscribed
+ * to. Any event on the primary proves it is subscribed, so it is the primary
+ * that decides — no list of which streams happen to overlap.
+ */
+function markCorePipeActive(ctx: SidecarContext, sessionId: string): void {
+	ctx.coreStreamActivity.set(sessionId, nowMs());
+}
+
+/**
+ * Forget that the ClineCore subscription served this session. Called when the
+ * session ends and wherever the sidecar stops a session: `stop` disposes the
+ * core subscription without any local `ended` event, and a stale mark would
+ * otherwise mute the observer for the next run another client starts on the
+ * same session, since that run's `run.started` marks the session busy.
+ */
+export function forgetCorePipe(ctx: SidecarContext, sessionId: string): void {
+	ctx.coreStreamActivity.delete(sessionId);
+}
+
+function isCorePipeActive(
+	ctx: SidecarContext,
+	sessionId: string,
+	now: number,
+): boolean {
+	const lastEventAt = ctx.coreStreamActivity.get(sessionId);
+	if (lastEventAt === undefined) return false;
+	// The mark is cleared when the session ends, so during a busy run it means
+	// the core subscription served this session and is still the pipe to trust
+	// even when neither pipe has had anything to deliver for a while.
+	if (ctx.liveSessions.get(sessionId)?.busy) return true;
+	return now - lastEventAt <= CORE_PIPE_ACTIVE_MS;
+}
+
 function emitChunk(
 	ctx: SidecarContext,
 	sessionId: string,
 	stream: string,
 	chunk: string,
+	source: ChunkSource = "core",
 ): void {
 	const ts = nowMs();
+	if (source === "observer" && isCorePipeActive(ctx, sessionId, ts)) {
+		return;
+	}
 	appendSessionChunk(sessionId, stream, chunk, ts);
 	const nextIndex = (ctx.streamIndices.get(sessionId) ?? 0) + 1;
 	ctx.streamIndices.set(sessionId, nextIndex);
@@ -181,6 +251,7 @@ function emitChunk(
 		chunk,
 		ts,
 		index: nextIndex,
+		boot: ctx.bootId,
 	});
 }
 
@@ -338,6 +409,7 @@ function handleAgentEvent(
 					message: event.message,
 					noticeType: event.noticeType,
 					reason: event.reason,
+					metadata: event.metadata,
 				}),
 			);
 			break;
@@ -361,6 +433,7 @@ function handleAgentEvent(
 			break;
 		}
 		case "done": {
+			cancelSidecarMistakeQuestions(ctx, sessionId, "Run ended");
 			const session = ctx.liveSessions.get(sessionId);
 			if (session) {
 				session.busy = false;
@@ -395,7 +468,19 @@ function handleAgentEvent(
 			);
 			break;
 		}
-		case "iteration_start":
+		case "iteration_start": {
+			const session = ctx.liveSessions.get(sessionId);
+			if (session) {
+				// Iterations restart at one for each user run. Keep the previous
+				// answer only within the run in which it was supplied.
+				if (event.iteration === 1 || !session.mistakeRecovery) {
+					session.mistakeRecovery = { latestIteration: event.iteration };
+				} else {
+					session.mistakeRecovery.latestIteration = event.iteration;
+				}
+			}
+			break;
+		}
 		case "iteration_end":
 			break;
 	}
@@ -438,6 +523,29 @@ export function handleCoreSessionEvent(
 	ctx: SidecarContext,
 	event: CoreSessionEvent,
 ): void {
+	// Reaching here at all means ClineCore is subscribed to the session, so its
+	// projection is live and the observer's copy of the same hub events would
+	// be a duplicate. Marked from the pipe itself rather than from `emitChunk`,
+	// so chunks the sidecar synthesizes locally never claim to be this pipe.
+	//
+	// Deliberately every event, not just the content-bearing ones: the hub
+	// fans out to listeners in registration order, and the observer's global
+	// subscription is registered at sidecar boot while this per-session one
+	// arrives at hydrate — so the observer sees each delta first. Waiting for
+	// core content to mark the pipe would let the observer's copy of a turn's
+	// first delta through before the mark existed, doubling it every turn.
+	// The cost is the reverse case: if this pipe delivers a status or queue
+	// event and then stops while the observer keeps streaming, the observer is
+	// held off for the rest of the run (and `CORE_PIPE_ACTIVE_MS` after it).
+	// That needs the subscription torn down mid-turn, which only stop and
+	// detach do, and the turn-end reconcile restores the gap from canonical
+	// history — where doubling would be visible on every turn.
+	const eventSessionId = (event.payload as { sessionId?: string } | undefined)
+		?.sessionId;
+	if (eventSessionId) {
+		markCorePipeActive(ctx, eventSessionId);
+	}
+
 	switch (event.type) {
 		case "chunk": {
 			const { sessionId, stream, chunk } = event.payload;
@@ -514,6 +622,7 @@ export function handleCoreSessionEvent(
 		}
 		case "ended": {
 			const { sessionId, reason } = event.payload;
+			cancelSidecarMistakeQuestions(ctx, sessionId, "Session ended");
 			const session = ctx.liveSessions.get(sessionId);
 			if (session) {
 				session.busy = false;
@@ -521,6 +630,8 @@ export function handleCoreSessionEvent(
 				session.status = reason || "ended";
 			}
 			discardAllTrackedAttachments(sessionId, session);
+			// The next run decides afresh which pipe is serving the session.
+			forgetCorePipe(ctx, sessionId);
 			sendEvent(ctx, "chat_session_ended", { sessionId, reason });
 			break;
 		}
@@ -564,12 +675,15 @@ export function createSidecarContext(
 	observability: {
 		logger?: BasicLogger;
 		telemetry?: ITelemetryService;
+		telemetryUser?: SidecarContext["telemetryUser"];
 	} = {},
 ): SidecarContext {
 	return {
 		liveSessions: new Map(),
 		restoringWorkspacePaths: new Set(),
 		streamIndices: new Map(),
+		coreStreamActivity: new Map(),
+		bootId: randomUUID(),
 		wsClients: new Set(),
 		pendingApprovals: new Map(),
 		pendingQuestions: new Map(),
@@ -578,6 +692,7 @@ export function createSidecarContext(
 		workspaceRoot,
 		logger: observability.logger,
 		telemetry: observability.telemetry,
+		telemetryUser: observability.telemetryUser,
 		unsubscribeSessionEvents: null,
 		hubBuildMismatch: null,
 	};
@@ -627,6 +742,10 @@ export async function disposeSidecarContext(
 		cleanup.push(sessionManager.dispose(reason));
 	}
 
+	// Shuts down the PostHog client the feature flags service owns, flushing
+	// any pending $feature_flag_called events.
+	cleanup.push(disposeDesktopFeatureFlagsService());
+
 	const results = await Promise.allSettled(cleanup);
 	const firstFailure = results.find(
 		(result): result is PromiseRejectedResult => result.status === "rejected",
@@ -714,6 +833,28 @@ export function resolveSidecarAskQuestion(
 	return true;
 }
 
+/** Remove prompts before their session is stopped or replaced in the UI. */
+export function cancelSidecarMistakeQuestions(
+	ctx: SidecarContext,
+	sessionId: string,
+	reason: string,
+): void {
+	for (const pending of ctx.pendingQuestions?.values() ?? []) {
+		if (
+			pending.item.sessionId !== sessionId ||
+			pending.item.context?.agentId !== "desktop-mistake-limit"
+		)
+			continue;
+		ctx.pendingQuestions.delete(pending.item.requestId);
+		if (pending.timeoutId) clearTimeout(pending.timeoutId);
+		pending.reject(new Error(reason));
+		sendEvent(ctx, "ask_question_cancelled", {
+			requestId: pending.item.requestId,
+			reason,
+		});
+	}
+}
+
 export function createSidecarRuntimeCapabilities(
 	ctx: SidecarContext,
 ): RuntimeCapabilities {
@@ -801,6 +942,10 @@ export function handleHubLiveEvent(
 		});
 		return;
 	}
+	if (event.event === "settings.changed") {
+		sendEvent(ctx, event.event, event.payload ?? {});
+		return;
+	}
 
 	const sessionId = typeof event.sessionId === "string" ? event.sessionId : "";
 	if (!sessionId) {
@@ -816,14 +961,20 @@ export function handleHubLiveEvent(
 			const text =
 				typeof event.payload?.text === "string" ? event.payload.text : "";
 			if (text) {
-				emitChunk(ctx, sessionId, "chat_text", text);
+				emitChunk(ctx, sessionId, "chat_text", text, "observer");
 			}
 			return;
 		}
 		case "assistant.media": {
 			const media = event.payload?.media;
 			if (isGeneratedMedia(media)) {
-				emitChunk(ctx, sessionId, "chat_media", JSON.stringify(media));
+				emitChunk(
+					ctx,
+					sessionId,
+					"chat_media",
+					JSON.stringify(media),
+					"observer",
+				);
 			}
 			return;
 		}
@@ -839,6 +990,7 @@ export function handleHubLiveEvent(
 				sessionId,
 				"chat_reasoning",
 				JSON.stringify({ text, redacted }),
+				"observer",
 			);
 			return;
 		}
@@ -858,6 +1010,7 @@ export function handleHubLiveEvent(
 							: "tool",
 					input: event.payload?.input,
 				}),
+				"observer",
 			);
 			return;
 		}
@@ -877,6 +1030,7 @@ export function handleHubLiveEvent(
 							: "tool",
 					update: event.payload?.update,
 				}),
+				"observer",
 			);
 			return;
 		}
@@ -900,6 +1054,7 @@ export function handleHubLiveEvent(
 							? event.payload.error
 							: undefined,
 				}),
+				"observer",
 			);
 			return;
 		}
@@ -1021,6 +1176,10 @@ export async function initializeSessionManager(
 		capabilities: createSidecarRuntimeCapabilities(ctx),
 		logger: ctx.logger,
 		telemetry: ctx.telemetry,
+		featureFlags: getDesktopFeatureFlagsService({
+			logger: ctx.logger,
+			telemetry: ctx.telemetry,
+		}),
 		hub: {
 			strategy: "require-hub",
 			workspaceRoot: ctx.workspaceRoot,

apps/examples/desktop-app/sidecar/feature-flags.test.ts

@@ -0,0 +1,241 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+	buildClinePostHogClient: vi.fn(() => ({ kind: "posthog-client" })),
+	PostHogFeatureFlagsProvider: vi.fn(function PostHogFeatureFlagsProvider(
+		this: Record<string, unknown>,
+		options: unknown,
+	) {
+		this.kind = "posthog";
+		this.options = options;
+	}),
+	NoOpFeatureFlagsProvider: vi.fn(function NoOpFeatureFlagsProvider(
+		this: Record<string, unknown>,
+	) {
+		this.kind = "noop";
+	}),
+	resolveCoreDistinctId: vi.fn(() => "machine-distinct-id"),
+	poll: vi.fn(async () => {}),
+	dispose: vi.fn(async () => {}),
+	setContext: vi.fn(),
+	getFlagPayload: vi.fn((_flag: unknown): unknown => undefined),
+}));
+
+vi.mock("@cline/core", async () => {
+	const actual =
+		await vi.importActual<typeof import("@cline/core")>("@cline/core");
+	return {
+		...actual,
+		// Two known flags keep the snapshot assertions meaningful even as the
+		// real registry changes.
+		FEATURE_FLAGS: ["ext-cline-pass", "ext-demo-flag"],
+		NoOpFeatureFlagsProvider: mocks.NoOpFeatureFlagsProvider,
+		resolveCoreDistinctId: mocks.resolveCoreDistinctId,
+		FeatureFlagsService: class {
+			options: Record<string, unknown>;
+			constructor(options: Record<string, unknown>) {
+				this.options = options;
+			}
+			poll = mocks.poll;
+			dispose = mocks.dispose;
+			setContext = mocks.setContext;
+			getFlagPayload = mocks.getFlagPayload;
+		},
+	};
+});
+
+vi.mock("@cline/core/services/feature-flags/posthog", () => ({
+	buildClinePostHogClient: mocks.buildClinePostHogClient,
+	PostHogFeatureFlagsProvider: mocks.PostHogFeatureFlagsProvider,
+}));
+
+import {
+	buildFeatureFlagsSnapshot,
+	disposeDesktopFeatureFlagsService,
+	getDesktopFeatureFlagsContext,
+	getDesktopFeatureFlagsService,
+	refreshDesktopFeatureFlags,
+	resetDesktopFeatureFlagsForTesting,
+	setDesktopFeatureFlagsAccountContext,
+} from "./feature-flags";
+
+const originalApiKey = process.env.TELEMETRY_SERVICE_API_KEY;
+const originalIsTest = process.env.IS_TEST;
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	resetDesktopFeatureFlagsForTesting();
+	delete process.env.IS_TEST;
+	delete process.env.E2E_TEST;
+});
+
+afterEach(() => {
+	if (originalApiKey === undefined) {
+		delete process.env.TELEMETRY_SERVICE_API_KEY;
+	} else {
+		process.env.TELEMETRY_SERVICE_API_KEY = originalApiKey;
+	}
+	if (originalIsTest === undefined) {
+		delete process.env.IS_TEST;
+	} else {
+		process.env.IS_TEST = originalIsTest;
+	}
+});
+
+describe("getDesktopFeatureFlagsService", () => {
+	it("uses PostHog when the build-time key is inlined", () => {
+		process.env.TELEMETRY_SERVICE_API_KEY = "phc_key";
+		getDesktopFeatureFlagsService();
+		expect(mocks.PostHogFeatureFlagsProvider).toHaveBeenCalledTimes(1);
+		expect(mocks.buildClinePostHogClient).toHaveBeenCalledWith("phc_key");
+		expect(mocks.NoOpFeatureFlagsProvider).not.toHaveBeenCalled();
+	});
+
+	it("falls back to the no-op provider when no key was inlined", () => {
+		delete process.env.TELEMETRY_SERVICE_API_KEY;
+		getDesktopFeatureFlagsService();
+		expect(mocks.NoOpFeatureFlagsProvider).toHaveBeenCalledTimes(1);
+		expect(mocks.PostHogFeatureFlagsProvider).not.toHaveBeenCalled();
+	});
+
+	it("never calls PostHog under IS_TEST even with a key present", () => {
+		process.env.TELEMETRY_SERVICE_API_KEY = "phc_key";
+		process.env.IS_TEST = "true";
+		getDesktopFeatureFlagsService();
+		expect(mocks.NoOpFeatureFlagsProvider).toHaveBeenCalledTimes(1);
+		expect(mocks.PostHogFeatureFlagsProvider).not.toHaveBeenCalled();
+	});
+
+	it("returns one shared instance so the core and the webview agree", () => {
+		process.env.TELEMETRY_SERVICE_API_KEY = "phc_key";
+		expect(getDesktopFeatureFlagsService()).toBe(
+			getDesktopFeatureFlagsService(),
+		);
+		expect(mocks.PostHogFeatureFlagsProvider).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe("feature flags context", () => {
+	it("defaults to the machine distinct ID under the cline-code client name", () => {
+		const context = getDesktopFeatureFlagsContext();
+		expect(context.clientName).toBe("cline-code");
+		expect(context.distinctId).toBe("machine-distinct-id");
+	});
+
+	it("switches to the account ID once signed in, and pushes it to the service", () => {
+		process.env.TELEMETRY_SERVICE_API_KEY = "phc_key";
+		getDesktopFeatureFlagsService();
+		setDesktopFeatureFlagsAccountContext({
+			id: "acct-1",
+			email: "dev@example.com",
+		});
+		const context = getDesktopFeatureFlagsContext();
+		expect(context.distinctId).toBe("acct-1");
+		expect(context.userId).toBe("acct-1");
+		expect(mocks.setContext).toHaveBeenCalledTimes(1);
+	});
+
+	it("keeps the device identity when the account ID is blank", () => {
+		setDesktopFeatureFlagsAccountContext({ id: "   " });
+		expect(getDesktopFeatureFlagsContext().distinctId).toBe(
+			"machine-distinct-id",
+		);
+	});
+
+	it("clears the account identity on sign-out and falls back to the device", () => {
+		setDesktopFeatureFlagsAccountContext({ id: "acct-1" });
+		expect(getDesktopFeatureFlagsContext().userId).toBe("acct-1");
+
+		expect(setDesktopFeatureFlagsAccountContext({})).toBe(true);
+
+		const context = getDesktopFeatureFlagsContext();
+		expect(context.userId).toBeUndefined();
+		// Must not be left on the signed-out account's ID.
+		expect(context.distinctId).toBe("machine-distinct-id");
+	});
+
+	it("reports no change when the same account is re-confirmed", () => {
+		expect(setDesktopFeatureFlagsAccountContext({ id: "acct-1" })).toBe(true);
+		expect(setDesktopFeatureFlagsAccountContext({ id: "acct-1" })).toBe(false);
+	});
+
+	it("reports no change when signed out twice", () => {
+		expect(setDesktopFeatureFlagsAccountContext({})).toBe(false);
+	});
+
+	it("re-points at the new account when switching accounts", () => {
+		setDesktopFeatureFlagsAccountContext({ id: "acct-1" });
+		expect(setDesktopFeatureFlagsAccountContext({ id: "acct-2" })).toBe(true);
+
+		const context = getDesktopFeatureFlagsContext();
+		expect(context.userId).toBe("acct-2");
+		expect(context.distinctId).toBe("acct-2");
+	});
+});
+
+describe("buildFeatureFlagsSnapshot", () => {
+	it("resolves every known flag so the client needs no defaults", () => {
+		mocks.getFlagPayload.mockImplementation((flag: unknown) =>
+			flag === "ext-cline-pass" ? true : undefined,
+		);
+		const snapshot = buildFeatureFlagsSnapshot(
+			getDesktopFeatureFlagsService() as never,
+		);
+		expect(snapshot.flags).toEqual({
+			"ext-cline-pass": true,
+			// Unreturned flags resolve to false rather than being absent.
+			"ext-demo-flag": false,
+		});
+	});
+
+	it("passes non-boolean payloads through untouched", () => {
+		mocks.getFlagPayload.mockImplementation((flag: unknown) =>
+			flag === "ext-cline-pass" ? { variant: "b", limit: 3 } : false,
+		);
+		const snapshot = buildFeatureFlagsSnapshot(
+			getDesktopFeatureFlagsService() as never,
+		);
+		expect(snapshot.flags["ext-cline-pass"]).toEqual({
+			variant: "b",
+			limit: 3,
+		});
+	});
+});
+
+describe("refreshDesktopFeatureFlags", () => {
+	it("polls before returning the snapshot", async () => {
+		mocks.getFlagPayload.mockReturnValue(true);
+		const snapshot = await refreshDesktopFeatureFlags();
+		expect(mocks.poll).toHaveBeenCalledTimes(1);
+		expect(snapshot.flags["ext-cline-pass"]).toBe(true);
+	});
+
+	it("still returns cached values when the poll fails", async () => {
+		mocks.poll.mockRejectedValueOnce(new Error("offline"));
+		mocks.getFlagPayload.mockReturnValue(false);
+		const logger = { error: vi.fn(), log: vi.fn(), debug: vi.fn() };
+
+		const snapshot = await refreshDesktopFeatureFlags({ logger });
+
+		expect(snapshot.flags["ext-cline-pass"]).toBe(false);
+		expect(logger.error).toHaveBeenCalled();
+	});
+});
+
+describe("disposeDesktopFeatureFlagsService", () => {
+	it("disposes the live service and clears it", async () => {
+		process.env.TELEMETRY_SERVICE_API_KEY = "phc_key";
+		getDesktopFeatureFlagsService();
+		await disposeDesktopFeatureFlagsService();
+		expect(mocks.dispose).toHaveBeenCalledTimes(1);
+
+		// A later call builds a fresh service rather than reusing a disposed one.
+		getDesktopFeatureFlagsService();
+		expect(mocks.PostHogFeatureFlagsProvider).toHaveBeenCalledTimes(2);
+	});
+
+	it("is a no-op when nothing was created", async () => {
+		await expect(disposeDesktopFeatureFlagsService()).resolves.toBeUndefined();
+		expect(mocks.dispose).not.toHaveBeenCalled();
+	});
+});

apps/examples/desktop-app/sidecar/feature-flags.ts

@@ -0,0 +1,171 @@
+import { join } from "node:path";
+import {
+	type BasicLogger,
+	FEATURE_FLAGS,
+	type FeatureFlagPayload,
+	type FeatureFlagsContext,
+	FeatureFlagsService,
+	type ITelemetryService,
+	NoOpFeatureFlagsProvider,
+	resolveCoreDistinctId,
+} from "@cline/core";
+import {
+	buildClinePostHogClient,
+	PostHogFeatureFlagsProvider,
+} from "@cline/core/services/feature-flags/posthog";
+import { resolveClineDataDir } from "@cline/shared/storage";
+
+const DESKTOP_FEATURE_FLAGS_CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+let desktopFeatureFlagsContext: FeatureFlagsContext = {
+	clientName: "cline-code",
+};
+let desktopFeatureFlagsService: FeatureFlagsService | undefined;
+
+function resolveDesktopFeatureFlagsCachePath(): string {
+	return join(resolveClineDataDir(), "cache", "feature-flags.cline-code.json");
+}
+
+function ensureDesktopDistinctId(): string {
+	const distinctId = desktopFeatureFlagsContext.distinctId?.trim();
+	if (distinctId) {
+		return distinctId;
+	}
+	const resolved = resolveCoreDistinctId();
+	desktopFeatureFlagsContext.distinctId = resolved;
+	return resolved;
+}
+
+export function getDesktopFeatureFlagsContext(): FeatureFlagsContext {
+	ensureDesktopDistinctId();
+	return { ...desktopFeatureFlagsContext };
+}
+
+export function getDesktopFeatureFlagsService(options?: {
+	logger?: BasicLogger;
+	telemetry?: ITelemetryService;
+}): FeatureFlagsService {
+	if (!desktopFeatureFlagsService) {
+		const apiKey = process.env.TELEMETRY_SERVICE_API_KEY;
+		const provider =
+			apiKey &&
+			process.env.IS_TEST !== "true" &&
+			process.env.E2E_TEST !== "true"
+				? new PostHogFeatureFlagsProvider({
+						client: buildClinePostHogClient(apiKey),
+						config: {
+							logger: options?.logger,
+						},
+					})
+				: new NoOpFeatureFlagsProvider();
+
+		desktopFeatureFlagsService = new FeatureFlagsService({
+			provider,
+			telemetry: options?.telemetry,
+			logger: options?.logger,
+			context: getDesktopFeatureFlagsContext(),
+			cacheFilePath: resolveDesktopFeatureFlagsCachePath(),
+			persistentCacheMaxAgeMs: DESKTOP_FEATURE_FLAGS_CACHE_MAX_AGE_MS,
+		});
+	}
+
+	return desktopFeatureFlagsService;
+}
+
+export async function disposeDesktopFeatureFlagsService(): Promise<void> {
+	if (!desktopFeatureFlagsService) {
+		return;
+	}
+
+	const current = desktopFeatureFlagsService;
+	desktopFeatureFlagsService = undefined;
+	await current.dispose();
+}
+
+export function setDesktopFeatureFlagsAccountContext(account: {
+	id?: string;
+	email?: string;
+}): boolean {
+	const accountId = account.id?.trim();
+	const previousUserId = desktopFeatureFlagsContext.userId ?? undefined;
+	if (previousUserId === (accountId || undefined)) {
+		return false;
+	}
+
+	if (accountId) {
+		desktopFeatureFlagsContext = {
+			...desktopFeatureFlagsContext,
+			distinctId: accountId,
+			userId: accountId,
+		};
+	} else {
+		// Drop both identifiers; ensureDesktopDistinctId re-resolves the device
+		// ID on the next read rather than leaving the old account's ID behind.
+		const {
+			distinctId: _distinctId,
+			userId: _userId,
+			...rest
+		} = desktopFeatureFlagsContext;
+		desktopFeatureFlagsContext = rest;
+	}
+
+	desktopFeatureFlagsService?.setContext(getDesktopFeatureFlagsContext());
+	return true;
+}
+
+export type FeatureFlagsSnapshot = {
+	flags: Record<string, FeatureFlagPayload>;
+};
+
+export function buildFeatureFlagsSnapshot(
+	service: FeatureFlagsService,
+): FeatureFlagsSnapshot {
+	const flags: Record<string, FeatureFlagPayload> = {};
+	for (const flag of FEATURE_FLAGS) {
+		flags[flag] = service.getFlagPayload(flag) ?? false;
+	}
+	return { flags };
+}
+
+/**
+ * Refresh flags from PostHog, then hand back the resolved snapshot.
+ *
+ * Polling is cheap to call repeatedly.
+ */
+export async function refreshDesktopFeatureFlags(options?: {
+	logger?: BasicLogger;
+	telemetry?: ITelemetryService;
+}): Promise<FeatureFlagsSnapshot> {
+	const service = getDesktopFeatureFlagsService(options);
+	try {
+		await service.poll();
+	} catch (error) {
+		options?.logger?.error?.("Error refreshing desktop feature flags", {
+			error,
+		});
+	}
+	return buildFeatureFlagsSnapshot(service);
+}
+
+export async function identifyDesktopFeatureFlagsAccount(
+	account: { id?: string; email?: string },
+	options?: { logger?: BasicLogger; telemetry?: ITelemetryService },
+): Promise<void> {
+	if (
+		!setDesktopFeatureFlagsAccountContext(account) ||
+		!desktopFeatureFlagsService
+	) {
+		return;
+	}
+
+	try {
+		await desktopFeatureFlagsService.poll();
+	} catch (error) {
+		options?.logger?.error?.("Error polling desktop feature flags", { error });
+	}
+}
+
+export function resetDesktopFeatureFlagsForTesting(): void {
+	desktopFeatureFlagsService = undefined;
+	desktopFeatureFlagsContext = { clientName: "cline-code" };
+}

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

@@ -1,7 +1,10 @@
 import { homedir } from "node:os";
 import {
+	checkManagedHubBuildMismatch,
 	createClineTelemetryServiceConfig,
+	readGlobalSettings,
 	setHomeDirIfUnset,
+	setModelToolEnabledGlobally,
 	watchManagedHubBuildMismatch,
 } from "@cline/core";
 import { captureSdkError, claimHubDaemonProcess } from "@cline/shared";
@@ -65,6 +68,20 @@ async function main() {
 		pid: process.pid,
 	});
 
+	// Web search is opt-in elsewhere in Cline, but the desktop app defaults
+	// it to on. Seed the shared setting only when the user has never set it,
+	// so an explicit off (from any Cline app) stays off. Best-effort: an
+	// unwritable settings file must not block startup over a default.
+	try {
+		if (readGlobalSettings().tools?.web_search === undefined) {
+			setModelToolEnabledGlobally("web_search", true);
+		}
+	} catch (error) {
+		observability.logger.error?.("Failed to seed web search default", {
+			error,
+		});
+	}
+
 	prewarmWorkspaceMetadata(workspaceRoot);
 	observability.logger.log(
 		"Login shell PATH resolution",
@@ -148,6 +165,34 @@ async function main() {
 			broadcastEvent(ctx, "hub_build_mismatch", mismatch);
 		},
 	});
+	// The watcher's first check only runs after its interval, but a mismatch
+	// that already exists at startup - an older Hub this app attached to
+	// because it is still serving other clients' sessions - must prompt
+	// before the user starts working, not half a minute in. Session-manager
+	// init has already settled the hub state, so check once right away. The
+	// broadcast reaches webviews that are already connected; the replay in
+	// createWebSocketHandler covers ones that connect later. Skipped when
+	// CLINE_HUB_PORT pins an explicit endpoint, matching the watcher: such
+	// hosts keep protocol-only compatibility and must not show update prompts.
+	if (!process.env.CLINE_HUB_PORT?.trim()) {
+		void checkManagedHubBuildMismatch()
+			.then((mismatch) => {
+				if (!mismatch || ctx.hubBuildMismatch) {
+					return;
+				}
+				ctx.hubBuildMismatch = mismatch;
+				observability.logger.log(
+					"Managed hub build mismatch detected at startup",
+					{
+						hubBuildId: mismatch.hubBuildId,
+						hubCoreVersion: mismatch.hubCoreVersion,
+						reason: mismatch.reason,
+					},
+				);
+				broadcastEvent(ctx, "hub_build_mismatch", mismatch);
+			})
+			.catch(() => undefined);
+	}
 
 	// 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;

apps/examples/desktop-app/sidecar/marketplace.test.ts

@@ -1,6 +1,7 @@
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { installPlugin } from "@cline/core";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
 	getOfficialPluginInstallPath,
@@ -9,6 +10,15 @@ import {
 } from "./marketplace";
 import type { JsonRecord } from "./types";
 
+// Marketplace plugin installs run in-process through @cline/core (spawning a
+// `cline` binary fails with 'Executable not found in $PATH: "cline"' in the
+// packaged app). Stub only installPlugin; everything else stays real.
+vi.mock(import("@cline/core"), async (importOriginal) => ({
+	...(await importOriginal()),
+	installPlugin: vi.fn(),
+}));
+const installPluginMock = vi.mocked(installPlugin);
+
 const GOAL_ENTRY = {
 	id: "goal",
 	type: "plugin",
@@ -23,6 +33,13 @@ beforeEach(async () => {
 	tempClineDir = await mkdtemp(join(tmpdir(), "desktop-marketplace-"));
 	previousClineDir = process.env.CLINE_DIR;
 	process.env.CLINE_DIR = tempClineDir;
+	installPluginMock.mockReset().mockImplementation(async (options) => ({
+		source: options.source,
+		installPath: goalInstallDir(),
+		entryPaths: [],
+		mcpSyncFailures: [],
+		mcpOAuthCandidates: [],
+	}));
 });
 
 afterEach(async () => {
@@ -43,57 +60,49 @@ function goalInstallDir(): string {
 }
 
 describe("official plugin install detection", () => {
-	it("does not treat a leftover empty install directory as installed", async () => {
-		// Regression: a failed or interrupted install can leave the directory
-		// behind with nothing in it. The next install attempt then returned
-		// "already installed" without running the CLI, so the UI flipped the
-		// entry to Uninstall with no error while nothing actually worked.
-		await mkdir(goalInstallDir(), { recursive: true });
-		const spawnCommand = vi.fn(async () => ({
-			exitCode: 1,
-			stdout: "",
-			stderr: "install exploded",
-		}));
-
-		await expect(
-			installMarketplaceEntry({ entry: GOAL_ENTRY }, { spawnCommand }),
-		).rejects.toThrow(/Plugin install failed/);
-		expect(spawnCommand).toHaveBeenCalledTimes(1);
-	});
-
-	it("passes --force so a retry can reclaim the leftover directory", async () => {
-		// Without --force the CLI refuses to replace the existing path
-		// ("Plugin is already installed at ... Use --force to replace it."),
-		// so every retry from the UI would fail against the stale directory.
-		await mkdir(goalInstallDir(), { recursive: true });
-		const spawnCommand = vi.fn(async (_command: string, _args: string[]) => ({
-			exitCode: 0,
-			stdout: "",
-			stderr: "",
-		}));
-
-		const result = await installMarketplaceEntry(
-			{ entry: GOAL_ENTRY },
-			{ spawnCommand },
-		);
+	it("installs plugins in-process through @cline/core", async () => {
+		const result = await installMarketplaceEntry({ entry: GOAL_ENTRY });
 
 		expect(result).toMatchObject({
 			status: "installed",
 			message: "Installed Goal.",
 		});
-		expect(spawnCommand.mock.calls[0]?.[1]).toContain("--force");
+		expect(installPluginMock).toHaveBeenCalledWith({
+			source: "goal",
+			force: false,
+		});
 	});
 
-	it("does not pass --force for a clean first install", async () => {
-		const spawnCommand = vi.fn(async (_command: string, _args: string[]) => ({
-			exitCode: 0,
-			stdout: "",
-			stderr: "",
-		}));
+	it("does not treat a leftover empty install directory as installed", async () => {
+		// Regression: a failed or interrupted install can leave the directory
+		// behind with nothing in it. The next install attempt then returned
+		// "already installed" without running the installer, so the UI flipped
+		// the entry to Uninstall with no error while nothing actually worked.
+		await mkdir(goalInstallDir(), { recursive: true });
+		installPluginMock.mockRejectedValueOnce(new Error("install exploded"));
 
-		await installMarketplaceEntry({ entry: GOAL_ENTRY }, { spawnCommand });
+		await expect(
+			installMarketplaceEntry({ entry: GOAL_ENTRY }),
+		).rejects.toThrow(/install exploded/);
+		expect(installPluginMock).toHaveBeenCalledTimes(1);
+	});
 
-		expect(spawnCommand.mock.calls[0]?.[1]).not.toContain("--force");
+	it("passes force so a retry can reclaim the leftover directory", async () => {
+		// Without force the installer refuses to replace the existing path
+		// ("Plugin is already installed at ... Use --force to replace it."),
+		// so every retry from the UI would fail against the stale directory.
+		await mkdir(goalInstallDir(), { recursive: true });
+
+		const result = await installMarketplaceEntry({ entry: GOAL_ENTRY });
+
+		expect(result).toMatchObject({
+			status: "installed",
+			message: "Installed Goal.",
+		});
+		expect(installPluginMock).toHaveBeenCalledWith({
+			source: "goal",
+			force: true,
+		});
 	});
 
 	it("still short-circuits when the directory contains a plugin module", async () => {
@@ -111,22 +120,51 @@ describe("official plugin install detection", () => {
 			join(installDir, "package", "index.ts"),
 			"export default {};",
 		);
-		const spawnCommand = vi.fn(async () => ({
-			exitCode: 0,
-			stdout: "",
-			stderr: "",
-		}));
 
-		const result = await installMarketplaceEntry(
-			{ entry: GOAL_ENTRY },
-			{ spawnCommand },
-		);
+		const result = await installMarketplaceEntry({ entry: GOAL_ENTRY });
 
 		expect(result).toMatchObject({
 			status: "installed",
 			message: "Goal is already installed.",
 		});
-		expect(spawnCommand).not.toHaveBeenCalled();
+		expect(installPluginMock).not.toHaveBeenCalled();
+	});
+
+	it("registers MCP servers in-process, honoring the -- args separator", async () => {
+		const settingsPath = join(tempClineDir, "cline_mcp_settings.json");
+		const previousSettingsPath = process.env.CLINE_MCP_SETTINGS_PATH;
+		process.env.CLINE_MCP_SETTINGS_PATH = settingsPath;
+		try {
+			const result = await installMarketplaceEntry({
+				entry: {
+					id: "aikido",
+					type: "mcp",
+					name: "Aikido",
+					install: {
+						args: ["aikido", "--", "npx", "-y", "@aikidosec/mcp@1.0.9"],
+					},
+				},
+			});
+
+			expect(result).toMatchObject({
+				status: "installed",
+				message: "Installed Aikido.",
+			});
+			const settings = JSON.parse(await readFile(settingsPath, "utf8")) as {
+				mcpServers: Record<string, { transport?: unknown }>;
+			};
+			expect(settings.mcpServers.aikido?.transport).toEqual({
+				type: "stdio",
+				command: "npx",
+				args: ["-y", "@aikidosec/mcp@1.0.9"],
+			});
+		} finally {
+			if (previousSettingsPath === undefined) {
+				delete process.env.CLINE_MCP_SETTINGS_PATH;
+			} else {
+				process.env.CLINE_MCP_SETTINGS_PATH = previousSettingsPath;
+			}
+		}
 	});
 
 	it("excludes partial install directories from the installed entries list", async () => {
@@ -149,4 +187,19 @@ describe("official plugin install detection", () => {
 		);
 		expect(populated.installedKeys).toEqual(["plugin:goal"]);
 	});
+
+	it("does not match portable Agent Plugins to Cline marketplace entries", () => {
+		const result = listMarketplaceInstalledEntries({ entries: [GOAL_ENTRY] }, {
+			plugins: [
+				{
+					id: "agent-plugin:goal",
+					name: "goal",
+					path: "/home/user/.agents/plugins/goal",
+					agentPlugin: true,
+				},
+			],
+		} as JsonRecord);
+
+		expect(result.installedKeys).toEqual([]);
+	});
 });

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

@@ -18,8 +18,11 @@ import {
 	resolve,
 } from "node:path";
 import {
+	installPlugin as installCorePlugin,
+	installMcpServer,
 	type MarketplaceActionResult,
 	type MarketplaceEntryInput,
+	parseMcpInstallArgs,
 	resolveSkillsConfigSearchPaths,
 	resolveWorkflowsConfigSearchPaths,
 	uninstallMarketplaceEntry as uninstallCoreMarketplaceEntry,
@@ -457,18 +460,6 @@ export function buildMarketplaceMcpInput(args: string[]): JsonRecord {
 	};
 }
 
-function resolveClineInvocation(): { command: string; argsPrefix: string[] } {
-	const wrapperPath = process.env.CLINE_WRAPPER_PATH?.trim();
-	if (wrapperPath) {
-		return { command: wrapperPath, argsPrefix: [] };
-	}
-	const entry = process.argv[1]?.trim();
-	if (entry && /(?:^|[/\\])apps[/\\]cli[/\\]src[/\\]index\.ts$/.test(entry)) {
-		return { command: process.execPath, argsPrefix: [entry] };
-	}
-	return { command: "cline", argsPrefix: [] };
-}
-
 function isInsidePath(childPath: string, parentPath: string): boolean {
 	const relativePath = relative(resolve(parentPath), resolve(childPath));
 	return (
@@ -723,6 +714,7 @@ function hasMatchingInventoryItem(
 	return items.some((item) => {
 		if (!item || typeof item !== "object") return false;
 		const record = item as JsonRecord;
+		if (record.agentPlugin === true) return false;
 		const values = [
 			typeof record.name === "string" ? record.name : undefined,
 			typeof record.id === "string" ? record.id : undefined,
@@ -823,7 +815,6 @@ async function installSkill(
 
 async function installPlugin(
 	entry: MarketplaceInstallInput,
-	spawnCommand: SpawnCommand,
 ): Promise<MarketplaceInstallResult> {
 	const installArgs = entry.install.args ?? [];
 	if (installArgs.length !== 1) {
@@ -840,41 +831,36 @@ async function installPlugin(
 			message: `${entry.name ?? entry.id} is already installed.`,
 		};
 	}
-	const { command, argsPrefix } = resolveClineInvocation();
-	const result = await spawnCommand(command, [
-		...argsPrefix,
-		"plugin",
-		"install",
-		installArgs[0] ?? "",
-		// Reclaim a leftover directory from a failed or interrupted install:
-		// without --force the CLI refuses to replace the existing path and
-		// every retry from the UI would fail the same way. This is safe
-		// because the state check just confirmed the directory contains no
-		// loadable plugin module.
-		...(installState === "partial" ? ["--force"] : []),
-		"--json",
-	]);
-	if (result.exitCode !== 0) {
-		const output = commandOutput(result);
-		throw new Error(
-			`Plugin install failed with exit code ${result.exitCode}${output ? `:\n${output}` : ""}`,
-		);
-	}
-	let details: JsonRecord | undefined;
-	try {
-		details = result.stdout.trim()
-			? (JSON.parse(result.stdout.trim()) as JsonRecord)
-			: undefined;
-	} catch {
-		details = undefined;
-	}
+	// Install in-process instead of shelling out to a `cline` binary: the
+	// packaged desktop app cannot assume a CLI install exists on the user's
+	// PATH (GUI apps inherit launchd's minimal PATH on macOS), which surfaced
+	// as 'Executable not found in $PATH: "cline"' in the marketplace UI.
+	//
+	// force reclaims a leftover directory from a failed or interrupted
+	// install: without it the installer refuses to replace the existing path
+	// and every retry from the UI would fail the same way. This is safe
+	// because the state check just confirmed the directory contains no
+	// loadable plugin module.
+	const result = await installCorePlugin({
+		source: installArgs[0] ?? "",
+		force: installState === "partial",
+	});
+	const warnings = result.mcpSyncFailures.map(
+		(failure) =>
+			`Failed to sync plugin MCP servers for ${failure.pluginName ?? failure.pluginPath}: ${failure.message}`,
+	);
 	return {
 		id: entry.id,
 		type: entry.type,
 		status: "installed",
 		message: `Installed ${entry.name ?? entry.id}.`,
-		details,
-		output: commandOutput(result),
+		details: {
+			source: result.source,
+			installPath: result.installPath,
+			entryPaths: result.entryPaths,
+			mcpSyncFailures: result.mcpSyncFailures,
+		} as JsonRecord,
+		output: [`Path: ${result.installPath}`, ...warnings].join("\n"),
 	};
 }
 
@@ -885,45 +871,26 @@ export async function installMarketplaceEntry(
 	const entry = readInstallInput(args);
 	const spawnCommand = options.spawnCommand ?? defaultSpawnCommand;
 	if (entry.type === "mcp") {
-		// Validate marketplace args before handing them to the CLI-backed installer.
-		buildMarketplaceMcpInput(entry.install.args ?? []);
-		const { command, argsPrefix } = resolveClineInvocation();
-		const result = await spawnCommand(command, [
-			...argsPrefix,
-			"mcp",
-			"install",
-			"--yes",
-			"--json",
-			...(entry.install.args ?? []),
-		]);
-		if (result.exitCode !== 0) {
-			const output = commandOutput(result);
-			throw new Error(
-				`MCP install failed with exit code ${result.exitCode}${output ? `:\n${output}` : ""}`,
-			);
-		}
-		let details: JsonRecord | undefined;
-		try {
-			details = result.stdout.trim()
-				? (JSON.parse(result.stdout.trim()) as JsonRecord)
-				: undefined;
-		} catch {
-			details = undefined;
-		}
+		// Register the server in-process; this only writes MCP settings, so
+		// there is no reason to depend on a `cline` binary being on PATH.
+		const result = installMcpServer(
+			parseMcpInstallArgs(entry.install.args ?? []),
+		);
 		return {
 			id: entry.id,
 			type: entry.type,
 			status: "installed",
 			message: `Installed ${entry.name ?? entry.id}.`,
-			details,
-			output: commandOutput(result),
+			details: result as unknown as JsonRecord,
+			output:
+				result.warnings.length > 0 ? result.warnings.join("\n") : undefined,
 		};
 	}
 	if (entry.type === "skill") {
 		return installSkill(entry, spawnCommand);
 	}
 	if (entry.type === "plugin") {
-		return installPlugin(entry, spawnCommand);
+		return installPlugin(entry);
 	}
 	throw new Error(`Unsupported marketplace entry type: ${entry.type}`);
 }

apps/examples/desktop-app/sidecar/mcp.test.ts

@@ -14,6 +14,8 @@ function createContext(workspaceRoot: string): SidecarContext {
 		liveSessions: new Map(),
 		restoringWorkspacePaths: new Set(),
 		streamIndices: new Map(),
+		coreStreamActivity: new Map(),
+		bootId: "test-boot",
 		wsClients: new Set(),
 		pendingApprovals: new Map(),
 		pendingQuestions: new Map(),

apps/examples/desktop-app/sidecar/oauth-login.ts

@@ -1,10 +1,13 @@
 import type { ProviderSettingsManager } from "@cline/core";
 import {
+	completeClineDeviceAuth,
 	getProviderAuthStorageId,
 	loginLocalProvider,
 	markLocalProviderEnabled,
 	saveLocalProviderOAuthCredentials,
+	startClineDeviceAuth,
 } from "@cline/core";
+import { getClineEnvironmentConfig } from "@cline/shared";
 
 export class OAuthLoginCancelledError extends Error {
 	constructor(providerId: string) {
@@ -26,13 +29,41 @@ type PendingOAuthLogin = {
 const pendingOAuthLoginsByProvider = new Map<string, PendingOAuthLogin>();
 
 export type OAuthLoginDependencies = {
-	login: typeof loginLocalProvider;
+	login: typeof loginProviderForDesktop;
 	save: typeof saveLocalProviderOAuthCredentials;
 	markEnabled: typeof markLocalProviderEnabled;
 };
 
+/**
+ * Cline account providers sign in with the WorkOS device-code grant, whose
+ * browser page asks the user to confirm a short code. `loginLocalProvider`
+ * runs that flow but discards the code, so use the split helpers instead and
+ * surface the code through `onUserCode` for the UI to display.
+ */
+async function loginProviderForDesktop(
+	providerId: string,
+	existing: Parameters<typeof loginLocalProvider>[1],
+	openUrl: (url: string) => void,
+	onUserCode?: (userCode: string) => void,
+): ReturnType<typeof loginLocalProvider> {
+	if (providerId !== "cline" && providerId !== "cline-pass") {
+		return loginLocalProvider(providerId, existing, openUrl);
+	}
+	const device = await startClineDeviceAuth();
+	onUserCode?.(device.userCode);
+	openUrl(device.verificationUriComplete ?? device.verificationUri);
+	return completeClineDeviceAuth({
+		deviceCode: device.deviceCode,
+		expiresInSeconds: device.expiresInSeconds,
+		pollIntervalSeconds: device.pollIntervalSeconds,
+		apiBaseUrl:
+			existing?.baseUrl?.trim() || getClineEnvironmentConfig().apiBaseUrl,
+		provider: providerId,
+	});
+}
+
 const defaultDependencies: OAuthLoginDependencies = {
-	login: loginLocalProvider,
+	login: loginProviderForDesktop,
 	save: saveLocalProviderOAuthCredentials,
 	markEnabled: markLocalProviderEnabled,
 };
@@ -47,7 +78,11 @@ export async function runCancellableProviderOAuthLogin(
 	manager: ProviderSettingsManager,
 	providerId: string,
 	openUrl: (url: string) => void,
-	options: { owner?: object } = {},
+	options: {
+		owner?: object;
+		/** Receives the device sign-in confirmation code, when the flow has one. */
+		onUserCode?: (userCode: string) => void;
+	} = {},
 	dependencies: OAuthLoginDependencies = defaultDependencies,
 ): Promise<{ provider: string; accessToken: string }> {
 	const storageProviderId = getProviderAuthStorageId(providerId) ?? providerId;
@@ -74,7 +109,7 @@ export async function runCancellableProviderOAuthLogin(
 		// after cancellation is observed and cannot become an unhandled
 		// rejection that kills the sidecar.
 		const credentials = await Promise.race([
-			dependencies.login(providerId, existing, openUrl),
+			dependencies.login(providerId, existing, openUrl, options.onUserCode),
 			cancellation,
 		]);
 		if (entry.cancelled) {

apps/examples/desktop-app/sidecar/observability.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { version } from "../package.json";
 
 const mocks = vi.hoisted(() => ({
 	captureExtensionActivated: vi.fn(),
@@ -28,7 +29,14 @@ vi.mock("@cline/core", async () => {
 		identifyAccount: mocks.identifyAccount,
 		ProviderSettingsManager: class {
 			getProviderSettings() {
-				return { auth: { accountId: "account-1" } };
+				return {
+					auth: {
+						accountId: "account-1",
+						organizationId: "org-1",
+						organizationName: "Acme",
+						memberId: "member-1",
+					},
+				};
 			}
 		},
 		setSdkLogger: mocks.setSdkLogger,
@@ -57,8 +65,10 @@ describe("desktop observability", () => {
 
 		expect(mocks.createClineTelemetryServiceConfig).toHaveBeenCalledWith({
 			metadata: expect.objectContaining({
+				extension_version: version,
 				cline_type: "desktop",
-				platform: "Cline",
+				platform: "Cline Desktop",
+				platform_version: version,
 			}),
 		});
 		expect(mocks.createConfiguredTelemetryHandle).toHaveBeenCalledWith(
@@ -67,9 +77,18 @@ describe("desktop observability", () => {
 		expect(mocks.identifyAccount).toHaveBeenCalledWith(telemetry, {
 			id: "account-1",
 			provider: "cline",
+			organizationId: "org-1",
+			organizationName: "Acme",
+			memberId: "member-1",
 		});
 		expect(mocks.captureExtensionActivated).toHaveBeenCalledWith(telemetry);
 		expect(mocks.setSdkLogger).toHaveBeenCalledWith(logger);
+		expect(observability.telemetryUser).toEqual({
+			distinctId: "account-1",
+			accountId: "account-1",
+			email: undefined,
+			organizationId: "org-1",
+		});
 
 		await observability.dispose();
 		await observability.dispose();

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

@@ -1,4 +1,3 @@
-import * as os from "node:os";
 import {
 	captureExtensionActivated,
 	createClineTelemetryServiceConfig,
@@ -8,7 +7,12 @@ import {
 	ProviderSettingsManager,
 	setSdkLogger,
 } from "@cline/core";
-import { version } from "../package.json";
+import type { UserContext } from "@cline/shared";
+import {
+	DESKTOP_TELEMETRY_METADATA,
+	resolveDesktopTelemetryUser,
+} from "./client-context";
+import { setDesktopFeatureFlagsAccountContext } from "./feature-flags";
 import {
 	createDesktopLoggerAdapter,
 	type DesktopLoggerAdapter,
@@ -17,6 +21,7 @@ import {
 export interface DesktopObservability {
 	readonly logger: DesktopLoggerAdapter["core"];
 	readonly telemetry: ITelemetryService;
+	readonly telemetryUser?: UserContext;
 	dispose(): Promise<void>;
 }
 
@@ -27,24 +32,25 @@ export function createDesktopObservability(): DesktopObservability {
 
 	const telemetryHandle = createConfiguredTelemetryHandle({
 		...createClineTelemetryServiceConfig({
-			metadata: {
-				extension_version: version,
-				cline_type: "desktop",
-				platform: "Cline",
-				platform_version: process.version,
-				os_type: os.platform(),
-				os_version: os.version(),
-			},
+			metadata: DESKTOP_TELEMETRY_METADATA,
 		}),
 		logger,
 	});
 	const telemetry = telemetryHandle.telemetry;
 	const auth = new ProviderSettingsManager().getProviderSettings("cline")?.auth;
+	const telemetryUser = resolveDesktopTelemetryUser({
+		accountId: auth?.accountId,
+		organizationId: auth?.organizationId,
+	});
 	if (auth?.accountId) {
 		identifyAccount(telemetry, {
 			id: auth.accountId,
 			provider: "cline",
+			organizationId: auth.organizationId,
+			organizationName: auth.organizationName,
+			memberId: auth.memberId,
 		});
+		setDesktopFeatureFlagsAccountContext({ id: auth.accountId });
 	}
 	captureExtensionActivated(telemetry);
 
@@ -52,6 +58,7 @@ export function createDesktopObservability(): DesktopObservability {
 	return {
 		logger,
 		telemetry,
+		telemetryUser,
 		async dispose() {
 			if (disposed) return;
 			disposed = true;

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

@@ -8,6 +8,7 @@ import type {
 	ToolApprovalResult,
 } from "@cline/core";
 import type { MessageWithMetadata } from "@cline/llms";
+import type { UserContext } from "@cline/shared";
 
 export type JsonRecord = Record<string, unknown>;
 
@@ -60,6 +61,11 @@ export type LiveSession = {
 	prompt?: string;
 	title?: string;
 	attachedViaHub?: boolean;
+	/** Iterations already in flight when the user supplied recovery guidance. */
+	mistakeRecovery?: {
+		latestIteration: number;
+		continuedThroughIteration?: number;
+	};
 	/** Materialized attachment files for prompts still waiting in the queue. */
 	queuedAttachmentFiles?: Map<string, string[]>;
 	/** Last prompt id announced via chat_queued_prompt_start, to dedupe emits. */
@@ -111,10 +117,29 @@ export type SidecarWebSocketClient = {
 	close?: () => void;
 };
 
+/**
+ * Which pipe produced a chat chunk. Both feed `emitChunk`, and for a session
+ * streaming through the hub both carry the same events, so the observer's copy
+ * is dropped while the ClineCore subscription is serving that session.
+ */
+export type ChunkSource = "core" | "observer";
+
 export type SidecarContext = {
 	liveSessions: Map<string, LiveSession>;
 	restoringWorkspacePaths: Set<string>;
 	streamIndices: Map<string, number>;
+	/**
+	 * When the ClineCore subscription last delivered an event for a session, so
+	 * the observer projection can stand down while it is serving and take over
+	 * again if it stops.
+	 */
+	coreStreamActivity: Map<string, number>;
+	/**
+	 * Identifies this sidecar process. `streamIndices` restarts whenever the
+	 * sidecar does, so the webview needs to tell "index 1 of a new process"
+	 * apart from a replay of the run it already rendered.
+	 */
+	bootId: string;
 	wsClients: Set<SidecarWebSocketClient>;
 	pendingApprovals: Map<string, PendingToolApproval>;
 	pendingQuestions: Map<string, PendingAskQuestion>;
@@ -123,6 +148,8 @@ export type SidecarContext = {
 	workspaceRoot: string;
 	logger?: BasicLogger;
 	telemetry?: ITelemetryService;
+	/** Analytics identity and explicit account state forwarded with each session. */
+	telemetryUser?: UserContext;
 	unsubscribeSessionEvents: (() => void) | null;
 	/**
 	 * Latest managed Hub build mismatch, broadcast as `hub_build_mismatch` and

apps/examples/desktop-app/src-tauri/Info.plist

@@ -4,5 +4,7 @@
 <dict>
 	<key>NSMicrophoneUsageDescription</key>
 	<string>Cline uses the microphone to transcribe speech into chat input.</string>
+	<key>NSSpeechRecognitionUsageDescription</key>
+	<string>Cline uses speech recognition to turn your voice into chat input.</string>
 </dict>
 </plist>

apps/examples/desktop-app/src-tauri/capabilities/default.json

@@ -5,6 +5,10 @@
 	"windows": ["main"],
 	"permissions": [
 		"core:default",
+		"core:window:allow-close",
+		"core:window:allow-is-maximized",
+		"core:window:allow-minimize",
+		"core:window:allow-toggle-maximize",
 		"core:window:allow-set-title",
 		"core:window:allow-start-dragging",
 		"notification:default"

apps/examples/desktop-app/src-tauri/entitlements.plist

@@ -9,5 +9,8 @@
 	<true/>
 	<key>com.apple.security.cs.disable-library-validation</key>
 	<true/>
+	<!-- Voice input requires audio capture access when Hardened Runtime is enabled. -->
+	<key>com.apple.security.device.audio-input</key>
+	<true/>
 </dict>
 </plist>

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

@@ -9,7 +9,8 @@ use std::fs;
 use std::io::{BufRead, BufReader};
 use std::path::{Path, PathBuf};
 use std::process::{Child, Command, Stdio};
-use std::sync::{Arc, Mutex};
+use std::sync::atomic::{AtomicBool, Ordering as AtomicOrdering};
+use std::sync::{Arc, Mutex, MutexGuard};
 use std::thread;
 use std::time::Duration;
 #[cfg(target_os = "macos")]
@@ -112,6 +113,12 @@ struct UpdateState {
     // concurrently and the later one can overwrite a freshly staged "ready"
     // with "idle"/"error" decided from its stale pre-await snapshot.
     cycle: tokio::sync::Mutex<()>,
+    // Windows only: the downloaded-but-not-installed update. On Windows,
+    // Update::install launches the NSIS installer and std::process::exit(0)s
+    // immediately, so installation must wait for the user-initiated restart
+    // instead of running inside the background cycle like it does on macOS.
+    #[cfg(windows)]
+    pending_install: Mutex<Option<(tauri_plugin_updater::Update, Vec<u8>)>>,
 }
 
 impl UpdateState {
@@ -224,12 +231,30 @@ async fn check_and_install_update(app: &tauri::AppHandle, state: &UpdateState) {
                 return;
             }
             set_update_status(app, state, "downloading", Some(version.clone()), None);
+            // macOS: install right away — it only swaps the .app on disk and
+            // the running app keeps going until the user restarts. Windows:
+            // download only, because install() launches the NSIS installer
+            // and exits the process on the spot; the staged bytes are
+            // installed by restart_to_apply_update instead.
+            #[cfg(not(windows))]
             match update.download_and_install(|_, _| {}, || {}).await {
                 Ok(()) => set_update_status(app, state, "ready", Some(version), None),
                 Err(error) => {
                     set_update_status(app, state, "error", Some(version), Some(error.to_string()))
                 }
             }
+            #[cfg(windows)]
+            match update.download(|_, _| {}, || {}).await {
+                Ok(bytes) => {
+                    if let Ok(mut pending) = state.pending_install.lock() {
+                        *pending = Some((update, bytes));
+                    }
+                    set_update_status(app, state, "ready", Some(version), None);
+                }
+                Err(error) => {
+                    set_update_status(app, state, "error", Some(version), Some(error.to_string()))
+                }
+            }
         }
         Ok(None) => {
             if ready_version.is_none() {
@@ -259,51 +284,35 @@ async fn run_update_loop(app: tauri::AppHandle, state: Arc<UpdateState>) {
 struct DesktopBackendState {
     ws_endpoint: Mutex<Option<String>>,
     process: Mutex<Option<Child>>,
-    shutting_down: Mutex<bool>,
+    shutting_down: AtomicBool,
 }
 
 impl DesktopBackendState {
     fn is_shutting_down(&self) -> bool {
-        self.shutting_down
-            .lock()
-            .map(|guard| *guard)
-            .unwrap_or(true)
+        self.shutting_down.load(AtomicOrdering::Acquire)
     }
 
     fn stop(&self) {
-        if let Ok(mut guard) = self.shutting_down.lock() {
-            *guard = true;
-        }
-
-        if let Ok(endpoint_guard) = self.ws_endpoint.lock() {
-            if let Some(endpoint) = endpoint_guard.as_ref() {
-                request_desktop_backend_shutdown(endpoint);
-            }
-        }
+        self.shutting_down.store(true, AtomicOrdering::Release);
 
         if let Ok(mut process_guard) = self.process.lock() {
             if let Some(child) = process_guard.as_mut() {
-                // The sidecar bounds its own graceful shutdown with
-                // SHUTDOWN_TIMEOUT_MS (5s in sidecar/index.ts) and then exits
-                // itself; wait past that window before escalating to kill so
-                // an active session can finish persisting.
-                for _ in 0..70 {
-                    match child.try_wait() {
-                        Ok(Some(_)) => break,
-                        Ok(None) => thread::sleep(Duration::from_millis(100)),
-                        Err(_) => break,
-                    }
-                }
-                match child.try_wait() {
-                    Ok(Some(_)) => {}
-                    Ok(None) => {
-                        let _ = child.kill();
-                        let _ = child.wait();
-                    }
-                    Err(_) => {
-                        let _ = child.kill();
-                        let _ = child.wait();
-                    }
+                // Quit runs this on the main thread (on macOS inside
+                // applicationWillTerminate:, where blocking beach-balls the
+                // app), so signal the sidecar and return without waiting.
+                // SIGTERM triggers its own bounded graceful shutdown
+                // (SHUTDOWN_TIMEOUT_MS in sidecar/index.ts), after which it
+                // exits itself, finishing session persistence as an orphan.
+                #[cfg(unix)]
+                let _ = Command::new("kill").arg(child.id().to_string()).status();
+                // Windows has no SIGTERM equivalent, so terminate outright.
+                // Reap the child too: TerminateProcess is quick, and the
+                // update-restart path needs the sidecar exe's file lock
+                // released before the NSIS installer replaces it.
+                #[cfg(not(unix))]
+                {
+                    let _ = child.kill();
+                    let _ = child.wait();
                 }
             }
             *process_guard = None;
@@ -332,13 +341,29 @@ struct DesktopBackendReadyLine {
     mode: Option<String>,
 }
 
+/// The release binary is a GUI-subsystem app (no console), so on Windows
+/// every console-subsystem child (git, cmd, the sidecar) would otherwise
+/// allocate its own visible console window. Piped stdio does not prevent
+/// that; only CREATE_NO_WINDOW does.
+#[cfg(windows)]
+fn hide_console_window(command: &mut Command) {
+    use std::os::windows::process::CommandExt;
+    const CREATE_NO_WINDOW: u32 = 0x0800_0000;
+    command.creation_flags(CREATE_NO_WINDOW);
+}
+
+#[cfg(not(windows))]
+fn hide_console_window(_command: &mut Command) {}
+
 fn resolve_workspace_root(launch_cwd: &str) -> String {
-    let output = Command::new("git")
+    let mut command = Command::new("git");
+    command
         .arg("-C")
         .arg(launch_cwd)
         .arg("rev-parse")
-        .arg("--show-toplevel")
-        .output();
+        .arg("--show-toplevel");
+    hide_console_window(&mut command);
+    let output = command.output();
 
     match output {
         Ok(result) if result.status.success() => {
@@ -353,51 +378,6 @@ fn resolve_workspace_root(launch_cwd: &str) -> String {
     }
 }
 
-fn request_desktop_backend_shutdown(endpoint: &str) {
-    let trimmed = endpoint.trim();
-    if trimmed.is_empty() {
-        return;
-    }
-    let base = trimmed.strip_suffix('/').unwrap_or(trimmed);
-    let url = format!("{base}/shutdown");
-    let timeout_seconds = "2";
-
-    #[cfg(target_os = "windows")]
-    {
-        let _ = Command::new("powershell")
-            .args([
-                "-NoProfile",
-                "-Command",
-                &format!(
-                    "try {{ Invoke-WebRequest -UseBasicParsing -Method Post -Uri '{}' -TimeoutSec {} | Out-Null }} catch {{ }}",
-                    url.replace('\'', "''"),
-                    timeout_seconds
-                ),
-            ])
-            .stdout(Stdio::null())
-            .stderr(Stdio::null())
-            .status();
-    }
-
-    #[cfg(not(target_os = "windows"))]
-    {
-        let _ = Command::new("curl")
-            .args([
-                "-fsS",
-                "--connect-timeout",
-                timeout_seconds,
-                "--max-time",
-                timeout_seconds,
-                "-X",
-                "POST",
-                &url,
-            ])
-            .stdout(Stdio::null())
-            .stderr(Stdio::null())
-            .status();
-    }
-}
-
 fn resolve_desktop_backend_script_path(context: &AppContext) -> Option<PathBuf> {
     let launch_cwd = PathBuf::from(&context.launch_cwd);
     let candidates = [
@@ -501,7 +481,9 @@ fn spawn_desktop_backend_process(context: &AppContext) -> Result<Child, String>
     command
         .stdin(Stdio::null())
         .stdout(Stdio::piped())
-        .stderr(Stdio::piped())
+        .stderr(Stdio::piped());
+    hide_console_window(&mut command);
+    command
         .spawn()
         .map_err(|e| format!("failed to start desktop backend sidecar: {e}"))
 }
@@ -525,10 +507,26 @@ fn ensure_desktop_backend_started_with(
     // callers (setup, the health-check loop, endpoint fetches from the
     // webview) serialize: the second caller blocks here, then sees the live
     // child and returns instead of spawning a duplicate.
-    let mut process_guard = state
+    let process_guard = state
         .process
         .lock()
         .map_err(|_| "failed to lock desktop backend process state")?;
+    ensure_desktop_backend_started_locked(state, process_guard, spawn_backend)
+}
+
+/// The check-and-spawn that runs under the process lock. Split from the lock
+/// acquisition so a test can establish "shutdown began after the unlocked
+/// check but before the lock was taken" deterministically.
+fn ensure_desktop_backend_started_locked(
+    state: &Arc<DesktopBackendState>,
+    mut process_guard: MutexGuard<'_, Option<Child>>,
+    spawn_backend: impl FnOnce() -> Result<Child, String>,
+) -> Result<(), String> {
+    // stop() marks shutdown before taking this same process lock. Recheck
+    // under the lock so a queued startup cannot spawn after shutdown.
+    if state.is_shutting_down() {
+        return Ok(());
+    }
     if let Some(existing) = process_guard.as_mut() {
         match existing.try_wait() {
             // A live child owns startup even while its endpoint is still
@@ -624,7 +622,11 @@ fn resolve_mcp_settings_path() -> Result<PathBuf, String> {
             return Ok(PathBuf::from(trimmed));
         }
     }
-    let home = std::env::var("HOME").map_err(|_| "HOME is not set".to_string())?;
+    // USERPROFILE is the Windows equivalent of HOME (and what the sidecar's
+    // homedir() resolves there); HOME is usually unset on Windows.
+    let home = std::env::var("HOME")
+        .or_else(|_| std::env::var("USERPROFILE"))
+        .map_err(|_| "neither HOME nor USERPROFILE is set".to_string())?;
     Ok(PathBuf::from(home)
         .join(".cline")
         .join("data")
@@ -648,8 +650,10 @@ fn open_path_with_default_app(path: &Path) -> Result<(), String> {
     #[cfg(target_os = "windows")]
     {
         let path_arg = path.to_string_lossy().to_string();
-        let status = Command::new("cmd")
-            .args(["/C", "start", "", &path_arg])
+        let mut command = Command::new("cmd");
+        command.args(["/C", "start", "", &path_arg]);
+        hide_console_window(&mut command);
+        let status = command
             .status()
             .map_err(|e| format!("failed to open path: {e}"))?;
         if status.success() {
@@ -675,17 +679,29 @@ fn open_path_with_default_app(path: &Path) -> Result<(), String> {
 }
 
 #[tauri::command]
-fn get_desktop_backend_endpoint(
+async fn get_desktop_backend_endpoint(
     backend_state: State<'_, Arc<DesktopBackendState>>,
     context: State<'_, AppContext>,
 ) -> Result<String, String> {
-    ensure_desktop_backend_started(backend_state.inner(), context.inner())?;
+    let backend_state = backend_state.inner().clone();
+    let context = context.inner().clone();
+    let state_for_start = backend_state.clone();
+    tauri::async_runtime::spawn_blocking(move || {
+        ensure_desktop_backend_started(&state_for_start, &context)
+    })
+    .await
+    .map_err(|error| format!("desktop backend startup task failed: {error}"))??;
+
     // Sidecar startup includes login-shell PATH resolution (bounded at 3s,
     // see sidecar/shell-path.ts) plus session-manager init, whose duration
     // varies by machine. Poll well past that combined worst case; the loop
     // returns as soon as the ready line arrives, so only failure waits long.
     // While pending this only waits — respawning is ensure's job, and it
     // refuses to start a second sidecar while the first one is still alive.
+    // A child that dies mid-poll makes this return an error rather than
+    // respawn: the next ensure call — the health-check loop within 5 seconds,
+    // or this command when the webview reconnects — replaces the dead child.
+    // Async sleeps keep Tauri's window event loop responsive while pending.
     for _ in 0..150 {
         if let Some(endpoint) = backend_state
             .ws_endpoint
@@ -708,7 +724,7 @@ fn get_desktop_backend_endpoint(
         if child_exited {
             return Err("desktop backend exited before publishing its endpoint".to_string());
         }
-        thread::sleep(Duration::from_millis(100));
+        tokio::time::sleep(Duration::from_millis(100)).await;
     }
     Err("desktop backend endpoint not ready".to_string())
 }
@@ -736,13 +752,52 @@ fn get_update_status(update_state: State<'_, Arc<UpdateState>>) -> UpdateStatus
 fn restart_to_apply_update(
     app: tauri::AppHandle,
     backend_state: State<'_, Arc<DesktopBackendState>>,
+    update_state: State<'_, Arc<UpdateState>>,
 ) {
-    // restart() never returns, so the run-loop Exit handler does not get a
-    // chance to stop the sidecar; shut it down explicitly first.
+    // Neither restart() nor install() returns, so the run-loop Exit handler
+    // does not get a chance to stop the sidecar; shut it down explicitly
+    // first. On Windows this also releases the sidecar exe's file lock,
+    // which the NSIS installer needs in order to replace it.
+    backend_state.stop();
+    // Windows: install the bytes staged by the background cycle. install()
+    // launches the NSIS installer (which relaunches the app when done) and
+    // exits this process, so it only returns on failure — fall through to a
+    // plain restart of the current version in that case.
+    #[cfg(windows)]
+    if let Some((update, bytes)) = update_state
+        .pending_install
+        .lock()
+        .ok()
+        .and_then(|mut pending| pending.take())
+    {
+        if let Err(error) = update.install(bytes) {
+            eprintln!("[updater] failed to launch the update installer: {error}");
+        }
+    }
+    #[cfg(not(windows))]
+    let _ = update_state;
+    app.restart();
+}
+
+/// Relaunch the current version of the app. Used after the sidecar replaces
+/// the shared Cline Hub under the running app (the "Cline Hub update
+/// required" flow): a fresh launch attaches everything to the new Hub instead
+/// of trying to migrate live connections. restart() never returns, so the
+/// run-loop Exit handler cannot stop the sidecar; do it explicitly first.
+#[tauri::command]
+fn relaunch_app(app: tauri::AppHandle, backend_state: State<'_, Arc<DesktopBackendState>>) {
     backend_state.stop();
     app.restart();
 }
 
+/// Quit the app. Used by the "Cline Hub update required" flow when the user
+/// chooses to keep the older running Hub (and its live sessions) and update
+/// later. The run-loop Exit handler stops the sidecar.
+#[tauri::command]
+fn quit_app(app: tauri::AppHandle) {
+    app.exit(0);
+}
+
 /// Run one updater check/download/stage cycle immediately instead of waiting
 /// for the next background interval, and report the resulting status. Used by
 /// flows that need an update staged right now (e.g. the "Cline Hub was
@@ -758,56 +813,82 @@ async fn check_for_update_now(
 }
 
 /// Icon ids accepted by `set_app_icon`; kept in sync with APP_ICONS in
-/// webview/lib/app-icon.ts. Every non-default id has a matching bundled
-/// resource at icons/dock/<id>.png.
-const APP_DOCK_ICONS: [&str; 4] = ["classic", "midnight", "hologram", "chip"];
+/// webview/lib/app-icon.ts. Every id has a matching bundled resource at
+/// icons/app/<id>.png.
+const APP_ICONS: [&str; 4] = ["classic", "midnight", "hologram", "chip"];
+
+#[cfg(any(target_os = "macos", target_os = "windows"))]
+fn resolve_app_icon(app: &tauri::AppHandle, icon: &str) -> Result<PathBuf, String> {
+    let icon_path = app
+        .path()
+        .resolve(
+            format!("icons/app/{icon}.png"),
+            tauri::path::BaseDirectory::Resource,
+        )
+        .map_err(|e| format!("failed resolving app icon resource: {e}"))?;
+    if !icon_path.exists() {
+        return Err(format!(
+            "app icon resource missing: {}",
+            icon_path.display()
+        ));
+    }
+    Ok(icon_path)
+}
 
 #[tauri::command]
-fn set_app_icon(app: tauri::AppHandle, icon: String) -> Result<bool, String> {
-    if !APP_DOCK_ICONS.contains(&icon.as_str()) {
+async fn set_app_icon(app: tauri::AppHandle, icon: String) -> Result<bool, String> {
+    if !APP_ICONS.contains(&icon.as_str()) {
         return Err(format!("unknown app icon: {icon}"));
     }
     #[cfg(target_os = "macos")]
     {
-        // "classic" also ships as a dock resource, so every choice loads the
-        // same way; setApplicationIconImage's binding warns that passing nil
-        // to restore the bundled icon may not be allowed.
-        let icon_path = app
-            .path()
-            .resolve(
-                format!("icons/dock/{icon}.png"),
-                tauri::path::BaseDirectory::Resource,
-            )
-            .map_err(|e| format!("failed resolving dock icon resource: {e}"))?;
-        if !icon_path.exists() {
-            return Err(format!(
-                "dock icon resource missing: {}",
-                icon_path.display()
-            ));
-        }
+        // Every choice uses a resource because AppKit does not support restoring
+        // the bundled icon by passing a nil application icon.
+        let icon_path = resolve_app_icon(&app, &icon)?;
+        let (result_tx, result_rx) = tokio::sync::oneshot::channel();
         app.run_on_main_thread(move || {
             use objc2::{AllocAnyThread, MainThreadMarker};
             use objc2_app_kit::{NSApplication, NSImage};
             use objc2_foundation::NSString;
 
-            let Some(mtm) = MainThreadMarker::new() else {
-                return;
-            };
-            let ns_app = NSApplication::sharedApplication(mtm);
-            let Some(image) = NSImage::initWithContentsOfFile(
-                NSImage::alloc(),
-                &NSString::from_str(&icon_path.to_string_lossy()),
-            ) else {
-                eprintln!("[dock-icon] failed loading image: {}", icon_path.display());
-                return;
-            };
-            // SAFETY: called on the main thread with a valid, non-nil image.
-            unsafe { ns_app.setApplicationIconImage(Some(&image)) };
+            let result = (|| {
+                let mtm = MainThreadMarker::new().ok_or_else(|| {
+                    "app icon update did not run on the main thread".to_string()
+                })?;
+                let ns_app = NSApplication::sharedApplication(mtm);
+                let image = NSImage::initWithContentsOfFile(
+                    NSImage::alloc(),
+                    &NSString::from_str(&icon_path.to_string_lossy()),
+                )
+                .ok_or_else(|| {
+                    format!("failed loading app icon image: {}", icon_path.display())
+                })?;
+                // SAFETY: called on the main thread with a valid, non-nil image.
+                unsafe { ns_app.setApplicationIconImage(Some(&image)) };
+                Ok(())
+            })();
+            let _ = result_tx.send(result);
         })
-        .map_err(|e| format!("failed switching dock icon: {e}"))?;
+        .map_err(|e| format!("failed switching app icon: {e}"))?;
+        result_rx
+            .await
+            .map_err(|_| "app icon update ended before AppKit completed".to_string())??;
         Ok(true)
     }
-    #[cfg(not(target_os = "macos"))]
+    #[cfg(target_os = "windows")]
+    {
+        let icon_path = resolve_app_icon(&app, &icon)?;
+        let image = tauri::image::Image::from_path(&icon_path)
+            .map_err(|e| format!("failed loading app icon image: {e}"))?;
+        let window = app
+            .get_webview_window(MAIN_WINDOW_LABEL)
+            .ok_or_else(|| "main window is unavailable".to_string())?;
+        window
+            .set_icon(image)
+            .map_err(|e| format!("failed switching taskbar icon: {e}"))?;
+        Ok(true)
+    }
+    #[cfg(not(any(target_os = "macos", target_os = "windows")))]
     {
         let _ = app;
         Ok(false)
@@ -1159,9 +1240,15 @@ fn main() {
             setup_tray_icon(app)?;
             let app_context = app.state::<AppContext>().inner().clone();
             let backend_state = app.state::<Arc<DesktopBackendState>>().inner().clone();
-            if let Err(error) = ensure_desktop_backend_started(&backend_state, &app_context) {
-                eprintln!("[desktop-backend] startup failed: {error}");
-            }
+            let state_for_start = backend_state.clone();
+            let context_for_start = app_context.clone();
+            tauri::async_runtime::spawn_blocking(move || {
+                if let Err(error) =
+                    ensure_desktop_backend_started(&state_for_start, &context_for_start)
+                {
+                    eprintln!("[desktop-backend] startup failed: {error}");
+                }
+            });
             // Dev builds are not installed app bundles, so there is nothing the
             // updater could meaningfully check or replace.
             if !cfg!(debug_assertions) {
@@ -1200,7 +1287,9 @@ fn main() {
             set_app_icon,
             show_session_notification,
             drain_desktop_actions,
-            set_tray_status
+            set_tray_status,
+            relaunch_app,
+            quit_app
         ])
         .build(tauri::generate_context!())
         .expect("error while building tauri app")
@@ -1225,6 +1314,16 @@ mod tests {
     use super::*;
     use std::sync::atomic::{AtomicUsize, Ordering};
 
+    #[test]
+    fn macos_bundle_declares_voice_input_permissions() {
+        let info_plist = include_str!("../Info.plist");
+        assert!(info_plist.contains("<key>NSMicrophoneUsageDescription</key>"));
+        assert!(info_plist.contains("<key>NSSpeechRecognitionUsageDescription</key>"));
+
+        let entitlements = include_str!("../entitlements.plist");
+        assert!(entitlements.contains("<key>com.apple.security.device.audio-input</key>"));
+    }
+
     #[test]
     fn desktop_actions_are_buffered_in_order_until_drained() {
         let state = DesktopActionState::default();
@@ -1400,6 +1499,28 @@ mod tests {
         state.stop();
     }
 
+    /// The interleaving where only the recheck under the lock stands between
+    /// shutdown and a fresh spawn: startup has passed its unlocked shutdown
+    /// check, stop() marks shutdown while startup is still waiting for the
+    /// process lock, and then startup acquires the lock. Played out directly
+    /// on one thread so the ordering is exact rather than scheduled.
+    #[test]
+    fn startup_queued_on_process_lock_does_not_spawn_after_shutdown() {
+        let state = Arc::new(DesktopBackendState::default());
+        let spawn_count = AtomicUsize::new(0);
+
+        assert!(!state.is_shutting_down(), "the unlocked check passes");
+        state.shutting_down.store(true, AtomicOrdering::Release);
+        let process_guard = state.process.lock().expect("process lock should succeed");
+        ensure_desktop_backend_started_locked(&state, process_guard, || {
+            spawn_count.fetch_add(1, Ordering::SeqCst);
+            spawn_pending_sidecar()
+        })
+        .expect("shutdown should make startup a no-op");
+
+        assert_eq!(spawn_count.load(Ordering::SeqCst), 0);
+    }
+
     #[test]
     fn exited_child_is_replaced_on_next_startup_check() {
         let state = Arc::new(DesktopBackendState::default());

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

@@ -1,12 +1,12 @@
 {
 	"$schema": "https://schema.tauri.app/config/2",
 	"productName": "Cline",
-	"version": "0.0.14",
+	"version": "0.0.24",
 	"identifier": "bot.cline.app",
 	"build": {
 		"beforeDevCommand": "bun run build:sidecar:bin && bun run dev:web",
 		"devUrl": "http://localhost:3125",
-		"beforeBuildCommand": "bun run build",
+		"beforeBuildCommand": "bun run dmg:background && bun run build",
 		"frontendDist": "../webview/out"
 	},
 	"plugins": {
@@ -38,7 +38,7 @@
 		"active": true,
 		"targets": "all",
 		"externalBin": ["bin/code-sidecar"],
-		"resources": ["icons/dock/*.png"],
+		"resources": ["icons/app/*.png"],
 		"icon": [
 			"icons/32x32.png",
 			"icons/128x128.png",
@@ -48,7 +48,22 @@
 		],
 		"macOS": {
 			"entitlements": "entitlements.plist",
-			"hardenedRuntime": true
+			"hardenedRuntime": true,
+			"dmg": {
+				"background": "dmg/background.gen.tiff",
+				"windowSize": {
+					"width": 640,
+					"height": 432
+				},
+				"appPosition": {
+					"x": 140,
+					"y": 200
+				},
+				"applicationFolderPosition": {
+					"x": 500,
+					"y": 200
+				}
+			}
 		}
 	}
 }