@quantumclaw/quantumclaw 2026.3.22

package/docs/platforms/linux.md

@@ -0,0 +1,94 @@
+---
+summary: "Linux support + companion app status"
+read_when:
+  - Looking for Linux companion app status
+  - Planning platform coverage or contributions
+title: "Linux App"
+---
+
+# Linux App
+
+The Gateway is fully supported on Linux. **Node is the recommended runtime**.
+Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).
+
+Native Linux companion apps are planned. Contributions are welcome if you want to help build one.
+
+## Beginner quick path (VPS)
+
+1. Install Node 24 (recommended; Node 22 LTS, currently `22.16+`, still works for compatibility)
+2. `npm i -g quantumclaw@latest`
+3. `quantumclaw onboard --install-daemon`
+4. From your laptop: `ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
+5. Open `http://127.0.0.1:18789/` and paste your token
+
+Full Linux server guide: [Linux Server](/vps). Step-by-step VPS example: [exe.dev](/install/exe-dev)
+
+## Install
+
+- [Getting Started](/start/getting-started)
+- [Install & updates](/install/updating)
+- Optional flows: [Bun (experimental)](/install/bun), [Nix](/install/nix), [Docker](/install/docker)
+
+## Gateway
+
+- [Gateway runbook](/gateway)
+- [Configuration](/gateway/configuration)
+
+## Gateway service install (CLI)
+
+Use one of these:
+
+```
+quantumclaw onboard --install-daemon
+```
+
+Or:
+
+```
+quantumclaw gateway install
+```
+
+Or:
+
+```
+quantumclaw configure
+```
+
+Select **Gateway service** when prompted.
+
+Repair/migrate:
+
+```
+quantumclaw doctor
+```
+
+## System control (systemd user unit)
+
+QuantumClaw installs a systemd **user** service by default. Use a **system**
+service for shared or always-on servers. The full unit example and guidance
+live in the [Gateway runbook](/gateway).
+
+Minimal setup:
+
+Create `~/.config/systemd/user/quantumclaw-gateway[-<profile>].service`:
+
+```
+[Unit]
+Description=QuantumClaw Gateway (profile: <profile>, v<version>)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/quantumclaw gateway --port 18789
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Enable it:
+
+```
+systemctl --user enable --now quantumclaw-gateway[-<profile>].service
+```

package/docs/platforms/mac/bundled-gateway.md

@@ -0,0 +1,73 @@
+---
+summary: "Gateway runtime on macOS (external launchd service)"
+read_when:
+  - Packaging QuantumClaw.app
+  - Debugging the macOS gateway launchd service
+  - Installing the gateway CLI for macOS
+title: "Gateway on macOS"
+---
+
+# Gateway on macOS (external launchd)
+
+QuantumClaw.app no longer bundles Node/Bun or the Gateway runtime. The macOS app
+expects an **external** `quantumclaw` CLI install, does not spawn the Gateway as a
+child process, and manages a per‑user launchd service to keep the Gateway
+running (or attaches to an existing local Gateway if one is already running).
+
+## Install the CLI (required for local mode)
+
+Node 24 is the default runtime on the Mac. Node 22 LTS, currently `22.16+`, still works for compatibility. Then install `quantumclaw` globally:
+
+```bash
+npm install -g quantumclaw@<version>
+```
+
+The macOS app’s **Install CLI** button runs the same flow via npm/pnpm (bun not recommended for Gateway runtime).
+
+## Launchd (Gateway as LaunchAgent)
+
+Label:
+
+- `ai.quantumclaw.gateway` (or `ai.quantumclaw.<profile>`; legacy `com.quantumclaw.*` may remain)
+
+Plist location (per‑user):
+
+- `~/Library/LaunchAgents/ai.quantumclaw.gateway.plist`
+  (or `~/Library/LaunchAgents/ai.quantumclaw.<profile>.plist`)
+
+Manager:
+
+- The macOS app owns LaunchAgent install/update in Local mode.
+- The CLI can also install it: `quantumclaw gateway install`.
+
+Behavior:
+
+- “QuantumClaw Active” enables/disables the LaunchAgent.
+- App quit does **not** stop the gateway (launchd keeps it alive).
+- If a Gateway is already running on the configured port, the app attaches to
+  it instead of starting a new one.
+
+Logging:
+
+- launchd stdout/err: `/tmp/quantumclaw/quantumclaw-gateway.log`
+
+## Version compatibility
+
+The macOS app checks the gateway version against its own version. If they’re
+incompatible, update the global CLI to match the app version.
+
+## Smoke check
+
+```bash
+quantumclaw --version
+
+QUANTUMCLAW_SKIP_CHANNELS=1 \
+QUANTUMCLAW_SKIP_CANVAS_HOST=1 \
+quantumclaw gateway --port 18999 --bind loopback
+```
+
+Then:
+
+```bash
+quantumclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000
+```

package/docs/platforms/mac/canvas.md

@@ -0,0 +1,125 @@
+---
+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
+title: "Canvas"
+---
+
+# Canvas (macOS app)
+
+The macOS app embeds an agent‑controlled **Canvas panel** using `WKWebView`. It
+is a lightweight visual workspace for HTML/CSS/JS, A2UI, and small interactive
+UI surfaces.
+
+## Where Canvas lives
+
+Canvas state is stored under Application Support:
+
+- `~/Library/Application Support/QuantumClaw/canvas/<session>/...`
+
+The Canvas panel serves those files via a **custom URL scheme**:
+
+- `quantumclaw-canvas://<session>/<path>`
+
+Examples:
+
+- `quantumclaw-canvas://main/` → `<canvasRoot>/main/index.html`
+- `quantumclaw-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
+- `quantumclaw-canvas://main/widgets/todo/` → `<canvasRoot>/main/widgets/todo/index.html`
+
+If no `index.html` exists at the root, the app shows a **built‑in scaffold page**.
+
+## Panel behavior
+
+- Borderless, resizable panel anchored near the menu bar (or mouse cursor).
+- Remembers size/position per session.
+- Auto‑reloads when local canvas files change.
+- Only one Canvas panel is visible at a time (session is switched as needed).
+
+Canvas can be disabled from Settings → **Allow Canvas**. When disabled, canvas
+node commands return `CANVAS_DISABLED`.
+
+## Agent API surface
+
+Canvas is exposed via the **Gateway WebSocket**, so the agent can:
+
+- show/hide the panel
+- navigate to a path or URL
+- evaluate JavaScript
+- capture a snapshot image
+
+CLI examples:
+
+```bash
+quantumclaw nodes canvas present --node <id>
+quantumclaw nodes canvas navigate --node <id> --url "/"
+quantumclaw nodes canvas eval --node <id> --js "document.title"
+quantumclaw nodes canvas snapshot --node <id>
+```
+
+Notes:
+
+- `canvas.navigate` accepts **local canvas paths**, `http(s)` URLs, and `file://` URLs.
+- If you pass `"/"`, the Canvas shows the local scaffold or `index.html`.
+
+## A2UI in Canvas
+
+A2UI is hosted by the Gateway canvas host and rendered inside the Canvas panel.
+When the Gateway advertises a Canvas host, the macOS app auto‑navigates to the
+A2UI host page on first open.
+
+Default A2UI host URL:
+
+```
+http://<gateway-host>:18789/__quantumclaw__/a2ui/
+```
+
+### A2UI commands (v0.8)
+
+Canvas currently accepts **A2UI v0.8** server→client messages:
+
+- `beginRendering`
+- `surfaceUpdate`
+- `dataModelUpdate`
+- `deleteSurface`
+
+`createSurface` (v0.9) is not supported.
+
+CLI example:
+
+```bash
+cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
+{"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, A2UI push works."},"usageHint":"body"}}}]}}
+{"beginRendering":{"surfaceId":"main","root":"root"}}
+EOFA2
+
+quantumclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
+```
+
+Quick smoke:
+
+```bash
+quantumclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"
+```
+
+## Triggering agent runs from Canvas
+
+Canvas can trigger new agent runs via deep links:
+
+- `quantumclaw://agent?...`
+
+Example (in JS):
+
+```js
+window.location.href = "quantumclaw://agent?message=Review%20this%20design";
+```
+
+The app prompts for confirmation unless a valid key is provided.
+
+## Security notes
+
+- Canvas scheme blocks directory traversal; files must live under the session root.
+- Local Canvas content uses a custom scheme (no loopback server required).
+- External `http(s)` URLs are allowed only when explicitly navigated.

package/docs/platforms/mac/child-process.md

@@ -0,0 +1,69 @@
+---
+summary: "Gateway lifecycle on macOS (launchd)"
+read_when:
+  - Integrating the mac app with the gateway lifecycle
+title: "Gateway Lifecycle"
+---
+
+# Gateway lifecycle on macOS
+
+The macOS app **manages the Gateway via launchd** by default and does not spawn
+the Gateway as a child process. It first tries to attach to an already‑running
+Gateway on the configured port; if none is reachable, it enables the launchd
+service via the external `quantumclaw` CLI (no embedded runtime). This gives you
+reliable auto‑start at login and restart on crashes.
+
+Child‑process mode (Gateway spawned directly by the app) is **not in use** today.
+If you need tighter coupling to the UI, run the Gateway manually in a terminal.
+
+## Default behavior (launchd)
+
+- The app installs a per‑user LaunchAgent labeled `ai.quantumclaw.gateway`
+  (or `ai.quantumclaw.<profile>` when using `--profile`/`QUANTUMCLAW_PROFILE`; legacy `com.quantumclaw.*` is supported).
+- When Local mode is enabled, the app ensures the LaunchAgent is loaded and
+  starts the Gateway if needed.
+- Logs are written to the launchd gateway log path (visible in Debug Settings).
+
+Common commands:
+
+```bash
+launchctl kickstart -k gui/$UID/ai.quantumclaw.gateway
+launchctl bootout gui/$UID/ai.quantumclaw.gateway
+```
+
+Replace the label with `ai.quantumclaw.<profile>` when running a named profile.
+
+## Unsigned dev builds
+
+`scripts/restart-mac.sh --no-sign` is for fast local builds when you don’t have
+signing keys. To prevent launchd from pointing at an unsigned relay binary, it:
+
+- Writes `~/.quantumclaw/disable-launchagent`.
+
+Signed runs of `scripts/restart-mac.sh` clear this override if the marker is
+present. To reset manually:
+
+```bash
+rm ~/.quantumclaw/disable-launchagent
+```
+
+## Attach-only mode
+
+To force the macOS app to **never install or manage launchd**, launch it with
+`--attach-only` (or `--no-launchd`). This sets `~/.quantumclaw/disable-launchagent`,
+so the app only attaches to an already running Gateway. You can toggle the same
+behavior in Debug Settings.
+
+## Remote mode
+
+Remote mode never starts a local Gateway. The app uses an SSH tunnel to the
+remote host and connects over that tunnel.
+
+## Why we prefer launchd
+
+- Auto‑start at login.
+- Built‑in restart/KeepAlive semantics.
+- Predictable logs and supervision.
+
+If a true child‑process mode is ever needed again, it should be documented as a
+separate, explicit dev‑only mode.

package/docs/platforms/mac/dev-setup.md

@@ -0,0 +1,104 @@
+---
+summary: "Setup guide for developers working on the QuantumClaw macOS app"
+read_when:
+  - Setting up the macOS development environment
+title: "macOS Dev Setup"
+---
+
+# macOS Developer Setup
+
+This guide covers the necessary steps to build and run the QuantumClaw 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 24 & pnpm**: Recommended for the gateway, CLI, and packaging scripts. Node 22 LTS, currently `22.16+`, remains supported for compatibility.
+
+## 1. Install Dependencies
+
+Install the project-wide dependencies:
+
+```bash
+pnpm install
+```
+
+## 2. Build and Package the App
+
+To build the macOS app and package it into `dist/QuantumClaw.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** (`-`).
+
+For dev run modes, signing flags, and Team ID troubleshooting, see the macOS app README:
+[https://github.com/quantumclaw/quantumclaw/blob/main/apps/macos/README.md](https://github.com/quantumclaw/quantumclaw/blob/main/apps/macos/README.md)
+
+> **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.
+
+## 3. Install the CLI
+
+The macOS app expects a global `quantumclaw` CLI install to manage background tasks.
+
+**To install it (recommended):**
+
+1. Open the QuantumClaw app.
+2. Go to the **General** settings tab.
+3. Click **"Install CLI"**.
+
+Alternatively, install it manually:
+
+```bash
+npm install -g quantumclaw@<version>
+```
+
+## Troubleshooting
+
+### Build Fails: Toolchain or SDK Mismatch
+
+The macOS app build expects the latest macOS SDK and Swift 6.2 toolchain.
+
+**System dependencies (required):**
+
+- **Latest macOS version available in Software Update** (required by Xcode 26.2 SDKs)
+- **Xcode 26.2** (Swift 6.2 toolchain)
+
+**Checks:**
+
+```bash
+xcodebuild -version
+xcrun swift --version
+```
+
+If versions don’t match, update macOS/Xcode and re-run the build.
+
+### 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 ai.quantumclaw.mac.debug
+   ```
+
+2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/quantumclaw/quantumclaw/blob/main/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
+quantumclaw gateway status
+quantumclaw gateway stop
+
+# If you're not using a LaunchAgent (dev mode / manual runs), find the listener:
+lsof -nP -iTCP:18789 -sTCP:LISTEN
+```
+
+If a manual run is holding the port, stop that process (Ctrl+C). As a last resort, kill the PID you found above.

package/docs/platforms/mac/health.md

@@ -0,0 +1,34 @@
+---
+summary: "How the macOS app reports gateway/Baileys health states"
+read_when:
+  - Debugging mac app health indicators
+title: "Health Checks (macOS)"
+---
+
+# Health Checks on macOS
+
+How to see whether the linked channel 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 "linked · auth 12m" 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.
+- **Channels tab** surfaces channel status + controls for WhatsApp/Telegram (login QR, logout, probe, last disconnect/error).
+
+## How the probe works
+
+- App runs `quantumclaw health --json` via `ShellExecutor` every ~60s and on demand. The probe loads creds 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 [Gateway health](/gateway/health) (`quantumclaw status`, `quantumclaw status --deep`, `quantumclaw health --json`) and tail `/tmp/quantumclaw/quantumclaw-*.log` for `web-heartbeat` / `web-reconnect`.

package/docs/platforms/mac/icon.md

@@ -0,0 +1,31 @@
+---
+summary: "Menu bar icon states and animations for QuantumClaw on macOS"
+read_when:
+  - Changing menu bar icon behavior
+title: "Menu Bar Icon"
+---
+
+# 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/platforms/mac/logging.md

@@ -0,0 +1,57 @@
+---
+summary: "QuantumClaw 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
+title: "macOS Logging"
+---
+
+# Logging (macOS)
+
+## Rolling diagnostics file log (Debug pane)
+
+QuantumClaw 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/QuantumClaw/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 QuantumClaw (`ai.quantumclaw`)
+
+- Write the plist to a temp file first, then install it atomically as root:
+
+```bash
+cat <<'EOF' >/tmp/ai.quantumclaw.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/ai.quantumclaw.plist /Library/Preferences/Logging/Subsystems/ai.quantumclaw.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/ai.quantumclaw.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/platforms/mac/menu-bar.md

@@ -0,0 +1,81 @@
+---
+summary: "Menu bar status logic and what is surfaced to users"
+read_when:
+  - Tweaking mac menu UI or status logic
+title: "Menu Bar"
+---
+
+# 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 (paired nodes via `node.list`), not client/presence entries.
+- A “Usage” section appears under Context when provider usage snapshots are available.
+
+## 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
+
+- `exec` → 💻
+- `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 · exec: pnpm test`, `Other · read: apps/macos/Sources/QuantumClaw/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:
+  - `exec`: 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.