clawdbot 2026.1.4-1

package/docs/mac/canvas.md

@@ -0,0 +1,161 @@
+---
+summary: "Agent-controlled Canvas panel embedded via WKWebView + custom URL scheme"
+read_when:
+  - Implementing the macOS Canvas panel
+  - Adding agent controls for visual workspace
+  - Debugging WKWebView canvas loads
+---
+
+# Canvas (macOS app)
+
+Status: draft spec · Date: 2025-12-12
+
+Note: for iOS/Android nodes that should render agent-edited HTML/CSS/JS over the network, prefer the Gateway `canvasHost` (serves `~/clawd/canvas` over LAN/tailnet with live reload). A2UI is also **hosted by the Gateway** over HTTP. This doc focuses on the macOS in-app canvas panel. See `docs/configuration.md`.
+
+Clawdbot can embed an agent-controlled “visual workspace” panel (“Canvas”) inside the macOS app using `WKWebView`, served via a **custom URL scheme** (no loopback HTTP port required).
+
+This is designed for:
+- Agent-written HTML/CSS/JS on disk (per-session directory).
+- A real browser engine for layout, rendering, and basic interactivity.
+- Agent-driven visibility (show/hide), navigation, DOM/JS queries, and snapshots.
+- Minimal chrome: borderless panel; bezel/chrome appears only on hover.
+
+## Why a custom scheme (vs. loopback HTTP)
+
+Using `WKURLSchemeHandler` keeps Canvas entirely in-process:
+- No port conflicts and no extra local server lifecycle.
+- Easier to sandbox: only serve files we explicitly map.
+- Works offline and can use an ephemeral data store (no persistent cookies/cache).
+
+If a Canvas page truly needs “real web” semantics (CORS, fetch to loopback endpoints, service workers), consider the loopback-server variant instead (out of scope for this doc).
+
+## URL ↔ directory mapping
+
+The Canvas scheme is:
+- `clawdbot-canvas://<session>/<path>`
+
+Routing model:
+- `clawdbot-canvas://main/` → `<canvasRoot>/main/index.html` (or `index.htm`)
+- `clawdbot-canvas://main/yolo` → `<canvasRoot>/main/yolo/index.html` (or `index.htm`)
+- `clawdbot-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
+
+Directory listings are not served.
+
+When `/` has no `index.html` yet, the handler serves a **built-in scaffold page** (bundled with the macOS app).
+This is a visual placeholder only (no A2UI renderer).
+
+### Suggested on-disk location
+
+Store Canvas state under the app support directory:
+- `~/Library/Application Support/Clawdbot/canvas/<session>/…`
+
+This keeps it alongside other app-owned state and avoids mixing with `~/.clawdbot/` gateway config.
+
+## Panel behavior (agent-controlled)
+
+Canvas is presented as a borderless `NSPanel` (similar to the existing WebChat panel):
+- Can be shown/hidden at any time by the agent.
+- Supports an “anchored” presentation (near the menu bar icon or another anchor rect).
+- Uses a rounded container; shadow stays on, but **chrome/bezel only appears on hover**.
+- Default position is the **top-right corner** of the current screen’s visible frame (unless the user moved/resized it previously).
+- The panel is **user-resizable** (edge resize + hover resize handle) and the last frame is persisted per session.
+
+### Hover-only chrome
+
+Implementation notes:
+- Keep the window borderless at all times (don’t toggle `styleMask`).
+- Add an overlay view inside the content container for chrome (stroke + subtle gradient/material).
+- Use an `NSTrackingArea` to fade the chrome in/out on `mouseEntered/mouseExited`.
+- Optionally show close/drag affordances only while hovered.
+
+## Agent API surface (current)
+
+Canvas is exposed via the Gateway **node bridge**, so the agent can:
+- Show/hide the panel.
+- Navigate to a path (relative to the session root).
+- Evaluate JavaScript and optionally return results.
+- Query/modify DOM (helpers mirroring “dom query/all/attr/click/type/wait” patterns).
+- Capture a snapshot image of the current canvas view.
+- Optionally set panel placement (screen `x/y` + `width/height`) when showing/navigating.
+
+This should be modeled after `WebChatManager`/`WebChatSwiftUIWindowController` but targeting `clawdbot-canvas://…` URLs.
+
+Related:
+- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See `docs/clawdbot-mac.md`.
+
+## Agent commands (current)
+
+Use the main `clawdbot` CLI; it invokes canvas commands via `node.invoke`.
+
+- `clawdbot canvas present [--node <id>] [--target <...>] [--x/--y/--width/--height]`
+  - Local targets map into the session directory via the custom scheme (directory targets resolve `index.html|index.htm`).
+  - If `/` has no index file, Canvas shows the built-in scaffold page and returns `status: "welcome"`.
+- `clawdbot canvas hide [--node <id>]`
+- `clawdbot canvas eval --js <code> [--node <id>]`
+- `clawdbot canvas snapshot [--node <id>]`
+
+### Canvas A2UI
+
+Canvas A2UI is hosted by the **Gateway canvas host** at:
+
+```
+http://<gateway-host>:18793/__clawdbot__/a2ui/
+```
+
+The macOS app simply renders that page in the Canvas panel. The agent can drive it with JSONL **server→client protocol messages** (one JSON object per line):
+
+- `clawdbot canvas a2ui push --jsonl <path> [--node <id>]`
+- `clawdbot canvas a2ui reset [--node <id>]`
+
+`push` expects a JSONL file where **each line is a single JSON object** (parsed and forwarded to the in-page A2UI renderer).
+
+Minimal example (v0.8):
+
+```bash
+cat > /tmp/a2ui-v0.8.jsonl <<'EOF'
+{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, `canvas a2ui push` works."},"usageHint":"body"}}}]}}
+{"beginRendering":{"surfaceId":"main","root":"root"}}
+EOF
+
+clawdbot canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
+```
+
+Notes:
+- This does **not** support the A2UI v0.9 examples using `createSurface`.
+- A2UI **fails** if the Gateway canvas host is unreachable (no local fallback).
+- `canvas a2ui push` validates JSONL (line numbers on errors) and rejects v0.9 payloads.
+- Quick smoke: `clawdbot canvas a2ui push --text "Hello from A2UI"` renders a minimal v0.8 view.
+
+## Triggering agent runs from Canvas (deep links)
+
+Canvas can trigger new agent runs via the macOS app deep-link scheme:
+- `clawdbot://agent?...`
+
+This is intentionally separate from `clawdbot-canvas://…` (which is only for serving local Canvas files into the `WKWebView`).
+
+Suggested patterns:
+- HTML: render links/buttons that navigate to `clawdbot://agent?message=...`.
+- JS: set `window.location.href = 'clawdbot://agent?...'` for “run this now” actions.
+
+Implementation note (important):
+- In `WKWebView`, intercept `clawdbot://…` navigations in `WKNavigationDelegate` and forward them to the app, e.g. by calling `DeepLinkHandler.shared.handle(url:)` and returning `.cancel` for the navigation.
+
+Safety:
+- Deep links (`clawdbot://agent?...`) are always enabled.
+- Without a `key` query param, the app will prompt for confirmation before invoking the agent.
+- With a valid `key`, the run is unattended (no prompt). For Canvas-originated actions, the app injects an internal key automatically.
+
+## Security / guardrails
+
+Recommended defaults:
+- `WKWebsiteDataStore.nonPersistent()` for Canvas (ephemeral).
+- Navigation policy: allow only `clawdbot-canvas://…` (and optionally `about:blank`); open `http/https` externally.
+- Scheme handler must prevent directory traversal: resolved file paths must stay under `<canvasRoot>/<session>/`.
+- Disable or tightly scope any JS bridge; prefer query-string/bootstrap config over `window.webkit.messageHandlers` for sensitive data.
+
+## Debugging
+
+Suggested debugging hooks:
+- Enable Web Inspector for Canvas builds (same approach as WebChat).
+- Log scheme requests + resolution decisions to OSLog (subsystem `com.clawdbot`, category `Canvas`).
+- Provide a “copy canvas dir” action in debug settings to quickly reveal the session directory in Finder.

package/docs/mac/child-process.md

@@ -0,0 +1,72 @@
+---
+summary: "Running the gateway as a child process of the macOS app and why"
+read_when:
+  - Integrating the mac app with the gateway lifecycle
+---
+# Clawdbot gateway as a child process of the macOS app
+
+Date: 2025-12-06 · Status: draft · Owner: steipete
+
+Note (2025-12-19): the current implementation prefers a **launchd LaunchAgent** that runs the **bundled bun-compiled gateway**. This doc remains as an alternative mode for tighter coupling to the UI.
+
+## Goal
+Run the Node-based Clawdbot/clawdbot gateway as a direct child of the LSUIElement app (instead of a launchd agent) while keeping all TCC-sensitive work inside the Swift app/broker layer and wiring the existing “Clawdbot Active” toggle to start/stop the child.
+
+## When to prefer the child-process mode
+- You want gateway lifetime strictly coupled to the menu-bar app (dies when the app quits) and controlled by the “Clawdbot Active” toggle without touching launchd.
+- You’re okay giving up login persistence/auto-restart that launchd provides, or you’ll add your own backoff loop.
+- You want simpler log capture and supervision inside the app (no external plist or user-visible LaunchAgent).
+
+## Tradeoffs vs. launchd
+- **Pros:** tighter coupling to UI state; simpler surface (no plist install/bootout); easier to stream stdout/stderr; fewer moving parts for beta users.
+- **Cons:** no built-in KeepAlive/login auto-start; app crash kills gateway; you must build your own restart/backoff; Activity Monitor will show both processes under the app; still need correct TCC handling (see below).
+- **TCC:** behaviorally, child processes often inherit the parent app’s “responsible process” for TCC, but this is *not a contract*. Continue to route all protected actions through the Swift app/broker so prompts stay tied to the signed app bundle.
+
+## TCC guardrails (must keep)
+- Screen Recording, Accessibility, mic, and speech prompts must originate from the signed Swift app/broker. The Node child should never call these APIs directly; route through the app’s node commands (via Gateway `node.invoke`) for:
+  - `system.notify`
+  - `system.run` (including `needsScreenRecording`)
+  - `screen.record` / `camera.*`
+  - PeekabooBridge UI automation (`peekaboo …`)
+- Usage strings (`NSMicrophoneUsageDescription`, `NSSpeechRecognitionUsageDescription`, etc.) stay in the app target’s Info.plist; a bare Node binary has none and would fail.
+- If you ever embed Node that *must* touch TCC, wrap that call in a tiny signed helper target inside the app bundle and have Node exec that helper instead of calling the API directly.
+
+## Process manager design (Swift Subprocess)
+- Add a small `GatewayProcessManager` (Swift) that owns:
+  - `execution: Execution?` from `Swift Subprocess` to track the child.
+  - `start(config)` called when “Clawdbot Active” flips ON:
+    - binary: host Node running the bundled gateway under `Clawdbot.app/Contents/Resources/Gateway/`
+    - args: current clawdbot entrypoint and flags
+    - cwd/env: point to `~/.clawdbot` as today; inject the expanded PATH so Homebrew Node resolves under launchd
+    - output: stream stdout/stderr to `/tmp/clawdbot-gateway.log` (cap buffer via Subprocess OutputLimits)
+    - restart: optional linear/backoff restart if exit was non-zero and Active is still true
+  - `stop()` called when Active flips OFF or app terminates: cancel the execution and `waitUntilExit`.
+- Wire SwiftUI toggle:
+- ON: `GatewayProcessManager.start(...)`
+- OFF: `GatewayProcessManager.stop()` (no launchctl calls in this mode)
+- Keep the existing `LaunchdManager` around so we can switch back if needed; the toggle can choose between launchd or child mode with a flag if we want both.
+
+## Packaging and signing
+- Bundle the gateway payload (dist + production node_modules) under `Contents/Resources/Gateway/`; rely on host Node ≥22 instead of embedding a runtime.
+- Codesign native addons and dylibs inside the bundle; no nested runtime binary to sign now.
+- Host runtime should not call TCC APIs directly; keep privileged work inside the app/broker.
+
+## Logging and observability
+- Stream child stdout/stderr to `/tmp/clawdbot-gateway.log`; surface the last N lines in the Debug tab.
+- Emit a user notification (via existing NotificationManager) on crash/exit while Active is true.
+- Add a lightweight heartbeat from Node → app (e.g., ping over stdout) so the app can show status in the menu.
+
+## Failure/edge cases
+- App crash/quit kills the gateway. Decide if that is acceptable for the deployment tier; otherwise, stick with launchd for production and keep child-process for dev/experiments.
+- If the gateway exits repeatedly, back off (e.g., 1s/2s/5s/10s) and give up after N attempts with a menu warning.
+- Respect the existing pause semantics: when paused, the broker should return `ok=false, "clawdbot paused"`; the gateway should avoid calling privileged routes while paused.
+
+## Open questions / follow-ups
+- Do we need dual-mode (launchd for prod, child for dev)? If yes, gate via a setting or build flag.
+- Embedding a runtime is off the table for now; we rely on host Node for size/simplicity. Revisit only if host PATH drift becomes painful.
+- Do we want a tiny signed helper for rare TCC actions that cannot be brokered via the Swift app/broker?
+
+## Decision snapshot (current recommendation)
+- Keep all TCC surfaces in the Swift app/broker (node commands + PeekabooBridgeHost).
+- Implement `GatewayProcessManager` with Swift Subprocess to start/stop the gateway on the “Clawdbot Active” toggle.
+- Maintain the launchd path as a fallback for uptime/login persistence until child-mode proves stable.

package/docs/mac/dev-setup.md

@@ -0,0 +1,81 @@
+---
+summary: "Setup guide for developers working on the Clawdbot macOS app"
+read_when:
+  - Setting up the macOS development environment
+---
+# macOS Developer Setup
+
+This guide covers the necessary steps to build and run the Clawdbot macOS application from source.
+
+## Prerequisites
+
+Before building the app, ensure you have the following installed:
+
+1.  **Xcode 26.2+**: Required for Swift development.
+2.  **Node.js & pnpm**: Required for the gateway and CLI components.
+3.  **Bun**: Required to package the embedded gateway relay.
+    ```bash
+    curl -fsSL https://bun.sh/install | bash
+    ```
+
+## 1. Initialize Submodules
+
+Clawdbot depends on several submodules (like `Peekaboo`). You must initialize these recursively:
+
+```bash
+git submodule update --init --recursive
+```
+
+## 2. Install Dependencies
+
+Install the project-wide dependencies:
+
+```bash
+pnpm install
+```
+
+## 3. Build and Package the App
+
+To build the macOS app and package it into `dist/Clawdbot.app`, run:
+
+```bash
+./scripts/package-mac-app.sh
+```
+
+If you don't have an Apple Developer ID certificate, the script will automatically use **ad-hoc signing** (`-`). 
+
+> **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.
+
+## 4. Install the CLI Helper
+
+The macOS app requires a symlink named `clawdbot` in `/usr/local/bin` or `/opt/homebrew/bin` to manage background tasks.
+
+**To install it:**
+1.  Open the Clawdbot app.
+2.  Go to the **General** settings tab.
+3.  Click **"Install CLI helper"** (requires administrator privileges).
+
+Alternatively, you can manually link it from your Admin account:
+```bash
+sudo ln -sf "/Users/$(whoami)/clawdbot/dist/Clawdbot.app/Contents/Resources/Relay/clawdbot" /usr/local/bin/clawdbot
+```
+
+## Troubleshooting
+
+### App Crashes on Permission Grant
+If the app crashes when you try to allow **Speech Recognition** or **Microphone** access, it may be due to a corrupted TCC cache or signature mismatch.
+
+**Fix:**
+1. Reset the TCC permissions:
+   ```bash
+   tccutil reset All com.clawdbot.mac.debug
+   ```
+2. If that fails, change the `BUNDLE_ID` temporarily in `scripts/package-mac-app.sh` to force a "clean slate" from macOS.
+
+### Gateway "Starting..." indefinitely
+If the gateway status stays on "Starting...", check if a zombie process is holding the port:
+
+```bash
+lsof -nP -i :18789
+```
+Kill any existing `node` or `clawdbot` processes listening on that port and restart the app.

package/docs/mac/health.md

@@ -0,0 +1,28 @@
+---
+summary: "How the macOS app reports gateway/Baileys health states"
+read_when:
+  - Debugging mac app health indicators
+---
+# Health Checks on macOS
+
+How to see whether the WhatsApp Web/Baileys bridge is healthy from the menu bar app.
+
+## Menu bar
+- Status dot now reflects Baileys health:
+  - Green: linked + socket opened recently.
+  - Orange: connecting/retrying.
+  - Red: logged out or probe failed.
+- Secondary line reads "Web: linked · auth 12m · socket ok" or shows the failure reason.
+- "Run Health Check" menu item triggers an on-demand probe.
+
+## Settings
+- General tab gains a Health card showing: linked auth age, session-store path/count, last check time, last error/status code, and buttons for Run Health Check / Reveal Logs.
+- Uses a cached snapshot so the UI loads instantly and falls back gracefully when offline.
+- **Connections tab** surfaces provider status + controls for WhatsApp/Telegram (login QR, logout, probe, last disconnect/error).
+
+## How the probe works
+- App runs `clawdbot health --json` via `ShellExecutor` every ~60s and on demand. The probe loads creds, attempts a short Baileys connect, and reports status without sending messages.
+- Cache the last good snapshot and the last error separately to avoid flicker; show the timestamp of each.
+
+## When in doubt
+- You can still use the CLI flow in `docs/health.md` (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.

package/docs/mac/icon.md

@@ -0,0 +1,26 @@
+---
+summary: "Menu bar icon states and animations for Clawdbot on macOS"
+read_when:
+  - Changing menu bar icon behavior
+---
+# Menu Bar Icon States
+
+Author: steipete · Updated: 2025-12-06 · Scope: macOS app (`apps/macos`)
+
+- **Idle:** Normal icon animation (blink, occasional wiggle).
+- **Paused:** Status item uses `appearsDisabled`; no motion.
+- **Voice trigger (big ears):** Voice wake detector calls `AppState.triggerVoiceEars(ttl: nil)` when the wake word is heard, keeping `earBoostActive=true` while the utterance is captured. Ears scale up (1.9x), get circular ear holes for readability, then drop via `stopVoiceEars()` after 1s of silence. Only fired from the in-app voice pipeline.
+- **Working (agent running):** `AppState.isWorking=true` drives a “tail/leg scurry” micro-motion: faster leg wiggle and slight offset while work is in-flight. Currently toggled around WebChat agent runs; add the same toggle around other long tasks when you wire them.
+
+Wiring points
+- Voice wake: runtime/tester call `AppState.triggerVoiceEars(ttl: nil)` on trigger and `stopVoiceEars()` after 1s of silence to match the capture window.
+- Agent activity: set `AppStateStore.shared.setWorking(true/false)` around work spans (already done in WebChat agent call). Keep spans short and reset in `defer` blocks to avoid stuck animations.
+
+Shapes & sizes
+- Base icon drawn in `CritterIconRenderer.makeIcon(blink:legWiggle:earWiggle:earScale:earHoles:)`.
+- Ear scale defaults to `1.0`; voice boost sets `earScale=1.9` and toggles `earHoles=true` without changing overall frame (18×18 pt template image rendered into a 36×36 px Retina backing store).
+- Scurry uses leg wiggle up to ~1.0 with a small horizontal jiggle; it’s additive to any existing idle wiggle.
+
+Behavioral notes
+- No external CLI/broker toggle for ears/working; keep it internal to the app’s own signals to avoid accidental flapping.
+- Keep TTLs short (<10s) so the icon returns to baseline quickly if a job hangs.

package/docs/mac/logging.md

@@ -0,0 +1,51 @@
+---
+summary: "Clawdbot logging: rolling diagnostics file log + unified log privacy flags"
+read_when:
+  - Capturing macOS logs or investigating private data logging
+  - Debugging voice wake/session lifecycle issues
+---
+# Logging (macOS)
+
+## Rolling diagnostics file log (Debug pane)
+Clawdbot routes macOS app logs through swift-log (unified logging by default) and can write a local, rotating file log to disk when you need a durable capture.
+
+- Verbosity: **Debug pane → Logs → App logging → Verbosity**
+- Enable: **Debug pane → Logs → App logging → “Write rolling diagnostics log (JSONL)”**
+- Location: `~/Library/Logs/Clawdbot/diagnostics.jsonl` (rotates automatically; old files are suffixed with `.1`, `.2`, …)
+- Clear: **Debug pane → Logs → App logging → “Clear”**
+
+Notes:
+- This is **off by default**. Enable only while actively debugging.
+- Treat the file as sensitive; don’t share it without review.
+
+## Unified logging private data on macOS
+
+Unified logging redacts most payloads unless a subsystem opts into `privacy -off`. Per Peter's write-up on macOS [logging privacy shenanigans](https://steipete.me/posts/2025/logging-privacy-shenanigans) (2025) this is controlled by a plist in `/Library/Preferences/Logging/Subsystems/` keyed by the subsystem name. Only new log entries pick up the flag, so enable it before reproducing an issue.
+
+## Enable for Clawdbot (`com.clawdbot`)
+- Write the plist to a temp file first, then install it atomically as root:
+
+```bash
+cat <<'EOF' >/tmp/com.clawdbot.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>DEFAULT-OPTIONS</key>
+    <dict>
+        <key>Enable-Private-Data</key>
+        <true/>
+    </dict>
+</dict>
+</plist>
+EOF
+sudo install -m 644 -o root -g wheel /tmp/com.clawdbot.plist /Library/Preferences/Logging/Subsystems/com.clawdbot.plist
+```
+
+- No reboot is required; logd notices the file quickly, but only new log lines will include private payloads.
+- View the richer output with the existing helper, e.g. `./scripts/clawlog.sh --category WebChat --last 5m`.
+
+## Disable after debugging
+- Remove the override: `sudo rm /Library/Preferences/Logging/Subsystems/com.clawdbot.plist`.
+- Optionally run `sudo log config --reload` to force logd to drop the override immediately.
+- Remember this surface can include phone numbers and message bodies; keep the plist in place only while you actively need the extra detail.

package/docs/mac/menu-bar.md

@@ -0,0 +1,69 @@
+---
+summary: "Menu bar status logic and what is surfaced to users"
+read_when:
+  - Tweaking mac menu UI or status logic
+---
+# Menu Bar Status Logic
+
+## What is shown
+- We surface the current agent work state in the menu bar icon and in the first status row of the menu.
+- Health status is hidden while work is active; it returns when all sessions are idle.
+- The “Nodes” block in the menu lists **devices** only (gateway bridge nodes via `node.list`), not client/presence entries.
+
+## State model
+- Sessions: events arrive with `runId` (per-run) plus `sessionKey` in the payload. The “main” session is the key `main`; if absent, we fall back to the most recently updated session.
+- Priority: main always wins. If main is active, its state is shown immediately. If main is idle, the most recently active non‑main session is shown. We do not flip‑flop mid‑activity; we only switch when the current session goes idle or main becomes active.
+- Activity kinds:
+  - `job`: high‑level command execution (`state: started|streaming|done|error`).
+  - `tool`: `phase: start|result` with `toolName` and `meta/args`.
+
+## IconState enum (Swift)
+- `idle`
+- `workingMain(ActivityKind)`
+- `workingOther(ActivityKind)`
+- `overridden(ActivityKind)` (debug override)
+
+### ActivityKind → glyph
+- `bash` → 💻
+- `read` → 📄
+- `write` → ✍️
+- `edit` → 📝
+- `attach` → 📎
+- default → 🛠️
+
+### Visual mapping
+- `idle`: normal critter.
+- `workingMain`: badge with glyph, full tint, leg “working” animation.
+- `workingOther`: badge with glyph, muted tint, no scurry.
+- `overridden`: uses the chosen glyph/tint regardless of activity.
+
+## Status row text (menu)
+- While work is active: `<Session role> · <activity label>`
+  - Examples: `Main · bash: pnpm test`, `Other · read: apps/macos/Sources/Clawdbot/AppState.swift`.
+- When idle: falls back to the health summary.
+
+## Event ingestion
+- Source: control‑channel `agent` events (`ControlChannel.handleAgentEvent`).
+- Parsed fields:
+  - `stream: "job"` with `data.state` for start/stop.
+  - `stream: "tool"` with `data.phase`, `name`, optional `meta`/`args`.
+- Labels:
+  - `bash`: first line of `args.command`.
+  - `read`/`write`: shortened path.
+  - `edit`: path plus inferred change kind from `meta`/diff counts.
+  - fallback: tool name.
+
+## Debug override
+- Settings ▸ Debug ▸ “Icon override” picker:
+  - `System (auto)` (default)
+  - `Working: main` (per tool kind)
+  - `Working: other` (per tool kind)
+  - `Idle`
+- Stored via `@AppStorage("iconOverride")`; mapped to `IconState.overridden`.
+
+## Testing checklist
+- Trigger main session job: verify icon switches immediately and status row shows main label.
+- Trigger non‑main session job while main idle: icon/status shows non‑main; stays stable until it finishes.
+- Start main while other active: icon flips to main instantly.
+- Rapid tool bursts: ensure badge does not flicker (TTL grace on tool results).
+- Health row reappears once all sessions idle.

package/docs/mac/peekaboo.md

@@ -0,0 +1,170 @@
+---
+summary: "Plan for integrating Peekaboo automation into Clawdbot via PeekabooBridge (socket-based TCC broker)"
+read_when:
+  - Hosting PeekabooBridge in Clawdbot.app
+  - Integrating Peekaboo as a submodule
+  - Changing PeekabooBridge protocol/paths
+---
+# Peekaboo Bridge in Clawdbot (macOS UI automation broker)
+
+## TL;DR
+- **Peekaboo removed its XPC helper** and now exposes privileged automation via a **UNIX domain socket bridge** (`PeekabooBridge` / `PeekabooBridgeHost`, socket name `bridge.sock`).
+- Clawdbot integrates by **optionally hosting the same bridge** inside **Clawdbot.app** (user-toggleable). The primary client is the **`peekaboo` CLI** (installed via npm); Clawdbot does not need its own `ui …` CLI surface.
+- For **visualizations**, we keep them in **Peekaboo.app** (best UX); Clawdbot stays a thin broker host. No visualizer toggle in Clawdbot.
+
+Non-goals:
+- No auto-launching Peekaboo.app.
+- No onboarding deep links from the automation endpoint (Clawdbot onboarding already handles permissions).
+- No AI provider/agent runtime dependencies in Clawdbot (avoid pulling Tachikoma/MCP into the Clawdbot app/CLI).
+
+## Big refactor (Dec 2025): XPC → Bridge
+Peekaboo’s privileged execution moved from “CLI → XPC helper” to “CLI → socket bridge host”. For Clawdbot this is a win:
+- It matches the existing “local socket + codesign checks” approach.
+- It lets us piggyback on **either** Peekaboo.app’s permissions **or** Clawdbot.app’s permissions (whichever is running).
+- It avoids “two apps with two TCC bubbles” unless needed.
+
+Reference (Peekaboo submodule): `docs/bridge-host.md`.
+
+## Architecture
+### Processes
+- **Bridge hosts** (provide TCC-backed automation):
+  - **Peekaboo.app** (preferred; also provides visualizations + controls)
+  - **Claude.app** (secondary; lets `peekaboo` reuse Claude Desktop’s granted permissions)
+  - **Clawdbot.app** (secondary; “thin host” only)
+- **Bridge clients** (trigger single actions):
+  - `peekaboo …` (preferred; humans + agents)
+  - Optional: Clawdbot/Node shells out to `peekaboo` when it needs UI automation/capture
+
+### Host discovery (client-side)
+Order is deliberate:
+1. Peekaboo.app host (full UX)
+2. Claude.app host (piggyback on Claude Desktop permissions)
+3. Clawdbot.app host (piggyback on Clawdbot permissions)
+
+Socket paths (convention; exact paths must match Peekaboo):
+- Peekaboo: `~/Library/Application Support/Peekaboo/bridge.sock`
+- Claude: `~/Library/Application Support/Claude/bridge.sock`
+- Clawdbot: `~/Library/Application Support/clawdbot/bridge.sock`
+
+No auto-launch: if a host isn’t reachable, the command fails with a clear error (start Peekaboo.app, Claude.app, or Clawdbot.app).
+
+Override (debugging): set `PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock`.
+
+### Protocol shape
+- **Single request per connection**: connect → write one JSON request → half-close → read one JSON response → close.
+- **Timeout**: 10 seconds end-to-end per action (client enforced; host should also enforce per-operation).
+- **Errors**: human-readable string by default; structured envelope in `--json`.
+
+## Dependency strategy (submodule)
+Integrate Peekaboo via git submodule (nested submodules are OK).
+
+Path in Clawdbot repo:
+- `./Peekaboo` (Swabble-style; keep stable so SwiftPM path deps don’t churn).
+
+What Clawdbot should use:
+- **Client side**: `PeekabooBridge` (socket client + protocol models).
+- **Host side (Clawdbot.app)**: `PeekabooBridgeHost` + the minimal Peekaboo services needed to implement operations.
+
+What Clawdbot should *not* embed:
+- **Visualizer UI**: keep it in Peekaboo.app for now (toggle + controls live there).
+- **XPC**: don’t reintroduce helper targets; use the bridge.
+
+## IPC / CLI surface
+### No `clawdbot ui …`
+We avoid a parallel “Clawdbot UI automation CLI”. Instead:
+- `peekaboo` is the user/agent-facing CLI surface for automation and capture.
+- Clawdbot.app can host PeekabooBridge as a **thin TCC broker** so Peekaboo can piggyback on Clawdbot permissions when Peekaboo.app isn’t running.
+
+### Diagnostics
+Use Peekaboo’s built-in diagnostics to see which host would be used:
+- `peekaboo bridge status`
+- `peekaboo bridge status --verbose`
+- `peekaboo bridge status --json`
+
+### Output format
+Peekaboo commands default to human text output. Add `--json` for a structured envelope.
+
+### Timeouts
+Default timeout for UI actions: **10 seconds** end-to-end (client enforced; host should also enforce per-operation).
+
+## Coordinate model (multi-display)
+Requirement: coordinates are **per screen**, not global.
+
+Standardize for the CLI (agent-friendly): **top-left origin per screen**.
+
+Proposed request shape:
+- Requests accept `screenIndex` + `{x, y}` in that screen’s local coordinate space.
+- Clawdbot.app converts to global CG coordinates using `NSScreen.screens[screenIndex].frame.origin`.
+- Responses should echo both:
+  - The resolved `screenIndex`
+  - The local `{x, y}` and bounds
+  - Optionally the global `{x, y}` for debugging
+
+Ordering: use `NSScreen.screens` ordering consistently (documented in the CLI help + JSON schema).
+
+## Targeting (per app/window)
+Expose window/app targeting in the UI surface (align with Peekaboo targeting):
+- frontmost
+- by app name / bundle id
+- by window title substring
+- by (app, index)
+
+Peekaboo CLI targeting (agent-friendly):
+- `--bundle-id <id>` for app targeting
+- `--window-index <n>` (0-based) for disambiguating within an app when capturing
+
+All “see/click/type/scroll/wait” requests should accept a target (default: frontmost).
+
+## “See” + click packs (Playwright-style)
+Behavior stays aligned with Peekaboo:
+- `peekaboo see` returns element IDs (e.g. `B1`, `T3`) with bounds/labels.
+- Follow-up actions reference those IDs without re-scanning.
+
+`peekaboo see` should:
+- capture (optionally targeted) window/screen
+- return a screenshot **file path** (default: temp directory)
+- return a list of elements (text or JSON)
+
+Snapshot lifecycle requirement:
+- Host apps are long-lived, so snapshot state should be **in-memory by default**.
+- Snapshot scoping: “implicit snapshot” is **per target bundle id** (reuse last snapshot for that app when snapshot id is omitted).
+
+Practical flow (agent-friendly):
+- `peekaboo list apps` / `peekaboo list windows` provide bundle-id context for targeting.
+- `peekaboo see --bundle-id X` updates the implicit snapshot for `X`.
+- `peekaboo click --bundle-id X --on B1` reuses the most recent snapshot for `X` when `--snapshot-id` is omitted.
+
+## Visualizer integration
+Keep visualizations in **Peekaboo.app** for now.
+- Clawdbot hosts the bridge, but does not render overlays.
+- Any “visualizer enabled/disabled” setting is controlled in Peekaboo.app.
+
+## Screenshots (legacy → Peekaboo takeover)
+Clawdbot should not grow a separate screenshot CLI surface.
+
+Migration plan:
+- Use `peekaboo capture …` / `peekaboo see …` (returns a file path, default temp directory).
+- Once Clawdbot’ legacy screenshot plumbing is replaced, remove it cleanly (no aliases).
+
+## Permissions behavior
+If required permissions are missing:
+- return `ok=false` with a short human error message (e.g., “Accessibility permission missing”)
+- do not try to open System Settings from the automation endpoint
+
+## Security (socket auth)
+Both hosts must enforce:
+- filesystem perms on the socket path (owner read/write only)
+- server-side caller validation:
+  - require the caller’s code signature TeamID to be `Y5PE65HELJ`
+  - optional bundle-id allowlist for tighter scoping
+
+Debug-only escape hatch (development convenience):
+- “allow same-UID callers” means: *skip codesign checks for clients running under the same Unix user*.
+- This must be **opt-in**, **DEBUG-only**, and guarded by an env var (Peekaboo uses `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`).
+
+## Next integration steps (after this doc)
+1. Add Peekaboo as a git submodule (nested submodules OK).
+2. Host `PeekabooBridgeHost` inside Clawdbot.app behind a single setting (“Enable Peekaboo Bridge”, default on).
+3. Ensure Clawdbot hosts the bridge at `~/Library/Application Support/clawdbot/bridge.sock` and speaks the PeekabooBridge JSON protocol.
+4. Validate with `peekaboo bridge status --verbose` that Peekaboo can select Clawdbot as the fallback host (no auto-launch).
+5. Keep all protocol decisions aligned with Peekaboo (coordinate system, element IDs, snapshot scoping, error envelopes).