fix: load CLI plugin registry for channel-aware commands (#1338) (thanks @MaudeBot)

Fixes #1327 - 'clawdbot message --channel telegram' fails with
'Unknown channel: telegram' because plugins weren't loaded.

The Commander code path (non-route-first) calls ensureConfigReady() in
preAction but doesn't load the plugin registry. Channel plugins like
telegram are registered during plugin loading, so getChannelPlugin()
returns undefined without it.

This adds ensurePluginRegistryLoaded() call for commands that need
channel plugin access: message, channels, directory.

.gitignore

@@ -66,3 +66,6 @@ apps/ios/*.mobileprovision
 IDENTITY.md
 USER.md
 .tgz
+
+# local tooling
+.serena/

.serena/.gitignore

@@ -1 +0,0 @@
-/cache

.serena/project.yml

@@ -1,87 +0,0 @@
-# list of languages for which language servers are started; choose from:
-#   al               bash             clojure          cpp              csharp           csharp_omnisharp
-#   dart             elixir           elm              erlang           fortran          fsharp
-#   go               groovy           haskell          java             julia            kotlin
-#   lua              markdown         nix              pascal           perl             php
-#   powershell       python           python_jedi      r                rego             ruby
-#   ruby_solargraph  rust             scala            swift            terraform        toml
-#   typescript       typescript_vts   yaml             zig
-# Note:
-#   - For C, use cpp
-#   - For JavaScript, use typescript
-#   - For Free Pascal / Lazarus, use pascal
-# Special requirements:
-#   - csharp: Requires the presence of a .sln file in the project folder.
-#   - pascal: Requires Free Pascal Compiler (fpc) and optionally Lazarus.
-# When using multiple languages, the first language server that supports a given file will be used for that file.
-# The first language is the default language and the respective language server will be used as a fallback.
-# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
-languages:
-- typescript
-
-# the encoding used by text files in the project
-# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
-encoding: "utf-8"
-
-# whether to use the project's gitignore file to ignore files
-# Added on 2025-04-07
-ignore_all_files_in_gitignore: true
-
-# list of additional paths to ignore
-# same syntax as gitignore, so you can use * and **
-# Was previously called `ignored_dirs`, please update your config if you are using that.
-# Added (renamed) on 2025-04-07
-ignored_paths: []
-
-# whether the project is in read-only mode
-# If set to true, all editing tools will be disabled and attempts to use them will result in an error
-# Added on 2025-04-18
-read_only: false
-
-# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
-# Below is the complete list of tools for convenience.
-# To make sure you have the latest list of tools, and to view their descriptions, 
-# execute `uv run scripts/print_tool_overview.py`.
-#
-#  * `activate_project`: Activates a project by name.
-#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
-#  * `create_text_file`: Creates/overwrites a file in the project directory.
-#  * `delete_lines`: Deletes a range of lines within a file.
-#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
-#  * `execute_shell_command`: Executes a shell command.
-#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
-#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
-#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
-#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
-#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
-#  * `initial_instructions`: Gets the initial instructions for the current project.
-#     Should only be used in settings where the system prompt cannot be set,
-#     e.g. in clients you have no control over, like Claude Desktop.
-#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
-#  * `insert_at_line`: Inserts content at a given line in a file.
-#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
-#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
-#  * `list_memories`: Lists memories in Serena's project-specific memory store.
-#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
-#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
-#  * `read_file`: Reads a file within the project directory.
-#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
-#  * `remove_project`: Removes a project from the Serena configuration.
-#  * `replace_lines`: Replaces a range of lines within a file with new content.
-#  * `replace_symbol_body`: Replaces the full definition of a symbol.
-#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
-#  * `search_for_pattern`: Performs a search for a pattern in the project.
-#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
-#  * `switch_modes`: Activates modes by providing a list of their names
-#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
-#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
-#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
-#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
-excluded_tools: []
-
-# initial prompt for the project. It will always be given to the LLM upon activating the project
-# (contrary to the memories, which are loaded on demand).
-initial_prompt: ""
-
-project_name: "clawdbot"
-included_optional_tools: []

CHANGELOG.md

@@ -2,11 +2,14 @@
 
 Docs: https://docs.clawd.bot
 
-## 2026.1.20-1
+## 2026.1.20
 
 ### Changes
 - Deps: update workspace + memory-lancedb dependencies.
 - Repo: remove the Peekaboo git submodule now that the SPM release is used.
+- Update: sync plugin sources on channel switches and update npm-installed plugins during `clawdbot update`.
+- Plugins: share npm plugin update logic between `clawdbot update` and `clawdbot plugins update`.
+- Channels: add the Nostr plugin channel with profile management + onboarding install defaults. (#1323) — thanks @joelklabo.
 - Plugins: require manifest-embedded config schemas, validate configs without loading plugin code, and surface plugin config warnings. (#1272) — thanks @thewilloftheshadow.
 - Plugins: move channel catalog metadata into plugin manifests; align Nextcloud Talk policy helpers with core patterns. (#1290) — thanks @NicholaiVogel.
 - Discord: fall back to /skill when native command limits are exceeded; expose /skill globally. (#1287) — thanks @thewilloftheshadow.
@@ -14,14 +17,29 @@ Docs: https://docs.clawd.bot
 - Matrix: migrate to matrix-bot-sdk with E2EE support, location handling, and group allowlist upgrades. (#1298) — thanks @sibbl.
 - Plugins/UI: let channel plugin metadata drive UI labels/icons and cron channel options. (#1306) — thanks @steipete.
 - Zalouser: add channel dock metadata, config schema, setup wiring, probe, and status issues. (#1219) — thanks @suminhthanh.
+- Security: warn when <=300B models run without sandboxing and with web tools enabled.
 ### Fixes
+- Discovery: shorten Bonjour DNS-SD service type to `_clawdbot-gw._tcp` and update discovery clients/docs.
+- Agents: preserve subagent announce thread/topic routing + queued replies across channels. (#1241) — thanks @gnarco.
+- Agents: avoid treating timeout errors with "aborted" messages as user aborts, so model fallback still runs.
+- Diagnostics: export OTLP logs, correct queue depth tracking, and document message-flow telemetry.
+- Model catalog: avoid caching import failures, log transient discovery errors, and keep partial results. (#1332) — thanks @dougvk.
+- Doctor: clarify plugin auto-enable hint text in the startup banner.
+- Gateway: clarify unauthorized handshake responses with token/password mismatch guidance.
+- UI: keep config form enums typed, preserve empty strings, protect sensitive defaults, and deepen config search. (#1315) — thanks @MaudeBot.
 - Web search: infer Perplexity base URL from API key source (direct vs OpenRouter).
 - TUI: keep thinking blocks ordered before content during streaming and isolate per-run assembly. (#1202) — thanks @aaronveklabs.
 - TUI: align custom editor initialization with the latest pi-tui API. (#1298) — thanks @sibbl.
 - CLI: avoid duplicating --profile/--dev flags when formatting commands.
+- CLI: load channel plugins for commands that need registry-backed lookups. (#1338) — thanks @MaudeBot.
+- Status: route native `/status` to the active agent so model selection reflects the correct profile. (#1301)
 - Exec: prefer bash when fish is default shell, falling back to sh if bash is missing. (#1297) — thanks @ysqander.
 - Exec: merge login-shell PATH for host=gateway exec while keeping daemon PATH minimal. (#1304)
 - Plugins: add Nextcloud Talk manifest for plugin config validation. (#1297) — thanks @ysqander.
+- Anthropic: default API prompt caching to 1h with configurable TTL override; ignore TTL for OAuth.
+- Discord: make resolve warnings avoid raw JSON payloads on rate limits.
+- Discord: process message handlers in parallel across sessions to avoid event queue blocking. (#1295)
+- Cron: auto-deliver isolated agent output to explicit targets without tool calls. (#1285)
 
 ## 2026.1.19-3
 
@@ -58,6 +76,7 @@ Docs: https://docs.clawd.bot
 - Usage: add `/usage cost` summaries and macOS menu cost submenu with daily charting.
 - Agents: clarify node_modules read-only guidance in agent instructions.
 - TUI: add syntax highlighting for code blocks. (#1200) — thanks @vignesh07.
+- TUI: session picker shows derived titles, fuzzy search, relative times, and last message preview. (#1271) — thanks @Whoaa512.
 
 ### Fixes
 - UI: enable shell mode for sync Windows spawns to avoid `pnpm ui:build` EINVAL. (#1212) — thanks @longmaba.
@@ -70,6 +89,7 @@ Docs: https://docs.clawd.bot
 - TUI: show generic empty-state text for searchable pickers. (#1201) — thanks @vignesh07.
 - Doctor: canonicalize legacy session keys in session stores to prevent stale metadata. (#1169)
 - CLI: centralize CLI command registration to keep fast-path routing and program wiring in sync. (#1207) — thanks @gumadeiras.
+- Config: allow custom fields under `skills.entries.<name>.config` for skill credentials/config. (#1226) — thanks @VACInc. (fixes #1225)
 
 ## 2026.1.18-5
 

README.md

@@ -482,24 +482,24 @@ Thanks to all clawtributors:
   <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/MatthieuBizien"><img src="https://avatars.githubusercontent.com/u/173090?v=4&s=48" width="48" height="48" alt="MatthieuBizien" title="MatthieuBizien"/></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/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/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/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/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/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/TSavo"><img src="https://avatars.githubusercontent.com/u/877990?v=4&s=48" width="48" height="48" alt="TSavo" title="TSavo"/></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/timolins"><img src="https://avatars.githubusercontent.com/u/1440854?v=4&s=48" width="48" height="48" alt="timolins" title="timolins"/></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/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/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/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/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/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/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/bradleypriest"><img src="https://avatars.githubusercontent.com/u/167215?v=4&s=48" width="48" height="48" alt="bradleypriest" title="bradleypriest"/></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/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/joshrad-dev"><img src="https://avatars.githubusercontent.com/u/62785552?v=4&s=48" width="48" height="48" alt="joshrad-dev" title="joshrad-dev"/></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/adityashaw2"><img src="https://avatars.githubusercontent.com/u/41204444?v=4&s=48" width="48" height="48" alt="adityashaw2" title="adityashaw2"/></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/artuskg"><img src="https://avatars.githubusercontent.com/u/11966157?v=4&s=48" width="48" height="48" alt="artuskg" title="artuskg"/></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/connorshea"><img src="https://avatars.githubusercontent.com/u/2977353?v=4&s=48" width="48" height="48" alt="connorshea" title="connorshea"/></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/zerone0x"><img src="https://avatars.githubusercontent.com/u/39543393?v=4&s=48" width="48" height="48" alt="zerone0x" title="zerone0x"/></a> <a href="https://github.com/gerardward2007"><img src="https://avatars.githubusercontent.com/u/3002155?v=4&s=48" width="48" height="48" alt="gerardward2007" title="gerardward2007"/></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/tosh-hamburg"><img src="https://avatars.githubusercontent.com/u/58424326?v=4&s=48" width="48" height="48" alt="tosh-hamburg" title="tosh-hamburg"/></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/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/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/cheeeee"><img src="https://avatars.githubusercontent.com/u/21245729?v=4&s=48" width="48" height="48" alt="cheeeee" title="cheeeee"/></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/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/chriseidhof"><img src="https://avatars.githubusercontent.com/u/5382?v=4&s=48" width="48" height="48" alt="chriseidhof" title="chriseidhof"/></a> <a href="https://github.com/tyler6204"><img src="https://avatars.githubusercontent.com/u/64381258?v=4&s=48" width="48" height="48" alt="tyler6204" title="tyler6204"/></a> <a href="https://github.com/ysqander"><img src="https://avatars.githubusercontent.com/u/80843820?v=4&s=48" width="48" height="48" alt="ysqander" title="ysqander"/></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/vignesh07"><img src="https://avatars.githubusercontent.com/u/1436853?v=4&s=48" width="48" height="48" alt="vignesh07" title="vignesh07"/></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/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/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/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/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/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/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/search?q=Ryan%20Lisse"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ryan Lisse" title="Ryan Lisse"/></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/search?q=Ghost"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ghost" title="Ghost"/></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/search?q=Marc"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Marc" title="Marc"/></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/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/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/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/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/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/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/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/24601"><img src="https://avatars.githubusercontent.com/u/1157207?v=4&s=48" width="48" height="48" alt="24601" title="24601"/></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/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/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/humanwritten"><img src="https://avatars.githubusercontent.com/u/206531610?v=4&s=48" width="48" height="48" alt="humanwritten" title="humanwritten"/></a> <a href="https://github.com/larlyssa"><img src="https://avatars.githubusercontent.com/u/13128869?v=4&s=48" width="48" height="48" alt="larlyssa" title="larlyssa"/></a> <a href="https://github.com/mkbehr"><img src="https://avatars.githubusercontent.com/u/1285?v=4&s=48" width="48" height="48" alt="mkbehr" title="mkbehr"/></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/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/sibbl"><img src="https://avatars.githubusercontent.com/u/866535?v=4&s=48" width="48" height="48" alt="sibbl" title="sibbl"/></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/aaronveklabs"><img src="https://avatars.githubusercontent.com/u/225997828?v=4&s=48" width="48" height="48" alt="aaronveklabs" title="aaronveklabs"/></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/dougvk"><img src="https://avatars.githubusercontent.com/u/401660?v=4&s=48" width="48" height="48" alt="dougvk" title="dougvk"/></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/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/ivanrvpereira"><img src="https://avatars.githubusercontent.com/u/183991?v=4&s=48" width="48" height="48" alt="ivanrvpereira" title="ivanrvpereira"/></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/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/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/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/T5-AndyML"><img src="https://avatars.githubusercontent.com/u/22801233?v=4&s=48" width="48" height="48" alt="T5-AndyML" title="T5-AndyML"/></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/anpoirier"><img src="https://avatars.githubusercontent.com/u/1245729?v=4&s=48" width="48" height="48" alt="anpoirier" title="anpoirier"/></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=Dimitrios%20Ploutarchos"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Dimitrios Ploutarchos" title="Dimitrios Ploutarchos"/></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/search?q=Felix%20Krause"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Felix Krause" title="Felix Krause"/></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=Jamie%20Openshaw"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jamie Openshaw" title="Jamie Openshaw"/></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/search?q=Kevin%20Lin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kevin Lin" title="Kevin Lin"/></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/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/rodrigouroz"><img src="https://avatars.githubusercontent.com/u/384037?v=4&s=48" width="48" height="48" alt="rodrigouroz" title="rodrigouroz"/></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/suminhthanh"><img src="https://avatars.githubusercontent.com/u/2907636?v=4&s=48" width="48" height="48" alt="suminhthanh" title="suminhthanh"/></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/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=Ubuntu"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ubuntu" title="Ubuntu"/></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/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/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/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/odrobnik"><img src="https://avatars.githubusercontent.com/u/333270?v=4&s=48" width="48" height="48" alt="odrobnik" title="odrobnik"/></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/rhjoh"><img src="https://avatars.githubusercontent.com/u/105699450?v=4&s=48" width="48" height="48" alt="rhjoh" title="rhjoh"/></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/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/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/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/bradleypriest"><img src="https://avatars.githubusercontent.com/u/167215?v=4&s=48" width="48" height="48" alt="bradleypriest" title="bradleypriest"/></a> <a href="https://github.com/timolins"><img src="https://avatars.githubusercontent.com/u/1440854?v=4&s=48" width="48" height="48" alt="timolins" title="timolins"/></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/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/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/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/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/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/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/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/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/joshrad-dev"><img src="https://avatars.githubusercontent.com/u/62785552?v=4&s=48" width="48" height="48" alt="joshrad-dev" title="joshrad-dev"/></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/adityashaw2"><img src="https://avatars.githubusercontent.com/u/41204444?v=4&s=48" width="48" height="48" alt="adityashaw2" title="adityashaw2"/></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/artuskg"><img src="https://avatars.githubusercontent.com/u/11966157?v=4&s=48" width="48" height="48" alt="artuskg" title="artuskg"/></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/tyler6204"><img src="https://avatars.githubusercontent.com/u/64381258?v=4&s=48" width="48" height="48" alt="tyler6204" title="tyler6204"/></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/connorshea"><img src="https://avatars.githubusercontent.com/u/2977353?v=4&s=48" width="48" height="48" alt="connorshea" title="connorshea"/></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/John-Rood"><img src="https://avatars.githubusercontent.com/u/62669593?v=4&s=48" width="48" height="48" alt="John-Rood" title="John-Rood"/></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/zerone0x"><img src="https://avatars.githubusercontent.com/u/39543393?v=4&s=48" width="48" height="48" alt="zerone0x" title="zerone0x"/></a> <a href="https://github.com/gerardward2007"><img src="https://avatars.githubusercontent.com/u/3002155?v=4&s=48" width="48" height="48" alt="gerardward2007" title="gerardward2007"/></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/tosh-hamburg"><img src="https://avatars.githubusercontent.com/u/58424326?v=4&s=48" width="48" height="48" alt="tosh-hamburg" title="tosh-hamburg"/></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/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/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/cheeeee"><img src="https://avatars.githubusercontent.com/u/21245729?v=4&s=48" width="48" height="48" alt="cheeeee" title="cheeeee"/></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/Whoaa512"><img src="https://avatars.githubusercontent.com/u/1581943?v=4&s=48" width="48" height="48" alt="Whoaa512" title="Whoaa512"/></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/chriseidhof"><img src="https://avatars.githubusercontent.com/u/5382?v=4&s=48" width="48" height="48" alt="chriseidhof" title="chriseidhof"/></a> <a href="https://github.com/ysqander"><img src="https://avatars.githubusercontent.com/u/80843820?v=4&s=48" width="48" height="48" alt="ysqander" title="ysqander"/></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/vignesh07"><img src="https://avatars.githubusercontent.com/u/1436853?v=4&s=48" width="48" height="48" alt="vignesh07" title="vignesh07"/></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/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/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/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/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/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/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/search?q=Ryan%20Lisse"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ryan Lisse" title="Ryan Lisse"/></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/search?q=Ghost"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ghost" title="Ghost"/></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/search?q=Marc"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Marc" title="Marc"/></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/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/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/dougvk"><img src="https://avatars.githubusercontent.com/u/401660?v=4&s=48" width="48" height="48" alt="dougvk" title="dougvk"/></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/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/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/sibbl"><img src="https://avatars.githubusercontent.com/u/866535?v=4&s=48" width="48" height="48" alt="sibbl" title="sibbl"/></a> <a href="https://github.com/suminhthanh"><img src="https://avatars.githubusercontent.com/u/2907636?v=4&s=48" width="48" height="48" alt="suminhthanh" title="suminhthanh"/></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/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/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/24601"><img src="https://avatars.githubusercontent.com/u/1157207?v=4&s=48" width="48" height="48" alt="24601" title="24601"/></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/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/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/humanwritten"><img src="https://avatars.githubusercontent.com/u/206531610?v=4&s=48" width="48" height="48" alt="humanwritten" title="humanwritten"/></a> <a href="https://github.com/larlyssa"><img src="https://avatars.githubusercontent.com/u/13128869?v=4&s=48" width="48" height="48" alt="larlyssa" title="larlyssa"/></a> <a href="https://github.com/mkbehr"><img src="https://avatars.githubusercontent.com/u/1285?v=4&s=48" width="48" height="48" alt="mkbehr" title="mkbehr"/></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/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/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/aaronveklabs"><img src="https://avatars.githubusercontent.com/u/225997828?v=4&s=48" width="48" height="48" alt="aaronveklabs" title="aaronveklabs"/></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/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/ivanrvpereira"><img src="https://avatars.githubusercontent.com/u/183991?v=4&s=48" width="48" height="48" alt="ivanrvpereira" title="ivanrvpereira"/></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/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/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/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/T5-AndyML"><img src="https://avatars.githubusercontent.com/u/22801233?v=4&s=48" width="48" height="48" alt="T5-AndyML" title="T5-AndyML"/></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/anpoirier"><img src="https://avatars.githubusercontent.com/u/1245729?v=4&s=48" width="48" height="48" alt="anpoirier" title="anpoirier"/></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=Dimitrios%20Ploutarchos"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Dimitrios Ploutarchos" title="Dimitrios Ploutarchos"/></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/search?q=Felix%20Krause"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Felix Krause" title="Felix Krause"/></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=Jamie%20Openshaw"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jamie Openshaw" title="Jamie Openshaw"/></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/search?q=Kevin%20Lin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kevin Lin" title="Kevin Lin"/></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/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/odysseus0"><img src="https://avatars.githubusercontent.com/u/8635094?v=4&s=48" width="48" height="48" alt="odysseus0" title="odysseus0"/></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/rodrigouroz"><img src="https://avatars.githubusercontent.com/u/384037?v=4&s=48" width="48" height="48" alt="rodrigouroz" title="rodrigouroz"/></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/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=Ubuntu"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ubuntu" title="Ubuntu"/></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/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/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/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/odrobnik"><img src="https://avatars.githubusercontent.com/u/333270?v=4&s=48" width="48" height="48" alt="odrobnik" title="odrobnik"/></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/rhjoh"><img src="https://avatars.githubusercontent.com/u/105699450?v=4&s=48" width="48" height="48" alt="rhjoh" title="rhjoh"/></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/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
 </p>

Swabble/Package.resolved

@@ -1,5 +1,5 @@
 {
-  "originHash" : "2e6f580ad7d1e839d513aa883350369bf2e4193fad872030fdaea7827f34d8ef",
+  "originHash" : "c0677e232394b5f6b0191b6dbb5bae553d55264f65ae725cd03a8ffdfda9cdd3",
   "pins" : [
     {
       "identity" : "commander",
@@ -10,24 +10,6 @@
         "version" : "0.2.1"
       }
     },
-    {
-      "identity" : "elevenlabskit",
-      "kind" : "remoteSourceControl",
-      "location" : "https://github.com/steipete/ElevenLabsKit",
-      "state" : {
-        "revision" : "c8679fbd37416a8780fe43be88a497ff16209e2d",
-        "version" : "0.1.0"
-      }
-    },
-    {
-      "identity" : "swift-concurrency-extras",
-      "kind" : "remoteSourceControl",
-      "location" : "https://github.com/pointfreeco/swift-concurrency-extras",
-      "state" : {
-        "revision" : "5a3825302b1a0d744183200915a47b508c828e6f",
-        "version" : "1.3.2"
-      }
-    },
     {
       "identity" : "swift-syntax",
       "kind" : "remoteSourceControl",
@@ -45,24 +27,6 @@
         "revision" : "399f76dcd91e4c688ca2301fa24a8cc6d9927211",
         "version" : "0.99.0"
       }
-    },
-    {
-      "identity" : "swiftui-math",
-      "kind" : "remoteSourceControl",
-      "location" : "https://github.com/gonzalezreal/swiftui-math",
-      "state" : {
-        "revision" : "0b5c2cfaaec8d6193db206f675048eeb5ce95f71",
-        "version" : "0.1.0"
-      }
-    },
-    {
-      "identity" : "textual",
-      "kind" : "remoteSourceControl",
-      "location" : "https://github.com/gonzalezreal/textual",
-      "state" : {
-        "revision" : "a03c1e103d88de4ea0dd8320ea1611ec0d4b29b3",
-        "version" : "0.2.0"
-      }
     }
   ],
   "version" : 3

apps/android/README.md

@@ -1,6 +1,6 @@
 ## Clawdbot Node (Android) (internal)
 
-Modern Android node app: connects to the **Gateway WebSocket** (`_clawdbot-gateway._tcp`) and exposes **Canvas + Chat + Camera**.
+Modern Android node app: connects to the **Gateway WebSocket** (`_clawdbot-gw._tcp`) and exposes **Canvas + Chat + Camera**.
 
 Notes:
 - The node keeps the connection alive via a **foreground service** (persistent notification with a Disconnect action).

apps/android/app/build.gradle.kts

@@ -21,8 +21,8 @@ android {
     applicationId = "com.clawdbot.android"
     minSdk = 31
     targetSdk = 36
-    versionCode = 202601114
-    versionName = "2026.1.11-4"
+    versionCode = 202601200
+    versionName = "2026.1.20"
   }
 
   buildTypes {

apps/android/app/src/main/java/com/clawdbot/android/gateway/GatewayDiscovery.kt

@@ -51,7 +51,7 @@ class GatewayDiscovery(
   private val nsd = context.getSystemService(NsdManager::class.java)
   private val connectivity = context.getSystemService(ConnectivityManager::class.java)
   private val dns = DnsResolver.getInstance()
-  private val serviceType = "_clawdbot-gateway._tcp."
+  private val serviceType = "_clawdbot-gw._tcp."
   private val wideAreaDomain = "clawdbot.internal."
   private val logTag = "Clawdbot/GatewayDiscovery"
 

apps/ios/Sources/Info.plist

@@ -19,9 +19,9 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.1.9</string>
+	<string>2026.1.20</string>
 	<key>CFBundleVersion</key>
-	<string>20260109</string>
+	<string>20260120</string>
 	<key>NSAppTransportSecurity</key>
 	<dict>
 		<key>NSAllowsArbitraryLoadsInWebContent</key>
@@ -29,7 +29,7 @@
 	</dict>
 	<key>NSBonjourServices</key>
 	<array>
-		<string>_clawdbot-gateway._tcp</string>
+		<string>_clawdbot-gw._tcp</string>
 	</array>
 	<key>NSCameraUsageDescription</key>
 	<string>Clawdbot can capture photos or short video clips when requested via the gateway.</string>

apps/ios/Tests/GatewayEndpointIDTests.swift

@@ -7,11 +7,11 @@ import Testing
     @Test func stableIDForServiceDecodesAndNormalizesName() {
         let endpoint = NWEndpoint.service(
             name: "Clawdbot\\032Gateway   \\032  Node\n",
-            type: "_clawdbot-gateway._tcp",
+            type: "_clawdbot-gw._tcp",
             domain: "local.",
             interface: nil)
 
-        #expect(GatewayEndpointID.stableID(endpoint) == "_clawdbot-gateway._tcp|local.|Clawdbot Gateway Node")
+        #expect(GatewayEndpointID.stableID(endpoint) == "_clawdbot-gw._tcp|local.|Clawdbot Gateway Node")
     }
 
     @Test func stableIDForNonServiceUsesEndpointDescription() {
@@ -22,7 +22,7 @@ import Testing
     @Test func prettyDescriptionDecodesBonjourEscapes() {
         let endpoint = NWEndpoint.service(
             name: "Clawdbot\\032Gateway",
-            type: "_clawdbot-gateway._tcp",
+            type: "_clawdbot-gw._tcp",
             domain: "local.",
             interface: nil)
 

apps/ios/Tests/Info.plist

@@ -17,8 +17,8 @@
 	<key>CFBundlePackageType</key>
 	<string>BNDL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.1.9</string>
+	<string>2026.1.20</string>
 	<key>CFBundleVersion</key>
-	<string>20260109</string>
+	<string>20260120</string>
 </dict>
 </plist>

apps/ios/project.yml

@@ -81,8 +81,8 @@ targets:
       properties:
         CFBundleDisplayName: Clawdbot
         CFBundleIconName: AppIcon
-        CFBundleShortVersionString: "2026.1.9"
-        CFBundleVersion: "20260109"
+        CFBundleShortVersionString: "2026.1.20"
+        CFBundleVersion: "20260120"
         UILaunchScreen: {}
         UIApplicationSceneManifest:
           UIApplicationSupportsMultipleScenes: false
@@ -92,7 +92,7 @@ targets:
         NSAppTransportSecurity:
           NSAllowsArbitraryLoadsInWebContent: true
         NSBonjourServices:
-          - _clawdbot-gateway._tcp
+          - _clawdbot-gw._tcp
         NSCameraUsageDescription: Clawdbot can capture photos or short video clips when requested via the gateway.
         NSLocationWhenInUseUsageDescription: Clawdbot uses your location when you allow location sharing.
         NSLocationAlwaysAndWhenInUseUsageDescription: Clawdbot can share your location in the background when you enable Always.
@@ -130,5 +130,5 @@ targets:
       path: Tests/Info.plist
       properties:
         CFBundleDisplayName: ClawdbotTests
-        CFBundleShortVersionString: "2026.1.9"
-        CFBundleVersion: "20260109"
+        CFBundleShortVersionString: "2026.1.20"
+        CFBundleVersion: "20260120"

apps/macos/Package.resolved

@@ -1,5 +1,5 @@
 {
-  "originHash" : "4ed05a95fa9feada29b97f81b3194392e59a0c7b9edf24851f922bc2b72b0438",
+  "originHash" : "550d4ea41d4bb2546b99a7bfa1c5cba7e28a13862bc226727ea7426c61555a33",
   "pins" : [
     {
       "identity" : "axorcist",

apps/macos/Package.swift

@@ -12,8 +12,7 @@ let package = Package(
         .library(name: "ClawdbotIPC", targets: ["ClawdbotIPC"]),
         .library(name: "ClawdbotDiscovery", targets: ["ClawdbotDiscovery"]),
         .executable(name: "Clawdbot", targets: ["Clawdbot"]),
-        .executable(name: "clawdbot-mac-discovery", targets: ["ClawdbotDiscoveryCLI"]),
-        .executable(name: "clawdbot-mac-wizard", targets: ["ClawdbotWizardCLI"]),
+        .executable(name: "clawdbot-mac", targets: ["ClawdbotMacCLI"]),
     ],
     dependencies: [
         .package(url: "https://github.com/orchetect/MenuBarExtraAccess", exact: "1.2.2"),
@@ -67,21 +66,13 @@ let package = Package(
                 .enableUpcomingFeature("StrictConcurrency"),
             ]),
         .executableTarget(
-            name: "ClawdbotDiscoveryCLI",
+            name: "ClawdbotMacCLI",
             dependencies: [
                 "ClawdbotDiscovery",
-            ],
-            path: "Sources/ClawdbotDiscoveryCLI",
-            swiftSettings: [
-                .enableUpcomingFeature("StrictConcurrency"),
-            ]),
-        .executableTarget(
-            name: "ClawdbotWizardCLI",
-            dependencies: [
                 .product(name: "ClawdbotKit", package: "ClawdbotKit"),
                 .product(name: "ClawdbotProtocol", package: "ClawdbotKit"),
             ],
-            path: "Sources/ClawdbotWizardCLI",
+            path: "Sources/ClawdbotMacCLI",
             swiftSettings: [
                 .enableUpcomingFeature("StrictConcurrency"),
             ]),

apps/macos/Sources/Clawdbot/AgentEventsWindow.swift

@@ -81,7 +81,7 @@ private struct EventRow: View {
         return f.string(from: date)
     }
 
-    private func prettyJSON(_ dict: [String: AnyCodable]) -> String? {
+    private func prettyJSON(_ dict: [String: ClawdbotProtocol.AnyCodable]) -> String? {
         let normalized = dict.mapValues { $0.value }
         guard JSONSerialization.isValidJSONObject(normalized),
               let data = try? JSONSerialization.data(withJSONObject: normalized, options: [.prettyPrinted]),
@@ -98,7 +98,10 @@ struct AgentEventsWindow_Previews: PreviewProvider {
             seq: 1,
             stream: "tool",
             ts: Date().timeIntervalSince1970 * 1000,
-            data: ["phase": AnyCodable("start"), "name": AnyCodable("bash")],
+            data: [
+                "phase": ClawdbotProtocol.AnyCodable("start"),
+                "name": ClawdbotProtocol.AnyCodable("bash"),
+            ],
             summary: nil)
         AgentEventStore.shared.append(sample)
         return AgentEventsWindow()

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

@@ -1,6 +1,11 @@
+import ClawdbotKit
 import ClawdbotProtocol
 import Foundation
 
+// Prefer the ClawdbotKit wrapper to keep gateway request payloads consistent.
+typealias AnyCodable = ClawdbotKit.AnyCodable
+typealias InstanceIdentity = ClawdbotKit.InstanceIdentity
+
 extension AnyCodable {
     var stringValue: String? { self.value as? String }
     var boolValue: Bool? { self.value as? Bool }
@@ -20,3 +25,23 @@ extension AnyCodable {
         }
     }
 }
+
+extension ClawdbotProtocol.AnyCodable {
+    var stringValue: String? { self.value as? String }
+    var boolValue: Bool? { self.value as? Bool }
+    var intValue: Int? { self.value as? Int }
+    var doubleValue: Double? { self.value as? Double }
+    var dictionaryValue: [String: ClawdbotProtocol.AnyCodable]? { self.value as? [String: ClawdbotProtocol.AnyCodable] }
+    var arrayValue: [ClawdbotProtocol.AnyCodable]? { self.value as? [ClawdbotProtocol.AnyCodable] }
+
+    var foundationValue: Any {
+        switch self.value {
+        case let dict as [String: ClawdbotProtocol.AnyCodable]:
+            dict.mapValues { $0.foundationValue }
+        case let array as [ClawdbotProtocol.AnyCodable]:
+            array.map(\.foundationValue)
+        default:
+            self.value
+        }
+    }
+}

apps/macos/Sources/Clawdbot/ChannelsSettings+ChannelState.swift

@@ -432,11 +432,11 @@ extension ChannelsSettings {
     }
 
     private func resolveChannelDetailTitle(_ id: String) -> String {
-        return self.store.resolveChannelDetailLabel(id)
+        self.store.resolveChannelDetailLabel(id)
     }
 
     private func resolveChannelSystemImage(_ id: String) -> String {
-        return self.store.resolveChannelSystemImage(id)
+        self.store.resolveChannelSystemImage(id)
     }
 
     private func channelStatusDictionary(_ id: String) -> [String: AnyCodable]? {

apps/macos/Sources/Clawdbot/ChannelsStore.swift

@@ -163,9 +163,9 @@ struct ChannelsStatusSnapshot: Codable {
     let ts: Double
     let channelOrder: [String]
     let channelLabels: [String: String]
-    let channelDetailLabels: [String: String]? = nil
-    let channelSystemImages: [String: String]? = nil
-    let channelMeta: [ChannelUiMetaEntry]? = nil
+    let channelDetailLabels: [String: String]?
+    let channelSystemImages: [String: String]?
+    let channelMeta: [ChannelUiMetaEntry]?
     let channels: [String: AnyCodable]
     let channelAccounts: [String: [ChannelAccountSnapshot]]
     let channelDefaultAccountId: [String: String]
@@ -263,7 +263,7 @@ final class ChannelsStore {
 
     func orderedChannelIds() -> [String] {
         if let meta = self.snapshot?.channelMeta, !meta.isEmpty {
-            return meta.map { $0.id }
+            return meta.map(\.id)
         }
         return self.snapshot?.channelOrder ?? []
     }

apps/macos/Sources/Clawdbot/ControlChannel.swift

@@ -20,7 +20,7 @@ struct ControlAgentEvent: Codable, Sendable, Identifiable {
     let seq: Int
     let stream: String
     let ts: Double
-    let data: [String: AnyCodable]
+    let data: [String: ClawdbotProtocol.AnyCodable]
     let summary: String?
 }
 
@@ -156,8 +156,8 @@ final class ControlChannel {
         timeoutMs: Double? = nil) async throws -> Data
     {
         do {
-            let rawParams = params?.reduce(into: [String: AnyCodable]()) {
-                $0[$1.key] = AnyCodable($1.value.base)
+            let rawParams = params?.reduce(into: [String: ClawdbotKit.AnyCodable]()) {
+                $0[$1.key] = ClawdbotKit.AnyCodable($1.value.base)
             }
             let data = try await GatewayConnection.shared.request(
                 method: method,
@@ -346,7 +346,7 @@ final class ControlChannel {
             let phase = event.data["phase"]?.value as? String ?? ""
             let name = event.data["name"]?.value as? String
             let meta = event.data["meta"]?.value as? String
-            let args = event.data["args"]?.value as? [String: AnyCodable]
+            let args = Self.bridgeToProtocolArgs(event.data["args"])
             WorkActivityStore.shared.handleTool(
                 sessionKey: sessionKey,
                 phase: phase,
@@ -357,6 +357,27 @@ final class ControlChannel {
             break
         }
     }
+
+    private static func bridgeToProtocolArgs(
+        _ value: ClawdbotProtocol.AnyCodable?) -> [String: ClawdbotProtocol.AnyCodable]?
+    {
+        guard let value else { return nil }
+        if let dict = value.value as? [String: ClawdbotProtocol.AnyCodable] {
+            return dict
+        }
+        if let dict = value.value as? [String: ClawdbotKit.AnyCodable],
+           let data = try? JSONEncoder().encode(dict),
+           let decoded = try? JSONDecoder().decode([String: ClawdbotProtocol.AnyCodable].self, from: data)
+        {
+            return decoded
+        }
+        if let data = try? JSONEncoder().encode(value),
+           let decoded = try? JSONDecoder().decode([String: ClawdbotProtocol.AnyCodable].self, from: data)
+        {
+            return decoded
+        }
+        return nil
+    }
 }
 
 extension Notification.Name {

apps/macos/Sources/Clawdbot/ExecApprovalsSocket.swift

@@ -259,6 +259,20 @@ enum ExecApprovalsPromptPresenter {
 
 @MainActor
 private enum ExecHostExecutor {
+    private struct ExecApprovalContext {
+        let command: [String]
+        let displayCommand: String
+        let trimmedAgent: String?
+        let approvals: ExecApprovalsResolved
+        let security: ExecSecurity
+        let ask: ExecAsk
+        let autoAllowSkills: Bool
+        let env: [String: String]?
+        let resolution: ExecCommandResolution?
+        let allowlistMatch: ExecAllowlistEntry?
+        let skillAllow: Bool
+    }
+
     private static let blockedEnvKeys: Set<String> = [
         "PATH",
         "NODE_OPTIONS",
@@ -277,14 +291,93 @@ private enum ExecHostExecutor {
     static func handle(_ request: ExecHostRequest) async -> ExecHostResponse {
         let command = request.command.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
         guard !command.isEmpty else {
-            return ExecHostResponse(
-                type: "exec-res",
-                id: UUID().uuidString,
-                ok: false,
-                payload: nil,
-                error: ExecHostError(code: "INVALID_REQUEST", message: "command required", reason: "invalid"))
+            return self.errorResponse(
+                code: "INVALID_REQUEST",
+                message: "command required",
+                reason: "invalid")
         }
 
+        let context = await self.buildContext(request: request, command: command)
+        if context.security == .deny {
+            return self.errorResponse(
+                code: "UNAVAILABLE",
+                message: "SYSTEM_RUN_DISABLED: security=deny",
+                reason: "security=deny")
+        }
+
+        let approvalDecision = request.approvalDecision
+        if approvalDecision == .deny {
+            return self.errorResponse(
+                code: "UNAVAILABLE",
+                message: "SYSTEM_RUN_DENIED: user denied",
+                reason: "user-denied")
+        }
+
+        var approvedByAsk = approvalDecision != nil
+        if self.requiresAsk(
+            ask: context.ask,
+            security: context.security,
+            allowlistMatch: context.allowlistMatch,
+            skillAllow: context.skillAllow),
+           approvalDecision == nil
+        {
+            let decision = ExecApprovalsPromptPresenter.prompt(
+                ExecApprovalPromptRequest(
+                    command: context.displayCommand,
+                    cwd: request.cwd,
+                    host: "node",
+                    security: context.security.rawValue,
+                    ask: context.ask.rawValue,
+                    agentId: context.trimmedAgent,
+                    resolvedPath: context.resolution?.resolvedPath))
+
+            switch decision {
+            case .deny:
+                return self.errorResponse(
+                    code: "UNAVAILABLE",
+                    message: "SYSTEM_RUN_DENIED: user denied",
+                    reason: "user-denied")
+            case .allowAlways:
+                approvedByAsk = true
+                self.persistAllowlistEntry(decision: decision, context: context)
+            case .allowOnce:
+                approvedByAsk = true
+            }
+        }
+
+        self.persistAllowlistEntry(decision: approvalDecision, context: context)
+
+        if context.security == .allowlist,
+           context.allowlistMatch == nil,
+           !context.skillAllow,
+           !approvedByAsk
+        {
+            return self.errorResponse(
+                code: "UNAVAILABLE",
+                message: "SYSTEM_RUN_DENIED: allowlist miss",
+                reason: "allowlist-miss")
+        }
+
+        if let match = context.allowlistMatch {
+            ExecApprovalsStore.recordAllowlistUse(
+                agentId: context.trimmedAgent,
+                pattern: match.pattern,
+                command: context.displayCommand,
+                resolvedPath: context.resolution?.resolvedPath)
+        }
+
+        if let errorResponse = await self.ensureScreenRecordingAccess(request.needsScreenRecording) {
+            return errorResponse
+        }
+
+        return await self.runCommand(
+            command: command,
+            cwd: request.cwd,
+            env: context.env,
+            timeoutMs: request.timeoutMs)
+    }
+
+    private static func buildContext(request: ExecHostRequest, command: [String]) async -> ExecApprovalContext {
         let displayCommand = ExecCommandFormatter.displayString(
             for: command,
             rawCommand: request.rawCommand)
@@ -310,122 +403,72 @@ private enum ExecHostExecutor {
         } else {
             skillAllow = false
         }
+        return ExecApprovalContext(
+            command: command,
+            displayCommand: displayCommand,
+            trimmedAgent: trimmedAgent,
+            approvals: approvals,
+            security: security,
+            ask: ask,
+            autoAllowSkills: autoAllowSkills,
+            env: env,
+            resolution: resolution,
+            allowlistMatch: allowlistMatch,
+            skillAllow: skillAllow)
+    }
 
-        if security == .deny {
-            return ExecHostResponse(
-                type: "exec-res",
-                id: UUID().uuidString,
-                ok: false,
-                payload: nil,
-                error: ExecHostError(
-                    code: "UNAVAILABLE",
-                    message: "SYSTEM_RUN_DISABLED: security=deny",
-                    reason: "security=deny"))
+    private static func requiresAsk(
+        ask: ExecAsk,
+        security: ExecSecurity,
+        allowlistMatch: ExecAllowlistEntry?,
+        skillAllow: Bool) -> Bool
+    {
+        if ask == .always { return true }
+        if ask == .onMiss, security == .allowlist, allowlistMatch == nil, !skillAllow { return true }
+        return false
+    }
+
+    private static func persistAllowlistEntry(
+        decision: ExecApprovalDecision?,
+        context: ExecApprovalContext)
+    {
+        guard decision == .allowAlways, context.security == .allowlist else { return }
+        guard let pattern = self.allowlistPattern(command: context.command, resolution: context.resolution) else {
+            return
         }
+        ExecApprovalsStore.addAllowlistEntry(agentId: context.trimmedAgent, pattern: pattern)
+    }
 
-        let requiresAsk: Bool = {
-            if ask == .always { return true }
-            if ask == .onMiss, security == .allowlist, allowlistMatch == nil, !skillAllow { return true }
-            return false
-        }()
+    private static func allowlistPattern(
+        command: [String],
+        resolution: ExecCommandResolution?) -> String?
+    {
+        let pattern = resolution?.resolvedPath ?? resolution?.rawExecutable ?? command.first ?? ""
+        return pattern.isEmpty ? nil : pattern
+    }
 
-        let approvalDecision = request.approvalDecision
-        if approvalDecision == .deny {
-            return ExecHostResponse(
-                type: "exec-res",
-                id: UUID().uuidString,
-                ok: false,
-                payload: nil,
-                error: ExecHostError(
-                    code: "UNAVAILABLE",
-                    message: "SYSTEM_RUN_DENIED: user denied",
-                    reason: "user-denied"))
-        }
+    private static func ensureScreenRecordingAccess(_ needsScreenRecording: Bool?) async -> ExecHostResponse? {
+        guard needsScreenRecording == true else { return nil }
+        let authorized = await PermissionManager
+            .status([.screenRecording])[.screenRecording] ?? false
+        if authorized { return nil }
+        return self.errorResponse(
+            code: "UNAVAILABLE",
+            message: "PERMISSION_MISSING: screenRecording",
+            reason: "permission:screenRecording")
+    }
 
-        var approvedByAsk = approvalDecision != nil
-        if requiresAsk, approvalDecision == nil {
-            let decision = ExecApprovalsPromptPresenter.prompt(
-                ExecApprovalPromptRequest(
-                    command: displayCommand,
-                    cwd: request.cwd,
-                    host: "node",
-                    security: security.rawValue,
-                    ask: ask.rawValue,
-                    agentId: trimmedAgent,
-                    resolvedPath: resolution?.resolvedPath))
-
-            switch decision {
-            case .deny:
-                return ExecHostResponse(
-                    type: "exec-res",
-                    id: UUID().uuidString,
-                    ok: false,
-                    payload: nil,
-                    error: ExecHostError(
-                        code: "UNAVAILABLE",
-                        message: "SYSTEM_RUN_DENIED: user denied",
-                        reason: "user-denied"))
-            case .allowAlways:
-                approvedByAsk = true
-                if security == .allowlist {
-                    let pattern = resolution?.resolvedPath ?? resolution?.rawExecutable ?? command.first ?? ""
-                    if !pattern.isEmpty {
-                        ExecApprovalsStore.addAllowlistEntry(agentId: trimmedAgent, pattern: pattern)
-                    }
-                }
-            case .allowOnce:
-                approvedByAsk = true
-            }
-        }
-
-        if approvalDecision == .allowAlways, security == .allowlist {
-            let pattern = resolution?.resolvedPath ?? resolution?.rawExecutable ?? command.first ?? ""
-            if !pattern.isEmpty {
-                ExecApprovalsStore.addAllowlistEntry(agentId: trimmedAgent, pattern: pattern)
-            }
-        }
-
-        if security == .allowlist, allowlistMatch == nil, !skillAllow, !approvedByAsk {
-            return ExecHostResponse(
-                type: "exec-res",
-                id: UUID().uuidString,
-                ok: false,
-                payload: nil,
-                error: ExecHostError(
-                    code: "UNAVAILABLE",
-                    message: "SYSTEM_RUN_DENIED: allowlist miss",
-                    reason: "allowlist-miss"))
-        }
-
-        if let match = allowlistMatch {
-            ExecApprovalsStore.recordAllowlistUse(
-                agentId: trimmedAgent,
-                pattern: match.pattern,
-                command: displayCommand,
-                resolvedPath: resolution?.resolvedPath)
-        }
-
-        if request.needsScreenRecording == true {
-            let authorized = await PermissionManager
-                .status([.screenRecording])[.screenRecording] ?? false
-            if !authorized {
-                return ExecHostResponse(
-                    type: "exec-res",
-                    id: UUID().uuidString,
-                    ok: false,
-                    payload: nil,
-                    error: ExecHostError(
-                        code: "UNAVAILABLE",
-                        message: "PERMISSION_MISSING: screenRecording",
-                        reason: "permission:screenRecording"))
-            }
-        }
-
-        let timeoutSec = request.timeoutMs.flatMap { Double($0) / 1000.0 }
+    private static func runCommand(
+        command: [String],
+        cwd: String?,
+        env: [String: String]?,
+        timeoutMs: Int?) async -> ExecHostResponse
+    {
+        let timeoutSec = timeoutMs.flatMap { Double($0) / 1000.0 }
         let result = await Task.detached { () -> ShellExecutor.ShellResult in
             await ShellExecutor.runDetailed(
                 command: command,
-                cwd: request.cwd,
+                cwd: cwd,
                 env: env,
                 timeout: timeoutSec)
         }.value
@@ -436,7 +479,24 @@ private enum ExecHostExecutor {
             stdout: result.stdout,
             stderr: result.stderr,
             error: result.errorMessage)
-        return ExecHostResponse(
+        return self.successResponse(payload)
+    }
+
+    private static func errorResponse(
+        code: String,
+        message: String,
+        reason: String?) -> ExecHostResponse
+    {
+        ExecHostResponse(
+            type: "exec-res",
+            id: UUID().uuidString,
+            ok: false,
+            payload: nil,
+            error: ExecHostError(code: code, message: message, reason: reason))
+    }
+
+    private static func successResponse(_ payload: ExecHostRunResult) -> ExecHostResponse {
+        ExecHostResponse(
             type: "exec-res",
             id: UUID().uuidString,
             ok: true,

apps/macos/Sources/Clawdbot/GatewayConnection.swift

@@ -148,6 +148,27 @@ actor GatewayConnection {
                     }
                 }
 
+                let nsError = lastError as NSError
+                if nsError.domain == URLError.errorDomain,
+                   let fallback = await GatewayEndpointStore.shared.maybeFallbackToTailnet(from: cfg.url)
+                {
+                    await self.configure(url: fallback.url, token: fallback.token, password: fallback.password)
+                    for delayMs in [150, 400, 900] {
+                        try await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
+                        do {
+                            guard let client = self.client else {
+                                throw NSError(
+                                    domain: "Gateway",
+                                    code: 0,
+                                    userInfo: [NSLocalizedDescriptionKey: "gateway not configured"])
+                            }
+                            return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
+                        } catch {
+                            lastError = error
+                        }
+                    }
+                }
+
                 throw lastError
             case .remote:
                 let nsError = error as NSError
@@ -244,9 +265,9 @@ actor GatewayConnection {
         return trimmed.isEmpty ? nil : trimmed
     }
 
-    private func sessionDefaultString(_ defaults: [String: AnyCodable]?, key: String) -> String {
-        (defaults?[key]?.stringValue ?? "")
-            .trimmingCharacters(in: CharacterSet.whitespacesAndNewlines)
+    private func sessionDefaultString(_ defaults: [String: ClawdbotProtocol.AnyCodable]?, key: String) -> String {
+        let raw = defaults?[key]?.value as? String
+        return (raw ?? "").trimmingCharacters(in: CharacterSet.whitespacesAndNewlines)
     }
 
     func cachedMainSessionKey() -> String? {

apps/macos/Sources/Clawdbot/GatewayEndpointStore.swift

@@ -165,7 +165,7 @@ actor GatewayEndpointStore {
             }
             return trimmed
         }
-        
+
         if let configToken = self.resolveConfigToken(isRemote: isRemote, root: root),
            !configToken.isEmpty
         {
@@ -177,7 +177,7 @@ actor GatewayEndpointStore {
         {
             return token
         }
-        
+
         return nil
     }
 
@@ -469,6 +469,35 @@ actor GatewayEndpointStore {
         }
     }
 
+    func maybeFallbackToTailnet(from currentURL: URL) async -> GatewayConnection.Config? {
+        let mode = await self.deps.mode()
+        guard mode == .local else { return nil }
+
+        let root = ClawdbotConfigFile.loadDict()
+        let bind = GatewayEndpointStore.resolveGatewayBindMode(
+            root: root,
+            env: ProcessInfo.processInfo.environment)
+        guard bind == "auto" else { return nil }
+
+        let currentHost = currentURL.host?.lowercased() ?? ""
+        guard currentHost == "127.0.0.1" || currentHost == "localhost" else { return nil }
+
+        let tailscaleIP = await MainActor.run { TailscaleService.shared.tailscaleIP }
+        guard let tailscaleIP, !tailscaleIP.isEmpty else { return nil }
+
+        let scheme = GatewayEndpointStore.resolveGatewayScheme(
+            root: root,
+            env: ProcessInfo.processInfo.environment)
+        let port = self.deps.localPort()
+        let token = self.deps.token()
+        let password = self.deps.password()
+        let url = URL(string: "\(scheme)://\(tailscaleIP):\(port)")!
+
+        self.logger.info("auto bind fallback to tailnet host=\(tailscaleIP, privacy: .public)")
+        self.setState(.ready(mode: .local, url: url, token: token, password: password))
+        return (url, token, password)
+    }
+
     private static func resolveGatewayBindMode(
         root: [String: Any],
         env: [String: String]) -> String?
@@ -524,8 +553,10 @@ actor GatewayEndpointStore {
         tailscaleIP: String?) -> String
     {
         switch bindMode {
-        case "tailnet", "auto":
+        case "tailnet":
             tailscaleIP ?? "127.0.0.1"
+        case "auto":
+            "127.0.0.1"
         case "custom":
             customBindHost ?? "127.0.0.1"
         default:

apps/macos/Sources/Clawdbot/OnboardingWizard.swift

@@ -217,7 +217,7 @@ final class OnboardingWizardModel {
 struct OnboardingWizardStepView: View {
     let step: WizardStep
     let isSubmitting: Bool
-    let onSubmit: (AnyCodable?) -> Void
+    let onStepSubmit: (AnyCodable?) -> Void
 
     @State private var textValue: String
     @State private var confirmValue: Bool
@@ -229,7 +229,7 @@ struct OnboardingWizardStepView: View {
     init(step: WizardStep, isSubmitting: Bool, onSubmit: @escaping (AnyCodable?) -> Void) {
         self.step = step
         self.isSubmitting = isSubmitting
-        self.onSubmit = onSubmit
+        self.onStepSubmit = onSubmit
         let options = parseWizardOptions(step.options).enumerated().map { index, option in
             WizardOptionItem(index: index, option: option)
         }
@@ -379,27 +379,27 @@ struct OnboardingWizardStepView: View {
     private func submit() {
         switch wizardStepType(self.step) {
         case "note", "progress":
-            self.onSubmit(nil)
+            self.onStepSubmit(nil)
         case "text":
-            self.onSubmit(AnyCodable(self.textValue))
+            self.onStepSubmit(AnyCodable(self.textValue))
         case "confirm":
-            self.onSubmit(AnyCodable(self.confirmValue))
+            self.onStepSubmit(AnyCodable(self.confirmValue))
         case "select":
             guard self.optionItems.indices.contains(self.selectedIndex) else {
-                self.onSubmit(nil)
+                self.onStepSubmit(nil)
                 return
             }
             let option = self.optionItems[self.selectedIndex].option
-            self.onSubmit(bridgeToLocal(option.value) ?? AnyCodable(option.label))
+            self.onStepSubmit(bridgeToLocal(option.value) ?? AnyCodable(option.label))
         case "multiselect":
             let values = self.optionItems
                 .filter { self.selectedIndices.contains($0.index) }
                 .map { bridgeToLocal($0.option.value) ?? AnyCodable($0.option.label) }
-            self.onSubmit(AnyCodable(values))
+            self.onStepSubmit(AnyCodable(values))
         case "action":
-            self.onSubmit(AnyCodable(true))
+            self.onStepSubmit(AnyCodable(true))
         default:
-            self.onSubmit(nil)
+            self.onStepSubmit(nil)
         }
     }
 }

apps/macos/Sources/Clawdbot/Resources/Info.plist

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.1.11-4</string>
+    <string>2026.1.20</string>
     <key>CFBundleVersion</key>
-    <string>202601113</string>
+    <string>202601200</string>
     <key>CFBundleIconFile</key>
     <string>Clawdbot</string>
     <key>CFBundleURLTypes</key>

apps/macos/Sources/ClawdbotDiscovery/WideAreaGatewayDiscovery.swift

@@ -52,7 +52,7 @@ enum WideAreaGatewayDiscovery {
 
         let domain = ClawdbotBonjour.wideAreaGatewayServiceDomain
         let domainTrimmed = domain.trimmingCharacters(in: CharacterSet(charactersIn: "."))
-        let probeName = "_clawdbot-gateway._tcp.\(domainTrimmed)"
+        let probeName = "_clawdbot-gw._tcp.\(domainTrimmed)"
         guard let ptrLines = context.dig(
             ["+short", "+time=1", "+tries=1", "@\(nameserver)", probeName, "PTR"],
             min(defaultTimeoutSeconds, remaining()))?.split(whereSeparator: \.isNewline),
@@ -66,7 +66,7 @@ enum WideAreaGatewayDiscovery {
             let ptr = raw.trimmingCharacters(in: .whitespacesAndNewlines)
             if ptr.isEmpty { continue }
             let ptrName = ptr.hasSuffix(".") ? String(ptr.dropLast()) : ptr
-            let suffix = "._clawdbot-gateway._tcp.\(domainTrimmed)"
+            let suffix = "._clawdbot-gw._tcp.\(domainTrimmed)"
             let rawInstanceName = ptrName.hasSuffix(suffix)
                 ? String(ptrName.dropLast(suffix.count))
                 : ptrName
@@ -156,7 +156,7 @@ enum WideAreaGatewayDiscovery {
     {
         let domain = ClawdbotBonjour.wideAreaGatewayServiceDomain
         let domainTrimmed = domain.trimmingCharacters(in: CharacterSet(charactersIn: "."))
-        let probeName = "_clawdbot-gateway._tcp.\(domainTrimmed)"
+        let probeName = "_clawdbot-gw._tcp.\(domainTrimmed)"
 
         let ips = candidates
         candidates.removeAll(keepingCapacity: true)

apps/macos/Sources/ClawdbotDiscoveryCLI/main.swift

@@ -1,150 +0,0 @@
-import ClawdbotDiscovery
-import Foundation
-
-struct DiscoveryOptions {
-    var timeoutMs: Int = 2000
-    var json: Bool = false
-    var includeLocal: Bool = false
-    var help: Bool = false
-
-    static func parse(_ args: [String]) -> DiscoveryOptions {
-        var opts = DiscoveryOptions()
-        var i = 0
-        while i < args.count {
-            let arg = args[i]
-            switch arg {
-            case "-h", "--help":
-                opts.help = true
-            case "--json":
-                opts.json = true
-            case "--include-local":
-                opts.includeLocal = true
-            case "--timeout":
-                let next = (i + 1 < args.count) ? args[i + 1] : nil
-                if let next, let parsed = Int(next.trimmingCharacters(in: .whitespacesAndNewlines)) {
-                    opts.timeoutMs = max(100, parsed)
-                    i += 1
-                }
-            default:
-                break
-            }
-            i += 1
-        }
-        return opts
-    }
-}
-
-struct DiscoveryOutput: Encodable {
-    struct Gateway: Encodable {
-        var displayName: String
-        var lanHost: String?
-        var tailnetDns: String?
-        var sshPort: Int
-        var gatewayPort: Int?
-        var cliPath: String?
-        var stableID: String
-        var debugID: String
-        var isLocal: Bool
-    }
-
-    var status: String
-    var timeoutMs: Int
-    var includeLocal: Bool
-    var count: Int
-    var gateways: [Gateway]
-}
-
-@main
-struct ClawdbotDiscoveryCLI {
-    static func main() async {
-        let opts = DiscoveryOptions.parse(Array(CommandLine.arguments.dropFirst()))
-        if opts.help {
-            print("""
-            clawdbot-mac-discovery
-
-            Usage:
-              clawdbot-mac-discovery [--timeout <ms>] [--json] [--include-local]
-
-            Options:
-              --timeout <ms>     Discovery window in milliseconds (default: 2000)
-              --json             Emit JSON
-              --include-local    Include gateways considered local
-              -h, --help         Show help
-            """)
-            return
-        }
-
-        let displayName = Host.current().localizedName ?? ProcessInfo.processInfo.hostName
-        let model = GatewayDiscoveryModel(
-            localDisplayName: displayName,
-            filterLocalGateways: !opts.includeLocal)
-
-        await MainActor.run {
-            model.start()
-        }
-
-        let nanos = UInt64(max(100, opts.timeoutMs)) * 1_000_000
-        try? await Task.sleep(nanoseconds: nanos)
-
-        let gateways = await MainActor.run { model.gateways }
-        let status = await MainActor.run { model.statusText }
-
-        await MainActor.run {
-            model.stop()
-        }
-
-        if opts.json {
-            let payload = DiscoveryOutput(
-                status: status,
-                timeoutMs: opts.timeoutMs,
-                includeLocal: opts.includeLocal,
-                count: gateways.count,
-                gateways: gateways.map {
-                    DiscoveryOutput.Gateway(
-                        displayName: $0.displayName,
-                        lanHost: $0.lanHost,
-                        tailnetDns: $0.tailnetDns,
-                        sshPort: $0.sshPort,
-                        gatewayPort: $0.gatewayPort,
-                        cliPath: $0.cliPath,
-                        stableID: $0.stableID,
-                        debugID: $0.debugID,
-                        isLocal: $0.isLocal)
-                })
-            let encoder = JSONEncoder()
-            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-            if let data = try? encoder.encode(payload),
-               let json = String(data: data, encoding: .utf8)
-            {
-                print(json)
-            } else {
-                print("{\"error\":\"failed to encode JSON\"}")
-            }
-            return
-        }
-
-        print("Gateway Discovery (macOS NWBrowser)")
-        print("Status: \(status)")
-        print("Found \(gateways.count) gateway(s)\(opts.includeLocal ? "" : " (local filtered)")")
-        if gateways.isEmpty { return }
-
-        for gateway in gateways {
-            let hosts = [gateway.tailnetDns, gateway.lanHost]
-                .compactMap { $0?.trimmingCharacters(in: .whitespacesAndNewlines) }
-                .filter { !$0.isEmpty }
-                .joined(separator: ", ")
-            print("- \(gateway.displayName)")
-            print("  hosts: \(hosts.isEmpty ? "(none)" : hosts)")
-            print("  ssh: \(gateway.sshPort)")
-            if let port = gateway.gatewayPort {
-                print("  gatewayPort: \(port)")
-            }
-            if let cliPath = gateway.cliPath {
-                print("  cliPath: \(cliPath)")
-            }
-            print("  isLocal: \(gateway.isLocal)")
-            print("  stableID: \(gateway.stableID)")
-            print("  debugID: \(gateway.debugID)")
-        }
-    }
-}

apps/macos/Sources/ClawdbotIPC/IPC.swift

@@ -408,8 +408,7 @@ extension Request: Codable {
 }
 
 // Shared transport settings
-public let controlSocketPath =
-    FileManager()
-        .homeDirectoryForCurrentUser
-        .appendingPathComponent("Library/Application Support/clawdbot/control.sock")
-        .path
+public let controlSocketPath = FileManager()
+    .homeDirectoryForCurrentUser
+    .appendingPathComponent("Library/Application Support/clawdbot/control.sock")
+    .path

apps/macos/Sources/ClawdbotMacCLI/ConnectCommand.swift

@@ -0,0 +1,306 @@
+import ClawdbotKit
+import ClawdbotProtocol
+import Foundation
+
+struct ConnectOptions {
+    var url: String?
+    var token: String?
+    var password: String?
+    var mode: String?
+    var timeoutMs: Int = 15_000
+    var json: Bool = false
+    var probe: Bool = false
+    var clientId: String = "clawdbot-macos"
+    var clientMode: String = "ui"
+    var displayName: String?
+    var role: String = "operator"
+    var scopes: [String] = ["operator.admin", "operator.approvals", "operator.pairing"]
+    var help: Bool = false
+
+    static func parse(_ args: [String]) -> ConnectOptions {
+        var opts = ConnectOptions()
+        var i = 0
+        while i < args.count {
+            let arg = args[i]
+            switch arg {
+            case "-h", "--help":
+                opts.help = true
+            case "--json":
+                opts.json = true
+            case "--probe":
+                opts.probe = true
+            case "--url":
+                opts.url = self.nextValue(args, index: &i)
+            case "--token":
+                opts.token = self.nextValue(args, index: &i)
+            case "--password":
+                opts.password = self.nextValue(args, index: &i)
+            case "--mode":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.mode = value
+                }
+            case "--timeout":
+                if let raw = self.nextValue(args, index: &i),
+                   let parsed = Int(raw.trimmingCharacters(in: .whitespacesAndNewlines))
+                {
+                    opts.timeoutMs = max(250, parsed)
+                }
+            case "--client-id":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.clientId = value
+                }
+            case "--client-mode":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.clientMode = value
+                }
+            case "--display-name":
+                opts.displayName = self.nextValue(args, index: &i)
+            case "--role":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.role = value
+                }
+            case "--scopes":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.scopes = value.split(separator: ",").map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                        .filter { !$0.isEmpty }
+                }
+            default:
+                break
+            }
+            i += 1
+        }
+        return opts
+    }
+
+    private static func nextValue(_ args: [String], index: inout Int) -> String? {
+        guard index + 1 < args.count else { return nil }
+        index += 1
+        return args[index].trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}
+
+struct ConnectOutput: Encodable {
+    var status: String
+    var url: String
+    var mode: String
+    var role: String
+    var clientId: String
+    var clientMode: String
+    var scopes: [String]
+    var snapshot: HelloOk?
+    var health: ProtoAnyCodable?
+    var error: String?
+}
+
+actor SnapshotStore {
+    private var value: HelloOk?
+
+    func set(_ snapshot: HelloOk) {
+        self.value = snapshot
+    }
+
+    func get() -> HelloOk? {
+        self.value
+    }
+}
+
+func runConnect(_ args: [String]) async {
+    let opts = ConnectOptions.parse(args)
+    if opts.help {
+        print("""
+        clawdbot-mac connect
+
+        Usage:
+          clawdbot-mac connect [--url <ws://host:port>] [--token <token>] [--password <password>]
+                               [--mode <local|remote>] [--timeout <ms>] [--probe] [--json]
+                               [--client-id <id>] [--client-mode <mode>] [--display-name <name>]
+                               [--role <role>] [--scopes <a,b,c>]
+
+        Options:
+          --url <url>        Gateway WebSocket URL (overrides config)
+          --token <token>    Gateway token (if required)
+          --password <pw>    Gateway password (if required)
+          --mode <mode>      Resolve from config: local|remote (default: config or local)
+          --timeout <ms>     Request timeout (default: 15000)
+          --probe            Force a fresh health probe
+          --json             Emit JSON
+          --client-id <id>   Override client id (default: clawdbot-macos)
+          --client-mode <m>  Override client mode (default: ui)
+          --display-name <n> Override display name
+          --role <role>      Override role (default: operator)
+          --scopes <a,b,c>   Override scopes list
+          -h, --help         Show help
+        """)
+        return
+    }
+
+    let config = loadGatewayConfig()
+    do {
+        let endpoint = try resolveGatewayEndpoint(opts: opts, config: config)
+        let displayName = opts.displayName ?? Host.current().localizedName ?? "Clawdbot macOS Debug CLI"
+        let connectOptions = GatewayConnectOptions(
+            role: opts.role,
+            scopes: opts.scopes,
+            caps: [],
+            commands: [],
+            permissions: [:],
+            clientId: opts.clientId,
+            clientMode: opts.clientMode,
+            clientDisplayName: displayName)
+
+        let snapshotStore = SnapshotStore()
+        let channel = GatewayChannelActor(
+            url: endpoint.url,
+            token: endpoint.token,
+            password: endpoint.password,
+            pushHandler: { push in
+                if case let .snapshot(ok) = push {
+                    await snapshotStore.set(ok)
+                }
+            },
+            connectOptions: connectOptions)
+
+        let params: [String: KitAnyCodable]? = opts.probe ? ["probe": KitAnyCodable(true)] : nil
+        let data = try await channel.request(
+            method: "health",
+            params: params,
+            timeoutMs: Double(opts.timeoutMs))
+        let health = try? JSONDecoder().decode(ProtoAnyCodable.self, from: data)
+        let snapshot = await snapshotStore.get()
+        await channel.shutdown()
+
+        let output = ConnectOutput(
+            status: "ok",
+            url: endpoint.url.absoluteString,
+            mode: endpoint.mode,
+            role: opts.role,
+            clientId: opts.clientId,
+            clientMode: opts.clientMode,
+            scopes: opts.scopes,
+            snapshot: snapshot,
+            health: health,
+            error: nil)
+        printConnectOutput(output, json: opts.json)
+    } catch {
+        let endpoint = bestEffortEndpoint(opts: opts, config: config)
+        let fallbackMode = (opts.mode ?? config.mode ?? "local").lowercased()
+        let output = ConnectOutput(
+            status: "error",
+            url: endpoint?.url.absoluteString ?? "unknown",
+            mode: endpoint?.mode ?? fallbackMode,
+            role: opts.role,
+            clientId: opts.clientId,
+            clientMode: opts.clientMode,
+            scopes: opts.scopes,
+            snapshot: nil,
+            health: nil,
+            error: error.localizedDescription)
+        printConnectOutput(output, json: opts.json)
+        exit(1)
+    }
+}
+
+private func printConnectOutput(_ output: ConnectOutput, json: Bool) {
+    if json {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        if let data = try? encoder.encode(output),
+           let text = String(data: data, encoding: .utf8)
+        {
+            print(text)
+        } else {
+            print("{\"error\":\"failed to encode JSON\"}")
+        }
+        return
+    }
+
+    print("Clawdbot macOS Gateway Connect")
+    print("Status: \(output.status)")
+    print("URL: \(output.url)")
+    print("Mode: \(output.mode)")
+    print("Client: \(output.clientId) (\(output.clientMode))")
+    print("Role: \(output.role)")
+    print("Scopes: \(output.scopes.joined(separator: ", "))")
+    if let snapshot = output.snapshot {
+        print("Protocol: \(snapshot._protocol)")
+        if let version = snapshot.server["version"]?.value as? String {
+            print("Server: \(version)")
+        }
+    }
+    if let health = output.health,
+       let ok = (health.value as? [String: ProtoAnyCodable])?["ok"]?.value as? Bool
+    {
+        print("Health: \(ok ? "ok" : "error")")
+    } else if output.health != nil {
+        print("Health: received")
+    }
+    if let error = output.error {
+        print("Error: \(error)")
+    }
+}
+
+private func resolveGatewayEndpoint(opts: ConnectOptions, config: GatewayConfig) throws -> GatewayEndpoint {
+    let resolvedMode = (opts.mode ?? config.mode ?? "local").lowercased()
+    if let raw = opts.url, !raw.isEmpty {
+        guard let url = URL(string: raw) else {
+            throw NSError(domain: "Gateway", code: 1, userInfo: [NSLocalizedDescriptionKey: "invalid url: \(raw)"])
+        }
+        return GatewayEndpoint(
+            url: url,
+            token: resolvedToken(opts: opts, mode: resolvedMode, config: config),
+            password: resolvedPassword(opts: opts, mode: resolvedMode, config: config),
+            mode: resolvedMode)
+    }
+
+    if resolvedMode == "remote" {
+        guard let raw = config.remoteUrl?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !raw.isEmpty else {
+            throw NSError(domain: "Gateway", code: 1, userInfo: [NSLocalizedDescriptionKey: "gateway.remote.url is missing"])
+        }
+        guard let url = URL(string: raw) else {
+            throw NSError(domain: "Gateway", code: 1, userInfo: [NSLocalizedDescriptionKey: "invalid url: \(raw)"])
+        }
+        return GatewayEndpoint(
+            url: url,
+            token: resolvedToken(opts: opts, mode: resolvedMode, config: config),
+            password: resolvedPassword(opts: opts, mode: resolvedMode, config: config),
+            mode: resolvedMode)
+    }
+
+    let port = config.port ?? 18789
+    let host = "127.0.0.1"
+    guard let url = URL(string: "ws://\(host):\(port)") else {
+        throw NSError(domain: "Gateway", code: 1, userInfo: [NSLocalizedDescriptionKey: "invalid url: ws://\(host):\(port)"])
+    }
+    return GatewayEndpoint(
+        url: url,
+        token: resolvedToken(opts: opts, mode: resolvedMode, config: config),
+        password: resolvedPassword(opts: opts, mode: resolvedMode, config: config),
+        mode: resolvedMode)
+}
+
+private func bestEffortEndpoint(opts: ConnectOptions, config: GatewayConfig) -> GatewayEndpoint? {
+    return try? resolveGatewayEndpoint(opts: opts, config: config)
+}
+
+private func resolvedToken(opts: ConnectOptions, mode: String, config: GatewayConfig) -> String? {
+    if let token = opts.token, !token.isEmpty { return token }
+    if let token = ProcessInfo.processInfo.environment["CLAWDBOT_GATEWAY_TOKEN"], !token.isEmpty {
+        return token
+    }
+    if mode == "remote" {
+        return config.remoteToken
+    }
+    return config.token
+}
+
+private func resolvedPassword(opts: ConnectOptions, mode: String, config: GatewayConfig) -> String? {
+    if let password = opts.password, !password.isEmpty { return password }
+    if let password = ProcessInfo.processInfo.environment["CLAWDBOT_GATEWAY_PASSWORD"], !password.isEmpty {
+        return password
+    }
+    if mode == "remote" {
+        return config.remotePassword
+    }
+    return config.password
+}

apps/macos/Sources/ClawdbotMacCLI/DiscoverCommand.swift

@@ -0,0 +1,149 @@
+import ClawdbotDiscovery
+import Foundation
+
+struct DiscoveryOptions {
+    var timeoutMs: Int = 2000
+    var json: Bool = false
+    var includeLocal: Bool = false
+    var help: Bool = false
+
+    static func parse(_ args: [String]) -> DiscoveryOptions {
+        var opts = DiscoveryOptions()
+        var i = 0
+        while i < args.count {
+            let arg = args[i]
+            switch arg {
+            case "-h", "--help":
+                opts.help = true
+            case "--json":
+                opts.json = true
+            case "--include-local":
+                opts.includeLocal = true
+            case "--timeout":
+                let next = (i + 1 < args.count) ? args[i + 1] : nil
+                if let next, let parsed = Int(next.trimmingCharacters(in: .whitespacesAndNewlines)) {
+                    opts.timeoutMs = max(100, parsed)
+                    i += 1
+                }
+            default:
+                break
+            }
+            i += 1
+        }
+        return opts
+    }
+}
+
+struct DiscoveryOutput: Encodable {
+    struct Gateway: Encodable {
+        var displayName: String
+        var lanHost: String?
+        var tailnetDns: String?
+        var sshPort: Int
+        var gatewayPort: Int?
+        var cliPath: String?
+        var stableID: String
+        var debugID: String
+        var isLocal: Bool
+    }
+
+    var status: String
+    var timeoutMs: Int
+    var includeLocal: Bool
+    var count: Int
+    var gateways: [Gateway]
+}
+
+func runDiscover(_ args: [String]) async {
+    let opts = DiscoveryOptions.parse(args)
+    if opts.help {
+        print("""
+        clawdbot-mac discover
+
+        Usage:
+          clawdbot-mac discover [--timeout <ms>] [--json] [--include-local]
+
+        Options:
+          --timeout <ms>     Discovery window in milliseconds (default: 2000)
+          --json             Emit JSON
+          --include-local    Include gateways considered local
+          -h, --help         Show help
+        """)
+        return
+    }
+
+    let displayName = Host.current().localizedName ?? ProcessInfo.processInfo.hostName
+    let model = await MainActor.run {
+        GatewayDiscoveryModel(
+            localDisplayName: displayName,
+            filterLocalGateways: !opts.includeLocal)
+    }
+
+    await MainActor.run {
+        model.start()
+    }
+
+    let nanos = UInt64(max(100, opts.timeoutMs)) * 1_000_000
+    try? await Task.sleep(nanoseconds: nanos)
+
+    let gateways = await MainActor.run { model.gateways }
+    let status = await MainActor.run { model.statusText }
+
+    await MainActor.run {
+        model.stop()
+    }
+
+    if opts.json {
+        let payload = DiscoveryOutput(
+            status: status,
+            timeoutMs: opts.timeoutMs,
+            includeLocal: opts.includeLocal,
+            count: gateways.count,
+            gateways: gateways.map {
+                DiscoveryOutput.Gateway(
+                    displayName: $0.displayName,
+                    lanHost: $0.lanHost,
+                    tailnetDns: $0.tailnetDns,
+                    sshPort: $0.sshPort,
+                    gatewayPort: $0.gatewayPort,
+                    cliPath: $0.cliPath,
+                    stableID: $0.stableID,
+                    debugID: $0.debugID,
+                    isLocal: $0.isLocal)
+            })
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        if let data = try? encoder.encode(payload),
+           let json = String(data: data, encoding: .utf8)
+        {
+            print(json)
+        } else {
+            print("{\"error\":\"failed to encode JSON\"}")
+        }
+        return
+    }
+
+    print("Gateway Discovery (macOS NWBrowser)")
+    print("Status: \(status)")
+    print("Found \(gateways.count) gateway(s)\(opts.includeLocal ? "" : " (local filtered)")")
+    if gateways.isEmpty { return }
+
+    for gateway in gateways {
+        let hosts = [gateway.tailnetDns, gateway.lanHost]
+            .compactMap { $0?.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .joined(separator: ", ")
+        print("- \(gateway.displayName)")
+        print("  hosts: \(hosts.isEmpty ? "(none)" : hosts)")
+        print("  ssh: \(gateway.sshPort)")
+        if let port = gateway.gatewayPort {
+            print("  gatewayPort: \(port)")
+        }
+        if let cliPath = gateway.cliPath {
+            print("  cliPath: \(cliPath)")
+        }
+        print("  isLocal: \(gateway.isLocal)")
+        print("  stableID: \(gateway.stableID)")
+        print("  debugID: \(gateway.debugID)")
+    }
+}

apps/macos/Sources/ClawdbotMacCLI/EntryPoint.swift

@@ -0,0 +1,56 @@
+import Foundation
+
+private struct RootCommand {
+    var name: String
+    var args: [String]
+}
+
+@main
+struct ClawdbotMacCLI {
+    static func main() async {
+        let args = Array(CommandLine.arguments.dropFirst())
+        let command = parseRootCommand(args)
+        switch command?.name {
+        case nil:
+            printUsage()
+        case "-h", "--help", "help":
+            printUsage()
+        case "connect":
+            await runConnect(command?.args ?? [])
+        case "discover":
+            await runDiscover(command?.args ?? [])
+        case "wizard":
+            await runWizardCommand(command?.args ?? [])
+        default:
+            fputs("clawdbot-mac: unknown command\n", stderr)
+            printUsage()
+            exit(1)
+        }
+    }
+}
+
+private func parseRootCommand(_ args: [String]) -> RootCommand? {
+    guard let first = args.first else { return nil }
+    return RootCommand(name: first, args: Array(args.dropFirst()))
+}
+
+private func printUsage() {
+    print("""
+    clawdbot-mac
+
+    Usage:
+      clawdbot-mac connect [--url <ws://host:port>] [--token <token>] [--password <password>]
+                           [--mode <local|remote>] [--timeout <ms>] [--probe] [--json]
+                           [--client-id <id>] [--client-mode <mode>] [--display-name <name>]
+                           [--role <role>] [--scopes <a,b,c>]
+      clawdbot-mac discover [--timeout <ms>] [--json] [--include-local]
+      clawdbot-mac wizard [--url <ws://host:port>] [--token <token>] [--password <password>]
+                          [--mode <local|remote>] [--workspace <path>] [--json]
+
+    Examples:
+      clawdbot-mac connect
+      clawdbot-mac connect --url ws://127.0.0.1:18789 --json
+      clawdbot-mac discover --timeout 3000 --json
+      clawdbot-mac wizard --mode local
+    """)
+}

apps/macos/Sources/ClawdbotMacCLI/GatewayConfig.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+struct GatewayConfig {
+    var mode: String?
+    var bind: String?
+    var port: Int?
+    var remoteUrl: String?
+    var token: String?
+    var password: String?
+    var remoteToken: String?
+    var remotePassword: String?
+}
+
+struct GatewayEndpoint {
+    let url: URL
+    let token: String?
+    let password: String?
+    let mode: String
+}
+
+func loadGatewayConfig() -> GatewayConfig {
+    let url = FileManager().homeDirectoryForCurrentUser
+        .appendingPathComponent(".clawdbot")
+        .appendingPathComponent("clawdbot.json")
+    guard let data = try? Data(contentsOf: url) else { return GatewayConfig() }
+    guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+        return GatewayConfig()
+    }
+
+    var cfg = GatewayConfig()
+    if let gateway = json["gateway"] as? [String: Any] {
+        cfg.mode = gateway["mode"] as? String
+        cfg.bind = gateway["bind"] as? String
+        cfg.port = gateway["port"] as? Int ?? parseInt(gateway["port"])
+
+        if let auth = gateway["auth"] as? [String: Any] {
+            cfg.token = auth["token"] as? String
+            cfg.password = auth["password"] as? String
+        }
+        if let remote = gateway["remote"] as? [String: Any] {
+            cfg.remoteUrl = remote["url"] as? String
+            cfg.remoteToken = remote["token"] as? String
+            cfg.remotePassword = remote["password"] as? String
+        }
+    }
+    return cfg
+}
+
+func parseInt(_ value: Any?) -> Int? {
+    switch value {
+    case let number as Int:
+        number
+    case let number as Double:
+        Int(number)
+    case let raw as String:
+        Int(raw.trimmingCharacters(in: .whitespacesAndNewlines))
+    default:
+        nil
+    }
+}

apps/macos/Sources/ClawdbotMacCLI/TypeAliases.swift

@@ -0,0 +1,5 @@
+import ClawdbotKit
+import ClawdbotProtocol
+
+typealias ProtoAnyCodable = ClawdbotProtocol.AnyCodable
+typealias KitAnyCodable = ClawdbotKit.AnyCodable

apps/macos/Sources/ClawdbotMacCLI/WizardCommand.swift

@@ -3,8 +3,6 @@ import ClawdbotProtocol
 import Darwin
 import Foundation
 
-private typealias ProtoAnyCodable = ClawdbotProtocol.AnyCodable
-
 struct WizardCliOptions {
     var url: String?
     var token: String?
@@ -51,17 +49,6 @@ struct WizardCliOptions {
     }
 }
 
-struct GatewayConfig {
-    var mode: String?
-    var bind: String?
-    var port: Int?
-    var remoteUrl: String?
-    var token: String?
-    var password: String?
-    var remoteToken: String?
-    var remotePassword: String?
-}
-
 enum WizardCliError: Error, CustomStringConvertible {
     case invalidUrl(String)
     case missingRemoteUrl
@@ -80,68 +67,56 @@ enum WizardCliError: Error, CustomStringConvertible {
     }
 }
 
-@main
-struct ClawdbotWizardCLI {
-    static func main() async {
-        let opts = WizardCliOptions.parse(Array(CommandLine.arguments.dropFirst()))
-        if opts.help {
-            printUsage()
-            return
-        }
+func runWizardCommand(_ args: [String]) async {
+    let opts = WizardCliOptions.parse(args)
+    if opts.help {
+        print("""
+        clawdbot-mac wizard
 
-        let config = loadGatewayConfig()
-        do {
-            guard isatty(STDIN_FILENO) != 0 else {
-                throw WizardCliError.gatewayError("Wizard requires an interactive TTY.")
-            }
-            let endpoint = try resolveGatewayEndpoint(opts: opts, config: config)
-            let client = GatewayWizardClient(
-                url: endpoint.url,
-                token: endpoint.token,
-                password: endpoint.password,
-                json: opts.json)
-            try await client.connect()
-            defer { Task { await client.close() } }
-            try await runWizard(client: client, opts: opts)
-        } catch {
-            fputs("wizard: \(error)\n", stderr)
-            exit(1)
+        Usage:
+          clawdbot-mac wizard [--url <ws://host:port>] [--token <token>] [--password <password>]
+                              [--mode <local|remote>] [--workspace <path>] [--json]
+
+        Options:
+          --url <url>        Gateway WebSocket URL (overrides config)
+          --token <token>    Gateway token (if required)
+          --password <pw>    Gateway password (if required)
+          --mode <mode>      Wizard mode (local|remote). Default: local
+          --workspace <path> Wizard workspace override
+          --json             Print raw wizard responses
+          -h, --help         Show help
+        """)
+        return
+    }
+
+    let config = loadGatewayConfig()
+    do {
+        guard isatty(STDIN_FILENO) != 0 else {
+            throw WizardCliError.gatewayError("Wizard requires an interactive TTY.")
         }
+        let endpoint = try resolveWizardGatewayEndpoint(opts: opts, config: config)
+        let client = GatewayWizardClient(
+            url: endpoint.url,
+            token: endpoint.token,
+            password: endpoint.password,
+            json: opts.json)
+        try await client.connect()
+        defer { Task { await client.close() } }
+        try await runWizard(client: client, opts: opts)
+    } catch {
+        fputs("wizard: \(error)\n", stderr)
+        exit(1)
     }
 }
 
-private struct GatewayEndpoint {
-    let url: URL
-    let token: String?
-    let password: String?
-}
-
-private func printUsage() {
-    print("""
-    clawdbot-mac-wizard
-
-    Usage:
-      clawdbot-mac-wizard [--url <ws://host:port>] [--token <token>] [--password <password>]
-                          [--mode <local|remote>] [--workspace <path>] [--json]
-
-    Options:
-      --url <url>        Gateway WebSocket URL (overrides config)
-      --token <token>    Gateway token (if required)
-      --password <pw>    Gateway password (if required)
-      --mode <mode>      Wizard mode (local|remote). Default: local
-      --workspace <path> Wizard workspace override
-      --json             Print raw wizard responses
-      -h, --help         Show help
-    """)
-}
-
-private func resolveGatewayEndpoint(opts: WizardCliOptions, config: GatewayConfig) throws -> GatewayEndpoint {
+private func resolveWizardGatewayEndpoint(opts: WizardCliOptions, config: GatewayConfig) throws -> GatewayEndpoint {
     if let raw = opts.url, !raw.isEmpty {
         guard let url = URL(string: raw) else { throw WizardCliError.invalidUrl(raw) }
         return GatewayEndpoint(
             url: url,
             token: resolvedToken(opts: opts, config: config),
-            password: resolvedPassword(opts: opts, config: config))
+            password: resolvedPassword(opts: opts, config: config),
+            mode: (config.mode ?? "local").lowercased())
     }
 
     let mode = (config.mode ?? "local").lowercased()
@@ -153,7 +128,8 @@ private func resolveGatewayEndpoint(opts: WizardCliOptions, config: GatewayConfi
         return GatewayEndpoint(
             url: url,
             token: resolvedToken(opts: opts, config: config),
-            password: resolvedPassword(opts: opts, config: config))
+            password: resolvedPassword(opts: opts, config: config),
+            mode: mode)
     }
 
     let port = config.port ?? 18789
@@ -164,7 +140,8 @@ private func resolveGatewayEndpoint(opts: WizardCliOptions, config: GatewayConfi
     return GatewayEndpoint(
         url: url,
         token: resolvedToken(opts: opts, config: config),
-        password: resolvedPassword(opts: opts, config: config))
+        password: resolvedPassword(opts: opts, config: config),
+        mode: mode)
 }
 
 private func resolvedToken(opts: WizardCliOptions, config: GatewayConfig) -> String? {
@@ -189,47 +166,6 @@ private func resolvedPassword(opts: WizardCliOptions, config: GatewayConfig) ->
     return config.password
 }
 
-private func loadGatewayConfig() -> GatewayConfig {
-    let url = FileManager().homeDirectoryForCurrentUser
-        .appendingPathComponent(".clawdbot")
-        .appendingPathComponent("clawdbot.json")
-    guard let data = try? Data(contentsOf: url) else { return GatewayConfig() }
-    guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
-        return GatewayConfig()
-    }
-
-    var cfg = GatewayConfig()
-    if let gateway = json["gateway"] as? [String: Any] {
-        cfg.mode = gateway["mode"] as? String
-        cfg.bind = gateway["bind"] as? String
-        cfg.port = gateway["port"] as? Int ?? parseInt(gateway["port"])
-
-        if let auth = gateway["auth"] as? [String: Any] {
-            cfg.token = auth["token"] as? String
-            cfg.password = auth["password"] as? String
-        }
-        if let remote = gateway["remote"] as? [String: Any] {
-            cfg.remoteUrl = remote["url"] as? String
-            cfg.remoteToken = remote["token"] as? String
-            cfg.remotePassword = remote["password"] as? String
-        }
-    }
-    return cfg
-}
-
-private func parseInt(_ value: Any?) -> Int? {
-    switch value {
-    case let number as Int:
-        number
-    case let number as Double:
-        Int(number)
-    case let raw as String:
-        Int(raw.trimmingCharacters(in: .whitespacesAndNewlines))
-    default:
-        nil
-    }
-}
-
 actor GatewayWizardClient {
     private enum ConnectChallengeError: Error {
         case timeout
@@ -365,7 +301,8 @@ actor GatewayWizardClient {
         }
         let payload = payloadParts.joined(separator: "|")
         if let signature = DeviceIdentityStore.signPayload(payload, identity: identity),
-           let publicKey = DeviceIdentityStore.publicKeyBase64Url(identity) {
+           let publicKey = DeviceIdentityStore.publicKeyBase64Url(identity)
+        {
             var device: [String: ProtoAnyCodable] = [
                 "id": ProtoAnyCodable(identity.deviceId),
                 "publicKey": ProtoAnyCodable(publicKey),
@@ -410,10 +347,11 @@ actor GatewayWizardClient {
                 operation: {
                     while true {
                         let message = try await task.receive()
-                        let frame = try decodeFrame(message)
+                        let frame = try await self.decodeFrame(message)
                         if case let .event(evt) = frame, evt.event == "connect.challenge" {
                             if let payload = evt.payload?.value as? [String: ProtoAnyCodable],
-                               let nonce = payload["nonce"]?.value as? String {
+                               let nonce = payload["nonce"]?.value as? String
+                            {
                                 return nonce
                             }
                         }

apps/macos/Tests/ClawdbotIPCTests/WideAreaGatewayDiscoveryTests.swift

@@ -20,7 +20,7 @@ struct WideAreaGatewayDiscoveryTests {
                 let nameserver = args.first(where: { $0.hasPrefix("@") }) ?? ""
                 if recordType == "PTR" {
                     if nameserver == "@100.123.224.76" {
-                        return "steipetacstudio-gateway._clawdbot-gateway._tcp.clawdbot.internal.\n"
+                        return "steipetacstudio-gateway._clawdbot-gw._tcp.clawdbot.internal.\n"
                     }
                     return ""
                 }

apps/shared/ClawdbotKit/Sources/ClawdbotKit/BonjourTypes.swift

@@ -2,7 +2,7 @@ import Foundation
 
 public enum ClawdbotBonjour {
     // v0: internal-only, subject to rename.
-    public static let gatewayServiceType = "_clawdbot-gateway._tcp"
+    public static let gatewayServiceType = "_clawdbot-gw._tcp"
     public static let gatewayServiceDomain = "local."
     public static let wideAreaGatewayServiceDomain = "clawdbot.internal."
 

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayErrors.swift

@@ -29,5 +29,10 @@ public struct GatewayDecodingError: LocalizedError, Sendable {
     public let method: String
     public let message: String
 
+    public init(method: String, message: String) {
+        self.method = method
+        self.message = message
+    }
+
     public var errorDescription: String? { "\(self.method): \(self.message)" }
 }

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayTLSPinning.swift

@@ -36,7 +36,7 @@ public enum GatewayTLSStore {
     }
 }
 
-public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLSessionDelegate {
+public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLSessionDelegate, @unchecked Sendable {
     private let params: GatewayTLSParams
     private lazy var session: URLSession = {
         let config = URLSessionConfiguration.default
@@ -96,10 +96,12 @@ public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLS
 }
 
 private func certificateFingerprint(_ trust: SecTrust) -> String? {
-    let count = SecTrustGetCertificateCount(trust)
-    guard count > 0, let cert = SecTrustGetCertificateAtIndex(trust, 0) else { return nil }
-    let data = SecCertificateCopyData(cert) as Data
-    return sha256Hex(data)
+    guard let chain = SecTrustCopyCertificateChain(trust) as? [SecCertificate],
+          let cert = chain.first
+    else {
+        return nil
+    }
+    return sha256Hex(SecCertificateCopyData(cert) as Data)
 }
 
 private func sha256Hex(_ data: Data) -> String {

docs/automation/cron-jobs.md

@@ -127,6 +127,11 @@ Isolated jobs can deliver output to a channel. The job payload can specify:
 If `channel` or `to` is omitted, cron can fall back to the main session’s “last route”
 (the last place the agent replied).
 
+Delivery notes:
+- If `to` is set, cron auto-delivers the agent’s final output even if `deliver` is omitted.
+- Use `deliver: true` when you want last-route delivery without an explicit `to`.
+- Use `deliver: false` to keep output internal even if a `to` is present.
+
 Target format reminders:
 - Slack/Discord targets should use explicit prefixes (e.g. `channel:<id>`, `user:<id>`) to avoid ambiguity.
 - Telegram topics should use the `:topic:` form (see below).

docs/channels/index.md

@@ -21,6 +21,7 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately).
 - [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (plugin, installed separately).
 - [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
+- [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (plugin, installed separately).
 - [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).
 - [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (plugin, installed separately).
 - [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.

docs/channels/nostr.md

@@ -0,0 +1,235 @@
+---
+summary: "Nostr DM channel via NIP-04 encrypted messages"
+read_when:
+  - You want Clawdbot to receive DMs via Nostr
+  - You're setting up decentralized messaging
+---
+# Nostr
+
+**Status:** Optional plugin (disabled by default).
+
+Nostr is a decentralized protocol for social networking. This channel enables Clawdbot to receive and respond to encrypted direct messages (DMs) via NIP-04.
+
+## Install (on demand)
+
+### Onboarding (recommended)
+
+- The onboarding wizard (`clawdbot onboard`) and `clawdbot channels add` list optional channel plugins.
+- Selecting Nostr prompts you to install the plugin on demand.
+
+Install defaults:
+
+- **Dev channel + git checkout available:** uses the local plugin path.
+- **Stable/Beta:** downloads from npm.
+
+You can always override the choice in the prompt.
+
+### Manual install
+
+```bash
+clawdbot plugins install @clawdbot/nostr
+```
+
+Use a local checkout (dev workflows):
+
+```bash
+clawdbot plugins install --link <path-to-clawdbot>/extensions/nostr
+```
+
+Restart the Gateway after installing or enabling plugins.
+
+## Quick setup
+
+1) Generate a Nostr keypair (if needed):
+
+```bash
+# Using nak
+nak key generate
+```
+
+2) Add to config:
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}"
+    }
+  }
+}
+```
+
+3) Export the key:
+
+```bash
+export NOSTR_PRIVATE_KEY="nsec1..."
+```
+
+4) Restart the Gateway.
+
+## Configuration reference
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `privateKey` | string | required | Private key in `nsec` or hex format |
+| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | Relay URLs (WebSocket) |
+| `dmPolicy` | string | `pairing` | DM access policy |
+| `allowFrom` | string[] | `[]` | Allowed sender pubkeys |
+| `enabled` | boolean | `true` | Enable/disable channel |
+| `name` | string | - | Display name |
+| `profile` | object | - | NIP-01 profile metadata |
+
+## Profile metadata
+
+Profile data is published as a NIP-01 `kind:0` event. You can manage it from the Control UI (Channels -> Nostr -> Profile) or set it directly in config.
+
+Example:
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "profile": {
+        "name": "clawdbot",
+        "displayName": "Clawdbot",
+        "about": "Personal assistant DM bot",
+        "picture": "https://example.com/avatar.png",
+        "banner": "https://example.com/banner.png",
+        "website": "https://example.com",
+        "nip05": "clawdbot@example.com",
+        "lud16": "clawdbot@example.com"
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- Profile URLs must use `https://`.
+- Importing from relays merges fields and preserves local overrides.
+
+## Access control
+
+### DM policies
+
+- **pairing** (default): unknown senders get a pairing code.
+- **allowlist**: only pubkeys in `allowFrom` can DM.
+- **open**: public inbound DMs (requires `allowFrom: ["*"]`).
+- **disabled**: ignore inbound DMs.
+
+### Allowlist example
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "dmPolicy": "allowlist",
+      "allowFrom": ["npub1abc...", "npub1xyz..."]
+    }
+  }
+}
+```
+
+## Key formats
+
+Accepted formats:
+
+- **Private key:** `nsec...` or 64-char hex
+- **Pubkeys (`allowFrom`):** `npub...` or hex
+
+## Relays
+
+Defaults: `relay.damus.io` and `nos.lol`.
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "relays": [
+        "wss://relay.damus.io",
+        "wss://relay.primal.net",
+        "wss://nostr.wine"
+      ]
+    }
+  }
+}
+```
+
+Tips:
+
+- Use 2-3 relays for redundancy.
+- Avoid too many relays (latency, duplication).
+- Paid relays can improve reliability.
+- Local relays are fine for testing (`ws://localhost:7777`).
+
+## Protocol support
+
+| NIP | Status | Description |
+| --- | --- | --- |
+| NIP-01 | Supported | Basic event format + profile metadata |
+| NIP-04 | Supported | Encrypted DMs (`kind:4`) |
+| NIP-17 | Planned | Gift-wrapped DMs |
+| NIP-44 | Planned | Versioned encryption |
+
+## Testing
+
+### Local relay
+
+```bash
+# Start strfry
+docker run -p 7777:7777 ghcr.io/hoytech/strfry
+```
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "relays": ["ws://localhost:7777"]
+    }
+  }
+}
+```
+
+### Manual test
+
+1) Note the bot pubkey (npub) from logs.
+2) Open a Nostr client (Damus, Amethyst, etc.).
+3) DM the bot pubkey.
+4) Verify the response.
+
+## Troubleshooting
+
+### Not receiving messages
+
+- Verify the private key is valid.
+- Ensure relay URLs are reachable and use `wss://` (or `ws://` for local).
+- Confirm `enabled` is not `false`.
+- Check Gateway logs for relay connection errors.
+
+### Not sending responses
+
+- Check relay accepts writes.
+- Verify outbound connectivity.
+- Watch for relay rate limits.
+
+### Duplicate responses
+
+- Expected when using multiple relays.
+- Messages are deduplicated by event ID; only the first delivery triggers a response.
+
+## Security
+
+- Never commit private keys.
+- Use environment variables for keys.
+- Consider `allowlist` for production bots.
+
+## Limitations (MVP)
+
+- Direct messages only (no group chats).
+- No media attachments.
+- NIP-04 only (NIP-17 gift-wrap planned).

docs/cli/gateway.md

@@ -116,7 +116,7 @@ clawdbot gateway call logs.tail --params '{"sinceMs": 60000}'
 
 ## Discover gateways (Bonjour)
 
-`gateway discover` scans for Gateway beacons (`_clawdbot-gateway._tcp`).
+`gateway discover` scans for Gateway beacons (`_clawdbot-gw._tcp`).
 
 - Multicast DNS-SD: `local.`
 - Unicast DNS-SD (Wide-Area Bonjour): `clawdbot.internal.` (requires split DNS + DNS server; see [/gateway/bonjour](/gateway/bonjour))

docs/cli/sandbox.md

@@ -114,6 +114,9 @@ clawdbot sandbox recreate --agent alfred
 
 **Solution:** Use `clawdbot sandbox recreate` to force removal of old containers. They'll be recreated automatically with current settings when next needed.
 
+Tip: prefer `clawdbot sandbox recreate` over manual `docker rm`. It uses the
+Gateway’s container naming and avoids mismatches when scope/session keys change.
+
 ## Configuration
 
 Sandbox settings live in `~/.clawdbot/clawdbot.json` under `agents.defaults.sandbox` (per-agent overrides go in `agents.list[].sandbox`):

docs/cli/security.md

@@ -21,3 +21,4 @@ clawdbot security audit --fix
 ```
 
 The audit warns when multiple DM senders share the main session and recommends `session.dmScope="per-channel-peer"` for shared inboxes.
+It also warns when small models (<=300B) are used without sandboxing and with web/browser tools enabled.

docs/cli/update.md

@@ -64,6 +64,7 @@ High-level:
 4. Installs deps (pnpm preferred; npm fallback).
 5. Builds + builds the Control UI.
 6. Runs `clawdbot doctor` as the final “safe update” check.
+7. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins.
 
 ## `--update` shorthand
 

docs/concepts/multi-agent.md

@@ -256,6 +256,52 @@ Keep WhatsApp on the fast agent, but route one DM to Opus:
 
 Peer bindings always win, so keep them above the channel-wide rule.
 
+## Family agent bound to a WhatsApp group
+
+Bind a dedicated family agent to a single WhatsApp group, with mention gating
+and a tighter tool policy:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "family",
+        name: "Family",
+        workspace: "~/clawd-family",
+        identity: { name: "Family Bot" },
+        groupChat: {
+          mentionPatterns: ["@family", "@familybot", "@Family Bot"]
+        },
+        sandbox: {
+          mode: "all",
+          scope: "agent"
+        },
+        tools: {
+          allow: ["exec", "read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
+          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"]
+        }
+      }
+    ]
+  },
+  bindings: [
+    {
+      agentId: "family",
+      match: {
+        channel: "whatsapp",
+        peer: { kind: "group", id: "120363999999999999@g.us" }
+      }
+    }
+  ]
+}
+```
+
+Notes:
+- Tool allow/deny lists are **tools**, not skills. If a skill needs to run a
+  binary, ensure `exec` is allowed and the binary exists in the sandbox.
+- For stricter gating, set `agents.list[].groupChat.mentionPatterns` and keep
+  group allowlists enabled for the channel.
+
 ## Per-Agent Sandbox and Tool Configuration
 
 Starting with v2026.1.6, each agent can have its own sandbox and tool restrictions:

docs/concepts/session.md

@@ -60,7 +60,7 @@ the workspace is writable. See [Memory](/concepts/memory) and
 - Idle reset (optional): `idleMinutes` adds a sliding idle window. When both daily and idle resets are configured, **whichever expires first** forces a new session.
 - Legacy idle-only: if you set `session.idleMinutes` without any `session.reset`/`resetByType` config, Clawdbot stays in idle-only mode for backward compatibility.
 - Per-type overrides (optional): `resetByType` lets you override the policy for `dm`, `group`, and `thread` sessions (thread = Slack/Discord threads, Telegram topics, Matrix threads when provided by the connector).
-- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. If `/new` or `/reset` is sent alone, Clawdbot runs a short “hello” greeting turn to confirm the reset.
+- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. `/new <model>` accepts a model alias, `provider/model`, or provider name (fuzzy match) to set the new session model. If `/new` or `/reset` is sent alone, Clawdbot runs a short “hello” greeting turn to confirm the reset.
 - Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
 - Isolated cron jobs always mint a fresh `sessionId` per run (no idle reuse).
 

docs/gateway/bonjour.md

@@ -19,7 +19,7 @@ boundary. You can keep the same discovery UX by switching to **unicast DNS‑SD*
 High‑level steps:
 
 1) Run a DNS server on the gateway host (reachable over Tailnet).
-2) Publish DNS‑SD records for `_clawdbot-bridge._tcp` under a dedicated zone
+2) Publish DNS‑SD records for `_clawdbot-gw._tcp` under a dedicated zone
    (example: `clawdbot.internal.`).
 3) Configure Tailscale **split DNS** so `clawdbot.internal` resolves via that
    DNS server for clients (including iOS).
@@ -49,8 +49,8 @@ This installs CoreDNS and configures it to:
 Validate from a tailnet‑connected machine:
 
 ```bash
-dns-sd -B _clawdbot-bridge._tcp clawdbot.internal.
-dig @<TAILNET_IPV4> -p 53 _clawdbot-bridge._tcp.clawdbot.internal PTR +short
+dns-sd -B _clawdbot-gw._tcp clawdbot.internal.
+dig @<TAILNET_IPV4> -p 53 _clawdbot-gw._tcp.clawdbot.internal PTR +short
 ```
 
 ### Tailscale DNS settings
@@ -61,7 +61,7 @@ In the Tailscale admin console:
 - Add split DNS so the domain `clawdbot.internal` uses that nameserver.
 
 Once clients accept tailnet DNS, iOS nodes can browse
-`_clawdbot-bridge._tcp` in `clawdbot.internal.` without multicast.
+`_clawdbot-gw._tcp` in `clawdbot.internal.` without multicast.
 
 ### Bridge listener security (recommended)
 
@@ -74,11 +74,11 @@ For tailnet‑only setups:
 
 ## What advertises
 
-Only the Gateway (when the **bridge is enabled**) advertises `_clawdbot-bridge._tcp`.
+Only the Gateway advertises `_clawdbot-gw._tcp`.
 
 ## Service types
 
-- `_clawdbot-bridge._tcp` — bridge transport beacon (used by macOS/iOS/Android nodes).
+- `_clawdbot-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).
 
 ## TXT keys (non‑secret hints)
 
@@ -101,11 +101,11 @@ Useful built‑in tools:
 
 - Browse instances:
   ```bash
-  dns-sd -B _clawdbot-bridge._tcp local.
+  dns-sd -B _clawdbot-gw._tcp local.
   ```
 - Resolve one instance (replace `<instance>`):
   ```bash
-  dns-sd -L "<instance>" _clawdbot-bridge._tcp local.
+  dns-sd -L "<instance>" _clawdbot-gw._tcp local.
   ```
 
 If browsing works but resolving fails, you’re usually hitting a LAN policy or
@@ -122,7 +122,7 @@ The Gateway writes a rolling log file (printed on startup as
 
 ## Debugging on iOS node
 
-The iOS node uses `NWBrowser` to discover `_clawdbot-bridge._tcp`.
+The iOS node uses `NWBrowser` to discover `_clawdbot-gw._tcp`.
 
 To capture logs:
 - Settings → Bridge → Advanced → **Discovery Debug Logs**

docs/gateway/configuration.md

@@ -1414,7 +1414,7 @@ Each `agents.defaults.models` entry can include:
 - `alias` (optional model shortcut, e.g. `/opus`).
 - `params` (optional provider-specific API params passed through to the model request).
 
-`params` is also applied to streaming runs (embedded agent + compaction). Supported keys today: `temperature`, `maxTokens`. These merge with call-time options; caller-supplied values win. `temperature` is an advanced knob—leave unset unless you know the model’s defaults and need a change.
+`params` is also applied to streaming runs (embedded agent + compaction). Supported keys today: `temperature`, `maxTokens`, `cacheControlTtl` (`"5m"` or `"1h"`, Anthropic API + OpenRouter Anthropic models only; ignored for Anthropic OAuth/Claude Code tokens). These merge with call-time options; caller-supplied values win. `temperature` is an advanced knob—leave unset unless you know the model’s defaults and need a change. Anthropic API defaults to `"1h"` unless you override (`cacheControlTtl: "5m"`). Clawdbot includes the `extended-cache-ttl-2025-04-11` beta flag for Anthropic API; keep it if you override provider headers.
 
 Example:
 
@@ -2988,7 +2988,7 @@ Auto-generated certs require `openssl` on PATH; if generation fails, the bridge
 
 ### `discovery.wideArea` (Wide-Area Bonjour / unicast DNS‑SD)
 
-When enabled, the Gateway writes a unicast DNS-SD zone for `_clawdbot-bridge._tcp` under `~/.clawdbot/dns/` using the standard discovery domain `clawdbot.internal.`
+When enabled, the Gateway writes a unicast DNS-SD zone for `_clawdbot-gw._tcp` under `~/.clawdbot/dns/` using the standard discovery domain `clawdbot.internal.`
 
 To make iOS/Android discover across networks (Vienna ⇄ London), pair this with:
 - a DNS server on the gateway host serving `clawdbot.internal.` (CoreDNS is recommended)

docs/gateway/discovery.md

@@ -51,7 +51,7 @@ Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
 #### Service beacon details
 
 - Service types:
-  - `_clawdbot-bridge._tcp` (bridge transport beacon)
+  - `_clawdbot-gw._tcp` (gateway transport beacon)
 - TXT keys (non-secret):
   - `role=gateway`
   - `lanHost=<hostname>.local`

docs/gateway/sandboxing.md

@@ -105,6 +105,11 @@ Build it once:
 scripts/sandbox-setup.sh
 ```
 
+Note: the default image does **not** include Node. If a skill needs Node (or
+other runtimes), either bake a custom image or install via
+`sandbox.docker.setupCommand` (requires network egress + writable root +
+root user).
+
 Sandboxed browser image:
 ```bash
 scripts/sandbox-browser-setup.sh
@@ -129,6 +134,8 @@ Common pitfalls:
 - Default `docker.network` is `"none"` (no egress), so package installs will fail.
 - `readOnlyRoot: true` prevents writes; set `readOnlyRoot: false` or bake a custom image.
 - `user` must be root for package installs (omit `user` or set `user: "0:0"`).
+- Sandbox exec does **not** inherit host `process.env`. Use
+  `agents.defaults.sandbox.docker.env` (or a custom image) for skill API keys.
 
 ## Tool policy + escape hatches
 Tool allow/deny policies still apply before sandbox rules. If a tool is denied

docs/gateway/security.md

@@ -177,6 +177,7 @@ Recommendations:
 - **Use the latest generation, best-tier model** for any bot that can run tools or touch files/networks.
 - **Avoid weaker tiers** (for example, Sonnet or Haiku) for tool-enabled agents or untrusted inboxes.
 - If you must use a smaller model, **reduce blast radius** (read-only tools, strong sandboxing, minimal filesystem access, strict allowlists).
+- When running small models, **enable sandboxing for all sessions** and **disable web_search/web_fetch/browser** unless inputs are tightly controlled.
 
 ## Reasoning & verbose output in groups
 

docs/gateway/troubleshooting.md

@@ -87,6 +87,17 @@ WhatsApp + Telegram channels require **Node**; Bun is unsupported. If your
 service was installed with Bun or a version-managed Node path, run `clawdbot doctor`
 to migrate to a system Node install.
 
+### Skill missing API key in sandbox
+
+**Symptom:** Skill works on host but fails in sandbox with missing API key.
+
+**Why:** sandboxed exec runs inside Docker and does **not** inherit host `process.env`.
+
+**Fix:**
+- set `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)
+- or bake the key into your custom sandbox image
+- then run `clawdbot sandbox recreate --agent <id>` (or `--all`)
+
 ### Service Running but Port Not Listening
 
 If the service reports **running** but nothing is listening on the gateway port,

docs/install/development-channels.md

@@ -7,6 +7,8 @@ read_when:
 
 # Development channels
 
+Last updated: 2026-01-20
+
 Clawdbot ships three update channels:
 
 - **stable**: tagged releases (`vYYYY.M.D` or `vYYYY.M.D-<patch>`). npm dist-tag: `latest`.
@@ -38,6 +40,13 @@ This updates via the corresponding npm dist-tag (`latest`, `beta`, `dev`).
 
 Tip: if you want stable + dev in parallel, keep two clones and point your gateway at the stable one.
 
+## Plugins and channels
+
+When you switch channels with `clawdbot update`, Clawdbot also syncs plugin sources:
+
+- `dev` prefers bundled plugins from the git checkout.
+- `stable` and `beta` restore npm-installed plugin packages.
+
 ## Tagging best practices
 
 - Stable: tag each release (`vYYYY.M.D` or `vYYYY.M.D-<patch>`).

docs/logging.md

@@ -136,6 +136,179 @@ Tool summaries can redact sensitive tokens before they hit the console:
 
 Redaction affects **console output only** and does not alter file logs.
 
+## Diagnostics + OpenTelemetry
+
+Diagnostics are structured, machine-readable events for model runs **and**
+message-flow telemetry (webhooks, queueing, session state). They do **not**
+replace logs; they exist to feed metrics, traces, and other exporters.
+
+Diagnostics events are emitted in-process, but exporters only attach when
+diagnostics + the exporter plugin are enabled.
+
+### OpenTelemetry vs OTLP
+
+- **OpenTelemetry (OTel)**: the data model + SDKs for traces, metrics, and logs.
+- **OTLP**: the wire protocol used to export OTel data to a collector/backend.
+- Clawdbot exports via **OTLP/HTTP (protobuf)** today.
+
+### Signals exported
+
+- **Metrics**: counters + histograms (token usage, message flow, queueing).
+- **Traces**: spans for model usage + webhook/message processing.
+- **Logs**: exported over OTLP when `diagnostics.otel.logs` is enabled. Log
+  volume can be high; keep `logging.level` and exporter filters in mind.
+
+### Diagnostic event catalog
+
+Model usage:
+- `model.usage`: tokens, cost, duration, context, provider/model/channel, session ids.
+
+Message flow:
+- `webhook.received`: webhook ingress per channel.
+- `webhook.processed`: webhook handled + duration.
+- `webhook.error`: webhook handler errors.
+- `message.queued`: message enqueued for processing.
+- `message.processed`: outcome + duration + optional error.
+
+Queue + session:
+- `queue.lane.enqueue`: command queue lane enqueue + depth.
+- `queue.lane.dequeue`: command queue lane dequeue + wait time.
+- `session.state`: session state transition + reason.
+- `session.stuck`: session stuck warning + age.
+- `run.attempt`: run retry/attempt metadata.
+- `diagnostic.heartbeat`: aggregate counters (webhooks/queue/session).
+
+### Enable diagnostics (no exporter)
+
+Use this if you want diagnostics events available to plugins or custom sinks:
+
+```json
+{
+  "diagnostics": {
+    "enabled": true
+  }
+}
+```
+
+### Export to OpenTelemetry
+
+Diagnostics can be exported via the `diagnostics-otel` plugin (OTLP/HTTP). This
+works with any OpenTelemetry collector/backend that accepts OTLP/HTTP.
+
+```json
+{
+  "plugins": {
+    "allow": ["diagnostics-otel"],
+    "entries": {
+      "diagnostics-otel": {
+        "enabled": true
+      }
+    }
+  },
+  "diagnostics": {
+    "enabled": true,
+    "otel": {
+      "enabled": true,
+      "endpoint": "http://otel-collector:4318",
+      "protocol": "http/protobuf",
+      "serviceName": "clawdbot-gateway",
+      "traces": true,
+      "metrics": true,
+      "logs": true,
+      "sampleRate": 0.2,
+      "flushIntervalMs": 60000
+    }
+  }
+}
+```
+
+Notes:
+- You can also enable the plugin with `clawdbot plugins enable diagnostics-otel`.
+- `protocol` currently supports `http/protobuf` only. `grpc` is ignored.
+- Metrics include token usage, cost, context size, run duration, and message-flow
+  counters/histograms (webhooks, queueing, session state, queue depth/wait).
+- Traces/metrics can be toggled with `traces` / `metrics` (default: on). Traces
+  include model usage spans plus webhook/message processing spans when enabled.
+- Set `headers` when your collector requires auth.
+- Environment variables supported: `OTEL_EXPORTER_OTLP_ENDPOINT`,
+  `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_PROTOCOL`.
+
+### Exported metrics (names + types)
+
+Model usage:
+- `clawdbot.tokens` (counter, attrs: `clawdbot.token`, `clawdbot.channel`,
+  `clawdbot.provider`, `clawdbot.model`)
+- `clawdbot.cost.usd` (counter, attrs: `clawdbot.channel`, `clawdbot.provider`,
+  `clawdbot.model`)
+- `clawdbot.run.duration_ms` (histogram, attrs: `clawdbot.channel`,
+  `clawdbot.provider`, `clawdbot.model`)
+- `clawdbot.context.tokens` (histogram, attrs: `clawdbot.context`,
+  `clawdbot.channel`, `clawdbot.provider`, `clawdbot.model`)
+
+Message flow:
+- `clawdbot.webhook.received` (counter, attrs: `clawdbot.channel`,
+  `clawdbot.webhook`)
+- `clawdbot.webhook.error` (counter, attrs: `clawdbot.channel`,
+  `clawdbot.webhook`)
+- `clawdbot.webhook.duration_ms` (histogram, attrs: `clawdbot.channel`,
+  `clawdbot.webhook`)
+- `clawdbot.message.queued` (counter, attrs: `clawdbot.channel`,
+  `clawdbot.source`)
+- `clawdbot.message.processed` (counter, attrs: `clawdbot.channel`,
+  `clawdbot.outcome`)
+- `clawdbot.message.duration_ms` (histogram, attrs: `clawdbot.channel`,
+  `clawdbot.outcome`)
+
+Queues + sessions:
+- `clawdbot.queue.lane.enqueue` (counter, attrs: `clawdbot.lane`)
+- `clawdbot.queue.lane.dequeue` (counter, attrs: `clawdbot.lane`)
+- `clawdbot.queue.depth` (histogram, attrs: `clawdbot.lane` or
+  `clawdbot.channel=heartbeat`)
+- `clawdbot.queue.wait_ms` (histogram, attrs: `clawdbot.lane`)
+- `clawdbot.session.state` (counter, attrs: `clawdbot.state`, `clawdbot.reason`)
+- `clawdbot.session.stuck` (counter, attrs: `clawdbot.state`)
+- `clawdbot.session.stuck_age_ms` (histogram, attrs: `clawdbot.state`)
+- `clawdbot.run.attempt` (counter, attrs: `clawdbot.attempt`)
+
+### Exported spans (names + key attributes)
+
+- `clawdbot.model.usage`
+  - `clawdbot.channel`, `clawdbot.provider`, `clawdbot.model`
+  - `clawdbot.sessionKey`, `clawdbot.sessionId`
+  - `clawdbot.tokens.*` (input/output/cache_read/cache_write/total)
+- `clawdbot.webhook.processed`
+  - `clawdbot.channel`, `clawdbot.webhook`, `clawdbot.chatId`
+- `clawdbot.webhook.error`
+  - `clawdbot.channel`, `clawdbot.webhook`, `clawdbot.chatId`,
+    `clawdbot.error`
+- `clawdbot.message.processed`
+  - `clawdbot.channel`, `clawdbot.outcome`, `clawdbot.chatId`,
+    `clawdbot.messageId`, `clawdbot.sessionKey`, `clawdbot.sessionId`,
+    `clawdbot.reason`
+- `clawdbot.session.stuck`
+  - `clawdbot.state`, `clawdbot.ageMs`, `clawdbot.queueDepth`,
+    `clawdbot.sessionKey`, `clawdbot.sessionId`
+
+### Sampling + flushing
+
+- Trace sampling: `diagnostics.otel.sampleRate` (0.0–1.0, root spans only).
+- Metric export interval: `diagnostics.otel.flushIntervalMs` (min 1000ms).
+
+### Protocol notes
+
+- OTLP/HTTP endpoints can be set via `diagnostics.otel.endpoint` or
+  `OTEL_EXPORTER_OTLP_ENDPOINT`.
+- If the endpoint already contains `/v1/traces` or `/v1/metrics`, it is used as-is.
+- If the endpoint already contains `/v1/logs`, it is used as-is for logs.
+- `diagnostics.otel.logs` enables OTLP log export for the main logger output.
+
+### Log export behavior
+
+- OTLP logs use the same structured records written to `logging.file`.
+- Respect `logging.level` (file log level). Console redaction does **not** apply
+  to OTLP logs.
+- High-volume installs should prefer OTLP collector sampling/filtering.
+
 ## Troubleshooting tips
 
 - **Gateway not reachable?** Run `clawdbot doctor` first.

docs/platforms/android.md

@@ -52,7 +52,7 @@ For tailnet-only setups (recommended for Vienna ⇄ London), bind the gateway to
 From the gateway machine:
 
 ```bash
-dns-sd -B _clawdbot-gateway._tcp local.
+dns-sd -B _clawdbot-gw._tcp local.
 ```
 
 More debugging notes: [Bonjour](/gateway/bonjour).
@@ -61,7 +61,7 @@ More debugging notes: [Bonjour](/gateway/bonjour).
 
 Android NSD/mDNS discovery won’t cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead:
 
-1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-gateway._tcp` records.
+1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-gw._tcp` records.
 2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.
 
 Details and example CoreDNS config: [Bonjour](/gateway/bonjour).

docs/platforms/mac/release.md

@@ -29,17 +29,17 @@ Notes:
 # From repo root; set release IDs so Sparkle feed is enabled.
 # APP_BUILD must be numeric + monotonic for Sparkle compare.
 BUNDLE_ID=com.clawdbot.mac \
-APP_VERSION=2026.1.13 \
+APP_VERSION=2026.1.20 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-app.sh
 
 # Zip for distribution (includes resource forks for Sparkle delta support)
-ditto -c -k --sequesterRsrc --keepParent dist/Clawdbot.app dist/Clawdbot-2026.1.13.zip
+ditto -c -k --sequesterRsrc --keepParent dist/Clawdbot.app dist/Clawdbot-2026.1.20.zip
 
 # Optional: also build a styled DMG for humans (drag to /Applications)
-scripts/create-dmg.sh dist/Clawdbot.app dist/Clawdbot-2026.1.13.dmg
+scripts/create-dmg.sh dist/Clawdbot.app dist/Clawdbot-2026.1.20.dmg
 
 # Recommended: build + notarize/staple zip + DMG
 # First, create a keychain profile once:
@@ -47,26 +47,26 @@ scripts/create-dmg.sh dist/Clawdbot.app dist/Clawdbot-2026.1.13.dmg
 #     --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
 NOTARIZE=1 NOTARYTOOL_PROFILE=clawdbot-notary \
 BUNDLE_ID=com.clawdbot.mac \
-APP_VERSION=2026.1.13 \
+APP_VERSION=2026.1.20 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-dist.sh
 
 # Optional: ship dSYM alongside the release
-ditto -c -k --keepParent apps/macos/.build/release/Clawdbot.app.dSYM dist/Clawdbot-2026.1.13.dSYM.zip
+ditto -c -k --keepParent apps/macos/.build/release/Clawdbot.app.dSYM dist/Clawdbot-2026.1.20.dSYM.zip
 ```
 
 ## Appcast entry
 Use the release note generator so Sparkle renders formatted HTML notes:
 ```bash
-SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/Clawdbot-2026.1.13.zip https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml
+SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/Clawdbot-2026.1.20.zip https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml
 ```
 Generates HTML release notes from `CHANGELOG.md` (via [`scripts/changelog-to-html.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/changelog-to-html.sh)) and embeds them in the appcast entry.
 Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when publishing.
 
 ## Publish & verify
-- Upload `Clawdbot-2026.1.13.zip` (and `Clawdbot-2026.1.13.dSYM.zip`) to the GitHub release for tag `v2026.1.13`.
+- Upload `Clawdbot-2026.1.20.zip` (and `Clawdbot-2026.1.20.dSYM.zip`) to the GitHub release for tag `v2026.1.20`.
 - Ensure the raw appcast URL matches the baked feed: `https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml`.
 - Sanity checks:
   - `curl -I https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml` returns 200.

docs/platforms/mac/xpc.md

@@ -5,7 +5,7 @@ read_when:
 ---
 # Clawdbot macOS IPC architecture
 
-**Current model:** a local Unix socket connects the **node service** to the **macOS app** for exec approvals + `system.run`. There is no `clawdbot-mac` CLI; agent actions still flow through the Gateway WebSocket and `node.invoke`. UI automation uses PeekabooBridge.
+**Current model:** a local Unix socket connects the **node service** to the **macOS app** for exec approvals + `system.run`. A `clawdbot-mac` debug CLI exists for discovery/connect checks; agent actions still flow through the Gateway WebSocket and `node.invoke`. UI automation uses PeekabooBridge.
 
 ## Goals
 - Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).

docs/platforms/macos.md

@@ -140,19 +140,27 @@ Safety:
 - `swift run Clawdbot` (or Xcode)
 - Package app: `scripts/package-mac-app.sh`
 
-## Debug gateway discovery (macOS CLI)
+## Debug gateway connectivity (macOS CLI)
 
-Use the debug CLI to exercise the same Bonjour + wide‑area discovery code that the
-macOS app uses, without launching the app.
+Use the debug CLI to exercise the same Gateway WebSocket handshake and discovery
+logic that the macOS app uses, without launching the app.
 
 ```bash
 cd apps/macos
-swift run clawdbot-mac-discovery --timeout 3000 --json
+swift run clawdbot-mac connect --json
+swift run clawdbot-mac discover --timeout 3000 --json
 ```
 
-Options:
+Connect options:
+- `--url <ws://host:port>`: override config
+- `--mode <local|remote>`: resolve from config (default: config or local)
+- `--probe`: force a fresh health probe
+- `--timeout <ms>`: request timeout (default: `15000`)
+- `--json`: structured output for diffing
+
+Discovery options:
 - `--include-local`: include gateways that would be filtered as “local”
-- `--timeout <ms>`: overall discovery window (default `2000`)
+- `--timeout <ms>`: overall discovery window (default: `2000`)
 - `--json`: structured output for diffing
 
 Tip: compare against `clawdbot gateway discover --json` to see whether the

docs/plugin.md

@@ -41,6 +41,7 @@ See [Voice Call](/plugins/voice-call) for a concrete example plugin.
 - [Voice Call](/plugins/voice-call) — `@clawdbot/voice-call`
 - [Zalo Personal](/plugins/zalouser) — `@clawdbot/zalouser`
 - [Matrix](/channels/matrix) — `@clawdbot/matrix`
+- [Nostr](/channels/nostr) — `@clawdbot/nostr`
 - [Zalo](/channels/zalo) — `@clawdbot/zalo`
 - [Microsoft Teams](/channels/msteams) — `@clawdbot/msteams`
 - Google Antigravity OAuth (provider auth) — bundled as `google-antigravity-auth` (disabled by default)

docs/providers/anthropic.md

@@ -34,6 +34,30 @@ clawdbot onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
 }
 ```
 
+## Prompt caching (Anthropic API)
+
+Clawdbot enables **1-hour prompt caching by default** for Anthropic API keys.
+This is **API-only**; Claude Code CLI OAuth ignores TTL settings.
+
+To override the TTL per model, set `cacheControlTtl` in the model `params`:
+
+```json5
+{
+  agents: {
+    defaults: {
+      models: {
+        "anthropic/claude-opus-4-5": {
+          params: { cacheControlTtl: "5m" } // or "1h"
+        }
+      }
+    }
+  }
+}
+```
+
+Clawdbot includes the `extended-cache-ttl-2025-04-11` beta flag for Anthropic API
+requests; keep it if you override provider headers (see [/gateway/configuration](/gateway/configuration)).
+
 ## Option B: Claude Code CLI (setup-token or OAuth)
 
 **Best for:** using your Claude subscription or existing Claude Code CLI login.

docs/tools/skills-config.md

@@ -62,3 +62,14 @@ Per-skill fields:
 - Keys under `entries` map to the skill name by default. If a skill defines
   `metadata.clawdbot.skillKey`, use that key instead.
 - Changes to skills are picked up on the next agent turn when the watcher is enabled.
+
+### Sandboxed skills + env vars
+
+When a session is **sandboxed**, skill processes run inside Docker. The sandbox
+does **not** inherit the host `process.env`.
+
+Use one of:
+- `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)
+- bake the env into your custom sandbox image
+
+Global `env` and `skills.entries.<skill>.env/apiKey` apply to **host** runs only.

docs/tools/skills.md

@@ -155,6 +155,10 @@ Bundled/managed skills can be toggled and supplied with env values:
         apiKey: "GEMINI_KEY_HERE",
         env: {
           GEMINI_API_KEY: "GEMINI_KEY_HERE"
+        },
+        config: {
+          endpoint: "https://example.invalid",
+          model: "nano-pro"
         }
       },
       peekaboo: { enabled: true },
@@ -173,6 +177,7 @@ Rules:
 - `enabled: false` disables the skill even if it’s bundled/installed.
 - `env`: injected **only if** the variable isn’t already set in the process.
 - `apiKey`: convenience for skills that declare `metadata.clawdbot.primaryEnv`.
+- `config`: optional bag for custom per-skill fields; custom keys must live here.
 - `allowBundled`: optional allowlist for **bundled** skills only. If set, only
   bundled skills in the list are eligible (managed/workspace skills unaffected).
 

docs/tools/slash-commands.md

@@ -73,7 +73,7 @@ Text + native (when enabled):
 - `/dock-slack` (alias: `/dock_slack`) (switch replies to Slack)
 - `/activation mention|always` (groups only)
 - `/send on|off|inherit` (owner-only)
-- `/reset` or `/new`
+- `/reset` or `/new [model]` (optional model hint; remainder is passed through)
 - `/think <off|minimal|low|medium|high|xhigh>` (dynamic choices by model/provider; aliases: `/thinking`, `/t`)
 - `/verbose on|full|off` (alias: `/v`)
 - `/reasoning on|off|stream` (alias: `/reason`; when on, sends a separate message prefixed `Reasoning:`; `stream` = Telegram draft only)
@@ -91,6 +91,7 @@ Text-only:
 
 Notes:
 - Commands accept an optional `:` between the command and args (e.g. `/think: high`, `/send: on`, `/help:`).
+- `/new <model>` accepts a model alias, `provider/model`, or a provider name (fuzzy match); if no match, the text is treated as the message body.
 - For full provider usage breakdown, use `clawdbot status --usage`.
 - `/usage` controls the per-response usage footer; `/usage cost` prints a local cost summary from Clawdbot session logs.
 - `/restart` is disabled by default; set `commands.restart: true` to enable it.

docs/tools/subagents.md

@@ -69,7 +69,8 @@ Note: the merge is additive, so main profiles are always available as fallbacks.
 Sub-agents report back via an announce step:
 - The announce step runs inside the sub-agent session (not the requester session).
 - If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted.
-- Otherwise the announce reply is posted to the requester chat channel via the gateway `send` method.
+- Otherwise the announce reply is posted to the requester chat channel via a follow-up `agent` call (`deliver=true`).
+- Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads).
 - Announce messages are normalized to a stable template:
   - `Status:` derived from the run outcome (`success`, `error`, `timeout`, or `unknown`).
   - `Result:` the summary content from the announce step (or `(not available)` if missing).

extensions/diagnostics-otel/clawdbot.plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "diagnostics-otel",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/diagnostics-otel/index.ts

@@ -0,0 +1,16 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+
+import { createDiagnosticsOtelService } from "./src/service.js";
+
+const plugin = {
+  id: "diagnostics-otel",
+  name: "Diagnostics OpenTelemetry",
+  description: "Export diagnostics events to OpenTelemetry",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    api.registerService(createDiagnosticsOtelService());
+  },
+};
+
+export default plugin;

extensions/diagnostics-otel/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@clawdbot/diagnostics-otel",
+  "version": "2026.1.17-1",
+  "type": "module",
+  "description": "Clawdbot diagnostics OpenTelemetry exporter",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.210.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.210.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.210.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.210.0",
+    "@opentelemetry/resources": "^2.4.0",
+    "@opentelemetry/sdk-logs": "^0.210.0",
+    "@opentelemetry/sdk-metrics": "^2.4.0",
+    "@opentelemetry/sdk-node": "^0.210.0",
+    "@opentelemetry/sdk-trace-base": "^2.4.0",
+    "@opentelemetry/semantic-conventions": "^1.39.0"
+  }
+}

extensions/diagnostics-otel/src/service.test.ts

@@ -0,0 +1,220 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+const registerLogTransportMock = vi.hoisted(() => vi.fn());
+
+const telemetryState = vi.hoisted(() => {
+  const counters = new Map<string, { add: ReturnType<typeof vi.fn> }>();
+  const histograms = new Map<string, { record: ReturnType<typeof vi.fn> }>();
+  const tracer = {
+    startSpan: vi.fn((_name: string, _opts?: unknown) => ({
+      end: vi.fn(),
+      setStatus: vi.fn(),
+    })),
+  };
+  const meter = {
+    createCounter: vi.fn((name: string) => {
+      const counter = { add: vi.fn() };
+      counters.set(name, counter);
+      return counter;
+    }),
+    createHistogram: vi.fn((name: string) => {
+      const histogram = { record: vi.fn() };
+      histograms.set(name, histogram);
+      return histogram;
+    }),
+  };
+  return { counters, histograms, tracer, meter };
+});
+
+const sdkStart = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+const sdkShutdown = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+const logEmit = vi.hoisted(() => vi.fn());
+const logShutdown = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+
+vi.mock("@opentelemetry/api", () => ({
+  metrics: {
+    getMeter: () => telemetryState.meter,
+  },
+  trace: {
+    getTracer: () => telemetryState.tracer,
+  },
+  SpanStatusCode: {
+    ERROR: 2,
+  },
+}));
+
+vi.mock("@opentelemetry/sdk-node", () => ({
+  NodeSDK: class {
+    start = sdkStart;
+    shutdown = sdkShutdown;
+  },
+}));
+
+vi.mock("@opentelemetry/exporter-metrics-otlp-http", () => ({
+  OTLPMetricExporter: class {},
+}));
+
+vi.mock("@opentelemetry/exporter-trace-otlp-http", () => ({
+  OTLPTraceExporter: class {},
+}));
+
+vi.mock("@opentelemetry/exporter-logs-otlp-http", () => ({
+  OTLPLogExporter: class {},
+}));
+
+vi.mock("@opentelemetry/sdk-logs", () => ({
+  BatchLogRecordProcessor: class {},
+  LoggerProvider: class {
+    addLogRecordProcessor = vi.fn();
+    getLogger = vi.fn(() => ({
+      emit: logEmit,
+    }));
+    shutdown = logShutdown;
+  },
+}));
+
+vi.mock("@opentelemetry/sdk-metrics", () => ({
+  PeriodicExportingMetricReader: class {},
+}));
+
+vi.mock("@opentelemetry/sdk-trace-base", () => ({
+  ParentBasedSampler: class {},
+  TraceIdRatioBasedSampler: class {},
+}));
+
+vi.mock("@opentelemetry/resources", () => ({
+  Resource: class {
+    // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+    constructor(_value?: unknown) {}
+  },
+}));
+
+vi.mock("@opentelemetry/semantic-conventions", () => ({
+  SemanticResourceAttributes: {
+    SERVICE_NAME: "service.name",
+  },
+}));
+
+vi.mock("clawdbot/plugin-sdk", async () => {
+  const actual = await vi.importActual<typeof import("clawdbot/plugin-sdk")>("clawdbot/plugin-sdk");
+  return {
+    ...actual,
+    registerLogTransport: registerLogTransportMock,
+  };
+});
+
+import { createDiagnosticsOtelService } from "./service.js";
+import { emitDiagnosticEvent } from "clawdbot/plugin-sdk";
+
+describe("diagnostics-otel service", () => {
+  beforeEach(() => {
+    telemetryState.counters.clear();
+    telemetryState.histograms.clear();
+    telemetryState.tracer.startSpan.mockClear();
+    telemetryState.meter.createCounter.mockClear();
+    telemetryState.meter.createHistogram.mockClear();
+    sdkStart.mockClear();
+    sdkShutdown.mockClear();
+    logEmit.mockClear();
+    logShutdown.mockClear();
+    registerLogTransportMock.mockReset();
+  });
+
+  test("records message-flow metrics and spans", async () => {
+    const registeredTransports: Array<(logObj: Record<string, unknown>) => void> = [];
+    const stopTransport = vi.fn();
+    registerLogTransportMock.mockImplementation((transport) => {
+      registeredTransports.push(transport);
+      return stopTransport;
+    });
+
+    const service = createDiagnosticsOtelService();
+    await service.start({
+      config: {
+        diagnostics: {
+          enabled: true,
+          otel: {
+            enabled: true,
+            endpoint: "http://otel-collector:4318",
+            protocol: "http/protobuf",
+            traces: true,
+            metrics: true,
+            logs: true,
+          },
+        },
+      },
+      logger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+      },
+    });
+
+    emitDiagnosticEvent({
+      type: "webhook.received",
+      channel: "telegram",
+      updateType: "telegram-post",
+    });
+    emitDiagnosticEvent({
+      type: "webhook.processed",
+      channel: "telegram",
+      updateType: "telegram-post",
+      durationMs: 120,
+    });
+    emitDiagnosticEvent({
+      type: "message.queued",
+      channel: "telegram",
+      source: "telegram",
+      queueDepth: 2,
+    });
+    emitDiagnosticEvent({
+      type: "message.processed",
+      channel: "telegram",
+      outcome: "completed",
+      durationMs: 55,
+    });
+    emitDiagnosticEvent({
+      type: "queue.lane.dequeue",
+      lane: "main",
+      queueSize: 3,
+      waitMs: 10,
+    });
+    emitDiagnosticEvent({
+      type: "session.stuck",
+      state: "processing",
+      ageMs: 125_000,
+    });
+    emitDiagnosticEvent({
+      type: "run.attempt",
+      runId: "run-1",
+      attempt: 2,
+    });
+
+    expect(telemetryState.counters.get("clawdbot.webhook.received")?.add).toHaveBeenCalled();
+    expect(telemetryState.histograms.get("clawdbot.webhook.duration_ms")?.record).toHaveBeenCalled();
+    expect(telemetryState.counters.get("clawdbot.message.queued")?.add).toHaveBeenCalled();
+    expect(telemetryState.counters.get("clawdbot.message.processed")?.add).toHaveBeenCalled();
+    expect(telemetryState.histograms.get("clawdbot.message.duration_ms")?.record).toHaveBeenCalled();
+    expect(telemetryState.histograms.get("clawdbot.queue.wait_ms")?.record).toHaveBeenCalled();
+    expect(telemetryState.counters.get("clawdbot.session.stuck")?.add).toHaveBeenCalled();
+    expect(telemetryState.histograms.get("clawdbot.session.stuck_age_ms")?.record).toHaveBeenCalled();
+    expect(telemetryState.counters.get("clawdbot.run.attempt")?.add).toHaveBeenCalled();
+
+    const spanNames = telemetryState.tracer.startSpan.mock.calls.map((call) => call[0]);
+    expect(spanNames).toContain("clawdbot.webhook.processed");
+    expect(spanNames).toContain("clawdbot.message.processed");
+    expect(spanNames).toContain("clawdbot.session.stuck");
+
+    expect(registerLogTransportMock).toHaveBeenCalledTimes(1);
+    expect(registeredTransports).toHaveLength(1);
+    registeredTransports[0]?.({
+      0: "{\"subsystem\":\"diagnostic\"}",
+      1: "hello",
+      _meta: { logLevelName: "INFO", date: new Date() },
+    });
+    expect(logEmit).toHaveBeenCalled();
+
+    await service.stop?.();
+  });
+});

extensions/diagnostics-otel/src/service.ts

@@ -0,0 +1,566 @@
+import { metrics, trace, SpanStatusCode } from "@opentelemetry/api";
+import type { SeverityNumber } from "@opentelemetry/api-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { Resource } from "@opentelemetry/resources";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
+import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
+
+import type { ClawdbotPluginService, DiagnosticEventPayload } from "clawdbot/plugin-sdk";
+import { onDiagnosticEvent, registerLogTransport } from "clawdbot/plugin-sdk";
+
+const DEFAULT_SERVICE_NAME = "clawdbot";
+
+function normalizeEndpoint(endpoint?: string): string | undefined {
+  const trimmed = endpoint?.trim();
+  return trimmed ? trimmed.replace(/\/+$/, "") : undefined;
+}
+
+function resolveOtelUrl(endpoint: string | undefined, path: string): string | undefined {
+  if (!endpoint) return undefined;
+  if (endpoint.includes("/v1/")) return endpoint;
+  return `${endpoint}/${path}`;
+}
+
+function resolveSampleRate(value: number | undefined): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  if (value < 0 || value > 1) return undefined;
+  return value;
+}
+
+export function createDiagnosticsOtelService(): ClawdbotPluginService {
+  let sdk: NodeSDK | null = null;
+  let logProvider: LoggerProvider | null = null;
+  let stopLogTransport: (() => void) | null = null;
+  let unsubscribe: (() => void) | null = null;
+
+  return {
+    id: "diagnostics-otel",
+    async start(ctx) {
+      const cfg = ctx.config.diagnostics;
+      const otel = cfg?.otel;
+      if (!cfg?.enabled || !otel?.enabled) return;
+
+      const protocol = otel.protocol ?? process.env.OTEL_EXPORTER_OTLP_PROTOCOL ?? "http/protobuf";
+      if (protocol !== "http/protobuf") {
+        ctx.logger.warn(`diagnostics-otel: unsupported protocol ${protocol}`);
+        return;
+      }
+
+      const endpoint = normalizeEndpoint(otel.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+      const headers = otel.headers ?? undefined;
+      const serviceName =
+        otel.serviceName?.trim() || process.env.OTEL_SERVICE_NAME || DEFAULT_SERVICE_NAME;
+      const sampleRate = resolveSampleRate(otel.sampleRate);
+
+      const tracesEnabled = otel.traces !== false;
+      const metricsEnabled = otel.metrics !== false;
+      const logsEnabled = otel.logs === true;
+      if (!tracesEnabled && !metricsEnabled && !logsEnabled) return;
+
+      const resource = new Resource({
+        [SemanticResourceAttributes.SERVICE_NAME]: serviceName,
+      });
+
+      const traceUrl = resolveOtelUrl(endpoint, "v1/traces");
+      const metricUrl = resolveOtelUrl(endpoint, "v1/metrics");
+      const logUrl = resolveOtelUrl(endpoint, "v1/logs");
+      const traceExporter = tracesEnabled
+        ? new OTLPTraceExporter({
+            ...(traceUrl ? { url: traceUrl } : {}),
+            ...(headers ? { headers } : {}),
+          })
+        : undefined;
+
+      const metricExporter = metricsEnabled
+        ? new OTLPMetricExporter({
+            ...(metricUrl ? { url: metricUrl } : {}),
+            ...(headers ? { headers } : {}),
+          })
+        : undefined;
+
+      const metricReader = metricExporter
+        ? new PeriodicExportingMetricReader({
+            exporter: metricExporter,
+            ...(typeof otel.flushIntervalMs === "number"
+              ? { exportIntervalMillis: Math.max(1000, otel.flushIntervalMs) }
+              : {}),
+          })
+        : undefined;
+
+      if (tracesEnabled || metricsEnabled) {
+        sdk = new NodeSDK({
+          resource,
+          ...(traceExporter ? { traceExporter } : {}),
+          ...(metricReader ? { metricReader } : {}),
+          ...(sampleRate !== undefined
+            ? {
+                sampler: new ParentBasedSampler({
+                  root: new TraceIdRatioBasedSampler(sampleRate),
+                }),
+              }
+            : {}),
+        });
+
+        await sdk.start();
+      }
+
+      const logSeverityMap: Record<string, SeverityNumber> = {
+        TRACE: 1 as SeverityNumber,
+        DEBUG: 5 as SeverityNumber,
+        INFO: 9 as SeverityNumber,
+        WARN: 13 as SeverityNumber,
+        ERROR: 17 as SeverityNumber,
+        FATAL: 21 as SeverityNumber,
+      };
+
+      const meter = metrics.getMeter("clawdbot");
+      const tracer = trace.getTracer("clawdbot");
+
+      const tokensCounter = meter.createCounter("clawdbot.tokens", {
+        unit: "1",
+        description: "Token usage by type",
+      });
+      const costCounter = meter.createCounter("clawdbot.cost.usd", {
+        unit: "1",
+        description: "Estimated model cost (USD)",
+      });
+      const durationHistogram = meter.createHistogram("clawdbot.run.duration_ms", {
+        unit: "ms",
+        description: "Agent run duration",
+      });
+      const contextHistogram = meter.createHistogram("clawdbot.context.tokens", {
+        unit: "1",
+        description: "Context window size and usage",
+      });
+      const webhookReceivedCounter = meter.createCounter("clawdbot.webhook.received", {
+        unit: "1",
+        description: "Webhook requests received",
+      });
+      const webhookErrorCounter = meter.createCounter("clawdbot.webhook.error", {
+        unit: "1",
+        description: "Webhook processing errors",
+      });
+      const webhookDurationHistogram = meter.createHistogram("clawdbot.webhook.duration_ms", {
+        unit: "ms",
+        description: "Webhook processing duration",
+      });
+      const messageQueuedCounter = meter.createCounter("clawdbot.message.queued", {
+        unit: "1",
+        description: "Messages queued for processing",
+      });
+      const messageProcessedCounter = meter.createCounter("clawdbot.message.processed", {
+        unit: "1",
+        description: "Messages processed by outcome",
+      });
+      const messageDurationHistogram = meter.createHistogram("clawdbot.message.duration_ms", {
+        unit: "ms",
+        description: "Message processing duration",
+      });
+      const queueDepthHistogram = meter.createHistogram("clawdbot.queue.depth", {
+        unit: "1",
+        description: "Queue depth on enqueue/dequeue",
+      });
+      const queueWaitHistogram = meter.createHistogram("clawdbot.queue.wait_ms", {
+        unit: "ms",
+        description: "Queue wait time before execution",
+      });
+      const laneEnqueueCounter = meter.createCounter("clawdbot.queue.lane.enqueue", {
+        unit: "1",
+        description: "Command queue lane enqueue events",
+      });
+      const laneDequeueCounter = meter.createCounter("clawdbot.queue.lane.dequeue", {
+        unit: "1",
+        description: "Command queue lane dequeue events",
+      });
+      const sessionStateCounter = meter.createCounter("clawdbot.session.state", {
+        unit: "1",
+        description: "Session state transitions",
+      });
+      const sessionStuckCounter = meter.createCounter("clawdbot.session.stuck", {
+        unit: "1",
+        description: "Sessions stuck in processing",
+      });
+      const sessionStuckAgeHistogram = meter.createHistogram("clawdbot.session.stuck_age_ms", {
+        unit: "ms",
+        description: "Age of stuck sessions",
+      });
+      const runAttemptCounter = meter.createCounter("clawdbot.run.attempt", {
+        unit: "1",
+        description: "Run attempts",
+      });
+
+      if (logsEnabled) {
+        const logExporter = new OTLPLogExporter({
+          ...(logUrl ? { url: logUrl } : {}),
+          ...(headers ? { headers } : {}),
+        });
+        logProvider = new LoggerProvider({ resource });
+        logProvider.addLogRecordProcessor(
+          new BatchLogRecordProcessor(logExporter, {
+            ...(typeof otel.flushIntervalMs === "number"
+              ? { scheduledDelayMillis: Math.max(1000, otel.flushIntervalMs) }
+              : {}),
+          }),
+        );
+        const otelLogger = logProvider.getLogger("clawdbot");
+
+        stopLogTransport = registerLogTransport((logObj) => {
+          const safeStringify = (value: unknown) => {
+            try {
+              return JSON.stringify(value);
+            } catch {
+              return String(value);
+            }
+          };
+          const meta = (logObj as Record<string, unknown>)._meta as
+            | {
+                logLevelName?: string;
+                date?: Date;
+                name?: string;
+                parentNames?: string[];
+                path?: {
+                  filePath?: string;
+                  fileLine?: string;
+                  fileColumn?: string;
+                  filePathWithLine?: string;
+                  method?: string;
+                };
+              }
+            | undefined;
+          const logLevelName = meta?.logLevelName ?? "INFO";
+          const severityNumber = logSeverityMap[logLevelName] ?? (9 as SeverityNumber);
+
+          const numericArgs = Object.entries(logObj)
+            .filter(([key]) => /^\d+$/.test(key))
+            .sort((a, b) => Number(a[0]) - Number(b[0]))
+            .map(([, value]) => value);
+
+          let bindings: Record<string, unknown> | undefined;
+          if (typeof numericArgs[0] === "string" && numericArgs[0].trim().startsWith("{")) {
+            try {
+              const parsed = JSON.parse(numericArgs[0]);
+              if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                bindings = parsed as Record<string, unknown>;
+                numericArgs.shift();
+              }
+            } catch {
+              // ignore malformed json bindings
+            }
+          }
+
+          let message = "";
+          if (numericArgs.length > 0 && typeof numericArgs[numericArgs.length - 1] === "string") {
+            message = String(numericArgs.pop());
+          } else if (numericArgs.length === 1) {
+            message = safeStringify(numericArgs[0]);
+            numericArgs.length = 0;
+          }
+          if (!message) {
+            message = "log";
+          }
+
+          const attributes: Record<string, string | number | boolean> = {
+            "clawdbot.log.level": logLevelName,
+          };
+          if (meta?.name) attributes["clawdbot.logger"] = meta.name;
+          if (meta?.parentNames?.length) {
+            attributes["clawdbot.logger.parents"] = meta.parentNames.join(".");
+          }
+          if (bindings) {
+            for (const [key, value] of Object.entries(bindings)) {
+              if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+                attributes[`clawdbot.${key}`] = value;
+              } else if (value != null) {
+                attributes[`clawdbot.${key}`] = safeStringify(value);
+              }
+            }
+          }
+          if (numericArgs.length > 0) {
+            attributes["clawdbot.log.args"] = safeStringify(numericArgs);
+          }
+          if (meta?.path?.filePath) attributes["code.filepath"] = meta.path.filePath;
+          if (meta?.path?.fileLine) attributes["code.lineno"] = Number(meta.path.fileLine);
+          if (meta?.path?.method) attributes["code.function"] = meta.path.method;
+          if (meta?.path?.filePathWithLine) {
+            attributes["clawdbot.code.location"] = meta.path.filePathWithLine;
+          }
+
+          otelLogger.emit({
+            body: message,
+            severityText: logLevelName,
+            severityNumber,
+            attributes,
+            timestamp: meta?.date ?? new Date(),
+          });
+        });
+      }
+
+      const spanWithDuration = (
+        name: string,
+        attributes: Record<string, string | number>,
+        durationMs?: number,
+      ) => {
+        const startTime =
+          typeof durationMs === "number" ? Date.now() - Math.max(0, durationMs) : undefined;
+        const span = tracer.startSpan(name, {
+          attributes,
+          ...(startTime ? { startTime } : {}),
+        });
+        return span;
+      };
+
+      const recordModelUsage = (evt: Extract<DiagnosticEventPayload, { type: "model.usage" }>) => {
+        const attrs = {
+          "clawdbot.channel": evt.channel ?? "unknown",
+          "clawdbot.provider": evt.provider ?? "unknown",
+          "clawdbot.model": evt.model ?? "unknown",
+        };
+
+        const usage = evt.usage;
+        if (usage.input) tokensCounter.add(usage.input, { ...attrs, "clawdbot.token": "input" });
+        if (usage.output) tokensCounter.add(usage.output, { ...attrs, "clawdbot.token": "output" });
+        if (usage.cacheRead)
+          tokensCounter.add(usage.cacheRead, { ...attrs, "clawdbot.token": "cache_read" });
+        if (usage.cacheWrite)
+          tokensCounter.add(usage.cacheWrite, { ...attrs, "clawdbot.token": "cache_write" });
+        if (usage.promptTokens)
+          tokensCounter.add(usage.promptTokens, { ...attrs, "clawdbot.token": "prompt" });
+        if (usage.total) tokensCounter.add(usage.total, { ...attrs, "clawdbot.token": "total" });
+
+        if (evt.costUsd) costCounter.add(evt.costUsd, attrs);
+        if (evt.durationMs) durationHistogram.record(evt.durationMs, attrs);
+        if (evt.context?.limit)
+          contextHistogram.record(evt.context.limit, {
+            ...attrs,
+            "clawdbot.context": "limit",
+          });
+        if (evt.context?.used)
+          contextHistogram.record(evt.context.used, {
+            ...attrs,
+            "clawdbot.context": "used",
+          });
+
+        if (!tracesEnabled) return;
+        const spanAttrs: Record<string, string | number> = {
+          ...attrs,
+          "clawdbot.sessionKey": evt.sessionKey ?? "",
+          "clawdbot.sessionId": evt.sessionId ?? "",
+          "clawdbot.tokens.input": usage.input ?? 0,
+          "clawdbot.tokens.output": usage.output ?? 0,
+          "clawdbot.tokens.cache_read": usage.cacheRead ?? 0,
+          "clawdbot.tokens.cache_write": usage.cacheWrite ?? 0,
+          "clawdbot.tokens.total": usage.total ?? 0,
+        };
+
+        const span = spanWithDuration("clawdbot.model.usage", spanAttrs, evt.durationMs);
+        span.end();
+      };
+
+      const recordWebhookReceived = (
+        evt: Extract<DiagnosticEventPayload, { type: "webhook.received" }>,
+      ) => {
+        const attrs = {
+          "clawdbot.channel": evt.channel ?? "unknown",
+          "clawdbot.webhook": evt.updateType ?? "unknown",
+        };
+        webhookReceivedCounter.add(1, attrs);
+      };
+
+      const recordWebhookProcessed = (
+        evt: Extract<DiagnosticEventPayload, { type: "webhook.processed" }>,
+      ) => {
+        const attrs = {
+          "clawdbot.channel": evt.channel ?? "unknown",
+          "clawdbot.webhook": evt.updateType ?? "unknown",
+        };
+        if (typeof evt.durationMs === "number") {
+          webhookDurationHistogram.record(evt.durationMs, attrs);
+        }
+        if (!tracesEnabled) return;
+        const spanAttrs: Record<string, string | number> = { ...attrs };
+        if (evt.chatId !== undefined) spanAttrs["clawdbot.chatId"] = String(evt.chatId);
+        const span = spanWithDuration("clawdbot.webhook.processed", spanAttrs, evt.durationMs);
+        span.end();
+      };
+
+      const recordWebhookError = (
+        evt: Extract<DiagnosticEventPayload, { type: "webhook.error" }>,
+      ) => {
+        const attrs = {
+          "clawdbot.channel": evt.channel ?? "unknown",
+          "clawdbot.webhook": evt.updateType ?? "unknown",
+        };
+        webhookErrorCounter.add(1, attrs);
+        if (!tracesEnabled) return;
+        const spanAttrs: Record<string, string | number> = {
+          ...attrs,
+          "clawdbot.error": evt.error,
+        };
+        if (evt.chatId !== undefined) spanAttrs["clawdbot.chatId"] = String(evt.chatId);
+        const span = tracer.startSpan("clawdbot.webhook.error", {
+          attributes: spanAttrs,
+        });
+        span.setStatus({ code: SpanStatusCode.ERROR, message: evt.error });
+        span.end();
+      };
+
+      const recordMessageQueued = (
+        evt: Extract<DiagnosticEventPayload, { type: "message.queued" }>,
+      ) => {
+        const attrs = {
+          "clawdbot.channel": evt.channel ?? "unknown",
+          "clawdbot.source": evt.source ?? "unknown",
+        };
+        messageQueuedCounter.add(1, attrs);
+        if (typeof evt.queueDepth === "number") {
+          queueDepthHistogram.record(evt.queueDepth, attrs);
+        }
+      };
+
+      const recordMessageProcessed = (
+        evt: Extract<DiagnosticEventPayload, { type: "message.processed" }>,
+      ) => {
+        const attrs = {
+          "clawdbot.channel": evt.channel ?? "unknown",
+          "clawdbot.outcome": evt.outcome ?? "unknown",
+        };
+        messageProcessedCounter.add(1, attrs);
+        if (typeof evt.durationMs === "number") {
+          messageDurationHistogram.record(evt.durationMs, attrs);
+        }
+        if (!tracesEnabled) return;
+        const spanAttrs: Record<string, string | number> = { ...attrs };
+        if (evt.sessionKey) spanAttrs["clawdbot.sessionKey"] = evt.sessionKey;
+        if (evt.sessionId) spanAttrs["clawdbot.sessionId"] = evt.sessionId;
+        if (evt.chatId !== undefined) spanAttrs["clawdbot.chatId"] = String(evt.chatId);
+        if (evt.messageId !== undefined) spanAttrs["clawdbot.messageId"] = String(evt.messageId);
+        if (evt.reason) spanAttrs["clawdbot.reason"] = evt.reason;
+        const span = spanWithDuration("clawdbot.message.processed", spanAttrs, evt.durationMs);
+        if (evt.outcome === "error") {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: evt.error });
+        }
+        span.end();
+      };
+
+      const recordLaneEnqueue = (
+        evt: Extract<DiagnosticEventPayload, { type: "queue.lane.enqueue" }>,
+      ) => {
+        const attrs = { "clawdbot.lane": evt.lane };
+        laneEnqueueCounter.add(1, attrs);
+        queueDepthHistogram.record(evt.queueSize, attrs);
+      };
+
+      const recordLaneDequeue = (
+        evt: Extract<DiagnosticEventPayload, { type: "queue.lane.dequeue" }>,
+      ) => {
+        const attrs = { "clawdbot.lane": evt.lane };
+        laneDequeueCounter.add(1, attrs);
+        queueDepthHistogram.record(evt.queueSize, attrs);
+        if (typeof evt.waitMs === "number") {
+          queueWaitHistogram.record(evt.waitMs, attrs);
+        }
+      };
+
+      const recordSessionState = (
+        evt: Extract<DiagnosticEventPayload, { type: "session.state" }>,
+      ) => {
+        const attrs: Record<string, string> = { "clawdbot.state": evt.state };
+        if (evt.reason) attrs["clawdbot.reason"] = evt.reason;
+        sessionStateCounter.add(1, attrs);
+      };
+
+      const recordSessionStuck = (
+        evt: Extract<DiagnosticEventPayload, { type: "session.stuck" }>,
+      ) => {
+        const attrs: Record<string, string> = { "clawdbot.state": evt.state };
+        sessionStuckCounter.add(1, attrs);
+        if (typeof evt.ageMs === "number") {
+          sessionStuckAgeHistogram.record(evt.ageMs, attrs);
+        }
+        if (!tracesEnabled) return;
+        const spanAttrs: Record<string, string | number> = { ...attrs };
+        if (evt.sessionKey) spanAttrs["clawdbot.sessionKey"] = evt.sessionKey;
+        if (evt.sessionId) spanAttrs["clawdbot.sessionId"] = evt.sessionId;
+        spanAttrs["clawdbot.queueDepth"] = evt.queueDepth ?? 0;
+        spanAttrs["clawdbot.ageMs"] = evt.ageMs;
+        const span = tracer.startSpan("clawdbot.session.stuck", { attributes: spanAttrs });
+        span.setStatus({ code: SpanStatusCode.ERROR, message: "session stuck" });
+        span.end();
+      };
+
+      const recordRunAttempt = (evt: Extract<DiagnosticEventPayload, { type: "run.attempt" }>) => {
+        runAttemptCounter.add(1, { "clawdbot.attempt": evt.attempt });
+      };
+
+      const recordHeartbeat = (
+        evt: Extract<DiagnosticEventPayload, { type: "diagnostic.heartbeat" }>,
+      ) => {
+        queueDepthHistogram.record(evt.queued, { "clawdbot.channel": "heartbeat" });
+      };
+
+      unsubscribe = onDiagnosticEvent((evt: DiagnosticEventPayload) => {
+        switch (evt.type) {
+          case "model.usage":
+            recordModelUsage(evt);
+            return;
+          case "webhook.received":
+            recordWebhookReceived(evt);
+            return;
+          case "webhook.processed":
+            recordWebhookProcessed(evt);
+            return;
+          case "webhook.error":
+            recordWebhookError(evt);
+            return;
+          case "message.queued":
+            recordMessageQueued(evt);
+            return;
+          case "message.processed":
+            recordMessageProcessed(evt);
+            return;
+          case "queue.lane.enqueue":
+            recordLaneEnqueue(evt);
+            return;
+          case "queue.lane.dequeue":
+            recordLaneDequeue(evt);
+            return;
+          case "session.state":
+            recordSessionState(evt);
+            return;
+          case "session.stuck":
+            recordSessionStuck(evt);
+            return;
+          case "run.attempt":
+            recordRunAttempt(evt);
+            return;
+          case "diagnostic.heartbeat":
+            recordHeartbeat(evt);
+            return;
+        }
+      });
+
+      if (logsEnabled) {
+        ctx.logger.info("diagnostics-otel: logs exporter enabled (OTLP/HTTP)");
+      }
+    },
+    async stop() {
+      unsubscribe?.();
+      unsubscribe = null;
+      stopLogTransport?.();
+      stopLogTransport = null;
+      if (logProvider) {
+        await logProvider.shutdown().catch(() => undefined);
+        logProvider = null;
+      }
+      if (sdk) {
+        await sdk.shutdown().catch(() => undefined);
+        sdk = null;
+      }
+    },
+  } satisfies ClawdbotPluginService;
+}

extensions/nostr/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 2026.1.19-1
+
+Initial release.
+
+### Features
+
+- NIP-04 encrypted DM support (kind:4 events)
+- Key validation (hex and nsec formats)
+- Multi-relay support with sequential fallback
+- Event signature verification
+- TTL-based deduplication (24h)
+- Access control via dmPolicy (pairing, allowlist, open, disabled)
+- Pubkey normalization (hex/npub)
+
+### Protocol Support
+
+- NIP-01: Basic event structure
+- NIP-04: Encrypted direct messages
+
+### Planned for v2
+
+- NIP-17: Gift-wrapped DMs
+- NIP-44: Versioned encryption
+- Media attachments

extensions/nostr/README.md

@@ -0,0 +1,136 @@
+# @clawdbot/nostr
+
+Nostr DM channel plugin for Clawdbot using NIP-04 encrypted direct messages.
+
+## Overview
+
+This extension adds Nostr as a messaging channel to Clawdbot. It enables your bot to:
+
+- Receive encrypted DMs from Nostr users
+- Send encrypted responses back
+- Work with any NIP-04 compatible Nostr client (Damus, Amethyst, etc.)
+
+## Installation
+
+```bash
+clawdbot plugins install @clawdbot/nostr
+```
+
+## Quick Setup
+
+1. Generate a Nostr keypair (if you don't have one):
+   ```bash
+   # Using nak CLI
+   nak key generate
+
+   # Or use any Nostr key generator
+   ```
+
+2. Add to your config:
+   ```json
+   {
+     "channels": {
+       "nostr": {
+         "privateKey": "${NOSTR_PRIVATE_KEY}",
+         "relays": ["wss://relay.damus.io", "wss://nos.lol"]
+       }
+     }
+   }
+   ```
+
+3. Set the environment variable:
+   ```bash
+   export NOSTR_PRIVATE_KEY="nsec1..."  # or hex format
+   ```
+
+4. Restart the gateway
+
+## Configuration
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `privateKey` | string | required | Bot's private key (nsec or hex format) |
+| `relays` | string[] | `["wss://relay.damus.io", "wss://nos.lol"]` | WebSocket relay URLs |
+| `dmPolicy` | string | `"pairing"` | Access control: `pairing`, `allowlist`, `open`, `disabled` |
+| `allowFrom` | string[] | `[]` | Allowed sender pubkeys (npub or hex) |
+| `enabled` | boolean | `true` | Enable/disable the channel |
+| `name` | string | - | Display name for the account |
+
+## Access Control
+
+### DM Policies
+
+- **pairing** (default): Unknown senders receive a pairing code to request access
+- **allowlist**: Only pubkeys in `allowFrom` can message the bot
+- **open**: Anyone can message the bot (use with caution)
+- **disabled**: DMs are disabled
+
+### Example: Allowlist Mode
+
+```json
+{
+  "channels": {
+    "nostr": {
+      "privateKey": "${NOSTR_PRIVATE_KEY}",
+      "dmPolicy": "allowlist",
+      "allowFrom": [
+        "npub1abc...",
+        "0123456789abcdef..."
+      ]
+    }
+  }
+}
+```
+
+## Testing
+
+### Local Relay (Recommended)
+
+```bash
+# Using strfry
+docker run -p 7777:7777 ghcr.io/hoytech/strfry
+
+# Configure clawdbot to use local relay
+"relays": ["ws://localhost:7777"]
+```
+
+### Manual Test
+
+1. Start the gateway with Nostr configured
+2. Open Damus, Amethyst, or another Nostr client
+3. Send a DM to your bot's npub
+4. Verify the bot responds
+
+## Protocol Support
+
+| NIP | Status | Notes |
+|-----|--------|-------|
+| NIP-01 | Supported | Basic event structure |
+| NIP-04 | Supported | Encrypted DMs (kind:4) |
+| NIP-17 | Planned | Gift-wrapped DMs (v2) |
+
+## Security Notes
+
+- Private keys are never logged
+- Event signatures are verified before processing
+- Use environment variables for keys, never commit to config files
+- Consider using `allowlist` mode in production
+
+## Troubleshooting
+
+### Bot not receiving messages
+
+1. Verify private key is correctly configured
+2. Check relay connectivity
+3. Ensure `enabled` is not set to `false`
+4. Check the bot's public key matches what you're sending to
+
+### Messages not being delivered
+
+1. Check relay URLs are correct (must use `wss://`)
+2. Verify relays are online and accepting connections
+3. Check for rate limiting (reduce message frequency)
+
+## License
+
+MIT

extensions/nostr/clawdbot.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "nostr",
+  "channels": [
+    "nostr"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/nostr/index.ts

@@ -0,0 +1,69 @@
+import type { ClawdbotPluginApi, ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+
+import { nostrPlugin } from "./src/channel.js";
+import { setNostrRuntime, getNostrRuntime } from "./src/runtime.js";
+import { createNostrProfileHttpHandler } from "./src/nostr-profile-http.js";
+import { resolveNostrAccount } from "./src/types.js";
+import type { NostrProfile } from "./src/config-schema.js";
+
+const plugin = {
+  id: "nostr",
+  name: "Nostr",
+  description: "Nostr DM channel plugin via NIP-04",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setNostrRuntime(api.runtime);
+    api.registerChannel({ plugin: nostrPlugin });
+
+    // Register HTTP handler for profile management
+    const httpHandler = createNostrProfileHttpHandler({
+      getConfigProfile: (accountId: string) => {
+        const runtime = getNostrRuntime();
+        const cfg = runtime.config.loadConfig() as ClawdbotConfig;
+        const account = resolveNostrAccount({ cfg, accountId });
+        return account.profile;
+      },
+      updateConfigProfile: async (accountId: string, profile: NostrProfile) => {
+        const runtime = getNostrRuntime();
+        const cfg = runtime.config.loadConfig() as ClawdbotConfig;
+
+        // Build the config patch for channels.nostr.profile
+        const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+        const nostrConfig = (channels.nostr ?? {}) as Record<string, unknown>;
+
+        const updatedNostrConfig = {
+          ...nostrConfig,
+          profile,
+        };
+
+        const updatedChannels = {
+          ...channels,
+          nostr: updatedNostrConfig,
+        };
+
+        await runtime.config.writeConfigFile({
+          ...cfg,
+          channels: updatedChannels,
+        });
+      },
+      getAccountInfo: (accountId: string) => {
+        const runtime = getNostrRuntime();
+        const cfg = runtime.config.loadConfig() as ClawdbotConfig;
+        const account = resolveNostrAccount({ cfg, accountId });
+        if (!account.configured || !account.publicKey) {
+          return null;
+        }
+        return {
+          pubkey: account.publicKey,
+          relays: account.relays,
+        };
+      },
+      log: api.logger,
+    });
+
+    api.registerHttpHandler(httpHandler);
+  },
+};
+
+export default plugin;

extensions/nostr/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@clawdbot/nostr",
+  "version": "2026.1.19-1",
+  "type": "module",
+  "description": "Clawdbot Nostr channel plugin for NIP-04 encrypted DMs",
+  "clawdbot": {
+    "extensions": ["./index.ts"],
+    "channel": {
+      "id": "nostr",
+      "label": "Nostr",
+      "selectionLabel": "Nostr (NIP-04 DMs)",
+      "docsPath": "/channels/nostr",
+      "docsLabel": "nostr",
+      "blurb": "Decentralized protocol; encrypted DMs via NIP-04.",
+      "order": 55,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@clawdbot/nostr",
+      "localPath": "extensions/nostr",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "clawdbot": "workspace:*",
+    "nostr-tools": "^2.10.4",
+    "zod": "^4.3.5"
+  }
+}

extensions/nostr/src/channel.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import { nostrPlugin } from "./channel.js";
+
+describe("nostrPlugin", () => {
+  describe("meta", () => {
+    it("has correct id", () => {
+      expect(nostrPlugin.id).toBe("nostr");
+    });
+
+    it("has required meta fields", () => {
+      expect(nostrPlugin.meta.label).toBe("Nostr");
+      expect(nostrPlugin.meta.docsPath).toBe("/channels/nostr");
+      expect(nostrPlugin.meta.blurb).toContain("NIP-04");
+    });
+  });
+
+  describe("capabilities", () => {
+    it("supports direct messages", () => {
+      expect(nostrPlugin.capabilities.chatTypes).toContain("direct");
+    });
+
+    it("does not support groups (MVP)", () => {
+      expect(nostrPlugin.capabilities.chatTypes).not.toContain("group");
+    });
+
+    it("does not support media (MVP)", () => {
+      expect(nostrPlugin.capabilities.media).toBe(false);
+    });
+  });
+
+  describe("config adapter", () => {
+    it("has required config functions", () => {
+      expect(nostrPlugin.config.listAccountIds).toBeTypeOf("function");
+      expect(nostrPlugin.config.resolveAccount).toBeTypeOf("function");
+      expect(nostrPlugin.config.isConfigured).toBeTypeOf("function");
+    });
+
+    it("listAccountIds returns empty array for unconfigured", () => {
+      const cfg = { channels: {} };
+      const ids = nostrPlugin.config.listAccountIds(cfg);
+      expect(ids).toEqual([]);
+    });
+
+    it("listAccountIds returns default for configured", () => {
+      const cfg = {
+        channels: {
+          nostr: {
+            privateKey: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+          },
+        },
+      };
+      const ids = nostrPlugin.config.listAccountIds(cfg);
+      expect(ids).toContain("default");
+    });
+  });
+
+  describe("messaging", () => {
+    it("has target resolver", () => {
+      expect(nostrPlugin.messaging?.targetResolver?.looksLikeId).toBeTypeOf("function");
+    });
+
+    it("recognizes npub as valid target", () => {
+      const looksLikeId = nostrPlugin.messaging?.targetResolver?.looksLikeId;
+      if (!looksLikeId) return;
+
+      expect(looksLikeId("npub1xyz123")).toBe(true);
+    });
+
+    it("recognizes hex pubkey as valid target", () => {
+      const looksLikeId = nostrPlugin.messaging?.targetResolver?.looksLikeId;
+      if (!looksLikeId) return;
+
+      const hexPubkey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(looksLikeId(hexPubkey)).toBe(true);
+    });
+
+    it("rejects invalid input", () => {
+      const looksLikeId = nostrPlugin.messaging?.targetResolver?.looksLikeId;
+      if (!looksLikeId) return;
+
+      expect(looksLikeId("not-a-pubkey")).toBe(false);
+      expect(looksLikeId("")).toBe(false);
+    });
+
+    it("normalizeTarget strips nostr: prefix", () => {
+      const normalize = nostrPlugin.messaging?.normalizeTarget;
+      if (!normalize) return;
+
+      const hexPubkey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(normalize(`nostr:${hexPubkey}`)).toBe(hexPubkey);
+    });
+  });
+
+  describe("outbound", () => {
+    it("has correct delivery mode", () => {
+      expect(nostrPlugin.outbound?.deliveryMode).toBe("direct");
+    });
+
+    it("has reasonable text chunk limit", () => {
+      expect(nostrPlugin.outbound?.textChunkLimit).toBe(4000);
+    });
+  });
+
+  describe("pairing", () => {
+    it("has id label for pairing", () => {
+      expect(nostrPlugin.pairing?.idLabel).toBe("nostrPubkey");
+    });
+
+    it("normalizes nostr: prefix in allow entries", () => {
+      const normalize = nostrPlugin.pairing?.normalizeAllowEntry;
+      if (!normalize) return;
+
+      const hexPubkey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(normalize(`nostr:${hexPubkey}`)).toBe(hexPubkey);
+    });
+  });
+
+  describe("security", () => {
+    it("has resolveDmPolicy function", () => {
+      expect(nostrPlugin.security?.resolveDmPolicy).toBeTypeOf("function");
+    });
+  });
+
+  describe("gateway", () => {
+    it("has startAccount function", () => {
+      expect(nostrPlugin.gateway?.startAccount).toBeTypeOf("function");
+    });
+  });
+
+  describe("status", () => {
+    it("has default runtime", () => {
+      expect(nostrPlugin.status?.defaultRuntime).toBeDefined();
+      expect(nostrPlugin.status?.defaultRuntime?.accountId).toBe("default");
+      expect(nostrPlugin.status?.defaultRuntime?.running).toBe(false);
+    });
+
+    it("has buildAccountSnapshot function", () => {
+      expect(nostrPlugin.status?.buildAccountSnapshot).toBeTypeOf("function");
+    });
+  });
+});

extensions/nostr/src/channel.ts

@@ -0,0 +1,335 @@
+import {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  formatPairingApproveHint,
+  type ChannelPlugin,
+} from "clawdbot/plugin-sdk";
+
+import { NostrConfigSchema } from "./config-schema.js";
+import { getNostrRuntime } from "./runtime.js";
+import {
+  listNostrAccountIds,
+  resolveDefaultNostrAccountId,
+  resolveNostrAccount,
+  type ResolvedNostrAccount,
+} from "./types.js";
+import { normalizePubkey, startNostrBus, type NostrBusHandle } from "./nostr-bus.js";
+import type { MetricEvent, MetricsSnapshot } from "./metrics.js";
+import type { NostrProfile } from "./config-schema.js";
+import type { ProfilePublishResult } from "./nostr-profile.js";
+
+// Store active bus handles per account
+const activeBuses = new Map<string, NostrBusHandle>();
+
+// Store metrics snapshots per account (for status reporting)
+const metricsSnapshots = new Map<string, MetricsSnapshot>();
+
+export const nostrPlugin: ChannelPlugin<ResolvedNostrAccount> = {
+  id: "nostr",
+  meta: {
+    id: "nostr",
+    label: "Nostr",
+    selectionLabel: "Nostr",
+    docsPath: "/channels/nostr",
+    docsLabel: "nostr",
+    blurb: "Decentralized DMs via Nostr relays (NIP-04)",
+    order: 100,
+  },
+  capabilities: {
+    chatTypes: ["direct"], // DMs only for MVP
+    media: false, // No media for MVP
+  },
+  reload: { configPrefixes: ["channels.nostr"] },
+  configSchema: buildChannelConfigSchema(NostrConfigSchema),
+
+  config: {
+    listAccountIds: (cfg) => listNostrAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveNostrAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultNostrAccountId(cfg),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      publicKey: account.publicKey,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveNostrAccount({ cfg, accountId }).config.allowFrom ?? []).map((entry) =>
+        String(entry)
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => {
+          if (entry === "*") return "*";
+          try {
+            return normalizePubkey(entry);
+          } catch {
+            return entry; // Keep as-is if normalization fails
+          }
+        })
+        .filter(Boolean),
+  },
+
+  pairing: {
+    idLabel: "nostrPubkey",
+    normalizeAllowEntry: (entry) => {
+      try {
+        return normalizePubkey(entry.replace(/^nostr:/i, ""));
+      } catch {
+        return entry;
+      }
+    },
+    notifyApproval: async ({ id }) => {
+      // Get the default account's bus and send approval message
+      const bus = activeBuses.get(DEFAULT_ACCOUNT_ID);
+      if (bus) {
+        await bus.sendDm(id, "Your pairing request has been approved!");
+      }
+    },
+  },
+
+  security: {
+    resolveDmPolicy: ({ account }) => {
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: "channels.nostr.dmPolicy",
+        allowFromPath: "channels.nostr.allowFrom",
+        approveHint: formatPairingApproveHint("nostr"),
+        normalizeEntry: (raw) => {
+          try {
+            return normalizePubkey(raw.replace(/^nostr:/i, "").trim());
+          } catch {
+            return raw.trim();
+          }
+        },
+      };
+    },
+  },
+
+  messaging: {
+    normalizeTarget: (target) => {
+      // Strip nostr: prefix if present
+      const cleaned = target.replace(/^nostr:/i, "").trim();
+      try {
+        return normalizePubkey(cleaned);
+      } catch {
+        return cleaned;
+      }
+    },
+    targetResolver: {
+      looksLikeId: (input) => {
+        const trimmed = input.trim();
+        return trimmed.startsWith("npub1") || /^[0-9a-fA-F]{64}$/.test(trimmed);
+      },
+      hint: "<npub|hex pubkey|nostr:npub...>",
+    },
+  },
+
+  outbound: {
+    deliveryMode: "direct",
+    textChunkLimit: 4000,
+    sendText: async ({ to, text, accountId }) => {
+      const aid = accountId ?? DEFAULT_ACCOUNT_ID;
+      const bus = activeBuses.get(aid);
+      if (!bus) {
+        throw new Error(`Nostr bus not running for account ${aid}`);
+      }
+      const normalizedTo = normalizePubkey(to);
+      await bus.sendDm(normalizedTo, text);
+      return { channel: "nostr", to: normalizedTo };
+    },
+  },
+
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((account) => {
+        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
+        if (!lastError) return [];
+        return [
+          {
+            channel: "nostr",
+            accountId: account.accountId,
+            kind: "runtime" as const,
+            message: `Channel error: ${lastError}`,
+          },
+        ];
+      }),
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      publicKey: snapshot.publicKey ?? null,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+    }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      publicKey: account.publicKey,
+      profile: account.profile,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({
+        accountId: account.accountId,
+        publicKey: account.publicKey,
+      });
+      ctx.log?.info(`[${account.accountId}] starting Nostr provider (pubkey: ${account.publicKey})`);
+
+      if (!account.configured) {
+        throw new Error("Nostr private key not configured");
+      }
+
+      const runtime = getNostrRuntime();
+
+      // Track bus handle for metrics callback
+      let busHandle: NostrBusHandle | null = null;
+
+      const bus = await startNostrBus({
+        accountId: account.accountId,
+        privateKey: account.privateKey,
+        relays: account.relays,
+        onMessage: async (senderPubkey, text, reply) => {
+          ctx.log?.debug(`[${account.accountId}] DM from ${senderPubkey}: ${text.slice(0, 50)}...`);
+
+          // Forward to clawdbot's message pipeline
+          await runtime.channel.reply.handleInboundMessage({
+            channel: "nostr",
+            accountId: account.accountId,
+            senderId: senderPubkey,
+            chatType: "direct",
+            chatId: senderPubkey, // For DMs, chatId is the sender's pubkey
+            text,
+            reply: async (responseText: string) => {
+              await reply(responseText);
+            },
+          });
+        },
+        onError: (error, context) => {
+          ctx.log?.error(`[${account.accountId}] Nostr error (${context}): ${error.message}`);
+        },
+        onConnect: (relay) => {
+          ctx.log?.debug(`[${account.accountId}] Connected to relay: ${relay}`);
+        },
+        onDisconnect: (relay) => {
+          ctx.log?.debug(`[${account.accountId}] Disconnected from relay: ${relay}`);
+        },
+        onEose: (relays) => {
+          ctx.log?.debug(`[${account.accountId}] EOSE received from relays: ${relays}`);
+        },
+        onMetric: (event: MetricEvent) => {
+          // Log significant metrics at appropriate levels
+          if (event.name.startsWith("event.rejected.")) {
+            ctx.log?.debug(`[${account.accountId}] Metric: ${event.name}`, event.labels);
+          } else if (event.name === "relay.circuit_breaker.open") {
+            ctx.log?.warn(`[${account.accountId}] Circuit breaker opened for relay: ${event.labels?.relay}`);
+          } else if (event.name === "relay.circuit_breaker.close") {
+            ctx.log?.info(`[${account.accountId}] Circuit breaker closed for relay: ${event.labels?.relay}`);
+          } else if (event.name === "relay.error") {
+            ctx.log?.debug(`[${account.accountId}] Relay error: ${event.labels?.relay}`);
+          }
+          // Update cached metrics snapshot
+          if (busHandle) {
+            metricsSnapshots.set(account.accountId, busHandle.getMetrics());
+          }
+        },
+      });
+
+      busHandle = bus;
+
+      // Store the bus handle
+      activeBuses.set(account.accountId, bus);
+
+      ctx.log?.info(`[${account.accountId}] Nostr provider started, connected to ${account.relays.length} relay(s)`);
+
+      // Return cleanup function
+      return {
+        stop: () => {
+          bus.close();
+          activeBuses.delete(account.accountId);
+          metricsSnapshots.delete(account.accountId);
+          ctx.log?.info(`[${account.accountId}] Nostr provider stopped`);
+        },
+      };
+    },
+  },
+};
+
+/**
+ * Get metrics snapshot for a Nostr account.
+ * Returns undefined if account is not running.
+ */
+export function getNostrMetrics(accountId: string = DEFAULT_ACCOUNT_ID): MetricsSnapshot | undefined {
+  const bus = activeBuses.get(accountId);
+  if (bus) {
+    return bus.getMetrics();
+  }
+  return metricsSnapshots.get(accountId);
+}
+
+/**
+ * Get all active Nostr bus handles.
+ * Useful for debugging and status reporting.
+ */
+export function getActiveNostrBuses(): Map<string, NostrBusHandle> {
+  return new Map(activeBuses);
+}
+
+/**
+ * Publish a profile (kind:0) for a Nostr account.
+ * @param accountId - Account ID (defaults to "default")
+ * @param profile - Profile data to publish
+ * @returns Publish results with successes and failures
+ * @throws Error if account is not running
+ */
+export async function publishNostrProfile(
+  accountId: string = DEFAULT_ACCOUNT_ID,
+  profile: NostrProfile
+): Promise<ProfilePublishResult> {
+  const bus = activeBuses.get(accountId);
+  if (!bus) {
+    throw new Error(`Nostr bus not running for account ${accountId}`);
+  }
+  return bus.publishProfile(profile);
+}
+
+/**
+ * Get profile publish state for a Nostr account.
+ * @param accountId - Account ID (defaults to "default")
+ * @returns Profile publish state or null if account not running
+ */
+export async function getNostrProfileState(
+  accountId: string = DEFAULT_ACCOUNT_ID
+): Promise<{
+  lastPublishedAt: number | null;
+  lastPublishedEventId: string | null;
+  lastPublishResults: Record<string, "ok" | "failed" | "timeout"> | null;
+} | null> {
+  const bus = activeBuses.get(accountId);
+  if (!bus) {
+    return null;
+  }
+  return bus.getProfileState();
+}

extensions/nostr/src/config-schema.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { buildChannelConfigSchema } from "clawdbot/plugin-sdk";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+/**
+ * Validates https:// URLs only (no javascript:, data:, file:, etc.)
+ */
+const safeUrlSchema = z
+  .string()
+  .url()
+  .refine(
+    (url) => {
+      try {
+        const parsed = new URL(url);
+        return parsed.protocol === "https:";
+      } catch {
+        return false;
+      }
+    },
+    { message: "URL must use https:// protocol" }
+  );
+
+/**
+ * NIP-01 profile metadata schema
+ * https://github.com/nostr-protocol/nips/blob/master/01.md
+ */
+export const NostrProfileSchema = z.object({
+  /** Username (NIP-01: name) - max 256 chars */
+  name: z.string().max(256).optional(),
+
+  /** Display name (NIP-01: display_name) - max 256 chars */
+  displayName: z.string().max(256).optional(),
+
+  /** Bio/description (NIP-01: about) - max 2000 chars */
+  about: z.string().max(2000).optional(),
+
+  /** Profile picture URL (must be https) */
+  picture: safeUrlSchema.optional(),
+
+  /** Banner image URL (must be https) */
+  banner: safeUrlSchema.optional(),
+
+  /** Website URL (must be https) */
+  website: safeUrlSchema.optional(),
+
+  /** NIP-05 identifier (e.g., "user@example.com") */
+  nip05: z.string().optional(),
+
+  /** Lightning address (LUD-16) */
+  lud16: z.string().optional(),
+});
+
+export type NostrProfile = z.infer<typeof NostrProfileSchema>;
+
+/**
+ * Zod schema for channels.nostr.* configuration
+ */
+export const NostrConfigSchema = z.object({
+  /** Account name (optional display name) */
+  name: z.string().optional(),
+
+  /** Whether this channel is enabled */
+  enabled: z.boolean().optional(),
+
+  /** Private key in hex or nsec bech32 format */
+  privateKey: z.string().optional(),
+
+  /** WebSocket relay URLs to connect to */
+  relays: z.array(z.string()).optional(),
+
+  /** DM access policy: pairing, allowlist, open, or disabled */
+  dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+
+  /** Allowed sender pubkeys (npub or hex format) */
+  allowFrom: z.array(allowFromEntry).optional(),
+
+  /** Profile metadata (NIP-01 kind:0 content) */
+  profile: NostrProfileSchema.optional(),
+});
+
+export type NostrConfig = z.infer<typeof NostrConfigSchema>;
+
+/**
+ * JSON Schema for Control UI (converted from Zod)
+ */
+export const nostrChannelConfigSchema = buildChannelConfigSchema(NostrConfigSchema);

extensions/nostr/src/metrics.ts

@@ -0,0 +1,464 @@
+/**
+ * Comprehensive metrics system for Nostr bus observability.
+ * Provides clear insight into what's happening with events, relays, and operations.
+ */
+
+// ============================================================================
+// Metric Types
+// ============================================================================
+
+export type EventMetricName =
+  | "event.received"
+  | "event.processed"
+  | "event.duplicate"
+  | "event.rejected.invalid_shape"
+  | "event.rejected.wrong_kind"
+  | "event.rejected.stale"
+  | "event.rejected.future"
+  | "event.rejected.rate_limited"
+  | "event.rejected.invalid_signature"
+  | "event.rejected.oversized_ciphertext"
+  | "event.rejected.oversized_plaintext"
+  | "event.rejected.decrypt_failed"
+  | "event.rejected.self_message";
+
+export type RelayMetricName =
+  | "relay.connect"
+  | "relay.disconnect"
+  | "relay.reconnect"
+  | "relay.error"
+  | "relay.message.event"
+  | "relay.message.eose"
+  | "relay.message.closed"
+  | "relay.message.notice"
+  | "relay.message.ok"
+  | "relay.message.auth"
+  | "relay.circuit_breaker.open"
+  | "relay.circuit_breaker.close"
+  | "relay.circuit_breaker.half_open";
+
+export type RateLimitMetricName = "rate_limit.per_sender" | "rate_limit.global";
+
+export type DecryptMetricName = "decrypt.success" | "decrypt.failure";
+
+export type MemoryMetricName =
+  | "memory.seen_tracker_size"
+  | "memory.rate_limiter_entries";
+
+export type MetricName =
+  | EventMetricName
+  | RelayMetricName
+  | RateLimitMetricName
+  | DecryptMetricName
+  | MemoryMetricName;
+
+// ============================================================================
+// Metric Event
+// ============================================================================
+
+export interface MetricEvent {
+  /** Metric name (e.g., "event.received", "relay.connect") */
+  name: MetricName;
+  /** Metric value (usually 1 for counters, or a measured value) */
+  value: number;
+  /** Unix timestamp in milliseconds */
+  timestamp: number;
+  /** Optional labels for additional context */
+  labels?: Record<string, string | number>;
+}
+
+export type OnMetricCallback = (event: MetricEvent) => void;
+
+// ============================================================================
+// Metrics Snapshot (for getMetrics())
+// ============================================================================
+
+export interface MetricsSnapshot {
+  /** Total events received (before any filtering) */
+  eventsReceived: number;
+  /** Events successfully processed */
+  eventsProcessed: number;
+  /** Duplicate events skipped */
+  eventsDuplicate: number;
+  /** Events rejected by reason */
+  eventsRejected: {
+    invalidShape: number;
+    wrongKind: number;
+    stale: number;
+    future: number;
+    rateLimited: number;
+    invalidSignature: number;
+    oversizedCiphertext: number;
+    oversizedPlaintext: number;
+    decryptFailed: number;
+    selfMessage: number;
+  };
+
+  /** Relay stats by URL */
+  relays: Record<
+    string,
+    {
+      connects: number;
+      disconnects: number;
+      reconnects: number;
+      errors: number;
+      messagesReceived: {
+        event: number;
+        eose: number;
+        closed: number;
+        notice: number;
+        ok: number;
+        auth: number;
+      };
+      circuitBreakerState: "closed" | "open" | "half_open";
+      circuitBreakerOpens: number;
+      circuitBreakerCloses: number;
+    }
+  >;
+
+  /** Rate limiting stats */
+  rateLimiting: {
+    perSenderHits: number;
+    globalHits: number;
+  };
+
+  /** Decrypt stats */
+  decrypt: {
+    success: number;
+    failure: number;
+  };
+
+  /** Memory/capacity stats */
+  memory: {
+    seenTrackerSize: number;
+    rateLimiterEntries: number;
+  };
+
+  /** Snapshot timestamp */
+  snapshotAt: number;
+}
+
+// ============================================================================
+// Metrics Collector
+// ============================================================================
+
+export interface NostrMetrics {
+  /** Emit a metric event */
+  emit: (
+    name: MetricName,
+    value?: number,
+    labels?: Record<string, string | number>
+  ) => void;
+
+  /** Get current metrics snapshot */
+  getSnapshot: () => MetricsSnapshot;
+
+  /** Reset all metrics to zero */
+  reset: () => void;
+}
+
+/**
+ * Create a metrics collector instance.
+ * Optionally pass an onMetric callback to receive real-time metric events.
+ */
+export function createMetrics(onMetric?: OnMetricCallback): NostrMetrics {
+  // Counters
+  let eventsReceived = 0;
+  let eventsProcessed = 0;
+  let eventsDuplicate = 0;
+  const eventsRejected = {
+    invalidShape: 0,
+    wrongKind: 0,
+    stale: 0,
+    future: 0,
+    rateLimited: 0,
+    invalidSignature: 0,
+    oversizedCiphertext: 0,
+    oversizedPlaintext: 0,
+    decryptFailed: 0,
+    selfMessage: 0,
+  };
+
+  // Per-relay stats
+  const relays = new Map<
+    string,
+    {
+      connects: number;
+      disconnects: number;
+      reconnects: number;
+      errors: number;
+      messagesReceived: {
+        event: number;
+        eose: number;
+        closed: number;
+        notice: number;
+        ok: number;
+        auth: number;
+      };
+      circuitBreakerState: "closed" | "open" | "half_open";
+      circuitBreakerOpens: number;
+      circuitBreakerCloses: number;
+    }
+  >();
+
+  // Rate limiting stats
+  const rateLimiting = {
+    perSenderHits: 0,
+    globalHits: 0,
+  };
+
+  // Decrypt stats
+  const decrypt = {
+    success: 0,
+    failure: 0,
+  };
+
+  // Memory stats (updated via gauge-style metrics)
+  const memory = {
+    seenTrackerSize: 0,
+    rateLimiterEntries: 0,
+  };
+
+  function getOrCreateRelay(url: string) {
+    let relay = relays.get(url);
+    if (!relay) {
+      relay = {
+        connects: 0,
+        disconnects: 0,
+        reconnects: 0,
+        errors: 0,
+        messagesReceived: {
+          event: 0,
+          eose: 0,
+          closed: 0,
+          notice: 0,
+          ok: 0,
+          auth: 0,
+        },
+        circuitBreakerState: "closed",
+        circuitBreakerOpens: 0,
+        circuitBreakerCloses: 0,
+      };
+      relays.set(url, relay);
+    }
+    return relay;
+  }
+
+  function emit(
+    name: MetricName,
+    value: number = 1,
+    labels?: Record<string, string | number>
+  ): void {
+    // Fire callback if provided
+    if (onMetric) {
+      onMetric({
+        name,
+        value,
+        timestamp: Date.now(),
+        labels,
+      });
+    }
+
+    // Update internal counters
+    const relayUrl = labels?.relay as string | undefined;
+
+    switch (name) {
+      // Event metrics
+      case "event.received":
+        eventsReceived += value;
+        break;
+      case "event.processed":
+        eventsProcessed += value;
+        break;
+      case "event.duplicate":
+        eventsDuplicate += value;
+        break;
+      case "event.rejected.invalid_shape":
+        eventsRejected.invalidShape += value;
+        break;
+      case "event.rejected.wrong_kind":
+        eventsRejected.wrongKind += value;
+        break;
+      case "event.rejected.stale":
+        eventsRejected.stale += value;
+        break;
+      case "event.rejected.future":
+        eventsRejected.future += value;
+        break;
+      case "event.rejected.rate_limited":
+        eventsRejected.rateLimited += value;
+        break;
+      case "event.rejected.invalid_signature":
+        eventsRejected.invalidSignature += value;
+        break;
+      case "event.rejected.oversized_ciphertext":
+        eventsRejected.oversizedCiphertext += value;
+        break;
+      case "event.rejected.oversized_plaintext":
+        eventsRejected.oversizedPlaintext += value;
+        break;
+      case "event.rejected.decrypt_failed":
+        eventsRejected.decryptFailed += value;
+        break;
+      case "event.rejected.self_message":
+        eventsRejected.selfMessage += value;
+        break;
+
+      // Relay metrics
+      case "relay.connect":
+        if (relayUrl) getOrCreateRelay(relayUrl).connects += value;
+        break;
+      case "relay.disconnect":
+        if (relayUrl) getOrCreateRelay(relayUrl).disconnects += value;
+        break;
+      case "relay.reconnect":
+        if (relayUrl) getOrCreateRelay(relayUrl).reconnects += value;
+        break;
+      case "relay.error":
+        if (relayUrl) getOrCreateRelay(relayUrl).errors += value;
+        break;
+      case "relay.message.event":
+        if (relayUrl) getOrCreateRelay(relayUrl).messagesReceived.event += value;
+        break;
+      case "relay.message.eose":
+        if (relayUrl) getOrCreateRelay(relayUrl).messagesReceived.eose += value;
+        break;
+      case "relay.message.closed":
+        if (relayUrl) getOrCreateRelay(relayUrl).messagesReceived.closed += value;
+        break;
+      case "relay.message.notice":
+        if (relayUrl) getOrCreateRelay(relayUrl).messagesReceived.notice += value;
+        break;
+      case "relay.message.ok":
+        if (relayUrl) getOrCreateRelay(relayUrl).messagesReceived.ok += value;
+        break;
+      case "relay.message.auth":
+        if (relayUrl) getOrCreateRelay(relayUrl).messagesReceived.auth += value;
+        break;
+      case "relay.circuit_breaker.open":
+        if (relayUrl) {
+          const r = getOrCreateRelay(relayUrl);
+          r.circuitBreakerState = "open";
+          r.circuitBreakerOpens += value;
+        }
+        break;
+      case "relay.circuit_breaker.close":
+        if (relayUrl) {
+          const r = getOrCreateRelay(relayUrl);
+          r.circuitBreakerState = "closed";
+          r.circuitBreakerCloses += value;
+        }
+        break;
+      case "relay.circuit_breaker.half_open":
+        if (relayUrl) {
+          getOrCreateRelay(relayUrl).circuitBreakerState = "half_open";
+        }
+        break;
+
+      // Rate limiting
+      case "rate_limit.per_sender":
+        rateLimiting.perSenderHits += value;
+        break;
+      case "rate_limit.global":
+        rateLimiting.globalHits += value;
+        break;
+
+      // Decrypt
+      case "decrypt.success":
+        decrypt.success += value;
+        break;
+      case "decrypt.failure":
+        decrypt.failure += value;
+        break;
+
+      // Memory (gauge-style - value replaces, not adds)
+      case "memory.seen_tracker_size":
+        memory.seenTrackerSize = value;
+        break;
+      case "memory.rate_limiter_entries":
+        memory.rateLimiterEntries = value;
+        break;
+    }
+  }
+
+  function getSnapshot(): MetricsSnapshot {
+    // Convert relay map to object
+    const relaysObj: MetricsSnapshot["relays"] = {};
+    for (const [url, stats] of relays) {
+      relaysObj[url] = { ...stats, messagesReceived: { ...stats.messagesReceived } };
+    }
+
+    return {
+      eventsReceived,
+      eventsProcessed,
+      eventsDuplicate,
+      eventsRejected: { ...eventsRejected },
+      relays: relaysObj,
+      rateLimiting: { ...rateLimiting },
+      decrypt: { ...decrypt },
+      memory: { ...memory },
+      snapshotAt: Date.now(),
+    };
+  }
+
+  function reset(): void {
+    eventsReceived = 0;
+    eventsProcessed = 0;
+    eventsDuplicate = 0;
+    Object.assign(eventsRejected, {
+      invalidShape: 0,
+      wrongKind: 0,
+      stale: 0,
+      future: 0,
+      rateLimited: 0,
+      invalidSignature: 0,
+      oversizedCiphertext: 0,
+      oversizedPlaintext: 0,
+      decryptFailed: 0,
+      selfMessage: 0,
+    });
+    relays.clear();
+    rateLimiting.perSenderHits = 0;
+    rateLimiting.globalHits = 0;
+    decrypt.success = 0;
+    decrypt.failure = 0;
+    memory.seenTrackerSize = 0;
+    memory.rateLimiterEntries = 0;
+  }
+
+  return { emit, getSnapshot, reset };
+}
+
+/**
+ * Create a no-op metrics instance (for when metrics are disabled).
+ */
+export function createNoopMetrics(): NostrMetrics {
+  const emptySnapshot: MetricsSnapshot = {
+    eventsReceived: 0,
+    eventsProcessed: 0,
+    eventsDuplicate: 0,
+    eventsRejected: {
+      invalidShape: 0,
+      wrongKind: 0,
+      stale: 0,
+      future: 0,
+      rateLimited: 0,
+      invalidSignature: 0,
+      oversizedCiphertext: 0,
+      oversizedPlaintext: 0,
+      decryptFailed: 0,
+      selfMessage: 0,
+    },
+    relays: {},
+    rateLimiting: { perSenderHits: 0, globalHits: 0 },
+    decrypt: { success: 0, failure: 0 },
+    memory: { seenTrackerSize: 0, rateLimiterEntries: 0 },
+    snapshotAt: 0,
+  };
+
+  return {
+    emit: () => {},
+    getSnapshot: () => ({ ...emptySnapshot, snapshotAt: Date.now() }),
+    reset: () => {},
+  };
+}

extensions/nostr/src/nostr-bus.fuzz.test.ts

@@ -0,0 +1,544 @@
+import { describe, expect, it } from "vitest";
+import { validatePrivateKey, isValidPubkey, normalizePubkey } from "./nostr-bus.js";
+import { createSeenTracker } from "./seen-tracker.js";
+import { createMetrics, type MetricName } from "./metrics.js";
+
+// ============================================================================
+// Fuzz Tests for validatePrivateKey
+// ============================================================================
+
+describe("validatePrivateKey fuzz", () => {
+  describe("type confusion", () => {
+    it("rejects null input", () => {
+      expect(() => validatePrivateKey(null as unknown as string)).toThrow();
+    });
+
+    it("rejects undefined input", () => {
+      expect(() => validatePrivateKey(undefined as unknown as string)).toThrow();
+    });
+
+    it("rejects number input", () => {
+      expect(() => validatePrivateKey(123 as unknown as string)).toThrow();
+    });
+
+    it("rejects boolean input", () => {
+      expect(() => validatePrivateKey(true as unknown as string)).toThrow();
+    });
+
+    it("rejects object input", () => {
+      expect(() => validatePrivateKey({} as unknown as string)).toThrow();
+    });
+
+    it("rejects array input", () => {
+      expect(() => validatePrivateKey([] as unknown as string)).toThrow();
+    });
+
+    it("rejects function input", () => {
+      expect(() => validatePrivateKey((() => {}) as unknown as string)).toThrow();
+    });
+  });
+
+  describe("unicode attacks", () => {
+    it("rejects unicode lookalike characters", () => {
+      // Using zero-width characters
+      const withZeroWidth =
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcde\u200Bf";
+      expect(() => validatePrivateKey(withZeroWidth)).toThrow();
+    });
+
+    it("rejects RTL override", () => {
+      const withRtl =
+        "\u202E0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(() => validatePrivateKey(withRtl)).toThrow();
+    });
+
+    it("rejects homoglyph 'a' (Cyrillic а)", () => {
+      // Using Cyrillic 'а' (U+0430) instead of Latin 'a'
+      const withCyrillicA =
+        "0123456789\u0430bcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(() => validatePrivateKey(withCyrillicA)).toThrow();
+    });
+
+    it("rejects emoji", () => {
+      const withEmoji =
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab😀";
+      expect(() => validatePrivateKey(withEmoji)).toThrow();
+    });
+
+    it("rejects combining characters", () => {
+      // 'a' followed by combining acute accent
+      const withCombining =
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcde\u0301";
+      expect(() => validatePrivateKey(withCombining)).toThrow();
+    });
+  });
+
+  describe("injection attempts", () => {
+    it("rejects null byte injection", () => {
+      const withNullByte =
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcde\x00f";
+      expect(() => validatePrivateKey(withNullByte)).toThrow();
+    });
+
+    it("rejects newline injection", () => {
+      const withNewline =
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcde\nf";
+      expect(() => validatePrivateKey(withNewline)).toThrow();
+    });
+
+    it("rejects carriage return injection", () => {
+      const withCR =
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcde\rf";
+      expect(() => validatePrivateKey(withCR)).toThrow();
+    });
+
+    it("rejects tab injection", () => {
+      const withTab =
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcde\tf";
+      expect(() => validatePrivateKey(withTab)).toThrow();
+    });
+
+    it("rejects form feed injection", () => {
+      const withFormFeed =
+        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcde\ff";
+      expect(() => validatePrivateKey(withFormFeed)).toThrow();
+    });
+  });
+
+  describe("edge cases", () => {
+    it("rejects very long string", () => {
+      const veryLong = "a".repeat(10000);
+      expect(() => validatePrivateKey(veryLong)).toThrow();
+    });
+
+    it("rejects string of spaces matching length", () => {
+      const spaces = " ".repeat(64);
+      expect(() => validatePrivateKey(spaces)).toThrow();
+    });
+
+    it("rejects hex with spaces between characters", () => {
+      const withSpaces =
+        "01 23 45 67 89 ab cd ef 01 23 45 67 89 ab cd ef 01 23 45 67 89 ab cd ef 01 23 45 67 89 ab cd ef";
+      expect(() => validatePrivateKey(withSpaces)).toThrow();
+    });
+  });
+
+  describe("nsec format edge cases", () => {
+    it("rejects nsec with invalid bech32 characters", () => {
+      // 'b', 'i', 'o' are not valid bech32 characters
+      const invalidBech32 = "nsec1qypqxpq9qtpqscx7peytbfwtdjmcv0mrz5rjpej8vjppfkqfqy8skqfv3l";
+      expect(() => validatePrivateKey(invalidBech32)).toThrow();
+    });
+
+    it("rejects nsec with wrong prefix", () => {
+      expect(() => validatePrivateKey("nsec0aaaa")).toThrow();
+    });
+
+    it("rejects partial nsec", () => {
+      expect(() => validatePrivateKey("nsec1")).toThrow();
+    });
+  });
+});
+
+// ============================================================================
+// Fuzz Tests for isValidPubkey
+// ============================================================================
+
+describe("isValidPubkey fuzz", () => {
+  describe("type confusion", () => {
+    it("handles null gracefully", () => {
+      expect(isValidPubkey(null as unknown as string)).toBe(false);
+    });
+
+    it("handles undefined gracefully", () => {
+      expect(isValidPubkey(undefined as unknown as string)).toBe(false);
+    });
+
+    it("handles number gracefully", () => {
+      expect(isValidPubkey(123 as unknown as string)).toBe(false);
+    });
+
+    it("handles object gracefully", () => {
+      expect(isValidPubkey({} as unknown as string)).toBe(false);
+    });
+  });
+
+  describe("malicious inputs", () => {
+    it("rejects __proto__ key", () => {
+      expect(isValidPubkey("__proto__")).toBe(false);
+    });
+
+    it("rejects constructor key", () => {
+      expect(isValidPubkey("constructor")).toBe(false);
+    });
+
+    it("rejects toString key", () => {
+      expect(isValidPubkey("toString")).toBe(false);
+    });
+  });
+});
+
+// ============================================================================
+// Fuzz Tests for normalizePubkey
+// ============================================================================
+
+describe("normalizePubkey fuzz", () => {
+  describe("prototype pollution attempts", () => {
+    it("throws for __proto__", () => {
+      expect(() => normalizePubkey("__proto__")).toThrow();
+    });
+
+    it("throws for constructor", () => {
+      expect(() => normalizePubkey("constructor")).toThrow();
+    });
+
+    it("throws for prototype", () => {
+      expect(() => normalizePubkey("prototype")).toThrow();
+    });
+  });
+
+  describe("case sensitivity", () => {
+    it("normalizes uppercase to lowercase", () => {
+      const upper = "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF";
+      const lower = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(normalizePubkey(upper)).toBe(lower);
+    });
+
+    it("normalizes mixed case to lowercase", () => {
+      const mixed = "0123456789AbCdEf0123456789AbCdEf0123456789AbCdEf0123456789AbCdEf";
+      const lower = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(normalizePubkey(mixed)).toBe(lower);
+    });
+  });
+});
+
+// ============================================================================
+// Fuzz Tests for SeenTracker
+// ============================================================================
+
+describe("SeenTracker fuzz", () => {
+  describe("malformed IDs", () => {
+    it("handles empty string IDs", () => {
+      const tracker = createSeenTracker({ maxEntries: 100 });
+      expect(() => tracker.add("")).not.toThrow();
+      expect(tracker.peek("")).toBe(true);
+      tracker.stop();
+    });
+
+    it("handles very long IDs", () => {
+      const tracker = createSeenTracker({ maxEntries: 100 });
+      const longId = "a".repeat(100000);
+      expect(() => tracker.add(longId)).not.toThrow();
+      expect(tracker.peek(longId)).toBe(true);
+      tracker.stop();
+    });
+
+    it("handles unicode IDs", () => {
+      const tracker = createSeenTracker({ maxEntries: 100 });
+      const unicodeId = "事件ID_🎉_тест";
+      expect(() => tracker.add(unicodeId)).not.toThrow();
+      expect(tracker.peek(unicodeId)).toBe(true);
+      tracker.stop();
+    });
+
+    it("handles IDs with null bytes", () => {
+      const tracker = createSeenTracker({ maxEntries: 100 });
+      const idWithNull = "event\x00id";
+      expect(() => tracker.add(idWithNull)).not.toThrow();
+      expect(tracker.peek(idWithNull)).toBe(true);
+      tracker.stop();
+    });
+
+    it("handles prototype property names as IDs", () => {
+      const tracker = createSeenTracker({ maxEntries: 100 });
+
+      // These should not affect the tracker's internal operation
+      expect(() => tracker.add("__proto__")).not.toThrow();
+      expect(() => tracker.add("constructor")).not.toThrow();
+      expect(() => tracker.add("toString")).not.toThrow();
+      expect(() => tracker.add("hasOwnProperty")).not.toThrow();
+
+      expect(tracker.peek("__proto__")).toBe(true);
+      expect(tracker.peek("constructor")).toBe(true);
+      expect(tracker.peek("toString")).toBe(true);
+      expect(tracker.peek("hasOwnProperty")).toBe(true);
+
+      tracker.stop();
+    });
+  });
+
+  describe("rapid operations", () => {
+    it("handles rapid add/check cycles", () => {
+      const tracker = createSeenTracker({ maxEntries: 1000 });
+
+      for (let i = 0; i < 10000; i++) {
+        const id = `event-${i}`;
+        tracker.add(id);
+        // Recently added should be findable
+        if (i < 1000) {
+          tracker.peek(id);
+        }
+      }
+
+      // Size should be capped at maxEntries
+      expect(tracker.size()).toBeLessThanOrEqual(1000);
+      tracker.stop();
+    });
+
+    it("handles concurrent-style operations", () => {
+      const tracker = createSeenTracker({ maxEntries: 100 });
+
+      // Simulate interleaved operations
+      for (let i = 0; i < 100; i++) {
+        tracker.add(`add-${i}`);
+        tracker.peek(`peek-${i}`);
+        tracker.has(`has-${i}`);
+        if (i % 10 === 0) {
+          tracker.delete(`add-${i - 5}`);
+        }
+      }
+
+      expect(() => tracker.size()).not.toThrow();
+      tracker.stop();
+    });
+  });
+
+  describe("seed edge cases", () => {
+    it("handles empty seed array", () => {
+      const tracker = createSeenTracker({ maxEntries: 100 });
+      expect(() => tracker.seed([])).not.toThrow();
+      expect(tracker.size()).toBe(0);
+      tracker.stop();
+    });
+
+    it("handles seed with duplicate IDs", () => {
+      const tracker = createSeenTracker({ maxEntries: 100 });
+      tracker.seed(["id1", "id1", "id1", "id2", "id2"]);
+      expect(tracker.size()).toBe(2);
+      tracker.stop();
+    });
+
+    it("handles seed larger than maxEntries", () => {
+      const tracker = createSeenTracker({ maxEntries: 5 });
+      const ids = Array.from({ length: 100 }, (_, i) => `id-${i}`);
+      tracker.seed(ids);
+      expect(tracker.size()).toBeLessThanOrEqual(5);
+      tracker.stop();
+    });
+  });
+});
+
+// ============================================================================
+// Fuzz Tests for Metrics
+// ============================================================================
+
+describe("Metrics fuzz", () => {
+  describe("invalid metric names", () => {
+    it("handles unknown metric names gracefully", () => {
+      const metrics = createMetrics();
+
+      // Cast to bypass type checking - testing runtime behavior
+      expect(() => {
+        metrics.emit("invalid.metric.name" as MetricName);
+      }).not.toThrow();
+    });
+  });
+
+  describe("invalid label values", () => {
+    it("handles null relay label", () => {
+      const metrics = createMetrics();
+      expect(() => {
+        metrics.emit("relay.connect", 1, { relay: null as unknown as string });
+      }).not.toThrow();
+    });
+
+    it("handles undefined relay label", () => {
+      const metrics = createMetrics();
+      expect(() => {
+        metrics.emit("relay.connect", 1, { relay: undefined as unknown as string });
+      }).not.toThrow();
+    });
+
+    it("handles very long relay URL", () => {
+      const metrics = createMetrics();
+      const longUrl = "wss://" + "a".repeat(10000) + ".com";
+      expect(() => {
+        metrics.emit("relay.connect", 1, { relay: longUrl });
+      }).not.toThrow();
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.relays[longUrl]).toBeDefined();
+    });
+  });
+
+  describe("extreme values", () => {
+    it("handles NaN value", () => {
+      const metrics = createMetrics();
+      expect(() => metrics.emit("event.received", NaN)).not.toThrow();
+
+      const snapshot = metrics.getSnapshot();
+      expect(isNaN(snapshot.eventsReceived)).toBe(true);
+    });
+
+    it("handles Infinity value", () => {
+      const metrics = createMetrics();
+      expect(() => metrics.emit("event.received", Infinity)).not.toThrow();
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.eventsReceived).toBe(Infinity);
+    });
+
+    it("handles negative value", () => {
+      const metrics = createMetrics();
+      metrics.emit("event.received", -1);
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.eventsReceived).toBe(-1);
+    });
+
+    it("handles very large value", () => {
+      const metrics = createMetrics();
+      metrics.emit("event.received", Number.MAX_SAFE_INTEGER);
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.eventsReceived).toBe(Number.MAX_SAFE_INTEGER);
+    });
+  });
+
+  describe("rapid emissions", () => {
+    it("handles many rapid emissions", () => {
+      const events: unknown[] = [];
+      const metrics = createMetrics((e) => events.push(e));
+
+      for (let i = 0; i < 10000; i++) {
+        metrics.emit("event.received");
+      }
+
+      expect(events).toHaveLength(10000);
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.eventsReceived).toBe(10000);
+    });
+  });
+
+  describe("reset during operation", () => {
+    it("handles reset mid-operation safely", () => {
+      const metrics = createMetrics();
+
+      metrics.emit("event.received");
+      metrics.emit("event.received");
+      metrics.reset();
+      metrics.emit("event.received");
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.eventsReceived).toBe(1);
+    });
+  });
+});
+
+// ============================================================================
+// Event Shape Validation (simulating malformed events)
+// ============================================================================
+
+describe("Event shape validation", () => {
+  describe("malformed event structures", () => {
+    // These test what happens if malformed data somehow gets through
+
+    it("identifies missing required fields", () => {
+      const malformedEvents = [
+        {}, // empty
+        { id: "abc" }, // missing pubkey, created_at, etc.
+        { id: null, pubkey: null }, // null values
+        { id: 123, pubkey: 456 }, // wrong types
+        { tags: "not-an-array" }, // wrong type for tags
+        { tags: [[1, 2, 3]] }, // wrong type for tag elements
+      ];
+
+      for (const event of malformedEvents) {
+        // These should be caught by shape validation before processing
+        const hasId = typeof event?.id === "string";
+        const hasPubkey = typeof (event as { pubkey?: unknown })?.pubkey === "string";
+        const hasTags = Array.isArray((event as { tags?: unknown })?.tags);
+
+        // At least one should be invalid
+        expect(hasId && hasPubkey && hasTags).toBe(false);
+      }
+    });
+  });
+
+  describe("timestamp edge cases", () => {
+    const testTimestamps = [
+      { value: NaN, desc: "NaN" },
+      { value: Infinity, desc: "Infinity" },
+      { value: -Infinity, desc: "-Infinity" },
+      { value: -1, desc: "negative" },
+      { value: 0, desc: "zero" },
+      { value: 253402300800, desc: "year 10000" }, // Far future
+      { value: -62135596800, desc: "year 0001" }, // Far past
+      { value: 1.5, desc: "float" },
+    ];
+
+    for (const { value, desc } of testTimestamps) {
+      it(`handles ${desc} timestamp`, () => {
+        const isValidTimestamp =
+          typeof value === "number" &&
+          !isNaN(value) &&
+          isFinite(value) &&
+          value >= 0 &&
+          Number.isInteger(value);
+
+        // Timestamps should be validated as positive integers
+        if (["NaN", "Infinity", "-Infinity", "negative", "float"].includes(desc)) {
+          expect(isValidTimestamp).toBe(false);
+        }
+      });
+    }
+  });
+});
+
+// ============================================================================
+// JSON parsing edge cases (simulating relay responses)
+// ============================================================================
+
+describe("JSON parsing edge cases", () => {
+  const malformedJsonCases = [
+    { input: "", desc: "empty string" },
+    { input: "null", desc: "null literal" },
+    { input: "undefined", desc: "undefined literal" },
+    { input: "{", desc: "incomplete object" },
+    { input: "[", desc: "incomplete array" },
+    { input: '{"key": undefined}', desc: "undefined value" },
+    { input: "{'key': 'value'}", desc: "single quotes" },
+    { input: '{"key": NaN}', desc: "NaN value" },
+    { input: '{"key": Infinity}', desc: "Infinity value" },
+    { input: "\x00", desc: "null byte" },
+    { input: "abc", desc: "plain string" },
+    { input: "123", desc: "plain number" },
+  ];
+
+  for (const { input, desc } of malformedJsonCases) {
+    it(`handles malformed JSON: ${desc}`, () => {
+      let parsed: unknown;
+      let parseError = false;
+
+      try {
+        parsed = JSON.parse(input);
+      } catch {
+        parseError = true;
+      }
+
+      // Either it throws or produces something that needs validation
+      if (!parseError) {
+        // If it parsed, we need to validate the structure
+        const isValidRelayMessage =
+          Array.isArray(parsed) &&
+          parsed.length >= 2 &&
+          typeof parsed[0] === "string";
+
+        // Most malformed cases won't produce valid relay messages
+        if (["null literal", "plain number", "plain string"].includes(desc)) {
+          expect(isValidRelayMessage).toBe(false);
+        }
+      }
+    });
+  }
+});

extensions/nostr/src/nostr-bus.integration.test.ts

@@ -0,0 +1,452 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { createSeenTracker } from "./seen-tracker.js";
+import {
+  createMetrics,
+  createNoopMetrics,
+  type MetricEvent,
+} from "./metrics.js";
+
+// ============================================================================
+// Seen Tracker Integration Tests
+// ============================================================================
+
+describe("SeenTracker", () => {
+  describe("basic operations", () => {
+    it("tracks seen IDs", () => {
+      const tracker = createSeenTracker({ maxEntries: 100, ttlMs: 60000 });
+
+      // First check returns false and adds
+      expect(tracker.has("id1")).toBe(false);
+      // Second check returns true (already seen)
+      expect(tracker.has("id1")).toBe(true);
+
+      tracker.stop();
+    });
+
+    it("peek does not add", () => {
+      const tracker = createSeenTracker({ maxEntries: 100, ttlMs: 60000 });
+
+      expect(tracker.peek("id1")).toBe(false);
+      expect(tracker.peek("id1")).toBe(false); // Still false
+
+      tracker.add("id1");
+      expect(tracker.peek("id1")).toBe(true);
+
+      tracker.stop();
+    });
+
+    it("delete removes entries", () => {
+      const tracker = createSeenTracker({ maxEntries: 100, ttlMs: 60000 });
+
+      tracker.add("id1");
+      expect(tracker.peek("id1")).toBe(true);
+
+      tracker.delete("id1");
+      expect(tracker.peek("id1")).toBe(false);
+
+      tracker.stop();
+    });
+
+    it("clear removes all entries", () => {
+      const tracker = createSeenTracker({ maxEntries: 100, ttlMs: 60000 });
+
+      tracker.add("id1");
+      tracker.add("id2");
+      tracker.add("id3");
+      expect(tracker.size()).toBe(3);
+
+      tracker.clear();
+      expect(tracker.size()).toBe(0);
+      expect(tracker.peek("id1")).toBe(false);
+
+      tracker.stop();
+    });
+
+    it("seed pre-populates entries", () => {
+      const tracker = createSeenTracker({ maxEntries: 100, ttlMs: 60000 });
+
+      tracker.seed(["id1", "id2", "id3"]);
+      expect(tracker.size()).toBe(3);
+      expect(tracker.peek("id1")).toBe(true);
+      expect(tracker.peek("id2")).toBe(true);
+      expect(tracker.peek("id3")).toBe(true);
+
+      tracker.stop();
+    });
+  });
+
+  describe("LRU eviction", () => {
+    it("evicts least recently used when at capacity", () => {
+      const tracker = createSeenTracker({ maxEntries: 3, ttlMs: 60000 });
+
+      tracker.add("id1");
+      tracker.add("id2");
+      tracker.add("id3");
+      expect(tracker.size()).toBe(3);
+
+      // Adding fourth should evict oldest (id1)
+      tracker.add("id4");
+      expect(tracker.size()).toBe(3);
+      expect(tracker.peek("id1")).toBe(false); // Evicted
+      expect(tracker.peek("id2")).toBe(true);
+      expect(tracker.peek("id3")).toBe(true);
+      expect(tracker.peek("id4")).toBe(true);
+
+      tracker.stop();
+    });
+
+    it("accessing an entry moves it to front (prevents eviction)", () => {
+      const tracker = createSeenTracker({ maxEntries: 3, ttlMs: 60000 });
+
+      tracker.add("id1");
+      tracker.add("id2");
+      tracker.add("id3");
+
+      // Access id1, moving it to front
+      tracker.has("id1");
+
+      // Add id4 - should evict id2 (now oldest)
+      tracker.add("id4");
+      expect(tracker.peek("id1")).toBe(true); // Not evicted, was accessed
+      expect(tracker.peek("id2")).toBe(false); // Evicted
+      expect(tracker.peek("id3")).toBe(true);
+      expect(tracker.peek("id4")).toBe(true);
+
+      tracker.stop();
+    });
+
+    it("handles capacity of 1", () => {
+      const tracker = createSeenTracker({ maxEntries: 1, ttlMs: 60000 });
+
+      tracker.add("id1");
+      expect(tracker.peek("id1")).toBe(true);
+
+      tracker.add("id2");
+      expect(tracker.peek("id1")).toBe(false);
+      expect(tracker.peek("id2")).toBe(true);
+
+      tracker.stop();
+    });
+
+    it("seed respects maxEntries", () => {
+      const tracker = createSeenTracker({ maxEntries: 2, ttlMs: 60000 });
+
+      tracker.seed(["id1", "id2", "id3", "id4"]);
+      expect(tracker.size()).toBe(2);
+      // Seed stops when maxEntries reached, processing from end to start
+      // So id4 and id3 get added first, then we're at capacity
+      expect(tracker.peek("id3")).toBe(true);
+      expect(tracker.peek("id4")).toBe(true);
+
+      tracker.stop();
+    });
+  });
+
+  describe("TTL expiration", () => {
+    it("expires entries after TTL", async () => {
+      vi.useFakeTimers();
+
+      const tracker = createSeenTracker({
+        maxEntries: 100,
+        ttlMs: 100,
+        pruneIntervalMs: 50,
+      });
+
+      tracker.add("id1");
+      expect(tracker.peek("id1")).toBe(true);
+
+      // Advance past TTL
+      vi.advanceTimersByTime(150);
+
+      // Entry should be expired
+      expect(tracker.peek("id1")).toBe(false);
+
+      tracker.stop();
+      vi.useRealTimers();
+    });
+
+    it("has() refreshes TTL", async () => {
+      vi.useFakeTimers();
+
+      const tracker = createSeenTracker({
+        maxEntries: 100,
+        ttlMs: 100,
+        pruneIntervalMs: 50,
+      });
+
+      tracker.add("id1");
+
+      // Advance halfway
+      vi.advanceTimersByTime(50);
+
+      // Access to refresh
+      expect(tracker.has("id1")).toBe(true);
+
+      // Advance another 75ms (total 125ms from add, but only 75ms from last access)
+      vi.advanceTimersByTime(75);
+
+      // Should still be valid (refreshed at 50ms)
+      expect(tracker.peek("id1")).toBe(true);
+
+      tracker.stop();
+      vi.useRealTimers();
+    });
+  });
+});
+
+// ============================================================================
+// Metrics Integration Tests
+// ============================================================================
+
+describe("Metrics", () => {
+  describe("createMetrics", () => {
+    it("emits metric events to callback", () => {
+      const events: MetricEvent[] = [];
+      const metrics = createMetrics((event) => events.push(event));
+
+      metrics.emit("event.received");
+      metrics.emit("event.processed");
+      metrics.emit("event.duplicate");
+
+      expect(events).toHaveLength(3);
+      expect(events[0].name).toBe("event.received");
+      expect(events[1].name).toBe("event.processed");
+      expect(events[2].name).toBe("event.duplicate");
+    });
+
+    it("includes labels in metric events", () => {
+      const events: MetricEvent[] = [];
+      const metrics = createMetrics((event) => events.push(event));
+
+      metrics.emit("relay.connect", 1, { relay: "wss://relay.example.com" });
+
+      expect(events[0].labels).toEqual({ relay: "wss://relay.example.com" });
+    });
+
+    it("accumulates counters in snapshot", () => {
+      const metrics = createMetrics();
+
+      metrics.emit("event.received");
+      metrics.emit("event.received");
+      metrics.emit("event.processed");
+      metrics.emit("event.duplicate");
+      metrics.emit("event.duplicate");
+      metrics.emit("event.duplicate");
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.eventsReceived).toBe(2);
+      expect(snapshot.eventsProcessed).toBe(1);
+      expect(snapshot.eventsDuplicate).toBe(3);
+    });
+
+    it("tracks per-relay stats", () => {
+      const metrics = createMetrics();
+
+      metrics.emit("relay.connect", 1, { relay: "wss://relay1.com" });
+      metrics.emit("relay.connect", 1, { relay: "wss://relay2.com" });
+      metrics.emit("relay.error", 1, { relay: "wss://relay1.com" });
+      metrics.emit("relay.error", 1, { relay: "wss://relay1.com" });
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.relays["wss://relay1.com"]).toBeDefined();
+      expect(snapshot.relays["wss://relay1.com"].connects).toBe(1);
+      expect(snapshot.relays["wss://relay1.com"].errors).toBe(2);
+      expect(snapshot.relays["wss://relay2.com"].connects).toBe(1);
+      expect(snapshot.relays["wss://relay2.com"].errors).toBe(0);
+    });
+
+    it("tracks circuit breaker state changes", () => {
+      const metrics = createMetrics();
+
+      metrics.emit("relay.circuit_breaker.open", 1, { relay: "wss://relay.com" });
+
+      let snapshot = metrics.getSnapshot();
+      expect(snapshot.relays["wss://relay.com"].circuitBreakerState).toBe("open");
+      expect(snapshot.relays["wss://relay.com"].circuitBreakerOpens).toBe(1);
+
+      metrics.emit("relay.circuit_breaker.close", 1, { relay: "wss://relay.com" });
+
+      snapshot = metrics.getSnapshot();
+      expect(snapshot.relays["wss://relay.com"].circuitBreakerState).toBe("closed");
+      expect(snapshot.relays["wss://relay.com"].circuitBreakerCloses).toBe(1);
+    });
+
+    it("tracks all rejection reasons", () => {
+      const metrics = createMetrics();
+
+      metrics.emit("event.rejected.invalid_shape");
+      metrics.emit("event.rejected.wrong_kind");
+      metrics.emit("event.rejected.stale");
+      metrics.emit("event.rejected.future");
+      metrics.emit("event.rejected.rate_limited");
+      metrics.emit("event.rejected.invalid_signature");
+      metrics.emit("event.rejected.oversized_ciphertext");
+      metrics.emit("event.rejected.oversized_plaintext");
+      metrics.emit("event.rejected.decrypt_failed");
+      metrics.emit("event.rejected.self_message");
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.eventsRejected.invalidShape).toBe(1);
+      expect(snapshot.eventsRejected.wrongKind).toBe(1);
+      expect(snapshot.eventsRejected.stale).toBe(1);
+      expect(snapshot.eventsRejected.future).toBe(1);
+      expect(snapshot.eventsRejected.rateLimited).toBe(1);
+      expect(snapshot.eventsRejected.invalidSignature).toBe(1);
+      expect(snapshot.eventsRejected.oversizedCiphertext).toBe(1);
+      expect(snapshot.eventsRejected.oversizedPlaintext).toBe(1);
+      expect(snapshot.eventsRejected.decryptFailed).toBe(1);
+      expect(snapshot.eventsRejected.selfMessage).toBe(1);
+    });
+
+    it("tracks relay message types", () => {
+      const metrics = createMetrics();
+
+      metrics.emit("relay.message.event", 1, { relay: "wss://relay.com" });
+      metrics.emit("relay.message.eose", 1, { relay: "wss://relay.com" });
+      metrics.emit("relay.message.closed", 1, { relay: "wss://relay.com" });
+      metrics.emit("relay.message.notice", 1, { relay: "wss://relay.com" });
+      metrics.emit("relay.message.ok", 1, { relay: "wss://relay.com" });
+      metrics.emit("relay.message.auth", 1, { relay: "wss://relay.com" });
+
+      const snapshot = metrics.getSnapshot();
+      const relay = snapshot.relays["wss://relay.com"];
+      expect(relay.messagesReceived.event).toBe(1);
+      expect(relay.messagesReceived.eose).toBe(1);
+      expect(relay.messagesReceived.closed).toBe(1);
+      expect(relay.messagesReceived.notice).toBe(1);
+      expect(relay.messagesReceived.ok).toBe(1);
+      expect(relay.messagesReceived.auth).toBe(1);
+    });
+
+    it("tracks decrypt success/failure", () => {
+      const metrics = createMetrics();
+
+      metrics.emit("decrypt.success");
+      metrics.emit("decrypt.success");
+      metrics.emit("decrypt.failure");
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.decrypt.success).toBe(2);
+      expect(snapshot.decrypt.failure).toBe(1);
+    });
+
+    it("tracks memory gauges (replaces rather than accumulates)", () => {
+      const metrics = createMetrics();
+
+      metrics.emit("memory.seen_tracker_size", 100);
+      metrics.emit("memory.seen_tracker_size", 150);
+      metrics.emit("memory.seen_tracker_size", 125);
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.memory.seenTrackerSize).toBe(125); // Last value, not sum
+    });
+
+    it("reset clears all counters", () => {
+      const metrics = createMetrics();
+
+      metrics.emit("event.received");
+      metrics.emit("event.processed");
+      metrics.emit("relay.connect", 1, { relay: "wss://relay.com" });
+
+      metrics.reset();
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.eventsReceived).toBe(0);
+      expect(snapshot.eventsProcessed).toBe(0);
+      expect(Object.keys(snapshot.relays)).toHaveLength(0);
+    });
+  });
+
+  describe("createNoopMetrics", () => {
+    it("does not throw on emit", () => {
+      const metrics = createNoopMetrics();
+
+      expect(() => {
+        metrics.emit("event.received");
+        metrics.emit("relay.connect", 1, { relay: "wss://relay.com" });
+      }).not.toThrow();
+    });
+
+    it("returns empty snapshot", () => {
+      const metrics = createNoopMetrics();
+
+      const snapshot = metrics.getSnapshot();
+      expect(snapshot.eventsReceived).toBe(0);
+      expect(snapshot.eventsProcessed).toBe(0);
+    });
+  });
+});
+
+// ============================================================================
+// Circuit Breaker Behavior Tests
+// ============================================================================
+
+describe("Circuit Breaker Behavior", () => {
+  // Test the circuit breaker logic through metrics emissions
+  it("emits circuit breaker metrics in correct sequence", () => {
+    const events: MetricEvent[] = [];
+    const metrics = createMetrics((event) => events.push(event));
+
+    // Simulate 5 failures -> open
+    for (let i = 0; i < 5; i++) {
+      metrics.emit("relay.error", 1, { relay: "wss://relay.com" });
+    }
+    metrics.emit("relay.circuit_breaker.open", 1, { relay: "wss://relay.com" });
+
+    // Simulate recovery
+    metrics.emit("relay.circuit_breaker.half_open", 1, { relay: "wss://relay.com" });
+    metrics.emit("relay.circuit_breaker.close", 1, { relay: "wss://relay.com" });
+
+    const cbEvents = events.filter((e) => e.name.startsWith("relay.circuit_breaker"));
+    expect(cbEvents).toHaveLength(3);
+    expect(cbEvents[0].name).toBe("relay.circuit_breaker.open");
+    expect(cbEvents[1].name).toBe("relay.circuit_breaker.half_open");
+    expect(cbEvents[2].name).toBe("relay.circuit_breaker.close");
+  });
+});
+
+// ============================================================================
+// Health Scoring Behavior Tests
+// ============================================================================
+
+describe("Health Scoring", () => {
+  it("metrics track relay errors for health scoring", () => {
+    const metrics = createMetrics();
+
+    // Simulate mixed success/failure pattern
+    metrics.emit("relay.connect", 1, { relay: "wss://good-relay.com" });
+    metrics.emit("relay.connect", 1, { relay: "wss://bad-relay.com" });
+
+    metrics.emit("relay.error", 1, { relay: "wss://bad-relay.com" });
+    metrics.emit("relay.error", 1, { relay: "wss://bad-relay.com" });
+    metrics.emit("relay.error", 1, { relay: "wss://bad-relay.com" });
+
+    const snapshot = metrics.getSnapshot();
+    expect(snapshot.relays["wss://good-relay.com"].errors).toBe(0);
+    expect(snapshot.relays["wss://bad-relay.com"].errors).toBe(3);
+  });
+});
+
+// ============================================================================
+// Reconnect Backoff Tests
+// ============================================================================
+
+describe("Reconnect Backoff", () => {
+  it("computes delays within expected bounds", () => {
+    // Compute expected delays (1s, 2s, 4s, 8s, 16s, 32s, 60s cap)
+    const BASE = 1000;
+    const MAX = 60000;
+    const JITTER = 0.3;
+
+    for (let attempt = 0; attempt < 10; attempt++) {
+      const exponential = BASE * Math.pow(2, attempt);
+      const capped = Math.min(exponential, MAX);
+      const minDelay = capped * (1 - JITTER);
+      const maxDelay = capped * (1 + JITTER);
+
+      // These are the expected bounds
+      expect(minDelay).toBeGreaterThanOrEqual(BASE * 0.7);
+      expect(maxDelay).toBeLessThanOrEqual(MAX * 1.3);
+    }
+  });
+});

extensions/nostr/src/nostr-bus.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it } from "vitest";
+import {
+  validatePrivateKey,
+  getPublicKeyFromPrivate,
+  isValidPubkey,
+  normalizePubkey,
+  pubkeyToNpub,
+} from "./nostr-bus.js";
+
+// Test private key (DO NOT use in production - this is a known test key)
+const TEST_HEX_KEY = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+const TEST_NSEC = "nsec1qypqxpq9qtpqscx7peytzfwtdjmcv0mrz5rjpej8vjppfkqfqy8skqfv3l";
+
+describe("validatePrivateKey", () => {
+  describe("hex format", () => {
+    it("accepts valid 64-char hex key", () => {
+      const result = validatePrivateKey(TEST_HEX_KEY);
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(result.length).toBe(32);
+    });
+
+    it("accepts lowercase hex", () => {
+      const result = validatePrivateKey(TEST_HEX_KEY.toLowerCase());
+      expect(result).toBeInstanceOf(Uint8Array);
+    });
+
+    it("accepts uppercase hex", () => {
+      const result = validatePrivateKey(TEST_HEX_KEY.toUpperCase());
+      expect(result).toBeInstanceOf(Uint8Array);
+    });
+
+    it("accepts mixed case hex", () => {
+      const mixed = "0123456789ABCdef0123456789abcDEF0123456789abcdef0123456789ABCDEF";
+      const result = validatePrivateKey(mixed);
+      expect(result).toBeInstanceOf(Uint8Array);
+    });
+
+    it("trims whitespace", () => {
+      const result = validatePrivateKey(`  ${TEST_HEX_KEY}  `);
+      expect(result).toBeInstanceOf(Uint8Array);
+    });
+
+    it("trims newlines", () => {
+      const result = validatePrivateKey(`${TEST_HEX_KEY}\n`);
+      expect(result).toBeInstanceOf(Uint8Array);
+    });
+
+    it("rejects 63-char hex (too short)", () => {
+      expect(() => validatePrivateKey(TEST_HEX_KEY.slice(0, 63))).toThrow(
+        "Private key must be 64 hex characters"
+      );
+    });
+
+    it("rejects 65-char hex (too long)", () => {
+      expect(() => validatePrivateKey(TEST_HEX_KEY + "0")).toThrow(
+        "Private key must be 64 hex characters"
+      );
+    });
+
+    it("rejects non-hex characters", () => {
+      const invalid = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdeg"; // 'g' at end
+      expect(() => validatePrivateKey(invalid)).toThrow("Private key must be 64 hex characters");
+    });
+
+    it("rejects empty string", () => {
+      expect(() => validatePrivateKey("")).toThrow("Private key must be 64 hex characters");
+    });
+
+    it("rejects whitespace-only string", () => {
+      expect(() => validatePrivateKey("   ")).toThrow("Private key must be 64 hex characters");
+    });
+
+    it("rejects key with 0x prefix", () => {
+      expect(() => validatePrivateKey("0x" + TEST_HEX_KEY)).toThrow(
+        "Private key must be 64 hex characters"
+      );
+    });
+  });
+
+  describe("nsec format", () => {
+    it("rejects invalid nsec (wrong checksum)", () => {
+      const badNsec = "nsec1invalidinvalidinvalidinvalidinvalidinvalidinvalidinvalid";
+      expect(() => validatePrivateKey(badNsec)).toThrow();
+    });
+
+    it("rejects npub (wrong type)", () => {
+      const npub = "npub1qypqxpq9qtpqscx7peytzfwtdjmcv0mrz5rjpej8vjppfkqfqy8s5epk55";
+      expect(() => validatePrivateKey(npub)).toThrow();
+    });
+  });
+});
+
+describe("isValidPubkey", () => {
+  describe("hex format", () => {
+    it("accepts valid 64-char hex pubkey", () => {
+      const validHex = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(isValidPubkey(validHex)).toBe(true);
+    });
+
+    it("accepts uppercase hex", () => {
+      const validHex = "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF";
+      expect(isValidPubkey(validHex)).toBe(true);
+    });
+
+    it("rejects 63-char hex", () => {
+      const shortHex = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcde";
+      expect(isValidPubkey(shortHex)).toBe(false);
+    });
+
+    it("rejects 65-char hex", () => {
+      const longHex = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0";
+      expect(isValidPubkey(longHex)).toBe(false);
+    });
+
+    it("rejects non-hex characters", () => {
+      const invalid = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdeg";
+      expect(isValidPubkey(invalid)).toBe(false);
+    });
+  });
+
+  describe("npub format", () => {
+    it("rejects invalid npub", () => {
+      expect(isValidPubkey("npub1invalid")).toBe(false);
+    });
+
+    it("rejects nsec (wrong type)", () => {
+      expect(isValidPubkey(TEST_NSEC)).toBe(false);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("rejects empty string", () => {
+      expect(isValidPubkey("")).toBe(false);
+    });
+
+    it("handles whitespace-padded input", () => {
+      const validHex = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(isValidPubkey(`  ${validHex}  `)).toBe(true);
+    });
+  });
+});
+
+describe("normalizePubkey", () => {
+  describe("hex format", () => {
+    it("lowercases hex pubkey", () => {
+      const upper = "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF";
+      const result = normalizePubkey(upper);
+      expect(result).toBe(upper.toLowerCase());
+    });
+
+    it("trims whitespace", () => {
+      const hex = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+      expect(normalizePubkey(`  ${hex}  `)).toBe(hex);
+    });
+
+    it("rejects invalid hex", () => {
+      expect(() => normalizePubkey("invalid")).toThrow("Pubkey must be 64 hex characters");
+    });
+  });
+});
+
+describe("getPublicKeyFromPrivate", () => {
+  it("derives public key from hex private key", () => {
+    const pubkey = getPublicKeyFromPrivate(TEST_HEX_KEY);
+    expect(pubkey).toMatch(/^[0-9a-f]{64}$/);
+    expect(pubkey.length).toBe(64);
+  });
+
+  it("derives consistent public key", () => {
+    const pubkey1 = getPublicKeyFromPrivate(TEST_HEX_KEY);
+    const pubkey2 = getPublicKeyFromPrivate(TEST_HEX_KEY);
+    expect(pubkey1).toBe(pubkey2);
+  });
+
+  it("throws for invalid private key", () => {
+    expect(() => getPublicKeyFromPrivate("invalid")).toThrow();
+  });
+});
+
+describe("pubkeyToNpub", () => {
+  it("converts hex pubkey to npub format", () => {
+    const hex = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+    const npub = pubkeyToNpub(hex);
+    expect(npub).toMatch(/^npub1[a-z0-9]+$/);
+  });
+
+  it("produces consistent output", () => {
+    const hex = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+    const npub1 = pubkeyToNpub(hex);
+    const npub2 = pubkeyToNpub(hex);
+    expect(npub1).toBe(npub2);
+  });
+
+  it("normalizes uppercase hex first", () => {
+    const lower = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+    const upper = lower.toUpperCase();
+    expect(pubkeyToNpub(lower)).toBe(pubkeyToNpub(upper));
+  });
+});

extensions/nostr/src/nostr-bus.ts

@@ -0,0 +1,741 @@
+import {
+  SimplePool,
+  finalizeEvent,
+  getPublicKey,
+  verifyEvent,
+  nip19,
+  type Event,
+} from "nostr-tools";
+import { decrypt, encrypt } from "nostr-tools/nip04";
+
+import {
+  readNostrBusState,
+  writeNostrBusState,
+  computeSinceTimestamp,
+  readNostrProfileState,
+  writeNostrProfileState,
+} from "./nostr-state-store.js";
+import {
+  publishProfile as publishProfileFn,
+  type ProfilePublishResult,
+} from "./nostr-profile.js";
+import type { NostrProfile } from "./config-schema.js";
+import { createSeenTracker, type SeenTracker } from "./seen-tracker.js";
+import {
+  createMetrics,
+  createNoopMetrics,
+  type NostrMetrics,
+  type MetricsSnapshot,
+  type MetricEvent,
+} from "./metrics.js";
+
+export const DEFAULT_RELAYS = ["wss://relay.damus.io", "wss://nos.lol"];
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const STARTUP_LOOKBACK_SEC = 120; // tolerate relay lag / clock skew
+const MAX_PERSISTED_EVENT_IDS = 5000;
+const STATE_PERSIST_DEBOUNCE_MS = 5000; // Debounce state writes
+
+// Reconnect configuration (exponential backoff with jitter)
+const RECONNECT_BASE_MS = 1000; // 1 second base
+const RECONNECT_MAX_MS = 60000; // 60 seconds max
+const RECONNECT_JITTER = 0.3; // ±30% jitter
+
+// Circuit breaker configuration
+const CIRCUIT_BREAKER_THRESHOLD = 5; // failures before opening
+const CIRCUIT_BREAKER_RESET_MS = 30000; // 30 seconds before half-open
+
+// Health tracker configuration
+const HEALTH_WINDOW_MS = 60000; // 1 minute window for health stats
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface NostrBusOptions {
+  /** Private key in hex or nsec format */
+  privateKey: string;
+  /** WebSocket relay URLs (defaults to damus + nos.lol) */
+  relays?: string[];
+  /** Account ID for state persistence (optional, defaults to pubkey prefix) */
+  accountId?: string;
+  /** Called when a DM is received */
+  onMessage: (
+    pubkey: string,
+    text: string,
+    reply: (text: string) => Promise<void>
+  ) => Promise<void>;
+  /** Called on errors (optional) */
+  onError?: (error: Error, context: string) => void;
+  /** Called on connection status changes (optional) */
+  onConnect?: (relay: string) => void;
+  /** Called on disconnection (optional) */
+  onDisconnect?: (relay: string) => void;
+  /** Called on EOSE (end of stored events) for initial sync (optional) */
+  onEose?: (relay: string) => void;
+  /** Called on each metric event (optional) */
+  onMetric?: (event: MetricEvent) => void;
+  /** Maximum entries in seen tracker (default: 100,000) */
+  maxSeenEntries?: number;
+  /** Seen tracker TTL in ms (default: 1 hour) */
+  seenTtlMs?: number;
+}
+
+export interface NostrBusHandle {
+  /** Stop the bus and close connections */
+  close: () => void;
+  /** Get the bot's public key */
+  publicKey: string;
+  /** Send a DM to a pubkey */
+  sendDm: (toPubkey: string, text: string) => Promise<void>;
+  /** Get current metrics snapshot */
+  getMetrics: () => MetricsSnapshot;
+  /** Publish a profile (kind:0) to all relays */
+  publishProfile: (profile: NostrProfile) => Promise<ProfilePublishResult>;
+  /** Get the last profile publish state */
+  getProfileState: () => Promise<{
+    lastPublishedAt: number | null;
+    lastPublishedEventId: string | null;
+    lastPublishResults: Record<string, "ok" | "failed" | "timeout"> | null;
+  }>;
+}
+
+// ============================================================================
+// Circuit Breaker
+// ============================================================================
+
+interface CircuitBreakerState {
+  state: "closed" | "open" | "half_open";
+  failures: number;
+  lastFailure: number;
+  lastSuccess: number;
+}
+
+interface CircuitBreaker {
+  /** Check if requests should be allowed */
+  canAttempt: () => boolean;
+  /** Record a success */
+  recordSuccess: () => void;
+  /** Record a failure */
+  recordFailure: () => void;
+  /** Get current state */
+  getState: () => CircuitBreakerState["state"];
+}
+
+function createCircuitBreaker(
+  relay: string,
+  metrics: NostrMetrics,
+  threshold: number = CIRCUIT_BREAKER_THRESHOLD,
+  resetMs: number = CIRCUIT_BREAKER_RESET_MS
+): CircuitBreaker {
+  const state: CircuitBreakerState = {
+    state: "closed",
+    failures: 0,
+    lastFailure: 0,
+    lastSuccess: Date.now(),
+  };
+
+  return {
+    canAttempt(): boolean {
+      if (state.state === "closed") return true;
+
+      if (state.state === "open") {
+        // Check if enough time has passed to try half-open
+        if (Date.now() - state.lastFailure >= resetMs) {
+          state.state = "half_open";
+          metrics.emit("relay.circuit_breaker.half_open", 1, { relay });
+          return true;
+        }
+        return false;
+      }
+
+      // half_open: allow one attempt
+      return true;
+    },
+
+    recordSuccess(): void {
+      if (state.state === "half_open") {
+        state.state = "closed";
+        state.failures = 0;
+        metrics.emit("relay.circuit_breaker.close", 1, { relay });
+      } else if (state.state === "closed") {
+        state.failures = 0;
+      }
+      state.lastSuccess = Date.now();
+    },
+
+    recordFailure(): void {
+      state.failures++;
+      state.lastFailure = Date.now();
+
+      if (state.state === "half_open") {
+        state.state = "open";
+        metrics.emit("relay.circuit_breaker.open", 1, { relay });
+      } else if (state.state === "closed" && state.failures >= threshold) {
+        state.state = "open";
+        metrics.emit("relay.circuit_breaker.open", 1, { relay });
+      }
+    },
+
+    getState(): CircuitBreakerState["state"] {
+      return state.state;
+    },
+  };
+}
+
+// ============================================================================
+// Relay Health Tracker
+// ============================================================================
+
+interface RelayHealthStats {
+  successCount: number;
+  failureCount: number;
+  latencySum: number;
+  latencyCount: number;
+  lastSuccess: number;
+  lastFailure: number;
+}
+
+interface RelayHealthTracker {
+  /** Record a successful operation */
+  recordSuccess: (relay: string, latencyMs: number) => void;
+  /** Record a failed operation */
+  recordFailure: (relay: string) => void;
+  /** Get health score (0-1, higher is better) */
+  getScore: (relay: string) => number;
+  /** Get relays sorted by health (best first) */
+  getSortedRelays: (relays: string[]) => string[];
+}
+
+function createRelayHealthTracker(): RelayHealthTracker {
+  const stats = new Map<string, RelayHealthStats>();
+
+  function getOrCreate(relay: string): RelayHealthStats {
+    let s = stats.get(relay);
+    if (!s) {
+      s = {
+        successCount: 0,
+        failureCount: 0,
+        latencySum: 0,
+        latencyCount: 0,
+        lastSuccess: 0,
+        lastFailure: 0,
+      };
+      stats.set(relay, s);
+    }
+    return s;
+  }
+
+  return {
+    recordSuccess(relay: string, latencyMs: number): void {
+      const s = getOrCreate(relay);
+      s.successCount++;
+      s.latencySum += latencyMs;
+      s.latencyCount++;
+      s.lastSuccess = Date.now();
+    },
+
+    recordFailure(relay: string): void {
+      const s = getOrCreate(relay);
+      s.failureCount++;
+      s.lastFailure = Date.now();
+    },
+
+    getScore(relay: string): number {
+      const s = stats.get(relay);
+      if (!s) return 0.5; // Unknown relay gets neutral score
+
+      const total = s.successCount + s.failureCount;
+      if (total === 0) return 0.5;
+
+      // Success rate (0-1)
+      const successRate = s.successCount / total;
+
+      // Recency bonus (prefer recently successful relays)
+      const now = Date.now();
+      const recencyBonus =
+        s.lastSuccess > s.lastFailure
+          ? Math.max(0, 1 - (now - s.lastSuccess) / HEALTH_WINDOW_MS) * 0.2
+          : 0;
+
+      // Latency penalty (lower is better)
+      const avgLatency =
+        s.latencyCount > 0 ? s.latencySum / s.latencyCount : 1000;
+      const latencyPenalty = Math.min(0.2, avgLatency / 10000);
+
+      return Math.max(0, Math.min(1, successRate + recencyBonus - latencyPenalty));
+    },
+
+    getSortedRelays(relays: string[]): string[] {
+      return [...relays].sort((a, b) => this.getScore(b) - this.getScore(a));
+    },
+  };
+}
+
+// ============================================================================
+// Reconnect with Exponential Backoff + Jitter
+// ============================================================================
+
+function computeReconnectDelay(attempt: number): number {
+  // Exponential backoff: base * 2^attempt
+  const exponential = RECONNECT_BASE_MS * Math.pow(2, attempt);
+  const capped = Math.min(exponential, RECONNECT_MAX_MS);
+
+  // Add jitter: ±JITTER%
+  const jitter = capped * RECONNECT_JITTER * (Math.random() * 2 - 1);
+  return Math.max(RECONNECT_BASE_MS, capped + jitter);
+}
+
+// ============================================================================
+// Key Validation
+// ============================================================================
+
+/**
+ * Validate and normalize a private key (accepts hex or nsec format)
+ */
+export function validatePrivateKey(key: string): Uint8Array {
+  const trimmed = key.trim();
+
+  // Handle nsec (bech32) format
+  if (trimmed.startsWith("nsec1")) {
+    const decoded = nip19.decode(trimmed);
+    if (decoded.type !== "nsec") {
+      throw new Error("Invalid nsec key: wrong type");
+    }
+    return decoded.data;
+  }
+
+  // Handle hex format
+  if (!/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+    throw new Error(
+      "Private key must be 64 hex characters or nsec bech32 format"
+    );
+  }
+
+  // Convert hex string to Uint8Array
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = parseInt(trimmed.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Get public key from private key (hex or nsec format)
+ */
+export function getPublicKeyFromPrivate(privateKey: string): string {
+  const sk = validatePrivateKey(privateKey);
+  return getPublicKey(sk);
+}
+
+// ============================================================================
+// Main Bus
+// ============================================================================
+
+/**
+ * Start the Nostr DM bus - subscribes to NIP-04 encrypted DMs
+ */
+export async function startNostrBus(
+  options: NostrBusOptions
+): Promise<NostrBusHandle> {
+  const {
+    privateKey,
+    relays = DEFAULT_RELAYS,
+    onMessage,
+    onError,
+    onEose,
+    onMetric,
+    maxSeenEntries = 100_000,
+    seenTtlMs = 60 * 60 * 1000,
+  } = options;
+
+  const sk = validatePrivateKey(privateKey);
+  const pk = getPublicKey(sk);
+  const pool = new SimplePool();
+  const accountId = options.accountId ?? pk.slice(0, 16);
+  const gatewayStartedAt = Math.floor(Date.now() / 1000);
+
+  // Initialize metrics
+  const metrics = onMetric ? createMetrics(onMetric) : createNoopMetrics();
+
+  // Initialize seen tracker with LRU
+  const seen: SeenTracker = createSeenTracker({
+    maxEntries: maxSeenEntries,
+    ttlMs: seenTtlMs,
+  });
+
+  // Initialize circuit breakers and health tracker
+  const circuitBreakers = new Map<string, CircuitBreaker>();
+  const healthTracker = createRelayHealthTracker();
+
+  for (const relay of relays) {
+    circuitBreakers.set(relay, createCircuitBreaker(relay, metrics));
+  }
+
+  // Read persisted state and compute `since` timestamp (with small overlap)
+  const state = await readNostrBusState({ accountId });
+  const baseSince = computeSinceTimestamp(state, gatewayStartedAt);
+  const since = Math.max(0, baseSince - STARTUP_LOOKBACK_SEC);
+
+  // Seed in-memory dedupe with recent IDs from disk (prevents restart replay)
+  if (state?.recentEventIds?.length) {
+    seen.seed(state.recentEventIds);
+  }
+
+  // Persist startup timestamp
+  await writeNostrBusState({
+    accountId,
+    lastProcessedAt: state?.lastProcessedAt ?? gatewayStartedAt,
+    gatewayStartedAt,
+    recentEventIds: state?.recentEventIds ?? [],
+  });
+
+  // Debounced state persistence
+  let pendingWrite: ReturnType<typeof setTimeout> | undefined;
+  let lastProcessedAt = state?.lastProcessedAt ?? gatewayStartedAt;
+  let recentEventIds = (state?.recentEventIds ?? []).slice(
+    -MAX_PERSISTED_EVENT_IDS
+  );
+
+  function scheduleStatePersist(eventCreatedAt: number, eventId: string): void {
+    lastProcessedAt = Math.max(lastProcessedAt, eventCreatedAt);
+    recentEventIds.push(eventId);
+    if (recentEventIds.length > MAX_PERSISTED_EVENT_IDS) {
+      recentEventIds = recentEventIds.slice(-MAX_PERSISTED_EVENT_IDS);
+    }
+
+    if (pendingWrite) clearTimeout(pendingWrite);
+    pendingWrite = setTimeout(() => {
+      writeNostrBusState({
+        accountId,
+        lastProcessedAt,
+        gatewayStartedAt,
+        recentEventIds,
+      }).catch((err) => onError?.(err as Error, "persist state"));
+    }, STATE_PERSIST_DEBOUNCE_MS);
+  }
+
+  const inflight = new Set<string>();
+
+  // Event handler
+  async function handleEvent(event: Event): Promise<void> {
+    try {
+      metrics.emit("event.received");
+
+      // Fast dedupe check (handles relay reconnections)
+      if (seen.peek(event.id) || inflight.has(event.id)) {
+        metrics.emit("event.duplicate");
+        return;
+      }
+      inflight.add(event.id);
+
+      // Self-message loop prevention: skip our own messages
+      if (event.pubkey === pk) {
+        metrics.emit("event.rejected.self_message");
+        return;
+      }
+
+      // Skip events older than our `since` (relay may ignore filter)
+      if (event.created_at < since) {
+        metrics.emit("event.rejected.stale");
+        return;
+      }
+
+      // Fast p-tag check BEFORE crypto (no allocation, cheaper)
+      let targetsUs = false;
+      for (const t of event.tags) {
+        if (t[0] === "p" && t[1] === pk) {
+          targetsUs = true;
+          break;
+        }
+      }
+      if (!targetsUs) {
+        metrics.emit("event.rejected.wrong_kind");
+        return;
+      }
+
+      // Verify signature (must pass before we trust the event)
+      if (!verifyEvent(event)) {
+        metrics.emit("event.rejected.invalid_signature");
+        onError?.(new Error("Invalid signature"), `event ${event.id}`);
+        return;
+      }
+
+      // Mark seen AFTER verify (don't cache invalid IDs)
+      seen.add(event.id);
+      metrics.emit("memory.seen_tracker_size", seen.size());
+
+      // Decrypt the message
+      let plaintext: string;
+      try {
+        plaintext = await decrypt(sk, event.pubkey, event.content);
+        metrics.emit("decrypt.success");
+      } catch (err) {
+        metrics.emit("decrypt.failure");
+        metrics.emit("event.rejected.decrypt_failed");
+        onError?.(err as Error, `decrypt from ${event.pubkey}`);
+        return;
+      }
+
+      // Create reply function (try relays by health score)
+      const replyTo = async (text: string): Promise<void> => {
+        await sendEncryptedDm(
+          pool,
+          sk,
+          event.pubkey,
+          text,
+          relays,
+          metrics,
+          circuitBreakers,
+          healthTracker,
+          onError
+        );
+      };
+
+      // Call the message handler
+      await onMessage(event.pubkey, plaintext, replyTo);
+
+      // Mark as processed
+      metrics.emit("event.processed");
+
+      // Persist progress (debounced)
+      scheduleStatePersist(event.created_at, event.id);
+    } catch (err) {
+      onError?.(err as Error, `event ${event.id}`);
+    } finally {
+      inflight.delete(event.id);
+    }
+  }
+
+  const sub = pool.subscribeMany(
+    relays,
+    [{ kinds: [4], "#p": [pk], since }],
+    {
+      onevent: handleEvent,
+      oneose: () => {
+        // EOSE handler - called when all stored events have been received
+        for (const relay of relays) {
+          metrics.emit("relay.message.eose", 1, { relay });
+        }
+        onEose?.(relays.join(", "));
+      },
+      onclose: (reason) => {
+        // Handle subscription close
+        for (const relay of relays) {
+          metrics.emit("relay.message.closed", 1, { relay });
+          options.onDisconnect?.(relay);
+        }
+        onError?.(
+          new Error(`Subscription closed: ${reason}`),
+          "subscription"
+        );
+      },
+    }
+  );
+
+  // Public sendDm function
+  const sendDm = async (toPubkey: string, text: string): Promise<void> => {
+    await sendEncryptedDm(
+      pool,
+      sk,
+      toPubkey,
+      text,
+      relays,
+      metrics,
+      circuitBreakers,
+      healthTracker,
+      onError
+    );
+  };
+
+  // Profile publishing function
+  const publishProfile = async (profile: NostrProfile): Promise<ProfilePublishResult> => {
+    // Read last published timestamp for monotonic ordering
+    const profileState = await readNostrProfileState({ accountId });
+    const lastPublishedAt = profileState?.lastPublishedAt ?? undefined;
+
+    // Publish the profile
+    const result = await publishProfileFn(pool, sk, relays, profile, lastPublishedAt);
+
+    // Convert results to state format
+    const publishResults: Record<string, "ok" | "failed" | "timeout"> = {};
+    for (const relay of result.successes) {
+      publishResults[relay] = "ok";
+    }
+    for (const { relay, error } of result.failures) {
+      publishResults[relay] = error === "timeout" ? "timeout" : "failed";
+    }
+
+    // Persist the publish state
+    await writeNostrProfileState({
+      accountId,
+      lastPublishedAt: result.createdAt,
+      lastPublishedEventId: result.eventId,
+      lastPublishResults: publishResults,
+    });
+
+    return result;
+  };
+
+  // Get profile state function
+  const getProfileState = async () => {
+    const state = await readNostrProfileState({ accountId });
+    return {
+      lastPublishedAt: state?.lastPublishedAt ?? null,
+      lastPublishedEventId: state?.lastPublishedEventId ?? null,
+      lastPublishResults: state?.lastPublishResults ?? null,
+    };
+  };
+
+  return {
+    close: () => {
+      sub.close();
+      seen.stop();
+      // Flush pending state write synchronously on close
+      if (pendingWrite) {
+        clearTimeout(pendingWrite);
+        writeNostrBusState({
+          accountId,
+          lastProcessedAt,
+          gatewayStartedAt,
+          recentEventIds,
+        }).catch((err) => onError?.(err as Error, "persist state on close"));
+      }
+    },
+    publicKey: pk,
+    sendDm,
+    getMetrics: () => metrics.getSnapshot(),
+    publishProfile,
+    getProfileState,
+  };
+}
+
+// ============================================================================
+// Send DM with Circuit Breaker + Health Scoring
+// ============================================================================
+
+/**
+ * Send an encrypted DM to a pubkey
+ */
+async function sendEncryptedDm(
+  pool: SimplePool,
+  sk: Uint8Array,
+  toPubkey: string,
+  text: string,
+  relays: string[],
+  metrics: NostrMetrics,
+  circuitBreakers: Map<string, CircuitBreaker>,
+  healthTracker: RelayHealthTracker,
+  onError?: (error: Error, context: string) => void
+): Promise<void> {
+  const ciphertext = await encrypt(sk, toPubkey, text);
+  const reply = finalizeEvent(
+    {
+      kind: 4,
+      content: ciphertext,
+      tags: [["p", toPubkey]],
+      created_at: Math.floor(Date.now() / 1000),
+    },
+    sk
+  );
+
+  // Sort relays by health score (best first)
+  const sortedRelays = healthTracker.getSortedRelays(relays);
+
+  // Try relays in order of health, respecting circuit breakers
+  let lastError: Error | undefined;
+  for (const relay of sortedRelays) {
+    const cb = circuitBreakers.get(relay);
+
+    // Skip if circuit breaker is open
+    if (cb && !cb.canAttempt()) {
+      continue;
+    }
+
+    const startTime = Date.now();
+    try {
+      await pool.publish([relay], reply);
+      const latency = Date.now() - startTime;
+
+      // Record success
+      cb?.recordSuccess();
+      healthTracker.recordSuccess(relay, latency);
+
+      return; // Success - exit early
+    } catch (err) {
+      lastError = err as Error;
+      const latency = Date.now() - startTime;
+
+      // Record failure
+      cb?.recordFailure();
+      healthTracker.recordFailure(relay);
+      metrics.emit("relay.error", 1, { relay, latency });
+
+      onError?.(lastError, `publish to ${relay}`);
+    }
+  }
+
+  throw new Error(`Failed to publish to any relay: ${lastError?.message}`);
+}
+
+// ============================================================================
+// Pubkey Utilities
+// ============================================================================
+
+/**
+ * Check if a string looks like a valid Nostr pubkey (hex or npub)
+ */
+export function isValidPubkey(input: string): boolean {
+  if (typeof input !== "string") return false;
+  const trimmed = input.trim();
+
+  // npub format
+  if (trimmed.startsWith("npub1")) {
+    try {
+      const decoded = nip19.decode(trimmed);
+      return decoded.type === "npub";
+    } catch {
+      return false;
+    }
+  }
+
+  // Hex format
+  return /^[0-9a-fA-F]{64}$/.test(trimmed);
+}
+
+/**
+ * Normalize a pubkey to hex format (accepts npub or hex)
+ */
+export function normalizePubkey(input: string): string {
+  const trimmed = input.trim();
+
+  // npub format - decode to hex
+  if (trimmed.startsWith("npub1")) {
+    const decoded = nip19.decode(trimmed);
+    if (decoded.type !== "npub") {
+      throw new Error("Invalid npub key");
+    }
+    // Convert Uint8Array to hex string
+    return Array.from(decoded.data)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+  }
+
+  // Already hex - validate and return lowercase
+  if (!/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+    throw new Error("Pubkey must be 64 hex characters or npub format");
+  }
+  return trimmed.toLowerCase();
+}
+
+/**
+ * Convert a hex pubkey to npub format
+ */
+export function pubkeyToNpub(hexPubkey: string): string {
+  const normalized = normalizePubkey(hexPubkey);
+  // npubEncode expects a hex string, not Uint8Array
+  return nip19.npubEncode(normalized);
+}

extensions/nostr/src/nostr-profile-http.test.ts

@@ -0,0 +1,378 @@
+/**
+ * Tests for Nostr Profile HTTP Handler
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Socket } from "node:net";
+
+import {
+  createNostrProfileHttpHandler,
+  type NostrProfileHttpContext,
+} from "./nostr-profile-http.js";
+
+// Mock the channel exports
+vi.mock("./channel.js", () => ({
+  publishNostrProfile: vi.fn(),
+  getNostrProfileState: vi.fn(),
+}));
+
+// Mock the import module
+vi.mock("./nostr-profile-import.js", () => ({
+  importProfileFromRelays: vi.fn(),
+  mergeProfiles: vi.fn((local, imported) => ({ ...imported, ...local })),
+}));
+
+import { publishNostrProfile, getNostrProfileState } from "./channel.js";
+import { importProfileFromRelays } from "./nostr-profile-import.js";
+
+// ============================================================================
+// Test Helpers
+// ============================================================================
+
+function createMockRequest(
+  method: string,
+  url: string,
+  body?: unknown
+): IncomingMessage {
+  const socket = new Socket();
+  const req = new IncomingMessage(socket);
+  req.method = method;
+  req.url = url;
+  req.headers = { host: "localhost:3000" };
+
+  if (body) {
+    const bodyStr = JSON.stringify(body);
+    process.nextTick(() => {
+      req.emit("data", Buffer.from(bodyStr));
+      req.emit("end");
+    });
+  } else {
+    process.nextTick(() => {
+      req.emit("end");
+    });
+  }
+
+  return req;
+}
+
+function createMockResponse(): ServerResponse & { _getData: () => string; _getStatusCode: () => number } {
+  const socket = new Socket();
+  const res = new ServerResponse({} as IncomingMessage);
+
+  let data = "";
+  let statusCode = 200;
+
+  res.write = function (chunk: unknown) {
+    data += String(chunk);
+    return true;
+  };
+
+  res.end = function (chunk?: unknown) {
+    if (chunk) data += String(chunk);
+    return this;
+  };
+
+  Object.defineProperty(res, "statusCode", {
+    get: () => statusCode,
+    set: (code: number) => {
+      statusCode = code;
+    },
+  });
+
+  (res as unknown as { _getData: () => string })._getData = () => data;
+  (res as unknown as { _getStatusCode: () => number })._getStatusCode = () => statusCode;
+
+  return res as ServerResponse & { _getData: () => string; _getStatusCode: () => number };
+}
+
+function createMockContext(overrides?: Partial<NostrProfileHttpContext>): NostrProfileHttpContext {
+  return {
+    getConfigProfile: vi.fn().mockReturnValue(undefined),
+    updateConfigProfile: vi.fn().mockResolvedValue(undefined),
+    getAccountInfo: vi.fn().mockReturnValue({
+      pubkey: "abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234",
+      relays: ["wss://relay.damus.io"],
+    }),
+    log: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+    ...overrides,
+  };
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe("nostr-profile-http", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("route matching", () => {
+    it("returns false for non-nostr paths", async () => {
+      const ctx = createMockContext();
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("GET", "/api/channels/telegram/profile");
+      const res = createMockResponse();
+
+      const result = await handler(req, res);
+
+      expect(result).toBe(false);
+    });
+
+    it("returns false for paths without accountId", async () => {
+      const ctx = createMockContext();
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("GET", "/api/channels/nostr/");
+      const res = createMockResponse();
+
+      const result = await handler(req, res);
+
+      expect(result).toBe(false);
+    });
+
+    it("handles /api/channels/nostr/:accountId/profile", async () => {
+      const ctx = createMockContext();
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("GET", "/api/channels/nostr/default/profile");
+      const res = createMockResponse();
+
+      vi.mocked(getNostrProfileState).mockResolvedValue(null);
+
+      const result = await handler(req, res);
+
+      expect(result).toBe(true);
+    });
+  });
+
+  describe("GET /api/channels/nostr/:accountId/profile", () => {
+    it("returns profile and publish state", async () => {
+      const ctx = createMockContext({
+        getConfigProfile: vi.fn().mockReturnValue({
+          name: "testuser",
+          displayName: "Test User",
+        }),
+      });
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("GET", "/api/channels/nostr/default/profile");
+      const res = createMockResponse();
+
+      vi.mocked(getNostrProfileState).mockResolvedValue({
+        lastPublishedAt: 1234567890,
+        lastPublishedEventId: "abc123",
+        lastPublishResults: { "wss://relay.damus.io": "ok" },
+      });
+
+      await handler(req, res);
+
+      expect(res._getStatusCode()).toBe(200);
+      const data = JSON.parse(res._getData());
+      expect(data.ok).toBe(true);
+      expect(data.profile.name).toBe("testuser");
+      expect(data.publishState.lastPublishedAt).toBe(1234567890);
+    });
+  });
+
+  describe("PUT /api/channels/nostr/:accountId/profile", () => {
+    it("validates profile and publishes", async () => {
+      const ctx = createMockContext();
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("PUT", "/api/channels/nostr/default/profile", {
+        name: "satoshi",
+        displayName: "Satoshi Nakamoto",
+        about: "Creator of Bitcoin",
+      });
+      const res = createMockResponse();
+
+      vi.mocked(publishNostrProfile).mockResolvedValue({
+        eventId: "event123",
+        createdAt: 1234567890,
+        successes: ["wss://relay.damus.io"],
+        failures: [],
+      });
+
+      await handler(req, res);
+
+      expect(res._getStatusCode()).toBe(200);
+      const data = JSON.parse(res._getData());
+      expect(data.ok).toBe(true);
+      expect(data.eventId).toBe("event123");
+      expect(data.successes).toContain("wss://relay.damus.io");
+      expect(data.persisted).toBe(true);
+      expect(ctx.updateConfigProfile).toHaveBeenCalled();
+    });
+
+    it("rejects private IP in picture URL (SSRF protection)", async () => {
+      const ctx = createMockContext();
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("PUT", "/api/channels/nostr/default/profile", {
+        name: "hacker",
+        picture: "https://127.0.0.1/evil.jpg",
+      });
+      const res = createMockResponse();
+
+      await handler(req, res);
+
+      expect(res._getStatusCode()).toBe(400);
+      const data = JSON.parse(res._getData());
+      expect(data.ok).toBe(false);
+      expect(data.error).toContain("private");
+    });
+
+    it("rejects non-https URLs", async () => {
+      const ctx = createMockContext();
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("PUT", "/api/channels/nostr/default/profile", {
+        name: "test",
+        picture: "http://example.com/pic.jpg",
+      });
+      const res = createMockResponse();
+
+      await handler(req, res);
+
+      expect(res._getStatusCode()).toBe(400);
+      const data = JSON.parse(res._getData());
+      expect(data.ok).toBe(false);
+      // The schema validation catches non-https URLs before SSRF check
+      expect(data.error).toBe("Validation failed");
+      expect(data.details).toBeDefined();
+      expect(data.details.some((d: string) => d.includes("https"))).toBe(true);
+    });
+
+    it("does not persist if all relays fail", async () => {
+      const ctx = createMockContext();
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("PUT", "/api/channels/nostr/default/profile", {
+        name: "test",
+      });
+      const res = createMockResponse();
+
+      vi.mocked(publishNostrProfile).mockResolvedValue({
+        eventId: "event123",
+        createdAt: 1234567890,
+        successes: [],
+        failures: [{ relay: "wss://relay.damus.io", error: "timeout" }],
+      });
+
+      await handler(req, res);
+
+      expect(res._getStatusCode()).toBe(200);
+      const data = JSON.parse(res._getData());
+      expect(data.persisted).toBe(false);
+      expect(ctx.updateConfigProfile).not.toHaveBeenCalled();
+    });
+
+    it("enforces rate limiting", async () => {
+      const ctx = createMockContext();
+      const handler = createNostrProfileHttpHandler(ctx);
+
+      vi.mocked(publishNostrProfile).mockResolvedValue({
+        eventId: "event123",
+        createdAt: 1234567890,
+        successes: ["wss://relay.damus.io"],
+        failures: [],
+      });
+
+      // Make 6 requests (limit is 5/min)
+      for (let i = 0; i < 6; i++) {
+        const req = createMockRequest("PUT", "/api/channels/nostr/rate-test/profile", {
+          name: `user${i}`,
+        });
+        const res = createMockResponse();
+        await handler(req, res);
+
+        if (i < 5) {
+          expect(res._getStatusCode()).toBe(200);
+        } else {
+          expect(res._getStatusCode()).toBe(429);
+          const data = JSON.parse(res._getData());
+          expect(data.error).toContain("Rate limit");
+        }
+      }
+    });
+  });
+
+  describe("POST /api/channels/nostr/:accountId/profile/import", () => {
+    it("imports profile from relays", async () => {
+      const ctx = createMockContext();
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("POST", "/api/channels/nostr/default/profile/import", {});
+      const res = createMockResponse();
+
+      vi.mocked(importProfileFromRelays).mockResolvedValue({
+        ok: true,
+        profile: {
+          name: "imported",
+          displayName: "Imported User",
+        },
+        event: {
+          id: "evt123",
+          pubkey: "abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234",
+          created_at: 1234567890,
+        },
+        relaysQueried: ["wss://relay.damus.io"],
+        sourceRelay: "wss://relay.damus.io",
+      });
+
+      await handler(req, res);
+
+      expect(res._getStatusCode()).toBe(200);
+      const data = JSON.parse(res._getData());
+      expect(data.ok).toBe(true);
+      expect(data.imported.name).toBe("imported");
+      expect(data.saved).toBe(false); // autoMerge not requested
+    });
+
+    it("auto-merges when requested", async () => {
+      const ctx = createMockContext({
+        getConfigProfile: vi.fn().mockReturnValue({ about: "local bio" }),
+      });
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("POST", "/api/channels/nostr/default/profile/import", {
+        autoMerge: true,
+      });
+      const res = createMockResponse();
+
+      vi.mocked(importProfileFromRelays).mockResolvedValue({
+        ok: true,
+        profile: {
+          name: "imported",
+          displayName: "Imported User",
+        },
+        event: {
+          id: "evt123",
+          pubkey: "abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234",
+          created_at: 1234567890,
+        },
+        relaysQueried: ["wss://relay.damus.io"],
+        sourceRelay: "wss://relay.damus.io",
+      });
+
+      await handler(req, res);
+
+      expect(res._getStatusCode()).toBe(200);
+      const data = JSON.parse(res._getData());
+      expect(data.saved).toBe(true);
+      expect(ctx.updateConfigProfile).toHaveBeenCalled();
+    });
+
+    it("returns error when account not found", async () => {
+      const ctx = createMockContext({
+        getAccountInfo: vi.fn().mockReturnValue(null),
+      });
+      const handler = createNostrProfileHttpHandler(ctx);
+      const req = createMockRequest("POST", "/api/channels/nostr/unknown/profile/import", {});
+      const res = createMockResponse();
+
+      await handler(req, res);
+
+      expect(res._getStatusCode()).toBe(404);
+      const data = JSON.parse(res._getData());
+      expect(data.error).toContain("not found");
+    });
+  });
+});

extensions/nostr/src/nostr-profile-http.ts

@@ -0,0 +1,500 @@
+/**
+ * Nostr Profile HTTP Handler
+ *
+ * Handles HTTP requests for profile management:
+ * - PUT /api/channels/nostr/:accountId/profile - Update and publish profile
+ * - POST /api/channels/nostr/:accountId/profile/import - Import from relays
+ * - GET /api/channels/nostr/:accountId/profile - Get current profile state
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+
+import { NostrProfileSchema, type NostrProfile } from "./config-schema.js";
+import { publishNostrProfile, getNostrProfileState } from "./channel.js";
+import { importProfileFromRelays, mergeProfiles } from "./nostr-profile-import.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface NostrProfileHttpContext {
+  /** Get current profile from config */
+  getConfigProfile: (accountId: string) => NostrProfile | undefined;
+  /** Update profile in config (after successful publish) */
+  updateConfigProfile: (accountId: string, profile: NostrProfile) => Promise<void>;
+  /** Get account's public key and relays */
+  getAccountInfo: (accountId: string) => { pubkey: string; relays: string[] } | null;
+  /** Logger */
+  log?: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}
+
+// ============================================================================
+// Rate Limiting
+// ============================================================================
+
+interface RateLimitEntry {
+  count: number;
+  windowStart: number;
+}
+
+const rateLimitMap = new Map<string, RateLimitEntry>();
+const RATE_LIMIT_WINDOW_MS = 60_000; // 1 minute
+const RATE_LIMIT_MAX_REQUESTS = 5; // 5 requests per minute
+
+function checkRateLimit(accountId: string): boolean {
+  const now = Date.now();
+  const entry = rateLimitMap.get(accountId);
+
+  if (!entry || now - entry.windowStart > RATE_LIMIT_WINDOW_MS) {
+    rateLimitMap.set(accountId, { count: 1, windowStart: now });
+    return true;
+  }
+
+  if (entry.count >= RATE_LIMIT_MAX_REQUESTS) {
+    return false;
+  }
+
+  entry.count++;
+  return true;
+}
+
+// ============================================================================
+// Mutex for Concurrent Publish Prevention
+// ============================================================================
+
+const publishLocks = new Map<string, Promise<void>>();
+
+async function withPublishLock<T>(accountId: string, fn: () => Promise<T>): Promise<T> {
+  // Atomic mutex using promise chaining - prevents TOCTOU race condition
+  const prev = publishLocks.get(accountId) ?? Promise.resolve();
+  let resolve: () => void;
+  const next = new Promise<void>((r) => {
+    resolve = r;
+  });
+  // Atomically replace the lock before awaiting - any concurrent request
+  // will now wait on our `next` promise
+  publishLocks.set(accountId, next);
+
+  // Wait for previous operation to complete
+  await prev.catch(() => {});
+
+  try {
+    return await fn();
+  } finally {
+    resolve!();
+    // Clean up if we're the last in chain
+    if (publishLocks.get(accountId) === next) {
+      publishLocks.delete(accountId);
+    }
+  }
+}
+
+// ============================================================================
+// SSRF Protection
+// ============================================================================
+
+// Block common private/internal hostnames (quick string check)
+const BLOCKED_HOSTNAMES = new Set([
+  "localhost",
+  "localhost.localdomain",
+  "127.0.0.1",
+  "::1",
+  "[::1]",
+  "0.0.0.0",
+]);
+
+// Check if an IP address (resolved) is in a private range
+function isPrivateIp(ip: string): boolean {
+  // Handle IPv4
+  const ipv4Match = ip.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+  if (ipv4Match) {
+    const [, a, b, c] = ipv4Match.map(Number);
+    // 127.0.0.0/8 (loopback)
+    if (a === 127) return true;
+    // 10.0.0.0/8 (private)
+    if (a === 10) return true;
+    // 172.16.0.0/12 (private)
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    // 192.168.0.0/16 (private)
+    if (a === 192 && b === 168) return true;
+    // 169.254.0.0/16 (link-local)
+    if (a === 169 && b === 254) return true;
+    // 0.0.0.0/8
+    if (a === 0) return true;
+    return false;
+  }
+
+  // Handle IPv6
+  const ipLower = ip.toLowerCase().replace(/^\[|\]$/g, "");
+  // ::1 (loopback)
+  if (ipLower === "::1") return true;
+  // fe80::/10 (link-local)
+  if (ipLower.startsWith("fe80:")) return true;
+  // fc00::/7 (unique local)
+  if (ipLower.startsWith("fc") || ipLower.startsWith("fd")) return true;
+  // ::ffff:x.x.x.x (IPv4-mapped IPv6) - extract and check IPv4
+  const v4Mapped = ipLower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (v4Mapped) return isPrivateIp(v4Mapped[1]);
+
+  return false;
+}
+
+function validateUrlSafety(urlStr: string): { ok: true } | { ok: false; error: string } {
+  try {
+    const url = new URL(urlStr);
+
+    if (url.protocol !== "https:") {
+      return { ok: false, error: "URL must use https:// protocol" };
+    }
+
+    const hostname = url.hostname.toLowerCase();
+
+    // Quick hostname block check
+    if (BLOCKED_HOSTNAMES.has(hostname)) {
+      return { ok: false, error: "URL must not point to private/internal addresses" };
+    }
+
+    // Check if hostname is an IP address directly
+    if (isPrivateIp(hostname)) {
+      return { ok: false, error: "URL must not point to private/internal addresses" };
+    }
+
+    // Block suspicious TLDs that resolve to localhost
+    if (hostname.endsWith(".localhost") || hostname.endsWith(".local")) {
+      return { ok: false, error: "URL must not point to private/internal addresses" };
+    }
+
+    return { ok: true };
+  } catch {
+    return { ok: false, error: "Invalid URL format" };
+  }
+}
+
+// Export for use in import validation
+export { validateUrlSafety }
+
+// ============================================================================
+// Validation Schemas
+// ============================================================================
+
+// NIP-05 format: user@domain.com
+const nip05FormatSchema = z
+  .string()
+  .regex(/^[a-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,}$/i, "Invalid NIP-05 format (user@domain.com)")
+  .optional();
+
+// LUD-16 Lightning address format: user@domain.com
+const lud16FormatSchema = z
+  .string()
+  .regex(/^[a-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,}$/i, "Invalid Lightning address format")
+  .optional();
+
+// Extended profile schema with additional format validation
+const ProfileUpdateSchema = NostrProfileSchema.extend({
+  nip05: nip05FormatSchema,
+  lud16: lud16FormatSchema,
+});
+
+// ============================================================================
+// Request Helpers
+// ============================================================================
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(body));
+}
+
+async function readJsonBody(req: IncomingMessage, maxBytes = 64 * 1024): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let totalBytes = 0;
+
+    req.on("data", (chunk: Buffer) => {
+      totalBytes += chunk.length;
+      if (totalBytes > maxBytes) {
+        reject(new Error("Request body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    req.on("end", () => {
+      try {
+        const body = Buffer.concat(chunks).toString("utf-8");
+        resolve(body ? JSON.parse(body) : {});
+      } catch {
+        reject(new Error("Invalid JSON"));
+      }
+    });
+
+    req.on("error", reject);
+  });
+}
+
+function parseAccountIdFromPath(pathname: string): string | null {
+  // Match: /api/channels/nostr/:accountId/profile
+  const match = pathname.match(/^\/api\/channels\/nostr\/([^/]+)\/profile/);
+  return match?.[1] ?? null;
+}
+
+// ============================================================================
+// HTTP Handler
+// ============================================================================
+
+export function createNostrProfileHttpHandler(
+  ctx: NostrProfileHttpContext
+): (req: IncomingMessage, res: ServerResponse) => Promise<boolean> {
+  return async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+
+    // Only handle /api/channels/nostr/:accountId/profile paths
+    if (!url.pathname.startsWith("/api/channels/nostr/")) {
+      return false;
+    }
+
+    const accountId = parseAccountIdFromPath(url.pathname);
+    if (!accountId) {
+      return false;
+    }
+
+    const isImport = url.pathname.endsWith("/profile/import");
+    const isProfilePath = url.pathname.endsWith("/profile") || isImport;
+
+    if (!isProfilePath) {
+      return false;
+    }
+
+    // Handle different HTTP methods
+    try {
+      if (req.method === "GET" && !isImport) {
+        return await handleGetProfile(accountId, ctx, res);
+      }
+
+      if (req.method === "PUT" && !isImport) {
+        return await handleUpdateProfile(accountId, ctx, req, res);
+      }
+
+      if (req.method === "POST" && isImport) {
+        return await handleImportProfile(accountId, ctx, req, res);
+      }
+
+      // Method not allowed
+      sendJson(res, 405, { ok: false, error: "Method not allowed" });
+      return true;
+    } catch (err) {
+      ctx.log?.error(`Profile HTTP error: ${String(err)}`);
+      sendJson(res, 500, { ok: false, error: "Internal server error" });
+      return true;
+    }
+  };
+}
+
+// ============================================================================
+// GET /api/channels/nostr/:accountId/profile
+// ============================================================================
+
+async function handleGetProfile(
+  accountId: string,
+  ctx: NostrProfileHttpContext,
+  res: ServerResponse
+): Promise<true> {
+  const configProfile = ctx.getConfigProfile(accountId);
+  const publishState = await getNostrProfileState(accountId);
+
+  sendJson(res, 200, {
+    ok: true,
+    profile: configProfile ?? null,
+    publishState: publishState ?? null,
+  });
+  return true;
+}
+
+// ============================================================================
+// PUT /api/channels/nostr/:accountId/profile
+// ============================================================================
+
+async function handleUpdateProfile(
+  accountId: string,
+  ctx: NostrProfileHttpContext,
+  req: IncomingMessage,
+  res: ServerResponse
+): Promise<true> {
+  // Rate limiting
+  if (!checkRateLimit(accountId)) {
+    sendJson(res, 429, { ok: false, error: "Rate limit exceeded (5 requests/minute)" });
+    return true;
+  }
+
+  // Parse body
+  let body: unknown;
+  try {
+    body = await readJsonBody(req);
+  } catch (err) {
+    sendJson(res, 400, { ok: false, error: String(err) });
+    return true;
+  }
+
+  // Validate profile
+  const parseResult = ProfileUpdateSchema.safeParse(body);
+  if (!parseResult.success) {
+    const errors = parseResult.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
+    sendJson(res, 400, { ok: false, error: "Validation failed", details: errors });
+    return true;
+  }
+
+  const profile = parseResult.data;
+
+  // SSRF check for picture URL
+  if (profile.picture) {
+    const pictureCheck = validateUrlSafety(profile.picture);
+    if (!pictureCheck.ok) {
+      sendJson(res, 400, { ok: false, error: `picture: ${pictureCheck.error}` });
+      return true;
+    }
+  }
+
+  // SSRF check for banner URL
+  if (profile.banner) {
+    const bannerCheck = validateUrlSafety(profile.banner);
+    if (!bannerCheck.ok) {
+      sendJson(res, 400, { ok: false, error: `banner: ${bannerCheck.error}` });
+      return true;
+    }
+  }
+
+  // SSRF check for website URL
+  if (profile.website) {
+    const websiteCheck = validateUrlSafety(profile.website);
+    if (!websiteCheck.ok) {
+      sendJson(res, 400, { ok: false, error: `website: ${websiteCheck.error}` });
+      return true;
+    }
+  }
+
+  // Merge with existing profile to preserve unknown fields
+  const existingProfile = ctx.getConfigProfile(accountId) ?? {};
+  const mergedProfile: NostrProfile = {
+    ...existingProfile,
+    ...profile,
+  };
+
+  // Publish with mutex to prevent concurrent publishes
+  try {
+    const result = await withPublishLock(accountId, async () => {
+      return await publishNostrProfile(accountId, mergedProfile);
+    });
+
+    // Only persist if at least one relay succeeded
+    if (result.successes.length > 0) {
+      await ctx.updateConfigProfile(accountId, mergedProfile);
+      ctx.log?.info(`[${accountId}] Profile published to ${result.successes.length} relay(s)`);
+    } else {
+      ctx.log?.warn(`[${accountId}] Profile publish failed on all relays`);
+    }
+
+    sendJson(res, 200, {
+      ok: true,
+      eventId: result.eventId,
+      createdAt: result.createdAt,
+      successes: result.successes,
+      failures: result.failures,
+      persisted: result.successes.length > 0,
+    });
+  } catch (err) {
+    ctx.log?.error(`[${accountId}] Profile publish error: ${String(err)}`);
+    sendJson(res, 500, { ok: false, error: `Publish failed: ${String(err)}` });
+  }
+
+  return true;
+}
+
+// ============================================================================
+// POST /api/channels/nostr/:accountId/profile/import
+// ============================================================================
+
+async function handleImportProfile(
+  accountId: string,
+  ctx: NostrProfileHttpContext,
+  req: IncomingMessage,
+  res: ServerResponse
+): Promise<true> {
+  // Get account info
+  const accountInfo = ctx.getAccountInfo(accountId);
+  if (!accountInfo) {
+    sendJson(res, 404, { ok: false, error: `Account not found: ${accountId}` });
+    return true;
+  }
+
+  const { pubkey, relays } = accountInfo;
+
+  if (!pubkey) {
+    sendJson(res, 400, { ok: false, error: "Account has no public key configured" });
+    return true;
+  }
+
+  // Parse options from body
+  let autoMerge = false;
+  try {
+    const body = await readJsonBody(req);
+    if (typeof body === "object" && body !== null) {
+      autoMerge = (body as { autoMerge?: boolean }).autoMerge === true;
+    }
+  } catch {
+    // Ignore body parse errors - use defaults
+  }
+
+  ctx.log?.info(`[${accountId}] Importing profile for ${pubkey.slice(0, 8)}...`);
+
+  // Import from relays
+  const result = await importProfileFromRelays({
+    pubkey,
+    relays,
+    timeoutMs: 10_000, // 10 seconds for import
+  });
+
+  if (!result.ok) {
+    sendJson(res, 200, {
+      ok: false,
+      error: result.error,
+      relaysQueried: result.relaysQueried,
+    });
+    return true;
+  }
+
+  // If autoMerge is requested, merge and save
+  if (autoMerge && result.profile) {
+    const localProfile = ctx.getConfigProfile(accountId);
+    const merged = mergeProfiles(localProfile, result.profile);
+    await ctx.updateConfigProfile(accountId, merged);
+    ctx.log?.info(`[${accountId}] Profile imported and merged`);
+
+    sendJson(res, 200, {
+      ok: true,
+      imported: result.profile,
+      merged,
+      saved: true,
+      event: result.event,
+      sourceRelay: result.sourceRelay,
+      relaysQueried: result.relaysQueried,
+    });
+    return true;
+  }
+
+  // Otherwise, just return the imported profile for review
+  sendJson(res, 200, {
+    ok: true,
+    imported: result.profile,
+    saved: false,
+    event: result.event,
+    sourceRelay: result.sourceRelay,
+    relaysQueried: result.relaysQueried,
+  });
+  return true;
+}

extensions/nostr/src/nostr-profile-import.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Tests for Nostr Profile Import
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+import { mergeProfiles, type ProfileImportOptions } from "./nostr-profile-import.js";
+import type { NostrProfile } from "./config-schema.js";
+
+// Note: importProfileFromRelays requires real network calls or complex mocking
+// of nostr-tools SimplePool, so we focus on unit testing mergeProfiles
+
+describe("nostr-profile-import", () => {
+  describe("mergeProfiles", () => {
+    it("returns empty object when both are undefined", () => {
+      const result = mergeProfiles(undefined, undefined);
+      expect(result).toEqual({});
+    });
+
+    it("returns imported when local is undefined", () => {
+      const imported: NostrProfile = {
+        name: "imported",
+        displayName: "Imported User",
+        about: "Bio from relay",
+      };
+      const result = mergeProfiles(undefined, imported);
+      expect(result).toEqual(imported);
+    });
+
+    it("returns local when imported is undefined", () => {
+      const local: NostrProfile = {
+        name: "local",
+        displayName: "Local User",
+      };
+      const result = mergeProfiles(local, undefined);
+      expect(result).toEqual(local);
+    });
+
+    it("prefers local values over imported", () => {
+      const local: NostrProfile = {
+        name: "localname",
+        about: "Local bio",
+      };
+      const imported: NostrProfile = {
+        name: "importedname",
+        displayName: "Imported Display",
+        about: "Imported bio",
+        picture: "https://example.com/pic.jpg",
+      };
+
+      const result = mergeProfiles(local, imported);
+
+      expect(result.name).toBe("localname"); // local wins
+      expect(result.displayName).toBe("Imported Display"); // imported fills gap
+      expect(result.about).toBe("Local bio"); // local wins
+      expect(result.picture).toBe("https://example.com/pic.jpg"); // imported fills gap
+    });
+
+    it("fills all missing fields from imported", () => {
+      const local: NostrProfile = {
+        name: "myname",
+      };
+      const imported: NostrProfile = {
+        name: "theirname",
+        displayName: "Their Name",
+        about: "Their bio",
+        picture: "https://example.com/pic.jpg",
+        banner: "https://example.com/banner.jpg",
+        website: "https://example.com",
+        nip05: "user@example.com",
+        lud16: "user@getalby.com",
+      };
+
+      const result = mergeProfiles(local, imported);
+
+      expect(result.name).toBe("myname");
+      expect(result.displayName).toBe("Their Name");
+      expect(result.about).toBe("Their bio");
+      expect(result.picture).toBe("https://example.com/pic.jpg");
+      expect(result.banner).toBe("https://example.com/banner.jpg");
+      expect(result.website).toBe("https://example.com");
+      expect(result.nip05).toBe("user@example.com");
+      expect(result.lud16).toBe("user@getalby.com");
+    });
+
+    it("handles empty strings as falsy (prefers imported)", () => {
+      const local: NostrProfile = {
+        name: "",
+        displayName: "",
+      };
+      const imported: NostrProfile = {
+        name: "imported",
+        displayName: "Imported",
+      };
+
+      const result = mergeProfiles(local, imported);
+
+      // Empty strings are still strings, so they "win" over imported
+      // This is JavaScript nullish coalescing behavior
+      expect(result.name).toBe("");
+      expect(result.displayName).toBe("");
+    });
+
+    it("handles null values in local (prefers imported)", () => {
+      const local: NostrProfile = {
+        name: undefined,
+        displayName: undefined,
+      };
+      const imported: NostrProfile = {
+        name: "imported",
+        displayName: "Imported",
+      };
+
+      const result = mergeProfiles(local, imported);
+
+      expect(result.name).toBe("imported");
+      expect(result.displayName).toBe("Imported");
+    });
+  });
+});

extensions/nostr/src/nostr-profile-import.ts

@@ -0,0 +1,259 @@
+/**
+ * Nostr Profile Import
+ *
+ * Fetches and verifies kind:0 profile events from relays.
+ * Used to import existing profiles before editing.
+ */
+
+import { SimplePool, verifyEvent, type Event } from "nostr-tools";
+
+import { contentToProfile, type ProfileContent } from "./nostr-profile.js";
+import type { NostrProfile } from "./config-schema.js";
+import { validateUrlSafety } from "./nostr-profile-http.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ProfileImportResult {
+  /** Whether the import was successful */
+  ok: boolean;
+  /** The imported profile (if found and valid) */
+  profile?: NostrProfile;
+  /** The raw event (for advanced users) */
+  event?: {
+    id: string;
+    pubkey: string;
+    created_at: number;
+  };
+  /** Error message if import failed */
+  error?: string;
+  /** Which relays responded */
+  relaysQueried: string[];
+  /** Which relay provided the winning event */
+  sourceRelay?: string;
+}
+
+export interface ProfileImportOptions {
+  /** The public key to fetch profile for */
+  pubkey: string;
+  /** Relay URLs to query */
+  relays: string[];
+  /** Timeout per relay in milliseconds (default: 5000) */
+  timeoutMs?: number;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+// ============================================================================
+// Profile Import
+// ============================================================================
+
+/**
+ * Sanitize URLs in an imported profile to prevent SSRF attacks.
+ * Removes any URLs that don't pass SSRF validation.
+ */
+function sanitizeProfileUrls(profile: NostrProfile): NostrProfile {
+  const result = { ...profile };
+  const urlFields = ["picture", "banner", "website"] as const;
+
+  for (const field of urlFields) {
+    const value = result[field];
+    if (value && typeof value === "string") {
+      const validation = validateUrlSafety(value);
+      if (!validation.ok) {
+        // Remove unsafe URL
+        delete result[field];
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Fetch the latest kind:0 profile event for a pubkey from relays.
+ *
+ * - Queries all relays in parallel
+ * - Takes the event with the highest created_at
+ * - Verifies the event signature
+ * - Parses and returns the profile
+ */
+export async function importProfileFromRelays(
+  opts: ProfileImportOptions
+): Promise<ProfileImportResult> {
+  const { pubkey, relays, timeoutMs = DEFAULT_TIMEOUT_MS } = opts;
+
+  if (!pubkey || !/^[0-9a-fA-F]{64}$/.test(pubkey)) {
+    return {
+      ok: false,
+      error: "Invalid pubkey format (must be 64 hex characters)",
+      relaysQueried: [],
+    };
+  }
+
+  if (relays.length === 0) {
+    return {
+      ok: false,
+      error: "No relays configured",
+      relaysQueried: [],
+    };
+  }
+
+  const pool = new SimplePool();
+  const relaysQueried: string[] = [];
+
+  try {
+    // Query all relays for kind:0 events from this pubkey
+    const events: Array<{ event: Event; relay: string }> = [];
+
+    // Create timeout promise
+    const timeoutPromise = new Promise<void>((resolve) => {
+      setTimeout(resolve, timeoutMs);
+    });
+
+    // Create subscription promise
+    const subscriptionPromise = new Promise<void>((resolve) => {
+      let completed = 0;
+
+      for (const relay of relays) {
+        relaysQueried.push(relay);
+
+        const sub = pool.subscribeMany(
+          [relay],
+          [
+            {
+              kinds: [0],
+              authors: [pubkey],
+              limit: 1,
+            },
+          ],
+          {
+            onevent(event) {
+              events.push({ event, relay });
+            },
+            oneose() {
+              completed++;
+              if (completed >= relays.length) {
+                resolve();
+              }
+            },
+            onclose() {
+              completed++;
+              if (completed >= relays.length) {
+                resolve();
+              }
+            },
+          }
+        );
+
+        // Clean up subscription after timeout
+        setTimeout(() => {
+          sub.close();
+        }, timeoutMs);
+      }
+    });
+
+    // Wait for either all relays to respond or timeout
+    await Promise.race([subscriptionPromise, timeoutPromise]);
+
+    // No events found
+    if (events.length === 0) {
+      return {
+        ok: false,
+        error: "No profile found on any relay",
+        relaysQueried,
+      };
+    }
+
+    // Find the event with the highest created_at (newest wins for replaceable events)
+    let bestEvent: { event: Event; relay: string } | null = null;
+    for (const item of events) {
+      if (!bestEvent || item.event.created_at > bestEvent.event.created_at) {
+        bestEvent = item;
+      }
+    }
+
+    if (!bestEvent) {
+      return {
+        ok: false,
+        error: "No valid profile event found",
+        relaysQueried,
+      };
+    }
+
+    // Verify the event signature
+    const isValid = verifyEvent(bestEvent.event);
+    if (!isValid) {
+      return {
+        ok: false,
+        error: "Profile event has invalid signature",
+        relaysQueried,
+        sourceRelay: bestEvent.relay,
+      };
+    }
+
+    // Parse the profile content
+    let content: ProfileContent;
+    try {
+      content = JSON.parse(bestEvent.event.content) as ProfileContent;
+    } catch {
+      return {
+        ok: false,
+        error: "Profile event has invalid JSON content",
+        relaysQueried,
+        sourceRelay: bestEvent.relay,
+      };
+    }
+
+    // Convert to our profile format
+    const profile = contentToProfile(content);
+
+    // Sanitize URLs from imported profile to prevent SSRF when auto-merging
+    const sanitizedProfile = sanitizeProfileUrls(profile);
+
+    return {
+      ok: true,
+      profile: sanitizedProfile,
+      event: {
+        id: bestEvent.event.id,
+        pubkey: bestEvent.event.pubkey,
+        created_at: bestEvent.event.created_at,
+      },
+      relaysQueried,
+      sourceRelay: bestEvent.relay,
+    };
+  } finally {
+    pool.close(relays);
+  }
+}
+
+/**
+ * Merge imported profile with local profile.
+ *
+ * Strategy:
+ * - For each field, prefer local if set, otherwise use imported
+ * - This preserves user customizations while filling in missing data
+ */
+export function mergeProfiles(
+  local: NostrProfile | undefined,
+  imported: NostrProfile | undefined
+): NostrProfile {
+  if (!imported) return local ?? {};
+  if (!local) return imported;
+
+  return {
+    name: local.name ?? imported.name,
+    displayName: local.displayName ?? imported.displayName,
+    about: local.about ?? imported.about,
+    picture: local.picture ?? imported.picture,
+    banner: local.banner ?? imported.banner,
+    website: local.website ?? imported.website,
+    nip05: local.nip05 ?? imported.nip05,
+    lud16: local.lud16 ?? imported.lud16,
+  };
+}

extensions/nostr/src/nostr-profile.fuzz.test.ts

@@ -0,0 +1,479 @@
+import { describe, expect, it } from "vitest";
+import { getPublicKey } from "nostr-tools";
+import {
+  createProfileEvent,
+  profileToContent,
+  validateProfile,
+  sanitizeProfileForDisplay,
+} from "./nostr-profile.js";
+import type { NostrProfile } from "./config-schema.js";
+
+// Test private key
+const TEST_HEX_KEY = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+const TEST_SK = new Uint8Array(
+  TEST_HEX_KEY.match(/.{2}/g)!.map((byte) => parseInt(byte, 16))
+);
+
+// ============================================================================
+// Unicode Attack Vectors
+// ============================================================================
+
+describe("profile unicode attacks", () => {
+  describe("zero-width characters", () => {
+    it("handles zero-width space in name", () => {
+      const profile: NostrProfile = {
+        name: "test\u200Buser", // Zero-width space
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+      // The character should be preserved (not stripped)
+      expect(result.profile?.name).toBe("test\u200Buser");
+    });
+
+    it("handles zero-width joiner in name", () => {
+      const profile: NostrProfile = {
+        name: "test\u200Duser", // Zero-width joiner
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+
+    it("handles zero-width non-joiner in about", () => {
+      const profile: NostrProfile = {
+        about: "test\u200Cabout", // Zero-width non-joiner
+      };
+      const content = profileToContent(profile);
+      expect(content.about).toBe("test\u200Cabout");
+    });
+  });
+
+  describe("RTL override attacks", () => {
+    it("handles RTL override in name", () => {
+      const profile: NostrProfile = {
+        name: "\u202Eevil\u202C", // Right-to-left override + pop direction
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+
+      // UI should escape or handle this
+      const sanitized = sanitizeProfileForDisplay(result.profile!);
+      expect(sanitized.name).toBeDefined();
+    });
+
+    it("handles bidi embedding in about", () => {
+      const profile: NostrProfile = {
+        about: "Normal \u202Breversed\u202C text", // LTR embedding
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe("homoglyph attacks", () => {
+    it("handles Cyrillic homoglyphs", () => {
+      const profile: NostrProfile = {
+        // Cyrillic 'а' (U+0430) looks like Latin 'a'
+        name: "\u0430dmin", // Fake "admin"
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+      // Profile is accepted but apps should be aware
+    });
+
+    it("handles Greek homoglyphs", () => {
+      const profile: NostrProfile = {
+        // Greek 'ο' (U+03BF) looks like Latin 'o'
+        name: "b\u03BFt", // Looks like "bot"
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe("combining characters", () => {
+    it("handles combining diacritics", () => {
+      const profile: NostrProfile = {
+        name: "cafe\u0301", // 'e' + combining acute = 'é'
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+      expect(result.profile?.name).toBe("cafe\u0301");
+    });
+
+    it("handles excessive combining characters (Zalgo text)", () => {
+      const zalgo =
+        "t̷̢̧̨̡̛̛̛͎̩̝̪̲̲̞̠̹̗̩͓̬̱̪̦͙̬̲̤͙̱̫̝̪̱̫̯̬̭̠̖̲̥̖̫̫̤͇̪̣̫̪̖̱̯̣͎̯̲̱̤̪̣̖̲̪̯͓̖̤̫̫̲̱̲̫̲̖̫̪̯̱̱̪̖̯e̶̡̧̨̧̛̛̛̖̪̯̱̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪s̶̨̧̛̛̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯̖̪̯̖̪̱̪̯t";
+      const profile: NostrProfile = {
+        name: zalgo.slice(0, 256), // Truncate to fit limit
+      };
+      const result = validateProfile(profile);
+      // Should be valid but may look weird
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe("CJK and other scripts", () => {
+    it("handles Chinese characters", () => {
+      const profile: NostrProfile = {
+        name: "中文用户",
+        about: "我是一个机器人",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+
+    it("handles Japanese hiragana and katakana", () => {
+      const profile: NostrProfile = {
+        name: "ボット",
+        about: "これはテストです",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+
+    it("handles Korean characters", () => {
+      const profile: NostrProfile = {
+        name: "한국어사용자",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+
+    it("handles Arabic text", () => {
+      const profile: NostrProfile = {
+        name: "مستخدم",
+        about: "مرحبا بالعالم",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+
+    it("handles Hebrew text", () => {
+      const profile: NostrProfile = {
+        name: "משתמש",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+
+    it("handles Thai text", () => {
+      const profile: NostrProfile = {
+        name: "ผู้ใช้",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe("emoji edge cases", () => {
+    it("handles emoji sequences (ZWJ)", () => {
+      const profile: NostrProfile = {
+        name: "👨‍👩‍👧‍👦", // Family emoji using ZWJ
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+
+    it("handles flag emojis", () => {
+      const profile: NostrProfile = {
+        name: "🇺🇸🇯🇵🇬🇧",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+
+    it("handles skin tone modifiers", () => {
+      const profile: NostrProfile = {
+        name: "👋🏻👋🏽👋🏿",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(true);
+    });
+  });
+});
+
+// ============================================================================
+// XSS Attack Vectors
+// ============================================================================
+
+describe("profile XSS attacks", () => {
+  describe("script injection", () => {
+    it("escapes script tags", () => {
+      const profile: NostrProfile = {
+        name: '<script>alert("xss")</script>',
+      };
+      const sanitized = sanitizeProfileForDisplay(profile);
+      expect(sanitized.name).not.toContain("<script>");
+      expect(sanitized.name).toContain("&lt;script&gt;");
+    });
+
+    it("escapes nested script tags", () => {
+      const profile: NostrProfile = {
+        about: '<<script>script>alert("xss")<</script>/script>',
+      };
+      const sanitized = sanitizeProfileForDisplay(profile);
+      expect(sanitized.about).not.toContain("<script>");
+    });
+  });
+
+  describe("event handler injection", () => {
+    it("escapes img onerror", () => {
+      const profile: NostrProfile = {
+        about: '<img src="x" onerror="alert(1)">',
+      };
+      const sanitized = sanitizeProfileForDisplay(profile);
+      expect(sanitized.about).toContain("&lt;img");
+      expect(sanitized.about).not.toContain('onerror="alert');
+    });
+
+    it("escapes svg onload", () => {
+      const profile: NostrProfile = {
+        about: '<svg onload="alert(1)">',
+      };
+      const sanitized = sanitizeProfileForDisplay(profile);
+      expect(sanitized.about).toContain("&lt;svg");
+    });
+
+    it("escapes body onload", () => {
+      const profile: NostrProfile = {
+        about: '<body onload="alert(1)">',
+      };
+      const sanitized = sanitizeProfileForDisplay(profile);
+      expect(sanitized.about).toContain("&lt;body");
+    });
+  });
+
+  describe("URL-based attacks", () => {
+    it("rejects javascript: URL in picture", () => {
+      const profile = {
+        picture: "javascript:alert('xss')",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(false);
+    });
+
+    it("rejects javascript: URL with encoding", () => {
+      const profile = {
+        picture: "java&#115;cript:alert('xss')",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(false);
+    });
+
+    it("rejects data: URL", () => {
+      const profile = {
+        picture: "data:text/html,<script>alert('xss')</script>",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(false);
+    });
+
+    it("rejects vbscript: URL", () => {
+      const profile = {
+        website: "vbscript:msgbox('xss')",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(false);
+    });
+
+    it("rejects file: URL", () => {
+      const profile = {
+        picture: "file:///etc/passwd",
+      };
+      const result = validateProfile(profile);
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe("HTML attribute injection", () => {
+    it("escapes double quotes in fields", () => {
+      const profile: NostrProfile = {
+        name: '" onclick="alert(1)" data-x="',
+      };
+      const sanitized = sanitizeProfileForDisplay(profile);
+      expect(sanitized.name).toContain("&quot;");
+      expect(sanitized.name).not.toContain('onclick="alert');
+    });
+
+    it("escapes single quotes in fields", () => {
+      const profile: NostrProfile = {
+        name: "' onclick='alert(1)' data-x='",
+      };
+      const sanitized = sanitizeProfileForDisplay(profile);
+      expect(sanitized.name).toContain("&#039;");
+    });
+  });
+
+  describe("CSS injection", () => {
+    it("escapes style tags", () => {
+      const profile: NostrProfile = {
+        about: '<style>body{background:url("javascript:alert(1)")}</style>',
+      };
+      const sanitized = sanitizeProfileForDisplay(profile);
+      expect(sanitized.about).toContain("&lt;style&gt;");
+    });
+  });
+});
+
+// ============================================================================
+// Length Boundary Tests
+// ============================================================================
+
+describe("profile length boundaries", () => {
+  describe("name field (max 256)", () => {
+    it("accepts exactly 256 characters", () => {
+      const result = validateProfile({ name: "a".repeat(256) });
+      expect(result.valid).toBe(true);
+    });
+
+    it("rejects 257 characters", () => {
+      const result = validateProfile({ name: "a".repeat(257) });
+      expect(result.valid).toBe(false);
+    });
+
+    it("accepts empty string", () => {
+      const result = validateProfile({ name: "" });
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe("displayName field (max 256)", () => {
+    it("accepts exactly 256 characters", () => {
+      const result = validateProfile({ displayName: "b".repeat(256) });
+      expect(result.valid).toBe(true);
+    });
+
+    it("rejects 257 characters", () => {
+      const result = validateProfile({ displayName: "b".repeat(257) });
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe("about field (max 2000)", () => {
+    it("accepts exactly 2000 characters", () => {
+      const result = validateProfile({ about: "c".repeat(2000) });
+      expect(result.valid).toBe(true);
+    });
+
+    it("rejects 2001 characters", () => {
+      const result = validateProfile({ about: "c".repeat(2001) });
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe("URL fields", () => {
+    it("accepts long valid HTTPS URLs", () => {
+      const longPath = "a".repeat(1000);
+      const result = validateProfile({
+        picture: `https://example.com/${longPath}.png`,
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    it("rejects invalid URL format", () => {
+      const result = validateProfile({
+        picture: "not-a-url",
+      });
+      expect(result.valid).toBe(false);
+    });
+
+    it("rejects URL without protocol", () => {
+      const result = validateProfile({
+        picture: "example.com/pic.png",
+      });
+      expect(result.valid).toBe(false);
+    });
+  });
+});
+
+// ============================================================================
+// Type Confusion Tests
+// ============================================================================
+
+describe("profile type confusion", () => {
+  it("rejects number as name", () => {
+    const result = validateProfile({ name: 123 as unknown as string });
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects array as about", () => {
+    const result = validateProfile({ about: ["hello"] as unknown as string });
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects object as picture", () => {
+    const result = validateProfile({ picture: { url: "https://example.com" } as unknown as string });
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects null as name", () => {
+    const result = validateProfile({ name: null as unknown as string });
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects boolean as about", () => {
+    const result = validateProfile({ about: true as unknown as string });
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects function as name", () => {
+    const result = validateProfile({ name: (() => "test") as unknown as string });
+    expect(result.valid).toBe(false);
+  });
+
+  it("handles prototype pollution attempt", () => {
+    const malicious = JSON.parse('{"__proto__": {"polluted": true}}') as unknown;
+    const result = validateProfile(malicious);
+    // Should not pollute Object.prototype
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+  });
+});
+
+// ============================================================================
+// Event Creation Edge Cases
+// ============================================================================
+
+describe("event creation edge cases", () => {
+  it("handles profile with all fields at max length", () => {
+    const profile: NostrProfile = {
+      name: "a".repeat(256),
+      displayName: "b".repeat(256),
+      about: "c".repeat(2000),
+      nip05: "d".repeat(200) + "@example.com",
+      lud16: "e".repeat(200) + "@example.com",
+    };
+
+    const event = createProfileEvent(TEST_SK, profile);
+    expect(event.kind).toBe(0);
+
+    // Content should be parseable JSON
+    expect(() => JSON.parse(event.content)).not.toThrow();
+  });
+
+  it("handles rapid sequential events with monotonic timestamps", () => {
+    const profile: NostrProfile = { name: "rapid" };
+
+    // Create events in quick succession
+    let lastTimestamp = 0;
+    for (let i = 0; i < 100; i++) {
+      const event = createProfileEvent(TEST_SK, profile, lastTimestamp);
+      expect(event.created_at).toBeGreaterThan(lastTimestamp);
+      lastTimestamp = event.created_at;
+    }
+  });
+
+  it("handles JSON special characters in content", () => {
+    const profile: NostrProfile = {
+      name: 'test"user',
+      about: "line1\nline2\ttab\\backslash",
+    };
+
+    const event = createProfileEvent(TEST_SK, profile);
+    const parsed = JSON.parse(event.content) as { name: string; about: string };
+
+    expect(parsed.name).toBe('test"user');
+    expect(parsed.about).toContain("\n");
+    expect(parsed.about).toContain("\t");
+    expect(parsed.about).toContain("\\");
+  });
+});

extensions/nostr/src/nostr-profile.test.ts

@@ -0,0 +1,410 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { verifyEvent, getPublicKey } from "nostr-tools";
+import {
+  createProfileEvent,
+  profileToContent,
+  contentToProfile,
+  validateProfile,
+  sanitizeProfileForDisplay,
+  type ProfileContent,
+} from "./nostr-profile.js";
+import type { NostrProfile } from "./config-schema.js";
+
+// Test private key (DO NOT use in production - this is a known test key)
+const TEST_HEX_KEY = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+const TEST_SK = new Uint8Array(
+  TEST_HEX_KEY.match(/.{2}/g)!.map((byte) => parseInt(byte, 16))
+);
+const TEST_PUBKEY = getPublicKey(TEST_SK);
+
+// ============================================================================
+// Profile Content Conversion Tests
+// ============================================================================
+
+describe("profileToContent", () => {
+  it("converts full profile to NIP-01 content format", () => {
+    const profile: NostrProfile = {
+      name: "testuser",
+      displayName: "Test User",
+      about: "A test user for unit testing",
+      picture: "https://example.com/avatar.png",
+      banner: "https://example.com/banner.png",
+      website: "https://example.com",
+      nip05: "testuser@example.com",
+      lud16: "testuser@walletofsatoshi.com",
+    };
+
+    const content = profileToContent(profile);
+
+    expect(content.name).toBe("testuser");
+    expect(content.display_name).toBe("Test User");
+    expect(content.about).toBe("A test user for unit testing");
+    expect(content.picture).toBe("https://example.com/avatar.png");
+    expect(content.banner).toBe("https://example.com/banner.png");
+    expect(content.website).toBe("https://example.com");
+    expect(content.nip05).toBe("testuser@example.com");
+    expect(content.lud16).toBe("testuser@walletofsatoshi.com");
+  });
+
+  it("omits undefined fields from content", () => {
+    const profile: NostrProfile = {
+      name: "minimaluser",
+    };
+
+    const content = profileToContent(profile);
+
+    expect(content.name).toBe("minimaluser");
+    expect("display_name" in content).toBe(false);
+    expect("about" in content).toBe(false);
+    expect("picture" in content).toBe(false);
+  });
+
+  it("handles empty profile", () => {
+    const profile: NostrProfile = {};
+    const content = profileToContent(profile);
+    expect(Object.keys(content)).toHaveLength(0);
+  });
+});
+
+describe("contentToProfile", () => {
+  it("converts NIP-01 content to profile format", () => {
+    const content: ProfileContent = {
+      name: "testuser",
+      display_name: "Test User",
+      about: "A test user",
+      picture: "https://example.com/avatar.png",
+      nip05: "test@example.com",
+    };
+
+    const profile = contentToProfile(content);
+
+    expect(profile.name).toBe("testuser");
+    expect(profile.displayName).toBe("Test User");
+    expect(profile.about).toBe("A test user");
+    expect(profile.picture).toBe("https://example.com/avatar.png");
+    expect(profile.nip05).toBe("test@example.com");
+  });
+
+  it("handles empty content", () => {
+    const content: ProfileContent = {};
+    const profile = contentToProfile(content);
+    expect(Object.keys(profile).filter((k) => profile[k as keyof NostrProfile] !== undefined)).toHaveLength(0);
+  });
+
+  it("round-trips profile data", () => {
+    const original: NostrProfile = {
+      name: "roundtrip",
+      displayName: "Round Trip Test",
+      about: "Testing round-trip conversion",
+    };
+
+    const content = profileToContent(original);
+    const restored = contentToProfile(content);
+
+    expect(restored.name).toBe(original.name);
+    expect(restored.displayName).toBe(original.displayName);
+    expect(restored.about).toBe(original.about);
+  });
+});
+
+// ============================================================================
+// Event Creation Tests
+// ============================================================================
+
+describe("createProfileEvent", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2024-01-15T12:00:00Z"));
+  });
+
+  it("creates a valid kind:0 event", () => {
+    const profile: NostrProfile = {
+      name: "testbot",
+      about: "A test bot",
+    };
+
+    const event = createProfileEvent(TEST_SK, profile);
+
+    expect(event.kind).toBe(0);
+    expect(event.pubkey).toBe(TEST_PUBKEY);
+    expect(event.tags).toEqual([]);
+    expect(event.id).toMatch(/^[0-9a-f]{64}$/);
+    expect(event.sig).toMatch(/^[0-9a-f]{128}$/);
+  });
+
+  it("includes profile content as JSON in event content", () => {
+    const profile: NostrProfile = {
+      name: "jsontest",
+      displayName: "JSON Test User",
+      about: "Testing JSON serialization",
+    };
+
+    const event = createProfileEvent(TEST_SK, profile);
+    const parsedContent = JSON.parse(event.content) as ProfileContent;
+
+    expect(parsedContent.name).toBe("jsontest");
+    expect(parsedContent.display_name).toBe("JSON Test User");
+    expect(parsedContent.about).toBe("Testing JSON serialization");
+  });
+
+  it("produces a verifiable signature", () => {
+    const profile: NostrProfile = { name: "signaturetest" };
+    const event = createProfileEvent(TEST_SK, profile);
+
+    expect(verifyEvent(event)).toBe(true);
+  });
+
+  it("uses current timestamp when no lastPublishedAt provided", () => {
+    const profile: NostrProfile = { name: "timestamptest" };
+    const event = createProfileEvent(TEST_SK, profile);
+
+    const expectedTimestamp = Math.floor(Date.now() / 1000);
+    expect(event.created_at).toBe(expectedTimestamp);
+  });
+
+  it("ensures monotonic timestamp when lastPublishedAt is in the future", () => {
+    // Current time is 2024-01-15T12:00:00Z = 1705320000
+    const futureTimestamp = 1705320000 + 3600; // 1 hour in the future
+    const profile: NostrProfile = { name: "monotonictest" };
+
+    const event = createProfileEvent(TEST_SK, profile, futureTimestamp);
+
+    expect(event.created_at).toBe(futureTimestamp + 1);
+  });
+
+  it("uses current time when lastPublishedAt is in the past", () => {
+    const pastTimestamp = 1705320000 - 3600; // 1 hour in the past
+    const profile: NostrProfile = { name: "pasttest" };
+
+    const event = createProfileEvent(TEST_SK, profile, pastTimestamp);
+
+    const expectedTimestamp = Math.floor(Date.now() / 1000);
+    expect(event.created_at).toBe(expectedTimestamp);
+  });
+
+  vi.useRealTimers();
+});
+
+// ============================================================================
+// Profile Validation Tests
+// ============================================================================
+
+describe("validateProfile", () => {
+  it("validates a correct profile", () => {
+    const profile = {
+      name: "validuser",
+      about: "A valid user",
+      picture: "https://example.com/pic.png",
+    };
+
+    const result = validateProfile(profile);
+
+    expect(result.valid).toBe(true);
+    expect(result.profile).toBeDefined();
+    expect(result.errors).toBeUndefined();
+  });
+
+  it("rejects profile with invalid URL", () => {
+    const profile = {
+      name: "invalidurl",
+      picture: "http://insecure.example.com/pic.png", // HTTP not HTTPS
+    };
+
+    const result = validateProfile(profile);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toBeDefined();
+    expect(result.errors!.some((e) => e.includes("https://"))).toBe(true);
+  });
+
+  it("rejects profile with javascript: URL", () => {
+    const profile = {
+      name: "xssattempt",
+      picture: "javascript:alert('xss')",
+    };
+
+    const result = validateProfile(profile);
+
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects profile with data: URL", () => {
+    const profile = {
+      name: "dataurl",
+      picture: "data:image/png;base64,abc123",
+    };
+
+    const result = validateProfile(profile);
+
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects name exceeding 256 characters", () => {
+    const profile = {
+      name: "a".repeat(257),
+    };
+
+    const result = validateProfile(profile);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors!.some((e) => e.includes("256"))).toBe(true);
+  });
+
+  it("rejects about exceeding 2000 characters", () => {
+    const profile = {
+      about: "a".repeat(2001),
+    };
+
+    const result = validateProfile(profile);
+
+    expect(result.valid).toBe(false);
+    expect(result.errors!.some((e) => e.includes("2000"))).toBe(true);
+  });
+
+  it("accepts empty profile", () => {
+    const result = validateProfile({});
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects null input", () => {
+    const result = validateProfile(null);
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects non-object input", () => {
+    const result = validateProfile("not an object");
+    expect(result.valid).toBe(false);
+  });
+});
+
+// ============================================================================
+// Sanitization Tests
+// ============================================================================
+
+describe("sanitizeProfileForDisplay", () => {
+  it("escapes HTML in name field", () => {
+    const profile: NostrProfile = {
+      name: "<script>alert('xss')</script>",
+    };
+
+    const sanitized = sanitizeProfileForDisplay(profile);
+
+    expect(sanitized.name).toBe("&lt;script&gt;alert(&#039;xss&#039;)&lt;/script&gt;");
+  });
+
+  it("escapes HTML in about field", () => {
+    const profile: NostrProfile = {
+      about: 'Check out <img src="x" onerror="alert(1)">',
+    };
+
+    const sanitized = sanitizeProfileForDisplay(profile);
+
+    expect(sanitized.about).toBe(
+      'Check out &lt;img src=&quot;x&quot; onerror=&quot;alert(1)&quot;&gt;'
+    );
+  });
+
+  it("preserves URLs without modification", () => {
+    const profile: NostrProfile = {
+      picture: "https://example.com/pic.png",
+      website: "https://example.com",
+    };
+
+    const sanitized = sanitizeProfileForDisplay(profile);
+
+    expect(sanitized.picture).toBe("https://example.com/pic.png");
+    expect(sanitized.website).toBe("https://example.com");
+  });
+
+  it("handles undefined fields", () => {
+    const profile: NostrProfile = {
+      name: "test",
+    };
+
+    const sanitized = sanitizeProfileForDisplay(profile);
+
+    expect(sanitized.name).toBe("test");
+    expect(sanitized.about).toBeUndefined();
+    expect(sanitized.picture).toBeUndefined();
+  });
+
+  it("escapes ampersands", () => {
+    const profile: NostrProfile = {
+      name: "Tom & Jerry",
+    };
+
+    const sanitized = sanitizeProfileForDisplay(profile);
+
+    expect(sanitized.name).toBe("Tom &amp; Jerry");
+  });
+
+  it("escapes quotes", () => {
+    const profile: NostrProfile = {
+      about: 'Say "hello" to everyone',
+    };
+
+    const sanitized = sanitizeProfileForDisplay(profile);
+
+    expect(sanitized.about).toBe("Say &quot;hello&quot; to everyone");
+  });
+});
+
+// ============================================================================
+// Edge Cases
+// ============================================================================
+
+describe("edge cases", () => {
+  it("handles emoji in profile fields", () => {
+    const profile: NostrProfile = {
+      name: "🤖 Bot",
+      about: "I am a 🤖 robot! 🎉",
+    };
+
+    const content = profileToContent(profile);
+    expect(content.name).toBe("🤖 Bot");
+    expect(content.about).toBe("I am a 🤖 robot! 🎉");
+
+    const event = createProfileEvent(TEST_SK, profile);
+    const parsed = JSON.parse(event.content) as ProfileContent;
+    expect(parsed.name).toBe("🤖 Bot");
+  });
+
+  it("handles unicode in profile fields", () => {
+    const profile: NostrProfile = {
+      name: "日本語ユーザー",
+      about: "Привет мир! 你好世界!",
+    };
+
+    const content = profileToContent(profile);
+    expect(content.name).toBe("日本語ユーザー");
+
+    const event = createProfileEvent(TEST_SK, profile);
+    expect(verifyEvent(event)).toBe(true);
+  });
+
+  it("handles newlines in about field", () => {
+    const profile: NostrProfile = {
+      about: "Line 1\nLine 2\nLine 3",
+    };
+
+    const content = profileToContent(profile);
+    expect(content.about).toBe("Line 1\nLine 2\nLine 3");
+
+    const event = createProfileEvent(TEST_SK, profile);
+    const parsed = JSON.parse(event.content) as ProfileContent;
+    expect(parsed.about).toBe("Line 1\nLine 2\nLine 3");
+  });
+
+  it("handles maximum length fields", () => {
+    const profile: NostrProfile = {
+      name: "a".repeat(256),
+      about: "b".repeat(2000),
+    };
+
+    const result = validateProfile(profile);
+    expect(result.valid).toBe(true);
+
+    const event = createProfileEvent(TEST_SK, profile);
+    expect(verifyEvent(event)).toBe(true);
+  });
+});

extensions/nostr/src/nostr-profile.ts

@@ -0,0 +1,242 @@
+/**
+ * Nostr Profile Management (NIP-01 kind:0)
+ *
+ * Profile events are "replaceable" - the latest created_at wins.
+ * This module handles profile event creation and publishing.
+ */
+
+import { finalizeEvent, SimplePool, type Event } from "nostr-tools";
+import { type NostrProfile, NostrProfileSchema } from "./config-schema.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Result of a profile publish attempt */
+export interface ProfilePublishResult {
+  /** Event ID of the published profile */
+  eventId: string;
+  /** Relays that successfully received the event */
+  successes: string[];
+  /** Relays that failed with their error messages */
+  failures: Array<{ relay: string; error: string }>;
+  /** Unix timestamp when the event was created */
+  createdAt: number;
+}
+
+/** NIP-01 profile content (JSON inside kind:0 event) */
+export interface ProfileContent {
+  name?: string;
+  display_name?: string;
+  about?: string;
+  picture?: string;
+  banner?: string;
+  website?: string;
+  nip05?: string;
+  lud16?: string;
+}
+
+// ============================================================================
+// Profile Content Conversion
+// ============================================================================
+
+/**
+ * Convert our config profile schema to NIP-01 content format.
+ * Strips undefined fields and validates URLs.
+ */
+export function profileToContent(profile: NostrProfile): ProfileContent {
+  const validated = NostrProfileSchema.parse(profile);
+
+  const content: ProfileContent = {};
+
+  if (validated.name !== undefined) content.name = validated.name;
+  if (validated.displayName !== undefined) content.display_name = validated.displayName;
+  if (validated.about !== undefined) content.about = validated.about;
+  if (validated.picture !== undefined) content.picture = validated.picture;
+  if (validated.banner !== undefined) content.banner = validated.banner;
+  if (validated.website !== undefined) content.website = validated.website;
+  if (validated.nip05 !== undefined) content.nip05 = validated.nip05;
+  if (validated.lud16 !== undefined) content.lud16 = validated.lud16;
+
+  return content;
+}
+
+/**
+ * Convert NIP-01 content format back to our config profile schema.
+ * Useful for importing existing profiles from relays.
+ */
+export function contentToProfile(content: ProfileContent): NostrProfile {
+  const profile: NostrProfile = {};
+
+  if (content.name !== undefined) profile.name = content.name;
+  if (content.display_name !== undefined) profile.displayName = content.display_name;
+  if (content.about !== undefined) profile.about = content.about;
+  if (content.picture !== undefined) profile.picture = content.picture;
+  if (content.banner !== undefined) profile.banner = content.banner;
+  if (content.website !== undefined) profile.website = content.website;
+  if (content.nip05 !== undefined) profile.nip05 = content.nip05;
+  if (content.lud16 !== undefined) profile.lud16 = content.lud16;
+
+  return profile;
+}
+
+// ============================================================================
+// Event Creation
+// ============================================================================
+
+/**
+ * Create a signed kind:0 profile event.
+ *
+ * @param sk - Private key as Uint8Array (32 bytes)
+ * @param profile - Profile data to include
+ * @param lastPublishedAt - Previous profile timestamp (for monotonic guarantee)
+ * @returns Signed Nostr event
+ */
+export function createProfileEvent(
+  sk: Uint8Array,
+  profile: NostrProfile,
+  lastPublishedAt?: number
+): Event {
+  const content = profileToContent(profile);
+  const contentJson = JSON.stringify(content);
+
+  // Ensure monotonic timestamp (new event > previous)
+  const now = Math.floor(Date.now() / 1000);
+  const createdAt = lastPublishedAt !== undefined ? Math.max(now, lastPublishedAt + 1) : now;
+
+  const event = finalizeEvent(
+    {
+      kind: 0,
+      content: contentJson,
+      tags: [],
+      created_at: createdAt,
+    },
+    sk
+  );
+
+  return event;
+}
+
+// ============================================================================
+// Profile Publishing
+// ============================================================================
+
+/** Per-relay publish timeout (ms) */
+const RELAY_PUBLISH_TIMEOUT_MS = 5000;
+
+/**
+ * Publish a profile event to multiple relays.
+ *
+ * Best-effort: publishes to all relays in parallel, reports per-relay results.
+ * Does NOT retry automatically - caller should handle retries if needed.
+ *
+ * @param pool - SimplePool instance for relay connections
+ * @param relays - Array of relay WebSocket URLs
+ * @param event - Signed profile event (kind:0)
+ * @returns Publish results with successes and failures
+ */
+export async function publishProfileEvent(
+  pool: SimplePool,
+  relays: string[],
+  event: Event
+): Promise<ProfilePublishResult> {
+  const successes: string[] = [];
+  const failures: Array<{ relay: string; error: string }> = [];
+
+  // Publish to each relay in parallel with timeout
+  const publishPromises = relays.map(async (relay) => {
+    try {
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new Error("timeout")), RELAY_PUBLISH_TIMEOUT_MS);
+      });
+
+      await Promise.race([pool.publish([relay], event), timeoutPromise]);
+
+      successes.push(relay);
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      failures.push({ relay, error: errorMessage });
+    }
+  });
+
+  await Promise.all(publishPromises);
+
+  return {
+    eventId: event.id,
+    successes,
+    failures,
+    createdAt: event.created_at,
+  };
+}
+
+/**
+ * Create and publish a profile event in one call.
+ *
+ * @param pool - SimplePool instance
+ * @param sk - Private key as Uint8Array
+ * @param relays - Array of relay URLs
+ * @param profile - Profile data
+ * @param lastPublishedAt - Previous timestamp for monotonic ordering
+ * @returns Publish results
+ */
+export async function publishProfile(
+  pool: SimplePool,
+  sk: Uint8Array,
+  relays: string[],
+  profile: NostrProfile,
+  lastPublishedAt?: number
+): Promise<ProfilePublishResult> {
+  const event = createProfileEvent(sk, profile, lastPublishedAt);
+  return publishProfileEvent(pool, relays, event);
+}
+
+// ============================================================================
+// Profile Validation Helpers
+// ============================================================================
+
+/**
+ * Validate a profile without throwing (returns result object).
+ */
+export function validateProfile(profile: unknown): {
+  valid: boolean;
+  profile?: NostrProfile;
+  errors?: string[];
+} {
+  const result = NostrProfileSchema.safeParse(profile);
+
+  if (result.success) {
+    return { valid: true, profile: result.data };
+  }
+
+  return {
+    valid: false,
+    errors: result.error.issues.map((e) => `${e.path.join(".")}: ${e.message}`),
+  };
+}
+
+/**
+ * Sanitize profile text fields to prevent XSS when displaying in UI.
+ * Escapes HTML special characters.
+ */
+export function sanitizeProfileForDisplay(profile: NostrProfile): NostrProfile {
+  const escapeHtml = (str: string | undefined): string | undefined => {
+    if (str === undefined) return undefined;
+    return str
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#039;");
+  };
+
+  return {
+    name: escapeHtml(profile.name),
+    displayName: escapeHtml(profile.displayName),
+    about: escapeHtml(profile.about),
+    picture: profile.picture, // URLs already validated by schema
+    banner: profile.banner,
+    website: profile.website,
+    nip05: escapeHtml(profile.nip05),
+    lud16: escapeHtml(profile.lud16),
+  };
+}

extensions/nostr/src/nostr-state-store.test.ts

@@ -0,0 +1,128 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+import type { PluginRuntime } from "clawdbot/plugin-sdk";
+
+import {
+  readNostrBusState,
+  writeNostrBusState,
+  computeSinceTimestamp,
+} from "./nostr-state-store.js";
+import { setNostrRuntime } from "./runtime.js";
+
+async function withTempStateDir<T>(fn: (dir: string) => Promise<T>) {
+  const previous = process.env.CLAWDBOT_STATE_DIR;
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-nostr-"));
+  process.env.CLAWDBOT_STATE_DIR = dir;
+  setNostrRuntime({
+    state: {
+      resolveStateDir: (env, homedir) => {
+        const override = env.CLAWDBOT_STATE_DIR?.trim();
+        if (override) return override;
+        return path.join(homedir(), ".clawdbot");
+      },
+    },
+  } as PluginRuntime);
+  try {
+    return await fn(dir);
+  } finally {
+    if (previous === undefined) delete process.env.CLAWDBOT_STATE_DIR;
+    else process.env.CLAWDBOT_STATE_DIR = previous;
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+describe("nostr bus state store", () => {
+  it("persists and reloads state across restarts", async () => {
+    await withTempStateDir(async () => {
+      // Fresh start - no state
+      expect(await readNostrBusState({ accountId: "test-bot" })).toBeNull();
+
+      // Write state
+      await writeNostrBusState({
+        accountId: "test-bot",
+        lastProcessedAt: 1700000000,
+        gatewayStartedAt: 1700000100,
+      });
+
+      // Read it back
+      const state = await readNostrBusState({ accountId: "test-bot" });
+      expect(state).toEqual({
+        version: 2,
+        lastProcessedAt: 1700000000,
+        gatewayStartedAt: 1700000100,
+        recentEventIds: [],
+      });
+    });
+  });
+
+  it("isolates state by accountId", async () => {
+    await withTempStateDir(async () => {
+      await writeNostrBusState({
+        accountId: "bot-a",
+        lastProcessedAt: 1000,
+        gatewayStartedAt: 1000,
+      });
+      await writeNostrBusState({
+        accountId: "bot-b",
+        lastProcessedAt: 2000,
+        gatewayStartedAt: 2000,
+      });
+
+      const stateA = await readNostrBusState({ accountId: "bot-a" });
+      const stateB = await readNostrBusState({ accountId: "bot-b" });
+
+      expect(stateA?.lastProcessedAt).toBe(1000);
+      expect(stateB?.lastProcessedAt).toBe(2000);
+    });
+  });
+});
+
+describe("computeSinceTimestamp", () => {
+  it("returns now for null state (fresh start)", () => {
+    const now = 1700000000;
+    expect(computeSinceTimestamp(null, now)).toBe(now);
+  });
+
+  it("uses lastProcessedAt when available", () => {
+    const state = {
+      version: 2,
+      lastProcessedAt: 1699999000,
+      gatewayStartedAt: null,
+      recentEventIds: [],
+    };
+    expect(computeSinceTimestamp(state, 1700000000)).toBe(1699999000);
+  });
+
+  it("uses gatewayStartedAt when lastProcessedAt is null", () => {
+    const state = {
+      version: 2,
+      lastProcessedAt: null,
+      gatewayStartedAt: 1699998000,
+      recentEventIds: [],
+    };
+    expect(computeSinceTimestamp(state, 1700000000)).toBe(1699998000);
+  });
+
+  it("uses the max of both timestamps", () => {
+    const state = {
+      version: 2,
+      lastProcessedAt: 1699999000,
+      gatewayStartedAt: 1699998000,
+      recentEventIds: [],
+    };
+    expect(computeSinceTimestamp(state, 1700000000)).toBe(1699999000);
+  });
+
+  it("falls back to now if both are null", () => {
+    const state = {
+      version: 2,
+      lastProcessedAt: null,
+      gatewayStartedAt: null,
+      recentEventIds: [],
+    };
+    expect(computeSinceTimestamp(state, 1700000000)).toBe(1700000000);
+  });
+});

extensions/nostr/src/nostr-state-store.ts

@@ -0,0 +1,226 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { getNostrRuntime } from "./runtime.js";
+
+const STORE_VERSION = 2;
+const PROFILE_STATE_VERSION = 1;
+
+type NostrBusStateV1 = {
+  version: 1;
+  /** Unix timestamp (seconds) of the last processed event */
+  lastProcessedAt: number | null;
+  /** Gateway startup timestamp (seconds) - events before this are old */
+  gatewayStartedAt: number | null;
+};
+
+type NostrBusState = {
+  version: 2;
+  /** Unix timestamp (seconds) of the last processed event */
+  lastProcessedAt: number | null;
+  /** Gateway startup timestamp (seconds) - events before this are old */
+  gatewayStartedAt: number | null;
+  /** Recent processed event IDs for overlap dedupe across restarts */
+  recentEventIds: string[];
+};
+
+/** Profile publish state (separate from bus state) */
+export type NostrProfileState = {
+  version: 1;
+  /** Unix timestamp (seconds) of last successful profile publish */
+  lastPublishedAt: number | null;
+  /** Event ID of the last published profile */
+  lastPublishedEventId: string | null;
+  /** Per-relay publish results from last attempt */
+  lastPublishResults: Record<string, "ok" | "failed" | "timeout"> | null;
+};
+
+function normalizeAccountId(accountId?: string): string {
+  const trimmed = accountId?.trim();
+  if (!trimmed) return "default";
+  return trimmed.replace(/[^a-z0-9._-]+/gi, "_");
+}
+
+function resolveNostrStatePath(
+  accountId?: string,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const stateDir = getNostrRuntime().state.resolveStateDir(env, os.homedir);
+  const normalized = normalizeAccountId(accountId);
+  return path.join(stateDir, "nostr", `bus-state-${normalized}.json`);
+}
+
+function resolveNostrProfileStatePath(
+  accountId?: string,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const stateDir = getNostrRuntime().state.resolveStateDir(env, os.homedir);
+  const normalized = normalizeAccountId(accountId);
+  return path.join(stateDir, "nostr", `profile-state-${normalized}.json`);
+}
+
+function safeParseState(raw: string): NostrBusState | null {
+  try {
+    const parsed = JSON.parse(raw) as Partial<NostrBusState> & Partial<NostrBusStateV1>;
+
+    if (parsed?.version === 2) {
+      return {
+        version: 2,
+        lastProcessedAt: typeof parsed.lastProcessedAt === "number" ? parsed.lastProcessedAt : null,
+        gatewayStartedAt: typeof parsed.gatewayStartedAt === "number" ? parsed.gatewayStartedAt : null,
+        recentEventIds: Array.isArray(parsed.recentEventIds)
+          ? parsed.recentEventIds.filter((x): x is string => typeof x === "string")
+          : [],
+      };
+    }
+
+    // Back-compat: v1 state files
+    if (parsed?.version === 1) {
+      return {
+        version: 2,
+        lastProcessedAt: typeof parsed.lastProcessedAt === "number" ? parsed.lastProcessedAt : null,
+        gatewayStartedAt: typeof parsed.gatewayStartedAt === "number" ? parsed.gatewayStartedAt : null,
+        recentEventIds: [],
+      };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function readNostrBusState(params: {
+  accountId?: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<NostrBusState | null> {
+  const filePath = resolveNostrStatePath(params.accountId, params.env);
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    return safeParseState(raw);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") return null;
+    return null;
+  }
+}
+
+export async function writeNostrBusState(params: {
+  accountId?: string;
+  lastProcessedAt: number;
+  gatewayStartedAt: number;
+  recentEventIds?: string[];
+  env?: NodeJS.ProcessEnv;
+}): Promise<void> {
+  const filePath = resolveNostrStatePath(params.accountId, params.env);
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(
+    dir,
+    `${path.basename(filePath)}.${crypto.randomUUID()}.tmp`
+  );
+  const payload: NostrBusState = {
+    version: STORE_VERSION,
+    lastProcessedAt: params.lastProcessedAt,
+    gatewayStartedAt: params.gatewayStartedAt,
+    recentEventIds: (params.recentEventIds ?? []).filter((x): x is string => typeof x === "string"),
+  };
+  await fs.writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf-8",
+  });
+  await fs.chmod(tmp, 0o600);
+  await fs.rename(tmp, filePath);
+}
+
+/**
+ * Determine the `since` timestamp for subscription.
+ * Returns the later of: lastProcessedAt or gatewayStartedAt (both from disk),
+ * falling back to `now` for fresh starts.
+ */
+export function computeSinceTimestamp(
+  state: NostrBusState | null,
+  nowSec: number = Math.floor(Date.now() / 1000)
+): number {
+  if (!state) return nowSec;
+
+  // Use the most recent timestamp we have
+  const candidates = [
+    state.lastProcessedAt,
+    state.gatewayStartedAt,
+  ].filter((t): t is number => t !== null && t > 0);
+
+  if (candidates.length === 0) return nowSec;
+  return Math.max(...candidates);
+}
+
+// ============================================================================
+// Profile State Management
+// ============================================================================
+
+function safeParseProfileState(raw: string): NostrProfileState | null {
+  try {
+    const parsed = JSON.parse(raw) as Partial<NostrProfileState>;
+
+    if (parsed?.version === 1) {
+      return {
+        version: 1,
+        lastPublishedAt:
+          typeof parsed.lastPublishedAt === "number" ? parsed.lastPublishedAt : null,
+        lastPublishedEventId:
+          typeof parsed.lastPublishedEventId === "string" ? parsed.lastPublishedEventId : null,
+        lastPublishResults:
+          parsed.lastPublishResults && typeof parsed.lastPublishResults === "object"
+            ? (parsed.lastPublishResults as Record<string, "ok" | "failed" | "timeout">)
+            : null,
+      };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function readNostrProfileState(params: {
+  accountId?: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<NostrProfileState | null> {
+  const filePath = resolveNostrProfileStatePath(params.accountId, params.env);
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    return safeParseProfileState(raw);
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ENOENT") return null;
+    return null;
+  }
+}
+
+export async function writeNostrProfileState(params: {
+  accountId?: string;
+  lastPublishedAt: number;
+  lastPublishedEventId: string;
+  lastPublishResults: Record<string, "ok" | "failed" | "timeout">;
+  env?: NodeJS.ProcessEnv;
+}): Promise<void> {
+  const filePath = resolveNostrProfileStatePath(params.accountId, params.env);
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(
+    dir,
+    `${path.basename(filePath)}.${crypto.randomUUID()}.tmp`
+  );
+  const payload: NostrProfileState = {
+    version: PROFILE_STATE_VERSION,
+    lastPublishedAt: params.lastPublishedAt,
+    lastPublishedEventId: params.lastPublishedEventId,
+    lastPublishResults: params.lastPublishResults,
+  };
+  await fs.writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf-8",
+  });
+  await fs.chmod(tmp, 0o600);
+  await fs.rename(tmp, filePath);
+}

extensions/nostr/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "clawdbot/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setNostrRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getNostrRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Nostr runtime not initialized");
+  }
+  return runtime;
+}

extensions/nostr/src/seen-tracker.ts

@@ -0,0 +1,271 @@
+/**
+ * LRU-based seen event tracker with TTL support.
+ * Prevents unbounded memory growth under high load or abuse.
+ */
+
+export interface SeenTrackerOptions {
+  /** Maximum number of entries to track (default: 100,000) */
+  maxEntries?: number;
+  /** TTL in milliseconds (default: 1 hour) */
+  ttlMs?: number;
+  /** Prune interval in milliseconds (default: 10 minutes) */
+  pruneIntervalMs?: number;
+}
+
+export interface SeenTracker {
+  /** Check if an ID has been seen (also marks it as seen if not) */
+  has: (id: string) => boolean;
+  /** Mark an ID as seen */
+  add: (id: string) => void;
+  /** Check if ID exists without marking */
+  peek: (id: string) => boolean;
+  /** Delete an ID */
+  delete: (id: string) => void;
+  /** Clear all entries */
+  clear: () => void;
+  /** Get current size */
+  size: () => number;
+  /** Stop the pruning timer */
+  stop: () => void;
+  /** Pre-seed with IDs (useful for restart recovery) */
+  seed: (ids: string[]) => void;
+}
+
+interface Entry {
+  seenAt: number;
+  // For LRU: track order via doubly-linked list
+  prev: string | null;
+  next: string | null;
+}
+
+/**
+ * Create a new seen tracker with LRU eviction and TTL expiration.
+ */
+export function createSeenTracker(options?: SeenTrackerOptions): SeenTracker {
+  const maxEntries = options?.maxEntries ?? 100_000;
+  const ttlMs = options?.ttlMs ?? 60 * 60 * 1000; // 1 hour
+  const pruneIntervalMs = options?.pruneIntervalMs ?? 10 * 60 * 1000; // 10 minutes
+
+  // Main storage
+  const entries = new Map<string, Entry>();
+
+  // LRU tracking: head = most recent, tail = least recent
+  let head: string | null = null;
+  let tail: string | null = null;
+
+  // Move an entry to the front (most recently used)
+  function moveToFront(id: string): void {
+    const entry = entries.get(id);
+    if (!entry) return;
+
+    // Already at front
+    if (head === id) return;
+
+    // Remove from current position
+    if (entry.prev) {
+      const prevEntry = entries.get(entry.prev);
+      if (prevEntry) prevEntry.next = entry.next;
+    }
+    if (entry.next) {
+      const nextEntry = entries.get(entry.next);
+      if (nextEntry) nextEntry.prev = entry.prev;
+    }
+
+    // Update tail if this was the tail
+    if (tail === id) {
+      tail = entry.prev;
+    }
+
+    // Move to front
+    entry.prev = null;
+    entry.next = head;
+    if (head) {
+      const headEntry = entries.get(head);
+      if (headEntry) headEntry.prev = id;
+    }
+    head = id;
+
+    // If no tail, this is also the tail
+    if (!tail) tail = id;
+  }
+
+  // Remove an entry from the linked list
+  function removeFromList(id: string): void {
+    const entry = entries.get(id);
+    if (!entry) return;
+
+    if (entry.prev) {
+      const prevEntry = entries.get(entry.prev);
+      if (prevEntry) prevEntry.next = entry.next;
+    } else {
+      head = entry.next;
+    }
+
+    if (entry.next) {
+      const nextEntry = entries.get(entry.next);
+      if (nextEntry) nextEntry.prev = entry.prev;
+    } else {
+      tail = entry.prev;
+    }
+  }
+
+  // Evict the least recently used entry
+  function evictLRU(): void {
+    if (!tail) return;
+    const idToEvict = tail;
+    removeFromList(idToEvict);
+    entries.delete(idToEvict);
+  }
+
+  // Prune expired entries
+  function pruneExpired(): void {
+    const now = Date.now();
+    const toDelete: string[] = [];
+
+    for (const [id, entry] of entries) {
+      if (now - entry.seenAt > ttlMs) {
+        toDelete.push(id);
+      }
+    }
+
+    for (const id of toDelete) {
+      removeFromList(id);
+      entries.delete(id);
+    }
+  }
+
+  // Start pruning timer
+  let pruneTimer: ReturnType<typeof setInterval> | undefined;
+  if (pruneIntervalMs > 0) {
+    pruneTimer = setInterval(pruneExpired, pruneIntervalMs);
+    // Don't keep process alive just for pruning
+    if (pruneTimer.unref) pruneTimer.unref();
+  }
+
+  function add(id: string): void {
+    const now = Date.now();
+
+    // If already exists, update and move to front
+    const existing = entries.get(id);
+    if (existing) {
+      existing.seenAt = now;
+      moveToFront(id);
+      return;
+    }
+
+    // Evict if at capacity
+    while (entries.size >= maxEntries) {
+      evictLRU();
+    }
+
+    // Add new entry at front
+    const newEntry: Entry = {
+      seenAt: now,
+      prev: null,
+      next: head,
+    };
+
+    if (head) {
+      const headEntry = entries.get(head);
+      if (headEntry) headEntry.prev = id;
+    }
+
+    entries.set(id, newEntry);
+    head = id;
+    if (!tail) tail = id;
+  }
+
+  function has(id: string): boolean {
+    const entry = entries.get(id);
+    if (!entry) {
+      add(id);
+      return false;
+    }
+
+    // Check if expired
+    if (Date.now() - entry.seenAt > ttlMs) {
+      removeFromList(id);
+      entries.delete(id);
+      add(id);
+      return false;
+    }
+
+    // Mark as recently used
+    entry.seenAt = Date.now();
+    moveToFront(id);
+    return true;
+  }
+
+  function peek(id: string): boolean {
+    const entry = entries.get(id);
+    if (!entry) return false;
+
+    // Check if expired
+    if (Date.now() - entry.seenAt > ttlMs) {
+      removeFromList(id);
+      entries.delete(id);
+      return false;
+    }
+
+    return true;
+  }
+
+  function deleteEntry(id: string): void {
+    if (entries.has(id)) {
+      removeFromList(id);
+      entries.delete(id);
+    }
+  }
+
+  function clear(): void {
+    entries.clear();
+    head = null;
+    tail = null;
+  }
+
+  function size(): number {
+    return entries.size;
+  }
+
+  function stop(): void {
+    if (pruneTimer) {
+      clearInterval(pruneTimer);
+      pruneTimer = undefined;
+    }
+  }
+
+  function seed(ids: string[]): void {
+    const now = Date.now();
+    // Seed in reverse order so first IDs end up at front
+    for (let i = ids.length - 1; i >= 0; i--) {
+      const id = ids[i];
+      if (!entries.has(id) && entries.size < maxEntries) {
+        const newEntry: Entry = {
+          seenAt: now,
+          prev: null,
+          next: head,
+        };
+
+        if (head) {
+          const headEntry = entries.get(head);
+          if (headEntry) headEntry.prev = id;
+        }
+
+        entries.set(id, newEntry);
+        head = id;
+        if (!tail) tail = id;
+      }
+    }
+  }
+
+  return {
+    has,
+    add,
+    peek,
+    delete: deleteEntry,
+    clear,
+    size,
+    stop,
+    seed,
+  };
+}

extensions/nostr/src/types.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it } from "vitest";
+import {
+  listNostrAccountIds,
+  resolveDefaultNostrAccountId,
+  resolveNostrAccount,
+} from "./types.js";
+
+const TEST_PRIVATE_KEY = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+
+describe("listNostrAccountIds", () => {
+  it("returns empty array when not configured", () => {
+    const cfg = { channels: {} };
+    expect(listNostrAccountIds(cfg)).toEqual([]);
+  });
+
+  it("returns empty array when nostr section exists but no privateKey", () => {
+    const cfg = { channels: { nostr: { enabled: true } } };
+    expect(listNostrAccountIds(cfg)).toEqual([]);
+  });
+
+  it("returns default when privateKey is configured", () => {
+    const cfg = {
+      channels: {
+        nostr: { privateKey: TEST_PRIVATE_KEY },
+      },
+    };
+    expect(listNostrAccountIds(cfg)).toEqual(["default"]);
+  });
+});
+
+describe("resolveDefaultNostrAccountId", () => {
+  it("returns default when configured", () => {
+    const cfg = {
+      channels: {
+        nostr: { privateKey: TEST_PRIVATE_KEY },
+      },
+    };
+    expect(resolveDefaultNostrAccountId(cfg)).toBe("default");
+  });
+
+  it("returns default when not configured", () => {
+    const cfg = { channels: {} };
+    expect(resolveDefaultNostrAccountId(cfg)).toBe("default");
+  });
+});
+
+describe("resolveNostrAccount", () => {
+  it("resolves configured account", () => {
+    const cfg = {
+      channels: {
+        nostr: {
+          privateKey: TEST_PRIVATE_KEY,
+          name: "Test Bot",
+          relays: ["wss://test.relay"],
+          dmPolicy: "pairing" as const,
+        },
+      },
+    };
+    const account = resolveNostrAccount({ cfg });
+
+    expect(account.accountId).toBe("default");
+    expect(account.name).toBe("Test Bot");
+    expect(account.enabled).toBe(true);
+    expect(account.configured).toBe(true);
+    expect(account.privateKey).toBe(TEST_PRIVATE_KEY);
+    expect(account.publicKey).toMatch(/^[0-9a-f]{64}$/);
+    expect(account.relays).toEqual(["wss://test.relay"]);
+  });
+
+  it("resolves unconfigured account with defaults", () => {
+    const cfg = { channels: {} };
+    const account = resolveNostrAccount({ cfg });
+
+    expect(account.accountId).toBe("default");
+    expect(account.enabled).toBe(true);
+    expect(account.configured).toBe(false);
+    expect(account.privateKey).toBe("");
+    expect(account.publicKey).toBe("");
+    expect(account.relays).toContain("wss://relay.damus.io");
+    expect(account.relays).toContain("wss://nos.lol");
+  });
+
+  it("handles disabled channel", () => {
+    const cfg = {
+      channels: {
+        nostr: {
+          enabled: false,
+          privateKey: TEST_PRIVATE_KEY,
+        },
+      },
+    };
+    const account = resolveNostrAccount({ cfg });
+
+    expect(account.enabled).toBe(false);
+    expect(account.configured).toBe(true);
+  });
+
+  it("handles custom accountId parameter", () => {
+    const cfg = {
+      channels: {
+        nostr: { privateKey: TEST_PRIVATE_KEY },
+      },
+    };
+    const account = resolveNostrAccount({ cfg, accountId: "custom" });
+
+    expect(account.accountId).toBe("custom");
+  });
+
+  it("handles allowFrom config", () => {
+    const cfg = {
+      channels: {
+        nostr: {
+          privateKey: TEST_PRIVATE_KEY,
+          allowFrom: ["npub1test", "0123456789abcdef"],
+        },
+      },
+    };
+    const account = resolveNostrAccount({ cfg });
+
+    expect(account.config.allowFrom).toEqual(["npub1test", "0123456789abcdef"]);
+  });
+
+  it("handles invalid private key gracefully", () => {
+    const cfg = {
+      channels: {
+        nostr: {
+          privateKey: "invalid-key",
+        },
+      },
+    };
+    const account = resolveNostrAccount({ cfg });
+
+    expect(account.configured).toBe(true); // key is present
+    expect(account.publicKey).toBe(""); // but can't derive pubkey
+  });
+
+  it("preserves all config options", () => {
+    const cfg = {
+      channels: {
+        nostr: {
+          privateKey: TEST_PRIVATE_KEY,
+          name: "Bot",
+          enabled: true,
+          relays: ["wss://relay1", "wss://relay2"],
+          dmPolicy: "allowlist" as const,
+          allowFrom: ["pubkey1", "pubkey2"],
+        },
+      },
+    };
+    const account = resolveNostrAccount({ cfg });
+
+    expect(account.config).toEqual({
+      privateKey: TEST_PRIVATE_KEY,
+      name: "Bot",
+      enabled: true,
+      relays: ["wss://relay1", "wss://relay2"],
+      dmPolicy: "allowlist",
+      allowFrom: ["pubkey1", "pubkey2"],
+    });
+  });
+});

extensions/nostr/src/types.ts

@@ -0,0 +1,99 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { getPublicKeyFromPrivate } from "./nostr-bus.js";
+import { DEFAULT_RELAYS } from "./nostr-bus.js";
+import type { NostrProfile } from "./config-schema.js";
+
+export interface NostrAccountConfig {
+  enabled?: boolean;
+  name?: string;
+  privateKey?: string;
+  relays?: string[];
+  dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
+  allowFrom?: Array<string | number>;
+  profile?: NostrProfile;
+}
+
+export interface ResolvedNostrAccount {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  privateKey: string;
+  publicKey: string;
+  relays: string[];
+  profile?: NostrProfile;
+  config: NostrAccountConfig;
+}
+
+const DEFAULT_ACCOUNT_ID = "default";
+
+/**
+ * List all configured Nostr account IDs
+ */
+export function listNostrAccountIds(cfg: ClawdbotConfig): string[] {
+  const nostrCfg = (cfg.channels as Record<string, unknown> | undefined)?.nostr as
+    | NostrAccountConfig
+    | undefined;
+
+  // If privateKey is configured at top level, we have a default account
+  if (nostrCfg?.privateKey) {
+    return [DEFAULT_ACCOUNT_ID];
+  }
+
+  return [];
+}
+
+/**
+ * Get the default account ID
+ */
+export function resolveDefaultNostrAccountId(cfg: ClawdbotConfig): string {
+  const ids = listNostrAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+/**
+ * Resolve a Nostr account from config
+ */
+export function resolveNostrAccount(opts: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedNostrAccount {
+  const accountId = opts.accountId ?? DEFAULT_ACCOUNT_ID;
+  const nostrCfg = (opts.cfg.channels as Record<string, unknown> | undefined)?.nostr as
+    | NostrAccountConfig
+    | undefined;
+
+  const baseEnabled = nostrCfg?.enabled !== false;
+  const privateKey = nostrCfg?.privateKey ?? "";
+  const configured = Boolean(privateKey.trim());
+
+  let publicKey = "";
+  if (configured) {
+    try {
+      publicKey = getPublicKeyFromPrivate(privateKey);
+    } catch {
+      // Invalid key - leave publicKey empty, configured will indicate issues
+    }
+  }
+
+  return {
+    accountId,
+    name: nostrCfg?.name?.trim() || undefined,
+    enabled: baseEnabled,
+    configured,
+    privateKey,
+    publicKey,
+    relays: nostrCfg?.relays ?? DEFAULT_RELAYS,
+    profile: nostrCfg?.profile,
+    config: {
+      enabled: nostrCfg?.enabled,
+      name: nostrCfg?.name,
+      privateKey: nostrCfg?.privateKey,
+      relays: nostrCfg?.relays,
+      dmPolicy: nostrCfg?.dmPolicy,
+      allowFrom: nostrCfg?.allowFrom,
+      profile: nostrCfg?.profile,
+    },
+  };
+}

extensions/nostr/test/setup.ts

@@ -0,0 +1,5 @@
+// Test setup file for nostr extension
+import { vi } from "vitest";
+
+// Mock console.error to suppress noise in tests
+vi.spyOn(console, "error").mockImplementation(() => {});

package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdbot",
-  "version": "2026.1.17-1",
+  "version": "2026.1.20",
   "description": "WhatsApp gateway CLI (Baileys web) with Pi RPC agent",
   "type": "module",
   "main": "dist/index.js",
@@ -152,8 +152,8 @@
     "@lydell/node-pty": "1.2.0-beta.3",
     "@mariozechner/pi-agent-core": "0.49.2",
     "@mariozechner/pi-ai": "0.49.2",
-    "@mariozechner/pi-coding-agent": "^0.49.2",
-    "@mariozechner/pi-tui": "^0.49.2",
+    "@mariozechner/pi-coding-agent": "0.49.2",
+    "@mariozechner/pi-tui": "0.49.2",
     "@mozilla/readability": "^0.6.0",
     "@sinclair/typebox": "0.34.47",
     "@slack/bolt": "^4.6.0",
@@ -232,6 +232,9 @@
       "@sinclair/typebox": "0.34.47",
       "hono": "4.11.4",
       "tar": "7.5.3"
+    },
+    "patchedDependencies": {
+      "@mariozechner/pi-ai@0.49.2": "patches/@mariozechner__pi-ai@0.49.2.patch"
     }
   },
   "vitest": {