Merge pull request #52090 from NousResearch/salvage/35994-reset-deadlock

fix(gateway): offload agent cleanup off the event loop in /new reset (#35994)

.github/actions/detect-changes/action.yml

@@ -0,0 +1,62 @@
+name: Detect affected areas
+description: >-
+  Classify a PR's changed files into CI work lanes (python, frontend, site,
+  scan, deps, mcp_catalog) so the orchestrator can conditionally call only
+  the sub-workflows a PR can affect. Outputs are always "true" on push/dispatch
+  events and fail open (everything "true") when the diff cannot be computed.
+
+outputs:
+  python:
+    description: Run Python tests / ruff / ty / windows-footguns.
+    value: ${{ steps.classify.outputs.python }}
+  frontend:
+    description: Run the TypeScript typecheck matrix + desktop build.
+    value: ${{ steps.classify.outputs.frontend }}
+  docker_meta:
+    description: Docker setup and meta files have changed.
+    value: ${{ steps.classify.outputs.docker_meta }}
+  site:
+    description: Build the Docusaurus docs site.
+    value: ${{ steps.classify.outputs.site }}
+  scan:
+    description: Run the supply-chain critical-pattern scanner.
+    value: ${{ steps.classify.outputs.scan }}
+  deps:
+    description: Check pyproject.toml dependency upper bounds.
+    value: ${{ steps.classify.outputs.deps }}
+  mcp_catalog:
+    description: Require MCP catalog security review label.
+    value: ${{ steps.classify.outputs.mcp_catalog }}
+
+runs:
+  using: composite
+  steps:
+    - name: Classify changed files
+      id: classify
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+        REPO: ${{ github.repository }}
+        EVENT_NAME: ${{ github.event_name }}
+        BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      run: |
+        set -euo pipefail
+
+        # Only pull_request events are gated. Other events (push, release,
+        # dispatch) leave CHANGED empty, so the classifier fails open and every
+        # lane runs. Post-merge / on-demand validation is never weakened.
+        if [ "$EVENT_NAME" = "pull_request" ]; then
+          # Use the compare endpoint with the pinned base/head SHAs from the
+          # event payload instead of the "current PR files" endpoint. The SHAs
+          # are frozen at trigger time, so the file list is deterministic even
+          # if the PR receives a new push between trigger and detect.
+          CHANGED="$(gh api \
+            --paginate \
+            "repos/${REPO}/compare/${BASE_SHA}...${HEAD_SHA}" \
+            --jq '.files[].filename' || true)"
+        fi
+
+        echo "Changed files:"
+        printf '%s\n' "${CHANGED:-(none)}"
+        printf '%s\n' "${CHANGED:-}" | python3 scripts/ci/classify_changes.py

.github/actions/retry/action.yml

@@ -0,0 +1,50 @@
+name: Retry a flaky command
+description: >-
+  Run a shell command, retrying on non-zero exit. For dependency installs
+  (npm ci, uv sync) whose only failures are transient network/toolchain
+  flakes — a node-gyp header fetch, a registry blip — so CI self-heals
+  instead of needing a manual re-run.
+
+inputs:
+  command:
+    description: Shell command to run (and retry).
+    required: true
+  attempts:
+    description: Max attempts before giving up.
+    default: "3"
+  delay:
+    description: Seconds to wait between attempts.
+    default: "10"
+  working-directory:
+    description: Directory to run in.
+    default: "."
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      # command goes through env, never interpolated into the script body, so
+      # a command with quotes/specials can't break or inject into the runner.
+      env:
+        _CMD: ${{ inputs.command }}
+        _ATTEMPTS: ${{ inputs.attempts }}
+        _DELAY: ${{ inputs.delay }}
+      run: |
+        set -uo pipefail
+        n=0
+        while :; do
+          n=$((n + 1))
+          echo "::group::attempt $n/$_ATTEMPTS: $_CMD"
+          if bash -c "$_CMD"; then
+            echo "::endgroup::"
+            exit 0
+          fi
+          echo "::endgroup::"
+          if [ "$n" -ge "$_ATTEMPTS" ]; then
+            echo "::error::failed after $n attempts: $_CMD"
+            exit 1
+          fi
+          echo "::warning::attempt $n failed; retrying in ${_DELAY}s: $_CMD"
+          sleep "$_DELAY"
+        done

.github/workflows/build-windows-installer.yml

@@ -1,100 +0,0 @@
-name: Build Windows Installer
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  # Gate: workflow_dispatch is already restricted to users with write access,
-  # but we want ADMIN-only. Explicitly check the triggering actor's repo
-  # permission via the API and fail fast for anyone below admin.
-  authorize:
-    name: Authorize (admins only)
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Check actor is a repo admin
-        env:
-          GH_TOKEN: ${{ github.token }}
-          ACTOR: ${{ github.actor }}
-        run: |
-          set -euo pipefail
-          perm=$(gh api \
-            "repos/${{ github.repository }}/collaborators/${ACTOR}/permission" \
-            --jq '.permission')
-          echo "Actor '${ACTOR}' has permission: ${perm}"
-          if [ "${perm}" != "admin" ]; then
-            echo "::error::'${ACTOR}' is not a repo admin (permission=${perm}). Refusing to build/sign."
-            exit 1
-          fi
-          echo "Authorized: '${ACTOR}' is an admin."
-
-  build:
-    name: Hermes-Setup.exe
-    needs: authorize
-    runs-on: windows-latest
-    timeout-minutes: 30
-    permissions:
-      contents: read
-      # Required for OIDC auth to Azure (azure/login federated credentials).
-      id-token: write
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
-        with:
-          node-version: 22
-          cache: npm
-
-      - name: Install npm dependencies
-        run: npm ci
-
-      - name: Setup Rust
-        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8  # stable
-
-      - name: Cache Rust targets
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32  # v2
-        with:
-          workspaces: apps/bootstrap-installer/src-tauri
-
-      - name: Build installer
-        run: npm run tauri:build
-        working-directory: apps/bootstrap-installer
-
-      - name: Azure login (OIDC)
-        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5  # v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-
-      - name: Sign Hermes-Setup.exe with Azure Artifact Signing
-        uses: azure/artifact-signing-action@c7ab2a863ab5f9a846ddb8265964877ef296ee82  # v2
-        with:
-          endpoint: ${{ vars.AZURE_SIGNING_ENDPOINT }}
-          signing-account-name: ${{ vars.AZURE_SIGNING_ACCOUNT_NAME }}
-          certificate-profile-name: ${{ vars.AZURE_SIGNING_CERTIFICATE_PROFILE }}
-          # Sign both the raw exe and the bundled NSIS installer.
-          files-folder: ${{ github.workspace }}\apps\bootstrap-installer\src-tauri\target\release
-          files-folder-filter: exe
-          files-folder-recurse: true
-          file-digest: SHA256
-          timestamp-rfc3161: http://timestamp.acs.microsoft.com
-          timestamp-digest: SHA256
-
-      - name: Upload NSIS installer
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: Hermes-Setup-installer
-          path: apps/bootstrap-installer/src-tauri/target/release/bundle/nsis/*.exe
-
-      - name: Upload raw exe
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: Hermes-Setup-exe
-          path: apps/bootstrap-installer/src-tauri/target/release/Hermes-Setup.exe

.github/workflows/ci.yml

@@ -0,0 +1,146 @@
+name: CI
+
+# Orchestrator workflow. Runs ``detect-changes`` once, then conditionally
+# calls the sub-workflows that a PR can actually affect. A final
+# ``all-checks-pass`` gate job aggregates results so branch protection only
+# needs to require a single check.
+#
+# Sub-workflows are triggered via ``workflow_call`` and keep their own job
+# definitions, matrices, and concurrency settings. They no longer have
+# ``push:`` / ``pull_request:`` triggers of their own — everything flows
+# through this file.
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write # needed by lint (PR comment) + supply-chain (PR comment)
+  actions: read # needed by osv-scanner (SARIF upload)
+  security-events: write # needed by osv-scanner (SARIF upload)
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # ─────────────────────────────────────────────────────────────────────
+  # detect: run the classifier once. Every downstream job reads its outputs
+  # to decide whether to run. On push/dispatch the classifier fails open
+  # (all lanes true) so post-merge validation is never weakened.
+  # ─────────────────────────────────────────────────────────────────────
+  detect:
+    runs-on: ubuntu-latest
+    outputs:
+      python: ${{ steps.classify.outputs.python }}
+      frontend: ${{ steps.classify.outputs.frontend }}
+      site: ${{ steps.classify.outputs.site }}
+      scan: ${{ steps.classify.outputs.scan }}
+      deps: ${{ steps.classify.outputs.deps }}
+      docker_meta: ${{ steps.classify.outputs.docker_meta }}
+      mcp_catalog: ${{ steps.classify.outputs.mcp_catalog }}
+      event_name: ${{ github.event_name }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Detect affected areas
+        id: classify
+        uses: ./.github/actions/detect-changes
+
+  # ─────────────────────────────────────────────────────────────────────
+  # Lane-gated sub-workflows. Each runs in parallel after detect finishes.
+  # Skipped workflows (if condition is false) don't spin up runners.
+  # ─────────────────────────────────────────────────────────────────────
+  tests:
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/tests.yml
+
+  lint:
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/lint.yml
+    with:
+      event_name: ${{ needs.detect.outputs.event_name }}
+
+  typecheck:
+    needs: detect
+    if: needs.detect.outputs.frontend == 'true'
+    uses: ./.github/workflows/typecheck.yml
+
+  docs-site:
+    needs: detect
+    if: needs.detect.outputs.site == 'true'
+    uses: ./.github/workflows/docs-site-checks.yml
+
+  history-check:
+    needs: detect
+    if: needs.detect.outputs.event_name == 'pull_request'
+    uses: ./.github/workflows/history-check.yml
+
+  contributor-check:
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/contributor-check.yml
+
+  uv-lockfile:
+    needs: detect
+    uses: ./.github/workflows/uv-lockfile-check.yml
+
+  docker-lint:
+    needs: detect
+    if: needs.detect.outputs.docker_meta == 'true'
+    uses: ./.github/workflows/docker-lint.yml
+
+  supply-chain:
+    needs: detect
+    if: needs.detect.outputs.event_name == 'pull_request' && (needs.detect.outputs.scan == 'true' || needs.detect.outputs.deps == 'true' || needs.detect.outputs.mcp_catalog == 'true')
+    uses: ./.github/workflows/supply-chain-audit.yml
+    with:
+      event_name: ${{ needs.detect.outputs.event_name }}
+      scan: ${{ needs.detect.outputs.scan == 'true' }}
+      deps: ${{ needs.detect.outputs.deps == 'true' }}
+      mcp_catalog: ${{ needs.detect.outputs.mcp_catalog == 'true' }}
+
+  osv-scanner:
+    needs: detect
+    uses: ./.github/workflows/osv-scanner.yml
+
+  # ─────────────────────────────────────────────────────────────────────
+  # Gate: runs after everything. ``if: always()`` ensures it reports a
+  # status even when some deps were skipped. Only actual ``failure``
+  # results cause it to fail; ``skipped`` is treated as success.
+  #
+  # Branch protection should require ONLY this check.
+  # ─────────────────────────────────────────────────────────────────────
+  all-checks-pass:
+    name: All required checks pass
+    needs:
+      - tests
+      - lint
+      - typecheck
+      - docs-site
+      - history-check
+      - contributor-check
+      - uv-lockfile
+      - docker-lint
+      - supply-chain
+      - osv-scanner
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate job results
+        env:
+          RESULTS: ${{ toJSON(needs.*.result) }}
+        run: |
+          echo "$RESULTS" | python3 -c "
+          import json, sys
+          results = json.load(sys.stdin)
+          failed = [r for r in results if r == 'failure']
+          if failed:
+              print(f'::error::{len(failed)} job(s) failed')
+              sys.exit(1)
+          print('All checks passed (or were skipped)')
+          "

.github/workflows/contributor-check.yml

@@ -1,11 +1,8 @@
 name: Contributor Attribution Check
 
 on:
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
+
 permissions:
   contents: read
 
@@ -17,21 +14,7 @@ jobs:
         with:
           fetch-depth: 0  # Full history needed for git log
 
-      - name: Check if relevant files changed
-        id: filter
-        run: |
-          BASE="${{ github.event.pull_request.base.sha }}"
-          HEAD="${{ github.event.pull_request.head.sha }}"
-          CHANGED=$(git diff --name-only "$BASE"..."$HEAD" -- '*.py' '**/*.py' '.github/workflows/contributor-check.yml' || true)
-          if [ -n "$CHANGED" ]; then
-            echo "run=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "run=false" >> "$GITHUB_OUTPUT"
-            echo "No Python files changed, skipping attribution check."
-          fi
-
       - name: Check for unmapped contributor emails
-        if: steps.filter.outputs.run == 'true'
         run: |
           # Get the merge base between this PR and main
           MERGE_BASE=$(git merge-base origin/main HEAD)

.github/workflows/docker-lint.yml

@@ -11,19 +11,7 @@ name: Docker / shell lint
 # activate script doesn't exist at lint time.
 
 on:
-  push:
-    branches: [main]
-    paths:
-      - Dockerfile
-      - docker/**
-      - .hadolint.yaml
-      - .github/workflows/docker-lint.yml
-
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 permissions:
   contents: read

.github/workflows/docker-publish.yml

@@ -56,13 +56,21 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
+      # The image build + smoke test + integration tests run ONLY on
+      # push-to-main and release — never on PRs. They are the heaviest jobs
+      # in CI (~15-45 min) and a broken build surfaces on the main push (and
+      # is gated pre-merge by docker-lint + uv-lockfile-check). Every step
+      # below is skipped on PRs, so the job still reports green and the
+      # required check never hangs.
       - name: Set up Docker Buildx
+        if: github.event_name != 'pull_request'
         uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
 
       # Build once, load into the local daemon for smoke testing.  Cached
       # to gha with a per-arch scope; the push step below reuses every
       # layer from this build.
       - name: Build image (amd64, smoke test)
+        if: github.event_name != 'pull_request'
         uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7.1.0
         with:
           context: .
@@ -76,6 +84,7 @@ jobs:
           cache-to: type=gha,mode=max,scope=docker-amd64
 
       - name: Smoke test image
+        if: github.event_name != 'pull_request'
         uses: ./.github/actions/hermes-smoke-test
         with:
           image: ${{ env.IMAGE_NAME }}:test
@@ -102,12 +111,15 @@ jobs:
       # cheapest path to coverage on every PR that touches docker code.
       # ---------------------------------------------------------------------
       - name: Install uv (for docker tests)
+        if: github.event_name != 'pull_request'
         uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
 
       - name: Set up Python 3.11 (for docker tests)
+        if: github.event_name != 'pull_request'
         run: uv python install 3.11
 
       - name: Install Python dependencies (for docker tests)
+        if: github.event_name != 'pull_request'
         run: |
           uv venv .venv --python 3.11
           source .venv/bin/activate
@@ -118,6 +130,7 @@ jobs:
           uv pip install -e ".[dev]"
 
       - name: Run docker integration tests
+        if: github.event_name != 'pull_request'
         env:
           # Skip rebuild; use the image already loaded by the build step.
           HERMES_TEST_IMAGE: ${{ env.IMAGE_NAME }}:test
@@ -190,7 +203,9 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
+      # arm64 build runs only on push-to-main and release (see build-amd64).
       - name: Set up Docker Buildx
+        if: github.event_name != 'pull_request'
         uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
 
       # Log in to ghcr.io so the registry-backed build cache below can be
@@ -201,41 +216,21 @@ jobs:
       # crashed the build before the smoke test (the reason the gha cache
       # was removed from arm64 PRs in the first place).
       - name: Log in to ghcr.io (build cache)
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121  # v4.1.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      # Build once, load into the local daemon for smoke testing.
-      #
-      # PR builds use the registry-backed cache READ-ONLY (cache-from only):
-      # they pull warm layers pushed by the most recent main build but never
-      # write, so rapid PR pushes don't race on cache writes or pollute the
-      # cache ref.  This restores warm-cache speed to arm64 PR builds (which
-      # were running fully uncached and were ~45% slower than amd64, making
-      # them the job most often cancelled on supersede).
+      # Build once, load into the local daemon for smoke testing, then push
+      # by digest below. Reads AND writes the registry-backed cache so the
+      # push reuses layers from this build and the next build starts warm.
       #
       # Registry cache (type=registry on ghcr.io) is used instead of the gha
       # cache that previously broke here: its credential is the job-lifetime
       # GITHUB_TOKEN, not a short-lived SAS token, so the cold-build-outlives-
       # token failure mode cannot recur.
-      - name: Build image (arm64, smoke test, cache read-only PR)
-        if: github.event_name == 'pull_request'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7.1.0
-        with:
-          context: .
-          file: Dockerfile
-          load: true
-          platforms: linux/arm64
-          tags: ${{ env.IMAGE_NAME }}:test
-          build-args: |
-            HERMES_GIT_SHA=${{ github.sha }}
-          cache-from: type=registry,ref=ghcr.io/nousresearch/hermes-agent:buildcache-arm64
-
-      # Main/release builds read AND write the registry cache so the digest
-      # push below reuses layers from this smoke-test build, and so the next
-      # PR/main build starts warm.
       - name: Build image (arm64, smoke test, cached publish)
         if: github.event_name != 'pull_request'
         uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7.1.0
@@ -251,6 +246,7 @@ jobs:
           cache-to: type=registry,ref=ghcr.io/nousresearch/hermes-agent:buildcache-arm64,mode=max
 
       - name: Smoke test image
+        if: github.event_name != 'pull_request'
         uses: ./.github/actions/hermes-smoke-test
         with:
           image: ${{ env.IMAGE_NAME }}:test

.github/workflows/docs-site-checks.yml

@@ -1,13 +1,7 @@
 name: Docs Site Checks
 
 on:
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
-
-  workflow_dispatch:
+  workflow_call:
 
 permissions:
   contents: read
@@ -25,15 +19,19 @@ jobs:
           cache-dependency-path: website/package-lock.json
 
       - name: Install website dependencies
-        run: npm ci
-        working-directory: website
+        uses: ./.github/actions/retry
+        with:
+          command: npm ci
+          working-directory: website
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.11"
 
       - name: Install ascii-guard
-        run: python -m pip install ascii-guard==2.3.0 pyyaml==6.0.3
+        uses: ./.github/actions/retry
+        with:
+          command: python -m pip install ascii-guard==2.3.0 pyyaml==6.0.3
 
       - name: Extract skill metadata for dashboard
         run: python3 website/scripts/extract-skills.py

.github/workflows/history-check.yml

@@ -14,11 +14,7 @@ name: History Check
 # the PR head and main to be non-empty.
 
 on:
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 permissions:
   contents: read

.github/workflows/lint.yml

@@ -9,18 +9,12 @@ name: Lint (ruff + ty)
 #      enforcement fails.
 
 on:
-  push:
-    branches: [main]
-    paths-ignore:
-      - "**/*.md"
-      - "docs/**"
-      - "website/**"
-
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
+    inputs:
+      event_name:
+        description: The event name from the calling orchestrator (pull_request or push).
+        type: string
+        required: true
 
 permissions:
   contents: read
@@ -33,6 +27,7 @@ concurrency:
 jobs:
   lint-diff:
     name: ruff + ty diff
+    if: inputs.event_name == 'pull_request'
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -45,16 +40,16 @@ jobs:
         uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
 
       - name: Install ruff + ty
-        run: |
-          uv tool install ruff
-          uv tool install ty
+        uses: ./.github/actions/retry
+        with:
+          command: uv tool install ruff && uv tool install ty
 
       - name: Determine base ref
         id: base
         run: |
           # For PRs, diff against the merge base with the target branch.
           # For pushes to main, diff against the previous commit on main.
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
+          if [ "${{ inputs.event_name }}" = "pull_request" ]; then
             BASE_SHA=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
             BASE_REF="origin/${{ github.base_ref }}"
           else
@@ -110,7 +105,7 @@ jobs:
             --base-ty   .lint-reports/base/ty.json \
             --head-ty   .lint-reports/head/ty.json \
             --base-ref  "${{ steps.base.outputs.ref }}" \
-            --head-ref  "${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}" \
+            --head-ref  "${{ inputs.event_name == 'pull_request' && github.head_ref || github.ref_name }}" \
             --output    .lint-reports/summary.md
           cat .lint-reports/summary.md >> "$GITHUB_STEP_SUMMARY"
 
@@ -122,7 +117,7 @@ jobs:
           retention-days: 14
 
       - name: Post / update PR comment
-        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        if: inputs.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
         continue-on-error: true
         uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
         with:
@@ -172,7 +167,9 @@ jobs:
         uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
 
       - name: Install ruff
-        run: uv tool install ruff
+        uses: ./.github/actions/retry
+        with:
+          command: uv tool install ruff
 
       - name: ruff check .
         # No --exit-zero, no || true. Exit code propagates to the job,

.github/workflows/osv-scanner.yml

@@ -1,8 +1,8 @@
 name: OSV-Scanner
 
 # Scans lockfiles (uv.lock, package-lock.json) against the OSV vulnerability
-# database. Runs on every PR that touches a lockfile and on a weekly schedule
-# against main.
+# database. Runs on every PR/push (via the ci.yml orchestrator's workflow_call)
+# and on a weekly schedule against main.
 #
 # This is detection-only — OSV-Scanner does NOT open PRs or modify pins.
 # It reports known CVEs in currently-pinned dependency versions so we can
@@ -10,9 +10,9 @@ name: OSV-Scanner
 # (full SHA / exact version) is preserved; only the notification signal
 # is added.
 #
-# Complements the existing supply-chain-audit.yml workflow (which scans
-# for malicious code patterns in PR diffs) by covering the orthogonal
-# "currently-pinned dep became known-vulnerable" case.
+# Complements the supply-chain-audit.yml workflow (which scans for malicious
+# code patterns in PR diffs) by covering the orthogonal "currently-pinned
+# dep became known-vulnerable" case.
 #
 # Uses Google's officially-recommended reusable workflow, pinned by SHA.
 # Findings land in the repo's Security tab (Code Scanning > OSV-Scanner).
@@ -20,19 +20,7 @@ name: OSV-Scanner
 # vulnerabilities in pinned deps that we may need to patch deliberately.
 
 on:
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
-  push:
-    branches: [main]
-    paths:
-      - "uv.lock"
-      - "pyproject.toml"
-      - "package.json"
-      - "package-lock.json"
-      - "website/package-lock.json"
+  workflow_call:
   schedule:
     # Weekly scan against main — catches CVEs published after merge for
     # deps that haven't changed since.

.github/workflows/supply-chain-audit.yml

@@ -1,16 +1,5 @@
 name: Supply Chain Audit
 
-on:
-  # No paths filter — the jobs must always run so required checks
-  # report a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  pull-requests: write
-  contents: read
-
 # Narrow, high-signal scanner. Only fires on critical indicators of supply
 # chain attacks (e.g. the litellm-style payloads). Low-signal heuristics
 # (plain base64, plain exec/eval, dependency/Dockerfile/workflow edits,
@@ -19,56 +8,40 @@ permissions:
 # the scanner. Keep this file's checks ruthlessly narrow: if you find
 # yourself adding WARNING-tier patterns here again, make a separate
 # advisory-only workflow instead.
+#
+# Path-gating is handled centrally by the ``ci.yml`` orchestrator's
+# ``detect`` job. The orchestrator passes ``scan`` / ``deps`` /
+# ``mcp_catalog`` booleans as inputs; this workflow's jobs gate on those
+# inputs instead of re-computing the diff.
+
+on:
+  workflow_call:
+    inputs:
+      event_name:
+        description: The event name from the calling orchestrator.
+        type: string
+        required: true
+      scan:
+        description: Whether supply-chain-relevant files changed.
+        type: boolean
+        required: true
+      deps:
+        description: Whether pyproject.toml changed.
+        type: boolean
+        required: true
+      mcp_catalog:
+        description: Whether the MCP catalog / installer changed.
+        type: boolean
+        required: true
+
+permissions:
+  pull-requests: write
+  contents: read
 
 jobs:
-  # ── Path filter (shared by both scan and dep-bounds) ───────────────
-  changes:
-    runs-on: ubuntu-latest
-    outputs:
-      # True when any file the scanner cares about changed in this PR
-      scan: ${{ steps.filter.outputs.scan }}
-      # True when pyproject.toml changed in this PR
-      deps: ${{ steps.filter.outputs.deps }}
-      # True when the curated MCP catalog / bundled MCP manifests changed.
-      mcp_catalog: ${{ steps.filter.outputs.mcp_catalog }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-      - name: Check for relevant file changes
-        id: filter
-        run: |
-          BASE="${{ github.event.pull_request.base.sha }}"
-          HEAD="${{ github.event.pull_request.head.sha }}"
-          SCAN_FILES=$(git diff --name-only "$BASE"..."$HEAD" -- \
-            '*.py' '**/*.py' '*.pth' '**/*.pth' \
-            'setup.py' 'setup.cfg' \
-            'sitecustomize.py' 'usercustomize.py' '__init__.pth' \
-            'pyproject.toml' || true)
-          if [ -n "$SCAN_FILES" ]; then
-            echo "scan=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "scan=false" >> "$GITHUB_OUTPUT"
-          fi
-          DEPS_FILES=$(git diff --name-only "$BASE"..."$HEAD" -- 'pyproject.toml' || true)
-          if [ -n "$DEPS_FILES" ]; then
-            echo "deps=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "deps=false" >> "$GITHUB_OUTPUT"
-          fi
-          MCP_CATALOG_FILES=$(git diff --name-only "$BASE"..."$HEAD" -- \
-            'optional-mcps/**' \
-            'hermes_cli/mcp_catalog.py' || true)
-          if [ -n "$MCP_CATALOG_FILES" ]; then
-            echo "mcp_catalog=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "mcp_catalog=false" >> "$GITHUB_OUTPUT"
-          fi
-
   scan:
     name: Scan PR for critical supply chain risks
-    needs: changes
-    if: needs.changes.outputs.scan == 'true'
+    if: inputs.scan
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -111,7 +84,7 @@ jobs:
           fi
 
           # --- base64 decode + exec/eval on the same line (the litellm attack pattern) ---
-          B64_EXEC_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -iE 'base64\.(b64decode|decodebytes|urlsafe_b64decode)' | grep -iE 'exec\(|eval\(' | head -10 || true)
+          B64_EXEC_HITS=$(echo "$DIFF" | grep -n '^+' | grep -iE 'base64\.(b64decode|decodebytes|urlsafe_b64decode)' | grep -iE 'exec\(|eval\(' | head -10 || true)
           if [ -n "$B64_EXEC_HITS" ]; then
             FINDINGS="${FINDINGS}
           ### 🚨 CRITICAL: base64 decode + exec/eval combo
@@ -125,7 +98,7 @@ jobs:
           fi
 
           # --- subprocess with encoded/obfuscated command argument ---
-          PROC_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -E 'subprocess\.(Popen|call|run)\s*\(' | grep -iE 'base64|\\x[0-9a-f]{2}|chr\(' | head -10 || true)
+          PROC_HITS=$(echo "$DIFF" | grep -n '^+' | grep -E 'subprocess\.(Popen|call|run)\s*\(' | grep -iE 'base64|\\x[0-9a-f]{2}|chr\(' | head -10 || true)
           if [ -n "$PROC_HITS" ]; then
             FINDINGS="${FINDINGS}
           ### 🚨 CRITICAL: subprocess with encoded/obfuscated command
@@ -187,23 +160,9 @@ jobs:
           echo "::error::CRITICAL supply chain risk patterns detected in this PR. See the PR comment for details."
           exit 1
 
-  # Gate: reports success when scan was skipped (no relevant files changed).
-  # This ensures the required check always gets a status.
-  scan-gate:
-    name: Scan PR for critical supply chain risks
-    needs: changes
-    # always() so the gate still reports SUCCESS even if `changes` fails/is
-    # skipped — without it, a failed dependency would leave the required
-    # check unreported (i.e. "pending"), the exact failure mode this fixes.
-    if: always() && needs.changes.outputs.scan != 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo "No supply-chain-relevant files changed, skipping scan."
-
   dep-bounds:
     name: Check PyPI dependency upper bounds
-    needs: changes
-    if: needs.changes.outputs.deps == 'true'
+    if: inputs.deps
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -253,7 +212,7 @@ jobs:
           $(cat /tmp/unbounded.txt)
           \`\`\`
 
-          **Fix:** Add an upper bound, e.g. \`\"package>=1.2.0,<2\"\`
+          **Fix:** Add an upper bound, e.g. \`"package>=1.2.0,<2"\`
 
           ---
           *See PR #2810 and CONTRIBUTING.md for the full policy rationale.*"
@@ -266,23 +225,9 @@ jobs:
           echo "::error::PyPI dependencies without upper bounds detected. Add <next_major ceiling per CONTRIBUTING.md policy."
           exit 1
 
-  # Gate: reports success when dep-bounds was skipped (no pyproject.toml changed).
-  # This ensures the required check always gets a status.
-  dep-bounds-gate:
-    name: Check PyPI dependency upper bounds
-    needs: changes
-    # always() so the gate still reports SUCCESS even if `changes` fails/is
-    # skipped — without it, a failed dependency would leave the required
-    # check unreported (i.e. "pending"), the exact failure mode this fixes.
-    if: always() && needs.changes.outputs.deps != 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo "No pyproject.toml changes, skipping dependency bounds check."
-
   mcp-catalog-review:
     name: MCP catalog security review
-    needs: changes
-    if: needs.changes.outputs.mcp_catalog == 'true'
+    if: inputs.mcp_catalog
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -317,11 +262,3 @@ jobs:
           gh pr comment "$PR" --body "$BODY" || echo "::warning::Could not post PR comment (expected for fork PRs)"
           echo "::error::MCP catalog changes require the mcp-catalog-reviewed label."
           exit 1
-
-  mcp-catalog-review-gate:
-    name: MCP catalog security review
-    needs: changes
-    if: always() && needs.changes.outputs.mcp_catalog != 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo "No MCP catalog changes, skipping MCP catalog security review."

.github/workflows/tests.yml

@@ -1,21 +1,12 @@
 name: Tests
 
 on:
-  push:
-    branches: [main]
-    paths-ignore:
-      - "**/*.md"
-      - "docs/**"
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 permissions:
   contents: read
 
-# Cancel in-progress runs for the same PR/branch
+# Cancel in-progress runs for the same ref
 concurrency:
   group: tests-${{ github.ref }}
   cancel-in-progress: true
@@ -49,7 +40,7 @@ jobs:
           RG_VERSION=15.1.0
           RG_SHA256=1c9297be4a084eea7ecaedf93eb03d058d6faae29bbc57ecdaf5063921491599
           RG_TARBALL=ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz
-          curl -sSfL -o "$RG_TARBALL" \
+          curl -sSfL --retry 3 --retry-delay 5 -o "$RG_TARBALL" \
             "https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${RG_TARBALL}"
           echo "${RG_SHA256}  ${RG_TARBALL}" | sha256sum -c -
           tar -xzf "$RG_TARBALL"
@@ -78,7 +69,9 @@ jobs:
         # fails if the lock is out of sync with pyproject.toml), giving a
         # reproducible env. It also creates .venv itself, so no separate
         # `uv venv` step is needed.
-        run: uv sync --locked --python 3.11 --extra all --extra dev
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra all --extra dev
 
       - name: Minimize uv cache
         # Optimized for CI: prunes pre-built wheels that are cheap to
@@ -171,7 +164,7 @@ jobs:
           RG_VERSION=15.1.0
           RG_SHA256=1c9297be4a084eea7ecaedf93eb03d058d6faae29bbc57ecdaf5063921491599
           RG_TARBALL=ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz
-          curl -sSfL -o "$RG_TARBALL" \
+          curl -sSfL --retry 3 --retry-delay 5 -o "$RG_TARBALL" \
             "https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${RG_TARBALL}"
           echo "${RG_SHA256}  ${RG_TARBALL}" | sha256sum -c -
           tar -xzf "$RG_TARBALL"
@@ -200,7 +193,9 @@ jobs:
         # fails if the lock is out of sync with pyproject.toml), giving a
         # reproducible env. It also creates .venv itself, so no separate
         # `uv venv` step is needed.
-        run: uv sync --locked --python 3.11 --extra all --extra dev
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra all --extra dev
 
       - name: Minimize uv cache
         # Optimized for CI: prunes pre-built wheels that are cheap to

.github/workflows/typecheck.yml

@@ -2,13 +2,7 @@
 name: Typecheck
 
 on:
-  push:
-    branches: [main]
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 jobs:
   typecheck:
@@ -24,7 +18,14 @@ jobs:
         with:
           node-version: 22
           cache: npm
-      - run: npm ci
+      # --ignore-scripts: typecheck only needs the TS sources + type defs, not
+      # native builds. Skipping install scripts drops node-pty's node-gyp
+      # header fetch — the transient flake that killed this job pre-`tsc` — and
+      # is faster. retry covers the remaining registry blips.
+      - 
+        uses: ./.github/actions/retry
+        with:
+          command: npm ci --ignore-scripts
       - run: npm run --prefix ${{ matrix.package }} typecheck
 
   # Production build of the desktop renderer. `typecheck` runs `tsc` only,
@@ -41,5 +42,10 @@ jobs:
         with:
           node-version: 22
           cache: npm
-      - run: npm ci
+      # Keep install scripts here: the production build may need node-pty's
+      # native binary. retry handles the transient install-time fetch flakes.
+      - 
+        uses: ./.github/actions/retry
+        with:
+          command: npm ci
       - run: npm run --prefix apps/desktop build

.github/workflows/uv-lockfile-check.yml

@@ -44,25 +44,14 @@ name: uv.lock check
 # the same way.  Better to catch it here than after merge.
 
 on:
-  push:
-    branches: [main]
-    paths:
-      - "pyproject.toml"
-      - "uv.lock"
-      - ".github/workflows/uv-lockfile-check.yml"
-
-  # No paths filter — the job must always run so the required check
-  # reports a status (path-gated workflows leave checks "pending" forever
-  # when no matching files change, which blocks merge).
-  pull_request:
-    branches: [main]
+  workflow_call:
 
 permissions:
   contents: read
 
 concurrency:
   group: uv-lockfile-check-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  cancel-in-progress: true
 
 jobs:
   check:

acp_adapter/entry.py

@@ -23,6 +23,11 @@ except ModuleNotFoundError:
     # new code but ``uv pip install -e .`` didn't finish.  Missing bootstrap
     # means UTF-8 stdio setup is skipped on Windows; POSIX is unaffected.
     pass
+else:
+    # Stop a ``utils/``/``proxy/``/``ui/`` package in the launch directory from
+    # shadowing Hermes's own modules — ``hermes acp`` can be started from any
+    # cwd, including a project that has same-named packages on its path.
+    hermes_bootstrap.harden_import_path()
 
 import argparse
 import asyncio

agent/anthropic_adapter.py

@@ -1297,7 +1297,15 @@ def run_oauth_setup_token() -> Optional[str]:
 # Stores credentials in ~/.hermes/.anthropic_oauth.json (our own file).
 
 _OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
-_OAUTH_TOKEN_URL = "https://console.anthropic.com/v1/oauth/token"
+# Anthropic migrated the OAuth token endpoint to platform.claude.com;
+# console.anthropic.com now 404s. Callers should iterate _OAUTH_TOKEN_URLS
+# (new host first, console fallback). _OAUTH_TOKEN_URL is kept as the primary
+# for backward compatibility with existing imports and now points at the live host.
+_OAUTH_TOKEN_URLS = [
+    "https://platform.claude.com/v1/oauth/token",
+    "https://console.anthropic.com/v1/oauth/token",
+]
+_OAUTH_TOKEN_URL = _OAUTH_TOKEN_URLS[0]
 _OAUTH_REDIRECT_URI = "https://console.anthropic.com/oauth/code/callback"
 _OAUTH_SCOPES = "org:create_api_key user:profile user:inference"
 _HERMES_OAUTH_FILE = get_hermes_home() / ".anthropic_oauth.json"
@@ -1395,18 +1403,34 @@ def run_hermes_oauth_login_pure() -> Optional[Dict[str, Any]]:
             "code_verifier": verifier,
         }).encode()
 
-        req = urllib.request.Request(
-            _OAUTH_TOKEN_URL,
-            data=exchange_data,
-            headers={
-                "Content-Type": "application/json",
-                "User-Agent": f"claude-cli/{_get_claude_code_version()} (external, cli)",
-            },
-            method="POST",
-        )
+        # Anthropic migrated the OAuth token endpoint to platform.claude.com;
+        # console.anthropic.com now 404s. Try the new host first, then fall
+        # back to console for older deployments (mirrors the refresh path).
+        result = None
+        last_error = None
+        for endpoint in _OAUTH_TOKEN_URLS:
+            req = urllib.request.Request(
+                endpoint,
+                data=exchange_data,
+                headers={
+                    "Content-Type": "application/json",
+                    "User-Agent": f"claude-cli/{_get_claude_code_version()} (external, cli)",
+                },
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=15) as resp:
+                    result = json.loads(resp.read().decode())
+                break
+            except Exception as exc:
+                last_error = exc
+                logger.debug("Anthropic token exchange failed at %s: %s", endpoint, exc)
+                continue
 
-        with urllib.request.urlopen(req, timeout=15) as resp:
-            result = json.loads(resp.read().decode())
+        if result is None:
+            raise last_error if last_error is not None else ValueError(
+                "Anthropic token exchange failed"
+            )
     except Exception as e:
         print(f"Token exchange failed: {e}")
         return None

agent/background_review.py

@@ -27,6 +27,131 @@ from typing import Any, Dict, List, Optional
 logger = logging.getLogger(__name__)
 
 
+# ---------------------------------------------------------------------------
+# Background-review aux-model selector + routed digest.
+#
+# The review fork runs on the MAIN model by default ("auto"), replaying the
+# full conversation — already warm in the prompt cache, so cheap cache reads.
+# Optimal and unchanged. A user can route the review to a different, cheaper
+# model via auxiliary.background_review.{provider,model}. A different model
+# cannot reuse the parent's cache (different key), so the fork is cold
+# regardless — replaying the full transcript would just cold-write it. So when
+# (and only when) routed to a different model, we replay a compact DIGEST to
+# minimise cold-written tokens. Same model -> full replay; different model ->
+# digest. That's the whole policy.
+# ---------------------------------------------------------------------------
+
+
+def _resolve_review_runtime(agent: Any) -> Dict[str, Any]:
+    """Resolve provider/model/credentials for the review fork.
+
+    Default (auto / unset / same as parent): inherit the parent's live runtime
+    (with codex_app_server -> codex_responses downgrade). ``routed`` is False —
+    the fork uses the main model and the warm cache, exactly as before. When
+    ``auxiliary.background_review.{provider,model}`` names a concrete model
+    different from the parent's, resolve that runtime and set ``routed=True``.
+    """
+    parent_runtime = agent._current_main_runtime()
+    parent_api_mode = parent_runtime.get("api_mode") or None
+    if parent_api_mode == "codex_app_server":
+        parent_api_mode = "codex_responses"
+    parent = {
+        "provider": agent.provider,
+        "model": agent.model,
+        "api_key": parent_runtime.get("api_key") or None,
+        "base_url": parent_runtime.get("base_url") or None,
+        "api_mode": parent_api_mode,
+        "routed": False,
+    }
+    try:
+        from hermes_cli.config import load_config
+        cfg = load_config()
+    except Exception:
+        return parent
+    aux = cfg.get("auxiliary", {}) if isinstance(cfg.get("auxiliary"), dict) else {}
+    task = aux.get("background_review", {}) if isinstance(aux.get("background_review"), dict) else {}
+    task_provider = (str(task.get("provider", "")).strip() or None)
+    task_model = (str(task.get("model", "")).strip() or None)
+    task_base_url = (str(task.get("base_url", "")).strip() or None)
+    task_api_key = (str(task.get("api_key", "")).strip() or None)
+    if not (task_provider and task_provider != "auto" and task_model):
+        return parent
+    if task_provider == (agent.provider or "") and task_model == (agent.model or ""):
+        return parent  # same model/provider as parent -> not routed
+    try:
+        from hermes_cli.runtime_provider import resolve_runtime_provider
+        rp = resolve_runtime_provider(
+            requested=task_provider,
+            target_model=task_model,
+            explicit_api_key=task_api_key,
+            explicit_base_url=task_base_url,
+        )
+        return {
+            "provider": rp.get("provider") or task_provider,
+            "model": task_model,
+            "api_key": rp.get("api_key"),
+            "base_url": rp.get("base_url"),
+            "api_mode": rp.get("api_mode"),
+            "routed": True,
+        }
+    except Exception as e:
+        logger.debug("background-review aux routing failed (%s); using main model", e)
+        return parent
+
+
+def _msg_text(m: Dict) -> str:
+    c = m.get("content")
+    if isinstance(c, str):
+        return c.strip()
+    if isinstance(c, list):
+        return " ".join(b.get("text", "") for b in c if isinstance(b, dict)).strip()
+    return ""
+
+
+def _digest_history(messages_snapshot: List[Dict], tail: int = 24) -> List[Dict]:
+    """Compact replay for the routed (different-model) path only.
+
+    Keeps the recent ``tail`` messages verbatim, collapses older turns into one
+    synthetic user-role digest, preserving role alternation. Used ONLY when
+    routed to a different model (cache cold regardless, so fewer cold-written
+    tokens is a pure win). Never on the main-model path (full replay stays warm).
+    """
+    msgs = list(messages_snapshot or [])
+    if len(msgs) <= tail:
+        return msgs
+    keep = msgs[-tail:]
+    while keep and isinstance(keep[0], dict) and keep[0].get("role") == "tool":
+        tail += 1
+        if len(msgs) <= tail:
+            return msgs
+        keep = msgs[-tail:]
+    old = msgs[:-len(keep)]
+    lines: List[str] = []
+    for m in old:
+        if not isinstance(m, dict):
+            continue
+        role = m.get("role")
+        text = _msg_text(m).replace("\n", " ")
+        if role == "user" and text:
+            lines.append(f"USER: {text[:300]}")
+        elif role == "assistant":
+            tcs = m.get("tool_calls") or []
+            if tcs:
+                names = [(tc.get("function") or {}).get("name", "?") for tc in tcs if isinstance(tc, dict)]
+                lines.append(f"ASSISTANT[tools: {', '.join(names)}]")
+            if text:
+                lines.append(f"ASSISTANT: {text[:200]}")
+    digest = {
+        "role": "user",
+        "content": (
+            "[Earlier conversation digest — older turns summarised to bound the "
+            "review's cold-write cost on the routed aux model. Recent turns "
+            "follow verbatim below.]\n" + "\n".join(lines)
+        ),
+    }
+    return [digest] + keep
+
+
 # Review-prompt strings — used by ``spawn_background_review_thread`` to build
 # the user-message that the forked review agent receives.  AIAgent exposes
 # them as class attributes (``_MEMORY_REVIEW_PROMPT`` etc.) for back-compat;
@@ -488,18 +613,13 @@ def _run_review_in_thread(
             # creds, or credential-pool setups where the resolver can't
             # reconstruct auth from scratch -- producing the spurious
             # "No LLM provider configured" warning at end of turn.
-            _parent_runtime = agent._current_main_runtime()
-            _parent_api_mode = _parent_runtime.get("api_mode") or None
-            # The review fork needs to call agent-loop tools (memory,
-            # skill_manage). Those tools require Hermes' own dispatch,
-            # which the codex_app_server runtime bypasses entirely
-            # (it runs the turn inside codex's subprocess). So when
-            # the parent is on codex_app_server, downgrade the review
-            # fork to codex_responses — same auth/credentials, but
-            # talks to the OpenAI Responses API directly so Hermes
-            # owns the loop and the agent-loop tools dispatch.
-            if _parent_api_mode == "codex_app_server":
-                _parent_api_mode = "codex_responses"
+            # _resolve_review_runtime() returns the parent's live runtime by
+            # default (routed=False; main model, warm cache), or — when the user
+            # set auxiliary.background_review.{provider,model} to a different
+            # model — that model's runtime (routed=True). The codex_app_server
+            # -> codex_responses downgrade is applied inside the resolver.
+            _rt = _resolve_review_runtime(agent)
+            _routed = bool(_rt.get("routed"))
             # skip_memory=True keeps the review fork from
             # touching external memory plugins (honcho, mem0,
             # supermemory, etc.).  Without it, the fork's
@@ -519,14 +639,14 @@ def _run_review_in_thread(
             # in the request body — Anthropic's cache key includes it.
             # (The runtime whitelist below still restricts dispatch.)
             review_agent = AIAgent(
-                model=agent.model,
+                model=_rt.get("model") or agent.model,
                 max_iterations=16,
                 quiet_mode=True,
                 platform=agent.platform,
-                provider=agent.provider,
-                api_mode=_parent_api_mode,
-                base_url=_parent_runtime.get("base_url") or None,
-                api_key=_parent_runtime.get("api_key") or None,
+                provider=_rt.get("provider") or agent.provider,
+                api_mode=_rt.get("api_mode"),
+                base_url=_rt.get("base_url") or None,
+                api_key=_rt.get("api_key") or None,
                 credential_pool=getattr(agent, "_credential_pool", None),
                 parent_session_id=agent.session_id,
                 enabled_toolsets=getattr(agent, "enabled_toolsets", None),
@@ -565,15 +685,20 @@ def _run_review_in_thread(
             # issue #25322 and PR #17276 for the full analysis +
             # measured impact (~26% end-to-end cost reduction on
             # Sonnet 4.5).
-            review_agent._cached_system_prompt = agent._cached_system_prompt
-            # Defensive: pin session_start + session_id to the
-            # parent's so any code path that re-renders parts of
-            # the system prompt (compression, plugin hooks) still
-            # produces byte-identical output. The cached-prompt
-            # assignment above already short-circuits the normal
-            # rebuild path, but these pins guarantee parity even
-            # if a future code path bypasses the cache.
-            review_agent.session_start = agent.session_start
+            # Share the parent's warm cached system prompt ONLY when the review
+            # runs on the SAME model (not routed). When routed to a different
+            # model the parent's cached prompt is for the wrong model/cache key
+            # and would miss anyway, so let the routed fork build its own.
+            if not _routed:
+                review_agent._cached_system_prompt = agent._cached_system_prompt
+                # Defensive: pin session_start + session_id to the
+                # parent's so any code path that re-renders parts of
+                # the system prompt (compression, plugin hooks) still
+                # produces byte-identical output. The cached-prompt
+                # assignment above already short-circuits the normal
+                # rebuild path, but these pins guarantee parity even
+                # if a future code path bypasses the cache.
+                review_agent.session_start = agent.session_start
             review_agent.session_id = agent.session_id
             # The fork shares the parent's live session_id (pinned above for
             # prefix-cache parity). It is single-lifecycle and calls close()
@@ -615,6 +740,13 @@ def _run_review_in_thread(
                 ),
             )
             try:
+                # Routed to a different model -> replay a digest (cache is cold
+                # on that model anyway, so minimise cold-written tokens). Same
+                # model -> replay the full snapshot (warm cache reads).
+                _review_history = (
+                    _digest_history(messages_snapshot) if _routed
+                    else messages_snapshot
+                )
                 review_agent.run_conversation(
                     user_message=(
                         prompt
@@ -622,7 +754,7 @@ def _run_review_in_thread(
                         "management tools. Other tools will be denied "
                         "at runtime — do not attempt them."
                     ),
-                    conversation_history=messages_snapshot,
+                    conversation_history=_review_history,
                 )
             finally:
                 clear_thread_tool_whitelist()

agent/coding_context.py

@@ -635,25 +635,32 @@ def _read_small(path: Path) -> str:
         return ""
 
 
-def _project_facts(root: Path) -> list[str]:
-    """Detected project facts for the workspace snapshot.
+@dataclass(frozen=True)
+class ProjectFacts:
+    """Structured project facts — the model's verify loop, detected once.
 
-    The point is to hand the model its *verify loop* up front — which manifest,
-    which package manager, and the exact test/lint/build commands — instead of
-    making it rediscover them every session. Cheap: stat calls plus reads of a
-    couple of small files; built once at prompt-build time (cache-safe).
+    The same data that feeds the workspace snapshot, exposed structurally so
+    non-prompt consumers (e.g. the desktop verify UI) read it instead of
+    re-detecting and drifting from the prompt.
     """
-    facts: list[str] = []
 
+    manifests: list[str]
+    package_managers: list[str]
+    verify_commands: list[str]
+    context_files: list[str]
+
+
+def detect_project_facts(root: Path) -> ProjectFacts:
+    """Detect manifests, package manager(s), verify commands, and context files.
+
+    Cheap: stat calls plus reads of a couple of small files. The single source
+    of truth for both the prompt snapshot (:func:`_project_facts`) and the
+    gateway's ``project.facts`` — so the UI never re-sniffs verify commands.
+    """
     manifests = [m for m in _PROJECT_MARKERS if m not in _CONTEXT_FILES and (root / m).is_file()]
-    package_managers = [
-        pm for lock, pm in (*_PY_LOCKFILES, *_JS_LOCKFILES) if (root / lock).is_file()
-    ]
-    if manifests:
-        line = f"- Project: {', '.join(manifests[:6])}"
-        if package_managers:
-            line += f" ({'/'.join(dict.fromkeys(package_managers))})"
-        facts.append(line)
+    package_managers = list(
+        dict.fromkeys(pm for lock, pm in (*_PY_LOCKFILES, *_JS_LOCKFILES) if (root / lock).is_file())
+    )
 
     verify: list[str] = []
     if (root / "scripts" / "run_tests.sh").is_file():
@@ -673,17 +680,61 @@ def _project_facts(root: Path) -> list[str]:
             f"make {name}" for name in _VERIFY_TARGETS
             if re.search(rf"^{re.escape(name)}\s*:", makefile, re.MULTILINE)
         )
-    if verify:
-        deduped = list(dict.fromkeys(verify))[:_MAX_VERIFY_COMMANDS]
-        facts.append(f"- Verify: {'; '.join(deduped)}")
 
-    context_files = [c for c in _CONTEXT_FILES if (root / c).is_file()]
-    if context_files:
-        facts.append(f"- Context files: {', '.join(context_files)}")
+    return ProjectFacts(
+        manifests=manifests,
+        package_managers=package_managers,
+        verify_commands=list(dict.fromkeys(verify))[:_MAX_VERIFY_COMMANDS],
+        context_files=[c for c in _CONTEXT_FILES if (root / c).is_file()],
+    )
+
+
+def _project_facts(root: Path) -> list[str]:
+    """Render :func:`detect_project_facts` as workspace-snapshot lines.
+
+    Hands the model its *verify loop* up front — which manifest, which package
+    manager, and the exact test/lint/build commands — instead of making it
+    rediscover them every session. Built once at prompt-build time; the string
+    output must stay byte-stable to preserve the prompt cache.
+    """
+    f = detect_project_facts(root)
+    facts: list[str] = []
+
+    if f.manifests:
+        line = f"- Project: {', '.join(f.manifests[:6])}"
+        if f.package_managers:
+            line += f" ({'/'.join(f.package_managers)})"
+        facts.append(line)
+    if f.verify_commands:
+        facts.append(f"- Verify: {'; '.join(f.verify_commands)}")
+    if f.context_files:
+        facts.append(f"- Context files: {', '.join(f.context_files)}")
 
     return facts
 
 
+def project_facts_for(cwd: Optional[str | Path] = None) -> Optional[dict[str, Any]]:
+    """Structured project facts for ``cwd`` — ``None`` outside a workspace.
+
+    Same detection the system-prompt snapshot uses (git root, else marker root),
+    exposed for non-prompt consumers (the desktop verify UI) so they never
+    re-derive "are we coding?" or duplicate the verify-command sniffing.
+    """
+    resolved = _resolve_cwd(cwd)
+    root = _git_root(resolved) or _marker_root(resolved)
+    if root is None:
+        return None
+
+    f = detect_project_facts(root)
+    return {
+        "root": str(root),
+        "manifests": f.manifests,
+        "packageManagers": f.package_managers,
+        "verifyCommands": f.verify_commands,
+        "contextFiles": f.context_files,
+    }
+
+
 def build_coding_workspace_block(cwd: Optional[str | Path] = None) -> str:
     """Workspace snapshot for the system prompt (empty outside a workspace).
 

agent/context_compressor.py

@@ -890,7 +890,15 @@ class ContextCompressor(ContextEngine):
         # This is independent of the abort_on_summary_failure config flag:
         # rotating on a broken credential is never the right behavior.
         self._last_summary_auth_failure: bool = False
-        # When a user-configured summary model fails and we recover by
+        # Set when summary generation ultimately fails due to a transient
+        # network/connection error (httpx/httpcore connection drop, premature
+        # stream close, etc.) — distinct from auth failures but treated the
+        # same way by compress(): ABORT and preserve the session unchanged
+        # rather than destroy the middle window for a deterministic
+        # "summary unavailable" marker. Retrying once the network recovers is
+        # strictly better than discarding context for a transient blip
+        # (#29559, #25585). Independent of abort_on_summary_failure.
+        self._last_summary_network_failure: bool = False
         # retrying on the main model, record the failure so gateway /
         # CLI callers can still warn the user even though compression
         # succeeded.  Silent recovery would hide the broken config.
@@ -1687,6 +1695,7 @@ This compaction should PRIORITISE preserving all information related to the focu
             self._summary_model_fallen_back = False
             self._last_summary_error = None
             self._last_summary_auth_failure = False
+            self._last_summary_network_failure = False
             return self._with_summary_prefix(summary)
         except Exception as e:
             # ``call_llm`` raises ``RuntimeError`` for two very different cases:
@@ -1819,6 +1828,15 @@ This compaction should PRIORITISE preserving all information related to the focu
             if len(err_text) > 220:
                 err_text = err_text[:217].rstrip() + "..."
             self._last_summary_error = err_text
+            # A terminal connection/network failure (we reach this branch only
+            # after any main-model fallback has already been tried or is
+            # unavailable). Flag it so compress() ABORTS and preserves the
+            # session unchanged instead of destroying the middle window for a
+            # placeholder marker — retrying once the network recovers is
+            # strictly better than dropping context (#29559, #25585). Mirrors
+            # the auth-failure carve-out; independent of abort_on_summary_failure.
+            if _is_streaming_closed:
+                self._last_summary_network_failure = True
             logger.warning(
                 "Failed to generate context summary: %s. "
                 "Further summary attempts paused for %d seconds.",
@@ -2382,6 +2400,7 @@ This compaction should PRIORITISE preserving all information related to the focu
         self._last_aux_model_failure_model = None
         self._last_compress_aborted = False
         self._last_summary_auth_failure = False
+        self._last_summary_network_failure = False
 
         # Manual /compress (force=True) bypasses the failure cooldown so the
         # user can retry immediately after an auto-compress abort.  Without
@@ -2498,15 +2517,21 @@ This compaction should PRIORITISE preserving all information related to the focu
         #           surface a warning.
         # Default is False (historical behavior).
         #
-        # EXCEPTION — auth failures always abort. A 401/403 from the summary
-        # call means the credential or endpoint is broken (invalid/blocked
-        # key, or a token pointed at the wrong inference host). Rotating into
+        # EXCEPTION — auth AND transient network failures always abort. A
+        # 401/403 from the summary call means the credential or endpoint is
+        # broken (invalid/blocked key, or a token pointed at the wrong
+        # inference host). A connection/stream-close error means the network
+        # blipped at the compaction moment (#29559). In BOTH cases rotating into
         # a child session with a placeholder summary on a broken credential
         # strands the user on a degraded session for zero benefit — every
         # subsequent call fails the same way. So when the failure was an auth
         # error we abort regardless of abort_on_summary_failure, preserving
         # the conversation unchanged until the credential is fixed.
-        if not summary and (self.abort_on_summary_failure or self._last_summary_auth_failure):
+        if not summary and (
+            self.abort_on_summary_failure
+            or self._last_summary_auth_failure
+            or self._last_summary_network_failure
+        ):
             n_skipped = compress_end - compress_start
             self._last_summary_dropped_count = 0  # nothing actually dropped
             self._last_summary_fallback_used = False
@@ -2521,6 +2546,15 @@ This compaction should PRIORITISE preserving all information related to the focu
                         "with /compress or start fresh with /new.",
                         n_skipped,
                     )
+                elif self._last_summary_network_failure:
+                    logger.warning(
+                        "Summary generation failed with a network/connection "
+                        "error — aborting compression. %d message(s) preserved "
+                        "unchanged; the session was NOT rotated. This is "
+                        "transient: retry with /compress once connectivity "
+                        "recovers, or continue the conversation as-is.",
+                        n_skipped,
+                    )
                 else:
                     logger.warning(
                         "Summary generation failed — aborting compression "

agent/conversation_compression.py

@@ -805,10 +805,11 @@ def try_shrink_image_parts_in_messages(
     Pillow couldn't help (caller should surface the original error).
 
     Strategy: look for ``image_url`` / ``input_image`` parts carrying a
-    ``data:image/...;base64,...`` payload.  For each one whose encoded
-    size exceeds 4 MB (a safe target that slides under Anthropic's 5 MB
-    ceiling with header overhead) or whose longest side exceeds
-    ``max_dimension``, write the base64 to a tempfile, call
+    ``data:image/...;base64,...`` payload, plus Anthropic-native
+    ``{"type": "image", "source": {"type": "base64", ...}}`` blocks.
+    For each one whose encoded size exceeds 4 MB (a safe target that slides
+    under Anthropic's 5 MB ceiling with header overhead) or whose longest side
+    exceeds ``max_dimension``, write the base64 to a tempfile, call
     ``vision_tools._resize_image_for_vision`` to produce a smaller data
     URL, and substitute it in place.
 
@@ -964,6 +965,28 @@ def try_shrink_image_parts_in_messages(
             logger.warning("image-shrink recovery: re-encode failed — %s", exc)
             return None, triggered_by is not None
 
+    def _source_to_data_url(source: Any) -> Optional[str]:
+        if not isinstance(source, dict) or source.get("type") != "base64":
+            return None
+        data = source.get("data")
+        if not isinstance(data, str) or not data:
+            return None
+        media_type = str(source.get("media_type") or "image/jpeg").strip()
+        if not media_type.startswith("image/"):
+            media_type = "image/jpeg"
+        return f"data:{media_type};base64,{data}"
+
+    def _write_data_url_to_source(source: dict, data_url: str) -> None:
+        header, _, data = data_url.partition(",")
+        media_type = "image/jpeg"
+        if header.startswith("data:"):
+            candidate = header[len("data:"):].split(";", 1)[0].strip()
+            if candidate.startswith("image/"):
+                media_type = candidate
+        source["type"] = "base64"
+        source["media_type"] = media_type
+        source["data"] = data
+
     for msg in api_messages:
         if not isinstance(msg, dict):
             continue
@@ -974,6 +997,16 @@ def try_shrink_image_parts_in_messages(
             if not isinstance(part, dict):
                 continue
             ptype = part.get("type")
+            if ptype == "image":
+                source = part.get("source")
+                url = _source_to_data_url(source)
+                resized, unshrinkable = _shrink_data_url(url or "")
+                if resized and isinstance(source, dict):
+                    _write_data_url_to_source(source, resized)
+                    changed_count += 1
+                elif unshrinkable:
+                    unshrinkable_oversized += 1
+                continue
             if ptype not in {"image_url", "input_image"}:
                 continue
             image_value = part.get("image_url")

agent/conversation_loop.py

@@ -4050,6 +4050,19 @@ def run_conversation(
 
                 messages.append(assistant_msg)
                 agent._emit_interim_assistant_message(assistant_msg)
+                try:
+                    # Persist the assistant tool-call turn before any tool
+                    # side effects run. If a destructive tool restarts or
+                    # terminates Hermes mid-turn, resume logic still sees the
+                    # exact tool-call block that already executed.
+                    agent._flush_messages_to_session_db(messages, conversation_history)
+                except Exception as exc:
+                    logger.warning(
+                        "Incremental tool-call persistence failed before execution "
+                        "(session=%s): %s",
+                        agent.session_id or "none",
+                        exc,
+                    )
 
                 # Close any open streaming display (response box, reasoning
                 # box) before tool execution begins.  Intermediate turns may

agent/learn_prompt.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""``/learn`` — build the standards-guided prompt that turns whatever the user
+described into a reusable skill.
+
+``/learn`` is open-ended. The user can point it at anything they can describe:
+a directory of code, an API doc URL, a workflow they just walked the agent
+through in this conversation, or pasted notes. This module builds ONE prompt
+that instructs the live agent to:
+
+  1. Gather the sources the user named, using the tools it already has
+     (``read_file`` / ``search_files`` for dirs, ``web_extract`` for URLs, the
+     current conversation for "what I just did", the user's text for pasted
+     material).
+  2. Author a single ``SKILL.md`` via ``skill_manage`` that follows the Hermes
+     skill-authoring standards (description <=60 chars, the modern section
+     order, Hermes-tool framing, no invented commands).
+
+There is no separate distillation engine and no model-tool footprint: the
+agent does the work with its existing toolset, so this works identically on
+local, Docker, and remote terminal backends. Every surface (CLI ``/learn``,
+gateway ``/learn``, the dashboard "Learn a skill" panel) calls
+:func:`build_learn_prompt` and feeds the result to the agent as a normal turn.
+"""
+
+from __future__ import annotations
+
+# The house-style rules, distilled from AGENTS.md "Skill authoring standards
+# (HARDLINE)" and the hermes-agent-dev new-skill salvage reference. Embedded in
+# the prompt so the agent authors skills the way a maintainer would by hand.
+_AUTHORING_STANDARDS = """\
+Follow the Hermes skill-authoring standards exactly:
+
+Frontmatter:
+- name: lowercase-hyphenated, <=64 chars, no spaces.
+- description: ONE sentence, <=60 characters, ends with a period. State the
+  capability, not the implementation. No marketing words (powerful,
+  comprehensive, seamless, advanced). Do NOT repeat the skill name. If the
+  description contains a colon, wrap the whole value in double quotes.
+- version: 0.1.0
+- metadata.hermes.tags: a few Capitalized, Relevant, Tags.
+
+Body section order (omit a section only if it genuinely has no content):
+1. "# <Human Title>" then a 2-3 sentence intro: what it does, what it does NOT
+   do, and the key dependency stance (e.g. "stdlib only").
+2. "## When to Use" — bullet list of concrete trigger phrases.
+3. "## Prerequisites" — exact env vars, install steps, credentials.
+4. "## How to Run" — the canonical invocation, framed through Hermes tools.
+5. "## Quick Reference" — a flat command/endpoint list, no narration.
+6. "## Procedure" — numbered steps with copy-paste-exact commands.
+7. "## Pitfalls" — known limits, rate limits, things that look broken but aren't.
+8. "## Verification" — a single command/check that proves the skill worked.
+
+Hermes-tool framing (this is what makes it a skill, not shell docs):
+- Frame running scripts as "invoke through the `terminal` tool".
+- Use `read_file` (not cat/head/tail), `search_files` (not grep/find/ls),
+  `patch` (not sed/awk), `web_extract` (not curl-to-scrape),
+  `vision_analyze` for images. Reference these tools by name in backticks.
+- Do NOT name shell utilities the agent already has wrapped.
+
+Quality bar:
+- Prefer exact commands, endpoint URLs, function signatures, and config keys
+  that appear VERBATIM in the source. NEVER invent flags, paths, or APIs — if
+  you didn't see it in the source, don't write it.
+- Keep it tight and scannable: ~100 lines for a simple skill, ~200 for a
+  complex one. Don't re-paste the source docs.
+- Don't write a router/index/hub skill that only points at other skills.
+- Larger scripts/parsers belong in a `scripts/` file (add via
+  `skill_manage` write_file), referenced from SKILL.md by relative path — not
+  inlined for the agent to re-type every run."""
+
+
+def build_learn_prompt(user_request: str) -> str:
+    """Build the agent prompt for an open-ended ``/learn`` request.
+
+    Args:
+        user_request: the free-text the user gave after ``/learn`` — a
+            description of the workflow, paths, URLs, or "what I just did".
+
+    Returns:
+        A complete instruction the agent runs as a normal turn. The agent
+        gathers the described sources with its existing tools and authors the
+        skill via ``skill_manage``.
+    """
+    req = (user_request or "").strip()
+    if not req:
+        req = (
+            "the workflow we just went through in this conversation — review "
+            "the steps taken and distill them into a reusable skill"
+        )
+
+    return (
+        "[/learn] The user wants you to learn a reusable skill from the "
+        "source(s) they described below, and save it.\n\n"
+        f"WHAT TO LEARN FROM:\n{req}\n\n"
+        "Do this:\n"
+        "1. Gather the material. Resolve whatever the user named using the "
+        "tools you already have — `read_file`/`search_files` for local files "
+        "or directories, `web_extract` for URLs, the current conversation "
+        "history if they referred to something you just did, and the text "
+        "they pasted as-is. If the request is ambiguous about scope, make a "
+        "reasonable choice and note it; do not stall.\n"
+        "2. Author ONE SKILL.md and save it with the `skill_manage` tool "
+        "(action=\"create\"). Pick a sensible category. If the procedure needs "
+        "a non-trivial script, add it under the skill's `scripts/` with "
+        "`skill_manage` write_file and reference it by relative path.\n\n"
+        f"{_AUTHORING_STANDARDS}\n\n"
+        "When done, tell the user the skill name, its category, and a "
+        "one-line summary of what it captured."
+    )

agent/oneshot.py

@@ -0,0 +1,158 @@
+"""Shared one-off LLM requests for non-conversational helpers.
+
+A "one-shot" is a single, stateless model call that runs *outside* any
+conversation: it never touches a session's history, never breaks prompt
+caching, and returns plain text. UI surfaces use it for small generative
+chores — a commit message from a diff, a rename suggestion, a summary —
+where spinning up an agent turn would be wrong (it would pollute the thread)
+and hand-rolling an LLM call at every call site would be worse.
+
+Two ways to call it:
+
+  * ``run_oneshot(instructions=..., user_input=...)`` — caller supplies the
+    full prompt.
+  * ``run_oneshot(template="commit_message", variables={...})`` — caller
+    names a registered template and passes its variables; the template owns
+    the prompt engineering so it stays consistent across CLI/TUI/desktop.
+
+Model selection rides the same auxiliary plumbing as title generation
+(:func:`agent.auxiliary_client.call_llm`): pass ``main_runtime`` to inherit
+the live session's provider/model, otherwise the configured ``task`` (default
+``title_generation``) resolves a cheap/fast backend.
+"""
+
+import logging
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from agent.auxiliary_client import call_llm, extract_content_or_reasoning
+
+logger = logging.getLogger(__name__)
+
+# A template turns a variables dict into a (instructions, user_input) pair.
+# Templates are plain callables (not str.format) so diff/code payloads with
+# literal "{" / "}" pass through untouched.
+PromptTemplate = Callable[[Dict[str, Any]], Tuple[str, str]]
+
+
+def _truncate(text: str, limit: int) -> str:
+    text = text or ""
+    if len(text) <= limit:
+        return text
+    return text[:limit].rstrip() + "\n…(truncated)"
+
+
+_COMMIT_INSTRUCTIONS = (
+    "You write git commit messages. Given a diff of staged changes, write ONE "
+    "concise Conventional Commits message describing what the change does and why.\n"
+    "Rules:\n"
+    "- Subject line: type(scope): summary — imperative mood, lower-case, no "
+    "trailing period, ≤ 72 characters. Types: feat, fix, refactor, perf, docs, "
+    "test, build, chore, style, ci.\n"
+    "- Omit the scope if it isn't obvious.\n"
+    "- Add a short body (wrapped at ~72 cols) ONLY when the change needs "
+    "explanation; skip it for small/obvious changes.\n"
+    "- Describe the actual change, never restate the diff line-by-line.\n"
+    "- Return ONLY the commit message text — no quotes, no markdown fences, no "
+    "preamble."
+)
+
+
+def _commit_message_template(variables: Dict[str, Any]) -> Tuple[str, str]:
+    diff = _truncate(str(variables.get("diff") or ""), 12000)
+    recent = _truncate(str(variables.get("recent_commits") or ""), 1500)
+
+    parts = []
+    if recent.strip():
+        parts.append(
+            "Recent commit subjects from this repo (match their style/conventions):\n"
+            f"{recent}"
+        )
+    parts.append("Diff to describe:\n" + (diff or "(no textual diff available)"))
+
+    # "Regenerate" must yield something new even on models that decode greedily
+    # / pin temperature server-side. A trailing nonce isn't enough, so we hand
+    # back the previous message and require a genuinely different one.
+    avoid = _truncate(str(variables.get("avoid") or "").strip(), 1000)
+    if avoid:
+        parts.append(
+            "You already proposed the message below and the user wants a "
+            "different one. Write a NEW message with different wording (and, if "
+            "reasonable, a different emphasis or scope framing) — do not repeat "
+            f"it:\n{avoid}"
+        )
+
+    return _COMMIT_INSTRUCTIONS, "\n\n".join(parts)
+
+
+# Registry of named templates. Add an entry here to give a new surface a
+# consistent, reusable prompt without teaching every caller the prompt text.
+PROMPT_TEMPLATES: Dict[str, PromptTemplate] = {
+    "commit_message": _commit_message_template,
+}
+
+
+def render_template(name: str, variables: Optional[Dict[str, Any]] = None) -> Tuple[str, str]:
+    """Resolve a registered template into (instructions, user_input).
+
+    Raises KeyError if the template name is unknown so callers fail loudly
+    instead of silently sending an empty prompt.
+    """
+    template = PROMPT_TEMPLATES.get(name)
+    if template is None:
+        raise KeyError(f"unknown one-shot template: {name}")
+    return template(variables or {})
+
+
+def run_oneshot(
+    *,
+    instructions: str = "",
+    user_input: str = "",
+    template: Optional[str] = None,
+    variables: Optional[Dict[str, Any]] = None,
+    task: str = "title_generation",
+    max_tokens: int = 1024,
+    temperature: Optional[float] = 0.3,
+    timeout: float = 60.0,
+    main_runtime: Optional[Dict[str, Any]] = None,
+) -> str:
+    """Run a single stateless LLM request and return its text.
+
+    Provide either a registered ``template`` (+ ``variables``) or an explicit
+    ``instructions`` / ``user_input`` pair. Returns the model's text answer,
+    stripped of surrounding whitespace and any wrapping code fence.
+
+    Raises RuntimeError when no LLM provider is configured (surfaced from
+    :func:`call_llm`) and KeyError for an unknown template name.
+    """
+    if template:
+        instructions, user_input = render_template(template, variables)
+
+    if not (instructions or "").strip() and not (user_input or "").strip():
+        raise ValueError("run_oneshot requires a template or instructions/user_input")
+
+    messages = []
+    if (instructions or "").strip():
+        messages.append({"role": "system", "content": instructions})
+    messages.append({"role": "user", "content": user_input or ""})
+
+    response = call_llm(
+        task=task,
+        messages=messages,
+        max_tokens=max_tokens,
+        temperature=temperature,
+        timeout=timeout,
+        main_runtime=main_runtime,
+    )
+
+    text = (extract_content_or_reasoning(response) or "").strip()
+    return _strip_code_fence(text)
+
+
+def _strip_code_fence(text: str) -> str:
+    """Drop a single wrapping ``` fence the model may have added."""
+    if not text.startswith("```"):
+        return text
+    lines = text.splitlines()
+    if len(lines) >= 2 and lines[0].startswith("```") and lines[-1].strip() == "```":
+        return "\n".join(lines[1:-1]).strip()
+    return text

agent/pet/__init__.py

@@ -0,0 +1,51 @@
+"""Petdex pet engine — shared core for the CLI, TUI, and desktop surfaces.
+
+Petdex (https://github.com/crafter-station/petdex) is a public gallery of
+animated sprite "pets" for coding agents.  Each pet is a ``pet.json`` plus a
+``spritesheet.{webp,png}`` of 192×208 px cells. Current Codex/petdex sheets use
+an 8-column × 9-row atlas; older Hermes/petdex sheets used an 8-row atlas.
+Hermes infers the row taxonomy from the sheet and maps agent activity onto
+idle/run/review/failed/wave/jump.
+
+This package is the **single source of truth** for the feature so the base
+CLI (Python) and TUI (Ink, via ``tui_gateway``) never duplicate the hard
+parts:
+
+- :mod:`agent.pet.constants` — frame geometry + the :class:`PetState` enum.
+- :mod:`agent.pet.state`     — map agent activity → a :class:`PetState`.
+- :mod:`agent.pet.manifest`  — fetch the public petdex manifest.
+- :mod:`agent.pet.store`     — install / list / resolve pets on disk
+                               (profile-aware via ``get_hermes_home()``).
+- :mod:`agent.pet.render`    — decode a spritesheet and encode frames for a
+                               terminal (kitty / iTerm2 / sixel graphics
+                               protocols, with a Unicode half-block
+                               fallback).
+
+Rendering in the Electron desktop is necessarily TypeScript (canvas), but it
+reuses the same on-disk store and the same state semantics.
+
+The whole feature is a *display* concern: it adds no model tool, mutates no
+system prompt or toolset, and therefore has zero effect on prompt caching.
+"""
+
+from agent.pet.constants import (
+    DEFAULT_SCALE,
+    FRAME_H,
+    FRAME_W,
+    FRAMES_PER_STATE,
+    LOOP_MS,
+    STATE_ROWS,
+    PetState,
+)
+from agent.pet.state import derive_pet_state
+
+__all__ = [
+    "DEFAULT_SCALE",
+    "FRAME_H",
+    "FRAME_W",
+    "FRAMES_PER_STATE",
+    "LOOP_MS",
+    "STATE_ROWS",
+    "PetState",
+    "derive_pet_state",
+]

agent/pet/constants.py

@@ -0,0 +1,167 @@
+"""Pet sprite geometry + animation-state taxonomy.
+
+These values are the common petdex/Codex pet geometry. The real ``pet.json``
+usually only carries ``id``/``displayName``/``description``/``spritesheetPath``;
+row taxonomy is inferred from the atlas shape so Hermes can render both legacy
+8-row sheets and current 9-row Codex sheets.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+# Frame geometry (pixels). Current Codex/petdex spritesheets are 8 columns x 9
+# rows (1536x1872), while older Hermes/petdex sheets used 9 columns x 8 rows
+# (1728x1664). Renderers derive both row taxonomy and real column count from the
+# concrete sheet, so either shape works.
+FRAME_W = 192
+FRAME_H = 208
+
+# Frames consumed per animation state (the petdex web app uses CSS
+# ``steps(6)``).  A sheet may physically contain more columns; we only step
+# through the first ``FRAMES_PER_STATE``.
+FRAMES_PER_STATE = 6
+
+# Full-loop duration for one state, milliseconds (petdex default).
+LOOP_MS = 1100
+
+# Default on-screen scale relative to native frame size.  ``display.pet.scale``
+# is the single master scalar: the desktop canvas multiplies its native pixels
+# by it and every terminal surface derives its half-block/kitty column width
+# from it (see :func:`cols_for_scale`), so one number shrinks all three
+# interfaces together.  (petdex's own clients render at 0.7; we default smaller
+# so the kitty/GUI mascot stays a glanceable corner sprite.  The half-block
+# fallback can't shrink as far — see ``UNICODE_MIN_COLS`` — and clamps to its
+# legibility floor instead.)
+DEFAULT_SCALE = 0.33
+
+# User-settable scale bounds (``/pet scale``, desktop slider).  Floor keeps the
+# pet clickable/visible; ceiling stops a fat-fingered value from filling the
+# screen.  The unicode fallback additionally clamps to ``UNICODE_MIN_COLS``.
+MIN_SCALE = 0.1
+MAX_SCALE = 3.0
+
+
+def clamp_scale(scale: float) -> float:
+    """Clamp *scale* to ``[MIN_SCALE, MAX_SCALE]`` (the single validation point)."""
+    return max(MIN_SCALE, min(MAX_SCALE, scale))
+
+# Terminal cells one native frame spans at ``scale == 1.0``.  A cell is ~8px
+# wide, a frame is ``FRAME_W`` (192) px → 24 cells.  This mirrors the kitty
+# graphics placement (``scaled_px // 8``) so at full scale every renderer agrees.
+BASE_UNICODE_COLS = FRAME_W // 8
+
+# Legibility floor for the half-block fallback.  A half-block cell samples the
+# sprite at only 1 horizontal + 2 vertical taps, so below this width a 192×208
+# pet collapses into an unreadable blob *regardless* of scale.  kitty/GUI draw
+# true pixels and have no such floor — that's why the same ``scale: 0.33`` is
+# crisp there but mush in half-blocks.  ``scale`` shrinks the unicode pet down
+# TO this floor (and grows it above), instead of past it into noise.
+UNICODE_MIN_COLS = 16
+
+
+def cols_for_scale(scale: float) -> int:
+    """Half-block width implied by *scale*, clamped to the legibility floor.
+
+    Above the floor it tracks the kitty cell box (``scaled_px // 8``) so the two
+    renderers converge at larger sizes; below it the floor keeps the sprite
+    readable rather than letting it devolve into a blob.
+    """
+    return max(UNICODE_MIN_COLS, round(BASE_UNICODE_COLS * (scale or DEFAULT_SCALE)))
+
+
+def resolve_cols(scale: float, unicode_cols: int = 0) -> int:
+    """Resolve terminal width: explicit *unicode_cols* override, else from *scale*."""
+    return int(unicode_cols) if unicode_cols and int(unicode_cols) > 0 else cols_for_scale(scale)
+
+
+class PetState(str, Enum):
+    """Animation state a pet can be shown in.
+
+    These are Hermes' activity state names. They are not always identical to the
+    source atlas row names: Codex-format pets use rows like ``jumping`` /
+    ``running`` while the UI keeps the shorter ``jump`` / ``run`` names.
+    """
+
+    IDLE = "idle"
+    WAVE = "wave"
+    RUN = "run"
+    FAILED = "failed"
+    REVIEW = "review"
+    JUMP = "jump"
+    WAITING = "waiting"
+
+
+# Legacy Hermes/petdex row order (top -> bottom) used by the older 8-row,
+# 9-column atlas shape.
+LEGACY_STATE_ROWS: list[str] = [
+    PetState.IDLE.value,
+    PetState.WAVE.value,
+    PetState.RUN.value,
+    PetState.FAILED.value,
+    PetState.REVIEW.value,
+    PetState.JUMP.value,
+    "extra1",
+    "extra2",
+]
+
+# Current Petdex row order (top -> bottom) used by 1536x1872 atlases:
+# 8 columns x 9 rows of 192x208 cells.
+CODEX_STATE_ROWS: list[str] = [
+    PetState.IDLE.value,
+    "running-right",
+    "running-left",
+    "waving",
+    "jumping",
+    PetState.FAILED.value,
+    PetState.WAITING.value,
+    "running",
+    PetState.REVIEW.value,
+]
+
+# Default/fallback for callers without a sheet. Prefer the current 9-row Codex
+# format because generated pets and the public Codex pet contract use it.
+STATE_ROWS: list[str] = CODEX_STATE_ROWS
+
+# Canonical Hermes activity names -> accepted row-name aliases in descending
+# preference. This keeps our internal state names stable (`wave`/`jump`/`run`)
+# while matching Petdex's current `waving`/`jumping`/`running` taxonomy.
+STATE_ALIASES: dict[str, tuple[str, ...]] = {
+    PetState.IDLE.value: (PetState.IDLE.value,),
+    PetState.WAVE.value: (PetState.WAVE.value, "waving"),
+    PetState.JUMP.value: (PetState.JUMP.value, "jumping"),
+    PetState.RUN.value: (PetState.RUN.value, "running"),
+    PetState.FAILED.value: (PetState.FAILED.value,),
+    PetState.REVIEW.value: (PetState.REVIEW.value,),
+    PetState.WAITING.value: (PetState.WAITING.value,),
+}
+
+
+def state_aliases_for(state: "PetState | str") -> tuple[str, ...]:
+    """Return accepted row-name aliases for *state* (always non-empty)."""
+    value = state.value if isinstance(state, PetState) else str(state)
+    aliases = STATE_ALIASES.get(value)
+    return aliases if aliases else (value,)
+
+
+def state_rows_for_grid(row_count: int | None) -> list[str]:
+    """Return the row taxonomy for a spritesheet with *row_count* rows."""
+    try:
+        rows = int(row_count or 0)
+    except (TypeError, ValueError):
+        rows = 0
+
+    if rows >= len(CODEX_STATE_ROWS):
+        return CODEX_STATE_ROWS
+    return LEGACY_STATE_ROWS
+
+
+def state_row_index(state: "PetState | str", row_count: int | None = None) -> int:
+    """Return the spritesheet row index for *state* (clamped, never raises)."""
+    rows = state_rows_for_grid(row_count)
+    for name in state_aliases_for(state):
+        try:
+            return rows.index(name)
+        except ValueError:
+            continue
+    return 0  # fall back to the idle row

agent/pet/manifest.py

@@ -0,0 +1,128 @@
+"""Fetch the public petdex manifest.
+
+``https://petdex.dev/api/manifest`` 307-redirects to a JSON document on R2:
+
+    {
+      "generatedAt": "...",
+      "total": 2926,
+      "pets": [
+        {"slug": "boba", "displayName": "Boba", "kind": "creature",
+         "submittedBy": "railly",
+         "spritesheetUrl": "https://assets.petdex.dev/.../spritesheet.webp",
+         "petJsonUrl": "https://assets.petdex.dev/.../pet.json",
+         "zipUrl": "https://assets.petdex.dev/.../boba.zip"},
+        ...
+      ]
+    }
+
+Read-only and unauthenticated; no credentials involved.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+MANIFEST_URL = "https://petdex.dev/api/manifest"
+
+_DEFAULT_TIMEOUT = 20.0
+
+# In-process cache for the (large, slow, identical-per-call) manifest. The list
+# is a static CDN object that barely changes, yet a single session can ask for
+# it many times — every gallery open, plus a full re-fetch per install/select
+# (``find_entry``). A short TTL collapses those into one network hit without
+# going stale for long. Cleared by :func:`clear_cache` (tests).
+_MANIFEST_TTL = 300.0
+_cache: tuple[float, list[ManifestEntry]] | None = None
+
+
+def clear_cache() -> None:
+    """Drop the cached manifest (forces the next fetch to hit the network)."""
+    global _cache
+    _cache = None
+
+
+@dataclass(frozen=True)
+class ManifestEntry:
+    """A single pet's row in the manifest."""
+
+    slug: str
+    display_name: str
+    kind: str
+    submitted_by: str
+    spritesheet_url: str
+    pet_json_url: str
+    zip_url: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ManifestEntry":
+        return cls(
+            slug=str(data.get("slug", "")).strip(),
+            display_name=str(data.get("displayName", "") or data.get("slug", "")),
+            kind=str(data.get("kind", "") or "pet"),
+            submitted_by=str(data.get("submittedBy", "") or ""),
+            spritesheet_url=str(data.get("spritesheetUrl", "") or ""),
+            pet_json_url=str(data.get("petJsonUrl", "") or ""),
+            zip_url=str(data.get("zipUrl", "") or ""),
+        )
+
+
+class ManifestError(RuntimeError):
+    """Raised when the manifest can't be fetched or parsed."""
+
+
+def fetch_manifest(*, timeout: float = _DEFAULT_TIMEOUT, force: bool = False) -> list[ManifestEntry]:
+    """Return every approved pet from the public manifest.
+
+    Cached in-process for ``_MANIFEST_TTL`` seconds (pass ``force=True`` to
+    bypass). Follows the 307 redirect to R2.  Raises :class:`ManifestError` on
+    any network/parse failure so callers can surface a clean message.
+    """
+    global _cache
+
+    if not force and _cache is not None and time.monotonic() - _cache[0] < _MANIFEST_TTL:
+        return _cache[1]
+
+    try:
+        import httpx
+    except ImportError as exc:  # pragma: no cover - httpx is a core dep
+        raise ManifestError("httpx is required to fetch the petdex manifest") from exc
+
+    try:
+        resp = httpx.get(
+            MANIFEST_URL,
+            timeout=timeout,
+            follow_redirects=True,
+            headers={"User-Agent": "hermes-agent-petdex"},
+        )
+        resp.raise_for_status()
+        payload = resp.json()
+    except Exception as exc:  # noqa: BLE001 - normalize to one error type
+        raise ManifestError(f"could not fetch petdex manifest: {exc}") from exc
+
+    pets = payload.get("pets") if isinstance(payload, dict) else None
+    if not isinstance(pets, list):
+        raise ManifestError("petdex manifest had no 'pets' array")
+
+    entries: list[ManifestEntry] = []
+    for raw in pets:
+        if not isinstance(raw, dict):
+            continue
+        entry = ManifestEntry.from_dict(raw)
+        if entry.slug and entry.spritesheet_url:
+            entries.append(entry)
+
+    _cache = (time.monotonic(), entries)
+    return entries
+
+
+def find_entry(slug: str, *, timeout: float = _DEFAULT_TIMEOUT) -> ManifestEntry | None:
+    """Return the manifest entry for *slug*, or ``None`` if not listed."""
+    slug = slug.strip().lower()
+    for entry in fetch_manifest(timeout=timeout):
+        if entry.slug.lower() == slug:
+            return entry
+    return None

agent/pet/render.py

@@ -0,0 +1,618 @@
+"""Decode a pet spritesheet and encode frames for a terminal.
+
+Shared by the base CLI (writes the escape bytes to its own stdout) and the
+TUI (``tui_gateway`` ships the encoded bytes to Ink, which writes them) so the
+decode + capability-detection + protocol-encoding logic exists exactly once.
+
+Supported output modes, in fidelity order:
+
+- ``kitty``   — the kitty graphics protocol (kitty, Ghostty, WezTerm).
+- ``iterm``   — iTerm2 inline images (iTerm2, WezTerm).
+- ``sixel``   — DEC sixel (xterm -ti vt340, foot, mlterm, WezTerm, …).
+- ``unicode`` — 24-bit half-block downscale; works in any truecolor terminal.
+
+Frame decoding requires Pillow (a core Hermes dependency).  If Pillow or the
+spritesheet is unavailable the renderer degrades to ``unicode`` text or an
+empty string rather than raising.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import logging
+import os
+import sys
+from functools import lru_cache
+from pathlib import Path
+
+from agent.pet.constants import (
+    DEFAULT_SCALE,
+    FRAME_H,
+    FRAME_W,
+    FRAMES_PER_STATE,
+    PetState,
+    state_row_index,
+)
+
+logger = logging.getLogger(__name__)
+
+# Public render-mode names accepted by ``display.pet.render_mode``.
+RENDER_MODES = ("auto", "kitty", "iterm", "sixel", "unicode", "off")
+
+
+# ─────────────────────────────────────────────────────────────────────────
+# Terminal capability detection
+# ─────────────────────────────────────────────────────────────────────────
+
+def detect_terminal_graphics() -> str:
+    """Best-effort detection of the richest graphics protocol available.
+
+    Env-based (non-blocking — we never issue a DA1/terminal query that could
+    hang a pipe).  Returns one of ``kitty`` / ``iterm`` / ``sixel`` /
+    ``unicode``.  Conservative: unknown terminals get ``unicode``, which works
+    anywhere with truecolor.
+    """
+    term = os.environ.get("TERM", "").lower()
+    term_program = os.environ.get("TERM_PROGRAM", "").lower()
+
+    # The VS Code / Cursor integrated terminal sets TERM_PROGRAM=vscode
+    # authoritatively but does NOT scrub the terminal env vars it inherits when
+    # launched from another emulator (ITERM_SESSION_ID, KITTY_WINDOW_ID, …).
+    # Trusting those leaks emits an image protocol the embedded xterm.js can't
+    # display — you get a blank frame. Inline images there are opt-in
+    # (terminal.integrated.enableImages), so default to half-blocks, which
+    # always render in its truecolor grid. Users who enabled images can pin
+    # display.pet.render_mode explicitly.
+    if term_program == "vscode":
+        return "unicode"
+
+    # kitty graphics protocol
+    if os.environ.get("KITTY_WINDOW_ID") or "kitty" in term or "ghostty" in term:
+        return "kitty"
+    if term_program in {"ghostty"}:
+        return "kitty"
+
+    # WezTerm speaks both kitty and iterm; prefer kitty (richer placement).
+    if term_program == "wezterm" or os.environ.get("WEZTERM_PANE"):
+        return "kitty"
+
+    # iTerm2 inline images
+    if term_program == "iterm.app" or os.environ.get("ITERM_SESSION_ID"):
+        return "iterm"
+
+    # sixel-capable terminals (env heuristics only)
+    if term_program in {"mintty"} or "foot" in term or "mlterm" in term:
+        return "sixel"
+    if "sixel" in term:
+        return "sixel"
+
+    return "unicode"
+
+
+def resolve_mode(configured: str | None, *, stream=None) -> str:
+    """Resolve the effective render mode from config + the environment.
+
+    ``configured`` is ``display.pet.render_mode`` (``auto`` → detect).  Returns
+    ``off`` when not attached to a TTY (no point emitting graphics into a pipe
+    or logfile).
+    """
+    mode = (configured or "auto").strip().lower()
+    if mode not in RENDER_MODES:
+        mode = "auto"
+    if mode == "off":
+        return "off"
+
+    stream = stream or sys.stdout
+    try:
+        if not (hasattr(stream, "isatty") and stream.isatty()):
+            return "off"
+    except (ValueError, OSError):
+        return "off"
+
+    if mode == "auto":
+        return detect_terminal_graphics()
+    return mode
+
+
+# ─────────────────────────────────────────────────────────────────────────
+# Frame decoding
+# ─────────────────────────────────────────────────────────────────────────
+
+def _open_sheet(path: Path):
+    from PIL import Image
+
+    img = Image.open(path)
+    return img.convert("RGBA")
+
+
+# Max alpha at/below which a frame counts as blank padding.  petdex sheets are
+# left-packed: a state with fewer real frames than ``FRAMES_PER_STATE`` fills
+# the trailing columns with fully transparent cells.  Animating into one flashes
+# the pet blank, so we stop the row at the first such gap.
+_BLANK_ALPHA = 8
+
+
+def _frame_is_blank(frame) -> bool:
+    """True if *frame* has no meaningfully opaque pixel (transparent padding)."""
+    return frame.getchannel("A").getextrema()[1] <= _BLANK_ALPHA
+
+
+@lru_cache(maxsize=16)
+def _raw_frames(
+    sheet_path: str,
+    state_value: str,
+    frame_w: int,
+    frame_h: int,
+    frames_per_state: int,
+) -> tuple:
+    """Cropped, padding-trimmed RGBA frames for one state row (unscaled).
+
+    Steps across the row until the first blank column so pets with ragged
+    per-state frame counts never animate into empty padding.  Cached; returns
+    ``()`` on any decode failure.
+    """
+    try:
+        sheet = _open_sheet(Path(sheet_path))
+        cols = max(1, sheet.width // frame_w)
+        rows = max(1, sheet.height // frame_h)
+        row = state_row_index(state_value, rows)
+        top = row * frame_h
+        # Clamp the row to the sheet (some pets ship fewer rows than the 8 the
+        # taxonomy reserves).
+        if top + frame_h > sheet.height:
+            top = max(0, sheet.height - frame_h)
+
+        frames = []
+        for i in range(min(frames_per_state, cols)):
+            left = i * frame_w
+            frame = sheet.crop((left, top, left + frame_w, top + frame_h))
+            if _frame_is_blank(frame):
+                break  # trailing transparent padding — real frames end here
+            frames.append(frame)
+        return tuple(frames)
+    except Exception as exc:  # noqa: BLE001 - cosmetic feature, never fatal
+        logger.debug("pet frame decode failed (%s, %s): %s", sheet_path, state_value, exc)
+        return ()
+
+
+@lru_cache(maxsize=8)
+def _frames_for(
+    sheet_path: str,
+    state_value: str,
+    frame_w: int,
+    frame_h: int,
+    frames_per_state: int,
+    scale_w: int,
+    scale_h: int,
+):
+    """Return padding-trimmed RGBA frames for one state row, scaled.
+
+    Thin scaling layer over :func:`_raw_frames`; both are cached so repeated
+    frame requests during animation are free.
+    """
+    raw = _raw_frames(sheet_path, state_value, frame_w, frame_h, frames_per_state)
+    if not raw or (scale_w, scale_h) == (frame_w, frame_h):
+        return list(raw)
+    from PIL import Image
+
+    return [f.resize((scale_w, scale_h), Image.LANCZOS) for f in raw]
+
+
+def state_frame_counts(
+    sheet_path: str | Path,
+    *,
+    frame_w: int = FRAME_W,
+    frame_h: int = FRAME_H,
+    frames_per_state: int = FRAMES_PER_STATE,
+) -> dict[str, int]:
+    """Map each driven :class:`PetState` → its real (padding-trimmed) frame count.
+
+    The single source of truth for "how many frames does this state actually
+    have?".  The CLI/TUI consume the trimmed frame lists directly; the gateway
+    ships this map to the desktop canvas, which steps its own loop.
+    """
+    return {
+        state.value: len(
+            _raw_frames(str(sheet_path), state.value, frame_w, frame_h, frames_per_state)
+        )
+        for state in PetState
+    }
+
+
+# ─────────────────────────────────────────────────────────────────────────
+# Encoders
+# ─────────────────────────────────────────────────────────────────────────
+
+def _png_bytes(frame) -> bytes:
+    buf = io.BytesIO()
+    frame.save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def _kitty_apc(ctrl: str, data: str) -> str:
+    """Emit a kitty APC escape for *data*, chunked into ≤4096-byte ``m`` pieces."""
+    chunk = 4096
+    if len(data) <= chunk:
+        return f"\x1b_G{ctrl},m=0;{data}\x1b\\"
+    out = [f"\x1b_G{ctrl},m=1;{data[:chunk]}\x1b\\"]
+    rest = data[chunk:]
+    while rest:
+        piece, rest = rest[:chunk], rest[chunk:]
+        out.append(f"\x1b_Gm={1 if rest else 0};{piece}\x1b\\")
+    return "".join(out)
+
+
+def _encode_kitty(frame, *, cell_cols: int | None = None, cell_rows: int | None = None) -> str:
+    """Encode one frame via the kitty graphics protocol (transmit + display).
+
+    ``a=T`` transmits & displays at the cursor; ``c``/``r`` request a display
+    box in terminal cells so successive frames overwrite the same area.
+    """
+    ctrl = "f=100,a=T,q=2"
+    if cell_cols:
+        ctrl += f",c={cell_cols}"
+    if cell_rows:
+        ctrl += f",r={cell_rows}"
+    return _kitty_apc(ctrl, base64.standard_b64encode(_png_bytes(frame)).decode("ascii"))
+
+
+# ─────────────────────────────────────────────────────────────────────────
+# kitty Unicode placeholders
+#
+# Ink (the TUI's React-for-terminal layer) owns the screen and measures every
+# cell's width, so it can't host raw kitty image escapes (no width to count,
+# clobbered on the next repaint). kitty's *Unicode placeholder* protocol is the
+# grid-safe path: transmit the image once (q=2, virtual placement U=1), then the
+# host app prints ordinary-width placeholder cells (U+10EEEE + diacritics) whose
+# foreground color encodes the image id. Ink counts those as width-1 text, so
+# layout stays correct and the terminal paints the image underneath.
+#   https://sw.kovidgoyal.net/kitty/graphics-protocol/#unicode-placeholders
+# ─────────────────────────────────────────────────────────────────────────
+
+_KITTY_PLACEHOLDER = "\U0010eeee"
+
+# Row/column diacritics, in order (index → diacritic). Verbatim from kitty's
+# gen/rowcolumn-diacritics.txt (Unicode 6.0.0, combining class 230). Index i is
+# the diacritic that encodes the number i; we only ever need the row index.
+_ROWCOL_DIACRITICS: tuple[int, ...] = (
+    0x0305, 0x030D, 0x030E, 0x0310, 0x0312, 0x033D, 0x033E, 0x033F, 0x0346, 0x034A,
+    0x034B, 0x034C, 0x0350, 0x0351, 0x0352, 0x0357, 0x035B, 0x0363, 0x0364, 0x0365,
+    0x0366, 0x0367, 0x0368, 0x0369, 0x036A, 0x036B, 0x036C, 0x036D, 0x036E, 0x036F,
+    0x0483, 0x0484, 0x0485, 0x0486, 0x0487, 0x0592, 0x0593, 0x0594, 0x0595, 0x0597,
+    0x0598, 0x0599, 0x059C, 0x059D, 0x059E, 0x059F, 0x05A0, 0x05A1, 0x05A8, 0x05A9,
+    0x05AB, 0x05AC, 0x05AF, 0x05C4, 0x0610, 0x0611, 0x0612, 0x0613, 0x0614, 0x0615,
+    0x0616, 0x0617, 0x0657, 0x0658, 0x0659, 0x065A, 0x065B, 0x065D, 0x065E, 0x06D6,
+    0x06D7, 0x06D8, 0x06D9, 0x06DA, 0x06DB, 0x06DC, 0x06DF, 0x06E0, 0x06E1, 0x06E2,
+    0x06E4, 0x06E7, 0x06E8, 0x06EB, 0x06EC, 0x0730, 0x0732, 0x0733, 0x0735, 0x0736,
+    0x073A, 0x073D, 0x073F, 0x0740, 0x0741, 0x0743, 0x0745, 0x0747, 0x0749, 0x074A,
+    0x07EB, 0x07EC, 0x07ED, 0x07EE, 0x07EF, 0x07F0, 0x07F1, 0x07F3, 0x0816, 0x0817,
+    0x0818, 0x0819, 0x081B, 0x081C, 0x081D, 0x081E, 0x081F, 0x0820, 0x0821, 0x0822,
+    0x0823, 0x0825, 0x0826, 0x0827, 0x0829, 0x082A, 0x082B, 0x082C, 0x082D, 0x0951,
+    0x0953, 0x0954, 0x0F82, 0x0F83, 0x0F86, 0x0F87, 0x135D, 0x135E, 0x135F, 0x17DD,
+    0x193A, 0x1A17, 0x1A75, 0x1A76, 0x1A77, 0x1A78, 0x1A79, 0x1A7A, 0x1A7B, 0x1A7C,
+    0x1B6B, 0x1B6D, 0x1B6E, 0x1B6F, 0x1B70, 0x1B71, 0x1B72, 0x1B73, 0x1CD0, 0x1CD1,
+    0x1CD2, 0x1CDA, 0x1CDB, 0x1CE0, 0x1DC0, 0x1DC1, 0x1DC3, 0x1DC4, 0x1DC5, 0x1DC6,
+    0x1DC7, 0x1DC8, 0x1DC9, 0x1DCB, 0x1DCC, 0x1DD1, 0x1DD2, 0x1DD3, 0x1DD4, 0x1DD5,
+    0x1DD6, 0x1DD7, 0x1DD8, 0x1DD9, 0x1DDA, 0x1DDB, 0x1DDC, 0x1DDD, 0x1DDE, 0x1DDF,
+    0x1DE0, 0x1DE1, 0x1DE2, 0x1DE3, 0x1DE4, 0x1DE5, 0x1DE6, 0x1DFE, 0x20D0, 0x20D1,
+    0x20D4, 0x20D5, 0x20D6, 0x20D7, 0x20DB, 0x20DC, 0x20E1, 0x20E7, 0x20E9, 0x20F0,
+    0x2CEF, 0x2CF0, 0x2CF1, 0x2DE0, 0x2DE1, 0x2DE2, 0x2DE3, 0x2DE4, 0x2DE5, 0x2DE6,
+    0x2DE7, 0x2DE8, 0x2DE9, 0x2DEA, 0x2DEB, 0x2DEC, 0x2DED, 0x2DEE, 0x2DEF, 0x2DF0,
+    0x2DF1, 0x2DF2, 0x2DF3, 0x2DF4, 0x2DF5, 0x2DF6, 0x2DF7, 0x2DF8, 0x2DF9, 0x2DFA,
+    0x2DFB, 0x2DFC, 0x2DFD, 0x2DFE, 0x2DFF, 0xA66F, 0xA67C, 0xA67D, 0xA6F0, 0xA6F1,
+    0xA8E0, 0xA8E1, 0xA8E2, 0xA8E3, 0xA8E4, 0xA8E5, 0xA8E6, 0xA8E7, 0xA8E8, 0xA8E9,
+    0xA8EA, 0xA8EB, 0xA8EC, 0xA8ED, 0xA8EE, 0xA8EF, 0xA8F0, 0xA8F1, 0xAAB0, 0xAAB2,
+    0xAAB3, 0xAAB7, 0xAAB8, 0xAABE, 0xAABF, 0xAAC1, 0xFE20, 0xFE21, 0xFE22, 0xFE23,
+    0xFE24, 0xFE25, 0xFE26, 0x10A0F, 0x10A38, 0x1D185, 0x1D186, 0x1D187, 0x1D188,
+    0x1D189, 0x1D1AA, 0x1D1AB, 0x1D1AC, 0x1D1AD, 0x1D242, 0x1D243, 0x1D244,
+)
+
+
+def kitty_image_id(slug: str) -> int:
+    """Stable per-pet image id in ``[1, 0x7FFF]``.
+
+    The id is encoded in the placeholder's 24-bit foreground color, so it must
+    be non-zero and fit comfortably under ``0xFFFFFF``. A small CRC keeps it
+    deterministic per slug (so re-renders reuse the same terminal-side image)
+    while making collisions between two different pets unlikely.
+    """
+    import zlib
+
+    return (zlib.crc32(slug.encode("utf-8")) % 0x7FFE) + 1
+
+
+def kitty_color_hex(image_id: int) -> str:
+    """Hex foreground color (``#rrggbb``) that encodes *image_id* for kitty."""
+    return "#%06x" % (image_id & 0xFFFFFF)
+
+
+def kitty_placeholder_rows(cols: int, rows: int) -> list[str]:
+    """Build the placeholder text grid for an *rows*×*cols* image.
+
+    Each line is one row of the grid: the first cell carries the row diacritic
+    (column defaults to 0), and the remaining ``cols-1`` bare placeholders let
+    the terminal auto-increment the column. The foreground color (the image id)
+    is applied by the caller / Ink, not embedded here.
+    """
+    cols = max(1, cols)
+    out: list[str] = []
+    for r in range(max(1, rows)):
+        idx = min(r, len(_ROWCOL_DIACRITICS) - 1)
+        first = _KITTY_PLACEHOLDER + chr(_ROWCOL_DIACRITICS[idx])
+        out.append(first + _KITTY_PLACEHOLDER * (cols - 1))
+    return out
+
+
+def _encode_kitty_virtual(frame, *, image_id: int, cols: int, rows: int) -> str:
+    """Transmit a frame as a kitty *virtual* placement for Unicode placeholders.
+
+    ``a=T`` transmits and creates the placement in one shot; ``U=1`` marks it
+    virtual (no on-screen output, cursor untouched); ``q=2`` suppresses the
+    terminal's OK/error replies that would otherwise corrupt the host app's
+    output. Re-sending with the same ``i`` replaces the image, so the static
+    placeholder cells animate underneath.
+    """
+    ctrl = f"a=T,U=1,i={image_id},c={cols},r={rows},f=100,q=2"
+    return _kitty_apc(ctrl, base64.standard_b64encode(_png_bytes(frame)).decode("ascii"))
+
+
+def _encode_iterm(frame, *, cell_cols: int | None = None, cell_rows: int | None = None) -> str:
+    """Encode one frame as an iTerm2 inline image (OSC 1337 File)."""
+    payload = base64.standard_b64encode(_png_bytes(frame)).decode("ascii")
+    size = len(payload)
+    args = [f"inline=1", f"size={size}", "preserveAspectRatio=1"]
+    if cell_cols:
+        args.append(f"width={cell_cols}")
+    if cell_rows:
+        args.append(f"height={cell_rows}")
+    return f"\x1b]1337;File={';'.join(args)}:{payload}\x07"
+
+
+def _encode_sixel(frame) -> str:
+    """Encode one frame as DEC sixel.
+
+    Quantizes to an adaptive palette (≤255 colors) and emits the sixel band
+    stream.  Pillow has no sixel writer, so this is a compact hand-rolled
+    encoder.  Transparent pixels render as background (color register skipped).
+    """
+    from PIL import Image
+
+    rgba = frame
+    # Composite onto transparent-as-skip: track alpha to decide background.
+    pal = rgba.convert("RGB").quantize(colors=255, method=Image.MEDIANCUT)
+    palette = pal.getpalette() or []
+    px = pal.load()
+    alpha = rgba.getchannel("A").load()
+    w, h = pal.size
+
+    out = ["\x1bP0;1;0q", '"1;1;%d;%d' % (w, h)]
+    # Color register definitions (sixel uses 0..100 scale).
+    used = sorted({px[x, y] for y in range(h) for x in range(w)})
+    for idx in used:
+        r = palette[idx * 3] if idx * 3 < len(palette) else 0
+        g = palette[idx * 3 + 1] if idx * 3 + 1 < len(palette) else 0
+        b = palette[idx * 3 + 2] if idx * 3 + 2 < len(palette) else 0
+        out.append("#%d;2;%d;%d;%d" % (idx, r * 100 // 255, g * 100 // 255, b * 100 // 255))
+
+    # Emit in 6-row bands.
+    for band in range(0, h, 6):
+        for color_idx in used:
+            line = ["#%d" % color_idx]
+            run_char = None
+            run_len = 0
+
+            def flush():
+                nonlocal run_char, run_len
+                if run_char is None:
+                    return
+                if run_len > 3:
+                    line.append("!%d%s" % (run_len, run_char))
+                else:
+                    line.append(run_char * run_len)
+                run_char, run_len = None, 0
+
+            for x in range(w):
+                bits = 0
+                for bit in range(6):
+                    y = band + bit
+                    if y < h and alpha[x, y] > 32 and px[x, y] == color_idx:
+                        bits |= 1 << bit
+                ch = chr(63 + bits)
+                if ch == run_char:
+                    run_len += 1
+                else:
+                    flush()
+                    run_char, run_len = ch, 1
+            flush()
+            out.append("".join(line) + "$")  # carriage return within band
+        out.append("-")  # next band
+    out.append("\x1b\\")
+    return "".join(out)
+
+
+_HALF_BLOCK = "▀"
+
+# A single half-block cell: top pixel + bottom pixel as (r, g, b, a) tuples.
+Cell = tuple[tuple[int, int, int, int], tuple[int, int, int, int]]
+
+
+def _downscale_cells(frame, *, target_cols: int) -> list[list[Cell]]:
+    """Downscale a frame to a grid of half-block cells.
+
+    Each cell pairs a top and bottom pixel so one terminal row encodes two
+    pixel rows.  Returns rows of ``((tr,tg,tb,ta),(br,bg,bb,ba))`` — the
+    framework-neutral representation shared by the ANSI encoder (CLI) and the
+    structured ``cells`` API (Ink).
+    """
+    from PIL import Image
+
+    target_cols = max(4, target_cols)
+    aspect = frame.height / max(1, frame.width)
+    target_rows = max(2, int(round(target_cols * aspect * 0.5)) * 2)
+    small = frame.resize((target_cols, target_rows), Image.LANCZOS).convert("RGBA")
+    px = small.load()
+
+    grid: list[list[Cell]] = []
+    for y in range(0, target_rows, 2):
+        row: list[Cell] = []
+        for x in range(target_cols):
+            top = px[x, y]
+            bottom = px[x, y + 1] if y + 1 < target_rows else (0, 0, 0, 0)
+            row.append((top, bottom))
+        grid.append(row)
+    return grid
+
+
+def _encode_unicode(frame, *, target_cols: int) -> str:
+    """Downscale to truecolor ANSI half-blocks (one char = 2 vertical pixels)."""
+    lines: list[str] = []
+    for row in _downscale_cells(frame, target_cols=target_cols):
+        cells: list[str] = []
+        for (tr, tg, tb, ta), (br, bg, bb, ba) in row:
+            if ta < 32 and ba < 32:
+                cells.append("\x1b[0m ")  # fully transparent → blank
+                continue
+            cells.append(f"\x1b[38;2;{tr};{tg};{tb}m\x1b[48;2;{br};{bg};{bb}m{_HALF_BLOCK}")
+        lines.append("".join(cells) + "\x1b[0m")
+    return "\n".join(lines)
+
+
+# ─────────────────────────────────────────────────────────────────────────
+# Public renderer
+# ─────────────────────────────────────────────────────────────────────────
+
+class PetRenderer:
+    """Holds a pet's spritesheet and yields encoded frames per (state, index).
+
+    Construct once per pet, then call :meth:`frame` on an animation timer.
+    Cheap to call repeatedly — decoded frames are cached.
+    """
+
+    def __init__(
+        self,
+        spritesheet: str | Path,
+        *,
+        mode: str = "unicode",
+        scale: float = DEFAULT_SCALE,
+        unicode_cols: int = 20,
+        frame_w: int = FRAME_W,
+        frame_h: int = FRAME_H,
+        frames_per_state: int = FRAMES_PER_STATE,
+    ) -> None:
+        self.spritesheet = str(spritesheet)
+        self.mode = mode if mode in RENDER_MODES else "unicode"
+        self.scale = scale
+        self.unicode_cols = unicode_cols
+        self.frame_w = frame_w
+        self.frame_h = frame_h
+        self.frames_per_state = frames_per_state
+
+    @property
+    def available(self) -> bool:
+        return self.mode != "off" and Path(self.spritesheet).is_file()
+
+    def frame_count(self, state: PetState | str) -> int:
+        return len(self._frames(state))
+
+    def _frames(self, state: PetState | str):
+        value = state.value if isinstance(state, PetState) else str(state)
+        scale_w = max(1, int(self.frame_w * self.scale))
+        scale_h = max(1, int(self.frame_h * self.scale))
+        return _frames_for(
+            self.spritesheet,
+            value,
+            self.frame_w,
+            self.frame_h,
+            self.frames_per_state,
+            scale_w,
+            scale_h,
+        )
+
+    def cells(self, state: PetState | str, index: int, *, cols: int | None = None) -> list[list[Cell]]:
+        """Return one frame as a half-block cell grid (framework-neutral).
+
+        Used by the TUI, which renders the grid with native Ink color props
+        instead of raw ANSI.  Returns ``[]`` when no frame is available.
+        """
+        frames = self._frames(state)
+        if not frames:
+            return []
+        frame = frames[index % len(frames)]
+        return _downscale_cells(frame, target_cols=cols or self.unicode_cols)
+
+    def _cell_box(self, frame) -> tuple[int, int]:
+        """Terminal cell box for a scaled frame (~8×16 px per cell).
+
+        Must match :meth:`frame` graphics sizing — kitty stretches the image to
+        fill ``c``×``r`` cells, so these must reflect the scaled pixel
+        dimensions, not a native-aspect column count (that upscales small pets).
+        """
+        return max(1, frame.width // 8), max(1, frame.height // 16)
+
+    def kitty_payload(self, state: PetState | str, *, image_id: int) -> dict | None:
+        """Build the kitty Unicode-placeholder payload for one state.
+
+        Returns ``{cols, rows, placeholder, frames}`` where ``frames`` is a
+        list of transmit escapes (one per animation frame, all reusing
+        ``image_id``) and ``placeholder`` is the static text grid Ink paints.
+        Placement geometry is derived from the scaled frame pixels (via
+        :meth:`_cell_box`), not ``unicode_cols`` — kitty upscales to fill
+        ``c``×``r`` cells. ``None`` when no frame is available.
+        """
+        frames = self._frames(state)
+        if not frames:
+            return None
+        cols, rows = self._cell_box(frames[0])
+        return {
+            "cols": cols,
+            "rows": rows,
+            "placeholder": kitty_placeholder_rows(cols, rows),
+            "frames": [
+                _encode_kitty_virtual(f, image_id=image_id, cols=cols, rows=rows) for f in frames
+            ],
+        }
+
+    def frame(self, state: PetState | str, index: int) -> str:
+        """Return the encoded escape string for one frame, or ``""``.
+
+        ``index`` is taken modulo the available frame count so callers can pass
+        a free-running counter.
+        """
+        if self.mode == "off":
+            return ""
+        frames = self._frames(state)
+        if not frames:
+            return ""
+        frame = frames[index % len(frames)]
+        cell_cols, cell_rows = self._cell_box(frame)
+
+        try:
+            if self.mode == "kitty":
+                return _encode_kitty(frame, cell_cols=cell_cols, cell_rows=cell_rows)
+            if self.mode == "iterm":
+                return _encode_iterm(frame, cell_cols=cell_cols, cell_rows=cell_rows)
+            if self.mode == "sixel":
+                return _encode_sixel(frame)
+            return _encode_unicode(frame, target_cols=self.unicode_cols)
+        except Exception as exc:  # noqa: BLE001 - degrade silently
+            logger.debug("pet frame encode failed (mode=%s): %s", self.mode, exc)
+            return ""
+
+
+def build_renderer(
+    spritesheet: str | Path,
+    *,
+    configured_mode: str | None = None,
+    scale: float = DEFAULT_SCALE,
+    unicode_cols: int = 20,
+    stream=None,
+) -> PetRenderer:
+    """Convenience factory: resolve the mode from config+env, then construct."""
+    mode = resolve_mode(configured_mode, stream=stream)
+    return PetRenderer(
+        spritesheet,
+        mode=mode,
+        scale=scale,
+        unicode_cols=unicode_cols,
+    )

agent/pet/state.py

@@ -0,0 +1,81 @@
+"""Map agent activity → a :class:`PetState`.
+
+This is the one place the "what is the agent doing right now?" → "which
+animation row?" decision lives.  Each surface feeds it the signals it already
+tracks:
+
+- CLI    — ``KawaiiSpinner`` waiting/thinking state + tool outcomes.
+- TUI    — gateway ``tool.start/complete`` + ``message.delta/complete`` events.
+- Desktop — the ``$busy``/``$awaitingResponse``/tool-event nanostores
+            (re-implemented in TS, but mirroring this priority order).
+
+Keeping the priority order here (and documenting it) lets the TypeScript
+mirror stay faithful without a second design.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from agent.pet.constants import PetState
+
+
+def todos_all_done(todos: Iterable[Any] | None) -> bool:
+    """True iff there's ≥1 todo and every one is completed/cancelled.
+
+    The "celebrate" beat (``JUMP``) fires when a plan finishes; this mirrors
+    the TUI's ``isTodoDone`` so the trigger is defined once across surfaces.
+    Accepts dicts (``{"status": ...}``) or objects with a ``status`` attr.
+    """
+    items = list(todos or [])
+    if not items:
+        return False
+
+    def _status(t: Any) -> Any:
+        return t.get("status") if isinstance(t, dict) else getattr(t, "status", None)
+
+    return all(_status(t) in ("completed", "cancelled") for t in items)
+
+
+def derive_pet_state(
+    *,
+    busy: bool = False,
+    awaiting_input: bool = False,
+    error: bool = False,
+    celebrate: bool = False,
+    just_completed: bool = False,
+    tool_running: bool = False,
+    reasoning: bool = False,
+) -> PetState:
+    """Resolve the animation state from coarse activity signals.
+
+    Priority (highest first) — only one row can show at a time, so the most
+    salient signal wins:
+
+    1. ``error``          → ``FAILED``  (a tool/turn just failed)
+    2. ``celebrate``      → ``JUMP``    (explicit success beat, e.g. todos done)
+    3. ``just_completed`` → ``WAVE``    (turn finished cleanly / greeting)
+    4. ``awaiting_input`` → ``WAITING`` (blocked on the user — a clarify/approval
+       prompt is open; this outranks the in-flight signals below because the turn
+       is paused on *you*, even though a tool is technically mid-call)
+    5. ``tool_running``   → ``RUN``     (a tool is executing)
+    6. ``reasoning``      → ``REVIEW``  (model is thinking / reading)
+    7. ``busy``           → ``RUN``     (turn in flight, unspecified work)
+    8. otherwise          → ``IDLE``
+    """
+    if error:
+        return PetState.FAILED
+    if celebrate:
+        return PetState.JUMP
+    if just_completed:
+        return PetState.WAVE
+    if awaiting_input:
+        return PetState.WAITING
+    if tool_running:
+        return PetState.RUN
+    if reasoning:
+        return PetState.REVIEW
+    if busy:
+        return PetState.RUN
+    return PetState.IDLE

agent/pet/store.py

@@ -0,0 +1,343 @@
+"""On-disk pet store — install / list / resolve pets.
+
+Pets live under ``get_hermes_home()/pets/<slug>/`` so every profile gets its
+own set (we deliberately do **not** reuse petdex's ``~/.codex/pets`` default —
+that's owned by the petdex npm CLI and isn't profile-aware).  Each installed
+pet directory holds:
+
+    pets/<slug>/
+        pet.json            # {id, displayName, description, spritesheetPath}
+        spritesheet.webp    # (or .png)
+
+The active pet is resolved from the caller-supplied ``display.pet.slug`` config
+value (falling back to the first installed pet), so this module stays free of
+the config loader.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from hermes_constants import get_hermes_home
+
+logger = logging.getLogger(__name__)
+
+_DOWNLOAD_TIMEOUT = 60.0
+
+
+class PetStoreError(RuntimeError):
+    """Raised on install/IO failures."""
+
+
+@dataclass(frozen=True)
+class InstalledPet:
+    """A pet present on disk."""
+
+    slug: str
+    display_name: str
+    description: str
+    directory: Path
+    spritesheet: Path
+
+    @property
+    def exists(self) -> bool:
+        return self.spritesheet.is_file()
+
+
+def pets_dir() -> Path:
+    """Return the profile-scoped pets directory (created on demand)."""
+    path = get_hermes_home() / "pets"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _read_pet_json(directory: Path) -> dict:
+    pet_json = directory / "pet.json"
+    if not pet_json.is_file():
+        return {}
+    try:
+        return json.loads(pet_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        logger.debug("unreadable pet.json in %s: %s", directory, exc)
+        return {}
+
+
+def _resolve_spritesheet(directory: Path, meta: dict) -> Path:
+    """Find the spritesheet for a pet dir.
+
+    Honors ``spritesheetPath`` from pet.json, else probes the conventional
+    filenames (``spritesheet.{webp,png}`` and petdex R2's ``sprite.webp``).
+    """
+    declared = str(meta.get("spritesheetPath", "") or "").strip()
+    if declared:
+        candidate = directory / declared
+        if candidate.is_file():
+            return candidate
+    for name in ("spritesheet.webp", "spritesheet.png", "sprite.webp", "sprite.png"):
+        candidate = directory / name
+        if candidate.is_file():
+            return candidate
+    # Default expectation even if missing, so callers get a stable path.
+    return directory / "spritesheet.webp"
+
+
+def _safe_slug(slug: str) -> str:
+    """Normalize a slug to a single bare path segment.
+
+    Pet slugs index into ``pets_dir()/<slug>/`` for load/remove, so a value
+    carrying path separators (``../``, absolute paths) could escape the pets
+    directory. Strip every separator and reject ``.``/``..`` so callers can
+    only ever name a direct child of the pets directory.
+    """
+    segment = Path(str(slug).strip()).name
+    if segment in ("", ".", ".."):
+        return ""
+    return segment
+
+
+def load_pet(slug: str) -> InstalledPet | None:
+    """Return the :class:`InstalledPet` for *slug*, or ``None`` if absent."""
+    slug = _safe_slug(slug)
+    if not slug:
+        return None
+    directory = pets_dir() / slug
+    if not directory.is_dir():
+        return None
+    meta = _read_pet_json(directory)
+    return InstalledPet(
+        slug=slug,
+        display_name=str(meta.get("displayName", "") or slug),
+        description=str(meta.get("description", "") or ""),
+        directory=directory,
+        spritesheet=_resolve_spritesheet(directory, meta),
+    )
+
+
+def installed_pets() -> list[InstalledPet]:
+    """Return every installed pet (dirs containing a usable spritesheet)."""
+    out: list[InstalledPet] = []
+    for child in sorted(pets_dir().iterdir()):
+        if not child.is_dir():
+            continue
+        pet = load_pet(child.name)
+        if pet and pet.exists:
+            out.append(pet)
+    return out
+
+
+def resolve_active_pet(configured_slug: str | None = None) -> InstalledPet | None:
+    """Resolve which pet to display.
+
+    Precedence: the configured slug (``display.pet.slug``) if it's installed,
+    otherwise the first installed pet alphabetically, otherwise ``None``.
+    """
+    if configured_slug:
+        pet = load_pet(configured_slug.strip())
+        if pet and pet.exists:
+            return pet
+    pets = installed_pets()
+    return pets[0] if pets else None
+
+
+def install_pet(slug: str, *, force: bool = False, timeout: float = _DOWNLOAD_TIMEOUT) -> InstalledPet:
+    """Download *slug* from the manifest into the pets directory.
+
+    Idempotent: a fully-installed pet is returned as-is unless *force*.  Raises
+    :class:`PetStoreError` / :class:`~agent.pet.manifest.ManifestError` on
+    failure.
+    """
+    from agent.pet.manifest import find_entry
+
+    slug = _safe_slug(slug)
+    if not slug:
+        raise PetStoreError("invalid pet slug")
+    existing = load_pet(slug)
+    if existing and existing.exists and not force:
+        return existing
+
+    entry = find_entry(slug, timeout=timeout)
+    if entry is None:
+        raise PetStoreError(f"pet '{slug}' is not in the petdex manifest")
+
+    # Host-pin every asset URL to petdex. The manifest is trusted (HTTPS from
+    # petdex.dev), but pin the asset hosts too so a compromised/spoofed manifest
+    # can't redirect the download at an arbitrary host. Matches thumbnail_png.
+    if not _is_petdex_host(entry.spritesheet_url):
+        raise PetStoreError(f"refusing non-petdex spritesheet host for '{slug}'")
+
+    directory = pets_dir() / slug
+    directory.mkdir(parents=True, exist_ok=True)
+
+    sprite_ext = ".png" if entry.spritesheet_url.lower().split("?")[0].endswith(".png") else ".webp"
+    sprite_path = directory / f"spritesheet{sprite_ext}"
+
+    _download(entry.spritesheet_url, sprite_path, timeout=timeout)
+
+    # Fetch the upstream pet.json if present; otherwise synthesize a minimal
+    # one so the local layout is self-describing.
+    meta: dict = {}
+    if entry.pet_json_url and _is_petdex_host(entry.pet_json_url):
+        try:
+            meta = _download_json(entry.pet_json_url, timeout=timeout)
+        except Exception as exc:  # noqa: BLE001 - non-fatal, fall back below
+            logger.debug("pet.json fetch failed for %s: %s", slug, exc)
+    if not isinstance(meta, dict) or not meta:
+        meta = {"id": slug, "displayName": entry.display_name, "description": ""}
+    meta["spritesheetPath"] = sprite_path.name
+    meta.setdefault("id", slug)
+    meta.setdefault("displayName", entry.display_name)
+    (directory / "pet.json").write_text(json.dumps(meta, indent=2), encoding="utf-8")
+
+    pet = load_pet(slug)
+    if pet is None or not pet.exists:
+        raise PetStoreError(f"install of '{slug}' did not produce a spritesheet")
+    return pet
+
+
+_THUMB_FRAME_W = 192
+_THUMB_FRAME_H = 208
+_THUMB_W = 96  # rendered ~40px; 2x+ keeps it crisp on HiDPI
+
+
+def _thumbs_dir() -> Path:
+    path = pets_dir() / ".thumbs"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _is_petdex_host(url: str) -> bool:
+    """True only for petdex.dev hosts — bounds server-side fetch (anti-SSRF)."""
+    from urllib.parse import urlparse
+
+    try:
+        host = (urlparse(url).hostname or "").lower()
+    except ValueError:
+        return False
+    return host == "petdex.dev" or host.endswith(".petdex.dev")
+
+
+def thumbnail_png(slug: str, *, source_url: str = "", timeout: float = 30.0) -> bytes | None:
+    """Return a small idle-frame PNG for *slug*, cached on disk.
+
+    Crops the top-left (idle, frame 0) cell of the spritesheet and downsamples
+    it to a thumbnail. Source preference: an installed spritesheet on disk, else
+    *source_url* — but only when it points at petdex (so the gateway never
+    fetches an arbitrary client-supplied URL). Returns ``None`` when there's no
+    usable source or Pillow/network fails; callers render a placeholder.
+
+    Doing this server-side sidesteps the renderer's CSP / R2 hotlink limits that
+    break a direct ``<img src=cdn>`` and lets the result ride the authenticated
+    gateway as a same-origin data URL.
+    """
+    slug = slug.strip()
+    if not slug:
+        return None
+
+    cache = _thumbs_dir() / f"{slug}.png"
+    if cache.is_file():
+        try:
+            return cache.read_bytes()
+        except OSError:
+            pass
+
+    sheet_bytes: bytes | None = None
+    pet = load_pet(slug)
+    if pet and pet.exists:
+        try:
+            sheet_bytes = pet.spritesheet.read_bytes()
+        except OSError:
+            sheet_bytes = None
+
+    if sheet_bytes is None and source_url and _is_petdex_host(source_url):
+        try:
+            import httpx
+
+            resp = httpx.get(
+                source_url,
+                timeout=timeout,
+                follow_redirects=True,
+                headers={"User-Agent": "hermes-agent-petdex"},
+            )
+            resp.raise_for_status()
+            sheet_bytes = resp.content
+        except Exception as exc:  # noqa: BLE001 - cosmetic, degrade to placeholder
+            logger.debug("thumb fetch failed for %s: %s", slug, exc)
+
+    if not sheet_bytes:
+        return None
+
+    try:
+        import io
+
+        from PIL import Image
+
+        with Image.open(io.BytesIO(sheet_bytes)) as im:
+            frame = im.convert("RGBA").crop(
+                (0, 0, min(_THUMB_FRAME_W, im.width), min(_THUMB_FRAME_H, im.height))
+            )
+            height = round(_THUMB_W * _THUMB_FRAME_H / _THUMB_FRAME_W)
+            frame = frame.resize((_THUMB_W, height), Image.NEAREST)
+            buf = io.BytesIO()
+            frame.save(buf, format="PNG")
+            data = buf.getvalue()
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("thumb crop failed for %s: %s", slug, exc)
+        return None
+
+    try:
+        cache.write_bytes(data)
+    except OSError:
+        pass
+    return data
+
+
+def remove_pet(slug: str) -> bool:
+    """Delete an installed pet directory.  Returns True if anything was removed."""
+    import shutil
+
+    slug = _safe_slug(slug)
+    if not slug:
+        return False
+    directory = pets_dir() / slug
+    if not directory.is_dir():
+        return False
+    shutil.rmtree(directory, ignore_errors=True)
+    return not directory.exists()
+
+
+def _download(url: str, dest: Path, *, timeout: float) -> None:
+    import httpx
+
+    try:
+        with httpx.stream(
+            "GET",
+            url,
+            timeout=timeout,
+            follow_redirects=True,
+            headers={"User-Agent": "hermes-agent-petdex"},
+        ) as resp:
+            resp.raise_for_status()
+            tmp = dest.with_suffix(dest.suffix + ".part")
+            with tmp.open("wb") as fh:
+                for chunk in resp.iter_bytes():
+                    fh.write(chunk)
+            tmp.replace(dest)
+    except Exception as exc:  # noqa: BLE001
+        raise PetStoreError(f"download failed for {url}: {exc}") from exc
+
+
+def _download_json(url: str, *, timeout: float) -> dict:
+    import httpx
+
+    resp = httpx.get(
+        url,
+        timeout=timeout,
+        follow_redirects=True,
+        headers={"User-Agent": "hermes-agent-petdex"},
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    return data if isinstance(data, dict) else {}

agent/prompt_builder.py

@@ -709,7 +709,24 @@ PLATFORM_HINTS = {
         "(those are only intercepted on messaging platforms like Telegram, "
         "Discord, Slack, etc.; on the CLI they render as literal text). "
         "When referring to a file you created or changed, just state its "
-        "absolute path in plain text; the user can open it from there."
+        "absolute path in plain text; the user can open it from there. "
+        "Cron jobs scheduled from this session are LOCAL-ONLY: their output is "
+        "saved (viewable via cronjob action='list') but is NOT delivered back "
+        "into this terminal — there is no live-delivery channel here. If the "
+        "user wants to be notified when a job runs, the job's `deliver` must "
+        "target a gateway-connected messaging platform (e.g. deliver='telegram' "
+        "or 'all'). Do not promise the user that a deliver='origin' or "
+        "default-deliver cron job will message them in this session."
+    ),
+    "tui": (
+        "You are running in the Hermes terminal UI (TUI). "
+        "Cron jobs scheduled from this session are LOCAL-ONLY: their output is "
+        "saved (viewable via cronjob action='list') but is NOT delivered back "
+        "into this TUI session — there is no live-delivery channel here. If the "
+        "user wants to be notified when a job runs, the job's `deliver` must "
+        "target a gateway-connected messaging platform (e.g. deliver='telegram' "
+        "or 'all'). Do not promise the user that a deliver='origin' or "
+        "default-deliver cron job will message them in this session."
     ),
     "sms": (
         "You are communicating via SMS. Keep responses concise and use plain text "

agent/tool_executor.py

@@ -69,12 +69,35 @@ def _budget_for_agent(agent) -> BudgetConfig:
 _MAX_TOOL_WORKERS = 8
 
 
+def _flush_session_db_after_tool_progress(
+    agent,
+    messages: list,
+    *,
+    stage: str,
+) -> None:
+    """Best-effort incremental SessionDB flush for tool-call progress.
+
+    Tool execution can perform side effects that terminate or restart the
+    current Hermes process before the normal turn-end persistence path runs.
+    Flush the already-appended assistant/tool messages immediately so the
+    transcript survives destructive-but-valid tool calls.
+    """
+    try:
+        agent._flush_messages_to_session_db(messages)
+    except Exception as exc:
+        logger.warning("Incremental tool-call persistence failed after %s: %s", stage, exc)
+
+
 def _ra():
     """Lazy reference to ``run_agent`` so patches like ``run_agent._set_interrupt`` work."""
     import run_agent
     return run_agent
 
 
+def _is_interpreter_shutdown_submit_error(exc: RuntimeError) -> bool:
+    return "cannot schedule new futures after interpreter shutdown" in str(exc)
+
+
 def _emit_terminal_post_tool_call(
     agent,
     *,
@@ -279,6 +302,11 @@ def execute_tool_calls_concurrent(agent, assistant_message, messages: list, effe
                 f"[Tool execution cancelled — {tc.function.name} was skipped due to user interrupt]",
                 tc.id,
             ))
+            _flush_session_db_after_tool_progress(
+                agent,
+                messages,
+                stage=f"cancelled tool result {tc.function.name}",
+            )
         return
 
     # ── Parse args + pre-execution bookkeeping ───────────────────────
@@ -581,13 +609,40 @@ def execute_tool_calls_concurrent(agent, assistant_message, messages: list, effe
         if runnable_calls:
             max_workers = min(len(runnable_calls), _MAX_TOOL_WORKERS)
             with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
-                for i, tc, name, args in runnable_calls:
+                for submit_index, (i, tc, name, args) in enumerate(runnable_calls):
                     # Propagate the agent turn's ContextVars (e.g.
                     # _approval_session_key) AND thread-local approval/sudo
                     # callbacks into the worker thread; clears callbacks on exit.
-                    f = executor.submit(
-                        propagate_context_to_thread(_run_tool), i, tc, name, args, parsed_calls[i][3]
-                    )
+                    try:
+                        f = executor.submit(
+                            propagate_context_to_thread(_run_tool), i, tc, name, args, parsed_calls[i][3]
+                        )
+                    except RuntimeError as submit_error:
+                        if not _is_interpreter_shutdown_submit_error(submit_error):
+                            raise
+                        skipped_calls = runnable_calls[submit_index:]
+                        logger.warning(
+                            "interpreter shutdown while scheduling concurrent tools; "
+                            "skipping %d unsubmitted tool(s)",
+                            len(skipped_calls),
+                        )
+                        for skipped_i, _tc, skipped_name, skipped_args in skipped_calls:
+                            if results[skipped_i] is None:
+                                middleware_trace = parsed_calls[skipped_i][3]
+                                result = (
+                                    f"Error executing tool '{skipped_name}': "
+                                    "Python interpreter is shutting down; tool was not started"
+                                )
+                                results[skipped_i] = (
+                                    skipped_name,
+                                    skipped_args,
+                                    result,
+                                    0.0,
+                                    True,
+                                    False,
+                                    middleware_trace,
+                                )
+                        break
                     futures.append(f)
 
                 # Wait for all to complete with periodic heartbeats so the
@@ -768,6 +823,11 @@ def execute_tool_calls_concurrent(agent, assistant_message, messages: list, effe
         # String results pass through unchanged.
         _tool_content = agent._tool_result_content_for_active_model(name, function_result)
         messages.append(make_tool_result_message(name, _tool_content, tc.id))
+        _flush_session_db_after_tool_progress(
+            agent,
+            messages,
+            stage=f"tool result {name}",
+        )
 
         # ── Per-tool /steer drain ───────────────────────────────────
         # Same as the sequential path: drain between each collected
@@ -803,13 +863,16 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
                 agent._vprint(f"{agent.log_prefix}⚡ Interrupt: skipping {len(remaining_calls)} tool call(s)", force=True)
             for skipped_tc in remaining_calls:
                 skipped_name = skipped_tc.function.name
-                skip_msg = {
-                    "role": "tool",
-                    "name": skipped_name,
-                    "content": f"[Tool execution cancelled — {skipped_name} was skipped due to user interrupt]",
-                    "tool_call_id": skipped_tc.id,
-                }
-                messages.append(skip_msg)
+                messages.append(make_tool_result_message(
+                    skipped_name,
+                    f"[Tool execution cancelled — {skipped_name} was skipped due to user interrupt]",
+                    skipped_tc.id,
+                ))
+                _flush_session_db_after_tool_progress(
+                    agent,
+                    messages,
+                    stage=f"cancelled tool result {skipped_name}",
+                )
             break
 
         function_name = tool_call.function.name
@@ -1402,6 +1465,11 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
         # (see parallel path for rationale). String results pass through.
         _tool_content = agent._tool_result_content_for_active_model(function_name, function_result)
         messages.append(make_tool_result_message(function_name, _tool_content, tool_call.id))
+        _flush_session_db_after_tool_progress(
+            agent,
+            messages,
+            stage=f"tool result {function_name}",
+        )
 
         # ── Per-tool /steer drain ───────────────────────────────────
         # Drain pending steer BETWEEN individual tool calls so the
@@ -1428,6 +1496,11 @@ def execute_tool_calls_sequential(agent, assistant_message, messages: list, effe
                     f"[Tool execution skipped — {skipped_name} was not started. User sent a new message]",
                     skipped_tc.id,
                 ))
+                _flush_session_db_after_tool_progress(
+                    agent,
+                    messages,
+                    stage=f"skipped tool result {skipped_name}",
+                )
             break
 
         if agent.tool_delay > 0 and i < len(assistant_message.tool_calls):

agent/turn_finalizer.py

@@ -122,10 +122,14 @@ def finalize_turn(
                 )
 
     # Determine if conversation completed successfully
+    normal_text_response = str(_turn_exit_reason).startswith("text_response(")
     completed = (
         final_response is not None
-        and api_call_count < agent.max_iterations
         and not failed
+        and (
+            api_call_count < agent.max_iterations
+            or normal_text_response
+        )
     )
 
     # Post-loop cleanup must never lose the response.  Trajectory save,
@@ -162,6 +166,29 @@ def finalize_turn(
     # same empty-response loop again.
     try:
         agent._drop_trailing_empty_response_scaffolding(messages)
+
+        # When the turn was interrupted and the last message is a tool
+        # result, append a synthetic assistant message to close the
+        # tool-call sequence. Without this, the session persists a
+        # ``tool → user`` alternation that strict providers (Gemini,
+        # Claude) reject, causing them to hallucinate a continuation of
+        # the user's message on the next turn (#48879).
+        #
+        # ``_drop_trailing_empty_response_scaffolding`` only rewinds the
+        # tool tail when an empty-response scaffolding flag is present; a
+        # clean ``/stop`` interrupt after a successful tool sets no such
+        # flag, so the tool result survives as the tail and we close it
+        # here instead. On an interrupt ``final_response`` is typically
+        # empty, so fall back to an explicit placeholder rather than
+        # persisting an empty-content assistant turn.
+        if interrupted and messages and messages[-1].get("role") == "tool":
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": (final_response or "").strip() or "Operation interrupted.",
+                }
+            )
+
         agent._persist_session(messages, conversation_history)
     except Exception as _persist_err:
         _cleanup_errors.append(f"persist_session: {_persist_err}")

apps/desktop/electron/main.cjs

@@ -12,6 +12,7 @@ const {
   powerMonitor,
   protocol,
   safeStorage,
+  screen,
   session,
   shell,
   systemPreferences
@@ -67,6 +68,13 @@ const {
   uninstallArgsForMode
 } = require('./desktop-uninstall.cjs')
 const { isPackagedInstallPath: isPackagedInstallPathUnderRoots } = require('./workspace-cwd.cjs')
+const {
+  MIN_WIDTH: WINDOW_MIN_WIDTH,
+  MIN_HEIGHT: WINDOW_MIN_HEIGHT,
+  sanitizeWindowState,
+  computeWindowOptions,
+  debounce
+} = require('./window-state.cjs')
 const {
   authModeFromStatus,
   buildGatewayWsUrl,
@@ -320,6 +328,7 @@ const BOOTSTRAP_MARKER_SCHEMA_VERSION = 1
 
 const DESKTOP_CONNECTION_CONFIG_PATH = path.join(app.getPath('userData'), 'connection.json')
 const DESKTOP_UPDATE_CONFIG_PATH = path.join(app.getPath('userData'), 'updates.json')
+const DESKTOP_WINDOW_STATE_PATH = path.join(app.getPath('userData'), 'window-state.json')
 // active-profile.json records which Hermes profile the desktop launches its
 // local backend as. When set, startHermes() passes `hermes --profile <name>
 // dashboard …`, which deterministically pins HERMES_HOME (see
@@ -944,6 +953,33 @@ function openExternalUrl(rawUrl) {
   return true
 }
 
+async function openPreviewInBrowser(rawUrl) {
+  const raw = String(rawUrl || '').trim()
+  if (!raw) return false
+
+  let parsed
+  try {
+    parsed = new URL(raw)
+  } catch {
+    return false
+  }
+
+  if (parsed.protocol === 'file:') {
+    let localPath
+    try {
+      localPath = resolveRequestedPathForIpc(parsed.toString(), { purpose: 'Open preview in browser' })
+    } catch {
+      return false
+    }
+
+    await shell.openExternal(pathToFileURL(localPath).toString())
+
+    return true
+  }
+
+  return openExternalUrl(raw)
+}
+
 function ensureWslWindowsFonts() {
   if (!IS_WSL) return
 
@@ -1495,6 +1531,36 @@ function writeDesktopUpdateConfig(config) {
   writeFileAtomic(DESKTOP_UPDATE_CONFIG_PATH, JSON.stringify(config, null, 2))
 }
 
+// ─── Main-window geometry persistence (window-state.json) ──────────────────
+
+function readWindowState() {
+  try {
+    return sanitizeWindowState(JSON.parse(fs.readFileSync(DESKTOP_WINDOW_STATE_PATH, 'utf8')))
+  } catch {
+    return null
+  }
+}
+
+// Persist the window's restored (non-maximized) bounds plus its maximized flag.
+// getNormalBounds() keeps the pre-maximize size, so un-maximizing next session
+// lands back where the user actually sized the window.
+function persistWindowState() {
+  if (!mainWindow || mainWindow.isDestroyed() || mainWindow.isMinimized()) return
+  try {
+    const { x, y, width, height } = mainWindow.getNormalBounds()
+    fs.mkdirSync(path.dirname(DESKTOP_WINDOW_STATE_PATH), { recursive: true })
+    writeFileAtomic(
+      DESKTOP_WINDOW_STATE_PATH,
+      JSON.stringify({ x, y, width, height, isMaximized: mainWindow.isMaximized() }, null, 2)
+    )
+  } catch (err) {
+    rememberLog(`[window-state] persist failed: ${err?.message || err}`)
+  }
+}
+
+// resized/moved fire many times mid-drag on Linux; debounce to one write.
+const schedulePersistWindowState = debounce(persistWindowState, 250)
+
 // Match the backend's source resolution but bias toward a real git checkout.
 // Dev → SOURCE_REPO_ROOT. Packaged/CLI install → ACTIVE_HERMES_ROOT.
 // HERMES_DESKTOP_HERMES_ROOT always wins so devs can pin a worktree.
@@ -5358,13 +5424,149 @@ function createNewSessionWindow() {
   return spawnSecondaryWindow({ newSession: true })
 }
 
+// The pet overlay: a single transparent, frameless, always-on-top window that
+// hosts ONLY the floating mascot. Shift-clicking the in-window pet "pops it out"
+// here so it can leave the app's bounds and stay visible while Hermes is
+// minimized (Codex-style task-completion glance). It carries no gateway
+// connection of its own — the main renderer is the single source of truth and
+// pushes pet state over IPC (hermes:pet-overlay:state); the overlay just renders
+// it. Control flows back (pop-in, composer submit) via hermes:pet-overlay:control.
+let petOverlayWindow = null
+
+function petOverlayUrl() {
+  if (DEV_SERVER) {
+    return `${DEV_SERVER.endsWith('/') ? DEV_SERVER.slice(0, -1) : DEV_SERVER}/?win=overlay#/`
+  }
+
+  return `${pathToFileURL(resolveRendererIndex()).toString()}?win=overlay#/`
+}
+
+function spawnPetOverlayWindow(bounds) {
+  const win = new BrowserWindow({
+    width: Math.max(80, Math.round(bounds?.width || 220)),
+    height: Math.max(80, Math.round(bounds?.height || 220)),
+    x: Number.isFinite(bounds?.x) ? Math.round(bounds.x) : undefined,
+    y: Number.isFinite(bounds?.y) ? Math.round(bounds.y) : undefined,
+    frame: false,
+    transparent: true,
+    resizable: false,
+    movable: true,
+    minimizable: false,
+    maximizable: false,
+    fullscreenable: false,
+    // Windows/Linux need this so the helper window does not get its own
+    // taskbar/alt-tab entry. On macOS, cmd-tab is app-level and this can make
+    // the whole app look like it vanished when the only newly-created visible
+    // window is a frameless overlay. Use NSPanel + Mission Control hiding below
+    // instead, leaving the main Hermes app as the Dock/cmd-tab anchor.
+    skipTaskbar: !IS_MAC,
+    hasShadow: false,
+    alwaysOnTop: true,
+    // macOS panels are non-activating helper windows and can float over full
+    // screen spaces without becoming the app's main switcher window.
+    type: IS_MAC ? 'panel' : undefined,
+    hiddenInMissionControl: IS_MAC,
+    // Non-activating: the overlay must never become the app's key/main window,
+    // or it (a frameless, taskbar-skipping panel) becomes the app's switcher
+    // anchor and the Hermes icon drops out of cmd/alt-tab — especially when the
+    // main window is minimized. We flip this on only while the composer needs
+    // the keyboard (see hermes:pet-overlay:set-focusable).
+    focusable: false,
+    show: false,
+    // Fully transparent — the renderer paints only the sprite + bubble.
+    backgroundColor: '#00000000',
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.cjs'),
+      contextIsolation: true,
+      sandbox: true,
+      nodeIntegration: false,
+      devTools: true,
+      // Keep the sprite animating + bubble updating while the main window is
+      // minimized/blurred — the whole point of the overlay.
+      backgroundThrottling: false
+    }
+  })
+
+  // Float above other apps and follow the user across desktops so the pet is
+  // always reachable. `floating` + `type: panel` is the macOS NSPanel path; the
+  // more aggressive `screen-saver` level can interfere with normal app/window
+  // switching semantics.
+  win.setAlwaysOnTop(true, IS_MAC ? 'floating' : 'screen-saver')
+  win.setHiddenInMissionControl?.(true)
+  try {
+    // Electron docs: macOS may transform process type on each
+    // setVisibleOnAllWorkspaces() call unless skipTransformProcessType=true,
+    // which briefly hides the Dock/cmd-tab presence. Keep Hermes in the normal
+    // ForegroundApplication class so shift-clicking the pet never drops the app
+    // out of app switchers.
+    win.setVisibleOnAllWorkspaces(
+      true,
+      IS_MAC ? { visibleOnFullScreen: true, skipTransformProcessType: true } : undefined
+    )
+  } catch {
+    // Not supported everywhere — best effort.
+  }
+
+  wireCommonWindowHandlers(win)
+
+  win.once('ready-to-show', () => {
+    if (!win.isDestroyed()) win.showInactive()
+  })
+
+  win.on('closed', () => {
+    if (petOverlayWindow === win) {
+      petOverlayWindow = null
+    }
+
+    // If the overlay went away on its own (e.g. ⌘W), tell the main renderer to
+    // pop the pet back in so it doesn't stay hidden. Harmless echo when we're
+    // the ones who closed it (popInPet already cleared the active flag).
+    if (mainWindow && !mainWindow.isDestroyed()) {
+      mainWindow.webContents.send('hermes:pet-overlay:control', { type: 'pop-in' })
+    }
+  })
+
+  win.loadURL(petOverlayUrl())
+
+  return win
+}
+
+function openPetOverlay(bounds) {
+  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
+    if (bounds) {
+      petOverlayWindow.setBounds({
+        x: Math.round(bounds.x),
+        y: Math.round(bounds.y),
+        width: Math.max(80, Math.round(bounds.width)),
+        height: Math.max(80, Math.round(bounds.height))
+      })
+    }
+
+    petOverlayWindow.showInactive()
+
+    return petOverlayWindow
+  }
+
+  petOverlayWindow = spawnPetOverlayWindow(bounds)
+
+  return petOverlayWindow
+}
+
+function closePetOverlay() {
+  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
+    petOverlayWindow.close()
+  }
+
+  petOverlayWindow = null
+}
+
 function createWindow() {
   const icon = getAppIconPath()
+  const savedWindowState = readWindowState()
   mainWindow = new BrowserWindow({
-    width: 1220,
-    height: 800,
-    minWidth: 400,
-    minHeight: 620,
+    ...computeWindowOptions(savedWindowState, screen.getAllDisplays()),
+    minWidth: WINDOW_MIN_WIDTH,
+    minHeight: WINDOW_MIN_HEIGHT,
     title: 'Hermes',
     // Frameless title bar on every platform so the renderer can paint the
     // "hide sidebar" button (and other left-side titlebar tools) flush with
@@ -5406,6 +5608,8 @@ function createWindow() {
     }
   }
 
+  if (savedWindowState?.isMaximized) mainWindow.maximize()
+
   mainWindow.once('ready-to-show', () => {
     if (mainWindow && !mainWindow.isDestroyed()) mainWindow.show()
   })
@@ -5415,6 +5619,19 @@ function createWindow() {
   mainWindow.on('will-leave-full-screen', () => sendWindowStateChanged(false))
   mainWindow.on('leave-full-screen', () => sendWindowStateChanged(false))
 
+  // Reopen where the user left off. resized/moved settle once per drag; close is
+  // the cross-platform backstop, flushed synchronously before the window is gone.
+  mainWindow.on('resized', schedulePersistWindowState)
+  mainWindow.on('moved', schedulePersistWindowState)
+  mainWindow.on('maximize', schedulePersistWindowState)
+  mainWindow.on('unmaximize', schedulePersistWindowState)
+  mainWindow.on('close', () => schedulePersistWindowState.flush())
+
+  // The overlay rides the main window — closing the app's primary window must
+  // tear it down too (otherwise it strands as an orphan that blocks
+  // window-all-closed from quitting on Windows/Linux).
+  mainWindow.on('closed', () => closePetOverlay())
+
   wireCommonWindowHandlers(mainWindow)
 
   mainWindow.webContents.on('render-process-gone', (_event, details) => {
@@ -5535,6 +5752,116 @@ ipcMain.handle('hermes:window:openNewSession', async () => {
 
   return { ok: true }
 })
+
+// --- Pet overlay (pop-out mascot) -----------------------------------------
+// `request` is `{ bounds, screen }`. A fresh pop-out passes viewport-space
+// bounds (screen=false): convert to screen space by adding the main window's
+// content origin so the pet lands where it sat in-window. A remembered/dragged
+// spot passes screen-space bounds (screen=true) and is used as-is. We return the
+// resolved screen bounds so the renderer can persist exactly where it opened.
+ipcMain.handle('hermes:pet-overlay:open', async (_event, request) => {
+  const bounds = request && request.bounds ? request.bounds : request
+  const isScreen = Boolean(request && request.screen)
+  let screenBounds = bounds
+
+  try {
+    if (bounds && !isScreen && mainWindow && !mainWindow.isDestroyed()) {
+      const content = mainWindow.getContentBounds()
+      screenBounds = {
+        x: content.x + (bounds.x || 0),
+        y: content.y + (bounds.y || 0),
+        width: bounds.width,
+        height: bounds.height
+      }
+    }
+  } catch {
+    // Fall back to raw bounds if the window geometry is unavailable.
+  }
+
+  openPetOverlay(screenBounds)
+
+  return { ok: true, bounds: screenBounds }
+})
+ipcMain.handle('hermes:pet-overlay:close', async () => {
+  closePetOverlay()
+
+  return { ok: true }
+})
+// Drag: the overlay reports a new absolute screen position (it already knows the
+// pointer's screen coords), we just move the window.
+ipcMain.on('hermes:pet-overlay:set-bounds', (_event, bounds) => {
+  if (!petOverlayWindow || petOverlayWindow.isDestroyed() || !bounds) {
+    return
+  }
+
+  petOverlayWindow.setBounds({
+    x: Math.round(bounds.x),
+    y: Math.round(bounds.y),
+    width: Math.max(80, Math.round(bounds.width)),
+    height: Math.max(80, Math.round(bounds.height))
+  })
+})
+// Click-through: the overlay window is a full rectangle but only the pet pixels
+// should be interactive. The renderer toggles this as the cursor enters/leaves
+// the sprite so transparent margins pass clicks to whatever is behind.
+ipcMain.on('hermes:pet-overlay:ignore-mouse', (_event, ignore) => {
+  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
+    petOverlayWindow.setIgnoreMouseEvents(Boolean(ignore), { forward: true })
+  }
+})
+// The overlay is a non-activating panel (focusable:false) so it never steals
+// the app's cmd/alt-tab anchor from the main window. But the pop-up composer
+// needs the keyboard, so the renderer asks us to flip it focusable + focus it
+// while the composer is open, then back to non-activating when it closes.
+ipcMain.on('hermes:pet-overlay:set-focusable', (_event, focusable) => {
+  if (!petOverlayWindow || petOverlayWindow.isDestroyed()) {
+    return
+  }
+
+  petOverlayWindow.setFocusable(Boolean(focusable))
+  if (focusable) {
+    petOverlayWindow.focus()
+  }
+})
+// Main renderer → overlay: forward the latest pet state for the overlay to render.
+ipcMain.on('hermes:pet-overlay:state', (_event, payload) => {
+  if (petOverlayWindow && !petOverlayWindow.isDestroyed()) {
+    petOverlayWindow.webContents.send('hermes:pet-overlay:state', payload)
+  }
+})
+// Overlay → main renderer: control messages (pop back in, composer submit).
+ipcMain.on('hermes:pet-overlay:control', (_event, payload) => {
+  if (!mainWindow || mainWindow.isDestroyed()) {
+    return
+  }
+
+  // Double-click toggles the app window: hide it away if it's up front, bring it
+  // back if it's minimized/buried. Pure window control — nothing for the
+  // renderer to do, so don't forward it.
+  if (payload && payload.type === 'toggle-app') {
+    if (mainWindow.isMinimized() || !mainWindow.isVisible()) {
+      mainWindow.show()
+      mainWindow.focus()
+    } else {
+      mainWindow.minimize()
+    }
+
+    return
+  }
+
+  // The mail icon means "take me to the app": raise the main window (it may be
+  // minimized or buried) before the renderer navigates to the latest thread.
+  if (payload && payload.type === 'open-app') {
+    if (mainWindow.isMinimized()) {
+      mainWindow.restore()
+    }
+
+    mainWindow.show()
+    mainWindow.focus()
+  }
+
+  mainWindow.webContents.send('hermes:pet-overlay:control', payload)
+})
 ipcMain.handle('hermes:bootstrap:reset', async () => {
   // Renderer's "Reload and retry" path. Clear the latched failure and
   // reset connection state so the next startHermes() call restarts the
@@ -5998,6 +6325,12 @@ ipcMain.handle('hermes:openExternal', (_event, url) => {
   }
 })
 
+ipcMain.handle('hermes:openPreviewInBrowser', async (_event, url) => {
+  if (!(await openPreviewInBrowser(url))) {
+    throw new Error('Invalid preview URL')
+  }
+})
+
 // User-configurable default project directory. The renderer reads this on
 // settings mount and seeds the value into the picker; writing back persists
 // it via writeDefaultProjectDir so resolveHermesCwd picks it up on the next
@@ -6739,6 +7072,10 @@ function configureSpellChecker() {
 }
 
 app.on('before-quit', () => {
+  // The always-on-top overlay isn't a "real" app window; close it so a stray
+  // pet can't keep the process alive or float over a quit app.
+  closePetOverlay()
+
   // Quitting mid-install should stop the installer, not orphan it.
   if (bootstrapAbortController) {
     try {

apps/desktop/electron/preload.cjs

@@ -7,6 +7,32 @@ contextBridge.exposeInMainWorld('hermesDesktop', {
   getGatewayWsUrl: profile => ipcRenderer.invoke('hermes:gateway:ws-url', profile),
   openSessionWindow: (sessionId, opts) => ipcRenderer.invoke('hermes:window:openSession', sessionId, opts),
   openNewSessionWindow: () => ipcRenderer.invoke('hermes:window:openNewSession'),
+  petOverlay: {
+    // Main renderer → main process: window lifecycle + drag. `request` is
+    // `{ bounds, screen }`; resolves with the screen bounds it actually used.
+    open: request => ipcRenderer.invoke('hermes:pet-overlay:open', request),
+    close: () => ipcRenderer.invoke('hermes:pet-overlay:close'),
+    setBounds: bounds => ipcRenderer.send('hermes:pet-overlay:set-bounds', bounds),
+    setIgnoreMouse: ignore => ipcRenderer.send('hermes:pet-overlay:ignore-mouse', ignore),
+    // Flip the overlay focusable (and focus it) while the composer needs keys.
+    setFocusable: focusable => ipcRenderer.send('hermes:pet-overlay:set-focusable', focusable),
+    // Main renderer → overlay (forwarded by main): push the latest pet state.
+    pushState: payload => ipcRenderer.send('hermes:pet-overlay:state', payload),
+    // Overlay → main renderer (forwarded by main): pop back in / composer submit.
+    control: payload => ipcRenderer.send('hermes:pet-overlay:control', payload),
+    // Overlay subscribes to state pushes.
+    onState: callback => {
+      const listener = (_event, payload) => callback(payload)
+      ipcRenderer.on('hermes:pet-overlay:state', listener)
+      return () => ipcRenderer.removeListener('hermes:pet-overlay:state', listener)
+    },
+    // Main renderer subscribes to overlay control messages.
+    onControl: callback => {
+      const listener = (_event, payload) => callback(payload)
+      ipcRenderer.on('hermes:pet-overlay:control', listener)
+      return () => ipcRenderer.removeListener('hermes:pet-overlay:control', listener)
+    }
+  },
   getBootProgress: () => ipcRenderer.invoke('hermes:boot-progress:get'),
   getConnectionConfig: profile => ipcRenderer.invoke('hermes:connection-config:get', profile),
   saveConnectionConfig: payload => ipcRenderer.invoke('hermes:connection-config:save', payload),
@@ -44,6 +70,7 @@ contextBridge.exposeInMainWorld('hermesDesktop', {
   setTranslucency: payload => ipcRenderer.send('hermes:translucency', payload),
   setPreviewShortcutActive: active => ipcRenderer.send('hermes:previewShortcutActive', Boolean(active)),
   openExternal: url => ipcRenderer.invoke('hermes:openExternal', url),
+  openPreviewInBrowser: url => ipcRenderer.invoke('hermes:openPreviewInBrowser', url),
   fetchLinkTitle: url => ipcRenderer.invoke('hermes:fetchLinkTitle', url),
   sanitizeWorkspaceCwd: cwd => ipcRenderer.invoke('hermes:workspace:sanitize', cwd),
   settings: {

apps/desktop/electron/window-state.cjs

@@ -0,0 +1,117 @@
+/**
+ * Pure geometry helpers for window-state.json — restoring the main window's
+ * size, position, and maximized flag across launches. Side-effect-free so the
+ * part that actually matters (rejecting garbage + off-screen bounds) is
+ * unit-testable without booting Electron; main.cjs owns the file I/O and the
+ * live `screen` displays.
+ */
+
+// Defaults mirror the historical hardcoded BrowserWindow size; MIN_* mirror its
+// minWidth/minHeight so a restored size never undershoots what the live window
+// allows. A fresh install (no saved state) is byte-identical to before.
+const DEFAULT_WIDTH = 1220
+const DEFAULT_HEIGHT = 800
+const MIN_WIDTH = 400
+const MIN_HEIGHT = 620
+
+// Keep at least this much of the window over a display work area before we trust
+// a saved position, so the title bar stays grabbable after a monitor unplugs.
+const MIN_VISIBLE = 48
+
+const finite = v => typeof v === 'number' && Number.isFinite(v)
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(v, hi))
+
+// Parse raw JSON → clean state, or null if garbage. width/height are required
+// and floored; x/y survive only as a finite pair; isMaximized is strict.
+function sanitizeWindowState(raw) {
+  if (!raw || typeof raw !== 'object' || !finite(raw.width) || !finite(raw.height)) return null
+
+  const state = {
+    width: Math.max(MIN_WIDTH, Math.round(raw.width)),
+    height: Math.max(MIN_HEIGHT, Math.round(raw.height)),
+    isMaximized: raw.isMaximized === true
+  }
+  if (finite(raw.x) && finite(raw.y)) {
+    state.x = Math.round(raw.x)
+    state.y = Math.round(raw.y)
+  }
+  return state
+}
+
+// True when `bounds` overlaps some display's work area by ≥ MIN_VISIBLE on both
+// axes. `displays` is Electron's screen.getAllDisplays() shape.
+function onScreen(bounds, displays) {
+  if (!Array.isArray(displays)) return false
+  return displays.some(({ workArea: a } = {}) => {
+    if (!a) return false
+    const x = Math.min(bounds.x + bounds.width, a.x + a.width) - Math.max(bounds.x, a.x)
+    const y = Math.min(bounds.y + bounds.height, a.y + a.height) - Math.max(bounds.y, a.y)
+    return x >= MIN_VISIBLE && y >= MIN_VISIBLE
+  })
+}
+
+// Sanitized state (or null) → BrowserWindow size/position options. Always sets
+// width/height, capped to the largest current display so a size saved on a
+// since-disconnected bigger monitor can't exceed any screen the user now has.
+// Sets x/y only when still on-screen; otherwise Electron centers the window.
+function computeWindowOptions(state, displays) {
+  const opts = {
+    width: finite(state?.width) ? state.width : DEFAULT_WIDTH,
+    height: finite(state?.height) ? state.height : DEFAULT_HEIGHT
+  }
+
+  const cap = (Array.isArray(displays) ? displays : []).reduce(
+    (m, { workArea: a } = {}) =>
+      a && finite(a.width) && finite(a.height)
+        ? { width: Math.max(m.width, a.width), height: Math.max(m.height, a.height) }
+        : m,
+    { width: 0, height: 0 }
+  )
+  if (cap.width && cap.height) {
+    opts.width = clamp(opts.width, MIN_WIDTH, cap.width)
+    opts.height = clamp(opts.height, MIN_HEIGHT, cap.height)
+  }
+
+  if (
+    state &&
+    finite(state.x) &&
+    finite(state.y) &&
+    onScreen({ x: state.x, y: state.y, width: opts.width, height: opts.height }, displays)
+  ) {
+    opts.x = state.x
+    opts.y = state.y
+  }
+  return opts
+}
+
+// Trailing debounce: collapse a burst of resize/move events (Linux fires many
+// mid-drag) into a single run `delayMs` after the last. `.flush()` runs now and
+// cancels the pending timer — used on close, before the window is gone.
+function debounce(fn, delayMs) {
+  let timer = null
+  const debounced = () => {
+    clearTimeout(timer)
+    timer = setTimeout(() => {
+      timer = null
+      fn()
+    }, delayMs)
+  }
+  debounced.flush = () => {
+    clearTimeout(timer)
+    timer = null
+    fn()
+  }
+  return debounced
+}
+
+module.exports = {
+  DEFAULT_WIDTH,
+  DEFAULT_HEIGHT,
+  MIN_WIDTH,
+  MIN_HEIGHT,
+  MIN_VISIBLE,
+  sanitizeWindowState,
+  onScreen,
+  computeWindowOptions,
+  debounce
+}

apps/desktop/electron/window-state.test.cjs

@@ -0,0 +1,135 @@
+/**
+ * Unit tests for the pure window-state geometry helpers. These cover the logic
+ * that protects the user: garbage rejection, off-screen fallback, oversized
+ * clamping, and the debounce that collapses mid-drag write storms.
+ */
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+
+const {
+  DEFAULT_WIDTH,
+  DEFAULT_HEIGHT,
+  MIN_WIDTH,
+  MIN_HEIGHT,
+  sanitizeWindowState,
+  onScreen,
+  computeWindowOptions,
+  debounce
+} = require('./window-state.cjs')
+
+// A single 1920×1080 monitor (work area trimmed for the taskbar).
+const PRIMARY = [{ workArea: { x: 0, y: 0, width: 1920, height: 1040 } }]
+// A laptop panel left behind after a bigger external monitor is unplugged.
+const LAPTOP = [{ workArea: { x: 0, y: 0, width: 1366, height: 728 } }]
+
+// ─── sanitizeWindowState ───────────────────────────────────────────────────
+
+test('sanitizeWindowState rejects missing/garbage input', () => {
+  for (const bad of [null, undefined, 'nope', 42, {}, { width: 'x', height: 800 }, { width: NaN, height: 800 }, { width: 1000 }]) {
+    assert.equal(sanitizeWindowState(bad), null)
+  }
+})
+
+test('sanitizeWindowState keeps a valid full state and rounds HiDPI fractions', () => {
+  assert.deepEqual(sanitizeWindowState({ x: 100.6, y: 50.2, width: 1400.4, height: 900.7, isMaximized: true }), {
+    x: 101,
+    y: 50,
+    width: 1400,
+    height: 901,
+    isMaximized: true
+  })
+})
+
+test('sanitizeWindowState floors size to the minimums', () => {
+  const state = sanitizeWindowState({ width: 10, height: 10 })
+  assert.equal(state.width, MIN_WIDTH)
+  assert.equal(state.height, MIN_HEIGHT)
+})
+
+test('sanitizeWindowState drops a partial position but keeps the size', () => {
+  assert.deepEqual(sanitizeWindowState({ x: 100, width: 1400, height: 900 }), {
+    width: 1400,
+    height: 900,
+    isMaximized: false
+  })
+})
+
+test('sanitizeWindowState treats isMaximized strictly', () => {
+  assert.equal(sanitizeWindowState({ width: 1400, height: 900, isMaximized: 'yes' }).isMaximized, false)
+})
+
+// ─── onScreen ──────────────────────────────────────────────────────────────
+
+test('onScreen accepts a window on the primary or a secondary display', () => {
+  const dual = [...PRIMARY, { workArea: { x: 1920, y: 0, width: 2560, height: 1400 } }]
+  assert.equal(onScreen({ x: 100, y: 100, width: 1220, height: 800 }, PRIMARY), true)
+  assert.equal(onScreen({ x: 2200, y: 200, width: 1220, height: 800 }, dual), true)
+})
+
+test('onScreen rejects off-screen, slivers, and bad input', () => {
+  assert.equal(onScreen({ x: 3000, y: 100, width: 1220, height: 800 }, PRIMARY), false) // past right edge
+  assert.equal(onScreen({ x: 100, y: -900, width: 1220, height: 800 }, PRIMARY), false) // above top
+  assert.equal(onScreen({ x: 1910, y: 100, width: 1220, height: 800 }, PRIMARY), false) // ~10px sliver
+  assert.equal(onScreen({ x: 0, y: 0, width: 1220, height: 800 }, []), false)
+  assert.equal(onScreen({ x: 0, y: 0, width: 1220, height: 800 }, null), false)
+})
+
+// ─── computeWindowOptions ──────────────────────────────────────────────────
+
+test('computeWindowOptions falls back to defaults with no saved state', () => {
+  assert.deepEqual(computeWindowOptions(null, PRIMARY), { width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT })
+})
+
+test('computeWindowOptions restores an on-screen position', () => {
+  const saved = sanitizeWindowState({ x: 200, y: 150, width: 1400, height: 900 })
+  assert.deepEqual(computeWindowOptions(saved, PRIMARY), { width: 1400, height: 900, x: 200, y: 150 })
+})
+
+test('computeWindowOptions keeps the size but drops an off-screen position', () => {
+  const saved = sanitizeWindowState({ x: 5000, y: 150, width: 1400, height: 900 })
+  assert.deepEqual(computeWindowOptions(saved, PRIMARY), { width: 1400, height: 900 })
+})
+
+test('computeWindowOptions clamps a size larger than the only display', () => {
+  const saved = sanitizeWindowState({ width: 2560, height: 1440 })
+  assert.deepEqual(computeWindowOptions(saved, LAPTOP), { width: 1366, height: 728 })
+})
+
+test('computeWindowOptions keeps the MIN floor on a sub-minimum display', () => {
+  const tiny = [{ workArea: { x: 0, y: 0, width: 360, height: 480 } }]
+  const saved = sanitizeWindowState({ width: 2000, height: 1500 })
+  assert.deepEqual(computeWindowOptions(saved, tiny), { width: MIN_WIDTH, height: MIN_HEIGHT })
+})
+
+test('computeWindowOptions does not clamp when displays are unknown', () => {
+  const saved = sanitizeWindowState({ width: 2560, height: 1440 })
+  assert.deepEqual(computeWindowOptions(saved, []), { width: 2560, height: 1440 })
+})
+
+// ─── debounce ──────────────────────────────────────────────────────────────
+
+test('debounce coalesces a burst into one trailing run', t => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  let calls = 0
+  const d = debounce(() => { calls += 1 }, 250)
+
+  d(); d(); d()
+  assert.equal(calls, 0)
+  t.mock.timers.tick(249)
+  assert.equal(calls, 0)
+  t.mock.timers.tick(1)
+  assert.equal(calls, 1)
+})
+
+test('debounce.flush runs now and cancels the pending timer', t => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  let calls = 0
+  const d = debounce(() => { calls += 1 }, 250)
+
+  d()
+  d.flush()
+  assert.equal(calls, 1)
+  t.mock.timers.tick(1000)
+  assert.equal(calls, 1)
+})

apps/desktop/package.json

@@ -37,7 +37,7 @@
     "test:desktop:nsis": "node scripts/test-desktop.mjs nsis",
     "test:desktop:existing": "node scripts/test-desktop.mjs existing",
     "test:desktop:fresh": "node scripts/test-desktop.mjs fresh",
-    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-env.test.cjs electron/backend-probes.test.cjs electron/backend-ready.test.cjs electron/bootstrap-runner.test.cjs electron/connection-config.test.cjs electron/dashboard-token.test.cjs electron/gateway-ws-probe.test.cjs electron/oauth-net-request.test.cjs electron/desktop-uninstall.test.cjs electron/session-windows.test.cjs electron/link-title-window.test.cjs electron/workspace-cwd.test.cjs electron/fs-read-dir.test.cjs electron/git-root.test.cjs electron/windows-child-process.test.cjs electron/update-remote.test.cjs electron/update-rebuild.test.cjs electron/update-marker.test.cjs electron/update-relaunch.test.cjs electron/windows-user-env.test.cjs",
+    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-env.test.cjs electron/backend-probes.test.cjs electron/backend-ready.test.cjs electron/bootstrap-runner.test.cjs electron/connection-config.test.cjs electron/dashboard-token.test.cjs electron/gateway-ws-probe.test.cjs electron/oauth-net-request.test.cjs electron/desktop-uninstall.test.cjs electron/session-windows.test.cjs electron/link-title-window.test.cjs electron/workspace-cwd.test.cjs electron/fs-read-dir.test.cjs electron/git-root.test.cjs electron/windows-child-process.test.cjs electron/update-remote.test.cjs electron/update-rebuild.test.cjs electron/update-marker.test.cjs electron/update-relaunch.test.cjs electron/windows-user-env.test.cjs electron/window-state.test.cjs",
     "typecheck": "tsc -p . --noEmit",
     "lint": "eslint src/ electron/",
     "lint:fix": "eslint src/ electron/ --fix",

apps/desktop/src/app/chat/composer/composer-text-guard.test.tsx

@@ -0,0 +1,106 @@
+// @vitest-environment jsdom
+import { act, cleanup, render } from '@testing-library/react'
+import { useCallback, useRef } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+afterEach(cleanup)
+
+// Regression repro for #49903: on desktop v0.17.0 the composer threw an
+// uncaught `Error: Composer is not available` at startup and the input went
+// unresponsive. The throw comes from @assistant-ui/core's composer-runtime —
+// every *mutator* (setText/send/…) does `if (!core) throw new Error("Composer
+// is not available")` when the thread's composer core isn't bound yet. Unlike
+// the read path (`s.composer.text`, which is null-safe: `runtime?.text ?? ""`),
+// the mutators have no graceful fallback. ChatBar's mount-time effects (draft
+// restore, clearDraft, external inserts) push text via `aui.composer().setText`
+// before the core binds, and the popout refactor (#49488) widened that window,
+// so the throw surfaced as an uncaught error that wedged the input.
+//
+// The fix wraps every `aui.composer().setText` call in a `setComposerText`
+// helper that swallows the unbound-core throw — the contentEditable DOM +
+// draftRef already hold the text and the draft⇄editor sync re-applies it once
+// the core attaches, so nothing is lost. This Harness mirrors that helper
+// faithfully (same try/catch shape) over a fake `aui` whose composer can be
+// toggled bound/unbound, the way the assistant-ui runtime behaves across mount.
+
+interface FakeComposer {
+  setText: (value: string) => void
+}
+
+// Mirror of index.tsx's `useAui()` composer surface: composer() returns a
+// runtime whose setText throws exactly like @assistant-ui/core when unbound.
+function makeFakeAui(bound: { current: boolean }, applied: string[]) {
+  const composer: FakeComposer = {
+    setText(value: string) {
+      if (!bound.current) {
+        throw new Error('Composer is not available')
+      }
+
+      applied.push(value)
+    }
+  }
+
+  return { composer: () => composer }
+}
+
+function Harness({
+  bound,
+  applied,
+  onError
+}: {
+  applied: string[]
+  bound: { current: boolean }
+  onError: (err: unknown) => void
+}) {
+  const aui = useRef(makeFakeAui(bound, applied)).current
+
+  // Verbatim mirror of the production `setComposerText` helper in index.tsx.
+  const setComposerText = useCallback(
+    (value: string) => {
+      try {
+        aui.composer().setText(value)
+      } catch {
+        // Composer core not bound yet — swallow so the input stays usable.
+      }
+    },
+    [aui]
+  )
+
+  // A draft-restore-on-mount that fires while the core may still be unbound,
+  // exactly like loadIntoComposer/clearDraft do on startup.
+  try {
+    setComposerText('restored draft')
+  } catch (err) {
+    onError(err)
+  }
+
+  return null
+}
+
+describe('setComposerText guard (#49903)', () => {
+  it('swallows the unbound-core throw at startup instead of crashing the renderer', () => {
+    const applied: string[] = []
+    const bound = { current: false }
+    const onError = vi.fn()
+
+    expect(() => render(<Harness applied={applied} bound={bound} onError={onError} />)).not.toThrow()
+
+    // The guard absorbed the throw — nothing escaped to the renderer, and no
+    // assistant-ui write landed (core was unbound).
+    expect(onError).not.toHaveBeenCalled()
+    expect(applied).toEqual([])
+  })
+
+  it('writes through to the composer once the core is bound', () => {
+    const applied: string[] = []
+    const bound = { current: true }
+    const onError = vi.fn()
+
+    act(() => {
+      render(<Harness applied={applied} bound={bound} onError={onError} />)
+    })
+
+    expect(onError).not.toHaveBeenCalled()
+    expect(applied).toEqual(['restored draft'])
+  })
+})

apps/desktop/src/app/chat/composer/context-menu.tsx

@@ -13,6 +13,7 @@ import {
   DropdownMenuTrigger
 } from '@/components/ui/dropdown-menu'
 import { Kbd } from '@/components/ui/kbd'
+import { Tip } from '@/components/ui/tooltip'
 import { useI18n } from '@/i18n'
 import { Clipboard, FileText, FolderOpen, type IconComponent, ImageIcon, Link, MessageSquareText } from '@/lib/icons'
 import { cn } from '@/lib/utils'
@@ -42,22 +43,23 @@ export function ContextMenu({
   return (
     <>
       <DropdownMenu>
-        <DropdownMenuTrigger asChild>
-          <Button
-            aria-label={state.tools.label}
-            className={cn(
-              GHOST_ICON_BTN,
-              'data-[state=open]:bg-(--chrome-action-hover) data-[state=open]:text-foreground'
-            )}
-            disabled={!state.tools.enabled}
-            size="icon"
-            title={state.tools.label}
-            type="button"
-            variant="ghost"
-          >
-            <Codicon name="add" size="0.875rem" />
-          </Button>
-        </DropdownMenuTrigger>
+        <Tip label={state.tools.label} side="top">
+          <DropdownMenuTrigger asChild>
+            <Button
+              aria-label={state.tools.label}
+              className={cn(
+                GHOST_ICON_BTN,
+                'data-[state=open]:bg-(--chrome-action-hover) data-[state=open]:text-foreground'
+              )}
+              disabled={!state.tools.enabled}
+              size="icon"
+              type="button"
+              variant="ghost"
+            >
+              <Codicon name="add" size="0.875rem" />
+            </Button>
+          </DropdownMenuTrigger>
+        </Tip>
         <DropdownMenuContent align="start" className={cn('w-60', composerPanelCard)} side="top" sideOffset={6}>
           <DropdownMenuLabel className="px-2 pb-0.5 pt-0.5 text-[0.625rem] font-semibold uppercase tracking-wider text-(--ui-text-tertiary)">
             {c.attachLabel}

apps/desktop/src/app/chat/composer/index.tsx

@@ -60,6 +60,7 @@ import {
   updateQueuedPrompt
 } from '@/store/composer-queue'
 import { $statusItemsBySession } from '@/store/composer-status'
+import { $previewStatusBySession } from '@/store/preview-status'
 import { notify } from '@/store/notifications'
 import { $gatewayState, $messages, setSessionPickerOpen } from '@/store/session'
 import { $threadScrolledUp } from '@/store/thread-scroll'
@@ -192,9 +193,36 @@ export function ChatBar({
 }: ChatBarProps) {
   const aui = useAui()
   const draft = useAuiState(s => s.composer.text)
+
+  // assistant-ui's composer *mutators* (setText/send/…) throw "Composer is not
+  // available" when the thread's composer core isn't bound yet — and unlike the
+  // read path (`s.composer.text`, which is null-safe), there's no graceful
+  // fallback. There's a startup/thread-swap window where this ChatBar's mount
+  // effects (draft restore, clearDraft, external inserts) run before the core
+  // binds; the popout refactor (#49488) widened it by moving the composer out
+  // of the contain wrapper into a sibling of the thread, so the throw began
+  // surfacing as an uncaught error that wedged the desktop input (#49903).
+  //
+  // Guard every mutation: if the core isn't ready, no-op the assistant-ui write.
+  // The contentEditable DOM + draftRef already hold the text, and the
+  // draft⇄editor sync reconciles composer state once the core attaches, so the
+  // draft is never lost — only the (premature) state push is skipped.
+  const setComposerText = useCallback(
+    (value: string) => {
+      try {
+        aui.composer().setText(value)
+      } catch {
+        // Composer core not bound yet — DOM/draftRef carry the text; the sync
+        // effect re-applies it after bind. Swallow so the input stays usable.
+      }
+    },
+    [aui]
+  )
+
   const attachments = useStore($composerAttachments)
   const queuedPromptsBySession = useStore($queuedPromptsBySession)
   const statusItemsBySession = useStore($statusItemsBySession)
+  const previewStatusBySession = useStore($previewStatusBySession)
   const scrolledUp = useStore($threadScrolledUp)
   // Pop-out is a shared, persisted state — but secondary windows (the Ctrl+Shift+N
   // tiny window, subagent watch windows) always start docked and can't pop out:
@@ -217,8 +245,12 @@ export function ChatBar({
 
   const statusStackVisible = useMemo(
     () =>
-      queuedPrompts.length > 0 || (statusSessionId ? (statusItemsBySession[statusSessionId]?.length ?? 0) > 0 : false),
-    [queuedPrompts.length, statusItemsBySession, statusSessionId]
+      queuedPrompts.length > 0 ||
+      (statusSessionId
+        ? (statusItemsBySession[statusSessionId]?.length ?? 0) > 0 ||
+          (previewStatusBySession[statusSessionId]?.length ?? 0) > 0
+        : false),
+    [previewStatusBySession, queuedPrompts.length, statusItemsBySession, statusSessionId]
   )
 
   const composerRef = useRef<HTMLFormElement | null>(null)
@@ -364,7 +396,7 @@ export function ChatBar({
       const next = `${base}${sep}${value}`
 
       draftRef.current = next
-      aui.composer().setText(next)
+      setComposerText(next)
 
       const editor = editorRef.current
 
@@ -375,7 +407,7 @@ export function ChatBar({
 
       setFocusRequestId(id => id + 1)
     },
-    [aui]
+    [setComposerText]
   )
 
   useEffect(() => {
@@ -585,7 +617,7 @@ export function ChatBar({
     const nextDraft = `${currentDraft}${sep}${text}`
 
     draftRef.current = nextDraft
-    aui.composer().setText(nextDraft)
+    setComposerText(nextDraft)
 
     // Push the new text into the contentEditable editor directly. Setting the
     // assistant-ui composer state alone is not enough: the draft→editor sync
@@ -618,7 +650,7 @@ export function ChatBar({
     }
 
     draftRef.current = nextDraft
-    aui.composer().setText(nextDraft)
+    setComposerText(nextDraft)
     requestMainFocus()
 
     return true
@@ -704,7 +736,7 @@ export function ChatBar({
 
     if (nextDraft !== draftRef.current) {
       draftRef.current = nextDraft
-      aui.composer().setText(nextDraft)
+      setComposerText(nextDraft)
     }
 
     window.setTimeout(refreshTrigger, 0)
@@ -830,7 +862,7 @@ export function ChatBar({
       renderComposerContents(editor, prefix)
       placeCaretEnd(editor)
       draftRef.current = composerPlainText(editor)
-      aui.composer().setText(draftRef.current)
+      setComposerText(draftRef.current)
       closeTrigger()
       runAction()
       requestMainFocus()
@@ -858,7 +890,7 @@ export function ChatBar({
 
     const finish = () => {
       draftRef.current = composerPlainText(editor)
-      aui.composer().setText(draftRef.current)
+      setComposerText(draftRef.current)
       requestMainFocus()
       keepTriggerOpen ? window.setTimeout(refreshTrigger, 0) : closeTrigger()
     }
@@ -1310,17 +1342,17 @@ export function ChatBar({
   }
 
   const clearDraft = useCallback(() => {
-    aui.composer().setText('')
+    setComposerText('')
     draftRef.current = ''
 
     if (editorRef.current) {
       editorRef.current.replaceChildren()
     }
-  }, [aui])
+  }, [setComposerText])
 
   const loadIntoComposer = (text: string, attachments: ComposerAttachment[]) => {
     draftRef.current = text
-    aui.composer().setText(text)
+    setComposerText(text)
     $composerAttachments.set(cloneAttachments(attachments))
 
     const editor = editorRef.current
@@ -1693,7 +1725,7 @@ export function ChatBar({
 
       if (domText !== draftRef.current) {
         draftRef.current = domText
-        aui.composer().setText(domText)
+        setComposerText(domText)
       }
     }
 

apps/desktop/src/app/chat/composer/model-pill.tsx

@@ -5,6 +5,7 @@ import { ModelMenuCloseContext } from '@/app/shell/model-menu-panel'
 import { Button } from '@/components/ui/button'
 import { DropdownMenu, DropdownMenuContent, DropdownMenuTrigger } from '@/components/ui/dropdown-menu'
 import { GlyphSpinner } from '@/components/ui/glyph-spinner'
+import { Tip } from '@/components/ui/tooltip'
 import { useI18n } from '@/i18n'
 import { ChevronDown } from '@/lib/icons'
 import { formatModelStatusLabel } from '@/lib/model-status-label'
@@ -74,34 +75,36 @@ export function ModelPill({
 
   if (!model.modelMenuContent) {
     return (
-      <Button
-        aria-label={copy.openModelPicker}
-        className={pillClass}
-        disabled={disabled}
-        onClick={() => setModelPickerOpen(true)}
-        title={copy.openModelPicker}
-        type="button"
-        variant="ghost"
-      >
-        {label}
-      </Button>
-    )
-  }
-
-  return (
-    <DropdownMenu onOpenChange={setOpen} open={open}>
-      <DropdownMenuTrigger asChild>
+      <Tip label={copy.openModelPicker} side="top">
         <Button
-          aria-label={title}
+          aria-label={copy.openModelPicker}
           className={pillClass}
           disabled={disabled}
-          title={title}
+          onClick={() => setModelPickerOpen(true)}
           type="button"
           variant="ghost"
         >
           {label}
         </Button>
-      </DropdownMenuTrigger>
+      </Tip>
+    )
+  }
+
+  return (
+    <DropdownMenu onOpenChange={setOpen} open={open}>
+      <Tip label={title} side="top">
+        <DropdownMenuTrigger asChild>
+          <Button
+            aria-label={title}
+            className={pillClass}
+            disabled={disabled}
+            type="button"
+            variant="ghost"
+          >
+            {label}
+          </Button>
+        </DropdownMenuTrigger>
+      </Tip>
       <DropdownMenuContent align="end" className="w-64 p-0" side="top" sideOffset={8}>
         <ModelMenuCloseContext.Provider value={() => setOpen(false)}>
           {model.modelMenuContent}

apps/desktop/src/app/chat/composer/status-stack/index.tsx

@@ -19,9 +19,11 @@ import {
   type StatusGroup,
   stopBackgroundProcess
 } from '@/store/composer-status'
+import { $previewStatusBySession, dismissPreviewArtifact } from '@/store/preview-status'
 import { $threadScrolledUp } from '@/store/thread-scroll'
 import { openSessionInNewWindow } from '@/store/windows'
 
+import { PreviewStatusRow } from './preview-row'
 import { StatusItemRow } from './status-row'
 
 // Slow safety-net poll for silent exits (processes without notify_on_complete
@@ -52,6 +54,7 @@ export function ComposerStatusStack({ queue, sessionId }: ComposerStatusStackPro
   const { t } = useI18n()
   const navigate = useNavigate()
   const itemsBySession = useStore($statusItemsBySession)
+  const previewsBySession = useStore($previewStatusBySession)
   const scrolledUp = useStore($threadScrolledUp)
 
   const groups = useMemo(
@@ -59,6 +62,8 @@ export function ComposerStatusStack({ queue, sessionId }: ComposerStatusStackPro
     [itemsBySession, sessionId]
   )
 
+  const previews = sessionId ? (previewsBySession[sessionId] ?? []) : []
+
   // Seed from the registry on session open; event-driven refreshes (terminal /
   // process tool completions) live in use-message-stream.
   useEffect(() => {
@@ -122,6 +127,21 @@ export function ComposerStatusStack({ queue, sessionId }: ComposerStatusStackPro
     )
   }))
 
+  if (previews.length > 0 && sessionId) {
+    sections.push({
+      key: 'preview',
+      // Not a collapsible group — preview links just sit there, one line each,
+      // each individually closeable.
+      node: (
+        <div className="px-1 py-0.5">
+          {previews.map(item => (
+            <PreviewStatusRow item={item} key={item.id} onDismiss={id => dismissPreviewArtifact(sessionId, id)} />
+          ))}
+        </div>
+      )
+    })
+  }
+
   if (queue) {
     sections.push({ key: 'queue', node: queue })
   }

apps/desktop/src/app/chat/composer/status-stack/preview-row.tsx

@@ -0,0 +1,125 @@
+import { useStore } from '@nanostores/react'
+import { memo, useState } from 'react'
+
+import { StatusRow } from '@/components/chat/status-row'
+import { Button } from '@/components/ui/button'
+import { Codicon } from '@/components/ui/codicon'
+import { Tip } from '@/components/ui/tooltip'
+import { useI18n } from '@/i18n'
+import { ChevronRight, X } from '@/lib/icons'
+import { normalizeOrLocalPreviewTarget } from '@/lib/local-preview'
+import { cn } from '@/lib/utils'
+import { PREVIEW_PANE_ID } from '@/store/layout'
+import { notifyError } from '@/store/notifications'
+import { $paneOpen } from '@/store/panes'
+import { $previewTarget, dismissPreviewTarget, setCurrentSessionPreviewTarget } from '@/store/preview'
+import { type PreviewArtifact } from '@/store/preview-status'
+
+interface PreviewStatusRowProps {
+  item: PreviewArtifact
+  onDismiss: (id: string) => void
+}
+
+/** One detected artifact, single line, always visible: filename + open + close. */
+export const PreviewStatusRow = memo(function PreviewStatusRow({ item, onDismiss }: PreviewStatusRowProps) {
+  const { t } = useI18n()
+  const activePreview = useStore($previewTarget)
+  const previewPaneOpen = useStore($paneOpen(PREVIEW_PANE_ID))
+  const [opening, setOpening] = useState(false)
+  const isOpen = activePreview?.source === item.target && previewPaneOpen
+
+  const resolveTarget = async () => {
+    const target = await normalizeOrLocalPreviewTarget(item.target, item.cwd || undefined)
+
+    if (!target) {
+      throw new Error(`Could not open preview target: ${item.target}`)
+    }
+
+    return target
+  }
+
+  const togglePreview = async () => {
+    if (opening) {
+      return
+    }
+
+    if (isOpen) {
+      dismissPreviewTarget()
+
+      return
+    }
+
+    setOpening(true)
+
+    try {
+      setCurrentSessionPreviewTarget(await resolveTarget(), 'tool-result', item.target)
+    } catch (error) {
+      notifyError(error, t.preview.unavailable)
+    } finally {
+      setOpening(false)
+    }
+  }
+
+  const openInBrowser = async () => {
+    try {
+      const bridge = window.hermesDesktop?.openPreviewInBrowser
+
+      if (!bridge) {
+        throw new Error('Desktop preview browser bridge is unavailable')
+      }
+
+      await bridge((await resolveTarget()).url)
+    } catch (error) {
+      notifyError(error, t.preview.unavailable)
+    }
+  }
+
+  return (
+    <StatusRow
+      leading={<ChevronRight aria-hidden className="size-3 text-muted-foreground/80" />}
+      onActivate={() => void togglePreview()}
+      trailing={
+        <span className="-my-1 flex items-center gap-0.5">
+          <Tip label={t.preview.openInBrowser}>
+            <Button
+              aria-label={t.preview.openInBrowser}
+              className="size-4 rounded-md text-muted-foreground/60 hover:text-foreground/90"
+              onClick={event => {
+                event.stopPropagation()
+                void openInBrowser()
+              }}
+              size="icon-xs"
+              type="button"
+              variant="ghost"
+            >
+              <Codicon name="link-external" size="0.75rem" />
+            </Button>
+          </Tip>
+          <Tip label={t.statusStack.dismiss}>
+            <Button
+              aria-label={t.statusStack.dismiss}
+              className="size-4 rounded-md text-muted-foreground/60 hover:text-foreground/90"
+              onClick={event => {
+                event.stopPropagation()
+                onDismiss(item.id)
+              }}
+              size="icon-xs"
+              type="button"
+              variant="ghost"
+            >
+              <X size={12} />
+            </Button>
+          </Tip>
+        </span>
+      }
+      trailingVisible
+    >
+      <span className="min-w-0 max-w-[18rem] truncate text-[0.73rem] leading-4 text-foreground/92" title={item.target}>
+        {item.label}
+      </span>
+      <span className={cn('shrink-0 text-[0.62rem] leading-4 text-muted-foreground/70', opening && 'animate-pulse')}>
+        {opening ? t.preview.opening : isOpen ? t.preview.hide : t.preview.openPreview}
+      </span>
+    </StatusRow>
+  )
+})

apps/desktop/src/app/command-palette/index.tsx

@@ -29,6 +29,7 @@ import {
   Moon,
   Package,
   Palette,
+  PawPrint,
   Plus,
   RefreshCw,
   Settings,
@@ -40,7 +41,7 @@ import {
   Zap
 } from '@/lib/icons'
 import { cn } from '@/lib/utils'
-import { $commandPaletteOpen, closeCommandPalette, setCommandPaletteOpen } from '@/store/command-palette'
+import { $commandPaletteOpen, $commandPalettePage, closeCommandPalette, setCommandPaletteOpen } from '@/store/command-palette'
 import { $bindings } from '@/store/keybinds'
 import { runGatewayRestart } from '@/store/system-actions'
 import { luminance } from '@/themes/color'
@@ -64,6 +65,7 @@ import { fieldCopyForSchemaKey } from '../settings/field-copy'
 import { prettyName } from '../settings/helpers'
 
 import { MarketplaceThemePage } from './marketplace-theme-page'
+import { PetInlineToggle, PetPalettePage } from './pet-palette-page'
 
 interface PaletteItem {
   /** Keybind action id — its live combo renders as a hotkey hint. */
@@ -207,6 +209,7 @@ function themeSupportsMode(name: string, target: 'light' | 'dark'): boolean {
 export function CommandPalette() {
   const { t } = useI18n()
   const open = useStore($commandPaletteOpen)
+  const pendingPage = useStore($commandPalettePage)
   const bindings = useStore($bindings)
   const navigate = useNavigate()
   const { availableThemes, resolvedMode, setMode, setTheme, themeName } = useTheme()
@@ -252,6 +255,14 @@ export function CommandPalette() {
     }
   }, [open])
 
+  // Deep-link into a nested page (e.g. `/pet list` → pets picker).
+  useEffect(() => {
+    if (open && pendingPage) {
+      setPage(pendingPage)
+      $commandPalettePage.set(null)
+    }
+  }, [open, pendingPage])
+
   const go = useCallback((path: string) => () => navigate(path), [navigate])
 
   // Step up one nested page (or back to the root list), clearing the filter so
@@ -391,6 +402,13 @@ export function CommandPalette() {
             keywords: ['appearance', 'color mode', 'brightness', 'dark', 'light', 'system'],
             label: cc.changeColorMode,
             to: 'color-mode'
+          },
+          {
+            icon: PawPrint,
+            id: 'appearance-pets',
+            keywords: ['pet', 'petdex', 'mascot', 'pets', '/pet', 'paw'],
+            label: cc.pets.title,
+            to: 'pets'
           }
         ]
       },
@@ -559,6 +577,12 @@ export function CommandPalette() {
           }
         ]
       },
+      // Server-driven page: browse petdex gallery, adopt/switch, toggle off.
+      pets: {
+        title: t.commandCenter.pets.title,
+        placeholder: t.commandCenter.pets.placeholder,
+        groups: []
+      },
       // Server-driven page: items come from the Marketplace, rendered by
       // <MarketplaceThemePage> (loader + live search + per-row install).
       'install-theme': {
@@ -633,45 +657,51 @@ export function CommandPalette() {
               }}
               onValueChange={setSearch}
               placeholder={placeholder}
+              right={page === 'pets' ? <PetInlineToggle /> : undefined}
               value={search}
             />
             <CommandList className="dt-portal-scrollbar max-h-[min(20rem,56vh)]">
-              {page === 'install-theme' ? (
+              {/* Server-driven pages render their own list; the rest show groups. */}
+              {page === 'pets' ? (
+                <PetPalettePage search={search} />
+              ) : page === 'install-theme' ? (
                 <MarketplaceThemePage onPickTheme={setTheme} search={search} />
               ) : (
-                <CommandEmpty>{t.commandCenter.noResults}</CommandEmpty>
-              )}
-              {visibleGroups.map((group, index) => (
-                <CommandGroup
-                  className={HUD_HEADING}
-                  heading={group.heading}
-                  key={group.heading ?? `palette-group-${index}`}
-                >
-                  {group.items.map(item => {
-                    const Icon = item.icon
-                    const combo = item.action ? bindings[item.action]?.[0] : undefined
+                <>
+                  <CommandEmpty>{t.commandCenter.noResults}</CommandEmpty>
+                  {visibleGroups.map((group, index) => (
+                    <CommandGroup
+                      className={HUD_HEADING}
+                      heading={group.heading}
+                      key={group.heading ?? `palette-group-${index}`}
+                    >
+                      {group.items.map(item => {
+                        const Icon = item.icon
+                        const combo = item.action ? bindings[item.action]?.[0] : undefined
 
-                    return (
-                      <CommandItem
-                        className={cn(HUD_ITEM, HUD_TEXT)}
-                        key={item.id}
-                        keywords={item.keywords}
-                        onSelect={() => handleSelect(item)}
-                        value={`${item.label} ${item.keywords?.join(' ') ?? ''} ${item.id}`}
-                      >
-                        <Icon className="size-3.5 shrink-0 text-muted-foreground" />
-                        <span className="truncate">{item.label}</span>
-                        {combo && <KbdCombo className="ml-auto opacity-55" combo={combo} size="sm" />}
-                        {item.to && (
-                          <ChevronRight
-                            className={cn('size-3.5 shrink-0 text-muted-foreground/70', !combo && 'ml-auto')}
-                          />
-                        )}
-                      </CommandItem>
-                    )
-                  })}
-                </CommandGroup>
-              ))}
+                        return (
+                          <CommandItem
+                            className={cn(HUD_ITEM, HUD_TEXT)}
+                            key={item.id}
+                            keywords={item.keywords}
+                            onSelect={() => handleSelect(item)}
+                            value={`${item.label} ${item.keywords?.join(' ') ?? ''} ${item.id}`}
+                          >
+                            <Icon className="size-3.5 shrink-0 text-muted-foreground" />
+                            <span className="truncate">{item.label}</span>
+                            {combo && <KbdCombo className="ml-auto opacity-55" combo={combo} size="sm" />}
+                            {item.to && (
+                              <ChevronRight
+                                className={cn('size-3.5 shrink-0 text-muted-foreground/70', !combo && 'ml-auto')}
+                              />
+                            )}
+                          </CommandItem>
+                        )
+                      })}
+                    </CommandGroup>
+                  ))}
+                </>
+              )}
             </CommandList>
           </Command>
         </DialogPrimitive.Content>

apps/desktop/src/app/command-palette/pet-palette-page.tsx

@@ -0,0 +1,185 @@
+/**
+ * Cmd-K "Pets…" page — browse the petdex gallery, adopt/switch, toggle off.
+ *
+ * A thin view over the `pet-gallery` store: it subscribes to the shared atoms
+ * and calls the store's actions. The store owns fetching, caching, the thumb
+ * cache, and optimistic mutations, so reopening this page is instant and a
+ * toggle never re-pulls the network gallery.
+ */
+
+import { useStore } from '@nanostores/react'
+import { useEffect, useMemo } from 'react'
+
+import { HUD_ITEM, HUD_TEXT } from '@/app/floating-hud'
+import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
+import { PetThumb } from '@/components/pet/pet-thumb'
+import { useI18n } from '@/i18n'
+import { triggerHaptic } from '@/lib/haptics'
+import { Check, Loader2, PawPrint } from '@/lib/icons'
+import { cn } from '@/lib/utils'
+import {
+  $petBusy,
+  $petGallery,
+  $petGalleryError,
+  $petGalleryStatus,
+  adoptPet,
+  loadPetGallery,
+  loadPetThumb,
+  rankedGalleryPets,
+  setPetEnabled
+} from '@/store/pet-gallery'
+
+interface PetPalettePageProps {
+  search: string
+}
+
+export function PetPalettePage({ search }: PetPalettePageProps) {
+  const { t } = useI18n()
+  const copy = t.commandCenter.pets
+  const { requestGateway } = useGatewayRequest()
+
+  const gallery = useStore($petGallery)
+  const status = useStore($petGalleryStatus)
+  const error = useStore($petGalleryError)
+  const busy = useStore($petBusy)
+
+  useEffect(() => {
+    void loadPetGallery(requestGateway)
+  }, [requestGateway])
+
+  const enabled = gallery?.enabled ?? false
+  const active = gallery?.active ?? ''
+
+  const shown = useMemo(() => rankedGalleryPets(gallery, search).slice(0, 50), [gallery, search])
+
+  const adopt = (slug: string) => {
+    void adoptPet(requestGateway, slug, copy.adoptFailed).then(ok => ok && triggerHaptic('crisp'))
+  }
+
+  if (status === 'loading' && !gallery) {
+    return <Status icon={<Loader2 className="size-3.5 animate-spin" />} text={copy.loading} />
+  }
+
+  if (status === 'stale') {
+    return <Status text={copy.staleBackend} tone="error" />
+  }
+
+  if (!gallery?.pets.length && error) {
+    return <Status text={error} tone="error" />
+  }
+
+  const mutating = Boolean(busy)
+
+  return (
+    <div role="listbox">
+      {error && <p className="px-2 pb-1 pt-1.5 text-[0.6875rem] text-(--ui-red)">{error}</p>}
+
+      {shown.length === 0 ? (
+        <Status text={copy.empty} />
+      ) : (
+        shown.map(pet => {
+          const isActive = enabled && pet.slug === active
+          const isBusy = busy === pet.slug
+
+          return (
+            <button
+              className={cn(
+                'flex w-full items-center gap-2 rounded-md text-left transition-colors hover:bg-(--chrome-action-hover) disabled:opacity-60',
+                HUD_ITEM,
+                HUD_TEXT,
+                isActive && 'bg-(--chrome-action-hover)/70'
+              )}
+              disabled={mutating && !isBusy}
+              key={pet.slug}
+              onClick={() => adopt(pet.slug)}
+              onMouseDown={event => event.preventDefault()}
+              role="option"
+              type="button"
+            >
+              <PetThumb
+                alt={pet.displayName}
+                load={(slug, url) => loadPetThumb(requestGateway, slug, url)}
+                size={32}
+                slug={pet.slug}
+                url={pet.spritesheetUrl}
+              />
+              <span className="flex min-w-0 flex-col">
+                <span className="truncate font-medium">{pet.displayName}</span>
+                <span className="truncate text-[0.6875rem] text-muted-foreground/80">
+                  {pet.slug}
+                  {pet.installed ? ` · ${copy.installed}` : ''}
+                </span>
+              </span>
+              <span className="ml-auto flex shrink-0 items-center text-[0.6875rem] text-muted-foreground">
+                {isBusy ? (
+                  <Loader2 className="size-3 animate-spin" />
+                ) : isActive ? (
+                  <Check className="size-3.5 text-foreground" />
+                ) : null}
+              </span>
+            </button>
+          )
+        })
+      )}
+    </div>
+  )
+}
+
+/**
+ * Single on/off toggle, rendered inline on the palette's search row (see
+ * `CommandInput`'s `right` slot). The paw lights up when pets are on. Reads the
+ * same shared gallery atoms, so it stays in sync with the list below.
+ */
+export function PetInlineToggle() {
+  const { t } = useI18n()
+  const copy = t.commandCenter.pets
+  const { requestGateway } = useGatewayRequest()
+  const gallery = useStore($petGallery)
+  const busy = useStore($petBusy)
+
+  if (!gallery) {
+    return null
+  }
+
+  const enabled = gallery.enabled
+
+  const toggle = () => {
+    void setPetEnabled(requestGateway, !enabled, {
+      noneAvailable: copy.noneAvailable,
+      fallback: copy.toggleFailed
+    }).then(ok => ok && triggerHaptic('crisp'))
+  }
+
+  return (
+    <button
+      aria-label={enabled ? copy.turnOff : copy.turnOn}
+      aria-pressed={enabled}
+      className={cn(
+        'flex shrink-0 items-center justify-center rounded-md p-1.5 transition-colors disabled:opacity-50',
+        enabled ? 'bg-(--chrome-action-hover) text-foreground' : 'text-muted-foreground hover:bg-(--chrome-action-hover)/60'
+      )}
+      disabled={Boolean(busy)}
+      onClick={toggle}
+      // Don't steal focus from the search input on click.
+      onMouseDown={event => event.preventDefault()}
+      title={enabled ? copy.turnOff : copy.turnOn}
+      type="button"
+    >
+      {busy ? <Loader2 className="size-4 animate-spin" /> : <PawPrint className="size-4" />}
+    </button>
+  )
+}
+
+function Status({ icon, text, tone }: { icon?: React.ReactNode; text: string; tone?: 'error' }) {
+  return (
+    <div
+      className={cn(
+        'flex items-center justify-center gap-2 px-2 py-6 text-xs',
+        tone === 'error' ? 'text-(--ui-red)' : 'text-muted-foreground'
+      )}
+    >
+      {icon}
+      {text}
+    </div>
+  )
+}

apps/desktop/src/app/desktop-controller.tsx

@@ -33,6 +33,7 @@ import {
   FILE_BROWSER_MAX_WIDTH,
   FILE_BROWSER_MIN_WIDTH,
   pinSession,
+  PREVIEW_PANE_ID,
   setSidebarOverlayMounted,
   SIDEBAR_DEFAULT_WIDTH,
   SIDEBAR_MAX_WIDTH,
@@ -40,6 +41,8 @@ import {
   unpinSession
 } from '../store/layout'
 import { respondToApprovalAction } from '../store/native-notifications'
+import { setPetActivity } from '../store/pet'
+import { setPetOverlayOpenAppHandler, setPetOverlaySubmitHandler } from '../store/pet-overlay'
 import { $filePreviewTarget, $previewTarget, closeActiveRightRailTab } from '../store/preview'
 import {
   $activeGatewayProfile,
@@ -51,6 +54,7 @@ import {
 } from '../store/profile'
 import {
   $activeSessionId,
+  $attentionSessionIds,
   $currentCwd,
   $freshDraftReady,
   $gatewayState,
@@ -840,6 +844,53 @@ export function DesktopController() {
     updateSessionState
   })
 
+  // The popped-out pet drives two actions back into the app: send a prompt, and
+  // open the most recent thread. Both are registered ONCE through refs that track
+  // the latest callbacks — re-registering on every `submitText`/`resumeSession`
+  // identity change left a brief window where the handler was nulled (cleanup
+  // before re-register), which could drop a submit fired from the overlay (e.g.
+  // creating a session from the new-session screen). The ref form keeps a stable,
+  // always-current handler. Primary window only — it owns the overlay.
+  const submitTextRef = useRef(submitText)
+  submitTextRef.current = submitText
+  const resumeSessionRef = useRef(resumeSession)
+  resumeSessionRef.current = resumeSession
+
+  useEffect(() => {
+    if (isSecondaryWindow()) {
+      return
+    }
+
+    setPetOverlaySubmitHandler(text => void submitTextRef.current(text))
+    // Mail icon: $sessions is ordered most-recent-first; the pet is global (not
+    // per session) so "most recent" is the right target. main.cjs already raised
+    // the window before forwarding this.
+    setPetOverlayOpenAppHandler(() => {
+      const recent = $sessions.get()[0]
+
+      if (recent?.id) {
+        void resumeSessionRef.current(recent.id)
+      }
+    })
+
+    return () => {
+      setPetOverlaySubmitHandler(null)
+      setPetOverlayOpenAppHandler(null)
+    }
+  }, [])
+
+  // Mirror "a session is blocked on the user" (clarify/approval) into the pet's
+  // awaitingInput flag so it shows the `waiting` pose. Lives on $petActivity so
+  // it rides the same atom the pop-out overlay mirrors — no session list needed
+  // there. Every window keeps its own in-window pet in sync.
+  useEffect(() => {
+    const sync = () => setPetActivity({ awaitingInput: $attentionSessionIds.get().length > 0 })
+
+    sync()
+
+    return $attentionSessionIds.listen(sync)
+  }, [])
+
   useGatewayBoot({
     handleGatewayEvent: handleDesktopGatewayEvent,
     onConnectionReady: c => {
@@ -1077,7 +1128,7 @@ export function DesktopController() {
   const previewPane = (
     <Pane
       disabled={!chatOpen || (!previewTarget && !filePreviewTarget)}
-      id="preview"
+      id={PREVIEW_PANE_ID}
       key="preview"
       maxWidth={PREVIEW_RAIL_MAX_WIDTH}
       minWidth={PREVIEW_RAIL_MIN_WIDTH}

apps/desktop/src/app/pet-overlay/overlay-root.tsx

@@ -0,0 +1,38 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+
+import { ErrorBoundary } from '@/components/error-boundary'
+import { ThemeProvider } from '@/themes/context'
+
+import { PetOverlayApp } from './pet-overlay-app'
+
+/**
+ * Boot the pet-overlay window. Loaded by the same bundle as the main app but
+ * via `?win=overlay`, so it shares CSS/atoms while mounting a minimal, transparent
+ * surface (no app shell, no gateway, no I18n — the bubble strings are inline).
+ *
+ * The index.html boot script paints an OPAQUE themed background to avoid a flash
+ * in normal windows; the overlay must be see-through, so we force every host
+ * layer transparent with a late, high-specificity style tag.
+ */
+export function mountPetOverlay(): void {
+  const style = document.createElement('style')
+  style.textContent = 'html,body,#root{background:transparent !important;}'
+  document.head.appendChild(style)
+
+  const root = document.getElementById('root')
+
+  if (!root) {
+    return
+  }
+
+  createRoot(root).render(
+    <StrictMode>
+      <ErrorBoundary label="pet-overlay">
+        <ThemeProvider>
+          <PetOverlayApp />
+        </ThemeProvider>
+      </ErrorBoundary>
+    </StrictMode>
+  )
+}

apps/desktop/src/app/pet-overlay/pet-overlay-app.tsx

@@ -0,0 +1,345 @@
+import { useStore } from '@nanostores/react'
+import { useEffect, useRef, useState } from 'react'
+
+import { PetBubble } from '@/components/pet/pet-bubble'
+import { PetSprite } from '@/components/pet/pet-sprite'
+import { Mail } from '@/lib/icons'
+import { $petActivity, $petInfo, setPetInfo } from '@/store/pet'
+import { setAwaitingResponse, setBusy } from '@/store/session'
+
+/**
+ * The pop-out overlay's only view: a transparent, draggable mascot with a mini
+ * composer.
+ *
+ * This runs in a separate, gateway-less BrowserWindow (`?win=overlay`). It is a
+ * pure puppet — the main renderer pushes the live pet state over IPC and we
+ * mirror it into the same atoms the in-window pet reads, so `PetSprite` /
+ * `PetBubble` render identically with zero extra logic.
+ *
+ * The window is a full rectangle but mostly transparent; we toggle OS-level
+ * mouse click-through so only the sprite (or the open composer) is interactive
+ * and the empty margins pass clicks through to whatever is behind.
+ *
+ * Gestures on the pet: drag to move it anywhere on screen (even outside the
+ * app), shift-click to pop it back into the window, single-click to open a small
+ * composer, double-click to toggle the app window (minimize ↔ restore). A mail
+ * icon (shown only when a turn finished while you were away) raises the app on
+ * the most recent thread.
+ */
+
+// Below this much pointer travel, a press counts as a click, not a drag.
+const CLICK_SLOP_PX = 3
+// A second click within this window is a double-click (raise app) and cancels
+// the deferred single-click (open composer), so a double never flashes it open.
+const DOUBLE_CLICK_MS = 250
+
+interface DragState {
+  startX: number
+  startY: number
+  offX: number
+  offY: number
+  width: number
+  height: number
+  moved: boolean
+}
+
+export function PetOverlayApp() {
+  const info = useStore($petInfo)
+  const [composerOpen, setComposerOpen] = useState(false)
+  const [draft, setDraft] = useState('')
+  // Mirrored from the main renderer: a finish landed while you were away.
+  const [unread, setUnread] = useState(false)
+
+  const dragRef = useRef<DragState | null>(null)
+  const petRef = useRef<HTMLDivElement | null>(null)
+  const inputRef = useRef<HTMLInputElement | null>(null)
+  const ignoreRef = useRef(true)
+  const composerOpenRef = useRef(false)
+  const clickTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+
+  const setIgnore = (ignore: boolean) => {
+    if (ignoreRef.current !== ignore) {
+      ignoreRef.current = ignore
+      window.hermesDesktop?.petOverlay?.setIgnoreMouse(ignore)
+    }
+  }
+
+  // Mirror pushed state into the shared atoms so PetSprite/PetBubble just work.
+  useEffect(() => {
+    const off = window.hermesDesktop?.petOverlay?.onState(payload => {
+      setPetInfo(payload.info)
+      $petActivity.set(payload.activity ?? {})
+      setBusy(Boolean(payload.busy))
+      setAwaitingResponse(Boolean(payload.awaiting))
+      setUnread(Boolean(payload.unread))
+    })
+
+    // Tell the main renderer we're mounted so it pushes the current frame (the
+    // subscribe-time pushes during open() can land before this view exists).
+    window.hermesDesktop?.petOverlay?.control({ type: 'ready' })
+
+    return off
+  }, [])
+
+  // Click-through: make only the sprite (or an open composer) interactive. With
+  // ignore+forward, the renderer still receives mousemove so we can re-enable
+  // hit-testing the moment the cursor returns to the pet.
+  useEffect(() => {
+    setIgnore(true)
+
+    const onMove = (ev: MouseEvent) => {
+      if (dragRef.current || composerOpenRef.current) {
+        setIgnore(false)
+
+        return
+      }
+
+      const el = petRef.current
+
+      if (!el) {
+        return
+      }
+
+      const r = el.getBoundingClientRect()
+      const over = ev.clientX >= r.left && ev.clientX <= r.right && ev.clientY >= r.top && ev.clientY <= r.bottom
+      setIgnore(!over)
+    }
+
+    window.addEventListener('mousemove', onMove)
+
+    return () => {
+      window.removeEventListener('mousemove', onMove)
+      clearTimeout(clickTimerRef.current)
+    }
+  }, [])
+
+  // The whole window must stay interactive while the composer is open (so the
+  // input keeps focus); focus it on open. The overlay is a non-activating panel
+  // (so it never steals the app's cmd/alt-tab anchor) — flip it focusable while
+  // the composer needs the keyboard, then back to non-activating when it closes.
+  useEffect(() => {
+    composerOpenRef.current = composerOpen
+
+    window.hermesDesktop?.petOverlay?.setFocusable(composerOpen)
+
+    if (composerOpen) {
+      setIgnore(false)
+      // The OS window has to become key first (setFocusable + focus happen in
+      // the main process), so focus the input on the next frame.
+      requestAnimationFrame(() => inputRef.current?.focus())
+    }
+  }, [composerOpen])
+
+  const onPetPointerDown = (e: React.PointerEvent) => {
+    if (e.button !== 0) {
+      return
+    }
+
+    ;(e.target as Element).setPointerCapture?.(e.pointerId)
+    dragRef.current = {
+      height: window.outerHeight,
+      moved: false,
+      offX: e.screenX - window.screenX,
+      offY: e.screenY - window.screenY,
+      startX: e.screenX,
+      startY: e.screenY,
+      width: window.outerWidth
+    }
+  }
+
+  const onPetPointerMove = (e: React.PointerEvent) => {
+    const drag = dragRef.current
+
+    if (!drag) {
+      return
+    }
+
+    if (Math.hypot(e.screenX - drag.startX, e.screenY - drag.startY) > CLICK_SLOP_PX) {
+      drag.moved = true
+    }
+
+    window.hermesDesktop?.petOverlay?.setBounds({
+      height: drag.height,
+      width: drag.width,
+      x: e.screenX - drag.offX,
+      y: e.screenY - drag.offY
+    })
+  }
+
+  const onPetPointerUp = (e: React.PointerEvent) => {
+    const drag = dragRef.current
+    dragRef.current = null
+    ;(e.target as Element).releasePointerCapture?.(e.pointerId)
+
+    if (!drag) {
+      return
+    }
+
+    if (drag.moved) {
+      // A drag cancels any deferred single-click so the composer can't pop open
+      // after you reposition the pet.
+      clearTimeout(clickTimerRef.current)
+      clickTimerRef.current = undefined
+
+      // Remember the spot on the desktop (screen coords) so the pet reopens here
+      // next time / after a restart.
+      window.hermesDesktop?.petOverlay?.control({
+        bounds: { height: drag.height, width: drag.width, x: e.screenX - drag.offX, y: e.screenY - drag.offY },
+        type: 'bounds'
+      })
+
+      return
+    }
+
+    // Shift-click always pops the pet back in (no double-click ambiguity).
+    if (e.shiftKey) {
+      window.hermesDesktop?.petOverlay?.control({ type: 'pop-in' })
+
+      return
+    }
+
+    // Double-click toggles the app window (minimize ↔ restore); defer the
+    // single-click composer toggle so a double never flashes the composer open.
+    if (clickTimerRef.current) {
+      clearTimeout(clickTimerRef.current)
+      clickTimerRef.current = undefined
+      window.hermesDesktop?.petOverlay?.control({ type: 'toggle-app' })
+
+      return
+    }
+
+    clickTimerRef.current = setTimeout(() => {
+      clickTimerRef.current = undefined
+      setComposerOpen(open => !open)
+    }, DOUBLE_CLICK_MS)
+  }
+
+  const send = () => {
+    const text = draft.trim()
+
+    if (text) {
+      window.hermesDesktop?.petOverlay?.control({ text, type: 'submit' })
+    }
+
+    setDraft('')
+    setComposerOpen(false)
+  }
+
+  const openApp = () => {
+    // Hide the icon immediately; the main renderer also clears the source flag.
+    setUnread(false)
+    window.hermesDesktop?.petOverlay?.control({ type: 'open-app' })
+  }
+
+  if (!info.enabled || !info.spritesheetBase64) {
+    return null
+  }
+
+  return (
+    <div
+      onPointerDown={e => {
+        // Click on the transparent backdrop (not the pet/composer) dismisses
+        // the composer.
+        if (composerOpen && e.target === e.currentTarget) {
+          setComposerOpen(false)
+        }
+      }}
+      style={{
+        alignItems: 'center',
+        background: 'transparent',
+        display: 'flex',
+        flexDirection: 'column',
+        height: '100vh',
+        justifyContent: 'flex-end',
+        paddingBottom: 24,
+        userSelect: 'none',
+        width: '100vw'
+      }}
+    >
+      {composerOpen && (
+        <input
+          onChange={e => setDraft(e.target.value)}
+          onKeyDown={e => {
+            if (e.key === 'Enter' && !e.shiftKey) {
+              e.preventDefault()
+              send()
+            } else if (e.key === 'Escape') {
+              setComposerOpen(false)
+            }
+          }}
+          placeholder="Message…"
+          ref={inputRef}
+          style={{
+            background: 'var(--ui-bg-elevated)',
+            border: '1px solid var(--ui-stroke-secondary)',
+            borderRadius: 2,
+            boxShadow: '0 6px 18px rgba(0,0,0,0.28)',
+            color: 'var(--foreground)',
+            fontSize: 12,
+            marginBottom: 8,
+            outline: 'none',
+            padding: '4px 8px',
+            width: 184
+          }}
+          value={draft}
+        />
+      )}
+
+      <div
+        onPointerDown={onPetPointerDown}
+        onPointerMove={onPetPointerMove}
+        onPointerUp={onPetPointerUp}
+        ref={petRef}
+        style={{
+          alignItems: 'center',
+          cursor: 'grab',
+          display: 'flex',
+          flexDirection: 'column',
+          position: 'relative',
+          touchAction: 'none'
+        }}
+      >
+        <div style={{ marginBottom: 4 }}>
+          <PetBubble />
+        </div>
+        <div style={{ lineHeight: 0, position: 'relative' }}>
+          <PetSprite info={info} />
+
+          {/* Mail icon: only when a finish landed while you were away. Jumps to
+              the app's most recent thread. Anchored to the sprite (kept inside
+              its box so the overlay's click-through hit-test still catches it);
+              stopPropagation keeps a click from starting a window drag. */}
+          {unread && (
+            <button
+              aria-label="Open in Hermes"
+              onClick={openApp}
+              onPointerDown={e => e.stopPropagation()}
+              onPointerUp={e => e.stopPropagation()}
+              style={{
+                alignItems: 'center',
+                background: 'var(--ui-bg-elevated)',
+                border: '1px solid var(--ui-stroke-secondary)',
+                borderRadius: 999,
+                boxShadow: '0 4px 14px rgba(0,0,0,0.22)',
+                color: 'var(--foreground)',
+                cursor: 'pointer',
+                display: 'inline-flex',
+                height: 24,
+                justifyContent: 'center',
+                padding: 0,
+                position: 'absolute',
+                right: 0,
+                top: 0,
+                width: 24
+              }}
+              title="Open in Hermes"
+              type="button"
+            >
+              <Mail style={{ height: 13, width: 13 }} />
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

apps/desktop/src/app/right-sidebar/index.tsx

@@ -5,6 +5,7 @@ import { ErrorBoundary } from '@/components/error-boundary'
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
 import { Loader } from '@/components/ui/loader'
+import { Tip } from '@/components/ui/tooltip'
 import { useI18n } from '@/i18n'
 import { selectDesktopPaths } from '@/lib/desktop-fs'
 import { normalizeOrLocalPreviewTarget } from '@/lib/local-preview'
@@ -167,38 +168,41 @@ function FilesystemTab({
             <SidebarPanelLabel>{cwdName}</SidebarPanelLabel>
           </button>
         </div>
-        <Button
-          aria-label={r.refreshTree}
-          className={HEADER_ACTION_LABEL_REVEAL}
-          disabled={!hasCwd || loading}
-          onClick={onRefresh}
-          size="icon-xs"
-          title={r.refreshTree}
-          variant="ghost"
-        >
-          <Codicon name="refresh" size="0.8125rem" spinning={loading} />
-        </Button>
-        <Button
-          aria-label={r.openFolder}
-          className={HEADER_ACTION_CLASS}
-          onClick={() => void onChangeFolder()}
-          size="icon-xs"
-          title={r.openFolder}
-          variant="ghost"
-        >
-          <Codicon name="folder-opened" size="0.8125rem" />
-        </Button>
-        <Button
-          aria-label={r.collapseAll}
-          className={cn(HEADER_ACTION_CLASS, !canCollapse && 'pointer-events-none opacity-0')}
-          disabled={!hasCwd || !canCollapse}
-          onClick={onCollapseAll}
-          size="icon-xs"
-          title={r.collapseAll}
-          variant="ghost"
-        >
-          <Codicon name="collapse-all" size="0.8125rem" />
-        </Button>
+        <Tip label={r.refreshTree} side="left">
+          <Button
+            aria-label={r.refreshTree}
+            className={HEADER_ACTION_LABEL_REVEAL}
+            disabled={!hasCwd || loading}
+            onClick={onRefresh}
+            size="icon-xs"
+            variant="ghost"
+          >
+            <Codicon name="refresh" size="0.8125rem" spinning={loading} />
+          </Button>
+        </Tip>
+        <Tip label={r.openFolder} side="left">
+          <Button
+            aria-label={r.openFolder}
+            className={HEADER_ACTION_CLASS}
+            onClick={() => void onChangeFolder()}
+            size="icon-xs"
+            variant="ghost"
+          >
+            <Codicon name="folder-opened" size="0.8125rem" />
+          </Button>
+        </Tip>
+        <Tip label={r.collapseAll} side="left">
+          <Button
+            aria-label={r.collapseAll}
+            className={cn(HEADER_ACTION_CLASS, !canCollapse && 'pointer-events-none opacity-0')}
+            disabled={!hasCwd || !canCollapse}
+            onClick={onCollapseAll}
+            size="icon-xs"
+            variant="ghost"
+          >
+            <Codicon name="collapse-all" size="0.8125rem" />
+          </Button>
+        </Tip>
       </RightSidebarSectionHeader>
       <FileTreeBody
         collapseNonce={collapseNonce}

apps/desktop/src/app/session/hooks/use-message-stream.ts

@@ -34,6 +34,7 @@ import { $gateway } from '@/store/gateway'
 import { dispatchNativeNotification } from '@/store/native-notifications'
 import { notify } from '@/store/notifications'
 import { requestDesktopOnboarding } from '@/store/onboarding'
+import { flashPetActivity, markPetUnread, setPetActivity } from '@/store/pet'
 import { clearAllPrompts, setApprovalRequest, setSecretRequest, setSudoRequest } from '@/store/prompts'
 import {
   setCurrentBranch,
@@ -870,10 +871,18 @@ export function useMessageStream({
         if (sessionId) {
           appendReasoningDelta(sessionId, coerceThinkingText(payload?.text))
         }
+
+        if (isActiveEvent) {
+          setPetActivity({ reasoning: true })
+        }
       } else if (event.type === 'reasoning.available') {
         if (sessionId) {
           appendReasoningDelta(sessionId, coerceThinkingText(payload?.text), true)
         }
+
+        if (isActiveEvent) {
+          setPetActivity({ reasoning: true })
+        }
       } else if (event.type === 'message.complete') {
         if (!sessionId) {
           return
@@ -895,6 +904,20 @@ export function useMessageStream({
 
         if (isActiveEvent) {
           setTurnStartedAt(null)
+
+          // Pet beat: a finished turn always celebrates — go straight to the
+          // jump, never linger on the run/reason pose. One atom update (clears
+          // toolRunning/reasoning AND sets celebrate together) so no stray "run"
+          // frame leaks to the sprite — including the popped-out overlay, which
+          // mirrors each activity change. The jump runs ~2 loops, then settles.
+          flashPetActivity({ celebrate: true, reasoning: false, toolRunning: false }, 2200)
+
+          // Light up the pet's mail icon if the user wasn't looking when the turn
+          // finished — a glanceable "new message" hint on the popped-out overlay.
+          // Cleared when they open the app via the mail icon or refocus the window.
+          if (typeof document !== 'undefined' && !document.hasFocus()) {
+            markPetUnread()
+          }
         }
 
         if (payload?.usage) {
@@ -907,10 +930,19 @@ export function useMessageStream({
 
         flushQueuedDeltas(sessionId)
         upsertToolCall(sessionId, toTodoPayload(payload) ?? payload, 'running', event.type)
+
+        if (isActiveEvent) {
+          setPetActivity({ reasoning: false, toolRunning: true })
+        }
       } else if (event.type === 'tool.complete') {
         if (sessionId) {
           flushQueuedDeltas(sessionId)
           upsertToolCall(sessionId, toTodoPayload(payload) ?? payload, 'complete', event.type)
+
+          if (isActiveEvent) {
+            setPetActivity({ toolRunning: false })
+          }
+
           // A pending clarify blocks the turn, so the first tool.complete after
           // one is the clarify resolving — drop the "needs input" flag here so
           // the sidebar indicator clears as soon as it's answered, not only at
@@ -1120,6 +1152,11 @@ export function useMessageStream({
           compactedTurnRef.current.delete(sessionId)
         }
 
+        if (isActiveEvent) {
+          setPetActivity({ reasoning: false, toolRunning: false })
+          flashPetActivity({ error: true })
+        }
+
         dispatchNativeNotification({
           body: errorMessage,
           kind: 'turnError',

apps/desktop/src/app/session/hooks/use-preview-routing.test.tsx

@@ -120,31 +120,7 @@ describe('usePreviewRouting', () => {
     expect(window.hermesDesktop.normalizePreviewTarget).not.toHaveBeenCalled()
   })
 
-  it('registers structured tool-result preview targets', async () => {
-    render(
-      <PreviewRoutingHarness
-        onEvent={handler => {
-          handleEvent = handler
-        }}
-      />
-    )
-
-    act(() =>
-      handleEvent({
-        payload: { path: './dist/index.html' },
-        session_id: 'session-1',
-        type: 'tool.complete'
-      })
-    )
-
-    await waitFor(() => {
-      expect($previewTarget.get()?.source).toBe('./dist/index.html')
-    })
-
-    expect(window.localStorage.getItem('hermes.desktop.sessionPreviews.v1')).toContain('./dist/index.html')
-  })
-
-  it('registers html previews from edit inline diffs', async () => {
+  it('does not auto-open a preview from tool results', async () => {
     render(
       <PreviewRoutingHarness
         onEvent={handler => {
@@ -160,9 +136,9 @@ describe('usePreviewRouting', () => {
         type: 'tool.complete'
       })
     )
+    act(() => handleEvent({ payload: { path: './dist/index.html' }, session_id: 'session-1', type: 'tool.complete' }))
 
-    await waitFor(() => {
-      expect($previewTarget.get()?.source).toBe('preview-demo.html')
-    })
+    expect($previewTarget.get()).toBeNull()
+    expect(window.localStorage.getItem('hermes.desktop.sessionPreviews.v1')).toBeNull()
   })
 })

apps/desktop/src/app/session/hooks/use-preview-routing.ts

@@ -10,8 +10,7 @@ import {
   getSessionPreviewRecord,
   progressPreviewServerRestart,
   requestPreviewReload,
-  setPreviewTarget,
-  setSessionPreviewTarget
+  setPreviewTarget
 } from '@/store/preview'
 import { $currentCwd } from '@/store/session'
 import type { RpcEvent } from '@/types/hermes'
@@ -40,53 +39,6 @@ function activePreviewSessionId(
   return selectedStoredSessionId || routedSessionId || activeSessionIdRef.current || ''
 }
 
-function looksLikePreviewTarget(value: string): boolean {
-  return /^https?:\/\//i.test(value) || /^file:\/\//i.test(value) || /^(?:\/|\.{1,2}\/|~\/).+/.test(value)
-}
-
-function stripAnsi(value: string): string {
-  return value.replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g'), '')
-}
-
-function htmlPathFromInlineDiff(value: string): string {
-  const cleaned = stripAnsi(value).replace(/^\s*┊\s*review diff\s*\n/i, '')
-
-  for (const match of cleaned.matchAll(/(?:^|\s)(?:[ab]\/)?([^\s]+\.html?)(?=\s|$)/gi)) {
-    const candidate = match[1]?.trim()
-
-    if (candidate) {
-      return candidate
-    }
-  }
-
-  return ''
-}
-
-function structuredPreviewCandidate(payload: unknown): string {
-  const record = asRecord(payload)
-  const fields = ['url', 'target', 'path', 'file', 'filepath', 'preview']
-
-  for (const field of fields) {
-    const value = record[field]
-
-    if (typeof value === 'string') {
-      const target = value.trim()
-
-      if (target && looksLikePreviewTarget(target)) {
-        return target
-      }
-    }
-  }
-
-  const inlineDiff = record.inline_diff
-
-  if (typeof inlineDiff === 'string') {
-    return htmlPathFromInlineDiff(inlineDiff)
-  }
-
-  return ''
-}
-
 export function usePreviewRouting({
   activeSessionIdRef,
   baseHandleGatewayEvent,
@@ -99,6 +51,10 @@ export function usePreviewRouting({
   const previewRegistry = useStore($sessionPreviewRegistry)
   const previewSessionId = activePreviewSessionId(activeSessionIdRef, routedSessionId, selectedStoredSessionId)
 
+  // Restore a *user-opened* preview when its session becomes active. Tool
+  // results no longer auto-register/open a preview — the inline preview card in
+  // the tool row is the only entry point, so HTML artifacts never pop the rail
+  // open on their own.
   useEffect(() => {
     if (currentView !== 'chat' || !previewSessionId) {
       setPreviewTarget(null)
@@ -111,53 +67,6 @@ export function usePreviewRouting({
     setPreviewTarget(record?.normalized ?? null)
   }, [currentView, previewRegistry, previewSessionId])
 
-  const registerStructuredPreview = useCallback(
-    async (event: RpcEvent) => {
-      if (
-        event.session_id &&
-        event.session_id !== activeSessionIdRef.current &&
-        event.session_id !== previewSessionId
-      ) {
-        return
-      }
-
-      if (!event.type.startsWith('tool.')) {
-        return
-      }
-
-      if (!previewSessionId) {
-        return
-      }
-
-      const candidate = structuredPreviewCandidate(event.payload)
-
-      if (!candidate) {
-        return
-      }
-
-      const desktop = window.hermesDesktop
-
-      if (!desktop?.normalizePreviewTarget) {
-        return
-      }
-
-      const sessionId = previewSessionId
-      const cwd = currentCwd || ''
-      const target = await desktop.normalizePreviewTarget(candidate, cwd || undefined).catch(() => null)
-
-      if (
-        !target ||
-        sessionId !== activePreviewSessionId(activeSessionIdRef, routedSessionId, selectedStoredSessionId) ||
-        $currentCwd.get() !== cwd
-      ) {
-        return
-      }
-
-      setSessionPreviewTarget(sessionId, target, 'tool-result', candidate)
-    },
-    [activeSessionIdRef, currentCwd, previewSessionId, routedSessionId, selectedStoredSessionId]
-  )
-
   const restartPreviewServer = useCallback(
     async (url: string, context?: string) => {
       const sessionId = activeSessionIdRef.current
@@ -210,13 +119,14 @@ export function usePreviewRouting({
         return
       }
 
-      void registerStructuredPreview(event)
-
+      // Only refresh an already-open live preview when a file changes; never
+      // open one unprompted. (Preview links are surfaced from the tool row into
+      // the status stack — see tool-fallback.tsx.)
       if ($previewTarget.get()?.kind === 'url' && gatewayEventCompletedFileDiff(event)) {
         requestPreviewReload()
       }
     },
-    [activeSessionIdRef, baseHandleGatewayEvent, registerStructuredPreview]
+    [activeSessionIdRef, baseHandleGatewayEvent]
   )
 
   return { handleDesktopGatewayEvent, restartPreviewServer }

apps/desktop/src/app/session/hooks/use-prompt-actions.ts

@@ -27,6 +27,7 @@ import { triggerHaptic } from '@/lib/haptics'
 import { setMutableRef } from '@/lib/mutable-ref'
 import { isProviderSetupErrorMessage } from '@/lib/provider-setup-errors'
 import { setSessionYolo } from '@/lib/yolo-session'
+import { openCommandPalettePage } from '@/store/command-palette'
 import {
   $composerAttachments,
   clearComposerAttachments,
@@ -37,8 +38,10 @@ import {
   updateComposerAttachment
 } from '@/store/composer'
 import { resetSessionBackground } from '@/store/composer-status'
+import { clearPreviewArtifacts } from '@/store/preview-status'
 import { clearNotifications, notify, notifyError } from '@/store/notifications'
 import { requestDesktopOnboarding } from '@/store/onboarding'
+import { setPetScale } from '@/store/pet-gallery'
 import { $activeGatewayProfile, $newChatProfile, ensureGatewayProfile, normalizeProfileKey } from '@/store/profile'
 import {
   $busy,
@@ -58,8 +61,8 @@ import { clearSessionSubagents } from '@/store/subagents'
 import { clearSessionTodos } from '@/store/todos'
 
 import type {
-  ClientSessionState,
   BrowserManageResponse,
+  ClientSessionState,
   FileAttachResponse,
   HandoffFailResponse,
   HandoffRequestResponse,
@@ -1175,6 +1178,35 @@ export function usePromptActions({
             renderSlashOutput(`error: ${err instanceof Error ? err.message : String(err)}`)
           }
         },
+        pet: async ctx => {
+          const [sub = '', rawValue = ''] = ctx.arg.trim().split(/\s+/)
+          const lower = sub.toLowerCase()
+
+          if (lower === 'list' || lower === 'gallery' || lower === 'browse' || lower === 'all') {
+            openCommandPalettePage('pets')
+
+            return
+          }
+
+          // `/pet scale <n>` resizes the floating pet locally (instant) and
+          // persists via the store — no round-trip to the slash worker.
+          if (lower === 'scale') {
+            const value = Number(rawValue)
+
+            if (!rawValue || Number.isNaN(value)) {
+              const resolved = await withSlashOutput(ctx)
+              resolved?.render('usage: /pet scale <factor>  (e.g. /pet scale 0.5)')
+
+              return
+            }
+
+            setPetScale(requestGateway, value)
+
+            return
+          }
+
+          await runExec(ctx)
+        },
         // /browser connect|disconnect|status manages the live CDP connection on
         // the gateway host, mirroring the TUI's browser.manage RPC. It mutates
         // BROWSER_CDP_URL (and may launch Chrome) in the gateway process — only
@@ -1391,6 +1423,7 @@ export function usePromptActions({
 
   const cancelRun = useCallback(async () => {
     const sessionId = activeSessionId || activeSessionIdRef.current
+
     const releaseBusy = () => {
       setMutableRef(busyRef, false)
       setBusy(false)
@@ -1643,6 +1676,7 @@ export function usePromptActions({
       // rows (and kill the live processes) before the fresh run repopulates.
       clearSessionTodos(sessionId)
       resetSessionBackground(sessionId)
+      clearPreviewArtifacts(sessionId)
 
       clearNotifications()
       setMutableRef(busyRef, true)
@@ -1705,6 +1739,7 @@ export function usePromptActions({
       // processes) before the re-run repopulates them.
       clearSessionTodos(sessionId)
       resetSessionBackground(sessionId)
+      clearPreviewArtifacts(sessionId)
 
       clearNotifications()
       setMutableRef(busyRef, true)

apps/desktop/src/app/settings/appearance-settings.tsx

@@ -1,30 +1,31 @@
 import { useStore } from '@nanostores/react'
-import { useState } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { useEffect, useState } from 'react'
 
 import { LanguageSwitcher } from '@/components/language-switcher'
 import { SegmentedControl } from '@/components/ui/segmented-control'
+import type { DesktopMarketplaceSearchItem } from '@/global'
 import { useI18n } from '@/i18n'
 import { triggerHaptic } from '@/lib/haptics'
 import { Check, Download, Loader2, Palette, Trash2 } from '@/lib/icons'
+import { selectableCardClass } from '@/lib/selectable-card'
 import { cn } from '@/lib/utils'
 import { $activeGatewayProfile, $profiles, normalizeProfileKey } from '@/store/profile'
 import { $toolViewMode, setToolViewMode } from '@/store/tool-view'
 import { $translucency, setTranslucency } from '@/store/translucency'
-import { useTheme } from '@/themes/context'
+import { getBaseColors, useTheme } from '@/themes/context'
 import { installVscodeThemeFromMarketplace } from '@/themes/install'
-import { isUserTheme, removeUserTheme, resolveTheme } from '@/themes/user-themes'
+import { isUserTheme, removeUserTheme } from '@/themes/user-themes'
 
 import { MODE_OPTIONS } from './constants'
+import { PetSettings } from './pet-settings'
 import { ListRow, SectionHeading, SettingsContent } from './primitives'
 
-function ThemePreview({ name }: { name: string }) {
-  const t = resolveTheme(name)
-
-  if (!t) {
-    return null
-  }
-
-  const c = t.colors
+function ThemePreview({ name, mode }: { name: string; mode: 'light' | 'dark' }) {
+  // Preview in the *current* mode: the dark palette in Dark, and the light
+  // palette in Light — synthesizing one for dark-only themes — so every card
+  // tracks the Light/Dark toggle, exactly like the app itself does.
+  const c = getBaseColors(name, mode)
 
   return (
     <div
@@ -57,90 +58,200 @@ function ThemePreview({ name }: { name: string }) {
   )
 }
 
-function VscodeThemeInstaller() {
+function useDebounced<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value)
+
+  useEffect(() => {
+    const handle = setTimeout(() => setDebounced(value), delayMs)
+
+    return () => clearTimeout(handle)
+  }, [value, delayMs])
+
+  return debounced
+}
+
+const compactNumber = new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 })
+
+/**
+ * Live VS Code Marketplace theme search (the same backend as the Cmd-K "Install
+ * theme…" page). Renders below the local grid when there's a query: each row
+ * downloads + converts + installs via `installVscodeThemeFromMarketplace` and
+ * activates it. Extensions already imported locally are marked installed.
+ */
+function MarketplaceThemeResults({
+  query,
+  installedExtIds,
+  onInstalled
+}: {
+  query: string
+  installedExtIds: Set<string>
+  onInstalled: (name: string) => void
+}) {
   const { t } = useI18n()
-  const { setTheme } = useTheme()
-  const a = t.settings.appearance
-  const [id, setId] = useState('')
-  const [busy, setBusy] = useState(false)
-  const [status, setStatus] = useState<{ kind: 'error' | 'success'; text: string } | null>(null)
+  const copy = t.commandCenter.installTheme
+  const debounced = useDebounced(query.trim(), 300)
+  const [installingId, setInstallingId] = useState<string | null>(null)
+  const [installedHere, setInstalledHere] = useState<Record<string, true>>({})
+  const [error, setError] = useState<string | null>(null)
 
-  const install = async () => {
-    const trimmed = id.trim()
+  const search = useQuery({
+    enabled: debounced.length > 0,
+    queryFn: () => window.hermesDesktop?.themes?.searchMarketplace(debounced) ?? Promise.resolve([]),
+    queryKey: ['marketplace-themes-settings', debounced],
+    staleTime: 5 * 60 * 1000
+  })
 
-    if (!trimmed || busy) {
+  const install = async (item: DesktopMarketplaceSearchItem) => {
+    if (installingId) {
       return
     }
 
-    setBusy(true)
-    setStatus(null)
+    setInstallingId(item.extensionId)
+    setError(null)
 
     try {
-      const theme = await installVscodeThemeFromMarketplace(trimmed)
+      const theme = await installVscodeThemeFromMarketplace(item.extensionId)
 
       triggerHaptic('crisp')
-      setTheme(theme.name)
-      setStatus({ kind: 'success', text: a.installed(theme.label) })
-      setId('')
-    } catch (error) {
-      setStatus({ kind: 'error', text: error instanceof Error ? error.message : a.installError })
+      setInstalledHere(prev => ({ ...prev, [item.extensionId]: true }))
+      onInstalled(theme.name)
+    } catch (e) {
+      setError(e instanceof Error ? e.message : copy.error)
     } finally {
-      setBusy(false)
+      setInstallingId(null)
     }
   }
 
-  return (
-    <div className="mt-3">
-      <div className="flex flex-wrap items-center gap-2">
-        <input
-          className="min-w-0 flex-1 rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-3 py-1.5 font-mono text-[length:var(--conversation-caption-font-size)] outline-none placeholder:text-(--ui-text-tertiary) focus:border-(--ui-stroke-secondary)"
-          disabled={busy}
-          onChange={event => {
-            setId(event.target.value)
-            setStatus(null)
-          }}
-          onKeyDown={event => {
-            if (event.key === 'Enter') {
-              void install()
-            }
-          }}
-          placeholder={a.installPlaceholder}
-          spellCheck={false}
-          value={id}
-        />
-        <button
-          className="inline-flex items-center gap-1.5 rounded-lg border border-(--ui-stroke-secondary) bg-(--ui-bg-tertiary) px-3 py-1.5 text-[length:var(--conversation-caption-font-size)] font-medium transition hover:bg-(--chrome-action-hover) disabled:opacity-50"
-          disabled={busy || !id.trim()}
-          onClick={() => void install()}
-          type="button"
-        >
-          {busy ? <Loader2 className="size-3.5 animate-spin" /> : <Download className="size-3.5" />}
-          {busy ? a.installing : a.installButton}
-        </button>
-      </div>
-      {status && (
-        <p
-          className={cn(
-            'mt-2 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height)',
-            status.kind === 'error' ? 'text-(--ui-red)' : 'text-(--ui-text-tertiary)'
-          )}
-        >
-          {status.text}
+  if (!debounced) {
+    return null
+  }
+
+  const header = (
+    <p className="mb-2 mt-4 text-[length:var(--conversation-caption-font-size)] font-medium text-(--ui-text-tertiary)">
+      From the VS Code Marketplace
+    </p>
+  )
+
+  if (search.isLoading) {
+    return (
+      <>
+        {header}
+        <p className="flex items-center gap-2 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+          <Loader2 className="size-3.5 animate-spin" />
+          {copy.loading}
         </p>
-      )}
-    </div>
+      </>
+    )
+  }
+
+  if (search.isError) {
+    return (
+      <>
+        {header}
+        <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-red)">{copy.error}</p>
+      </>
+    )
+  }
+
+  const results = search.data ?? []
+
+  if (results.length === 0) {
+    return (
+      <>
+        {header}
+        <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">{copy.empty}</p>
+      </>
+    )
+  }
+
+  return (
+    <>
+      {header}
+      {error && <p className="mb-2 text-[length:var(--conversation-caption-font-size)] text-(--ui-red)">{error}</p>}
+      <div className="grid gap-2 sm:grid-cols-2">
+        {results.map(item => {
+          const busy = installingId === item.extensionId
+          const done = installedHere[item.extensionId] || installedExtIds.has(item.extensionId)
+
+          return (
+            <button
+              className={cn(
+                'flex items-center gap-2.5 px-2.5 py-2 text-left disabled:opacity-60',
+                selectableCardClass({ prominent: done })
+              )}
+              disabled={Boolean(installingId) && !busy}
+              key={item.extensionId}
+              onClick={() => void install(item)}
+              type="button"
+            >
+              <Palette className="size-4 shrink-0 text-(--ui-text-tertiary)" />
+              <span className="min-w-0 flex-1">
+                <span className="block truncate text-[length:var(--conversation-text-font-size)] font-medium">
+                  {item.displayName}
+                </span>
+                <span className="block truncate text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+                  {item.publisher}
+                  {item.installs > 0 ? ` · ${copy.installs(compactNumber.format(item.installs))}` : ''}
+                </span>
+              </span>
+              <span className="shrink-0 text-(--ui-text-tertiary)">
+                {busy ? (
+                  <Loader2 className="size-4 animate-spin" />
+                ) : done ? (
+                  <Check className="size-4 text-(--ui-green)" />
+                ) : (
+                  <Download className="size-4" />
+                )}
+              </span>
+            </button>
+          )
+        })}
+      </div>
+    </>
   )
 }
 
 export function AppearanceSettings() {
   const { t, isSavingLocale } = useI18n()
-  const { themeName, mode, availableThemes, setTheme, setMode } = useTheme()
+  const { themeName, mode, resolvedMode, availableThemes, setTheme, setMode } = useTheme()
   const toolViewMode = useStore($toolViewMode)
   const translucency = useStore($translucency)
   const profiles = useStore($profiles)
   const activeProfileKey = normalizeProfileKey(useStore($activeGatewayProfile))
   const a = t.settings.appearance
 
+  const [query, setQuery] = useState('')
+
+  // One box does double duty: filter installed themes live (below), and run a
+  // name search against the VS Code Marketplace (the Cmd-K "Install theme…"
+  // backend) for anything not already installed.
+  const needle = query.trim().toLowerCase()
+
+  const filteredThemes = availableThemes
+    .filter(
+      theme =>
+        !needle ||
+        theme.label.toLowerCase().includes(needle) ||
+        theme.name.toLowerCase().includes(needle) ||
+        theme.description.toLowerCase().includes(needle)
+    )
+    // Active theme first; stable sort keeps the rest in their original order.
+    .sort((a, b) => Number(b.name === themeName) - Number(a.name === themeName))
+
+  // Marketplace imports describe themselves as "VS Code · <publisher.extension>";
+  // pull those ids back out so search results already imported show as installed.
+  const MARKETPLACE_DESC_PREFIX = 'VS Code · '
+
+  const installedExtIds = new Set(
+    availableThemes
+      .map(theme =>
+        theme.description.startsWith(MARKETPLACE_DESC_PREFIX)
+          ? theme.description.slice(MARKETPLACE_DESC_PREFIX.length)
+          : ''
+      )
+      .filter(Boolean)
+  )
+
   // Themes save per profile. Surface that only when the user actually has more
   // than one profile (single-profile installs never see the distinction).
   const showProfileNote = profiles.length > 1
@@ -163,7 +274,7 @@ export function AppearanceSettings() {
           {a.intro}
         </p>
 
-        <div className="mt-2 divide-y divide-(--ui-stroke-tertiary)">
+        <div className="mt-2">
           <ListRow
             action={<LanguageSwitcher />}
             description={isSavingLocale ? t.language.saving : t.language.description}
@@ -171,18 +282,107 @@ export function AppearanceSettings() {
           />
 
           <ListRow
-            action={
-              <SegmentedControl
-                onChange={id => {
-                  triggerHaptic('crisp')
-                  setMode(id)
-                }}
-                options={modeOptions}
-                value={mode}
-              />
+            below={
+              <>
+                {/* One search box: filters your installed themes (the grid)
+                    and live-searches the VS Code Marketplace below. */}
+                <div className="mt-3">
+                  <input
+                    className="w-full rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-3 py-1.5 text-[length:var(--conversation-caption-font-size)] outline-none placeholder:text-(--ui-text-tertiary) focus:border-(--ui-stroke-secondary)"
+                    onChange={event => setQuery(event.target.value)}
+                    placeholder="Search your themes or the VS Code Marketplace…"
+                    spellCheck={false}
+                    value={query}
+                  />
+                </div>
+
+                {/* Fixed-height scroll area so the (growing) theme list never
+                    runs the page long; the grid scrolls inside it. */}
+                <div className="mt-3 max-h-96 overflow-y-auto pr-1">
+                  {filteredThemes.length === 0 ? (
+                    needle ? (
+                      <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+                        No installed themes match "{query.trim()}".
+                      </p>
+                    ) : null
+                  ) : (
+                    <div className="grid gap-3 sm:grid-cols-2 xl:grid-cols-3">
+                      {filteredThemes.map(theme => {
+                        const active = themeName === theme.name
+                        const removable = isUserTheme(theme.name)
+
+                        return (
+                          <div className="group relative" key={theme.name}>
+                            <button
+                              className={cn('w-full p-2 text-left', selectableCardClass({ active, prominent: true }))}
+                              onClick={() => {
+                                triggerHaptic('crisp')
+                                setTheme(theme.name)
+                              }}
+                              type="button"
+                            >
+                              <ThemePreview mode={resolvedMode} name={theme.name} />
+                              <div className="mt-3 px-1">
+                                <div className="truncate text-[length:var(--conversation-text-font-size)] font-medium">
+                                  {theme.label}
+                                </div>
+                                <div className="mt-0.5 line-clamp-2 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+                                  {theme.description}
+                                </div>
+                              </div>
+                            </button>
+                            {removable && (
+                              <button
+                                aria-label={a.removeTheme}
+                                className="absolute right-1.5 top-1.5 grid size-6 place-items-center rounded-md bg-(--ui-bg-elevated)/80 text-(--ui-text-tertiary) opacity-0 backdrop-blur-sm transition hover:text-(--ui-red) focus-visible:opacity-100 group-hover:opacity-100"
+                                onClick={() => {
+                                  triggerHaptic('crisp')
+                                  removeUserTheme(theme.name)
+
+                                  // Re-normalize off the now-missing skin → default.
+                                  if (active) {
+                                    setTheme(theme.name)
+                                  }
+                                }}
+                                title={a.removeTheme}
+                                type="button"
+                              >
+                                <Trash2 className="size-3.5" />
+                              </button>
+                            )}
+                          </div>
+                        )
+                      })}
+                    </div>
+                  )}
+                  <MarketplaceThemeResults
+                    installedExtIds={installedExtIds}
+                    onInstalled={name => setTheme(name)}
+                    query={query}
+                  />
+                </div>
+                {showProfileNote && (
+                  <p className="mt-3 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+                    {a.themeProfileNote(activeProfileName)}
+                  </p>
+                )}
+              </>
             }
-            description={a.colorModeDesc}
-            title={a.colorMode}
+            description={a.themeDesc}
+            title={
+              <div className="flex items-center justify-between gap-3">
+                <span>{a.themeTitle}</span>
+                <SegmentedControl
+                  onChange={id => {
+                    triggerHaptic('crisp')
+                    setMode(id)
+                  }}
+                  options={modeOptions}
+                  value={mode}
+                />
+              </div>
+            }
+            wide
           />
 
           <ListRow
@@ -211,80 +411,6 @@ export function AppearanceSettings() {
             title={a.translucencyTitle}
           />
 
-          <ListRow
-            below={
-              <>
-                <div className="mt-3 grid gap-3 sm:grid-cols-2 xl:grid-cols-3">
-                  {availableThemes.map(theme => {
-                    const active = themeName === theme.name
-                    const removable = isUserTheme(theme.name)
-
-                    return (
-                      <div className="group relative" key={theme.name}>
-                        <button
-                          className={cn(
-                            'w-full rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) p-2 text-left transition hover:bg-(--chrome-action-hover)',
-                            active && 'border-(--ui-stroke-secondary) bg-(--ui-bg-tertiary)'
-                          )}
-                          onClick={() => {
-                            triggerHaptic('crisp')
-                            setTheme(theme.name)
-                          }}
-                          type="button"
-                        >
-                          <ThemePreview name={theme.name} />
-                          <div className="mt-3 flex items-start justify-between gap-3 px-1">
-                            <div className="min-w-0">
-                              <div className="truncate text-[length:var(--conversation-text-font-size)] font-medium">
-                                {theme.label}
-                              </div>
-                              <div className="mt-0.5 line-clamp-2 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
-                                {theme.description}
-                              </div>
-                            </div>
-                            {active && (
-                              <span className="mt-0.5 grid size-5 shrink-0 place-items-center rounded-full bg-primary text-primary-foreground">
-                                <Check className="size-3.5" />
-                              </span>
-                            )}
-                          </div>
-                        </button>
-                        {removable && (
-                          <button
-                            aria-label={a.removeTheme}
-                            className="absolute right-1.5 top-1.5 grid size-6 place-items-center rounded-md bg-(--ui-bg-elevated)/80 text-(--ui-text-tertiary) opacity-0 backdrop-blur-sm transition hover:text-(--ui-red) focus-visible:opacity-100 group-hover:opacity-100"
-                            onClick={() => {
-                              triggerHaptic('crisp')
-                              removeUserTheme(theme.name)
-
-                              // Re-normalize off the now-missing skin → default.
-                              if (active) {
-                                setTheme(theme.name)
-                              }
-                            }}
-                            title={a.removeTheme}
-                            type="button"
-                          >
-                            <Trash2 className="size-3.5" />
-                          </button>
-                        )}
-                      </div>
-                    )
-                  })}
-                </div>
-                <VscodeThemeInstaller />
-                {showProfileNote && (
-                  <p className="mt-3 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
-                    {a.themeProfileNote(activeProfileName)}
-                  </p>
-                )}
-              </>
-            }
-            description={a.themeDesc}
-            title={a.themeTitle}
-            wide
-          />
-
           <ListRow
             action={
               <SegmentedControl
@@ -301,6 +427,10 @@ export function AppearanceSettings() {
           />
         </div>
       </div>
+
+      <div className="mt-6">
+        <PetSettings />
+      </div>
     </SettingsContent>
   )
 }

apps/desktop/src/app/settings/computer-use-panel.tsx

@@ -0,0 +1,239 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { getActionStatus, getComputerUseStatus, grantComputerUsePermissions } from '@/hermes'
+import { AlertTriangle, Check, ExternalLink, Loader2, RefreshCw, X } from '@/lib/icons'
+import { upsertDesktopActionTask } from '@/store/activity'
+import { notify, notifyError } from '@/store/notifications'
+import type { ComputerUseStatus } from '@/types/hermes'
+
+import { Pill } from './primitives'
+
+interface ComputerUsePanelProps {
+  /** Re-read the parent toolset list after a permission/install change so the
+   *  "Configured / Needs keys" pill stays in sync. */
+  onConfiguredChange?: () => void
+}
+
+// Per-OS one-liner shown when there's no TCC grant flow (Windows/Linux). macOS
+// drives the permission rows instead, so it has no entry here.
+const PLATFORM_NOTE: Record<string, string> = {
+  linux: 'Drives your desktop via the X11/XWayland accessibility stack — no permission prompt.',
+  win32: 'First run may trigger a Windows SmartScreen prompt for the cua-driver UIAccess worker — allow it.'
+}
+
+function tone(granted: boolean | null) {
+  return granted === true ? 'primary' : 'muted'
+}
+
+function GrantIcon({ granted }: { granted: boolean | null }) {
+  const Icon = granted === true ? Check : granted === false ? X : AlertTriangle
+
+  return <Icon className="size-3" />
+}
+
+function PermissionRow({ granted, label, hint }: { granted: boolean | null; label: string; hint: string }) {
+  return (
+    <div className="flex flex-wrap items-center justify-between gap-2 rounded-lg bg-background/55 p-2.5">
+      <div className="min-w-0">
+        <span className="text-sm font-medium">{label}</span>
+        <p className="mt-0.5 text-[0.7rem] text-muted-foreground">{hint}</p>
+      </div>
+      <Pill tone={tone(granted)}>
+        <GrantIcon granted={granted} />
+        {granted === true ? 'Granted' : granted === false ? 'Not granted' : 'Unknown'}
+      </Pill>
+    </div>
+  )
+}
+
+/**
+ * Cross-platform Computer Use preflight card.
+ *
+ * cua-driver runs on macOS, Windows, and Linux, but readiness differs: macOS
+ * needs two TCC grants (Accessibility + Screen Recording) that attach to
+ * cua-driver's own `com.trycua.driver` identity — not Hermes — and are
+ * requested via `cua-driver permissions grant` (dialog attributed to
+ * CuaDriver). Windows/Linux have no TCC toggles, so readiness is driver health
+ * from `cua-driver doctor`. The backend folds both into one `ready` signal.
+ *
+ * Binary install/upgrade stays in the cua-driver provider's post-setup runner
+ * below this card (the generic ToolsetConfigPanel).
+ */
+export function ComputerUsePanel({ onConfiguredChange }: ComputerUsePanelProps) {
+  const [status, setStatus] = useState<ComputerUseStatus | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [granting, setGranting] = useState(false)
+  const activeRef = useRef(false)
+
+  const refresh = useCallback(async () => {
+    try {
+      setStatus(await getComputerUseStatus())
+    } catch (err) {
+      notifyError(err, 'Could not read Computer Use status')
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    activeRef.current = true
+    void refresh()
+
+    return () => void (activeRef.current = false)
+  }, [refresh])
+
+  const grant = useCallback(async () => {
+    setGranting(true)
+
+    try {
+      const started = await grantComputerUsePermissions()
+
+      if (!started.ok) {
+        notifyError(new Error('spawn failed'), 'Could not request permissions')
+
+        return
+      }
+
+      notify({
+        kind: 'info',
+        title: 'Approve in System Settings',
+        message: 'macOS will show a permission dialog attributed to CuaDriver. Approve it, then return here.'
+      })
+
+      // The driver waits for the user to flip the switch — poll until it exits.
+      for (let attempt = 0; attempt < 150 && activeRef.current; attempt += 1) {
+        await new Promise(resolve => window.setTimeout(resolve, 1500))
+
+        if (!activeRef.current) {
+          break
+        }
+
+        const polled = await getActionStatus(started.name, 200)
+        upsertDesktopActionTask(polled)
+
+        if (!polled.running) {
+          break
+        }
+      }
+
+      if (activeRef.current) {
+        await refresh()
+        onConfiguredChange?.()
+      }
+    } catch (err) {
+      if (activeRef.current) {
+        notifyError(err, 'Could not request permissions')
+      }
+    } finally {
+      if (activeRef.current) {
+        setGranting(false)
+      }
+    }
+  }, [onConfiguredChange, refresh])
+
+  if (loading) {
+    return (
+      <div className="mt-3 flex items-center gap-2 px-1 text-xs text-muted-foreground">
+        <Loader2 className="size-3.5 animate-spin" />
+        Checking Computer Use status…
+      </div>
+    )
+  }
+
+  if (!status) {
+    return null
+  }
+
+  if (!status.platform_supported) {
+    return (
+      <p className="mt-3 px-1 text-xs text-muted-foreground">
+        Computer Use isn&apos;t supported on this platform ({status.platform}).
+      </p>
+    )
+  }
+
+  if (!status.installed) {
+    return (
+      <p className="mt-3 px-1 text-xs text-muted-foreground">
+        Install the cua-driver backend below to drive this machine.
+        {status.can_grant && ' Then grant Accessibility and Screen Recording here.'}
+      </p>
+    )
+  }
+
+  const failingChecks = status.checks.filter(c => c.status !== 'ok')
+
+  return (
+    <div className="mt-3 grid gap-2">
+      <div className="flex flex-wrap items-center justify-between gap-2 px-1">
+        <div className="min-w-0">
+          {status.can_grant ? (
+            <p className="text-[0.72rem] text-muted-foreground">
+              Grants attach to CuaDriver&apos;s own identity (com.trycua.driver), not Hermes — so the dialog is
+              attributed to the process that drives your Mac.
+            </p>
+          ) : (
+            <p className="text-[0.72rem] text-muted-foreground">{PLATFORM_NOTE[status.platform] ?? ''}</p>
+          )}
+          {status.version && <p className="text-[0.68rem] text-muted-foreground/80">{status.version}</p>}
+        </div>
+        <Button onClick={() => void refresh()} size="sm" variant="text">
+          <RefreshCw className="size-3.5" />
+          Recheck
+        </Button>
+      </div>
+
+      {status.can_grant ? (
+        <>
+          <PermissionRow
+            granted={status.accessibility}
+            hint="Lets cua-driver post clicks, keystrokes, and read the accessibility tree."
+            label="Accessibility"
+          />
+          <PermissionRow
+            granted={status.screen_recording}
+            hint="Lets cua-driver capture screenshots of app windows."
+            label="Screen Recording"
+          />
+        </>
+      ) : (
+        <div className="flex flex-wrap items-center justify-between gap-2 rounded-lg bg-background/55 p-2.5">
+          <span className="text-sm font-medium">Driver health</span>
+          <Pill tone={tone(status.ready)}>
+            <GrantIcon granted={status.ready} />
+            {status.ready === true ? 'Ready' : status.ready === false ? 'Not ready' : 'Unknown'}
+          </Pill>
+        </div>
+      )}
+
+      {failingChecks.map(c => (
+        <p className="px-1 text-[0.7rem] text-muted-foreground" key={c.label}>
+          <AlertTriangle className="mr-1 inline size-3" />
+          {c.label}: {c.message}
+        </p>
+      ))}
+
+      {status.error && (
+        <p className="px-1 text-[0.7rem] text-muted-foreground">
+          <AlertTriangle className="mr-1 inline size-3" />
+          {status.error}
+        </p>
+      )}
+
+      {status.ready ? (
+        <div className="flex items-center gap-1.5 px-1 text-xs text-muted-foreground">
+          <Check className="size-3.5" />
+          Computer Use is ready. Ask the agent to capture an app and click around.
+        </div>
+      ) : (
+        status.can_grant && (
+          <Button disabled={granting} onClick={() => void grant()} size="sm">
+            {granting ? <Loader2 className="size-3.5 animate-spin" /> : <ExternalLink className="size-3.5" />}
+            {granting ? 'Waiting for approval…' : 'Grant permissions'}
+          </Button>
+        )
+      )}
+    </div>
+  )
+}

apps/desktop/src/app/settings/config-settings.tsx

@@ -21,6 +21,7 @@ import type { ConfigFieldSchema, HermesConfigRecord } from '@/types/hermes'
 import { CONTROL_TEXT, EMPTY_SELECT_VALUE, FIELD_DESCRIPTIONS, FIELD_LABELS, SECTIONS } from './constants'
 import { fieldCopyForSchemaKey } from './field-copy'
 import { enumOptionsFor, getNested, prettyName, setNested } from './helpers'
+import { MemoryConnect } from './memory/connect'
 import { ModelSettings } from './model-settings'
 import { EmptyState, ListRow, LoadingState, SettingsContent } from './primitives'
 import { ProviderConfigPanel } from './provider-config-panel'
@@ -31,7 +32,8 @@ function ConfigField({
   value,
   enumOptions,
   optionLabels,
-  onChange
+  onChange,
+  descriptionExtra
 }: {
   schemaKey: string
   schema: ConfigFieldSchema
@@ -39,6 +41,7 @@ function ConfigField({
   enumOptions?: string[]
   optionLabels?: Record<string, string>
   onChange: (value: unknown) => void
+  descriptionExtra?: ReactNode
 }) {
   const { t } = useI18n()
   const c = t.settings.config
@@ -64,8 +67,17 @@ function ConfigField({
       ? rawDescription
       : undefined
 
+  const descriptionNode: ReactNode = descriptionExtra ? (
+    <span className="inline-flex flex-wrap items-center gap-x-3 gap-y-1">
+      {description}
+      {descriptionExtra}
+    </span>
+  ) : (
+    description
+  )
+
   const row = (action: ReactNode, wide = false) => (
-    <ListRow action={action} description={description} title={label} wide={wide} />
+    <ListRow action={action} description={descriptionNode} title={label} wide={wide} />
   )
 
   if (schema.type === 'boolean') {
@@ -358,6 +370,11 @@ export function ConfigSettings({
           {fields.map(([key, field]) => (
             <div className="scroll-mt-6 rounded-lg" id={`setting-field-${key}`} key={key}>
               <ConfigField
+                descriptionExtra={
+                  key === 'memory.provider' && Boolean(getNested(config, key)) ? (
+                    <MemoryConnect provider={String(getNested(config, key))} />
+                  ) : undefined
+                }
                 enumOptions={
                   key === 'tts.elevenlabs.voice_id'
                     ? enumOptionsFor(key, getNested(config, key), config, elevenLabsVoiceOptions ?? undefined)

apps/desktop/src/app/settings/memory/connect.tsx

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { getMemoryProviderOAuthStatus, startMemoryProviderOAuth } from '@/hermes'
+import { Check, ExternalLink, Loader2 } from '@/lib/icons'
+import { notifyError } from '@/store/notifications'
+import type { MemoryProviderOAuthStatus } from '@/types/hermes'
+
+const POLL_MS = 1500
+const POLL_TIMEOUT_MS = 120_000
+
+// Small connect affordance rendered under the provider dropdown. Capability is
+// backend-driven: the status route 404s for providers without an oauth_flow
+// module, so non-OAuth providers render nothing.
+export function MemoryConnect({ provider }: { provider: string }) {
+  const [capable, setCapable] = useState<'no' | 'unknown' | 'yes'>('unknown')
+  const [connected, setConnected] = useState(false)
+  const [auth, setAuth] = useState<MemoryProviderOAuthStatus['auth']>(null)
+  const [phase, setPhase] = useState<'error' | 'idle' | 'pending'>('idle')
+  const [detail, setDetail] = useState('')
+  const timer = useRef<ReturnType<typeof setInterval> | null>(null)
+  const deadline = useRef(0)
+
+  const stop = useCallback(() => {
+    if (timer.current !== null) {
+      clearInterval(timer.current)
+      timer.current = null
+    }
+  }, [])
+
+  useEffect(() => {
+    let active = true
+    setCapable('unknown')
+    getMemoryProviderOAuthStatus(provider)
+      .then(s => {
+        if (!active) {
+          return
+        }
+
+        setCapable('yes')
+        setConnected(s.connected)
+        setAuth(s.auth)
+      })
+      .catch(() => {
+        if (active) {
+          setCapable('no')
+        }
+      })
+
+    return () => {
+      active = false
+      stop()
+    }
+  }, [provider, stop])
+
+  // An error message isn't sticky — it clears back to the steady state
+  // (Connect link, plus the connected badge if a credential is stored).
+  useEffect(() => {
+    if (phase !== 'error') {
+      return
+    }
+
+    const t = setTimeout(() => {
+      setPhase('idle')
+      setDetail('')
+    }, 6000)
+
+    return () => clearTimeout(t)
+  }, [phase])
+
+  const connect = useCallback(async () => {
+    setPhase('pending')
+
+    try {
+      await startMemoryProviderOAuth(provider)
+    } catch (err) {
+      setPhase('error')
+      setDetail('Could not start the connection.')
+      notifyError(err, 'Failed to start connection')
+
+      return
+    }
+
+    deadline.current = Date.now() + POLL_TIMEOUT_MS
+    stop()
+    timer.current = setInterval(() => {
+      void (async () => {
+        try {
+          const next = await getMemoryProviderOAuthStatus(provider)
+
+          if (next.state === 'pending') {
+            if (Date.now() > deadline.current) {
+              stop()
+              setPhase('error')
+              setDetail('Timed out — try again.')
+            }
+
+            return
+          }
+
+          stop()
+          setConnected(next.connected)
+          setAuth(next.auth)
+
+          if (next.state === 'error') {
+            setPhase('error')
+            setDetail(next.detail || 'Connection failed.')
+          } else {
+            setPhase('idle')
+          }
+        } catch {
+          // Transient poll failure — keep trying until the deadline.
+        }
+      })()
+    }, POLL_MS)
+  }, [provider, stop])
+
+  const cancel = useCallback(() => {
+    stop()
+    setPhase('idle')
+  }, [stop])
+
+  if (capable !== 'yes') {
+    return null
+  }
+
+  const connectLabel = connected ? (auth === 'apikey' ? 'Connect via OAuth' : 'Reconnect') : 'Connect'
+
+  return (
+    <span className="inline-flex flex-wrap items-center gap-x-3 gap-y-1 text-xs">
+      {phase === 'idle' && connected && (
+        <span className="inline-flex items-center gap-1 text-muted-foreground">
+          <Check className="size-3" />
+          {auth === 'apikey' ? 'api key set' : 'oauth set'}
+        </span>
+      )}
+      {phase === 'pending' ? (
+        <>
+          <span className="inline-flex items-center gap-1.5 text-muted-foreground">
+            <Loader2 className="size-3 animate-spin" />
+            Waiting for browser consent…
+          </span>
+          <Button className="h-auto p-0 text-xs" onClick={cancel} size="sm" type="button" variant="link">
+            Cancel
+          </Button>
+        </>
+      ) : (
+        <Button
+          className="h-auto gap-1 p-0 text-xs"
+          onClick={() => void connect()}
+          size="sm"
+          type="button"
+          variant="link"
+        >
+          <ExternalLink className="size-3" />
+          {connectLabel}
+        </Button>
+      )}
+      {phase === 'error' && detail && <span className="text-destructive">{detail}</span>}
+    </span>
+  )
+}

apps/desktop/src/app/settings/pet-settings.tsx

@@ -0,0 +1,231 @@
+import { useStore } from '@nanostores/react'
+import { useEffect, useState } from 'react'
+
+import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
+import { PetThumb } from '@/components/pet/pet-thumb'
+import { SegmentedControl } from '@/components/ui/segmented-control'
+import { useI18n } from '@/i18n'
+import { triggerHaptic } from '@/lib/haptics'
+import { Loader2, PawPrint, Trash2 } from '@/lib/icons'
+import { selectableCardClass } from '@/lib/selectable-card'
+import { cn } from '@/lib/utils'
+import { $petInfo } from '@/store/pet'
+import {
+  $petBusy,
+  $petGallery,
+  $petGalleryError,
+  $petGalleryStatus,
+  adoptPet,
+  loadPetGallery,
+  loadPetThumb,
+  PET_SCALE_DEFAULT,
+  PET_SCALE_MAX,
+  PET_SCALE_MIN,
+  rankedGalleryPets,
+  removePet as removePetAction,
+  setPetEnabled,
+  setPetScale
+} from '@/store/pet-gallery'
+import { $gatewayState } from '@/store/session'
+
+import { ListRow, SectionHeading } from './primitives'
+
+/**
+ * Appearance opt-in for the floating petdex mascot. A thin view over the shared
+ * `pet-gallery` store — it subscribes to the atoms and calls the store actions,
+ * so the gallery is fetched once + cached and adopt/toggle/remove patch local
+ * state instead of re-pulling the network gallery. The floating mascot polls
+ * `pet.info`, so picking a pet here lights it up within a couple seconds.
+ */
+export function PetSettings() {
+  const { t } = useI18n()
+  const copy = t.settings.appearance.pet
+  const { requestGateway } = useGatewayRequest()
+  const gatewayState = useStore($gatewayState)
+  const gallery = useStore($petGallery)
+  const status = useStore($petGalleryStatus)
+  const error = useStore($petGalleryError)
+  const busySlug = useStore($petBusy)
+  const petInfo = useStore($petInfo)
+  const [query, setQuery] = useState('')
+  const scale = petInfo.scale ?? PET_SCALE_DEFAULT
+
+  useEffect(() => {
+    if (gatewayState !== 'open') {
+      return
+    }
+
+    void loadPetGallery(requestGateway)
+  }, [gatewayState, requestGateway])
+
+  const enabled = gallery?.enabled ?? false
+  const active = gallery?.active ?? ''
+  const pets = gallery?.pets ?? []
+  const staleBackend = status === 'stale'
+
+  const selectPet = (slug: string) => {
+    void adoptPet(requestGateway, slug, copy.adoptFailed(slug)).then(ok => ok && triggerHaptic('crisp'))
+  }
+
+  const removePet = (slug: string) => {
+    void removePetAction(requestGateway, slug, copy.uninstallFailed(slug)).then(ok => ok && triggerHaptic('crisp'))
+  }
+
+  const toggle = (on: boolean) => {
+    void setPetEnabled(requestGateway, on, {
+      noneAvailable: copy.noneAvailable,
+      fallback: on ? copy.turnOnFailed : copy.turnOffFailed
+    }).then(ok => ok && triggerHaptic('crisp'))
+  }
+
+  // The petdex catalog is thousands of entries, so rank + cap how many render.
+  const RENDER_CAP = 60
+  const sorted = rankedGalleryPets(gallery, query)
+  const shown = sorted.slice(0, RENDER_CAP)
+
+  return (
+    <div>
+      <SectionHeading icon={PawPrint} title={copy.title} />
+      <p className="max-w-2xl text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+        {copy.intro}
+      </p>
+
+      {staleBackend && (
+        <p className="mt-2 rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-3 py-2 text-[length:var(--conversation-caption-font-size)] leading-(--conversation-caption-line-height) text-(--ui-text-tertiary)">
+          {copy.restartHint}
+        </p>
+      )}
+
+      <div className="mt-2">
+        <ListRow
+          below={
+            <>
+              <input
+                className="mt-3 w-full rounded-lg border border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) px-3 py-1.5 text-[length:var(--conversation-caption-font-size)] outline-none placeholder:text-(--ui-text-tertiary) focus:border-(--ui-stroke-secondary)"
+                onChange={event => setQuery(event.target.value)}
+                placeholder={copy.searchPlaceholder}
+                spellCheck={false}
+                value={query}
+              />
+              {/* Fixed-height scroll area so filtering never grows/shrinks the
+                  page (no layout thrash); the grid scrolls inside it. */}
+              <div className="mt-3 h-72 overflow-y-auto pr-1">
+                {pets.length === 0 ? (
+                  <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+                    {copy.unreachable}
+                  </p>
+                ) : shown.length === 0 ? (
+                  <p className="text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+                    {copy.noMatch(query)}
+                  </p>
+                ) : (
+                  <div className="grid gap-2 sm:grid-cols-2 xl:grid-cols-3">
+                    {shown.map(pet => {
+                      const isActive = enabled && active === pet.slug
+                      const isBusy = busySlug === pet.slug
+
+                      return (
+                        <div className="group relative" key={pet.slug}>
+                          <button
+                            className={cn(
+                              'flex w-full items-center gap-2.5 px-2.5 py-2 text-left disabled:opacity-50',
+                              selectableCardClass({ active: isActive, prominent: pet.installed })
+                            )}
+                            disabled={isBusy}
+                            onClick={() => void selectPet(pet.slug)}
+                            type="button"
+                          >
+                            <PetThumb
+                              alt={pet.displayName}
+                              load={(slug, url) => loadPetThumb(requestGateway, slug, url)}
+                              slug={pet.slug}
+                              url={pet.spritesheetUrl}
+                            />
+                            <span className="min-w-0 flex-1">
+                              <span className="block truncate text-[length:var(--conversation-text-font-size)] font-medium">
+                                {pet.displayName}
+                              </span>
+                              <span className="block truncate text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+                                {pet.slug}
+                                {pet.installed ? ` · ${copy.installedTag}` : ''}
+                              </span>
+                            </span>
+                            {isBusy && <Loader2 className="size-4 shrink-0 animate-spin text-(--ui-text-tertiary)" />}
+                          </button>
+                          {pet.installed && !isBusy && (
+                            <button
+                              aria-label={copy.uninstall(pet.displayName)}
+                              className="absolute right-1.5 top-1.5 grid size-6 place-items-center rounded-md bg-(--ui-bg-elevated)/80 text-(--ui-text-tertiary) opacity-0 backdrop-blur-sm transition hover:text-(--ui-red) focus-visible:opacity-100 group-hover:opacity-100"
+                              onClick={() => void removePet(pet.slug)}
+                              title={copy.uninstall(pet.displayName)}
+                              type="button"
+                            >
+                              <Trash2 className="size-3.5" />
+                            </button>
+                          )}
+                        </div>
+                      )
+                    })}
+                  </div>
+                )}
+              </div>
+              {/* Always-present status line so its appearance never shifts layout. */}
+              <p className="mt-2 min-h-4 text-[length:var(--conversation-caption-font-size)] text-(--ui-text-tertiary)">
+                {error ? (
+                  <span className="text-(--ui-red)">{error}</span>
+                ) : sorted.length > RENDER_CAP ? (
+                  copy.countCapped(RENDER_CAP, sorted.length)
+                ) : (
+                  copy.count(sorted.length)
+                )}
+              </p>
+            </>
+          }
+          description={copy.chooseDesc}
+          title={
+            <div className="flex items-center justify-between gap-3">
+              <span>{copy.chooseTitle}</span>
+              <SegmentedControl
+                onChange={id => void toggle(id === 'on')}
+                options={[
+                  { id: 'off', label: copy.off },
+                  { id: 'on', label: copy.on }
+                ]}
+                value={enabled ? 'on' : 'off'}
+              />
+            </div>
+          }
+          wide
+        />
+
+        {enabled && (
+          <ListRow
+            action={
+              <div className="flex items-center gap-3">
+                <input
+                  aria-label={copy.scaleTitle}
+                  className="h-1 w-40 cursor-pointer appearance-none rounded-full bg-(--ui-stroke-tertiary)"
+                  max={PET_SCALE_MAX}
+                  min={PET_SCALE_MIN}
+                  onChange={event => {
+                    triggerHaptic('selection')
+                    setPetScale(requestGateway, Number(event.target.value))
+                  }}
+                  step={0.05}
+                  style={{ accentColor: 'var(--dt-primary)' }}
+                  type="range"
+                  value={scale}
+                />
+                <span className="w-9 text-right text-[length:var(--conversation-caption-font-size)] tabular-nums text-(--ui-text-tertiary)">
+                  {`${Math.round(scale * 100)}%`}
+                </span>
+              </div>
+            }
+            description={copy.scaleDesc}
+            title={copy.scaleTitle}
+          />
+        )}
+      </div>
+    </div>
+  )
+}

apps/desktop/src/app/shell/app-shell.tsx

@@ -4,6 +4,7 @@ import { useSyncExternalStore } from 'react'
 
 import { NotificationStack } from '@/components/notifications'
 import { PaneShell } from '@/components/pane-shell'
+import { FloatingPet } from '@/components/pet/floating-pet'
 import { SidebarProvider } from '@/components/ui/sidebar'
 import { useMediaQuery } from '@/hooks/use-media-query'
 import {
@@ -202,6 +203,10 @@ export function AppShell({
       {/* Mounted at the shell root (after overlays) so success/error toasts
           surface above every route and overlay — not just the chat view. */}
       <NotificationStack />
+
+      {/* Petdex floating mascot — in-window, always-on-top, reactive to agent
+          activity. Renders nothing unless a pet is installed + enabled. */}
+      <FloatingPet />
     </SidebarProvider>
   )
 }

apps/desktop/src/app/shell/titlebar-controls.tsx

@@ -4,6 +4,7 @@ import { useLocation, useNavigate } from 'react-router-dom'
 
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
+import { Tip } from '@/components/ui/tooltip'
 import { useI18n } from '@/i18n'
 import { triggerHaptic } from '@/lib/haptics'
 import { cn } from '@/lib/utils'
@@ -204,41 +205,43 @@ function TitlebarToolButton({ navigate, tool }: { navigate: ReturnType<typeof us
 
   if (tool.href) {
     return (
-      <Button asChild className={className} size="icon-titlebar" variant="ghost">
-        <a
-          aria-label={tool.label}
-          href={tool.href}
-          onPointerDown={event => event.stopPropagation()}
-          rel="noreferrer"
-          target="_blank"
-          title={tool.title ?? tool.label}
-        >
-          {tool.icon}
-        </a>
-      </Button>
+      <Tip label={tool.title ?? tool.label}>
+        <Button asChild className={className} size="icon-titlebar" variant="ghost">
+          <a
+            aria-label={tool.label}
+            href={tool.href}
+            onPointerDown={event => event.stopPropagation()}
+            rel="noreferrer"
+            target="_blank"
+          >
+            {tool.icon}
+          </a>
+        </Button>
+      </Tip>
     )
   }
 
   return (
-    <Button
-      aria-label={tool.label}
-      aria-pressed={tool.active ?? undefined}
-      className={className}
-      disabled={tool.disabled}
-      onClick={() => {
-        if (tool.to) {
-          navigate(tool.to)
-        }
+    <Tip label={tool.title ?? tool.label}>
+      <Button
+        aria-label={tool.label}
+        aria-pressed={tool.active ?? undefined}
+        className={className}
+        disabled={tool.disabled}
+        onClick={() => {
+          if (tool.to) {
+            navigate(tool.to)
+          }
 
-        tool.onSelect?.()
-      }}
-      onPointerDown={event => event.stopPropagation()}
-      size="icon-titlebar"
-      title={tool.title ?? tool.label}
-      type="button"
-      variant="ghost"
-    >
-      {tool.icon}
-    </Button>
+          tool.onSelect?.()
+        }}
+        onPointerDown={event => event.stopPropagation()}
+        size="icon-titlebar"
+        type="button"
+        variant="ghost"
+      >
+        {tool.icon}
+      </Button>
+    </Tip>
   )
 }

apps/desktop/src/app/skills/index.tsx

@@ -17,6 +17,7 @@ import { useRefreshHotkey } from '../hooks/use-refresh-hotkey'
 import { useRouteEnumParam } from '../hooks/use-route-enum-param'
 import { PAGE_INSET_X } from '../layout-constants'
 import { PageSearchShell } from '../page-search-shell'
+import { ComputerUsePanel } from '../settings/computer-use-panel'
 import { asText, includesQuery, prettyName, toolNames, toolsetDisplayLabel } from '../settings/helpers'
 import { ToolsetConfigPanel } from '../settings/toolset-config-panel'
 import type { SetStatusbarItemGroup } from '../shell/statusbar-controls'
@@ -334,6 +335,9 @@ export function SkillsView({ setStatusbarItemGroup: _setStatusbarItemGroup, ...p
                           ))}
                         </div>
                       )}
+                      {expanded && toolset.name === 'computer_use' && (
+                        <ComputerUsePanel onConfiguredChange={refreshToolsets} />
+                      )}
                       {expanded && <ToolsetConfigPanel onConfiguredChange={refreshToolsets} toolset={toolset.name} />}
                     </div>
                   )

apps/desktop/src/components/assistant-ui/thread-timeline-data.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+
+import { activeTimelineIndex, deriveTimelineEntries, timelinePreview } from './thread-timeline-data'
+
+describe('timelinePreview', () => {
+  it('collapses whitespace to a single line', () => {
+    expect(timelinePreview('hello\n\n  world\tagain')).toBe('hello world again')
+  })
+
+  it('truncates with an ellipsis past the limit', () => {
+    const out = timelinePreview('abcdefghij', 5)
+    expect(out).toBe('abcd…')
+    expect(out.length).toBe(5)
+  })
+})
+
+describe('deriveTimelineEntries', () => {
+  it('keeps non-empty user prompts in order', () => {
+    expect(
+      deriveTimelineEntries([
+        { id: 'u1', role: 'user', text: 'first' },
+        { id: 'a1', role: 'assistant', text: 'answer' },
+        { id: 'u2', role: 'user', text: '  second  ' }
+      ])
+    ).toEqual([
+      { id: 'u1', preview: 'first' },
+      { id: 'u2', preview: 'second' }
+    ])
+  })
+
+  it('drops blanks and background-process notifications', () => {
+    expect(
+      deriveTimelineEntries([
+        { id: 'u1', role: 'user', text: '   ' },
+        { id: 'u2', role: 'user', text: '[IMPORTANT: Background process 123 finished]' },
+        { id: 'u3', role: 'user', text: 'real prompt' }
+      ]).map(e => e.id)
+    ).toEqual(['u3'])
+  })
+})
+
+describe('activeTimelineIndex', () => {
+  it('returns the last prompt scrolled to or above the top edge', () => {
+    expect(activeTimelineIndex([-400, -10, 320])).toBe(1)
+  })
+
+  it('falls back to the first rendered entry', () => {
+    expect(activeTimelineIndex([null, 120, 480])).toBe(1)
+    expect(activeTimelineIndex([null, null])).toBe(0)
+  })
+})

apps/desktop/src/components/assistant-ui/thread-timeline-data.ts

@@ -0,0 +1,75 @@
+// Pure timeline helpers — no React/DOM; tested in thread-timeline-data.test.ts.
+
+export interface TimelineSourceMessage {
+  id: string
+  role: string
+  text: string
+}
+
+export interface TimelineEntry {
+  id: string
+  preview: string
+}
+
+// Injected as user messages for alternation; not human prompts (thread.tsx).
+const PROCESS_NOTIFICATION_RE = /^\[IMPORTANT: Background process [\s\S]*\]$/
+
+const PREVIEW_MAX = 120
+
+export function timelinePreview(text: string, max: number = PREVIEW_MAX): string {
+  const collapsed = text.replace(/\s+/g, ' ').trim()
+
+  if (collapsed.length <= max) {
+    return collapsed
+  }
+
+  return `${collapsed.slice(0, max - 1).trimEnd()}…`
+}
+
+export function deriveTimelineEntries(messages: readonly TimelineSourceMessage[]): TimelineEntry[] {
+  const entries: TimelineEntry[] = []
+
+  for (const message of messages) {
+    if (message.role !== 'user') {
+      continue
+    }
+
+    const text = message.text.trim()
+
+    if (!text || PROCESS_NOTIFICATION_RE.test(text)) {
+      continue
+    }
+
+    entries.push({ id: message.id, preview: timelinePreview(text) })
+  }
+
+  return entries
+}
+
+/** Last user prompt at/above the viewport top (with slack); else first rendered. */
+export function activeTimelineIndex(offsets: readonly (number | null)[], slack: number = 8): number {
+  let active = -1
+  let firstRendered = -1
+
+  for (let i = 0; i < offsets.length; i++) {
+    const offset = offsets[i]
+
+    if (offset == null) {
+      continue
+    }
+
+    if (firstRendered === -1) {
+      firstRendered = i
+    }
+
+    if (offset <= slack) {
+      active = i
+    }
+  }
+
+  if (active !== -1) {
+    return active
+  }
+
+  return firstRendered === -1 ? 0 : firstRendered
+}

apps/desktop/src/components/assistant-ui/thread-timeline.tsx

@@ -0,0 +1,272 @@
+import { useAuiState } from '@assistant-ui/react'
+import { type FC, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+
+import { composerPanelCard } from '@/components/chat/composer-dock'
+import { triggerHaptic } from '@/lib/haptics'
+import { cn } from '@/lib/utils'
+import { setPaneHoverRevealSuppressed } from '@/store/panes'
+
+import {
+  activeTimelineIndex,
+  deriveTimelineEntries,
+  type TimelineEntry,
+  type TimelineSourceMessage
+} from './thread-timeline-data'
+
+const MIN_ENTRIES = 4
+const VIEWPORT = '[data-slot="aui_thread-viewport"]'
+const HOVER_CLOSE_MS = 140
+
+const ROW_CLASS =
+  'relative flex w-full min-w-0 max-w-full cursor-pointer select-none overflow-hidden rounded-md px-2 py-1 text-left outline-hidden transition-colors duration-100 ease-out hover:bg-(--ui-row-hover-background) hover:transition-none'
+
+const POPOVER_SHELL = cn(
+  'absolute right-full top-1/2 z-50 mr-1.5 max-h-[min(22rem,calc(100vh-8rem))] w-80 max-w-[min(20rem,calc(100vw-2rem))] -translate-y-1/2 overflow-x-hidden overflow-y-auto overscroll-contain p-1 text-popover-foreground transition-[opacity,transform] duration-100 ease-out group-hover/timeline:transition-none',
+  composerPanelCard,
+  // Solid fill — composerPanelCard is deliberately translucent; without this,
+  // directive chips in the transcript bleed through and look like popover overflow.
+  'bg-(--composer-fill)'
+)
+
+function userPromptText(content: unknown): string {
+  if (typeof content === 'string') {
+    return content
+  }
+
+  if (!Array.isArray(content)) {
+    return ''
+  }
+
+  let out = ''
+
+  for (const part of content) {
+    if (typeof part === 'string') {
+      out += part
+
+      continue
+    }
+
+    if (!part || typeof part !== 'object') {
+      continue
+    }
+
+    const row = part as { text?: unknown; type?: unknown }
+
+    if ((!row.type || row.type === 'text') && typeof row.text === 'string') {
+      out += row.text
+    }
+  }
+
+  return out
+}
+
+function scrollToPrompt(id: string) {
+  const viewport = document.querySelector<HTMLElement>(VIEWPORT)
+  const node = viewport?.querySelector<HTMLElement>(`[data-message-id="${CSS.escape(id)}"]`)
+
+  if (!viewport || !node) {
+    return
+  }
+
+  const top = viewport.scrollTop + (node.getBoundingClientRect().top - viewport.getBoundingClientRect().top) - 8
+
+  triggerHaptic('selection')
+  viewport.scrollTo({ behavior: 'smooth', top: Math.max(0, top) })
+}
+
+/** Right-edge prompt rail — hover previews, click to jump. ≥4 user turns only. */
+export const ThreadTimeline: FC = () => {
+  const sourceSignature = useAuiState(s => {
+    const rows: TimelineSourceMessage[] = []
+
+    for (const message of s.thread.messages) {
+      if (message.role !== 'user') {
+        continue
+      }
+
+      rows.push({ id: message.id, role: 'user', text: userPromptText(message.content) })
+    }
+
+    return JSON.stringify(rows)
+  })
+
+  const entries = useMemo(
+    () => deriveTimelineEntries(JSON.parse(sourceSignature) as TimelineSourceMessage[]),
+    [sourceSignature]
+  )
+
+  const [activeIndex, setActiveIndex] = useState(0)
+  const [hoverIndex, setHoverIndex] = useState<number | null>(null)
+  const [open, setOpen] = useState(false)
+  const closeTimerRef = useRef<number | undefined>(undefined)
+
+  const keepOpen = useCallback(() => {
+    window.clearTimeout(closeTimerRef.current)
+    setPaneHoverRevealSuppressed(true)
+    setOpen(true)
+  }, [])
+
+  const closeSoon = useCallback(() => {
+    window.clearTimeout(closeTimerRef.current)
+    setHoverIndex(null)
+    setPaneHoverRevealSuppressed(false)
+    closeTimerRef.current = window.setTimeout(() => setOpen(false), HOVER_CLOSE_MS)
+  }, [])
+
+  useEffect(
+    () => () => {
+      window.clearTimeout(closeTimerRef.current)
+      setPaneHoverRevealSuppressed(false)
+    },
+    []
+  )
+
+  useEffect(() => {
+    if (entries.length < MIN_ENTRIES) {
+      setPaneHoverRevealSuppressed(false)
+    }
+  }, [entries.length])
+
+  useEffect(() => {
+    const viewport = document.querySelector<HTMLElement>(VIEWPORT)
+
+    if (!viewport || entries.length === 0) {
+      return
+    }
+
+    let raf = 0
+
+    const compute = () => {
+      raf = 0
+
+      const top = viewport.getBoundingClientRect().top
+
+      const offsets = entries.map(entry => {
+        const node = viewport.querySelector<HTMLElement>(`[data-message-id="${CSS.escape(entry.id)}"]`)
+
+        return node ? node.getBoundingClientRect().top - top : null
+      })
+
+      const next = activeTimelineIndex(offsets)
+
+      setActiveIndex(prev => (prev === next ? prev : next))
+    }
+
+    const onScroll = () => {
+      if (!raf) {
+        raf = requestAnimationFrame(compute)
+      }
+    }
+
+    compute()
+    viewport.addEventListener('scroll', onScroll, { passive: true })
+
+    return () => {
+      viewport.removeEventListener('scroll', onScroll)
+
+      if (raf) {
+        cancelAnimationFrame(raf)
+      }
+    }
+  }, [entries])
+
+  if (entries.length < MIN_ENTRIES) {
+    return null
+  }
+
+  return (
+    <div
+      aria-label="Conversation timeline"
+      className="group/timeline pointer-events-auto absolute right-0 top-1/2 z-40 flex -translate-y-1/2 flex-col items-end"
+      data-slot="thread-timeline"
+      onMouseEnter={keepOpen}
+      onMouseLeave={closeSoon}
+      role="navigation"
+    >
+      <TimelineTicks
+        activeIndex={activeIndex}
+        entries={entries}
+        onHover={setHoverIndex}
+        onJump={scrollToPrompt}
+      />
+      <TimelinePopover
+        activeIndex={activeIndex}
+        entries={entries}
+        hoverIndex={hoverIndex}
+        onHover={setHoverIndex}
+        onJump={scrollToPrompt}
+        open={open}
+      />
+    </div>
+  )
+}
+
+const TimelinePopover: FC<{
+  activeIndex: number
+  entries: TimelineEntry[]
+  hoverIndex: number | null
+  onHover: (index: number) => void
+  onJump: (id: string) => void
+  open: boolean
+}> = ({ activeIndex, entries, hoverIndex, onHover, onJump, open }) => (
+  <div
+    className={cn(
+      POPOVER_SHELL,
+      open ? 'pointer-events-auto opacity-100 translate-x-0' : 'pointer-events-none translate-x-1 opacity-0'
+    )}
+    data-slot="thread-timeline-popover"
+  >
+    {entries.map((entry, index) => {
+      const hovered = index === hoverIndex
+      const active = index === activeIndex
+
+      return (
+        <button
+          aria-label={entry.preview}
+          className={cn(
+            ROW_CLASS,
+            active && 'bg-(--ui-row-active-background) text-foreground',
+            hovered && 'bg-(--ui-row-hover-background) text-foreground transition-none'
+          )}
+          key={entry.id}
+          onClick={() => onJump(entry.id)}
+          onMouseEnter={() => onHover(index)}
+          type="button"
+        >
+          <span className="block w-full min-w-0 truncate font-medium leading-snug text-foreground">
+            {entry.preview}
+          </span>
+        </button>
+      )
+    })}
+  </div>
+)
+
+const TimelineTicks: FC<{
+  activeIndex: number
+  entries: TimelineEntry[]
+  onHover: (index: number) => void
+  onJump: (id: string) => void
+}> = ({ activeIndex, entries, onHover, onJump }) => (
+  <div className="flex flex-col items-end py-1" data-slot="thread-timeline-ticks">
+    {entries.map((entry, index) => (
+      <button
+        aria-label={entry.preview}
+        className="group/tick flex h-2 w-7 cursor-pointer items-center justify-end pr-1"
+        key={entry.id}
+        onClick={() => onJump(entry.id)}
+        onMouseEnter={() => onHover(index)}
+        type="button"
+      >
+        <span
+          className={cn(
+            'block h-px w-3 transition-opacity duration-100 ease-out',
+            index === activeIndex
+              ? 'bg-(--theme-primary)'
+              : 'dither text-(--ui-text-quaternary) opacity-70 group-hover/tick:opacity-100 group-hover/tick:transition-none'
+          )}
+        />
+      </button>
+    ))}
+  </div>
+)

apps/desktop/src/components/assistant-ui/thread.tsx

@@ -64,6 +64,7 @@ import { ClarifyTool } from '@/components/assistant-ui/clarify-tool'
 import { DirectiveContent, hermesDirectiveFormatter } from '@/components/assistant-ui/directive-text'
 import { MarkdownText, MarkdownTextContent } from '@/components/assistant-ui/markdown-text'
 import { ThreadMessageList } from '@/components/assistant-ui/thread-list'
+import { ThreadTimeline } from '@/components/assistant-ui/thread-timeline'
 import { ToolFallback, ToolGroupSlot } from '@/components/assistant-ui/tool-fallback'
 import { TooltipIconButton } from '@/components/assistant-ui/tooltip-icon-button'
 import { UserMessageText } from '@/components/assistant-ui/user-message-text'
@@ -212,6 +213,7 @@ export const Thread: FC<{
         sessionKey={sessionKey}
       />
       {loading === 'session' && <CenteredThreadSpinner />}
+      <ThreadTimeline />
     </div>
   )
 }
@@ -797,7 +799,15 @@ function messageAttachmentRefs(value: unknown): string[] {
   return value.every(ref => typeof ref === 'string') ? value : EMPTY_ATTACHMENT_REFS
 }
 
-function StickyHumanMessageContainer({ attachments, children }: { attachments?: ReactNode; children: ReactNode }) {
+function StickyHumanMessageContainer({
+  attachments,
+  children,
+  messageId
+}: {
+  attachments?: ReactNode
+  children: ReactNode
+  messageId?: string
+}) {
   return (
     // Fragment, not a wrapper: a wrapping element becomes the sticky's
     // containing block (it'd stick within its own height = never). The bubble
@@ -806,6 +816,7 @@ function StickyHumanMessageContainer({ attachments, children }: { attachments?:
     <>
       <div
         className="group/user-message sticky z-40 -mx-4 flex w-[calc(100%+2rem)] min-w-0 max-w-none flex-col items-stretch gap-0 self-end overflow-visible bg-(--ui-chat-surface-background) px-4 pb-(--conversation-turn-gap) pt-1"
+        data-message-id={messageId}
         data-role="user"
         data-slot="aui_user-message-root"
       >
@@ -990,6 +1001,7 @@ const UserMessage: FC<{
   return (
     <MessagePrimitive.Root asChild>
       <StickyHumanMessageContainer
+        messageId={messageId}
         attachments={
           // Attachments live BELOW the sticky bubble in normal flow, so they
           // scroll away behind the pinned bubble instead of riding along with

apps/desktop/src/components/assistant-ui/tool-fallback.tsx

@@ -2,7 +2,7 @@
 
 import { type ToolCallMessagePartProps, useAuiState } from '@assistant-ui/react'
 import { useStore } from '@nanostores/react'
-import { createContext, type FC, type PropsWithChildren, type ReactNode, useContext, useMemo } from 'react'
+import { createContext, type FC, type PropsWithChildren, type ReactNode, useContext, useEffect, useMemo } from 'react'
 
 import { AnsiText } from '@/components/assistant-ui/ansi-text'
 import { useElapsedSeconds } from '@/components/chat/activity-timer'
@@ -10,7 +10,6 @@ import { ActivityTimerText } from '@/components/chat/activity-timer-text'
 import { CompactMarkdown } from '@/components/chat/compact-markdown'
 import { FileDiffPanel } from '@/components/chat/diff-lines'
 import { DisclosureRow } from '@/components/chat/disclosure-row'
-import { PreviewAttachment } from '@/components/chat/preview-attachment'
 import { ZoomableImage } from '@/components/chat/zoomable-image'
 import { Button } from '@/components/ui/button'
 import { Codicon } from '@/components/ui/codicon'
@@ -25,6 +24,8 @@ import { PrettyLink, LinkifiedText as SharedLinkifiedText, urlSlugTitleLabel } f
 import { AlertCircle, CheckCircle2 } from '@/lib/icons'
 import { useEnterAnimation } from '@/lib/use-enter-animation'
 import { cn } from '@/lib/utils'
+import { recordPreviewArtifact } from '@/store/preview-status'
+import { $activeSessionId, $currentCwd } from '@/store/session'
 import { $toolInlineDiffs } from '@/store/tool-diffs'
 import { $toolRowDismissed, dismissToolRow } from '@/store/tool-dismiss'
 import { $toolDisclosureOpen, $toolViewMode, setToolDisclosureOpen } from '@/store/tool-view'
@@ -76,6 +77,8 @@ const TOOL_SECTION_LABEL_CLASS = 'mb-1 text-[0.65rem] font-medium uppercase trac
 const TOOL_SECTION_SURFACE_CLASS =
   'max-h-20 max-w-full overflow-auto bg-transparent px-2 py-1.5 text-(--ui-text-secondary)'
 
+const TOOL_EXPANDED_SHELL_CLASS = 'rounded-[0.3125rem] border border-(--ui-stroke-tertiary)'
+
 const TOOL_SECTION_PRE_CLASS = cn(TOOL_SECTION_SURFACE_CLASS, 'font-mono text-[0.7rem] leading-relaxed')
 
 interface ToolStatusCopy {
@@ -242,6 +245,22 @@ function ToolEntry({ part }: ToolEntryProps) {
     return buildToolView(p, inlineDiff)
   }, [inlineDiff, isPending, part])
 
+  // Surface a previewable artifact (HTML file / localhost URL) as a compact link
+  // in the composer status stack rather than a bulky inline card. Uses the same
+  // detected target the old inline card did, keyed to the active session the
+  // stack reads from. Idempotent + dedup'd, so re-renders don't churn.
+  const activeSessionId = useStore($activeSessionId)
+  const currentCwd = useStore($currentCwd)
+  const previewTarget = view.previewTarget
+
+  useEffect(() => {
+    if (isPending || !activeSessionId || !previewTarget || !isPreviewableTarget(previewTarget)) {
+      return
+    }
+
+    recordPreviewArtifact(activeSessionId, previewTarget, currentCwd || '')
+  }, [activeSessionId, currentCwd, isPending, previewTarget])
+
   const detailSections = useMemo(() => {
     if (!view.detail) {
       return { body: '', summary: '' }
@@ -291,12 +310,7 @@ function ToolEntry({ part }: ToolEntryProps) {
     Boolean(view.rawResult.trim())
 
   const hasExpandableContent = Boolean(
-    (view.previewTarget && isPreviewableTarget(view.previewTarget)) ||
-    view.imageUrl ||
-    view.inlineDiff ||
-    showDetail ||
-    hasSearchHits ||
-    toolViewMode === 'technical'
+    view.imageUrl || view.inlineDiff || showDetail || hasSearchHits || toolViewMode === 'technical'
   )
 
   const copyAction = useMemo(() => toolCopyPayload(part, view), [part, view])
@@ -360,7 +374,7 @@ function ToolEntry({ part }: ToolEntryProps) {
     <div
       className={cn(
         'min-w-0 max-w-full overflow-hidden text-[length:var(--conversation-tool-font-size)] text-(--ui-text-tertiary)',
-        open && 'rounded-[0.625rem] border border-(--ui-stroke-tertiary)'
+        open && TOOL_EXPANDED_SHELL_CLASS
       )}
       data-file-edit={isFileEdit && open ? '' : undefined}
       data-slot="tool-block"
@@ -425,9 +439,6 @@ function ToolEntry({ part }: ToolEntryProps) {
               text={copyAction.text}
             />
           )}
-          {!embedded && view.previewTarget && isPreviewableTarget(view.previewTarget) && (
-            <PreviewAttachment source="tool-result" target={view.previewTarget} />
-          )}
           {view.imageUrl && (
             <div className="max-w-72 overflow-hidden rounded-[0.25rem] border border-(--ui-stroke-tertiary)">
               <ZoomableImage alt={copy.outputAlt} className="h-auto w-full object-cover" src={view.imageUrl} />

apps/desktop/src/components/chat/preview-attachment.tsx

@@ -104,16 +104,15 @@ export function PreviewAttachment({ source = 'manual', target }: { source?: Prev
   }
 
   return (
-    <div className="flex w-full max-w-160 flex-wrap items-center gap-2.5 rounded-lg border border-border/55 bg-card/55 px-2.5 py-1.5 text-sm">
-      <span className="grid size-7 shrink-0 place-items-center rounded-md bg-muted/55 text-muted-foreground/85">
+    <div className="flex w-full max-w-160 items-center gap-2 rounded-lg border border-border/55 bg-card/55 px-2.5 py-1.5 text-sm">
+      <span className="grid size-6 shrink-0 place-items-center rounded-md bg-muted/55 text-muted-foreground/85">
         <MonitorPlay className="size-3.5" />
       </span>
-      <div className="min-w-0 flex-1">
-        <div className="truncate text-[0.78rem] font-medium leading-[1.15rem] text-foreground/90">{name}</div>
-        <div className="truncate font-mono text-[0.66rem] leading-4 text-muted-foreground/70">{target}</div>
-      </div>
+      <span className="min-w-0 flex-1 truncate text-[0.78rem] font-medium text-foreground/90" title={target}>
+        {name}
+      </span>
       <button
-        className="ml-auto shrink-0 rounded-md border border-border/55 bg-background/40 px-2 py-1 text-[0.7rem] font-medium text-muted-foreground transition-colors hover:bg-accent/55 hover:text-foreground disabled:opacity-50 max-[28rem]:ml-9 max-[28rem]:w-[calc(100%-2.25rem)]"
+        className="shrink-0 rounded-md border border-border/55 bg-background/40 px-2 py-1 text-[0.7rem] font-medium text-muted-foreground transition-colors hover:bg-accent/55 hover:text-foreground disabled:opacity-50"
         disabled={opening}
         onClick={() => void togglePreview()}
         type="button"

apps/desktop/src/components/pane-shell/pane-shell.tsx

@@ -15,7 +15,7 @@ import {
 } from 'react'
 
 import { cn } from '@/lib/utils'
-import { $paneStates, ensurePaneRegistered, setPaneWidthOverride } from '@/store/panes'
+import { $paneHoverRevealSuppressed, $paneStates, ensurePaneRegistered, setPaneWidthOverride } from '@/store/panes'
 
 import { PaneShellContext, type PaneShellContextValue, type PaneSlot } from './context'
 
@@ -250,6 +250,7 @@ export function Pane({
 }: PaneProps) {
   const ctx = useContext(PaneShellContext)
   const paneStates = useStore($paneStates)
+  const hoverRevealSuppressed = useStore($paneHoverRevealSuppressed)
   const registered = useRef(false)
   const paneRef = useRef<HTMLDivElement | null>(null)
   // Keyboard (mod+b / mod+j) pins the reveal open while collapsed; hover is CSS.
@@ -378,7 +379,10 @@ export function Pane({
       >
         <div
           aria-hidden="true"
-          className="pointer-events-auto absolute inset-y-0 z-30 [-webkit-app-region:no-drag]"
+          className={cn(
+            'absolute inset-y-0 z-30 [-webkit-app-region:no-drag]',
+            hoverRevealSuppressed ? 'pointer-events-none' : 'pointer-events-auto'
+          )}
           style={{ [edge]: HOVER_REVEAL_EDGE_GUTTER, width: HOVER_REVEAL_TRIGGER_WIDTH }}
         />
 
@@ -388,7 +392,8 @@ export function Pane({
           className={cn(
             'pointer-events-none absolute inset-y-0 z-30 overflow-hidden transition-transform delay-0',
             offscreen,
-            'group-hover/reveal:pointer-events-auto group-hover/reveal:translate-x-0 group-hover/reveal:delay-[var(--reveal-enter-delay)] group-hover/reveal:shadow-[var(--reveal-shadow)]',
+            !hoverRevealSuppressed &&
+              'group-hover/reveal:pointer-events-auto group-hover/reveal:translate-x-0 group-hover/reveal:delay-[var(--reveal-enter-delay)] group-hover/reveal:shadow-[var(--reveal-shadow)]',
             'group-data-[forced]/reveal:pointer-events-auto group-data-[forced]/reveal:translate-x-0 group-data-[forced]/reveal:delay-0 group-data-[forced]/reveal:shadow-[var(--reveal-shadow)]'
           )}
           key={edge}

apps/desktop/src/components/pet/floating-pet.tsx

@@ -0,0 +1,313 @@
+import { useStore } from '@nanostores/react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { useGatewayRequest } from '@/app/gateway/hooks/use-gateway-request'
+import { persistString, storedString } from '@/lib/storage'
+import { $petInfo, clearPetUnread, type PetInfo, petProfile, setPetInfo } from '@/store/pet'
+import { resetPetGallery } from '@/store/pet-gallery'
+import { $petOverlayActive, initPetOverlayBridge, popOutPet, restorePetOverlay } from '@/store/pet-overlay'
+import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
+import { $gatewayState } from '@/store/session'
+import { isSecondaryWindow } from '@/store/windows'
+import { useTheme } from '@/themes/context'
+
+import { PetSprite } from './pet-sprite'
+
+// v2: positions are now top/left anchored (v1 stored bottom-anchored values,
+// which dragged inverted). Bumping the key discards stale v1 coordinates.
+const POSITION_KEY = 'hermes.desktop.pet-position.v2'
+
+interface Point {
+  x: number
+  y: number
+}
+
+function clampToViewport({ x, y }: Point): Point {
+  const maxX = Math.max(0, (window.innerWidth || 800) - 80)
+  const maxY = Math.max(0, (window.innerHeight || 600) - 80)
+
+  return { x: Math.min(Math.max(0, x), maxX), y: Math.min(Math.max(0, y), maxY) }
+}
+
+// The sprite art faces left by default, so mirror it when the pet's center sits
+// on the left half of the window — it always faces inward, toward the content.
+function facing(leftX: number, petW: number): string {
+  return leftX + petW / 2 < (window.innerWidth || 800) / 2 ? 'scaleX(-1)' : 'none'
+}
+
+function loadPosition(): Point {
+  try {
+    const raw = storedString(POSITION_KEY)
+
+    if (raw) {
+      const parsed = JSON.parse(raw) as Point
+
+      if (typeof parsed.x === 'number' && typeof parsed.y === 'number') {
+        return clampToViewport(parsed)
+      }
+    }
+  } catch {
+    // fall through to default
+  }
+
+  // Default: lower-left corner (top/left anchored).
+  return clampToViewport({ x: 24, y: (window.innerHeight || 600) - 220 })
+}
+
+/**
+ * In-window floating petdex mascot. Always-on-top within the app, draggable,
+ * and reactive to agent activity via `$petState`. Fetches the active pet via
+ * the shared `pet.info` RPC; renders nothing until a pet is installed +
+ * enabled.
+ *
+ * Adopting a pet is fully in-app: type `/pet boba` in the composer. That
+ * writes `display.pet.*` from the slash worker, so we keep polling `pet.info`
+ * while no pet is active and the mascot pops in within a few seconds — no
+ * reload, no CLI. Once a pet is live we stop polling.
+ *
+ * Promotion to a separate frameless OS-level window is a follow-up — the
+ * sprite + state logic here is reused as-is, only the host changes.
+ */
+const PET_POLL_MS = 3000
+
+export function FloatingPet() {
+  const { requestGateway } = useGatewayRequest()
+  const { resolvedMode } = useTheme()
+  const gatewayState = useStore($gatewayState)
+  const info = useStore($petInfo)
+  const overlayActive = useStore($petOverlayActive)
+
+  const [position, setPosition] = useState<Point>(loadPosition)
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  // The facing mirror lives on the sprite wrapper, not the container, so the
+  // speech bubble (a container child) never renders flipped/backwards.
+  const spriteWrapRef = useRef<HTMLDivElement | null>(null)
+  const petW = (info.frameW ?? 192) * (info.scale ?? 0.33)
+  // Soft contact shadow, sized off the pet so every scale/species grounds the
+  // same way (cf. lairp's per-actor feet ellipse). Lighter on light backgrounds.
+  const shadowW = Math.round(petW * 0.55)
+  const shadowH = Math.max(3, Math.round(shadowW * 0.28))
+  const shadowAlpha = resolvedMode === 'light' ? 0.2 : 0.55
+  // Live drag offset (pointer → element top-left). Drag updates the DOM
+  // directly to avoid a React re-render (and canvas reflow) per pointermove —
+  // state is only committed on release.
+  const dragRef = useRef<{ dx: number; dy: number; x: number; y: number } | null>(null)
+
+  // Fetch pet.info on connect, then keep polling while no pet is active so an
+  // in-app `/pet <slug>` shows up live. Stops polling once a pet is enabled.
+  const active = info.enabled && Boolean(info.spritesheetBase64)
+  useEffect(() => {
+    if (gatewayState !== 'open' || active) {
+      return
+    }
+
+    let cancelled = false
+
+    const pull = async () => {
+      try {
+        const next = await requestGateway<PetInfo>('pet.info', { profile: petProfile() })
+
+        if (!cancelled && next) {
+          setPetInfo(next)
+        }
+      } catch {
+        // cosmetic feature — never surface gateway errors
+      }
+    }
+
+    void pull()
+    const timer = window.setInterval(() => void pull(), PET_POLL_MS)
+
+    return () => {
+      cancelled = true
+      window.clearInterval(timer)
+    }
+  }, [gatewayState, active, requestGateway])
+
+  // Pets are per-profile. When the active profile changes, drop the previous
+  // profile's mascot + gallery cache so the poll above refetches the new
+  // profile's pet (its config + pets dir resolve per-profile on the backend).
+  const profileRef = useRef(normalizeProfileKey($activeGatewayProfile.get()))
+  useEffect(
+    () =>
+      $activeGatewayProfile.subscribe(next => {
+        const key = normalizeProfileKey(next)
+
+        if (key === profileRef.current) {
+          return
+        }
+
+        profileRef.current = key
+        setPetInfo({ enabled: false })
+        resetPetGallery()
+      }),
+    []
+  )
+
+  // Wire the overlay control channel once, only in the primary window — the
+  // pop-out overlay belongs to it (main.cjs positions it against the main
+  // window and routes control messages back to it).
+  useEffect(() => {
+    if (isSecondaryWindow()) {
+      return
+    }
+
+    return initPetOverlayBridge()
+  }, [])
+
+  // Returning to the app (by any route, not just the mail icon) clears the pet's
+  // "new message" hint — you've seen it now.
+  useEffect(() => {
+    if (isSecondaryWindow()) {
+      return
+    }
+
+    const onFocus = () => clearPetUnread()
+    window.addEventListener('focus', onFocus)
+
+    return () => window.removeEventListener('focus', onFocus)
+  }, [])
+
+  // Restore a popped-out pet on boot, once the pet has loaded (so we never spawn
+  // an empty overlay window). Primary window only; runs at most once.
+  const restoredRef = useRef(false)
+  useEffect(() => {
+    if (isSecondaryWindow() || restoredRef.current || !active) {
+      return
+    }
+
+    restoredRef.current = true
+    restorePetOverlay()
+  }, [active])
+
+  // A window resize must never strand the pet off-screen — re-clamp the
+  // committed position (and persist it) whenever the viewport shrinks.
+  useEffect(() => {
+    const onResize = () =>
+      setPosition(prev => {
+        const next = clampToViewport(prev)
+
+        if (next.x === prev.x && next.y === prev.y) {
+          return prev
+        }
+
+        persistString(POSITION_KEY, JSON.stringify(next))
+
+        return next
+      })
+
+    window.addEventListener('resize', onResize)
+
+    return () => window.removeEventListener('resize', onResize)
+  }, [])
+
+  const onPointerDown = useCallback((e: React.PointerEvent) => {
+    const el = containerRef.current
+
+    if (!el) {
+      return
+    }
+
+    const rect = el.getBoundingClientRect()
+
+    // Shift-click pops the pet out into a free-floating desktop overlay (it can
+    // leave the window and stays visible while Hermes is minimized) instead of
+    // starting an in-window drag. Primary window only — the overlay is anchored
+    // to it.
+    if (e.shiftKey && !isSecondaryWindow()) {
+      popOutPet({ height: rect.height, width: rect.width, x: rect.left, y: rect.top })
+
+      return
+    }
+
+    dragRef.current = { dx: e.clientX - rect.left, dy: e.clientY - rect.top, x: rect.left, y: rect.top }
+    el.setPointerCapture(e.pointerId)
+    el.style.cursor = 'grabbing'
+  }, [])
+
+  const onPointerMove = useCallback(
+    (e: React.PointerEvent) => {
+      const drag = dragRef.current
+      const el = containerRef.current
+
+      if (!drag || !el) {
+        return
+      }
+
+      const next = clampToViewport({ x: e.clientX - drag.dx, y: e.clientY - drag.dy })
+      drag.x = next.x
+      drag.y = next.y
+      // Mutate the DOM directly — no setState, so no re-render while dragging. The
+      // mirror follows the pointer across the midline for the same reason; it
+      // rides the sprite wrapper so the bubble stays upright.
+      el.style.left = `${next.x}px`
+      el.style.top = `${next.y}px`
+
+      if (spriteWrapRef.current) {
+        spriteWrapRef.current.style.transform = facing(next.x, petW)
+      }
+    },
+    [petW]
+  )
+
+  const onPointerUp = useCallback((e: React.PointerEvent) => {
+    const drag = dragRef.current
+
+    if (drag) {
+      dragRef.current = null
+      const committed = { x: drag.x, y: drag.y }
+      setPosition(committed)
+      persistString(POSITION_KEY, JSON.stringify(committed))
+    }
+
+    const el = containerRef.current
+
+    if (el) {
+      el.style.cursor = 'grab'
+      el.releasePointerCapture?.(e.pointerId)
+    }
+  }, [])
+
+  // While popped out, the desktop overlay window owns the mascot — hide the
+  // in-window one so there aren't two.
+  if (!info.enabled || !info.spritesheetBase64 || overlayActive) {
+    return null
+  }
+
+  return (
+    <div
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={onPointerUp}
+      ref={containerRef}
+      style={{
+        cursor: 'grab',
+        left: position.x,
+        pointerEvents: 'auto',
+        position: 'fixed',
+        top: position.y,
+        touchAction: 'none',
+        userSelect: 'none',
+        zIndex: 60
+      }}
+    >
+      <div
+        aria-hidden
+        style={{
+          background: `radial-gradient(ellipse at center, rgba(0,0,0,${shadowAlpha}) 0%, rgba(0,0,0,0) 70%)`,
+          bottom: -shadowH * 0.4,
+          height: shadowH,
+          left: '50%',
+          pointerEvents: 'none',
+          position: 'absolute',
+          transform: 'translateX(-50%)',
+          width: shadowW,
+          zIndex: 0
+        }}
+      />
+      <div ref={spriteWrapRef} style={{ lineHeight: 0, position: 'relative', transform: facing(position.x, petW), zIndex: 1 }}>
+        <PetSprite info={info} />
+      </div>
+    </div>
+  )
+}

apps/desktop/src/components/pet/pet-bubble.tsx

@@ -0,0 +1,142 @@
+import { useStore } from '@nanostores/react'
+import { useEffect, useState } from 'react'
+
+import { AlertCircle, Clock, type IconComponent } from '@/lib/icons'
+import { $petActivity, $petState, type PetState } from '@/store/pet'
+
+/**
+ * Speech bubble + status glyph for the popped-out pet overlay — the
+ * "notification" half of the mascot. It externalizes what the agent is doing
+ * (Codex-style) so a glance at the desktop pet replaces switching back to the
+ * window. The in-window pet doesn't show it (the app itself is the surface);
+ * only the overlay renders it.
+ *
+ * Text is derived purely from the same `$petState` / `$petActivity` the sprite
+ * already reacts to, so it never drifts from the animation. The bubble is shown
+ * only when there's something worth saying (working / reviewing / a transient
+ * done/error beat / waiting on the user) and is hidden at plain idle.
+ */
+
+type Tone = 'error' | 'wait'
+
+interface Spec {
+  lines: string[]
+  glyph?: IconComponent
+  tone?: Tone
+}
+
+// Phrasings per mood, picked at random (no immediate repeat) for a bit of life.
+// Keep them short — the bubble is tiny and never wraps.
+const SPECS: Partial<Record<PetState, Spec>> = {
+  run: {
+    lines: ['working…', 'on it…', 'crunching…', 'tinkering…', 'cooking…', 'in the weeds…', 'wiring it up…', 'making moves…', 'heads down…', 'hammering away…']
+  },
+  review: {
+    lines: ['thinking…', 'reading…', 'reviewing…', 'pondering…', 'connecting dots…', 'sizing it up…', 'tracing it…', 'mulling…', 'scheming…', 'hmm…']
+  },
+  failed: {
+    glyph: AlertCircle,
+    lines: ['hit a snag', 'welp', 'that broke', 'oof', 'snagged'],
+    tone: 'error'
+  },
+  waiting: {
+    glyph: Clock,
+    lines: ['your turn', 'all yours', 'over to you', 'ball’s in your court', 'awaiting orders'],
+    tone: 'wait'
+  }
+}
+
+const TONE_COLOR: Record<Tone, string> = {
+  error: 'var(--ui-red)',
+  wait: 'var(--ui-yellow)'
+}
+
+// Random pick that avoids repeating the line we're already showing.
+function pick(lines: string[], prev: string): string {
+  if (lines.length <= 1) {
+    return lines[0] ?? ''
+  }
+
+  let next = prev
+
+  while (next === prev) {
+    next = lines[Math.floor(Math.random() * lines.length)]
+  }
+
+  return next
+}
+
+export function PetBubble() {
+  const state = useStore($petState)
+  const activity = useStore($petActivity)
+  const [line, setLine] = useState('')
+
+  // Finish beats are carried by the sprite/mail icon; idle only speaks up when
+  // it's actually the user's turn. Everything else maps to a mood spec.
+  const specKey: null | PetState =
+    state in SPECS ? state : state === 'idle' && activity.awaitingInput ? 'waiting' : null
+  const rotating = specKey === 'run' || specKey === 'review'
+
+  // Pick a fresh line on every mood change, then keep rotating (random, no
+  // repeat) only while the agent is actively working/thinking.
+  useEffect(() => {
+    const spec = specKey ? SPECS[specKey] : null
+
+    if (!spec) {
+      setLine('')
+
+      return
+    }
+
+    setLine(prev => pick(spec.lines, prev))
+
+    if (!rotating || spec.lines.length <= 1) {
+      return
+    }
+
+    const id = window.setInterval(() => setLine(prev => pick(spec.lines, prev)), 2600)
+
+    return () => window.clearInterval(id)
+  }, [specKey, rotating])
+
+  const spec = specKey ? SPECS[specKey] : null
+
+  if (!spec) {
+    return null
+  }
+
+  const Glyph = spec.glyph
+  const text = line || spec.lines[0]
+  const hasText = Boolean(text)
+
+  return (
+    <div
+      style={{
+        alignItems: 'center',
+        // Solid, theme-driven surface (the prior --ui-bg-card mixes in
+        // `transparent`, so the bubble was see-through).
+        background: 'var(--ui-bg-elevated)',
+        border: '1px solid var(--ui-stroke-secondary)',
+        borderRadius: hasText ? 10 : 999,
+        boxShadow: '0 4px 14px rgba(0,0,0,0.22)',
+        color: 'var(--foreground)',
+        display: 'inline-flex',
+        fontSize: 11,
+        fontWeight: 500,
+        gap: hasText ? 5 : 0,
+        lineHeight: 1,
+        // Glyph-only bubbles collapse to a tight, symmetric badge.
+        padding: hasText ? '5px 8px' : 5,
+        pointerEvents: 'none',
+        whiteSpace: 'nowrap'
+      }}
+    >
+      {Glyph && (
+        <span style={{ display: 'inline-flex' }}>
+          <Glyph style={{ color: spec.tone ? TONE_COLOR[spec.tone] : 'currentColor', height: 13, width: 13 }} />
+        </span>
+      )}
+      {text}
+    </div>
+  )
+}

apps/desktop/src/components/pet/pet-sprite.tsx

@@ -0,0 +1,178 @@
+import { memo, useEffect, useMemo, useRef } from 'react'
+
+import { $petState, type PetInfo, type PetState } from '@/store/pet'
+
+const DEFAULT_FRAME_W = 192
+const DEFAULT_FRAME_H = 208
+const DEFAULT_FRAMES = 6
+const DEFAULT_LOOP_MS = 1100
+// Mirrors agent.pet.constants.DEFAULT_SCALE — fallback only; the gateway sends
+// the configured scale.
+const DEFAULT_SCALE = 0.33
+// Mirrors agent.pet.constants.CODEX_STATE_ROWS (Petdex current taxonomy).
+const DEFAULT_STATE_ROWS = [
+  'idle',
+  'running-right',
+  'running-left',
+  'waving',
+  'jumping',
+  'failed',
+  'waiting',
+  'running',
+  'review'
+]
+
+const STATE_ALIASES: Record<PetState, string[]> = {
+  idle: ['idle'],
+  wave: ['wave', 'waving'],
+  jump: ['jump', 'jumping'],
+  run: ['run', 'running'],
+  failed: ['failed'],
+  review: ['review'],
+  waiting: ['waiting']
+}
+
+interface PetSpriteProps {
+  info: PetInfo
+  /** On-screen scale multiplier applied on top of the pet's native scale. */
+  zoom?: number
+}
+
+/**
+ * Canvas renderer for a petdex spritesheet — the one piece that must be
+ * TypeScript (the engine's decode/encode is Python). Draws the row matching the
+ * live `$petState`, stepping `framesPerState` frames across a `loopMs` loop.
+ *
+ * State is read from `$petState` via a ref + subscription rather than a prop,
+ * so the frequent activity-driven state changes during an agent turn update the
+ * canvas (inside its RAF loop) WITHOUT triggering a React re-render. Combined
+ * with `memo`, this component effectively never re-renders after mount until
+ * the pet itself changes.
+ */
+function PetSpriteImpl({ info, zoom = 1 }: PetSpriteProps) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null)
+  const stateRef = useRef<PetState>($petState.get())
+
+  const frameW = info.frameW ?? DEFAULT_FRAME_W
+  const frameH = info.frameH ?? DEFAULT_FRAME_H
+  const frames = info.framesPerState ?? DEFAULT_FRAMES
+  const framesByState = info.framesByState
+  const loopMs = info.loopMs ?? DEFAULT_LOOP_MS
+  const scale = (info.scale ?? DEFAULT_SCALE) * zoom
+  const rows = info.stateRows ?? DEFAULT_STATE_ROWS
+
+  const drawW = Math.round(frameW * scale)
+  const drawH = Math.round(frameH * scale)
+
+  const image = useMemo(() => {
+    if (!info.spritesheetBase64) {
+      return null
+    }
+
+    const img = new Image()
+    img.src = `data:${info.mime ?? 'image/webp'};base64,${info.spritesheetBase64}`
+
+    return img
+  }, [info.spritesheetBase64, info.mime])
+
+  useEffect(() => {
+    const canvas = canvasRef.current
+
+    if (!canvas || !image) {
+      return
+    }
+
+    const ctx = canvas.getContext('2d')
+
+    if (!ctx) {
+      return
+    }
+
+    // Track state via subscription, not a prop — no re-render on activity ticks.
+    stateRef.current = $petState.get()
+
+    const unsubState = $petState.listen(next => {
+      stateRef.current = next
+    })
+
+    let raf = 0
+    let frame = 0
+    let lastStep = performance.now()
+    let drawnFrame = -1
+    let drawnRow = -1
+
+    const rowIndexForState = (s: PetState): number => {
+      for (const key of STATE_ALIASES[s] ?? [s]) {
+        const idx = rows.indexOf(key)
+        if (idx >= 0) {
+          return idx
+        }
+      }
+      return 0
+    }
+
+    // Resolve a state to the row it draws and its real frame count. A state
+    // with no real frames (ragged sheet, empty row) falls back to idle rather
+    // than flashing blank padding.
+    const resolve = (s: PetState): { row: number; count: number } => {
+      const real = framesByState?.[s] ?? frames
+      if (real > 0) {
+        return { row: rowIndexForState(s), count: real }
+      }
+
+      return { row: rowIndexForState('idle'), count: Math.max(1, framesByState?.idle ?? frames) }
+    }
+
+    const render = (now: number) => {
+      const { row, count } = resolve(stateRef.current)
+      // Per-state step keeps every state's loop ~loopMs even when frame counts
+      // differ; counts vary per row so derive the cadence here, not once.
+      const stepMs = loopMs / count
+
+      if (now - lastStep >= stepMs) {
+        frame += 1
+        lastStep = now
+      }
+
+      frame %= count
+
+      // Only touch the canvas when the visible cell actually changes. The RAF
+      // ticks at ~60Hz but the sprite only steps ~5Hz, so this skips ~90% of
+      // the clear+draw work and keeps the main thread free.
+      if ((frame !== drawnFrame || row !== drawnRow) && image.complete && image.naturalWidth > 0) {
+        const sx = frame * frameW
+        const sy = row * frameH
+        ctx.clearRect(0, 0, canvas.width, canvas.height)
+        ctx.imageSmoothingEnabled = false
+        ctx.drawImage(image, sx, sy, frameW, frameH, 0, 0, drawW, drawH)
+        drawnFrame = frame
+        drawnRow = row
+      }
+
+      raf = requestAnimationFrame(render)
+    }
+
+    raf = requestAnimationFrame(render)
+
+    return () => {
+      cancelAnimationFrame(raf)
+      unsubState()
+    }
+  }, [image, frameW, frameH, frames, framesByState, loopMs, drawW, drawH, rows])
+
+  return (
+    <canvas
+      aria-label={info.displayName ? `${info.displayName} pet` : 'pet'}
+      height={drawH}
+      ref={canvasRef}
+      style={{ height: drawH, width: drawW }}
+      width={drawW}
+    />
+  )
+}
+
+/**
+ * Memoized so a parent re-render (e.g. a position commit on drag-end) doesn't
+ * re-run the canvas setup. Props change only when the pet itself changes.
+ */
+export const PetSprite = memo(PetSpriteImpl)

apps/desktop/src/components/pet/pet-thumb.tsx

@@ -0,0 +1,79 @@
+import { useEffect, useRef, useState } from 'react'
+
+import { PawPrint } from '@/lib/icons'
+
+// petdex frames are a fixed 192×208 grid; the box matches that aspect.
+const THUMB_W = 40
+const THUMB_H = Math.round((THUMB_W * 208) / 192)
+
+export type PetThumbLoader = (slug: string, url?: string) => Promise<string | null>
+
+/**
+ * Idle-frame preview for one pet. The backend crops + caches the frame and
+ * returns it as a same-origin data URI (`pet.thumb`), which dodges the renderer
+ * CSP / R2 hotlink rules that break a direct `<img src=cdn>`.
+ */
+export function PetThumb({
+  slug,
+  url,
+  alt,
+  load,
+  size = THUMB_W
+}: {
+  slug: string
+  url?: string
+  alt: string
+  load: PetThumbLoader
+  /** Width in px; height follows the petdex frame aspect. */
+  size?: number
+}) {
+  const [src, setSrc] = useState<string | null>(null)
+  const boxRef = useRef<HTMLSpanElement | null>(null)
+  const height = Math.round((size * 208) / 192)
+
+  useEffect(() => {
+    const el = boxRef.current
+
+    if (!el || src) {
+      return
+    }
+
+    const observer = new IntersectionObserver(
+      entries => {
+        if (entries.some(entry => entry.isIntersecting)) {
+          observer.disconnect()
+          void load(slug, url).then(uri => {
+            if (uri) {
+              setSrc(uri)
+            }
+          })
+        }
+      },
+      { rootMargin: '120px' }
+    )
+
+    observer.observe(el)
+
+    return () => observer.disconnect()
+  }, [slug, url, src, load])
+
+  return (
+    <span
+      className="grid shrink-0 place-items-center overflow-hidden rounded-md bg-(--ui-bg-tertiary) text-(--ui-text-tertiary)"
+      ref={boxRef}
+      style={{ height, width: size }}
+    >
+      {src ? (
+        <img
+          alt={alt}
+          aria-hidden
+          className="pointer-events-none size-full object-contain"
+          src={src}
+          style={{ imageRendering: 'pixelated' }}
+        />
+      ) : (
+        <PawPrint className="size-4" />
+      )}
+    </span>
+  )
+}

apps/desktop/src/components/ui/command.tsx

@@ -17,7 +17,12 @@ function Command({ className, ...props }: React.ComponentProps<typeof CommandPri
   )
 }
 
-function CommandInput({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Input>) {
+interface CommandInputProps extends React.ComponentProps<typeof CommandPrimitive.Input> {
+  /** Inline trailing slot, rendered on the right of the search row. */
+  right?: React.ReactNode
+}
+
+function CommandInput({ className, right, ...props }: CommandInputProps) {
   return (
     <div className="flex h-11 items-center gap-2 border-b border-border px-3" data-slot="command-input-wrapper">
       <SearchIcon className="size-4 shrink-0 text-muted-foreground" />
@@ -29,6 +34,7 @@ function CommandInput({ className, ...props }: React.ComponentProps<typeof Comma
         data-slot="command-input"
         {...props}
       />
+      {right}
     </div>
   )
 }

apps/desktop/src/global.d.ts

@@ -1,3 +1,10 @@
+import type {
+  PetOverlayBounds,
+  PetOverlayControl,
+  PetOverlayOpenRequest,
+  PetOverlayStatePayload
+} from './store/pet-overlay'
+
 export {}
 
 declare global {
@@ -26,6 +33,20 @@ declare global {
       openSessionWindow: (sessionId: string, opts?: { watch?: boolean }) => Promise<{ ok: boolean; error?: string }>
       // Open (or focus) a compact secondary window on the new-session draft.
       openNewSessionWindow: () => Promise<{ ok: boolean; error?: string }>
+      // The pop-out pet overlay: a transparent always-on-top window hosting only
+      // the mascot. The main renderer drives it (open/close/drag + state push);
+      // the overlay sends control messages back (pop-in, composer submit).
+      petOverlay: {
+        open: (request: PetOverlayOpenRequest) => Promise<{ ok: boolean; bounds?: PetOverlayBounds }>
+        close: () => Promise<{ ok: boolean }>
+        setBounds: (bounds: PetOverlayBounds) => void
+        setIgnoreMouse: (ignore: boolean) => void
+        setFocusable: (focusable: boolean) => void
+        pushState: (payload: PetOverlayStatePayload) => void
+        control: (payload: PetOverlayControl) => void
+        onState: (callback: (payload: PetOverlayStatePayload) => void) => () => void
+        onControl: (callback: (payload: PetOverlayControl) => void) => () => void
+      }
       getBootProgress: () => Promise<DesktopBootProgress>
       getConnectionConfig: (profile?: null | string) => Promise<DesktopConnectionConfig>
       saveConnectionConfig: (payload: DesktopConnectionConfigInput) => Promise<DesktopConnectionConfig>
@@ -60,6 +81,7 @@ declare global {
       setTranslucency?: (payload: { intensity: number }) => void
       setPreviewShortcutActive?: (active: boolean) => void
       openExternal: (url: string) => Promise<void>
+      openPreviewInBrowser?: (url: string) => Promise<void>
       fetchLinkTitle: (url: string) => Promise<string>
       sanitizeWorkspaceCwd: (cwd?: null | string) => Promise<{ cwd: string; sanitized: boolean }>
       settings: {

apps/desktop/src/hermes.ts

@@ -8,6 +8,7 @@ import type {
   AudioTranscriptionResponse,
   AuxiliaryModelsResponse,
   BackendUpdateCheckResponse,
+  ComputerUseStatus,
   ConfigSchemaResponse,
   CronJob,
   CronJobCreatePayload,
@@ -18,6 +19,7 @@ import type {
   HermesConfigRecord,
   LogsResponse,
   MemoryProviderConfig,
+  MemoryProviderOAuthStatus,
   MessagingPlatformsResponse,
   MessagingPlatformTestResponse,
   MessagingPlatformUpdate,
@@ -59,6 +61,9 @@ export type {
   AudioTranscriptionResponse,
   AuxiliaryModelsResponse,
   BackendUpdateCheckResponse,
+  ComputerUseCheck,
+  ComputerUsePermissionSource,
+  ComputerUseStatus,
   ConfigFieldSchema,
   ConfigSchemaResponse,
   CronJob,
@@ -73,6 +78,7 @@ export type {
   HermesConfigRecord,
   LogsResponse,
   MemoryProviderConfig,
+  MemoryProviderOAuthStatus,
   MessagingEnvVarInfo,
   MessagingHomeChannel,
   MessagingPlatformInfo,
@@ -453,6 +459,23 @@ export function cancelOAuthSession(sessionId: string): Promise<{ ok: boolean }>
   })
 }
 
+// Memory-provider OAuth connect (provider-keyed; 404s for providers without an
+// OAuth flow). Profile-scoped: the grant lands in the active profile's config.
+export function startMemoryProviderOAuth(provider: string): Promise<MemoryProviderOAuthStatus> {
+  return window.hermesDesktop.api<MemoryProviderOAuthStatus>({
+    ...profileScoped(),
+    path: `/api/memory/providers/${encodeURIComponent(provider)}/oauth/start`,
+    method: 'POST'
+  })
+}
+
+export function getMemoryProviderOAuthStatus(provider: string): Promise<MemoryProviderOAuthStatus> {
+  return window.hermesDesktop.api<MemoryProviderOAuthStatus>({
+    ...profileScoped(),
+    path: `/api/memory/providers/${encodeURIComponent(provider)}/oauth/status`
+  })
+}
+
 export function getSkills(): Promise<SkillInfo[]> {
   return window.hermesDesktop.api<SkillInfo[]>({
     ...profileScoped(),
@@ -516,6 +539,21 @@ export function runToolsetPostSetup(name: string, key: string): Promise<ActionRe
   })
 }
 
+export function getComputerUseStatus(): Promise<ComputerUseStatus> {
+  return window.hermesDesktop.api<ComputerUseStatus>({
+    ...profileScoped(),
+    path: '/api/tools/computer-use/status'
+  })
+}
+
+export function grantComputerUsePermissions(): Promise<ActionResponse> {
+  return window.hermesDesktop.api<ActionResponse>({
+    ...profileScoped(),
+    path: '/api/tools/computer-use/permissions/grant',
+    method: 'POST'
+  })
+}
+
 export function getMessagingPlatforms(): Promise<MessagingPlatformsResponse> {
   return window.hermesDesktop.api<MessagingPlatformsResponse>({
     path: '/api/messaging/platforms'

apps/desktop/src/i18n/en.ts

@@ -372,7 +372,32 @@ export const en: Translations = {
       installError: 'Could not install that theme.',
       installed: name => `Installed “${name}”.`,
       removeTheme: 'Remove theme',
-      importedBadge: 'Imported'
+      importedBadge: 'Imported',
+      pet: {
+        title: 'Pet',
+        intro:
+          'Adopt an animated petdex mascot that floats over the app and reacts to what Hermes is doing — running while tools execute, celebrating on success, sulking on errors.',
+        restartHint:
+          'Pets need a quick restart — the running app started before this feature was added. Quit and reopen Hermes, then come back here.',
+        on: 'On',
+        off: 'Off',
+        scaleTitle: 'Size',
+        scaleDesc: 'Resize the floating mascot. Applies everywhere instantly.',
+        chooseTitle: 'Choose a pet',
+        chooseDesc: 'Picking one installs it (if needed) and makes it active.',
+        searchPlaceholder: 'Search pets…',
+        unreachable: "Couldn't reach the petdex gallery. Check your connection and reopen this page.",
+        noMatch: query => `No pets match "${query}".`,
+        installedTag: 'installed',
+        countCapped: (cap, total) => `Showing ${cap} of ${total} — type to narrow it down.`,
+        count: n => `${n} pet${n === 1 ? '' : 's'}.`,
+        uninstall: name => `Uninstall ${name}`,
+        adoptFailed: slug => `Could not adopt ${slug}`,
+        uninstallFailed: slug => `Could not uninstall ${slug}`,
+        noneAvailable: 'No pets available to turn on right now.',
+        turnOnFailed: 'Could not turn the pet on.',
+        turnOffFailed: 'Could not turn the pet off.'
+      }
     },
     fieldLabels: FIELD_LABELS,
     fieldDescriptions: FIELD_DESCRIPTIONS,
@@ -723,8 +748,22 @@ export const en: Translations = {
     commandCenter: 'Command Center',
     appearance: 'Appearance',
     settings: 'Settings',
-    changeTheme: 'Change theme...',
+    changeTheme: 'Change theme',
     changeColorMode: 'Change color mode...',
+    pets: {
+      title: 'Pets',
+      placeholder: 'Search pets…',
+      loading: 'Loading petdex gallery…',
+      error: 'Could not reach the petdex gallery.',
+      staleBackend: 'Restart Hermes to use pets — the backend predates this feature.',
+      empty: 'No matching pets.',
+      turnOff: 'Turn off',
+      turnOn: 'Turn on',
+      installed: 'Installed',
+      adoptFailed: 'Could not adopt that pet.',
+      toggleFailed: 'Could not toggle the pet.',
+      noneAvailable: 'No pets available — pick one below to install.'
+    },
     installTheme: {
       title: 'Install theme...',
       placeholder: 'Search the VS Code Marketplace...',
@@ -1671,6 +1710,7 @@ export const en: Translations = {
     opening: 'Opening...',
     hide: 'Hide',
     openPreview: 'Open preview',
+    openInBrowser: 'Open in browser',
     sourceLineTitle: 'Click to select · shift-click to extend · drag to composer',
     source: 'SOURCE',
     renderedPreview: 'PREVIEW',

apps/desktop/src/i18n/ja.ts

@@ -287,7 +287,32 @@ export const ja = defineLocale({
       installError: 'そのテーマをインストールできませんでした。',
       installed: name => `「${name}」をインストールしました。`,
       removeTheme: 'テーマを削除',
-      importedBadge: 'インポート済み'
+      importedBadge: 'インポート済み',
+      pet: {
+        title: 'ペット',
+        intro:
+          'アプリ上に浮かぶ petdex のアニメーションマスコットを採用しましょう。ツール実行中は走り、成功すると喜び、エラーでしょんぼりと、Hermes の状態に反応します。',
+        restartHint:
+          'ペット機能には再起動が必要です。この機能が追加される前に起動したアプリが動作中です。Hermes を終了して再度開き、このページに戻ってください。',
+        scaleTitle: 'サイズ',
+        scaleDesc: '浮遊マスコットの大きさを変更します。すべての画面に即時反映されます。',
+        on: 'オン',
+        off: 'オフ',
+        chooseTitle: 'ペットを選ぶ',
+        chooseDesc: '選ぶと（必要に応じて）インストールされ、アクティブになります。',
+        searchPlaceholder: 'ペットを検索…',
+        unreachable: 'petdex ギャラリーに接続できませんでした。接続を確認してこのページを開き直してください。',
+        noMatch: query => `「${query}」に一致するペットがありません。`,
+        installedTag: 'インストール済み',
+        countCapped: (cap, total) => `${total} 件中 ${cap} 件を表示中——入力して絞り込めます。`,
+        count: n => `${n} 件のペット。`,
+        uninstall: name => `${name} をアンインストール`,
+        adoptFailed: slug => `${slug} を採用できませんでした`,
+        uninstallFailed: slug => `${slug} をアンインストールできませんでした`,
+        noneAvailable: 'オンにできるペットがありません。',
+        turnOnFailed: 'ペットをオンにできませんでした。',
+        turnOffFailed: 'ペットをオフにできませんでした。'
+      }
     },
     fieldLabels: defineFieldCopy({
       model: 'デフォルトモデル',
@@ -843,8 +868,22 @@ export const ja = defineLocale({
     commandCenter: 'コマンドセンター',
     appearance: '外観',
     settings: '設定',
-    changeTheme: 'テーマを変更...',
+    changeTheme: 'テーマを変更',
     changeColorMode: 'カラーモードを変更...',
+    pets: {
+      title: 'ペット',
+      placeholder: 'ペットを検索…',
+      loading: 'petdex ギャラリーを読み込み中…',
+      error: 'petdex ギャラリーに接続できません。',
+      staleBackend: 'ペット機能を使うには Hermes を再起動してください。',
+      empty: '一致するペットがありません。',
+      turnOff: 'オフ',
+      turnOn: 'オン',
+      installed: 'インストール済み',
+      adoptFailed: 'ペットを採用できませんでした。',
+      toggleFailed: 'ペットを切り替えできませんでした。',
+      noneAvailable: '利用可能なペットがありません。'
+    },
     installTheme: {
       title: 'テーマをインストール...',
       placeholder: 'VS Code Marketplace を検索...',
@@ -1800,6 +1839,7 @@ export const ja = defineLocale({
     opening: '開いています...',
     hide: '非表示',
     openPreview: 'プレビューを開く',
+    openInBrowser: 'ブラウザで開く',
     sourceLineTitle: 'クリックして選択 · Shift クリックで拡張 · コンポーザーにドラッグ',
     source: 'ソース',
     renderedPreview: 'プレビュー',

apps/desktop/src/i18n/types.ts

@@ -270,6 +270,29 @@ export interface Translations {
       installed: (name: string) => string
       removeTheme: string
       importedBadge: string
+      pet: {
+        title: string
+        intro: string
+        restartHint: string
+        on: string
+        off: string
+        scaleTitle: string
+        scaleDesc: string
+        chooseTitle: string
+        chooseDesc: string
+        searchPlaceholder: string
+        unreachable: string
+        noMatch: (query: string) => string
+        installedTag: string
+        countCapped: (cap: number, total: number) => string
+        count: (n: number) => string
+        uninstall: (name: string) => string
+        adoptFailed: (slug: string) => string
+        uninstallFailed: (slug: string) => string
+        noneAvailable: string
+        turnOnFailed: string
+        turnOffFailed: string
+      }
     }
     fieldLabels: Record<string, string>
     fieldDescriptions: Record<string, string>
@@ -602,6 +625,20 @@ export interface Translations {
     settings: string
     changeTheme: string
     changeColorMode: string
+    pets: {
+      title: string
+      placeholder: string
+      loading: string
+      error: string
+      staleBackend: string
+      empty: string
+      turnOff: string
+      turnOn: string
+      installed: string
+      adoptFailed: string
+      toggleFailed: string
+      noneAvailable: string
+    }
     installTheme: {
       title: string
       placeholder: string
@@ -1308,6 +1345,7 @@ export interface Translations {
     opening: string
     hide: string
     openPreview: string
+    openInBrowser: string
     sourceLineTitle: string
     source: string
     renderedPreview: string

apps/desktop/src/i18n/zh-hant.ts

@@ -276,7 +276,30 @@ export const zhHant = defineLocale({
       installError: '無法安裝該主題。',
       installed: name => `已安裝「${name}」。`,
       removeTheme: '移除主題',
-      importedBadge: '已匯入'
+      importedBadge: '已匯入',
+      pet: {
+        title: '寵物',
+        intro: '領養一隻懸浮在應用上的 petdex 動畫寵物，它會根據 Hermes 的狀態做出反應——工具執行時奔跑、成功時歡呼、出錯時沮喪。',
+        restartHint: '寵物功能需要重新啟動——目前執行的應用在此功能加入前啟動。請結束並重新開啟 Hermes，然後回到此處。',
+        scaleTitle: '大小',
+        scaleDesc: '調整懸浮寵物的大小，所有介面即時生效。',
+        on: '開啟',
+        off: '關閉',
+        chooseTitle: '選擇寵物',
+        chooseDesc: '選擇後會自動安裝（如需）並設為目前寵物。',
+        searchPlaceholder: '搜尋寵物…',
+        unreachable: '無法連線至 petdex 畫廊。請檢查網路連線並重新開啟此頁面。',
+        noMatch: query => `沒有符合「${query}」的寵物。`,
+        installedTag: '已安裝',
+        countCapped: (cap, total) => `顯示 ${total} 個中的 ${cap} 個——輸入關鍵字以縮小範圍。`,
+        count: n => `${n} 個寵物。`,
+        uninstall: name => `解除安裝 ${name}`,
+        adoptFailed: slug => `無法領養 ${slug}`,
+        uninstallFailed: slug => `無法解除安裝 ${slug}`,
+        noneAvailable: '目前沒有可開啟的寵物。',
+        turnOnFailed: '無法開啟寵物。',
+        turnOffFailed: '無法關閉寵物。'
+      }
     },
     fieldLabels: defineFieldCopy({
       model: '預設模型',
@@ -815,8 +838,22 @@ export const zhHant = defineLocale({
     commandCenter: '命令中心',
     appearance: '外觀',
     settings: '設定',
-    changeTheme: '變更主題...',
+    changeTheme: '變更主題',
     changeColorMode: '變更色彩模式...',
+    pets: {
+      title: '寵物',
+      placeholder: '搜尋寵物…',
+      loading: '正在載入 petdex 畫廊…',
+      error: '無法連線至 petdex 畫廊。',
+      staleBackend: '請重新啟動 Hermes 以使用寵物功能。',
+      empty: '沒有符合的寵物。',
+      turnOff: '關閉',
+      turnOn: '開啟',
+      installed: '已安裝',
+      adoptFailed: '無法領養該寵物。',
+      toggleFailed: '無法切換寵物顯示。',
+      noneAvailable: '尚無可用寵物——請在下方選擇一個安裝。'
+    },
     installTheme: {
       title: '安裝主題...',
       placeholder: '搜尋 VS Code Marketplace...',
@@ -1743,6 +1780,7 @@ export const zhHant = defineLocale({
     opening: '開啟中...',
     hide: '隱藏',
     openPreview: '開啟預覽',
+    openInBrowser: '在瀏覽器中開啟',
     sourceLineTitle: '點擊選取 · shift 點擊擴展 · 拖曳至輸入框',
     source: '原始碼',
     renderedPreview: '預覽',

apps/desktop/src/i18n/zh.ts

@@ -364,7 +364,30 @@ export const zh: Translations = {
       installError: '无法安装该主题。',
       installed: name => `已安装「${name}」。`,
       removeTheme: '移除主题',
-      importedBadge: '已导入'
+      importedBadge: '已导入',
+      pet: {
+        title: '宠物',
+        intro: '领养一只悬浮在应用上的 petdex 动画宠物，它会根据 Hermes 的状态做出反应——工具执行时奔跑、成功时欢呼、出错时沮丧。',
+        restartHint: '宠物功能需要重启——当前运行的应用在此功能加入前启动。请退出并重新打开 Hermes，然后回到此处。',
+        scaleTitle: '大小',
+        scaleDesc: '调整悬浮宠物的大小，所有界面即时生效。',
+        on: '开启',
+        off: '关闭',
+        chooseTitle: '选择宠物',
+        chooseDesc: '选择后会自动安装（如需）并设为当前宠物。',
+        searchPlaceholder: '搜索宠物…',
+        unreachable: '无法连接到 petdex 画廊。请检查网络连接并重新打开此页面。',
+        noMatch: query => `没有匹配「${query}」的宠物。`,
+        installedTag: '已安装',
+        countCapped: (cap, total) => `显示 ${total} 个中的 ${cap} 个——输入关键词以缩小范围。`,
+        count: n => `${n} 个宠物。`,
+        uninstall: name => `卸载 ${name}`,
+        adoptFailed: slug => `无法领养 ${slug}`,
+        uninstallFailed: slug => `无法卸载 ${slug}`,
+        noneAvailable: '当前没有可开启的宠物。',
+        turnOnFailed: '无法开启宠物。',
+        turnOffFailed: '无法关闭宠物。'
+      }
     },
     fieldLabels: defineFieldCopy({
       model: '默认模型',
@@ -912,8 +935,22 @@ export const zh: Translations = {
     commandCenter: '命令中心',
     appearance: '外观',
     settings: '设置',
-    changeTheme: '更改主题...',
+    changeTheme: '更改主题',
     changeColorMode: '更改颜色模式...',
+    pets: {
+      title: '宠物',
+      placeholder: '搜索宠物…',
+      loading: '正在加载 petdex 画廊…',
+      error: '无法连接到 petdex 画廊。',
+      staleBackend: '请重启 Hermes 以使用宠物功能——当前后端版本过旧。',
+      empty: '没有匹配的宠物。',
+      turnOff: '关闭',
+      turnOn: '开启',
+      installed: '已安装',
+      adoptFailed: '无法领养该宠物。',
+      toggleFailed: '无法切换宠物显示。',
+      noneAvailable: '暂无可用宠物——请在下方选择一个安装。'
+    },
     installTheme: {
       title: '安装主题...',
       placeholder: '搜索 VS Code Marketplace...',
@@ -1848,6 +1885,7 @@ export const zh: Translations = {
     opening: '正在打开...',
     hide: '隐藏',
     openPreview: '打开预览',
+    openInBrowser: '在浏览器中打开',
     sourceLineTitle: '点击选择 · shift 点击扩展 · 拖到输入框',
     source: '源码',
     renderedPreview: '预览',

apps/desktop/src/lib/desktop-slash-commands.test.ts

@@ -52,6 +52,16 @@ describe('desktop slash command curation', () => {
     expect(desktopSlashUnavailableMessage('/personality')).toBeNull()
   })
 
+  it('routes /pet through the desktop action handler and drops /pets', () => {
+    expect(resolveDesktopCommand('/pet')?.surface).toEqual({ kind: 'action', action: 'pet' })
+    expect(resolveDesktopCommand('/pet')?.args).toBe(true)
+    expect(isDesktopSlashSuggestion('/pet')).toBe(true)
+    expect(isDesktopSlashCommand('/pet')).toBe(true)
+    expect(resolveDesktopCommand('/pets')?.surface).toEqual({ kind: 'unavailable', reason: 'settings' })
+    expect(isDesktopSlashSuggestion('/pets')).toBe(false)
+    expect(isDesktopSlashCommand('/pets')).toBe(false)
+  })
+
   it('treats /browser as an executable action command (local-gateway connect)', () => {
     // /browser used to be terminal-only; it now resolves to a desktop action
     // handler that routes browser.manage RPC when the gateway is local.

apps/desktop/src/lib/desktop-slash-commands.ts

@@ -34,6 +34,7 @@ export type DesktopActionId =
   | 'handoff'
   | 'help'
   | 'new'
+  | 'pet'
   | 'profile'
   | 'skin'
   | 'title'
@@ -128,6 +129,7 @@ const DESKTOP_COMMAND_SPECS: readonly DesktopCommandSpec[] = [
   { name: '/debug', description: 'Create a debug report', surface: exec() },
   { name: '/goal', description: 'Manage the standing goal for this session', surface: exec() },
   { name: '/personality', description: 'Switch personality for this session', surface: exec(), args: true },
+  { name: '/pet', description: 'Toggle or adopt a petdex mascot (/pet, /pet list, /pet boba)', surface: action('pet'), args: true },
   { name: '/queue', description: 'Queue a prompt for the next turn', aliases: ['/q'], surface: exec() },
   { name: '/retry', description: 'Retry the last user message', surface: exec() },
   { name: '/rollback', description: 'List or restore filesystem checkpoints', surface: exec() },
@@ -155,7 +157,7 @@ const NO_DESKTOP_SURFACE: Record<DesktopUnavailableReason, readonly string[]> =
     '/sb', '/set-home', '/sethome', '/snap', '/snapshot', '/statusbar', '/toolsets', '/update', '/verbose'
   ],
   messaging: ['/approve', '/deny'],
-  settings: ['/skills'],
+  settings: ['/skills', '/pets'],
   advanced: ['/curator', '/fast', '/insights', '/kanban', '/reasoning', '/voice']
 }
 

apps/desktop/src/lib/embedded-images.test.ts

@@ -32,4 +32,13 @@ describe('extractEmbeddedImages', () => {
     expect(result.cleanedText).toBe('first  mid  tail')
     expect(result.images).toEqual([SAMPLE_PNG_DATA_URL, second])
   })
+
+  it('handles multi-megabyte data URLs without overflowing the JS stack', () => {
+    const hugeDataUrl = 'data:image/png;base64,' + 'A'.repeat(8_000_000)
+    const result = extractEmbeddedImages(`describe this ${hugeDataUrl} thanks`)
+
+    expect(result.cleanedText).toBe('describe this  thanks')
+    expect(result.images).toHaveLength(1)
+    expect(result.images[0]).toHaveLength(hugeDataUrl.length)
+  })
 })

apps/desktop/src/lib/embedded-images.ts

@@ -1,7 +1,11 @@
-const EMBEDDED_IMAGE_RE =
-  /(\{\s*"type"\s*:\s*"image_url"\s*,\s*"image_url"\s*:\s*\{\s*"url"\s*:\s*")?(data:image\/[\w.+-]+;base64,[A-Za-z0-9+/=]{64,})("\s*\}\s*\})?/g
-
 const DATA_URL_RE = /^data:([\w./+-]+);base64,(.*)$/i
+const DATA_IMAGE_PREFIX = 'data:image/'
+const BASE64_MARKER = ';base64,'
+const MIN_EMBEDDED_IMAGE_BASE64_LENGTH = 64
+const JSON_IMAGE_OPEN_RE = /\{\s*"type"\s*:\s*"image_url"\s*,\s*"image_url"\s*:\s*\{\s*"url"\s*:\s*"$/
+const JSON_IMAGE_CLOSE_RE = /^"\s*\}\s*\}/
+const JSON_IMAGE_OPEN_MAX = 96
+const JSON_IMAGE_CLOSE_MAX = 16
 
 export const DATA_IMAGE_URL_RE = /^data:image\/[\w.+-]+;base64,/i
 
@@ -31,24 +35,119 @@ export function dataUrlToBlob(dataUrl: string): Blob | null {
   }
 }
 
+function isImageMimeCode(code: number): boolean {
+  return (
+    (code >= 48 && code <= 57) ||
+    (code >= 65 && code <= 90) ||
+    (code >= 97 && code <= 122) ||
+    code === 43 ||
+    code === 45 ||
+    code === 46 ||
+    code === 95
+  )
+}
+
+function isBase64Code(code: number): boolean {
+  return (
+    (code >= 48 && code <= 57) ||
+    (code >= 65 && code <= 90) ||
+    (code >= 97 && code <= 122) ||
+    code === 43 ||
+    code === 47 ||
+    code === 61
+  )
+}
+
+function readDataImageUrl(text: string, start: number): { end: number; url: string } | null {
+  if (!text.startsWith(DATA_IMAGE_PREFIX, start)) {
+    return null
+  }
+
+  let cursor = start + DATA_IMAGE_PREFIX.length
+
+  while (cursor < text.length && isImageMimeCode(text.charCodeAt(cursor))) {
+    cursor += 1
+  }
+
+  if (cursor === start + DATA_IMAGE_PREFIX.length || !text.startsWith(BASE64_MARKER, cursor)) {
+    return null
+  }
+
+  cursor += BASE64_MARKER.length
+  const base64Start = cursor
+
+  while (cursor < text.length && isBase64Code(text.charCodeAt(cursor))) {
+    cursor += 1
+  }
+
+  if (cursor - base64Start < MIN_EMBEDDED_IMAGE_BASE64_LENGTH) {
+    return null
+  }
+
+  return { end: cursor, url: text.slice(start, cursor) }
+}
+
+function embeddedImageRemovalRange(text: string, dataStart: number, dataEnd: number): { end: number; start: number } {
+  let start = dataStart
+  let end = dataEnd
+  const openSearchStart = Math.max(0, dataStart - JSON_IMAGE_OPEN_MAX)
+  const openMatch = text.slice(openSearchStart, dataStart).match(JSON_IMAGE_OPEN_RE)
+
+  if (openMatch?.index !== undefined) {
+    const close = text.slice(dataEnd, dataEnd + JSON_IMAGE_CLOSE_MAX).match(JSON_IMAGE_CLOSE_RE)
+
+    if (close) {
+      start = openSearchStart + openMatch.index
+      end = dataEnd + close[0].length
+    }
+  }
+
+  return { end, start }
+}
+
+function normalizeCleanedText(text: string): string {
+  return text.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim()
+}
+
 export function extractEmbeddedImages(text: string): EmbeddedImageExtraction {
-  if (!text || !text.includes('data:image/')) {
+  if (!text || !text.includes(DATA_IMAGE_PREFIX)) {
     return { cleanedText: text, images: [] }
   }
 
   const images: string[] = []
+  const pieces: string[] = []
+  let appendCursor = 0
+  let searchCursor = 0
 
-  const cleanedText = text
-    .replace(EMBEDDED_IMAGE_RE, (_match, _open, dataUrl: string) => {
-      images.push(dataUrl)
+  while (searchCursor < text.length) {
+    const dataStart = text.indexOf(DATA_IMAGE_PREFIX, searchCursor)
 
-      return ''
-    })
-    .replace(/[ \t]+\n/g, '\n')
-    .replace(/\n{3,}/g, '\n\n')
-    .trim()
+    if (dataStart === -1) {
+      break
+    }
 
-  return { cleanedText, images }
+    const dataUrl = readDataImageUrl(text, dataStart)
+
+    if (!dataUrl) {
+      searchCursor = dataStart + DATA_IMAGE_PREFIX.length
+
+      continue
+    }
+
+    const range = embeddedImageRemovalRange(text, dataStart, dataUrl.end)
+    pieces.push(text.slice(appendCursor, range.start))
+    images.push(dataUrl.url)
+    appendCursor = range.end
+    searchCursor = range.end
+  }
+
+  if (!images.length) {
+    return { cleanedText: text, images: [] }
+  }
+
+  pieces.push(text.slice(appendCursor))
+
+  return { cleanedText: normalizeCleanedText(pieces.join('')), images }
 }
 
 export function embeddedImageUrls(text: string): string[] {

apps/desktop/src/lib/icons.ts

@@ -51,6 +51,7 @@ import {
   IconLoader2 as Loader2Icon,
   IconLock as Lock,
   IconLogin as LogIn,
+  IconMail as Mail,
   IconMessageCircle as MessageCircle,
   IconMessage2 as MessageSquareText,
   IconMicrophone as Mic,
@@ -67,6 +68,7 @@ import {
   IconLayoutBottombar as PanelBottom,
   IconLayoutSidebar as PanelLeftIcon,
   IconPlayerPause as Pause,
+  IconPaw as PawPrint,
   IconPencil as Pencil,
   IconPencil as PencilIcon,
   IconPencil as PencilLine,
@@ -153,6 +155,7 @@ export {
   Loader2Icon,
   Lock,
   LogIn,
+  Mail,
   MessageCircle,
   MessageSquareText,
   Mic,
@@ -169,6 +172,7 @@ export {
   PanelBottom,
   PanelLeftIcon,
   Pause,
+  PawPrint,
   Pencil,
   PencilIcon,
   PencilLine,

apps/desktop/src/lib/runtime-readiness.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { interpretRuntimeReadiness } from './runtime-readiness'
+import { evaluateRuntimeReadiness, fetchRuntimeReadinessSignals, interpretRuntimeReadiness } from './runtime-readiness'
 
 describe('interpretRuntimeReadiness', () => {
   it('prefers runtime_check when both signals exist', () => {
@@ -63,3 +63,51 @@ describe('interpretRuntimeReadiness', () => {
     expect(result.reason).toBe('setup.runtime_check timeout')
   })
 })
+
+describe('fetchRuntimeReadinessSignals', () => {
+  it('scopes setup.runtime_check to the requested provider', async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = []
+    const requestGateway = async <T = unknown>(method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      if (method === 'setup.status') {
+        return { provider_configured: true } as T
+      }
+
+      if (method === 'setup.runtime_check') {
+        return { ok: true } as T
+      }
+
+      throw new Error(`unexpected method: ${method}`)
+    }
+
+    await fetchRuntimeReadinessSignals(requestGateway, 'nous')
+
+    expect(calls).toEqual([
+      { method: 'setup.status' },
+      { method: 'setup.runtime_check', params: { provider: 'nous' } }
+    ])
+  })
+})
+
+describe('evaluateRuntimeReadiness', () => {
+  it('forwards requestedProvider to setup.runtime_check', async () => {
+    const requestGateway = async <T = unknown>(method: string, params?: Record<string, unknown>) => {
+      if (method === 'setup.status') {
+        return { provider_configured: true } as T
+      }
+
+      if (method === 'setup.runtime_check') {
+        expect(params).toEqual({ provider: 'nous' })
+
+        return { ok: true } as T
+      }
+
+      throw new Error(`unexpected method: ${method}`)
+    }
+
+    const result = await evaluateRuntimeReadiness(requestGateway, { requestedProvider: 'nous' })
+
+    expect(result.ready).toBe(true)
+  })
+})

apps/desktop/src/lib/runtime-readiness.ts

@@ -16,6 +16,7 @@ export interface RuntimeReadinessSignals {
 
 export interface RuntimeReadinessOptions {
   defaultReason?: string
+  requestedProvider?: string
   unknownReady?: boolean
 }
 
@@ -54,21 +55,27 @@ function normalizeMessage(value: null | string | undefined): null | string {
 
 async function requestWithFallback<T>(
   requestGateway: RuntimeReadinessRequester,
-  method: string
+  method: string,
+  params?: Record<string, unknown>
 ): Promise<{ error: null | string; value: null | T }> {
   try {
-    return { error: null, value: await requestGateway<T>(method) }
+    return { error: null, value: await requestGateway<T>(method, params) }
   } catch (error) {
     return { error: toErrorMessage(error), value: null }
   }
 }
 
 export async function fetchRuntimeReadinessSignals(
-  requestGateway: RuntimeReadinessRequester
+  requestGateway: RuntimeReadinessRequester,
+  requestedProvider?: string
 ): Promise<RuntimeReadinessSignals> {
+  const runtimeParams = requestedProvider?.trim()
+    ? { provider: requestedProvider.trim() }
+    : undefined
+
   const [setup, runtime] = await Promise.all([
     requestWithFallback<SetupStatusSnapshot>(requestGateway, 'setup.status'),
-    requestWithFallback<RuntimeCheckSnapshot>(requestGateway, 'setup.runtime_check')
+    requestWithFallback<RuntimeCheckSnapshot>(requestGateway, 'setup.runtime_check', runtimeParams)
   ])
 
   return {
@@ -141,7 +148,7 @@ export async function evaluateRuntimeReadiness(
   requestGateway: RuntimeReadinessRequester,
   options: RuntimeReadinessOptions = {}
 ): Promise<RuntimeReadinessResult> {
-  const signals = await fetchRuntimeReadinessSignals(requestGateway)
+  const signals = await fetchRuntimeReadinessSignals(requestGateway, options.requestedProvider)
 
   return interpretRuntimeReadiness(signals, options)
 }

apps/desktop/src/lib/selectable-card.ts

@@ -0,0 +1,31 @@
+import { cn } from '@/lib/utils'
+
+export interface SelectableCardState {
+  /** Currently selected / active — the strongest emphasis. */
+  active?: boolean
+  /**
+   * Configured / installed / "you have this" — solid surface + border. When
+   * false the card renders muted (transparent, dimmed) until hovered, so the
+   * eye lands on what you already have. Ignored when `active` is set.
+   */
+  prominent?: boolean
+}
+
+/**
+ * Shared emphasis for selectable list cards across settings surfaces (theme
+ * picker, pet picker, Marketplace results, provider rows…). Three tiers:
+ * active > prominent > muted. Keeps the "installed = solid, not-installed =
+ * quiet" pattern consistent everywhere instead of each picker rolling its own.
+ *
+ * Callers own layout (padding, flex, width); this owns only border + surface.
+ */
+export function selectableCardClass({ active, prominent }: SelectableCardState): string {
+  return cn(
+    'rounded-lg border transition-colors',
+    active
+      ? 'border-primary bg-primary/[0.06] ring-2 ring-primary/20'
+      : prominent
+        ? 'border-(--ui-stroke-tertiary) bg-(--ui-bg-quinary) hover:bg-(--chrome-action-hover)'
+        : 'border-transparent bg-transparent text-(--ui-text-tertiary) hover:border-(--ui-stroke-tertiary) hover:bg-(--ui-bg-quinary)'
+  )
+}

apps/desktop/src/main.tsx

@@ -26,20 +26,27 @@ if (import.meta.env.MODE !== 'production') {
   import('./app/chat/perf-probe')
 }
 
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <ErrorBoundary label="root">
-      <QueryClientProvider client={queryClient}>
-        <I18nProvider>
-          <ThemeProvider>
-            <HapticsProvider>
-              <HashRouter>
-                <App />
-              </HashRouter>
-            </HapticsProvider>
-          </ThemeProvider>
-        </I18nProvider>
-      </QueryClientProvider>
-    </ErrorBoundary>
-  </StrictMode>
-)
+// The pet overlay rides this same bundle (`?win=overlay`) but mounts a tiny,
+// transparent, gateway-less surface instead of the full app. Branch before any
+// app-shell work so the overlay window stays cheap.
+if (new URLSearchParams(window.location.search).get('win') === 'overlay') {
+  void import('./app/pet-overlay/overlay-root').then(({ mountPetOverlay }) => mountPetOverlay())
+} else {
+  createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+      <ErrorBoundary label="root">
+        <QueryClientProvider client={queryClient}>
+          <I18nProvider>
+            <ThemeProvider>
+              <HapticsProvider>
+                <HashRouter>
+                  <App />
+                </HashRouter>
+              </HapticsProvider>
+            </ThemeProvider>
+          </I18nProvider>
+        </QueryClientProvider>
+      </ErrorBoundary>
+    </StrictMode>
+  )
+}

apps/desktop/src/store/command-palette.ts

@@ -3,16 +3,30 @@ import { atom } from 'nanostores'
 /** Whether the global command palette (Cmd/Ctrl+K) is currently open. */
 export const $commandPaletteOpen = atom(false)
 
+/** Optional nested page to open when the palette next opens (e.g. `pets`). */
+export const $commandPalettePage = atom<string | null>(null)
+
 export function openCommandPalette(): void {
   $commandPaletteOpen.set(true)
 }
 
+/** Open the palette directly on a nested page (`theme`, `pets`, …). */
+export function openCommandPalettePage(page: string): void {
+  $commandPalettePage.set(page)
+  $commandPaletteOpen.set(true)
+}
+
 export function closeCommandPalette(): void {
   $commandPaletteOpen.set(false)
+  $commandPalettePage.set(null)
 }
 
 export function setCommandPaletteOpen(open: boolean): void {
   $commandPaletteOpen.set(open)
+
+  if (!open) {
+    $commandPalettePage.set(null)
+  }
 }
 
 export function toggleCommandPalette(): void {

apps/desktop/src/store/layout.ts

@@ -32,12 +32,14 @@ const PANES_FLIPPED_STORAGE_KEY = 'hermes.desktop.panesFlipped'
 
 export const CHAT_SIDEBAR_PANE_ID = 'chat-sidebar'
 export const FILE_BROWSER_PANE_ID = 'file-browser'
+export const PREVIEW_PANE_ID = 'preview'
 export const RIGHT_RAIL_PREVIEW_TAB_ID = 'preview'
 
 export type RightRailTabId = typeof RIGHT_RAIL_PREVIEW_TAB_ID | `file:${string}`
 
 ensurePaneRegistered(CHAT_SIDEBAR_PANE_ID, { open: true })
 ensurePaneRegistered(FILE_BROWSER_PANE_ID, { open: false })
+ensurePaneRegistered(PREVIEW_PANE_ID, { open: true })
 
 export const $sidebarOpen: ReadableAtom<boolean> = computed(
   $paneStates,

apps/desktop/src/store/onboarding.test.ts

@@ -2,6 +2,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type { OAuthProvider } from '@/types/hermes'
 
+import * as notifications from '@/store/notifications'
+
 import {
   $desktopOnboarding,
   type DesktopOnboardingState,
@@ -63,6 +65,16 @@ function onboardingContext(requestGateway: OnboardingContext['requestGateway']):
   return { requestGateway }
 }
 
+function fallbackTimeoutGateway(): OnboardingContext['requestGateway'] {
+  return async method => {
+    if (method === 'setup.status' || method === 'setup.runtime_check') {
+      throw new Error(`request timed out: ${method}`)
+    }
+
+    throw new Error(`unexpected gateway method: ${method}`)
+  }
+}
+
 describe('refreshOnboarding', () => {
   beforeEach(() => {
     window.localStorage.clear()
@@ -116,6 +128,108 @@ describe('refreshOnboarding', () => {
     expect($desktopOnboarding.get().providers?.map(p => p.id)).toEqual(['cached'])
   })
 
+  it('does not downgrade configured=true on fallback-only readiness failures', async () => {
+    const api = vi.fn(async ({ path }: { path: string }) => {
+      if (path === '/api/providers/oauth') {
+        return { providers: [provider('fresh')] }
+      }
+
+      throw new Error(`unexpected api path: ${path}`)
+    })
+
+    installApiMock(api)
+    // Simulate a returning user: cache is set and store is configured.
+    window.localStorage.setItem('hermes-desktop-onboarded-v1', '1')
+    $desktopOnboarding.set(
+      baseState({
+        configured: true,
+        providers: [provider('cached')],
+        reason: null,
+        requested: false
+      })
+    )
+
+    const ready = await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
+
+    expect(ready).toBe(false)
+    expect(api).not.toHaveBeenCalled()
+    expect($desktopOnboarding.get().configured).toBe(true)
+    expect($desktopOnboarding.get().reason).toBeNull()
+    // The cache must survive the refresh — proving we didn't downgrade.
+    expect(window.localStorage.getItem('hermes-desktop-onboarded-v1')).toBe('1')
+  })
+
+  it('shows a non-blocking notification when preserving configured on fallback', async () => {
+    const notifySpy = vi.spyOn(notifications, 'notify')
+
+    installApiMock(vi.fn())
+    $desktopOnboarding.set(
+      baseState({
+        configured: true,
+        providers: [provider('cached')],
+        reason: null,
+        requested: false
+      })
+    )
+
+    await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
+
+    expect(notifySpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: 'runtime-not-ready',
+        kind: 'error'
+      })
+    )
+    expect($desktopOnboarding.get().configured).toBe(true)
+  })
+
+  it('does not preserve configured when onboarding was explicitly requested', async () => {
+    const api = vi.fn(async ({ path }: { path: string }) => {
+      if (path === '/api/providers/oauth') {
+        return { providers: [provider('fresh')] }
+      }
+
+      throw new Error(`unexpected api path: ${path}`)
+    })
+
+    installApiMock(api)
+    $desktopOnboarding.set(
+      baseState({
+        configured: true,
+        providers: [provider('cached')],
+        reason: null,
+        requested: true
+      })
+    )
+
+    const ready = await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
+
+    expect(ready).toBe(false)
+    // requested overrides preservation — should downgrade.
+    expect($desktopOnboarding.get().configured).toBe(false)
+    expect(api).toHaveBeenCalledTimes(1)
+  })
+
+  it('still surfaces onboarding when fallback failure happens before configured state', async () => {
+    const api = vi.fn(async ({ path }: { path: string }) => {
+      if (path === '/api/providers/oauth') {
+        return { providers: [provider('fresh')] }
+      }
+
+      throw new Error(`unexpected api path: ${path}`)
+    })
+
+    installApiMock(api)
+    $desktopOnboarding.set(baseState({ configured: false, providers: null, requested: true }))
+
+    const ready = await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
+
+    expect(ready).toBe(false)
+    expect(api).toHaveBeenCalledTimes(1)
+    expect($desktopOnboarding.get().configured).toBe(false)
+    expect($desktopOnboarding.get().reason).toContain('request timed out')
+  })
+
   it('deduplicates concurrent provider refresh calls', async () => {
     let resolveProviders!: (value: { providers: OAuthProvider[] }) => void
 
@@ -194,7 +308,7 @@ describe('OAuth onboarding', () => {
       throw new Error(`unexpected api path: ${path}`)
     })
 
-    const requestGateway: OnboardingContext['requestGateway'] = async method => {
+    const requestGateway: OnboardingContext['requestGateway'] = async (method, params) => {
       if (method === 'reload.env') {
         return {} as never
       }
@@ -204,6 +318,8 @@ describe('OAuth onboarding', () => {
       }
 
       if (method === 'setup.runtime_check') {
+        expect(params).toEqual({ provider: 'nous' })
+
         return { ok: true } as never
       }
 
@@ -241,6 +357,14 @@ describe('OAuth onboarding', () => {
     }
 
     expect(calls.some(c => c.path === '/api/model/set')).toBe(true)
+
+    const optionsIndex = calls.findIndex(c => c.path === '/api/model/options')
+    const recommendedIndex = calls.findIndex(c => c.path.startsWith('/api/model/recommended-default'))
+    const setIndex = calls.findIndex(c => c.path === '/api/model/set')
+
+    expect(optionsIndex).toBeGreaterThanOrEqual(0)
+    expect(recommendedIndex).toBeGreaterThan(optionsIndex)
+    expect(setIndex).toBeGreaterThan(recommendedIndex)
   })
 })
 

apps/desktop/src/store/onboarding.ts

@@ -181,13 +181,27 @@ function clearPoll() {
   }
 }
 
-async function checkRuntime(ctx: OnboardingContext): Promise<RuntimeReadinessResult> {
+async function checkRuntime(
+  ctx: OnboardingContext,
+  requestedProvider?: string
+): Promise<RuntimeReadinessResult> {
   return evaluateRuntimeReadiness(ctx.requestGateway, {
     defaultReason: DEFAULT_ONBOARDING_REASON,
+    requestedProvider,
     unknownReady: false
   })
 }
 
+function shouldPreserveConfiguredOnFallback(
+  runtime: RuntimeReadinessResult,
+  state: DesktopOnboardingState
+): boolean {
+  // A fallback result means both runtime probes were non-authoritative
+  // (transport timeout/disconnect). Keep a previously verified configured
+  // state instead of forcing the blocking onboarding overlay.
+  return runtime.source === 'fallback' && state.configured === true && !state.requested
+}
+
 function notifyReady(provider: string) {
   notify({ kind: 'success', title: 'Hermes is ready', message: `${provider} connected.` })
 }
@@ -307,7 +321,28 @@ async function completeWithModelConfirm(
   ignoreRuntimeGate = false
 ) {
   await ctx.requestGateway('reload.env').catch(() => undefined)
-  const runtime = await checkRuntime(ctx)
+
+  const defaults = await fetchProviderDefaultModel(preferredSlugs)
+
+  if (defaults) {
+    // Persist the chosen provider/model before the runtime gate so a stale
+    // config provider (e.g. anthropic from a prior failed setup) cannot make
+    // setup.runtime_check validate the wrong backend after a fresh OAuth login.
+    try {
+      const res = await setModelAssignment({
+        scope: 'main',
+        provider: defaults.providerSlug,
+        model: defaults.defaultModel
+      })
+
+      notifyGatewayTools(res.gateway_tools)
+    } catch {
+      // Persistence failed — still run the scoped runtime check below and
+      // show the confirm card so the user can pick something explicitly.
+    }
+  }
+
+  const runtime = await checkRuntime(ctx, preferredSlugs[0])
 
   if (!runtime.ready && !ignoreRuntimeGate) {
     onFail(runtime.reason)
@@ -315,8 +350,6 @@ async function completeWithModelConfirm(
     return
   }
 
-  const defaults = await fetchProviderDefaultModel(preferredSlugs)
-
   if (!defaults) {
     // Couldn't get a sensible default — proceed without confirm step.
     notifyReady(providerLabel)
@@ -326,27 +359,6 @@ async function completeWithModelConfirm(
     return
   }
 
-  // Persist the default model BEFORE showing the confirm card so that:
-  // (1) "current default: X" shown in the UI is what's actually written
-  //     to config — no lying.
-  // (2) If the user clicks "Start chatting" without changing anything,
-  //     no extra write is needed.
-  // (3) If they bail out (e.g., refresh the page), they still end up
-  //     with a working config, not an empty-model fallback.
-  try {
-    const res = await setModelAssignment({
-      scope: 'main',
-      provider: defaults.providerSlug,
-      model: defaults.defaultModel
-    })
-
-    notifyGatewayTools(res.gateway_tools)
-  } catch {
-    // Persistence failed — still show the confirm card so the user can
-    // pick something explicitly. The backend will pick its own default
-    // at chat time if we end up never persisting.
-  }
-
   setFlow({
     status: 'confirming_model',
     providerSlug: defaults.providerSlug,
@@ -515,6 +527,21 @@ export async function refreshOnboarding(ctx: OnboardingContext) {
   }
 
   const state = $desktopOnboarding.get()
+  if (shouldPreserveConfiguredOnFallback(runtime, state)) {
+    // Gateway probes timed out but the user was already configured — don't
+    // downgrade to the blocking onboarding overlay. Surface a non-blocking
+    // notification with a stable id so repeated calls during an outage dedup
+    // instead of stacking toasts.
+    notify({
+      id: 'runtime-not-ready',
+      kind: 'error',
+      title: 'Runtime not ready',
+      message: 'Hermes Desktop could not verify the running backend on startup. Some features may be unavailable until the gateway is reachable.'
+    })
+
+    return false
+  }
+
   const reason = runtime.reason || state.reason || DEFAULT_ONBOARDING_REASON
 
   writeCachedConfigured(false)

apps/desktop/src/store/panes.ts

@@ -76,6 +76,7 @@ function persist(states: Record<string, PaneStateSnapshot>) {
 }
 
 export const $paneStates = atom<Record<string, PaneStateSnapshot>>(load())
+export const $paneHoverRevealSuppressed = atom(false)
 
 $paneStates.subscribe(persist)
 
@@ -143,3 +144,4 @@ export function setPaneWidthOverride(id: string, width: number | undefined) {
 
 export const clearPaneWidthOverride = (id: string) => setPaneWidthOverride(id, undefined)
 export const getPaneStateSnapshot = (id: string) => $paneStates.get()[id]
+export const setPaneHoverRevealSuppressed = (suppressed: boolean) => $paneHoverRevealSuppressed.set(suppressed)

apps/desktop/src/store/pet-gallery.ts

@@ -0,0 +1,322 @@
+import { atom } from 'nanostores'
+
+import { $petInfo, type PetInfo, petProfile, setPetInfo } from '@/store/pet'
+
+/**
+ * Feature store for the petdex gallery picker (Cmd+K "Pets…" + Settings).
+ *
+ * Why this exists: `pet.gallery` does a *network* manifest fetch on the gateway,
+ * so re-pulling it after every adopt/toggle made the picker feel laggy and made
+ * two components (palette + settings) each carry their own copy of the same
+ * fetch / thumb-cache / optimistic-mutation logic. This store centralizes it:
+ *
+ *  - The gallery is fetched once and cached; reopening the picker is instant.
+ *  - Mutations (adopt / enable / remove) patch local state and only re-pull the
+ *    cheap, local `pet.info` — never the network manifest again.
+ *  - Thumbnails are deduped in a process-global cache (the backend disk-caches
+ *    too, so a slug is fetched at most once per session).
+ *
+ * Consumers just `useStore($petGallery)` and call the actions; no component
+ * owns gallery state anymore.
+ */
+
+export interface GalleryPet {
+  slug: string
+  displayName: string
+  installed: boolean
+  spritesheetUrl?: string
+  /** petdex's hand-picked set — used only to rank "popular" pets first. */
+  curated?: boolean
+}
+
+export interface PetGallery {
+  enabled: boolean
+  active: string
+  pets: GalleryPet[]
+}
+
+export type PetGalleryStatus = 'idle' | 'loading' | 'ready' | 'stale' | 'error'
+
+/** The recovering `requestGateway` from `useGatewayRequest` — passed in so the
+ *  store reuses the hook's reconnect/reauth handling instead of duplicating it. */
+export type GatewayRequest = <T>(method: string, params?: Record<string, unknown>) => Promise<T>
+
+/** Profile-scoped pet RPC. Pets are per-profile, so every call carries the active
+ *  profile (the gateway no-ops it for the launch profile). One chokepoint so no
+ *  call site can forget it. */
+const petRpc = <T>(request: GatewayRequest, method: string, params: Record<string, unknown> = {}): Promise<T> =>
+  request<T>(method, { ...params, profile: petProfile() })
+
+/** A JSON-RPC "method not found" — the backend predates the pet RPCs. */
+function isMissingMethod(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+
+  return /method not found|-32601|unknown method|no such method/i.test(message)
+}
+
+export const $petGallery = atom<PetGallery | null>(null)
+export const $petGalleryStatus = atom<PetGalleryStatus>('idle')
+export const $petGalleryError = atom<string | null>(null)
+
+// Which action is in flight, so rows/buttons can show a spinner. A slug for a
+// per-pet mutation; the `TOGGLE_*` sentinels for the on/off switch.
+export const TOGGLE_ON = '\u0000on'
+export const TOGGLE_OFF = '\u0000off'
+export const $petBusy = atom<string | null>(null)
+
+// Process-global caches (survive component unmount → instant reopen).
+const thumbCache = new Map<string, Promise<string | null>>()
+let galleryLoad: Promise<void> | null = null
+
+/**
+ * Drop the cached gallery, thumbnails, and in-flight load so the next open
+ * refetches against the now-active profile's backend. Called on a profile switch
+ * (pets are per-profile) — the floating pet's own `pet.info` poll repaints the
+ * new profile's mascot, and the picker reloads its gallery on next mount.
+ */
+export function resetPetGallery(): void {
+  galleryLoad = null
+  thumbCache.clear()
+  $petGallery.set(null)
+  $petGalleryStatus.set('idle')
+  $petGalleryError.set(null)
+  $petBusy.set(null)
+}
+
+export function loadPetThumb(request: GatewayRequest, slug: string, url?: string): Promise<string | null> {
+  let pending = thumbCache.get(slug)
+
+  if (!pending) {
+    pending = petRpc<{ ok: boolean; dataUri?: string }>(request, 'pet.thumb', { slug, url: url ?? '' })
+      .then(result => (result?.ok && result.dataUri ? result.dataUri : null))
+      .catch(() => null)
+    thumbCache.set(slug, pending)
+  }
+
+  return pending
+}
+
+/**
+ * Fetch the gallery once and cache it. Subsequent calls are no-ops while a
+ * ready snapshot is held; pass `{ force: true }` to bypass the cache (e.g. a
+ * manual refresh). Concurrent callers share a single in-flight request.
+ */
+export function loadPetGallery(request: GatewayRequest, options: { force?: boolean } = {}): Promise<void> {
+  if (!options.force && $petGallery.get() && $petGalleryStatus.get() === 'ready') {
+    return Promise.resolve()
+  }
+
+  if (galleryLoad) {
+    return galleryLoad
+  }
+
+  galleryLoad = (async () => {
+    if (!$petGallery.get()) {
+      $petGalleryStatus.set('loading')
+    }
+
+    try {
+      const [next, info] = await Promise.all([
+        petRpc<PetGallery>(request, 'pet.gallery'),
+        petRpc<PetInfo>(request, 'pet.info')
+      ])
+
+      if (next) {
+        $petGallery.set(next)
+        $petGalleryStatus.set('ready')
+        $petGalleryError.set(null)
+      }
+
+      if (info) {
+        setPetInfo(info)
+      }
+    } catch (e) {
+      if (isMissingMethod(e)) {
+        $petGalleryStatus.set('stale')
+      } else if (!$petGallery.get()) {
+        // Only surface a hard error when we have nothing to show; a transient
+        // hiccup mid-session leaves the cached gallery intact.
+        $petGalleryStatus.set('error')
+        $petGalleryError.set(e instanceof Error ? e.message : 'Could not reach the petdex gallery.')
+      }
+    } finally {
+      galleryLoad = null
+    }
+  })()
+
+  return galleryLoad
+}
+
+// Push the live mascot state (cheap, local config read) without re-pulling the
+// network gallery — the floating pet repaints, the picker keeps its cache.
+async function syncInfo(request: GatewayRequest): Promise<void> {
+  try {
+    const info = await petRpc<PetInfo>(request, 'pet.info')
+
+    if (info) {
+      setPetInfo(info)
+    }
+  } catch {
+    // The mutation already succeeded; a stale mascot self-heals on its poll.
+  }
+}
+
+/**
+ * Filter (drop the internal `clawd*` pets + apply a search query) and rank the
+ * gallery for a picker. Ranking has no popularity data, so it leans on the
+ * signals we do have: active pet first, then installed, then curated. Shared by
+ * the Cmd-K palette and the Settings grid so the two can't drift — each caller
+ * applies its own cap and reads `.length` for the total.
+ */
+export function rankedGalleryPets(gallery: PetGallery | null, query = ''): GalleryPet[] {
+  if (!gallery) {
+    return []
+  }
+
+  const needle = query.trim().toLowerCase()
+
+  const rank = (p: GalleryPet) =>
+    Number(gallery.enabled && p.slug === gallery.active) * 4 + Number(p.installed) * 2 + Number(p.curated)
+
+  return gallery.pets
+    .filter(
+      p =>
+        !/^clawd(-|$)/i.test(p.slug) &&
+        (!needle || p.slug.toLowerCase().includes(needle) || p.displayName.toLowerCase().includes(needle))
+    )
+    .sort((a, b) => rank(b) - rank(a))
+}
+
+function patchGallery(fn: (gallery: PetGallery) => PetGallery): void {
+  const current = $petGallery.get()
+
+  if (current) {
+    $petGallery.set(fn(current))
+  }
+}
+
+/** Shared mutation wrapper: spin, fire, patch on success, surface failures. */
+async function mutate(
+  busyKey: string,
+  fallback: string,
+  request: GatewayRequest,
+  run: () => Promise<void>
+): Promise<boolean> {
+  $petBusy.set(busyKey)
+  $petGalleryError.set(null)
+
+  try {
+    await run()
+    await syncInfo(request)
+
+    return true
+  } catch (e) {
+    if (isMissingMethod(e)) {
+      $petGalleryStatus.set('stale')
+    } else {
+      $petGalleryError.set(e instanceof Error ? e.message : fallback)
+    }
+
+    return false
+  } finally {
+    $petBusy.set(null)
+  }
+}
+
+/** Install (if needed) + activate a pet. Optimistically marks it active. */
+export function adoptPet(request: GatewayRequest, slug: string, fallback: string): Promise<boolean> {
+  return mutate(slug, fallback, request, async () => {
+    await petRpc(request, 'pet.select', { slug })
+    patchGallery(g => ({
+      ...g,
+      enabled: true,
+      active: slug,
+      pets: g.pets.map(p => (p.slug === slug ? { ...p, installed: true } : p))
+    }))
+  })
+}
+
+/**
+ * Turn the floating mascot on/off. On enable, activates the current pet (or the
+ * first installed one). Returns false without firing if there's nothing to show.
+ */
+export function setPetEnabled(
+  request: GatewayRequest,
+  on: boolean,
+  copy: { noneAvailable: string; fallback: string }
+): Promise<boolean> {
+  const gallery = $petGallery.get()
+
+  if (!on && !(gallery?.enabled ?? false)) {
+    return Promise.resolve(true)
+  }
+
+  let slug = gallery?.active || ''
+
+  if (on) {
+    slug = slug || gallery?.pets.find(p => p.installed)?.slug || ''
+
+    if (!slug) {
+      $petGalleryError.set(copy.noneAvailable)
+
+      return Promise.resolve(false)
+    }
+  }
+
+  return mutate(on ? TOGGLE_ON : TOGGLE_OFF, copy.fallback, request, async () => {
+    if (on) {
+      await petRpc(request, 'pet.select', { slug })
+    } else {
+      await petRpc(request, 'pet.disable')
+    }
+
+    patchGallery(g => ({ ...g, enabled: on, active: on ? slug : g.active }))
+  })
+}
+
+// Pet scale bounds — mirror `agent/pet/constants.py` (MIN_SCALE / MAX_SCALE) so
+// the slider and the server clamp to the same range.
+export const PET_SCALE_MIN = 0.1
+export const PET_SCALE_MAX = 3.0
+export const PET_SCALE_DEFAULT = 0.33
+export const clampPetScale = (n: number) => Math.max(PET_SCALE_MIN, Math.min(PET_SCALE_MAX, n))
+
+let scalePersist: ReturnType<typeof setTimeout> | undefined
+
+/**
+ * Resize the floating pet. Updates `$petInfo` synchronously so the on-screen pet
+ * (and the slider) react on the same frame, then debounce-persists to
+ * `display.pet.scale` so a slider drag fires one RPC, not one per pixel. No poll
+ * or event needed — the pet already renders from `$petInfo.scale`.
+ */
+export function setPetScale(request: GatewayRequest, scale: number): void {
+  const next = clampPetScale(scale)
+
+  setPetInfo({ ...$petInfo.get(), scale: next })
+
+  clearTimeout(scalePersist)
+  scalePersist = setTimeout(() => {
+    petRpc<{ ok: boolean; scale?: number }>(request, 'pet.scale', { scale: next })
+      .then(result => {
+        // Reconcile with the server's clamp (cheap; only matters at the bounds).
+        if (typeof result?.scale === 'number' && result.scale !== $petInfo.get().scale) {
+          setPetInfo({ ...$petInfo.get(), scale: result.scale })
+        }
+      })
+      .catch(() => {
+        // Cosmetic — the pet already resized; persistence self-heals next write.
+      })
+  }, 200)
+}
+
+/** Uninstall a pet; turns the mascot off if it was the active one. */
+export function removePet(request: GatewayRequest, slug: string, fallback: string): Promise<boolean> {
+  return mutate(slug, fallback, request, async () => {
+    await petRpc(request, 'pet.remove', { slug })
+    patchGallery(g => ({
+      ...g,
+      enabled: g.active === slug ? false : g.enabled,
+      pets: g.pets.map(p => (p.slug === slug ? { ...p, installed: false } : p))
+    }))
+  })
+}

apps/desktop/src/store/pet-overlay.ts

@@ -0,0 +1,260 @@
+import { atom } from 'nanostores'
+
+import { persistBoolean, persistString, storedBoolean, storedString } from '@/lib/storage'
+import { $petActivity, $petInfo, $petUnread, clearPetUnread, type PetActivity, type PetInfo } from '@/store/pet'
+import { $awaitingResponse, $busy } from '@/store/session'
+
+/**
+ * Controller for the pop-out pet overlay (main-renderer side).
+ *
+ * Shift-clicking the in-window pet "pops it out" into a transparent,
+ * always-on-top OS window (created in electron/main.cjs) that can leave the
+ * app's bounds and stays visible while Hermes is minimized. That window carries
+ * NO gateway connection — this renderer remains the single source of truth and
+ * pushes the live pet state to it over IPC. Control flows back (pop the pet back
+ * in, submit a composer message) via `onControl`.
+ *
+ * The overlay renders the same `PetSprite` / `PetBubble` as the in-window pet by
+ * mirroring the four reactive inputs of `$petState` (`$petInfo`, `$petActivity`,
+ * `$busy`, `$awaitingResponse`) into its own copies of those atoms — so the
+ * popped-out mascot is pixel-identical and needs zero bespoke render logic.
+ */
+
+export interface PetOverlayBounds {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/**
+ * Request to open the overlay window. `screen` says whether `bounds` are already
+ * in absolute screen coordinates (a remembered/dragged spot) or in the main
+ * window's viewport space (a fresh shift-click pop-out, which main.cjs converts
+ * by adding the content origin).
+ */
+export interface PetOverlayOpenRequest {
+  bounds: PetOverlayBounds
+  screen?: boolean
+}
+
+/** Everything the overlay needs to reproduce the live mascot. */
+export interface PetOverlayStatePayload {
+  info: PetInfo
+  activity: PetActivity
+  busy: boolean
+  awaiting: boolean
+  /** Drives the overlay's mail icon: a finish landed while you were away. */
+  unread: boolean
+}
+
+export type PetOverlayControl =
+  | { type: 'pop-in' }
+  | { type: 'ready' }
+  | { type: 'submit'; text: string }
+  | { type: 'bounds'; bounds: PetOverlayBounds }
+  | { type: 'open-app' }
+  | { type: 'toggle-app' }
+
+// Persisted across restarts: was the pet popped out, and where on the desktop
+// did the user leave it. Keyed v1; bump if the bounds shape ever changes.
+const OVERLAY_ACTIVE_KEY = 'hermes.desktop.pet-overlay-active.v1'
+const OVERLAY_BOUNDS_KEY = 'hermes.desktop.pet-overlay-bounds.v1'
+
+export const $petOverlayActive = atom(storedBoolean(OVERLAY_ACTIVE_KEY, false))
+
+// Persist the in/out choice so a popped-out pet comes back popped out.
+$petOverlayActive.subscribe(active => persistBoolean(OVERLAY_ACTIVE_KEY, active))
+
+function loadSavedBounds(): null | PetOverlayBounds {
+  try {
+    const raw = storedString(OVERLAY_BOUNDS_KEY)
+
+    if (!raw) {
+      return null
+    }
+
+    const parsed = JSON.parse(raw) as Partial<PetOverlayBounds>
+
+    if (
+      typeof parsed.x === 'number' &&
+      typeof parsed.y === 'number' &&
+      typeof parsed.width === 'number' &&
+      typeof parsed.height === 'number'
+    ) {
+      return { height: parsed.height, width: parsed.width, x: parsed.x, y: parsed.y }
+    }
+  } catch {
+    // fall through to null
+  }
+
+  return null
+}
+
+function saveBounds(bounds: PetOverlayBounds): void {
+  persistString(OVERLAY_BOUNDS_KEY, JSON.stringify(bounds))
+}
+
+// The overlay window is padded around the sprite so the bubble (above), the
+// drag area, and the pop-up composer all have room; the pet sits near the
+// bottom and the rest of the rectangle is transparent + click-through.
+const OVERLAY_PAD_X = 100
+const OVERLAY_PAD_Y = 200
+const OVERLAY_MIN_W = 240
+const OVERLAY_MIN_H = 300
+
+let stateUnsubs: Array<() => void> = []
+let controlUnsub: (() => void) | null = null
+let submitHandler: ((text: string) => void) | null = null
+let openAppHandler: (() => void) | null = null
+
+function currentPayload(): PetOverlayStatePayload {
+  return {
+    info: $petInfo.get(),
+    activity: $petActivity.get(),
+    busy: $busy.get(),
+    awaiting: $awaitingResponse.get(),
+    unread: $petUnread.get()
+  }
+}
+
+function pushNow(): void {
+  window.hermesDesktop?.petOverlay?.pushState(currentPayload())
+}
+
+/**
+ * Open the overlay window and start mirroring live state into it. The main
+ * process echoes back the actual screen bounds it used, which we persist so the
+ * pet reopens exactly where the user left it.
+ */
+function openOverlay(request: PetOverlayOpenRequest): void {
+  const api = window.hermesDesktop?.petOverlay
+
+  if (!api || stateUnsubs.length) {
+    return
+  }
+
+  $petOverlayActive.set(true)
+  void api.open(request).then(res => {
+    if (res?.bounds) {
+      saveBounds(res.bounds)
+    }
+
+    pushNow()
+  })
+
+  // Mirror live state into the overlay. subscribe() fires immediately, so the
+  // overlay also gets a first frame the moment it's ready (it asks via 'ready').
+  stateUnsubs = [
+    $petInfo.subscribe(pushNow),
+    $petActivity.subscribe(pushNow),
+    $busy.subscribe(pushNow),
+    $awaitingResponse.subscribe(pushNow),
+    $petUnread.subscribe(pushNow)
+  ]
+}
+
+/**
+ * Pop the pet out of the window. `petRect` is the in-window sprite's viewport
+ * rect; we grow it to the padded overlay size and center the window on the
+ * pet's old spot (main.cjs adds the window's screen origin). If the user has
+ * popped out before, reopen at that remembered desktop spot instead.
+ */
+export function popOutPet(petRect: PetOverlayBounds): void {
+  if ($petOverlayActive.get() || stateUnsubs.length) {
+    return
+  }
+
+  const saved = loadSavedBounds()
+
+  if (saved) {
+    openOverlay({ bounds: saved, screen: true })
+
+    return
+  }
+
+  const width = Math.max(OVERLAY_MIN_W, Math.round(petRect.width + OVERLAY_PAD_X))
+  const height = Math.max(OVERLAY_MIN_H, Math.round(petRect.height + OVERLAY_PAD_Y))
+  const x = Math.round(petRect.x - (width - petRect.width) / 2)
+  const y = Math.round(petRect.y - (height - petRect.height) / 2)
+
+  openOverlay({ bounds: { height, width, x, y }, screen: false })
+}
+
+/**
+ * Restore the overlay on boot if the pet was popped out when the app last
+ * closed. Requires a remembered desktop spot — without one we fall back to the
+ * in-window pet rather than spawning an orphan window at the origin.
+ */
+export function restorePetOverlay(): void {
+  if (!window.hermesDesktop?.petOverlay || !$petOverlayActive.get() || stateUnsubs.length) {
+    return
+  }
+
+  const saved = loadSavedBounds()
+
+  if (!saved) {
+    $petOverlayActive.set(false)
+
+    return
+  }
+
+  openOverlay({ bounds: saved, screen: true })
+}
+
+/** Pop the pet back into the window (closes the overlay window). */
+export function popInPet(): void {
+  for (const off of stateUnsubs) {
+    off()
+  }
+
+  stateUnsubs = []
+  $petOverlayActive.set(false)
+  void window.hermesDesktop?.petOverlay?.close()
+}
+
+/** Register the handler that turns an overlay composer submit into a real send. */
+export function setPetOverlaySubmitHandler(fn: ((text: string) => void) | null): void {
+  submitHandler = fn
+}
+
+/** Register the handler that opens the app to the most recent thread (mail icon). */
+export function setPetOverlayOpenAppHandler(fn: (() => void) | null): void {
+  openAppHandler = fn
+}
+
+/**
+ * Wire the overlay→renderer control channel once. Returns a disposer. Idempotent
+ * — a second call while already wired is a no-op.
+ */
+export function initPetOverlayBridge(): () => void {
+  const api = window.hermesDesktop?.petOverlay
+
+  if (!api || controlUnsub) {
+    return () => {}
+  }
+
+  controlUnsub = api.onControl(payload => {
+    if (payload?.type === 'pop-in') {
+      popInPet()
+    } else if (payload?.type === 'ready') {
+      // The overlay just mounted — hand it the current frame.
+      pushNow()
+    } else if (payload?.type === 'submit' && typeof payload.text === 'string') {
+      submitHandler?.(payload.text)
+    } else if (payload?.type === 'bounds' && payload.bounds) {
+      // The user dragged the overlay to a new desktop spot — remember it.
+      saveBounds(payload.bounds)
+    } else if (payload?.type === 'open-app') {
+      // Mail icon: surface the app on the most recent thread (main.cjs already
+      // focused the window before forwarding this) and mark it read.
+      clearPetUnread()
+      openAppHandler?.()
+    }
+  })
+
+  return () => {
+    controlUnsub?.()
+    controlUnsub = null
+  }
+}

apps/desktop/src/store/pet.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+
+import { $petActivity, $petState, derivePetState, flashPetActivity, setPetActivity } from './pet'
+
+describe('derivePetState', () => {
+  it('rests at idle by default and uses waiting when awaiting input', () => {
+    expect(derivePetState({})).toBe('idle')
+    expect(derivePetState({ awaitingInput: true })).toBe('waiting')
+  })
+
+  it('runs when busy or a tool is executing', () => {
+    expect(derivePetState({ busy: true })).toBe('run')
+    expect(derivePetState({ toolRunning: true })).toBe('run')
+  })
+
+  it('reviews while reasoning (below tool, above bare busy)', () => {
+    expect(derivePetState({ reasoning: true })).toBe('review')
+    expect(derivePetState({ reasoning: true, busy: true })).toBe('review')
+    expect(derivePetState({ reasoning: true, toolRunning: true })).toBe('run')
+  })
+
+  it('waits (blocked on the user) above the in-flight signals', () => {
+    expect(derivePetState({ awaitingInput: true, toolRunning: true, busy: true })).toBe('waiting')
+    // but a finish beat still wins over waiting
+    expect(derivePetState({ justCompleted: true, awaitingInput: true })).toBe('wave')
+  })
+
+  it('honors the full priority chain: error > celebrate > complete > tool', () => {
+    expect(derivePetState({ error: true, celebrate: true, busy: true })).toBe('failed')
+    expect(derivePetState({ celebrate: true, justCompleted: true, toolRunning: true })).toBe('jump')
+    expect(derivePetState({ justCompleted: true, toolRunning: true })).toBe('wave')
+  })
+})
+
+describe('flashPetActivity', () => {
+  it('clears stale sibling beats so a completion never inherits a prior error', () => {
+    // A turn errors (sad), then the next turn finishes cleanly. The celebrate
+    // beat must win — error is highest priority, so a merge-only flash would
+    // keep the pet on the failed pose.
+    setPetActivity({ error: true })
+    flashPetActivity({ celebrate: true })
+
+    expect($petActivity.get().error).toBe(false)
+    expect($petState.get()).toBe('jump')
+
+    setPetActivity({})
+  })
+})

apps/desktop/src/store/pet.ts

@@ -0,0 +1,160 @@
+import { atom, computed } from 'nanostores'
+
+import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
+import { $busy } from '@/store/session'
+
+/**
+ * Petdex mascot state for the desktop floating pet.
+ *
+ * The spritesheet payload comes from the gateway `pet.info` RPC (shared with
+ * the TUI). The animation *state* is derived here from the same activity
+ * signals the chat already tracks, mirroring the priority order documented in
+ * `agent/pet/state.py` so the Python and TS surfaces never drift.
+ */
+
+export type PetState = 'idle' | 'wave' | 'run' | 'failed' | 'review' | 'jump' | 'waiting'
+
+export interface PetInfo {
+  enabled: boolean
+  slug?: string
+  displayName?: string
+  mime?: string
+  spritesheetBase64?: string
+  frameW?: number
+  frameH?: number
+  framesPerState?: number
+  // Real (padding-trimmed) frame count per state row, from the engine. Lets the
+  // canvas step only frames that exist instead of a fixed framesPerState, which
+  // would animate into the transparent padding of ragged sheets (blank flash).
+  framesByState?: Record<string, number>
+  loopMs?: number
+  scale?: number
+  stateRows?: string[]
+}
+
+export interface PetActivity {
+  busy?: boolean
+  awaitingInput?: boolean
+  toolRunning?: boolean
+  reasoning?: boolean
+  error?: boolean
+  justCompleted?: boolean
+  celebrate?: boolean
+}
+
+/**
+ * Resolve the animation state from coarse activity signals.
+ *
+ * Priority (highest first) mirrors `agent.pet.state.derive_pet_state`:
+ * error → celebrate → justCompleted → awaitingInput → toolRunning → reasoning →
+ * busy → idle. `awaitingInput` (a clarify/approval blocking on the user) outranks
+ * the in-flight signals because the turn is paused on you, not working.
+ */
+export function derivePetState(activity: PetActivity): PetState {
+  if (activity.error) {
+    return 'failed'
+  }
+
+  if (activity.celebrate) {
+    return 'jump'
+  }
+
+  if (activity.justCompleted) {
+    return 'wave'
+  }
+
+  if (activity.awaitingInput) {
+    return 'waiting'
+  }
+
+  if (activity.toolRunning) {
+    return 'run'
+  }
+
+  if (activity.reasoning) {
+    return 'review'
+  }
+
+  if (activity.busy) {
+    return 'run'
+  }
+
+  return 'idle'
+}
+
+export const $petInfo = atom<PetInfo>({ enabled: false })
+export const $petActivity = atom<PetActivity>({})
+
+/**
+ * Profile the pet RPCs should resolve against. Pets are per-profile — the active
+ * pet (`display.pet.*`) and the installed sprites live under each profile's
+ * HERMES_HOME — so every pet RPC carries this. The gateway no-ops it for the
+ * launch profile (own-profile backends already resolve it) and rebinds for any
+ * other profile, which is what makes per-profile pets work in app-global remote
+ * mode (one backend serving every profile).
+ */
+export function petProfile(): string {
+  return normalizeProfileKey($activeGatewayProfile.get())
+}
+
+/**
+ * Pet-local "you have a new message" flag, surfaced as the overlay's mail icon.
+ * Deliberately not real unread tracking: it flips on when a turn finishes while
+ * the app isn't focused, and off when the user opens the app via the mail icon
+ * (or returns to the window). No persistence — it's a glance hint, not state.
+ */
+export const $petUnread = atom(false)
+export const markPetUnread = () => $petUnread.set(true)
+export const clearPetUnread = () => $petUnread.set(false)
+
+/** Steady activity flags (toolRunning / reasoning) set + cleared by the stream. */
+export const setPetActivity = (next: Partial<PetActivity>) =>
+  $petActivity.set({ ...$petActivity.get(), ...next })
+
+let flashTimer: ReturnType<typeof setTimeout> | undefined
+
+/** Fire a transient reaction beat (error / celebrate / justCompleted) that
+ *  decays back to the steady state after `ms`.
+ *
+ *  Each beat first clears its siblings so a stale one can't win the priority
+ *  race: without this, a completion beat (`celebrate`) would merge on top of a
+ *  lingering `error`, and `derivePetState` checks `error` first — so a clean
+ *  finish would render the sad/failed pose. */
+export const flashPetActivity = (next: Partial<PetActivity>, ms = 1600) => {
+  setPetActivity({ celebrate: false, error: false, justCompleted: false, ...next })
+  clearTimeout(flashTimer)
+  flashTimer = setTimeout(
+    () => setPetActivity({ celebrate: false, error: false, justCompleted: false }),
+    ms
+  )
+}
+
+export const setPetInfo = (info: PetInfo) => $petInfo.set(info)
+
+/**
+ * The live pet state. Derives from the dedicated activity atom, falling back to
+ * the always-present `$busy` chat signal so the pet reacts out of the box.
+ *
+ * `awaitingInput` (a clarify/approval blocking on the user) is an explicit flag
+ * on `$petActivity` — set by the controller from `$attentionSessionIds` and
+ * mirrored to the pop-out overlay through the same atom, so both surfaces agree
+ * without the overlay needing the session list.
+ */
+export const $petState = computed(
+  [$petActivity, $busy],
+  (activity, busy): PetState => {
+    const live = activity.busy ?? busy
+
+    return derivePetState({
+      busy: live,
+      awaitingInput: activity.awaitingInput,
+      // Steady flags only count mid-turn — ignore stale ones once at rest so an
+      // interrupted turn can't pin the pet on `run`/`review`.
+      toolRunning: live && activity.toolRunning,
+      reasoning: live && activity.reasoning,
+      error: activity.error,
+      justCompleted: activity.justCompleted,
+      celebrate: activity.celebrate
+    })
+  }
+)

apps/desktop/src/store/preview-status.test.ts

@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  $previewStatusBySession,
+  clearPreviewArtifacts,
+  dismissPreviewArtifact,
+  recordPreviewArtifact
+} from './preview-status'
+
+beforeEach(() => $previewStatusBySession.set({}))
+
+describe('recordPreviewArtifact', () => {
+  it('appends new targets newest-last and is idempotent', () => {
+    recordPreviewArtifact('s1', '/a/index.html', '/work')
+    recordPreviewArtifact('s1', '/a/about.html', '/work')
+    recordPreviewArtifact('s1', '/a/index.html', '/work')
+
+    expect($previewStatusBySession.get().s1.map(i => i.id)).toEqual(['/a/index.html', '/a/about.html'])
+  })
+
+  it('caps the list and derives a label', () => {
+    for (const n of [1, 2, 3, 4, 5]) {
+      recordPreviewArtifact('s1', `/a/p${n}.html`, '/work')
+    }
+
+    const list = $previewStatusBySession.get().s1
+    expect(list).toHaveLength(4)
+    expect(list[0].id).toBe('/a/p2.html')
+    expect(list[3].label).toBe('p5.html')
+  })
+
+  it('dismiss and clear remove rows', () => {
+    recordPreviewArtifact('s1', '/a/index.html', '/work')
+    recordPreviewArtifact('s1', '/a/about.html', '/work')
+    dismissPreviewArtifact('s1', '/a/index.html')
+    expect($previewStatusBySession.get().s1.map(i => i.id)).toEqual(['/a/about.html'])
+
+    clearPreviewArtifacts('s1')
+    expect($previewStatusBySession.get().s1).toBeUndefined()
+  })
+})