diff --git a/index.html b/index.html
index 154b856f2..d13c00b30 100644
--- a/index.html
+++ b/index.html
@@ -6,6 +6,15 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <script>
       (() => {
+        // Auxiliary panel webviews (?window=...) skip the startup canvas:
+        // the desktop-agent panel is a transparent always-on-top window,
+        // and painting the opaque themed background here would flash a
+        // solid square before React mounts. Session windows use
+        // ?sessionKey= and keep the canvas.
+        if (new URLSearchParams(window.location.search).has("window")) {
+          return;
+        }
+
         const getDefaultAccent = (theme) =>
           theme === "dark" ? "#ffffff" : "#1a1a1a";
 
diff --git a/public/desktop-agent/berd-logo.mp4 b/public/desktop-agent/berd-logo.mp4
new file mode 100644
index 000000000..e6a8ea65d
Binary files /dev/null and b/public/desktop-agent/berd-logo.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_DangleToDangle_00001_.mp4 b/public/desktop-agent/berdy/berdy_DangleToDangle_00001_.mp4
new file mode 100644
index 000000000..8615cb022
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_DangleToDangle_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_DangleToIdle_00001_.mp4 b/public/desktop-agent/berdy/berdy_DangleToIdle_00001_.mp4
new file mode 100644
index 000000000..6ac3a1fca
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_DangleToIdle_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_DangleToSit_00001_.mp4 b/public/desktop-agent/berdy/berdy_DangleToSit_00001_.mp4
new file mode 100644
index 000000000..c172a22cf
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_DangleToSit_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_IdleToDangle_00001_.mp4 b/public/desktop-agent/berdy/berdy_IdleToDangle_00001_.mp4
new file mode 100644
index 000000000..75180e399
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_IdleToDangle_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_Idle_01_00001_.mp4 b/public/desktop-agent/berdy/berdy_Idle_01_00001_.mp4
new file mode 100644
index 000000000..1a0d7d21f
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_Idle_01_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_Idle_01_00001_.png b/public/desktop-agent/berdy/berdy_Idle_01_00001_.png
new file mode 100644
index 000000000..fa74fd76a
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_Idle_01_00001_.png differ
diff --git a/public/desktop-agent/berdy/berdy_Idle_02_00001_.mp4 b/public/desktop-agent/berdy/berdy_Idle_02_00001_.mp4
new file mode 100644
index 000000000..1b0dc5530
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_Idle_02_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_Idle_03_00001_.mp4 b/public/desktop-agent/berdy/berdy_Idle_03_00001_.mp4
new file mode 100644
index 000000000..1d2a3fb0b
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_Idle_03_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_Idle_04_00001_.mp4 b/public/desktop-agent/berdy/berdy_Idle_04_00001_.mp4
new file mode 100644
index 000000000..280281d37
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_Idle_04_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_SitToDangle_00001_.mp4 b/public/desktop-agent/berdy/berdy_SitToDangle_00001_.mp4
new file mode 100644
index 000000000..e6177aec9
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_SitToDangle_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_Sit_Idle_01_00001_.mp4 b/public/desktop-agent/berdy/berdy_Sit_Idle_01_00001_.mp4
new file mode 100644
index 000000000..89f0be0d1
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_Sit_Idle_01_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_Sit_Idle_02_00001_.mp4 b/public/desktop-agent/berdy/berdy_Sit_Idle_02_00001_.mp4
new file mode 100644
index 000000000..3ce63e913
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_Sit_Idle_02_00001_.mp4 differ
diff --git a/public/desktop-agent/berdy/berdy_Sit_Idle_03_00001_.mp4 b/public/desktop-agent/berdy/berdy_Sit_Idle_03_00001_.mp4
new file mode 100644
index 000000000..ba2cc10fa
Binary files /dev/null and b/public/desktop-agent/berdy/berdy_Sit_Idle_03_00001_.mp4 differ
diff --git a/public/desktop-agent/gloopies-22.mp4 b/public/desktop-agent/gloopies-22.mp4
new file mode 100644
index 000000000..9a3917e5a
Binary files /dev/null and b/public/desktop-agent/gloopies-22.mp4 differ
diff --git a/scripts/berdy-media.json b/scripts/berdy-media.json
new file mode 100644
index 000000000..c0547b512
--- /dev/null
+++ b/scripts/berdy-media.json
@@ -0,0 +1,107 @@
+{
+  "description": "Lossless 1.5x timing of existing HEVC-alpha MP4s. All encoded samples, alpha, edit/sample tables and endpoints unchanged; only mvhd/mdhd timescales 12288 -> 18432. Native rates: effective source speed / 1.5. No audio.",
+  "originalTimescale": 12288,
+  "timescale": 18432,
+  "sourceFrames": 122,
+  "sourceFps": 24,
+  "mediaFps": 36,
+  "durationTicks": 62472,
+  "assets": [
+    {
+      "file": "berdy_DangleToDangle_00001_.mp4",
+      "bytes": 842853,
+      "originalSha256": "4d9b4b7c1adb36420a45b45380ebbf8e487cd4f8df1775651aa74962e38304e6",
+      "sha256": "370f9b3a634c1cfa42bc36d3e0d68d6ee8dfd9ad910a21ef8224062d46ee3770",
+      "mdatSha256": "dad1b29f9e098b2dc556560f5e3cd68ab24e4a7368a08ffc8e01a30c94280010",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_DangleToIdle_00001_.mp4",
+      "bytes": 902187,
+      "originalSha256": "e8b0e7b34d238130ee069de81a9a9da886f22ffdfedc6e4ba584ab29e6a42fc7",
+      "sha256": "8f0ed09690ab00c9bf91314cadc09a2f22fa57af1382cde40f0a5530a28ed358",
+      "mdatSha256": "d25c45c3e0158ffb471c7170f26f29fc7d566f841d12cf7df6a901c1c07432e0",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_DangleToSit_00001_.mp4",
+      "bytes": 1050978,
+      "originalSha256": "6dd93e1e53ca8f5c8d0df6265f4c84825f8f81faf81d37a0868ed7849dafae1e",
+      "sha256": "eddb6a098f21c75dcd5cbdc08e7699f164453b6d34c6132abfc3b8312551771d",
+      "mdatSha256": "a2736f6a372b9f4542f96d71f5d4a06f394d3c66d93b3a5257faf7df0cd3e64d",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_IdleToDangle_00001_.mp4",
+      "bytes": 1064141,
+      "originalSha256": "1d8e63eeab2d2fa3c8bfa216ceb4154a761b7f850cbe7f9e76adc65b47c3eea3",
+      "sha256": "ca4ff1ad04391ad4cee4ca5b32738da86905b4d6e5f94a72b817b8a15de2698e",
+      "mdatSha256": "419085b141f5b9b2de18e5fc404fc93ef06bb59d0e96ad52750374cb986a9169",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_Idle_01_00001_.mp4",
+      "bytes": 905500,
+      "originalSha256": "6c7ac32132c1238799e1f0aba1d54ae2597310fb13727a920333d023fbb3128d",
+      "sha256": "feb86e8c635301a83561e9c73cf0a1aa4a14f8460a7b5297c9503133e1ca8237",
+      "mdatSha256": "0db7b0c5c39a087e3789057a60fad40ba12962aea469ef60f63d8cece7eea724",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_Idle_02_00001_.mp4",
+      "bytes": 815724,
+      "originalSha256": "916d4084d29415b499be26a34fc5b9f01caf83aba4970106365529903a5aaeb5",
+      "sha256": "877de4b6e447d10606bf6d197edf31bca5954236f0674baa9ac1b44189e03f6c",
+      "mdatSha256": "6bc86a040517b0bf8da004727f9ac91fd194ab17174ca1ceb17167924ab56634",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_Idle_03_00001_.mp4",
+      "bytes": 793758,
+      "originalSha256": "d64c8020654c3bc9546f421aff50526477bad4f6222402c43187b8640030fbef",
+      "sha256": "a08e08ab1da193103118493e3c70354eda3b7b54b2df54c4a06104748d25ba2f",
+      "mdatSha256": "96d2d5ff43d6de8c3344f2c96ffb2ee5e7b2fcd5c03cad784d66fd8d09687691",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_Idle_04_00001_.mp4",
+      "bytes": 710787,
+      "originalSha256": "d51fb9a85f065ff52735fff11a1e564e0fd2696626fb9ebb5b15a1447d4e8c60",
+      "sha256": "7d369d86e7ddddf791a4d23905f24131fca8a69700549e4246a0ba623921adfc",
+      "mdatSha256": "8401018f83ad13eb7bfd641a065763f8a01a2dcc2f4151dc115530a5ffacbfd2",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_SitToDangle_00001_.mp4",
+      "bytes": 1020745,
+      "originalSha256": "5e5db8f51097dee17c0f3591516f96e933dcb080ec89fef64a9ddacba7dd444a",
+      "sha256": "b940eb090971cdc11d0975be7b0022a49d39ca41e765bf000d90a0684cb7048b",
+      "mdatSha256": "d097e4ca66141357a519266ef76223dbd02e5ed4fffc60b418016e9c18b53e93",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_Sit_Idle_01_00001_.mp4",
+      "bytes": 787190,
+      "originalSha256": "308101f2854671e091d31646acda4c429153461673d22a6e4989953103080fbe",
+      "sha256": "34afaaff93dbeae5f27db6bdbffe5bf18f0c3c0edbc16aa7686b341b3be9b172",
+      "mdatSha256": "78019926feef1882127fc98fc4c6ca7bbf8a7fb8c18e667f59bd9d9c2c9cd2de",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_Sit_Idle_02_00001_.mp4",
+      "bytes": 925222,
+      "originalSha256": "980002a70f779e4e57b8340f78a7c3aa9e470134813726f4ba181f9a28a99d26",
+      "sha256": "f90e2c722cb01c3dbb9b9e265f4466d73d8d7d5d18a9f92e390ba74041217f8a",
+      "mdatSha256": "09ebf4098dca3dbf4a6d825d1c80df24bc12403740037f05e07d43acd97bc1b3",
+      "timescaleOffsets": [56, 308]
+    },
+    {
+      "file": "berdy_Sit_Idle_03_00001_.mp4",
+      "bytes": 881085,
+      "originalSha256": "187baf7ba514f1f89a7ccf30733a86981b6efc3a4607c3e27e92c0b2d5e93930",
+      "sha256": "4a52b20f0895bc19c4e1652ba45169b00a605deea977407df9e0274460edcc9f",
+      "mdatSha256": "42db502f5bfd5902451266023377aac9d0159f46ad80f83e5991086a865cf51f",
+      "timescaleOffsets": [56, 308]
+    }
+  ]
+}
diff --git a/scripts/check-i18n-strings.mjs b/scripts/check-i18n-strings.mjs
index a11701486..5051c126f 100644
--- a/scripts/check-i18n-strings.mjs
+++ b/scripts/check-i18n-strings.mjs
@@ -7,6 +7,7 @@ const CHECKED_PATHS = [
   "src/features/agents",
   "src/features/automations",
   "src/features/chat/ui",
+  "src/features/desktop-agent",
   "src/features/experiments",
   "src/features/home",
   "src/features/projects",
diff --git a/scripts/retime-berdy-media.py b/scripts/retime-berdy-media.py
new file mode 100644
index 000000000..7d40a40af
--- /dev/null
+++ b/scripts/retime-berdy-media.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Verify/reproduce the lossless HEVC-alpha cadence fix (Python standard library).
+
+Run from any directory:
+  python3 scripts/retime-berdy-media.py            # verify checked-in assets
+  python3 scripts/retime-berdy-media.py --apply   # retime original assets, idempotent
+  python3 scripts/retime-berdy-media.py --restore # restore exact original bytes
+
+The manifest pins original/output hashes and validated timescale field offsets.
+Only mvhd/mdhd timescales change, NOT durations in ticks, sample/edit tables,
+HEVC configuration or mdat. Movie/media clocks both speed up by 1.5. Retaining
+all samples (including alpha and endpoints) avoids re-encoding or frame removal.
+Native playback uses effective source speed / 1.5; never exceeds WebKit's 2x
+full-frame threshold. No second variant, per-frame seeks, or extra media bytes.
+"""
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import struct
+
+
+def sha(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def mdat_sha(data):
+    """Hash media payloads, including MP4 boxes with 64-bit extended sizes."""
+    digest = hashlib.sha256()
+    offset = 0
+    payload_bytes = 0
+    while offset < len(data):
+        if len(data) - offset < 8:
+            raise ValueError("Truncated MP4 box")
+        size, kind = struct.unpack_from(">I4s", data, offset)
+        header = 8
+        if size == 1:
+            if len(data) - offset < 16:
+                raise ValueError("Truncated extended MP4 box")
+            size = struct.unpack_from(">Q", data, offset + 8)[0]
+            header = 16
+        elif size == 0:
+            size = len(data) - offset
+        if size < header or offset + size > len(data):
+            raise ValueError("Invalid MP4 box size")
+        if kind == b"mdat":
+            digest.update(data[offset + header:offset + size])
+            payload_bytes += size - header
+        offset += size
+    if not payload_bytes:
+        raise ValueError("Missing media payload")
+    return digest.hexdigest()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    modes = parser.add_mutually_exclusive_group()
+    modes.add_argument("--apply", action="store_true")
+    modes.add_argument("--restore", action="store_true")
+    args = parser.parse_args()
+    root = Path(__file__).resolve().parent.parent
+    manifest = json.loads((root / "scripts/berdy-media.json").read_text())
+    directory = root / "public/desktop-agent/berdy"
+    pending = []
+    for entry in manifest["assets"]:
+        path = directory / entry["file"]
+        data = path.read_bytes()
+        digest = sha(data)
+        if len(data) != entry["bytes"] or digest not in (
+            entry["originalSha256"], entry["sha256"]
+        ):
+            raise SystemExit(f"Refusing unknown media: {path}")
+        if not args.apply and not args.restore and digest != entry["sha256"]:
+            raise SystemExit(f"Original media needs --apply: {path}")
+        # Validate each transformation in both directions, even in verify mode.
+        original = bytearray(data)
+        retimed = bytearray(data)
+        for offset in entry["timescaleOffsets"]:
+            if data[offset - 16:offset - 12] not in (b"mvhd", b"mdhd"):
+                raise SystemExit(f"Invalid clock offset: {path}")
+            struct.pack_into(">I", original, offset, manifest["originalTimescale"])
+            struct.pack_into(">I", retimed, offset, manifest["timescale"])
+        if sha(original) != entry["originalSha256"] or sha(retimed) != entry["sha256"]:
+            raise SystemExit(f"Unexpected timing transformation: {path}")
+        if mdat_sha(original) != entry["mdatSha256"] or mdat_sha(retimed) != entry["mdatSha256"]:
+            raise SystemExit(f"Unexpected media payload: {path}")
+        output = original if args.restore else retimed
+        if (args.apply or args.restore) and output != data:
+            pending.append((path, output))
+    # Fail validation of the entire catalog before writing any file.
+    for path, data in pending:
+        path.write_bytes(data)
+    print(f"Verified {len(manifest['assets'])} HEVC-alpha clips; changed {len(pending)}.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock
index eeb77ae37..9a735bd10 100644
--- a/src-tauri/Cargo.lock
+++ b/src-tauri/Cargo.lock
@@ -34,7 +34,10 @@ dependencies = [
  "objc2-app-kit",
  "objc2-avf-audio",
  "objc2-core-audio",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
  "objc2-foundation",
+ "objc2-screen-capture-kit",
  "objc2-user-notifications",
  "percent-encoding",
  "plist",
@@ -51,11 +54,13 @@ dependencies = [
  "tar",
  "tauri",
  "tauri-build",
+ "tauri-nspanel",
  "tauri-plugin-app-test-driver",
  "tauri-plugin-berdctl",
  "tauri-plugin-clipboard-manager",
  "tauri-plugin-deep-link",
  "tauri-plugin-dialog",
+ "tauri-plugin-global-shortcut",
  "tauri-plugin-log",
  "tauri-plugin-notification",
  "tauri-plugin-opener",
@@ -672,6 +677,12 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "block"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d8c1fef690941d3e7788d328517591fecc684c084084702d6ff1641e993699a"
+
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
@@ -1043,6 +1054,35 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "cocoa"
+version = "0.26.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad36507aeb7e16159dfe68db81ccc27571c3ccd4b76fb2fb72fc59e7a4b1b64c"
+dependencies = [
+ "bitflags 2.13.1",
+ "block",
+ "cocoa-foundation",
+ "core-foundation 0.10.1",
+ "core-graphics 0.24.0",
+ "foreign-types 0.5.0",
+ "libc",
+ "objc",
+]
+
+[[package]]
+name = "cocoa-foundation"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "81411967c50ee9a1fc11365f8c585f863a22a9697c89239c452292c40ba79b0d"
+dependencies = [
+ "bitflags 2.13.1",
+ "block",
+ "core-foundation 0.10.1",
+ "core-graphics-types",
+ "objc",
+]
+
 [[package]]
 name = "colorchoice"
 version = "1.0.5"
@@ -1164,6 +1204,19 @@ version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
+[[package]]
+name = "core-graphics"
+version = "0.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa95a34622365fa5bbf40b20b75dba8dfa8c94c734aea8ac9a5ca38af14316f1"
+dependencies = [
+ "bitflags 2.13.1",
+ "core-foundation 0.10.1",
+ "core-graphics-types",
+ "foreign-types 0.5.0",
+ "libc",
+]
+
 [[package]]
 name = "core-graphics"
 version = "0.25.0"
@@ -2494,6 +2547,24 @@ version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
 
+[[package]]
+name = "global-hotkey"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c386b0a4a70cb2d39fffd74480f985b6f0bfbcb934b6a6b6b7e630e448f242e"
+dependencies = [
+ "crossbeam-channel",
+ "keyboard-types",
+ "objc2",
+ "objc2-app-kit",
+ "once_cell",
+ "serde",
+ "thiserror 2.0.20",
+ "windows-sys 0.59.0",
+ "x11rb",
+ "xkeysym",
+]
+
 [[package]]
 name = "globset"
 version = "0.4.20"
@@ -3501,6 +3572,15 @@ version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc04a4c58212d57930a24bf47d3fa87485264a3a054e9c10e042eb373573ad3c"
 
+[[package]]
+name = "malloc_buf"
+version = "0.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "62bb907fe88d54d8d9ce32a3cceab4218ed2f6b7d35617cafe9adf84e43919cb"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "markup5ever"
 version = "0.38.0"
@@ -3933,6 +4013,26 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "objc"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "915b1b472bc21c53464d6c8461c9d3af805ba1ef837e1cac254428f4a77177b1"
+dependencies = [
+ "malloc_buf",
+]
+
+[[package]]
+name = "objc-foundation"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1add1b659e36c9607c7aab864a76c7a4c2760cd0cd2e120f3fb8b952c7e22bf9"
+dependencies = [
+ "block",
+ "objc",
+ "objc_id",
+]
+
 [[package]]
 name = "objc2"
 version = "0.6.4"
@@ -3980,6 +4080,16 @@ dependencies = [
  "objc2-foundation",
 ]
 
+[[package]]
+name = "objc2-av-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "478ae33fcac9df0a18db8302387c666b8ef08a3e2d62b510ca4fc278a384b6c0"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
 [[package]]
 name = "objc2-avf-audio"
 version = "0.3.2"
@@ -4061,10 +4171,13 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
 dependencies = [
  "bitflags 2.13.1",
+ "block2",
  "dispatch2",
+ "libc",
  "objc2",
  "objc2-core-foundation",
  "objc2-io-surface",
+ "objc2-metal",
 ]
 
 [[package]]
@@ -4087,6 +4200,21 @@ dependencies = [
  "objc2-foundation",
 ]
 
+[[package]]
+name = "objc2-core-media"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05ec576860167a15dd9fce7fbee7512beb4e31f532159d3482d1f9c6caedf31d"
+dependencies = [
+ "bitflags 2.13.1",
+ "dispatch2",
+ "objc2",
+ "objc2-core-audio",
+ "objc2-core-audio-types",
+ "objc2-core-foundation",
+ "objc2-core-video",
+]
+
 [[package]]
 name = "objc2-core-text"
 version = "0.3.2"
@@ -4151,6 +4279,17 @@ dependencies = [
  "objc2-core-foundation",
 ]
 
+[[package]]
+name = "objc2-metal"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a0125f776a10d00af4152d74616409f0d4a2053a6f57fa5b7d6aa2854ac04794"
+dependencies = [
+ "bitflags 2.13.1",
+ "objc2",
+ "objc2-foundation",
+]
+
 [[package]]
 name = "objc2-osa-kit"
 version = "0.3.2"
@@ -4175,6 +4314,25 @@ dependencies = [
  "objc2-foundation",
 ]
 
+[[package]]
+name = "objc2-screen-capture-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74b7c5390f477482f001bc354d6571a70db7e4f8d5288e860c45521fbce11394"
+dependencies = [
+ "bitflags 2.13.1",
+ "block2",
+ "dispatch2",
+ "libc",
+ "objc2",
+ "objc2-av-foundation",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-core-media",
+ "objc2-foundation",
+ "objc2-uniform-type-identifiers",
+]
+
 [[package]]
 name = "objc2-ui-kit"
 version = "0.3.2"
@@ -4196,6 +4354,16 @@ dependencies = [
  "objc2-user-notifications",
 ]
 
+[[package]]
+name = "objc2-uniform-type-identifiers"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7902ac02859fc1f7045f8b598c63f1ae0cc7efeaa06a9bc9f3d9a3c955974fa4"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
 [[package]]
 name = "objc2-user-notifications"
 version = "0.3.2"
@@ -4223,6 +4391,15 @@ dependencies = [
  "objc2-foundation",
 ]
 
+[[package]]
+name = "objc_id"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c92d4ddb4bd7b50d730c215ff871754d0da6b2178849f8a2a2ab69712d0c073b"
+dependencies = [
+ "objc",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -4350,7 +4527,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7d8fae84b431384b68627d0f9b3b1245fcf9f46f6c0e3dc902e9dce64edd1967"
 dependencies = [
  "libc",
- "windows-sys 0.45.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -6469,7 +6646,7 @@ dependencies = [
  "bitflags 2.13.1",
  "block2",
  "core-foundation 0.10.1",
- "core-graphics",
+ "core-graphics 0.25.0",
  "crossbeam-channel",
  "dbus",
  "dispatch2",
@@ -6642,6 +6819,22 @@ dependencies = [
  "tauri-utils",
 ]
 
+[[package]]
+name = "tauri-nspanel"
+version = "2.0.1"
+source = "git+https://github.com/ahkohd/tauri-nspanel?rev=18ffb9a201fbf6fedfaa382fd4b92315ea30ab1a#18ffb9a201fbf6fedfaa382fd4b92315ea30ab1a"
+dependencies = [
+ "bitflags 2.13.1",
+ "block",
+ "cocoa",
+ "core-foundation 0.10.1",
+ "core-graphics 0.25.0",
+ "objc",
+ "objc-foundation",
+ "objc_id",
+ "tauri",
+]
+
 [[package]]
 name = "tauri-plugin"
 version = "2.6.3"
@@ -6763,6 +6956,21 @@ dependencies = [
  "url",
 ]
 
+[[package]]
+name = "tauri-plugin-global-shortcut"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4dd9f4c5136c09cd962da0c86dc4accd4666db2ea591cf16e6597435843bd2b"
+dependencies = [
+ "global-hotkey",
+ "log",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "thiserror 2.0.20",
+]
+
 [[package]]
 name = "tauri-plugin-log"
 version = "2.9.0"
@@ -7038,7 +7246,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.3.4",
+ "getrandom 0.4.3",
  "once_cell",
  "rustix",
  "windows-sys 0.61.2",
@@ -8994,6 +9202,12 @@ dependencies = [
  "rustix",
 ]
 
+[[package]]
+name = "xkeysym"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9cc00251562a284751c9973bace760d86c0276c471b4be569fe6b068ee97a56"
+
 [[package]]
 name = "yaml_serde"
 version = "0.10.5"
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
index 1f7ced02b..7e71be40e 100644
--- a/src-tauri/Cargo.toml
+++ b/src-tauri/Cargo.toml
@@ -64,7 +64,7 @@ yaml_serde = "0.10.4"
 sha2 = "0.10"
 sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio-rustls", "sqlite", "migrate", "macros"] }
 sysinfo = { version = "0.33", default-features = false, features = ["system"] }
-tauri = { version = "2", features = ["protocol-asset"] }
+tauri = { version = "2", features = ["protocol-asset", "macos-private-api"] }
 toml = "1.1.4"
 tauri-plugin-berdctl = { path = "plugins/berdctl" }
 tauri-plugin-app-test-driver = { path = "plugins/app-test-driver" }
@@ -104,9 +104,22 @@ objc2 = "0.6"
 objc2-app-kit = { version = "0.3.2", features = ["NSApplication", "NSRunningApplication", "NSImage", "NSMenu", "NSMenuItem", "NSAlert", "NSButton", "NSControl", "NSCell", "NSResponder", "NSView"] }
 objc2-avf-audio = { version = "0.3.2", features = ["AVAudioApplication", "block2"] }
 objc2-core-audio = "0.3.2"
-objc2-foundation = { version = "0.3.2", features = ["NSDictionary", "NSError", "NSFileManager", "NSObject", "NSProcessInfo", "NSString", "NSURL"] }
+objc2-foundation = { version = "0.3.2", features = ["NSDictionary", "NSError", "NSFileManager", "NSObject", "NSProcessInfo", "NSString", "NSURL", "NSValue"] }
+# Perch mode (desktop_agent): CGWindowList enumeration, CF containers +
+# CGRect/CGPoint interchange, and ScreenCaptureKit window capture. All
+# crates.io, same objc2 0.3 family as the existing app-kit/foundation
+# pins. AXUIElement has no objc2 wrapper — perch.rs links the raw
+# ApplicationServices C API directly, so there is deliberately NO
+# objc2-application-services dependency.
+objc2-core-foundation = "0.3.2"
+objc2-core-graphics = { version = "0.3.2", features = ["CGWindow"] }
+objc2-screen-capture-kit = "0.3.2"
 objc2-user-notifications = "0.3.2"
 rodio = { version = "0.22", default-features = false, features = ["playback"] }
+# Pinned to the rev validated by the desktop-agent dependency spike.
+# Treat updates as review-worthy — community plugin, swizzling approach.
+tauri-nspanel = { git = "https://github.com/ahkohd/tauri-nspanel", rev = "18ffb9a201fbf6fedfaa382fd4b92315ea30ab1a" }
+tauri-plugin-global-shortcut = "2"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 keyring = { version = "3.6.3", default-features = false, features = ["sync-secret-service", "vendored"] }
diff --git a/src-tauri/capabilities/desktop-agent.json b/src-tauri/capabilities/desktop-agent.json
new file mode 100644
index 000000000..a99de37e4
--- /dev/null
+++ b/src-tauri/capabilities/desktop-agent.json
@@ -0,0 +1,8 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "desktop-agent",
+  "description": "Capability for the Berd Desktop Agent panel window",
+  "platforms": ["macOS"],
+  "windows": ["desktop-agent"],
+  "permissions": ["core:default"]
+}
diff --git a/src-tauri/gen/schemas/acl-manifests.json b/src-tauri/gen/schemas/acl-manifests.json
index 52de0b2e6..2abf86407 100644
--- a/src-tauri/gen/schemas/acl-manifests.json
+++ b/src-tauri/gen/schemas/acl-manifests.json
@@ -1 +1 @@
-{"app-test-driver":{"default_permission":{"identifier":"default","description":"Default permissions for the app test driver plugin.\n","permissions":["allow-driver-result"]},"permissions":{"allow-driver-result":{"identifier":"allow-driver-result","description":"Enables the driver_result command without any pre-configured scope.","commands":{"allow":["driver_result"],"deny":[]}},"deny-driver-result":{"identifier":"deny-driver-result","description":"Denies the driver_result command without any pre-configured scope.","commands":{"allow":[],"deny":["driver_result"]}}},"permission_sets":{},"global_scope_schema":null},"berdctl":{"default_permission":{"identifier":"default","description":"Default permissions for the app control plugin (the loopback HTTP broker for\nthe berdctl CLI). Grants the main window access to the broker lifecycle,\ntimeout, and bridge-result commands.\n","permissions":["allow-start","allow-stop","allow-status","allow-set-timeouts","allow-submit-result"]},"permissions":{"allow-set-timeouts":{"identifier":"allow-set-timeouts","description":"Enables the set_timeouts command without any pre-configured scope.","commands":{"allow":["set_timeouts"],"deny":[]}},"allow-start":{"identifier":"allow-start","description":"Enables the start command without any pre-configured scope.","commands":{"allow":["start"],"deny":[]}},"allow-status":{"identifier":"allow-status","description":"Enables the status command without any pre-configured scope.","commands":{"allow":["status"],"deny":[]}},"allow-stop":{"identifier":"allow-stop","description":"Enables the stop command without any pre-configured scope.","commands":{"allow":["stop"],"deny":[]}},"allow-submit-result":{"identifier":"allow-submit-result","description":"Enables the submit_result command without any pre-configured scope.","commands":{"allow":["submit_result"],"deny":[]}},"deny-set-timeouts":{"identifier":"deny-set-timeouts","description":"Denies the set_timeouts command without any pre-configured scope.","commands":{"allow":[],"deny":["set_timeouts"]}},"deny-start":{"identifier":"deny-start","description":"Denies the start command without any pre-configured scope.","commands":{"allow":[],"deny":["start"]}},"deny-status":{"identifier":"deny-status","description":"Denies the status command without any pre-configured scope.","commands":{"allow":[],"deny":["status"]}},"deny-stop":{"identifier":"deny-stop","description":"Denies the stop command without any pre-configured scope.","commands":{"allow":[],"deny":["stop"]}},"deny-submit-result":{"identifier":"deny-submit-result","description":"Denies the submit_result command without any pre-configured scope.","commands":{"allow":[],"deny":["submit_result"]}}},"permission_sets":{},"global_scope_schema":null},"clipboard-manager":{"default_permission":{"identifier":"default","description":"No features are enabled by default, as we believe\nthe clipboard can be inherently dangerous and it is \napplication specific if read and/or write access is needed.\n\nClipboard interaction needs to be explicitly enabled.\n","permissions":[]},"permissions":{"allow-clear":{"identifier":"allow-clear","description":"Enables the clear command without any pre-configured scope.","commands":{"allow":["clear"],"deny":[]}},"allow-read-image":{"identifier":"allow-read-image","description":"Enables the read_image command without any pre-configured scope.","commands":{"allow":["read_image"],"deny":[]}},"allow-read-text":{"identifier":"allow-read-text","description":"Enables the read_text command without any pre-configured scope.","commands":{"allow":["read_text"],"deny":[]}},"allow-write-html":{"identifier":"allow-write-html","description":"Enables the write_html command without any pre-configured scope.","commands":{"allow":["write_html"],"deny":[]}},"allow-write-image":{"identifier":"allow-write-image","description":"Enables the write_image command without any pre-configured scope.","commands":{"allow":["write_image"],"deny":[]}},"allow-write-text":{"identifier":"allow-write-text","description":"Enables the write_text command without any pre-configured scope.","commands":{"allow":["write_text"],"deny":[]}},"deny-clear":{"identifier":"deny-clear","description":"Denies the clear command without any pre-configured scope.","commands":{"allow":[],"deny":["clear"]}},"deny-read-image":{"identifier":"deny-read-image","description":"Denies the read_image command without any pre-configured scope.","commands":{"allow":[],"deny":["read_image"]}},"deny-read-text":{"identifier":"deny-read-text","description":"Denies the read_text command without any pre-configured scope.","commands":{"allow":[],"deny":["read_text"]}},"deny-write-html":{"identifier":"deny-write-html","description":"Denies the write_html command without any pre-configured scope.","commands":{"allow":[],"deny":["write_html"]}},"deny-write-image":{"identifier":"deny-write-image","description":"Denies the write_image command without any pre-configured scope.","commands":{"allow":[],"deny":["write_image"]}},"deny-write-text":{"identifier":"deny-write-text","description":"Denies the write_text command without any pre-configured scope.","commands":{"allow":[],"deny":["write_text"]}}},"permission_sets":{},"global_scope_schema":null},"core":{"default_permission":{"identifier":"default","description":"Default core plugins set.","permissions":["core:path:default","core:event:default","core:window:default","core:webview:default","core:app:default","core:image:default","core:resources:default","core:menu:default","core:tray:default"]},"permissions":{},"permission_sets":{},"global_scope_schema":null},"core:app":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin.","permissions":["allow-version","allow-name","allow-tauri-version","allow-identifier","allow-bundle-type","allow-register-listener","allow-remove-listener","allow-supports-multiple-windows"]},"permissions":{"allow-app-hide":{"identifier":"allow-app-hide","description":"Enables the app_hide command without any pre-configured scope.","commands":{"allow":["app_hide"],"deny":[]}},"allow-app-show":{"identifier":"allow-app-show","description":"Enables the app_show command without any pre-configured scope.","commands":{"allow":["app_show"],"deny":[]}},"allow-bundle-type":{"identifier":"allow-bundle-type","description":"Enables the bundle_type command without any pre-configured scope.","commands":{"allow":["bundle_type"],"deny":[]}},"allow-default-window-icon":{"identifier":"allow-default-window-icon","description":"Enables the default_window_icon command without any pre-configured scope.","commands":{"allow":["default_window_icon"],"deny":[]}},"allow-fetch-data-store-identifiers":{"identifier":"allow-fetch-data-store-identifiers","description":"Enables the fetch_data_store_identifiers command without any pre-configured scope.","commands":{"allow":["fetch_data_store_identifiers"],"deny":[]}},"allow-identifier":{"identifier":"allow-identifier","description":"Enables the identifier command without any pre-configured scope.","commands":{"allow":["identifier"],"deny":[]}},"allow-name":{"identifier":"allow-name","description":"Enables the name command without any pre-configured scope.","commands":{"allow":["name"],"deny":[]}},"allow-register-listener":{"identifier":"allow-register-listener","description":"Enables the register_listener command without any pre-configured scope.","commands":{"allow":["register_listener"],"deny":[]}},"allow-remove-data-store":{"identifier":"allow-remove-data-store","description":"Enables the remove_data_store command without any pre-configured scope.","commands":{"allow":["remove_data_store"],"deny":[]}},"allow-remove-listener":{"identifier":"allow-remove-listener","description":"Enables the remove_listener command without any pre-configured scope.","commands":{"allow":["remove_listener"],"deny":[]}},"allow-set-app-theme":{"identifier":"allow-set-app-theme","description":"Enables the set_app_theme command without any pre-configured scope.","commands":{"allow":["set_app_theme"],"deny":[]}},"allow-set-dock-visibility":{"identifier":"allow-set-dock-visibility","description":"Enables the set_dock_visibility command without any pre-configured scope.","commands":{"allow":["set_dock_visibility"],"deny":[]}},"allow-supports-multiple-windows":{"identifier":"allow-supports-multiple-windows","description":"Enables the supports_multiple_windows command without any pre-configured scope.","commands":{"allow":["supports_multiple_windows"],"deny":[]}},"allow-tauri-version":{"identifier":"allow-tauri-version","description":"Enables the tauri_version command without any pre-configured scope.","commands":{"allow":["tauri_version"],"deny":[]}},"allow-version":{"identifier":"allow-version","description":"Enables the version command without any pre-configured scope.","commands":{"allow":["version"],"deny":[]}},"deny-app-hide":{"identifier":"deny-app-hide","description":"Denies the app_hide command without any pre-configured scope.","commands":{"allow":[],"deny":["app_hide"]}},"deny-app-show":{"identifier":"deny-app-show","description":"Denies the app_show command without any pre-configured scope.","commands":{"allow":[],"deny":["app_show"]}},"deny-bundle-type":{"identifier":"deny-bundle-type","description":"Denies the bundle_type command without any pre-configured scope.","commands":{"allow":[],"deny":["bundle_type"]}},"deny-default-window-icon":{"identifier":"deny-default-window-icon","description":"Denies the default_window_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["default_window_icon"]}},"deny-fetch-data-store-identifiers":{"identifier":"deny-fetch-data-store-identifiers","description":"Denies the fetch_data_store_identifiers command without any pre-configured scope.","commands":{"allow":[],"deny":["fetch_data_store_identifiers"]}},"deny-identifier":{"identifier":"deny-identifier","description":"Denies the identifier command without any pre-configured scope.","commands":{"allow":[],"deny":["identifier"]}},"deny-name":{"identifier":"deny-name","description":"Denies the name command without any pre-configured scope.","commands":{"allow":[],"deny":["name"]}},"deny-register-listener":{"identifier":"deny-register-listener","description":"Denies the register_listener command without any pre-configured scope.","commands":{"allow":[],"deny":["register_listener"]}},"deny-remove-data-store":{"identifier":"deny-remove-data-store","description":"Denies the remove_data_store command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_data_store"]}},"deny-remove-listener":{"identifier":"deny-remove-listener","description":"Denies the remove_listener command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_listener"]}},"deny-set-app-theme":{"identifier":"deny-set-app-theme","description":"Denies the set_app_theme command without any pre-configured scope.","commands":{"allow":[],"deny":["set_app_theme"]}},"deny-set-dock-visibility":{"identifier":"deny-set-dock-visibility","description":"Denies the set_dock_visibility command without any pre-configured scope.","commands":{"allow":[],"deny":["set_dock_visibility"]}},"deny-supports-multiple-windows":{"identifier":"deny-supports-multiple-windows","description":"Denies the supports_multiple_windows command without any pre-configured scope.","commands":{"allow":[],"deny":["supports_multiple_windows"]}},"deny-tauri-version":{"identifier":"deny-tauri-version","description":"Denies the tauri_version command without any pre-configured scope.","commands":{"allow":[],"deny":["tauri_version"]}},"deny-version":{"identifier":"deny-version","description":"Denies the version command without any pre-configured scope.","commands":{"allow":[],"deny":["version"]}}},"permission_sets":{},"global_scope_schema":null},"core:event":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-listen","allow-unlisten","allow-emit","allow-emit-to"]},"permissions":{"allow-emit":{"identifier":"allow-emit","description":"Enables the emit command without any pre-configured scope.","commands":{"allow":["emit"],"deny":[]}},"allow-emit-to":{"identifier":"allow-emit-to","description":"Enables the emit_to command without any pre-configured scope.","commands":{"allow":["emit_to"],"deny":[]}},"allow-listen":{"identifier":"allow-listen","description":"Enables the listen command without any pre-configured scope.","commands":{"allow":["listen"],"deny":[]}},"allow-unlisten":{"identifier":"allow-unlisten","description":"Enables the unlisten command without any pre-configured scope.","commands":{"allow":["unlisten"],"deny":[]}},"deny-emit":{"identifier":"deny-emit","description":"Denies the emit command without any pre-configured scope.","commands":{"allow":[],"deny":["emit"]}},"deny-emit-to":{"identifier":"deny-emit-to","description":"Denies the emit_to command without any pre-configured scope.","commands":{"allow":[],"deny":["emit_to"]}},"deny-listen":{"identifier":"deny-listen","description":"Denies the listen command without any pre-configured scope.","commands":{"allow":[],"deny":["listen"]}},"deny-unlisten":{"identifier":"deny-unlisten","description":"Denies the unlisten command without any pre-configured scope.","commands":{"allow":[],"deny":["unlisten"]}}},"permission_sets":{},"global_scope_schema":null},"core:image":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-new","allow-from-bytes","allow-from-path","allow-rgba","allow-size"]},"permissions":{"allow-from-bytes":{"identifier":"allow-from-bytes","description":"Enables the from_bytes command without any pre-configured scope.","commands":{"allow":["from_bytes"],"deny":[]}},"allow-from-path":{"identifier":"allow-from-path","description":"Enables the from_path command without any pre-configured scope.","commands":{"allow":["from_path"],"deny":[]}},"allow-new":{"identifier":"allow-new","description":"Enables the new command without any pre-configured scope.","commands":{"allow":["new"],"deny":[]}},"allow-rgba":{"identifier":"allow-rgba","description":"Enables the rgba command without any pre-configured scope.","commands":{"allow":["rgba"],"deny":[]}},"allow-size":{"identifier":"allow-size","description":"Enables the size command without any pre-configured scope.","commands":{"allow":["size"],"deny":[]}},"deny-from-bytes":{"identifier":"deny-from-bytes","description":"Denies the from_bytes command without any pre-configured scope.","commands":{"allow":[],"deny":["from_bytes"]}},"deny-from-path":{"identifier":"deny-from-path","description":"Denies the from_path command without any pre-configured scope.","commands":{"allow":[],"deny":["from_path"]}},"deny-new":{"identifier":"deny-new","description":"Denies the new command without any pre-configured scope.","commands":{"allow":[],"deny":["new"]}},"deny-rgba":{"identifier":"deny-rgba","description":"Denies the rgba command without any pre-configured scope.","commands":{"allow":[],"deny":["rgba"]}},"deny-size":{"identifier":"deny-size","description":"Denies the size command without any pre-configured scope.","commands":{"allow":[],"deny":["size"]}}},"permission_sets":{},"global_scope_schema":null},"core:menu":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-new","allow-append","allow-prepend","allow-insert","allow-remove","allow-remove-at","allow-items","allow-get","allow-popup","allow-create-default","allow-set-as-app-menu","allow-set-as-window-menu","allow-text","allow-set-text","allow-is-enabled","allow-set-enabled","allow-set-accelerator","allow-set-as-windows-menu-for-nsapp","allow-set-as-help-menu-for-nsapp","allow-is-checked","allow-set-checked","allow-set-icon"]},"permissions":{"allow-append":{"identifier":"allow-append","description":"Enables the append command without any pre-configured scope.","commands":{"allow":["append"],"deny":[]}},"allow-create-default":{"identifier":"allow-create-default","description":"Enables the create_default command without any pre-configured scope.","commands":{"allow":["create_default"],"deny":[]}},"allow-get":{"identifier":"allow-get","description":"Enables the get command without any pre-configured scope.","commands":{"allow":["get"],"deny":[]}},"allow-insert":{"identifier":"allow-insert","description":"Enables the insert command without any pre-configured scope.","commands":{"allow":["insert"],"deny":[]}},"allow-is-checked":{"identifier":"allow-is-checked","description":"Enables the is_checked command without any pre-configured scope.","commands":{"allow":["is_checked"],"deny":[]}},"allow-is-enabled":{"identifier":"allow-is-enabled","description":"Enables the is_enabled command without any pre-configured scope.","commands":{"allow":["is_enabled"],"deny":[]}},"allow-items":{"identifier":"allow-items","description":"Enables the items command without any pre-configured scope.","commands":{"allow":["items"],"deny":[]}},"allow-new":{"identifier":"allow-new","description":"Enables the new command without any pre-configured scope.","commands":{"allow":["new"],"deny":[]}},"allow-popup":{"identifier":"allow-popup","description":"Enables the popup command without any pre-configured scope.","commands":{"allow":["popup"],"deny":[]}},"allow-prepend":{"identifier":"allow-prepend","description":"Enables the prepend command without any pre-configured scope.","commands":{"allow":["prepend"],"deny":[]}},"allow-remove":{"identifier":"allow-remove","description":"Enables the remove command without any pre-configured scope.","commands":{"allow":["remove"],"deny":[]}},"allow-remove-at":{"identifier":"allow-remove-at","description":"Enables the remove_at command without any pre-configured scope.","commands":{"allow":["remove_at"],"deny":[]}},"allow-set-accelerator":{"identifier":"allow-set-accelerator","description":"Enables the set_accelerator command without any pre-configured scope.","commands":{"allow":["set_accelerator"],"deny":[]}},"allow-set-as-app-menu":{"identifier":"allow-set-as-app-menu","description":"Enables the set_as_app_menu command without any pre-configured scope.","commands":{"allow":["set_as_app_menu"],"deny":[]}},"allow-set-as-help-menu-for-nsapp":{"identifier":"allow-set-as-help-menu-for-nsapp","description":"Enables the set_as_help_menu_for_nsapp command without any pre-configured scope.","commands":{"allow":["set_as_help_menu_for_nsapp"],"deny":[]}},"allow-set-as-window-menu":{"identifier":"allow-set-as-window-menu","description":"Enables the set_as_window_menu command without any pre-configured scope.","commands":{"allow":["set_as_window_menu"],"deny":[]}},"allow-set-as-windows-menu-for-nsapp":{"identifier":"allow-set-as-windows-menu-for-nsapp","description":"Enables the set_as_windows_menu_for_nsapp command without any pre-configured scope.","commands":{"allow":["set_as_windows_menu_for_nsapp"],"deny":[]}},"allow-set-checked":{"identifier":"allow-set-checked","description":"Enables the set_checked command without any pre-configured scope.","commands":{"allow":["set_checked"],"deny":[]}},"allow-set-enabled":{"identifier":"allow-set-enabled","description":"Enables the set_enabled command without any pre-configured scope.","commands":{"allow":["set_enabled"],"deny":[]}},"allow-set-icon":{"identifier":"allow-set-icon","description":"Enables the set_icon command without any pre-configured scope.","commands":{"allow":["set_icon"],"deny":[]}},"allow-set-text":{"identifier":"allow-set-text","description":"Enables the set_text command without any pre-configured scope.","commands":{"allow":["set_text"],"deny":[]}},"allow-text":{"identifier":"allow-text","description":"Enables the text command without any pre-configured scope.","commands":{"allow":["text"],"deny":[]}},"deny-append":{"identifier":"deny-append","description":"Denies the append command without any pre-configured scope.","commands":{"allow":[],"deny":["append"]}},"deny-create-default":{"identifier":"deny-create-default","description":"Denies the create_default command without any pre-configured scope.","commands":{"allow":[],"deny":["create_default"]}},"deny-get":{"identifier":"deny-get","description":"Denies the get command without any pre-configured scope.","commands":{"allow":[],"deny":["get"]}},"deny-insert":{"identifier":"deny-insert","description":"Denies the insert command without any pre-configured scope.","commands":{"allow":[],"deny":["insert"]}},"deny-is-checked":{"identifier":"deny-is-checked","description":"Denies the is_checked command without any pre-configured scope.","commands":{"allow":[],"deny":["is_checked"]}},"deny-is-enabled":{"identifier":"deny-is-enabled","description":"Denies the is_enabled command without any pre-configured scope.","commands":{"allow":[],"deny":["is_enabled"]}},"deny-items":{"identifier":"deny-items","description":"Denies the items command without any pre-configured scope.","commands":{"allow":[],"deny":["items"]}},"deny-new":{"identifier":"deny-new","description":"Denies the new command without any pre-configured scope.","commands":{"allow":[],"deny":["new"]}},"deny-popup":{"identifier":"deny-popup","description":"Denies the popup command without any pre-configured scope.","commands":{"allow":[],"deny":["popup"]}},"deny-prepend":{"identifier":"deny-prepend","description":"Denies the prepend command without any pre-configured scope.","commands":{"allow":[],"deny":["prepend"]}},"deny-remove":{"identifier":"deny-remove","description":"Denies the remove command without any pre-configured scope.","commands":{"allow":[],"deny":["remove"]}},"deny-remove-at":{"identifier":"deny-remove-at","description":"Denies the remove_at command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_at"]}},"deny-set-accelerator":{"identifier":"deny-set-accelerator","description":"Denies the set_accelerator command without any pre-configured scope.","commands":{"allow":[],"deny":["set_accelerator"]}},"deny-set-as-app-menu":{"identifier":"deny-set-as-app-menu","description":"Denies the set_as_app_menu command without any pre-configured scope.","commands":{"allow":[],"deny":["set_as_app_menu"]}},"deny-set-as-help-menu-for-nsapp":{"identifier":"deny-set-as-help-menu-for-nsapp","description":"Denies the set_as_help_menu_for_nsapp command without any pre-configured scope.","commands":{"allow":[],"deny":["set_as_help_menu_for_nsapp"]}},"deny-set-as-window-menu":{"identifier":"deny-set-as-window-menu","description":"Denies the set_as_window_menu command without any pre-configured scope.","commands":{"allow":[],"deny":["set_as_window_menu"]}},"deny-set-as-windows-menu-for-nsapp":{"identifier":"deny-set-as-windows-menu-for-nsapp","description":"Denies the set_as_windows_menu_for_nsapp command without any pre-configured scope.","commands":{"allow":[],"deny":["set_as_windows_menu_for_nsapp"]}},"deny-set-checked":{"identifier":"deny-set-checked","description":"Denies the set_checked command without any pre-configured scope.","commands":{"allow":[],"deny":["set_checked"]}},"deny-set-enabled":{"identifier":"deny-set-enabled","description":"Denies the set_enabled command without any pre-configured scope.","commands":{"allow":[],"deny":["set_enabled"]}},"deny-set-icon":{"identifier":"deny-set-icon","description":"Denies the set_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon"]}},"deny-set-text":{"identifier":"deny-set-text","description":"Denies the set_text command without any pre-configured scope.","commands":{"allow":[],"deny":["set_text"]}},"deny-text":{"identifier":"deny-text","description":"Denies the text command without any pre-configured scope.","commands":{"allow":[],"deny":["text"]}}},"permission_sets":{},"global_scope_schema":null},"core:path":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-resolve-directory","allow-resolve","allow-normalize","allow-join","allow-dirname","allow-extname","allow-basename","allow-is-absolute"]},"permissions":{"allow-basename":{"identifier":"allow-basename","description":"Enables the basename command without any pre-configured scope.","commands":{"allow":["basename"],"deny":[]}},"allow-dirname":{"identifier":"allow-dirname","description":"Enables the dirname command without any pre-configured scope.","commands":{"allow":["dirname"],"deny":[]}},"allow-extname":{"identifier":"allow-extname","description":"Enables the extname command without any pre-configured scope.","commands":{"allow":["extname"],"deny":[]}},"allow-is-absolute":{"identifier":"allow-is-absolute","description":"Enables the is_absolute command without any pre-configured scope.","commands":{"allow":["is_absolute"],"deny":[]}},"allow-join":{"identifier":"allow-join","description":"Enables the join command without any pre-configured scope.","commands":{"allow":["join"],"deny":[]}},"allow-normalize":{"identifier":"allow-normalize","description":"Enables the normalize command without any pre-configured scope.","commands":{"allow":["normalize"],"deny":[]}},"allow-resolve":{"identifier":"allow-resolve","description":"Enables the resolve command without any pre-configured scope.","commands":{"allow":["resolve"],"deny":[]}},"allow-resolve-directory":{"identifier":"allow-resolve-directory","description":"Enables the resolve_directory command without any pre-configured scope.","commands":{"allow":["resolve_directory"],"deny":[]}},"deny-basename":{"identifier":"deny-basename","description":"Denies the basename command without any pre-configured scope.","commands":{"allow":[],"deny":["basename"]}},"deny-dirname":{"identifier":"deny-dirname","description":"Denies the dirname command without any pre-configured scope.","commands":{"allow":[],"deny":["dirname"]}},"deny-extname":{"identifier":"deny-extname","description":"Denies the extname command without any pre-configured scope.","commands":{"allow":[],"deny":["extname"]}},"deny-is-absolute":{"identifier":"deny-is-absolute","description":"Denies the is_absolute command without any pre-configured scope.","commands":{"allow":[],"deny":["is_absolute"]}},"deny-join":{"identifier":"deny-join","description":"Denies the join command without any pre-configured scope.","commands":{"allow":[],"deny":["join"]}},"deny-normalize":{"identifier":"deny-normalize","description":"Denies the normalize command without any pre-configured scope.","commands":{"allow":[],"deny":["normalize"]}},"deny-resolve":{"identifier":"deny-resolve","description":"Denies the resolve command without any pre-configured scope.","commands":{"allow":[],"deny":["resolve"]}},"deny-resolve-directory":{"identifier":"deny-resolve-directory","description":"Denies the resolve_directory command without any pre-configured scope.","commands":{"allow":[],"deny":["resolve_directory"]}}},"permission_sets":{},"global_scope_schema":null},"core:resources":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-close"]},"permissions":{"allow-close":{"identifier":"allow-close","description":"Enables the close command without any pre-configured scope.","commands":{"allow":["close"],"deny":[]}},"deny-close":{"identifier":"deny-close","description":"Denies the close command without any pre-configured scope.","commands":{"allow":[],"deny":["close"]}}},"permission_sets":{},"global_scope_schema":null},"core:tray":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-new","allow-get-by-id","allow-remove-by-id","allow-set-icon","allow-set-menu","allow-set-tooltip","allow-set-title","allow-set-visible","allow-set-temp-dir-path","allow-set-icon-as-template","allow-set-icon-with-as-template","allow-set-show-menu-on-left-click"]},"permissions":{"allow-get-by-id":{"identifier":"allow-get-by-id","description":"Enables the get_by_id command without any pre-configured scope.","commands":{"allow":["get_by_id"],"deny":[]}},"allow-new":{"identifier":"allow-new","description":"Enables the new command without any pre-configured scope.","commands":{"allow":["new"],"deny":[]}},"allow-remove-by-id":{"identifier":"allow-remove-by-id","description":"Enables the remove_by_id command without any pre-configured scope.","commands":{"allow":["remove_by_id"],"deny":[]}},"allow-set-icon":{"identifier":"allow-set-icon","description":"Enables the set_icon command without any pre-configured scope.","commands":{"allow":["set_icon"],"deny":[]}},"allow-set-icon-as-template":{"identifier":"allow-set-icon-as-template","description":"Enables the set_icon_as_template command without any pre-configured scope.","commands":{"allow":["set_icon_as_template"],"deny":[]}},"allow-set-icon-with-as-template":{"identifier":"allow-set-icon-with-as-template","description":"Enables the set_icon_with_as_template command without any pre-configured scope.","commands":{"allow":["set_icon_with_as_template"],"deny":[]}},"allow-set-menu":{"identifier":"allow-set-menu","description":"Enables the set_menu command without any pre-configured scope.","commands":{"allow":["set_menu"],"deny":[]}},"allow-set-show-menu-on-left-click":{"identifier":"allow-set-show-menu-on-left-click","description":"Enables the set_show_menu_on_left_click command without any pre-configured scope.","commands":{"allow":["set_show_menu_on_left_click"],"deny":[]}},"allow-set-temp-dir-path":{"identifier":"allow-set-temp-dir-path","description":"Enables the set_temp_dir_path command without any pre-configured scope.","commands":{"allow":["set_temp_dir_path"],"deny":[]}},"allow-set-title":{"identifier":"allow-set-title","description":"Enables the set_title command without any pre-configured scope.","commands":{"allow":["set_title"],"deny":[]}},"allow-set-tooltip":{"identifier":"allow-set-tooltip","description":"Enables the set_tooltip command without any pre-configured scope.","commands":{"allow":["set_tooltip"],"deny":[]}},"allow-set-visible":{"identifier":"allow-set-visible","description":"Enables the set_visible command without any pre-configured scope.","commands":{"allow":["set_visible"],"deny":[]}},"deny-get-by-id":{"identifier":"deny-get-by-id","description":"Denies the get_by_id command without any pre-configured scope.","commands":{"allow":[],"deny":["get_by_id"]}},"deny-new":{"identifier":"deny-new","description":"Denies the new command without any pre-configured scope.","commands":{"allow":[],"deny":["new"]}},"deny-remove-by-id":{"identifier":"deny-remove-by-id","description":"Denies the remove_by_id command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_by_id"]}},"deny-set-icon":{"identifier":"deny-set-icon","description":"Denies the set_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon"]}},"deny-set-icon-as-template":{"identifier":"deny-set-icon-as-template","description":"Denies the set_icon_as_template command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon_as_template"]}},"deny-set-icon-with-as-template":{"identifier":"deny-set-icon-with-as-template","description":"Denies the set_icon_with_as_template command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon_with_as_template"]}},"deny-set-menu":{"identifier":"deny-set-menu","description":"Denies the set_menu command without any pre-configured scope.","commands":{"allow":[],"deny":["set_menu"]}},"deny-set-show-menu-on-left-click":{"identifier":"deny-set-show-menu-on-left-click","description":"Denies the set_show_menu_on_left_click command without any pre-configured scope.","commands":{"allow":[],"deny":["set_show_menu_on_left_click"]}},"deny-set-temp-dir-path":{"identifier":"deny-set-temp-dir-path","description":"Denies the set_temp_dir_path command without any pre-configured scope.","commands":{"allow":[],"deny":["set_temp_dir_path"]}},"deny-set-title":{"identifier":"deny-set-title","description":"Denies the set_title command without any pre-configured scope.","commands":{"allow":[],"deny":["set_title"]}},"deny-set-tooltip":{"identifier":"deny-set-tooltip","description":"Denies the set_tooltip command without any pre-configured scope.","commands":{"allow":[],"deny":["set_tooltip"]}},"deny-set-visible":{"identifier":"deny-set-visible","description":"Denies the set_visible command without any pre-configured scope.","commands":{"allow":[],"deny":["set_visible"]}}},"permission_sets":{},"global_scope_schema":null},"core:webview":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin.","permissions":["allow-get-all-webviews","allow-webview-position","allow-webview-size","allow-internal-toggle-devtools"]},"permissions":{"allow-clear-all-browsing-data":{"identifier":"allow-clear-all-browsing-data","description":"Enables the clear_all_browsing_data command without any pre-configured scope.","commands":{"allow":["clear_all_browsing_data"],"deny":[]}},"allow-create-webview":{"identifier":"allow-create-webview","description":"Enables the create_webview command without any pre-configured scope.","commands":{"allow":["create_webview"],"deny":[]}},"allow-create-webview-window":{"identifier":"allow-create-webview-window","description":"Enables the create_webview_window command without any pre-configured scope.","commands":{"allow":["create_webview_window"],"deny":[]}},"allow-get-all-webviews":{"identifier":"allow-get-all-webviews","description":"Enables the get_all_webviews command without any pre-configured scope.","commands":{"allow":["get_all_webviews"],"deny":[]}},"allow-internal-toggle-devtools":{"identifier":"allow-internal-toggle-devtools","description":"Enables the internal_toggle_devtools command without any pre-configured scope.","commands":{"allow":["internal_toggle_devtools"],"deny":[]}},"allow-print":{"identifier":"allow-print","description":"Enables the print command without any pre-configured scope.","commands":{"allow":["print"],"deny":[]}},"allow-reparent":{"identifier":"allow-reparent","description":"Enables the reparent command without any pre-configured scope.","commands":{"allow":["reparent"],"deny":[]}},"allow-set-webview-auto-resize":{"identifier":"allow-set-webview-auto-resize","description":"Enables the set_webview_auto_resize command without any pre-configured scope.","commands":{"allow":["set_webview_auto_resize"],"deny":[]}},"allow-set-webview-background-color":{"identifier":"allow-set-webview-background-color","description":"Enables the set_webview_background_color command without any pre-configured scope.","commands":{"allow":["set_webview_background_color"],"deny":[]}},"allow-set-webview-focus":{"identifier":"allow-set-webview-focus","description":"Enables the set_webview_focus command without any pre-configured scope.","commands":{"allow":["set_webview_focus"],"deny":[]}},"allow-set-webview-position":{"identifier":"allow-set-webview-position","description":"Enables the set_webview_position command without any pre-configured scope.","commands":{"allow":["set_webview_position"],"deny":[]}},"allow-set-webview-size":{"identifier":"allow-set-webview-size","description":"Enables the set_webview_size command without any pre-configured scope.","commands":{"allow":["set_webview_size"],"deny":[]}},"allow-set-webview-zoom":{"identifier":"allow-set-webview-zoom","description":"Enables the set_webview_zoom command without any pre-configured scope.","commands":{"allow":["set_webview_zoom"],"deny":[]}},"allow-webview-close":{"identifier":"allow-webview-close","description":"Enables the webview_close command without any pre-configured scope.","commands":{"allow":["webview_close"],"deny":[]}},"allow-webview-hide":{"identifier":"allow-webview-hide","description":"Enables the webview_hide command without any pre-configured scope.","commands":{"allow":["webview_hide"],"deny":[]}},"allow-webview-position":{"identifier":"allow-webview-position","description":"Enables the webview_position command without any pre-configured scope.","commands":{"allow":["webview_position"],"deny":[]}},"allow-webview-show":{"identifier":"allow-webview-show","description":"Enables the webview_show command without any pre-configured scope.","commands":{"allow":["webview_show"],"deny":[]}},"allow-webview-size":{"identifier":"allow-webview-size","description":"Enables the webview_size command without any pre-configured scope.","commands":{"allow":["webview_size"],"deny":[]}},"deny-clear-all-browsing-data":{"identifier":"deny-clear-all-browsing-data","description":"Denies the clear_all_browsing_data command without any pre-configured scope.","commands":{"allow":[],"deny":["clear_all_browsing_data"]}},"deny-create-webview":{"identifier":"deny-create-webview","description":"Denies the create_webview command without any pre-configured scope.","commands":{"allow":[],"deny":["create_webview"]}},"deny-create-webview-window":{"identifier":"deny-create-webview-window","description":"Denies the create_webview_window command without any pre-configured scope.","commands":{"allow":[],"deny":["create_webview_window"]}},"deny-get-all-webviews":{"identifier":"deny-get-all-webviews","description":"Denies the get_all_webviews command without any pre-configured scope.","commands":{"allow":[],"deny":["get_all_webviews"]}},"deny-internal-toggle-devtools":{"identifier":"deny-internal-toggle-devtools","description":"Denies the internal_toggle_devtools command without any pre-configured scope.","commands":{"allow":[],"deny":["internal_toggle_devtools"]}},"deny-print":{"identifier":"deny-print","description":"Denies the print command without any pre-configured scope.","commands":{"allow":[],"deny":["print"]}},"deny-reparent":{"identifier":"deny-reparent","description":"Denies the reparent command without any pre-configured scope.","commands":{"allow":[],"deny":["reparent"]}},"deny-set-webview-auto-resize":{"identifier":"deny-set-webview-auto-resize","description":"Denies the set_webview_auto_resize command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_auto_resize"]}},"deny-set-webview-background-color":{"identifier":"deny-set-webview-background-color","description":"Denies the set_webview_background_color command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_background_color"]}},"deny-set-webview-focus":{"identifier":"deny-set-webview-focus","description":"Denies the set_webview_focus command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_focus"]}},"deny-set-webview-position":{"identifier":"deny-set-webview-position","description":"Denies the set_webview_position command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_position"]}},"deny-set-webview-size":{"identifier":"deny-set-webview-size","description":"Denies the set_webview_size command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_size"]}},"deny-set-webview-zoom":{"identifier":"deny-set-webview-zoom","description":"Denies the set_webview_zoom command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_zoom"]}},"deny-webview-close":{"identifier":"deny-webview-close","description":"Denies the webview_close command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_close"]}},"deny-webview-hide":{"identifier":"deny-webview-hide","description":"Denies the webview_hide command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_hide"]}},"deny-webview-position":{"identifier":"deny-webview-position","description":"Denies the webview_position command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_position"]}},"deny-webview-show":{"identifier":"deny-webview-show","description":"Denies the webview_show command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_show"]}},"deny-webview-size":{"identifier":"deny-webview-size","description":"Denies the webview_size command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_size"]}}},"permission_sets":{},"global_scope_schema":null},"core:window":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin.","permissions":["allow-get-all-windows","allow-scale-factor","allow-inner-position","allow-outer-position","allow-inner-size","allow-outer-size","allow-is-fullscreen","allow-is-minimized","allow-is-maximized","allow-is-focused","allow-is-decorated","allow-is-resizable","allow-is-maximizable","allow-is-minimizable","allow-is-closable","allow-is-visible","allow-is-enabled","allow-title","allow-current-monitor","allow-primary-monitor","allow-monitor-from-point","allow-available-monitors","allow-cursor-position","allow-theme","allow-is-always-on-top","allow-activity-name","allow-scene-identifier","allow-internal-toggle-maximize"]},"permissions":{"allow-activity-name":{"identifier":"allow-activity-name","description":"Enables the activity_name command without any pre-configured scope.","commands":{"allow":["activity_name"],"deny":[]}},"allow-available-monitors":{"identifier":"allow-available-monitors","description":"Enables the available_monitors command without any pre-configured scope.","commands":{"allow":["available_monitors"],"deny":[]}},"allow-center":{"identifier":"allow-center","description":"Enables the center command without any pre-configured scope.","commands":{"allow":["center"],"deny":[]}},"allow-close":{"identifier":"allow-close","description":"Enables the close command without any pre-configured scope.","commands":{"allow":["close"],"deny":[]}},"allow-create":{"identifier":"allow-create","description":"Enables the create command without any pre-configured scope.","commands":{"allow":["create"],"deny":[]}},"allow-current-monitor":{"identifier":"allow-current-monitor","description":"Enables the current_monitor command without any pre-configured scope.","commands":{"allow":["current_monitor"],"deny":[]}},"allow-cursor-position":{"identifier":"allow-cursor-position","description":"Enables the cursor_position command without any pre-configured scope.","commands":{"allow":["cursor_position"],"deny":[]}},"allow-destroy":{"identifier":"allow-destroy","description":"Enables the destroy command without any pre-configured scope.","commands":{"allow":["destroy"],"deny":[]}},"allow-get-all-windows":{"identifier":"allow-get-all-windows","description":"Enables the get_all_windows command without any pre-configured scope.","commands":{"allow":["get_all_windows"],"deny":[]}},"allow-hide":{"identifier":"allow-hide","description":"Enables the hide command without any pre-configured scope.","commands":{"allow":["hide"],"deny":[]}},"allow-inner-position":{"identifier":"allow-inner-position","description":"Enables the inner_position command without any pre-configured scope.","commands":{"allow":["inner_position"],"deny":[]}},"allow-inner-size":{"identifier":"allow-inner-size","description":"Enables the inner_size command without any pre-configured scope.","commands":{"allow":["inner_size"],"deny":[]}},"allow-internal-toggle-maximize":{"identifier":"allow-internal-toggle-maximize","description":"Enables the internal_toggle_maximize command without any pre-configured scope.","commands":{"allow":["internal_toggle_maximize"],"deny":[]}},"allow-is-always-on-top":{"identifier":"allow-is-always-on-top","description":"Enables the is_always_on_top command without any pre-configured scope.","commands":{"allow":["is_always_on_top"],"deny":[]}},"allow-is-closable":{"identifier":"allow-is-closable","description":"Enables the is_closable command without any pre-configured scope.","commands":{"allow":["is_closable"],"deny":[]}},"allow-is-decorated":{"identifier":"allow-is-decorated","description":"Enables the is_decorated command without any pre-configured scope.","commands":{"allow":["is_decorated"],"deny":[]}},"allow-is-enabled":{"identifier":"allow-is-enabled","description":"Enables the is_enabled command without any pre-configured scope.","commands":{"allow":["is_enabled"],"deny":[]}},"allow-is-focused":{"identifier":"allow-is-focused","description":"Enables the is_focused command without any pre-configured scope.","commands":{"allow":["is_focused"],"deny":[]}},"allow-is-fullscreen":{"identifier":"allow-is-fullscreen","description":"Enables the is_fullscreen command without any pre-configured scope.","commands":{"allow":["is_fullscreen"],"deny":[]}},"allow-is-maximizable":{"identifier":"allow-is-maximizable","description":"Enables the is_maximizable command without any pre-configured scope.","commands":{"allow":["is_maximizable"],"deny":[]}},"allow-is-maximized":{"identifier":"allow-is-maximized","description":"Enables the is_maximized command without any pre-configured scope.","commands":{"allow":["is_maximized"],"deny":[]}},"allow-is-minimizable":{"identifier":"allow-is-minimizable","description":"Enables the is_minimizable command without any pre-configured scope.","commands":{"allow":["is_minimizable"],"deny":[]}},"allow-is-minimized":{"identifier":"allow-is-minimized","description":"Enables the is_minimized command without any pre-configured scope.","commands":{"allow":["is_minimized"],"deny":[]}},"allow-is-resizable":{"identifier":"allow-is-resizable","description":"Enables the is_resizable command without any pre-configured scope.","commands":{"allow":["is_resizable"],"deny":[]}},"allow-is-visible":{"identifier":"allow-is-visible","description":"Enables the is_visible command without any pre-configured scope.","commands":{"allow":["is_visible"],"deny":[]}},"allow-maximize":{"identifier":"allow-maximize","description":"Enables the maximize command without any pre-configured scope.","commands":{"allow":["maximize"],"deny":[]}},"allow-minimize":{"identifier":"allow-minimize","description":"Enables the minimize command without any pre-configured scope.","commands":{"allow":["minimize"],"deny":[]}},"allow-monitor-from-point":{"identifier":"allow-monitor-from-point","description":"Enables the monitor_from_point command without any pre-configured scope.","commands":{"allow":["monitor_from_point"],"deny":[]}},"allow-outer-position":{"identifier":"allow-outer-position","description":"Enables the outer_position command without any pre-configured scope.","commands":{"allow":["outer_position"],"deny":[]}},"allow-outer-size":{"identifier":"allow-outer-size","description":"Enables the outer_size command without any pre-configured scope.","commands":{"allow":["outer_size"],"deny":[]}},"allow-primary-monitor":{"identifier":"allow-primary-monitor","description":"Enables the primary_monitor command without any pre-configured scope.","commands":{"allow":["primary_monitor"],"deny":[]}},"allow-request-user-attention":{"identifier":"allow-request-user-attention","description":"Enables the request_user_attention command without any pre-configured scope.","commands":{"allow":["request_user_attention"],"deny":[]}},"allow-scale-factor":{"identifier":"allow-scale-factor","description":"Enables the scale_factor command without any pre-configured scope.","commands":{"allow":["scale_factor"],"deny":[]}},"allow-scene-identifier":{"identifier":"allow-scene-identifier","description":"Enables the scene_identifier command without any pre-configured scope.","commands":{"allow":["scene_identifier"],"deny":[]}},"allow-set-always-on-bottom":{"identifier":"allow-set-always-on-bottom","description":"Enables the set_always_on_bottom command without any pre-configured scope.","commands":{"allow":["set_always_on_bottom"],"deny":[]}},"allow-set-always-on-top":{"identifier":"allow-set-always-on-top","description":"Enables the set_always_on_top command without any pre-configured scope.","commands":{"allow":["set_always_on_top"],"deny":[]}},"allow-set-background-color":{"identifier":"allow-set-background-color","description":"Enables the set_background_color command without any pre-configured scope.","commands":{"allow":["set_background_color"],"deny":[]}},"allow-set-badge-count":{"identifier":"allow-set-badge-count","description":"Enables the set_badge_count command without any pre-configured scope.","commands":{"allow":["set_badge_count"],"deny":[]}},"allow-set-badge-label":{"identifier":"allow-set-badge-label","description":"Enables the set_badge_label command without any pre-configured scope.","commands":{"allow":["set_badge_label"],"deny":[]}},"allow-set-closable":{"identifier":"allow-set-closable","description":"Enables the set_closable command without any pre-configured scope.","commands":{"allow":["set_closable"],"deny":[]}},"allow-set-content-protected":{"identifier":"allow-set-content-protected","description":"Enables the set_content_protected command without any pre-configured scope.","commands":{"allow":["set_content_protected"],"deny":[]}},"allow-set-cursor-grab":{"identifier":"allow-set-cursor-grab","description":"Enables the set_cursor_grab command without any pre-configured scope.","commands":{"allow":["set_cursor_grab"],"deny":[]}},"allow-set-cursor-icon":{"identifier":"allow-set-cursor-icon","description":"Enables the set_cursor_icon command without any pre-configured scope.","commands":{"allow":["set_cursor_icon"],"deny":[]}},"allow-set-cursor-position":{"identifier":"allow-set-cursor-position","description":"Enables the set_cursor_position command without any pre-configured scope.","commands":{"allow":["set_cursor_position"],"deny":[]}},"allow-set-cursor-visible":{"identifier":"allow-set-cursor-visible","description":"Enables the set_cursor_visible command without any pre-configured scope.","commands":{"allow":["set_cursor_visible"],"deny":[]}},"allow-set-decorations":{"identifier":"allow-set-decorations","description":"Enables the set_decorations command without any pre-configured scope.","commands":{"allow":["set_decorations"],"deny":[]}},"allow-set-effects":{"identifier":"allow-set-effects","description":"Enables the set_effects command without any pre-configured scope.","commands":{"allow":["set_effects"],"deny":[]}},"allow-set-enabled":{"identifier":"allow-set-enabled","description":"Enables the set_enabled command without any pre-configured scope.","commands":{"allow":["set_enabled"],"deny":[]}},"allow-set-focus":{"identifier":"allow-set-focus","description":"Enables the set_focus command without any pre-configured scope.","commands":{"allow":["set_focus"],"deny":[]}},"allow-set-focusable":{"identifier":"allow-set-focusable","description":"Enables the set_focusable command without any pre-configured scope.","commands":{"allow":["set_focusable"],"deny":[]}},"allow-set-fullscreen":{"identifier":"allow-set-fullscreen","description":"Enables the set_fullscreen command without any pre-configured scope.","commands":{"allow":["set_fullscreen"],"deny":[]}},"allow-set-icon":{"identifier":"allow-set-icon","description":"Enables the set_icon command without any pre-configured scope.","commands":{"allow":["set_icon"],"deny":[]}},"allow-set-ignore-cursor-events":{"identifier":"allow-set-ignore-cursor-events","description":"Enables the set_ignore_cursor_events command without any pre-configured scope.","commands":{"allow":["set_ignore_cursor_events"],"deny":[]}},"allow-set-max-size":{"identifier":"allow-set-max-size","description":"Enables the set_max_size command without any pre-configured scope.","commands":{"allow":["set_max_size"],"deny":[]}},"allow-set-maximizable":{"identifier":"allow-set-maximizable","description":"Enables the set_maximizable command without any pre-configured scope.","commands":{"allow":["set_maximizable"],"deny":[]}},"allow-set-min-size":{"identifier":"allow-set-min-size","description":"Enables the set_min_size command without any pre-configured scope.","commands":{"allow":["set_min_size"],"deny":[]}},"allow-set-minimizable":{"identifier":"allow-set-minimizable","description":"Enables the set_minimizable command without any pre-configured scope.","commands":{"allow":["set_minimizable"],"deny":[]}},"allow-set-overlay-icon":{"identifier":"allow-set-overlay-icon","description":"Enables the set_overlay_icon command without any pre-configured scope.","commands":{"allow":["set_overlay_icon"],"deny":[]}},"allow-set-position":{"identifier":"allow-set-position","description":"Enables the set_position command without any pre-configured scope.","commands":{"allow":["set_position"],"deny":[]}},"allow-set-progress-bar":{"identifier":"allow-set-progress-bar","description":"Enables the set_progress_bar command without any pre-configured scope.","commands":{"allow":["set_progress_bar"],"deny":[]}},"allow-set-resizable":{"identifier":"allow-set-resizable","description":"Enables the set_resizable command without any pre-configured scope.","commands":{"allow":["set_resizable"],"deny":[]}},"allow-set-shadow":{"identifier":"allow-set-shadow","description":"Enables the set_shadow command without any pre-configured scope.","commands":{"allow":["set_shadow"],"deny":[]}},"allow-set-simple-fullscreen":{"identifier":"allow-set-simple-fullscreen","description":"Enables the set_simple_fullscreen command without any pre-configured scope.","commands":{"allow":["set_simple_fullscreen"],"deny":[]}},"allow-set-size":{"identifier":"allow-set-size","description":"Enables the set_size command without any pre-configured scope.","commands":{"allow":["set_size"],"deny":[]}},"allow-set-size-constraints":{"identifier":"allow-set-size-constraints","description":"Enables the set_size_constraints command without any pre-configured scope.","commands":{"allow":["set_size_constraints"],"deny":[]}},"allow-set-skip-taskbar":{"identifier":"allow-set-skip-taskbar","description":"Enables the set_skip_taskbar command without any pre-configured scope.","commands":{"allow":["set_skip_taskbar"],"deny":[]}},"allow-set-theme":{"identifier":"allow-set-theme","description":"Enables the set_theme command without any pre-configured scope.","commands":{"allow":["set_theme"],"deny":[]}},"allow-set-title":{"identifier":"allow-set-title","description":"Enables the set_title command without any pre-configured scope.","commands":{"allow":["set_title"],"deny":[]}},"allow-set-title-bar-style":{"identifier":"allow-set-title-bar-style","description":"Enables the set_title_bar_style command without any pre-configured scope.","commands":{"allow":["set_title_bar_style"],"deny":[]}},"allow-set-visible-on-all-workspaces":{"identifier":"allow-set-visible-on-all-workspaces","description":"Enables the set_visible_on_all_workspaces command without any pre-configured scope.","commands":{"allow":["set_visible_on_all_workspaces"],"deny":[]}},"allow-show":{"identifier":"allow-show","description":"Enables the show command without any pre-configured scope.","commands":{"allow":["show"],"deny":[]}},"allow-start-dragging":{"identifier":"allow-start-dragging","description":"Enables the start_dragging command without any pre-configured scope.","commands":{"allow":["start_dragging"],"deny":[]}},"allow-start-resize-dragging":{"identifier":"allow-start-resize-dragging","description":"Enables the start_resize_dragging command without any pre-configured scope.","commands":{"allow":["start_resize_dragging"],"deny":[]}},"allow-theme":{"identifier":"allow-theme","description":"Enables the theme command without any pre-configured scope.","commands":{"allow":["theme"],"deny":[]}},"allow-title":{"identifier":"allow-title","description":"Enables the title command without any pre-configured scope.","commands":{"allow":["title"],"deny":[]}},"allow-toggle-maximize":{"identifier":"allow-toggle-maximize","description":"Enables the toggle_maximize command without any pre-configured scope.","commands":{"allow":["toggle_maximize"],"deny":[]}},"allow-unmaximize":{"identifier":"allow-unmaximize","description":"Enables the unmaximize command without any pre-configured scope.","commands":{"allow":["unmaximize"],"deny":[]}},"allow-unminimize":{"identifier":"allow-unminimize","description":"Enables the unminimize command without any pre-configured scope.","commands":{"allow":["unminimize"],"deny":[]}},"deny-activity-name":{"identifier":"deny-activity-name","description":"Denies the activity_name command without any pre-configured scope.","commands":{"allow":[],"deny":["activity_name"]}},"deny-available-monitors":{"identifier":"deny-available-monitors","description":"Denies the available_monitors command without any pre-configured scope.","commands":{"allow":[],"deny":["available_monitors"]}},"deny-center":{"identifier":"deny-center","description":"Denies the center command without any pre-configured scope.","commands":{"allow":[],"deny":["center"]}},"deny-close":{"identifier":"deny-close","description":"Denies the close command without any pre-configured scope.","commands":{"allow":[],"deny":["close"]}},"deny-create":{"identifier":"deny-create","description":"Denies the create command without any pre-configured scope.","commands":{"allow":[],"deny":["create"]}},"deny-current-monitor":{"identifier":"deny-current-monitor","description":"Denies the current_monitor command without any pre-configured scope.","commands":{"allow":[],"deny":["current_monitor"]}},"deny-cursor-position":{"identifier":"deny-cursor-position","description":"Denies the cursor_position command without any pre-configured scope.","commands":{"allow":[],"deny":["cursor_position"]}},"deny-destroy":{"identifier":"deny-destroy","description":"Denies the destroy command without any pre-configured scope.","commands":{"allow":[],"deny":["destroy"]}},"deny-get-all-windows":{"identifier":"deny-get-all-windows","description":"Denies the get_all_windows command without any pre-configured scope.","commands":{"allow":[],"deny":["get_all_windows"]}},"deny-hide":{"identifier":"deny-hide","description":"Denies the hide command without any pre-configured scope.","commands":{"allow":[],"deny":["hide"]}},"deny-inner-position":{"identifier":"deny-inner-position","description":"Denies the inner_position command without any pre-configured scope.","commands":{"allow":[],"deny":["inner_position"]}},"deny-inner-size":{"identifier":"deny-inner-size","description":"Denies the inner_size command without any pre-configured scope.","commands":{"allow":[],"deny":["inner_size"]}},"deny-internal-toggle-maximize":{"identifier":"deny-internal-toggle-maximize","description":"Denies the internal_toggle_maximize command without any pre-configured scope.","commands":{"allow":[],"deny":["internal_toggle_maximize"]}},"deny-is-always-on-top":{"identifier":"deny-is-always-on-top","description":"Denies the is_always_on_top command without any pre-configured scope.","commands":{"allow":[],"deny":["is_always_on_top"]}},"deny-is-closable":{"identifier":"deny-is-closable","description":"Denies the is_closable command without any pre-configured scope.","commands":{"allow":[],"deny":["is_closable"]}},"deny-is-decorated":{"identifier":"deny-is-decorated","description":"Denies the is_decorated command without any pre-configured scope.","commands":{"allow":[],"deny":["is_decorated"]}},"deny-is-enabled":{"identifier":"deny-is-enabled","description":"Denies the is_enabled command without any pre-configured scope.","commands":{"allow":[],"deny":["is_enabled"]}},"deny-is-focused":{"identifier":"deny-is-focused","description":"Denies the is_focused command without any pre-configured scope.","commands":{"allow":[],"deny":["is_focused"]}},"deny-is-fullscreen":{"identifier":"deny-is-fullscreen","description":"Denies the is_fullscreen command without any pre-configured scope.","commands":{"allow":[],"deny":["is_fullscreen"]}},"deny-is-maximizable":{"identifier":"deny-is-maximizable","description":"Denies the is_maximizable command without any pre-configured scope.","commands":{"allow":[],"deny":["is_maximizable"]}},"deny-is-maximized":{"identifier":"deny-is-maximized","description":"Denies the is_maximized command without any pre-configured scope.","commands":{"allow":[],"deny":["is_maximized"]}},"deny-is-minimizable":{"identifier":"deny-is-minimizable","description":"Denies the is_minimizable command without any pre-configured scope.","commands":{"allow":[],"deny":["is_minimizable"]}},"deny-is-minimized":{"identifier":"deny-is-minimized","description":"Denies the is_minimized command without any pre-configured scope.","commands":{"allow":[],"deny":["is_minimized"]}},"deny-is-resizable":{"identifier":"deny-is-resizable","description":"Denies the is_resizable command without any pre-configured scope.","commands":{"allow":[],"deny":["is_resizable"]}},"deny-is-visible":{"identifier":"deny-is-visible","description":"Denies the is_visible command without any pre-configured scope.","commands":{"allow":[],"deny":["is_visible"]}},"deny-maximize":{"identifier":"deny-maximize","description":"Denies the maximize command without any pre-configured scope.","commands":{"allow":[],"deny":["maximize"]}},"deny-minimize":{"identifier":"deny-minimize","description":"Denies the minimize command without any pre-configured scope.","commands":{"allow":[],"deny":["minimize"]}},"deny-monitor-from-point":{"identifier":"deny-monitor-from-point","description":"Denies the monitor_from_point command without any pre-configured scope.","commands":{"allow":[],"deny":["monitor_from_point"]}},"deny-outer-position":{"identifier":"deny-outer-position","description":"Denies the outer_position command without any pre-configured scope.","commands":{"allow":[],"deny":["outer_position"]}},"deny-outer-size":{"identifier":"deny-outer-size","description":"Denies the outer_size command without any pre-configured scope.","commands":{"allow":[],"deny":["outer_size"]}},"deny-primary-monitor":{"identifier":"deny-primary-monitor","description":"Denies the primary_monitor command without any pre-configured scope.","commands":{"allow":[],"deny":["primary_monitor"]}},"deny-request-user-attention":{"identifier":"deny-request-user-attention","description":"Denies the request_user_attention command without any pre-configured scope.","commands":{"allow":[],"deny":["request_user_attention"]}},"deny-scale-factor":{"identifier":"deny-scale-factor","description":"Denies the scale_factor command without any pre-configured scope.","commands":{"allow":[],"deny":["scale_factor"]}},"deny-scene-identifier":{"identifier":"deny-scene-identifier","description":"Denies the scene_identifier command without any pre-configured scope.","commands":{"allow":[],"deny":["scene_identifier"]}},"deny-set-always-on-bottom":{"identifier":"deny-set-always-on-bottom","description":"Denies the set_always_on_bottom command without any pre-configured scope.","commands":{"allow":[],"deny":["set_always_on_bottom"]}},"deny-set-always-on-top":{"identifier":"deny-set-always-on-top","description":"Denies the set_always_on_top command without any pre-configured scope.","commands":{"allow":[],"deny":["set_always_on_top"]}},"deny-set-background-color":{"identifier":"deny-set-background-color","description":"Denies the set_background_color command without any pre-configured scope.","commands":{"allow":[],"deny":["set_background_color"]}},"deny-set-badge-count":{"identifier":"deny-set-badge-count","description":"Denies the set_badge_count command without any pre-configured scope.","commands":{"allow":[],"deny":["set_badge_count"]}},"deny-set-badge-label":{"identifier":"deny-set-badge-label","description":"Denies the set_badge_label command without any pre-configured scope.","commands":{"allow":[],"deny":["set_badge_label"]}},"deny-set-closable":{"identifier":"deny-set-closable","description":"Denies the set_closable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_closable"]}},"deny-set-content-protected":{"identifier":"deny-set-content-protected","description":"Denies the set_content_protected command without any pre-configured scope.","commands":{"allow":[],"deny":["set_content_protected"]}},"deny-set-cursor-grab":{"identifier":"deny-set-cursor-grab","description":"Denies the set_cursor_grab command without any pre-configured scope.","commands":{"allow":[],"deny":["set_cursor_grab"]}},"deny-set-cursor-icon":{"identifier":"deny-set-cursor-icon","description":"Denies the set_cursor_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_cursor_icon"]}},"deny-set-cursor-position":{"identifier":"deny-set-cursor-position","description":"Denies the set_cursor_position command without any pre-configured scope.","commands":{"allow":[],"deny":["set_cursor_position"]}},"deny-set-cursor-visible":{"identifier":"deny-set-cursor-visible","description":"Denies the set_cursor_visible command without any pre-configured scope.","commands":{"allow":[],"deny":["set_cursor_visible"]}},"deny-set-decorations":{"identifier":"deny-set-decorations","description":"Denies the set_decorations command without any pre-configured scope.","commands":{"allow":[],"deny":["set_decorations"]}},"deny-set-effects":{"identifier":"deny-set-effects","description":"Denies the set_effects command without any pre-configured scope.","commands":{"allow":[],"deny":["set_effects"]}},"deny-set-enabled":{"identifier":"deny-set-enabled","description":"Denies the set_enabled command without any pre-configured scope.","commands":{"allow":[],"deny":["set_enabled"]}},"deny-set-focus":{"identifier":"deny-set-focus","description":"Denies the set_focus command without any pre-configured scope.","commands":{"allow":[],"deny":["set_focus"]}},"deny-set-focusable":{"identifier":"deny-set-focusable","description":"Denies the set_focusable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_focusable"]}},"deny-set-fullscreen":{"identifier":"deny-set-fullscreen","description":"Denies the set_fullscreen command without any pre-configured scope.","commands":{"allow":[],"deny":["set_fullscreen"]}},"deny-set-icon":{"identifier":"deny-set-icon","description":"Denies the set_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon"]}},"deny-set-ignore-cursor-events":{"identifier":"deny-set-ignore-cursor-events","description":"Denies the set_ignore_cursor_events command without any pre-configured scope.","commands":{"allow":[],"deny":["set_ignore_cursor_events"]}},"deny-set-max-size":{"identifier":"deny-set-max-size","description":"Denies the set_max_size command without any pre-configured scope.","commands":{"allow":[],"deny":["set_max_size"]}},"deny-set-maximizable":{"identifier":"deny-set-maximizable","description":"Denies the set_maximizable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_maximizable"]}},"deny-set-min-size":{"identifier":"deny-set-min-size","description":"Denies the set_min_size command without any pre-configured scope.","commands":{"allow":[],"deny":["set_min_size"]}},"deny-set-minimizable":{"identifier":"deny-set-minimizable","description":"Denies the set_minimizable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_minimizable"]}},"deny-set-overlay-icon":{"identifier":"deny-set-overlay-icon","description":"Denies the set_overlay_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_overlay_icon"]}},"deny-set-position":{"identifier":"deny-set-position","description":"Denies the set_position command without any pre-configured scope.","commands":{"allow":[],"deny":["set_position"]}},"deny-set-progress-bar":{"identifier":"deny-set-progress-bar","description":"Denies the set_progress_bar command without any pre-configured scope.","commands":{"allow":[],"deny":["set_progress_bar"]}},"deny-set-resizable":{"identifier":"deny-set-resizable","description":"Denies the set_resizable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_resizable"]}},"deny-set-shadow":{"identifier":"deny-set-shadow","description":"Denies the set_shadow command without any pre-configured scope.","commands":{"allow":[],"deny":["set_shadow"]}},"deny-set-simple-fullscreen":{"identifier":"deny-set-simple-fullscreen","description":"Denies the set_simple_fullscreen command without any pre-configured scope.","commands":{"allow":[],"deny":["set_simple_fullscreen"]}},"deny-set-size":{"identifier":"deny-set-size","description":"Denies the set_size command without any pre-configured scope.","commands":{"allow":[],"deny":["set_size"]}},"deny-set-size-constraints":{"identifier":"deny-set-size-constraints","description":"Denies the set_size_constraints command without any pre-configured scope.","commands":{"allow":[],"deny":["set_size_constraints"]}},"deny-set-skip-taskbar":{"identifier":"deny-set-skip-taskbar","description":"Denies the set_skip_taskbar command without any pre-configured scope.","commands":{"allow":[],"deny":["set_skip_taskbar"]}},"deny-set-theme":{"identifier":"deny-set-theme","description":"Denies the set_theme command without any pre-configured scope.","commands":{"allow":[],"deny":["set_theme"]}},"deny-set-title":{"identifier":"deny-set-title","description":"Denies the set_title command without any pre-configured scope.","commands":{"allow":[],"deny":["set_title"]}},"deny-set-title-bar-style":{"identifier":"deny-set-title-bar-style","description":"Denies the set_title_bar_style command without any pre-configured scope.","commands":{"allow":[],"deny":["set_title_bar_style"]}},"deny-set-visible-on-all-workspaces":{"identifier":"deny-set-visible-on-all-workspaces","description":"Denies the set_visible_on_all_workspaces command without any pre-configured scope.","commands":{"allow":[],"deny":["set_visible_on_all_workspaces"]}},"deny-show":{"identifier":"deny-show","description":"Denies the show command without any pre-configured scope.","commands":{"allow":[],"deny":["show"]}},"deny-start-dragging":{"identifier":"deny-start-dragging","description":"Denies the start_dragging command without any pre-configured scope.","commands":{"allow":[],"deny":["start_dragging"]}},"deny-start-resize-dragging":{"identifier":"deny-start-resize-dragging","description":"Denies the start_resize_dragging command without any pre-configured scope.","commands":{"allow":[],"deny":["start_resize_dragging"]}},"deny-theme":{"identifier":"deny-theme","description":"Denies the theme command without any pre-configured scope.","commands":{"allow":[],"deny":["theme"]}},"deny-title":{"identifier":"deny-title","description":"Denies the title command without any pre-configured scope.","commands":{"allow":[],"deny":["title"]}},"deny-toggle-maximize":{"identifier":"deny-toggle-maximize","description":"Denies the toggle_maximize command without any pre-configured scope.","commands":{"allow":[],"deny":["toggle_maximize"]}},"deny-unmaximize":{"identifier":"deny-unmaximize","description":"Denies the unmaximize command without any pre-configured scope.","commands":{"allow":[],"deny":["unmaximize"]}},"deny-unminimize":{"identifier":"deny-unminimize","description":"Denies the unminimize command without any pre-configured scope.","commands":{"allow":[],"deny":["unminimize"]}}},"permission_sets":{},"global_scope_schema":null},"deep-link":{"default_permission":{"identifier":"default","description":"Allows reading the opened deep link via the get_current command","permissions":["allow-get-current"]},"permissions":{"allow-get-current":{"identifier":"allow-get-current","description":"Enables the get_current command without any pre-configured scope.","commands":{"allow":["get_current"],"deny":[]}},"allow-is-registered":{"identifier":"allow-is-registered","description":"Enables the is_registered command without any pre-configured scope.","commands":{"allow":["is_registered"],"deny":[]}},"allow-register":{"identifier":"allow-register","description":"Enables the register command without any pre-configured scope.","commands":{"allow":["register"],"deny":[]}},"allow-unregister":{"identifier":"allow-unregister","description":"Enables the unregister command without any pre-configured scope.","commands":{"allow":["unregister"],"deny":[]}},"deny-get-current":{"identifier":"deny-get-current","description":"Denies the get_current command without any pre-configured scope.","commands":{"allow":[],"deny":["get_current"]}},"deny-is-registered":{"identifier":"deny-is-registered","description":"Denies the is_registered command without any pre-configured scope.","commands":{"allow":[],"deny":["is_registered"]}},"deny-register":{"identifier":"deny-register","description":"Denies the register command without any pre-configured scope.","commands":{"allow":[],"deny":["register"]}},"deny-unregister":{"identifier":"deny-unregister","description":"Denies the unregister command without any pre-configured scope.","commands":{"allow":[],"deny":["unregister"]}}},"permission_sets":{},"global_scope_schema":null},"dialog":{"default_permission":{"identifier":"default","description":"This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n","permissions":["allow-message","allow-save","allow-open"]},"permissions":{"allow-ask":{"identifier":"allow-ask","description":"Enables the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)","commands":{"allow":["message"],"deny":[]}},"allow-confirm":{"identifier":"allow-confirm","description":"Enables the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)","commands":{"allow":["message"],"deny":[]}},"allow-message":{"identifier":"allow-message","description":"Enables the message command without any pre-configured scope.","commands":{"allow":["message"],"deny":[]}},"allow-open":{"identifier":"allow-open","description":"Enables the open command without any pre-configured scope.","commands":{"allow":["open"],"deny":[]}},"allow-save":{"identifier":"allow-save","description":"Enables the save command without any pre-configured scope.","commands":{"allow":["save"],"deny":[]}},"deny-ask":{"identifier":"deny-ask","description":"Denies the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)","commands":{"allow":[],"deny":["message"]}},"deny-confirm":{"identifier":"deny-confirm","description":"Denies the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)","commands":{"allow":[],"deny":["message"]}},"deny-message":{"identifier":"deny-message","description":"Denies the message command without any pre-configured scope.","commands":{"allow":[],"deny":["message"]}},"deny-open":{"identifier":"deny-open","description":"Denies the open command without any pre-configured scope.","commands":{"allow":[],"deny":["open"]}},"deny-save":{"identifier":"deny-save","description":"Denies the save command without any pre-configured scope.","commands":{"allow":[],"deny":["save"]}}},"permission_sets":{},"global_scope_schema":null},"log":{"default_permission":{"identifier":"default","description":"Allows the log command","permissions":["allow-log"]},"permissions":{"allow-log":{"identifier":"allow-log","description":"Enables the log command without any pre-configured scope.","commands":{"allow":["log"],"deny":[]}},"deny-log":{"identifier":"deny-log","description":"Denies the log command without any pre-configured scope.","commands":{"allow":[],"deny":["log"]}}},"permission_sets":{},"global_scope_schema":null},"notification":{"default_permission":{"identifier":"default","description":"This permission set configures which\nnotification features are by default exposed.\n\n#### Granted Permissions\n\nIt allows all notification related features.\n\n","permissions":["allow-is-permission-granted","allow-request-permission","allow-notify","allow-register-action-types","allow-register-listener","allow-cancel","allow-get-pending","allow-remove-active","allow-get-active","allow-check-permissions","allow-show","allow-batch","allow-list-channels","allow-delete-channel","allow-create-channel","allow-permission-state"]},"permissions":{"allow-batch":{"identifier":"allow-batch","description":"Enables the batch command without any pre-configured scope.","commands":{"allow":["batch"],"deny":[]}},"allow-cancel":{"identifier":"allow-cancel","description":"Enables the cancel command without any pre-configured scope.","commands":{"allow":["cancel"],"deny":[]}},"allow-check-permissions":{"identifier":"allow-check-permissions","description":"Enables the check_permissions command without any pre-configured scope.","commands":{"allow":["check_permissions"],"deny":[]}},"allow-create-channel":{"identifier":"allow-create-channel","description":"Enables the create_channel command without any pre-configured scope.","commands":{"allow":["create_channel"],"deny":[]}},"allow-delete-channel":{"identifier":"allow-delete-channel","description":"Enables the delete_channel command without any pre-configured scope.","commands":{"allow":["delete_channel"],"deny":[]}},"allow-get-active":{"identifier":"allow-get-active","description":"Enables the get_active command without any pre-configured scope.","commands":{"allow":["get_active"],"deny":[]}},"allow-get-pending":{"identifier":"allow-get-pending","description":"Enables the get_pending command without any pre-configured scope.","commands":{"allow":["get_pending"],"deny":[]}},"allow-is-permission-granted":{"identifier":"allow-is-permission-granted","description":"Enables the is_permission_granted command without any pre-configured scope.","commands":{"allow":["is_permission_granted"],"deny":[]}},"allow-list-channels":{"identifier":"allow-list-channels","description":"Enables the list_channels command without any pre-configured scope.","commands":{"allow":["list_channels"],"deny":[]}},"allow-notify":{"identifier":"allow-notify","description":"Enables the notify command without any pre-configured scope.","commands":{"allow":["notify"],"deny":[]}},"allow-permission-state":{"identifier":"allow-permission-state","description":"Enables the permission_state command without any pre-configured scope.","commands":{"allow":["permission_state"],"deny":[]}},"allow-register-action-types":{"identifier":"allow-register-action-types","description":"Enables the register_action_types command without any pre-configured scope.","commands":{"allow":["register_action_types"],"deny":[]}},"allow-register-listener":{"identifier":"allow-register-listener","description":"Enables the register_listener command without any pre-configured scope.","commands":{"allow":["register_listener"],"deny":[]}},"allow-remove-active":{"identifier":"allow-remove-active","description":"Enables the remove_active command without any pre-configured scope.","commands":{"allow":["remove_active"],"deny":[]}},"allow-request-permission":{"identifier":"allow-request-permission","description":"Enables the request_permission command without any pre-configured scope.","commands":{"allow":["request_permission"],"deny":[]}},"allow-show":{"identifier":"allow-show","description":"Enables the show command without any pre-configured scope.","commands":{"allow":["show"],"deny":[]}},"deny-batch":{"identifier":"deny-batch","description":"Denies the batch command without any pre-configured scope.","commands":{"allow":[],"deny":["batch"]}},"deny-cancel":{"identifier":"deny-cancel","description":"Denies the cancel command without any pre-configured scope.","commands":{"allow":[],"deny":["cancel"]}},"deny-check-permissions":{"identifier":"deny-check-permissions","description":"Denies the check_permissions command without any pre-configured scope.","commands":{"allow":[],"deny":["check_permissions"]}},"deny-create-channel":{"identifier":"deny-create-channel","description":"Denies the create_channel command without any pre-configured scope.","commands":{"allow":[],"deny":["create_channel"]}},"deny-delete-channel":{"identifier":"deny-delete-channel","description":"Denies the delete_channel command without any pre-configured scope.","commands":{"allow":[],"deny":["delete_channel"]}},"deny-get-active":{"identifier":"deny-get-active","description":"Denies the get_active command without any pre-configured scope.","commands":{"allow":[],"deny":["get_active"]}},"deny-get-pending":{"identifier":"deny-get-pending","description":"Denies the get_pending command without any pre-configured scope.","commands":{"allow":[],"deny":["get_pending"]}},"deny-is-permission-granted":{"identifier":"deny-is-permission-granted","description":"Denies the is_permission_granted command without any pre-configured scope.","commands":{"allow":[],"deny":["is_permission_granted"]}},"deny-list-channels":{"identifier":"deny-list-channels","description":"Denies the list_channels command without any pre-configured scope.","commands":{"allow":[],"deny":["list_channels"]}},"deny-notify":{"identifier":"deny-notify","description":"Denies the notify command without any pre-configured scope.","commands":{"allow":[],"deny":["notify"]}},"deny-permission-state":{"identifier":"deny-permission-state","description":"Denies the permission_state command without any pre-configured scope.","commands":{"allow":[],"deny":["permission_state"]}},"deny-register-action-types":{"identifier":"deny-register-action-types","description":"Denies the register_action_types command without any pre-configured scope.","commands":{"allow":[],"deny":["register_action_types"]}},"deny-register-listener":{"identifier":"deny-register-listener","description":"Denies the register_listener command without any pre-configured scope.","commands":{"allow":[],"deny":["register_listener"]}},"deny-remove-active":{"identifier":"deny-remove-active","description":"Denies the remove_active command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_active"]}},"deny-request-permission":{"identifier":"deny-request-permission","description":"Denies the request_permission command without any pre-configured scope.","commands":{"allow":[],"deny":["request_permission"]}},"deny-show":{"identifier":"deny-show","description":"Denies the show command without any pre-configured scope.","commands":{"allow":[],"deny":["show"]}}},"permission_sets":{},"global_scope_schema":null},"opener":{"default_permission":{"identifier":"default","description":"This permission set allows opening `mailto:`, `tel:`, `https://` and `http://` urls using their default application\nas well as reveal file in directories using default file explorer","permissions":["allow-open-url","allow-reveal-item-in-dir","allow-default-urls"]},"permissions":{"allow-default-urls":{"identifier":"allow-default-urls","description":"This enables opening `mailto:`, `tel:`, `https://` and `http://` urls using their default application.","commands":{"allow":[],"deny":[]},"scope":{"allow":[{"url":"mailto:*"},{"url":"tel:*"},{"url":"http://*"},{"url":"https://*"}]}},"allow-open-path":{"identifier":"allow-open-path","description":"Enables the open_path command without any pre-configured scope.","commands":{"allow":["open_path"],"deny":[]}},"allow-open-url":{"identifier":"allow-open-url","description":"Enables the open_url command without any pre-configured scope.","commands":{"allow":["open_url"],"deny":[]}},"allow-reveal-item-in-dir":{"identifier":"allow-reveal-item-in-dir","description":"Enables the reveal_item_in_dir command without any pre-configured scope.","commands":{"allow":["reveal_item_in_dir"],"deny":[]}},"deny-open-path":{"identifier":"deny-open-path","description":"Denies the open_path command without any pre-configured scope.","commands":{"allow":[],"deny":["open_path"]}},"deny-open-url":{"identifier":"deny-open-url","description":"Denies the open_url command without any pre-configured scope.","commands":{"allow":[],"deny":["open_url"]}},"deny-reveal-item-in-dir":{"identifier":"deny-reveal-item-in-dir","description":"Denies the reveal_item_in_dir command without any pre-configured scope.","commands":{"allow":[],"deny":["reveal_item_in_dir"]}}},"permission_sets":{},"global_scope_schema":{"$schema":"http://json-schema.org/draft-07/schema#","anyOf":[{"properties":{"app":{"allOf":[{"$ref":"#/definitions/Application"}],"description":"An application to open this url with, for example: firefox."},"url":{"description":"A URL that can be opened by the webview when using the Opener APIs.\n\nWildcards can be used following the UNIX glob pattern.\n\nExamples:\n\n- \"https://*\" : allows all HTTPS origin\n\n- \"https://*.github.com/tauri-apps/tauri\": allows any subdomain of \"github.com\" with the \"tauri-apps/api\" path\n\n- \"https://myapi.service.com/users/*\": allows access to any URLs that begins with \"https://myapi.service.com/users/\"","type":"string"}},"required":["url"],"type":"object"},{"properties":{"app":{"allOf":[{"$ref":"#/definitions/Application"}],"description":"An application to open this path with, for example: xdg-open."},"path":{"description":"A path that can be opened by the webview when using the Opener APIs.\n\nThe pattern can start with a variable that resolves to a system base directory. The variables are: `$AUDIO`, `$CACHE`, `$CONFIG`, `$DATA`, `$LOCALDATA`, `$DESKTOP`, `$DOCUMENT`, `$DOWNLOAD`, `$EXE`, `$FONT`, `$HOME`, `$PICTURE`, `$PUBLIC`, `$RUNTIME`, `$TEMPLATE`, `$VIDEO`, `$RESOURCE`, `$APP`, `$LOG`, `$TEMP`, `$APPCONFIG`, `$APPDATA`, `$APPLOCALDATA`, `$APPCACHE`, `$APPLOG`.","type":"string"}},"required":["path"],"type":"object"}],"definitions":{"Application":{"anyOf":[{"description":"Open in default application.","type":"null"},{"description":"If true, allow open with any application.","type":"boolean"},{"description":"Allow specific application to open with.","type":"string"}],"description":"Opener scope application."}},"description":"Opener scope entry.","title":"OpenerScopeEntry"}},"process":{"default_permission":{"identifier":"default","description":"This permission set configures which\nprocess features are by default exposed.\n\n#### Granted Permissions\n\nThis enables to quit via `allow-exit` and restart via `allow-restart`\nthe application.\n","permissions":["allow-exit","allow-restart"]},"permissions":{"allow-exit":{"identifier":"allow-exit","description":"Enables the exit command without any pre-configured scope.","commands":{"allow":["exit"],"deny":[]}},"allow-restart":{"identifier":"allow-restart","description":"Enables the restart command without any pre-configured scope.","commands":{"allow":["restart"],"deny":[]}},"deny-exit":{"identifier":"deny-exit","description":"Denies the exit command without any pre-configured scope.","commands":{"allow":[],"deny":["exit"]}},"deny-restart":{"identifier":"deny-restart","description":"Denies the restart command without any pre-configured scope.","commands":{"allow":[],"deny":["restart"]}}},"permission_sets":{},"global_scope_schema":null},"shell":{"default_permission":{"identifier":"default","description":"This permission set configures which\nshell functionality is exposed by default.\n\n#### Granted Permissions\n\nIt allows to use the `open` functionality with a reasonable\nscope pre-configured. It will allow opening `http(s)://`,\n`tel:` and `mailto:` links.\n","permissions":["allow-open"]},"permissions":{"allow-execute":{"identifier":"allow-execute","description":"Enables the execute command without any pre-configured scope.","commands":{"allow":["execute"],"deny":[]}},"allow-kill":{"identifier":"allow-kill","description":"Enables the kill command without any pre-configured scope.","commands":{"allow":["kill"],"deny":[]}},"allow-open":{"identifier":"allow-open","description":"Enables the open command without any pre-configured scope.","commands":{"allow":["open"],"deny":[]}},"allow-spawn":{"identifier":"allow-spawn","description":"Enables the spawn command without any pre-configured scope.","commands":{"allow":["spawn"],"deny":[]}},"allow-stdin-write":{"identifier":"allow-stdin-write","description":"Enables the stdin_write command without any pre-configured scope.","commands":{"allow":["stdin_write"],"deny":[]}},"deny-execute":{"identifier":"deny-execute","description":"Denies the execute command without any pre-configured scope.","commands":{"allow":[],"deny":["execute"]}},"deny-kill":{"identifier":"deny-kill","description":"Denies the kill command without any pre-configured scope.","commands":{"allow":[],"deny":["kill"]}},"deny-open":{"identifier":"deny-open","description":"Denies the open command without any pre-configured scope.","commands":{"allow":[],"deny":["open"]}},"deny-spawn":{"identifier":"deny-spawn","description":"Denies the spawn command without any pre-configured scope.","commands":{"allow":[],"deny":["spawn"]}},"deny-stdin-write":{"identifier":"deny-stdin-write","description":"Denies the stdin_write command without any pre-configured scope.","commands":{"allow":[],"deny":["stdin_write"]}}},"permission_sets":{},"global_scope_schema":{"$schema":"http://json-schema.org/draft-07/schema#","anyOf":[{"additionalProperties":false,"properties":{"args":{"allOf":[{"$ref":"#/definitions/ShellScopeEntryAllowedArgs"}],"description":"The allowed arguments for the command execution."},"cmd":{"description":"The command name. It can start with a variable that resolves to a system base directory. The variables are: `$AUDIO`, `$CACHE`, `$CONFIG`, `$DATA`, `$LOCALDATA`, `$DESKTOP`, `$DOCUMENT`, `$DOWNLOAD`, `$EXE`, `$FONT`, `$HOME`, `$PICTURE`, `$PUBLIC`, `$RUNTIME`, `$TEMPLATE`, `$VIDEO`, `$RESOURCE`, `$LOG`, `$TEMP`, `$APPCONFIG`, `$APPDATA`, `$APPLOCALDATA`, `$APPCACHE`, `$APPLOG`.","type":"string"},"name":{"description":"The name for this allowed shell command configuration.\n\nThis name will be used inside of the webview API to call this command along with any specified arguments.","type":"string"}},"required":["cmd","name"],"type":"object"},{"additionalProperties":false,"properties":{"args":{"allOf":[{"$ref":"#/definitions/ShellScopeEntryAllowedArgs"}],"description":"The allowed arguments for the command execution."},"name":{"description":"The name for this allowed shell command configuration.\n\nThis name will be used inside of the webview API to call this command along with any specified arguments.","type":"string"},"sidecar":{"description":"If this command is a sidecar command.","type":"boolean"}},"required":["name","sidecar"],"type":"object"}],"definitions":{"ShellScopeEntryAllowedArg":{"anyOf":[{"description":"A non-configurable argument that is passed to the command in the order it was specified.","type":"string"},{"additionalProperties":false,"description":"A variable that is set while calling the command from the webview API.","properties":{"raw":{"default":false,"description":"Marks the validator as a raw regex, meaning the plugin should not make any modification at runtime.\n\nThis means the regex will not match on the entire string by default, which might be exploited if your regex allow unexpected input to be considered valid. When using this option, make sure your regex is correct.","type":"boolean"},"validator":{"description":"[regex] validator to require passed values to conform to an expected input.\n\nThis will require the argument value passed to this variable to match the `validator` regex before it will be executed.\n\nThe regex string is by default surrounded by `^...$` to match the full string. For example the `https?://\\w+` regex would be registered as `^https?://\\w+$`.\n\n[regex]: <https://docs.rs/regex/latest/regex/#syntax>","type":"string"}},"required":["validator"],"type":"object"}],"description":"A command argument allowed to be executed by the webview API."},"ShellScopeEntryAllowedArgs":{"anyOf":[{"description":"Use a simple boolean to allow all or disable all arguments to this command configuration.","type":"boolean"},{"description":"A specific set of [`ShellScopeEntryAllowedArg`] that are valid to call for the command configuration.","items":{"$ref":"#/definitions/ShellScopeEntryAllowedArg"},"type":"array"}],"description":"A set of command arguments allowed to be executed by the webview API.\n\nA value of `true` will allow any arguments to be passed to the command. `false` will disable all arguments. A list of [`ShellScopeEntryAllowedArg`] will set those arguments as the only valid arguments to be passed to the attached command configuration."}},"description":"Shell scope entry.","title":"ShellScopeEntry"}},"updater":{"default_permission":{"identifier":"default","description":"This permission set configures which kind of\nupdater functions are exposed to the frontend.\n\n#### Granted Permissions\n\nThe full workflow from checking for updates to installing them\nis enabled.\n\n","permissions":["allow-check","allow-download","allow-install","allow-download-and-install"]},"permissions":{"allow-check":{"identifier":"allow-check","description":"Enables the check command without any pre-configured scope.","commands":{"allow":["check"],"deny":[]}},"allow-download":{"identifier":"allow-download","description":"Enables the download command without any pre-configured scope.","commands":{"allow":["download"],"deny":[]}},"allow-download-and-install":{"identifier":"allow-download-and-install","description":"Enables the download_and_install command without any pre-configured scope.","commands":{"allow":["download_and_install"],"deny":[]}},"allow-install":{"identifier":"allow-install","description":"Enables the install command without any pre-configured scope.","commands":{"allow":["install"],"deny":[]}},"deny-check":{"identifier":"deny-check","description":"Denies the check command without any pre-configured scope.","commands":{"allow":[],"deny":["check"]}},"deny-download":{"identifier":"deny-download","description":"Denies the download command without any pre-configured scope.","commands":{"allow":[],"deny":["download"]}},"deny-download-and-install":{"identifier":"deny-download-and-install","description":"Denies the download_and_install command without any pre-configured scope.","commands":{"allow":[],"deny":["download_and_install"]}},"deny-install":{"identifier":"deny-install","description":"Denies the install command without any pre-configured scope.","commands":{"allow":[],"deny":["install"]}}},"permission_sets":{},"global_scope_schema":null},"window-state":{"default_permission":{"identifier":"default","description":"This permission set configures what kind of\noperations are available from the window state plugin.\n\n#### Granted Permissions\n\nAll operations are enabled by default.\n\n","permissions":["allow-filename","allow-restore-state","allow-save-window-state"]},"permissions":{"allow-filename":{"identifier":"allow-filename","description":"Enables the filename command without any pre-configured scope.","commands":{"allow":["filename"],"deny":[]}},"allow-restore-state":{"identifier":"allow-restore-state","description":"Enables the restore_state command without any pre-configured scope.","commands":{"allow":["restore_state"],"deny":[]}},"allow-save-window-state":{"identifier":"allow-save-window-state","description":"Enables the save_window_state command without any pre-configured scope.","commands":{"allow":["save_window_state"],"deny":[]}},"deny-filename":{"identifier":"deny-filename","description":"Denies the filename command without any pre-configured scope.","commands":{"allow":[],"deny":["filename"]}},"deny-restore-state":{"identifier":"deny-restore-state","description":"Denies the restore_state command without any pre-configured scope.","commands":{"allow":[],"deny":["restore_state"]}},"deny-save-window-state":{"identifier":"deny-save-window-state","description":"Denies the save_window_state command without any pre-configured scope.","commands":{"allow":[],"deny":["save_window_state"]}}},"permission_sets":{},"global_scope_schema":null}}
\ No newline at end of file
+{"app-test-driver":{"default_permission":{"identifier":"default","description":"Default permissions for the app test driver plugin.\n","permissions":["allow-driver-result"]},"permissions":{"allow-driver-result":{"identifier":"allow-driver-result","description":"Enables the driver_result command without any pre-configured scope.","commands":{"allow":["driver_result"],"deny":[]}},"deny-driver-result":{"identifier":"deny-driver-result","description":"Denies the driver_result command without any pre-configured scope.","commands":{"allow":[],"deny":["driver_result"]}}},"permission_sets":{},"global_scope_schema":null},"berdctl":{"default_permission":{"identifier":"default","description":"Default permissions for the app control plugin (the loopback HTTP broker for\nthe berdctl CLI). Grants the main window access to the broker lifecycle,\ntimeout, and bridge-result commands.\n","permissions":["allow-start","allow-stop","allow-status","allow-set-timeouts","allow-submit-result"]},"permissions":{"allow-set-timeouts":{"identifier":"allow-set-timeouts","description":"Enables the set_timeouts command without any pre-configured scope.","commands":{"allow":["set_timeouts"],"deny":[]}},"allow-start":{"identifier":"allow-start","description":"Enables the start command without any pre-configured scope.","commands":{"allow":["start"],"deny":[]}},"allow-status":{"identifier":"allow-status","description":"Enables the status command without any pre-configured scope.","commands":{"allow":["status"],"deny":[]}},"allow-stop":{"identifier":"allow-stop","description":"Enables the stop command without any pre-configured scope.","commands":{"allow":["stop"],"deny":[]}},"allow-submit-result":{"identifier":"allow-submit-result","description":"Enables the submit_result command without any pre-configured scope.","commands":{"allow":["submit_result"],"deny":[]}},"deny-set-timeouts":{"identifier":"deny-set-timeouts","description":"Denies the set_timeouts command without any pre-configured scope.","commands":{"allow":[],"deny":["set_timeouts"]}},"deny-start":{"identifier":"deny-start","description":"Denies the start command without any pre-configured scope.","commands":{"allow":[],"deny":["start"]}},"deny-status":{"identifier":"deny-status","description":"Denies the status command without any pre-configured scope.","commands":{"allow":[],"deny":["status"]}},"deny-stop":{"identifier":"deny-stop","description":"Denies the stop command without any pre-configured scope.","commands":{"allow":[],"deny":["stop"]}},"deny-submit-result":{"identifier":"deny-submit-result","description":"Denies the submit_result command without any pre-configured scope.","commands":{"allow":[],"deny":["submit_result"]}}},"permission_sets":{},"global_scope_schema":null},"clipboard-manager":{"default_permission":{"identifier":"default","description":"No features are enabled by default, as we believe\nthe clipboard can be inherently dangerous and it is \napplication specific if read and/or write access is needed.\n\nClipboard interaction needs to be explicitly enabled.\n","permissions":[]},"permissions":{"allow-clear":{"identifier":"allow-clear","description":"Enables the clear command without any pre-configured scope.","commands":{"allow":["clear"],"deny":[]}},"allow-read-image":{"identifier":"allow-read-image","description":"Enables the read_image command without any pre-configured scope.","commands":{"allow":["read_image"],"deny":[]}},"allow-read-text":{"identifier":"allow-read-text","description":"Enables the read_text command without any pre-configured scope.","commands":{"allow":["read_text"],"deny":[]}},"allow-write-html":{"identifier":"allow-write-html","description":"Enables the write_html command without any pre-configured scope.","commands":{"allow":["write_html"],"deny":[]}},"allow-write-image":{"identifier":"allow-write-image","description":"Enables the write_image command without any pre-configured scope.","commands":{"allow":["write_image"],"deny":[]}},"allow-write-text":{"identifier":"allow-write-text","description":"Enables the write_text command without any pre-configured scope.","commands":{"allow":["write_text"],"deny":[]}},"deny-clear":{"identifier":"deny-clear","description":"Denies the clear command without any pre-configured scope.","commands":{"allow":[],"deny":["clear"]}},"deny-read-image":{"identifier":"deny-read-image","description":"Denies the read_image command without any pre-configured scope.","commands":{"allow":[],"deny":["read_image"]}},"deny-read-text":{"identifier":"deny-read-text","description":"Denies the read_text command without any pre-configured scope.","commands":{"allow":[],"deny":["read_text"]}},"deny-write-html":{"identifier":"deny-write-html","description":"Denies the write_html command without any pre-configured scope.","commands":{"allow":[],"deny":["write_html"]}},"deny-write-image":{"identifier":"deny-write-image","description":"Denies the write_image command without any pre-configured scope.","commands":{"allow":[],"deny":["write_image"]}},"deny-write-text":{"identifier":"deny-write-text","description":"Denies the write_text command without any pre-configured scope.","commands":{"allow":[],"deny":["write_text"]}}},"permission_sets":{},"global_scope_schema":null},"core":{"default_permission":{"identifier":"default","description":"Default core plugins set.","permissions":["core:path:default","core:event:default","core:window:default","core:webview:default","core:app:default","core:image:default","core:resources:default","core:menu:default","core:tray:default"]},"permissions":{},"permission_sets":{},"global_scope_schema":null},"core:app":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin.","permissions":["allow-version","allow-name","allow-tauri-version","allow-identifier","allow-bundle-type","allow-register-listener","allow-remove-listener","allow-supports-multiple-windows"]},"permissions":{"allow-app-hide":{"identifier":"allow-app-hide","description":"Enables the app_hide command without any pre-configured scope.","commands":{"allow":["app_hide"],"deny":[]}},"allow-app-show":{"identifier":"allow-app-show","description":"Enables the app_show command without any pre-configured scope.","commands":{"allow":["app_show"],"deny":[]}},"allow-bundle-type":{"identifier":"allow-bundle-type","description":"Enables the bundle_type command without any pre-configured scope.","commands":{"allow":["bundle_type"],"deny":[]}},"allow-default-window-icon":{"identifier":"allow-default-window-icon","description":"Enables the default_window_icon command without any pre-configured scope.","commands":{"allow":["default_window_icon"],"deny":[]}},"allow-fetch-data-store-identifiers":{"identifier":"allow-fetch-data-store-identifiers","description":"Enables the fetch_data_store_identifiers command without any pre-configured scope.","commands":{"allow":["fetch_data_store_identifiers"],"deny":[]}},"allow-identifier":{"identifier":"allow-identifier","description":"Enables the identifier command without any pre-configured scope.","commands":{"allow":["identifier"],"deny":[]}},"allow-name":{"identifier":"allow-name","description":"Enables the name command without any pre-configured scope.","commands":{"allow":["name"],"deny":[]}},"allow-register-listener":{"identifier":"allow-register-listener","description":"Enables the register_listener command without any pre-configured scope.","commands":{"allow":["register_listener"],"deny":[]}},"allow-remove-data-store":{"identifier":"allow-remove-data-store","description":"Enables the remove_data_store command without any pre-configured scope.","commands":{"allow":["remove_data_store"],"deny":[]}},"allow-remove-listener":{"identifier":"allow-remove-listener","description":"Enables the remove_listener command without any pre-configured scope.","commands":{"allow":["remove_listener"],"deny":[]}},"allow-set-app-theme":{"identifier":"allow-set-app-theme","description":"Enables the set_app_theme command without any pre-configured scope.","commands":{"allow":["set_app_theme"],"deny":[]}},"allow-set-dock-visibility":{"identifier":"allow-set-dock-visibility","description":"Enables the set_dock_visibility command without any pre-configured scope.","commands":{"allow":["set_dock_visibility"],"deny":[]}},"allow-supports-multiple-windows":{"identifier":"allow-supports-multiple-windows","description":"Enables the supports_multiple_windows command without any pre-configured scope.","commands":{"allow":["supports_multiple_windows"],"deny":[]}},"allow-tauri-version":{"identifier":"allow-tauri-version","description":"Enables the tauri_version command without any pre-configured scope.","commands":{"allow":["tauri_version"],"deny":[]}},"allow-version":{"identifier":"allow-version","description":"Enables the version command without any pre-configured scope.","commands":{"allow":["version"],"deny":[]}},"deny-app-hide":{"identifier":"deny-app-hide","description":"Denies the app_hide command without any pre-configured scope.","commands":{"allow":[],"deny":["app_hide"]}},"deny-app-show":{"identifier":"deny-app-show","description":"Denies the app_show command without any pre-configured scope.","commands":{"allow":[],"deny":["app_show"]}},"deny-bundle-type":{"identifier":"deny-bundle-type","description":"Denies the bundle_type command without any pre-configured scope.","commands":{"allow":[],"deny":["bundle_type"]}},"deny-default-window-icon":{"identifier":"deny-default-window-icon","description":"Denies the default_window_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["default_window_icon"]}},"deny-fetch-data-store-identifiers":{"identifier":"deny-fetch-data-store-identifiers","description":"Denies the fetch_data_store_identifiers command without any pre-configured scope.","commands":{"allow":[],"deny":["fetch_data_store_identifiers"]}},"deny-identifier":{"identifier":"deny-identifier","description":"Denies the identifier command without any pre-configured scope.","commands":{"allow":[],"deny":["identifier"]}},"deny-name":{"identifier":"deny-name","description":"Denies the name command without any pre-configured scope.","commands":{"allow":[],"deny":["name"]}},"deny-register-listener":{"identifier":"deny-register-listener","description":"Denies the register_listener command without any pre-configured scope.","commands":{"allow":[],"deny":["register_listener"]}},"deny-remove-data-store":{"identifier":"deny-remove-data-store","description":"Denies the remove_data_store command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_data_store"]}},"deny-remove-listener":{"identifier":"deny-remove-listener","description":"Denies the remove_listener command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_listener"]}},"deny-set-app-theme":{"identifier":"deny-set-app-theme","description":"Denies the set_app_theme command without any pre-configured scope.","commands":{"allow":[],"deny":["set_app_theme"]}},"deny-set-dock-visibility":{"identifier":"deny-set-dock-visibility","description":"Denies the set_dock_visibility command without any pre-configured scope.","commands":{"allow":[],"deny":["set_dock_visibility"]}},"deny-supports-multiple-windows":{"identifier":"deny-supports-multiple-windows","description":"Denies the supports_multiple_windows command without any pre-configured scope.","commands":{"allow":[],"deny":["supports_multiple_windows"]}},"deny-tauri-version":{"identifier":"deny-tauri-version","description":"Denies the tauri_version command without any pre-configured scope.","commands":{"allow":[],"deny":["tauri_version"]}},"deny-version":{"identifier":"deny-version","description":"Denies the version command without any pre-configured scope.","commands":{"allow":[],"deny":["version"]}}},"permission_sets":{},"global_scope_schema":null},"core:event":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-listen","allow-unlisten","allow-emit","allow-emit-to"]},"permissions":{"allow-emit":{"identifier":"allow-emit","description":"Enables the emit command without any pre-configured scope.","commands":{"allow":["emit"],"deny":[]}},"allow-emit-to":{"identifier":"allow-emit-to","description":"Enables the emit_to command without any pre-configured scope.","commands":{"allow":["emit_to"],"deny":[]}},"allow-listen":{"identifier":"allow-listen","description":"Enables the listen command without any pre-configured scope.","commands":{"allow":["listen"],"deny":[]}},"allow-unlisten":{"identifier":"allow-unlisten","description":"Enables the unlisten command without any pre-configured scope.","commands":{"allow":["unlisten"],"deny":[]}},"deny-emit":{"identifier":"deny-emit","description":"Denies the emit command without any pre-configured scope.","commands":{"allow":[],"deny":["emit"]}},"deny-emit-to":{"identifier":"deny-emit-to","description":"Denies the emit_to command without any pre-configured scope.","commands":{"allow":[],"deny":["emit_to"]}},"deny-listen":{"identifier":"deny-listen","description":"Denies the listen command without any pre-configured scope.","commands":{"allow":[],"deny":["listen"]}},"deny-unlisten":{"identifier":"deny-unlisten","description":"Denies the unlisten command without any pre-configured scope.","commands":{"allow":[],"deny":["unlisten"]}}},"permission_sets":{},"global_scope_schema":null},"core:image":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-new","allow-from-bytes","allow-from-path","allow-rgba","allow-size"]},"permissions":{"allow-from-bytes":{"identifier":"allow-from-bytes","description":"Enables the from_bytes command without any pre-configured scope.","commands":{"allow":["from_bytes"],"deny":[]}},"allow-from-path":{"identifier":"allow-from-path","description":"Enables the from_path command without any pre-configured scope.","commands":{"allow":["from_path"],"deny":[]}},"allow-new":{"identifier":"allow-new","description":"Enables the new command without any pre-configured scope.","commands":{"allow":["new"],"deny":[]}},"allow-rgba":{"identifier":"allow-rgba","description":"Enables the rgba command without any pre-configured scope.","commands":{"allow":["rgba"],"deny":[]}},"allow-size":{"identifier":"allow-size","description":"Enables the size command without any pre-configured scope.","commands":{"allow":["size"],"deny":[]}},"deny-from-bytes":{"identifier":"deny-from-bytes","description":"Denies the from_bytes command without any pre-configured scope.","commands":{"allow":[],"deny":["from_bytes"]}},"deny-from-path":{"identifier":"deny-from-path","description":"Denies the from_path command without any pre-configured scope.","commands":{"allow":[],"deny":["from_path"]}},"deny-new":{"identifier":"deny-new","description":"Denies the new command without any pre-configured scope.","commands":{"allow":[],"deny":["new"]}},"deny-rgba":{"identifier":"deny-rgba","description":"Denies the rgba command without any pre-configured scope.","commands":{"allow":[],"deny":["rgba"]}},"deny-size":{"identifier":"deny-size","description":"Denies the size command without any pre-configured scope.","commands":{"allow":[],"deny":["size"]}}},"permission_sets":{},"global_scope_schema":null},"core:menu":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-new","allow-append","allow-prepend","allow-insert","allow-remove","allow-remove-at","allow-items","allow-get","allow-popup","allow-create-default","allow-set-as-app-menu","allow-set-as-window-menu","allow-text","allow-set-text","allow-is-enabled","allow-set-enabled","allow-set-accelerator","allow-set-as-windows-menu-for-nsapp","allow-set-as-help-menu-for-nsapp","allow-is-checked","allow-set-checked","allow-set-icon"]},"permissions":{"allow-append":{"identifier":"allow-append","description":"Enables the append command without any pre-configured scope.","commands":{"allow":["append"],"deny":[]}},"allow-create-default":{"identifier":"allow-create-default","description":"Enables the create_default command without any pre-configured scope.","commands":{"allow":["create_default"],"deny":[]}},"allow-get":{"identifier":"allow-get","description":"Enables the get command without any pre-configured scope.","commands":{"allow":["get"],"deny":[]}},"allow-insert":{"identifier":"allow-insert","description":"Enables the insert command without any pre-configured scope.","commands":{"allow":["insert"],"deny":[]}},"allow-is-checked":{"identifier":"allow-is-checked","description":"Enables the is_checked command without any pre-configured scope.","commands":{"allow":["is_checked"],"deny":[]}},"allow-is-enabled":{"identifier":"allow-is-enabled","description":"Enables the is_enabled command without any pre-configured scope.","commands":{"allow":["is_enabled"],"deny":[]}},"allow-items":{"identifier":"allow-items","description":"Enables the items command without any pre-configured scope.","commands":{"allow":["items"],"deny":[]}},"allow-new":{"identifier":"allow-new","description":"Enables the new command without any pre-configured scope.","commands":{"allow":["new"],"deny":[]}},"allow-popup":{"identifier":"allow-popup","description":"Enables the popup command without any pre-configured scope.","commands":{"allow":["popup"],"deny":[]}},"allow-prepend":{"identifier":"allow-prepend","description":"Enables the prepend command without any pre-configured scope.","commands":{"allow":["prepend"],"deny":[]}},"allow-remove":{"identifier":"allow-remove","description":"Enables the remove command without any pre-configured scope.","commands":{"allow":["remove"],"deny":[]}},"allow-remove-at":{"identifier":"allow-remove-at","description":"Enables the remove_at command without any pre-configured scope.","commands":{"allow":["remove_at"],"deny":[]}},"allow-set-accelerator":{"identifier":"allow-set-accelerator","description":"Enables the set_accelerator command without any pre-configured scope.","commands":{"allow":["set_accelerator"],"deny":[]}},"allow-set-as-app-menu":{"identifier":"allow-set-as-app-menu","description":"Enables the set_as_app_menu command without any pre-configured scope.","commands":{"allow":["set_as_app_menu"],"deny":[]}},"allow-set-as-help-menu-for-nsapp":{"identifier":"allow-set-as-help-menu-for-nsapp","description":"Enables the set_as_help_menu_for_nsapp command without any pre-configured scope.","commands":{"allow":["set_as_help_menu_for_nsapp"],"deny":[]}},"allow-set-as-window-menu":{"identifier":"allow-set-as-window-menu","description":"Enables the set_as_window_menu command without any pre-configured scope.","commands":{"allow":["set_as_window_menu"],"deny":[]}},"allow-set-as-windows-menu-for-nsapp":{"identifier":"allow-set-as-windows-menu-for-nsapp","description":"Enables the set_as_windows_menu_for_nsapp command without any pre-configured scope.","commands":{"allow":["set_as_windows_menu_for_nsapp"],"deny":[]}},"allow-set-checked":{"identifier":"allow-set-checked","description":"Enables the set_checked command without any pre-configured scope.","commands":{"allow":["set_checked"],"deny":[]}},"allow-set-enabled":{"identifier":"allow-set-enabled","description":"Enables the set_enabled command without any pre-configured scope.","commands":{"allow":["set_enabled"],"deny":[]}},"allow-set-icon":{"identifier":"allow-set-icon","description":"Enables the set_icon command without any pre-configured scope.","commands":{"allow":["set_icon"],"deny":[]}},"allow-set-text":{"identifier":"allow-set-text","description":"Enables the set_text command without any pre-configured scope.","commands":{"allow":["set_text"],"deny":[]}},"allow-text":{"identifier":"allow-text","description":"Enables the text command without any pre-configured scope.","commands":{"allow":["text"],"deny":[]}},"deny-append":{"identifier":"deny-append","description":"Denies the append command without any pre-configured scope.","commands":{"allow":[],"deny":["append"]}},"deny-create-default":{"identifier":"deny-create-default","description":"Denies the create_default command without any pre-configured scope.","commands":{"allow":[],"deny":["create_default"]}},"deny-get":{"identifier":"deny-get","description":"Denies the get command without any pre-configured scope.","commands":{"allow":[],"deny":["get"]}},"deny-insert":{"identifier":"deny-insert","description":"Denies the insert command without any pre-configured scope.","commands":{"allow":[],"deny":["insert"]}},"deny-is-checked":{"identifier":"deny-is-checked","description":"Denies the is_checked command without any pre-configured scope.","commands":{"allow":[],"deny":["is_checked"]}},"deny-is-enabled":{"identifier":"deny-is-enabled","description":"Denies the is_enabled command without any pre-configured scope.","commands":{"allow":[],"deny":["is_enabled"]}},"deny-items":{"identifier":"deny-items","description":"Denies the items command without any pre-configured scope.","commands":{"allow":[],"deny":["items"]}},"deny-new":{"identifier":"deny-new","description":"Denies the new command without any pre-configured scope.","commands":{"allow":[],"deny":["new"]}},"deny-popup":{"identifier":"deny-popup","description":"Denies the popup command without any pre-configured scope.","commands":{"allow":[],"deny":["popup"]}},"deny-prepend":{"identifier":"deny-prepend","description":"Denies the prepend command without any pre-configured scope.","commands":{"allow":[],"deny":["prepend"]}},"deny-remove":{"identifier":"deny-remove","description":"Denies the remove command without any pre-configured scope.","commands":{"allow":[],"deny":["remove"]}},"deny-remove-at":{"identifier":"deny-remove-at","description":"Denies the remove_at command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_at"]}},"deny-set-accelerator":{"identifier":"deny-set-accelerator","description":"Denies the set_accelerator command without any pre-configured scope.","commands":{"allow":[],"deny":["set_accelerator"]}},"deny-set-as-app-menu":{"identifier":"deny-set-as-app-menu","description":"Denies the set_as_app_menu command without any pre-configured scope.","commands":{"allow":[],"deny":["set_as_app_menu"]}},"deny-set-as-help-menu-for-nsapp":{"identifier":"deny-set-as-help-menu-for-nsapp","description":"Denies the set_as_help_menu_for_nsapp command without any pre-configured scope.","commands":{"allow":[],"deny":["set_as_help_menu_for_nsapp"]}},"deny-set-as-window-menu":{"identifier":"deny-set-as-window-menu","description":"Denies the set_as_window_menu command without any pre-configured scope.","commands":{"allow":[],"deny":["set_as_window_menu"]}},"deny-set-as-windows-menu-for-nsapp":{"identifier":"deny-set-as-windows-menu-for-nsapp","description":"Denies the set_as_windows_menu_for_nsapp command without any pre-configured scope.","commands":{"allow":[],"deny":["set_as_windows_menu_for_nsapp"]}},"deny-set-checked":{"identifier":"deny-set-checked","description":"Denies the set_checked command without any pre-configured scope.","commands":{"allow":[],"deny":["set_checked"]}},"deny-set-enabled":{"identifier":"deny-set-enabled","description":"Denies the set_enabled command without any pre-configured scope.","commands":{"allow":[],"deny":["set_enabled"]}},"deny-set-icon":{"identifier":"deny-set-icon","description":"Denies the set_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon"]}},"deny-set-text":{"identifier":"deny-set-text","description":"Denies the set_text command without any pre-configured scope.","commands":{"allow":[],"deny":["set_text"]}},"deny-text":{"identifier":"deny-text","description":"Denies the text command without any pre-configured scope.","commands":{"allow":[],"deny":["text"]}}},"permission_sets":{},"global_scope_schema":null},"core:path":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-resolve-directory","allow-resolve","allow-normalize","allow-join","allow-dirname","allow-extname","allow-basename","allow-is-absolute"]},"permissions":{"allow-basename":{"identifier":"allow-basename","description":"Enables the basename command without any pre-configured scope.","commands":{"allow":["basename"],"deny":[]}},"allow-dirname":{"identifier":"allow-dirname","description":"Enables the dirname command without any pre-configured scope.","commands":{"allow":["dirname"],"deny":[]}},"allow-extname":{"identifier":"allow-extname","description":"Enables the extname command without any pre-configured scope.","commands":{"allow":["extname"],"deny":[]}},"allow-is-absolute":{"identifier":"allow-is-absolute","description":"Enables the is_absolute command without any pre-configured scope.","commands":{"allow":["is_absolute"],"deny":[]}},"allow-join":{"identifier":"allow-join","description":"Enables the join command without any pre-configured scope.","commands":{"allow":["join"],"deny":[]}},"allow-normalize":{"identifier":"allow-normalize","description":"Enables the normalize command without any pre-configured scope.","commands":{"allow":["normalize"],"deny":[]}},"allow-resolve":{"identifier":"allow-resolve","description":"Enables the resolve command without any pre-configured scope.","commands":{"allow":["resolve"],"deny":[]}},"allow-resolve-directory":{"identifier":"allow-resolve-directory","description":"Enables the resolve_directory command without any pre-configured scope.","commands":{"allow":["resolve_directory"],"deny":[]}},"deny-basename":{"identifier":"deny-basename","description":"Denies the basename command without any pre-configured scope.","commands":{"allow":[],"deny":["basename"]}},"deny-dirname":{"identifier":"deny-dirname","description":"Denies the dirname command without any pre-configured scope.","commands":{"allow":[],"deny":["dirname"]}},"deny-extname":{"identifier":"deny-extname","description":"Denies the extname command without any pre-configured scope.","commands":{"allow":[],"deny":["extname"]}},"deny-is-absolute":{"identifier":"deny-is-absolute","description":"Denies the is_absolute command without any pre-configured scope.","commands":{"allow":[],"deny":["is_absolute"]}},"deny-join":{"identifier":"deny-join","description":"Denies the join command without any pre-configured scope.","commands":{"allow":[],"deny":["join"]}},"deny-normalize":{"identifier":"deny-normalize","description":"Denies the normalize command without any pre-configured scope.","commands":{"allow":[],"deny":["normalize"]}},"deny-resolve":{"identifier":"deny-resolve","description":"Denies the resolve command without any pre-configured scope.","commands":{"allow":[],"deny":["resolve"]}},"deny-resolve-directory":{"identifier":"deny-resolve-directory","description":"Denies the resolve_directory command without any pre-configured scope.","commands":{"allow":[],"deny":["resolve_directory"]}}},"permission_sets":{},"global_scope_schema":null},"core:resources":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-close"]},"permissions":{"allow-close":{"identifier":"allow-close","description":"Enables the close command without any pre-configured scope.","commands":{"allow":["close"],"deny":[]}},"deny-close":{"identifier":"deny-close","description":"Denies the close command without any pre-configured scope.","commands":{"allow":[],"deny":["close"]}}},"permission_sets":{},"global_scope_schema":null},"core:tray":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin, which enables all commands.","permissions":["allow-new","allow-get-by-id","allow-remove-by-id","allow-set-icon","allow-set-menu","allow-set-tooltip","allow-set-title","allow-set-visible","allow-set-temp-dir-path","allow-set-icon-as-template","allow-set-icon-with-as-template","allow-set-show-menu-on-left-click"]},"permissions":{"allow-get-by-id":{"identifier":"allow-get-by-id","description":"Enables the get_by_id command without any pre-configured scope.","commands":{"allow":["get_by_id"],"deny":[]}},"allow-new":{"identifier":"allow-new","description":"Enables the new command without any pre-configured scope.","commands":{"allow":["new"],"deny":[]}},"allow-remove-by-id":{"identifier":"allow-remove-by-id","description":"Enables the remove_by_id command without any pre-configured scope.","commands":{"allow":["remove_by_id"],"deny":[]}},"allow-set-icon":{"identifier":"allow-set-icon","description":"Enables the set_icon command without any pre-configured scope.","commands":{"allow":["set_icon"],"deny":[]}},"allow-set-icon-as-template":{"identifier":"allow-set-icon-as-template","description":"Enables the set_icon_as_template command without any pre-configured scope.","commands":{"allow":["set_icon_as_template"],"deny":[]}},"allow-set-icon-with-as-template":{"identifier":"allow-set-icon-with-as-template","description":"Enables the set_icon_with_as_template command without any pre-configured scope.","commands":{"allow":["set_icon_with_as_template"],"deny":[]}},"allow-set-menu":{"identifier":"allow-set-menu","description":"Enables the set_menu command without any pre-configured scope.","commands":{"allow":["set_menu"],"deny":[]}},"allow-set-show-menu-on-left-click":{"identifier":"allow-set-show-menu-on-left-click","description":"Enables the set_show_menu_on_left_click command without any pre-configured scope.","commands":{"allow":["set_show_menu_on_left_click"],"deny":[]}},"allow-set-temp-dir-path":{"identifier":"allow-set-temp-dir-path","description":"Enables the set_temp_dir_path command without any pre-configured scope.","commands":{"allow":["set_temp_dir_path"],"deny":[]}},"allow-set-title":{"identifier":"allow-set-title","description":"Enables the set_title command without any pre-configured scope.","commands":{"allow":["set_title"],"deny":[]}},"allow-set-tooltip":{"identifier":"allow-set-tooltip","description":"Enables the set_tooltip command without any pre-configured scope.","commands":{"allow":["set_tooltip"],"deny":[]}},"allow-set-visible":{"identifier":"allow-set-visible","description":"Enables the set_visible command without any pre-configured scope.","commands":{"allow":["set_visible"],"deny":[]}},"deny-get-by-id":{"identifier":"deny-get-by-id","description":"Denies the get_by_id command without any pre-configured scope.","commands":{"allow":[],"deny":["get_by_id"]}},"deny-new":{"identifier":"deny-new","description":"Denies the new command without any pre-configured scope.","commands":{"allow":[],"deny":["new"]}},"deny-remove-by-id":{"identifier":"deny-remove-by-id","description":"Denies the remove_by_id command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_by_id"]}},"deny-set-icon":{"identifier":"deny-set-icon","description":"Denies the set_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon"]}},"deny-set-icon-as-template":{"identifier":"deny-set-icon-as-template","description":"Denies the set_icon_as_template command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon_as_template"]}},"deny-set-icon-with-as-template":{"identifier":"deny-set-icon-with-as-template","description":"Denies the set_icon_with_as_template command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon_with_as_template"]}},"deny-set-menu":{"identifier":"deny-set-menu","description":"Denies the set_menu command without any pre-configured scope.","commands":{"allow":[],"deny":["set_menu"]}},"deny-set-show-menu-on-left-click":{"identifier":"deny-set-show-menu-on-left-click","description":"Denies the set_show_menu_on_left_click command without any pre-configured scope.","commands":{"allow":[],"deny":["set_show_menu_on_left_click"]}},"deny-set-temp-dir-path":{"identifier":"deny-set-temp-dir-path","description":"Denies the set_temp_dir_path command without any pre-configured scope.","commands":{"allow":[],"deny":["set_temp_dir_path"]}},"deny-set-title":{"identifier":"deny-set-title","description":"Denies the set_title command without any pre-configured scope.","commands":{"allow":[],"deny":["set_title"]}},"deny-set-tooltip":{"identifier":"deny-set-tooltip","description":"Denies the set_tooltip command without any pre-configured scope.","commands":{"allow":[],"deny":["set_tooltip"]}},"deny-set-visible":{"identifier":"deny-set-visible","description":"Denies the set_visible command without any pre-configured scope.","commands":{"allow":[],"deny":["set_visible"]}}},"permission_sets":{},"global_scope_schema":null},"core:webview":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin.","permissions":["allow-get-all-webviews","allow-webview-position","allow-webview-size","allow-internal-toggle-devtools"]},"permissions":{"allow-clear-all-browsing-data":{"identifier":"allow-clear-all-browsing-data","description":"Enables the clear_all_browsing_data command without any pre-configured scope.","commands":{"allow":["clear_all_browsing_data"],"deny":[]}},"allow-create-webview":{"identifier":"allow-create-webview","description":"Enables the create_webview command without any pre-configured scope.","commands":{"allow":["create_webview"],"deny":[]}},"allow-create-webview-window":{"identifier":"allow-create-webview-window","description":"Enables the create_webview_window command without any pre-configured scope.","commands":{"allow":["create_webview_window"],"deny":[]}},"allow-get-all-webviews":{"identifier":"allow-get-all-webviews","description":"Enables the get_all_webviews command without any pre-configured scope.","commands":{"allow":["get_all_webviews"],"deny":[]}},"allow-internal-toggle-devtools":{"identifier":"allow-internal-toggle-devtools","description":"Enables the internal_toggle_devtools command without any pre-configured scope.","commands":{"allow":["internal_toggle_devtools"],"deny":[]}},"allow-print":{"identifier":"allow-print","description":"Enables the print command without any pre-configured scope.","commands":{"allow":["print"],"deny":[]}},"allow-reparent":{"identifier":"allow-reparent","description":"Enables the reparent command without any pre-configured scope.","commands":{"allow":["reparent"],"deny":[]}},"allow-set-webview-auto-resize":{"identifier":"allow-set-webview-auto-resize","description":"Enables the set_webview_auto_resize command without any pre-configured scope.","commands":{"allow":["set_webview_auto_resize"],"deny":[]}},"allow-set-webview-background-color":{"identifier":"allow-set-webview-background-color","description":"Enables the set_webview_background_color command without any pre-configured scope.","commands":{"allow":["set_webview_background_color"],"deny":[]}},"allow-set-webview-focus":{"identifier":"allow-set-webview-focus","description":"Enables the set_webview_focus command without any pre-configured scope.","commands":{"allow":["set_webview_focus"],"deny":[]}},"allow-set-webview-position":{"identifier":"allow-set-webview-position","description":"Enables the set_webview_position command without any pre-configured scope.","commands":{"allow":["set_webview_position"],"deny":[]}},"allow-set-webview-size":{"identifier":"allow-set-webview-size","description":"Enables the set_webview_size command without any pre-configured scope.","commands":{"allow":["set_webview_size"],"deny":[]}},"allow-set-webview-zoom":{"identifier":"allow-set-webview-zoom","description":"Enables the set_webview_zoom command without any pre-configured scope.","commands":{"allow":["set_webview_zoom"],"deny":[]}},"allow-webview-close":{"identifier":"allow-webview-close","description":"Enables the webview_close command without any pre-configured scope.","commands":{"allow":["webview_close"],"deny":[]}},"allow-webview-hide":{"identifier":"allow-webview-hide","description":"Enables the webview_hide command without any pre-configured scope.","commands":{"allow":["webview_hide"],"deny":[]}},"allow-webview-position":{"identifier":"allow-webview-position","description":"Enables the webview_position command without any pre-configured scope.","commands":{"allow":["webview_position"],"deny":[]}},"allow-webview-show":{"identifier":"allow-webview-show","description":"Enables the webview_show command without any pre-configured scope.","commands":{"allow":["webview_show"],"deny":[]}},"allow-webview-size":{"identifier":"allow-webview-size","description":"Enables the webview_size command without any pre-configured scope.","commands":{"allow":["webview_size"],"deny":[]}},"deny-clear-all-browsing-data":{"identifier":"deny-clear-all-browsing-data","description":"Denies the clear_all_browsing_data command without any pre-configured scope.","commands":{"allow":[],"deny":["clear_all_browsing_data"]}},"deny-create-webview":{"identifier":"deny-create-webview","description":"Denies the create_webview command without any pre-configured scope.","commands":{"allow":[],"deny":["create_webview"]}},"deny-create-webview-window":{"identifier":"deny-create-webview-window","description":"Denies the create_webview_window command without any pre-configured scope.","commands":{"allow":[],"deny":["create_webview_window"]}},"deny-get-all-webviews":{"identifier":"deny-get-all-webviews","description":"Denies the get_all_webviews command without any pre-configured scope.","commands":{"allow":[],"deny":["get_all_webviews"]}},"deny-internal-toggle-devtools":{"identifier":"deny-internal-toggle-devtools","description":"Denies the internal_toggle_devtools command without any pre-configured scope.","commands":{"allow":[],"deny":["internal_toggle_devtools"]}},"deny-print":{"identifier":"deny-print","description":"Denies the print command without any pre-configured scope.","commands":{"allow":[],"deny":["print"]}},"deny-reparent":{"identifier":"deny-reparent","description":"Denies the reparent command without any pre-configured scope.","commands":{"allow":[],"deny":["reparent"]}},"deny-set-webview-auto-resize":{"identifier":"deny-set-webview-auto-resize","description":"Denies the set_webview_auto_resize command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_auto_resize"]}},"deny-set-webview-background-color":{"identifier":"deny-set-webview-background-color","description":"Denies the set_webview_background_color command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_background_color"]}},"deny-set-webview-focus":{"identifier":"deny-set-webview-focus","description":"Denies the set_webview_focus command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_focus"]}},"deny-set-webview-position":{"identifier":"deny-set-webview-position","description":"Denies the set_webview_position command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_position"]}},"deny-set-webview-size":{"identifier":"deny-set-webview-size","description":"Denies the set_webview_size command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_size"]}},"deny-set-webview-zoom":{"identifier":"deny-set-webview-zoom","description":"Denies the set_webview_zoom command without any pre-configured scope.","commands":{"allow":[],"deny":["set_webview_zoom"]}},"deny-webview-close":{"identifier":"deny-webview-close","description":"Denies the webview_close command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_close"]}},"deny-webview-hide":{"identifier":"deny-webview-hide","description":"Denies the webview_hide command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_hide"]}},"deny-webview-position":{"identifier":"deny-webview-position","description":"Denies the webview_position command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_position"]}},"deny-webview-show":{"identifier":"deny-webview-show","description":"Denies the webview_show command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_show"]}},"deny-webview-size":{"identifier":"deny-webview-size","description":"Denies the webview_size command without any pre-configured scope.","commands":{"allow":[],"deny":["webview_size"]}}},"permission_sets":{},"global_scope_schema":null},"core:window":{"default_permission":{"identifier":"default","description":"Default permissions for the plugin.","permissions":["allow-get-all-windows","allow-scale-factor","allow-inner-position","allow-outer-position","allow-inner-size","allow-outer-size","allow-is-fullscreen","allow-is-minimized","allow-is-maximized","allow-is-focused","allow-is-decorated","allow-is-resizable","allow-is-maximizable","allow-is-minimizable","allow-is-closable","allow-is-visible","allow-is-enabled","allow-title","allow-current-monitor","allow-primary-monitor","allow-monitor-from-point","allow-available-monitors","allow-cursor-position","allow-theme","allow-is-always-on-top","allow-activity-name","allow-scene-identifier","allow-internal-toggle-maximize"]},"permissions":{"allow-activity-name":{"identifier":"allow-activity-name","description":"Enables the activity_name command without any pre-configured scope.","commands":{"allow":["activity_name"],"deny":[]}},"allow-available-monitors":{"identifier":"allow-available-monitors","description":"Enables the available_monitors command without any pre-configured scope.","commands":{"allow":["available_monitors"],"deny":[]}},"allow-center":{"identifier":"allow-center","description":"Enables the center command without any pre-configured scope.","commands":{"allow":["center"],"deny":[]}},"allow-close":{"identifier":"allow-close","description":"Enables the close command without any pre-configured scope.","commands":{"allow":["close"],"deny":[]}},"allow-create":{"identifier":"allow-create","description":"Enables the create command without any pre-configured scope.","commands":{"allow":["create"],"deny":[]}},"allow-current-monitor":{"identifier":"allow-current-monitor","description":"Enables the current_monitor command without any pre-configured scope.","commands":{"allow":["current_monitor"],"deny":[]}},"allow-cursor-position":{"identifier":"allow-cursor-position","description":"Enables the cursor_position command without any pre-configured scope.","commands":{"allow":["cursor_position"],"deny":[]}},"allow-destroy":{"identifier":"allow-destroy","description":"Enables the destroy command without any pre-configured scope.","commands":{"allow":["destroy"],"deny":[]}},"allow-get-all-windows":{"identifier":"allow-get-all-windows","description":"Enables the get_all_windows command without any pre-configured scope.","commands":{"allow":["get_all_windows"],"deny":[]}},"allow-hide":{"identifier":"allow-hide","description":"Enables the hide command without any pre-configured scope.","commands":{"allow":["hide"],"deny":[]}},"allow-inner-position":{"identifier":"allow-inner-position","description":"Enables the inner_position command without any pre-configured scope.","commands":{"allow":["inner_position"],"deny":[]}},"allow-inner-size":{"identifier":"allow-inner-size","description":"Enables the inner_size command without any pre-configured scope.","commands":{"allow":["inner_size"],"deny":[]}},"allow-internal-toggle-maximize":{"identifier":"allow-internal-toggle-maximize","description":"Enables the internal_toggle_maximize command without any pre-configured scope.","commands":{"allow":["internal_toggle_maximize"],"deny":[]}},"allow-is-always-on-top":{"identifier":"allow-is-always-on-top","description":"Enables the is_always_on_top command without any pre-configured scope.","commands":{"allow":["is_always_on_top"],"deny":[]}},"allow-is-closable":{"identifier":"allow-is-closable","description":"Enables the is_closable command without any pre-configured scope.","commands":{"allow":["is_closable"],"deny":[]}},"allow-is-decorated":{"identifier":"allow-is-decorated","description":"Enables the is_decorated command without any pre-configured scope.","commands":{"allow":["is_decorated"],"deny":[]}},"allow-is-enabled":{"identifier":"allow-is-enabled","description":"Enables the is_enabled command without any pre-configured scope.","commands":{"allow":["is_enabled"],"deny":[]}},"allow-is-focused":{"identifier":"allow-is-focused","description":"Enables the is_focused command without any pre-configured scope.","commands":{"allow":["is_focused"],"deny":[]}},"allow-is-fullscreen":{"identifier":"allow-is-fullscreen","description":"Enables the is_fullscreen command without any pre-configured scope.","commands":{"allow":["is_fullscreen"],"deny":[]}},"allow-is-maximizable":{"identifier":"allow-is-maximizable","description":"Enables the is_maximizable command without any pre-configured scope.","commands":{"allow":["is_maximizable"],"deny":[]}},"allow-is-maximized":{"identifier":"allow-is-maximized","description":"Enables the is_maximized command without any pre-configured scope.","commands":{"allow":["is_maximized"],"deny":[]}},"allow-is-minimizable":{"identifier":"allow-is-minimizable","description":"Enables the is_minimizable command without any pre-configured scope.","commands":{"allow":["is_minimizable"],"deny":[]}},"allow-is-minimized":{"identifier":"allow-is-minimized","description":"Enables the is_minimized command without any pre-configured scope.","commands":{"allow":["is_minimized"],"deny":[]}},"allow-is-resizable":{"identifier":"allow-is-resizable","description":"Enables the is_resizable command without any pre-configured scope.","commands":{"allow":["is_resizable"],"deny":[]}},"allow-is-visible":{"identifier":"allow-is-visible","description":"Enables the is_visible command without any pre-configured scope.","commands":{"allow":["is_visible"],"deny":[]}},"allow-maximize":{"identifier":"allow-maximize","description":"Enables the maximize command without any pre-configured scope.","commands":{"allow":["maximize"],"deny":[]}},"allow-minimize":{"identifier":"allow-minimize","description":"Enables the minimize command without any pre-configured scope.","commands":{"allow":["minimize"],"deny":[]}},"allow-monitor-from-point":{"identifier":"allow-monitor-from-point","description":"Enables the monitor_from_point command without any pre-configured scope.","commands":{"allow":["monitor_from_point"],"deny":[]}},"allow-outer-position":{"identifier":"allow-outer-position","description":"Enables the outer_position command without any pre-configured scope.","commands":{"allow":["outer_position"],"deny":[]}},"allow-outer-size":{"identifier":"allow-outer-size","description":"Enables the outer_size command without any pre-configured scope.","commands":{"allow":["outer_size"],"deny":[]}},"allow-primary-monitor":{"identifier":"allow-primary-monitor","description":"Enables the primary_monitor command without any pre-configured scope.","commands":{"allow":["primary_monitor"],"deny":[]}},"allow-request-user-attention":{"identifier":"allow-request-user-attention","description":"Enables the request_user_attention command without any pre-configured scope.","commands":{"allow":["request_user_attention"],"deny":[]}},"allow-scale-factor":{"identifier":"allow-scale-factor","description":"Enables the scale_factor command without any pre-configured scope.","commands":{"allow":["scale_factor"],"deny":[]}},"allow-scene-identifier":{"identifier":"allow-scene-identifier","description":"Enables the scene_identifier command without any pre-configured scope.","commands":{"allow":["scene_identifier"],"deny":[]}},"allow-set-always-on-bottom":{"identifier":"allow-set-always-on-bottom","description":"Enables the set_always_on_bottom command without any pre-configured scope.","commands":{"allow":["set_always_on_bottom"],"deny":[]}},"allow-set-always-on-top":{"identifier":"allow-set-always-on-top","description":"Enables the set_always_on_top command without any pre-configured scope.","commands":{"allow":["set_always_on_top"],"deny":[]}},"allow-set-background-color":{"identifier":"allow-set-background-color","description":"Enables the set_background_color command without any pre-configured scope.","commands":{"allow":["set_background_color"],"deny":[]}},"allow-set-badge-count":{"identifier":"allow-set-badge-count","description":"Enables the set_badge_count command without any pre-configured scope.","commands":{"allow":["set_badge_count"],"deny":[]}},"allow-set-badge-label":{"identifier":"allow-set-badge-label","description":"Enables the set_badge_label command without any pre-configured scope.","commands":{"allow":["set_badge_label"],"deny":[]}},"allow-set-closable":{"identifier":"allow-set-closable","description":"Enables the set_closable command without any pre-configured scope.","commands":{"allow":["set_closable"],"deny":[]}},"allow-set-content-protected":{"identifier":"allow-set-content-protected","description":"Enables the set_content_protected command without any pre-configured scope.","commands":{"allow":["set_content_protected"],"deny":[]}},"allow-set-cursor-grab":{"identifier":"allow-set-cursor-grab","description":"Enables the set_cursor_grab command without any pre-configured scope.","commands":{"allow":["set_cursor_grab"],"deny":[]}},"allow-set-cursor-icon":{"identifier":"allow-set-cursor-icon","description":"Enables the set_cursor_icon command without any pre-configured scope.","commands":{"allow":["set_cursor_icon"],"deny":[]}},"allow-set-cursor-position":{"identifier":"allow-set-cursor-position","description":"Enables the set_cursor_position command without any pre-configured scope.","commands":{"allow":["set_cursor_position"],"deny":[]}},"allow-set-cursor-visible":{"identifier":"allow-set-cursor-visible","description":"Enables the set_cursor_visible command without any pre-configured scope.","commands":{"allow":["set_cursor_visible"],"deny":[]}},"allow-set-decorations":{"identifier":"allow-set-decorations","description":"Enables the set_decorations command without any pre-configured scope.","commands":{"allow":["set_decorations"],"deny":[]}},"allow-set-effects":{"identifier":"allow-set-effects","description":"Enables the set_effects command without any pre-configured scope.","commands":{"allow":["set_effects"],"deny":[]}},"allow-set-enabled":{"identifier":"allow-set-enabled","description":"Enables the set_enabled command without any pre-configured scope.","commands":{"allow":["set_enabled"],"deny":[]}},"allow-set-focus":{"identifier":"allow-set-focus","description":"Enables the set_focus command without any pre-configured scope.","commands":{"allow":["set_focus"],"deny":[]}},"allow-set-focusable":{"identifier":"allow-set-focusable","description":"Enables the set_focusable command without any pre-configured scope.","commands":{"allow":["set_focusable"],"deny":[]}},"allow-set-fullscreen":{"identifier":"allow-set-fullscreen","description":"Enables the set_fullscreen command without any pre-configured scope.","commands":{"allow":["set_fullscreen"],"deny":[]}},"allow-set-icon":{"identifier":"allow-set-icon","description":"Enables the set_icon command without any pre-configured scope.","commands":{"allow":["set_icon"],"deny":[]}},"allow-set-ignore-cursor-events":{"identifier":"allow-set-ignore-cursor-events","description":"Enables the set_ignore_cursor_events command without any pre-configured scope.","commands":{"allow":["set_ignore_cursor_events"],"deny":[]}},"allow-set-max-size":{"identifier":"allow-set-max-size","description":"Enables the set_max_size command without any pre-configured scope.","commands":{"allow":["set_max_size"],"deny":[]}},"allow-set-maximizable":{"identifier":"allow-set-maximizable","description":"Enables the set_maximizable command without any pre-configured scope.","commands":{"allow":["set_maximizable"],"deny":[]}},"allow-set-min-size":{"identifier":"allow-set-min-size","description":"Enables the set_min_size command without any pre-configured scope.","commands":{"allow":["set_min_size"],"deny":[]}},"allow-set-minimizable":{"identifier":"allow-set-minimizable","description":"Enables the set_minimizable command without any pre-configured scope.","commands":{"allow":["set_minimizable"],"deny":[]}},"allow-set-overlay-icon":{"identifier":"allow-set-overlay-icon","description":"Enables the set_overlay_icon command without any pre-configured scope.","commands":{"allow":["set_overlay_icon"],"deny":[]}},"allow-set-position":{"identifier":"allow-set-position","description":"Enables the set_position command without any pre-configured scope.","commands":{"allow":["set_position"],"deny":[]}},"allow-set-progress-bar":{"identifier":"allow-set-progress-bar","description":"Enables the set_progress_bar command without any pre-configured scope.","commands":{"allow":["set_progress_bar"],"deny":[]}},"allow-set-resizable":{"identifier":"allow-set-resizable","description":"Enables the set_resizable command without any pre-configured scope.","commands":{"allow":["set_resizable"],"deny":[]}},"allow-set-shadow":{"identifier":"allow-set-shadow","description":"Enables the set_shadow command without any pre-configured scope.","commands":{"allow":["set_shadow"],"deny":[]}},"allow-set-simple-fullscreen":{"identifier":"allow-set-simple-fullscreen","description":"Enables the set_simple_fullscreen command without any pre-configured scope.","commands":{"allow":["set_simple_fullscreen"],"deny":[]}},"allow-set-size":{"identifier":"allow-set-size","description":"Enables the set_size command without any pre-configured scope.","commands":{"allow":["set_size"],"deny":[]}},"allow-set-size-constraints":{"identifier":"allow-set-size-constraints","description":"Enables the set_size_constraints command without any pre-configured scope.","commands":{"allow":["set_size_constraints"],"deny":[]}},"allow-set-skip-taskbar":{"identifier":"allow-set-skip-taskbar","description":"Enables the set_skip_taskbar command without any pre-configured scope.","commands":{"allow":["set_skip_taskbar"],"deny":[]}},"allow-set-theme":{"identifier":"allow-set-theme","description":"Enables the set_theme command without any pre-configured scope.","commands":{"allow":["set_theme"],"deny":[]}},"allow-set-title":{"identifier":"allow-set-title","description":"Enables the set_title command without any pre-configured scope.","commands":{"allow":["set_title"],"deny":[]}},"allow-set-title-bar-style":{"identifier":"allow-set-title-bar-style","description":"Enables the set_title_bar_style command without any pre-configured scope.","commands":{"allow":["set_title_bar_style"],"deny":[]}},"allow-set-visible-on-all-workspaces":{"identifier":"allow-set-visible-on-all-workspaces","description":"Enables the set_visible_on_all_workspaces command without any pre-configured scope.","commands":{"allow":["set_visible_on_all_workspaces"],"deny":[]}},"allow-show":{"identifier":"allow-show","description":"Enables the show command without any pre-configured scope.","commands":{"allow":["show"],"deny":[]}},"allow-start-dragging":{"identifier":"allow-start-dragging","description":"Enables the start_dragging command without any pre-configured scope.","commands":{"allow":["start_dragging"],"deny":[]}},"allow-start-resize-dragging":{"identifier":"allow-start-resize-dragging","description":"Enables the start_resize_dragging command without any pre-configured scope.","commands":{"allow":["start_resize_dragging"],"deny":[]}},"allow-theme":{"identifier":"allow-theme","description":"Enables the theme command without any pre-configured scope.","commands":{"allow":["theme"],"deny":[]}},"allow-title":{"identifier":"allow-title","description":"Enables the title command without any pre-configured scope.","commands":{"allow":["title"],"deny":[]}},"allow-toggle-maximize":{"identifier":"allow-toggle-maximize","description":"Enables the toggle_maximize command without any pre-configured scope.","commands":{"allow":["toggle_maximize"],"deny":[]}},"allow-unmaximize":{"identifier":"allow-unmaximize","description":"Enables the unmaximize command without any pre-configured scope.","commands":{"allow":["unmaximize"],"deny":[]}},"allow-unminimize":{"identifier":"allow-unminimize","description":"Enables the unminimize command without any pre-configured scope.","commands":{"allow":["unminimize"],"deny":[]}},"deny-activity-name":{"identifier":"deny-activity-name","description":"Denies the activity_name command without any pre-configured scope.","commands":{"allow":[],"deny":["activity_name"]}},"deny-available-monitors":{"identifier":"deny-available-monitors","description":"Denies the available_monitors command without any pre-configured scope.","commands":{"allow":[],"deny":["available_monitors"]}},"deny-center":{"identifier":"deny-center","description":"Denies the center command without any pre-configured scope.","commands":{"allow":[],"deny":["center"]}},"deny-close":{"identifier":"deny-close","description":"Denies the close command without any pre-configured scope.","commands":{"allow":[],"deny":["close"]}},"deny-create":{"identifier":"deny-create","description":"Denies the create command without any pre-configured scope.","commands":{"allow":[],"deny":["create"]}},"deny-current-monitor":{"identifier":"deny-current-monitor","description":"Denies the current_monitor command without any pre-configured scope.","commands":{"allow":[],"deny":["current_monitor"]}},"deny-cursor-position":{"identifier":"deny-cursor-position","description":"Denies the cursor_position command without any pre-configured scope.","commands":{"allow":[],"deny":["cursor_position"]}},"deny-destroy":{"identifier":"deny-destroy","description":"Denies the destroy command without any pre-configured scope.","commands":{"allow":[],"deny":["destroy"]}},"deny-get-all-windows":{"identifier":"deny-get-all-windows","description":"Denies the get_all_windows command without any pre-configured scope.","commands":{"allow":[],"deny":["get_all_windows"]}},"deny-hide":{"identifier":"deny-hide","description":"Denies the hide command without any pre-configured scope.","commands":{"allow":[],"deny":["hide"]}},"deny-inner-position":{"identifier":"deny-inner-position","description":"Denies the inner_position command without any pre-configured scope.","commands":{"allow":[],"deny":["inner_position"]}},"deny-inner-size":{"identifier":"deny-inner-size","description":"Denies the inner_size command without any pre-configured scope.","commands":{"allow":[],"deny":["inner_size"]}},"deny-internal-toggle-maximize":{"identifier":"deny-internal-toggle-maximize","description":"Denies the internal_toggle_maximize command without any pre-configured scope.","commands":{"allow":[],"deny":["internal_toggle_maximize"]}},"deny-is-always-on-top":{"identifier":"deny-is-always-on-top","description":"Denies the is_always_on_top command without any pre-configured scope.","commands":{"allow":[],"deny":["is_always_on_top"]}},"deny-is-closable":{"identifier":"deny-is-closable","description":"Denies the is_closable command without any pre-configured scope.","commands":{"allow":[],"deny":["is_closable"]}},"deny-is-decorated":{"identifier":"deny-is-decorated","description":"Denies the is_decorated command without any pre-configured scope.","commands":{"allow":[],"deny":["is_decorated"]}},"deny-is-enabled":{"identifier":"deny-is-enabled","description":"Denies the is_enabled command without any pre-configured scope.","commands":{"allow":[],"deny":["is_enabled"]}},"deny-is-focused":{"identifier":"deny-is-focused","description":"Denies the is_focused command without any pre-configured scope.","commands":{"allow":[],"deny":["is_focused"]}},"deny-is-fullscreen":{"identifier":"deny-is-fullscreen","description":"Denies the is_fullscreen command without any pre-configured scope.","commands":{"allow":[],"deny":["is_fullscreen"]}},"deny-is-maximizable":{"identifier":"deny-is-maximizable","description":"Denies the is_maximizable command without any pre-configured scope.","commands":{"allow":[],"deny":["is_maximizable"]}},"deny-is-maximized":{"identifier":"deny-is-maximized","description":"Denies the is_maximized command without any pre-configured scope.","commands":{"allow":[],"deny":["is_maximized"]}},"deny-is-minimizable":{"identifier":"deny-is-minimizable","description":"Denies the is_minimizable command without any pre-configured scope.","commands":{"allow":[],"deny":["is_minimizable"]}},"deny-is-minimized":{"identifier":"deny-is-minimized","description":"Denies the is_minimized command without any pre-configured scope.","commands":{"allow":[],"deny":["is_minimized"]}},"deny-is-resizable":{"identifier":"deny-is-resizable","description":"Denies the is_resizable command without any pre-configured scope.","commands":{"allow":[],"deny":["is_resizable"]}},"deny-is-visible":{"identifier":"deny-is-visible","description":"Denies the is_visible command without any pre-configured scope.","commands":{"allow":[],"deny":["is_visible"]}},"deny-maximize":{"identifier":"deny-maximize","description":"Denies the maximize command without any pre-configured scope.","commands":{"allow":[],"deny":["maximize"]}},"deny-minimize":{"identifier":"deny-minimize","description":"Denies the minimize command without any pre-configured scope.","commands":{"allow":[],"deny":["minimize"]}},"deny-monitor-from-point":{"identifier":"deny-monitor-from-point","description":"Denies the monitor_from_point command without any pre-configured scope.","commands":{"allow":[],"deny":["monitor_from_point"]}},"deny-outer-position":{"identifier":"deny-outer-position","description":"Denies the outer_position command without any pre-configured scope.","commands":{"allow":[],"deny":["outer_position"]}},"deny-outer-size":{"identifier":"deny-outer-size","description":"Denies the outer_size command without any pre-configured scope.","commands":{"allow":[],"deny":["outer_size"]}},"deny-primary-monitor":{"identifier":"deny-primary-monitor","description":"Denies the primary_monitor command without any pre-configured scope.","commands":{"allow":[],"deny":["primary_monitor"]}},"deny-request-user-attention":{"identifier":"deny-request-user-attention","description":"Denies the request_user_attention command without any pre-configured scope.","commands":{"allow":[],"deny":["request_user_attention"]}},"deny-scale-factor":{"identifier":"deny-scale-factor","description":"Denies the scale_factor command without any pre-configured scope.","commands":{"allow":[],"deny":["scale_factor"]}},"deny-scene-identifier":{"identifier":"deny-scene-identifier","description":"Denies the scene_identifier command without any pre-configured scope.","commands":{"allow":[],"deny":["scene_identifier"]}},"deny-set-always-on-bottom":{"identifier":"deny-set-always-on-bottom","description":"Denies the set_always_on_bottom command without any pre-configured scope.","commands":{"allow":[],"deny":["set_always_on_bottom"]}},"deny-set-always-on-top":{"identifier":"deny-set-always-on-top","description":"Denies the set_always_on_top command without any pre-configured scope.","commands":{"allow":[],"deny":["set_always_on_top"]}},"deny-set-background-color":{"identifier":"deny-set-background-color","description":"Denies the set_background_color command without any pre-configured scope.","commands":{"allow":[],"deny":["set_background_color"]}},"deny-set-badge-count":{"identifier":"deny-set-badge-count","description":"Denies the set_badge_count command without any pre-configured scope.","commands":{"allow":[],"deny":["set_badge_count"]}},"deny-set-badge-label":{"identifier":"deny-set-badge-label","description":"Denies the set_badge_label command without any pre-configured scope.","commands":{"allow":[],"deny":["set_badge_label"]}},"deny-set-closable":{"identifier":"deny-set-closable","description":"Denies the set_closable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_closable"]}},"deny-set-content-protected":{"identifier":"deny-set-content-protected","description":"Denies the set_content_protected command without any pre-configured scope.","commands":{"allow":[],"deny":["set_content_protected"]}},"deny-set-cursor-grab":{"identifier":"deny-set-cursor-grab","description":"Denies the set_cursor_grab command without any pre-configured scope.","commands":{"allow":[],"deny":["set_cursor_grab"]}},"deny-set-cursor-icon":{"identifier":"deny-set-cursor-icon","description":"Denies the set_cursor_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_cursor_icon"]}},"deny-set-cursor-position":{"identifier":"deny-set-cursor-position","description":"Denies the set_cursor_position command without any pre-configured scope.","commands":{"allow":[],"deny":["set_cursor_position"]}},"deny-set-cursor-visible":{"identifier":"deny-set-cursor-visible","description":"Denies the set_cursor_visible command without any pre-configured scope.","commands":{"allow":[],"deny":["set_cursor_visible"]}},"deny-set-decorations":{"identifier":"deny-set-decorations","description":"Denies the set_decorations command without any pre-configured scope.","commands":{"allow":[],"deny":["set_decorations"]}},"deny-set-effects":{"identifier":"deny-set-effects","description":"Denies the set_effects command without any pre-configured scope.","commands":{"allow":[],"deny":["set_effects"]}},"deny-set-enabled":{"identifier":"deny-set-enabled","description":"Denies the set_enabled command without any pre-configured scope.","commands":{"allow":[],"deny":["set_enabled"]}},"deny-set-focus":{"identifier":"deny-set-focus","description":"Denies the set_focus command without any pre-configured scope.","commands":{"allow":[],"deny":["set_focus"]}},"deny-set-focusable":{"identifier":"deny-set-focusable","description":"Denies the set_focusable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_focusable"]}},"deny-set-fullscreen":{"identifier":"deny-set-fullscreen","description":"Denies the set_fullscreen command without any pre-configured scope.","commands":{"allow":[],"deny":["set_fullscreen"]}},"deny-set-icon":{"identifier":"deny-set-icon","description":"Denies the set_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_icon"]}},"deny-set-ignore-cursor-events":{"identifier":"deny-set-ignore-cursor-events","description":"Denies the set_ignore_cursor_events command without any pre-configured scope.","commands":{"allow":[],"deny":["set_ignore_cursor_events"]}},"deny-set-max-size":{"identifier":"deny-set-max-size","description":"Denies the set_max_size command without any pre-configured scope.","commands":{"allow":[],"deny":["set_max_size"]}},"deny-set-maximizable":{"identifier":"deny-set-maximizable","description":"Denies the set_maximizable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_maximizable"]}},"deny-set-min-size":{"identifier":"deny-set-min-size","description":"Denies the set_min_size command without any pre-configured scope.","commands":{"allow":[],"deny":["set_min_size"]}},"deny-set-minimizable":{"identifier":"deny-set-minimizable","description":"Denies the set_minimizable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_minimizable"]}},"deny-set-overlay-icon":{"identifier":"deny-set-overlay-icon","description":"Denies the set_overlay_icon command without any pre-configured scope.","commands":{"allow":[],"deny":["set_overlay_icon"]}},"deny-set-position":{"identifier":"deny-set-position","description":"Denies the set_position command without any pre-configured scope.","commands":{"allow":[],"deny":["set_position"]}},"deny-set-progress-bar":{"identifier":"deny-set-progress-bar","description":"Denies the set_progress_bar command without any pre-configured scope.","commands":{"allow":[],"deny":["set_progress_bar"]}},"deny-set-resizable":{"identifier":"deny-set-resizable","description":"Denies the set_resizable command without any pre-configured scope.","commands":{"allow":[],"deny":["set_resizable"]}},"deny-set-shadow":{"identifier":"deny-set-shadow","description":"Denies the set_shadow command without any pre-configured scope.","commands":{"allow":[],"deny":["set_shadow"]}},"deny-set-simple-fullscreen":{"identifier":"deny-set-simple-fullscreen","description":"Denies the set_simple_fullscreen command without any pre-configured scope.","commands":{"allow":[],"deny":["set_simple_fullscreen"]}},"deny-set-size":{"identifier":"deny-set-size","description":"Denies the set_size command without any pre-configured scope.","commands":{"allow":[],"deny":["set_size"]}},"deny-set-size-constraints":{"identifier":"deny-set-size-constraints","description":"Denies the set_size_constraints command without any pre-configured scope.","commands":{"allow":[],"deny":["set_size_constraints"]}},"deny-set-skip-taskbar":{"identifier":"deny-set-skip-taskbar","description":"Denies the set_skip_taskbar command without any pre-configured scope.","commands":{"allow":[],"deny":["set_skip_taskbar"]}},"deny-set-theme":{"identifier":"deny-set-theme","description":"Denies the set_theme command without any pre-configured scope.","commands":{"allow":[],"deny":["set_theme"]}},"deny-set-title":{"identifier":"deny-set-title","description":"Denies the set_title command without any pre-configured scope.","commands":{"allow":[],"deny":["set_title"]}},"deny-set-title-bar-style":{"identifier":"deny-set-title-bar-style","description":"Denies the set_title_bar_style command without any pre-configured scope.","commands":{"allow":[],"deny":["set_title_bar_style"]}},"deny-set-visible-on-all-workspaces":{"identifier":"deny-set-visible-on-all-workspaces","description":"Denies the set_visible_on_all_workspaces command without any pre-configured scope.","commands":{"allow":[],"deny":["set_visible_on_all_workspaces"]}},"deny-show":{"identifier":"deny-show","description":"Denies the show command without any pre-configured scope.","commands":{"allow":[],"deny":["show"]}},"deny-start-dragging":{"identifier":"deny-start-dragging","description":"Denies the start_dragging command without any pre-configured scope.","commands":{"allow":[],"deny":["start_dragging"]}},"deny-start-resize-dragging":{"identifier":"deny-start-resize-dragging","description":"Denies the start_resize_dragging command without any pre-configured scope.","commands":{"allow":[],"deny":["start_resize_dragging"]}},"deny-theme":{"identifier":"deny-theme","description":"Denies the theme command without any pre-configured scope.","commands":{"allow":[],"deny":["theme"]}},"deny-title":{"identifier":"deny-title","description":"Denies the title command without any pre-configured scope.","commands":{"allow":[],"deny":["title"]}},"deny-toggle-maximize":{"identifier":"deny-toggle-maximize","description":"Denies the toggle_maximize command without any pre-configured scope.","commands":{"allow":[],"deny":["toggle_maximize"]}},"deny-unmaximize":{"identifier":"deny-unmaximize","description":"Denies the unmaximize command without any pre-configured scope.","commands":{"allow":[],"deny":["unmaximize"]}},"deny-unminimize":{"identifier":"deny-unminimize","description":"Denies the unminimize command without any pre-configured scope.","commands":{"allow":[],"deny":["unminimize"]}}},"permission_sets":{},"global_scope_schema":null},"deep-link":{"default_permission":{"identifier":"default","description":"Allows reading the opened deep link via the get_current command","permissions":["allow-get-current"]},"permissions":{"allow-get-current":{"identifier":"allow-get-current","description":"Enables the get_current command without any pre-configured scope.","commands":{"allow":["get_current"],"deny":[]}},"allow-is-registered":{"identifier":"allow-is-registered","description":"Enables the is_registered command without any pre-configured scope.","commands":{"allow":["is_registered"],"deny":[]}},"allow-register":{"identifier":"allow-register","description":"Enables the register command without any pre-configured scope.","commands":{"allow":["register"],"deny":[]}},"allow-unregister":{"identifier":"allow-unregister","description":"Enables the unregister command without any pre-configured scope.","commands":{"allow":["unregister"],"deny":[]}},"deny-get-current":{"identifier":"deny-get-current","description":"Denies the get_current command without any pre-configured scope.","commands":{"allow":[],"deny":["get_current"]}},"deny-is-registered":{"identifier":"deny-is-registered","description":"Denies the is_registered command without any pre-configured scope.","commands":{"allow":[],"deny":["is_registered"]}},"deny-register":{"identifier":"deny-register","description":"Denies the register command without any pre-configured scope.","commands":{"allow":[],"deny":["register"]}},"deny-unregister":{"identifier":"deny-unregister","description":"Denies the unregister command without any pre-configured scope.","commands":{"allow":[],"deny":["unregister"]}}},"permission_sets":{},"global_scope_schema":null},"dialog":{"default_permission":{"identifier":"default","description":"This permission set configures the types of dialogs\navailable from the dialog plugin.\n\n#### Granted Permissions\n\nAll dialog types are enabled.\n\n\n","permissions":["allow-message","allow-save","allow-open"]},"permissions":{"allow-ask":{"identifier":"allow-ask","description":"Enables the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)","commands":{"allow":["message"],"deny":[]}},"allow-confirm":{"identifier":"allow-confirm","description":"Enables the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `allow-message` and will be removed in v3)","commands":{"allow":["message"],"deny":[]}},"allow-message":{"identifier":"allow-message","description":"Enables the message command without any pre-configured scope.","commands":{"allow":["message"],"deny":[]}},"allow-open":{"identifier":"allow-open","description":"Enables the open command without any pre-configured scope.","commands":{"allow":["open"],"deny":[]}},"allow-save":{"identifier":"allow-save","description":"Enables the save command without any pre-configured scope.","commands":{"allow":["save"],"deny":[]}},"deny-ask":{"identifier":"deny-ask","description":"Denies the ask command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)","commands":{"allow":[],"deny":["message"]}},"deny-confirm":{"identifier":"deny-confirm","description":"Denies the confirm command without any pre-configured scope. (**DEPRECATED**: This is now an alias to `deny-message` and will be removed in v3)","commands":{"allow":[],"deny":["message"]}},"deny-message":{"identifier":"deny-message","description":"Denies the message command without any pre-configured scope.","commands":{"allow":[],"deny":["message"]}},"deny-open":{"identifier":"deny-open","description":"Denies the open command without any pre-configured scope.","commands":{"allow":[],"deny":["open"]}},"deny-save":{"identifier":"deny-save","description":"Denies the save command without any pre-configured scope.","commands":{"allow":[],"deny":["save"]}}},"permission_sets":{},"global_scope_schema":null},"global-shortcut":{"default_permission":{"identifier":"default","description":"No features are enabled by default, as we believe\nthe shortcuts can be inherently dangerous and it is\napplication specific if specific shortcuts should be\nregistered or unregistered.\n","permissions":[]},"permissions":{"allow-is-registered":{"identifier":"allow-is-registered","description":"Enables the is_registered command without any pre-configured scope.","commands":{"allow":["is_registered"],"deny":[]}},"allow-register":{"identifier":"allow-register","description":"Enables the register command without any pre-configured scope.","commands":{"allow":["register"],"deny":[]}},"allow-register-all":{"identifier":"allow-register-all","description":"Enables the register_all command without any pre-configured scope.","commands":{"allow":["register_all"],"deny":[]}},"allow-unregister":{"identifier":"allow-unregister","description":"Enables the unregister command without any pre-configured scope.","commands":{"allow":["unregister"],"deny":[]}},"allow-unregister-all":{"identifier":"allow-unregister-all","description":"Enables the unregister_all command without any pre-configured scope.","commands":{"allow":["unregister_all"],"deny":[]}},"deny-is-registered":{"identifier":"deny-is-registered","description":"Denies the is_registered command without any pre-configured scope.","commands":{"allow":[],"deny":["is_registered"]}},"deny-register":{"identifier":"deny-register","description":"Denies the register command without any pre-configured scope.","commands":{"allow":[],"deny":["register"]}},"deny-register-all":{"identifier":"deny-register-all","description":"Denies the register_all command without any pre-configured scope.","commands":{"allow":[],"deny":["register_all"]}},"deny-unregister":{"identifier":"deny-unregister","description":"Denies the unregister command without any pre-configured scope.","commands":{"allow":[],"deny":["unregister"]}},"deny-unregister-all":{"identifier":"deny-unregister-all","description":"Denies the unregister_all command without any pre-configured scope.","commands":{"allow":[],"deny":["unregister_all"]}}},"permission_sets":{},"global_scope_schema":null},"log":{"default_permission":{"identifier":"default","description":"Allows the log command","permissions":["allow-log"]},"permissions":{"allow-log":{"identifier":"allow-log","description":"Enables the log command without any pre-configured scope.","commands":{"allow":["log"],"deny":[]}},"deny-log":{"identifier":"deny-log","description":"Denies the log command without any pre-configured scope.","commands":{"allow":[],"deny":["log"]}}},"permission_sets":{},"global_scope_schema":null},"notification":{"default_permission":{"identifier":"default","description":"This permission set configures which\nnotification features are by default exposed.\n\n#### Granted Permissions\n\nIt allows all notification related features.\n\n","permissions":["allow-is-permission-granted","allow-request-permission","allow-notify","allow-register-action-types","allow-register-listener","allow-cancel","allow-get-pending","allow-remove-active","allow-get-active","allow-check-permissions","allow-show","allow-batch","allow-list-channels","allow-delete-channel","allow-create-channel","allow-permission-state"]},"permissions":{"allow-batch":{"identifier":"allow-batch","description":"Enables the batch command without any pre-configured scope.","commands":{"allow":["batch"],"deny":[]}},"allow-cancel":{"identifier":"allow-cancel","description":"Enables the cancel command without any pre-configured scope.","commands":{"allow":["cancel"],"deny":[]}},"allow-check-permissions":{"identifier":"allow-check-permissions","description":"Enables the check_permissions command without any pre-configured scope.","commands":{"allow":["check_permissions"],"deny":[]}},"allow-create-channel":{"identifier":"allow-create-channel","description":"Enables the create_channel command without any pre-configured scope.","commands":{"allow":["create_channel"],"deny":[]}},"allow-delete-channel":{"identifier":"allow-delete-channel","description":"Enables the delete_channel command without any pre-configured scope.","commands":{"allow":["delete_channel"],"deny":[]}},"allow-get-active":{"identifier":"allow-get-active","description":"Enables the get_active command without any pre-configured scope.","commands":{"allow":["get_active"],"deny":[]}},"allow-get-pending":{"identifier":"allow-get-pending","description":"Enables the get_pending command without any pre-configured scope.","commands":{"allow":["get_pending"],"deny":[]}},"allow-is-permission-granted":{"identifier":"allow-is-permission-granted","description":"Enables the is_permission_granted command without any pre-configured scope.","commands":{"allow":["is_permission_granted"],"deny":[]}},"allow-list-channels":{"identifier":"allow-list-channels","description":"Enables the list_channels command without any pre-configured scope.","commands":{"allow":["list_channels"],"deny":[]}},"allow-notify":{"identifier":"allow-notify","description":"Enables the notify command without any pre-configured scope.","commands":{"allow":["notify"],"deny":[]}},"allow-permission-state":{"identifier":"allow-permission-state","description":"Enables the permission_state command without any pre-configured scope.","commands":{"allow":["permission_state"],"deny":[]}},"allow-register-action-types":{"identifier":"allow-register-action-types","description":"Enables the register_action_types command without any pre-configured scope.","commands":{"allow":["register_action_types"],"deny":[]}},"allow-register-listener":{"identifier":"allow-register-listener","description":"Enables the register_listener command without any pre-configured scope.","commands":{"allow":["register_listener"],"deny":[]}},"allow-remove-active":{"identifier":"allow-remove-active","description":"Enables the remove_active command without any pre-configured scope.","commands":{"allow":["remove_active"],"deny":[]}},"allow-request-permission":{"identifier":"allow-request-permission","description":"Enables the request_permission command without any pre-configured scope.","commands":{"allow":["request_permission"],"deny":[]}},"allow-show":{"identifier":"allow-show","description":"Enables the show command without any pre-configured scope.","commands":{"allow":["show"],"deny":[]}},"deny-batch":{"identifier":"deny-batch","description":"Denies the batch command without any pre-configured scope.","commands":{"allow":[],"deny":["batch"]}},"deny-cancel":{"identifier":"deny-cancel","description":"Denies the cancel command without any pre-configured scope.","commands":{"allow":[],"deny":["cancel"]}},"deny-check-permissions":{"identifier":"deny-check-permissions","description":"Denies the check_permissions command without any pre-configured scope.","commands":{"allow":[],"deny":["check_permissions"]}},"deny-create-channel":{"identifier":"deny-create-channel","description":"Denies the create_channel command without any pre-configured scope.","commands":{"allow":[],"deny":["create_channel"]}},"deny-delete-channel":{"identifier":"deny-delete-channel","description":"Denies the delete_channel command without any pre-configured scope.","commands":{"allow":[],"deny":["delete_channel"]}},"deny-get-active":{"identifier":"deny-get-active","description":"Denies the get_active command without any pre-configured scope.","commands":{"allow":[],"deny":["get_active"]}},"deny-get-pending":{"identifier":"deny-get-pending","description":"Denies the get_pending command without any pre-configured scope.","commands":{"allow":[],"deny":["get_pending"]}},"deny-is-permission-granted":{"identifier":"deny-is-permission-granted","description":"Denies the is_permission_granted command without any pre-configured scope.","commands":{"allow":[],"deny":["is_permission_granted"]}},"deny-list-channels":{"identifier":"deny-list-channels","description":"Denies the list_channels command without any pre-configured scope.","commands":{"allow":[],"deny":["list_channels"]}},"deny-notify":{"identifier":"deny-notify","description":"Denies the notify command without any pre-configured scope.","commands":{"allow":[],"deny":["notify"]}},"deny-permission-state":{"identifier":"deny-permission-state","description":"Denies the permission_state command without any pre-configured scope.","commands":{"allow":[],"deny":["permission_state"]}},"deny-register-action-types":{"identifier":"deny-register-action-types","description":"Denies the register_action_types command without any pre-configured scope.","commands":{"allow":[],"deny":["register_action_types"]}},"deny-register-listener":{"identifier":"deny-register-listener","description":"Denies the register_listener command without any pre-configured scope.","commands":{"allow":[],"deny":["register_listener"]}},"deny-remove-active":{"identifier":"deny-remove-active","description":"Denies the remove_active command without any pre-configured scope.","commands":{"allow":[],"deny":["remove_active"]}},"deny-request-permission":{"identifier":"deny-request-permission","description":"Denies the request_permission command without any pre-configured scope.","commands":{"allow":[],"deny":["request_permission"]}},"deny-show":{"identifier":"deny-show","description":"Denies the show command without any pre-configured scope.","commands":{"allow":[],"deny":["show"]}}},"permission_sets":{},"global_scope_schema":null},"opener":{"default_permission":{"identifier":"default","description":"This permission set allows opening `mailto:`, `tel:`, `https://` and `http://` urls using their default application\nas well as reveal file in directories using default file explorer","permissions":["allow-open-url","allow-reveal-item-in-dir","allow-default-urls"]},"permissions":{"allow-default-urls":{"identifier":"allow-default-urls","description":"This enables opening `mailto:`, `tel:`, `https://` and `http://` urls using their default application.","commands":{"allow":[],"deny":[]},"scope":{"allow":[{"url":"mailto:*"},{"url":"tel:*"},{"url":"http://*"},{"url":"https://*"}]}},"allow-open-path":{"identifier":"allow-open-path","description":"Enables the open_path command without any pre-configured scope.","commands":{"allow":["open_path"],"deny":[]}},"allow-open-url":{"identifier":"allow-open-url","description":"Enables the open_url command without any pre-configured scope.","commands":{"allow":["open_url"],"deny":[]}},"allow-reveal-item-in-dir":{"identifier":"allow-reveal-item-in-dir","description":"Enables the reveal_item_in_dir command without any pre-configured scope.","commands":{"allow":["reveal_item_in_dir"],"deny":[]}},"deny-open-path":{"identifier":"deny-open-path","description":"Denies the open_path command without any pre-configured scope.","commands":{"allow":[],"deny":["open_path"]}},"deny-open-url":{"identifier":"deny-open-url","description":"Denies the open_url command without any pre-configured scope.","commands":{"allow":[],"deny":["open_url"]}},"deny-reveal-item-in-dir":{"identifier":"deny-reveal-item-in-dir","description":"Denies the reveal_item_in_dir command without any pre-configured scope.","commands":{"allow":[],"deny":["reveal_item_in_dir"]}}},"permission_sets":{},"global_scope_schema":{"$schema":"http://json-schema.org/draft-07/schema#","anyOf":[{"properties":{"app":{"allOf":[{"$ref":"#/definitions/Application"}],"description":"An application to open this url with, for example: firefox."},"url":{"description":"A URL that can be opened by the webview when using the Opener APIs.\n\nWildcards can be used following the UNIX glob pattern.\n\nExamples:\n\n- \"https://*\" : allows all HTTPS origin\n\n- \"https://*.github.com/tauri-apps/tauri\": allows any subdomain of \"github.com\" with the \"tauri-apps/api\" path\n\n- \"https://myapi.service.com/users/*\": allows access to any URLs that begins with \"https://myapi.service.com/users/\"","type":"string"}},"required":["url"],"type":"object"},{"properties":{"app":{"allOf":[{"$ref":"#/definitions/Application"}],"description":"An application to open this path with, for example: xdg-open."},"path":{"description":"A path that can be opened by the webview when using the Opener APIs.\n\nThe pattern can start with a variable that resolves to a system base directory. The variables are: `$AUDIO`, `$CACHE`, `$CONFIG`, `$DATA`, `$LOCALDATA`, `$DESKTOP`, `$DOCUMENT`, `$DOWNLOAD`, `$EXE`, `$FONT`, `$HOME`, `$PICTURE`, `$PUBLIC`, `$RUNTIME`, `$TEMPLATE`, `$VIDEO`, `$RESOURCE`, `$APP`, `$LOG`, `$TEMP`, `$APPCONFIG`, `$APPDATA`, `$APPLOCALDATA`, `$APPCACHE`, `$APPLOG`.","type":"string"}},"required":["path"],"type":"object"}],"definitions":{"Application":{"anyOf":[{"description":"Open in default application.","type":"null"},{"description":"If true, allow open with any application.","type":"boolean"},{"description":"Allow specific application to open with.","type":"string"}],"description":"Opener scope application."}},"description":"Opener scope entry.","title":"OpenerScopeEntry"}},"process":{"default_permission":{"identifier":"default","description":"This permission set configures which\nprocess features are by default exposed.\n\n#### Granted Permissions\n\nThis enables to quit via `allow-exit` and restart via `allow-restart`\nthe application.\n","permissions":["allow-exit","allow-restart"]},"permissions":{"allow-exit":{"identifier":"allow-exit","description":"Enables the exit command without any pre-configured scope.","commands":{"allow":["exit"],"deny":[]}},"allow-restart":{"identifier":"allow-restart","description":"Enables the restart command without any pre-configured scope.","commands":{"allow":["restart"],"deny":[]}},"deny-exit":{"identifier":"deny-exit","description":"Denies the exit command without any pre-configured scope.","commands":{"allow":[],"deny":["exit"]}},"deny-restart":{"identifier":"deny-restart","description":"Denies the restart command without any pre-configured scope.","commands":{"allow":[],"deny":["restart"]}}},"permission_sets":{},"global_scope_schema":null},"shell":{"default_permission":{"identifier":"default","description":"This permission set configures which\nshell functionality is exposed by default.\n\n#### Granted Permissions\n\nIt allows to use the `open` functionality with a reasonable\nscope pre-configured. It will allow opening `http(s)://`,\n`tel:` and `mailto:` links.\n","permissions":["allow-open"]},"permissions":{"allow-execute":{"identifier":"allow-execute","description":"Enables the execute command without any pre-configured scope.","commands":{"allow":["execute"],"deny":[]}},"allow-kill":{"identifier":"allow-kill","description":"Enables the kill command without any pre-configured scope.","commands":{"allow":["kill"],"deny":[]}},"allow-open":{"identifier":"allow-open","description":"Enables the open command without any pre-configured scope.","commands":{"allow":["open"],"deny":[]}},"allow-spawn":{"identifier":"allow-spawn","description":"Enables the spawn command without any pre-configured scope.","commands":{"allow":["spawn"],"deny":[]}},"allow-stdin-write":{"identifier":"allow-stdin-write","description":"Enables the stdin_write command without any pre-configured scope.","commands":{"allow":["stdin_write"],"deny":[]}},"deny-execute":{"identifier":"deny-execute","description":"Denies the execute command without any pre-configured scope.","commands":{"allow":[],"deny":["execute"]}},"deny-kill":{"identifier":"deny-kill","description":"Denies the kill command without any pre-configured scope.","commands":{"allow":[],"deny":["kill"]}},"deny-open":{"identifier":"deny-open","description":"Denies the open command without any pre-configured scope.","commands":{"allow":[],"deny":["open"]}},"deny-spawn":{"identifier":"deny-spawn","description":"Denies the spawn command without any pre-configured scope.","commands":{"allow":[],"deny":["spawn"]}},"deny-stdin-write":{"identifier":"deny-stdin-write","description":"Denies the stdin_write command without any pre-configured scope.","commands":{"allow":[],"deny":["stdin_write"]}}},"permission_sets":{},"global_scope_schema":{"$schema":"http://json-schema.org/draft-07/schema#","anyOf":[{"additionalProperties":false,"properties":{"args":{"allOf":[{"$ref":"#/definitions/ShellScopeEntryAllowedArgs"}],"description":"The allowed arguments for the command execution."},"cmd":{"description":"The command name. It can start with a variable that resolves to a system base directory. The variables are: `$AUDIO`, `$CACHE`, `$CONFIG`, `$DATA`, `$LOCALDATA`, `$DESKTOP`, `$DOCUMENT`, `$DOWNLOAD`, `$EXE`, `$FONT`, `$HOME`, `$PICTURE`, `$PUBLIC`, `$RUNTIME`, `$TEMPLATE`, `$VIDEO`, `$RESOURCE`, `$LOG`, `$TEMP`, `$APPCONFIG`, `$APPDATA`, `$APPLOCALDATA`, `$APPCACHE`, `$APPLOG`.","type":"string"},"name":{"description":"The name for this allowed shell command configuration.\n\nThis name will be used inside of the webview API to call this command along with any specified arguments.","type":"string"}},"required":["cmd","name"],"type":"object"},{"additionalProperties":false,"properties":{"args":{"allOf":[{"$ref":"#/definitions/ShellScopeEntryAllowedArgs"}],"description":"The allowed arguments for the command execution."},"name":{"description":"The name for this allowed shell command configuration.\n\nThis name will be used inside of the webview API to call this command along with any specified arguments.","type":"string"},"sidecar":{"description":"If this command is a sidecar command.","type":"boolean"}},"required":["name","sidecar"],"type":"object"}],"definitions":{"ShellScopeEntryAllowedArg":{"anyOf":[{"description":"A non-configurable argument that is passed to the command in the order it was specified.","type":"string"},{"additionalProperties":false,"description":"A variable that is set while calling the command from the webview API.","properties":{"raw":{"default":false,"description":"Marks the validator as a raw regex, meaning the plugin should not make any modification at runtime.\n\nThis means the regex will not match on the entire string by default, which might be exploited if your regex allow unexpected input to be considered valid. When using this option, make sure your regex is correct.","type":"boolean"},"validator":{"description":"[regex] validator to require passed values to conform to an expected input.\n\nThis will require the argument value passed to this variable to match the `validator` regex before it will be executed.\n\nThe regex string is by default surrounded by `^...$` to match the full string. For example the `https?://\\w+` regex would be registered as `^https?://\\w+$`.\n\n[regex]: <https://docs.rs/regex/latest/regex/#syntax>","type":"string"}},"required":["validator"],"type":"object"}],"description":"A command argument allowed to be executed by the webview API."},"ShellScopeEntryAllowedArgs":{"anyOf":[{"description":"Use a simple boolean to allow all or disable all arguments to this command configuration.","type":"boolean"},{"description":"A specific set of [`ShellScopeEntryAllowedArg`] that are valid to call for the command configuration.","items":{"$ref":"#/definitions/ShellScopeEntryAllowedArg"},"type":"array"}],"description":"A set of command arguments allowed to be executed by the webview API.\n\nA value of `true` will allow any arguments to be passed to the command. `false` will disable all arguments. A list of [`ShellScopeEntryAllowedArg`] will set those arguments as the only valid arguments to be passed to the attached command configuration."}},"description":"Shell scope entry.","title":"ShellScopeEntry"}},"updater":{"default_permission":{"identifier":"default","description":"This permission set configures which kind of\nupdater functions are exposed to the frontend.\n\n#### Granted Permissions\n\nThe full workflow from checking for updates to installing them\nis enabled.\n\n","permissions":["allow-check","allow-download","allow-install","allow-download-and-install"]},"permissions":{"allow-check":{"identifier":"allow-check","description":"Enables the check command without any pre-configured scope.","commands":{"allow":["check"],"deny":[]}},"allow-download":{"identifier":"allow-download","description":"Enables the download command without any pre-configured scope.","commands":{"allow":["download"],"deny":[]}},"allow-download-and-install":{"identifier":"allow-download-and-install","description":"Enables the download_and_install command without any pre-configured scope.","commands":{"allow":["download_and_install"],"deny":[]}},"allow-install":{"identifier":"allow-install","description":"Enables the install command without any pre-configured scope.","commands":{"allow":["install"],"deny":[]}},"deny-check":{"identifier":"deny-check","description":"Denies the check command without any pre-configured scope.","commands":{"allow":[],"deny":["check"]}},"deny-download":{"identifier":"deny-download","description":"Denies the download command without any pre-configured scope.","commands":{"allow":[],"deny":["download"]}},"deny-download-and-install":{"identifier":"deny-download-and-install","description":"Denies the download_and_install command without any pre-configured scope.","commands":{"allow":[],"deny":["download_and_install"]}},"deny-install":{"identifier":"deny-install","description":"Denies the install command without any pre-configured scope.","commands":{"allow":[],"deny":["install"]}}},"permission_sets":{},"global_scope_schema":null},"window-state":{"default_permission":{"identifier":"default","description":"This permission set configures what kind of\noperations are available from the window state plugin.\n\n#### Granted Permissions\n\nAll operations are enabled by default.\n\n","permissions":["allow-filename","allow-restore-state","allow-save-window-state"]},"permissions":{"allow-filename":{"identifier":"allow-filename","description":"Enables the filename command without any pre-configured scope.","commands":{"allow":["filename"],"deny":[]}},"allow-restore-state":{"identifier":"allow-restore-state","description":"Enables the restore_state command without any pre-configured scope.","commands":{"allow":["restore_state"],"deny":[]}},"allow-save-window-state":{"identifier":"allow-save-window-state","description":"Enables the save_window_state command without any pre-configured scope.","commands":{"allow":["save_window_state"],"deny":[]}},"deny-filename":{"identifier":"deny-filename","description":"Denies the filename command without any pre-configured scope.","commands":{"allow":[],"deny":["filename"]}},"deny-restore-state":{"identifier":"deny-restore-state","description":"Denies the restore_state command without any pre-configured scope.","commands":{"allow":[],"deny":["restore_state"]}},"deny-save-window-state":{"identifier":"deny-save-window-state","description":"Denies the save_window_state command without any pre-configured scope.","commands":{"allow":[],"deny":["save_window_state"]}}},"permission_sets":{},"global_scope_schema":null}}
\ No newline at end of file
diff --git a/src-tauri/gen/schemas/capabilities.json b/src-tauri/gen/schemas/capabilities.json
index 07fa89bf0..08696fba7 100644
--- a/src-tauri/gen/schemas/capabilities.json
+++ b/src-tauri/gen/schemas/capabilities.json
@@ -1 +1 @@
-{"default":{"identifier":"default","description":"Capability for the main window","local":true,"windows":["main"],"permissions":["core:default","core:window:allow-start-dragging","core:window:allow-toggle-maximize","core:window:allow-show","core:window:allow-close","core:window:allow-set-size","core:window:allow-set-min-size","deep-link:default","opener:default",{"identifier":"opener:allow-open-url","allow":[{"url":"linear://*"},{"url":"https://linear.app/*"}]},{"identifier":"opener:allow-open-path","allow":[{"path":"$HOME/**"},{"path":"$HOME/.goose/**"},{"path":"$TEMP/**"},{"path":"/Volumes/**"},{"path":"/mnt/**"},{"path":"/workspace/**"},{"path":"/workspaces/**"},{"path":"/opt/**"},{"path":"/srv/**"},{"path":"*:/**"}]},"window-state:allow-restore-state","window-state:allow-save-window-state","dialog:allow-open","dialog:allow-save","clipboard-manager:allow-write-text","app-test-driver:default","berdctl:default","updater:default","process:allow-restart","notification:default"]},"session-window":{"identifier":"session-window","description":"Capability for popped-out chat session windows","local":true,"windows":["session:*"],"permissions":["core:default","core:window:allow-start-dragging","core:window:allow-show","core:window:allow-close","core:window:allow-set-focus","core:window:allow-set-size","core:window:allow-set-min-size","opener:default",{"identifier":"opener:allow-open-url","allow":[{"url":"linear://*"},{"url":"https://linear.app/*"}]},{"identifier":"opener:allow-open-path","allow":[{"path":"$HOME/**"},{"path":"$HOME/.goose/**"},{"path":"$TEMP/**"},{"path":"/Volumes/**"},{"path":"/mnt/**"},{"path":"/workspace/**"},{"path":"/workspaces/**"},{"path":"/opt/**"},{"path":"/srv/**"},{"path":"*:/**"}]},"dialog:allow-open","dialog:allow-save","berdctl:allow-status"],"platforms":["macOS"]},"voice-buddy":{"identifier":"voice-buddy","description":"Capability for the always-on-top voice conversation buddy","local":true,"windows":["voice-buddy"],"permissions":["core:default","core:window:allow-start-dragging"]}}
\ No newline at end of file
+{"default":{"identifier":"default","description":"Capability for the main window","local":true,"windows":["main"],"permissions":["core:default","core:window:allow-start-dragging","core:window:allow-toggle-maximize","core:window:allow-show","core:window:allow-close","core:window:allow-set-size","core:window:allow-set-min-size","deep-link:default","opener:default",{"identifier":"opener:allow-open-url","allow":[{"url":"linear://*"},{"url":"https://linear.app/*"}]},{"identifier":"opener:allow-open-path","allow":[{"path":"$HOME/**"},{"path":"$HOME/.goose/**"},{"path":"$TEMP/**"},{"path":"/Volumes/**"},{"path":"/mnt/**"},{"path":"/workspace/**"},{"path":"/workspaces/**"},{"path":"/opt/**"},{"path":"/srv/**"},{"path":"*:/**"}]},"window-state:allow-restore-state","window-state:allow-save-window-state","dialog:allow-open","dialog:allow-save","clipboard-manager:allow-write-text","app-test-driver:default","berdctl:default","updater:default","process:allow-restart","notification:default"]},"desktop-agent":{"identifier":"desktop-agent","description":"Capability for the Berd Desktop Agent panel window","local":true,"windows":["desktop-agent"],"permissions":["core:default"],"platforms":["macOS"]},"session-window":{"identifier":"session-window","description":"Capability for popped-out chat session windows","local":true,"windows":["session:*"],"permissions":["core:default","core:window:allow-start-dragging","core:window:allow-show","core:window:allow-close","core:window:allow-set-focus","core:window:allow-set-size","core:window:allow-set-min-size","opener:default",{"identifier":"opener:allow-open-url","allow":[{"url":"linear://*"},{"url":"https://linear.app/*"}]},{"identifier":"opener:allow-open-path","allow":[{"path":"$HOME/**"},{"path":"$HOME/.goose/**"},{"path":"$TEMP/**"},{"path":"/Volumes/**"},{"path":"/mnt/**"},{"path":"/workspace/**"},{"path":"/workspaces/**"},{"path":"/opt/**"},{"path":"/srv/**"},{"path":"*:/**"}]},"dialog:allow-open","dialog:allow-save","berdctl:allow-status"],"platforms":["macOS"]},"voice-buddy":{"identifier":"voice-buddy","description":"Capability for the always-on-top voice conversation buddy","local":true,"windows":["voice-buddy"],"permissions":["core:default","core:window:allow-start-dragging"]}}
\ No newline at end of file
diff --git a/src-tauri/gen/schemas/desktop-schema.json b/src-tauri/gen/schemas/desktop-schema.json
index 1f658ed17..08a491dbe 100644
--- a/src-tauri/gen/schemas/desktop-schema.json
+++ b/src-tauri/gen/schemas/desktop-schema.json
@@ -2852,6 +2852,72 @@
           "const": "dialog:deny-save",
           "markdownDescription": "Denies the save command without any pre-configured scope."
         },
+        {
+          "description": "No features are enabled by default, as we believe\nthe shortcuts can be inherently dangerous and it is\napplication specific if specific shortcuts should be\nregistered or unregistered.\n",
+          "type": "string",
+          "const": "global-shortcut:default",
+          "markdownDescription": "No features are enabled by default, as we believe\nthe shortcuts can be inherently dangerous and it is\napplication specific if specific shortcuts should be\nregistered or unregistered.\n"
+        },
+        {
+          "description": "Enables the is_registered command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-is-registered",
+          "markdownDescription": "Enables the is_registered command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the register command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-register",
+          "markdownDescription": "Enables the register command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the register_all command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-register-all",
+          "markdownDescription": "Enables the register_all command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the unregister command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-unregister",
+          "markdownDescription": "Enables the unregister command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the unregister_all command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-unregister-all",
+          "markdownDescription": "Enables the unregister_all command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the is_registered command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-is-registered",
+          "markdownDescription": "Denies the is_registered command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the register command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-register",
+          "markdownDescription": "Denies the register command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the register_all command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-register-all",
+          "markdownDescription": "Denies the register_all command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the unregister command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-unregister",
+          "markdownDescription": "Denies the unregister command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the unregister_all command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-unregister-all",
+          "markdownDescription": "Denies the unregister_all command without any pre-configured scope."
+        },
         {
           "description": "Allows the log command\n#### This default permission set includes:\n\n- `allow-log`",
           "type": "string",
diff --git a/src-tauri/gen/schemas/macOS-schema.json b/src-tauri/gen/schemas/macOS-schema.json
index 1f658ed17..08a491dbe 100644
--- a/src-tauri/gen/schemas/macOS-schema.json
+++ b/src-tauri/gen/schemas/macOS-schema.json
@@ -2852,6 +2852,72 @@
           "const": "dialog:deny-save",
           "markdownDescription": "Denies the save command without any pre-configured scope."
         },
+        {
+          "description": "No features are enabled by default, as we believe\nthe shortcuts can be inherently dangerous and it is\napplication specific if specific shortcuts should be\nregistered or unregistered.\n",
+          "type": "string",
+          "const": "global-shortcut:default",
+          "markdownDescription": "No features are enabled by default, as we believe\nthe shortcuts can be inherently dangerous and it is\napplication specific if specific shortcuts should be\nregistered or unregistered.\n"
+        },
+        {
+          "description": "Enables the is_registered command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-is-registered",
+          "markdownDescription": "Enables the is_registered command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the register command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-register",
+          "markdownDescription": "Enables the register command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the register_all command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-register-all",
+          "markdownDescription": "Enables the register_all command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the unregister command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-unregister",
+          "markdownDescription": "Enables the unregister command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the unregister_all command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:allow-unregister-all",
+          "markdownDescription": "Enables the unregister_all command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the is_registered command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-is-registered",
+          "markdownDescription": "Denies the is_registered command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the register command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-register",
+          "markdownDescription": "Denies the register command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the register_all command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-register-all",
+          "markdownDescription": "Denies the register_all command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the unregister command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-unregister",
+          "markdownDescription": "Denies the unregister command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the unregister_all command without any pre-configured scope.",
+          "type": "string",
+          "const": "global-shortcut:deny-unregister-all",
+          "markdownDescription": "Denies the unregister_all command without any pre-configured scope."
+        },
         {
           "description": "Allows the log command\n#### This default permission set includes:\n\n- `allow-log`",
           "type": "string",
diff --git a/src-tauri/src/desktop_agent/capture.rs b/src-tauri/src/desktop_agent/capture.rs
new file mode 100644
index 000000000..76ac7cd5f
--- /dev/null
+++ b/src-tauri/src/desktop_agent/capture.rs
@@ -0,0 +1,157 @@
+//! ScreenCaptureKit still-image capture for perch mode.
+//!
+//! Decisions carried from the prototype: fresh capture per send; 1500px
+//! long-edge cap; PNG; no quality knob. Window-scoped capture only — the
+//! prototype's display-region path was deleted before the port.
+
+use std::ptr::NonNull;
+use std::sync::mpsc;
+use std::time::Duration;
+
+use block2::RcBlock;
+use objc2::rc::Retained;
+use objc2::runtime::AnyObject;
+use objc2::{msg_send, AllocAnyThread};
+use objc2_core_graphics::CGImage;
+use objc2_foundation::{NSDictionary, NSError};
+use objc2_screen_capture_kit::{
+    SCContentFilter, SCScreenshotManager, SCShareableContent, SCStreamConfiguration, SCWindow,
+};
+use serde::Serialize;
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CaptureDto {
+    /// Base64 PNG.
+    pub data: String,
+    pub mime_type: String,
+}
+
+/// Window-scoped capture for perch mode:
+/// SCContentFilter(desktopIndependentWindow:) — no display math, works
+/// even when the window is occluded. Called from perch::desktop_agent_perch_capture.
+pub async fn capture_window(window_id: u32) -> Result<CaptureDto, String> {
+    let png = tauri::async_runtime::spawn_blocking(move || capture_window_blocking(window_id))
+        .await
+        .map_err(|e| e.to_string())??;
+    use base64::Engine;
+    Ok(CaptureDto {
+        data: base64::engine::general_purpose::STANDARD.encode(png),
+        mime_type: "image/png".into(),
+    })
+}
+
+fn capture_window_blocking(window_id: u32) -> Result<Vec<u8>, String> {
+    let (tx, rx) = mpsc::channel::<Result<Vec<u8>, String>>();
+
+    let content_tx = tx.clone();
+    let content_block = RcBlock::new(
+        move |content: *mut SCShareableContent, error: *mut NSError| {
+            if content.is_null() {
+                let message = unsafe {
+                    error
+                        .as_ref()
+                        .map(|e| e.localizedDescription().to_string())
+                        .unwrap_or_else(|| "screen capture unavailable".into())
+                };
+                let _ = content_tx.send(Err(message));
+                return;
+            }
+            let content = unsafe { &*content };
+            // onScreenWindowsOnly=false below: a window that minimized or
+            // left the Space between the follow tick and this capture must
+            // still be findable — degrade at the SCK level, not by us
+            // failing to find the window.
+            let windows = unsafe { content.windows() };
+            let window: Option<Retained<SCWindow>> = windows
+                .iter()
+                .find(|w| unsafe { w.windowID() } == window_id);
+            let Some(window) = window else {
+                let _ = content_tx.send(Err("The perched window is no longer available".into()));
+                return;
+            };
+            let filter = unsafe {
+                SCContentFilter::initWithDesktopIndependentWindow(SCContentFilter::alloc(), &window)
+            };
+            let size = unsafe { filter.contentRect() }.size;
+            let long_edge = size.width.max(size.height);
+            let scale = if long_edge > 1500.0 {
+                1500.0 / long_edge
+            } else {
+                1.0
+            };
+            let config = unsafe { SCStreamConfiguration::new() };
+            unsafe {
+                config.setWidth((size.width * scale).max(1.0) as usize);
+                config.setHeight((size.height * scale).max(1.0) as usize);
+                config.setShowsCursor(false);
+                config.setScalesToFit(true);
+                config.setPreservesAspectRatio(true);
+            }
+            let shot_tx = content_tx.clone();
+            let shot_block = RcBlock::new(move |image: *mut CGImage, error: *mut NSError| {
+                if let Some(image) = NonNull::new(image) {
+                    let _ = shot_tx.send(encode_png(unsafe { image.as_ref() }));
+                } else {
+                    let message = unsafe {
+                        error
+                            .as_ref()
+                            .map(|e| e.localizedDescription().to_string())
+                            .unwrap_or_else(|| "screenshot failed".into())
+                    };
+                    let _ = shot_tx.send(Err(message));
+                }
+            });
+            unsafe {
+                SCScreenshotManager::captureImageWithFilter_configuration_completionHandler(
+                    &filter,
+                    &config,
+                    Some(&shot_block),
+                );
+            }
+        },
+    );
+    unsafe {
+        SCShareableContent::getShareableContentExcludingDesktopWindows_onScreenWindowsOnly_completionHandler(
+            false, false, &content_block,
+        );
+    }
+
+    rx.recv_timeout(Duration::from_secs(15))
+        .map_err(|_| "screen capture timed out".to_string())?
+}
+
+/// CGImage -> PNG bytes via NSBitmapImageRep.
+///
+/// Runs on a blocking thread with NO ambient autorelease pool, so one is
+/// created explicitly and the alloc/init'd rep is released on every path
+/// (an earlier shape leaked the rep — holding the full screenshot — on
+/// every capture, plus the autoreleased NSData).
+fn encode_png(image: &CGImage) -> Result<Vec<u8>, String> {
+    objc2::rc::autoreleasepool(|_| unsafe {
+        let cls =
+            objc2::runtime::AnyClass::get(&std::ffi::CString::new("NSBitmapImageRep").unwrap())
+                .ok_or("NSBitmapImageRep unavailable")?;
+        let rep: *mut AnyObject = msg_send![cls, alloc];
+        let image_ptr: *const CGImage = image;
+        let rep: *mut AnyObject = msg_send![rep, initWithCGImage: image_ptr];
+        if rep.is_null() {
+            return Err("could not wrap screenshot".into());
+        }
+        let result = (|| {
+            let props: Retained<NSDictionary> = NSDictionary::new();
+            // NSBitmapImageFileTypePNG == 4
+            let data: *mut AnyObject =
+                msg_send![&*rep, representationUsingType: 4usize, properties: &*props];
+            if data.is_null() {
+                return Err("could not encode screenshot as PNG".into());
+            }
+            // NSData is autoreleased — the pool drains it; copy out first.
+            let length: usize = msg_send![&*data, length];
+            let bytes: *const u8 = msg_send![&*data, bytes];
+            Ok(std::slice::from_raw_parts(bytes, length).to_vec())
+        })();
+        let _: () = msg_send![&*rep, release];
+        result
+    })
+}
diff --git a/src-tauri/src/desktop_agent/coordinate_space.rs b/src-tauri/src/desktop_agent/coordinate_space.rs
new file mode 100644
index 000000000..d723adec2
--- /dev/null
+++ b/src-tauri/src/desktop_agent/coordinate_space.rs
@@ -0,0 +1,449 @@
+//! Coordinate space conversions for the desktop agent panel.
+//!
+//! THE HARD RULE: this module is the sole
+//! authority for CG top-left ↔ AppKit bottom-left conversions. No other
+//! module does coordinate flips. The webview/TS layer works exclusively in
+//! global top-left coordinates (the channel contract); Rust converts at
+//! the AppKit boundary using these functions.
+//!
+//! Pure functions take screen geometry as parameters so they unit-test
+//! without AppKit. Callers fetch live screens via `screens()` (main thread).
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Rect {
+    pub x: f64,
+    pub y: f64,
+    pub width: f64,
+    pub height: f64,
+}
+
+impl Rect {
+    pub const fn new(x: f64, y: f64, width: f64, height: f64) -> Self {
+        Self {
+            x,
+            y,
+            width,
+            height,
+        }
+    }
+    pub fn max_x(&self) -> f64 {
+        self.x + self.width
+    }
+    pub fn max_y(&self) -> f64 {
+        self.y + self.height
+    }
+    pub fn mid_x(&self) -> f64 {
+        self.x + self.width / 2.0
+    }
+    pub fn mid_y(&self) -> f64 {
+        self.y + self.height / 2.0
+    }
+}
+
+/// A display in AppKit global (bottom-left origin) coordinates.
+#[derive(Debug, Clone, Copy)]
+pub struct Screen {
+    pub frame: Rect,
+    pub visible_frame: Rect,
+}
+
+/// Total bounding height of all screens in AppKit global space — the flip
+/// constant between AppKit and top-left conventions.
+pub fn global_max_y(screens: &[Screen]) -> f64 {
+    screens.iter().map(|s| s.frame.max_y()).fold(0.0, f64::max)
+}
+
+/// Top-left global rect -> AppKit global rect).
+pub fn appkit_rect_from_top_left(rect: Rect, screens: &[Screen]) -> Rect {
+    Rect::new(
+        rect.x,
+        global_max_y(screens) - rect.y - rect.height,
+        rect.width,
+        rect.height,
+    )
+}
+
+/// AppKit global rect -> top-left global rect).
+pub fn top_left_rect_from_appkit(rect: Rect, screens: &[Screen]) -> Rect {
+    Rect::new(
+        rect.x,
+        global_max_y(screens) - rect.max_y(),
+        rect.width,
+        rect.height,
+    )
+}
+
+/// AppKit global rect -> CoreGraphics/ScreenCaptureKit global space.
+/// Unlike the channel contract above, CoreGraphics anchors Y to the PRIMARY
+/// display's top-left, not the maximum Y across all displays. These
+/// conventions coincide on one display but diverge when a display extends
+/// above the primary..)
+pub fn cg_rect_from_appkit(rect: Rect, screens: &[Screen]) -> Rect {
+    let primary_max_y = screens.first().map(|s| s.frame.max_y()).unwrap_or(0.0);
+    Rect::new(
+        rect.x,
+        primary_max_y - rect.max_y(),
+        rect.width,
+        rect.height,
+    )
+}
+
+/// Inverse of `cg_rect_from_appkit`).
+pub fn appkit_rect_from_cg(rect: Rect, screens: &[Screen]) -> Rect {
+    let primary_max_y = screens.first().map(|s| s.frame.max_y()).unwrap_or(0.0);
+    Rect::new(
+        rect.x,
+        primary_max_y - rect.max_y(),
+        rect.width,
+        rect.height,
+    )
+}
+
+/// Clamp a rect inside bounds).
+pub fn clamp(rect: Rect, bounds: Rect) -> Rect {
+    let width = rect.width.min(bounds.width);
+    let height = rect.height.min(bounds.height);
+    Rect::new(
+        rect.x.max(bounds.x).min(bounds.max_x() - width),
+        rect.y.max(bounds.y).min(bounds.max_y() - height),
+        width,
+        height,
+    )
+}
+
+/// Clamp a rect FULLY inside the visible frame of the best screen (most
+/// overlap; tie broken by nearest center) — used for panel seating so the
+/// avatar never clips a monitor edge.
+pub fn clamp_within_visible_screens(rect: Rect, screens: &[Screen]) -> Rect {
+    let Some(target) = best_screen_frame(rect, screens) else {
+        return rect;
+    };
+    clamp(rect, target)
+}
+
+fn best_screen_frame(rect: Rect, screens: &[Screen]) -> Option<Rect> {
+    screens.iter().map(|s| s.visible_frame).max_by(|lhs, rhs| {
+        let la = intersection_area(rect, *lhs);
+        let ra = intersection_area(rect, *rhs);
+        if la != ra {
+            la.partial_cmp(&ra).unwrap()
+        } else {
+            center_distance_squared(rect, *rhs)
+                .partial_cmp(&center_distance_squared(rect, *lhs))
+                .unwrap()
+        }
+    })
+}
+
+/// Title-bar band of a window frame, AppKit space.
+pub fn title_bar_band(rect: Rect, height: f64) -> Rect {
+    let h = height.min(rect.height);
+    Rect::new(rect.x, rect.max_y() - h, rect.width, h)
+}
+
+/// Title-bar band for drop HIT-TESTING (not display). When the window's top
+/// edge abuts the top of its screen's visible area (maximized windows), the
+/// pointer naturally overshoots into the menu-bar strip — extend the band to
+/// the physical screen top so the drop still counts.
+pub fn title_bar_hit_band(rect: Rect, height: f64, screens: &[Screen]) -> Rect {
+    let mut band = title_bar_band(rect, height);
+    let screen = screens
+        .iter()
+        .max_by(|a, b| {
+            intersection_area(a.frame, rect)
+                .partial_cmp(&intersection_area(b.frame, rect))
+                .unwrap()
+        })
+        .filter(|s| intersection_area(s.frame, rect) > 0.0);
+    if let Some(screen) = screen {
+        if rect.max_y() >= screen.visible_frame.max_y() - 1.0 && screen.frame.max_y() > band.max_y()
+        {
+            band.height += screen.frame.max_y() - band.max_y();
+        }
+    }
+    band
+}
+
+/// Panel frame for an avatar perched on a window's title bar at a horizontal
+/// offset ratio, straddling the top edge by `overlap`.
+/// Left margin kept clear of the perched avatar so the window's
+/// traffic-light buttons (close/minimize/zoom, ~62pt from the left edge)
+/// stay clickable.
+pub const TRAFFIC_LIGHT_CLEARANCE: f64 = 78.0;
+
+// The canvas is 92pt centered in a 94pt panel. Include its 1pt bottom
+// inset, not panel_height * (1 - anchor), so the butt line meets the edge.
+pub fn avatar_perch_overlap(character: bool) -> f64 {
+    if character {
+        1.0 + 92.0 * (1.0 - 0.74)
+    } else {
+        12.0
+    }
+}
+
+pub fn perch_frame(window: Rect, panel: (f64, f64), offset_ratio: f64, overlap: f64) -> Rect {
+    let (pw, ph) = panel;
+    let ratio = offset_ratio.clamp(0.0, 1.0);
+    let target_x = window.x + window.width * ratio;
+    let max_x = window.max_x() - pw;
+    // Keep the traffic lights clear when the window is wide enough;
+    // narrow windows degrade to the old flush-left clamp.
+    let cleared_min = window.x + TRAFFIC_LIGHT_CLEARANCE;
+    let min_x = if max_x >= cleared_min {
+        cleared_min
+    } else {
+        window.x
+    };
+    let origin_x = if max_x >= min_x {
+        (target_x - pw / 2.0).clamp(min_x, max_x)
+    } else {
+        window.mid_x() - pw / 2.0
+    };
+    Rect::new(origin_x, window.max_y() - overlap, pw, ph)
+}
+
+// (The outline no longer has its own dock position: the avatar always
+// seats via perch_frame. The waiting-spot helper is gone with the
+// waiting phase itself — minimize now ends the perch.)
+
+/// Shared intersection helper.
+pub fn intersection_area(lhs: Rect, rhs: Rect) -> f64 {
+    let w = lhs.max_x().min(rhs.max_x()) - lhs.x.max(rhs.x);
+    let h = lhs.max_y().min(rhs.max_y()) - lhs.y.max(rhs.y);
+    if w <= 0.0 || h <= 0.0 {
+        0.0
+    } else {
+        w * h
+    }
+}
+
+fn center_distance_squared(lhs: Rect, rhs: Rect) -> f64 {
+    let dx = lhs.mid_x() - rhs.mid_x();
+    let dy = lhs.mid_y() - rhs.mid_y();
+    dx * dx + dy * dy
+}
+
+/// Live screens in AppKit global coordinates. MAIN THREAD ONLY (AppKit).
+pub fn screens() -> Vec<Screen> {
+    use objc2::msg_send;
+    use objc2::runtime::AnyObject;
+    use objc2_foundation::NSRect;
+    use std::ffi::CString;
+
+    fn to_rect(r: NSRect) -> Rect {
+        Rect::new(r.origin.x, r.origin.y, r.size.width, r.size.height)
+    }
+
+    unsafe {
+        let cls = objc2::runtime::AnyClass::get(&CString::new("NSScreen").unwrap()).unwrap();
+        let arr: *mut AnyObject = msg_send![cls, screens];
+        let count: usize = msg_send![&*arr, count];
+        (0..count)
+            .map(|i| {
+                let screen: *mut AnyObject = msg_send![&*arr, objectAtIndex: i];
+                let frame: NSRect = msg_send![&*screen, frame];
+                let visible: NSRect = msg_send![&*screen, visibleFrame];
+                Screen {
+                    frame: to_rect(frame),
+                    visible_frame: to_rect(visible),
+                }
+            })
+            .collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn single_screen() -> Vec<Screen> {
+        vec![Screen {
+            frame: Rect::new(0.0, 0.0, 1512.0, 982.0),
+            visible_frame: Rect::new(0.0, 76.0, 1512.0, 874.0),
+        }]
+    }
+
+    fn dual_screens() -> Vec<Screen> {
+        // External display above the primary (the divergence case).
+        vec![
+            Screen {
+                frame: Rect::new(0.0, 0.0, 1512.0, 982.0),
+                visible_frame: Rect::new(0.0, 76.0, 1512.0, 874.0),
+            },
+            Screen {
+                frame: Rect::new(0.0, 982.0, 2560.0, 1440.0),
+                visible_frame: Rect::new(0.0, 982.0, 2560.0, 1415.0),
+            },
+        ]
+    }
+
+    #[test]
+    fn character_seat_accounts_for_canvas_padding_and_chip_is_unchanged() {
+        let window = Rect::new(100.0, 100.0, 800.0, 600.0);
+        let seat = perch_frame(window, (94.0, 94.0), 0.5, avatar_perch_overlap(true));
+        let butt_y = seat.y + 1.0 + 92.0 * (1.0 - 0.74);
+        assert!((butt_y - (window.y + window.height)).abs() < 1e-9);
+        assert_eq!(avatar_perch_overlap(false), 12.0);
+    }
+
+    #[test]
+    fn round_trips_top_left_and_appkit() {
+        for screens in [single_screen(), dual_screens()] {
+            let top_left = Rect::new(100.0, 40.0, 90.0, 90.0);
+            let appkit = appkit_rect_from_top_left(top_left, &screens);
+            let back = top_left_rect_from_appkit(appkit, &screens);
+            assert_eq!(back, top_left);
+        }
+    }
+
+    #[test]
+    fn top_left_origin_maps_to_global_top() {
+        let screens = single_screen();
+        let appkit = appkit_rect_from_top_left(Rect::new(0.0, 0.0, 90.0, 90.0), &screens);
+        // Top-left (0,0) = AppKit y at globalMaxY - height.
+        assert_eq!(appkit.y, 982.0 - 90.0);
+    }
+
+    #[test]
+    fn stacked_display_uses_total_bounding_height() {
+        let screens = dual_screens();
+        assert_eq!(global_max_y(&screens), 982.0 + 1440.0);
+        let appkit = appkit_rect_from_top_left(Rect::new(0.0, 0.0, 90.0, 90.0), &screens);
+        assert_eq!(appkit.y, 2422.0 - 90.0);
+    }
+
+    #[test]
+    fn cg_conversion_coincides_on_single_display() {
+        let screens = single_screen();
+        let appkit = Rect::new(100.0, 100.0, 300.0, 200.0);
+        let cg = cg_rect_from_appkit(appkit, &screens);
+        // Single display: CG top-left == globalMaxY flip.
+        assert_eq!(cg, top_left_rect_from_appkit(appkit, &screens));
+        assert_eq!(appkit_rect_from_cg(cg, &screens), appkit);
+    }
+
+    #[test]
+    fn cg_conversion_diverges_with_display_above_primary() {
+        let screens = dual_screens();
+        let appkit = Rect::new(0.0, 1000.0, 100.0, 100.0); // on the upper display
+        let cg = cg_rect_from_appkit(appkit, &screens);
+        // CG anchors to the PRIMARY height (982), not globalMaxY (2422):
+        // y = 982 - 1100 = -118 (above the primary's top in CG space).
+        assert_eq!(cg.y, -118.0);
+        assert_ne!(cg, top_left_rect_from_appkit(appkit, &screens));
+        assert_eq!(appkit_rect_from_cg(cg, &screens), appkit);
+    }
+
+    #[test]
+    fn clamp_keeps_rect_inside_bounds() {
+        let bounds = Rect::new(0.0, 76.0, 1512.0, 874.0);
+        let clamped = clamp(Rect::new(-50.0, 1000.0, 90.0, 90.0), bounds);
+        assert_eq!(clamped.x, 0.0);
+        assert_eq!(clamped.max_y(), bounds.max_y());
+    }
+
+    #[test]
+    fn clamp_shrinks_oversized_rect() {
+        let bounds = Rect::new(0.0, 0.0, 100.0, 100.0);
+        let clamped = clamp(Rect::new(0.0, 0.0, 500.0, 50.0), bounds);
+        assert_eq!(clamped.width, 100.0);
+    }
+
+    #[test]
+    fn within_clamp_pulls_partially_clipped_rect_fully_inside() {
+        let screens = single_screen();
+        // Half off the left edge — the partial-visibility clamp tolerates
+        // this; the full-containment clamp must not.
+        let clipped = Rect::new(-45.0, 200.0, 90.0, 90.0);
+        let contained = clamp_within_visible_screens(clipped, &screens);
+        assert_eq!(contained, Rect::new(0.0, 200.0, 90.0, 90.0));
+    }
+
+    #[test]
+    fn within_clamp_contains_rect_straddling_top_edge() {
+        let screens = single_screen();
+        // Perch straddle on a window flush with the visible top: seat pokes
+        // above max_y (950). Must be pulled fully inside.
+        let straddle = Rect::new(300.0, 920.0, 94.0, 94.0);
+        let contained = clamp_within_visible_screens(straddle, &screens);
+        assert_eq!(contained.max_y(), screens[0].visible_frame.max_y());
+        assert_eq!(contained.x, 300.0);
+    }
+
+    #[test]
+    fn within_clamp_leaves_fully_visible_rect_alone() {
+        let screens = single_screen();
+        let inside = Rect::new(300.0, 300.0, 94.0, 94.0);
+        assert_eq!(clamp_within_visible_screens(inside, &screens), inside);
+    }
+
+    #[test]
+    fn within_clamp_uses_best_screen_on_dual_displays() {
+        let screens = dual_screens();
+        // Mostly on the upper display, poking past its top edge (2397).
+        let poking = Rect::new(100.0, 2360.0, 94.0, 94.0);
+        let contained = clamp_within_visible_screens(poking, &screens);
+        assert_eq!(contained.max_y(), screens[1].visible_frame.max_y());
+    }
+
+    #[test]
+    fn within_clamp_empty_screens_is_identity() {
+        let r = Rect::new(1.0, 2.0, 3.0, 4.0);
+        assert_eq!(clamp_within_visible_screens(r, &[]), r);
+    }
+
+    #[test]
+    fn title_bar_band_is_top_strip_in_appkit_space() {
+        let window = Rect::new(100.0, 100.0, 800.0, 600.0);
+        let band = title_bar_band(window, 40.0);
+        // AppKit: top of the window is maxY.
+        assert_eq!(band.y, 660.0);
+        assert_eq!(band.height, 40.0);
+        assert_eq!(band.width, 800.0);
+    }
+
+    #[test]
+    fn hit_band_extends_through_menu_bar_for_maximized_windows() {
+        let screens = single_screen();
+        // Window top flush against the visible-area top (76 + 874 = 950).
+        let window = Rect::new(0.0, 76.0, 1512.0, 874.0);
+        let band = title_bar_hit_band(window, 40.0, &screens);
+        // Extends to the physical screen top (982).
+        assert_eq!(band.max_y(), 982.0);
+        // A normal mid-screen window is untouched.
+        let normal = Rect::new(100.0, 100.0, 800.0, 600.0);
+        let normal_band = title_bar_hit_band(normal, 40.0, &screens);
+        assert_eq!(normal_band, title_bar_band(normal, 40.0));
+    }
+
+    #[test]
+    fn perch_frame_clamps_offset_and_straddles_top_edge() {
+        let window = Rect::new(100.0, 100.0, 800.0, 600.0);
+        // Centered drop at ratio 0.5.
+        let mid = perch_frame(window, (90.0, 90.0), 0.5, 12.0);
+        assert_eq!(mid.x, 100.0 + 400.0 - 45.0);
+        // Straddle: panel bottom overlaps the window top by `overlap`.
+        assert_eq!(mid.y, 700.0 - 12.0);
+        // Ratio 1.0 clamps to the right edge.
+        let right = perch_frame(window, (90.0, 90.0), 1.0, 12.0);
+        assert_eq!(right.x, 900.0 - 90.0);
+        // Ratio 0.0 clamps RIGHT of the traffic lights, not flush-left
+        // (flush-left would cover close/minimize).
+        let left = perch_frame(window, (90.0, 90.0), 0.0, 12.0);
+        assert_eq!(left.x, 100.0 + TRAFFIC_LIGHT_CLEARANCE);
+        // Window narrower than the panel centers on it.
+        let narrow = perch_frame(Rect::new(0.0, 0.0, 50.0, 100.0), (90.0, 90.0), 0.0, 12.0);
+        assert_eq!(narrow.x, 25.0 - 45.0);
+    }
+
+    #[test]
+    fn intersection_area_of_disjoint_rects_is_zero() {
+        assert_eq!(
+            intersection_area(
+                Rect::new(0.0, 0.0, 10.0, 10.0),
+                Rect::new(20.0, 20.0, 10.0, 10.0)
+            ),
+            0.0
+        );
+    }
+}
diff --git a/src-tauri/src/desktop_agent/main_thread.rs b/src-tauri/src/desktop_agent/main_thread.rs
new file mode 100644
index 000000000..5c3949e9b
--- /dev/null
+++ b/src-tauri/src/desktop_agent/main_thread.rs
@@ -0,0 +1,19 @@
+//! The one main-thread hop helper. AppKit rule: every AppKit-touching
+//! call runs on the main thread; this helper hops there and returns the
+//! closure's value over a channel.
+
+use std::sync::mpsc;
+
+use tauri::AppHandle;
+
+pub fn on_main<T: Send + 'static>(
+    app: &AppHandle,
+    f: impl FnOnce() -> T + Send + 'static,
+) -> Result<T, String> {
+    let (tx, rx) = mpsc::channel();
+    app.run_on_main_thread(move || {
+        let _ = tx.send(f());
+    })
+    .map_err(|e| e.to_string())?;
+    rx.recv().map_err(|e| e.to_string())
+}
diff --git a/src-tauri/src/desktop_agent/mod.rs b/src-tauri/src/desktop_agent/mod.rs
new file mode 100644
index 000000000..2016a457e
--- /dev/null
+++ b/src-tauri/src/desktop_agent/mod.rs
@@ -0,0 +1,217 @@
+//! Berd Desktop Agent — native panel shell (macOS only, experiment-gated).
+//!
+//! Owns the lifecycle of the `desktop-agent` window: a small always-on-top,
+//! non-activating NSPanel hosting the desktop-agent webview route
+//! (`index.html?window=desktop-agent`). The settings bridge in the main
+//! webview drives it:
+//!
+//! - setting enabled -> `desktop_agent_open`
+//! - setting disabled -> `desktop_agent_close` (destroy; "Hide agent" in
+//!   the panel's context menu turns the setting off, so hide == disable)
+//!
+//! The panel-toggle chord arrives as an ARGUMENT from the bridge (read
+//! from the shortcuts-registry entry `desktopAgent.togglePanel`) — never
+//! hardcoded here. Registration failure (e.g. the chord is held by another
+//! app) logs and continues: the panel works without a shortcut.
+//!
+//! No activation-policy calls anywhere in this module: Berd is a regular
+//! app with a Dock icon and must stay one. The non-activating NSPanel
+//! style mask (panel.rs) alone keeps focus with the app the user is
+//! working in.
+
+pub mod capture;
+pub mod coordinate_space;
+mod main_thread;
+mod overlay_panel;
+mod panel;
+pub mod perch;
+pub mod permissions;
+pub mod window_commands;
+
+use std::sync::Mutex;
+
+use tauri::{AppHandle, Emitter, Manager, WebviewUrl, WebviewWindowBuilder};
+use tauri_plugin_global_shortcut::{GlobalShortcutExt, Shortcut, ShortcutState};
+
+/// Window label for the panel webview. Also referenced by the window-state
+/// plugin denylist (lib.rs) and capabilities/desktop-agent.json.
+pub const WINDOW_LABEL: &str = "desktop-agent";
+
+/// Berd's main window label (the settings deep-link target). lib.rs uses
+/// the string literal throughout; this module names it once.
+const MAIN_WINDOW_LABEL: &str = "main";
+
+/// Webview entry route: src/main.tsx branches on `?window=desktop-agent`.
+const WINDOW_URL: &str = "index.html?window=desktop-agent";
+
+/// Chord currently registered for the panel toggle (None while the panel
+/// is closed). Lets a re-open with a changed binding swap chords, and
+/// keeps the plugin handler honest about which chord is ours.
+static REGISTERED_SHORTCUT: Mutex<Option<Shortcut>> = Mutex::new(None);
+
+/// Global-shortcut plugin for the app builder (lib.rs). Nothing else in
+/// Berd registers through this plugin today (the existing "global
+/// shortcut" feature is the external catch sidecar), but the handler still
+/// checks the chord against the one this module registered so a future
+/// second registrant can't fire the panel toggle by accident.
+pub fn global_shortcut_plugin<R: tauri::Runtime>() -> tauri::plugin::TauriPlugin<R> {
+    tauri_plugin_global_shortcut::Builder::new()
+        .with_handler(|app, shortcut, event| {
+            if event.state() != ShortcutState::Pressed {
+                return;
+            }
+            let is_ours = REGISTERED_SHORTCUT
+                .lock()
+                .map(|registered| registered.as_ref() == Some(shortcut))
+                .unwrap_or(false);
+            if is_ours {
+                let _ = app.emit_to(WINDOW_LABEL, "desktop-agent:toggle-panel", ());
+            }
+        })
+        .build()
+}
+
+/// Settings deep-link from the panel's custom webview menu. Settings live
+/// in the MAIN window: reveal + focus it first (it may be hidden or buried — the
+/// panel is always-on-top, the main window is not), then tell its webview
+/// to open the Behavior settings section. The bridge listens (it is the
+/// desktop-agent presence in the main webview).
+#[tauri::command]
+pub fn desktop_agent_open_settings(app: AppHandle) -> Result<(), String> {
+    if let Some(window) = app.get_webview_window(MAIN_WINDOW_LABEL) {
+        let _ = window.show();
+        let _ = window.set_focus();
+    }
+    app.emit_to(MAIN_WINDOW_LABEL, "desktop-agent:open-settings", ())
+        .map_err(|e| e.to_string())
+}
+
+/// Opens the panel window (idempotent) and keeps the toggle chord
+/// registered. Window flags match the prototype's panel window entry; the
+/// NSPanel swizzle + flags land on the main thread before first paint.
+///
+/// The window is ALWAYS built hidden: a visible-at-build window
+/// flashes as a white square at the OS default position — the webview
+/// paints white until its first transparent paint, and the persisted
+/// avatar position only lands after the webview restores it. The webview
+/// itself reveals the panel via its first set_state once restore has
+/// painted.
+#[tauri::command]
+pub fn desktop_agent_open(app: AppHandle, shortcut: String) -> Result<(), String> {
+    if app.get_webview_window(WINDOW_LABEL).is_none() {
+        let window =
+            WebviewWindowBuilder::new(&app, WINDOW_LABEL, WebviewUrl::App(WINDOW_URL.into()))
+                .title("Berd Desktop Agent")
+                .inner_size(94.0, 94.0)
+                .decorations(false)
+                .transparent(true)
+                .shadow(false)
+                .resizable(false)
+                .always_on_top(true)
+                .visible_on_all_workspaces(true)
+                .skip_taskbar(true)
+                .accept_first_mouse(true)
+                // ALWAYS hidden at build: the reveal happens at
+                // the webview's first set_state after position restore —
+                // never here, where the webview is an unpainted white
+                // rect at the OS default position.
+                .visible(false)
+                .build()
+                .map_err(|e| format!("failed to create desktop-agent window: {e}"))?;
+
+        let panel_window = window.clone();
+        main_thread::on_main(&app, move || {
+            panel::install(&panel_window).map_err(|e| e.to_string())
+        })??;
+    }
+
+    register_toggle_shortcut(&app, &shortcut);
+    Ok(())
+}
+
+/// Destroys the panel window and releases the toggle chord (setting
+/// disable). Chat state is server-side: a later open re-adopts it.
+#[tauri::command]
+pub fn desktop_agent_close(app: AppHandle) -> Result<(), String> {
+    unregister_toggle_shortcut(&app);
+    // Perch teardown BEFORE the window is destroyed: stops the targeting
+    // and follow loops (whose next tick would otherwise touch the dying
+    // window), hides both overlays, releases the AX element.
+    perch::teardown(&app);
+    // Un-swizzle IMMEDIATELY before destroy (the first live disable
+    // crashed) — restores tao's original window class so teardown and
+    // the eventual dealloc run the chain the window was built with.
+    panel::prepare_destroy(&app);
+    if let Some(window) = app.get_webview_window(WINDOW_LABEL) {
+        window.destroy().map_err(|e| e.to_string())?;
+    }
+    Ok(())
+}
+
+/// Native performWindowDrag handoff for the avatar (the webview mousedown
+/// has already preventDefault-ed).
+#[tauri::command]
+pub fn desktop_agent_start_drag(app: AppHandle) -> Result<(), String> {
+    panel::start_drag(&app).map_err(|e| e.to_string())
+}
+
+/// The shortcuts registry stores web-style chords ("alt+meta+b", where
+/// meta = Command). The global-shortcut parser wants "super" for that
+/// modifier; normalize so the registry format works unchanged.
+fn normalize_chord(chord: &str) -> String {
+    chord
+        .split('+')
+        .map(|token| match token.trim().to_ascii_lowercase().as_str() {
+            "meta" => "super".to_string(),
+            other => other.to_string(),
+        })
+        .collect::<Vec<_>>()
+        .join("+")
+}
+
+fn register_toggle_shortcut(app: &AppHandle, chord: &str) {
+    let parsed: Shortcut = match normalize_chord(chord).parse() {
+        Ok(parsed) => parsed,
+        Err(error) => {
+            log::warn!("desktop-agent: unparseable toggle chord {chord:?}: {error}");
+            // Release any previously registered chord (review Check 3):
+            // an unparseable rebind (e.g. a cleared binding arriving as
+            // "") must not leave the OLD chord registered with the OS
+            // while settings show something else.
+            unregister_toggle_shortcut(app);
+            return;
+        }
+    };
+    let Ok(mut registered) = REGISTERED_SHORTCUT.lock() else {
+        log::warn!("desktop-agent: toggle chord state lock poisoned");
+        return;
+    };
+    if *registered == Some(parsed) {
+        return;
+    }
+    if let Some(previous) = registered.take() {
+        if let Err(error) = app.global_shortcut().unregister(previous) {
+            log::warn!("desktop-agent: failed to unregister previous toggle chord: {error}");
+        }
+    }
+    match app.global_shortcut().register(parsed) {
+        Ok(()) => *registered = Some(parsed),
+        Err(error) => {
+            // Log-and-continue: the chord may be held by another app; the
+            // panel still works without a shortcut, and users can rebind
+            // in Berd's shortcut settings.
+            log::warn!("desktop-agent: could not register toggle chord {chord:?}: {error}");
+        }
+    }
+}
+
+fn unregister_toggle_shortcut(app: &AppHandle) {
+    let Ok(mut registered) = REGISTERED_SHORTCUT.lock() else {
+        return;
+    };
+    if let Some(previous) = registered.take() {
+        if let Err(error) = app.global_shortcut().unregister(previous) {
+            log::warn!("desktop-agent: failed to unregister toggle chord: {error}");
+        }
+    }
+}
diff --git a/src-tauri/src/desktop_agent/overlay_panel.rs b/src-tauri/src/desktop_agent/overlay_panel.rs
new file mode 100644
index 000000000..cf78a1f92
--- /dev/null
+++ b/src-tauri/src/desktop_agent/overlay_panel.rs
@@ -0,0 +1,149 @@
+//! Shared factory for the perch overlay NSPanels — the targeting
+//! highlight band and the settled perch outline share one creation path
+//! (they had grown near-identical blocks in the prototype). Both overlays
+//! use one profile: borderless, non-activating, status level, joins all
+//! Spaces (fullscreen-auxiliary), transparent, shadowless,
+//! mouse-transparent, never released on close.
+//!
+//! These are plain AppKit objects, NOT tauri windows: created lazily,
+//! hidden via orderOut, and never destroyed. Experiment disable hides
+//! them (perch::teardown) rather than tearing them down — two tiny
+//! borderless panels; revisit only if enable/disable cycling shows leaks.
+//!
+//! Main thread only (AppKit rule).
+
+use std::ffi::CString;
+
+use objc2::msg_send;
+use objc2::runtime::{AnyClass, AnyObject, Bool};
+use objc2_foundation::{NSPoint, NSRect, NSSize};
+
+const NS_BORDERLESS: usize = 0;
+const NS_NONACTIVATING_PANEL_MASK: usize = 1 << 7;
+const NS_STATUS_WINDOW_LEVEL: isize = 25;
+const CAN_JOIN_ALL_SPACES: usize = 1 << 0;
+const FULLSCREEN_AUXILIARY: usize = 1 << 8;
+const NS_BACKING_BUFFERED: usize = 2;
+
+pub(super) enum OverlayColor {
+    /// systemYellow — the transient targeting highlight.
+    Yellow,
+    /// lightGray — the settled perch outline. The resting border should
+    /// recede, not shout; yellow stays the transient affordance color.
+    LightGray,
+}
+
+pub(super) enum OverlayAppearance {
+    /// Stroke outline (the perch outline). `alpha` < 1.0 makes the
+    /// border translucent.
+    Stroke {
+        width: f64,
+        radius: f64,
+        color: OverlayColor,
+        alpha: f64,
+    },
+    /// Translucent fill (the targeting highlight band). The band sits on
+    /// the TOP region of the target window, so only its top corners are
+    /// rounded (`top_radius`) to match the window's own corners.
+    Fill {
+        color: OverlayColor,
+        alpha: f64,
+        top_radius: f64,
+    },
+}
+
+unsafe fn ns_color(cls: &AnyClass, color: &OverlayColor, alpha: f64) -> *mut AnyObject {
+    let base: *mut AnyObject = match color {
+        OverlayColor::Yellow => msg_send![cls, systemYellowColor],
+        OverlayColor::LightGray => msg_send![cls, lightGrayColor],
+    };
+    if alpha >= 1.0 {
+        return base;
+    }
+    msg_send![&*base, colorWithAlphaComponent: alpha]
+}
+
+/// Creates a configured overlay panel (always mouse-transparent — both
+/// overlays are pure indication, never interaction). Caller owns
+/// showing/hiding/frame.
+///
+/// # Safety
+/// Main thread only. The returned pointer is a +1 retained NSPanel with
+/// `releasedWhenClosed:NO`; per the module header it is cached for the
+/// process lifetime and never released.
+pub(super) unsafe fn create_overlay_panel(appearance: &OverlayAppearance) -> *mut AnyObject {
+    let cls = AnyClass::get(&CString::new("NSPanel").unwrap()).unwrap();
+    let panel: *mut AnyObject = msg_send![cls, alloc];
+    let frame = NSRect::new(NSPoint::new(0.0, 0.0), NSSize::new(10.0, 10.0));
+    let style = NS_BORDERLESS | NS_NONACTIVATING_PANEL_MASK;
+    let panel: *mut AnyObject = msg_send![
+        panel,
+        initWithContentRect: frame,
+        styleMask: style,
+        backing: NS_BACKING_BUFFERED,
+        defer: Bool::NO
+    ];
+    let _: () = msg_send![&mut *panel, setLevel: NS_STATUS_WINDOW_LEVEL];
+    let _: () =
+        msg_send![&mut *panel, setCollectionBehavior: CAN_JOIN_ALL_SPACES | FULLSCREEN_AUXILIARY];
+    let _: () = msg_send![&mut *panel, setOpaque: Bool::NO];
+    let _: () = msg_send![&mut *panel, setHasShadow: Bool::NO];
+    let _: () = msg_send![&mut *panel, setHidesOnDeactivate: Bool::NO];
+    let _: () = msg_send![&mut *panel, setReleasedWhenClosed: Bool::NO];
+    let _: () = msg_send![&mut *panel, setIgnoresMouseEvents: Bool::YES];
+
+    let color_cls = AnyClass::get(&CString::new("NSColor").unwrap()).unwrap();
+    match appearance {
+        OverlayAppearance::Stroke {
+            width,
+            radius,
+            color,
+            alpha,
+        } => {
+            let clear: *mut AnyObject = msg_send![color_cls, clearColor];
+            let _: () = msg_send![&mut *panel, setBackgroundColor: &*clear];
+            let content: *mut AnyObject = msg_send![&*panel, contentView];
+            if !content.is_null() {
+                let _: () = msg_send![&mut *content, setWantsLayer: Bool::YES];
+                let layer: *mut AnyObject = msg_send![&*content, layer];
+                if !layer.is_null() {
+                    let _: () = msg_send![&mut *layer, setBorderWidth: *width];
+                    let _: () = msg_send![&mut *layer, setCornerRadius: *radius];
+                    let stroke = ns_color(color_cls, color, *alpha);
+                    let cg: *mut AnyObject = msg_send![&*stroke, CGColor];
+                    let _: () = msg_send![&mut *layer, setBorderColor: &*cg];
+                }
+            }
+        }
+        OverlayAppearance::Fill {
+            color,
+            alpha,
+            top_radius,
+        } => {
+            // Layer-backed fill with rounded TOP corners: the window
+            // background stays clear and the content-view layer paints
+            // the band, because an NSWindow background cannot be
+            // corner-masked.
+            let clear: *mut AnyObject = msg_send![color_cls, clearColor];
+            let _: () = msg_send![&mut *panel, setBackgroundColor: &*clear];
+            let content: *mut AnyObject = msg_send![&*panel, contentView];
+            if !content.is_null() {
+                let _: () = msg_send![&mut *content, setWantsLayer: Bool::YES];
+                let layer: *mut AnyObject = msg_send![&*content, layer];
+                if !layer.is_null() {
+                    let fill = ns_color(color_cls, color, *alpha);
+                    let cg: *mut AnyObject = msg_send![&*fill, CGColor];
+                    let _: () = msg_send![&mut *layer, setBackgroundColor: &*cg];
+                    let _: () = msg_send![&mut *layer, setCornerRadius: *top_radius];
+                    let _: () = msg_send![&mut *layer, setMasksToBounds: Bool::YES];
+                    // Top corners only. The content view is NOT flipped, so
+                    // the layer's MaxY edge is the visual top:
+                    // kCALayerMinXMaxYCorner | kCALayerMaxXMaxYCorner.
+                    let corners: usize = (1 << 2) | (1 << 3);
+                    let _: () = msg_send![&mut *layer, setMaskedCorners: corners];
+                }
+            }
+        }
+    }
+    panel
+}
diff --git a/src-tauri/src/desktop_agent/panel.rs b/src-tauri/src/desktop_agent/panel.rs
new file mode 100644
index 000000000..7324397e0
--- /dev/null
+++ b/src-tauri/src/desktop_agent/panel.rs
@@ -0,0 +1,293 @@
+//! Panel foundation for the desktop agent: swizzles the panel window into
+//! a non-activating NSPanel (via tauri-nspanel) and installs a runtime
+//! subclass with the panel behaviors:
+//!
+//! - `canBecomeKeyWindow` gated on an "expanded" flag (collapsed avatar is
+//!   never key; expanded popover may become key WITHOUT activating the app)
+//! - key-status changes pushed to the webview as `desktop-agent:key-status`
+//!   events (the click-outside-collapse signal)
+//! - status window level, canJoinAllSpaces + fullScreenAuxiliary
+//!
+//! House rules:
+//! - every AppKit touch happens on the main thread (`run_on_main_thread`)
+//! - NSApplication::sharedApplication, never a fictional NSApp class
+//!
+//! Note: the subclass uses objc2's runtime `ClassBuilder` rather than
+//! `define_class!` — the panel class must extend tauri-nspanel's
+//! `RawNSPanel`, which is only known at runtime, so the static macro
+//! cannot name it.
+
+use std::cell::Cell;
+use std::ffi::CString;
+use std::ptr::NonNull;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::OnceLock;
+
+use objc2::runtime::{AnyClass, AnyObject, Bool, ClassBuilder, Sel};
+use objc2::{msg_send, sel};
+use tauri::{AppHandle, Emitter, Manager, WebviewWindow};
+
+const SUBCLASS_NAME: &str = "BerdDesktopAgentPanel";
+const PLUGIN_PANEL_CLASS: &str = "RawNSPanel";
+
+const NS_NONACTIVATING_PANEL_MASK: usize = 1 << 7;
+const NS_BORDERLESS_MASK: usize = 0;
+const NS_STATUS_WINDOW_LEVEL: isize = 25;
+const CAN_JOIN_ALL_SPACES: usize = 1 << 0;
+const FULLSCREEN_AUXILIARY: usize = 1 << 8;
+
+/// Expanded flag read by the subclass's canBecomeKeyWindow override. A
+/// process-global is acceptable: there is exactly one avatar panel.
+static EXPANDED: AtomicBool = AtomicBool::new(false);
+
+/// tao's original NSWindow class, captured in install() BEFORE any
+/// swizzle so prepare_destroy() can restore it (see that function for
+/// the teardown-crash story). Class pointers are 'static; usize keeps
+/// the static plain. One panel, so one slot.
+static ORIGINAL_CLASS: AtomicUsize = AtomicUsize::new(0);
+
+/// AppHandle for pushing key-status events from the ObjC overrides.
+static APP_HANDLE: OnceLock<AppHandle> = OnceLock::new();
+
+thread_local! {
+    /// Re-entrancy guard: super calls from the overrides must not re-emit.
+    static IN_KEY_HOOK: Cell<bool> = const { Cell::new(false) };
+}
+
+fn emit_key_status(is_key: bool) {
+    if let Some(app) = APP_HANDLE.get() {
+        let _ = app.emit("desktop-agent:key-status", is_key);
+    }
+}
+
+extern "C" fn can_become_key_window(_this: *mut AnyObject, _cmd: Sel) -> Bool {
+    Bool::new(EXPANDED.load(Ordering::Relaxed))
+}
+
+extern "C" fn can_become_main_window(_this: *mut AnyObject, _cmd: Sel) -> Bool {
+    Bool::NO
+}
+
+extern "C" fn become_key_window(this: *mut AnyObject, _cmd: Sel) {
+    unsafe {
+        let superclass = AnyClass::get(&CString::new(PLUGIN_PANEL_CLASS).unwrap())
+            .expect("plugin panel class registered");
+        let this_ref = &mut *this;
+        let _: () = msg_send![super(this_ref, superclass), becomeKeyWindow];
+    }
+    IN_KEY_HOOK.with(|guard| {
+        if !guard.get() {
+            guard.set(true);
+            emit_key_status(true);
+            guard.set(false);
+        }
+    });
+}
+
+extern "C" fn resign_key_window(this: *mut AnyObject, _cmd: Sel) {
+    unsafe {
+        let superclass = AnyClass::get(&CString::new(PLUGIN_PANEL_CLASS).unwrap())
+            .expect("plugin panel class registered");
+        let this_ref = &mut *this;
+        let _: () = msg_send![super(this_ref, superclass), resignKeyWindow];
+    }
+    IN_KEY_HOOK.with(|guard| {
+        if !guard.get() {
+            guard.set(true);
+            emit_key_status(false);
+            guard.set(false);
+        }
+    });
+}
+
+fn subclass() -> &'static AnyClass {
+    static CLASS: OnceLock<&'static AnyClass> = OnceLock::new();
+    CLASS.get_or_init(|| {
+        let superclass = AnyClass::get(&CString::new(PLUGIN_PANEL_CLASS).unwrap())
+            .expect("tauri-nspanel must have registered RawNSPanel before subclassing");
+        let mut builder = ClassBuilder::new(&CString::new(SUBCLASS_NAME).unwrap(), superclass)
+            .expect("BerdDesktopAgentPanel class name must be unique");
+        unsafe {
+            builder.add_method(
+                sel!(canBecomeKeyWindow),
+                can_become_key_window as extern "C" fn(_, _) -> _,
+            );
+            builder.add_method(
+                sel!(canBecomeMainWindow),
+                can_become_main_window as extern "C" fn(_, _) -> _,
+            );
+            builder.add_method(
+                sel!(becomeKeyWindow),
+                become_key_window as extern "C" fn(_, _),
+            );
+            builder.add_method(
+                sel!(resignKeyWindow),
+                resign_key_window as extern "C" fn(_, _),
+            );
+        }
+        builder.register()
+    })
+}
+
+/// Observes display connect/disconnect/rearrange and tells the webview to
+/// re-clamp the avatar (a disconnected display could otherwise strand the
+/// panel off-screen).
+unsafe fn install_screen_observer() {
+    // install() runs on every desktop_agent_open (the panel can be
+    // destroyed and recreated as the experiment toggles); the process-wide
+    // observer must not stack, or every reopen would multiply
+    // screens-changed emissions.
+    static OBSERVER_INSTALLED: AtomicBool = AtomicBool::new(false);
+    if OBSERVER_INSTALLED.swap(true, Ordering::SeqCst) {
+        return;
+    }
+    use block2::RcBlock;
+    let center: *mut AnyObject = {
+        let cls = AnyClass::get(&CString::new("NSNotificationCenter").unwrap()).unwrap();
+        msg_send![cls, defaultCenter]
+    };
+    let name =
+        objc2_foundation::NSString::from_str("NSApplicationDidChangeScreenParametersNotification");
+    let block = RcBlock::new(move |_note: *mut AnyObject| {
+        if let Some(app) = APP_HANDLE.get() {
+            let _ = app.emit("desktop-agent:screens-changed", ());
+        }
+    });
+    let _: *mut AnyObject = msg_send![
+        &*center,
+        addObserverForName: &*name,
+        object: std::ptr::null::<AnyObject>(),
+        queue: std::ptr::null::<AnyObject>(),
+        usingBlock: &*block
+    ];
+    // The block must outlive this scope — the notification center holds it
+    // for the process lifetime (observer is never removed by design; the
+    // panel lives as long as the app).
+    std::mem::forget(block);
+}
+
+/// One-time panel setup. Must run on the main thread (callers hop there).
+pub fn install(window: &WebviewWindow) -> tauri::Result<()> {
+    APP_HANDLE.get_or_init(|| window.app_handle().clone());
+
+    // Fresh window: the process-global expanded flag must not leak the
+    // previous panel's expanded state across a disable/enable cycle.
+    EXPANDED.store(false, Ordering::Relaxed);
+
+    let ns_window = window.ns_window()? as *mut AnyObject;
+    let panel = NonNull::new(ns_window).expect("ns_window");
+    unsafe {
+        // Teardown prep, BEFORE any swizzle (see prepare_destroy — the
+        // disable crash):
+        // 1. Capture tao's original window class so destroy can restore
+        //    it and the final dealloc runs the chain the window was
+        //    BUILT with — never tauri-nspanel's RawNSPanel dealloc,
+        //    which super-calls NSObject's dealloc DIRECTLY (skipping
+        //    NSWindow's teardown) and corrupts AppKit state.
+        // 2. One compensating retain: the plugin's from_window claims
+        //    ownership of a +1 it was never given (Id::from_retained_ptr
+        //    on tao's own reference) and parks a clone in its
+        //    process-lived store. Without this, tao's release at destroy
+        //    drops the count to 0 MID-close-machinery (dealloc under
+        //    AppKit's feet → NSException at run-loop-cycle end → Rust
+        //    abort). With it, the store's claim is real: the closed husk
+        //    stays alive until the store replaces it on the next open.
+        let original: *const AnyClass = objc2::ffi::object_getClass(panel.as_ptr().cast()).cast();
+        ORIGINAL_CLASS.store(original as usize, Ordering::SeqCst);
+        let _: *mut AnyObject = msg_send![&*panel.as_ptr(), retain];
+    }
+
+    // tauri-nspanel swizzle first (window -> RawNSPanel), then our
+    // subclass on top.
+    use tauri_nspanel::WebviewWindowExt;
+    window
+        .to_panel()
+        .map_err(|e| tauri::Error::Anyhow(anyhow::anyhow!("to_panel failed: {e:?}")))?;
+
+    unsafe {
+        let cls = subclass();
+        // Returns the previous class; we don't need it.
+        let _ = objc2::ffi::object_setClass(panel.as_ptr().cast(), (cls as *const AnyClass).cast());
+        configure(panel.as_ptr());
+        install_screen_observer();
+    }
+    Ok(())
+}
+
+/// Un-swizzles the panel ahead of `window.destroy()` — the teardown half
+/// of install()'s class surgery (first live disable crashed
+/// with SIGABRT, a foreign NSException unwinding through tao's run-loop
+/// observer).
+///
+/// Restoring tao's original class means every later message the dying
+/// window receives — including its eventual dealloc, which fires when
+/// tauri-nspanel's store drops its ShareId on the NEXT open — dispatches
+/// through the implementation the window was created with. Neither the
+/// plugin's broken dealloc nor our subclass stays in the chain. Safe to
+/// call when the window is already gone (no-op). Synchronous main-thread
+/// hop; callers invoke this IMMEDIATELY before destroy.
+pub fn prepare_destroy(app: &AppHandle) {
+    let Some(window) = app.get_webview_window(super::WINDOW_LABEL) else {
+        return;
+    };
+    let Ok(ns_window) = window.ns_window() else {
+        return;
+    };
+    let ptr = ns_window as usize;
+    let _ = super::main_thread::on_main(app, move || unsafe {
+        let original = ORIGINAL_CLASS.load(Ordering::SeqCst);
+        if original != 0 {
+            let _ = objc2::ffi::object_setClass(
+                (ptr as *mut AnyObject).cast(),
+                (original as *const AnyClass).cast(),
+            );
+        }
+    });
+}
+
+/// Applies the panel flags. Main thread only.
+unsafe fn configure(panel: *mut AnyObject) {
+    let panel = &mut *panel;
+    let _: () =
+        msg_send![&mut *panel, setStyleMask: NS_BORDERLESS_MASK | NS_NONACTIVATING_PANEL_MASK];
+    let _: () = msg_send![&mut *panel, setLevel: NS_STATUS_WINDOW_LEVEL];
+    let _: () =
+        msg_send![&mut *panel, setCollectionBehavior: CAN_JOIN_ALL_SPACES | FULLSCREEN_AUXILIARY];
+    let _: () = msg_send![&mut *panel, setBecomesKeyOnlyIfNeeded: Bool::YES];
+    let _: () = msg_send![&mut *panel, setHidesOnDeactivate: Bool::NO];
+    let _: () = msg_send![&mut *panel, setOpaque: Bool::NO];
+    let _: () = msg_send![&mut *panel, setHasShadow: Bool::NO];
+    let _: () = msg_send![&mut *panel, setMovableByWindowBackground: Bool::NO];
+    let _: () = msg_send![&mut *panel, setReleasedWhenClosed: Bool::NO];
+}
+
+/// Updates the expanded flag without touching the panel — used by
+/// window_commands::set_state, which sequences the frame + key changes
+/// itself in one main-thread hop (anti-blink ordering).
+pub fn note_expanded(expanded: bool) {
+    EXPANDED.store(expanded, Ordering::Relaxed);
+}
+
+pub fn is_expanded() -> bool {
+    EXPANDED.load(Ordering::Relaxed)
+}
+
+/// Native performDrag handoff (returns immediately; the run loop stays
+/// live). Invoked from a webview mousedown that has already
+/// preventDefault-ed.
+pub fn start_drag(app: &AppHandle) -> tauri::Result<()> {
+    let window = app
+        .get_webview_window(super::WINDOW_LABEL)
+        .ok_or_else(|| tauri::Error::Anyhow(anyhow::anyhow!("desktop-agent window missing")))?;
+    let ns_window_ptr = window.ns_window()? as usize;
+    app.run_on_main_thread(move || unsafe {
+        let panel = ns_window_ptr as *mut AnyObject;
+        let ns_app_class = AnyClass::get(&CString::new("NSApplication").unwrap()).unwrap();
+        let shared: *mut AnyObject = msg_send![ns_app_class, sharedApplication];
+        let event: *mut AnyObject = msg_send![&*shared, currentEvent];
+        if !event.is_null() {
+            let _: () = msg_send![&mut *panel, performWindowDragWithEvent: &*event];
+        }
+    })?;
+    Ok(())
+}
diff --git a/src-tauri/src/desktop_agent/perch.rs b/src-tauri/src/desktop_agent/perch.rs
new file mode 100644
index 000000000..5dcc194c5
--- /dev/null
+++ b/src-tauri/src/desktop_agent/perch.rs
@@ -0,0 +1,1249 @@
+//! Perch mode: targeting, AX resolve, attach, follow, dismount. The
+//! avatar panel is dragged over another app's window and "seats" on its
+//! title bar; a native follow loop keeps it there; window capture and
+//! artifact-URL extraction ride sends while perched.
+//!
+//! Hard rules carried from the prototype's review history:
+//!
+//! - Type guard on EVERY CF cast (CF objects can't be blindly downcast).
+//!   Enforced through objc2-core-foundation: owned (Copy-rule) returns
+//!   ride `CFRetained<CFType>` (RAII release) and every concrete view
+//!   goes through the crate's CFGetTypeID-checked `downcast_ref` —
+//!   never a hand-rolled pointer cast. AXUIElement has no crate wrapper
+//!   and stays a raw pointer with manual retain/release.
+//! - AX window resolve: FRAME MATCH IS AUTHORITATIVE; title only
+//!   disambiguates multiple frame matches and never vetoes a sole match
+//!   (Chrome decorates AX titles differently from CG titles).
+//! - performDrag returns immediately (async handoff) — drop detection
+//!   happens at webview pointer-up via end_targeting's hit-test.
+//! - AXEnhancedUserInterface set once at perch-on (err -25208 expected
+//!   and ignored); deliberately never unset.
+//! - Follow + highlight stay native: nothing per-move crosses the
+//!   webview. Following is a 100ms main-thread AX reconciliation poll.
+//!
+//! Berd lifecycle deviations from the prototype (whose panel WAS the main
+//! window and lived for the process):
+//! - The panel window is resolved fresh wherever it is needed (never a
+//!   cached NSWindow ptr in a long-lived loop): `desktop_agent_close`
+//!   (experiment disable) can DESTROY the panel mid-perch.
+//! - `teardown` stops both loops, hides both overlays, and releases the
+//!   AX element — called from `desktop_agent_close` BEFORE the window is
+//!   destroyed.
+//! - Events are targeted at the panel webview (`emit_to`), namespaced
+//!   `desktop-agent:*`.
+
+use std::cell::RefCell;
+use std::ffi::{c_void, CString};
+use std::ptr::NonNull;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{mpsc, Mutex};
+use std::time::Duration;
+
+use objc2::msg_send;
+use objc2::runtime::{AnyClass, AnyObject, Bool};
+use objc2_core_foundation::{
+    CFArray, CFBoolean, CFDictionary, CFNumber, CFRetained, CFString, CFType, CGPoint, CGRect,
+    CFURL,
+};
+use objc2_core_graphics::{
+    kCGNullWindowID, CGRectMakeWithDictionaryRepresentation, CGWindowListCopyWindowInfo,
+    CGWindowListOption,
+};
+use objc2_foundation::{NSPoint, NSRect, NSSize};
+use serde::Serialize;
+use tauri::{AppHandle, Emitter, Manager};
+
+use super::coordinate_space as cs;
+use super::main_thread::on_main;
+
+// ---------------------------------------------------------------------------
+// Raw AX FFI. AXUIElement has no objc2 wrapper, so its symbols stay
+// hand-declared and AX element pointers stay raw (retained/released
+// manually, never dereferenced). AXValue IS a plain CF object — it gets
+// a local CF-type shim below so it rides the crate's owned `CFRetained`
+// + CFGetTypeID-checked `downcast_ref` like every other CF type.
+
+#[repr(C)]
+struct AXUIElementOpaque(c_void);
+type AXUIElementRef = *const AXUIElementOpaque;
+
+/// AXValue as a crate-native CF type (the objc2 generators don't cover
+/// HIServices). Mirrors the shape the crate's own `cf_type!` types use:
+/// opaque, unconstructible, `!Send`/`!Sync`.
+#[repr(C)]
+struct AXValue {
+    inner: [u8; 0],
+    _p: core::cell::UnsafeCell<
+        core::marker::PhantomData<(
+            *const core::cell::UnsafeCell<()>,
+            core::marker::PhantomPinned,
+        )>,
+    >,
+}
+
+// SAFETY: AXValue is a CoreFoundation object — CFRetain/CFRelease-safe
+// (Apple documents AXValueRef as a CFTypeRef).
+unsafe impl objc2_core_foundation::Type for AXValue {}
+// SAFETY: AXValueGetTypeID uniquely identifies AXValue instances; this
+// is exactly the contract ConcreteType encodes, and what lets
+// `downcast_ref::<AXValue>` type-guard the cast.
+unsafe impl objc2_core_foundation::ConcreteType for AXValue {
+    fn type_id() -> objc2_core_foundation::CFTypeID {
+        unsafe { AXValueGetTypeID() }
+    }
+}
+
+#[link(name = "ApplicationServices", kind = "framework")]
+extern "C" {
+    fn AXUIElementCreateApplication(pid: i32) -> AXUIElementRef;
+    fn AXUIElementCopyAttributeValue(
+        element: AXUIElementRef,
+        attribute: *const c_void, // CFStringRef
+        value: *mut *const c_void,
+    ) -> i32;
+    fn AXUIElementSetAttributeValue(
+        element: AXUIElementRef,
+        attribute: *const c_void,
+        value: *const c_void,
+    ) -> i32;
+    fn AXValueGetValue(value: &AXValue, value_type: u32, out: *mut c_void) -> bool;
+    fn AXValueGetTypeID() -> objc2_core_foundation::CFTypeID;
+    fn CFRetain(cf: *const c_void) -> *const c_void;
+    fn CFRelease(cf: *const c_void);
+}
+
+const K_AX_VALUE_CGPOINT: u32 = 1;
+const K_AX_VALUE_CGSIZE: u32 = 2;
+
+fn cf_str(s: &str) -> CFRetained<CFString> {
+    CFString::from_str(s)
+}
+
+/// Borrows an untyped CF pointer as `CFType`, tied to its owner's
+/// lifetime (Get rule: the value is owned by `owner` — a dictionary or
+/// array — and must not outlive it). The ONE place a raw CF pointer
+/// becomes a reference; every typed view then goes through the crate's
+/// CFGetTypeID-checked `downcast_ref`.
+///
+/// # Safety
+/// `ptr` must be null or a live CF object owned by `owner`.
+unsafe fn cf_borrow<O: ?Sized>(_owner: &O, ptr: *const c_void) -> Option<&CFType> {
+    NonNull::new(ptr.cast_mut()).map(|p| p.cast::<CFType>().as_ref())
+}
+
+/// AX attribute read. The result is OWNED (+1, Copy rule) — CFRetained
+/// releases it on drop; typed views go through `downcast_ref` (the
+/// type-guard hard rule).
+unsafe fn ax_copy(element: AXUIElementRef, attribute: &str) -> Option<CFRetained<CFType>> {
+    let attr = cf_str(attribute);
+    let mut out: *const c_void = std::ptr::null();
+    let err = AXUIElementCopyAttributeValue(
+        element,
+        CFRetained::as_ptr(&attr).as_ptr() as *const c_void,
+        &mut out,
+    );
+    if err != 0 {
+        return None;
+    }
+    let ptr = NonNull::new(out.cast_mut())?.cast::<CFType>();
+    // SAFETY: the copy succeeded with a non-null object we own (+1).
+    Some(CFRetained::from_raw(ptr))
+}
+
+unsafe fn ax_frame(element: AXUIElementRef) -> Option<cs::Rect> {
+    let pos_ref = ax_copy(element, "AXPosition")?;
+    let size_ref = ax_copy(element, "AXSize")?;
+    // Type guard via the crate-checked downcast (the AXValue shim above
+    // implements ConcreteType over AXValueGetTypeID). CFRetained drops
+    // both owned values on every exit path.
+    let pos = pos_ref.downcast_ref::<AXValue>()?;
+    let size_value = size_ref.downcast_ref::<AXValue>()?;
+    let mut point = CGPoint { x: 0.0, y: 0.0 };
+    let mut size = objc2_core_foundation::CGSize {
+        width: 0.0,
+        height: 0.0,
+    };
+    if !AXValueGetValue(pos, K_AX_VALUE_CGPOINT, &mut point as *mut _ as *mut c_void)
+        || !AXValueGetValue(
+            size_value,
+            K_AX_VALUE_CGSIZE,
+            &mut size as *mut _ as *mut c_void,
+        )
+    {
+        return None;
+    }
+    // AX frames are CG top-left space.
+    Some(cs::Rect::new(point.x, point.y, size.width, size.height))
+}
+
+unsafe fn ax_title(element: AXUIElementRef) -> Option<String> {
+    let title_ref = ax_copy(element, "AXTitle")?;
+    let title = title_ref.downcast_ref::<CFString>()?; // type guard
+    Some(title.to_string())
+}
+
+/// AX attribute as a URL string: CFURL or CFString accepted (Chrome
+/// exposes AXDocument as a string, Safari's AXURL is a CFURL). Both
+/// branches are crate-checked downcasts.
+unsafe fn ax_url(element: AXUIElementRef, attribute: &str) -> Option<String> {
+    let value_ref = ax_copy(element, attribute)?;
+    if let Some(url) = value_ref.downcast_ref::<CFURL>() {
+        // The crate renamed CFURLGetString to a crate-private method;
+        // the deprecated public wrapper is the sanctioned owned
+        // accessor for now.
+        #[allow(deprecated)]
+        let url_string = objc2_core_foundation::CFURLGetString(url)?;
+        return Some(url_string.to_string());
+    }
+    if let Some(s) = value_ref.downcast_ref::<CFString>() {
+        let trimmed = s.to_string().trim().to_string();
+        return if trimmed.is_empty() {
+            None
+        } else {
+            Some(trimmed)
+        };
+    }
+    None // type guard
+}
+
+/// AXChildren as raw element pointers (AX elements have no crate
+/// wrapper): each child is retained beyond the array's lifetime; the BFS
+/// releases them as it visits.
+unsafe fn ax_children(element: AXUIElementRef) -> Vec<AXUIElementRef> {
+    let Some(children_ref) = ax_copy(element, "AXChildren") else {
+        return Vec::new();
+    };
+    let Some(array) = children_ref.downcast_ref::<CFArray>() else {
+        return Vec::new(); // type guard
+    };
+    (0..array.count())
+        .map(|i| array.value_at_index(i) as AXUIElementRef)
+        .filter(|e| !e.is_null())
+        .inspect(|&e| {
+            CFRetain(e as *const c_void);
+        })
+        .collect()
+}
+
+unsafe fn ax_role(element: AXUIElementRef) -> Option<String> {
+    let role_ref = ax_copy(element, "AXRole")?;
+    let role = role_ref.downcast_ref::<CFString>()?; // type guard
+    Some(role.to_string())
+}
+
+unsafe fn ax_bool(element: AXUIElementRef, attribute: &str) -> Option<bool> {
+    let value_ref = ax_copy(element, attribute)?;
+    Some(value_ref.downcast_ref::<CFBoolean>()?.value()) // type guard
+}
+
+// Spiked bounds: the BFS must never make a send feel slow.
+const ARTIFACT_URL_MAX_DEPTH: usize = 20;
+const ARTIFACT_URL_MAX_NODES: usize = 8000;
+const ARTIFACT_URL_MAX_MS: u128 = 150;
+
+/// Frontmost tab's URL from the perched window: AXDocument on the window
+/// element first (Chrome, ~0.1ms, works minimized), else a bounded BFS to
+/// AXWebArea -> AXURL/AXDocument (Safari — needs AXEnhancedUserInterface,
+/// set at perch-on). Every failure is None; a send never blocks on this.
+unsafe fn artifact_url_from(element: AXUIElementRef) -> Option<String> {
+    if let Some(document) = ax_url(element, "AXDocument") {
+        return Some(document);
+    }
+    let started = std::time::Instant::now();
+    let mut queue: std::collections::VecDeque<(AXUIElementRef, usize)> =
+        std::collections::VecDeque::new();
+    // Root is borrowed (caller owns it); children are retained by
+    // ax_children and released as visited.
+    let mut visited = 0usize;
+    let mut found: Option<String> = None;
+    for child in ax_children(element) {
+        queue.push_back((child, 1));
+    }
+    while let Some((node, depth)) = queue.pop_front() {
+        visited += 1;
+        let over_budget =
+            visited > ARTIFACT_URL_MAX_NODES || started.elapsed().as_millis() > ARTIFACT_URL_MAX_MS;
+        if !over_budget && found.is_none() {
+            if ax_role(node).as_deref() == Some("AXWebArea") {
+                found = ax_url(node, "AXURL").or_else(|| ax_url(node, "AXDocument"));
+            } else if depth < ARTIFACT_URL_MAX_DEPTH {
+                for child in ax_children(node) {
+                    queue.push_back((child, depth + 1));
+                }
+            }
+        }
+        // Every dequeued node was retained by ax_children — release it
+        // whether or not we're still searching (leak-free on all exits).
+        CFRelease(node as *const c_void);
+    }
+    found
+}
+
+// ---------------------------------------------------------------------------
+// Window enumeration (CGWindowList — layer 0, own PID excluded)
+
+#[derive(Serialize, Clone, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct PerchableWindow {
+    pub window_id: u32,
+    pub pid: i32,
+    pub app_name: String,
+    pub title: String,
+    /// AppKit global space.
+    #[serde(skip)]
+    pub appkit_frame: cs::Rect,
+}
+
+/// Borrowed dictionary lookup (Get rule: the value is owned by `dict`).
+/// Typed views go through the crate's checked `downcast_ref`.
+fn dict_get<'a>(dict: &'a CFDictionary, key: &str) -> Option<&'a CFType> {
+    let key_cf = cf_str(key);
+    let mut value: *const c_void = std::ptr::null();
+    let found = unsafe {
+        dict.value_if_present(
+            CFRetained::as_ptr(&key_cf).as_ptr() as *const c_void,
+            &mut value,
+        )
+    };
+    if !found {
+        return None;
+    }
+    // SAFETY: value_if_present returned true — `value` is a live CF
+    // object owned by `dict`.
+    unsafe { cf_borrow(dict, value) }
+}
+
+fn dict_i64(dict: &CFDictionary, key: &str) -> Option<i64> {
+    dict_get(dict, key)?.downcast_ref::<CFNumber>()?.as_i64()
+}
+
+fn dict_string(dict: &CFDictionary, key: &str) -> Option<String> {
+    Some(dict_get(dict, key)?.downcast_ref::<CFString>()?.to_string())
+}
+
+/// Enumerates perchable windows (layer 0, on-screen, own PID excluded),
+/// frames converted to AppKit space. Excluding our own PID excludes ALL
+/// Berd windows — main, session windows, and the panel itself: no
+/// self-perch, no captures of the conversation feeding itself.
+/// Main thread only (uses NSScreen).
+unsafe fn perchable_windows() -> Vec<PerchableWindow> {
+    let own_pid = std::process::id() as i64;
+    let screens = cs::screens();
+    // Owned array (Copy rule) — CFRetained releases it on drop.
+    let Some(list) = CGWindowListCopyWindowInfo(
+        CGWindowListOption::OptionOnScreenOnly | CGWindowListOption::ExcludeDesktopElements,
+        kCGNullWindowID,
+    ) else {
+        return Vec::new();
+    };
+    let mut out = Vec::new();
+    for i in 0..list.count() {
+        // Get rule: the item is owned by `list`; borrow + checked downcast.
+        let Some(item) = cf_borrow(&list, list.value_at_index(i)) else {
+            continue;
+        };
+        let Some(dict) = item.downcast_ref::<CFDictionary>() else {
+            continue; // type guard
+        };
+        if dict_i64(dict, "kCGWindowLayer") != Some(0) {
+            continue;
+        }
+        let pid = match dict_i64(dict, "kCGWindowOwnerPID") {
+            Some(pid) if pid != own_pid => pid,
+            _ => continue,
+        };
+        let window_id = match dict_i64(dict, "kCGWindowNumber") {
+            Some(id) => id as u32,
+            None => continue,
+        };
+        let bounds = match dict_get(dict, "kCGWindowBounds")
+            .and_then(|b| b.downcast_ref::<CFDictionary>())
+        {
+            Some(bounds_dict) => {
+                let mut rect = CGRect::default();
+                if !CGRectMakeWithDictionaryRepresentation(Some(bounds_dict), &mut rect) {
+                    continue;
+                }
+                rect
+            }
+            None => continue,
+        };
+        // Tiny windows are chrome/popups, not perch targets.
+        if bounds.size.width < 120.0 || bounds.size.height < 80.0 {
+            continue;
+        }
+        let cg = cs::Rect::new(
+            bounds.origin.x,
+            bounds.origin.y,
+            bounds.size.width,
+            bounds.size.height,
+        );
+        out.push(PerchableWindow {
+            window_id,
+            pid: pid as i32,
+            app_name: dict_string(dict, "kCGWindowOwnerName").unwrap_or_default(),
+            title: dict_string(dict, "kCGWindowName").unwrap_or_default(),
+            appkit_frame: cs::appkit_rect_from_cg(cg, &screens),
+        });
+    }
+    out
+}
+
+// ---------------------------------------------------------------------------
+// AX resolve (frame authoritative; title disambiguates only)
+
+/// Frame-match tolerance for AX window resolution.
+const AX_FRAME_TOLERANCE: f64 = 6.0;
+
+/// Pure matching predicate (extracted for testing): FRAME MATCH IS
+/// AUTHORITATIVE. Title only disambiguates multiple frame matches and
+/// never vetoes a sole match (Chrome decorates AX titles differently from
+/// CG titles). Returns the index of the chosen candidate.
+pub(crate) fn choose_ax_match(
+    candidate_frames: &[(cs::Rect, Option<String>)],
+    target_frame: cs::Rect,
+    target_title: &str,
+) -> Option<usize> {
+    let frame_matches: Vec<usize> = candidate_frames
+        .iter()
+        .enumerate()
+        .filter(|(_, (frame, _))| {
+            (frame.x - target_frame.x).abs() <= AX_FRAME_TOLERANCE
+                && (frame.y - target_frame.y).abs() <= AX_FRAME_TOLERANCE
+                && (frame.width - target_frame.width).abs() <= AX_FRAME_TOLERANCE
+                && (frame.height - target_frame.height).abs() <= AX_FRAME_TOLERANCE
+        })
+        .map(|(i, _)| i)
+        .collect();
+    match frame_matches.len() {
+        0 => None,
+        1 => Some(frame_matches[0]), // sole frame match wins; title never vetoes
+        _ => frame_matches
+            .iter()
+            .find(|&&i| {
+                // Both sides trimmed before comparing.
+                candidate_frames[i].1.as_deref().map(str::trim) == Some(target_title.trim())
+            })
+            .copied()
+            .or(Some(frame_matches[0])),
+    }
+}
+
+unsafe fn resolve_ax_window(target: &PerchableWindow) -> Option<AXUIElementRef> {
+    let app = AXUIElementCreateApplication(target.pid);
+    if app.is_null() {
+        return None;
+    }
+    // Single exit below releases `app` on EVERY path.
+    let result = (|| {
+        // Owned (Copy rule) — drops at closure end, AFTER the chosen
+        // element is retained.
+        let windows_ref = ax_copy(app, "AXWindows")?;
+        let array = windows_ref.downcast_ref::<CFArray>()?; // type guard
+        let screens = cs::screens();
+        // AX frames are CG top-left; compare in CG space.
+        let target_ax = cs::cg_rect_from_appkit(target.appkit_frame, &screens);
+
+        let mut elements: Vec<AXUIElementRef> = Vec::new();
+        let mut candidates: Vec<(cs::Rect, Option<String>)> = Vec::new();
+        for i in 0..array.count() {
+            let element = array.value_at_index(i) as AXUIElementRef;
+            if element.is_null() {
+                continue;
+            }
+            if let Some(frame) = ax_frame(element) {
+                elements.push(element);
+                candidates.push((frame, ax_title(element)));
+            }
+        }
+        let chosen = choose_ax_match(&candidates, target_ax, &target.title).map(|i| elements[i]);
+        // Retain the chosen element beyond the array's lifetime.
+        chosen.inspect(|&e| {
+            CFRetain(e as *const c_void);
+        })
+    })();
+    CFRelease(app as *const c_void);
+    result
+}
+
+// ---------------------------------------------------------------------------
+// Perch state + overlay panels
+
+struct PerchedState {
+    element: AXUIElementRef,
+    window_id: u32,
+    app_name: String,
+    title: String,
+    offset_ratio: f64,
+    overlap: f64,
+}
+
+thread_local! {
+    static PERCHED: RefCell<Option<PerchedState>> = const { RefCell::new(None) };
+    static HIGHLIGHT_PANEL: RefCell<Option<usize>> = const { RefCell::new(None) };
+    static OUTLINE_PANEL: RefCell<Option<usize>> = const { RefCell::new(None) };
+    static TARGET_CANDIDATES: RefCell<Vec<PerchableWindow>> = const { RefCell::new(Vec::new()) };
+}
+
+static TARGETING: AtomicBool = AtomicBool::new(false);
+static FOLLOWING: AtomicBool = AtomicBool::new(false);
+static LAST_WINDOW_FRAME: Mutex<Option<cs::Rect>> = Mutex::new(None);
+
+const TITLE_BAR_HEIGHT: f64 = 40.0;
+
+/// Corner radius for the targeting highlight band's TOP corners, matching
+/// the top corners of the macOS window it sits on. Hardcoded: AppKit does
+/// not expose a window's corner radius — ~16pt matches macOS 26 windows.
+const HIGHLIGHT_TOP_CORNER_RADIUS: f64 = 16.0;
+
+/// Matches the panel's inner_size (mod.rs) — the seat math needs the
+/// avatar footprint, not the live NSWindow frame (which the webview may
+/// have expanded into the popover).
+const AVATAR_SIZE: f64 = 94.0;
+
+/// The panel's NSWindow, resolved FRESH — never cache across awaits or
+/// loop ticks: `desktop_agent_close` can destroy the window mid-perch.
+fn panel_ns_window(app: &AppHandle) -> Option<usize> {
+    app.get_webview_window(super::WINDOW_LABEL)
+        .and_then(|w| w.ns_window().ok())
+        .map(|p| p as usize)
+}
+
+unsafe fn ensure_highlight_panel() -> *mut AnyObject {
+    let existing = HIGHLIGHT_PANEL.with(|p| *p.borrow());
+    if let Some(ptr) = existing {
+        return ptr as *mut AnyObject;
+    }
+    let panel = super::overlay_panel::create_overlay_panel(
+        &super::overlay_panel::OverlayAppearance::Fill {
+            color: super::overlay_panel::OverlayColor::Yellow,
+            alpha: 0.35,
+            top_radius: HIGHLIGHT_TOP_CORNER_RADIUS,
+        },
+    );
+    HIGHLIGHT_PANEL.with(|p| *p.borrow_mut() = Some(panel as usize));
+    panel
+}
+
+unsafe fn hide_highlight() {
+    let existing = HIGHLIGHT_PANEL.with(|p| *p.borrow());
+    if let Some(ptr) = existing {
+        let panel = ptr as *mut AnyObject;
+        let _: () = msg_send![&mut *panel, orderOut: std::ptr::null::<AnyObject>()];
+    }
+}
+
+unsafe fn mouse_location() -> cs::Rect {
+    let cls = AnyClass::get(&CString::new("NSEvent").unwrap()).unwrap();
+    let point: NSPoint = msg_send![cls, mouseLocation];
+    cs::Rect::new(point.x, point.y, 0.0, 0.0)
+}
+
+/// Pure occlusion-aware hit test (extracted for testing). Candidates are
+/// FRONT-TO-BACK (CG list order), each as (title band, full frame). The
+/// first candidate whose title band contains the point wins — but a
+/// candidate whose BODY contains the point OCCLUDES everything behind it,
+/// so the walk stops there (otherwise the walk would match title bars
+/// buried under the stack, highlighting windows nobody could see and
+/// seating perches nobody intended).
+///
+/// Occluders are the layer-0 candidates themselves: floating panels /
+/// chrome (other layers, tiny windows) never occlude here — acceptable,
+/// they're excluded from perching for the same reason.
+pub(crate) fn choose_hit_candidate(
+    bands_and_frames: &[(cs::Rect, cs::Rect)],
+    point: (f64, f64),
+) -> Option<usize> {
+    let (x, y) = point;
+    let contains = |r: &cs::Rect| x >= r.x && x <= r.max_x() && y >= r.y && y <= r.max_y();
+    for (i, (band, frame)) in bands_and_frames.iter().enumerate() {
+        if contains(band) {
+            return Some(i);
+        }
+        if contains(frame) {
+            // The point is on this window's body: every window behind it
+            // is covered at this point. No perch.
+            return None;
+        }
+    }
+    None
+}
+
+/// Hit-test the current mouse location against candidates' title-bar hit
+/// bands (AppKit space), occlusion-aware.
+unsafe fn hit_test_title_bands(candidates: &[PerchableWindow]) -> Option<PerchableWindow> {
+    let mouse = mouse_location();
+    let screens = cs::screens();
+    let bands_and_frames: Vec<(cs::Rect, cs::Rect)> = candidates
+        .iter()
+        .map(|c| {
+            (
+                cs::title_bar_hit_band(c.appkit_frame, TITLE_BAR_HEIGHT, &screens),
+                c.appkit_frame,
+            )
+        })
+        .collect();
+    choose_hit_candidate(&bands_and_frames, (mouse.x, mouse.y)).map(|i| candidates[i].clone())
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+
+/// Starts targeting: snapshots candidates and runs a 10Hz native
+/// highlight loop for the duration of the drag (the run loop stays live
+/// during performDrag).
+#[tauri::command]
+pub fn desktop_agent_perch_begin_targeting(app: AppHandle) -> Result<(), String> {
+    if TARGETING.swap(true, Ordering::Relaxed) {
+        return Ok(());
+    }
+    let app_for_loop = app.clone();
+    on_main(&app, || unsafe {
+        TARGET_CANDIDATES.with(|c| *c.borrow_mut() = perchable_windows());
+    })?;
+    tauri::async_runtime::spawn(async move {
+        while TARGETING.load(Ordering::Relaxed) {
+            let _ = app_for_loop.run_on_main_thread(|| unsafe {
+                let candidates = TARGET_CANDIDATES.with(|c| c.borrow().clone());
+                let panel = ensure_highlight_panel();
+                if let Some(hit) = hit_test_title_bands(&candidates) {
+                    let band = cs::title_bar_band(hit.appkit_frame, TITLE_BAR_HEIGHT);
+                    let rect = NSRect::new(
+                        NSPoint::new(band.x, band.y),
+                        NSSize::new(band.width, band.height),
+                    );
+                    let _: () = msg_send![&mut *panel, setFrame: rect, display: Bool::YES];
+                    let _: () = msg_send![&mut *panel, orderFrontRegardless];
+                } else {
+                    let _: () = msg_send![&mut *panel, orderOut: std::ptr::null::<AnyObject>()];
+                }
+            });
+            tokio::time::sleep(Duration::from_millis(100)).await;
+        }
+    });
+    Ok(())
+}
+
+#[derive(Serialize, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct PerchCandidateDto {
+    pub app_name: String,
+    pub title: String,
+}
+
+/// Ends targeting (pointer-up). Hides the highlight and returns the
+/// candidate under the mouse, if any. The webview then calls perch_on.
+#[tauri::command]
+pub fn desktop_agent_perch_end_targeting(
+    app: AppHandle,
+) -> Result<Option<PerchCandidateDto>, String> {
+    TARGETING.store(false, Ordering::Relaxed);
+    on_main(&app, || unsafe {
+        hide_highlight();
+        let candidates = TARGET_CANDIDATES.with(|c| c.borrow().clone());
+        let hit = hit_test_title_bands(&candidates);
+        if let Some(hit) = hit {
+            // Stash the full candidate for perch_on (avoids re-enumeration).
+            TARGET_CANDIDATES.with(|c| *c.borrow_mut() = vec![hit.clone()]);
+            Some(PerchCandidateDto {
+                app_name: hit.app_name,
+                title: hit.title,
+            })
+        } else {
+            TARGET_CANDIDATES.with(|c| c.borrow_mut().clear());
+            None
+        }
+    })
+}
+
+#[derive(Serialize, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct PerchResultDto {
+    pub app_name: String,
+    pub title: String,
+}
+
+/// Attach path: resolves the AX window, seats the avatar panel on the
+/// title bar at the drop offset (mouse X relative to the window), starts
+/// the follow loop. Seats the panel exactly once.
+fn attach_to_target(
+    app: &AppHandle,
+    target: PerchableWindow,
+    overlap: f64,
+) -> Result<PerchResultDto, String> {
+    let panel_ptr = panel_ns_window(app).ok_or("desktop-agent window missing")?;
+    let app_for_presentation = app.clone();
+
+    let result = on_main(app, move || unsafe {
+        let Some(element) = resolve_ax_window(&target) else {
+            return Err("ax_resolve_failed".to_string());
+        };
+        // Set-once, never unset. -25208 expected (already set / not
+        // settable) and ignored.
+        let app_element = AXUIElementCreateApplication(target.pid);
+        if !app_element.is_null() {
+            let key = cf_str("AXEnhancedUserInterface");
+            let true_ref = objc2_core_foundation::kCFBooleanTrue;
+            let _ = AXUIElementSetAttributeValue(
+                app_element,
+                CFRetained::as_ptr(&key).as_ptr() as *const c_void,
+                true_ref
+                    .map(|b| b as *const _ as *const c_void)
+                    .unwrap_or(std::ptr::null()),
+            );
+            CFRelease(app_element as *const c_void);
+        }
+
+        let window_frame = target.appkit_frame;
+        // Drop offset: mouse X relative to the window.
+        let mouse = mouse_location();
+        let offset_ratio = if window_frame.width > 0.0 {
+            ((mouse.x - window_frame.x) / window_frame.width).clamp(0.0, 1.0)
+        } else {
+            0.5
+        };
+        *LAST_WINDOW_FRAME.lock().unwrap() = Some(window_frame);
+        PERCHED.with(|p| {
+            // Defensive release: PerchedState holds a raw retained
+            // AXUIElementRef with no Drop impl — overwriting a live perch
+            // without releasing the old element leaks it. Correctness
+            // must not depend on every caller dismounting first.
+            if let Some(previous) = p.borrow_mut().take() {
+                CFRelease(previous.element as *const c_void);
+            }
+            *p.borrow_mut() = Some(PerchedState {
+                element,
+                window_id: target.window_id,
+                app_name: target.app_name.clone(),
+                title: target.title.clone(),
+                offset_ratio,
+                overlap,
+            })
+        });
+        apply_perched_presentation(
+            &app_for_presentation,
+            panel_ptr,
+            window_frame,
+            offset_ratio,
+            target.window_id,
+            overlap,
+        );
+        Ok(PerchResultDto {
+            app_name: target.app_name,
+            title: target.title,
+        })
+    })??;
+
+    start_follow_loop(app.clone());
+    Ok(result)
+}
+
+/// TCC gate: the ONLY place an Accessibility prompt can fire, and it is
+/// reachable ONLY from the explicit perch drop gesture (product rule —
+/// never at panel open, never at experiment enable).
+#[tauri::command]
+pub fn desktop_agent_perch_on(
+    app: AppHandle,
+    character_seat: Option<bool>,
+) -> Result<PerchResultDto, String> {
+    if !super::permissions::status().accessibility {
+        // Explanation-first flow is the webview's job; this is the gate.
+        super::permissions::request_accessibility();
+        return Err("accessibility_denied".into());
+    }
+    // Take (not peek) the end_targeting hit — the mailbox is consumed so
+    // a future perch_on can't re-attach to a stale snapshot.
+    let target = on_main(&app, || {
+        TARGET_CANDIDATES.with(|c| {
+            let mut candidates = c.borrow_mut();
+            let first = candidates.first().cloned();
+            candidates.clear();
+            first
+        })
+    })?;
+    let Some(target) = target else {
+        return Err("no perch candidate".to_string());
+    };
+    attach_to_target(
+        &app,
+        target,
+        cs::avatar_perch_overlap(character_seat.unwrap_or(false)),
+    )
+}
+
+/// Seats the avatar panel + outline — the one place presentation
+/// happens. Main thread only.
+///
+/// CONTRACT: callers invoke this while holding a PERCHED borrow (the
+/// follow tick holds borrow_mut). This function MUST NOT touch PERCHED —
+/// everything it needs arrives as parameters. Adding a PERCHED.with(...)
+/// here is a guaranteed RefCell panic on the main thread mid-follow.
+unsafe fn apply_perched_presentation(
+    app: &AppHandle,
+    panel_ptr: usize,
+    window_frame: cs::Rect,
+    offset_ratio: f64,
+    window_id: u32,
+    overlap: f64,
+) {
+    let panel = panel_ptr as *mut AnyObject;
+    show_outline(window_frame, window_id);
+    if super::panel::is_expanded() {
+        let _ = app.emit_to(super::WINDOW_LABEL, "desktop-agent:perch-moved", ());
+        return;
+    }
+    let seat = cs::perch_frame(
+        window_frame,
+        (AVATAR_SIZE, AVATAR_SIZE),
+        offset_ratio,
+        overlap,
+    );
+    // Never clip a monitor edge: a window dragged against the top/side of
+    // a display would otherwise seat the avatar partly offscreen. Full
+    // containment beats seat fidelity; the outline is NOT clamped — it
+    // mirrors the window frame, which may legitimately extend offscreen.
+    let avatar = cs::clamp_within_visible_screens(seat, &cs::screens());
+    let rect = NSRect::new(
+        NSPoint::new(avatar.x, avatar.y),
+        NSSize::new(avatar.width, avatar.height),
+    );
+    let _: () = msg_send![&mut *panel, setFrame: rect, display: Bool::YES];
+    let _: () = msg_send![&mut *panel, orderFrontRegardless];
+}
+
+unsafe fn ensure_outline_panel() -> *mut AnyObject {
+    let existing = OUTLINE_PANEL.with(|p| *p.borrow());
+    if let Some(ptr) = existing {
+        return ptr as *mut AnyObject;
+    }
+    let panel = super::overlay_panel::create_overlay_panel(
+        // 3pt stroke, 9pt radius. Light grey and translucent — the
+        // settled outline should recede, not shout; yellow stays the
+        // transient targeting affordance.
+        &super::overlay_panel::OverlayAppearance::Stroke {
+            width: 3.0,
+            radius: 9.0,
+            color: super::overlay_panel::OverlayColor::LightGray,
+            alpha: 0.55,
+        },
+    );
+    OUTLINE_PANEL.with(|p| *p.borrow_mut() = Some(panel as usize));
+    panel
+}
+
+/// NSWindowOrderingMode::NSWindowAbove.
+const NS_WINDOW_ABOVE: isize = 1;
+/// NSNormalWindowLevel.
+const NS_NORMAL_WINDOW_LEVEL: isize = 0;
+
+unsafe fn show_outline(window_frame: cs::Rect, window_id: u32) {
+    let outline = ensure_outline_panel();
+    let rect = NSRect::new(
+        NSPoint::new(window_frame.x, window_frame.y),
+        NSSize::new(window_frame.width, window_frame.height),
+    );
+    let _: () = msg_send![&mut *outline, setFrame: rect, display: Bool::YES];
+    // Z-order: the outline sits DIRECTLY above the perched window in the
+    // global order — NOT floating over everything. At status level it
+    // drew across windows covering an unfocused perch; at normal level,
+    // ordered relative to the target's window number, whatever occludes
+    // the window occludes the outline too. (The avatar panel stays
+    // always-on-top by design — it is the grabbable affordance.)
+    let _: () = msg_send![&mut *outline, setLevel: NS_NORMAL_WINDOW_LEVEL];
+    let _: () =
+        msg_send![&mut *outline, orderWindow: NS_WINDOW_ABOVE, relativeTo: window_id as isize];
+}
+
+/// Re-asserts the outline's above-the-window ordering without touching
+/// its frame. Called every steady-state follow tick: clicking around
+/// reshuffles the global z-order without any frame change, which would
+/// otherwise leave the outline stranded above (or below) the wrong
+/// neighbors.
+unsafe fn reassert_outline_order(window_id: u32) {
+    let existing = OUTLINE_PANEL.with(|p| *p.borrow());
+    if let Some(ptr) = existing {
+        let outline = ptr as *mut AnyObject;
+        let visible: Bool = msg_send![&*outline, isVisible];
+        if visible.as_bool() {
+            let _: () = msg_send![&mut *outline, orderWindow: NS_WINDOW_ABOVE, relativeTo: window_id as isize];
+        }
+    }
+}
+
+unsafe fn hide_outline() {
+    let existing = OUTLINE_PANEL.with(|p| *p.borrow());
+    if let Some(ptr) = existing {
+        let outline = ptr as *mut AnyObject;
+        let _: () = msg_send![&mut *outline, orderOut: std::ptr::null::<AnyObject>()];
+    }
+}
+
+/// Outcome of one follow tick, decided entirely on the main thread.
+enum TickOutcome {
+    /// AX frame read, panel reseated if the window moved.
+    Followed,
+    /// AX frame read failed (window likely closing) — count toward misses.
+    Miss,
+    /// PERCHED is gone (dismount happened) — stop silently, no event: the
+    /// dismount path already owns the state transition (emitting here
+    /// raced drag-off and teleported the avatar home mid-drag).
+    Dismounted,
+    /// Window minimized: the perch ENDS (product rule — a perch is a
+    /// context grant, and a minimized window is no longer clearly
+    /// indicated on screen; auto-unperching prevents accidental
+    /// screenshot sends). The avatar stays where it was seated.
+    Minimized,
+}
+
+/// 100ms reconciliation poll: AX frame read -> reseat panel on change.
+/// Window gone (AX read fails twice) -> dismount + perch-ended event.
+fn start_follow_loop(app: AppHandle) {
+    if FOLLOWING.swap(true, Ordering::Relaxed) {
+        return;
+    }
+    tauri::async_runtime::spawn(async move {
+        let mut misses = 0u32;
+        while FOLLOWING.load(Ordering::Relaxed) {
+            // ONE main-thread hop per tick: read AX, reseat, and report
+            // the outcome back over a channel.
+            let (tx, rx) = mpsc::channel::<TickOutcome>();
+            let app_for_tick = app.clone();
+            let hop = app.run_on_main_thread(move || {
+                let outcome = unsafe {
+                    // FOLLOWING re-checked INSIDE the hop: a dismount that
+                    // landed between the loop check and this closure must
+                    // not touch the panel or emit anything.
+                    if !FOLLOWING.load(Ordering::Relaxed) {
+                        TickOutcome::Dismounted
+                    } else {
+                        // Resolved per tick, NOT cached across the loop:
+                        // experiment disable destroys the panel window.
+                        let panel_ptr = panel_ns_window(&app_for_tick);
+                        PERCHED.with(|p| {
+                            let mut borrow = p.borrow_mut();
+                            let Some(state) = borrow.as_mut() else {
+                                return TickOutcome::Dismounted;
+                            };
+                            // Minimize ends the perch (product rule):
+                            // AXMinimized is the reliable check — the
+                            // frame read can keep answering for minimized
+                            // windows.
+                            let minimized = ax_bool(state.element, "AXMinimized").unwrap_or(false);
+                            let frame_readable = ax_frame(state.element);
+                            match (minimized, frame_readable) {
+                                (true, _) => TickOutcome::Minimized,
+                                (false, Some(ax_cg_frame)) => {
+                                    let screens = cs::screens();
+                                    let window_frame =
+                                        cs::appkit_rect_from_cg(ax_cg_frame, &screens);
+                                    let previous = *LAST_WINDOW_FRAME.lock().unwrap();
+                                    if previous != Some(window_frame) {
+                                        *LAST_WINDOW_FRAME.lock().unwrap() = Some(window_frame);
+                                        if let Some(panel_ptr) = panel_ptr {
+                                            apply_perched_presentation(
+                                                &app_for_tick,
+                                                panel_ptr,
+                                                window_frame,
+                                                state.offset_ratio,
+                                                state.window_id,
+                                                state.overlap,
+                                            );
+                                        }
+                                    } else {
+                                        // Steady state: no frame change,
+                                        // but clicks reshuffle the global
+                                        // z-order — keep the outline glued
+                                        // directly above its window.
+                                        reassert_outline_order(state.window_id);
+                                    }
+                                    TickOutcome::Followed
+                                }
+                                (false, None) => TickOutcome::Miss,
+                            }
+                        })
+                    }
+                };
+                let _ = tx.send(outcome);
+            });
+            let outcome = if hop.is_ok() {
+                rx.recv_timeout(Duration::from_secs(1))
+                    .unwrap_or(TickOutcome::Miss)
+            } else {
+                TickOutcome::Miss
+            };
+            match outcome {
+                TickOutcome::Followed => misses = 0,
+                TickOutcome::Dismounted => break, // no event — dismount owns it
+                TickOutcome::Minimized => {
+                    // Auto-unperch on minimize: the grant ends, the avatar
+                    // STAYS where it was seated (reason tells the webview
+                    // not to fly it home — a minimize is not a close).
+                    end_perch_internal(&app);
+                    let _ = app.emit_to(
+                        super::WINDOW_LABEL,
+                        "desktop-agent:perch-ended",
+                        "minimized",
+                    );
+                    break;
+                }
+                TickOutcome::Miss => {
+                    misses += 1;
+                    // Window gone: two consecutive misses end the perch
+                    // and notify the webview exactly once.
+                    if misses >= 2 {
+                        end_perch_internal(&app);
+                        let _ = app.emit_to(
+                            super::WINDOW_LABEL,
+                            "desktop-agent:perch-ended",
+                            "windowGone",
+                        );
+                        break;
+                    }
+                }
+            }
+            tokio::time::sleep(Duration::from_millis(100)).await;
+        }
+    });
+}
+
+fn end_perch_internal(app: &AppHandle) {
+    FOLLOWING.store(false, Ordering::Relaxed);
+    let _ = on_main(app, || unsafe {
+        hide_outline(); // the outline never survives the perch (all exit paths)
+        PERCHED.with(|p| {
+            if let Some(state) = p.borrow_mut().take() {
+                CFRelease(state.element as *const c_void);
+            }
+        });
+        *LAST_WINDOW_FRAME.lock().unwrap() = None;
+    });
+}
+
+/// Full perch teardown for `desktop_agent_close` (setting disable):
+/// stops BOTH loops, hides BOTH overlays, releases the AX element. Must
+/// run BEFORE the panel window is destroyed — the follow loop's next tick
+/// re-checks FOLLOWING inside the hop and exits without touching the
+/// dying window. No events: the webview is going away with the window.
+pub fn teardown(app: &AppHandle) {
+    TARGETING.store(false, Ordering::Relaxed);
+    let _ = on_main(app, || unsafe {
+        hide_highlight();
+        TARGET_CANDIDATES.with(|c| c.borrow_mut().clear());
+    });
+    end_perch_internal(app);
+}
+
+/// Dismount: stop following, clear state. The panel stays where it is
+/// (the webview decides whether to return to the saved position —
+/// drag-off leaves it at the drop).
+#[tauri::command]
+pub fn desktop_agent_perch_dismount(app: AppHandle) -> Result<(), String> {
+    end_perch_internal(&app);
+    Ok(())
+}
+
+#[derive(Serialize, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct PerchStatusDto {
+    pub perched: bool,
+    pub app_name: Option<String>,
+    pub title: Option<String>,
+}
+
+/// Dev-reload reconciliation: a webview reload does not end the grant —
+/// the native perch never stopped; the UI re-syncs from this. A full app
+/// relaunch always starts unperched (no persisted perch, by product
+/// ruling — a perch is a context grant and must never re-establish
+/// itself unnoticed). An optional renderer hint updates ONLY an existing
+/// grant's seat; it can never attach a target or request TCC permission.
+#[tauri::command]
+pub fn desktop_agent_perch_status(
+    app: AppHandle,
+    character_seat: Option<bool>,
+) -> Result<PerchStatusDto, String> {
+    let panel_ptr = panel_ns_window(&app);
+    let app_for_presentation = app.clone();
+    on_main(&app, move || {
+        if let Some(character) = character_seat {
+            PERCHED.with(|p| {
+                if let Some(state) = p.borrow_mut().as_mut() {
+                    let overlap = cs::avatar_perch_overlap(character);
+                    if state.overlap == overlap {
+                        return;
+                    }
+                    state.overlap = overlap;
+                    if let (Some(panel), Some(frame)) =
+                        (panel_ptr, *LAST_WINDOW_FRAME.lock().unwrap())
+                    {
+                        unsafe {
+                            apply_perched_presentation(
+                                &app_for_presentation,
+                                panel,
+                                frame,
+                                state.offset_ratio,
+                                state.window_id,
+                                state.overlap,
+                            );
+                        }
+                    }
+                }
+            });
+        }
+        PERCHED.with(|p| {
+            let borrow = p.borrow();
+            match borrow.as_ref() {
+                Some(state) => PerchStatusDto {
+                    perched: true,
+                    app_name: Some(state.app_name.clone()),
+                    title: Some(state.title.clone()),
+                },
+                None => PerchStatusDto {
+                    perched: false,
+                    app_name: None,
+                    title: None,
+                },
+            }
+        })
+    })
+}
+
+/// Window-scoped SCK capture of the perched window: works even when
+/// occluded. Returns None when unperched; errors degrade to text-only
+/// sends in the webview.
+#[tauri::command]
+pub async fn desktop_agent_perch_capture(
+    app: AppHandle,
+) -> Result<Option<super::capture::CaptureDto>, String> {
+    let window_id = on_main(&app, || {
+        PERCHED.with(|p| p.borrow().as_ref().map(|s| s.window_id))
+    })?;
+    let Some(window_id) = window_id else {
+        return Ok(None);
+    };
+    match super::capture::capture_window(window_id).await {
+        Ok(capture) => Ok(Some(capture)),
+        Err(error) => Err(error),
+    }
+}
+
+/// Frontmost tab URL of the perched window, fresh per send (tabs change).
+/// None when unperched; every failure degrades to None — a send never
+/// blocks on this.
+#[tauri::command]
+pub fn desktop_agent_perch_artifact_url(app: AppHandle) -> Result<Option<String>, String> {
+    on_main(&app, || unsafe {
+        PERCHED.with(|p| {
+            p.borrow()
+                .as_ref()
+                .and_then(|state| artifact_url_from(state.element))
+        })
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // choose_ax_match: frame match is authoritative; title only
+    // disambiguates; title never vetoes a sole frame match (the Chrome
+    // lesson).
+
+    fn frame(x: f64) -> cs::Rect {
+        cs::Rect::new(x, 100.0, 800.0, 600.0)
+    }
+
+    #[test]
+    fn sole_frame_match_wins_despite_title_mismatch() {
+        // The Chrome case: CG title is ellipsis-truncated, AX title is
+        // decorated — they never string-match, and must not need to.
+        let candidates = vec![(frame(0.0), Some("Doc — Chrome — Profile".to_string()))];
+        let chosen = choose_ax_match(&candidates, frame(0.0), "Doc — Chr…");
+        assert_eq!(chosen, Some(0));
+    }
+
+    #[test]
+    fn no_frame_match_returns_none() {
+        let candidates = vec![(frame(500.0), Some("Anything".to_string()))];
+        assert_eq!(choose_ax_match(&candidates, frame(0.0), "Anything"), None);
+    }
+
+    #[test]
+    fn title_disambiguates_multiple_frame_matches() {
+        let candidates = vec![
+            (frame(0.0), Some("Wrong".to_string())),
+            (frame(0.0), Some("Right".to_string())),
+        ];
+        assert_eq!(choose_ax_match(&candidates, frame(0.0), "Right"), Some(1));
+    }
+
+    #[test]
+    fn multiple_matches_without_title_match_fall_back_to_first() {
+        let candidates = vec![(frame(0.0), Some("A".to_string())), (frame(0.0), None)];
+        assert_eq!(choose_ax_match(&candidates, frame(0.0), "Z"), Some(0));
+    }
+
+    #[test]
+    fn tolerance_admits_near_matches_and_rejects_beyond() {
+        let near = vec![(cs::Rect::new(5.0, 100.0, 800.0, 600.0), None)];
+        assert_eq!(choose_ax_match(&near, frame(0.0), ""), Some(0));
+        let far = vec![(cs::Rect::new(7.0, 100.0, 800.0, 600.0), None)];
+        assert_eq!(choose_ax_match(&far, frame(0.0), ""), None);
+    }
+
+    // choose_hit_candidate: occlusion-aware title-band hit test.
+    // Candidates front-to-back; a body containing the point occludes
+    // everything behind it. AppKit space: y grows UP, so a window's title
+    // band is at the TOP of its frame (max_y side).
+
+    /// (band, frame) for a window whose frame is (x, y, w, h) with a 24pt
+    /// title band at the top.
+    fn window(x: f64, y: f64, w: f64, h: f64) -> (cs::Rect, cs::Rect) {
+        let f = cs::Rect::new(x, y, w, h);
+        (cs::Rect::new(x, y + h - 24.0, w, 24.0), f)
+    }
+
+    #[test]
+    fn hit_topmost_band_wins() {
+        let stack = vec![
+            window(0.0, 0.0, 800.0, 600.0),
+            window(50.0, 50.0, 800.0, 600.0),
+        ];
+        // Point on the front window's band.
+        assert_eq!(choose_hit_candidate(&stack, (400.0, 588.0)), Some(0));
+    }
+
+    #[test]
+    fn buried_band_under_front_body_is_not_a_hit() {
+        // Back window's band (its top strip) sits under the FRONT
+        // window's body: front spans y 0..600, back's band is at
+        // y ~476..500 within front's x-range. A naive walk skips front
+        // (point not on its band) and matches back — the
+        // invisible-highlight bug this predicate exists to prevent.
+        let front = window(0.0, 0.0, 800.0, 600.0);
+        let back = window(100.0, -100.0, 800.0, 600.0); // band at y 476..500
+        assert_eq!(choose_hit_candidate(&[front, back], (400.0, 490.0)), None);
+    }
+
+    #[test]
+    fn band_visible_beside_front_window_still_hits() {
+        // Same stack, but the point is OUTSIDE the front window's x-range
+        // — the back window's band is genuinely visible there.
+        let front = window(0.0, 0.0, 800.0, 600.0);
+        let back = window(100.0, -100.0, 800.0, 600.0);
+        assert_eq!(
+            choose_hit_candidate(&[front, back], (850.0, 490.0)),
+            Some(1)
+        );
+    }
+
+    #[test]
+    fn point_on_nothing_is_none() {
+        let stack = vec![window(0.0, 0.0, 800.0, 600.0)];
+        assert_eq!(choose_hit_candidate(&stack, (2000.0, 2000.0)), None);
+    }
+
+    #[test]
+    fn empty_candidates_is_none() {
+        assert_eq!(choose_hit_candidate(&[], (10.0, 10.0)), None);
+    }
+}
diff --git a/src-tauri/src/desktop_agent/permissions.rs b/src-tauri/src/desktop_agent/permissions.rs
new file mode 100644
index 000000000..7c96abc6b
--- /dev/null
+++ b/src-tauri/src/desktop_agent/permissions.rs
@@ -0,0 +1,70 @@
+//! TCC permission seams for perch mode — Accessibility (AX window
+//! tracking) and Screen Recording (window capture). ALL checks and
+//! requests route through here so the prompting story stays auditable:
+//! Accessibility prompts fire ONLY from the explicit perch drag gesture
+//! (product rule — never at panel open, never at experiment enable).
+//!
+//! Grants attach to Berd's bundle id + code signature. Dev and release
+//! builds are separate TCC identities, so dev rebuilds may re-ask even
+//! after a release grant — document for QA, don't fight it.
+
+#[derive(Debug, Clone)]
+pub struct PermissionStatus {
+    pub accessibility: bool,
+}
+
+// AX + CG permission APIs, linked directly — the objc2 wrapper crates gate
+// some of these behind features; the raw symbols are stable C API.
+#[link(name = "ApplicationServices", kind = "framework")]
+extern "C" {
+    fn AXIsProcessTrusted() -> bool;
+    fn AXIsProcessTrustedWithOptions(options: *const std::ffi::c_void) -> bool;
+}
+
+#[link(name = "CoreGraphics", kind = "framework")]
+extern "C" {
+    fn CGRequestScreenCaptureAccess() -> bool;
+}
+
+/// Non-prompting Accessibility check. Safe from any thread.
+pub fn status() -> PermissionStatus {
+    unsafe {
+        PermissionStatus {
+            accessibility: AXIsProcessTrusted(),
+        }
+    }
+}
+
+/// Prompts for Accessibility via the system dialog
+/// (kAXTrustedCheckOptionPrompt). The grant takes effect for fresh checks
+/// WITHOUT an app relaunch, but trust is keyed to code identity — debug
+/// rebuilds may re-ask.
+pub fn request_accessibility() -> bool {
+    use objc2_foundation::{ns_string, NSDictionary, NSNumber, NSString};
+    unsafe {
+        let key: &NSString = ns_string!("AXTrustedCheckOptionPrompt");
+        let value = NSNumber::new_bool(true);
+        let options: objc2::rc::Retained<NSDictionary<NSString, NSNumber>> =
+            NSDictionary::from_slices(&[key], &[&*value]);
+        let ptr: *const NSDictionary<NSString, NSNumber> = &*options;
+        AXIsProcessTrustedWithOptions(ptr.cast())
+    }
+}
+
+/// Prompts for Screen Recording (system dialog on the first ask; a
+/// Settings deep-link thereafter — macOS behavior, not ours). Sequoia
+/// adds recurring re-approval prompts: a revocation mid-perch surfaces
+/// as capture failure on the next send, which degrades to text-only —
+/// never a blocked send.
+pub fn request_screen_recording() -> bool {
+    unsafe { CGRequestScreenCaptureAccess() }
+}
+
+#[tauri::command]
+pub fn desktop_agent_request_permission(which: String) -> Result<bool, String> {
+    match which.as_str() {
+        "accessibility" => Ok(request_accessibility()),
+        "screenRecording" => Ok(request_screen_recording()),
+        other => Err(format!("unknown permission: {other}")),
+    }
+}
diff --git a/src-tauri/src/desktop_agent/window_commands.rs b/src-tauri/src/desktop_agent/window_commands.rs
new file mode 100644
index 000000000..08c45d9f8
--- /dev/null
+++ b/src-tauri/src/desktop_agent/window_commands.rs
@@ -0,0 +1,136 @@
+//! Tauri commands backing the TS WindowPort seam (panelState.ts).
+//!
+//! The webview works exclusively in GLOBAL TOP-LEFT coordinates (the
+//! channel contract). Conversions to/from AppKit's bottom-left space happen
+//! here, and only via coordinate_space (the sole flip authority).
+
+use serde::{Deserialize, Serialize};
+
+use super::coordinate_space::{self as cs, Rect};
+use super::panel;
+use objc2::msg_send;
+use objc2::runtime::AnyObject;
+use tauri::{AppHandle, Manager};
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy)]
+pub struct RectDto {
+    pub x: f64,
+    pub y: f64,
+    pub width: f64,
+    pub height: f64,
+}
+
+impl From<Rect> for RectDto {
+    fn from(r: Rect) -> Self {
+        Self {
+            x: r.x,
+            y: r.y,
+            width: r.width,
+            height: r.height,
+        }
+    }
+}
+
+impl From<RectDto> for Rect {
+    fn from(r: RectDto) -> Self {
+        Rect::new(r.x, r.y, r.width, r.height)
+    }
+}
+
+#[derive(Serialize, Debug, Clone, Copy)]
+#[serde(rename_all = "camelCase")]
+pub struct ScreenDto {
+    pub frame: RectDto,
+    pub visible_frame: RectDto,
+    pub is_main: bool,
+}
+
+use super::main_thread::on_main;
+
+fn ns_panel_ptr(app: &AppHandle) -> Result<usize, String> {
+    let window = app
+        .get_webview_window(super::WINDOW_LABEL)
+        .ok_or("desktop-agent window missing")?;
+    window
+        .ns_window()
+        .map(|p| p as usize)
+        .map_err(|e| e.to_string())
+}
+
+/// Screens in global TOP-LEFT coordinates for the webview.
+#[tauri::command]
+pub fn desktop_agent_get_screens(app: AppHandle) -> Result<Vec<ScreenDto>, String> {
+    on_main(&app, || {
+        let screens = cs::screens();
+        screens
+            .iter()
+            .enumerate()
+            .map(|(i, s)| ScreenDto {
+                frame: cs::top_left_rect_from_appkit(s.frame, &screens).into(),
+                visible_frame: cs::top_left_rect_from_appkit(s.visible_frame, &screens).into(),
+                // AppKit convention: the first screen in NSScreen.screens is
+                // the one with the menu bar (the "main" for our purposes).
+                is_main: i == 0,
+            })
+            .collect()
+    })
+}
+
+/// Current panel frame in global TOP-LEFT coordinates.
+#[tauri::command]
+pub fn desktop_agent_get_panel_frame(app: AppHandle) -> Result<RectDto, String> {
+    let ptr = ns_panel_ptr(&app)?;
+    on_main(&app, move || {
+        let screens = cs::screens();
+        let frame: objc2_foundation::NSRect = unsafe {
+            let panel = ptr as *mut AnyObject;
+            msg_send![&*panel, frame]
+        };
+        let appkit = Rect::new(
+            frame.origin.x,
+            frame.origin.y,
+            frame.size.width,
+            frame.size.height,
+        );
+        cs::top_left_rect_from_appkit(appkit, &screens).into()
+    })
+}
+
+/// Atomically resizes the panel and flips key-window eligibility — the
+/// panel setState contract, including the anti-blink ordering: frame first, then
+/// key status, in a single main-thread hop.
+#[tauri::command]
+pub fn desktop_agent_set_state(
+    app: AppHandle,
+    expanded: bool,
+    frame: RectDto,
+) -> Result<(), String> {
+    let ptr = ns_panel_ptr(&app)?;
+    panel::note_expanded(expanded);
+    on_main(&app, move || {
+        let screens = cs::screens();
+        let appkit = cs::appkit_rect_from_top_left(frame.into(), &screens);
+        unsafe {
+            let p = ptr as *mut AnyObject;
+            let ns_rect = objc2_foundation::NSRect::new(
+                objc2_foundation::NSPoint::new(appkit.x, appkit.y),
+                objc2_foundation::NSSize::new(appkit.width, appkit.height),
+            );
+            let _: () = msg_send![&mut *p, setFrame: ns_rect, display: true];
+            if expanded {
+                let _: () = msg_send![&mut *p, makeKeyWindow];
+            } else {
+                let is_key: objc2::runtime::Bool = msg_send![&*p, isKeyWindow];
+                if is_key.as_bool() {
+                    let _: () = msg_send![&mut *p, resignKeyWindow];
+                }
+            }
+            // set_state doubles as the REVEAL for the built-hidden window:
+            // the webview's post-restore setState is the first moment the
+            // panel has both a correct frame and a painted transparent
+            // webview. "Hide agent" destroys the panel now, so there is no
+            // hidden-but-running state for frame updates.
+            let _: () = msg_send![&mut *p, orderFrontRegardless];
+        }
+    })
+}
diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
index 79cdcf904..a988826ac 100644
--- a/src-tauri/src/lib.rs
+++ b/src-tauri/src/lib.rs
@@ -1,5 +1,7 @@
 mod commands;
 mod deep_links;
+#[cfg(target_os = "macos")]
+pub mod desktop_agent;
 mod services;
 mod types;
 
@@ -153,6 +155,7 @@ pub fn run() {
         .plugin(tauri_plugin_notification::init())
         .plugin(
             tauri_plugin_window_state::Builder::default()
+                .with_denylist(&["desktop-agent"])
                 .with_state_flags(StateFlags::all() & !StateFlags::VISIBLE)
                 .build(),
         );
@@ -171,6 +174,15 @@ pub fn run() {
     #[cfg(feature = "berdctl")]
     let builder = builder.plugin(tauri_plugin_berdctl::init());
 
+    // Desktop-agent experiment (macOS only): the global-shortcut plugin is
+    // inert until the settings bridge opens the panel and registers a
+    // chord; the menu handler ignores every id outside the desktop-agent:
+    // namespace (there is no other on_menu_event consumer in the app).
+    #[cfg(target_os = "macos")]
+    let builder = builder
+        .plugin(tauri_nspanel::init())
+        .plugin(desktop_agent::global_shortcut_plugin());
+
     if let Some(mode) = &e2e_mode {
         mode.log_enabled();
     }
@@ -766,6 +778,36 @@ pub fn run() {
             #[cfg(feature = "block-skill-discovery")]
             commands::skill_marketplace::install_remote_skill,
             commands::workspace_context::load_workspace_context,
+            #[cfg(target_os = "macos")]
+            desktop_agent::desktop_agent_open,
+            #[cfg(target_os = "macos")]
+            desktop_agent::desktop_agent_close,
+            #[cfg(target_os = "macos")]
+            desktop_agent::desktop_agent_start_drag,
+            #[cfg(target_os = "macos")]
+            desktop_agent::desktop_agent_open_settings,
+            #[cfg(target_os = "macos")]
+            desktop_agent::window_commands::desktop_agent_get_screens,
+            #[cfg(target_os = "macos")]
+            desktop_agent::window_commands::desktop_agent_get_panel_frame,
+            #[cfg(target_os = "macos")]
+            desktop_agent::window_commands::desktop_agent_set_state,
+            #[cfg(target_os = "macos")]
+            desktop_agent::permissions::desktop_agent_request_permission,
+            #[cfg(target_os = "macos")]
+            desktop_agent::perch::desktop_agent_perch_begin_targeting,
+            #[cfg(target_os = "macos")]
+            desktop_agent::perch::desktop_agent_perch_end_targeting,
+            #[cfg(target_os = "macos")]
+            desktop_agent::perch::desktop_agent_perch_on,
+            #[cfg(target_os = "macos")]
+            desktop_agent::perch::desktop_agent_perch_dismount,
+            #[cfg(target_os = "macos")]
+            desktop_agent::perch::desktop_agent_perch_status,
+            #[cfg(target_os = "macos")]
+            desktop_agent::perch::desktop_agent_perch_capture,
+            #[cfg(target_os = "macos")]
+            desktop_agent::perch::desktop_agent_perch_artifact_url,
         ])
         .build(context)
         .expect("error while building tauri application")
diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json
index ef00b5e22..4db4eb3d4 100644
--- a/src-tauri/tauri.conf.json
+++ b/src-tauri/tauri.conf.json
@@ -14,6 +14,7 @@
     "frontendDist": "../dist"
   },
   "app": {
+    "macOSPrivateApi": true,
     "windows": [
       {
         "title": "Berd",
diff --git a/src/app/App.tsx b/src/app/App.tsx
index 291058817..62b9a5279 100644
--- a/src/app/App.tsx
+++ b/src/app/App.tsx
@@ -5,6 +5,7 @@ import { TopBarActionsProvider } from "@/app/contexts/TopBarActionsContext";
 import { SelectedTextContextMenu } from "@/app/ui/SelectedTextContextMenu";
 import { StartupLoadingView } from "@/app/ui/StartupLoadingView";
 import { useAuthGate } from "@/features/auth/hooks/useAuthGate";
+import { DesktopAgentBridge } from "@/features/desktop-agent/DesktopAgentBridge";
 import { GlobalShortcutBridge } from "@/features/global-shortcut/GlobalShortcutBridge";
 import { LoginView } from "@/features/auth/ui/LoginView";
 import { getBuildFeatureState } from "@/shared/profile/buildProfile";
@@ -48,6 +49,7 @@ export function App() {
     content = (
       <TopBarActionsProvider>
         <GlobalShortcutBridge />
+        <DesktopAgentBridge />
         <AppShell
           authStatus={authGate.authStatus}
           onLoggedOut={authGate.completeLogin}
diff --git a/src/app/lib/rendererDiagnostics.ts b/src/app/lib/rendererDiagnostics.ts
index 5dbc59250..20dd39d8b 100644
--- a/src/app/lib/rendererDiagnostics.ts
+++ b/src/app/lib/rendererDiagnostics.ts
@@ -5,7 +5,7 @@ const SECRET_VALUE_PATTERN =
   /\b(authorization|refresh_token|access_token|secret_key|api_key|apikey|password|secret|token)\b\s*[:=]\s*(['"]?)[^,\s;&'"]+/gi;
 
 interface RendererDiagnosticsContext {
-  windowKind: "main" | "session" | "voice-buddy";
+  windowKind: "main" | "session" | "voice-buddy" | "desktop-agent";
 }
 
 let installed = false;
diff --git a/src/features/desktop-agent/DesktopAgentBridge.test.tsx b/src/features/desktop-agent/DesktopAgentBridge.test.tsx
new file mode 100644
index 000000000..2f43aefd4
--- /dev/null
+++ b/src/features/desktop-agent/DesktopAgentBridge.test.tsx
@@ -0,0 +1,196 @@
+// Bridge tests: Desktop Agent settings -> panel lifecycle commands. Pins the
+// mapping (enable→open,
+// disable→close, chord rebind→re-open) plus the platform/StrictMode
+// guards. Pattern: GlobalShortcutBridge.test.tsx (hoisted invoke mock,
+// real settings/shortcut stores backed by localStorage).
+
+import { act, cleanup, render } from "@testing-library/react";
+import React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { DesktopAgentBridge } from "./DesktopAgentBridge";
+import {
+  DESKTOP_AGENT_ENABLED_STORAGE_KEY,
+  setDesktopAgentEnabled,
+} from "./lib/desktopAgentPreferences";
+import { OPEN_SETTINGS_EVENT } from "@/features/settings/lib/settingsEvents";
+import {
+  setShortcutOverride,
+  SHORTCUT_PREFERENCES_STORAGE_KEY,
+} from "@/features/shortcuts/lib/shortcutRegistry";
+
+const mocks = vi.hoisted(() => ({
+  getPlatform: vi.fn(() => "mac"),
+  invoke: vi.fn(),
+  // Tauri event listeners by name — tests fire them to simulate Rust
+  // emitting at the main webview (the settings deep-link path).
+  listeners: new Map<string, Array<(event: unknown) => void>>(),
+}));
+
+vi.mock("@tauri-apps/api/core", () => ({
+  invoke: (...args: unknown[]) => mocks.invoke(...args),
+}));
+
+vi.mock("@tauri-apps/api/event", () => ({
+  listen: (name: string, handler: (event: unknown) => void) => {
+    const list = mocks.listeners.get(name) ?? [];
+    list.push(handler);
+    mocks.listeners.set(name, list);
+    return Promise.resolve(() => {
+      const current = mocks.listeners.get(name) ?? [];
+      mocks.listeners.set(
+        name,
+        current.filter((h) => h !== handler),
+      );
+    });
+  },
+}));
+
+vi.mock("@/shared/lib/platform", () => ({
+  getPlatform: () => mocks.getPlatform(),
+}));
+
+function callsTo(command: string) {
+  return mocks.invoke.mock.calls.filter(([name]) => name === command);
+}
+
+async function flushAsync() {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.listeners.clear();
+  mocks.getPlatform.mockReturnValue("mac");
+  mocks.invoke.mockImplementation(() => Promise.resolve());
+  window.__TAURI_INTERNALS__ = {};
+  localStorage.removeItem(DESKTOP_AGENT_ENABLED_STORAGE_KEY);
+  localStorage.removeItem(SHORTCUT_PREFERENCES_STORAGE_KEY);
+});
+
+/** Fires a mocked Tauri event at every registered listener (simulates
+ *  Rust emit_to targeting this webview). */
+function fireTauriEvent(name: string, payload?: unknown) {
+  for (const handler of mocks.listeners.get(name) ?? []) {
+    handler({ event: name, payload });
+  }
+}
+
+afterEach(() => {
+  cleanup();
+  delete window.__TAURI_INTERNALS__;
+});
+
+describe("DesktopAgentBridge", () => {
+  it("does nothing while the setting is disabled", async () => {
+    render(<DesktopAgentBridge />);
+    await flushAsync();
+    expect(mocks.invoke).not.toHaveBeenCalled();
+  });
+
+  it("opens the panel with the registry chord when the setting turns on", async () => {
+    render(<DesktopAgentBridge />);
+    await flushAsync();
+    act(() => {
+      setDesktopAgentEnabled(true);
+    });
+    await flushAsync();
+    expect(callsTo("desktop_agent_open")).toEqual([
+      ["desktop_agent_open", { shortcut: "meta+alt+b" }],
+    ]);
+  });
+
+  it("closes the panel when the setting turns off", async () => {
+    render(<DesktopAgentBridge />);
+    act(() => {
+      setDesktopAgentEnabled(true);
+    });
+    await flushAsync();
+    act(() => {
+      setDesktopAgentEnabled(false);
+    });
+    await flushAsync();
+    expect(callsTo("desktop_agent_close")).toHaveLength(1);
+  });
+
+  it("re-opens (re-registering the chord) when the binding changes while enabled", async () => {
+    render(<DesktopAgentBridge />);
+    act(() => {
+      setDesktopAgentEnabled(true);
+    });
+    await flushAsync();
+    act(() => {
+      setShortcutOverride("desktopAgent.togglePanel", "ctrl+alt+d");
+    });
+    await flushAsync();
+    expect(callsTo("desktop_agent_open")).toEqual([
+      ["desktop_agent_open", { shortcut: "meta+alt+b" }],
+      ["desktop_agent_open", { shortcut: "ctrl+alt+d" }],
+    ]);
+  });
+
+  it("no-ops off macOS", async () => {
+    mocks.getPlatform.mockReturnValue("windows");
+    act(() => {
+      setDesktopAgentEnabled(true);
+    });
+    render(<DesktopAgentBridge />);
+    await flushAsync();
+    expect(mocks.invoke).not.toHaveBeenCalled();
+  });
+
+  it("no-ops without the Tauri bridge (plain browser context)", async () => {
+    delete window.__TAURI_INTERNALS__;
+    act(() => {
+      setDesktopAgentEnabled(true);
+    });
+    render(<DesktopAgentBridge />);
+    await flushAsync();
+    expect(mocks.invoke).not.toHaveBeenCalled();
+  });
+
+  it("opens exactly once under StrictMode double-mount with the setting pre-enabled", async () => {
+    act(() => {
+      setDesktopAgentEnabled(true);
+    });
+    render(
+      <React.StrictMode>
+        <DesktopAgentBridge />
+      </React.StrictMode>,
+    );
+    await flushAsync();
+    expect(callsTo("desktop_agent_open")).toHaveLength(1);
+  });
+
+  it("routes the panel's settings deep-link to the Behavior settings section", async () => {
+    const details: unknown[] = [];
+    const onOpenSettings = (event: Event) => {
+      details.push((event as CustomEvent).detail);
+    };
+    window.addEventListener(OPEN_SETTINGS_EVENT, onOpenSettings);
+    try {
+      // Deliberately NOT enabling the setting: the listener is
+      // unconditional (the event can only originate from a live panel,
+      // and gating would add re-registration churn on toggle).
+      render(<DesktopAgentBridge />);
+      await flushAsync();
+      act(() => {
+        fireTauriEvent("desktop-agent:open-settings");
+      });
+      expect(details).toEqual([{ section: "behavior" }]);
+    } finally {
+      window.removeEventListener(OPEN_SETTINGS_EVENT, onOpenSettings);
+    }
+  });
+
+  it("registers no settings listener off macOS", async () => {
+    mocks.getPlatform.mockReturnValue("windows");
+    render(<DesktopAgentBridge />);
+    await flushAsync();
+    expect(
+      mocks.listeners.get("desktop-agent:open-settings") ?? [],
+    ).toHaveLength(0);
+  });
+});
diff --git a/src/features/desktop-agent/DesktopAgentBridge.tsx b/src/features/desktop-agent/DesktopAgentBridge.tsx
new file mode 100644
index 000000000..505af1d34
--- /dev/null
+++ b/src/features/desktop-agent/DesktopAgentBridge.tsx
@@ -0,0 +1,108 @@
+// Settings bridge for the Berd Desktop Agent panel (macOS only).
+//
+// Runs in the MAIN webview and owns the mapping from the Desktop Agent
+// settings (desktopAgentPreferences.ts) to panel lifecycle:
+//
+//   setting off -> on             desktop_agent_open (registers the
+//                                 toggle chord from the shortcuts
+//                                 registry)
+//   toggle chord rebound          desktop_agent_open again (idempotent
+//                                 for the window; re-registers the chord)
+//   setting on -> off             desktop_agent_close (destroy; chat
+//                                 state is server-side and re-adopts on
+//                                 re-enable)
+//
+// Cross-webview coherence: the setting lives in localStorage,
+// which is shared across same-origin webviews — the panel webview writes
+// `enabled` false on "Turn off agent", the storage event lands here, and
+// this bridge closes the panel. The preference hooks/useShortcutBindings
+// are storage-event-driven, so no extra wiring is needed.
+//
+// Deliberately NO unmount cleanup: a main-webview reload must not destroy
+// the panel (open is idempotent and re-runs on mount); disable-close is
+// driven by state, and app quit takes the panel window with the process.
+
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+import { useCallback, useEffect, useRef } from "react";
+
+import { useDesktopAgentEnabledPreference } from "@/features/desktop-agent/lib/desktopAgentPreferences";
+import { requestOpenSettings } from "@/features/settings/lib/settingsEvents";
+import { useShortcutBindings } from "@/features/shortcuts/lib/shortcutRegistry";
+import { getPlatform } from "@/shared/lib/platform";
+
+interface BridgeState {
+  enabled: boolean;
+  chord: string;
+}
+
+export function DesktopAgentBridge() {
+  const isMac = getPlatform() === "mac";
+  const enabled = useDesktopAgentEnabledPreference().enabled;
+  const bindings = useShortcutBindings("desktopAgent.togglePanel");
+
+  // A cleared keybinding must not read as "disabled": open with an empty
+  // chord (Rust logs the unparseable chord and continues without one).
+  const chord = bindings[0]?.shortcut ?? "";
+
+  // Ops are serialized so a rapid toggle can't interleave open/close
+  // (pattern: GlobalShortcutBridge).
+  const operationQueueRef = useRef<Promise<void>>(Promise.resolve());
+  const enqueue = useCallback((operation: () => Promise<void>) => {
+    operationQueueRef.current = operationQueueRef.current
+      .catch(() => undefined)
+      .then(operation)
+      .catch((error) => {
+        console.error("Desktop-agent bridge operation failed:", error);
+      });
+  }, []);
+
+  // Previous applied state; transitions below are diffs against it. Refs
+  // survive StrictMode's simulated remount, and every native op is
+  // idempotent anyway.
+  const appliedRef = useRef<BridgeState>({
+    enabled: false,
+    chord: "",
+  });
+
+  // Settings deep-link from the panel's avatar menu: Rust has already
+  // revealed + focused the main window (the panel is always-on-top, this
+  // window may be hidden); the remaining hop is in-webview navigation to
+  // the Behavior section, which owns the Desktop Agent settings. The
+  // bridge hosts the listener because it IS the desktop-agent presence
+  // in the main webview. Not gated on `enabled`: the event can only
+  // originate from a live panel, and an unconditional listener avoids
+  // re-registration churn on toggle.
+  useEffect(() => {
+    if (!window.__TAURI_INTERNALS__ || !isMac) {
+      return;
+    }
+    const unlisten = listen("desktop-agent:open-settings", () => {
+      requestOpenSettings("behavior");
+    });
+    return () => {
+      void unlisten.then((fn) => fn());
+    };
+  }, [isMac]);
+
+  useEffect(() => {
+    if (!window.__TAURI_INTERNALS__ || !isMac) {
+      return;
+    }
+    const before = appliedRef.current;
+    const next: BridgeState = { enabled, chord };
+    appliedRef.current = next;
+
+    if (enabled) {
+      if (!before.enabled || before.chord !== chord) {
+        enqueue(() => invoke("desktop_agent_open", { shortcut: chord }));
+      }
+      return;
+    }
+    if (before.enabled) {
+      enqueue(() => invoke("desktop_agent_close"));
+    }
+  }, [enabled, chord, isMac, enqueue]);
+
+  return null;
+}
diff --git a/src/features/desktop-agent/hooks/useAgentAvatar.test.tsx b/src/features/desktop-agent/hooks/useAgentAvatar.test.tsx
new file mode 100644
index 000000000..e4da08711
--- /dev/null
+++ b/src/features/desktop-agent/hooks/useAgentAvatar.test.tsx
@@ -0,0 +1,44 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, expect, it, vi } from "vitest";
+
+import { useAgentAvatar } from "@/features/desktop-agent/hooks/useAgentAvatar";
+import { listPersonas } from "@/shared/api/agents";
+import { getCachedAvatarForRef } from "@/shared/api/avatars";
+import type { Persona } from "@/shared/types/agents";
+
+vi.mock("@/shared/api/agents", () => ({ listPersonas: vi.fn() }));
+vi.mock("@/shared/api/avatars", () => ({
+  getCachedAvatarForRef: vi.fn(),
+  cachedAssetToMedia: vi.fn(),
+}));
+const berdy: Persona = {
+  id: "/home/me/.agents/agents/berdy.md",
+  displayName: "Berdy",
+  avatar: "app-avatar:gloopies-22",
+  systemPrompt: "",
+  isBuiltin: true,
+  writable: false,
+  sourceProperties: { metadata: { berdBundled: true } },
+};
+beforeEach(() => {
+  vi.mocked(listPersonas).mockResolvedValue([berdy]);
+  vi.mocked(getCachedAvatarForRef).mockResolvedValue(null);
+});
+it("default and positively identified Berdy qualify; unrelated fallback does not", async () => {
+  const { result, rerender } = renderHook(({ id }) => useAgentAvatar(id), {
+    initialProps: { id: null as string | null },
+  });
+  expect(result.current.isBerdy).toBe(true);
+  rerender({ id: berdy.id });
+  await waitFor(() => expect(result.current.isBerdy).toBe(true));
+  rerender({ id: "unrelated" });
+  expect(result.current.isBerdy).toBe(false);
+  await waitFor(() => expect(listPersonas).toHaveBeenCalledTimes(2));
+  expect(result.current.isBerdy).toBe(false);
+});
+it("fetch failures and lookalike avatars never classify another agent as Berdy", async () => {
+  vi.mocked(listPersonas).mockResolvedValue([{ ...berdy, id: "/other.md" }]);
+  const { result } = renderHook(() => useAgentAvatar("/other.md"));
+  await waitFor(() => expect(getCachedAvatarForRef).toHaveBeenCalled());
+  expect(result.current.isBerdy).toBe(false);
+});
diff --git a/src/features/desktop-agent/hooks/useAgentAvatar.ts b/src/features/desktop-agent/hooks/useAgentAvatar.ts
new file mode 100644
index 000000000..f3c37b036
--- /dev/null
+++ b/src/features/desktop-agent/hooks/useAgentAvatar.ts
@@ -0,0 +1,123 @@
+// Agent avatar resolution: maps the agent driving the NEXT or CURRENT
+// chat to an AvatarChoice. Pending selection wins over the committed
+// session binding (the avatar previews who you're about to talk to); no
+// agent, no catalog asset, or fetch failure all fall back to the default
+// avatar — an avatar miss must never look like an error.
+//
+// In-process integration: personas carry an avatar REF (app-avatar:<id>,
+// user-avatar:<id>, or a remote URL). Catalog refs resolve through Berd's
+// avatar cache (getCachedAvatarForRef → cachedAssetToMedia — the same
+// path the main UI uses), which returns animated video media when the
+// catalog has it. Plain invoke-based, deliberately: the panel webview
+// mounts no React Query client.
+
+import { useEffect, useRef, useState } from "react";
+
+import { findBerdyPersonaId } from "@/features/onboarding/berdyAgent";
+
+import { listPersonas } from "@/shared/api/agents";
+import {
+  cachedAssetToMedia,
+  getCachedAvatarForRef,
+} from "@/shared/api/avatars";
+import { isAppAvatarRef, isUserAvatarRef } from "@/shared/avatars/catalog";
+import { resolveAvatarSrc } from "@/shared/lib/avatarUrl";
+
+import { DEFAULT_AVATAR, type AvatarChoice } from "../lib/avatarState";
+
+async function avatarRefFor(
+  agentId: string,
+): Promise<{ ref: string | null; isBerdy: boolean }> {
+  const personas = await listPersonas();
+  const persona = personas.find((candidate) => candidate.id === agentId);
+  const ref = persona?.avatar;
+  return {
+    ref: typeof ref === "string" && ref.trim().length > 0 ? ref.trim() : null,
+    isBerdy: findBerdyPersonaId(personas) === agentId,
+  };
+}
+
+type AgentAvatar = { choice: AvatarChoice; isBerdy: boolean };
+
+async function choiceFor(agentId: string): Promise<AgentAvatar | null> {
+  const { ref, isBerdy } = await avatarRefFor(agentId);
+  if (ref === null) return null;
+
+  if (isAppAvatarRef(ref) || isUserAvatarRef(ref)) {
+    const cached = await getCachedAvatarForRef({ avatarRef: ref });
+    if (cached === null) return { choice: DEFAULT_AVATAR, isBerdy };
+    const media = cachedAssetToMedia(cached.asset);
+    return {
+      isBerdy,
+      choice: {
+        id: `agent:${agentId}`,
+        label: "Agent",
+        src: media.src,
+        shape: "circle",
+        kind: media.mediaType === "video" ? "video" : "image",
+      },
+    };
+  }
+
+  // Remote URL refs pass through as static images.
+  const direct = resolveAvatarSrc(ref);
+  if (!direct) return null;
+  return {
+    isBerdy: false,
+    choice: {
+      id: `agent:${agentId}`,
+      label: "Agent",
+      src: direct,
+      shape: "circle",
+      kind: "image",
+    },
+  };
+}
+
+export function useAgentAvatar(agentId: string | null): AgentAvatar {
+  // Null is the intentional default/Berdy identity (including a fresh chat),
+  // not an unresolved non-null agent or a missing catalog asset.
+  const fallback = { choice: DEFAULT_AVATAR, isBerdy: agentId === null };
+  const [resolved, setResolved] = useState<{
+    agentId: string | null;
+    value: AgentAvatar;
+  } | null>(null);
+  // Per-agent memo: avatars are static per session; refetching on every
+  // pending/active flip would flash the probe swap needlessly.
+  const cache = useRef(new Map<string, AgentAvatar>());
+
+  useEffect(() => {
+    const setChoice = (value: AgentAvatar) => setResolved({ agentId, value });
+    if (agentId === null) {
+      setChoice({ choice: DEFAULT_AVATAR, isBerdy: agentId === null });
+      return;
+    }
+    const cached = cache.current.get(agentId);
+    if (cached) {
+      setChoice(cached);
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      try {
+        const next = await choiceFor(agentId);
+        if (cancelled) return;
+        if (next === null) {
+          setChoice({ choice: DEFAULT_AVATAR, isBerdy: agentId === null });
+          return;
+        }
+        cache.current.set(agentId, next);
+        setChoice(next);
+      } catch {
+        if (!cancelled)
+          setChoice({ choice: DEFAULT_AVATAR, isBerdy: agentId === null });
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [agentId]);
+
+  // Never carry a previous agent's identity across an async resolution.
+  return resolved?.agentId === agentId ? resolved.value : fallback;
+}
diff --git a/src/features/desktop-agent/hooks/useAvatarMenu.test.tsx b/src/features/desktop-agent/hooks/useAvatarMenu.test.tsx
new file mode 100644
index 000000000..c8fb40a84
--- /dev/null
+++ b/src/features/desktop-agent/hooks/useAvatarMenu.test.tsx
@@ -0,0 +1,230 @@
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, expect, it, vi } from "vitest";
+
+import type { PendingSelection } from "./useSession";
+import { useAvatarMenu } from "./useAvatarMenu";
+
+const mocks = vi.hoisted(() => ({
+  listPersonas: vi.fn(),
+}));
+
+vi.mock("@/shared/api/agents", () => ({
+  listPersonas: () => mocks.listPersonas(),
+}));
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.listPersonas.mockResolvedValue([
+    { id: "a1", displayName: "Scout", systemPrompt: "" },
+  ]);
+});
+
+function renderMenu(args?: {
+  agentSelector?: boolean;
+  pendingSelection?: PendingSelection | null;
+  activeAgentId?: string | null;
+  select?: (selection: PendingSelection | null) => void;
+}) {
+  return renderHook(() =>
+    useAvatarMenu({
+      pendingSelection: args?.pendingSelection ?? null,
+      activeAgentId: args?.activeAgentId ?? null,
+      select: args?.select ?? vi.fn(),
+      agentSelector: args?.agentSelector ?? true,
+    }),
+  );
+}
+
+it("skips the persona fetch while the agent selector experiment is off", async () => {
+  const { result } = renderMenu({ agentSelector: false });
+  const model = await act(() => result.current.prepareMenu());
+  expect(mocks.listPersonas).not.toHaveBeenCalled();
+  expect(model.agents).toEqual([]);
+});
+
+it("lists agents and checks the fresh entry when nothing is armed or committed", async () => {
+  const { result } = renderMenu();
+  const model = await act(() => result.current.prepareMenu());
+  expect(model.agents).toEqual([
+    {
+      agentId: "a1",
+      name: "Scout",
+      systemPrompt: "",
+      provider: null,
+      model: null,
+    },
+  ]);
+  expect(model.checkedFresh).toBe(true);
+  expect(model.checkedAgentId).toBeNull();
+});
+
+it("falls back to the committed agent for the checkmark when nothing is armed", async () => {
+  const { result } = renderMenu({ activeAgentId: "a1" });
+  const model = await act(() => result.current.prepareMenu());
+  expect(model.checkedAgentId).toBe("a1");
+  expect(model.checkedFresh).toBe(false);
+});
+
+it("survives a failed persona fetch with an empty list", async () => {
+  mocks.listPersonas.mockRejectedValue(new Error("boom"));
+  const { result } = renderMenu();
+  const model = await act(() => result.current.prepareMenu());
+  expect(model.agents).toEqual([]);
+  expect(model.checkedFresh).toBe(true);
+});
+
+it("arms an agent on select and no-ops when it is already armed", async () => {
+  const select = vi.fn();
+  const armed: PendingSelection = {
+    kind: "agent",
+    agent: {
+      agentId: "a1",
+      name: "Scout",
+      systemPrompt: "",
+      provider: null,
+      model: null,
+    },
+  };
+  const { result, rerender } = renderHook(
+    ({ pending }: { pending: PendingSelection | null }) =>
+      useAvatarMenu({
+        pendingSelection: pending,
+        activeAgentId: null,
+        select,
+        agentSelector: true,
+      }),
+    { initialProps: { pending: null as PendingSelection | null } },
+  );
+  await act(() => result.current.prepareMenu());
+  act(() => result.current.selectAgent("a1"));
+  expect(select).toHaveBeenCalledWith({ kind: "agent", agent: armed.agent });
+
+  select.mockClear();
+  rerender({ pending: armed });
+  act(() => result.current.selectAgent("a1"));
+  expect(select).not.toHaveBeenCalled();
+});
+
+it("arms fresh on select and no-ops when fresh is already armed", async () => {
+  const select = vi.fn();
+  const { result, rerender } = renderHook(
+    ({ pending }: { pending: PendingSelection | null }) =>
+      useAvatarMenu({
+        pendingSelection: pending,
+        activeAgentId: "a1",
+        select,
+        agentSelector: true,
+      }),
+    { initialProps: { pending: null as PendingSelection | null } },
+  );
+  act(() => result.current.selectFresh());
+  expect(select).toHaveBeenCalledWith({ kind: "fresh" });
+
+  select.mockClear();
+  rerender({ pending: { kind: "fresh" } });
+  act(() => result.current.selectFresh());
+  expect(select).not.toHaveBeenCalled();
+});
+
+it("newChat no-ops when a pending selection is already armed or the chat is empty", async () => {
+  const select = vi.fn();
+  const { result, rerender } = renderHook(
+    ({
+      pending,
+      active,
+    }: {
+      pending: PendingSelection | null;
+      active: string | null;
+    }) =>
+      useAvatarMenu({
+        pendingSelection: pending,
+        activeAgentId: active,
+        select,
+        agentSelector: true,
+      }),
+    {
+      initialProps: {
+        pending: { kind: "fresh" } as PendingSelection | null,
+        active: null,
+      },
+    },
+  );
+  await act(() => result.current.prepareMenu());
+  await act(() => result.current.newChat(3));
+  expect(select).not.toHaveBeenCalled();
+
+  rerender({ pending: null, active: null });
+  await act(() => result.current.newChat(0));
+  expect(select).not.toHaveBeenCalled();
+});
+
+it("newChat keeps the active agent when the cached list contains it", async () => {
+  const select = vi.fn();
+  const { result } = renderMenu({ activeAgentId: "a1", select });
+  await act(() => result.current.prepareMenu());
+  await act(() => result.current.newChat(2));
+  expect(select).toHaveBeenCalledWith({
+    kind: "agent",
+    agent: {
+      agentId: "a1",
+      name: "Scout",
+      systemPrompt: "",
+      provider: null,
+      model: null,
+    },
+  });
+});
+
+it("newChat fetches and keeps the active agent when the selector is off", async () => {
+  const select = vi.fn();
+  const { result } = renderMenu({
+    agentSelector: false,
+    activeAgentId: "a1",
+    select,
+  });
+  await act(() => result.current.prepareMenu());
+  mocks.listPersonas.mockClear();
+
+  await act(() => result.current.newChat(2));
+
+  expect(mocks.listPersonas).toHaveBeenCalledOnce();
+  expect(select).toHaveBeenCalledWith({
+    kind: "agent",
+    agent: {
+      agentId: "a1",
+      name: "Scout",
+      systemPrompt: "",
+      provider: null,
+      model: null,
+    },
+  });
+});
+
+it("newChat aborts without selecting when the active-agent fetch fails", async () => {
+  const select = vi.fn();
+  const { result } = renderMenu({
+    agentSelector: false,
+    activeAgentId: "a1",
+    select,
+  });
+  await act(() => result.current.prepareMenu());
+  mocks.listPersonas.mockRejectedValue(new Error("boom"));
+
+  await act(() => result.current.newChat(2));
+
+  expect(select).not.toHaveBeenCalled();
+});
+
+it("newChat falls back to fresh when the active persona was deleted", async () => {
+  const select = vi.fn();
+  const { result } = renderMenu({
+    agentSelector: false,
+    activeAgentId: "missing",
+    select,
+  });
+  await act(() => result.current.prepareMenu());
+
+  await act(() => result.current.newChat(2));
+
+  expect(select).toHaveBeenCalledWith({ kind: "fresh" });
+});
diff --git a/src/features/desktop-agent/hooks/useAvatarMenu.ts b/src/features/desktop-agent/hooks/useAvatarMenu.ts
new file mode 100644
index 000000000..68c3d8337
--- /dev/null
+++ b/src/features/desktop-agent/hooks/useAvatarMenu.ts
@@ -0,0 +1,153 @@
+// Avatar context-menu model: right-click opens the custom webview menu
+// (ui/AvatarMenu.tsx — the native NSMenu is gone; a webview menu can show
+// avatar previews and match the popover's dark glass). This hook owns the
+// DATA side: fetching the persona list on open and the selection
+// semantics; DesktopAgentApp owns the geometry (growing the panel window
+// into "menu" mode) and the menu's open/closed lifecycle.
+//
+// Selection semantics: the menu only ever SELECTS — clicking an entry
+// never cancels anything. Clicking the
+// already-ARMED entry is a no-op (arming twice is meaningless); clicking
+// anything else arms it, including the committed identity (that's "new
+// chat with the same agent" — a legitimate ask). The checkmark shows the
+// EFFECTIVE identity: the armed selection when one exists, else the
+// current chat's committed agent binding, else the fresh/Berd entry —
+// never uncheckmarked, because there is no "no identity" state.
+
+import { useCallback, useRef } from "react";
+
+import { listPersonas } from "@/shared/api/agents";
+
+import type { Persona } from "@/shared/types/agents";
+
+import type { AgentInfo, PendingSelection } from "./useSession";
+
+const personaToAgent = (persona: Persona): AgentInfo => ({
+  agentId: persona.id,
+  name: persona.displayName,
+  systemPrompt: persona.systemPrompt,
+  provider: persona.provider ?? null,
+  model: persona.model ?? null,
+});
+
+export interface AvatarMenuModel {
+  agents: AgentInfo[];
+  /** Checked agent row, or null when the fresh/Berd entry is checked. */
+  checkedAgentId: string | null;
+  checkedFresh: boolean;
+}
+
+export function useAvatarMenu(args: {
+  pendingSelection: PendingSelection | null;
+  /** Committed agent binding of the CURRENT chat — the checkmark falls
+   *  back to it when nothing is armed, so the menu always shows the
+   *  effective identity. */
+  activeAgentId: string | null;
+  select(selection: PendingSelection | null): void;
+  /** Agent selector experiment: when false the menu only has the
+   *  settings and turn off items (no "Switch agent" submenu). */
+  agentSelector: boolean;
+}): {
+  prepareMenu(): Promise<AvatarMenuModel>;
+  selectAgent(agentId: string): void;
+  selectFresh(): void;
+  newChat(messageCount: number): Promise<boolean>;
+} {
+  // Callbacks capture refs so a menu opened against one render can still
+  // act on the live values at click time.
+  const pending = useRef(args.pendingSelection);
+  pending.current = args.pendingSelection;
+  const active = useRef(args.activeAgentId);
+  active.current = args.activeAgentId;
+  const select = useRef(args.select);
+  select.current = args.select;
+  const agents = useRef<AgentInfo[]>([]);
+  const agentSelector = args.agentSelector;
+
+  const prepareMenu = useCallback(async (): Promise<AvatarMenuModel> => {
+    if (!agentSelector) {
+      agents.current = [];
+      return { agents: [], checkedAgentId: null, checkedFresh: false };
+    }
+    // Fresh list per open: personas are edited in the main window and
+    // menu opens are rare — staleness would be worse than the fetch. A
+    // failed fetch must not kill the menu — the fresh entry still works
+    // with zero agents.
+    const personas = await listPersonas().catch(() => []);
+    const list = personas.map(personaToAgent);
+    agents.current = list;
+    const current = pending.current;
+    const checkedAgentId =
+      current !== null
+        ? current.kind === "agent"
+          ? current.agent.agentId
+          : null
+        : active.current;
+    return {
+      agents: list,
+      checkedAgentId,
+      checkedFresh:
+        current !== null ? current.kind === "fresh" : active.current === null,
+    };
+  }, [agentSelector]);
+
+  const selectAgent = useCallback((agentId: string) => {
+    const agent = agents.current.find((a) => a.agentId === agentId);
+    if (!agent) return;
+    const current = pending.current;
+    if (current?.kind === "agent" && current.agent.agentId === agentId) {
+      return; // already armed: no-op
+    }
+    select.current({ kind: "agent", agent });
+  }, []);
+
+  const selectFresh = useCallback(() => {
+    if (pending.current?.kind === "fresh") return; // already armed: no-op
+    select.current({ kind: "fresh" });
+  }, []);
+
+  const newChat = useCallback(
+    async (messageCount: number): Promise<boolean> => {
+      if (pending.current !== null) return true; // already armed: empty new chat
+      if (messageCount === 0) return true; // current chat is already empty
+      const activeAgentId = active.current;
+      if (activeAgentId === null) {
+        select.current({ kind: "fresh" });
+        return true;
+      }
+
+      const cachedAgent = agents.current.find(
+        (agent) => agent.agentId === activeAgentId,
+      );
+      if (cachedAgent !== undefined) {
+        select.current({ kind: "agent", agent: cachedAgent });
+        return true;
+      }
+
+      // The menu may not have an agent list (selector disabled or a prior
+      // fetch failed). Preserve the committed identity by refetching it here;
+      // if the network fails, abort New chat rather than silently switching
+      // the user to fresh/Berd.
+      let fetched: AgentInfo[];
+      try {
+        fetched = (await listPersonas()).map(personaToAgent);
+      } catch {
+        return false;
+      }
+      agents.current = fetched;
+      const fetchedAgent = fetched.find(
+        (agent) => agent.agentId === activeAgentId,
+      );
+      if (fetchedAgent !== undefined) {
+        select.current({ kind: "agent", agent: fetchedAgent });
+        return true;
+      }
+
+      select.current({ kind: "fresh" });
+      return true;
+    },
+    [],
+  );
+
+  return { prepareMenu, selectAgent, selectFresh, newChat };
+}
diff --git a/src/features/desktop-agent/hooks/usePerch.test.tsx b/src/features/desktop-agent/hooks/usePerch.test.tsx
new file mode 100644
index 000000000..daf584dd5
--- /dev/null
+++ b/src/features/desktop-agent/hooks/usePerch.test.tsx
@@ -0,0 +1,126 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, expect, it, vi } from "vitest";
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+
+import { usePerch } from "@/features/desktop-agent/hooks/usePerch";
+
+vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
+vi.mock("@tauri-apps/api/event", () => ({ listen: vi.fn() }));
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.mocked(listen).mockResolvedValue(vi.fn());
+  vi.mocked(invoke).mockImplementation(async (command) => {
+    if (command === "desktop_agent_perch_status") return { perched: false };
+    return { appName: "Finder", title: "Files" };
+  });
+});
+it("only explicit drop attaches; renderer changes update existing seating without permission commands", async () => {
+  const { result, rerender } = renderHook(
+    ({ character }) => usePerch(vi.fn(), character),
+    { initialProps: { character: false } },
+  );
+  await waitFor(() =>
+    expect(invoke).toHaveBeenCalledWith("desktop_agent_perch_status", {
+      characterSeat: false,
+    }),
+  );
+  expect(invoke).not.toHaveBeenCalledWith(
+    "desktop_agent_perch_on",
+    expect.anything(),
+  );
+  rerender({ character: true });
+  await waitFor(() =>
+    expect(invoke).toHaveBeenCalledWith("desktop_agent_perch_status", {
+      characterSeat: true,
+    }),
+  );
+  await act(async () => {
+    expect(await result.current.endTargetingAndMaybePerch()).toBe(true);
+  });
+  expect(invoke).toHaveBeenCalledWith("desktop_agent_perch_on", {
+    characterSeat: true,
+  });
+  expect(result.current.phase).toBe("perched");
+  rerender({ character: false });
+  await act(async () => {
+    await result.current.endTargetingAndMaybePerch();
+  });
+  expect(invoke).toHaveBeenCalledWith("desktop_agent_perch_on", {
+    characterSeat: false,
+  });
+});
+it("unmount before async listener registration releases listener without reconciliation", async () => {
+  let finish: (fn: () => void) => void = () => {};
+  vi.mocked(listen).mockReturnValue(
+    new Promise((resolve) => {
+      finish = resolve;
+    }),
+  );
+  const unlisten = vi.fn();
+  const { unmount } = renderHook(() => usePerch(vi.fn()));
+  unmount();
+  await act(async () => finish(unlisten));
+  expect(unlisten).toHaveBeenCalledOnce();
+  expect(invoke).not.toHaveBeenCalledWith("desktop_agent_perch_status");
+});
+
+it("keeps cancellation and drag callbacks stable across phase and renderer changes", async () => {
+  const { result, rerender } = renderHook(
+    ({ character }) => usePerch(vi.fn(), character),
+    { initialProps: { character: false } },
+  );
+  await act(async () => {});
+  const initial = result.current;
+  await act(async () => result.current.beginTargeting());
+  expect(result.current.phase).toBe("targeting");
+  expect(result.current.cancelTargeting).toBe(initial.cancelTargeting);
+  rerender({ character: true });
+  expect(result.current.cancelTargeting).toBe(initial.cancelTargeting);
+  expect(result.current.beginTargeting).toBe(initial.beginTargeting);
+  expect(result.current.dismount).toBe(initial.dismount);
+  await act(async () => result.current.cancelTargeting());
+  expect(result.current.phase).toBe("unperched");
+});
+
+it.each([
+  "hit-test",
+  "attach",
+])("cancellation during %s cannot leave a new perch attached", async (stage) => {
+  const { result } = renderHook(() => usePerch(vi.fn()));
+  await act(async () => {});
+  await act(async () => result.current.beginTargeting());
+  let finish!: (value: { appName: string; title: string }) => void;
+  const command =
+    stage === "hit-test"
+      ? "desktop_agent_perch_end_targeting"
+      : "desktop_agent_perch_on";
+  vi.mocked(invoke).mockImplementation(async (name) => {
+    if (name === command) {
+      // Only the in-flight drop is delayed, not cancellation's stop command.
+      vi.mocked(invoke).mockResolvedValue(null);
+      return new Promise((resolve) => {
+        finish = resolve;
+      });
+    }
+    return { appName: "Finder", title: "Files" };
+  });
+  let drop!: Promise<boolean>;
+  await act(async () => {
+    drop = result.current.endTargetingAndMaybePerch();
+  });
+  await act(async () => result.current.cancelTargeting());
+  await act(async () => {
+    finish({ appName: "Finder", title: "Files" });
+    expect(await drop).toBe(false);
+  });
+  expect(result.current.phase).toBe("unperched");
+  if (stage === "hit-test") {
+    expect(invoke).not.toHaveBeenCalledWith(
+      "desktop_agent_perch_on",
+      expect.anything(),
+    );
+  } else {
+    expect(invoke).toHaveBeenCalledWith("desktop_agent_perch_dismount");
+  }
+});
diff --git a/src/features/desktop-agent/hooks/usePerch.ts b/src/features/desktop-agent/hooks/usePerch.ts
new file mode 100644
index 000000000..d8413ae5d
--- /dev/null
+++ b/src/features/desktop-agent/hooks/usePerch.ts
@@ -0,0 +1,228 @@
+// Perch state hook: targeting rides the avatar drag, the drop attaches
+// via desktop_agent_perch_on, the native follow loop owns panel position
+// while perched, and perch-ended hands the shell an END REASON
+// ("windowGone" flies the avatar home; "minimized" leaves it seated).
+// Phases: unperched -> targeting (drag in flight) -> perched. Minimize
+// AUTO-UNPERCHES (product rule): a minimized window is no longer clearly
+// indicated on screen, and a silent grant invites accidental screenshot
+// sends.
+//
+// Deliberately NOT persisted: perch identity. A perch is a context grant
+// (window capture + artifact URL ride every send), so it must never
+// re-establish itself across an app relaunch — re-perching costs one
+// drag; an unnoticed auto-pin leaks screenshots. Dev-reload
+// reconciliation stays: if the native side still holds a live perch
+// across a webview reload, the grant never ended and the UI just
+// re-syncs from desktop_agent_perch_status.
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+
+import type { PerchPhase } from "../lib/sendSource";
+
+export interface PerchView {
+  phase: PerchPhase;
+  appName: string | null;
+  title: string | null;
+  /** Raw perch-layer error (AX resolve failure, capture failure, the
+   *  accessibility_denied gate token). Kept verbatim — composerHint maps
+   *  the recognized token to grant-instructions copy and renders the
+   *  rest as-is. */
+  lastError: string | null;
+  /** Drag started: snapshot candidates, run the native highlight loop. */
+  beginTargeting(): Promise<void>;
+  /** Pointer-up: hit-test + attach. Returns true when a perch attached. */
+  endTargetingAndMaybePerch(): Promise<boolean>;
+  /** Cancel a gesture without attaching the hit-tested window. */
+  cancelTargeting(): Promise<void>;
+  dismount(): Promise<void>;
+  /** Window-scoped capture of the perched window, or null when
+   *  unperched/failed. Errors surface in lastError; sends degrade to
+   *  text-only. */
+  captureNow(): Promise<{ data: string; mimeType: string } | null>;
+  /** Frontmost tab URL of the perched window, fresh per send (tabs
+   *  change). Every failure is null — a send never blocks on this. */
+  artifactUrlNow(): Promise<string | null>;
+}
+
+/** Why a native perch ended without a dismount gesture. */
+export type PerchEndReason = "windowGone" | "minimized";
+
+export function usePerch(
+  onPerchEnded: (reason: PerchEndReason) => void,
+  characterSeat = false,
+): PerchView {
+  const [phase, setPhase] = useState<PerchPhase>("unperched");
+  const [appName, setAppName] = useState<string | null>(null);
+  const [title, setTitle] = useState<string | null>(null);
+  const [lastError, setLastError] = useState<string | null>(null);
+  const targetingGeneration = useRef(0);
+  const endedHandler = useRef(onPerchEnded);
+  endedHandler.current = onPerchEnded;
+
+  // Startup — ONE effect, strictly ordered (listen() is async, so a
+  // native perch event could otherwise outrun its listener):
+  //   1. AWAIT the perch-ended listener
+  //   2. reconcile native state (dev-reload only — no startup rematch)
+  useEffect(() => {
+    let cancelled = false;
+    let unlistenEnded: (() => void) | null = null;
+    void (async () => {
+      // 1. Listener FIRST — no native event may outrun it. The payload
+      // is the END REASON: "windowGone" (closed — avatar flies home) vs
+      // "minimized" (auto-unperch — the avatar STAYS where it was
+      // seated; a minimize is not a close, and yanking the avatar home
+      // would punish the gesture).
+      unlistenEnded = await listen<string>(
+        "desktop-agent:perch-ended",
+        (event) => {
+          setPhase("unperched");
+          setAppName(null);
+          setTitle(null);
+          endedHandler.current(
+            event.payload === "minimized" ? "minimized" : "windowGone",
+          );
+        },
+      );
+      if (cancelled) {
+        unlistenEnded();
+        return;
+      }
+
+      // 2. Reconcile native state (dev-reload only: a webview reload
+      // does not end the grant — the native perch never stopped). A full
+      // app relaunch always starts unperched by design.
+      try {
+        const status = await invoke<{
+          perched: boolean;
+          appName: string | null;
+          title: string | null;
+        }>("desktop_agent_perch_status");
+        if (cancelled) return;
+        if (status.perched) {
+          setPhase("perched");
+          setAppName(status.appName);
+          setTitle(status.title);
+        }
+      } catch {
+        // Reconciliation is best-effort; the avatar stays free.
+      }
+    })();
+    return () => {
+      cancelled = true;
+      unlistenEnded?.();
+    };
+  }, []);
+
+  // Re-seat an existing grant when the renderer changes; never request
+  // permission or attach a new grant from this effect.
+  useEffect(() => {
+    void invoke("desktop_agent_perch_status", { characterSeat }).catch(
+      () => {},
+    );
+  }, [characterSeat]);
+
+  const beginTargeting = useCallback(async () => {
+    const generation = ++targetingGeneration.current;
+    setPhase("targeting");
+    try {
+      await invoke("desktop_agent_perch_begin_targeting");
+    } catch (error) {
+      if (generation !== targetingGeneration.current) return;
+      setLastError(String(error));
+      setPhase("unperched");
+    }
+  }, []);
+
+  const endTargetingAndMaybePerch = useCallback(async (): Promise<boolean> => {
+    const generation = targetingGeneration.current;
+    try {
+      const candidate = await invoke<{
+        appName: string;
+        title: string;
+      } | null>("desktop_agent_perch_end_targeting");
+      if (generation !== targetingGeneration.current) return false;
+      if (!candidate) {
+        setPhase("unperched");
+        return false;
+      }
+      const result = await invoke<{ appName: string; title: string }>(
+        "desktop_agent_perch_on",
+        { characterSeat },
+      );
+      if (generation !== targetingGeneration.current) {
+        // Cancellation can arrive while native attach is already in flight.
+        await invoke("desktop_agent_perch_dismount");
+        return false;
+      }
+      setPhase("perched");
+      setAppName(result.appName);
+      setTitle(result.title);
+      setLastError(null);
+      return true;
+    } catch (error) {
+      if (generation !== targetingGeneration.current) return false;
+      setLastError(String(error));
+      setPhase("unperched");
+      return false;
+    }
+  }, [characterSeat]);
+
+  const cancelTargeting = useCallback(async () => {
+    targetingGeneration.current++;
+    setPhase("unperched");
+    // Stop the native highlight loop and discard its candidate. In particular,
+    // cancellation must not call perch_on (which can request permissions).
+    try {
+      await invoke("desktop_agent_perch_end_targeting");
+    } catch {
+      // Cancellation is best-effort when the native panel is disappearing.
+    }
+  }, []);
+
+  const dismount = useCallback(async () => {
+    try {
+      await invoke("desktop_agent_perch_dismount");
+    } finally {
+      setPhase("unperched");
+      setAppName(null);
+      setTitle(null);
+    }
+  }, []);
+
+  const captureNow = useCallback(async () => {
+    if (phase === "unperched" || phase === "targeting") return null;
+    try {
+      return await invoke<{ data: string; mimeType: string } | null>(
+        "desktop_agent_perch_capture",
+      );
+    } catch (error) {
+      // Capture failure never blocks a send — it degrades to text-only.
+      setLastError(String(error));
+      return null;
+    }
+  }, [phase]);
+
+  const artifactUrlNow = useCallback(async () => {
+    if (phase === "unperched" || phase === "targeting") return null;
+    try {
+      return await invoke<string | null>("desktop_agent_perch_artifact_url");
+    } catch {
+      return null;
+    }
+  }, [phase]);
+
+  return {
+    phase,
+    appName,
+    title,
+    lastError,
+    beginTargeting,
+    endTargetingAndMaybePerch,
+    cancelTargeting,
+    dismount,
+    captureNow,
+    artifactUrlNow,
+  };
+}
diff --git a/src/features/desktop-agent/hooks/useSession.ts b/src/features/desktop-agent/hooks/useSession.ts
new file mode 100644
index 000000000..75d2994c3
--- /dev/null
+++ b/src/features/desktop-agent/hooks/useSession.ts
@@ -0,0 +1,389 @@
+// Session state hook — a thin composer over unit-tested modules; this
+// hook owns only the React glue:
+//
+//   PanelConnection   single-flight attach + one-shot auto re-attach over
+//                     the shared per-webview ACP connection
+//   SessionStore      armed/parked/commit machine + admission + epoch
+//   SendController    the send paths, composer gate, stop()
+//   panelAcp          direct-ACP session create (persona bound at create
+//                     time), prompt, cancel, adopt probe
+//
+// In-process integration notes: the panel is its own webview, so the
+// shared acpConnection module gives it its OWN GooseClient. Sessions are
+// created directly over that connection — the first response streams live
+// (no dispatch, no export backfill). goosed lives and dies with Berd, so
+// reconnect is one automatic fresh dial after a close, then a manual
+// retry affordance (no blind retry loop).
+//
+// Deferred chats: select() is PURE UI STATE — nothing is created until
+// the first send (product rule). Both create paths stream live.
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { getClient, setNotificationHandler } from "@/shared/api/acpConnection";
+
+import { notificationFromSessionUpdate } from "../lib/acpNotification";
+import type { ChatMessage } from "../lib/chatModels";
+import {
+  adoptSession,
+  cancelPanelSession,
+  createAgentSession,
+  createFreshSession,
+  promptSession,
+} from "../lib/panelAcp";
+import { PanelConnection } from "../lib/panelConnection";
+import { SendController } from "../lib/sendController";
+import { SessionStore } from "../lib/sessionStore";
+import { StallWatchdog } from "../lib/stallWatchdog";
+
+export interface AgentInfo {
+  agentId: string;
+  name: string;
+  systemPrompt: string;
+  provider: string | null;
+  model: string | null;
+}
+
+/** What the next chat is armed to be: an agent-bound session (persona
+ *  bound at create time) or a fresh plain session (the default entry). */
+export type PendingSelection =
+  | { kind: "agent"; agent: AgentInfo }
+  | { kind: "fresh" };
+
+export type SessionActivity = "none" | "thinking" | "responding";
+
+/** Fresh state, Berd-owned: the panel's only persistence. */
+export const SESSION_ID_STORAGE_KEY = "goose:desktop-agent:session-id";
+export const AGENT_ID_STORAGE_KEY = "goose:desktop-agent:agent-id";
+
+function readStorage(key: string): string | null {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(key: string, value: string | null): void {
+  try {
+    if (value === null) localStorage.removeItem(key);
+    else localStorage.setItem(key, value);
+  } catch {
+    // Persistence is best-effort; the current webview keeps working.
+  }
+}
+
+/** One instance per hook life, created on first render. These instances
+ *  ARE the hook's state machines — closures capture them directly, so
+ *  once-registered listeners always read live values. */
+function useSingleton<T>(create: () => T): T {
+  const ref = useRef<T | null>(null);
+  if (ref.current === null) {
+    ref.current = create();
+  }
+  return ref.current;
+}
+
+export interface SessionView {
+  attached: boolean;
+  sessionId: string | null;
+  messages: ChatMessage[];
+  activity: SessionActivity;
+  lastSendError: string | null;
+  /** Connection/attach failure — own channel so reconnect churn never
+   *  stomps a send error. Rendered only while disconnected. */
+  connectionError: string | null;
+  /** No further automatic reconnect attempt is coming — the UI must stop
+   *  saying "reconnecting" and offer the manual retry. */
+  reconnectExhausted: boolean;
+  /** Manual retry affordance after exhaustion. */
+  retry(): void;
+  /** Thinking with zero updates for 25s — surfaces a hint, never aborts
+   *  the send. */
+  sendStalled: boolean;
+  /** What the NEXT chat is armed to be — pure UI state until the first
+   *  send (product rule: selection creates nothing). */
+  pendingSelection: PendingSelection | null;
+  /** Agent bound to the CURRENT session: set when an agent chat commits,
+   *  cleared on fresh commit, restored from persistence at adopt. Drives
+   *  the avatar. */
+  activeAgentId: string | null;
+  /** True while a deferred create is in flight (before streaming takes
+   *  over); the composer shows agent-starting state. */
+  agentSendInFlight: boolean;
+  /** SYNCHRONOUS live view of the send gate: true while a deferred
+   *  create is in flight OR a run is active on the live session (goosed
+   *  rejects concurrent prompts per session — mid-run sends are
+   *  disallowed). The composer must check this BEFORE
+   *  clearing the draft — React state lags a render, and a send()
+   *  bounced off the internal guards would otherwise eat the message
+   *  silently. */
+  sendBusy(): boolean;
+  /** Stops the in-flight run (session/cancel). Fire-and-forget: the
+   *  pending prompt resolves normally with stopReason "cancelled". */
+  stop(): Promise<void>;
+  /** Arms a deferred chat: clears the transcript view, holds the
+   *  selection until the first send. Passing null cancels back to the
+   *  current session unchanged. */
+  select(selection: PendingSelection | null): void;
+  /** Resolves true when the message DISPATCHED (echo appended, delivery
+   *  attempted — failures land on lastSendError) and false when it
+   *  BOUNCED off a send gate untouched. A composer with an async gap
+   *  between its gate check and this call (the perch capture path) must
+   *  restore the cleared draft on false — otherwise the bounce eats the
+   *  message.
+   *
+   *  makePreamble (perch sends): builds the wire-only identity preamble
+   *  from live perch state; the controller decides full-vs-slim guidance
+   *  and owns the ledger. Absent for ordinary sends. */
+  send(
+    text: string,
+    imageBlocks?: Array<Record<string, unknown>>,
+    makePreamble?: ((fullGuidance: boolean) => string | null) | null,
+  ): Promise<boolean>;
+}
+
+export function useSession(): SessionView {
+  // Canonical session/transcript state machine. React state below mirrors
+  // the store after each mutating call.
+  const store = useSingleton(() => new SessionStore());
+  const [attached, setAttached] = useState(false);
+  const [sessionId, setSessionId] = useState<string | null>(null);
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [activity, setActivity] = useState<SessionActivity>("none");
+  const [lastSendError, setLastSendError] = useState<string | null>(null);
+  const [connectionError, setConnectionError] = useState<string | null>(null);
+  const [reconnectExhausted, setReconnectExhausted] = useState(false);
+  const [sendStalled, setSendStalled] = useState(false);
+  const [pendingSelection, setPendingSelection] =
+    useState<PendingSelection | null>(null);
+  const [agentSendInFlight, setAgentSendInFlight] = useState(false);
+  const [activeAgentId, setActiveAgentId] = useState<string | null>(null);
+  const watchdog = useSingleton(() => new StallWatchdog(setSendStalled));
+
+  const publish = useCallback(() => {
+    // store.messages is already a fresh-array snapshot (publish contract).
+    setMessages(store.messages);
+  }, [store]);
+
+  // Send flows: the SendController owns the send paths and the
+  // createInFlight composer gate. Constructed once — its ports close over
+  // the store and stable setters; the onCommitted sink mirrors the
+  // store's canonical values into React state and persists the ids.
+  const controller = useSingleton(
+    () =>
+      new SendController(
+        store,
+        {
+          prompt: (args) => promptSession(args.sessionId, args.content),
+          createAgentSession: (agent) => createAgentSession(agent),
+          createFreshSession: () => createFreshSession(),
+          cancel: (id) => cancelPanelSession(id),
+        },
+        {
+          setActivity,
+          setLastSendError,
+          setAgentSendInFlight,
+          onCommitted: () => {
+            setSessionId(store.sessionId);
+            setPendingSelection(store.pendingSelection);
+            setActiveAgentId(store.activeAgentId);
+            writeStorage(SESSION_ID_STORAGE_KEY, store.sessionId);
+            writeStorage(AGENT_ID_STORAGE_KEY, store.activeAgentId);
+          },
+          publish: () => setMessages(store.messages),
+        },
+      ),
+  );
+
+  // Armed on entering thinking, cleared on leaving. NOT armed during a
+  // deferred create: the create RPC has its own error path, and the
+  // watchdog would false-fire on slow persona setup.
+  useEffect(() => {
+    if (activity === "thinking" && !agentSendInFlight) {
+      watchdog.arm();
+    } else {
+      watchdog.clear();
+    }
+  }, [activity, agentSendInFlight, watchdog]);
+
+  // Dispose: no late fires after unmount.
+  useEffect(() => () => watchdog.clear(), [watchdog]);
+
+  // Adopt-or-wait: after (re-)attach, re-adopt the persisted session via
+  // session/load — the replay streams through the notification handler
+  // and repaints the transcript from server truth. Only a DEFINITIVE
+  // stale id (goosed refused it over a healthy connection) clears
+  // persistence; a transient failure (connection died mid-probe) keeps
+  // the ids so the reconnect's re-adopt can retry — wiping on transient
+  // failures silently unlinked the conversation forever (review 5.3).
+  const adoptOnAttach = useCallback(async () => {
+    const persistedId = readStorage(SESSION_ID_STORAGE_KEY);
+    if (persistedId !== null) {
+      store.resetForAdopt(persistedId);
+      publish();
+      const outcome = await adoptSession(persistedId);
+      if (outcome === "adopted") {
+        const agentId = readStorage(AGENT_ID_STORAGE_KEY);
+        if (agentId !== null && !store.armed) {
+          store.restoreAgentBinding(agentId);
+          setActiveAgentId(agentId);
+        }
+        if (!store.armed) setSessionId(persistedId);
+      } else if (outcome === "stale") {
+        writeStorage(SESSION_ID_STORAGE_KEY, null);
+        writeStorage(AGENT_ID_STORAGE_KEY, null);
+        store.resetForAdopt(null);
+        if (!store.armed) {
+          setSessionId(null);
+          // The store unlinked the agent binding too — an agent avatar
+          // over a null session would be the wrong face until the next
+          // commit corrected it (review Check 4 LOW).
+          setActiveAgentId(null);
+        }
+        publish();
+      } else {
+        // Transient: persistence untouched. The store keeps the
+        // persisted id as its live id (half-replayed transcript is
+        // replaced wholesale by the NEXT successful adopt's
+        // resetForAdopt), and the connection's close monitor is about
+        // to fire onDetached → auto re-attach → this function again.
+      }
+    }
+    setAttached(true);
+    setConnectionError(null);
+    setReconnectExhausted(false);
+  }, [publish, store]);
+
+  // The connection is constructed once; route its callback through a ref
+  // so it always calls the latest adoptOnAttach.
+  const adoptOnAttachRef = useRef(adoptOnAttach);
+  adoptOnAttachRef.current = adoptOnAttach;
+
+  // Connection lifecycle: single-flight attach over the shared client,
+  // one automatic re-attach after a close, exhaustion after that.
+  const connection = useSingleton(
+    () =>
+      new PanelConnection(
+        { connect: () => getClient() },
+        {
+          onAttached: () => {
+            void adoptOnAttachRef.current();
+          },
+          onDetached: () => {
+            setAttached(false);
+            setActivity("none");
+          },
+          onFailed: (error, exhausted) => {
+            setConnectionError(error);
+            if (exhausted) setReconnectExhausted(true);
+          },
+        },
+      ),
+  );
+
+  // Attach on mount. revive() undoes the previous cleanup's dispose
+  // (StrictMode mounts twice; the connection instance survives).
+  useEffect(() => {
+    connection.revive();
+    void connection.attach();
+    return () => connection.dispose();
+  }, [connection]);
+
+  // Manual retry after exhaustion.
+  const retry = useCallback(() => {
+    setReconnectExhausted(false);
+    void connection.attach();
+  }, [connection]);
+
+  // Stream notifications into the store. The shared connection hands
+  // SessionNotification objects to the registered handler; admission
+  // control lives in SessionStore.admit (armed view admits nothing,
+  // foreign sessions drop). Only 'painted' admissions prove liveness.
+  useEffect(() => {
+    setNotificationHandler({
+      handleSessionNotification: async (notification) => {
+        const mapped = notificationFromSessionUpdate(
+          notification.sessionId,
+          notification.update as unknown as Record<string, unknown>,
+        );
+        if (!mapped) return;
+        if (store.admit(mapped) !== "painted") return;
+        // Traffic proves liveness — re-arms the stall watchdog.
+        watchdog.noteTraffic();
+        // First assistant-visible content flips thinking -> responding.
+        if (store.paintedStreaming()) {
+          setActivity((current) =>
+            current === "thinking" ? "responding" : current,
+          );
+        }
+        publish();
+      },
+    });
+    // No unregister API: the handler is webview-scoped and the panel IS
+    // this webview — it lives exactly as long as the handler should.
+  }, [publish, store, watchdog]);
+
+  // Arms (or cancels) a deferred chat. Selection is PURE UI state: the
+  // current transcript is parked, the view goes empty, and NOTHING exists
+  // server-side until the first send. Cancelling (null) restores the
+  // parked transcript verbatim.
+  const select = useCallback(
+    (selection: PendingSelection | null) => {
+      // Cleared on EVERY selection change, not just cancel: a re-select
+      // mid-create orphans the create's finally (epoch mismatch), and a
+      // stuck true here is an input lock now that the composer gates on
+      // it.
+      setAgentSendInFlight(false);
+      if (selection === null) {
+        store.cancelArm(); // bumps the epoch
+        // The scratch view (and any failed send it hosted) is being
+        // discarded — a lingering "Couldn't send" describing a message
+        // that is no longer on screen would be a lie (review 5.3).
+        setLastSendError(null);
+        setSessionId(store.sessionId);
+        setActiveAgentId(store.activeAgentId);
+        setPendingSelection(null);
+        setActivity("none");
+        setMessages(store.messages);
+        return;
+      }
+      store.arm(selection); // bumps the epoch; scratch reducer replaced
+      setPendingSelection(selection);
+      setLastSendError(null);
+      setActivity("none");
+      setMessages([]);
+    },
+    [store],
+  );
+
+  const stop = useCallback(() => controller.stop(), [controller]);
+
+  const send = useCallback(
+    (
+      text: string,
+      imageBlocks?: Array<Record<string, unknown>>,
+      makePreamble?: ((fullGuidance: boolean) => string | null) | null,
+    ) => controller.send(text, imageBlocks, makePreamble),
+    [controller],
+  );
+
+  return {
+    attached,
+    sessionId,
+    messages,
+    activity,
+    lastSendError,
+    connectionError,
+    reconnectExhausted,
+    retry,
+    sendStalled,
+    pendingSelection,
+    activeAgentId,
+    agentSendInFlight,
+    sendBusy: () => controller.busy,
+    stop,
+    select,
+    send,
+  };
+}
diff --git a/src/features/desktop-agent/lib/acpNotification.ts b/src/features/desktop-agent/lib/acpNotification.ts
new file mode 100644
index 000000000..69e4e34d5
--- /dev/null
+++ b/src/features/desktop-agent/lib/acpNotification.ts
@@ -0,0 +1,113 @@
+// Ported from the prototype's Dart ACP client. A `session/update` (or
+// `_goose/unstable/session/update`) notification and its update wrapper.
+
+export interface AcpNotification {
+  sessionId: string;
+  update: AcpUpdate;
+}
+
+/** Tri-state for `_meta.goose.activeRunId`: absent key, explicit null, or id. */
+export interface ActiveRunId {
+  isPresent: boolean;
+  id: string | null;
+}
+
+/** Adapter for Berd's shared ACP connection: the GooseClient notification
+ *  callback hands `SessionNotification` objects ({ sessionId, update })
+ *  directly — no JSON-RPC envelope (the prototype's Rust-pushed event
+ *  shape is gone). Same wrapper, same downstream reducer/admission path. */
+export function notificationFromSessionUpdate(
+  sessionId: unknown,
+  update: unknown,
+): AcpNotification | null {
+  if (
+    typeof sessionId !== "string" ||
+    typeof update !== "object" ||
+    update === null
+  ) {
+    return null;
+  }
+  return {
+    sessionId,
+    update: new AcpUpdate(update as Record<string, unknown>),
+  };
+}
+
+const asString = (v: unknown): string | null =>
+  typeof v === "string" ? v : null;
+const asRecord = (v: unknown): Record<string, unknown> | null =>
+  typeof v === "object" && v !== null && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : null;
+
+function parseIso8601(v: unknown): number | undefined {
+  if (typeof v !== "string") return undefined;
+  const ms = Date.parse(v);
+  return Number.isNaN(ms) ? undefined : ms;
+}
+
+/** Wrapper for one `update` object inside a session/update notification. */
+export class AcpUpdate {
+  constructor(readonly raw: Record<string, unknown>) {}
+
+  get kind(): string {
+    return asString(this.raw.sessionUpdate) ?? "unknown";
+  }
+
+  get messageId(): string | null {
+    return asString(this.raw.messageId);
+  }
+
+  get content(): Record<string, unknown> | null {
+    return asRecord(this.raw.content);
+  }
+
+  get toolCallId(): string | null {
+    return asString(this.raw.toolCallId);
+  }
+
+  get title(): string | null {
+    return asString(this.raw.title);
+  }
+
+  get status(): string | null {
+    return asString(this.raw.status);
+  }
+
+  private get meta(): Record<string, unknown> | null {
+    return asRecord(this.raw._meta);
+  }
+
+  private get gooseMeta(): Record<string, unknown> | null {
+    return asRecord(this.meta?.goose);
+  }
+
+  /** Distinguishes absent key / explicit null / string id. */
+  get activeRunId(): ActiveRunId {
+    const goose = this.gooseMeta;
+    if (goose === null || !("activeRunId" in goose)) {
+      return { isPresent: false, id: null };
+    }
+    const value = goose.activeRunId;
+    return typeof value === "string"
+      ? { isPresent: true, id: value }
+      : { isPresent: true, id: null };
+  }
+
+  get updatedAt(): number | undefined {
+    return parseIso8601(this.raw.updatedAt);
+  }
+
+  get lastMessageAt(): number | undefined {
+    return (
+      parseIso8601(this.meta?.lastMessageAt) ??
+      parseIso8601(this.raw.lastMessageAt)
+    );
+  }
+
+  get archivedAt(): number | undefined {
+    return (
+      parseIso8601(this.meta?.archivedAt) ?? parseIso8601(this.raw.archivedAt)
+    );
+  }
+}
diff --git a/src/features/desktop-agent/lib/anchorGeometry.test.ts b/src/features/desktop-agent/lib/anchorGeometry.test.ts
new file mode 100644
index 000000000..5dfdf684d
--- /dev/null
+++ b/src/features/desktop-agent/lib/anchorGeometry.test.ts
@@ -0,0 +1,538 @@
+// Ported from the prototype's test/shell/anchor_geometry_test.dart — same cases,
+// same geometry, same expectations.
+
+import { describe, expect, test } from "vitest";
+
+import {
+  clampAvatarToScreens,
+  computeExpandedLayout,
+  computeGrownLayout,
+  inflate,
+  POPOVER_SHADOW_MARGIN,
+  rect,
+  rectBottom,
+  rectContains,
+  rectRight,
+  screenContaining,
+  type ScreenInfo,
+} from "./anchorGeometry";
+
+const mainScreen: ScreenInfo = {
+  frame: rect(0, 0, 1440, 900),
+  visibleFrame: rect(0, 25, 1440, 875),
+  isMain: true,
+};
+
+const sideScreen: ScreenInfo = {
+  frame: rect(1440, 0, 1920, 1080),
+  visibleFrame: rect(1440, 0, 1920, 1080),
+};
+
+const screens = [mainScreen, sideScreen];
+
+describe("screenContaining", () => {
+  test("returns the screen containing the point", () => {
+    expect(screenContaining({ x: 100, y: 100 }, screens)).toBe(mainScreen);
+    expect(screenContaining({ x: 1500, y: 100 }, screens)).toBe(sideScreen);
+  });
+
+  test("falls back to the main screen for off-screen points", () => {
+    expect(screenContaining({ x: -500, y: -500 }, screens)).toBe(mainScreen);
+  });
+
+  test("falls back to the first screen when no main is flagged", () => {
+    const noMain: ScreenInfo[] = [
+      { frame: rect(0, 0, 100, 100), visibleFrame: rect(0, 0, 100, 100) },
+      { frame: rect(100, 0, 100, 100), visibleFrame: rect(100, 0, 100, 100) },
+    ];
+    expect(screenContaining({ x: -1, y: -1 }, noMain)).toBe(noMain[0]);
+  });
+});
+
+describe("clampAvatarToScreens", () => {
+  const avatar = rect(200, 200, 90, 90);
+
+  test("leaves a fully visible avatar unchanged", () => {
+    expect(clampAvatarToScreens(avatar, screens)).toEqual(avatar);
+  });
+
+  test("clamps an avatar hanging past the bottom edge onto the screen", () => {
+    const hanging = rect(200, 880, 90, 90);
+    const clamped = clampAvatarToScreens(hanging, screens);
+    expect(rectBottom(clamped)).toBe(rectBottom(mainScreen.visibleFrame));
+    expect(clamped.x).toBe(200);
+  });
+
+  test("clamps an avatar under the menu bar down into the visible frame", () => {
+    const underMenuBar = rect(200, 0, 90, 90);
+    const clamped = clampAvatarToScreens(underMenuBar, screens);
+    expect(clamped.y).toBe(mainScreen.visibleFrame.y);
+  });
+
+  test("keeps a mostly off-screen avatar attached to its nearest screen", () => {
+    const mostlyOff = rect(1400, 850, 90, 90);
+    const clamped = clampAvatarToScreens(mostlyOff, screens);
+    const center = { x: clamped.x + 45, y: clamped.y + 45 };
+    const container = screenContaining(center, screens);
+    expect(rectContains(container.visibleFrame, center)).toBe(true);
+    expect(rectRight(clamped)).toBeLessThanOrEqual(
+      rectRight(container.visibleFrame),
+    );
+  });
+});
+
+describe("computeExpandedLayout", () => {
+  const popoverSize = { width: 380, height: 520 };
+
+  test("avatar global position is invariant across expansion", () => {
+    const avatar = rect(600, 700, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens,
+    });
+    expect({
+      x: layout.avatarRect.x + layout.windowFrame.x,
+      y: layout.avatarRect.y + layout.windowFrame.y,
+      width: layout.avatarRect.width,
+      height: layout.avatarRect.height,
+    }).toEqual(avatar);
+  });
+
+  test("opens above when the avatar is in the lower half", () => {
+    const avatar = rect(600, 750, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens,
+    });
+    expect(layout.popoverAbove).toBe(true);
+    expect(rectBottom(layout.popoverRect)).toBeLessThanOrEqual(
+      layout.avatarRect.y,
+    );
+  });
+
+  test("opens below when the avatar is in the upper half", () => {
+    const avatar = rect(600, 100, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens,
+    });
+    expect(layout.popoverAbove).toBe(false);
+    expect(layout.popoverRect.y).toBeGreaterThanOrEqual(
+      rectBottom(layout.avatarRect),
+    );
+  });
+
+  test("popover stays fully on-screen in all four corners", () => {
+    const corners = [
+      rect(0, 25, 90, 90),
+      rect(1350, 25, 90, 90),
+      rect(0, 810, 90, 90),
+      rect(1350, 810, 90, 90),
+    ];
+    for (const avatar of corners) {
+      const layout = computeExpandedLayout({
+        avatarGlobal: avatar,
+        popoverSize,
+        screens,
+      });
+      const popGlobal = rect(
+        layout.popoverRect.x + layout.windowFrame.x,
+        layout.popoverRect.y + layout.windowFrame.y,
+        layout.popoverRect.width,
+        layout.popoverRect.height,
+      );
+      expect(popGlobal.x).toBeGreaterThanOrEqual(mainScreen.visibleFrame.x);
+      expect(rectRight(popGlobal)).toBeLessThanOrEqual(
+        rectRight(mainScreen.visibleFrame),
+      );
+    }
+  });
+
+  test("short screen above placement does not throw and stays visible", () => {
+    const shortScreen: ScreenInfo = {
+      frame: rect(0, 0, 800, 400),
+      visibleFrame: rect(0, 25, 800, 375),
+      isMain: true,
+    };
+    const avatar = rect(300, 280, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens: [shortScreen],
+    });
+    const popGlobal = rect(
+      layout.popoverRect.x + layout.windowFrame.x,
+      layout.popoverRect.y + layout.windowFrame.y,
+      layout.popoverRect.width,
+      layout.popoverRect.height,
+    );
+    expect(popGlobal.y).toBeGreaterThanOrEqual(12);
+    // Anchor invariant holds even in degenerate space.
+    expect({
+      x: layout.avatarRect.x + layout.windowFrame.x,
+      y: layout.avatarRect.y + layout.windowFrame.y,
+    }).toEqual({ x: avatar.x, y: avatar.y });
+  });
+
+  test("popover never occludes the avatar, in any corner or edge", () => {
+    // Near screen corners the vertical clamp used to slide the
+    // popover back over the avatar. Sweep positions across the visible
+    // frame and assert the no-occlusion invariant everywhere.
+    const size = 45;
+    const positions: Array<{ x: number; y: number }> = [];
+    for (const x of [0, 360, 720, 1080, 1440 - size]) {
+      for (const y of [25, 240, 460, 680, 900 - size]) {
+        positions.push({ x, y });
+      }
+    }
+    for (const pos of positions) {
+      const avatar = rect(pos.x, pos.y, size, size);
+      const layout = computeExpandedLayout({
+        avatarGlobal: avatar,
+        popoverSize,
+        screens,
+      });
+      const overlaps =
+        layout.popoverRect.x < rectRight(layout.avatarRect) &&
+        layout.avatarRect.x < rectRight(layout.popoverRect) &&
+        layout.popoverRect.y < rectBottom(layout.avatarRect) &&
+        layout.avatarRect.y < rectBottom(layout.popoverRect);
+      expect(overlaps, `popover occludes avatar at (${pos.x},${pos.y})`).toBe(
+        false,
+      );
+      // The anchor invariant must survive the fallback too.
+      expect({
+        x: layout.avatarRect.x + layout.windowFrame.x,
+        y: layout.avatarRect.y + layout.windowFrame.y,
+      }).toEqual({ x: avatar.x, y: avatar.y });
+    }
+  });
+
+  test("degenerate case: popover wider than screen still leaves avatar clickable", () => {
+    // When the popover cannot fit beside the avatar at all, the side
+    // clamp used to land back on top of it. Last resort slides
+    // vertically off the avatar instead.
+    const tinyScreen: ScreenInfo = {
+      frame: rect(0, 0, 400, 700),
+      visibleFrame: rect(0, 25, 400, 675),
+      isMain: true,
+    };
+    const avatar = rect(180, 340, 45, 45); // dead center
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize, // 380 wide on a 400-wide screen: side placement impossible
+      screens: [tinyScreen],
+    });
+    const overlaps =
+      layout.popoverRect.x < rectRight(layout.avatarRect) &&
+      layout.avatarRect.x < rectRight(layout.popoverRect) &&
+      layout.popoverRect.y < rectBottom(layout.avatarRect) &&
+      layout.avatarRect.y < rectBottom(layout.popoverRect);
+    expect(overlaps).toBe(false);
+  });
+
+  test("mid-edge fallback places the popover beside the avatar", () => {
+    // Left edge, vertical middle: neither above nor below fits the 520pt
+    // popover, so the vertical clamp used to slide it over the avatar.
+    // Now it must sit to the avatar's right (the side with room).
+    const avatar = rect(0, 460, 45, 45);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens,
+    });
+    expect(layout.popoverRect.x).toBeGreaterThanOrEqual(
+      rectRight(layout.avatarRect),
+    );
+  });
+
+  test("window frame bounds both the avatar and the popover", () => {
+    const avatar = rect(600, 700, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens,
+    });
+    expect(layout.avatarRect.x).toBeGreaterThanOrEqual(0);
+    expect(layout.avatarRect.y).toBeGreaterThanOrEqual(0);
+    expect(layout.popoverRect.x).toBeGreaterThanOrEqual(0);
+    expect(layout.popoverRect.y).toBeGreaterThanOrEqual(0);
+    expect(rectRight(layout.avatarRect)).toBeLessThanOrEqual(
+      layout.windowFrame.width,
+    );
+    expect(rectBottom(layout.avatarRect)).toBeLessThanOrEqual(
+      layout.windowFrame.height,
+    );
+    expect(rectRight(layout.popoverRect)).toBeLessThanOrEqual(
+      layout.windowFrame.width,
+    );
+    expect(rectBottom(layout.popoverRect)).toBeLessThanOrEqual(
+      layout.windowFrame.height,
+    );
+  });
+});
+
+describe("computeExpandedLayout side placement", () => {
+  const popoverSize = { width: 380, height: 96 };
+
+  function globalPopover(layout: ReturnType<typeof computeExpandedLayout>) {
+    return rect(
+      layout.popoverRect.x + layout.windowFrame.x,
+      layout.popoverRect.y + layout.windowFrame.y,
+      layout.popoverRect.width,
+      layout.popoverRect.height,
+    );
+  }
+
+  test("right-half avatar places the popover on the left", () => {
+    const avatar = rect(1200, 400, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens,
+      placement: "side",
+    });
+    const popover = globalPopover(layout);
+    expect(layout.popoverSide).toBe("left");
+    expect(rectRight(popover)).toBeLessThanOrEqual(avatar.x - 8);
+  });
+
+  test("left-half avatar places the popover on the right", () => {
+    const avatar = rect(120, 400, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens,
+      placement: "side",
+    });
+    const popover = globalPopover(layout);
+    expect(layout.popoverSide).toBe("right");
+    expect(popover.x).toBeGreaterThanOrEqual(rectRight(avatar) + 8);
+  });
+
+  test("side placement vertically centers on the avatar, clamped to visible frame", () => {
+    const avatar = rect(120, 400, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens,
+      placement: "side",
+    });
+    const popover = globalPopover(layout);
+    expect(popover.y + popover.height / 2).toBe(avatar.y + avatar.height / 2);
+
+    const edgeAvatar = rect(120, 25, 90, 90);
+    const edgeLayout = computeExpandedLayout({
+      avatarGlobal: edgeAvatar,
+      popoverSize,
+      screens,
+      placement: "side",
+    });
+    expect(globalPopover(edgeLayout).y).toBeGreaterThanOrEqual(
+      mainScreen.visibleFrame.y + 12,
+    );
+  });
+
+  test("falls back to the other side when the preferred side lacks room", () => {
+    const avatar = rect(1050, 400, 90, 90);
+    const narrow: ScreenInfo = {
+      frame: rect(0, 0, 1200, 900),
+      visibleFrame: rect(0, 25, 1200, 875),
+      isMain: true,
+    };
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens: [narrow],
+      placement: "side",
+    });
+    expect(layout.popoverSide).toBe("left");
+  });
+
+  test("falls back to vertical when neither side has room", () => {
+    const tiny: ScreenInfo = {
+      frame: rect(0, 0, 300, 700),
+      visibleFrame: rect(0, 25, 300, 675),
+      isMain: true,
+    };
+    const avatar = rect(100, 100, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens: [tiny],
+      placement: "side",
+    });
+    expect(layout.popoverSide).toBeNull();
+    expect(layout.popoverRect.y).toBeGreaterThanOrEqual(
+      rectBottom(layout.avatarRect),
+    );
+  });
+
+  test("avatar rect stays unchanged and window contains inflated popover", () => {
+    const avatar = rect(120, 400, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize,
+      screens,
+      placement: "side",
+    });
+    expect({
+      x: layout.avatarRect.x + layout.windowFrame.x,
+      y: layout.avatarRect.y + layout.windowFrame.y,
+      width: layout.avatarRect.width,
+      height: layout.avatarRect.height,
+    }).toEqual(avatar);
+
+    const inflatedPopover = inflate(layout.popoverRect, POPOVER_SHADOW_MARGIN);
+    expect(inflatedPopover.x).toBeGreaterThanOrEqual(0);
+    expect(inflatedPopover.y).toBeGreaterThanOrEqual(0);
+    expect(rectRight(inflatedPopover)).toBeLessThanOrEqual(
+      layout.windowFrame.width,
+    );
+    expect(rectBottom(inflatedPopover)).toBeLessThanOrEqual(
+      layout.windowFrame.height,
+    );
+  });
+});
+
+describe("computeGrownLayout", () => {
+  const composerSize = { width: 380, height: 96 };
+  const fullSize = { width: 380, height: 520 };
+
+  function globalPopover(layout: ReturnType<typeof computeExpandedLayout>) {
+    return rect(
+      layout.popoverRect.x + layout.windowFrame.x,
+      layout.popoverRect.y + layout.windowFrame.y,
+      layout.popoverRect.width,
+      layout.popoverRect.height,
+    );
+  }
+
+  test("keeps x and composer bottom fixed while preserving avatar and shadow containment", () => {
+    const avatar = rect(120, 500, 90, 90);
+    const composer = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize: composerSize,
+      screens,
+      placement: "side",
+    });
+    const fromPopover = globalPopover(composer);
+    const composerBottom = rectBottom(fromPopover) - 20;
+    const grown = computeGrownLayout({
+      avatarGlobal: avatar,
+      fromPopoverGlobal: fromPopover,
+      composerBottomGlobal: composerBottom,
+      popoverSize: fullSize,
+      screens,
+      bottomInset: 16,
+      fromPopoverSide: composer.popoverSide,
+    });
+    const popover = globalPopover(grown);
+
+    expect(popover.x).toBe(fromPopover.x);
+    expect(rectBottom(popover) - 16).toBe(composerBottom);
+    expect({
+      x: grown.avatarRect.x + grown.windowFrame.x,
+      y: grown.avatarRect.y + grown.windowFrame.y,
+      width: grown.avatarRect.width,
+      height: grown.avatarRect.height,
+    }).toEqual(avatar);
+
+    const inflatedPopover = inflate(grown.popoverRect, POPOVER_SHADOW_MARGIN);
+    expect(inflatedPopover.x).toBeGreaterThanOrEqual(0);
+    expect(inflatedPopover.y).toBeGreaterThanOrEqual(0);
+    expect(rectRight(inflatedPopover)).toBeLessThanOrEqual(
+      grown.windowFrame.width,
+    );
+    expect(rectBottom(inflatedPopover)).toBeLessThanOrEqual(
+      grown.windowFrame.height,
+    );
+  });
+
+  test("clamps down by the minimum needed when growing near the top of the screen", () => {
+    const avatar = rect(120, 40, 90, 90);
+    const composer = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize: composerSize,
+      screens,
+      placement: "side",
+    });
+    const fromPopover = globalPopover(composer);
+    const grown = computeGrownLayout({
+      avatarGlobal: avatar,
+      fromPopoverGlobal: fromPopover,
+      composerBottomGlobal: rectBottom(fromPopover) - 20,
+      popoverSize: fullSize,
+      screens,
+      bottomInset: 16,
+      fromPopoverSide: composer.popoverSide,
+    });
+    const popover = globalPopover(grown);
+
+    expect(popover.x).toBe(fromPopover.x);
+    expect(popover.y).toBe(mainScreen.visibleFrame.y + 12);
+  });
+
+  test("vertical-fallback composer keeps old expanded behavior", () => {
+    const tiny: ScreenInfo = {
+      frame: rect(0, 0, 300, 700),
+      visibleFrame: rect(0, 25, 300, 675),
+      isMain: true,
+    };
+    const avatar = rect(100, 100, 90, 90);
+    const composer = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize: composerSize,
+      screens: [tiny],
+      placement: "side",
+    });
+    expect(composer.popoverSide).toBeNull();
+
+    const grown = computeGrownLayout({
+      avatarGlobal: avatar,
+      fromPopoverGlobal: globalPopover(composer),
+      composerBottomGlobal: 250,
+      popoverSize: fullSize,
+      screens: [tiny],
+      bottomInset: 16,
+      fromPopoverSide: composer.popoverSide,
+    });
+    const old = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize: fullSize,
+      screens: [tiny],
+    });
+
+    expect(grown).toEqual(old);
+  });
+});
+
+describe("popover shadow margin", () => {
+  test("window contains the inflated popover while avatar global rect is unchanged", () => {
+    const avatar = rect(600, 700, 90, 90);
+    const layout = computeExpandedLayout({
+      avatarGlobal: avatar,
+      popoverSize: { width: 380, height: 520 },
+      screens,
+    });
+    const inflatedPopover = inflate(layout.popoverRect, POPOVER_SHADOW_MARGIN);
+
+    expect(inflatedPopover.x).toBeGreaterThanOrEqual(0);
+    expect(inflatedPopover.y).toBeGreaterThanOrEqual(0);
+    expect(rectRight(inflatedPopover)).toBeLessThanOrEqual(
+      layout.windowFrame.width,
+    );
+    expect(rectBottom(inflatedPopover)).toBeLessThanOrEqual(
+      layout.windowFrame.height,
+    );
+    expect({
+      x: layout.avatarRect.x + layout.windowFrame.x,
+      y: layout.avatarRect.y + layout.windowFrame.y,
+      width: layout.avatarRect.width,
+      height: layout.avatarRect.height,
+    }).toEqual(avatar);
+  });
+});
diff --git a/src/features/desktop-agent/lib/anchorGeometry.ts b/src/features/desktop-agent/lib/anchorGeometry.ts
new file mode 100644
index 000000000..b37320283
--- /dev/null
+++ b/src/features/desktop-agent/lib/anchorGeometry.ts
@@ -0,0 +1,461 @@
+// Anchor geometry — ported from the prototype's lib/shell/anchor_geometry.dart.
+//
+// All coordinates are GLOBAL TOP-LEFT. The Rust side
+// (coordinate_space.rs) is the sole authority for AppKit flips; this layer
+// never sees bottom-left coordinates.
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/** A display in global top-left coordinates. */
+export interface ScreenInfo {
+  /** Full screen bounds. */
+  frame: Rect;
+  /** Bounds excluding the menu bar, notch, and Dock. */
+  visibleFrame: Rect;
+  isMain?: boolean;
+}
+
+/**
+ * Geometry for the expanded (popover) state.
+ *
+ * The invariant: the avatar must not move on screen when the popover opens.
+ * The window grows to the bounding box of the avatar and the popover card,
+ * and both are positioned inside it.
+ */
+export interface ExpandedLayout {
+  /** New panel frame in global top-left coordinates. */
+  windowFrame: Rect;
+  /** Avatar position within the window (local coordinates). */
+  avatarRect: Rect;
+  /** Popover card position within the window (local coordinates). */
+  popoverRect: Rect;
+  /** Whether the popover opens above the avatar; ignored for side placement. */
+  popoverAbove: boolean;
+  /** Side placement used for the popover, or null for vertical placement. */
+  popoverSide: "left" | "right" | null;
+}
+
+export const rect = (
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+): Rect => ({
+  x,
+  y,
+  width,
+  height,
+});
+
+export const rectRight = (r: Rect): number => r.x + r.width;
+export const rectBottom = (r: Rect): number => r.y + r.height;
+export const rectCenter = (r: Rect): { x: number; y: number } => ({
+  x: r.x + r.width / 2,
+  y: r.y + r.height / 2,
+});
+
+export function popoverGlobal(layout: ExpandedLayout): Rect {
+  return rect(
+    layout.windowFrame.x + layout.popoverRect.x,
+    layout.windowFrame.y + layout.popoverRect.y,
+    layout.popoverRect.width,
+    layout.popoverRect.height,
+  );
+}
+
+export function rectContains(r: Rect, p: { x: number; y: number }): boolean {
+  return p.x >= r.x && p.x < rectRight(r) && p.y >= r.y && p.y < rectBottom(r);
+}
+
+export function rectsIntersect(a: Rect, b: Rect): boolean {
+  return (
+    a.x < rectRight(b) &&
+    b.x < rectRight(a) &&
+    a.y < rectBottom(b) &&
+    b.y < rectBottom(a)
+  );
+}
+
+/**
+ * Breathing room the window frame reserves around the popover card so its
+ * CSS box-shadow isn't clipped at the window edge (the card used to fill
+ * the window region exactly, cropping the shadow). Covers the largest
+ * shadow in desktop-agent.css (0 8px 32px).
+ */
+export const POPOVER_SHADOW_MARGIN = 24;
+
+/** Rect grown by `amount` on every side. */
+export function inflate(r: Rect, amount: number): Rect {
+  return rect(
+    r.x - amount,
+    r.y - amount,
+    r.width + 2 * amount,
+    r.height + 2 * amount,
+  );
+}
+
+/** Bounding box of two rects. */
+export function expandToInclude(a: Rect, b: Rect): Rect {
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return rect(
+    x,
+    y,
+    Math.max(rectRight(a), rectRight(b)) - x,
+    Math.max(rectBottom(a), rectBottom(b)) - y,
+  );
+}
+
+const clampNumber = (value: number, min: number, max: number): number =>
+  Math.min(Math.max(value, min), max);
+
+/**
+ * Returns the screen whose visible frame contains the point, the main
+ * screen, or the first screen, in that order of preference.
+ */
+export function screenContaining(
+  point: { x: number; y: number },
+  screens: ScreenInfo[],
+): ScreenInfo {
+  if (screens.length === 0)
+    throw new Error("screenContaining requires screens");
+  for (const screen of screens) {
+    if (rectContains(screen.visibleFrame, point)) return screen;
+  }
+  return screens.find((s) => s.isMain) ?? screens[0];
+}
+
+/**
+ * Clamps the avatar fully within the visible frame of the nearest screen.
+ * Used on launch (restored position may reference a disconnected display)
+ * and after drags.
+ */
+export function clampAvatarToScreens(
+  avatar: Rect,
+  screens: ScreenInfo[],
+): Rect {
+  const screen = screenContaining(rectCenter(avatar), screens);
+  const visible = screen.visibleFrame;
+  const x = clampNumber(avatar.x, visible.x, rectRight(visible) - avatar.width);
+  const y = clampNumber(
+    avatar.y,
+    visible.y,
+    rectBottom(visible) - avatar.height,
+  );
+  return rect(x, y, avatar.width, avatar.height);
+}
+
+function clampPopoverOrigin(args: {
+  requested: number;
+  visibleStart: number;
+  visibleEnd: number;
+  popoverExtent: number;
+  margin: number;
+}): number {
+  const min = args.visibleStart + args.margin;
+  const max = args.visibleEnd - args.margin - args.popoverExtent;
+  if (min > max) return min;
+  return clampNumber(args.requested, min, max);
+}
+
+/**
+ * Grows a side-placed composer-only popover into the full chat in place:
+ * same x, and the full layout's composer pill bottom lands where the
+ * composer-only pill's bottom was (the transcript appears above it).
+ * Only clamps vertically when the full height won't fit on-screen.
+ * Vertical (non-side) composer layouts fall back to computeExpandedLayout.
+ */
+export function computeGrownLayout(args: {
+  avatarGlobal: Rect;
+  fromPopoverGlobal: Rect;
+  composerBottomGlobal: number;
+  popoverSize: Size;
+  screens: ScreenInfo[];
+  /** Bottom distance from the full popover border box to the composer pill. */
+  bottomInset: number;
+  /** Side placement of the composer-only layout; null keeps legacy vertical growth. */
+  fromPopoverSide: "left" | "right" | null;
+}): ExpandedLayout {
+  const {
+    avatarGlobal,
+    fromPopoverGlobal,
+    composerBottomGlobal,
+    popoverSize,
+    screens,
+    bottomInset,
+    fromPopoverSide,
+  } = args;
+  const margin = 12;
+
+  if (fromPopoverSide === null) {
+    return computeExpandedLayout({ avatarGlobal, popoverSize, screens });
+  }
+
+  const screen = screenContaining(rectCenter(avatarGlobal), screens);
+  const visible = screen.visibleFrame;
+  const requestedTop = composerBottomGlobal + bottomInset - popoverSize.height;
+  const clampedTop = clampPopoverOrigin({
+    requested: requestedTop,
+    visibleStart: visible.y,
+    visibleEnd: rectBottom(visible),
+    popoverExtent: popoverSize.height,
+    margin,
+  });
+
+  return expandedLayoutFromGlobals({
+    avatarGlobal,
+    popoverGlobal: rect(
+      fromPopoverGlobal.x,
+      clampedTop,
+      popoverSize.width,
+      popoverSize.height,
+    ),
+    popoverAbove: false,
+    popoverSide: fromPopoverSide,
+  });
+}
+
+export type ExpandedPlacement = "vertical" | "side";
+
+function expandedLayoutFromGlobals(args: {
+  avatarGlobal: Rect;
+  popoverGlobal: Rect;
+  popoverAbove: boolean;
+  popoverSide: "left" | "right" | null;
+}): ExpandedLayout {
+  const { avatarGlobal, popoverGlobal } = args;
+  // The window grows past the popover by the shadow margin so the card's
+  // box-shadow has room to paint. Only the WINDOW inflates — the popover
+  // and avatar keep their global rects, so nothing moves on screen.
+  const windowGlobal = expandToInclude(
+    avatarGlobal,
+    inflate(popoverGlobal, POPOVER_SHADOW_MARGIN),
+  );
+
+  return {
+    windowFrame: windowGlobal,
+    avatarRect: rect(
+      avatarGlobal.x - windowGlobal.x,
+      avatarGlobal.y - windowGlobal.y,
+      avatarGlobal.width,
+      avatarGlobal.height,
+    ),
+    popoverRect: rect(
+      popoverGlobal.x - windowGlobal.x,
+      popoverGlobal.y - windowGlobal.y,
+      popoverGlobal.width,
+      popoverGlobal.height,
+    ),
+    popoverAbove: args.popoverAbove,
+    popoverSide: args.popoverSide,
+  };
+}
+
+function computeSideRoom(args: {
+  avatarGlobal: Rect;
+  visible: Rect;
+  gap: number;
+  margin: number;
+  popoverWidth: number;
+  preferRight: boolean;
+}): { side: "left" | "right"; left: number; fits: boolean } {
+  const { avatarGlobal, visible, gap, margin, popoverWidth, preferRight } =
+    args;
+  const roomRight = rectRight(visible) - margin - rectRight(avatarGlobal) - gap;
+  const roomLeft = avatarGlobal.x - gap - (visible.x + margin);
+  const preferred: "left" | "right" = preferRight ? "right" : "left";
+  const fallback: "left" | "right" = preferRight ? "left" : "right";
+  const preferredRoom = preferRight ? roomRight : roomLeft;
+  const fallbackRoom = preferRight ? roomLeft : roomRight;
+  const side =
+    preferredRoom >= popoverWidth || preferredRoom >= fallbackRoom
+      ? preferred
+      : fallback;
+
+  return {
+    side,
+    left:
+      side === "left"
+        ? avatarGlobal.x - gap - popoverWidth
+        : rectRight(avatarGlobal) + gap,
+    fits: (side === "left" ? roomLeft : roomRight) >= popoverWidth,
+  };
+}
+
+function computeVerticalExpandedLayout(args: {
+  avatarGlobal: Rect;
+  popoverSize: Size;
+  visible: Rect;
+  gap: number;
+  margin: number;
+}): ExpandedLayout {
+  const { avatarGlobal, popoverSize, visible, gap, margin } = args;
+
+  // Vertical: "lower half" means center.y past the visible midpoint.
+  const preferAbove = rectCenter(avatarGlobal).y > rectCenter(visible).y;
+  const spaceAbove = avatarGlobal.y - visible.y - gap - margin;
+  const spaceBelow =
+    rectBottom(visible) - rectBottom(avatarGlobal) - gap - margin;
+  const above = preferAbove
+    ? spaceAbove >= popoverSize.height || spaceAbove >= spaceBelow
+    : !(spaceBelow >= popoverSize.height || spaceBelow >= spaceAbove);
+
+  const popTopGlobal = above
+    ? avatarGlobal.y - gap - popoverSize.height
+    : rectBottom(avatarGlobal) + gap;
+  const clampedPopTop = clampPopoverOrigin({
+    requested: popTopGlobal,
+    visibleStart: visible.y,
+    visibleEnd: rectBottom(visible),
+    popoverExtent: popoverSize.height,
+    margin,
+  });
+
+  // Horizontal: center on the avatar, clamped to the visible frame.
+  const popLeftGlobal = rectCenter(avatarGlobal).x - popoverSize.width / 2;
+  const clampedPopLeft = clampPopoverOrigin({
+    requested: popLeftGlobal,
+    visibleStart: visible.x,
+    visibleEnd: rectRight(visible),
+    popoverExtent: popoverSize.width,
+    margin,
+  });
+
+  let popoverGlobal = rect(
+    clampedPopLeft,
+    clampedPopTop,
+    popoverSize.width,
+    popoverSize.height,
+  );
+  let popoverSide: "left" | "right" | null = null;
+
+  // No-occlusion invariant: near screen corners the
+  // vertical clamp can slide the popover back over the avatar, hiding the
+  // thing you interact with. If the clamped rects overlap, fall back to
+  // SIDE placement — beside the avatar on whichever side has more room —
+  // keeping the clamped vertical position.
+  if (rectsIntersect(popoverGlobal, avatarGlobal)) {
+    const sideRoom = computeSideRoom({
+      avatarGlobal,
+      visible,
+      gap,
+      margin,
+      popoverWidth: popoverSize.width,
+      preferRight: true,
+    });
+    const clampedSideLeft = clampPopoverOrigin({
+      requested: sideRoom.left,
+      visibleStart: visible.x,
+      visibleEnd: rectRight(visible),
+      popoverExtent: popoverSize.width,
+      margin,
+    });
+    const sideCandidate = rect(
+      clampedSideLeft,
+      clampedPopTop,
+      popoverSize.width,
+      popoverSize.height,
+    );
+    // Degenerate case (popover wider than the visible frame): the side
+    // clamp can land back over the avatar. Last resort: overlap but slide
+    // vertically off the avatar so it stays clickable (invariant honest
+    // even when the screen genuinely can't fit both side by side).
+    if (rectsIntersect(sideCandidate, avatarGlobal)) {
+      const below = rectBottom(avatarGlobal) + gap;
+      const aboveTop = avatarGlobal.y - gap - popoverSize.height;
+      popoverGlobal = rect(
+        clampedSideLeft,
+        aboveTop >= visible.y + margin ? aboveTop : below,
+        popoverSize.width,
+        popoverSize.height,
+      );
+    } else {
+      popoverGlobal = sideCandidate;
+      popoverSide = sideRoom.side;
+    }
+  }
+
+  return expandedLayoutFromGlobals({
+    avatarGlobal,
+    popoverGlobal,
+    popoverAbove: above,
+    popoverSide,
+  });
+}
+
+/**
+ * Computes the expanded panel layout for an avatar at avatarGlobal.
+ *
+ * The popover opens above the avatar when the avatar sits in the lower half
+ * of its screen's visible frame (and below otherwise), preferring whichever
+ * side has room. Horizontally it centers on the avatar, clamped fully
+ * on-screen. The avatar's global rect never changes. Composer-only callers
+ * may request side placement so the pill sits like a speech bubble beside
+ * the avatar.
+ */
+
+export function computeExpandedLayout(args: {
+  avatarGlobal: Rect;
+  popoverSize: Size;
+  screens: ScreenInfo[];
+  gap?: number;
+  margin?: number;
+  placement?: ExpandedPlacement;
+}): ExpandedLayout {
+  const { avatarGlobal, popoverSize, screens } = args;
+  const gap = args.gap ?? 8;
+  const margin = args.margin ?? 12;
+
+  const screen = screenContaining(rectCenter(avatarGlobal), screens);
+  const visible = screen.visibleFrame;
+
+  if (args.placement === "side") {
+    const clampedTop = clampPopoverOrigin({
+      requested: rectCenter(avatarGlobal).y - popoverSize.height / 2,
+      visibleStart: visible.y,
+      visibleEnd: rectBottom(visible),
+      popoverExtent: popoverSize.height,
+      margin,
+    });
+    const sideRoom = computeSideRoom({
+      avatarGlobal,
+      visible,
+      gap,
+      margin,
+      popoverWidth: popoverSize.width,
+      preferRight: rectCenter(avatarGlobal).x <= rectCenter(visible).x,
+    });
+
+    if (sideRoom.fits) {
+      return expandedLayoutFromGlobals({
+        avatarGlobal,
+        popoverGlobal: rect(
+          sideRoom.left,
+          clampedTop,
+          popoverSize.width,
+          popoverSize.height,
+        ),
+        popoverAbove: false,
+        popoverSide: sideRoom.side,
+      });
+    }
+  }
+
+  return computeVerticalExpandedLayout({
+    avatarGlobal,
+    popoverSize,
+    visible,
+    gap,
+    margin,
+  });
+}
diff --git a/src/features/desktop-agent/lib/avatarState.test.ts b/src/features/desktop-agent/lib/avatarState.test.ts
new file mode 100644
index 000000000..38926c4da
--- /dev/null
+++ b/src/features/desktop-agent/lib/avatarState.test.ts
@@ -0,0 +1,83 @@
+// Ported from the prototype's avatar_state_controller semantics: derivation priority
+// debugOverride > disconnected > activity > expanded > hover > idle.
+
+import { describe, expect, test } from "vitest";
+
+import {
+  deriveAvatarState,
+  treatmentFor,
+  type AvatarInputs,
+} from "./avatarState";
+
+const base: AvatarInputs = {
+  hovering: false,
+  expanded: false,
+  connected: true,
+  activity: "none",
+};
+
+describe("deriveAvatarState", () => {
+  test("idle by default", () => {
+    expect(deriveAvatarState(base)).toBe("idle");
+  });
+
+  test("hover when pointer over and nothing else going on", () => {
+    expect(deriveAvatarState({ ...base, hovering: true })).toBe("hover");
+  });
+
+  test("listening when expanded beats hover", () => {
+    expect(deriveAvatarState({ ...base, hovering: true, expanded: true })).toBe(
+      "listening",
+    );
+  });
+
+  test("activity beats expanded and hover", () => {
+    expect(
+      deriveAvatarState({
+        ...base,
+        hovering: true,
+        expanded: true,
+        activity: "thinking",
+      }),
+    ).toBe("thinking");
+    expect(
+      deriveAvatarState({ ...base, expanded: true, activity: "responding" }),
+    ).toBe("responding");
+  });
+
+  test("disconnected beats everything except debug override", () => {
+    expect(
+      deriveAvatarState({
+        ...base,
+        connected: false,
+        activity: "thinking",
+        expanded: true,
+      }),
+    ).toBe("error");
+  });
+
+  test("debug override wins outright", () => {
+    expect(
+      deriveAvatarState({ ...base, connected: false, debugOverride: "hover" }),
+    ).toBe("hover");
+  });
+});
+
+describe("treatmentFor", () => {
+  test("thinking and responding speed the loop up", () => {
+    expect(treatmentFor("thinking").playbackRate).toBe(1.6);
+    expect(treatmentFor("responding").playbackRate).toBe(1.6);
+    expect(treatmentFor("idle").playbackRate).toBe(1.0);
+  });
+
+  test("error pauses and desaturates", () => {
+    const t = treatmentFor("error");
+    expect(t.paused).toBe(true);
+    expect(t.desaturated).toBe(true);
+  });
+
+  test("hover scales 1.025 (fits inside the 90pt panel)", () => {
+    expect(treatmentFor("hover").scale).toBe(1.025);
+    expect(treatmentFor("idle").scale).toBe(1.0);
+  });
+});
diff --git a/src/features/desktop-agent/lib/avatarState.ts b/src/features/desktop-agent/lib/avatarState.ts
new file mode 100644
index 000000000..de3e57496
--- /dev/null
+++ b/src/features/desktop-agent/lib/avatarState.ts
@@ -0,0 +1,96 @@
+// Ported from the prototype's lib/avatar/avatar_state.dart + avatar_state_controller.dart.
+//
+// The state is always DERIVED from independent facts, never transitioned
+// imperatively — stale states cannot get stuck (berd-mobile spec rule:
+// activity indicators clear from authoritative updates, not lingering local
+// state).
+
+export type AvatarState =
+  | "idle" //       default: subtle breathing/blink loop
+  | "hover" //      mouse over: perk up (slight scale)
+  | "listening" //  popover open: attentive
+  | "thinking" //   prompt sent, awaiting first chunk: faster loop
+  | "responding" // chunks streaming: faster loop
+  | "error"; //     disconnected: paused + desaturated
+
+export type AvatarActivity = "none" | "thinking" | "responding";
+
+export interface AvatarInputs {
+  hovering: boolean;
+  expanded: boolean;
+  /** Optimistically true at startup so the avatar doesn't flash the error
+   *  treatment before the first connection attempt resolves. */
+  connected: boolean;
+  activity: AvatarActivity;
+  debugOverride?: AvatarState | null;
+}
+
+/**
+ * Priority (highest wins): debugOverride > disconnected > activity >
+ * expanded > hover > idle. Pure — the prototype's controller getter as a function.
+ */
+export function deriveAvatarState(inputs: AvatarInputs): AvatarState {
+  if (inputs.debugOverride) return inputs.debugOverride;
+  if (!inputs.connected) return "error";
+  switch (inputs.activity) {
+    case "thinking":
+      return "thinking";
+    case "responding":
+      return "responding";
+    case "none":
+      return inputs.expanded ? "listening" : inputs.hovering ? "hover" : "idle";
+  }
+}
+
+/** Playback treatment for a state. */
+export function treatmentFor(state: AvatarState): {
+  playbackRate: number;
+  paused: boolean;
+  desaturated: boolean;
+  scale: number;
+} {
+  return {
+    playbackRate: state === "thinking" || state === "responding" ? 1.6 : 1.0,
+    paused: state === "error",
+    desaturated: state === "error",
+    scale: state === "hover" ? 1.025 : 1.0,
+  };
+}
+
+/** Avatar chip shape. */
+export type AvatarShape = "circle" | "roundedSquare";
+
+export interface AvatarChoice {
+  id: string;
+  label: string;
+  /** Path under the site root (public/), or a data: URI for agent
+   *  avatars pulled from Berd's artifact catalog. */
+  src: string;
+  shape: AvatarShape;
+  /** Bundled avatars are HEVC loops; agent avatars are static images.
+   *  Static avatars ignore playbackRate/paused treatments (nothing to
+   *  animate) but keep scale/desaturation. */
+  kind: "video" | "image";
+  /** Per-avatar render scale (default 1.0), applied to the CHIP only —
+   *  panel frame, hit target, and perch geometry stay at full size. The
+   *  Berd logo reads visually heavier than the gloopies at equal pixels
+   *  (the Berd logo renders 30% smaller). */
+  renderScale?: number;
+}
+
+/** The bundled default avatar (agent avatars resolve from Berd's avatar
+ *  catalog at runtime — see useAgentAvatar). The Berd gloopy (gloopies-22,
+ *  2026-08-13 avatar pack): the default identity lands on a character,
+ *  not an icon (2026-08-19 decision, replacing the Berd logo chip). */
+export const DEFAULT_AVATAR: AvatarChoice = {
+  id: "berd-gloopy",
+  label: "Berd",
+  src: "/desktop-agent/gloopies-22.mp4",
+  shape: "circle",
+  kind: "video",
+};
+
+/** Chip corner radius: circle = size/2; rounded square = size * 0.23. */
+export function cornerRadius(shape: AvatarShape, size: number): number {
+  return shape === "circle" ? size / 2 : size * 0.23;
+}
diff --git a/src/features/desktop-agent/lib/berdyClips.ts b/src/features/desktop-agent/lib/berdyClips.ts
new file mode 100644
index 000000000..b600c8abf
--- /dev/null
+++ b/src/features/desktop-agent/lib/berdyClips.ts
@@ -0,0 +1,182 @@
+export type BerdyPose = "idle" | "dangle" | "sit";
+
+export type BerdyClipKey =
+  | "idle1"
+  | "idle2"
+  | "idle3"
+  | "idle4"
+  | "idleToDangle"
+  | "dangleLoop"
+  | "dangleToIdle"
+  | "dangleToSit"
+  | "sitToDangle"
+  | "sitIdle1"
+  | "sitIdle2"
+  | "sitIdle3";
+
+export interface BerdyClip {
+  key: BerdyClipKey;
+  file: string;
+  from: BerdyPose;
+  to: BerdyPose;
+}
+
+const ASSET_DIR = "/desktop-agent/berdy/";
+
+export const BERDY_CLIPS: Record<BerdyClipKey, BerdyClip> = {
+  idle1: {
+    key: "idle1",
+    file: `${ASSET_DIR}berdy_Idle_01_00001_.mp4`,
+    from: "idle",
+    to: "idle",
+  },
+  idle2: {
+    key: "idle2",
+    file: `${ASSET_DIR}berdy_Idle_02_00001_.mp4`,
+    from: "idle",
+    to: "idle",
+  },
+  idle3: {
+    key: "idle3",
+    file: `${ASSET_DIR}berdy_Idle_03_00001_.mp4`,
+    from: "idle",
+    to: "idle",
+  },
+  idle4: {
+    key: "idle4",
+    file: `${ASSET_DIR}berdy_Idle_04_00001_.mp4`,
+    from: "idle",
+    to: "idle",
+  },
+  idleToDangle: {
+    key: "idleToDangle",
+    file: `${ASSET_DIR}berdy_IdleToDangle_00001_.mp4`,
+    from: "idle",
+    to: "dangle",
+  },
+  dangleLoop: {
+    key: "dangleLoop",
+    file: `${ASSET_DIR}berdy_DangleToDangle_00001_.mp4`,
+    from: "dangle",
+    to: "dangle",
+  },
+  dangleToIdle: {
+    key: "dangleToIdle",
+    file: `${ASSET_DIR}berdy_DangleToIdle_00001_.mp4`,
+    from: "dangle",
+    to: "idle",
+  },
+  dangleToSit: {
+    key: "dangleToSit",
+    file: `${ASSET_DIR}berdy_DangleToSit_00001_.mp4`,
+    from: "dangle",
+    to: "sit",
+  },
+  sitToDangle: {
+    key: "sitToDangle",
+    file: `${ASSET_DIR}berdy_SitToDangle_00001_.mp4`,
+    from: "sit",
+    to: "dangle",
+  },
+  sitIdle1: {
+    key: "sitIdle1",
+    file: `${ASSET_DIR}berdy_Sit_Idle_01_00001_.mp4`,
+    from: "sit",
+    to: "sit",
+  },
+  sitIdle2: {
+    key: "sitIdle2",
+    file: `${ASSET_DIR}berdy_Sit_Idle_02_00001_.mp4`,
+    from: "sit",
+    to: "sit",
+  },
+  sitIdle3: {
+    key: "sitIdle3",
+    file: `${ASSET_DIR}berdy_Sit_Idle_03_00001_.mp4`,
+    from: "sit",
+    to: "sit",
+  },
+};
+
+export const IDLE_CLIPS = ["idle1", "idle2", "idle3", "idle4"] as const;
+export const SIT_CLIPS = ["sitIdle1", "sitIdle2", "sitIdle3"] as const;
+
+export const ANCHOR = {
+  idleFootY: 374 / 400,
+  sitButtY: 0.74,
+  grabX: 0.4875,
+  grabY: 0.125,
+} as const;
+
+export const SPEED = {
+  base: 1.3,
+  hurry: 3.0,
+  hurryTransitions: true,
+} as const;
+
+/** Media clocks are losslessly pre-timed 1.5x (36fps instead of 24fps).
+ * Divide source-space rates by this factor to preserve product timing while
+ * keeping native playback <=2x: WK otherwise drops to keyframes at hurry.
+ * All samples/alpha/end poses are unchanged; see scripts/retime-berdy-media.py.
+ */
+export const BERDY_MEDIA_TIME_SCALE = 1.5;
+
+export function playbackRateFor(
+  clip: BerdyClip,
+  target: BerdyPose,
+  speed: typeof SPEED = SPEED,
+) {
+  const onTarget = clip.to === target;
+  const atRest = onTarget && clip.from === clip.to;
+  return atRest || (onTarget && !speed.hurryTransitions)
+    ? speed.base
+    : speed.hurry;
+}
+
+export interface LoopPicker {
+  nextIdle(): BerdyClipKey;
+  nextSit(): BerdyClipKey;
+}
+
+export function createLoopPicker(
+  random = Math.random,
+  randomIdle = true,
+): LoopPicker {
+  let idleIdx = -1;
+  let sitIdx = -1;
+
+  const pick = (clips: readonly BerdyClipKey[], lastIdx: number) => {
+    if (!randomIdle) return (lastIdx + 1) % clips.length;
+    if (clips.length <= 1) return 0;
+    let next = Math.floor(random() * clips.length);
+    if (next === lastIdx) next = (next + 1) % clips.length;
+    return next;
+  };
+
+  return {
+    nextIdle() {
+      idleIdx = pick(IDLE_CLIPS, idleIdx);
+      return IDLE_CLIPS[idleIdx];
+    },
+    nextSit() {
+      sitIdx = pick(SIT_CLIPS, sitIdx);
+      return SIT_CLIPS[sitIdx];
+    },
+  };
+}
+
+export function nextClipFor(
+  state: BerdyPose,
+  target: BerdyPose,
+  picker: LoopPicker,
+): BerdyClipKey {
+  if (state === "idle") {
+    return target === "idle" ? picker.nextIdle() : "idleToDangle";
+  }
+  if (state === "dangle") {
+    if (target === "idle") return "dangleToIdle";
+    if (target === "sit") return "dangleToSit";
+    return "dangleLoop";
+  }
+  return target === "sit" ? picker.nextSit() : "sitToDangle";
+}
diff --git a/src/features/desktop-agent/lib/berdyMachine.test.ts b/src/features/desktop-agent/lib/berdyMachine.test.ts
new file mode 100644
index 000000000..6ab5ad8d8
--- /dev/null
+++ b/src/features/desktop-agent/lib/berdyMachine.test.ts
@@ -0,0 +1,418 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  BERDY_CLIPS,
+  BERDY_MEDIA_TIME_SCALE,
+  createLoopPicker,
+  nextClipFor,
+  playbackRateFor,
+  type BerdyPose,
+} from "@/features/desktop-agent/lib/berdyClips";
+import { BerdyMachine } from "@/features/desktop-agent/lib/berdyMachine";
+
+class Video extends EventTarget {
+  private time = 0;
+  get currentTime() {
+    return this.time;
+  }
+  set currentTime(value: number) {
+    this.time = value;
+    this.ended = false;
+  }
+  duration = 5.083984375 / BERDY_MEDIA_TIME_SCALE;
+  playbackRate = 1;
+  paused = true;
+  ended = false;
+  error = null;
+  muted = false;
+  playsInline = false;
+  preload = "";
+  src = "";
+  videoWidth = 400;
+  readyState = 2;
+  seeking = false;
+  callbacks = new Map<number, VideoFrameRequestCallback>();
+  next = 0;
+  load = vi.fn();
+  play = vi.fn(async () => {
+    this.paused = false;
+  });
+  pause = vi.fn(() => {
+    this.paused = true;
+  });
+  removeAttribute = vi.fn();
+  requestVideoFrameCallback(cb: VideoFrameRequestCallback) {
+    this.callbacks.set(++this.next, cb);
+    return this.next;
+  }
+  cancelVideoFrameCallback(id: number) {
+    this.callbacks.delete(id);
+  }
+  frame() {
+    const callbacks = [...this.callbacks.values()];
+    this.callbacks.clear();
+    for (const cb of callbacks) cb(0, {} as VideoFrameCallbackMetadata);
+  }
+  end() {
+    this.ended = true;
+    this.dispatchEvent(new Event("ended"));
+  }
+}
+
+function fixture() {
+  const videos: Video[] = [];
+  const drawImage = vi.fn();
+  const clearRect = vi.fn();
+  const context = {
+    drawImage,
+    clearRect,
+    globalCompositeOperation: "source-over",
+  };
+  const canvas = {
+    width: 400,
+    height: 400,
+    getContext: () => context,
+  } as unknown as HTMLCanvasElement;
+  const ready = vi.fn();
+  const machine = new BerdyMachine({
+    canvas,
+    random: () => 0,
+    onReady: ready,
+    createVideo: () => {
+      const video = new Video();
+      videos.push(video);
+      return video as unknown as HTMLVideoElement;
+    },
+  });
+  return { machine, videos, drawImage, clearRect, ready, context };
+}
+
+describe("frozen clip graph", () => {
+  it("routes every state/target pair and preserves legal two-hop edges", () => {
+    const picker = createLoopPicker(() => 0);
+    const poses: BerdyPose[] = ["idle", "dangle", "sit"];
+    const expected = [
+      ["idle1", "idleToDangle", "idleToDangle"],
+      ["dangleToIdle", "dangleLoop", "dangleToSit"],
+      ["sitToDangle", "sitToDangle", "sitIdle1"],
+    ];
+    poses.forEach((from, i) => {
+      poses.forEach((target, j) => {
+        const key = nextClipFor(from, target, picker);
+        expect(key).toBe(expected[i][j]);
+        expect(BERDY_CLIPS[key].from).toBe(from);
+      });
+    });
+  });
+  it("uses 1.3 only at rest on target; every other combination hurries at 3", () => {
+    for (const clip of Object.values(BERDY_CLIPS)) {
+      for (const target of ["idle", "dangle", "sit"] as const) {
+        expect(playbackRateFor(clip, target)).toBe(
+          clip.from === target && clip.to === target ? 1.3 : 3,
+        );
+      }
+    }
+  });
+  it("preserves source-space duration at both speeds with native rates <=2", () => {
+    const sourceDuration = 5.083984375;
+    const mediaDuration = sourceDuration / BERDY_MEDIA_TIME_SCALE;
+    for (const clip of Object.values(BERDY_CLIPS)) {
+      for (const target of ["idle", "dangle", "sit"] as const) {
+        const effectiveRate = playbackRateFor(clip, target);
+        const nativeRate = effectiveRate / BERDY_MEDIA_TIME_SCALE;
+        expect(nativeRate).toBeLessThanOrEqual(2);
+        expect(mediaDuration / nativeRate).toBeCloseTo(
+          sourceDuration / effectiveRate,
+          12,
+        );
+      }
+    }
+  });
+  it("never immediately repeats idle or seated loops", () => {
+    const picker = createLoopPicker(() => 0);
+    let idle = picker.nextIdle();
+    let sit = picker.nextSit();
+    for (let i = 0; i < 50; i++) {
+      const nextIdle = picker.nextIdle();
+      const nextSit = picker.nextSit();
+      expect(nextIdle).not.toBe(idle);
+      expect(nextSit).not.toBe(sit);
+      idle = nextIdle;
+      sit = nextSit;
+    }
+  });
+});
+
+describe("Berdy controller", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+  it("clears old alpha pixels immediately before each drawable frame, never while unavailable", async () => {
+    const { machine, videos, drawImage, clearRect, context } = fixture();
+    machine.start();
+    await vi.advanceTimersByTimeAsync(7200);
+    const idle = videos[0];
+    const operations: string[] = [];
+    clearRect.mockImplementation(() => operations.push("clear"));
+    drawImage.mockImplementation(() => {
+      expect(context.globalCompositeOperation).toBe("source-over");
+      operations.push("draw");
+    });
+    idle.frame();
+    idle.frame();
+    expect(operations).toEqual(["clear", "draw", "clear", "draw"]);
+    expect(clearRect).toHaveBeenNthCalledWith(1, 0, 0, 400, 400);
+    expect(clearRect).toHaveBeenNthCalledWith(2, 0, 0, 400, 400);
+    idle.readyState = 1;
+    idle.frame();
+    idle.readyState = 2;
+    idle.seeking = true;
+    idle.frame();
+    idle.seeking = false;
+    idle.videoWidth = 0;
+    idle.frame();
+    expect(clearRect).toHaveBeenCalledTimes(2);
+    expect(drawImage).toHaveBeenCalledTimes(2);
+    machine.suspend();
+    expect(clearRect).toHaveBeenCalledTimes(2);
+    machine.dispose();
+  });
+  it("interrupts steady loops immediately, keeps in-flight edges coherent and routes the latest target", async () => {
+    const { machine, videos, ready, drawImage, clearRect } = fixture();
+    machine.start();
+    await vi.advanceTimersByTimeAsync(7200);
+    const idle = videos[0];
+    idle.frame();
+    expect(ready).toHaveBeenCalledOnce();
+    const staleFrame = [...idle.callbacks.values()][0];
+    idle.currentTime = 2;
+    machine.setTarget("dangle");
+    expect(idle.paused).toBe(true);
+    expect(idle.callbacks.size).toBe(0);
+    expect(videos[4].paused).toBe(false);
+    expect(videos[4].playbackRate).toBe(2);
+    staleFrame(0, {} as VideoFrameCallbackMetadata);
+    idle.end(); // old decoder's callbacks cannot route/draw over the new one
+    expect(drawImage).toHaveBeenCalledOnce();
+    videos[4].readyState = 1;
+    videos[4].frame();
+    expect(clearRect).toHaveBeenCalledOnce(); // keep last pixels until ready
+    videos[4].currentTime = 0.75;
+    const plays = videos[4].play.mock.calls.length;
+    for (const target of ["idle", "sit", "dangle", "sit"] as const) {
+      machine.setTarget(target);
+      expect(videos[4].currentTime).toBe(0.75);
+      expect(videos[4].play).toHaveBeenCalledTimes(plays);
+    }
+    videos[4].end();
+    expect(videos[7].paused).toBe(false); // latest sit, never an idle hop
+    videos[7].end();
+    expect(videos[9].paused).toBe(false);
+    expect(videos[9].playbackRate).toBe(1.3 / BERDY_MEDIA_TIME_SCALE);
+    machine.setTarget("idle"); // seated loop interrupts via sit->dangle
+    expect(videos[9].paused).toBe(true);
+    expect(videos[8].paused).toBe(false);
+    machine.setTarget("dangle");
+    videos[8].end();
+    expect(videos[5].paused).toBe(false);
+    machine.setTarget("idle"); // dangle loop also interrupts immediately
+    expect(videos[5].paused).toBe(true);
+    expect(videos[6].paused).toBe(false);
+    machine.dispose();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("does not restart unchanged targets or seek in-flight transitions, including suspend/resume", async () => {
+    const { machine, videos } = fixture();
+    machine.start();
+    await vi.advanceTimersByTimeAsync(7200);
+    const idle = videos[0];
+    idle.currentTime = 1.25;
+    const plays = idle.play.mock.calls.length;
+    machine.setTarget("idle");
+    expect(idle.currentTime).toBe(1.25);
+    expect(idle.play).toHaveBeenCalledTimes(plays);
+    machine.suspend();
+    const totalPlays = videos.map((v) => v.play.mock.calls.length);
+    machine.setTarget("sit");
+    expect(videos.map((v) => v.play.mock.calls.length)).toEqual(totalPlays);
+    machine.resume();
+    expect(videos[4].paused).toBe(false); // don't resume the obsolete idle loop
+    videos[4].currentTime = 1;
+    machine.setTarget("idle");
+    machine.suspend();
+    machine.setTarget("dangle");
+    machine.resume();
+    expect(videos[4].currentTime).toBe(1);
+    expect(videos[4].playbackRate).toBe(2);
+    videos[4].end();
+    expect(videos[5].paused).toBe(false);
+    const danglePlays = videos[5].play.mock.calls.length;
+    videos[5].currentTime = 0.5;
+    machine.setTarget("dangle");
+    expect(videos[5].currentTime).toBe(0.5);
+    expect(videos[5].play).toHaveBeenCalledTimes(danglePlays);
+    machine.dispose();
+  });
+
+  it("starts at the requested edge after warming rather than waiting for an idle loop", async () => {
+    const { machine, videos } = fixture();
+    machine.setTarget("sit");
+    machine.start();
+    await vi.advanceTimersByTimeAsync(7200);
+    expect(videos[0].paused).toBe(true);
+    expect(videos[4].paused).toBe(false);
+    machine.dispose();
+  });
+
+  it("parks before startup and during warm-up; resumes and frees all callbacks/timers", async () => {
+    const { machine, videos } = fixture();
+    machine.suspend();
+    machine.start();
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(videos.every((v) => v.play.mock.calls.length === 0)).toBe(true);
+    machine.resume();
+    await vi.advanceTimersByTimeAsync(100);
+    machine.suspend();
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(videos.every((v) => v.paused && v.callbacks.size === 0)).toBe(true);
+    expect(vi.getTimerCount()).toBe(0);
+    machine.resume();
+    await vi.advanceTimersByTimeAsync(7200);
+    expect(videos[0].paused).toBe(false);
+    machine.suspend();
+    videos[0].ended = true;
+    machine.setTarget("sit");
+    machine.resume();
+    expect(videos[4].paused).toBe(false);
+    machine.dispose();
+    expect(vi.getTimerCount()).toBe(0);
+    expect(videos.every((v) => v.callbacks.size === 0)).toBe(true);
+  });
+  it("recovers lost-ended and external pause; microseek cannot mask a permanent stall", async () => {
+    const { machine, videos } = fixture();
+    machine.start();
+    await vi.advanceTimersByTimeAsync(7200);
+    const idle = videos[0];
+    idle.paused = true;
+    await vi.advanceTimersByTimeAsync(700);
+    expect(idle.paused).toBe(false);
+    await vi.advanceTimersByTimeAsync(4500);
+    expect(idle.load).toHaveBeenCalled();
+    machine.setTarget("dangle");
+    idle.ended = true;
+    await vi.advanceTimersByTimeAsync(500);
+    expect(videos[4].paused).toBe(false);
+    machine.dispose();
+  });
+  it.each([
+    "idle",
+    "sit",
+  ] as const)("recovers when the %s picker re-enters a failed loop", async (pose) => {
+    const { machine, videos, drawImage } = fixture();
+    machine.start();
+    await vi.advanceTimersByTimeAsync(7200);
+    if (pose === "sit") {
+      machine.setTarget("sit");
+      videos[0].end();
+      videos[4].end();
+      videos[7].end();
+    }
+    const [first, second, third] = pose === "idle" ? videos : videos.slice(9);
+    first.frame();
+    first.dispatchEvent(new Event("error"));
+    expect(second.paused).toBe(false);
+    const failedPlays = first.play.mock.calls.length;
+    // Deterministic random=0 repeatedly selects the failed first clip.
+    let active = second;
+    for (let i = 0; i < 4; i++) {
+      active.ended = false;
+      active.currentTime = 2;
+      await vi.advanceTimersByTimeAsync(100);
+      expect(active.currentTime).toBe(2); // healthy media is never cut
+      const previous = active;
+      active.end();
+      expect(first.play).toHaveBeenCalledTimes(failedPlays);
+      const next = videos.find((video) => !video.paused);
+      expect(next).toBeDefined();
+      if (!next) throw new Error("missing active decoder");
+      active = next;
+      expect(active).not.toBe(previous); // no repeats with healthy siblings
+    }
+    second.dispatchEvent(new Event("error"));
+    expect(third.paused).toBe(false); // bounded scan, not a random retry loop
+    third.frame();
+    expect(drawImage).toHaveBeenCalledTimes(2);
+    machine.dispose();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it.each([
+    "watchdog",
+    "resume",
+  ])("parks on failed transitions without fabricating a destination; %s recovers on a new target", async (recovery) => {
+    const { machine, videos, drawImage } = fixture();
+    machine.start();
+    await vi.advanceTimersByTimeAsync(7200);
+    videos[0].frame();
+    // An inactive decoder failure cannot cut the healthy active clip.
+    videos[4].dispatchEvent(new Event("error"));
+    machine.setTarget("sit");
+    await vi.advanceTimersByTimeAsync(100);
+    expect(videos[0].paused).toBe(true);
+    videos[0].end();
+    const plays = videos.map((video) => video.play.mock.calls.length);
+    videos[4].end(); // a failed edge cannot signal a normal boundary
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(videos.map((video) => video.play.mock.calls.length)).toEqual(plays);
+    expect(drawImage).toHaveBeenCalledOnce();
+    expect(videos[7].paused).toBe(true); // idle->dangle never reached dangle
+    if (recovery === "resume") machine.suspend();
+    machine.setTarget("idle");
+    if (recovery === "resume") machine.resume();
+    else await vi.advanceTimersByTimeAsync(100);
+    expect(videos[1].paused).toBe(false);
+    machine.dispose();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("all-failed media stays bounded, retains pixels, and releases watchdog on hide/dispose", async () => {
+    const { machine, videos, drawImage } = fixture();
+    machine.start();
+    await vi.advanceTimersByTimeAsync(7200);
+    videos[0].frame();
+    // Fail inactive clips first, then the active one.
+    for (const video of [...videos.slice(1), videos[0]]) {
+      video.dispatchEvent(new Event("error"));
+    }
+    const plays = videos.map((video) => video.play.mock.calls.length);
+    for (const target of ["sit", "dangle", "idle"] as const) {
+      machine.setTarget(target);
+      await vi.advanceTimersByTimeAsync(10000);
+    }
+    expect(videos.map((video) => video.play.mock.calls.length)).toEqual(plays);
+    expect(
+      videos.every((video) => video.paused && video.callbacks.size === 0),
+    ).toBe(true);
+    expect(drawImage).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(1);
+    machine.suspend();
+    expect(vi.getTimerCount()).toBe(0);
+    machine.resume();
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(videos.map((video) => video.play.mock.calls.length)).toEqual(plays);
+    machine.dispose();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("disposal during warm-up cannot start more decoders", async () => {
+    const { machine, videos, ready } = fixture();
+    machine.start();
+    machine.dispose();
+    await vi.advanceTimersByTimeAsync(10000);
+    expect(videos.slice(1).every((v) => v.play.mock.calls.length === 0)).toBe(
+      true,
+    );
+    expect(ready).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});
diff --git a/src/features/desktop-agent/lib/berdyMachine.ts b/src/features/desktop-agent/lib/berdyMachine.ts
new file mode 100644
index 000000000..2be5d17ea
--- /dev/null
+++ b/src/features/desktop-agent/lib/berdyMachine.ts
@@ -0,0 +1,361 @@
+import {
+  BERDY_CLIPS,
+  BERDY_MEDIA_TIME_SCALE,
+  createLoopPicker,
+  nextClipFor,
+  playbackRateFor,
+  type BerdyClipKey,
+  type BerdyPose,
+} from "@/features/desktop-agent/lib/berdyClips";
+
+export interface BerdyMachineOptions {
+  canvas: HTMLCanvasElement;
+  createVideo?: () => HTMLVideoElement;
+  random?: () => number;
+  onReady?: () => void;
+}
+
+/** Steady loops yield immediately to a new target; pose-changing clips finish.
+ * Decoders stay off-DOM; the canvas retains its last frame across boundaries.
+ */
+export class BerdyMachine {
+  private readonly context: CanvasRenderingContext2D;
+  private readonly videos = new Map<BerdyClipKey, HTMLVideoElement>();
+  private readonly picker;
+  private active: BerdyClipKey | null = null;
+  private target: BerdyPose = "idle";
+  private suspended = false;
+  private disposed = false;
+  private started = false;
+  private ready = false;
+  private generation = 0;
+  private endedCancel: (() => void) | null = null;
+  private frameCancel: (() => void) | null = null;
+  private watchdog: number | null = null;
+  private warmCancel: (() => void) | null = null;
+  private warming = false;
+  private warmed = new Set<BerdyClipKey>();
+  private failed = new Set<BerdyClipKey>();
+  private lastTime = -1;
+  private lastProgress = 0;
+  private recovery = 0;
+  private endedSince = 0;
+
+  constructor(private readonly options: BerdyMachineOptions) {
+    const context = options.canvas.getContext("2d", { alpha: true });
+    if (!context) throw new Error("Berdy canvas 2D context unavailable");
+    this.context = context;
+    this.picker = createLoopPicker(options.random);
+    const create =
+      options.createVideo ?? (() => document.createElement("video"));
+    for (const clip of Object.values(BERDY_CLIPS)) {
+      const video = create();
+      video.muted = true;
+      video.playsInline = true;
+      video.preload = "auto";
+      video.src = clip.file;
+      video.addEventListener("error", this.onError);
+      this.videos.set(clip.key, video);
+    }
+  }
+
+  start() {
+    if (this.started || this.disposed) return;
+    this.started = true;
+    void this.prepare();
+  }
+
+  setTarget(target: BerdyPose) {
+    if (this.disposed || this.target === target) return;
+    this.target = target;
+    if (!this.suspended && this.interruptLoop()) return;
+    this.applyRate();
+  }
+
+  suspend() {
+    this.suspended = true;
+    this.cancelDraw();
+    this.stopWatchdog();
+    this.warmCancel?.();
+    for (const video of this.videos.values()) video.pause();
+  }
+
+  resume() {
+    if (this.disposed) return;
+    const wasSuspended = this.suspended;
+    this.suspended = false;
+    if (!this.started) return;
+    if (!this.active) {
+      void this.prepare();
+      return;
+    }
+    if (!wasSuspended) return;
+    const video = this.activeVideo();
+    this.resetLiveness();
+    if (this.failed.has(this.active)) this.recoverFailedClip();
+    else if (this.interruptLoop()) {
+      // Resume directly into the requested edge, not the old steady loop.
+    } else if (video?.ended) this.advance();
+    else {
+      this.applyRate();
+      this.play(video);
+      this.drawLoop();
+    }
+    this.startWatchdog();
+  }
+
+  dispose() {
+    this.disposed = true;
+    this.suspend();
+    for (const video of this.videos.values()) {
+      video.removeEventListener("error", this.onError);
+      video.removeAttribute("src");
+      video.load();
+    }
+    this.videos.clear();
+  }
+
+  private async prepare() {
+    if (this.warming || this.suspended || this.disposed) return;
+    this.warming = true;
+    for (const [key, video] of this.videos) {
+      if (this.disposed || this.suspended) break;
+      if (this.warmed.has(key)) continue;
+      // play() fulfillment is not proof of a decoded frame. Bound first-frame
+      // warm-up, and make cancellation release every timer/callback on hide.
+      await new Promise<void>((resolve) => {
+        let frame: number | undefined;
+        let settled = false;
+        const finish = () => {
+          if (settled) return;
+          settled = true;
+          window.clearTimeout(timer);
+          if (frame !== undefined) video.cancelVideoFrameCallback?.(frame);
+          video.pause();
+          this.warmCancel = null;
+          resolve();
+        };
+        const timer = window.setTimeout(finish, 600);
+        this.warmCancel = finish;
+        frame = video.requestVideoFrameCallback?.(finish);
+        this.play(video);
+      });
+      if (!this.suspended && !this.disposed) this.warmed.add(key);
+    }
+    this.warming = false;
+    if (this.disposed || this.suspended) return;
+    // A hide→show during an awaited warm frame may have interrupted the loop.
+    if (this.warmed.size !== this.videos.size) {
+      void this.prepare();
+      return;
+    }
+    this.playClip(nextClipFor("idle", this.target, this.picker));
+    this.startWatchdog();
+  }
+
+  private play(video: HTMLVideoElement | null | undefined) {
+    if (video && !this.disposed && !this.suspended)
+      void video.play().catch(() => {});
+  }
+
+  private playClip(key: BerdyClipKey) {
+    if (this.disposed || this.suspended) return;
+    // A failed loop may have healthy siblings. Never skip a failed transition
+    // to its destination: those pixels/that pose were never reached.
+    if (this.failed.has(key)) {
+      const failedClip = BERDY_CLIPS[key];
+      const alternatives = Object.values(BERDY_CLIPS).filter(
+        (clip) =>
+          clip.from === failedClip.from &&
+          clip.to === failedClip.to &&
+          !this.failed.has(clip.key),
+      );
+      // Preserve no-repeat when at least two healthy sibling loops remain.
+      key =
+        (
+          alternatives.find((clip) => clip.key !== this.active) ??
+          alternatives[0]
+        )?.key ?? key;
+    }
+    this.cancelDraw();
+    this.activeVideo()?.pause();
+    this.active = key;
+    const video = this.activeVideo();
+    if (!video) return;
+    this.resetLiveness();
+    // Park on an unavailable edge, retaining last good pixels. The watchdog
+    // retries routing from its SOURCE so a changed target can still recover.
+    if (this.failed.has(key)) return;
+    try {
+      video.currentTime = 0;
+    } catch {
+      /* metadata pending */
+    }
+    this.applyRate();
+    this.drawLoop();
+    this.play(video);
+  }
+
+  private interruptLoop() {
+    if (!this.active) return false;
+    const clip = BERDY_CLIPS[this.active];
+    if (this.failed.has(this.active)) {
+      this.recoverFailedClip();
+      return true;
+    }
+    if (clip.from !== clip.to || clip.to === this.target) return false;
+    this.playClip(nextClipFor(clip.to, this.target, this.picker));
+    return true;
+  }
+
+  private applyRate() {
+    const video = this.activeVideo();
+    if (video && this.active)
+      video.playbackRate =
+        playbackRateFor(BERDY_CLIPS[this.active], this.target) /
+        BERDY_MEDIA_TIME_SCALE;
+  }
+
+  private advance() {
+    if (!this.active || this.disposed || this.suspended) return;
+    this.playClip(
+      nextClipFor(BERDY_CLIPS[this.active].to, this.target, this.picker),
+    );
+  }
+
+  private recoverFailedClip() {
+    if (!this.active) return;
+    this.playClip(
+      nextClipFor(BERDY_CLIPS[this.active].from, this.target, this.picker),
+    );
+  }
+
+  private cancelDraw() {
+    this.generation++;
+    this.endedCancel?.();
+    this.endedCancel = null;
+    this.frameCancel?.();
+    this.frameCancel = null;
+  }
+
+  private drawActiveVideo(video: HTMLVideoElement) {
+    if (video.readyState < 2 || video.seeking || video.videoWidth <= 0) return;
+    const { width, height } = this.options.canvas;
+    // WKWebView's HEVC-alpha drawImage path can retain old silhouette pixels
+    // with 'copy'. Clear explicitly, then paint in the same synchronous draw.
+    this.context.clearRect(0, 0, width, height);
+    this.context.globalCompositeOperation = "source-over";
+    this.context.drawImage(video, 0, 0, width, height);
+    if (!this.ready) {
+      this.ready = true;
+      this.options.onReady?.();
+    }
+  }
+
+  private drawLoop() {
+    this.cancelDraw();
+    const token = this.generation;
+    const video = this.activeVideo();
+    if (!video) return;
+    const ended = () => {
+      // A removed listener/rVFC may already be queued. Also reject an old
+      // ended event when this same decoder has since been rewound/reused.
+      if (
+        token === this.generation &&
+        !this.disposed &&
+        !this.suspended &&
+        video.ended
+      )
+        this.advance();
+    };
+    video.addEventListener("ended", ended);
+    this.endedCancel = () => video.removeEventListener("ended", ended);
+    const schedule = () => {
+      if (video.requestVideoFrameCallback) {
+        const id = video.requestVideoFrameCallback(draw);
+        this.frameCancel = () => video.cancelVideoFrameCallback(id);
+      } else {
+        const id = window.requestAnimationFrame(draw);
+        this.frameCancel = () => window.cancelAnimationFrame(id);
+      }
+    };
+    const draw = () => {
+      if (this.disposed || this.suspended || token !== this.generation) return;
+      this.drawActiveVideo(video);
+      schedule();
+    };
+    schedule();
+  }
+
+  private activeVideo() {
+    return this.active ? (this.videos.get(this.active) ?? null) : null;
+  }
+  private resetLiveness() {
+    this.lastTime = -1;
+    this.lastProgress = performance.now();
+    this.recovery = 0;
+    this.endedSince = 0;
+  }
+  private startWatchdog() {
+    if (this.watchdog === null && !this.suspended)
+      this.watchdog = window.setInterval(() => this.tick(), 100);
+  }
+  private stopWatchdog() {
+    if (this.watchdog !== null) window.clearInterval(this.watchdog);
+    this.watchdog = null;
+  }
+  private tick() {
+    const video = this.activeVideo();
+    if (!video || this.suspended || this.disposed) return;
+    if (this.active && this.failed.has(this.active)) {
+      // At most one routing attempt per tick; all-failed media cannot recurse
+      // or fabricate an ended boundary. Healthy clips never enter this path.
+      this.recoverFailedClip();
+      return;
+    }
+    const now = performance.now();
+    if (video.ended) {
+      this.endedSince ||= now;
+      if (now - this.endedSince >= 300) this.advance();
+      return;
+    }
+    this.endedSince = 0;
+    if (video.currentTime !== this.lastTime) {
+      this.lastTime = video.currentTime;
+      this.lastProgress = now;
+      this.recovery = 0;
+      return;
+    }
+    if (video.paused && now - this.lastProgress >= 500) this.play(video);
+    if (now - this.lastProgress < 1500) return;
+    this.lastProgress = now;
+    this.recovery++;
+    if (this.recovery < 3) {
+      try {
+        video.currentTime += 0.001;
+        this.lastTime = video.currentTime;
+      } catch {
+        /* escalate */
+      }
+    } else {
+      // Decoder recovery keeps the same clip/time,
+      // retain the canvas, and reassert rate after load resets the decoder.
+      const time = video.currentTime;
+      video.load();
+      try {
+        video.currentTime = time;
+      } catch {
+        /* metadata pending */
+      }
+      this.applyRate();
+      this.recovery = 0;
+    }
+    this.play(video);
+  }
+  private onError = (event: Event) => {
+    for (const [key, video] of this.videos) {
+      if (event.currentTarget === video) this.failed.add(key);
+    }
+    if (event.currentTarget === this.activeVideo()) this.recoverFailedClip();
+  };
+}
diff --git a/src/features/desktop-agent/lib/chatModels.ts b/src/features/desktop-agent/lib/chatModels.ts
new file mode 100644
index 000000000..eb487c703
--- /dev/null
+++ b/src/features/desktop-agent/lib/chatModels.ts
@@ -0,0 +1,123 @@
+// Ported from the prototype's Dart ACP client. Same shapes, TS-idiomatic.
+
+export type ChatRole = "user" | "assistant" | "system";
+
+export interface TextContent {
+  type: "text";
+  text: string;
+}
+
+export interface ImageContent {
+  type: "image";
+  data: string;
+  mimeType: string;
+}
+
+export interface ToolActivity {
+  id: string;
+  name: string;
+  status: string;
+  result?: string;
+}
+
+export interface ToolContent {
+  type: "tool";
+  tool: ToolActivity;
+}
+
+export interface SystemContent {
+  type: "system";
+  text: string;
+}
+
+export type ChatContent =
+  | TextContent
+  | ImageContent
+  | ToolContent
+  | SystemContent;
+
+export interface ChatMessage {
+  id: string;
+  role: ChatRole;
+  createdAt: number;
+  content: ChatContent[];
+  isStreaming: boolean;
+}
+
+export function plainText(message: ChatMessage): string | null {
+  const text = message.content
+    .filter((c): c is TextContent => c.type === "text")
+    .map((c) => c.text)
+    .join("\n")
+    .trim();
+  return text.length === 0 ? null : text;
+}
+
+/** Per-session transient state that is not part of the transcript itself. */
+export interface SessionRuntime {
+  isOpening: boolean;
+  isReplaying: boolean;
+  hasTailSnapshot: boolean;
+  hasAuthoritativeReplay: boolean;
+  queuedPromptCount: number;
+  optimisticUserMessageIds: Set<string>;
+  snapshotMessageIds: Set<string>;
+  activeRunId: string | null;
+  streamingMessageId: string | null;
+  errorMessage: string | null;
+}
+
+export function emptyRuntime(
+  overrides: Partial<SessionRuntime> = {},
+): SessionRuntime {
+  return {
+    isOpening: false,
+    isReplaying: false,
+    hasTailSnapshot: false,
+    hasAuthoritativeReplay: false,
+    queuedPromptCount: 0,
+    optimisticUserMessageIds: new Set(),
+    snapshotMessageIds: new Set(),
+    activeRunId: null,
+    streamingMessageId: null,
+    errorMessage: null,
+    ...overrides,
+  };
+}
+
+export interface QueuedPrompt {
+  id: string;
+  text: string;
+  preamble?: string;
+}
+
+/** Metadata surfaced while applying updates. */
+export interface TranscriptApplyResult {
+  subtitle?: string;
+  sessionTitle?: string;
+  updatedAt?: number;
+  lastMessageAt?: number;
+  isArchived: boolean;
+  hasMessageActivity: boolean;
+}
+
+export function emptyApplyResult(): TranscriptApplyResult {
+  return { isArchived: false, hasMessageActivity: false };
+}
+
+export function mergeApplyResult(
+  into: TranscriptApplyResult,
+  other: TranscriptApplyResult,
+): void {
+  into.subtitle = other.subtitle ?? into.subtitle;
+  into.sessionTitle = other.sessionTitle ?? into.sessionTitle;
+  into.updatedAt = latest(into.updatedAt, other.updatedAt);
+  into.lastMessageAt = latest(into.lastMessageAt, other.lastMessageAt);
+  into.isArchived = into.isArchived || other.isArchived;
+  into.hasMessageActivity = into.hasMessageActivity || other.hasMessageActivity;
+}
+
+function latest(lhs?: number, rhs?: number): number | undefined {
+  if (lhs !== undefined && rhs !== undefined) return Math.max(lhs, rhs);
+  return lhs ?? rhs;
+}
diff --git a/src/features/desktop-agent/lib/chatTranscriptReducer.test.ts b/src/features/desktop-agent/lib/chatTranscriptReducer.test.ts
new file mode 100644
index 000000000..2f5e127c7
--- /dev/null
+++ b/src/features/desktop-agent/lib/chatTranscriptReducer.test.ts
@@ -0,0 +1,259 @@
+// Ported from the prototype's test/chat/chat_transcript_reducer_test.dart — same cases
+// (minus the AcpRpcError hint test, which belongs to the session layer).
+
+import { describe, expect, test } from "vitest";
+
+import { AcpUpdate, type AcpNotification } from "./acpNotification";
+import { emptyRuntime, plainText, type QueuedPrompt } from "./chatModels";
+import { ChatTranscriptReducer } from "./chatTranscriptReducer";
+
+function textNotification(
+  kind: string,
+  messageId: string,
+  text: string,
+  audience?: string[],
+): AcpNotification {
+  return {
+    sessionId: "s1",
+    update: new AcpUpdate({
+      sessionUpdate: kind,
+      messageId,
+      content: {
+        type: "text",
+        text,
+        ...(audience ? { annotations: { audience } } : {}),
+      },
+    }),
+  };
+}
+
+describe("ChatTranscriptReducer", () => {
+  test("assistant chunks append to a stable message", () => {
+    const reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+
+    reducer.apply(textNotification("agent_message_chunk", "m1", "Hello"));
+    const result = reducer.apply(
+      textNotification("agent_message_chunk", "m1", " world"),
+    );
+
+    expect(reducer.messages).toHaveLength(1);
+    expect(reducer.messages[0].id).toBe("m1");
+    expect(plainText(reducer.messages[0])).toBe("Hello world");
+    expect(result.subtitle).toBe("Hello world");
+  });
+
+  test("assistant-only user replay chunks are hidden", () => {
+    const reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+
+    const result = reducer.apply(
+      textNotification("user_message_chunk", "u1", "hidden context", [
+        "assistant",
+      ]),
+    );
+
+    expect(reducer.messages).toHaveLength(0);
+    expect(result.subtitle).toBeUndefined();
+  });
+
+  test("session info with null active run ends streaming", () => {
+    const reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime({ activeRunId: "run-1" }),
+    });
+    reducer.apply(textNotification("agent_message_chunk", "a1", "streaming"));
+
+    reducer.apply({
+      sessionId: "s1",
+      update: new AcpUpdate({
+        sessionUpdate: "session_info_update",
+        _meta: { goose: { activeRunId: null } },
+      }),
+    });
+
+    expect(reducer.runtime.streamingMessageId).toBeNull();
+    expect(reducer.runtime.activeRunId).toBeNull();
+    expect(reducer.messages[0].isStreaming).toBe(false);
+  });
+
+  test("authoritative replay preserves unreplayed local prompt", () => {
+    const prompts: QueuedPrompt[] = [{ id: "local-1", text: "queued prompt" }];
+    const replay = ChatTranscriptReducer.authoritativeReplay(
+      [textNotification("agent_message_chunk", "a1", "loaded")],
+      prompts,
+    );
+
+    expect(replay.messages.map((m) => m.id)).toEqual(["a1", "local-1"]);
+    expect(replay.runtime.hasAuthoritativeReplay).toBe(true);
+    expect(replay.runtime.isReplaying).toBe(false);
+    expect(replay.queuedPrompts.map((p) => p.id)).toEqual(["local-1"]);
+  });
+
+  test("authoritative replay drops local prompts the replay contained", () => {
+    const prompts: QueuedPrompt[] = [{ id: "local-1", text: "already there" }];
+    const replay = ChatTranscriptReducer.authoritativeReplay(
+      [textNotification("user_message", "server-1", "already there")],
+      prompts,
+    );
+
+    expect(replay.messages.map((m) => m.id)).toEqual(["server-1"]);
+    expect(replay.queuedPrompts).toHaveLength(0);
+  });
+
+  test("tool call and update flow", () => {
+    const reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+
+    reducer.apply({
+      sessionId: "s1",
+      update: new AcpUpdate({
+        sessionUpdate: "tool_call",
+        messageId: "a1",
+        toolCallId: "t1",
+        title: "shell",
+        status: "in_progress",
+      }),
+    });
+    reducer.apply({
+      sessionId: "s1",
+      update: new AcpUpdate({
+        sessionUpdate: "tool_call_update",
+        toolCallId: "t1",
+        status: "completed",
+        result: "ok",
+      }),
+    });
+
+    const tool = reducer.messages[0].content.find((c) => c.type === "tool");
+    expect(tool?.type).toBe("tool");
+    if (tool?.type === "tool") {
+      expect(tool.tool.status).toBe("completed");
+      expect(tool.tool.result).toBe("ok");
+    }
+  });
+
+  test("replayed toolRequest/toolResponse blocks render as tool activity", () => {
+    const reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+    reducer.apply({
+      sessionId: "s1",
+      update: new AcpUpdate({
+        sessionUpdate: "agent_message",
+        messageId: "req-1",
+        content: {
+          type: "toolRequest",
+          id: "call-1",
+          toolCall: { value: { name: "shell" } },
+          _meta: { "goose.toolSummary.title": "running checks" },
+        },
+      }),
+    });
+    reducer.apply({
+      sessionId: "s1",
+      update: new AcpUpdate({
+        sessionUpdate: "user_message",
+        messageId: "res-1",
+        content: {
+          type: "toolResponse",
+          id: "call-1",
+          toolResult: {
+            value: {
+              isError: true,
+              structuredContent: {
+                stdout: "",
+                stderr: "sh: just: command not found",
+                exit_code: 127,
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const tools = reducer.messages.flatMap((m) =>
+      m.content.filter((c) => c.type === "tool"),
+    );
+    expect(tools).toHaveLength(2);
+    expect(tools[0]?.type === "tool" && tools[0].tool.name).toBe(
+      "running checks",
+    );
+    expect(tools[1]?.type === "tool" && tools[1].tool.status).toBe("failed");
+    expect(tools[1]?.type === "tool" && tools[1].tool.result).toContain(
+      "exit_code: 127",
+    );
+  });
+
+  test("failed tool updates keep structured stdout/stderr for expansion", () => {
+    const reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+    reducer.apply({
+      sessionId: "s1",
+      update: new AcpUpdate({
+        sessionUpdate: "tool_call_update",
+        messageId: "a1",
+        toolCallId: "t1",
+        title: "shell",
+        status: "failed",
+        result: {
+          structuredContent: {
+            stdout: "partial output",
+            stderr: "sh: just: command not found",
+            exit_code: 127,
+          },
+        },
+      }),
+    });
+
+    const tool = reducer.messages[0].content.find((c) => c.type === "tool");
+    expect(tool?.type).toBe("tool");
+    if (tool?.type === "tool") {
+      expect(tool.tool.status).toBe("failed");
+      expect(tool.tool.result).toContain("exit_code: 127");
+      expect(tool.tool.result).toContain("stdout:\npartial output");
+      expect(tool.tool.result).toContain(
+        "stderr:\nsh: just: command not found",
+      );
+    }
+  });
+
+  test("optimistic echo is not duplicated by server user_message", () => {
+    const reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+    reducer.appendLocalUserMessage({ id: "opt-1", text: "hi there" });
+
+    reducer.apply(textNotification("user_message", "server-9", "hi there"));
+
+    expect(reducer.messages).toHaveLength(1);
+    expect(reducer.messages[0].id).toBe("opt-1");
+  });
+
+  test("turn_complete settles streaming", () => {
+    const reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+    reducer.apply(textNotification("agent_message_chunk", "a1", "partial"));
+    expect(reducer.messages[0].isStreaming).toBe(true);
+
+    reducer.apply({
+      sessionId: "s1",
+      update: new AcpUpdate({ sessionUpdate: "turn_complete" }),
+    });
+
+    expect(reducer.messages[0].isStreaming).toBe(false);
+    expect(reducer.runtime.streamingMessageId).toBeNull();
+  });
+});
diff --git a/src/features/desktop-agent/lib/chatTranscriptReducer.ts b/src/features/desktop-agent/lib/chatTranscriptReducer.ts
new file mode 100644
index 000000000..cb0808e5e
--- /dev/null
+++ b/src/features/desktop-agent/lib/chatTranscriptReducer.ts
@@ -0,0 +1,542 @@
+// Ported 1:1 from the prototype's lib/chat/chat_transcript_reducer.dart (itself ported
+// from the original Swift prototype), including the optimistic-echo and
+// snapshot-reconciliation rules encoded in its tests.
+
+import type { AcpNotification, AcpUpdate } from "./acpNotification";
+import {
+  emptyApplyResult,
+  emptyRuntime,
+  mergeApplyResult,
+  plainText,
+  type ChatContent,
+  type ChatMessage,
+  type ImageContent,
+  type QueuedPrompt,
+  type SessionRuntime,
+  type ToolContent,
+  type TranscriptApplyResult,
+} from "./chatModels";
+
+const normalized = (text: string): string => text.trim();
+
+let uuidCounter = 0;
+const generatedId = (): string => `generated-${Date.now()}-${uuidCounter++}`;
+
+export interface AuthoritativeReplayOutcome {
+  messages: ChatMessage[];
+  runtime: SessionRuntime;
+  result: TranscriptApplyResult;
+  queuedPrompts: QueuedPrompt[];
+}
+
+export class ChatTranscriptReducer {
+  messages: ChatMessage[];
+  runtime: SessionRuntime;
+
+  constructor(args: { messages: ChatMessage[]; runtime: SessionRuntime }) {
+    this.messages = args.messages;
+    this.runtime = args.runtime;
+  }
+
+  /**
+   * Replays `session/load` notifications into a fresh reducer, appends any
+   * local prompts the replay did not already contain, and settles all
+   * streaming state: replay completion must never leave replay-derived
+   * active-run or progress UI alive.
+   */
+  static authoritativeReplay(
+    notifications: AcpNotification[],
+    preservingLocalPrompts: QueuedPrompt[] = [],
+  ): AuthoritativeReplayOutcome {
+    const reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+    const mergedResult = emptyApplyResult();
+
+    for (const notification of notifications) {
+      mergeApplyResult(mergedResult, reducer.apply(notification));
+    }
+
+    const unreplayedLocalPrompts = preservingLocalPrompts.filter((prompt) => {
+      return !reducer.messages.some((message) => {
+        if (message.id === prompt.id) return true;
+        if (message.role !== "user") return false;
+        const text = plainText(message);
+        return text !== null && normalized(text) === normalized(prompt.text);
+      });
+    });
+
+    for (const prompt of unreplayedLocalPrompts) {
+      reducer.appendLocalUserMessage({ id: prompt.id, text: prompt.text });
+    }
+
+    reducer.runtime.activeRunId = null;
+    reducer.finishStreamingMessage();
+
+    reducer.runtime.hasAuthoritativeReplay = true;
+    reducer.runtime.hasTailSnapshot = false;
+    reducer.runtime.isOpening = false;
+    reducer.runtime.isReplaying = false;
+    reducer.runtime.queuedPromptCount = unreplayedLocalPrompts.length;
+    return {
+      messages: reducer.messages,
+      runtime: reducer.runtime,
+      result: mergedResult,
+      queuedPrompts: unreplayedLocalPrompts,
+    };
+  }
+
+  appendLocalUserMessage(args: {
+    id: string;
+    text: string;
+    createdAt?: number;
+  }): void {
+    this.finishStreamingMessage();
+    this.messages.push({
+      id: args.id,
+      role: "user",
+      createdAt: args.createdAt ?? Date.now(),
+      content: [{ type: "text", text: args.text }],
+      isStreaming: false,
+    });
+    this.runtime.optimisticUserMessageIds.add(args.id);
+  }
+
+  apply(notification: AcpNotification): TranscriptApplyResult {
+    const update = notification.update;
+    const result = emptyApplyResult();
+
+    const activeRunId = update.activeRunId;
+    if (activeRunId.isPresent && activeRunId.id !== null) {
+      this.runtime.activeRunId = activeRunId.id;
+    }
+
+    switch (update.kind) {
+      case "agent_message":
+      case "agent_message_chunk": {
+        const content = update.content;
+        if (content !== null) {
+          const messageId = this.ensureAssistantMessage(update.messageId);
+          const text = textContent(content);
+          if (text !== null && text.length > 0) {
+            this.appendText(text, messageId);
+            result.subtitle = this.plainTextFor(messageId) ?? text;
+            result.hasMessageActivity = true;
+          } else {
+            const image = imageContent(content);
+            const replayTool = toolContentFromReplay(content);
+            if (image !== null) {
+              this.appendContent(image, messageId);
+              result.hasMessageActivity = true;
+            } else if (replayTool !== null) {
+              this.appendContent(replayTool, messageId);
+              result.hasMessageActivity = true;
+            }
+          }
+        }
+        break;
+      }
+
+      case "user_message":
+      case "user_message_chunk": {
+        const content = update.content;
+        if (content !== null && !isAssistantOnly(content)) {
+          const text = textContent(content);
+          if (text !== null) {
+            this.finishStreamingMessage();
+            const messageId = update.messageId ?? generatedId();
+            this.appendUserText(text, messageId);
+            result.subtitle = this.plainTextFor(messageId) ?? text;
+            result.hasMessageActivity = true;
+          } else {
+            const replayTool = toolContentFromReplay(content);
+            if (replayTool !== null) {
+              this.finishStreamingMessage();
+              const messageId = update.messageId ?? generatedId();
+              this.messages.push({
+                id: messageId,
+                role: "assistant",
+                createdAt: Date.now(),
+                content: [replayTool],
+                isStreaming: false,
+              });
+              result.hasMessageActivity = true;
+            }
+          }
+        }
+        break;
+      }
+
+      case "tool_call": {
+        const messageId = this.ensureAssistantMessage(update.messageId);
+        const tool = {
+          id: update.toolCallId ?? generatedId(),
+          name: update.title ?? "Tool",
+          status: update.status ?? "in_progress",
+        };
+        this.appendContent({ type: "tool", tool }, messageId);
+        result.subtitle = `Tool ${tool.status}: ${tool.name}`;
+        result.hasMessageActivity = true;
+        break;
+      }
+
+      case "tool_call_update": {
+        const toolId = update.toolCallId;
+        if (toolId !== null) {
+          this.updateTool(toolId, update);
+          result.subtitle = `Tool ${update.status ?? "updated"}`;
+          result.hasMessageActivity = true;
+        }
+        break;
+      }
+
+      case "session_info_update": {
+        const title = update.raw.title;
+        result.sessionTitle = typeof title === "string" ? title : undefined;
+        result.updatedAt = update.updatedAt;
+        result.lastMessageAt = update.lastMessageAt;
+        result.isArchived = update.archivedAt !== undefined;
+        if (activeRunId.isPresent && activeRunId.id === null) {
+          this.runtime.activeRunId = null;
+          this.finishStreamingMessage();
+        }
+        break;
+      }
+
+      case "usage_update":
+      case "config_option_update":
+        break;
+
+      case "task_complete":
+      case "turn_complete":
+      case "session_idle":
+      case "agent_turn_complete":
+        this.runtime.activeRunId = null;
+        this.finishStreamingMessage();
+        break;
+
+      default:
+        break;
+    }
+
+    return result;
+  }
+
+  private ensureAssistantMessage(preferredId: string | null): string {
+    if (preferredId !== null) {
+      if (!this.messages.some((message) => message.id === preferredId)) {
+        this.messages.push({
+          id: preferredId,
+          role: "assistant",
+          createdAt: Date.now(),
+          content: [],
+          isStreaming: true,
+        });
+      }
+      this.runtime.streamingMessageId = preferredId;
+      return preferredId;
+    }
+
+    const streamingMessageId = this.runtime.streamingMessageId;
+    if (
+      streamingMessageId !== null &&
+      this.messages.some((message) => message.id === streamingMessageId)
+    ) {
+      return streamingMessageId;
+    }
+
+    const id = generatedId();
+    this.messages.push({
+      id,
+      role: "assistant",
+      createdAt: Date.now(),
+      content: [],
+      isStreaming: true,
+    });
+    this.runtime.streamingMessageId = id;
+    return id;
+  }
+
+  private appendText(text: string, messageId: string): void {
+    const message = this.messages.find((m) => m.id === messageId);
+    if (!message) return;
+    const last =
+      message.content.length > 0
+        ? message.content[message.content.length - 1]
+        : null;
+    if (last !== null && last.type === "text") {
+      const existing = last.text;
+      // Snapshot-sourced settled messages may receive replayed echoes of
+      // their own text: ignore duplicates/subsets and replace on extension
+      // instead of double-appending.
+      if (
+        !message.isStreaming &&
+        this.runtime.snapshotMessageIds.has(messageId)
+      ) {
+        const existingText = normalized(existing);
+        const newText = normalized(text);
+        if (
+          existingText === newText ||
+          (newText.length < existingText.length &&
+            existingText.includes(newText))
+        ) {
+          return;
+        }
+        if (newText.startsWith(existingText)) {
+          message.content[message.content.length - 1] = { type: "text", text };
+          return;
+        }
+      }
+      message.content[message.content.length - 1] = {
+        type: "text",
+        text: existing + text,
+      };
+    } else {
+      message.content.push({ type: "text", text });
+    }
+  }
+
+  private appendUserText(text: string, messageId: string): void {
+    const index = this.messages.findIndex((m) => m.id === messageId);
+    const message = index >= 0 ? this.messages[index] : null;
+    const last =
+      message && message.content.length > 0
+        ? message.content[message.content.length - 1]
+        : null;
+    if (message && last !== null && last.type === "text") {
+      const existing = last.text;
+      if (
+        this.runtime.optimisticUserMessageIds.has(messageId) ||
+        this.runtime.snapshotMessageIds.has(messageId)
+      ) {
+        const existingText = normalized(existing);
+        const newText = normalized(text);
+        if (
+          existingText === newText ||
+          (newText.length < existingText.length &&
+            existingText.includes(newText))
+        ) {
+          return;
+        }
+        if (newText.startsWith(existingText)) {
+          message.content[message.content.length - 1] = { type: "text", text };
+          return;
+        }
+      }
+      message.content[message.content.length - 1] = {
+        type: "text",
+        text: existing + text,
+      };
+    } else if (message) {
+      this.appendContent({ type: "text", text }, messageId);
+    } else if (this.hasMatchingOptimisticOrSnapshotUserMessage(text)) {
+      return;
+    } else {
+      this.messages.push({
+        id: messageId,
+        role: "user",
+        createdAt: Date.now(),
+        content: [{ type: "text", text }],
+        isStreaming: false,
+      });
+    }
+  }
+
+  private appendContent(content: ChatContent, messageId: string): void {
+    const message = this.messages.find((m) => m.id === messageId);
+    if (!message) return;
+    message.content.push(content);
+  }
+
+  private updateTool(toolId: string, update: AcpUpdate): void {
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      const message = this.messages[i];
+      for (
+        let contentIndex = 0;
+        contentIndex < message.content.length;
+        contentIndex++
+      ) {
+        const content = message.content[contentIndex];
+        if (content.type !== "tool" || content.tool.id !== toolId) continue;
+        const tool = { ...content.tool };
+        if (update.title !== null) tool.name = update.title;
+        if (update.status !== null) tool.status = update.status;
+        tool.result = toolResult(update) ?? tool.result;
+        message.content[contentIndex] = {
+          type: "tool",
+          tool,
+        } satisfies ToolContent;
+        return;
+      }
+    }
+
+    const messageId = this.ensureAssistantMessage(update.messageId);
+    this.appendContent(
+      {
+        type: "tool",
+        tool: {
+          id: toolId,
+          name: update.title ?? "Tool",
+          status: update.status ?? "updated",
+          result: toolResult(update),
+        },
+      },
+      messageId,
+    );
+  }
+
+  private markStreaming(isStreaming: boolean, messageId: string): void {
+    const message = this.messages.find((m) => m.id === messageId);
+    if (!message) return;
+    message.isStreaming = isStreaming;
+  }
+
+  finishStreamingMessage(): void {
+    const streamingMessageId = this.runtime.streamingMessageId;
+    if (streamingMessageId !== null) {
+      this.markStreaming(false, streamingMessageId);
+    }
+    this.runtime.streamingMessageId = null;
+  }
+
+  private plainTextFor(messageId: string): string | null {
+    const message = this.messages.find((m) => m.id === messageId);
+    return message ? plainText(message) : null;
+  }
+
+  private hasMatchingOptimisticOrSnapshotUserMessage(text: string): boolean {
+    const normalizedText = normalized(text);
+    return this.messages.some((message) => {
+      if (message.role !== "user") return false;
+      if (
+        !this.runtime.optimisticUserMessageIds.has(message.id) &&
+        !this.runtime.snapshotMessageIds.has(message.id)
+      ) {
+        return false;
+      }
+      const messageText = plainText(message);
+      return messageText !== null && normalized(messageText) === normalizedText;
+    });
+  }
+}
+
+function textContent(object: Record<string, unknown>): string | null {
+  if (object.type !== "text") return null;
+  const text = object.text;
+  return typeof text === "string" ? text : null;
+}
+
+/**
+ * Hidden prompt context replayed to the client carries an
+ * `annotations.audience` that does not include `user`; it must never be
+ * displayed in the transcript.
+ */
+function isAssistantOnly(object: Record<string, unknown>): boolean {
+  const annotations = object.annotations;
+  if (typeof annotations !== "object" || annotations === null) return false;
+  const audience = (annotations as Record<string, unknown>).audience;
+  if (!Array.isArray(audience)) return false;
+  return !audience
+    .filter((a): a is string => typeof a === "string")
+    .includes("user");
+}
+
+function toolResult(update: AcpUpdate): string | undefined {
+  const result = update.raw.result;
+  if (typeof result === "string") return result;
+  const resultText = structuredToolText(result);
+  if (resultText !== undefined) return resultText;
+  const content = update.raw.content;
+  if (typeof content === "object" && content !== null) {
+    const text = (content as Record<string, unknown>).text;
+    if (typeof text === "string") return text;
+  }
+  return undefined;
+}
+
+function structuredToolText(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const record = value as Record<string, unknown>;
+  const structured = record.structuredContent;
+  if (typeof structured === "object" && structured !== null) {
+    const s = structured as Record<string, unknown>;
+    const stdout = typeof s.stdout === "string" ? s.stdout.trimEnd() : "";
+    const stderr = typeof s.stderr === "string" ? s.stderr.trimEnd() : "";
+    const exitCode = s.exit_code;
+    const parts: string[] = [];
+    if (typeof exitCode === "number") parts.push(`exit_code: ${exitCode}`);
+    if (stdout.length > 0) parts.push(`stdout:\n${stdout}`);
+    if (stderr.length > 0) parts.push(`stderr:\n${stderr}`);
+    if (parts.length > 0) return parts.join("\n\n");
+  }
+  const content = record.content;
+  if (Array.isArray(content)) {
+    const text = content
+      .map((item) => {
+        const entry = asRecord(item);
+        return typeof entry?.text === "string" ? entry.text : null;
+      })
+      .filter((text): text is string => text !== null)
+      .join("\n")
+      .trim();
+    if (text.length > 0) return text;
+  }
+  const message = record.message ?? record.error;
+  if (typeof message === "string") return message;
+  return undefined;
+}
+
+function toolContentFromReplay(
+  object: Record<string, unknown>,
+): ToolContent | null {
+  if (object.type === "toolRequest") {
+    const id = typeof object.id === "string" ? object.id : generatedId();
+    const toolCall = asRecord(object.toolCall);
+    const value = asRecord(toolCall?.value);
+    const meta = asRecord(object._meta);
+    const summaryTitle = meta?.["goose.toolSummary.title"];
+    const name =
+      (typeof summaryTitle === "string" && summaryTitle.trim()) ||
+      (typeof value?.name === "string" && value.name.trim()) ||
+      "Tool";
+    return { type: "tool", tool: { id, name, status: "in_progress" } };
+  }
+  if (object.type === "toolResponse") {
+    const id = typeof object.id === "string" ? object.id : generatedId();
+    const toolResult = asRecord(object.toolResult);
+    const value = asRecord(toolResult?.value);
+    const failed = value?.isError === true || structuredExitCode(value) !== 0;
+    return {
+      type: "tool",
+      tool: {
+        id,
+        name: "Tool result",
+        status: failed ? "failed" : "completed",
+        result: failed ? structuredToolText(value) : undefined,
+      },
+    };
+  }
+  return null;
+}
+
+function structuredExitCode(value: unknown): number | null {
+  const record = asRecord(value);
+  const structured = asRecord(record?.structuredContent);
+  const exitCode = structured?.exit_code;
+  return typeof exitCode === "number" ? exitCode : null;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function imageContent(object: Record<string, unknown>): ImageContent | null {
+  if (object.type !== "image") return null;
+  const data = object.data;
+  const mimeType = object.mimeType;
+  if (typeof data !== "string" || typeof mimeType !== "string") return null;
+  return { type: "image", data, mimeType };
+}
diff --git a/src/features/desktop-agent/lib/composerHint.test.ts b/src/features/desktop-agent/lib/composerHint.test.ts
new file mode 100644
index 000000000..bf005a34f
--- /dev/null
+++ b/src/features/desktop-agent/lib/composerHint.test.ts
@@ -0,0 +1,172 @@
+// Table tests pinning the composer-hint priority chain. The helper
+// returns i18n descriptors ({ key, params }) — the component translates.
+
+import { describe, expect, test } from "vitest";
+
+import { deriveComposerHint, type ComposerHintInputs } from "./composerHint";
+
+const quiet: ComposerHintInputs = {
+  lastSendError: null,
+  perchError: null,
+  perchPhase: "unperched",
+  perchApp: null,
+  perchTitle: null,
+  attached: true,
+  connectionError: null,
+  reconnectExhausted: false,
+  sendStalled: false,
+  agentSendInFlight: false,
+  capturePending: false,
+  pendingName: null,
+  thinking: false,
+};
+
+describe("deriveComposerHint", () => {
+  test("quiet state renders no hint", () => {
+    expect(deriveComposerHint(quiet)).toBeNull();
+  });
+
+  test("send error beats everything", () => {
+    const everythingOn: ComposerHintInputs = {
+      lastSendError: "boom",
+      perchError: "ax broke",
+      perchPhase: "perched",
+      perchApp: "Chrome",
+      perchTitle: "Doc",
+      attached: false,
+      connectionError: "closed",
+      reconnectExhausted: true,
+      sendStalled: true,
+      agentSendInFlight: true,
+      capturePending: true,
+      pendingName: "Panda",
+      thinking: true,
+    };
+    expect(deriveComposerHint(everythingOn)).toEqual({
+      key: "hint.sendFailed",
+      params: { message: "boom" },
+    });
+  });
+
+  test("disconnected ladder: exhausted > reconnecting > connecting", () => {
+    const off = { ...quiet, attached: false };
+    expect(deriveComposerHint({ ...off, reconnectExhausted: true })?.key).toBe(
+      "hint.reconnectExhausted",
+    );
+    expect(deriveComposerHint({ ...off, connectionError: "closed" })?.key).toBe(
+      "hint.reconnecting",
+    );
+    expect(deriveComposerHint(off)?.key).toBe("hint.connecting");
+  });
+
+  test("attached ladder: stalled > capturing > agent starting > thinking", () => {
+    expect(
+      deriveComposerHint({
+        ...quiet,
+        sendStalled: true,
+        capturePending: true,
+        agentSendInFlight: true,
+        thinking: true,
+      })?.key,
+    ).toBe("hint.stalled");
+    expect(
+      deriveComposerHint({
+        ...quiet,
+        capturePending: true,
+        agentSendInFlight: true,
+        thinking: true,
+      })?.key,
+    ).toBe("hint.capturing");
+    expect(
+      deriveComposerHint({
+        ...quiet,
+        agentSendInFlight: true,
+        pendingName: "Panda",
+        thinking: true,
+      }),
+    ).toEqual({ key: "hint.agentStarting", params: { name: "Panda" } });
+    expect(deriveComposerHint({ ...quiet, thinking: true })?.key).toBe(
+      "hint.thinking",
+    );
+  });
+
+  test("agent starting without a name uses the generic key (no English fallback)", () => {
+    expect(deriveComposerHint({ ...quiet, agentSendInFlight: true })).toEqual({
+      key: "hint.agentStartingGeneric",
+    });
+  });
+});
+
+describe("deriveComposerHint perch rungs", () => {
+  const perched: ComposerHintInputs = {
+    ...quiet,
+    perchPhase: "perched",
+    perchApp: "Chrome",
+    perchTitle: "Quarterly Doc",
+  };
+
+  test("perch error beats disconnected but loses to send error", () => {
+    expect(
+      deriveComposerHint({ ...quiet, perchError: "ax broke", attached: false }),
+    ).toEqual({ key: "hint.perchError", params: { message: "ax broke" } });
+    expect(
+      deriveComposerHint({
+        ...quiet,
+        perchError: "ax broke",
+        lastSendError: "boom",
+      })?.key,
+    ).toBe("hint.sendFailed");
+  });
+
+  test("accessibility_denied maps to the grant-instructions key", () => {
+    expect(
+      deriveComposerHint({ ...quiet, perchError: "accessibility_denied" }),
+    ).toEqual({ key: "hint.perchAccessibility" });
+    // The gate token arrives wrapped in invoke error prose — still maps.
+    expect(
+      deriveComposerHint({
+        ...quiet,
+        perchError: 'invoke error: "accessibility_denied"',
+      }),
+    ).toEqual({ key: "hint.perchAccessibility" });
+  });
+
+  test("perched identity: app+title and app-only variants", () => {
+    expect(deriveComposerHint(perched)).toEqual({
+      key: "hint.perched",
+      params: { app: "Chrome", title: "Quarterly Doc" },
+    });
+    expect(deriveComposerHint({ ...perched, perchTitle: "  " })).toEqual({
+      key: "hint.perchedApp",
+      params: { app: "Chrome" },
+    });
+  });
+
+  test("perch identity beats thinking but loses to agent starting", () => {
+    expect(deriveComposerHint({ ...perched, thinking: true })?.key).toBe(
+      "hint.perched",
+    );
+    expect(
+      deriveComposerHint({ ...perched, agentSendInFlight: true })?.key,
+    ).toBe("hint.agentStartingGeneric");
+  });
+
+  test("targeting and unperched render no identity hint", () => {
+    expect(
+      deriveComposerHint({ ...perched, perchPhase: "targeting" }),
+    ).toBeNull();
+    expect(
+      deriveComposerHint({ ...perched, perchPhase: "unperched" }),
+    ).toBeNull();
+  });
+
+  test("long app/title truncate with ellipsis (one-line hint row)", () => {
+    const hint = deriveComposerHint({
+      ...perched,
+      perchApp: "A".repeat(40),
+      perchTitle: "T".repeat(90),
+    });
+    expect(hint?.params?.app).toBe(`${"A".repeat(27)}…`);
+    expect(hint?.params?.title).toBe(`${"T".repeat(71)}…`);
+  });
+});
diff --git a/src/features/desktop-agent/lib/composerHint.ts b/src/features/desktop-agent/lib/composerHint.ts
new file mode 100644
index 000000000..d3b6101ab
--- /dev/null
+++ b/src/features/desktop-agent/lib/composerHint.ts
@@ -0,0 +1,111 @@
+// Composer hint derivation: the priority chain was once a ~12-branch
+// nested ternary inline in ChatPopover — pure derivation logic trapped in
+// the component, unscannable and untested. Extracted here with a
+// table-driven test pinning the priority order.
+//
+// Returns an i18n DESCRIPTOR ({ key, params }) rather than English text:
+// the component translates via the `desktop-agent` namespace. Keys live in
+// src/shared/i18n/locales/{en,es}/desktop-agent.json.
+//
+// Priority (first match wins):
+//   1. send error        — actionable failure, beats everything
+//   2. perch error       — AX/capture problems from the perch layer
+//   3. disconnected      — exhausted > reconnecting > connecting
+//   4. stalled           — thinking with zero traffic for 25s
+//   5. capture pending   — perched-window snapshot before dispatch
+//   6. agent starting    — deferred create in flight
+//   7. perch hint        — ambient perched-on identity
+//   8. thinking          — plain activity indicator
+//   9. null              — no hint row
+//
+// (The prototype's "notice" rung — delivered-but-status for the
+// out-of-process dispatch path — was dead plumbing in the in-process
+// rewrite and was removed in PR3; see git history if a status channel
+// is ever needed again.)
+
+import type { PerchPhase } from "./sendSource";
+
+export interface ComposerHintInputs {
+  lastSendError: string | null;
+  /** Raw perch-layer error (usePerch.lastError): AX resolve failures,
+   *  capture failures, the accessibility_denied gate. Mapped to a
+   *  friendly key when recognized, passthrough otherwise. */
+  perchError: string | null;
+  perchPhase: PerchPhase;
+  perchApp: string | null;
+  perchTitle: string | null;
+  attached: boolean;
+  connectionError: string | null;
+  /** Reconnect gave up: the copy must stop claiming "reconnecting" when
+   *  nothing is reconnecting. */
+  reconnectExhausted: boolean;
+  sendStalled: boolean;
+  agentSendInFlight: boolean;
+  capturePending: boolean;
+  pendingName: string | null;
+  thinking: boolean;
+}
+
+export interface ComposerHint {
+  key: string;
+  params?: Record<string, string>;
+}
+
+const truncate = (value: string, maxCharacters: number): string =>
+  value.length <= maxCharacters
+    ? value
+    : `${value.slice(0, maxCharacters - 1)}…`;
+
+/** The perch_on gate rejects with this token when Accessibility is not
+ *  granted (perch.rs) — mapped to friendly copy instead of passthrough. */
+const ACCESSIBILITY_DENIED_TOKEN = "accessibility_denied";
+
+/** Ambient perched-on identity (priority 7). Identity params are
+ *  pre-truncated here (app 28, title 72) — the hint row is one line. */
+function perchIdentityHint(inputs: ComposerHintInputs): ComposerHint | null {
+  if (inputs.perchApp === null) return null;
+  const app = truncate(inputs.perchApp, 28);
+  if (inputs.perchPhase !== "perched") return null;
+  const title = (inputs.perchTitle ?? "").trim();
+  return title.length > 0
+    ? {
+        key: "hint.perched",
+        params: { app, title: truncate(title, 72) },
+      }
+    : { key: "hint.perchedApp", params: { app } };
+}
+
+export function deriveComposerHint(
+  inputs: ComposerHintInputs,
+): ComposerHint | null {
+  if (inputs.lastSendError) {
+    return {
+      key: "hint.sendFailed",
+      params: { message: inputs.lastSendError },
+    };
+  }
+  if (inputs.perchError) {
+    // The one recognizable token gets real copy (grant instructions);
+    // everything else is a native-layer message rendered verbatim, like
+    // sendFailed.
+    return inputs.perchError.includes(ACCESSIBILITY_DENIED_TOKEN)
+      ? { key: "hint.perchAccessibility" }
+      : { key: "hint.perchError", params: { message: inputs.perchError } };
+  }
+  if (!inputs.attached) {
+    if (inputs.reconnectExhausted) return { key: "hint.reconnectExhausted" };
+    if (inputs.connectionError) return { key: "hint.reconnecting" };
+    return { key: "hint.connecting" };
+  }
+  if (inputs.sendStalled) return { key: "hint.stalled" };
+  if (inputs.capturePending) return { key: "hint.capturing" };
+  if (inputs.agentSendInFlight) {
+    return inputs.pendingName !== null
+      ? { key: "hint.agentStarting", params: { name: inputs.pendingName } }
+      : { key: "hint.agentStartingGeneric" };
+  }
+  const perched = perchIdentityHint(inputs);
+  if (perched) return perched;
+  if (inputs.thinking) return { key: "hint.thinking" };
+  return null;
+}
diff --git a/src/features/desktop-agent/lib/desktopAgentPreferences.ts b/src/features/desktop-agent/lib/desktopAgentPreferences.ts
new file mode 100644
index 000000000..a6cb78f2e
--- /dev/null
+++ b/src/features/desktop-agent/lib/desktopAgentPreferences.ts
@@ -0,0 +1,32 @@
+// Desktop Agent setting (Behavior settings, macOS only): ONE on/off
+// switch; the agent shows the animated Berdy character whenever Berdy is
+// the agent. The right-click agent selector stays behind its own
+// experiment (DESKTOP_AGENT_AGENT_SELECTOR_EXPERIMENT_ID).
+//
+// localStorage is shared by the main and panel webviews, so every write
+// reaches the other webview as a storage event: the panel's "Turn off agent"
+// menu item writes `enabled` false and the main-webview bridge closes the
+// panel in response.
+//
+// There used to be a second `goose:desktop-agent-visible` preference
+// (hide WITHOUT disabling). It collapsed into this single switch: hiding
+// IS disabling now. Migration: the stale `visible` key is removed once —
+// a user who had visible=false and enabled=true comes back enabled (and
+// can hide again with one click).
+
+import { createBooleanLocalStoragePreference } from "@/shared/preferences/createBooleanLocalStoragePreference";
+
+// Safe to delete after 2027-01.
+localStorage.removeItem("goose:desktop-agent-visible");
+
+export const DESKTOP_AGENT_ENABLED_STORAGE_KEY = "goose:desktop-agent-enabled";
+
+// An always-on-top panel appearing uninvited is rude: off by default.
+const enabledPreference = createBooleanLocalStoragePreference({
+  storageKey: DESKTOP_AGENT_ENABLED_STORAGE_KEY,
+  changedEvent: "goose:desktop-agent-enabled-changed",
+  defaultValue: false,
+});
+
+export const setDesktopAgentEnabled = enabledPreference.set;
+export const useDesktopAgentEnabledPreference = enabledPreference.useValue;
diff --git a/src/features/desktop-agent/lib/markdown.test.ts b/src/features/desktop-agent/lib/markdown.test.ts
new file mode 100644
index 000000000..94ef450b7
--- /dev/null
+++ b/src/features/desktop-agent/lib/markdown.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+
+import { parseInline, parseMarkdown } from "./markdown";
+
+describe("parseInline", () => {
+  it("passes plain text through as a single span", () => {
+    expect(parseInline("hello world")).toEqual([
+      { kind: "text", text: "hello world" },
+    ]);
+  });
+
+  it("parses bold, italic, and code spans", () => {
+    expect(parseInline("a **b** *c* _d_ `e`")).toEqual([
+      { kind: "text", text: "a " },
+      { kind: "bold", text: "b" },
+      { kind: "text", text: " " },
+      { kind: "italic", text: "c" },
+      { kind: "text", text: " " },
+      { kind: "italic", text: "d" },
+      { kind: "text", text: " " },
+      { kind: "code", text: "e" },
+    ]);
+  });
+
+  it("parses http(s) links and rejects other schemes", () => {
+    expect(parseInline("[docs](https://example.com/a)")).toEqual([
+      { kind: "link", text: "docs", href: "https://example.com/a" },
+    ]);
+    // javascript: scheme never becomes a link — stays literal text.
+    const spans = parseInline("[x](javascript:alert(1))");
+    expect(spans.every((s) => s.kind !== "link")).toBe(true);
+  });
+
+  it("code spans win over emphasis inside them", () => {
+    expect(parseInline("`a *b* c`")).toEqual([
+      { kind: "code", text: "a *b* c" },
+    ]);
+  });
+
+  it("lone asterisks stay literal", () => {
+    expect(parseInline("2 * 3 * 4")).toEqual([
+      { kind: "text", text: "2 * 3 * 4" },
+    ]);
+  });
+});
+
+describe("parseMarkdown", () => {
+  it("splits paragraphs on blank lines", () => {
+    const blocks = parseMarkdown("one\n\ntwo");
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0]).toEqual({
+      kind: "paragraph",
+      spans: [{ kind: "text", text: "one" }],
+    });
+  });
+
+  it("parses headings h1-h4", () => {
+    const blocks = parseMarkdown("# Title\n#### Sub");
+    expect(blocks[0]).toMatchObject({ kind: "heading", level: 1 });
+    expect(blocks[1]).toMatchObject({ kind: "heading", level: 4 });
+  });
+
+  it("parses fenced code and never inline-parses its body", () => {
+    const blocks = parseMarkdown("```ts\nconst a = **not bold**;\n```");
+    expect(blocks).toEqual([
+      { kind: "code", language: "ts", text: "const a = **not bold**;" },
+    ]);
+  });
+
+  it("an unclosed fence still renders as code", () => {
+    const blocks = parseMarkdown("```\nunterminated");
+    expect(blocks).toEqual([
+      { kind: "code", language: "", text: "unterminated" },
+    ]);
+  });
+
+  it("parses unordered and ordered lists", () => {
+    const blocks = parseMarkdown("- a\n- b\n\n1. x\n2. y");
+    expect(blocks[0]).toMatchObject({ kind: "list", ordered: false });
+    expect((blocks[0] as { items: unknown[] }).items).toHaveLength(2);
+    expect(blocks[1]).toMatchObject({ kind: "list", ordered: true });
+  });
+
+  it("parses block quotes and strips the markers", () => {
+    const blocks = parseMarkdown("> quoted\n> more");
+    expect(blocks[0]).toMatchObject({ kind: "quote" });
+  });
+
+  it("empty input produces no blocks", () => {
+    expect(parseMarkdown("")).toEqual([]);
+    expect(parseMarkdown("\n\n")).toEqual([]);
+  });
+});
diff --git a/src/features/desktop-agent/lib/markdown.ts b/src/features/desktop-agent/lib/markdown.ts
new file mode 100644
index 000000000..cf22bc79f
--- /dev/null
+++ b/src/features/desktop-agent/lib/markdown.ts
@@ -0,0 +1,158 @@
+// Scoped markdown for agent replies: agents answer in heavy markdown,
+// and raw asterisk soup in the bubbles reads terribly.
+//
+// Deliberately a SUBSET, parsed to a typed block AST that MessageRow
+// renders as React elements — no dangerouslySetInnerHTML, so the output is
+// XSS-safe by construction and no parser/sanitizer dependency lands in the
+// bundle. Unknown constructs degrade to plain text — a rendering miss must
+// never eat content.
+//
+// Supported: # headings, ``` fences, - / * / 1. lists, > quotes, **bold**,
+// *italic* / _italic_, `code`, [text](http/https link). Everything else is
+// literal text.
+
+export type InlineSpan =
+  | { kind: "text"; text: string }
+  | { kind: "bold"; text: string }
+  | { kind: "italic"; text: string }
+  | { kind: "code"; text: string }
+  | { kind: "link"; text: string; href: string };
+
+export type MarkdownBlock =
+  | { kind: "paragraph"; spans: InlineSpan[] }
+  | { kind: "heading"; level: number; spans: InlineSpan[] }
+  | { kind: "code"; language: string; text: string }
+  | { kind: "list"; ordered: boolean; items: InlineSpan[][] }
+  | { kind: "quote"; spans: InlineSpan[] };
+
+// --- inline ----------------------------------------------------------------
+
+const INLINE_PATTERN =
+  /(`[^`]+`)|(\*\*[^*]+\*\*)|(\*[^*\s][^*]*\*)|(_[^_\s][^_]*_)|(\[[^\]]+\]\(https?:\/\/[^\s)]+\))/;
+
+export function parseInline(text: string): InlineSpan[] {
+  const spans: InlineSpan[] = [];
+  let rest = text;
+  while (rest.length > 0) {
+    const match = INLINE_PATTERN.exec(rest);
+    if (!match || match.index === undefined) {
+      spans.push({ kind: "text", text: rest });
+      break;
+    }
+    if (match.index > 0) {
+      spans.push({ kind: "text", text: rest.slice(0, match.index) });
+    }
+    const token = match[0];
+    if (token.startsWith("`")) {
+      spans.push({ kind: "code", text: token.slice(1, -1) });
+    } else if (token.startsWith("**")) {
+      spans.push({ kind: "bold", text: token.slice(2, -2) });
+    } else if (token.startsWith("*") || token.startsWith("_")) {
+      spans.push({ kind: "italic", text: token.slice(1, -1) });
+    } else {
+      // [text](href) — pattern guarantees the shape and http(s) scheme.
+      const close = token.indexOf("](");
+      spans.push({
+        kind: "link",
+        text: token.slice(1, close),
+        href: token.slice(close + 2, -1),
+      });
+    }
+    rest = rest.slice(match.index + token.length);
+  }
+  return spans;
+}
+
+// --- blocks ------------------------------------------------------------------
+
+const HEADING = /^(#{1,4})\s+(.*)$/;
+const UNORDERED_ITEM = /^\s*[-*]\s+(.*)$/;
+const ORDERED_ITEM = /^\s*\d+[.)]\s+(.*)$/;
+
+export function parseMarkdown(text: string): MarkdownBlock[] {
+  const blocks: MarkdownBlock[] = [];
+  const lines = text.split("\n");
+  let paragraph: string[] = [];
+
+  const flushParagraph = () => {
+    if (paragraph.length === 0) return;
+    blocks.push({
+      kind: "paragraph",
+      spans: parseInline(paragraph.join("\n")),
+    });
+    paragraph = [];
+  };
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Fenced code: consumed to the closing fence (or end — an unclosed
+    // fence still renders as code rather than leaking asterisk parsing).
+    if (line.trimStart().startsWith("```")) {
+      flushParagraph();
+      const language = line.trim().slice(3).trim();
+      const body: string[] = [];
+      i += 1;
+      while (i < lines.length && !lines[i].trimStart().startsWith("```")) {
+        body.push(lines[i]);
+        i += 1;
+      }
+      i += 1; // skip the closing fence (no-op at end of input)
+      blocks.push({ kind: "code", language, text: body.join("\n") });
+      continue;
+    }
+
+    const heading = HEADING.exec(line);
+    if (heading) {
+      flushParagraph();
+      blocks.push({
+        kind: "heading",
+        level: heading[1].length,
+        spans: parseInline(heading[2]),
+      });
+      i += 1;
+      continue;
+    }
+
+    if (line.startsWith(">")) {
+      flushParagraph();
+      const quoted: string[] = [];
+      while (i < lines.length && lines[i].startsWith(">")) {
+        quoted.push(lines[i].replace(/^>\s?/, ""));
+        i += 1;
+      }
+      blocks.push({ kind: "quote", spans: parseInline(quoted.join("\n")) });
+      continue;
+    }
+
+    const unordered = UNORDERED_ITEM.exec(line);
+    const ordered = unordered ? null : ORDERED_ITEM.exec(line);
+    if (unordered || ordered) {
+      flushParagraph();
+      const isOrdered = ordered !== null;
+      const items: InlineSpan[][] = [];
+      while (i < lines.length) {
+        const item = isOrdered
+          ? ORDERED_ITEM.exec(lines[i])
+          : UNORDERED_ITEM.exec(lines[i]);
+        if (!item) break;
+        items.push(parseInline(item[1]));
+        i += 1;
+      }
+      blocks.push({ kind: "list", ordered: isOrdered, items });
+      continue;
+    }
+
+    if (line.trim().length === 0) {
+      flushParagraph();
+      i += 1;
+      continue;
+    }
+
+    paragraph.push(line);
+    i += 1;
+  }
+  flushParagraph();
+  return blocks;
+}
diff --git a/src/features/desktop-agent/lib/panelAcp.ts b/src/features/desktop-agent/lib/panelAcp.ts
new file mode 100644
index 000000000..160f1cd7a
--- /dev/null
+++ b/src/features/desktop-agent/lib/panelAcp.ts
@@ -0,0 +1,118 @@
+// Panel-side ACP operations, built on Berd's shared per-webview
+// connection (src/shared/api/acpConnection) and thin wrappers
+// (src/shared/api/acpApi). The panel is its own webview, so importing
+// these modules gives it its OWN GooseClient — no coordination with the
+// main window's connection.
+//
+// Agent sessions are created directly over ACP with the persona bound at
+// create time:
+//   1. session/new carrying personaId + provider in _meta (the same meta
+//      the main UI writes, so the session list shows the persona badge
+//      and goosed round-trips personaId in session info)
+//   2. the persona system prompt via the goose system-prompt extension
+//      (same seam the main UI uses for persona handoff)
+//   3. the persona model pin via the session config-option seam
+// The first response then STREAMS LIVE — no dispatch, no backfill.
+
+import type { ContentBlock } from "@agentclientprotocol/sdk";
+
+import {
+  appendSessionSystemPrompt,
+  cancelSession,
+  loadSession,
+  newSession,
+  prompt as acpPrompt,
+  setModel,
+} from "@/shared/api/acpApi";
+import { isClientReady } from "@/shared/api/acpConnection";
+import { getHomeDir } from "@/shared/api/system";
+
+import type { AgentInfo } from "../hooks/useSession";
+
+/** The system-prompt slot the main UI uses for persona instructions —
+ *  reusing it keeps panel-created sessions indistinguishable from
+ *  main-UI persona sessions on the wire. */
+const PERSONA_SYSTEM_PROMPT_KEY = "client_system_prompt";
+
+/** DELIBERATE PR1 SCOPE (review 5.4): panel sessions get the persona
+ *  system prompt only — NOT the main UI's full prompt stack (style
+ *  guidelines + berdctl app-context appends from src/shared/api/acp.ts).
+ *  The popover has its own renderer and no berdctl surface, so the same
+ *  persona may read as less app-aware here than in the main window.
+ *  Revisit at graduation alongside the design-system pass. */
+export async function createAgentSession(agent: AgentInfo): Promise<string> {
+  const cwd = await getHomeDir();
+  const response = await newSession(cwd, {
+    personaId: agent.agentId,
+    ...(agent.provider ? { providerId: agent.provider } : {}),
+  });
+  const sessionId = response.sessionId;
+  if (agent.systemPrompt.trim().length > 0) {
+    await appendSessionSystemPrompt(
+      sessionId,
+      PERSONA_SYSTEM_PROMPT_KEY,
+      agent.systemPrompt,
+    );
+  }
+  if (agent.model) {
+    try {
+      await setModel(sessionId, agent.model);
+    } catch (error) {
+      // Soft-fail: the chat still works on the session's default model.
+      // (Right words, default brain — visible in the main UI's session
+      // config if the user checks; a hard failure here would eat the
+      // user's first message over a preference.)
+      console.warn("[desktop-agent] persona model pin failed:", error);
+    }
+  }
+  return sessionId;
+}
+
+export async function createFreshSession(): Promise<string> {
+  const cwd = await getHomeDir();
+  const response = await newSession(cwd, {});
+  return response.sessionId;
+}
+
+export async function promptSession(
+  sessionId: string,
+  content: Array<Record<string, unknown>>,
+): Promise<void> {
+  await acpPrompt(sessionId, content as unknown as ContentBlock[]);
+}
+
+export async function cancelPanelSession(sessionId: string): Promise<void> {
+  await cancelSession(sessionId);
+}
+
+export type AdoptOutcome = "adopted" | "stale" | "transient";
+
+/** Adopt probe: session/load replays the transcript through the
+ *  notification handler and proves the id still exists.
+ *
+ *  Failure is TWO different stories and the caller must not conflate
+ *  them (review finding: a transient failure once wiped persistence —
+ *  one flaky moment at startup silently unlinked the conversation
+ *  forever, even though the session still existed server-side):
+ *  - "stale": the connection is still healthy, so the rejection came
+ *    from goosed itself — the id is unloadable (deleted session, wiped
+ *    server storage). The caller may clear persistence.
+ *  - "transient": the connection died during the probe (socket drop
+ *    mid-replay, goosed hiccup). The id may be perfectly fine — the
+ *    caller must keep persistence and let the reconnect retry. */
+export async function adoptSession(sessionId: string): Promise<AdoptOutcome> {
+  try {
+    await loadSession(sessionId, await getHomeDir());
+    return "adopted";
+  } catch {
+    // isClientReady flips false when the closed-monitor clears the
+    // cached client. A healthy connection + a rejection = goosed
+    // refused the id; a dead connection = we never really asked.
+    // One macrotask of grace first: the pending-request rejection and
+    // the closed settlement race on the same socket-death event, and
+    // misreading a dying connection as healthy would re-create the
+    // exact wipe this classification exists to prevent.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    return isClientReady() ? "stale" : "transient";
+  }
+}
diff --git a/src/features/desktop-agent/lib/panelConnection.test.ts b/src/features/desktop-agent/lib/panelConnection.test.ts
new file mode 100644
index 000000000..23733437e
--- /dev/null
+++ b/src/features/desktop-agent/lib/panelConnection.test.ts
@@ -0,0 +1,232 @@
+// Fake-driven tests for the panel connection lifecycle: single-flight
+// attach, the one automatic re-attach after a close, exhaustion on the
+// second consecutive failure, and dispose/revive (StrictMode) semantics.
+
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import { PanelConnection, type PanelClientLike } from "./panelConnection";
+
+interface EventLog {
+  attached: number;
+  detached: number;
+  failures: Array<{ error: string; exhausted: boolean }>;
+}
+
+function harness(script: Array<"ok" | "fail">) {
+  const log: EventLog = { attached: 0, detached: 0, failures: [] };
+  const closers: Array<(value: unknown) => void> = [];
+  const rejecters: Array<(reason: unknown) => void> = [];
+  let call = 0;
+  const connection = new PanelConnection(
+    {
+      connect: () => {
+        const outcome = script[Math.min(call, script.length - 1)];
+        call += 1;
+        if (outcome === "fail")
+          return Promise.reject(new Error(`dial-${call}`));
+        let close!: (value: unknown) => void;
+        const closed = new Promise((resolve, reject) => {
+          close = resolve;
+          rejecters.push(reject);
+        });
+        closers.push(close);
+        return Promise.resolve({ closed } satisfies PanelClientLike);
+      },
+    },
+    {
+      onAttached: () => {
+        log.attached += 1;
+      },
+      onDetached: () => {
+        log.detached += 1;
+      },
+      onFailed: (error, exhausted) => {
+        log.failures.push({ error, exhausted });
+      },
+    },
+  );
+  return { connection, log, closers, rejecters, calls: () => call };
+}
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+const flushMicrotasks = () => Promise.resolve();
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("PanelConnection", () => {
+  test("attach succeeds and reports attached once", async () => {
+    const h = harness(["ok"]);
+    expect(await h.connection.attach()).toBe(true);
+    expect(h.log.attached).toBe(1);
+    expect(h.log.failures).toHaveLength(0);
+  });
+
+  test("single-flight: concurrent attaches dial once", async () => {
+    const h = harness(["ok"]);
+    const [first, second] = await Promise.all([
+      h.connection.attach(),
+      h.connection.attach(),
+    ]);
+    expect([first, second].filter(Boolean)).toHaveLength(1);
+    expect(h.calls()).toBe(1);
+  });
+
+  test("close triggers one automatic re-attach", async () => {
+    const h = harness(["ok", "ok"]);
+    await h.connection.attach();
+    h.closers[0](undefined); // connection dies
+    await tick();
+    expect(h.log.detached).toBe(1);
+    expect(h.log.attached).toBe(2); // recovered
+    expect(h.log.failures).toHaveLength(0);
+  });
+
+  test("failed automatic recovery reports exhaustion", async () => {
+    const h = harness(["ok", "fail"]);
+    await h.connection.attach();
+    h.closers[0](undefined);
+    await tick();
+    expect(h.log.detached).toBe(1);
+    expect(h.log.failures).toEqual([
+      { error: "Error: dial-2", exhausted: true },
+    ]);
+  });
+
+  test("initial attach failure waits briefly before one automatic retry", async () => {
+    vi.useFakeTimers();
+    const h = harness(["fail", "fail"]);
+    expect(await h.connection.attach()).toBe(false);
+    expect(h.calls()).toBe(1);
+    expect(h.log.failures).toEqual([
+      { error: "Error: dial-1", exhausted: false },
+    ]);
+
+    await vi.advanceTimersByTimeAsync(749);
+    expect(h.calls()).toBe(1);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await flushMicrotasks();
+    expect(h.calls()).toBe(2);
+    expect(h.log.failures).toEqual([
+      { error: "Error: dial-1", exhausted: false },
+      { error: "Error: dial-2", exhausted: true },
+    ]);
+  });
+
+  test("manual retry before delayed initial recovery prevents an extra automatic dial", async () => {
+    vi.useFakeTimers();
+    const h = harness(["fail", "ok", "fail"]);
+    expect(await h.connection.attach()).toBe(false);
+    expect(h.calls()).toBe(1);
+
+    expect(await h.connection.attach()).toBe(true);
+    expect(h.calls()).toBe(2);
+    expect(h.log.attached).toBe(1);
+
+    await vi.advanceTimersByTimeAsync(750);
+    await flushMicrotasks();
+    expect(h.calls()).toBe(2);
+    expect(h.log.failures).toEqual([
+      { error: "Error: dial-1", exhausted: false },
+    ]);
+  });
+
+  test("manual retry after initial exhaustion redials and can recover", async () => {
+    vi.useFakeTimers();
+    const h = harness(["fail", "fail", "ok"]);
+    expect(await h.connection.attach()).toBe(false);
+    await vi.advanceTimersByTimeAsync(750);
+    await flushMicrotasks();
+    expect(h.log.failures.at(-1)?.exhausted).toBe(true);
+    expect(await h.connection.attach()).toBe(true);
+    expect(h.calls()).toBe(3);
+    expect(h.log.attached).toBe(1);
+  });
+
+  test("StrictMode remount: attach bounced off an in-flight disposed dial redials", async () => {
+    // Mount 1 dials (slow), cleanup disposes, mount 2 revives and
+    // attaches into the single-flight guard. The stale dial's finally
+    // must serve the bounced request — otherwise the panel sits
+    // unattached until a manual retry.
+    const h = harness(["ok", "ok"]);
+    let resolveFirst!: (client: PanelClientLike) => void;
+    const firstDial = new Promise<PanelClientLike>((resolve) => {
+      resolveFirst = resolve;
+    });
+    let call = 0;
+    const connection = new PanelConnection(
+      {
+        connect: () => {
+          call += 1;
+          if (call === 1) return firstDial;
+          return Promise.resolve({ closed: new Promise(() => {}) });
+        },
+      },
+      {
+        onAttached: () => {
+          h.log.attached += 1;
+        },
+        onDetached: () => {
+          h.log.detached += 1;
+        },
+        onFailed: (error, exhausted) => {
+          h.log.failures.push({ error, exhausted });
+        },
+      },
+    );
+    const first = connection.attach(); // mount 1
+    connection.dispose(); // mount 1 cleanup
+    connection.revive(); // mount 2
+    const second = connection.attach(); // bounces off the guard
+    expect(await second).toBe(false);
+    resolveFirst({ closed: new Promise(() => {}) });
+    expect(await first).toBe(false); // orphaned by the dispose
+    await tick();
+    expect(call).toBe(2); // the bounced request redialed
+    expect(h.log.attached).toBe(1); // and attached
+    expect(h.log.failures).toHaveLength(0);
+  });
+
+  test("second close after a successful recovery gets its own auto re-attach", async () => {
+    // Pins "one auto attempt per CLOSE, reset on success" (review 8.2
+    // edge 1) — a regression to once-per-process would fail here.
+    const h = harness(["ok", "ok", "ok"]);
+    await h.connection.attach();
+    h.closers[0](undefined); // close #1
+    await tick();
+    expect(h.log.attached).toBe(2); // recovered
+    h.closers[1](undefined); // close #2, after recovery
+    await tick();
+    expect(h.log.attached).toBe(3); // recovered again
+    expect(h.log.detached).toBe(2);
+    expect(h.log.failures).toHaveLength(0);
+  });
+
+  test("a REJECTING closed (socket error) triggers the same auto re-attach", async () => {
+    // watchClosed must settle on the reject arm too (review 8.2 edge 2)
+    // — sockets erroring is the likelier real-world death.
+    const h = harness(["ok", "ok"]);
+    await h.connection.attach();
+    h.rejecters[0](new Error("socket died"));
+    await tick();
+    expect(h.log.detached).toBe(1);
+    expect(h.log.attached).toBe(2); // recovered
+    expect(h.log.failures).toHaveLength(0);
+  });
+
+  test("dispose orphans the closed watcher; revive allows re-attach", async () => {
+    const h = harness(["ok", "ok"]);
+    await h.connection.attach();
+    h.connection.dispose();
+    h.closers[0](undefined); // stale close after dispose
+    await tick();
+    expect(h.log.detached).toBe(0); // orphaned — no events, no redial
+    expect(h.calls()).toBe(1);
+
+    h.connection.revive();
+    expect(await h.connection.attach()).toBe(true);
+    expect(h.log.attached).toBe(2);
+  });
+});
diff --git a/src/features/desktop-agent/lib/panelConnection.ts b/src/features/desktop-agent/lib/panelConnection.ts
new file mode 100644
index 000000000..73b5dc721
--- /dev/null
+++ b/src/features/desktop-agent/lib/panelConnection.ts
@@ -0,0 +1,147 @@
+// Panel connection lifecycle — the in-process replacement for the
+// prototype's ConnectionSupervisor. goosed is spawned once per Berd
+// process and lives (and dies) with the app, so the 3s/180s blind retry
+// loop is gone. What remains is Berd's reconnect-on-demand pattern: the
+// shared acpConnection clears its cached client when the socket closes,
+// and the next connect() dials fresh. This class owns the panel-side
+// choreography around that seam:
+//
+// - single-flight attach (StrictMode double-mounts, retry mashing)
+// - watch `client.closed` and auto re-attach ONCE; a second consecutive
+//   failure reports exhaustion (the manual retry affordance takes over —
+//   claiming "reconnecting…" forever when goosed died with the app would
+//   be a lie)
+// - dispose() for unmount (late resolutions must not mutate anything)
+//
+// Ports are injected so the whole lifecycle is fake-testable.
+
+export interface PanelClientLike {
+  /** Resolves (or rejects) when the underlying connection closes. */
+  closed: Promise<unknown>;
+}
+
+export interface PanelConnectionPorts {
+  /** Production: acpConnection.getClient(). Must dial fresh after the
+   *  previous connection closed (the shared module guarantees this). */
+  connect(): Promise<PanelClientLike>;
+}
+
+const INITIAL_ATTACH_RECOVERY_DELAY_MS = 750;
+
+export interface PanelConnectionEvents {
+  /** Connected (or re-connected). Fires once per successful attach. */
+  onAttached(): void;
+  /** Connection lost; an automatic re-attach may follow. */
+  onDetached(): void;
+  /** An attach attempt failed. `exhausted` is true when no further
+   *  automatic attempt will happen. */
+  onFailed(error: string, exhausted: boolean): void;
+}
+
+export class PanelConnection {
+  private attaching = false;
+  private disposed = false;
+  /** Orphans stale closed-watchers after re-attach/dispose. */
+  private generation = 0;
+  private everAttached = false;
+  /** An attach bounced off the single-flight guard while the in-flight
+   *  dial belonged to a DISPOSED generation (StrictMode: mount 1 dials,
+   *  cleanup disposes, mount 2 revives and attaches into the guard). The
+   *  stale dial's finally honors this by redialing for the live
+   *  generation — without it the panel would sit unattached until a
+   *  manual retry. */
+  private reattachRequested = false;
+  private initialRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
+  private initialRecoveryScheduled = false;
+
+  constructor(
+    private readonly ports: PanelConnectionPorts,
+    private readonly events: PanelConnectionEvents,
+  ) {}
+
+  /** Attach once (single-flight). `auto` marks automatic recovery
+   *  attempts: their failure is exhaustion; a manual attach failing is
+   *  not (the user can click again). */
+  async attach(auto = false): Promise<boolean> {
+    if (this.disposed) return false;
+    if (this.attaching) {
+      this.reattachRequested = true;
+      return false;
+    }
+    if (!auto && !this.everAttached && this.initialRecoveryScheduled) {
+      this.clearInitialRecovery();
+    }
+    this.attaching = true;
+    const generation = ++this.generation;
+    try {
+      const client = await this.ports.connect();
+      if (this.disposed || generation !== this.generation) return false;
+      this.clearInitialRecovery();
+      this.everAttached = true;
+      this.events.onAttached();
+      this.watchClosed(client, generation);
+      return true;
+    } catch (error) {
+      if (!this.disposed && generation === this.generation) {
+        this.events.onFailed(String(error), auto);
+        if (!auto && !this.everAttached) {
+          this.scheduleInitialRecovery();
+        }
+      }
+      return false;
+    } finally {
+      this.attaching = false;
+      // Serve a bounced attach only when this dial's outcome was orphaned
+      // (generation moved on) — a same-generation success already served
+      // every caller via onAttached.
+      const orphanedRequest =
+        this.reattachRequested &&
+        !this.disposed &&
+        generation !== this.generation;
+      this.reattachRequested = false;
+      if (orphanedRequest) void this.attach(auto);
+    }
+  }
+
+  private scheduleInitialRecovery(): void {
+    if (this.initialRecoveryScheduled) return;
+    this.initialRecoveryScheduled = true;
+    // A first attach failure is equivalent to a dropped connection, but give
+    // goosed a short beat before the bounded recovery dial. Manual Retry after
+    // the first failure owns the next dial and must not queue an extra auto one.
+    this.initialRecoveryTimer = setTimeout(() => {
+      this.initialRecoveryTimer = null;
+      if (this.disposed || this.everAttached) return;
+      void this.attach(true);
+    }, INITIAL_ATTACH_RECOVERY_DELAY_MS);
+  }
+
+  private clearInitialRecovery(): void {
+    if (this.initialRecoveryTimer === null) return;
+    clearTimeout(this.initialRecoveryTimer);
+    this.initialRecoveryTimer = null;
+  }
+
+  private watchClosed(client: PanelClientLike, generation: number): void {
+    const settle = () => {
+      if (this.disposed || generation !== this.generation) return;
+      this.events.onDetached();
+      // One automatic recovery attempt: goosed restarts are Berd-driven
+      // (a fresh spawn under the same process), so a single fresh dial
+      // either finds it or nothing is coming back.
+      void this.attach(true);
+    };
+    client.closed.then(settle, settle);
+  }
+
+  /** StrictMode second mount undoes the first cleanup's dispose. */
+  revive(): void {
+    this.disposed = false;
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.clearInitialRecovery();
+    this.generation += 1;
+  }
+}
diff --git a/src/features/desktop-agent/lib/panelState.test.ts b/src/features/desktop-agent/lib/panelState.test.ts
new file mode 100644
index 000000000..604c0c9c6
--- /dev/null
+++ b/src/features/desktop-agent/lib/panelState.test.ts
@@ -0,0 +1,318 @@
+// Ported from the prototype's test/shell/panel_state_test.dart — same cases against
+// the same state-machine semantics, with the platform channel replaced by
+// a fake WindowPort/PositionStore.
+
+import { beforeEach, describe, expect, test } from "vitest";
+
+import {
+  popoverGlobal,
+  rect,
+  type Rect,
+  type ScreenInfo,
+} from "./anchorGeometry";
+import {
+  AVATAR_PANEL_SIZE,
+  PanelStateMachine,
+  type PositionStore,
+  type WindowPort,
+} from "./panelState";
+
+const screens: ScreenInfo[] = [
+  {
+    frame: rect(0, 0, 1440, 900),
+    visibleFrame: rect(0, 25, 1440, 815),
+    isMain: true,
+  },
+];
+
+class FakeWindow implements WindowPort {
+  panelFrame: Rect = rect(700, 700, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+  calls: string[] = [];
+  setStates: Array<{ expanded: boolean; frame: Rect }> = [];
+
+  async getScreens(): Promise<ScreenInfo[]> {
+    this.calls.push("getScreens");
+    return screens;
+  }
+
+  async getPanelFrame(): Promise<Rect> {
+    this.calls.push("getPanelFrame");
+    return this.panelFrame;
+  }
+
+  async setState(args: { expanded: boolean; frame: Rect }): Promise<void> {
+    this.calls.push("setState");
+    this.setStates.push(args);
+    this.panelFrame = args.frame;
+  }
+
+  async startDrag(): Promise<void> {
+    this.calls.push("startDrag");
+  }
+}
+
+class MemoryStore implements PositionStore {
+  saved: { x: number; y: number } | null = null;
+
+  async load(): Promise<{ x: number; y: number } | null> {
+    return this.saved;
+  }
+
+  async save(position: { x: number; y: number }): Promise<void> {
+    this.saved = position;
+  }
+}
+
+let window_: FakeWindow;
+let store: MemoryStore;
+let machine: PanelStateMachine;
+
+beforeEach(() => {
+  window_ = new FakeWindow();
+  store = new MemoryStore();
+  machine = new PanelStateMachine({ window: window_, positionStore: store });
+});
+
+function lastSetState(window_: {
+  setStates: Array<{ expanded: boolean; frame: Rect }>;
+}): {
+  expanded: boolean;
+  frame: Rect;
+} {
+  const last = window_.setStates.at(-1);
+  if (!last) throw new Error("expected at least one setState call");
+  return last;
+}
+
+describe("PanelStateMachine", () => {
+  test("syncFromPanel tracks current panel frame without persisting", async () => {
+    window_.panelFrame = rect(320, 240, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+
+    await machine.syncFromPanel();
+    await machine.collapse();
+
+    expect(window_.panelFrame).toEqual(
+      rect(320, 240, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE),
+    );
+    expect(store.saved).toBeNull();
+    expect(window_.calls).toEqual(["getPanelFrame", "setState"]);
+  });
+
+  test("restore uses saved position, clamped to the visible screen", async () => {
+    store.saved = { x: 5000, y: -200 }; // way off-screen
+    await machine.restore();
+
+    const applied = lastSetState(window_);
+    expect(applied.expanded).toBe(false);
+    // Clamped fully inside the visible frame.
+    expect(applied.frame.x).toBeLessThanOrEqual(1440 - AVATAR_PANEL_SIZE);
+    expect(applied.frame.y).toBeGreaterThanOrEqual(25);
+  });
+
+  test("restore without a saved position adopts the current panel frame", async () => {
+    window_.panelFrame = rect(300, 300, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+    await machine.restore();
+
+    const applied = lastSetState(window_);
+    expect(applied.frame).toEqual(
+      rect(300, 300, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE),
+    );
+  });
+
+  test("expand/collapse preserves the avatar anchor (anti-blink sequencing)", async () => {
+    window_.panelFrame = rect(600, 700, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+    await machine.syncFromPanel();
+
+    const layout = await machine.computeExpanded();
+    // Layout computed WITHOUT any native setState (the anti-blink contract):
+    expect(window_.setStates).toHaveLength(0);
+
+    await machine.applyExpanded(layout);
+    expect(machine.mode).toBe("expanded");
+    // Avatar's global position inside the expanded window is unchanged.
+    expect({
+      x: layout.avatarRect.x + layout.windowFrame.x,
+      y: layout.avatarRect.y + layout.windowFrame.y,
+    }).toEqual({ x: 600, y: 700 });
+
+    await machine.collapse();
+    expect(machine.mode).toBe("avatar");
+    const collapsed = lastSetState(window_);
+    expect(collapsed.expanded).toBe(false);
+    expect(collapsed.frame).toEqual(
+      rect(600, 700, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE),
+    );
+  });
+
+  test("recomputing while expanded does not adopt the expanded window as the avatar frame", async () => {
+    window_.panelFrame = rect(600, 700, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+    await machine.syncFromPanel();
+
+    const layout = await machine.computeExpanded({ width: 380, height: 96 });
+    await machine.applyExpanded(layout);
+    expect(window_.panelFrame).toEqual(layout.windowFrame);
+
+    const grown = await machine.computeExpanded({ width: 500, height: 520 });
+
+    expect({
+      x: grown.avatarRect.x + grown.windowFrame.x,
+      y: grown.avatarRect.y + grown.windowFrame.y,
+      width: grown.avatarRect.width,
+      height: grown.avatarRect.height,
+    }).toEqual(rect(600, 700, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE));
+
+    await machine.applyExpanded(grown);
+    await machine.collapse();
+
+    expect(lastSetState(window_)).toEqual({
+      expanded: false,
+      frame: rect(600, 700, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE),
+    });
+  });
+
+  test("computeGrown reuses cached avatar without syncing from the expanded panel", async () => {
+    window_.panelFrame = rect(600, 700, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+    await machine.syncFromPanel();
+
+    const composer = await machine.computeExpanded(
+      { width: 380, height: 96 },
+      "side",
+    );
+    await machine.applyExpanded(composer);
+    window_.calls = [];
+
+    const grown = await machine.computeGrown({
+      fromPopoverGlobal: popoverGlobal(composer),
+      composerBottomGlobal:
+        composer.windowFrame.y +
+        composer.popoverRect.y +
+        composer.popoverRect.height,
+      bottomInset: 16,
+      fromPopoverSide: composer.popoverSide,
+    });
+
+    expect(window_.calls).toEqual(["getScreens"]);
+    expect({
+      x: grown.avatarRect.x + grown.windowFrame.x,
+      y: grown.avatarRect.y + grown.windowFrame.y,
+      width: grown.avatarRect.width,
+      height: grown.avatarRect.height,
+    }).toEqual(rect(600, 700, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE));
+  });
+
+  test("computeMenu/applyMenu grows the window but returns to the saved avatar frame", async () => {
+    window_.panelFrame = rect(420, 500, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+    await machine.syncFromPanel();
+
+    const layout = await machine.computeMenu({ width: 438, height: 124 });
+    await machine.applyMenu(layout);
+
+    expect(machine.mode).toBe("menu");
+    expect(lastSetState(window_)).toEqual({
+      expanded: true,
+      frame: layout.windowFrame,
+    });
+
+    await machine.collapse();
+
+    expect(machine.mode).toBe("avatar");
+    expect(lastSetState(window_)).toEqual({
+      expanded: false,
+      frame: rect(420, 500, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE),
+    });
+  });
+
+  test("onDragEnded clamps and persists the new position", async () => {
+    await machine.restore();
+    // Simulate the OS drag leaving the panel hanging off the bottom edge.
+    window_.panelFrame = rect(200, 880, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+
+    await machine.onDragEnded();
+
+    // Clamped back inside the visible frame (bottom = 25 + 815 = 840).
+    const applied = lastSetState(window_);
+    expect(applied.frame.y).toBe(840 - AVATAR_PANEL_SIZE);
+    expect(store.saved).toEqual({ x: 200, y: 840 - AVATAR_PANEL_SIZE });
+  });
+
+  test("onDragEnded skips setState when position is already legal", async () => {
+    await machine.restore();
+    const before = window_.setStates.length;
+    window_.panelFrame = rect(400, 400, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+
+    await machine.onDragEnded();
+
+    expect(window_.setStates.length).toBe(before); // no extra setState
+    expect(store.saved).toEqual({ x: 400, y: 400 });
+  });
+
+  test("onDragEndedPerched syncs from panel without saving free position", async () => {
+    // the prototype case: native perch placement owns the panel; the free-position
+    // store must not learn the perched coordinates.
+    window_.panelFrame = rect(450, 120, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+
+    await machine.onDragEndedPerched();
+    await machine.collapse();
+
+    expect(window_.panelFrame).toEqual(
+      rect(450, 120, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE),
+    );
+    expect(store.saved).toBeNull();
+    expect(window_.calls).toEqual(["getPanelFrame", "setState"]);
+  });
+
+  test("returnToSavedPosition restores the saved free position, clamped", async () => {
+    store.saved = { x: 5000, y: -200 }; // stale off-screen save
+    await machine.returnToSavedPosition();
+
+    const applied = lastSetState(window_);
+    expect(applied.expanded).toBe(false);
+    expect(applied.frame.x).toBeLessThanOrEqual(1440 - AVATAR_PANEL_SIZE);
+    expect(applied.frame.y).toBeGreaterThanOrEqual(25);
+    expect(machine.mode).toBe("avatar");
+  });
+
+  test("returnToSavedPosition without a save adopts the current frame", async () => {
+    window_.panelFrame = rect(333, 444, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+    await machine.returnToSavedPosition();
+
+    const applied = lastSetState(window_);
+    expect(applied.frame).toEqual(
+      rect(333, 444, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE),
+    );
+  });
+
+  test("returnToSavedPosition is ignored while menu is open", async () => {
+    await machine.syncFromPanel();
+    const layout = await machine.computeMenu({ width: 438, height: 124 });
+    await machine.applyMenu(layout);
+    const statesBefore = window_.setStates.length;
+
+    await machine.returnToSavedPosition();
+
+    expect(machine.mode).toBe("menu");
+    expect(window_.setStates.length).toBe(statesBefore);
+  });
+
+  test("returnToSavedPosition is ignored while expanded", async () => {
+    // the prototype case: an in-progress popover must not be yanked to avatar size.
+    await machine.syncFromPanel();
+    const layout = await machine.computeExpanded();
+    await machine.applyExpanded(layout);
+    const statesBefore = window_.setStates.length;
+
+    await machine.returnToSavedPosition();
+
+    expect(machine.mode).toBe("expanded");
+    expect(window_.setStates.length).toBe(statesBefore); // untouched
+  });
+
+  test("drag is rejected while expanded", async () => {
+    await machine.syncFromPanel();
+    const layout = await machine.computeExpanded();
+    await machine.applyExpanded(layout);
+
+    await expect(machine.onDragStarted()).rejects.toThrow();
+    await expect(machine.onDragEnded()).rejects.toThrow();
+  });
+});
diff --git a/src/features/desktop-agent/lib/panelState.ts b/src/features/desktop-agent/lib/panelState.ts
new file mode 100644
index 000000000..7751e353c
--- /dev/null
+++ b/src/features/desktop-agent/lib/panelState.ts
@@ -0,0 +1,260 @@
+// Panel state machine — ported from the prototype's lib/shell/panel_state.dart.
+//
+// Owns the avatar/expanded state machine and keeps the native panel frame,
+// key-window eligibility, and persisted avatar position in sync. All
+// geometry decisions delegate to anchorGeometry (pure, unit-tested); this
+// class sequences the platform calls.
+//
+// Anti-blink sequencing:
+// computeExpanded() is separated from applyExpanded() so the caller can
+// commit the layout to the UI tree BEFORE the native resize — the resize
+// repaint then finds a tree that already knows the layout, and the panel
+// never flashes at the wrong size/position.
+
+import {
+  clampAvatarToScreens,
+  computeExpandedLayout,
+  computeGrownLayout,
+  rect,
+  type ExpandedLayout,
+  type ExpandedPlacement,
+  type Rect,
+  type ScreenInfo,
+  type Size,
+} from "./anchorGeometry";
+
+export const AVATAR_PANEL_SIZE = 94;
+
+export type PanelMode = "avatar" | "expanded" | "menu";
+
+/**
+ * Platform seam — implemented over Tauri invoke in production, faked in
+ * tests.
+ */
+export interface WindowPort {
+  getScreens(): Promise<ScreenInfo[]>;
+  getPanelFrame(): Promise<Rect>;
+  setState(args: { expanded: boolean; frame: Rect }): Promise<void>;
+  startDrag(): Promise<void>;
+}
+
+/** Persistence seam. */
+export interface PositionStore {
+  load(): Promise<{ x: number; y: number } | null>;
+  save(position: { x: number; y: number }): Promise<void>;
+}
+
+export class PanelStateMachine {
+  private readonly window: WindowPort;
+  private readonly positionStore: PositionStore;
+  readonly avatarSize: Size;
+  readonly popoverSize: Size;
+
+  private modeInternal: PanelMode = "avatar";
+  /**
+   * Avatar frame in global top-left coordinates. This is the anchor
+   * invariant: it must not change during expand/collapse.
+   */
+  private avatarGlobal: Rect = rect(0, 0, AVATAR_PANEL_SIZE, AVATAR_PANEL_SIZE);
+
+  constructor(args: {
+    window: WindowPort;
+    positionStore: PositionStore;
+    avatarSize?: Size;
+    popoverSize?: Size;
+  }) {
+    this.window = args.window;
+    this.positionStore = args.positionStore;
+    this.avatarSize = args.avatarSize ?? {
+      width: AVATAR_PANEL_SIZE,
+      height: AVATAR_PANEL_SIZE,
+    };
+    this.popoverSize = args.popoverSize ?? { width: 380, height: 520 };
+  }
+
+  get mode(): PanelMode {
+    return this.modeInternal;
+  }
+
+  /** Current avatar frame (global top-left). Exposed for the UI layer. */
+  get avatarFrame(): Rect {
+    return this.avatarGlobal;
+  }
+
+  /**
+   * Restores the persisted avatar position (clamped onto a visible screen)
+   * and applies the initial avatar frame to the native panel.
+   */
+  async restore(): Promise<void> {
+    const screens = await this.window.getScreens();
+    const saved = await this.positionStore.load();
+    const requested = saved
+      ? rect(saved.x, saved.y, this.avatarSize.width, this.avatarSize.height)
+      : await this.window.getPanelFrame();
+    this.avatarGlobal = clampAvatarToScreens(
+      rect(
+        requested.x,
+        requested.y,
+        this.avatarSize.width,
+        this.avatarSize.height,
+      ),
+      screens,
+    );
+    await this.window.setState({ expanded: false, frame: this.avatarGlobal });
+  }
+
+  /**
+   * Computes the expanded layout WITHOUT touching the native panel, so
+   * callers can commit it to the UI tree before the native resize
+   * (anti-blink sequencing — see module comment). `size` overrides the
+   * default popover size (the composer-only first-run popover is
+   * smaller; growing to the full chat re-runs this same path).
+   */
+  async computeExpanded(
+    size?: Size,
+    placement?: ExpandedPlacement,
+  ): Promise<ExpandedLayout> {
+    if (this.modeInternal === "avatar") {
+      await this.syncFromPanel();
+    }
+    const screens = await this.window.getScreens();
+    return computeExpandedLayout({
+      avatarGlobal: this.avatarGlobal,
+      popoverSize: size ?? this.popoverSize,
+      screens,
+      placement,
+    });
+  }
+
+  /**
+   * Computes the full-chat layout while growing from an existing composer-only
+   * popover. Reuses the cached avatar anchor: in expanded mode the native
+   * panel frame is the grown window, not the avatar frame.
+   */
+  async computeGrown(args: {
+    fromPopoverGlobal: Rect;
+    composerBottomGlobal: number;
+    bottomInset: number;
+    fromPopoverSide: "left" | "right" | null;
+  }): Promise<ExpandedLayout> {
+    const screens = await this.window.getScreens();
+    return computeGrownLayout({
+      avatarGlobal: this.avatarGlobal,
+      fromPopoverGlobal: args.fromPopoverGlobal,
+      composerBottomGlobal: args.composerBottomGlobal,
+      popoverSize: this.popoverSize,
+      screens,
+      bottomInset: args.bottomInset,
+      fromPopoverSide: args.fromPopoverSide,
+    });
+  }
+
+  /** Applies a layout from computeExpanded() to the native panel. */
+  async applyExpanded(layout: ExpandedLayout): Promise<void> {
+    await this.window.setState({ expanded: true, frame: layout.windowFrame });
+    this.modeInternal = "expanded";
+  }
+
+  /**
+   * Computes the layout for the avatar context menu — the same grown-
+   * window geometry as the chat popover (the collapsed window is
+   * avatar-sized; a menu needs room), just a different overlay size and a
+   * distinct mode so gesture guards can tell menu from chat.
+   */
+  async computeMenu(size: Size): Promise<ExpandedLayout> {
+    return this.computeExpanded(size);
+  }
+
+  /** Applies a layout from computeMenu() to the native panel. */
+  async applyMenu(layout: ExpandedLayout): Promise<void> {
+    await this.window.setState({ expanded: true, frame: layout.windowFrame });
+    this.modeInternal = "menu";
+  }
+
+  /**
+   * Collapses back to the avatar-only frame and returns key status to the
+   * previously active app.
+   */
+  async collapse(): Promise<void> {
+    await this.window.setState({ expanded: false, frame: this.avatarGlobal });
+    this.modeInternal = "avatar";
+  }
+
+  /**
+   * Restores the last persisted free-floating avatar position. Used when a
+   * native perch relationship ends without a drag dismount.
+   */
+  async returnToSavedPosition(): Promise<void> {
+    if (this.modeInternal !== "avatar") return;
+    const screens = await this.window.getScreens();
+    const saved = await this.positionStore.load();
+    const requested = saved
+      ? rect(saved.x, saved.y, this.avatarSize.width, this.avatarSize.height)
+      : await this.window.getPanelFrame();
+    this.avatarGlobal = clampAvatarToScreens(
+      rect(
+        requested.x,
+        requested.y,
+        this.avatarSize.width,
+        this.avatarSize.height,
+      ),
+      screens,
+    );
+    await this.window.setState({ expanded: false, frame: this.avatarGlobal });
+    this.modeInternal = "avatar";
+  }
+
+  /**
+   * Re-reads the current avatar frame WITHOUT saving the free position —
+   * native perch placement owns the panel while perched.
+   */
+  async onDragEndedPerched(): Promise<void> {
+    return this.syncFromPanel();
+  }
+
+  /**
+   * Hands the in-flight pointer sequence to native performDrag. Only valid
+   * in avatar mode (dragging is disabled while expanded).
+   */
+  async onDragStarted(): Promise<void> {
+    if (this.modeInternal !== "avatar")
+      throw new Error("drag only in avatar mode");
+    return this.window.startDrag();
+  }
+
+  /**
+   * Called after a native drag completes: re-reads the panel frame, clamps
+   * it onto a visible screen, and persists the new avatar position.
+   */
+  async onDragEnded(): Promise<void> {
+    if (this.modeInternal !== "avatar")
+      throw new Error("drag only in avatar mode");
+    const screens = await this.window.getScreens();
+    const frame = await this.window.getPanelFrame();
+    this.avatarGlobal = clampAvatarToScreens(
+      rect(frame.x, frame.y, this.avatarSize.width, this.avatarSize.height),
+      screens,
+    );
+    if (this.avatarGlobal.x !== frame.x || this.avatarGlobal.y !== frame.y) {
+      await this.window.setState({ expanded: false, frame: this.avatarGlobal });
+    }
+    await this.positionStore.save({
+      x: this.avatarGlobal.x,
+      y: this.avatarGlobal.y,
+    });
+  }
+
+  /**
+   * Re-reads the current avatar frame without changing the free-position
+   * store.
+   */
+  async syncFromPanel(): Promise<void> {
+    const frame = await this.window.getPanelFrame();
+    this.avatarGlobal = rect(
+      frame.x,
+      frame.y,
+      this.avatarSize.width,
+      this.avatarSize.height,
+    );
+  }
+}
diff --git a/src/features/desktop-agent/lib/sendController.test.ts b/src/features/desktop-agent/lib/sendController.test.ts
new file mode 100644
index 000000000..5e11e2ff9
--- /dev/null
+++ b/src/features/desktop-agent/lib/sendController.test.ts
@@ -0,0 +1,482 @@
+// Fake-driven tests for the panel send flows. The FakeSendRpc records
+// call ORDER — the create flows are ordering guarantees, so the tests
+// assert sequences, not just outcomes. Pins:
+//
+// - live prompt: echo first, thinking during, run-end cleanup after
+// - deferred agent create: create → epoch check → commit → onCommitted →
+//   in-flight released BEFORE the prompt (the response streams live)
+// - deferred fresh create: same shape, null agent binding
+// - implicit fresh: no armed selection and no session yet → fresh create
+// - cancel racing a create: no commit, no prompt, nothing mutated
+// - double-send guard: busy sends mutate NOTHING and busy is synchronous
+// - run gate: a second send while a run is active on the
+//   live session bounces — goosed allows one run per session; deferred
+//   creates pass the gate (they target a NEW session); a late orphaned
+//   finally never clears the new owner's gate (generation tokens)
+// - epoch-orphaned finally blocks mutate nothing
+// - perch preamble: wire text carries it, the echo stays bare, and the
+//   guidance ledger burns ONLY after confirmed delivery with the REAL
+//   session id (deferred creates decide full-vs-slim before the id exists)
+
+import { beforeEach, describe, expect, test } from "vitest";
+
+import {
+  SendController,
+  type SendRpc,
+  type SendStatusSink,
+} from "./sendController";
+import { plainText } from "./chatModels";
+import { markGuidanceSent, resetGuidanceLedger } from "./sendSource";
+import { SessionStore } from "./sessionStore";
+import type { AgentInfo, SessionActivity } from "../hooks/useSession";
+
+const agent: AgentInfo = {
+  agentId: "panda",
+  name: "Panda",
+  systemPrompt: "be panda",
+  provider: null,
+  model: null,
+};
+
+class FakeSendRpc implements SendRpc {
+  calls: string[] = [];
+  lastContent: Array<Record<string, unknown>> | null = null;
+  createResult: () => Promise<string> = () => Promise.resolve("new-session");
+  promptResult: () => Promise<void> = () => Promise.resolve();
+
+  prompt(args: {
+    sessionId: string;
+    content: Array<Record<string, unknown>>;
+  }): Promise<void> {
+    this.calls.push(`prompt:${args.sessionId}`);
+    this.lastContent = args.content;
+    return this.promptResult();
+  }
+  createAgentSession(info: AgentInfo): Promise<string> {
+    this.calls.push(`createAgent:${info.agentId}`);
+    return this.createResult();
+  }
+  createFreshSession(): Promise<string> {
+    this.calls.push("createFresh");
+    return this.createResult();
+  }
+  cancel(sessionId: string): Promise<void> {
+    this.calls.push(`cancel:${sessionId}`);
+    return Promise.resolve();
+  }
+}
+
+interface SinkLog {
+  activity: SessionActivity[];
+  sendErrors: Array<string | null>;
+  inFlight: boolean[];
+  committed: number;
+  publishes: number;
+}
+
+function harness() {
+  const store = new SessionStore();
+  const rpc = new FakeSendRpc();
+  const log: SinkLog = {
+    activity: [],
+    sendErrors: [],
+    inFlight: [],
+    committed: 0,
+    publishes: 0,
+  };
+  const sink: SendStatusSink = {
+    setActivity: (activity) => log.activity.push(activity),
+    setLastSendError: (error) => log.sendErrors.push(error),
+    setAgentSendInFlight: (inFlight) => log.inFlight.push(inFlight),
+    onCommitted: () => {
+      log.committed += 1;
+    },
+    publish: () => {
+      log.publishes += 1;
+    },
+  };
+  const controller = new SendController(store, rpc, sink);
+  return { store, rpc, log, controller };
+}
+
+// The guidance ledger is module-scoped (survives component remounts by
+// design) — reset per test so ordering can't leak.
+beforeEach(() => {
+  resetGuidanceLedger();
+});
+
+describe("SendController live prompt", () => {
+  test("happy path: echo, thinking, prompt content, run-end cleanup", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.resetForAdopt("live-1");
+    await controller.send("hello");
+    expect(rpc.calls).toEqual(["prompt:live-1"]);
+    expect(rpc.lastContent).toEqual([{ type: "text", text: "hello" }]);
+    expect(store.messages).toHaveLength(1); // the optimistic echo
+    // thinking during, none after (run-end signal).
+    expect(log.activity).toEqual(["thinking", "none"]);
+    expect(log.sendErrors.filter((e) => e !== null)).toHaveLength(0);
+  });
+
+  test("image blocks ride the same prompt content array", async () => {
+    const { store, rpc, controller } = harness();
+    store.resetForAdopt("live-1");
+    await controller.send("look", [
+      { type: "image", data: "abc", mimeType: "image/png" },
+    ]);
+    expect(rpc.lastContent).toEqual([
+      { type: "text", text: "look" },
+      { type: "image", data: "abc", mimeType: "image/png" },
+    ]);
+  });
+
+  test("prompt failure lands on lastSendError and still cleans up", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.resetForAdopt("live-1");
+    rpc.promptResult = () => Promise.reject(new Error("boom"));
+    await controller.send("hello");
+    // Errors render through formatAcpErrorMessage: the bare message, and
+    // an ACP RequestError's data payload instead of "Invalid params".
+    expect(log.sendErrors).toContain("boom");
+    expect(log.activity[log.activity.length - 1]).toBe("none");
+  });
+
+  test("ACP errors surface their data payload, not the generic message", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.resetForAdopt("live-1");
+    const wireError = Object.assign(new Error("Invalid params"), {
+      name: "RequestError",
+      code: -32602,
+      data: "session already has active run `run_1`; use _goose/unstable/session/steer",
+    });
+    rpc.promptResult = () => Promise.reject(wireError);
+    await controller.send("hello");
+    expect(log.sendErrors).toContain(
+      "session already has active run `run_1`; use _goose/unstable/session/steer",
+    );
+  });
+
+  test("empty text is a no-op", async () => {
+    const { store, rpc, controller } = harness();
+    store.resetForAdopt("live-1");
+    await controller.send("   ");
+    expect(rpc.calls).toHaveLength(0);
+    expect(store.messages).toHaveLength(0);
+  });
+});
+
+describe("SendController deferred agent create", () => {
+  test("create → commit → in-flight released BEFORE the live-streaming prompt", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.resetForAdopt("old-live");
+    store.arm({ kind: "agent", agent });
+    await controller.send("hello");
+    expect(rpc.calls).toEqual(["createAgent:panda", "prompt:new-session"]);
+    expect(store.sessionId).toBe("new-session");
+    expect(store.activeAgentId).toBe("panda");
+    expect(log.committed).toBe(1);
+    // true (entry), false (commit — streaming takes over), false (finally).
+    expect(log.inFlight).toEqual([true, false, false]);
+    // The prompt carries the BARE text (no preamble machinery in PR1).
+    expect(rpc.lastContent).toEqual([{ type: "text", text: "hello" }]);
+  });
+
+  test("cancel racing the create commits nothing and prompts nothing", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.resetForAdopt("old-live");
+    store.arm({ kind: "agent", agent });
+    let resolveCreate!: (id: string) => void;
+    rpc.createResult = () =>
+      new Promise((resolve) => {
+        resolveCreate = resolve;
+      });
+    const send = controller.send("hello");
+    store.cancelArm(); // epoch bump: the user went back
+    resolveCreate("orphan-session");
+    await send;
+    expect(rpc.calls).toEqual(["createAgent:panda"]); // no prompt
+    expect(store.sessionId).toBe("old-live"); // restored, not committed
+    expect(log.committed).toBe(0);
+    // Orphaned finally: the cancel path owns state now — the in-flight
+    // flag was set at entry and must NOT be force-cleared by the stale
+    // flow (select() clears it).
+    expect(log.inFlight).toEqual([true]);
+  });
+
+  test("create failure is a send error; nothing committed", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.arm({ kind: "agent", agent });
+    rpc.createResult = () => Promise.reject(new Error("create failed"));
+    await controller.send("hello");
+    expect(log.sendErrors).toContain("create failed");
+    expect(store.sessionId).toBeNull();
+    expect(log.committed).toBe(0);
+  });
+});
+
+describe("SendController deferred fresh create", () => {
+  test("armed fresh: create → commit(null) → prompt", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.resetForAdopt("old-live");
+    store.restoreAgentBinding("panda");
+    store.arm({ kind: "fresh" });
+    await controller.send("hello");
+    expect(rpc.calls).toEqual(["createFresh", "prompt:new-session"]);
+    expect(store.activeAgentId).toBeNull(); // default avatar
+    expect(log.committed).toBe(1);
+  });
+
+  test("implicit fresh: nothing armed, no session yet", async () => {
+    const { store, rpc, log, controller } = harness();
+    await controller.send("hello");
+    expect(rpc.calls).toEqual(["createFresh", "prompt:new-session"]);
+    expect(store.sessionId).toBe("new-session");
+    expect(log.committed).toBe(1);
+  });
+});
+
+describe("SendController composer gate", () => {
+  test("busy is synchronous and a bounced send mutates nothing", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.arm({ kind: "agent", agent });
+    let resolveCreate!: (id: string) => void;
+    rpc.createResult = () =>
+      new Promise((resolve) => {
+        resolveCreate = resolve;
+      });
+    const first = controller.send("first");
+    expect(controller.busy).toBe(true); // synchronous view
+    const echoCount = store.messages.length;
+    const errorCount = log.sendErrors.length;
+    await controller.send("second"); // bounced
+    expect(store.messages).toHaveLength(echoCount); // no second echo
+    expect(log.sendErrors).toHaveLength(errorCount); // no cleared errors
+    expect(rpc.calls.filter((c) => c.startsWith("createAgent"))).toHaveLength(
+      1,
+    );
+    resolveCreate("new-session");
+    await first;
+    expect(controller.busy).toBe(false);
+  });
+});
+
+describe("SendController run gate", () => {
+  test("second send while the live session's run is active bounces and mutates nothing", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.resetForAdopt("live-1");
+    let resolvePrompt!: () => void;
+    rpc.promptResult = () =>
+      new Promise<void>((resolve) => {
+        resolvePrompt = resolve;
+      });
+    const first = controller.send("first");
+    expect(controller.busy).toBe(true); // synchronous — the composer's check
+    const echoCount = store.messages.length;
+    const errorWrites = log.sendErrors.length;
+    await controller.send("second"); // bounced: goosed allows one run/session
+    expect(store.messages).toHaveLength(echoCount); // no second echo
+    expect(log.sendErrors).toHaveLength(errorWrites); // no cleared errors
+    expect(rpc.calls).toEqual(["prompt:live-1"]); // no second prompt
+    resolvePrompt();
+    await first;
+    expect(controller.busy).toBe(false); // run ended: the gate lifts
+    rpc.promptResult = () => Promise.resolve();
+    await controller.send("third");
+    expect(rpc.calls).toEqual(["prompt:live-1", "prompt:live-1"]);
+  });
+
+  test("create gate lifts at COMMIT (no double-create) but the run gate holds through the first streamed turn", async () => {
+    const { store, rpc, log, controller } = harness();
+    store.arm({ kind: "agent", agent });
+    let resolveFirstPrompt!: () => void;
+    rpc.promptResult = () =>
+      new Promise<void>((resolve) => {
+        resolveFirstPrompt = resolve;
+      });
+    const first = controller.send("hello");
+    await new Promise((r) => setTimeout(r, 0)); // create resolves; commit runs; prompt pending
+    expect(log.committed).toBe(1);
+    // REVISES review 5.1: the create gate still lifts at commit (a
+    // follow-up can never double-create), but the first response is an
+    // ACTIVE RUN on the committed session — goosed rejects a concurrent
+    // prompt, so Enter mid-first-stream bounces like any mid-run send.
+    expect(controller.busy).toBe(true);
+    const echoCount = store.messages.length;
+    await controller.send("mid-stream"); // bounced: mutates nothing
+    expect(store.messages).toHaveLength(echoCount);
+    expect(rpc.calls.filter((c) => c.startsWith("createAgent"))).toHaveLength(
+      1,
+    );
+    expect(rpc.calls.filter((c) => c === "prompt:new-session")).toHaveLength(1);
+    resolveFirstPrompt();
+    await first;
+    // Run ended: follow-ups take the normal prompt path.
+    expect(controller.busy).toBe(false);
+    rpc.promptResult = () => Promise.resolve();
+    await controller.send("follow-up");
+    expect(rpc.calls.filter((c) => c === "prompt:new-session")).toHaveLength(2);
+  });
+
+  test("an armed selection escapes the run gate; the old run's late finally cannot clear the new owner's gate", async () => {
+    const { store, rpc, controller } = harness();
+    store.resetForAdopt("live-1");
+    let resolveOldPrompt!: () => void;
+    rpc.promptResult = () =>
+      new Promise<void>((resolve) => {
+        resolveOldPrompt = resolve;
+      });
+    const oldSend = controller.send("on the live session");
+    expect(controller.busy).toBe(true);
+    // The user picks an agent mid-stream: the next send targets a NEW
+    // session — one-run-per-session is a per-session rule, so the gate
+    // opens for the deferred create.
+    store.arm({ kind: "agent", agent });
+    expect(controller.busy).toBe(false);
+    let resolveNewPrompt!: () => void;
+    rpc.promptResult = () =>
+      new Promise<void>((resolve) => {
+        resolveNewPrompt = resolve;
+      });
+    const newSend = controller.send("first message to the agent");
+    await new Promise((r) => setTimeout(r, 0)); // create resolves; commit; new prompt pending
+    expect(rpc.calls).toEqual([
+      "prompt:live-1",
+      "createAgent:panda",
+      "prompt:new-session",
+    ]);
+    // The OLD run ends while the new one streams: its stale finally
+    // must not clear the gate the new run owns (generation token).
+    resolveOldPrompt();
+    await oldSend;
+    expect(controller.busy).toBe(true);
+    resolveNewPrompt();
+    await newSend;
+    expect(controller.busy).toBe(false);
+  });
+});
+
+describe("SendController perch preamble + guidance ledger", () => {
+  const makePreamble = (fullGuidance: boolean) =>
+    fullGuidance
+      ? "[Perched on: Chrome]\nguidance sentence"
+      : "[Perched on: Chrome]";
+
+  test("wire text carries the preamble; the echo stays the bare words", async () => {
+    const { store, rpc, controller } = harness();
+    store.resetForAdopt("live-1");
+    await controller.send("hello", undefined, makePreamble);
+    expect(rpc.lastContent).toEqual([
+      {
+        type: "text",
+        text: "[Perched on: Chrome]\nguidance sentence\n\nhello",
+      },
+    ]);
+    expect(plainText(store.messages[0])).toBe("hello"); // bare echo
+  });
+
+  test("first perched send is full guidance, the second is slim (ledger burns at delivery)", async () => {
+    const { store, rpc, controller } = harness();
+    store.resetForAdopt("live-1");
+    await controller.send("first", undefined, makePreamble);
+    expect(rpc.lastContent).toEqual([
+      {
+        type: "text",
+        text: "[Perched on: Chrome]\nguidance sentence\n\nfirst",
+      },
+    ]);
+    await controller.send("second", undefined, makePreamble);
+    expect(rpc.lastContent).toEqual([
+      { type: "text", text: "[Perched on: Chrome]\n\nsecond" },
+    ]);
+  });
+
+  test("a FAILED send leaves the ledger unburned — the retry carries full guidance again", async () => {
+    const { store, rpc, controller } = harness();
+    store.resetForAdopt("live-1");
+    rpc.promptResult = () => Promise.reject(new Error("boom"));
+    await controller.send("first", undefined, makePreamble);
+    rpc.promptResult = () => Promise.resolve();
+    await controller.send("retry", undefined, makePreamble);
+    expect(rpc.lastContent).toEqual([
+      {
+        type: "text",
+        text: "[Perched on: Chrome]\nguidance sentence\n\nretry",
+      },
+    ]);
+  });
+
+  test("a bare send (no preamble) never burns the ledger", async () => {
+    const { store, rpc, controller } = harness();
+    store.resetForAdopt("live-1");
+    await controller.send("plain", undefined, null);
+    await controller.send("perched now", undefined, makePreamble);
+    expect(rpc.lastContent).toEqual([
+      {
+        type: "text",
+        text: "[Perched on: Chrome]\nguidance sentence\n\nperched now",
+      },
+    ]);
+  });
+
+  test("deferred create is ALWAYS full guidance and burns the REAL id, not the parked one", async () => {
+    const { store, rpc, controller } = harness();
+    store.resetForAdopt("parked-session");
+    // The parked session already saw guidance — must not matter.
+    markGuidanceSent("parked-session");
+    store.arm({ kind: "agent", agent });
+    await controller.send("hello", undefined, makePreamble);
+    // Full guidance rode the create's prompt despite the burned park.
+    expect(rpc.lastContent).toEqual([
+      {
+        type: "text",
+        text: "[Perched on: Chrome]\nguidance sentence\n\nhello",
+      },
+    ]);
+    // The NEW session's ledger burned at delivery: next send is slim.
+    await controller.send("again", undefined, makePreamble);
+    expect(rpc.lastContent).toEqual([
+      { type: "text", text: "[Perched on: Chrome]\n\nagain" },
+    ]);
+  });
+
+  test("create failure leaves the new session's ledger unburned", async () => {
+    const { store, rpc, controller } = harness();
+    store.arm({ kind: "agent", agent });
+    rpc.createResult = () => Promise.reject(new Error("create failed"));
+    await controller.send("hello", undefined, makePreamble);
+    rpc.createResult = () => Promise.resolve("new-session");
+    await controller.send("retry", undefined, makePreamble);
+    // The successful retry's prompt still carries FULL guidance.
+    expect(rpc.lastContent).toEqual([
+      {
+        type: "text",
+        text: "[Perched on: Chrome]\nguidance sentence\n\nretry",
+      },
+    ]);
+  });
+
+  test("images ride behind the preamble text block", async () => {
+    const { store, rpc, controller } = harness();
+    store.resetForAdopt("live-1");
+    await controller.send(
+      "look",
+      [{ type: "image", data: "abc", mimeType: "image/png" }],
+      makePreamble,
+    );
+    expect(rpc.lastContent).toEqual([
+      { type: "text", text: "[Perched on: Chrome]\nguidance sentence\n\nlook" },
+      { type: "image", data: "abc", mimeType: "image/png" },
+    ]);
+  });
+});
+
+describe("SendController stop", () => {
+  test("cancels the live session; no-op without one", async () => {
+    const { store, rpc, controller } = harness();
+    await controller.stop(); // no live session
+    expect(rpc.calls).toHaveLength(0);
+    store.resetForAdopt("live-1");
+    await controller.stop();
+    expect(rpc.calls).toEqual(["cancel:live-1"]);
+  });
+});
diff --git a/src/features/desktop-agent/lib/sendController.ts b/src/features/desktop-agent/lib/sendController.ts
new file mode 100644
index 000000000..fe5cde2d2
--- /dev/null
+++ b/src/features/desktop-agent/lib/sendController.ts
@@ -0,0 +1,365 @@
+// Send flows for the desktop agent panel: the normal prompt, the deferred
+// agent create, and the deferred fresh create. Plain class with injected
+// RPC + status-sink ports (the panelState pattern) so the flow sequencing
+// — where the epoch-guard bugs live — is fake-testable.
+//
+// In-process simplification (vs the out-of-process prototype): sessions
+// are created directly over the panel's own ACP connection with the
+// persona bound at create time (personaId + provider in _meta, system
+// prompt + model pin applied post-create). The first response STREAMS
+// LIVE like any other send — there is no external dispatch, no adopt
+// step, no export backfill, and no orphan-reuse bookkeeping (commit is
+// local-only and cannot fail separately from create).
+//
+// Epoch rule (house): epoch guards cancel the CLIENT half of a two-sided
+// transaction. Every await is followed by a store.epoch re-check before
+// any mutation. A cancel racing a create leaves the created session as a
+// harmless orphan in the session list — nothing local committed.
+//
+// Run gate: goosed rejects a second session/prompt while a
+// run is active on the session (invalid_params: "session already has
+// active run …; use _goose/unstable/session/steer"). The main app queues
+// or steers mid-stream sends; the panel's product call is DISALLOW —
+// send() bounces them BEFORE any mutation (no echo, no cleared error),
+// and `busy` exposes the gate synchronously so the composer can bounce
+// BEFORE clearing the draft. A deferred create targets a NEW session and
+// passes the gate. Steering is the graduation-era follow-up.
+//
+// Perch preamble: send() optionally takes a makePreamble closure (the
+// composer builds it from live perch identity). The preamble is
+// WIRE-ONLY — the echo stays the user's bare words — and this controller
+// is the guidance ledger's SOLE reader/marker: only it knows which
+// session a send actually targets (a deferred create's id exists only
+// after commit), and it marks AFTER confirmed delivery, never
+// optimistically — a failed send leaves the ledger unburned so the
+// retry carries full guidance again.
+
+import { formatAcpErrorMessage } from "@/shared/api/acpErrors";
+
+import { markGuidanceSent, shouldSendFullGuidanceFor } from "./sendSource";
+import type { SessionStore } from "./sessionStore";
+import type { AgentInfo, SessionActivity } from "../hooks/useSession";
+
+export interface SendRpc {
+  /** session/prompt with the full content array (text + any images).
+   *  Resolves when the turn completes (run-end signal). */
+  prompt(args: {
+    sessionId: string;
+    content: Array<Record<string, unknown>>;
+  }): Promise<void>;
+  /** Creates an agent-bound session: session/new carrying personaId +
+   *  provider meta, then system prompt + model pin. Returns the id. */
+  createAgentSession(agent: AgentInfo): Promise<string>;
+  /** Creates a plain session (the fresh "Berd" chat). */
+  createFreshSession(): Promise<string>;
+  cancel(sessionId: string): Promise<void>;
+}
+
+/** React setters, grouped. The controller never touches React directly —
+ *  the hook wires these to useState setters and its publish(). */
+export interface SendStatusSink {
+  setActivity(activity: SessionActivity): void;
+  setLastSendError(error: string | null): void;
+  setAgentSendInFlight(inFlight: boolean): void;
+  /** A deferred create committed: the hook mirrors the store's canonical
+   *  values into React state and persists the session/agent ids. Called
+   *  AFTER store.commit(). */
+  onCommitted(): void;
+  publish(): void;
+}
+
+let messageCounter = 0;
+const localMessageId = (): string => `local-${Date.now()}-${messageCounter++}`;
+
+function contentFor(
+  text: string,
+  imageBlocks: Array<Record<string, unknown>> | null,
+): Array<Record<string, unknown>> {
+  return [{ type: "text", text }, ...(imageBlocks ?? [])];
+}
+
+export class SendController {
+  // Synchronous re-entry guard: a second Enter while a create is in
+  // flight must not spawn a second session. State-based guards are
+  // async; this field closes the same-tick window.
+  private createInFlight = false;
+  // Ownership token for the gate. The gate releases at COMMIT (review
+  // 5.1), so a first send's outer finally can still be pending when a
+  // SECOND deferred create (re-arm mid-stream + send) has taken the
+  // gate — the stale finally must not stomp the new owner's true.
+  private createGeneration = 0;
+  // A run is active on the live session (a prompt is awaiting run-end).
+  // goosed rejects concurrent prompts per session — send() bounces
+  // mid-stream sends instead of erroring on the wire.
+  private promptInFlight = false;
+  // Ownership token, same pattern as createGeneration: a re-arm
+  // mid-stream starts a NEW flow whose prompt takes the gate; the
+  // ORPHANED flow's late finally must not clear the new owner's true.
+  private promptGeneration = 0;
+
+  constructor(
+    private readonly store: SessionStore,
+    private readonly rpc: SendRpc,
+    private readonly sink: SendStatusSink,
+  ) {}
+
+  /** SYNCHRONOUS live view of the send gate — true when send() would
+   *  bounce. The composer must check this BEFORE clearing the draft:
+   *  React state lags a render, and a send() bounced off the internal
+   *  guards would otherwise eat the message silently.
+   *
+   *  Mirrors send()'s own decision exactly: a create in flight gates
+   *  everything; an active run gates only sends TARGETING the live
+   *  session — an armed selection (or a panel with nothing adopted)
+   *  sends via a NEW session and passes (one-run-per-session is a
+   *  per-session rule). */
+  get busy(): boolean {
+    if (this.createInFlight) return true;
+    if (!this.promptInFlight) return false;
+    const pendingCreate =
+      this.store.pendingSelection !== null || this.store.sessionId === null;
+    return !pendingCreate;
+  }
+
+  /** Stop the in-flight run. Fire-and-forget: session/cancel resolves the
+   *  pending prompt normally with stopReason "cancelled" — the existing
+   *  run-end handling (activity reset, finishStreamingMessage) cleans up.
+   *  Failure is a quiet no-op: the run keeps streaming, which the UI
+   *  already shows honestly. */
+  async stop(): Promise<void> {
+    const target = this.store.liveSessionId;
+    if (target === null) return;
+    try {
+      await this.rpc.cancel(target);
+    } catch {
+      // Cancel is best-effort; the running state remains visibly true.
+    }
+  }
+
+  /** Resolves true when the message was DISPATCHED (echo appended, a
+   *  delivery attempt ran — even if it later failed onto lastSendError)
+   *  and false when it BOUNCED off a gate (nothing mutated, the text was
+   *  not consumed). The composer clears its draft before awaiting, so a
+   *  false return is its signal to restore the eaten text — the sync
+   *  busy check closes the same-tick window, but any composer that
+   *  awaits between its gate check and send() (the perch capture path)
+   *  needs the return value for the async gap. */
+  async send(
+    text: string,
+    imageBlocks?: Array<Record<string, unknown>>,
+    makePreamble?: ((fullGuidance: boolean) => string | null) | null,
+  ): Promise<boolean> {
+    const trimmed = text.trim();
+    if (trimmed.length === 0) return false;
+    // Re-entry guard: bounced sends mutate NOTHING — no echo, no rpc, no
+    // cleared errors (the composer gate contract).
+    if (this.createInFlight) return false;
+    const pending = this.store.pendingSelection;
+    const sessionId = this.store.sessionId;
+    // Deferred create: an armed selection, or the very first message of a
+    // panel that had nothing to adopt (implicit fresh chat).
+    const pendingCreate = pending !== null || sessionId === null;
+    // Run gate: a second prompt while a run is active on the live session
+    // would be rejected by goosed (invalid_params: "session already has
+    // active run") — bounce it BEFORE the echo, same mutate-nothing
+    // contract. A deferred create targets a NEW session and passes.
+    if (!pendingCreate && this.promptInFlight) return false;
+    this.sink.setLastSendError(null);
+    // Guidance decision: a deferred create always gets full guidance
+    // (new session, agent never saw it); otherwise the LIVE session's
+    // ledger decides. Decided here — not in the composer — because only
+    // this controller knows which session the send targets.
+    const fullGuidance = shouldSendFullGuidanceFor(pendingCreate, sessionId);
+    const preamble = makePreamble ? makePreamble(fullGuidance) : null;
+    const id = localMessageId();
+    // Optimistic echo first (house rule: composer clears before the
+    // send). The echo is the user's BARE words — the preamble is
+    // wire-only; the transcript never shows the bracket line.
+    this.store.appendLocalEcho({
+      id,
+      text: trimmed,
+      imageBlocks: imageBlocks ?? null,
+    });
+    this.sink.publish();
+
+    // Wire text carries the identity preamble; the echo above stays bare.
+    const wireText = preamble ? `${preamble}\n\n${trimmed}` : trimmed;
+    // Ledger burns only when a full-guidance preamble actually rides this
+    // send (a bare send or slim preamble must not burn it).
+    const markGuidance = preamble !== null && fullGuidance;
+
+    if (pendingCreate) {
+      this.createInFlight = true;
+      this.createGeneration += 1;
+      const generation = this.createGeneration;
+      try {
+        if (pending?.kind === "agent") {
+          await this.sendCreatingAgentSession(
+            pending.agent,
+            wireText,
+            markGuidance,
+            imageBlocks ?? null,
+          );
+        } else {
+          await this.sendCreatingFreshSession(
+            wireText,
+            markGuidance,
+            imageBlocks ?? null,
+          );
+        }
+      } finally {
+        // Safety net for the failure paths (the success path released at
+        // commit): only the CURRENT gate owner may clear — a superseded
+        // send's late finally leaves the new create's gate alone.
+        if (this.createGeneration === generation) {
+          this.createInFlight = false;
+        }
+      }
+      // Dispatched: the echo landed and a create/prompt attempt ran —
+      // failures surfaced on lastSendError, but the text was consumed.
+      return true;
+    }
+
+    this.sink.setActivity("thinking");
+    this.promptInFlight = true;
+    this.promptGeneration += 1;
+    const promptGeneration = this.promptGeneration;
+    try {
+      await this.rpc.prompt({
+        sessionId,
+        content: contentFor(wireText, imageBlocks ?? null),
+      });
+      // Guidance delivered: marked only after the prompt resolved — a
+      // failed send leaves the ledger unburned so the retry carries full
+      // guidance again.
+      if (markGuidance) markGuidanceSent(sessionId);
+    } catch (error) {
+      this.sink.setLastSendError(formatAcpErrorMessage(error));
+    } finally {
+      // Prompt future completing is a run-end signal — for THIS run. The
+      // whole cleanup is ownership-gated (generation token): if a newer
+      // run has taken the gate (re-arm mid-stream + send), the stale
+      // finally must not clear the gate, stomp activity to "none", or
+      // finish-stream the reducer the NEW run is streaming into.
+      if (this.promptGeneration === promptGeneration) {
+        this.promptInFlight = false;
+        this.sink.setActivity("none");
+        this.store.finishStreamingMessage();
+        this.sink.publish();
+      }
+    }
+    // Dispatched: the echo landed and a delivery attempt ran — failures
+    // surfaced on lastSendError, but the text was consumed.
+    return true;
+  }
+
+  /** First send under a pending agent: create the persona-bound session
+   *  on our own connection, commit, then prompt — the response streams
+   *  live. A cancel racing the create leaves an unadopted orphan
+   *  session; nothing local mutated (the epoch check gates commit). */
+  private async sendCreatingAgentSession(
+    agent: AgentInfo,
+    wireText: string,
+    markGuidance: boolean,
+    imageBlocks: Array<Record<string, unknown>> | null,
+  ): Promise<void> {
+    const s = this.store;
+    const epoch = s.epoch;
+    let promptGeneration: number | null = null;
+    this.sink.setAgentSendInFlight(true);
+    this.sink.setActivity("thinking");
+    try {
+      const newSessionId = await this.rpc.createAgentSession(agent);
+      if (s.epoch !== epoch) return; // cancelled: the orphan stays unadopted
+
+      s.commit(newSessionId, agent.agentId);
+      this.sink.onCommitted();
+      // Committed: from here the response streams live — "starting up"
+      // would be a lie, so the agent-send flag clears NOW, and the
+      // CREATE gate lifts (review 5.1: post-commit follow-ups can't
+      // double-create). The RUN gate takes over for this first streamed
+      // turn: goosed rejects a second prompt while the run
+      // is active, so Enter mid-stream bounces quietly until run-end.
+      this.createInFlight = false;
+      this.sink.setAgentSendInFlight(false);
+      this.promptInFlight = true;
+      this.promptGeneration += 1;
+      promptGeneration = this.promptGeneration;
+      await this.rpc.prompt({
+        sessionId: newSessionId,
+        content: contentFor(wireText, imageBlocks),
+      });
+      // Ledger burns with the REAL id, only after the prompt delivered.
+      if (markGuidance) markGuidanceSent(newSessionId);
+    } catch (error) {
+      // Pre-commit failures (create) and post-commit failures (prompt on
+      // the NEW session) are both send errors — same channel.
+      if (s.epoch === epoch) {
+        this.sink.setLastSendError(formatAcpErrorMessage(error));
+      }
+    } finally {
+      // The run gate clears for its owner regardless of epoch — the
+      // generation token (not the epoch) is its ownership rule.
+      if (
+        promptGeneration !== null &&
+        this.promptGeneration === promptGeneration
+      ) {
+        this.promptInFlight = false;
+      }
+      if (s.epoch === epoch) {
+        this.sink.setAgentSendInFlight(false);
+        this.sink.setActivity("none");
+        s.finishStreamingMessage();
+        this.sink.publish();
+      }
+    }
+  }
+
+  /** First send under a pending FRESH selection (the "Berd" entry), or
+   *  the implicit first chat when nothing was adoptable at attach. */
+  private async sendCreatingFreshSession(
+    wireText: string,
+    markGuidance: boolean,
+    imageBlocks: Array<Record<string, unknown>> | null,
+  ): Promise<void> {
+    const s = this.store;
+    const epoch = s.epoch;
+    let promptGeneration: number | null = null;
+    this.sink.setAgentSendInFlight(true); // composer gate covers fresh creates too
+    this.sink.setActivity("thinking");
+    try {
+      const newSessionId = await this.rpc.createFreshSession();
+      if (s.epoch !== epoch) return; // cancelled: orphan stays unadopted
+      s.commit(newSessionId, null); // fresh session: default avatar
+      this.sink.onCommitted();
+      this.createInFlight = false; // create gate lifts at commit (review 5.1)
+      this.sink.setAgentSendInFlight(false);
+      // Run gate holds through the first streamed turn.
+      this.promptInFlight = true;
+      this.promptGeneration += 1;
+      promptGeneration = this.promptGeneration;
+      await this.rpc.prompt({
+        sessionId: newSessionId,
+        content: contentFor(wireText, imageBlocks),
+      });
+      if (markGuidance) markGuidanceSent(newSessionId);
+    } catch (error) {
+      if (s.epoch === epoch) {
+        this.sink.setLastSendError(formatAcpErrorMessage(error));
+      }
+    } finally {
+      if (
+        promptGeneration !== null &&
+        this.promptGeneration === promptGeneration
+      ) {
+        this.promptInFlight = false;
+      }
+      if (s.epoch === epoch) {
+        this.sink.setAgentSendInFlight(false);
+        this.sink.setActivity("none");
+        s.finishStreamingMessage();
+        this.sink.publish();
+      }
+    }
+  }
+}
diff --git a/src/features/desktop-agent/lib/sendSource.test.ts b/src/features/desktop-agent/lib/sendSource.test.ts
new file mode 100644
index 000000000..f12f7676e
--- /dev/null
+++ b/src/features/desktop-agent/lib/sendSource.test.ts
@@ -0,0 +1,159 @@
+// Send-source priority, perch preamble shape, and guidance-ledger
+// semantics. The preamble tests pin the EXACT wire shape —
+// transcriptDisplay.stripWirePreamble parses it back out of replays, so
+// a drift here breaks display-stripping silently.
+
+import { describe, expect, test } from "vitest";
+
+import {
+  chooseComposerSendSource,
+  markGuidanceSent,
+  perchSendPreamble,
+  resetGuidanceLedger,
+  shouldSendFullGuidance,
+  shouldSendFullGuidanceFor,
+} from "./sendSource";
+import { stripWirePreamble } from "./transcriptDisplay";
+
+describe("chooseComposerSendSource", () => {
+  test("perched phase selects the perched window", () => {
+    expect(chooseComposerSendSource({ perchPhase: "perched" })).toBe(
+      "perchedWindow",
+    );
+  });
+
+  test("unperched and targeting select nothing", () => {
+    expect(chooseComposerSendSource({ perchPhase: "unperched" })).toBe("none");
+    // Mid-drag is not a perch: nothing is granted until the drop attaches.
+    expect(chooseComposerSendSource({ perchPhase: "targeting" })).toBe("none");
+  });
+});
+
+describe("perchSendPreamble", () => {
+  test("perched preamble carries app, title, and url", () => {
+    const preamble = perchSendPreamble({
+      phase: "perched",
+      appName: "Google Chrome",
+      title: "Q3 Planning - Google Docs",
+      artifactUrl: "https://docs.google.com/document/d/abc",
+    });
+    expect(preamble).toContain(
+      '[Perched on: Google Chrome — "Q3 Planning - Google Docs" — https://docs.google.com/document/d/abc]',
+    );
+    expect(preamble).toContain("prefer acting on the underlying artifact");
+    expect(preamble).not.toContain("minimized");
+  });
+
+  test("missing title and url degrade gracefully", () => {
+    const preamble = perchSendPreamble({
+      phase: "perched",
+      appName: "Terminal",
+      title: "  ",
+      artifactUrl: null,
+    });
+    expect(preamble).toContain("[Perched on: Terminal]");
+    expect(preamble).not.toContain('""');
+  });
+
+  test("unperched, targeting, or missing identity -> null", () => {
+    expect(
+      perchSendPreamble({ phase: "unperched", appName: "Safari", title: "T" }),
+    ).toBeNull();
+    expect(
+      perchSendPreamble({ phase: "targeting", appName: "Safari", title: "T" }),
+    ).toBeNull();
+    expect(
+      perchSendPreamble({ phase: "perched", appName: null, title: "T" }),
+    ).toBeNull();
+  });
+
+  test("slim preamble is bracket-only: identity yes, guidance no", () => {
+    const preamble = perchSendPreamble({
+      phase: "perched",
+      appName: "Google Chrome",
+      title: "Q3 Planning",
+      artifactUrl: "https://docs.google.com/document/d/abc",
+      fullGuidance: false,
+    });
+    expect(preamble).toBe(
+      '[Perched on: Google Chrome — "Q3 Planning" — https://docs.google.com/document/d/abc]',
+    );
+    expect(preamble).not.toContain("underlying artifact");
+  });
+
+  test("fullGuidance defaults to true", () => {
+    const preamble = perchSendPreamble({
+      phase: "perched",
+      appName: "Safari",
+      title: "Doc",
+    });
+    expect(preamble).toContain("underlying artifact");
+  });
+
+  test("round-trip: stripWirePreamble recovers the bare words from every preamble shape", () => {
+    // The two modules are a matched pair — this is the coupling test.
+    const bare = "can you validate this issue";
+    for (const args of [
+      { phase: "perched" as const, appName: "Chrome", title: "Doc" },
+      {
+        phase: "perched" as const,
+        appName: "Chrome",
+        title: "Doc",
+        artifactUrl: "https://x.test/d",
+        fullGuidance: false,
+      },
+      { phase: "perched" as const, appName: "Chrome", title: null },
+      {
+        phase: "perched" as const,
+        appName: "Chrome",
+        title: "T",
+        fullGuidance: false,
+      },
+    ]) {
+      const preamble = perchSendPreamble(args);
+      expect(preamble).not.toBeNull();
+      expect(stripWirePreamble(`${preamble}\n\n${bare}`)).toBe(bare);
+    }
+  });
+});
+
+describe("guidance ledger", () => {
+  test("first send full, subsequent slim, per session key", () => {
+    resetGuidanceLedger();
+    expect(shouldSendFullGuidance("s1")).toBe(true);
+    markGuidanceSent("s1");
+    expect(shouldSendFullGuidance("s1")).toBe(false);
+    // A different session (new chat) gets guidance again.
+    expect(shouldSendFullGuidance("s2")).toBe(true);
+  });
+
+  test("reset clears the ledger", () => {
+    resetGuidanceLedger();
+    markGuidanceSent("s1");
+    resetGuidanceLedger();
+    expect(shouldSendFullGuidance("s1")).toBe(true);
+  });
+});
+
+describe("shouldSendFullGuidanceFor", () => {
+  test("deferred create is ALWAYS full — even when the visible sessionId is burned", () => {
+    resetGuidanceLedger();
+    markGuidanceSent("parked-session");
+    // While armed, sessionId still holds the PARKED session's id. A
+    // deferred create targets a brand-new session whose agent has never
+    // seen the guidance — the parked ledger entry must not matter.
+    expect(shouldSendFullGuidanceFor(true, "parked-session")).toBe(true);
+  });
+
+  test("no pending create: the live session ledger decides", () => {
+    resetGuidanceLedger();
+    expect(shouldSendFullGuidanceFor(false, "s1")).toBe(true);
+    markGuidanceSent("s1");
+    expect(shouldSendFullGuidanceFor(false, "s1")).toBe(false);
+  });
+
+  test("null sessionId (implicit fresh create) defaults to full", () => {
+    resetGuidanceLedger();
+    expect(shouldSendFullGuidanceFor(false, null)).toBe(true);
+  });
+});
diff --git a/src/features/desktop-agent/lib/sendSource.ts b/src/features/desktop-agent/lib/sendSource.ts
new file mode 100644
index 000000000..78439976c
--- /dev/null
+++ b/src/features/desktop-agent/lib/sendSource.ts
@@ -0,0 +1,108 @@
+// Send-source priority, perch wire preamble, and the guidance ledger.
+// Pure functions — no React, no invoke (the lib-layer rule).
+//
+// WIRE TEXT NOTICE: perchSendPreamble builds AGENT-FACING English that
+// rides the ACP prompt — it is not UI copy and deliberately does NOT go
+// through i18n (the transcript strips it for display via
+// transcriptDisplay.stripWirePreamble, whose parser is coupled to this
+// exact shape — change them together).
+
+/** Where the perch lifecycle stands. Defined here (not in usePerch) so
+ *  lib modules never import from hooks/. (No "waiting" phase: minimize
+ *  auto-unperches — product rule against accidental screenshot sends.) */
+export type PerchPhase = "unperched" | "targeting" | "perched";
+
+export type ComposerSendSource = "perchedWindow" | "none";
+
+/** Send-source priority: perched window > nothing. */
+export function chooseComposerSendSource(args: {
+  perchPhase: PerchPhase;
+}): ComposerSendSource {
+  if (args.perchPhase === "perched") {
+    return "perchedWindow";
+  }
+  return "none";
+}
+
+/**
+ * Identity preamble for perched sends. Prepended ON THE WIRE ONLY: the
+ * local echo stays the user's bare words (house rule), and
+ * stripWirePreamble removes it from replays.
+ *
+ * Guidance once per session: the panel renders wire truth, so guidance
+ * repeated on every perched send gunks the transcript when the session
+ * is opened in the main app. The FIRST perched send of a session carries
+ * the full guidance; subsequent sends (fullGuidance: false) carry only
+ * the bracket identity line — the per-message facts (app, title,
+ * artifact URL, staleness warning) the agent needs each time.
+ */
+export function perchSendPreamble(args: {
+  phase: PerchPhase;
+  appName: string | null;
+  title: string | null;
+  artifactUrl?: string | null;
+  fullGuidance?: boolean;
+}): string | null {
+  const { phase, appName, title } = args;
+  if (appName === null || phase === "unperched" || phase === "targeting") {
+    return null;
+  }
+
+  const bracketParts = [`Perched on: ${appName.trim()}`];
+  const trimmedTitle = (title ?? "").trim();
+  if (trimmedTitle.length > 0) bracketParts.push(`"${trimmedTitle}"`);
+  const url = args.artifactUrl?.trim();
+  if (url) bracketParts.push(url);
+  const bracket = `[${bracketParts.join(" — ")}]`;
+
+  if (args.fullGuidance === false) {
+    return bracket;
+  }
+
+  const guidance =
+    "If a skill of yours matches this window's content, prefer acting on the underlying artifact; any attached screenshot is visual context. Do not restate this notice.";
+  return `${bracket}\n${guidance}`;
+}
+
+// Guidance ledger: which sessions have already received the full
+// guidance. Module scope on purpose — the consuming components remount
+// (ChatPopover unmounts per popover collapse), so local state would
+// re-send the guidance per open. Resets per app launch (harmless: one
+// repeat per session per launch). OWNERSHIP: SendController owns all
+// reads/marks — it is the only place that knows which session a send
+// actually targets (a deferred create's id exists only after commit).
+// Marking happens AFTER delivery, never optimistically — a failed send
+// leaves the ledger unburned so the retry carries full guidance again.
+const guidanceSent = new Set<string>();
+
+export function shouldSendFullGuidance(sessionKey: string): boolean {
+  return !guidanceSent.has(sessionKey);
+}
+
+/**
+ * Guidance decision for a send (pure — pins the armed-selection
+ * semantics): a deferred create targets a NEW session whose agent has
+ * never seen the guidance — always full, regardless of what the CURRENT
+ * sessionId's ledger says (while armed, sessionId still holds the parked
+ * session's id; keying off it was a review bug in the prototype).
+ * Otherwise the live session's ledger decides; a null sessionId
+ * (pre-attach edge) defaults to full — a repeat is harmless, a skip is
+ * not.
+ */
+export function shouldSendFullGuidanceFor(
+  pendingCreate: boolean,
+  sessionId: string | null,
+): boolean {
+  if (pendingCreate) return true;
+  if (sessionId === null) return true;
+  return shouldSendFullGuidance(sessionId);
+}
+
+export function markGuidanceSent(sessionKey: string): void {
+  guidanceSent.add(sessionKey);
+}
+
+/** Test seam. */
+export function resetGuidanceLedger(): void {
+  guidanceSent.clear();
+}
diff --git a/src/features/desktop-agent/lib/sessionStore.test.ts b/src/features/desktop-agent/lib/sessionStore.test.ts
new file mode 100644
index 000000000..194cac25a
--- /dev/null
+++ b/src/features/desktop-agent/lib/sessionStore.test.ts
@@ -0,0 +1,313 @@
+// Table tests for the session/transcript state machine (extracted from
+// useSession). Pins the seams where the prototype's admission bugs
+// lived, previously asserted only in comments:
+//
+// - admission control: armed view admits nothing;
+//   parked reducer keeps streaming; foreign sessions drop; null live
+//   admits everything (startup replay)
+// - armed-swap discards the scratch reducer but keeps the original park
+//
+// - cancel restores a transcript that kept streaming while parked
+// - epoch bumps ONLY on arm/cancelArm
+// - commit clears park + armed and rebinds the agent
+
+import { describe, expect, test } from "vitest";
+
+import { AcpUpdate, type AcpNotification } from "./acpNotification";
+import { plainText } from "./chatModels";
+import { SessionStore } from "./sessionStore";
+
+function chunk(
+  sessionId: string,
+  messageId: string,
+  text: string,
+): AcpNotification {
+  return {
+    sessionId,
+    update: new AcpUpdate({
+      sessionUpdate: "agent_message_chunk",
+      messageId,
+      content: { type: "text", text },
+    }),
+  };
+}
+
+const agentSelection = {
+  kind: "agent" as const,
+  agent: {
+    agentId: "panda",
+    name: "Panda",
+    systemPrompt: "",
+    provider: null,
+    model: null,
+  },
+};
+
+describe("SessionStore admission", () => {
+  test("null liveSessionId admits everything (startup replay)", () => {
+    const store = new SessionStore();
+    expect(store.admit(chunk("any-session", "m1", "hello"))).toBe("painted");
+    expect(store.messages).toHaveLength(1);
+  });
+
+  test("attached: live session paints, foreign sessions drop", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    expect(store.admit(chunk("live-1", "m1", "yes"))).toBe("painted");
+    expect(store.admit(chunk("other", "m2", "no"))).toBe("dropped");
+    expect(store.messages).toHaveLength(1);
+    expect(plainText(store.messages[0])).toBe("yes");
+  });
+
+  test("armed: live-session chunks park (not discarded), everything else drops", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.arm(agentSelection);
+    expect(store.messages).toHaveLength(0);
+    // Late chunk from the parked session: applied to the PARKED reducer.
+    expect(store.admit(chunk("live-1", "m1", "kept streaming"))).toBe("parked");
+    // The armed view stays empty — nothing painted.
+    expect(store.messages).toHaveLength(0);
+    // Foreign session while armed: dropped outright.
+    expect(store.admit(chunk("other", "m2", "noise"))).toBe("dropped");
+  });
+
+  test("cancel restores a transcript that kept streaming while parked", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.admit(chunk("live-1", "m1", "before arm"));
+    store.arm(agentSelection);
+    store.admit(chunk("live-1", "m1", " … and after"));
+    store.cancelArm();
+    expect(store.messages).toHaveLength(1);
+    expect(plainText(store.messages[0])).toBe("before arm … and after");
+    // Restored view paints again.
+    expect(store.admit(chunk("live-1", "m2", "live"))).toBe("painted");
+  });
+
+  test("armed with nothing parked before first attach: everything drops", () => {
+    const store = new SessionStore();
+    store.arm(agentSelection);
+    // parked exists but liveSessionId is null — no notification matches it.
+    expect(store.admit(chunk("any", "m1", "x"))).toBe("dropped");
+  });
+});
+
+describe("SessionStore arming lifecycle", () => {
+  test("arm parks the current transcript and empties the view", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.restoreAgentBinding("old-agent");
+    store.admit(chunk("live-1", "m1", "history"));
+    store.arm(agentSelection);
+    expect(store.armed).toBe(true);
+    expect(store.pendingSelection).toEqual(agentSelection);
+    expect(store.messages).toHaveLength(0);
+    // sessionId still holds the parked id while armed (the F1 shape —
+    // callers must NOT key sends off it; the store keeps it for restore).
+    expect(store.sessionId).toBe("live-1");
+    expect(store.activeAgentId).toBe("old-agent");
+  });
+
+  test("swap-while-armed keeps the original park and discards the scratch (finding 1)", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.admit(chunk("live-1", "m1", "original"));
+    store.arm(agentSelection);
+    // A failed/orphaned send left an echo in the armed scratch.
+    store.appendLocalEcho({ id: "ghost", text: "orphaned echo" });
+    expect(store.messages).toHaveLength(1);
+    // Swap to a different selection: scratch replaced, park untouched.
+    store.arm({ kind: "fresh" });
+    expect(store.messages).toHaveLength(0); // no ghost in the new chat
+    expect(store.pendingSelection).toEqual({ kind: "fresh" });
+    store.cancelArm();
+    expect(store.messages).toHaveLength(1);
+    expect(plainText(store.messages[0])).toBe("original");
+  });
+
+  test("cancel restores sessionId and agent binding verbatim", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.restoreAgentBinding("old-agent");
+    store.arm(agentSelection);
+    store.cancelArm();
+    expect(store.armed).toBe(false);
+    expect(store.pendingSelection).toBeNull();
+    expect(store.sessionId).toBe("live-1");
+    expect(store.activeAgentId).toBe("old-agent");
+  });
+
+  test("cancel with nothing parked is safe", () => {
+    const store = new SessionStore();
+    store.cancelArm();
+    expect(store.armed).toBe(false);
+    expect(store.sessionId).toBeNull();
+  });
+
+  test("epoch bumps exactly on arm/cancelArm and nowhere else", () => {
+    const store = new SessionStore();
+    expect(store.epoch).toBe(0);
+    store.resetForAdopt("live-1");
+    store.restoreAgentBinding("a");
+    store.admit(chunk("live-1", "m1", "x"));
+    store.appendLocalEcho({ id: "e1", text: "y" });
+    store.finishStreamingMessage();
+    expect(store.epoch).toBe(0);
+    store.arm(agentSelection);
+    expect(store.epoch).toBe(1);
+    store.arm({ kind: "fresh" }); // swap bumps too (every select() call)
+    expect(store.epoch).toBe(2);
+    store.cancelArm();
+    expect(store.epoch).toBe(3);
+    store.commit("s2", null);
+    expect(store.epoch).toBe(3); // commit is NOT a selection change
+  });
+});
+
+describe("SessionStore commit", () => {
+  test("commit makes the new session live, drops the park, binds the agent", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.admit(chunk("live-1", "m1", "old history"));
+    store.arm(agentSelection);
+    store.appendLocalEcho({ id: "e1", text: "first message" });
+    store.commit("new-session", "panda");
+    expect(store.armed).toBe(false);
+    expect(store.pendingSelection).toBeNull();
+    expect(store.sessionId).toBe("new-session");
+    expect(store.liveSessionId).toBe("new-session");
+    expect(store.activeAgentId).toBe("panda");
+    // The echo survives commit (the armed scratch becomes the live view).
+    expect(store.messages).toHaveLength(1);
+    // The park is history: cancel-shaped restore is impossible now.
+    store.cancelArm();
+    expect(store.sessionId).toBe("new-session");
+    // New live session paints; the old one no longer does.
+    expect(store.admit(chunk("new-session", "m2", "reply"))).toBe("painted");
+    expect(store.admit(chunk("live-1", "m3", "stale"))).toBe("dropped");
+  });
+
+  test("fresh commit clears the agent binding (default avatar)", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.restoreAgentBinding("panda");
+    store.arm({ kind: "fresh" });
+    store.commit("fresh-session", null);
+    expect(store.activeAgentId).toBeNull();
+  });
+});
+
+describe("SessionStore transcript operations", () => {
+  test("appendLocalEcho carries image blocks with valid shapes only", () => {
+    const store = new SessionStore();
+    store.appendLocalEcho({
+      id: "e1",
+      text: "look at this",
+      imageBlocks: [
+        { data: "abc123", mimeType: "image/png" },
+        { data: 42, mimeType: "image/png" }, // malformed: skipped
+      ],
+    });
+    const message = store.messages[0];
+    expect(message.content).toHaveLength(2); // text + one valid image
+    expect(message.content[1]).toEqual({
+      type: "image",
+      data: "abc123",
+      mimeType: "image/png",
+    });
+  });
+
+  test("messages returns a fresh array identity each call (publish contract)", () => {
+    const store = new SessionStore();
+    store.appendLocalEcho({ id: "e1", text: "x" });
+    expect(store.messages).not.toBe(store.messages);
+  });
+
+  test("paintedStreaming reflects the live reducer runtime", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    expect(store.paintedStreaming()).toBe(false);
+    store.admit(chunk("live-1", "m1", "streaming now"));
+    expect(store.paintedStreaming()).toBe(true);
+    store.finishStreamingMessage();
+    expect(store.paintedStreaming()).toBe(false);
+  });
+});
+
+describe("SessionStore resetForAdopt", () => {
+  test("unarmed: fresh reducer before replay — re-adopt does not duplicate chunks", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.admit(chunk("live-1", "m1", "hello"));
+    // Reconnect: re-adopt the same session; session/load replays m1.
+    // Without the fresh reducer, appendText would concatenate the
+    // replayed chunk onto the old copy ("hellohello").
+    store.resetForAdopt("live-1");
+    store.admit(chunk("live-1", "m1", "hello"));
+    expect(store.messages).toHaveLength(1);
+    expect(plainText(store.messages[0])).toBe("hello");
+  });
+
+  test("unarmed: null clears the live session (stale persisted id)", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.admit(chunk("live-1", "m1", "old"));
+    store.resetForAdopt(null);
+    expect(store.sessionId).toBeNull();
+    expect(store.liveSessionId).toBeNull();
+    expect(store.messages).toHaveLength(0);
+    // Null live id admits everything again (startup semantics).
+    expect(store.admit(chunk("any-session", "m2", "new"))).toBe("painted");
+  });
+
+  test("unarmed: a stale id (null) unlinks the agent binding too", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.restoreAgentBinding("panda");
+    store.resetForAdopt(null);
+    // No session, no binding — an agent avatar over a null session would
+    // be the wrong face until the next commit (review Check 4 LOW).
+    expect(store.sessionId).toBeNull();
+    expect(store.activeAgentId).toBeNull();
+    // A live re-adopt does NOT touch the binding (adopt restores it from
+    // persistence separately, in the hook).
+    store.restoreAgentBinding("panda");
+    store.resetForAdopt("live-2");
+    expect(store.activeAgentId).toBe("panda");
+  });
+
+  test("armed: a stale id (null) unlinks the PARK's binding — cancel cannot restore the wrong face", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.restoreAgentBinding("panda");
+    store.arm(agentSelection);
+    // Reconnect finds the persisted id stale while a selection is armed.
+    store.resetForAdopt(null);
+    store.cancelArm();
+    // The park restored: null session AND null binding (previously the
+    // pre-arm agent leaked through, arming a fresh send under an agent
+    // avatar).
+    expect(store.sessionId).toBeNull();
+    expect(store.activeAgentId).toBeNull();
+    expect(store.messages).toHaveLength(0);
+  });
+
+  test("armed: replay rebuilds the PARK, the scratch view stays empty, cancel restores it", () => {
+    const store = new SessionStore();
+    store.resetForAdopt("live-1");
+    store.admit(chunk("live-1", "m1", "pre-arm history"));
+    store.arm(agentSelection);
+    // Reconnect while armed: the park's reducer is replaced, the armed
+    // scratch view must not repaint.
+    store.resetForAdopt("live-1");
+    expect(store.admit(chunk("live-1", "m1", "replayed history"))).toBe(
+      "parked",
+    );
+    expect(store.messages).toHaveLength(0); // scratch untouched
+    store.cancelArm();
+    expect(store.sessionId).toBe("live-1");
+    expect(store.messages).toHaveLength(1);
+    expect(plainText(store.messages[0])).toBe("replayed history");
+  });
+});
diff --git a/src/features/desktop-agent/lib/sessionStore.ts b/src/features/desktop-agent/lib/sessionStore.ts
new file mode 100644
index 000000000..4dcca1815
--- /dev/null
+++ b/src/features/desktop-agent/lib/sessionStore.ts
@@ -0,0 +1,227 @@
+// Session/transcript state machine (extracted from useSession).
+//
+// Owns the armed/parked/commit lifecycle and notification admission — the
+// seam where three HIGH review bugs lived (armed-swap ghost transcript,
+// composer keying off the parked sessionId, late chunks painting into the
+// armed view). Plain class, no React, no invoke: useSession holds one
+// instance in a ref and mirrors the canonical values into React state
+// after each mutating call.
+//
+// Deferred chats: arming is PURE UI STATE — nothing is
+// created until the first send (product rule). The current transcript is
+// parked, the view goes empty, and cancelling restores the park verbatim
+// (including the agent binding, so the avatar comes back too).
+//
+// Admission control: while armed the transcript is a
+// fresh empty view — late chunks from the parked session must not paint
+// into it. They are NOT discarded: they apply to the parked
+// reducer, so cancelling restores a transcript that kept streaming while
+// parked. When not armed, only the live session's notifications paint; a
+// null liveSessionId accepts everything (startup replay arrives before
+// attach resolves).
+
+import type { AcpNotification } from "./acpNotification";
+import { emptyRuntime, type ChatMessage } from "./chatModels";
+import { ChatTranscriptReducer } from "./chatTranscriptReducer";
+import type { PendingSelection } from "../hooks/useSession";
+
+export type AdmitResult = "painted" | "parked" | "dropped";
+
+export class SessionStore {
+  private reducer = new ChatTranscriptReducer({
+    messages: [],
+    runtime: emptyRuntime(),
+  });
+  // The transcript parked when a selection was armed — restored verbatim
+  // if the selection is cancelled before the first send.
+  private parked: {
+    sessionId: string | null;
+    reducer: ChatTranscriptReducer;
+    activeAgentId: string | null;
+  } | null = null;
+  private armedInternal = false;
+  private pendingInternal: PendingSelection | null = null;
+  private sessionIdInternal: string | null = null;
+  // Which session the stream is allowed to paint. Distinct from sessionId
+  // only transiently (mid-commit); null accepts everything.
+  private liveSessionIdInternal: string | null = null;
+  private activeAgentIdInternal: string | null = null;
+  // Monotonic guard: a session switch mid-flow must orphan in-flight work
+  // (create flows capture it at entry and compare at every await). Bumped
+  // ONLY by arm()/cancelArm() — the store's selection changes.
+  private epochInternal = 0;
+
+  get sessionId(): string | null {
+    return this.sessionIdInternal;
+  }
+  get liveSessionId(): string | null {
+    return this.liveSessionIdInternal;
+  }
+  get activeAgentId(): string | null {
+    return this.activeAgentIdInternal;
+  }
+  get pendingSelection(): PendingSelection | null {
+    return this.pendingInternal;
+  }
+  get armed(): boolean {
+    return this.armedInternal;
+  }
+  get epoch(): number {
+    return this.epochInternal;
+  }
+  /** Fresh-array snapshot — the reducer mutates in place and the React
+   *  view needs a new identity (the old publish()). */
+  get messages(): ChatMessage[] {
+    return [...this.reducer.messages];
+  }
+
+  /** Adopt (or re-adopt after reconnect): fresh reducer + new live id,
+   *  BEFORE session/load streams the replay. The replay repaints the
+   *  transcript from server truth — re-loading into the old reducer
+   *  would duplicate text chunks (appendText concatenates). Passing null
+   *  clears the live session entirely (a stale persisted id: nothing to
+   *  adopt; the first send creates).
+   *
+   *  Re-adopt WHILE ARMED (reconnect racing a pending selection): the
+   *  armed scratch view must survive untouched — the replay belongs to
+   *  the parked session, so the PARK's reducer is the one replaced (the
+   *  replay rebuilds it; cancel still restores a correct transcript). */
+  resetForAdopt(sessionId: string | null): void {
+    const fresh = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+    if (this.armedInternal && this.parked !== null) {
+      this.parked = {
+        ...this.parked,
+        sessionId,
+        reducer: fresh,
+        // A stale id (null) unlinks the park's SESSION — keeping its
+        // agent binding would have cancelArm restore an agent avatar
+        // over a null session: the next send would create a FRESH chat
+        // under the wrong face until commit corrected it (review
+        // Check 4 LOW: stale-adopt-while-armed park binding).
+        activeAgentId: sessionId === null ? null : this.parked.activeAgentId,
+      };
+    } else {
+      this.reducer = fresh;
+      // Same rule unarmed: no session, no binding.
+      if (sessionId === null) this.activeAgentIdInternal = null;
+    }
+    this.sessionIdInternal = sessionId;
+    this.liveSessionIdInternal = sessionId;
+  }
+
+  /** Agent binding restored from server-side run state at attach. */
+  restoreAgentBinding(agentId: string): void {
+    this.activeAgentIdInternal = agentId;
+  }
+
+  /** Arms a deferred chat. Re-selecting while already pending swaps the
+   *  selection without stacking parks — the original session stays the
+   *  single restore point. The armed scratch reducer is ALWAYS replaced
+   * : a swap keeps the park but must discard the
+   *  scratch — a failed or orphaned send's echo in it would otherwise
+   *  reappear in the NEW chat's transcript on the next publish. */
+  arm(selection: PendingSelection): void {
+    this.epochInternal += 1;
+    if (this.parked === null) {
+      this.parked = {
+        sessionId: this.sessionIdInternal,
+        reducer: this.reducer,
+        activeAgentId: this.activeAgentIdInternal,
+      };
+    }
+    this.reducer = new ChatTranscriptReducer({
+      messages: [],
+      runtime: emptyRuntime(),
+    });
+    this.armedInternal = true; // empty armed view: admit no stream updates
+    this.pendingInternal = selection;
+  }
+
+  /** Cancels the armed selection: restores the parked transcript (and its
+   *  agent binding) verbatim. Safe when nothing is parked. */
+  cancelArm(): void {
+    this.epochInternal += 1;
+    const parked = this.parked;
+    if (parked) {
+      this.reducer = parked.reducer;
+      this.sessionIdInternal = parked.sessionId;
+      this.activeAgentIdInternal = parked.activeAgentId;
+      this.parked = null;
+    }
+    this.armedInternal = false; // stream may paint the (restored) live session
+    this.pendingInternal = null;
+  }
+
+  /** A deferred create adopted: the new session is live, the park is
+   *  history, the agent binding is server-side truth (null for fresh). */
+  commit(sessionId: string, agentId: string | null): void {
+    this.liveSessionIdInternal = sessionId;
+    this.armedInternal = false;
+    this.sessionIdInternal = sessionId;
+    this.pendingInternal = null;
+    this.activeAgentIdInternal = agentId;
+    this.parked = null;
+  }
+
+  /** Notification admission. 'painted' applied to
+   *  the visible transcript; 'parked' applied to the parked reducer while
+   *  armed; 'dropped' filtered. Only 'painted' proves connection liveness
+   *  (watchdog traffic) or warrants a publish. */
+  admit(notification: AcpNotification): AdmitResult {
+    if (this.armedInternal) {
+      const parked = this.parked;
+      if (parked && notification.sessionId === this.liveSessionIdInternal) {
+        parked.reducer.apply(notification);
+        return "parked";
+      }
+      return "dropped";
+    }
+    if (
+      this.liveSessionIdInternal !== null &&
+      notification.sessionId !== this.liveSessionIdInternal
+    ) {
+      return "dropped";
+    }
+    this.reducer.apply(notification);
+    return "painted";
+  }
+
+  /** First assistant-visible content flips thinking -> responding — the hook checks this after a painted admit. */
+  paintedStreaming(): boolean {
+    return this.reducer.runtime.streamingMessageId !== null;
+  }
+
+  /** Optimistic local echo: the user's BARE words (preamble is wire-only,
+   *  house rule), plus attached images. */
+  appendLocalEcho(args: {
+    id: string;
+    text: string;
+    imageBlocks?: Array<Record<string, unknown>> | null;
+  }): void {
+    this.reducer.appendLocalUserMessage({ id: args.id, text: args.text });
+    if (args.imageBlocks) {
+      const message = this.reducer.messages.find((m) => m.id === args.id);
+      for (const block of args.imageBlocks) {
+        if (
+          message &&
+          typeof block.data === "string" &&
+          typeof block.mimeType === "string"
+        ) {
+          message.content.push({
+            type: "image",
+            data: block.data,
+            mimeType: block.mimeType,
+          });
+        }
+      }
+    }
+  }
+
+  /** Run-end cleanup (the prompt future resolved or the flow finished). */
+  finishStreamingMessage(): void {
+    this.reducer.finishStreamingMessage();
+  }
+}
diff --git a/src/features/desktop-agent/lib/stallWatchdog.test.ts b/src/features/desktop-agent/lib/stallWatchdog.test.ts
new file mode 100644
index 000000000..d873b32ad
--- /dev/null
+++ b/src/features/desktop-agent/lib/stallWatchdog.test.ts
@@ -0,0 +1,117 @@
+// Ported from the prototype's watchdog stall cases: thinking + 25s
+// silence -> stalled; traffic re-arms; leaving thinking clears; no late
+// fires after clear.
+
+import { describe, expect, test } from "vitest";
+
+import { StallWatchdog, type StallTimerFactory } from "./stallWatchdog";
+
+/** Manual timer harness: fires only when told to. */
+class FakeTimers {
+  pending: Array<{ callback: () => void; ms: number; cancelled: boolean }> = [];
+
+  factory: StallTimerFactory = (callback, ms) => {
+    const entry = { callback, ms, cancelled: false };
+    this.pending.push(entry);
+    return () => {
+      entry.cancelled = true;
+    };
+  };
+
+  /** Fires the most recent uncancelled timer (simulating threshold elapse).
+   *  A fired one-shot is dead: mark it consumed so liveCount stays honest. */
+  fireLatest(): void {
+    const live = this.pending.filter((t) => !t.cancelled);
+    const latest = live[live.length - 1];
+    if (latest) {
+      latest.cancelled = true;
+      latest.callback();
+    }
+  }
+
+  get liveCount(): number {
+    return this.pending.filter((t) => !t.cancelled).length;
+  }
+}
+
+function harness() {
+  const timers = new FakeTimers();
+  const changes: boolean[] = [];
+  const watchdog = new StallWatchdog(
+    (stalled) => changes.push(stalled),
+    timers.factory,
+  );
+  return { timers, changes, watchdog };
+}
+
+describe("StallWatchdog", () => {
+  test("thinking + threshold silence -> stalled", () => {
+    const { timers, changes, watchdog } = harness();
+    watchdog.arm();
+    expect(watchdog.stalled).toBe(false);
+
+    timers.fireLatest();
+
+    expect(watchdog.stalled).toBe(true);
+    expect(changes).toEqual([true]);
+  });
+
+  test("traffic re-arms: old timer cancelled, new one started", () => {
+    const { timers, watchdog } = harness();
+    watchdog.arm();
+    watchdog.noteTraffic();
+
+    // The armed timer was replaced — exactly one live timer remains.
+    expect(timers.liveCount).toBe(1);
+    expect(watchdog.stalled).toBe(false);
+  });
+
+  test("stalled then traffic resumes -> clears and re-arms", () => {
+    const { timers, changes, watchdog } = harness();
+    watchdog.arm();
+    timers.fireLatest();
+    expect(watchdog.stalled).toBe(true);
+
+    watchdog.noteTraffic();
+
+    expect(watchdog.stalled).toBe(false);
+    expect(changes).toEqual([true, false]);
+    expect(timers.liveCount).toBe(1); // re-armed
+  });
+
+  test("leaving thinking clears without firing", () => {
+    const { timers, changes, watchdog } = harness();
+    watchdog.arm();
+    watchdog.clear();
+
+    expect(timers.liveCount).toBe(0);
+    expect(watchdog.stalled).toBe(false);
+    expect(changes).toEqual([]); // never became stalled, no spurious change
+  });
+
+  test("clear cancels the armed timer (the no-late-fire guarantee)", () => {
+    // The no-late-fire property rests on clear() actually cancelling the
+    // host timer — a real clearTimeout never fires a cancelled callback.
+    // Assert the cancellation itself: this test FAILS if clear() stops
+    // invoking the cancel handle (unlike its tautological predecessor,
+    // which couldn't fail — review nit).
+    const { timers, changes, watchdog } = harness();
+    watchdog.arm();
+    expect(timers.liveCount).toBe(1);
+
+    watchdog.clear();
+
+    expect(timers.pending[0].cancelled).toBe(true);
+    expect(timers.liveCount).toBe(0);
+    expect(watchdog.stalled).toBe(false);
+    expect(changes).toEqual([]);
+  });
+
+  test("traffic while idle is a no-op (clear watchdog stays clear)", () => {
+    const { timers, changes, watchdog } = harness();
+    watchdog.noteTraffic();
+
+    expect(timers.liveCount).toBe(0);
+    expect(changes).toEqual([]);
+  });
+});
diff --git a/src/features/desktop-agent/lib/stallWatchdog.ts b/src/features/desktop-agent/lib/stallWatchdog.ts
new file mode 100644
index 000000000..048e15665
--- /dev/null
+++ b/src/features/desktop-agent/lib/stallWatchdog.ts
@@ -0,0 +1,71 @@
+// Stuck-send watchdog — ported from the prototype's semantics
+// (the desktop agentSessionManager.sendStalled):
+//
+// - Armed (timer started, 25s) when activity enters `thinking`.
+// - Re-armed on EACH incoming session notification — traffic proves
+//   liveness and resets the clock.
+// - Cleared (timer cancelled, flag false) when activity leaves `thinking`.
+// - The send is never aborted; this only surfaces a hint.
+//
+// Pure class with an injectable timer factory so the semantics test without real time.
+
+export type StallTimerFactory = (
+  callback: () => void,
+  ms: number,
+) => () => void;
+
+const defaultTimerFactory: StallTimerFactory = (callback, ms) => {
+  const handle = setTimeout(callback, ms);
+  return () => clearTimeout(handle);
+};
+
+export const STALL_THRESHOLD_MS = 25_000;
+
+export class StallWatchdog {
+  private cancel: (() => void) | null = null;
+  private stalledInternal = false;
+
+  constructor(
+    private readonly onChange: (stalled: boolean) => void,
+    private readonly timerFactory: StallTimerFactory = defaultTimerFactory,
+    private readonly thresholdMs: number = STALL_THRESHOLD_MS,
+  ) {}
+
+  get stalled(): boolean {
+    return this.stalledInternal;
+  }
+
+  /** Activity entered `thinking`: arm. */
+  arm(): void {
+    this.restartTimer();
+  }
+
+  /** A session notification arrived: liveness proven, re-arm. Only
+   *  meaningful while armed — a clear watchdog stays clear. */
+  noteTraffic(): void {
+    if (this.cancel === null && !this.stalledInternal) return;
+    this.setStalled(false);
+    this.restartTimer();
+  }
+
+  /** Activity left `thinking` (responding or none), or detach/dispose. */
+  clear(): void {
+    this.cancel?.();
+    this.cancel = null;
+    this.setStalled(false);
+  }
+
+  private restartTimer(): void {
+    this.cancel?.();
+    this.cancel = this.timerFactory(() => {
+      this.cancel = null;
+      this.setStalled(true);
+    }, this.thresholdMs);
+  }
+
+  private setStalled(next: boolean): void {
+    if (this.stalledInternal === next) return;
+    this.stalledInternal = next;
+    this.onChange(next);
+  }
+}
diff --git a/src/features/desktop-agent/lib/tauriWindowPort.ts b/src/features/desktop-agent/lib/tauriWindowPort.ts
new file mode 100644
index 000000000..dd4202d36
--- /dev/null
+++ b/src/features/desktop-agent/lib/tauriWindowPort.ts
@@ -0,0 +1,86 @@
+// Production WindowPort/PositionStore implementations. Thin by design:
+// all decision logic lives in panelState.ts (tested), all coordinate
+// flips live in Rust's desktop_agent::coordinate_space (sole authority).
+
+import { invoke } from "@tauri-apps/api/core";
+
+import type { Rect, ScreenInfo } from "./anchorGeometry";
+import type { PositionStore, WindowPort } from "./panelState";
+
+interface RectDto {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+interface ScreenDto {
+  frame: RectDto;
+  visibleFrame: RectDto;
+  isMain: boolean;
+}
+
+export class TauriWindowPort implements WindowPort {
+  async getScreens(): Promise<ScreenInfo[]> {
+    const screens = await invoke<ScreenDto[]>("desktop_agent_get_screens");
+    return screens.map((s) => ({
+      frame: s.frame,
+      visibleFrame: s.visibleFrame,
+      isMain: s.isMain,
+    }));
+  }
+
+  async getPanelFrame(): Promise<Rect> {
+    return invoke<RectDto>("desktop_agent_get_panel_frame");
+  }
+
+  async setState(args: { expanded: boolean; frame: Rect }): Promise<void> {
+    await invoke("desktop_agent_set_state", {
+      expanded: args.expanded,
+      frame: args.frame,
+    });
+  }
+
+  async startDrag(): Promise<void> {
+    await invoke("desktop_agent_start_drag");
+  }
+}
+
+/** Panel position persistence in webview localStorage (fresh state — the
+ *  panel owns it; the window-state plugin denylists this window). */
+export const PANEL_POSITION_STORAGE_KEY = "goose:desktop-agent:panel-position";
+
+export class LocalStoragePositionStore implements PositionStore {
+  async load(): Promise<{ x: number; y: number } | null> {
+    try {
+      const raw = localStorage.getItem(PANEL_POSITION_STORAGE_KEY);
+      if (!raw) return null;
+      const parsed: unknown = JSON.parse(raw);
+      if (
+        typeof parsed === "object" &&
+        parsed !== null &&
+        typeof (parsed as { x?: unknown }).x === "number" &&
+        typeof (parsed as { y?: unknown }).y === "number"
+      ) {
+        return {
+          x: (parsed as { x: number }).x,
+          y: (parsed as { y: number }).y,
+        };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  async save(position: { x: number; y: number }): Promise<void> {
+    try {
+      localStorage.setItem(
+        PANEL_POSITION_STORAGE_KEY,
+        JSON.stringify(position),
+      );
+    } catch {
+      // Persistence is best-effort; the panel still works this session.
+    }
+  }
+}
diff --git a/src/features/desktop-agent/lib/transcriptDisplay.test.ts b/src/features/desktop-agent/lib/transcriptDisplay.test.ts
new file mode 100644
index 000000000..c34e6824c
--- /dev/null
+++ b/src/features/desktop-agent/lib/transcriptDisplay.test.ts
@@ -0,0 +1,178 @@
+import { describe, expect, test } from "vitest";
+
+import type { ChatMessage } from "./chatModels";
+import {
+  groupTranscript,
+  stripWirePreamble,
+  toolDisplayName,
+  toolGlyph,
+  toolResultText,
+} from "./transcriptDisplay";
+
+const msg = (
+  id: string,
+  content: ChatMessage["content"],
+  role: "user" | "assistant" = "assistant",
+): ChatMessage => ({
+  id,
+  role,
+  content,
+  isStreaming: false,
+  createdAt: 0,
+});
+
+const tool = (id: string, name: string, status: string) => ({
+  type: "tool" as const,
+  tool: { id, name, status },
+});
+
+describe("groupTranscript", () => {
+  test("consecutive tool-only messages collapse into one toolRun", () => {
+    const items = groupTranscript([
+      msg("u1", [{ type: "text", text: "do the thing" }], "user"),
+      msg("a1", [tool("t1", "shell", "completed")]),
+      msg("a2", [tool("t2", "shell", "completed")]),
+      msg("a3", [tool("t3", "shell", "failed")]),
+      msg("a4", [{ type: "text", text: "done!" }]),
+    ]);
+    expect(items.map((i) => i.kind)).toEqual(["message", "toolRun", "message"]);
+    const run = items[1];
+    expect(run.kind === "toolRun" && run.tools.map((t) => t.id)).toEqual([
+      "t1",
+      "t2",
+      "t3",
+    ]);
+  });
+
+  test("mixed content (text + tool) renders as a normal message, breaking the run", () => {
+    const items = groupTranscript([
+      msg("a1", [tool("t1", "shell", "completed")]),
+      msg("a2", [
+        { type: "text", text: "thinking…" },
+        tool("t2", "shell", "completed"),
+      ]),
+      msg("a3", [tool("t3", "shell", "completed")]),
+    ]);
+    expect(items.map((i) => i.kind)).toEqual(["toolRun", "message", "toolRun"]);
+  });
+
+  test("empty content (streaming placeholder) is a message, not a run", () => {
+    const items = groupTranscript([msg("a1", [])]);
+    expect(items[0].kind).toBe("message");
+  });
+
+  test("multiple tools inside one message join the run", () => {
+    const items = groupTranscript([
+      msg("a1", [
+        tool("t1", "shell", "completed"),
+        tool("t2", "shell", "completed"),
+      ]),
+      msg("a2", [tool("t3", "shell", "completed")]),
+    ]);
+    expect(items).toHaveLength(1);
+    const run = items[0];
+    expect(run.kind === "toolRun" && run.tools).toHaveLength(3);
+  });
+
+  test("replay request/response pair with the same id merges into one tool row", () => {
+    const items = groupTranscript([
+      msg("a1", [tool("call-1", "shell", "in_progress")]),
+      msg("a2", [
+        {
+          type: "tool",
+          tool: {
+            id: "call-1",
+            name: "Tool result",
+            status: "failed",
+            result: "boom",
+          },
+        },
+      ]),
+    ]);
+    expect(items).toHaveLength(1);
+    const run = items[0];
+    expect(run.kind === "toolRun" && run.tools).toHaveLength(1);
+    expect(run.kind === "toolRun" && run.tools[0]).toMatchObject({
+      id: "call-1",
+      name: "shell",
+      status: "failed",
+      result: "boom",
+    });
+  });
+
+  test("run key is stable across regroups (first message id)", () => {
+    const messages = [
+      msg("a7", [tool("t1", "shell", "completed")]),
+      msg("a8", [tool("t2", "shell", "in_progress")]),
+    ];
+    const a = groupTranscript(messages);
+    const b = groupTranscript(messages);
+    expect(a[0].kind === "toolRun" && a[0].key).toBe("tools-a7");
+    expect(b[0].kind === "toolRun" && b[0].key).toBe("tools-a7");
+  });
+});
+
+describe("tool display helpers", () => {
+  test("status glyphs", () => {
+    expect(toolGlyph("completed")).toBe("✓");
+    expect(toolGlyph("failed")).toBe("✗");
+    expect(toolGlyph("in_progress")).toBe("⋯");
+  });
+
+  test("result text trims empty output but preserves useful logs", () => {
+    expect(
+      toolResultText({ id: "t1", name: "shell", status: "failed" }),
+    ).toBeNull();
+    expect(
+      toolResultText({
+        id: "t1",
+        name: "shell",
+        status: "failed",
+        result: "  boom\n",
+      }),
+    ).toBe("boom");
+  });
+
+  test("display name normalizes whitespace and falls back to Tool", () => {
+    expect(
+      toolDisplayName({
+        id: "t1",
+        name: " shell   command ",
+        status: "completed",
+      }),
+    ).toBe("shell command");
+    expect(
+      toolDisplayName({ id: "t1", name: "   ", status: "completed" }),
+    ).toBe("Tool");
+  });
+});
+
+describe("stripWirePreamble", () => {
+  test("strips the bracket line from a replayed perched send", () => {
+    expect(
+      stripWirePreamble(
+        '[Perched on: Chrome — "TICKET-123"]\n\ncan you validate this issue',
+      ),
+    ).toBe("can you validate this issue");
+  });
+
+  test("strips the full-guidance preamble (bracket + guidance sentence)", () => {
+    expect(
+      stripWirePreamble(
+        '[Perched on: Chrome — "Doc"]\nIf a skill of yours matches this window\u2019s content, prefer acting on the underlying artifact; any attached screenshot is visual context. Do not restate this notice.\n\nreal question here',
+      ),
+    ).toBe("real question here");
+  });
+
+  test("user text that merely mentions perching passes through", () => {
+    expect(stripWirePreamble("I was perched on a chair")).toBe(
+      "I was perched on a chair",
+    );
+  });
+
+  test("preamble-shaped text without the blank-line gap passes through", () => {
+    expect(stripWirePreamble("[Perched on: Chrome] no gap here")).toBe(
+      "[Perched on: Chrome] no gap here",
+    );
+  });
+});
diff --git a/src/features/desktop-agent/lib/transcriptDisplay.ts b/src/features/desktop-agent/lib/transcriptDisplay.ts
new file mode 100644
index 000000000..22db03c50
--- /dev/null
+++ b/src/features/desktop-agent/lib/transcriptDisplay.ts
@@ -0,0 +1,97 @@
+// Transcript display shaping (the "wall of ⚙ rows" polish):
+// pure functions between the reducer's messages and the JSX.
+//
+// Why: goosed emits each tool call as its own assistant message, so a
+// replayed agent session (session resume replays EVERYTHING) renders as
+// dozens of consecutive `⚙ shell · cd … — completed` rows drowning the
+// conversation. Grouping is display-only — the reducer's message list
+// stays wire truth.
+
+import type { ChatMessage, ToolActivity } from "./chatModels";
+
+export type TranscriptItem =
+  | { kind: "message"; message: ChatMessage }
+  | { kind: "toolRun"; key: string; tools: ToolActivity[] };
+
+/** Groups consecutive tool-only messages into a single toolRun item.
+ *  A message with any non-tool content (text, image) breaks the run and
+ *  renders as a normal message row. */
+export function groupTranscript(messages: ChatMessage[]): TranscriptItem[] {
+  const items: TranscriptItem[] = [];
+  for (const message of messages) {
+    const toolOnly =
+      message.content.length > 0 &&
+      message.content.every((c) => c.type === "tool");
+    if (!toolOnly) {
+      items.push({ kind: "message", message });
+      continue;
+    }
+    const tools = message.content.flatMap((c) =>
+      c.type === "tool" ? [c.tool] : [],
+    );
+    const last = items[items.length - 1];
+    if (last && last.kind === "toolRun") {
+      mergeTools(last.tools, tools);
+    } else {
+      items.push({
+        kind: "toolRun",
+        key: `tools-${message.id}`,
+        tools: [...tools],
+      });
+    }
+  }
+  return items;
+}
+
+function mergeTools(target: ToolActivity[], incoming: ToolActivity[]): void {
+  for (const next of incoming) {
+    const index = target.findIndex((tool) => tool.id === next.id);
+    if (index === -1) {
+      target.push(next);
+      continue;
+    }
+    const previous = target[index];
+    target[index] = {
+      ...previous,
+      ...next,
+      // Replay often has toolRequest(name) followed by toolResponse(result)
+      // with the SAME id but no name. Preserve the real request name.
+      name: next.name === "Tool result" ? previous.name : next.name,
+      result: next.result ?? previous.result,
+    };
+  }
+}
+
+export function isSettled(tool: ToolActivity): boolean {
+  return tool.status === "completed" || tool.status === "failed";
+}
+
+export function toolGlyph(status: ToolActivity["status"]): string {
+  if (status === "completed") return "✓";
+  if (status === "failed") return "✗";
+  return "⋯";
+}
+
+export function toolResultText(tool: ToolActivity): string | null {
+  const result = tool.result?.trim();
+  return result && result.length > 0 ? result : null;
+}
+
+export function toolDisplayName(tool: ToolActivity): string {
+  return tool.name.replace(/\s+/g, " ").trim() || "Tool";
+}
+
+/** Display-strips the perch wire preamble from a replayed user message.
+ *
+ *  Live sends echo the user's BARE words — the preamble is
+ *  wire-only. But session resume replays wire truth, so the bracket line
+ *  (and the guidance sentence on first sends) reappears in the user
+ *  bubble. WE authored that text, so stripping it for display is honest —
+ *  the user's own words are never touched: anything that doesn't match
+ *  the exact preamble shape passes through verbatim. */
+export function stripWirePreamble(text: string): string {
+  if (!text.startsWith("[Perched on: ")) return text;
+  const gap = text.indexOf("\n\n");
+  if (gap === -1) return text; // preamble-only or unexpected shape: show as-is
+  return text.slice(gap + 2);
+}
diff --git a/src/features/desktop-agent/ui/AgentAvatar.test.tsx b/src/features/desktop-agent/ui/AgentAvatar.test.tsx
new file mode 100644
index 000000000..1bd4376cb
--- /dev/null
+++ b/src/features/desktop-agent/ui/AgentAvatar.test.tsx
@@ -0,0 +1,62 @@
+import { act, render } from "@testing-library/react";
+import { expect, it, vi } from "vitest";
+
+import { DEFAULT_AVATAR } from "@/features/desktop-agent/lib/avatarState";
+import { AgentAvatar } from "@/features/desktop-agent/ui/AgentAvatar";
+
+const callbacks = vi.hoisted(() => ({ chip: () => {}, berdy: () => {} }));
+vi.mock("@/features/desktop-agent/ui/AvatarView", () => ({
+  AvatarView: ({ onReady }: { onReady: () => void }) => {
+    callbacks.chip = onReady;
+    return <span data-testid="chip" />;
+  },
+}));
+vi.mock("@/features/desktop-agent/ui/BerdyView", () => ({
+  BerdyView: ({ onReady }: { onReady: () => void }) => {
+    callbacks.berdy = onReady;
+    return <span data-testid="berdy" />;
+  },
+}));
+it("retains outgoing renderer until incoming pixels and cancels superseded switches", () => {
+  const view = (character: boolean) => (
+    <AgentAvatar
+      character={character}
+      choice={DEFAULT_AVATAR}
+      state="idle"
+      target="idle"
+      hidden={false}
+    />
+  );
+  const { rerender, queryByTestId, getByTestId } = render(view(false));
+  rerender(view(true));
+  expect(getByTestId("chip").parentElement).toHaveStyle({ opacity: "1" });
+  expect(getByTestId("berdy").parentElement).toHaveStyle({ opacity: "0" });
+  rerender(view(false));
+  expect(queryByTestId("berdy")).toBeNull();
+  rerender(view(true));
+  act(() => callbacks.berdy());
+  expect(queryByTestId("chip")).toBeNull();
+  rerender(view(false));
+  expect(getByTestId("berdy").parentElement).toHaveStyle({ opacity: "1" });
+  act(() => callbacks.chip());
+  expect(queryByTestId("berdy")).toBeNull();
+});
+
+it("initial character enablement presents the fallback chip until real character pixels", () => {
+  const { getByTestId, queryByTestId } = render(
+    <AgentAvatar
+      character
+      choice={DEFAULT_AVATAR}
+      state="idle"
+      target="idle"
+      hidden={false}
+    />,
+  );
+  expect(getByTestId("chip").parentElement).toHaveStyle({ opacity: "1" });
+  expect(getByTestId("berdy").parentElement).toHaveStyle({ opacity: "0" });
+  act(() => callbacks.chip());
+  expect(getByTestId("chip").parentElement).toHaveStyle({ opacity: "1" });
+  act(() => callbacks.berdy());
+  expect(queryByTestId("chip")).toBeNull();
+  expect(getByTestId("berdy").parentElement).toHaveStyle({ opacity: "1" });
+});
diff --git a/src/features/desktop-agent/ui/AgentAvatar.tsx b/src/features/desktop-agent/ui/AgentAvatar.tsx
new file mode 100644
index 000000000..9ad22f9ea
--- /dev/null
+++ b/src/features/desktop-agent/ui/AgentAvatar.tsx
@@ -0,0 +1,68 @@
+import { useState } from "react";
+
+import type {
+  AvatarChoice,
+  AvatarState,
+} from "@/features/desktop-agent/lib/avatarState";
+import type { BerdyPose } from "@/features/desktop-agent/lib/berdyClips";
+import { AvatarView } from "@/features/desktop-agent/ui/AvatarView";
+import { BerdyView } from "@/features/desktop-agent/ui/BerdyView";
+
+/** Keep the outgoing renderer until the incoming one has real pixels. */
+export function AgentAvatar({
+  character,
+  choice,
+  state,
+  target,
+  hidden,
+}: {
+  character: boolean;
+  choice: AvatarChoice;
+  state: AvatarState;
+  target: BerdyPose;
+  hidden: boolean;
+}) {
+  // Even an initially enabled character must warm before replacing the chip.
+  const [presented, setPresented] = useState(false);
+  const switching = presented !== character;
+  return (
+    <div style={{ position: "relative", width: 92, height: 92 }}>
+      {(!presented || !character) && (
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            opacity: presented ? 0 : 1,
+          }}
+        >
+          <AvatarView
+            choice={choice}
+            state={state}
+            size={92}
+            onReady={() => {
+              if (switching && !character) setPresented(false);
+            }}
+          />
+        </div>
+      )}
+      {(presented || character) && (
+        <div
+          style={{ position: "absolute", inset: 0, opacity: presented ? 1 : 0 }}
+        >
+          <BerdyView
+            target={target}
+            errored={state === "error"}
+            hidden={hidden}
+            size={92}
+            onReady={() => {
+              if (switching && character) setPresented(true);
+            }}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/features/desktop-agent/ui/AvatarMenu.test.tsx b/src/features/desktop-agent/ui/AvatarMenu.test.tsx
new file mode 100644
index 000000000..5d784a8b7
--- /dev/null
+++ b/src/features/desktop-agent/ui/AvatarMenu.test.tsx
@@ -0,0 +1,179 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  computeAvatarMenuPlacement,
+  MENU_WIDTH,
+  SUBMENU_GAP,
+  SUBMENU_WIDTH,
+  AvatarMenu,
+} from "./AvatarMenu";
+import type { ExpandedLayout } from "../lib/anchorGeometry";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) =>
+      ({
+        "menu.newChat": "Start new chat",
+        "menu.switchAgent": "Switch agent",
+        "menu.settings": "Settings",
+        "menu.turnOff": "Turn off agent",
+        "menu.fresh": "Berd",
+        "menu.empty": "No agents yet",
+      })[key] ?? key,
+  }),
+}));
+vi.mock("../hooks/useAgentAvatar", () => ({
+  useAgentAvatar: () => ({
+    choice: { kind: "image", src: "agent.png", label: "Agent" },
+  }),
+}));
+vi.mock("./AvatarView", () => ({
+  AvatarView: () => <span data-testid="preview" />,
+}));
+vi.mock("../lib/berdyClips", () => ({
+  BERDY_CLIPS: { idle1: { file: "idle.mp4" } },
+}));
+
+const layout: ExpandedLayout = {
+  windowFrame: { x: 100, y: 100, width: 600, height: 300 },
+  avatarRect: { x: 0, y: 100, width: 94, height: 94 },
+  popoverRect: { x: 94, y: 0, width: 438, height: 124 },
+  popoverAbove: false,
+  popoverSide: null,
+};
+
+function renderMenu(overrides?: Partial<Parameters<typeof AvatarMenu>[0]>) {
+  const props = {
+    layout,
+    agentSelector: true,
+    model: {
+      agents: [
+        {
+          agentId: "a1",
+          name: "Scout",
+          systemPrompt: "",
+          provider: null,
+          model: null,
+        },
+      ],
+      checkedAgentId: null,
+      checkedFresh: true,
+    },
+    onNewChat: vi.fn(),
+    onSelectAgent: vi.fn(),
+    onSelectFresh: vi.fn(),
+    onSettings: vi.fn(),
+    onTurnOff: vi.fn(),
+    ...overrides,
+  };
+  render(<AvatarMenu {...props} />);
+  return props;
+}
+
+describe("AvatarMenu keyboard and activation", () => {
+  it("navigates root rows and activates with Enter/Escape untouched", () => {
+    const props = renderMenu();
+    fireEvent.keyDown(window, { key: "ArrowDown" });
+    fireEvent.keyDown(window, { key: "ArrowDown" });
+    fireEvent.keyDown(window, { key: "Enter" });
+    expect(props.onSettings).toHaveBeenCalledOnce();
+    fireEvent.keyDown(window, { key: "ArrowDown" });
+    fireEvent.keyDown(window, { key: "Enter" });
+    expect(props.onTurnOff).toHaveBeenCalledOnce();
+  });
+
+  it("opens, navigates, activates, and closes the submenu with arrows", () => {
+    const props = renderMenu();
+    fireEvent.keyDown(window, { key: "ArrowDown" });
+    fireEvent.keyDown(window, { key: "ArrowRight" });
+    expect(screen.getByText("Berd")).toBeInTheDocument();
+    fireEvent.keyDown(window, { key: "ArrowDown" });
+    fireEvent.keyDown(window, { key: "Enter" });
+    expect(props.onSelectAgent).toHaveBeenCalledWith(props.model.agents[0]);
+
+    fireEvent.keyDown(window, { key: "ArrowLeft" });
+    expect(screen.queryByText("Scout")).not.toBeInTheDocument();
+    expect(screen.getByText("Switch agent").closest("button")).toHaveFocus();
+  });
+
+  it("renders Start new chat first and activates it by keyboard", () => {
+    const props = renderMenu();
+    const rows = screen.getAllByRole("menuitem");
+    expect(rows[0]).toHaveTextContent("Start new chat");
+    fireEvent.keyDown(window, { key: "Enter" });
+    expect(props.onNewChat).toHaveBeenCalledOnce();
+  });
+
+  it("supports hover + click submenu activation", () => {
+    const props = renderMenu();
+    fireEvent.pointerEnter(screen.getByText("Switch agent"));
+    fireEvent.click(screen.getByText("Scout"));
+    expect(props.onSelectAgent).toHaveBeenCalledWith(props.model.agents[0]);
+  });
+
+  it("renders checkmark fallback, zero-agents row, and selector-off rows", () => {
+    const { rerender } = render(
+      <AvatarMenu
+        layout={layout}
+        agentSelector={true}
+        model={{ agents: [], checkedAgentId: null, checkedFresh: true }}
+        onNewChat={vi.fn()}
+        onSelectAgent={vi.fn()}
+        onSelectFresh={vi.fn()}
+        onSettings={vi.fn()}
+        onTurnOff={vi.fn()}
+      />,
+    );
+    fireEvent.pointerEnter(screen.getByText("Switch agent"));
+    expect(screen.getByText("No agents yet")).toBeInTheDocument();
+    expect(screen.getByText("✓")).toBeInTheDocument();
+
+    rerender(
+      <AvatarMenu
+        layout={layout}
+        agentSelector={false}
+        model={{ agents: [], checkedAgentId: null, checkedFresh: false }}
+        onNewChat={vi.fn()}
+        onSelectAgent={vi.fn()}
+        onSelectFresh={vi.fn()}
+        onSettings={vi.fn()}
+        onTurnOff={vi.fn()}
+      />,
+    );
+    expect(screen.queryByText("Switch agent")).not.toBeInTheDocument();
+    expect(screen.getAllByRole("menuitem")[0]).toHaveTextContent(
+      "Start new chat",
+    );
+    expect(screen.getByText("Settings")).toBeInTheDocument();
+    expect(screen.getByText("Turn off agent")).toBeInTheDocument();
+  });
+});
+
+describe("AvatarMenu placement", () => {
+  it.each([
+    ["centre", MENU_WIDTH / 2, "right"],
+    ["left screen edge", 0, "right"],
+    ["right screen edge", MENU_WIDTH + SUBMENU_GAP + SUBMENU_WIDTH, "left"],
+  ] as const)("keeps root/submenu non-overlapping and on-screen at %s", (_name, avatarCenterX, side) => {
+    const placement = computeAvatarMenuPlacement({
+      agentSelector: true,
+      agentCount: 3,
+      avatarCenterX,
+    });
+    const root = placement.root;
+    const sub = placement.submenu;
+    expect(root.x).toBeGreaterThanOrEqual(0);
+    expect(sub.x).toBeGreaterThanOrEqual(0);
+    expect(root.x + root.width).toBeLessThanOrEqual(placement.regionSize.width);
+    expect(sub.x + sub.width).toBeLessThanOrEqual(placement.regionSize.width);
+    expect(root.x + root.width <= sub.x || sub.x + sub.width <= root.x).toBe(
+      true,
+    );
+    expect(sub.width).toBe(SUBMENU_WIDTH);
+    expect(placement.regionSize.width).toBe(
+      MENU_WIDTH + SUBMENU_GAP + SUBMENU_WIDTH,
+    );
+    expect(placement.submenuSide).toBe(side);
+  });
+});
diff --git a/src/features/desktop-agent/ui/AvatarMenu.tsx b/src/features/desktop-agent/ui/AvatarMenu.tsx
new file mode 100644
index 000000000..5455143e7
--- /dev/null
+++ b/src/features/desktop-agent/ui/AvatarMenu.tsx
@@ -0,0 +1,516 @@
+// Custom webview context menu for the avatar — replaces the native
+// NSMenu so rows can carry avatar previews and the chrome can match the
+// popover's dark glass. The collapsed panel window is avatar-sized, so
+// DesktopAgentApp grows the window first ("menu" panel mode, same
+// anti-blink path as the chat popover) and renders this component inside
+// the computed overlay region; this component only positions the menu
+// card (and the "Switch agent" submenu) WITHIN that region.
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+
+import type { ExpandedLayout, Size } from "../lib/anchorGeometry";
+import { deriveAvatarState } from "../lib/avatarState";
+import { BERDY_CLIPS } from "../lib/berdyClips";
+import { useAgentAvatar } from "../hooks/useAgentAvatar";
+import type { AvatarMenuModel } from "../hooks/useAvatarMenu";
+import type { AgentInfo } from "../hooks/useSession";
+import { AvatarView } from "./AvatarView";
+
+export const MENU_WIDTH = 190;
+export const SUBMENU_WIDTH = 240;
+const ROW_HEIGHT = 28;
+const MENU_PADDING = 6;
+const SEPARATOR_HEIGHT = 9; // 1px rule + margins
+export const SUBMENU_GAP = 8;
+const PREVIEW_SIZE = 18;
+const SUBMENU_MAX_ROWS = 8;
+const SUBMENU_CLOSE_DELAY_MS = 150;
+const MENU_BORDER_WIDTH = 1;
+
+export interface AvatarMenuPlacement {
+  regionSize: Size;
+  root: { x: number; y: number; width: number; height: number };
+  submenu: { x: number; y: number; width: number; height: number };
+  submenuMaxHeight: number;
+  submenuSide: "left" | "right";
+}
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(Math.max(value, min), Math.max(min, max));
+
+function rootHeight(agentSelector: boolean): number {
+  const rows = agentSelector ? 4 : 3;
+  return (
+    MENU_PADDING * 2 +
+    rows * ROW_HEIGHT +
+    (agentSelector ? SEPARATOR_HEIGHT : 0) +
+    MENU_BORDER_WIDTH * 2
+  );
+}
+
+function submenuNaturalHeight(agentCount: number): number {
+  return (
+    MENU_PADDING * 2 +
+    (1 + Math.max(agentCount, 1)) * ROW_HEIGHT +
+    MENU_BORDER_WIDTH * 2
+  );
+}
+
+/**
+ * Single source of truth for the menu overlay geometry. The native window
+ * must be sized before render, so this pure function is shared by
+ * menuOverlaySize() and AvatarMenu. The region is wide enough for root +
+ * submenu, but the root hugs the avatar edge while the submenu opens away
+ * from the avatar/toward available screen space.
+ */
+export function computeAvatarMenuPlacement(args: {
+  agentSelector: boolean;
+  agentCount: number;
+  visibleHeight?: number;
+  openSubmenu?: boolean;
+  regionWidth?: number;
+  regionHeight?: number;
+  avatarCenterX?: number;
+  popoverAbove?: boolean;
+}): AvatarMenuPlacement {
+  const mainHeight = rootHeight(args.agentSelector);
+  const rawSubHeight = submenuNaturalHeight(args.agentCount);
+  const maxScrollableSubHeight =
+    MENU_PADDING * 2 + SUBMENU_MAX_ROWS * ROW_HEIGHT + MENU_BORDER_WIDTH * 2;
+  const visibleHeight = args.visibleHeight ?? Number.POSITIVE_INFINITY;
+  const submenuMaxHeight = Math.max(
+    MENU_PADDING * 2 + ROW_HEIGHT + MENU_BORDER_WIDTH * 2,
+    Math.min(rawSubHeight, maxScrollableSubHeight, visibleHeight),
+  );
+  const subHeight = args.agentSelector ? submenuMaxHeight : 0;
+  const openSubmenu = args.agentSelector && args.openSubmenu !== false;
+  const width = args.agentSelector
+    ? MENU_WIDTH + SUBMENU_GAP + SUBMENU_WIDTH
+    : MENU_WIDTH;
+  const height = Math.max(mainHeight, openSubmenu ? subHeight : 0);
+  const regionWidth = args.regionWidth ?? width;
+  const regionHeight = args.regionHeight ?? height;
+  const submenuSide =
+    args.avatarCenterX !== undefined && args.avatarCenterX < regionWidth / 2
+      ? "right"
+      : "left";
+  const rootX = clamp(
+    args.agentSelector && submenuSide === "left" ? regionWidth - MENU_WIDTH : 0,
+    0,
+    regionWidth - MENU_WIDTH,
+  );
+  const rootY = clamp(
+    args.popoverAbove ? regionHeight - mainHeight : 0,
+    0,
+    regionHeight - mainHeight,
+  );
+  const subX =
+    submenuSide === "right"
+      ? rootX + MENU_WIDTH + SUBMENU_GAP
+      : rootX - SUBMENU_GAP - SUBMENU_WIDTH;
+  const subY = clamp(rootY, 0, regionHeight - subHeight);
+  return {
+    regionSize: { width, height },
+    root: { x: rootX, y: rootY, width: MENU_WIDTH, height: mainHeight },
+    submenu: { x: subX, y: subY, width: SUBMENU_WIDTH, height: subHeight },
+    submenuMaxHeight,
+    submenuSide,
+  };
+}
+
+/** Overlay region the menu needs before it is rendered. */
+export function menuOverlaySize(args: {
+  agentSelector: boolean;
+  agentCount: number;
+  visibleHeight?: number;
+}): Size {
+  return computeAvatarMenuPlacement({
+    agentSelector: args.agentSelector,
+    agentCount: args.agentCount,
+    visibleHeight: args.visibleHeight,
+  }).regionSize;
+}
+
+/** Berd's submenu preview: a static first frame of the Berdy character. */
+function BerdPreview() {
+  return (
+    <video
+      className="menu-preview"
+      src={BERDY_CLIPS.idle1.file}
+      muted
+      playsInline
+      preload="auto"
+      width={PREVIEW_SIZE}
+      height={PREVIEW_SIZE}
+    />
+  );
+}
+
+const PREVIEW_STATE = deriveAvatarState({
+  hovering: false,
+  expanded: false,
+  connected: true,
+  activity: "none",
+});
+
+function AgentPreview({ agentId }: { agentId: string }) {
+  const avatar = useAgentAvatar(agentId);
+  return (
+    <span className="menu-preview">
+      <AvatarView
+        choice={avatar.choice}
+        state={PREVIEW_STATE}
+        size={PREVIEW_SIZE}
+      />
+    </span>
+  );
+}
+
+export function AvatarMenu({
+  layout,
+  agentSelector,
+  model,
+  onNewChat,
+  onSelectAgent,
+  onSelectFresh,
+  onSettings,
+  onTurnOff,
+  onClose,
+}: {
+  layout: ExpandedLayout;
+  agentSelector: boolean;
+  model: AvatarMenuModel;
+  onNewChat(): void;
+  onSelectAgent(agent: AgentInfo): void;
+  onSelectFresh(): void;
+  onSettings(): void;
+  onTurnOff(): void;
+  onClose?(): void;
+}) {
+  const { t } = useTranslation("desktop-agent");
+  const [submenuOpen, setSubmenuOpen] = useState(false);
+  const [highlight, setHighlight] = useState<number | null>(0);
+  const [subHighlight, setSubHighlight] = useState<number | null>(null);
+  const closeTimer = useRef<number | null>(null);
+  const rootRefs = useRef<Array<HTMLButtonElement | null>>([]);
+  const subRefs = useRef<Array<HTMLButtonElement | null>>([]);
+
+  const rootItems = useMemo<
+    Array<"newChat" | "switch" | "settings" | "turnOff">
+  >(
+    () =>
+      agentSelector
+        ? ["newChat", "switch", "settings", "turnOff"]
+        : ["newChat", "settings", "turnOff"],
+    [agentSelector],
+  );
+  const subItems = useMemo<("fresh" | AgentInfo)[]>(
+    () => ["fresh" as const, ...model.agents],
+    [model.agents],
+  );
+
+  const regionW = layout.popoverRect.width;
+  const regionH = layout.popoverRect.height;
+  const avatarCenterX =
+    layout.avatarRect.x + layout.avatarRect.width / 2 - layout.popoverRect.x;
+  const placement = computeAvatarMenuPlacement({
+    agentSelector,
+    agentCount: model.agents.length,
+    visibleHeight: regionH,
+    openSubmenu: submenuOpen,
+    regionWidth: regionW,
+    regionHeight: regionH,
+    avatarCenterX,
+    popoverAbove: layout.popoverAbove,
+  });
+
+  const clearCloseTimer = useCallback(() => {
+    if (closeTimer.current !== null) window.clearTimeout(closeTimer.current);
+    closeTimer.current = null;
+  }, []);
+  const openSubmenu = useCallback(() => {
+    clearCloseTimer();
+    setSubmenuOpen(true);
+  }, [clearCloseTimer]);
+  const scheduleSubmenuClose = useCallback(() => {
+    clearCloseTimer();
+    closeTimer.current = window.setTimeout(() => {
+      closeTimer.current = null;
+      setSubmenuOpen(false);
+      setSubHighlight(null);
+    }, SUBMENU_CLOSE_DELAY_MS);
+  }, [clearCloseTimer]);
+
+  useEffect(() => clearCloseTimer, [clearCloseTimer]);
+
+  useEffect(() => {
+    if (highlight !== null) rootRefs.current[highlight]?.focus();
+  }, [highlight]);
+
+  useEffect(() => {
+    if (subHighlight !== null) subRefs.current[subHighlight]?.focus();
+  }, [subHighlight]);
+
+  const activateRoot = useCallback(
+    (item: (typeof rootItems)[number]) => {
+      if (item === "newChat") {
+        onNewChat();
+        return;
+      }
+      if (item === "switch") {
+        openSubmenu();
+        setSubHighlight(0);
+        return;
+      }
+      if (item === "settings") onSettings();
+      else onTurnOff();
+    },
+    [onTurnOff, onNewChat, onSettings, openSubmenu],
+  );
+
+  useEffect(() => {
+    const move = (index: number | null, delta: number, length: number) =>
+      index === null
+        ? delta > 0
+          ? 0
+          : length - 1
+        : (index + delta + length) % length;
+    const onKey = (e: KeyboardEvent) => {
+      switch (e.key) {
+        case "ArrowDown":
+        case "ArrowUp": {
+          const delta = e.key === "ArrowDown" ? 1 : -1;
+          if (submenuOpen)
+            setSubHighlight((i) => move(i, delta, subItems.length));
+          else setHighlight((i) => move(i, delta, rootItems.length));
+          e.preventDefault();
+          break;
+        }
+        case "ArrowRight":
+          if (!submenuOpen && rootItems[highlight ?? -1] === "switch") {
+            openSubmenu();
+            setSubHighlight(0);
+            e.preventDefault();
+          }
+          break;
+        case "ArrowLeft":
+          if (submenuOpen) {
+            const switchIndex = rootItems.indexOf("switch");
+            setSubmenuOpen(false);
+            setSubHighlight(null);
+            setHighlight(switchIndex);
+            rootRefs.current[switchIndex]?.focus();
+            e.preventDefault();
+          }
+          break;
+        case "Escape":
+          onClose?.();
+          e.preventDefault();
+          break;
+        case "Enter":
+          if (e.repeat) break;
+          if (submenuOpen) {
+            const item = subItems[subHighlight ?? -1];
+            if (item !== undefined) {
+              if (item === "fresh") onSelectFresh();
+              else onSelectAgent(item);
+              e.preventDefault();
+            }
+          } else {
+            const item = rootItems[highlight ?? -1];
+            if (item !== undefined) {
+              activateRoot(item);
+              e.preventDefault();
+            }
+          }
+          break;
+        default:
+          break;
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [
+    highlight,
+    activateRoot,
+    onSelectAgent,
+    onSelectFresh,
+    onClose,
+    openSubmenu,
+    rootItems,
+    subHighlight,
+    subItems,
+    submenuOpen,
+  ]);
+
+  const row = (args: {
+    key: string;
+    className?: string;
+    highlighted: boolean;
+    menu: "root" | "sub";
+    index: number;
+    onHover(): void;
+    onClick(): void;
+    children: React.ReactNode;
+  }) => (
+    <button
+      key={args.key}
+      ref={(node) => {
+        const refs = args.menu === "root" ? rootRefs.current : subRefs.current;
+        refs[args.index] = node;
+      }}
+      type="button"
+      className={`menu-row focus-override ${args.className ?? ""} ${
+        args.highlighted ? "highlighted" : ""
+      }`}
+      onPointerEnter={args.onHover}
+      onClick={args.onClick}
+      role="menuitem"
+      tabIndex={args.highlighted ? 0 : -1}
+    >
+      {args.children}
+    </button>
+  );
+
+  return (
+    <div className="avatar-menu-region">
+      <div
+        className="menu-card avatar-menu"
+        style={{
+          left: placement.root.x,
+          top: placement.root.y,
+          width: MENU_WIDTH,
+        }}
+        role="menu"
+        onPointerEnter={clearCloseTimer}
+      >
+        {(() => {
+          const index = rootItems.indexOf("newChat");
+          return row({
+            key: "newChat",
+            menu: "root",
+            index,
+            highlighted: highlight === index,
+            onHover: () => {
+              setHighlight(index);
+              scheduleSubmenuClose();
+            },
+            onClick: onNewChat,
+            children: <span className="menu-label">{t("menu.newChat")}</span>,
+          });
+        })()}
+        {agentSelector && (
+          <>
+            {(() => {
+              const index = rootItems.indexOf("switch");
+              return row({
+                key: "switch",
+                menu: "root",
+                index,
+                highlighted: highlight === index,
+                onHover: () => {
+                  setHighlight(index);
+                  openSubmenu();
+                },
+                onClick: () => {
+                  openSubmenu();
+                  setSubHighlight(0);
+                },
+                children: (
+                  <>
+                    <span className="menu-label">{t("menu.switchAgent")}</span>
+                    <span className="menu-chevron">›</span>
+                  </>
+                ),
+              });
+            })()}
+            <div className="menu-separator" />
+          </>
+        )}
+        {(() => {
+          const index = rootItems.indexOf("settings");
+          return row({
+            key: "settings",
+            menu: "root",
+            index,
+            highlighted: highlight === index,
+            onHover: () => {
+              setHighlight(index);
+              scheduleSubmenuClose();
+            },
+            onClick: onSettings,
+            children: <span className="menu-label">{t("menu.settings")}</span>,
+          });
+        })()}
+        {(() => {
+          const index = rootItems.indexOf("turnOff");
+          return row({
+            key: "turnOff",
+            menu: "root",
+            index,
+            highlighted: highlight === index,
+            onHover: () => {
+              setHighlight(index);
+              scheduleSubmenuClose();
+            },
+            onClick: onTurnOff,
+            children: <span className="menu-label">{t("menu.turnOff")}</span>,
+          });
+        })()}
+      </div>
+      {agentSelector && submenuOpen && (
+        <div
+          className="menu-card avatar-submenu"
+          style={{
+            left: placement.submenu.x,
+            top: placement.submenu.y,
+            width: SUBMENU_WIDTH,
+            maxHeight: placement.submenuMaxHeight,
+          }}
+          role="menu"
+          onPointerEnter={clearCloseTimer}
+          onPointerLeave={scheduleSubmenuClose}
+        >
+          {row({
+            key: "fresh",
+            menu: "sub",
+            index: 0,
+            highlighted: subHighlight === 0,
+            onHover: () => setSubHighlight(0),
+            onClick: onSelectFresh,
+            children: (
+              <>
+                <BerdPreview />
+                <span className="menu-label">{t("menu.fresh")}</span>
+                {model.checkedFresh && <span className="menu-check">✓</span>}
+              </>
+            ),
+          })}
+          {model.agents.map((agent, i) =>
+            row({
+              key: agent.agentId,
+              menu: "sub",
+              index: i + 1,
+              highlighted: subHighlight === i + 1,
+              onHover: () => setSubHighlight(i + 1),
+              onClick: () => onSelectAgent(agent),
+              children: (
+                <>
+                  <AgentPreview agentId={agent.agentId} />
+                  <span className="menu-label">{agent.name}</span>
+                  {model.checkedAgentId === agent.agentId && (
+                    <span className="menu-check">✓</span>
+                  )}
+                </>
+              ),
+            }),
+          )}
+          {model.agents.length === 0 && (
+            <div className="menu-empty">{t("menu.empty")}</div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/features/desktop-agent/ui/AvatarView.tsx b/src/features/desktop-agent/ui/AvatarView.tsx
new file mode 100644
index 000000000..fd13a1ea7
--- /dev/null
+++ b/src/features/desktop-agent/ui/AvatarView.tsx
@@ -0,0 +1,209 @@
+// Avatar chip: looping HEVC video with per-state treatment (ported from
+// the prototype's avatar_view.dart). No rings or overlays — the animation itself is
+// the avatar. While the video initializes the chip stays invisible (no
+// placeholder flash); the prototype's flash-free swap rule carries over: the old
+// source keeps playing until the new one is ready.
+
+import { useEffect, useRef, useState } from "react";
+
+import {
+  cornerRadius,
+  treatmentFor,
+  type AvatarChoice,
+  type AvatarState,
+} from "../lib/avatarState";
+
+export function AvatarView({
+  choice,
+  state,
+  size,
+  onReady,
+}: {
+  choice: AvatarChoice;
+  state: AvatarState;
+  size: number;
+  onReady?: () => void;
+}) {
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const [ready, setReady] = useState(false);
+  const onReadyRef = useRef(onReady);
+  onReadyRef.current = onReady;
+  useEffect(() => {
+    if (ready) onReadyRef.current?.();
+  }, [ready]);
+  // Flash-free swap: keep rendering the previous src until the new one is
+  // ready. Two media elements never render at once — the src only advances
+  // when the probe confirms it decodable (browser keeps painting the old
+  // frame until then; the single-element swap is imperceptible at chip size).
+  // The ACTIVE kind rides along: during a video->image swap the displayed
+  // element must stay a <video> until the image is ready.
+  const [active, setActive] = useState({ src: choice.src, kind: choice.kind });
+
+  useEffect(() => {
+    if (choice.src === active.src) return;
+    const next = { src: choice.src, kind: choice.kind };
+    // Probe matches the media kind of the INCOMING source.
+    if (choice.kind === "image") {
+      const probe = new Image();
+      probe.src = choice.src;
+      probe.onload = () => setActive(next);
+      probe.onerror = () => setActive(next); // visible failure beats a stuck chip
+      return () => {
+        probe.onload = null;
+        probe.onerror = null;
+      };
+    }
+    const probe = document.createElement("video");
+    probe.muted = true;
+    probe.src = choice.src;
+    probe.oncanplay = () => setActive(next);
+    probe.onerror = () => setActive(next); // fall through; visible failure beats a stuck chip
+    probe.load();
+    return () => {
+      probe.oncanplay = null;
+      probe.onerror = null;
+    };
+  }, [choice.src, choice.kind, active.src]);
+
+  const treatment = treatmentFor(state);
+
+  // Apply playback treatment whenever state or the element changes.
+  // Static images have no playback — scale/desaturation still apply via
+  // the chip style below.
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !ready || active.kind !== "video") return;
+    video.playbackRate = treatment.playbackRate;
+    if (treatment.paused) {
+      video.pause();
+    } else if (video.paused) {
+      void video.play().catch(() => {});
+    }
+  }, [treatment.playbackRate, treatment.paused, ready, active]);
+
+  // Frozen-avatar fix: WKWebView pauses <video> EXTERNALLY when the
+  // panel hides or is occluded. The treatment effect above only re-runs
+  // when its deps change — and the
+  // common transitions (hover↔idle, expanded↔collapsed) all keep
+  // playbackRate=1.0/paused=false, so an external pause stuck forever
+  // (only incidentally cured when a send flipped thinking's 1.6 rate).
+  // Two re-assertion paths, both no-ops for a legitimate error-state
+  // pause (treatment.paused reads the CURRENT treatment via ref):
+  const treatmentRef = useRef(treatment);
+  treatmentRef.current = treatment;
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !ready || active.kind !== "video") return;
+    // 1. The element itself reports the muzzle: an external pause fires
+    //    `pause` — resume unless the treatment genuinely wants a pause.
+    const onPause = () => {
+      if (!treatmentRef.current.paused) void video.play().catch(() => {});
+    };
+    // 2. Belt-and-suspenders: on becoming visible again, re-assert the
+    //    full treatment (some WKWebView pauses land without a pause
+    //    event reaching JS).
+    const onVisible = () => {
+      if (document.visibilityState !== "visible") return;
+      video.playbackRate = treatmentRef.current.playbackRate;
+      if (!treatmentRef.current.paused && video.paused) {
+        void video.play().catch(() => {});
+      }
+    };
+    video.addEventListener("pause", onPause);
+    document.addEventListener("visibilitychange", onVisible);
+    return () => {
+      video.removeEventListener("pause", onPause);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [ready, active]);
+
+  // Stall watchdog (hide/show alone did NOT cure a frozen loop in the
+  // field, so the pause-event/visibility paths above can miss). WKWebView
+  // has a further failure mode: the video reports paused=false but the
+  // decoder is suspended — no pause event, no visibility change, frozen
+  // frames. Poll currentTime; if it stops advancing while the treatment
+  // wants motion, nudge (seek + play), then fully re-init the decoder
+  // (load) as the last resort. Steady state is one cheap property read
+  // per tick.
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !ready || active.kind !== "video") return;
+    let last = -1;
+    let stalledTicks = 0;
+    const id = window.setInterval(() => {
+      if (treatmentRef.current.paused) {
+        last = -1;
+        stalledTicks = 0;
+        return; // error state: frozen is correct
+      }
+      const now = video.currentTime;
+      if (now !== last) {
+        last = now;
+        stalledTicks = 0;
+        return; // advancing: healthy
+      }
+      stalledTicks += 1;
+      if (stalledTicks <= 2) {
+        // Gentle kick: a micro-seek forces a decode; play() covers the
+        // silently-paused variant.
+        try {
+          video.currentTime = now + 0.01;
+        } catch {
+          /* seek can throw pre-metadata; the next tick escalates */
+        }
+        void video.play().catch(() => {});
+      } else if (stalledTicks === 3) {
+        // Decoder re-init. loop/muted/autoplay attributes persist; the
+        // existing onCanPlay handler re-fires. ready stays true — the
+        // brief re-buffer beats an eternally frozen avatar.
+        video.load();
+        void video.play().catch(() => {});
+      }
+    }, 1500);
+    return () => window.clearInterval(id);
+  }, [ready, active]);
+
+  // Per-avatar render scale: shrinks the CHIP only. The hit target and
+  // panel frame stay full size (the flex-centered parent absorbs the
+  // difference), so drag/click/perch geometry is unchanged.
+  const rendered = size * (choice.renderScale ?? 1);
+
+  return (
+    <div
+      className="avatar-chip"
+      style={{
+        width: rendered,
+        height: rendered,
+        borderRadius: cornerRadius(choice.shape, rendered),
+        overflow: "hidden",
+        transform: `scale(${treatment.scale})`,
+        transition: "transform 140ms ease, filter 220ms ease",
+        filter: treatment.desaturated ? "grayscale(1) brightness(0.7)" : "none",
+        opacity: ready ? 1 : 0,
+      }}
+    >
+      {active.kind === "image" ? (
+        <img
+          key={active.src}
+          src={active.src}
+          alt=""
+          draggable={false}
+          onLoad={() => setReady(true)}
+          style={{ width: "100%", height: "100%", objectFit: "cover" }}
+        />
+      ) : (
+        <video
+          ref={videoRef}
+          key={active.src}
+          src={active.src}
+          muted
+          loop
+          autoPlay
+          playsInline
+          onCanPlay={() => setReady(true)}
+          style={{ width: "100%", height: "100%", objectFit: "cover" }}
+        />
+      )}
+    </div>
+  );
+}
diff --git a/src/features/desktop-agent/ui/BerdyView.test.tsx b/src/features/desktop-agent/ui/BerdyView.test.tsx
new file mode 100644
index 000000000..2b9c2b450
--- /dev/null
+++ b/src/features/desktop-agent/ui/BerdyView.test.tsx
@@ -0,0 +1,61 @@
+import { act, render } from "@testing-library/react";
+import { beforeEach, expect, it, vi } from "vitest";
+
+import { BerdyView } from "@/features/desktop-agent/ui/BerdyView";
+
+const instances = vi.hoisted(
+  () =>
+    [] as {
+      start: ReturnType<typeof vi.fn>;
+      setTarget: ReturnType<typeof vi.fn>;
+      suspend: ReturnType<typeof vi.fn>;
+      resume: ReturnType<typeof vi.fn>;
+      dispose: ReturnType<typeof vi.fn>;
+    }[],
+);
+vi.mock("@/features/desktop-agent/lib/berdyMachine", () => ({
+  BerdyMachine: class {
+    start = vi.fn();
+    setTarget = vi.fn();
+    suspend = vi.fn();
+    resume = vi.fn();
+    dispose = vi.fn();
+    constructor() {
+      instances.push(this);
+    }
+  },
+}));
+beforeEach(() => {
+  instances.length = 0;
+});
+it("recreated machine receives current pose and suspension after reduced-motion toggles", () => {
+  let reduced = false;
+  let change = () => {};
+  vi.spyOn(window, "matchMedia").mockImplementation(
+    () =>
+      ({
+        get matches() {
+          return reduced;
+        },
+        addEventListener: (_: string, cb: () => void) => {
+          change = cb;
+        },
+        removeEventListener: vi.fn(),
+      }) as unknown as MediaQueryList,
+  );
+  const { rerender, unmount } = render(
+    <BerdyView target="sit" errored={false} hidden={false} size={92} />,
+  );
+  expect(instances[0].setTarget).toHaveBeenCalledWith("sit");
+  rerender(<BerdyView target="dangle" errored hidden size={92} />);
+  expect(instances[0].suspend).toHaveBeenCalled();
+  reduced = true;
+  act(() => change());
+  expect(instances[0].dispose).toHaveBeenCalledOnce();
+  reduced = false;
+  act(() => change());
+  expect(instances[1].setTarget).toHaveBeenCalledWith("dangle");
+  expect(instances[1].suspend).toHaveBeenCalled();
+  unmount();
+  expect(instances[1].dispose).toHaveBeenCalledOnce();
+});
diff --git a/src/features/desktop-agent/ui/BerdyView.tsx b/src/features/desktop-agent/ui/BerdyView.tsx
new file mode 100644
index 000000000..439239293
--- /dev/null
+++ b/src/features/desktop-agent/ui/BerdyView.tsx
@@ -0,0 +1,99 @@
+import { useEffect, useRef, useState } from "react";
+
+import type { BerdyPose } from "@/features/desktop-agent/lib/berdyClips";
+import { BerdyMachine } from "@/features/desktop-agent/lib/berdyMachine";
+
+export function BerdyView({
+  target,
+  errored,
+  hidden,
+  size,
+  onReady,
+}: {
+  target: BerdyPose;
+  errored: boolean;
+  hidden: boolean;
+  size: number;
+  onReady?: () => void;
+}) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const machineRef = useRef<BerdyMachine | null>(null);
+  const [ready, setReady] = useState(false);
+  const [reducedMotion, setReducedMotion] = useState(
+    () => window.matchMedia("(prefers-reduced-motion: reduce)").matches,
+  );
+  const latest = useRef({ target, errored, hidden, onReady });
+  latest.current = { target, errored, hidden, onReady };
+
+  useEffect(() => {
+    const media = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const update = () => setReducedMotion(media.matches);
+    media.addEventListener("change", update);
+    return () => media.removeEventListener("change", update);
+  }, []);
+
+  useEffect(() => {
+    if (reducedMotion || !canvasRef.current) return;
+    setReady(false);
+    const machine = new BerdyMachine({
+      canvas: canvasRef.current,
+      onReady: () => {
+        setReady(true);
+        latest.current.onReady?.();
+      },
+    });
+    machineRef.current = machine;
+    machine.setTarget(latest.current.target);
+    const sync = () => {
+      if (
+        latest.current.errored ||
+        latest.current.hidden ||
+        document.visibilityState === "hidden"
+      )
+        machine.suspend();
+      else machine.resume();
+    };
+    sync();
+    machine.start();
+    document.addEventListener("visibilitychange", sync);
+    return () => {
+      document.removeEventListener("visibilitychange", sync);
+      machine.dispose();
+      machineRef.current = null;
+    };
+  }, [reducedMotion]);
+
+  useEffect(() => {
+    machineRef.current?.setTarget(target);
+  }, [target]);
+  useEffect(() => {
+    const machine = machineRef.current;
+    if (errored || hidden || document.visibilityState === "hidden")
+      machine?.suspend();
+    else machine?.resume();
+  }, [errored, hidden]);
+
+  const style = {
+    width: size,
+    height: size,
+    filter: errored ? "grayscale(1) brightness(0.7)" : "none",
+  };
+  if (reducedMotion)
+    return (
+      <img
+        src="/desktop-agent/berdy/berdy_Idle_01_00001_.png"
+        alt=""
+        draggable={false}
+        style={style}
+        onLoad={() => latest.current.onReady?.()}
+      />
+    );
+  return (
+    <canvas
+      ref={canvasRef}
+      width={400}
+      height={400}
+      style={{ ...style, opacity: ready ? 1 : 0 }}
+    />
+  );
+}
diff --git a/src/features/desktop-agent/ui/ChatPopover.test.tsx b/src/features/desktop-agent/ui/ChatPopover.test.tsx
new file mode 100644
index 000000000..a9df89ed6
--- /dev/null
+++ b/src/features/desktop-agent/ui/ChatPopover.test.tsx
@@ -0,0 +1,247 @@
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { ChatPopover } from "./ChatPopover";
+import type { ChatMessage } from "../lib/chatModels";
+import type { PerchView } from "../hooks/usePerch";
+import type { SessionView } from "../hooks/useSession";
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string) => key,
+  }),
+}));
+
+vi.mock("./MarkdownBody", () => ({
+  MarkdownBody: ({ text }: { text: string }) => <span>{text}</span>,
+}));
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function perch(overrides: Partial<PerchView> = {}): PerchView {
+  return {
+    phase: "unperched",
+    appName: null,
+    title: null,
+    lastError: null,
+    beginTargeting: vi.fn(),
+    endTargetingAndMaybePerch: vi.fn(),
+    cancelTargeting: vi.fn(),
+    dismount: vi.fn(),
+    artifactUrlNow: vi.fn(async () => null),
+    captureNow: vi.fn(async () => null),
+    ...overrides,
+  } as unknown as PerchView;
+}
+
+function session(
+  messages: ChatMessage[],
+  overrides: Partial<SessionView> = {},
+): SessionView {
+  return {
+    messages,
+    pendingSelection: null,
+    attached: true,
+    connectionError: null,
+    reconnectExhausted: false,
+    lastSendError: null,
+    sendStalled: false,
+    agentSendInFlight: false,
+    activity: "none",
+    sendBusy: () => false,
+    send: vi.fn(async () => true),
+    retry: vi.fn(),
+    stop: vi.fn(),
+    ...overrides,
+  } as unknown as SessionView;
+}
+
+function setScrollMetrics(
+  el: HTMLElement,
+  metrics: { scrollHeight: number; clientHeight: number },
+) {
+  Object.defineProperty(el, "scrollHeight", {
+    configurable: true,
+    value: metrics.scrollHeight,
+  });
+  Object.defineProperty(el, "clientHeight", {
+    configurable: true,
+    value: metrics.clientHeight,
+  });
+}
+
+const message = (id: string, text: string): ChatMessage => ({
+  id,
+  role: "assistant",
+  createdAt: 0,
+  content: [{ type: "text", text }],
+  isStreaming: false,
+});
+
+describe("ChatPopover transcript following", () => {
+  it("scrolls to the bottom when messages append or streaming text extends", () => {
+    const first = [message("m1", "hello")];
+    const view = render(
+      <ChatPopover session={session(first)} perch={perch()} variant="full" />,
+    );
+    const transcript = view.container.querySelector(
+      ".transcript",
+    ) as HTMLElement;
+    setScrollMetrics(transcript, { scrollHeight: 100, clientHeight: 50 });
+
+    act(() => {
+      view.rerender(
+        <ChatPopover
+          session={session([message("m1", "hello"), message("m2", "world")])}
+          perch={perch()}
+          variant="full"
+        />,
+      );
+    });
+    expect(transcript.scrollTop).toBe(100);
+
+    setScrollMetrics(transcript, { scrollHeight: 180, clientHeight: 50 });
+    act(() => {
+      view.rerender(
+        <ChatPopover
+          session={session([message("m1", "hello"), message("m2", "world!!!")])}
+          perch={perch()}
+          variant="full"
+        />,
+      );
+    });
+    expect(transcript.scrollTop).toBe(180);
+  });
+
+  it("preserves scroll position after the user scrolls away from bottom", () => {
+    const view = render(
+      <ChatPopover
+        session={session([message("m1", "hello")])}
+        perch={perch()}
+        variant="full"
+      />,
+    );
+    const transcript = view.container.querySelector(
+      ".transcript",
+    ) as HTMLElement;
+    setScrollMetrics(transcript, { scrollHeight: 300, clientHeight: 100 });
+    transcript.scrollTop = 100;
+    fireEvent.scroll(transcript);
+
+    act(() => {
+      view.rerender(
+        <ChatPopover
+          session={session([message("m1", "hello"), message("m2", "later")])}
+          perch={perch()}
+          variant="full"
+        />,
+      );
+    });
+
+    expect(transcript.scrollTop).toBe(100);
+  });
+});
+
+describe("ChatPopover perched capture send state", () => {
+  it("blocks a second submit while capture is pending", async () => {
+    const capture = deferred<{ data: string; mimeType: string } | null>();
+    const send = vi.fn(async () => true);
+    render(
+      <ChatPopover
+        session={session([], { send })}
+        perch={perch({
+          phase: "perched",
+          appName: "Safari",
+          artifactUrlNow: vi.fn(async () => null),
+          captureNow: vi.fn(() => capture.promise),
+        })}
+        variant="composer"
+      />,
+    );
+
+    const input = screen.getByRole("textbox");
+    fireEvent.change(input, { target: { value: "summarize" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(screen.getByText("hint.capturing")).toBeInTheDocument();
+    fireEvent.change(input, { target: { value: "second" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(send).not.toHaveBeenCalled();
+
+    await act(async () =>
+      capture.resolve({ data: "abc", mimeType: "image/png" }),
+    );
+    expect(send).toHaveBeenCalledOnce();
+  });
+
+  it("clears the capturing hint after capture resolves while send stays gated", async () => {
+    const capture = deferred<{ data: string; mimeType: string } | null>();
+    const dispatch = deferred<boolean>();
+    const send = vi.fn(() => dispatch.promise);
+    render(
+      <ChatPopover
+        session={session([], { send })}
+        perch={perch({
+          phase: "perched",
+          appName: "Safari",
+          artifactUrlNow: vi.fn(async () => null),
+          captureNow: vi.fn(() => capture.promise),
+        })}
+        variant="composer"
+      />,
+    );
+
+    const input = screen.getByRole("textbox");
+    fireEvent.change(input, { target: { value: "summarize" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(screen.getByText("hint.capturing")).toBeInTheDocument();
+
+    await act(async () => {
+      capture.resolve({ data: "abc", mimeType: "image/png" });
+      await Promise.resolve();
+    });
+    expect(screen.queryByText("hint.capturing")).not.toBeInTheDocument();
+    expect(send).toHaveBeenCalledOnce();
+
+    fireEvent.change(input, { target: { value: "second" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(send).toHaveBeenCalledOnce();
+
+    await act(async () => dispatch.resolve(true));
+  });
+
+  it("sends text-only and releases capture state when capture fails", async () => {
+    const send = vi.fn(async () => true);
+    render(
+      <ChatPopover
+        session={session([], { send })}
+        perch={perch({
+          phase: "perched",
+          appName: "Safari",
+          captureNow: vi.fn(async () => null),
+        })}
+        variant="composer"
+      />,
+    );
+
+    const input = screen.getByRole("textbox");
+    fireEvent.change(input, { target: { value: "what is here" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(screen.getByText("hint.capturing")).toBeInTheDocument();
+    await act(async () => await Promise.resolve());
+
+    expect(send).toHaveBeenCalledWith(
+      "what is here",
+      undefined,
+      expect.any(Function),
+    );
+    expect(screen.queryByText("hint.capturing")).not.toBeInTheDocument();
+  });
+});
diff --git a/src/features/desktop-agent/ui/ChatPopover.tsx b/src/features/desktop-agent/ui/ChatPopover.tsx
new file mode 100644
index 000000000..ada9be647
--- /dev/null
+++ b/src/features/desktop-agent/ui/ChatPopover.tsx
@@ -0,0 +1,425 @@
+// Desktop-agent chat popover: transcript list, grouped tool activity,
+// scoped markdown for assistant replies, and the composer. User text
+// stays verbatim in display; wire-only preambles are stripped during
+// replay by transcriptDisplay. All user-facing strings live in the
+// `desktop-agent` i18n namespace.
+
+import { useEffect, useLayoutEffect, useRef, useState, type Ref } from "react";
+import { useTranslation } from "react-i18next";
+
+import {
+  plainText,
+  type ChatMessage,
+  type ToolActivity,
+} from "../lib/chatModels";
+import { deriveComposerHint } from "../lib/composerHint";
+import { chooseComposerSendSource, perchSendPreamble } from "../lib/sendSource";
+import {
+  groupTranscript,
+  stripWirePreamble,
+  toolDisplayName,
+  toolGlyph,
+  toolResultText,
+} from "../lib/transcriptDisplay";
+import { MarkdownBody } from "./MarkdownBody";
+import type { PerchView } from "../hooks/usePerch";
+import type { SessionView } from "../hooks/useSession";
+
+/** Consecutive tool-only messages, collapsed to one quiet summary line —
+ *  a replayed agent session would otherwise render dozens of tool rows
+ *  drowning the conversation. Click expands the individual calls;
+ *  failures are surfaced in the summary. */
+function ToolRunRow({ tools }: { tools: ToolActivity[] }) {
+  const { t } = useTranslation("desktop-agent");
+  const [expanded, setExpanded] = useState(false);
+  const failed = tools.filter((tool) => tool.status === "failed").length;
+  const running = tools.some(
+    (tool) => tool.status !== "completed" && tool.status !== "failed",
+  );
+  const summary = running
+    ? `⚙ ${t("tools.working", { count: tools.length })}`
+    : `⚙ ${t("tools.summary", { count: tools.length })}${
+        failed > 0 ? ` · ${t("tools.failed", { count: failed })}` : ""
+      }`;
+  return (
+    <div className="row assistant">
+      <button
+        type="button"
+        className={`tool-run-summary ${failed > 0 ? "has-failures" : ""}`}
+        onClick={() => setExpanded((open) => !open)}
+        title={expanded ? t("tools.collapse") : t("tools.expand")}
+      >
+        <span className={`disclosure ${expanded ? "open" : ""}`}>›</span>
+        {summary}
+      </button>
+      {expanded && (
+        <div className="tool-run-detail">
+          {tools.map((tool) => {
+            const toolFailed = tool.status === "failed";
+            const result = toolFailed ? toolResultText(tool) : null;
+            return (
+              <div
+                key={tool.id}
+                className={`tool-row ${toolFailed ? "failed" : ""}`}
+              >
+                <div className="tool-row-header">
+                  <span className="tool-row-glyph">
+                    {toolGlyph(tool.status)}
+                  </span>
+                  <span className="tool-row-name">{toolDisplayName(tool)}</span>
+                  {toolFailed && result !== null && (
+                    <span className="tool-row-hint">
+                      {t("tools.failureDetail")}
+                    </span>
+                  )}
+                </div>
+                {result !== null && (
+                  <pre className={`tool-result ${toolFailed ? "failed" : ""}`}>
+                    {result}
+                  </pre>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function MessageRow({ message }: { message: ChatMessage }) {
+  const text = plainText(message);
+  return (
+    <div className={`row ${message.role}`}>
+      {message.content.map((content, i) => {
+        if (content.type === "text") {
+          // Assistant text renders as markdown (agents answer in it);
+          // user text stays verbatim — echoing someone's asterisks back
+          // as bold would misquote them. Replayed user text is display-
+          // stripped of OUR wire preamble (transcriptDisplay).
+          return (
+            // biome-ignore lint/suspicious/noArrayIndexKey: message content arrays are wire-truth and only ever append — the index IS the stable identity
+            <div key={i} className="bubble">
+              {message.role === "assistant" ? (
+                <MarkdownBody text={content.text} />
+              ) : (
+                stripWirePreamble(content.text)
+              )}
+              {message.isStreaming && <span className="cursor">▋</span>}
+            </div>
+          );
+        }
+        if (content.type === "tool") {
+          // Tool inside a MIXED message (text + tool): a single quiet row.
+          // Tool-ONLY messages never reach here — groupTranscript collapses
+          // them into a ToolRunRow.
+          return (
+            // biome-ignore lint/suspicious/noArrayIndexKey: message content arrays are wire-truth and only ever append — the index IS the stable identity
+            <div key={i} className="tool-row">
+              {toolGlyph(content.tool.status)} {toolDisplayName(content.tool)}
+            </div>
+          );
+        }
+        if (content.type === "image") {
+          return (
+            <img
+              // biome-ignore lint/suspicious/noArrayIndexKey: message content arrays are wire-truth and only ever append — the index IS the stable identity
+              key={i}
+              className="attached-image"
+              src={`data:${content.mimeType};base64,${content.data}`}
+              alt=""
+            />
+          );
+        }
+        return null;
+      })}
+      {message.content.length === 0 && message.isStreaming && (
+        <div className="bubble thinking-dots">…</div>
+      )}
+      {text === null &&
+        message.content.length === 0 &&
+        !message.isStreaming &&
+        null}
+    </div>
+  );
+}
+
+export function ChatPopover({
+  session,
+  perch,
+  variant = "full",
+  anchor = "bottom",
+  composerRef,
+}: {
+  session: SessionView;
+  perch: PerchView;
+  /** "composer": no transcript yet — the popover is just the composer
+   *  pill (plus the hint row when relevant). The parent sizes the window
+   *  accordingly and upgrades to "full" when the first message lands. */
+  variant?: "full" | "composer";
+  /** Which edge of the overlay region faces the avatar — the composer-
+   *  only pill hugs it. */
+  anchor?: "top" | "bottom" | "center";
+  composerRef?: Ref<HTMLDivElement>;
+}) {
+  const { t } = useTranslation("desktop-agent");
+  const [draft, setDraft] = useState("");
+  const [capturePending, setCapturePending] = useState(false);
+  const capturePendingRef = useRef(false);
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  // Follow streaming output only while the user is already near the
+  // bottom — otherwise every incoming chunk would yank the scroll back
+  // to the latest token while someone reads earlier content.
+  const followBottom = useRef(true);
+
+  const noteScrollPosition = () => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+    followBottom.current = distanceFromBottom < 48;
+  };
+
+  const lastMessage = session.messages.at(-1);
+  const lastTool = lastMessage?.content.findLast(
+    (content) => content.type === "tool",
+  );
+  const lastMessageContentLength =
+    lastMessage?.content.reduce(
+      (total, content) =>
+        total +
+        (content.type === "text" || content.type === "system"
+          ? content.text.length
+          : content.type === "image"
+            ? content.data.length
+            : (content.tool.result?.length ?? 0)),
+      0,
+    ) ?? 0;
+  const transcriptFollowKey = [
+    session.messages.length,
+    lastMessageContentLength,
+    lastTool?.tool.status ?? "",
+  ].join(":");
+
+  // Pin to bottom only when we're following. useLayoutEffect avoids a
+  // visible two-frame jump when a new chunk extends the transcript.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: transcriptFollowKey is the rendered-content signal; refs are intentionally stable.
+  useLayoutEffect(() => {
+    const el = scrollRef.current;
+    if (el && followBottom.current) el.scrollTop = el.scrollHeight;
+  }, [transcriptFollowKey]);
+
+  // Focus the composer when the popover opens.
+  useEffect(() => {
+    const timer = setTimeout(() => inputRef.current?.focus(), 80);
+    return () => clearTimeout(timer);
+  }, []);
+
+  const submit = () => {
+    // Send gate: while a deferred create is in flight OR a run is
+    // streaming on the live session, Enter must do nothing — goosed
+    // allows one run per session (a concurrent prompt is rejected with
+    // invalid_params), so mid-run sends are DISALLOWED here rather than
+    // surfaced as wire errors. sendBusy() is the SYNCHRONOUS
+    // view of the internal guards — checked before the draft clears, so
+    // a bounced Enter never eats the message: the draft stays put and
+    // the hint row already shows the streaming state.
+    if (
+      session.agentSendInFlight ||
+      session.sendBusy() ||
+      capturePendingRef.current
+    )
+      return;
+    const text = draft;
+    if (text.trim().length === 0) return;
+    // House rule: the composer clears immediately after snapshotting.
+    setDraft("");
+    // Perch identity snapshots at SUBMIT — a send must not pick up a
+    // perch that changed mid-flight (the capture/URL fetches below are
+    // async and the user can dismount meanwhile).
+    const source = chooseComposerSendSource({ perchPhase: perch.phase });
+    if (source === "perchedWindow") {
+      capturePendingRef.current = true;
+      setCapturePending(true);
+    }
+    const perchPhase = perch.phase;
+    const perchApp = perch.appName;
+    const perchTitle = perch.title;
+    void (async () => {
+      let dispatched = false;
+      try {
+        // Fresh per send: tabs change. Failures are null — never blocking.
+        const artifactUrl =
+          source === "perchedWindow" ? await perch.artifactUrlNow() : null;
+        const makePreamble =
+          source === "perchedWindow"
+            ? (fullGuidance: boolean) =>
+                perchSendPreamble({
+                  phase: perchPhase,
+                  appName: perchApp,
+                  title: perchTitle,
+                  artifactUrl,
+                  fullGuidance,
+                })
+            : null;
+        // Fresh capture per send; failure degrades to a text-only send.
+        const image =
+          source === "perchedWindow" ? await perch.captureNow() : null;
+        if (source === "perchedWindow") setCapturePending(false);
+        dispatched = await session.send(
+          text,
+          image ? [{ type: "image", ...image }] : undefined,
+          makePreamble,
+        );
+      } finally {
+        if (source === "perchedWindow") {
+          capturePendingRef.current = false;
+          setCapturePending(false);
+        }
+      }
+      // The gate check at the top of submit() ran BEFORE the async
+      // capture/URL awaits above — a competing send that dispatched
+      // during that gap closes the gate, and THIS send bounces off it
+      // untouched (mutate-nothing contract). The snapshotted draft must
+      // come back or the bounce eats the message. Only an untouched
+      // composer is restored: overwriting text the user typed meanwhile
+      // would trade one eaten message for another.
+      if (!dispatched) {
+        setDraft((current) => (current.length === 0 ? text : current));
+      }
+    })();
+    inputRef.current?.focus();
+  };
+
+  // Display name for the armed selection: agents show their name; the
+  // fresh entry shows the default identity.
+  const pendingName =
+    session.pendingSelection === null
+      ? null
+      : session.pendingSelection.kind === "agent"
+        ? session.pendingSelection.agent.name
+        : t("menu.fresh");
+
+  const hint = deriveComposerHint({
+    lastSendError: session.lastSendError,
+    perchError: perch.lastError,
+    perchPhase: perch.phase,
+    perchApp: perch.appName,
+    perchTitle: perch.title,
+    attached: session.attached,
+    connectionError: session.connectionError,
+    reconnectExhausted: session.reconnectExhausted,
+    sendStalled: session.sendStalled,
+    agentSendInFlight: session.agentSendInFlight,
+    capturePending,
+    pendingName,
+    thinking: session.activity === "thinking",
+  });
+
+  const hintRow = hint && (
+    <div className={`hint ${session.lastSendError ? "error" : ""}`}>
+      {t(hint.key, hint.params)}
+      {session.reconnectExhausted && !session.attached && (
+        <button
+          type="button"
+          className="hint-retry"
+          title={t("hint.retry")}
+          onClick={() => session.retry()}
+        >
+          ↻
+        </button>
+      )}
+    </div>
+  );
+
+  const composerBox = (
+    <div className="composer-box" ref={composerRef}>
+      <input
+        ref={inputRef}
+        // focus-override: opts out of globals.css's global focus-visible
+        // ring (the main-app composer convention — GlobalComposerPill
+        // does the same). Without it, clicking into the input paints a
+        // ring/offset box-shadow around it; the composer-box
+        // :focus-within border is this composer's focus affordance.
+        className="focus-override"
+        value={draft}
+        placeholder={
+          variant === "composer"
+            ? pendingName
+              ? t("composer.startAgent", { name: pendingName })
+              : t("composer.start")
+            : pendingName
+              ? t("composer.placeholderAgent", { name: pendingName })
+              : t("composer.placeholder")
+        }
+        onChange={(e) => setDraft(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && !e.nativeEvent.isComposing) submit();
+        }}
+      />
+      <div className="composer-controls">
+        {session.activity !== "none" ? (
+          <button
+            type="button"
+            className="send-pill stop"
+            title={t("composer.stop")}
+            onClick={() => void session.stop()}
+          >
+            ◼
+          </button>
+        ) : (
+          <button
+            type="button"
+            className="send-pill"
+            title={t("composer.send")}
+            onClick={submit}
+            disabled={
+              draft.trim().length === 0 ||
+              session.agentSendInFlight ||
+              capturePending
+            }
+          >
+            ↑
+          </button>
+        )}
+      </div>
+    </div>
+  );
+
+  // Composer-first: no transcript (and no empty hint) until a
+  // conversation exists — just the pill, hugging the avatar edge. The
+  // hint row (connection/perch problems) stays visible above it.
+  if (variant === "composer") {
+    return (
+      <div className={`chat-popover composer-only anchor-${anchor}`}>
+        {hintRow}
+        {composerBox}
+      </div>
+    );
+  }
+
+  return (
+    <div className="chat-popover">
+      <div className="transcript" ref={scrollRef} onScroll={noteScrollPosition}>
+        {session.messages.length === 0 && (
+          <div className="empty-hint">
+            {pendingName
+              ? t("empty.newChat", { name: pendingName })
+              : session.attached
+                ? t("empty.prompt")
+                : t("empty.waiting")}
+          </div>
+        )}
+        {groupTranscript(session.messages).map((item) =>
+          item.kind === "message" ? (
+            <MessageRow key={item.message.id} message={item.message} />
+          ) : (
+            <ToolRunRow key={item.key} tools={item.tools} />
+          ),
+        )}
+      </div>
+      {hintRow}
+      {composerBox}
+    </div>
+  );
+}
diff --git a/src/features/desktop-agent/ui/DesktopAgentApp.test.tsx b/src/features/desktop-agent/ui/DesktopAgentApp.test.tsx
new file mode 100644
index 000000000..6c1f05128
--- /dev/null
+++ b/src/features/desktop-agent/ui/DesktopAgentApp.test.tsx
@@ -0,0 +1,763 @@
+import {
+  act,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+
+import { setDesktopAgentEnabled } from "@/features/desktop-agent/lib/desktopAgentPreferences";
+import { DesktopAgentApp } from "@/features/desktop-agent/ui/DesktopAgentApp";
+
+const mocks = vi.hoisted(() => ({
+  avatar: {
+    isBerdy: true,
+    choice: {
+      src: "default",
+      id: "default",
+      kind: "video",
+      shape: "circle",
+      label: "Default",
+    },
+  },
+  perch: {
+    phase: "unperched",
+    dismount: vi.fn(),
+    beginTargeting: vi.fn(),
+    endTargetingAndMaybePerch: vi.fn(),
+    cancelTargeting: vi.fn(async () => {}),
+  },
+  port: {
+    restore: vi.fn(async () => {}),
+    onDragStarted: vi.fn(),
+    onDragEnded: vi.fn(),
+    onDragEndedPerched: vi.fn(),
+    mode: "avatar",
+    computeExpanded: vi.fn(),
+    applyExpanded: vi.fn(),
+    computeGrown: vi.fn(),
+    computeMenu: vi.fn(),
+    applyMenu: vi.fn(),
+    collapse: vi.fn(),
+  },
+  agentId: null as string | null,
+  sessionMessages: [] as Array<unknown>,
+  openMenu: vi.fn(),
+  newChat: vi.fn(async () => true),
+  invoke: vi.fn(async () => undefined),
+  avatarProps: {} as Record<string, unknown>,
+}));
+vi.mock("@/features/desktop-agent/lib/panelState", () => ({
+  PanelStateMachine: class {
+    constructor() {
+      Object.assign(this, mocks.port);
+    }
+    get mode() {
+      return mocks.port.mode;
+    }
+    set mode(value: string) {
+      mocks.port.mode = value;
+    }
+  },
+}));
+vi.mock("@/features/desktop-agent/lib/tauriWindowPort", () => ({
+  LocalStoragePositionStore: class {},
+  TauriWindowPort: class {},
+}));
+vi.mock("@/features/desktop-agent/hooks/useAgentAvatar", () => ({
+  useAgentAvatar: () => mocks.avatar,
+}));
+vi.mock("@/features/desktop-agent/hooks/usePerch", () => ({
+  usePerch: () => mocks.perch,
+}));
+vi.mock("@/features/desktop-agent/hooks/useSession", () => ({
+  useSession: () => ({
+    messages: mocks.sessionMessages,
+    pendingSelection: null,
+    activeAgentId: mocks.agentId,
+    attached: true,
+    activity: "idle",
+  }),
+}));
+vi.mock("@/features/desktop-agent/hooks/useAvatarMenu", () => ({
+  useAvatarMenu: () => ({
+    prepareMenu: mocks.openMenu,
+    selectAgent: vi.fn(),
+    selectFresh: vi.fn(),
+    newChat: mocks.newChat,
+  }),
+}));
+vi.mock("@/features/desktop-agent/ui/AgentAvatar", () => ({
+  AgentAvatar: (props: Record<string, unknown>) => {
+    mocks.avatarProps = props;
+    return <span data-testid="avatar" />;
+  },
+}));
+vi.mock("@/features/desktop-agent/ui/ChatPopover", () => ({
+  ChatPopover: (props: Record<string, unknown>) => (
+    <div
+      ref={props.composerRef as React.Ref<HTMLDivElement>}
+      data-testid="chat-popover"
+      data-variant={props.variant as string}
+      data-anchor={props.anchor as string}
+    />
+  ),
+}));
+vi.mock("@/features/experiments/experimentPreferences", () => ({
+  useExperiment: () => ({ enabled: true, config: {} }),
+}));
+vi.mock("@/features/desktop-agent/lib/desktopAgentPreferences", () => ({
+  setDesktopAgentEnabled: vi.fn(),
+}));
+vi.mock("@tauri-apps/api/core", () => ({
+  invoke: mocks.invoke,
+}));
+vi.mock("@tauri-apps/api/event", () => ({
+  listen: vi.fn(async () => vi.fn()),
+}));
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.stubGlobal("PointerEvent", MouseEvent);
+  mocks.agentId = null;
+  mocks.sessionMessages = [];
+  mocks.port.mode = "avatar";
+  mocks.port.computeExpanded.mockResolvedValue({
+    avatarRect: { x: 0, y: 0, width: 94, height: 94 },
+    popoverRect: { x: 94, y: 0, width: 300, height: 400 },
+    windowFrame: { x: 0, y: 0, width: 394, height: 424 },
+    popoverAbove: false,
+    popoverSide: null,
+  });
+  mocks.port.computeGrown.mockResolvedValue({
+    avatarRect: { x: 0, y: 0, width: 94, height: 94 },
+    popoverRect: { x: 94, y: 0, width: 380, height: 520 },
+    windowFrame: { x: 0, y: 0, width: 498, height: 544 },
+    popoverAbove: false,
+    popoverSide: "right",
+  });
+  mocks.port.applyExpanded.mockImplementation(async () => {
+    mocks.port.mode = "expanded";
+  });
+  mocks.port.collapse.mockImplementation(async () => {
+    mocks.port.mode = "avatar";
+  });
+  mocks.avatar.isBerdy = true;
+  mocks.openMenu.mockResolvedValue({
+    agents: [],
+    checkedAgentId: null,
+    checkedFresh: true,
+  });
+  mocks.newChat.mockResolvedValue(true);
+  mocks.port.computeMenu.mockResolvedValue({
+    avatarRect: { x: 42, y: 17, width: 94, height: 94 },
+    popoverRect: { x: 136, y: 17, width: 438, height: 96 },
+    windowFrame: { x: 0, y: 0, width: 574, height: 130 },
+    popoverAbove: false,
+  });
+  mocks.port.applyMenu.mockImplementation(async () => {
+    mocks.port.mode = "menu";
+  });
+  mocks.perch.phase = "unperched";
+  mocks.perch.endTargetingAndMaybePerch.mockResolvedValue(true);
+});
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+it("animates only a positively identified Berdy, and forwards hide and perch state", async () => {
+  const { rerender, findByTestId } = render(<DesktopAgentApp />);
+  await findByTestId("avatar");
+  expect(mocks.avatarProps.character).toBe(true);
+  mocks.avatar.isBerdy = false;
+  rerender(<DesktopAgentApp />);
+  expect(mocks.avatarProps.character).toBe(false);
+  mocks.avatar.isBerdy = true;
+  mocks.perch.phase = "targeting";
+  rerender(<DesktopAgentApp />);
+  expect(mocks.avatarProps.target).toBe("dangle");
+  mocks.perch.phase = "perched";
+  rerender(<DesktopAgentApp />);
+  expect(mocks.avatarProps.target).toBe("sit");
+  // Hidden only flips via the menu's "Turn off agent" turn-off path now (the
+  // separate visible preference is gone).
+  expect(mocks.avatarProps.hidden).toBe(false);
+  mocks.perch.phase = "unperched";
+  rerender(<DesktopAgentApp />);
+  expect(mocks.avatarProps.target).toBe("idle");
+});
+
+it("positions the avatar from menu layout while the menu is open", async () => {
+  const { findByTestId } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+
+  await act(async () => fireEvent.contextMenu(hit));
+
+  expect(mocks.port.applyMenu).toHaveBeenCalledOnce();
+  expect(hit.style.left).toBe("42px");
+  expect(hit.style.top).toBe("17px");
+});
+
+it("ignores a second right-click while menu preparation is in flight", async () => {
+  let resolve!: (value: {
+    agents: [];
+    checkedAgentId: null;
+    checkedFresh: true;
+  }) => void;
+  mocks.openMenu.mockReturnValue(
+    new Promise((r) => {
+      resolve = r;
+    }),
+  );
+  const { findByTestId } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+
+  fireEvent.contextMenu(hit);
+  fireEvent.contextMenu(hit);
+  expect(mocks.openMenu).toHaveBeenCalledOnce();
+
+  await act(async () =>
+    resolve({ agents: [], checkedAgentId: null, checkedFresh: true }),
+  );
+  expect(mocks.port.applyMenu).toHaveBeenCalledOnce();
+});
+
+it("cancels an in-flight menu open when Escape changes generation", async () => {
+  let resolve!: (value: {
+    agents: [];
+    checkedAgentId: null;
+    checkedFresh: true;
+  }) => void;
+  mocks.openMenu.mockReturnValue(
+    new Promise((r) => {
+      resolve = r;
+    }),
+  );
+  const { findByTestId } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+
+  fireEvent.contextMenu(hit);
+  fireEvent.keyDown(window, { key: "Escape" });
+  await act(async () =>
+    resolve({ agents: [], checkedAgentId: null, checkedFresh: true }),
+  );
+
+  expect(mocks.port.computeMenu).not.toHaveBeenCalled();
+  expect(mocks.port.applyMenu).not.toHaveBeenCalled();
+});
+
+it("keyboard opens and closes the avatar menu while preserving focus reachability", async () => {
+  const { findByTestId } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+
+  expect(hit).toHaveAttribute("role", "button");
+  expect(hit).toHaveAttribute("tabindex", "0");
+  hit.focus();
+  expect(document.activeElement).toBe(hit);
+
+  await act(async () => fireEvent.keyDown(hit, { key: "F10", shiftKey: true }));
+  expect(mocks.port.applyMenu).toHaveBeenCalledOnce();
+  expect(hit).toHaveAttribute("aria-haspopup", "menu");
+  expect(hit).toHaveAttribute("aria-expanded", "true");
+  const first = screen.getByRole("menuitem", { name: "Start new chat" });
+  expect(document.activeElement).toBe(first);
+
+  fireEvent.keyDown(window, { key: "ArrowDown" });
+  expect(
+    screen.getByRole("menuitem", { name: "Switch agent ›" }),
+  ).toHaveFocus();
+
+  fireEvent.keyDown(window, { key: "Escape" });
+  await waitFor(() => expect(mocks.port.collapse).toHaveBeenCalledOnce());
+  expect(hit).toHaveFocus();
+});
+
+it("avatar keyboard Enter and Space toggle chat like primary click", async () => {
+  const { findByTestId } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+
+  await act(async () => fireEvent.keyDown(hit, { key: "Enter" }));
+  expect(mocks.port.applyExpanded).toHaveBeenCalledOnce();
+  await act(async () => fireEvent.keyDown(hit, { key: " " }));
+  expect(mocks.port.collapse).toHaveBeenCalledOnce();
+});
+
+it("native drag slop changes target, not DOM position, and drop returns to idle", async () => {
+  // jsdom has no PointerEvent; MouseEvent supplies the coordinates React reads.
+  vi.stubGlobal("PointerEvent", MouseEvent);
+  const { findByTestId } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+  fireEvent.pointerDown(hit, { button: 0, screenX: 10, screenY: 10 });
+  fireEvent.pointerMove(hit, { screenX: 12, screenY: 10 });
+  expect(mocks.avatarProps.target).toBe("idle");
+  fireEvent.pointerMove(hit, { screenX: 15, screenY: 10 });
+  expect(mocks.avatarProps.target).toBe("dangle");
+  expect(mocks.port.onDragStarted).toHaveBeenCalled();
+  expect(hit.style.left).toBe("0px");
+  await act(async () => fireEvent.pointerUp(hit));
+  await waitFor(() => expect(mocks.port.onDragEndedPerched).toHaveBeenCalled());
+  expect(mocks.avatarProps.target).toBe("idle");
+  vi.unstubAllGlobals();
+});
+
+it("a clean pointer-up expands once without the subsequent click collapsing the persistent renderer", async () => {
+  vi.clearAllMocks();
+  mocks.port.computeExpanded.mockResolvedValue({
+    avatarRect: { x: 0, y: 0, width: 94, height: 94 },
+    popoverRect: { x: 94, y: 0, width: 300, height: 400 },
+    windowFrame: { x: 0, y: 0, width: 394, height: 424 },
+    popoverAbove: false,
+    popoverSide: null,
+  });
+  mocks.port.computeGrown.mockResolvedValue({
+    avatarRect: { x: 0, y: 0, width: 94, height: 94 },
+    popoverRect: { x: 94, y: 0, width: 380, height: 520 },
+    windowFrame: { x: 0, y: 0, width: 498, height: 544 },
+    popoverAbove: false,
+    popoverSide: "right",
+  });
+  vi.stubGlobal("PointerEvent", MouseEvent);
+  const { findByTestId } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+  fireEvent.pointerDown(hit, { button: 0, screenX: 10, screenY: 10 });
+  await act(async () => fireEvent.pointerUp(hit));
+  fireEvent.click(hit);
+  expect(mocks.port.applyExpanded).toHaveBeenCalledOnce();
+  expect(mocks.port.collapse).not.toHaveBeenCalled();
+  expect(mocks.port.onDragStarted).not.toHaveBeenCalled();
+  vi.unstubAllGlobals();
+});
+
+it("expanded avatar collapses only on a primary click, not pointer-up or context/auxiliary clicks", async () => {
+  const { findByTestId } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+  fireEvent.pointerDown(hit, { button: 0 });
+  await act(async () => fireEvent.pointerUp(hit));
+  fireEvent.click(hit); // trailing click from the expansion gesture
+  expect(mocks.port.mode).toBe("expanded");
+  expect(mocks.port.collapse).not.toHaveBeenCalled();
+
+  for (const button of [1, 2]) {
+    fireEvent.pointerDown(hit, { button });
+    fireEvent.pointerUp(hit, { button });
+    fireEvent.click(hit, { button });
+  }
+  fireEvent.pointerDown(document.body, { button: 0 });
+  fireEvent.pointerUp(hit, { button: 0 });
+  expect(mocks.port.collapse).not.toHaveBeenCalled();
+
+  fireEvent.pointerDown(hit, { button: 0 });
+  fireEvent.pointerUp(hit, { button: 0 });
+  expect(mocks.port.collapse).not.toHaveBeenCalled();
+  await act(async () => fireEvent.click(hit, { button: 0 }));
+  expect(mocks.port.collapse).toHaveBeenCalledOnce();
+});
+
+it.each([
+  true,
+  false,
+])("keeps dangle until async drop resolves (perched=%s)", async (perched) => {
+  let resolveDrop!: (value: boolean) => void;
+  mocks.perch.endTargetingAndMaybePerch.mockReturnValue(
+    new Promise<boolean>((resolve) => {
+      resolveDrop = resolve;
+    }),
+  );
+  const { findByTestId, rerender } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+  fireEvent.pointerDown(hit, { button: 0, screenX: 10, screenY: 10 });
+  fireEvent.pointerMove(hit, { screenX: 15, screenY: 10 });
+  fireEvent.pointerUp(hit);
+  expect(mocks.avatarProps.target).toBe("dangle");
+  // Native targeting itself also keeps the route dangling, even after up.
+  mocks.perch.phase = "targeting";
+  rerender(<DesktopAgentApp />);
+  expect(mocks.avatarProps.target).toBe("dangle");
+  expect(mocks.port.onDragEnded).not.toHaveBeenCalled();
+  expect(mocks.port.onDragEndedPerched).not.toHaveBeenCalled();
+  await act(async () => {
+    mocks.perch.phase = perched ? "perched" : "unperched";
+    resolveDrop(perched);
+  });
+  expect(mocks.avatarProps.target).toBe(perched ? "sit" : "idle");
+  expect(
+    perched ? mocks.port.onDragEndedPerched : mocks.port.onDragEnded,
+  ).toHaveBeenCalledOnce();
+});
+
+async function pressFixture() {
+  const view = render(<DesktopAgentApp />);
+  const hit = (await view.findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+  vi.useFakeTimers();
+  hit.setPointerCapture = vi.fn();
+  hit.hasPointerCapture = vi.fn(() => true);
+  hit.releasePointerCapture = vi.fn();
+  return { ...view, hit };
+}
+
+it.each([
+  "unperched",
+  "perched",
+])("stationary hold at 180ms is visual only (%s) and release never opens chat", async (phase) => {
+  mocks.perch.phase = phase;
+  const { hit, unmount } = await pressFixture();
+  fireEvent.pointerDown(hit, { button: 0 });
+  act(() => vi.advanceTimersByTime(179));
+  expect(mocks.avatarProps.target).toBe(phase === "perched" ? "sit" : "idle");
+  act(() => vi.advanceTimersByTime(1));
+  expect(mocks.avatarProps.target).toBe("dangle");
+  expect(hit.setPointerCapture).toHaveBeenCalledOnce();
+  expect(mocks.port.onDragStarted).not.toHaveBeenCalled();
+  expect(mocks.perch.beginTargeting).not.toHaveBeenCalled();
+  expect(mocks.perch.dismount).not.toHaveBeenCalled();
+  await act(async () => fireEvent.pointerUp(hit, { button: 0 }));
+  fireEvent.click(hit);
+  expect(hit.releasePointerCapture).toHaveBeenCalledOnce();
+  expect(mocks.avatarProps.target).toBe(phase === "perched" ? "sit" : "idle");
+  expect(mocks.port.computeExpanded).not.toHaveBeenCalled();
+  expect(mocks.perch.endTargetingAndMaybePerch).not.toHaveBeenCalled();
+  unmount();
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+it("quick clicks clear their hold timer, and expanded presses never hold", async () => {
+  const { hit, unmount } = await pressFixture();
+  fireEvent.pointerDown(hit, { button: 0 });
+  act(() => vi.advanceTimersByTime(179));
+  await act(async () => fireEvent.pointerUp(hit, { button: 0 }));
+  fireEvent.click(hit);
+  act(() => vi.advanceTimersByTime(500));
+  expect(mocks.avatarProps.target).toBe("idle");
+  expect(mocks.port.applyExpanded).toHaveBeenCalledOnce();
+  fireEvent.pointerDown(hit, { button: 0 });
+  act(() => vi.advanceTimersByTime(500));
+  expect(mocks.avatarProps.target).toBe("idle");
+  fireEvent.pointerUp(hit, { button: 0 });
+  await act(async () => fireEvent.click(hit));
+  expect(mocks.port.collapse).toHaveBeenCalledOnce();
+  unmount();
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+it.each([
+  "cancel",
+  "lostcapture",
+  "identity",
+  "unmount",
+  "visibility",
+])("clears holds on %s without stale timer or native attach", async (reason) => {
+  const { hit, rerender, unmount } = await pressFixture();
+  fireEvent.pointerDown(hit, { button: 0 });
+  act(() => vi.advanceTimersByTime(90));
+  if (reason === "cancel") fireEvent.pointerCancel(hit);
+  if (reason === "lostcapture") fireEvent.lostPointerCapture(hit);
+  if (reason === "identity") {
+    mocks.agentId = "other";
+    rerender(<DesktopAgentApp />);
+  }
+  if (reason === "visibility") {
+    const visibility = vi
+      .spyOn(document, "visibilityState", "get")
+      .mockReturnValue("hidden");
+    fireEvent(document, new Event("visibilitychange"));
+    visibility.mockRestore();
+  }
+  if (reason === "unmount") unmount();
+  act(() => vi.advanceTimersByTime(500));
+  expect(mocks.avatarProps.target).toBe("idle");
+  fireEvent.pointerUp(hit, { button: 0 });
+  expect(mocks.port.computeExpanded).not.toHaveBeenCalled();
+  expect(mocks.perch.endTargetingAndMaybePerch).not.toHaveBeenCalled();
+  unmount();
+  expect(vi.getTimerCount()).toBe(0);
+});
+
+it("ignores auxiliary holds and preserves the context menu", async () => {
+  const { hit, unmount } = await pressFixture();
+  for (const button of [1, 2]) {
+    fireEvent.pointerDown(hit, { button });
+    act(() => vi.advanceTimersByTime(500));
+    fireEvent.pointerUp(hit, { button });
+  }
+  await act(async () => {
+    fireEvent.contextMenu(hit);
+  });
+  expect(mocks.openMenu).toHaveBeenCalledOnce();
+  expect(mocks.avatarProps.target).toBe("idle");
+  expect(mocks.port.computeExpanded).not.toHaveBeenCalled();
+  expect(mocks.port.onDragStarted).not.toHaveBeenCalled();
+  unmount();
+});
+
+it("native drag starts before hold threshold; cancellation stops targeting without a drop", async () => {
+  const { hit, unmount } = await pressFixture();
+  fireEvent.pointerDown(hit, { button: 0, screenX: 0, screenY: 0 });
+  fireEvent.pointerMove(hit, { screenX: 4, screenY: 0 });
+  expect(mocks.avatarProps.target).toBe("dangle");
+  expect(mocks.port.onDragStarted).toHaveBeenCalledOnce();
+  expect(vi.getTimerCount()).toBe(0);
+  await act(async () => fireEvent.pointerCancel(hit));
+  expect(mocks.perch.cancelTargeting).toHaveBeenCalledOnce();
+  expect(mocks.perch.endTargetingAndMaybePerch).not.toHaveBeenCalled();
+  expect(mocks.avatarProps.target).toBe("idle");
+  unmount();
+});
+
+it("an old async drop cannot clear a regrab hold or start overlapping native drags", async () => {
+  let finish!: (value: boolean) => void;
+  mocks.perch.endTargetingAndMaybePerch.mockReturnValue(
+    new Promise<boolean>((resolve) => {
+      finish = resolve;
+    }),
+  );
+  const { hit, unmount } = await pressFixture();
+  fireEvent.pointerDown(hit, { button: 0, screenX: 0, screenY: 0 });
+  fireEvent.pointerMove(hit, { screenX: 4, screenY: 0 });
+  fireEvent.pointerUp(hit, { button: 0 });
+  fireEvent.pointerDown(hit, { button: 0, screenX: 0, screenY: 0 });
+  fireEvent.pointerMove(hit, { screenX: 4, screenY: 0 });
+  expect(mocks.port.onDragStarted).toHaveBeenCalledOnce();
+  act(() => vi.advanceTimersByTime(180));
+  await act(async () => finish(false));
+  expect(mocks.avatarProps.target).toBe("dangle");
+  await act(async () => fireEvent.pointerUp(hit, { button: 0 }));
+  expect(mocks.avatarProps.target).toBe("idle");
+  expect(mocks.port.computeExpanded).not.toHaveBeenCalled();
+  unmount();
+});
+
+it("native handoff capture loss preserves drag until pointer-up", async () => {
+  const { hit, unmount } = await pressFixture();
+  fireEvent.pointerDown(hit, { button: 0, screenX: 0, screenY: 0 });
+  fireEvent.pointerMove(hit, { screenX: 4, screenY: 0 });
+  fireEvent.lostPointerCapture(hit);
+  expect(mocks.perch.cancelTargeting).not.toHaveBeenCalled();
+  expect(mocks.avatarProps.target).toBe("dangle");
+  await act(async () => fireEvent.pointerUp(hit, { button: 0 }));
+  expect(mocks.perch.endTargetingAndMaybePerch).toHaveBeenCalledOnce();
+  expect(mocks.port.onDragEndedPerched).toHaveBeenCalledOnce();
+  expect(mocks.port.computeExpanded).not.toHaveBeenCalled();
+  unmount();
+});
+
+it("cancelling a pending drop prevents stale placement and keeps a new hold intact", async () => {
+  let finish!: (value: boolean) => void;
+  mocks.perch.endTargetingAndMaybePerch.mockReturnValue(
+    new Promise<boolean>((resolve) => {
+      finish = resolve;
+    }),
+  );
+  const { hit, rerender, unmount } = await pressFixture();
+  fireEvent.pointerDown(hit, { button: 0, screenX: 0, screenY: 0 });
+  fireEvent.pointerMove(hit, { screenX: 4, screenY: 0 });
+  fireEvent.pointerUp(hit, { button: 0 });
+  mocks.agentId = "other";
+  rerender(<DesktopAgentApp />);
+  expect(mocks.perch.cancelTargeting).toHaveBeenCalledOnce();
+  fireEvent.pointerDown(hit, { button: 0 });
+  act(() => vi.advanceTimersByTime(180));
+  await act(async () => finish(true));
+  expect(mocks.port.onDragEndedPerched).not.toHaveBeenCalled();
+  expect(mocks.port.onDragEnded).not.toHaveBeenCalled();
+  expect(mocks.avatarProps.target).toBe("dangle");
+  await act(async () => fireEvent.pointerUp(hit, { button: 0 }));
+  expect(mocks.avatarProps.target).toBe("idle");
+  expect(mocks.port.computeExpanded).not.toHaveBeenCalled();
+  unmount();
+});
+
+it("growing after first send uses the grown path for a side-placed composer", async () => {
+  const composerLayout = {
+    avatarRect: { x: 0, y: 0, width: 94, height: 94 },
+    popoverRect: { x: 118, y: 24, width: 380, height: 96 },
+    windowFrame: { x: 10, y: 20, width: 512, height: 144 },
+    popoverAbove: false,
+    popoverSide: "right" as const,
+  };
+  const grownLayout = {
+    avatarRect: { x: 0, y: 420, width: 94, height: 94 },
+    popoverRect: { x: 118, y: 0, width: 380, height: 520 },
+    windowFrame: { x: 10, y: -380, width: 512, height: 544 },
+    popoverAbove: false,
+    popoverSide: "right" as const,
+  };
+  mocks.port.computeExpanded.mockResolvedValue(composerLayout);
+  mocks.port.computeGrown.mockResolvedValue(grownLayout);
+
+  const { findByTestId, rerender } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+  await act(async () => {
+    fireEvent.pointerDown(hit, { button: 0, screenX: 10, screenY: 10 });
+    fireEvent.pointerUp(hit, { button: 0 });
+  });
+  const popover = await findByTestId("chat-popover");
+  Object.defineProperty(popover, "getBoundingClientRect", {
+    configurable: true,
+    value: () => ({ bottom: 96 }),
+  });
+  popover.style.setProperty("--desktop-agent-panel-padding", "16px");
+  mocks.sessionMessages = [{ id: "m1" }];
+
+  await act(async () => rerender(<DesktopAgentApp />));
+
+  expect(mocks.port.computeGrown).toHaveBeenCalledWith({
+    fromPopoverGlobal: { x: 128, y: 44, width: 380, height: 96 },
+    composerBottomGlobal: 116,
+    bottomInset: 16,
+    fromPopoverSide: "right",
+  });
+  expect(mocks.port.applyExpanded).toHaveBeenLastCalledWith(grownLayout);
+});
+
+it("activating Turn off agent disables the setting and closes the panel", async () => {
+  const { findByTestId, findByRole } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+
+  await act(async () => fireEvent.contextMenu(hit));
+  const turnOff = await findByRole("menuitem", { name: "Turn off agent" });
+  await act(async () => fireEvent.click(turnOff));
+
+  expect(turnOff).toHaveTextContent("Turn off agent");
+  expect(setDesktopAgentEnabled).toHaveBeenCalledWith(false);
+  expect(mocks.invoke).toHaveBeenCalledWith("desktop_agent_close");
+  expect(mocks.avatarProps.hidden).toBe(true);
+});
+
+it("choosing Start new chat closes the menu and expands composer-only on the side", async () => {
+  mocks.sessionMessages = [{ id: "m1" }];
+  mocks.newChat.mockImplementation(async () => {
+    mocks.sessionMessages = [];
+    return true;
+  });
+  const { findByTestId, findByText } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+
+  await act(async () => fireEvent.contextMenu(hit));
+  const newChat = await findByText("Start new chat");
+  await act(async () => fireEvent.click(newChat));
+
+  expect(mocks.newChat).toHaveBeenCalledWith(1);
+  expect(mocks.port.collapse).toHaveBeenCalledOnce();
+  expect(mocks.port.computeExpanded).toHaveBeenCalledWith(
+    { width: 380, height: 96 },
+    "side",
+  );
+  expect(mocks.port.applyExpanded).toHaveBeenCalledOnce();
+  expect(await findByTestId("chat-popover")).toHaveAttribute(
+    "data-variant",
+    "composer",
+  );
+});
+
+it("opening an existing chat places the full window beside the avatar, composer level with the bubble", async () => {
+  const bubbleLayout = {
+    avatarRect: { x: 0, y: 0, width: 94, height: 94 },
+    popoverRect: { x: 118, y: 24, width: 380, height: 96 },
+    windowFrame: { x: 10, y: 20, width: 512, height: 144 },
+    popoverAbove: false,
+    popoverSide: "right" as const,
+  };
+  const fullLayout = {
+    avatarRect: { x: 0, y: 420, width: 94, height: 94 },
+    popoverRect: { x: 118, y: 0, width: 380, height: 520 },
+    windowFrame: { x: 10, y: -380, width: 512, height: 544 },
+    popoverAbove: false,
+    popoverSide: "right" as const,
+  };
+  mocks.sessionMessages = [{ id: "m1" }];
+  mocks.port.computeExpanded.mockResolvedValue(bubbleLayout);
+  mocks.port.computeGrown.mockResolvedValue(fullLayout);
+
+  const { findByTestId } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+  await act(async () => {
+    fireEvent.pointerDown(hit, { button: 0, screenX: 10, screenY: 10 });
+    fireEvent.pointerUp(hit, { button: 0 });
+  });
+
+  expect(mocks.port.computeExpanded).toHaveBeenCalledWith(
+    { width: 380, height: 96 },
+    "side",
+  );
+  // Bubble center line = 20 + 24 + 48 = 92; composer-only pill bottom = 92 + 23.
+  expect(mocks.port.computeGrown).toHaveBeenCalledWith({
+    fromPopoverGlobal: { x: 128, y: 44, width: 380, height: 96 },
+    composerBottomGlobal: 115,
+    bottomInset: 16,
+    fromPopoverSide: "right",
+  });
+  expect(mocks.port.applyExpanded).toHaveBeenLastCalledWith(fullLayout);
+});
+
+it("reopen and grow use the same composer bottom for the same no-hint bubble layout", async () => {
+  const bubbleLayout = {
+    avatarRect: { x: 0, y: 0, width: 94, height: 94 },
+    popoverRect: { x: 118, y: 24, width: 380, height: 96 },
+    windowFrame: { x: 10, y: 20, width: 512, height: 144 },
+    popoverAbove: false,
+    popoverSide: "right" as const,
+  };
+  const fullLayout = {
+    avatarRect: { x: 0, y: 420, width: 94, height: 94 },
+    popoverRect: { x: 118, y: 0, width: 380, height: 520 },
+    windowFrame: { x: 10, y: -380, width: 512, height: 544 },
+    popoverAbove: false,
+    popoverSide: "right" as const,
+  };
+  mocks.port.computeExpanded.mockResolvedValue(bubbleLayout);
+  mocks.port.computeGrown.mockResolvedValue(fullLayout);
+  mocks.sessionMessages = [];
+
+  const { findByTestId, rerender, unmount } = render(<DesktopAgentApp />);
+  const hit = (await findByTestId("avatar")).parentElement;
+  if (!hit) throw new Error("missing hit target");
+  await act(async () => {
+    fireEvent.pointerDown(hit, { button: 0, screenX: 10, screenY: 10 });
+    fireEvent.pointerUp(hit, { button: 0 });
+  });
+  const popover = await findByTestId("chat-popover");
+  Object.defineProperty(popover, "getBoundingClientRect", {
+    configurable: true,
+    value: () => ({ bottom: 95 }),
+  });
+  popover.style.setProperty("--desktop-agent-panel-padding", "16px");
+  mocks.sessionMessages = [{ id: "m1" }];
+
+  await act(async () => rerender(<DesktopAgentApp />));
+  const growBottom =
+    mocks.port.computeGrown.mock.calls.at(-1)?.[0].composerBottomGlobal;
+
+  unmount();
+  vi.clearAllMocks();
+  mocks.port.mode = "avatar";
+  mocks.sessionMessages = [{ id: "m1" }];
+  mocks.port.computeExpanded.mockResolvedValue(bubbleLayout);
+  mocks.port.computeGrown.mockResolvedValue(fullLayout);
+
+  const { findByTestId: findReopened } = render(<DesktopAgentApp />);
+  const reopenHit = (await findReopened("avatar")).parentElement;
+  if (!reopenHit) throw new Error("missing hit target");
+  await act(async () => {
+    fireEvent.pointerDown(reopenHit, { button: 0, screenX: 10, screenY: 10 });
+    fireEvent.pointerUp(reopenHit, { button: 0 });
+  });
+  const reopenBottom =
+    mocks.port.computeGrown.mock.calls.at(-1)?.[0].composerBottomGlobal;
+
+  expect(reopenBottom).toBe(growBottom);
+  expect(reopenBottom).toBe(115);
+});
diff --git a/src/features/desktop-agent/ui/DesktopAgentApp.tsx b/src/features/desktop-agent/ui/DesktopAgentApp.tsx
new file mode 100644
index 000000000..be29ddb70
--- /dev/null
+++ b/src/features/desktop-agent/ui/DesktopAgentApp.tsx
@@ -0,0 +1,751 @@
+// Desktop-agent webview shell: animated avatar, popover chat, native
+// panel geometry, the right-click agent menu, and the perch
+// choreography (targeting rides the avatar drag; the drop decision
+// lands at pointer-up). The Rust side (src-tauri/src/desktop_agent)
+// owns the AppKit seams; this component composes the UI state machines
+// and keeps the transparent panel window honest.
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+import { useTranslation } from "react-i18next";
+
+import { DESKTOP_AGENT_AGENT_SELECTOR_EXPERIMENT_ID } from "@/features/experiments/experimentDefinitions";
+import { useExperiment } from "@/features/experiments/experimentPreferences";
+
+import {
+  popoverGlobal,
+  type ExpandedLayout,
+  type Size,
+} from "../lib/anchorGeometry";
+import { deriveAvatarState } from "../lib/avatarState";
+import { setDesktopAgentEnabled } from "../lib/desktopAgentPreferences";
+import { PanelStateMachine } from "../lib/panelState";
+import {
+  LocalStoragePositionStore,
+  TauriWindowPort,
+} from "../lib/tauriWindowPort";
+import { useAgentAvatar } from "../hooks/useAgentAvatar";
+import { useAvatarMenu, type AvatarMenuModel } from "../hooks/useAvatarMenu";
+import { usePerch } from "../hooks/usePerch";
+import { useSession } from "../hooks/useSession";
+import { AgentAvatar } from "./AgentAvatar";
+import { AvatarMenu, menuOverlaySize } from "./AvatarMenu";
+import { ChatPopover } from "./ChatPopover";
+import "./desktop-agent.css";
+
+// Distinguish an intentional stationary hold from an ordinary chat click.
+const HOLD_DELAY_MS = 180;
+
+// Composer-first: a chat with no messages opens as just the composer
+// pill — room for the pill plus the hint row when one is relevant.
+const COMPOSER_ONLY_SIZE: Size = { width: 380, height: 96 };
+// Composer-only bubble pill height (desktop-agent.css:
+// .composer-only .composer-box padding 9px around the 26px send pill,
+// plus 1px border ×2). Used before the DOM exists to measure the pill.
+export const BUBBLE_PILL_HEIGHT = 46;
+const FULL_PANEL_PADDING = 16;
+
+export function bubbleComposerBottomGlobal(layout: ExpandedLayout): number {
+  return (
+    layout.windowFrame.y +
+    layout.popoverRect.y +
+    layout.popoverRect.height / 2 +
+    BUBBLE_PILL_HEIGHT / 2
+  );
+}
+
+function readComposerBottomInset(popover: HTMLElement, composer: HTMLElement) {
+  // Measured while still in composer mode, where .panel-popover's padding
+  // is 0 — so read the FULL layout's padding from the shared custom
+  // property (desktop-agent.css #root), not the current computed padding.
+  const padding = Number.parseFloat(
+    getComputedStyle(popover).getPropertyValue("--desktop-agent-panel-padding"),
+  );
+  const margin = Number.parseFloat(getComputedStyle(composer).marginBottom);
+  return (
+    (Number.isFinite(padding) ? padding : 16) +
+    (Number.isFinite(margin) ? margin : 0)
+  );
+}
+
+const machine = new PanelStateMachine({
+  window: new TauriWindowPort(),
+  positionStore: new LocalStoragePositionStore(),
+});
+
+export function DesktopAgentApp() {
+  const { t } = useTranslation("desktop-agent");
+  const session = useSession();
+  const agentSelector =
+    useExperiment(DESKTOP_AGENT_AGENT_SELECTOR_EXPERIMENT_ID)?.enabled === true;
+  // Set when "Turn off agent" has fired: the enabled-pref write is in flight
+  // to the main webview's bridge (which closes the panel); meanwhile the
+  // panel must already look gone.
+  const [turnedOff, setTurnedOff] = useState(false);
+  const avatarAgentId =
+    session.pendingSelection !== null
+      ? session.pendingSelection.kind === "agent"
+        ? session.pendingSelection.agent.agentId
+        : null
+      : session.activeAgentId;
+  const avatar = useAgentAvatar(avatarAgentId);
+  // Berdy is always the animated character; other agents keep their
+  // avatars.
+  const character = avatar.isBerdy;
+  const [dragActive, setDragActive] = useState(false);
+  const [holdActive, setHoldActive] = useState(false);
+  // Perch ended natively. Reason decides placement: window CLOSED →
+  // avatar flies home to the saved free position; window MINIMIZED →
+  // auto-unperch but the avatar STAYS where it was seated (syncing the
+  // frame so panelState owns the spot without saving it as home).
+  // Dismounts and drag-offs do NOT route through this — they own their
+  // own placement.
+  const perch = usePerch((reason) => {
+    if (reason === "minimized") {
+      void machine.syncFromPanel();
+    } else {
+      void machine.returnToSavedPosition();
+    }
+  }, character);
+  const [layout, setLayout] = useState<ExpandedLayout | null>(null);
+  const [lastAvatarRect, setLastAvatarRect] = useState<
+    ExpandedLayout["avatarRect"] | null
+  >(null);
+  const [expandedApplied, setExpandedApplied] = useState(0);
+  // Composer-first: "composer" until the chat has messages, then "full".
+  const [popoverVariant, setPopoverVariant] = useState<"composer" | "full">(
+    "full",
+  );
+  const [menu, setMenu] = useState<{
+    layout: ExpandedLayout;
+    model: AvatarMenuModel;
+  } | null>(null);
+  const [hovering, setHovering] = useState(false);
+  const [restored, setRestored] = useState(false);
+  const collapsing = useRef(false);
+  const closingMenu = useRef(false);
+  const openingMenu = useRef(false);
+  const dragging = useRef(false);
+  const ignoreNextClick = useRef(false);
+  const avatarTriggerRef = useRef<HTMLDivElement>(null);
+  const pointerDownAt = useRef<{
+    x: number;
+    y: number;
+    id: number;
+    element: Element;
+    held: boolean;
+  } | null>(null);
+  const holdTimer = useRef<number | null>(null);
+  // Do not overlap native hit-test/attach and a second native drag. A regrab
+  // may still hold immediately; its next move can drag once the drop settles.
+  const dropPending = useRef(false);
+  const gestureGeneration = useRef(0);
+  const sessionMessageCount = useRef(session.messages.length);
+  sessionMessageCount.current = session.messages.length;
+
+  const clearHoldTimer = useCallback(() => {
+    if (holdTimer.current !== null) window.clearTimeout(holdTimer.current);
+    holdTimer.current = null;
+  }, []);
+
+  const clearPress = useCallback(() => {
+    clearHoldTimer();
+    const press = pointerDownAt.current;
+    pointerDownAt.current = null;
+    setHoldActive(false);
+    // Clear the ref first: releasing capture can synchronously send lostcapture.
+    if (press?.element.hasPointerCapture?.(press.id)) {
+      press.element.releasePointerCapture(press.id);
+    }
+  }, [clearHoldTimer]);
+
+  // Startup: restore persisted position (clamped) before showing anything.
+  useEffect(() => {
+    machine.restore().then(() => setRestored(true));
+  }, []);
+
+  const collapse = useCallback(async () => {
+    gestureGeneration.current++;
+    if (collapsing.current || machine.mode !== "expanded") return;
+    collapsing.current = true;
+    try {
+      // Anti-blink: drop the popover from the tree BEFORE the native
+      // shrink, so the resize repaint never shows a stale popover.
+      if (layout) setLastAvatarRect(layout.avatarRect);
+      setLayout(null);
+      await machine.collapse();
+      setLastAvatarRect(null);
+    } finally {
+      collapsing.current = false;
+    }
+  }, [layout]);
+
+  const expand = useCallback(async (options?: { composerOnly?: boolean }) => {
+    if (openingMenu.current || machine.mode !== "avatar") return;
+    const generation = ++gestureGeneration.current;
+    // Composer-first: an empty chat (nothing to show, including reopen
+    // of a still-empty chat) opens as just the composer pill; a chat
+    // with messages opens as the full window. New Chat forces the
+    // composer-only view before React lands the cleared transcript.
+    const composerOnly =
+      options?.composerOnly ?? sessionMessageCount.current === 0;
+    // Anti-blink: compute first, commit to the tree, THEN resize native.
+    // Both variants sit BESIDE the avatar like a speech bubble. The full
+    // chat is laid out as if grown from the composer bubble: its composer
+    // is level with where the bubble's pill would be, transcript above —
+    // so reopening an existing chat matches the grow-in-place geometry.
+    const bubble = await machine.computeExpanded(COMPOSER_ONLY_SIZE, "side");
+    let next = bubble;
+    if (!composerOnly) {
+      next =
+        bubble.popoverSide === null
+          ? await machine.computeExpanded() // no side room: above/below
+          : await machine.computeGrown({
+              fromPopoverGlobal: popoverGlobal(bubble),
+              // The bubble's pill is vertically centered in its region
+              // (anchor-center); align the full composer bottom to that
+              // measured composer-only pill bottom, ignoring the hint row.
+              composerBottomGlobal: bubbleComposerBottomGlobal(bubble),
+              bottomInset: FULL_PANEL_PADDING,
+              fromPopoverSide: bubble.popoverSide,
+            });
+    }
+    if (generation !== gestureGeneration.current || machine.mode !== "avatar") {
+      return;
+    }
+    setPopoverVariant(composerOnly ? "composer" : "full");
+    setLayout(next);
+    await machine.applyExpanded(next);
+    setExpandedApplied((count) => count + 1);
+  }, []);
+
+  // First message sent while composer-only: grow to the full chat window
+  // through the same anti-blink path (compute, commit to tree, THEN
+  // native resize — the avatar stays put).
+  const popoverElement = useRef<HTMLDivElement>(null);
+  const composerElement = useRef<HTMLDivElement>(null);
+  const growing = useRef(false);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: expandedApplied retries when the first message arrives before applyExpanded flips native mode.
+  useEffect(() => {
+    if (
+      layout === null ||
+      popoverVariant !== "composer" ||
+      session.messages.length === 0 ||
+      growing.current
+    )
+      return;
+    growing.current = true;
+    void (async () => {
+      try {
+        if (machine.mode !== "expanded") return;
+        const generation = gestureGeneration.current;
+        const fromPopoverSide = layout.popoverSide;
+        const popover = popoverElement.current;
+        const composer = composerElement.current;
+        const next =
+          fromPopoverSide !== null && popover && composer
+            ? await machine.computeGrown({
+                fromPopoverGlobal: {
+                  ...popoverGlobal(layout),
+                },
+                composerBottomGlobal:
+                  layout.windowFrame.y +
+                  composer.getBoundingClientRect().bottom,
+                bottomInset: readComposerBottomInset(popover, composer),
+                fromPopoverSide,
+              })
+            : await machine.computeExpanded();
+        if (
+          generation !== gestureGeneration.current ||
+          machine.mode !== "expanded"
+        ) {
+          return;
+        }
+        setPopoverVariant("full");
+        setLayout(next);
+        await machine.applyExpanded(next);
+        setExpandedApplied((count) => count + 1);
+      } finally {
+        growing.current = false;
+      }
+    })();
+  }, [layout, popoverVariant, session.messages.length, expandedApplied]);
+
+  const closeMenu = useCallback(
+    async (options?: { restoreAvatarFocus?: boolean }) => {
+      gestureGeneration.current++;
+      if (closingMenu.current || machine.mode !== "menu") {
+        if (options?.restoreAvatarFocus) avatarTriggerRef.current?.focus();
+        return;
+      }
+      closingMenu.current = true;
+      try {
+        // Anti-blink, in reverse: drop the menu from the tree first.
+        if (menu) setLastAvatarRect(menu.layout.avatarRect);
+        setMenu(null);
+        await machine.collapse();
+        setLastAvatarRect(null);
+        if (options?.restoreAvatarFocus) avatarTriggerRef.current?.focus();
+      } finally {
+        closingMenu.current = false;
+      }
+    },
+    [menu],
+  );
+
+  // "Turn off agent" = the Desktop Agent setting goes OFF (one on/off state;
+  // the old separate hide-without-disabling preference is gone). The
+  // localStorage write reaches the main webview's bridge via the storage
+  // event and the bridge destroys the panel. The local turnedOff state
+  // hides the avatar immediately while that close is in flight.
+  const turnOff = useCallback(() => {
+    gestureGeneration.current++;
+    clearPress();
+    if (machine.mode === "expanded") void collapse();
+    if (machine.mode === "menu") void closeMenu();
+    setTurnedOff(true);
+    setDesktopAgentEnabled(false);
+    void invoke("desktop_agent_close").catch(() => undefined);
+  }, [clearPress, collapse, closeMenu]);
+
+  // Right-click menu data/selection semantics (geometry is handled here
+  // in openMenu/closeMenu): pick an agent for the NEXT chat (selection
+  // creates nothing — deferred create on first send). Selection only
+  // swaps the avatar; the popover stays closed until the user opens it.
+  const avatarMenu = useAvatarMenu({
+    pendingSelection: session.pendingSelection,
+    activeAgentId: session.activeAgentId,
+    select: session.select,
+    agentSelector,
+  });
+
+  // Opens the custom webview menu: the collapsed window is avatar-sized,
+  // so the panel grows first ("menu" mode — same anti-blink sequencing
+  // as expand). Right-clicking while the chat is expanded CLOSES THE
+  // CHAT FIRST and opens the menu from the collapsed state — the
+  // simplest robust option (one grown-window layout at a time; no
+  // menu-inside-chat z-order or geometry union to reason about).
+  const openMenu = useCallback(async () => {
+    if (openingMenu.current || machine.mode === "menu") return;
+    if (machine.mode === "expanded") await collapse();
+    if (machine.mode !== "avatar") return;
+    const generation = ++gestureGeneration.current;
+    openingMenu.current = true;
+    try {
+      const valid = () =>
+        machine.mode === "avatar" &&
+        generation === gestureGeneration.current &&
+        !dropPending.current &&
+        !dragging.current &&
+        pointerDownAt.current === null;
+      if (!valid()) return;
+      const model = await avatarMenu.prepareMenu();
+      if (!valid()) return;
+      const size = menuOverlaySize({
+        agentSelector,
+        agentCount: model.agents.length,
+      });
+      const next = await machine.computeMenu(size);
+      if (!valid()) return;
+      setMenu({ layout: next, model });
+      await machine.applyMenu(next);
+    } finally {
+      openingMenu.current = false;
+    }
+  }, [agentSelector, avatarMenu, collapse]);
+
+  // Native perch follow refuses to resize an expanded/menu panel down to
+  // avatar size; collapse first so the next tick can reseat safely.
+  useEffect(() => {
+    const unlisten = listen("desktop-agent:perch-moved", () => {
+      gestureGeneration.current++;
+      void closeMenu();
+      void collapse();
+    });
+    return () => {
+      void unlisten.then((fn) => fn());
+    };
+  }, [collapse, closeMenu]);
+
+  // Key-loss while expanded = click outside -> collapse (menu included).
+  useEffect(() => {
+    const unlisten = listen<boolean>("desktop-agent:key-status", (event) => {
+      // A late key-loss from openMenu's own collapse (or one landing while
+      // already collapsed) must not cancel the menu that is opening.
+      if (!event.payload) {
+        if (machine.mode === "avatar" || openingMenu.current) return;
+        gestureGeneration.current++;
+        void closeMenu();
+        void collapse();
+      }
+    });
+    return () => {
+      void unlisten.then((fn) => fn());
+    };
+  }, [collapse, closeMenu]);
+
+  // Esc closes the menu or collapses the popover.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return;
+      gestureGeneration.current++;
+      void closeMenu();
+      void collapse();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [collapse, closeMenu]);
+
+  // Global-shortcut toggle event from Rust (the registry-bound chord).
+  // Only live while the panel exists (= setting enabled): hiding IS
+  // disabling now, so there is no hidden-but-running panel.
+  useEffect(() => {
+    const unlisten = listen("desktop-agent:toggle-panel", () => {
+      gestureGeneration.current++;
+      if (machine.mode === "menu") void closeMenu();
+      else if (machine.mode === "expanded") void collapse();
+      else void expand();
+    });
+    return () => {
+      void unlisten.then((fn) => fn());
+    };
+  }, [collapse, closeMenu, expand]);
+
+  // Display connect/disconnect/rearrange: re-clamp the avatar onto a
+  // visible screen (a disconnected display must not strand the panel).
+  // Perched avatars are exempt — native perch placement owns the panel,
+  // and the follow loop reconciles against the (possibly moved) window
+  // on its next tick.
+  useEffect(() => {
+    const unlisten = listen("desktop-agent:screens-changed", () => {
+      if (machine.mode === "avatar" && perch.phase === "unperched") {
+        void machine.returnToSavedPosition();
+      }
+    });
+    return () => {
+      void unlisten.then((fn) => fn());
+    };
+  }, [perch.phase]);
+
+  const cancelPress = useCallback(() => {
+    gestureGeneration.current++;
+    ignoreNextClick.current = true;
+    clearPress();
+    if (dropPending.current) void perch.cancelTargeting();
+    if (dragging.current) {
+      dragging.current = false;
+      dropPending.current = true;
+      // Cancellation stops highlighting but must NEVER attach a perch.
+      void perch.cancelTargeting().finally(() => {
+        dropPending.current = false;
+        setDragActive(false);
+      });
+    }
+  }, [clearPress, perch.cancelTargeting]);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: identity, renderer and visibility changes intentionally cancel the previous gesture via cleanup.
+  useEffect(() => {
+    const onVisibility = () => {
+      if (document.visibilityState === "hidden") cancelPress();
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    // Clear hold/capture on identity changes, hiding and unmount, not on hover
+    // or perch updates. Native drags can briefly lose key status, so no blur.
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibility);
+      cancelPress();
+    };
+  }, [cancelPress, avatarAgentId, character, turnedOff]);
+
+  const onAvatarPointerDown = useCallback(
+    (e: React.PointerEvent) => {
+      if (turnedOff || e.button !== 0 || e.isPrimary === false || e.ctrlKey)
+        return;
+      ignoreNextClick.current = false;
+      if (machine.mode !== "avatar" || pointerDownAt.current) return;
+      // preventDefault before any native drag, or the webview turns the
+      // gesture into text selection. Capture keeps stationary releases outside
+      // the hit surface from leaving a stuck hold (native drag still uses slop).
+      e.preventDefault();
+      const press = {
+        x: e.screenX,
+        y: e.screenY,
+        id: e.pointerId,
+        element: e.currentTarget,
+        held: false,
+      };
+      pointerDownAt.current = press;
+      dragging.current = false;
+      try {
+        e.currentTarget.setPointerCapture?.(e.pointerId);
+      } catch {
+        // Native panel handoff may already have released the pointer.
+      }
+      if (character) {
+        holdTimer.current = window.setTimeout(() => {
+          holdTimer.current = null;
+          if (pointerDownAt.current !== press || dragging.current) return;
+          press.held = true;
+          setHoldActive(true);
+        }, HOLD_DELAY_MS);
+      }
+    },
+    [character, turnedOff],
+  );
+
+  // Start native drag only on a fresh pointer-MOVE past slop. Queuing an old
+  // event for later can teleport the AppKit panel after mouse-up.
+  const onAvatarPointerMove = useCallback(
+    (e: React.PointerEvent) => {
+      const start = pointerDownAt.current;
+      if (
+        !start ||
+        e.pointerId !== start.id ||
+        dragging.current ||
+        dropPending.current ||
+        machine.mode !== "avatar"
+      )
+        return;
+      const moved =
+        Math.abs(e.screenX - start.x) > 3 || Math.abs(e.screenY - start.y) > 3;
+      if (moved) {
+        clearHoldTimer();
+        dragging.current = true;
+        setDragActive(true);
+        // Only REAL movement detaches a host or begins permission-bearing
+        // targeting; stationary holds remain purely visual, including perched.
+        if (perch.phase !== "unperched") void perch.dismount();
+        void machine.onDragStarted();
+        void perch.beginTargeting();
+      }
+    },
+    [clearHoldTimer, perch],
+  );
+
+  const onAvatarPointerUp = useCallback(
+    async (e: React.PointerEvent) => {
+      const press = pointerDownAt.current;
+      if (turnedOff || !press || e.pointerId !== press.id || e.button !== 0)
+        return;
+      const wasDragging = dragging.current;
+      dragging.current = false;
+      clearPress();
+      // The collapsed pointer-up owns expansion/drag. Its following click must
+      // not collapse the same persistent hit surface after layout changes.
+      ignoreNextClick.current = true;
+      if (wasDragging) {
+        const generation = gestureGeneration.current;
+        dropPending.current = true;
+        try {
+          const perched = await perch.endTargetingAndMaybePerch();
+          if (generation !== gestureGeneration.current) return;
+          if (perched) await machine.onDragEndedPerched();
+          else await machine.onDragEnded();
+        } finally {
+          // Retain dangle throughout hit-test/attach; a newer stationary hold
+          // has its own flag and cannot be cleared by this older completion.
+          dropPending.current = false;
+          setDragActive(false);
+        }
+      } else if (!press.held && !dropPending.current && !turnedOff) {
+        await expand();
+      }
+    },
+    [clearPress, turnedOff, expand, perch],
+  );
+
+  // Avatar follows the agent: pending selection previews the next chat's
+  // identity (a pending fresh chat previews the default avatar by mapping
+  // to null); otherwise the committed session binding; otherwise the
+  // default avatar.
+
+  const newChatBusy = useRef(false);
+  const handleNewChat = useCallback(async () => {
+    if (newChatBusy.current) return;
+    newChatBusy.current = true;
+    try {
+      const armed = await avatarMenu.newChat(session.messages.length);
+      if (!armed) return;
+      await closeMenu();
+      await expand({ composerOnly: true });
+    } finally {
+      newChatBusy.current = false;
+    }
+  }, [avatarMenu, closeMenu, expand, session.messages.length]);
+
+  const activeLayout = layout ?? menu?.layout ?? null;
+  const avatarRect = activeLayout?.avatarRect ?? lastAvatarRect;
+
+  const avatarState = deriveAvatarState({
+    hovering,
+    expanded: layout !== null,
+    connected: session.attached,
+    activity: session.activity,
+  });
+
+  const avatarView = (
+    <AgentAvatar
+      character={character}
+      choice={avatar.choice}
+      state={avatarState}
+      target={
+        holdActive || dragActive || perch.phase === "targeting"
+          ? "dangle"
+          : perch.phase === "perched"
+            ? "sit"
+            : "idle"
+      }
+      hidden={turnedOff}
+    />
+  );
+
+  if (!restored) return null;
+
+  return (
+    <div
+      className="expanded-root"
+      onPointerDown={(e) => {
+        // Any press in the grown menu window outside the menu cards and
+        // the avatar (shadow margin, empty corners) closes the menu.
+        if (!menu) return;
+        const target = e.target as Element;
+        if (target.closest(".menu-card") || target.closest(".avatar-hit"))
+          return;
+        void closeMenu();
+      }}
+    >
+      {/* biome-ignore lint/a11y/useSemanticElements: the avatar remains a div so pointer drag/capture stays on the native drag surface. */}
+      <div
+        ref={avatarTriggerRef}
+        className="avatar-hit"
+        style={{
+          position: "absolute",
+          left: avatarRect?.x ?? 0,
+          top: avatarRect?.y ?? 0,
+          width: avatarRect?.width ?? 94,
+          height: avatarRect?.height ?? 94,
+        }}
+        onPointerDown={onAvatarPointerDown}
+        onPointerMove={activeLayout ? undefined : onAvatarPointerMove}
+        onPointerUp={activeLayout ? undefined : onAvatarPointerUp}
+        onPointerCancel={(e) => {
+          if (e.pointerId === pointerDownAt.current?.id) cancelPress();
+        }}
+        onLostPointerCapture={(e) => {
+          // AppKit owns the pointer after performWindowDrag. Losing webview
+          // capture alone is not cancellation of that native drag; pointer-up
+          // still owns the drop, and pointercancel/hide remain explicit aborts.
+          if (!dragging.current && e.pointerId === pointerDownAt.current?.id)
+            cancelPress();
+        }}
+        onClick={(e) => {
+          if (ignoreNextClick.current) {
+            ignoreNextClick.current = false;
+            return;
+          }
+          if (turnedOff || e.button !== 0) return;
+          if (menu) void closeMenu({ restoreAvatarFocus: true });
+          else if (layout) void collapse();
+        }}
+        onPointerEnter={() => setHovering(true)}
+        onPointerLeave={() => setHovering(false)}
+        title={t("avatar.title")}
+        tabIndex={0}
+        role="button"
+        aria-label={t("avatar.title")}
+        aria-haspopup="menu"
+        aria-expanded={menu !== null}
+        onKeyDown={(e) => {
+          if (turnedOff || e.repeat) return;
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            if (menu) void closeMenu({ restoreAvatarFocus: true });
+            else if (layout) void collapse();
+            else void expand();
+            return;
+          }
+          if (e.key === "ContextMenu" || (e.key === "F10" && e.shiftKey)) {
+            e.preventDefault();
+            void openMenu();
+          }
+        }}
+        onContextMenu={(e) => {
+          if (turnedOff) return;
+          e.preventDefault();
+          void openMenu();
+        }}
+      >
+        {avatarView}
+      </div>
+      {layout && (
+        <div
+          className={`popover panel-popover${
+            popoverVariant === "composer" ? " composer-mode" : ""
+          }`}
+          ref={popoverElement}
+          style={{
+            position: "absolute",
+            left: layout.popoverRect.x,
+            top: layout.popoverRect.y,
+            width: layout.popoverRect.width,
+            height: layout.popoverRect.height,
+          }}
+        >
+          <ChatPopover
+            session={session}
+            perch={perch}
+            variant={popoverVariant}
+            anchor={
+              layout.popoverSide === null
+                ? layout.popoverAbove
+                  ? "bottom"
+                  : "top"
+                : "center"
+            }
+            composerRef={composerElement}
+          />
+        </div>
+      )}
+      {menu && (
+        <div
+          style={{
+            position: "absolute",
+            left: menu.layout.popoverRect.x,
+            top: menu.layout.popoverRect.y,
+            width: menu.layout.popoverRect.width,
+            height: menu.layout.popoverRect.height,
+          }}
+        >
+          <AvatarMenu
+            layout={menu.layout}
+            agentSelector={agentSelector}
+            model={menu.model}
+            onNewChat={() => {
+              void handleNewChat();
+            }}
+            onSelectAgent={(agent) => {
+              avatarMenu.selectAgent(agent.agentId);
+              void closeMenu({ restoreAvatarFocus: true });
+            }}
+            onSelectFresh={() => {
+              avatarMenu.selectFresh();
+              void closeMenu({ restoreAvatarFocus: true });
+            }}
+            onSettings={() => {
+              // Rust reveals + focuses the main window and tells its
+              // webview to open the Behavior settings section (where the
+              // Desktop Agent settings live).
+              void invoke("desktop_agent_open_settings").catch(() => undefined);
+              void closeMenu();
+            }}
+            onTurnOff={turnOff}
+            onClose={() => {
+              void closeMenu({ restoreAvatarFocus: true });
+            }}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/features/desktop-agent/ui/MarkdownBody.tsx b/src/features/desktop-agent/ui/MarkdownBody.tsx
new file mode 100644
index 000000000..d21db57dc
--- /dev/null
+++ b/src/features/desktop-agent/ui/MarkdownBody.tsx
@@ -0,0 +1,118 @@
+// Markdown renderer for agent replies: typed AST -> React elements. No
+// dangerouslySetInnerHTML anywhere — XSS-safe by construction (the parser
+// only admits http/https links; everything else is text nodes).
+
+import { openUrl } from "@tauri-apps/plugin-opener";
+
+import type { InlineSpan, MarkdownBlock } from "../lib/markdown";
+import { parseMarkdown } from "../lib/markdown";
+
+function Spans({ spans }: { spans: InlineSpan[] }) {
+  return (
+    <>
+      {spans.map((span, i) => {
+        switch (span.kind) {
+          case "bold":
+            // biome-ignore lint/suspicious/noArrayIndexKey: parse/content arrays are regenerated wholesale per render and only ever append — the index IS the stable identity
+            return <strong key={i}>{span.text}</strong>;
+          case "italic":
+            // biome-ignore lint/suspicious/noArrayIndexKey: parse/content arrays are regenerated wholesale per render and only ever append — the index IS the stable identity
+            return <em key={i}>{span.text}</em>;
+          case "code":
+            // biome-ignore lint/suspicious/noArrayIndexKey: parse/content arrays are regenerated wholesale per render and only ever append — the index IS the stable identity
+            return <code key={i}>{span.text}</code>;
+          case "link":
+            // This WKWebView has no new-window handler, so target=_blank
+            // navigations are cancelled outright — links would do nothing.
+            // Route through Berd's opener plugin instead (href is already
+            // http(s)-only by parser construction).
+            return (
+              <a
+                // biome-ignore lint/suspicious/noArrayIndexKey: parse/content arrays are regenerated wholesale per render and only ever append — the index IS the stable identity
+                key={i}
+                href={span.href}
+                onClick={(e) => {
+                  e.preventDefault();
+                  void openUrl(span.href).catch(() => {});
+                }}
+              >
+                {span.text}
+              </a>
+            );
+          case "text":
+            // biome-ignore lint/suspicious/noArrayIndexKey: parse/content arrays are regenerated wholesale per render and only ever append — the index IS the stable identity
+            return <span key={i}>{span.text}</span>;
+          default:
+            // Exhaustive over InlineSpan['kind']; unreachable.
+            return null;
+        }
+      })}
+    </>
+  );
+}
+
+function Block({ block }: { block: MarkdownBlock }) {
+  switch (block.kind) {
+    case "paragraph":
+      return (
+        <p>
+          <Spans spans={block.spans} />
+        </p>
+      );
+    case "heading": {
+      // Headings render as bold paragraph-ish lines scaled by level —
+      // real h1/h2 elements are absurd inside a 380pt chat bubble.
+      const size =
+        block.level === 1 ? "1.05em" : block.level === 2 ? "1.0em" : "0.95em";
+      return (
+        <p style={{ fontWeight: 700, fontSize: size, margin: "0.5em 0 0.2em" }}>
+          <Spans spans={block.spans} />
+        </p>
+      );
+    }
+    case "code":
+      return (
+        <pre>
+          <code>{block.text}</code>
+        </pre>
+      );
+    case "list":
+      return block.ordered ? (
+        <ol>
+          {block.items.map((item, i) => (
+            // biome-ignore lint/suspicious/noArrayIndexKey: parse/content arrays are regenerated wholesale per render and only ever append — the index IS the stable identity
+            <li key={i}>
+              <Spans spans={item} />
+            </li>
+          ))}
+        </ol>
+      ) : (
+        <ul>
+          {block.items.map((item, i) => (
+            // biome-ignore lint/suspicious/noArrayIndexKey: parse/content arrays are regenerated wholesale per render and only ever append — the index IS the stable identity
+            <li key={i}>
+              <Spans spans={item} />
+            </li>
+          ))}
+        </ul>
+      );
+    case "quote":
+      return (
+        <blockquote>
+          <Spans spans={block.spans} />
+        </blockquote>
+      );
+  }
+}
+
+export function MarkdownBody({ text }: { text: string }) {
+  const blocks = parseMarkdown(text);
+  return (
+    <div className="markdown-body">
+      {blocks.map((block, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: parse/content arrays are regenerated wholesale per render and only ever append — the index IS the stable identity
+        <Block key={i} block={block} />
+      ))}
+    </div>
+  );
+}
diff --git a/src/features/desktop-agent/ui/desktop-agent.css b/src/features/desktop-agent/ui/desktop-agent.css
new file mode 100644
index 000000000..21e443f0e
--- /dev/null
+++ b/src/features/desktop-agent/ui/desktop-agent.css
@@ -0,0 +1,777 @@
+/* Desktop-agent transparent shell: only the avatar, popover, and menus paint. */
+
+/* The desktop-agent panel is intentionally always-dark: it floats over
+   arbitrary apps and wallpaper instead of living inside Berd's themed
+   window. Keep this scoped semantic token set here so the panel does not
+   depend on a ThemeProvider, while still aliasing shared primitives when
+   they are exact dark-theme matches.
+
+   The webview loads globals.css, but without a ThemeProvider its semantic
+   tokens resolve to LIGHT values. Re-point --background so the global
+   focus-visible ring's offset reads dark on this panel. */
+#root {
+  --desktop-agent-surface-base: #18181b;
+  --background: var(--desktop-agent-surface-base);
+  /* Full chat popover padding. Also read by
+     DesktopAgentApp.readComposerBottomInset (grow-in-place geometry needs
+     the FULL layout's bottom padding while still in composer mode). */
+  --desktop-agent-panel-padding: 16px;
+  /* Dark glass shared by chat popover and avatar menu. Keep
+     POPOVER_SHADOW_MARGIN in anchorGeometry.ts large enough for this shadow. */
+  --panel-glass-bg: rgba(24, 24, 27, 0.96);
+  --panel-glass-shadow: 0 8px 32px rgba(0, 0, 0, 0.45);
+
+  --desktop-agent-surface: var(--panel-glass-bg); /* panel/menu glass */
+  --desktop-agent-surface-strong: rgba(
+    24,
+    24,
+    27,
+    0.92
+  ); /* composer-only hint */
+  --desktop-agent-surface-border: rgba(
+    255,
+    255,
+    255,
+    0.08
+  ); /* composer-only/menu borders */
+  --desktop-agent-quote-border: rgba(
+    255,
+    255,
+    255,
+    0.25
+  ); /* markdown blockquote border */
+  --desktop-agent-shadow: var(--panel-glass-shadow); /* panel/menu shadows */
+  --desktop-agent-shadow-soft: 0 4px 16px rgba(0, 0, 0, 0.35); /* composer-only hint shadow */
+
+  --desktop-agent-foreground: #e4e4e7; /* panel, assistant, and menu text */
+  --desktop-agent-foreground-inverse: var(--color-white); /* user bubble text */
+  --desktop-agent-foreground-muted: rgba(
+    255,
+    255,
+    255,
+    0.5
+  ); /* tool rows and chevrons */
+  --desktop-agent-foreground-subtle: rgba(
+    255,
+    255,
+    255,
+    0.45
+  ); /* hints, disabled send, empty menu */
+  --desktop-agent-foreground-faint: rgba(
+    255,
+    255,
+    255,
+    0.4
+  ); /* empty hint and tool summaries */
+  --desktop-agent-foreground-soft: rgba(
+    255,
+    255,
+    255,
+    0.65
+  ); /* hovered tool summary */
+  --desktop-agent-foreground-placeholder: rgba(
+    255,
+    255,
+    255,
+    0.35
+  ); /* composer placeholder */
+  --desktop-agent-foreground-control: rgba(
+    255,
+    255,
+    255,
+    0.7
+  ); /* icon buttons */
+  --desktop-agent-foreground-readable: rgba(
+    255,
+    255,
+    255,
+    0.72
+  ); /* tool result text */
+  --desktop-agent-quote-foreground: rgba(
+    228,
+    228,
+    231,
+    0.8
+  ); /* markdown blockquote text */
+
+  --desktop-agent-control: rgba(
+    255,
+    255,
+    255,
+    0.08
+  ); /* icon button background */
+  --desktop-agent-control-hover: rgba(
+    255,
+    255,
+    255,
+    0.14
+  ); /* icon hover and disabled send background */
+  --desktop-agent-control-subtle: rgba(
+    255,
+    255,
+    255,
+    0.07
+  ); /* composer background */
+  --desktop-agent-control-border: rgba(
+    255,
+    255,
+    255,
+    0.06
+  ); /* composer border */
+  --desktop-agent-control-border-hover: rgba(
+    255,
+    255,
+    255,
+    0.14
+  ); /* composer focus border */
+  --desktop-agent-control-muted: rgba(
+    255,
+    255,
+    255,
+    0.1
+  ); /* inline code and separators */
+  --desktop-agent-control-muted-strong: rgba(
+    255,
+    255,
+    255,
+    0.12
+  ); /* retry button and menu highlight */
+  --desktop-agent-control-strong: rgba(
+    255,
+    255,
+    255,
+    0.22
+  ); /* retry button hover */
+  --desktop-agent-code-surface: rgba(0, 0, 0, 0.35); /* markdown code blocks */
+  --desktop-agent-tool-result-surface: rgba(
+    255,
+    255,
+    255,
+    0.055
+  ); /* tool result background */
+
+  --desktop-agent-primary-action: var(--color-zinc-100); /* enabled send pill */
+  --desktop-agent-primary-action-fg: var(
+    --desktop-agent-surface-base
+  ); /* enabled send glyph */
+  --desktop-agent-primary-action-hover: var(
+    --color-white
+  ); /* enabled send hover */
+
+  --desktop-agent-user-bubble: var(--color-gray-700); /* user message bubble */
+  --desktop-agent-danger: rgba(248, 113, 113, 0.9); /* failed tool row */
+  --desktop-agent-danger-fg: rgba(
+    254,
+    202,
+    202,
+    0.95
+  ); /* failed tool result text */
+  --desktop-agent-danger-muted: rgba(
+    248,
+    113,
+    113,
+    0.7
+  ); /* failed tool summary */
+  --desktop-agent-danger-subtle: rgba(
+    248,
+    113,
+    113,
+    0.65
+  ); /* failed tool detail hint */
+  --desktop-agent-danger-surface: rgba(
+    127,
+    29,
+    29,
+    0.28
+  ); /* failed tool result background */
+  --desktop-agent-danger-solid: var(--color-red-400); /* error hint */
+  --desktop-agent-link: #7cb3ff; /* markdown links */
+  --desktop-agent-warning: var(--color-yellow-500); /* active capture button */
+  --desktop-agent-warning-surface: rgba(
+    234,
+    179,
+    8,
+    0.15
+  ); /* active capture background */
+}
+
+html,
+body,
+#root {
+  margin: 0;
+  padding: 0;
+  width: 100%;
+  height: 100%;
+  background: transparent;
+  overflow: hidden;
+  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.expanded-root {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+.panel-popover {
+  border-radius: 18px;
+  background: var(--desktop-agent-surface);
+  color: var(--desktop-agent-foreground);
+  box-sizing: border-box;
+  padding: var(--desktop-agent-panel-padding);
+  box-shadow: var(--desktop-agent-shadow);
+}
+
+/* Composer-first mode: the overlay region paints NOTHING itself — only
+   the hint and composer pills paint, so the "popover" reads as a lone
+   pill next to the avatar until a conversation exists. */
+.panel-popover.composer-mode {
+  background: transparent;
+  box-shadow: none;
+  padding: 0;
+  border-radius: 0;
+}
+
+/* Chat popover */
+.chat-popover {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  box-sizing: border-box;
+}
+
+.transcript {
+  flex: 1;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding-bottom: 8px;
+}
+
+.chat-popover.composer-only {
+  gap: 6px;
+}
+
+/* The composer pill hugs whichever region edge faces the avatar. */
+.chat-popover.composer-only.anchor-bottom {
+  justify-content: flex-end;
+}
+
+.chat-popover.composer-only.anchor-top {
+  justify-content: flex-start;
+}
+
+.chat-popover.composer-only.anchor-center {
+  justify-content: center;
+}
+
+.empty-hint {
+  color: var(--desktop-agent-foreground-faint);
+  text-align: center;
+  margin-top: 40%;
+  font-size: 13px;
+}
+
+.row {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.row.user {
+  align-items: flex-end;
+}
+
+.row.assistant {
+  align-items: flex-start;
+}
+
+/* Text metrics shared by both roles. The bubble CHROME (fill, radius,
+   inset, width cap) is USER-ONLY — matching the main app, which bubbles
+   user sends and renders assistant replies plain on the surface
+   (MessageBubble: user = rounded bg-message-user-bg, assistant =
+   w-full). */
+.bubble {
+  font-size: 13px;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+/* Berd's dark scheme paints user messages DARK GREY, not accent blue —
+   this is the main app's dark --message-user-bg (gray-700), inlined
+   through the panel-scoped tokens above so the always-dark surface keeps
+   the same treatment without depending on app theme state. */
+.row.user .bubble {
+  max-width: 85%;
+  padding: 8px 11px;
+  border-radius: 12px;
+  background: var(--desktop-agent-user-bubble);
+  color: var(--desktop-agent-foreground-inverse);
+}
+
+/* Assistant replies render PLAIN on the popover surface — no fill, no
+   inset, full width (the main app's treatment). */
+.row.assistant .bubble {
+  width: 100%;
+  color: var(--desktop-agent-foreground);
+}
+
+/* Markdown in assistant bubbles. The bubble itself keeps pre-wrap for
+   plain user text; rendered markdown resets it — block elements already
+   own the line breaks, and pre-wrap would double-space them. */
+.markdown-body {
+  white-space: normal;
+}
+
+.markdown-body p {
+  margin: 0.35em 0;
+}
+
+.markdown-body p:first-child {
+  margin-top: 0;
+}
+
+.markdown-body p:last-child {
+  margin-bottom: 0;
+}
+
+.markdown-body ul,
+.markdown-body ol {
+  margin: 0.35em 0;
+  padding-left: 1.3em;
+}
+
+/* Tailwind preflight (globals.css) strips list markers; restore them for
+   rendered agent markdown. */
+.markdown-body ul {
+  list-style: disc;
+}
+
+.markdown-body ol {
+  list-style: decimal;
+}
+
+.markdown-body li {
+  margin: 0.15em 0;
+}
+
+.markdown-body code {
+  background: var(--desktop-agent-control-muted);
+  border-radius: 4px;
+  padding: 0.1em 0.35em;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  font-size: 0.92em;
+}
+
+.markdown-body pre {
+  background: var(--desktop-agent-code-surface);
+  border-radius: 8px;
+  padding: 8px 10px;
+  margin: 0.4em 0;
+  overflow-x: auto;
+}
+
+.markdown-body pre code {
+  background: none;
+  padding: 0;
+  font-size: 0.9em;
+  white-space: pre;
+}
+
+.markdown-body blockquote {
+  margin: 0.35em 0;
+  padding-left: 0.8em;
+  border-left: 3px solid var(--desktop-agent-quote-border);
+  color: var(--desktop-agent-quote-foreground);
+}
+
+.markdown-body a {
+  color: var(--desktop-agent-link);
+}
+
+.cursor {
+  opacity: 0.6;
+  animation: blink 1s steps(1) infinite;
+}
+
+@keyframes blink {
+  50% {
+    opacity: 0;
+  }
+}
+
+.tool-row {
+  font-size: 11px;
+  color: var(--desktop-agent-foreground-muted);
+  padding: 2px 4px;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  max-width: 100%;
+}
+
+.tool-row.failed {
+  color: var(--desktop-agent-danger);
+}
+
+.tool-row-header {
+  display: flex;
+  align-items: baseline;
+  gap: 6px;
+  min-width: 0;
+}
+
+.tool-row-glyph {
+  flex: 0 0 auto;
+}
+
+.tool-row-name {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.tool-row-hint {
+  flex: 0 0 auto;
+  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+  font-size: 10px;
+  color: var(--desktop-agent-danger-subtle);
+}
+
+.tool-result {
+  margin: 3px 0 4px 17px;
+  padding: 8px 9px;
+  max-height: 260px;
+  overflow: auto;
+  white-space: pre-wrap;
+  user-select: text;
+  -webkit-user-select: text;
+  border-radius: 8px;
+  background: var(--desktop-agent-tool-result-surface);
+  color: var(--desktop-agent-foreground-readable);
+}
+
+.tool-result.failed {
+  background: var(--desktop-agent-danger-surface);
+  color: var(--desktop-agent-danger-fg);
+}
+
+/* Collapsed tool-run summary: one quiet line per
+   burst of tool activity, click to expand. Button-reset styling — it
+   should read as transcript metadata, not chrome. */
+.tool-run-summary {
+  border: none;
+  background: none;
+  text-align: left;
+  font-size: 11px;
+  color: var(--desktop-agent-foreground-faint);
+  padding: 2px 4px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.tool-run-summary:hover {
+  color: var(--desktop-agent-foreground-soft);
+}
+
+.tool-run-summary.has-failures {
+  color: var(--desktop-agent-danger-muted);
+}
+
+.tool-run-summary .disclosure {
+  display: inline-block;
+  transition: transform 0.12s ease;
+  font-size: 12px;
+}
+
+.tool-run-summary .disclosure.open {
+  transform: rotate(90deg);
+}
+
+.tool-run-detail {
+  padding: 2px 0 4px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  max-width: 100%;
+}
+
+.attached-image {
+  max-width: 70%;
+  border-radius: 10px;
+}
+
+.hint {
+  font-size: 11px;
+  color: var(--desktop-agent-foreground-subtle);
+  padding: 4px 2px;
+}
+
+.hint.error {
+  color: var(--desktop-agent-danger-solid);
+}
+
+/* Composer — matches the main Berd app's visual language: one rounded
+   grey box containing a borderless input with the send pill inside it. */
+.composer-box {
+  /* Single row: input and send pill share the line — a stacked two-row
+     layout reads as two lines tall no matter how tight the input is. */
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 6px;
+  margin-top: 8px;
+  /* Tight vertical inset matching Berd's composer: the pill nearly
+     fills the box height. */
+  padding: 5px 5px 5px 12px;
+  border-radius: 19px;
+  background: var(--desktop-agent-control-subtle);
+  border: 1px solid var(--desktop-agent-control-border);
+}
+
+.composer-box:focus-within {
+  border-color: var(--desktop-agent-control-border-hover);
+}
+
+.composer-box input {
+  flex: 1;
+  min-width: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: inherit;
+  font-size: 13px;
+  height: 17px;
+  line-height: 17px;
+  /* The empty-input caret draws at x=0 of the input, where a curved
+     clip boundary slices it into a rounded stub that reads as "too
+     small" (it is full height all along). Kill any intrinsic input
+     rounding and give the caret 2px of clearance so it never hugs the
+     clip edge. */
+  border-radius: 0;
+  padding: 0 0 0 2px;
+  margin: 0;
+}
+
+.composer-box input::placeholder {
+  color: var(--desktop-agent-foreground-placeholder);
+}
+
+.composer-only .composer-box {
+  margin-top: 0;
+  border-radius: 24px;
+  background: var(--desktop-agent-surface);
+  border-color: var(--desktop-agent-surface-border);
+  box-shadow: var(--desktop-agent-shadow);
+  padding: 9px 9px 9px 16px;
+}
+
+.composer-only .hint {
+  align-self: center;
+  background: var(--desktop-agent-surface-strong);
+  border-radius: 10px;
+  padding: 4px 10px;
+  box-shadow: var(--desktop-agent-shadow-soft);
+}
+
+.composer-controls {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-shrink: 0;
+}
+
+.icon-button {
+  width: 26px;
+  height: 26px;
+  border-radius: 13px;
+  border: none;
+  background: var(--desktop-agent-control);
+  color: var(--desktop-agent-foreground-control);
+  font-size: 12px;
+  line-height: 1;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.icon-button:hover {
+  background: var(--desktop-agent-control-hover);
+}
+
+.icon-button.active {
+  color: var(--desktop-agent-warning);
+  background: var(--desktop-agent-warning-surface);
+}
+
+.icon-button:disabled {
+  opacity: 0.35;
+  cursor: default;
+}
+
+/* The send pill: slightly horizontally oblong, lives inside the grey box
+   (Berd's composer pattern — wider than tall, nearly filling the box
+   height). Enabled = near-white fill with a dark glyph, matching the
+   main composer's primary action (the grey-on-grey version lacked
+   contrast); the stop variant wears the same chrome. */
+.send-pill {
+  width: 34px;
+  height: 26px;
+  border-radius: 13px;
+  border: none;
+  background: var(--desktop-agent-primary-action);
+  color: var(--desktop-agent-primary-action-fg);
+  font-size: 14px;
+  font-weight: 700;
+  line-height: 1;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.send-pill:hover {
+  background: var(--desktop-agent-primary-action-hover);
+}
+
+/* Disabled must read clearly distinct from enabled: a quiet grey wash,
+   not a dimmed white (opacity on near-white still reads "lit"). */
+.send-pill:disabled {
+  background: var(--desktop-agent-control-hover);
+  color: var(--desktop-agent-foreground-subtle);
+  cursor: default;
+}
+
+/* Stop variant: send-pill mid-response. Smaller glyph — the ◼ reads
+   heavier than the ↑ at equal font size. */
+.send-pill.stop {
+  font-size: 10px;
+}
+
+/* Manual reconnect affordance in the hint row — the affordance the
+   exhausted copy points at. */
+.hint-retry {
+  margin-left: 6px;
+  border: none;
+  background: var(--desktop-agent-control-muted-strong);
+  color: inherit;
+  border-radius: 8px;
+  padding: 1px 7px;
+  font-size: 12px;
+  cursor: pointer;
+}
+
+.hint-retry:hover {
+  background: var(--desktop-agent-control-strong);
+}
+
+/* Avatar chip */
+.avatar-hit {
+  width: 94px;
+  height: 94px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: grab;
+}
+
+/* Avatar context menu — dark glass matching the popover, native-menu
+   metrics (13px text, 28px rows). The region wrapper fills the computed
+   overlay rect; the cards position inside it. */
+.avatar-menu-region {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+.menu-card {
+  position: absolute;
+  box-sizing: border-box;
+  padding: 6px 4px;
+  border-radius: 12px;
+  background: var(--desktop-agent-surface);
+  border: 1px solid var(--desktop-agent-surface-border);
+  box-shadow: var(--desktop-agent-shadow);
+  display: flex;
+  flex-direction: column;
+}
+
+.avatar-submenu {
+  overflow-y: auto;
+}
+
+.menu-row {
+  /* The .highlighted fill is the focus affordance (roving focus follows
+     it); suppress WebKit's native outline, which focus-override doesn't. */
+  outline: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 28px;
+  padding: 0 10px;
+  border: none;
+  border-radius: 7px;
+  background: none;
+  color: var(--desktop-agent-foreground);
+  font-size: 13px;
+  font-family: inherit;
+  text-align: left;
+  cursor: default;
+}
+
+.menu-row.highlighted,
+.menu-row:hover {
+  background: var(--desktop-agent-control-muted-strong);
+}
+
+.menu-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.menu-chevron {
+  flex: 0 0 auto;
+  color: var(--desktop-agent-foreground-muted);
+}
+
+.menu-check {
+  flex: 0 0 auto;
+  font-size: 12px;
+}
+
+.menu-separator {
+  height: 1px;
+  margin: 4px 8px;
+  background: var(--desktop-agent-control-muted);
+}
+
+.menu-preview {
+  flex: 0 0 auto;
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  overflow: hidden;
+  object-fit: cover;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Zero agents: secondary explainer text, NOT a disabled menu item. */
+.menu-empty {
+  height: 28px;
+  display: flex;
+  align-items: center;
+  padding: 0 10px;
+  font-size: 12px;
+  color: var(--desktop-agent-foreground-subtle);
+}
diff --git a/src/features/desktop-agent/ui/desktopAgentCss.test.ts b/src/features/desktop-agent/ui/desktopAgentCss.test.ts
new file mode 100644
index 000000000..27dfd8e37
--- /dev/null
+++ b/src/features/desktop-agent/ui/desktopAgentCss.test.ts
@@ -0,0 +1,111 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const desktopAgentCss = readFileSync(
+  resolve(process.cwd(), "src/features/desktop-agent/ui/desktop-agent.css"),
+  "utf8",
+);
+
+function blockFor(selector: string): string {
+  const selectorStart = desktopAgentCss.indexOf(selector);
+  if (selectorStart === -1) {
+    throw new Error(`Missing ${selector} block`);
+  }
+
+  const blockStart = desktopAgentCss.indexOf("{", selectorStart);
+  const blockEnd = desktopAgentCss.indexOf("\n}", blockStart);
+  if (blockStart === -1 || blockEnd === -1) {
+    throw new Error(`Malformed ${selector} block`);
+  }
+
+  return desktopAgentCss.slice(blockStart, blockEnd + 2);
+}
+
+function declarationMatches(block: string): string[] {
+  return Array.from(
+    block.matchAll(/(^|\n)\s*[^\n{}:;]+:\s*[^;]+;/g),
+    ([match]) => match,
+  );
+}
+
+function declarationsFor(block: string): Map<string, string> {
+  const declarations = new Map<string, string>();
+  for (const declaration of declarationMatches(block)) {
+    const [property, value] = declaration.split(/:(.*)/s);
+    declarations.set(property.trim(), value.replace(/;$/, "").trim());
+  }
+  return declarations;
+}
+
+function tokenValues(): Map<string, string> {
+  const tokens = new Map<string, string>();
+  for (const declaration of declarationMatches(blockFor("#root {"))) {
+    const [token, value] = declaration.split(/:(.*)/s);
+    tokens.set(token.trim(), value.replace(/;$/, "").trim());
+  }
+  return tokens;
+}
+
+function canonicalCssValue(value: string): string {
+  return value
+    .replace(/\s+/g, " ")
+    .replace(/\( /g, "(")
+    .replace(/ \)/g, ")")
+    .trim();
+}
+
+function resolveToken(value: string, tokens: Map<string, string>): string {
+  const tokenName = value.match(/^var\((--[\w-]+)\)$/)?.[1];
+  if (!tokenName) return value;
+  const resolved = tokens.get(tokenName);
+  if (resolved === undefined) throw new Error(`Missing token ${tokenName}`);
+  return resolveToken(resolved, tokens);
+}
+
+describe("desktop-agent CSS tokens", () => {
+  it("keeps raw color literals scoped to the panel token block", () => {
+    const tokenBlock = blockFor("#root {");
+    const cssOutsideTokenBlock = desktopAgentCss.replace(tokenBlock, "");
+
+    expect(cssOutsideTokenBlock).not.toMatch(/#[0-9a-fA-F]{3,8}\b|rgba\(/);
+  });
+
+  it("keeps refactored tokens pixel-identical for pinned rules", () => {
+    const tokens = tokenValues();
+    const pinned: Record<string, Record<string, string>> = {
+      ".markdown-body blockquote": {
+        "border-left": "3px solid rgba(255, 255, 255, 0.25)",
+        color: "rgba(228, 228, 231, 0.8)",
+      },
+      ".icon-button": {
+        background: "rgba(255, 255, 255, 0.08)",
+        color: "rgba(255, 255, 255, 0.7)",
+      },
+      ".tool-result": {
+        background: "rgba(255, 255, 255, 0.055)",
+        color: "rgba(255, 255, 255, 0.72)",
+      },
+      ".composer-only .composer-box": {
+        "border-color": "rgba(255, 255, 255, 0.08)",
+      },
+    };
+
+    for (const [selector, expected] of Object.entries(pinned)) {
+      const declarations = declarationsFor(blockFor(selector));
+      for (const [property, value] of Object.entries(expected)) {
+        const actual = declarations.get(property);
+        if (actual === undefined) {
+          throw new Error(`Missing ${property} in ${selector}`);
+        }
+        expect(
+          canonicalCssValue(
+            actual.replace(/var\((--[\w-]+)\)/g, (_, token: string) =>
+              resolveToken(`var(${token})`, tokens),
+            ),
+          ),
+        ).toBe(value);
+      }
+    }
+  });
+});
diff --git a/src/features/experiments/__tests__/ExperimentsSettings.test.tsx b/src/features/experiments/__tests__/ExperimentsSettings.test.tsx
index 68c26af93..d2ab15eb1 100644
--- a/src/features/experiments/__tests__/ExperimentsSettings.test.tsx
+++ b/src/features/experiments/__tests__/ExperimentsSettings.test.tsx
@@ -6,6 +6,7 @@ import {
   BERDY_ONBOARDING_EXPERIMENT_ID,
   BUILDERBOT_SURFACE_EXPERIMENT_ID,
   CHAT_ON_CANVAS_EXPERIMENT_ID,
+  DESKTOP_AGENT_AGENT_SELECTOR_EXPERIMENT_ID,
   EXPERIMENT_DEFINITIONS,
   PROMPT_PINS_EXPERIMENT_ID,
   RELATED_PULL_REQUESTS_EXPERIMENT_ID,
@@ -142,6 +143,7 @@ describe("ExperimentsSettings", () => {
       RELATED_PULL_REQUESTS_EXPERIMENT_ID,
       PROMPT_PINS_EXPERIMENT_ID,
       REMOTE_SSH_SESSIONS_EXPERIMENT_ID,
+      DESKTOP_AGENT_AGENT_SELECTOR_EXPERIMENT_ID,
     ]);
   });
 
diff --git a/src/features/experiments/experimentDefinitions.test.ts b/src/features/experiments/experimentDefinitions.test.ts
index 48266b6df..d5b5f789d 100644
--- a/src/features/experiments/experimentDefinitions.test.ts
+++ b/src/features/experiments/experimentDefinitions.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  DESKTOP_AGENT_AGENT_SELECTOR_EXPERIMENT_ID,
   EXPERIMENT_DEFINITIONS,
   REMOTE_SSH_SESSIONS_EXPERIMENT_ID,
   VOICE_CONVERSATION_EXPERIMENT_ID,
@@ -21,4 +22,11 @@ describe("experiment definitions", () => {
     expect(definition?.manualEnableOnly).toBe(true);
     expect(definition?.settingsVisibility).toBe("all");
   });
+
+  it("keeps only the agent selector behind a Desktop Agent experiment", () => {
+    const ids = EXPERIMENT_DEFINITIONS.map(({ id }) => id);
+    expect(ids).toContain(DESKTOP_AGENT_AGENT_SELECTOR_EXPERIMENT_ID);
+    // The Desktop Agent itself is a General setting now.
+    expect(ids).not.toContain("desktop-agent");
+  });
 });
diff --git a/src/features/experiments/experimentDefinitions.ts b/src/features/experiments/experimentDefinitions.ts
index 54bccb0bb..b841d8d06 100644
--- a/src/features/experiments/experimentDefinitions.ts
+++ b/src/features/experiments/experimentDefinitions.ts
@@ -69,6 +69,11 @@ export const PROMPT_PINS_EXPERIMENT_ID = "prompt-pins";
 
 export const REMOTE_SSH_SESSIONS_EXPERIMENT_ID = "remote-ssh-sessions";
 
+/** Agent selector in the Desktop Agent's right-click menu. The Desktop Agent
+ *  itself is a General setting (desktopAgentPreferences.ts). */
+export const DESKTOP_AGENT_AGENT_SELECTOR_EXPERIMENT_ID =
+  "desktop-agent-agent-selector";
+
 export const EXPERIMENT_DEFINITIONS = [
   {
     id: BUILDERBOT_SURFACE_EXPERIMENT_ID,
@@ -137,4 +142,12 @@ export const EXPERIMENT_DEFINITIONS = [
     manualEnableOnly: true,
     settingsVisibility: "all",
   },
+  {
+    id: DESKTOP_AGENT_AGENT_SELECTOR_EXPERIMENT_ID,
+    titleKey: "experiments.desktopAgentAgentSelector.title",
+    descriptionKey: "experiments.desktopAgentAgentSelector.description",
+    // Only changes the Desktop Agent's right-click menu (no effect while the
+    // agent is off). No explicit default, so it follows the global auto-enable
+    // preference: on in dev builds, off in production.
+  },
 ] as const satisfies readonly ExperimentDefinition[];
diff --git a/src/features/settings/ui/BehaviorSettings.tsx b/src/features/settings/ui/BehaviorSettings.tsx
index 6ded5fcca..ee7fbea9c 100644
--- a/src/features/settings/ui/BehaviorSettings.tsx
+++ b/src/features/settings/ui/BehaviorSettings.tsx
@@ -13,6 +13,7 @@ import { Switch } from "@/shared/ui/switch";
 import { Textarea } from "@/shared/ui/textarea";
 import { GooseAutoCompactSettings } from "./GooseAutoCompactSettings";
 import { useAgentToolsTipsPreference } from "@/features/chat/lib/agentToolsTipPreferences";
+import { useDesktopAgentEnabledPreference } from "@/features/desktop-agent/lib/desktopAgentPreferences";
 import { useSessionCostPreference } from "@/features/chat/lib/sessionCostPreference";
 import { useResponseStartGutterPreference } from "@/features/chat/lib/responseStartGutterPreference";
 import { useArtifactAutoOpenPreference } from "@/features/chat/lib/artifactAutoOpenPreference";
@@ -24,6 +25,7 @@ import { useAtMentionDefaultCategoryPreference } from "@/features/chat/lib/menti
 import { useProfileCapability } from "@/shared/profile/capabilities";
 import { useStyleGuidelinesPreference } from "@/shared/preferences/styleGuidelinesPreference";
 import { useMultiWorkspacePreference } from "@/features/workspaces/multiWorkspacePreference";
+import { getPlatform } from "@/shared/lib/platform";
 
 // Behavior (rev 3): split out of the old GeneralSettings.tsx. Named
 // "Behavior" rather than "Chat" because most of what's left here affects
@@ -44,6 +46,7 @@ export function BehaviorSettings() {
   const agentToolsTipsPreference = useAgentToolsTipsPreference();
   const sessionCostPreference = useSessionCostPreference();
   const responseStartGutterPreference = useResponseStartGutterPreference();
+  const desktopAgentPreference = useDesktopAgentEnabledPreference();
   const multiWorkspacePreference = useMultiWorkspacePreference();
   const streamingShortcutPreference = useStreamingShortcutPreference();
   const {
@@ -62,6 +65,7 @@ export function BehaviorSettings() {
   // here since the global shortcut toggle that needed it moved to
   // KeyboardShortcutsSettings.tsx (see the comment above).
   const showAgentToolsTipsSetting = useProfileCapability("agentTools");
+  const isMac = getPlatform() === "mac";
 
   useEffect(() => {
     setStyleGuidelinesPromptDraft(styleGuidelinesPreference.prompt);
@@ -196,6 +200,19 @@ export function BehaviorSettings() {
             />
           </SettingsRow>
 
+          {isMac ? (
+            <SettingsRow
+              label={t("general.desktopAgent.label")}
+              description={t("general.desktopAgent.description")}
+            >
+              <Switch
+                checked={desktopAgentPreference.enabled}
+                onCheckedChange={desktopAgentPreference.setEnabled}
+                aria-label={t("general.desktopAgent.label")}
+              />
+            </SettingsRow>
+          ) : null}
+
           <SettingsRow
             label={t("general.artifactAutoOpen.label")}
             description={t("general.artifactAutoOpen.description")}
diff --git a/src/features/settings/ui/settingsSearchItems.ts b/src/features/settings/ui/settingsSearchItems.ts
index 846e10a07..9328c94b3 100644
--- a/src/features/settings/ui/settingsSearchItems.ts
+++ b/src/features/settings/ui/settingsSearchItems.ts
@@ -67,6 +67,11 @@ export const SETTINGS_SEARCH_ITEMS: readonly SettingsSearchItem[] = [
     sectionId: "behavior",
     labelKey: "general.responseStartGutter.label",
   },
+  {
+    id: "desktop-agent",
+    sectionId: "behavior",
+    labelKey: "general.desktopAgent.label",
+  },
   {
     id: "artifact-auto-open",
     sectionId: "behavior",
diff --git a/src/features/shortcuts/lib/shortcutDefinitions.ts b/src/features/shortcuts/lib/shortcutDefinitions.ts
index 5ed2c1c88..8c04f7b36 100644
--- a/src/features/shortcuts/lib/shortcutDefinitions.ts
+++ b/src/features/shortcuts/lib/shortcutDefinitions.ts
@@ -20,6 +20,7 @@ export type KnownShortcutCommandId =
   | "navigation.openSettings"
   | "navigation.paneJump"
   | "navigation.globalShortcut"
+  | "desktopAgent.togglePanel"
   | "session.quickSwitch"
   | "session.next"
   | "session.previous"
@@ -219,6 +220,16 @@ export const SHORTCUT_COMMANDS: readonly ShortcutCommandDefinition[] = [
     discoverable: true,
     when: () => getPlatform() === "mac",
   },
+  {
+    id: "desktopAgent.togglePanel",
+    category: "navigation",
+    scope: "global",
+    defaultBindings: [{ shortcut: "alt+meta+b" }],
+    descriptionKey: "actions.desktopAgentTogglePanel",
+    configurable: true,
+    discoverable: true,
+    when: () => getPlatform() === "mac",
+  },
   {
     id: "navigation.paneJump",
     category: "navigation",
diff --git a/src/main.tsx b/src/main.tsx
index 78a817727..0dfee2583 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -3,6 +3,7 @@ import {
   QueryClient,
   QueryClientProvider,
 } from "@tanstack/react-query";
+import { invoke } from "@tauri-apps/api/core";
 import React from "react";
 import ReactDOM from "react-dom/client";
 
@@ -118,12 +119,17 @@ function OptionalBerdctlBridge() {
 }
 
 const entrypointParams = new URLSearchParams(window.location.search);
+const isDesktopAgentWindow = entrypointParams.get("window") === "desktop-agent";
 const sessionKey = entrypointParams.get("sessionKey");
 const voiceBuddy = entrypointParams.has("voiceBuddy");
-if (voiceBuddy) document.documentElement.dataset.windowKind = "voice-buddy";
+if (isDesktopAgentWindow) {
+  document.documentElement.dataset.windowKind = "desktop-agent";
+} else if (voiceBuddy) {
+  document.documentElement.dataset.windowKind = "voice-buddy";
+}
 let sessionId: string | null = null;
 let bootError: string | null = null;
-if (sessionKey) {
+if (!isDesktopAgentWindow && sessionKey) {
   try {
     sessionId = decodeSessionKey(sessionKey);
   } catch (error) {
@@ -134,10 +140,60 @@ if (sessionKey) {
 }
 
 installRendererDiagnostics({
-  windowKind: voiceBuddy ? "voice-buddy" : sessionId ? "session" : "main",
+  windowKind: isDesktopAgentWindow
+    ? "desktop-agent"
+    : voiceBuddy
+      ? "voice-buddy"
+      : sessionId
+        ? "session"
+        : "main",
 });
 
-if (voiceBuddy) {
+if (isDesktopAgentWindow) {
+  // Desktop Agent panel webview (macOS only): a minimal tree — I18nProvider
+  // + the panel app. Deliberately no ThemeProvider / QueryClient / telemetry:
+  // the window is a transparent always-on-top panel, and the feature resolves
+  // its own data over its own ACP connection.
+  import("@/features/desktop-agent/ui/DesktopAgentApp")
+    .then(({ DesktopAgentApp }) => {
+      reactRoot.render(
+        <React.StrictMode>
+          <RendererErrorBoundary>
+            <I18nProvider>
+              <DesktopAgentApp />
+            </I18nProvider>
+          </RendererErrorBoundary>
+        </React.StrictMode>,
+      );
+    })
+    .catch((error) => {
+      console.error("Failed to load desktop-agent bundle:", error);
+      reportRendererError("desktop_agent_bundle_load_failed", error);
+      // Never leave an invisible always-on-top window squatting over the
+      // desktop eating clicks: ask Rust to destroy the panel, and render a
+      // small visible marker in case that fails. Hardcoded English matches
+      // renderBootError's precedent — this renders before I18nProvider exists.
+      void invoke("desktop_agent_close").catch(() => {});
+      reactRoot.render(
+        <div
+          title="Berd Desktop Agent failed to load — disable and re-enable the setting"
+          style={{
+            width: 94,
+            height: 94,
+            borderRadius: 20,
+            background: "rgba(24, 24, 27, 0.9)",
+            color: "#f87171",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            fontSize: 32,
+          }}
+        >
+          !
+        </div>,
+      );
+    });
+} else if (voiceBuddy) {
   import("@/features/voice-conversation/ui/VoiceBuddyApp")
     .then(({ VoiceBuddyApp }) => {
       reactRoot.render(
diff --git a/src/shared/i18n/constants.ts b/src/shared/i18n/constants.ts
index eecb828fd..e857dcdc6 100644
--- a/src/shared/i18n/constants.ts
+++ b/src/shared/i18n/constants.ts
@@ -7,6 +7,7 @@ export const TRANSLATION_NAMESPACES = [
   "builderbot",
   "common",
   "chat",
+  "desktop-agent",
   "feedback",
   "home",
   "onboarding",
diff --git a/src/shared/i18n/i18n.ts b/src/shared/i18n/i18n.ts
index 3c91aad14..f083b238c 100644
--- a/src/shared/i18n/i18n.ts
+++ b/src/shared/i18n/i18n.ts
@@ -33,6 +33,7 @@ const localeResourceLoaders = {
     builderbot: () => import("./locales/en/builderbot.json"),
     common: () => import("./locales/en/common.json"),
     chat: () => import("./locales/en/chat.json"),
+    "desktop-agent": () => import("./locales/en/desktop-agent.json"),
     feedback: () => import("./locales/en/feedback.json"),
     home: () => import("./locales/en/home.json"),
     onboarding: () => import("./locales/en/onboarding.json"),
@@ -50,6 +51,7 @@ const localeResourceLoaders = {
     builderbot: () => import("./locales/es/builderbot.json"),
     common: () => import("./locales/es/common.json"),
     chat: () => import("./locales/es/chat.json"),
+    "desktop-agent": () => import("./locales/es/desktop-agent.json"),
     feedback: () => import("./locales/es/feedback.json"),
     home: () => import("./locales/es/home.json"),
     onboarding: () => import("./locales/es/onboarding.json"),
diff --git a/src/shared/i18n/locales/en/desktop-agent.json b/src/shared/i18n/locales/en/desktop-agent.json
new file mode 100644
index 000000000..370226589
--- /dev/null
+++ b/src/shared/i18n/locales/en/desktop-agent.json
@@ -0,0 +1,53 @@
+{
+  "avatar": {
+    "title": "Berd Desktop Agent"
+  },
+  "composer": {
+    "placeholder": "Message Berd",
+    "placeholderAgent": "Message {{name}}",
+    "start": "Start new chat",
+    "startAgent": "Start new chat with {{name}}",
+    "send": "Send",
+    "stop": "Stop"
+  },
+  "empty": {
+    "prompt": "Ask the agent anything.",
+    "waiting": "Waiting for connection…",
+    "newChat": "New chat with {{name}} — your first message starts it."
+  },
+  "hint": {
+    "agentStarting": "{{name}} is starting up…",
+    "connecting": "Connecting to the agent server…",
+    "reconnecting": "Connection lost — reconnecting…",
+    "reconnectExhausted": "Can't reach the agent server. Click ↻ to retry.",
+    "retry": "Retry connection",
+    "sendFailed": "Couldn't send: {{message}}",
+    "stalled": "Still working — the agent server may be unreachable.",
+    "capturing": "Capturing window…",
+    "thinking": "Thinking…",
+    "agentStartingGeneric": "The agent is starting up…",
+    "perchError": "Perch problem: {{message}}",
+    "perchAccessibility": "Berd needs Accessibility permission to perch — grant it in System Settings, then try again.",
+    "perched": "Perched on {{app}} — {{title}}",
+    "perchedApp": "Perched on {{app}}"
+  },
+  "menu": {
+    "newChat": "Start new chat",
+    "switchAgent": "Switch agent",
+    "fresh": "Berd",
+    "empty": "No agents yet — create them in the main window",
+    "settings": "Settings…",
+    "turnOff": "Turn off agent"
+  },
+  "tools": {
+    "working_one": "Working… ({{count}} tool call)",
+    "working_other": "Working… ({{count}} tool calls)",
+    "summary_one": "{{count}} tool call",
+    "summary_other": "{{count}} tool calls",
+    "failed_one": "{{count}} failed",
+    "failed_other": "{{count}} failed",
+    "expand": "Expand tool calls",
+    "collapse": "Collapse tool calls",
+    "failureDetail": "full error below"
+  }
+}
diff --git a/src/shared/i18n/locales/en/settings.json b/src/shared/i18n/locales/en/settings.json
index 7658e72ee..1f102425b 100644
--- a/src/shared/i18n/locales/en/settings.json
+++ b/src/shared/i18n/locales/en/settings.json
@@ -264,6 +264,10 @@
     "chatOnCanvas": {
       "title": "Chat on canvas",
       "description": "Expand pinned chats into live conversation cards on Home where you can read and respond."
+    },
+    "desktopAgentAgentSelector": {
+      "title": "Desktop Agent agent selector",
+      "description": "Choose which agent the Desktop Agent's next chat uses from its right-click menu."
     }
   },
   "extensions": {
@@ -414,7 +418,11 @@
       "saveError": "Couldn't update the terminal fallback folder. Try again.",
       "saveSuccess": "Terminal fallback folder updated."
     },
-    "title": "General"
+    "title": "General",
+    "desktopAgent": {
+      "label": "Berd Desktop Agent",
+      "description": "An always-on-top agent avatar that lives on your screen and expands into a chat popover."
+    }
   },
   "nav": {
     "appearance": "Appearance",
diff --git a/src/shared/i18n/locales/en/shortcuts.json b/src/shared/i18n/locales/en/shortcuts.json
index 7209afe15..d946934fd 100644
--- a/src/shared/i18n/locales/en/shortcuts.json
+++ b/src/shared/i18n/locales/en/shortcuts.json
@@ -34,7 +34,8 @@
     "toggleTerminal": "Toggle terminal",
     "zoomIn": "Zoom in",
     "zoomOut": "Zoom out",
-    "zoomReset": "Reset zoom"
+    "zoomReset": "Reset zoom",
+    "desktopAgentTogglePanel": "Toggle the desktop agent"
   },
   "categories": {
     "chat": "Chat",
diff --git a/src/shared/i18n/locales/es/desktop-agent.json b/src/shared/i18n/locales/es/desktop-agent.json
new file mode 100644
index 000000000..373797697
--- /dev/null
+++ b/src/shared/i18n/locales/es/desktop-agent.json
@@ -0,0 +1,53 @@
+{
+  "avatar": {
+    "title": "Agente de escritorio de Berd"
+  },
+  "composer": {
+    "placeholder": "Escribe a Berd",
+    "placeholderAgent": "Escribe a {{name}}",
+    "send": "Enviar",
+    "stop": "Detener",
+    "start": "Iniciar nuevo chat",
+    "startAgent": "Iniciar nuevo chat con {{name}}"
+  },
+  "empty": {
+    "prompt": "Pregúntale lo que quieras al agente.",
+    "waiting": "Esperando la conexión…",
+    "newChat": "Nuevo chat con {{name}} — tu primer mensaje lo inicia."
+  },
+  "hint": {
+    "agentStarting": "{{name}} se está iniciando…",
+    "connecting": "Conectando con el servidor del agente…",
+    "reconnecting": "Conexión perdida — reconectando…",
+    "reconnectExhausted": "No se puede conectar con el servidor del agente. Haz clic en ↻ para reintentar.",
+    "retry": "Reintentar conexión",
+    "sendFailed": "No se pudo enviar: {{message}}",
+    "stalled": "Sigue trabajando — puede que el servidor del agente no esté disponible.",
+    "capturing": "Capturando ventana…",
+    "thinking": "Pensando…",
+    "agentStartingGeneric": "El agente se está iniciando…",
+    "perchError": "Problema al posarse: {{message}}",
+    "perchAccessibility": "Berd necesita el permiso de Accesibilidad para posarse — concédelo en Configuración del Sistema y vuelve a intentarlo.",
+    "perched": "Posado en {{app}} — {{title}}",
+    "perchedApp": "Posado en {{app}}"
+  },
+  "menu": {
+    "newChat": "Iniciar nuevo chat",
+    "switchAgent": "Cambiar de agente",
+    "fresh": "Berd",
+    "empty": "Aún no hay agentes — créalos en la ventana principal",
+    "settings": "Configuración…",
+    "turnOff": "Desactivar agente"
+  },
+  "tools": {
+    "working_one": "Trabajando… ({{count}} llamada de herramienta)",
+    "working_other": "Trabajando… ({{count}} llamadas de herramientas)",
+    "summary_one": "{{count}} llamada de herramienta",
+    "summary_other": "{{count}} llamadas de herramientas",
+    "failed_one": "{{count}} con error",
+    "failed_other": "{{count}} con error",
+    "expand": "Mostrar llamadas de herramientas",
+    "collapse": "Ocultar llamadas de herramientas",
+    "failureDetail": "error completo abajo"
+  }
+}
diff --git a/src/shared/i18n/locales/es/settings.json b/src/shared/i18n/locales/es/settings.json
index adbace8e3..e40329391 100644
--- a/src/shared/i18n/locales/es/settings.json
+++ b/src/shared/i18n/locales/es/settings.json
@@ -264,6 +264,10 @@
     "chatOnCanvas": {
       "title": "Chat en el lienzo",
       "description": "Expande los chats fijados en tarjetas de conversación en vivo en Inicio, donde puedes leer y responder."
+    },
+    "desktopAgentAgentSelector": {
+      "title": "Selector de agentes del Agente de escritorio",
+      "description": "Elige desde el menú contextual qué agente usará el próximo chat del Agente de escritorio."
     }
   },
   "extensions": {
@@ -414,7 +418,11 @@
       "saveError": "No se pudo actualizar la carpeta de reserva del terminal. Inténtalo de nuevo.",
       "saveSuccess": "Carpeta de reserva del terminal actualizada."
     },
-    "title": "General"
+    "title": "General",
+    "desktopAgent": {
+      "label": "Agente de escritorio de Berd",
+      "description": "Un avatar de agente siempre visible que vive en tu pantalla y se expande en un chat."
+    }
   },
   "nav": {
     "appearance": "Apariencia",
diff --git a/src/shared/i18n/locales/es/shortcuts.json b/src/shared/i18n/locales/es/shortcuts.json
index 5b6dc7d4a..44632e21c 100644
--- a/src/shared/i18n/locales/es/shortcuts.json
+++ b/src/shared/i18n/locales/es/shortcuts.json
@@ -34,7 +34,8 @@
     "toggleTerminal": "Mostrar u ocultar terminal",
     "zoomIn": "Acercar",
     "zoomOut": "Alejar",
-    "zoomReset": "Restablecer zoom"
+    "zoomReset": "Restablecer zoom",
+    "desktopAgentTogglePanel": "Mostrar u ocultar el agente de escritorio"
   },
   "categories": {
     "chat": "Chat",
diff --git a/src/shared/styles/globals.css b/src/shared/styles/globals.css
index 78739b45d..35b461942 100644
--- a/src/shared/styles/globals.css
+++ b/src/shared/styles/globals.css
@@ -1953,10 +1953,8 @@ html[data-window-kind="voice-buddy"] #root {
     outline: none !important;
   }
 
-  *:not(body):not(.focus-override) {
-    &:focus-visible {
-      @apply ring-ring ring-offset-background ring-2 ring-offset-1 outline-hidden;
-    }
+  *:not(body):not(.focus-override):focus-visible {
+    @apply ring-ring ring-offset-background ring-2 ring-offset-1 outline-hidden;
   }
 
   /* Menu surfaces and items paint their own focus highlight (focus:bg-*),
@@ -1977,20 +1975,16 @@ html[data-window-kind="voice-buddy"] #root {
       [data-slot="menubar-checkbox-item"],
       [data-slot="menubar-radio-item"],
       [data-slot="menubar-sub-trigger"]
-    ) {
-    &:focus-visible {
-      @apply ring-0 ring-offset-0;
-    }
+    ):focus-visible {
+    @apply ring-0 ring-offset-0;
   }
 
   .link {
     @apply hover:text-foreground/80 inline-flex items-center gap-1 rounded-xs font-medium underline underline-offset-4;
   }
 
-  *:not(body):not(.focus-override).link {
-    &:focus-visible {
-      @apply ring-ring ring-offset-background ring-2 ring-offset-2 outline-hidden;
-    }
+  *:not(body):not(.focus-override).link:focus-visible {
+    @apply ring-ring ring-offset-background ring-2 ring-offset-2 outline-hidden;
   }
 }
 
diff --git a/src/shared/styles/globals.test.ts b/src/shared/styles/globals.test.ts
index 20dc6bc04..a593a5f72 100644
--- a/src/shared/styles/globals.test.ts
+++ b/src/shared/styles/globals.test.ts
@@ -35,6 +35,30 @@ describe("text shimmer motion", () => {
   });
 });
 
+describe("global focus ring", () => {
+  // Tailwind v4.3.3 drops the whole parent selector when a `*`-led selector
+  // like `*:not(body):not(.focus-override)` uses `&` nesting, compiling it to a
+  // bare `:focus-visible` that matches every element. Keep these rules
+  // flattened until the upstream Tailwind bug is fixed.
+  it("keeps focus-visible selectors flattened", () => {
+    const cssWithoutVariantDefinitions = globalsCss
+      .split("\n")
+      .filter((line) => !line.trimStart().startsWith("@custom-variant"))
+      .join("\n");
+
+    expect(cssWithoutVariantDefinitions).not.toMatch(/^\s*&/m);
+    expect(globalsCss).toContain(
+      "*:not(body):not(.focus-override):focus-visible {",
+    );
+    expect(globalsCss).toContain(
+      '[data-slot="menubar-sub-trigger"]\n    ):focus-visible {',
+    );
+    expect(globalsCss).toContain(
+      "*:not(body):not(.focus-override).link:focus-visible {",
+    );
+  });
+});
+
 describe("card-glass surface", () => {
   it("derives the glass panel fill from the card token in both themes", () => {
     const lightTheme = declarationsFor(":root {");