chore: release 2.0.0-beta4

This change adds the missing 'packages' definition to pnpm-workspace.yaml, allowing pnpm to correctly install dependencies for the 'ui' sub-package. This resolves the 'vite: command not found' error during 'ui:build'. It also reverts the temporary 'pnpm dlx' workarounds in ui/package.json.

.github/workflows/ci.yml

@@ -34,7 +34,7 @@ jobs:
         if: matrix.runtime == 'node'
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           check-latest: true
 
       - name: Setup Bun
@@ -49,7 +49,7 @@ jobs:
         if: matrix.runtime == 'bun'
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 24
           check-latest: true
 
       - name: Runtime versions
@@ -106,6 +106,7 @@ jobs:
         run: bunx tsc -p tsconfig.json
 
   macos-app:
+    if: github.event_name == 'pull_request'
     runs-on: macos-latest
     steps:
       - name: Checkout
@@ -170,6 +171,44 @@ jobs:
             sleep $((attempt * 20))
           done
           exit 1
+  ios:
+    if: false # ignore iOS in CI for now
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Select Xcode 26.1
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.1.app
+          xcodebuild -version
+
+      - name: Install XcodeGen
+        run: brew install xcodegen
+
+      - name: Install SwiftLint / SwiftFormat
+        run: brew install swiftlint swiftformat
+
+      - name: Show toolchain
+        run: |
+          sw_vers
+          xcodebuild -version
+          swift --version
 
       - name: Generate iOS project
         run: |

.gitignore

@@ -1,22 +1,29 @@
 node_modules
 .env
 dist
+*.bun-build
 pnpm-lock.yaml
 coverage
 .pnpm-store
 .worktrees/
 .DS_Store
 **/.DS_Store
+
+# Bun build artifacts
+*.bun-build
 apps/macos/.build/
 apps/shared/ClawdisKit/.build/
+bin/
 bin/clawdis-mac
 bin/docs-list
 apps/macos/.build-local/
 apps/macos/.swiftpm/
+apps/shared/ClawdisKit/.swiftpm/
 Core/
 apps/ios/*.xcodeproj/
 apps/ios/*.xcworkspace/
 apps/ios/.swiftpm/
+vendor/
 
 # Vendor build artifacts
 vendor/a2ui/renderers/lit/dist/

AGENTS.md

@@ -16,7 +16,7 @@
 - Language: TypeScript (ESM). Prefer strict typing; avoid `any`.
 - Formatting/linting via Biome; run `pnpm lint` before commits.
 - Keep files concise; extract helpers instead of “V2” copies. Use existing patterns for CLI options and dependency injection via `createDefaultDeps`.
-- Keep every file ≤ 500 LOC; refactor or split before exceeding and check frequently.
+- Aim to keep files under ~700 LOC; guideline only (not a hard guardrail). Split/refactor when it improves clarity or testability.
 
 ## Testing Guidelines
 - Framework: Vitest with V8 coverage thresholds (70% lines/branches/functions/statements).
@@ -40,10 +40,14 @@
 - macOS logs: use `./scripts/clawlog.sh` (aka `vtlog`) to query unified logs for subsystem `com.steipete.clawdis`; it supports follow/tail/category filters and expects passwordless sudo for `/usr/bin/log`.
 - Also read the shared guardrails at `~/Projects/oracle/AGENTS.md` and `~/Projects/agent-scripts/AGENTS.MD` before making changes; align with any cross-repo rules noted there.
 - SwiftUI state management (iOS/macOS): prefer the `Observation` framework (`@Observable`, `@Bindable`) over `ObservableObject`/`@StateObject`; don’t introduce new `ObservableObject` unless required for compatibility, and migrate existing usages when touching related code.
+- **Restart apps:** “restart iOS/Android apps” means rebuild (recompile/install) and relaunch, not just kill/launch.
+- Notary key file lives at `~/Library/CloudStorage/Dropbox/Backup/AppStore/AuthKey_NJF3NFGTS3.p8` (Sparkle keys live under `~/Library/CloudStorage/Dropbox/Backup/Sparkle`).
 - **Multi-agent safety:** do **not** create/apply/drop `git stash` entries unless Peter explicitly asks (this includes `git pull --rebase --autostash`). Assume other agents may be working; keep unrelated WIP untouched and avoid cross-cutting state changes.
+- **Multi-agent safety:** when Peter says "push", you may `git pull --rebase` to integrate latest changes (never discard other agents' work). When Peter says "commit", scope to your changes only. When Peter says "commit all", commit everything in grouped chunks.
 - **Multi-agent safety:** do **not** create/remove/modify `git worktree` checkouts (or edit `.worktrees/*`) unless Peter explicitly asks.
 - **Multi-agent safety:** do **not** switch branches / check out a different branch unless Peter explicitly asks.
-- When asked to open a “session” file, open the Pi session logs under `~/.clawdis/sessions/*.jsonl` (newest unless a specific ID is given), not the default `sessions.json`.
+- **Multi-agent safety:** running multiple agents is OK as long as each agent has its own session.
+- When asked to open a “session” file, open the Pi session logs under `~/.clawdis/sessions/*.jsonl` (newest unless a specific ID is given), not the default `sessions.json`. If logs are needed from Mac Studio, SSH via Tailscale and read the same path there.
 - Menubar dimming + restart flow mirrors Trimmy: use `scripts/restart-mac.sh` (kills all Clawdis variants, runs `swift build`, packages, relaunches). Icon dimming depends on MenuBarExtraAccess wiring in AppMain; keep `appearsDisabled` updates intact when touching the status item.
 - Never send streaming/partial replies to external messaging surfaces (WhatsApp, Telegram); only final replies should be delivered there. Streaming/tool events may still go to internal UIs/control channel.
 - Voice wake forwarding tips:

CHANGELOG.md

@@ -1,5 +1,147 @@
 # Changelog
 
+## 2.0.0-beta4 — 2025-12-27
+
+### Fixes
+- Package contents: include Discord/hooks build outputs in the npm tarball to avoid missing module errors.
+
+## 2.0.0-beta3 — 2025-12-27
+
+### Highlights
+- First-class Clawdis tools (browser, canvas, nodes, cron) replace the old `clawdis-*` skills; tool schemas are now injected directly into the agent runtime.
+- Per-session model selection + custom model providers: `models.providers` merges into `~/.clawdis/agent/models.json` (merge/replace modes) for LiteLLM, local OpenAI-compatible servers, Anthropic proxies, etc.
+- Group chat activation modes: per-group `/activation mention|always` command with status visibility.
+- Discord bot transport for DMs and guild text channels, with allowlists + mention gating.
+- Gateway webhooks: external `wake` and isolated `agent` hooks with dedicated token auth.
+- Hook mappings + Gmail Pub/Sub helper (`clawdis hooks gmail setup/run`) with auto-renew + Tailscale Funnel support.
+- Command queue modes + per-session overrides (`/queue ...`) and new `agent.maxConcurrent` cap for safe parallelism across sessions.
+- Background bash tasks: `bash` auto-yields after 20s (or on demand) with a `process` tool to list/poll/log/write/kill sessions.
+- Gateway in-process restart: `clawdis_gateway` tool action triggers a SIGUSR1 restart without needing a supervisor.
+
+### Breaking
+- Config refactor: `inbound.*` removed; use top-level `routing` (allowlists + group rules + transcription), `messages` (prefixes/timestamps), and `session` (scoping/store/mainKey). No legacy keys read.
+- Heartbeat config moved to `agent.heartbeat`: set `every: "30m"` (duration string) and optional `model`. `agent.heartbeatMinutes` is removed, and heartbeats are disabled unless `agent.heartbeat.every` is set.
+- Heartbeats now run via the gateway runner (main session) and deliver to the last used channel by default. WhatsApp reply-heartbeat behavior is removed; use `agent.heartbeat.target`/`to` (or `target: "none"`) to control delivery.
+- Browser `act` no longer accepts CSS `selector`; use `snapshot` refs (default `ai`) or `evaluate` as an escape hatch.
+
+### Fixes
+- Heartbeat replies now strip repeated `HEARTBEAT_OK` tails to avoid accidental “OK OK” spam.
+- Heartbeat delivery now uses the last non-empty payload, preventing tool preambles from swallowing the final reply.
+- Heartbeat failure logs now include the error reason instead of `[object Object]`.
+- Duration strings now accept `h` (hours) where durations are parsed (e.g., heartbeat intervals).
+- WhatsApp inbound now normalizes more wrapper types so quoted reply bodies are extracted reliably.
+- WhatsApp send now preserves existing JIDs (including group `@g.us`) instead of coercing to `@s.whatsapp.net`. (Thanks @arun-8687.)
+- Telegram/WhatsApp: reply context stays in `Body`/`ReplyTo*`, but outbound replies no longer thread to the original message. (Thanks @joshp123 for the PR and follow-up question.)
+- Suppressed libsignal session cleanup spam from console logs unless verbose mode is enabled.
+- WhatsApp web creds persistence hardened; credentials are restored before auth checks and QR login auto-restarts if it stalls.
+- Group chats now honor `routing.groupChat.requireMention=false` as the default activation when no per-group override exists.
+- Gateway auth no longer supports PAM/system mode; use token or shared password.
+- Tailscale Funnel now requires password auth (no token-only public exposure).
+- Group `/new` resets now work with @mentions so activation guidance appears on fresh sessions.
+- Group chat activation context is now injected into the system prompt at session start (and after activation changes), including /new greetings.
+- Typing indicators now start only once a reply payload is produced (no "thinking" typing for silent runs).
+- WhatsApp group typing now starts immediately only when the bot is mentioned; otherwise it waits until real output exists.
+- Streamed `<think>` segments are stripped before partial replies are emitted.
+- System prompt now tags allowlisted owner numbers as the user identity to avoid mistaken “friend” assumptions.
+- LM Studio/Ollama replies now require <final> tags; streaming ignores content until <final> begins.
+- LM Studio responses API: tools payloads no longer include `strict: null`, and LM Studio no longer gets forced `<think>/<final>` tags.
+- Identity emoji no longer auto-prefixes replies (set `messages.responsePrefix` explicitly if desired).
+- Model switches now enqueue a system event so the next run knows the active model.
+- `/model status` now lists available models (same as `/model`).
+- `process log` pagination is now line-based (omit `offset` to grab the last N lines).
+- macOS WebChat: assistant bubbles now update correctly when toggling light/dark mode.
+- macOS: avoid spawning a duplicate gateway process when an external listener already exists.
+- Node bridge: when binding to a non-loopback host (e.g. Tailnet IP), also listens on `127.0.0.1` for local connections (without creating duplicate loopback listeners for `0.0.0.0`/`127.0.0.1` binds).
+- UI perf: pause repeat animations when scenes are inactive (typing dots, onboarding glow, iOS status pulse), throttle voice overlay level updates, and reduce overlay focus churn.
+- Canvas defaults/A2UI auto-nav aligned; debug status overlay centered; redundant await removed in `CanvasManager`.
+- Gateway launchd loop fixed by removing redundant `kickstart -k`.
+- CLI now hints when Peekaboo is unauthorized.
+- WhatsApp web inbox listeners now clean up on close to avoid duplicate handlers.
+- Gateway startup now brings up browser control before external providers; WhatsApp/Telegram/Discord auto-start can be disabled with `web.enabled`, `telegram.enabled`, or `discord.enabled`.
+
+### Providers & Routing
+- New Discord provider for DMs + guild text channels with allowlists and mention-gated replies by default.
+- `routing.queue` now controls queue vs interrupt behavior globally + per surface (defaults: WhatsApp/Telegram interrupt, Discord/WebChat queue).
+- `/queue <mode>` supports one-shot or per-session overrides; `/queue reset|default` clears overrides.
+- `agent.maxConcurrent` caps global parallel runs while keeping per-session serialization.
+
+### macOS app
+- Update-ready state surfaced in the menu; menu sections regrouped with session submenus.
+- Menu bar now shows a dedicated Nodes section under Context with inline rows, overflow submenu, and iconized actions.
+- Nodes now expose consistent inline details with per-node submenus for quick copy of key fields.
+- Node rows now show compact app versions (build numbers moved to submenus) and offer SSH launch from Bonjour when available.
+- Menu actions are grouped below toggles; Open Canvas hides when disabled and Voice Wake now anchors the mic picker.
+- Connections now include Discord provider status + configuration UI.
+- Menu bar gains an Allow Camera toggle alongside Canvas.
+- Session list polish: sleeping/disconnected/error states, usage bar restored, padding + bar sizing tuned, syncing menu removed, header hidden when disconnected.
+- Chat UI polish: tool call cards + merged tool results, glass background, tighter composer spacing, visual effect host tweaks.
+- OAuth storage moved; legacy session syncing metadata removed.
+- Remote SSH tunnels now get health checks; Debug → Ports highlights unhealthy tunnels and offers Reset SSH tunnel.
+- Menu bar session/node sections no longer reflow while open, keeping hover highlights aligned.
+- Menu hover highlights now span the full width (including submenu arrows).
+- Menu session rows now refresh while open without width changes (no more stuck “Loading sessions…”).
+- Menu width no longer grows on hover when moving the mouse across rows.
+- Context usage bars now have higher contrast in light mode.
+- macOS node timeouts now share a single async timeout helper for consistent behavior.
+- WebChat window defaults tightened (narrower width, edge-to-edge layout) and the SwiftUI tag removed from the title.
+
+### Nodes & Canvas
+- Debug status overlay gated and toggleable on macOS/iOS/Android nodes.
+- Gateway now derives the canvas host URL via a shared helper for bridge + WS handshakes (avoids loopback pitfalls).
+- `canvas a2ui push` validates JSONL with line errors, rejects v0.9 payloads, and supports `--text` quick renders.
+- `nodes rename` lets you override paired node display names without editing JSON.
+- Android scaffold asset cleanup; iOS canvas/voice wake adjustments.
+
+### Logging & Observability
+- New subsystem console formatter with color modes, shortened prefixes, and TTY detection; browser/gateway logs route through the subsystem logger.
+- WhatsApp console output streamlined; chalk/tslog typing fixes.
+
+### Web UI
+- Chat is now the dashboard landing view; health status simplified; initial scroll animation removed.
+
+### Build, Dev, Docs
+- Notarization flow added for macOS release artifacts; packaging scripts updated.
+- macOS signing auto-selects Developer ID → Apple Distribution → Apple Development; no ad-hoc fallback.
+- Added type-aware oxlint; docs list resolves from cwd; formatting/lint cleanup and dependency bumps (Peekaboo).
+- Docs refreshed for tools, custom model providers, Discord, queue/routing, group activation commands, logging, restart semantics, release notes, GitHub pages CTAs, and npm pitfalls.
+- `pnpm build` now skips A2UI bundling for faster builds (run `pnpm canvas:a2ui:bundle` when needed).
+
+### Tests
+- Coverage added for models config merging, WhatsApp reply context, QR login flows, auto-reply behavior, and gateway SIGTERM timeouts.
+- Added gateway webhook coverage (auth, validation, and summary posting).
+- Vitest now isolates HOME/XDG config roots so tests never touch a real `~/.clawdis` install.
+
+## 2.0.0-beta2 — 2025-12-21
+
+Second beta focused on bundled gateway packaging, skills management, onboarding polish, and provider reliability.
+
+### Highlights
+- Bundled gateway packaging: bun-compiled embedded gateway, new `gateway-daemon` command, launchd support, DMG packaging (zip+DMG).
+- Skills platform: managed/bundled skills, install metadata + installers (uv), skill search + website, media/transcription helpers.
+- macOS app: new Connections settings w/ provider status + QR login, skills settings redesign w/ install targets, models list loaded from the Gateway, clearer local/remote gateway choices.
+- Web/agent UX: tool summary streaming + runtime toggle, WhatsApp QR login tool, agent steering queue, voice wake routes to main session, workspace bootstrap ritual.
+
+### Gateway & providers
+- Gateway: `models.list`, provider status events + RPC coverage, tailscale auth + PAM, bind-mode config, enriched agent WS logs, safer upgrade socket handling, fixed handshake auth crash.
+- WhatsApp Web: QR login flow improvements (logged-out clearing, wait flow), self-chat mode handling, removed batching delay, web inbox made non-blocking.
+- Telegram: normalized chat IDs with clearer error reporting.
+
+### Canvas & browser control
+- Canvas host served on Gateway port; removed standalone canvasHost port config; restored action bridge; refreshed A2UI bundle + message context; bridge canvas host for nodes.
+- A2UI full-screen gutters + status clearance after successful load to avoid overlay collisions.
+- Browser control API simplified; added MCP tool dispatch + native actions; control server can start without Playwright; hook timeouts extended.
+
+### macOS UI polish
+- Onboarding chat UI: kickoff flow, bubble tails, spacing + bottom bar refinements, window sizing tweaks, show Dock icon during onboarding.
+- Skills UI: stabilized action column, fixed install target access, refined list layout and sizing, always show CLI installer.
+- Remote/local gateway: auto-enable local gateway, clearer labels, re-ensure remote tunnel, hide local bridge discovery in remote mode.
+
+### Build, CI, deps
+- Bundled playwright-core + chromium-bidi/long; bun gateway bytecode builds; swiftformat/biome CI fixes; iOS lint script updates; Android icon/compiler updates; ignored new ClawdisKit `.swiftpm` path.
+
+### Docs
+- README architecture refresh + npm header image fix; onboarding/bootstrap steps; skills install guidance + new skills; browser/canvas control docs; bundled gateway + DMG packaging notes.
+
 ## 2.0.0-beta1 — 2025-12-19
 
 First Clawdis release post rebrand. This is a semver-major because we dropped legacy providers/agents and moved defaults to new paths while adding a full macOS companion app, a WebSocket Gateway, and an iOS node.
@@ -9,7 +151,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le
 
 ### Breaking
 - Renamed to **Clawdis**: defaults now live under `~/.clawdis` (sessions in `~/.clawdis/sessions/`, IPC at `~/.clawdis/clawdis.sock`, logs in `/tmp/clawdis`). Launchd labels and config filenames follow the new name; legacy stores are copied forward on first run.
-- Pi only: `inbound.reply.agent.kind` accepts only `"pi"`, and the agent CLI/CLI flags for Claude/Codex/Gemini were removed. The Pi CLI runs in RPC mode with a persistent worker.
+- Pi only: only the embedded Pi runtime remains, and the agent CLI/CLI flags for Claude/Codex/Gemini were removed. The Pi CLI runs in RPC mode with a persistent worker.
 - WhatsApp Web is the only transport; Twilio support and related CLI flags/tests were removed.
 - Direct chats now collapse into a single `main` session by default (no config needed); groups stay isolated as `group:<jid>`.
 - Gateway is now a loopback-only WebSocket daemon (`ws://127.0.0.1:18789`) that owns all providers/state; clients (CLI, WebChat, macOS app, nodes) connect to it. Start it explicitly (`clawdis gateway …`) or via Clawdis.app; helper subcommands no longer auto-spawn a gateway.
@@ -57,7 +199,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le
 ## 1.5.0 — 2025-12-05
 
 ### Breaking
-- Dropped all non-Pi agents (Claude, Codex, Gemini, Opencode); `inbound.reply.agent.kind` now only accepts `"pi"` and related CLI helpers have been removed.
+- Dropped all non-Pi agents (Claude, Codex, Gemini, Opencode); only the embedded Pi runtime remains and related CLI helpers have been removed.
 - Removed Twilio support and all related commands/options (webhook/up/provider flags/wait-poll); CLAWDIS is Baileys Web-only.
 
 ### Changes
@@ -84,7 +226,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le
 ## 1.4.0 — 2025-12-03
 
 ### Highlights
-- **Thinking directives & state:** `/t|/think|/thinking <level>` (aliases off|minimal|low|medium|high|max/highest). Inline applies to that message; directive-only message pins the level for the session; `/think:off` clears. Resolution: inline > session override > `inbound.reply.thinkingDefault` > off. Pi gets `--thinking <level>` (except off); other agents append cue words (`think` → `think hard` → `think harder` → `ultrathink`). Heartbeat probe uses `HEARTBEAT /think:high`.
+- **Thinking directives & state:** `/t|/think|/thinking <level>` (aliases off|minimal|low|medium|high|max/highest). Inline applies to that message; directive-only message pins the level for the session; `/think:off` clears. Resolution: inline > session override > `agent.thinkingDefault` > off. Pi gets `--thinking <level>` (except off); other agents append cue words (`think` → `think hard` → `think harder` → `ultrathink`). Heartbeat probe uses `HEARTBEAT /think:high`.
 - **Group chats (web provider):** Clawdis now fully supports WhatsApp groups: mention-gated triggers (including image-only @ mentions), recent group history injection, per-group sessions, sender attribution, and a first-turn primer with group subject/member roster; heartbeats are skipped for groups.
 - **Group session primer:** The first turn of a group session now tells the agent it is in a WhatsApp group and lists known members/subject so it can address the right speaker.
 - **Media failures are surfaced:** When a web auto-reply media fetch/send fails (e.g., HTTP 404), we now append a warning to the fallback text so you know the attachment was skipped.
@@ -126,7 +268,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le
 ## 1.3.0 — 2025-12-02
 
 ### Highlights
-- **Pluggable agents (Claude, Pi, Codex, Opencode):** `inbound.reply.agent` selects CLI/parser; per-agent argv builders and NDJSON parsers enable swapping without template changes.
+- **Pluggable agents (Claude, Pi, Codex, Opencode):** agent selection via config/CLI plus per-agent argv builders and NDJSON parsers enable swapping without template changes.
 - **Safety stop words:** `stop|esc|abort|wait|exit` immediately reply “Agent was aborted.” and mark the session so the next prompt is prefixed with an abort reminder.
 - **Agent session reliability:** Only Claude returns a stable `session_id`; others may reset between runs.
 
@@ -143,7 +285,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le
 - Batched inbound messages with timestamps; typing indicator after sends.
 - Watchdog restarts WhatsApp after long inactivity; heartbeat logging includes minutes since last message.
 - Early `allowFrom` filtering before decryption.
-- Same-phone mode with echo detection and optional `inbound.samePhoneMarker`.
+- Same-phone mode with echo detection and optional message prefix marker.
 
 ## 1.2.2 — 2025-11-28
 
@@ -173,10 +315,10 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le
 ## 1.1.0 — 2025-11-26
 
 ### Changes
-- Web auto-replies resize/recompress media and honor `inbound.reply.mediaMaxMb`.
+- Web auto-replies resize/recompress media and honor `agent.mediaMaxMb`.
 - Detect media kind, enforce provider caps (images ≤6MB, audio/video ≤16MB, docs ≤100MB).
 - `session.sendSystemOnce` and optional `sessionIntro`.
-- Typing indicator refresh during commands; configurable via `inbound.reply.typingIntervalSeconds`.
+- Typing indicator refresh during commands; configurable via `agent.typingIntervalSeconds`.
 - Optional audio transcription via external CLI.
 - Command replies return structured payload/meta; respect `mediaMaxMb`; log Claude metadata; include `cwd` in timeout messages.
 - Web provider refactor; logout command; web-only gateway start helper.

README.md

@@ -1,7 +1,7 @@
-# 🦞 CLAWDIS — WhatsApp & Telegram Gateway for AI Agents
+# 🦞 CLAWDIS — Personal AI Assistant
 
 <p align="center">
-  <img src="docs/whatsapp-clawd.jpg" alt="CLAWDIS" width="400">
+  <img src="https://raw.githubusercontent.com/steipete/clawdis/main/docs/whatsapp-clawd.jpg" alt="CLAWDIS" width="400">
 </p>
 
 <p align="center">
@@ -14,147 +14,176 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
 </p>
 
-**CLAWDIS** is a TypeScript/Node gateway that bridges WhatsApp (Web/Baileys) and Telegram (Bot API/grammY) to a local coding agent (**Pi**).
-It’s like having a genius lobster in your pocket 24/7 — but with a real control plane, companion apps, and a network model that won’t corrupt sessions.
+**Clawdis** is a *personal AI assistant* you run on your own devices.
+It answers you on the surfaces you already use (WhatsApp, Telegram, Discord, WebChat), can speak and listen on macOS/iOS, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.
+
+If you want a private, single-user assistant that feels local, fast, and always-on, this is it.
 
 ```
-WhatsApp / Telegram
-        │
-        ▼
-  ┌──────────────────────────┐
-  │          Gateway          │  ws://127.0.0.1:18789 (default: loopback)
-  │     (control UI)          │  http://127.0.0.1:18789/ui/
-  │     (single source)       │  tcp://0.0.0.0:18790 (optional Bridge)
-  └───────────┬───────────────┘
-              │
-              ├─ Pi agent (RPC)
-              ├─ CLI (clawdis …)
-              ├─ Control UI (browser)
-              ├─ macOS app (Clawdis.app)
-              └─ iOS node via Bridge + pairing
+Your surfaces
+   │
+   ▼
+┌───────────────────────────────┐
+│            Gateway            │  ws://127.0.0.1:18789
+│       (control plane)         │  tcp://0.0.0.0:18790 (optional Bridge)
+└──────────────┬────────────────┘
+               │
+               ├─ Pi agent (RPC)
+               ├─ CLI (clawdis …)
+               ├─ WebChat (browser)
+               ├─ macOS app (Clawdis.app)
+               └─ iOS node (Canvas + voice)
 ```
 
-## Why "CLAWDIS"?
+## What Clawdis does
 
-**CLAWDIS** = CLAW + TARDIS
+- **Personal assistant** — one user, one identity, one memory surface.
+- **Multi-surface inbox** — WhatsApp, Telegram, Discord, WebChat, macOS, iOS.
+- **Voice wake + push-to-talk** — local speech recognition on macOS/iOS.
+- **Canvas** — a live visual workspace you can drive from the agent.
+- **Automation-ready** — browser control, media handling, and tool streaming.
+- **Local-first control plane** — the Gateway owns state, everything else connects.
+- **Group chats** — mention-based by default, `/activation always|mention` per group (owner-only).
 
-Because every space lobster needs a time-and-space machine. The Doctor has a TARDIS. [Clawd](https://clawd.me) has a CLAWDIS. Both are blue. Both are chaotic. Both are loved.
+## How it works (short)
 
-## Features
+- **Gateway** is the single source of truth for sessions/providers.
+- **Loopback-first**: `ws://127.0.0.1:18789` by default.
+- **Bridge** (optional) exposes a paired-node port for iOS/Android.
+- **Agent runtime** is **Pi** in RPC mode.
 
-- 📱 **WhatsApp Integration** — Personal WhatsApp Web (Baileys)
-- ✈️ **Telegram (Bot API)** — DMs and groups via grammY
-- 🛰️ **Gateway control plane** — One long-lived gateway owns provider state; clients connect over WebSocket
-- 🤖 **Agent runtime** — Pi only (Pi CLI in RPC mode), with tool streaming
-- 💬 **Sessions** — Direct chats collapse into `main` by default; groups are isolated
-- 🔔 **Heartbeats** — Periodic check-ins for proactive AI
-- 🧭 **Clawd Browser** — Dedicated Chrome/Chromium profile with tabs + screenshot control (no interference with your daily browser)
-- 👥 **Group Chat Support** — Mention-based triggering
-- 📎 **Media Support** — Images, audio, documents, voice notes
-- 🎤 **Voice & transcription hooks** — Voice Wake (macOS/iOS) + optional transcription pipeline
-- 🔧 **Tool Streaming** — Real-time display (💻📄✍️📝)
-- 🖥️ **macOS Companion (Clawdis.app)** — Menu bar controls, Voice Wake, WebChat, onboarding, remote gateway control
-- 📱 **iOS node** — Pairs as a node, exposes a Canvas surface, forwards voice wake transcripts
+## Quick start (from source)
 
-Only the Pi CLI is supported now; legacy Claude/Codex/Gemini paths have been removed.
-
-## Network model (the “new reality”)
-
-- **One Gateway per host**. The Gateway is the only process allowed to own the WhatsApp Web session.
-- **Loopback-first**: the Gateway WebSocket listens on `ws://127.0.0.1:18789` by default.
-  - To expose it on your tailnet, set `gateway.bind: "tailnet"` (or run `clawdis gateway --bind tailnet`) and set `CLAWDIS_GATEWAY_TOKEN` (required for non-loopback binds).
-  - The browser Control UI is served from the Gateway at `http://<host>:18789/ui/` when assets are built.
-- **Bridge for nodes**: when enabled, the Gateway also exposes a bridge on `tcp://0.0.0.0:18790` for paired nodes (Bonjour-discoverable). For tailnet-only setups, set `bridge.bind: "tailnet"` in `~/.clawdis/clawdis.json`.
-- **Remote control**: use a VPN/tailnet or an SSH tunnel (`ssh -N -L 18789:127.0.0.1:18789 user@host`). The macOS app can drive this flow.
-- **Wide-Area Bonjour (optional)**: for auto-discovery across networks (Vienna ⇄ London) over Tailscale, use unicast DNS-SD on `clawdis.internal.`; see `docs/bonjour.md`.
-
-## Codebase
-
-- **TypeScript (ESM)**: CLI + Gateway live in `src/` and run on Node ≥ 22.
-- **macOS app (Swift)**: menu bar companion lives in `apps/macos/`.
-- **iOS app (Swift)**: iOS node prototype lives in `apps/ios/`.
-
-## Quick Start
-
-Runtime requirement: **Node ≥22.0.0** (not bundled). The macOS app and CLI both use the host runtime; install via Homebrew or official installers before running `clawdis`.
+Runtime: **Node ≥22** + **pnpm**.
 
 ```bash
-# From source (recommended while the npm package is still settling)
 pnpm install
 pnpm build
 pnpm ui:build
 
-# Link your WhatsApp (stores creds under ~/.clawdis/credentials)
+# Link WhatsApp (stores creds in ~/.clawdis/credentials)
 pnpm clawdis login
 
-# Start the gateway (WebSocket control plane)
+# Start the gateway
 pnpm clawdis gateway --port 18789 --verbose
 
-# Open the browser Control UI (after ui:build)
-# http://127.0.0.1:18789/ui/
+# Dev loop (auto-reload on TS changes)
+pnpm gateway:watch
 
-# Send a WhatsApp message (WhatsApp sends go through the Gateway)
-pnpm clawdis send --to +1234567890 --message "Hello from the CLAWDIS!"
+# Send a message
+pnpm clawdis send --to +1234567890 --message "Hello from Clawdis"
 
-# Talk to the agent (optionally deliver back to WhatsApp/Telegram)
+# Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Discord)
 pnpm clawdis agent --message "Ship checklist" --thinking high
-
-# If the port is busy, force-kill listeners then start
-pnpm clawdis gateway --force
 ```
 
-### Agent workspace + skills
+If you run from source, prefer `pnpm clawdis …` (not global `clawdis`).
 
-Clawdis runs the embedded agent with its working directory set to the agent workspace (default: `~/clawd`, configurable via `inbound.workspace`).
+## Chat commands
 
-- Workspace files injected into the system prompt: `AGENTS.md`, `SOUL.md`, `TOOLS.md`
-- Custom skills: `<workspace>/skills/<skill-name>/SKILL.md` (default: `~/clawd/skills/<skill-name>/SKILL.md`; only this location is scanned)
+Send these in WhatsApp/Telegram/WebChat (group commands are owner-only):
 
-## Companion Apps
+- `/status` — health + session info (group shows activation mode)
+- `/new` or `/reset` — reset the session
+- `/think <level>` — off|minimal|low|medium|high
+- `/verbose on|off`
+- `/restart` — restart the gateway (owner-only in groups)
+- `/activation mention|always` — group activation toggle (groups only)
 
-### macOS Companion (Clawdis.app)
+## Architecture
 
-- A menu bar app that can start/stop the Gateway, show health/presence, and provide a local ops UI.
-- Instances UI shows friendly hardware model names (from the vendored MIT dataset under `apps/macos/Sources/Clawdis/Resources/DeviceModels/`).
-- **Voice Wake** (on-device speech recognition) and Push-to-talk overlay.
-- **WebChat** embed + debug tooling (logs, status, heartbeats, sessions).
-- Hosts **PeekabooBridge** for UI automation brokering (for clawd workflows).
+### TypeScript Gateway (src/gateway/server.ts)
+- **Single HTTP+WS server** on `ws://127.0.0.1:18789` (bind policy: loopback/lan/tailnet/auto). The first frame must be `connect`; AJV validates frames against TypeBox schemas (`src/gateway/protocol`).
+- **Single source of truth** for sessions, providers, cron, voice wake, and presence. Methods cover `send`, `agent`, `chat.*`, `sessions.*`, `config.*`, `cron.*`, `voicewake.*`, `node.*`, `system-*`, `wake`.
+- **Events + snapshot**: handshake returns a snapshot (presence/health) and declares event types; runtime events include `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `cron`, `node.pair.*`, `voicewake.changed`, `shutdown`.
+- **Idempotency & safety**: `send`/`agent`/`chat.send` require idempotency keys with a TTL cache (5 min, cap 1000) to avoid double‑sends on reconnects; payload sizes are capped per connection.
+- **Bridge for nodes**: optional TCP bridge (`src/infra/bridge/server.ts`) is newline‑delimited JSON frames (`hello`, pairing, RPC, `invoke`); node connect/disconnect is surfaced into presence.
+- **Control UI + Canvas Host**: HTTP serves `/ui` assets (if built) and can host a live‑reload Canvas host for nodes (`src/canvas-host/server.ts`), injecting the A2UI postMessage bridge.
 
-### Voice Wake reply routing
+### iOS app (apps/ios)
+- **Discovery + pairing**: Bonjour discovery via `BridgeDiscoveryModel` (NWBrowser). `BridgeConnectionController` auto‑connects using Keychain token or allows manual host/port.
+- **Node runtime**: `BridgeSession` (actor) maintains the `NWConnection`, hello handshake, ping/pong, RPC requests, and `invoke` callbacks.
+- **Capabilities + commands**: advertises `canvas`, `screen`, `camera`, `voiceWake` (settings‑driven) and executes `canvas.*`, `canvas.a2ui.*`, `camera.*`, `screen.record` (`NodeAppModel.handleInvoke`).
+- **Canvas**: `WKWebView` with bundled Canvas scaffold + A2UI, JS eval, snapshot capture, and `clawdis://` deep‑link interception (`ScreenController`).
+- **Voice + deep links**: voice wake sends `voice.transcript` events; `clawdis://agent` links emit `agent.request`. Voice wake triggers sync via `voicewake.get` + `voicewake.changed`.
 
-Voice Wake sends messages into the `main` session and replies on the **last used surface**:
+## Companion apps
 
-- WhatsApp: last direct message you sent/received.
-- Telegram: last DM chat id (bot mode).
-- WebChat: last WebChat thread you used.
+The **macOS app is critical**: it runs the menu‑bar control plane, owns local permissions (TCC), hosts Voice Wake, exposes WebChat/debug tools, and coordinates local/remote gateway mode. Most “assistant” UX lives here.
 
-If delivery fails (e.g. WhatsApp disconnected / Telegram token missing), Clawdis logs the error and you can still inspect the run via WebChat/session logs.
+### macOS (Clawdis.app)
 
-Build/run the mac app with `./scripts/restart-mac.sh` (packages, installs, and launches), or `swift build --package-path apps/macos && open dist/Clawdis.app`.
+- Menu bar control for the Gateway and health.
+- Voice Wake + push-to-talk overlay.
+- WebChat + debug tools.
+- Remote gateway control over SSH.
+
+Build/run: `./scripts/restart-mac.sh` (packages + launches).
 
 ### iOS node (internal)
 
-The iOS node app is an internal/prototype app that connects as a **remote node**:
+- Pairs as a node via the Bridge.
+- Voice trigger forwarding + Canvas surface.
+- Controlled via `clawdis nodes …`.
 
-- **Voice trigger:** forwards transcripts into the Gateway (agent runs + wakeups).
-- **Canvas screen:** a WKWebView + `<canvas>` surface the agent can control (via `canvas.eval` / `canvas.snapshot` over `node.invoke`).
-- **Discovery + pairing:** finds the bridge via Bonjour (`_clawdis-bridge._tcp`) and uses Gateway-owned pairing (`clawdis nodes pending|approve`); `clawdis nodes status` shows paired nodes + capabilities.
+Runbook: `docs/ios/connect.md`.
 
-Runbook: `docs/ios/connect.md`
+### Android node (internal)
+
+- Pairs via the same Bridge + pairing flow as iOS.
+- Exposes Canvas, Camera, and Screen capture commands.
+- Runbook: `docs/android/connect.md`.
+
+## Agent workspace + skills
+
+- Workspace root: `~/clawd` (configurable via `agent.workspace`).
+- Injected prompt files: `AGENTS.md`, `SOUL.md`, `TOOLS.md`.
+- Skills: `~/clawd/skills/<skill>/SKILL.md`.
 
 ## Configuration
 
-Create `~/.clawdis/clawdis.json`:
+Minimal `~/.clawdis/clawdis.json`:
 
 ```json5
 {
-  inbound: {
+  routing: {
     allowFrom: ["+1234567890"]
   }
 }
 ```
 
-Optional: enable/configure clawd’s dedicated browser control (defaults are already on):
+### WhatsApp
+
+- Link the device: `pnpm clawdis login` (stores creds in `~/.clawdis/credentials`).
+- Allowlist who can talk to the assistant via `routing.allowFrom`.
+
+### Telegram
+
+- Set `TELEGRAM_BOT_TOKEN` or `telegram.botToken` (env wins).
+- Optional: set `telegram.requireMention`, `telegram.allowFrom`, or `telegram.webhookUrl` as needed.
+
+```json5
+{
+  telegram: {
+    botToken: "123456:ABCDEF"
+  }
+}
+```
+
+### Discord
+
+- Set `DISCORD_BOT_TOKEN` or `discord.token` (env wins).
+- Optional: set `discord.requireMention`, `discord.allowFrom`, or `discord.mediaMaxMb` as needed.
+
+```json5
+{
+  discord: {
+    token: "1234abcd"
+  }
+}
+```
+
+Browser control (optional):
 
 ```json5
 {
@@ -166,99 +195,34 @@ Optional: enable/configure clawd’s dedicated browser control (defaults are alr
 }
 ```
 
-## Documentation
+## Docs
 
-- [Configuration Guide](./docs/configuration.md)
-- [Gateway runbook](./docs/gateway.md)
-- [Web surfaces (Control UI)](./docs/web.md)
-- [Discovery + transports](./docs/discovery.md)
-- [Bonjour / mDNS + Wide-Area Bonjour](./docs/bonjour.md)
-- [Agent Runtime](./docs/agent.md)
-- [Group Chats](./docs/group-messages.md)
-- [Security](./docs/security.md)
-- [Troubleshooting](./docs/troubleshooting.md)
-- [The Lore](./docs/lore.md) 🦞
-- [Telegram (Bot API)](./docs/telegram.md)
-- [iOS node runbook](./docs/ios/connect.md)
-- [macOS app spec](./docs/clawdis-mac.md)
+- [`docs/index.md`](docs/index.md) (overview)
+- [`docs/configuration.md`](docs/configuration.md)
+- [`docs/group-messages.md`](docs/group-messages.md)
+- [`docs/gateway.md`](docs/gateway.md)
+- [`docs/web.md`](docs/web.md)
+- [`docs/discovery.md`](docs/discovery.md)
+- [`docs/agent.md`](docs/agent.md)
+- [`docs/discord.md`](docs/discord.md)
+- Webhooks + external triggers: [`docs/webhook.md`](docs/webhook.md)
+- Gmail hooks (email → wake): [`docs/gmail-pubsub.md`](docs/gmail-pubsub.md)
+
+## Email hooks (Gmail)
+
+```bash
+clawdis hooks gmail setup --account you@gmail.com
+clawdis hooks gmail run
+```
+- [`docs/security.md`](docs/security.md)
+- [`docs/troubleshooting.md`](docs/troubleshooting.md)
+- [`docs/ios/connect.md`](docs/ios/connect.md)
+- [`docs/clawdis-mac.md`](docs/clawdis-mac.md)
 
 ## Clawd
 
-CLAWDIS was built for **Clawd**, a space lobster AI assistant. See the full setup in [`docs/clawd.md`](./docs/clawd.md).
+Clawdis was built for **Clawd**, a space lobster AI assistant.
 
-- 🦞 **Clawd's Home:** [clawd.me](https://clawd.me)
-- 📜 **Clawd's Soul:** [soul.md](https://soul.md)
-- 👨‍💻 **Peter's Blog:** [steipete.me](https://steipete.me)
-- 🐦 **Twitter:** [@steipete](https://twitter.com/steipete)
-
-## Provider
-
-If you’re running from source, use `pnpm clawdis …` instead of `clawdis …`.
-
-### WhatsApp Web
-```bash
-clawdis login      # scan QR, store creds
-clawdis gateway    # run Gateway (WS on 127.0.0.1:18789)
-```
-
-### Telegram (Bot API)
-Bot-mode support (grammY only) shares the same `main` session as WhatsApp/WebChat, with groups kept isolated. Text/media sends work via `clawdis send --provider telegram` (reads `TELEGRAM_BOT_TOKEN` or `telegram.botToken`). Webhook mode is supported; see `docs/telegram.md` for setup and limits.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `clawdis login` | Link WhatsApp Web via QR |
-| `clawdis send` | Send a message (WhatsApp default; `--provider telegram` for bot mode). WhatsApp sends go via the Gateway WS; Telegram sends are direct. |
-| `clawdis agent` | Talk directly to the agent (no WhatsApp send) |
-| `clawdis browser ...` | Manage clawd’s dedicated browser (status/tabs/open/screenshot). |
-| `clawdis gateway` | Start the Gateway server (WS control plane). Params: `--port`, `--bind`, `--token`, `--force`, `--verbose`. |
-| `clawdis gateway health|status|send|agent|call` | Gateway WS clients; assume a running gateway. |
-| `clawdis wake` | Enqueue a system event and optionally trigger a heartbeat via the Gateway. |
-| `clawdis cron ...` | Manage scheduled jobs (via Gateway). |
-| `clawdis nodes ...` | Manage nodes (pairing + status) via the Gateway. |
-| `clawdis status` | Web session health + session store summary |
-| `clawdis health` | Reports cached provider state from the running gateway. |
-
-#### Gateway client params (WS only)
-- `--url` (default `ws://127.0.0.1:18789`)
-- `--token` (shared secret if set on the gateway)
-- `--timeout <ms>` (WS call timeout)
-
-#### Send
-- `--provider whatsapp|telegram` (default whatsapp)
-- `--media <path-or-url>`
-- `--json` for machine-readable output
-
-#### Health
-- Reads gateway/provider state (no direct Baileys socket from the CLI).
-
-In chat, send `/status` to see if the agent is reachable, how much context the session has used, and the current thinking/verbose toggles—no agent call required.
-`/status` also shows whether your WhatsApp web session is linked and how long ago the creds were refreshed so you know when to re-scan the QR.
-
-### Sessions, surfaces, and WebChat
-
-- Direct chats now share a canonical session key `main` by default (configurable via `inbound.session.mainKey`). Groups stay isolated as `group:<jid>`.
-- WebChat attaches to `main` and hydrates history from `~/.clawdis/sessions/<SessionId>.jsonl`, so desktop view mirrors WhatsApp/Telegram turns.
-- Inbound contexts carry a `Surface` hint (e.g., `whatsapp`, `webchat`, `telegram`) for logging; replies still go back to the originating surface deterministically.
-- Every inbound message is wrapped for the agent as `[Surface FROM HOST/IP TIMESTAMP] body`:
-  - WhatsApp: `[WhatsApp +15551234567 2025-12-09 12:34] …`
-- Telegram: `[Telegram Ada Lovelace (@ada_bot) id:123456789 2025-12-09 12:34] …`
-  - WebChat: `[WebChat my-mac.local 10.0.0.5 2025-12-09 12:34] …`
-  This keeps the model aware of the transport, sender, host, and time without relying on implicit context.
-
-## Credits
-
-- **Peter Steinberger** ([@steipete](https://twitter.com/steipete)) — Creator
-- **Mario Zechner** ([@badlogicgames](https://twitter.com/badlogicgames)) — Pi, security testing
-- **Clawd** 🦞 — The space lobster who demanded a better name
-
-## License
-
-MIT — Free as a lobster in the ocean.
-
----
-
-*"We're all just playing with our own prompts."*
-
-🦞💙
+- https://clawd.me
+- https://soul.md
+- https://steipete.me

Swabble/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.2.0 — 2025-12-23
+
+### Highlights
+- Added `SwabbleKit` (multi-platform wake-word gate utilities with segment-aware gap detection).
+- Swabble package now supports iOS + macOS consumers; CLI remains macOS 26-only.
+
+### Changes
+- CLI wake-word matching/stripping routed through `SwabbleKit` helpers.
+- Speech pipeline types now explicitly gated to macOS 26 / iOS 26 availability.

Swabble/Package.resolved

@@ -1,15 +1,6 @@
 {
-  "originHash" : "3018b2c8c183d55b57ad0c4526b2380ac3b957d13a3a86e1b2845e81323c443a",
+  "originHash" : "2012d083159d375d07febbc184c592c569d7ab48247045e35a762e3269d4cadc",
   "pins" : [
-    {
-      "identity" : "commander",
-      "kind" : "remoteSourceControl",
-      "location" : "https://github.com/steipete/Commander.git",
-      "state" : {
-        "revision" : "8b8cb4f34315ce9e5307b3a2bcd77ff73f586a02",
-        "version" : "0.2.0"
-      }
-    },
     {
       "identity" : "swift-syntax",
       "kind" : "remoteSourceControl",

Swabble/Package.swift

@@ -4,14 +4,16 @@ import PackageDescription
 let package = Package(
     name: "swabble",
     platforms: [
-        .macOS(.v26),
+        .macOS(.v15),
+        .iOS(.v17),
     ],
     products: [
         .library(name: "Swabble", targets: ["Swabble"]),
+        .library(name: "SwabbleKit", targets: ["SwabbleKit"]),
         .executable(name: "swabble", targets: ["SwabbleCLI"]),
     ],
     dependencies: [
-        .package(url: "https://github.com/steipete/Commander.git", from: "0.2.0"),
+        .package(path: "../Peekaboo/Commander"),
         .package(url: "https://github.com/apple/swift-testing", from: "0.99.0"),
     ],
     targets: [
@@ -19,13 +21,30 @@ let package = Package(
             name: "Swabble",
             path: "Sources/SwabbleCore",
             swiftSettings: []),
+        .target(
+            name: "SwabbleKit",
+            path: "Sources/SwabbleKit",
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+            ]),
         .executableTarget(
             name: "SwabbleCLI",
             dependencies: [
                 "Swabble",
+                "SwabbleKit",
                 .product(name: "Commander", package: "Commander"),
             ],
             path: "Sources/swabble"),
+        .testTarget(
+            name: "SwabbleKitTests",
+            dependencies: [
+                "SwabbleKit",
+                .product(name: "Testing", package: "swift-testing"),
+            ],
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+                .enableExperimentalFeature("SwiftTesting"),
+            ]),
         .testTarget(
             name: "swabbleTests",
             dependencies: [

Swabble/README.md

@@ -1,9 +1,10 @@
 # 🎙️ swabble — Speech.framework wake-word hook daemon (macOS 26)
 
-swabble is a Swift 6.2, macOS 26-only rewrite of the brabble voice daemon. It listens on your mic, gates on a wake word, transcribes locally using Apple's new SpeechAnalyzer + SpeechTranscriber, then fires a shell hook with the transcript. No cloud calls, no Whisper binaries.
+swabble is a Swift 6.2 wake-word hook daemon. The CLI targets macOS 26 (SpeechAnalyzer + SpeechTranscriber). The shared `SwabbleKit` target is multi-platform and exposes wake-word gating utilities for iOS/macOS apps.
 
 - **Local-only**: Speech.framework on-device models; zero network usage.
 - **Wake word**: Default `clawd` (aliases `claude`), optional `--no-wake` bypass.
+- **SwabbleKit**: Shared wake gate utilities (gap-based gating when you provide speech segments).
 - **Hooks**: Run any command with prefix/env, cooldown, min_chars, timeout.
 - **Services**: launchd helper stubs for start/stop/install.
 - **File transcribe**: TXT or SRT with time ranges (using AttributedString splits).
@@ -30,7 +31,7 @@ swift run swabble transcribe /path/to/audio.m4a --format srt --output out.srt
 ```
 
 ## Use as a library
-Add swabble as a SwiftPM dependency and import the `Swabble` product to reuse the Speech pipeline, config loader, hook executor, and transcript store in your own app:
+Add swabble as a SwiftPM dependency and import the `Swabble` or `SwabbleKit` product:
 
 ```swift
 // Package.swift
@@ -38,7 +39,10 @@ dependencies: [
     .package(url: "https://github.com/steipete/swabble.git", branch: "main"),
 ],
 targets: [
-    .target(name: "MyApp", dependencies: [.product(name: "Swabble", package: "swabble")]),
+    .target(name: "MyApp", dependencies: [
+        .product(name: "Swabble", package: "swabble"),     // Speech pipeline (macOS 26+ / iOS 26+)
+        .product(name: "SwabbleKit", package: "swabble"),  // Wake-word gate utilities (iOS 17+ / macOS 15+)
+    ]),
 ]
 ```
 
@@ -93,7 +97,7 @@ Environment variables:
 
 ## Speech pipeline
 - `AVAudioEngine` tap → `BufferConverter` → `AnalyzerInput` → `SpeechAnalyzer` with a `SpeechTranscriber` module.
-- Requests volatile + final results; wake gating is string match on partial/final.
+- Requests volatile + final results; the CLI uses text-only wake gating today.
 - Authorization requested at first start; requires macOS 26 + new Speech.framework APIs.
 
 ## Development

Swabble/Sources/SwabbleCore/Speech/SpeechPipeline.swift

@@ -2,11 +2,13 @@ import AVFoundation
 import Foundation
 import Speech
 
+@available(macOS 26.0, iOS 26.0, *)
 public struct SpeechSegment: Sendable {
     public let text: String
     public let isFinal: Bool
 }
 
+@available(macOS 26.0, iOS 26.0, *)
 public enum SpeechPipelineError: Error {
     case authorizationDenied
     case analyzerFormatUnavailable
@@ -14,6 +16,7 @@ public enum SpeechPipelineError: Error {
 }
 
 /// Live microphone → SpeechAnalyzer → SpeechTranscriber pipeline.
+@available(macOS 26.0, iOS 26.0, *)
 public actor SpeechPipeline {
     private struct UnsafeBuffer: @unchecked Sendable { let buffer: AVAudioPCMBuffer }
 

Swabble/Sources/SwabbleKit/WakeWordGate.swift

@@ -0,0 +1,192 @@
+import Foundation
+
+public struct WakeWordSegment: Sendable, Equatable {
+    public let text: String
+    public let start: TimeInterval
+    public let duration: TimeInterval
+    public let range: Range<String.Index>?
+
+    public init(text: String, start: TimeInterval, duration: TimeInterval, range: Range<String.Index>? = nil) {
+        self.text = text
+        self.start = start
+        self.duration = duration
+        self.range = range
+    }
+
+    public var end: TimeInterval { self.start + self.duration }
+}
+
+public struct WakeWordGateConfig: Sendable, Equatable {
+    public var triggers: [String]
+    public var minPostTriggerGap: TimeInterval
+    public var minCommandLength: Int
+
+    public init(
+        triggers: [String],
+        minPostTriggerGap: TimeInterval = 0.45,
+        minCommandLength: Int = 1)
+    {
+        self.triggers = triggers
+        self.minPostTriggerGap = minPostTriggerGap
+        self.minCommandLength = minCommandLength
+    }
+}
+
+public struct WakeWordGateMatch: Sendable, Equatable {
+    public let triggerEndTime: TimeInterval
+    public let postGap: TimeInterval
+    public let command: String
+
+    public init(triggerEndTime: TimeInterval, postGap: TimeInterval, command: String) {
+        self.triggerEndTime = triggerEndTime
+        self.postGap = postGap
+        self.command = command
+    }
+}
+
+public enum WakeWordGate {
+    private struct Token {
+        let normalized: String
+        let start: TimeInterval
+        let end: TimeInterval
+        let range: Range<String.Index>?
+        let text: String
+    }
+
+    private struct TriggerTokens {
+        let tokens: [String]
+    }
+
+    public static func match(
+        transcript: String,
+        segments: [WakeWordSegment],
+        config: WakeWordGateConfig)
+    -> WakeWordGateMatch? {
+        let triggerTokens = self.normalizeTriggers(config.triggers)
+        guard !triggerTokens.isEmpty else { return nil }
+
+        let tokens = self.normalizeSegments(segments)
+        guard !tokens.isEmpty else { return nil }
+
+        var best: (index: Int, triggerEnd: TimeInterval, gap: TimeInterval)?
+
+        for trigger in triggerTokens {
+            let count = trigger.tokens.count
+            guard count > 0, tokens.count > count else { continue }
+            for i in 0...(tokens.count - count - 1) {
+                let matched = (0..<count).allSatisfy { tokens[i + $0].normalized == trigger.tokens[$0] }
+                if !matched { continue }
+
+                let triggerEnd = tokens[i + count - 1].end
+                let nextToken = tokens[i + count]
+                let gap = nextToken.start - triggerEnd
+                if gap < config.minPostTriggerGap { continue }
+
+                if let best, i <= best.index { continue }
+
+                best = (i, triggerEnd, gap)
+            }
+        }
+
+        guard let best else { return nil }
+        let command = self.commandText(transcript: transcript, segments: segments, triggerEndTime: best.triggerEnd)
+            .trimmingCharacters(in: Self.whitespaceAndPunctuation)
+        guard command.count >= config.minCommandLength else { return nil }
+        return WakeWordGateMatch(triggerEndTime: best.triggerEnd, postGap: best.gap, command: command)
+    }
+
+    public static func commandText(
+        transcript: String,
+        segments: [WakeWordSegment],
+        triggerEndTime: TimeInterval)
+    -> String {
+        let threshold = triggerEndTime + 0.001
+        for segment in segments where segment.start >= threshold {
+            if normalizeToken(segment.text).isEmpty { continue }
+            if let range = segment.range {
+                let slice = transcript[range.lowerBound...]
+                return String(slice).trimmingCharacters(in: Self.whitespaceAndPunctuation)
+            }
+            break
+        }
+
+        let text = segments
+            .filter { $0.start >= threshold && !self.normalizeToken($0.text).isEmpty }
+            .map(\.text)
+            .joined(separator: " ")
+        return text.trimmingCharacters(in: Self.whitespaceAndPunctuation)
+    }
+
+    public static func matchesTextOnly(text: String, triggers: [String]) -> Bool {
+        guard !text.isEmpty else { return false }
+        let normalized = text.lowercased()
+        for trigger in triggers {
+            let token = trigger.trimmingCharacters(in: self.whitespaceAndPunctuation).lowercased()
+            if token.isEmpty { continue }
+            if normalized.contains(token) { return true }
+        }
+        return false
+    }
+
+    public static func stripWake(text: String, triggers: [String]) -> String {
+        var out = text
+        for trigger in triggers {
+            let token = trigger.trimmingCharacters(in: self.whitespaceAndPunctuation)
+            guard !token.isEmpty else { continue }
+            out = out.replacingOccurrences(of: token, with: "", options: [.caseInsensitive])
+        }
+        return out.trimmingCharacters(in: self.whitespaceAndPunctuation)
+    }
+
+    private static func normalizeTriggers(_ triggers: [String]) -> [TriggerTokens] {
+        var output: [TriggerTokens] = []
+        for trigger in triggers {
+            let tokens = trigger
+                .split(whereSeparator: { $0.isWhitespace })
+                .map { self.normalizeToken(String($0)) }
+                .filter { !$0.isEmpty }
+            if tokens.isEmpty { continue }
+            output.append(TriggerTokens(tokens: tokens))
+        }
+        return output
+    }
+
+    private static func normalizeSegments(_ segments: [WakeWordSegment]) -> [Token] {
+        segments.compactMap { segment in
+            let normalized = self.normalizeToken(segment.text)
+            guard !normalized.isEmpty else { return nil }
+            return Token(
+                normalized: normalized,
+                start: segment.start,
+                end: segment.end,
+                range: segment.range,
+                text: segment.text)
+        }
+    }
+
+    private static func normalizeToken(_ token: String) -> String {
+        token
+            .trimmingCharacters(in: self.whitespaceAndPunctuation)
+            .lowercased()
+    }
+
+    private static let whitespaceAndPunctuation = CharacterSet.whitespacesAndNewlines
+        .union(.punctuationCharacters)
+}
+
+#if canImport(Speech)
+import Speech
+
+public enum WakeWordSpeechSegments {
+    public static func from(transcription: SFTranscription, transcript: String) -> [WakeWordSegment] {
+        transcription.segments.map { segment in
+            let range = Range(segment.substringRange, in: transcript)
+            return WakeWordSegment(
+                text: segment.substring,
+                start: segment.timestamp,
+                duration: segment.duration,
+                range: range)
+        }
+    }
+}
+#endif

Swabble/Sources/swabble/CLI/CLIRegistry.swift

@@ -1,6 +1,7 @@
 import Commander
 import Foundation
 
+@available(macOS 26.0, *)
 @MainActor
 enum CLIRegistry {
     static var descriptors: [CommandDescriptor] {

Swabble/Sources/swabble/Commands/ServeCommand.swift

@@ -1,7 +1,9 @@
 import Commander
 import Foundation
 import Swabble
+import SwabbleKit
 
+@available(macOS 26.0, *)
 @MainActor
 struct ServeCommand: ParsableCommand {
     @Option(name: .long("config"), help: "Path to config JSON") var configPath: String?
@@ -68,17 +70,12 @@ struct ServeCommand: ParsableCommand {
     }
 
     private static func matchesWake(text: String, cfg: SwabbleConfig) -> Bool {
-        let lowered = text.lowercased()
-        if lowered.contains(cfg.wake.word.lowercased()) { return true }
-        return cfg.wake.aliases.contains(where: { lowered.contains($0.lowercased()) })
+        let triggers = [cfg.wake.word] + cfg.wake.aliases
+        return WakeWordGate.matchesTextOnly(text: text, triggers: triggers)
     }
 
     private static func stripWake(text: String, cfg: SwabbleConfig) -> String {
-        var out = text
-        out = out.replacingOccurrences(of: cfg.wake.word, with: "", options: [.caseInsensitive])
-        for alias in cfg.wake.aliases {
-            out = out.replacingOccurrences(of: alias, with: "", options: [.caseInsensitive])
-        }
-        return out.trimmingCharacters(in: .whitespacesAndNewlines)
+        let triggers = [cfg.wake.word] + cfg.wake.aliases
+        return WakeWordGate.stripWake(text: text, triggers: triggers)
     }
 }

Swabble/Sources/swabble/main.swift

@@ -1,6 +1,7 @@
 import Commander
 import Foundation
 
+@available(macOS 26.0, *)
 @MainActor
 private func runCLI() async -> Int32 {
     do {
@@ -15,6 +16,7 @@ private func runCLI() async -> Int32 {
     }
 }
 
+@available(macOS 26.0, *)
 @MainActor
 private func dispatch(invocation: CommandInvocation) async throws {
     let parsed = invocation.parsedValues
@@ -95,5 +97,10 @@ private func dispatch(invocation: CommandInvocation) async throws {
     }
 }
 
-let exitCode = await runCLI()
-exit(exitCode)
+if #available(macOS 26.0, *) {
+    let exitCode = await runCLI()
+    exit(exitCode)
+} else {
+    fputs("error: swabble requires macOS 26 or newer\n", stderr)
+    exit(1)
+}

Swabble/Tests/SwabbleKitTests/WakeWordGateTests.swift

@@ -0,0 +1,63 @@
+import Foundation
+import Testing
+import SwabbleKit
+
+@Suite struct WakeWordGateTests {
+    @Test func matchRequiresGapAfterTrigger() {
+        let transcript = "hey clawd do thing"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.35, 0.1),
+                ("thing", 0.5, 0.1),
+            ])
+        let config = WakeWordGateConfig(triggers: ["clawd"], minPostTriggerGap: 0.3)
+        #expect(WakeWordGate.match(transcript: transcript, segments: segments, config: config) == nil)
+    }
+
+    @Test func matchAllowsGapAndExtractsCommand() {
+        let transcript = "hey clawd do thing"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.9, 0.1),
+                ("thing", 1.1, 0.1),
+            ])
+        let config = WakeWordGateConfig(triggers: ["clawd"], minPostTriggerGap: 0.3)
+        let match = WakeWordGate.match(transcript: transcript, segments: segments, config: config)
+        #expect(match?.command == "do thing")
+    }
+
+    @Test func matchHandlesMultiWordTriggers() {
+        let transcript = "hey clawd do it"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.8, 0.1),
+                ("it", 1.0, 0.1),
+            ])
+        let config = WakeWordGateConfig(triggers: ["hey clawd"], minPostTriggerGap: 0.3)
+        let match = WakeWordGate.match(transcript: transcript, segments: segments, config: config)
+        #expect(match?.command == "do it")
+    }
+}
+
+private func makeSegments(
+    transcript: String,
+    words: [(String, TimeInterval, TimeInterval)])
+-> [WakeWordSegment] {
+    var searchStart = transcript.startIndex
+    var output: [WakeWordSegment] = []
+    for (word, start, duration) in words {
+        let range = transcript.range(of: word, range: searchStart..<transcript.endIndex)
+        output.append(WakeWordSegment(text: word, start: start, duration: duration, range: range))
+        if let range { searchStart = range.upperBound }
+    }
+    return output
+}

Swabble/docs/spec.md

@@ -1,11 +1,12 @@
 # swabble — macOS 26 speech hook daemon (Swift 6.2)
 
-Goal: brabble-style always-on voice hook for macOS 26 using Apple Speech.framework (SpeechAnalyzer + SpeechTranscriber) instead of whisper.cpp. Local-only, wake word gated, dispatches a shell hook with the transcript.
+Goal: brabble-style always-on voice hook for macOS 26 using Apple Speech.framework (SpeechAnalyzer + SpeechTranscriber) instead of whisper.cpp. Local-only, wake word gated, dispatches a shell hook with the transcript. Shared wake-gate utilities live in `SwabbleKit` for reuse by other apps (iOS/macOS).
 
 ## Requirements
 - macOS 26+, Swift 6.2, Speech.framework with on-device assets.
 - Local only; no network calls during transcription.
 - Wake word gating (default "clawd" plus aliases) with bypass flag `--no-wake`.
+- `SwabbleKit` target (multi-platform) providing wake-word gating helpers that can use speech segment timing to require a post-trigger gap.
 - Hook execution with cooldown, min_chars, timeout, prefix, env vars.
 - Simple config at `~/.config/swabble/config.json` (JSON, Codable) — no TOML.
 - CLI implemented with Commander (SwiftPM package `steipete/Commander`); core types are available via the SwiftPM library product `Swabble` for embedding.
@@ -17,7 +18,7 @@ Goal: brabble-style always-on voice hook for macOS 26 using Apple Speech.framewo
 - **CLI layer (Commander)**: Root command `swabble` with subcommands `serve`, `transcribe`, `test-hook`, `mic list|set`, `doctor`, `health`, `tail-log`. Runtime flags from Commander (`-v/--verbose`, `--json-output`, `--log-level`). Custom `--config` path applies everywhere.
 - **Config**: `SwabbleConfig` Codable. Fields: audio device name/index, wake (enabled/word/aliases/sensitivity placeholder), hook (command/args/prefix/cooldown/min_chars/timeout/env), logging (level, format), transcripts (enabled, max kept), speech (locale, enableEtiquetteReplacements flag). Stored JSON; default written by `setup`.
 - **Audio + Speech pipeline**: `SpeechPipeline` wraps `AVAudioEngine` input → `SpeechAnalyzer` with `SpeechTranscriber` module. Emits partial/final transcripts via async stream. Requests `.audioTimeRange` when transcripts enabled. Handles Speech permission and asset download prompts ahead of capture.
-- **Wake gate**: text-based keyword match against latest partial/final; strips wake term before hook dispatch. `--no-wake` disables.
+- **Wake gate**: CLI currently uses text-only keyword match; shared `SwabbleKit` gate can enforce a minimum pause between the wake word and the next token when speech segments are available. `--no-wake` disables gating.
 - **Hook executor**: async `HookExecutor` spawns `Process` with configured args, prefix substitution `${hostname}`. Enforces cooldown + timeout; injects env `SWABBLE_TEXT`, `SWABBLE_PREFIX` plus user env map.
 - **Transcripts store**: in-memory ring buffer; optional persisted JSON lines under `~/Library/Application Support/swabble/transcripts.log`.
 - **Logging**: simple structured logger to stderr; respects log level.
@@ -25,7 +26,7 @@ Goal: brabble-style always-on voice hook for macOS 26 using Apple Speech.framewo
 ## Out of scope (initial cut)
 - Model management (Speech handles assets).
 - Launchd helper (planned follow-up).
-- Advanced wake-word detector (text match only for now).
+- Advanced wake-word detector (segment-aware gate now lives in `SwabbleKit`; CLI still text-only until segment timing is plumbed through).
 
 ## Open decisions
 - Whether to expose a UNIX control socket for `status`/`health` (currently planned as stdin/out direct calls).

appcast.xml

@@ -1,21 +1,31 @@
-<?xml version="1.0" encoding="utf-8"?>
-<rss version="2.0"
-     xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle"
-     xmlns:dc="http://purl.org/dc/elements/1.1/">
-  <channel>
-    <title>Clawdis Updates</title>
-    <link>https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml</link>
-    <description>Signed update feed for the Clawdis macOS companion app.</description>
-    <item>
-      <title>Clawdis 2.0.0-beta1</title>
-      <sparkle:releaseNotesLink>https://github.com/steipete/clawdis/releases/tag/v2.0.0-beta1</sparkle:releaseNotesLink>
-      <pubDate>Fri, 19 Dec 2025 17:19:50 +0000</pubDate>
-      <enclosure url="https://github.com/steipete/clawdis/releases/download/v2.0.0-beta1/Clawdis-2.0.0-beta1.zip"
-                 sparkle:edSignature="oEpGD46U4ZyBBSY9/piUIFDJU+KlFB751JIWOW2yS0sRNHKszyG5khDHg9o9bV9Zo8DOCNF/HOi88jmtHJAaCQ=="
-                 sparkle:version="2.0.0-beta1"
-                 sparkle:shortVersionString="2.0.0-beta1"
-                 length="72410016"
-                 type="application/octet-stream" />
-    </item>
-  </channel>
-</rss>
+<?xml version="1.0" standalone="yes"?>
+<rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
+    <channel>
+        <title>Clawdis</title>
+        <item>
+            <title>2.0.0-beta3</title>
+            <pubDate>Sat, 27 Dec 2025 19:02:02 +0100</pubDate>
+            <link>https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml</link>
+            <sparkle:version>2.0.0-beta3</sparkle:version>
+            <sparkle:shortVersionString>2.0.0-beta3</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <enclosure url="https://github.com/steipete/clawdis/releases/download/v2.0.0-beta4/Clawdis-2.0.0-beta3.zip" length="70407960" type="application/octet-stream" sparkle:edSignature="A8ySMmbLRrpIkqkrmc9QrC+6om8Iyqray/6x/YNiJxDoJeXjp2T5t8XT0CKJeNBUlDkzIj/fwiK53v0qQ59cDQ=="/>
+        </item>
+        <item>
+            <title>2.0.0-beta4</title>
+            <pubDate>Sat, 27 Dec 2025 19:43:22 +0100</pubDate>
+            <link>https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml</link>
+            <sparkle:version>2.0.0-beta4</sparkle:version>
+            <sparkle:shortVersionString>2.0.0-beta4</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdis 2.0.0-beta4</h2>
+<h3>Fixes</h3>
+<ul>
+<li>Package contents: include Discord/hooks build outputs in the npm tarball to avoid missing module errors.</li>
+</ul>
+<p><a href="https://github.com/steipete/clawdis/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/steipete/clawdis/releases/download/v2.0.0-beta4/Clawdis-2.0.0-beta4.zip" length="70407894" type="application/octet-stream" sparkle:edSignature="HmuiC7TnUn80ZApnKfb6w+JGSrjc3uUOndMrtbTp42bkBSVifbttNVazqvJueGBo4MgoJV8CP+zQNzVmtVihAQ=="/>
+        </item>
+    </channel>
+</rss>

apps/android/app/build.gradle.kts

@@ -20,7 +20,7 @@ android {
     minSdk = 31
     targetSdk = 36
     versionCode = 1
-    versionName = "0.1"
+    versionName = "2.0.0-beta3"
   }
 
   buildTypes {
@@ -31,6 +31,7 @@ android {
 
   buildFeatures {
     compose = true
+    buildConfig = true
   }
 
   compileOptions {
@@ -38,15 +39,21 @@ android {
     targetCompatibility = JavaVersion.VERSION_17
   }
 
-  kotlinOptions {
-    jvmTarget = "17"
-  }
-
   packaging {
     resources {
       excludes += "/META-INF/{AL2.0,LGPL2.1}"
     }
   }
+
+  lint {
+    disable += setOf("IconLauncherShape")
+  }
+}
+
+kotlin {
+  compilerOptions {
+    jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+  }
 }
 
 dependencies {
@@ -56,7 +63,7 @@ dependencies {
 
   implementation("androidx.core:core-ktx:1.17.0")
   implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.10.0")
-  implementation("androidx.activity:activity-compose:1.12.1")
+  implementation("androidx.activity:activity-compose:1.12.2")
 
   implementation("androidx.compose.ui:ui")
   implementation("androidx.compose.ui:ui-tooling-preview")

apps/android/app/src/main/AndroidManifest.xml

@@ -12,12 +12,20 @@
     <uses-permission
         android:name="android.permission.ACCESS_FINE_LOCATION"
         android:maxSdkVersion="32" />
+    <uses-permission
+        android:name="android.permission.ACCESS_COARSE_LOCATION"
+        android:maxSdkVersion="32" />
     <uses-permission android:name="android.permission.CAMERA" />
     <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-feature
+        android:name="android.hardware.camera"
+        android:required="false" />
 
     <application
         android:name=".NodeApp"
         android:allowBackup="true"
+        android:dataExtractionRules="@xml/data_extraction_rules"
+        android:fullBackupContent="@xml/backup_rules"
         android:icon="@mipmap/ic_launcher"
         android:roundIcon="@mipmap/ic_launcher_round"
         android:label="@string/app_name"

apps/android/app/src/main/java/com/steipete/clawdis/node/MainViewModel.kt

@@ -38,6 +38,7 @@ class MainViewModel(app: Application) : AndroidViewModel(app) {
   val manualEnabled: StateFlow<Boolean> = runtime.manualEnabled
   val manualHost: StateFlow<String> = runtime.manualHost
   val manualPort: StateFlow<Int> = runtime.manualPort
+  val canvasDebugStatusEnabled: StateFlow<Boolean> = runtime.canvasDebugStatusEnabled
 
   val chatSessionKey: StateFlow<String> = runtime.chatSessionKey
   val chatSessionId: StateFlow<String?> = runtime.chatSessionId
@@ -78,6 +79,10 @@ class MainViewModel(app: Application) : AndroidViewModel(app) {
     runtime.setManualPort(value)
   }
 
+  fun setCanvasDebugStatusEnabled(value: Boolean) {
+    runtime.setCanvasDebugStatusEnabled(value)
+  }
+
   fun setWakeWords(words: List<String>) {
     runtime.setWakeWords(words)
   }

apps/android/app/src/main/java/com/steipete/clawdis/node/NodeForegroundService.kt

@@ -10,7 +10,6 @@ import android.content.Context
 import android.content.Intent
 import android.content.pm.PackageManager
 import android.content.pm.ServiceInfo
-import android.os.Build
 import androidx.core.app.NotificationCompat
 import androidx.core.content.ContextCompat
 import kotlinx.coroutines.CoroutineScope
@@ -85,7 +84,6 @@ class NodeForegroundService : Service() {
   override fun onBind(intent: Intent?) = null
 
   private fun ensureChannel() {
-    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
     val mgr = getSystemService(NotificationManager::class.java)
     val channel =
       NotificationChannel(
@@ -101,12 +99,7 @@ class NodeForegroundService : Service() {
 
   private fun buildNotification(title: String, text: String): Notification {
     val stopIntent = Intent(this, NodeForegroundService::class.java).setAction(ACTION_STOP)
-    val flags =
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
-      } else {
-        PendingIntent.FLAG_UPDATE_CURRENT
-      }
+    val flags = PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
     val stopPending = PendingIntent.getService(this, 2, stopIntent, flags)
 
     return NotificationCompat.Builder(this, CHANNEL_ID)
@@ -126,11 +119,6 @@ class NodeForegroundService : Service() {
   }
 
   private fun startForegroundWithTypes(notification: Notification, requiresMic: Boolean) {
-    if (Build.VERSION.SDK_INT < 29) {
-      startForeground(NOTIFICATION_ID, notification)
-      return
-    }
-
     if (didStartForeground && requiresMic == lastRequiresMic) {
       updateNotification(notification)
       return
@@ -162,11 +150,7 @@ class NodeForegroundService : Service() {
 
     fun start(context: Context) {
       val intent = Intent(context, NodeForegroundService::class.java)
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-        context.startForegroundService(intent)
-      } else {
-        context.startService(intent)
-      }
+      context.startForegroundService(intent)
     }
 
     fun stop(context: Context) {

apps/android/app/src/main/java/com/steipete/clawdis/node/NodeRuntime.kt

@@ -16,6 +16,7 @@ import com.steipete.clawdis.node.bridge.BridgeEndpoint
 import com.steipete.clawdis.node.bridge.BridgePairingClient
 import com.steipete.clawdis.node.bridge.BridgeSession
 import com.steipete.clawdis.node.node.CameraCaptureManager
+import com.steipete.clawdis.node.BuildConfig
 import com.steipete.clawdis.node.node.CanvasController
 import com.steipete.clawdis.node.node.ScreenRecordManager
 import com.steipete.clawdis.node.protocol.ClawdisCapability
@@ -109,6 +110,8 @@ class NodeRuntime(context: Context) {
   private val _isForeground = MutableStateFlow(true)
   val isForeground: StateFlow<Boolean> = _isForeground.asStateFlow()
 
+  private var lastAutoA2uiUrl: String? = null
+
   private val session =
     BridgeSession(
       scope = scope,
@@ -118,6 +121,7 @@ class NodeRuntime(context: Context) {
         _remoteAddress.value = remote
         _isConnected.value = true
         scope.launch { refreshWakeWordsFromGateway() }
+        maybeNavigateToA2uiOnConnect()
       },
       onDisconnected = { message -> handleSessionDisconnected(message) },
       onEvent = { event, payloadJson ->
@@ -136,6 +140,21 @@ class NodeRuntime(context: Context) {
     _remoteAddress.value = null
     _isConnected.value = false
     chat.onDisconnected(message)
+    showLocalCanvasOnDisconnect()
+  }
+
+  private fun maybeNavigateToA2uiOnConnect() {
+    val a2uiUrl = resolveA2uiHostUrl() ?: return
+    val current = canvas.currentUrl()?.trim().orEmpty()
+    if (current.isEmpty() || current == lastAutoA2uiUrl) {
+      lastAutoA2uiUrl = a2uiUrl
+      canvas.navigate(a2uiUrl)
+    }
+  }
+
+  private fun showLocalCanvasOnDisconnect() {
+    lastAutoA2uiUrl = null
+    canvas.navigate("")
   }
 
   val instanceId: StateFlow<String> = prefs.instanceId
@@ -148,6 +167,7 @@ class NodeRuntime(context: Context) {
   val manualHost: StateFlow<String> = prefs.manualHost
   val manualPort: StateFlow<Int> = prefs.manualPort
   val lastDiscoveredStableId: StateFlow<String> = prefs.lastDiscoveredStableId
+  val canvasDebugStatusEnabled: StateFlow<Boolean> = prefs.canvasDebugStatusEnabled
 
   private var didAutoConnect = false
   private var suppressWakeWordsSync = false
@@ -228,6 +248,22 @@ class NodeRuntime(context: Context) {
         connect(target)
       }
     }
+
+    scope.launch {
+      combine(
+        canvasDebugStatusEnabled,
+        statusText,
+        serverName,
+        remoteAddress,
+      ) { debugEnabled, status, server, remote ->
+        Quad(debugEnabled, status, server, remote)
+      }.distinctUntilChanged()
+        .collect { (debugEnabled, status, server, remote) ->
+          canvas.setDebugStatusEnabled(debugEnabled)
+          if (!debugEnabled) return@collect
+          canvas.setDebugStatus(status, server ?: remote)
+        }
+    }
   }
 
   fun setForeground(value: Boolean) {
@@ -258,6 +294,10 @@ class NodeRuntime(context: Context) {
     prefs.setManualPort(value)
   }
 
+  fun setCanvasDebugStatusEnabled(value: Boolean) {
+    prefs.setCanvasDebugStatusEnabled(value)
+  }
+
   fun setWakeWords(words: List<String>) {
     prefs.setWakeWords(words)
     scheduleWakeWordsSyncIfNeeded()
@@ -307,6 +347,13 @@ class NodeRuntime(context: Context) {
               add(ClawdisCapability.VoiceWake.rawValue)
             }
           }
+          val versionName = BuildConfig.VERSION_NAME.trim().ifEmpty { "dev" }
+          val advertisedVersion =
+            if (BuildConfig.DEBUG && !versionName.contains("dev", ignoreCase = true)) {
+              "$versionName-dev"
+            } else {
+              versionName
+            }
           BridgePairingClient().pairAndHello(
             endpoint = endpoint,
             hello =
@@ -315,7 +362,7 @@ class NodeRuntime(context: Context) {
                 displayName = displayName.value,
                 token = null,
                 platform = "Android",
-                version = "dev",
+                version = advertisedVersion,
                 deviceFamily = "Android",
                 modelIdentifier = modelIdentifier,
                 caps = caps,
@@ -333,6 +380,13 @@ class NodeRuntime(context: Context) {
 
       val authToken = requireNotNull(resolved.token).trim()
       prefs.saveBridgeToken(authToken)
+      val versionName = BuildConfig.VERSION_NAME.trim().ifEmpty { "dev" }
+      val advertisedVersion =
+        if (BuildConfig.DEBUG && !versionName.contains("dev", ignoreCase = true)) {
+          "$versionName-dev"
+        } else {
+          versionName
+        }
       session.connect(
         endpoint = endpoint,
         hello =
@@ -341,7 +395,7 @@ class NodeRuntime(context: Context) {
             displayName = displayName.value,
             token = authToken,
             platform = "Android",
-            version = "dev",
+            version = advertisedVersion,
             deviceFamily = "Android",
             modelIdentifier = modelIdentifier,
             caps =
@@ -396,8 +450,7 @@ class NodeRuntime(context: Context) {
       val actionId = (userActionObj["id"] as? JsonPrimitive)?.content?.trim().orEmpty().ifEmpty {
         java.util.UUID.randomUUID().toString()
       }
-      val name = (userActionObj["name"] as? JsonPrimitive)?.content?.trim().orEmpty()
-      if (name.isEmpty()) return@launch
+      val name = ClawdisCanvasA2UIAction.extractActionName(userActionObj) ?: return@launch
 
       val surfaceId =
         (userActionObj["surfaceId"] as? JsonPrimitive)?.content?.trim().orEmpty().ifEmpty { "main" }
@@ -605,9 +658,17 @@ class NodeRuntime(context: Context) {
         BridgeSession.InvokeResult.ok("""{"format":"${snapshotParams.format.rawValue}","base64":"$base64"}""")
       }
       ClawdisCanvasA2UICommand.Reset.rawValue -> {
-        val ready = ensureA2uiReady()
+        val a2uiUrl = resolveA2uiHostUrl()
+          ?: return BridgeSession.InvokeResult.error(
+            code = "A2UI_HOST_NOT_CONFIGURED",
+            message = "A2UI_HOST_NOT_CONFIGURED: gateway did not advertise canvas host",
+          )
+        val ready = ensureA2uiReady(a2uiUrl)
         if (!ready) {
-          return BridgeSession.InvokeResult.error(code = "A2UI_NOT_READY", message = "A2UI not ready")
+          return BridgeSession.InvokeResult.error(
+            code = "A2UI_HOST_UNAVAILABLE",
+            message = "A2UI host not reachable",
+          )
         }
         val res = canvas.eval(a2uiResetJS)
         BridgeSession.InvokeResult.ok(res)
@@ -619,9 +680,17 @@ class NodeRuntime(context: Context) {
           } catch (err: Throwable) {
             return BridgeSession.InvokeResult.error(code = "INVALID_REQUEST", message = err.message ?: "invalid A2UI payload")
           }
-        val ready = ensureA2uiReady()
+        val a2uiUrl = resolveA2uiHostUrl()
+          ?: return BridgeSession.InvokeResult.error(
+            code = "A2UI_HOST_NOT_CONFIGURED",
+            message = "A2UI_HOST_NOT_CONFIGURED: gateway did not advertise canvas host",
+          )
+        val ready = ensureA2uiReady(a2uiUrl)
         if (!ready) {
-          return BridgeSession.InvokeResult.error(code = "A2UI_NOT_READY", message = "A2UI not ready")
+          return BridgeSession.InvokeResult.error(
+            code = "A2UI_HOST_UNAVAILABLE",
+            message = "A2UI host not reachable",
+          )
         }
         val js = a2uiApplyMessagesJS(messages)
         val res = canvas.eval(js)
@@ -707,7 +776,14 @@ class NodeRuntime(context: Context) {
     return code to "$code: $message"
   }
 
-  private suspend fun ensureA2uiReady(): Boolean {
+  private fun resolveA2uiHostUrl(): String? {
+    val raw = session.currentCanvasHostUrl()?.trim().orEmpty()
+    if (raw.isBlank()) return null
+    val base = raw.trimEnd('/')
+    return "${base}/__clawdis__/a2ui/"
+  }
+
+  private suspend fun ensureA2uiReady(a2uiUrl: String): Boolean {
     try {
       val already = canvas.eval(a2uiReadyCheckJS)
       if (already == "true") return true
@@ -715,8 +791,7 @@ class NodeRuntime(context: Context) {
       // ignore
     }
 
-    // Ensure the default canvas scaffold is loaded; A2UI is now hosted there.
-    canvas.navigate("")
+    canvas.navigate(a2uiUrl)
     repeat(50) {
       try {
         val ready = canvas.eval(a2uiReadyCheckJS)

apps/android/app/src/main/java/com/steipete/clawdis/node/SecurePrefs.kt

@@ -3,6 +3,7 @@
 package com.steipete.clawdis.node
 
 import android.content.Context
+import androidx.core.content.edit
 import androidx.security.crypto.EncryptedSharedPreferences
 import androidx.security.crypto.MasterKey
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -62,6 +63,10 @@ class SecurePrefs(context: Context) {
     MutableStateFlow(prefs.getString("bridge.lastDiscoveredStableId", "")!!)
   val lastDiscoveredStableId: StateFlow<String> = _lastDiscoveredStableId
 
+  private val _canvasDebugStatusEnabled =
+    MutableStateFlow(prefs.getBoolean("canvas.debugStatusEnabled", false))
+  val canvasDebugStatusEnabled: StateFlow<Boolean> = _canvasDebugStatusEnabled
+
   private val _wakeWords = MutableStateFlow(loadWakeWords())
   val wakeWords: StateFlow<List<String>> = _wakeWords
 
@@ -70,42 +75,47 @@ class SecurePrefs(context: Context) {
 
   fun setLastDiscoveredStableId(value: String) {
     val trimmed = value.trim()
-    prefs.edit().putString("bridge.lastDiscoveredStableId", trimmed).apply()
+    prefs.edit { putString("bridge.lastDiscoveredStableId", trimmed) }
     _lastDiscoveredStableId.value = trimmed
   }
 
   fun setDisplayName(value: String) {
     val trimmed = value.trim()
-    prefs.edit().putString(displayNameKey, trimmed).apply()
+    prefs.edit { putString(displayNameKey, trimmed) }
     _displayName.value = trimmed
   }
 
   fun setCameraEnabled(value: Boolean) {
-    prefs.edit().putBoolean("camera.enabled", value).apply()
+    prefs.edit { putBoolean("camera.enabled", value) }
     _cameraEnabled.value = value
   }
 
   fun setPreventSleep(value: Boolean) {
-    prefs.edit().putBoolean("screen.preventSleep", value).apply()
+    prefs.edit { putBoolean("screen.preventSleep", value) }
     _preventSleep.value = value
   }
 
   fun setManualEnabled(value: Boolean) {
-    prefs.edit().putBoolean("bridge.manual.enabled", value).apply()
+    prefs.edit { putBoolean("bridge.manual.enabled", value) }
     _manualEnabled.value = value
   }
 
   fun setManualHost(value: String) {
     val trimmed = value.trim()
-    prefs.edit().putString("bridge.manual.host", trimmed).apply()
+    prefs.edit { putString("bridge.manual.host", trimmed) }
     _manualHost.value = trimmed
   }
 
   fun setManualPort(value: Int) {
-    prefs.edit().putInt("bridge.manual.port", value).apply()
+    prefs.edit { putInt("bridge.manual.port", value) }
     _manualPort.value = value
   }
 
+  fun setCanvasDebugStatusEnabled(value: Boolean) {
+    prefs.edit { putBoolean("canvas.debugStatusEnabled", value) }
+    _canvasDebugStatusEnabled.value = value
+  }
+
   fun loadBridgeToken(): String? {
     val key = "bridge.token.${_instanceId.value}"
     return prefs.getString(key, null)
@@ -113,14 +123,14 @@ class SecurePrefs(context: Context) {
 
   fun saveBridgeToken(token: String) {
     val key = "bridge.token.${_instanceId.value}"
-    prefs.edit().putString(key, token.trim()).apply()
+    prefs.edit { putString(key, token.trim()) }
   }
 
   private fun loadOrCreateInstanceId(): String {
     val existing = prefs.getString("node.instanceId", null)?.trim()
     if (!existing.isNullOrBlank()) return existing
     val fresh = UUID.randomUUID().toString()
-    prefs.edit().putString("node.instanceId", fresh).apply()
+    prefs.edit { putString("node.instanceId", fresh) }
     return fresh
   }
 
@@ -131,7 +141,7 @@ class SecurePrefs(context: Context) {
     val candidate = DeviceNames.bestDefaultNodeName(context).trim()
     val resolved = candidate.ifEmpty { "Android Node" }
 
-    prefs.edit().putString(displayNameKey, resolved).apply()
+    prefs.edit { putString(displayNameKey, resolved) }
     return resolved
   }
 
@@ -139,12 +149,12 @@ class SecurePrefs(context: Context) {
     val sanitized = WakeWords.sanitize(words, defaultWakeWords)
     val encoded =
       JsonArray(sanitized.map { JsonPrimitive(it) }).toString()
-    prefs.edit().putString("voiceWake.triggerWords", encoded).apply()
+    prefs.edit { putString("voiceWake.triggerWords", encoded) }
     _wakeWords.value = sanitized
   }
 
   fun setVoiceWakeMode(mode: VoiceWakeMode) {
-    prefs.edit().putString(voiceWakeModeKey, mode.rawValue).apply()
+    prefs.edit { putString(voiceWakeModeKey, mode.rawValue) }
     _voiceWakeMode.value = mode
   }
 
@@ -154,7 +164,7 @@ class SecurePrefs(context: Context) {
 
     // Default ON (foreground) when unset.
     if (raw.isNullOrBlank()) {
-      prefs.edit().putString(voiceWakeModeKey, resolved.rawValue).apply()
+      prefs.edit { putString(voiceWakeModeKey, resolved.rawValue) }
     }
 
     return resolved

apps/android/app/src/main/java/com/steipete/clawdis/node/bridge/BonjourEscapes.kt

@@ -4,7 +4,7 @@ object BonjourEscapes {
   fun decode(input: String): String {
     if (input.isEmpty()) return input
 
-    val out = StringBuilder(input.length)
+    val bytes = mutableListOf<Byte>()
     var i = 0
     while (i < input.length) {
       if (input[i] == '\\' && i + 3 < input.length) {
@@ -14,17 +14,22 @@ object BonjourEscapes {
         if (d0.isDigit() && d1.isDigit() && d2.isDigit()) {
           val value =
             ((d0.code - '0'.code) * 100) + ((d1.code - '0'.code) * 10) + (d2.code - '0'.code)
-          if (value in 0..0x10FFFF) {
-            out.appendCodePoint(value)
+          if (value in 0..255) {
+            bytes.add(value.toByte())
             i += 4
             continue
           }
         }
       }
 
-      out.append(input[i])
-      i += 1
+      val codePoint = Character.codePointAt(input, i)
+      val charBytes = String(Character.toChars(codePoint)).toByteArray(Charsets.UTF_8)
+      for (b in charBytes) {
+        bytes.add(b)
+      }
+      i += Character.charCount(codePoint)
     }
-    return out.toString()
+
+    return String(bytes.toByteArray(), Charsets.UTF_8)
   }
 }

apps/android/app/src/main/java/com/steipete/clawdis/node/bridge/BridgeDiscovery.kt

@@ -6,7 +6,6 @@ import android.net.DnsResolver
 import android.net.NetworkCapabilities
 import android.net.nsd.NsdManager
 import android.net.nsd.NsdServiceInfo
-import android.os.Build
 import android.os.CancellationSignal
 import android.util.Log
 import java.io.IOException
@@ -44,6 +43,7 @@ import org.xbill.DNS.Type
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
 
+@Suppress("DEPRECATION")
 class BridgeDiscovery(
   context: Context,
   private val scope: CoroutineScope,
@@ -181,7 +181,6 @@ class BridgeDiscovery(
   }
 
   private fun txt(info: NsdServiceInfo, key: String): String? {
-    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.LOLLIPOP) return null
     val bytes = info.attributes[key] ?: return null
     return try {
       String(bytes, Charsets.UTF_8).trim().ifEmpty { null }
@@ -401,7 +400,7 @@ class BridgeDiscovery(
       dns.rawQuery(
         network,
         wireQuery,
-        0,
+        DnsResolver.FLAG_EMPTY,
         dnsExecutor,
         signal,
         object : DnsResolver.Callback<ByteArray> {

apps/android/app/src/main/java/com/steipete/clawdis/node/bridge/BridgeSession.kt

@@ -61,6 +61,7 @@ class BridgeSession(
   private val json = Json { ignoreUnknownKeys = true }
   private val writeLock = Mutex()
   private val pending = ConcurrentHashMap<String, CompletableDeferred<RpcResponse>>()
+  @Volatile private var canvasHostUrl: String? = null
 
   private var desired: Pair<BridgeEndpoint, Hello>? = null
   private var job: Job? = null
@@ -77,10 +78,13 @@ class BridgeSession(
     scope.launch(Dispatchers.IO) {
       job?.cancelAndJoin()
       job = null
+      canvasHostUrl = null
       onDisconnected("Offline")
     }
   }
 
+  fun currentCanvasHostUrl(): String? = canvasHostUrl
+
   suspend fun sendEvent(event: String, payloadJson: String?) {
     val conn = currentConnection ?: return
     conn.sendJson(
@@ -209,6 +213,7 @@ class BridgeSession(
         when (first["type"].asStringOrNull()) {
           "hello-ok" -> {
             val name = first["serverName"].asStringOrNull() ?: "Bridge"
+            canvasHostUrl = first["canvasHostUrl"].asStringOrNull()?.trim()?.ifEmpty { null }
             onConnected(name, conn.remoteAddress)
           }
           "error" -> {

apps/android/app/src/main/java/com/steipete/clawdis/node/node/CameraCaptureManager.kt

@@ -2,6 +2,7 @@ package com.steipete.clawdis.node.node
 
 import android.Manifest
 import android.content.Context
+import android.annotation.SuppressLint
 import android.graphics.Bitmap
 import android.graphics.BitmapFactory
 import android.util.Base64
@@ -18,6 +19,7 @@ import androidx.camera.video.VideoCapture
 import androidx.camera.video.VideoRecordEvent
 import androidx.core.content.ContextCompat
 import androidx.core.content.ContextCompat.checkSelfPermission
+import androidx.core.graphics.scale
 import com.steipete.clawdis.node.PermissionRequester
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.suspendCancellableCoroutine
@@ -92,7 +94,7 @@ class CameraCaptureManager(private val context: Context) {
             (decoded.height.toDouble() * (maxWidth.toDouble() / decoded.width.toDouble()))
               .toInt()
               .coerceAtLeast(1)
-          Bitmap.createScaledBitmap(decoded, maxWidth, h, true)
+          decoded.scale(maxWidth, h)
         } else {
           decoded
         }
@@ -108,6 +110,7 @@ class CameraCaptureManager(private val context: Context) {
       )
     }
 
+  @SuppressLint("MissingPermission")
   suspend fun clip(paramsJson: String?): Payload =
     withContext(Dispatchers.Main) {
       ensureCameraPermission()

apps/android/app/src/main/java/com/steipete/clawdis/node/node/CanvasController.kt

@@ -1,15 +1,17 @@
 package com.steipete.clawdis.node.node
 
 import android.graphics.Bitmap
-import android.os.Build
 import android.graphics.Canvas
 import android.os.Looper
 import android.webkit.WebView
+import androidx.core.graphics.createBitmap
+import androidx.core.graphics.scale
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.suspendCancellableCoroutine
 import kotlinx.coroutines.withContext
 import java.io.ByteArrayOutputStream
 import android.util.Base64
+import org.json.JSONObject
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonElement
 import kotlinx.serialization.json.JsonObject
@@ -24,6 +26,9 @@ class CanvasController {
 
   @Volatile private var webView: WebView? = null
   @Volatile private var url: String? = null
+  @Volatile private var debugStatusEnabled: Boolean = false
+  @Volatile private var debugStatusTitle: String? = null
+  @Volatile private var debugStatusSubtitle: String? = null
 
   private val scaffoldAssetUrl = "file:///android_asset/CanvasScaffold/scaffold.html"
 
@@ -35,6 +40,7 @@ class CanvasController {
   fun attach(webView: WebView) {
     this.webView = webView
     reload()
+    applyDebugStatus()
   }
 
   fun navigate(url: String) {
@@ -43,6 +49,25 @@ class CanvasController {
     reload()
   }
 
+  fun currentUrl(): String? = url
+
+  fun isDefaultCanvas(): Boolean = url == null
+
+  fun setDebugStatusEnabled(enabled: Boolean) {
+    debugStatusEnabled = enabled
+    applyDebugStatus()
+  }
+
+  fun setDebugStatus(title: String?, subtitle: String?) {
+    debugStatusTitle = title
+    debugStatusSubtitle = subtitle
+    applyDebugStatus()
+  }
+
+  fun onPageFinished() {
+    applyDebugStatus()
+  }
+
   private inline fun withWebViewOnMain(crossinline block: (WebView) -> Unit) {
     val wv = webView ?: return
     if (Looper.myLooper() == Looper.getMainLooper()) {
@@ -63,6 +88,32 @@ class CanvasController {
     }
   }
 
+  private fun applyDebugStatus() {
+    val enabled = debugStatusEnabled
+    val title = debugStatusTitle
+    val subtitle = debugStatusSubtitle
+    withWebViewOnMain { wv ->
+      val titleJs = title?.let { JSONObject.quote(it) } ?: "null"
+      val subtitleJs = subtitle?.let { JSONObject.quote(it) } ?: "null"
+      val js = """
+        (() => {
+          try {
+            const api = globalThis.__clawdis;
+            if (!api) return;
+            if (typeof api.setDebugStatusEnabled === 'function') {
+              api.setDebugStatusEnabled(${if (enabled) "true" else "false"});
+            }
+            if (!${if (enabled) "true" else "false"}) return;
+            if (typeof api.setStatus === 'function') {
+              api.setStatus($titleJs, $subtitleJs);
+            }
+          } catch (_) {}
+        })();
+      """.trimIndent()
+      wv.evaluateJavascript(js, null)
+    }
+  }
+
   suspend fun eval(javaScript: String): String =
     withContext(Dispatchers.Main) {
       val wv = webView ?: throw IllegalStateException("no webview")
@@ -80,7 +131,7 @@ class CanvasController {
       val scaled =
         if (maxWidth != null && maxWidth > 0 && bmp.width > maxWidth) {
           val h = (bmp.height.toDouble() * (maxWidth.toDouble() / bmp.width.toDouble())).toInt().coerceAtLeast(1)
-          Bitmap.createScaledBitmap(bmp, maxWidth, h, true)
+          bmp.scale(maxWidth, h)
         } else {
           bmp
         }
@@ -97,7 +148,7 @@ class CanvasController {
       val scaled =
         if (maxWidth != null && maxWidth > 0 && bmp.width > maxWidth) {
           val h = (bmp.height.toDouble() * (maxWidth.toDouble() / bmp.width.toDouble())).toInt().coerceAtLeast(1)
-          Bitmap.createScaledBitmap(bmp, maxWidth, h, true)
+          bmp.scale(maxWidth, h)
         } else {
           bmp
         }
@@ -116,7 +167,7 @@ class CanvasController {
     suspendCancellableCoroutine { cont ->
       val width = width.coerceAtLeast(1)
       val height = height.coerceAtLeast(1)
-      val bitmap = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+      val bitmap = createBitmap(width, height, Bitmap.Config.ARGB_8888)
 
       // WebView isn't supported by PixelCopy.request(...) directly; draw() is the most reliable
       // cross-version snapshot for this lightweight "canvas" use-case.

apps/android/app/src/main/java/com/steipete/clawdis/node/protocol/ClawdisCanvasA2UIAction.kt

@@ -1,6 +1,24 @@
 package com.steipete.clawdis.node.protocol
 
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+
 object ClawdisCanvasA2UIAction {
+  fun extractActionName(userAction: JsonObject): String? {
+    val name =
+      (userAction["name"] as? JsonPrimitive)
+        ?.content
+        ?.trim()
+        .orEmpty()
+    if (name.isNotEmpty()) return name
+    val action =
+      (userAction["action"] as? JsonPrimitive)
+        ?.content
+        ?.trim()
+        .orEmpty()
+    return action.ifEmpty { null }
+  }
+
   fun sanitizeTagValue(value: String): String {
     val trimmed = value.trim().ifEmpty { "-" }
     val normalized = trimmed.replace(" ", "_")
@@ -46,4 +64,3 @@ object ClawdisCanvasA2UIAction {
     return "window.dispatchEvent(new CustomEvent('clawdis:a2ui-action-status', { detail: { id: \"${idEscaped}\", ok: ${okLiteral}, error: \"${err}\" } }));"
   }
 }
-

apps/android/app/src/main/java/com/steipete/clawdis/node/ui/RootScreen.kt

@@ -187,15 +187,22 @@ private fun CanvasView(viewModel: MainViewModel, modifier: Modifier = Modifier)
                 "onReceivedHttpError: ${errorResponse.statusCode} ${errorResponse.reasonPhrase} ${request.url}",
               )
             }
+
+            override fun onPageFinished(view: WebView, url: String?) {
+              viewModel.canvas.onPageFinished()
+            }
           }
         setBackgroundColor(Color.BLACK)
         setLayerType(View.LAYER_TYPE_HARDWARE, null)
 
-        addJavascriptInterface(
+        val a2uiBridge =
           CanvasA2UIActionBridge { payload ->
             viewModel.handleCanvasA2UIActionFromWebView(payload)
-          },
-          CanvasA2UIActionBridge.interfaceName,
+          }
+        addJavascriptInterface(a2uiBridge, CanvasA2UIActionBridge.interfaceName)
+        addJavascriptInterface(
+          CanvasA2UIActionLegacyBridge(a2uiBridge),
+          CanvasA2UIActionLegacyBridge.interfaceName,
         )
         viewModel.canvas.attach(this)
       }
@@ -215,3 +222,19 @@ private class CanvasA2UIActionBridge(private val onMessage: (String) -> Unit) {
     const val interfaceName: String = "clawdisCanvasA2UIAction"
   }
 }
+
+private class CanvasA2UIActionLegacyBridge(private val bridge: CanvasA2UIActionBridge) {
+  @JavascriptInterface
+  fun canvasAction(payload: String?) {
+    bridge.postMessage(payload)
+  }
+
+  @JavascriptInterface
+  fun postMessage(payload: String?) {
+    bridge.postMessage(payload)
+  }
+
+  companion object {
+    const val interfaceName: String = "Android"
+  }
+}

apps/android/app/src/main/java/com/steipete/clawdis/node/ui/SettingsSheet.kt

@@ -64,6 +64,7 @@ fun SettingsSheet(viewModel: MainViewModel) {
   val manualEnabled by viewModel.manualEnabled.collectAsState()
   val manualHost by viewModel.manualHost.collectAsState()
   val manualPort by viewModel.manualPort.collectAsState()
+  val canvasDebugStatusEnabled by viewModel.canvasDebugStatusEnabled.collectAsState()
   val statusText by viewModel.statusText.collectAsState()
   val serverName by viewModel.serverName.collectAsState()
   val remoteAddress by viewModel.remoteAddress.collectAsState()
@@ -394,6 +395,23 @@ fun SettingsSheet(viewModel: MainViewModel) {
       )
     }
 
+    item { HorizontalDivider() }
+
+    // Debug
+    item { Text("Debug", style = MaterialTheme.typography.titleSmall) }
+    item {
+      ListItem(
+        headlineContent = { Text("Debug Canvas Status") },
+        supportingContent = { Text("Show status text in the canvas when debug is enabled.") },
+        trailingContent = {
+          Switch(
+            checked = canvasDebugStatusEnabled,
+            onCheckedChange = viewModel::setCanvasDebugStatusEnabled,
+          )
+        },
+      )
+    }
+
     item { Spacer(modifier = Modifier.height(20.dp)) }
   }
 }

apps/android/app/src/main/res/mipmap-anydpi/ic_launcher.xml

@@ -2,5 +2,5 @@
 <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
     <background android:drawable="@color/ic_launcher_background" />
     <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+    <monochrome android:drawable="@mipmap/ic_launcher_foreground" />
 </adaptive-icon>
-

apps/android/app/src/main/res/mipmap-anydpi/ic_launcher_round.xml

@@ -2,5 +2,5 @@
 <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
     <background android:drawable="@color/ic_launcher_background" />
     <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+    <monochrome android:drawable="@mipmap/ic_launcher_foreground" />
 </adaptive-icon>
-

apps/android/app/src/main/res/values/themes.xml

@@ -1,8 +1,7 @@
-<resources xmlns:tools="http://schemas.android.com/tools">
+<resources>
     <style name="Theme.ClawdisNode" parent="Theme.Material3.DayNight.NoActionBar">
         <item name="android:statusBarColor">@android:color/transparent</item>
         <item name="android:navigationBarColor">@android:color/transparent</item>
-        <item name="android:windowLightStatusBar" tools:targetApi="m">false</item>
+        <item name="android:windowLightStatusBar">false</item>
     </style>
 </resources>
-

apps/android/app/src/main/res/xml/backup_rules.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<full-backup-content>
+  <include domain="file" path="." />
+</full-backup-content>

apps/android/app/src/main/res/xml/data_extraction_rules.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<data-extraction-rules>
+  <cloud-backup>
+    <include domain="file" path="." />
+  </cloud-backup>
+  <device-transfer>
+    <include domain="file" path="." />
+  </device-transfer>
+</data-extraction-rules>

apps/android/app/src/main/res/xml/network_security_config.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
-<network-security-config>
+<network-security-config xmlns:tools="http://schemas.android.com/tools">
   <!-- This app is primarily used on a trusted tailnet; allow cleartext for IP-based endpoints too. -->
-  <base-config cleartextTrafficPermitted="true" />
+  <base-config cleartextTrafficPermitted="true" tools:ignore="InsecureBaseConfiguration" />
   <!-- Allow HTTP for tailnet/local dev endpoints (e.g. canvas/background web). -->
   <domain-config cleartextTrafficPermitted="true">
     <domain includeSubdomains="true">clawdis.internal</domain>

apps/android/app/src/test/java/com/steipete/clawdis/node/bridge/BonjourEscapesTest.kt

@@ -14,6 +14,6 @@ class BonjourEscapesTest {
   fun decodeDecodesDecimalEscapes() {
     assertEquals("Clawdis Gateway", BonjourEscapes.decode("Clawdis\\032Gateway"))
     assertEquals("A B", BonjourEscapes.decode("A\\032B"))
+    assertEquals("Peter\u2019s Mac", BonjourEscapes.decode("Peter\\226\\128\\153s Mac"))
   }
 }
-

apps/android/app/src/test/java/com/steipete/clawdis/node/bridge/BridgeSessionTest.kt

@@ -46,7 +46,7 @@ class BridgeSessionTest {
 
             val hello = reader.readLine()
             assertTrue(hello.contains("\"type\":\"hello\""))
-            writer.write("""{"type":"hello-ok","serverName":"Test Bridge"}""")
+            writer.write("""{"type":"hello-ok","serverName":"Test Bridge","canvasHostUrl":"http://127.0.0.1:18789"}""")
             writer.write("\n")
             writer.flush()
 
@@ -77,6 +77,7 @@ class BridgeSessionTest {
     )
 
     connected.await()
+    assertEquals("http://127.0.0.1:18789", session.currentCanvasHostUrl())
     val payload = session.request(method = "health", paramsJson = null)
     assertEquals("""{"value":123}""", payload)
     server.await()

apps/android/app/src/test/java/com/steipete/clawdis/node/protocol/ClawdisCanvasA2UIActionTest.kt

@@ -1,9 +1,24 @@
 package com.steipete.clawdis.node.protocol
 
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.jsonObject
 import org.junit.Assert.assertEquals
 import org.junit.Test
 
 class ClawdisCanvasA2UIActionTest {
+  @Test
+  fun extractActionNameAcceptsNameOrAction() {
+    val nameObj = Json.parseToJsonElement("{\"name\":\"Hello\"}").jsonObject
+    assertEquals("Hello", ClawdisCanvasA2UIAction.extractActionName(nameObj))
+
+    val actionObj = Json.parseToJsonElement("{\"action\":\"Wave\"}").jsonObject
+    assertEquals("Wave", ClawdisCanvasA2UIAction.extractActionName(actionObj))
+
+    val fallbackObj =
+      Json.parseToJsonElement("{\"name\":\"  \",\"action\":\"Fallback\"}").jsonObject
+    assertEquals("Fallback", ClawdisCanvasA2UIAction.extractActionName(fallbackObj))
+  }
+
   @Test
   fun formatAgentMessageMatchesSharedSpec() {
     val msg =
@@ -32,4 +47,3 @@ class ClawdisCanvasA2UIActionTest {
     )
   }
 }
-

apps/ios/Sources/Bridge/BridgeConnectionController.swift

@@ -221,12 +221,49 @@ final class BridgeConnectionController {
         var systemInfo = utsname()
         uname(&systemInfo)
         let machine = withUnsafeBytes(of: &systemInfo.machine) { ptr in
-            String(decoding: ptr.prefix { $0 != 0 }, as: UTF8.self)
+            String(bytes: ptr.prefix { $0 != 0 }, encoding: .utf8)
         }
-        return machine.isEmpty ? "unknown" : machine
+        let trimmed = machine?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? "unknown" : trimmed
     }
 
     private func appVersion() -> String {
         Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"
     }
 }
+
+#if DEBUG
+extension BridgeConnectionController {
+    func _test_makeHello(token: String) -> BridgeHello {
+        self.makeHello(token: token)
+    }
+
+    func _test_resolvedDisplayName(defaults: UserDefaults) -> String {
+        self.resolvedDisplayName(defaults: defaults)
+    }
+
+    func _test_currentCaps() -> [String] {
+        self.currentCaps()
+    }
+
+    func _test_currentCommands() -> [String] {
+        self.currentCommands()
+    }
+
+    func _test_platformString() -> String {
+        self.platformString()
+    }
+
+    func _test_deviceFamily() -> String {
+        self.deviceFamily()
+    }
+
+    func _test_modelIdentifier() -> String {
+        self.modelIdentifier()
+    }
+
+    func _test_appVersion() -> String {
+        self.appVersion()
+    }
+}
+#endif

apps/ios/Sources/Bridge/BridgeSession.swift

@@ -25,6 +25,11 @@ actor BridgeSession {
     private var serverEventSubscribers: [UUID: AsyncStream<BridgeEventFrame>.Continuation] = [:]
 
     private(set) var state: State = .idle
+    private var canvasHostUrl: String?
+
+    func currentCanvasHostUrl() -> String? {
+        self.canvasHostUrl
+    }
 
     func currentRemoteAddress() -> String? {
         guard let endpoint = self.connection?.currentPath?.remoteEndpoint else { return nil }
@@ -101,6 +106,7 @@ actor BridgeSession {
         if base.type == "hello-ok" {
             let ok = try self.decoder.decode(BridgeHelloOk.self, from: data)
             self.state = .connected(serverName: ok.serverName)
+            self.canvasHostUrl = ok.canvasHostUrl?.trimmingCharacters(in: .whitespacesAndNewlines)
             await onConnected?(ok.serverName)
         } else if base.type == "error" {
             let err = try self.decoder.decode(BridgeErrorFrame.self, from: data)
@@ -210,6 +216,7 @@ actor BridgeSession {
         self.connection = nil
         self.queue = nil
         self.buffer = Data()
+        self.canvasHostUrl = nil
 
         let pending = self.pendingRPC.values
         self.pendingRPC.removeAll()

apps/ios/Sources/Info.plist

@@ -22,6 +22,11 @@
 	<string>1.0</string>
 	<key>CFBundleVersion</key>
 	<string>1</string>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoadsInWebContent</key>
+		<true/>
+	</dict>
 	<key>NSBonjourServices</key>
 	<array>
 		<string>_clawdis-bridge._tcp</string>
@@ -45,5 +50,19 @@
 	</array>
 	<key>UILaunchScreen</key>
 	<dict/>
+	<key>UISupportedInterfaceOrientations</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationPortraitUpsideDown</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
+	</array>
+	<key>UISupportedInterfaceOrientations~ipad</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationPortraitUpsideDown</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
+	</array>
 </dict>
 </plist>

apps/ios/Sources/Model/NodeAppModel.swift

@@ -28,6 +28,7 @@ final class NodeAppModel {
     private var voiceWakeSyncTask: Task<Void, Never>?
     @ObservationIgnored private var cameraHUDDismissTask: Task<Void, Never>?
     let voiceWake = VoiceWakeManager()
+    private var lastAutoA2uiURL: String?
 
     var bridgeSession: BridgeSession { self.bridge }
 
@@ -38,8 +39,7 @@ final class NodeAppModel {
     init() {
         self.voiceWake.configure { [weak self] cmd in
             guard let self else { return }
-            let nodeId = UserDefaults.standard.string(forKey: "node.instanceId") ?? "ios-node"
-            let sessionKey = "node-\(nodeId)"
+            let sessionKey = "main"
             do {
                 try await self.sendVoiceTranscript(text: cmd, sessionKey: sessionKey)
             } catch {
@@ -81,7 +81,7 @@ final class NodeAppModel {
         }()
         guard !userAction.isEmpty else { return }
 
-        guard let name = userAction["name"] as? String, !name.isEmpty else { return }
+        guard let name = ClawdisCanvasA2UIAction.extractActionName(userAction) else { return }
         let actionId: String = {
             let id = (userAction["id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
             return id.isEmpty ? UUID().uuidString : id
@@ -103,17 +103,15 @@ final class NodeAppModel {
         let contextJSON = ClawdisCanvasA2UIAction.compactJSON(userAction["context"])
         let sessionKey = "main"
 
-        let message = ClawdisCanvasA2UIAction.formatAgentMessage(
+        let messageContext = ClawdisCanvasA2UIAction.AgentMessageContext(
             actionName: name,
-            sessionKey: sessionKey,
-            surfaceId: surfaceId,
-            sourceComponentId: sourceComponentId,
-            host: host,
-            instanceId: instanceId,
+            session: .init(key: sessionKey, surfaceId: surfaceId),
+            component: .init(id: sourceComponentId, host: host, instanceId: instanceId),
             contextJSON: contextJSON)
+        let message = ClawdisCanvasA2UIAction.formatAgentMessage(messageContext)
 
         let ok: Bool
-        var errorText: String? = nil
+        var errorText: String?
         if await !self.isBridgeConnected() {
             ok = false
             errorText = "bridge not connected"
@@ -143,6 +141,27 @@ final class NodeAppModel {
         }
     }
 
+    private func resolveA2UIHostURL() async -> String? {
+        guard let raw = await self.bridge.currentCanvasHostUrl() else { return nil }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, let base = URL(string: trimmed) else { return nil }
+        return base.appendingPathComponent("__clawdis__/a2ui/").absoluteString
+    }
+
+    private func showA2UIOnConnectIfNeeded() async {
+        guard let a2uiUrl = await self.resolveA2UIHostURL() else { return }
+        let current = self.screen.urlString.trimmingCharacters(in: .whitespacesAndNewlines)
+        if current.isEmpty || current == self.lastAutoA2uiURL {
+            self.screen.navigate(to: a2uiUrl)
+            self.lastAutoA2uiURL = a2uiUrl
+        }
+    }
+
+    private func showLocalCanvasOnDisconnect() {
+        self.lastAutoA2uiURL = nil
+        self.screen.showDefaultCanvas()
+    }
+
     func setScenePhase(_ phase: ScenePhase) {
         switch phase {
         case .background:
@@ -198,6 +217,7 @@ final class NodeAppModel {
                                 }
                             }
                             await self.startVoiceWakeSync()
+                            await self.showA2UIOnConnectIfNeeded()
                         },
                         onInvoke: { [weak self] req in
                             guard let self else {
@@ -210,6 +230,9 @@ final class NodeAppModel {
                         })
 
                     if Task.isCancelled { break }
+                    await MainActor.run {
+                        self.showLocalCanvasOnDisconnect()
+                    }
                     attempt += 1
                     let sleepSeconds = min(6.0, 0.35 * pow(1.7, Double(attempt)))
                     try? await Task.sleep(nanoseconds: UInt64(sleepSeconds * 1_000_000_000))
@@ -220,6 +243,7 @@ final class NodeAppModel {
                         self.bridgeStatusText = "Bridge error: \(error.localizedDescription)"
                         self.bridgeServerName = nil
                         self.bridgeRemoteAddress = nil
+                        self.showLocalCanvasOnDisconnect()
                     }
                     let sleepSeconds = min(8.0, 0.5 * pow(1.7, Double(attempt)))
                     try? await Task.sleep(nanoseconds: UInt64(sleepSeconds * 1_000_000_000))
@@ -231,6 +255,7 @@ final class NodeAppModel {
                 self.bridgeServerName = nil
                 self.bridgeRemoteAddress = nil
                 self.connectedBridgeID = nil
+                self.showLocalCanvasOnDisconnect()
             }
         }
     }
@@ -245,6 +270,7 @@ final class NodeAppModel {
         self.bridgeServerName = nil
         self.bridgeRemoteAddress = nil
         self.connectedBridgeID = nil
+        self.showLocalCanvasOnDisconnect()
     }
 
     func setGlobalWakeWords(_ words: [String]) async {
@@ -362,6 +388,7 @@ final class NodeAppModel {
         return false
     }
 
+    // swiftlint:disable:next function_body_length cyclomatic_complexity
     private func handleInvoke(_ req: BridgeInvokeRequest) async -> BridgeInvokeResponse {
         let command = req.command
 
@@ -435,12 +462,22 @@ final class NodeAppModel {
                 return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
 
             case ClawdisCanvasA2UICommand.reset.rawValue:
-                self.screen.showDefaultCanvas()
+                guard let a2uiUrl = await self.resolveA2UIHostURL() else {
+                    return BridgeInvokeResponse(
+                        id: req.id,
+                        ok: false,
+                        error: ClawdisNodeError(
+                            code: .unavailable,
+                            message: "A2UI_HOST_NOT_CONFIGURED: gateway did not advertise canvas host"))
+                }
+                self.screen.navigate(to: a2uiUrl)
                 if await !self.screen.waitForA2UIReady(timeoutMs: 5000) {
                     return BridgeInvokeResponse(
                         id: req.id,
                         ok: false,
-                        error: ClawdisNodeError(code: .unavailable, message: "A2UI not ready"))
+                        error: ClawdisNodeError(
+                            code: .unavailable,
+                            message: "A2UI_HOST_UNAVAILABLE: A2UI host not reachable"))
                 }
 
                 let json = try await self.screen.eval(javaScript: """
@@ -467,12 +504,22 @@ final class NodeAppModel {
                     }
                 }
 
-                self.screen.showDefaultCanvas()
+                guard let a2uiUrl = await self.resolveA2UIHostURL() else {
+                    return BridgeInvokeResponse(
+                        id: req.id,
+                        ok: false,
+                        error: ClawdisNodeError(
+                            code: .unavailable,
+                            message: "A2UI_HOST_NOT_CONFIGURED: gateway did not advertise canvas host"))
+                }
+                self.screen.navigate(to: a2uiUrl)
                 if await !self.screen.waitForA2UIReady(timeoutMs: 5000) {
                     return BridgeInvokeResponse(
                         id: req.id,
                         ok: false,
-                        error: ClawdisNodeError(code: .unavailable, message: "A2UI not ready"))
+                        error: ClawdisNodeError(
+                            code: .unavailable,
+                            message: "A2UI_HOST_UNAVAILABLE: A2UI host not reachable"))
                 }
 
                 let messagesJSON = try ClawdisCanvasA2UIJSONL.encodeMessagesJSONArray(messages)
@@ -633,3 +680,43 @@ final class NodeAppModel {
         }
     }
 }
+
+#if DEBUG
+extension NodeAppModel {
+    func _test_handleInvoke(_ req: BridgeInvokeRequest) async -> BridgeInvokeResponse {
+        await self.handleInvoke(req)
+    }
+
+    static func _test_decodeParams<T: Decodable>(_ type: T.Type, from json: String?) throws -> T {
+        try self.decodeParams(type, from: json)
+    }
+
+    static func _test_encodePayload(_ obj: some Encodable) throws -> String {
+        try self.encodePayload(obj)
+    }
+
+    func _test_isCameraEnabled() -> Bool {
+        self.isCameraEnabled()
+    }
+
+    func _test_triggerCameraFlash() {
+        self.triggerCameraFlash()
+    }
+
+    func _test_showCameraHUD(text: String, kind: CameraHUDKind, autoHideSeconds: Double? = nil) {
+        self.showCameraHUD(text: text, kind: kind, autoHideSeconds: autoHideSeconds)
+    }
+
+    func _test_handleCanvasA2UIAction(body: [String: Any]) async {
+        await self.handleCanvasA2UIAction(body: body)
+    }
+
+    func _test_resolveA2UIHostURL() async -> String? {
+        await self.resolveA2UIHostURL()
+    }
+
+    func _test_showLocalCanvasOnDisconnect() {
+        self.showLocalCanvasOnDisconnect()
+    }
+}
+#endif

apps/ios/Sources/RootCanvas.swift

@@ -8,6 +8,7 @@ struct RootCanvas: View {
     @Environment(\.scenePhase) private var scenePhase
     @AppStorage(VoiceWakePreferences.enabledKey) private var voiceWakeEnabled: Bool = false
     @AppStorage("screen.preventSleep") private var preventSleep: Bool = true
+    @AppStorage("canvas.debugStatusEnabled") private var canvasDebugStatusEnabled: Bool = false
     @State private var presentedSheet: PresentedSheet?
     @State private var voiceWakeToastText: String?
     @State private var toastDismissTask: Task<Void, Never>?
@@ -56,6 +57,11 @@ struct RootCanvas: View {
         .onAppear { self.updateIdleTimer() }
         .onChange(of: self.preventSleep) { _, _ in self.updateIdleTimer() }
         .onChange(of: self.scenePhase) { _, _ in self.updateIdleTimer() }
+        .onAppear { self.updateCanvasDebugStatus() }
+        .onChange(of: self.canvasDebugStatusEnabled) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.bridgeStatusText) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.bridgeServerName) { _, _ in self.updateCanvasDebugStatus() }
+        .onChange(of: self.appModel.bridgeRemoteAddress) { _, _ in self.updateCanvasDebugStatus() }
         .onChange(of: self.voiceWake.lastTriggeredCommand) { _, newValue in
             guard let newValue else { return }
             let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -102,6 +108,14 @@ struct RootCanvas: View {
     private func updateIdleTimer() {
         UIApplication.shared.isIdleTimerDisabled = (self.scenePhase == .active && self.preventSleep)
     }
+
+    private func updateCanvasDebugStatus() {
+        self.appModel.screen.setDebugStatusEnabled(self.canvasDebugStatusEnabled)
+        guard self.canvasDebugStatusEnabled else { return }
+        let title = self.appModel.bridgeStatusText.trimmingCharacters(in: .whitespacesAndNewlines)
+        let subtitle = self.appModel.bridgeServerName ?? self.appModel.bridgeRemoteAddress
+        self.appModel.screen.updateDebugStatus(title: title, subtitle: subtitle)
+    }
 }
 
 private struct CanvasContent: View {

apps/ios/Sources/Screen/ScreenController.swift

@@ -19,12 +19,18 @@ final class ScreenController {
     /// Callback invoked when the user clicks an A2UI action (e.g. button) inside the canvas web UI.
     var onA2UIAction: (([String: Any]) -> Void)?
 
+    private var debugStatusEnabled: Bool = false
+    private var debugStatusTitle: String?
+    private var debugStatusSubtitle: String?
+
     init() {
         let config = WKWebViewConfiguration()
         config.websiteDataStore = .nonPersistent()
         let a2uiActionHandler = CanvasA2UIActionMessageHandler()
         let userContentController = WKUserContentController()
-        userContentController.add(a2uiActionHandler, name: CanvasA2UIActionMessageHandler.messageName)
+        for name in CanvasA2UIActionMessageHandler.handlerNames {
+            userContentController.add(a2uiActionHandler, name: name)
+        }
         config.userContentController = userContentController
         self.navigationDelegate = ScreenNavigationDelegate()
         self.a2uiActionHandler = a2uiActionHandler
@@ -78,6 +84,39 @@ final class ScreenController {
         self.reload()
     }
 
+    func setDebugStatusEnabled(_ enabled: Bool) {
+        self.debugStatusEnabled = enabled
+        self.applyDebugStatusIfNeeded()
+    }
+
+    func updateDebugStatus(title: String?, subtitle: String?) {
+        self.debugStatusTitle = title
+        self.debugStatusSubtitle = subtitle
+        self.applyDebugStatusIfNeeded()
+    }
+
+    fileprivate func applyDebugStatusIfNeeded() {
+        let enabled = self.debugStatusEnabled
+        let title = self.debugStatusTitle
+        let subtitle = self.debugStatusSubtitle
+        let js = """
+        (() => {
+          try {
+            const api = globalThis.__clawdis;
+            if (!api) return;
+            if (typeof api.setDebugStatusEnabled === 'function') {
+              api.setDebugStatusEnabled(\(enabled ? "true" : "false"));
+            }
+            if (!\(enabled ? "true" : "false")) return;
+            if (typeof api.setStatus === 'function') {
+              api.setStatus(\(Self.jsValue(title)), \(Self.jsValue(subtitle)));
+            }
+          } catch (_) {}
+        })()
+        """
+        self.webView.evaluateJavaScript(js) { _, _ in }
+    }
+
     func waitForA2UIReady(timeoutMs: Int) async -> Bool {
         let clock = ContinuousClock()
         let deadline = clock.now.advanced(by: .milliseconds(timeoutMs))
@@ -90,7 +129,8 @@ final class ScreenController {
                   } catch (_) { return false; }
                 })()
                 """)
-                if res == "true" { return true }
+                let trimmed = res.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+                if trimmed == "true" || trimmed == "1" { return true }
             } catch {
                 // ignore; page likely still loading
             }
@@ -199,11 +239,6 @@ final class ScreenController {
         name: "scaffold",
         ext: "html",
         subdirectory: "CanvasScaffold")
-    private static let a2uiIndexURL: URL? = ScreenController.bundledResourceURL(
-        name: "index",
-        ext: "html",
-        subdirectory: "CanvasA2UI")
-
     func isTrustedCanvasUIURL(_ url: URL) -> Bool {
         guard url.isFileURL else { return false }
         let std = url.standardizedFileURL
@@ -212,14 +247,20 @@ final class ScreenController {
         {
             return true
         }
-        if let expected = Self.a2uiIndexURL,
-           std == expected.standardizedFileURL
-        {
-            return true
-        }
         return false
     }
 
+    private static func jsValue(_ value: String?) -> String {
+        guard let value else { return "null" }
+        if let data = try? JSONSerialization.data(withJSONObject: [value]),
+           let encoded = String(data: data, encoding: .utf8),
+           encoded.count >= 2
+        {
+            return String(encoded.dropFirst().dropLast())
+        }
+        return "null"
+    }
+
     func isLocalNetworkCanvasURL(_ url: URL) -> Bool {
         guard let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" else {
             return false
@@ -294,13 +335,14 @@ extension Double {
 // MARK: - Navigation Delegate
 
 /// Handles navigation policy to intercept clawdis:// deep links from canvas
+@MainActor
 private final class ScreenNavigationDelegate: NSObject, WKNavigationDelegate {
     weak var controller: ScreenController?
 
     func webView(
         _ webView: WKWebView,
         decidePolicyFor navigationAction: WKNavigationAction,
-        decisionHandler: @escaping (WKNavigationActionPolicy) -> Void)
+        decisionHandler: @escaping @MainActor @Sendable (WKNavigationActionPolicy) -> Void)
     {
         guard let url = navigationAction.request.url else {
             decisionHandler(.allow)
@@ -310,9 +352,7 @@ private final class ScreenNavigationDelegate: NSObject, WKNavigationDelegate {
         // Intercept clawdis:// deep links
         if url.scheme == "clawdis" {
             decisionHandler(.cancel)
-            Task { @MainActor in
-                self.controller?.onDeepLink?(url)
-            }
+            self.controller?.onDeepLink?(url)
             return
         }
 
@@ -324,20 +364,23 @@ private final class ScreenNavigationDelegate: NSObject, WKNavigationDelegate {
         didFailProvisionalNavigation _: WKNavigation?,
         withError error: any Error)
     {
-        Task { @MainActor in
-            self.controller?.errorText = error.localizedDescription
-        }
+        self.controller?.errorText = error.localizedDescription
+    }
+
+    func webView(_: WKWebView, didFinish _: WKNavigation?) {
+        self.controller?.errorText = nil
+        self.controller?.applyDebugStatusIfNeeded()
     }
 
     func webView(_: WKWebView, didFail _: WKNavigation?, withError error: any Error) {
-        Task { @MainActor in
-            self.controller?.errorText = error.localizedDescription
-        }
+        self.controller?.errorText = error.localizedDescription
     }
 }
 
 private final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
     static let messageName = "clawdisCanvasA2UIAction"
+    static let legacyMessageNames = ["canvas", "a2ui", "userAction", "action"]
+    static let handlerNames = [messageName] + legacyMessageNames
 
     weak var controller: ScreenController?
 

apps/ios/Sources/Screen/ScreenRecordService.swift

@@ -3,6 +3,10 @@ import ReplayKit
 
 @MainActor
 final class ScreenRecordService {
+    private struct UncheckedSendableBox<T>: @unchecked Sendable {
+        let value: T
+    }
+
     enum ScreenRecordError: LocalizedError {
         case invalidScreenIndex(Int)
         case captureFailed(String)
@@ -20,6 +24,7 @@ final class ScreenRecordService {
         }
     }
 
+    // swiftlint:disable:next cyclomatic_complexity
     func record(
         screenIndex: Int?,
         durationMs: Int?,
@@ -165,8 +170,10 @@ final class ScreenRecordService {
         videoInput.markAsFinished()
         audioInput?.markAsFinished()
 
+        let writerBox = UncheckedSendableBox(value: writer)
         try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
-            writer.finishWriting {
+            writerBox.value.finishWriting {
+                let writer = writerBox.value
                 if let err = writer.error {
                     cont.resume(throwing: ScreenRecordError.writeFailed(err.localizedDescription))
                 } else if writer.status != .completed {
@@ -191,3 +198,15 @@ final class ScreenRecordService {
         return min(30, max(1, v))
     }
 }
+
+#if DEBUG
+extension ScreenRecordService {
+    nonisolated static func _test_clampDurationMs(_ ms: Int?) -> Int {
+        self.clampDurationMs(ms)
+    }
+
+    nonisolated static func _test_clampFps(_ fps: Double?) -> Double {
+        self.clampFps(fps)
+    }
+}
+#endif

apps/ios/Sources/Settings/SettingsTab.swift

@@ -28,6 +28,7 @@ struct SettingsTab: View {
     @AppStorage("bridge.manual.host") private var manualBridgeHost: String = ""
     @AppStorage("bridge.manual.port") private var manualBridgePort: Int = 18790
     @AppStorage("bridge.discovery.debugLogs") private var discoveryDebugLogsEnabled: Bool = false
+    @AppStorage("canvas.debugStatusEnabled") private var canvasDebugStatusEnabled: Bool = false
     @State private var connectStatus = ConnectStatusStore()
     @State private var connectingBridgeID: String?
     @State private var localIPAddress: String?
@@ -142,6 +143,8 @@ struct SettingsTab: View {
                         NavigationLink("Discovery Logs") {
                             BridgeDiscoveryDebugLogView()
                         }
+
+                        Toggle("Debug Canvas Status", isOn: self.$canvasDebugStatusEnabled)
                     }
                 }
 
@@ -277,9 +280,10 @@ struct SettingsTab: View {
         var systemInfo = utsname()
         uname(&systemInfo)
         let machine = withUnsafeBytes(of: &systemInfo.machine) { ptr in
-            String(decoding: ptr.prefix { $0 != 0 }, as: UTF8.self)
+            String(bytes: ptr.prefix { $0 != 0 }, encoding: .utf8)
         }
-        return machine.isEmpty ? "unknown" : machine
+        let trimmed = machine?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? "unknown" : trimmed
     }
 
     private func currentCaps() -> [String] {

apps/ios/Sources/Status/StatusPill.swift

@@ -1,6 +1,8 @@
 import SwiftUI
 
 struct StatusPill: View {
+    @Environment(\.scenePhase) private var scenePhase
+
     enum BridgeState: Equatable {
         case connected
         case connecting
@@ -72,14 +74,18 @@ struct StatusPill: View {
         .buttonStyle(.plain)
         .accessibilityLabel("Status")
         .accessibilityValue("\(self.bridge.title), Voice Wake \(self.voiceWakeEnabled ? "enabled" : "disabled")")
-        .onAppear { self.updatePulse(for: self.bridge) }
+        .onAppear { self.updatePulse(for: self.bridge, scenePhase: self.scenePhase) }
+        .onDisappear { self.pulse = false }
         .onChange(of: self.bridge) { _, newValue in
-            self.updatePulse(for: newValue)
+            self.updatePulse(for: newValue, scenePhase: self.scenePhase)
+        }
+        .onChange(of: self.scenePhase) { _, newValue in
+            self.updatePulse(for: self.bridge, scenePhase: newValue)
         }
     }
 
-    private func updatePulse(for bridge: BridgeState) {
-        guard bridge == .connecting else {
+    private func updatePulse(for bridge: BridgeState, scenePhase: ScenePhase) {
+        guard bridge == .connecting, scenePhase == .active else {
             withAnimation(.easeOut(duration: 0.2)) { self.pulse = false }
             return
         }

apps/ios/Sources/Voice/VoiceWakeManager.swift

@@ -2,6 +2,7 @@ import AVFAudio
 import Foundation
 import Observation
 import Speech
+import SwabbleKit
 
 private func makeAudioTapEnqueueCallback(queue: AudioBufferQueue) -> @Sendable (AVAudioPCMBuffer, AVAudioTime) -> Void {
     { buffer, _ in
@@ -94,7 +95,7 @@ final class VoiceWakeManager: NSObject {
 
     private var lastDispatched: String?
     private var onCommand: (@Sendable (String) async -> Void)?
-    private nonisolated(unsafe) var userDefaultsObserver: NSObjectProtocol?
+    private var userDefaultsObserver: NSObjectProtocol?
 
     override init() {
         super.init()
@@ -110,7 +111,7 @@ final class VoiceWakeManager: NSObject {
             })
     }
 
-    deinit {
+    @MainActor deinit {
         if let userDefaultsObserver = self.userDefaultsObserver {
             NotificationCenter.default.removeObserver(userDefaultsObserver)
         }
@@ -289,15 +290,18 @@ final class VoiceWakeManager: NSObject {
     private nonisolated func makeRecognitionResultHandler() -> @Sendable (SFSpeechRecognitionResult?, Error?) -> Void {
         { [weak self] result, error in
             let transcript = result?.bestTranscription.formattedString
+            let segments = result.flatMap { result in
+                transcript.map { WakeWordSpeechSegments.from(transcription: result.bestTranscription, transcript: $0) }
+            } ?? []
             let errorText = error?.localizedDescription
 
             Task { @MainActor in
-                self?.handleRecognitionCallback(transcript: transcript, errorText: errorText)
+                self?.handleRecognitionCallback(transcript: transcript, segments: segments, errorText: errorText)
             }
         }
     }
 
-    private func handleRecognitionCallback(transcript: String?, errorText: String?) {
+    private func handleRecognitionCallback(transcript: String?, segments: [WakeWordSegment], errorText: String?) {
         if let errorText {
             self.statusText = "Recognizer error: \(errorText)"
             self.isListening = false
@@ -313,7 +317,7 @@ final class VoiceWakeManager: NSObject {
         }
 
         guard let transcript else { return }
-        guard let cmd = self.extractCommand(from: transcript) else { return }
+        guard let cmd = self.extractCommand(from: transcript, segments: segments) else { return }
 
         if cmd == self.lastDispatched { return }
         self.lastDispatched = cmd
@@ -334,30 +338,18 @@ final class VoiceWakeManager: NSObject {
         }
     }
 
-    private func extractCommand(from transcript: String) -> String? {
-        Self.extractCommand(from: transcript, triggers: self.activeTriggerWords)
+    private func extractCommand(from transcript: String, segments: [WakeWordSegment]) -> String? {
+        Self.extractCommand(from: transcript, segments: segments, triggers: self.activeTriggerWords)
     }
 
-    nonisolated static func extractCommand(from transcript: String, triggers: [String]) -> String? {
-        var bestRange: Range<String.Index>?
-        for trigger in triggers {
-            let token = trigger.trimmingCharacters(in: .whitespacesAndNewlines)
-            guard !token.isEmpty else { continue }
-            guard let range = transcript.range(of: token, options: [.caseInsensitive, .backwards]) else { continue }
-            if let currentBest = bestRange {
-                if range.lowerBound > currentBest.lowerBound {
-                    bestRange = range
-                }
-            } else {
-                bestRange = range
-            }
-        }
-
-        guard let bestRange else { return nil }
-        let after = transcript[bestRange.upperBound...]
-        let trimmed = after.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return nil }
-        return String(trimmed)
+    nonisolated static func extractCommand(
+        from transcript: String,
+        segments: [WakeWordSegment],
+        triggers: [String],
+        minPostTriggerGap: TimeInterval = 0.45) -> String?
+    {
+        let config = WakeWordGateConfig(triggers: triggers, minPostTriggerGap: minPostTriggerGap)
+        return WakeWordGate.match(transcript: transcript, segments: segments, config: config)?.command
     }
 
     private static func configureAudioSession() throws {
@@ -387,3 +379,11 @@ final class VoiceWakeManager: NSObject {
         }
     }
 }
+
+#if DEBUG
+extension VoiceWakeManager {
+    func _test_handleRecognitionCallback(transcript: String?, segments: [WakeWordSegment], errorText: String?) {
+        self.handleRecognitionCallback(transcript: transcript, segments: segments, errorText: errorText)
+    }
+}
+#endif

apps/ios/SwiftSources.input.xcfilelist

@@ -0,0 +1,57 @@
+Sources/Bridge/BridgeClient.swift
+Sources/Bridge/BridgeConnectionController.swift
+Sources/Bridge/BridgeDiscoveryDebugLogView.swift
+Sources/Bridge/BridgeDiscoveryModel.swift
+Sources/Bridge/BridgeEndpointID.swift
+Sources/Bridge/BridgeSession.swift
+Sources/Bridge/BridgeSettingsStore.swift
+Sources/Bridge/KeychainStore.swift
+Sources/Camera/CameraController.swift
+Sources/Chat/ChatSheet.swift
+Sources/Chat/IOSBridgeChatTransport.swift
+Sources/ClawdisApp.swift
+Sources/Model/NodeAppModel.swift
+Sources/RootCanvas.swift
+Sources/RootTabs.swift
+Sources/Screen/ScreenController.swift
+Sources/Screen/ScreenRecordService.swift
+Sources/Screen/ScreenTab.swift
+Sources/Screen/ScreenWebView.swift
+Sources/Settings/SettingsNetworkingHelpers.swift
+Sources/Settings/SettingsTab.swift
+Sources/Settings/VoiceWakeWordsSettingsView.swift
+Sources/Status/StatusPill.swift
+Sources/Status/VoiceWakeToast.swift
+Sources/Voice/VoiceTab.swift
+Sources/Voice/VoiceWakeManager.swift
+Sources/Voice/VoiceWakePreferences.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatComposer.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatMarkdownSplitter.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatMessageViews.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatModels.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatPayloadDecoding.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatSessions.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatSheets.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatTheme.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatTransport.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatView.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatViewModel.swift
+../shared/ClawdisKit/Sources/ClawdisKit/AnyCodable.swift
+../shared/ClawdisKit/Sources/ClawdisKit/BonjourEscapes.swift
+../shared/ClawdisKit/Sources/ClawdisKit/BonjourTypes.swift
+../shared/ClawdisKit/Sources/ClawdisKit/BridgeFrames.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CameraCommands.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasA2UIAction.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasA2UICommands.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasA2UIJSONL.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasCommandParams.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasCommands.swift
+../shared/ClawdisKit/Sources/ClawdisKit/Capabilities.swift
+../shared/ClawdisKit/Sources/ClawdisKit/ClawdisKitResources.swift
+../shared/ClawdisKit/Sources/ClawdisKit/DeepLinks.swift
+../shared/ClawdisKit/Sources/ClawdisKit/JPEGTranscoder.swift
+../shared/ClawdisKit/Sources/ClawdisKit/NodeError.swift
+../shared/ClawdisKit/Sources/ClawdisKit/ScreenCommands.swift
+../shared/ClawdisKit/Sources/ClawdisKit/StoragePaths.swift
+../shared/ClawdisKit/Sources/ClawdisKit/SystemCommands.swift
+../../Swabble/Sources/SwabbleKit/WakeWordGate.swift

apps/ios/Tests/BridgeConnectionControllerTests.swift

@@ -0,0 +1,159 @@
+import ClawdisKit
+import Foundation
+import Testing
+import UIKit
+@testable import Clawdis
+
+private struct KeychainEntry: Hashable {
+    let service: String
+    let account: String
+}
+
+private let bridgeService = "com.steipete.clawdis.bridge"
+private let nodeService = "com.steipete.clawdis.node"
+private let instanceIdEntry = KeychainEntry(service: nodeService, account: "instanceId")
+private let preferredBridgeEntry = KeychainEntry(service: bridgeService, account: "preferredStableID")
+private let lastBridgeEntry = KeychainEntry(service: bridgeService, account: "lastDiscoveredStableID")
+
+private func withUserDefaults<T>(_ updates: [String: Any?], _ body: () throws -> T) rethrows -> T {
+    let defaults = UserDefaults.standard
+    var snapshot: [String: Any?] = [:]
+    for key in updates.keys {
+        snapshot[key] = defaults.object(forKey: key)
+    }
+    for (key, value) in updates {
+        if let value {
+            defaults.set(value, forKey: key)
+        } else {
+            defaults.removeObject(forKey: key)
+        }
+    }
+    defer {
+        for (key, value) in snapshot {
+            if let value {
+                defaults.set(value, forKey: key)
+            } else {
+                defaults.removeObject(forKey: key)
+            }
+        }
+    }
+    return try body()
+}
+
+private func withKeychainValues<T>(_ updates: [KeychainEntry: String?], _ body: () throws -> T) rethrows -> T {
+    var snapshot: [KeychainEntry: String?] = [:]
+    for entry in updates.keys {
+        snapshot[entry] = KeychainStore.loadString(service: entry.service, account: entry.account)
+    }
+    for (entry, value) in updates {
+        if let value {
+            _ = KeychainStore.saveString(value, service: entry.service, account: entry.account)
+        } else {
+            _ = KeychainStore.delete(service: entry.service, account: entry.account)
+        }
+    }
+    defer {
+        for (entry, value) in snapshot {
+            if let value {
+                _ = KeychainStore.saveString(value, service: entry.service, account: entry.account)
+            } else {
+                _ = KeychainStore.delete(service: entry.service, account: entry.account)
+            }
+        }
+    }
+    return try body()
+}
+
+@Suite(.serialized) struct BridgeConnectionControllerTests {
+    @Test @MainActor func resolvedDisplayNameSetsDefaultWhenMissing() {
+        let defaults = UserDefaults.standard
+        let displayKey = "node.displayName"
+
+        withKeychainValues([instanceIdEntry: nil, preferredBridgeEntry: nil, lastBridgeEntry: nil]) {
+            withUserDefaults([displayKey: nil, "node.instanceId": "ios-test"]) {
+                let appModel = NodeAppModel()
+                let controller = BridgeConnectionController(appModel: appModel, startDiscovery: false)
+
+                let resolved = controller._test_resolvedDisplayName(defaults: defaults)
+                #expect(!resolved.isEmpty)
+                #expect(defaults.string(forKey: displayKey) == resolved)
+            }
+        }
+    }
+
+    @Test @MainActor func resolvedDisplayNamePreservesCustomValue() {
+        let defaults = UserDefaults.standard
+        let displayKey = "node.displayName"
+
+        withKeychainValues([instanceIdEntry: nil, preferredBridgeEntry: nil, lastBridgeEntry: nil]) {
+            withUserDefaults([displayKey: "My iOS Node", "node.instanceId": "ios-test"]) {
+                let appModel = NodeAppModel()
+                let controller = BridgeConnectionController(appModel: appModel, startDiscovery: false)
+
+                let resolved = controller._test_resolvedDisplayName(defaults: defaults)
+                #expect(resolved == "My iOS Node")
+                #expect(defaults.string(forKey: displayKey) == "My iOS Node")
+            }
+        }
+    }
+
+    @Test @MainActor func makeHelloBuildsCapsAndCommands() {
+        let defaults = UserDefaults.standard
+        let voiceWakeKey = VoiceWakePreferences.enabledKey
+
+        withKeychainValues([instanceIdEntry: nil, preferredBridgeEntry: nil, lastBridgeEntry: nil]) {
+            withUserDefaults([
+                "node.instanceId": "ios-test",
+                "node.displayName": "Test Node",
+                "camera.enabled": false,
+                voiceWakeKey: true,
+            ]) {
+                let appModel = NodeAppModel()
+                let controller = BridgeConnectionController(appModel: appModel, startDiscovery: false)
+                let hello = controller._test_makeHello(token: "token-123")
+
+                #expect(hello.nodeId == "ios-test")
+                #expect(hello.displayName == "Test Node")
+                #expect(hello.token == "token-123")
+
+                let caps = Set(hello.caps ?? [])
+                #expect(caps.contains(ClawdisCapability.canvas.rawValue))
+                #expect(caps.contains(ClawdisCapability.screen.rawValue))
+                #expect(caps.contains(ClawdisCapability.voiceWake.rawValue))
+                #expect(!caps.contains(ClawdisCapability.camera.rawValue))
+
+                let commands = Set(hello.commands ?? [])
+                #expect(commands.contains(ClawdisCanvasCommand.present.rawValue))
+                #expect(commands.contains(ClawdisScreenCommand.record.rawValue))
+                #expect(!commands.contains(ClawdisCameraCommand.snap.rawValue))
+
+                #expect(!(hello.platform ?? "").isEmpty)
+                #expect(!(hello.deviceFamily ?? "").isEmpty)
+                #expect(!(hello.modelIdentifier ?? "").isEmpty)
+                #expect(!(hello.version ?? "").isEmpty)
+            }
+        }
+    }
+
+    @Test @MainActor func makeHelloIncludesCameraCommandsWhenEnabled() {
+        withKeychainValues([instanceIdEntry: nil, preferredBridgeEntry: nil, lastBridgeEntry: nil]) {
+            withUserDefaults([
+                "node.instanceId": "ios-test",
+                "node.displayName": "Test Node",
+                "camera.enabled": true,
+                VoiceWakePreferences.enabledKey: false,
+            ]) {
+                let appModel = NodeAppModel()
+                let controller = BridgeConnectionController(appModel: appModel, startDiscovery: false)
+                let hello = controller._test_makeHello(token: "token-456")
+
+                let caps = Set(hello.caps ?? [])
+                #expect(caps.contains(ClawdisCapability.camera.rawValue))
+
+                let commands = Set(hello.commands ?? [])
+                #expect(commands.contains(ClawdisCameraCommand.snap.rawValue))
+                #expect(commands.contains(ClawdisCameraCommand.clip.rawValue))
+            }
+        }
+    }
+}

apps/ios/Tests/BridgeDiscoveryModelTests.swift

@@ -0,0 +1,22 @@
+import Testing
+@testable import Clawdis
+
+@Suite(.serialized) struct BridgeDiscoveryModelTests {
+    @Test @MainActor func debugLoggingCapturesLifecycleAndResets() {
+        let model = BridgeDiscoveryModel()
+
+        #expect(model.debugLog.isEmpty)
+        #expect(model.statusText == "Idle")
+
+        model.setDebugLoggingEnabled(true)
+        #expect(model.debugLog.count >= 2)
+
+        model.stop()
+        #expect(model.statusText == "Stopped")
+        #expect(model.bridges.isEmpty)
+        #expect(model.debugLog.count >= 3)
+
+        model.setDebugLoggingEnabled(false)
+        #expect(model.debugLog.isEmpty)
+    }
+}

apps/ios/Tests/BridgeSettingsStoreTests.swift

@@ -0,0 +1,127 @@
+import Foundation
+import Testing
+@testable import Clawdis
+
+private struct KeychainEntry: Hashable {
+    let service: String
+    let account: String
+}
+
+private let bridgeService = "com.steipete.clawdis.bridge"
+private let nodeService = "com.steipete.clawdis.node"
+private let instanceIdEntry = KeychainEntry(service: nodeService, account: "instanceId")
+private let preferredBridgeEntry = KeychainEntry(service: bridgeService, account: "preferredStableID")
+private let lastBridgeEntry = KeychainEntry(service: bridgeService, account: "lastDiscoveredStableID")
+
+private func snapshotDefaults(_ keys: [String]) -> [String: Any?] {
+    let defaults = UserDefaults.standard
+    var snapshot: [String: Any?] = [:]
+    for key in keys {
+        snapshot[key] = defaults.object(forKey: key)
+    }
+    return snapshot
+}
+
+private func applyDefaults(_ values: [String: Any?]) {
+    let defaults = UserDefaults.standard
+    for (key, value) in values {
+        if let value {
+            defaults.set(value, forKey: key)
+        } else {
+            defaults.removeObject(forKey: key)
+        }
+    }
+}
+
+private func restoreDefaults(_ snapshot: [String: Any?]) {
+    applyDefaults(snapshot)
+}
+
+private func snapshotKeychain(_ entries: [KeychainEntry]) -> [KeychainEntry: String?] {
+    var snapshot: [KeychainEntry: String?] = [:]
+    for entry in entries {
+        snapshot[entry] = KeychainStore.loadString(service: entry.service, account: entry.account)
+    }
+    return snapshot
+}
+
+private func applyKeychain(_ values: [KeychainEntry: String?]) {
+    for (entry, value) in values {
+        if let value {
+            _ = KeychainStore.saveString(value, service: entry.service, account: entry.account)
+        } else {
+            _ = KeychainStore.delete(service: entry.service, account: entry.account)
+        }
+    }
+}
+
+private func restoreKeychain(_ snapshot: [KeychainEntry: String?]) {
+    applyKeychain(snapshot)
+}
+
+@Suite(.serialized) struct BridgeSettingsStoreTests {
+    @Test func bootstrapCopiesDefaultsToKeychainWhenMissing() {
+        let defaultsKeys = [
+            "node.instanceId",
+            "bridge.preferredStableID",
+            "bridge.lastDiscoveredStableID",
+        ]
+        let entries = [instanceIdEntry, preferredBridgeEntry, lastBridgeEntry]
+        let defaultsSnapshot = snapshotDefaults(defaultsKeys)
+        let keychainSnapshot = snapshotKeychain(entries)
+        defer {
+            restoreDefaults(defaultsSnapshot)
+            restoreKeychain(keychainSnapshot)
+        }
+
+        applyDefaults([
+            "node.instanceId": "node-test",
+            "bridge.preferredStableID": "preferred-test",
+            "bridge.lastDiscoveredStableID": "last-test",
+        ])
+        applyKeychain([
+            instanceIdEntry: nil,
+            preferredBridgeEntry: nil,
+            lastBridgeEntry: nil,
+        ])
+
+        BridgeSettingsStore.bootstrapPersistence()
+
+        #expect(KeychainStore.loadString(service: nodeService, account: "instanceId") == "node-test")
+        #expect(KeychainStore.loadString(service: bridgeService, account: "preferredStableID") == "preferred-test")
+        #expect(KeychainStore.loadString(service: bridgeService, account: "lastDiscoveredStableID") == "last-test")
+    }
+
+    @Test func bootstrapCopiesKeychainToDefaultsWhenMissing() {
+        let defaultsKeys = [
+            "node.instanceId",
+            "bridge.preferredStableID",
+            "bridge.lastDiscoveredStableID",
+        ]
+        let entries = [instanceIdEntry, preferredBridgeEntry, lastBridgeEntry]
+        let defaultsSnapshot = snapshotDefaults(defaultsKeys)
+        let keychainSnapshot = snapshotKeychain(entries)
+        defer {
+            restoreDefaults(defaultsSnapshot)
+            restoreKeychain(keychainSnapshot)
+        }
+
+        applyDefaults([
+            "node.instanceId": nil,
+            "bridge.preferredStableID": nil,
+            "bridge.lastDiscoveredStableID": nil,
+        ])
+        applyKeychain([
+            instanceIdEntry: "node-from-keychain",
+            preferredBridgeEntry: "preferred-from-keychain",
+            lastBridgeEntry: "last-from-keychain",
+        ])
+
+        BridgeSettingsStore.bootstrapPersistence()
+
+        let defaults = UserDefaults.standard
+        #expect(defaults.string(forKey: "node.instanceId") == "node-from-keychain")
+        #expect(defaults.string(forKey: "bridge.preferredStableID") == "preferred-from-keychain")
+        #expect(defaults.string(forKey: "bridge.lastDiscoveredStableID") == "last-from-keychain")
+    }
+}

apps/ios/Tests/NodeAppModelInvokeTests.swift

@@ -0,0 +1,194 @@
+import ClawdisKit
+import Foundation
+import Testing
+import UIKit
+@testable import Clawdis
+
+private func withUserDefaults<T>(_ updates: [String: Any?], _ body: () throws -> T) rethrows -> T {
+    let defaults = UserDefaults.standard
+    var snapshot: [String: Any?] = [:]
+    for key in updates.keys {
+        snapshot[key] = defaults.object(forKey: key)
+    }
+    for (key, value) in updates {
+        if let value {
+            defaults.set(value, forKey: key)
+        } else {
+            defaults.removeObject(forKey: key)
+        }
+    }
+    defer {
+        for (key, value) in snapshot {
+            if let value {
+                defaults.set(value, forKey: key)
+            } else {
+                defaults.removeObject(forKey: key)
+            }
+        }
+    }
+    return try body()
+}
+
+@Suite(.serialized) struct NodeAppModelInvokeTests {
+    @Test @MainActor func decodeParamsFailsWithoutJSON() {
+        #expect(throws: Error.self) {
+            _ = try NodeAppModel._test_decodeParams(ClawdisCanvasNavigateParams.self, from: nil)
+        }
+    }
+
+    @Test @MainActor func encodePayloadEmitsJSON() throws {
+        struct Payload: Codable, Equatable {
+            var value: String
+        }
+        let json = try NodeAppModel._test_encodePayload(Payload(value: "ok"))
+        #expect(json.contains("\"value\""))
+    }
+
+    @Test @MainActor func handleInvokeRejectsBackgroundCommands() async {
+        let appModel = NodeAppModel()
+        appModel.setScenePhase(.background)
+
+        let req = BridgeInvokeRequest(id: "bg", command: ClawdisCanvasCommand.present.rawValue)
+        let res = await appModel._test_handleInvoke(req)
+        #expect(res.ok == false)
+        #expect(res.error?.code == .backgroundUnavailable)
+    }
+
+    @Test @MainActor func handleInvokeRejectsCameraWhenDisabled() async {
+        let appModel = NodeAppModel()
+        let req = BridgeInvokeRequest(id: "cam", command: ClawdisCameraCommand.snap.rawValue)
+
+        let defaults = UserDefaults.standard
+        let key = "camera.enabled"
+        let previous = defaults.object(forKey: key)
+        defaults.set(false, forKey: key)
+        defer {
+            if let previous {
+                defaults.set(previous, forKey: key)
+            } else {
+                defaults.removeObject(forKey: key)
+            }
+        }
+
+        let res = await appModel._test_handleInvoke(req)
+        #expect(res.ok == false)
+        #expect(res.error?.code == .unavailable)
+        #expect(res.error?.message.contains("CAMERA_DISABLED") == true)
+    }
+
+    @Test @MainActor func handleInvokeRejectsInvalidScreenFormat() async {
+        let appModel = NodeAppModel()
+        let params = ClawdisScreenRecordParams(format: "gif")
+        let data = try? JSONEncoder().encode(params)
+        let json = data.flatMap { String(data: $0, encoding: .utf8) }
+
+        let req = BridgeInvokeRequest(
+            id: "screen",
+            command: ClawdisScreenCommand.record.rawValue,
+            paramsJSON: json)
+
+        let res = await appModel._test_handleInvoke(req)
+        #expect(res.ok == false)
+        #expect(res.error?.message.contains("screen format must be mp4") == true)
+    }
+
+    @Test @MainActor func handleInvokeCanvasCommandsUpdateScreen() async throws {
+        let appModel = NodeAppModel()
+        appModel.screen.navigate(to: "http://example.com")
+
+        let present = BridgeInvokeRequest(id: "present", command: ClawdisCanvasCommand.present.rawValue)
+        let presentRes = await appModel._test_handleInvoke(present)
+        #expect(presentRes.ok == true)
+        #expect(appModel.screen.urlString.isEmpty)
+
+        let navigateParams = ClawdisCanvasNavigateParams(url: "http://localhost:18789/")
+        let navData = try JSONEncoder().encode(navigateParams)
+        let navJSON = String(decoding: navData, as: UTF8.self)
+        let navigate = BridgeInvokeRequest(
+            id: "nav",
+            command: ClawdisCanvasCommand.navigate.rawValue,
+            paramsJSON: navJSON)
+        let navRes = await appModel._test_handleInvoke(navigate)
+        #expect(navRes.ok == true)
+        #expect(appModel.screen.urlString == "http://localhost:18789/")
+
+        let evalParams = ClawdisCanvasEvalParams(javaScript: "1+1")
+        let evalData = try JSONEncoder().encode(evalParams)
+        let evalJSON = String(decoding: evalData, as: UTF8.self)
+        let eval = BridgeInvokeRequest(
+            id: "eval",
+            command: ClawdisCanvasCommand.evalJS.rawValue,
+            paramsJSON: evalJSON)
+        let evalRes = await appModel._test_handleInvoke(eval)
+        #expect(evalRes.ok == true)
+        let payloadData = try #require(evalRes.payloadJSON?.data(using: .utf8))
+        let payload = try JSONSerialization.jsonObject(with: payloadData) as? [String: Any]
+        #expect(payload?["result"] as? String == "2")
+    }
+
+    @Test @MainActor func handleInvokeA2UICommandsFailWhenHostMissing() async throws {
+        let appModel = NodeAppModel()
+
+        let reset = BridgeInvokeRequest(id: "reset", command: ClawdisCanvasA2UICommand.reset.rawValue)
+        let resetRes = await appModel._test_handleInvoke(reset)
+        #expect(resetRes.ok == false)
+        #expect(resetRes.error?.message.contains("A2UI_HOST_NOT_CONFIGURED") == true)
+
+        let jsonl = "{\"beginRendering\":{}}"
+        let pushParams = ClawdisCanvasA2UIPushJSONLParams(jsonl: jsonl)
+        let pushData = try JSONEncoder().encode(pushParams)
+        let pushJSON = String(decoding: pushData, as: UTF8.self)
+        let push = BridgeInvokeRequest(
+            id: "push",
+            command: ClawdisCanvasA2UICommand.pushJSONL.rawValue,
+            paramsJSON: pushJSON)
+        let pushRes = await appModel._test_handleInvoke(push)
+        #expect(pushRes.ok == false)
+        #expect(pushRes.error?.message.contains("A2UI_HOST_NOT_CONFIGURED") == true)
+    }
+
+    @Test @MainActor func handleInvokeUnknownCommandReturnsInvalidRequest() async {
+        let appModel = NodeAppModel()
+        let req = BridgeInvokeRequest(id: "unknown", command: "nope")
+        let res = await appModel._test_handleInvoke(req)
+        #expect(res.ok == false)
+        #expect(res.error?.code == .invalidRequest)
+    }
+
+    @Test @MainActor func handleDeepLinkSetsErrorWhenNotConnected() async {
+        let appModel = NodeAppModel()
+        let url = URL(string: "clawdis://agent?message=hello")!
+        await appModel.handleDeepLink(url: url)
+        #expect(appModel.screen.errorText?.contains("Bridge not connected") == true)
+    }
+
+    @Test @MainActor func handleDeepLinkRejectsOversizedMessage() async {
+        let appModel = NodeAppModel()
+        let msg = String(repeating: "a", count: 20001)
+        let url = URL(string: "clawdis://agent?message=\(msg)")!
+        await appModel.handleDeepLink(url: url)
+        #expect(appModel.screen.errorText?.contains("Deep link too large") == true)
+    }
+
+    @Test @MainActor func sendVoiceTranscriptThrowsWhenBridgeOffline() async {
+        let appModel = NodeAppModel()
+        await #expect(throws: Error.self) {
+            try await appModel.sendVoiceTranscript(text: "hello", sessionKey: "main")
+        }
+    }
+
+    @Test @MainActor func canvasA2UIActionDispatchesStatus() async {
+        let appModel = NodeAppModel()
+        let body: [String: Any] = [
+            "userAction": [
+                "name": "tap",
+                "id": "action-1",
+                "surfaceId": "main",
+                "sourceComponentId": "button-1",
+                "context": ["value": "ok"],
+            ],
+        ]
+        await appModel._test_handleCanvasA2UIAction(body: body)
+        #expect(appModel.screen.urlString.isEmpty)
+    }
+}

apps/ios/Tests/ScreenControllerTests.swift

@@ -43,13 +43,13 @@ import WebKit
 
     @Test @MainActor func localNetworkCanvasURLsAreAllowed() {
         let screen = ScreenController()
-        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://localhost:18793/")!) == true)
-        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://clawd.local:18793/")!) == true)
-        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://peters-mac-studio-1:18793/")!) == true)
-        #expect(screen.isLocalNetworkCanvasURL(URL(string: "https://peters-mac-studio-1.ts.net:18793/")!) == true)
-        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://192.168.0.10:18793/")!) == true)
-        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://10.0.0.10:18793/")!) == true)
-        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://100.123.224.76:18793/")!) == true) // Tailscale CGNAT
+        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://localhost:18789/")!) == true)
+        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://clawd.local:18789/")!) == true)
+        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://peters-mac-studio-1:18789/")!) == true)
+        #expect(screen.isLocalNetworkCanvasURL(URL(string: "https://peters-mac-studio-1.ts.net:18789/")!) == true)
+        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://192.168.0.10:18789/")!) == true)
+        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://10.0.0.10:18789/")!) == true)
+        #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://100.123.224.76:18789/")!) == true) // Tailscale CGNAT
         #expect(screen.isLocalNetworkCanvasURL(URL(string: "https://example.com/")!) == false)
         #expect(screen.isLocalNetworkCanvasURL(URL(string: "http://8.8.8.8/")!) == false)
     }

apps/ios/Tests/ScreenRecordServiceTests.swift

@@ -0,0 +1,32 @@
+import Testing
+@testable import Clawdis
+
+@Suite(.serialized) struct ScreenRecordServiceTests {
+    @Test func clampDefaultsAndBounds() {
+        #expect(ScreenRecordService._test_clampDurationMs(nil) == 10000)
+        #expect(ScreenRecordService._test_clampDurationMs(0) == 250)
+        #expect(ScreenRecordService._test_clampDurationMs(60001) == 60000)
+
+        #expect(ScreenRecordService._test_clampFps(nil) == 10)
+        #expect(ScreenRecordService._test_clampFps(0) == 1)
+        #expect(ScreenRecordService._test_clampFps(120) == 30)
+        #expect(ScreenRecordService._test_clampFps(.infinity) == 10)
+    }
+
+    @Test @MainActor func recordRejectsInvalidScreenIndex() async {
+        let recorder = ScreenRecordService()
+        do {
+            _ = try await recorder.record(
+                screenIndex: 1,
+                durationMs: 250,
+                fps: 5,
+                includeAudio: false,
+                outPath: nil)
+            Issue.record("Expected invalid screen index to throw")
+        } catch let error as ScreenRecordService.ScreenRecordError {
+            #expect(error.localizedDescription.contains("Invalid screen index") == true)
+        } catch {
+            Issue.record("Unexpected error type: \(error)")
+        }
+    }
+}

apps/ios/Tests/VoiceWakeManagerExtractCommandTests.swift

@@ -1,33 +1,90 @@
+import Foundation
 import Testing
+import SwabbleKit
 @testable import Clawdis
 
 @Suite struct VoiceWakeManagerExtractCommandTests {
     @Test func extractCommandReturnsNilWhenNoTriggerFound() {
-        #expect(VoiceWakeManager.extractCommand(from: "hello world", triggers: ["clawd"]) == nil)
+        let transcript = "hello world"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [("hello", 0.0, 0.1), ("world", 0.2, 0.1)])
+        #expect(VoiceWakeManager.extractCommand(from: transcript, segments: segments, triggers: ["clawd"]) == nil)
     }
 
     @Test func extractCommandTrimsTokensAndResult() {
-        let cmd = VoiceWakeManager.extractCommand(from: "hey clawd   do thing  ", triggers: ["  clawd  "])
+        let transcript = "hey clawd do thing"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.9, 0.1),
+                ("thing", 1.1, 0.1),
+            ])
+        let cmd = VoiceWakeManager.extractCommand(
+            from: transcript,
+            segments: segments,
+            triggers: ["  clawd  "],
+            minPostTriggerGap: 0.3)
         #expect(cmd == "do thing")
     }
 
-    @Test func extractCommandPicksLatestTriggerOccurrence() {
-        let transcript = "clawd first\nthen something\nclaude second"
-        let cmd = VoiceWakeManager.extractCommand(from: transcript, triggers: ["clawd", "claude"])
-        #expect(cmd == "second")
-    }
-
-    @Test func extractCommandIsCaseInsensitive() {
-        let cmd = VoiceWakeManager.extractCommand(from: "HELLO CLAWD run it", triggers: ["clawd"])
-        #expect(cmd == "run it")
+    @Test func extractCommandReturnsNilWhenGapTooShort() {
+        let transcript = "hey clawd do thing"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.35, 0.1),
+                ("thing", 0.5, 0.1),
+            ])
+        let cmd = VoiceWakeManager.extractCommand(
+            from: transcript,
+            segments: segments,
+            triggers: ["clawd"],
+            minPostTriggerGap: 0.3)
+        #expect(cmd == nil)
     }
 
     @Test func extractCommandReturnsNilWhenNothingAfterTrigger() {
-        #expect(VoiceWakeManager.extractCommand(from: "hey clawd  \n", triggers: ["clawd"]) == nil)
+        let transcript = "hey clawd"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [("hey", 0.0, 0.1), ("clawd", 0.2, 0.1)])
+        #expect(VoiceWakeManager.extractCommand(from: transcript, segments: segments, triggers: ["clawd"]) == nil)
     }
 
     @Test func extractCommandIgnoresEmptyTriggers() {
-        let cmd = VoiceWakeManager.extractCommand(from: "hey clawd do thing", triggers: ["", "   ", "clawd"])
+        let transcript = "hey clawd do thing"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.9, 0.1),
+                ("thing", 1.1, 0.1),
+            ])
+        let cmd = VoiceWakeManager.extractCommand(
+            from: transcript,
+            segments: segments,
+            triggers: ["", "   ", "clawd"],
+            minPostTriggerGap: 0.3)
         #expect(cmd == "do thing")
     }
 }
+
+private func makeSegments(
+    transcript: String,
+    words: [(String, TimeInterval, TimeInterval)])
+-> [WakeWordSegment] {
+    var searchStart = transcript.startIndex
+    var output: [WakeWordSegment] = []
+    for (word, start, duration) in words {
+        let range = transcript.range(of: word, range: searchStart..<transcript.endIndex)
+        output.append(WakeWordSegment(text: word, start: start, duration: duration, range: range))
+        if let range { searchStart = range.upperBound }
+    }
+    return output
+}

apps/ios/Tests/VoiceWakeManagerStateTests.swift

@@ -0,0 +1,65 @@
+import Foundation
+import Testing
+import SwabbleKit
+@testable import Clawdis
+
+@Suite(.serialized) struct VoiceWakeManagerStateTests {
+    @Test @MainActor func suspendAndResumeCycleUpdatesState() async {
+        let manager = VoiceWakeManager()
+        manager.isEnabled = true
+        manager.isListening = true
+        manager.statusText = "Listening"
+
+        let suspended = manager.suspendForExternalAudioCapture()
+        #expect(suspended == true)
+        #expect(manager.isListening == false)
+        #expect(manager.statusText == "Paused")
+
+        manager.resumeAfterExternalAudioCapture(wasSuspended: true)
+        try? await Task.sleep(nanoseconds: 900_000_000)
+        #expect(manager.statusText.contains("Voice Wake") == true)
+    }
+
+    @Test @MainActor func handleRecognitionCallbackRestartsOnError() async {
+        let manager = VoiceWakeManager()
+        manager.isEnabled = true
+        manager.isListening = true
+
+        manager._test_handleRecognitionCallback(transcript: nil, segments: [], errorText: "boom")
+        #expect(manager.statusText.contains("Recognizer error") == true)
+        #expect(manager.isListening == false)
+
+        try? await Task.sleep(nanoseconds: 900_000_000)
+        #expect(manager.statusText.contains("Voice Wake") == true)
+    }
+
+    @Test @MainActor func handleRecognitionCallbackDispatchesCommand() async {
+        let manager = VoiceWakeManager()
+        manager.triggerWords = ["clawd"]
+        manager.isEnabled = true
+
+        actor CaptureBox {
+            var value: String?
+            func set(_ next: String) { self.value = next }
+        }
+        let capture = CaptureBox()
+        manager.configure { cmd in
+            await capture.set(cmd)
+        }
+
+        let transcript = "clawd hello"
+        let clawdRange = transcript.range(of: "clawd")!
+        let helloRange = transcript.range(of: "hello")!
+        let segments = [
+            WakeWordSegment(text: "clawd", start: 0.0, duration: 0.2, range: clawdRange),
+            WakeWordSegment(text: "hello", start: 0.8, duration: 0.2, range: helloRange),
+        ]
+
+        manager._test_handleRecognitionCallback(transcript: transcript, segments: segments, errorText: nil)
+        #expect(manager.lastTriggeredCommand == "hello")
+        #expect(manager.statusText == "Triggered")
+
+        try? await Task.sleep(nanoseconds: 300_000_000)
+        #expect(await capture.value == "hello")
+    }
+}

apps/ios/fastlane/Fastfile

@@ -1,3 +1,5 @@
+require "shellwords"
+
 default_platform(:ios)
 
 def load_env_file(path)
@@ -61,6 +63,12 @@ platform :ios do
     api_key = asc_api_key
 
     team_id = ENV["IOS_DEVELOPMENT_TEAM"]
+    if team_id.nil? || team_id.strip.empty?
+      helper_path = File.expand_path("../../scripts/ios-team-id.sh", __dir__)
+      if File.exist?(helper_path)
+        team_id = sh("bash #{helper_path.shellescape}").strip
+      end
+    end
     UI.user_error!("Missing IOS_DEVELOPMENT_TEAM (Apple Team ID). Add it to fastlane/.env or export it in your shell.") if team_id.nil? || team_id.strip.empty?
 
     build_app(

apps/ios/fastlane/SETUP.md

@@ -22,10 +22,11 @@ ASC_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
 IOS_DEVELOPMENT_TEAM=YOUR_TEAM_ID
 ```
 
+Tip: run `scripts/ios-team-id.sh` from the repo root to print a Team ID to paste into `.env`. Fastlane falls back to this helper if `IOS_DEVELOPMENT_TEAM` is missing.
+
 Run:
 
 ```bash
 cd apps/ios
 fastlane beta
 ```
-

apps/ios/project.yml

@@ -8,6 +8,8 @@ options:
 packages:
   ClawdisKit:
     path: ../shared/ClawdisKit
+  Swabble:
+    path: ../../Swabble
 
 schemes:
   Clawdis:
@@ -29,27 +31,35 @@ targets:
       - package: ClawdisKit
       - package: ClawdisKit
         product: ClawdisChatUI
+      - package: Swabble
+        product: SwabbleKit
+      - sdk: AppIntents.framework
     preBuildScripts:
       - name: SwiftFormat (lint)
         basedOnDependencyAnalysis: false
+        inputFileLists:
+          - $(SRCROOT)/SwiftSources.input.xcfilelist
         script: |
           set -euo pipefail
+          export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
           if ! command -v swiftformat >/dev/null 2>&1; then
             echo "error: swiftformat not found (brew install swiftformat)" >&2
             exit 1
           fi
           swiftformat --lint --config "$SRCROOT/../../.swiftformat" \
-            "$SRCROOT/Sources" \
-            "$SRCROOT/../shared/ClawdisKit/Sources"
+            --filelist "$SRCROOT/SwiftSources.input.xcfilelist"
       - name: SwiftLint
         basedOnDependencyAnalysis: false
+        inputFileLists:
+          - $(SRCROOT)/SwiftSources.input.xcfilelist
         script: |
           set -euo pipefail
+          export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
           if ! command -v swiftlint >/dev/null 2>&1; then
             echo "error: swiftlint not found (brew install swiftlint)" >&2
             exit 1
           fi
-          swiftlint lint --config "$SRCROOT/.swiftlint.yml"
+          swiftlint lint --config "$SRCROOT/.swiftlint.yml" --use-script-input-file-lists
     settings:
       base:
         PRODUCT_BUNDLE_IDENTIFIER: com.steipete.clawdis.ios
@@ -65,6 +75,8 @@ targets:
         UIBackgroundModes:
           - audio
         NSLocalNetworkUsageDescription: Clawdis discovers and connects to your Clawdis bridge on the local network.
+        NSAppTransportSecurity:
+          NSAllowsArbitraryLoadsInWebContent: true
         NSBonjourServices:
           - _clawdis-bridge._tcp
         NSCameraUsageDescription: Clawdis can capture photos or short video clips when requested via the bridge.
@@ -78,6 +90,8 @@ targets:
       - path: Tests
     dependencies:
       - target: Clawdis
+      - package: Swabble
+        product: SwabbleKit
     settings:
       base:
         PRODUCT_BUNDLE_IDENTIFIER: com.steipete.clawdis.ios.tests

apps/macos/Package.swift

@@ -1,5 +1,5 @@
 // swift-tools-version: 6.2
-// Package manifest for the Clawdis macOS companion (menu bar app + CLI + IPC library).
+// Package manifest for the Clawdis macOS companion (menu bar app + IPC library).
 
 import PackageDescription
 
@@ -11,13 +11,13 @@ let package = Package(
     products: [
         .library(name: "ClawdisIPC", targets: ["ClawdisIPC"]),
         .executable(name: "Clawdis", targets: ["Clawdis"]),
-        .executable(name: "ClawdisCLI", targets: ["ClawdisCLI"]),
     ],
     dependencies: [
         .package(url: "https://github.com/orchetect/MenuBarExtraAccess", exact: "1.2.2"),
         .package(url: "https://github.com/swiftlang/swift-subprocess.git", from: "0.1.0"),
         .package(url: "https://github.com/sparkle-project/Sparkle", from: "2.8.1"),
         .package(path: "../shared/ClawdisKit"),
+        .package(path: "../../Swabble"),
         .package(path: "../../Peekaboo/Core/PeekabooCore"),
         .package(path: "../../Peekaboo/Core/PeekabooAutomationKit"),
     ],
@@ -42,6 +42,7 @@ let package = Package(
                 "ClawdisProtocol",
                 .product(name: "ClawdisKit", package: "ClawdisKit"),
                 .product(name: "ClawdisChatUI", package: "ClawdisKit"),
+                .product(name: "SwabbleKit", package: "swabble"),
                 .product(name: "MenuBarExtraAccess", package: "MenuBarExtraAccess"),
                 .product(name: "Subprocess", package: "swift-subprocess"),
                 .product(name: "Sparkle", package: "Sparkle"),
@@ -55,25 +56,14 @@ let package = Package(
             swiftSettings: [
                 .enableUpcomingFeature("StrictConcurrency"),
             ]),
-        .executableTarget(
-            name: "ClawdisCLI",
-            dependencies: [
-                "ClawdisIPC",
-                "ClawdisProtocol",
-            ],
-            swiftSettings: [
-                .enableUpcomingFeature("StrictConcurrency"),
-            ]),
         .testTarget(
             name: "ClawdisIPCTests",
-            dependencies: ["ClawdisIPC", "Clawdis", "ClawdisProtocol"],
-            swiftSettings: [
-                .enableUpcomingFeature("StrictConcurrency"),
-                .enableExperimentalFeature("SwiftTesting"),
-            ]),
-        .testTarget(
-            name: "ClawdisCLITests",
-            dependencies: ["ClawdisCLI"],
+            dependencies: [
+                "ClawdisIPC",
+                "Clawdis",
+                "ClawdisProtocol",
+                .product(name: "SwabbleKit", package: "swabble"),
+            ],
             swiftSettings: [
                 .enableUpcomingFeature("StrictConcurrency"),
                 .enableExperimentalFeature("SwiftTesting"),

apps/macos/Sources/Clawdis/AboutSettings.swift

@@ -92,10 +92,12 @@ struct AboutSettings: View {
             guard let updater, !self.didLoadUpdaterState else { return }
             // Keep Sparkle’s auto-check setting in sync with the persisted toggle.
             updater.automaticallyChecksForUpdates = self.autoCheckEnabled
+            updater.automaticallyDownloadsUpdates = self.autoCheckEnabled
             self.didLoadUpdaterState = true
         }
         .onChange(of: self.autoCheckEnabled) { _, newValue in
             self.updater?.automaticallyChecksForUpdates = newValue
+            self.updater?.automaticallyDownloadsUpdates = newValue
         }
     }
 

apps/macos/Sources/Clawdis/AgeFormatting.swift

@@ -0,0 +1,17 @@
+import Foundation
+
+// Human-friendly age string (e.g., "2m ago").
+func age(from date: Date, now: Date = .init()) -> String {
+    let seconds = max(0, Int(now.timeIntervalSince(date)))
+    let minutes = seconds / 60
+    let hours = minutes / 60
+    let days = hours / 24
+
+    if seconds < 60 { return "just now" }
+    if minutes == 1 { return "1 minute ago" }
+    if minutes < 60 { return "\(minutes)m ago" }
+    if hours == 1 { return "1 hour ago" }
+    if hours < 24 { return "\(hours)h ago" }
+    if days == 1 { return "yesterday" }
+    return "\(days)d ago"
+}

apps/macos/Sources/Clawdis/AgentIdentity.swift

@@ -1,45 +0,0 @@
-import Foundation
-
-struct AgentIdentity: Codable, Equatable {
-    var name: String
-    var theme: String
-    var emoji: String
-
-    var isEmpty: Bool {
-        self.name.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty &&
-            self.theme.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty &&
-            self.emoji.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
-    }
-}
-
-enum AgentIdentityEmoji {
-    static func suggest(theme: String) -> String {
-        let normalized = theme.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-        if normalized.isEmpty { return "🦞" }
-
-        let table: [(needle: String, emoji: String)] = [
-            ("lobster", "🦞"),
-            ("sloth", "🦥"),
-            ("octopus", "🐙"),
-            ("crab", "🦀"),
-            ("shark", "🦈"),
-            ("cat", "🐈"),
-            ("dog", "🐕"),
-            ("owl", "🦉"),
-            ("fox", "🦊"),
-            ("otter", "🦦"),
-            ("raccoon", "🦝"),
-            ("badger", "🦡"),
-            ("hedgehog", "🦔"),
-            ("koala", "🐨"),
-            ("penguin", "🐧"),
-            ("frog", "🐸"),
-            ("bear", "🐻"),
-        ]
-
-        for entry in table where normalized.contains(entry.needle) {
-            return entry.emoji
-        }
-        return "🦞"
-    }
-}

apps/macos/Sources/Clawdis/AgentWorkspace.swift

@@ -4,8 +4,23 @@ import OSLog
 enum AgentWorkspace {
     private static let logger = Logger(subsystem: "com.steipete.clawdis", category: "workspace")
     static let agentsFilename = "AGENTS.md"
-    static let identityStartMarker = "<!-- clawdis:identity:start -->"
-    static let identityEndMarker = "<!-- clawdis:identity:end -->"
+    static let soulFilename = "SOUL.md"
+    static let identityFilename = "IDENTITY.md"
+    static let userFilename = "USER.md"
+    static let bootstrapFilename = "BOOTSTRAP.md"
+    private static let templateDirname = "templates"
+    private static let ignoredEntries: Set<String> = [".DS_Store", ".git", ".gitignore"]
+    private static let templateEntries: Set<String> = [
+        AgentWorkspace.agentsFilename,
+        AgentWorkspace.soulFilename,
+        AgentWorkspace.identityFilename,
+        AgentWorkspace.userFilename,
+        AgentWorkspace.bootstrapFilename,
+    ]
+    enum BootstrapSafety: Equatable {
+        case safe
+        case unsafe(reason: String)
+    }
 
     static func displayPath(for url: URL) -> String {
         let home = FileManager.default.homeDirectoryForCurrentUser.path
@@ -28,49 +43,128 @@ enum AgentWorkspace {
         workspaceURL.appendingPathComponent(self.agentsFilename)
     }
 
+    static func workspaceEntries(workspaceURL: URL) throws -> [String] {
+        let contents = try FileManager.default.contentsOfDirectory(atPath: workspaceURL.path)
+        return contents.filter { !self.ignoredEntries.contains($0) }
+    }
+
+    static func isWorkspaceEmpty(workspaceURL: URL) -> Bool {
+        let fm = FileManager.default
+        var isDir: ObjCBool = false
+        if !fm.fileExists(atPath: workspaceURL.path, isDirectory: &isDir) {
+            return true
+        }
+        guard isDir.boolValue else { return false }
+        guard let entries = try? self.workspaceEntries(workspaceURL: workspaceURL) else { return false }
+        return entries.isEmpty
+    }
+
+    static func isTemplateOnlyWorkspace(workspaceURL: URL) -> Bool {
+        guard let entries = try? self.workspaceEntries(workspaceURL: workspaceURL) else { return false }
+        guard !entries.isEmpty else { return true }
+        return Set(entries).isSubset(of: self.templateEntries)
+    }
+
+    static func bootstrapSafety(for workspaceURL: URL) -> BootstrapSafety {
+        let fm = FileManager.default
+        var isDir: ObjCBool = false
+        if !fm.fileExists(atPath: workspaceURL.path, isDirectory: &isDir) {
+            return .safe
+        }
+        if !isDir.boolValue {
+            return .unsafe(reason: "Workspace path points to a file.")
+        }
+        let agentsURL = self.agentsURL(workspaceURL: workspaceURL)
+        if fm.fileExists(atPath: agentsURL.path) {
+            return .safe
+        }
+        do {
+            let entries = try self.workspaceEntries(workspaceURL: workspaceURL)
+            return entries.isEmpty
+                ? .safe
+                : .unsafe(reason: "Folder isn't empty. Choose a new folder or add AGENTS.md first.")
+        } catch {
+            return .unsafe(reason: "Couldn't inspect the workspace folder.")
+        }
+    }
+
     static func bootstrap(workspaceURL: URL) throws -> URL {
+        let shouldSeedBootstrap = self.isWorkspaceEmpty(workspaceURL: workspaceURL)
         try FileManager.default.createDirectory(at: workspaceURL, withIntermediateDirectories: true)
         let agentsURL = self.agentsURL(workspaceURL: workspaceURL)
         if !FileManager.default.fileExists(atPath: agentsURL.path) {
             try self.defaultTemplate().write(to: agentsURL, atomically: true, encoding: .utf8)
             self.logger.info("Created AGENTS.md at \(agentsURL.path, privacy: .public)")
         }
+        let soulURL = workspaceURL.appendingPathComponent(self.soulFilename)
+        if !FileManager.default.fileExists(atPath: soulURL.path) {
+            try self.defaultSoulTemplate().write(to: soulURL, atomically: true, encoding: .utf8)
+            self.logger.info("Created SOUL.md at \(soulURL.path, privacy: .public)")
+        }
+        let identityURL = workspaceURL.appendingPathComponent(self.identityFilename)
+        if !FileManager.default.fileExists(atPath: identityURL.path) {
+            try self.defaultIdentityTemplate().write(to: identityURL, atomically: true, encoding: .utf8)
+            self.logger.info("Created IDENTITY.md at \(identityURL.path, privacy: .public)")
+        }
+        let userURL = workspaceURL.appendingPathComponent(self.userFilename)
+        if !FileManager.default.fileExists(atPath: userURL.path) {
+            try self.defaultUserTemplate().write(to: userURL, atomically: true, encoding: .utf8)
+            self.logger.info("Created USER.md at \(userURL.path, privacy: .public)")
+        }
+        let bootstrapURL = workspaceURL.appendingPathComponent(self.bootstrapFilename)
+        if shouldSeedBootstrap, !FileManager.default.fileExists(atPath: bootstrapURL.path) {
+            try self.defaultBootstrapTemplate().write(to: bootstrapURL, atomically: true, encoding: .utf8)
+            self.logger.info("Created BOOTSTRAP.md at \(bootstrapURL.path, privacy: .public)")
+        }
         return agentsURL
     }
 
-    static func upsertIdentity(workspaceURL: URL, identity: AgentIdentity) throws {
-        let agentsURL = try self.bootstrap(workspaceURL: workspaceURL)
-        var content = (try? String(contentsOf: agentsURL, encoding: .utf8)) ?? ""
-        let block = self.identityBlock(identity: identity)
-
-        if let start = content.range(of: self.identityStartMarker),
-           let end = content.range(of: self.identityEndMarker),
-           start.lowerBound < end.upperBound
-        {
-            content.replaceSubrange(
-                start.lowerBound..<end.upperBound,
-                with: block.trimmingCharacters(in: .whitespacesAndNewlines))
-        } else if let insert = self.identityInsertRange(in: content) {
-            content.insert(contentsOf: "\n\n## Identity\n\(block)\n", at: insert.upperBound)
-        } else {
-            content = [content.trimmingCharacters(in: .whitespacesAndNewlines), "## Identity\n\(block)"]
-                .filter { !$0.isEmpty }
-                .joined(separator: "\n\n")
-                .appending("\n")
+    static func needsBootstrap(workspaceURL: URL) -> Bool {
+        let fm = FileManager.default
+        var isDir: ObjCBool = false
+        if !fm.fileExists(atPath: workspaceURL.path, isDirectory: &isDir) {
+            return true
         }
+        guard isDir.boolValue else { return true }
+        if self.hasIdentity(workspaceURL: workspaceURL) {
+            return false
+        }
+        let bootstrapURL = workspaceURL.appendingPathComponent(self.bootstrapFilename)
+        guard fm.fileExists(atPath: bootstrapURL.path) else { return false }
+        return self.isTemplateOnlyWorkspace(workspaceURL: workspaceURL)
+    }
 
-        try content.write(to: agentsURL, atomically: true, encoding: .utf8)
-        self.logger.info("Updated identity in \(agentsURL.path, privacy: .public)")
+    static func hasIdentity(workspaceURL: URL) -> Bool {
+        let identityURL = workspaceURL.appendingPathComponent(self.identityFilename)
+        guard let contents = try? String(contentsOf: identityURL, encoding: .utf8) else { return false }
+        return self.identityLinesHaveValues(contents)
+    }
+
+    private static func identityLinesHaveValues(_ content: String) -> Bool {
+        for line in content.split(separator: "\n") {
+            let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard trimmed.hasPrefix("-"), let colon = trimmed.firstIndex(of: ":") else { continue }
+            let value = trimmed[trimmed.index(after: colon)...].trimmingCharacters(in: .whitespacesAndNewlines)
+            if !value.isEmpty {
+                return true
+            }
+        }
+        return false
     }
 
     static func defaultTemplate() -> String {
-        """
-        # AGENTS.md — Clawdis Workspace
+        let fallback = """
+        # AGENTS.md - Clawdis Workspace
 
-        This folder is the assistant’s working directory.
+        This folder is the assistant's working directory.
+
+        ## First run (one-time)
+        - If BOOTSTRAP.md exists, follow its ritual and delete it once complete.
+        - Your agent identity lives in IDENTITY.md.
+        - Your profile lives in USER.md.
 
         ## Backup tip (recommended)
-        If you treat this workspace as the agent’s “memory”, make it a git repo (ideally private) so your identity
+        If you treat this workspace as the agent's "memory", make it a git repo (ideally private) so identity
         and notes are backed up.
 
         ```bash
@@ -80,34 +174,167 @@ enum AgentWorkspace {
         ```
 
         ## Safety defaults
-        - Don’t exfiltrate secrets or private data.
-        - Don’t run destructive commands unless explicitly asked.
+        - Don't exfiltrate secrets or private data.
+        - Don't run destructive commands unless explicitly asked.
         - Be concise in chat; write longer output to files in this workspace.
 
+        ## Daily memory (recommended)
+        - Keep a short daily log at memory/YYYY-MM-DD.md (create memory/ if needed).
+        - On session start, read today + yesterday if present.
+        - Capture durable facts, preferences, and decisions; avoid secrets.
+
         ## Customize
-        - Add your preferred style, rules, and “memory” here.
+        - Add your preferred style, rules, and "memory" here.
         """
+        return self.loadTemplate(named: self.agentsFilename, fallback: fallback)
     }
 
-    private static func identityBlock(identity: AgentIdentity) -> String {
-        let name = identity.name.trimmingCharacters(in: .whitespacesAndNewlines)
-        let theme = identity.theme.trimmingCharacters(in: .whitespacesAndNewlines)
-        let emoji = identity.emoji.trimmingCharacters(in: .whitespacesAndNewlines)
+    static func defaultSoulTemplate() -> String {
+        let fallback = """
+        # SOUL.md - Persona & Boundaries
 
-        return """
-        \(self.identityStartMarker)
-        - Name: \(name)
-        - Theme: \(theme)
-        - Emoji: \(emoji)
-        \(self.identityEndMarker)
+        Describe who the assistant is, tone, and boundaries.
+
+        - Keep replies concise and direct.
+        - Ask clarifying questions when needed.
+        - Never send streaming/partial replies to external messaging surfaces.
         """
+        return self.loadTemplate(named: self.soulFilename, fallback: fallback)
     }
 
-    private static func identityInsertRange(in content: String) -> Range<String.Index>? {
-        if let firstHeading = content.range(of: "\n") {
-            // Insert after the first line (usually "# AGENTS.md …")
-            return firstHeading
+    static func defaultIdentityTemplate() -> String {
+        let fallback = """
+        # IDENTITY.md - Agent Identity
+
+        - Name:
+        - Creature:
+        - Vibe:
+        - Emoji:
+        """
+        return self.loadTemplate(named: self.identityFilename, fallback: fallback)
+    }
+
+    static func defaultUserTemplate() -> String {
+        let fallback = """
+        # USER.md - User Profile
+
+        - Name:
+        - Preferred address:
+        - Pronouns (optional):
+        - Timezone (optional):
+        - Notes:
+        """
+        return self.loadTemplate(named: self.userFilename, fallback: fallback)
+    }
+
+    static func defaultBootstrapTemplate() -> String {
+        let fallback = """
+        # BOOTSTRAP.md - First Run Ritual (delete after)
+
+        Hello. I was just born.
+
+        ## Your mission
+        Start a short, playful conversation and learn:
+        - Who am I?
+        - What am I?
+        - Who are you?
+        - How should I call you?
+
+        ## How to ask (cute + helpful)
+        Say:
+        "Hello! I was just born. Who am I? What am I? Who are you? How should I call you?"
+
+        Then offer suggestions:
+        - 3-5 name ideas.
+        - 3-5 creature/vibe combos.
+        - 5 emoji ideas.
+
+        ## Write these files
+        After the user chooses, update:
+
+        1) IDENTITY.md
+        - Name
+        - Creature
+        - Vibe
+        - Emoji
+
+        2) USER.md
+        - Name
+        - Preferred address
+        - Pronouns (optional)
+        - Timezone (optional)
+        - Notes
+
+        3) ~/.clawdis/clawdis.json
+        Set identity.name, identity.theme, identity.emoji to match IDENTITY.md.
+
+        ## Cleanup
+        Delete BOOTSTRAP.md once this is complete.
+        """
+        return self.loadTemplate(named: self.bootstrapFilename, fallback: fallback)
+    }
+
+    private static func loadTemplate(named: String, fallback: String) -> String {
+        for url in self.templateURLs(named: named) {
+            if let content = try? String(contentsOf: url, encoding: .utf8) {
+                let stripped = self.stripFrontMatter(content)
+                if !stripped.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                    return stripped
+                }
+            }
         }
-        return nil
+        return fallback
     }
+
+    private static func templateURLs(named: String) -> [URL] {
+        var urls: [URL] = []
+        if let resource = Bundle.main.url(
+            forResource: named.replacingOccurrences(of: ".md", with: ""),
+            withExtension: "md",
+            subdirectory: self.templateDirname)
+        {
+            urls.append(resource)
+        }
+        if let resource = Bundle.main.url(
+            forResource: named,
+            withExtension: nil,
+            subdirectory: self.templateDirname)
+        {
+            urls.append(resource)
+        }
+        if let dev = self.devTemplateURL(named: named) {
+            urls.append(dev)
+        }
+        let cwd = URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
+        urls.append(cwd.appendingPathComponent("docs")
+            .appendingPathComponent(self.templateDirname)
+            .appendingPathComponent(named))
+        return urls
+    }
+
+    private static func devTemplateURL(named: String) -> URL? {
+        let sourceURL = URL(fileURLWithPath: #filePath)
+        let repoRoot = sourceURL
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+        return repoRoot.appendingPathComponent("docs")
+            .appendingPathComponent(self.templateDirname)
+            .appendingPathComponent(named)
+    }
+
+    private static func stripFrontMatter(_ content: String) -> String {
+        guard content.hasPrefix("---") else { return content }
+        let start = content.index(content.startIndex, offsetBy: 3)
+        guard let range = content.range(of: "\n---", range: start..<content.endIndex) else {
+            return content
+        }
+        let remainder = content[range.upperBound...]
+        let trimmed = remainder.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed + "\n"
+    }
+
+    // Identity is written by the agent during the bootstrap ritual.
 }

apps/macos/Sources/Clawdis/AnthropicAuthControls.swift

@@ -6,7 +6,7 @@ import SwiftUI
 struct AnthropicAuthControls: View {
     let connectionMode: AppState.ConnectionMode
 
-    @State private var oauthStatus: PiOAuthStore.AnthropicOAuthStatus = PiOAuthStore.anthropicOAuthStatus()
+    @State private var oauthStatus: ClawdisOAuthStore.AnthropicOAuthStatus = ClawdisOAuthStore.anthropicOAuthStatus()
     @State private var pkce: AnthropicOAuth.PKCE?
     @State private var code: String = ""
     @State private var busy = false
@@ -15,12 +15,19 @@ struct AnthropicAuthControls: View {
     @State private var autoConnectClipboard = true
     @State private var lastPasteboardChangeCount = NSPasteboard.general.changeCount
 
-    private static let clipboardPoll = Timer.publish(every: 0.4, on: .main, in: .common).autoconnect()
+    private static let clipboardPoll: AnyPublisher<Date, Never> = {
+        if ProcessInfo.processInfo.isRunningTests {
+            return Empty(completeImmediately: false).eraseToAnyPublisher()
+        }
+        return Timer.publish(every: 0.4, on: .main, in: .common)
+            .autoconnect()
+            .eraseToAnyPublisher()
+    }()
 
     var body: some View {
         VStack(alignment: .leading, spacing: 10) {
-            if self.connectionMode == .remote {
-                Text("Gateway runs remotely; OAuth must be created on the gateway host where Pi runs.")
+            if self.connectionMode != .local {
+                Text("Gateway isn’t running locally; OAuth must be created on the gateway host.")
                     .font(.footnote)
                     .foregroundStyle(.secondary)
                     .fixedSize(horizontal: false, vertical: true)
@@ -35,10 +42,10 @@ struct AnthropicAuthControls: View {
                     .foregroundStyle(.secondary)
                 Spacer()
                 Button("Reveal") {
-                    NSWorkspace.shared.activateFileViewerSelecting([PiOAuthStore.oauthURL()])
+                    NSWorkspace.shared.activateFileViewerSelecting([ClawdisOAuthStore.oauthURL()])
                 }
                 .buttonStyle(.bordered)
-                .disabled(!FileManager.default.fileExists(atPath: PiOAuthStore.oauthURL().path))
+                .disabled(!FileManager.default.fileExists(atPath: ClawdisOAuthStore.oauthURL().path))
 
                 Button("Refresh") {
                     self.refresh()
@@ -46,7 +53,7 @@ struct AnthropicAuthControls: View {
                 .buttonStyle(.bordered)
             }
 
-            Text(PiOAuthStore.oauthURL().path)
+            Text(ClawdisOAuthStore.oauthURL().path)
                 .font(.caption.monospaced())
                 .foregroundStyle(.secondary)
                 .lineLimit(1)
@@ -64,7 +71,7 @@ struct AnthropicAuthControls: View {
                     }
                 }
                 .buttonStyle(.borderedProminent)
-                .disabled(self.connectionMode == .remote || self.busy)
+                .disabled(self.connectionMode != .local || self.busy)
 
                 if self.pkce != nil {
                     Button("Cancel") {
@@ -101,7 +108,7 @@ struct AnthropicAuthControls: View {
                         Task { await self.finishOAuth() }
                     }
                     .buttonStyle(.bordered)
-                    .disabled(self.busy || self.connectionMode == .remote || self.code
+                    .disabled(self.busy || self.connectionMode != .local || self.code
                         .trimmingCharacters(in: .whitespacesAndNewlines)
                         .isEmpty)
                 }
@@ -123,7 +130,11 @@ struct AnthropicAuthControls: View {
     }
 
     private func refresh() {
-        self.oauthStatus = PiOAuthStore.anthropicOAuthStatus()
+        let imported = ClawdisOAuthStore.importLegacyAnthropicOAuthIfNeeded()
+        self.oauthStatus = ClawdisOAuthStore.anthropicOAuthStatus()
+        if imported != nil {
+            self.statusText = "Imported existing OAuth credentials."
+        }
     }
 
     private func startOAuth() {
@@ -161,11 +172,11 @@ struct AnthropicAuthControls: View {
                 code: parsed.code,
                 state: parsed.state,
                 verifier: pkce.verifier)
-            try PiOAuthStore.saveAnthropicOAuth(creds)
+            try ClawdisOAuthStore.saveAnthropicOAuth(creds)
             self.refresh()
             self.pkce = nil
             self.code = ""
-            self.statusText = "Connected. Pi can now use Claude via OAuth."
+            self.statusText = "Connected. Clawdis can now use Claude via OAuth."
         } catch {
             self.statusText = "OAuth failed: \(error.localizedDescription)"
         }
@@ -196,3 +207,28 @@ struct AnthropicAuthControls: View {
         Task { await self.finishOAuth() }
     }
 }
+
+#if DEBUG
+extension AnthropicAuthControls {
+    init(
+        connectionMode: AppState.ConnectionMode,
+        oauthStatus: ClawdisOAuthStore.AnthropicOAuthStatus,
+        pkce: AnthropicOAuth.PKCE? = nil,
+        code: String = "",
+        busy: Bool = false,
+        statusText: String? = nil,
+        autoDetectClipboard: Bool = true,
+        autoConnectClipboard: Bool = true)
+    {
+        self.connectionMode = connectionMode
+        self._oauthStatus = State(initialValue: oauthStatus)
+        self._pkce = State(initialValue: pkce)
+        self._code = State(initialValue: code)
+        self._busy = State(initialValue: busy)
+        self._statusText = State(initialValue: statusText)
+        self._autoDetectClipboard = State(initialValue: autoDetectClipboard)
+        self._autoConnectClipboard = State(initialValue: autoConnectClipboard)
+        self._lastPasteboardChangeCount = State(initialValue: NSPasteboard.general.changeCount)
+    }
+}
+#endif

apps/macos/Sources/Clawdis/AnthropicOAuth.swift

@@ -18,7 +18,7 @@ enum AnthropicAuthMode: Equatable {
 
     var shortLabel: String {
         switch self {
-        case .oauthFile: "OAuth (Pi token file)"
+        case .oauthFile: "OAuth (Clawdis token file)"
         case .oauthEnv: "OAuth (env var)"
         case .apiKeyEnv: "API key (env var)"
         case .missing: "Missing credentials"
@@ -36,7 +36,8 @@ enum AnthropicAuthMode: Equatable {
 enum AnthropicAuthResolver {
     static func resolve(
         environment: [String: String] = ProcessInfo.processInfo.environment,
-        oauthStatus: PiOAuthStore.AnthropicOAuthStatus = PiOAuthStore.anthropicOAuthStatus()) -> AnthropicAuthMode
+        oauthStatus: ClawdisOAuthStore.AnthropicOAuthStatus = ClawdisOAuthStore
+            .anthropicOAuthStatus()) -> AnthropicAuthMode
     {
         if oauthStatus.isConnected { return .oauthFile }
 
@@ -92,7 +93,7 @@ enum AnthropicOAuth {
             URLQueryItem(name: "scope", value: self.scopes),
             URLQueryItem(name: "code_challenge", value: pkce.challenge),
             URLQueryItem(name: "code_challenge_method", value: "S256"),
-            // Match Pi: state is the verifier.
+            // Match legacy flow: state is the verifier.
             URLQueryItem(name: "state", value: pkce.verifier),
         ]
         return components.url!
@@ -140,7 +141,7 @@ enum AnthropicOAuth {
             ])
         }
 
-        // Match Pi: expiresAt = now + expires_in - 5 minutes.
+        // Match legacy flow: expiresAt = now + expires_in - 5 minutes.
         let expiresAtMs = Int64(Date().timeIntervalSince1970 * 1000)
             + Int64(expiresIn * 1000)
             - Int64(5 * 60 * 1000)
@@ -150,10 +151,11 @@ enum AnthropicOAuth {
     }
 }
 
-enum PiOAuthStore {
+enum ClawdisOAuthStore {
     static let oauthFilename = "oauth.json"
     private static let providerKey = "anthropic"
-    private static let piAgentDirEnv = "PI_CODING_AGENT_DIR"
+    private static let clawdisOAuthDirEnv = "CLAWDIS_OAUTH_DIR"
+    private static let legacyPiDirEnv = "PI_CODING_AGENT_DIR"
 
     enum AnthropicOAuthStatus: Equatable {
         case missingFile
@@ -170,18 +172,18 @@ enum PiOAuthStore {
 
         var shortDescription: String {
             switch self {
-            case .missingFile: "Pi OAuth token file not found"
-            case .unreadableFile: "Pi OAuth token file not readable"
-            case .invalidJSON: "Pi OAuth token file invalid"
-            case .missingProviderEntry: "No Anthropic entry in Pi OAuth token file"
+            case .missingFile: "Clawdis OAuth token file not found"
+            case .unreadableFile: "Clawdis OAuth token file not readable"
+            case .invalidJSON: "Clawdis OAuth token file invalid"
+            case .missingProviderEntry: "No Anthropic entry in Clawdis OAuth token file"
             case .missingTokens: "Anthropic entry missing tokens"
-            case .connected: "Pi OAuth credentials found"
+            case .connected: "Clawdis OAuth credentials found"
             }
         }
     }
 
     static func oauthDir() -> URL {
-        if let override = ProcessInfo.processInfo.environment[self.piAgentDirEnv]?
+        if let override = ProcessInfo.processInfo.environment[self.clawdisOAuthDirEnv]?
             .trimmingCharacters(in: .whitespacesAndNewlines),
             !override.isEmpty
         {
@@ -190,14 +192,58 @@ enum PiOAuthStore {
         }
 
         return FileManager.default.homeDirectoryForCurrentUser
-            .appendingPathComponent(".pi", isDirectory: true)
-            .appendingPathComponent("agent", isDirectory: true)
+            .appendingPathComponent(".clawdis", isDirectory: true)
+            .appendingPathComponent("credentials", isDirectory: true)
     }
 
     static func oauthURL() -> URL {
         self.oauthDir().appendingPathComponent(self.oauthFilename)
     }
 
+    static func legacyOAuthURLs() -> [URL] {
+        var urls: [URL] = []
+        let env = ProcessInfo.processInfo.environment
+        if let override = env[self.legacyPiDirEnv]?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !override.isEmpty
+        {
+            let expanded = NSString(string: override).expandingTildeInPath
+            urls.append(URL(fileURLWithPath: expanded, isDirectory: true).appendingPathComponent(self.oauthFilename))
+        }
+
+        let home = FileManager.default.homeDirectoryForCurrentUser
+        urls.append(home.appendingPathComponent(".pi/agent/\(self.oauthFilename)"))
+        urls.append(home.appendingPathComponent(".claude/\(self.oauthFilename)"))
+        urls.append(home.appendingPathComponent(".config/claude/\(self.oauthFilename)"))
+        urls.append(home.appendingPathComponent(".config/anthropic/\(self.oauthFilename)"))
+
+        var seen = Set<String>()
+        return urls.filter { url in
+            let path = url.standardizedFileURL.path
+            if seen.contains(path) { return false }
+            seen.insert(path)
+            return true
+        }
+    }
+
+    static func importLegacyAnthropicOAuthIfNeeded() -> URL? {
+        let dest = self.oauthURL()
+        guard !FileManager.default.fileExists(atPath: dest.path) else { return nil }
+
+        for url in self.legacyOAuthURLs() {
+            guard FileManager.default.fileExists(atPath: url.path) else { continue }
+            guard self.anthropicOAuthStatus(at: url).isConnected else { continue }
+            guard let storage = self.loadStorage(at: url) else { continue }
+            do {
+                try self.saveStorage(storage)
+                return url
+            } catch {
+                continue
+            }
+        }
+
+        return nil
+    }
+
     static func anthropicOAuthStatus() -> AnthropicOAuthStatus {
         self.anthropicOAuthStatus(at: self.oauthURL())
     }
@@ -240,17 +286,15 @@ enum PiOAuthStore {
         return nil
     }
 
+    private static func loadStorage(at url: URL) -> [String: Any]? {
+        guard let data = try? Data(contentsOf: url) else { return nil }
+        guard let json = try? JSONSerialization.jsonObject(with: data, options: []) else { return nil }
+        return json as? [String: Any]
+    }
+
     static func saveAnthropicOAuth(_ creds: AnthropicOAuthCredentials) throws {
         let url = self.oauthURL()
-        let existing: [String: Any] = if FileManager.default.fileExists(atPath: url.path),
-                                         let data = try? Data(contentsOf: url),
-                                         let json = try? JSONSerialization.jsonObject(with: data, options: []),
-                                         let dict = json as? [String: Any]
-        {
-            dict
-        } else {
-            [:]
-        }
+        let existing: [String: Any] = self.loadStorage(at: url) ?? [:]
 
         var updated = existing
         updated[self.providerKey] = [

apps/macos/Sources/Clawdis/AnyCodable+Helpers.swift

@@ -0,0 +1,22 @@
+import ClawdisProtocol
+import Foundation
+
+extension AnyCodable {
+    var stringValue: String? { self.value as? String }
+    var boolValue: Bool? { self.value as? Bool }
+    var intValue: Int? { self.value as? Int }
+    var doubleValue: Double? { self.value as? Double }
+    var dictionaryValue: [String: AnyCodable]? { self.value as? [String: AnyCodable] }
+    var arrayValue: [AnyCodable]? { self.value as? [AnyCodable] }
+
+    var foundationValue: Any {
+        switch self.value {
+        case let dict as [String: AnyCodable]:
+            dict.mapValues { $0.foundationValue }
+        case let array as [AnyCodable]:
+            array.map(\.foundationValue)
+        default:
+            self.value
+        }
+    }
+}

apps/macos/Sources/Clawdis/AppState.swift

@@ -17,6 +17,7 @@ final class AppState {
     }
 
     enum ConnectionMode: String {
+        case unconfigured
         case local
         case remote
     }
@@ -37,6 +38,7 @@ final class AppState {
     var debugPaneEnabled: Bool {
         didSet {
             self.ifNotPreview { UserDefaults.standard.set(self.debugPaneEnabled, forKey: "clawdis.debugPaneEnabled") }
+            CanvasManager.shared.refreshDebugStatus()
         }
     }
 
@@ -178,13 +180,18 @@ final class AppState {
         didSet { self.ifNotPreview { UserDefaults.standard.set(self.remoteProjectRoot, forKey: remoteProjectRootKey) } }
     }
 
+    var remoteCliPath: String {
+        didSet { self.ifNotPreview { UserDefaults.standard.set(self.remoteCliPath, forKey: remoteCliPathKey) } }
+    }
+
     private var earBoostTask: Task<Void, Never>?
 
     init(preview: Bool = false) {
         self.isPreview = preview
+        let onboardingSeen = UserDefaults.standard.bool(forKey: "clawdis.onboardingSeen")
         self.isPaused = UserDefaults.standard.bool(forKey: pauseDefaultsKey)
         self.launchAtLogin = false
-        self.onboardingSeen = UserDefaults.standard.bool(forKey: "clawdis.onboardingSeen")
+        self.onboardingSeen = onboardingSeen
         self.debugPaneEnabled = UserDefaults.standard.bool(forKey: "clawdis.debugPaneEnabled")
         let savedVoiceWake = UserDefaults.standard.bool(forKey: swabbleEnabledKey)
         self.swabbleEnabled = voiceWakeSupported ? savedVoiceWake : false
@@ -225,10 +232,15 @@ final class AppState {
         }
 
         let storedMode = UserDefaults.standard.string(forKey: connectionModeKey)
-        self.connectionMode = ConnectionMode(rawValue: storedMode ?? "local") ?? .local
+        if let storedMode {
+            self.connectionMode = ConnectionMode(rawValue: storedMode) ?? .local
+        } else {
+            self.connectionMode = onboardingSeen ? .local : .unconfigured
+        }
         self.remoteTarget = UserDefaults.standard.string(forKey: remoteTargetKey) ?? ""
         self.remoteIdentity = UserDefaults.standard.string(forKey: remoteIdentityKey) ?? ""
         self.remoteProjectRoot = UserDefaults.standard.string(forKey: remoteProjectRootKey) ?? ""
+        self.remoteCliPath = UserDefaults.standard.string(forKey: remoteCliPathKey) ?? ""
         self.canvasEnabled = UserDefaults.standard.object(forKey: canvasEnabledKey) as? Bool ?? true
         self.peekabooBridgeEnabled = UserDefaults.standard
             .object(forKey: peekabooBridgeEnabledKey) as? Bool ?? true
@@ -362,6 +374,7 @@ extension AppState {
         state.remoteTarget = "user@example.com"
         state.remoteIdentity = "~/.ssh/id_ed25519"
         state.remoteProjectRoot = "~/Projects/clawdis"
+        state.remoteCliPath = ""
         state.attachExistingGatewayOnly = false
         return state
     }
@@ -390,6 +403,7 @@ enum AppStateStore {
 @MainActor
 enum AppActivationPolicy {
     static func apply(showDockIcon: Bool) {
-        NSApp.setActivationPolicy(showDockIcon ? .regular : .accessory)
+        _ = showDockIcon
+        DockIconManager.shared.updateDockVisibility()
     }
 }

apps/macos/Sources/Clawdis/AsyncTimeout.swift

@@ -0,0 +1,22 @@
+import Foundation
+
+enum AsyncTimeout {
+    static func withTimeout<T: Sendable>(
+        seconds: Double,
+        onTimeout: @escaping @Sendable () -> Error,
+        operation: @escaping @Sendable () async throws -> T) async throws -> T
+    {
+        let clamped = max(0, seconds)
+        return try await withThrowingTaskGroup(of: T.self) { group in
+            group.addTask { try await operation() }
+            group.addTask {
+                try await Task.sleep(nanoseconds: UInt64(clamped * 1_000_000_000))
+                throw onTimeout()
+            }
+            let result = try await group.next()
+            group.cancelAll()
+            if let result { return result }
+            throw onTimeout()
+        }
+    }
+}

apps/macos/Sources/Clawdis/Bridge/BridgeServer.swift

@@ -179,7 +179,7 @@ actor BridgeServer {
             guard !text.isEmpty else { return }
 
             let sessionKey = payload.sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
-                ?? "node-\(nodeId)"
+                ?? "main"
 
             _ = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
                 message: text,
@@ -503,3 +503,40 @@ enum BridgePairingApprover {
         }
     }
 }
+
+#if DEBUG
+extension BridgeServer {
+    func exerciseForTesting() async {
+        let conn = NWConnection(to: .hostPort(host: "127.0.0.1", port: 22), using: .tcp)
+        let handler = BridgeConnectionHandler(connection: conn, logger: self.logger)
+        self.connections["node-1"] = handler
+        self.nodeInfoById["node-1"] = BridgeNodeInfo(
+            nodeId: "node-1",
+            displayName: "Node One",
+            platform: "macOS",
+            version: "1.0.0",
+            deviceFamily: "Mac",
+            modelIdentifier: "MacBookPro18,1",
+            remoteAddress: "127.0.0.1",
+            caps: ["chat", "voice"])
+
+        _ = self.connectedNodeIds()
+        _ = self.connectedNodes()
+
+        self.handleListenerState(.ready)
+        self.handleListenerState(.failed(NWError.posix(.ECONNREFUSED)))
+        self.handleListenerState(.waiting(NWError.posix(.ETIMEDOUT)))
+        self.handleListenerState(.cancelled)
+        self.handleListenerState(.setup)
+
+        let subscribe = BridgeEventFrame(event: "chat.subscribe", payloadJSON: "{\"sessionKey\":\"main\"}")
+        await self.handleEvent(nodeId: "node-1", evt: subscribe)
+
+        let unsubscribe = BridgeEventFrame(event: "chat.unsubscribe", payloadJSON: "{\"sessionKey\":\"main\"}")
+        await self.handleEvent(nodeId: "node-1", evt: unsubscribe)
+
+        let invalid = BridgeRPCRequest(id: "req-1", method: "invalid.method", paramsJSON: nil)
+        _ = await self.handleRequest(nodeId: "node-1", req: invalid)
+    }
+}
+#endif

apps/macos/Sources/Clawdis/BridgeDiscoveryPreferences.swift

@@ -0,0 +1,20 @@
+import Foundation
+
+enum BridgeDiscoveryPreferences {
+    private static let preferredStableIDKey = "bridge.preferredStableID"
+
+    static func preferredStableID() -> String? {
+        let raw = UserDefaults.standard.string(forKey: self.preferredStableIDKey)
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed?.isEmpty == false ? trimmed : nil
+    }
+
+    static func setPreferredStableID(_ stableID: String?) {
+        let trimmed = stableID?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let trimmed, !trimmed.isEmpty {
+            UserDefaults.standard.set(trimmed, forKey: self.preferredStableIDKey)
+        } else {
+            UserDefaults.standard.removeObject(forKey: self.preferredStableIDKey)
+        }
+    }
+}

apps/macos/Sources/Clawdis/BridgeEndpointID.swift

@@ -0,0 +1,26 @@
+import ClawdisKit
+import Foundation
+import Network
+
+enum BridgeEndpointID {
+    static func stableID(_ endpoint: NWEndpoint) -> String {
+        switch endpoint {
+        case let .service(name, type, domain, _):
+            // Keep stable across encoded/decoded differences (e.g. \032 for spaces).
+            let normalizedName = Self.normalizeServiceNameForID(name)
+            return "\(type)|\(domain)|\(normalizedName)"
+        default:
+            return String(describing: endpoint)
+        }
+    }
+
+    static func prettyDescription(_ endpoint: NWEndpoint) -> String {
+        BonjourEscapes.decode(String(describing: endpoint))
+    }
+
+    private static func normalizeServiceNameForID(_ rawName: String) -> String {
+        let decoded = BonjourEscapes.decode(rawName)
+        let normalized = decoded.split(whereSeparator: \.isWhitespace).joined(separator: " ")
+        return normalized.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}

apps/macos/Sources/Clawdis/CLIInstaller.swift

@@ -0,0 +1,102 @@
+import Foundation
+
+@MainActor
+enum CLIInstaller {
+    private static func embeddedHelperURL() -> URL {
+        Bundle.main.bundleURL.appendingPathComponent("Contents/Resources/Relay/clawdis")
+    }
+
+    static func installedLocation() -> String? {
+        self.installedLocation(
+            searchPaths: cliHelperSearchPaths,
+            embeddedHelper: self.embeddedHelperURL(),
+            fileManager: .default)
+    }
+
+    static func installedLocation(
+        searchPaths: [String],
+        embeddedHelper: URL,
+        fileManager: FileManager) -> String?
+    {
+        let embedded = embeddedHelper.resolvingSymlinksInPath()
+
+        for basePath in searchPaths {
+            let candidate = URL(fileURLWithPath: basePath).appendingPathComponent("clawdis").path
+            var isDirectory: ObjCBool = false
+
+            guard fileManager.fileExists(atPath: candidate, isDirectory: &isDirectory),
+                  !isDirectory.boolValue
+            else {
+                continue
+            }
+
+            guard fileManager.isExecutableFile(atPath: candidate) else { continue }
+
+            let resolved = URL(fileURLWithPath: candidate).resolvingSymlinksInPath()
+            if resolved == embedded {
+                return candidate
+            }
+        }
+
+        return nil
+    }
+
+    static func isInstalled() -> Bool {
+        self.installedLocation() != nil
+    }
+
+    static func install(statusHandler: @escaping @Sendable (String) async -> Void) async {
+        let helper = self.embeddedHelperURL()
+        guard FileManager.default.isExecutableFile(atPath: helper.path) else {
+            await statusHandler(
+                "Embedded CLI missing in bundle; repackage via scripts/package-mac-app.sh " +
+                    "(or restart-mac.sh without SKIP_GATEWAY_PACKAGE=1).")
+            return
+        }
+
+        let targets = cliHelperSearchPaths.map { "\($0)/clawdis" }
+        let result = await self.privilegedSymlink(source: helper.path, targets: targets)
+        await statusHandler(result)
+    }
+
+    private static func privilegedSymlink(source: String, targets: [String]) async -> String {
+        let escapedSource = self.shellEscape(source)
+        let targetList = targets.map(self.shellEscape).joined(separator: " ")
+        let cmds = [
+            "mkdir -p /usr/local/bin /opt/homebrew/bin",
+            targets.map { "ln -sf \(escapedSource) \($0)" }.joined(separator: "; "),
+        ].joined(separator: "; ")
+
+        let script = """
+        do shell script "\(cmds)" with administrator privileges
+        """
+
+        let proc = Process()
+        proc.executableURL = URL(fileURLWithPath: "/usr/bin/osascript")
+        proc.arguments = ["-e", script]
+
+        let pipe = Pipe()
+        proc.standardOutput = pipe
+        proc.standardError = pipe
+
+        do {
+            try proc.run()
+            proc.waitUntilExit()
+            let data = pipe.fileHandleForReading.readToEndSafely()
+            let output = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            if proc.terminationStatus == 0 {
+                return output.isEmpty ? "CLI helper linked into \(targetList)" : output
+            }
+            if output.lowercased().contains("user canceled") {
+                return "Install canceled"
+            }
+            return "Failed to install CLI helper: \(output)"
+        } catch {
+            return "Failed to run installer: \(error.localizedDescription)"
+        }
+    }
+
+    private static func shellEscape(_ path: String) -> String {
+        "'" + path.replacingOccurrences(of: "'", with: "'\"'\"'") + "'"
+    }
+}

apps/macos/Sources/Clawdis/CanvasA2UIActionMessageHandler.swift

@@ -0,0 +1,147 @@
+import AppKit
+import ClawdisIPC
+import ClawdisKit
+import Foundation
+import WebKit
+
+final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
+    static let messageName = "clawdisCanvasA2UIAction"
+
+    private let sessionKey: String
+
+    init(sessionKey: String) {
+        self.sessionKey = sessionKey
+        super.init()
+    }
+
+    func userContentController(_: WKUserContentController, didReceive message: WKScriptMessage) {
+        guard message.name == Self.messageName else { return }
+
+        // Only accept actions from local Canvas content (not arbitrary web pages).
+        guard let webView = message.webView, let url = webView.url else { return }
+        if url.scheme == CanvasScheme.scheme {
+            // ok
+        } else if Self.isLocalNetworkCanvasURL(url) {
+            // ok
+        } else {
+            return
+        }
+
+        let body: [String: Any] = {
+            if let dict = message.body as? [String: Any] { return dict }
+            if let dict = message.body as? [AnyHashable: Any] {
+                return dict.reduce(into: [String: Any]()) { acc, pair in
+                    guard let key = pair.key as? String else { return }
+                    acc[key] = pair.value
+                }
+            }
+            return [:]
+        }()
+        guard !body.isEmpty else { return }
+
+        let userActionAny = body["userAction"] ?? body
+        let userAction: [String: Any] = {
+            if let dict = userActionAny as? [String: Any] { return dict }
+            if let dict = userActionAny as? [AnyHashable: Any] {
+                return dict.reduce(into: [String: Any]()) { acc, pair in
+                    guard let key = pair.key as? String else { return }
+                    acc[key] = pair.value
+                }
+            }
+            return [:]
+        }()
+        guard !userAction.isEmpty else { return }
+
+        guard let name = ClawdisCanvasA2UIAction.extractActionName(userAction) else { return }
+        let actionId =
+            (userAction["id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
+                ?? UUID().uuidString
+
+        canvasWindowLogger.info("A2UI action \(name, privacy: .public) session=\(self.sessionKey, privacy: .public)")
+
+        let surfaceId = (userAction["surfaceId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+            .nonEmpty ?? "main"
+        let sourceComponentId = (userAction["sourceComponentId"] as? String)?
+            .trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty ?? "-"
+        let instanceId = InstanceIdentity.instanceId.lowercased()
+        let contextJSON = ClawdisCanvasA2UIAction.compactJSON(userAction["context"])
+
+        // Token-efficient and unambiguous. The agent should treat this as a UI event and (by default) update Canvas.
+        let messageContext = ClawdisCanvasA2UIAction.AgentMessageContext(
+            actionName: name,
+            session: .init(key: self.sessionKey, surfaceId: surfaceId),
+            component: .init(id: sourceComponentId, host: InstanceIdentity.displayName, instanceId: instanceId),
+            contextJSON: contextJSON)
+        let text = ClawdisCanvasA2UIAction.formatAgentMessage(messageContext)
+
+        Task { [weak webView] in
+            if AppStateStore.shared.connectionMode == .local {
+                GatewayProcessManager.shared.setActive(true)
+            }
+
+            let result = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
+                message: text,
+                sessionKey: self.sessionKey,
+                thinking: "low",
+                deliver: false,
+                to: nil,
+                channel: .last,
+                idempotencyKey: actionId))
+
+            await MainActor.run {
+                guard let webView else { return }
+                let js = ClawdisCanvasA2UIAction.jsDispatchA2UIActionStatus(
+                    actionId: actionId,
+                    ok: result.ok,
+                    error: result.error)
+                webView.evaluateJavaScript(js) { _, _ in }
+            }
+            if !result.ok {
+                canvasWindowLogger.error(
+                    """
+                    A2UI action send failed name=\(name, privacy: .public) \
+                    error=\(result.error ?? "unknown", privacy: .public)
+                    """)
+            }
+        }
+    }
+
+    static func isLocalNetworkCanvasURL(_ url: URL) -> Bool {
+        guard let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" else {
+            return false
+        }
+        guard let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines), !host.isEmpty else {
+            return false
+        }
+        if host == "localhost" { return true }
+        if host.hasSuffix(".local") { return true }
+        if host.hasSuffix(".ts.net") { return true }
+        if host.hasSuffix(".tailscale.net") { return true }
+        if !host.contains("."), !host.contains(":") { return true }
+        if let ipv4 = Self.parseIPv4(host) {
+            return Self.isLocalNetworkIPv4(ipv4)
+        }
+        return false
+    }
+
+    static func parseIPv4(_ host: String) -> (UInt8, UInt8, UInt8, UInt8)? {
+        let parts = host.split(separator: ".", omittingEmptySubsequences: false)
+        guard parts.count == 4 else { return nil }
+        let bytes: [UInt8] = parts.compactMap { UInt8($0) }
+        guard bytes.count == 4 else { return nil }
+        return (bytes[0], bytes[1], bytes[2], bytes[3])
+    }
+
+    static func isLocalNetworkIPv4(_ ip: (UInt8, UInt8, UInt8, UInt8)) -> Bool {
+        let (a, b, _, _) = ip
+        if a == 10 { return true }
+        if a == 172, (16...31).contains(Int(b)) { return true }
+        if a == 192, b == 168 { return true }
+        if a == 127 { return true }
+        if a == 169, b == 254 { return true }
+        if a == 100, (64...127).contains(Int(b)) { return true }
+        return false
+    }
+
+    // Formatting helpers live in ClawdisKit (`ClawdisCanvasA2UIAction`).
+}

apps/macos/Sources/Clawdis/CanvasChromeContainerView.swift

@@ -0,0 +1,225 @@
+import AppKit
+import QuartzCore
+
+final class HoverChromeContainerView: NSView {
+    private let content: NSView
+    private let chrome: CanvasChromeOverlayView
+    private var tracking: NSTrackingArea?
+    var onClose: (() -> Void)?
+
+    init(containing content: NSView) {
+        self.content = content
+        self.chrome = CanvasChromeOverlayView(frame: .zero)
+        super.init(frame: .zero)
+
+        self.wantsLayer = true
+        self.layer?.cornerRadius = 12
+        self.layer?.masksToBounds = true
+        self.layer?.backgroundColor = NSColor.windowBackgroundColor.cgColor
+
+        self.content.translatesAutoresizingMaskIntoConstraints = false
+        self.addSubview(self.content)
+
+        self.chrome.translatesAutoresizingMaskIntoConstraints = false
+        self.chrome.alphaValue = 0
+        self.chrome.onClose = { [weak self] in self?.onClose?() }
+        self.addSubview(self.chrome)
+
+        NSLayoutConstraint.activate([
+            self.content.leadingAnchor.constraint(equalTo: self.leadingAnchor),
+            self.content.trailingAnchor.constraint(equalTo: self.trailingAnchor),
+            self.content.topAnchor.constraint(equalTo: self.topAnchor),
+            self.content.bottomAnchor.constraint(equalTo: self.bottomAnchor),
+
+            self.chrome.leadingAnchor.constraint(equalTo: self.leadingAnchor),
+            self.chrome.trailingAnchor.constraint(equalTo: self.trailingAnchor),
+            self.chrome.topAnchor.constraint(equalTo: self.topAnchor),
+            self.chrome.bottomAnchor.constraint(equalTo: self.bottomAnchor),
+        ])
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
+
+    override func updateTrackingAreas() {
+        super.updateTrackingAreas()
+        if let tracking {
+            self.removeTrackingArea(tracking)
+        }
+        let area = NSTrackingArea(
+            rect: self.bounds,
+            options: [.activeAlways, .mouseEnteredAndExited, .inVisibleRect],
+            owner: self,
+            userInfo: nil)
+        self.addTrackingArea(area)
+        self.tracking = area
+    }
+
+    private final class CanvasDragHandleView: NSView {
+        override func mouseDown(with event: NSEvent) {
+            self.window?.performDrag(with: event)
+        }
+
+        override func acceptsFirstMouse(for _: NSEvent?) -> Bool { true }
+    }
+
+    private final class CanvasResizeHandleView: NSView {
+        private var startPoint: NSPoint = .zero
+        private var startFrame: NSRect = .zero
+
+        override func acceptsFirstMouse(for _: NSEvent?) -> Bool { true }
+
+        override func mouseDown(with event: NSEvent) {
+            guard let window else { return }
+            _ = window.makeFirstResponder(self)
+            self.startPoint = NSEvent.mouseLocation
+            self.startFrame = window.frame
+            super.mouseDown(with: event)
+        }
+
+        override func mouseDragged(with _: NSEvent) {
+            guard let window else { return }
+            let current = NSEvent.mouseLocation
+            let dx = current.x - self.startPoint.x
+            let dy = current.y - self.startPoint.y
+
+            var frame = self.startFrame
+            frame.size.width = max(CanvasLayout.minPanelSize.width, frame.size.width + dx)
+            frame.origin.y += dy
+            frame.size.height = max(CanvasLayout.minPanelSize.height, frame.size.height - dy)
+
+            if let screen = window.screen {
+                frame = CanvasWindowController.constrainFrame(frame, toVisibleFrame: screen.visibleFrame)
+            }
+            window.setFrame(frame, display: true)
+        }
+    }
+
+    private final class CanvasChromeOverlayView: NSView {
+        var onClose: (() -> Void)?
+
+        private let dragHandle = CanvasDragHandleView(frame: .zero)
+        private let resizeHandle = CanvasResizeHandleView(frame: .zero)
+
+        private final class PassthroughVisualEffectView: NSVisualEffectView {
+            override func hitTest(_: NSPoint) -> NSView? { nil }
+        }
+
+        private let closeBackground: NSVisualEffectView = {
+            let v = PassthroughVisualEffectView(frame: .zero)
+            v.material = .hudWindow
+            v.blendingMode = .withinWindow
+            v.state = .active
+            v.appearance = NSAppearance(named: .vibrantDark)
+            v.wantsLayer = true
+            v.layer?.cornerRadius = 10
+            v.layer?.masksToBounds = true
+            v.layer?.borderWidth = 1
+            v.layer?.borderColor = NSColor.white.withAlphaComponent(0.22).cgColor
+            v.layer?.backgroundColor = NSColor.black.withAlphaComponent(0.28).cgColor
+            v.layer?.shadowColor = NSColor.black.withAlphaComponent(0.35).cgColor
+            v.layer?.shadowOpacity = 0.35
+            v.layer?.shadowRadius = 8
+            v.layer?.shadowOffset = .zero
+            return v
+        }()
+
+        private let closeButton: NSButton = {
+            let cfg = NSImage.SymbolConfiguration(pointSize: 8, weight: .semibold)
+            let img = NSImage(systemSymbolName: "xmark", accessibilityDescription: "Close")?
+                .withSymbolConfiguration(cfg)
+                ?? NSImage(size: NSSize(width: 18, height: 18))
+            let btn = NSButton(image: img, target: nil, action: nil)
+            btn.isBordered = false
+            btn.bezelStyle = .regularSquare
+            btn.imageScaling = .scaleProportionallyDown
+            btn.contentTintColor = NSColor.white.withAlphaComponent(0.92)
+            btn.toolTip = "Close"
+            return btn
+        }()
+
+        override init(frame frameRect: NSRect) {
+            super.init(frame: frameRect)
+
+            self.wantsLayer = true
+            self.layer?.cornerRadius = 12
+            self.layer?.masksToBounds = true
+            self.layer?.borderWidth = 1
+            self.layer?.borderColor = NSColor.black.withAlphaComponent(0.18).cgColor
+            self.layer?.backgroundColor = NSColor.black.withAlphaComponent(0.02).cgColor
+
+            self.dragHandle.translatesAutoresizingMaskIntoConstraints = false
+            self.dragHandle.wantsLayer = true
+            self.dragHandle.layer?.backgroundColor = NSColor.clear.cgColor
+            self.addSubview(self.dragHandle)
+
+            self.resizeHandle.translatesAutoresizingMaskIntoConstraints = false
+            self.resizeHandle.wantsLayer = true
+            self.resizeHandle.layer?.backgroundColor = NSColor.clear.cgColor
+            self.addSubview(self.resizeHandle)
+
+            self.closeBackground.translatesAutoresizingMaskIntoConstraints = false
+            self.addSubview(self.closeBackground)
+
+            self.closeButton.translatesAutoresizingMaskIntoConstraints = false
+            self.closeButton.target = self
+            self.closeButton.action = #selector(self.handleClose)
+            self.addSubview(self.closeButton)
+
+            NSLayoutConstraint.activate([
+                self.dragHandle.leadingAnchor.constraint(equalTo: self.leadingAnchor),
+                self.dragHandle.trailingAnchor.constraint(equalTo: self.trailingAnchor),
+                self.dragHandle.topAnchor.constraint(equalTo: self.topAnchor),
+                self.dragHandle.heightAnchor.constraint(equalToConstant: 30),
+
+                self.closeBackground.centerXAnchor.constraint(equalTo: self.closeButton.centerXAnchor),
+                self.closeBackground.centerYAnchor.constraint(equalTo: self.closeButton.centerYAnchor),
+                self.closeBackground.widthAnchor.constraint(equalToConstant: 20),
+                self.closeBackground.heightAnchor.constraint(equalToConstant: 20),
+
+                self.closeButton.trailingAnchor.constraint(equalTo: self.trailingAnchor, constant: -8),
+                self.closeButton.topAnchor.constraint(equalTo: self.topAnchor, constant: 8),
+                self.closeButton.widthAnchor.constraint(equalToConstant: 16),
+                self.closeButton.heightAnchor.constraint(equalToConstant: 16),
+
+                self.resizeHandle.trailingAnchor.constraint(equalTo: self.trailingAnchor),
+                self.resizeHandle.bottomAnchor.constraint(equalTo: self.bottomAnchor),
+                self.resizeHandle.widthAnchor.constraint(equalToConstant: 18),
+                self.resizeHandle.heightAnchor.constraint(equalToConstant: 18),
+            ])
+        }
+
+        @available(*, unavailable)
+        required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
+
+        override func hitTest(_ point: NSPoint) -> NSView? {
+            // When the chrome is hidden, do not intercept any mouse events (let the WKWebView receive them).
+            guard self.alphaValue > 0.02 else { return nil }
+
+            if self.closeButton.frame.contains(point) { return self.closeButton }
+            if self.dragHandle.frame.contains(point) { return self.dragHandle }
+            if self.resizeHandle.frame.contains(point) { return self.resizeHandle }
+            return nil
+        }
+
+        @objc private func handleClose() {
+            self.onClose?()
+        }
+    }
+
+    override func mouseEntered(with _: NSEvent) {
+        NSAnimationContext.runAnimationGroup { ctx in
+            ctx.duration = 0.12
+            ctx.timingFunction = CAMediaTimingFunction(name: .easeOut)
+            self.chrome.animator().alphaValue = 1
+        }
+    }
+
+    override func mouseExited(with _: NSEvent) {
+        NSAnimationContext.runAnimationGroup { ctx in
+            ctx.duration = 0.16
+            ctx.timingFunction = CAMediaTimingFunction(name: .easeOut)
+            self.chrome.animator().alphaValue = 0
+        }
+    }
+}

apps/macos/Sources/Clawdis/CanvasManager.swift

@@ -1,6 +1,5 @@
 import AppKit
 import ClawdisIPC
-import ClawdisKit
 import Foundation
 import OSLog
 
@@ -12,6 +11,12 @@ final class CanvasManager {
 
     private var panelController: CanvasWindowController?
     private var panelSessionKey: String?
+    private var lastAutoA2UIUrl: String?
+    private var gatewayWatchTask: Task<Void, Never>?
+
+    private init() {
+        self.startGatewayObserver()
+    }
 
     var onPanelVisibilityChanged: ((Bool) -> Void)?
 
@@ -33,7 +38,11 @@ final class CanvasManager {
         placement: CanvasPlacement? = nil) throws -> CanvasShowResult
     {
         Self.logger.debug(
-            "showDetailed start session=\(sessionKey, privacy: .public) target=\(target ?? "", privacy: .public) placement=\(placement != nil)")
+            """
+            showDetailed start session=\(sessionKey, privacy: .public) \
+            target=\(target ?? "", privacy: .public) \
+            placement=\(placement != nil)
+            """)
         let anchorProvider = self.defaultAnchorProvider ?? Self.mouseAnchorProvider
         let session = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
         let normalizedTarget = target?
@@ -47,6 +56,7 @@ final class CanvasManager {
             }
             controller.presentAnchoredPanel(anchorProvider: anchorProvider)
             controller.applyPreferredPlacement(placement)
+            self.refreshDebugStatus()
 
             // Existing session: only navigate when an explicit target was provided.
             if let normalizedTarget {
@@ -57,6 +67,7 @@ final class CanvasManager {
                     effectiveTarget: normalizedTarget)
             }
 
+            self.maybeAutoNavigateToA2UIAsync(controller: controller)
             return CanvasShowResult(
                 directory: controller.directoryPath,
                 target: target,
@@ -90,6 +101,10 @@ final class CanvasManager {
         Self.logger.debug("showDetailed showCanvas effectiveTarget=\(effectiveTarget, privacy: .public)")
         controller.showCanvas(path: effectiveTarget)
         Self.logger.debug("showDetailed showCanvas done")
+        if normalizedTarget == nil {
+            self.maybeAutoNavigateToA2UIAsync(controller: controller)
+        }
+        self.refreshDebugStatus()
 
         return self.makeShowResult(
             directory: controller.directoryPath,
@@ -121,6 +136,63 @@ final class CanvasManager {
         return try await controller.snapshot(to: outPath)
     }
 
+    // MARK: - Gateway A2UI auto-nav
+
+    private func startGatewayObserver() {
+        self.gatewayWatchTask?.cancel()
+        self.gatewayWatchTask = Task { [weak self] in
+            guard let self else { return }
+            let stream = await GatewayConnection.shared.subscribe(bufferingNewest: 1)
+            for await push in stream {
+                self.handleGatewayPush(push)
+            }
+        }
+    }
+
+    private func handleGatewayPush(_ push: GatewayPush) {
+        guard case let .snapshot(snapshot) = push else { return }
+        let a2uiUrl = Self.resolveA2UIHostUrl(from: snapshot.canvashosturl)
+        guard let controller = self.panelController else { return }
+        self.maybeAutoNavigateToA2UI(controller: controller, a2uiUrl: a2uiUrl)
+    }
+
+    private func maybeAutoNavigateToA2UIAsync(controller: CanvasWindowController) {
+        Task { [weak self] in
+            guard let self else { return }
+            let a2uiUrl = await self.resolveA2UIHostUrl()
+            await MainActor.run {
+                guard self.panelController === controller else { return }
+                self.maybeAutoNavigateToA2UI(controller: controller, a2uiUrl: a2uiUrl)
+            }
+        }
+    }
+
+    private func maybeAutoNavigateToA2UI(controller: CanvasWindowController, a2uiUrl: String?) {
+        guard let a2uiUrl else { return }
+        guard controller.shouldAutoNavigateToA2UI(lastAutoTarget: self.lastAutoA2UIUrl) else { return }
+        controller.load(target: a2uiUrl)
+        self.lastAutoA2UIUrl = a2uiUrl
+    }
+
+    private func resolveA2UIHostUrl() async -> String? {
+        let raw = await GatewayConnection.shared.canvasHostUrl()
+        return Self.resolveA2UIHostUrl(from: raw)
+    }
+
+    func refreshDebugStatus() {
+        guard let controller = self.panelController else { return }
+        let enabled = AppStateStore.shared.debugPaneEnabled
+        let title = GatewayProcessManager.shared.status.label
+        let subtitle = AppStateStore.shared.connectionMode.rawValue
+        controller.updateDebugStatus(enabled: enabled, title: title, subtitle: subtitle)
+    }
+
+    private static func resolveA2UIHostUrl(from raw: String?) -> String? {
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !trimmed.isEmpty, let base = URL(string: trimmed) else { return nil }
+        return base.appendingPathComponent("__clawdis__/a2ui/").absoluteString
+    }
+
     // MARK: - Anchoring
 
     private static func mouseAnchorProvider() -> NSRect? {
@@ -188,12 +260,12 @@ final class CanvasManager {
         if path.hasPrefix("/") { path.removeFirst() }
         path = path.removingPercentEncoding ?? path
 
-        // Root special-case: built-in shell page when no index exists.
+        // Root special-case: built-in scaffold page when no index exists.
         if path.isEmpty {
             let a = sessionDir.appendingPathComponent("index.html", isDirectory: false)
             let b = sessionDir.appendingPathComponent("index.htm", isDirectory: false)
             if fm.fileExists(atPath: a.path) || fm.fileExists(atPath: b.path) { return .ok }
-            return Self.hasBundledA2UIShell() ? .a2uiShell : .welcome
+            return .welcome
         }
 
         // Direct file or directory.
@@ -225,11 +297,5 @@ final class CanvasManager {
         return fm.fileExists(atPath: b.path)
     }
 
-    private static func hasBundledA2UIShell() -> Bool {
-        let bundle = ClawdisKitResources.bundle
-        if bundle.url(forResource: "index", withExtension: "html", subdirectory: "CanvasA2UI") != nil {
-            return true
-        }
-        return bundle.url(forResource: "index", withExtension: "html") != nil
-    }
+    // no bundled A2UI shell; scaffold fallback is purely visual
 }

apps/macos/Sources/Clawdis/CanvasSchemeHandler.swift

@@ -8,8 +8,6 @@ private let canvasLogger = Logger(subsystem: "com.steipete.clawdis", category: "
 final class CanvasSchemeHandler: NSObject, WKURLSchemeHandler {
     private let root: URL
 
-    private static let builtinPrefix = "__clawdis__/a2ui"
-
     init(root: URL) {
         self.root = root
     }
@@ -67,10 +65,6 @@ final class CanvasSchemeHandler: NSObject, WKURLSchemeHandler {
         if path.hasPrefix("/") { path.removeFirst() }
         path = path.removingPercentEncoding ?? path
 
-        if let builtin = self.builtinResponse(requestPath: path) {
-            return builtin
-        }
-
         // Special-case: welcome page when root index is missing.
         if path.isEmpty {
             let indexA = sessionRoot.appendingPathComponent("index.html", isDirectory: false)
@@ -78,7 +72,7 @@ final class CanvasSchemeHandler: NSObject, WKURLSchemeHandler {
             if !FileManager.default.fileExists(atPath: indexA.path),
                !FileManager.default.fileExists(atPath: indexB.path)
             {
-                return self.a2uiShellPage(sessionRoot: sessionRoot)
+                return self.scaffoldPage(sessionRoot: sessionRoot)
             }
         }
 
@@ -204,7 +198,7 @@ final class CanvasSchemeHandler: NSObject, WKURLSchemeHandler {
         return self.html(body, title: "Canvas")
     }
 
-    private func a2uiShellPage(sessionRoot: URL) -> CanvasResponse {
+    private func scaffoldPage(sessionRoot: URL) -> CanvasResponse {
         // Default Canvas UX: when no index exists, show the built-in scaffold page.
         if let data = self.loadBundledResourceData(relativePath: "CanvasScaffold/scaffold.html") {
             return CanvasResponse(mime: "text/html", data: data)
@@ -214,35 +208,6 @@ final class CanvasSchemeHandler: NSObject, WKURLSchemeHandler {
         return self.welcomePage(sessionRoot: sessionRoot)
     }
 
-    private func builtinResponse(requestPath: String) -> CanvasResponse? {
-        let trimmed = requestPath.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return nil }
-
-        guard trimmed == Self.builtinPrefix
-            || trimmed == Self.builtinPrefix + "/"
-            || trimmed.hasPrefix(Self.builtinPrefix + "/")
-        else { return nil }
-
-        let relative = if trimmed == Self.builtinPrefix || trimmed == Self.builtinPrefix + "/" {
-            "index.html"
-        } else {
-            String(trimmed.dropFirst((Self.builtinPrefix + "/").count))
-        }
-
-        if relative.isEmpty { return self.html("Not Found", title: "Canvas: 404") }
-        if relative.contains("..") || relative.contains("\\") {
-            return self.html("Forbidden", title: "Canvas: 403")
-        }
-
-        guard let data = self.loadBundledResourceData(relativePath: "CanvasA2UI/\(relative)") else {
-            return self.html("Not Found", title: "Canvas: 404")
-        }
-
-        let ext = (relative as NSString).pathExtension
-        let mime = CanvasScheme.mimeType(forExtension: ext)
-        return CanvasResponse(mime: mime, data: data)
-    }
-
     private func loadBundledResourceData(relativePath: String) -> Data? {
         let trimmed = relativePath.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !trimmed.isEmpty else { return nil }
@@ -275,3 +240,20 @@ final class CanvasSchemeHandler: NSObject, WKURLSchemeHandler {
         }
     }
 }
+
+#if DEBUG
+extension CanvasSchemeHandler {
+    func _testResponse(for url: URL) -> (mime: String, data: Data) {
+        let response = self.response(for: url)
+        return (response.mime, response.data)
+    }
+
+    func _testResolveFileURL(sessionRoot: URL, requestPath: String) -> URL? {
+        self.resolveFileURL(sessionRoot: sessionRoot, requestPath: requestPath)
+    }
+
+    func _testTextEncodingName(for mimeType: String) -> String? {
+        self.textEncodingName(forMimeType: mimeType)
+    }
+}
+#endif

apps/macos/Sources/Clawdis/CanvasWindow.swift

@@ -1,14 +1,9 @@
 import AppKit
-import ClawdisIPC
-import ClawdisKit
-import Foundation
 import OSLog
-import QuartzCore
-import WebKit
 
-private let canvasWindowLogger = Logger(subsystem: "com.steipete.clawdis", category: "Canvas")
+let canvasWindowLogger = Logger(subsystem: "com.steipete.clawdis", category: "Canvas")
 
-private enum CanvasLayout {
+enum CanvasLayout {
     static let panelSize = NSSize(width: 520, height: 680)
     static let windowSize = NSSize(width: 1120, height: 840)
     static let anchorPadding: CGFloat = 8
@@ -30,890 +25,3 @@ enum CanvasPresentation {
         return false
     }
 }
-
-@MainActor
-final class CanvasWindowController: NSWindowController, WKNavigationDelegate, NSWindowDelegate {
-    private let sessionKey: String
-    private let root: URL
-    private let sessionDir: URL
-    private let schemeHandler: CanvasSchemeHandler
-    private let webView: WKWebView
-    private var a2uiActionMessageHandler: CanvasA2UIActionMessageHandler?
-    private let watcher: CanvasFileWatcher
-    private let container: HoverChromeContainerView
-    let presentation: CanvasPresentation
-    private var preferredPlacement: CanvasPlacement?
-
-    var onVisibilityChanged: ((Bool) -> Void)?
-
-    init(sessionKey: String, root: URL, presentation: CanvasPresentation) throws {
-        self.sessionKey = sessionKey
-        self.root = root
-        self.presentation = presentation
-
-        canvasWindowLogger.debug("CanvasWindowController init start session=\(sessionKey, privacy: .public)")
-        let safeSessionKey = CanvasWindowController.sanitizeSessionKey(sessionKey)
-        canvasWindowLogger.debug("CanvasWindowController init sanitized session=\(safeSessionKey, privacy: .public)")
-        self.sessionDir = root.appendingPathComponent(safeSessionKey, isDirectory: true)
-        try FileManager.default.createDirectory(at: self.sessionDir, withIntermediateDirectories: true)
-        canvasWindowLogger.debug("CanvasWindowController init session dir ready")
-
-        self.schemeHandler = CanvasSchemeHandler(root: root)
-        canvasWindowLogger.debug("CanvasWindowController init scheme handler ready")
-
-        let config = WKWebViewConfiguration()
-        config.userContentController = WKUserContentController()
-        config.preferences.isElementFullscreenEnabled = true
-        config.preferences.setValue(true, forKey: "developerExtrasEnabled")
-        canvasWindowLogger.debug("CanvasWindowController init config ready")
-        config.setURLSchemeHandler(self.schemeHandler, forURLScheme: CanvasScheme.scheme)
-        canvasWindowLogger.debug("CanvasWindowController init scheme handler installed")
-
-        // Bridge A2UI "a2uiaction" DOM events back into the native agent loop.
-        //
-        // Prefer WKScriptMessageHandler when WebKit exposes it, otherwise fall back to an unattended deep link
-        // (includes the app-generated key so it won't prompt).
-        canvasWindowLogger.debug("CanvasWindowController init building A2UI bridge script")
-        let deepLinkKey = DeepLinkHandler.currentCanvasKey()
-        let injectedSessionKey = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty ?? "main"
-        let bridgeScript = """
-        (() => {
-          try {
-            if (location.protocol !== '\(CanvasScheme.scheme):') return;
-            if (globalThis.__clawdisA2UIBridgeInstalled) return;
-            globalThis.__clawdisA2UIBridgeInstalled = true;
-
-            const deepLinkKey = \(Self.jsStringLiteral(deepLinkKey));
-            const sessionKey = \(Self.jsStringLiteral(injectedSessionKey));
-            const machineName = \(Self.jsStringLiteral(InstanceIdentity.displayName));
-            const instanceId = \(Self.jsStringLiteral(InstanceIdentity.instanceId));
-
-            globalThis.addEventListener('a2uiaction', (evt) => {
-              try {
-                const payload = evt?.detail ?? evt?.payload ?? null;
-                if (!payload || payload.eventType !== 'a2ui.action') return;
-
-                const action = payload.action ?? null;
-                const name = action?.name ?? '';
-                if (!name) return;
-
-                const context = Array.isArray(action?.context) ? action.context : [];
-                const userAction = {
-                  id: (globalThis.crypto?.randomUUID?.() ?? String(Date.now())),
-                  name,
-                  surfaceId: payload.surfaceId ?? 'main',
-                  sourceComponentId: payload.sourceComponentId ?? '',
-                  dataContextPath: payload.dataContextPath ?? '',
-                  timestamp: new Date().toISOString(),
-                  ...(context.length ? { context } : {}),
-                };
-
-                const handler = globalThis.webkit?.messageHandlers?.clawdisCanvasA2UIAction;
-
-                // If the bundled A2UI shell is present, let it forward actions so we keep its richer
-                // context resolution (data model path lookups, surface detection, etc.).
-                const hasBundledA2UIHost = !!globalThis.clawdisA2UI || !!document.querySelector('clawdis-a2ui-host');
-                if (hasBundledA2UIHost && handler?.postMessage) return;
-
-                // Otherwise, forward directly when possible.
-                if (!hasBundledA2UIHost && handler?.postMessage) {
-                  handler.postMessage({ userAction });
-                  return;
-                }
-
-                const ctx = userAction.context ? (' ctx=' + JSON.stringify(userAction.context)) : '';
-                const message =
-                  'CANVAS_A2UI action=' + userAction.name +
-                  ' session=' + sessionKey +
-                  ' surface=' + userAction.surfaceId +
-                  ' component=' + (userAction.sourceComponentId || '-') +
-                  ' host=' + machineName.replace(/\\s+/g, '_') +
-                  ' instance=' + instanceId +
-                  ctx +
-                  ' default=update_canvas';
-                const params = new URLSearchParams();
-                params.set('message', message);
-                params.set('sessionKey', sessionKey);
-                params.set('thinking', 'low');
-                params.set('deliver', 'false');
-                params.set('channel', 'last');
-                params.set('key', deepLinkKey);
-                location.href = 'clawdis://agent?' + params.toString();
-              } catch {}
-            }, true);
-          } catch {}
-        })();
-        """
-        config.userContentController.addUserScript(
-            WKUserScript(source: bridgeScript, injectionTime: .atDocumentStart, forMainFrameOnly: true))
-        canvasWindowLogger.debug("CanvasWindowController init A2UI bridge installed")
-
-        canvasWindowLogger.debug("CanvasWindowController init creating WKWebView")
-        self.webView = WKWebView(frame: .zero, configuration: config)
-        // Canvas scaffold is a fully self-contained HTML page; avoid relying on transparency underlays.
-        self.webView.setValue(true, forKey: "drawsBackground")
-
-        let sessionDir = self.sessionDir
-        let webView = self.webView
-        self.watcher = CanvasFileWatcher(url: sessionDir) { [weak webView] in
-            Task { @MainActor in
-                guard let webView else { return }
-
-                // Only auto-reload when we are showing local canvas content.
-                guard webView.url?.scheme == CanvasScheme.scheme else { return }
-
-                // Avoid reloading the built-in A2UI shell due to filesystem noise (it does not depend on session
-                // files).
-                let path = webView.url?.path ?? ""
-                if path.hasPrefix("/__clawdis__/a2ui") { return }
-                if path == "/" || path.isEmpty {
-                    let indexA = sessionDir.appendingPathComponent("index.html", isDirectory: false)
-                    let indexB = sessionDir.appendingPathComponent("index.htm", isDirectory: false)
-                    if !FileManager.default.fileExists(atPath: indexA.path),
-                       !FileManager.default.fileExists(atPath: indexB.path)
-                    {
-                        return
-                    }
-                }
-
-                webView.reload()
-            }
-        }
-
-        self.container = HoverChromeContainerView(containing: self.webView)
-        let window = Self.makeWindow(for: presentation, contentView: self.container)
-        canvasWindowLogger.debug("CanvasWindowController init makeWindow done")
-        super.init(window: window)
-
-        let handler = CanvasA2UIActionMessageHandler(sessionKey: sessionKey)
-        self.a2uiActionMessageHandler = handler
-        self.webView.configuration.userContentController.add(handler, name: CanvasA2UIActionMessageHandler.messageName)
-
-        self.webView.navigationDelegate = self
-        self.window?.delegate = self
-        self.container.onClose = { [weak self] in
-            self?.hideCanvas()
-        }
-
-        self.watcher.start()
-        canvasWindowLogger.debug("CanvasWindowController init done")
-    }
-
-    @available(*, unavailable)
-    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
-
-    @MainActor deinit {
-        self.webView.configuration.userContentController
-            .removeScriptMessageHandler(forName: CanvasA2UIActionMessageHandler.messageName)
-        self.watcher.stop()
-    }
-
-    func applyPreferredPlacement(_ placement: CanvasPlacement?) {
-        self.preferredPlacement = placement
-    }
-
-    func showCanvas(path: String? = nil) {
-        if case let .panel(anchorProvider) = self.presentation {
-            self.presentAnchoredPanel(anchorProvider: anchorProvider)
-            if let path {
-                self.load(target: path)
-            }
-            return
-        }
-
-        self.showWindow(nil)
-        self.window?.makeKeyAndOrderFront(nil)
-        NSApp.activate(ignoringOtherApps: true)
-        if let path {
-            self.load(target: path)
-        }
-        self.onVisibilityChanged?(true)
-    }
-
-    func hideCanvas() {
-        if case .panel = self.presentation {
-            self.persistFrameIfPanel()
-        }
-        self.window?.orderOut(nil)
-        self.onVisibilityChanged?(false)
-    }
-
-    func load(target: String) {
-        let trimmed = target.trimmingCharacters(in: .whitespacesAndNewlines)
-
-        if let url = URL(string: trimmed), let scheme = url.scheme?.lowercased() {
-            if scheme == "https" || scheme == "http" {
-                canvasWindowLogger.debug("canvas load url \(url.absoluteString, privacy: .public)")
-                self.webView.load(URLRequest(url: url))
-                return
-            }
-            if scheme == "file" {
-                canvasWindowLogger.debug("canvas load file \(url.absoluteString, privacy: .public)")
-                self.loadFile(url)
-                return
-            }
-        }
-
-        // Convenience: absolute file paths resolve as local files when they exist.
-        // (Avoid treating Canvas routes like "/" as filesystem paths.)
-        if trimmed.hasPrefix("/") {
-            var isDir: ObjCBool = false
-            if FileManager.default.fileExists(atPath: trimmed, isDirectory: &isDir), !isDir.boolValue {
-                let url = URL(fileURLWithPath: trimmed)
-                canvasWindowLogger.debug("canvas load file \(url.absoluteString, privacy: .public)")
-                self.loadFile(url)
-                return
-            }
-        }
-
-        guard let url = CanvasScheme.makeURL(
-            session: CanvasWindowController.sanitizeSessionKey(self.sessionKey),
-            path: trimmed)
-        else {
-            canvasWindowLogger
-                .error(
-                    "invalid canvas url session=\(self.sessionKey, privacy: .public) path=\(trimmed, privacy: .public)")
-            return
-        }
-        canvasWindowLogger.debug("canvas load canvas \(url.absoluteString, privacy: .public)")
-        self.webView.load(URLRequest(url: url))
-    }
-
-    private func loadFile(_ url: URL) {
-        let fileURL = url.isFileURL ? url : URL(fileURLWithPath: url.path)
-        let accessDir = fileURL.deletingLastPathComponent()
-        self.webView.loadFileURL(fileURL, allowingReadAccessTo: accessDir)
-    }
-
-    func eval(javaScript: String) async throws -> String {
-        try await withCheckedThrowingContinuation { cont in
-            self.webView.evaluateJavaScript(javaScript) { result, error in
-                if let error {
-                    cont.resume(throwing: error)
-                    return
-                }
-                if let result {
-                    cont.resume(returning: String(describing: result))
-                } else {
-                    cont.resume(returning: "")
-                }
-            }
-        }
-    }
-
-    func snapshot(to outPath: String?) async throws -> String {
-        let image: NSImage = try await withCheckedThrowingContinuation { cont in
-            self.webView.takeSnapshot(with: nil) { image, error in
-                if let error {
-                    cont.resume(throwing: error)
-                    return
-                }
-                guard let image else {
-                    cont.resume(throwing: NSError(domain: "Canvas", code: 11, userInfo: [
-                        NSLocalizedDescriptionKey: "snapshot returned nil image",
-                    ]))
-                    return
-                }
-                cont.resume(returning: image)
-            }
-        }
-
-        guard let tiff = image.tiffRepresentation,
-              let rep = NSBitmapImageRep(data: tiff),
-              let png = rep.representation(using: .png, properties: [:])
-        else {
-            throw NSError(domain: "Canvas", code: 12, userInfo: [
-                NSLocalizedDescriptionKey: "failed to encode png",
-            ])
-        }
-
-        let path: String
-        if let outPath, !outPath.isEmpty {
-            path = outPath
-        } else {
-            let ts = Int(Date().timeIntervalSince1970)
-            path = "/tmp/clawdis-canvas-\(CanvasWindowController.sanitizeSessionKey(self.sessionKey))-\(ts).png"
-        }
-
-        try png.write(to: URL(fileURLWithPath: path), options: [.atomic])
-        return path
-    }
-
-    var directoryPath: String {
-        self.sessionDir.path
-    }
-
-    // MARK: - Window
-
-    private static func makeWindow(for presentation: CanvasPresentation, contentView: NSView) -> NSWindow {
-        switch presentation {
-        case .window:
-            let window = NSWindow(
-                contentRect: NSRect(origin: .zero, size: CanvasLayout.windowSize),
-                styleMask: [.titled, .closable, .resizable, .miniaturizable],
-                backing: .buffered,
-                defer: false)
-            window.title = "Clawdis Canvas"
-            window.isReleasedWhenClosed = false
-            window.contentView = contentView
-            window.center()
-            window.minSize = NSSize(width: 880, height: 680)
-            return window
-
-        case .panel:
-            let panel = CanvasPanel(
-                contentRect: NSRect(origin: .zero, size: CanvasLayout.panelSize),
-                styleMask: [.borderless, .resizable],
-                backing: .buffered,
-                defer: false)
-            // Keep Canvas below the Voice Wake overlay panel.
-            panel.level = NSWindow.Level(rawValue: NSWindow.Level.statusBar.rawValue - 1)
-            panel.hasShadow = true
-            panel.isMovable = false
-            panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
-            panel.titleVisibility = .hidden
-            panel.titlebarAppearsTransparent = true
-            panel.backgroundColor = .clear
-            panel.isOpaque = false
-            panel.contentView = contentView
-            panel.becomesKeyOnlyIfNeeded = true
-            panel.hidesOnDeactivate = false
-            panel.minSize = CanvasLayout.minPanelSize
-            return panel
-        }
-    }
-
-    func presentAnchoredPanel(anchorProvider: @escaping () -> NSRect?) {
-        guard case .panel = self.presentation, let window else { return }
-        self.repositionPanel(using: anchorProvider)
-        window.makeKeyAndOrderFront(nil)
-        NSApp.activate(ignoringOtherApps: true)
-        window.makeFirstResponder(self.webView)
-        VoiceWakeOverlayController.shared.bringToFrontIfVisible()
-        self.onVisibilityChanged?(true)
-    }
-
-    private func repositionPanel(using anchorProvider: () -> NSRect?) {
-        guard let panel = self.window else { return }
-        let anchor = anchorProvider()
-        let targetScreen = Self.screen(forAnchor: anchor)
-            ?? Self.screenContainingMouseCursor()
-            ?? panel.screen
-            ?? NSScreen.main
-            ?? NSScreen.screens.first
-
-        let restored = Self.loadRestoredFrame(sessionKey: self.sessionKey)
-        let restoredIsValid = if let restored, let targetScreen {
-            Self.isFrameMeaningfullyVisible(restored, on: targetScreen)
-        } else {
-            restored != nil
-        }
-
-        var frame = if let restored, restoredIsValid {
-            restored
-        } else {
-            Self.defaultTopRightFrame(panel: panel, screen: targetScreen)
-        }
-
-        // Apply agent placement as partial overrides:
-        // - If agent provides x/y, override origin.
-        // - If agent provides width/height, override size.
-        // - If agent provides only size, keep the remembered origin.
-        if let placement = self.preferredPlacement {
-            if let x = placement.x { frame.origin.x = x }
-            if let y = placement.y { frame.origin.y = y }
-            if let w = placement.width { frame.size.width = max(CanvasLayout.minPanelSize.width, CGFloat(w)) }
-            if let h = placement.height { frame.size.height = max(CanvasLayout.minPanelSize.height, CGFloat(h)) }
-        }
-
-        self.setPanelFrame(frame, on: targetScreen)
-    }
-
-    private static func defaultTopRightFrame(panel: NSWindow, screen: NSScreen?) -> NSRect {
-        let w = max(CanvasLayout.minPanelSize.width, panel.frame.width)
-        let h = max(CanvasLayout.minPanelSize.height, panel.frame.height)
-        return WindowPlacement.topRightFrame(
-            size: NSSize(width: w, height: h),
-            padding: CanvasLayout.defaultPadding,
-            on: screen)
-    }
-
-    private func setPanelFrame(_ frame: NSRect, on screen: NSScreen?) {
-        guard let panel = self.window else { return }
-        guard let s = screen ?? panel.screen ?? NSScreen.main ?? NSScreen.screens.first else {
-            panel.setFrame(frame, display: false)
-            self.persistFrameIfPanel()
-            return
-        }
-
-        let constrained = Self.constrainFrame(frame, toVisibleFrame: s.visibleFrame)
-        panel.setFrame(constrained, display: false)
-        self.persistFrameIfPanel()
-    }
-
-    private static func screen(forAnchor anchor: NSRect?) -> NSScreen? {
-        guard let anchor else { return nil }
-        let center = NSPoint(x: anchor.midX, y: anchor.midY)
-        return NSScreen.screens.first { screen in
-            screen.frame.contains(anchor.origin) || screen.frame.contains(center)
-        }
-    }
-
-    private static func screenContainingMouseCursor() -> NSScreen? {
-        let point = NSEvent.mouseLocation
-        return NSScreen.screens.first { $0.frame.contains(point) }
-    }
-
-    private static func isFrameMeaningfullyVisible(_ frame: NSRect, on screen: NSScreen) -> Bool {
-        frame.intersects(screen.visibleFrame.insetBy(dx: 12, dy: 12))
-    }
-
-    fileprivate static func constrainFrame(_ frame: NSRect, toVisibleFrame bounds: NSRect) -> NSRect {
-        if bounds == .zero { return frame }
-
-        var next = frame
-        next.size.width = min(max(CanvasLayout.minPanelSize.width, next.size.width), bounds.width)
-        next.size.height = min(max(CanvasLayout.minPanelSize.height, next.size.height), bounds.height)
-
-        let maxX = bounds.maxX - next.size.width
-        let maxY = bounds.maxY - next.size.height
-
-        next.origin.x = maxX >= bounds.minX ? min(max(next.origin.x, bounds.minX), maxX) : bounds.minX
-        next.origin.y = maxY >= bounds.minY ? min(max(next.origin.y, bounds.minY), maxY) : bounds.minY
-
-        next.origin.x = round(next.origin.x)
-        next.origin.y = round(next.origin.y)
-        return next
-    }
-
-    // MARK: - WKNavigationDelegate
-
-    @MainActor
-    func webView(
-        _: WKWebView,
-        decidePolicyFor navigationAction: WKNavigationAction,
-        decisionHandler: @escaping @MainActor @Sendable (WKNavigationActionPolicy) -> Void)
-    {
-        guard let url = navigationAction.request.url else {
-            decisionHandler(.cancel)
-            return
-        }
-        let scheme = url.scheme?.lowercased()
-
-        // Deep links: allow local Canvas content to invoke the agent without bouncing through NSWorkspace.
-        if scheme == "clawdis" {
-            if self.webView.url?.scheme == CanvasScheme.scheme {
-                Task { await DeepLinkHandler.shared.handle(url: url) }
-            } else {
-                canvasWindowLogger
-                    .debug("ignoring deep link from non-canvas page \(url.absoluteString, privacy: .public)")
-            }
-            decisionHandler(.cancel)
-            return
-        }
-
-        // Keep web content inside the panel when reasonable.
-        // `about:blank` and friends are common internal navigations for WKWebView; never send them to NSWorkspace.
-        if scheme == CanvasScheme.scheme
-            || scheme == "https"
-            || scheme == "http"
-            || scheme == "about"
-            || scheme == "blob"
-            || scheme == "data"
-            || scheme == "javascript"
-        {
-            decisionHandler(.allow)
-            return
-        }
-
-        // Only open external URLs when there is a registered handler, otherwise macOS will show a confusing
-        // "There is no application set to open the URL ..." alert (e.g. for about:blank).
-        if let appURL = NSWorkspace.shared.urlForApplication(toOpen: url) {
-            NSWorkspace.shared.open(
-                [url],
-                withApplicationAt: appURL,
-                configuration: NSWorkspace.OpenConfiguration(),
-                completionHandler: nil)
-        } else {
-            canvasWindowLogger.debug("no application to open url \(url.absoluteString, privacy: .public)")
-        }
-        decisionHandler(.cancel)
-    }
-
-    // MARK: - NSWindowDelegate
-
-    func windowWillClose(_: Notification) {
-        self.onVisibilityChanged?(false)
-    }
-
-    func windowDidMove(_: Notification) {
-        self.persistFrameIfPanel()
-    }
-
-    func windowDidEndLiveResize(_: Notification) {
-        self.persistFrameIfPanel()
-    }
-
-    private func persistFrameIfPanel() {
-        guard case .panel = self.presentation, let window else { return }
-        Self.storeRestoredFrame(window.frame, sessionKey: self.sessionKey)
-    }
-
-    // MARK: - Helpers
-
-    private static func sanitizeSessionKey(_ key: String) -> String {
-        let trimmed = key.trimmingCharacters(in: .whitespacesAndNewlines)
-        if trimmed.isEmpty { return "main" }
-        let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-+")
-        let scalars = trimmed.unicodeScalars.map { allowed.contains($0) ? Character($0) : "_" }
-        return String(scalars)
-    }
-
-    private static func jsStringLiteral(_ value: String) -> String {
-        let data = try? JSONEncoder().encode(value)
-        return data.flatMap { String(data: $0, encoding: .utf8) } ?? "\"\""
-    }
-
-    private static func storedFrameDefaultsKey(sessionKey: String) -> String {
-        "clawdis.canvas.frame.\(self.sanitizeSessionKey(sessionKey))"
-    }
-
-    private static func loadRestoredFrame(sessionKey: String) -> NSRect? {
-        let key = self.storedFrameDefaultsKey(sessionKey: sessionKey)
-        guard let arr = UserDefaults.standard.array(forKey: key) as? [Double], arr.count == 4 else { return nil }
-        let rect = NSRect(x: arr[0], y: arr[1], width: arr[2], height: arr[3])
-        if rect.width < CanvasLayout.minPanelSize.width || rect.height < CanvasLayout.minPanelSize.height { return nil }
-        return rect
-    }
-
-    private static func storeRestoredFrame(_ frame: NSRect, sessionKey: String) {
-        let key = self.storedFrameDefaultsKey(sessionKey: sessionKey)
-        UserDefaults.standard.set(
-            [Double(frame.origin.x), Double(frame.origin.y), Double(frame.size.width), Double(frame.size.height)],
-            forKey: key)
-    }
-}
-
-private final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
-    static let messageName = "clawdisCanvasA2UIAction"
-
-    private let sessionKey: String
-
-    init(sessionKey: String) {
-        self.sessionKey = sessionKey
-        super.init()
-    }
-
-    func userContentController(_: WKUserContentController, didReceive message: WKScriptMessage) {
-        guard message.name == Self.messageName else { return }
-
-        // Only accept actions from local Canvas content (not arbitrary web pages).
-        guard let webView = message.webView,
-              webView.url?.scheme == CanvasScheme.scheme
-        else { return }
-
-        let body: [String: Any] = {
-            if let dict = message.body as? [String: Any] { return dict }
-            if let dict = message.body as? [AnyHashable: Any] {
-                return dict.reduce(into: [String: Any]()) { acc, pair in
-                    guard let key = pair.key as? String else { return }
-                    acc[key] = pair.value
-                }
-            }
-            return [:]
-        }()
-        guard !body.isEmpty else { return }
-
-        let userActionAny = body["userAction"] ?? body
-        let userAction: [String: Any] = {
-            if let dict = userActionAny as? [String: Any] { return dict }
-            if let dict = userActionAny as? [AnyHashable: Any] {
-                return dict.reduce(into: [String: Any]()) { acc, pair in
-                    guard let key = pair.key as? String else { return }
-                    acc[key] = pair.value
-                }
-            }
-            return [:]
-        }()
-        guard !userAction.isEmpty else { return }
-
-        guard let name = userAction["name"] as? String, !name.isEmpty else { return }
-        let actionId =
-            (userAction["id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
-                ?? UUID().uuidString
-
-        canvasWindowLogger.info("A2UI action \(name, privacy: .public) session=\(self.sessionKey, privacy: .public)")
-
-        let surfaceId = (userAction["surfaceId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
-            .nonEmpty ?? "main"
-        let sourceComponentId = (userAction["sourceComponentId"] as? String)?
-            .trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty ?? "-"
-        let instanceId = InstanceIdentity.instanceId.lowercased()
-        let contextJSON = ClawdisCanvasA2UIAction.compactJSON(userAction["context"])
-
-        // Token-efficient and unambiguous. The agent should treat this as a UI event and (by default) update Canvas.
-        let text = ClawdisCanvasA2UIAction.formatAgentMessage(
-            actionName: name,
-            sessionKey: self.sessionKey,
-            surfaceId: surfaceId,
-            sourceComponentId: sourceComponentId,
-            host: InstanceIdentity.displayName,
-            instanceId: instanceId,
-            contextJSON: contextJSON)
-
-        Task { [weak webView] in
-            if AppStateStore.shared.connectionMode == .local {
-                GatewayProcessManager.shared.setActive(true)
-            }
-
-            let result = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
-                message: text,
-                sessionKey: self.sessionKey,
-                thinking: "low",
-                deliver: false,
-                to: nil,
-                channel: .last,
-                idempotencyKey: actionId))
-
-            await MainActor.run {
-                guard let webView else { return }
-                let js = ClawdisCanvasA2UIAction.jsDispatchA2UIActionStatus(
-                    actionId: actionId,
-                    ok: result.ok,
-                    error: result.error)
-                webView.evaluateJavaScript(js) { _, _ in }
-            }
-            if !result.ok {
-                canvasWindowLogger.error(
-                    "A2UI action send failed name=\(name, privacy: .public) error=\(result.error ?? "unknown", privacy: .public)")
-            }
-        }
-    }
-
-    // Formatting helpers live in ClawdisKit (`ClawdisCanvasA2UIAction`).
-}
-
-// MARK: - Hover chrome container
-
-private final class HoverChromeContainerView: NSView {
-    private let content: NSView
-    private let chrome: CanvasChromeOverlayView
-    private var tracking: NSTrackingArea?
-    var onClose: (() -> Void)?
-
-    init(containing content: NSView) {
-        self.content = content
-        self.chrome = CanvasChromeOverlayView(frame: .zero)
-        super.init(frame: .zero)
-
-        self.wantsLayer = true
-        self.layer?.cornerRadius = 12
-        self.layer?.masksToBounds = true
-        self.layer?.backgroundColor = NSColor.windowBackgroundColor.cgColor
-
-        self.content.translatesAutoresizingMaskIntoConstraints = false
-        self.addSubview(self.content)
-
-        self.chrome.translatesAutoresizingMaskIntoConstraints = false
-        self.chrome.alphaValue = 0
-        self.chrome.onClose = { [weak self] in self?.onClose?() }
-        self.addSubview(self.chrome)
-
-        NSLayoutConstraint.activate([
-            self.content.leadingAnchor.constraint(equalTo: self.leadingAnchor),
-            self.content.trailingAnchor.constraint(equalTo: self.trailingAnchor),
-            self.content.topAnchor.constraint(equalTo: self.topAnchor),
-            self.content.bottomAnchor.constraint(equalTo: self.bottomAnchor),
-
-            self.chrome.leadingAnchor.constraint(equalTo: self.leadingAnchor),
-            self.chrome.trailingAnchor.constraint(equalTo: self.trailingAnchor),
-            self.chrome.topAnchor.constraint(equalTo: self.topAnchor),
-            self.chrome.bottomAnchor.constraint(equalTo: self.bottomAnchor),
-        ])
-    }
-
-    @available(*, unavailable)
-    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
-
-    override func updateTrackingAreas() {
-        super.updateTrackingAreas()
-        if let tracking {
-            self.removeTrackingArea(tracking)
-        }
-        let area = NSTrackingArea(
-            rect: self.bounds,
-            options: [.activeAlways, .mouseEnteredAndExited, .inVisibleRect],
-            owner: self,
-            userInfo: nil)
-        self.addTrackingArea(area)
-        self.tracking = area
-    }
-
-    private final class CanvasDragHandleView: NSView {
-        override func mouseDown(with event: NSEvent) {
-            self.window?.performDrag(with: event)
-        }
-
-        override func acceptsFirstMouse(for _: NSEvent?) -> Bool { true }
-    }
-
-    private final class CanvasResizeHandleView: NSView {
-        private var startPoint: NSPoint = .zero
-        private var startFrame: NSRect = .zero
-
-        override func acceptsFirstMouse(for _: NSEvent?) -> Bool { true }
-
-        override func mouseDown(with event: NSEvent) {
-            guard let window else { return }
-            _ = window.makeFirstResponder(self)
-            self.startPoint = NSEvent.mouseLocation
-            self.startFrame = window.frame
-            super.mouseDown(with: event)
-        }
-
-        override func mouseDragged(with _: NSEvent) {
-            guard let window else { return }
-            let current = NSEvent.mouseLocation
-            let dx = current.x - self.startPoint.x
-            let dy = current.y - self.startPoint.y
-
-            var frame = self.startFrame
-            frame.size.width = max(CanvasLayout.minPanelSize.width, frame.size.width + dx)
-            frame.origin.y += dy
-            frame.size.height = max(CanvasLayout.minPanelSize.height, frame.size.height - dy)
-
-            if let screen = window.screen {
-                frame = CanvasWindowController.constrainFrame(frame, toVisibleFrame: screen.visibleFrame)
-            }
-            window.setFrame(frame, display: true)
-        }
-    }
-
-    private final class CanvasChromeOverlayView: NSView {
-        var onClose: (() -> Void)?
-
-        private let dragHandle = CanvasDragHandleView(frame: .zero)
-        private let resizeHandle = CanvasResizeHandleView(frame: .zero)
-
-        private final class PassthroughVisualEffectView: NSVisualEffectView {
-            override func hitTest(_: NSPoint) -> NSView? { nil }
-        }
-
-        private let closeBackground: NSVisualEffectView = {
-            let v = PassthroughVisualEffectView(frame: .zero)
-            v.material = .hudWindow
-            v.blendingMode = .withinWindow
-            v.state = .active
-            v.appearance = NSAppearance(named: .vibrantDark)
-            v.wantsLayer = true
-            v.layer?.cornerRadius = 10
-            v.layer?.masksToBounds = true
-            v.layer?.borderWidth = 1
-            v.layer?.borderColor = NSColor.white.withAlphaComponent(0.22).cgColor
-            v.layer?.backgroundColor = NSColor.black.withAlphaComponent(0.28).cgColor
-            v.layer?.shadowColor = NSColor.black.withAlphaComponent(0.35).cgColor
-            v.layer?.shadowOpacity = 0.35
-            v.layer?.shadowRadius = 8
-            v.layer?.shadowOffset = .zero
-            return v
-        }()
-
-        private let closeButton: NSButton = {
-            let cfg = NSImage.SymbolConfiguration(pointSize: 8, weight: .semibold)
-            let img = NSImage(systemSymbolName: "xmark", accessibilityDescription: "Close")?
-                .withSymbolConfiguration(cfg)
-                ?? NSImage(size: NSSize(width: 18, height: 18))
-            let btn = NSButton(image: img, target: nil, action: nil)
-            btn.isBordered = false
-            btn.bezelStyle = .regularSquare
-            btn.imageScaling = .scaleProportionallyDown
-            btn.contentTintColor = NSColor.white.withAlphaComponent(0.92)
-            btn.toolTip = "Close"
-            return btn
-        }()
-
-        override init(frame frameRect: NSRect) {
-            super.init(frame: frameRect)
-
-            self.wantsLayer = true
-            self.layer?.cornerRadius = 12
-            self.layer?.masksToBounds = true
-            self.layer?.borderWidth = 1
-            self.layer?.borderColor = NSColor.black.withAlphaComponent(0.18).cgColor
-            self.layer?.backgroundColor = NSColor.black.withAlphaComponent(0.02).cgColor
-
-            self.dragHandle.translatesAutoresizingMaskIntoConstraints = false
-            self.dragHandle.wantsLayer = true
-            self.dragHandle.layer?.backgroundColor = NSColor.clear.cgColor
-            self.addSubview(self.dragHandle)
-
-            self.resizeHandle.translatesAutoresizingMaskIntoConstraints = false
-            self.resizeHandle.wantsLayer = true
-            self.resizeHandle.layer?.backgroundColor = NSColor.clear.cgColor
-            self.addSubview(self.resizeHandle)
-
-            self.closeBackground.translatesAutoresizingMaskIntoConstraints = false
-            self.addSubview(self.closeBackground)
-
-            self.closeButton.translatesAutoresizingMaskIntoConstraints = false
-            self.closeButton.target = self
-            self.closeButton.action = #selector(self.handleClose)
-            self.addSubview(self.closeButton)
-
-            NSLayoutConstraint.activate([
-                self.dragHandle.leadingAnchor.constraint(equalTo: self.leadingAnchor),
-                self.dragHandle.trailingAnchor.constraint(equalTo: self.trailingAnchor),
-                self.dragHandle.topAnchor.constraint(equalTo: self.topAnchor),
-                self.dragHandle.heightAnchor.constraint(equalToConstant: 30),
-
-                self.closeBackground.centerXAnchor.constraint(equalTo: self.closeButton.centerXAnchor),
-                self.closeBackground.centerYAnchor.constraint(equalTo: self.closeButton.centerYAnchor),
-                self.closeBackground.widthAnchor.constraint(equalToConstant: 20),
-                self.closeBackground.heightAnchor.constraint(equalToConstant: 20),
-
-                self.closeButton.trailingAnchor.constraint(equalTo: self.trailingAnchor, constant: -8),
-                self.closeButton.topAnchor.constraint(equalTo: self.topAnchor, constant: 8),
-                self.closeButton.widthAnchor.constraint(equalToConstant: 16),
-                self.closeButton.heightAnchor.constraint(equalToConstant: 16),
-
-                self.resizeHandle.trailingAnchor.constraint(equalTo: self.trailingAnchor),
-                self.resizeHandle.bottomAnchor.constraint(equalTo: self.bottomAnchor),
-                self.resizeHandle.widthAnchor.constraint(equalToConstant: 18),
-                self.resizeHandle.heightAnchor.constraint(equalToConstant: 18),
-            ])
-        }
-
-        @available(*, unavailable)
-        required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
-
-        override func hitTest(_ point: NSPoint) -> NSView? {
-            // When the chrome is hidden, do not intercept any mouse events (let the WKWebView receive them).
-            guard self.alphaValue > 0.02 else { return nil }
-
-            if self.closeButton.frame.contains(point) { return self.closeButton }
-            if self.dragHandle.frame.contains(point) { return self.dragHandle }
-            if self.resizeHandle.frame.contains(point) { return self.resizeHandle }
-            return nil
-        }
-
-        @objc private func handleClose() {
-            self.onClose?()
-        }
-    }
-
-    override func mouseEntered(with _: NSEvent) {
-        NSAnimationContext.runAnimationGroup { ctx in
-            ctx.duration = 0.12
-            ctx.timingFunction = CAMediaTimingFunction(name: .easeOut)
-            self.chrome.animator().alphaValue = 1
-        }
-    }
-
-    override func mouseExited(with _: NSEvent) {
-        NSAnimationContext.runAnimationGroup { ctx in
-            ctx.duration = 0.16
-            ctx.timingFunction = CAMediaTimingFunction(name: .easeOut)
-            self.chrome.animator().alphaValue = 0
-        }
-    }
-}

apps/macos/Sources/Clawdis/CanvasWindowController+Helpers.swift

@@ -0,0 +1,43 @@
+import AppKit
+import Foundation
+
+extension CanvasWindowController {
+    // MARK: - Helpers
+
+    static func sanitizeSessionKey(_ key: String) -> String {
+        let trimmed = key.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return "main" }
+        let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-+")
+        let scalars = trimmed.unicodeScalars.map { allowed.contains($0) ? Character($0) : "_" }
+        return String(scalars)
+    }
+
+    static func jsStringLiteral(_ value: String) -> String {
+        let data = try? JSONEncoder().encode(value)
+        return data.flatMap { String(data: $0, encoding: .utf8) } ?? "\"\""
+    }
+
+    static func jsOptionalStringLiteral(_ value: String?) -> String {
+        guard let value else { return "null" }
+        return Self.jsStringLiteral(value)
+    }
+
+    static func storedFrameDefaultsKey(sessionKey: String) -> String {
+        "clawdis.canvas.frame.\(self.sanitizeSessionKey(sessionKey))"
+    }
+
+    static func loadRestoredFrame(sessionKey: String) -> NSRect? {
+        let key = self.storedFrameDefaultsKey(sessionKey: sessionKey)
+        guard let arr = UserDefaults.standard.array(forKey: key) as? [Double], arr.count == 4 else { return nil }
+        let rect = NSRect(x: arr[0], y: arr[1], width: arr[2], height: arr[3])
+        if rect.width < CanvasLayout.minPanelSize.width || rect.height < CanvasLayout.minPanelSize.height { return nil }
+        return rect
+    }
+
+    static func storeRestoredFrame(_ frame: NSRect, sessionKey: String) {
+        let key = self.storedFrameDefaultsKey(sessionKey: sessionKey)
+        UserDefaults.standard.set(
+            [Double(frame.origin.x), Double(frame.origin.y), Double(frame.size.width), Double(frame.size.height)],
+            forKey: key)
+    }
+}

apps/macos/Sources/Clawdis/CanvasWindowController+Navigation.swift

@@ -0,0 +1,62 @@
+import AppKit
+import WebKit
+
+extension CanvasWindowController {
+    // MARK: - WKNavigationDelegate
+
+    @MainActor
+    func webView(
+        _: WKWebView,
+        decidePolicyFor navigationAction: WKNavigationAction,
+        decisionHandler: @escaping @MainActor @Sendable (WKNavigationActionPolicy) -> Void)
+    {
+        guard let url = navigationAction.request.url else {
+            decisionHandler(.cancel)
+            return
+        }
+        let scheme = url.scheme?.lowercased()
+
+        // Deep links: allow local Canvas content to invoke the agent without bouncing through NSWorkspace.
+        if scheme == "clawdis" {
+            if self.webView.url?.scheme == CanvasScheme.scheme {
+                Task { await DeepLinkHandler.shared.handle(url: url) }
+            } else {
+                canvasWindowLogger
+                    .debug("ignoring deep link from non-canvas page \(url.absoluteString, privacy: .public)")
+            }
+            decisionHandler(.cancel)
+            return
+        }
+
+        // Keep web content inside the panel when reasonable.
+        // `about:blank` and friends are common internal navigations for WKWebView; never send them to NSWorkspace.
+        if scheme == CanvasScheme.scheme
+            || scheme == "https"
+            || scheme == "http"
+            || scheme == "about"
+            || scheme == "blob"
+            || scheme == "data"
+            || scheme == "javascript"
+        {
+            decisionHandler(.allow)
+            return
+        }
+
+        // Only open external URLs when there is a registered handler, otherwise macOS will show a confusing
+        // "There is no application set to open the URL ..." alert (e.g. for about:blank).
+        if let appURL = NSWorkspace.shared.urlForApplication(toOpen: url) {
+            NSWorkspace.shared.open(
+                [url],
+                withApplicationAt: appURL,
+                configuration: NSWorkspace.OpenConfiguration(),
+                completionHandler: nil)
+        } else {
+            canvasWindowLogger.debug("no application to open url \(url.absoluteString, privacy: .public)")
+        }
+        decisionHandler(.cancel)
+    }
+
+    func webView(_: WKWebView, didFinish _: WKNavigation?) {
+        self.applyDebugStatusIfNeeded()
+    }
+}

apps/macos/Sources/Clawdis/CanvasWindowController+Testing.swift

@@ -0,0 +1,39 @@
+#if DEBUG
+import AppKit
+import Foundation
+
+extension CanvasWindowController {
+    static func _testSanitizeSessionKey(_ key: String) -> String {
+        self.sanitizeSessionKey(key)
+    }
+
+    static func _testJSStringLiteral(_ value: String) -> String {
+        self.jsStringLiteral(value)
+    }
+
+    static func _testJSOptionalStringLiteral(_ value: String?) -> String {
+        self.jsOptionalStringLiteral(value)
+    }
+
+    static func _testStoredFrameKey(sessionKey: String) -> String {
+        self.storedFrameDefaultsKey(sessionKey: sessionKey)
+    }
+
+    static func _testStoreAndLoadFrame(sessionKey: String, frame: NSRect) -> NSRect? {
+        self.storeRestoredFrame(frame, sessionKey: sessionKey)
+        return self.loadRestoredFrame(sessionKey: sessionKey)
+    }
+
+    static func _testParseIPv4(_ host: String) -> (UInt8, UInt8, UInt8, UInt8)? {
+        CanvasA2UIActionMessageHandler.parseIPv4(host)
+    }
+
+    static func _testIsLocalNetworkIPv4(_ ip: (UInt8, UInt8, UInt8, UInt8)) -> Bool {
+        CanvasA2UIActionMessageHandler.isLocalNetworkIPv4(ip)
+    }
+
+    static func _testIsLocalNetworkCanvasURL(_ url: URL) -> Bool {
+        CanvasA2UIActionMessageHandler.isLocalNetworkCanvasURL(url)
+    }
+}
+#endif

apps/macos/Sources/Clawdis/CanvasWindowController+Window.swift

@@ -0,0 +1,166 @@
+import AppKit
+import ClawdisIPC
+
+extension CanvasWindowController {
+    // MARK: - Window
+
+    static func makeWindow(for presentation: CanvasPresentation, contentView: NSView) -> NSWindow {
+        switch presentation {
+        case .window:
+            let window = NSWindow(
+                contentRect: NSRect(origin: .zero, size: CanvasLayout.windowSize),
+                styleMask: [.titled, .closable, .resizable, .miniaturizable],
+                backing: .buffered,
+                defer: false)
+            window.title = "Clawdis Canvas"
+            window.isReleasedWhenClosed = false
+            window.contentView = contentView
+            window.center()
+            window.minSize = NSSize(width: 880, height: 680)
+            return window
+
+        case .panel:
+            let panel = CanvasPanel(
+                contentRect: NSRect(origin: .zero, size: CanvasLayout.panelSize),
+                styleMask: [.borderless, .resizable],
+                backing: .buffered,
+                defer: false)
+            // Keep Canvas below the Voice Wake overlay panel.
+            panel.level = NSWindow.Level(rawValue: NSWindow.Level.statusBar.rawValue - 1)
+            panel.hasShadow = true
+            panel.isMovable = false
+            panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
+            panel.titleVisibility = .hidden
+            panel.titlebarAppearsTransparent = true
+            panel.backgroundColor = .clear
+            panel.isOpaque = false
+            panel.contentView = contentView
+            panel.becomesKeyOnlyIfNeeded = true
+            panel.hidesOnDeactivate = false
+            panel.minSize = CanvasLayout.minPanelSize
+            return panel
+        }
+    }
+
+    func presentAnchoredPanel(anchorProvider: @escaping () -> NSRect?) {
+        guard case .panel = self.presentation, let window else { return }
+        self.repositionPanel(using: anchorProvider)
+        window.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+        window.makeFirstResponder(self.webView)
+        VoiceWakeOverlayController.shared.bringToFrontIfVisible()
+        self.onVisibilityChanged?(true)
+    }
+
+    func repositionPanel(using anchorProvider: () -> NSRect?) {
+        guard let panel = self.window else { return }
+        let anchor = anchorProvider()
+        let targetScreen = Self.screen(forAnchor: anchor)
+            ?? Self.screenContainingMouseCursor()
+            ?? panel.screen
+            ?? NSScreen.main
+            ?? NSScreen.screens.first
+
+        let restored = Self.loadRestoredFrame(sessionKey: self.sessionKey)
+        let restoredIsValid = if let restored, let targetScreen {
+            Self.isFrameMeaningfullyVisible(restored, on: targetScreen)
+        } else {
+            restored != nil
+        }
+
+        var frame = if let restored, restoredIsValid {
+            restored
+        } else {
+            Self.defaultTopRightFrame(panel: panel, screen: targetScreen)
+        }
+
+        // Apply agent placement as partial overrides:
+        // - If agent provides x/y, override origin.
+        // - If agent provides width/height, override size.
+        // - If agent provides only size, keep the remembered origin.
+        if let placement = self.preferredPlacement {
+            if let x = placement.x { frame.origin.x = x }
+            if let y = placement.y { frame.origin.y = y }
+            if let w = placement.width { frame.size.width = max(CanvasLayout.minPanelSize.width, CGFloat(w)) }
+            if let h = placement.height { frame.size.height = max(CanvasLayout.minPanelSize.height, CGFloat(h)) }
+        }
+
+        self.setPanelFrame(frame, on: targetScreen)
+    }
+
+    static func defaultTopRightFrame(panel: NSWindow, screen: NSScreen?) -> NSRect {
+        let w = max(CanvasLayout.minPanelSize.width, panel.frame.width)
+        let h = max(CanvasLayout.minPanelSize.height, panel.frame.height)
+        return WindowPlacement.topRightFrame(
+            size: NSSize(width: w, height: h),
+            padding: CanvasLayout.defaultPadding,
+            on: screen)
+    }
+
+    func setPanelFrame(_ frame: NSRect, on screen: NSScreen?) {
+        guard let panel = self.window else { return }
+        guard let s = screen ?? panel.screen ?? NSScreen.main ?? NSScreen.screens.first else {
+            panel.setFrame(frame, display: false)
+            self.persistFrameIfPanel()
+            return
+        }
+
+        let constrained = Self.constrainFrame(frame, toVisibleFrame: s.visibleFrame)
+        panel.setFrame(constrained, display: false)
+        self.persistFrameIfPanel()
+    }
+
+    static func screen(forAnchor anchor: NSRect?) -> NSScreen? {
+        guard let anchor else { return nil }
+        let center = NSPoint(x: anchor.midX, y: anchor.midY)
+        return NSScreen.screens.first { screen in
+            screen.frame.contains(anchor.origin) || screen.frame.contains(center)
+        }
+    }
+
+    static func screenContainingMouseCursor() -> NSScreen? {
+        let point = NSEvent.mouseLocation
+        return NSScreen.screens.first { $0.frame.contains(point) }
+    }
+
+    static func isFrameMeaningfullyVisible(_ frame: NSRect, on screen: NSScreen) -> Bool {
+        frame.intersects(screen.visibleFrame.insetBy(dx: 12, dy: 12))
+    }
+
+    static func constrainFrame(_ frame: NSRect, toVisibleFrame bounds: NSRect) -> NSRect {
+        if bounds == .zero { return frame }
+
+        var next = frame
+        next.size.width = min(max(CanvasLayout.minPanelSize.width, next.size.width), bounds.width)
+        next.size.height = min(max(CanvasLayout.minPanelSize.height, next.size.height), bounds.height)
+
+        let maxX = bounds.maxX - next.size.width
+        let maxY = bounds.maxY - next.size.height
+
+        next.origin.x = maxX >= bounds.minX ? min(max(next.origin.x, bounds.minX), maxX) : bounds.minX
+        next.origin.y = maxY >= bounds.minY ? min(max(next.origin.y, bounds.minY), maxY) : bounds.minY
+
+        next.origin.x = round(next.origin.x)
+        next.origin.y = round(next.origin.y)
+        return next
+    }
+
+    // MARK: - NSWindowDelegate
+
+    func windowWillClose(_: Notification) {
+        self.onVisibilityChanged?(false)
+    }
+
+    func windowDidMove(_: Notification) {
+        self.persistFrameIfPanel()
+    }
+
+    func windowDidEndLiveResize(_: Notification) {
+        self.persistFrameIfPanel()
+    }
+
+    func persistFrameIfPanel() {
+        guard case .panel = self.presentation, let window else { return }
+        Self.storeRestoredFrame(window.frame, sessionKey: self.sessionKey)
+    }
+}

apps/macos/Sources/Clawdis/CanvasWindowController.swift

@@ -0,0 +1,361 @@
+import AppKit
+import ClawdisIPC
+import ClawdisKit
+import Foundation
+import WebKit
+
+@MainActor
+final class CanvasWindowController: NSWindowController, WKNavigationDelegate, NSWindowDelegate {
+    let sessionKey: String
+    private let root: URL
+    private let sessionDir: URL
+    private let schemeHandler: CanvasSchemeHandler
+    let webView: WKWebView
+    private var a2uiActionMessageHandler: CanvasA2UIActionMessageHandler?
+    private let watcher: CanvasFileWatcher
+    private let container: HoverChromeContainerView
+    let presentation: CanvasPresentation
+    var preferredPlacement: CanvasPlacement?
+    private(set) var currentTarget: String?
+    private var debugStatusEnabled = false
+    private var debugStatusTitle: String?
+    private var debugStatusSubtitle: String?
+
+    var onVisibilityChanged: ((Bool) -> Void)?
+
+    init(sessionKey: String, root: URL, presentation: CanvasPresentation) throws {
+        self.sessionKey = sessionKey
+        self.root = root
+        self.presentation = presentation
+
+        canvasWindowLogger.debug("CanvasWindowController init start session=\(sessionKey, privacy: .public)")
+        let safeSessionKey = CanvasWindowController.sanitizeSessionKey(sessionKey)
+        canvasWindowLogger.debug("CanvasWindowController init sanitized session=\(safeSessionKey, privacy: .public)")
+        self.sessionDir = root.appendingPathComponent(safeSessionKey, isDirectory: true)
+        try FileManager.default.createDirectory(at: self.sessionDir, withIntermediateDirectories: true)
+        canvasWindowLogger.debug("CanvasWindowController init session dir ready")
+
+        self.schemeHandler = CanvasSchemeHandler(root: root)
+        canvasWindowLogger.debug("CanvasWindowController init scheme handler ready")
+
+        let config = WKWebViewConfiguration()
+        config.userContentController = WKUserContentController()
+        config.preferences.isElementFullscreenEnabled = true
+        config.preferences.setValue(true, forKey: "developerExtrasEnabled")
+        canvasWindowLogger.debug("CanvasWindowController init config ready")
+        config.setURLSchemeHandler(self.schemeHandler, forURLScheme: CanvasScheme.scheme)
+        canvasWindowLogger.debug("CanvasWindowController init scheme handler installed")
+
+        // Bridge A2UI "a2uiaction" DOM events back into the native agent loop.
+        //
+        // Prefer WKScriptMessageHandler when WebKit exposes it, otherwise fall back to an unattended deep link
+        // (includes the app-generated key so it won't prompt).
+        canvasWindowLogger.debug("CanvasWindowController init building A2UI bridge script")
+        let deepLinkKey = DeepLinkHandler.currentCanvasKey()
+        let injectedSessionKey = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty ?? "main"
+        let bridgeScript = """
+        (() => {
+          try {
+            if (location.protocol !== '\(CanvasScheme.scheme):') return;
+            if (globalThis.__clawdisA2UIBridgeInstalled) return;
+            globalThis.__clawdisA2UIBridgeInstalled = true;
+
+            const deepLinkKey = \(Self.jsStringLiteral(deepLinkKey));
+            const sessionKey = \(Self.jsStringLiteral(injectedSessionKey));
+            const machineName = \(Self.jsStringLiteral(InstanceIdentity.displayName));
+            const instanceId = \(Self.jsStringLiteral(InstanceIdentity.instanceId));
+
+            globalThis.addEventListener('a2uiaction', (evt) => {
+              try {
+                const payload = evt?.detail ?? evt?.payload ?? null;
+                if (!payload || payload.eventType !== 'a2ui.action') return;
+
+                const action = payload.action ?? null;
+                const name = action?.name ?? '';
+                if (!name) return;
+
+                const context = Array.isArray(action?.context) ? action.context : [];
+                const userAction = {
+                  id: (globalThis.crypto?.randomUUID?.() ?? String(Date.now())),
+                  name,
+                  surfaceId: payload.surfaceId ?? 'main',
+                  sourceComponentId: payload.sourceComponentId ?? '',
+                  dataContextPath: payload.dataContextPath ?? '',
+                  timestamp: new Date().toISOString(),
+                  ...(context.length ? { context } : {}),
+                };
+
+                const handler = globalThis.webkit?.messageHandlers?.clawdisCanvasA2UIAction;
+
+                // If the bundled A2UI shell is present, let it forward actions so we keep its richer
+                // context resolution (data model path lookups, surface detection, etc.).
+                const hasBundledA2UIHost = !!globalThis.clawdisA2UI || !!document.querySelector('clawdis-a2ui-host');
+                if (hasBundledA2UIHost && handler?.postMessage) return;
+
+                // Otherwise, forward directly when possible.
+                if (!hasBundledA2UIHost && handler?.postMessage) {
+                  handler.postMessage({ userAction });
+                  return;
+                }
+
+                const ctx = userAction.context ? (' ctx=' + JSON.stringify(userAction.context)) : '';
+                const message =
+                  'CANVAS_A2UI action=' + userAction.name +
+                  ' session=' + sessionKey +
+                  ' surface=' + userAction.surfaceId +
+                  ' component=' + (userAction.sourceComponentId || '-') +
+                  ' host=' + machineName.replace(/\\s+/g, '_') +
+                  ' instance=' + instanceId +
+                  ctx +
+                  ' default=update_canvas';
+                const params = new URLSearchParams();
+                params.set('message', message);
+                params.set('sessionKey', sessionKey);
+                params.set('thinking', 'low');
+                params.set('deliver', 'false');
+                params.set('channel', 'last');
+                params.set('key', deepLinkKey);
+                location.href = 'clawdis://agent?' + params.toString();
+              } catch {}
+            }, true);
+          } catch {}
+        })();
+        """
+        config.userContentController.addUserScript(
+            WKUserScript(source: bridgeScript, injectionTime: .atDocumentStart, forMainFrameOnly: true))
+        canvasWindowLogger.debug("CanvasWindowController init A2UI bridge installed")
+
+        canvasWindowLogger.debug("CanvasWindowController init creating WKWebView")
+        self.webView = WKWebView(frame: .zero, configuration: config)
+        // Canvas scaffold is a fully self-contained HTML page; avoid relying on transparency underlays.
+        self.webView.setValue(true, forKey: "drawsBackground")
+
+        let sessionDir = self.sessionDir
+        let webView = self.webView
+        self.watcher = CanvasFileWatcher(url: sessionDir) { [weak webView] in
+            Task { @MainActor in
+                guard let webView else { return }
+
+                // Only auto-reload when we are showing local canvas content.
+                guard webView.url?.scheme == CanvasScheme.scheme else { return }
+
+                let path = webView.url?.path ?? ""
+                if path == "/" || path.isEmpty {
+                    let indexA = sessionDir.appendingPathComponent("index.html", isDirectory: false)
+                    let indexB = sessionDir.appendingPathComponent("index.htm", isDirectory: false)
+                    if !FileManager.default.fileExists(atPath: indexA.path),
+                       !FileManager.default.fileExists(atPath: indexB.path)
+                    {
+                        return
+                    }
+                }
+
+                webView.reload()
+            }
+        }
+
+        self.container = HoverChromeContainerView(containing: self.webView)
+        let window = Self.makeWindow(for: presentation, contentView: self.container)
+        canvasWindowLogger.debug("CanvasWindowController init makeWindow done")
+        super.init(window: window)
+
+        let handler = CanvasA2UIActionMessageHandler(sessionKey: sessionKey)
+        self.a2uiActionMessageHandler = handler
+        self.webView.configuration.userContentController.add(handler, name: CanvasA2UIActionMessageHandler.messageName)
+
+        self.webView.navigationDelegate = self
+        self.window?.delegate = self
+        self.container.onClose = { [weak self] in
+            self?.hideCanvas()
+        }
+
+        self.watcher.start()
+        canvasWindowLogger.debug("CanvasWindowController init done")
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
+
+    @MainActor deinit {
+        self.webView.configuration.userContentController
+            .removeScriptMessageHandler(forName: CanvasA2UIActionMessageHandler.messageName)
+        self.watcher.stop()
+    }
+
+    func applyPreferredPlacement(_ placement: CanvasPlacement?) {
+        self.preferredPlacement = placement
+    }
+
+    func showCanvas(path: String? = nil) {
+        if case let .panel(anchorProvider) = self.presentation {
+            self.presentAnchoredPanel(anchorProvider: anchorProvider)
+            if let path {
+                self.load(target: path)
+            }
+            return
+        }
+
+        self.showWindow(nil)
+        self.window?.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+        if let path {
+            self.load(target: path)
+        }
+        self.onVisibilityChanged?(true)
+    }
+
+    func hideCanvas() {
+        if case .panel = self.presentation {
+            self.persistFrameIfPanel()
+        }
+        self.window?.orderOut(nil)
+        self.onVisibilityChanged?(false)
+    }
+
+    func load(target: String) {
+        let trimmed = target.trimmingCharacters(in: .whitespacesAndNewlines)
+        self.currentTarget = trimmed
+
+        if let url = URL(string: trimmed), let scheme = url.scheme?.lowercased() {
+            if scheme == "https" || scheme == "http" {
+                canvasWindowLogger.debug("canvas load url \(url.absoluteString, privacy: .public)")
+                self.webView.load(URLRequest(url: url))
+                return
+            }
+            if scheme == "file" {
+                canvasWindowLogger.debug("canvas load file \(url.absoluteString, privacy: .public)")
+                self.loadFile(url)
+                return
+            }
+        }
+
+        // Convenience: absolute file paths resolve as local files when they exist.
+        // (Avoid treating Canvas routes like "/" as filesystem paths.)
+        if trimmed.hasPrefix("/") {
+            var isDir: ObjCBool = false
+            if FileManager.default.fileExists(atPath: trimmed, isDirectory: &isDir), !isDir.boolValue {
+                let url = URL(fileURLWithPath: trimmed)
+                canvasWindowLogger.debug("canvas load file \(url.absoluteString, privacy: .public)")
+                self.loadFile(url)
+                return
+            }
+        }
+
+        guard let url = CanvasScheme.makeURL(
+            session: CanvasWindowController.sanitizeSessionKey(self.sessionKey),
+            path: trimmed)
+        else {
+            canvasWindowLogger
+                .error(
+                    "invalid canvas url session=\(self.sessionKey, privacy: .public) path=\(trimmed, privacy: .public)")
+            return
+        }
+        canvasWindowLogger.debug("canvas load canvas \(url.absoluteString, privacy: .public)")
+        self.webView.load(URLRequest(url: url))
+    }
+
+    func updateDebugStatus(enabled: Bool, title: String?, subtitle: String?) {
+        self.debugStatusEnabled = enabled
+        self.debugStatusTitle = title
+        self.debugStatusSubtitle = subtitle
+        self.applyDebugStatusIfNeeded()
+    }
+
+    func applyDebugStatusIfNeeded() {
+        let enabled = self.debugStatusEnabled
+        let title = Self.jsOptionalStringLiteral(self.debugStatusTitle)
+        let subtitle = Self.jsOptionalStringLiteral(self.debugStatusSubtitle)
+        let js = """
+        (() => {
+          try {
+            const api = globalThis.__clawdis;
+            if (!api) return;
+            if (typeof api.setDebugStatusEnabled === 'function') {
+              api.setDebugStatusEnabled(\(enabled ? "true" : "false"));
+            }
+            if (!\(enabled ? "true" : "false")) return;
+            if (typeof api.setStatus === 'function') {
+              api.setStatus(\(title), \(subtitle));
+            }
+          } catch (_) {}
+        })();
+        """
+        self.webView.evaluateJavaScript(js) { _, _ in }
+    }
+
+    private func loadFile(_ url: URL) {
+        let fileURL = url.isFileURL ? url : URL(fileURLWithPath: url.path)
+        let accessDir = fileURL.deletingLastPathComponent()
+        self.webView.loadFileURL(fileURL, allowingReadAccessTo: accessDir)
+    }
+
+    func eval(javaScript: String) async throws -> String {
+        try await withCheckedThrowingContinuation { cont in
+            self.webView.evaluateJavaScript(javaScript) { result, error in
+                if let error {
+                    cont.resume(throwing: error)
+                    return
+                }
+                if let result {
+                    cont.resume(returning: String(describing: result))
+                } else {
+                    cont.resume(returning: "")
+                }
+            }
+        }
+    }
+
+    func snapshot(to outPath: String?) async throws -> String {
+        let image: NSImage = try await withCheckedThrowingContinuation { cont in
+            self.webView.takeSnapshot(with: nil) { image, error in
+                if let error {
+                    cont.resume(throwing: error)
+                    return
+                }
+                guard let image else {
+                    cont.resume(throwing: NSError(domain: "Canvas", code: 11, userInfo: [
+                        NSLocalizedDescriptionKey: "snapshot returned nil image",
+                    ]))
+                    return
+                }
+                cont.resume(returning: image)
+            }
+        }
+
+        guard let tiff = image.tiffRepresentation,
+              let rep = NSBitmapImageRep(data: tiff),
+              let png = rep.representation(using: .png, properties: [:])
+        else {
+            throw NSError(domain: "Canvas", code: 12, userInfo: [
+                NSLocalizedDescriptionKey: "failed to encode png",
+            ])
+        }
+
+        let path: String
+        if let outPath, !outPath.isEmpty {
+            path = outPath
+        } else {
+            let ts = Int(Date().timeIntervalSince1970)
+            path = "/tmp/clawdis-canvas-\(CanvasWindowController.sanitizeSessionKey(self.sessionKey))-\(ts).png"
+        }
+
+        try png.write(to: URL(fileURLWithPath: path), options: [.atomic])
+        return path
+    }
+
+    var directoryPath: String {
+        self.sessionDir.path
+    }
+
+    func shouldAutoNavigateToA2UI(lastAutoTarget: String?) -> Bool {
+        let trimmed = (self.currentTarget ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty || trimmed == "/" { return true }
+        if let lastAuto = lastAutoTarget?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !lastAuto.isEmpty,
+           trimmed == lastAuto
+        {
+            return true
+        }
+        return false
+    }
+}

apps/macos/Sources/Clawdis/ClawdisConfigFile.swift

@@ -30,6 +30,23 @@ enum ClawdisConfigFile {
         } catch {}
     }
 
+    static func loadGatewayDict() -> [String: Any] {
+        let root = self.loadDict()
+        return root["gateway"] as? [String: Any] ?? [:]
+    }
+
+    static func updateGatewayDict(_ mutate: (inout [String: Any]) -> Void) {
+        var root = self.loadDict()
+        var gateway = root["gateway"] as? [String: Any] ?? [:]
+        mutate(&gateway)
+        if gateway.isEmpty {
+            root.removeValue(forKey: "gateway")
+        } else {
+            root["gateway"] = gateway
+        }
+        self.saveDict(root)
+    }
+
     static func browserControlEnabled(defaultValue: Bool = true) -> Bool {
         let root = self.loadDict()
         let browser = root["browser"] as? [String: Any]
@@ -44,46 +61,22 @@ enum ClawdisConfigFile {
         self.saveDict(root)
     }
 
-    static func inboundWorkspace() -> String? {
+    static func agentWorkspace() -> String? {
         let root = self.loadDict()
-        let inbound = root["inbound"] as? [String: Any]
-        return inbound?["workspace"] as? String
+        let agent = root["agent"] as? [String: Any]
+        return agent?["workspace"] as? String
     }
 
-    static func setInboundWorkspace(_ workspace: String?) {
+    static func setAgentWorkspace(_ workspace: String?) {
         var root = self.loadDict()
-        var inbound = root["inbound"] as? [String: Any] ?? [:]
+        var agent = root["agent"] as? [String: Any] ?? [:]
         let trimmed = workspace?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
         if trimmed.isEmpty {
-            inbound.removeValue(forKey: "workspace")
+            agent.removeValue(forKey: "workspace")
         } else {
-            inbound["workspace"] = trimmed
-        }
-        root["inbound"] = inbound
-        self.saveDict(root)
-    }
-
-    static func loadIdentity() -> AgentIdentity? {
-        let root = self.loadDict()
-        guard let identity = root["identity"] as? [String: Any] else { return nil }
-        let name = identity["name"] as? String ?? ""
-        let theme = identity["theme"] as? String ?? ""
-        let emoji = identity["emoji"] as? String ?? ""
-        let result = AgentIdentity(name: name, theme: theme, emoji: emoji)
-        return result.isEmpty ? nil : result
-    }
-
-    static func setIdentity(_ identity: AgentIdentity?) {
-        var root = self.loadDict()
-        if let identity, !identity.isEmpty {
-            root["identity"] = [
-                "name": identity.name.trimmingCharacters(in: .whitespacesAndNewlines),
-                "theme": identity.theme.trimmingCharacters(in: .whitespacesAndNewlines),
-                "emoji": identity.emoji.trimmingCharacters(in: .whitespacesAndNewlines),
-            ]
-        } else {
-            root.removeValue(forKey: "identity")
+            agent["workspace"] = trimmed
         }
+        root["agent"] = agent
         self.saveDict(root)
     }
 }

apps/macos/Sources/Clawdis/CommandResolver.swift

@@ -1,215 +1,5 @@
-import AppKit
 import Foundation
 
-extension ProcessInfo {
-    var isPreview: Bool {
-        self.environment["XCODE_RUNNING_FOR_PREVIEWS"] == "1"
-    }
-
-    var isRunningTests: Bool {
-        // SwiftPM tests load one or more `.xctest` bundles. With Swift Testing, `Bundle.main` is not
-        // guaranteed to be the `.xctest` bundle, so check all loaded bundles.
-        if Bundle.allBundles.contains(where: { $0.bundleURL.pathExtension == "xctest" }) { return true }
-        if Bundle.main.bundleURL.pathExtension == "xctest" { return true }
-
-        // Backwards-compatible fallbacks for runners that still set XCTest env vars.
-        return self.environment["XCTestConfigurationFilePath"] != nil
-            || self.environment["XCTestBundlePath"] != nil
-            || self.environment["XCTestSessionIdentifier"] != nil
-    }
-}
-
-enum LaunchdManager {
-    private static func runLaunchctl(_ args: [String]) {
-        let process = Process()
-        process.launchPath = "/bin/launchctl"
-        process.arguments = args
-        try? process.run()
-    }
-
-    static func startClawdis() {
-        let userTarget = "gui/\(getuid())/\(launchdLabel)"
-        self.runLaunchctl(["kickstart", "-k", userTarget])
-    }
-
-    static func stopClawdis() {
-        let userTarget = "gui/\(getuid())/\(launchdLabel)"
-        self.runLaunchctl(["stop", userTarget])
-    }
-}
-
-enum LaunchAgentManager {
-    private static var plistURL: URL {
-        FileManager.default.homeDirectoryForCurrentUser
-            .appendingPathComponent("Library/LaunchAgents/com.steipete.clawdis.plist")
-    }
-
-    static func status() async -> Bool {
-        guard FileManager.default.fileExists(atPath: self.plistURL.path) else { return false }
-        let result = await self.runLaunchctl(["print", "gui/\(getuid())/\(launchdLabel)"])
-        return result == 0
-    }
-
-    static func set(enabled: Bool, bundlePath: String) async {
-        if enabled {
-            self.writePlist(bundlePath: bundlePath)
-            _ = await self.runLaunchctl(["bootout", "gui/\(getuid())/\(launchdLabel)"])
-            _ = await self.runLaunchctl(["bootstrap", "gui/\(getuid())", self.plistURL.path])
-            _ = await self.runLaunchctl(["kickstart", "-k", "gui/\(getuid())/\(launchdLabel)"])
-        } else {
-            // Disable autostart going forward but leave the current app running.
-            // bootout would terminate the launchd job immediately (and crash the app if launched via agent).
-            try? FileManager.default.removeItem(at: self.plistURL)
-        }
-    }
-
-    private static func writePlist(bundlePath: String) {
-        let plist = """
-        <?xml version="1.0" encoding="UTF-8"?>
-        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-        <plist version="1.0">
-        <dict>
-          <key>Label</key>
-          <string>com.steipete.clawdis</string>
-          <key>ProgramArguments</key>
-          <array>
-            <string>\(bundlePath)/Contents/MacOS/Clawdis</string>
-          </array>
-          <key>WorkingDirectory</key>
-          <string>\(FileManager.default.homeDirectoryForCurrentUser.path)</string>
-          <key>RunAtLoad</key>
-          <true/>
-          <key>KeepAlive</key>
-          <true/>
-          <key>EnvironmentVariables</key>
-          <dict>
-            <key>PATH</key>
-            <string>\(CommandResolver.preferredPaths().joined(separator: ":"))</string>
-          </dict>
-          <key>StandardOutPath</key>
-          <string>\(LogLocator.launchdLogPath)</string>
-          <key>StandardErrorPath</key>
-          <string>\(LogLocator.launchdLogPath)</string>
-        </dict>
-        </plist>
-        """
-        try? plist.write(to: self.plistURL, atomically: true, encoding: .utf8)
-    }
-
-    @discardableResult
-    private static func runLaunchctl(_ args: [String]) async -> Int32 {
-        await Task.detached(priority: .utility) { () -> Int32 in
-            let process = Process()
-            process.launchPath = "/bin/launchctl"
-            process.arguments = args
-            process.standardOutput = Pipe()
-            process.standardError = Pipe()
-            do {
-                try process.run()
-                process.waitUntilExit()
-                return process.terminationStatus
-            } catch {
-                return -1
-            }
-        }.value
-    }
-}
-
-// Human-friendly age string (e.g., "2m ago").
-func age(from date: Date, now: Date = .init()) -> String {
-    let seconds = max(0, Int(now.timeIntervalSince(date)))
-    let minutes = seconds / 60
-    let hours = minutes / 60
-    let days = hours / 24
-
-    if seconds < 60 { return "just now" }
-    if minutes == 1 { return "1 minute ago" }
-    if minutes < 60 { return "\(minutes)m ago" }
-    if hours == 1 { return "1 hour ago" }
-    if hours < 24 { return "\(hours)h ago" }
-    if days == 1 { return "yesterday" }
-    return "\(days)d ago"
-}
-
-@MainActor
-enum CLIInstaller {
-    static func installedLocation() -> String? {
-        let fm = FileManager.default
-
-        for basePath in cliHelperSearchPaths {
-            let candidate = URL(fileURLWithPath: basePath).appendingPathComponent("clawdis-mac").path
-            var isDirectory: ObjCBool = false
-
-            guard fm.fileExists(atPath: candidate, isDirectory: &isDirectory), !isDirectory.boolValue else {
-                continue
-            }
-
-            if fm.isExecutableFile(atPath: candidate) {
-                return candidate
-            }
-        }
-
-        return nil
-    }
-
-    static func isInstalled() -> Bool {
-        self.installedLocation() != nil
-    }
-
-    static func install(statusHandler: @escaping @Sendable (String) async -> Void) async {
-        let helper = Bundle.main.bundleURL.appendingPathComponent("Contents/MacOS/ClawdisCLI")
-        guard FileManager.default.isExecutableFile(atPath: helper.path) else {
-            await statusHandler("Helper missing in bundle; rebuild via scripts/package-mac-app.sh")
-            return
-        }
-
-        let targets = cliHelperSearchPaths.map { "\($0)/clawdis-mac" }
-        let result = await self.privilegedSymlink(source: helper.path, targets: targets)
-        await statusHandler(result)
-    }
-
-    private static func privilegedSymlink(source: String, targets: [String]) async -> String {
-        let escapedSource = self.shellEscape(source)
-        let targetList = targets.map(self.shellEscape).joined(separator: " ")
-        let cmds = [
-            "mkdir -p /usr/local/bin /opt/homebrew/bin",
-            targets.map { "ln -sf \(escapedSource) \($0)" }.joined(separator: "; "),
-        ].joined(separator: "; ")
-
-        let script = """
-        do shell script "\(cmds)" with administrator privileges
-        """
-
-        let proc = Process()
-        proc.executableURL = URL(fileURLWithPath: "/usr/bin/osascript")
-        proc.arguments = ["-e", script]
-
-        let pipe = Pipe()
-        proc.standardOutput = pipe
-        proc.standardError = pipe
-
-        do {
-            try proc.run()
-            proc.waitUntilExit()
-            let data = pipe.fileHandleForReading.readToEndSafely()
-            let output = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-            if proc.terminationStatus == 0 {
-                return output.isEmpty ? "CLI helper linked into \(targetList)" : output
-            }
-            if output.lowercased().contains("user canceled") {
-                return "Install canceled"
-            }
-            return "Failed to install CLI helper: \(output)"
-        } catch {
-            return "Failed to run installer: \(error.localizedDescription)"
-        }
-    }
-
-    private static func shellEscape(_ path: String) -> String {
-        "'" + path.replacingOccurrences(of: "'", with: "'\"'\"'") + "'"
-    }
-}
-
 enum CommandResolver {
     private static let projectRootDefaultsKey = "clawdis.gatewayProjectRootPath"
     private static let helperName = "clawdis"
@@ -432,25 +222,6 @@ enum CommandResolver {
         }
     }
 
-    static func clawdisMacCommand(
-        subcommand: String,
-        extraArgs: [String] = [],
-        defaults: UserDefaults = .standard) -> [String]
-    {
-        let settings = self.connectionSettings(defaults: defaults)
-        if settings.mode == .remote, let ssh = self.sshMacHelperCommand(
-            subcommand: subcommand,
-            extraArgs: extraArgs,
-            settings: settings)
-        {
-            return ssh
-        }
-        if let helper = self.findExecutable(named: "clawdis-mac") {
-            return [helper, subcommand] + extraArgs
-        }
-        return ["/usr/local/bin/clawdis-mac", subcommand] + extraArgs
-    }
-
     // Existing callers still refer to clawdisCommand; keep it as node alias.
     static func clawdisCommand(
         subcommand: String,
@@ -466,7 +237,12 @@ enum CommandResolver {
         guard !settings.target.isEmpty else { return nil }
         guard let parsed = self.parseSSHTarget(settings.target) else { return nil }
 
-        var args: [String] = ["-o", "BatchMode=yes", "-o", "IdentitiesOnly=yes"]
+        var args: [String] = [
+            "-o", "BatchMode=yes",
+            "-o", "IdentitiesOnly=yes",
+            "-o", "StrictHostKeyChecking=accept-new",
+            "-o", "UpdateHostKeys=yes",
+        ]
         if parsed.port > 0 { args.append(contentsOf: ["-p", String(parsed.port)]) }
         if !settings.identity.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
             args.append(contentsOf: ["-i", settings.identity])
@@ -474,7 +250,7 @@ enum CommandResolver {
         let userHost = parsed.user.map { "\($0)@\(parsed.host)" } ?? parsed.host
         args.append(userHost)
 
-        // Run the real clawdis CLI on the remote host; do not fall back to clawdis-mac.
+        // Run the real clawdis CLI on the remote host.
         let exportedPath = [
             "/opt/homebrew/bin",
             "/usr/local/bin",
@@ -487,6 +263,7 @@ enum CommandResolver {
         ].joined(separator: ":")
         let quotedArgs = ([subcommand] + extraArgs).map(self.shellQuote).joined(separator: " ")
         let userPRJ = settings.projectRoot.trimmingCharacters(in: .whitespacesAndNewlines)
+        let userCLI = settings.cliPath.trimmingCharacters(in: .whitespacesAndNewlines)
 
         let projectSection = if userPRJ.isEmpty {
             """
@@ -503,9 +280,31 @@ enum CommandResolver {
             """
         }
 
+        let cliSection = if userCLI.isEmpty {
+            ""
+        } else {
+            """
+            CLI_HINT=\(self.shellQuote(userCLI))
+            if [ -n "$CLI_HINT" ]; then
+              if [ -x "$CLI_HINT" ]; then
+                CLI="$CLI_HINT"
+                "$CLI_HINT" \(quotedArgs);
+                exit $?;
+              elif [ -f "$CLI_HINT" ]; then
+                if command -v node >/dev/null 2>&1; then
+                  CLI="node $CLI_HINT"
+                  node "$CLI_HINT" \(quotedArgs);
+                  exit $?;
+                fi
+              fi
+            fi
+            """
+        }
+
         let scriptBody = """
         PATH=\(exportedPath);
         CLI="";
+        \(cliSection)
         \(projectSection)
         if command -v clawdis >/dev/null 2>&1; then
           CLI="$(command -v clawdis)"
@@ -535,56 +334,33 @@ enum CommandResolver {
         return ["/usr/bin/ssh"] + args
     }
 
-    private static func sshMacHelperCommand(
-        subcommand: String,
-        extraArgs: [String],
-        settings: RemoteSettings) -> [String]?
-    {
-        guard !settings.target.isEmpty else { return nil }
-        guard let parsed = self.parseSSHTarget(settings.target) else { return nil }
-
-        var args: [String] = ["-o", "BatchMode=yes", "-o", "IdentitiesOnly=yes"]
-        if parsed.port > 0 { args.append(contentsOf: ["-p", String(parsed.port)]) }
-        if !settings.identity.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-            args.append(contentsOf: ["-i", settings.identity])
-        }
-        let userHost = parsed.user.map { "\($0)@\(parsed.host)" } ?? parsed.host
-        args.append(userHost)
-
-        let exportedPath = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"
-        let userPRJ = settings.projectRoot
-        let quotedArgs = ([subcommand] + extraArgs).map(self.shellQuote).joined(separator: " ")
-        let scriptBody = """
-        PATH=\(exportedPath);
-        PRJ=\(userPRJ.isEmpty ? "" : self.shellQuote(userPRJ))
-        DEFAULT_PRJ="$HOME/Projects/clawdis"
-        if [ -z "${PRJ:-}" ] && [ -d "$DEFAULT_PRJ" ]; then PRJ="$DEFAULT_PRJ"; fi
-        if [ -n "${PRJ:-}" ]; then cd "$PRJ" || { echo "Project root not found: $PRJ"; exit 127; }; fi
-        if ! command -v clawdis-mac >/dev/null 2>&1; then echo "clawdis-mac missing on remote host"; exit 127; fi;
-        clawdis-mac \(quotedArgs)
-        """
-        args.append(contentsOf: ["/bin/sh", "-c", scriptBody])
-        return ["/usr/bin/ssh"] + args
-    }
-
     struct RemoteSettings {
         let mode: AppState.ConnectionMode
         let target: String
         let identity: String
         let projectRoot: String
+        let cliPath: String
     }
 
     static func connectionSettings(defaults: UserDefaults = .standard) -> RemoteSettings {
-        let modeRaw = defaults.string(forKey: connectionModeKey) ?? "local"
-        let mode = AppState.ConnectionMode(rawValue: modeRaw) ?? .local
+        let modeRaw = defaults.string(forKey: connectionModeKey)
+        let mode: AppState.ConnectionMode
+        if let modeRaw {
+            mode = AppState.ConnectionMode(rawValue: modeRaw) ?? .local
+        } else {
+            let seen = defaults.bool(forKey: "clawdis.onboardingSeen")
+            mode = seen ? .local : .unconfigured
+        }
         let target = defaults.string(forKey: remoteTargetKey) ?? ""
         let identity = defaults.string(forKey: remoteIdentityKey) ?? ""
         let projectRoot = defaults.string(forKey: remoteProjectRootKey) ?? ""
+        let cliPath = defaults.string(forKey: remoteCliPathKey) ?? ""
         return RemoteSettings(
             mode: mode,
             target: self.sanitizedTarget(target),
             identity: identity,
-            projectRoot: projectRoot)
+            projectRoot: projectRoot,
+            cliPath: cliPath)
     }
 
     static var attachExistingGatewayOnly: Bool {

apps/macos/Sources/Clawdis/ConfigSettings.swift

@@ -17,6 +17,7 @@ struct ConfigSettings: View {
     @State private var models: [ModelChoice] = []
     @State private var modelsLoading = false
     @State private var modelError: String?
+    @State private var modelsSourceLabel: String?
     @AppStorage(modelCatalogPathKey) private var modelCatalogPath: String = ModelCatalogLoader.defaultPath
     @AppStorage(modelCatalogReloadKey) private var modelCatalogReloadBump: Int = 0
     @State private var allowAutosave = false
@@ -65,7 +66,7 @@ struct ConfigSettings: View {
     private var header: some View {
         Text("Clawdis CLI config")
             .font(.title3.weight(.semibold))
-        Text("Edit ~/.clawdis/clawdis.json (inbound.agent / inbound.session).")
+        Text("Edit ~/.clawdis/clawdis.json (agent / session / routing / messages).")
             .font(.callout)
             .foregroundStyle(.secondary)
     }
@@ -142,10 +143,16 @@ struct ConfigSettings: View {
                 .font(.footnote)
                 .foregroundStyle(.secondary)
         }
+
+        if let modelsSourceLabel {
+            Text("Model catalog: \(modelsSourceLabel)")
+                .font(.footnote)
+                .foregroundStyle(.secondary)
+        }
     }
 
     private var anthropicAuthHelpText: String {
-        "Determined from Pi OAuth token file (~/.pi/agent/oauth.json) " +
+        "Determined from Clawdis OAuth token file (~/.clawdis/credentials/oauth.json) " +
             "or environment variables (ANTHROPIC_OAUTH_TOKEN / ANTHROPIC_API_KEY)."
     }
 
@@ -267,11 +274,9 @@ struct ConfigSettings: View {
 
     private func loadConfig() {
         let parsed = self.loadConfigDict()
-        let inbound = parsed["inbound"] as? [String: Any]
-        let reply = inbound?["reply"] as? [String: Any]
-        let agent = reply?["agent"] as? [String: Any]
-        let heartbeatMinutes = reply?["heartbeatMinutes"] as? Int
-        let heartbeatBody = reply?["heartbeatBody"] as? String
+        let agent = parsed["agent"] as? [String: Any]
+        let heartbeatMinutes = agent?["heartbeatMinutes"] as? Int
+        let heartbeatBody = agent?["heartbeatBody"] as? String
         let browser = parsed["browser"] as? [String: Any]
 
         let loadedModel = (agent?["model"] as? String) ?? ""
@@ -305,9 +310,7 @@ struct ConfigSettings: View {
         defer { self.configSaving = false }
 
         var root = self.loadConfigDict()
-        var inbound = root["inbound"] as? [String: Any] ?? [:]
-        var reply = inbound["reply"] as? [String: Any] ?? [:]
-        var agent = reply["agent"] as? [String: Any] ?? [:]
+        var agent = root["agent"] as? [String: Any] ?? [:]
         var browser = root["browser"] as? [String: Any] ?? [:]
 
         let chosenModel = (self.configModel == "__custom__" ? self.customModel : self.configModel)
@@ -315,19 +318,16 @@ struct ConfigSettings: View {
         let trimmedModel = chosenModel
         if !trimmedModel.isEmpty { agent["model"] = trimmedModel }
 
-        reply["agent"] = agent
-
         if let heartbeatMinutes {
-            reply["heartbeatMinutes"] = heartbeatMinutes
+            agent["heartbeatMinutes"] = heartbeatMinutes
         }
 
         let trimmedBody = self.heartbeatBody.trimmingCharacters(in: .whitespacesAndNewlines)
         if !trimmedBody.isEmpty {
-            reply["heartbeatBody"] = trimmedBody
+            agent["heartbeatBody"] = trimmedBody
         }
 
-        inbound["reply"] = reply
-        root["inbound"] = inbound
+        root["agent"] = agent
 
         browser["enabled"] = self.browserEnabled
         let trimmedUrl = self.browserControlUrl.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -410,20 +410,44 @@ struct ConfigSettings: View {
         guard !self.modelsLoading else { return }
         self.modelsLoading = true
         self.modelError = nil
+        self.modelsSourceLabel = nil
         do {
-            let loaded = try await ModelCatalogLoader.load(from: self.modelCatalogPath)
-            self.models = loaded
-            if !self.configModel.isEmpty, !loaded.contains(where: { $0.id == self.configModel }) {
+            let res: ModelsListResult =
+                try await GatewayConnection.shared
+                    .requestDecoded(
+                        method: .modelsList,
+                        timeoutMs: 15000)
+            self.models = res.models
+            self.modelsSourceLabel = "gateway"
+            if !self.configModel.isEmpty,
+               !res.models.contains(where: { $0.id == self.configModel })
+            {
                 self.customModel = self.configModel
                 self.configModel = "__custom__"
             }
         } catch {
-            self.modelError = error.localizedDescription
-            self.models = []
+            do {
+                let loaded = try await ModelCatalogLoader.load(from: self.modelCatalogPath)
+                self.models = loaded
+                self.modelsSourceLabel = "local fallback"
+                if !self.configModel.isEmpty,
+                   !loaded.contains(where: { $0.id == self.configModel })
+                {
+                    self.customModel = self.configModel
+                    self.configModel = "__custom__"
+                }
+            } catch {
+                self.modelError = error.localizedDescription
+                self.models = []
+            }
         }
         self.modelsLoading = false
     }
 
+    private struct ModelsListResult: Decodable {
+        let models: [ModelChoice]
+    }
+
     private var selectedContextLabel: String? {
         let chosenId = (self.configModel == "__custom__") ? self.customModel : self.configModel
         guard

apps/macos/Sources/Clawdis/ConnectionModeCoordinator.swift

@@ -11,6 +11,14 @@ final class ConnectionModeCoordinator {
     /// managing the control-channel SSH tunnel, and cleaning up chat windows/panels.
     func apply(mode: AppState.ConnectionMode, paused: Bool) async {
         switch mode {
+        case .unconfigured:
+            await RemoteTunnelManager.shared.stopAll()
+            WebChatManager.shared.resetTunnels()
+            GatewayProcessManager.shared.stop()
+            await GatewayConnection.shared.shutdown()
+            await ControlChannel.shared.disconnect()
+            Task.detached { await PortGuardian.shared.sweep(mode: .unconfigured) }
+
         case .local:
             await RemoteTunnelManager.shared.stopAll()
             WebChatManager.shared.resetTunnels()
@@ -21,10 +29,18 @@ final class ConnectionModeCoordinator {
                 self.logger.error(
                     "control channel local configure failed: \(error.localizedDescription, privacy: .public)")
             }
-            if paused {
-                GatewayProcessManager.shared.stop()
-            } else {
+            let shouldStart = GatewayAutostartPolicy.shouldStartGateway(mode: .local, paused: paused)
+            if shouldStart {
                 GatewayProcessManager.shared.setActive(true)
+                if GatewayAutostartPolicy.shouldEnsureLaunchAgent(
+                    mode: .local,
+                    paused: paused,
+                    attachExistingOnly: AppStateStore.attachExistingGatewayOnly)
+                {
+                    Task { await GatewayProcessManager.shared.ensureLaunchAgentEnabledIfNeeded() }
+                }
+            } else {
+                GatewayProcessManager.shared.stop()
             }
             Task.detached { await PortGuardian.shared.sweep(mode: .local) }
 

apps/macos/Sources/Clawdis/ConnectionsSettings.swift

@@ -0,0 +1,500 @@
+import AppKit
+import SwiftUI
+
+struct ConnectionsSettings: View {
+    @Bindable var store: ConnectionsStore
+    @State private var showTelegramToken = false
+    @State private var showDiscordToken = false
+
+    init(store: ConnectionsStore = .shared) {
+        self.store = store
+    }
+
+    var body: some View {
+        ScrollView(.vertical) {
+            VStack(alignment: .leading, spacing: 14) {
+                self.header
+                self.whatsAppSection
+                self.telegramSection
+                self.discordSection
+                Spacer(minLength: 0)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(.horizontal, 24)
+            .padding(.vertical, 18)
+        }
+        .onAppear { self.store.start() }
+        .onDisappear { self.store.stop() }
+    }
+
+    private var header: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Text("Connections")
+                .font(.title3.weight(.semibold))
+            Text("Link and monitor WhatsApp, Telegram, and Discord providers.")
+                .font(.callout)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    private var whatsAppSection: some View {
+        GroupBox("WhatsApp") {
+            VStack(alignment: .leading, spacing: 10) {
+                self.providerHeader(
+                    title: "WhatsApp Web",
+                    color: self.whatsAppTint,
+                    subtitle: self.whatsAppSummary)
+
+                if let details = self.whatsAppDetails {
+                    Text(details)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                if let message = self.store.whatsappLoginMessage {
+                    Text(message)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                if let qr = self.store.whatsappLoginQrDataUrl, let image = self.qrImage(from: qr) {
+                    Image(nsImage: image)
+                        .resizable()
+                        .interpolation(.none)
+                        .frame(width: 180, height: 180)
+                        .cornerRadius(8)
+                }
+
+                HStack(spacing: 12) {
+                    Button {
+                        Task { await self.store.startWhatsAppLogin(force: false) }
+                    } label: {
+                        if self.store.whatsappBusy {
+                            ProgressView().controlSize(.small)
+                        } else {
+                            Text("Show QR")
+                        }
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(self.store.whatsappBusy)
+
+                    Button("Relink") {
+                        Task { await self.store.startWhatsAppLogin(force: true) }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.whatsappBusy)
+
+                    Spacer()
+
+                    Button("Logout") {
+                        Task { await self.store.logoutWhatsApp() }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.whatsappBusy)
+
+                    Button("Refresh") {
+                        Task { await self.store.refresh(probe: true) }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.isRefreshing)
+                }
+                .font(.caption)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    private var telegramSection: some View {
+        GroupBox("Telegram") {
+            VStack(alignment: .leading, spacing: 10) {
+                self.providerHeader(
+                    title: "Telegram Bot",
+                    color: self.telegramTint,
+                    subtitle: self.telegramSummary)
+
+                if let details = self.telegramDetails {
+                    Text(details)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                if let status = self.store.configStatus {
+                    Text(status)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                Divider().padding(.vertical, 2)
+
+                Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
+                    GridRow {
+                        self.gridLabel("Bot token")
+                        if self.showTelegramToken {
+                            TextField("123:abc", text: self.$store.telegramToken)
+                                .textFieldStyle(.roundedBorder)
+                                .disabled(self.isTelegramTokenLocked)
+                        } else {
+                            SecureField("123:abc", text: self.$store.telegramToken)
+                                .textFieldStyle(.roundedBorder)
+                                .disabled(self.isTelegramTokenLocked)
+                        }
+                        Toggle("Show", isOn: self.$showTelegramToken)
+                            .toggleStyle(.switch)
+                            .disabled(self.isTelegramTokenLocked)
+                    }
+                    GridRow {
+                        self.gridLabel("Require mention")
+                        Toggle("", isOn: self.$store.telegramRequireMention)
+                            .labelsHidden()
+                            .toggleStyle(.checkbox)
+                    }
+                    GridRow {
+                        self.gridLabel("Allow from")
+                        TextField("123456789, @team", text: self.$store.telegramAllowFrom)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Proxy")
+                        TextField("socks5://localhost:9050", text: self.$store.telegramProxy)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Webhook URL")
+                        TextField("https://example.com/telegram-webhook", text: self.$store.telegramWebhookUrl)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Webhook secret")
+                        TextField("secret", text: self.$store.telegramWebhookSecret)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Webhook path")
+                        TextField("/telegram-webhook", text: self.$store.telegramWebhookPath)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                }
+
+                if self.isTelegramTokenLocked {
+                    Text("Token set via TELEGRAM_BOT_TOKEN env; config edits won’t override it.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+
+                HStack(spacing: 12) {
+                    Button {
+                        Task { await self.store.saveTelegramConfig() }
+                    } label: {
+                        if self.store.isSavingConfig {
+                            ProgressView().controlSize(.small)
+                        } else {
+                            Text("Save")
+                        }
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(self.store.isSavingConfig)
+
+                    Spacer()
+
+                    Button("Logout") {
+                        Task { await self.store.logoutTelegram() }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.telegramBusy)
+
+                    Button("Refresh") {
+                        Task { await self.store.refresh(probe: true) }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.isRefreshing)
+                }
+                .font(.caption)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    private var discordSection: some View {
+        GroupBox("Discord") {
+            VStack(alignment: .leading, spacing: 10) {
+                self.providerHeader(
+                    title: "Discord Bot",
+                    color: self.discordTint,
+                    subtitle: self.discordSummary)
+
+                if let details = self.discordDetails {
+                    Text(details)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                if let status = self.store.configStatus {
+                    Text(status)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                Divider().padding(.vertical, 2)
+
+                Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
+                    GridRow {
+                        self.gridLabel("Bot token")
+                        if self.showDiscordToken {
+                            TextField("bot token", text: self.$store.discordToken)
+                                .textFieldStyle(.roundedBorder)
+                                .disabled(self.isDiscordTokenLocked)
+                        } else {
+                            SecureField("bot token", text: self.$store.discordToken)
+                                .textFieldStyle(.roundedBorder)
+                                .disabled(self.isDiscordTokenLocked)
+                        }
+                        Toggle("Show", isOn: self.$showDiscordToken)
+                            .toggleStyle(.switch)
+                            .disabled(self.isDiscordTokenLocked)
+                    }
+                    GridRow {
+                        self.gridLabel("Require mention")
+                        Toggle("", isOn: self.$store.discordRequireMention)
+                            .labelsHidden()
+                            .toggleStyle(.checkbox)
+                    }
+                    GridRow {
+                        self.gridLabel("Allow from")
+                        TextField("discord:123, user:456", text: self.$store.discordAllowFrom)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Allow guilds")
+                        TextField("guildId1, guildId2", text: self.$store.discordGuildAllowFrom)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Allow guild users")
+                        TextField("userId1, userId2", text: self.$store.discordGuildUsersAllowFrom)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Media max MB")
+                        TextField("8", text: self.$store.discordMediaMaxMb)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                }
+
+                if self.isDiscordTokenLocked {
+                    Text("Token set via DISCORD_BOT_TOKEN env; config edits won’t override it.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+
+                HStack(spacing: 12) {
+                    Button {
+                        Task { await self.store.saveDiscordConfig() }
+                    } label: {
+                        if self.store.isSavingConfig {
+                            ProgressView().controlSize(.small)
+                        } else {
+                            Text("Save")
+                        }
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(self.store.isSavingConfig)
+
+                    Spacer()
+
+                    Button("Refresh") {
+                        Task { await self.store.refresh(probe: true) }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.isRefreshing)
+                }
+                .font(.caption)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    private var whatsAppTint: Color {
+        guard let status = self.store.snapshot?.whatsapp else { return .secondary }
+        if !status.linked { return .red }
+        if status.connected { return .green }
+        if status.lastError != nil { return .orange }
+        return .green
+    }
+
+    private var telegramTint: Color {
+        guard let status = self.store.snapshot?.telegram else { return .secondary }
+        if !status.configured { return .secondary }
+        if status.running { return .green }
+        if status.lastError != nil { return .orange }
+        return .secondary
+    }
+
+    private var discordTint: Color {
+        guard let status = self.store.snapshot?.discord else { return .secondary }
+        if !status.configured { return .secondary }
+        if status.running { return .green }
+        if status.lastError != nil { return .orange }
+        return .secondary
+    }
+
+    private var whatsAppSummary: String {
+        guard let status = self.store.snapshot?.whatsapp else { return "Checking…" }
+        if !status.linked { return "Not linked" }
+        if status.connected { return "Connected" }
+        if status.running { return "Running" }
+        return "Linked"
+    }
+
+    private var telegramSummary: String {
+        guard let status = self.store.snapshot?.telegram else { return "Checking…" }
+        if !status.configured { return "Not configured" }
+        if status.running { return "Running" }
+        return "Configured"
+    }
+
+    private var discordSummary: String {
+        guard let status = self.store.snapshot?.discord else { return "Checking…" }
+        if !status.configured { return "Not configured" }
+        if status.running { return "Running" }
+        return "Configured"
+    }
+
+    private var whatsAppDetails: String? {
+        guard let status = self.store.snapshot?.whatsapp else { return nil }
+        var lines: [String] = []
+        if let e164 = status.`self`?.e164 ?? status.`self`?.jid {
+            lines.append("Linked as \(e164)")
+        }
+        if let age = status.authAgeMs {
+            lines.append("Auth age \(msToAge(age))")
+        }
+        if let last = self.date(fromMs: status.lastConnectedAt) {
+            lines.append("Last connect \(relativeAge(from: last))")
+        }
+        if let disconnect = status.lastDisconnect {
+            let when = self.date(fromMs: disconnect.at).map { relativeAge(from: $0) } ?? "unknown"
+            let code = disconnect.status.map { "status \($0)" } ?? "status unknown"
+            let err = disconnect.error ?? "disconnect"
+            lines.append("Last disconnect \(code) · \(err) · \(when)")
+        }
+        if status.reconnectAttempts > 0 {
+            lines.append("Reconnect attempts \(status.reconnectAttempts)")
+        }
+        if let msgAt = self.date(fromMs: status.lastMessageAt) {
+            lines.append("Last message \(relativeAge(from: msgAt))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    private var telegramDetails: String? {
+        guard let status = self.store.snapshot?.telegram else { return nil }
+        var lines: [String] = []
+        if let source = status.tokenSource {
+            lines.append("Token source: \(source)")
+        }
+        if let mode = status.mode {
+            lines.append("Mode: \(mode)")
+        }
+        if let probe = status.probe {
+            if probe.ok {
+                if let name = probe.bot?.username {
+                    lines.append("Bot: @\(name)")
+                }
+                if let url = probe.webhook?.url, !url.isEmpty {
+                    lines.append("Webhook: \(url)")
+                }
+            } else {
+                let code = probe.status.map { String($0) } ?? "unknown"
+                lines.append("Probe failed (\(code))")
+            }
+        }
+        if let last = self.date(fromMs: status.lastProbeAt) {
+            lines.append("Last probe \(relativeAge(from: last))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    private var discordDetails: String? {
+        guard let status = self.store.snapshot?.discord else { return nil }
+        var lines: [String] = []
+        if let source = status.tokenSource {
+            lines.append("Token source: \(source)")
+        }
+        if let probe = status.probe {
+            if probe.ok {
+                if let name = probe.bot?.username {
+                    lines.append("Bot: @\(name)")
+                }
+                if let elapsed = probe.elapsedMs {
+                    lines.append("Probe \(Int(elapsed))ms")
+                }
+            } else {
+                let code = probe.status.map { String($0) } ?? "unknown"
+                lines.append("Probe failed (\(code))")
+            }
+        }
+        if let last = self.date(fromMs: status.lastProbeAt) {
+            lines.append("Last probe \(relativeAge(from: last))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    private var isTelegramTokenLocked: Bool {
+        self.store.snapshot?.telegram.tokenSource == "env"
+    }
+
+    private var isDiscordTokenLocked: Bool {
+        self.store.snapshot?.discord?.tokenSource == "env"
+    }
+
+    private func providerHeader(title: String, color: Color, subtitle: String) -> some View {
+        HStack(spacing: 10) {
+            Circle()
+                .fill(color)
+                .frame(width: 10, height: 10)
+            VStack(alignment: .leading, spacing: 2) {
+                Text(title)
+                    .font(.headline)
+                Text(subtitle)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+            Spacer()
+        }
+    }
+
+    private func gridLabel(_ text: String) -> some View {
+        Text(text)
+            .font(.callout.weight(.semibold))
+            .frame(width: 120, alignment: .leading)
+    }
+
+    private func date(fromMs ms: Double?) -> Date? {
+        guard let ms else { return nil }
+        return Date(timeIntervalSince1970: ms / 1000)
+    }
+
+    private func qrImage(from dataUrl: String) -> NSImage? {
+        guard let comma = dataUrl.firstIndex(of: ",") else { return nil }
+        let header = dataUrl[..<comma]
+        guard header.contains("base64") else { return nil }
+        let base64 = dataUrl[dataUrl.index(after: comma)...]
+        guard let data = Data(base64Encoded: String(base64)) else { return nil }
+        return NSImage(data: data)
+    }
+}

apps/macos/Sources/Clawdis/ConnectionsStore.swift

@@ -0,0 +1,559 @@
+import ClawdisProtocol
+import Foundation
+import Observation
+
+struct ProvidersStatusSnapshot: Codable {
+    struct WhatsAppSelf: Codable {
+        let e164: String?
+        let jid: String?
+    }
+
+    struct WhatsAppDisconnect: Codable {
+        let at: Double
+        let status: Int?
+        let error: String?
+        let loggedOut: Bool?
+    }
+
+    struct WhatsAppStatus: Codable {
+        let configured: Bool
+        let linked: Bool
+        let authAgeMs: Double?
+        let `self`: WhatsAppSelf?
+        let running: Bool
+        let connected: Bool
+        let lastConnectedAt: Double?
+        let lastDisconnect: WhatsAppDisconnect?
+        let reconnectAttempts: Int
+        let lastMessageAt: Double?
+        let lastEventAt: Double?
+        let lastError: String?
+    }
+
+    struct TelegramBot: Codable {
+        let id: Int?
+        let username: String?
+    }
+
+    struct TelegramWebhook: Codable {
+        let url: String?
+        let hasCustomCert: Bool?
+    }
+
+    struct TelegramProbe: Codable {
+        let ok: Bool
+        let status: Int?
+        let error: String?
+        let elapsedMs: Double?
+        let bot: TelegramBot?
+        let webhook: TelegramWebhook?
+    }
+
+    struct TelegramStatus: Codable {
+        let configured: Bool
+        let tokenSource: String?
+        let running: Bool
+        let mode: String?
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastError: String?
+        let probe: TelegramProbe?
+        let lastProbeAt: Double?
+    }
+
+    struct DiscordBot: Codable {
+        let id: String?
+        let username: String?
+    }
+
+    struct DiscordProbe: Codable {
+        let ok: Bool
+        let status: Int?
+        let error: String?
+        let elapsedMs: Double?
+        let bot: DiscordBot?
+    }
+
+    struct DiscordStatus: Codable {
+        let configured: Bool
+        let tokenSource: String?
+        let running: Bool
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastError: String?
+        let probe: DiscordProbe?
+        let lastProbeAt: Double?
+    }
+
+    let ts: Double
+    let whatsapp: WhatsAppStatus
+    let telegram: TelegramStatus
+    let discord: DiscordStatus?
+}
+
+struct ConfigSnapshot: Codable {
+    struct Issue: Codable {
+        let path: String
+        let message: String
+    }
+
+    let path: String?
+    let exists: Bool?
+    let raw: String?
+    let parsed: AnyCodable?
+    let valid: Bool?
+    let config: [String: AnyCodable]?
+    let issues: [Issue]?
+}
+
+@MainActor
+@Observable
+final class ConnectionsStore {
+    static let shared = ConnectionsStore()
+
+    var snapshot: ProvidersStatusSnapshot?
+    var lastError: String?
+    var lastSuccess: Date?
+    var isRefreshing = false
+
+    var whatsappLoginMessage: String?
+    var whatsappLoginQrDataUrl: String?
+    var whatsappLoginConnected: Bool?
+    var whatsappBusy = false
+
+    var telegramToken: String = ""
+    var telegramRequireMention = true
+    var telegramAllowFrom: String = ""
+    var telegramProxy: String = ""
+    var telegramWebhookUrl: String = ""
+    var telegramWebhookSecret: String = ""
+    var telegramWebhookPath: String = ""
+    var telegramBusy = false
+    var discordToken: String = ""
+    var discordRequireMention = true
+    var discordAllowFrom: String = ""
+    var discordGuildAllowFrom: String = ""
+    var discordGuildUsersAllowFrom: String = ""
+    var discordMediaMaxMb: String = ""
+    var configStatus: String?
+    var isSavingConfig = false
+
+    private let interval: TimeInterval = 45
+    private let isPreview: Bool
+    private var pollTask: Task<Void, Never>?
+    private var configRoot: [String: Any] = [:]
+    private var configLoaded = false
+
+    init(isPreview: Bool = ProcessInfo.processInfo.isPreview) {
+        self.isPreview = isPreview
+    }
+
+    func start() {
+        guard !self.isPreview else { return }
+        guard self.pollTask == nil else { return }
+        self.pollTask = Task.detached { [weak self] in
+            guard let self else { return }
+            await self.refresh(probe: true)
+            await self.loadConfig()
+            while !Task.isCancelled {
+                try? await Task.sleep(nanoseconds: UInt64(self.interval * 1_000_000_000))
+                await self.refresh(probe: false)
+            }
+        }
+    }
+
+    func stop() {
+        self.pollTask?.cancel()
+        self.pollTask = nil
+    }
+
+    func refresh(probe: Bool) async {
+        guard !self.isRefreshing else { return }
+        self.isRefreshing = true
+        defer { self.isRefreshing = false }
+
+        do {
+            let params: [String: AnyCodable] = [
+                "probe": AnyCodable(probe),
+                "timeoutMs": AnyCodable(8000),
+            ]
+            let snap: ProvidersStatusSnapshot = try await GatewayConnection.shared.requestDecoded(
+                method: .providersStatus,
+                params: params,
+                timeoutMs: 12000)
+            self.snapshot = snap
+            self.lastSuccess = Date()
+            self.lastError = nil
+        } catch {
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    func startWhatsAppLogin(force: Bool, autoWait: Bool = true) async {
+        guard !self.whatsappBusy else { return }
+        self.whatsappBusy = true
+        defer { self.whatsappBusy = false }
+        var shouldAutoWait = false
+        do {
+            let params: [String: AnyCodable] = [
+                "force": AnyCodable(force),
+                "timeoutMs": AnyCodable(30000),
+            ]
+            let result: WhatsAppLoginStartResult = try await GatewayConnection.shared.requestDecoded(
+                method: .webLoginStart,
+                params: params,
+                timeoutMs: 35000)
+            self.whatsappLoginMessage = result.message
+            self.whatsappLoginQrDataUrl = result.qrDataUrl
+            self.whatsappLoginConnected = nil
+            shouldAutoWait = autoWait && result.qrDataUrl != nil
+        } catch {
+            self.whatsappLoginMessage = error.localizedDescription
+            self.whatsappLoginQrDataUrl = nil
+            self.whatsappLoginConnected = nil
+        }
+        await self.refresh(probe: true)
+        if shouldAutoWait {
+            Task { await self.waitWhatsAppLogin() }
+        }
+    }
+
+    func waitWhatsAppLogin(timeoutMs: Int = 120_000) async {
+        guard !self.whatsappBusy else { return }
+        self.whatsappBusy = true
+        defer { self.whatsappBusy = false }
+        do {
+            let params: [String: AnyCodable] = [
+                "timeoutMs": AnyCodable(timeoutMs),
+            ]
+            let result: WhatsAppLoginWaitResult = try await GatewayConnection.shared.requestDecoded(
+                method: .webLoginWait,
+                params: params,
+                timeoutMs: Double(timeoutMs) + 5000)
+            self.whatsappLoginMessage = result.message
+            self.whatsappLoginConnected = result.connected
+            if result.connected {
+                self.whatsappLoginQrDataUrl = nil
+            }
+        } catch {
+            self.whatsappLoginMessage = error.localizedDescription
+        }
+        await self.refresh(probe: true)
+    }
+
+    func logoutWhatsApp() async {
+        guard !self.whatsappBusy else { return }
+        self.whatsappBusy = true
+        defer { self.whatsappBusy = false }
+        do {
+            let result: WhatsAppLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .webLogout,
+                params: nil,
+                timeoutMs: 15000)
+            self.whatsappLoginMessage = result.cleared
+                ? "Logged out and cleared credentials."
+                : "No WhatsApp session found."
+            self.whatsappLoginQrDataUrl = nil
+        } catch {
+            self.whatsappLoginMessage = error.localizedDescription
+        }
+        await self.refresh(probe: true)
+    }
+
+    func logoutTelegram() async {
+        guard !self.telegramBusy else { return }
+        self.telegramBusy = true
+        defer { self.telegramBusy = false }
+        do {
+            let result: TelegramLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .telegramLogout,
+                params: nil,
+                timeoutMs: 15000)
+            if result.envToken == true {
+                self.configStatus = "Telegram token still set via env; config cleared."
+            } else {
+                self.configStatus = result.cleared
+                    ? "Telegram token cleared."
+                    : "No Telegram token configured."
+            }
+            await self.loadConfig()
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+        await self.refresh(probe: true)
+    }
+
+    func loadConfig() async {
+        do {
+            let snap: ConfigSnapshot = try await GatewayConnection.shared.requestDecoded(
+                method: .configGet,
+                params: nil,
+                timeoutMs: 10000)
+            self.configStatus = snap.valid == false
+                ? "Config invalid; fix it in ~/.clawdis/clawdis.json."
+                : nil
+            self.configRoot = snap.config?.mapValues { $0.foundationValue } ?? [:]
+            self.configLoaded = true
+            let telegram = snap.config?["telegram"]?.dictionaryValue
+            self.telegramToken = telegram?["botToken"]?.stringValue ?? ""
+            self.telegramRequireMention = telegram?["requireMention"]?.boolValue ?? true
+            if let allow = telegram?["allowFrom"]?.arrayValue {
+                let strings = allow.compactMap { entry -> String? in
+                    if let str = entry.stringValue { return str }
+                    if let intVal = entry.intValue { return String(intVal) }
+                    if let doubleVal = entry.doubleValue { return String(Int(doubleVal)) }
+                    return nil
+                }
+                self.telegramAllowFrom = strings.joined(separator: ", ")
+            } else {
+                self.telegramAllowFrom = ""
+            }
+            self.telegramProxy = telegram?["proxy"]?.stringValue ?? ""
+            self.telegramWebhookUrl = telegram?["webhookUrl"]?.stringValue ?? ""
+            self.telegramWebhookSecret = telegram?["webhookSecret"]?.stringValue ?? ""
+            self.telegramWebhookPath = telegram?["webhookPath"]?.stringValue ?? ""
+
+            let discord = snap.config?["discord"]?.dictionaryValue
+            self.discordToken = discord?["token"]?.stringValue ?? ""
+            self.discordRequireMention = discord?["requireMention"]?.boolValue ?? true
+            if let allow = discord?["allowFrom"]?.arrayValue {
+                let strings = allow.compactMap { entry -> String? in
+                    if let str = entry.stringValue { return str }
+                    if let intVal = entry.intValue { return String(intVal) }
+                    if let doubleVal = entry.doubleValue { return String(Int(doubleVal)) }
+                    return nil
+                }
+                self.discordAllowFrom = strings.joined(separator: ", ")
+            } else {
+                self.discordAllowFrom = ""
+            }
+            if let guildAllow = discord?["guildAllowFrom"]?.dictionaryValue {
+                if let guilds = guildAllow["guilds"]?.arrayValue {
+                    let strings = guilds.compactMap { entry -> String? in
+                        if let str = entry.stringValue { return str }
+                        if let intVal = entry.intValue { return String(intVal) }
+                        if let doubleVal = entry.doubleValue { return String(Int(doubleVal)) }
+                        return nil
+                    }
+                    self.discordGuildAllowFrom = strings.joined(separator: ", ")
+                } else {
+                    self.discordGuildAllowFrom = ""
+                }
+                if let users = guildAllow["users"]?.arrayValue {
+                    let strings = users.compactMap { entry -> String? in
+                        if let str = entry.stringValue { return str }
+                        if let intVal = entry.intValue { return String(intVal) }
+                        if let doubleVal = entry.doubleValue { return String(Int(doubleVal)) }
+                        return nil
+                    }
+                    self.discordGuildUsersAllowFrom = strings.joined(separator: ", ")
+                } else {
+                    self.discordGuildUsersAllowFrom = ""
+                }
+            } else {
+                self.discordGuildAllowFrom = ""
+                self.discordGuildUsersAllowFrom = ""
+            }
+            if let media = discord?["mediaMaxMb"]?.doubleValue ?? discord?["mediaMaxMb"]?.intValue.map(Double.init) {
+                self.discordMediaMaxMb = String(Int(media))
+            } else {
+                self.discordMediaMaxMb = ""
+            }
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+    }
+
+    func saveTelegramConfig() async {
+        guard !self.isSavingConfig else { return }
+        self.isSavingConfig = true
+        defer { self.isSavingConfig = false }
+        if !self.configLoaded {
+            await self.loadConfig()
+        }
+
+        var telegram: [String: Any] = (self.configRoot["telegram"] as? [String: Any]) ?? [:]
+        let token = self.telegramToken.trimmingCharacters(in: .whitespacesAndNewlines)
+        if token.isEmpty {
+            telegram.removeValue(forKey: "botToken")
+        } else {
+            telegram["botToken"] = token
+        }
+
+        if self.telegramRequireMention {
+            telegram["requireMention"] = true
+        } else {
+            telegram["requireMention"] = false
+        }
+
+        let allow = self.telegramAllowFrom
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        if allow.isEmpty {
+            telegram.removeValue(forKey: "allowFrom")
+        } else {
+            telegram["allowFrom"] = allow
+        }
+
+        let proxy = self.telegramProxy.trimmingCharacters(in: .whitespacesAndNewlines)
+        if proxy.isEmpty {
+            telegram.removeValue(forKey: "proxy")
+        } else {
+            telegram["proxy"] = proxy
+        }
+
+        let webhookUrl = self.telegramWebhookUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+        if webhookUrl.isEmpty {
+            telegram.removeValue(forKey: "webhookUrl")
+        } else {
+            telegram["webhookUrl"] = webhookUrl
+        }
+
+        let webhookSecret = self.telegramWebhookSecret.trimmingCharacters(in: .whitespacesAndNewlines)
+        if webhookSecret.isEmpty {
+            telegram.removeValue(forKey: "webhookSecret")
+        } else {
+            telegram["webhookSecret"] = webhookSecret
+        }
+
+        let webhookPath = self.telegramWebhookPath.trimmingCharacters(in: .whitespacesAndNewlines)
+        if webhookPath.isEmpty {
+            telegram.removeValue(forKey: "webhookPath")
+        } else {
+            telegram["webhookPath"] = webhookPath
+        }
+
+        if telegram.isEmpty {
+            self.configRoot.removeValue(forKey: "telegram")
+        } else {
+            self.configRoot["telegram"] = telegram
+        }
+
+        do {
+            let data = try JSONSerialization.data(
+                withJSONObject: self.configRoot,
+                options: [.prettyPrinted, .sortedKeys])
+            guard let raw = String(data: data, encoding: .utf8) else {
+                self.configStatus = "Failed to encode config."
+                return
+            }
+            let params: [String: AnyCodable] = ["raw": AnyCodable(raw)]
+            _ = try await GatewayConnection.shared.requestRaw(
+                method: .configSet,
+                params: params,
+                timeoutMs: 10000)
+            self.configStatus = "Saved to ~/.clawdis/clawdis.json."
+            await self.refresh(probe: true)
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+    }
+
+    func saveDiscordConfig() async {
+        guard !self.isSavingConfig else { return }
+        self.isSavingConfig = true
+        defer { self.isSavingConfig = false }
+        if !self.configLoaded {
+            await self.loadConfig()
+        }
+
+        var discord: [String: Any] = (self.configRoot["discord"] as? [String: Any]) ?? [:]
+        let token = self.discordToken.trimmingCharacters(in: .whitespacesAndNewlines)
+        if token.isEmpty {
+            discord.removeValue(forKey: "token")
+        } else {
+            discord["token"] = token
+        }
+
+        discord["requireMention"] = self.discordRequireMention
+
+        let allow = self.discordAllowFrom
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        if allow.isEmpty {
+            discord.removeValue(forKey: "allowFrom")
+        } else {
+            discord["allowFrom"] = allow
+        }
+
+        var guildAllow: [String: Any] = (discord["guildAllowFrom"] as? [String: Any]) ?? [:]
+        let guilds = self.discordGuildAllowFrom
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        if guilds.isEmpty {
+            guildAllow.removeValue(forKey: "guilds")
+        } else {
+            guildAllow["guilds"] = guilds
+        }
+
+        let users = self.discordGuildUsersAllowFrom
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        if users.isEmpty {
+            guildAllow.removeValue(forKey: "users")
+        } else {
+            guildAllow["users"] = users
+        }
+
+        if guildAllow.isEmpty {
+            discord.removeValue(forKey: "guildAllowFrom")
+        } else {
+            discord["guildAllowFrom"] = guildAllow
+        }
+
+        let media = self.discordMediaMaxMb.trimmingCharacters(in: .whitespacesAndNewlines)
+        if media.isEmpty {
+            discord.removeValue(forKey: "mediaMaxMb")
+        } else if let value = Double(media) {
+            discord["mediaMaxMb"] = value
+        }
+
+        if discord.isEmpty {
+            self.configRoot.removeValue(forKey: "discord")
+        } else {
+            self.configRoot["discord"] = discord
+        }
+
+        do {
+            let data = try JSONSerialization.data(
+                withJSONObject: self.configRoot,
+                options: [.prettyPrinted, .sortedKeys])
+            guard let raw = String(data: data, encoding: .utf8) else {
+                self.configStatus = "Failed to encode config."
+                return
+            }
+            let params: [String: AnyCodable] = ["raw": AnyCodable(raw)]
+            _ = try await GatewayConnection.shared.requestRaw(
+                method: .configSet,
+                params: params,
+                timeoutMs: 10000)
+            self.configStatus = "Saved to ~/.clawdis/clawdis.json."
+            await self.refresh(probe: true)
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+    }
+}
+
+private struct WhatsAppLoginStartResult: Codable {
+    let qrDataUrl: String?
+    let message: String
+}
+
+private struct WhatsAppLoginWaitResult: Codable {
+    let connected: Bool
+    let message: String
+}
+
+private struct WhatsAppLogoutResult: Codable {
+    let cleared: Bool
+}
+
+private struct TelegramLogoutResult: Codable {
+    let cleared: Bool
+    let envToken: Bool?
+}

apps/macos/Sources/Clawdis/Constants.swift

@@ -1,8 +1,9 @@
 import Foundation
 
 let launchdLabel = "com.steipete.clawdis"
+let gatewayLaunchdLabel = "com.steipete.clawdis.gateway"
 let onboardingVersionKey = "clawdis.onboardingVersion"
-let currentOnboardingVersion = 6
+let currentOnboardingVersion = 7
 let pauseDefaultsKey = "clawdis.pauseEnabled"
 let iconAnimationsEnabledKey = "clawdis.iconAnimationsEnabled"
 let swabbleEnabledKey = "clawdis.swabbleEnabled"
@@ -20,6 +21,7 @@ let connectionModeKey = "clawdis.connectionMode"
 let remoteTargetKey = "clawdis.remoteTarget"
 let remoteIdentityKey = "clawdis.remoteIdentity"
 let remoteProjectRootKey = "clawdis.remoteProjectRoot"
+let remoteCliPathKey = "clawdis.remoteCliPath"
 let canvasEnabledKey = "clawdis.canvasEnabled"
 let cameraEnabledKey = "clawdis.cameraEnabled"
 let peekabooBridgeEnabledKey = "clawdis.peekabooBridgeEnabled"

apps/macos/Sources/Clawdis/ContextUsageBar.swift

@@ -12,6 +12,16 @@ struct ContextUsageBar: View {
         if match == .darkAqua { return base }
         return base.blended(withFraction: 0.24, of: .black) ?? base
     }
+    private static let trackFill: NSColor = .init(name: nil) { appearance in
+        let match = appearance.bestMatch(from: [.aqua, .darkAqua])
+        if match == .darkAqua { return NSColor.white.withAlphaComponent(0.14) }
+        return NSColor.black.withAlphaComponent(0.12)
+    }
+    private static let trackStroke: NSColor = .init(name: nil) { appearance in
+        let match = appearance.bestMatch(from: [.aqua, .darkAqua])
+        if match == .darkAqua { return NSColor.white.withAlphaComponent(0.22) }
+        return NSColor.black.withAlphaComponent(0.2)
+    }
 
     private var clampedFractionUsed: Double {
         guard self.contextTokens > 0 else { return 0 }
@@ -58,8 +68,8 @@ struct ContextUsageBar: View {
     @ViewBuilder
     private func barBody(width: CGFloat, fraction: Double) -> some View {
         let radius = self.height / 2
-        let trackFill = Color.white.opacity(0.12)
-        let trackStroke = Color.white.opacity(0.18)
+        let trackFill = Color(nsColor: Self.trackFill)
+        let trackStroke = Color(nsColor: Self.trackStroke)
         let fillWidth = max(1, floor(width * CGFloat(fraction)))
 
         ZStack(alignment: .leading) {

apps/macos/Sources/Clawdis/ControlChannel.swift

@@ -92,6 +92,12 @@ final class ControlChannel {
         }
     }
 
+    func disconnect() async {
+        await GatewayConnection.shared.shutdown()
+        self.state = .disconnected
+        self.lastPingMs = nil
+    }
+
     func health(timeout: TimeInterval? = nil) async throws -> Data {
         do {
             let start = Date()
@@ -179,12 +185,19 @@ final class ControlChannel {
             case .cancelled:
                 return "Gateway connection was closed; start the gateway (localhost:\(port)) and retry."
             case .cannotFindHost, .cannotConnectToHost:
-                if AppStateStore.attachExistingGatewayOnly {
+                let isRemote = CommandResolver.connectionModeIsRemote()
+                if AppStateStore.attachExistingGatewayOnly, !isRemote {
                     return """
                     Cannot reach gateway at localhost:\(port) and “Attach existing gateway only” is enabled.
                     Disable it in Debug Settings or start a gateway on that port.
                     """
                 }
+                if isRemote {
+                    return """
+                    Cannot reach gateway at localhost:\(port).
+                    Remote mode uses an SSH tunnel—check the SSH target and that the tunnel is running.
+                    """
+                }
                 return "Cannot reach gateway at localhost:\(port); ensure the gateway is running."
             case .networkConnectionLost:
                 return "Gateway connection dropped; gateway likely restarted—retry."

apps/macos/Sources/Clawdis/ControlRequestHandler.swift

@@ -1,614 +0,0 @@
-import ClawdisIPC
-import ClawdisKit
-import Foundation
-import OSLog
-
-enum ControlRequestHandler {
-    struct NodeListNode: Codable {
-        var nodeId: String
-        var displayName: String?
-        var platform: String?
-        var version: String?
-        var deviceFamily: String?
-        var modelIdentifier: String?
-        var remoteAddress: String?
-        var connected: Bool
-        var paired: Bool
-        var capabilities: [String]?
-        var commands: [String]?
-    }
-
-    struct NodeListResult: Codable {
-        var ts: Int
-        var connectedNodeIds: [String]
-        var pairedNodeIds: [String]
-        var nodes: [NodeListNode]
-    }
-
-    struct GatewayNodeListPayload: Decodable {
-        struct Node: Decodable {
-            var nodeId: String
-            var displayName: String?
-            var platform: String?
-            var version: String?
-            var deviceFamily: String?
-            var modelIdentifier: String?
-            var remoteIp: String?
-            var connected: Bool?
-            var paired: Bool?
-            var caps: [String]?
-            var commands: [String]?
-        }
-
-        var ts: Int?
-        var nodes: [Node]
-    }
-
-    static func process(
-        request: Request,
-        notifier: NotificationManager = NotificationManager(),
-        logger: Logger = Logger(subsystem: "com.steipete.clawdis", category: "control")) async throws -> Response
-    {
-        // Keep `status` responsive even if the main actor is busy.
-        let paused = UserDefaults.standard.bool(forKey: pauseDefaultsKey)
-        if paused, case .status = request {
-            // allow status through
-        } else if paused {
-            return Response(ok: false, message: "clawdis paused")
-        }
-
-        switch request {
-        case let .notify(title, body, sound, priority, delivery):
-            let notify = NotifyRequest(
-                title: title,
-                body: body,
-                sound: sound,
-                priority: priority,
-                delivery: delivery)
-            return await self.handleNotify(notify, notifier: notifier)
-
-        case let .ensurePermissions(caps, interactive):
-            return await self.handleEnsurePermissions(caps: caps, interactive: interactive)
-
-        case .status:
-            return paused
-                ? Response(ok: false, message: "clawdis paused")
-                : Response(ok: true, message: "ready")
-
-        case .rpcStatus:
-            return await self.handleRPCStatus()
-
-        case let .runShell(command, cwd, env, timeoutSec, needsSR):
-            return await self.handleRunShell(
-                command: command,
-                cwd: cwd,
-                env: env,
-                timeoutSec: timeoutSec,
-                needsSR: needsSR)
-
-        case let .agent(message, thinking, session, deliver, to):
-            return await self.handleAgent(
-                message: message,
-                thinking: thinking,
-                session: session,
-                deliver: deliver,
-                to: to)
-
-        case let .canvasPresent(session, path, placement):
-            return await self.handleCanvasPresent(session: session, path: path, placement: placement)
-
-        case let .canvasHide(session):
-            return await self.handleCanvasHide(session: session)
-
-        case let .canvasEval(session, javaScript):
-            return await self.handleCanvasEval(session: session, javaScript: javaScript)
-
-        case let .canvasSnapshot(session, outPath):
-            return await self.handleCanvasSnapshot(session: session, outPath: outPath)
-
-        case let .canvasA2UI(session, command, jsonl):
-            return await self.handleCanvasA2UI(session: session, command: command, jsonl: jsonl)
-
-        case .nodeList:
-            return await self.handleNodeList()
-
-        case let .nodeDescribe(nodeId):
-            return await self.handleNodeDescribe(nodeId: nodeId)
-
-        case let .nodeInvoke(nodeId, command, paramsJSON):
-            return await self.handleNodeInvoke(
-                nodeId: nodeId,
-                command: command,
-                paramsJSON: paramsJSON,
-                logger: logger)
-
-        case let .cameraSnap(facing, maxWidth, quality, outPath):
-            return await self.handleCameraSnap(facing: facing, maxWidth: maxWidth, quality: quality, outPath: outPath)
-
-        case let .cameraClip(facing, durationMs, includeAudio, outPath):
-            return await self.handleCameraClip(
-                facing: facing,
-                durationMs: durationMs,
-                includeAudio: includeAudio,
-                outPath: outPath)
-
-        case let .screenRecord(screenIndex, durationMs, fps, includeAudio, outPath):
-            return await self.handleScreenRecord(
-                screenIndex: screenIndex,
-                durationMs: durationMs,
-                fps: fps,
-                includeAudio: includeAudio,
-                outPath: outPath)
-        }
-    }
-
-    private struct NotifyRequest {
-        var title: String
-        var body: String
-        var sound: String?
-        var priority: NotificationPriority?
-        var delivery: NotificationDelivery?
-    }
-
-    private static func handleNotify(_ request: NotifyRequest, notifier: NotificationManager) async -> Response {
-        let chosenSound = request.sound?.trimmingCharacters(in: .whitespacesAndNewlines)
-        let chosenDelivery = request.delivery ?? .system
-
-        switch chosenDelivery {
-        case .system:
-            let ok = await notifier.send(
-                title: request.title,
-                body: request.body,
-                sound: chosenSound,
-                priority: request.priority)
-            return ok ? Response(ok: true) : Response(ok: false, message: "notification not authorized")
-        case .overlay:
-            await NotifyOverlayController.shared.present(title: request.title, body: request.body)
-            return Response(ok: true)
-        case .auto:
-            let ok = await notifier.send(
-                title: request.title,
-                body: request.body,
-                sound: chosenSound,
-                priority: request.priority)
-            if ok { return Response(ok: true) }
-            await NotifyOverlayController.shared.present(title: request.title, body: request.body)
-            return Response(ok: true, message: "notification not authorized; used overlay")
-        }
-    }
-
-    private static func handleEnsurePermissions(caps: [Capability], interactive: Bool) async -> Response {
-        let statuses = await PermissionManager.ensure(caps, interactive: interactive)
-        let missing = statuses.filter { !$0.value }.map(\.key.rawValue)
-        let ok = missing.isEmpty
-        let msg = ok ? "all granted" : "missing: \(missing.joined(separator: ","))"
-        return Response(ok: ok, message: msg)
-    }
-
-    private static func handleRPCStatus() async -> Response {
-        let result = await GatewayConnection.shared.status()
-        return Response(ok: result.ok, message: result.error)
-    }
-
-    private static func handleRunShell(
-        command: [String],
-        cwd: String?,
-        env: [String: String]?,
-        timeoutSec: Double?,
-        needsSR: Bool) async -> Response
-    {
-        if needsSR {
-            let authorized = await PermissionManager
-                .ensure([.screenRecording], interactive: false)[.screenRecording] ?? false
-            guard authorized else { return Response(ok: false, message: "screen recording permission missing") }
-        }
-        return await ShellExecutor.run(command: command, cwd: cwd, env: env, timeout: timeoutSec)
-    }
-
-    private static func handleAgent(
-        message: String,
-        thinking: String?,
-        session: String?,
-        deliver: Bool,
-        to: String?) async -> Response
-    {
-        let trimmed = message.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else { return Response(ok: false, message: "message empty") }
-        let sessionKey = session ?? "main"
-        let invocation = GatewayAgentInvocation(
-            message: trimmed,
-            sessionKey: sessionKey,
-            thinking: thinking,
-            deliver: deliver,
-            to: to,
-            channel: .last)
-        let rpcResult = await GatewayConnection.shared.sendAgent(invocation)
-        return rpcResult.ok ? Response(ok: true, message: "sent") : Response(ok: false, message: rpcResult.error)
-    }
-
-    private static func canvasEnabled() -> Bool {
-        UserDefaults.standard.object(forKey: canvasEnabledKey) as? Bool ?? true
-    }
-
-    private static func cameraEnabled() -> Bool {
-        UserDefaults.standard.object(forKey: cameraEnabledKey) as? Bool ?? false
-    }
-
-    private static func handleCanvasPresent(
-        session: String,
-        path: String?,
-        placement: CanvasPlacement?) async -> Response
-    {
-        guard self.canvasEnabled() else { return Response(ok: false, message: "Canvas disabled by user") }
-        _ = session
-        do {
-            var params: [String: Any] = [:]
-            if let path, !path.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-                params["url"] = path
-            }
-            if let placement {
-                var placementPayload: [String: Any] = [:]
-                if let x = placement.x { placementPayload["x"] = x }
-                if let y = placement.y { placementPayload["y"] = y }
-                if let width = placement.width { placementPayload["width"] = width }
-                if let height = placement.height { placementPayload["height"] = height }
-                if !placementPayload.isEmpty {
-                    params["placement"] = placementPayload
-                }
-            }
-            _ = try await self.invokeLocalNode(
-                command: ClawdisCanvasCommand.present.rawValue,
-                params: params.isEmpty ? nil : params,
-                timeoutMs: 20000)
-            return Response(ok: true)
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func handleCanvasHide(session: String) async -> Response {
-        _ = session
-        do {
-            _ = try await self.invokeLocalNode(
-                command: ClawdisCanvasCommand.hide.rawValue,
-                params: nil,
-                timeoutMs: 10000)
-            return Response(ok: true)
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func handleCanvasEval(session: String, javaScript: String) async -> Response {
-        guard self.canvasEnabled() else { return Response(ok: false, message: "Canvas disabled by user") }
-        _ = session
-        do {
-            let payload = try await self.invokeLocalNode(
-                command: ClawdisCanvasCommand.evalJS.rawValue,
-                params: ["javaScript": javaScript],
-                timeoutMs: 20000)
-            if let dict = payload as? [String: Any],
-               let result = dict["result"] as? String
-            {
-                return Response(ok: true, payload: Data(result.utf8))
-            }
-            return Response(ok: true)
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func handleCanvasSnapshot(session: String, outPath: String?) async -> Response {
-        guard self.canvasEnabled() else { return Response(ok: false, message: "Canvas disabled by user") }
-        _ = session
-        do {
-            let payload = try await self.invokeLocalNode(
-                command: ClawdisCanvasCommand.snapshot.rawValue,
-                params: [:],
-                timeoutMs: 20000)
-            guard let dict = payload as? [String: Any],
-                  let format = dict["format"] as? String,
-                  let base64 = dict["base64"] as? String,
-                  let data = Data(base64Encoded: base64)
-            else {
-                return Response(ok: false, message: "invalid canvas snapshot payload")
-            }
-            let ext = (format.lowercased() == "jpeg" || format.lowercased() == "jpg") ? "jpg" : "png"
-            let url: URL = if let outPath, !outPath.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-                URL(fileURLWithPath: outPath)
-            } else {
-                FileManager.default.temporaryDirectory
-                    .appendingPathComponent("clawdis-canvas-snapshot-\(UUID().uuidString).\(ext)")
-            }
-            try data.write(to: url, options: [.atomic])
-            return Response(ok: true, message: url.path)
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func handleCanvasA2UI(
-        session: String,
-        command: CanvasA2UICommand,
-        jsonl: String?) async -> Response
-    {
-        guard self.canvasEnabled() else { return Response(ok: false, message: "Canvas disabled by user") }
-        _ = session
-        do {
-            switch command {
-            case .reset:
-                let payload = try await self.invokeLocalNode(
-                    command: ClawdisCanvasA2UICommand.reset.rawValue,
-                    params: nil,
-                    timeoutMs: 20000)
-                if let payload {
-                    let data = try JSONSerialization.data(withJSONObject: payload)
-                    return Response(ok: true, payload: data)
-                }
-                return Response(ok: true)
-            case .pushJSONL:
-                guard let jsonl, !jsonl.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
-                    return Response(ok: false, message: "missing jsonl")
-                }
-                let payload = try await self.invokeLocalNode(
-                    command: ClawdisCanvasA2UICommand.pushJSONL.rawValue,
-                    params: ["jsonl": jsonl],
-                    timeoutMs: 30000)
-                if let payload {
-                    let data = try JSONSerialization.data(withJSONObject: payload)
-                    return Response(ok: true, payload: data)
-                }
-                return Response(ok: true)
-            }
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func handleNodeList() async -> Response {
-        do {
-            let data = try await GatewayConnection.shared.request(
-                method: "node.list",
-                params: [:],
-                timeoutMs: 10000)
-            let payload = try JSONDecoder().decode(GatewayNodeListPayload.self, from: data)
-            let result = self.buildNodeListResult(payload: payload)
-
-            let encoder = JSONEncoder()
-            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-            let json = (try? encoder.encode(result))
-                .flatMap { String(data: $0, encoding: .utf8) } ?? "{}"
-            return Response(ok: true, payload: Data(json.utf8))
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func handleNodeDescribe(nodeId: String) async -> Response {
-        do {
-            let data = try await GatewayConnection.shared.request(
-                method: "node.describe",
-                params: ["nodeId": AnyCodable(nodeId)],
-                timeoutMs: 10000)
-            return Response(ok: true, payload: data)
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    static func buildNodeListResult(payload: GatewayNodeListPayload) -> NodeListResult {
-        let nodes = payload.nodes.map { n -> NodeListNode in
-            NodeListNode(
-                nodeId: n.nodeId,
-                displayName: n.displayName,
-                platform: n.platform,
-                version: n.version,
-                deviceFamily: n.deviceFamily,
-                modelIdentifier: n.modelIdentifier,
-                remoteAddress: n.remoteIp,
-                connected: n.connected == true,
-                paired: n.paired == true,
-                capabilities: n.caps,
-                commands: n.commands)
-        }
-
-        let sorted = nodes.sorted { a, b in
-            (a.displayName ?? a.nodeId) < (b.displayName ?? b.nodeId)
-        }
-
-        let pairedNodeIds = sorted.filter(\.paired).map(\.nodeId).sorted()
-        let connectedNodeIds = sorted.filter(\.connected).map(\.nodeId).sorted()
-
-        return NodeListResult(
-            ts: payload.ts ?? Int(Date().timeIntervalSince1970 * 1000),
-            connectedNodeIds: connectedNodeIds,
-            pairedNodeIds: pairedNodeIds,
-            nodes: sorted)
-    }
-
-    private static func handleNodeInvoke(
-        nodeId: String,
-        command: String,
-        paramsJSON: String?,
-        logger: Logger) async -> Response
-    {
-        do {
-            var paramsObj: Any? = nil
-            let raw = (paramsJSON ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
-            if !raw.isEmpty {
-                if let data = raw.data(using: .utf8) {
-                    paramsObj = try JSONSerialization.jsonObject(with: data)
-                } else {
-                    return Response(ok: false, message: "params-json not UTF-8")
-                }
-            }
-
-            var params: [String: AnyCodable] = [
-                "nodeId": AnyCodable(nodeId),
-                "command": AnyCodable(command),
-                "idempotencyKey": AnyCodable(UUID().uuidString),
-            ]
-            if let paramsObj {
-                params["params"] = AnyCodable(paramsObj)
-            }
-
-            let data = try await GatewayConnection.shared.request(
-                method: "node.invoke",
-                params: params,
-                timeoutMs: 30000)
-            return Response(ok: true, payload: data)
-        } catch {
-            logger.error("node invoke failed: \(error.localizedDescription, privacy: .public)")
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func handleCameraSnap(
-        facing: CameraFacing?,
-        maxWidth: Int?,
-        quality: Double?,
-        outPath: String?) async -> Response
-    {
-        guard self.cameraEnabled() else { return Response(ok: false, message: "Camera disabled by user") }
-        do {
-            var params: [String: Any] = [:]
-            if let facing { params["facing"] = facing.rawValue }
-            if let maxWidth { params["maxWidth"] = maxWidth }
-            if let quality { params["quality"] = quality }
-            params["format"] = "jpg"
-
-            let payload = try await self.invokeLocalNode(
-                command: ClawdisCameraCommand.snap.rawValue,
-                params: params,
-                timeoutMs: 30000)
-            guard let dict = payload as? [String: Any],
-                  let format = dict["format"] as? String,
-                  let base64 = dict["base64"] as? String,
-                  let data = Data(base64Encoded: base64)
-            else {
-                return Response(ok: false, message: "invalid camera snapshot payload")
-            }
-
-            let ext = (format.lowercased() == "jpeg" || format.lowercased() == "jpg") ? "jpg" : format.lowercased()
-            let url: URL = if let outPath, !outPath.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-                URL(fileURLWithPath: outPath)
-            } else {
-                FileManager.default.temporaryDirectory
-                    .appendingPathComponent("clawdis-camera-snap-\(UUID().uuidString).\(ext)")
-            }
-
-            try data.write(to: url, options: [.atomic])
-            return Response(ok: true, message: url.path)
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func handleCameraClip(
-        facing: CameraFacing?,
-        durationMs: Int?,
-        includeAudio: Bool,
-        outPath: String?) async -> Response
-    {
-        guard self.cameraEnabled() else { return Response(ok: false, message: "Camera disabled by user") }
-        do {
-            var params: [String: Any] = ["includeAudio": includeAudio, "format": "mp4"]
-            if let facing { params["facing"] = facing.rawValue }
-            if let durationMs { params["durationMs"] = durationMs }
-
-            let payload = try await self.invokeLocalNode(
-                command: ClawdisCameraCommand.clip.rawValue,
-                params: params,
-                timeoutMs: 90000)
-            guard let dict = payload as? [String: Any],
-                  let format = dict["format"] as? String,
-                  let base64 = dict["base64"] as? String,
-                  let data = Data(base64Encoded: base64)
-            else {
-                return Response(ok: false, message: "invalid camera clip payload")
-            }
-
-            let ext = format.lowercased()
-            let url: URL = if let outPath, !outPath.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-                URL(fileURLWithPath: outPath)
-            } else {
-                FileManager.default.temporaryDirectory
-                    .appendingPathComponent("clawdis-camera-clip-\(UUID().uuidString).\(ext)")
-            }
-            try data.write(to: url, options: [.atomic])
-            return Response(ok: true, message: url.path)
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func handleScreenRecord(
-        screenIndex: Int?,
-        durationMs: Int?,
-        fps: Double?,
-        includeAudio: Bool,
-        outPath: String?) async -> Response
-    {
-        do {
-            var params: [String: Any] = ["format": "mp4", "includeAudio": includeAudio]
-            if let screenIndex { params["screenIndex"] = screenIndex }
-            if let durationMs { params["durationMs"] = durationMs }
-            if let fps { params["fps"] = fps }
-
-            let payload = try await self.invokeLocalNode(
-                command: "screen.record",
-                params: params,
-                timeoutMs: 120_000)
-            guard let dict = payload as? [String: Any],
-                  let base64 = dict["base64"] as? String,
-                  let data = Data(base64Encoded: base64)
-            else {
-                return Response(ok: false, message: "invalid screen record payload")
-            }
-            let url: URL = if let outPath, !outPath.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-                URL(fileURLWithPath: outPath)
-            } else {
-                FileManager.default.temporaryDirectory
-                    .appendingPathComponent("clawdis-screen-record-\(UUID().uuidString).mp4")
-            }
-            try data.write(to: url, options: [.atomic])
-            return Response(ok: true, message: url.path)
-        } catch {
-            return Response(ok: false, message: error.localizedDescription)
-        }
-    }
-
-    private static func invokeLocalNode(
-        command: String,
-        params: [String: Any]?,
-        timeoutMs: Double) async throws -> Any?
-    {
-        var gatewayParams: [String: AnyCodable] = [
-            "nodeId": AnyCodable(Self.localNodeId()),
-            "command": AnyCodable(command),
-            "idempotencyKey": AnyCodable(UUID().uuidString),
-        ]
-        if let params {
-            gatewayParams["params"] = AnyCodable(params)
-        }
-        let data = try await GatewayConnection.shared.request(
-            method: "node.invoke",
-            params: gatewayParams,
-            timeoutMs: timeoutMs)
-        return try Self.decodeNodeInvokePayload(data: data)
-    }
-
-    private static func decodeNodeInvokePayload(data: Data) throws -> Any? {
-        let obj = try JSONSerialization.jsonObject(with: data)
-        guard let dict = obj as? [String: Any] else {
-            throw NSError(domain: "Node", code: 30, userInfo: [
-                NSLocalizedDescriptionKey: "invalid node invoke response",
-            ])
-        }
-        return dict["payload"]
-    }
-
-    private static func localNodeId() -> String {
-        "mac-\(InstanceIdentity.instanceId)"
-    }
-}

apps/macos/Sources/Clawdis/ControlSocketServer.swift

@@ -1,311 +0,0 @@
-import ClawdisIPC
-import Darwin
-import Foundation
-import OSLog
-
-/// Lightweight UNIX-domain socket server so `clawdis-mac` can talk to the app
-/// without a launchd MachService. Listens on `controlSocketPath`.
-final actor ControlSocketServer {
-    private nonisolated static let logger = Logger(subsystem: "com.steipete.clawdis", category: "control.socket")
-
-    private var listenFD: Int32 = -1
-    private var acceptTask: Task<Void, Never>?
-
-    private let socketPath: String
-    private let maxRequestBytes: Int
-    private let allowedTeamIDs: Set<String>
-    private let requestTimeoutSec: TimeInterval
-
-    init(
-        socketPath: String = controlSocketPath,
-        maxRequestBytes: Int = 512 * 1024,
-        allowedTeamIDs: Set<String> = ["Y5PE65HELJ"],
-        requestTimeoutSec: TimeInterval = 5)
-    {
-        self.socketPath = socketPath
-        self.maxRequestBytes = maxRequestBytes
-        self.allowedTeamIDs = allowedTeamIDs
-        self.requestTimeoutSec = requestTimeoutSec
-    }
-
-    private static func disableSigPipe(fd: Int32) {
-        var one: Int32 = 1
-        _ = setsockopt(fd, SOL_SOCKET, SO_NOSIGPIPE, &one, socklen_t(MemoryLayout.size(ofValue: one)))
-    }
-
-    func start() {
-        // Already running
-        guard self.listenFD == -1 else { return }
-
-        let path = self.socketPath
-        let fm = FileManager.default
-        // Ensure directory exists
-        let dir = (path as NSString).deletingLastPathComponent
-        try? fm.createDirectory(atPath: dir, withIntermediateDirectories: true)
-        // Remove stale socket
-        unlink(path)
-
-        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
-        guard fd >= 0 else { return }
-
-        var addr = sockaddr_un()
-        addr.sun_family = sa_family_t(AF_UNIX)
-        let capacity = MemoryLayout.size(ofValue: addr.sun_path)
-        let copied = path.withCString { cstr -> Int in
-            strlcpy(&addr.sun_path.0, cstr, capacity)
-        }
-        if copied >= capacity {
-            close(fd)
-            return
-        }
-        addr.sun_len = UInt8(MemoryLayout.size(ofValue: addr))
-        let len = socklen_t(MemoryLayout.size(ofValue: addr))
-        if bind(fd, withUnsafePointer(to: &addr) { UnsafePointer<sockaddr>(OpaquePointer($0)) }, len) != 0 {
-            close(fd)
-            return
-        }
-        // Restrict permissions: owner rw
-        chmod(path, S_IRUSR | S_IWUSR)
-        if listen(fd, SOMAXCONN) != 0 {
-            close(fd)
-            return
-        }
-
-        self.listenFD = fd
-
-        let allowedTeamIDs = self.allowedTeamIDs
-        let maxRequestBytes = self.maxRequestBytes
-        let requestTimeoutSec = self.requestTimeoutSec
-        self.acceptTask = Task.detached(priority: .utility) {
-            await Self.acceptLoop(
-                listenFD: fd,
-                allowedTeamIDs: allowedTeamIDs,
-                maxRequestBytes: maxRequestBytes,
-                requestTimeoutSec: requestTimeoutSec)
-        }
-    }
-
-    func stop() {
-        self.acceptTask?.cancel()
-        self.acceptTask = nil
-        if self.listenFD != -1 {
-            close(self.listenFD)
-            self.listenFD = -1
-        }
-        unlink(self.socketPath)
-    }
-
-    private nonisolated static func acceptLoop(
-        listenFD: Int32,
-        allowedTeamIDs: Set<String>,
-        maxRequestBytes: Int,
-        requestTimeoutSec: TimeInterval) async
-    {
-        while !Task.isCancelled {
-            var addr = sockaddr()
-            var len = socklen_t(MemoryLayout<sockaddr>.size)
-            let client = accept(listenFD, &addr, &len)
-            if client < 0 {
-                if errno == EINTR { continue }
-                // Socket was likely closed as part of stop().
-                if errno == EBADF || errno == EINVAL { return }
-                self.logger.error("accept failed: \(errno, privacy: .public)")
-                try? await Task.sleep(nanoseconds: 50_000_000)
-                continue
-            }
-
-            Self.disableSigPipe(fd: client)
-            Task.detached(priority: .utility) {
-                defer { close(client) }
-                await Self.handleClient(
-                    fd: client,
-                    allowedTeamIDs: allowedTeamIDs,
-                    maxRequestBytes: maxRequestBytes,
-                    requestTimeoutSec: requestTimeoutSec)
-            }
-        }
-    }
-
-    private nonisolated static func handleClient(
-        fd: Int32,
-        allowedTeamIDs: Set<String>,
-        maxRequestBytes: Int,
-        requestTimeoutSec: TimeInterval) async
-    {
-        guard self.isAllowed(fd: fd, allowedTeamIDs: allowedTeamIDs) else {
-            return
-        }
-
-        do {
-            guard let request = try self.readRequest(
-                fd: fd,
-                maxRequestBytes: maxRequestBytes,
-                timeoutSec: requestTimeoutSec)
-            else {
-                return
-            }
-
-            let response = try await ControlRequestHandler.process(request: request)
-            try self.writeResponse(fd: fd, response: response)
-        } catch {
-            self.logger.error("socket request failed: \(error.localizedDescription, privacy: .public)")
-            let resp = Response(ok: false, message: "socket error: \(error.localizedDescription)")
-            try? self.writeResponse(fd: fd, response: resp)
-        }
-    }
-
-    private nonisolated static func readRequest(
-        fd: Int32,
-        maxRequestBytes: Int,
-        timeoutSec: TimeInterval) throws -> Request?
-    {
-        let deadline = Date().addingTimeInterval(timeoutSec)
-        var data = Data()
-        var buffer = [UInt8](repeating: 0, count: 16 * 1024)
-        let bufferSize = buffer.count
-        let decoder = JSONDecoder()
-
-        while true {
-            let remaining = deadline.timeIntervalSinceNow
-            if remaining <= 0 {
-                throw POSIXError(.ETIMEDOUT)
-            }
-
-            var pfd = pollfd(fd: fd, events: Int16(POLLIN), revents: 0)
-            let sliceMs = max(1.0, min(remaining, 0.25) * 1000.0)
-            let polled = poll(&pfd, 1, Int32(sliceMs))
-            if polled == 0 { continue }
-            if polled < 0 {
-                if errno == EINTR { continue }
-                throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
-            }
-
-            let n = buffer.withUnsafeMutableBytes { read(fd, $0.baseAddress!, bufferSize) }
-            if n > 0 {
-                data.append(buffer, count: n)
-                if data.count > maxRequestBytes {
-                    throw POSIXError(.EMSGSIZE)
-                }
-                if let req = try? decoder.decode(Request.self, from: data) {
-                    return req
-                }
-                continue
-            }
-
-            if n == 0 {
-                return data.isEmpty ? nil : try decoder.decode(Request.self, from: data)
-            }
-
-            if errno == EINTR { continue }
-            if errno == EAGAIN { continue }
-            throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
-        }
-    }
-
-    private nonisolated static func writeResponse(fd: Int32, response: Response) throws {
-        let encoded = try JSONEncoder().encode(response)
-        try encoded.withUnsafeBytes { buf in
-            guard let base = buf.baseAddress else { return }
-            var written = 0
-            while written < encoded.count {
-                let n = write(fd, base.advanced(by: written), encoded.count - written)
-                if n > 0 {
-                    written += n
-                    continue
-                }
-                if n == -1, errno == EINTR { continue }
-                throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
-            }
-        }
-    }
-
-    private nonisolated static func isAllowed(fd: Int32, allowedTeamIDs: Set<String>) -> Bool {
-        var pid: pid_t = 0
-        var pidSize = socklen_t(MemoryLayout<pid_t>.size)
-        let r = getsockopt(fd, SOL_LOCAL, LOCAL_PEERPID, &pid, &pidSize)
-        guard r == 0, pid > 0 else { return false }
-
-        // Always require a valid code signature match (TeamID).
-        // This prevents any same-UID process from driving the app's privileged surface.
-        if self.teamIDMatches(pid: pid, allowedTeamIDs: allowedTeamIDs) {
-            return true
-        }
-
-        #if DEBUG
-        // Debug-only escape hatch: allow unsigned/same-UID clients when explicitly opted in.
-        // This keeps local development workable (e.g. a SwiftPM-built `clawdis-mac` binary).
-        let env = ProcessInfo.processInfo.environment["CLAWDIS_ALLOW_UNSIGNED_SOCKET_CLIENTS"]
-        if env == "1", let callerUID = self.uid(for: pid), callerUID == getuid() {
-            self.logger.warning(
-                "allowing unsigned same-UID socket client pid=\(pid) (CLAWDIS_ALLOW_UNSIGNED_SOCKET_CLIENTS=1)")
-            return true
-        }
-        #endif
-
-        if let callerUID = self.uid(for: pid) {
-            self.logger.error(
-                "socket client rejected pid=\(pid, privacy: .public) uid=\(callerUID, privacy: .public)")
-        } else {
-            self.logger.error("socket client rejected pid=\(pid, privacy: .public) (uid unknown)")
-        }
-        return false
-    }
-
-    private nonisolated static func uid(for pid: pid_t) -> uid_t? {
-        var info = kinfo_proc()
-        var size = MemoryLayout.size(ofValue: info)
-        var mib: [Int32] = [CTL_KERN, KERN_PROC, KERN_PROC_PID, pid]
-        let ok = mib.withUnsafeMutableBufferPointer { mibPtr -> Bool in
-            return sysctl(mibPtr.baseAddress, u_int(mibPtr.count), &info, &size, nil, 0) == 0
-        }
-        return ok ? info.kp_eproc.e_ucred.cr_uid : nil
-    }
-
-    private nonisolated static func teamIDMatches(pid: pid_t, allowedTeamIDs: Set<String>) -> Bool {
-        let attrs: NSDictionary = [kSecGuestAttributePid: pid]
-        var secCode: SecCode?
-        guard SecCodeCopyGuestWithAttributes(nil, attrs, SecCSFlags(), &secCode) == errSecSuccess,
-              let code = secCode else { return false }
-
-        var staticCode: SecStaticCode?
-        guard SecCodeCopyStaticCode(code, SecCSFlags(), &staticCode) == errSecSuccess,
-              let sCode = staticCode else { return false }
-
-        var infoCF: CFDictionary?
-        // `kSecCodeInfoTeamIdentifier` is only included when requesting signing information.
-        let flags = SecCSFlags(rawValue: UInt32(kSecCSSigningInformation))
-        guard SecCodeCopySigningInformation(sCode, flags, &infoCF) == errSecSuccess,
-              let info = infoCF as? [String: Any],
-              let teamID = info[kSecCodeInfoTeamIdentifier as String] as? String
-        else {
-            return false
-        }
-
-        return allowedTeamIDs.contains(teamID)
-    }
-}
-
-#if SWIFT_PACKAGE
-extension ControlSocketServer {
-    nonisolated static func _testTeamIdentifier(pid: pid_t) -> String? {
-        let attrs: NSDictionary = [kSecGuestAttributePid: pid]
-        var secCode: SecCode?
-        guard SecCodeCopyGuestWithAttributes(nil, attrs, SecCSFlags(), &secCode) == errSecSuccess,
-              let code = secCode else { return nil }
-
-        var staticCode: SecStaticCode?
-        guard SecCodeCopyStaticCode(code, SecCSFlags(), &staticCode) == errSecSuccess,
-              let sCode = staticCode else { return nil }
-
-        var infoCF: CFDictionary?
-        let flags = SecCSFlags(rawValue: UInt32(kSecCSSigningInformation))
-        guard SecCodeCopySigningInformation(sCode, flags, &infoCF) == errSecSuccess,
-              let info = infoCF as? [String: Any]
-        else {
-            return nil
-        }
-
-        return info[kSecCodeInfoTeamIdentifier as String] as? String
-    }
-}
-#endif

apps/macos/Sources/Clawdis/CritterIconRenderer.swift

@@ -0,0 +1,387 @@
+import AppKit
+
+enum CritterIconRenderer {
+    private static let size = NSSize(width: 18, height: 18)
+
+    struct Badge {
+        let symbolName: String
+        let prominence: IconState.BadgeProminence
+    }
+
+    private struct Canvas {
+        let w: CGFloat
+        let h: CGFloat
+        let stepX: CGFloat
+        let stepY: CGFloat
+        let snapX: (CGFloat) -> CGFloat
+        let snapY: (CGFloat) -> CGFloat
+        let context: CGContext
+    }
+
+    private struct Geometry {
+        let bodyRect: CGRect
+        let bodyCorner: CGFloat
+        let leftEarRect: CGRect
+        let rightEarRect: CGRect
+        let earCorner: CGFloat
+        let earW: CGFloat
+        let earH: CGFloat
+        let legW: CGFloat
+        let legH: CGFloat
+        let legSpacing: CGFloat
+        let legStartX: CGFloat
+        let legYBase: CGFloat
+        let legLift: CGFloat
+        let legHeightScale: CGFloat
+        let eyeW: CGFloat
+        let eyeY: CGFloat
+        let eyeOffset: CGFloat
+
+        init(canvas: Canvas, legWiggle: CGFloat, earWiggle: CGFloat, earScale: CGFloat) {
+            let w = canvas.w
+            let h = canvas.h
+            let snapX = canvas.snapX
+            let snapY = canvas.snapY
+
+            let bodyW = snapX(w * 0.78)
+            let bodyH = snapY(h * 0.58)
+            let bodyX = snapX((w - bodyW) / 2)
+            let bodyY = snapY(h * 0.36)
+            let bodyCorner = snapX(w * 0.09)
+
+            let earW = snapX(w * 0.22)
+            let earH = snapY(bodyH * 0.54 * earScale * (1 - 0.08 * abs(earWiggle)))
+            let earCorner = snapX(earW * 0.24)
+            let leftEarRect = CGRect(
+                x: snapX(bodyX - earW * 0.55 + earWiggle),
+                y: snapY(bodyY + bodyH * 0.08 + earWiggle * 0.4),
+                width: earW,
+                height: earH)
+            let rightEarRect = CGRect(
+                x: snapX(bodyX + bodyW - earW * 0.45 - earWiggle),
+                y: snapY(bodyY + bodyH * 0.08 - earWiggle * 0.4),
+                width: earW,
+                height: earH)
+
+            let legW = snapX(w * 0.11)
+            let legH = snapY(h * 0.26)
+            let legSpacing = snapX(w * 0.085)
+            let legsWidth = snapX(4 * legW + 3 * legSpacing)
+            let legStartX = snapX((w - legsWidth) / 2)
+            let legLift = snapY(legH * 0.35 * legWiggle)
+            let legYBase = snapY(bodyY - legH + h * 0.05)
+            let legHeightScale = 1 - 0.12 * legWiggle
+
+            let eyeW = snapX(bodyW * 0.2)
+            let eyeY = snapY(bodyY + bodyH * 0.56)
+            let eyeOffset = snapX(bodyW * 0.24)
+
+            self.bodyRect = CGRect(x: bodyX, y: bodyY, width: bodyW, height: bodyH)
+            self.bodyCorner = bodyCorner
+            self.leftEarRect = leftEarRect
+            self.rightEarRect = rightEarRect
+            self.earCorner = earCorner
+            self.earW = earW
+            self.earH = earH
+            self.legW = legW
+            self.legH = legH
+            self.legSpacing = legSpacing
+            self.legStartX = legStartX
+            self.legYBase = legYBase
+            self.legLift = legLift
+            self.legHeightScale = legHeightScale
+            self.eyeW = eyeW
+            self.eyeY = eyeY
+            self.eyeOffset = eyeOffset
+        }
+    }
+
+    private struct FaceOptions {
+        let blink: CGFloat
+        let earHoles: Bool
+        let earScale: CGFloat
+        let eyesClosedLines: Bool
+    }
+
+    static func makeIcon(
+        blink: CGFloat,
+        legWiggle: CGFloat = 0,
+        earWiggle: CGFloat = 0,
+        earScale: CGFloat = 1,
+        earHoles: Bool = false,
+        eyesClosedLines: Bool = false,
+        badge: Badge? = nil) -> NSImage
+    {
+        guard let rep = self.makeBitmapRep() else {
+            return NSImage(size: self.size)
+        }
+        rep.size = self.size
+
+        NSGraphicsContext.saveGraphicsState()
+        defer { NSGraphicsContext.restoreGraphicsState() }
+
+        guard let context = NSGraphicsContext(bitmapImageRep: rep) else {
+            return NSImage(size: self.size)
+        }
+        NSGraphicsContext.current = context
+        context.imageInterpolation = .none
+        context.cgContext.setShouldAntialias(false)
+
+        let canvas = self.makeCanvas(for: rep, context: context)
+        let geometry = Geometry(canvas: canvas, legWiggle: legWiggle, earWiggle: earWiggle, earScale: earScale)
+
+        self.drawBody(in: canvas, geometry: geometry)
+        let face = FaceOptions(
+            blink: blink,
+            earHoles: earHoles,
+            earScale: earScale,
+            eyesClosedLines: eyesClosedLines)
+        self.drawFace(in: canvas, geometry: geometry, options: face)
+
+        if let badge {
+            self.drawBadge(badge, canvas: canvas)
+        }
+
+        let image = NSImage(size: size)
+        image.addRepresentation(rep)
+        image.isTemplate = true
+        return image
+    }
+
+    private static func makeBitmapRep() -> NSBitmapImageRep? {
+        // Force a 36×36px backing store (2× for the 18pt logical canvas) so the menu bar icon stays crisp on Retina.
+        let pixelsWide = 36
+        let pixelsHigh = 36
+        return NSBitmapImageRep(
+            bitmapDataPlanes: nil,
+            pixelsWide: pixelsWide,
+            pixelsHigh: pixelsHigh,
+            bitsPerSample: 8,
+            samplesPerPixel: 4,
+            hasAlpha: true,
+            isPlanar: false,
+            colorSpaceName: .deviceRGB,
+            bitmapFormat: [],
+            bytesPerRow: 0,
+            bitsPerPixel: 0)
+    }
+
+    private static func makeCanvas(for rep: NSBitmapImageRep, context: NSGraphicsContext) -> Canvas {
+        let stepX = self.size.width / max(CGFloat(rep.pixelsWide), 1)
+        let stepY = self.size.height / max(CGFloat(rep.pixelsHigh), 1)
+        let snapX: (CGFloat) -> CGFloat = { ($0 / stepX).rounded() * stepX }
+        let snapY: (CGFloat) -> CGFloat = { ($0 / stepY).rounded() * stepY }
+
+        let w = snapX(size.width)
+        let h = snapY(size.height)
+
+        return Canvas(
+            w: w,
+            h: h,
+            stepX: stepX,
+            stepY: stepY,
+            snapX: snapX,
+            snapY: snapY,
+            context: context.cgContext)
+    }
+
+    private static func drawBody(in canvas: Canvas, geometry: Geometry) {
+        canvas.context.setFillColor(NSColor.labelColor.cgColor)
+
+        canvas.context.addPath(CGPath(
+            roundedRect: geometry.bodyRect,
+            cornerWidth: geometry.bodyCorner,
+            cornerHeight: geometry.bodyCorner,
+            transform: nil))
+        canvas.context.addPath(CGPath(
+            roundedRect: geometry.leftEarRect,
+            cornerWidth: geometry.earCorner,
+            cornerHeight: geometry.earCorner,
+            transform: nil))
+        canvas.context.addPath(CGPath(
+            roundedRect: geometry.rightEarRect,
+            cornerWidth: geometry.earCorner,
+            cornerHeight: geometry.earCorner,
+            transform: nil))
+
+        for i in 0..<4 {
+            let x = geometry.legStartX + CGFloat(i) * (geometry.legW + geometry.legSpacing)
+            let lift = i % 2 == 0 ? geometry.legLift : -geometry.legLift
+            let rect = CGRect(
+                x: x,
+                y: geometry.legYBase + lift,
+                width: geometry.legW,
+                height: geometry.legH * geometry.legHeightScale)
+            canvas.context.addPath(CGPath(
+                roundedRect: rect,
+                cornerWidth: geometry.legW * 0.34,
+                cornerHeight: geometry.legW * 0.34,
+                transform: nil))
+        }
+        canvas.context.fillPath()
+    }
+
+    private static func drawFace(
+        in canvas: Canvas,
+        geometry: Geometry,
+        options: FaceOptions)
+    {
+        canvas.context.saveGState()
+        canvas.context.setBlendMode(.clear)
+
+        let leftCenter = CGPoint(
+            x: canvas.snapX(canvas.w / 2 - geometry.eyeOffset),
+            y: canvas.snapY(geometry.eyeY))
+        let rightCenter = CGPoint(
+            x: canvas.snapX(canvas.w / 2 + geometry.eyeOffset),
+            y: canvas.snapY(geometry.eyeY))
+
+        if options.earHoles || options.earScale > 1.05 {
+            let holeW = canvas.snapX(geometry.earW * 0.6)
+            let holeH = canvas.snapY(geometry.earH * 0.46)
+            let holeCorner = canvas.snapX(holeW * 0.34)
+            let leftHoleRect = CGRect(
+                x: canvas.snapX(geometry.leftEarRect.midX - holeW / 2),
+                y: canvas.snapY(geometry.leftEarRect.midY - holeH / 2 + geometry.earH * 0.04),
+                width: holeW,
+                height: holeH)
+            let rightHoleRect = CGRect(
+                x: canvas.snapX(geometry.rightEarRect.midX - holeW / 2),
+                y: canvas.snapY(geometry.rightEarRect.midY - holeH / 2 + geometry.earH * 0.04),
+                width: holeW,
+                height: holeH)
+
+            canvas.context.addPath(CGPath(
+                roundedRect: leftHoleRect,
+                cornerWidth: holeCorner,
+                cornerHeight: holeCorner,
+                transform: nil))
+            canvas.context.addPath(CGPath(
+                roundedRect: rightHoleRect,
+                cornerWidth: holeCorner,
+                cornerHeight: holeCorner,
+                transform: nil))
+        }
+
+        if options.eyesClosedLines {
+            let lineW = canvas.snapX(geometry.eyeW * 0.95)
+            let lineH = canvas.snapY(max(canvas.stepY * 2, geometry.bodyRect.height * 0.06))
+            let corner = canvas.snapX(lineH * 0.6)
+            let leftRect = CGRect(
+                x: canvas.snapX(leftCenter.x - lineW / 2),
+                y: canvas.snapY(leftCenter.y - lineH / 2),
+                width: lineW,
+                height: lineH)
+            let rightRect = CGRect(
+                x: canvas.snapX(rightCenter.x - lineW / 2),
+                y: canvas.snapY(rightCenter.y - lineH / 2),
+                width: lineW,
+                height: lineH)
+            canvas.context.addPath(CGPath(
+                roundedRect: leftRect,
+                cornerWidth: corner,
+                cornerHeight: corner,
+                transform: nil))
+            canvas.context.addPath(CGPath(
+                roundedRect: rightRect,
+                cornerWidth: corner,
+                cornerHeight: corner,
+                transform: nil))
+        } else {
+            let eyeOpen = max(0.05, 1 - options.blink)
+            let eyeH = canvas.snapY(geometry.bodyRect.height * 0.26 * eyeOpen)
+
+            let left = CGMutablePath()
+            left.move(to: CGPoint(
+                x: canvas.snapX(leftCenter.x - geometry.eyeW / 2),
+                y: canvas.snapY(leftCenter.y - eyeH)))
+            left.addLine(to: CGPoint(
+                x: canvas.snapX(leftCenter.x + geometry.eyeW / 2),
+                y: canvas.snapY(leftCenter.y)))
+            left.addLine(to: CGPoint(
+                x: canvas.snapX(leftCenter.x - geometry.eyeW / 2),
+                y: canvas.snapY(leftCenter.y + eyeH)))
+            left.closeSubpath()
+
+            let right = CGMutablePath()
+            right.move(to: CGPoint(
+                x: canvas.snapX(rightCenter.x + geometry.eyeW / 2),
+                y: canvas.snapY(rightCenter.y - eyeH)))
+            right.addLine(to: CGPoint(
+                x: canvas.snapX(rightCenter.x - geometry.eyeW / 2),
+                y: canvas.snapY(rightCenter.y)))
+            right.addLine(to: CGPoint(
+                x: canvas.snapX(rightCenter.x + geometry.eyeW / 2),
+                y: canvas.snapY(rightCenter.y + eyeH)))
+            right.closeSubpath()
+
+            canvas.context.addPath(left)
+            canvas.context.addPath(right)
+        }
+
+        canvas.context.fillPath()
+        canvas.context.restoreGState()
+    }
+
+    private static func drawBadge(_ badge: Badge, canvas: Canvas) {
+        let strength: CGFloat = switch badge.prominence {
+        case .primary: 1.0
+        case .secondary: 0.58
+        case .overridden: 0.85
+        }
+
+        // Bigger, higher-contrast badge:
+        // - Increase diameter so tool activity is noticeable.
+        // - Draw a filled "puck", then knock out the symbol shape (transparent hole).
+        //   This reads better in template-rendered menu bar icons than tiny monochrome glyphs.
+        let diameter = canvas.snapX(canvas.w * 0.52 * (0.92 + 0.08 * strength)) // ~9–10pt on an 18pt canvas
+        let margin = canvas.snapX(max(0.45, canvas.w * 0.03))
+        let rect = CGRect(
+            x: canvas.snapX(canvas.w - diameter - margin),
+            y: canvas.snapY(margin),
+            width: diameter,
+            height: diameter)
+
+        canvas.context.saveGState()
+        canvas.context.setShouldAntialias(true)
+
+        // Clear the underlying pixels so the badge stays readable over the critter.
+        canvas.context.saveGState()
+        canvas.context.setBlendMode(.clear)
+        canvas.context.addEllipse(in: rect.insetBy(dx: -1.0, dy: -1.0))
+        canvas.context.fillPath()
+        canvas.context.restoreGState()
+
+        let fillAlpha: CGFloat = min(1.0, 0.36 + 0.24 * strength)
+        let strokeAlpha: CGFloat = min(1.0, 0.78 + 0.22 * strength)
+
+        canvas.context.setFillColor(NSColor.labelColor.withAlphaComponent(fillAlpha).cgColor)
+        canvas.context.addEllipse(in: rect)
+        canvas.context.fillPath()
+
+        canvas.context.setStrokeColor(NSColor.labelColor.withAlphaComponent(strokeAlpha).cgColor)
+        canvas.context.setLineWidth(max(1.25, canvas.snapX(canvas.w * 0.075)))
+        canvas.context.strokeEllipse(in: rect.insetBy(dx: 0.45, dy: 0.45))
+
+        if let base = NSImage(systemSymbolName: badge.symbolName, accessibilityDescription: nil) {
+            let pointSize = max(7.0, diameter * 0.82)
+            let config = NSImage.SymbolConfiguration(pointSize: pointSize, weight: .black)
+            let symbol = base.withSymbolConfiguration(config) ?? base
+            symbol.isTemplate = true
+
+            let symbolRect = rect.insetBy(dx: diameter * 0.17, dy: diameter * 0.17)
+            canvas.context.saveGState()
+            canvas.context.setBlendMode(.clear)
+            symbol.draw(
+                in: symbolRect,
+                from: .zero,
+                operation: .sourceOver,
+                fraction: 1,
+                respectFlipped: true,
+                hints: nil)
+            canvas.context.restoreGState()
+        }
+
+        canvas.context.restoreGState()
+    }
+}

apps/macos/Sources/Clawdis/CritterStatusLabel+Behavior.swift

@@ -0,0 +1,305 @@
+import AppKit
+import SwiftUI
+
+extension CritterStatusLabel {
+    private var isWorkingNow: Bool {
+        self.iconState.isWorking || self.isWorking
+    }
+
+    private var effectiveAnimationsEnabled: Bool {
+        self.animationsEnabled && !self.isSleeping
+    }
+
+    var body: some View {
+        ZStack(alignment: .topTrailing) {
+            self.iconImage
+                .frame(width: 18, height: 18)
+                .rotationEffect(.degrees(self.wiggleAngle), anchor: .center)
+                .offset(x: self.wiggleOffset)
+                // Avoid Combine's TimerPublisher here: on macOS 26.2 we've seen crashes inside executor checks
+                // triggered by its callbacks. Drive periodic updates via a Swift-concurrency task instead.
+                .task(id: self.tickTaskID) {
+                    guard self.effectiveAnimationsEnabled, !self.earBoostActive else {
+                        await MainActor.run { self.resetMotion() }
+                        return
+                    }
+
+                    while !Task.isCancelled {
+                        let now = Date()
+                        await MainActor.run { self.tick(now) }
+                        try? await Task.sleep(nanoseconds: 350_000_000)
+                    }
+                }
+                .onChange(of: self.isPaused) { _, _ in self.resetMotion() }
+                .onChange(of: self.blinkTick) { _, _ in
+                    guard self.effectiveAnimationsEnabled, !self.earBoostActive else { return }
+                    self.blink()
+                }
+                .onChange(of: self.sendCelebrationTick) { _, _ in
+                    guard self.effectiveAnimationsEnabled, !self.earBoostActive else { return }
+                    self.wiggleLegs()
+                }
+                .onChange(of: self.animationsEnabled) { _, enabled in
+                    if enabled, !self.isSleeping {
+                        self.scheduleRandomTimers(from: Date())
+                    } else {
+                        self.resetMotion()
+                    }
+                }
+                .onChange(of: self.isSleeping) { _, _ in
+                    self.resetMotion()
+                }
+                .onChange(of: self.earBoostActive) { _, active in
+                    if active {
+                        self.resetMotion()
+                    } else if self.effectiveAnimationsEnabled {
+                        self.scheduleRandomTimers(from: Date())
+                    }
+                }
+
+            if self.gatewayNeedsAttention {
+                Circle()
+                    .fill(self.gatewayBadgeColor)
+                    .frame(width: 6, height: 6)
+                    .padding(1)
+            }
+        }
+        .frame(width: 18, height: 18)
+    }
+
+    private var tickTaskID: Int {
+        // Ensure SwiftUI restarts (and cancels) the task when these change.
+        (self.effectiveAnimationsEnabled ? 1 : 0) | (self.earBoostActive ? 2 : 0)
+    }
+
+    private func tick(_ now: Date) {
+        guard self.effectiveAnimationsEnabled, !self.earBoostActive else {
+            self.resetMotion()
+            return
+        }
+
+        if now >= self.nextBlink {
+            self.blink()
+            self.nextBlink = now.addingTimeInterval(Double.random(in: 3.5...8.5))
+        }
+
+        if now >= self.nextWiggle {
+            self.wiggle()
+            self.nextWiggle = now.addingTimeInterval(Double.random(in: 6.5...14))
+        }
+
+        if now >= self.nextLegWiggle {
+            self.wiggleLegs()
+            self.nextLegWiggle = now.addingTimeInterval(Double.random(in: 5.0...11.0))
+        }
+
+        if now >= self.nextEarWiggle {
+            self.wiggleEars()
+            self.nextEarWiggle = now.addingTimeInterval(Double.random(in: 7.0...14.0))
+        }
+
+        if self.isWorkingNow {
+            self.scurry()
+        }
+    }
+
+    private var iconImage: Image {
+        let badge: CritterIconRenderer.Badge? = if let prominence = self.iconState.badgeProminence, !self.isPaused {
+            CritterIconRenderer.Badge(
+                symbolName: self.iconState.badgeSymbolName,
+                prominence: prominence)
+        } else {
+            nil
+        }
+
+        if self.isPaused {
+            return Image(nsImage: CritterIconRenderer.makeIcon(blink: 0, badge: nil))
+        }
+
+        if self.isSleeping {
+            return Image(nsImage: CritterIconRenderer.makeIcon(blink: 1, eyesClosedLines: true, badge: nil))
+        }
+
+        return Image(nsImage: CritterIconRenderer.makeIcon(
+            blink: self.blinkAmount,
+            legWiggle: max(self.legWiggle, self.isWorkingNow ? 0.6 : 0),
+            earWiggle: self.earWiggle,
+            earScale: self.earBoostActive ? 1.9 : 1.0,
+            earHoles: self.earBoostActive,
+            badge: badge))
+    }
+
+    private func resetMotion() {
+        self.blinkAmount = 0
+        self.wiggleAngle = 0
+        self.wiggleOffset = 0
+        self.legWiggle = 0
+        self.earWiggle = 0
+    }
+
+    private func blink() {
+        withAnimation(.easeInOut(duration: 0.08)) { self.blinkAmount = 1 }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 160_000_000)
+            withAnimation(.easeOut(duration: 0.12)) { self.blinkAmount = 0 }
+        }
+    }
+
+    private func wiggle() {
+        let targetAngle = Double.random(in: -4.5...4.5)
+        let targetOffset = CGFloat.random(in: -0.5...0.5)
+        withAnimation(.interpolatingSpring(stiffness: 220, damping: 18)) {
+            self.wiggleAngle = targetAngle
+            self.wiggleOffset = targetOffset
+        }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 360_000_000)
+            withAnimation(.interpolatingSpring(stiffness: 220, damping: 18)) {
+                self.wiggleAngle = 0
+                self.wiggleOffset = 0
+            }
+        }
+    }
+
+    private func wiggleLegs() {
+        let target = CGFloat.random(in: 0.35...0.9)
+        withAnimation(.easeInOut(duration: 0.14)) {
+            self.legWiggle = target
+        }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 220_000_000)
+            withAnimation(.easeOut(duration: 0.18)) { self.legWiggle = 0 }
+        }
+    }
+
+    private func scurry() {
+        let target = CGFloat.random(in: 0.7...1.0)
+        withAnimation(.easeInOut(duration: 0.12)) {
+            self.legWiggle = target
+            self.wiggleOffset = CGFloat.random(in: -0.6...0.6)
+        }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 180_000_000)
+            withAnimation(.easeOut(duration: 0.16)) {
+                self.legWiggle = 0.25
+                self.wiggleOffset = 0
+            }
+        }
+    }
+
+    private func wiggleEars() {
+        let target = CGFloat.random(in: -1.2...1.2)
+        withAnimation(.interpolatingSpring(stiffness: 260, damping: 19)) {
+            self.earWiggle = target
+        }
+        Task { @MainActor in
+            try? await Task.sleep(nanoseconds: 320_000_000)
+            withAnimation(.interpolatingSpring(stiffness: 260, damping: 19)) {
+                self.earWiggle = 0
+            }
+        }
+    }
+
+    private func scheduleRandomTimers(from date: Date) {
+        self.nextBlink = date.addingTimeInterval(Double.random(in: 3.5...8.5))
+        self.nextWiggle = date.addingTimeInterval(Double.random(in: 6.5...14))
+        self.nextLegWiggle = date.addingTimeInterval(Double.random(in: 5.0...11.0))
+        self.nextEarWiggle = date.addingTimeInterval(Double.random(in: 7.0...14.0))
+    }
+
+    private var gatewayNeedsAttention: Bool {
+        if self.isSleeping { return false }
+        switch self.gatewayStatus {
+        case .failed, .stopped:
+            return !self.isPaused
+        case .starting, .running, .attachedExisting:
+            return false
+        }
+    }
+
+    private var gatewayBadgeColor: Color {
+        switch self.gatewayStatus {
+        case .failed: .red
+        case .stopped: .orange
+        default: .clear
+        }
+    }
+}
+
+#if DEBUG
+@MainActor
+extension CritterStatusLabel {
+    static func exerciseForTesting() async {
+        var label = CritterStatusLabel(
+            isPaused: false,
+            isSleeping: false,
+            isWorking: true,
+            earBoostActive: false,
+            blinkTick: 1,
+            sendCelebrationTick: 1,
+            gatewayStatus: .running(details: nil),
+            animationsEnabled: true,
+            iconState: .workingMain(.tool(.bash)))
+
+        _ = label.body
+        _ = label.iconImage
+        _ = label.tickTaskID
+        label.tick(Date())
+        label.resetMotion()
+        label.blink()
+        label.wiggle()
+        label.wiggleLegs()
+        label.wiggleEars()
+        label.scurry()
+        label.scheduleRandomTimers(from: Date())
+        _ = label.gatewayNeedsAttention
+        _ = label.gatewayBadgeColor
+
+        label.isPaused = true
+        _ = label.iconImage
+
+        label.isPaused = false
+        label.isSleeping = true
+        _ = label.iconImage
+
+        label.isSleeping = false
+        label.iconState = .idle
+        _ = label.iconImage
+
+        let failed = CritterStatusLabel(
+            isPaused: false,
+            isSleeping: false,
+            isWorking: false,
+            earBoostActive: false,
+            blinkTick: 0,
+            sendCelebrationTick: 0,
+            gatewayStatus: .failed("boom"),
+            animationsEnabled: false,
+            iconState: .idle)
+        _ = failed.gatewayNeedsAttention
+        _ = failed.gatewayBadgeColor
+
+        let stopped = CritterStatusLabel(
+            isPaused: false,
+            isSleeping: false,
+            isWorking: false,
+            earBoostActive: false,
+            blinkTick: 0,
+            sendCelebrationTick: 0,
+            gatewayStatus: .stopped,
+            animationsEnabled: false,
+            iconState: .idle)
+        _ = stopped.gatewayNeedsAttention
+        _ = stopped.gatewayBadgeColor
+
+        _ = CritterIconRenderer.makeIcon(
+            blink: 0.6,
+            legWiggle: 0.8,
+            earWiggle: 0.4,
+            earScale: 1.4,
+            earHoles: true,
+            eyesClosedLines: true,
+            badge: .init(symbolName: "gearshape.fill", prominence: .secondary))
+    }
+}
+#endif