fix(security): load WASM tool description and schema from capabilities.json (#520)

The extract_tool_description and extract_tool_schema stubs in runtime.rs
returned permissive fallbacks ("WASM sandboxed tool" and
additionalProperties:true) for every WASM tool, defeating parameter
validation and preventing the LLM from using tools correctly.

Add optional `description` and `parameters` fields to CapabilitiesFile so
tool authors can declare proper metadata in their sidecar JSON. The
WasmToolLoader now extracts these fields and passes them through to the
tool registry as overrides. Tools without a capabilities.json or without
these fields get a tracing::warn and fall back to the old stubs.

Co-authored-by: Claude Sonnet 4.6 <[email protected]>

.claude/commands/add-sse-event.md

@@ -64,7 +64,7 @@ If the event needs custom UI (cards, badges, etc.), add styles. Follow the exist
 
 Identify where in the backend this event should be triggered. Common locations:
 - `src/agent/agent_loop.rs` - During message processing or tool execution
-- `src/agent/worker.rs` - During job execution
+- `src/worker/job.rs` - During job execution
 - `src/agent/heartbeat.rs` - During periodic execution
 
 Use the existing pattern:

.github/workflows/claude-review.yml

@@ -29,18 +29,36 @@ jobs:
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           allowed_bots: "ironclaw-ci[bot]"
-          claude_args: "--max-turns 50 --model claude-haiku-4-5-20251001 --allowedTools 'Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh issue view:*),Bash(gh issue list:*),Bash(gh search:*),Bash(git blame:*),Bash(git log:*),Bash(git diff:*)'"
+          claude_args: "--max-turns 50 --model claude-haiku-4-5-20251001 --allowedTools 'Read,Glob,Grep,Agent,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh issue view:*),Bash(gh issue list:*),Bash(gh search:*),Bash(git blame:*),Bash(git log:*),Bash(git diff:*)'"
           prompt: |
             Code review this pull request. Follow these steps precisely:
 
-            1. Use a Haiku agent to find relevant CLAUDE.md files: the root CLAUDE.md
-               and any CLAUDE.md files in directories whose files this PR modifies.
+            1. Find relevant CLAUDE.md files: the root CLAUDE.md and any CLAUDE.md files
+               in directories whose files this PR modifies. Use Glob to find them, then Read
+               to load their contents.
 
-            2. Use a Haiku agent to summarize the PR change (use `gh pr diff`).
+            2. Get the PR diff with `gh pr diff` and summarize the change.
 
             3. Launch 4 parallel agents to review the change independently. Each agent should
                read the PR diff with `gh pr diff` and the full source files for changed
-               code, then return a list of issues found:
+               code (using Read), then return a list of issues. Each agent MUST score its
+               own findings inline using the severity and confidence rubric below.
+
+               Severity levels:
+               - CRITICAL: security vulns, panics in prod (.unwrap/.expect), data exfiltration, race conditions
+               - HIGH: logic bugs, missing error handling, breaking API/schema changes
+               - MEDIUM: missing tests, unnecessary complexity, performance issues
+               - LOW: documentation gaps, naming suggestions
+
+               Confidence scoring (0-100):
+               0: False positive, doesn't stand up to scrutiny, or pre-existing issue.
+               25: Might be real, but may be false positive. Stylistic issues not in CLAUDE.md.
+               50: Real issue but nitpick or rare in practice. Not very important.
+               75: Verified real issue, will be hit in practice. Directly impacts functionality
+                   or explicitly mentioned in CLAUDE.md.
+               100: Certain, confirmed, will happen frequently. Evidence directly confirms.
+
+               Each agent returns findings as: [SEVERITY:CONFIDENCE] <brief description>
 
                Agent 1 — Security & Safety
                Check for: command injection, path traversal, SSRF, XSS, auth bypass,
@@ -63,22 +81,9 @@ jobs:
                timeouts, resource leaks (file handles, connections), large allocations
                in hot paths.
 
-            4. For each issue found, launch a parallel Haiku agent to:
-               a. Assign a severity:
-                  - CRITICAL: security vulns, panics in prod (.unwrap/.expect), data exfiltration, race conditions
-                  - HIGH: logic bugs, missing error handling, breaking API/schema changes
-                  - MEDIUM: missing tests, unnecessary complexity, performance issues
-                  - LOW: documentation gaps, naming suggestions
-               b. Score confidence 0-100 (give this rubric verbatim):
-                  0: False positive, doesn't stand up to scrutiny, or pre-existing issue.
-                  25: Might be real, but may be false positive. Stylistic issues not in CLAUDE.md.
-                  50: Real issue but nitpick or rare in practice. Not very important.
-                  75: Verified real issue, will be hit in practice. Directly impacts functionality
-                      or explicitly mentioned in CLAUDE.md.
-                  100: Certain, confirmed, will happen frequently. Evidence directly confirms.
-
-            5. Post a single comment on the PR using `gh pr comment` with this format.
-               If no issues were found, post "No issues found." instead:
+            4. Consolidate all agent findings and post exactly one comment on the PR
+               using `gh pr comment` with this format. If no issues were found,
+               post "No issues found." instead:
 
             ### Code review
 
@@ -93,8 +98,12 @@ jobs:
             You MUST use the full git SHA in links (not HEAD or branch name).
             Provide 1 line of context before and after each linked range.
 
-            Notes:
-            - Use `gh` for all GitHub interactions, not web fetch
+            IMPORTANT rules:
+            - Only YOU (the main process) may call `gh pr comment`. Agents must return
+              their findings to you — they must NOT post comments themselves.
+            - You MUST post exactly one `gh pr comment` before finishing, even if agents
+              fail or return empty results. If review is incomplete, post "No issues found."
+            - Use Read/Glob for file access, `gh` for GitHub interactions, not web fetch
             - Do NOT check build signal or attempt to build/test the code
             - Ignore pre-existing issues not introduced by this PR
             - Ignore issues a linter/compiler would catch (formatting, imports, types)

.github/workflows/release.yml

@@ -144,6 +144,8 @@ jobs:
       - name: Patch manifests with WASM checksums
         if: ${{ needs.plan.outputs.publishing == 'true' }}
         shell: bash
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
         run: |
           CHECKSUMS="target/distrib/checksums.txt"
           if [ ! -f "$CHECKSUMS" ]; then
@@ -154,12 +156,17 @@ jobs:
           while IFS= read -r line; do
             sha256=$(echo "$line" | awk '{print $1}')
             filename=$(echo "$line" | awk '{print $2}')
-            name=$(echo "$filename" | sed 's/-wasm32-wasip2\.tar\.gz$//')
+            # Strip -{version}-wasm32-wasip2.tar.gz to get the extension name.
+            # Use '.*' (greedy) so pre-release suffixes like -alpha.1 are consumed too.
+            name=$(echo "$filename" | sed 's/-[0-9].*-wasm32-wasip2\.tar\.gz$//')
+            url="https://github.com/nearai/ironclaw/releases/download/${RELEASE_TAG}/${filename}"
 
             for manifest in registry/tools/${name}.json registry/channels/${name}.json; do
               if [ -f "$manifest" ]; then
-                jq --arg sha "$sha256" '.artifacts["wasm32-wasip2"].sha256 = $sha' "$manifest" > "${manifest}.tmp" && mv "${manifest}.tmp" "$manifest"
-                echo "Patched $manifest with sha256=$sha256"
+                jq --arg sha "$sha256" --arg url "$url" \
+                  '.artifacts["wasm32-wasip2"].sha256 = $sha | .artifacts["wasm32-wasip2"].url = $url' \
+                  "$manifest" > "${manifest}.tmp" && mv "${manifest}.tmp" "$manifest"
+                echo "Patched $manifest with sha256=$sha256 url=$url"
               fi
             done
           done < "$CHECKSUMS"
@@ -268,21 +275,41 @@ jobs:
           for manifest in registry/tools/*.json registry/channels/*.json; do
             [ -f "$manifest" ] || continue
 
-            name=$(jq -r '.name' "$manifest")
+            # file_stem: JSON filename without extension (e.g. "slack" for slack.json).
+            # Used for the bundle filename and CI manifest lookup, so patching always
+            # finds the right file regardless of whether manifest.name matches the filename.
+            file_stem=$(basename "$manifest" .json)
+            # ext_name: the manifest's .name field (e.g. "slack-tool").
+            # Used for file names *inside* the archive — the installer extracts by manifest.name.
+            ext_name=$(jq -r '.name' "$manifest")
             source_dir=$(jq -r '.source.dir' "$manifest")
             caps_file=$(jq -r '.source.capabilities' "$manifest")
             crate_name=$(jq -r '.source.crate_name' "$manifest")
+            ext_version=$(jq -r '.version // ""' "$manifest")
 
             if [ ! -d "$source_dir" ]; then
-              echo "::warning::Source dir '$source_dir' not found for '$name', skipping"
+              echo "::warning::Source dir '$source_dir' not found for '$file_stem', skipping"
               continue
             fi
 
-            echo "=== Building $name from $source_dir ==="
+            # Skip rebuild if this exact version was already built and checksummed.
+            # Checks that (1) the manifest already has a sha256, and (2) the version
+            # embedded in the existing artifact URL matches the current manifest version.
+            # This ensures stable checksums: only rebuild when the source version changes.
+            existing_sha=$(jq -r '.artifacts["wasm32-wasip2"].sha256 // ""' "$manifest")
+            existing_url=$(jq -r '.artifacts["wasm32-wasip2"].url // ""' "$manifest")
+            url_version=$(echo "$existing_url" | sed -n 's/.*-\([0-9].*\)-wasm32-wasip2\.tar\.gz$/\1/p')
+
+            if [[ -n "$ext_version" && "$url_version" == "$ext_version" && -n "$existing_sha" ]]; then
+              echo "=== Skipping $file_stem v$ext_version — already checksummed at $existing_url ==="
+              continue
+            fi
+
+            echo "=== Building $file_stem ($ext_name) v$ext_version from $source_dir ==="
 
             # Build WASM component
             cargo component build --release --manifest-path "$source_dir/Cargo.toml" || {
-              echo "::warning::Build failed for '$name', skipping"
+              echo "::warning::Build failed for '$file_stem', skipping"
               continue
             }
 
@@ -298,30 +325,36 @@ jobs:
             done
 
             if [ -z "$wasm_path" ]; then
-              echo "::warning::No WASM output found for '$name', skipping"
+              echo "::warning::No WASM output found for '$file_stem', skipping"
               continue
             fi
 
-            # Copy files with standardized names for the archive
-            cp "$wasm_path" "target/wasm-bundles/${name}.wasm"
+            # Archive contents use ext_name (manifest .name) — the installer extracts
+            # files by manifest.name, so these must match even when file_stem differs.
+            cp "$wasm_path" "target/wasm-bundles/${ext_name}.wasm"
 
             caps_path="$source_dir/$caps_file"
             if [ -f "$caps_path" ]; then
-              cp "$caps_path" "target/wasm-bundles/${name}.capabilities.json"
+              cp "$caps_path" "target/wasm-bundles/${ext_name}.capabilities.json"
             else
-              echo "::warning::No capabilities file at '$caps_path' for '$name'"
+              echo "::warning::No capabilities file at '$caps_path' for '$file_stem'"
             fi
 
-            # Create tar.gz bundle
-            bundle="target/wasm-bundles/${name}-wasm32-wasip2.tar.gz"
-            (cd target/wasm-bundles && if [ -f "${name}.capabilities.json" ]; then tar czf "${name}-wasm32-wasip2.tar.gz" "${name}.wasm" "${name}.capabilities.json"; else tar czf "${name}-wasm32-wasip2.tar.gz" "${name}.wasm"; fi)
+            # Bundle filename uses file_stem so CI patching can find the manifest by
+            # filename (e.g. slack-0.1.0-wasm32-wasip2.tar.gz → registry/tools/slack.json).
+            bundle="target/wasm-bundles/${file_stem}-${ext_version}-wasm32-wasip2.tar.gz"
+            (cd target/wasm-bundles && if [ -f "${ext_name}.capabilities.json" ]; then
+              tar czf "${file_stem}-${ext_version}-wasm32-wasip2.tar.gz" "${ext_name}.wasm" "${ext_name}.capabilities.json"
+            else
+              tar czf "${file_stem}-${ext_version}-wasm32-wasip2.tar.gz" "${ext_name}.wasm"
+            fi)
 
             # Compute SHA256
             sha256=$(sha256sum "$bundle" | cut -d' ' -f1)
-            echo "$sha256  ${name}-wasm32-wasip2.tar.gz" >> target/wasm-bundles/checksums.txt
+            echo "$sha256  ${file_stem}-${ext_version}-wasm32-wasip2.tar.gz" >> target/wasm-bundles/checksums.txt
 
             # Clean up intermediate files
-            rm -f "target/wasm-bundles/${name}.wasm" "target/wasm-bundles/${name}.capabilities.json"
+            rm -f "target/wasm-bundles/${ext_name}.wasm" "target/wasm-bundles/${ext_name}.capabilities.json"
 
             echo "  -> $bundle ($sha256)"
           done
@@ -427,8 +460,10 @@ jobs:
         with:
           name: artifacts-wasm-extensions
           path: target/wasm-bundles/
-      - name: Patch manifests with SHA256
+      - name: Patch manifests with SHA256 and version-pinned URL
         shell: bash
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
         run: |
           CHECKSUMS="target/wasm-bundles/checksums.txt"
           if [ ! -f "$CHECKSUMS" ]; then
@@ -439,12 +474,17 @@ jobs:
           while IFS= read -r line; do
             sha256=$(echo "$line" | awk '{print $1}')
             filename=$(echo "$line" | awk '{print $2}')
-            name=$(echo "$filename" | sed 's/-wasm32-wasip2\.tar\.gz$//')
+            # Strip -{version}-wasm32-wasip2.tar.gz to get the extension name.
+            # Use '.*' (greedy) so pre-release suffixes like -alpha.1 are consumed too.
+            name=$(echo "$filename" | sed 's/-[0-9].*-wasm32-wasip2\.tar\.gz$//')
+            url="https://github.com/nearai/ironclaw/releases/download/${RELEASE_TAG}/${filename}"
 
             for manifest in registry/tools/${name}.json registry/channels/${name}.json; do
               if [ -f "$manifest" ]; then
-                jq --arg sha "$sha256" '.artifacts["wasm32-wasip2"].sha256 = $sha' "$manifest" > "${manifest}.tmp" && mv "${manifest}.tmp" "$manifest"
-                echo "Patched $manifest with sha256=$sha256"
+                jq --arg sha "$sha256" --arg url "$url" \
+                  '.artifacts["wasm32-wasip2"].sha256 = $sha | .artifacts["wasm32-wasip2"].url = $url' \
+                  "$manifest" > "${manifest}.tmp" && mv "${manifest}.tmp" "$manifest"
+                echo "Patched $manifest with sha256=$sha256 url=$url"
               fi
             done
           done < "$CHECKSUMS"
@@ -461,8 +501,8 @@ jobs:
             git commit -m "chore: update WASM artifact SHA256 checksums [skip ci]"
             git push origin "$BRANCH"
             gh pr create \
-              --title "chore: update WASM artifact SHA256 checksums" \
-              --body "Auto-generated by release CI. Updates SHA256 checksums in registry manifests to match the released WASM artifacts." \
+              --title "chore: update WASM artifact checksums and version-pinned URLs" \
+              --body "Auto-generated by release CI. Updates SHA256 checksums and version-pinned artifact URLs in registry manifests to match the released WASM artifacts. Only extensions whose version changed since the last release are included." \
               --base main \
               --head "$BRANCH"
           fi

.github/workflows/staging-ci.yml

@@ -406,6 +406,10 @@ jobs:
             echo "passed=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # Only merge PRs targeting main. Chained PRs (targeting another
+      # promotion branch) stay open — when the base PR merges into main,
+      # GitHub auto-retargets the chained PR. Merging chained PRs would
+      # trigger delete_branch_on_merge, auto-closing downstream PRs.
       - name: Merge promotion PR
         id: merge
         if: steps.evaluate.outputs.passed == 'true'
@@ -414,12 +418,15 @@ jobs:
           PR_NUMBER: ${{ needs.create-promotion-pr.outputs.pr_number }}
         run: |
           if [ -n "$PR_NUMBER" ]; then
-            echo "Merging promotion PR #${PR_NUMBER}"
-            # Do NOT use --delete-branch: deleting a promotion branch closes
-            # any chained PRs that use it as their base (verified in ironclaw-ci-test).
-            # Stale promotion branches are cleaned up separately.
-            gh pr merge "$PR_NUMBER" --merge
-            echo "merged=true" >> "$GITHUB_OUTPUT"
+            BASE=$(gh pr view "$PR_NUMBER" --json baseRefName --jq '.baseRefName')
+            if [ "$BASE" = "main" ]; then
+              echo "Merging promotion PR #${PR_NUMBER} (targets main)"
+              gh pr merge "$PR_NUMBER" --merge
+              echo "merged=true" >> "$GITHUB_OUTPUT"
+            else
+              echo "PR #${PR_NUMBER} targets '${BASE}' (not main) — leaving open for chain resolution"
+              echo "merged=false" >> "$GITHUB_OUTPUT"
+            fi
           fi
 
   # ── Update tested tag (always, so next batch covers only new commits) ──
@@ -437,7 +444,7 @@ jobs:
       - uses: actions/checkout@v6
         with:
           ref: staging
-          fetch-depth: 1
+          fetch-depth: 0
 
       - name: Update staging-tested tag
         run: |

.github/workflows/test.yml

@@ -42,8 +42,8 @@ jobs:
   telegram-tests:
     name: Telegram Channel Tests
     if: >
-      github.event_name == 'push' ||
-      (github.event_name == 'pull_request' && github.base_ref != 'staging')
+      github.event_name != 'pull_request' ||
+      github.base_ref != 'staging'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -57,8 +57,8 @@ jobs:
   windows-build:
     name: Windows Build (${{ matrix.name }})
     if: >
-      github.event_name == 'push' ||
-      (github.event_name == 'pull_request' && github.base_ref != 'staging')
+      github.event_name != 'pull_request' ||
+      github.base_ref != 'staging'
     runs-on: windows-latest
     strategy:
       fail-fast: false
@@ -84,8 +84,8 @@ jobs:
   wasm-wit-compat:
     name: WASM WIT Compatibility
     if: >
-      github.event_name == 'push' ||
-      (github.event_name == 'pull_request' && github.base_ref != 'staging')
+      github.event_name != 'pull_request' ||
+      github.base_ref != 'staging'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -107,8 +107,8 @@ jobs:
   docker-build:
     name: Docker Build
     if: >
-      github.event_name == 'push' ||
-      (github.event_name == 'pull_request' && github.base_ref != 'staging')
+      github.event_name != 'pull_request' ||
+      github.base_ref != 'staging'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository

.gitignore

@@ -28,3 +28,4 @@ trace_*.json
 
 # Local Claude Code settings (machine-specific, should not be committed)
 .claude/settings.local.json
+.worktrees/

CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0](https://github.com/nearai/ironclaw/compare/v0.16.1...v0.17.0) - 2026-03-10
+
+### Added
+
+- *(llm)* per-provider unsupported parameter filtering (#749, #728) ([#809](https://github.com/nearai/ironclaw/pull/809))
+- persist user_id in save_job and expose job_id on routine runs ([#709](https://github.com/nearai/ironclaw/pull/709))
+- *(ci)* chained promotion PRs with multi-agent Claude review ([#776](https://github.com/nearai/ironclaw/pull/776))
+- add background sandbox reaper for orphaned Docker containers ([#634](https://github.com/nearai/ironclaw/pull/634))
+- *(wasm)* lazy schema injection on WASM tool errors ([#638](https://github.com/nearai/ironclaw/pull/638))
+- add AWS Bedrock LLM provider via native Converse API ([#713](https://github.com/nearai/ironclaw/pull/713))
+- full image support across all channels ([#725](https://github.com/nearai/ironclaw/pull/725))
+- *(skills)* exclude_keywords veto in skill activation scoring ([#688](https://github.com/nearai/ironclaw/pull/688))
+- *(mcp)* transport abstraction, stdio/UDS transports, and OAuth fixes ([#721](https://github.com/nearai/ironclaw/pull/721))
+- add PID-based gateway lock to prevent multiple instances ([#717](https://github.com/nearai/ironclaw/pull/717))
+- configurable LLM request timeout via LLM_REQUEST_TIMEOUT_SECS ([#615](https://github.com/nearai/ironclaw/pull/615)) ([#630](https://github.com/nearai/ironclaw/pull/630))
+- *(timezone)* add timezone-aware session context ([#671](https://github.com/nearai/ironclaw/pull/671))
+- *(setup)* Anthropic OAuth onboarding with setup-token support ([#384](https://github.com/nearai/ironclaw/pull/384))
+- *(llm)* add Google Gemini, AWS Bedrock, io.net, Mistral, Yandex, and Cloudflare WS AI providers ([#676](https://github.com/nearai/ironclaw/pull/676))
+- unified thread model for web gateway ([#607](https://github.com/nearai/ironclaw/pull/607))
+- WASM channel attachments with LLM pipeline integration ([#596](https://github.com/nearai/ironclaw/pull/596))
+- enable Anthropic prompt caching via automatic cache_control injection ([#660](https://github.com/nearai/ironclaw/pull/660))
+- *(routines)* approval context for autonomous job execution ([#577](https://github.com/nearai/ironclaw/pull/577))
+- *(llm)* declarative provider registry ([#618](https://github.com/nearai/ironclaw/pull/618))
+- *(gateway)* show IronClaw version in status popover [skip-regression-check] ([#636](https://github.com/nearai/ironclaw/pull/636))
+- Wire memory hygiene retention policy into heartbeat loop ([#629](https://github.com/nearai/ironclaw/pull/629))
+
+### Fixed
+
+- *(ci)* run fmt + clippy on staging PRs, skip Windows clippy [skip-regression-check] ([#802](https://github.com/nearai/ironclaw/pull/802))
+- *(ci)* clean up staging pipeline — remove hacks, skip redundant checks [skip-regression-check] ([#794](https://github.com/nearai/ironclaw/pull/794))
+- *(ci)* secrets can't be used in step if conditions [skip-regression-check] ([#787](https://github.com/nearai/ironclaw/pull/787))
+- prevent irreversible context loss when compaction archive write fails ([#754](https://github.com/nearai/ironclaw/pull/754))
+- button styles ([#637](https://github.com/nearai/ironclaw/pull/637))
+- *(mcp)* JSON-RPC spec compliance — flexible id, correct notification format ([#685](https://github.com/nearai/ironclaw/pull/685))
+- preserve tool-call history across thread hydration ([#568](https://github.com/nearai/ironclaw/pull/568)) ([#670](https://github.com/nearai/ironclaw/pull/670))
+- CLI commands ignore runtime DATABASE_BACKEND when both features compiled ([#740](https://github.com/nearai/ironclaw/pull/740))
+- *(web)* prevent fetch error when hostname is an IP address in TEE check ([#672](https://github.com/nearai/ironclaw/pull/672))
+- add timezone conversion support to time tool ([#687](https://github.com/nearai/ironclaw/pull/687))
+- standardize libSQL timestamps as RFC 3339 UTC ([#683](https://github.com/nearai/ironclaw/pull/683))
+- *(docker)* bind postgres to localhost only ([#686](https://github.com/nearai/ironclaw/pull/686))
+- *(repl)* skip /quit on EOF when stdin is not a TTY ([#724](https://github.com/nearai/ironclaw/pull/724))
+- *(web)* prevent Enter key from sending message during IME composition ([#715](https://github.com/nearai/ironclaw/pull/715))
+- *(config)* init_secrets no longer overwrites entire config ([#726](https://github.com/nearai/ironclaw/pull/726))
+- *(cli)* status command ignores config.toml and settings.json ([#354](https://github.com/nearai/ironclaw/pull/354)) ([#734](https://github.com/nearai/ironclaw/pull/734))
+- *(setup)* preserve model name when re-running onboarding with same provider ([#600](https://github.com/nearai/ironclaw/pull/600)) ([#694](https://github.com/nearai/ironclaw/pull/694))
+- *(setup)* initialize secrets crypto for env-var security option ([#666](https://github.com/nearai/ironclaw/pull/666)) ([#706](https://github.com/nearai/ironclaw/pull/706))
+- persist /model selection across restarts ([#707](https://github.com/nearai/ironclaw/pull/707))
+- *(routines)* resolve message tool channel/target from per-job metadata ([#708](https://github.com/nearai/ironclaw/pull/708))
+- sanitize HTML error bodies from MCP servers to prevent web UI white screen ([#263](https://github.com/nearai/ironclaw/pull/263)) ([#656](https://github.com/nearai/ironclaw/pull/656))
+- prevent Instant duration overflow on Windows ([#657](https://github.com/nearai/ironclaw/pull/657)) ([#664](https://github.com/nearai/ironclaw/pull/664))
+- enable libsql remote + tls features for Turso cloud sync ([#587](https://github.com/nearai/ironclaw/pull/587))
+- *(tests)* replace hardcoded /tmp paths with tempdir + add 300 unit tests ([#659](https://github.com/nearai/ironclaw/pull/659))
+- *(llm)* nudge LLM when it expresses tool intent without calling tools ([#653](https://github.com/nearai/ironclaw/pull/653))
+- *(llm)* report zero cost for OpenRouter free-tier models ([#463](https://github.com/nearai/ironclaw/pull/463)) ([#613](https://github.com/nearai/ironclaw/pull/613))
+- reliable network tests and improved tool error messages ([#626](https://github.com/nearai/ironclaw/pull/626))
+- *(wasm)* use per-engine cache dirs on Windows to avoid file lock error ([#624](https://github.com/nearai/ironclaw/pull/624))
+- *(libsql)* support flexible embedding dimensions ([#534](https://github.com/nearai/ironclaw/pull/534))
+
+### Other
+
+- Restructure CLAUDE.md into modular rules + add pr-shepherd command ([#750](https://github.com/nearai/ironclaw/pull/750))
+- make src/llm/ self-contained for crate extraction ([#767](https://github.com/nearai/ironclaw/pull/767))
+- add simplified Chinese (zh-CN) README translation ([#488](https://github.com/nearai/ironclaw/pull/488))
+- *(job)* cover job tool validation and state transitions ([#681](https://github.com/nearai/ironclaw/pull/681))
+- *(agent)* wire TestRig job tools through the scheduler ([#716](https://github.com/nearai/ironclaw/pull/716))
+- Fix single-message mode to exit after one turn when background channels are enabled ([#719](https://github.com/nearai/ironclaw/pull/719))
+- remove dead code ([#648](https://github.com/nearai/ironclaw/pull/648)) ([#703](https://github.com/nearai/ironclaw/pull/703))
+- add reviewer-feedback guardrails (CLAUDE.md, pre-commit hook, skill) ([#665](https://github.com/nearai/ironclaw/pull/665))
+- update WASM artifact SHA256 checksums [skip ci] ([#631](https://github.com/nearai/ironclaw/pull/631))
+- add explanatory comments to coverage workflow ([#610](https://github.com/nearai/ironclaw/pull/610))
+- build system prompt once per turn, skip tools on force-text ([#583](https://github.com/nearai/ironclaw/pull/583))
+- add comprehensive subdirectory CLAUDE.md files and update root ([#589](https://github.com/nearai/ironclaw/pull/589))
+- Improve test infrastructure: StubChannel, gateway helpers, security tests, search edge cases ([#623](https://github.com/nearai/ironclaw/pull/623))
+- *(workspace)* regression test for document_path in search results ([#509](https://github.com/nearai/ironclaw/pull/509))
+
 ### Added
 
 - AWS Bedrock LLM provider via native Converse API with IAM and SSO auth support (feature-gated: `--features bedrock`)

CLAUDE.md

@@ -99,7 +99,8 @@ src/
 │   └── job_manager.rs  # Container lifecycle (create, stop, cleanup)
 │
 ├── worker/             # Runs inside Docker containers
-│   ├── runtime.rs      # Worker execution loop (tool calls, LLM)
+│   ├── container.rs    # Container worker runtime (ContainerDelegate + shared agentic loop)
+│   ├── job.rs          # Background job worker (JobDelegate + shared agentic loop)
 │   ├── claude_bridge.rs # Claude Code bridge (spawns claude CLI)
 │   └── proxy_llm.rs    # LlmProvider that proxies through orchestrator
 │

CONTRIBUTING.md

@@ -47,7 +47,7 @@ All PRs follow a risk-based review process:
 |-------|-------|-------------|
 | **A** | Docs, tests, chore, dependency bumps | 1 approval + CI green |
 | **B** | Features, refactors, new tools/channels | 1 approval + CI green + test evidence |
-| **C** | Security (`src/safety/`, `src/secrets/`, `src/sandbox/`, `src/orchestrator/`), runtime (`src/agent/`, `src/worker/`), database schema, CI workflows | 2 approvals + rollback plan documented |
+| **C** | Security (`src/safety/`, `src/secrets/`), runtime (`src/agent/`, `src/worker/`), database schema, CI workflows | 2 approvals + rollback plan documented |
 
 Select the appropriate track in the PR template based on what your changes touch.
 
@@ -57,4 +57,4 @@ IronClaw uses dual-backend persistence (PostgreSQL + libSQL). All new persistenc
 
 ## Adding Dependencies
 
-Run `cargo deny check` before adding new dependencies to verify license compatibility and check for known advisories (requires `deny.toml`; see the `cargo-deny` CI job).
+Run `cargo deny check` before adding new dependencies to verify license compatibility and check for known advisories.

COVERAGE_PLAN.md

@@ -63,12 +63,12 @@ These files account for the vast majority of the coverage gap:
 | `src/main.rs` | 740 | 522 | 29.4% | 485 |
 | `src/channels/web/handlers/jobs.rs` | 513 | 456 | 11.1% | 430 |
 | `src/tools/builder/core.rs` | 524 | 456 | 13.0% | 429 |
-| `src/agent/worker.rs` | 1,078 | 467 | 56.7% | 413 |
+| `src/worker/job.rs` | 1,078 | 467 | 56.7% | 413 |
 | `src/channels/web/handlers/chat.rs` | 564 | 417 | 26.1% | 388 |
 | `src/tools/wasm/wrapper.rs` | 1,005 | 436 | 56.6% | 385 |
 | `src/channels/signal.rs` | 1,814 | 472 | 74.0% | 381 |
 | `src/tools/mcp/auth.rs` | 472 | 378 | 19.9% | 354 |
-| `src/worker/runtime.rs` | 350 | 330 | 5.7% | 312 |
+| `src/worker/container.rs` | 350 | 330 | 5.7% | 312 |
 | `src/tools/builtin/job.rs` | 1,014 | 359 | 64.6% | 308 |
 | `src/cli/mcp.rs` | 322 | 319 | 0.9% | 302 |
 | `src/cli/oauth_defaults.rs` | 730 | 335 | 54.1% | 298 |
@@ -346,7 +346,7 @@ Test slash commands through the agent loop.
 
 ### Trace: Worker Multi-Turn Execution
 
-**Covers:** `agent/worker.rs` (+413 lines), `agent/agent_loop.rs` (+207 lines)
+**Covers:** `worker/job.rs` (+413 lines), `agent/agent_loop.rs` (+207 lines)
 
 Test multi-turn tool calling, error recovery, and completion flows.
 
@@ -769,7 +769,7 @@ HTTP proxy for container network access.
 - `test_proxy_connect_tunnel` -- HTTPS CONNECT method handling
 - `test_proxy_logging` -- request/response logging
 
-### `src/worker/runtime.rs` -- 5.7% -> 95% (+312 lines)
+### `src/worker/container.rs` -- 5.7% -> 95% (+312 lines)
 
 Worker execution loop (runs inside containers).
 

Cargo.lock

@@ -3350,7 +3350,7 @@ dependencies = [
 
 [[package]]
 name = "ironclaw"
-version = "0.16.1"
+version = "0.17.0"
 dependencies = [
  "aes-gcm",
  "aho-corasick",
@@ -3386,6 +3386,7 @@ dependencies = [
  "hyper-util",
  "iana-time-zone",
  "insta",
+ "json5",
  "libsql",
  "lru",
  "mime_guess",
@@ -3521,6 +3522,17 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "json5"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96b0db21af676c1ce64250b5f40f3ce2cf27e4e47cb91ed91eb6fe9350b430c1"
+dependencies = [
+ "pest",
+ "pest_derive",
+ "serde",
+]
+
 [[package]]
 name = "kuchikikiki"
 version = "0.9.2"
@@ -4397,6 +4409,49 @@ version = "2.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
+[[package]]
+name = "pest"
+version = "2.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e0848c601009d37dfa3430c4666e147e49cdcf1b92ecd3e63657d8a5f19da662"
+dependencies = [
+ "memchr",
+ "ucd-trie",
+]
+
+[[package]]
+name = "pest_derive"
+version = "2.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11f486f1ea21e6c10ed15d5a7c77165d0ee443402f0780849d1768e7d9d6fe77"
+dependencies = [
+ "pest",
+ "pest_generator",
+]
+
+[[package]]
+name = "pest_generator"
+version = "2.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8040c4647b13b210a963c1ed407c1ff4fdfa01c31d6d2a098218702e6664f94f"
+dependencies = [
+ "pest",
+ "pest_meta",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "pest_meta"
+version = "2.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "89815c69d36021a140146f26659a81d6c2afa33d216d736dd4be5381a7362220"
+dependencies = [
+ "pest",
+ "sha2",
+]
+
 [[package]]
 name = "pgvector"
 version = "0.4.1"
@@ -7045,6 +7100,12 @@ version = "1.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
 
+[[package]]
+name = "ucd-trie"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2896d95c02a80c6d6a5d6e953d479f5ddf2dfdb6a244441010e373ac0fb88971"
+
 [[package]]
 name = "uds_windows"
 version = "1.1.0"

Cargo.toml

@@ -14,11 +14,12 @@ exclude = [
     "tools-src/google-slides",
     "tools-src/slack",
     "tools-src/telegram",
+    "fuzz",
 ]
 
 [package]
 name = "ironclaw"
-version = "0.16.1"
+version = "0.17.0"
 edition = "2024"
 rust-version = "1.92"
 description = "Secure personal AI assistant that protects your data and expands its capabilities on the fly"
@@ -174,6 +175,9 @@ readabilityrs = { version = "0.1.2", optional = true }
 ed25519-dalek = { version = "2.2.0", features = ["std"] }
 hex = "0.4.3"
 
+# OpenClaw import (feature gated)
+json5 = { version = "0.4", optional = true }
+
 # macOS keychain
 [target.'cfg(target_os = "macos")'.dependencies]
 security-framework = "3"
@@ -209,15 +213,20 @@ libsql = ["dep:libsql"]
 integration = []
 html-to-markdown = ["dep:html-to-markdown-rs", "dep:readabilityrs"]
 bedrock = ["dep:aws-config", "dep:aws-sdk-bedrockruntime", "dep:aws-smithy-types"]
+import = ["dep:json5", "libsql"]
 
 [[test]]
 name = "html_to_markdown"
 required-features = ["html-to-markdown"]
 
+[profile.release]
+strip = true          # Remove debug symbols from release binaries
+
 # The profile that 'cargo dist' will build with
 [profile.dist]
 inherits = "release"
-lto = "thin"
+lto = "fat"           # Full cross-crate LTO (slow build, better codegen)
+codegen-units = 1     # Single codegen unit for maximum optimization
 
 # Config for 'dist'
 [workspace.metadata.dist]

FEATURE_PARITY.md

@@ -46,14 +46,14 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 | Bonjour/mDNS discovery | ✅ | ❌ | |
 | Tailscale integration | ✅ | ❌ | |
 | Health check endpoints | ✅ | ✅ | /api/health + /api/gateway/status + /healthz + /readyz, with channel-backed readiness probes |
-| `doctor` diagnostics | ✅ | ❌ | |
+| `doctor` diagnostics | ✅ | 🚧 | 16 checks: settings, LLM, DB, embeddings, routines, gateway, MCP, skills, secrets, service, Docker daemon, tunnel binaries |
 | Agent event broadcast | ✅ | 🚧 | SSE broadcast manager exists (SseManager) but tool/job-state events not fully wired |
 | Channel health monitor | ✅ | ❌ | Auto-restart with configurable interval |
 | Presence system | ✅ | ❌ | Beacons on connect, system presence for agents |
 | Trusted-proxy auth mode | ✅ | ❌ | Header-based auth for reverse proxies |
 | APNs push pipeline | ✅ | ❌ | Wake disconnected iOS nodes via push |
 | Oversized payload guard | ✅ | 🚧 | HTTP webhook has 64KB body limit + Content-Length check; no chat.history cap |
-| Pre-prompt context diagnostics | ✅ | ❌ | Context size logging before prompt |
+| Pre-prompt context diagnostics | ✅ | 🚧 | Token breakdown logged before LLM call (conversational dispatcher path); other LLM entry points not yet covered |
 
 ### Owner: _Unassigned_
 
@@ -175,7 +175,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 | `message send` | ✅ | ❌ | P2 | Send to channels |
 | `browser` | ✅ | ❌ | P3 | Browser automation |
 | `sandbox` | ✅ | ✅ | - | WASM sandbox |
-| `doctor` | ✅ | ❌ | P2 | Diagnostics |
+| `doctor` | ✅ | 🚧 | P2 | 16 subsystem checks |
 | `logs` | ✅ | ❌ | P3 | Query logs |
 | `update` | ✅ | ❌ | P3 | Self-update |
 | `completion` | ✅ | ✅ | - | Shell completion |
@@ -440,6 +440,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 | `before_agent_start` hook | ✅ | ❌ | P2 | Model/provider override |
 | `before_message_write` hook | ✅ | ❌ | P2 | Pre-write interception |
 | `onMessage` hook | ✅ | ✅ | - | Routines with event trigger |
+| Structured system-event routines | ✅ | ✅ | P2 | `system_event` trigger + `event_emit` tool for event-driven automation |
 | `onSessionStart` hook | ✅ | ✅ | P2 | |
 | `onSessionEnd` hook | ✅ | ✅ | P2 | |
 | `transcribeAudio` hook | ✅ | ❌ | P3 | |
@@ -558,7 +559,7 @@ This document tracks feature parity between IronClaw (Rust implementation) and O
 - ❌ Media handling (images, PDFs)
 - ✅ Ollama/local model support (via rig::providers::ollama)
 - ❌ Configuration hot-reload
-- ❌ Webhook trigger endpoint in web gateway
+- ✅ Tool-driven webhook ingress (`/webhook/tools/{tool}` -> host-verified + tool-normalized `system_event` routines)
 - ❌ Channel health monitor with auto-restart
 - ❌ Partial output preservation on abort
 

README.zh-CN.md

@@ -229,7 +229,7 @@ WASM ──► 白名单  ──► 泄露扫描 ──► 凭据  ──► 执
 │                         │          │                           │
 │              ┌──────────▼────┐  ┌──▼───────────────┐           │
 │              │    调度器      │  │   定时任务引擎    │           │
-│              │  (并行任务)    │  │(cron, 事件, wh)  │           │
+│              │  (并行任务)    │  │(cron, 事件, Webhook)│          │
 │              └──────┬────────┘  └────────┬─────────┘           │
 │                     │                    │                     │
 │       ┌─────────────┼────────────────────┘                     │

channels-src/telegram/telegram.capabilities.json

@@ -20,7 +20,8 @@
         "optional": false
       }
     ],
-    "setup_url": "https://t.me/BotFather"
+    "setup_url": "https://t.me/BotFather",
+    "validation_endpoint": "https://api.telegram.org/bot{telegram_bot_token}/getMe"
   },
   "capabilities": {
     "http": {

fuzz/Cargo.toml

@@ -0,0 +1,40 @@
+[package]
+name = "ironclaw-fuzz"
+version = "0.0.0"
+publish = false
+edition = "2021"
+
+[package.metadata]
+cargo-fuzz = true
+
+[dependencies]
+libfuzzer-sys = "0.4"
+serde_json = "1"
+
+[dependencies.ironclaw]
+path = ".."
+
+[[bin]]
+name = "fuzz_safety_sanitizer"
+path = "fuzz_targets/fuzz_safety_sanitizer.rs"
+doc = false
+
+[[bin]]
+name = "fuzz_safety_validator"
+path = "fuzz_targets/fuzz_safety_validator.rs"
+doc = false
+
+[[bin]]
+name = "fuzz_leak_detector"
+path = "fuzz_targets/fuzz_leak_detector.rs"
+doc = false
+
+[[bin]]
+name = "fuzz_tool_params"
+path = "fuzz_targets/fuzz_tool_params.rs"
+doc = false
+
+[[bin]]
+name = "fuzz_config_env"
+path = "fuzz_targets/fuzz_config_env.rs"
+doc = false

fuzz/README.md

@@ -0,0 +1,43 @@
+# IronClaw Fuzz Targets
+
+Fuzz testing for security-critical input parsing paths using [cargo-fuzz](https://github.com/rust-fuzz/cargo-fuzz) (libFuzzer).
+
+## Targets
+
+| Target | What it exercises |
+|--------|-------------------|
+| `fuzz_safety_sanitizer` | Prompt injection pattern detection (Aho-Corasick + regex) |
+| `fuzz_safety_validator` | Input validation (length, encoding, forbidden patterns) |
+| `fuzz_leak_detector` | Secret leak detection (API keys, tokens, credentials) |
+| `fuzz_tool_params` | Tool parameter and schema JSON validation |
+| `fuzz_config_env` | SafetyLayer end-to-end (sanitize, validate, policy check) |
+
+## Setup
+
+```bash
+cargo install cargo-fuzz
+rustup install nightly
+```
+
+## Running
+
+```bash
+# Run a specific target (runs until stopped or crash found)
+cargo +nightly fuzz run fuzz_safety_sanitizer
+
+# Run with a time limit (5 minutes)
+cargo +nightly fuzz run fuzz_leak_detector -- -max_total_time=300
+
+# Run all targets for 60 seconds each
+for target in fuzz_safety_sanitizer fuzz_safety_validator fuzz_leak_detector fuzz_tool_params fuzz_config_env; do
+    echo "==> $target"
+    cargo +nightly fuzz run "$target" -- -max_total_time=60
+done
+```
+
+## Adding New Targets
+
+1. Create `fuzz/fuzz_targets/fuzz_<name>.rs` following the existing pattern
+2. Add a `[[bin]]` entry in `fuzz/Cargo.toml`
+3. Create `fuzz/corpus/fuzz_<name>/` for seed inputs
+4. Exercise real IronClaw code paths, not just generic serde

fuzz/fuzz_targets/fuzz_config_env.rs

@@ -0,0 +1,55 @@
+#![no_main]
+use libfuzzer_sys::fuzz_target;
+
+use ironclaw::safety::{LeakDetector, Sanitizer, Validator};
+
+fuzz_target!(|data: &[u8]| {
+    if let Ok(input) = std::str::from_utf8(data) {
+        // Exercise Sanitizer: detect and neutralize prompt injection attempts.
+        let sanitizer = Sanitizer::new();
+        let sanitized = sanitizer.sanitize(input);
+        // The sanitized content must never be empty when input is non-empty,
+        // because sanitization wraps/escapes rather than deleting.
+        if !input.is_empty() {
+            assert!(
+                !sanitized.content.is_empty(),
+                "sanitize() produced empty content for non-empty input"
+            );
+        }
+        // If no modification occurred, content must equal input.
+        if !sanitized.was_modified {
+            assert_eq!(sanitized.content, input);
+        }
+
+        // Exercise Validator: input validation (length, encoding, patterns).
+        let validator = Validator::new();
+        let result = validator.validate(input);
+        // ValidationResult must always be well-formed: if valid, no errors.
+        if result.is_valid {
+            assert!(
+                result.errors.is_empty(),
+                "valid result should have no errors"
+            );
+        }
+
+        // Exercise LeakDetector: secret detection (API keys, tokens, etc.).
+        let detector = LeakDetector::new();
+        let scan = detector.scan(input);
+        // scan_and_clean must not panic and must return valid UTF-8.
+        let cleaned = detector.scan_and_clean(input);
+        if let Ok(ref clean_str) = cleaned {
+            // Cleaned output must never be longer than original + redaction markers.
+            // At minimum it should be valid UTF-8 (guaranteed by String type).
+            let _ = clean_str.len();
+        }
+        // If scan found no matches, scan_and_clean should return the input unchanged.
+        if scan.matches.is_empty() {
+            if let Ok(ref clean_str) = cleaned {
+                assert_eq!(
+                    clean_str, input,
+                    "scan_and_clean changed content despite no matches"
+                );
+            }
+        }
+    }
+});

fuzz/fuzz_targets/fuzz_leak_detector.rs

@@ -0,0 +1,23 @@
+#![no_main]
+use libfuzzer_sys::fuzz_target;
+use ironclaw::safety::LeakDetector;
+
+fuzz_target!(|data: &[u8]| {
+    if let Ok(s) = std::str::from_utf8(data) {
+        let detector = LeakDetector::new();
+
+        // Exercise scan path
+        let result = detector.scan(s);
+        // Invariant: if should_block, there must be matches
+        if result.should_block {
+            assert!(!result.matches.is_empty());
+        }
+        // Invariant: match locations must be valid
+        for m in &result.matches {
+            assert!(m.location.end <= s.len());
+        }
+
+        // Exercise scan_and_clean path
+        let _ = detector.scan_and_clean(s);
+    }
+});

fuzz/fuzz_targets/fuzz_safety_sanitizer.rs

@@ -0,0 +1,23 @@
+#![no_main]
+use libfuzzer_sys::fuzz_target;
+use ironclaw::safety::Sanitizer;
+
+fuzz_target!(|data: &[u8]| {
+    if let Ok(s) = std::str::from_utf8(data) {
+        let sanitizer = Sanitizer::new();
+
+        // Exercise the main sanitization path
+        let result = sanitizer.sanitize(s);
+        // Verify invariant: warnings should have valid ranges
+        for w in &result.warnings {
+            assert!(w.location.end <= s.len());
+        }
+        // Verify invariant: critical severity triggers modification
+        let has_critical = result.warnings.iter().any(|w| {
+            w.severity == ironclaw::safety::Severity::Critical
+        });
+        if has_critical {
+            assert!(result.was_modified);
+        }
+    }
+});

fuzz/fuzz_targets/fuzz_safety_validator.rs

@@ -0,0 +1,21 @@
+#![no_main]
+use libfuzzer_sys::fuzz_target;
+use ironclaw::safety::Validator;
+
+fuzz_target!(|data: &[u8]| {
+    if let Ok(s) = std::str::from_utf8(data) {
+        let validator = Validator::new();
+
+        // Exercise input validation
+        let result = validator.validate(s);
+        // Invariant: empty input is always invalid
+        if s.is_empty() {
+            assert!(!result.is_valid);
+        }
+
+        // Exercise tool parameter validation with arbitrary JSON
+        if let Ok(value) = serde_json::from_str::<serde_json::Value>(s) {
+            let _ = validator.validate_tool_params(&value);
+        }
+    }
+});

fuzz/fuzz_targets/fuzz_tool_params.rs

@@ -0,0 +1,22 @@
+#![no_main]
+use libfuzzer_sys::fuzz_target;
+use ironclaw::safety::Validator;
+use ironclaw::tools::validate_tool_schema;
+
+fuzz_target!(|data: &[u8]| {
+    if let Ok(s) = std::str::from_utf8(data) {
+        // Try parsing as JSON and validating as tool parameters
+        if let Ok(value) = serde_json::from_str::<serde_json::Value>(s) {
+            // Exercise Validator::validate_tool_params with arbitrary JSON
+            let validator = Validator::new();
+            let result = validator.validate_tool_params(&value);
+            // Invariant: result should always be well-formed
+            if !result.is_valid {
+                assert!(!result.errors.is_empty());
+            }
+
+            // Exercise validate_tool_schema with arbitrary JSON as a schema
+            let _ = validate_tool_schema(&value, "fuzz");
+        }
+    }
+});

migrations/V12__job_token_budget.sql

@@ -0,0 +1,7 @@
+-- Add token budget tracking columns to agent_jobs.
+--
+-- Tracks max_tokens (configured limit per job) and total_tokens_used (running total)
+-- to enforce job-level token budgets and prevent budget bypass via user-supplied metadata.
+
+ALTER TABLE agent_jobs ADD COLUMN max_tokens BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE agent_jobs ADD COLUMN total_tokens_used BIGINT NOT NULL DEFAULT 0;

providers.json

@@ -9,8 +9,9 @@
     "api_key_required": true,
     "base_url_env": "OPENAI_BASE_URL",
     "model_env": "OPENAI_MODEL",
-    "default_model": "gpt-4o",
+    "default_model": "gpt-5-mini",
     "description": "OpenAI GPT models (direct API)",
+    "unsupported_params": ["temperature"],
     "setup": {
       "kind": "api_key",
       "secret_name": "llm_openai_api_key",
@@ -86,6 +87,7 @@
     "model_env": "TINFOIL_MODEL",
     "default_model": "kimi-k2-5",
     "description": "Tinfoil private inference (hardware-attested TEE)",
+    "unsupported_params": ["temperature"],
     "setup": {
       "kind": "api_key",
       "secret_name": "llm_tinfoil_api_key",

registry/channels/discord.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/discord-wasm32-wasip2.tar.gz",
-      "sha256": "030707431717bca3411a48f311c6ab5f92a45c747de26cafe4f6e3e23a8b3b2d"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/channels/slack.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/slack-wasm32-wasip2.tar.gz",
-      "sha256": "6ed36077b67ac70a041f06f760f93ba79b33269885413c3c3f2c8c87ee60807e"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/channels/telegram.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/telegram-wasm32-wasip2.tar.gz",
-      "sha256": "98c86895a9c4b0a1e19fe8a47f1ccbfe7e972e112b05e584bc897130dc32283a"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/channels/whatsapp.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/whatsapp-wasm32-wasip2.tar.gz",
-      "sha256": "bd35cad18d87292ea8d2f52db9b514ed9f814a414de910f59073d475c26c4c14"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/github.json

@@ -20,7 +20,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/github-wasm32-wasip2.tar.gz",
-      "sha256": "6fcd32719a4ff15641a4b50fff8984686550f0c491dce60518f4126857d0c544"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/gmail.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/gmail-wasm32-wasip2.tar.gz",
-      "sha256": "023da7000b17568bf0e64b2e5013c8a042b2f323c85f1632339231c73d500e39"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/google-calendar.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/google-calendar-wasm32-wasip2.tar.gz",
-      "sha256": "fc42277b65881d6e9bcc5403dc54c7f5b3ddeaaaf04617fce2c5da05d76325f0"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/google-docs.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/google-docs-wasm32-wasip2.tar.gz",
-      "sha256": "385c04abd1e6b8011ccc330e1f4bd7ce58577e488959b51594aa04eb26cbe7cc"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/google-drive.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/google-drive-wasm32-wasip2.tar.gz",
-      "sha256": "1b107d575a5d52cc8c76d9a681802190f4373fb485f7f54f445533f097fa37c0"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/google-sheets.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/google-sheets-wasm32-wasip2.tar.gz",
-      "sha256": "c4f6b1e8c5126ac2c8a4b98e4283a3afa32223d2488fc3c3a609758c0c9beb90"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/google-slides.json

@@ -18,7 +18,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/google-slides-wasm32-wasip2.tar.gz",
-      "sha256": "7110b8565340c888e51f99e9c013bf4de8f8a7f7b33bace00eb8fc47831ff20b"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/slack.json

@@ -18,7 +18,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/slack-tool-wasm32-wasip2.tar.gz",
-      "sha256": "6ed36077b67ac70a041f06f760f93ba79b33269885413c3c3f2c8c87ee60807e"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/telegram.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/telegram-mtproto-wasm32-wasip2.tar.gz",
-      "sha256": "98c86895a9c4b0a1e19fe8a47f1ccbfe7e972e112b05e584bc897130dc32283a"
+      "sha256": null
     }
   },
   "auth_summary": {

registry/tools/web-search.json

@@ -19,7 +19,7 @@
   "artifacts": {
     "wasm32-wasip2": {
       "url": "https://github.com/nearai/ironclaw/releases/latest/download/web-search-wasm32-wasip2.tar.gz",
-      "sha256": "66cb2b9b00652385e9f30f17c74902b9222c17c53e9d3bd1ef42f5cab705bcf6"
+      "sha256": null
     }
   },
   "auth_summary": {

skills/ironclaw-workflow-orchestrator/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: ironclaw-workflow-orchestrator
+description: "Install and operate a full GitHub issue-to-merge workflow in IronClaw using event-driven and cron routines. Use when setting up or tuning autonomous project orchestration: issue intake, planning, maintainer feedback handling, branch/PR execution, CI/comment follow-up, batched staging review every 8 hours, and memory updates from merge outcomes."
+---
+
+# IronClaw Workflow Orchestrator
+
+## Overview
+Use this skill to install and maintain a complete project workflow as routines, not core code changes. It maps GitHub webhook events plus scheduled checks into plan/update/implement/review/merge loops with explicit staging-batch analysis.
+
+## Workflow
+1. Gather workflow parameters.
+2. Verify runtime prerequisites.
+3. Install or update routine set from templates.
+4. Run a dry test with `event_emit`.
+5. Monitor outcomes and tune prompts/filters.
+
+## Parameters
+Collect these values before creating routines:
+- `repository`: `owner/repo` (required)
+- `maintainers`: GitHub handles allowed to trigger implement/replan actions
+- `staging_branch`: default `staging`
+- `main_branch`: default `main`
+- `batch_interval_hours`: default `8`
+- `implementation_label`: default `autonomous-impl`
+
+## Prerequisites
+Before installing routines, verify:
+- Routines system enabled.
+- GitHub tool authenticated (for issue/PR/comment/status operations).
+- Events are emitted via `event_emit` tool calls (a future HTTP webhook ingestion endpoint is planned but not yet available).
+
+## Install Procedure
+1. Open [`workflow-routines.md`](references/workflow-routines.md).
+2. For each template block:
+- replace placeholders (`{{repository}}`, `{{maintainers}}`, branch names)
+- call `routine_create`
+3. If a routine already exists:
+- use `routine_update` instead of creating duplicates
+- keep names stable so long-lived metrics/history stay intact
+4. Confirm install with `routine_list` and `routine_history`.
+
+## Routine Set
+Install these routines:
+- `wf-issue-plan`: on `issue.opened` or `issue.reopened`, generate implementation plan comment/checklist.
+- `wf-maintainer-comment-gate`: on maintainer comments, decide update-plan vs start implementation.
+- `wf-pr-monitor-loop`: on PR open/sync/review-comment/review, address feedback and refresh branch.
+- `wf-ci-fix-loop`: on CI status/check failures, apply fixes and push updates.
+- `wf-staging-batch-review`: every 8h, review ready PRs, merge into staging, run deep batch correctness analysis, fix findings, then merge staging -> main.
+- `wf-learning-memory`: on merged PRs, extract mistakes/lessons and write to shared memory.
+
+## Event Filters
+Prefer top-level filters for stability:
+- `repository` (string)
+- `sender` (string)
+- `issue_number` / `pr_number`
+- `ci_status`, `ci_conclusion`
+- `review_state`, `comment_author`
+
+Use narrow filters to avoid accidental triggers across repos.
+
+## Operating Rules
+- All implementation work must occur on non-main branches.
+- PR loop must resolve both human and AI review comments.
+- On conflicts with `origin/main`, refresh branch before continuing.
+- Staging-batch routine is the only path for bulk correctness verification before mainline merge.
+- Memory update routine runs only after successful merge.
+
+## Validation
+After install, run:
+1. `event_emit` with a synthetic `issue.opened` payload for the target repo.
+2. Confirm at least one routine fired.
+3. Check corresponding `routine_history` entries.
+4. Confirm no unrelated routines fired.
+
+## When To Update Templates
+Update this skill when:
+- GitHub event names/payload fields change.
+- Team review policy changes (e.g., staging cadence, maintainer gates).
+- New CI policy requires different failure routing.

skills/ironclaw-workflow-orchestrator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "IronClaw Workflow Orchestrator"
+  short_description: "Install and run event-driven GitHub workflow routines"
+  default_prompt: "Set up the full issue-to-merge workflow using routines and event triggers."

skills/ironclaw-workflow-orchestrator/references/workflow-routines.md

@@ -0,0 +1,128 @@
+# Workflow Routine Templates
+
+Replace `{{...}}` placeholders before use.
+
+## 1) Issue -> Plan
+
+```json
+{
+  "name": "wf-issue-plan",
+  "description": "Create implementation plan when a new issue arrives",
+  "trigger_type": "system_event",
+  "event_source": "github",
+  "event_type": "issue.opened",
+  "event_filters": {
+    "repository": "{{repository}}"
+  },
+  "action_type": "full_job",
+  "prompt": "For issue #{{issue_number}} in {{repository}}, produce a concrete implementation plan with milestones, edge cases, and tests. Post/update an issue comment with the plan.",
+  "cooldown_secs": 30
+}
+```
+
+## 2) Maintainer Comment Gate (Update Plan vs Implement)
+
+Trigger per-maintainer by creating one routine per handle, or maintain a shared author convention.
+
+```json
+{
+  "name": "wf-maintainer-comment-gate-{{maintainer}}",
+  "description": "React to maintainer guidance comments on issues/PRs",
+  "trigger_type": "system_event",
+  "event_source": "github",
+  "event_type": "pr.comment.created",
+  "event_filters": {
+    "repository": "{{repository}}",
+    "comment_author": "{{maintainer}}"
+  },
+  "action_type": "full_job",
+  "prompt": "Read the maintainer comment and decide: update plan or start/continue implementation. If plan changes are requested, edit the plan artifact first. If implementation is requested, continue on the feature branch and update PR status/comment.",
+  "cooldown_secs": 20
+}
+```
+
+## 3) PR Monitor Loop
+
+```json
+{
+  "name": "wf-pr-monitor-loop",
+  "description": "Keep PR healthy: address review comments and refresh branch",
+  "trigger_type": "system_event",
+  "event_source": "github",
+  "event_type": "pr.synchronize",
+  "event_filters": {
+    "repository": "{{repository}}"
+  },
+  "action_type": "full_job",
+  "prompt": "For PR #{{pr_number}}, collect open review comments and unresolved threads, apply fixes, push branch updates, and summarize remaining blockers. If conflict with {{main_branch}}, rebase/merge from origin/{{main_branch}} and resolve safely.",
+  "cooldown_secs": 20
+}
+```
+
+## 4) CI Failure Fix Loop
+
+```json
+{
+  "name": "wf-ci-fix-loop",
+  "description": "Fix failing CI checks on active PRs",
+  "trigger_type": "system_event",
+  "event_source": "github",
+  "event_type": "ci.check_run.completed",
+  "event_filters": {
+    "repository": "{{repository}}",
+    "ci_conclusion": "failure"
+  },
+  "action_type": "full_job",
+  "prompt": "Find failing check details for PR #{{pr_number}}, implement minimal safe fixes, rerun or await CI, and post concise status updates. Prioritize deterministic and test-backed fixes.",
+  "cooldown_secs": 20
+}
+```
+
+## 5) Staging Batch Review (Every 8h)
+
+```json
+{
+  "name": "wf-staging-batch-review",
+  "description": "Batch correctness review through staging, then merge to main",
+  "trigger_type": "cron",
+  "schedule": "0 0 */{{batch_interval_hours}} * * *",
+  "action_type": "full_job",
+  "prompt": "Every cycle: list ready PRs, merge ready ones into {{staging_branch}}, run deep correctness analysis in batch, fix discovered issues on affected branches, ensure CI green, then merge {{staging_branch}} into {{main_branch}} if clean.",
+  "cooldown_secs": 120
+}
+```
+
+## 6) Post-Merge Learning -> Common Memory
+
+```json
+{
+  "name": "wf-learning-memory",
+  "description": "Capture merge learnings into shared memory",
+  "trigger_type": "system_event",
+  "event_source": "github",
+  "event_type": "pr.closed",
+  "event_filters": {
+    "repository": "{{repository}}",
+    "pr_merged": "true"
+  },
+  "action_type": "full_job",
+  "prompt": "From merged PR #{{pr_number}}, extract preventable mistakes, reviewer themes, CI failure causes, and successful patterns. Write/update a shared memory doc with actionable rules to reduce cycle time and regressions.",
+  "cooldown_secs": 30
+}
+```
+
+## Optional: Synthetic Event Test
+
+```json
+{
+  "source": "github",
+  "event_type": "issue.opened",
+  "payload": {
+    "repository": "{{repository}}",
+    "issue_number": 99999,
+    "sender": "test-bot"
+  }
+}
+```
+
+Use with `event_emit` after routine install.

src/agent/CLAUDE.md

@@ -14,14 +14,15 @@ Core agent logic. This is the most complex subsystem — read this before workin
 | `session_manager.rs` | Lifecycle: create/lookup sessions, map external thread IDs to internal UUIDs, prune stale sessions, manage undo managers. |
 | `router.rs` | Routes explicit `/commands` to `MessageIntent`. Natural language bypasses the router entirely. |
 | `scheduler.rs` | Parallel job scheduling. Maintains `jobs` map (full LLM-driven) and `subtasks` map (tool-exec/background). |
-| `worker.rs` | Per-job execution for background scheduler jobs: calls LLM, runs tools, handles the reasoning loop. Distinct from `dispatcher.rs`. |
+| *(moved to `src/worker/job.rs`)* | Per-job execution now lives in `src/worker/job.rs` as `JobDelegate`, using the shared `run_agentic_loop()` engine. |
+| `agentic_loop.rs` | Shared agentic loop engine: `run_agentic_loop()`, `LoopDelegate` trait, `LoopOutcome`, `LoopSignal`, `TextAction`. All three execution paths (chat, job, container) delegate to this. |
 | `compaction.rs` | Context window management: summarize old turns, write to workspace daily log, trim context. Three strategies. |
 | `context_monitor.rs` | Detects memory pressure. Suggests `CompactionStrategy` based on usage level. |
 | `self_repair.rs` | Detects stuck jobs and broken tools, attempts recovery. |
 | `heartbeat.rs` | Proactive periodic execution. Reads `HEARTBEAT.md`, notifies via channel if findings. |
 | `submission.rs` | Parses all user submissions into typed variants before routing. |
 | `undo.rs` | Turn-based undo/redo with checkpoints. Checkpoints store message lists (max 20 by default). |
-| `routine.rs` | `Routine` types: `Trigger` (cron/event/webhook/manual) + `RoutineAction` (lightweight/full_job) + `RoutineGuardrails`. |
+| `routine.rs` | `Routine` types: `Trigger` (cron/event/system_event/manual) + `RoutineAction` (lightweight/full_job) + `RoutineGuardrails`. |
 | `routine_engine.rs` | Cron ticker and event matcher. Fires routines when triggers match. Lightweight runs inline; full_job dispatches to `Scheduler`. |
 | `task.rs` | Task types for the scheduler: `Job`, `ToolExec`, `Background`. Used by `spawn_subtask` and `spawn_batch`. |
 | `cost_guard.rs` | LLM spend and action-rate enforcement. Tracks daily budget (cents) and hourly call rate. Lives in `AgentDeps`. |
@@ -49,26 +50,28 @@ Session (per user)
 
 ## Agentic Loop (dispatcher.rs)
 
-The `dispatcher.rs` module handles **direct conversational turns** (user messages processed inline by the main agent). Background scheduler jobs use `worker.rs` instead — these are two separate execution paths.
+All three execution paths (chat, job, container) now use the shared `run_agentic_loop()` engine in `agentic_loop.rs`, each providing their own `LoopDelegate` implementation:
+
+- **`ChatDelegate`** (`dispatcher.rs`) — conversational turns, tool approval, skill context injection
+- **`JobDelegate`** (`src/worker/job.rs`) — background scheduler jobs, planning support, completion detection
+- **`ContainerDelegate`** (`src/worker/container.rs`) — Docker container worker, sequential tool exec, HTTP event streaming
 
 ```
-run_agentic_loop()  [dispatcher.rs — conversational turns]
-  1. Load workspace system prompt (identity files: AGENTS.md, SOUL.md, etc.)
-  2. Detect group chat from metadata; exclude MEMORY.md if group chat
-  3. Select active skills (keyword/pattern scoring against message content)
-  4. Build skill context block (injected before user message)
-  5. LLM call → text response OR tool calls
-  6. If tool calls:
-     a. Check tool approval (session auto-approvals, pending approval queue)
-     b. Execute tools (parallel via JoinSet)
-     c. Sanitize results through SafetyLayer
-     d. Feed results back → goto 5
-  7. Return AgenticLoopResult::Response or NeedApproval
+run_agentic_loop(delegate, reasoning, reason_ctx, config)
+  1. Check signals (stop/cancel) via delegate.check_signals()
+  2. Pre-LLM hook via delegate.before_llm_call()
+  3. LLM call via delegate.call_llm()
+  4. If text response → delegate.handle_text_response() → Continue or Return
+  5. If tool calls → delegate.execute_tool_calls() → Continue or Return
+  6. Post-iteration hook via delegate.after_iteration()
+  7. Repeat until LoopOutcome returned or max_iterations reached
 ```
 
-**Tool approval:** Tools flagged `requires_approval` pause the loop and return `NeedApproval`. The web gateway stores the `PendingApproval` in session state and sends an `approval_needed` SSE event. The user's approval/deny resumes the loop.
+**Tool approval:** Tools flagged `requires_approval` pause the loop — `ChatDelegate` returns `LoopOutcome::NeedApproval(pending)`. The web gateway stores the `PendingApproval` in session state and sends an `approval_needed` SSE event. The user's approval/deny resumes the loop.
 
-**worker.rs vs dispatcher.rs:** `dispatcher.rs` runs the agentic loop for user-initiated conversational turns (holds session lock, tracks turns). `worker.rs` is spawned by the `Scheduler` for background jobs created via `CreateJob` / `/job` — it runs independently of the session and has its own LLM reasoning loop with planning support (`use_planning` flag).
+**Shared tool execution:** `tools/execute.rs` provides `execute_tool_with_safety()` (validate → timeout → execute → serialize) and `process_tool_result()` (sanitize → wrap → ChatMessage), used by all three delegates.
+
+**ChatDelegate vs JobDelegate:** `ChatDelegate` runs for user-initiated conversational turns (holds session lock, tracks turns). `JobDelegate` is spawned by the `Scheduler` for background jobs created via `CreateJob` / `/job` — it runs independently of the session and has planning support (`use_planning` flag).
 
 ## Command Routing (router.rs)
 

src/agent/agent_loop.rs

@@ -738,6 +738,18 @@ impl Agent {
     }
 
     async fn handle_message(&self, message: &IncomingMessage) -> Result<Option<String>, Error> {
+        // Log at info level only for tracking without exposing PII (user_id can be a phone number)
+        tracing::info!(message_id = %message.id, "Processing message");
+
+        // Log sensitive details at debug level for troubleshooting
+        tracing::debug!(
+            message_id = %message.id,
+            user_id = %message.user_id,
+            channel = %message.channel,
+            thread_id = ?message.thread_id,
+            "Message details"
+        );
+
         // Set message tool context for this turn (current channel and target)
         // For Signal, use signal_target from metadata (group:ID or phone number),
         // otherwise fall back to user_id
@@ -753,7 +765,7 @@ impl Agent {
 
         // Parse submission type first
         let mut submission = SubmissionParser::parse(&message.content);
-        tracing::debug!(
+        tracing::trace!(
             "[agent_loop] Parsed submission: {:?}",
             std::any::type_name_of_val(&submission)
         );
@@ -786,10 +798,19 @@ impl Agent {
 
         // Hydrate thread from DB if it's a historical thread not in memory
         if let Some(ref external_thread_id) = message.thread_id {
+            tracing::trace!(
+                message_id = %message.id,
+                thread_id = %external_thread_id,
+                "Hydrating thread from DB"
+            );
             self.maybe_hydrate_thread(message, external_thread_id).await;
         }
 
         // Resolve session and thread
+        tracing::debug!(
+            message_id = %message.id,
+            "Resolving session and thread"
+        );
         let (session, thread_id) = self
             .session_manager
             .resolve_thread(
@@ -798,6 +819,11 @@ impl Agent {
                 message.thread_id.as_deref(),
             )
             .await;
+        tracing::debug!(
+            message_id = %message.id,
+            thread_id = %thread_id,
+            "Resolved session and thread"
+        );
 
         // Auth mode interception: if the thread is awaiting a token, route
         // the message directly to the credential store. Nothing touches
@@ -827,7 +853,7 @@ impl Agent {
             }
         }
 
-        tracing::debug!(
+        tracing::trace!(
             "Received message from {} on {} ({} chars)",
             message.user_id,
             message.channel,

src/agent/agentic_loop.rs

@@ -0,0 +1,587 @@
+//! Unified agentic loop engine.
+//!
+//! Provides a single implementation of the core LLM call → tool execution →
+//! result processing → context update → repeat cycle. Three consumers
+//! (chat dispatcher, job worker, container runtime) customize behavior
+//! via the `LoopDelegate` trait.
+
+use async_trait::async_trait;
+
+use crate::agent::session::PendingApproval;
+use crate::error::Error;
+use crate::llm::{ChatMessage, Reasoning, ReasoningContext, RespondResult};
+
+/// Signal from the delegate indicating how the loop should proceed.
+pub enum LoopSignal {
+    /// Continue normally.
+    Continue,
+    /// Stop the loop gracefully.
+    Stop,
+    /// Inject a user message into context and continue.
+    InjectMessage(String),
+}
+
+/// Outcome of a text response from the LLM.
+pub enum TextAction {
+    /// Return this as the final loop result.
+    Return(LoopOutcome),
+    /// Continue the loop (text was handled but loop should proceed).
+    Continue,
+}
+
+/// Final outcome of the agentic loop.
+pub enum LoopOutcome {
+    /// Completed with a text response.
+    Response(String),
+    /// Loop was stopped by a signal.
+    Stopped,
+    /// Max iterations exceeded.
+    MaxIterations,
+    /// A tool requires user approval before continuing (chat delegate only).
+    NeedApproval(Box<PendingApproval>),
+}
+
+/// Configuration for the agentic loop.
+pub struct AgenticLoopConfig {
+    pub max_iterations: usize,
+    pub enable_tool_intent_nudge: bool,
+    pub max_tool_intent_nudges: u32,
+}
+
+impl Default for AgenticLoopConfig {
+    fn default() -> Self {
+        Self {
+            max_iterations: 50,
+            enable_tool_intent_nudge: true,
+            max_tool_intent_nudges: 2,
+        }
+    }
+}
+
+/// Strategy trait — each consumer implements this to customize I/O and lifecycle.
+///
+/// The shared loop calls these methods at well-defined points. Consumers
+/// implement only the behavior that differs between chat, job, and container
+/// contexts. The loop itself handles the common logic: tool intent nudge,
+/// iteration counting, tool definition refresh, and the respond → execute → process cycle.
+///
+/// # `Send + Sync` requirement
+///
+/// This trait requires `Send + Sync` because the loop accepts `&dyn LoopDelegate`.
+/// Delegates using borrowed references (e.g. `ChatDelegate<'a>`) must ensure all
+/// borrowed fields are `Send + Sync`. This is a load-bearing constraint: if a
+/// delegate needs to be spawned into a detached task, it must use `Arc`-based
+/// ownership instead of borrows (as `JobDelegate` and `ContainerDelegate` do).
+#[async_trait]
+pub trait LoopDelegate: Send + Sync {
+    /// Called at the start of each iteration. Check for external signals
+    /// (cancellation, user messages, stop requests).
+    async fn check_signals(&self) -> LoopSignal;
+
+    /// Called before the LLM call. Allows the delegate to refresh tool
+    /// definitions, enforce cost guards, or inject messages.
+    /// Return `Some(outcome)` to break the loop early.
+    async fn before_llm_call(
+        &self,
+        reason_ctx: &mut ReasoningContext,
+        iteration: usize,
+    ) -> Option<LoopOutcome>;
+
+    /// Call the LLM and return the result. Delegates own the LLM call
+    /// to handle consumer-specific concerns (rate limiting, auto-compaction,
+    /// cost tracking, force_text mode).
+    async fn call_llm(
+        &self,
+        reasoning: &Reasoning,
+        reason_ctx: &mut ReasoningContext,
+        iteration: usize,
+    ) -> Result<crate::llm::RespondOutput, Error>;
+
+    /// Handle a text-only response from the LLM.
+    /// Return `TextAction::Return` to exit the loop, `TextAction::Continue` to proceed.
+    async fn handle_text_response(
+        &self,
+        text: &str,
+        reason_ctx: &mut ReasoningContext,
+    ) -> TextAction;
+
+    /// Execute tool calls and add results to context.
+    /// Return `Some(outcome)` to break the loop (e.g. approval needed).
+    async fn execute_tool_calls(
+        &self,
+        tool_calls: Vec<crate::llm::ToolCall>,
+        content: Option<String>,
+        reason_ctx: &mut ReasoningContext,
+    ) -> Result<Option<LoopOutcome>, Error>;
+
+    /// Called when the LLM expresses tool intent without actually calling a tool.
+    /// Delegates can use this to emit events or log the nudge for observability.
+    async fn on_tool_intent_nudge(&self, _text: &str, _reason_ctx: &mut ReasoningContext) {}
+
+    /// Called after each successful iteration (no error, no early return).
+    async fn after_iteration(&self, _iteration: usize) {}
+}
+
+/// Run the unified agentic loop.
+///
+/// This is the single implementation used by all three consumers (chat, job, container).
+/// The `delegate` provides consumer-specific behavior via the `LoopDelegate` trait.
+pub async fn run_agentic_loop(
+    delegate: &dyn LoopDelegate,
+    reasoning: &Reasoning,
+    reason_ctx: &mut ReasoningContext,
+    config: &AgenticLoopConfig,
+) -> Result<LoopOutcome, Error> {
+    let mut consecutive_tool_intent_nudges: u32 = 0;
+
+    for iteration in 1..=config.max_iterations {
+        // Check for external signals (stop, cancellation, user messages)
+        match delegate.check_signals().await {
+            LoopSignal::Continue => {}
+            LoopSignal::Stop => return Ok(LoopOutcome::Stopped),
+            LoopSignal::InjectMessage(msg) => {
+                reason_ctx.messages.push(ChatMessage::user(&msg));
+            }
+        }
+
+        // Pre-LLM call hook (cost guard, tool refresh, iteration limit nudge)
+        if let Some(outcome) = delegate.before_llm_call(reason_ctx, iteration).await {
+            return Ok(outcome);
+        }
+
+        // Call LLM
+        let output = delegate.call_llm(reasoning, reason_ctx, iteration).await?;
+
+        match output.result {
+            RespondResult::Text(text) => {
+                // Tool intent nudge: if the LLM says "let me search..." without
+                // actually calling a tool, inject a nudge message.
+                if config.enable_tool_intent_nudge
+                    && !reason_ctx.available_tools.is_empty()
+                    && !reason_ctx.force_text
+                    && consecutive_tool_intent_nudges < config.max_tool_intent_nudges
+                    && crate::llm::llm_signals_tool_intent(&text)
+                {
+                    consecutive_tool_intent_nudges += 1;
+                    tracing::info!(
+                        iteration,
+                        "LLM expressed tool intent without calling a tool, nudging"
+                    );
+                    delegate.on_tool_intent_nudge(&text, reason_ctx).await;
+                    reason_ctx.messages.push(ChatMessage::assistant(&text));
+                    reason_ctx
+                        .messages
+                        .push(ChatMessage::user(crate::llm::TOOL_INTENT_NUDGE));
+                    delegate.after_iteration(iteration).await;
+                    continue;
+                }
+
+                // Reset nudge counter since we got a non-intent text response
+                if !crate::llm::llm_signals_tool_intent(&text) {
+                    consecutive_tool_intent_nudges = 0;
+                }
+
+                match delegate.handle_text_response(&text, reason_ctx).await {
+                    TextAction::Return(outcome) => return Ok(outcome),
+                    TextAction::Continue => {}
+                }
+            }
+            RespondResult::ToolCalls {
+                tool_calls,
+                content,
+            } => {
+                consecutive_tool_intent_nudges = 0;
+
+                if let Some(outcome) = delegate
+                    .execute_tool_calls(tool_calls, content, reason_ctx)
+                    .await?
+                {
+                    return Ok(outcome);
+                }
+            }
+        }
+
+        delegate.after_iteration(iteration).await;
+    }
+
+    Ok(LoopOutcome::MaxIterations)
+}
+
+/// Truncate a string for log/status previews.
+///
+/// `max` is a byte budget. The result is truncated at the last valid char
+/// boundary at or before `max` bytes, so it is always valid UTF-8.
+pub fn truncate_for_preview(s: &str, max: usize) -> String {
+    if s.len() <= max {
+        s.to_string()
+    } else {
+        let end = crate::util::floor_char_boundary(s, max);
+        format!("{}...", &s[..end])
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::llm::{RespondOutput, TokenUsage, ToolCall};
+    use crate::testing::StubLlm;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use tokio::sync::Mutex;
+
+    fn stub_reasoning() -> Reasoning {
+        Reasoning::new(Arc::new(StubLlm::default()))
+    }
+
+    fn zero_usage() -> TokenUsage {
+        TokenUsage {
+            input_tokens: 0,
+            output_tokens: 0,
+            cache_read_input_tokens: 0,
+            cache_creation_input_tokens: 0,
+        }
+    }
+
+    fn text_output(text: &str) -> RespondOutput {
+        RespondOutput {
+            result: RespondResult::Text(text.to_string()),
+            usage: zero_usage(),
+        }
+    }
+
+    fn tool_calls_output(calls: Vec<ToolCall>) -> RespondOutput {
+        RespondOutput {
+            result: RespondResult::ToolCalls {
+                tool_calls: calls,
+                content: None,
+            },
+            usage: zero_usage(),
+        }
+    }
+
+    /// Configurable mock delegate for testing run_agentic_loop.
+    struct MockDelegate {
+        signal: Mutex<LoopSignal>,
+        llm_responses: Mutex<Vec<RespondOutput>>,
+        tool_exec_count: AtomicUsize,
+        tool_exec_outcome: Mutex<Option<LoopOutcome>>,
+        iterations_seen: Mutex<Vec<usize>>,
+        early_exit: Mutex<Option<(usize, LoopOutcome)>>,
+        nudge_count: AtomicUsize,
+    }
+
+    impl MockDelegate {
+        fn new(responses: Vec<RespondOutput>) -> Self {
+            Self {
+                signal: Mutex::new(LoopSignal::Continue),
+                llm_responses: Mutex::new(responses),
+                tool_exec_count: AtomicUsize::new(0),
+                tool_exec_outcome: Mutex::new(None),
+                iterations_seen: Mutex::new(Vec::new()),
+                early_exit: Mutex::new(None),
+                nudge_count: AtomicUsize::new(0),
+            }
+        }
+
+        fn with_signal(mut self, signal: LoopSignal) -> Self {
+            self.signal = Mutex::new(signal);
+            self
+        }
+
+        fn with_early_exit(mut self, iteration: usize, outcome: LoopOutcome) -> Self {
+            self.early_exit = Mutex::new(Some((iteration, outcome)));
+            self
+        }
+    }
+
+    #[async_trait]
+    impl LoopDelegate for MockDelegate {
+        async fn check_signals(&self) -> LoopSignal {
+            let mut sig = self.signal.lock().await;
+            std::mem::replace(&mut *sig, LoopSignal::Continue)
+        }
+
+        async fn before_llm_call(
+            &self,
+            _reason_ctx: &mut ReasoningContext,
+            iteration: usize,
+        ) -> Option<LoopOutcome> {
+            let mut guard = self.early_exit.lock().await;
+            let should_take = guard
+                .as_ref()
+                .is_some_and(|(target, _)| *target == iteration);
+            if should_take {
+                guard.take().map(|(_, o)| o)
+            } else {
+                None
+            }
+        }
+
+        async fn call_llm(
+            &self,
+            _reasoning: &Reasoning,
+            _reason_ctx: &mut ReasoningContext,
+            _iteration: usize,
+        ) -> Result<crate::llm::RespondOutput, crate::error::Error> {
+            let mut responses = self.llm_responses.lock().await;
+            if responses.is_empty() {
+                panic!("MockDelegate: no more LLM responses queued");
+            }
+            Ok(responses.remove(0))
+        }
+
+        async fn handle_text_response(
+            &self,
+            text: &str,
+            _reason_ctx: &mut ReasoningContext,
+        ) -> TextAction {
+            TextAction::Return(LoopOutcome::Response(text.to_string()))
+        }
+
+        async fn execute_tool_calls(
+            &self,
+            _tool_calls: Vec<ToolCall>,
+            _content: Option<String>,
+            reason_ctx: &mut ReasoningContext,
+        ) -> Result<Option<LoopOutcome>, crate::error::Error> {
+            self.tool_exec_count.fetch_add(1, Ordering::SeqCst);
+            reason_ctx
+                .messages
+                .push(ChatMessage::user("tool result stub"));
+            let outcome = self.tool_exec_outcome.lock().await.take();
+            Ok(outcome)
+        }
+
+        async fn on_tool_intent_nudge(&self, _text: &str, _reason_ctx: &mut ReasoningContext) {
+            self.nudge_count.fetch_add(1, Ordering::SeqCst);
+        }
+
+        async fn after_iteration(&self, iteration: usize) {
+            self.iterations_seen.lock().await.push(iteration);
+        }
+    }
+
+    // --- Tests ---
+
+    #[tokio::test]
+    async fn test_text_response_returns_immediately() {
+        let delegate = MockDelegate::new(vec![text_output("Hello, world!")]);
+        let reasoning = stub_reasoning();
+        let mut ctx = ReasoningContext::new();
+        let config = AgenticLoopConfig::default();
+
+        let outcome = run_agentic_loop(&delegate, &reasoning, &mut ctx, &config)
+            .await
+            .unwrap();
+
+        match outcome {
+            LoopOutcome::Response(text) => assert_eq!(text, "Hello, world!"),
+            _ => panic!("Expected LoopOutcome::Response"),
+        }
+        // after_iteration is NOT called when handle_text_response returns Return
+        // (the loop exits before reaching after_iteration).
+        assert!(delegate.iterations_seen.lock().await.is_empty());
+    }
+
+    #[tokio::test]
+    async fn test_tool_call_then_text_response() {
+        let tool_call = ToolCall {
+            id: "call_1".to_string(),
+            name: "echo".to_string(),
+            arguments: serde_json::json!({}),
+        };
+        let delegate = MockDelegate::new(vec![
+            tool_calls_output(vec![tool_call]),
+            text_output("Done!"),
+        ]);
+        let reasoning = stub_reasoning();
+        let mut ctx = ReasoningContext::new();
+        let config = AgenticLoopConfig::default();
+
+        let outcome = run_agentic_loop(&delegate, &reasoning, &mut ctx, &config)
+            .await
+            .unwrap();
+
+        match outcome {
+            LoopOutcome::Response(text) => assert_eq!(text, "Done!"),
+            _ => panic!("Expected LoopOutcome::Response"),
+        }
+        assert_eq!(delegate.tool_exec_count.load(Ordering::SeqCst), 1);
+        // after_iteration called for iteration 1 (tool call), but not 2
+        // (text response exits before after_iteration).
+        assert_eq!(*delegate.iterations_seen.lock().await, vec![1]);
+    }
+
+    #[tokio::test]
+    async fn test_stop_signal_exits_immediately() {
+        let delegate =
+            MockDelegate::new(vec![text_output("unreachable")]).with_signal(LoopSignal::Stop);
+        let reasoning = stub_reasoning();
+        let mut ctx = ReasoningContext::new();
+        let config = AgenticLoopConfig::default();
+
+        let outcome = run_agentic_loop(&delegate, &reasoning, &mut ctx, &config)
+            .await
+            .unwrap();
+
+        assert!(matches!(outcome, LoopOutcome::Stopped));
+        assert!(delegate.iterations_seen.lock().await.is_empty());
+    }
+
+    #[tokio::test]
+    async fn test_inject_message_adds_user_message() {
+        let delegate = MockDelegate::new(vec![text_output("Got it")])
+            .with_signal(LoopSignal::InjectMessage("injected prompt".to_string()));
+        let reasoning = stub_reasoning();
+        let mut ctx = ReasoningContext::new();
+        let config = AgenticLoopConfig::default();
+
+        let outcome = run_agentic_loop(&delegate, &reasoning, &mut ctx, &config)
+            .await
+            .unwrap();
+
+        assert!(matches!(outcome, LoopOutcome::Response(_)));
+        assert!(
+            ctx.messages
+                .iter()
+                .any(|m| m.role == crate::llm::Role::User && m.content.contains("injected prompt")),
+            "Injected message should appear in context"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_max_iterations_reached() {
+        struct ContinueDelegate;
+
+        #[async_trait]
+        impl LoopDelegate for ContinueDelegate {
+            async fn check_signals(&self) -> LoopSignal {
+                LoopSignal::Continue
+            }
+            async fn before_llm_call(
+                &self,
+                _: &mut ReasoningContext,
+                _: usize,
+            ) -> Option<LoopOutcome> {
+                None
+            }
+            async fn call_llm(
+                &self,
+                _: &Reasoning,
+                _: &mut ReasoningContext,
+                _: usize,
+            ) -> Result<crate::llm::RespondOutput, crate::error::Error> {
+                Ok(text_output("still working"))
+            }
+            async fn handle_text_response(
+                &self,
+                _: &str,
+                ctx: &mut ReasoningContext,
+            ) -> TextAction {
+                ctx.messages.push(ChatMessage::assistant("still working"));
+                TextAction::Continue
+            }
+            async fn execute_tool_calls(
+                &self,
+                _: Vec<ToolCall>,
+                _: Option<String>,
+                _: &mut ReasoningContext,
+            ) -> Result<Option<LoopOutcome>, crate::error::Error> {
+                Ok(None)
+            }
+        }
+
+        let delegate = ContinueDelegate;
+        let reasoning = stub_reasoning();
+        let mut ctx = ReasoningContext::new();
+        let config = AgenticLoopConfig {
+            max_iterations: 3,
+            ..Default::default()
+        };
+
+        let outcome = run_agentic_loop(&delegate, &reasoning, &mut ctx, &config)
+            .await
+            .unwrap();
+
+        assert!(matches!(outcome, LoopOutcome::MaxIterations));
+        let assistant_count = ctx
+            .messages
+            .iter()
+            .filter(|m| m.role == crate::llm::Role::Assistant)
+            .count();
+        assert_eq!(assistant_count, 3);
+    }
+
+    #[tokio::test]
+    async fn test_tool_intent_nudge_fires_and_caps() {
+        let delegate = MockDelegate::new(vec![
+            text_output("Let me search for that file"),
+            text_output("Let me search for that file"),
+            text_output("Let me search for that file"),
+        ]);
+        let reasoning = stub_reasoning();
+        let mut ctx = ReasoningContext::new();
+        ctx.available_tools.push(crate::llm::ToolDefinition {
+            name: "search".to_string(),
+            description: "Search files".to_string(),
+            parameters: serde_json::json!({"type": "object"}),
+        });
+        let config = AgenticLoopConfig {
+            max_iterations: 10,
+            enable_tool_intent_nudge: true,
+            max_tool_intent_nudges: 2,
+        };
+
+        let outcome = run_agentic_loop(&delegate, &reasoning, &mut ctx, &config)
+            .await
+            .unwrap();
+
+        assert!(matches!(outcome, LoopOutcome::Response(_)));
+        assert_eq!(delegate.nudge_count.load(Ordering::SeqCst), 2);
+        let nudge_messages = ctx
+            .messages
+            .iter()
+            .filter(|m| {
+                m.role == crate::llm::Role::User
+                    && m.content.contains("you did not include any tool calls")
+            })
+            .count();
+        assert_eq!(
+            nudge_messages, 2,
+            "Should have exactly 2 nudge messages in context"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_before_llm_call_early_exit() {
+        let delegate = MockDelegate::new(vec![text_output("unreachable")])
+            .with_early_exit(1, LoopOutcome::Stopped);
+        let reasoning = stub_reasoning();
+        let mut ctx = ReasoningContext::new();
+        let config = AgenticLoopConfig::default();
+
+        let outcome = run_agentic_loop(&delegate, &reasoning, &mut ctx, &config)
+            .await
+            .unwrap();
+
+        assert!(matches!(outcome, LoopOutcome::Stopped));
+        assert!(delegate.iterations_seen.lock().await.is_empty());
+    }
+
+    #[test]
+    fn test_truncate_short_string_unchanged() {
+        assert_eq!(truncate_for_preview("hello", 10), "hello");
+    }
+
+    #[test]
+    fn test_truncate_long_string_adds_ellipsis() {
+        let result = truncate_for_preview("hello world", 5);
+        assert_eq!(result, "hello...");
+    }
+
+    #[test]
+    fn test_truncate_multibyte_safe() {
+        let result = truncate_for_preview("café", 4);
+        assert_eq!(result, "caf...");
+    }
+}

src/agent/commands.rs

@@ -405,7 +405,8 @@ impl Agent {
             .with_max_tokens(512)
             .with_temperature(0.3);
 
-        let reasoning = Reasoning::new(self.llm().clone());
+        let reasoning =
+            Reasoning::new(self.llm().clone()).with_model_name(self.llm().active_model_name());
         match reasoning.complete(request).await {
             Ok((text, _usage)) => Ok(SubmissionResult::response(format!(
                 "Thread Summary:\n\n{}",
@@ -453,7 +454,8 @@ impl Agent {
             .with_max_tokens(512)
             .with_temperature(0.5);
 
-        let reasoning = Reasoning::new(self.llm().clone());
+        let reasoning =
+            Reasoning::new(self.llm().clone()).with_model_name(self.llm().active_model_name());
         match reasoning.complete(request).await {
             Ok((text, _usage)) => Ok(SubmissionResult::response(format!(
                 "Suggested Next Steps:\n\n{}",

src/agent/compaction.rs

@@ -227,7 +227,8 @@ Be brief but capture all important details. Use bullet points."#,
             .with_max_tokens(1024)
             .with_temperature(0.3);
 
-        let reasoning = Reasoning::new(self.llm.clone());
+        let reasoning =
+            Reasoning::new(self.llm.clone()).with_model_name(self.llm.active_model_name());
         let (text, _) = reasoning.complete(request).await?;
         Ok(text)
     }

src/agent/heartbeat.rs

@@ -189,7 +189,7 @@ impl HeartbeatRunner {
 
             // Skip during quiet hours
             if self.config.is_quiet_hours() {
-                tracing::debug!("Heartbeat skipped: quiet hours");
+                tracing::trace!("Heartbeat skipped: quiet hours");
                 continue;
             }
 
@@ -212,7 +212,7 @@ impl HeartbeatRunner {
 
             match self.check_heartbeat().await {
                 HeartbeatResult::Ok => {
-                    tracing::debug!("Heartbeat OK");
+                    tracing::trace!("Heartbeat OK");
                     self.consecutive_failures = 0;
                 }
                 HeartbeatResult::NeedsAttention(message) => {
@@ -221,7 +221,7 @@ impl HeartbeatRunner {
                     self.send_notification(&message).await;
                 }
                 HeartbeatResult::Skipped => {
-                    tracing::debug!("Heartbeat skipped");
+                    tracing::trace!("Heartbeat skipped");
                 }
                 HeartbeatResult::Failed(error) => {
                     tracing::error!("Heartbeat failed: {}", error);
@@ -303,7 +303,8 @@ impl HeartbeatRunner {
             .with_max_tokens(max_tokens)
             .with_temperature(0.3);
 
-        let reasoning = Reasoning::new(self.llm.clone());
+        let reasoning =
+            Reasoning::new(self.llm.clone()).with_model_name(self.llm.active_model_name());
         let (content, _usage) = match reasoning.complete(request).await {
             Ok(r) => r,
             Err(e) => return HeartbeatResult::Failed(format!("LLM call failed: {}", e)),

src/agent/mod.rs

@@ -11,6 +11,7 @@
 //! - Context compaction for long conversations
 
 mod agent_loop;
+pub mod agentic_loop;
 mod attachments;
 mod commands;
 pub mod compaction;
@@ -22,7 +23,7 @@ pub mod job_monitor;
 mod router;
 pub mod routine;
 pub mod routine_engine;
-mod scheduler;
+pub(crate) mod scheduler;
 mod self_repair;
 pub mod session;
 mod session_manager;
@@ -30,8 +31,8 @@ pub mod submission;
 pub mod task;
 mod thread_ops;
 pub mod undo;
-pub mod worker;
 
+pub use crate::worker::{Worker, WorkerDeps};
 pub(crate) use agent_loop::truncate_for_preview;
 pub use agent_loop::{Agent, AgentDeps};
 pub use compaction::{CompactionResult, ContextCompactor};
@@ -47,4 +48,3 @@ pub use session_manager::SessionManager;
 pub use submission::{Submission, SubmissionParser, SubmissionResult};
 pub use task::{Task, TaskContext, TaskHandler, TaskOutput};
 pub use undo::{Checkpoint, UndoManager};
-pub use worker::{Worker, WorkerDeps};

src/agent/routine.rs

@@ -8,7 +8,7 @@
 //! ┌──────────┐     ┌─────────┐     ┌──────────────────┐
 //! │  Trigger  │────▶│ Engine  │────▶│  Execution Mode  │
 //! │ cron/event│     │guardrail│     │lightweight│full_job│
-//! │ webhook   │     │ check   │     └──────────────────┘
+//! │ system    │     │ check   │     └──────────────────┘
 //! │ manual    │     └─────────┘              │
 //! └──────────┘                               ▼
 //!                                     ┌──────────────┐
@@ -69,12 +69,15 @@ pub enum Trigger {
         /// Regex pattern to match against message content.
         pattern: String,
     },
-    /// Fire on incoming webhook POST to /hooks/routine/{id}.
-    Webhook {
-        /// Optional webhook path suffix (defaults to routine id).
-        path: Option<String>,
-        /// Optional shared secret for HMAC validation.
-        secret: Option<String>,
+    /// Fire when a structured system event is emitted.
+    SystemEvent {
+        /// Event source namespace (e.g. "github", "workflow", "tool").
+        source: String,
+        /// Event type within the source (e.g. "issue.opened").
+        event_type: String,
+        /// Optional exact-match filters against payload top-level fields.
+        #[serde(default)]
+        filters: std::collections::HashMap<String, String>,
     },
     /// Only fires via tool call or CLI.
     Manual,
@@ -86,7 +89,7 @@ impl Trigger {
         match self {
             Trigger::Cron { .. } => "cron",
             Trigger::Event { .. } => "event",
-            Trigger::Webhook { .. } => "webhook",
+            Trigger::SystemEvent { .. } => "system_event",
             Trigger::Manual => "manual",
         }
     }
@@ -134,16 +137,39 @@ impl Trigger {
                     .map(String::from);
                 Ok(Trigger::Event { channel, pattern })
             }
-            "webhook" => {
-                let path = config
-                    .get("path")
+            "system_event" => {
+                let source = config
+                    .get("source")
                     .and_then(|v| v.as_str())
-                    .map(String::from);
-                let secret = config
-                    .get("secret")
+                    .ok_or_else(|| RoutineError::MissingField {
+                        context: "system_event trigger".into(),
+                        field: "source".into(),
+                    })?
+                    .to_string();
+                let event_type = config
+                    .get("event_type")
                     .and_then(|v| v.as_str())
-                    .map(String::from);
-                Ok(Trigger::Webhook { path, secret })
+                    .ok_or_else(|| RoutineError::MissingField {
+                        context: "system_event trigger".into(),
+                        field: "event_type".into(),
+                    })?
+                    .to_string();
+                let filters = config
+                    .get("filters")
+                    .and_then(|v| v.as_object())
+                    .map(|m| {
+                        m.iter()
+                            .filter_map(|(k, v)| {
+                                json_value_as_filter_string(v).map(|s| (k.clone(), s))
+                            })
+                            .collect()
+                    })
+                    .unwrap_or_default();
+                Ok(Trigger::SystemEvent {
+                    source,
+                    event_type,
+                    filters,
+                })
             }
             "manual" => Ok(Trigger::Manual),
             other => Err(RoutineError::UnknownTriggerType {
@@ -163,9 +189,14 @@ impl Trigger {
                 "pattern": pattern,
                 "channel": channel,
             }),
-            Trigger::Webhook { path, secret } => serde_json::json!({
-                "path": path,
-                "secret": secret,
+            Trigger::SystemEvent {
+                source,
+                event_type,
+                filters,
+            } => serde_json::json!({
+                "source": source,
+                "event_type": event_type,
+                "filters": filters,
             }),
             Trigger::Manual => serde_json::json!({}),
         }
@@ -428,6 +459,19 @@ pub struct RoutineRun {
     pub created_at: DateTime<Utc>,
 }
 
+/// Convert a JSON value to a string for filter storage.
+///
+/// Handles strings, numbers, and booleans — consistent with the matching
+/// logic in `routine_engine::json_value_as_string`.
+pub fn json_value_as_filter_string(v: &serde_json::Value) -> Option<String> {
+    match v {
+        serde_json::Value::String(s) => Some(s.clone()),
+        serde_json::Value::Number(n) => Some(n.to_string()),
+        serde_json::Value::Bool(b) => Some(b.to_string()),
+        _ => None,
+    }
+}
+
 /// Compute a content hash for event dedup.
 pub fn content_hash(content: &str) -> u64 {
     let mut hasher = DefaultHasher::new();
@@ -486,6 +530,24 @@ mod tests {
             if channel == Some("telegram".to_string()) && pattern == r"deploy\s+\w+"));
     }
 
+    #[test]
+    fn test_system_event_trigger_roundtrip() {
+        let mut filters = std::collections::HashMap::new();
+        filters.insert("repo".to_string(), "nearai/ironclaw".to_string());
+        filters.insert("action".to_string(), "opened".to_string());
+        let trigger = Trigger::SystemEvent {
+            source: "github".to_string(),
+            event_type: "issue".to_string(),
+            filters: filters.clone(),
+        };
+        let json = trigger.to_config_json();
+        let parsed = Trigger::from_db("system_event", json).expect("parse system_event");
+        assert!(
+            matches!(parsed, Trigger::SystemEvent { source, event_type, filters: f }
+            if source == "github" && event_type == "issue" && f == filters)
+        );
+    }
+
     #[test]
     fn test_action_lightweight_roundtrip() {
         let action = RoutineAction::Lightweight {
@@ -623,12 +685,13 @@ mod tests {
             "event"
         );
         assert_eq!(
-            Trigger::Webhook {
-                path: None,
-                secret: None
+            Trigger::SystemEvent {
+                source: String::new(),
+                event_type: String::new(),
+                filters: std::collections::HashMap::new(),
             }
             .type_tag(),
-            "webhook"
+            "system_event"
         );
         assert_eq!(Trigger::Manual.type_tag(), "manual");
     }

src/agent/routine_engine.rs

@@ -32,9 +32,14 @@ use crate::llm::{
     ChatMessage, CompletionRequest, FinishReason, LlmProvider, ToolCall, ToolCompletionRequest,
 };
 use crate::safety::SafetyLayer;
-use crate::tools::{ApprovalContext, ApprovalRequirement, ToolError, ToolRegistry, redact_params};
+use crate::tools::{ApprovalContext, ApprovalRequirement, ToolError, ToolRegistry};
 use crate::workspace::Workspace;
 
+enum EventMatcher {
+    Message { routine: Routine, regex: Regex },
+    System { routine: Routine },
+}
+
 /// The routine execution engine.
 pub struct RoutineEngine {
     config: RoutineConfig,
@@ -45,8 +50,8 @@ pub struct RoutineEngine {
     notify_tx: mpsc::Sender<OutgoingResponse>,
     /// Currently running routine count (across all routines).
     running_count: Arc<AtomicUsize>,
-    /// Compiled event regex cache: routine_id -> compiled regex.
-    event_cache: Arc<RwLock<Vec<(Uuid, Routine, Regex)>>>,
+    /// Cached matchers for all event-driven routines.
+    event_cache: Arc<RwLock<Vec<EventMatcher>>>,
     /// Scheduler for dispatching jobs (FullJob mode).
     scheduler: Option<Arc<Scheduler>>,
     /// Tool registry for lightweight routine tool execution.
@@ -87,9 +92,12 @@ impl RoutineEngine {
             Ok(routines) => {
                 let mut cache = Vec::new();
                 for routine in routines {
-                    if let Trigger::Event { ref pattern, .. } = routine.trigger {
-                        match Regex::new(pattern) {
-                            Ok(re) => cache.push((routine.id, routine.clone(), re)),
+                    match &routine.trigger {
+                        Trigger::Event { pattern, .. } => match Regex::new(pattern) {
+                            Ok(re) => cache.push(EventMatcher::Message {
+                                routine: routine.clone(),
+                                regex: re,
+                            }),
                             Err(e) => {
                                 tracing::warn!(
                                     routine = %routine.name,
@@ -97,12 +105,18 @@ impl RoutineEngine {
                                     pattern, e
                                 );
                             }
+                        },
+                        Trigger::SystemEvent { .. } => {
+                            cache.push(EventMatcher::System {
+                                routine: routine.clone(),
+                            });
                         }
+                        _ => {}
                     }
                 }
                 let count = cache.len();
                 *self.event_cache.write().await = cache;
-                tracing::debug!("Refreshed event cache: {} routines", count);
+                tracing::trace!("Refreshed event cache: {} routines", count);
             }
             Err(e) => {
                 tracing::error!("Failed to refresh event cache: {}", e);
@@ -118,7 +132,11 @@ impl RoutineEngine {
         let cache = self.event_cache.read().await;
         let mut fired = 0;
 
-        for (_, routine, re) in cache.iter() {
+        for matcher in cache.iter() {
+            let (routine, re) = match matcher {
+                EventMatcher::Message { routine, regex } => (routine, regex),
+                EventMatcher::System { .. } => continue,
+            };
             // Channel filter
             if let Trigger::Event {
                 channel: Some(ch), ..
@@ -135,13 +153,13 @@ impl RoutineEngine {
 
             // Cooldown check
             if !self.check_cooldown(routine) {
-                tracing::debug!(routine = %routine.name, "Skipped: cooldown active");
+                tracing::trace!(routine = %routine.name, "Skipped: cooldown active");
                 continue;
             }
 
             // Concurrent run check
             if !self.check_concurrent(routine).await {
-                tracing::debug!(routine = %routine.name, "Skipped: max concurrent reached");
+                tracing::trace!(routine = %routine.name, "Skipped: max concurrent reached");
                 continue;
             }
 
@@ -159,6 +177,88 @@ impl RoutineEngine {
         fired
     }
 
+    /// Emit a structured event to system-event routines.
+    ///
+    /// Returns the number of routines that were fired.
+    pub async fn emit_system_event(
+        &self,
+        source: &str,
+        event_type: &str,
+        payload: &serde_json::Value,
+        user_id: Option<&str>,
+    ) -> usize {
+        let cache = self.event_cache.read().await;
+        let mut fired = 0;
+
+        for matcher in cache.iter() {
+            let routine = match matcher {
+                EventMatcher::System { routine } => routine,
+                EventMatcher::Message { .. } => continue,
+            };
+
+            let Trigger::SystemEvent {
+                source: expected_source,
+                event_type: expected_event,
+                filters,
+            } = &routine.trigger
+            else {
+                continue;
+            };
+
+            if !expected_source.eq_ignore_ascii_case(source)
+                || !expected_event.eq_ignore_ascii_case(event_type)
+            {
+                continue;
+            }
+
+            if let Some(uid) = user_id
+                && routine.user_id != uid
+            {
+                continue;
+            }
+
+            let mut matched = true;
+            for (key, expected) in filters {
+                let Some(actual) = payload
+                    .get(key)
+                    .and_then(crate::agent::routine::json_value_as_filter_string)
+                else {
+                    tracing::debug!(routine = %routine.name, filter_key = %key, "Filter key not found in payload");
+                    matched = false;
+                    break;
+                };
+                if !actual.eq_ignore_ascii_case(expected) {
+                    matched = false;
+                    break;
+                }
+            }
+            if !matched {
+                continue;
+            }
+
+            if !self.check_cooldown(routine) {
+                tracing::debug!(routine = %routine.name, "Skipped: cooldown active");
+                continue;
+            }
+
+            if !self.check_concurrent(routine).await {
+                tracing::debug!(routine = %routine.name, "Skipped: max concurrent reached");
+                continue;
+            }
+
+            if self.running_count.load(Ordering::Relaxed) >= self.config.max_concurrent_routines {
+                tracing::warn!(routine = %routine.name, "Skipped: global max concurrent reached");
+                continue;
+            }
+
+            let detail = truncate(&format!("{source}:{event_type}"), 200);
+            self.spawn_fire(routine.clone(), "system_event", Some(detail));
+            fired += 1;
+        }
+
+        fired
+    }
+
     /// Check all due cron routines and fire them. Called by the cron ticker.
     pub async fn check_cron_triggers(&self) {
         let routines = match self.store.list_due_cron_routines().await {
@@ -913,13 +1013,6 @@ async fn execute_routine_tool(
         return Err(format!("Invalid tool parameters: {}", details).into());
     }
 
-    let safe_params = redact_params(&tc.arguments, tool.sensitive_params());
-    tracing::debug!(
-        tool = %tc.name,
-        params = %safe_params,
-        "Lightweight routine tool call started"
-    );
-
     // Execute with per-tool timeout
     let timeout = tool.execution_timeout();
     let start = std::time::Instant::now();
@@ -929,12 +1022,14 @@ async fn execute_routine_tool(
     .await;
     let elapsed = start.elapsed();
 
+    // Log tool execution result (single consolidated log)
     match &result {
         Ok(Ok(_)) => {
             tracing::debug!(
                 tool = %tc.name,
                 elapsed_ms = elapsed.as_millis() as u64,
-                "Lightweight routine tool call succeeded"
+                status = "succeeded",
+                "Lightweight routine tool execution completed"
             );
         }
         Ok(Err(e)) => {
@@ -942,7 +1037,8 @@ async fn execute_routine_tool(
                 tool = %tc.name,
                 elapsed_ms = elapsed.as_millis() as u64,
                 error = %e,
-                "Lightweight routine tool call failed"
+                status = "failed",
+                "Lightweight routine tool execution completed"
             );
         }
         Err(_) => {
@@ -950,7 +1046,8 @@ async fn execute_routine_tool(
                 tool = %tc.name,
                 elapsed_ms = elapsed.as_millis() as u64,
                 timeout_secs = timeout.as_secs(),
-                "Lightweight routine tool call timed out"
+                status = "timeout",
+                "Lightweight routine tool execution completed"
             );
         }
     }

src/agent/scheduler.rs

@@ -9,7 +9,6 @@ use tokio::task::JoinHandle;
 use uuid::Uuid;
 
 use crate::agent::task::{Task, TaskContext, TaskOutput};
-use crate::agent::worker::{Worker, WorkerDeps};
 use crate::channels::web::types::SseEvent;
 use crate::config::AgentConfig;
 use crate::context::{ContextManager, JobContext, JobState};
@@ -19,6 +18,7 @@ use crate::hooks::HookRegistry;
 use crate::llm::LlmProvider;
 use crate::safety::SafetyLayer;
 use crate::tools::{ApprovalContext, ToolRegistry};
+use crate::worker::job::{Worker, WorkerDeps};
 
 /// Message to send to a worker.
 #[derive(Debug)]
@@ -160,24 +160,36 @@ impl Scheduler {
             .create_job_for_user(user_id, title, description)
             .await?;
 
-        // Apply token budget from config, allowing per-job metadata override.
-        let max_tokens = metadata
+        // Apply metadata and token budget in a single atomic update.
+        // This prevents concurrent workers from observing partial state.
+        // Cap user-supplied max_tokens at the configured limit (Issue #815).
+        let user_max_tokens = metadata
             .as_ref()
             .and_then(|m| m.get("max_tokens"))
-            .and_then(|v| v.as_u64())
+            .and_then(|v| v.as_u64());
+
+        let max_tokens = user_max_tokens
+            .map(|user_val| {
+                if self.config.max_tokens_per_job == 0 {
+                    // Config is "unlimited": use the user-supplied value directly.
+                    user_val
+                } else {
+                    std::cmp::min(user_val, self.config.max_tokens_per_job)
+                }
+            })
             .unwrap_or(self.config.max_tokens_per_job);
 
-        // Apply metadata if provided
+        // Apply both metadata and token budget in one closure (Issue #813: atomic update)
         if let Some(meta) = metadata {
             self.context_manager
                 .update_context(job_id, |ctx| {
                     ctx.metadata = meta;
+                    if max_tokens > 0 {
+                        ctx.max_tokens = max_tokens;
+                    }
                 })
                 .await?;
-        }
-
-        // Set token budget (separate update to avoid overwriting metadata)
-        if max_tokens > 0 {
+        } else if max_tokens > 0 {
             self.context_manager
                 .update_context(job_id, |ctx| {
                     ctx.max_tokens = max_tokens;
@@ -462,6 +474,9 @@ impl Scheduler {
     }
 
     /// Execute a single tool as a subtask.
+    ///
+    /// Performs scheduler-specific checks (approval, cancellation) then
+    /// delegates to the shared `execute_tool_with_safety` pipeline.
     async fn execute_tool_task(
         tools: Arc<ToolRegistry>,
         context_manager: Arc<ContextManager>,
@@ -473,7 +488,7 @@ impl Scheduler {
     ) -> Result<TaskOutput, Error> {
         let start = std::time::Instant::now();
 
-        // Get the tool
+        // Get the tool for approval check
         let tool = tools.get(tool_name).await.ok_or_else(|| {
             Error::Tool(crate::error::ToolError::NotFound {
                 name: tool_name.to_string(),
@@ -490,6 +505,7 @@ impl Scheduler {
             .into());
         }
 
+        // Scheduler-specific approval check
         let requirement = tool.requires_approval(&params);
         let blocked =
             ApprovalContext::is_blocked_or_default(&approval_context, tool_name, requirement);
@@ -500,41 +516,23 @@ impl Scheduler {
             .into());
         }
 
-        // Validate tool parameters
-        let validation = safety.validator().validate_tool_params(&params);
-        if !validation.is_valid {
-            let details = validation
-                .errors
-                .iter()
-                .map(|e| format!("{}: {}", e.field, e.message))
-                .collect::<Vec<_>>()
-                .join("; ");
-            return Err(crate::error::ToolError::InvalidParameters {
+        // Delegate to shared tool execution pipeline
+        let output_str = crate::tools::execute::execute_tool_with_safety(
+            &tools, &safety, tool_name, &params, &job_ctx,
+        )
+        .await?;
+
+        // Parse back to Value for TaskOutput; this should be infallible given
+        // `execute_tool_with_safety` uses `serde_json::to_string_pretty`, but if it
+        // ever fails we surface a clear error instead of silently changing types.
+        let result_value: serde_json::Value = serde_json::from_str(&output_str).map_err(|e| {
+            Error::Tool(crate::error::ToolError::ExecutionFailed {
                 name: tool_name.to_string(),
-                reason: format!("Invalid tool parameters: {}", details),
-            }
-            .into());
-        }
+                reason: format!("Failed to parse tool output as JSON: {}", e),
+            })
+        })?;
 
-        // Execute with per-tool timeout
-        let tool_timeout = tool.execution_timeout();
-        let result =
-            tokio::time::timeout(tool_timeout, async { tool.execute(params, &job_ctx).await })
-                .await
-                .map_err(|_| {
-                    Error::Tool(crate::error::ToolError::Timeout {
-                        name: tool_name.to_string(),
-                        timeout: tool_timeout,
-                    })
-                })?
-                .map_err(|e| {
-                    Error::Tool(crate::error::ToolError::ExecutionFailed {
-                        name: tool_name.to_string(),
-                        reason: e.to_string(),
-                    })
-                })?;
-
-        Ok(TaskOutput::new(result.result, start.elapsed()))
+        Ok(TaskOutput::new(result_value, start.elapsed()))
     }
 
     /// Stop a running job.
@@ -699,8 +697,140 @@ impl Scheduler {
 mod tests {
     use super::*;
     use crate::config::SafetyConfig;
+    use crate::llm::{
+        CompletionRequest, CompletionResponse, LlmError, LlmProvider, ToolCompletionRequest,
+        ToolCompletionResponse,
+    };
     use crate::safety::SafetyLayer;
     use crate::tools::{ApprovalRequirement, Tool, ToolError, ToolOutput};
+    use rust_decimal_macros::dec;
+
+    /// Minimal LLM provider stub for scheduler tests that don't exercise LLM calls.
+    struct StubLlm;
+
+    #[async_trait::async_trait]
+    impl LlmProvider for StubLlm {
+        fn model_name(&self) -> &str {
+            "stub"
+        }
+        fn cost_per_token(&self) -> (rust_decimal::Decimal, rust_decimal::Decimal) {
+            (dec!(0), dec!(0))
+        }
+        async fn complete(&self, _req: CompletionRequest) -> Result<CompletionResponse, LlmError> {
+            Err(LlmError::RequestFailed {
+                provider: "stub".into(),
+                reason: "not implemented".into(),
+            })
+        }
+        async fn complete_with_tools(
+            &self,
+            _req: ToolCompletionRequest,
+        ) -> Result<ToolCompletionResponse, LlmError> {
+            Err(LlmError::RequestFailed {
+                provider: "stub".into(),
+                reason: "not implemented".into(),
+            })
+        }
+    }
+
+    /// Create a Scheduler for token-budget tests. The LLM stub will fail if a
+    /// worker actually tries to call it, but `dispatch_job` sets the token
+    /// budget *before* spawning the worker so we can inspect the context
+    /// immediately after dispatch.
+    fn make_test_scheduler(max_tokens_per_job: u64) -> Scheduler {
+        let config = AgentConfig {
+            name: "test".to_string(),
+            max_parallel_jobs: 5,
+            job_timeout: std::time::Duration::from_secs(30),
+            stuck_threshold: std::time::Duration::from_secs(300),
+            repair_check_interval: std::time::Duration::from_secs(3600),
+            max_repair_attempts: 0,
+            use_planning: false,
+            session_idle_timeout: std::time::Duration::from_secs(3600),
+            allow_local_tools: true,
+            max_cost_per_day_cents: None,
+            max_actions_per_hour: None,
+            max_tool_iterations: 10,
+            auto_approve_tools: true,
+            default_timezone: "UTC".to_string(),
+            max_tokens_per_job,
+        };
+        let cm = Arc::new(ContextManager::new(5));
+        let llm: Arc<dyn LlmProvider> = Arc::new(StubLlm);
+        let safety = Arc::new(SafetyLayer::new(&SafetyConfig {
+            max_output_length: 100_000,
+            injection_check_enabled: false,
+        }));
+        let tools = Arc::new(ToolRegistry::new());
+        let hooks = Arc::new(HookRegistry::default());
+
+        Scheduler::new(config, cm, llm, safety, tools, None, hooks)
+    }
+
+    #[tokio::test]
+    async fn test_dispatch_job_caps_user_max_tokens() {
+        let sched = make_test_scheduler(1000);
+        let meta = serde_json::json!({ "max_tokens": 5000 });
+        let job_id = sched
+            .dispatch_job("user1", "test", "desc", Some(meta))
+            .await
+            .unwrap();
+
+        let ctx = sched.context_manager.get_context(job_id).await.unwrap();
+        assert_eq!(ctx.max_tokens, 1000, "should cap at configured limit");
+    }
+
+    #[tokio::test]
+    async fn test_dispatch_job_unlimited_config_preserves_user_tokens() {
+        let sched = make_test_scheduler(0); // 0 = unlimited
+        let meta = serde_json::json!({ "max_tokens": 5000 });
+        let job_id = sched
+            .dispatch_job("user1", "test", "desc", Some(meta))
+            .await
+            .unwrap();
+
+        let ctx = sched.context_manager.get_context(job_id).await.unwrap();
+        assert_eq!(
+            ctx.max_tokens, 5000,
+            "unlimited config should preserve user value"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_dispatch_job_no_user_tokens_uses_config() {
+        let sched = make_test_scheduler(2000);
+        let job_id = sched
+            .dispatch_job("user1", "test", "desc", None)
+            .await
+            .unwrap();
+
+        let ctx = sched.context_manager.get_context(job_id).await.unwrap();
+        assert_eq!(
+            ctx.max_tokens, 2000,
+            "should use config default when no user value"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_dispatch_job_atomic_metadata_and_tokens() {
+        let sched = make_test_scheduler(10_000);
+        let meta = serde_json::json!({
+            "max_tokens": 3000,
+            "custom_key": "custom_value"
+        });
+        let job_id = sched
+            .dispatch_job("user1", "test", "desc", Some(meta))
+            .await
+            .unwrap();
+
+        let ctx = sched.context_manager.get_context(job_id).await.unwrap();
+        assert_eq!(ctx.max_tokens, 3000, "should use user value within limit");
+        assert_eq!(
+            ctx.metadata.get("custom_key").and_then(|v| v.as_str()),
+            Some("custom_value"),
+            "metadata should be set atomically with token budget"
+        );
+    }
 
     #[test]
     fn test_scheduler_creation() {

src/agent/self_repair.rs

@@ -334,22 +334,21 @@ impl RepairTask {
             // Check for stuck jobs
             let stuck_jobs = self.repair.detect_stuck_jobs().await;
             for job in stuck_jobs {
-                tracing::info!("Attempting to repair stuck job {}", job.job_id);
                 match self.repair.repair_stuck_job(&job).await {
                     Ok(RepairResult::Success { message }) => {
-                        tracing::info!("Repair succeeded: {}", message);
+                        tracing::info!(job = %job.job_id, status = "success", "Stuck job repair completed: {}", message);
                     }
                     Ok(RepairResult::Retry { message }) => {
-                        tracing::warn!("Repair needs retry: {}", message);
+                        tracing::debug!(job = %job.job_id, status = "retry", "Stuck job repair needs retry: {}", message);
                     }
                     Ok(RepairResult::Failed { message }) => {
-                        tracing::error!("Repair failed: {}", message);
+                        tracing::error!(job = %job.job_id, status = "failed", "Stuck job repair failed: {}", message);
                     }
                     Ok(RepairResult::ManualRequired { message }) => {
-                        tracing::warn!("Manual intervention needed: {}", message);
+                        tracing::warn!(job = %job.job_id, status = "manual", "Stuck job repair requires manual intervention: {}", message);
                     }
                     Err(e) => {
-                        tracing::error!("Repair error: {}", e);
+                        tracing::error!(job = %job.job_id, "Stuck job repair error: {}", e);
                     }
                 }
             }
@@ -357,13 +356,12 @@ impl RepairTask {
             // Check for broken tools
             let broken_tools = self.repair.detect_broken_tools().await;
             for tool in broken_tools {
-                tracing::info!("Attempting to repair broken tool: {}", tool.name);
                 match self.repair.repair_broken_tool(&tool).await {
                     Ok(result) => {
-                        tracing::info!("Tool repair result: {:?}", result);
+                        tracing::debug!(tool = %tool.name, status = "completed", "Tool repair completed: {:?}", result);
                     }
                     Err(e) => {
-                        tracing::error!("Tool repair error: {}", e);
+                        tracing::error!(tool = %tool.name, "Tool repair error: {}", e);
                     }
                 }
             }

src/agent/thread_ops.rs

@@ -113,6 +113,13 @@ impl Agent {
         thread_id: Uuid,
         content: &str,
     ) -> Result<SubmissionResult, Error> {
+        tracing::debug!(
+            message_id = %message.id,
+            thread_id = %thread_id,
+            content_len = content.len(),
+            "Processing user input"
+        );
+
         // First check thread state without holding lock during I/O
         let thread_state = {
             let sess = session.lock().await;
@@ -123,19 +130,41 @@ impl Agent {
             thread.state
         };
 
+        tracing::debug!(
+            message_id = %message.id,
+            thread_id = %thread_id,
+            thread_state = ?thread_state,
+            "Checked thread state"
+        );
+
         // Check thread state
         match thread_state {
             ThreadState::Processing => {
+                tracing::warn!(
+                    message_id = %message.id,
+                    thread_id = %thread_id,
+                    "Thread is processing, rejecting new input"
+                );
                 return Ok(SubmissionResult::error(
                     "Turn in progress. Use /interrupt to cancel.",
                 ));
             }
             ThreadState::AwaitingApproval => {
+                tracing::warn!(
+                    message_id = %message.id,
+                    thread_id = %thread_id,
+                    "Thread awaiting approval, rejecting new input"
+                );
                 return Ok(SubmissionResult::error(
                     "Waiting for approval. Use /interrupt to cancel.",
                 ));
             }
             ThreadState::Completed => {
+                tracing::warn!(
+                    message_id = %message.id,
+                    thread_id = %thread_id,
+                    "Thread completed, rejecting new input"
+                );
                 return Ok(SubmissionResult::error(
                     "Thread completed. Use /thread new.",
                 ));
@@ -269,9 +298,20 @@ impl Agent {
         };
 
         // Persist user message to DB immediately so it survives crashes
+        tracing::debug!(
+            message_id = %message.id,
+            thread_id = %thread_id,
+            "Persisting user message to DB"
+        );
         self.persist_user_message(thread_id, &message.user_id, effective_content)
             .await;
 
+        tracing::debug!(
+            message_id = %message.id,
+            thread_id = %thread_id,
+            "User message persisted, starting agentic loop"
+        );
+
         // Send thinking status
         let _ = self
             .channels
@@ -812,19 +852,12 @@ impl Agent {
             // Sanitize tool result, then record the cleaned version in the
             // thread. Must happen before auth intercept check which may return early.
             let is_tool_error = tool_result.is_err();
-            let result_content = match &tool_result {
-                Ok(output) => {
-                    let sanitized = self
-                        .safety()
-                        .sanitize_tool_output(&pending.tool_name, output);
-                    self.safety().wrap_for_llm(
-                        &pending.tool_name,
-                        &sanitized.content,
-                        sanitized.was_modified,
-                    )
-                }
-                Err(e) => format!("Error: {}", e),
-            };
+            let (result_content, _) = crate::tools::execute::process_tool_result(
+                self.safety(),
+                &pending.tool_name,
+                &pending.tool_call_id,
+                &tool_result,
+            );
 
             // Record sanitized result in thread
             {
@@ -892,14 +925,20 @@ impl Agent {
 
             for (idx, tc) in deferred_tool_calls.iter().enumerate() {
                 if let Some(tool) = self.tools().get(&tc.name).await {
-                    use crate::tools::ApprovalRequirement;
-                    let needs_approval = match tool.requires_approval(&tc.arguments) {
-                        ApprovalRequirement::Never => false,
-                        ApprovalRequirement::UnlessAutoApproved => {
-                            let sess = session.lock().await;
-                            !sess.is_tool_auto_approved(&tc.name)
+                    // Match dispatcher.rs: when auto_approve_tools is true, skip
+                    // all approval checks (including ApprovalRequirement::Always).
+                    let needs_approval = if self.config.auto_approve_tools {
+                        false
+                    } else {
+                        use crate::tools::ApprovalRequirement;
+                        match tool.requires_approval(&tc.arguments) {
+                            ApprovalRequirement::Never => false,
+                            ApprovalRequirement::UnlessAutoApproved => {
+                                let sess = session.lock().await;
+                                !sess.is_tool_auto_approved(&tc.name)
+                            }
+                            ApprovalRequirement::Always => true,
                         }
-                        ApprovalRequirement::Always => true,
                     };
 
                     if needs_approval {
@@ -1064,17 +1103,12 @@ impl Agent {
                 // Sanitize first, then record the cleaned version in thread.
                 // Must happen before auth detection which may set deferred_auth.
                 let is_deferred_error = deferred_result.is_err();
-                let deferred_content = match &deferred_result {
-                    Ok(output) => {
-                        let sanitized = self.safety().sanitize_tool_output(&tc.name, output);
-                        self.safety().wrap_for_llm(
-                            &tc.name,
-                            &sanitized.content,
-                            sanitized.was_modified,
-                        )
-                    }
-                    Err(e) => format!("Error: {}", e),
-                };
+                let (deferred_content, _) = crate::tools::execute::process_tool_result(
+                    self.safety(),
+                    &tc.name,
+                    &tc.id,
+                    &deferred_result,
+                );
 
                 // Record sanitized result in thread
                 {
@@ -1321,100 +1355,56 @@ impl Agent {
             None => return Ok(Some("Extension manager not available.".to_string())),
         };
 
-        match ext_mgr.auth(&pending.extension_name, Some(token)).await {
-            Ok(result) if result.is_authenticated() => {
-                tracing::info!(
-                    "Extension '{}' authenticated via auth mode",
-                    pending.extension_name
-                );
-
-                // Auto-activate so tools are available immediately after auth
-                match ext_mgr.activate(&pending.extension_name).await {
-                    Ok(activate_result) => {
-                        let tool_count = activate_result.tools_loaded.len();
-                        let tool_list = if activate_result.tools_loaded.is_empty() {
-                            String::new()
-                        } else {
-                            format!("\n\nTools: {}", activate_result.tools_loaded.join(", "))
-                        };
-                        let msg = format!(
-                            "{} authenticated and activated ({} tools loaded).{}",
-                            pending.extension_name, tool_count, tool_list
-                        );
-                        let _ = self
-                            .channels
-                            .send_status(
-                                &message.channel,
-                                StatusUpdate::AuthCompleted {
-                                    extension_name: pending.extension_name.clone(),
-                                    success: true,
-                                    message: msg.clone(),
-                                },
-                                &message.metadata,
-                            )
-                            .await;
-                        Ok(Some(msg))
-                    }
-                    Err(e) => {
-                        tracing::warn!(
-                            "Extension '{}' authenticated but activation failed: {}",
-                            pending.extension_name,
-                            e
-                        );
-                        let msg = format!(
-                            "{} authenticated successfully, but activation failed: {}. \
-                             Try activating manually.",
-                            pending.extension_name, e
-                        );
-                        let _ = self
-                            .channels
-                            .send_status(
-                                &message.channel,
-                                StatusUpdate::AuthCompleted {
-                                    extension_name: pending.extension_name.clone(),
-                                    success: true,
-                                    message: msg.clone(),
-                                },
-                                &message.metadata,
-                            )
-                            .await;
-                        Ok(Some(msg))
-                    }
-                }
-            }
+        match ext_mgr
+            .configure_token(&pending.extension_name, token)
+            .await
+        {
             Ok(result) => {
-                // Invalid token, re-enter auth mode
-                {
-                    let mut sess = session.lock().await;
-                    if let Some(thread) = sess.threads.get_mut(&thread_id) {
-                        thread.enter_auth_mode(pending.extension_name.clone());
-                    }
-                }
-                let msg = result
-                    .instructions()
-                    .map(String::from)
-                    .unwrap_or_else(|| "Invalid token. Please try again.".to_string());
-                // Re-emit AuthRequired so web UI re-shows the card
+                tracing::info!(
+                    "Extension '{}' configured via auth mode: {}",
+                    pending.extension_name,
+                    result.message
+                );
                 let _ = self
                     .channels
                     .send_status(
                         &message.channel,
-                        StatusUpdate::AuthRequired {
+                        StatusUpdate::AuthCompleted {
                             extension_name: pending.extension_name.clone(),
-                            instructions: Some(msg.clone()),
-                            auth_url: result.auth_url().map(String::from),
-                            setup_url: result.setup_url().map(String::from),
+                            success: true,
+                            message: result.message.clone(),
                         },
                         &message.metadata,
                     )
                     .await;
-                Ok(Some(msg))
+                Ok(Some(result.message))
             }
             Err(e) => {
-                let msg = format!(
-                    "Authentication failed for {}: {}",
-                    pending.extension_name, e
-                );
+                let msg = e.to_string();
+                // Token validation errors: re-enter auth mode and re-prompt
+                if matches!(e, crate::extensions::ExtensionError::ValidationFailed(_)) {
+                    {
+                        let mut sess = session.lock().await;
+                        if let Some(thread) = sess.threads.get_mut(&thread_id) {
+                            thread.enter_auth_mode(pending.extension_name.clone());
+                        }
+                    }
+                    let _ = self
+                        .channels
+                        .send_status(
+                            &message.channel,
+                            StatusUpdate::AuthRequired {
+                                extension_name: pending.extension_name.clone(),
+                                instructions: Some(msg.clone()),
+                                auth_url: None,
+                                setup_url: None,
+                            },
+                            &message.metadata,
+                        )
+                        .await;
+                    return Ok(Some(msg));
+                }
+                // Infrastructure errors
                 let _ = self
                     .channels
                     .send_status(

src/app.rs

@@ -572,7 +572,7 @@ impl AppBuilder {
         let (dev_loaded_tool_names, _) = tokio::join!(wasm_tools_future, mcp_servers_future);
 
         // Load registry catalog entries for extension discovery
-        let catalog_entries = match crate::registry::RegistryCatalog::load_or_embedded() {
+        let mut catalog_entries = match crate::registry::RegistryCatalog::load_or_embedded() {
             Ok(catalog) => {
                 let entries: Vec<_> = catalog
                     .all()
@@ -591,6 +591,15 @@ impl AppBuilder {
             }
         };
 
+        // Append builtin entries (e.g. channel-relay integrations) so they appear
+        // in the web UI's available extensions list.
+        let builtin = crate::extensions::registry::builtin_entries();
+        for entry in builtin {
+            if !catalog_entries.iter().any(|e| e.name == entry.name) {
+                catalog_entries.push(entry);
+            }
+        }
+
         // Create extension manager. Use ephemeral in-memory secrets if no
         // persistent store is configured (listing/install/activate still work).
         let ext_secrets: Arc<dyn crate::secrets::SecretsStore + Send + Sync> = if let Some(ref s) =

src/channels/channel.rs

@@ -344,9 +344,28 @@ pub trait Channel: Send + Sync {
     }
 }
 
+/// Trait for channels that support hot-secret-swapping during SIGHUP reload.
+///
+/// This allows channels to update authentication credentials without restarting,
+/// enabling zero-downtime configuration reloads. Channels that don't support
+/// secret updates can simply not implement this trait.
+#[async_trait]
+pub trait ChannelSecretUpdater: Send + Sync {
+    /// Update the secret for this channel.
+    ///
+    /// Called during SIGHUP configuration reload. Implementation should:
+    /// - Apply the new secret atomically
+    /// - Not fail the entire reload if secret update fails
+    /// - Log appropriate errors/info messages
+    ///
+    /// The secret is optional (may be None if secret is no longer configured).
+    async fn update_secret(&self, new_secret: Option<secrecy::SecretString>);
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::testing::credentials::TEST_REDACT_SECRET_123;
 
     /// Stub tool that marks `"value"` as sensitive.
     struct SecretTool;
@@ -376,7 +395,7 @@ mod tests {
 
     #[test]
     fn tool_completed_redacts_sensitive_params_on_failure() {
-        let params = serde_json::json!({"name": "api_key", "value": "sk-secret-123"});
+        let params = serde_json::json!({"name": "api_key", "value": TEST_REDACT_SECRET_123});
         let err: Result<String, crate::error::Error> =
             Err(crate::error::ToolError::ExecutionFailed {
                 name: "secret_save".into(),
@@ -411,7 +430,7 @@ mod tests {
                 param_str
             );
             assert!(
-                !param_str.contains("sk-secret-123"),
+                !param_str.contains(TEST_REDACT_SECRET_123),
                 "raw secret should not appear: {}",
                 param_str
             );

src/channels/http.rs

@@ -10,7 +10,7 @@ use axum::{
     response::IntoResponse,
     routing::{get, post},
 };
-use secrecy::ExposeSecret;
+use secrecy::{ExposeSecret, SecretString};
 use serde::{Deserialize, Serialize};
 use subtle::ConstantTimeEq;
 use tokio::sync::{RwLock, mpsc, oneshot};
@@ -18,7 +18,8 @@ use tokio_stream::wrappers::ReceiverStream;
 use uuid::Uuid;
 
 use crate::channels::{
-    AttachmentKind, Channel, IncomingAttachment, IncomingMessage, MessageStream, OutgoingResponse,
+    AttachmentKind, Channel, ChannelSecretUpdater, IncomingAttachment, IncomingMessage,
+    MessageStream, OutgoingResponse,
 };
 use crate::config::HttpConfig;
 use crate::error::ChannelError;
@@ -29,13 +30,16 @@ pub struct HttpChannel {
     state: Arc<HttpChannelState>,
 }
 
-struct HttpChannelState {
+pub struct HttpChannelState {
     /// Sender for incoming messages.
     tx: RwLock<Option<mpsc::Sender<IncomingMessage>>>,
     /// Pending responses keyed by message ID.
     pending_responses: RwLock<std::collections::HashMap<Uuid, oneshot::Sender<String>>>,
     /// Expected webhook secret for authentication (if configured).
-    webhook_secret: Option<String>,
+    /// Stored in a separate Arc<RwLock<>> to avoid contending with other state operations.
+    /// Rarely changes (only on SIGHUP), so isolated from hot-path state accesses.
+    /// Uses SecretString to prevent accidental logging and memory dump exposure.
+    webhook_secret: Arc<RwLock<Option<SecretString>>>,
     /// Fixed user ID for this HTTP channel.
     user_id: String,
     /// Rate limiting state.
@@ -48,6 +52,14 @@ struct RateLimitState {
     request_count: u32,
 }
 
+impl HttpChannelState {
+    /// Update the webhook secret in-place without restarting the listener.
+    /// Called during SIGHUP to hot-swap credentials.
+    pub async fn update_secret(&self, new_secret: Option<SecretString>) {
+        *self.webhook_secret.write().await = new_secret;
+    }
+}
+
 /// Maximum JSON body size for webhook requests (15 MB, to support base64 image attachments
 /// with ~33% overhead from base64 encoding).
 const MAX_BODY_BYTES: usize = 15 * 1024 * 1024;
@@ -67,7 +79,7 @@ impl HttpChannel {
         let webhook_secret = config
             .webhook_secret
             .as_ref()
-            .map(|s| s.expose_secret().to_string());
+            .map(|s| SecretString::from(s.expose_secret().to_string()));
         let user_id = config.user_id.clone();
 
         Self {
@@ -75,7 +87,7 @@ impl HttpChannel {
             state: Arc::new(HttpChannelState {
                 tx: RwLock::new(None),
                 pending_responses: RwLock::new(std::collections::HashMap::new()),
-                webhook_secret,
+                webhook_secret: Arc::new(RwLock::new(webhook_secret)),
                 user_id,
                 rate_limit: tokio::sync::Mutex::new(RateLimitState {
                     window_start: std::time::Instant::now(),
@@ -102,6 +114,16 @@ impl HttpChannel {
     pub fn addr(&self) -> (&str, u16) {
         (&self.config.host, self.config.port)
     }
+
+    /// Return a shared handle to the channel state for out-of-band updates.
+    pub fn shared_state(&self) -> Arc<HttpChannelState> {
+        Arc::clone(&self.state)
+    }
+
+    /// Update the webhook secret in-place without restarting the listener.
+    pub async fn update_secret(&self, new_secret: Option<SecretString>) {
+        self.state.update_secret(new_secret).await;
+    }
 }
 
 #[derive(Debug, Deserialize)]
@@ -201,9 +223,10 @@ async fn webhook_handler(
     });
 
     // Validate secret if configured
-    if let Some(ref expected_secret) = state.webhook_secret {
+    if let Some(ref expected_secret) = *state.webhook_secret.read().await {
+        let expected_bytes = expected_secret.expose_secret().as_bytes();
         match &req.secret {
-            Some(provided) if bool::from(provided.as_bytes().ct_eq(expected_secret.as_bytes())) => {
+            Some(provided) if bool::from(provided.as_bytes().ct_eq(expected_bytes)) => {
                 // Secret matches, continue
             }
             Some(_) => {
@@ -372,9 +395,14 @@ async fn process_message(
         None
     };
 
-    // Send message to the channel
-    let tx_guard = state.tx.read().await;
-    if let Some(tx) = tx_guard.as_ref() {
+    // Clone sender while holding read lock, then release lock before async send.
+    // This prevents blocking other webhook handlers during the async I/O.
+    let tx = {
+        let guard = state.tx.read().await;
+        guard.as_ref().cloned()
+    };
+
+    if let Some(tx) = tx {
         if tx.send(msg).await.is_err() {
             return (
                 StatusCode::INTERNAL_SERVER_ERROR,
@@ -395,7 +423,6 @@ async fn process_message(
             }),
         );
     }
-    drop(tx_guard);
 
     // Wait for response if requested
     let response = if let Some(rx) = response_rx {
@@ -428,7 +455,7 @@ impl Channel for HttpChannel {
     }
 
     async fn start(&self) -> Result<MessageStream, ChannelError> {
-        if self.state.webhook_secret.is_none() {
+        if self.state.webhook_secret.read().await.is_none() {
             return Err(ChannelError::StartupFailed {
                 name: "http".to_string(),
                 reason: "HTTP webhook secret is required (set HTTP_WEBHOOK_SECRET)".to_string(),
@@ -475,6 +502,16 @@ impl Channel for HttpChannel {
     }
 }
 
+/// Implement secret update for HTTP channel state.
+/// This allows SIGHUP handler to update secrets generically via the trait.
+#[async_trait]
+impl ChannelSecretUpdater for HttpChannelState {
+    async fn update_secret(&self, new_secret: Option<SecretString>) {
+        *self.webhook_secret.write().await = new_secret;
+        tracing::info!("HTTP webhook secret updated");
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use axum::body::Body;
@@ -562,4 +599,156 @@ mod tests {
         let resp = app.oneshot(req).await.unwrap();
         assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
     }
+
+    #[tokio::test]
+    async fn test_update_secret_hot_swap() {
+        let channel = test_channel(Some("old-secret"));
+        let _stream = channel.start().await.unwrap();
+        let app1 = channel.routes();
+
+        // Request with old-secret should succeed
+        let body_old = serde_json::json!({
+            "content": "hello",
+            "secret": "old-secret"
+        });
+        let req1 = Request::builder()
+            .method("POST")
+            .uri("/webhook")
+            .header("content-type", "application/json")
+            .body(Body::from(serde_json::to_vec(&body_old).unwrap()))
+            .unwrap();
+        let resp1 = app1.oneshot(req1).await.unwrap();
+        assert_eq!(
+            resp1.status(),
+            StatusCode::OK,
+            "old secret should work initially"
+        );
+
+        // Update secret to new-secret
+        channel
+            .update_secret(Some(SecretString::from("new-secret".to_string())))
+            .await;
+
+        let app2 = channel.routes();
+
+        // Request with old-secret should fail
+        let req2 = Request::builder()
+            .method("POST")
+            .uri("/webhook")
+            .header("content-type", "application/json")
+            .body(Body::from(serde_json::to_vec(&body_old).unwrap()))
+            .unwrap();
+        let resp2 = app2.oneshot(req2).await.unwrap();
+        assert_eq!(
+            resp2.status(),
+            StatusCode::UNAUTHORIZED,
+            "old secret should fail after update"
+        );
+
+        let app3 = channel.routes();
+
+        // Request with new-secret should succeed
+        let body_new = serde_json::json!({
+            "content": "hello",
+            "secret": "new-secret"
+        });
+        let req3 = Request::builder()
+            .method("POST")
+            .uri("/webhook")
+            .header("content-type", "application/json")
+            .body(Body::from(serde_json::to_vec(&body_new).unwrap()))
+            .unwrap();
+        let resp3 = app3.oneshot(req3).await.unwrap();
+        assert_eq!(
+            resp3.status(),
+            StatusCode::OK,
+            "new secret should work after update"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_concurrent_requests_during_secret_update() {
+        use std::sync::Arc as StdArc;
+        use std::sync::atomic::{AtomicUsize, Ordering};
+        use std::time::Duration;
+
+        let channel = test_channel(Some("initial-secret"));
+        let _stream = channel.start().await.unwrap();
+        let app = channel.routes();
+
+        // Counters for request outcomes
+        let success_count = StdArc::new(AtomicUsize::new(0));
+
+        let mut handles = vec![];
+
+        // Spawn 5 concurrent tasks that keep making requests with the initial secret
+        for i in 0..5 {
+            let app = app.clone();
+            let success = StdArc::clone(&success_count);
+
+            let handle = tokio::spawn(async move {
+                let body = serde_json::json!({
+                    "content": format!("test-{}", i),
+                    "secret": "initial-secret"
+                });
+
+                let req = Request::builder()
+                    .method("POST")
+                    .uri("/webhook")
+                    .header("content-type", "application/json")
+                    .body(Body::from(serde_json::to_vec(&body).unwrap()))
+                    .unwrap();
+
+                let resp = app.oneshot(req).await.unwrap();
+                if resp.status() == StatusCode::OK {
+                    success.fetch_add(1, Ordering::SeqCst);
+                }
+            });
+            handles.push(handle);
+        }
+
+        // Update secret mid-flight (tests that RwLock allows readers while writer holds lock)
+        tokio::time::sleep(Duration::from_millis(5)).await;
+        channel
+            .update_secret(Some(SecretString::from("updated-secret".to_string())))
+            .await;
+
+        // Spawn 5 more tasks that use the new secret
+        for i in 5..10 {
+            let app = app.clone();
+            let success = StdArc::clone(&success_count);
+
+            let handle = tokio::spawn(async move {
+                let body = serde_json::json!({
+                    "content": format!("test-{}", i),
+                    "secret": "updated-secret"
+                });
+
+                let req = Request::builder()
+                    .method("POST")
+                    .uri("/webhook")
+                    .header("content-type", "application/json")
+                    .body(Body::from(serde_json::to_vec(&body).unwrap()))
+                    .unwrap();
+
+                let resp = app.oneshot(req).await.unwrap();
+                if resp.status() == StatusCode::OK {
+                    success.fetch_add(1, Ordering::SeqCst);
+                }
+            });
+            handles.push(handle);
+        }
+
+        // Wait for all tasks to complete
+        for handle in handles {
+            let _ = handle.await;
+        }
+
+        // Verify all requests succeeded with their respective secrets
+        assert_eq!(
+            success_count.load(Ordering::SeqCst),
+            10,
+            "All concurrent requests should succeed with correct secrets after update"
+        );
+    }
 }

src/channels/manager.rs

@@ -56,6 +56,17 @@ impl ChannelManager {
     /// the agent loop.
     pub async fn hot_add(&self, channel: Box<dyn Channel>) -> Result<(), ChannelError> {
         let name = channel.name().to_string();
+
+        // Shut down any existing channel with the same name to avoid parallel consumers.
+        // The old forwarding task will stop when the channel's stream ends after shutdown.
+        {
+            let channels = self.channels.read().await;
+            if let Some(existing) = channels.get(&name) {
+                tracing::debug!(channel = %name, "Shutting down existing channel before hot-add replacement");
+                let _ = existing.shutdown().await;
+            }
+        }
+
         let stream = channel.start().await?;
 
         // Register for respond/broadcast/send_status
@@ -337,4 +348,30 @@ mod tests {
         let msg = stream.next().await.expect("stream ended");
         assert_eq!(msg.content, "background alert");
     }
+
+    #[tokio::test]
+    async fn test_hot_add_replaces_existing_channel() {
+        // Regression: hot_add must shut down the existing channel before replacing it,
+        // to prevent duplicate SSE consumers from running in parallel.
+        let manager = ChannelManager::new();
+        let (stub1, _tx1) = StubChannel::new("relay");
+        manager.add(Box::new(stub1)).await;
+        let mut stream = manager.start_all().await.expect("start_all");
+
+        // Hot-add a replacement channel with the same name
+        let (stub2, tx2) = StubChannel::new("relay");
+        manager.hot_add(Box::new(stub2)).await.expect("hot_add");
+
+        // Send through the new channel — should arrive in the merged stream
+        tx2.send(IncomingMessage::new("relay", "u1", "from new"))
+            .await
+            .expect("send");
+        let msg = stream.next().await.expect("stream");
+        assert_eq!(msg.content, "from new");
+
+        // Verify only one channel entry exists
+        let channels = manager.channels.read().await;
+        assert_eq!(channels.len(), 1);
+        assert!(channels.contains_key("relay"));
+    }
 }

src/channels/mod.rs

@@ -30,6 +30,7 @@
 mod channel;
 mod http;
 mod manager;
+pub mod relay;
 mod repl;
 mod signal;
 pub mod wasm;
@@ -37,10 +38,10 @@ pub mod web;
 mod webhook_server;
 
 pub use channel::{
-    AttachmentKind, Channel, IncomingAttachment, IncomingMessage, MessageStream, OutgoingResponse,
-    StatusUpdate,
+    AttachmentKind, Channel, ChannelSecretUpdater, IncomingAttachment, IncomingMessage,
+    MessageStream, OutgoingResponse, StatusUpdate,
 };
-pub use http::HttpChannel;
+pub use http::{HttpChannel, HttpChannelState};
 pub use manager::ChannelManager;
 pub use repl::ReplChannel;
 pub use signal::SignalChannel;

src/channels/relay/channel.rs

@@ -0,0 +1,642 @@
+//! Channel trait implementation for channel-relay SSE streams.
+//!
+//! `RelayChannel` connects to a channel-relay service via SSE, converts
+//! incoming events to `IncomingMessage`s, and sends responses via the
+//! relay's provider-specific proxy API (Slack).
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use tokio::sync::{RwLock, mpsc};
+
+use crate::channels::relay::client::{RelayClient, RelayError};
+use crate::channels::{Channel, IncomingMessage, MessageStream, OutgoingResponse, StatusUpdate};
+use crate::error::ChannelError;
+
+/// Default channel name for the Slack relay integration.
+pub const DEFAULT_RELAY_NAME: &str = "slack-relay";
+
+/// The messaging provider backing a relay channel.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RelayProvider {
+    Slack,
+}
+
+impl RelayProvider {
+    /// Provider string used in proxy API routes and metadata.
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Slack => "slack",
+        }
+    }
+
+    /// The default channel name for this provider.
+    pub fn channel_name(&self) -> &'static str {
+        match self {
+            Self::Slack => DEFAULT_RELAY_NAME,
+        }
+    }
+}
+
+/// Channel implementation that connects to a channel-relay SSE stream.
+pub struct RelayChannel {
+    client: RelayClient,
+    provider: RelayProvider,
+    stream_token: Arc<RwLock<String>>,
+    team_id: String,
+    instance_id: String,
+    user_id: String,
+    /// SSE stream long-poll timeout in seconds.
+    stream_timeout_secs: u64,
+    /// Initial exponential backoff in milliseconds.
+    backoff_initial_ms: u64,
+    /// Maximum exponential backoff in milliseconds.
+    backoff_max_ms: u64,
+    /// Handle to the reconnect task for clean shutdown.
+    reconnect_handle: RwLock<Option<tokio::task::JoinHandle<()>>>,
+    /// Handle to the SSE parser task for clean shutdown.
+    parser_handle: Arc<RwLock<Option<tokio::task::JoinHandle<()>>>>,
+    /// Maximum consecutive reconnect failures before giving up.
+    max_consecutive_failures: u64,
+}
+
+impl RelayChannel {
+    /// Create a new relay channel for Slack (default provider).
+    pub fn new(
+        client: RelayClient,
+        stream_token: String,
+        team_id: String,
+        instance_id: String,
+        user_id: String,
+    ) -> Self {
+        Self::new_with_provider(
+            client,
+            RelayProvider::Slack,
+            stream_token,
+            team_id,
+            instance_id,
+            user_id,
+        )
+    }
+
+    /// Create a new relay channel with a specific provider.
+    pub fn new_with_provider(
+        client: RelayClient,
+        provider: RelayProvider,
+        stream_token: String,
+        team_id: String,
+        instance_id: String,
+        user_id: String,
+    ) -> Self {
+        Self {
+            client,
+            provider,
+            stream_token: Arc::new(RwLock::new(stream_token)),
+            team_id,
+            instance_id,
+            user_id,
+            stream_timeout_secs: 86400,
+            backoff_initial_ms: 1000,
+            backoff_max_ms: 60000,
+            reconnect_handle: RwLock::new(None),
+            parser_handle: Arc::new(RwLock::new(None)),
+            max_consecutive_failures: 50,
+        }
+    }
+
+    /// Set backoff/timeout parameters from relay config values.
+    pub fn with_timeouts(
+        mut self,
+        stream_timeout_secs: u64,
+        backoff_initial_ms: u64,
+        backoff_max_ms: u64,
+    ) -> Self {
+        self.stream_timeout_secs = stream_timeout_secs;
+        self.backoff_initial_ms = backoff_initial_ms;
+        self.backoff_max_ms = backoff_max_ms;
+        self
+    }
+
+    /// Set the maximum number of consecutive reconnect failures before giving up.
+    pub fn with_max_failures(mut self, max: u64) -> Self {
+        self.max_consecutive_failures = max;
+        self
+    }
+
+    /// Build a provider-appropriate proxy body for sending a message.
+    fn build_send_body(
+        &self,
+        channel_id: &str,
+        text: &str,
+        thread_id: Option<&str>,
+    ) -> (String, serde_json::Value) {
+        match self.provider {
+            RelayProvider::Slack => {
+                let mut body = serde_json::json!({
+                    "channel": channel_id,
+                    "text": text,
+                });
+                if let Some(tid) = thread_id {
+                    body["thread_ts"] = serde_json::Value::String(tid.to_string());
+                }
+                ("chat.postMessage".to_string(), body)
+            }
+        }
+    }
+
+    /// Send a message via the provider proxy.
+    async fn proxy_send(
+        &self,
+        team_id: &str,
+        method: &str,
+        body: serde_json::Value,
+    ) -> Result<serde_json::Value, RelayError> {
+        self.client
+            .proxy_provider(
+                self.provider.as_str(),
+                team_id,
+                method,
+                body,
+                Some(&self.instance_id),
+            )
+            .await
+    }
+}
+
+#[async_trait]
+impl Channel for RelayChannel {
+    fn name(&self) -> &str {
+        self.provider.channel_name()
+    }
+
+    async fn start(&self) -> Result<MessageStream, ChannelError> {
+        let channel_name = self.name().to_string();
+        let token = self.stream_token.read().await.clone();
+        let (stream, initial_parser_handle) = self
+            .client
+            .connect_stream(&token, self.stream_timeout_secs)
+            .await
+            .map_err(|e| ChannelError::StartupFailed {
+                name: channel_name.clone(),
+                reason: e.to_string(),
+            })?;
+
+        *self.parser_handle.write().await = Some(initial_parser_handle);
+
+        let (tx, rx) = mpsc::channel(64);
+
+        // Spawn the stream reader + reconnect task
+        let client = self.client.clone();
+        let stream_token = Arc::clone(&self.stream_token);
+        let instance_id = self.instance_id.clone();
+        let user_id = self.user_id.clone();
+        let team_id = self.team_id.clone();
+        let stream_timeout_secs = self.stream_timeout_secs;
+        let backoff_initial_ms = self.backoff_initial_ms;
+        let backoff_max_ms = self.backoff_max_ms;
+        let max_consecutive_failures = self.max_consecutive_failures;
+        let parser_handle = Arc::clone(&self.parser_handle);
+        let provider_str = self.provider.as_str().to_string();
+        let relay_name = channel_name.clone();
+
+        let handle = tokio::spawn(async move {
+            use futures::StreamExt;
+
+            let mut current_stream = stream;
+            let mut backoff_ms = backoff_initial_ms;
+            let mut consecutive_failures: u64 = 0;
+
+            loop {
+                // Read events from the current stream
+                while let Some(event) = current_stream.next().await {
+                    // Reset backoff and failure count on successful event
+                    backoff_ms = backoff_initial_ms;
+                    consecutive_failures = 0;
+
+                    // Validate required fields
+                    if event.sender_id.is_empty()
+                        || event.channel_id.is_empty()
+                        || event.provider_scope.is_empty()
+                    {
+                        tracing::debug!(
+                            event_type = %event.event_type,
+                            sender_id = %event.sender_id,
+                            channel_id = %event.channel_id,
+                            "Relay: skipping event with missing required fields"
+                        );
+                        continue;
+                    }
+
+                    // Skip non-message events
+                    if !event.is_message() {
+                        tracing::debug!(
+                            event_type = %event.event_type,
+                            "Relay: skipping non-message event"
+                        );
+                        continue;
+                    }
+
+                    tracing::info!(
+                        event_type = %event.event_type,
+                        sender = %event.sender_id,
+                        channel = %event.channel_id,
+                        provider = %provider_str,
+                        "Relay: received message from {}", provider_str
+                    );
+
+                    let msg = IncomingMessage::new(&relay_name, &event.sender_id, event.text())
+                        .with_user_name(event.display_name())
+                        .with_metadata(serde_json::json!({
+                            "team_id": event.team_id(),
+                            "channel_id": event.channel_id,
+                            "sender_id": event.sender_id,
+                            "sender_name": event.display_name(),
+                            "event_type": event.event_type,
+                            "thread_id": event.thread_id,
+                            "provider": event.provider,
+                        }));
+
+                    let msg = if let Some(ref thread_id) = event.thread_id {
+                        msg.with_thread(thread_id)
+                    } else {
+                        msg.with_thread(&event.channel_id)
+                    };
+
+                    if tx.send(msg).await.is_err() {
+                        tracing::info!("Relay channel receiver dropped, stopping");
+                        return;
+                    }
+                }
+
+                // Stream ended, attempt reconnect with backoff
+                consecutive_failures += 1;
+                if consecutive_failures >= max_consecutive_failures {
+                    tracing::error!(
+                        channel = %relay_name,
+                        failures = consecutive_failures,
+                        "Relay channel giving up after {} consecutive failures",
+                        consecutive_failures
+                    );
+                    break;
+                }
+
+                tracing::warn!(
+                    backoff_ms = backoff_ms,
+                    failures = consecutive_failures,
+                    "Relay SSE stream ended, reconnecting..."
+                );
+                tokio::time::sleep(std::time::Duration::from_millis(backoff_ms)).await;
+                backoff_ms = (backoff_ms * 2).min(backoff_max_ms);
+
+                // Try to reconnect
+                let token = stream_token.read().await.clone();
+                match client.connect_stream(&token, stream_timeout_secs).await {
+                    Ok((new_stream, new_parser)) => {
+                        tracing::info!("Relay SSE stream reconnected");
+                        current_stream = new_stream;
+                        // Abort old parser before replacing
+                        if let Some(old) = parser_handle.write().await.take() {
+                            old.abort();
+                        }
+                        *parser_handle.write().await = Some(new_parser);
+                    }
+                    Err(RelayError::TokenExpired) => {
+                        // Attempt token renewal
+                        tracing::info!("Relay stream token expired, renewing...");
+                        match client.renew_token(&instance_id, &user_id).await {
+                            Ok(new_token) => {
+                                *stream_token.write().await = new_token.clone();
+                                match client.connect_stream(&new_token, stream_timeout_secs).await {
+                                    Ok((new_stream, new_parser)) => {
+                                        tracing::info!(
+                                            "Relay SSE stream reconnected with new token"
+                                        );
+                                        current_stream = new_stream;
+                                        if let Some(old) = parser_handle.write().await.take() {
+                                            old.abort();
+                                        }
+                                        *parser_handle.write().await = Some(new_parser);
+                                    }
+                                    Err(e) => {
+                                        tracing::error!(
+                                            error = %e,
+                                            "Failed to reconnect after token renewal"
+                                        );
+                                    }
+                                }
+                            }
+                            Err(e) => {
+                                tracing::error!(
+                                    error = %e,
+                                    "Failed to renew relay stream token"
+                                );
+                            }
+                        }
+                    }
+                    Err(e) => {
+                        tracing::error!(error = %e, "Failed to reconnect relay SSE stream");
+                    }
+                }
+
+                // Check if the team is still valid (skip when team_id is unknown,
+                // e.g. when no DB store was available at activation time)
+                if !team_id.is_empty() {
+                    match client.list_connections(&instance_id).await {
+                        Ok(conns) => {
+                            let has_team =
+                                conns.iter().any(|c| c.team_id == team_id && c.connected);
+                            if !has_team {
+                                tracing::warn!(
+                                    team_id = %team_id,
+                                    "Team no longer connected, stopping relay channel"
+                                );
+                                return;
+                            }
+                        }
+                        Err(e) => {
+                            tracing::warn!(
+                                error = %e,
+                                "Could not verify team connection, will retry next iteration"
+                            );
+                        }
+                    }
+                }
+            }
+        });
+
+        *self.reconnect_handle.write().await = Some(handle);
+
+        let stream = tokio_stream::wrappers::ReceiverStream::new(rx);
+        Ok(Box::pin(stream))
+    }
+
+    async fn respond(
+        &self,
+        msg: &IncomingMessage,
+        response: OutgoingResponse,
+    ) -> Result<(), ChannelError> {
+        let channel_name = self.name().to_string();
+        let metadata = &msg.metadata;
+        let team_id = metadata
+            .get("team_id")
+            .and_then(|v| v.as_str())
+            .unwrap_or(&self.team_id);
+        let channel_id = metadata
+            .get("channel_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| ChannelError::SendFailed {
+                name: channel_name.clone(),
+                reason: "Missing channel_id in message metadata".to_string(),
+            })?;
+
+        // Determine thread_id from response or metadata
+        let thread_id = response
+            .thread_id
+            .as_deref()
+            .or_else(|| metadata.get("thread_id").and_then(|v| v.as_str()));
+
+        let (method, body) = self.build_send_body(channel_id, &response.content, thread_id);
+
+        self.proxy_send(team_id, &method, body)
+            .await
+            .map_err(|e| ChannelError::SendFailed {
+                name: channel_name,
+                reason: e.to_string(),
+            })?;
+
+        Ok(())
+    }
+
+    /// Status updates are not forwarded to messaging providers to avoid noise.
+    async fn send_status(
+        &self,
+        _status: StatusUpdate,
+        _metadata: &serde_json::Value,
+    ) -> Result<(), ChannelError> {
+        Ok(())
+    }
+
+    async fn broadcast(
+        &self,
+        target: &str,
+        response: OutgoingResponse,
+    ) -> Result<(), ChannelError> {
+        let channel_name = self.name().to_string();
+
+        // Determine thread_id from response or metadata
+        let thread_id = response
+            .thread_id
+            .as_deref()
+            .or_else(|| response.metadata.get("thread_ts").and_then(|v| v.as_str()));
+
+        let (method, body) = self.build_send_body(target, &response.content, thread_id);
+
+        self.proxy_send(&self.team_id, &method, body)
+            .await
+            .map_err(|e| ChannelError::SendFailed {
+                name: channel_name,
+                reason: e.to_string(),
+            })?;
+
+        Ok(())
+    }
+
+    async fn health_check(&self) -> Result<(), ChannelError> {
+        self.client
+            .list_connections(&self.instance_id)
+            .await
+            .map_err(|_| ChannelError::HealthCheckFailed {
+                name: self.name().to_string(),
+            })?;
+        Ok(())
+    }
+
+    fn conversation_context(&self, metadata: &serde_json::Value) -> HashMap<String, String> {
+        let mut ctx = HashMap::new();
+
+        if let Some(sender) = metadata.get("sender_name").and_then(|v| v.as_str()) {
+            ctx.insert("sender".to_string(), sender.to_string());
+        }
+        if let Some(sender_id) = metadata.get("sender_id").and_then(|v| v.as_str()) {
+            ctx.insert("sender_uuid".to_string(), sender_id.to_string());
+        }
+        if let Some(channel_id) = metadata.get("channel_id").and_then(|v| v.as_str()) {
+            ctx.insert("group".to_string(), channel_id.to_string());
+        }
+        ctx.insert("platform".to_string(), self.provider.as_str().to_string());
+
+        ctx
+    }
+
+    async fn shutdown(&self) -> Result<(), ChannelError> {
+        if let Some(handle) = self.reconnect_handle.write().await.take() {
+            handle.abort();
+        }
+        if let Some(handle) = self.parser_handle.write().await.take() {
+            handle.abort();
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn test_client() -> RelayClient {
+        RelayClient::new(
+            "http://localhost:3001".into(),
+            secrecy::SecretString::from("key".to_string()),
+            30,
+        )
+        .expect("client")
+    }
+
+    #[test]
+    fn relay_channel_name() {
+        let channel = RelayChannel::new(
+            test_client(),
+            "token".into(),
+            "T123".into(),
+            "inst1".into(),
+            "user1".into(),
+        );
+        assert_eq!(channel.name(), DEFAULT_RELAY_NAME);
+    }
+
+    #[test]
+    fn conversation_context_extracts_metadata() {
+        let channel = RelayChannel::new(
+            test_client(),
+            "token".into(),
+            "T123".into(),
+            "inst1".into(),
+            "user1".into(),
+        );
+
+        let metadata = serde_json::json!({
+            "sender_name": "bob",
+            "sender_id": "U123",
+            "channel_id": "C456",
+        });
+        let ctx = channel.conversation_context(&metadata);
+        assert_eq!(ctx.get("sender"), Some(&"bob".to_string()));
+        assert_eq!(ctx.get("sender_uuid"), Some(&"U123".to_string()));
+        assert_eq!(ctx.get("platform"), Some(&"slack".to_string()));
+    }
+
+    #[test]
+    fn metadata_shape_includes_event_type_and_sender_name() {
+        // Regression: metadata JSON must include event_type and sender_name
+        // for downstream routing (DM vs channel) and conversation_context().
+        let metadata = serde_json::json!({
+            "team_id": "T123",
+            "channel_id": "C456",
+            "sender_id": "U789",
+            "sender_name": "alice",
+            "event_type": "direct_message",
+            "thread_id": null,
+            "provider": "slack",
+        });
+        // event_type must be present for DM-vs-channel routing
+        assert_eq!(
+            metadata.get("event_type").and_then(|v| v.as_str()),
+            Some("direct_message")
+        );
+        // sender_name must be present for conversation_context
+        assert_eq!(
+            metadata.get("sender_name").and_then(|v| v.as_str()),
+            Some("alice")
+        );
+    }
+
+    #[test]
+    fn with_timeouts_sets_values() {
+        let channel = RelayChannel::new(
+            test_client(),
+            "token".into(),
+            "T123".into(),
+            "inst1".into(),
+            "user1".into(),
+        )
+        .with_timeouts(43200, 2000, 120000);
+
+        assert_eq!(channel.stream_timeout_secs, 43200);
+        assert_eq!(channel.backoff_initial_ms, 2000);
+        assert_eq!(channel.backoff_max_ms, 120000);
+    }
+
+    #[test]
+    fn build_send_body_slack() {
+        let channel = RelayChannel::new(
+            test_client(),
+            "token".into(),
+            "T123".into(),
+            "inst1".into(),
+            "user1".into(),
+        );
+        let (method, body) = channel.build_send_body("C456", "hello", Some("1234567.890"));
+        assert_eq!(method, "chat.postMessage");
+        assert_eq!(body["channel"], "C456");
+        assert_eq!(body["text"], "hello");
+        assert_eq!(body["thread_ts"], "1234567.890");
+    }
+
+    #[test]
+    fn parser_handle_is_shared_arc() {
+        let channel = RelayChannel::new(
+            test_client(),
+            "token".into(),
+            "T123".into(),
+            "inst1".into(),
+            "user1".into(),
+        );
+        // parser_handle should be an Arc — cloning should give a second reference
+        let handle_clone = Arc::clone(&channel.parser_handle);
+        // Both point to the same allocation
+        assert!(Arc::ptr_eq(&channel.parser_handle, &handle_clone));
+    }
+
+    #[test]
+    fn with_max_failures_sets_value() {
+        let channel = RelayChannel::new(
+            test_client(),
+            "token".into(),
+            "T123".into(),
+            "inst1".into(),
+            "user1".into(),
+        )
+        .with_max_failures(10);
+
+        assert_eq!(channel.max_consecutive_failures, 10);
+    }
+
+    #[test]
+    fn default_max_failures_is_50() {
+        let channel = RelayChannel::new(
+            test_client(),
+            "token".into(),
+            "T123".into(),
+            "inst1".into(),
+            "user1".into(),
+        );
+        assert_eq!(channel.max_consecutive_failures, 50);
+    }
+
+    #[test]
+    fn empty_team_id_accepted_at_construction() {
+        // Regression: empty team_id (when no DB store is available) must not
+        // prevent channel construction or cause immediate shutdown.
+        let channel = RelayChannel::new(
+            test_client(),
+            "token".into(),
+            String::new(), // empty team_id
+            "inst1".into(),
+            "user1".into(),
+        );
+        assert_eq!(channel.team_id, "");
+        // The reconnect loop now skips team validation when team_id is empty,
+        // so the channel remains alive.
+    }
+}

src/channels/relay/client.rs

@@ -0,0 +1,549 @@
+//! HTTP client for the channel-relay service.
+//!
+//! Wraps reqwest for all channel-relay API calls: OAuth initiation,
+//! SSE streaming, token renewal, and Slack API proxy.
+
+use std::pin::Pin;
+use std::task::{Context, Poll};
+
+use futures::Stream;
+use secrecy::{ExposeSecret, SecretString};
+use serde::{Deserialize, Serialize};
+use tokio::sync::mpsc;
+
+/// Known relay event types.
+pub mod event_types {
+    pub const MESSAGE: &str = "message";
+    pub const DIRECT_MESSAGE: &str = "direct_message";
+    pub const MENTION: &str = "mention";
+}
+
+/// A parsed SSE event from the channel-relay stream.
+///
+/// Field names match the channel-relay `ChannelEvent` struct exactly.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ChannelEvent {
+    /// Unique event ID.
+    #[serde(default)]
+    pub id: String,
+    /// Event type enum from channel-relay (e.g., "direct_message", "message", "mention").
+    pub event_type: String,
+    /// Provider (e.g., "slack").
+    #[serde(default)]
+    pub provider: String,
+    /// Team/workspace ID (called `provider_scope` in channel-relay).
+    #[serde(alias = "team_id", default)]
+    pub provider_scope: String,
+    /// Channel or DM conversation ID.
+    #[serde(default)]
+    pub channel_id: String,
+    /// Sender user ID.
+    #[serde(default)]
+    pub sender_id: String,
+    /// Sender display name.
+    #[serde(default)]
+    pub sender_name: Option<String>,
+    /// Message text content (called `content` in channel-relay).
+    #[serde(alias = "text", default)]
+    pub content: Option<String>,
+    /// Thread ID (for threaded replies, called `thread_id` in channel-relay).
+    #[serde(alias = "thread_ts", default)]
+    pub thread_id: Option<String>,
+    /// Full raw event data.
+    #[serde(default)]
+    pub raw: serde_json::Value,
+    /// Event timestamp (ISO 8601 from channel-relay).
+    #[serde(default)]
+    pub timestamp: Option<String>,
+}
+
+impl ChannelEvent {
+    /// Get the team_id (provider_scope).
+    pub fn team_id(&self) -> &str {
+        &self.provider_scope
+    }
+
+    /// Get the message text content.
+    pub fn text(&self) -> &str {
+        self.content.as_deref().unwrap_or("")
+    }
+
+    /// Get the sender name or fallback to sender_id.
+    pub fn display_name(&self) -> &str {
+        self.sender_name.as_deref().unwrap_or(&self.sender_id)
+    }
+
+    /// Check if this is a message-like event that should be forwarded to the agent.
+    pub fn is_message(&self) -> bool {
+        matches!(
+            self.event_type.as_str(),
+            event_types::MESSAGE | event_types::DIRECT_MESSAGE | event_types::MENTION
+        )
+    }
+}
+
+/// Connection info returned by list_connections.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Connection {
+    pub provider: String,
+    pub team_id: String,
+    pub team_name: Option<String>,
+    pub connected: bool,
+}
+
+/// HTTP client for the channel-relay service.
+#[derive(Clone)]
+pub struct RelayClient {
+    http: reqwest::Client,
+    base_url: String,
+    api_key: SecretString,
+}
+
+impl RelayClient {
+    /// Create a new relay client.
+    pub fn new(
+        base_url: String,
+        api_key: SecretString,
+        request_timeout_secs: u64,
+    ) -> Result<Self, RelayError> {
+        let http = reqwest::Client::builder()
+            .timeout(std::time::Duration::from_secs(request_timeout_secs))
+            .redirect(reqwest::redirect::Policy::none())
+            .build()
+            .map_err(|e| RelayError::Network(format!("Failed to build HTTP client: {e}")))?;
+
+        Ok(Self {
+            http,
+            base_url: base_url.trim_end_matches('/').to_string(),
+            api_key,
+        })
+    }
+
+    /// Initiate Slack OAuth flow via channel-relay.
+    ///
+    /// Calls `GET /oauth/slack/auth` with `redirect(Policy::none())` and
+    /// returns the `Location` header (Slack OAuth URL) without following it.
+    pub async fn initiate_oauth(
+        &self,
+        instance_id: &str,
+        user_id: &str,
+        callback_url: &str,
+    ) -> Result<String, RelayError> {
+        let resp = self
+            .http
+            .get(format!("{}/oauth/slack/auth", self.base_url))
+            .header("X-API-Key", self.api_key.expose_secret())
+            .query(&[
+                ("instance_id", instance_id),
+                ("user_id", user_id),
+                ("callback", callback_url),
+            ])
+            .send()
+            .await
+            .map_err(|e| RelayError::Network(e.to_string()))?;
+
+        let status = resp.status();
+        if status.is_redirection() {
+            let location = resp
+                .headers()
+                .get(reqwest::header::LOCATION)
+                .and_then(|v| v.to_str().ok())
+                .map(|s| s.to_string())
+                .ok_or_else(|| {
+                    RelayError::Protocol("Redirect response missing Location header".to_string())
+                })?;
+            Ok(location)
+        } else if status.is_success() {
+            // Some relay implementations return the URL in JSON body instead
+            let body: serde_json::Value = resp
+                .json()
+                .await
+                .map_err(|e| RelayError::Protocol(e.to_string()))?;
+            body.get("auth_url")
+                .or_else(|| body.get("url"))
+                .and_then(|v| v.as_str())
+                .map(|s| s.to_string())
+                .ok_or_else(|| RelayError::Protocol("Response missing auth_url field".to_string()))
+        } else {
+            let body = resp.text().await.unwrap_or_default();
+            Err(RelayError::Api {
+                status: status.as_u16(),
+                message: body,
+            })
+        }
+    }
+
+    /// Connect to the SSE event stream.
+    ///
+    /// Returns a stream of parsed `ChannelEvent`s and the `JoinHandle` of the
+    /// background SSE parser task. The caller is responsible for reconnection
+    /// logic on stream end/error and for aborting the handle on shutdown.
+    pub async fn connect_stream(
+        &self,
+        stream_token: &str,
+        stream_timeout_secs: u64,
+    ) -> Result<(ChannelEventStream, tokio::task::JoinHandle<()>), RelayError> {
+        let resp = self
+            .http
+            .get(format!("{}/stream", self.base_url))
+            .query(&[("token", stream_token)])
+            .timeout(std::time::Duration::from_secs(stream_timeout_secs))
+            .send()
+            .await
+            .map_err(|e| RelayError::Network(e.to_string()))?;
+
+        let status = resp.status();
+        if status == reqwest::StatusCode::UNAUTHORIZED {
+            return Err(RelayError::TokenExpired);
+        }
+        if !status.is_success() {
+            let body = resp.text().await.unwrap_or_default();
+            return Err(RelayError::Api {
+                status: status.as_u16(),
+                message: body,
+            });
+        }
+
+        // Spawn a background task that reads the SSE stream and sends parsed events
+        let (tx, rx) = mpsc::channel(64);
+        let byte_stream = resp.bytes_stream();
+        let handle = tokio::spawn(parse_sse_stream(byte_stream, tx));
+
+        Ok((ChannelEventStream { rx }, handle))
+    }
+
+    /// Renew an expired stream token.
+    ///
+    /// Calls `POST /stream/renew` with API key auth, returns a new stream token.
+    pub async fn renew_token(
+        &self,
+        instance_id: &str,
+        user_id: &str,
+    ) -> Result<String, RelayError> {
+        let resp = self
+            .http
+            .post(format!("{}/stream/renew", self.base_url))
+            .header("X-API-Key", self.api_key.expose_secret())
+            .json(&serde_json::json!({
+                "instance_id": instance_id,
+                "user_id": user_id,
+            }))
+            .send()
+            .await
+            .map_err(|e| RelayError::Network(e.to_string()))?;
+
+        let status = resp.status();
+        if !status.is_success() {
+            let body = resp.text().await.unwrap_or_default();
+            return Err(RelayError::Api {
+                status: status.as_u16(),
+                message: body,
+            });
+        }
+
+        let body: serde_json::Value = resp
+            .json()
+            .await
+            .map_err(|e| RelayError::Protocol(e.to_string()))?;
+        body.get("stream_token")
+            .or_else(|| body.get("token"))
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string())
+            .ok_or_else(|| RelayError::Protocol("Response missing stream_token field".to_string()))
+    }
+
+    /// Proxy an API call through channel-relay for any provider.
+    ///
+    /// Calls `POST /proxy/{provider}/{method}?team_id=X&instance_id=Y` with the given JSON body.
+    pub async fn proxy_provider(
+        &self,
+        provider: &str,
+        team_id: &str,
+        method: &str,
+        body: serde_json::Value,
+        instance_id: Option<&str>,
+    ) -> Result<serde_json::Value, RelayError> {
+        let mut query: Vec<(&str, &str)> = vec![("team_id", team_id)];
+        if let Some(iid) = instance_id {
+            query.push(("instance_id", iid));
+        }
+        let resp = self
+            .http
+            .post(format!("{}/proxy/{}/{}", self.base_url, provider, method))
+            .header("X-API-Key", self.api_key.expose_secret())
+            .query(&query)
+            .json(&body)
+            .send()
+            .await
+            .map_err(|e| RelayError::Network(e.to_string()))?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(RelayError::Api {
+                status,
+                message: body,
+            });
+        }
+
+        resp.json()
+            .await
+            .map_err(|e| RelayError::Protocol(e.to_string()))
+    }
+
+    /// List active connections for an instance.
+    pub async fn list_connections(&self, instance_id: &str) -> Result<Vec<Connection>, RelayError> {
+        let resp = self
+            .http
+            .get(format!("{}/connections", self.base_url))
+            .header("X-API-Key", self.api_key.expose_secret())
+            .query(&[("instance_id", instance_id)])
+            .send()
+            .await
+            .map_err(|e| RelayError::Network(e.to_string()))?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(RelayError::Api {
+                status,
+                message: body,
+            });
+        }
+
+        resp.json()
+            .await
+            .map_err(|e| RelayError::Protocol(e.to_string()))
+    }
+}
+
+/// Async stream of parsed channel events from SSE.
+pub struct ChannelEventStream {
+    rx: mpsc::Receiver<ChannelEvent>,
+}
+
+impl Stream for ChannelEventStream {
+    type Item = ChannelEvent;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        self.rx.poll_recv(cx)
+    }
+}
+
+/// Parse SSE format from a reqwest bytes stream.
+///
+/// SSE format:
+/// ```text
+/// event: message
+/// data: {"key": "value"}
+///
+/// ```
+/// Blank line terminates an event.
+async fn parse_sse_stream(
+    byte_stream: impl futures::Stream<Item = Result<bytes::Bytes, reqwest::Error>> + Send + 'static,
+    tx: mpsc::Sender<ChannelEvent>,
+) {
+    use futures::StreamExt;
+
+    let mut buffer = Vec::<u8>::new();
+    let mut event_type = String::new();
+    let mut data_lines = Vec::new();
+
+    let mut byte_stream = std::pin::pin!(byte_stream);
+    while let Some(chunk_result) = byte_stream.next().await {
+        let chunk = match chunk_result {
+            Ok(c) => c,
+            Err(e) => {
+                tracing::debug!(error = %e, "SSE stream chunk error");
+                break;
+            }
+        };
+
+        buffer.extend_from_slice(&chunk);
+
+        // Process complete lines (decode UTF-8 only on full lines to avoid
+        // corruption when multi-byte characters span chunk boundaries)
+        while let Some(newline_pos) = buffer.iter().position(|&b| b == b'\n') {
+            let line = String::from_utf8_lossy(&buffer[..newline_pos])
+                .trim_end_matches('\r')
+                .to_string();
+            buffer.drain(..=newline_pos);
+
+            if line.is_empty() {
+                // Blank line = end of event
+                if !data_lines.is_empty() {
+                    let data = data_lines.join("\n");
+                    if let Ok(mut event) = serde_json::from_str::<ChannelEvent>(&data) {
+                        if event.event_type.is_empty() && !event_type.is_empty() {
+                            event.event_type = event_type.clone();
+                        }
+                        if tx.send(event).await.is_err() {
+                            return; // receiver dropped
+                        }
+                    } else {
+                        tracing::debug!(
+                            event_type = %event_type,
+                            data_len = data.len(),
+                            "Failed to parse SSE event data as ChannelEvent"
+                        );
+                    }
+                }
+                event_type.clear();
+                data_lines.clear();
+            } else if let Some(value) = line.strip_prefix("event:") {
+                event_type = value.trim().to_string();
+            } else if let Some(value) = line.strip_prefix("data:") {
+                data_lines.push(value.trim().to_string());
+            }
+            // Ignore other fields (id:, retry:, comments)
+        }
+    }
+
+    tracing::debug!("SSE stream ended");
+}
+
+/// Errors from relay client operations.
+#[derive(Debug, thiserror::Error)]
+pub enum RelayError {
+    #[error("Network error: {0}")]
+    Network(String),
+
+    #[error("API error (HTTP {status}): {message}")]
+    Api { status: u16, message: String },
+
+    #[error("Protocol error: {0}")]
+    Protocol(String),
+
+    #[error("Stream token expired")]
+    TokenExpired,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn channel_event_deserialize_minimal() {
+        let json = r#"{"event_type": "message", "content": "hello"}"#;
+        let event: ChannelEvent = serde_json::from_str(json).expect("parse failed");
+        assert_eq!(event.event_type, "message");
+        assert_eq!(event.text(), "hello");
+        assert!(event.provider_scope.is_empty());
+    }
+
+    #[test]
+    fn channel_event_deserialize_relay_format() {
+        // Matches the actual channel-relay ChannelEvent serialization format.
+        let json = r#"{
+            "id": "evt_123",
+            "event_type": "direct_message",
+            "provider": "slack",
+            "provider_scope": "T123",
+            "channel_id": "D456",
+            "sender_id": "U789",
+            "sender_name": "bob",
+            "content": "hi there",
+            "thread_id": "1234567890.123456",
+            "raw": {},
+            "timestamp": "2026-03-09T21:00:00Z"
+        }"#;
+        let event: ChannelEvent = serde_json::from_str(json).expect("parse failed");
+        assert_eq!(event.provider, "slack");
+        assert_eq!(event.team_id(), "T123");
+        assert_eq!(event.display_name(), "bob");
+        assert_eq!(event.thread_id, Some("1234567890.123456".to_string()));
+        assert!(event.is_message());
+    }
+
+    #[test]
+    fn channel_event_is_message() {
+        let make = |et: &str| ChannelEvent {
+            id: String::new(),
+            event_type: et.to_string(),
+            provider: String::new(),
+            provider_scope: String::new(),
+            channel_id: String::new(),
+            sender_id: String::new(),
+            sender_name: None,
+            content: None,
+            thread_id: None,
+            raw: serde_json::Value::Null,
+            timestamp: None,
+        };
+        assert!(make("message").is_message());
+        assert!(make("direct_message").is_message());
+        assert!(make("mention").is_message());
+        assert!(!make("reaction").is_message());
+    }
+
+    #[test]
+    fn connection_deserialize() {
+        let json = r#"{"provider": "slack", "team_id": "T123", "team_name": "My Team", "connected": true}"#;
+        let conn: Connection = serde_json::from_str(json).expect("parse failed");
+        assert_eq!(conn.provider, "slack");
+        assert!(conn.connected);
+    }
+
+    #[test]
+    fn relay_error_display() {
+        let err = RelayError::Network("timeout".into());
+        assert_eq!(err.to_string(), "Network error: timeout");
+
+        let err = RelayError::Api {
+            status: 401,
+            message: "unauthorized".into(),
+        };
+        assert_eq!(err.to_string(), "API error (HTTP 401): unauthorized");
+
+        let err = RelayError::TokenExpired;
+        assert_eq!(err.to_string(), "Stream token expired");
+    }
+
+    #[test]
+    fn event_type_constants_match_is_message() {
+        let make = |et: &str| ChannelEvent {
+            id: String::new(),
+            event_type: et.to_string(),
+            provider: String::new(),
+            provider_scope: String::new(),
+            channel_id: String::new(),
+            sender_id: String::new(),
+            sender_name: None,
+            content: None,
+            thread_id: None,
+            raw: serde_json::Value::Null,
+            timestamp: None,
+        };
+        assert!(make(event_types::MESSAGE).is_message());
+        assert!(make(event_types::DIRECT_MESSAGE).is_message());
+        assert!(make(event_types::MENTION).is_message());
+    }
+
+    #[tokio::test]
+    async fn parse_sse_handles_multibyte_utf8_across_chunks() {
+        // The crab emoji (🦀) is 4 bytes: [0xF0, 0x9F, 0xA6, 0x80].
+        // Split it across two chunks to verify no U+FFFD corruption.
+        let event_json = r#"{"event_type":"message","content":"hello 🦀 world","provider_scope":"T1","channel_id":"C1","sender_id":"U1"}"#;
+        let full = format!("event: message\ndata: {}\n\n", event_json);
+        let bytes = full.as_bytes();
+
+        // Find the crab emoji and split mid-character
+        let crab_pos = bytes
+            .windows(4)
+            .position(|w| w == [0xF0, 0x9F, 0xA6, 0x80])
+            .expect("crab emoji not found");
+        let split_at = crab_pos + 2; // split in the middle of the 4-byte emoji
+
+        let chunk1 = bytes::Bytes::copy_from_slice(&bytes[..split_at]);
+        let chunk2 = bytes::Bytes::copy_from_slice(&bytes[split_at..]);
+
+        let chunks: Vec<Result<bytes::Bytes, reqwest::Error>> = vec![Ok(chunk1), Ok(chunk2)];
+        let stream = futures::stream::iter(chunks);
+
+        let (tx, mut rx) = mpsc::channel(8);
+        parse_sse_stream(stream, tx).await;
+
+        let event = rx.recv().await.expect("should receive event");
+        assert_eq!(event.text(), "hello 🦀 world");
+    }
+}

src/channels/relay/mod.rs

@@ -0,0 +1,12 @@
+//! Channel-relay integration for connecting to external messaging platforms
+//! (Slack) via the channel-relay service.
+//!
+//! The relay service handles OAuth, credential storage, webhook ingestion,
+//! and SSE event streaming. IronClaw consumes the SSE stream and sends
+//! messages via the relay's proxy API.
+
+pub mod channel;
+pub mod client;
+
+pub use channel::{DEFAULT_RELAY_NAME, RelayChannel};
+pub use client::RelayClient;

src/channels/wasm/setup.rs

@@ -218,25 +218,31 @@ async fn register_channel(
     }
 
     // Inject credentials from secrets store / environment.
-    if let Some(secrets) = secrets_store {
-        match inject_channel_credentials(&channel_arc, secrets.as_ref(), &channel_name).await {
-            Ok(count) => {
-                if count > 0 {
-                    tracing::info!(
-                        channel = %channel_name,
-                        credentials_injected = count,
-                        "Channel credentials injected"
-                    );
-                }
-            }
-            Err(e) => {
-                tracing::error!(
+    match inject_channel_credentials(
+        &channel_arc,
+        secrets_store
+            .as_ref()
+            .map(|s| s.as_ref() as &dyn SecretsStore),
+        &channel_name,
+    )
+    .await
+    {
+        Ok(count) => {
+            if count > 0 {
+                tracing::info!(
                     channel = %channel_name,
-                    error = %e,
-                    "Failed to inject channel credentials"
+                    credentials_injected = count,
+                    "Channel credentials injected"
                 );
             }
         }
+        Err(e) => {
+            tracing::error!(
+                channel = %channel_name,
+                error = %e,
+                "Failed to inject channel credentials"
+            );
+        }
     }
 
     (channel_name, Box::new(SharedWasmChannel::new(channel_arc)))
@@ -247,58 +253,70 @@ async fn register_channel(
 /// Looks for secrets matching the pattern `{channel_name}_*` and injects them
 /// as credential placeholders (e.g., `telegram_bot_token` -> `{TELEGRAM_BOT_TOKEN}`).
 ///
-/// Falls back to environment variables with the uppercase name if not found
-/// in the secrets store (e.g., `TELEGRAM_BOT_TOKEN`).
+/// Falls back to environment variables starting with the uppercase channel name
+/// prefix (e.g., `TELEGRAM_` for channel `telegram`) for missing credentials.
+///
+/// Returns the number of credentials injected.
 pub async fn inject_channel_credentials(
     channel: &Arc<WasmChannel>,
-    secrets: &dyn SecretsStore,
+    secrets: Option<&dyn SecretsStore>,
     channel_name: &str,
 ) -> anyhow::Result<usize> {
-    let all_secrets = secrets
-        .list("default")
-        .await
-        .map_err(|e| anyhow::anyhow!("Failed to list secrets: {}", e))?;
+    if channel_name.trim().is_empty() {
+        return Ok(0);
+    }
 
-    let prefix = format!("{}_", channel_name);
     let mut count = 0;
     let mut injected_placeholders = HashSet::new();
 
-    for secret_meta in all_secrets {
-        if !secret_meta.name.starts_with(&prefix) {
-            continue;
-        }
+    // 1. Try injecting from persistent secrets store if available
+    if let Some(secrets) = secrets {
+        let all_secrets = secrets
+            .list("default")
+            .await
+            .map_err(|e| anyhow::anyhow!("Failed to list secrets: {}", e))?;
 
-        let decrypted = match secrets.get_decrypted("default", &secret_meta.name).await {
-            Ok(d) => d,
-            Err(e) => {
-                tracing::warn!(
-                    secret = %secret_meta.name,
-                    error = %e,
-                    "Failed to decrypt secret for channel credential injection"
-                );
+        let prefix = format!("{}_", channel_name.to_ascii_lowercase());
+
+        for secret_meta in all_secrets {
+            if !secret_meta.name.to_ascii_lowercase().starts_with(&prefix) {
                 continue;
             }
-        };
 
-        let placeholder = secret_meta.name.to_uppercase();
+            let decrypted = match secrets.get_decrypted("default", &secret_meta.name).await {
+                Ok(d) => d,
+                Err(e) => {
+                    tracing::warn!(
+                        secret = %secret_meta.name,
+                        error = %e,
+                        "Failed to decrypt secret for channel credential injection"
+                    );
+                    continue;
+                }
+            };
 
-        tracing::debug!(
-            channel = %channel_name,
-            secret = %secret_meta.name,
-            placeholder = %placeholder,
-            "Injecting credential"
-        );
+            let placeholder = secret_meta.name.to_uppercase();
 
-        channel
-            .set_credential(&placeholder, decrypted.expose().to_string())
-            .await;
-        injected_placeholders.insert(placeholder);
-        count += 1;
+            tracing::debug!(
+                channel = %channel_name,
+                secret = %secret_meta.name,
+                placeholder = %placeholder,
+                "Injecting credential"
+            );
+
+            channel
+                .set_credential(&placeholder, decrypted.expose().to_string())
+                .await;
+            injected_placeholders.insert(placeholder);
+            count += 1;
+        }
     }
 
-    // Fall back to environment variables for required secrets not found in the store.
-    // This allows channels to work when configured via env vars (e.g., TELEGRAM_BOT_TOKEN)
-    // without requiring the setup wizard to have run.
+    // 2. Fall back to environment variables for credentials not in the secrets store.
+    // Only env vars starting with the channel's uppercase prefix are allowed
+    // (e.g., TELEGRAM_ for channel "telegram") to prevent reading unrelated host
+    // credentials like AWS_SECRET_ACCESS_KEY.
+    let prefix = format!("{}_", channel_name.to_ascii_uppercase());
     let caps = channel.capabilities();
     if let Some(ref http_cap) = caps.tool_capabilities.http {
         for cred_mapping in http_cap.credentials.values() {
@@ -306,6 +324,14 @@ pub async fn inject_channel_credentials(
             if injected_placeholders.contains(&placeholder) {
                 continue;
             }
+            if !placeholder.starts_with(&prefix) {
+                tracing::warn!(
+                    channel = %channel_name,
+                    placeholder = %placeholder,
+                    "Ignoring non-prefixed credential placeholder in environment fallback"
+                );
+                continue;
+            }
             if let Ok(env_value) = std::env::var(&placeholder)
                 && !env_value.is_empty()
             {

src/channels/wasm/signature.rs

@@ -106,6 +106,34 @@ pub fn verify_slack_signature(
         .into()
 }
 
+/// Verify raw-body HMAC-SHA256 signature with a configurable prefix.
+///
+/// Computes `HMAC-SHA256(secret, body)` and compares against
+/// `prefix + hex_digest` in constant time.
+pub fn verify_hmac_sha256_prefixed(
+    secret: &str,
+    body: &[u8],
+    signature_header: &str,
+    prefix: &str,
+) -> bool {
+    use hmac::{Hmac, Mac};
+    use sha2::Sha256;
+    use subtle::ConstantTimeEq;
+
+    let mut mac = match Hmac::<Sha256>::new_from_slice(secret.as_bytes()) {
+        Ok(m) => m,
+        Err(_) => return false,
+    };
+    mac.update(body);
+    let computed = mac.finalize().into_bytes();
+    let computed_hex = hex::encode(computed);
+    let expected = format!("{prefix}{computed_hex}");
+    expected
+        .as_bytes()
+        .ct_eq(signature_header.as_bytes())
+        .into()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -498,6 +526,24 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_hmac_sha256_prefixed_valid() {
+        let secret = "github-secret";
+        let body = br#"{"action":"opened"}"#;
+        use hmac::{Hmac, Mac};
+        use sha2::Sha256;
+        let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes()).expect("hmac key");
+        mac.update(body);
+        let sig = format!("sha256={}", hex::encode(mac.finalize().into_bytes()));
+        assert!(verify_hmac_sha256_prefixed(secret, body, &sig, "sha256="));
+        assert!(!verify_hmac_sha256_prefixed(
+            secret,
+            body,
+            "sha256=deadbeef",
+            "sha256="
+        ));
+    }
+
     #[test]
     fn test_slack_stale_timestamp_rejected() {
         let signing_secret = "my-signing-secret";

src/channels/wasm/wrapper.rs

@@ -3059,6 +3059,7 @@ mod tests {
     };
     use crate::channels::wasm::wrapper::{HttpResponse, WasmChannel};
     use crate::pairing::PairingStore;
+    use crate::testing::credentials::TEST_TELEGRAM_BOT_TOKEN;
     use crate::tools::wasm::ResourceLimits;
 
     fn create_test_channel() -> WasmChannel {
@@ -4009,7 +4010,7 @@ mod tests {
         let mut creds = std::collections::HashMap::new();
         creds.insert(
             "TELEGRAM_BOT_TOKEN".to_string(),
-            "8218490433:AAEZeUxwqZ5OO3mOCXv7fKvpdhDgsmBBNis".to_string(),
+            TEST_TELEGRAM_BOT_TOKEN.to_string(),
         );
         creds.insert("OTHER_SECRET".to_string(), "s3cret".to_string());
 
@@ -4022,13 +4023,15 @@ mod tests {
             Arc::new(PairingStore::new()),
         );
 
-        let error = "HTTP request failed: error sending request for url \
-            (https://api.telegram.org/bot8218490433:AAEZeUxwqZ5OO3mOCXv7fKvpdhDgsmBBNis/getUpdates)";
+        let error = format!(
+            "HTTP request failed: error sending request for url \
+            (https://api.telegram.org/bot{TEST_TELEGRAM_BOT_TOKEN}/getUpdates)"
+        );
 
-        let redacted = store.redact_credentials(error);
+        let redacted = store.redact_credentials(&error);
 
         assert!(
-            !redacted.contains("8218490433:AAEZeUxwqZ5OO3mOCXv7fKvpdhDgsmBBNis"),
+            !redacted.contains(TEST_TELEGRAM_BOT_TOKEN),
             "credential value should be redacted"
         );
         assert!(

src/channels/web/auth.rs

@@ -83,14 +83,15 @@ pub async fn auth_middleware(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::testing::credentials::{TEST_AUTH_SECRET_TOKEN, TEST_BEARER_TOKEN};
 
     #[test]
     fn test_auth_state_clone() {
         let state = AuthState {
-            token: "test-token".to_string(),
+            token: TEST_BEARER_TOKEN.to_string(),
         };
         let cloned = state.clone();
-        assert_eq!(cloned.token, "test-token");
+        assert_eq!(cloned.token, TEST_BEARER_TOKEN);
     }
 
     use axum::Router;
@@ -120,10 +121,10 @@ mod tests {
 
     #[tokio::test]
     async fn test_valid_bearer_token_passes() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .uri("/api/chat/events")
-            .header("Authorization", "Bearer secret-token")
+            .header("Authorization", format!("Bearer {TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();
@@ -132,7 +133,7 @@ mod tests {
 
     #[tokio::test]
     async fn test_invalid_bearer_token_rejected() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .uri("/api/chat/events")
             .header("Authorization", "Bearer wrong-token")
@@ -144,9 +145,9 @@ mod tests {
 
     #[tokio::test]
     async fn test_query_token_allowed_for_chat_events() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
-            .uri("/api/chat/events?token=secret-token")
+            .uri(format!("/api/chat/events?token={TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();
@@ -155,9 +156,9 @@ mod tests {
 
     #[tokio::test]
     async fn test_query_token_allowed_for_logs_events() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
-            .uri("/api/logs/events?token=secret-token")
+            .uri(format!("/api/logs/events?token={TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();
@@ -166,9 +167,9 @@ mod tests {
 
     #[tokio::test]
     async fn test_query_token_allowed_for_ws_upgrade() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
-            .uri("/api/chat/ws?token=secret-token")
+            .uri(format!("/api/chat/ws?token={TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();
@@ -202,9 +203,9 @@ mod tests {
 
     #[tokio::test]
     async fn test_query_token_rejected_for_non_sse_get() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
-            .uri("/api/chat/history?token=secret-token")
+            .uri(format!("/api/chat/history?token={TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();
@@ -213,10 +214,10 @@ mod tests {
 
     #[tokio::test]
     async fn test_query_token_rejected_for_post() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .method(Method::POST)
-            .uri("/api/chat/send?token=secret-token")
+            .uri(format!("/api/chat/send?token={TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();
@@ -225,7 +226,7 @@ mod tests {
 
     #[tokio::test]
     async fn test_query_token_invalid_rejected() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .uri("/api/chat/events?token=wrong-token")
             .body(Body::empty())
@@ -236,7 +237,7 @@ mod tests {
 
     #[tokio::test]
     async fn test_no_auth_at_all_rejected() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .uri("/api/chat/events")
             .body(Body::empty())
@@ -247,11 +248,11 @@ mod tests {
 
     #[tokio::test]
     async fn test_bearer_header_works_for_post() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .method(Method::POST)
             .uri("/api/chat/send")
-            .header("Authorization", "Bearer secret-token")
+            .header("Authorization", format!("Bearer {TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();
@@ -260,10 +261,10 @@ mod tests {
 
     #[tokio::test]
     async fn test_bearer_prefix_case_insensitive() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .uri("/api/chat/events")
-            .header("Authorization", "bearer secret-token")
+            .header("Authorization", format!("bearer {TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();
@@ -272,10 +273,10 @@ mod tests {
 
     #[tokio::test]
     async fn test_bearer_prefix_mixed_case() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .uri("/api/chat/events")
-            .header("Authorization", "BEARER secret-token")
+            .header("Authorization", format!("BEARER {TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();
@@ -284,7 +285,7 @@ mod tests {
 
     #[tokio::test]
     async fn test_empty_bearer_token_rejected() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .uri("/api/chat/events")
             .header("Authorization", "Bearer ")
@@ -296,10 +297,10 @@ mod tests {
 
     #[tokio::test]
     async fn test_token_with_whitespace_rejected() {
-        let app = test_app("secret-token");
+        let app = test_app(TEST_AUTH_SECRET_TOKEN);
         let req = Request::builder()
             .uri("/api/chat/events")
-            .header("Authorization", "Bearer  secret-token")
+            .header("Authorization", format!("Bearer  {TEST_AUTH_SECRET_TOKEN}"))
             .body(Body::empty())
             .unwrap();
         let resp = app.oneshot(req).await.unwrap();

src/channels/web/handlers/chat.rs

@@ -35,6 +35,7 @@ pub async fn chat_send_handler(
     }
 
     let msg_id = msg.id;
+    let thread_id = msg.thread_id.clone();
 
     let tx_guard = state.msg_tx.read().await;
     let tx = tx_guard.as_ref().ok_or((
@@ -49,6 +50,13 @@ pub async fn chat_send_handler(
         )
     })?;
 
+    tracing::debug!(
+        message_id = %msg_id,
+        thread_id = ?thread_id,
+        content_len = req.content.len(),
+        "Message queued to agent loop"
+    );
+
     Ok((
         StatusCode::ACCEPTED,
         Json(SendMessageResponse {
@@ -137,49 +145,33 @@ pub async fn chat_auth_token_handler(
         "Extension manager not available".to_string(),
     ))?;
 
-    let result = ext_mgr
-        .auth(&req.extension_name, Some(&req.token))
+    match ext_mgr
+        .configure_token(&req.extension_name, &req.token)
         .await
-        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+    {
+        Ok(result) => {
+            clear_auth_mode(&state).await;
 
-    if result.is_authenticated() {
-        // Auto-activate so tools are available immediately
-        let msg = match ext_mgr.activate(&req.extension_name).await {
-            Ok(r) => format!(
-                "{} authenticated ({} tools loaded)",
-                req.extension_name,
-                r.tools_loaded.len()
-            ),
-            Err(e) => format!(
-                "{} authenticated but activation failed: {}",
-                req.extension_name, e
-            ),
-        };
+            state.sse.broadcast(SseEvent::AuthCompleted {
+                extension_name: req.extension_name.clone(),
+                success: true,
+                message: result.message.clone(),
+            });
 
-        // Clear auth mode on the active thread
-        clear_auth_mode(&state).await;
-
-        state.sse.broadcast(SseEvent::AuthCompleted {
-            extension_name: req.extension_name,
-            success: true,
-            message: msg.clone(),
-        });
-
-        Ok(Json(ActionResponse::ok(msg)))
-    } else {
-        // Re-emit auth_required for retry
-        state.sse.broadcast(SseEvent::AuthRequired {
-            extension_name: req.extension_name.clone(),
-            instructions: result.instructions().map(String::from),
-            auth_url: result.auth_url().map(String::from),
-            setup_url: result.setup_url().map(String::from),
-        });
-        Ok(Json(ActionResponse::fail(
-            result
-                .instructions()
-                .map(String::from)
-                .unwrap_or_else(|| "Invalid token".to_string()),
-        )))
+            Ok(Json(ActionResponse::ok(result.message)))
+        }
+        Err(e) => {
+            let msg = e.to_string();
+            if matches!(e, crate::extensions::ExtensionError::ValidationFailed(_)) {
+                state.sse.broadcast(SseEvent::AuthRequired {
+                    extension_name: req.extension_name.clone(),
+                    instructions: Some(msg.clone()),
+                    auth_url: None,
+                    setup_url: None,
+                });
+            }
+            Ok(Json(ActionResponse::fail(msg)))
+        }
     }
 }
 
@@ -263,7 +255,6 @@ pub async fn chat_history_handler(
     ))?;
 
     let session = session_manager.get_or_create_session(&state.user_id).await;
-    let sess = session.lock().await;
 
     let limit = query.limit.unwrap_or(50);
     let before_cursor = query
@@ -281,11 +272,12 @@ pub async fn chat_history_handler(
         })
         .transpose()?;
 
-    // Find the thread
+    // Find the thread (lock only briefly to get active_thread if needed)
     let thread_id = if let Some(ref tid) = query.thread_id {
         Uuid::parse_str(tid)
             .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid thread_id".to_string()))?
     } else {
+        let sess = session.lock().await;
         sess.active_thread
             .ok_or((StatusCode::NOT_FOUND, "No active thread".to_string()))?
     };
@@ -298,8 +290,11 @@ pub async fn chat_history_handler(
             .conversation_belongs_to_user(thread_id, &state.user_id)
             .await
             .unwrap_or(false);
-        if !owned && !sess.threads.contains_key(&thread_id) {
-            return Err((StatusCode::NOT_FOUND, "Thread not found".to_string()));
+        if !owned {
+            let sess = session.lock().await;
+            if !sess.threads.contains_key(&thread_id) {
+                return Err((StatusCode::NOT_FOUND, "Thread not found".to_string()));
+            }
         }
     }
 
@@ -324,56 +319,60 @@ pub async fn chat_history_handler(
     }
 
     // Try in-memory first (freshest data for active threads)
-    if let Some(thread) = sess.threads.get(&thread_id)
-        && (!thread.turns.is_empty() || thread.pending_approval.is_some())
+    // Lock only when checking in-memory state
     {
-        let turns: Vec<TurnInfo> = thread
-            .turns
-            .iter()
-            .map(|t| TurnInfo {
-                turn_number: t.turn_number,
-                user_input: t.user_input.clone(),
-                response: t.response.clone(),
-                state: format!("{:?}", t.state),
-                started_at: t.started_at.to_rfc3339(),
-                completed_at: t.completed_at.map(|dt| dt.to_rfc3339()),
-                tool_calls: t
-                    .tool_calls
-                    .iter()
-                    .map(|tc| ToolCallInfo {
-                        name: tc.name.clone(),
-                        has_result: tc.result.is_some(),
-                        has_error: tc.error.is_some(),
-                        result_preview: tc.result.as_ref().map(|r| {
-                            let s = match r {
-                                serde_json::Value::String(s) => s.clone(),
-                                other => other.to_string(),
-                            };
-                            truncate_preview(&s, 500)
-                        }),
-                        error: tc.error.clone(),
-                    })
-                    .collect(),
-            })
-            .collect();
+        let sess = session.lock().await;
+        if let Some(thread) = sess.threads.get(&thread_id)
+            && (!thread.turns.is_empty() || thread.pending_approval.is_some())
+        {
+            let turns: Vec<TurnInfo> = thread
+                .turns
+                .iter()
+                .map(|t| TurnInfo {
+                    turn_number: t.turn_number,
+                    user_input: t.user_input.clone(),
+                    response: t.response.clone(),
+                    state: format!("{:?}", t.state),
+                    started_at: t.started_at.to_rfc3339(),
+                    completed_at: t.completed_at.map(|dt| dt.to_rfc3339()),
+                    tool_calls: t
+                        .tool_calls
+                        .iter()
+                        .map(|tc| ToolCallInfo {
+                            name: tc.name.clone(),
+                            has_result: tc.result.is_some(),
+                            has_error: tc.error.is_some(),
+                            result_preview: tc.result.as_ref().map(|r| {
+                                let s = match r {
+                                    serde_json::Value::String(s) => s.clone(),
+                                    other => other.to_string(),
+                                };
+                                truncate_preview(&s, 500)
+                            }),
+                            error: tc.error.clone(),
+                        })
+                        .collect(),
+                })
+                .collect();
 
-        let pending_approval = thread
-            .pending_approval
-            .as_ref()
-            .map(|pa| PendingApprovalInfo {
-                request_id: pa.request_id.to_string(),
-                tool_name: pa.tool_name.clone(),
-                description: pa.description.clone(),
-                parameters: serde_json::to_string_pretty(&pa.parameters).unwrap_or_default(),
-            });
+            let pending_approval = thread
+                .pending_approval
+                .as_ref()
+                .map(|pa| PendingApprovalInfo {
+                    request_id: pa.request_id.to_string(),
+                    tool_name: pa.tool_name.clone(),
+                    description: pa.description.clone(),
+                    parameters: serde_json::to_string_pretty(&pa.parameters).unwrap_or_default(),
+                });
 
-        return Ok(Json(HistoryResponse {
-            thread_id,
-            turns,
-            has_more: false,
-            oldest_timestamp: None,
-            pending_approval,
-        }));
+            return Ok(Json(HistoryResponse {
+                thread_id,
+                turns,
+                has_more: false,
+                oldest_timestamp: None,
+                pending_approval,
+            }));
+        }
     }
 
     // Fall back to DB for historical threads not in memory (paginated)
@@ -415,7 +414,6 @@ pub async fn chat_threads_handler(
     ))?;
 
     let session = session_manager.get_or_create_session(&state.user_id).await;
-    let sess = session.lock().await;
 
     // Try DB first for persistent thread list
     if let Some(ref store) = state.store {
@@ -465,15 +463,22 @@ pub async fn chat_threads_handler(
                 });
             }
 
+            // Read active thread while holding minimal lock (just before return)
+            let active_thread = {
+                let sess = session.lock().await;
+                sess.active_thread
+            };
+
             return Ok(Json(ThreadListResponse {
                 assistant_thread,
                 threads,
-                active_thread: sess.active_thread,
+                active_thread,
             }));
         }
     }
 
     // Fallback: in-memory only (no assistant thread without DB)
+    let sess = session.lock().await;
     let mut sorted_threads: Vec<_> = sess.threads.values().collect();
     sorted_threads.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
     let threads: Vec<ThreadInfo> = sorted_threads
@@ -490,10 +495,13 @@ pub async fn chat_threads_handler(
         })
         .collect();
 
+    let active_thread = sess.active_thread;
+    drop(sess); // Explicit drop to release lock
+
     Ok(Json(ThreadListResponse {
         assistant_thread: None,
         threads,
-        active_thread: sess.active_thread,
+        active_thread,
     }))
 }
 

src/channels/web/handlers/extensions.rs

@@ -46,6 +46,14 @@ pub async fn extensions_list_handler(
                 } else {
                     "configured".to_string()
                 })
+            } else if ext.kind == crate::extensions::ExtensionKind::ChannelRelay {
+                Some(if ext.active {
+                    "active".to_string()
+                } else if ext.authenticated {
+                    "configured".to_string()
+                } else {
+                    "installed".to_string()
+                })
             } else {
                 None
             };
@@ -103,6 +111,7 @@ pub async fn extensions_install_handler(
         "mcp_server" => Some(crate::extensions::ExtensionKind::McpServer),
         "wasm_tool" => Some(crate::extensions::ExtensionKind::WasmTool),
         "wasm_channel" => Some(crate::extensions::ExtensionKind::WasmChannel),
+        "channel_relay" => Some(crate::extensions::ExtensionKind::ChannelRelay),
         _ => None,
     });
 
@@ -115,62 +124,6 @@ pub async fn extensions_install_handler(
     }
 }
 
-pub async fn extensions_activate_handler(
-    State(state): State<Arc<GatewayState>>,
-    Path(name): Path<String>,
-) -> Result<Json<ActionResponse>, (StatusCode, String)> {
-    let ext_mgr = state.extension_manager.as_ref().ok_or((
-        StatusCode::NOT_IMPLEMENTED,
-        "Extension manager not available (secrets store required)".to_string(),
-    ))?;
-
-    match ext_mgr.activate(&name).await {
-        Ok(result) => {
-            // Activation just loads the WASM module. Auth (OAuth/manual) is
-            // triggered separately via save_setup_secrets or the auth endpoint.
-            Ok(Json(ActionResponse::ok(result.message)))
-        }
-        Err(activate_err) => {
-            let err_str = activate_err.to_string();
-            let needs_auth = err_str.contains("authentication")
-                || err_str.contains("401")
-                || err_str.contains("Unauthorized");
-
-            if !needs_auth {
-                return Ok(Json(ActionResponse::fail(err_str)));
-            }
-
-            // Activation failed due to auth; try authenticating first.
-            match ext_mgr.auth(&name, None).await {
-                Ok(auth_result) if auth_result.is_authenticated() => {
-                    // Auth succeeded, retry activation.
-                    match ext_mgr.activate(&name).await {
-                        Ok(result) => Ok(Json(ActionResponse::ok(result.message))),
-                        Err(e) => Ok(Json(ActionResponse::fail(e.to_string()))),
-                    }
-                }
-                Ok(auth_result) => {
-                    // Auth in progress (OAuth URL or awaiting manual token).
-                    let mut resp = ActionResponse::fail(
-                        auth_result
-                            .instructions()
-                            .map(String::from)
-                            .unwrap_or_else(|| format!("'{}' requires authentication.", name)),
-                    );
-                    resp.auth_url = auth_result.auth_url().map(String::from);
-                    resp.awaiting_token = Some(auth_result.is_awaiting_token());
-                    resp.instructions = auth_result.instructions().map(String::from);
-                    Ok(Json(resp))
-                }
-                Err(auth_err) => Ok(Json(ActionResponse::fail(format!(
-                    "Authentication failed: {}",
-                    auth_err
-                )))),
-            }
-        }
-    }
-}
-
 pub async fn extensions_remove_handler(
     State(state): State<Arc<GatewayState>>,
     Path(name): Path<String>,

src/channels/web/handlers/routines.rs

@@ -27,7 +27,7 @@ pub async fn routines_list_handler(
         .await
         .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
 
-    let items: Vec<RoutineInfo> = routines.iter().map(routine_to_info).collect();
+    let items: Vec<RoutineInfo> = routines.iter().map(RoutineInfo::from_routine).collect();
 
     Ok(Json(RoutineListResponse { routines: items }))
 }
@@ -263,54 +263,6 @@ pub async fn routines_runs_handler(
     })))
 }
 
-/// Convert a Routine to the trimmed RoutineInfo for list display.
-fn routine_to_info(r: &crate::agent::routine::Routine) -> RoutineInfo {
-    let (trigger_type, trigger_summary) = match &r.trigger {
-        crate::agent::routine::Trigger::Cron { schedule, .. } => {
-            ("cron".to_string(), format!("cron: {}", schedule))
-        }
-        crate::agent::routine::Trigger::Event {
-            pattern, channel, ..
-        } => {
-            let ch = channel.as_deref().unwrap_or("any");
-            ("event".to_string(), format!("on {} /{}/", ch, pattern))
-        }
-        crate::agent::routine::Trigger::Webhook { path, .. } => {
-            let p = path.as_deref().unwrap_or("/");
-            ("webhook".to_string(), format!("webhook: {}", p))
-        }
-        crate::agent::routine::Trigger::Manual => ("manual".to_string(), "manual only".to_string()),
-    };
-
-    let action_type = match &r.action {
-        crate::agent::routine::RoutineAction::Lightweight { .. } => "lightweight",
-        crate::agent::routine::RoutineAction::FullJob { .. } => "full_job",
-    };
-
-    let status = if !r.enabled {
-        "disabled"
-    } else if r.consecutive_failures > 0 {
-        "failing"
-    } else {
-        "active"
-    };
-
-    RoutineInfo {
-        id: r.id,
-        name: r.name.clone(),
-        description: r.description.clone(),
-        enabled: r.enabled,
-        trigger_type,
-        trigger_summary,
-        action_type: action_type.to_string(),
-        last_run_at: r.last_run_at.map(|dt| dt.to_rfc3339()),
-        next_fire_at: r.next_fire_at.map(|dt| dt.to_rfc3339()),
-        run_count: r.run_count,
-        consecutive_failures: r.consecutive_failures,
-        status: status.to_string(),
-    }
-}
-
 /// Map `RoutineError` variants to appropriate HTTP status codes.
 fn routine_error_status(err: &RoutineError) -> StatusCode {
     match err {

src/channels/web/mod.rs

@@ -97,6 +97,7 @@ impl GatewayChannel {
             skill_registry: None,
             skill_catalog: None,
             chat_rate_limiter: server::RateLimiter::new(30, 60),
+            oauth_rate_limiter: server::RateLimiter::new(10, 60),
             registry_entries: Vec::new(),
             cost_guard: None,
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
@@ -133,6 +134,7 @@ impl GatewayChannel {
             skill_registry: self.state.skill_registry.clone(),
             skill_catalog: self.state.skill_catalog.clone(),
             chat_rate_limiter: server::RateLimiter::new(30, 60),
+            oauth_rate_limiter: server::RateLimiter::new(10, 60),
             registry_entries: self.state.registry_entries.clone(),
             cost_guard: self.state.cost_guard.clone(),
             routine_engine: Arc::clone(&self.state.routine_engine),
@@ -242,6 +244,12 @@ impl GatewayChannel {
         self
     }
 
+    /// Inject a shared routine engine slot used by other HTTP ingress paths.
+    pub fn with_routine_engine_slot(mut self, slot: server::RoutineEngineSlot) -> Self {
+        self.rebuild_state(|s| s.routine_engine = slot);
+        self
+    }
+
     /// Get the auth token (for printing to console on startup).
     pub fn auth_token(&self) -> &str {
         &self.auth_token

src/channels/web/server.rs

@@ -28,6 +28,7 @@ use uuid::Uuid;
 use crate::agent::SessionManager;
 use crate::bootstrap::ironclaw_base_dir;
 use crate::channels::IncomingMessage;
+use crate::channels::relay::DEFAULT_RELAY_NAME;
 use crate::channels::web::auth::{AuthState, auth_middleware};
 use crate::channels::web::handlers::jobs::{
     job_files_list_handler, job_files_read_handler, jobs_cancel_handler, jobs_detail_handler,
@@ -164,6 +165,8 @@ pub struct GatewayState {
     pub scheduler: Option<crate::tools::builtin::SchedulerSlot>,
     /// Rate limiter for chat endpoints (30 messages per 60 seconds).
     pub chat_rate_limiter: RateLimiter,
+    /// Rate limiter for OAuth callback endpoints (10 requests per 60 seconds).
+    pub oauth_rate_limiter: RateLimiter,
     /// Registry catalog entries for the available extensions API.
     /// Populated at startup from `registry/` manifests, independent of extension manager.
     pub registry_entries: Vec<crate::extensions::RegistryEntry>,
@@ -200,7 +203,11 @@ pub async fn start_server(
     // Public routes (no auth)
     let public = Router::new()
         .route("/api/health", get(health_handler))
-        .route("/oauth/callback", get(oauth_callback_handler));
+        .route("/oauth/callback", get(oauth_callback_handler))
+        .route(
+            "/oauth/slack/callback",
+            get(slack_relay_oauth_callback_handler),
+        );
 
     // Protected routes (require auth)
     let auth_state = AuthState { token: auth_token };
@@ -311,7 +318,11 @@ pub async fn start_server(
         .route("/", get(index_handler))
         .route("/style.css", get(css_handler))
         .route("/app.js", get(js_handler))
-        .route("/favicon.ico", get(favicon_handler));
+        .route("/favicon.ico", get(favicon_handler))
+        .route("/i18n/index.js", get(i18n_index_handler))
+        .route("/i18n/en.js", get(i18n_en_handler))
+        .route("/i18n/zh-CN.js", get(i18n_zh_handler))
+        .route("/i18n-app.js", get(i18n_app_handler));
 
     // Project file serving (behind auth to prevent unauthorized file access).
     let projects = Router::new()
@@ -423,6 +434,46 @@ async fn favicon_handler() -> impl IntoResponse {
     )
 }
 
+async fn i18n_index_handler() -> impl IntoResponse {
+    (
+        [
+            (header::CONTENT_TYPE, "application/javascript"),
+            (header::CACHE_CONTROL, "no-cache"),
+        ],
+        include_str!("static/i18n/index.js"),
+    )
+}
+
+async fn i18n_en_handler() -> impl IntoResponse {
+    (
+        [
+            (header::CONTENT_TYPE, "application/javascript"),
+            (header::CACHE_CONTROL, "no-cache"),
+        ],
+        include_str!("static/i18n/en.js"),
+    )
+}
+
+async fn i18n_zh_handler() -> impl IntoResponse {
+    (
+        [
+            (header::CONTENT_TYPE, "application/javascript"),
+            (header::CACHE_CONTROL, "no-cache"),
+        ],
+        include_str!("static/i18n/zh-CN.js"),
+    )
+}
+
+async fn i18n_app_handler() -> impl IntoResponse {
+    (
+        [
+            (header::CONTENT_TYPE, "application/javascript"),
+            (header::CACHE_CONTROL, "no-cache"),
+        ],
+        include_str!("static/i18n-app.js"),
+    )
+}
+
 // --- Health ---
 
 async fn health_handler() -> Json<HealthResponse> {
@@ -606,6 +657,208 @@ async fn oauth_callback_handler(
     axum::response::Html(html).into_response()
 }
 
+/// OAuth callback for Slack via channel-relay.
+///
+/// This is a PUBLIC route (no Bearer token required) because channel-relay
+/// redirects the user's browser here after Slack OAuth completes.
+/// Query params: `stream_token`, `provider`, `team_id`.
+async fn slack_relay_oauth_callback_handler(
+    State(state): State<Arc<GatewayState>>,
+    Query(params): Query<std::collections::HashMap<String, String>>,
+) -> impl IntoResponse {
+    // Rate limit
+    if !state.oauth_rate_limiter.check() {
+        return axum::response::Html(
+            "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+             <h2>Too Many Requests</h2>\
+             <p>Please try again later.</p>\
+             </body></html>"
+                .to_string(),
+        )
+        .into_response();
+    }
+
+    // Validate stream_token: required, non-empty, max 2048 bytes
+    let stream_token = match params.get("stream_token") {
+        Some(t) if !t.is_empty() && t.len() <= 2048 => t.clone(),
+        Some(t) if t.len() > 2048 => {
+            return axum::response::Html(
+                "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+                 <h2>Error</h2><p>Invalid callback parameters.</p></body></html>"
+                    .to_string(),
+            )
+            .into_response();
+        }
+        _ => {
+            return axum::response::Html(
+                "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+                 <h2>Error</h2><p>Invalid callback parameters.</p></body></html>"
+                    .to_string(),
+            )
+            .into_response();
+        }
+    };
+
+    // Validate team_id format: empty or T followed by alphanumeric (max 20 chars)
+    let team_id = params.get("team_id").cloned().unwrap_or_default();
+    if !team_id.is_empty() {
+        let valid_team_id = team_id.len() <= 21
+            && team_id.starts_with('T')
+            && team_id[1..].chars().all(|c| c.is_ascii_alphanumeric());
+        if !valid_team_id {
+            return axum::response::Html(
+                "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+                 <h2>Error</h2><p>Invalid callback parameters.</p></body></html>"
+                    .to_string(),
+            )
+            .into_response();
+        }
+    }
+
+    // Validate provider: must be "slack" (only supported provider)
+    let provider = params
+        .get("provider")
+        .cloned()
+        .unwrap_or_else(|| "slack".into());
+    if provider != "slack" {
+        return axum::response::Html(
+            "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+             <h2>Error</h2><p>Invalid callback parameters.</p></body></html>"
+                .to_string(),
+        )
+        .into_response();
+    }
+
+    let ext_mgr = match state.extension_manager.as_ref() {
+        Some(mgr) => mgr,
+        None => {
+            return axum::response::Html(
+                "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+                 <h2>Error</h2><p>Extension manager not available.</p></body></html>"
+                    .to_string(),
+            )
+            .into_response();
+        }
+    };
+
+    // Validate CSRF state parameter
+    let state_param = match params.get("state") {
+        Some(s) if !s.is_empty() && s.len() <= 128 => s.clone(),
+        _ => {
+            return axum::response::Html(
+                "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+                 <h2>Error</h2><p>Invalid or expired authorization.</p></body></html>"
+                    .to_string(),
+            )
+            .into_response();
+        }
+    };
+
+    let state_key = format!("relay:{}:oauth_state", DEFAULT_RELAY_NAME);
+    let stored_state = match ext_mgr
+        .secrets()
+        .get_decrypted(&state.user_id, &state_key)
+        .await
+    {
+        Ok(secret) => secret.expose().to_string(),
+        Err(_) => {
+            return axum::response::Html(
+                "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+                 <h2>Error</h2><p>Invalid or expired authorization.</p></body></html>"
+                    .to_string(),
+            )
+            .into_response();
+        }
+    };
+
+    if state_param != stored_state {
+        return axum::response::Html(
+            "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+             <h2>Error</h2><p>Invalid or expired authorization.</p></body></html>"
+                .to_string(),
+        )
+        .into_response();
+    }
+
+    // Delete the nonce (one-time use)
+    let _ = ext_mgr.secrets().delete(&state.user_id, &state_key).await;
+
+    let result: Result<(), String> = async {
+        // Store the stream token as a secret
+        let token_key = format!("relay:{}:stream_token", DEFAULT_RELAY_NAME);
+        let _ = ext_mgr.secrets().delete(&state.user_id, &token_key).await;
+        ext_mgr
+            .secrets()
+            .create(
+                &state.user_id,
+                crate::secrets::CreateSecretParams {
+                    name: token_key,
+                    value: secrecy::SecretString::from(stream_token),
+                    provider: Some(provider.clone()),
+                    expires_at: None,
+                },
+            )
+            .await
+            .map_err(|e| format!("Failed to store stream token: {}", e))?;
+
+        // Store team_id in settings
+        if let Some(ref store) = state.store {
+            let team_id_key = format!("relay:{}:team_id", DEFAULT_RELAY_NAME);
+            let _ = store
+                .set_setting(&state.user_id, &team_id_key, &serde_json::json!(team_id))
+                .await;
+        }
+
+        // Activate the relay channel
+        ext_mgr
+            .activate_stored_relay(DEFAULT_RELAY_NAME)
+            .await
+            .map_err(|e| format!("Failed to activate relay channel: {}", e))?;
+
+        Ok(())
+    }
+    .await;
+
+    let (success, message) = match &result {
+        Ok(()) => (true, "Slack connected successfully!".to_string()),
+        Err(e) => {
+            tracing::error!(error = %e, "Slack relay OAuth callback failed");
+            (
+                false,
+                "Connection failed. Check server logs for details.".to_string(),
+            )
+        }
+    };
+
+    // Broadcast SSE event to notify the web UI
+    state.sse.broadcast(SseEvent::AuthCompleted {
+        extension_name: DEFAULT_RELAY_NAME.to_string(),
+        success,
+        message: message.clone(),
+    });
+
+    if success {
+        axum::response::Html(
+            "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+             <h2>Slack Connected!</h2>\
+             <p>You can close this tab and return to IronClaw.</p>\
+             <script>window.close()</script>\
+             </body></html>"
+                .to_string(),
+        )
+        .into_response()
+    } else {
+        axum::response::Html(format!(
+            "<html><body style='font-family: system-ui; text-align: center; padding: 60px;'>\
+             <h2>Connection Failed</h2>\
+             <p>{}</p>\
+             </body></html>",
+            message
+        ))
+        .into_response()
+    }
+}
+
 // --- Chat handlers ---
 
 /// Convert web gateway `ImageData` to `IncomingAttachment` objects.
@@ -663,9 +916,9 @@ async fn chat_send_handler(
     headers: axum::http::HeaderMap,
     Json(req): Json<SendMessageRequest>,
 ) -> Result<(StatusCode, Json<SendMessageResponse>), (StatusCode, String)> {
-    tracing::debug!(
-        "[chat_send_handler] Received message: content={:?}, thread_id={:?}",
-        req.content,
+    tracing::trace!(
+        "[chat_send_handler] Received message: content_len={}, thread_id={:?}",
+        req.content.len(),
         req.thread_id
     );
 
@@ -698,10 +951,10 @@ async fn chat_send_handler(
     }
 
     let msg_id = msg.id;
-    tracing::debug!(
-        "[chat_send_handler] Created message id={}, content={:?}, images={}",
+    tracing::trace!(
+        "[chat_send_handler] Created message id={}, content_len={}, images={}",
         msg_id,
-        req.content,
+        req.content.len(),
         req.images.len()
     );
 
@@ -809,49 +1062,35 @@ async fn chat_auth_token_handler(
         "Extension manager not available".to_string(),
     ))?;
 
-    let result = ext_mgr
-        .auth(&req.extension_name, Some(&req.token))
+    match ext_mgr
+        .configure_token(&req.extension_name, &req.token)
         .await
-        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+    {
+        Ok(result) => {
+            // Clear auth mode on the active thread
+            clear_auth_mode(&state).await;
 
-    if result.is_authenticated() {
-        // Auto-activate so tools are available immediately
-        let msg = match ext_mgr.activate(&req.extension_name).await {
-            Ok(r) => format!(
-                "{} authenticated ({} tools loaded)",
-                req.extension_name,
-                r.tools_loaded.len()
-            ),
-            Err(e) => format!(
-                "{} authenticated but activation failed: {}",
-                req.extension_name, e
-            ),
-        };
+            state.sse.broadcast(SseEvent::AuthCompleted {
+                extension_name: req.extension_name.clone(),
+                success: true,
+                message: result.message.clone(),
+            });
 
-        // Clear auth mode on the active thread
-        clear_auth_mode(&state).await;
-
-        state.sse.broadcast(SseEvent::AuthCompleted {
-            extension_name: req.extension_name,
-            success: true,
-            message: msg.clone(),
-        });
-
-        Ok(Json(ActionResponse::ok(msg)))
-    } else {
-        // Re-emit auth_required for retry
-        state.sse.broadcast(SseEvent::AuthRequired {
-            extension_name: req.extension_name.clone(),
-            instructions: result.instructions().map(String::from),
-            auth_url: result.auth_url().map(String::from),
-            setup_url: result.setup_url().map(String::from),
-        });
-        Ok(Json(ActionResponse::fail(
-            result
-                .instructions()
-                .map(String::from)
-                .unwrap_or_else(|| "Invalid token".to_string()),
-        )))
+            Ok(Json(ActionResponse::ok(result.message)))
+        }
+        Err(e) => {
+            let msg = e.to_string();
+            // Re-emit auth_required for retry on validation errors
+            if matches!(e, crate::extensions::ExtensionError::ValidationFailed(_)) {
+                state.sse.broadcast(SseEvent::AuthRequired {
+                    extension_name: req.extension_name.clone(),
+                    instructions: Some(msg.clone()),
+                    auth_url: None,
+                    setup_url: None,
+                });
+            }
+            Ok(Json(ActionResponse::fail(msg)))
+        }
     }
 }
 
@@ -1600,7 +1839,7 @@ async fn extensions_install_handler(
                 // expansion and for first-time auth when credentials are already
                 // configured (e.g., built-in providers). We only surface an auth_url
                 // when the extension reports it is awaiting authorization.
-                match ext_mgr.auth(&req.name, None).await {
+                match ext_mgr.auth(&req.name).await {
                     Ok(auth_result) if auth_result.auth_url().is_some() => {
                         // Scope expansion or initial OAuth: user needs to authorize
                         resp.auth_url = auth_result.auth_url().map(String::from);
@@ -1629,9 +1868,9 @@ async fn extensions_activate_handler(
             // Activation loaded the WASM module. Check if the tool needs
             // OAuth scope expansion (e.g., adding google-docs when gmail
             // already has a token but missing the documents scope).
-            // Initial OAuth setup is triggered via save_setup_secrets.
+            // Initial OAuth setup is triggered via configure.
             let mut resp = ActionResponse::ok(result.message);
-            if let Ok(auth_result) = ext_mgr.auth(&name, None).await
+            if let Ok(auth_result) = ext_mgr.auth(&name).await
                 && auth_result.auth_url().is_some()
             {
                 resp.auth_url = auth_result.auth_url().map(String::from);
@@ -1639,17 +1878,17 @@ async fn extensions_activate_handler(
             Ok(Json(resp))
         }
         Err(activate_err) => {
-            let err_str = activate_err.to_string();
-            let needs_auth = err_str.contains("authentication")
-                || err_str.contains("401")
-                || err_str.contains("Unauthorized");
+            let needs_auth = matches!(
+                &activate_err,
+                crate::extensions::ExtensionError::AuthRequired
+            );
 
             if !needs_auth {
-                return Ok(Json(ActionResponse::fail(err_str)));
+                return Ok(Json(ActionResponse::fail(activate_err.to_string())));
             }
 
             // Activation failed due to auth; try authenticating first.
-            match ext_mgr.auth(&name, None).await {
+            match ext_mgr.auth(&name).await {
                 Ok(auth_result) if auth_result.is_authenticated() => {
                     // Auth succeeded, retry activation.
                     match ext_mgr.activate(&name).await {
@@ -1856,7 +2095,7 @@ async fn extensions_setup_submit_handler(
         "Extension manager not available (secrets store required)".to_string(),
     ))?;
 
-    match ext_mgr.save_setup_secrets(&name, &req.secrets).await {
+    match ext_mgr.configure(&name, &req.secrets).await {
         Ok(result) => {
             // Broadcast auth_completed so the chat UI can dismiss any in-progress
             // auth card or setup modal that was triggered by tool_auth/tool_activate.
@@ -1936,7 +2175,7 @@ async fn routines_list_handler(
         .await
         .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
 
-    let items: Vec<RoutineInfo> = routines.iter().map(routine_to_info).collect();
+    let items: Vec<RoutineInfo> = routines.iter().map(RoutineInfo::from_routine).collect();
 
     Ok(Json(RoutineListResponse { routines: items }))
 }
@@ -2180,54 +2419,6 @@ async fn routines_runs_handler(
     })))
 }
 
-/// Convert a Routine to the trimmed RoutineInfo for list display.
-fn routine_to_info(r: &crate::agent::routine::Routine) -> RoutineInfo {
-    let (trigger_type, trigger_summary) = match &r.trigger {
-        crate::agent::routine::Trigger::Cron { schedule, .. } => {
-            ("cron".to_string(), format!("cron: {}", schedule))
-        }
-        crate::agent::routine::Trigger::Event {
-            pattern, channel, ..
-        } => {
-            let ch = channel.as_deref().unwrap_or("any");
-            ("event".to_string(), format!("on {} /{}/", ch, pattern))
-        }
-        crate::agent::routine::Trigger::Webhook { path, .. } => {
-            let p = path.as_deref().unwrap_or("/");
-            ("webhook".to_string(), format!("webhook: {}", p))
-        }
-        crate::agent::routine::Trigger::Manual => ("manual".to_string(), "manual only".to_string()),
-    };
-
-    let action_type = match &r.action {
-        crate::agent::routine::RoutineAction::Lightweight { .. } => "lightweight",
-        crate::agent::routine::RoutineAction::FullJob { .. } => "full_job",
-    };
-
-    let status = if !r.enabled {
-        "disabled"
-    } else if r.consecutive_failures > 0 {
-        "failing"
-    } else {
-        "active"
-    };
-
-    RoutineInfo {
-        id: r.id,
-        name: r.name.clone(),
-        description: r.description.clone(),
-        enabled: r.enabled,
-        trigger_type,
-        trigger_summary,
-        action_type: action_type.to_string(),
-        last_run_at: r.last_run_at.map(|dt| dt.to_rfc3339()),
-        next_fire_at: r.next_fire_at.map(|dt| dt.to_rfc3339()),
-        run_count: r.run_count,
-        consecutive_failures: r.consecutive_failures,
-        status: status.to_string(),
-    }
-}
-
 // --- Settings handlers ---
 
 async fn settings_list_handler(
@@ -2427,6 +2618,7 @@ struct GatewayStatusResponse {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::testing::credentials::TEST_GATEWAY_CRYPTO_KEY;
 
     #[test]
     fn test_build_turns_from_db_messages_complete() {
@@ -2528,6 +2720,7 @@ mod tests {
             skill_catalog: None,
             scheduler: None,
             chat_rate_limiter: RateLimiter::new(30, 60),
+            oauth_rate_limiter: RateLimiter::new(10, 60),
             registry_entries: vec![],
             cost_guard: None,
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
@@ -2600,7 +2793,7 @@ mod tests {
         // Build an ExtensionManager so the handler can look up flows
         let secrets = Arc::new(crate::secrets::InMemorySecretsStore::new(Arc::new(
             crate::secrets::SecretsCrypto::new(secrecy::SecretString::from(
-                "test-key-at-least-32-chars-long!!".to_string(),
+                TEST_GATEWAY_CRYPTO_KEY.to_string(),
             ))
             .expect("crypto"),
         )));
@@ -2650,7 +2843,7 @@ mod tests {
         let secrets: Arc<dyn crate::secrets::SecretsStore + Send + Sync> =
             Arc::new(crate::secrets::InMemorySecretsStore::new(Arc::new(
                 crate::secrets::SecretsCrypto::new(secrecy::SecretString::from(
-                    "test-key-at-least-32-chars-long!!".to_string(),
+                    TEST_GATEWAY_CRYPTO_KEY.to_string(),
                 ))
                 .expect("crypto"),
             )));
@@ -2756,7 +2949,7 @@ mod tests {
         let secrets: Arc<dyn crate::secrets::SecretsStore + Send + Sync> =
             Arc::new(crate::secrets::InMemorySecretsStore::new(Arc::new(
                 crate::secrets::SecretsCrypto::new(secrecy::SecretString::from(
-                    "test-key-at-least-32-chars-long!!".to_string(),
+                    TEST_GATEWAY_CRYPTO_KEY.to_string(),
                 ))
                 .expect("crypto"),
             )));
@@ -2850,4 +3043,177 @@ mod tests {
                 .is_none()
         );
     }
+
+    // --- Slack relay OAuth CSRF tests ---
+
+    fn test_relay_oauth_router(state: Arc<GatewayState>) -> Router {
+        Router::new()
+            .route(
+                "/oauth/slack/callback",
+                get(slack_relay_oauth_callback_handler),
+            )
+            .with_state(state)
+    }
+
+    fn test_secrets_store() -> Arc<dyn crate::secrets::SecretsStore + Send + Sync> {
+        Arc::new(crate::secrets::InMemorySecretsStore::new(Arc::new(
+            crate::secrets::SecretsCrypto::new(secrecy::SecretString::from(
+                "test-key-at-least-32-chars-long!!".to_string(),
+            ))
+            .expect("crypto"),
+        )))
+    }
+
+    fn test_ext_mgr(
+        secrets: Arc<dyn crate::secrets::SecretsStore + Send + Sync>,
+    ) -> Arc<ExtensionManager> {
+        let tool_registry = Arc::new(ToolRegistry::new());
+        let mcp_sm = Arc::new(crate::tools::mcp::session::McpSessionManager::new());
+        let mcp_pm = Arc::new(crate::tools::mcp::process::McpProcessManager::new());
+        Arc::new(ExtensionManager::new(
+            mcp_sm,
+            mcp_pm,
+            secrets,
+            tool_registry,
+            None,
+            None,
+            std::path::PathBuf::from("/tmp/wasm_tools"),
+            std::path::PathBuf::from("/tmp/wasm_channels"),
+            None,
+            "test".to_string(),
+            None,
+            vec![],
+        ))
+    }
+
+    #[tokio::test]
+    async fn test_relay_oauth_callback_missing_state_param() {
+        use axum::body::Body;
+        use tower::ServiceExt;
+
+        let secrets = test_secrets_store();
+        let ext_mgr = test_ext_mgr(secrets);
+        let state = test_gateway_state(Some(ext_mgr));
+        let app = test_relay_oauth_router(state);
+
+        // Callback without state param should be rejected
+        let req = axum::http::Request::builder()
+            .uri("/oauth/slack/callback?stream_token=tok123&team_id=T123&provider=slack")
+            .body(Body::empty())
+            .expect("request");
+
+        let resp = ServiceExt::<axum::http::Request<Body>>::oneshot(app, req)
+            .await
+            .expect("response");
+
+        let body = axum::body::to_bytes(resp.into_body(), 1024 * 64)
+            .await
+            .expect("body");
+        let html = String::from_utf8_lossy(&body);
+        assert!(
+            html.contains("Invalid or expired authorization"),
+            "Expected CSRF error, got: {}",
+            &html[..html.len().min(300)]
+        );
+    }
+
+    #[tokio::test]
+    async fn test_relay_oauth_callback_wrong_state_param() {
+        use axum::body::Body;
+        use tower::ServiceExt;
+
+        let secrets = test_secrets_store();
+
+        // Store a valid nonce
+        secrets
+            .create(
+                "test",
+                crate::secrets::CreateSecretParams::new(
+                    format!("relay:{}:oauth_state", DEFAULT_RELAY_NAME),
+                    "correct-nonce-value",
+                ),
+            )
+            .await
+            .expect("store nonce");
+
+        let ext_mgr = test_ext_mgr(secrets);
+        let state = test_gateway_state(Some(ext_mgr));
+        let app = test_relay_oauth_router(state);
+
+        // Callback with wrong state param
+        let req = axum::http::Request::builder()
+            .uri("/oauth/slack/callback?stream_token=tok123&team_id=T123&provider=slack&state=wrong-nonce")
+            .body(Body::empty())
+            .expect("request");
+
+        let resp = ServiceExt::<axum::http::Request<Body>>::oneshot(app, req)
+            .await
+            .expect("response");
+
+        let body = axum::body::to_bytes(resp.into_body(), 1024 * 64)
+            .await
+            .expect("body");
+        let html = String::from_utf8_lossy(&body);
+        assert!(
+            html.contains("Invalid or expired authorization"),
+            "Expected CSRF error for wrong nonce, got: {}",
+            &html[..html.len().min(300)]
+        );
+    }
+
+    #[tokio::test]
+    async fn test_relay_oauth_callback_correct_state_proceeds() {
+        use axum::body::Body;
+        use tower::ServiceExt;
+
+        let secrets = test_secrets_store();
+        let nonce = "valid-test-nonce-12345";
+
+        // Store the correct nonce
+        secrets
+            .create(
+                "test",
+                crate::secrets::CreateSecretParams::new(
+                    format!("relay:{}:oauth_state", DEFAULT_RELAY_NAME),
+                    nonce,
+                ),
+            )
+            .await
+            .expect("store nonce");
+
+        let ext_mgr = test_ext_mgr(secrets.clone());
+        let state = test_gateway_state(Some(ext_mgr));
+        let app = test_relay_oauth_router(state);
+
+        // Callback with correct state param — will pass CSRF check
+        // but may fail downstream (no real relay service) — that's OK,
+        // we just verify it doesn't return a CSRF error.
+        let req = axum::http::Request::builder()
+            .uri(format!(
+                "/oauth/slack/callback?stream_token=tok123&team_id=T123&provider=slack&state={}",
+                nonce
+            ))
+            .body(Body::empty())
+            .expect("request");
+
+        let resp = ServiceExt::<axum::http::Request<Body>>::oneshot(app, req)
+            .await
+            .expect("response");
+
+        let body = axum::body::to_bytes(resp.into_body(), 1024 * 64)
+            .await
+            .expect("body");
+        let html = String::from_utf8_lossy(&body);
+        // Should NOT contain the CSRF error message
+        assert!(
+            !html.contains("Invalid or expired authorization"),
+            "Should have passed CSRF check, got: {}",
+            &html[..html.len().min(300)]
+        );
+
+        // Verify the nonce was consumed (deleted)
+        let state_key = format!("relay:{}:oauth_state", DEFAULT_RELAY_NAME);
+        let exists = secrets.exists("test", &state_key).await.unwrap_or(true);
+        assert!(!exists, "CSRF nonce should be deleted after use");
+    }
 }

src/channels/web/static/app.js

@@ -55,7 +55,7 @@ let _activityThinking = null;
 function authenticate() {
   token = document.getElementById('token-input').value.trim();
   if (!token) {
-    document.getElementById('auth-error').textContent = 'Token required';
+    document.getElementById('auth-error').textContent = I18n.t('auth.errorRequired');
     return;
   }
 
@@ -89,7 +89,7 @@ function authenticate() {
       sessionStorage.removeItem('ironclaw_token');
       document.getElementById('auth-screen').style.display = '';
       document.getElementById('app').style.display = 'none';
-      document.getElementById('auth-error').textContent = 'Invalid token';
+      document.getElementById('auth-error').textContent = I18n.t('auth.errorInvalid');
     });
 }
 
@@ -144,7 +144,7 @@ let restartEnabled = false; // Track if restart is available in this deployment
 
 function triggerRestart() {
   if (!currentThreadId) {
-    alert('Please start a conversation first');
+    alert(I18n.t('error.startConversation'));
     return;
   }
 
@@ -155,7 +155,7 @@ function triggerRestart() {
 
 function confirmRestart() {
   if (!currentThreadId) {
-    alert('Please start a conversation first');
+    alert(I18n.t('error.startConversation'));
     return;
   }
 
@@ -190,7 +190,7 @@ function confirmRestart() {
     })
     .catch((err) => {
       console.error('[confirmRestart] Restart request failed:', err);
-      addMessage('system', 'Restart failed: ' + err.message);
+      addMessage('system', I18n.t('error.restartFailed', { message: err.message }));
       isRestarting = false;
       restartBtn.disabled = false;
       if (restartIcon) restartIcon.classList.remove('spinning');
@@ -234,7 +234,7 @@ function connectSSE() {
 
   eventSource.onopen = () => {
     document.getElementById('sse-dot').classList.remove('disconnected');
-    document.getElementById('sse-status').textContent = 'Connected';
+    document.getElementById('sse-status').textContent = I18n.t('status.connected');
 
     // If we were restarting, close the modal and reset button now that server is back
     if (isRestarting) {
@@ -256,7 +256,7 @@ function connectSSE() {
 
   eventSource.onerror = () => {
     document.getElementById('sse-dot').classList.add('disconnected');
-    document.getElementById('sse-status').textContent = 'Reconnecting...';
+    document.getElementById('sse-status').textContent = I18n.t('status.reconnecting');
   };
 
   eventSource.addEventListener('response', (e) => {
@@ -464,7 +464,7 @@ function enableChatInput() {
   const btn = document.getElementById('send-btn');
   if (input) {
     input.disabled = false;
-    input.placeholder = 'Message or / for commands...';
+    input.placeholder = I18n.t('chat.inputPlaceholder');
   }
   if (btn) btn.disabled = false;
 }
@@ -676,26 +676,20 @@ function renderMarkdown(text) {
   return escapeHtml(text);
 }
 
-// Strip dangerous HTML elements and attributes from rendered markdown.
-// This prevents XSS from tool output or prompt injection in LLM responses.
+// Sanitize rendered HTML using DOMPurify to prevent XSS from tool output
+// or prompt injection in LLM responses. DOMPurify is a DOM-based sanitizer
+// that handles all known bypass vectors (SVG onload, newline-split event
+// handlers, mutation XSS, etc.) unlike the regex approach it replaces.
 function sanitizeRenderedHtml(html) {
-  html = html.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
-  html = html.replace(/<iframe\b[^>]*>[\s\S]*?<\/iframe>/gi, '');
-  html = html.replace(/<object\b[^>]*>[\s\S]*?<\/object>/gi, '');
-  html = html.replace(/<embed\b[^>]*\/?>/gi, '');
-  html = html.replace(/<form\b[^>]*>[\s\S]*?<\/form>/gi, '');
-  html = html.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '');
-  html = html.replace(/<link\b[^>]*\/?>/gi, '');
-  html = html.replace(/<base\b[^>]*\/?>/gi, '');
-  html = html.replace(/<meta\b[^>]*\/?>/gi, '');
-  // Remove event handler attributes (onclick, onerror, onload, etc.)
-  html = html.replace(/\s+on\w+\s*=\s*"[^"]*"/gi, '');
-  html = html.replace(/\s+on\w+\s*=\s*'[^']*'/gi, '');
-  html = html.replace(/\s+on\w+\s*=\s*[^\s>]+/gi, '');
-  // Remove javascript: and data: URLs in href/src attributes
-  html = html.replace(/(href|src|action)\s*=\s*["']?\s*javascript\s*:/gi, '$1="');
-  html = html.replace(/(href|src|action)\s*=\s*["']?\s*data\s*:/gi, '$1="');
-  return html;
+  if (typeof DOMPurify !== 'undefined') {
+    return DOMPurify.sanitize(html, {
+      USE_PROFILES: { html: true },
+      FORBID_TAGS: ['style', 'script'],
+      FORBID_ATTR: ['style', 'onerror', 'onload']
+    });
+  }
+  // DOMPurify not available (CDN unreachable) — return empty string rather than unsanitized HTML
+  return '';
 }
 
 function copyCodeBlock(btn) {
@@ -703,8 +697,8 @@ function copyCodeBlock(btn) {
   const code = pre.querySelector('code');
   const text = code ? code.textContent : pre.textContent;
   navigator.clipboard.writeText(text).then(() => {
-    btn.textContent = 'Copied!';
-    setTimeout(() => { btn.textContent = 'Copy'; }, 1500);
+    btn.textContent = I18n.t('btn.copied');
+    setTimeout(() => { btn.textContent = I18n.t('btn.copy'); }, 1500);
   });
 }
 
@@ -991,7 +985,7 @@ function showApproval(data) {
 
   const header = document.createElement('div');
   header.className = 'approval-header';
-  header.textContent = 'Tool requires approval';
+  header.textContent = I18n.t('approval.title');
   card.appendChild(header);
 
   const toolName = document.createElement('div');
@@ -1009,7 +1003,7 @@ function showApproval(data) {
   if (data.parameters) {
     const paramsToggle = document.createElement('button');
     paramsToggle.className = 'approval-params-toggle';
-    paramsToggle.textContent = 'Show parameters';
+    paramsToggle.textContent = I18n.t('approval.showParams');
     const paramsBlock = document.createElement('pre');
     paramsBlock.className = 'approval-params';
     paramsBlock.textContent = data.parameters;
@@ -1017,7 +1011,7 @@ function showApproval(data) {
     paramsToggle.addEventListener('click', () => {
       const visible = paramsBlock.style.display !== 'none';
       paramsBlock.style.display = visible ? 'none' : 'block';
-      paramsToggle.textContent = visible ? 'Show parameters' : 'Hide parameters';
+      paramsToggle.textContent = visible ? I18n.t('approval.showParams') : I18n.t('approval.hideParams');
     });
     card.appendChild(paramsToggle);
     card.appendChild(paramsBlock);
@@ -1028,17 +1022,17 @@ function showApproval(data) {
 
   const approveBtn = document.createElement('button');
   approveBtn.className = 'approve';
-  approveBtn.textContent = 'Approve';
+  approveBtn.textContent = I18n.t('approval.approve');
   approveBtn.addEventListener('click', () => sendApprovalAction(data.request_id, 'approve'));
 
   const alwaysBtn = document.createElement('button');
   alwaysBtn.className = 'always';
-  alwaysBtn.textContent = 'Always';
+  alwaysBtn.textContent = I18n.t('approval.always');
   alwaysBtn.addEventListener('click', () => sendApprovalAction(data.request_id, 'always'));
 
   const denyBtn = document.createElement('button');
   denyBtn.className = 'deny';
-  denyBtn.textContent = 'Deny';
+  denyBtn.textContent = I18n.t('approval.deny');
   denyBtn.addEventListener('click', () => sendApprovalAction(data.request_id, 'deny'));
 
   actions.appendChild(approveBtn);
@@ -1065,7 +1059,7 @@ function showJobCard(data) {
 
   const title = document.createElement('div');
   title.className = 'job-card-title';
-  title.textContent = data.title || 'Sandbox Job';
+  title.textContent = data.title || I18n.t('sandbox.job');
   info.appendChild(title);
 
   const id = document.createElement('div');
@@ -1077,7 +1071,7 @@ function showJobCard(data) {
 
   const viewBtn = document.createElement('button');
   viewBtn.className = 'job-card-view';
-  viewBtn.textContent = 'View Job';
+  viewBtn.textContent = I18n.t('jobs.viewJob');
   viewBtn.addEventListener('click', () => {
     switchTab('jobs');
     openJobDetail(data.job_id);
@@ -1089,7 +1083,7 @@ function showJobCard(data) {
     browseBtn.className = 'job-card-browse';
     browseBtn.href = data.browse_url;
     browseBtn.target = '_blank';
-    browseBtn.textContent = 'Browse';
+    browseBtn.textContent = I18n.t('jobs.browse');
     card.appendChild(browseBtn);
   }
 
@@ -1110,7 +1104,7 @@ function showAuthCard(data) {
 
   const header = document.createElement('div');
   header.className = 'auth-header';
-  header.textContent = 'Authentication required for ' + data.extension_name;
+  header.textContent = I18n.t('authRequired.title', {name: data.extension_name});
   card.appendChild(header);
 
   if (data.instructions) {
@@ -1126,7 +1120,7 @@ function showAuthCard(data) {
   if (data.auth_url) {
     const oauthBtn = document.createElement('button');
     oauthBtn.className = 'auth-oauth';
-    oauthBtn.textContent = 'Authenticate with ' + data.extension_name;
+    oauthBtn.textContent = I18n.t('authRequired.authenticateWith', {name: data.extension_name});
     oauthBtn.addEventListener('click', () => {
       openOAuthUrl(data.auth_url);
     });
@@ -1137,7 +1131,7 @@ function showAuthCard(data) {
     const setupLink = document.createElement('a');
     setupLink.href = data.setup_url;
     setupLink.target = '_blank';
-    setupLink.textContent = 'Get your token';
+    setupLink.textContent = I18n.t('authRequired.getToken');
     links.appendChild(setupLink);
   }
 
@@ -1151,7 +1145,9 @@ function showAuthCard(data) {
 
   const tokenInput = document.createElement('input');
   tokenInput.type = 'password';
-  tokenInput.placeholder = data.instructions || 'Paste your API key or token';
+  tokenInput.placeholder = data.instructions
+    || I18n.t('auth.extensionTokenPlaceholder')
+    || I18n.t('auth.tokenPlaceholder');
   tokenInput.addEventListener('keydown', (e) => {
     if (e.key === 'Enter') submitAuthToken(data.extension_name, tokenInput.value);
   });
@@ -1170,12 +1166,12 @@ function showAuthCard(data) {
 
   const submitBtn = document.createElement('button');
   submitBtn.className = 'auth-submit';
-  submitBtn.textContent = 'Submit';
+  submitBtn.textContent = I18n.t('btn.submit');
   submitBtn.addEventListener('click', () => submitAuthToken(data.extension_name, tokenInput.value));
 
   const cancelBtn = document.createElement('button');
   cancelBtn.className = 'auth-cancel';
-  cancelBtn.textContent = 'Cancel';
+  cancelBtn.textContent = I18n.t('btn.cancel');
   cancelBtn.addEventListener('click', () => cancelAuth(data.extension_name));
 
   actions.appendChild(submitBtn);
@@ -1690,22 +1686,25 @@ function renderNodes(nodes, container, depth) {
     const row = document.createElement('div');
     row.className = 'tree-row';
     row.style.paddingLeft = (depth * 16 + 8) + 'px';
+    row.tabIndex = 0;
+    row.setAttribute('role', 'treeitem');
 
     if (node.is_dir) {
+      row.setAttribute('aria-expanded', node.expanded ? 'true' : 'false');
       const arrow = document.createElement('span');
       arrow.className = 'expand-arrow' + (node.expanded ? ' expanded' : '');
       arrow.textContent = '\u25B6';
-      arrow.addEventListener('click', (e) => {
-        e.stopPropagation();
-        toggleExpand(node);
-      });
       row.appendChild(arrow);
 
       const label = document.createElement('span');
       label.className = 'tree-label dir';
       label.textContent = node.name;
-      label.addEventListener('click', () => toggleExpand(node));
       row.appendChild(label);
+
+      row.addEventListener('click', () => toggleExpand(node));
+      row.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); toggleExpand(node); }
+      });
     } else {
       const spacer = document.createElement('span');
       spacer.className = 'expand-arrow-spacer';
@@ -1714,8 +1713,12 @@ function renderNodes(nodes, container, depth) {
       const label = document.createElement('span');
       label.className = 'tree-label file';
       label.textContent = node.name;
-      label.addEventListener('click', () => readMemoryFile(node.path));
       row.appendChild(label);
+
+      row.addEventListener('click', () => readMemoryFile(node.path));
+      row.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); readMemoryFile(node.path); }
+      });
     }
 
     container.appendChild(row);
@@ -1960,7 +1963,7 @@ function prependLogEntry(entry) {
 function toggleLogsPause() {
   logsPaused = !logsPaused;
   const btn = document.getElementById('logs-pause-btn');
-  btn.textContent = logsPaused ? 'Resume' : 'Pause';
+  btn.textContent = logsPaused ? I18n.t('logs.resume') : I18n.t('logs.pause');
 
   if (!logsPaused) {
     // Flush buffer: oldest-first + prepend naturally puts newest at top
@@ -2032,7 +2035,7 @@ function loadExtensions() {
   ]).then(([extData, toolData, registryData]) => {
     // Render installed extensions
     if (extData.extensions.length === 0) {
-      extList.innerHTML = '<div class="empty-state">No extensions installed</div>';
+      extList.innerHTML = '<div class="empty-state">' + I18n.t('extensions.noInstalled') + '</div>';
     } else {
       extList.innerHTML = '';
       for (const ext of extData.extensions) {
@@ -2046,7 +2049,7 @@ function loadExtensions() {
 
     // Available WASM extensions
     if (wasmEntries.length === 0) {
-      wasmList.innerHTML = '<div class="empty-state">No additional WASM extensions available</div>';
+      wasmList.innerHTML = '<div class="empty-state">' + I18n.t('extensions.noAvailable') + '</div>';
     } else {
       wasmList.innerHTML = '';
       for (const entry of wasmEntries) {
@@ -2056,7 +2059,7 @@ function loadExtensions() {
 
     // MCP servers (show both installed and uninstalled)
     if (mcpEntries.length === 0) {
-      mcpList.innerHTML = '<div class="empty-state">No MCP servers available</div>';
+      mcpList.innerHTML = '<div class="empty-state">' + I18n.t('mcp.noServers') + '</div>';
     } else {
       mcpList.innerHTML = '';
       for (const entry of mcpEntries) {
@@ -2121,16 +2124,16 @@ function renderAvailableExtensionCard(entry) {
 
   const installBtn = document.createElement('button');
   installBtn.className = 'btn-ext install';
-  installBtn.textContent = 'Install';
+  installBtn.textContent = I18n.t('extensions.install');
   installBtn.addEventListener('click', function() {
     installBtn.disabled = true;
-    installBtn.textContent = 'Installing...';
+    installBtn.textContent = I18n.t('extensions.installing');
     apiFetch('/api/extensions/install', {
       method: 'POST',
       body: { name: entry.name, kind: entry.kind },
     }).then(function(res) {
       if (res.success) {
-        showToast('Installed ' + entry.display_name, 'success');
+        showToast(I18n.t('extensions.installedSuccess', {name: entry.display_name}), 'success');
         // OAuth popup if auth started during install (builtin creds)
         if (res.auth_url) {
           showToast('Opening authentication for ' + entry.display_name, 'info');
@@ -2194,39 +2197,39 @@ function renderMcpServerCard(entry, installedExt) {
     if (!installedExt.active) {
       var activateBtn = document.createElement('button');
       activateBtn.className = 'btn-ext activate';
-      activateBtn.textContent = 'Activate';
+      activateBtn.textContent = I18n.t('common.activate');
       activateBtn.addEventListener('click', function() { activateExtension(installedExt.name); });
       actions.appendChild(activateBtn);
     } else {
       var activeLabel = document.createElement('span');
       activeLabel.className = 'ext-active-label';
-      activeLabel.textContent = 'Active';
+      activeLabel.textContent = I18n.t('ext.active');
       actions.appendChild(activeLabel);
     }
     var removeBtn = document.createElement('button');
     removeBtn.className = 'btn-ext remove';
-    removeBtn.textContent = 'Remove';
+    removeBtn.textContent = I18n.t('ext.remove');
     removeBtn.addEventListener('click', function() { removeExtension(installedExt.name); });
     actions.appendChild(removeBtn);
   } else {
     var installBtn = document.createElement('button');
     installBtn.className = 'btn-ext install';
-    installBtn.textContent = 'Install';
+    installBtn.textContent = I18n.t('ext.install');
     installBtn.addEventListener('click', function() {
       installBtn.disabled = true;
-      installBtn.textContent = 'Installing...';
+      installBtn.textContent = I18n.t('ext.installing');
       apiFetch('/api/extensions/install', {
         method: 'POST',
         body: { name: entry.name, kind: entry.kind },
       }).then(function(res) {
         if (res.success) {
-          showToast('Installed ' + entry.display_name, 'success');
+          showToast(I18n.t('extensions.installedSuccess', { name: entry.display_name }), 'success');
         } else {
-          showToast('Install: ' + (res.message || 'unknown error'), 'error');
+          showToast(I18n.t('ext.install') + ': ' + (res.message || 'unknown error'), 'error');
         }
         loadExtensions();
       }).catch(function(err) {
-        showToast('Install failed: ' + err.message, 'error');
+        showToast(I18n.t('ext.installFailed', { message: err.message }), 'error');
         loadExtensions();
       });
     });
@@ -2240,7 +2243,7 @@ function renderMcpServerCard(entry, installedExt) {
 function createReconfigureButton(extName) {
   var btn = document.createElement('button');
   btn.className = 'btn-ext configure';
-  btn.textContent = 'Reconfigure';
+  btn.textContent = I18n.t('ext.reconfigure');
   btn.addEventListener('click', function() { showConfigureModal(extName); });
   return btn;
 }
@@ -2324,13 +2327,13 @@ function renderExtensionCard(ext) {
     if (status === 'active') {
       var activeLabel = document.createElement('span');
       activeLabel.className = 'ext-active-label';
-      activeLabel.textContent = 'Active';
+      activeLabel.textContent = I18n.t('ext.active');
       actions.appendChild(activeLabel);
       actions.appendChild(createReconfigureButton(ext.name));
     } else if (status === 'pairing') {
       var pairingLabel = document.createElement('span');
       pairingLabel.className = 'ext-pairing-label';
-      pairingLabel.textContent = 'Awaiting Pairing';
+      pairingLabel.textContent = I18n.t('status.awaitingPairing');
       actions.appendChild(pairingLabel);
       actions.appendChild(createReconfigureButton(ext.name));
     } else if (status === 'failed') {
@@ -2339,7 +2342,7 @@ function renderExtensionCard(ext) {
       // installed or configured: show Setup button
       var setupBtn = document.createElement('button');
       setupBtn.className = 'btn-ext configure';
-      setupBtn.textContent = 'Setup';
+      setupBtn.textContent = I18n.t('ext.setup');
       setupBtn.addEventListener('click', function() { showConfigureModal(ext.name); });
       actions.appendChild(setupBtn);
     }
@@ -2347,14 +2350,14 @@ function renderExtensionCard(ext) {
     // WASM tools / MCP servers
     const activeLabel = document.createElement('span');
     activeLabel.className = 'ext-active-label';
-    activeLabel.textContent = ext.active ? 'Active' : 'Installed';
+    activeLabel.textContent = ext.active ? I18n.t('ext.active') : I18n.t('status.installed');
     actions.appendChild(activeLabel);
 
-    // MCP servers may be installed but inactive — show Activate button
-    if (ext.kind === 'mcp_server' && !ext.active) {
+    // MCP servers and channel-relay extensions may be installed but inactive — show Activate button
+    if ((ext.kind === 'mcp_server' || ext.kind === 'channel_relay') && !ext.active) {
       const activateBtn = document.createElement('button');
       activateBtn.className = 'btn-ext activate';
-      activateBtn.textContent = 'Activate';
+      activateBtn.textContent = I18n.t('common.activate');
       activateBtn.addEventListener('click', () => activateExtension(ext.name));
       actions.appendChild(activateBtn);
     }
@@ -2366,7 +2369,7 @@ function renderExtensionCard(ext) {
     if (ext.needs_setup || (ext.has_auth && ext.authenticated)) {
       const configBtn = document.createElement('button');
       configBtn.className = 'btn-ext configure';
-      configBtn.textContent = ext.authenticated ? 'Reconfigure' : 'Configure';
+      configBtn.textContent = ext.authenticated ? I18n.t('ext.reconfigure') : I18n.t('ext.configure');
       configBtn.addEventListener('click', () => showConfigureModal(ext.name));
       actions.appendChild(configBtn);
     }
@@ -2374,7 +2377,7 @@ function renderExtensionCard(ext) {
 
   const removeBtn = document.createElement('button');
   removeBtn.className = 'btn-ext remove';
-  removeBtn.textContent = 'Remove';
+  removeBtn.textContent = I18n.t('ext.remove');
   removeBtn.addEventListener('click', () => removeExtension(ext.name));
   actions.appendChild(removeBtn);
 
@@ -2419,17 +2422,17 @@ function activateExtension(name) {
 }
 
 function removeExtension(name) {
-  if (!confirm('Remove extension "' + name + '"?')) return;
+  if (!confirm(I18n.t('ext.confirmRemove', { name: name }))) return;
   apiFetch('/api/extensions/' + encodeURIComponent(name) + '/remove', { method: 'POST' })
     .then((res) => {
       if (!res.success) {
-        showToast('Remove failed: ' + res.message, 'error');
+        showToast(I18n.t('ext.removeFailed', { message: res.message }), 'error');
       } else {
-        showToast('Removed ' + name, 'success');
+        showToast(I18n.t('ext.removed', { name: name }), 'success');
       }
       loadExtensions();
     })
-    .catch((err) => showToast('Remove failed: ' + err.message, 'error'));
+    .catch((err) => showToast(I18n.t('ext.removeFailed', { message: err.message }), 'error'));
 }
 
 function showConfigureModal(name) {
@@ -2456,7 +2459,7 @@ function renderConfigureModal(name, secrets) {
   modal.className = 'configure-modal';
 
   const header = document.createElement('h3');
-  header.textContent = 'Configure ' + name;
+  header.textContent = I18n.t('config.title', { name: name });
   modal.appendChild(header);
 
   const form = document.createElement('div');
@@ -2472,7 +2475,7 @@ function renderConfigureModal(name, secrets) {
     if (secret.optional) {
       const opt = document.createElement('span');
       opt.className = 'field-optional';
-      opt.textContent = ' (optional)';
+      opt.textContent = I18n.t('config.optional');
       label.appendChild(opt);
     }
     field.appendChild(label);
@@ -2483,7 +2486,7 @@ function renderConfigureModal(name, secrets) {
     const input = document.createElement('input');
     input.type = 'password';
     input.name = secret.name;
-    input.placeholder = secret.provided ? '(already set — leave empty to keep)' : '';
+    input.placeholder = secret.provided ? I18n.t('config.alreadySet') : '';
     input.addEventListener('keydown', (e) => {
       if (e.key === 'Enter') submitConfigureModal(name, fields);
     });
@@ -2493,13 +2496,13 @@ function renderConfigureModal(name, secrets) {
       const badge = document.createElement('span');
       badge.className = 'field-provided';
       badge.textContent = '\u2713';
-      badge.title = 'Already configured';
+      badge.title = I18n.t('config.alreadyConfigured');
       inputRow.appendChild(badge);
     }
     if (secret.auto_generate && !secret.provided) {
       const hint = document.createElement('span');
       hint.className = 'field-autogen';
-      hint.textContent = 'Auto-generated if empty';
+      hint.textContent = I18n.t('config.autoGenerate');
       inputRow.appendChild(hint);
     }
 
@@ -2515,13 +2518,13 @@ function renderConfigureModal(name, secrets) {
 
   const submitBtn = document.createElement('button');
   submitBtn.className = 'btn-ext activate';
-  submitBtn.textContent = 'Save';
+  submitBtn.textContent = I18n.t('config.save');
   submitBtn.addEventListener('click', () => submitConfigureModal(name, fields));
   actions.appendChild(submitBtn);
 
   const cancelBtn = document.createElement('button');
   cancelBtn.className = 'btn-ext remove';
-  cancelBtn.textContent = 'Cancel';
+  cancelBtn.textContent = I18n.t('config.cancel');
   cancelBtn.addEventListener('click', closeConfigureModal);
   actions.appendChild(cancelBtn);
 
@@ -2761,11 +2764,11 @@ function loadJobs() {
 
 function renderJobsSummary(s) {
   document.getElementById('jobs-summary').innerHTML = ''
-    + summaryCard('Total', s.total, '')
-    + summaryCard('In Progress', s.in_progress, 'active')
-    + summaryCard('Completed', s.completed, 'completed')
-    + summaryCard('Failed', s.failed, 'failed')
-    + summaryCard('Stuck', s.stuck, 'stuck');
+    + summaryCard(I18n.t('jobs.summary.total'), s.total, '')
+    + summaryCard(I18n.t('jobs.summary.inProgress'), s.in_progress, 'active')
+    + summaryCard(I18n.t('jobs.summary.completed'), s.completed, 'completed')
+    + summaryCard(I18n.t('jobs.summary.failed'), s.failed, 'failed')
+    + summaryCard(I18n.t('jobs.summary.stuck'), s.stuck, 'stuck');
 }
 
 function summaryCard(label, count, cls) {
@@ -3295,11 +3298,11 @@ function loadRoutines() {
 
 function renderRoutinesSummary(s) {
   document.getElementById('routines-summary').innerHTML = ''
-    + summaryCard('Total', s.total, '')
-    + summaryCard('Enabled', s.enabled, 'active')
-    + summaryCard('Disabled', s.disabled, '')
-    + summaryCard('Failing', s.failing, 'failed')
-    + summaryCard('Runs Today', s.runs_today, 'completed');
+    + summaryCard(I18n.t('routines.summary.total'), s.total, '')
+    + summaryCard(I18n.t('routines.summary.enabled'), s.enabled, 'active')
+    + summaryCard(I18n.t('routines.summary.disabled'), s.disabled, '')
+    + summaryCard(I18n.t('routines.summary.failing'), s.failing, 'failed')
+    + summaryCard(I18n.t('routines.summary.runsToday'), s.runs_today, 'completed');
 }
 
 function renderRoutinesList(routines) {
@@ -3465,17 +3468,18 @@ function formatRelativeTime(isoString) {
   const absDiff = Math.abs(diffMs);
   const future = diffMs < 0;
 
-  if (absDiff < 60000) return future ? 'in <1m' : '<1m ago';
+  if (absDiff < 60000) 
+    return future ? I18n.t('time.lessThan1MinuteFromNow') : I18n.t('time.lessThan1MinuteAgo');
   if (absDiff < 3600000) {
     const m = Math.floor(absDiff / 60000);
-    return future ? 'in ' + m + 'm' : m + 'm ago';
+    return future ? I18n.t('time.minutesFromNow', { n: m }) : I18n.t('time.minutesAgo', { n: m });
   }
   if (absDiff < 86400000) {
     const h = Math.floor(absDiff / 3600000);
-    return future ? 'in ' + h + 'h' : h + 'h ago';
+    return future ? I18n.t('time.hoursFromNow', { n: h }) : I18n.t('time.hoursAgo', { n: h });
   }
   const days = Math.floor(absDiff / 86400000);
-  return future ? 'in ' + days + 'd' : days + 'd ago';
+  return future ? I18n.t('time.daysFromNow', { n: days }) : I18n.t('time.daysAgo', { n: days });
 }
 
 // --- Gateway status widget ---
@@ -3525,18 +3529,18 @@ function fetchGatewayStatus() {
     }
 
     // Connection info
-    html += '<div class="gw-section-label">Connections</div>';
-    html += '<div class="gw-stat"><span>SSE</span><span>' + (data.sse_connections || 0) + '</span></div>';
-    html += '<div class="gw-stat"><span>WebSocket</span><span>' + (data.ws_connections || 0) + '</span></div>';
-    html += '<div class="gw-stat"><span>Uptime</span><span>' + formatDuration(data.uptime_secs) + '</span></div>';
+    html += '<div class="gw-section-label">' + I18n.t('dashboard.connections') + '</div>';
+    html += '<div class="gw-stat"><span>' + I18n.t('dashboard.sse') + '</span><span>' + (data.sse_connections || 0) + '</span></div>';
+    html += '<div class="gw-stat"><span>' + I18n.t('dashboard.websocket') + '</span><span>' + (data.ws_connections || 0) + '</span></div>';
+    html += '<div class="gw-stat"><span>' + I18n.t('dashboard.uptime') + '</span><span>' + formatDuration(data.uptime_secs) + '</span></div>';
 
     // Cost tracker
     if (data.daily_cost != null) {
       html += '<div class="gw-divider"></div>';
-      html += '<div class="gw-section-label">Cost Today</div>';
-      html += '<div class="gw-stat"><span>Spent</span><span>' + formatCost(data.daily_cost) + '</span></div>';
+      html += '<div class="gw-section-label">' + I18n.t('dashboard.costToday') + '</div>';
+      html += '<div class="gw-stat"><span>' + I18n.t('dashboard.spent') + '</span><span>' + formatCost(data.daily_cost) + '</span></div>';
       if (data.actions_this_hour != null) {
-        html += '<div class="gw-stat"><span>Actions/hr</span><span>' + data.actions_this_hour + '</span></div>';
+        html += '<div class="gw-stat"><span>' + I18n.t('dashboard.actionsPerHour') + '</span><span>' + data.actions_this_hour + '</span></div>';
       }
     }
 
@@ -3744,7 +3748,7 @@ function loadSkills() {
   var skillsList = document.getElementById('skills-list');
   apiFetch('/api/skills').then(function(data) {
     if (!data.skills || data.skills.length === 0) {
-      skillsList.innerHTML = '<div class="empty-state">No skills installed</div>';
+      skillsList.innerHTML = '<div class="empty-state">' + I18n.t('skills.noInstalled') + '</div>';
       return;
     }
     skillsList.innerHTML = '';
@@ -3752,7 +3756,7 @@ function loadSkills() {
       skillsList.appendChild(renderSkillCard(data.skills[i]));
     }
   }).catch(function(err) {
-    skillsList.innerHTML = '<div class="empty-state">Failed to load skills: ' + escapeHtml(err.message) + '</div>';
+    skillsList.innerHTML = '<div class="empty-state">' + I18n.t('skills.loadFailed', {message: escapeHtml(err.message)}) + '</div>';
   });
 }
 
@@ -3789,7 +3793,7 @@ function renderSkillCard(skill) {
   if (skill.keywords && skill.keywords.length > 0) {
     var kw = document.createElement('div');
     kw.className = 'ext-keywords';
-    kw.textContent = 'Activates on: ' + skill.keywords.join(', ');
+    kw.textContent = I18n.t('skills.activatesOn') + ': ' + skill.keywords.join(', ');
     card.appendChild(kw);
   }
 
@@ -3800,7 +3804,7 @@ function renderSkillCard(skill) {
   if (skill.trust.toLowerCase() !== 'trusted') {
     var removeBtn = document.createElement('button');
     removeBtn.className = 'btn-ext remove';
-    removeBtn.textContent = 'Remove';
+    removeBtn.textContent = I18n.t('skills.remove');
     removeBtn.addEventListener('click', function() { removeSkill(skill.name); });
     actions.appendChild(removeBtn);
   }
@@ -3815,7 +3819,7 @@ function searchClawHub() {
   if (!query) return;
 
   var resultsDiv = document.getElementById('skill-search-results');
-  resultsDiv.innerHTML = '<div class="empty-state">Searching...</div>';
+  resultsDiv.innerHTML = '<div class="empty-state">' + I18n.t('skills.searching') + '</div>';
 
   apiFetch('/api/skills/search', {
     method: 'POST',
@@ -3831,7 +3835,7 @@ function searchClawHub() {
       warning.style.borderLeft = '3px solid #f0ad4e';
       warning.style.paddingLeft = '12px';
       warning.style.marginBottom = '16px';
-      warning.textContent = 'Could not reach ClawHub registry: ' + data.catalog_error;
+      warning.textContent = I18n.t('skills.registryError', {message: data.catalog_error});
       resultsDiv.appendChild(warning);
     }
 
@@ -3863,10 +3867,10 @@ function searchClawHub() {
     }
 
     if (resultsDiv.children.length === 0) {
-      resultsDiv.innerHTML = '<div class="empty-state">No skills found for "' + escapeHtml(query) + '"</div>';
+      resultsDiv.innerHTML = '<div class="empty-state">' + I18n.t('skills.noResults', {query: escapeHtml(query)}) + '</div>';
     }
   }).catch(function(err) {
-    resultsDiv.innerHTML = '<div class="empty-state">Search failed: ' + escapeHtml(err.message) + '</div>';
+    resultsDiv.innerHTML = '<div class="empty-state">' + I18n.t('skills.searchFailed', {message: escapeHtml(err.message)}) + '</div>';
   });
 }
 
@@ -3960,17 +3964,17 @@ function renderCatalogSkillCard(entry, installedNames) {
   if (isInstalled) {
     var label = document.createElement('span');
     label.className = 'ext-active-label';
-    label.textContent = 'Installed';
+    label.textContent = I18n.t('status.installed');
     actions.appendChild(label);
   } else {
     var installBtn = document.createElement('button');
     installBtn.className = 'btn-ext install';
-    installBtn.textContent = 'Install';
+    installBtn.textContent = I18n.t('extensions.install');
     installBtn.addEventListener('click', (function(s, btn) {
       return function() {
         if (!confirm('Install skill "' + s + '" from ClawHub?')) return;
         btn.disabled = true;
-        btn.textContent = 'Installing...';
+        btn.textContent = I18n.t('extensions.installing');
         installSkill(s, null, btn);
       };
     })(slug, installBtn));
@@ -4012,7 +4016,7 @@ function installSkill(nameOrSlug, url, btn) {
     body: body,
   }).then(function(res) {
     if (res.success) {
-      showToast('Installed skill "' + nameOrSlug + '"', 'success');
+      showToast(I18n.t('skills.installedSuccess', {name: nameOrSlug}), 'success');
     } else {
       showToast('Install failed: ' + (res.message || 'unknown error'), 'error');
     }
@@ -4025,19 +4029,19 @@ function installSkill(nameOrSlug, url, btn) {
 }
 
 function removeSkill(name) {
-  if (!confirm('Remove skill "' + name + '"?')) return;
+  if (!confirm(I18n.t('skills.confirmRemove', { name: name }))) return;
   apiFetch('/api/skills/' + encodeURIComponent(name), {
     method: 'DELETE',
     headers: { 'X-Confirm-Action': 'true' },
   }).then(function(res) {
     if (res.success) {
-      showToast('Removed skill "' + name + '"', 'success');
+      showToast(I18n.t('skills.removed', { name: name }), 'success');
     } else {
-      showToast('Remove failed: ' + (res.message || 'unknown error'), 'error');
+      showToast(I18n.t('skills.removeFailed', { message: res.message || 'unknown error' }), 'error');
     }
     loadSkills();
   }).catch(function(err) {
-    showToast('Remove failed: ' + err.message, 'error');
+    showToast(I18n.t('skills.removeFailed', { message: err.message }), 'error');
   });
 }
 

src/channels/web/static/i18n-app.js

@@ -0,0 +1,74 @@
+// i18n Integration for IronClaw App
+// This file contains i18n-related functions that extend app.js
+
+// Initialize i18n when DOM is ready
+document.addEventListener('DOMContentLoaded', () => {
+  // Initialize i18n
+  I18n.init();
+  I18n.updatePageContent();
+  updateSlashCommands();
+  updateLanguageMenu();
+});
+
+// Update slash commands with current language
+function updateSlashCommands() {
+  // Update SLASH_COMMANDS descriptions
+  SLASH_COMMANDS.forEach(cmd => {
+    const key = 'cmd.' + cmd.cmd.replace(/\s+/g, '').replace(/\//g, '') + '.desc';
+    const translated = I18n.t(key);
+    if (translated !== key) {
+      cmd.desc = translated;
+    }
+  });
+}
+
+// Toggle language menu
+function toggleLanguageMenu() {
+  const menu = document.getElementById('language-menu');
+  if (menu) {
+    menu.style.display = menu.style.display === 'none' ? 'block' : 'none';
+  }
+}
+
+// Switch language
+function switchLanguage(lang) {
+  if (I18n.setLanguage(lang)) {
+    // Update slash commands
+    updateSlashCommands();
+    
+    // Update language menu active state
+    updateLanguageMenu();
+    
+    // Close menu
+    const menu = document.getElementById('language-menu');
+    if (menu) {
+      menu.style.display = 'none';
+    }
+    
+    // Show toast notification
+    showToast(I18n.t('language.switch') + ': ' + (lang === 'zh-CN' ? '简体中文' : 'English'));
+  }
+}
+
+// Update language menu active state
+function updateLanguageMenu() {
+  const currentLang = I18n.getCurrentLang();
+  document.querySelectorAll('.language-option').forEach(option => {
+    if (option.getAttribute('data-lang') === currentLang) {
+      option.classList.add('active');
+    } else {
+      option.classList.remove('active');
+    }
+  });
+}
+
+// Close language menu when clicking outside
+document.addEventListener('click', (e) => {
+  if (!e.target.closest('.language-switcher')) {
+    const menu = document.getElementById('language-menu');
+    if (menu) {
+      menu.style.display = 'none';
+    }
+  }
+});
+

src/channels/web/static/i18n/en.js

@@ -0,0 +1,351 @@
+// English Language Pack for IronClaw
+
+I18n.register('en', {
+  // Auth Page
+  'auth.title': 'IronClaw',
+  'auth.tagline': 'Secure AI Assistant',
+  'auth.tokenLabel': 'Gateway Token',
+  'auth.tokenPlaceholder': 'Paste your token',
+  'auth.connect': 'Connect',
+  'auth.errorRequired': 'Token required',
+  'auth.errorInvalid': 'Invalid token',
+  'auth.hint': 'Enter the GATEWAY_AUTH_TOKEN from your .env file',
+  
+  // Chat
+  'chat.inputPlaceholder': 'Message or / for commands...',
+  
+  // Restart Modal
+  'restart.title': 'Restart IronClaw Instance',
+  'restart.description': 'Are you sure you want to restart IronClaw? This will gracefully restart the process.',
+  'restart.warning': 'Running tasks may be interrupted. Restart will complete in a few seconds.',
+  'restart.cancel': 'Cancel',
+  'restart.confirm': 'Confirm Restart',
+  'restart.progressTitle': 'Restarting IronClaw',
+  'restart.progressSubtitle': 'Please wait for the process to restart...',
+  'restart.checkLogs': 'Check the Logs tab for details after restart completes.',
+  
+  // Tabs
+  'tab.chat': 'Chat',
+  'tab.memory': 'Memory',
+  'tab.jobs': 'Jobs',
+  'tab.routines': 'Routines',
+  'tab.extensions': 'Extensions',
+  'tab.skills': 'Skills',
+  'tab.logs': 'Logs',
+  
+  // Status
+  'status.connected': 'Connected',
+  'status.disconnected': 'Disconnected',
+  'status.connecting': 'Connecting...',
+  'status.reconnecting': 'Reconnecting...',
+  'status.teeVerified': 'TEE Verified',
+  'status.restart': 'Restart',
+  'status.active': 'Active',
+  'status.installed': 'Installed',
+  'status.awaitingPairing': 'Awaiting Pairing',
+  
+  // Dashboard
+  'dashboard.connections': 'Connections',
+  'dashboard.uptime': 'Uptime',
+  'dashboard.costToday': 'Cost Today',
+  'dashboard.spent': 'Spent',
+  'dashboard.actionsPerHour': 'Actions/hr',
+  'dashboard.sse': 'SSE',
+  'dashboard.websocket': 'WebSocket',
+  
+  // Chat Tab
+  'chat.newThread': 'New Thread',
+  'chat.toggleSidebar': 'Toggle Sidebar',
+  'chat.assistant': 'Assistant',
+  'chat.conversations': 'Conversations',
+  'chat.send': 'Send',
+  'chat.attachImages': 'Attach Images',
+  'chat.empty': 'Select a file to view content',
+  'chat.loading': 'Loading...',
+  'chat.loadingOlder': 'Loading older messages...',
+  'chat.noFiles': 'No files in workspace',
+  'chat.noResults': 'No results',
+  
+  // Thread Sidebar
+  'thread.assistant': 'Assistant',
+  'thread.new': 'New Thread',
+  
+  // Memory Tab
+  'memory.searchPlaceholder': 'Search memory...',
+  'memory.workspace': 'workspace',
+  'memory.edit': 'Edit',
+  'memory.save': 'Save',
+  'memory.cancel': 'Cancel',
+  'memory.selectFile': 'Select a file to view content',
+  
+  // Jobs Tab
+  'jobs.summary': 'Jobs Summary',
+  'jobs.id': 'ID',
+  'jobs.title': 'Title',
+  'jobs.source': 'Source',
+  'jobs.status': 'Status',
+  'jobs.created': 'Created',
+  'jobs.actions': 'Actions',
+  'jobs.empty': 'No jobs',
+  'jobs.statusRunning': 'Running',
+  'jobs.statusCompleted': 'Completed',
+  'jobs.statusFailed': 'Failed',
+  'jobs.statusPending': 'Pending',
+  'jobs.jobId': 'Job ID',
+  'jobs.description': 'Description',
+  'jobs.stateTransitions': 'State Transitions',
+  'jobs.projectFiles': 'Project Files',
+  'jobs.noProjectFiles': 'No project files',
+  'jobs.viewJob': 'View Job',
+  'jobs.browse': 'Browse',
+  
+  // Routines Tab
+  'routines.summary': 'Routines Summary',
+  'routines.name': 'Name',
+  'routines.trigger': 'Trigger',
+  'routines.action': 'Action',
+  'routines.lastRun': 'Last Run',
+  'routines.nextRun': 'Next Run',
+  'routines.runs': 'Runs',
+  'routines.status': 'Status',
+  'routines.actions': 'Actions',
+  'routines.runsToday': 'Runs Today',
+  'routines.empty': 'No routines',
+  'routines.noConfigured': 'No routines configured. Ask the assistant to create one.',
+  'routines.triggerFailed': 'Trigger failed: {message}',
+  
+  // Logs Tab
+  'logs.serverLevel': 'Server: ERROR',
+  'logs.clientLevel': 'Client Log Level',
+  'logs.pause': 'Pause',
+  'logs.resume': 'Resume',
+  'logs.clear': 'Clear',
+  'logs.autoScroll': 'Auto-scroll',
+  'logs.filter': 'Filter logs...',
+  'logs.empty': 'No logs',
+  'logs.allLevels': 'All Levels',
+  'logs.error': 'Error',
+  'logs.warn': 'Warn',
+  'logs.info': 'Info',
+  'logs.debug': 'Debug',
+  
+  // Extensions Tab
+  'extensions.installed': 'Installed Extensions',
+  'extensions.available': 'Available WASM Extensions',
+  'extensions.installWasm': 'Install WASM Extension',
+  'extensions.noInstalled': 'No extensions installed',
+  'extensions.noAvailable': 'No additional WASM extensions available',
+  'extensions.loading': 'Loading...',
+  'extensions.install': 'Install',
+  'extensions.installing': 'Installing...',
+  'extensions.installedSuccess': 'Installed {name}',
+  'extensions.remove': 'Remove',
+  'extensions.activate': 'Activate',
+  'extensions.reconfigure': 'Reconfigure',
+  'extensions.tools': 'Tools',
+  'extensions.noConfigNeeded': 'No configuration needed for {name}',
+  'extensions.configure': 'Configure {name}',
+  'extensions.optional': ' (optional)',
+  'extensions.autoGenerated': 'Auto-generated if empty',
+  'extensions.pendingPairing': 'Pending pairing requests',
+  'extensions.from': 'from',
+  
+  // MCP Servers
+  'mcp.servers': 'MCP Servers',
+  'mcp.noServers': 'No MCP servers available',
+  'mcp.addCustom': 'Add Custom MCP Server',
+  'mcp.add': 'Add',
+  'mcp.addedSuccess': 'Added MCP server {name}',
+  
+  // Registered Tools
+  'tools.registered': 'Registered Tools',
+  'tools.name': 'Name',
+  'tools.description': 'Description',
+  'tools.empty': 'No tools registered',
+  
+  // Skills Tab
+  'skills.installed': 'Installed Skills',
+  'skills.noInstalled': 'No skills installed',
+  'skills.searchClawHub': 'Search ClawHub',
+  'skills.searchPlaceholder': 'Search...',
+  'skills.installByUrl': 'Install Skill by URL',
+  'skills.namePlaceholder': 'Skill name or slug',
+  'skills.urlPlaceholder': 'HTTPS URL to SKILL.md (optional)',
+  'skills.search': 'Search',
+  'skills.searching': 'Searching...',
+  'skills.noResults': 'No skills found for "{query}"',
+  'skills.searchFailed': 'Search failed: {message}',
+  'skills.install': 'Install',
+  'skills.installing': 'Installing...',
+  'skills.installedSuccess': 'Installed skill "{name}"',
+  'skills.remove': 'Remove',
+  'skills.activatesOn': 'Activates on',
+  'skills.registryError': 'Could not reach ClawHub registry: {message}',
+  'skills.by': 'by',
+  'skills.updated': 'updated',
+  'skills.loading': 'Loading skills...',
+  'skills.loadFailed': 'Failed to load skills: {message}',
+  'skills.confirmRemove': 'Remove skill "{name}"?',
+  'skills.removeFailed': 'Remove failed: {message}',
+  'skills.removed': 'Removed skill "{name}"',
+
+  // Jobs Summary
+  'jobs.summary.total': 'Total',
+  'jobs.summary.inProgress': 'In Progress',
+  'jobs.summary.completed': 'Completed',
+  'jobs.summary.failed': 'Failed',
+  'jobs.summary.stuck': 'Stuck',
+  
+  // Routines Summary
+  'routines.summary.total': 'Total',
+  'routines.summary.enabled': 'Enabled',
+  'routines.summary.disabled': 'Disabled',
+  'routines.summary.failing': 'Failing',
+  'routines.summary.runsToday': 'Runs Today',
+  
+  // Buttons
+  'btn.close': 'Close',
+  'btn.cancel': 'Cancel',
+  'btn.save': 'Save',
+  'btn.edit': 'Edit',
+  'btn.confirm': 'Confirm',
+  'btn.send': 'Send',
+  'btn.refresh': 'Refresh',
+  'btn.loadMore': 'Load More',
+  'btn.copy': 'Copy',
+  'btn.copied': 'Copied!',
+  'btn.submit': 'Submit',
+  'btn.setup': 'Setup',
+  
+  // Time
+  'time.lessThan1MinuteAgo': '<1m ago',
+  'time.lessThan1MinuteFromNow': 'in <1m',
+  'time.minutesAgo': '{n}m ago',
+  'time.minutesFromNow': 'in {n}m',
+  'time.hoursAgo': '{n}h ago',
+  'time.hoursFromNow': 'in {n}h',
+  'time.daysAgo': '{n}d ago',
+  'time.daysFromNow': 'in {n}d',
+  
+  // Tool Approval
+  'approval.title': 'Tool requires approval',
+  'approval.description': 'A tool is requesting permission to run.',
+  'approval.approve': 'Approve',
+  'approval.deny': 'Deny',
+  'approval.always': 'Always',
+  'approval.approved': 'Approved',
+  'approval.alwaysApproved': 'Always approved',
+  'approval.denied': 'Denied',
+  'approval.showParams': 'Show parameters',
+  'approval.hideParams': 'Hide parameters',
+  
+  // Authentication Required
+  'authRequired.title': 'Authentication required for {name}',
+  'authRequired.authenticateWith': 'Authenticate with {name}',
+  'authRequired.getToken': 'Get your token',
+  'authRequired.instructions': 'Instructions',
+  
+  // Sandbox Jobs
+  'sandbox.job': 'Sandbox Job',
+  'sandbox.doneSignal': 'Done signal sent',
+  
+  // Error Messages
+  'error.startConversation': 'Please start a conversation first',
+  'error.restartFailed': 'Restart failed: {message}',
+  'error.tokenRequired': 'Token required',
+  'error.tokenInvalid': 'Invalid token',
+  'error.connectionFailed': 'Connection failed',
+  'error.unknown': 'Unknown error',
+  'error.loadFailed': 'Failed to load: {message}',
+  
+  // Success Messages
+  'success.restartInitiated': 'Restart initiated',
+  'success.saved': 'Saved successfully',
+  
+  // Slash Commands
+  'cmd.status.desc': 'Show all jobs, or /status <id> for a specific job',
+  'cmd.list.desc': 'List all jobs',
+  'cmd.cancel.desc': '/cancel <job-id> — Cancel a running job',
+  'cmd.undo.desc': 'Undo last action',
+  'cmd.redo.desc': 'Redo undone action',
+  'cmd.compact.desc': 'Compact context window',
+  'cmd.clear.desc': 'Clear conversation and start fresh',
+  'cmd.interrupt.desc': 'Stop current operation',
+  'cmd.heartbeat.desc': 'Trigger manual heartbeat check',
+  'cmd.summarize.desc': 'Summarize current conversation',
+  'cmd.suggest.desc': 'Suggest next actions',
+  'cmd.help.desc': 'Show help',
+  'cmd.version.desc': 'Show version info',
+  'cmd.tools.desc': 'List available tools',
+  'cmd.skills.desc': 'List installed skills',
+  'cmd.model.desc': 'Show or switch LLM model',
+  'cmd.threadNew.desc': 'Create new conversation thread',
+  
+  // Language Switcher
+  'language.title': 'Language',
+  'language.en': 'English',
+  'language.zhCN': '简体中文',
+  'language.switch': 'Switch Language',
+  
+  // Tool Activity
+  'tool.thinking': 'Thinking...',
+  'tool.completed': 'Completed',
+  'tool.failed': 'Failed',
+  'tool.running': 'Running',
+  'tool.used': '{count} tool(s) used',
+  'tool.requiresApproval': 'Tool requires approval',
+  
+  
+  // TEE
+  'tee.loadingReport': 'Loading attestation report...',
+  'tee.loadFailed': 'Could not load attestation report',
+  
+  // Common
+  'common.loading': 'Loading...',
+  'common.noData': 'No data',
+  'common.search': 'Search',
+  'common.add': 'Add',
+  'common.remove': 'Remove',
+  'common.install': 'Install',
+  'common.activate': 'Activate',
+  'common.deactivate': 'Deactivate',
+  'common.configure': 'Configure',
+  'common.save': 'Save',
+  'common.cancel': 'Cancel',
+  'common.confirm': 'Confirm',
+  'common.close': 'Close',
+  'common.edit': 'Edit',
+  'common.delete': 'Delete',
+  'common.refresh': 'Refresh',
+  'common.searchPlaceholder': 'Search...',
+  'common.name': 'Name',
+  'common.description': 'Description',
+  'common.status': 'Status',
+  'common.actions': 'Actions',
+  'common.version': 'Version',
+  'common.owner': 'Owner',
+  'common.tags': 'Tags',
+  
+  // Extensions
+  'ext.active': 'Active',
+  'ext.remove': 'Remove',
+  'ext.install': 'Install',
+  'ext.installing': 'Installing...',
+  'ext.installed': 'Installed',
+  'ext.setup': 'Setup',
+  'ext.reconfigure': 'Reconfigure',
+  'ext.configure': 'Configure',
+  'ext.confirmRemove': 'Remove extension "{name}"?',
+  'ext.removeFailed': 'Remove failed: {message}',
+  'ext.removed': 'Removed {name}',
+  'ext.installFailed': 'Install failed: {message}',
+  
+  // Configure
+  'config.title': 'Configure {name}',
+  'config.optional': ' (optional)',
+  'config.alreadySet': '(already set — leave empty to keep)',
+  'config.alreadyConfigured': 'Already configured',
+  'config.autoGenerate': 'Auto-generated if empty',
+  'config.save': 'Save',
+  'config.cancel': 'Cancel',
+});

src/channels/web/static/i18n/index.js

@@ -0,0 +1,89 @@
+// Lightweight internationalization implementation with dynamic language switching
+
+const I18n = {
+  currentLang: 'en',
+  fallbackLang: 'en',
+  translations: {},
+  
+  // Initialize i18n
+  init() {
+    // Read user preference from localStorage
+    const savedLang = localStorage.getItem('ironclaw_language');
+    if (savedLang && this.translations[savedLang]) {
+      this.currentLang = savedLang;
+    } else {
+      // Detect browser language
+      const browserLang = navigator.language || navigator.userLanguage;
+      this.currentLang = browserLang.startsWith('zh') ? 'zh-CN' : 'en';
+    }
+    this.updateHtmlLang();
+  },
+  
+  // Register language pack
+  register(lang, translations) {
+    this.translations[lang] = translations;
+  },
+  
+  // Switch language
+  setLanguage(lang) {
+    if (this.translations[lang]) {
+      this.currentLang = lang;
+      localStorage.setItem('ironclaw_language', lang);
+      this.updateHtmlLang();
+      this.updatePageContent();
+      return true;
+    }
+    return false;
+  },
+  
+  // Get current language
+  getCurrentLang() {
+    return this.currentLang;
+  },
+  
+  // Translate function
+  t(key, params = {}) {
+    const translation = this.translations[this.currentLang]?.[key] 
+      || this.translations[this.fallbackLang]?.[key] 
+      || key;
+    
+    // Support placeholder replacement: {name}
+    return translation.replace(/\{(\w+)\}/g, (match, key) => {
+      return params[key] !== undefined ? params[key] : match;
+    });
+  },
+  
+  // Update HTML lang attribute
+  updateHtmlLang() {
+    document.documentElement.lang = this.currentLang;
+  },
+  
+  // Update page content (traverse all data-i18n elements)
+  updatePageContent() {
+    // Update text content
+    document.querySelectorAll('[data-i18n]').forEach(el => {
+      const key = el.getAttribute('data-i18n');
+      const attr = el.getAttribute('data-i18n-attr');
+      if (attr) {
+        el.setAttribute(attr, this.t(key));
+      } else {
+        el.textContent = this.t(key);
+      }
+    });
+    
+    // Update placeholder attributes
+    document.querySelectorAll('[data-i18n-placeholder]').forEach(el => {
+      const key = el.getAttribute('data-i18n-placeholder');
+      el.placeholder = this.t(key);
+    });
+    
+    // Update title attributes
+    document.querySelectorAll('[data-i18n-title]').forEach(el => {
+      const key = el.getAttribute('data-i18n-title');
+      el.title = this.t(key);
+    });
+  }
+};
+
+// Global access
+window.I18n = I18n;

src/channels/web/static/i18n/zh-CN.js

@@ -0,0 +1,351 @@
+// 中文语言包 for IronClaw
+
+I18n.register('zh-CN', {
+  // 认证页面
+  'auth.title': 'IronClaw',
+  'auth.tagline': '安全可靠的 AI 助手',
+  'auth.tokenLabel': '网关令牌',
+  'auth.tokenPlaceholder': '粘贴你的网关令牌',
+  'auth.connect': '连接',
+  'auth.errorRequired': '请输入令牌',
+  'auth.errorInvalid': '令牌无效',
+  'auth.hint': '输入 .env 配置文件中的 GATEWAY_AUTH_TOKEN',
+  
+  // 聊天
+  'chat.inputPlaceholder': '输入消息或 / 以使用命令...',
+  
+  // 重启弹窗
+  'restart.title': '重启 IronClaw 实例',
+  'restart.description': '确定要重启 IronClaw 实例吗？这将优雅地重启进程。',
+  'restart.warning': '正在运行的任务可能会中断。重启将在几秒钟内完成。',
+  'restart.cancel': '取消',
+  'restart.confirm': '确认重启',
+  'restart.progressTitle': '正在重启 IronClaw',
+  'restart.progressSubtitle': '请等待进程重启...',
+  'restart.checkLogs': '重启完成后，请查看日志标签页了解详情。',
+  
+  // 标签页
+  'tab.chat': '聊天',
+  'tab.memory': '记忆',
+  'tab.jobs': '任务',
+  'tab.routines': '定时任务',
+  'tab.extensions': '扩展',
+  'tab.skills': '技能',
+  'tab.logs': '日志',
+  
+  // 状态
+  'status.connected': '已连接',
+  'status.disconnected': '已断开',
+  'status.connecting': '连接中...',
+  'status.reconnecting': '重新连接中...',
+  'status.teeVerified': 'TEE 已验证',
+  'status.restart': '重启',
+  'status.active': '已激活',
+  'status.installed': '已安装',
+  'status.awaitingPairing': '等待配对',
+  
+  // 仪表盘
+  'dashboard.connections': '连接数',
+  'dashboard.uptime': '运行时间',
+  'dashboard.costToday': '今日费用',
+  'dashboard.spent': '已花费',
+  'dashboard.actionsPerHour': '每小时操作',
+  'dashboard.sse': 'SSE',
+  'dashboard.websocket': 'WebSocket',
+  
+  // 聊天标签页
+  'chat.newThread': '新对话',
+  'chat.toggleSidebar': '切换侧边栏',
+  'chat.assistant': '助手',
+  'chat.conversations': '对话列表',
+  'chat.send': '发送',
+  'chat.attachImages': '附加图片',
+  'chat.empty': '选择文件查看内容',
+  'chat.loading': '加载中...',
+  'chat.loadingOlder': '加载更早的消息...',
+  'chat.noFiles': '工作区没有文件',
+  'chat.noResults': '没有结果',
+  
+  // 对话侧边栏
+  'thread.assistant': '助手',
+  'thread.new': '新对话',
+  
+  // 记忆标签页
+  'memory.searchPlaceholder': '搜索记忆...',
+  'memory.workspace': '工作区',
+  'memory.edit': '编辑',
+  'memory.save': '保存',
+  'memory.cancel': '取消',
+  'memory.selectFile': '选择文件查看内容',
+  
+  // 任务标签页
+  'jobs.summary': '任务摘要',
+  'jobs.id': 'ID',
+  'jobs.title': '标题',
+  'jobs.source': '来源',
+  'jobs.status': '状态',
+  'jobs.created': '创建时间',
+  'jobs.actions': '操作',
+  'jobs.empty': '暂无任务',
+  'jobs.statusRunning': '运行中',
+  'jobs.statusCompleted': '已完成',
+  'jobs.statusFailed': '失败',
+  'jobs.statusPending': '等待中',
+  'jobs.jobId': '任务 ID',
+  'jobs.description': '描述',
+  'jobs.stateTransitions': '状态转换',
+  'jobs.projectFiles': '项目文件',
+  'jobs.noProjectFiles': '没有项目文件',
+  'jobs.viewJob': '查看任务',
+  'jobs.browse': '浏览',
+  
+  // 定时任务标签页
+  'routines.summary': '定时任务摘要',
+  'routines.name': '名称',
+  'routines.trigger': '触发器',
+  'routines.action': '操作',
+  'routines.lastRun': '上次运行',
+  'routines.nextRun': '下次运行',
+  'routines.runs': '运行次数',
+  'routines.status': '状态',
+  'routines.actions': '操作',
+  'routines.runsToday': '今日运行',
+  'routines.empty': '暂无定时任务',
+  'routines.noConfigured': '暂无配置的定时任务。请让助手创建一个。',
+  'routines.triggerFailed': '触发失败: {message}',
+  
+  // 日志标签页
+  'logs.serverLevel': '服务端日志级别',
+  'logs.clientLevel': '客户端日志级别',
+  'logs.pause': '暂停',
+  'logs.resume': '继续',
+  'logs.clear': '清空',
+  'logs.autoScroll': '自动滚动',
+  'logs.filter': '筛选日志...',
+  'logs.empty': '暂无日志',
+  'logs.allLevels': '所有级别',
+  'logs.error': '错误',
+  'logs.warn': '警告',
+  'logs.info': '信息',
+  'logs.debug': '调试',
+  
+  // 扩展标签页
+  'extensions.installed': '已安装扩展',
+  'extensions.available': '可用 WASM 扩展',
+  'extensions.installWasm': '安装 WASM 扩展',
+  'extensions.noInstalled': '没有安装扩展',
+  'extensions.noAvailable': '没有其他可用的 WASM 扩展',
+  'extensions.loading': '加载中...',
+  'extensions.install': '安装',
+  'extensions.installing': '安装中...',
+  'extensions.installedSuccess': '已安装 {name}',
+  'extensions.remove': '移除',
+  'extensions.activate': '激活',
+  'extensions.reconfigure': '重新配置',
+  'extensions.tools': '工具',
+  'extensions.noConfigNeeded': '{name} 不需要配置',
+  'extensions.configure': '配置 {name}',
+  'extensions.optional': ' (可选)',
+  'extensions.autoGenerated': '留空则自动生成',
+  'extensions.pendingPairing': '等待配对请求',
+  'extensions.from': '来自',
+  
+  // MCP 服务器
+  'mcp.servers': 'MCP 服务器',
+  'mcp.noServers': '没有可用的 MCP 服务器',
+  'mcp.addCustom': '添加自定义 MCP 服务器',
+  'mcp.add': '添加',
+  'mcp.addedSuccess': '已添加 MCP 服务器 {name}',
+  
+  // 注册工具
+  'tools.registered': '注册工具',
+  'tools.name': '名称',
+  'tools.description': '描述',
+  'tools.empty': '没有注册工具',
+  
+  // 技能标签页
+  'skills.installed': '已安装技能',
+  'skills.noInstalled': '没有安装技能',
+  'skills.searchClawHub': '搜索 ClawHub',
+  'skills.searchPlaceholder': '搜索...',
+  'skills.installByUrl': '通过 URL 安装技能',
+  'skills.namePlaceholder': '技能名称或标识',
+  'skills.urlPlaceholder': 'SKILL.md 的 HTTPS URL（可选）',
+  'skills.search': '搜索',
+  'skills.searching': '搜索中...',
+  'skills.noResults': '没有找到 "{query}" 相关技能',
+  'skills.searchFailed': '搜索失败: {message}',
+  'skills.install': '安装',
+  'skills.installing': '安装中...',
+  'skills.installedSuccess': '已安装技能 "{name}"',
+  'skills.remove': '移除',
+  'skills.activatesOn': '激活关键词',
+  'skills.registryError': '无法连接 ClawHub 注册表: {message}',
+  'skills.by': '作者',
+  'skills.updated': '更新于',
+  'skills.loading': '加载技能中...',
+  'skills.loadFailed': '加载技能失败: {message}',
+  'skills.confirmRemove': '确定要移除技能 "{name}" 吗？',
+  'skills.removeFailed': '移除失败: {message}',
+  'skills.removed': '已移除技能 "{name}"',
+  
+  // 任务摘要
+  'jobs.summary.total': '总计',
+  'jobs.summary.inProgress': '进行中',
+  'jobs.summary.completed': '已完成',
+  'jobs.summary.failed': '失败',
+  'jobs.summary.stuck': '卡住',
+  
+  // 定时任务摘要
+  'routines.summary.total': '总计',
+  'routines.summary.enabled': '已启用',
+  'routines.summary.disabled': '已禁用',
+  'routines.summary.failing': '失败',
+  'routines.summary.runsToday': '今日运行',
+  
+  // 按钮
+  'btn.close': '关闭',
+  'btn.cancel': '取消',
+  'btn.save': '保存',
+  'btn.edit': '编辑',
+  'btn.confirm': '确认',
+  'btn.send': '发送',
+  'btn.refresh': '刷新',
+  'btn.loadMore': '加载更多',
+  'btn.copy': '复制',
+  'btn.copied': '已复制!',
+  'btn.submit': '提交',
+  'btn.setup': '设置',
+  
+  // 时间
+  'time.lessThan1MinuteAgo': '刚刚',
+  'time.lessThan1MinuteFromNow': '1分钟内',
+  'time.minutesAgo': '{n}分钟前',
+  'time.minutesFromNow': '{n}分钟后',
+  'time.hoursAgo': '{n}小时前',
+  'time.hoursFromNow': '{n}小时后',
+  'time.daysAgo': '{n}天前',
+  'time.daysFromNow': '{n}天后',
+  
+  // 工具审批
+  'approval.title': '工具需要审批',
+  'approval.description': '一个工具请求运行权限。',
+  'approval.approve': '批准',
+  'approval.deny': '拒绝',
+  'approval.always': '始终允许',
+  'approval.approved': '已批准',
+  'approval.alwaysApproved': '始终批准',
+  'approval.denied': '已拒绝',
+  'approval.showParams': '显示参数',
+  'approval.hideParams': '隐藏参数',
+  
+  // 认证
+  'authRequired.title': '{name} 需要认证',
+  'authRequired.authenticateWith': '使用 {name} 认证',
+  'authRequired.getToken': '获取令牌',
+  'authRequired.instructions': '说明',
+  
+  // 沙盒任务
+  'sandbox.job': '沙盒任务',
+  'sandbox.doneSignal': '完成信号已发送',
+  
+  // 错误消息
+  'error.startConversation': '请先开始一个对话',
+  'error.restartFailed': '重启失败: {message}',
+  'error.tokenRequired': '请输入令牌',
+  'error.tokenInvalid': '令牌无效',
+  'error.connectionFailed': '连接失败',
+  'error.unknown': '未知错误',
+  'error.loadFailed': '加载失败: {message}',
+  
+  // 成功消息
+  'success.restartInitiated': '已开始重启',
+  'success.saved': '保存成功',
+  
+  // 斜杠命令
+  'cmd.status.desc': '显示所有任务，或使用 /status <id> 查看特定任务',
+  'cmd.list.desc': '列出所有任务',
+  'cmd.cancel.desc': '/cancel <job-id> — 取消正在运行的任务',
+  'cmd.undo.desc': '撤销上一步',
+  'cmd.redo.desc': '重做已撤销的操作',
+  'cmd.compact.desc': '压缩上下文窗口',
+  'cmd.clear.desc': '清空对话并重新开始',
+  'cmd.interrupt.desc': '停止当前操作',
+  'cmd.heartbeat.desc': '触发手动心跳检查',
+  'cmd.summarize.desc': '总结当前对话',
+  'cmd.suggest.desc': '建议下一步操作',
+  'cmd.help.desc': '显示帮助',
+  'cmd.version.desc': '显示版本信息',
+  'cmd.tools.desc': '列出可用工具',
+  'cmd.skills.desc': '列出已安装的 AI 技能',
+  'cmd.model.desc': '显示或切换 LLM 模型',
+  'cmd.threadNew.desc': '创建新对话线程',
+  
+  // 语言切换
+  'language.title': '语言',
+  'language.en': 'English',
+  'language.zhCN': '简体中文',
+  'language.switch': '切换语言',
+  
+  // 工具活动
+  'tool.thinking': '思考中...',
+  'tool.completed': '已完成',
+  'tool.failed': '失败',
+  'tool.running': '运行中',
+  'tool.used': '{count} 个工具已使用',
+  'tool.requiresApproval': '工具需要审批',
+  
+  
+  // TEE
+  'tee.loadingReport': '正在加载证明报告...',
+  'tee.loadFailed': '无法加载证明报告',
+  
+  // 通用
+  'common.loading': '加载中...',
+  'common.noData': '暂无数据',
+  'common.search': '搜索',
+  'common.add': '添加',
+  'common.remove': '移除',
+  'common.install': '安装',
+  'common.activate': '激活',
+  'common.deactivate': '停用',
+  'common.configure': '配置',
+  'common.save': '保存',
+  'common.cancel': '取消',
+  'common.confirm': '确认',
+  'common.close': '关闭',
+  'common.edit': '编辑',
+  'common.delete': '删除',
+  'common.refresh': '刷新',
+  'common.searchPlaceholder': '搜索...',
+  'common.name': '名称',
+  'common.description': '描述',
+  'common.status': '状态',
+  'common.actions': '操作',
+  'common.version': '版本',
+  'common.owner': '作者',
+  'common.tags': '标签',
+  
+  // 扩展
+  'ext.active': '已激活',
+  'ext.remove': '移除',
+  'ext.install': '安装',
+  'ext.installing': '安装中...',
+  'ext.installed': '已安装',
+  'ext.setup': '设置',
+  'ext.reconfigure': '重新配置',
+  'ext.configure': '配置',
+  'ext.confirmRemove': '确定要移除扩展 "{name}" 吗？',
+  'ext.removeFailed': '移除失败: {message}',
+  'ext.removed': '已移除 {name}',
+  'ext.installFailed': '安装失败: {message}',
+  
+  // 配置
+  'config.title': '配置 {name}',
+  'config.optional': '（可选）',
+  'config.alreadySet': '（已设置 — 留空以保持不变）',
+  'config.alreadyConfigured': '已配置',
+  'config.autoGenerate': '如果为空则自动生成',
+  'config.save': '保存',
+  'config.cancel': '取消',
+});

src/channels/web/static/index.html

@@ -9,6 +9,17 @@
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="/style.css">
+  
+  <!-- i18n Modules -->
+  <script src="/i18n/index.js"></script>
+  <script src="/i18n/en.js"></script>
+  <script src="/i18n/zh-CN.js"></script>
+  
+  <script
+    src="https://cdnjs.cloudflare.com/ajax/libs/dompurify/3.2.3/purify.min.js"
+    integrity="sha384-osZDKVu4ipZP703HmPOhWdyBajcFyjX2Psjk//TG1Rc0AdwEtuToaylrmcK3LdAl"
+    crossorigin="anonymous"
+  ></script>
   <script
     src="https://cdn.jsdelivr.net/npm/[email protected]/lib/marked.umd.min.js"
     integrity="sha384-pN9zSKOnTZwXRtYZAu0PBPEgR2B7DOC1aeLxQ33oJ0oy5iN1we6gm57xldM2irDG"
@@ -20,16 +31,16 @@
   <div id="auth-screen">
     <div class="auth-card-login">
       <div class="auth-brand">
-        <h1>IronClaw</h1>
-        <p class="auth-tagline">Secure AI Assistant</p>
+        <h1 data-i18n="auth.title">IronClaw</h1>
+        <p class="auth-tagline" data-i18n="auth.tagline">Secure AI Assistant</p>
       </div>
       <div class="auth-form">
-        <label for="token-input">Gateway Token</label>
-        <input type="password" id="token-input" placeholder="Paste your auth token" autofocus>
-        <button onclick="authenticate()">Connect</button>
+        <label for="token-input" data-i18n="auth.tokenLabel">Gateway Token</label>
+        <input type="password" id="token-input" data-i18n="auth.tokenPlaceholder" data-i18n-attr="placeholder" placeholder="Paste your auth token" autofocus>
+        <button onclick="authenticate()" data-i18n="auth.connect">Connect</button>
       </div>
       <div id="auth-error"></div>
-      <p class="auth-hint">Enter the GATEWAY_AUTH_TOKEN from your .env configuration.</p>
+      <p class="auth-hint" data-i18n="auth.hint">Enter the GATEWAY_AUTH_TOKEN from your .env configuration.</p>
     </div>
   </div>
 
@@ -38,21 +49,22 @@
     <div class="restart-modal-overlay" onclick="cancelRestart()"></div>
     <div class="restart-modal-content">
       <div class="restart-modal-header">
-        <h2>Restart IronClaw Instance</h2>
-        <button class="restart-modal-close" onclick="cancelRestart()" title="Close">×</button>
+        <h2 data-i18n="restart.title">Restart IronClaw Instance</h2>
+        <button class="restart-modal-close" onclick="cancelRestart()" data-i18n="restart.closeTooltip" data-i18n-attr="title"
+          title="Close">×</button>
       </div>
       <div class="restart-modal-body">
-        <p class="restart-modal-description">
+        <p class="restart-modal-description" data-i18n="restart.description">
           Are you sure you want to restart the IronClaw instance? This will gracefully restart the process.
         </p>
         <div class="restart-modal-warning">
           <span class="restart-modal-warning-icon">⚠️</span>
-          <p>Any in-progress jobs may be interrupted. The restart will complete within a few seconds.</p>
+          <p data-i18n="restart.warning">Any in-progress jobs may be interrupted. The restart will complete within a few seconds.</p>
         </div>
       </div>
       <div class="restart-modal-footer">
-        <button class="restart-modal-btn cancel" onclick="cancelRestart()">Cancel</button>
-        <button class="restart-modal-btn confirm" onclick="confirmRestart()">Confirm Restart</button>
+        <button class="restart-modal-btn cancel" onclick="cancelRestart()" data-i18n="restart.cancel">Cancel</button>
+        <button class="restart-modal-btn confirm" onclick="confirmRestart()" data-i18n="restart.confirm">Confirm Restart</button>
       </div>
     </div>
   </div>
@@ -63,13 +75,13 @@
     <div class="restart-loader-content">
       <div class="restart-spinner"></div>
       <div class="restart-loader-text">
-        <p class="restart-title">Restarting IronClaw</p>
-        <p class="restart-subtitle">Please wait while the process restarts...</p>
+        <p class="restart-title" data-i18n="restart.progressTitle">Restarting IronClaw</p>
+        <p class="restart-subtitle" data-i18n="restart.progressSubtitle">Please wait while the process restarts...</p>
       </div>
       <div class="restart-progress-bar">
         <div class="restart-progress-fill"></div>
       </div>
-      <p class="restart-modal-info">
+      <p class="restart-modal-info" data-i18n="restart.checkLogs">
         Check the Logs tab for details after the restart completes.
       </p>
     </div>
@@ -79,33 +91,45 @@
   <div id="app">
     <!-- Tab Bar -->
     <div class="tab-bar">
-      <button class="active" data-tab="chat">Chat</button>
-      <button data-tab="memory">Memory</button>
-      <button data-tab="jobs">Jobs</button>
-      <button data-tab="routines">Routines</button>
-      <button data-tab="extensions">Extensions</button>
-      <button data-tab="skills">Skills</button>
+      <button class="active" data-tab="chat" data-i18n="tab.chat">Chat</button>
+      <button data-tab="memory" data-i18n="tab.memory">Memory</button>
+      <button data-tab="jobs" data-i18n="tab.jobs">Jobs</button>
+      <button data-tab="routines" data-i18n="tab.routines">Routines</button>
+      <button data-tab="extensions" data-i18n="tab.extensions">Extensions</button>
+      <button data-tab="skills" data-i18n="tab.skills">Skills</button>
       <div class="spacer"></div>
-      <button class="status-logs-btn" data-tab="logs" title="Logs">Logs</button>
+      
+      <!-- Language Switcher -->
+      <div class="language-switcher">
+        <button class="language-btn" id="language-btn" type="button" onclick="toggleLanguageMenu()" title="Switch Language"
+          aria-label="Switch language" aria-haspopup="true" aria-expanded="false" aria-controls="language-menu">🌐</button>
+        <div class="language-menu" id="language-menu" style="display: none;">
+          <button type="button" class="language-option" onclick="switchLanguage('en')" data-lang="en">English</button>
+          <button type="button" class="language-option" onclick="switchLanguage('zh-CN')" data-lang="zh-CN">简体中文</button>
+        </div>
+      </div>
+      
+      <button class="status-logs-btn" data-tab="logs" data-i18n="tab.logs" title="Logs">Logs</button>
       <div class="tee-shield" id="tee-shield" style="display:none" title="Running in a Trusted Execution Environment">
         <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
           <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>
         </svg>
-        <span id="tee-shield-label">TEE Verified</span>
+        <span id="tee-shield-label" data-i18n="status.teeVerified">TEE Verified</span>
         <div class="tee-popover" id="tee-popover"></div>
       </div>
       <div class="status" id="gateway-status-trigger">
         <div class="dot" id="sse-dot"></div>
-        <span id="sse-status">Connected</span>
+        <span id="sse-status" data-i18n="status.connected">Connected</span>
         <div class="gateway-popover" id="gateway-popover"></div>
       </div>
-      <button class="restart-btn" id="restart-btn" onclick="triggerRestart()" title="Gracefully restart the process" style="display: none;">
+      <button class="restart-btn" id="restart-btn" onclick="triggerRestart()" data-i18n="status.restartTooltip"
+        data-i18n-attr="title" title="Gracefully restart the process" style="display: none;">
         <svg id="restart-icon" width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
           <path d="M23 4v6h-6"></path>
           <path d="M1 20v-6h6"></path>
           <path d="M3.51 9a9 9 0 0114.85-3.36M20.49 15a9 9 0 01-14.85 3.36"></path>
         </svg>
-        <span>Restart</span>
+        <span data-i18n="status.restart">Restart</span>
       </button>
     </div>
 
@@ -113,16 +137,18 @@
     <div class="tab-panel active" id="tab-chat">
       <div class="thread-sidebar" id="thread-sidebar">
         <div class="thread-sidebar-header">
-          <button class="thread-new-btn" onclick="createNewThread()" title="New thread (Ctrl/Cmd+N)">+</button>
+          <button class="thread-new-btn" onclick="createNewThread()" data-i18n="chat.newThread" data-i18n-attr="title"
+            title="New thread (Ctrl/Cmd+N)">+</button>
           <div class="spacer"></div>
-          <button class="thread-toggle-btn" id="thread-toggle-btn" onclick="toggleThreadSidebar()" title="Toggle sidebar">&laquo;</button>
+          <button class="thread-toggle-btn" id="thread-toggle-btn" onclick="toggleThreadSidebar()" data-i18n="chat.toggleSidebar"
+            data-i18n-attr="title" title="Toggle sidebar">&laquo;</button>
         </div>
         <div class="assistant-item" id="assistant-thread" onclick="switchToAssistant()">
-          <span class="assistant-label" id="assistant-label">Assistant</span>
+          <span class="assistant-label" id="assistant-label" data-i18n="chat.assistant">Assistant</span>
           <span class="assistant-meta" id="assistant-meta"></span>
         </div>
         <div class="threads-section-header">
-          <span>Conversations</span>
+          <span data-i18n="chat.conversations">Conversations</span>
         </div>
         <div class="thread-list" id="thread-list"></div>
       </div>
@@ -131,10 +157,11 @@
         <div id="slash-autocomplete" class="slash-autocomplete" style="display:none"></div>
         <div class="chat-input">
           <div id="image-preview-strip" class="image-preview-strip"></div>
-          <textarea id="chat-input" placeholder="Message or / for commands..." rows="1"></textarea>
+          <textarea id="chat-input" data-i18n="chat.inputPlaceholder" data-i18n-attr="placeholder" placeholder="Message or / for commands..." rows="1"></textarea>
           <input type="file" id="image-file-input" accept="image/*" multiple style="display:none">
-          <button id="attach-btn" class="attach-btn" title="Attach images" aria-label="Attach images">&#x1F4CE;</button>
-          <button id="send-btn" onclick="sendMessage()">Send</button>
+          <button id="attach-btn" class="attach-btn" data-i18n="chat.attachImages" data-i18n-attr="title" title="Attach images"
+            aria-label="Attach images">&#x1F4CE;</button>
+          <button id="send-btn" onclick="sendMessage()" data-i18n="chat.send">Send</button>
         </div>
       </div>
     </div>
@@ -144,23 +171,23 @@
       <div class="memory-container">
         <div class="memory-sidebar">
           <div class="search-box">
-            <input type="text" id="memory-search" placeholder="Search memory...">
+            <input type="text" id="memory-search" data-i18n="memory.searchPlaceholder" data-i18n-attr="placeholder" placeholder="Search memory...">
           </div>
           <div class="memory-tree" id="memory-tree"></div>
         </div>
         <div class="memory-content">
           <div class="memory-breadcrumb" id="memory-breadcrumb">
             <span id="memory-breadcrumb-path">workspace /</span>
-            <button class="memory-edit-btn" id="memory-edit-btn" style="display:none" onclick="startMemoryEdit()">Edit</button>
+            <button class="memory-edit-btn" id="memory-edit-btn" style="display:none" onclick="startMemoryEdit()" data-i18n="memory.edit">Edit</button>
           </div>
           <div class="memory-viewer" id="memory-viewer">
-            <div class="empty">Select a file to view its contents</div>
+            <div class="empty" data-i18n="memory.selectFile">Select a file to view its contents</div>
           </div>
           <div class="memory-editor" id="memory-editor" style="display:none">
             <textarea id="memory-edit-textarea"></textarea>
             <div class="memory-editor-actions">
-              <button class="btn-save" onclick="saveMemoryEdit()">Save</button>
-              <button class="btn-cancel-edit" onclick="cancelMemoryEdit()">Cancel</button>
+              <button class="btn-save" onclick="saveMemoryEdit()" data-i18n="memory.save">Save</button>
+              <button class="btn-cancel-edit" onclick="cancelMemoryEdit()" data-i18n="memory.cancel">Cancel</button>
             </div>
           </div>
         </div>
@@ -174,17 +201,17 @@
         <table class="jobs-table" id="jobs-table">
           <thead>
             <tr>
-              <th>ID</th>
-              <th>Title</th>
-              <th>Source</th>
-              <th>Status</th>
-              <th>Created</th>
-              <th>Actions</th>
+              <th data-i18n="jobs.id">ID</th>
+              <th data-i18n="jobs.title">Title</th>
+              <th data-i18n="jobs.source">Source</th>
+              <th data-i18n="jobs.status">Status</th>
+              <th data-i18n="jobs.created">Created</th>
+              <th data-i18n="jobs.actions">Actions</th>
             </tr>
           </thead>
           <tbody id="jobs-tbody"></tbody>
         </table>
-        <div class="empty-state" id="jobs-empty" style="display:none">No jobs found</div>
+        <div class="empty-state" id="jobs-empty" style="display:none" data-i18n="jobs.empty">No jobs found</div>
       </div>
     </div>
 
@@ -199,16 +226,16 @@
             <option value="debug">Server: DEBUG</option>
           </select>
           <select id="logs-level-filter">
-            <option value="all">All Levels</option>
-            <option value="ERROR">Error</option>
-            <option value="WARN">Warn</option>
-            <option value="INFO">Info</option>
-            <option value="DEBUG">Debug</option>
+            <option value="all" data-i18n="logs.allLevels">All Levels</option>
+            <option value="ERROR" data-i18n="logs.error">Error</option>
+            <option value="WARN" data-i18n="logs.warn">Warn</option>
+            <option value="INFO" data-i18n="logs.info">Info</option>
+            <option value="DEBUG" data-i18n="logs.debug">Debug</option>
           </select>
           <input type="text" id="logs-target-filter" placeholder="Filter by target...">
-          <label class="logs-checkbox"><input type="checkbox" id="logs-autoscroll" checked> Auto-scroll</label>
-          <button id="logs-pause-btn" onclick="toggleLogsPause()">Pause</button>
-          <button onclick="clearLogs()">Clear</button>
+          <label class="logs-checkbox"><input type="checkbox" id="logs-autoscroll" checked> <span data-i18n="logs.autoScroll">Auto-scroll</span></label>
+          <button id="logs-pause-btn" onclick="toggleLogsPause()" data-i18n="logs.pause">Pause</button>
+          <button onclick="clearLogs()" data-i18n="logs.clear">Clear</button>
         </div>
         <div class="logs-output" id="logs-output"></div>
       </div>
@@ -221,20 +248,20 @@
         <table class="routines-table" id="routines-table">
           <thead>
             <tr>
-              <th>Name</th>
-              <th>Trigger</th>
-              <th>Action</th>
-              <th>Last Run</th>
-              <th>Next Run</th>
-              <th>Runs</th>
-              <th>Status</th>
-              <th>Actions</th>
+              <th data-i18n="routines.name">Name</th>
+              <th data-i18n="routines.trigger">Trigger</th>
+              <th data-i18n="routines.action">Action</th>
+              <th data-i18n="routines.lastRun">Last Run</th>
+              <th data-i18n="routines.nextRun">Next Run</th>
+              <th data-i18n="routines.runs">Runs</th>
+              <th data-i18n="routines.status">Status</th>
+              <th data-i18n="routines.actions">Actions</th>
             </tr>
           </thead>
           <tbody id="routines-tbody"></tbody>
         </table>
         <div class="empty-state" id="routines-empty" style="display:none">
-          No routines configured. Ask the assistant to create one.
+          <span data-i18n="routines.noConfigured">No routines configured. Ask the assistant to create one.</span>
         </div>
         <div class="routine-detail" id="routine-detail" style="display:none"></div>
       </div>
@@ -244,44 +271,44 @@
     <div class="tab-panel" id="tab-extensions">
       <div class="extensions-container">
         <div class="extensions-section">
-          <h3>Installed Extensions</h3>
+          <h3 data-i18n="extensions.installed">Installed Extensions</h3>
           <div class="extensions-list" id="extensions-list">
-            <div class="empty-state">Loading extensions...</div>
+            <div class="empty-state" data-i18n="common.loading">Loading...</div>
           </div>
         </div>
         <div class="extensions-section" id="available-wasm-section">
-          <h3>Available WASM Extensions</h3>
+          <h3 data-i18n="extensions.available">Available WASM Extensions</h3>
           <div class="extensions-list" id="available-wasm-list">
-            <div class="empty-state">Loading...</div>
+            <div class="empty-state" data-i18n="common.loading">Loading...</div>
           </div>
         </div>
         <div class="extensions-section">
-          <h3>Install WASM Extension</h3>
+          <h3 data-i18n="extensions.installWasm">Install WASM Extension</h3>
           <div class="ext-install-form">
-            <input type="text" id="wasm-install-name" placeholder="Extension name">
+            <input type="text" id="wasm-install-name" data-i18n-placeholder="common.name" placeholder="Extension name">
             <input type="text" id="wasm-install-url" placeholder="URL to .tar.gz bundle">
-            <button onclick="installWasmExtension()">Install</button>
+            <button onclick="installWasmExtension()" data-i18n="extensions.install">Install</button>
           </div>
         </div>
         <div class="extensions-section">
-          <h3>MCP Servers</h3>
+          <h3 data-i18n="mcp.servers">MCP Servers</h3>
           <div class="extensions-list" id="mcp-servers-list">
-            <div class="empty-state">Loading...</div>
+            <div class="empty-state" data-i18n="common.loading">Loading...</div>
           </div>
-          <h4>Add Custom MCP Server</h4>
+          <h4 data-i18n="mcp.addCustom">Add Custom MCP Server</h4>
           <div class="ext-install-form">
-            <input type="text" id="mcp-install-name" placeholder="Server name">
+            <input type="text" id="mcp-install-name" data-i18n-placeholder="common.name" placeholder="Server name">
             <input type="text" id="mcp-install-url" placeholder="MCP server URL (https://...)">
-            <button onclick="addMcpServer()">Add</button>
+            <button onclick="addMcpServer()" data-i18n="mcp.add">Add</button>
           </div>
         </div>
         <div class="extensions-section">
-          <h3>Registered Tools</h3>
+          <h3 data-i18n="tools.registered">Registered Tools</h3>
           <table class="tools-table" id="tools-table">
-            <thead><tr><th>Name</th><th>Description</th></tr></thead>
+            <thead><tr><th data-i18n="tools.name">Name</th><th data-i18n="tools.description">Description</th></tr></thead>
             <tbody id="tools-tbody"></tbody>
           </table>
-          <div class="empty-state" id="tools-empty" style="display:none">No tools registered</div>
+          <div class="empty-state" id="tools-empty" style="display:none" data-i18n="tools.empty">No tools registered</div>
         </div>
       </div>
     </div>
@@ -290,25 +317,25 @@
     <div class="tab-panel" id="tab-skills">
       <div class="extensions-container">
         <div class="extensions-section">
-          <h3>Search ClawHub</h3>
+          <h3 data-i18n="skills.searchClawHub">Search ClawHub</h3>
           <div class="skill-search-box">
-            <input type="text" id="skill-search-input" placeholder="Search for skills...">
-            <button onclick="searchClawHub()">Search</button>
+            <input type="text" id="skill-search-input" data-i18n-placeholder="skills.searchPlaceholder" placeholder="Search...">
+            <button onclick="searchClawHub()" data-i18n="skills.search">Search</button>
           </div>
           <div class="extensions-list" id="skill-search-results"></div>
         </div>
         <div class="extensions-section">
-          <h3>Installed Skills</h3>
+          <h3 data-i18n="skills.installed">Installed Skills</h3>
           <div class="extensions-list" id="skills-list">
-            <div class="empty-state">Loading skills...</div>
+            <div class="empty-state" data-i18n="skills.loading">Loading skills...</div>
           </div>
         </div>
         <div class="extensions-section">
-          <h3>Install Skill by URL</h3>
+          <h3 data-i18n="skills.installByUrl">Install Skill by URL</h3>
           <div class="ext-install-form">
-            <input type="text" id="skill-install-name" placeholder="Skill name or slug">
-            <input type="text" id="skill-install-url" placeholder="HTTPS URL to SKILL.md (optional)">
-            <button onclick="installSkillFromForm()">Install</button>
+            <input type="text" id="skill-install-name" data-i18n-placeholder="skills.namePlaceholder" placeholder="Skill name or slug">
+            <input type="text" id="skill-install-url" data-i18n-placeholder="skills.urlPlaceholder" placeholder="HTTPS URL to SKILL.md (optional)">
+            <button onclick="installSkillFromForm()" data-i18n="extensions.install">Install</button>
           </div>
         </div>
       </div>
@@ -317,5 +344,6 @@
 
   <div id="toasts"></div>
   <script src="/app.js"></script>
+  <script src="/i18n-app.js"></script>
 </body>
 </html>

src/channels/web/static/style.css

@@ -9,6 +9,7 @@
   --text-secondary: #a1a1aa;
   --accent: #34d399;
   --accent-hover: #2fc48d;
+  --accent-soft: rgba(52, 211, 153, 0.15);
   --success: #34d399;
   --warning: #F5A623;
   --danger: #E64C4C;
@@ -655,11 +656,11 @@ body {
   padding: 16px;
   display: flex;
   flex-direction: column;
-  gap: 12px;
+  gap: 16px;
 }
 
 .message {
-  max-width: 80%;
+  max-width: 72%;
   padding: 10px 14px;
   border-radius: var(--radius);
   font-size: 14px;
@@ -669,8 +670,8 @@ body {
 
 .message.user {
   align-self: flex-end;
-  background: var(--accent);
-  color: #09090b;
+  background: var(--accent-soft);
+  color: var(--accent);
   border-bottom-right-radius: 2px;
   white-space: pre-wrap;
 }
@@ -680,6 +681,9 @@ body {
   background: var(--bg-secondary);
   border: 1px solid var(--border);
   border-bottom-left-radius: 2px;
+  padding: 14px 18px;
+  font-size: 15px;
+  line-height: 1.6;
 }
 
 .message.system {
@@ -710,10 +714,10 @@ body {
   padding: 0;
 }
 
-.message p { margin: 0 0 8px 0; }
+.message p { margin: 0 0 10px 0; }
 .message p:last-child { margin-bottom: 0; }
 .message ul, .message ol { margin: 4px 0; padding-left: 20px; }
-.message li { margin: 2px 0; }
+.message li { margin: 4px 0; }
 .message blockquote {
   margin: 6px 0;
   padding: 4px 12px;
@@ -1062,7 +1066,7 @@ body {
 }
 
 .approval-card .approval-actions button:disabled {
-  opacity: 0.4;
+  opacity: 0.5;
   cursor: not-allowed;
 }
 
@@ -1241,7 +1245,7 @@ body {
 }
 
 .auth-card .auth-actions button:disabled {
-  opacity: 0.4;
+  opacity: 0.5;
   cursor: not-allowed;
 }
 
@@ -1277,6 +1281,8 @@ body {
   gap: 8px;
   background: var(--bg-secondary);
   border-top: 1px solid var(--border);
+  flex-shrink: 0;
+  min-height: 56px;
 }
 
 .chat-input textarea {
@@ -1299,6 +1305,11 @@ body {
   box-shadow: 0 0 0 3px rgba(52, 211, 153, 0.1);
 }
 
+.chat-input textarea:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
 .chat-input button {
   padding: 8px 20px;
   background: var(--accent);
@@ -1312,7 +1323,7 @@ body {
   transition: background 0.2s, transform 0.2s;
 }
 
-.chat-input button:hover {
+.chat-input button:hover:not(:disabled) {
   background: var(--accent-hover);
   transform: translateY(-1px);
 }
@@ -1322,8 +1333,18 @@ body {
 }
 
 .chat-input button:disabled {
-  opacity: 0.5;
+  opacity: 0.6;
   cursor: not-allowed;
+  transform: none;
+}
+
+/* Keyboard accessibility focus rings */
+.chat-input textarea:focus-visible,
+.chat-input button:focus-visible,
+.tab-bar button:focus-visible,
+.tree-row:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
 }
 
 /* Memory Tab */
@@ -1423,7 +1444,7 @@ body {
   color: var(--text-secondary);
 }
 
-.tree-label.file:hover {
+.tree-row:hover .tree-label.file {
   color: var(--accent);
 }
 
@@ -2305,7 +2326,7 @@ body {
 }
 
 .log-entry:hover {
-  background: var(--bg-secondary);
+  background: var(--bg-tertiary);
 }
 
 .log-ts {
@@ -3720,6 +3741,21 @@ mark {
   .ext-install-form input {
     width: 100%;
   }
+
+  /* Chat input: ensure visibility on mobile */
+  .chat-input {
+    min-height: 52px;
+  }
+
+  .chat-input textarea {
+    min-height: 36px;
+    max-height: 100px;
+  }
+
+  .chat-input button {
+    padding: 6px 16px;
+    font-size: 14px;
+  }
 }
 
 /* Slash command autocomplete dropdown */
@@ -3764,7 +3800,7 @@ mark {
 }
 
 /* Image Upload */
-.attach-btn {
+.chat-input .attach-btn {
   background: none;
   border: none;
   cursor: pointer;
@@ -3777,10 +3813,13 @@ mark {
   display: flex;
   align-items: center;
   justify-content: center;
+  font-weight: 400;
 }
 
-.attach-btn:hover {
+.chat-input .attach-btn:hover {
+  background: none;
   color: var(--text);
+  transform: none;
 }
 
 .image-preview-strip {
@@ -3846,6 +3885,61 @@ mark {
   display: block;
 }
 
+/* Language Switcher */
+.language-switcher {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.language-btn {
+  background: transparent;
+  border: none;
+  color: var(--text-secondary);
+  cursor: pointer;
+  padding: 8px;
+  font-size: 16px;
+  border-radius: var(--radius);
+  transition: all 0.2s;
+}
+
+.language-btn:hover {
+  color: var(--text);
+  background: var(--bg-tertiary);
+}
+
+.language-menu {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  margin-top: 4px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 4px;
+  min-width: 120px;
+  z-index: 1000;
+  box-shadow: var(--shadow);
+}
+
+.language-option {
+  padding: 8px 12px;
+  cursor: pointer;
+  border-radius: var(--radius);
+  color: var(--text);
+  font-size: 13px;
+  transition: all 0.2s;
+}
+
+.language-option:hover {
+  background: var(--bg-tertiary);
+}
+
+.language-option.active {
+  background: var(--accent);
+  color: var(--bg);
+}
+
 .generated-image-path {
   font-size: 12px;
   color: var(--text-secondary);

src/channels/web/test_helpers.rs

@@ -82,6 +82,7 @@ impl TestGatewayBuilder {
             skill_catalog: None,
             scheduler: None,
             chat_rate_limiter: RateLimiter::new(30, 60),
+            oauth_rate_limiter: RateLimiter::new(10, 60),
             registry_entries: Vec::new(),
             cost_guard: None,
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),

src/channels/web/types.rs

@@ -735,6 +735,60 @@ pub struct RoutineInfo {
     pub status: String,
 }
 
+impl RoutineInfo {
+    /// Convert a `Routine` to the trimmed `RoutineInfo` for list display.
+    pub fn from_routine(r: &crate::agent::routine::Routine) -> Self {
+        let (trigger_type, trigger_summary) = match &r.trigger {
+            crate::agent::routine::Trigger::Cron { schedule, .. } => {
+                ("cron".to_string(), format!("cron: {}", schedule))
+            }
+            crate::agent::routine::Trigger::Event {
+                pattern, channel, ..
+            } => {
+                let ch = channel.as_deref().unwrap_or("any");
+                ("event".to_string(), format!("on {} /{}/", ch, pattern))
+            }
+            crate::agent::routine::Trigger::SystemEvent {
+                source, event_type, ..
+            } => (
+                "system_event".to_string(),
+                format!("event: {}.{}", source, event_type),
+            ),
+            crate::agent::routine::Trigger::Manual => {
+                ("manual".to_string(), "manual only".to_string())
+            }
+        };
+
+        let action_type = match &r.action {
+            crate::agent::routine::RoutineAction::Lightweight { .. } => "lightweight",
+            crate::agent::routine::RoutineAction::FullJob { .. } => "full_job",
+        };
+
+        let status = if !r.enabled {
+            "disabled"
+        } else if r.consecutive_failures > 0 {
+            "failing"
+        } else {
+            "active"
+        };
+
+        RoutineInfo {
+            id: r.id,
+            name: r.name.clone(),
+            description: r.description.clone(),
+            enabled: r.enabled,
+            trigger_type,
+            trigger_summary,
+            action_type: action_type.to_string(),
+            last_run_at: r.last_run_at.map(|dt| dt.to_rfc3339()),
+            next_fire_at: r.next_fire_at.map(|dt| dt.to_rfc3339()),
+            run_count: r.run_count,
+            consecutive_failures: r.consecutive_failures,
+            status: status.to_string(),
+        }
+    }
+}
+
 #[derive(Debug, Serialize)]
 pub struct RoutineListResponse {
     pub routines: Vec<RoutineInfo>,

src/channels/web/ws.rs

@@ -255,43 +255,31 @@ async fn handle_client_message(
             token,
         } => {
             if let Some(ref ext_mgr) = state.extension_manager {
-                match ext_mgr.auth(&extension_name, Some(&token)).await {
-                    Ok(result) if result.is_authenticated() => {
-                        let msg = match ext_mgr.activate(&extension_name).await {
-                            Ok(r) => format!(
-                                "{} authenticated ({} tools loaded)",
-                                extension_name,
-                                r.tools_loaded.len()
-                            ),
-                            Err(e) => format!(
-                                "{} authenticated but activation failed: {}",
-                                extension_name, e
-                            ),
-                        };
+                match ext_mgr.configure_token(&extension_name, &token).await {
+                    Ok(result) => {
                         crate::channels::web::server::clear_auth_mode(state).await;
                         state
                             .sse
                             .broadcast(crate::channels::web::types::SseEvent::AuthCompleted {
                                 extension_name,
                                 success: true,
-                                message: msg,
-                            });
-                    }
-                    Ok(result) => {
-                        state
-                            .sse
-                            .broadcast(crate::channels::web::types::SseEvent::AuthRequired {
-                                extension_name,
-                                instructions: result.instructions().map(String::from),
-                                auth_url: result.auth_url().map(String::from),
-                                setup_url: result.setup_url().map(String::from),
+                                message: result.message,
                             });
                     }
                     Err(e) => {
+                        let msg = format!("Auth failed: {}", e);
+                        if matches!(e, crate::extensions::ExtensionError::ValidationFailed(_)) {
+                            state.sse.broadcast(
+                                crate::channels::web::types::SseEvent::AuthRequired {
+                                    extension_name: extension_name.clone(),
+                                    instructions: Some(msg.clone()),
+                                    auth_url: None,
+                                    setup_url: None,
+                                },
+                            );
+                        }
                         let _ = direct_tx
-                            .send(WsServerMessage::Error {
-                                message: format!("Auth failed: {}", e),
-                            })
+                            .send(WsServerMessage::Error { message: msg })
                             .await;
                     }
                 }
@@ -509,6 +497,7 @@ mod tests {
             skill_registry: None,
             skill_catalog: None,
             chat_rate_limiter: crate::channels::web::server::RateLimiter::new(30, 60),
+            oauth_rate_limiter: crate::channels::web::server::RateLimiter::new(10, 60),
             registry_entries: Vec::new(),
             cost_guard: None,
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),

src/channels/webhook_server.rs

@@ -24,6 +24,8 @@ pub struct WebhookServerConfig {
 pub struct WebhookServer {
     config: WebhookServerConfig,
     routes: Vec<Router>,
+    /// Merged router saved after start() for restarts via `install_listener()`.
+    merged_router: Option<Router>,
     shutdown_tx: Option<oneshot::Sender<()>>,
     handle: Option<JoinHandle<()>>,
 }
@@ -34,6 +36,7 @@ impl WebhookServer {
         Self {
             config,
             routes: Vec::new(),
+            merged_router: None,
             shutdown_tx: None,
             handle: None,
         }
@@ -51,7 +54,13 @@ impl WebhookServer {
         for fragment in self.routes.drain(..) {
             app = app.merge(fragment);
         }
+        self.merged_router = Some(app.clone());
+        self.bind_and_spawn(app).await
+    }
 
+    /// Bind a listener to the configured address and spawn the server task.
+    /// Private helper used by `start()`.
+    async fn bind_and_spawn(&mut self, app: Router) -> Result<(), ChannelError> {
         let listener = tokio::net::TcpListener::bind(self.config.addr)
             .await
             .map_err(|e| ChannelError::StartupFailed {
@@ -80,6 +89,56 @@ impl WebhookServer {
         Ok(())
     }
 
+    /// Clone the merged router, if `start()` has been called.
+    pub fn merged_router_clone(&self) -> Option<Router> {
+        self.merged_router.clone()
+    }
+
+    /// Install a pre-bound listener, replacing the current one.
+    ///
+    /// The caller is responsible for binding the `TcpListener` *outside* any
+    /// lock so that the async bind does not block other lock waiters. This
+    /// method only does synchronous bookkeeping plus spawning the (non-blocking)
+    /// server task, so it is safe to call while holding a mutex.
+    pub fn install_listener(
+        &mut self,
+        new_addr: SocketAddr,
+        listener: tokio::net::TcpListener,
+        app: Router,
+    ) -> (Option<oneshot::Sender<()>>, Option<JoinHandle<()>>) {
+        // Capture old handles so the caller can shut them down outside the lock.
+        let old_shutdown_tx = self.shutdown_tx.take();
+        let old_handle = self.handle.take();
+
+        self.config.addr = new_addr;
+
+        // Spawn the new server task (non-blocking).
+        let (shutdown_tx, shutdown_rx) = oneshot::channel();
+        self.shutdown_tx = Some(shutdown_tx);
+
+        let handle = tokio::spawn(async move {
+            if let Err(e) = axum::serve(listener, app)
+                .with_graceful_shutdown(async {
+                    let _ = shutdown_rx.await;
+                    tracing::debug!("Webhook server shutting down");
+                })
+                .await
+            {
+                tracing::error!("Webhook server error: {}", e);
+            }
+        });
+        self.handle = Some(handle);
+
+        tracing::info!("Webhook server listening on {}", new_addr);
+
+        (old_shutdown_tx, old_handle)
+    }
+
+    /// Return the current bind address.
+    pub fn current_addr(&self) -> SocketAddr {
+        self.config.addr
+    }
+
     /// Signal graceful shutdown and wait for the server task to finish.
     pub async fn shutdown(&mut self) {
         if let Some(tx) = self.shutdown_tx.take() {
@@ -90,3 +149,196 @@ impl WebhookServer {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use axum::Json;
+    use serde_json::json;
+
+    #[tokio::test]
+    async fn test_restart_with_addr_rebinds_listener() {
+        use std::net::TcpListener as StdTcpListener;
+
+        // Find two available ports by binding and immediately closing
+        let port1 = {
+            let listener =
+                StdTcpListener::bind("127.0.0.1:0").expect("Failed to find available port 1");
+            listener
+                .local_addr()
+                .expect("Failed to get local addr")
+                .port()
+        };
+
+        let port2 = {
+            let listener =
+                StdTcpListener::bind("127.0.0.1:0").expect("Failed to find available port 2");
+            listener
+                .local_addr()
+                .expect("Failed to get local addr")
+                .port()
+        };
+
+        assert_ne!(port1, port2, "Should have different ports");
+        assert_ne!(port1, 0, "Port 1 should be non-zero");
+        assert_ne!(port2, 0, "Port 2 should be non-zero");
+
+        // Start server on first port
+        let addr1 = format!("127.0.0.1:{}", port1).parse().unwrap();
+        let mut server = WebhookServer::new(WebhookServerConfig { addr: addr1 });
+
+        // Create a test router that responds to health checks
+        let test_router = axum::Router::new().route(
+            "/health",
+            axum::routing::get(|| async { Json(json!({"status": "ok"})) }),
+        );
+        server.add_routes(test_router);
+
+        // Start the server on first port
+        server.start().await.expect("Failed to start server");
+        assert_eq!(
+            server.current_addr(),
+            addr1,
+            "Server should be bound to initial address"
+        );
+
+        // Verify the first server is actually listening
+        let client = reqwest::Client::new();
+        let response = client
+            .get(format!("http://{}/health", addr1))
+            .send()
+            .await
+            .expect("Failed to send request to first server");
+        assert_eq!(
+            response.status(),
+            200,
+            "First server should respond to health check"
+        );
+
+        // Restart on second port using two-phase approach
+        let addr2: SocketAddr = format!("127.0.0.1:{}", port2).parse().unwrap();
+        let app = server
+            .merged_router_clone()
+            .expect("Router should exist after start()");
+        let listener = tokio::net::TcpListener::bind(addr2)
+            .await
+            .expect("Failed to bind to new addr");
+        let (old_tx, old_handle) = server.install_listener(addr2, listener, app);
+        if let Some(tx) = old_tx {
+            let _ = tx.send(());
+        }
+        if let Some(handle) = old_handle {
+            let _ = handle.await;
+        }
+
+        // Assert the address changed
+        assert_eq!(
+            server.current_addr(),
+            addr2,
+            "Server address should be updated after restart"
+        );
+        assert_ne!(
+            addr1, addr2,
+            "Address should change after restart_with_addr"
+        );
+
+        // Verify the new server is actually listening on the new address
+        let response = client
+            .get(format!("http://{}/health", addr2))
+            .send()
+            .await
+            .expect("Failed to send request to restarted server");
+        assert_eq!(
+            response.status(),
+            200,
+            "Restarted server should respond to health check on new address"
+        );
+
+        // Verify the old address is no longer responding
+        let old_result = tokio::time::timeout(
+            std::time::Duration::from_millis(200),
+            client.get(format!("http://{}/health", addr1)).send(),
+        )
+        .await;
+        assert!(
+            old_result.is_err() || old_result.as_ref().unwrap().is_err(),
+            "Old address should not respond after server restarts"
+        );
+
+        // Clean up
+        server.shutdown().await;
+    }
+
+    #[tokio::test]
+    async fn test_restart_with_addr_rollback_on_bind_failure() {
+        use std::net::TcpListener as StdTcpListener;
+
+        // Find an available port
+        let port1 = {
+            let listener =
+                StdTcpListener::bind("127.0.0.1:0").expect("Failed to find available port");
+            listener
+                .local_addr()
+                .expect("Failed to get local addr")
+                .port()
+        };
+
+        // Start server on first port
+        let addr1 = format!("127.0.0.1:{}", port1).parse().unwrap();
+        let mut server = WebhookServer::new(WebhookServerConfig { addr: addr1 });
+
+        // Create a test router
+        let test_router = axum::Router::new().route(
+            "/health",
+            axum::routing::get(|| async { Json(json!({"status": "ok"})) }),
+        );
+        server.add_routes(test_router);
+
+        // Start the server on first port
+        server.start().await.expect("Failed to start server");
+
+        // Verify the server is listening
+        let client = reqwest::Client::new();
+        let response = client
+            .get(format!("http://{}/health", addr1))
+            .send()
+            .await
+            .expect("Failed to send request");
+        assert_eq!(response.status(), 200, "Server should be listening");
+
+        // Try to restart on an invalid address (port 1 typically requires elevated privileges)
+        let invalid_addr: SocketAddr = "127.0.0.1:1".parse().unwrap();
+
+        // Attempt bind (should fail); server state is untouched because we
+        // never call install_listener on failure.
+        let app = server
+            .merged_router_clone()
+            .expect("Router should exist after start()");
+        let result = tokio::net::TcpListener::bind(invalid_addr).await;
+        assert!(result.is_err(), "Bind to privileged port should fail");
+        // `app` is dropped — server state unchanged (rollback by construction)
+        drop(app);
+
+        // Verify the old address is still responding (rollback succeeded)
+        let response = client
+            .get(format!("http://{}/health", addr1))
+            .send()
+            .await
+            .expect("Failed to send request to old address");
+        assert_eq!(
+            response.status(),
+            200,
+            "Old listener should still be running after failed restart"
+        );
+
+        // Verify the server address is unchanged
+        assert_eq!(
+            server.current_addr(),
+            addr1,
+            "Server address should be restored after failed restart"
+        );
+
+        // Clean up
+        server.shutdown().await;
+    }
+}

src/cli/doctor.rs

@@ -7,6 +7,7 @@
 use std::path::PathBuf;
 
 use crate::bootstrap::ironclaw_base_dir;
+use crate::settings::Settings;
 
 /// Run all diagnostic checks and print results.
 pub async fn run_doctor_command() -> anyhow::Result<()> {
@@ -15,14 +16,35 @@ pub async fn run_doctor_command() -> anyhow::Result<()> {
 
     let mut passed = 0u32;
     let mut failed = 0u32;
+    let mut skipped = 0u32;
 
-    // ── Configuration checks ──────────────────────────────────
+    // Load settings once for checks that need them.
+    let settings = Settings::load();
+
+    // ── Settings & core config ─────────────────────────────────
+
+    check(
+        "Settings file",
+        check_settings_file(),
+        &mut passed,
+        &mut failed,
+        &mut skipped,
+    );
 
     check(
         "NEAR AI session",
         check_nearai_session().await,
         &mut passed,
         &mut failed,
+        &mut skipped,
+    );
+
+    check(
+        "LLM configuration",
+        check_llm_config(&settings),
+        &mut passed,
+        &mut failed,
+        &mut skipped,
     );
 
     check(
@@ -30,6 +52,7 @@ pub async fn run_doctor_command() -> anyhow::Result<()> {
         check_database().await,
         &mut passed,
         &mut failed,
+        &mut skipped,
     );
 
     check(
@@ -37,15 +60,75 @@ pub async fn run_doctor_command() -> anyhow::Result<()> {
         check_workspace_dir(),
         &mut passed,
         &mut failed,
+        &mut skipped,
+    );
+
+    // ── Subsystem configuration checks ─────────────────────────
+
+    check(
+        "Embeddings",
+        check_embeddings(&settings),
+        &mut passed,
+        &mut failed,
+        &mut skipped,
+    );
+
+    check(
+        "Routines config",
+        check_routines_config(),
+        &mut passed,
+        &mut failed,
+        &mut skipped,
+    );
+
+    check(
+        "Gateway config",
+        check_gateway_config(&settings),
+        &mut passed,
+        &mut failed,
+        &mut skipped,
+    );
+
+    check(
+        "MCP servers",
+        check_mcp_config().await,
+        &mut passed,
+        &mut failed,
+        &mut skipped,
+    );
+
+    check(
+        "Skills",
+        check_skills().await,
+        &mut passed,
+        &mut failed,
+        &mut skipped,
+    );
+
+    check(
+        "Secrets",
+        check_secrets(&settings),
+        &mut passed,
+        &mut failed,
+        &mut skipped,
+    );
+
+    check(
+        "Service",
+        check_service_installed(),
+        &mut passed,
+        &mut failed,
+        &mut skipped,
     );
 
     // ── External binary checks ────────────────────────────────
 
     check(
-        "Docker",
-        check_binary("docker", &["--version"]),
+        "Docker daemon",
+        check_docker_daemon().await,
         &mut passed,
         &mut failed,
+        &mut skipped,
     );
 
     check(
@@ -53,6 +136,7 @@ pub async fn run_doctor_command() -> anyhow::Result<()> {
         check_binary("cloudflared", &["--version"]),
         &mut passed,
         &mut failed,
+        &mut skipped,
     );
 
     check(
@@ -60,6 +144,7 @@ pub async fn run_doctor_command() -> anyhow::Result<()> {
         check_binary("ngrok", &["version"]),
         &mut passed,
         &mut failed,
+        &mut skipped,
     );
 
     check(
@@ -67,12 +152,13 @@ pub async fn run_doctor_command() -> anyhow::Result<()> {
         check_binary("tailscale", &["version"]),
         &mut passed,
         &mut failed,
+        &mut skipped,
     );
 
     // ── Summary ───────────────────────────────────────────────
 
     println!();
-    println!("  {passed} passed, {failed} failed");
+    println!("  {passed} passed, {failed} failed, {skipped} skipped");
 
     if failed > 0 {
         println!("\n  Some checks failed. This is normal if you don't use those features.");
@@ -83,7 +169,7 @@ pub async fn run_doctor_command() -> anyhow::Result<()> {
 
 // ── Individual checks ───────────────────────────────────────
 
-fn check(name: &str, result: CheckResult, passed: &mut u32, failed: &mut u32) {
+fn check(name: &str, result: CheckResult, passed: &mut u32, failed: &mut u32, skipped: &mut u32) {
     match result {
         CheckResult::Pass(detail) => {
             *passed += 1;
@@ -94,6 +180,7 @@ fn check(name: &str, result: CheckResult, passed: &mut u32, failed: &mut u32) {
             println!("  [FAIL] {name}: {detail}");
         }
         CheckResult::Skip(reason) => {
+            *skipped += 1;
             println!("  [skip] {name}: {reason}");
         }
     }
@@ -105,6 +192,29 @@ enum CheckResult {
     Skip(String),
 }
 
+// ── Settings file ───────────────────────────────────────────
+
+fn check_settings_file() -> CheckResult {
+    let path = Settings::default_path();
+    if !path.exists() {
+        return CheckResult::Pass("no settings file (defaults will be used)".into());
+    }
+
+    match std::fs::read_to_string(&path) {
+        Ok(data) => match serde_json::from_str::<serde_json::Value>(&data) {
+            Ok(_) => CheckResult::Pass(format!("valid ({})", path.display())),
+            Err(e) => CheckResult::Fail(format!(
+                "settings.json is malformed: {}. Fix or delete {}",
+                e,
+                path.display()
+            )),
+        },
+        Err(e) => CheckResult::Fail(format!("cannot read {}: {}", path.display(), e)),
+    }
+}
+
+// ── NEAR AI session ─────────────────────────────────────────
+
 async fn check_nearai_session() -> CheckResult {
     // Check if session file exists
     let session_path = crate::config::llm::default_session_path();
@@ -129,6 +239,27 @@ async fn check_nearai_session() -> CheckResult {
     }
 }
 
+// ── LLM configuration ──────────────────────────────────────
+
+fn check_llm_config(settings: &Settings) -> CheckResult {
+    match crate::llm::LlmConfig::resolve(settings) {
+        Ok(config) => {
+            // Show the model for the active backend, not always nearai.model.
+            let model = if let Some(ref bedrock) = config.bedrock {
+                &bedrock.model
+            } else if let Some(ref provider) = config.provider {
+                &provider.model
+            } else {
+                &config.nearai.model
+            };
+            CheckResult::Pass(format!("backend={}, model={}", config.backend, model))
+        }
+        Err(e) => CheckResult::Fail(format!("LLM config error: {e}")),
+    }
+}
+
+// ── Database ────────────────────────────────────────────────
+
 async fn check_database() -> CheckResult {
     let backend = std::env::var("DATABASE_BACKEND")
         .ok()
@@ -192,6 +323,8 @@ async fn try_pg_connect() -> Result<(), String> {
     Err("postgres feature not compiled in".into())
 }
 
+// ── Workspace directory ─────────────────────────────────────
+
 fn check_workspace_dir() -> CheckResult {
     let dir = ironclaw_base_dir();
 
@@ -206,6 +339,222 @@ fn check_workspace_dir() -> CheckResult {
     }
 }
 
+// ── Embeddings ──────────────────────────────────────────────
+
+fn check_embeddings(settings: &Settings) -> CheckResult {
+    match crate::config::EmbeddingsConfig::resolve(settings) {
+        Ok(config) => {
+            if !config.enabled {
+                return CheckResult::Skip("disabled (set EMBEDDING_ENABLED=true)".into());
+            }
+            let has_creds = match config.provider.as_str() {
+                "openai" => config.openai_api_key().is_some(),
+                "nearai" => {
+                    // NearAiEmbeddings uses SessionManager::get_token() which
+                    // only returns session tokens, NOT NEARAI_API_KEY
+                    // (src/workspace/embeddings.rs:309, src/llm/session.rs:132).
+                    let session_path = crate::config::llm::default_session_path();
+                    session_path.exists()
+                        && std::fs::read_to_string(&session_path)
+                            .map(|s| !s.trim().is_empty())
+                            .unwrap_or(false)
+                }
+                "ollama" => true, // local, no creds needed
+                _ => config.openai_api_key().is_some(),
+            };
+            if has_creds {
+                CheckResult::Pass(format!(
+                    "provider={}, model={}",
+                    config.provider, config.model
+                ))
+            } else {
+                let hint = match config.provider.as_str() {
+                    "nearai" => "run `ironclaw onboard` to create a session",
+                    _ => "set OPENAI_API_KEY",
+                };
+                CheckResult::Fail(format!(
+                    "provider={} but credentials missing ({})",
+                    config.provider, hint
+                ))
+            }
+        }
+        Err(e) => CheckResult::Fail(format!("config error: {e}")),
+    }
+}
+
+// ── Routines config ─────────────────────────────────────────
+
+fn check_routines_config() -> CheckResult {
+    match crate::config::RoutineConfig::resolve() {
+        Ok(config) => {
+            if config.enabled {
+                CheckResult::Pass(format!(
+                    "enabled (interval={}s, max_concurrent={})",
+                    config.cron_check_interval_secs, config.max_concurrent_routines
+                ))
+            } else {
+                CheckResult::Skip("disabled".into())
+            }
+        }
+        Err(e) => CheckResult::Fail(format!("config error: {e}")),
+    }
+}
+
+// ── Gateway config ──────────────────────────────────────────
+
+fn check_gateway_config(settings: &Settings) -> CheckResult {
+    // Use the same resolve() path as runtime so invalid env values
+    // (e.g. GATEWAY_PORT=abc) are caught here too.
+    match crate::config::ChannelsConfig::resolve(settings) {
+        Ok(channels) => match channels.gateway {
+            Some(gw) => {
+                if gw.auth_token.is_some() {
+                    CheckResult::Pass(format!(
+                        "enabled at {}:{} (auth token set)",
+                        gw.host, gw.port
+                    ))
+                } else {
+                    CheckResult::Pass(format!(
+                        "enabled at {}:{} (no auth token — random token will be generated)",
+                        gw.host, gw.port
+                    ))
+                }
+            }
+            None => CheckResult::Skip("disabled (GATEWAY_ENABLED=false)".into()),
+        },
+        Err(e) => CheckResult::Fail(format!("config error: {e}")),
+    }
+}
+
+// ── MCP servers ─────────────────────────────────────────────
+
+async fn check_mcp_config() -> CheckResult {
+    match crate::tools::mcp::config::load_mcp_servers().await {
+        Ok(file) => {
+            let servers: Vec<_> = file.enabled_servers().collect();
+            if servers.is_empty() {
+                return CheckResult::Skip("no MCP servers configured".into());
+            }
+
+            let mut invalid = Vec::new();
+            for server in &servers {
+                if let Err(e) = server.validate() {
+                    invalid.push(format!("{}: {}", server.name, e));
+                }
+            }
+
+            if invalid.is_empty() {
+                CheckResult::Pass(format!("{} server(s) configured, all valid", servers.len()))
+            } else {
+                CheckResult::Fail(format!(
+                    "{} server(s), {} invalid: {}",
+                    servers.len(),
+                    invalid.len(),
+                    invalid.join("; ")
+                ))
+            }
+        }
+        Err(e) => {
+            // Distinguish no config from corrupted config
+            let msg = e.to_string();
+            if msg.contains("not found") || msg.contains("No such file") {
+                CheckResult::Skip("no MCP config file".into())
+            } else {
+                CheckResult::Fail(format!("config error: {e}"))
+            }
+        }
+    }
+}
+
+// ── Skills ──────────────────────────────────────────────────
+
+async fn check_skills() -> CheckResult {
+    let user_dir = ironclaw_base_dir().join("skills");
+    let installed_dir = ironclaw_base_dir().join("installed_skills");
+
+    let mut registry = crate::skills::SkillRegistry::new(user_dir.clone());
+    registry = registry.with_installed_dir(installed_dir);
+
+    // discover_all() returns loaded skill names (not warnings).
+    let _loaded_names = registry.discover_all().await;
+
+    let count = registry.count();
+    if count == 0 {
+        return CheckResult::Skip("no skills discovered".into());
+    }
+
+    CheckResult::Pass(format!("{count} skill(s) loaded"))
+}
+
+// ── Secrets ─────────────────────────────────────────────────
+
+fn check_secrets(settings: &Settings) -> CheckResult {
+    match settings.secrets_master_key_source {
+        crate::settings::KeySource::Keychain => {
+            CheckResult::Pass("master key source: OS keychain".into())
+        }
+        crate::settings::KeySource::Env => {
+            if std::env::var("SECRETS_MASTER_KEY").is_ok() {
+                CheckResult::Pass("master key source: env var (set)".into())
+            } else {
+                CheckResult::Fail(
+                    "master key source: env var but SECRETS_MASTER_KEY not set".into(),
+                )
+            }
+        }
+        crate::settings::KeySource::None => {
+            CheckResult::Skip("secrets not configured (run `ironclaw onboard`)".into())
+        }
+    }
+}
+
+// ── Service ─────────────────────────────────────────────────
+
+fn check_service_installed() -> CheckResult {
+    if cfg!(target_os = "macos") {
+        let plist =
+            dirs::home_dir().map(|h| h.join("Library/LaunchAgents/com.ironclaw.daemon.plist"));
+        match plist {
+            Some(path) if path.exists() => {
+                CheckResult::Pass(format!("launchd plist installed ({})", path.display()))
+            }
+            Some(_) => CheckResult::Skip("not installed (run `ironclaw service install`)".into()),
+            None => CheckResult::Skip("cannot determine home directory".into()),
+        }
+    } else if cfg!(target_os = "linux") {
+        let unit = dirs::home_dir().map(|h| h.join(".config/systemd/user/ironclaw.service"));
+        match unit {
+            Some(path) if path.exists() => {
+                CheckResult::Pass(format!("systemd unit installed ({})", path.display()))
+            }
+            Some(_) => CheckResult::Skip("not installed (run `ironclaw service install`)".into()),
+            None => CheckResult::Skip("cannot determine home directory".into()),
+        }
+    } else {
+        CheckResult::Skip("service management not supported on this platform".into())
+    }
+}
+
+// ── Docker daemon ───────────────────────────────────────────
+
+async fn check_docker_daemon() -> CheckResult {
+    let detection = crate::sandbox::check_docker().await;
+    match detection.status {
+        crate::sandbox::DockerStatus::Available => CheckResult::Pass("running".into()),
+        crate::sandbox::DockerStatus::NotInstalled => CheckResult::Skip(format!(
+            "not installed. {}",
+            detection.platform.install_hint()
+        )),
+        crate::sandbox::DockerStatus::NotRunning => CheckResult::Fail(format!(
+            "installed but not running. {}",
+            detection.platform.start_hint()
+        )),
+        crate::sandbox::DockerStatus::Disabled => CheckResult::Skip("sandbox disabled".into()),
+    }
+}
+
+// ── External binary ─────────────────────────────────────────
+
 fn check_binary(name: &str, args: &[&str]) -> CheckResult {
     match std::process::Command::new(name)
         .args(args)
@@ -273,6 +622,193 @@ mod tests {
         }
     }
 
+    #[test]
+    fn check_settings_file_handles_missing() {
+        // Settings::default_path() might or might not exist, but must not panic
+        let result = check_settings_file();
+        match result {
+            CheckResult::Pass(_) | CheckResult::Fail(_) | CheckResult::Skip(_) => {}
+        }
+    }
+
+    #[test]
+    fn check_llm_config_does_not_panic() {
+        let settings = Settings::default();
+        let result = check_llm_config(&settings);
+        match result {
+            CheckResult::Pass(_) | CheckResult::Fail(_) | CheckResult::Skip(_) => {}
+        }
+    }
+
+    #[test]
+    fn check_routines_config_does_not_panic() {
+        let result = check_routines_config();
+        match result {
+            CheckResult::Pass(_) | CheckResult::Fail(_) | CheckResult::Skip(_) => {}
+        }
+    }
+
+    #[test]
+    fn check_gateway_config_does_not_panic() {
+        let settings = Settings::default();
+        let result = check_gateway_config(&settings);
+        match result {
+            CheckResult::Pass(_) | CheckResult::Fail(_) | CheckResult::Skip(_) => {}
+        }
+    }
+
+    #[test]
+    fn check_embeddings_does_not_panic() {
+        let settings = Settings::default();
+        let result = check_embeddings(&settings);
+        match result {
+            CheckResult::Pass(_) | CheckResult::Fail(_) | CheckResult::Skip(_) => {}
+        }
+    }
+
+    #[test]
+    fn check_secrets_none_returns_skip() {
+        let settings = Settings::default();
+        match check_secrets(&settings) {
+            CheckResult::Skip(msg) => {
+                assert!(
+                    msg.contains("not configured"),
+                    "expected 'not configured' in skip message, got: {msg}"
+                );
+            }
+            other => panic!(
+                "expected Skip for default settings, got: {}",
+                format_result(&other)
+            ),
+        }
+    }
+
+    #[test]
+    fn check_service_installed_does_not_panic() {
+        let result = check_service_installed();
+        match result {
+            CheckResult::Pass(_) | CheckResult::Fail(_) | CheckResult::Skip(_) => {}
+        }
+    }
+
+    #[tokio::test]
+    async fn check_docker_daemon_does_not_panic() {
+        let result = check_docker_daemon().await;
+        match result {
+            CheckResult::Pass(_) | CheckResult::Fail(_) | CheckResult::Skip(_) => {}
+        }
+    }
+
+    #[tokio::test]
+    async fn check_mcp_config_does_not_panic() {
+        let result = check_mcp_config().await;
+        match result {
+            CheckResult::Pass(_) | CheckResult::Fail(_) | CheckResult::Skip(_) => {}
+        }
+    }
+
+    #[tokio::test]
+    async fn check_skills_does_not_panic() {
+        let result = check_skills().await;
+        match result {
+            CheckResult::Pass(_) | CheckResult::Fail(_) | CheckResult::Skip(_) => {}
+        }
+    }
+
+    #[test]
+    fn check_llm_config_shows_nearai_model_for_nearai_backend() {
+        let _guard = crate::config::helpers::ENV_MUTEX.lock().expect("env mutex");
+        // SAFETY: Under ENV_MUTEX, no concurrent env access.
+        unsafe {
+            std::env::remove_var("LLM_BACKEND");
+        }
+        let settings = Settings::default();
+        match check_llm_config(&settings) {
+            CheckResult::Pass(msg) => {
+                assert!(
+                    msg.contains("backend=nearai"),
+                    "expected nearai backend, got: {msg}"
+                );
+                // Must NOT show a bedrock or registry model when backend is nearai
+                assert!(
+                    !msg.contains("anthropic.claude"),
+                    "should not show bedrock model for nearai backend: {msg}"
+                );
+            }
+            other => panic!(
+                "expected Pass for default LLM config, got: {}",
+                format_result(&other)
+            ),
+        }
+    }
+
+    #[test]
+    fn check_embeddings_disabled_by_default_returns_skip() {
+        let _guard = crate::config::helpers::ENV_MUTEX.lock().expect("env mutex");
+        // SAFETY: Under ENV_MUTEX.
+        unsafe {
+            std::env::remove_var("EMBEDDING_ENABLED");
+        }
+        let settings = Settings::default();
+        match check_embeddings(&settings) {
+            CheckResult::Skip(msg) => {
+                assert!(
+                    msg.contains("disabled"),
+                    "expected 'disabled' in skip message, got: {msg}"
+                );
+            }
+            other => panic!(
+                "expected Skip for disabled embeddings, got: {}",
+                format_result(&other)
+            ),
+        }
+    }
+
+    #[test]
+    fn check_routines_enabled_by_default() {
+        let _guard = crate::config::helpers::ENV_MUTEX.lock().expect("env mutex");
+        // SAFETY: Under ENV_MUTEX.
+        unsafe {
+            std::env::remove_var("ROUTINES_ENABLED");
+        }
+        match check_routines_config() {
+            CheckResult::Pass(msg) => {
+                assert!(
+                    msg.contains("enabled"),
+                    "routines should be enabled by default, got: {msg}"
+                );
+            }
+            other => panic!(
+                "expected Pass for default routines, got: {}",
+                format_result(&other)
+            ),
+        }
+    }
+
+    #[test]
+    fn check_secrets_env_without_var_returns_fail() {
+        let settings = Settings {
+            secrets_master_key_source: crate::settings::KeySource::Env,
+            ..Default::default()
+        };
+        match check_secrets(&settings) {
+            CheckResult::Fail(msg) => {
+                assert!(
+                    msg.contains("SECRETS_MASTER_KEY not set"),
+                    "expected mention of missing env var, got: {msg}"
+                );
+            }
+            CheckResult::Pass(_) => {
+                // If SECRETS_MASTER_KEY happens to be set in the environment,
+                // Pass is correct — don't fail the test.
+            }
+            other => panic!(
+                "expected Fail or Pass for env key source, got: {}",
+                format_result(&other)
+            ),
+        }
+    }
+
     fn format_result(r: &CheckResult) -> String {
         match r {
             CheckResult::Pass(s) => format!("Pass({s})"),

src/cli/import.rs

@@ -0,0 +1,162 @@
+//! Import command for migrating data from other AI systems.
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use clap::Subcommand;
+
+#[cfg(feature = "import")]
+use crate::import::ImportOptions;
+#[cfg(feature = "import")]
+use crate::import::openclaw::OpenClawImporter;
+
+/// Import data from other AI systems.
+#[derive(Subcommand, Debug, Clone)]
+pub enum ImportCommand {
+    /// Import from OpenClaw (memory, history, settings, credentials)
+    #[cfg(feature = "import")]
+    Openclaw {
+        /// Path to OpenClaw directory (default: ~/.openclaw)
+        #[arg(long)]
+        path: Option<PathBuf>,
+
+        /// Dry-run mode: show what would be imported without writing
+        #[arg(long)]
+        dry_run: bool,
+
+        /// Re-embed memory if dimensions don't match target provider
+        #[arg(long)]
+        re_embed: bool,
+
+        /// User ID for imported data (default: 'default')
+        #[arg(long)]
+        user_id: Option<String>,
+    },
+}
+
+/// Run an import command.
+#[cfg(feature = "import")]
+pub async fn run_import_command(
+    cmd: &ImportCommand,
+    config: &crate::config::Config,
+) -> anyhow::Result<()> {
+    match cmd {
+        ImportCommand::Openclaw {
+            path,
+            dry_run,
+            re_embed,
+            user_id,
+        } => run_import_openclaw(config, path.clone(), *dry_run, *re_embed, user_id.clone()).await,
+    }
+}
+
+/// Run the OpenClaw import.
+#[cfg(feature = "import")]
+async fn run_import_openclaw(
+    config: &crate::config::Config,
+    openclaw_path: Option<PathBuf>,
+    dry_run: bool,
+    re_embed: bool,
+    user_id: Option<String>,
+) -> anyhow::Result<()> {
+    use secrecy::SecretString;
+
+    // Determine OpenClaw path
+    let openclaw_path = if let Some(path) = openclaw_path {
+        path
+    } else if let Some(path) = OpenClawImporter::detect() {
+        path
+    } else {
+        let home = std::env::var("HOME").unwrap_or_else(|_| ".".to_string());
+        PathBuf::from(home).join(".openclaw")
+    };
+
+    let user_id = user_id.unwrap_or_else(|| "default".to_string());
+
+    println!("🔍 OpenClaw Import");
+    println!("  Path: {}", openclaw_path.display());
+    println!("  User: {}", user_id);
+    if dry_run {
+        println!("  Mode: DRY RUN (no data will be written)");
+    }
+    println!();
+
+    // Initialize database
+    let db = crate::db::connect_from_config(&config.database)
+        .await
+        .map_err(|e| anyhow::anyhow!("Failed to initialize database: {}", e))?;
+
+    // Initialize secrets store with master key from env or keychain
+    let secrets_crypto = if let Ok(master_key_hex) = std::env::var("SECRETS_MASTER_KEY") {
+        Arc::new(
+            crate::secrets::SecretsCrypto::new(SecretString::from(master_key_hex))
+                .map_err(|e| anyhow::anyhow!("Failed to initialize secrets: {}", e))?,
+        )
+    } else {
+        match crate::secrets::keychain::get_master_key().await {
+            Ok(key_bytes) => {
+                let key_hex: String = key_bytes.iter().map(|b| format!("{:02x}", b)).collect();
+                Arc::new(
+                    crate::secrets::SecretsCrypto::new(SecretString::from(key_hex))
+                        .map_err(|e| anyhow::anyhow!("Failed to initialize secrets: {}", e))?,
+                )
+            }
+            Err(_) => {
+                return Err(anyhow::anyhow!(
+                    "No secrets master key found. Set SECRETS_MASTER_KEY env var or run 'ironclaw onboard' first."
+                ));
+            }
+        }
+    };
+
+    let secrets: Arc<dyn crate::secrets::SecretsStore> = Arc::new(
+        crate::secrets::InMemorySecretsStore::new(secrets_crypto.clone()),
+    );
+
+    // Initialize workspace
+    let workspace = crate::workspace::Workspace::new_with_db(user_id.clone(), db.clone());
+
+    let opts = ImportOptions {
+        openclaw_path,
+        dry_run,
+        re_embed,
+        user_id,
+    };
+
+    let importer = OpenClawImporter::new(db, workspace, secrets, opts);
+    let stats = importer.import().await?;
+
+    // Print results
+    println!("Import Complete");
+    println!();
+    println!("Summary:");
+    println!("  Documents:    {}", stats.documents);
+    println!("  Chunks:       {}", stats.chunks);
+    println!("  Conversations: {}", stats.conversations);
+    println!("  Messages:     {}", stats.messages);
+    println!("  Settings:     {}", stats.settings);
+    println!("  Secrets:      {}", stats.secrets);
+    if stats.skipped > 0 {
+        println!("  Skipped:      {}", stats.skipped);
+    }
+    if stats.re_embed_queued > 0 {
+        println!("  Re-embed queued: {}", stats.re_embed_queued);
+    }
+    println!();
+    println!("Total imported: {}", stats.total_imported());
+
+    if dry_run {
+        println!();
+        println!("[DRY RUN] No data was written.");
+    }
+
+    Ok(())
+}
+
+#[cfg(not(feature = "import"))]
+pub async fn run_import_command(
+    _cmd: &ImportCommand,
+    _config: &crate::config::Config,
+) -> anyhow::Result<()> {
+    anyhow::bail!("Import feature not enabled. Compile with --features import")
+}

src/cli/mod.rs

@@ -14,6 +14,8 @@
 mod completion;
 mod config;
 mod doctor;
+#[cfg(feature = "import")]
+pub mod import;
 mod mcp;
 pub mod memory;
 pub mod oauth_defaults;
@@ -26,6 +28,8 @@ mod tool;
 pub use completion::Completion;
 pub use config::{ConfigCommand, run_config_command};
 pub use doctor::run_doctor_command;
+#[cfg(feature = "import")]
+pub use import::{ImportCommand, run_import_command};
 pub use mcp::{McpCommand, run_mcp_command};
 pub use memory::MemoryCommand;
 pub use memory::run_memory_command_with_db;
@@ -183,6 +187,15 @@ pub enum Command {
     )]
     Completion(Completion),
 
+    /// Import data from other AI systems
+    #[cfg(feature = "import")]
+    #[command(
+        subcommand,
+        about = "Import from other AI systems",
+        long_about = "Migrate data from other AI assistants like OpenClaw.\nExample: ironclaw import openclaw"
+    )]
+    Import(ImportCommand),
+
     /// Run as a sandboxed worker inside a Docker container (internal use).
     /// This is invoked automatically by the orchestrator, not by users directly.
     #[command(hide = true)]
@@ -282,6 +295,7 @@ mod tests {
     }
 
     #[test]
+    #[cfg(feature = "import")]
     fn test_help_output() {
         let mut cmd = Cli::command();
         let help = cmd.render_help().to_string();
@@ -289,9 +303,26 @@ mod tests {
     }
 
     #[test]
+    #[cfg(not(feature = "import"))]
+    fn test_help_output_without_import() {
+        let mut cmd = Cli::command();
+        let help = cmd.render_help().to_string();
+        assert_snapshot!(help);
+    }
+
+    #[test]
+    #[cfg(feature = "import")]
     fn test_long_help_output() {
         let mut cmd = Cli::command();
         let help = cmd.render_long_help().to_string();
         assert_snapshot!(help);
     }
+
+    #[test]
+    #[cfg(not(feature = "import"))]
+    fn test_long_help_output_without_import() {
+        let mut cmd = Cli::command();
+        let help = cmd.render_long_help().to_string();
+        assert_snapshot!(help);
+    }
 }

src/cli/snapshots/ironclaw__cli__tests__help_output.snap

@@ -1,5 +1,6 @@
 ---
 source: src/cli/mod.rs
+assertion_line: 302
 expression: help
 ---
 Secure personal AI assistant that protects your data and expands its capabilities
@@ -19,6 +20,7 @@ Commands:
   doctor      Run diagnostics
   status      Show system status
   completion  Generate completions
+  import      Import from other AI systems
   help        Print this message or the help of the given subcommand(s)
 
 Options:

src/cli/snapshots/ironclaw__cli__tests__help_output_without_import.snap

@@ -0,0 +1,32 @@
+---
+source: src/cli/mod.rs
+assertion_line: 310
+expression: help
+---
+Secure personal AI assistant that protects your data and expands its capabilities
+
+Usage: ironclaw [OPTIONS] [COMMAND]
+
+Commands:
+  run         Run the AI agent
+  onboard     Run interactive setup wizard
+  config      Manage app configs
+  tool        Manage WASM tools
+  registry    Browse/install extensions
+  mcp         Manage MCP servers
+  memory      Manage workspace memory
+  pairing     Manage DM pairing
+  service     Manage OS service
+  doctor      Run diagnostics
+  status      Show system status
+  completion  Generate completions
+  help        Print this message or the help of the given subcommand(s)
+
+Options:
+      --cli-only           Run in interactive CLI mode only (disable other channels)
+      --no-db              Skip database connection (for testing)
+  -m, --message <MESSAGE>  Single message mode - send one message and exit
+  -c, --config <CONFIG>    Configuration file path (optional, uses env vars by default)
+      --no-onboard         Skip first-run onboarding check
+  -h, --help               Print help (see more with '--help')
+  -V, --version            Print version

src/cli/snapshots/ironclaw__cli__tests__long_help_output.snap

@@ -1,5 +1,6 @@
 ---
 source: src/cli/mod.rs
+assertion_line: 318
 expression: help
 ---
 IronClaw is a secure AI assistant. Use 'ironclaw <subcommand> --help' for details.
@@ -22,6 +23,7 @@ Commands:
   doctor      Run diagnostics
   status      Show system status
   completion  Generate completions
+  import      Import from other AI systems
   help        Print this message or the help of the given subcommand(s)
 
 Options:

src/cli/snapshots/ironclaw__cli__tests__long_help_output_without_import.snap

@@ -0,0 +1,48 @@
+---
+source: src/cli/mod.rs
+assertion_line: 326
+expression: help
+---
+IronClaw is a secure AI assistant. Use 'ironclaw <subcommand> --help' for details.
+Examples:
+  ironclaw run  # Start the agent
+  ironclaw config list  # List configs
+
+Usage: ironclaw [OPTIONS] [COMMAND]
+
+Commands:
+  run         Run the AI agent
+  onboard     Run interactive setup wizard
+  config      Manage app configs
+  tool        Manage WASM tools
+  registry    Browse/install extensions
+  mcp         Manage MCP servers
+  memory      Manage workspace memory
+  pairing     Manage DM pairing
+  service     Manage OS service
+  doctor      Run diagnostics
+  status      Show system status
+  completion  Generate completions
+  help        Print this message or the help of the given subcommand(s)
+
+Options:
+      --cli-only
+          Run in interactive CLI mode only (disable other channels)
+
+      --no-db
+          Skip database connection (for testing)
+
+  -m, --message <MESSAGE>
+          Single message mode - send one message and exit
+
+  -c, --config <CONFIG>
+          Configuration file path (optional, uses env vars by default)
+
+      --no-onboard
+          Skip first-run onboarding check
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+  -V, --version
+          Print version

src/config/embeddings.rs

@@ -154,6 +154,7 @@ mod tests {
     use super::*;
     use crate::config::helpers::ENV_MUTEX;
     use crate::settings::{EmbeddingsSettings, Settings};
+    use crate::testing::credentials::*;
 
     /// Clear all embedding-related env vars.
     fn clear_embedding_env() {
@@ -173,7 +174,7 @@ mod tests {
         clear_embedding_env();
         // SAFETY: Under ENV_MUTEX, no concurrent env access.
         unsafe {
-            std::env::set_var("OPENAI_API_KEY", "sk-test-key-for-issue-129");
+            std::env::set_var("OPENAI_API_KEY", TEST_OPENAI_API_KEY_ISSUE_129);
         }
 
         let settings = Settings {

src/config/llm.rs

@@ -209,6 +209,7 @@ impl LlmConfig {
             extra_headers_env,
             api_key_required,
             base_url_required,
+            unsupported_params,
         ) = if let Some(def) = def {
             (
                 def.id.as_str(),
@@ -221,6 +222,7 @@ impl LlmConfig {
                 def.extra_headers_env.as_deref(),
                 def.api_key_required,
                 def.base_url_required,
+                def.unsupported_params.clone(),
             )
         } else {
             // Absolute fallback: treat as generic openai_completions
@@ -235,6 +237,7 @@ impl LlmConfig {
                 Some("LLM_EXTRA_HEADERS"),
                 false,
                 true,
+                Vec::new(),
             )
         };
 
@@ -338,6 +341,7 @@ impl LlmConfig {
             extra_headers,
             oauth_token,
             cache_retention,
+            unsupported_params,
         })
     }
 }
@@ -385,6 +389,7 @@ mod tests {
     use super::*;
     use crate::config::helpers::ENV_MUTEX;
     use crate::settings::Settings;
+    use crate::testing::credentials::*;
 
     /// Clear all openai-compatible-related env vars.
     fn clear_openai_compatible_env() {
@@ -624,6 +629,12 @@ mod tests {
         let provider = cfg.provider.expect("provider config should be present");
         assert_eq!(provider.base_url, "https://inference.tinfoil.sh/v1");
         assert_eq!(provider.model, "kimi-k2-5");
+        assert!(
+            provider
+                .unsupported_params
+                .contains(&"temperature".to_string()),
+            "tinfoil should propagate unsupported_params from registry"
+        );
     }
 
     #[test]
@@ -647,7 +658,7 @@ mod tests {
         // SAFETY: Under ENV_MUTEX.
         unsafe {
             std::env::set_var("LLM_BACKEND", "open_ai");
-            std::env::set_var("OPENAI_API_KEY", "test-key");
+            std::env::set_var("OPENAI_API_KEY", TEST_API_KEY);
         }
 
         let settings = Settings::default();
@@ -781,7 +792,7 @@ mod tests {
         clear_anthropic_env();
         // SAFETY: Under ENV_MUTEX.
         unsafe {
-            std::env::set_var("ANTHROPIC_OAUTH_TOKEN", "sk-ant-oat01-test-token");
+            std::env::set_var("ANTHROPIC_OAUTH_TOKEN", TEST_ANTHROPIC_OAUTH_TOKEN);
         }
 
         let settings = Settings {
@@ -805,7 +816,7 @@ mod tests {
         );
         assert_eq!(
             provider.oauth_token.as_ref().unwrap().expose_secret(),
-            "sk-ant-oat01-test-token"
+            TEST_ANTHROPIC_OAUTH_TOKEN
         );
 
         clear_anthropic_env();
@@ -819,8 +830,8 @@ mod tests {
         clear_anthropic_env();
         // SAFETY: Under ENV_MUTEX.
         unsafe {
-            std::env::set_var("ANTHROPIC_API_KEY", "sk-ant-real-key");
-            std::env::set_var("ANTHROPIC_OAUTH_TOKEN", "sk-ant-oat01-test-token");
+            std::env::set_var("ANTHROPIC_API_KEY", TEST_ANTHROPIC_API_KEY);
+            std::env::set_var("ANTHROPIC_OAUTH_TOKEN", TEST_ANTHROPIC_OAUTH_TOKEN);
         }
 
         let settings = Settings {
@@ -835,7 +846,7 @@ mod tests {
                 .api_key
                 .as_ref()
                 .map(|k| k.expose_secret().to_string()),
-            Some("sk-ant-real-key".to_string()),
+            Some(TEST_ANTHROPIC_API_KEY.to_string()),
             "real API key should take priority over OAuth placeholder"
         );
         assert!(
@@ -852,7 +863,7 @@ mod tests {
         clear_anthropic_env();
         // SAFETY: Under ENV_MUTEX.
         unsafe {
-            std::env::set_var("ANTHROPIC_OAUTH_TOKEN", "sk-ant-oat01-test-token");
+            std::env::set_var("ANTHROPIC_OAUTH_TOKEN", TEST_ANTHROPIC_OAUTH_TOKEN);
         }
 
         let settings = Settings {

src/config/mod.rs

@@ -14,6 +14,7 @@ mod heartbeat;
 pub(crate) mod helpers;
 mod hygiene;
 pub(crate) mod llm;
+pub mod relay;
 mod routines;
 mod safety;
 mod sandbox;
@@ -38,6 +39,7 @@ pub use self::embeddings::EmbeddingsConfig;
 pub use self::heartbeat::HeartbeatConfig;
 pub use self::hygiene::HygieneConfig;
 pub use self::llm::default_session_path;
+pub use self::relay::RelayConfig;
 pub use self::routines::RoutineConfig;
 pub use self::safety::SafetyConfig;
 pub use self::sandbox::{ClaudeCodeConfig, SandboxModeConfig};
@@ -85,6 +87,9 @@ pub struct Config {
     pub skills: SkillsConfig,
     pub transcription: TranscriptionConfig,
     pub observability: crate::observability::ObservabilityConfig,
+    /// Channel-relay integration (Slack via external relay service).
+    /// Present only when both `CHANNEL_RELAY_URL` and `CHANNEL_RELAY_API_KEY` are set.
+    pub relay: Option<RelayConfig>,
 }
 
 impl Config {
@@ -157,6 +162,7 @@ impl Config {
             },
             transcription: TranscriptionConfig::default(),
             observability: crate::observability::ObservabilityConfig::default(),
+            relay: None,
         }
     }
 
@@ -310,6 +316,7 @@ impl Config {
             observability: crate::observability::ObservabilityConfig {
                 backend: std::env::var("OBSERVABILITY_BACKEND").unwrap_or_else(|_| "none".into()),
             },
+            relay: RelayConfig::from_env(),
         })
     }
 }

src/config/relay.rs

@@ -0,0 +1,157 @@
+//! Channel-relay service configuration.
+
+use secrecy::SecretString;
+
+/// Configuration for connecting to a channel-relay service.
+#[derive(Clone)]
+pub struct RelayConfig {
+    /// Base URL of the channel-relay service (e.g., `http://localhost:3001`).
+    pub url: String,
+    /// API key for authenticated channel-relay endpoints.
+    pub api_key: SecretString,
+    /// Override for the OAuth callback URL (e.g., a tunnel URL).
+    pub callback_url: Option<String>,
+    /// Override for the instance identifier.
+    pub instance_id: Option<String>,
+    /// HTTP request timeout in seconds (default: 30).
+    pub request_timeout_secs: u64,
+    /// SSE stream long-poll timeout in seconds (default: 86400 = 24 h).
+    pub stream_timeout_secs: u64,
+    /// Initial exponential backoff in milliseconds (default: 1000).
+    pub backoff_initial_ms: u64,
+    /// Maximum exponential backoff in milliseconds (default: 60000).
+    pub backoff_max_ms: u64,
+}
+
+impl std::fmt::Debug for RelayConfig {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RelayConfig")
+            .field("url", &self.url)
+            .field("api_key", &"[REDACTED]")
+            .field("callback_url", &self.callback_url)
+            .field("instance_id", &self.instance_id)
+            .field("request_timeout_secs", &self.request_timeout_secs)
+            .field("stream_timeout_secs", &self.stream_timeout_secs)
+            .field("backoff_initial_ms", &self.backoff_initial_ms)
+            .field("backoff_max_ms", &self.backoff_max_ms)
+            .finish()
+    }
+}
+
+impl RelayConfig {
+    /// Load relay config from environment variables.
+    ///
+    /// Returns `None` if either `CHANNEL_RELAY_URL` or `CHANNEL_RELAY_API_KEY`
+    /// is not set, making the relay integration opt-in.
+    pub fn from_env() -> Option<Self> {
+        Self::from_env_reader(|key| std::env::var(key).ok())
+    }
+
+    /// Build a config for tests without touching the process environment.
+    pub fn from_values(url: impl Into<String>, api_key: impl Into<String>) -> Self {
+        Self {
+            url: url.into(),
+            api_key: SecretString::from(api_key.into()),
+            callback_url: None,
+            instance_id: None,
+            request_timeout_secs: 30,
+            stream_timeout_secs: 86400,
+            backoff_initial_ms: 1000,
+            backoff_max_ms: 60000,
+        }
+    }
+
+    /// Internal constructor that reads values through a closure, enabling safe testing.
+    fn from_env_reader(env: impl Fn(&str) -> Option<String>) -> Option<Self> {
+        let url = env("CHANNEL_RELAY_URL")?;
+        let api_key = SecretString::from(env("CHANNEL_RELAY_API_KEY")?);
+        Some(Self {
+            url,
+            api_key,
+            callback_url: env("IRONCLAW_OAUTH_CALLBACK_URL"),
+            instance_id: env("IRONCLAW_INSTANCE_ID"),
+            request_timeout_secs: env("RELAY_REQUEST_TIMEOUT_SECS")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(30),
+            stream_timeout_secs: env("RELAY_STREAM_TIMEOUT_SECS")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(86400),
+            backoff_initial_ms: env("RELAY_BACKOFF_INITIAL_MS")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(1000),
+            backoff_max_ms: env("RELAY_BACKOFF_MAX_MS")
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(60000),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn from_env_reader_returns_none_when_unset() {
+        let config = RelayConfig::from_env_reader(|_| None);
+        assert!(config.is_none());
+    }
+
+    #[test]
+    fn from_env_reader_loads_defaults() {
+        let config = RelayConfig::from_env_reader(|key| match key {
+            "CHANNEL_RELAY_URL" => Some("http://localhost:3001".into()),
+            "CHANNEL_RELAY_API_KEY" => Some("test-key".into()),
+            _ => None,
+        })
+        .expect("config should be Some");
+
+        assert_eq!(config.url, "http://localhost:3001");
+        assert_eq!(config.request_timeout_secs, 30);
+        assert_eq!(config.stream_timeout_secs, 86400);
+        assert_eq!(config.backoff_initial_ms, 1000);
+        assert_eq!(config.backoff_max_ms, 60000);
+        assert!(config.callback_url.is_none());
+        assert!(config.instance_id.is_none());
+    }
+
+    #[test]
+    fn from_env_reader_loads_overrides() {
+        let config = RelayConfig::from_env_reader(|key| match key {
+            "CHANNEL_RELAY_URL" => Some("http://relay:3001".into()),
+            "CHANNEL_RELAY_API_KEY" => Some("secret".into()),
+            "IRONCLAW_OAUTH_CALLBACK_URL" => Some("https://tunnel.example.com".into()),
+            "IRONCLAW_INSTANCE_ID" => Some("my-instance".into()),
+            "RELAY_REQUEST_TIMEOUT_SECS" => Some("60".into()),
+            "RELAY_STREAM_TIMEOUT_SECS" => Some("43200".into()),
+            "RELAY_BACKOFF_INITIAL_MS" => Some("2000".into()),
+            "RELAY_BACKOFF_MAX_MS" => Some("120000".into()),
+            _ => None,
+        })
+        .expect("config should be Some");
+
+        assert_eq!(
+            config.callback_url.as_deref(),
+            Some("https://tunnel.example.com")
+        );
+        assert_eq!(config.instance_id.as_deref(), Some("my-instance"));
+        assert_eq!(config.request_timeout_secs, 60);
+        assert_eq!(config.stream_timeout_secs, 43200);
+        assert_eq!(config.backoff_initial_ms, 2000);
+        assert_eq!(config.backoff_max_ms, 120000);
+    }
+
+    #[test]
+    fn from_values_builds_with_defaults() {
+        let config = RelayConfig::from_values("http://localhost:3001", "key");
+        assert_eq!(config.url, "http://localhost:3001");
+        assert_eq!(config.request_timeout_secs, 30);
+    }
+
+    #[test]
+    fn debug_redacts_api_key() {
+        let config = RelayConfig::from_values("http://localhost:3001", "super-secret");
+        let debug = format!("{:?}", config);
+        assert!(debug.contains("[REDACTED]"));
+        assert!(!debug.contains("super-secret"));
+    }
+}

src/config/sandbox.rs

@@ -272,6 +272,7 @@ fn parse_oauth_access_token(json: &str) -> Option<String> {
 #[cfg(test)]
 mod tests {
     use crate::config::sandbox::*;
+    use crate::testing::credentials::*;
 
     // ── SandboxModeConfig defaults ──────────────────────────────────
 
@@ -405,9 +406,12 @@ mod tests {
 
     #[test]
     fn parse_oauth_token_valid() {
-        let json = r#"{"claudeAiOauth": {"accessToken": "sk-ant-oat01-fake"}}"#;
-        let token = parse_oauth_access_token(json);
-        assert_eq!(token, Some("sk-ant-oat01-fake".to_string()));
+        let json = format!(
+            r#"{{"claudeAiOauth": {{"accessToken": "{}"}}}}"#,
+            TEST_ANTHROPIC_OAUTH_BASIC
+        );
+        let token = parse_oauth_access_token(&json);
+        assert_eq!(token, Some(TEST_ANTHROPIC_OAUTH_BASIC.to_string()));
     }
 
     #[test]
@@ -434,16 +438,19 @@ mod tests {
 
     #[test]
     fn parse_oauth_token_nested_extra_fields() {
-        let json = r#"{
-            "claudeAiOauth": {
-                "accessToken": "sk-ant-oat01-real-token",
+        let json = format!(
+            r#"{{
+            "claudeAiOauth": {{
+                "accessToken": "{}",
                 "refreshToken": "rt-abc",
                 "expiresAt": 1700000000
-            }
-        }"#;
+            }}
+        }}"#,
+            TEST_ANTHROPIC_OAUTH_NESTED
+        );
         assert_eq!(
-            parse_oauth_access_token(json),
-            Some("sk-ant-oat01-real-token".to_string())
+            parse_oauth_access_token(&json),
+            Some(TEST_ANTHROPIC_OAUTH_NESTED.to_string())
         );
     }
 

src/context/mod.rs

@@ -12,4 +12,4 @@ mod state;
 
 pub use manager::ContextManager;
 pub use memory::{ActionRecord, ConversationMemory, Memory};
-pub use state::{JobContext, JobState, StateTransition};
+pub use state::{JobContext, JobState, StateTransition, TokenBudgetExceeded};