fix: improve reminder context plumbing (#993) (thanks @cpojer)

fix(zalo): fix pairing channel detection and webhook payload format

AGENTS.md

@@ -6,6 +6,7 @@
 - Source code: `src/` (CLI wiring in `src/cli`, commands in `src/commands`, web provider in `src/provider-web.ts`, infra in `src/infra`, media pipeline in `src/media`).
 - Tests: colocated `*.test.ts`.
 - Docs: `docs/` (images, queue, Pi config). Built output lives in `dist/`.
+- Plugins/extensions: live under `extensions/*` (workspace packages). Keep plugin-only deps in the extension `package.json`; do not add them to the root `package.json` unless core uses them.
 - Installers served from `https://clawd.bot/*`: live in the sibling repo `../clawd.bot` (`public/install.sh`, `public/install-cli.sh`, `public/install.ps1`).
 
 ## Docs Linking (Mintlify)
@@ -59,6 +60,9 @@
 - When merging a PR from a new contributor: add their avatar to the README “Thanks to all clawtributors” thumbnail list.
 - After merging a PR: run `bun scripts/update-clawtributors.ts` if the contributor is missing, then commit the regenerated README.
 
+## Shorthand Commands
+- `sync up`: if working tree is dirty, commit all changes (pick a sensible Conventional Commit message), then `git pull --rebase`; if rebase conflicts and cannot resolve, stop; otherwise `git push`.
+
 ### PR Workflow (Review vs Land)
 - **Review mode (PR link only):** read `gh pr view/diff`; **do not** switch branches; **do not** change code.
 - **Landing mode:** create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm lint && pnpm build && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing). Important: contributor needs to be in git graph after this!
@@ -70,10 +74,11 @@
 - Never commit or publish real phone numbers, videos, or live configuration values. Use obviously fake placeholders in docs, tests, and examples.
 
 ## Troubleshooting
-- Rebrand/migration issues (Clawdis → Clawdbot) or legacy config/service warnings: run `clawdbot doctor` (see `docs/gateway/doctor.md`).
+- Rebrand/migration issues or legacy config/service warnings: run `clawdbot doctor` (see `docs/gateway/doctor.md`).
 
 ## Agent-Specific Notes
 - Vocabulary: "makeup" = "mac app".
+- When working on a GitHub Issue or PR, print the full URL at the end of the task.
 - When answering questions, respond with high-confidence answers only: verify in code; do not guess.
 - Never update the Carbon dependency.
 - Any dependency with `pnpm.patchedDependencies` must use an exact version (no `^`/`~`).

CHANGELOG.md

@@ -1,16 +1,76 @@
 # Changelog
 
-## 2026.1.15
+## 2026.1.15 (unreleased)
+
+- **BREAKING:** Microsoft Teams is now a plugin; install `@clawdbot/msteams` via `clawdbot plugins install @clawdbot/msteams`.
+- CLI: set process titles to `clawdbot-<command>` for clearer process listings.
+- Heartbeat: tighten prompt guidance + suppress duplicate alerts for 24h. (#980) — thanks @voidserf.
+- Sessions/Security: add `session.dmScope` for multi-user DM isolation and audit warnings. (#948) — thanks @Alphonse-arianee.
+- Plugins: add provider auth registry + `clawdbot models auth login` for plugin-driven OAuth/API key flows.
+- Onboarding: switch channels setup to a single-select loop with per-channel actions and disabled hints in the picker.
+- TUI: show provider/model labels for the active session and default model.
+- Heartbeat: add per-agent heartbeat configuration and multi-agent docs example.
+- Fix: list model picker entries as provider/model pairs for explicit selection. (#970) — thanks @mcinteerj.
+- Fix: persist `gateway.mode=local` after selecting Local run mode in `clawdbot configure`, even if no other sections are chosen.
+- Daemon: fix profile-aware service label resolution (env-driven) and add coverage for launchd/systemd/schtasks. (#969) — thanks @bjesuiter.
+- Daemon: share profile/state-dir resolution across service helpers and honor `CLAWDBOT_STATE_DIR` for Windows task scripts.
+- Docs: clarify multi-gateway rescue bot guidance. (#969) — thanks @bjesuiter.
+- Agents: add Current Date & Time system prompt section with configurable time format (auto/12/24).
+- Agents: avoid false positives when logging unsupported Google tool schema keywords.
+- Agents: include recent context in reminder cron payloads. (#993) — thanks @cpojer.
+- Status: restore usage summary line for current provider when no OAuth profiles exist.
+- Tools: normalize Slack/Discord message timestamps with `timestampMs`/`timestampUtc` while keeping raw provider fields.
+- Docs: add Date & Time guide and update prompt/timezone configuration docs.
+- Messages: debounce rapid inbound messages across channels with per-connector overrides. (#971) — thanks @juanpablodlc.
+- Messages: allow media-only sends (CLI/tool) and show Telegram voice recording status for voice notes. (#957) — thanks @rdev.
+- Auth/Status: keep auth profiles sticky per session (rotate on compaction/new), surface provider usage headers in `/status` and `clawdbot models status`, and update docs.
+- Fix: guard model fallback against undefined provider/model values. (#954) — thanks @roshanasingh4.
+- Fix: refactor session store updates, add chat.inject, and harden subagent cleanup flow. (#944) — thanks @tyler6204.
+- Fix: clean up suspended CLI processes across backends. (#978) — thanks @Nachx639.
+- Memory: make `node-llama-cpp` an optional dependency (avoid Node 25 install failures) and improve local-embeddings fallback/errors.
+- Browser: add `snapshot refs=aria` (Playwright aria-ref ids) for self-resolving refs across `snapshot` → `act`.
+- Browser: `profile="chrome"` now defaults to host control and returns clearer “attach a tab” errors.
+- Browser: extension mode recovers when only one tab is attached (stale targetId fallback).
+- Browser: prefer stable Chrome for auto-detect, with Brave/Edge fallbacks and updated docs. (#983) — thanks @cpojer.
+- Browser: fix `tab not found` for extension relay snapshots/actions when Playwright blocks `newCDPSession` (use the single available Page).
+- Telegram: add bidirectional reaction support with configurable notifications and agent guidance. (#964) — thanks @bohdanpodvirnyi.
+- Telegram: skip `message_thread_id=1` for General topic sends while keeping typing indicators. (#848) — thanks @azade-c.
+- Discord: allow allowlisted guilds without channel lists to receive messages when `groupPolicy="allowlist"`. — thanks @thewilloftheshadow.
+- Fix: sanitize user-facing error text + strip `<final>` tags across reply pipelines. (#975) — thanks @ThomsenDrake.
+- Fix: normalize pairing CLI aliases, allow extension channels, and harden Zalo webhook payload parsing. (#991) — thanks @longmaba.
+
+## 2026.1.14-1
+
+### Highlights
+- Web search: `web_search`/`web_fetch` tools (Brave API) + first-time setup in onboarding/configure.
+- Browser control: Chrome extension relay takeover mode + remote browser control via `clawdbot browser serve`.
+- Plugins: channel plugins (gateway HTTP hooks) + Zalo plugin + onboarding install flow. (#854) — thanks @longmaba.
+- Security: expanded `clawdbot security audit` (+ `--fix`), detect-secrets CI scan, and a `SECURITY.md` reporting policy.
 
 ### Changes
-- Security: add `clawdbot security audit` (`--deep`) and surface it in `status --all` and `doctor`.
+- Docs: clarify per-agent auth stores, sandboxed skill binaries, and elevated semantics.
+- Docs: add FAQ entries for missing provider auth after adding agents and Gemini thinking signature errors.
+- Agents: add optional auth-profile copy prompt on `agents add` and improve auth error messaging.
+- Security: expand `clawdbot security audit` checks (model hygiene, config includes, plugin allowlists, exposure matrix) and extend `--fix` to tighten more sensitive state paths.
+- Security: add `SECURITY.md` reporting policy.
+- Channels: add Matrix plugin (external) with docs + onboarding hooks.
+- Plugins: add Zalo channel plugin with gateway HTTP hooks and onboarding install prompt. (#854) — thanks @longmaba.
 - Onboarding: add a security checkpoint prompt (docs link + sandboxing hint); require `--accept-risk` for `--non-interactive`.
 - Docs: expand gateway security hardening guidance and incident response checklist.
 - Docs: document DM history limits for channel DMs. (#883) — thanks @pkrmf.
 - Security: add detect-secrets CI scan and baseline guidance. (#227) — thanks @Hyaxia.
+- Tools: add `web_search`/`web_fetch` (Brave API), auto-enable `web_fetch` for sandboxed sessions, and remove the `brave-search` skill.
+- CLI/Docs: add a web tools configure section for storing Brave API keys and update onboarding tips.
+- Browser: add Chrome extension relay takeover mode (toolbar button), plus `clawdbot browser extension install/path` and remote browser control via `clawdbot browser serve` + `browser.controlToken`.
 
 ### Fixes
+- Sessions: refactor session store updates to lock + mutate per-entry, add chat.inject, and harden subagent cleanup flow. (#944) — thanks @tyler6204.
+- Browser: add tests for snapshot labels/efficient query params and labeled image responses.
+- Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.
+- Doctor: avoid re-adding WhatsApp config when only legacy ack reactions are set. (#927, fixes #900) — thanks @grp06.
 - Agents: scrub tuple `items` schemas for Gemini tool calls. (#926, fixes #746) — thanks @grp06.
+- Agents: harden Antigravity Claude history/tool-call sanitization. (#968) — thanks @rdev.
+- Agents: stabilize sub-agent announce status from runtime outcomes and normalize Result/Notes. (#835) — thanks @roshanasingh4.
 - Embedded runner: suppress raw API error payloads from replies. (#924) — thanks @grp06.
 - Auth: normalize Claude Code CLI profile mode to oauth and auto-migrate config. (#855) — thanks @sebslight.
 - Daemon: clear persisted launchd disabled state before bootstrap (fixes `daemon install` after uninstall). (#849) — thanks @ndraiman.
@@ -19,6 +79,8 @@
 - Sandbox: preserve configured PATH for `docker exec` so custom tools remain available. (#873) — thanks @akonyer.
 - Slack: respect `channels.slack.requireMention` default when resolving channel mention gating. (#850) — thanks @evalexpr.
 - Telegram: aggregate split inbound messages into one prompt (reduces “one reply per fragment”).
+- Auto-reply: treat trailing `NO_REPLY` tokens as silent replies.
+- Config: prevent partial config writes from clobbering unrelated settings (base hash guard + merge patch for connection saves).
 
 ## 2026.1.14
 
@@ -34,7 +96,28 @@
  - UI: use application-defined WebSocket close code (browser compatibility). (#918) — thanks @rahthakor.
 - TUI: render picker overlays via the overlay stack so /models and /settings display. (#921) — thanks @grizzdank.
 - TUI: add a bright spinner + elapsed time in the status line for send/stream/run states.
+- TUI: show LLM error messages (rate limits, auth, etc.) instead of `(no output)`.
 - Gateway/Dev: ensure `pnpm gateway:dev` always uses the dev profile config + state (`~/.clawdbot-dev`).
+
+#### Agents / Auth / Tools / Sandbox
+- Agents: make user time zone and 24-hour time explicit in the system prompt. (#859) — thanks @CashWilliams.
+- Agents: strip downgraded tool call text without eating adjacent replies and filter thinking-tag leaks. (#905) — thanks @erikpr1994.
+- Agents: cap tool call IDs for OpenAI/OpenRouter to avoid request rejections. (#875) — thanks @j1philli.
+- Agents: scrub tuple `items` schemas for Gemini tool calls. (#926, fixes #746) — thanks @grp06.
+- Agents: stabilize sub-agent announce status from runtime outcomes and normalize Result/Notes. (#835) — thanks @roshanasingh4.
+- Auth: normalize Claude Code CLI profile mode to oauth and auto-migrate config. (#855) — thanks @sebslight.
+- Embedded runner: suppress raw API error payloads from replies. (#924) — thanks @grp06.
+- Logging: tolerate `EIO` from console writes to avoid gateway crashes. (#925, fixes #878) — thanks @grp06.
+- Sandbox: restore `docker.binds` config validation and preserve configured PATH for `docker exec`. (#873) — thanks @akonyer.
+- Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.
+
+#### macOS / Apps
+- macOS: ensure launchd log directory exists with a test-only override. (#909) — thanks @roshanasingh4.
+- macOS: format ConnectionsStore config to satisfy SwiftFormat lint. (#852) — thanks @mneves75.
+- macOS: pass auth token/password to dashboard URL for authenticated access. (#918) — thanks @rahthakor.
+- macOS: reuse launchd gateway auth and skip wizard when gateway config already exists. (#917)
+- macOS: prefer the default bridge tunnel port in remote mode for node bridge connectivity; document macOS remote control + bridge tunnels. (#960, fixes #865) — thanks @kkarimi.
+- Apps: use canonical main session keys from gateway defaults across macOS/iOS/Android to avoid creating bare `main` sessions.
 - macOS: fix cron preview/testing payload to use `channel` key. (#867) — thanks @wes-davis.
 - Telegram: honor `channels.telegram.timeoutSeconds` for grammY API requests. (#863) — thanks @Snaver.
 - Telegram: split long captions into media + follow-up text messages. (#907) - thanks @jalehman.
@@ -77,6 +160,7 @@
 - Memory: new `clawdbot memory` CLI plus `memory_search`/`memory_get` tools with snippets + line ranges; index stored under `~/.clawdbot/memory/{agentId}.sqlite` with watch-on-by-default.
 - Agents: strengthen memory recall guidance; make workspace bootstrap truncation configurable (default 20k) with warnings; add default sub-agent model config.
 - Tools/Sandbox: add tool profiles + group shorthands; support tool-policy groups in `tools.sandbox.tools`; drop legacy `memory` shorthand; allow Docker bind mounts via `docker.binds`. (#790) — thanks @akonyer.
+- Tools: add provider/model-specific tool policy overrides (`tools.byProvider`) to trim tool exposure per provider.
 - Tools: add browser `scrollintoview` action; allow Claude/Gemini tool param aliases; allow thinking `xhigh` for GPT-5.2/Codex with safe downgrades. (#793) — thanks @hsrvc; (#444) — thanks @grp06.
 - Gateway/CLI: add Tailscale binary discovery, custom bind mode, and probe auth retry; add `clawdbot dashboard` auto-open flow; default native slash commands to `"auto"` with per-provider overrides. (#740) — thanks @jeffersonwarrior.
 - Auth/Onboarding: add Chutes OAuth (PKCE + refresh + onboarding choice); normalize API key inputs; default TUI onboarding to `deliver: false`. (#726) — thanks @FrieSei; (#791) — thanks @roshanasingh4.
@@ -89,6 +173,7 @@
 
 ### Fixes
 - Doctor: warn on pnpm workspace mismatches, missing Control UI assets, and missing tsx binaries; offer UI rebuilds.
+- Tools: apply global tool allow/deny even when agent-specific tool policy is set.
 - Models/Providers: treat credential validation failures as auth errors to trigger fallback; normalize `${ENV_VAR}` apiKey values and auto-fill missing provider keys; preserve explicit GitHub Copilot provider config + agent-dir auth profiles. (#822) — thanks @sebslight; (#705) — thanks @TAGOOZ.
 - Auth: drop invalid auth profiles from ordering so environment keys can still be used for providers like MiniMax.
 - Gemini: normalize Gemini 3 ids to preview variants; strip Gemini CLI tool call/response ids; downgrade missing `thought_signature`; strip Claude `msg_*` thought_signature fields to avoid base64 decode errors. (#795) — thanks @thewilloftheshadow; (#783) — thanks @ananth-vardhan-cn; (#793) — thanks @hsrvc; (#805) — thanks @marcmarg.

README.md

@@ -468,25 +468,29 @@ AI/vibe-coded PRs welcome! 🤖
 
 Special thanks to @andrewting19 for the Anthropic OAuth tool-name fix.
 
+Core contributors:
+- @cpojer — Telegram onboarding UX + docs
+
 Thanks to all clawtributors:
 
 <p align="left">
-  <a href="https://github.com/steipete"><img src="https://avatars.githubusercontent.com/u/58493?v=4&s=48" width="48" height="48" alt="steipete" title="steipete"/></a> <a href="https://github.com/joaohlisboa"><img src="https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width="48" height="48" alt="joaohlisboa" title="joaohlisboa"/></a> <a href="https://github.com/mneves75"><img src="https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width="48" height="48" alt="mneves75" title="mneves75"/></a> <a href="https://github.com/rahthakor"><img src="https://avatars.githubusercontent.com/u/8470553?v=4&s=48" width="48" height="48" alt="rahthakor" title="rahthakor"/></a> <a href="https://github.com/joshp123"><img src="https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width="48" height="48" alt="joshp123" title="joshp123"/></a> <a href="https://github.com/mukhtharcm"><img src="https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width="48" height="48" alt="mukhtharcm" title="mukhtharcm"/></a> <a href="https://github.com/maxsumrall"><img src="https://avatars.githubusercontent.com/u/628843?v=4&s=48" width="48" height="48" alt="maxsumrall" title="maxsumrall"/></a> <a href="https://github.com/xadenryan"><img src="https://avatars.githubusercontent.com/u/165437834?v=4&s=48" width="48" height="48" alt="xadenryan" title="xadenryan"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="Tobias Bischoff" title="Tobias Bischoff"/></a> <a href="https://github.com/hsrvc"><img src="https://avatars.githubusercontent.com/u/129702169?v=4&s=48" width="48" height="48" alt="hsrvc" title="hsrvc"/></a>
-  <a href="https://github.com/magimetal"><img src="https://avatars.githubusercontent.com/u/36491250?v=4&s=48" width="48" height="48" alt="magimetal" title="magimetal"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/NicholasSpisak"><img src="https://avatars.githubusercontent.com/u/129075147?v=4&s=48" width="48" height="48" alt="NicholasSpisak" title="NicholasSpisak"/></a> <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="abhisekbasu1" title="abhisekbasu1"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a> <a href="https://github.com/jamesgroat"><img src="https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width="48" height="48" alt="jamesgroat" title="jamesgroat"/></a> <a href="https://github.com/dantelex"><img src="https://avatars.githubusercontent.com/u/631543?v=4&s=48" width="48" height="48" alt="dantelex" title="dantelex"/></a> <a href="https://github.com/daveonkels"><img src="https://avatars.githubusercontent.com/u/533642?v=4&s=48" width="48" height="48" alt="daveonkels" title="daveonkels"/></a> <a href="https://github.com/vrknetha"><img src="https://avatars.githubusercontent.com/u/20596261?v=4&s=48" width="48" height="48" alt="vrknetha" title="vrknetha"/></a> <a href="https://github.com/radek-paclt"><img src="https://avatars.githubusercontent.com/u/50451445?v=4&s=48" width="48" height="48" alt="radek-paclt" title="radek-paclt"/></a>
-  <a href="https://github.com/mteam88"><img src="https://avatars.githubusercontent.com/u/84196639?v=4&s=48" width="48" height="48" alt="mteam88" title="mteam88"/></a> <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="Eng. Juan Combetto" title="Eng. Juan Combetto"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a> <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="Mariano Belinky" title="Mariano Belinky"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/benithors"><img src="https://avatars.githubusercontent.com/u/20652882?v=4&s=48" width="48" height="48" alt="benithors" title="benithors"/></a> <a href="https://github.com/sreekaransrinath"><img src="https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width="48" height="48" alt="sreekaransrinath" title="sreekaransrinath"/></a> <a href="https://github.com/gupsammy"><img src="https://avatars.githubusercontent.com/u/20296019?v=4&s=48" width="48" height="48" alt="gupsammy" title="gupsammy"/></a> <a href="https://github.com/cristip73"><img src="https://avatars.githubusercontent.com/u/24499421?v=4&s=48" width="48" height="48" alt="cristip73" title="cristip73"/></a> <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a>
-  <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="Vasanth Rao Naik Sabavat" title="Vasanth Rao Naik Sabavat"/></a> <a href="https://github.com/lc0rp"><img src="https://avatars.githubusercontent.com/u/2609441?v=4&s=48" width="48" height="48" alt="lc0rp" title="lc0rp"/></a> <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a> <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="nachx639" title="nachx639"/></a> <a href="https://github.com/davidguttman"><img src="https://avatars.githubusercontent.com/u/431696?v=4&s=48" width="48" height="48" alt="davidguttman" title="davidguttman"/></a> <a href="https://github.com/sircrumpet"><img src="https://avatars.githubusercontent.com/u/4436535?v=4&s=48" width="48" height="48" alt="sircrumpet" title="sircrumpet"/></a> <a href="https://github.com/peschee"><img src="https://avatars.githubusercontent.com/u/63866?v=4&s=48" width="48" height="48" alt="peschee" title="peschee"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a> <a href="https://github.com/lutr0"><img src="https://avatars.githubusercontent.com/u/76906369?v=4&s=48" width="48" height="48" alt="lutr0" title="lutr0"/></a>
-  <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/KristijanJovanovski"><img src="https://avatars.githubusercontent.com/u/8942284?v=4&s=48" width="48" height="48" alt="KristijanJovanovski" title="KristijanJovanovski"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="Sebastian Barrios" title="Sebastian Barrios"/></a> <a href="https://github.com/search?q=sheeek"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="sheeek" title="sheeek"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a> <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="manuelhettich" title="manuelhettich"/></a>
-  <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/myfunc"><img src="https://avatars.githubusercontent.com/u/19294627?v=4&s=48" width="48" height="48" alt="myfunc" title="myfunc"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a> <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a> <a href="https://github.com/danielz1z"><img src="https://avatars.githubusercontent.com/u/235270390?v=4&s=48" width="48" height="48" alt="danielz1z" title="danielz1z"/></a> <a href="https://github.com/bjesuiter"><img src="https://avatars.githubusercontent.com/u/2365676?v=4&s=48" width="48" height="48" alt="bjesuiter" title="bjesuiter"/></a> <a href="https://github.com/superman32432432"><img src="https://avatars.githubusercontent.com/u/7228420?v=4&s=48" width="48" height="48" alt="superman32432432" title="superman32432432"/></a>
-  <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a> <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a> <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a>
-  <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a> <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a> <a href="https://github.com/roshanasingh4"><img src="https://avatars.githubusercontent.com/u/88576930?v=4&s=48" width="48" height="48" alt="roshanasingh4" title="roshanasingh4"/></a> <a href="https://github.com/search?q=Friederike%20Seiler"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Friederike Seiler" title="Friederike Seiler"/></a>
-  <a href="https://github.com/gabriel-trigo"><img src="https://avatars.githubusercontent.com/u/38991125?v=4&s=48" width="48" height="48" alt="gabriel-trigo" title="gabriel-trigo"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a> <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a> <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a> <a href="https://github.com/petradonka"><img src="https://avatars.githubusercontent.com/u/7353770?v=4&s=48" width="48" height="48" alt="petradonka" title="petradonka"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a>
-  <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/search?q=Chris%20Taylor"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Chris Taylor" title="Chris Taylor"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/search?q=Aaron%20Konyer"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Aaron Konyer" title="Aaron Konyer"/></a> <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a>
-  <a href="https://github.com/gumadeiras"><img src="https://avatars.githubusercontent.com/u/5599352?v=4&s=48" width="48" height="48" alt="gumadeiras" title="gumadeiras"/></a> <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/search?q=jeffersonwarrior"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a> <a href="https://github.com/juanpablodlc"><img src="https://avatars.githubusercontent.com/u/92012363?v=4&s=48" width="48" height="48" alt="juanpablodlc" title="juanpablodlc"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a> <a href="https://github.com/mjrussell"><img src="https://avatars.githubusercontent.com/u/1641895?v=4&s=48" width="48" height="48" alt="mjrussell" title="mjrussell"/></a>
-  <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a> <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a> <a href="https://github.com/robaxelsen"><img src="https://avatars.githubusercontent.com/u/13132899?v=4&s=48" width="48" height="48" alt="robaxelsen" title="robaxelsen"/></a> <a href="https://github.com/search?q=Sash%20Catanzarite"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Sash Catanzarite" title="Sash Catanzarite"/></a> <a href="https://github.com/search?q=VAC"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="VAC" title="VAC"/></a> <a href="https://github.com/zknicker"><img src="https://avatars.githubusercontent.com/u/1164085?v=4&s=48" width="48" height="48" alt="zknicker" title="zknicker"/></a> <a href="https://github.com/adam91holt"><img src="https://avatars.githubusercontent.com/u/9592417?v=4&s=48" width="48" height="48" alt="adam91holt" title="adam91holt"/></a> <a href="https://github.com/search?q=alejandro%20maza"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="alejandro maza" title="alejandro maza"/></a> <a href="https://github.com/andrewting19"><img src="https://avatars.githubusercontent.com/u/10536704?v=4&s=48" width="48" height="48" alt="andrewting19" title="andrewting19"/></a>
-  <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/bolismauro"><img src="https://avatars.githubusercontent.com/u/771999?v=4&s=48" width="48" height="48" alt="bolismauro" title="bolismauro"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/search?q=Clawd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Clawd" title="Clawd"/></a> <a href="https://github.com/conhecendocontato"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendocontato" title="conhecendocontato"/></a> <a href="https://github.com/search?q=Drake%20Thomsen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Drake Thomsen" title="Drake Thomsen"/></a> <a href="https://github.com/evalexpr"><img src="https://avatars.githubusercontent.com/u/23485511?v=4&s=48" width="48" height="48" alt="evalexpr" title="evalexpr"/></a> <a href="https://github.com/grp06"><img src="https://avatars.githubusercontent.com/u/1573959?v=4&s=48" width="48" height="48" alt="grp06" title="grp06"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a>
-  <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a> <a href="https://github.com/search?q=Jefferson%20Nunn"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jefferson Nunn" title="Jefferson Nunn"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a> <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/search?q=Marc"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Marc" title="Marc"/></a>
-  <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a> <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/search?q=Mustafa%20Tag%20Eldeen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mustafa Tag Eldeen" title="Mustafa Tag Eldeen"/></a> <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a> <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/search?q=Rony%20Kelner"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rony Kelner" title="Rony Kelner"/></a>
-  <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/siraht"><img src="https://avatars.githubusercontent.com/u/73152895?v=4&s=48" width="48" height="48" alt="siraht" title="siraht"/></a> <a href="https://github.com/sleontenko"><img src="https://avatars.githubusercontent.com/u/7135949?v=4&s=48" width="48" height="48" alt="sleontenko" title="sleontenko"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a> <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/YuriNachos"><img src="https://avatars.githubusercontent.com/u/19365375?v=4&s=48" width="48" height="48" alt="YuriNachos" title="YuriNachos"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a>
-  <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a> <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a>
-  <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a> <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
+  <a href="https://github.com/steipete"><img src="https://avatars.githubusercontent.com/u/58493?v=4&s=48" width="48" height="48" alt="steipete" title="steipete"/></a> <a href="https://github.com/bohdanpodvirnyi"><img src="https://avatars.githubusercontent.com/u/31819391?v=4&s=48" width="48" height="48" alt="bohdanpodvirnyi" title="bohdanpodvirnyi"/></a> <a href="https://github.com/joaohlisboa"><img src="https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width="48" height="48" alt="joaohlisboa" title="joaohlisboa"/></a> <a href="https://github.com/mneves75"><img src="https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width="48" height="48" alt="mneves75" title="mneves75"/></a> <a href="https://github.com/rahthakor"><img src="https://avatars.githubusercontent.com/u/8470553?v=4&s=48" width="48" height="48" alt="rahthakor" title="rahthakor"/></a> <a href="https://github.com/vrknetha"><img src="https://avatars.githubusercontent.com/u/20596261?v=4&s=48" width="48" height="48" alt="vrknetha" title="vrknetha"/></a> <a href="https://github.com/joshp123"><img src="https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width="48" height="48" alt="joshp123" title="joshp123"/></a> <a href="https://github.com/mukhtharcm"><img src="https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width="48" height="48" alt="mukhtharcm" title="mukhtharcm"/></a> <a href="https://github.com/maxsumrall"><img src="https://avatars.githubusercontent.com/u/628843?v=4&s=48" width="48" height="48" alt="maxsumrall" title="maxsumrall"/></a> <a href="https://github.com/xadenryan"><img src="https://avatars.githubusercontent.com/u/165437834?v=4&s=48" width="48" height="48" alt="xadenryan" title="xadenryan"/></a>
+  <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="Tobias Bischoff" title="Tobias Bischoff"/></a> <a href="https://github.com/juanpablodlc"><img src="https://avatars.githubusercontent.com/u/92012363?v=4&s=48" width="48" height="48" alt="juanpablodlc" title="juanpablodlc"/></a> <a href="https://github.com/hsrvc"><img src="https://avatars.githubusercontent.com/u/129702169?v=4&s=48" width="48" height="48" alt="hsrvc" title="hsrvc"/></a> <a href="https://github.com/magimetal"><img src="https://avatars.githubusercontent.com/u/36491250?v=4&s=48" width="48" height="48" alt="magimetal" title="magimetal"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/NicholasSpisak"><img src="https://avatars.githubusercontent.com/u/129075147?v=4&s=48" width="48" height="48" alt="NicholasSpisak" title="NicholasSpisak"/></a> <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="abhisekbasu1" title="abhisekbasu1"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a> <a href="https://github.com/jamesgroat"><img src="https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width="48" height="48" alt="jamesgroat" title="jamesgroat"/></a> <a href="https://github.com/Hyaxia"><img src="https://avatars.githubusercontent.com/u/36747317?v=4&s=48" width="48" height="48" alt="Hyaxia" title="Hyaxia"/></a>
+  <a href="https://github.com/dantelex"><img src="https://avatars.githubusercontent.com/u/631543?v=4&s=48" width="48" height="48" alt="dantelex" title="dantelex"/></a> <a href="https://github.com/daveonkels"><img src="https://avatars.githubusercontent.com/u/533642?v=4&s=48" width="48" height="48" alt="daveonkels" title="daveonkels"/></a> <a href="https://github.com/radek-paclt"><img src="https://avatars.githubusercontent.com/u/50451445?v=4&s=48" width="48" height="48" alt="radek-paclt" title="radek-paclt"/></a> <a href="https://github.com/mteam88"><img src="https://avatars.githubusercontent.com/u/84196639?v=4&s=48" width="48" height="48" alt="mteam88" title="mteam88"/></a> <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="Eng. Juan Combetto" title="Eng. Juan Combetto"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a> <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="Mariano Belinky" title="Mariano Belinky"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/benithors"><img src="https://avatars.githubusercontent.com/u/20652882?v=4&s=48" width="48" height="48" alt="benithors" title="benithors"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="nachx639" title="nachx639"/></a>
+  <a href="https://github.com/sreekaransrinath"><img src="https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width="48" height="48" alt="sreekaransrinath" title="sreekaransrinath"/></a> <a href="https://github.com/gupsammy"><img src="https://avatars.githubusercontent.com/u/20296019?v=4&s=48" width="48" height="48" alt="gupsammy" title="gupsammy"/></a> <a href="https://github.com/cristip73"><img src="https://avatars.githubusercontent.com/u/24499421?v=4&s=48" width="48" height="48" alt="cristip73" title="cristip73"/></a> <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a> <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="Vasanth Rao Naik Sabavat" title="Vasanth Rao Naik Sabavat"/></a> <a href="https://github.com/lc0rp"><img src="https://avatars.githubusercontent.com/u/2609441?v=4&s=48" width="48" height="48" alt="lc0rp" title="lc0rp"/></a> <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a> <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a> <a href="https://github.com/davidguttman"><img src="https://avatars.githubusercontent.com/u/431696?v=4&s=48" width="48" height="48" alt="davidguttman" title="davidguttman"/></a> <a href="https://github.com/sleontenko"><img src="https://avatars.githubusercontent.com/u/7135949?v=4&s=48" width="48" height="48" alt="sleontenko" title="sleontenko"/></a>
+  <a href="https://github.com/sircrumpet"><img src="https://avatars.githubusercontent.com/u/4436535?v=4&s=48" width="48" height="48" alt="sircrumpet" title="sircrumpet"/></a> <a href="https://github.com/peschee"><img src="https://avatars.githubusercontent.com/u/63866?v=4&s=48" width="48" height="48" alt="peschee" title="peschee"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a> <a href="https://github.com/lutr0"><img src="https://avatars.githubusercontent.com/u/76906369?v=4&s=48" width="48" height="48" alt="lutr0" title="lutr0"/></a> <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/gumadeiras"><img src="https://avatars.githubusercontent.com/u/5599352?v=4&s=48" width="48" height="48" alt="gumadeiras" title="gumadeiras"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/KristijanJovanovski"><img src="https://avatars.githubusercontent.com/u/8942284?v=4&s=48" width="48" height="48" alt="KristijanJovanovski" title="KristijanJovanovski"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a>
+  <a href="https://github.com/rdev"><img src="https://avatars.githubusercontent.com/u/8418866?v=4&s=48" width="48" height="48" alt="rdev" title="rdev"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="sebslight" title="sebslight"/></a> <a href="https://github.com/search?q=sheeek"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="sheeek" title="sheeek"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="manuelhettich" title="manuelhettich"/></a> <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/myfunc"><img src="https://avatars.githubusercontent.com/u/19294627?v=4&s=48" width="48" height="48" alt="myfunc" title="myfunc"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a>
+  <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a> <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a> <a href="https://github.com/bjesuiter"><img src="https://avatars.githubusercontent.com/u/2365676?v=4&s=48" width="48" height="48" alt="bjesuiter" title="bjesuiter"/></a> <a href="https://github.com/danielz1z"><img src="https://avatars.githubusercontent.com/u/235270390?v=4&s=48" width="48" height="48" alt="danielz1z" title="danielz1z"/></a> <a href="https://github.com/j1philli"><img src="https://avatars.githubusercontent.com/u/3744255?v=4&s=48" width="48" height="48" alt="Josh Phillips" title="Josh Phillips"/></a> <a href="https://github.com/roshanasingh4"><img src="https://avatars.githubusercontent.com/u/88576930?v=4&s=48" width="48" height="48" alt="roshanasingh4" title="roshanasingh4"/></a> <a href="https://github.com/superman32432432"><img src="https://avatars.githubusercontent.com/u/7228420?v=4&s=48" width="48" height="48" alt="superman32432432" title="superman32432432"/></a> <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a>
+  <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a> <a href="https://github.com/grp06"><img src="https://avatars.githubusercontent.com/u/1573959?v=4&s=48" width="48" height="48" alt="grp06" title="grp06"/></a> <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a>
+  <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a> <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a>
+  <a href="https://github.com/chrisrodz"><img src="https://avatars.githubusercontent.com/u/2967620?v=4&s=48" width="48" height="48" alt="chrisrodz" title="chrisrodz"/></a> <a href="https://github.com/search?q=Friederike%20Seiler"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Friederike Seiler" title="Friederike Seiler"/></a> <a href="https://github.com/gabriel-trigo"><img src="https://avatars.githubusercontent.com/u/38991125?v=4&s=48" width="48" height="48" alt="gabriel-trigo" title="gabriel-trigo"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a> <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a> <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a>
+  <a href="https://github.com/petradonka"><img src="https://avatars.githubusercontent.com/u/7353770?v=4&s=48" width="48" height="48" alt="petradonka" title="petradonka"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/search?q=Chris%20Taylor"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Chris Taylor" title="Chris Taylor"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/search?q=Aaron%20Konyer"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Aaron Konyer" title="Aaron Konyer"/></a> <a href="https://github.com/adam91holt"><img src="https://avatars.githubusercontent.com/u/9592417?v=4&s=48" width="48" height="48" alt="adam91holt" title="adam91holt"/></a>
+  <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/evalexpr"><img src="https://avatars.githubusercontent.com/u/23485511?v=4&s=48" width="48" height="48" alt="evalexpr" title="evalexpr"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a> <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/search?q=jeffersonwarrior"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a>
+  <a href="https://github.com/mjrussell"><img src="https://avatars.githubusercontent.com/u/1641895?v=4&s=48" width="48" height="48" alt="mjrussell" title="mjrussell"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a> <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a> <a href="https://github.com/robaxelsen"><img src="https://avatars.githubusercontent.com/u/13132899?v=4&s=48" width="48" height="48" alt="robaxelsen" title="robaxelsen"/></a> <a href="https://github.com/search?q=Sash%20Catanzarite"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Sash Catanzarite" title="Sash Catanzarite"/></a> <a href="https://github.com/search?q=VAC"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="VAC" title="VAC"/></a> <a href="https://github.com/zknicker"><img src="https://avatars.githubusercontent.com/u/1164085?v=4&s=48" width="48" height="48" alt="zknicker" title="zknicker"/></a> <a href="https://github.com/search?q=alejandro%20maza"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="alejandro maza" title="alejandro maza"/></a> <a href="https://github.com/andrewting19"><img src="https://avatars.githubusercontent.com/u/10536704?v=4&s=48" width="48" height="48" alt="andrewting19" title="andrewting19"/></a>
+  <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/bolismauro"><img src="https://avatars.githubusercontent.com/u/771999?v=4&s=48" width="48" height="48" alt="bolismauro" title="bolismauro"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/search?q=Clawd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Clawd" title="Clawd"/></a> <a href="https://github.com/conhecendocontato"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendocontato" title="conhecendocontato"/></a> <a href="https://github.com/search?q=Drake%20Thomsen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Drake Thomsen" title="Drake Thomsen"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a> <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a>
+  <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a> <a href="https://github.com/search?q=Jefferson%20Nunn"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jefferson Nunn" title="Jefferson Nunn"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/search?q=Marc"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Marc" title="Marc"/></a> <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a> <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a>
+  <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/search?q=Mustafa%20Tag%20Eldeen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mustafa Tag Eldeen" title="Mustafa Tag Eldeen"/></a> <a href="https://github.com/ndraiman"><img src="https://avatars.githubusercontent.com/u/12609607?v=4&s=48" width="48" height="48" alt="ndraiman" title="ndraiman"/></a> <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a> <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/search?q=Rony%20Kelner"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rony Kelner" title="Rony Kelner"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a>
+  <a href="https://github.com/siraht"><img src="https://avatars.githubusercontent.com/u/73152895?v=4&s=48" width="48" height="48" alt="siraht" title="siraht"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a> <a href="https://github.com/voidserf"><img src="https://avatars.githubusercontent.com/u/477673?v=4&s=48" width="48" height="48" alt="voidserf" title="voidserf"/></a> <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/YuriNachos"><img src="https://avatars.githubusercontent.com/u/19365375?v=4&s=48" width="48" height="48" alt="YuriNachos" title="YuriNachos"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/Alphonse-arianee"><img src="https://avatars.githubusercontent.com/u/254457365?v=4&s=48" width="48" height="48" alt="Alphonse-arianee" title="Alphonse-arianee"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a>
+  <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a> <a href="https://github.com/cpojer"><img src="https://avatars.githubusercontent.com/u/13352?v=4&s=48" width="48" height="48" alt="cpojer" title="cpojer"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a> <a href="https://github.com/longmaba"><img src="https://avatars.githubusercontent.com/u/9361500?v=4&s=48" width="48" height="48" alt="longmaba" title="longmaba"/></a> <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a>
+  <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a> <a href="https://github.com/ronak-guliani"><img src="https://avatars.githubusercontent.com/u/23518228?v=4&s=48" width="48" height="48" alt="ronak-guliani" title="ronak-guliani"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a> <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
 </p>

SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+If you believe you’ve found a security issue in Clawdbot, please report it privately.
+
+## Reporting
+
+- Email: `steipete@gmail.com`
+- What to include: reproduction steps, impact assessment, and (if possible) a minimal PoC.
+
+## Operational Guidance
+
+For threat model + hardening guidance (including `clawdbot security audit --deep` and `--fix`), see:
+
+- `https://docs.clawd.bot/gateway/security`
+

Swabble/Sources/SwabbleCore/Support/AttributedString+Sentences.swift

@@ -34,8 +34,7 @@ extension AttributedString {
             var ranges: [Range<AttributedString.Index>] = []
             for wordRange in wordRanges {
                 if let lastRange = ranges.last,
-                   self[lastRange].characters.count + self[wordRange].characters.count <= maxLength
-                {
+                   self[lastRange].characters.count + self[wordRange].characters.count <= maxLength {
                     ranges[ranges.count - 1] = lastRange.lowerBound..<wordRange.upperBound
                 } else {
                     ranges.append(wordRange)

Swabble/Sources/SwabbleCore/Support/TranscriptsStore.swift

@@ -13,8 +13,7 @@ public actor TranscriptsStore {
         try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
         fileURL = dir.appendingPathComponent("transcripts.log")
         if let data = try? Data(contentsOf: fileURL),
-           let text = String(data: data, encoding: .utf8)
-        {
+           let text = String(data: data, encoding: .utf8) {
             entries = text.split(separator: "\n").map(String.init).suffix(limit)
         }
     }

Swabble/Sources/SwabbleKit/WakeWordGate.swift

@@ -24,8 +24,7 @@ public struct WakeWordGateConfig: Sendable, Equatable {
     public init(
         triggers: [String],
         minPostTriggerGap: TimeInterval = 0.45,
-        minCommandLength: Int = 1)
-    {
+        minCommandLength: Int = 1) {
         self.triggers = triggers
         self.minPostTriggerGap = minPostTriggerGap
         self.minCommandLength = minCommandLength
@@ -57,6 +56,12 @@ public enum WakeWordGate {
         let tokens: [String]
     }
 
+    private struct MatchCandidate {
+        let index: Int
+        let triggerEnd: TimeInterval
+        let gap: TimeInterval
+    }
+
     public static func match(
         transcript: String,
         segments: [WakeWordSegment],
@@ -68,7 +73,7 @@ public enum WakeWordGate {
         let tokens = normalizeSegments(segments)
         guard !tokens.isEmpty else { return nil }
 
-        var best: (index: Int, triggerEnd: TimeInterval, gap: TimeInterval)?
+        var best: MatchCandidate?
 
         for trigger in triggerTokens {
             let count = trigger.tokens.count
@@ -84,7 +89,7 @@ public enum WakeWordGate {
 
                 if let best, i <= best.index { continue }
 
-                best = (i, triggerEnd, gap)
+                best = MatchCandidate(index: i, triggerEnd: triggerEnd, gap: gap)
             }
         }
 

Swabble/Sources/swabble/CLI/CLIRegistry.swift

@@ -24,7 +24,7 @@ enum CLIRegistry {
             subcommands: [
                 descriptor(for: ServiceInstall.self),
                 descriptor(for: ServiceUninstall.self),
-                descriptor(for: ServiceStatus.self),
+                descriptor(for: ServiceStatus.self)
             ])
         let doctorDesc = descriptor(for: DoctorCommand.self)
         let setupDesc = descriptor(for: SetupCommand.self)
@@ -54,7 +54,7 @@ enum CLIRegistry {
                 startDesc,
                 stopDesc,
                 restartDesc,
-                statusDesc,
+                statusDesc
             ])
         return [root]
     }

Swabble/Sources/swabble/Commands/ServiceCommands.swift

@@ -25,7 +25,7 @@ private enum LaunchdHelper {
             "Label": label,
             "ProgramArguments": [executable, "serve"],
             "RunAtLoad": true,
-            "KeepAlive": true,
+            "KeepAlive": true
         ]
         let data = try PropertyListSerialization.data(fromPropertyList: plist, format: .xml, options: 0)
         try data.write(to: plistURL)

Swabble/Sources/swabble/main.swift

@@ -25,78 +25,123 @@ private func dispatch(invocation: CommandInvocation) async throws {
 
     switch first {
     case "swabble":
-        guard path.count >= 2 else { throw CommanderProgramError.missingSubcommand(command: "swabble") }
-        let sub = path[1]
-        switch sub {
-        case "serve":
-            var cmd = ServeCommand(parsed: parsed)
-            try await cmd.run()
-        case "transcribe":
-            var cmd = TranscribeCommand(parsed: parsed)
-            try await cmd.run()
-        case "test-hook":
-            var cmd = TestHookCommand(parsed: parsed)
-            try await cmd.run()
-        case "mic":
-            guard path.count >= 3 else { throw CommanderProgramError.missingSubcommand(command: "mic") }
-            let micSub = path[2]
-            if micSub == "list" {
-                var cmd = MicList(parsed: parsed)
-                try await cmd.run()
-            } else if micSub == "set" {
-                var cmd = MicSet(parsed: parsed)
-                try await cmd.run()
-            } else {
-                throw CommanderProgramError.unknownSubcommand(command: "mic", name: micSub)
-            }
-        case "service":
-            guard path.count >= 3 else { throw CommanderProgramError.missingSubcommand(command: "service") }
-            let svcSub = path[2]
-            switch svcSub {
-            case "install":
-                var cmd = ServiceInstall()
-                try await cmd.run()
-            case "uninstall":
-                var cmd = ServiceUninstall()
-                try await cmd.run()
-            case "status":
-                var cmd = ServiceStatus()
-                try await cmd.run()
-            default:
-                throw CommanderProgramError.unknownSubcommand(command: "service", name: svcSub)
-            }
-        case "doctor":
-            var cmd = DoctorCommand(parsed: parsed)
-            try await cmd.run()
-        case "setup":
-            var cmd = SetupCommand(parsed: parsed)
-            try await cmd.run()
-        case "health":
-            var cmd = HealthCommand(parsed: parsed)
-            try await cmd.run()
-        case "tail-log":
-            var cmd = TailLogCommand(parsed: parsed)
-            try await cmd.run()
-        case "start":
-            var cmd = StartCommand()
-            try await cmd.run()
-        case "stop":
-            var cmd = StopCommand()
-            try await cmd.run()
-        case "restart":
-            var cmd = RestartCommand()
-            try await cmd.run()
-        case "status":
-            var cmd = StatusCommand()
-            try await cmd.run()
-        default:
-            throw CommanderProgramError.unknownSubcommand(command: "swabble", name: sub)
-        }
+        try await dispatchSwabble(parsed: parsed, path: path)
     default:
         throw CommanderProgramError.unknownCommand(first)
     }
 }
 
+@available(macOS 26.0, *)
+@MainActor
+private func dispatchSwabble(parsed: ParsedValues, path: [String]) async throws {
+    let sub = try subcommand(path, index: 1, command: "swabble")
+    switch sub {
+    case "mic":
+        try await dispatchMic(parsed: parsed, path: path)
+    case "service":
+        try await dispatchService(path: path)
+    default:
+        let handlers = swabbleHandlers(parsed: parsed)
+        guard let handler = handlers[sub] else {
+            throw CommanderProgramError.unknownSubcommand(command: "swabble", name: sub)
+        }
+        try await handler()
+    }
+}
+
+@available(macOS 26.0, *)
+@MainActor
+private func swabbleHandlers(parsed: ParsedValues) -> [String: () async throws -> Void] {
+    [
+        "serve": {
+            var cmd = ServeCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "transcribe": {
+            var cmd = TranscribeCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "test-hook": {
+            var cmd = TestHookCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "doctor": {
+            var cmd = DoctorCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "setup": {
+            var cmd = SetupCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "health": {
+            var cmd = HealthCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "tail-log": {
+            var cmd = TailLogCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "start": {
+            var cmd = StartCommand()
+            try await cmd.run()
+        },
+        "stop": {
+            var cmd = StopCommand()
+            try await cmd.run()
+        },
+        "restart": {
+            var cmd = RestartCommand()
+            try await cmd.run()
+        },
+        "status": {
+            var cmd = StatusCommand()
+            try await cmd.run()
+        }
+    ]
+}
+
+@available(macOS 26.0, *)
+@MainActor
+private func dispatchMic(parsed: ParsedValues, path: [String]) async throws {
+    let micSub = try subcommand(path, index: 2, command: "mic")
+    switch micSub {
+    case "list":
+        var cmd = MicList(parsed: parsed)
+        try await cmd.run()
+    case "set":
+        var cmd = MicSet(parsed: parsed)
+        try await cmd.run()
+    default:
+        throw CommanderProgramError.unknownSubcommand(command: "mic", name: micSub)
+    }
+}
+
+@available(macOS 26.0, *)
+@MainActor
+private func dispatchService(path: [String]) async throws {
+    let svcSub = try subcommand(path, index: 2, command: "service")
+    switch svcSub {
+    case "install":
+        var cmd = ServiceInstall()
+        try await cmd.run()
+    case "uninstall":
+        var cmd = ServiceUninstall()
+        try await cmd.run()
+    case "status":
+        var cmd = ServiceStatus()
+        try await cmd.run()
+    default:
+        throw CommanderProgramError.unknownSubcommand(command: "service", name: svcSub)
+    }
+}
+
+private func subcommand(_ path: [String], index: Int, command: String) throws -> String {
+    guard path.count > index else {
+        throw CommanderProgramError.missingSubcommand(command: command)
+    }
+    return path[index]
+}
+
 if #available(macOS 26.0, *) {
     let exitCode = await runCLI()
     exit(exitCode)

appcast.xml

@@ -2,6 +2,178 @@
 <rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
     <channel>
         <title>Clawdbot</title>
+        <item>
+            <title>2026.1.14-1</title>
+            <pubDate>Thu, 15 Jan 2026 11:14:40 +0000</pubDate>
+            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
+            <sparkle:version>5825</sparkle:version>
+            <sparkle:shortVersionString>2026.1.14-1</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdbot 2026.1.14-1</h2>
+<h3>Highlights</h3>
+<ul>
+<li>Web search: <code>web_search</code>/<code>web_fetch</code> tools (Brave API) + first-time setup in onboarding/configure.</li>
+<li>Browser control: Chrome extension relay takeover mode + remote browser control via <code>clawdbot browser serve</code>.</li>
+<li>Plugins: channel plugins (gateway HTTP hooks) + Zalo plugin + onboarding install flow. (#854) — thanks @longmaba.</li>
+<li>Security: expanded <code>clawdbot security audit</code> (+ <code>--fix</code>), detect-secrets CI scan, and a <code>SECURITY.md</code> reporting policy.</li>
+</ul>
+<h3>Changes</h3>
+<h4>Web Tools</h4>
+<ul>
+<li>Tools: add <code>web_search</code>/<code>web_fetch</code> (Brave API), including helpful setup hints when the key is missing.</li>
+<li>Tools: enable <code>web_fetch</code> by default (unless explicitly disabled in config).</li>
+<li>CLI/Docs: add <code>clawdbot configure --section web</code> for storing Brave API keys and update onboarding tips.</li>
+</ul>
+<h4>Browser / Control UI</h4>
+<ul>
+<li>Browser: add Chrome extension relay takeover mode (toolbar button) + <code>clawdbot browser serve</code> remote control + <code>browser.controlToken</code>.</li>
+<li>Browser: ship a built-in <code>chrome</code> profile for extension relay and start the relay automatically when running locally.</li>
+<li>Browser: default <code>browser.defaultProfile</code> to <code>chrome</code> (existing Chrome takeover mode).</li>
+<li>Browser: add <code>clawdbot browser extension install/path</code> and copy extension path to clipboard.</li>
+<li>Browser: add <code>snapshot refs=aria</code> (Playwright aria-ref ids) for self-resolving refs across <code>snapshot</code> → <code>act</code>.</li>
+<li>Browser: <code>profile="chrome"</code> now defaults to host control and returns clearer “attach a tab” errors.</li>
+<li>Browser: extension mode recovers when only one tab is attached (stale targetId fallback).</li>
+<li>Control UI: show raw any-map entries in config views; move Docs link into the left nav.</li>
+</ul>
+<h4>Plugins</h4>
+<ul>
+<li>Plugins: add plugin HTTP hooks + loader updates to support channel plugins. (#854) — thanks @longmaba.</li>
+<li>Plugins: add onboarding plugin install flow. (#854) — thanks @longmaba.</li>
+<li>Channels: add Matrix plugin (external) with docs + onboarding hooks.</li>
+<li>Voice Call: add Plivo provider (no SDK dependency). (#846) — thanks @vrknetha.</li>
+</ul>
+<h4>Security</h4>
+<ul>
+<li>Security: expand <code>clawdbot security audit</code> checks and publish a <code>SECURITY.md</code> reporting policy.</li>
+<li>Security: extend <code>clawdbot security audit --fix</code> to tighten more sensitive state paths.</li>
+<li>Security: add detect-secrets CI scan and baseline guidance. (#227) — thanks @Hyaxia.</li>
+</ul>
+<h4>Onboarding / Daemon</h4>
+<ul>
+<li>Onboarding: add a security checkpoint prompt (docs link + sandboxing hint); require <code>--accept-risk</code> for <code>--non-interactive</code>.</li>
+<li>Daemon: support profile-aware service names for multi-gateway setups. (#671) — thanks @bjesuiter.</li>
+</ul>
+<h4>Auth / Usage / Config</h4>
+<ul>
+<li>Usage: add MiniMax coding plan usage tracking.</li>
+<li>Auth: label Claude Code CLI auth options. (#915) — thanks @SeanZoR.</li>
+<li>Agents: add optional auth-profile copy prompt on <code>agents add</code> and improve auth error messaging.</li>
+<li>Auth: add dynamic template variables to <code>messages.responsePrefix</code>. (#928) — thanks @sebslight.</li>
+<li>Config: add <code>channels.<provider>.configWrites</code> gating for channel-initiated config writes; migrate Slack channel IDs.</li>
+</ul>
+<h4>Channels</h4>
+<ul>
+<li>Telegram: add message delete action in the message tool. (#903) — thanks @sleontenko.</li>
+<li>WhatsApp: add <code>channels.whatsapp.sendReadReceipts</code> to disable auto read receipts. (#882) — thanks @chrisrodz.</li>
+</ul>
+<h4>Docs</h4>
+<ul>
+<li>Docs: clarify per-agent auth stores, sandboxed skill binaries, and elevated semantics.</li>
+<li>Docs: add FAQ entries for missing provider auth after adding agents and Gemini thinking signature errors.</li>
+<li>Docs: expand gateway security hardening guidance and incident response checklist.</li>
+<li>Docs: document DM history limits for channel DMs. (#883) — thanks @pkrmf.</li>
+<li>Docs: standardize Claude Code CLI naming across docs and prompts. (follow-up to #915)</li>
+<li>Docs: add per-command CLI doc pages and link them from <code>clawdbot <command> --help</code>.</li>
+<li>Docs: add multi-gateway guide (sidebar + nav).</li>
+</ul>
+<h3>Fixes</h3>
+<h4>Gateway / Daemon / Sessions</h4>
+<ul>
+<li>Gateway: forward termination signals to respawned CLI child processes to avoid orphaned systemd runs. (#933) — thanks @roshanasingh4.</li>
+<li>Gateway/UI: ship session defaults in the hello snapshot so the Control UI canonicalizes main session keys (no bare <code>main</code> alias).</li>
+<li>Agents: skip thinking/final tag stripping inside Markdown code spans. (#939) — thanks @ngutman.</li>
+<li>Browser: add tests for snapshot labels/efficient query params and labeled image responses.</li>
+<li>Browser: persist role snapshot refs per CDP target so <code>snapshot</code> → <code>act</code> clicks work even if Playwright returns a different Page instance.</li>
+<li>macOS: ensure launchd log directory exists with a test-only override. (#909) — thanks @roshanasingh4.</li>
+<li>macOS: format ConnectionsStore config to satisfy SwiftFormat lint. (#852) — thanks @mneves75.</li>
+<li>Packaging: run <code>pnpm build</code> on <code>prepack</code> so npm publishes include fresh <code>dist/</code> output.</li>
+<li>Telegram: register dock native commands with underscores to avoid <code>BOT_COMMAND_INVALID</code> (#929, fixes #901) — thanks @grp06.</li>
+<li>Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.</li>
+<li>Agents: make user time zone and 24-hour time explicit in the system prompt. (#859) — thanks @CashWilliams.</li>
+<li>Agents: strip downgraded tool call text without eating adjacent replies and filter thinking-tag leaks. (#905) — thanks @erikpr1994.</li>
+<li>Agents: cap tool call IDs for OpenAI/OpenRouter to avoid request rejections. (#875) — thanks @j1philli.</li>
+<li>Doctor: avoid re-adding WhatsApp config when only legacy ack reactions are set. (#927, fixes #900) — thanks @grp06.</li>
+<li>Agents: scrub tuple <code>items</code> schemas for Gemini tool calls. (#926, fixes #746) — thanks @grp06.</li>
+<li>Agents: stabilize sub-agent announce status from runtime outcomes and normalize Result/Notes. (#835) — thanks @roshanasingh4.</li>
+<li>Apps: use canonical main session keys from gateway defaults across macOS/iOS/Android to avoid creating bare <code>main</code> sessions.</li>
+<li>Embedded runner: suppress raw API error payloads from replies. (#924) — thanks @grp06.</li>
+<li>Auth: normalize Claude Code CLI profile mode to oauth and auto-migrate config. (#855) — thanks @sebslight.</li>
+<li>Daemon: clear persisted launchd disabled state before bootstrap (fixes <code>daemon install</code> after uninstall). (#849) — thanks @ndraiman.</li>
+<li>Sessions: return deep clones (<code>structuredClone</code>) so cached session entries can't be mutated. (#934) — thanks @ronak-guliani.</li>
+<li>Heartbeat: keep <code>updatedAt</code> monotonic when restoring heartbeat sessions. (#934) — thanks @ronak-guliani.</li>
+<li>Agent: clear run context after CLI runs (<code>clearAgentRunContext</code>) to avoid runaway contexts. (#934) — thanks @ronak-guliani.</li>
+<li>Gateway/Dev: ensure <code>pnpm gateway:dev</code> always uses the dev profile config + state (<code>~/.clawdbot-dev</code>).</li>
+</ul>
+<h4>CLI / Onboarding</h4>
+<ul>
+<li>Onboarding: show web search setup at the end (not the beginning).</li>
+<li>Onboarding: show daemon install/restart progress (avoid “blinking cursor”) and fix daemon install output formatting.</li>
+<li>Health: colorize “not configured” provider lines for easier scanning.</li>
+</ul>
+<h4>Control UI / TUI</h4>
+<ul>
+<li>Control UI: load cron run history on job selection and clarify empty-state messaging. (#866)</li>
+<li>UI: use application-defined WebSocket close code and fix dashboard auth query items. (#918) — thanks @rahthakor.</li>
+<li>UI: always apply <code>?token=</code> from URL (fixes unauthorized after re-onboard).</li>
+<li>Browser: add tests for snapshot labels/efficient query params and labeled image responses.</li>
+<li>TUI: render picker overlays via the overlay stack so /models and /settings display. (#921) — thanks @grizzdank.</li>
+<li>TUI: add a bright spinner + elapsed time in the status line for send/stream/run states.</li>
+<li>TUI: show LLM error messages (rate limits, auth, etc.) instead of <code>(no output)</code>.</li>
+</ul>
+<h4>Agents / Auth / Tools / Sandbox</h4>
+<ul>
+<li>Agents: make user time zone and 24-hour time explicit in the system prompt. (#859) — thanks @CashWilliams.</li>
+<li>Agents: strip downgraded tool call text without eating adjacent replies and filter thinking-tag leaks. (#905) — thanks @erikpr1994.</li>
+<li>Agents: cap tool call IDs for OpenAI/OpenRouter to avoid request rejections. (#875) — thanks @j1philli.</li>
+<li>Agents: scrub tuple <code>items</code> schemas for Gemini tool calls. (#926, fixes #746) — thanks @grp06.</li>
+<li>Agents: stabilize sub-agent announce status from runtime outcomes and normalize Result/Notes. (#835) — thanks @roshanasingh4.</li>
+<li>Auth: normalize Claude Code CLI profile mode to oauth and auto-migrate config. (#855) — thanks @sebslight.</li>
+<li>Embedded runner: suppress raw API error payloads from replies. (#924) — thanks @grp06.</li>
+<li>Logging: tolerate <code>EIO</code> from console writes to avoid gateway crashes. (#925, fixes #878) — thanks @grp06.</li>
+<li>Sandbox: restore <code>docker.binds</code> config validation and preserve configured PATH for <code>docker exec</code>. (#873) — thanks @akonyer.</li>
+<li>Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.</li>
+</ul>
+<h4>macOS / Apps</h4>
+<ul>
+<li>macOS: ensure launchd log directory exists with a test-only override. (#909) — thanks @roshanasingh4.</li>
+<li>macOS: format ConnectionsStore config to satisfy SwiftFormat lint. (#852) — thanks @mneves75.</li>
+<li>macOS: pass auth token/password to dashboard URL for authenticated access. (#918) — thanks @rahthakor.</li>
+<li>macOS: reuse launchd gateway auth and skip wizard when gateway config already exists. (#917)</li>
+<li>Apps: use canonical main session keys from gateway defaults across macOS/iOS/Android to avoid creating bare <code>main</code> sessions.</li>
+<li>macOS: fix cron preview/testing payload to use <code>channel</code> key. (#867) — thanks @wes-davis.</li>
+<li>macOS: update cron testing channel arg. (#896) — thanks @ngutman.</li>
+</ul>
+<h4>Channels / Messaging</h4>
+<ul>
+<li>Slack: isolate thread history and avoid inheriting channel transcripts for new threads by default. (#758)</li>
+<li>Slack: respect <code>channels.slack.requireMention</code> default when resolving channel mention gating. (#850) — thanks @evalexpr.</li>
+<li>Slack: drop Socket Mode events with mismatched <code>api_app_id</code>/<code>team_id</code>. (#889) — thanks @roshanasingh4.</li>
+<li>Commands: add native command argument menus across Discord/Slack/Telegram. (#936) — thanks @thewilloftheshadow.</li>
+<li>Discord: isolate autoThread thread context. (#856) — thanks @davidguttman.</li>
+<li>Telegram: honor <code>channels.telegram.timeoutSeconds</code> for grammY API requests. (#863) — thanks @Snaver.</li>
+<li>Telegram: aggregate split inbound messages into one prompt (reduces “one reply per fragment”).</li>
+<li>Telegram: let control commands bypass per-chat sequentialization; always allow abort triggers.</li>
+<li>Telegram: split long captions into media + follow-up text messages. (#907) — thanks @jalehman.</li>
+<li>Telegram: migrate group config when supergroups change chat IDs. (#906) — thanks @sleontenko.</li>
+<li>Telegram: register dock native commands with underscores to avoid <code>BOT_COMMAND_INVALID</code> (#929, fixes #901) — thanks @grp06.</li>
+<li>Messaging: unify markdown formatting + format-first chunking for Slack/Telegram/Signal. (#920) — thanks @TheSethRose.</li>
+<li>iMessage: prefer handle routing for direct-message replies; include imsg RPC error details. (#935)</li>
+<li>WhatsApp: fix context isolation using wrong ID (was bot's number, now conversation ID). (#911) — thanks @tristanmanchester.</li>
+<li>WhatsApp: normalize user JIDs with device suffix for allowlist checks in groups. (#838) — thanks @peschee.</li>
+<li>WhatsApp: harden owner command auth.</li>
+<li>Auto-reply: treat trailing <code>NO_REPLY</code> tokens as silent replies.</li>
+</ul>
+<h4>Config / Doctor / Packaging</h4>
+<ul>
+<li>Config: prevent partial config writes from clobbering unrelated settings (base hash guard + merge patch for connection saves).</li>
+<li>Config/Doctor: remove legacy Clawdis env fallbacks and config/service migrations (Clawdbot-only).</li>
+<li>Doctor: avoid re-adding WhatsApp config when only legacy ack reactions are set. (#927, fixes #900) — thanks @grp06.</li>
+<li>Packaging: run <code>pnpm build</code> on <code>prepack</code> so npm publishes include fresh <code>dist/</code> output.</li>
+</ul>
+<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.14-1/Clawdbot-2026.1.14-1.zip" length="19887144" type="application/octet-stream" sparkle:edSignature="1irKxBLt2eRtns34m/8JsjL/ZzhZQNjahwrxtArTvzaCnidS/MEnpD4nV2SHnhuo8g+fJZQpV9NoCAoEOAinCw=="/>
+        </item>
         <item>
             <title>2026.1.12-2</title>
             <pubDate>Tue, 13 Jan 2026 10:05:25 +0000</pubDate>
@@ -35,22 +207,5 @@
 ]]></description>
             <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.11-3/Clawdbot-2026.1.11-3.zip" length="19860758" type="application/octet-stream" sparkle:edSignature="LbvGUSjc3jGO7aVo2UVA0nEkaJbb3O4iwRBo1TBqoapdTtxnDlS3s6N+Z4vOSLRAoAm22EoZOwbpK9085c7HAQ=="/>
         </item>
-        <item>
-            <title>2026.1.11-2</title>
-            <pubDate>Mon, 12 Jan 2026 10:25:53 +0000</pubDate>
-            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
-            <sparkle:version>5210</sparkle:version>
-            <sparkle:shortVersionString>2026.1.11-2</sparkle:shortVersionString>
-            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>Clawdbot 2026.1.11-2</h2>
-<h3>Fixes</h3>
-<ul>
-<li>Installer: ensure the CLI entrypoint is executable after npm installs.</li>
-<li>Packaging: include <code>dist/plugins/</code> in the npm package to avoid missing module errors.</li>
-</ul>
-<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
-]]></description>
-            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.11-2/Clawdbot-2026.1.11-2.zip" length="19860732" type="application/octet-stream" sparkle:edSignature="0UG+d9v3Qf5F9vs/KozUB404WpHjFBQRVoRuhwtzF8kpU7jJmmGlQzh1c61E+LMN4fHcljpxIwHHrvvIfRyrCw=="/>
-        </item>
     </channel>
 </rss>

apps/android/app/src/main/java/com/clawdbot/android/MainViewModel.kt

@@ -27,6 +27,7 @@ class MainViewModel(app: Application) : AndroidViewModel(app) {
   val remoteAddress: StateFlow<String?> = runtime.remoteAddress
   val isForeground: StateFlow<Boolean> = runtime.isForeground
   val seamColorArgb: StateFlow<Long> = runtime.seamColorArgb
+  val mainSessionKey: StateFlow<String> = runtime.mainSessionKey
 
   val cameraHud: StateFlow<CameraHudState?> = runtime.cameraHud
   val cameraFlashToken: StateFlow<Long> = runtime.cameraFlashToken
@@ -138,7 +139,7 @@ class MainViewModel(app: Application) : AndroidViewModel(app) {
     runtime.handleCanvasA2UIActionFromWebView(payloadJson)
   }
 
-  fun loadChat(sessionKey: String = "main") {
+  fun loadChat(sessionKey: String) {
     runtime.loadChat(sessionKey)
   }
 

apps/android/app/src/main/java/com/clawdbot/android/NodeRuntime.kt

@@ -16,6 +16,7 @@ import com.clawdbot.android.bridge.BridgeDiscovery
 import com.clawdbot.android.bridge.BridgeEndpoint
 import com.clawdbot.android.bridge.BridgePairingClient
 import com.clawdbot.android.bridge.BridgeSession
+import com.clawdbot.android.bridge.BridgeTlsParams
 import com.clawdbot.android.node.CameraCaptureManager
 import com.clawdbot.android.node.LocationCaptureManager
 import com.clawdbot.android.BuildConfig
@@ -78,7 +79,7 @@ class NodeRuntime(context: Context) {
           payloadJson =
             buildJsonObject {
               put("message", JsonPrimitive(command))
-              put("sessionKey", JsonPrimitive(mainSessionKey.value))
+              put("sessionKey", JsonPrimitive(resolveMainSessionKey()))
               put("thinking", JsonPrimitive(chatThinkingLevel.value))
               put("deliver", JsonPrimitive(false))
             }.toString(),
@@ -142,12 +143,13 @@ class NodeRuntime(context: Context) {
   private val session =
     BridgeSession(
       scope = scope,
-      onConnected = { name, remote ->
+      onConnected = { name, remote, mainSessionKey ->
         _statusText.value = "Connected"
         _serverName.value = name
         _remoteAddress.value = remote
         _isConnected.value = true
         _seamColorArgb.value = DEFAULT_SEAM_COLOR_ARGB
+        applyMainSessionKey(mainSessionKey)
         scope.launch { refreshBrandingFromGateway() }
         scope.launch { refreshWakeWordsFromGateway() }
         maybeNavigateToA2uiOnConnect()
@@ -159,6 +161,9 @@ class NodeRuntime(context: Context) {
       onInvoke = { req ->
         handleInvoke(req.command, req.paramsJson)
       },
+      onTlsFingerprint = { stableId, fingerprint ->
+        prefs.saveBridgeTlsFingerprint(stableId, fingerprint)
+      },
     )
 
   private val chat = ChatController(scope = scope, session = session, json = json)
@@ -172,11 +177,31 @@ class NodeRuntime(context: Context) {
     _remoteAddress.value = null
     _isConnected.value = false
     _seamColorArgb.value = DEFAULT_SEAM_COLOR_ARGB
-    _mainSessionKey.value = "main"
+    if (!isCanonicalMainSessionKey(_mainSessionKey.value)) {
+      _mainSessionKey.value = "main"
+    }
+    val mainKey = resolveMainSessionKey()
+    talkMode.setMainSessionKey(mainKey)
+    chat.applyMainSessionKey(mainKey)
     chat.onDisconnected(message)
     showLocalCanvasOnDisconnect()
   }
 
+  private fun applyMainSessionKey(candidate: String?) {
+    val trimmed = candidate?.trim().orEmpty()
+    if (trimmed.isEmpty()) return
+    if (isCanonicalMainSessionKey(_mainSessionKey.value)) return
+    if (_mainSessionKey.value == trimmed) return
+    _mainSessionKey.value = trimmed
+    talkMode.setMainSessionKey(trimmed)
+    chat.applyMainSessionKey(trimmed)
+  }
+
+  private fun resolveMainSessionKey(): String {
+    val trimmed = _mainSessionKey.value.trim()
+    return if (trimmed.isEmpty()) "main" else trimmed
+  }
+
   private fun maybeNavigateToA2uiOnConnect() {
     val a2uiUrl = resolveA2uiHostUrl() ?: return
     val current = canvas.currentUrl()?.trim().orEmpty()
@@ -467,12 +492,17 @@ class NodeRuntime(context: Context) {
     scope.launch {
       _statusText.value = "Connecting…"
       val storedToken = prefs.loadBridgeToken()
+      val tls = resolveTlsParams(endpoint)
       val resolved =
         if (storedToken.isNullOrBlank()) {
           _statusText.value = "Pairing…"
           BridgePairingClient().pairAndHello(
             endpoint = endpoint,
             hello = buildPairingHello(token = null),
+            tls = tls,
+            onTlsFingerprint = { fingerprint ->
+              prefs.saveBridgeTlsFingerprint(endpoint.stableId, fingerprint)
+            },
           )
         } else {
           BridgePairingClient.PairResult(ok = true, token = storedToken.trim())
@@ -489,6 +519,7 @@ class NodeRuntime(context: Context) {
       session.connect(
         endpoint = endpoint,
         hello = buildSessionHello(token = authToken),
+        tls = tls,
       )
     }
   }
@@ -535,6 +566,41 @@ class NodeRuntime(context: Context) {
     session.disconnect()
   }
 
+  private fun resolveTlsParams(endpoint: BridgeEndpoint): BridgeTlsParams? {
+    val stored = prefs.loadBridgeTlsFingerprint(endpoint.stableId)
+    val hinted = endpoint.tlsEnabled || !endpoint.tlsFingerprintSha256.isNullOrBlank()
+    val manual = endpoint.stableId.startsWith("manual|")
+
+    if (hinted) {
+      return BridgeTlsParams(
+        required = true,
+        expectedFingerprint = endpoint.tlsFingerprintSha256 ?: stored,
+        allowTOFU = stored == null,
+        stableId = endpoint.stableId,
+      )
+    }
+
+    if (!stored.isNullOrBlank()) {
+      return BridgeTlsParams(
+        required = true,
+        expectedFingerprint = stored,
+        allowTOFU = false,
+        stableId = endpoint.stableId,
+      )
+    }
+
+    if (manual) {
+      return BridgeTlsParams(
+        required = false,
+        expectedFingerprint = null,
+        allowTOFU = true,
+        stableId = endpoint.stableId,
+      )
+    }
+
+    return null
+  }
+
   fun handleCanvasA2UIActionFromWebView(payloadJson: String) {
     scope.launch {
       val trimmed = payloadJson.trim()
@@ -559,7 +625,7 @@ class NodeRuntime(context: Context) {
         (userActionObj["sourceComponentId"] as? JsonPrimitive)?.content?.trim().orEmpty().ifEmpty { "-" }
       val contextJson = (userActionObj["context"] as? JsonObject)?.toString()
 
-      val sessionKey = "main"
+      val sessionKey = resolveMainSessionKey()
       val message =
         ClawdbotCanvasA2UIAction.formatAgentMessage(
           actionName = name,
@@ -607,8 +673,9 @@ class NodeRuntime(context: Context) {
     }
   }
 
-  fun loadChat(sessionKey: String = "main") {
-    chat.load(sessionKey)
+  fun loadChat(sessionKey: String) {
+    val key = sessionKey.trim().ifEmpty { resolveMainSessionKey() }
+    chat.load(key)
   }
 
   fun refreshChat() {
@@ -701,7 +768,7 @@ class NodeRuntime(context: Context) {
       val raw = ui?.get("seamColor").asStringOrNull()?.trim()
       val sessionCfg = config?.get("session").asObjectOrNull()
       val mainKey = normalizeMainKey(sessionCfg?.get("mainKey").asStringOrNull())
-      _mainSessionKey.value = mainKey
+      applyMainSessionKey(mainKey)
 
       val parsed = parseHexColorArgb(raw)
       _seamColorArgb.value = parsed ?: DEFAULT_SEAM_COLOR_ARGB

apps/android/app/src/main/java/com/clawdbot/android/SecurePrefs.kt

@@ -147,6 +147,16 @@ class SecurePrefs(context: Context) {
     prefs.edit { putString(key, token.trim()) }
   }
 
+  fun loadBridgeTlsFingerprint(stableId: String): String? {
+    val key = "bridge.tls.$stableId"
+    return prefs.getString(key, null)?.trim()?.takeIf { it.isNotEmpty() }
+  }
+
+  fun saveBridgeTlsFingerprint(stableId: String, fingerprint: String) {
+    val key = "bridge.tls.$stableId"
+    prefs.edit { putString(key, fingerprint.trim()) }
+  }
+
   private fun loadOrCreateInstanceId(): String {
     val existing = prefs.getString("node.instanceId", null)?.trim()
     if (!existing.isNullOrBlank()) return existing

apps/android/app/src/main/java/com/clawdbot/android/SessionKey.kt

@@ -4,3 +4,10 @@ internal fun normalizeMainKey(raw: String?): String {
   val trimmed = raw?.trim()
   return if (!trimmed.isNullOrEmpty()) trimmed else "main"
 }
+
+internal fun isCanonicalMainSessionKey(raw: String?): Boolean {
+  val trimmed = raw?.trim().orEmpty()
+  if (trimmed.isEmpty()) return false
+  if (trimmed == "global") return true
+  return trimmed.startsWith("agent:")
+}

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgeDiscovery.kt

@@ -143,6 +143,8 @@ class BridgeDiscovery(
         val gatewayPort = txtInt(resolved, "gatewayPort")
         val bridgePort = txtInt(resolved, "bridgePort")
         val canvasPort = txtInt(resolved, "canvasPort")
+        val tlsEnabled = txtBool(resolved, "bridgeTls")
+        val tlsFingerprint = txt(resolved, "bridgeTlsSha256")
         val id = stableId(serviceName, "local.")
         localById[id] =
           BridgeEndpoint(
@@ -155,6 +157,8 @@ class BridgeDiscovery(
             gatewayPort = gatewayPort,
             bridgePort = bridgePort,
             canvasPort = canvasPort,
+            tlsEnabled = tlsEnabled,
+            tlsFingerprintSha256 = tlsFingerprint,
           )
         publish()
       }
@@ -209,6 +213,11 @@ class BridgeDiscovery(
     return txt(info, key)?.toIntOrNull()
   }
 
+  private fun txtBool(info: NsdServiceInfo, key: String): Boolean {
+    val raw = txt(info, key)?.trim()?.lowercase() ?: return false
+    return raw == "1" || raw == "true" || raw == "yes"
+  }
+
   private suspend fun refreshUnicast(domain: String) {
     val ptrName = "${serviceType}${domain}"
     val ptrMsg = lookupUnicastMessage(ptrName, Type.PTR) ?: return
@@ -252,6 +261,8 @@ class BridgeDiscovery(
       val gatewayPort = txtIntValue(txt, "gatewayPort")
       val bridgePort = txtIntValue(txt, "bridgePort")
       val canvasPort = txtIntValue(txt, "canvasPort")
+      val tlsEnabled = txtBoolValue(txt, "bridgeTls")
+      val tlsFingerprint = txtValue(txt, "bridgeTlsSha256")
       val id = stableId(instanceName, domain)
       next[id] =
         BridgeEndpoint(
@@ -264,6 +275,8 @@ class BridgeDiscovery(
           gatewayPort = gatewayPort,
           bridgePort = bridgePort,
           canvasPort = canvasPort,
+          tlsEnabled = tlsEnabled,
+          tlsFingerprintSha256 = tlsFingerprint,
         )
     }
 
@@ -474,6 +487,11 @@ class BridgeDiscovery(
     return txtValue(records, key)?.toIntOrNull()
   }
 
+  private fun txtBoolValue(records: List<TXTRecord>, key: String): Boolean {
+    val raw = txtValue(records, key)?.trim()?.lowercase() ?: return false
+    return raw == "1" || raw == "true" || raw == "yes"
+  }
+
   private fun decodeDnsTxtString(raw: String): String {
     // dnsjava treats TXT as opaque bytes and decodes as ISO-8859-1 to preserve bytes.
     // Our TXT payload is UTF-8 (written by the gateway), so re-decode when possible.

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgeEndpoint.kt

@@ -10,6 +10,8 @@ data class BridgeEndpoint(
   val gatewayPort: Int? = null,
   val bridgePort: Int? = null,
   val canvasPort: Int? = null,
+  val tlsEnabled: Boolean = false,
+  val tlsFingerprintSha256: String? = null,
 ) {
   companion object {
     fun manual(host: String, port: Int): BridgeEndpoint =
@@ -18,6 +20,8 @@ data class BridgeEndpoint(
         name = "$host:$port",
         host = host,
         port = port,
+        tlsEnabled = false,
+        tlsFingerprintSha256 = null,
       )
   }
 }

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgePairingClient.kt

@@ -14,7 +14,6 @@ import java.io.BufferedWriter
 import java.io.InputStreamReader
 import java.io.OutputStreamWriter
 import java.net.InetSocketAddress
-import java.net.Socket
 
 class BridgePairingClient {
   private val json = Json { ignoreUnknownKeys = true }
@@ -33,95 +32,120 @@ class BridgePairingClient {
 
   data class PairResult(val ok: Boolean, val token: String?, val error: String? = null)
 
-  suspend fun pairAndHello(endpoint: BridgeEndpoint, hello: Hello): PairResult =
+  suspend fun pairAndHello(
+    endpoint: BridgeEndpoint,
+    hello: Hello,
+    tls: BridgeTlsParams? = null,
+    onTlsFingerprint: ((String) -> Unit)? = null,
+  ): PairResult =
     withContext(Dispatchers.IO) {
-      val socket = Socket()
-      socket.tcpNoDelay = true
-      try {
-        socket.connect(InetSocketAddress(endpoint.host, endpoint.port), 8_000)
-        socket.soTimeout = 60_000
-
-        val reader = BufferedReader(InputStreamReader(socket.getInputStream(), Charsets.UTF_8))
-        val writer = BufferedWriter(OutputStreamWriter(socket.getOutputStream(), Charsets.UTF_8))
-
-        fun send(line: String) {
-          writer.write(line)
-          writer.write("\n")
-          writer.flush()
-        }
-
-        fun sendJson(obj: JsonObject) = send(obj.toString())
-
-        sendJson(
-          buildJsonObject {
-            put("type", JsonPrimitive("hello"))
-            put("nodeId", JsonPrimitive(hello.nodeId))
-            hello.displayName?.let { put("displayName", JsonPrimitive(it)) }
-            hello.token?.let { put("token", JsonPrimitive(it)) }
-            hello.platform?.let { put("platform", JsonPrimitive(it)) }
-            hello.version?.let { put("version", JsonPrimitive(it)) }
-            hello.deviceFamily?.let { put("deviceFamily", JsonPrimitive(it)) }
-            hello.modelIdentifier?.let { put("modelIdentifier", JsonPrimitive(it)) }
-            hello.caps?.let { put("caps", JsonArray(it.map(::JsonPrimitive))) }
-            hello.commands?.let { put("commands", JsonArray(it.map(::JsonPrimitive))) }
-          },
-        )
-
-        val firstObj = json.parseToJsonElement(reader.readLine()).asObjectOrNull()
-          ?: return@withContext PairResult(ok = false, token = null, error = "unexpected bridge response")
-        when (firstObj["type"].asStringOrNull()) {
-          "hello-ok" -> PairResult(ok = true, token = hello.token)
-          "error" -> {
-            val code = firstObj["code"].asStringOrNull() ?: "UNAVAILABLE"
-            val message = firstObj["message"].asStringOrNull() ?: "pairing required"
-            if (code != "NOT_PAIRED" && code != "UNAUTHORIZED") {
-              return@withContext PairResult(ok = false, token = null, error = "$code: $message")
-            }
-
-            sendJson(
-              buildJsonObject {
-                put("type", JsonPrimitive("pair-request"))
-                put("nodeId", JsonPrimitive(hello.nodeId))
-                hello.displayName?.let { put("displayName", JsonPrimitive(it)) }
-                hello.platform?.let { put("platform", JsonPrimitive(it)) }
-                hello.version?.let { put("version", JsonPrimitive(it)) }
-                hello.deviceFamily?.let { put("deviceFamily", JsonPrimitive(it)) }
-                hello.modelIdentifier?.let { put("modelIdentifier", JsonPrimitive(it)) }
-                hello.caps?.let { put("caps", JsonArray(it.map(::JsonPrimitive))) }
-                hello.commands?.let { put("commands", JsonArray(it.map(::JsonPrimitive))) }
-              },
-            )
-
-            while (true) {
-              val nextLine = reader.readLine() ?: break
-              val next = json.parseToJsonElement(nextLine).asObjectOrNull() ?: continue
-              when (next["type"].asStringOrNull()) {
-                "pair-ok" -> {
-                  val token = next["token"].asStringOrNull()
-                  return@withContext PairResult(ok = !token.isNullOrBlank(), token = token)
-                }
-                "error" -> {
-                  val c = next["code"].asStringOrNull() ?: "UNAVAILABLE"
-                  val m = next["message"].asStringOrNull() ?: "pairing failed"
-                  return@withContext PairResult(ok = false, token = null, error = "$c: $m")
-                }
-              }
-            }
-            PairResult(ok = false, token = null, error = "pairing failed")
-          }
-          else -> PairResult(ok = false, token = null, error = "unexpected bridge response")
-        }
-      } catch (e: Exception) {
-        val message = e.message?.trim().orEmpty().ifEmpty { "gateway unreachable" }
-        PairResult(ok = false, token = null, error = message)
-      } finally {
+      if (tls != null) {
         try {
-          socket.close()
-        } catch (_: Throwable) {
-          // ignore
+          return@withContext pairAndHelloWithTls(endpoint, hello, tls, onTlsFingerprint)
+        } catch (e: Exception) {
+          if (tls.required) throw e
         }
       }
+      pairAndHelloWithTls(endpoint, hello, null, null)
     }
+
+  private fun pairAndHelloWithTls(
+    endpoint: BridgeEndpoint,
+    hello: Hello,
+    tls: BridgeTlsParams?,
+    onTlsFingerprint: ((String) -> Unit)?,
+  ): PairResult {
+    val socket =
+      createBridgeSocket(tls) { fingerprint ->
+        onTlsFingerprint?.invoke(fingerprint)
+      }
+    socket.tcpNoDelay = true
+    try {
+      socket.connect(InetSocketAddress(endpoint.host, endpoint.port), 8_000)
+      socket.soTimeout = 60_000
+      startTlsHandshakeIfNeeded(socket)
+
+      val reader = BufferedReader(InputStreamReader(socket.getInputStream(), Charsets.UTF_8))
+      val writer = BufferedWriter(OutputStreamWriter(socket.getOutputStream(), Charsets.UTF_8))
+
+      fun send(line: String) {
+        writer.write(line)
+        writer.write("\n")
+        writer.flush()
+      }
+
+      fun sendJson(obj: JsonObject) = send(obj.toString())
+
+      sendJson(
+        buildJsonObject {
+          put("type", JsonPrimitive("hello"))
+          put("nodeId", JsonPrimitive(hello.nodeId))
+          hello.displayName?.let { put("displayName", JsonPrimitive(it)) }
+          hello.token?.let { put("token", JsonPrimitive(it)) }
+          hello.platform?.let { put("platform", JsonPrimitive(it)) }
+          hello.version?.let { put("version", JsonPrimitive(it)) }
+          hello.deviceFamily?.let { put("deviceFamily", JsonPrimitive(it)) }
+          hello.modelIdentifier?.let { put("modelIdentifier", JsonPrimitive(it)) }
+          hello.caps?.let { put("caps", JsonArray(it.map(::JsonPrimitive))) }
+          hello.commands?.let { put("commands", JsonArray(it.map(::JsonPrimitive))) }
+        },
+      )
+
+      val firstObj = json.parseToJsonElement(reader.readLine()).asObjectOrNull()
+        ?: return PairResult(ok = false, token = null, error = "unexpected bridge response")
+      return when (firstObj["type"].asStringOrNull()) {
+        "hello-ok" -> PairResult(ok = true, token = hello.token)
+        "error" -> {
+          val code = firstObj["code"].asStringOrNull() ?: "UNAVAILABLE"
+          val message = firstObj["message"].asStringOrNull() ?: "pairing required"
+          if (code != "NOT_PAIRED" && code != "UNAUTHORIZED") {
+            return PairResult(ok = false, token = null, error = "$code: $message")
+          }
+
+          sendJson(
+            buildJsonObject {
+              put("type", JsonPrimitive("pair-request"))
+              put("nodeId", JsonPrimitive(hello.nodeId))
+              hello.displayName?.let { put("displayName", JsonPrimitive(it)) }
+              hello.platform?.let { put("platform", JsonPrimitive(it)) }
+              hello.version?.let { put("version", JsonPrimitive(it)) }
+              hello.deviceFamily?.let { put("deviceFamily", JsonPrimitive(it)) }
+              hello.modelIdentifier?.let { put("modelIdentifier", JsonPrimitive(it)) }
+              hello.caps?.let { put("caps", JsonArray(it.map(::JsonPrimitive))) }
+              hello.commands?.let { put("commands", JsonArray(it.map(::JsonPrimitive))) }
+            },
+          )
+
+          while (true) {
+            val nextLine = reader.readLine() ?: break
+            val next = json.parseToJsonElement(nextLine).asObjectOrNull() ?: continue
+            when (next["type"].asStringOrNull()) {
+              "pair-ok" -> {
+                val token = next["token"].asStringOrNull()
+                return PairResult(ok = !token.isNullOrBlank(), token = token)
+              }
+              "error" -> {
+                val c = next["code"].asStringOrNull() ?: "UNAVAILABLE"
+                val m = next["message"].asStringOrNull() ?: "pairing failed"
+                return PairResult(ok = false, token = null, error = "$c: $m")
+              }
+            }
+          }
+          PairResult(ok = false, token = null, error = "pairing failed")
+        }
+        else -> PairResult(ok = false, token = null, error = "unexpected bridge response")
+      }
+    } catch (e: Exception) {
+      val message = e.message?.trim().orEmpty().ifEmpty { "gateway unreachable" }
+      return PairResult(ok = false, token = null, error = message)
+    } finally {
+      try {
+        socket.close()
+      } catch (_: Throwable) {
+        // ignore
+      }
+    }
+  }
 }
 
 private fun JsonElement?.asObjectOrNull(): JsonObject? = this as? JsonObject

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgeSession.kt

@@ -31,10 +31,11 @@ import java.util.concurrent.ConcurrentHashMap
 
 class BridgeSession(
   private val scope: CoroutineScope,
-  private val onConnected: (serverName: String, remoteAddress: String?) -> Unit,
+  private val onConnected: (serverName: String, remoteAddress: String?, mainSessionKey: String?) -> Unit,
   private val onDisconnected: (message: String) -> Unit,
   private val onEvent: (event: String, payloadJson: String?) -> Unit,
   private val onInvoke: suspend (InvokeRequest) -> InvokeResult,
+  private val onTlsFingerprint: ((stableId: String, fingerprint: String) -> Unit)? = null,
 ) {
   data class Hello(
     val nodeId: String,
@@ -64,12 +65,19 @@ class BridgeSession(
   private val writeLock = Mutex()
   private val pending = ConcurrentHashMap<String, CompletableDeferred<RpcResponse>>()
   @Volatile private var canvasHostUrl: String? = null
+  @Volatile private var mainSessionKey: String? = null
 
-  private var desired: Pair<BridgeEndpoint, Hello>? = null
+  private data class DesiredConnection(
+    val endpoint: BridgeEndpoint,
+    val hello: Hello,
+    val tls: BridgeTlsParams?,
+  )
+
+  private var desired: DesiredConnection? = null
   private var job: Job? = null
 
-  fun connect(endpoint: BridgeEndpoint, hello: Hello) {
-    desired = endpoint to hello
+  fun connect(endpoint: BridgeEndpoint, hello: Hello, tls: BridgeTlsParams? = null) {
+    desired = DesiredConnection(endpoint, hello, tls)
     if (job == null) {
       job = scope.launch(Dispatchers.IO) { runLoop() }
     }
@@ -77,7 +85,7 @@ class BridgeSession(
 
   suspend fun updateHello(hello: Hello) {
     val target = desired ?: return
-    desired = target.first to hello
+    desired = target.copy(hello = hello)
     val conn = currentConnection ?: return
     conn.sendJson(buildHelloJson(hello))
   }
@@ -90,11 +98,13 @@ class BridgeSession(
       job?.cancelAndJoin()
       job = null
       canvasHostUrl = null
+      mainSessionKey = null
       onDisconnected("Offline")
     }
   }
 
   fun currentCanvasHostUrl(): String? = canvasHostUrl
+  fun currentMainSessionKey(): String? = mainSessionKey
 
   suspend fun sendEvent(event: String, payloadJson: String?) {
     val conn = currentConnection ?: return
@@ -162,10 +172,10 @@ class BridgeSession(
         continue
       }
 
-      val (endpoint, hello) = target
+      val (endpoint, hello, tls) = target
       try {
         onDisconnected(if (attempt == 0) "Connecting…" else "Reconnecting…")
-        connectOnce(endpoint, hello)
+        connectOnce(endpoint, hello, tls)
         attempt = 0
       } catch (err: Throwable) {
         attempt += 1
@@ -189,48 +199,66 @@ class BridgeSession(
     return InvokeResult.error(code = "UNAVAILABLE", message = msg)
   }
 
-  private suspend fun connectOnce(endpoint: BridgeEndpoint, hello: Hello) =
+  private suspend fun connectOnce(endpoint: BridgeEndpoint, hello: Hello, tls: BridgeTlsParams?) =
     withContext(Dispatchers.IO) {
-      val socket = Socket()
-      socket.tcpNoDelay = true
-      socket.connect(InetSocketAddress(endpoint.host, endpoint.port), 8_000)
-      socket.soTimeout = 0
-
-      val reader = BufferedReader(InputStreamReader(socket.getInputStream(), Charsets.UTF_8))
-      val writer = BufferedWriter(OutputStreamWriter(socket.getOutputStream(), Charsets.UTF_8))
-
-      val conn = Connection(socket, reader, writer, writeLock)
-      currentConnection = conn
-
-      try {
-        conn.sendJson(buildHelloJson(hello))
-
-        val firstLine = reader.readLine() ?: throw IllegalStateException("bridge closed connection")
-        val first = json.parseToJsonElement(firstLine).asObjectOrNull()
-          ?: throw IllegalStateException("unexpected bridge response")
-        when (first["type"].asStringOrNull()) {
-          "hello-ok" -> {
-            val name = first["serverName"].asStringOrNull() ?: "Bridge"
-            val rawCanvasUrl = first["canvasHostUrl"].asStringOrNull()?.trim()?.ifEmpty { null }
-            canvasHostUrl = normalizeCanvasHostUrl(rawCanvasUrl, endpoint)
-            if (BuildConfig.DEBUG) {
-              // Local JVM unit tests use android.jar stubs; Log.d can throw "not mocked".
-              runCatching {
-                android.util.Log.d(
-                  "ClawdbotBridge",
-                  "canvasHostUrl resolved=${canvasHostUrl ?: "none"} (raw=${rawCanvasUrl ?: "none"})",
-                )
-              }
-            }
-            onConnected(name, conn.remoteAddress)
-          }
-          "error" -> {
-            val code = first["code"].asStringOrNull() ?: "UNAVAILABLE"
-            val msg = first["message"].asStringOrNull() ?: "connect failed"
-            throw IllegalStateException("$code: $msg")
-          }
-          else -> throw IllegalStateException("unexpected bridge response")
+      if (tls != null) {
+        try {
+          connectWithSocket(endpoint, hello, tls)
+          return@withContext
+        } catch (err: Throwable) {
+          if (tls.required) throw err
         }
+      }
+      connectWithSocket(endpoint, hello, null)
+    }
+
+  private fun connectWithSocket(endpoint: BridgeEndpoint, hello: Hello, tls: BridgeTlsParams?) {
+    val socket =
+      createBridgeSocket(tls) { fingerprint ->
+        onTlsFingerprint?.invoke(tls?.stableId ?: endpoint.stableId, fingerprint)
+      }
+    socket.tcpNoDelay = true
+    socket.connect(InetSocketAddress(endpoint.host, endpoint.port), 8_000)
+    socket.soTimeout = 0
+    startTlsHandshakeIfNeeded(socket)
+
+    val reader = BufferedReader(InputStreamReader(socket.getInputStream(), Charsets.UTF_8))
+    val writer = BufferedWriter(OutputStreamWriter(socket.getOutputStream(), Charsets.UTF_8))
+
+    val conn = Connection(socket, reader, writer, writeLock)
+    currentConnection = conn
+
+    try {
+      conn.sendJson(buildHelloJson(hello))
+
+      val firstLine = reader.readLine() ?: throw IllegalStateException("bridge closed connection")
+      val first = json.parseToJsonElement(firstLine).asObjectOrNull()
+        ?: throw IllegalStateException("unexpected bridge response")
+      when (first["type"].asStringOrNull()) {
+        "hello-ok" -> {
+          val name = first["serverName"].asStringOrNull() ?: "Bridge"
+          val rawCanvasUrl = first["canvasHostUrl"].asStringOrNull()?.trim()?.ifEmpty { null }
+          val rawMainSessionKey = first["mainSessionKey"].asStringOrNull()?.trim()?.ifEmpty { null }
+          canvasHostUrl = normalizeCanvasHostUrl(rawCanvasUrl, endpoint)
+          mainSessionKey = rawMainSessionKey
+          if (BuildConfig.DEBUG) {
+            // Local JVM unit tests use android.jar stubs; Log.d can throw "not mocked".
+            runCatching {
+              android.util.Log.d(
+                "ClawdbotBridge",
+                "canvasHostUrl resolved=${canvasHostUrl ?: "none"} (raw=${rawCanvasUrl ?: "none"})",
+              )
+            }
+          }
+          onConnected(name, conn.remoteAddress, rawMainSessionKey)
+        }
+        "error" -> {
+          val code = first["code"].asStringOrNull() ?: "UNAVAILABLE"
+          val msg = first["message"].asStringOrNull() ?: "connect failed"
+          throw IllegalStateException("$code: $msg")
+        }
+        else -> throw IllegalStateException("unexpected bridge response")
+      }
 
         while (scope.isActive) {
           val line = reader.readLine() ?: break

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgeTls.kt

@@ -0,0 +1,79 @@
+package com.clawdbot.android.bridge
+
+import java.net.Socket
+import java.security.MessageDigest
+import java.security.SecureRandom
+import java.security.cert.CertificateException
+import java.security.cert.X509Certificate
+import javax.net.ssl.SSLContext
+import javax.net.ssl.SSLSocket
+import javax.net.ssl.TrustManagerFactory
+import javax.net.ssl.X509TrustManager
+
+data class BridgeTlsParams(
+  val required: Boolean,
+  val expectedFingerprint: String?,
+  val allowTOFU: Boolean,
+  val stableId: String,
+)
+
+fun createBridgeSocket(params: BridgeTlsParams?, onStore: ((String) -> Unit)? = null): Socket {
+  if (params == null) return Socket()
+  val expected = params.expectedFingerprint?.let(::normalizeFingerprint)
+  val defaultTrust = defaultTrustManager()
+  val trustManager =
+    object : X509TrustManager {
+      override fun checkClientTrusted(chain: Array<X509Certificate>, authType: String) {
+        defaultTrust.checkClientTrusted(chain, authType)
+      }
+
+      override fun checkServerTrusted(chain: Array<X509Certificate>, authType: String) {
+        if (chain.isEmpty()) throw CertificateException("empty certificate chain")
+        val fingerprint = sha256Hex(chain[0].encoded)
+        if (expected != null) {
+          if (fingerprint != expected) {
+            throw CertificateException("bridge TLS fingerprint mismatch")
+          }
+          return
+        }
+        if (params.allowTOFU) {
+          onStore?.invoke(fingerprint)
+          return
+        }
+        defaultTrust.checkServerTrusted(chain, authType)
+      }
+
+      override fun getAcceptedIssuers(): Array<X509Certificate> = defaultTrust.acceptedIssuers
+    }
+
+  val context = SSLContext.getInstance("TLS")
+  context.init(null, arrayOf(trustManager), SecureRandom())
+  return context.socketFactory.createSocket()
+}
+
+fun startTlsHandshakeIfNeeded(socket: Socket) {
+  if (socket is SSLSocket) {
+    socket.startHandshake()
+  }
+}
+
+private fun defaultTrustManager(): X509TrustManager {
+  val factory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm())
+  factory.init(null as java.security.KeyStore?)
+  val trust =
+    factory.trustManagers.firstOrNull { it is X509TrustManager } as? X509TrustManager
+  return trust ?: throw IllegalStateException("No default X509TrustManager found")
+}
+
+private fun sha256Hex(data: ByteArray): String {
+  val digest = MessageDigest.getInstance("SHA-256").digest(data)
+  val out = StringBuilder(digest.size * 2)
+  for (byte in digest) {
+    out.append(String.format("%02x", byte))
+  }
+  return out.toString()
+}
+
+private fun normalizeFingerprint(raw: String): String {
+  return raw.lowercase().filter { it in '0'..'9' || it in 'a'..'f' }
+}

apps/android/app/src/main/java/com/clawdbot/android/chat/ChatController.kt

@@ -71,12 +71,21 @@ class ChatController(
     _sessionId.value = null
   }
 
-  fun load(sessionKey: String = "main") {
+  fun load(sessionKey: String) {
     val key = sessionKey.trim().ifEmpty { "main" }
     _sessionKey.value = key
     scope.launch { bootstrap(forceHealth = true) }
   }
 
+  fun applyMainSessionKey(mainSessionKey: String) {
+    val trimmed = mainSessionKey.trim()
+    if (trimmed.isEmpty()) return
+    if (_sessionKey.value == trimmed) return
+    if (_sessionKey.value != "main") return
+    _sessionKey.value = trimmed
+    scope.launch { bootstrap(forceHealth = true) }
+  }
+
   fun refresh() {
     scope.launch { bootstrap(forceHealth = true) }
   }

apps/android/app/src/main/java/com/clawdbot/android/ui/chat/ChatComposer.kt

@@ -44,6 +44,7 @@ import com.clawdbot.android.chat.ChatSessionEntry
 fun ChatComposer(
   sessionKey: String,
   sessions: List<ChatSessionEntry>,
+  mainSessionKey: String,
   healthOk: Boolean,
   thinkingLevel: String,
   pendingRunCount: Int,
@@ -61,7 +62,7 @@ fun ChatComposer(
   var showThinkingMenu by remember { mutableStateOf(false) }
   var showSessionMenu by remember { mutableStateOf(false) }
 
-  val sessionOptions = resolveSessionChoices(sessionKey, sessions)
+  val sessionOptions = resolveSessionChoices(sessionKey, sessions, mainSessionKey = mainSessionKey)
   val currentSessionLabel =
     sessionOptions.firstOrNull { it.key == sessionKey }?.displayName ?: sessionKey
 

apps/android/app/src/main/java/com/clawdbot/android/ui/chat/ChatSheetContent.kt

@@ -33,13 +33,14 @@ fun ChatSheetContent(viewModel: MainViewModel) {
   val pendingRunCount by viewModel.pendingRunCount.collectAsState()
   val healthOk by viewModel.chatHealthOk.collectAsState()
   val sessionKey by viewModel.chatSessionKey.collectAsState()
+  val mainSessionKey by viewModel.mainSessionKey.collectAsState()
   val thinkingLevel by viewModel.chatThinkingLevel.collectAsState()
   val streamingAssistantText by viewModel.chatStreamingAssistantText.collectAsState()
   val pendingToolCalls by viewModel.chatPendingToolCalls.collectAsState()
   val sessions by viewModel.chatSessions.collectAsState()
 
-  LaunchedEffect(Unit) {
-    viewModel.loadChat("main")
+  LaunchedEffect(mainSessionKey) {
+    viewModel.loadChat(mainSessionKey)
     viewModel.refreshChatSessions(limit = 200)
   }
 
@@ -85,6 +86,7 @@ fun ChatSheetContent(viewModel: MainViewModel) {
     ChatComposer(
       sessionKey = sessionKey,
       sessions = sessions,
+      mainSessionKey = mainSessionKey,
       healthOk = healthOk,
       thinkingLevel = thinkingLevel,
       pendingRunCount = pendingRunCount,

apps/android/app/src/main/java/com/clawdbot/android/ui/chat/SessionFilters.kt

@@ -2,20 +2,23 @@ package com.clawdbot.android.ui.chat
 
 import com.clawdbot.android.chat.ChatSessionEntry
 
-private const val MAIN_SESSION_KEY = "main"
 private const val RECENT_WINDOW_MS = 24 * 60 * 60 * 1000L
 
 fun resolveSessionChoices(
   currentSessionKey: String,
   sessions: List<ChatSessionEntry>,
+  mainSessionKey: String,
   nowMs: Long = System.currentTimeMillis(),
 ): List<ChatSessionEntry> {
-  val current = currentSessionKey.trim()
+  val mainKey = mainSessionKey.trim().ifEmpty { "main" }
+  val current = currentSessionKey.trim().let { if (it == "main" && mainKey != "main") mainKey else it }
+  val aliasKey = if (mainKey == "main") null else "main"
   val cutoff = nowMs - RECENT_WINDOW_MS
   val sorted = sessions.sortedByDescending { it.updatedAtMs ?: 0L }
   val recent = mutableListOf<ChatSessionEntry>()
   val seen = mutableSetOf<String>()
   for (entry in sorted) {
+    if (aliasKey != null && entry.key == aliasKey) continue
     if (!seen.add(entry.key)) continue
     if ((entry.updatedAtMs ?: 0L) < cutoff) continue
     recent.add(entry)
@@ -23,13 +26,13 @@ fun resolveSessionChoices(
 
   val result = mutableListOf<ChatSessionEntry>()
   val included = mutableSetOf<String>()
-  val mainEntry = sorted.firstOrNull { it.key == MAIN_SESSION_KEY }
+  val mainEntry = sorted.firstOrNull { it.key == mainKey }
   if (mainEntry != null) {
     result.add(mainEntry)
-    included.add(MAIN_SESSION_KEY)
-  } else if (current == MAIN_SESSION_KEY) {
-    result.add(ChatSessionEntry(key = MAIN_SESSION_KEY, updatedAtMs = null))
-    included.add(MAIN_SESSION_KEY)
+    included.add(mainKey)
+  } else if (current == mainKey) {
+    result.add(ChatSessionEntry(key = mainKey, updatedAtMs = null))
+    included.add(mainKey)
   }
 
   for (entry in recent) {

apps/android/app/src/main/java/com/clawdbot/android/voice/TalkModeManager.kt

@@ -21,6 +21,7 @@ import android.speech.tts.UtteranceProgressListener
 import android.util.Log
 import androidx.core.content.ContextCompat
 import com.clawdbot.android.bridge.BridgeSession
+import com.clawdbot.android.isCanonicalMainSessionKey
 import com.clawdbot.android.normalizeMainKey
 import java.net.HttpURLConnection
 import java.net.URL
@@ -116,6 +117,13 @@ class TalkModeManager(
     chatSubscribedSessionKey = null
   }
 
+  fun setMainSessionKey(sessionKey: String?) {
+    val trimmed = sessionKey?.trim().orEmpty()
+    if (trimmed.isEmpty()) return
+    if (isCanonicalMainSessionKey(mainSessionKey)) return
+    mainSessionKey = trimmed
+  }
+
   fun setEnabled(enabled: Boolean) {
     if (_isEnabled.value == enabled) return
     _isEnabled.value = enabled
@@ -827,7 +835,9 @@ class TalkModeManager(
       val key = talk?.get("apiKey")?.asStringOrNull()?.trim()?.takeIf { it.isNotEmpty() }
       val interrupt = talk?.get("interruptOnSpeech")?.asBooleanOrNull()
 
-      mainSessionKey = mainKey
+      if (!isCanonicalMainSessionKey(mainSessionKey)) {
+        mainSessionKey = mainKey
+      }
       defaultVoiceId = voice ?: envVoice?.takeIf { it.isNotEmpty() } ?: sagVoice?.takeIf { it.isNotEmpty() }
       voiceAliases = aliases
       if (!voiceOverrideActive) currentVoiceId = defaultVoiceId

apps/android/app/src/test/java/com/clawdbot/android/bridge/BridgeSessionTest.kt

@@ -30,7 +30,7 @@ class BridgeSessionTest {
     val session =
       BridgeSession(
         scope = scope,
-        onConnected = { _, _ -> connected.complete(Unit) },
+        onConnected = { _, _, _ -> connected.complete(Unit) },
         onDisconnected = { /* ignore */ },
         onEvent = { _, _ -> /* ignore */ },
         onInvoke = { BridgeSession.InvokeResult.ok(null) },
@@ -97,7 +97,7 @@ class BridgeSessionTest {
     val session =
       BridgeSession(
         scope = scope,
-        onConnected = { _, _ -> connected.complete(Unit) },
+        onConnected = { _, _, _ -> connected.complete(Unit) },
         onDisconnected = { /* ignore */ },
         onEvent = { _, _ -> /* ignore */ },
         onInvoke = { BridgeSession.InvokeResult.ok(null) },
@@ -167,7 +167,7 @@ class BridgeSessionTest {
     val session =
       BridgeSession(
         scope = scope,
-        onConnected = { _, _ -> connected.complete(Unit) },
+        onConnected = { _, _, _ -> connected.complete(Unit) },
         onDisconnected = { /* ignore */ },
         onEvent = { _, _ -> /* ignore */ },
         onInvoke = { throw IllegalStateException("FOO_BAR: boom") },
@@ -239,7 +239,7 @@ class BridgeSessionTest {
     val session =
       BridgeSession(
         scope = scope,
-        onConnected = { _, _ -> connected.countDown() },
+        onConnected = { _, _, _ -> connected.countDown() },
         onDisconnected = { /* ignore */ },
         onEvent = { _, _ -> /* ignore */ },
         onInvoke = { BridgeSession.InvokeResult.ok(null) },

apps/android/app/src/test/java/com/clawdbot/android/ui/chat/SessionFiltersTest.kt

@@ -19,7 +19,7 @@ class SessionFiltersTest {
         ChatSessionEntry(key = "recent-2", updatedAtMs = recent2),
       )
 
-    val result = resolveSessionChoices("main", sessions, nowMs = now).map { it.key }
+    val result = resolveSessionChoices("main", sessions, mainSessionKey = "main", nowMs = now).map { it.key }
     assertEquals(listOf("main", "recent-1", "recent-2"), result)
   }
 
@@ -29,7 +29,7 @@ class SessionFiltersTest {
     val recent = now - 10 * 60 * 1000L
     val sessions = listOf(ChatSessionEntry(key = "main", updatedAtMs = recent))
 
-    val result = resolveSessionChoices("custom", sessions, nowMs = now).map { it.key }
+    val result = resolveSessionChoices("custom", sessions, mainSessionKey = "main", nowMs = now).map { it.key }
     assertEquals(listOf("main", "custom"), result)
   }
 }

apps/ios/Sources/Bridge/BridgeClient.swift

@@ -10,10 +10,36 @@ actor BridgeClient {
     func pairAndHello(
         endpoint: NWEndpoint,
         hello: BridgeHello,
+        tls: BridgeTLSParams? = nil,
+        onStatus: (@Sendable (String) -> Void)? = nil) async throws -> String
+    {
+        do {
+            return try await self.pairAndHelloOnce(
+                endpoint: endpoint,
+                hello: hello,
+                tls: tls,
+                onStatus: onStatus)
+        } catch {
+            if let tls, !tls.required {
+                return try await self.pairAndHelloOnce(
+                    endpoint: endpoint,
+                    hello: hello,
+                    tls: nil,
+                    onStatus: onStatus)
+            }
+            throw error
+        }
+    }
+
+    private func pairAndHelloOnce(
+        endpoint: NWEndpoint,
+        hello: BridgeHello,
+        tls: BridgeTLSParams?,
         onStatus: (@Sendable (String) -> Void)? = nil) async throws -> String
     {
         self.lineBuffer = Data()
-        let connection = NWConnection(to: endpoint, using: .tcp)
+        let params = self.makeParameters(tls: tls)
+        let connection = NWConnection(to: endpoint, using: params)
         let queue = DispatchQueue(label: "com.clawdbot.ios.bridge-client")
         defer { connection.cancel() }
         try await self.withTimeout(seconds: 8, purpose: "connect") {
@@ -142,6 +168,18 @@ actor BridgeClient {
         }
     }
 
+    private func makeParameters(tls: BridgeTLSParams?) -> NWParameters {
+        if let tlsOptions = makeBridgeTLSOptions(tls) {
+            let tcpOptions = NWProtocolTCP.Options()
+            let params = NWParameters(tls: tlsOptions, tcp: tcpOptions)
+            params.includePeerToPeer = true
+            return params
+        }
+        let params = NWParameters.tcp
+        params.includePeerToPeer = true
+        return params
+    }
+
     private struct TimeoutError: LocalizedError, Sendable {
         var purpose: String
         var seconds: Int

apps/ios/Sources/Bridge/BridgeConnectionController.swift

@@ -10,6 +10,7 @@ protocol BridgePairingClient: Sendable {
     func pairAndHello(
         endpoint: NWEndpoint,
         hello: BridgeHello,
+        tls: BridgeTLSParams?,
         onStatus: (@Sendable (String) -> Void)?) async throws -> String
 }
 
@@ -115,9 +116,12 @@ final class BridgeConnectionController {
 
             self.didAutoConnect = true
             let endpoint = NWEndpoint.hostPort(host: NWEndpoint.Host(manualHost), port: port)
+            let stableID = BridgeEndpointID.stableID(endpoint)
+            let tlsParams = self.resolveManualTLSParams(stableID: stableID)
             self.startAutoConnect(
                 endpoint: endpoint,
-                bridgeStableID: BridgeEndpointID.stableID(endpoint),
+                bridgeStableID: stableID,
+                tls: tlsParams,
                 token: token,
                 instanceId: instanceId)
             return
@@ -135,10 +139,12 @@ final class BridgeConnectionController {
 
         guard let target = self.bridges.first(where: { $0.stableID == targetStableID }) else { return }
 
+        let tlsParams = self.resolveDiscoveredTLSParams(bridge: target)
         self.didAutoConnect = true
         self.startAutoConnect(
             endpoint: target.endpoint,
             bridgeStableID: target.stableID,
+            tls: tlsParams,
             token: token,
             instanceId: instanceId)
     }
@@ -182,6 +188,7 @@ final class BridgeConnectionController {
     private func startAutoConnect(
         endpoint: NWEndpoint,
         bridgeStableID: String,
+        tls: BridgeTLSParams?,
         token: String,
         instanceId: String)
     {
@@ -193,6 +200,7 @@ final class BridgeConnectionController {
                 let refreshed = try await self.bridgeClientFactory().pairAndHello(
                     endpoint: endpoint,
                     hello: hello,
+                    tls: tls,
                     onStatus: { status in
                         Task { @MainActor in
                             appModel.bridgeStatusText = status
@@ -208,6 +216,7 @@ final class BridgeConnectionController {
                 appModel.connectToBridge(
                     endpoint: endpoint,
                     bridgeStableID: bridgeStableID,
+                    tls: tls,
                     hello: self.makeHello(token: resolvedToken))
             } catch {
                 await MainActor.run {
@@ -217,6 +226,47 @@ final class BridgeConnectionController {
         }
     }
 
+    private func resolveDiscoveredTLSParams(
+        bridge: BridgeDiscoveryModel.DiscoveredBridge) -> BridgeTLSParams?
+    {
+        let stableID = bridge.stableID
+        let stored = BridgeTLSStore.loadFingerprint(stableID: stableID)
+
+        if bridge.tlsEnabled || bridge.tlsFingerprintSha256 != nil {
+            return BridgeTLSParams(
+                required: true,
+                expectedFingerprint: bridge.tlsFingerprintSha256 ?? stored,
+                allowTOFU: stored == nil,
+                storeKey: stableID)
+        }
+
+        if let stored {
+            return BridgeTLSParams(
+                required: true,
+                expectedFingerprint: stored,
+                allowTOFU: false,
+                storeKey: stableID)
+        }
+
+        return nil
+    }
+
+    private func resolveManualTLSParams(stableID: String) -> BridgeTLSParams? {
+        if let stored = BridgeTLSStore.loadFingerprint(stableID: stableID) {
+            return BridgeTLSParams(
+                required: true,
+                expectedFingerprint: stored,
+                allowTOFU: false,
+                storeKey: stableID)
+        }
+
+        return BridgeTLSParams(
+            required: false,
+            expectedFingerprint: nil,
+            allowTOFU: true,
+            storeKey: stableID)
+    }
+
     private func resolvedDisplayName(defaults: UserDefaults) -> String {
         let key = "node.displayName"
         let existing = defaults.string(forKey: key)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""

apps/ios/Sources/Bridge/BridgeDiscoveryModel.swift

@@ -23,6 +23,8 @@ final class BridgeDiscoveryModel {
         var gatewayPort: Int?
         var bridgePort: Int?
         var canvasPort: Int?
+        var tlsEnabled: Bool
+        var tlsFingerprintSha256: String?
         var cliPath: String?
     }
 
@@ -90,6 +92,8 @@ final class BridgeDiscoveryModel {
                                 gatewayPort: Self.txtIntValue(txt, key: "gatewayPort"),
                                 bridgePort: Self.txtIntValue(txt, key: "bridgePort"),
                                 canvasPort: Self.txtIntValue(txt, key: "canvasPort"),
+                                tlsEnabled: Self.txtBoolValue(txt, key: "bridgeTls"),
+                                tlsFingerprintSha256: Self.txtValue(txt, key: "bridgeTlsSha256"),
                                 cliPath: Self.txtValue(txt, key: "cliPath"))
                         default:
                             return nil
@@ -214,4 +218,9 @@ final class BridgeDiscoveryModel {
         guard let raw = self.txtValue(dict, key: key) else { return nil }
         return Int(raw)
     }
+
+    private static func txtBoolValue(_ dict: [String: String], key: String) -> Bool {
+        guard let raw = self.txtValue(dict, key: key)?.lowercased() else { return false }
+        return raw == "1" || raw == "true" || raw == "yes"
+    }
 }

apps/ios/Sources/Bridge/BridgeSession.swift

@@ -26,6 +26,7 @@ actor BridgeSession {
 
     private(set) var state: State = .idle
     private var canvasHostUrl: String?
+    private var mainSessionKey: String?
 
     func currentCanvasHostUrl() -> String? {
         self.canvasHostUrl
@@ -68,15 +69,42 @@ actor BridgeSession {
     func connect(
         endpoint: NWEndpoint,
         hello: BridgeHello,
-        onConnected: (@Sendable (String) async -> Void)? = nil,
+        tls: BridgeTLSParams? = nil,
+        onConnected: (@Sendable (String, String?) async -> Void)? = nil,
         onInvoke: @escaping @Sendable (BridgeInvokeRequest) async -> BridgeInvokeResponse)
         async throws
     {
         await self.disconnect()
         self.state = .connecting
+        do {
+            try await self.connectOnce(
+                endpoint: endpoint,
+                hello: hello,
+                tls: tls,
+                onConnected: onConnected,
+                onInvoke: onInvoke)
+        } catch {
+            if let tls, !tls.required {
+                try await self.connectOnce(
+                    endpoint: endpoint,
+                    hello: hello,
+                    tls: nil,
+                    onConnected: onConnected,
+                    onInvoke: onInvoke)
+                return
+            }
+            throw error
+        }
+    }
 
-        let params = NWParameters.tcp
-        params.includePeerToPeer = true
+    private func connectOnce(
+        endpoint: NWEndpoint,
+        hello: BridgeHello,
+        tls: BridgeTLSParams?,
+        onConnected: (@Sendable (String, String?) async -> Void)?,
+        onInvoke: @escaping @Sendable (BridgeInvokeRequest) async -> BridgeInvokeResponse) async throws
+    {
+        let params = self.makeParameters(tls: tls)
         let connection = NWConnection(to: endpoint, using: params)
         let queue = DispatchQueue(label: "com.clawdbot.ios.bridge-session")
         self.connection = connection
@@ -107,7 +135,9 @@ actor BridgeSession {
             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)
+            let mainKey = ok.mainSessionKey?.trimmingCharacters(in: .whitespacesAndNewlines)
+            self.mainSessionKey = (mainKey?.isEmpty == false) ? mainKey : nil
+            await onConnected?(ok.serverName, self.mainSessionKey)
         } else if base.type == "error" {
             let err = try self.decoder.decode(BridgeErrorFrame.self, from: data)
             self.state = .failed(message: "\(err.code): \(err.message)")
@@ -217,6 +247,7 @@ actor BridgeSession {
         self.queue = nil
         self.buffer = Data()
         self.canvasHostUrl = nil
+        self.mainSessionKey = nil
 
         let pending = self.pendingRPC.values
         self.pendingRPC.removeAll()
@@ -234,6 +265,10 @@ actor BridgeSession {
         self.state = .idle
     }
 
+    func currentMainSessionKey() -> String? {
+        self.mainSessionKey
+    }
+
     private func beginRPC(
         id: String,
         request: BridgeRPCRequest,
@@ -247,6 +282,18 @@ actor BridgeSession {
         }
     }
 
+    private func makeParameters(tls: BridgeTLSParams?) -> NWParameters {
+        if let tlsOptions = makeBridgeTLSOptions(tls) {
+            let tcpOptions = NWProtocolTCP.Options()
+            let params = NWParameters(tls: tlsOptions, tcp: tcpOptions)
+            params.includePeerToPeer = true
+            return params
+        }
+        let params = NWParameters.tcp
+        params.includePeerToPeer = true
+        return params
+    }
+
     private func timeoutRPC(id: String) async {
         guard let cont = self.pendingRPC.removeValue(forKey: id) else { return }
         cont.resume(throwing: NSError(domain: "Bridge", code: 15, userInfo: [

apps/ios/Sources/Bridge/BridgeTLS.swift

@@ -0,0 +1,67 @@
+import CryptoKit
+import Foundation
+import Network
+import Security
+
+struct BridgeTLSParams: Sendable {
+    let required: Bool
+    let expectedFingerprint: String?
+    let allowTOFU: Bool
+    let storeKey: String?
+}
+
+enum BridgeTLSStore {
+    private static let service = "com.clawdbot.bridge.tls"
+
+    static func loadFingerprint(stableID: String) -> String? {
+        KeychainStore.loadString(service: service, account: stableID)?.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    static func saveFingerprint(_ value: String, stableID: String) {
+        _ = KeychainStore.saveString(value, service: service, account: stableID)
+    }
+}
+
+func makeBridgeTLSOptions(_ params: BridgeTLSParams?) -> NWProtocolTLS.Options? {
+    guard let params else { return nil }
+    let options = NWProtocolTLS.Options()
+    let expected = params.expectedFingerprint.map(normalizeBridgeFingerprint)
+    let allowTOFU = params.allowTOFU
+    let storeKey = params.storeKey
+
+    sec_protocol_options_set_verify_block(
+        options.securityProtocolOptions,
+        { _, trust, complete in
+            guard let trust else {
+                complete(false)
+                return
+            }
+            if let cert = SecTrustGetCertificateAtIndex(trust, 0) {
+                let data = SecCertificateCopyData(cert) as Data
+                let fingerprint = sha256Hex(data)
+                if let expected {
+                    complete(fingerprint == expected)
+                    return
+                }
+                if allowTOFU {
+                    if let storeKey { BridgeTLSStore.saveFingerprint(fingerprint, stableID: storeKey) }
+                    complete(true)
+                    return
+                }
+            }
+            let ok = SecTrustEvaluateWithError(trust, nil)
+            complete(ok)
+        },
+        DispatchQueue(label: "com.clawdbot.bridge.tls.verify"))
+
+    return options
+}
+
+private func sha256Hex(_ data: Data) -> String {
+    let digest = SHA256.hash(data: data)
+    return digest.map { String(format: "%02x", $0) }.joined()
+}
+
+private func normalizeBridgeFingerprint(_ raw: String) -> String {
+    raw.lowercased().filter { $0.isHexDigit }
+}

apps/ios/Sources/Chat/ChatSheet.swift

@@ -6,7 +6,7 @@ struct ChatSheet: View {
     @State private var viewModel: ClawdbotChatViewModel
     private let userAccent: Color?
 
-    init(bridge: BridgeSession, sessionKey: String = "main", userAccent: Color? = nil) {
+    init(bridge: BridgeSession, sessionKey: String, userAccent: Color? = nil) {
         let transport = IOSBridgeChatTransport(bridge: bridge)
         self._viewModel = State(
             initialValue: ClawdbotChatViewModel(

apps/ios/Sources/Model/NodeAppModel.swift

@@ -109,7 +109,7 @@ final class NodeAppModel {
         let host = UserDefaults.standard.string(forKey: "node.displayName") ?? UIDevice.current.name
         let instanceId = (UserDefaults.standard.string(forKey: "node.instanceId") ?? "ios-node").lowercased()
         let contextJSON = ClawdbotCanvasA2UIAction.compactJSON(userAction["context"])
-        let sessionKey = "main"
+        let sessionKey = self.mainSessionKey
 
         let messageContext = ClawdbotCanvasA2UIAction.AgentMessageContext(
             actionName: name,
@@ -205,6 +205,7 @@ final class NodeAppModel {
     func connectToBridge(
         endpoint: NWEndpoint,
         bridgeStableID: String,
+        tls: BridgeTLSParams?,
         hello: BridgeHello)
     {
         self.bridgeTask?.cancel()
@@ -232,12 +233,16 @@ final class NodeAppModel {
                     try await self.bridge.connect(
                         endpoint: endpoint,
                         hello: hello,
-                        onConnected: { [weak self] serverName in
+                        tls: tls,
+                        onConnected: { [weak self] serverName, mainSessionKey in
                             guard let self else { return }
                             await MainActor.run {
                                 self.bridgeStatusText = "Connected"
                                 self.bridgeServerName = serverName
                             }
+                            await MainActor.run {
+                                self.applyMainSessionKey(mainSessionKey)
+                            }
                             if let addr = await self.bridge.currentRemoteAddress() {
                                 await MainActor.run {
                                     self.bridgeRemoteAddress = addr
@@ -286,7 +291,10 @@ final class NodeAppModel {
                 self.bridgeRemoteAddress = nil
                 self.connectedBridgeID = nil
                 self.seamColorHex = nil
-                self.mainSessionKey = "main"
+                if !SessionKey.isCanonicalMainSessionKey(self.mainSessionKey) {
+                    self.mainSessionKey = "main"
+                    self.talkMode.updateMainSessionKey(self.mainSessionKey)
+                }
                 self.showLocalCanvasOnDisconnect()
             }
         }
@@ -303,10 +311,23 @@ final class NodeAppModel {
         self.bridgeRemoteAddress = nil
         self.connectedBridgeID = nil
         self.seamColorHex = nil
-        self.mainSessionKey = "main"
+        if !SessionKey.isCanonicalMainSessionKey(self.mainSessionKey) {
+            self.mainSessionKey = "main"
+            self.talkMode.updateMainSessionKey(self.mainSessionKey)
+        }
         self.showLocalCanvasOnDisconnect()
     }
 
+    private func applyMainSessionKey(_ key: String?) {
+        let trimmed = (key ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        let current = self.mainSessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        if SessionKey.isCanonicalMainSessionKey(current) { return }
+        if trimmed == current { return }
+        self.mainSessionKey = trimmed
+        self.talkMode.updateMainSessionKey(trimmed)
+    }
+
     var seamColor: Color {
         Self.color(fromHex: self.seamColorHex) ?? Self.defaultSeamColor
     }
@@ -335,7 +356,10 @@ final class NodeAppModel {
             let mainKey = SessionKey.normalizeMainKey(session?["mainKey"] as? String)
             await MainActor.run {
                 self.seamColorHex = raw.isEmpty ? nil : raw
-                self.mainSessionKey = mainKey
+                if !SessionKey.isCanonicalMainSessionKey(self.mainSessionKey) {
+                    self.mainSessionKey = mainKey
+                    self.talkMode.updateMainSessionKey(mainKey)
+                }
             }
         } catch {
             // ignore

apps/ios/Sources/SessionKey.swift

@@ -5,4 +5,11 @@ enum SessionKey {
         let trimmed = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
         return trimmed.isEmpty ? "main" : trimmed
     }
+
+    static func isCanonicalMainSessionKey(_ value: String?) -> Bool {
+        let trimmed = (value ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return false }
+        if trimmed == "global" { return true }
+        return trimmed.hasPrefix("agent:")
+    }
 }

apps/ios/Sources/Settings/SettingsTab.swift

@@ -407,9 +407,11 @@ struct SettingsTab: View {
                 modelIdentifier: self.modelIdentifier(),
                 caps: self.currentCaps(),
                 commands: self.currentCommands())
+            let tlsParams = self.resolveDiscoveredTLSParams(bridge: bridge)
             let token = try await BridgeClient().pairAndHello(
                 endpoint: bridge.endpoint,
                 hello: hello,
+                tls: tlsParams,
                 onStatus: { status in
                     Task { @MainActor in
                         statusStore.text = status
@@ -426,6 +428,7 @@ struct SettingsTab: View {
             self.appModel.connectToBridge(
                 endpoint: bridge.endpoint,
                 bridgeStableID: bridge.stableID,
+                tls: tlsParams,
                 hello: BridgeHello(
                     nodeId: self.instanceId,
                     displayName: self.displayName,
@@ -462,6 +465,8 @@ struct SettingsTab: View {
         defer { self.connectingBridgeID = nil }
 
         let endpoint: NWEndpoint = .hostPort(host: NWEndpoint.Host(host), port: port)
+        let stableID = BridgeEndpointID.stableID(endpoint)
+        let tlsParams = self.resolveManualTLSParams(stableID: stableID)
 
         do {
             let statusStore = self.connectStatus
@@ -485,6 +490,7 @@ struct SettingsTab: View {
             let token = try await BridgeClient().pairAndHello(
                 endpoint: endpoint,
                 hello: hello,
+                tls: tlsParams,
                 onStatus: { status in
                     Task { @MainActor in
                         statusStore.text = status
@@ -500,7 +506,8 @@ struct SettingsTab: View {
 
             self.appModel.connectToBridge(
                 endpoint: endpoint,
-                bridgeStableID: BridgeEndpointID.stableID(endpoint),
+                bridgeStableID: stableID,
+                tls: tlsParams,
                 hello: BridgeHello(
                     nodeId: self.instanceId,
                     displayName: self.displayName,
@@ -517,6 +524,47 @@ struct SettingsTab: View {
         }
     }
 
+    private func resolveDiscoveredTLSParams(
+        bridge: BridgeDiscoveryModel.DiscoveredBridge) -> BridgeTLSParams?
+    {
+        let stableID = bridge.stableID
+        let stored = BridgeTLSStore.loadFingerprint(stableID: stableID)
+
+        if bridge.tlsEnabled || bridge.tlsFingerprintSha256 != nil {
+            return BridgeTLSParams(
+                required: true,
+                expectedFingerprint: bridge.tlsFingerprintSha256 ?? stored,
+                allowTOFU: stored == nil,
+                storeKey: stableID)
+        }
+
+        if let stored {
+            return BridgeTLSParams(
+                required: true,
+                expectedFingerprint: stored,
+                allowTOFU: false,
+                storeKey: stableID)
+        }
+
+        return nil
+    }
+
+    private func resolveManualTLSParams(stableID: String) -> BridgeTLSParams? {
+        if let stored = BridgeTLSStore.loadFingerprint(stableID: stableID) {
+            return BridgeTLSParams(
+                required: true,
+                expectedFingerprint: stored,
+                allowTOFU: false,
+                storeKey: stableID)
+        }
+
+        return BridgeTLSParams(
+            required: false,
+            expectedFingerprint: nil,
+            allowTOFU: true,
+            storeKey: stableID)
+    }
+
     private static func primaryIPv4Address() -> String? {
         var addrList: UnsafeMutablePointer<ifaddrs>?
         guard getifaddrs(&addrList) == 0, let first = addrList else { return nil }

apps/ios/Sources/Voice/TalkModeManager.swift

@@ -53,6 +53,13 @@ final class TalkModeManager: NSObject {
         self.bridge = bridge
     }
 
+    func updateMainSessionKey(_ sessionKey: String?) {
+        let trimmed = (sessionKey ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        if SessionKey.isCanonicalMainSessionKey(self.mainSessionKey) { return }
+        self.mainSessionKey = trimmed
+    }
+
     func setEnabled(_ enabled: Bool) {
         self.isEnabled = enabled
         if enabled {
@@ -649,7 +656,10 @@ final class TalkModeManager: NSObject {
             guard let config = json["config"] as? [String: Any] else { return }
             let talk = config["talk"] as? [String: Any]
             let session = config["session"] as? [String: Any]
-            self.mainSessionKey = SessionKey.normalizeMainKey(session?["mainKey"] as? String)
+            let mainKey = SessionKey.normalizeMainKey(session?["mainKey"] as? String)
+            if !SessionKey.isCanonicalMainSessionKey(self.mainSessionKey) {
+                self.mainSessionKey = mainKey
+            }
             self.defaultVoiceId = (talk?["voiceId"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
             if let aliases = talk?["voiceAliases"] as? [String: Any] {
                 var resolved: [String: String] = [:]

apps/ios/Tests/BridgeConnectionControllerTests.swift

@@ -27,6 +27,7 @@ private actor MockBridgePairingClient: BridgePairingClient {
     func pairAndHello(
         endpoint: NWEndpoint,
         hello: BridgeHello,
+        tls: BridgeTLSParams?,
         onStatus: (@Sendable (String) -> Void)?) async throws -> String
     {
         self.lastToken = hello.token
@@ -244,6 +245,8 @@ private func withKeychainValues<T>(
             gatewayPort: 18789,
             bridgePort: 18790,
             canvasPort: 18793,
+            tlsEnabled: false,
+            tlsFingerprintSha256: nil,
             cliPath: nil)
         let mock = MockBridgePairingClient(resultToken: "new-token")
         let account = "bridge-token.ios-test"
@@ -292,6 +295,8 @@ private func withKeychainValues<T>(
             gatewayPort: 18789,
             bridgePort: 18790,
             canvasPort: 18793,
+            tlsEnabled: false,
+            tlsFingerprintSha256: nil,
             cliPath: nil)
         let bridgeB = BridgeDiscoveryModel.DiscoveredBridge(
             name: "Gateway B",
@@ -303,6 +308,8 @@ private func withKeychainValues<T>(
             gatewayPort: 28789,
             bridgePort: 28790,
             canvasPort: 28793,
+            tlsEnabled: false,
+            tlsFingerprintSha256: nil,
             cliPath: nil)
 
         let mock = MockBridgePairingClient(resultToken: "token-ok")

apps/macos/Sources/Clawdbot/AppState.swift

@@ -170,6 +170,10 @@ final class AppState {
         didSet { self.ifNotPreview { UserDefaults.standard.set(self.canvasEnabled, forKey: canvasEnabledKey) } }
     }
 
+    var systemRunPolicy: SystemRunPolicy {
+        didSet { self.ifNotPreview { MacNodeConfigFile.setSystemRunPolicy(self.systemRunPolicy) } }
+    }
+
     /// Tracks whether the Canvas panel is currently visible (not persisted).
     var canvasPanelVisible: Bool = false
 
@@ -292,6 +296,7 @@ final class AppState {
         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.systemRunPolicy = SystemRunPolicy.load()
         self.peekabooBridgeEnabled = UserDefaults.standard
             .object(forKey: peekabooBridgeEnabledKey) as? Bool ?? true
         if !self.isPreview {

apps/macos/Sources/Clawdbot/Bridge/BridgeConnectionHandler.swift

@@ -282,7 +282,12 @@ actor BridgeConnectionHandler {
             do {
                 try await self.send(BridgePairOk(type: "pair-ok", token: token))
                 self.isAuthenticated = true
-                try await self.send(BridgeHelloOk(type: "hello-ok", serverName: serverName))
+                let mainSessionKey = await GatewayConnection.shared.mainSessionKey()
+                try await self.send(
+                    BridgeHelloOk(
+                        type: "hello-ok",
+                        serverName: serverName,
+                        mainSessionKey: mainSessionKey))
             } catch {
                 self.logger.error("bridge send pair-ok failed: \(error.localizedDescription, privacy: .public)")
             }
@@ -298,7 +303,12 @@ actor BridgeConnectionHandler {
         case .ok:
             self.isAuthenticated = true
             do {
-                try await self.send(BridgeHelloOk(type: "hello-ok", serverName: serverName))
+                let mainSessionKey = await GatewayConnection.shared.mainSessionKey()
+                try await self.send(
+                    BridgeHelloOk(
+                        type: "hello-ok",
+                        serverName: serverName,
+                        mainSessionKey: mainSessionKey))
             } catch {
                 self.logger.error("bridge send hello-ok failed: \(error.localizedDescription, privacy: .public)")
             }

apps/macos/Sources/Clawdbot/ConfigStore.swift

@@ -19,6 +19,7 @@ enum ConfigStore {
     }
 
     private static let overrideStore = OverrideStore()
+    @MainActor private static var lastHash: String?
 
     private static func isRemoteMode() async -> Bool {
         let overrides = await self.overrideStore.overrides
@@ -75,6 +76,7 @@ enum ConfigStore {
                 method: .configGet,
                 params: nil,
                 timeoutMs: 8000)
+            self.lastHash = snap.hash
             return snap.config?.mapValues { $0.foundationValue } ?? [:]
         } catch {
             return nil
@@ -83,17 +85,24 @@ enum ConfigStore {
 
     @MainActor
     private static func saveToGateway(_ root: [String: Any]) async throws {
+        if self.lastHash == nil {
+            _ = await self.loadFromGateway()
+        }
         let data = try JSONSerialization.data(withJSONObject: root, options: [.prettyPrinted, .sortedKeys])
         guard let raw = String(data: data, encoding: .utf8) else {
             throw NSError(domain: "ConfigStore", code: 1, userInfo: [
                 NSLocalizedDescriptionKey: "Failed to encode config.",
             ])
         }
-        let params: [String: AnyCodable] = ["raw": AnyCodable(raw)]
+        var params: [String: AnyCodable] = ["raw": AnyCodable(raw)]
+        if let baseHash = self.lastHash {
+            params["baseHash"] = AnyCodable(baseHash)
+        }
         _ = try await GatewayConnection.shared.requestRaw(
             method: .configSet,
             params: params,
             timeoutMs: 10000)
+        _ = await self.loadFromGateway()
     }
 
     #if DEBUG

apps/macos/Sources/Clawdbot/ConnectionsStore+Config.swift

@@ -2,6 +2,16 @@ import ClawdbotProtocol
 import Foundation
 
 extension ConnectionsStore {
+    var isTelegramTokenLocked: Bool {
+        self.snapshot?.decodeChannel("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)?
+            .tokenSource == "env"
+    }
+
+    var isDiscordTokenLocked: Bool {
+        self.snapshot?.decodeChannel("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)?
+            .tokenSource == "env"
+    }
+
     func loadConfig() async {
         do {
             let snap: ConfigSnapshot = try await GatewayConnection.shared.requestDecoded(
@@ -12,6 +22,7 @@ extension ConnectionsStore {
                 ? "Config invalid; fix it in ~/.clawdbot/clawdbot.json."
                 : nil
             self.configRoot = snap.config?.mapValues { $0.foundationValue } ?? [:]
+            self.configHash = snap.hash
             self.configLoaded = true
 
             self.applyUIConfig(snap)
@@ -34,10 +45,23 @@ extension ConnectionsStore {
         AppStateStore.shared.seamColorHex = rawSeam.isEmpty ? nil : rawSeam
     }
 
+    private func resolveChannelConfig(_ snap: ConfigSnapshot, key: String) -> [String: AnyCodable]? {
+        if let channels = snap.config?["channels"]?.dictionaryValue,
+           let entry = channels[key]?.dictionaryValue
+        {
+            return entry
+        }
+        return snap.config?[key]?.dictionaryValue
+    }
+
     private func applyTelegramConfig(_ snap: ConfigSnapshot) {
-        let telegram = snap.config?["telegram"]?.dictionaryValue
+        let telegram = self.resolveChannelConfig(snap, key: "telegram")
         self.telegramToken = telegram?["botToken"]?.stringValue ?? ""
-        self.telegramRequireMention = telegram?["requireMention"]?.boolValue ?? true
+        let groups = telegram?["groups"]?.dictionaryValue
+        let defaultGroup = groups?["*"]?.dictionaryValue
+        self.telegramRequireMention = defaultGroup?["requireMention"]?.boolValue
+            ?? telegram?["requireMention"]?.boolValue
+            ?? true
         self.telegramAllowFrom = self.stringList(from: telegram?["allowFrom"]?.arrayValue)
         self.telegramProxy = telegram?["proxy"]?.stringValue ?? ""
         self.telegramWebhookUrl = telegram?["webhookUrl"]?.stringValue ?? ""
@@ -46,7 +70,7 @@ extension ConnectionsStore {
     }
 
     private func applyDiscordConfig(_ snap: ConfigSnapshot) {
-        let discord = snap.config?["discord"]?.dictionaryValue
+        let discord = self.resolveChannelConfig(snap, key: "discord")
         self.discordEnabled = discord?["enabled"]?.boolValue ?? true
         self.discordToken = discord?["token"]?.stringValue ?? ""
 
@@ -122,7 +146,7 @@ extension ConnectionsStore {
     }
 
     private func applySignalConfig(_ snap: ConfigSnapshot) {
-        let signal = snap.config?["signal"]?.dictionaryValue
+        let signal = self.resolveChannelConfig(snap, key: "signal")
         self.signalEnabled = signal?["enabled"]?.boolValue ?? true
         self.signalAccount = signal?["account"]?.stringValue ?? ""
         self.signalHttpUrl = signal?["httpUrl"]?.stringValue ?? ""
@@ -139,7 +163,7 @@ extension ConnectionsStore {
     }
 
     private func applyIMessageConfig(_ snap: ConfigSnapshot) {
-        let imessage = snap.config?["imessage"]?.dictionaryValue
+        let imessage = self.resolveChannelConfig(snap, key: "imessage")
         self.imessageEnabled = imessage?["enabled"]?.boolValue ?? true
         self.imessageCliPath = imessage?["cliPath"]?.stringValue ?? ""
         self.imessageDbPath = imessage?["dbPath"]?.stringValue ?? ""
@@ -150,6 +174,15 @@ extension ConnectionsStore {
         self.imessageMediaMaxMb = self.numberString(from: imessage?["mediaMaxMb"])
     }
 
+    private func channelConfigRoot(for key: String) -> [String: Any] {
+        if let channels = self.configRoot["channels"] as? [String: Any],
+           let entry = channels[key] as? [String: Any]
+        {
+            return entry
+        }
+        return self.configRoot[key] as? [String: Any] ?? [:]
+    }
+
     func saveTelegramConfig() async {
         guard !self.isSavingConfig else { return }
         self.isSavingConfig = true
@@ -158,30 +191,24 @@ extension ConnectionsStore {
             await self.loadConfig()
         }
 
-        var telegram: [String: Any] = (self.configRoot["telegram"] as? [String: Any]) ?? [:]
-        let token = self.trimmed(self.telegramToken)
-        if token.isEmpty {
-            telegram.removeValue(forKey: "botToken")
-        } else {
-            telegram["botToken"] = token
+        var telegram: [String: Any] = [:]
+        if !self.isTelegramTokenLocked {
+            self.setPatchString(&telegram, key: "botToken", value: self.telegramToken)
         }
-
-        telegram["requireMention"] = self.telegramRequireMention
-
+        telegram["requireMention"] = NSNull()
+        telegram["groups"] = [
+            "*": [
+                "requireMention": self.telegramRequireMention,
+            ],
+        ]
         let allow = self.splitCsv(self.telegramAllowFrom)
-        if allow.isEmpty {
-            telegram.removeValue(forKey: "allowFrom")
-        } else {
-            telegram["allowFrom"] = allow
-        }
+        self.setPatchList(&telegram, key: "allowFrom", values: allow)
+        self.setPatchString(&telegram, key: "proxy", value: self.telegramProxy)
+        self.setPatchString(&telegram, key: "webhookUrl", value: self.telegramWebhookUrl)
+        self.setPatchString(&telegram, key: "webhookSecret", value: self.telegramWebhookSecret)
+        self.setPatchString(&telegram, key: "webhookPath", value: self.telegramWebhookPath)
 
-        self.setOptionalString(&telegram, key: "proxy", value: self.telegramProxy)
-        self.setOptionalString(&telegram, key: "webhookUrl", value: self.telegramWebhookUrl)
-        self.setOptionalString(&telegram, key: "webhookSecret", value: self.telegramWebhookSecret)
-        self.setOptionalString(&telegram, key: "webhookPath", value: self.telegramWebhookPath)
-
-        self.setSection("telegram", payload: telegram)
-        await self.persistConfig()
+        await self.persistChannelPatch("telegram", payload: telegram)
     }
 
     func saveDiscordConfig() async {
@@ -192,9 +219,9 @@ extension ConnectionsStore {
             await self.loadConfig()
         }
 
-        let discord = self.buildDiscordConfig()
-        self.setSection("discord", payload: discord)
-        await self.persistConfig()
+        let base = self.channelConfigRoot(for: "discord")
+        let discord = self.buildDiscordPatch(base: base)
+        await self.persistChannelPatch("discord", payload: discord)
     }
 
     func saveSignalConfig() async {
@@ -205,42 +232,23 @@ extension ConnectionsStore {
             await self.loadConfig()
         }
 
-        var signal: [String: Any] = (self.configRoot["signal"] as? [String: Any]) ?? [:]
-        if self.signalEnabled {
-            signal.removeValue(forKey: "enabled")
-        } else {
-            signal["enabled"] = false
-        }
-
-        self.setOptionalString(&signal, key: "account", value: self.signalAccount)
-        self.setOptionalString(&signal, key: "httpUrl", value: self.signalHttpUrl)
-        self.setOptionalString(&signal, key: "httpHost", value: self.signalHttpHost)
-        self.setOptionalNumber(&signal, key: "httpPort", value: self.signalHttpPort)
-        self.setOptionalString(&signal, key: "cliPath", value: self.signalCliPath)
-
-        if self.signalAutoStart {
-            signal.removeValue(forKey: "autoStart")
-        } else {
-            signal["autoStart"] = false
-        }
-
-        self.setOptionalString(&signal, key: "receiveMode", value: self.signalReceiveMode)
-
-        self.setOptionalBool(&signal, key: "ignoreAttachments", value: self.signalIgnoreAttachments)
-        self.setOptionalBool(&signal, key: "ignoreStories", value: self.signalIgnoreStories)
-        self.setOptionalBool(&signal, key: "sendReadReceipts", value: self.signalSendReadReceipts)
-
+        var signal: [String: Any] = [:]
+        self.setPatchBool(&signal, key: "enabled", value: self.signalEnabled, defaultValue: true)
+        self.setPatchString(&signal, key: "account", value: self.signalAccount)
+        self.setPatchString(&signal, key: "httpUrl", value: self.signalHttpUrl)
+        self.setPatchString(&signal, key: "httpHost", value: self.signalHttpHost)
+        self.setPatchNumber(&signal, key: "httpPort", value: self.signalHttpPort)
+        self.setPatchString(&signal, key: "cliPath", value: self.signalCliPath)
+        self.setPatchBool(&signal, key: "autoStart", value: self.signalAutoStart, defaultValue: true)
+        self.setPatchString(&signal, key: "receiveMode", value: self.signalReceiveMode)
+        self.setPatchBool(&signal, key: "ignoreAttachments", value: self.signalIgnoreAttachments, defaultValue: false)
+        self.setPatchBool(&signal, key: "ignoreStories", value: self.signalIgnoreStories, defaultValue: false)
+        self.setPatchBool(&signal, key: "sendReadReceipts", value: self.signalSendReadReceipts, defaultValue: false)
         let allow = self.splitCsv(self.signalAllowFrom)
-        if allow.isEmpty {
-            signal.removeValue(forKey: "allowFrom")
-        } else {
-            signal["allowFrom"] = allow
-        }
+        self.setPatchList(&signal, key: "allowFrom", values: allow)
+        self.setPatchNumber(&signal, key: "mediaMaxMb", value: self.signalMediaMaxMb)
 
-        self.setOptionalNumber(&signal, key: "mediaMaxMb", value: self.signalMediaMaxMb)
-
-        self.setSection("signal", payload: signal)
-        await self.persistConfig()
+        await self.persistChannelPatch("signal", payload: signal)
     }
 
     func saveIMessageConfig() async {
@@ -251,147 +259,168 @@ extension ConnectionsStore {
             await self.loadConfig()
         }
 
-        var imessage: [String: Any] = (self.configRoot["imessage"] as? [String: Any]) ?? [:]
-        if self.imessageEnabled {
-            imessage.removeValue(forKey: "enabled")
-        } else {
-            imessage["enabled"] = false
-        }
-
-        self.setOptionalString(&imessage, key: "cliPath", value: self.imessageCliPath)
-        self.setOptionalString(&imessage, key: "dbPath", value: self.imessageDbPath)
+        var imessage: [String: Any] = [:]
+        self.setPatchBool(&imessage, key: "enabled", value: self.imessageEnabled, defaultValue: true)
+        self.setPatchString(&imessage, key: "cliPath", value: self.imessageCliPath)
+        self.setPatchString(&imessage, key: "dbPath", value: self.imessageDbPath)
 
         let service = self.trimmed(self.imessageService)
         if service.isEmpty || service == "auto" {
-            imessage.removeValue(forKey: "service")
+            imessage["service"] = NSNull()
         } else {
             imessage["service"] = service
         }
 
-        self.setOptionalString(&imessage, key: "region", value: self.imessageRegion)
+        self.setPatchString(&imessage, key: "region", value: self.imessageRegion)
 
         let allow = self.splitCsv(self.imessageAllowFrom)
-        if allow.isEmpty {
-            imessage.removeValue(forKey: "allowFrom")
-        } else {
-            imessage["allowFrom"] = allow
-        }
+        self.setPatchList(&imessage, key: "allowFrom", values: allow)
 
-        self.setOptionalBool(&imessage, key: "includeAttachments", value: self.imessageIncludeAttachments)
-        self.setOptionalNumber(&imessage, key: "mediaMaxMb", value: self.imessageMediaMaxMb)
+        self.setPatchBool(
+            &imessage,
+            key: "includeAttachments",
+            value: self.imessageIncludeAttachments,
+            defaultValue: false)
+        self.setPatchNumber(&imessage, key: "mediaMaxMb", value: self.imessageMediaMaxMb)
 
-        self.setSection("imessage", payload: imessage)
-        await self.persistConfig()
+        await self.persistChannelPatch("imessage", payload: imessage)
     }
 
-    private func buildDiscordConfig() -> [String: Any] {
-        var discord: [String: Any] = (self.configRoot["discord"] as? [String: Any]) ?? [:]
-        if self.discordEnabled {
-            discord.removeValue(forKey: "enabled")
-        } else {
-            discord["enabled"] = false
+    private func buildDiscordPatch(base: [String: Any]) -> [String: Any] {
+        var discord: [String: Any] = [:]
+        self.setPatchBool(&discord, key: "enabled", value: self.discordEnabled, defaultValue: true)
+        if !self.isDiscordTokenLocked {
+            self.setPatchString(&discord, key: "token", value: self.discordToken)
         }
-        self.setOptionalString(&discord, key: "token", value: self.discordToken)
 
-        if let dm = self.buildDiscordDmConfig(base: discord["dm"] as? [String: Any] ?? [:]) {
+        if let dm = self.buildDiscordDmPatch() {
             discord["dm"] = dm
         } else {
-            discord.removeValue(forKey: "dm")
+            discord["dm"] = NSNull()
         }
 
-        self.setOptionalNumber(&discord, key: "mediaMaxMb", value: self.discordMediaMaxMb)
-        self.setOptionalInt(&discord, key: "historyLimit", value: self.discordHistoryLimit, allowZero: true)
-        self.setOptionalInt(&discord, key: "textChunkLimit", value: self.discordTextChunkLimit, allowZero: false)
+        self.setPatchNumber(&discord, key: "mediaMaxMb", value: self.discordMediaMaxMb)
+        self.setPatchInt(&discord, key: "historyLimit", value: self.discordHistoryLimit, allowZero: true)
+        self.setPatchInt(&discord, key: "textChunkLimit", value: self.discordTextChunkLimit, allowZero: false)
 
         let replyToMode = self.trimmed(self.discordReplyToMode)
-        if replyToMode.isEmpty || replyToMode == "off" {
-            discord.removeValue(forKey: "replyToMode")
-        } else if ["first", "all"].contains(replyToMode) {
-            discord["replyToMode"] = replyToMode
+        if replyToMode.isEmpty || replyToMode == "off" || !["first", "all"].contains(replyToMode) {
+            discord["replyToMode"] = NSNull()
         } else {
-            discord.removeValue(forKey: "replyToMode")
+            discord["replyToMode"] = replyToMode
         }
 
-        if let guilds = self.buildDiscordGuildsConfig() {
+        let baseGuilds = base["guilds"] as? [String: Any] ?? [:]
+        if let guilds = self.buildDiscordGuildsPatch(base: baseGuilds) {
             discord["guilds"] = guilds
         } else {
-            discord.removeValue(forKey: "guilds")
+            discord["guilds"] = NSNull()
         }
 
-        if let actions = self.buildDiscordActionsConfig(base: discord["actions"] as? [String: Any] ?? [:]) {
+        if let actions = self.buildDiscordActionsPatch() {
             discord["actions"] = actions
         } else {
-            discord.removeValue(forKey: "actions")
+            discord["actions"] = NSNull()
         }
 
-        if let slash = self.buildDiscordSlashConfig(base: discord["slashCommand"] as? [String: Any] ?? [:]) {
+        if let slash = self.buildDiscordSlashPatch() {
             discord["slashCommand"] = slash
         } else {
-            discord.removeValue(forKey: "slashCommand")
+            discord["slashCommand"] = NSNull()
         }
 
         return discord
     }
 
-    private func buildDiscordDmConfig(base: [String: Any]) -> [String: Any]? {
-        var dm = base
-        if self.discordDmEnabled {
-            dm.removeValue(forKey: "enabled")
-        } else {
-            dm["enabled"] = false
-        }
+    private func buildDiscordDmPatch() -> [String: Any]? {
+        var dm: [String: Any] = [:]
+        self.setPatchBool(&dm, key: "enabled", value: self.discordDmEnabled, defaultValue: true)
         let allow = self.splitCsv(self.discordAllowFrom)
-        if allow.isEmpty {
-            dm.removeValue(forKey: "allowFrom")
-        } else {
-            dm["allowFrom"] = allow
-        }
-
-        if self.discordGroupEnabled {
-            dm["groupEnabled"] = true
-        } else {
-            dm.removeValue(forKey: "groupEnabled")
-        }
-
+        self.setPatchList(&dm, key: "allowFrom", values: allow)
+        self.setPatchBool(&dm, key: "groupEnabled", value: self.discordGroupEnabled, defaultValue: false)
         let groupChannels = self.splitCsv(self.discordGroupChannels)
-        if groupChannels.isEmpty {
-            dm.removeValue(forKey: "groupChannels")
-        } else {
-            dm["groupChannels"] = groupChannels
-        }
-
+        self.setPatchList(&dm, key: "groupChannels", values: groupChannels)
         return dm.isEmpty ? nil : dm
     }
 
-    private func buildDiscordGuildsConfig() -> [String: Any]? {
-        let guilds: [String: Any] = self.discordGuilds.reduce(into: [:]) { result, entry in
-            let key = self.trimmed(entry.key)
-            guard !key.isEmpty else { return }
-            var payload: [String: Any] = [:]
-            let slug = self.trimmed(entry.slug)
-            if !slug.isEmpty { payload["slug"] = slug }
-            if entry.requireMention { payload["requireMention"] = true }
-            if ["off", "own", "all", "allowlist"].contains(entry.reactionNotifications) {
-                payload["reactionNotifications"] = entry.reactionNotifications
-            }
-            let users = self.splitCsv(entry.users)
-            if !users.isEmpty { payload["users"] = users }
-            let channels: [String: Any] = entry.channels.reduce(into: [:]) { channelsResult, channel in
-                let channelKey = self.trimmed(channel.key)
-                guard !channelKey.isEmpty else { return }
-                var channelPayload: [String: Any] = [:]
-                if !channel.allow { channelPayload["allow"] = false }
-                if channel.requireMention { channelPayload["requireMention"] = true }
-                channelsResult[channelKey] = channelPayload
-            }
-            if !channels.isEmpty { payload["channels"] = channels }
-            result[key] = payload
+    private func buildDiscordGuildsPatch(base: [String: Any]) -> Any? {
+        if self.discordGuilds.isEmpty {
+            return NSNull()
         }
-        return guilds.isEmpty ? nil : guilds
+        var patch: [String: Any] = [:]
+        let baseKeys = Set(base.keys)
+        var formKeys = Set<String>()
+        for entry in self.discordGuilds {
+            let key = self.trimmed(entry.key)
+            guard !key.isEmpty else { continue }
+            formKeys.insert(key)
+            let baseGuild = base[key] as? [String: Any] ?? [:]
+            patch[key] = self.buildDiscordGuildPatch(entry, base: baseGuild)
+        }
+        for key in baseKeys.subtracting(formKeys) {
+            patch[key] = NSNull()
+        }
+        return patch.isEmpty ? NSNull() : patch
     }
 
-    private func buildDiscordActionsConfig(base: [String: Any]) -> [String: Any]? {
-        var actions = base
+    private func buildDiscordGuildPatch(_ entry: DiscordGuildForm, base: [String: Any]) -> [String: Any] {
+        var payload: [String: Any] = [:]
+        let slug = self.trimmed(entry.slug)
+        if slug.isEmpty {
+            payload["slug"] = NSNull()
+        } else {
+            payload["slug"] = slug
+        }
+        if entry.requireMention {
+            payload["requireMention"] = true
+        } else {
+            payload["requireMention"] = NSNull()
+        }
+        if ["off", "all", "allowlist"].contains(entry.reactionNotifications) {
+            payload["reactionNotifications"] = entry.reactionNotifications
+        } else {
+            payload["reactionNotifications"] = NSNull()
+        }
+        let users = self.splitCsv(entry.users)
+        self.setPatchList(&payload, key: "users", values: users)
+
+        let baseChannels = base["channels"] as? [String: Any] ?? [:]
+        if let channels = self.buildDiscordChannelsPatch(base: baseChannels, forms: entry.channels) {
+            payload["channels"] = channels
+        } else {
+            payload["channels"] = NSNull()
+        }
+        return payload
+    }
+
+    private func buildDiscordChannelsPatch(base: [String: Any], forms: [DiscordGuildChannelForm]) -> Any? {
+        if forms.isEmpty {
+            return NSNull()
+        }
+        var patch: [String: Any] = [:]
+        let baseKeys = Set(base.keys)
+        var formKeys = Set<String>()
+        for channel in forms {
+            let channelKey = self.trimmed(channel.key)
+            guard !channelKey.isEmpty else { continue }
+            formKeys.insert(channelKey)
+            var channelPayload: [String: Any] = [:]
+            self.setPatchBool(&channelPayload, key: "allow", value: channel.allow, defaultValue: true)
+            self.setPatchBool(
+                &channelPayload,
+                key: "requireMention",
+                value: channel.requireMention,
+                defaultValue: false)
+            patch[channelKey] = channelPayload
+        }
+        for key in baseKeys.subtracting(formKeys) {
+            patch[key] = NSNull()
+        }
+        return patch.isEmpty ? NSNull() : patch
+    }
+
+    private func buildDiscordActionsPatch() -> [String: Any]? {
+        var actions: [String: Any] = [:]
         self.setAction(&actions, key: "reactions", value: self.discordActionReactions, defaultValue: true)
         self.setAction(&actions, key: "stickers", value: self.discordActionStickers, defaultValue: true)
         self.setAction(&actions, key: "polls", value: self.discordActionPolls, defaultValue: true)
@@ -410,52 +439,44 @@ extension ConnectionsStore {
         return actions.isEmpty ? nil : actions
     }
 
-    private func buildDiscordSlashConfig(base: [String: Any]) -> [String: Any]? {
-        var slash = base
-        if self.discordSlashEnabled {
-            slash["enabled"] = true
-        } else {
-            slash.removeValue(forKey: "enabled")
-        }
-        self.setOptionalString(&slash, key: "name", value: self.discordSlashName)
-        self.setOptionalString(&slash, key: "sessionPrefix", value: self.discordSlashSessionPrefix)
-        if self.discordSlashEphemeral {
-            slash.removeValue(forKey: "ephemeral")
-        } else {
-            slash["ephemeral"] = false
-        }
+    private func buildDiscordSlashPatch() -> [String: Any]? {
+        var slash: [String: Any] = [:]
+        self.setPatchBool(&slash, key: "enabled", value: self.discordSlashEnabled, defaultValue: false)
+        self.setPatchString(&slash, key: "name", value: self.discordSlashName)
+        self.setPatchString(&slash, key: "sessionPrefix", value: self.discordSlashSessionPrefix)
+        self.setPatchBool(&slash, key: "ephemeral", value: self.discordSlashEphemeral, defaultValue: true)
         return slash.isEmpty ? nil : slash
     }
 
-    private func persistConfig() async {
+    private func persistChannelPatch(_ channelId: String, payload: [String: Any]) async {
         do {
+            guard let baseHash = self.configHash else {
+                self.configStatus = "Config hash missing; reload and retry."
+                return
+            }
             let data = try JSONSerialization.data(
-                withJSONObject: self.configRoot,
+                withJSONObject: ["channels": [channelId: payload]],
                 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)]
+            let params: [String: AnyCodable] = [
+                "raw": AnyCodable(raw),
+                "baseHash": AnyCodable(baseHash),
+            ]
             _ = try await GatewayConnection.shared.requestRaw(
-                method: .configSet,
+                method: .configPatch,
                 params: params,
                 timeoutMs: 10000)
             self.configStatus = "Saved to ~/.clawdbot/clawdbot.json."
+            await self.loadConfig()
             await self.refresh(probe: true)
         } catch {
             self.configStatus = error.localizedDescription
         }
     }
 
-    private func setSection(_ key: String, payload: [String: Any]) {
-        if payload.isEmpty {
-            self.configRoot.removeValue(forKey: key)
-        } else {
-            self.configRoot[key] = payload
-        }
-    }
-
     private func stringList(from values: [AnyCodable]?) -> String {
         guard let values else { return "" }
         let strings = values.compactMap { entry -> String? in
@@ -492,25 +513,29 @@ extension ConnectionsStore {
         value.trimmingCharacters(in: .whitespacesAndNewlines)
     }
 
-    private func setOptionalString(_ target: inout [String: Any], key: String, value: String) {
+    private func setPatchString(_ target: inout [String: Any], key: String, value: String) {
         let trimmed = self.trimmed(value)
         if trimmed.isEmpty {
-            target.removeValue(forKey: key)
+            target[key] = NSNull()
         } else {
             target[key] = trimmed
         }
     }
 
-    private func setOptionalNumber(_ target: inout [String: Any], key: String, value: String) {
+    private func setPatchNumber(_ target: inout [String: Any], key: String, value: String) {
         let trimmed = self.trimmed(value)
         if trimmed.isEmpty {
-            target.removeValue(forKey: key)
-        } else if let number = Double(trimmed) {
+            target[key] = NSNull()
+            return
+        }
+        if let number = Double(trimmed) {
             target[key] = number
+        } else {
+            target[key] = NSNull()
         }
     }
 
-    private func setOptionalInt(
+    private func setPatchInt(
         _ target: inout [String: Any],
         key: String,
         value: String,
@@ -518,26 +543,39 @@ extension ConnectionsStore {
     {
         let trimmed = self.trimmed(value)
         if trimmed.isEmpty {
-            target.removeValue(forKey: key)
+            target[key] = NSNull()
             return
         }
         guard let number = Int(trimmed) else {
-            target.removeValue(forKey: key)
+            target[key] = NSNull()
             return
         }
         let isValid = allowZero ? number >= 0 : number > 0
         guard isValid else {
-            target.removeValue(forKey: key)
+            target[key] = NSNull()
             return
         }
         target[key] = number
     }
 
-    private func setOptionalBool(_ target: inout [String: Any], key: String, value: Bool) {
-        if value {
-            target[key] = true
+    private func setPatchBool(
+        _ target: inout [String: Any],
+        key: String,
+        value: Bool,
+        defaultValue: Bool)
+    {
+        if value == defaultValue {
+            target[key] = NSNull()
         } else {
-            target.removeValue(forKey: key)
+            target[key] = value
+        }
+    }
+
+    private func setPatchList(_ target: inout [String: Any], key: String, values: [String]) {
+        if values.isEmpty {
+            target[key] = NSNull()
+        } else {
+            target[key] = values
         }
     }
 
@@ -548,7 +586,7 @@ extension ConnectionsStore {
         defaultValue: Bool)
     {
         if value == defaultValue {
-            actions.removeValue(forKey: key)
+            actions[key] = NSNull()
         } else {
             actions[key] = value
         }

apps/macos/Sources/Clawdbot/ConnectionsStore.swift

@@ -180,6 +180,7 @@ struct ConfigSnapshot: Codable {
     let path: String?
     let exists: Bool?
     let raw: String?
+    let hash: String?
     let parsed: AnyCodable?
     let valid: Bool?
     let config: [String: AnyCodable]?
@@ -307,6 +308,7 @@ final class ConnectionsStore {
     var pollTask: Task<Void, Never>?
     var configRoot: [String: Any] = [:]
     var configLoaded = false
+    var configHash: String?
 
     init(isPreview: Bool = ProcessInfo.processInfo.isPreview) {
         self.isPreview = isPreview

apps/macos/Sources/Clawdbot/Constants.swift

@@ -26,6 +26,9 @@ let remoteProjectRootKey = "clawdbot.remoteProjectRoot"
 let remoteCliPathKey = "clawdbot.remoteCliPath"
 let canvasEnabledKey = "clawdbot.canvasEnabled"
 let cameraEnabledKey = "clawdbot.cameraEnabled"
+let systemRunPolicyKey = "clawdbot.systemRunPolicy"
+let systemRunAllowlistKey = "clawdbot.systemRunAllowlist"
+let systemRunEnabledKey = "clawdbot.systemRunEnabled"
 let locationModeKey = "clawdbot.locationMode"
 let locationPreciseKey = "clawdbot.locationPreciseEnabled"
 let peekabooBridgeEnabledKey = "clawdbot.peekabooBridgeEnabled"

apps/macos/Sources/Clawdbot/GatewayConnection.swift

@@ -55,6 +55,7 @@ actor GatewayConnection {
         case channelsStatus = "channels.status"
         case configGet = "config.get"
         case configSet = "config.set"
+        case configPatch = "config.patch"
         case wizardStart = "wizard.start"
         case wizardNext = "wizard.next"
         case wizardCancel = "wizard.cancel"
@@ -232,7 +233,18 @@ actor GatewayConnection {
 
     func canvasHostUrl() async -> String? {
         guard let snapshot = self.lastSnapshot else { return nil }
-        let trimmed = snapshot.canvashosturl?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let trimmed = snapshot.canvashosturl?.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private func sessionDefaultString(_ defaults: [String: AnyCodable]?, key: String) -> String {
+        (defaults?[key]?.stringValue ?? "")
+            .trimmingCharacters(in: CharacterSet.whitespacesAndNewlines)
+    }
+
+    func cachedMainSessionKey() -> String? {
+        guard let snapshot = self.lastSnapshot else { return nil }
+        let trimmed = self.sessionDefaultString(snapshot.snapshot.sessiondefaults, key: "mainSessionKey")
         return trimmed.isEmpty ? nil : trimmed
     }
 
@@ -267,12 +279,35 @@ actor GatewayConnection {
     private func broadcast(_ push: GatewayPush) {
         if case let .snapshot(snapshot) = push {
             self.lastSnapshot = snapshot
+            if let mainSessionKey = self.cachedMainSessionKey() {
+                Task { @MainActor in
+                    WorkActivityStore.shared.setMainSessionKey(mainSessionKey)
+                }
+            }
         }
         for (_, continuation) in self.subscribers {
             continuation.yield(push)
         }
     }
 
+    private func canonicalizeSessionKey(_ raw: String) -> String {
+        let trimmed = raw.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return trimmed }
+        guard let defaults = self.lastSnapshot?.snapshot.sessiondefaults else { return trimmed }
+        let mainSessionKey = self.sessionDefaultString(defaults, key: "mainSessionKey")
+        guard !mainSessionKey.isEmpty else { return trimmed }
+        let mainKey = self.sessionDefaultString(defaults, key: "mainKey")
+        let defaultAgentId = self.sessionDefaultString(defaults, key: "defaultAgentId")
+        let isMainAlias =
+            trimmed == "main" ||
+            (!mainKey.isEmpty && trimmed == mainKey) ||
+            trimmed == mainSessionKey ||
+            (!defaultAgentId.isEmpty &&
+                (trimmed == "agent:\(defaultAgentId):main" ||
+                    (mainKey.isEmpty == false && trimmed == "agent:\(defaultAgentId):\(mainKey)")))
+        return isMainAlias ? mainSessionKey : trimmed
+    }
+
     private func configure(url: URL, token: String?, password: String?) async {
         if self.client != nil, self.configuredURL == url, self.configuredToken == token,
            self.configuredPassword == password
@@ -331,6 +366,9 @@ extension GatewayConnection {
     }
 
     func mainSessionKey(timeoutMs: Double = 15000) async -> String {
+        if let cached = self.cachedMainSessionKey() {
+            return cached
+        }
         do {
             let data = try await self.requestRaw(method: "config.get", params: nil, timeoutMs: timeoutMs)
             return try Self.mainSessionKey(fromConfigGetData: data)
@@ -361,10 +399,11 @@ extension GatewayConnection {
     func sendAgent(_ invocation: GatewayAgentInvocation) async -> (ok: Bool, error: String?) {
         let trimmed = invocation.message.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !trimmed.isEmpty else { return (false, "message empty") }
+        let sessionKey = self.canonicalizeSessionKey(invocation.sessionKey)
 
         var params: [String: AnyCodable] = [
             "message": AnyCodable(trimmed),
-            "sessionKey": AnyCodable(invocation.sessionKey),
+            "sessionKey": AnyCodable(sessionKey),
             "thinking": AnyCodable(invocation.thinking ?? "default"),
             "deliver": AnyCodable(invocation.deliver),
             "to": AnyCodable(invocation.to ?? ""),
@@ -468,7 +507,8 @@ extension GatewayConnection {
         limit: Int? = nil,
         timeoutMs: Int? = nil) async throws -> ClawdbotChatHistoryPayload
     {
-        var params: [String: AnyCodable] = ["sessionKey": AnyCodable(sessionKey)]
+        let resolvedKey = self.canonicalizeSessionKey(sessionKey)
+        var params: [String: AnyCodable] = ["sessionKey": AnyCodable(resolvedKey)]
         if let limit { params["limit"] = AnyCodable(limit) }
         let timeout = timeoutMs.map { Double($0) }
         return try await self.requestDecoded(
@@ -485,8 +525,9 @@ extension GatewayConnection {
         attachments: [ClawdbotChatAttachmentPayload],
         timeoutMs: Int = 30000) async throws -> ClawdbotChatSendResponse
     {
+        let resolvedKey = self.canonicalizeSessionKey(sessionKey)
         var params: [String: AnyCodable] = [
-            "sessionKey": AnyCodable(sessionKey),
+            "sessionKey": AnyCodable(resolvedKey),
             "message": AnyCodable(message),
             "thinking": AnyCodable(thinking),
             "idempotencyKey": AnyCodable(idempotencyKey),
@@ -512,10 +553,11 @@ extension GatewayConnection {
     }
 
     func chatAbort(sessionKey: String, runId: String) async throws -> Bool {
+        let resolvedKey = self.canonicalizeSessionKey(sessionKey)
         struct AbortResponse: Decodable { let ok: Bool?; let aborted: Bool? }
         let res: AbortResponse = try await self.requestDecoded(
             method: .chatAbort,
-            params: ["sessionKey": AnyCodable(sessionKey), "runId": AnyCodable(runId)])
+            params: ["sessionKey": AnyCodable(resolvedKey), "runId": AnyCodable(runId)])
         return res.aborted ?? false
     }
 

apps/macos/Sources/Clawdbot/GatewayEndpointStore.swift

@@ -33,14 +33,16 @@ actor GatewayEndpointStore {
                 return GatewayEndpointStore.resolveGatewayToken(
                     isRemote: CommandResolver.connectionModeIsRemote(),
                     root: root,
-                    env: ProcessInfo.processInfo.environment)
+                    env: ProcessInfo.processInfo.environment,
+                    launchdSnapshot: GatewayLaunchAgentManager.launchdConfigSnapshot())
             },
             password: {
                 let root = ClawdbotConfigFile.loadDict()
                 return GatewayEndpointStore.resolveGatewayPassword(
                     isRemote: CommandResolver.connectionModeIsRemote(),
                     root: root,
-                    env: ProcessInfo.processInfo.environment)
+                    env: ProcessInfo.processInfo.environment,
+                    launchdSnapshot: GatewayLaunchAgentManager.launchdConfigSnapshot())
             },
             localPort: { GatewayEnvironment.gatewayPort() },
             localHost: {
@@ -60,7 +62,8 @@ actor GatewayEndpointStore {
     private static func resolveGatewayPassword(
         isRemote: Bool,
         root: [String: Any],
-        env: [String: String]) -> String?
+        env: [String: String],
+        launchdSnapshot: LaunchAgentPlistSnapshot?) -> String?
     {
         let raw = env["CLAWDBOT_GATEWAY_PASSWORD"] ?? ""
         let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -88,13 +91,19 @@ actor GatewayEndpointStore {
                 return pw
             }
         }
+        if let password = launchdSnapshot?.password?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !password.isEmpty
+        {
+            return password
+        }
         return nil
     }
 
     private static func resolveGatewayToken(
         isRemote: Bool,
         root: [String: Any],
-        env: [String: String]) -> String?
+        env: [String: String],
+        launchdSnapshot: LaunchAgentPlistSnapshot?) -> String?
     {
         let raw = env["CLAWDBOT_GATEWAY_TOKEN"] ?? ""
         let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -122,6 +131,11 @@ actor GatewayEndpointStore {
                 return value
             }
         }
+        if let token = launchdSnapshot?.token?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !token.isEmpty
+        {
+            return token
+        }
         return nil
     }
 
@@ -430,9 +444,19 @@ extension GatewayEndpointStore {
     static func _testResolveGatewayPassword(
         isRemote: Bool,
         root: [String: Any],
-        env: [String: String]) -> String?
+        env: [String: String],
+        launchdSnapshot: LaunchAgentPlistSnapshot? = nil) -> String?
     {
-        self.resolveGatewayPassword(isRemote: isRemote, root: root, env: env)
+        self.resolveGatewayPassword(isRemote: isRemote, root: root, env: env, launchdSnapshot: launchdSnapshot)
+    }
+
+    static func _testResolveGatewayToken(
+        isRemote: Bool,
+        root: [String: Any],
+        env: [String: String],
+        launchdSnapshot: LaunchAgentPlistSnapshot? = nil) -> String?
+    {
+        self.resolveGatewayToken(isRemote: isRemote, root: root, env: env, launchdSnapshot: launchdSnapshot)
     }
 
     static func _testResolveGatewayBindMode(

apps/macos/Sources/Clawdbot/GatewayLaunchAgentManager.swift

@@ -306,6 +306,10 @@ enum GatewayLaunchAgentManager {
             password: snapshot.password)
     }
 
+    static func launchdConfigSnapshot() -> LaunchAgentPlistSnapshot? {
+        LaunchAgentPlist.snapshot(url: self.plistURL)
+    }
+
     private static func ensureEnabled() async {
         let result = await Launchctl.run(["enable", "gui/\(getuid())/\(gatewayLaunchdLabel)"])
         guard result.status != 0 else { return }

apps/macos/Sources/Clawdbot/GeneralSettings.swift

@@ -83,6 +83,25 @@ struct GeneralSettings: View {
                         subtitle: "Allow the agent to capture a photo or short video via the built-in camera.",
                         binding: self.$cameraEnabled)
 
+                    VStack(alignment: .leading, spacing: 6) {
+                        Text("Node Run Commands")
+                            .font(.body)
+
+                        Picker("", selection: self.$state.systemRunPolicy) {
+                            ForEach(SystemRunPolicy.allCases) { policy in
+                                Text(policy.title).tag(policy)
+                            }
+                        }
+                        .pickerStyle(.segmented)
+
+                        Text("""
+                        Controls remote command execution on this Mac when it is paired as a node. "Always Ask" prompts on each command; "Always Allow" runs without prompts; "Never" disables `system.run`.
+                        """)
+                        .font(.footnote)
+                        .foregroundStyle(.tertiary)
+                        .fixedSize(horizontal: false, vertical: true)
+                    }
+
                     VStack(alignment: .leading, spacing: 6) {
                         Text("Location Access")
                             .font(.body)

apps/macos/Sources/Clawdbot/LogLocator.swift

@@ -1,9 +1,25 @@
 import Foundation
 
 enum LogLocator {
-    private static let logDir = URL(fileURLWithPath: "/tmp/clawdbot")
-    private static let stdoutLog = logDir.appendingPathComponent("clawdbot-stdout.log")
-    private static let gatewayLog = logDir.appendingPathComponent("clawdbot-gateway.log")
+    private static var logDir: URL {
+        if let override = ProcessInfo.processInfo.environment["CLAWDBOT_LOG_DIR"], !override.isEmpty {
+            return URL(fileURLWithPath: override)
+        }
+
+        return URL(fileURLWithPath: "/tmp/clawdbot")
+    }
+
+    private static var stdoutLog: URL {
+        logDir.appendingPathComponent("clawdbot-stdout.log")
+    }
+
+    private static var gatewayLog: URL {
+        logDir.appendingPathComponent("clawdbot-gateway.log")
+    }
+
+    private static func ensureLogDirExists() {
+        try? FileManager.default.createDirectory(at: self.logDir, withIntermediateDirectories: true)
+    }
 
     private static func modificationDate(for url: URL) -> Date {
         (try? url.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate) ?? .distantPast
@@ -11,6 +27,7 @@ enum LogLocator {
 
     /// Returns the newest log file under /tmp/clawdbot/ (rolling or stdout), or nil if none exist.
     static func bestLogFile() -> URL? {
+        self.ensureLogDirExists()
         let fm = FileManager.default
         let files = (try? fm.contentsOfDirectory(
             at: self.logDir,
@@ -26,11 +43,13 @@ enum LogLocator {
 
     /// Path to use for launchd stdout/err.
     static var launchdLogPath: String {
-        stdoutLog.path
+        self.ensureLogDirExists()
+        return stdoutLog.path
     }
 
     /// Path to use for the Gateway launchd job stdout/err.
     static var launchdGatewayLogPath: String {
-        gatewayLog.path
+        self.ensureLogDirExists()
+        return gatewayLog.path
     }
 }

apps/macos/Sources/Clawdbot/MacNodeConfigFile.swift

@@ -0,0 +1,81 @@
+import Foundation
+import OSLog
+
+enum MacNodeConfigFile {
+    private static let logger = Logger(subsystem: "com.clawdbot", category: "mac-node-config")
+
+    static func url() -> URL {
+        ClawdbotPaths.stateDirURL.appendingPathComponent("macos-node.json")
+    }
+
+    static func loadDict() -> [String: Any] {
+        let url = self.url()
+        guard FileManager.default.fileExists(atPath: url.path) else { return [:] }
+        do {
+            let data = try Data(contentsOf: url)
+            guard let root = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+                self.logger.warning("mac node config JSON root invalid")
+                return [:]
+            }
+            return root
+        } catch {
+            self.logger.warning("mac node config read failed: \(error.localizedDescription, privacy: .public)")
+            return [:]
+        }
+    }
+
+    static func saveDict(_ dict: [String: Any]) {
+        do {
+            let data = try JSONSerialization.data(withJSONObject: dict, options: [.prettyPrinted, .sortedKeys])
+            let url = self.url()
+            try FileManager.default.createDirectory(
+                at: url.deletingLastPathComponent(),
+                withIntermediateDirectories: true)
+            try data.write(to: url, options: [.atomic])
+            try? FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: url.path)
+        } catch {
+            self.logger.error("mac node config save failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    static func systemRunPolicy() -> SystemRunPolicy? {
+        let root = self.loadDict()
+        let systemRun = root["systemRun"] as? [String: Any]
+        let raw = systemRun?["policy"] as? String
+        guard let raw, let policy = SystemRunPolicy(rawValue: raw) else { return nil }
+        return policy
+    }
+
+    static func setSystemRunPolicy(_ policy: SystemRunPolicy) {
+        var root = self.loadDict()
+        var systemRun = root["systemRun"] as? [String: Any] ?? [:]
+        systemRun["policy"] = policy.rawValue
+        root["systemRun"] = systemRun
+        self.saveDict(root)
+    }
+
+    static func systemRunAllowlist() -> [String]? {
+        let root = self.loadDict()
+        let systemRun = root["systemRun"] as? [String: Any]
+        return systemRun?["allowlist"] as? [String]
+    }
+
+    static func setSystemRunAllowlist(_ allowlist: [String]) {
+        let cleaned = allowlist
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        var root = self.loadDict()
+        var systemRun = root["systemRun"] as? [String: Any] ?? [:]
+        if cleaned.isEmpty {
+            systemRun.removeValue(forKey: "allowlist")
+        } else {
+            systemRun["allowlist"] = cleaned
+        }
+        if systemRun.isEmpty {
+            root.removeValue(forKey: "systemRun")
+        } else {
+            root["systemRun"] = systemRun
+        }
+        self.saveDict(root)
+    }
+}

apps/macos/Sources/Clawdbot/MenuContentView.swift

@@ -31,6 +31,12 @@ struct MenuContent: View {
         self._updateStatus = Bindable(wrappedValue: updater?.updateStatus ?? UpdateStatus.disabled)
     }
 
+    private var systemRunPolicyBinding: Binding<SystemRunPolicy> {
+        Binding(
+            get: { self.state.systemRunPolicy },
+            set: { self.state.systemRunPolicy = $0 })
+    }
+
     var body: some View {
         VStack(alignment: .leading, spacing: 8) {
             Toggle(isOn: self.activeBinding) {
@@ -68,6 +74,13 @@ struct MenuContent: View {
             Toggle(isOn: self.$cameraEnabled) {
                 Label("Allow Camera", systemImage: "camera")
             }
+            Picker(selection: self.systemRunPolicyBinding) {
+                ForEach(SystemRunPolicy.allCases) { policy in
+                    Text(policy.title).tag(policy)
+                }
+            } label: {
+                Label("Node Run Commands", systemImage: "terminal")
+            }
             Toggle(isOn: Binding(get: { self.state.canvasEnabled }, set: { self.state.canvasEnabled = $0 })) {
                 Label("Allow Canvas", systemImage: "rectangle.and.pencil.and.ellipsis")
             }
@@ -102,11 +115,14 @@ struct MenuContent: View {
             }
             if self.state.canvasEnabled {
                 Button {
-                    if self.state.canvasPanelVisible {
-                        CanvasManager.shared.hideAll()
-                    } else {
-                        // Don't force a navigation on re-open: preserve the current web view state.
-                        _ = try? CanvasManager.shared.show(sessionKey: "main", path: nil)
+                    Task { @MainActor in
+                        if self.state.canvasPanelVisible {
+                            CanvasManager.shared.hideAll()
+                        } else {
+                            let sessionKey = await GatewayConnection.shared.mainSessionKey()
+                            // Don't force a navigation on re-open: preserve the current web view state.
+                            _ = try? CanvasManager.shared.show(sessionKey: sessionKey, path: nil)
+                        }
                     }
                 } label: {
                     Label(

apps/macos/Sources/Clawdbot/MenuSessionsInjector.swift

@@ -104,6 +104,8 @@ final class MenuSessionsInjector: NSObject, NSMenuDelegate {
 extension MenuSessionsInjector {
     // MARK: - Injection
 
+    private var mainSessionKey: String { WorkActivityStore.shared.mainSessionKey }
+
     private func inject(into menu: NSMenu) {
         // Remove any previous injected items.
         for item in menu.items where item.tag == self.tag {
@@ -120,13 +122,15 @@ extension MenuSessionsInjector {
 
         if let snapshot = self.cachedSnapshot {
             let now = Date()
+            let mainKey = self.mainSessionKey
             let rows = snapshot.rows.filter { row in
-                if row.key == "main" { return true }
+                if row.key == "main", mainKey != "main" { return false }
+                if row.key == mainKey { return true }
                 guard let updatedAt = row.updatedAt else { return false }
                 return now.timeIntervalSince(updatedAt) <= self.activeWindowSeconds
             }.sorted { lhs, rhs in
-                if lhs.key == "main" { return true }
-                if rhs.key == "main" { return false }
+                if lhs.key == mainKey { return true }
+                if rhs.key == mainKey { return false }
                 return (lhs.updatedAt ?? .distantPast) > (rhs.updatedAt ?? .distantPast)
             }
 
@@ -645,7 +649,7 @@ extension MenuSessionsInjector {
         compact.representedObject = row.key
         menu.addItem(compact)
 
-        if row.key != "main", row.key != "global" {
+        if row.key != self.mainSessionKey, row.key != "global" {
             let del = NSMenuItem(title: "Delete Session", action: #selector(self.deleteSession(_:)), keyEquivalent: "")
             del.target = self
             del.representedObject = row.key

apps/macos/Sources/Clawdbot/NodeMode/MacNodeBridgePairingClient.swift

@@ -11,10 +11,39 @@ actor MacNodeBridgePairingClient {
         endpoint: NWEndpoint,
         hello: BridgeHello,
         silent: Bool,
+        tls: MacNodeBridgeTLSParams? = nil,
+        onStatus: (@Sendable (String) -> Void)? = nil) async throws -> String
+    {
+        do {
+            return try await self.pairAndHelloOnce(
+                endpoint: endpoint,
+                hello: hello,
+                silent: silent,
+                tls: tls,
+                onStatus: onStatus)
+        } catch {
+            if let tls, !tls.required {
+                return try await self.pairAndHelloOnce(
+                    endpoint: endpoint,
+                    hello: hello,
+                    silent: silent,
+                    tls: nil,
+                    onStatus: onStatus)
+            }
+            throw error
+        }
+    }
+
+    private func pairAndHelloOnce(
+        endpoint: NWEndpoint,
+        hello: BridgeHello,
+        silent: Bool,
+        tls: MacNodeBridgeTLSParams?,
         onStatus: (@Sendable (String) -> Void)? = nil) async throws -> String
     {
         self.lineBuffer = Data()
-        let connection = NWConnection(to: endpoint, using: .tcp)
+        let params = self.makeParameters(tls: tls)
+        let connection = NWConnection(to: endpoint, using: params)
         let queue = DispatchQueue(label: "com.clawdbot.macos.bridge-client")
         defer { connection.cancel() }
         try await AsyncTimeout.withTimeout(
@@ -164,6 +193,18 @@ actor MacNodeBridgePairingClient {
         }
     }
 
+    private func makeParameters(tls: MacNodeBridgeTLSParams?) -> NWParameters {
+        let tcpOptions = NWProtocolTCP.Options()
+        if let tlsOptions = makeMacNodeTLSOptions(tls) {
+            let params = NWParameters(tls: tlsOptions, tcp: tcpOptions)
+            params.includePeerToPeer = true
+            return params
+        }
+        let params = NWParameters.tcp
+        params.includePeerToPeer = true
+        return params
+    }
+
     private func startAndWaitForReady(
         _ connection: NWConnection,
         queue: DispatchQueue) async throws

apps/macos/Sources/Clawdbot/NodeMode/MacNodeBridgeSession.swift

@@ -36,7 +36,8 @@ actor MacNodeBridgeSession {
     func connect(
         endpoint: NWEndpoint,
         hello: BridgeHello,
-        onConnected: (@Sendable (String) async -> Void)? = nil,
+        tls: MacNodeBridgeTLSParams? = nil,
+        onConnected: (@Sendable (String, String?) async -> Void)? = nil,
         onDisconnected: (@Sendable (String) async -> Void)? = nil,
         onInvoke: @escaping @Sendable (BridgeInvokeRequest) async -> BridgeInvokeResponse)
         async throws
@@ -44,15 +45,35 @@ actor MacNodeBridgeSession {
         await self.disconnect()
         self.disconnectHandler = onDisconnected
         self.state = .connecting
+        do {
+            try await self.connectOnce(
+                endpoint: endpoint,
+                hello: hello,
+                tls: tls,
+                onConnected: onConnected,
+                onInvoke: onInvoke)
+        } catch {
+            if let tls, !tls.required {
+                try await self.connectOnce(
+                    endpoint: endpoint,
+                    hello: hello,
+                    tls: nil,
+                    onConnected: onConnected,
+                    onInvoke: onInvoke)
+                return
+            }
+            throw error
+        }
+    }
 
-        let params = NWParameters.tcp
-        params.includePeerToPeer = true
-        let tcpOptions = NWProtocolTCP.Options()
-        tcpOptions.enableKeepalive = true
-        tcpOptions.keepaliveIdle = 30
-        tcpOptions.keepaliveInterval = 15
-        tcpOptions.keepaliveCount = 3
-        params.defaultProtocolStack.transportProtocol = tcpOptions
+    private func connectOnce(
+        endpoint: NWEndpoint,
+        hello: BridgeHello,
+        tls: MacNodeBridgeTLSParams?,
+        onConnected: (@Sendable (String, String?) async -> Void)? = nil,
+        onInvoke: @escaping @Sendable (BridgeInvokeRequest) async -> BridgeInvokeResponse) async throws
+    {
+        let params = self.makeParameters(tls: tls)
         let connection = NWConnection(to: endpoint, using: params)
         let queue = DispatchQueue(label: "com.clawdbot.macos.bridge-session")
         self.connection = connection
@@ -98,7 +119,8 @@ actor MacNodeBridgeSession {
             let ok = try self.decoder.decode(BridgeHelloOk.self, from: data)
             self.state = .connected(serverName: ok.serverName)
             self.startPingLoop()
-            await onConnected?(ok.serverName)
+            let mainKey = ok.mainSessionKey?.trimmingCharacters(in: .whitespacesAndNewlines)
+            await onConnected?(ok.serverName, mainKey?.isEmpty == false ? mainKey : nil)
         } else if base.type == "error" {
             let err = try self.decoder.decode(BridgeErrorFrame.self, from: data)
             self.state = .failed(message: "\(err.code): \(err.message)")
@@ -261,6 +283,25 @@ actor MacNodeBridgeSession {
         }
     }
 
+    private func makeParameters(tls: MacNodeBridgeTLSParams?) -> NWParameters {
+        let tcpOptions = NWProtocolTCP.Options()
+        tcpOptions.enableKeepalive = true
+        tcpOptions.keepaliveIdle = 30
+        tcpOptions.keepaliveInterval = 15
+        tcpOptions.keepaliveCount = 3
+
+        if let tlsOptions = makeMacNodeTLSOptions(tls) {
+            let params = NWParameters(tls: tlsOptions, tcp: tcpOptions)
+            params.includePeerToPeer = true
+            return params
+        }
+
+        let params = NWParameters.tcp
+        params.includePeerToPeer = true
+        params.defaultProtocolStack.transportProtocol = tcpOptions
+        return params
+    }
+
     private func failRPC(id: String, error: Error) async {
         if let cont = self.pendingRPC.removeValue(forKey: id) {
             cont.resume(throwing: error)

apps/macos/Sources/Clawdbot/NodeMode/MacNodeBridgeTLS.swift

@@ -0,0 +1,75 @@
+import CryptoKit
+import Foundation
+import Network
+import Security
+
+struct MacNodeBridgeTLSParams: Sendable {
+    let required: Bool
+    let expectedFingerprint: String?
+    let allowTOFU: Bool
+    let storeKey: String?
+}
+
+enum MacNodeBridgeTLSStore {
+    private static let suiteName = "com.clawdbot.shared"
+    private static let keyPrefix = "mac.node.bridge.tls."
+
+    private static var defaults: UserDefaults {
+        UserDefaults(suiteName: suiteName) ?? .standard
+    }
+
+    static func loadFingerprint(stableID: String) -> String? {
+        let key = keyPrefix + stableID
+        let raw = defaults.string(forKey: key)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return raw?.isEmpty == false ? raw : nil
+    }
+
+    static func saveFingerprint(_ value: String, stableID: String) {
+        let key = keyPrefix + stableID
+        defaults.set(value, forKey: key)
+    }
+}
+
+func makeMacNodeTLSOptions(_ params: MacNodeBridgeTLSParams?) -> NWProtocolTLS.Options? {
+    guard let params else { return nil }
+    let options = NWProtocolTLS.Options()
+    let expected = params.expectedFingerprint.map(normalizeMacNodeFingerprint)
+    let allowTOFU = params.allowTOFU
+    let storeKey = params.storeKey
+
+    sec_protocol_options_set_verify_block(
+        options.securityProtocolOptions,
+        { _, trust, complete in
+            guard let trust else {
+                complete(false)
+                return
+            }
+            if let cert = SecTrustGetCertificateAtIndex(trust, 0) {
+                let data = SecCertificateCopyData(cert) as Data
+                let fingerprint = sha256Hex(data)
+                if let expected {
+                    complete(fingerprint == expected)
+                    return
+                }
+                if allowTOFU {
+                    if let storeKey { MacNodeBridgeTLSStore.saveFingerprint(fingerprint, stableID: storeKey) }
+                    complete(true)
+                    return
+                }
+            }
+            let ok = SecTrustEvaluateWithError(trust, nil)
+            complete(ok)
+        },
+        DispatchQueue(label: "com.clawdbot.macos.bridge.tls.verify"))
+
+    return options
+}
+
+private func sha256Hex(_ data: Data) -> String {
+    let digest = SHA256.hash(data: data)
+    return digest.map { String(format: "%02x", $0) }.joined()
+}
+
+private func normalizeMacNodeFingerprint(_ raw: String) -> String {
+    raw.lowercased().filter { $0.isHexDigit }
+}

apps/macos/Sources/Clawdbot/NodeMode/MacNodeModeCoordinator.swift

@@ -4,6 +4,12 @@ import Foundation
 import Network
 import OSLog
 
+private struct BridgeTarget {
+    let endpoint: NWEndpoint
+    let stableID: String
+    let tls: MacNodeBridgeTLSParams?
+}
+
 @MainActor
 final class MacNodeModeCoordinator {
     static let shared = MacNodeModeCoordinator()
@@ -37,6 +43,7 @@ final class MacNodeModeCoordinator {
     private func run() async {
         var retryDelay: UInt64 = 1_000_000_000
         var lastCameraEnabled: Bool?
+        var lastSystemRunPolicy: SystemRunPolicy?
         let defaults = UserDefaults.standard
         while !Task.isCancelled {
             if await MainActor.run(body: { AppStateStore.shared.isPaused }) {
@@ -53,7 +60,16 @@ final class MacNodeModeCoordinator {
                 try? await Task.sleep(nanoseconds: 200_000_000)
             }
 
-            guard let endpoint = await self.resolveBridgeEndpoint(timeoutSeconds: 5) else {
+            let systemRunPolicy = SystemRunPolicy.load()
+            if lastSystemRunPolicy == nil {
+                lastSystemRunPolicy = systemRunPolicy
+            } else if lastSystemRunPolicy != systemRunPolicy {
+                lastSystemRunPolicy = systemRunPolicy
+                await self.session.disconnect()
+                try? await Task.sleep(nanoseconds: 200_000_000)
+            }
+
+            guard let target = await self.resolveBridgeEndpoint(timeoutSeconds: 5) else {
                 try? await Task.sleep(nanoseconds: min(retryDelay, 5_000_000_000))
                 retryDelay = min(retryDelay * 2, 10_000_000_000)
                 continue
@@ -63,12 +79,16 @@ final class MacNodeModeCoordinator {
             do {
                 let hello = await self.makeHello()
                 self.logger.info(
-                    "mac node bridge connecting endpoint=\(endpoint, privacy: .public)")
+                    "mac node bridge connecting endpoint=\(target.endpoint, privacy: .public)")
                 try await self.session.connect(
-                    endpoint: endpoint,
+                    endpoint: target.endpoint,
                     hello: hello,
-                    onConnected: { [weak self] serverName in
+                    tls: target.tls,
+                    onConnected: { [weak self] serverName, mainSessionKey in
                         self?.logger.info("mac node connected to \(serverName, privacy: .public)")
+                        if let mainSessionKey {
+                            await self?.runtime.updateMainSessionKey(mainSessionKey)
+                        }
                     },
                     onDisconnected: { reason in
                         await MacNodeModeCoordinator.handleBridgeDisconnect(reason: reason)
@@ -83,7 +103,7 @@ final class MacNodeModeCoordinator {
                         return await self.runtime.handleInvoke(req)
                     })
             } catch {
-                if await self.tryPair(endpoint: endpoint, error: error) {
+                if await self.tryPair(target: target, error: error) {
                     continue
                 }
                 self.logger.error(
@@ -140,10 +160,13 @@ final class MacNodeModeCoordinator {
             ClawdbotCanvasA2UICommand.pushJSONL.rawValue,
             ClawdbotCanvasA2UICommand.reset.rawValue,
             MacNodeScreenCommand.record.rawValue,
-            ClawdbotSystemCommand.run.rawValue,
             ClawdbotSystemCommand.notify.rawValue,
         ]
 
+        if SystemRunPolicy.load() != .never {
+            commands.append(ClawdbotSystemCommand.run.rawValue)
+        }
+
         let capsSet = Set(caps)
         if capsSet.contains(ClawdbotCapability.camera.rawValue) {
             commands.append(ClawdbotCameraCommand.list.rawValue)
@@ -157,7 +180,7 @@ final class MacNodeModeCoordinator {
         return commands
     }
 
-    private func tryPair(endpoint: NWEndpoint, error: Error) async -> Bool {
+    private func tryPair(target: BridgeTarget, error: Error) async -> Bool {
         let text = error.localizedDescription.uppercased()
         guard text.contains("NOT_PAIRED") || text.contains("UNAUTHORIZED") else { return false }
 
@@ -167,9 +190,10 @@ final class MacNodeModeCoordinator {
             }
             let hello = await self.makeHello()
             let token = try await MacNodeBridgePairingClient().pairAndHello(
-                endpoint: endpoint,
+                endpoint: target.endpoint,
                 hello: hello,
                 silent: shouldSilent,
+                tls: target.tls,
                 onStatus: { [weak self] status in
                     self?.logger.info("mac node pairing: \(status, privacy: .public)")
                 })
@@ -187,7 +211,7 @@ final class MacNodeModeCoordinator {
         "mac-\(InstanceIdentity.instanceId)"
     }
 
-    private func resolveLoopbackBridgeEndpoint(timeoutSeconds: Double) async -> NWEndpoint? {
+    private func resolveLoopbackBridgeEndpoint(timeoutSeconds: Double) async -> BridgeTarget? {
         guard let port = Self.loopbackBridgePort(),
               let endpointPort = NWEndpoint.Port(rawValue: port)
         else {
@@ -195,7 +219,10 @@ final class MacNodeModeCoordinator {
         }
         let endpoint = NWEndpoint.hostPort(host: "127.0.0.1", port: endpointPort)
         let reachable = await Self.probeEndpoint(endpoint, timeoutSeconds: timeoutSeconds)
-        return reachable ? endpoint : nil
+        guard reachable else { return nil }
+        let stableID = BridgeEndpointID.stableID(endpoint)
+        let tlsParams = Self.resolveManualTLSParams(stableID: stableID)
+        return BridgeTarget(endpoint: endpoint, stableID: stableID, tls: tlsParams)
     }
 
     static func loopbackBridgePort() -> UInt16? {
@@ -288,7 +315,7 @@ final class MacNodeModeCoordinator {
             })
     }
 
-    private func resolveBridgeEndpoint(timeoutSeconds: Double) async -> NWEndpoint? {
+    private func resolveBridgeEndpoint(timeoutSeconds: Double) async -> BridgeTarget? {
         let mode = await MainActor.run(body: { AppStateStore.shared.connectionMode })
         if mode == .remote {
             do {
@@ -300,7 +327,10 @@ final class MacNodeModeCoordinator {
                     if healthy, let port = NWEndpoint.Port(rawValue: localPort) {
                         self.logger.info(
                             "reusing mac node bridge tunnel localPort=\(localPort, privacy: .public)")
-                        return .hostPort(host: "127.0.0.1", port: port)
+                        let endpoint = NWEndpoint.hostPort(host: "127.0.0.1", port: port)
+                        let stableID = BridgeEndpointID.stableID(endpoint)
+                        let tlsParams = Self.resolveManualTLSParams(stableID: stableID)
+                        return BridgeTarget(endpoint: endpoint, stableID: stableID, tls: tlsParams)
                     }
                     self.logger.error(
                         "mac node bridge tunnel unhealthy localPort=\(localPort, privacy: .public); restarting")
@@ -309,9 +339,23 @@ final class MacNodeModeCoordinator {
                 }
 
                 let remotePort = Self.remoteBridgePort()
+                let preferredLocalPort = Self.loopbackBridgePort()
+                if let preferredLocalPort {
+                    self.logger.info(
+                        "mac node bridge tunnel starting " +
+                            "preferredLocalPort=\(preferredLocalPort, privacy: .public) " +
+                            "remotePort=\(remotePort, privacy: .public)")
+                } else {
+                    self.logger.info(
+                        "mac node bridge tunnel starting " +
+                            "preferredLocalPort=none " +
+                            "remotePort=\(remotePort, privacy: .public)")
+                }
                 self.tunnel = try await RemotePortTunnel.create(
                     remotePort: remotePort,
-                    allowRemoteUrlOverride: false)
+                    preferredLocalPort: preferredLocalPort,
+                    allowRemoteUrlOverride: false,
+                    allowRandomLocalPort: true)
                 if let localPort = self.tunnel?.localPort,
                    let port = NWEndpoint.Port(rawValue: localPort)
                 {
@@ -319,7 +363,10 @@ final class MacNodeModeCoordinator {
                         "mac node bridge tunnel ready " +
                             "localPort=\(localPort, privacy: .public) " +
                             "remotePort=\(remotePort, privacy: .public)")
-                    return .hostPort(host: "127.0.0.1", port: port)
+                    let endpoint = NWEndpoint.hostPort(host: "127.0.0.1", port: port)
+                    let stableID = BridgeEndpointID.stableID(endpoint)
+                    let tlsParams = Self.resolveManualTLSParams(stableID: stableID)
+                    return BridgeTarget(endpoint: endpoint, stableID: stableID, tls: tlsParams)
                 }
             } catch {
                 self.logger.error("mac node bridge tunnel failed: \(error.localizedDescription, privacy: .public)")
@@ -330,8 +377,8 @@ final class MacNodeModeCoordinator {
             tunnel.terminate()
             self.tunnel = nil
         }
-        if mode == .local, let endpoint = await self.resolveLoopbackBridgeEndpoint(timeoutSeconds: 0.4) {
-            return endpoint
+        if mode == .local, let target = await self.resolveLoopbackBridgeEndpoint(timeoutSeconds: 0.4) {
+            return target
         }
         return await Self.discoverBridgeEndpoint(timeoutSeconds: timeoutSeconds)
     }
@@ -351,14 +398,14 @@ final class MacNodeModeCoordinator {
         return await Self.probeEndpoint(.hostPort(host: "127.0.0.1", port: port), timeoutSeconds: timeoutSeconds)
     }
 
-    private static func discoverBridgeEndpoint(timeoutSeconds: Double) async -> NWEndpoint? {
+    private static func discoverBridgeEndpoint(timeoutSeconds: Double) async -> BridgeTarget? {
         final class DiscoveryState: @unchecked Sendable {
             let lock = NSLock()
             var resolved = false
             var browsers: [NWBrowser] = []
-            var continuation: CheckedContinuation<NWEndpoint?, Never>?
+            var continuation: CheckedContinuation<BridgeTarget?, Never>?
 
-            func finish(_ endpoint: NWEndpoint?) {
+            func finish(_ target: BridgeTarget?) {
                 self.lock.lock()
                 defer { lock.unlock() }
                 if self.resolved { return }
@@ -366,7 +413,7 @@ final class MacNodeModeCoordinator {
                 for browser in self.browsers {
                     browser.cancel()
                 }
-                self.continuation?.resume(returning: endpoint)
+                self.continuation?.resume(returning: target)
                 self.continuation = nil
             }
         }
@@ -392,12 +439,12 @@ final class MacNodeModeCoordinator {
                            return false
                        })
                     {
-                        state.finish(match.endpoint)
+                        state.finish(Self.targetFromResult(match))
                         return
                     }
 
                     if let result = results.first(where: { if case .service = $0.endpoint { true } else { false } }) {
-                        state.finish(result.endpoint)
+                        state.finish(Self.targetFromResult(result))
                     }
                 }
                 browser.stateUpdateHandler = { browserState in
@@ -415,6 +462,72 @@ final class MacNodeModeCoordinator {
             }
         }
     }
+
+    private static func targetFromResult(_ result: NWBrowser.Result) -> BridgeTarget? {
+        let endpoint = result.endpoint
+        guard case .service = endpoint else { return nil }
+        let stableID = BridgeEndpointID.stableID(endpoint)
+        let txt = result.endpoint.txtRecord?.dictionary ?? [:]
+        let tlsEnabled = Self.txtBoolValue(txt, key: "bridgeTls")
+        let tlsFingerprint = Self.txtValue(txt, key: "bridgeTlsSha256")
+        let tlsParams = Self.resolveDiscoveredTLSParams(
+            stableID: stableID,
+            tlsEnabled: tlsEnabled,
+            tlsFingerprintSha256: tlsFingerprint)
+        return BridgeTarget(endpoint: endpoint, stableID: stableID, tls: tlsParams)
+    }
+
+    private static func resolveDiscoveredTLSParams(
+        stableID: String,
+        tlsEnabled: Bool,
+        tlsFingerprintSha256: String?) -> MacNodeBridgeTLSParams?
+    {
+        let stored = MacNodeBridgeTLSStore.loadFingerprint(stableID: stableID)
+
+        if tlsEnabled || tlsFingerprintSha256 != nil {
+            return MacNodeBridgeTLSParams(
+                required: true,
+                expectedFingerprint: tlsFingerprintSha256 ?? stored,
+                allowTOFU: stored == nil,
+                storeKey: stableID)
+        }
+
+        if let stored {
+            return MacNodeBridgeTLSParams(
+                required: true,
+                expectedFingerprint: stored,
+                allowTOFU: false,
+                storeKey: stableID)
+        }
+
+        return nil
+    }
+
+    private static func resolveManualTLSParams(stableID: String) -> MacNodeBridgeTLSParams? {
+        if let stored = MacNodeBridgeTLSStore.loadFingerprint(stableID: stableID) {
+            return MacNodeBridgeTLSParams(
+                required: true,
+                expectedFingerprint: stored,
+                allowTOFU: false,
+                storeKey: stableID)
+        }
+
+        return MacNodeBridgeTLSParams(
+            required: false,
+            expectedFingerprint: nil,
+            allowTOFU: true,
+            storeKey: stableID)
+    }
+
+    private static func txtValue(_ dict: [String: String], key: String) -> String? {
+        let raw = dict[key]?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return raw.isEmpty ? nil : raw
+    }
+
+    private static func txtBoolValue(_ dict: [String: String], key: String) -> Bool {
+        guard let raw = self.txtValue(dict, key: key)?.lowercased() else { return false }
+        return raw == "1" || raw == "true" || raw == "yes"
+    }
 }
 
 enum MacNodeTokenStore {

apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntime.swift

@@ -7,6 +7,7 @@ actor MacNodeRuntime {
     private let cameraCapture = CameraCaptureService()
     private let makeMainActorServices: () async -> any MacNodeRuntimeMainActorServices
     private var cachedMainActorServices: (any MacNodeRuntimeMainActorServices)?
+    private var mainSessionKey: String = "main"
 
     init(
         makeMainActorServices: @escaping () async -> any MacNodeRuntimeMainActorServices = {
@@ -16,6 +17,12 @@ actor MacNodeRuntime {
         self.makeMainActorServices = makeMainActorServices
     }
 
+    func updateMainSessionKey(_ sessionKey: String) {
+        let trimmed = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        self.mainSessionKey = trimmed
+    }
+
     func handleInvoke(_ req: BridgeInvokeRequest) async -> BridgeInvokeResponse {
         let command = req.command
         if self.isCanvasCommand(command), !Self.canvasEnabled() {
@@ -72,28 +79,32 @@ actor MacNodeRuntime {
             let placement = params.placement.map {
                 CanvasPlacement(x: $0.x, y: $0.y, width: $0.width, height: $0.height)
             }
+            let sessionKey = self.mainSessionKey
             try await MainActor.run {
                 _ = try CanvasManager.shared.showDetailed(
-                    sessionKey: "main",
+                    sessionKey: sessionKey,
                     target: url,
                     placement: placement)
             }
             return BridgeInvokeResponse(id: req.id, ok: true)
         case ClawdbotCanvasCommand.hide.rawValue:
+            let sessionKey = self.mainSessionKey
             await MainActor.run {
-                CanvasManager.shared.hide(sessionKey: "main")
+                CanvasManager.shared.hide(sessionKey: sessionKey)
             }
             return BridgeInvokeResponse(id: req.id, ok: true)
         case ClawdbotCanvasCommand.navigate.rawValue:
             let params = try Self.decodeParams(ClawdbotCanvasNavigateParams.self, from: req.paramsJSON)
+            let sessionKey = self.mainSessionKey
             try await MainActor.run {
-                _ = try CanvasManager.shared.show(sessionKey: "main", path: params.url)
+                _ = try CanvasManager.shared.show(sessionKey: sessionKey, path: params.url)
             }
             return BridgeInvokeResponse(id: req.id, ok: true)
         case ClawdbotCanvasCommand.evalJS.rawValue:
             let params = try Self.decodeParams(ClawdbotCanvasEvalParams.self, from: req.paramsJSON)
+            let sessionKey = self.mainSessionKey
             let result = try await CanvasManager.shared.eval(
-                sessionKey: "main",
+                sessionKey: sessionKey,
                 javaScript: params.javaScript)
             let payload = try Self.encodePayload(["result": result] as [String: String])
             return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
@@ -109,7 +120,8 @@ actor MacNodeRuntime {
             }()
             let quality = params?.quality ?? 0.9
 
-            let path = try await CanvasManager.shared.snapshot(sessionKey: "main", outPath: nil)
+            let sessionKey = self.mainSessionKey
+            let path = try await CanvasManager.shared.snapshot(sessionKey: sessionKey, outPath: nil)
             defer { try? FileManager.default.removeItem(atPath: path) }
             let data = try Data(contentsOf: URL(fileURLWithPath: path))
             guard let image = NSImage(data: data) else {
@@ -319,7 +331,8 @@ actor MacNodeRuntime {
     private func handleA2UIReset(_ req: BridgeInvokeRequest) async throws -> BridgeInvokeResponse {
         try await self.ensureA2UIHost()
 
-        let json = try await CanvasManager.shared.eval(sessionKey: "main", javaScript: """
+        let sessionKey = self.mainSessionKey
+        let json = try await CanvasManager.shared.eval(sessionKey: sessionKey, javaScript: """
         (() => {
           if (!globalThis.clawdbotA2UI) return JSON.stringify({ ok: false, error: "missing clawdbotA2UI" });
           return JSON.stringify(globalThis.clawdbotA2UI.reset());
@@ -358,7 +371,8 @@ actor MacNodeRuntime {
           }
         })()
         """
-        let resultJSON = try await CanvasManager.shared.eval(sessionKey: "main", javaScript: js)
+        let sessionKey = self.mainSessionKey
+        let resultJSON = try await CanvasManager.shared.eval(sessionKey: sessionKey, javaScript: js)
         return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: resultJSON)
     }
 
@@ -369,8 +383,9 @@ actor MacNodeRuntime {
                 NSLocalizedDescriptionKey: "A2UI_HOST_NOT_CONFIGURED: gateway did not advertise canvas host",
             ])
         }
+        let sessionKey = self.mainSessionKey
         _ = try await MainActor.run {
-            try CanvasManager.shared.show(sessionKey: "main", path: a2uiUrl)
+            try CanvasManager.shared.show(sessionKey: sessionKey, path: a2uiUrl)
         }
         if await self.isA2UIReady(poll: true) { return }
         throw NSError(domain: "Canvas", code: 31, userInfo: [
@@ -389,7 +404,8 @@ actor MacNodeRuntime {
         let deadline = poll ? Date().addingTimeInterval(6.0) : Date()
         while true {
             do {
-                let ready = try await CanvasManager.shared.eval(sessionKey: "main", javaScript: """
+                let sessionKey = self.mainSessionKey
+                let ready = try await CanvasManager.shared.eval(sessionKey: sessionKey, javaScript: """
                 (() => String(Boolean(globalThis.clawdbotA2UI)))()
                 """)
                 let trimmed = ready.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -410,6 +426,37 @@ actor MacNodeRuntime {
             return Self.errorResponse(req, code: .invalidRequest, message: "INVALID_REQUEST: command required")
         }
 
+        let wasAllowlisted = SystemRunAllowlist.contains(command)
+        switch Self.systemRunPolicy() {
+        case .never:
+            return Self.errorResponse(
+                req,
+                code: .unavailable,
+                message: "SYSTEM_RUN_DISABLED: policy=never")
+        case .always:
+            break
+        case .ask:
+            if !wasAllowlisted {
+                let services = await self.mainActorServices()
+                let decision = await services.confirmSystemRun(
+                    command: SystemRunAllowlist.displayString(for: command),
+                    cwd: params.cwd)
+                switch decision {
+                case .allowOnce:
+                    break
+                case .allowAlways:
+                    SystemRunAllowlist.add(command)
+                case .deny:
+                    return Self.errorResponse(
+                        req,
+                        code: .unavailable,
+                        message: "SYSTEM_RUN_DENIED: user denied")
+                }
+            }
+        }
+
+        let env = Self.sanitizedEnv(params.env)
+
         if params.needsScreenRecording == true {
             let authorized = await PermissionManager
                 .status([.screenRecording])[.screenRecording] ?? false
@@ -425,7 +472,7 @@ actor MacNodeRuntime {
         let result = await ShellExecutor.runDetailed(
             command: command,
             cwd: params.cwd,
-            env: params.env,
+            env: env,
             timeout: timeoutSec)
 
         struct RunPayload: Encodable {
@@ -513,6 +560,39 @@ actor MacNodeRuntime {
         UserDefaults.standard.object(forKey: cameraEnabledKey) as? Bool ?? false
     }
 
+    private nonisolated static func systemRunPolicy() -> SystemRunPolicy {
+        SystemRunPolicy.load()
+    }
+
+    private static let blockedEnvKeys: Set<String> = [
+        "PATH",
+        "NODE_OPTIONS",
+        "PYTHONHOME",
+        "PYTHONPATH",
+        "PERL5LIB",
+        "PERL5OPT",
+        "RUBYOPT",
+    ]
+
+    private static let blockedEnvPrefixes: [String] = [
+        "DYLD_",
+        "LD_",
+    ]
+
+    private static func sanitizedEnv(_ overrides: [String: String]?) -> [String: String]? {
+        guard let overrides else { return nil }
+        var merged = ProcessInfo.processInfo.environment
+        for (rawKey, value) in overrides {
+            let key = rawKey.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !key.isEmpty else { continue }
+            let upper = key.uppercased()
+            if blockedEnvKeys.contains(upper) { continue }
+            if blockedEnvPrefixes.contains(where: { upper.hasPrefix($0) }) { continue }
+            merged[key] = value
+        }
+        return merged
+    }
+
     private nonisolated static func locationMode() -> ClawdbotLocationMode {
         let raw = UserDefaults.standard.string(forKey: locationModeKey) ?? "off"
         return ClawdbotLocationMode(rawValue: raw) ?? .off

apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntimeMainActorServices.swift

@@ -1,7 +1,14 @@
+import AppKit
 import ClawdbotKit
 import CoreLocation
 import Foundation
 
+enum SystemRunDecision: Sendable {
+    case allowOnce
+    case allowAlways
+    case deny
+}
+
 @MainActor
 protocol MacNodeRuntimeMainActorServices: Sendable {
     func recordScreen(
@@ -17,6 +24,8 @@ protocol MacNodeRuntimeMainActorServices: Sendable {
         desiredAccuracy: ClawdbotLocationAccuracy,
         maxAgeMs: Int?,
         timeoutMs: Int?) async throws -> CLLocation
+
+    func confirmSystemRun(command: String, cwd: String?) async -> SystemRunDecision
 }
 
 @MainActor
@@ -57,4 +66,31 @@ final class LiveMacNodeRuntimeMainActorServices: MacNodeRuntimeMainActorServices
             maxAgeMs: maxAgeMs,
             timeoutMs: timeoutMs)
     }
+
+    func confirmSystemRun(command: String, cwd: String?) async -> SystemRunDecision {
+        let alert = NSAlert()
+        alert.alertStyle = .warning
+        alert.messageText = "Allow this command?"
+
+        var details = "Clawdbot wants to run:\n\n\(command)"
+        let trimmedCwd = cwd?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedCwd.isEmpty {
+            details += "\n\nWorking directory:\n\(trimmedCwd)"
+        }
+        details += "\n\nThis runs on this Mac via node mode."
+        alert.informativeText = details
+
+        alert.addButton(withTitle: "Allow Once")
+        alert.addButton(withTitle: "Always Allow")
+        alert.addButton(withTitle: "Don't Allow")
+
+        switch alert.runModal() {
+        case .alertFirstButtonReturn:
+            return .allowOnce
+        case .alertSecondButtonReturn:
+            return .allowAlways
+        default:
+            return .deny
+        }
+    }
 }

apps/macos/Sources/Clawdbot/OnboardingWizard.swift

@@ -58,6 +58,13 @@ final class OnboardingWizardModel {
     func startIfNeeded(mode: AppState.ConnectionMode, workspace: String? = nil) async {
         guard self.sessionId == nil, !self.isStarting else { return }
         guard mode == .local else { return }
+        if self.shouldSkipWizard() {
+            self.sessionId = nil
+            self.currentStep = nil
+            self.status = "done"
+            self.errorMessage = nil
+            return
+        }
         self.isStarting = true
         self.errorMessage = nil
         self.lastStartMode = mode
@@ -177,6 +184,33 @@ final class OnboardingWizardModel {
         Task { await self.startIfNeeded(mode: mode, workspace: self.lastStartWorkspace) }
         return true
     }
+
+    private func shouldSkipWizard() -> Bool {
+        let root = ClawdbotConfigFile.loadDict()
+        if let wizard = root["wizard"] as? [String: Any], !wizard.isEmpty {
+            return true
+        }
+        if let gateway = root["gateway"] as? [String: Any],
+           let auth = gateway["auth"] as? [String: Any]
+        {
+            if let mode = auth["mode"] as? String,
+               !mode.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            {
+                return true
+            }
+            if let token = auth["token"] as? String,
+               !token.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            {
+                return true
+            }
+            if let password = auth["password"] as? String,
+               !password.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            {
+                return true
+            }
+        }
+        return false
+    }
 }
 
 struct OnboardingWizardStepView: View {

apps/macos/Sources/Clawdbot/SystemRunPolicy.swift

@@ -0,0 +1,89 @@
+import Foundation
+
+enum SystemRunPolicy: String, CaseIterable, Identifiable {
+    case never
+    case ask
+    case always
+
+    var id: String { self.rawValue }
+
+    var title: String {
+        switch self {
+        case .never:
+            return "Never"
+        case .ask:
+            return "Always Ask"
+        case .always:
+            return "Always Allow"
+        }
+    }
+
+    static func load(from defaults: UserDefaults = .standard) -> SystemRunPolicy {
+        if let policy = MacNodeConfigFile.systemRunPolicy() {
+            return policy
+        }
+        if let raw = defaults.string(forKey: systemRunPolicyKey),
+           let policy = SystemRunPolicy(rawValue: raw)
+        {
+            MacNodeConfigFile.setSystemRunPolicy(policy)
+            return policy
+        }
+        if let legacy = defaults.object(forKey: systemRunEnabledKey) as? Bool {
+            let policy: SystemRunPolicy = legacy ? .ask : .never
+            MacNodeConfigFile.setSystemRunPolicy(policy)
+            return policy
+        }
+        let fallback: SystemRunPolicy = .ask
+        MacNodeConfigFile.setSystemRunPolicy(fallback)
+        return fallback
+    }
+}
+
+enum SystemRunAllowlist {
+    static func key(for argv: [String]) -> String {
+        let trimmed = argv.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+        guard !trimmed.isEmpty else { return "" }
+        if let data = try? JSONEncoder().encode(trimmed),
+           let json = String(data: data, encoding: .utf8)
+        {
+            return json
+        }
+        return trimmed.joined(separator: " ")
+    }
+
+    static func displayString(for argv: [String]) -> String {
+        argv.map { arg in
+            let trimmed = arg.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { return "\"\"" }
+            let needsQuotes = trimmed.contains { $0.isWhitespace || $0 == "\"" }
+            if !needsQuotes { return trimmed }
+            let escaped = trimmed.replacingOccurrences(of: "\"", with: "\\\"")
+            return "\"\(escaped)\""
+        }.joined(separator: " ")
+    }
+
+    static func load(from defaults: UserDefaults = .standard) -> Set<String> {
+        if let allowlist = MacNodeConfigFile.systemRunAllowlist() {
+            return Set(allowlist)
+        }
+        if let legacy = defaults.stringArray(forKey: systemRunAllowlistKey), !legacy.isEmpty {
+            MacNodeConfigFile.setSystemRunAllowlist(legacy)
+            return Set(legacy)
+        }
+        return []
+    }
+
+    static func contains(_ argv: [String], defaults: UserDefaults = .standard) -> Bool {
+        let key = key(for: argv)
+        return load(from: defaults).contains(key)
+    }
+
+    static func add(_ argv: [String], defaults: UserDefaults = .standard) {
+        let key = key(for: argv)
+        guard !key.isEmpty else { return }
+        var allowlist = load(from: defaults)
+        if allowlist.insert(key).inserted {
+            MacNodeConfigFile.setSystemRunAllowlist(Array(allowlist).sorted())
+        }
+    }
+}

apps/macos/Sources/Clawdbot/WorkActivityStore.swift

@@ -28,9 +28,11 @@ final class WorkActivityStore {
     private var currentSessionKey: String?
     private var toolSeqBySession: [String: Int] = [:]
 
-    private let mainSessionKey = "main"
+    private var mainSessionKeyStorage = "main"
     private let toolResultGrace: TimeInterval = 2.0
 
+    var mainSessionKey: String { self.mainSessionKeyStorage }
+
     func handleJob(sessionKey: String, state: String) {
         let isStart = state.lowercased() == "started" || state.lowercased() == "streaming"
         if isStart {
@@ -129,6 +131,17 @@ final class WorkActivityStore {
         self.refreshDerivedState()
     }
 
+    func setMainSessionKey(_ sessionKey: String) {
+        let trimmed = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        guard trimmed != self.mainSessionKeyStorage else { return }
+        self.mainSessionKeyStorage = trimmed
+        if let current = self.currentSessionKey, !self.isActive(sessionKey: current) {
+            self.pickNextSession()
+        }
+        self.refreshDerivedState()
+    }
+
     private func clearJob(sessionKey: String) {
         guard self.jobs[sessionKey] != nil else { return }
         self.jobs.removeValue(forKey: sessionKey)
@@ -151,8 +164,8 @@ final class WorkActivityStore {
 
     private func pickNextSession() {
         // Prefer main if present.
-        if self.isActive(sessionKey: self.mainSessionKey) {
-            self.currentSessionKey = self.mainSessionKey
+        if self.isActive(sessionKey: self.mainSessionKeyStorage) {
+            self.currentSessionKey = self.mainSessionKeyStorage
             return
         }
 
@@ -163,7 +176,7 @@ final class WorkActivityStore {
     }
 
     private func role(for sessionKey: String) -> SessionRole {
-        sessionKey == self.mainSessionKey ? .main : .other
+        sessionKey == self.mainSessionKeyStorage ? .main : .other
     }
 
     private func isActive(sessionKey: String) -> Bool {

apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -252,6 +252,7 @@ public struct Snapshot: Codable, Sendable {
     public let uptimems: Int
     public let configpath: String?
     public let statedir: String?
+    public let sessiondefaults: [String: AnyCodable]?
 
     public init(
         presence: [PresenceEntry],
@@ -259,7 +260,8 @@ public struct Snapshot: Codable, Sendable {
         stateversion: StateVersion,
         uptimems: Int,
         configpath: String?,
-        statedir: String?
+        statedir: String?,
+        sessiondefaults: [String: AnyCodable]?
     ) {
         self.presence = presence
         self.health = health
@@ -267,6 +269,7 @@ public struct Snapshot: Codable, Sendable {
         self.uptimems = uptimems
         self.configpath = configpath
         self.statedir = statedir
+        self.sessiondefaults = sessiondefaults
     }
     private enum CodingKeys: String, CodingKey {
         case presence
@@ -275,6 +278,7 @@ public struct Snapshot: Codable, Sendable {
         case uptimems = "uptimeMs"
         case configpath = "configPath"
         case statedir = "stateDir"
+        case sessiondefaults = "sessionDefaults"
     }
 }
 
@@ -845,42 +849,67 @@ public struct ConfigGetParams: Codable, Sendable {
 
 public struct ConfigSetParams: Codable, Sendable {
     public let raw: String
+    public let basehash: String?
 
     public init(
-        raw: String
+        raw: String,
+        basehash: String?
     ) {
         self.raw = raw
+        self.basehash = basehash
     }
     private enum CodingKeys: String, CodingKey {
         case raw
+        case basehash = "baseHash"
     }
 }
 
 public struct ConfigApplyParams: Codable, Sendable {
     public let raw: String
+    public let basehash: String?
     public let sessionkey: String?
     public let note: String?
     public let restartdelayms: Int?
 
     public init(
         raw: String,
+        basehash: String?,
         sessionkey: String?,
         note: String?,
         restartdelayms: Int?
     ) {
         self.raw = raw
+        self.basehash = basehash
         self.sessionkey = sessionkey
         self.note = note
         self.restartdelayms = restartdelayms
     }
     private enum CodingKeys: String, CodingKey {
         case raw
+        case basehash = "baseHash"
         case sessionkey = "sessionKey"
         case note
         case restartdelayms = "restartDelayMs"
     }
 }
 
+public struct ConfigPatchParams: Codable, Sendable {
+    public let raw: String
+    public let basehash: String?
+
+    public init(
+        raw: String,
+        basehash: String?
+    ) {
+        self.raw = raw
+        self.basehash = basehash
+    }
+    private enum CodingKeys: String, CodingKey {
+        case raw
+        case basehash = "baseHash"
+    }
+}
+
 public struct ConfigSchemaParams: Codable, Sendable {
 }
 
@@ -1650,6 +1679,27 @@ public struct ChatAbortParams: Codable, Sendable {
     }
 }
 
+public struct ChatInjectParams: Codable, Sendable {
+    public let sessionkey: String
+    public let message: String
+    public let label: String?
+
+    public init(
+        sessionkey: String,
+        message: String,
+        label: String?
+    ) {
+        self.sessionkey = sessionkey
+        self.message = message
+        self.label = label
+    }
+    private enum CodingKeys: String, CodingKey {
+        case sessionkey = "sessionKey"
+        case message
+        case label
+    }
+}
+
 public struct ChatEvent: Codable, Sendable {
     public let runid: String
     public let sessionkey: String

apps/macos/Tests/ClawdbotIPCTests/ConnectionsSettingsSmokeTests.swift

@@ -4,22 +4,22 @@ import Testing
 
 @Suite(.serialized)
 @MainActor
-    struct ConnectionsSettingsSmokeTests {
-        @Test func connectionsSettingsBuildsBodyWithSnapshot() {
-            let store = ConnectionsStore(isPreview: true)
-            store.snapshot = ChannelsStatusSnapshot(
-                ts: 1_700_000_000_000,
-                channelOrder: ["whatsapp", "telegram", "signal", "imessage"],
-                channelLabels: [
-                    "whatsapp": "WhatsApp",
-                    "telegram": "Telegram",
-                    "signal": "Signal",
-                    "imessage": "iMessage",
-                ],
-                channels: [
-                    "whatsapp": AnyCodable([
-                        "configured": true,
-                        "linked": true,
+struct ConnectionsSettingsSmokeTests {
+    @Test func connectionsSettingsBuildsBodyWithSnapshot() {
+        let store = ConnectionsStore(isPreview: true)
+        store.snapshot = ChannelsStatusSnapshot(
+            ts: 1_700_000_000_000,
+            channelOrder: ["whatsapp", "telegram", "signal", "imessage"],
+            channelLabels: [
+                "whatsapp": "WhatsApp",
+                "telegram": "Telegram",
+                "signal": "Signal",
+                "imessage": "iMessage",
+            ],
+            channels: [
+                "whatsapp": AnyCodable([
+                    "configured": true,
+                    "linked": true,
                     "authAgeMs": 86_400_000,
                     "self": ["e164": "+15551234567"],
                     "running": true,
@@ -70,13 +70,13 @@ import Testing
                     "lastError": "not configured",
                     "probe": ["ok": false, "error": "imsg not found (imsg)"],
                     "lastProbeAt": 1_700_000_050_000,
-                    ]),
-                ],
-                channelAccounts: [:],
-                channelDefaultAccountId: [
-                    "whatsapp": "default",
-                    "telegram": "default",
-                    "signal": "default",
+                ]),
+            ],
+            channelAccounts: [:],
+            channelDefaultAccountId: [
+                "whatsapp": "default",
+                "telegram": "default",
+                "signal": "default",
                 "imessage": "default",
             ])
 
@@ -93,23 +93,23 @@ import Testing
 
         let view = ConnectionsSettings(store: store)
         _ = view.body
-        }
+    }
 
-        @Test func connectionsSettingsBuildsBodyWithoutSnapshot() {
-            let store = ConnectionsStore(isPreview: true)
-            store.snapshot = ChannelsStatusSnapshot(
-                ts: 1_700_000_000_000,
-                channelOrder: ["whatsapp", "telegram", "signal", "imessage"],
-                channelLabels: [
-                    "whatsapp": "WhatsApp",
-                    "telegram": "Telegram",
-                    "signal": "Signal",
-                    "imessage": "iMessage",
-                ],
-                channels: [
-                    "whatsapp": AnyCodable([
-                        "configured": false,
-                        "linked": false,
+    @Test func connectionsSettingsBuildsBodyWithoutSnapshot() {
+        let store = ConnectionsStore(isPreview: true)
+        store.snapshot = ChannelsStatusSnapshot(
+            ts: 1_700_000_000_000,
+            channelOrder: ["whatsapp", "telegram", "signal", "imessage"],
+            channelLabels: [
+                "whatsapp": "WhatsApp",
+                "telegram": "Telegram",
+                "signal": "Signal",
+                "imessage": "iMessage",
+            ],
+            channels: [
+                "whatsapp": AnyCodable([
+                    "configured": false,
+                    "linked": false,
                     "running": false,
                     "connected": false,
                     "reconnectAttempts": 0,
@@ -146,13 +146,13 @@ import Testing
                     "cliPath": "imsg",
                     "probe": ["ok": false, "error": "imsg not found (imsg)"],
                     "lastProbeAt": 1_700_000_200_000,
-                    ]),
-                ],
-                channelAccounts: [:],
-                channelDefaultAccountId: [
-                    "whatsapp": "default",
-                    "telegram": "default",
-                    "signal": "default",
+                ]),
+            ],
+            channelAccounts: [:],
+            channelDefaultAccountId: [
+                "whatsapp": "default",
+                "telegram": "default",
+                "signal": "default",
                 "imessage": "default",
             ])
 

apps/macos/Tests/ClawdbotIPCTests/GatewayEndpointStoreTests.swift

@@ -1,36 +1,63 @@
+import Foundation
 import Testing
 @testable import Clawdbot
 
-@Suite(.serialized)
-struct GatewayEndpointStoreTests {
-    @Test func resolvesLocalHostFromBindModes() {
-        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
-            bindMode: "loopback",
-            tailscaleIP: "100.64.0.10") == "127.0.0.1")
-        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
-            bindMode: "lan",
-            tailscaleIP: "100.64.0.10") == "127.0.0.1")
-        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
-            bindMode: "tailnet",
-            tailscaleIP: "100.64.0.10") == "100.64.0.10")
-        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
-            bindMode: "tailnet",
-            tailscaleIP: nil) == "127.0.0.1")
-        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
-            bindMode: "auto",
-            tailscaleIP: "100.64.0.10") == "100.64.0.10")
-        #expect(GatewayEndpointStore._testResolveLocalGatewayHost(
-            bindMode: "auto",
-            tailscaleIP: nil) == "127.0.0.1")
+@Suite struct GatewayEndpointStoreTests {
+    @Test func resolveGatewayTokenPrefersEnvAndFallsBackToLaunchd() {
+        let snapshot = LaunchAgentPlistSnapshot(
+            programArguments: [],
+            environment: ["CLAWDBOT_GATEWAY_TOKEN": "launchd-token"],
+            port: nil,
+            bind: nil,
+            token: "launchd-token",
+            password: nil)
+
+        let envToken = GatewayEndpointStore._testResolveGatewayToken(
+            isRemote: false,
+            root: [:],
+            env: ["CLAWDBOT_GATEWAY_TOKEN": "env-token"],
+            launchdSnapshot: snapshot)
+        #expect(envToken == "env-token")
+
+        let fallbackToken = GatewayEndpointStore._testResolveGatewayToken(
+            isRemote: false,
+            root: [:],
+            env: [:],
+            launchdSnapshot: snapshot)
+        #expect(fallbackToken == "launchd-token")
     }
 
-    @Test func resolvesBindModeFromEnvOrConfig() {
-        let root: [String: Any] = ["gateway": ["bind": "tailnet"]]
-        #expect(GatewayEndpointStore._testResolveGatewayBindMode(
-            root: root,
-            env: [:]) == "tailnet")
-        #expect(GatewayEndpointStore._testResolveGatewayBindMode(
-            root: root,
-            env: ["CLAWDBOT_GATEWAY_BIND": "lan"]) == "lan")
+    @Test func resolveGatewayTokenIgnoresLaunchdInRemoteMode() {
+        let snapshot = LaunchAgentPlistSnapshot(
+            programArguments: [],
+            environment: ["CLAWDBOT_GATEWAY_TOKEN": "launchd-token"],
+            port: nil,
+            bind: nil,
+            token: "launchd-token",
+            password: nil)
+
+        let token = GatewayEndpointStore._testResolveGatewayToken(
+            isRemote: true,
+            root: [:],
+            env: [:],
+            launchdSnapshot: snapshot)
+        #expect(token == nil)
+    }
+
+    @Test func resolveGatewayPasswordFallsBackToLaunchd() {
+        let snapshot = LaunchAgentPlistSnapshot(
+            programArguments: [],
+            environment: ["CLAWDBOT_GATEWAY_PASSWORD": "launchd-pass"],
+            port: nil,
+            bind: nil,
+            token: nil,
+            password: "launchd-pass")
+
+        let password = GatewayEndpointStore._testResolveGatewayPassword(
+            isRemote: false,
+            root: [:],
+            env: [:],
+            launchdSnapshot: snapshot)
+        #expect(password == "launchd-pass")
     }
 }

apps/macos/Tests/ClawdbotIPCTests/HealthDecodeTests.swift

@@ -2,9 +2,9 @@ import Foundation
 import Testing
 @testable import Clawdbot
 
-    @Suite struct HealthDecodeTests {
-        private let sampleJSON: String = // minimal but complete payload
-            """
+@Suite struct HealthDecodeTests {
+    private let sampleJSON: String = // minimal but complete payload
+        """
         {"ts":1733622000,"durationMs":420,"channels":{"whatsapp":{"linked":true,"authAgeMs":120000},"telegram":{"configured":true,"probe":{"ok":true,"elapsedMs":800}}},"channelOrder":["whatsapp","telegram"],"heartbeatSeconds":60,"sessions":{"path":"/tmp/sessions.json","count":1,"recent":[{"key":"abc","updatedAt":1733621900,"age":120000}]}}
         """
 

apps/macos/Tests/ClawdbotIPCTests/LogLocatorTests.swift

@@ -0,0 +1,24 @@
+import Darwin
+import Foundation
+import Testing
+@testable import Clawdbot
+
+@Suite struct LogLocatorTests {
+    @Test func launchdGatewayLogPathEnsuresTmpDirExists() throws {
+        let fm = FileManager.default
+        let baseDir = URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
+        let logDir = baseDir.appendingPathComponent("clawdbot-tests-\(UUID().uuidString)")
+
+        setenv("CLAWDBOT_LOG_DIR", logDir.path, 1)
+        defer {
+            unsetenv("CLAWDBOT_LOG_DIR")
+            try? fm.removeItem(at: logDir)
+        }
+
+        _ = LogLocator.launchdGatewayLogPath
+
+        var isDir: ObjCBool = false
+        #expect(fm.fileExists(atPath: logDir.path, isDirectory: &isDir))
+        #expect(isDir.boolValue == true)
+    }
+}

apps/shared/ClawdbotKit/Sources/ClawdbotKit/BridgeFrames.swift

@@ -100,11 +100,18 @@ public struct BridgeHelloOk: Codable, Sendable {
     public let type: String
     public let serverName: String
     public let canvasHostUrl: String?
+    public let mainSessionKey: String?
 
-    public init(type: String = "hello-ok", serverName: String, canvasHostUrl: String? = nil) {
+    public init(
+        type: String = "hello-ok",
+        serverName: String,
+        canvasHostUrl: String? = nil,
+        mainSessionKey: String? = nil)
+    {
         self.type = type
         self.serverName = serverName
         self.canvasHostUrl = canvasHostUrl
+        self.mainSessionKey = mainSessionKey
     }
 }
 

assets/chrome-extension/README.md

@@ -0,0 +1,22 @@
+# Clawdbot Chrome Extension (Browser Relay)
+
+Purpose: attach Clawdbot to an existing Chrome tab so the Gateway can automate it (via the local CDP relay server).
+
+## Dev / load unpacked
+
+1. Build/run Clawdbot Gateway with browser control enabled.
+2. Ensure the relay server is reachable at `http://127.0.0.1:18792/` (default).
+3. Install the extension to a stable path:
+
+   ```bash
+   clawdbot browser extension install
+   clawdbot browser extension path
+   ```
+
+4. Chrome → `chrome://extensions` → enable “Developer mode”.
+5. “Load unpacked” → select the path printed above.
+6. Pin the extension. Click the icon on a tab to attach/detach.
+
+## Options
+
+- `Relay port`: defaults to `18792`.

assets/chrome-extension/background.js

@@ -0,0 +1,438 @@
+const DEFAULT_PORT = 18792
+
+const BADGE = {
+  on: { text: 'ON', color: '#FF5A36' },
+  off: { text: '', color: '#000000' },
+  connecting: { text: '…', color: '#F59E0B' },
+  error: { text: '!', color: '#B91C1C' },
+}
+
+/** @type {WebSocket|null} */
+let relayWs = null
+/** @type {Promise<void>|null} */
+let relayConnectPromise = null
+
+let debuggerListenersInstalled = false
+
+let nextSession = 1
+
+/** @type {Map<number, {state:'connecting'|'connected', sessionId?:string, targetId?:string, attachOrder?:number}>} */
+const tabs = new Map()
+/** @type {Map<string, number>} */
+const tabBySession = new Map()
+/** @type {Map<string, number>} */
+const childSessionToTab = new Map()
+
+/** @type {Map<number, {resolve:(v:any)=>void, reject:(e:Error)=>void}>} */
+const pending = new Map()
+
+function nowStack() {
+  try {
+    return new Error().stack || ''
+  } catch {
+    return ''
+  }
+}
+
+async function getRelayPort() {
+  const stored = await chrome.storage.local.get(['relayPort'])
+  const raw = stored.relayPort
+  const n = Number.parseInt(String(raw || ''), 10)
+  if (!Number.isFinite(n) || n <= 0 || n > 65535) return DEFAULT_PORT
+  return n
+}
+
+function setBadge(tabId, kind) {
+  const cfg = BADGE[kind]
+  void chrome.action.setBadgeText({ tabId, text: cfg.text })
+  void chrome.action.setBadgeBackgroundColor({ tabId, color: cfg.color })
+  void chrome.action.setBadgeTextColor({ tabId, color: '#FFFFFF' }).catch(() => {})
+}
+
+async function ensureRelayConnection() {
+  if (relayWs && relayWs.readyState === WebSocket.OPEN) return
+  if (relayConnectPromise) return await relayConnectPromise
+
+  relayConnectPromise = (async () => {
+    const port = await getRelayPort()
+    const httpBase = `http://127.0.0.1:${port}`
+    const wsUrl = `ws://127.0.0.1:${port}/extension`
+
+    // Fast preflight: is the relay server up?
+    try {
+      await fetch(`${httpBase}/`, { method: 'HEAD', signal: AbortSignal.timeout(2000) })
+    } catch (err) {
+      throw new Error(`Relay server not reachable at ${httpBase} (${String(err)})`)
+    }
+
+    const ws = new WebSocket(wsUrl)
+    relayWs = ws
+
+    await new Promise((resolve, reject) => {
+      const t = setTimeout(() => reject(new Error('WebSocket connect timeout')), 5000)
+      ws.onopen = () => {
+        clearTimeout(t)
+        resolve()
+      }
+      ws.onerror = () => {
+        clearTimeout(t)
+        reject(new Error('WebSocket connect failed'))
+      }
+      ws.onclose = (ev) => {
+        clearTimeout(t)
+        reject(new Error(`WebSocket closed (${ev.code} ${ev.reason || 'no reason'})`))
+      }
+    })
+
+    ws.onmessage = (event) => void onRelayMessage(String(event.data || ''))
+    ws.onclose = () => onRelayClosed('closed')
+    ws.onerror = () => onRelayClosed('error')
+
+    if (!debuggerListenersInstalled) {
+      debuggerListenersInstalled = true
+      chrome.debugger.onEvent.addListener(onDebuggerEvent)
+      chrome.debugger.onDetach.addListener(onDebuggerDetach)
+    }
+  })()
+
+  try {
+    await relayConnectPromise
+  } finally {
+    relayConnectPromise = null
+  }
+}
+
+function onRelayClosed(reason) {
+  relayWs = null
+  for (const [id, p] of pending.entries()) {
+    pending.delete(id)
+    p.reject(new Error(`Relay disconnected (${reason})`))
+  }
+
+  for (const tabId of tabs.keys()) {
+    void chrome.debugger.detach({ tabId }).catch(() => {})
+    setBadge(tabId, 'connecting')
+    void chrome.action.setTitle({
+      tabId,
+      title: 'Clawdbot Browser Relay: disconnected (click to re-attach)',
+    })
+  }
+  tabs.clear()
+  tabBySession.clear()
+  childSessionToTab.clear()
+}
+
+function sendToRelay(payload) {
+  const ws = relayWs
+  if (!ws || ws.readyState !== WebSocket.OPEN) {
+    throw new Error('Relay not connected')
+  }
+  ws.send(JSON.stringify(payload))
+}
+
+async function maybeOpenHelpOnce() {
+  try {
+    const stored = await chrome.storage.local.get(['helpOnErrorShown'])
+    if (stored.helpOnErrorShown === true) return
+    await chrome.storage.local.set({ helpOnErrorShown: true })
+    await chrome.runtime.openOptionsPage()
+  } catch {
+    // ignore
+  }
+}
+
+function requestFromRelay(command) {
+  const id = command.id
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject })
+    try {
+      sendToRelay(command)
+    } catch (err) {
+      pending.delete(id)
+      reject(err instanceof Error ? err : new Error(String(err)))
+    }
+  })
+}
+
+async function onRelayMessage(text) {
+  /** @type {any} */
+  let msg
+  try {
+    msg = JSON.parse(text)
+  } catch {
+    return
+  }
+
+  if (msg && msg.method === 'ping') {
+    try {
+      sendToRelay({ method: 'pong' })
+    } catch {
+      // ignore
+    }
+    return
+  }
+
+  if (msg && typeof msg.id === 'number' && (msg.result !== undefined || msg.error !== undefined)) {
+    const p = pending.get(msg.id)
+    if (!p) return
+    pending.delete(msg.id)
+    if (msg.error) p.reject(new Error(String(msg.error)))
+    else p.resolve(msg.result)
+    return
+  }
+
+  if (msg && typeof msg.id === 'number' && msg.method === 'forwardCDPCommand') {
+    try {
+      const result = await handleForwardCdpCommand(msg)
+      sendToRelay({ id: msg.id, result })
+    } catch (err) {
+      sendToRelay({ id: msg.id, error: err instanceof Error ? err.message : String(err) })
+    }
+  }
+}
+
+function getTabBySessionId(sessionId) {
+  const direct = tabBySession.get(sessionId)
+  if (direct) return { tabId: direct, kind: 'main' }
+  const child = childSessionToTab.get(sessionId)
+  if (child) return { tabId: child, kind: 'child' }
+  return null
+}
+
+function getTabByTargetId(targetId) {
+  for (const [tabId, tab] of tabs.entries()) {
+    if (tab.targetId === targetId) return tabId
+  }
+  return null
+}
+
+async function attachTab(tabId, opts = {}) {
+  const debuggee = { tabId }
+  await chrome.debugger.attach(debuggee, '1.3')
+  await chrome.debugger.sendCommand(debuggee, 'Page.enable').catch(() => {})
+
+  const info = /** @type {any} */ (await chrome.debugger.sendCommand(debuggee, 'Target.getTargetInfo'))
+  const targetInfo = info?.targetInfo
+  const targetId = String(targetInfo?.targetId || '').trim()
+  if (!targetId) {
+    throw new Error('Target.getTargetInfo returned no targetId')
+  }
+
+  const sessionId = `cb-tab-${nextSession++}`
+  const attachOrder = nextSession
+
+  tabs.set(tabId, { state: 'connected', sessionId, targetId, attachOrder })
+  tabBySession.set(sessionId, tabId)
+  void chrome.action.setTitle({
+    tabId,
+    title: 'Clawdbot Browser Relay: attached (click to detach)',
+  })
+
+  if (!opts.skipAttachedEvent) {
+    sendToRelay({
+      method: 'forwardCDPEvent',
+      params: {
+        method: 'Target.attachedToTarget',
+        params: {
+          sessionId,
+          targetInfo: { ...targetInfo, attached: true },
+          waitingForDebugger: false,
+        },
+      },
+    })
+  }
+
+  setBadge(tabId, 'on')
+  return { sessionId, targetId }
+}
+
+async function detachTab(tabId, reason) {
+  const tab = tabs.get(tabId)
+  if (tab?.sessionId && tab?.targetId) {
+    try {
+      sendToRelay({
+        method: 'forwardCDPEvent',
+        params: {
+          method: 'Target.detachedFromTarget',
+          params: { sessionId: tab.sessionId, targetId: tab.targetId, reason },
+        },
+      })
+    } catch {
+      // ignore
+    }
+  }
+
+  if (tab?.sessionId) tabBySession.delete(tab.sessionId)
+  tabs.delete(tabId)
+
+  for (const [childSessionId, parentTabId] of childSessionToTab.entries()) {
+    if (parentTabId === tabId) childSessionToTab.delete(childSessionId)
+  }
+
+  try {
+    await chrome.debugger.detach({ tabId })
+  } catch {
+    // ignore
+  }
+
+  setBadge(tabId, 'off')
+  void chrome.action.setTitle({
+    tabId,
+    title: 'Clawdbot Browser Relay (click to attach/detach)',
+  })
+}
+
+async function connectOrToggleForActiveTab() {
+  const [active] = await chrome.tabs.query({ active: true, currentWindow: true })
+  const tabId = active?.id
+  if (!tabId) return
+
+  const existing = tabs.get(tabId)
+  if (existing?.state === 'connected') {
+    await detachTab(tabId, 'toggle')
+    return
+  }
+
+  tabs.set(tabId, { state: 'connecting' })
+  setBadge(tabId, 'connecting')
+  void chrome.action.setTitle({
+    tabId,
+    title: 'Clawdbot Browser Relay: connecting to local relay…',
+  })
+
+  try {
+    await ensureRelayConnection()
+    await attachTab(tabId)
+  } catch (err) {
+    tabs.delete(tabId)
+    setBadge(tabId, 'error')
+    void chrome.action.setTitle({
+      tabId,
+      title: 'Clawdbot Browser Relay: relay not running (open options for setup)',
+    })
+    void maybeOpenHelpOnce()
+    // Extra breadcrumbs in chrome://extensions service worker logs.
+    const message = err instanceof Error ? err.message : String(err)
+    console.warn('attach failed', message, nowStack())
+  }
+}
+
+async function handleForwardCdpCommand(msg) {
+  const method = String(msg?.params?.method || '').trim()
+  const params = msg?.params?.params || undefined
+  const sessionId = typeof msg?.params?.sessionId === 'string' ? msg.params.sessionId : undefined
+
+  // Map command to tab
+  const bySession = sessionId ? getTabBySessionId(sessionId) : null
+  const targetId = typeof params?.targetId === 'string' ? params.targetId : undefined
+  const tabId =
+    bySession?.tabId ||
+    (targetId ? getTabByTargetId(targetId) : null) ||
+    (() => {
+      // No sessionId: pick the first connected tab (stable-ish).
+      for (const [id, tab] of tabs.entries()) {
+        if (tab.state === 'connected') return id
+      }
+      return null
+    })()
+
+  if (!tabId) throw new Error(`No attached tab for method ${method}`)
+
+  /** @type {chrome.debugger.DebuggerSession} */
+  const debuggee = { tabId }
+
+  if (method === 'Runtime.enable') {
+    try {
+      await chrome.debugger.sendCommand(debuggee, 'Runtime.disable')
+      await new Promise((r) => setTimeout(r, 50))
+    } catch {
+      // ignore
+    }
+    return await chrome.debugger.sendCommand(debuggee, 'Runtime.enable', params)
+  }
+
+  if (method === 'Target.createTarget') {
+    const url = typeof params?.url === 'string' ? params.url : 'about:blank'
+    const tab = await chrome.tabs.create({ url, active: false })
+    if (!tab.id) throw new Error('Failed to create tab')
+    await new Promise((r) => setTimeout(r, 100))
+    const attached = await attachTab(tab.id)
+    return { targetId: attached.targetId }
+  }
+
+  if (method === 'Target.closeTarget') {
+    const target = typeof params?.targetId === 'string' ? params.targetId : ''
+    const toClose = target ? getTabByTargetId(target) : tabId
+    if (!toClose) return { success: false }
+    try {
+      await chrome.tabs.remove(toClose)
+    } catch {
+      return { success: false }
+    }
+    return { success: true }
+  }
+
+  if (method === 'Target.activateTarget') {
+    const target = typeof params?.targetId === 'string' ? params.targetId : ''
+    const toActivate = target ? getTabByTargetId(target) : tabId
+    if (!toActivate) return {}
+    const tab = await chrome.tabs.get(toActivate).catch(() => null)
+    if (!tab) return {}
+    if (tab.windowId) {
+      await chrome.windows.update(tab.windowId, { focused: true }).catch(() => {})
+    }
+    await chrome.tabs.update(toActivate, { active: true }).catch(() => {})
+    return {}
+  }
+
+  const tabState = tabs.get(tabId)
+  const mainSessionId = tabState?.sessionId
+  const debuggerSession =
+    sessionId && mainSessionId && sessionId !== mainSessionId
+      ? { ...debuggee, sessionId }
+      : debuggee
+
+  return await chrome.debugger.sendCommand(debuggerSession, method, params)
+}
+
+function onDebuggerEvent(source, method, params) {
+  const tabId = source.tabId
+  if (!tabId) return
+  const tab = tabs.get(tabId)
+  if (!tab?.sessionId) return
+
+  if (method === 'Target.attachedToTarget' && params?.sessionId) {
+    childSessionToTab.set(String(params.sessionId), tabId)
+  }
+
+  if (method === 'Target.detachedFromTarget' && params?.sessionId) {
+    childSessionToTab.delete(String(params.sessionId))
+  }
+
+  try {
+    sendToRelay({
+      method: 'forwardCDPEvent',
+      params: {
+        sessionId: source.sessionId || tab.sessionId,
+        method,
+        params,
+      },
+    })
+  } catch {
+    // ignore
+  }
+}
+
+function onDebuggerDetach(source, reason) {
+  const tabId = source.tabId
+  if (!tabId) return
+  if (!tabs.has(tabId)) return
+  void detachTab(tabId, reason)
+}
+
+chrome.action.onClicked.addListener(() => void connectOrToggleForActiveTab())
+
+chrome.runtime.onInstalled.addListener(() => {
+  // Useful: first-time instructions.
+  void chrome.runtime.openOptionsPage()
+})

assets/chrome-extension/manifest.json

@@ -0,0 +1,25 @@
+{
+  "manifest_version": 3,
+  "name": "Clawdbot Browser Relay",
+  "version": "0.1.0",
+  "description": "Attach Clawdbot to your existing Chrome tab via a local CDP relay server.",
+  "icons": {
+    "16": "icons/icon16.png",
+    "32": "icons/icon32.png",
+    "48": "icons/icon48.png",
+    "128": "icons/icon128.png"
+  },
+  "permissions": ["debugger", "tabs", "activeTab", "storage"],
+  "host_permissions": ["http://127.0.0.1/*", "http://localhost/*"],
+  "background": { "service_worker": "background.js", "type": "module" },
+  "action": {
+    "default_title": "Clawdbot Browser Relay (click to attach/detach)",
+    "default_icon": {
+      "16": "icons/icon16.png",
+      "32": "icons/icon32.png",
+      "48": "icons/icon48.png",
+      "128": "icons/icon128.png"
+    }
+  },
+  "options_ui": { "page": "options.html", "open_in_tab": true }
+}

assets/chrome-extension/options.html

@@ -0,0 +1,197 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Clawdbot Browser Relay</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+        --accent: #ff5a36;
+        --panel: color-mix(in oklab, canvas 92%, canvasText 8%);
+        --border: color-mix(in oklab, canvasText 18%, transparent);
+        --muted: color-mix(in oklab, canvasText 70%, transparent);
+        --shadow: 0 10px 30px color-mix(in oklab, canvasText 18%, transparent);
+        font-family: ui-rounded, system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Rounded",
+          "SF Pro Display", "Segoe UI", sans-serif;
+        line-height: 1.4;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        background:
+          radial-gradient(1000px 500px at 10% 0%, color-mix(in oklab, var(--accent) 30%, transparent), transparent 70%),
+          radial-gradient(900px 450px at 90% 0%, color-mix(in oklab, var(--accent) 18%, transparent), transparent 75%),
+          canvas;
+        color: canvasText;
+      }
+      .wrap {
+        max-width: 820px;
+        margin: 36px auto;
+        padding: 0 24px 48px 24px;
+      }
+      header {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        margin-bottom: 18px;
+      }
+      .logo {
+        width: 44px;
+        height: 44px;
+        border-radius: 14px;
+        background: color-mix(in oklab, var(--accent) 18%, transparent);
+        border: 1px solid color-mix(in oklab, var(--accent) 35%, transparent);
+        box-shadow: var(--shadow);
+        display: grid;
+        place-items: center;
+      }
+      .logo img {
+        width: 28px;
+        height: 28px;
+        image-rendering: pixelated;
+      }
+      h1 {
+        font-size: 20px;
+        margin: 0;
+        letter-spacing: -0.01em;
+      }
+      .subtitle {
+        margin: 2px 0 0 0;
+        color: var(--muted);
+        font-size: 13px;
+      }
+      .grid {
+        display: grid;
+        grid-template-columns: 1fr;
+        gap: 14px;
+      }
+      .card {
+        background: var(--panel);
+        border: 1px solid var(--border);
+        border-radius: 16px;
+        padding: 16px;
+        box-shadow: var(--shadow);
+      }
+      .card h2 {
+        margin: 0 0 10px 0;
+        font-size: 14px;
+        letter-spacing: 0.01em;
+      }
+      .card p {
+        margin: 8px 0 0 0;
+        color: var(--muted);
+        font-size: 13px;
+      }
+      .row {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        flex-wrap: wrap;
+      }
+      label {
+        display: block;
+        font-size: 12px;
+        color: var(--muted);
+        margin-bottom: 6px;
+      }
+      input {
+        width: 160px;
+        padding: 10px 12px;
+        border-radius: 12px;
+        border: 1px solid var(--border);
+        background: color-mix(in oklab, canvas 92%, canvasText 8%);
+        color: canvasText;
+        outline: none;
+      }
+      input:focus {
+        border-color: color-mix(in oklab, var(--accent) 70%, transparent);
+        box-shadow: 0 0 0 4px color-mix(in oklab, var(--accent) 20%, transparent);
+      }
+      button {
+        padding: 10px 14px;
+        border-radius: 12px;
+        border: 1px solid color-mix(in oklab, var(--accent) 55%, transparent);
+        background: linear-gradient(
+          180deg,
+          color-mix(in oklab, var(--accent) 80%, white 20%),
+          var(--accent)
+        );
+        color: white;
+        font-weight: 650;
+        letter-spacing: 0.01em;
+        cursor: pointer;
+      }
+      button:active {
+        transform: translateY(1px);
+      }
+      .hint {
+        margin-top: 10px;
+        font-size: 12px;
+        color: var(--muted);
+      }
+      code {
+        font-family: ui-monospace, Menlo, Monaco, Consolas, "SF Mono", monospace;
+        font-size: 12px;
+      }
+      a {
+        color: color-mix(in oklab, var(--accent) 85%, canvasText 15%);
+      }
+      .status {
+        margin-top: 10px;
+        font-size: 12px;
+        color: color-mix(in oklab, var(--accent) 70%, canvasText 30%);
+        min-height: 16px;
+      }
+      .status[data-kind='ok'] {
+        color: color-mix(in oklab, #16a34a 75%, canvasText 25%);
+      }
+      .status[data-kind='error'] {
+        color: color-mix(in oklab, #ef4444 75%, canvasText 25%);
+      }
+    </style>
+  </head>
+  <body>
+    <div class="wrap">
+      <header>
+        <div class="logo" aria-hidden="true">
+          <img src="icons/icon128.png" alt="" />
+        </div>
+        <div>
+          <h1>Clawdbot Browser Relay</h1>
+          <p class="subtitle">Click the toolbar button on a tab to attach / detach.</p>
+        </div>
+      </header>
+
+      <div class="grid">
+        <div class="card">
+          <h2>Getting started</h2>
+          <p>
+            If you see a red <code>!</code> badge on the extension icon, the relay server is not reachable.
+            Start Clawdbot’s browser relay on this machine (Gateway or <code>clawdbot browser serve</code>),
+            then click the toolbar button again.
+          </p>
+          <p>
+            Full guide (install, remote Gateway, security): <a href="https://docs.clawd.bot/tools/chrome-extension" target="_blank" rel="noreferrer">docs.clawd.bot/tools/chrome-extension</a>
+          </p>
+        </div>
+
+        <div class="card">
+          <h2>Relay port</h2>
+          <label for="port">Port</label>
+          <div class="row">
+            <input id="port" inputmode="numeric" pattern="[0-9]*" />
+            <button id="save" type="button">Save</button>
+          </div>
+          <div class="hint">
+            Default: <code>18792</code>. Extension connects to: <code id="relay-url">http://127.0.0.1:&lt;port&gt;/</code>.
+            Only change this if your Clawdbot profile uses a different <code>cdpUrl</code> port.
+          </div>
+          <div class="status" id="status"></div>
+        </div>
+      </div>
+
+      <script type="module" src="options.js"></script>
+    </div>
+  </body>
+</html>

assets/chrome-extension/options.js

@@ -0,0 +1,59 @@
+const DEFAULT_PORT = 18792
+
+function clampPort(value) {
+  const n = Number.parseInt(String(value || ''), 10)
+  if (!Number.isFinite(n)) return DEFAULT_PORT
+  if (n <= 0 || n > 65535) return DEFAULT_PORT
+  return n
+}
+
+function updateRelayUrl(port) {
+  const el = document.getElementById('relay-url')
+  if (!el) return
+  el.textContent = `http://127.0.0.1:${port}/`
+}
+
+function setStatus(kind, message) {
+  const status = document.getElementById('status')
+  if (!status) return
+  status.dataset.kind = kind || ''
+  status.textContent = message || ''
+}
+
+async function checkRelayReachable(port) {
+  const url = `http://127.0.0.1:${port}/`
+  const ctrl = new AbortController()
+  const t = setTimeout(() => ctrl.abort(), 900)
+  try {
+    const res = await fetch(url, { method: 'HEAD', signal: ctrl.signal })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    setStatus('ok', `Relay reachable at ${url}`)
+  } catch {
+    setStatus(
+      'error',
+      `Relay not reachable at ${url}. Start Clawdbot’s browser relay on this machine, then click the toolbar button again.`,
+    )
+  } finally {
+    clearTimeout(t)
+  }
+}
+
+async function load() {
+  const stored = await chrome.storage.local.get(['relayPort'])
+  const port = clampPort(stored.relayPort)
+  document.getElementById('port').value = String(port)
+  updateRelayUrl(port)
+  await checkRelayReachable(port)
+}
+
+async function save() {
+  const input = document.getElementById('port')
+  const port = clampPort(input.value)
+  await chrome.storage.local.set({ relayPort: port })
+  input.value = String(port)
+  updateRelayUrl(port)
+  await checkRelayReachable(port)
+}
+
+document.getElementById('save').addEventListener('click', () => void save())
+void load()

docs/channels/discord.md

@@ -191,7 +191,7 @@ Notes:
   - Your config requires mentions and you didn’t mention it, or
   - Your guild/channel allowlist denies the channel/user.
 - **`requireMention: false` but still no replies**:
-  - `channels.discord.groupPolicy` defaults to **allowlist**; set it to `"open"` or explicitly list channels under `channels.discord.guilds.<id>.channels`.
+  - `channels.discord.groupPolicy` defaults to **allowlist**; set it to `"open"` or add a guild entry under `channels.discord.guilds` (optionally list channels under `channels.discord.guilds.<id>.channels` to restrict).
   - `requireMention` must live under `channels.discord.guilds` (or a specific channel). `channels.discord.requireMention` at the top level is ignored.
 - **Permission audits** (`channels status --probe`) only check numeric channel IDs. If you use slugs/names as `channels.discord.guilds.*.channels` keys, the audit can’t verify permissions.
 - **DMs don’t work**: `channels.discord.dm.enabled=false`, `channels.discord.dm.policy="disabled"`, or you haven’t been approved yet (`channels.discord.dm.policy="pairing"`).
@@ -352,6 +352,7 @@ Allowlist matching notes:
 - Prefixes like `discord:`/`user:` (users) and `channel:` (group DMs) are supported.
 - Use `*` to allow any sender/channel.
 - When `guilds.<id>.channels` is present, channels not listed are denied by default.
+- When `guilds.<id>.channels` is omitted, all channels in the allowlisted guild are allowed.
 
 Native command notes:
 - The registered commands mirror Clawdbot’s chat commands.
@@ -362,6 +363,7 @@ The agent can call `discord` with actions like:
 - `react` / `reactions` (add or list reactions)
 - `sticker`, `poll`, `permissions`
 - `readMessages`, `sendMessage`, `editMessage`, `deleteMessage`
+- Read/search/pin tool payloads include normalized `timestampMs` (UTC epoch ms) and `timestampUtc` alongside raw Discord `timestamp`.
 - `threadCreate`, `threadList`, `threadReply`
 - `pinMessage`, `unpinMessage`, `listPins`
 - `searchMessages`, `memberInfo`, `roleInfo`, `roleAdd`, `roleRemove`, `emojiList`

docs/channels/index.md

@@ -17,7 +17,9 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Slack](/channels/slack) — Bolt SDK; workspace apps.
 - [Signal](/channels/signal) — signal-cli; privacy-focused.
 - [iMessage](/channels/imessage) — macOS only; native integration.
-- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support.
+- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately).
+- [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
+- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).
 - [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
 
 ## Notes

docs/channels/matrix.md

@@ -0,0 +1,127 @@
+---
+summary: "Matrix support status, capabilities, and configuration"
+read_when:
+  - Working on Matrix channel features
+---
+# Matrix (plugin)
+
+Status: supported via plugin (matrix-js-sdk). Direct messages, rooms, threads, media, reactions, and polls.
+
+## Plugin required
+Matrix ships as a plugin and is not bundled with the core install.
+
+Install via CLI (npm registry):
+```bash
+clawdbot plugins install @clawdbot/matrix
+```
+
+Local checkout (when running from a git repo):
+```bash
+clawdbot plugins install ./extensions/matrix
+```
+
+If you choose Matrix during configure/onboarding and a git checkout is detected,
+Clawdbot will offer the local install path automatically.
+
+Details: [Plugins](/plugin)
+
+## Quick setup (beginner)
+1) Install the Matrix plugin:
+   - From npm: `clawdbot plugins install @clawdbot/matrix`
+   - From a local checkout: `clawdbot plugins install ./extensions/matrix`
+2) Configure credentials:
+   - Env: `MATRIX_HOMESERVER`, `MATRIX_USER_ID`, `MATRIX_ACCESS_TOKEN` (or `MATRIX_PASSWORD`)
+   - Or config: `channels.matrix.*`
+3) Restart the gateway (or finish onboarding).
+4) DM access defaults to pairing; approve the pairing code on first contact.
+
+Runtime note: Matrix requires Node.js (Bun is not supported).
+
+Minimal config:
+```json5
+{
+  channels: {
+    matrix: {
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      userId: "@clawdbot:example.org",
+      accessToken: "syt_***",
+      dm: { policy: "pairing" }
+    }
+  }
+}
+```
+
+## Encryption (E2EE)
+End-to-end encrypted rooms are **not** supported.
+- Use unencrypted rooms or disable encryption when creating the room.
+- If a room is E2EE, the bot will receive encrypted events and won’t reply.
+
+## What it is
+Matrix is an open messaging protocol. Clawdbot connects as a Matrix user and listens to DMs and rooms.
+- A Matrix user account owned by the Gateway.
+- Deterministic routing: replies go back to Matrix.
+- DMs share the agent's main session; rooms map to group sessions.
+
+## Access control (DMs)
+- Default: `channels.matrix.dm.policy = "pairing"`. Unknown senders get a pairing code.
+- Approve via:
+  - `clawdbot pairing list matrix`
+  - `clawdbot pairing approve matrix <CODE>`
+- Public DMs: `channels.matrix.dm.policy="open"` plus `channels.matrix.dm.allowFrom=["*"]`.
+
+## Rooms (groups)
+- Default: `channels.matrix.groupPolicy = "allowlist"` (mention-gated).
+- Allowlist rooms with `channels.matrix.rooms`:
+```json5
+{
+  channels: {
+    matrix: {
+      rooms: {
+        "!roomId:example.org": { requireMention: true }
+      }
+    }
+  }
+}
+```
+- `requireMention: false` enables auto-reply in that room.
+
+## Threads
+- Reply threading is supported.
+- `channels.matrix.replyToMode` controls replies when tagged:
+  - `off` (default), `first`, `all`
+
+## Capabilities
+| Feature | Status |
+|---------|--------|
+| Direct messages | ✅ Supported |
+| Rooms | ✅ Supported |
+| Threads | ✅ Supported |
+| Media | ✅ Supported |
+| Reactions | ✅ Supported |
+| Polls | ✅ Supported |
+| Native commands | ✅ Supported |
+
+## Configuration reference (Matrix)
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+- `channels.matrix.enabled`: enable/disable channel startup.
+- `channels.matrix.homeserver`: homeserver URL.
+- `channels.matrix.userId`: Matrix user ID.
+- `channels.matrix.accessToken`: access token.
+- `channels.matrix.password`: password for login (token stored).
+- `channels.matrix.deviceName`: device display name.
+- `channels.matrix.initialSyncLimit`: initial sync limit.
+- `channels.matrix.threadReplies`: `off | inbound | always` (default: inbound).
+- `channels.matrix.textChunkLimit`: outbound text chunk size (chars).
+- `channels.matrix.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `channels.matrix.dm.allowFrom`: DM allowlist. `open` requires `"*"`.
+- `channels.matrix.groupPolicy`: `allowlist | open | disabled` (default: allowlist).
+- `channels.matrix.allowlistOnly`: force allowlist rules for DMs + rooms.
+- `channels.matrix.rooms`: per-room settings and allowlist.
+- `channels.matrix.replyToMode`: reply-to mode for threads/tags.
+- `channels.matrix.mediaMaxMb`: inbound/outbound media cap (MB).
+- `channels.matrix.autoJoin`: invite handling (`always | allowlist | off`, default: always).
+- `channels.matrix.autoJoinAllowlist`: allowed room IDs/aliases for auto-join.
+- `channels.matrix.actions`: per-action tool gating (reactions/messages/pins/memberInfo/channelInfo).

docs/channels/msteams.md

@@ -3,20 +3,43 @@ summary: "Microsoft Teams bot support status, capabilities, and configuration"
 read_when:
   - Working on MS Teams channel features
 ---
-# Microsoft Teams (Bot Framework)
+# Microsoft Teams (plugin)
 
 > "Abandon all hope, ye who enter here."
 
 
-Updated: 2026-01-08
+Updated: 2026-01-16
 
 Status: text + DM attachments are supported; channel/group attachments require Microsoft Graph permissions. Polls are sent via Adaptive Cards.
 
+## Plugin required
+Microsoft Teams ships as a plugin and is not bundled with the core install.
+
+**Breaking change (2026.1.15):** MS Teams moved out of core. If you use it, you must install the plugin.
+
+Explainable: keeps core installs lighter and lets MS Teams dependencies update independently.
+
+Install via CLI (npm registry):
+```bash
+clawdbot plugins install @clawdbot/msteams
+```
+
+Local checkout (when running from a git repo):
+```bash
+clawdbot plugins install ./extensions/msteams
+```
+
+If you choose Teams during configure/onboarding and a git checkout is detected,
+Clawdbot will offer the local install path automatically.
+
+Details: [Plugins](/plugin)
+
 ## Quick setup (beginner)
-1) Create an **Azure Bot** (App ID + client secret + tenant ID).
-2) Configure Clawdbot with those credentials.
-3) Expose `/api/messages` (port 3978 by default) via a public URL or tunnel.
-4) Install the Teams app package and start the gateway.
+1) Install the Microsoft Teams plugin.
+2) Create an **Azure Bot** (App ID + client secret + tenant ID).
+3) Configure Clawdbot with those credentials.
+4) Expose `/api/messages` (port 3978 by default) via a public URL or tunnel.
+5) Install the Teams app package and start the gateway.
 
 Minimal config:
 ```json5
@@ -73,11 +96,12 @@ Example:
 ```
 
 ## How it works
-1. Create an **Azure Bot** (App ID + secret + tenant ID).
-2. Build a **Teams app package** that references the bot and includes the RSC permissions below.
-3. Upload/install the Teams app into a team (or personal scope for DMs).
-4. Configure `msteams` in `~/.clawdbot/clawdbot.json` (or env vars) and start the gateway.
-5. The gateway listens for Bot Framework webhook traffic on `/api/messages` by default.
+1. Install the Microsoft Teams plugin.
+2. Create an **Azure Bot** (App ID + secret + tenant ID).
+3. Build a **Teams app package** that references the bot and includes the RSC permissions below.
+4. Upload/install the Teams app into a team (or personal scope for DMs).
+5. Configure `msteams` in `~/.clawdbot/clawdbot.json` (or env vars) and start the gateway.
+6. The gateway listens for Bot Framework webhook traffic on `/api/messages` by default.
 
 ## Azure Bot Setup (Prerequisites)
 
@@ -166,13 +190,17 @@ This is often easier than hand-editing JSON manifests.
 3. Check gateway logs for incoming activity
 
 ## Setup (minimal text-only)
-1. **Bot registration**
+1. **Install the Microsoft Teams plugin**
+   - From npm: `clawdbot plugins install @clawdbot/msteams`
+   - From a local checkout: `clawdbot plugins install ./extensions/msteams`
+
+2. **Bot registration**
    - Create an Azure Bot (see above) and note:
      - App ID
      - Client secret (App password)
      - Tenant ID (single-tenant)
 
-2. **Teams app manifest**
+3. **Teams app manifest**
    - Include a `bot` entry with `botId = <App ID>`.
    - Scopes: `personal`, `team`, `groupChat`.
    - `supportsFiles: true` (required for personal scope file handling).
@@ -180,7 +208,7 @@ This is often easier than hand-editing JSON manifests.
    - Create icons: `outline.png` (32x32) and `color.png` (192x192).
    - Zip all three files together: `manifest.json`, `outline.png`, `color.png`.
 
-3. **Configure Clawdbot**
+4. **Configure Clawdbot**
    ```json
    {
      "msteams": {
@@ -198,12 +226,12 @@ This is often easier than hand-editing JSON manifests.
    - `MSTEAMS_APP_PASSWORD`
    - `MSTEAMS_TENANT_ID`
 
-4. **Bot endpoint**
+5. **Bot endpoint**
    - Set the Azure Bot Messaging Endpoint to:
      - `https://<host>:3978/api/messages` (or your chosen path/port).
 
-5. **Run the gateway**
-   - The Teams channel starts automatically when `msteams` config exists and credentials are set.
+6. **Run the gateway**
+   - The Teams channel starts automatically when the plugin is installed and `msteams` config exists with credentials.
 
 ## History context
 - `channels.msteams.historyLimit` controls how many recent channel/group messages are wrapped into the prompt.

docs/channels/slack.md

@@ -27,17 +27,17 @@ Minimal config:
 1) Create a Slack app (From scratch) in https://api.channels.slack.com/apps.
 2) **Socket Mode** → toggle on. Then go to **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes** with scope `connections:write`. Copy the **App Token** (`xapp-...`).
 3) **OAuth & Permissions** → add bot token scopes (use the manifest below). Click **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
-4) **Event Subscriptions** → enable events and subscribe to:
+4) Optional: **OAuth & Permissions** → add **User Token Scopes** (see the read-only list below). Reinstall the app and copy the **User OAuth Token** (`xoxp-...`).
+5) **Event Subscriptions** → enable events and subscribe to:
    - `message.*` (includes edits/deletes/thread broadcasts)
    - `app_mention`
    - `reaction_added`, `reaction_removed`
    - `member_joined_channel`, `member_left_channel`
-   - `channel_id_changed`
    - `channel_rename`
    - `pin_added`, `pin_removed`
-5) Invite the bot to channels you want it to read.
-6) Slash Commands → create `/clawd` if you use `channels.slack.slashCommand`. If you enable native commands, add one slash command per built-in command (same names as `/help`). Native defaults to off for Slack unless you set `channels.slack.commands.native: true` (global `commands.native` is `"auto"` which leaves Slack off).
-7) App Home → enable the **Messages Tab** so users can DM the bot.
+6) Invite the bot to channels you want it to read.
+7) Slash Commands → create `/clawd` if you use `channels.slack.slashCommand`. If you enable native commands, add one slash command per built-in command (same names as `/help`). Native defaults to off for Slack unless you set `channels.slack.commands.native: true` (global `commands.native` is `"auto"` which leaves Slack off).
+8) App Home → enable the **Messages Tab** so users can DM the bot.
 
 Use the manifest below so scopes and events stay in sync.
 
@@ -63,27 +63,59 @@ Or via config:
 }
 ```
 
-## History context
-- `channels.slack.historyLimit` (or `channels.slack.accounts.*.historyLimit`) controls how many recent channel/group messages are wrapped into the prompt.
-- Falls back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).
-- DM history can be limited with `channels.slack.dmHistoryLimit` (user turns). Per-user overrides: `channels.slack.dms["<user_id>"].historyLimit`.
+## User token (optional)
+Clawdbot can use a Slack user token (`xoxp-...`) for read operations (history,
+pins, reactions, emoji, member info). By default this stays read-only: reads
+prefer the user token when present, and writes still use the bot token unless
+you explicitly opt in. Even with `userTokenReadOnly: false`, the bot token stays
+preferred for writes when it is available.
 
-## Config writes
-By default, Slack is allowed to write config updates triggered by channel events or `/config set|unset`.
+User tokens are configured in the config file (no env var support). For
+multi-account, set `channels.slack.accounts.<id>.userToken`.
 
-This happens when:
-- Slack emits `channel_id_changed` (e.g. Slack Connect channel ID changes). Clawdbot can migrate `channels.slack.channels` automatically.
-- You run `/config set` or `/config unset` in Slack (requires `commands.config: true`).
-
-Disable with:
+Example with bot + app + user tokens:
 ```json5
 {
-  channels: { slack: { configWrites: false } }
+  channels: {
+    slack: {
+      enabled: true,
+      appToken: "xapp-...",
+      botToken: "xoxb-...",
+      userToken: "xoxp-..."
+    }
+  }
 }
 ```
 
+Example with userTokenReadOnly explicitly set (allow user token writes):
+```json5
+{
+  channels: {
+    slack: {
+      enabled: true,
+      appToken: "xapp-...",
+      botToken: "xoxb-...",
+      userToken: "xoxp-...",
+      userTokenReadOnly: false
+    }
+  }
+}
+```
+
+### Token usage
+- Read operations (history, reactions list, pins list, emoji list, member info,
+  search) prefer the user token when configured, otherwise the bot token.
+- Write operations (send/edit/delete messages, add/remove reactions, pin/unpin,
+  file uploads) use the bot token by default. If `userTokenReadOnly: false` and
+  no bot token is available, Clawdbot falls back to the user token.
+
+## History context
+- `channels.slack.historyLimit` (or `channels.slack.accounts.*.historyLimit`) controls how many recent channel/group messages are wrapped into the prompt.
+- Falls back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).
+
 ## Manifest (optional)
-Use this Slack app manifest to create the app quickly (adjust the name/command if you want).
+Use this Slack app manifest to create the app quickly (adjust the name/command if you want). Include the
+user scopes if you plan to configure a user token.
 
 ```json
 {
@@ -133,6 +165,21 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i
         "commands",
         "files:read",
         "files:write"
+      ],
+      "user": [
+        "channels:history",
+        "channels:read",
+        "groups:history",
+        "groups:read",
+        "im:history",
+        "im:read",
+        "mpim:history",
+        "mpim:read",
+        "users:read",
+        "reactions:read",
+        "pins:read",
+        "emoji:read",
+        "search:read"
       ]
     }
   },
@@ -149,7 +196,6 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i
         "reaction_removed",
         "member_joined_channel",
         "member_left_channel",
-        "channel_id_changed",
         "channel_rename",
         "pin_added",
         "pin_removed"
@@ -166,7 +212,7 @@ Slack's Conversations API is type-scoped: you only need the scopes for the
 conversation types you actually touch (channels, groups, im, mpim). See
 https://api.channels.slack.com/docs/conversations-api for the overview.
 
-### Required scopes
+### Bot token scopes (required)
 - `chat:write` (send/update/delete messages via `chat.postMessage`)
   https://api.channels.slack.com/methods/chat.postMessage
 - `im:write` (open DMs via `conversations.open` for user DMs)
@@ -188,6 +234,17 @@ https://api.channels.slack.com/docs/conversations-api for the overview.
 - `files:write` (uploads via `files.uploadV2`)
   https://api.channels.slack.com/messaging/files/uploading
 
+### User token scopes (optional, read-only by default)
+Add these under **User Token Scopes** if you configure `channels.slack.userToken`.
+
+- `channels:history`, `groups:history`, `im:history`, `mpim:history`
+- `channels:read`, `groups:read`, `im:read`, `mpim:read`
+- `users:read`
+- `reactions:read`
+- `pins:read`
+- `emoji:read`
+- `search:read`
+
 ### Not needed today (but likely future)
 - `mpim:write` (only if we add group-DM open/DM start via `conversations.open`)
 - `groups:write` (only if we add private-channel management: create/rename/invite/archive)
@@ -315,6 +372,17 @@ Slack tool actions can be gated with `channels.slack.actions.*`:
 | memberInfo | enabled | Member info |
 | emojiList | enabled | Custom emoji list |
 
+## Security notes
+- Writes default to the bot token so state-changing actions stay scoped to the
+  app's bot permissions and identity.
+- Setting `userTokenReadOnly: false` allows the user token to be used for write
+  operations when a bot token is unavailable, which means actions run with the
+  installing user's access. Treat the user token as highly privileged and keep
+  action gates and allowlists tight.
+- If you enable user-token writes, make sure the user token includes the write
+  scopes you expect (`chat:write`, `reactions:write`, `pins:write`,
+  `files:write`) or those operations will fail.
+
 ## Notes
 - Mention gating is controlled via `channels.slack.channels` (set `requireMention` to `true`); `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions.
 - Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.

docs/channels/telegram.md

@@ -93,6 +93,7 @@ group messages, so use admin if you need full visibility.
 - Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
 - Replies always route back to the same Telegram chat.
 - Long-polling uses grammY runner with per-chat sequencing; overall concurrency is capped by `agents.defaults.maxConcurrent`.
+- Telegram Bot API does not support read receipts; there is no `sendReadReceipts` option.
 
 ## Formatting (Telegram HTML)
 - Outbound Telegram text uses `parse_mode: "HTML"` (Telegram’s supported tag subset).
@@ -167,7 +168,7 @@ Forward any message from the group to `@userinfobot` or `@getidsbot` on Telegram
 
 **Tip:** For your own user ID, DM the bot and it will reply with your user ID (pairing message), or use `/whoami` once commands are enabled.
 
-**Privacy note:** `@userinfobot` is a third-party bot. If you prefer, use gateway logs (`clawdbot logs`) or Telegram developer tools to find user/chat IDs.
+**Privacy note:** `@userinfobot` is a third-party bot. If you prefer, add the bot to the group, send a message, and use `clawdbot logs --follow` to read `chat.id`, or use the Bot API `getUpdates`.
 
 ## Config writes
 By default, Telegram is allowed to write config updates triggered by channel events or `/config set|unset`.
@@ -187,11 +188,74 @@ Disable with:
 Telegram forum topics include a `message_thread_id` per message. Clawdbot:
 - Appends `:topic:<threadId>` to the Telegram group session key so each topic is isolated.
 - Sends typing indicators and replies with `message_thread_id` so responses stay in the topic.
+- General topic (thread id `1`) is special: message sends omit `message_thread_id` (Telegram rejects it), but typing indicators still include it.
 - Exposes `MessageThreadId` + `IsForum` in template context for routing/templating.
 - Topic-specific configuration is available under `channels.telegram.groups.<chatId>.topics.<threadId>` (skills, allowlists, auto-reply, system prompts, disable).
 
 Private chats can include `message_thread_id` in some edge cases. Clawdbot keeps the DM session key unchanged, but still uses the thread id for replies/draft streaming when it is present.
 
+## Inline Buttons
+
+Telegram supports inline keyboards with callback buttons. Enable this feature via capabilities:
+
+```json5
+{
+  "channels": {
+    "telegram": {
+      "capabilities": ["inlineButtons"]
+    }
+  }
+}
+```
+
+For per-account configuration:
+```json5
+{
+  "channels": {
+    "telegram": {
+      "accounts": {
+        "main": {
+          "capabilities": ["inlineButtons"]
+        }
+      }
+    }
+  }
+}
+```
+
+### Sending buttons
+
+Use the message tool with the `buttons` parameter:
+
+```json5
+{
+  "action": "send",
+  "channel": "telegram",
+  "to": "123456789",
+  "message": "Choose an option:",
+  "buttons": [
+    [
+      {"text": "Yes", "callback_data": "yes"},
+      {"text": "No", "callback_data": "no"}
+    ],
+    [
+      {"text": "Cancel", "callback_data": "cancel"}
+    ]
+  ]
+}
+```
+
+When a user clicks a button, the callback data is sent back to the agent as a message with the format:
+`callback_data: value`
+
+### Configuration options
+
+Telegram capabilities can be configured at two levels:
+
+- `channels.telegram.capabilities`: Global default capability list applied to all Telegram accounts unless overridden.
+- `channels.telegram.accounts.<account>.capabilities`: Per-account capabilities that override or extend the global defaults for that specific account.
+
+Use the global setting when all Telegram bots/accounts should behave the same. Use per-account configuration when different bots need different behaviors (for example, one account only handles DMs while another is allowed in groups or has extra capabilities).
 ## Access control (DMs + groups)
 
 ### DM access
@@ -200,7 +264,22 @@ Private chats can include `message_thread_id` in some edge cases. Clawdbot keeps
   - `clawdbot pairing list telegram`
   - `clawdbot pairing approve telegram <CODE>`
 - Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/start/pairing)
-- `channels.telegram.allowFrom` accepts numeric user IDs (recommended) or `@username` entries. It is **not** the bot username; use the human sender’s ID (get it from `@userinfobot` or the `from.id` field in the gateway log).
+- `channels.telegram.allowFrom` accepts numeric user IDs (recommended) or `@username` entries. It is **not** the bot username; use the human sender’s ID.
+
+#### Finding your Telegram user ID
+Safer (no third-party bot):
+1) Start the gateway and DM your bot.
+2) Run `clawdbot logs --follow` and look for `from.id`.
+
+Alternate (official Bot API):
+1) DM your bot.
+2) Fetch updates with your bot token and read `message.from.id`:
+   ```bash
+   curl "https://api.telegram.org/bot<bot_token>/getUpdates"
+   ```
+
+Third-party (less private):
+- DM `@userinfobot` or `@getidsbot` and use the returned user id.
 
 ### Group access
 
@@ -281,6 +360,49 @@ Outbound Telegram API calls retry on transient network/429 errors with exponenti
 - Reaction removal semantics: see [/tools/reactions](/tools/reactions).
 - Tool gating: `channels.telegram.actions.reactions`, `channels.telegram.actions.sendMessage`, `channels.telegram.actions.deleteMessage` (default: enabled).
 
+## Reaction notifications
+
+**How reactions work:**
+Telegram reactions arrive as **separate `message_reaction` events**, not as properties in message payloads. When a user adds a reaction, Clawdbot:
+
+1. Receives the `message_reaction` update from Telegram API
+2. Converts it to a **system event** with format: `"Telegram reaction added: {emoji} by {user} on msg {id}"`
+3. Enqueues the system event using the **same session key** as regular messages
+4. When the next message arrives in that conversation, system events are drained and prepended to the agent's context
+
+The agent sees reactions as **system notifications** in the conversation history, not as message metadata.
+
+**Configuration:**
+- `channels.telegram.reactionNotifications`: Controls which reactions trigger notifications
+  - `"off"` — ignore all reactions (default when not set)
+  - `"own"` — notify when users react to bot messages (best-effort; in-memory)
+  - `"all"` — notify for all reactions
+
+- `channels.telegram.reactionLevel`: Controls agent's reaction capability
+  - `"off"` — agent cannot react to messages
+  - `"ack"` — bot sends acknowledgment reactions (👀 while processing) (default)
+  - `"minimal"` — agent can react sparingly (guideline: 1 per 5-10 exchanges)
+  - `"extensive"` — agent can react liberally when appropriate
+
+**Forum groups:** Reactions in forum groups include `message_thread_id` and use session keys like `agent:main:telegram:group:{chatId}:topic:{threadId}`. This ensures reactions and messages in the same topic stay together.
+
+**Example config:**
+```json5
+{
+  channels: {
+    telegram: {
+      reactionNotifications: "all",  // See all reactions
+      reactionLevel: "minimal"        // Agent can react sparingly
+    }
+  }
+}
+```
+
+**Requirements:**
+- Telegram bots must explicitly request `message_reaction` in `allowed_updates` (configured automatically by Clawdbot)
+- For webhook mode, reactions are included in the webhook `allowed_updates`
+- For polling mode, reactions are included in the `getUpdates` `allowed_updates`
+
 ## Delivery targets (CLI/cron)
 - Use a chat id (`123456789`) or a username (`@name`) as the target.
 - Example: `clawdbot message send --channel telegram --to 123456789 --message "hi"`.
@@ -308,6 +430,11 @@ Outbound Telegram API calls retry on transient network/429 errors with exponenti
 - Make sure your Telegram user ID is authorized (via pairing or `channels.telegram.allowFrom`)
 - Commands require authorization even in groups with `groupPolicy: "open"`
 
+**Bot starts, then silently stops responding (or logs `HttpError: Network request ... failed`):**
+- Some hosts resolve `api.telegram.org` to IPv6 first. If your server does not have working IPv6 egress, grammY can get stuck on IPv6-only requests.
+- Fix by enabling IPv6 egress **or** forcing IPv4 resolution for `api.telegram.org` (for example, add an `/etc/hosts` entry using the IPv4 A record, or prefer IPv4 in your OS DNS stack), then restart the gateway.
+- Quick check: `dig +short api.telegram.org A` and `dig +short api.telegram.org AAAA` to confirm what DNS returns.
+
 ## Configuration reference (Telegram)
 Full configuration: [Configuration](/gateway/configuration)
 
@@ -327,6 +454,8 @@ Provider options:
   - `channels.telegram.groups.<id>.enabled`: disable the group when `false`.
   - `channels.telegram.groups.<id>.topics.<threadId>.*`: per-topic overrides (same fields as group).
   - `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: per-topic mention gating override.
+- `channels.telegram.capabilities`: Enable channel features (e.g., "inlineButtons").
+- `channels.telegram.accounts.<account>.capabilities`: Per-account capabilities.
 - `channels.telegram.replyToMode`: `off | first | all` (default: `first`).
 - `channels.telegram.textChunkLimit`: outbound chunk size (chars).
 - `channels.telegram.streamMode`: `off | partial | block` (draft streaming).
@@ -339,6 +468,8 @@ Provider options:
 - `channels.telegram.actions.reactions`: gate Telegram tool reactions.
 - `channels.telegram.actions.sendMessage`: gate Telegram tool message sends.
 - `channels.telegram.actions.deleteMessage`: gate Telegram tool message deletes.
+- `channels.telegram.reactionNotifications`: `off | own | all` — control which reactions trigger system events (default: `off` when not set).
+- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — control agent's reaction capability (default: `ack` when not set).
 
 Related global options:
 - `agents.list[].groupChat.mentionPatterns` (mention gating patterns).

docs/channels/troubleshooting.md

@@ -19,3 +19,6 @@ clawdbot channels status --probe
 - Discord: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
 - Telegram: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
 - WhatsApp: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
+
+## Telegram quick fixes
+- Logs show `HttpError: Network request for 'sendMessage' failed` or `sendChatAction` → check IPv6 DNS. If `api.telegram.org` resolves to IPv6 first and the host lacks IPv6 egress, force IPv4 or enable IPv6. See [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting).

docs/channels/whatsapp.md

@@ -138,6 +138,32 @@ Behavior:
 - Self-chat mode (allowFrom includes your number) avoids auto read receipts and ignores mention JIDs.
 - Read receipts sent for non-self-chat DMs.
 
+## Read receipts
+By default, the gateway marks inbound WhatsApp messages as read (blue ticks) once they are accepted.
+
+Disable globally:
+```json5
+{
+  channels: { whatsapp: { sendReadReceipts: false } }
+}
+```
+
+Disable per account:
+```json5
+{
+  channels: {
+    whatsapp: {
+      accounts: {
+        personal: { sendReadReceipts: false }
+      }
+    }
+  }
+}
+```
+
+Notes:
+- Self-chat mode always skips read receipts.
+
 ## WhatsApp FAQ: sending messages + pairing
 
 **Will Clawdbot message random contacts when I link WhatsApp?**  
@@ -270,8 +296,9 @@ WhatsApp can automatically send emoji reactions to incoming messages immediately
 
 ## Heartbeats
 - **Gateway heartbeat** logs connection health (`web.heartbeatSeconds`, default 60s).
-- **Agent heartbeat** is global (`agents.defaults.heartbeat.*`) and runs in the main session.
-  - Uses the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`) + `HEARTBEAT_OK` skip behavior.
+- **Agent heartbeat** can be configured per agent (`agents.list[].heartbeat`) or globally
+  via `agents.defaults.heartbeat` (fallback when no per-agent entries are set).
+  - Uses the configured heartbeat prompt (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`) + `HEARTBEAT_OK` skip behavior.
   - Delivery defaults to the last used channel (or configured target).
 
 ## Reconnect behavior
@@ -304,6 +331,7 @@ WhatsApp can automatically send emoji reactions to incoming messages immediately
 - `agents.defaults.heartbeat.model` (optional override)
 - `agents.defaults.heartbeat.target`
 - `agents.defaults.heartbeat.to`
+- `agents.list[].heartbeat.*` (per-agent overrides)
 - `session.*` (scope, idle, store, mainKey)
 - `web.enabled` (disable channel startup when false)
 - `web.heartbeatSeconds`

docs/channels/zalo.md

@@ -0,0 +1,167 @@
+---
+summary: "Zalo bot support status, capabilities, and configuration"
+read_when:
+  - Working on Zalo features or webhooks
+---
+# Zalo (Bot API)
+
+Status: experimental. Direct messages only; groups coming soon per Zalo docs.
+
+## Plugin required
+Zalo ships as a plugin and is not bundled with the core install.
+- Install via CLI: `clawdbot plugins install @clawdbot/zalo`
+- Or select **Zalo** during onboarding and confirm the install prompt
+- Details: [Plugins](/plugin)
+
+## Quick setup (beginner)
+1) Install the Zalo plugin:
+   - From a source checkout: `clawdbot plugins install ./extensions/zalo`
+   - From npm (if published): `clawdbot plugins install @clawdbot/zalo`
+   - Or pick **Zalo** in onboarding and confirm the install prompt
+2) Set the token:
+   - Env: `ZALO_BOT_TOKEN=...`
+   - Or config: `channels.zalo.botToken: "..."`.
+3) Restart the gateway (or finish onboarding).
+4) DM access is pairing by default; approve the pairing code on first contact.
+
+Minimal config:
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      botToken: "12345689:abc-xyz",
+      dmPolicy: "pairing"
+    }
+  }
+}
+```
+
+## What it is
+Zalo is a Vietnam-focused messaging app; its Bot API lets the Gateway run a bot for 1:1 conversations.
+It is a good fit for support or notifications where you want deterministic routing back to Zalo.
+- A Zalo Bot API channel owned by the Gateway.
+- Deterministic routing: replies go back to Zalo; the model never chooses channels.
+- DMs share the agent's main session.
+- Groups are not yet supported (Zalo docs state "coming soon").
+
+## Setup (fast path)
+
+### 1) Create a bot token (Zalo Bot Platform)
+1) Go to **https://bot.zaloplatforms.com** and sign in.
+2) Create a new bot and configure its settings.
+3) Copy the bot token (format: `12345689:abc-xyz`).
+
+### 2) Configure the token (env or config)
+Example:
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      botToken: "12345689:abc-xyz",
+      dmPolicy: "pairing"
+    }
+  }
+}
+```
+
+Env option: `ZALO_BOT_TOKEN=...` (works for the default account only).
+
+Multi-account support: use `channels.zalo.accounts` with per-account tokens and optional `name`.
+
+3) Restart the gateway. Zalo starts when a token is resolved (env or config).
+4) DM access defaults to pairing. Approve the code when the bot is first contacted.
+
+## How it works (behavior)
+- Inbound messages are normalized into the shared channel envelope with media placeholders.
+- Replies always route back to the same Zalo chat.
+- Long-polling by default; webhook mode available with `channels.zalo.webhookUrl`.
+
+## Limits
+- Outbound text is chunked to 2000 characters (Zalo API limit).
+- Media downloads/uploads are capped by `channels.zalo.mediaMaxMb` (default 5).
+- Streaming is blocked by default due to the 2000 char limit making streaming less useful.
+
+## Access control (DMs)
+
+### DM access
+- Default: `channels.zalo.dmPolicy = "pairing"`. Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `clawdbot pairing list zalo`
+  - `clawdbot pairing approve zalo <CODE>`
+- Pairing is the default token exchange. Details: [Pairing](/start/pairing)
+- `channels.zalo.allowFrom` accepts numeric user IDs.
+
+## Long-polling vs webhook
+- Default: long-polling (no public URL required).
+- Webhook mode: set `channels.zalo.webhookUrl` and `channels.zalo.webhookSecret`.
+  - The webhook secret must be 8-256 characters.
+  - Webhook URL must use HTTPS.
+  - Zalo sends events with `X-Bot-Api-Secret-Token` header for verification.
+  - Gateway HTTP handles webhook requests at `channels.zalo.webhookPath` (defaults to the webhook URL path).
+
+**Note:** getUpdates (polling) and webhook are mutually exclusive per Zalo API docs.
+
+## Supported message types
+- **Text messages**: Full support with 2000 character chunking.
+- **Image messages**: Download and process inbound images; send images via `sendPhoto`.
+- **Stickers**: Logged but not fully processed (no agent response).
+- **Unsupported types**: Logged (e.g., messages from protected users).
+
+## Capabilities
+| Feature | Status |
+|---------|--------|
+| Direct messages | ✅ Supported |
+| Groups | ❌ Coming soon (per Zalo docs) |
+| Media (images) | ✅ Supported |
+| Reactions | ❌ Not supported |
+| Threads | ❌ Not supported |
+| Polls | ❌ Not supported |
+| Native commands | ❌ Not supported |
+| Streaming | ⚠️ Blocked (2000 char limit) |
+
+## Delivery targets (CLI/cron)
+- Use a chat id as the target.
+- Example: `clawdbot message send --channel zalo --to 123456789 --message "hi"`.
+
+## Troubleshooting
+
+**Bot doesn't respond:**
+- Check that the token is valid: `clawdbot channels status --probe`
+- Verify the sender is approved (pairing or allowFrom)
+- Check gateway logs: `clawdbot logs --follow`
+
+**Webhook not receiving events:**
+- Ensure webhook URL uses HTTPS
+- Verify secret token is 8-256 characters
+- Confirm the gateway HTTP endpoint is reachable on the configured path
+- Check that getUpdates polling is not running (they're mutually exclusive)
+
+## Configuration reference (Zalo)
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+- `channels.zalo.enabled`: enable/disable channel startup.
+- `channels.zalo.botToken`: bot token from Zalo Bot Platform.
+- `channels.zalo.tokenFile`: read token from file path.
+- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `channels.zalo.allowFrom`: DM allowlist (user IDs). `open` requires `"*"`.
+- `channels.zalo.mediaMaxMb`: inbound/outbound media cap (MB, default 5).
+- `channels.zalo.webhookUrl`: enable webhook mode (HTTPS required).
+- `channels.zalo.webhookSecret`: webhook secret (8-256 chars).
+- `channels.zalo.webhookPath`: webhook path on the gateway HTTP server.
+- `channels.zalo.proxy`: proxy URL for API requests.
+
+Multi-account options:
+- `channels.zalo.accounts.<id>.botToken`: per-account token.
+- `channels.zalo.accounts.<id>.tokenFile`: per-account token file.
+- `channels.zalo.accounts.<id>.name`: display name.
+- `channels.zalo.accounts.<id>.enabled`: enable/disable account.
+- `channels.zalo.accounts.<id>.dmPolicy`: per-account DM policy.
+- `channels.zalo.accounts.<id>.allowFrom`: per-account allowlist.
+- `channels.zalo.accounts.<id>.webhookUrl`: per-account webhook URL.
+- `channels.zalo.accounts.<id>.webhookSecret`: per-account webhook secret.
+- `channels.zalo.accounts.<id>.webhookPath`: per-account webhook path.
+- `channels.zalo.accounts.<id>.proxy`: per-account proxy URL.

docs/cli/agent.md

@@ -0,0 +1,20 @@
+---
+summary: "CLI reference for `clawdbot agent` (send one agent turn via the Gateway)"
+read_when:
+  - You want to run one agent turn from scripts (optionally deliver reply)
+---
+
+# `clawdbot agent`
+
+Run an agent turn via the Gateway (use `--local` for embedded).
+
+Related:
+- Agent send tool: [Agent send](/tools/agent-send)
+
+## Examples
+
+```bash
+clawdbot agent --to +15555550123 --message "status update" --deliver
+clawdbot agent --session-id 1234 --message "Summarize inbox" --thinking medium
+```
+

docs/cli/agents.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot agents` (list/add/delete isolated agents)"
+read_when:
+  - You want multiple isolated agents (workspaces + routing + auth)
+---
+
+# `clawdbot agents`
+
+Manage isolated agents (workspaces + auth + routing).
+
+Related:
+- Multi-agent routing: [Multi-Agent Routing](/concepts/multi-agent)
+- Agent workspace: [Agent workspace](/concepts/agent-workspace)
+
+## Examples
+
+```bash
+clawdbot agents list
+clawdbot agents add work --workspace ~/clawd-work
+clawdbot agents delete work
+```
+

docs/cli/browser.md

@@ -0,0 +1,106 @@
+---
+summary: "CLI reference for `clawdbot browser` (profiles, tabs, actions, extension relay, remote serve)"
+read_when:
+  - You use `clawdbot browser` and want examples for common tasks
+  - You want to control a remote browser via `browser.controlUrl`
+  - You want to use the Chrome extension relay (attach/detach via toolbar button)
+---
+
+# `clawdbot browser`
+
+Manage Clawdbot’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks, typing).
+
+Related:
+- Browser tool + API: [Browser tool](/tools/browser)
+- Chrome extension relay: [Chrome extension](/tools/chrome-extension)
+
+## Common flags
+
+- `--url <controlUrl>`: override `browser.controlUrl` for this command invocation.
+- `--browser-profile <name>`: choose a browser profile (default comes from config).
+- `--json`: machine-readable output (where supported).
+
+## Quick start (local)
+
+```bash
+clawdbot browser --browser-profile chrome tabs
+clawdbot browser --browser-profile clawd start
+clawdbot browser --browser-profile clawd open https://example.com
+clawdbot browser --browser-profile clawd snapshot
+```
+
+## Profiles
+
+Profiles are named browser routing configs. In practice:
+- `clawd`: launches/attaches to a dedicated Clawdbot-managed Chrome instance (isolated user data dir).
+- `chrome`: controls your existing Chrome tab(s) via the Chrome extension relay.
+
+```bash
+clawdbot browser profiles
+clawdbot browser create-profile --name work --color "#FF5A36"
+clawdbot browser delete-profile --name work
+```
+
+Use a specific profile:
+
+```bash
+clawdbot browser --browser-profile work tabs
+```
+
+## Tabs
+
+```bash
+clawdbot browser tabs
+clawdbot browser open https://docs.clawd.bot
+clawdbot browser focus <targetId>
+clawdbot browser close <targetId>
+```
+
+## Snapshot / screenshot / actions
+
+Snapshot:
+
+```bash
+clawdbot browser snapshot
+```
+
+Screenshot:
+
+```bash
+clawdbot browser screenshot
+```
+
+Navigate/click/type (ref-based UI automation):
+
+```bash
+clawdbot browser navigate https://example.com
+clawdbot browser click <ref>
+clawdbot browser type <ref> "hello"
+```
+
+## Chrome extension relay (attach via toolbar button)
+
+This mode lets the agent control an existing Chrome tab that you attach manually (it does not auto-attach).
+
+Install the unpacked extension to a stable path:
+
+```bash
+clawdbot browser extension install
+clawdbot browser extension path
+```
+
+Then Chrome → `chrome://extensions` → enable “Developer mode” → “Load unpacked” → select the printed folder.
+
+Full guide: [Chrome extension](/tools/chrome-extension)
+
+## Remote browser control (`clawdbot browser serve`)
+
+If the Gateway runs on a different machine than the browser, run a standalone browser control server on the machine that runs Chrome:
+
+```bash
+clawdbot browser serve --bind 127.0.0.1 --port 18791 --token <token>
+```
+
+Then point the Gateway at it using `browser.controlUrl` + `browser.controlToken` (or `CLAWDBOT_BROWSER_CONTROL_TOKEN`).
+
+Security + TLS best-practices: [Browser tool](/tools/browser), [Tailscale](/gateway/tailscale), [Security](/gateway/security)

docs/cli/channels.md

@@ -0,0 +1,44 @@
+---
+summary: "CLI reference for `clawdbot channels` (accounts, status, login/logout, logs)"
+read_when:
+  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage)
+  - You want to check channel status or tail channel logs
+---
+
+# `clawdbot channels`
+
+Manage chat channel accounts and their runtime status on the Gateway.
+
+Related docs:
+- Channel guides: [Channels](/channels/index)
+- Gateway configuration: [Configuration](/gateway/configuration)
+
+## Common commands
+
+```bash
+clawdbot channels list
+clawdbot channels status
+clawdbot channels logs --channel all
+```
+
+## Add / remove accounts
+
+```bash
+clawdbot channels add --channel telegram --token <bot-token>
+clawdbot channels remove --channel telegram --delete
+```
+
+Tip: `clawdbot channels add --help` shows per-channel flags (token, app token, signal-cli paths, etc).
+
+## Login / logout (interactive)
+
+```bash
+clawdbot channels login --channel whatsapp
+clawdbot channels logout --channel whatsapp
+```
+
+## Troubleshooting
+
+- Run `clawdbot status --deep` for a broad probe.
+- Use `clawdbot doctor` for guided fixes.
+

docs/cli/configure.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot configure` / `clawdbot config` (interactive configuration prompts)"
+read_when:
+  - You want to tweak credentials, devices, or agent defaults interactively
+---
+
+# `clawdbot configure` (alias: `config`)
+
+Interactive prompt to set up credentials, devices, and agent defaults.
+
+Related:
+- Gateway configuration reference: [Configuration](/gateway/configuration)
+
+Notes:
+- Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if that is all you need.
+
+## Examples
+
+```bash
+clawdbot configure
+clawdbot configure --section models --section channels
+```

docs/cli/cron.md

@@ -0,0 +1,16 @@
+---
+summary: "CLI reference for `clawdbot cron` (schedule and run background jobs)"
+read_when:
+  - You want scheduled jobs and wakeups
+  - You’re debugging cron execution and logs
+---
+
+# `clawdbot cron`
+
+Manage cron jobs for the Gateway scheduler.
+
+Related:
+- Cron jobs: [Cron jobs](/automation/cron-jobs)
+
+Tip: run `clawdbot cron --help` for the full command surface.
+

docs/cli/daemon.md

@@ -0,0 +1,17 @@
+---
+summary: "CLI reference for `clawdbot daemon` (install/uninstall/status for the Gateway service)"
+read_when:
+  - You want to run the Gateway as a background service
+  - You’re debugging daemon install, status, or logs
+---
+
+# `clawdbot daemon`
+
+Manage the Gateway daemon (background service).
+
+Related:
+- Gateway CLI: [Gateway](/cli/gateway)
+- macOS platform notes: [macOS](/platforms/macos)
+
+Tip: run `clawdbot daemon --help` for platform-specific flags.
+

docs/cli/dashboard.md

@@ -0,0 +1,16 @@
+---
+summary: "CLI reference for `clawdbot dashboard` (open the Control UI)"
+read_when:
+  - You want to open the Control UI with your current token
+  - You want to print the URL without launching a browser
+---
+
+# `clawdbot dashboard`
+
+Open the Control UI using your current auth.
+
+```bash
+clawdbot dashboard
+clawdbot dashboard --no-open
+```
+

docs/cli/dns.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot dns` (wide-area discovery helpers)"
+read_when:
+  - You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
+  - You’re setting up split DNS for clawdbot.internal
+---
+
+# `clawdbot dns`
+
+DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
+
+Related:
+- Gateway discovery: [Discovery](/gateway/discovery)
+- Wide-area discovery config: [Configuration](/gateway/configuration)
+
+## Setup
+
+```bash
+clawdbot dns setup
+clawdbot dns setup --apply
+```
+

docs/cli/docs.md

@@ -0,0 +1,15 @@
+---
+summary: "CLI reference for `clawdbot docs` (search the live docs index)"
+read_when:
+  - You want to search the live Clawdbot docs from the terminal
+---
+
+# `clawdbot docs`
+
+Search the live docs index.
+
+```bash
+clawdbot docs browser extension
+clawdbot docs sandbox allowHostControl
+```
+

docs/cli/doctor.md

@@ -0,0 +1,23 @@
+---
+summary: "CLI reference for `clawdbot doctor` (health checks + guided repairs)"
+read_when:
+  - You have connectivity/auth issues and want guided fixes
+  - You updated and want a sanity check
+---
+
+# `clawdbot doctor`
+
+Health checks + quick fixes for the gateway and channels.
+
+Related:
+- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
+- Security audit: [Security](/gateway/security)
+
+## Examples
+
+```bash
+clawdbot doctor
+clawdbot doctor --repair
+clawdbot doctor --deep
+```
+

docs/cli/gateway.md

@@ -78,7 +78,7 @@ clawdbot gateway health --url ws://127.0.0.1:18789
 - your configured remote gateway (if set), and
 - localhost (loopback) **even if remote is configured**.
 
-If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use profiles for redundancy, but most installs still run a single gateway.
+If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.
 
 ```bash
 clawdbot gateway status

docs/cli/health.md

@@ -0,0 +1,15 @@
+---
+summary: "CLI reference for `clawdbot health` (gateway health endpoint via RPC)"
+read_when:
+  - You want to quickly check the running Gateway’s health
+---
+
+# `clawdbot health`
+
+Fetch health from the running Gateway.
+
+```bash
+clawdbot health
+clawdbot health --json
+```
+

docs/cli/hooks.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot hooks` (Gmail Pub/Sub + webhook helpers)"
+read_when:
+  - You want to wire Gmail Pub/Sub events into Clawdbot hooks
+  - You want to run the gog watch service and renew loop
+---
+
+# `clawdbot hooks`
+
+Webhook helpers and hook-based integrations.
+
+Related:
+- Webhooks: [Webhook](/automation/webhook)
+- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/gmail-pubsub)
+
+## Gmail
+
+```bash
+clawdbot hooks gmail setup --account you@example.com
+clawdbot hooks gmail run
+```
+