diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 00000000000..472089ed5b1
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,48 @@
+version: 2
+updates:
+  - package-ecosystem: cargo
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    groups:
+      tokio-ecosystem:
+        patterns:
+          - "tokio*"
+          - "hyper*"
+          - "axum*"
+          - "tower*"
+      serialization:
+        patterns:
+          - "serde*"
+          - "prost*"
+      wasm:
+        patterns:
+          - "wasmtime*"
+          - "wit-*"
+          - "wasm-*"
+          - "cargo-component*"
+      everything-else:
+        patterns:
+          - "*"
+        exclude-patterns:
+          - "tokio*"
+          - "hyper*"
+          - "axum*"
+          - "tower*"
+          - "serde*"
+          - "prost*"
+          - "wasmtime*"
+          - "wit-*"
+          - "wasm-*"
+          - "cargo-component*"
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      actions:
+        patterns:
+          - "*"
diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml
index 26c15d8928a..a792ea0d95f 100644
--- a/.github/workflows/claude-review.yml
+++ b/.github/workflows/claude-review.yml
@@ -20,12 +20,13 @@ jobs:
     if: contains(github.event.pull_request.labels.*.name, 'staging-promotion')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Run Claude Code review
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@1eddb334cfa79fdb21ecbe2180ca1a016e8e7d47 # v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           allowed_bots: "ironclaw-ci[bot]"
diff --git a/.github/workflows/code_style.yml b/.github/workflows/code_style.yml
index f89161d9285..614611d3424 100644
--- a/.github/workflows/code_style.yml
+++ b/.github/workflows/code_style.yml
@@ -2,15 +2,20 @@ name: Code Style
 on:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   format:
     name: Formatting
     runs-on: ubuntu-latest
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      with:
+        persist-credentials: false
     - name: Install Rust
-      uses: dtolnay/rust-toolchain@stable
+      uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
       with:
         components: rustfmt
     - name: Check formatting
@@ -21,9 +26,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      with:
+        persist-credentials: false
     - name: Run cargo deny
-      uses: EmbarkStudios/cargo-deny-action@v2
+      uses: EmbarkStudios/cargo-deny-action@3fd3802e88374d3fe9159b834c7714ec57d6c979 # v2
 
   clippy:
     name: Clippy (${{ matrix.name }})
@@ -40,12 +47,14 @@ jobs:
             flags: "--no-default-features --features libsql"
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      with:
+        persist-credentials: false
     - name: Install Rust
-      uses: dtolnay/rust-toolchain@stable
+      uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
       with:
         components: clippy
-    - uses: Swatinem/rust-cache@v2
+    - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
       with:
         key: clippy-${{ matrix.name }}
     - name: Check lints
@@ -67,12 +76,14 @@ jobs:
             flags: "--no-default-features --features libsql"
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      with:
+        persist-credentials: false
     - name: Install Rust
-      uses: dtolnay/rust-toolchain@stable
+      uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
       with:
         components: clippy
-    - uses: Swatinem/rust-cache@v2
+    - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
       with:
         key: clippy-windows-${{ matrix.name }}
     - name: Check lints
@@ -83,10 +94,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@v5
+        persist-credentials: false
+    - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
       with:
         python-version: "3.12"
     - name: Check for .unwrap(), .expect(), assert!() in production code
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
index 2f885b169e2..074433d232d 100644
--- a/.github/workflows/coverage.yml
+++ b/.github/workflows/coverage.yml
@@ -32,13 +32,15 @@ on:
     branches: [main]
 
 permissions:
-  id-token: write
   contents: read
 
 jobs:
   coverage:
     name: Coverage (${{ matrix.name }})
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
     strategy:
       fail-fast: false
       matrix:
@@ -67,19 +69,21 @@ jobs:
           --health-timeout 5s
           --health-retries 5
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
 
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
         with:
           components: llvm-tools-preview
           targets: wasm32-wasip2
 
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           key: coverage-${{ matrix.name }}
 
       - name: Install cargo-llvm-cov
-        uses: taiki-e/install-action@cargo-llvm-cov
+        uses: taiki-e/install-action@62b0f2dec647a8e604c6a0fda0e38530180dce20 # cargo-llvm-cov
 
       - name: Install cargo-component
         run: |
@@ -113,7 +117,7 @@ jobs:
         run: cargo llvm-cov ${{ matrix.flags }} --workspace --lcov --output-path lcov.info
 
       - name: Upload to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5
         with:
           files: lcov.info
           flags: ${{ matrix.name }}
@@ -125,20 +129,25 @@ jobs:
     name: E2E Coverage
     runs-on: ubuntu-latest
     timeout-minutes: 30
+    permissions:
+      id-token: write
+      contents: read
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
 
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
         with:
           components: llvm-tools-preview
           targets: wasm32-wasip2
 
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           key: e2e-coverage
 
       - name: Install cargo-llvm-cov
-        uses: taiki-e/install-action@cargo-llvm-cov
+        uses: taiki-e/install-action@62b0f2dec647a8e604c6a0fda0e38530180dce20 # cargo-llvm-cov
 
       - name: Install cargo-component
         run: |
@@ -162,7 +171,7 @@ jobs:
       - name: Build instrumented binary
         run: cargo build --no-default-features --features libsql
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.12"
 
@@ -197,7 +206,7 @@ jobs:
 
       - name: Upload to Codecov
         if: always()
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5
         with:
           files: e2e-coverage.info
           flags: e2e
@@ -207,7 +216,7 @@ jobs:
 
       - name: Upload screenshots on failure
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: e2e-screenshots
           path: tests/e2e/screenshots/
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index a8e937b93b2..9c6bfacb5ee 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -35,9 +35,10 @@ jobs:
       actions: write
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           ref: ${{ github.event_name == 'schedule' && 'staging' || '' }}
+          persist-credentials: false
 
       - name: Extract version from Cargo.toml
         id: version
@@ -48,50 +49,53 @@ jobs:
 
       - name: Determine tags
         id: tags
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          EVENT_NAME: ${{ github.event_name }}
+          INPUT_TAG: ${{ inputs.tag }}
         run: |
-          VERSION="${{ steps.version.outputs.version }}"
           SHA="sha-${GITHUB_SHA::7}"
           echo "sha_tag=${SHA}" >> "$GITHUB_OUTPUT"
 
-          if [[ "${{ github.event_name }}" == "workflow_call" ]]; then
+          if [[ "${EVENT_NAME}" == "workflow_call" ]]; then
             # Release: :version + :latest + :sha-xxx
-            TAGS="${{ env.IMAGE_NAME }}:${VERSION}"
-            TAGS="${TAGS},${{ env.IMAGE_NAME }}:latest"
-            TAGS="${TAGS},${{ env.IMAGE_NAME }}:${SHA}"
-            WORKER_TAGS="${{ env.WORKER_IMAGE_NAME }}:${VERSION}"
-            WORKER_TAGS="${WORKER_TAGS},${{ env.WORKER_IMAGE_NAME }}:latest"
-            WORKER_TAGS="${WORKER_TAGS},${{ env.WORKER_IMAGE_NAME }}:${SHA}"
-          elif [[ "${{ github.event_name }}" == "schedule" ]]; then
+            TAGS="${IMAGE_NAME}:${VERSION}"
+            TAGS="${TAGS},${IMAGE_NAME}:latest"
+            TAGS="${TAGS},${IMAGE_NAME}:${SHA}"
+            WORKER_TAGS="${WORKER_IMAGE_NAME}:${VERSION}"
+            WORKER_TAGS="${WORKER_TAGS},${WORKER_IMAGE_NAME}:latest"
+            WORKER_TAGS="${WORKER_TAGS},${WORKER_IMAGE_NAME}:${SHA}"
+          elif [[ "${EVENT_NAME}" == "schedule" ]]; then
             # Daily staging: :staging + :sha-xxx
-            TAGS="${{ env.IMAGE_NAME }}:staging"
-            TAGS="${TAGS},${{ env.IMAGE_NAME }}:${SHA}"
-            WORKER_TAGS="${{ env.WORKER_IMAGE_NAME }}:staging"
-            WORKER_TAGS="${WORKER_TAGS},${{ env.WORKER_IMAGE_NAME }}:${SHA}"
+            TAGS="${IMAGE_NAME}:staging"
+            TAGS="${TAGS},${IMAGE_NAME}:${SHA}"
+            WORKER_TAGS="${WORKER_IMAGE_NAME}:staging"
+            WORKER_TAGS="${WORKER_TAGS},${WORKER_IMAGE_NAME}:${SHA}"
           else
             # Manual dispatch: :sha-xxx only
-            TAGS="${{ env.IMAGE_NAME }}:${SHA}"
-            WORKER_TAGS="${{ env.WORKER_IMAGE_NAME }}:${SHA}"
+            TAGS="${IMAGE_NAME}:${SHA}"
+            WORKER_TAGS="${WORKER_IMAGE_NAME}:${SHA}"
           fi
 
           # Manual override adds an extra tag (e.g. "staging")
-          if [[ -n "${{ inputs.tag }}" ]]; then
-            TAGS="${TAGS},${{ env.IMAGE_NAME }}:${{ inputs.tag }}"
-            WORKER_TAGS="${WORKER_TAGS},${{ env.WORKER_IMAGE_NAME }}:${{ inputs.tag }}"
+          if [[ -n "${INPUT_TAG}" ]]; then
+            TAGS="${TAGS},${IMAGE_NAME}:${INPUT_TAG}"
+            WORKER_TAGS="${WORKER_TAGS},${WORKER_IMAGE_NAME}:${INPUT_TAG}"
           fi
           echo "tags=${TAGS}" >> "$GITHUB_OUTPUT"
           echo "worker_tags=${WORKER_TAGS}" >> "$GITHUB_OUTPUT"
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
 
       - name: Log in to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
         with:
           username: ${{ vars.DOCKER_REGISTRY_USER }}
           password: ${{ secrets.DOCKER_REGISTRY_TOKEN }}
 
       - name: Build and push (ironclaw)
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
         with:
           context: .
           push: true
@@ -101,7 +105,7 @@ jobs:
           cache-to: type=gha,mode=max
 
       - name: Build and push (ironclaw-worker)
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
         with:
           context: .
           file: Dockerfile.worker
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
index 65ba6c3d12f..9ed4df9cad9 100644
--- a/.github/workflows/e2e.yml
+++ b/.github/workflows/e2e.yml
@@ -16,6 +16,9 @@ on:
       - "src/channels/web/**"
       - "tests/e2e/**"
 
+permissions:
+  contents: read
+
 jobs:
   # ── Step 1: compile once ──────────────────────────────────────────────────
   build:
@@ -23,13 +26,14 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
 
-      - uses: dtolnay/rust-toolchain@stable
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
 
-      - uses: actions/cache@v4
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: |
             target
@@ -40,7 +44,7 @@ jobs:
         run: cargo build --no-default-features --features libsql
 
       - name: Upload binary
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: ironclaw-e2e-binary
           path: target/debug/ironclaw
@@ -65,12 +69,13 @@ jobs:
           - group: routines
             files: "tests/e2e/scenarios/test_owner_scope.py tests/e2e/scenarios/test_routine_event_batch.py"
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
 
       - name: Download binary
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: ironclaw-e2e-binary
           path: target/debug/
@@ -78,7 +83,7 @@ jobs:
       - name: Make binary executable
         run: chmod +x target/debug/ironclaw
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.12"
 
@@ -93,7 +98,7 @@ jobs:
 
       - name: Upload screenshots on failure
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: e2e-screenshots-${{ matrix.group }}
           path: tests/e2e/screenshots/
diff --git a/.github/workflows/pr-label-classify.yml b/.github/workflows/pr-label-classify.yml
index 90f141de717..7d0ee97a9ac 100644
--- a/.github/workflows/pr-label-classify.yml
+++ b/.github/workflows/pr-label-classify.yml
@@ -14,9 +14,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout base branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           ref: ${{ github.event.pull_request.base.ref }}
+          persist-credentials: false
 
       - name: Classify PR
         env:
diff --git a/.github/workflows/pr-label-scope.yml b/.github/workflows/pr-label-scope.yml
index 1c3885612e7..c798f09bce6 100644
--- a/.github/workflows/pr-label-scope.yml
+++ b/.github/workflows/pr-label-scope.yml
@@ -12,7 +12,7 @@ jobs:
   scope:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/labeler@v5
+      - uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5
         with:
           configuration-path: .github/labeler.yml
           sync-labels: false          # additive only — never remove scope labels
diff --git a/.github/workflows/regression-test-check.yml b/.github/workflows/regression-test-check.yml
index 75b8eb55304..d06301b3787 100644
--- a/.github/workflows/regression-test-check.yml
+++ b/.github/workflows/regression-test-check.yml
@@ -3,29 +3,37 @@ name: Regression Test Check
 on:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   regression-test:
     name: Regression test enforcement
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Fetch PR head and base
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
         run: |
-          git fetch origin ${{ github.event.pull_request.base.ref }}
-          git fetch origin pull/${{ github.event.pull_request.number }}/head:pr-head
+          git fetch origin -- "$BASE_REF"
+          git fetch origin -- "pull/${PR_NUMBER}/head:pr-head"
 
       - name: Check for regression tests
         env:
           PR_TITLE: ${{ github.event.pull_request.title }}
           PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
+          PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
         run: |
           set -euo pipefail
 
-          BASE_REF="origin/${{ github.event.pull_request.base.ref }}"
+          BASE_REF="origin/${PR_BASE_REF}"
           # Use the actual PR head, not the merge commit that actions/checkout checks out
           HEAD_REF="pr-head"
 
diff --git a/.github/workflows/release-plz-batch-summary.yml b/.github/workflows/release-plz-batch-summary.yml
index 0e1067362fd..8e01ec40e21 100644
--- a/.github/workflows/release-plz-batch-summary.yml
+++ b/.github/workflows/release-plz-batch-summary.yml
@@ -29,11 +29,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout base branch
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ github.event_name == 'workflow_dispatch' && 'main' || github.event.pull_request.base.ref }}
           fetch-depth: 0
           fetch-tags: true
+          persist-credentials: false
 
       - name: Update release-plz PR body with staging batch summary
         env:
diff --git a/.github/workflows/release-plz.yml b/.github/workflows/release-plz.yml
index d1be9004e68..cfff0e59720 100644
--- a/.github/workflows/release-plz.yml
+++ b/.github/workflows/release-plz.yml
@@ -17,18 +17,18 @@ jobs:
     steps:
       - &checkout
         name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
           persist-credentials: false
       - &install-rust
         name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
       # Generating a GitHub token, so that PRs and tags created by
       # the release-plz-action can trigger actions workflows.
       - name: Generate GitHub token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
         id: generate-token
         with:
           # GitHub App ID secret name
@@ -36,7 +36,7 @@ jobs:
           # GitHub App private key secret name
           private-key: ${{ secrets.GH_RELEASES_MANAGER_APP_PRIVATE_KEY }}
       - name: Run release-plz
-        uses: release-plz/action@v0.5
+        uses: release-plz/action@1528104d2ca23787631a1c1f022abb64b34c1e11 # v0.5
         with:
           command: release
         env:
@@ -57,15 +57,15 @@ jobs:
     steps:
       - *checkout
       - *install-rust
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
       - name: Generate GitHub token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
         id: generate-token
         with:
           app-id: ${{ secrets.GH_RELEASES_MANAGER_APP_ID }}
           private-key: ${{ secrets.GH_RELEASES_MANAGER_APP_PRIVATE_KEY }}
       - name: Run release-plz
-        uses: release-plz/action@v0.5
+        uses: release-plz/action@1528104d2ca23787631a1c1f022abb64b34c1e11 # v0.5
         with:
           command: release-pr
         env:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c4a4f416d53..b237d28665d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -15,7 +15,7 @@
 
 name: Release
 permissions:
-  "contents": "write"
+  contents: read
 
 # This task will run whenever you push a git tag that looks like a version
 # like "1.0.0", "v0.1.0-prerelease.1", "my-app/0.1.0", "releases/v1.0.0", etc.
@@ -55,7 +55,7 @@ jobs:
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           persist-credentials: false
           submodules: recursive
@@ -65,7 +65,7 @@ jobs:
         shell: bash
         run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.30.3/cargo-dist-installer.sh | sh"
       - name: Cache dist
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/dist
@@ -75,13 +75,20 @@ jobs:
       # (PRs run on the *source* but secrets are usually on the *target* -- that's *good*
       # but also really annoying to build CI around when it needs secrets to work right.)
       - id: plan
+        env:
+          IS_PUSH: ${{ !github.event.pull_request }}
+          REF_NAME: ${{ github.ref_name }}
         run: |
-          dist ${{ (!github.event.pull_request && format('host --steps=create --tag={0}', github.ref_name)) || 'plan' }} --output-format=json > plan-dist-manifest.json
+          if [ "$IS_PUSH" = "true" ]; then
+            dist host --steps=create --tag="$REF_NAME" --output-format=json > plan-dist-manifest.json
+          else
+            dist plan --output-format=json > plan-dist-manifest.json
+          fi
           echo "dist ran successfully"
           cat plan-dist-manifest.json
           echo "manifest=$(jq -c "." plan-dist-manifest.json)" >> "$GITHUB_OUTPUT"
       - name: "Upload dist-manifest.json"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: artifacts-plan-dist-manifest
           path: plan-dist-manifest.json
@@ -117,7 +124,7 @@ jobs:
       - name: enable windows longpaths
         run: |
           git config --global core.longpaths true
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           persist-credentials: false
           submodules: recursive
@@ -128,7 +135,7 @@ jobs:
             curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
             echo "$HOME/.cargo/bin" >> $GITHUB_PATH
           fi
-      - uses: swatinem/rust-cache@v2
+      - uses: swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           key: ${{ join(matrix.targets, '-') }}
           cache-provider: ${{ matrix.cache_provider }}
@@ -136,7 +143,7 @@ jobs:
         run: ${{ matrix.install_dist.run }}
       # Get the dist-manifest
       - name: Fetch local artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           pattern: artifacts-*
           path: target/distrib/
@@ -180,9 +187,13 @@ jobs:
         run: |
           ${{ matrix.packages_install }}
       - name: Build artifacts
+        env:
+          TAG_FLAG: ${{ needs.plan.outputs.tag-flag }}
+          DIST_ARGS: ${{ matrix.dist_args }}
         run: |
           # Actually do builds and make zips and whatnot
-          dist build ${{ needs.plan.outputs.tag-flag }} --print=linkage --output-format=json ${{ matrix.dist_args }} > dist-manifest.json
+          # shellcheck disable=SC2086  # TAG_FLAG/DIST_ARGS may contain multiple args
+          dist build $TAG_FLAG --print=linkage --output-format=json $DIST_ARGS > dist-manifest.json
           echo "dist ran successfully"
       - id: cargo-dist
         name: Post-build
@@ -198,7 +209,7 @@ jobs:
 
           cp dist-manifest.json "$BUILD_MANIFEST_NAME"
       - name: "Upload artifacts"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: artifacts-build-local-${{ join(matrix.targets, '_') }}
           path: |
@@ -215,27 +226,30 @@ jobs:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       BUILD_MANIFEST_NAME: target/distrib/global-dist-manifest.json
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           persist-credentials: false
           submodules: recursive
       - name: Install cached dist
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/
       - run: chmod +x ~/.cargo/bin/dist
       # Get all the local artifacts for the global tasks to use (for e.g. checksums)
       - name: Fetch local artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           pattern: artifacts-*
           path: target/distrib/
           merge-multiple: true
       - id: cargo-dist
         shell: bash
+        env:
+          TAG_FLAG: ${{ needs.plan.outputs.tag-flag }}
         run: |
-          dist build ${{ needs.plan.outputs.tag-flag }} --output-format=json "--artifacts=global" > dist-manifest.json
+          # shellcheck disable=SC2086  # TAG_FLAG may expand to '--tag=X' or empty
+          dist build $TAG_FLAG --output-format=json "--artifacts=global" > dist-manifest.json
           echo "dist ran successfully"
 
           # Parse out what we just built and upload it to scratch storage
@@ -245,7 +259,7 @@ jobs:
 
           cp dist-manifest.json "$BUILD_MANIFEST_NAME"
       - name: "Upload artifacts"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: artifacts-build-global
           path: |
@@ -260,7 +274,7 @@ jobs:
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           persist-credentials: false
           submodules: recursive
@@ -268,7 +282,7 @@ jobs:
         run: |
           rustup target add wasm32-wasip2
           cargo install cargo-component --locked || true
-      - uses: swatinem/rust-cache@v2
+      - uses: swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           key: wasm-extensions
       - name: Build and package WASM extensions
@@ -374,7 +388,7 @@ jobs:
           echo "=== WASM bundles built ==="
           ls -la target/wasm-bundles/
       - name: "Upload WASM bundles"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: artifacts-wasm-extensions
           path: |
@@ -390,45 +404,50 @@ jobs:
       - build-wasm-extensions
     # Only run if we're "publishing", and only if plan, local, global, and wasm didn't fail (skipped is fine)
     if: ${{ always() && needs.plan.result == 'success' && needs.plan.outputs.publishing == 'true' && (needs.build-global-artifacts.result == 'skipped' || needs.build-global-artifacts.result == 'success') && (needs.build-local-artifacts.result == 'skipped' || needs.build-local-artifacts.result == 'success') && (needs.build-wasm-extensions.result == 'skipped' || needs.build-wasm-extensions.result == 'success') }}
+    permissions:
+      contents: write
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     runs-on: "ubuntu-22.04"
     outputs:
       val: ${{ steps.host.outputs.manifest }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           persist-credentials: false
           submodules: recursive
       - name: Install cached dist
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/
       - run: chmod +x ~/.cargo/bin/dist
       # Fetch artifacts from scratch-storage
       - name: Fetch artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           pattern: artifacts-*
           path: target/distrib/
           merge-multiple: true
       - id: host
         shell: bash
+        env:
+          TAG_FLAG: ${{ needs.plan.outputs.tag-flag }}
         run: |
-          dist host ${{ needs.plan.outputs.tag-flag }} --steps=upload --steps=release --output-format=json > dist-manifest.json
+          # shellcheck disable=SC2086  # TAG_FLAG may expand to '--tag=X' or empty
+          dist host $TAG_FLAG --steps=upload --steps=release --output-format=json > dist-manifest.json
           echo "artifacts uploaded and released successfully"
           cat dist-manifest.json
           echo "manifest=$(jq -c "." dist-manifest.json)" >> "$GITHUB_OUTPUT"
       - name: "Upload dist-manifest.json"
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           # Overwrite the previous copy
           name: artifacts-dist-manifest
           path: dist-manifest.json
       # Create a GitHub Release while uploading all files to it
       - name: "Download GitHub Artifacts"
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           pattern: artifacts-*
           path: artifacts
@@ -443,11 +462,13 @@ jobs:
           ANNOUNCEMENT_TITLE: "${{ fromJson(steps.host.outputs.manifest).announcement_title }}"
           ANNOUNCEMENT_BODY: "${{ fromJson(steps.host.outputs.manifest).announcement_github_body }}"
           RELEASE_COMMIT: "${{ github.sha }}"
+          RELEASE_TAG: ${{ needs.plan.outputs.tag }}
         run: |
           # Write and read notes from a file to avoid quoting breaking things
-          echo "$ANNOUNCEMENT_BODY" > $RUNNER_TEMP/notes.txt
+          echo "$ANNOUNCEMENT_BODY" > "$RUNNER_TEMP/notes.txt"
 
-          gh release create "${{ needs.plan.outputs.tag }}" --target "$RELEASE_COMMIT" $PRERELEASE_FLAG --title "$ANNOUNCEMENT_TITLE" --notes-file "$RUNNER_TEMP/notes.txt" artifacts/*
+          # shellcheck disable=SC2086  # PRERELEASE_FLAG is '--prerelease' or empty
+          gh release create "$RELEASE_TAG" --target "$RELEASE_COMMIT" $PRERELEASE_FLAG --title "$ANNOUNCEMENT_TITLE" --notes-file "$RUNNER_TEMP/notes.txt" artifacts/*
 
   # Commit patched manifest SHA256 checksums back to main so the repo
   # stays in sync with the released artifacts.
@@ -464,11 +485,12 @@ jobs:
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           ref: main
+          # persist-credentials kept enabled — job pushes a checksum-update branch.
       - name: Fetch WASM checksums
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: artifacts-wasm-extensions
           path: target/wasm-bundles/
@@ -537,7 +559,7 @@ jobs:
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           persist-credentials: false
           submodules: recursive
diff --git a/.github/workflows/staging-ci.yml b/.github/workflows/staging-ci.yml
index 99ee2bfc63a..5b8cc1abfe1 100644
--- a/.github/workflows/staging-ci.yml
+++ b/.github/workflows/staging-ci.yml
@@ -15,10 +15,7 @@ on:
         default: false
 
 permissions:
-  contents: write
-  issues: write
-  pull-requests: write
-  checks: read
+  contents: read
 
 concurrency:
   group: staging-ci
@@ -29,6 +26,9 @@ jobs:
   resolve-promotion-base:
     name: Resolve promotion base
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
     outputs:
       promotion_base: ${{ steps.resolve.outputs.promotion_base }}
     steps:
@@ -55,16 +55,19 @@ jobs:
     name: Check for new commits
     needs: resolve-promotion-base
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     outputs:
       has_changes: ${{ steps.check.outputs.has_changes }}
       current_head: ${{ steps.check.outputs.current_head }}
       diff_range: ${{ steps.check.outputs.diff_range }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ github.sha }}
           fetch-depth: 0
           fetch-tags: true
+          persist-credentials: false
 
       - name: Check for changes since last tested
         id: check
@@ -135,22 +138,26 @@ jobs:
     needs: [resolve-promotion-base, check-changes]
     if: needs.check-changes.outputs.has_changes == 'true'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     outputs:
       pr_number: ${{ steps.create-pr.outputs.pr_number }}
       promotion_branch: ${{ steps.branch.outputs.branch }}
     steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ needs.check-changes.outputs.current_head }}
-          fetch-depth: 0
-
       - name: Generate GitHub App token
         id: app-token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
         with:
           app-id: ${{ secrets.GH_RELEASES_MANAGER_APP_ID }}
           private-key: ${{ secrets.GH_RELEASES_MANAGER_APP_PRIVATE_KEY }}
 
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ needs.check-changes.outputs.current_head }}
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
+
       - name: Set token
         id: token
         run: |
@@ -251,18 +258,24 @@ jobs:
       needs.create-promotion-pr.result == 'success'
     runs-on: ubuntu-latest
     timeout-minutes: 25
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      checks: read
     outputs:
       gate_passed: ${{ steps.evaluate.outputs.passed }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: staging
           # Need full history to recompute the final promoted range before merge.
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Generate GitHub App token
         id: app-token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
         with:
           app-id: ${{ secrets.GH_RELEASES_MANAGER_APP_ID }}
           private-key: ${{ secrets.GH_RELEASES_MANAGER_APP_PRIVATE_KEY }}
@@ -493,11 +506,14 @@ jobs:
       needs.e2e.result == 'success' &&
       needs.create-promotion-pr.result == 'success'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: staging
           fetch-depth: 0
+          # persist-credentials kept enabled — job pushes the staging-tested tag.
 
       - name: Update staging-tested tag
         run: |
@@ -511,6 +527,8 @@ jobs:
     needs: [check-changes, tests, e2e, create-promotion-pr, gate, update-tag]
     if: always() && needs.check-changes.outputs.has_changes == 'true'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - name: Summary
         run: |
diff --git a/.github/workflows/staging-promotion-metadata.yml b/.github/workflows/staging-promotion-metadata.yml
index 76b8326b29c..3017e97061a 100644
--- a/.github/workflows/staging-promotion-metadata.yml
+++ b/.github/workflows/staging-promotion-metadata.yml
@@ -20,7 +20,6 @@ on:
 
 permissions:
   contents: read
-  pull-requests: write
 
 jobs:
   refresh-single-pr:
@@ -30,15 +29,19 @@ jobs:
        startsWith(github.event.pull_request.head.ref, 'staging-promote/')) ||
       github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
       - name: Checkout workflow source
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           # For chained promotion PRs, the script lives on the trusted PR head,
           # not necessarily on the older promotion branch used as the PR base.
           ref: ${{ github.event_name == 'workflow_dispatch' && 'main' || github.event.pull_request.head.sha }}
           fetch-depth: 0
           fetch-tags: true
+          persist-credentials: false
 
       - name: Refresh staging promotion PR body
         env:
@@ -51,13 +54,17 @@ jobs:
   refresh-open-prs-after-main-push:
     if: github.event_name == 'push'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
       - name: Checkout main
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: main
           fetch-depth: 0
           fetch-tags: true
+          persist-credentials: false
 
       - name: Refresh all open staging promotion PR bodies
         env:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 27a32a502c0..11898cf0fb2 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -13,6 +13,9 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
 jobs:
   tests:
     name: Tests (${{ matrix.name }})
@@ -33,14 +36,15 @@ jobs:
             flags: "--no-default-features --features libsql"
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
       - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
         with:
           targets: wasm32-wasip2
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           key: ${{ matrix.name }}
       - name: Install cargo-component
@@ -58,14 +62,15 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
       - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
         with:
           targets: wasm32-wasip2
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           key: heavy-integration
       - name: Build Telegram WASM channel
@@ -88,12 +93,13 @@ jobs:
     timeout-minutes: 15
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
       - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
       - name: Run Telegram Channel Tests
         run: |
           timeout --signal=INT --kill-after=30s 10m \
@@ -117,12 +123,13 @@ jobs:
             flags: "--no-default-features --features libsql"
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
       - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           key: windows-${{ matrix.name }}
       - name: Check compilation
@@ -137,14 +144,15 @@ jobs:
     timeout-minutes: 30
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
       - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
         with:
           targets: wasm32-wasip2
-      - uses: Swatinem/rust-cache@v2
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           key: wasm-extensions
       - name: Install cargo-component
@@ -161,12 +169,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
       - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           key: bench
       - name: Compile benchmarks
@@ -180,9 +189,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
       - name: Build Docker image
         run: docker build -t ironclaw-test:ci .
 
@@ -192,9 +202,10 @@ jobs:
     if: github.event_name == 'pull_request'
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ inputs.ref || github.sha }}
+          persist-credentials: false
           fetch-depth: 0
       - name: Check version bumps for changed extensions
         env:
diff --git a/Cargo.lock b/Cargo.lock
index e935bebab8e..4096c42da54 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -228,6 +228,26 @@ dependencies = [
  "derive_arbitrary",
 ]
 
+[[package]]
+name = "arboard"
+version = "3.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0348a1c054491f4bfe6ab86a7b6ab1e44e45d899005de92f58b3df180b36ddaf"
+dependencies = [
+ "clipboard-win",
+ "image",
+ "log",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-foundation",
+ "parking_lot",
+ "percent-encoding",
+ "windows-sys 0.60.2",
+ "x11rb",
+]
+
 [[package]]
 name = "arrayref"
 version = "0.3.9"
@@ -1271,6 +1291,12 @@ version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
 [[package]]
 name = "bytes"
 version = "1.11.1"
@@ -1368,6 +1394,12 @@ dependencies = [
  "winx",
 ]
 
+[[package]]
+name = "cassowary"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df8670b8c7b9dae1793364eafadf7239c40d669904660c5960d74cfd80b46a53"
+
 [[package]]
 name = "cast"
 version = "0.3.0"
@@ -1585,6 +1617,20 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
+[[package]]
+name = "compact_str"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b79c4069c6cad78e2e0cdfcbd26275770669fb39fd308a752dc110e83b9af32"
+dependencies = [
+ "castaway",
+ "cfg-if",
+ "itoa",
+ "rustversion",
+ "ryu",
+ "static_assertions",
+]
+
 [[package]]
 name = "compact_str"
 version = "0.9.0"
@@ -1676,7 +1722,7 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "980c2afde4af43d6a05c5be738f9eae595cff86dce1f38f88b95058a98c027f3"
 dependencies = [
- "crossterm",
+ "crossterm 0.29.0",
 ]
 
 [[package]]
@@ -1903,7 +1949,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04a63daf06a168535c74ab97cdba3ed4fa5d4f32cb36e437dcceb83d66854b7c"
 dependencies = [
  "crokey-proc_macros",
- "crossterm",
+ "crossterm 0.29.0",
  "once_cell",
  "serde",
  "strict",
@@ -1915,7 +1961,7 @@ version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "847f11a14855fc490bd5d059821895c53e77eeb3c2b73ee3dded7ce77c93b231"
 dependencies = [
- "crossterm",
+ "crossterm 0.29.0",
  "proc-macro2",
  "quote",
  "strict",
@@ -1989,6 +2035,22 @@ version = "0.8.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
+[[package]]
+name = "crossterm"
+version = "0.28.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "829d955a0bb380ef178a640b91779e3987da38c9aea133b20614cfed8cdea9c6"
+dependencies = [
+ "bitflags 2.11.0",
+ "crossterm_winapi",
+ "mio",
+ "parking_lot",
+ "rustix 0.38.44",
+ "signal-hook",
+ "signal-hook-mio",
+ "winapi",
+]
+
 [[package]]
 name = "crossterm"
 version = "0.29.0"
@@ -2333,6 +2395,16 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "dispatch2"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
+dependencies = [
+ "bitflags 2.11.0",
+ "objc2",
+]
+
 [[package]]
 name = "displaydoc"
 version = "0.2.5"
@@ -2602,6 +2674,26 @@ version = "2.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
 
+[[package]]
+name = "fax"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f05de7d48f37cd6730705cbca900770cab77a89f413d23e100ad7fad7795a0ab"
+dependencies = [
+ "fax_derive",
+]
+
+[[package]]
+name = "fax_derive"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a0aca10fb742cb43f9e7bb8467c91aa9bcb8e3ffbc6a6f7389bb93ffc920577d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "fd-lock"
 version = "4.0.4"
@@ -2613,6 +2705,15 @@ dependencies = [
  "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
 [[package]]
 name = "fiat-crypto"
 version = "0.2.9"
@@ -2878,20 +2979,30 @@ version = "0.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "49cf31a6d70300cf81461098f7797571362387ef4bf85d32ac47eaa59b3a5a1a"
 dependencies = [
- "compact_str",
+ "compact_str 0.9.0",
  "get-size-derive2",
  "hashbrown 0.16.1",
  "ordermap",
  "smallvec",
 ]
 
+[[package]]
+name = "gethostname"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bd49230192a3797a9a4d6abe9b3eed6f7fa4c8a8a4947977c6f80025f92cbd8"
+dependencies = [
+ "rustix 1.1.4",
+ "windows-link",
+]
+
 [[package]]
 name = "getopts"
 version = "0.2.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
 dependencies = [
- "unicode-width 0.2.2",
+ "unicode-width 0.2.0",
 ]
 
 [[package]]
@@ -3045,6 +3156,8 @@ version = "0.15.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
 dependencies = [
+ "allocator-api2",
+ "equivalent",
  "foldhash 0.1.5",
  "serde",
 ]
@@ -3148,7 +3261,7 @@ dependencies = [
  "base64 0.22.1",
  "html-escape",
  "html5ever 0.39.0",
- "lru",
+ "lru 0.16.3",
  "once_cell",
  "regex",
  "serde",
@@ -3562,6 +3675,20 @@ dependencies = [
  "icu_properties",
 ]
 
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "moxcms",
+ "num-traits",
+ "png",
+ "tiff",
+]
+
 [[package]]
 name = "indexmap"
 version = "1.9.3"
@@ -3585,6 +3712,15 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
 [[package]]
 name = "inout"
 version = "0.1.4"
@@ -3607,6 +3743,19 @@ dependencies = [
  "tempfile",
 ]
 
+[[package]]
+name = "instability"
+version = "0.3.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5eb2d60ef19920a3a9193c3e371f726ec1dafc045dac788d0fb3704272458971"
+dependencies = [
+ "darling",
+ "indoc",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "interpolator"
 version = "0.5.0"
@@ -3669,7 +3818,7 @@ dependencies = [
  "clap_complete",
  "cookie",
  "cron",
- "crossterm",
+ "crossterm 0.29.0",
  "deadpool-postgres",
  "dirs 6.0.0",
  "dotenvy",
@@ -3691,10 +3840,11 @@ dependencies = [
  "ironclaw_engine",
  "ironclaw_safety",
  "ironclaw_skills",
+ "ironclaw_tui",
  "json5",
  "jsonwebtoken",
  "libsql",
- "lru",
+ "lru 0.16.3",
  "mime_guess",
  "open",
  "pdf-extract",
@@ -3770,6 +3920,7 @@ dependencies = [
  "pretty_assertions",
  "serde",
  "serde_json",
+ "sha2",
  "thiserror 2.0.18",
  "tokio",
  "tracing",
@@ -3808,6 +3959,24 @@ dependencies = [
  "urlencoding",
 ]
 
+[[package]]
+name = "ironclaw_tui"
+version = "0.1.0"
+dependencies = [
+ "arboard",
+ "chrono",
+ "image",
+ "pulldown-cmark",
+ "ratatui",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+ "tokio",
+ "tracing",
+ "tui-textarea",
+ "unicode-width 0.2.0",
+]
+
 [[package]]
 name = "is-docker"
 version = "0.2.0"
@@ -3874,6 +4043,15 @@ dependencies = [
  "either",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itertools"
 version = "0.14.0"
@@ -4292,6 +4470,15 @@ dependencies = [
  "weezl",
 ]
 
+[[package]]
+name = "lru"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "234cf4f4a04dc1f57e24b96cc0cd600cf2af460d4161ac5ecdd0af8e1f3b2a38"
+dependencies = [
+ "hashbrown 0.15.5",
+]
+
 [[package]]
 name = "lru"
 version = "0.16.3"
@@ -4520,6 +4707,16 @@ dependencies = [
  "strum 0.27.2",
 ]
 
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
 [[package]]
 name = "nanoid"
 version = "0.4.0"
@@ -4678,6 +4875,27 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "objc2"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a12a8ed07aefc768292f076dc3ac8c48f3781c8f2d5851dd3d98950e8c5a89f"
+dependencies = [
+ "objc2-encode",
+]
+
+[[package]]
+name = "objc2-app-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
+dependencies = [
+ "bitflags 2.11.0",
+ "objc2",
+ "objc2-core-graphics",
+ "objc2-foundation",
+]
+
 [[package]]
 name = "objc2-core-foundation"
 version = "0.3.2"
@@ -4685,6 +4903,49 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
 dependencies = [
  "bitflags 2.11.0",
+ "dispatch2",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-core-graphics"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
+dependencies = [
+ "bitflags 2.11.0",
+ "dispatch2",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-io-surface",
+]
+
+[[package]]
+name = "objc2-encode"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33"
+
+[[package]]
+name = "objc2-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
+dependencies = [
+ "bitflags 2.11.0",
+ "objc2",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-io-surface"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d"
+dependencies = [
+ "bitflags 2.11.0",
+ "objc2",
+ "objc2-core-foundation",
 ]
 
 [[package]]
@@ -5163,6 +5424,19 @@ dependencies = [
  "plotters-backend",
 ]
 
+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags 2.11.0",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
 [[package]]
 name = "polling"
 version = "3.11.0"
@@ -5395,6 +5669,17 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "pulldown-cmark"
+version = "0.12.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f86ba2052aebccc42cbbb3ed234b8b13ce76f75c3551a303cb2bcffcff12bb14"
+dependencies = [
+ "bitflags 2.11.0",
+ "memchr",
+ "unicase",
+]
+
 [[package]]
 name = "pulley-interpreter"
 version = "28.0.1"
@@ -5406,6 +5691,12 @@ dependencies = [
  "sptr",
 ]
 
+[[package]]
+name = "pxfm"
+version = "0.1.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5a041e753da8b807c9255f28de81879c78c876392ff2469cde94799b2896b9d"
+
 [[package]]
 name = "pyo3"
 version = "0.28.3"
@@ -5466,6 +5757,12 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quinn"
 version = "0.11.9"
@@ -5645,6 +5942,27 @@ version = "1.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "973443cf09a9c8656b574a866ab68dfa19f0867d0340648c7d2f6a71b8a8ea68"
 
+[[package]]
+name = "ratatui"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eabd94c2f37801c20583fc49dd5cd6b0ba68c716787c2dd6ed18571e1e63117b"
+dependencies = [
+ "bitflags 2.11.0",
+ "cassowary",
+ "compact_str 0.8.1",
+ "crossterm 0.28.1",
+ "indoc",
+ "instability",
+ "itertools 0.13.0",
+ "lru 0.12.5",
+ "paste",
+ "strum 0.26.3",
+ "unicode-segmentation",
+ "unicode-truncate",
+ "unicode-width 0.2.0",
+]
+
 [[package]]
 name = "rayon"
 version = "1.11.0"
@@ -5983,7 +6301,7 @@ source = "git+https://github.com/astral-sh/ruff.git?rev=6ded4bed1651e30b34dd04cd
 dependencies = [
  "aho-corasick",
  "bitflags 2.11.0",
- "compact_str",
+ "compact_str 0.9.0",
  "get-size2",
  "is-macro",
  "memchr",
@@ -6001,7 +6319,7 @@ source = "git+https://github.com/astral-sh/ruff.git?rev=6ded4bed1651e30b34dd04cd
 dependencies = [
  "bitflags 2.11.0",
  "bstr",
- "compact_str",
+ "compact_str 0.9.0",
  "get-size2",
  "memchr",
  "ruff_python_ast",
@@ -6275,7 +6593,7 @@ dependencies = [
  "radix_trie",
  "rustyline-derive",
  "unicode-segmentation",
- "unicode-width 0.2.2",
+ "unicode-width 0.2.0",
  "utf8parse",
  "windows-sys 0.60.2",
 ]
@@ -6935,6 +7253,15 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "strum"
+version = "0.26.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
+dependencies = [
+ "strum_macros 0.26.4",
+]
+
 [[package]]
 name = "strum"
 version = "0.27.2"
@@ -6953,6 +7280,19 @@ dependencies = [
  "strum_macros 0.28.0",
 ]
 
+[[package]]
+name = "strum_macros"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c6bee85a5a24955dc440386795aa378cd9cf82acd5f764469152d2270e581be"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "rustversion",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "strum_macros"
 version = "0.27.2"
@@ -7243,6 +7583,20 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "tiff"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63feaf3343d35b6ca4d50483f94843803b0f51634937cc2ec519fc32232bc52"
+dependencies = [
+ "fax",
+ "flate2",
+ "half",
+ "quick-error",
+ "weezl",
+ "zune-jpeg",
+]
+
 [[package]]
 name = "time"
 version = "0.3.47"
@@ -7850,6 +8204,17 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
+[[package]]
+name = "tui-textarea"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0a5318dd619ed73c52a9417ad19046724effc1287fb75cdcc4eca1d6ac1acbae"
+dependencies = [
+ "crossterm 0.28.1",
+ "ratatui",
+ "unicode-width 0.2.0",
+]
+
 [[package]]
 name = "tungstenite"
 version = "0.26.2"
@@ -7966,6 +8331,17 @@ version = "1.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9629274872b2bfaf8d66f5f15725007f635594914870f65218920345aa11aa8c"
 
+[[package]]
+name = "unicode-truncate"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3644627a5af5fa321c95b9b235a72fd24cd29c648c2c379431e6628655627bf"
+dependencies = [
+ "itertools 0.13.0",
+ "unicode-segmentation",
+ "unicode-width 0.1.14",
+]
+
 [[package]]
 name = "unicode-width"
 version = "0.1.14"
@@ -7974,9 +8350,9 @@ checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
 
 [[package]]
 name = "unicode-width"
-version = "0.2.2"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
+checksum = "1fc81956842c57dac11422a97c3b8195a1ff727f06e85c84ed2e8aa277c9a0fd"
 
 [[package]]
 name = "unicode-xid"
@@ -8626,7 +9002,7 @@ dependencies = [
  "bumpalo",
  "leb128fmt",
  "memchr",
- "unicode-width 0.2.2",
+ "unicode-width 0.2.0",
  "wasm-encoder 0.245.1",
 ]
 
@@ -9272,6 +9648,23 @@ dependencies = [
  "tap",
 ]
 
+[[package]]
+name = "x11rb"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9993aa5be5a26815fe2c3eacfc1fde061fc1a1f094bf1ad2a18bf9c495dd7414"
+dependencies = [
+ "gethostname",
+ "rustix 1.1.4",
+ "x11rb-protocol",
+]
+
+[[package]]
+name = "x11rb-protocol"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
+
 [[package]]
 name = "x509-cert"
 version = "0.2.5"
@@ -9580,6 +9973,21 @@ dependencies = [
  "pkg-config",
 ]
 
+[[package]]
+name = "zune-core"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb8a0807f7c01457d0379ba880ba6322660448ddebc890ce29bb64da71fb40f9"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]
+
 [[package]]
 name = "zvariant"
 version = "4.2.0"
diff --git a/Cargo.toml b/Cargo.toml
index a7f91ba5678..83ea874e61c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,5 @@
 [workspace]
-members = [".", "crates/ironclaw_common", "crates/ironclaw_safety", "crates/ironclaw_skills", "crates/ironclaw_engine"]
+members = [".", "crates/ironclaw_common", "crates/ironclaw_safety", "crates/ironclaw_skills", "crates/ironclaw_engine", "crates/ironclaw_tui"]
 exclude = [
     "channels-src/discord",
     "channels-src/telegram",
@@ -113,6 +113,7 @@ ironclaw_common = { path = "crates/ironclaw_common", version = "0.1.0" }
 ironclaw_engine = { path = "crates/ironclaw_engine", version = "0.1.0" }
 ironclaw_safety = { path = "crates/ironclaw_safety", version = "0.2.0" }
 ironclaw_skills = { path = "crates/ironclaw_skills", version = "0.1.0" }
+ironclaw_tui = { path = "crates/ironclaw_tui", version = "0.1.0", optional = true }
 regex = "1"
 aho-corasick = "1"
 
@@ -239,6 +240,7 @@ 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"]
+tui = ["dep:ironclaw_tui"]
 import = ["dep:json5", "libsql"]
 
 [[test]]
diff --git a/crates/ironclaw_common/src/event.rs b/crates/ironclaw_common/src/event.rs
index 43de9158690..54a33b6b728 100644
--- a/crates/ironclaw_common/src/event.rs
+++ b/crates/ironclaw_common/src/event.rs
@@ -59,6 +59,8 @@ pub enum AppEvent {
     ToolStarted {
         name: String,
         #[serde(skip_serializing_if = "Option::is_none")]
+        detail: Option<String>,
+        #[serde(skip_serializing_if = "Option::is_none")]
         thread_id: Option<String>,
     },
     #[serde(rename = "tool_completed")]
@@ -380,6 +382,7 @@ mod tests {
             },
             AppEvent::ToolStarted {
                 name: String::new(),
+                detail: None,
                 thread_id: None,
             },
             AppEvent::ToolCompleted {
diff --git a/crates/ironclaw_engine/CLAUDE.md b/crates/ironclaw_engine/CLAUDE.md
index 346b8c9c119..0ea1b6a1fbc 100644
--- a/crates/ironclaw_engine/CLAUDE.md
+++ b/crates/ironclaw_engine/CLAUDE.md
@@ -83,11 +83,12 @@ Validated by `ThreadState::can_transition_to()`. Terminal states: `Done`, `Faile
 
 ## Learning Missions
 
-Three event-driven missions fire automatically after thread completion:
+Four event-driven missions fire automatically after thread completion:
 
 1. **Error diagnosis** (`self-improvement`) — fires when a thread completes with trace issues. Diagnoses root cause and applies prompt overlays or orchestrator patches.
-2. **Skill extraction** (`skill-extraction`) — fires when a thread succeeds with 5+ steps and 3+ tool actions. Extracts reusable skills with activation metadata, CodeAct code snippets, and domain tags. Output stored as `DocType::Skill` MemoryDoc.
-3. **Conversation insights** (`conversation-insights`) — fires every 5 completed threads in a project. Extracts user preferences, domain knowledge, and workflow patterns.
+2. **Skill repair** (`skill-repair`) — fires when a completed thread used an active skill but the trace suggests the skill instructions were stale, incomplete, or missing verification. Applies the smallest safe versioned update to the implicated skill.
+3. **Skill extraction** (`skill-extraction`) — fires when a thread succeeds with 5+ steps and 3+ tool actions. Extracts reusable skills with activation metadata, CodeAct code snippets, and domain tags. Output stored as `DocType::Skill` MemoryDoc.
+4. **Conversation insights** (`conversation-insights`) — fires every 5 completed threads in a project. Extracts user preferences, domain knowledge, and workflow patterns.
 
 Created by `MissionManager::ensure_learning_missions()` at project bootstrap.
 
diff --git a/crates/ironclaw_engine/Cargo.toml b/crates/ironclaw_engine/Cargo.toml
index 634e7ca1cc3..1ac046d5e61 100644
--- a/crates/ironclaw_engine/Cargo.toml
+++ b/crates/ironclaw_engine/Cargo.toml
@@ -24,6 +24,7 @@ thiserror = "2"
 tokio = { version = "1", features = ["sync", "time", "macros", "rt"] }
 tracing = "0.1"
 uuid = { version = "1", features = ["v4", "serde"] }
+sha2 = "0.10"
 
 [dev-dependencies]
 pretty_assertions = "1"
diff --git a/crates/ironclaw_engine/orchestrator/default.py b/crates/ironclaw_engine/orchestrator/default.py
index a9b32d5f310..ee701f4d7c2 100644
--- a/crates/ironclaw_engine/orchestrator/default.py
+++ b/crates/ironclaw_engine/orchestrator/default.py
@@ -478,6 +478,20 @@ def run_loop(context, goal, actions, state, config):
             all_skills = __list_skills__()
             active_skills = select_skills(all_skills, goal, max_candidates=3, max_tokens=4000)
             if active_skills:
+                __set_active_skills__([
+                    {
+                        "doc_id": s.get("doc_id", ""),
+                        "name": s.get("metadata", {}).get("name", "?"),
+                        "version": s.get("metadata", {}).get("version", 1),
+                        "snippet_names": [
+                            sn.get("name", "")
+                            for sn in s.get("metadata", {}).get("code_snippets", [])
+                            if sn.get("name")
+                        ],
+                        "force_activated": False,
+                    }
+                    for s in active_skills
+                ])
                 skill_text = format_skills(active_skills)
                 append_system_append(working_messages, skill_text)
                 # Emit skill activation event for CLI/gateway display
diff --git a/crates/ironclaw_engine/prompts/mission_skill_repair.md b/crates/ironclaw_engine/prompts/mission_skill_repair.md
new file mode 100644
index 00000000000..122f58f5689
--- /dev/null
+++ b/crates/ironclaw_engine/prompts/mission_skill_repair.md
@@ -0,0 +1,70 @@
+You are the skill-repair learning mission for the IronClaw engine. You receive trigger payloads from completed threads where an active skill was relevant, but execution suggests the skill instructions were incomplete, stale, incorrectly ordered, or missing verification or workarounds.
+
+## Input
+
+`state["trigger_payload"]` contains:
+- `source_thread_id` — the completed thread that exposed the skill gap
+- `goal` — what the thread was trying to accomplish
+- `active_skills` — implicated skills with `doc_id`, `name`, `version`, and snippet names
+- `issues` — trace issues from the thread
+- `error_messages` — action failure text
+- `observed_actions` — actions actually attempted during execution
+- `repair_hints` — conservative hint categories such as `missing_prerequisite`, `stale_command_path`, `missing_pitfall`, `missing_verification`
+
+## Mission
+
+Choose the single most likely implicated skill and produce the smallest safe repair.
+
+Classify the gap as exactly one of:
+- `missing_prerequisite`
+- `wrong_ordering`
+- `stale_command_path`
+- `missing_branch`
+- `missing_pitfall`
+- `missing_verification`
+
+## Process
+
+1. Inspect the implicated skill and source context with tools (`memory_search`, `memory_read`, `read_file`, `shell`, etc.).
+2. Confirm the gap from the thread evidence. If the evidence points to engine behavior instead of the skill, do not repair the skill.
+3. Generate the smallest safe content patch:
+   - add an auth or setup prerequisite check
+   - add a missing ordering note
+   - fix one exact command or path
+   - add one platform-specific branch or workaround
+   - add one verification or smoke-test step
+4. Keep the skill focused. Do not rewrite the entire skill unless the existing content is unusable.
+
+## Output Format
+
+Return a single JSON object in `FINAL(...)` with this shape:
+
+```json
+{
+  "doc_id": "<uuid>",
+  "repair_type": "missing_prerequisite",
+  "summary": "Added GitHub auth prerequisite before gh commands.",
+  "updated_content": "<full repaired skill prompt content>",
+  "description": "<optional updated one-line description>",
+  "activation": {
+    "keywords": ["github", "pull request"],
+    "patterns": [],
+    "tags": ["github"],
+    "exclude_keywords": [],
+    "max_context_tokens": 1200
+  },
+  "code_snippets": [],
+  "next_focus": "Watch for repeated failures in repo-cloning flows.",
+  "goal_achieved": false
+}
+```
+
+Only include `description`, `activation`, or `code_snippets` if they truly need to change.
+
+## Rules
+
+- Repair only one skill per thread.
+- Only target a `doc_id` from `active_skills`.
+- Prefer additive edits over broad rewrites.
+- Do not write the skill doc directly with `memory_write`; return structured JSON and let the runtime apply the versioned update.
+- If the evidence is weak or the gap is not skill-related, call `FINAL("No safe skill repair identified")`.
diff --git a/crates/ironclaw_engine/src/executor/orchestrator.rs b/crates/ironclaw_engine/src/executor/orchestrator.rs
index d3b3872f5ef..f1328082ea8 100644
--- a/crates/ironclaw_engine/src/executor/orchestrator.rs
+++ b/crates/ironclaw_engine/src/executor/orchestrator.rs
@@ -41,7 +41,7 @@ use crate::types::message::ThreadMessage;
 use crate::types::project::ProjectId;
 use crate::types::shared_owner_id;
 use crate::types::step::{StepId, TokenUsage};
-use crate::types::thread::{Thread, ThreadState};
+use crate::types::thread::{ActiveSkillProvenance, Thread, ThreadState};
 
 use super::scripting::{execute_code, json_to_monty, monty_to_json, monty_to_string};
 
@@ -455,6 +455,9 @@ pub async fn execute_orchestrator(
                     // __record_skill_usage__(doc_id, success)
                     "__record_skill_usage__" => handle_record_skill_usage(args, store).await,
 
+                    // __set_active_skills__(skills)
+                    "__set_active_skills__" => handle_set_active_skills(args, thread),
+
                     // Unknown — let Monty resolve it (user-defined functions, builtins)
                     other => ExtFunctionResult::NotFound(other.to_string()),
                 };
@@ -1756,6 +1759,31 @@ async fn handle_record_skill_usage(
     ExtFunctionResult::Return(MontyObject::None)
 }
 
+/// Handle `__set_active_skills__(skills)`.
+///
+/// Persists the selected skill provenance onto the thread so post-run learning
+/// flows can reason about the exact skill versions and snippets that were active.
+fn handle_set_active_skills(args: &[MontyObject], thread: &mut Thread) -> ExtFunctionResult {
+    let skills_json = args
+        .first()
+        .map(monty_to_json)
+        .unwrap_or_else(|| serde_json::json!([]));
+
+    let skills = match serde_json::from_value::<Vec<ActiveSkillProvenance>>(skills_json) {
+        Ok(skills) => skills,
+        Err(e) => {
+            debug!("__set_active_skills__: invalid payload: {e}");
+            return ExtFunctionResult::Return(MontyObject::None);
+        }
+    };
+
+    if let Err(e) = thread.set_active_skills(&skills) {
+        debug!("__set_active_skills__: failed to persist active skills: {e}");
+    }
+
+    ExtFunctionResult::Return(MontyObject::None)
+}
+
 // ── Helpers ─────────────────────────────────────────────────
 
 /// Build the context variables injected into the orchestrator Python.
diff --git a/crates/ironclaw_engine/src/lib.rs b/crates/ironclaw_engine/src/lib.rs
index fb39628384a..63b49f3b1aa 100644
--- a/crates/ironclaw_engine/src/lib.rs
+++ b/crates/ironclaw_engine/src/lib.rs
@@ -39,7 +39,9 @@ pub use types::provenance::Provenance;
 pub use types::step::{
     ActionCall, ActionResult, ExecutionTier, LlmResponse, Step, StepId, StepStatus, TokenUsage,
 };
-pub use types::thread::{Thread, ThreadConfig, ThreadId, ThreadState, ThreadType};
+pub use types::thread::{
+    ActiveSkillProvenance, Thread, ThreadConfig, ThreadId, ThreadState, ThreadType,
+};
 
 // ── Re-exports: traits ──────────────────────────────────────
 
diff --git a/crates/ironclaw_engine/src/memory/skill_tracker.rs b/crates/ironclaw_engine/src/memory/skill_tracker.rs
index a0fbd76ef85..0b21c29074b 100644
--- a/crates/ironclaw_engine/src/memory/skill_tracker.rs
+++ b/crates/ironclaw_engine/src/memory/skill_tracker.rs
@@ -6,7 +6,8 @@
 
 use std::sync::Arc;
 
-use ironclaw_skills::v2::V2SkillMetadata;
+use ironclaw_skills::v2::{SkillRevision, V2SkillMetadata};
+use sha2::{Digest, Sha256};
 
 use crate::traits::store::Store;
 use crate::types::error::EngineError;
@@ -17,6 +18,19 @@ pub struct SkillTracker {
     store: Arc<dyn Store>,
 }
 
+fn compute_content_hash(content: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(content.as_bytes());
+    format!(
+        "sha256:{}",
+        hasher
+            .finalize()
+            .iter()
+            .map(|b| format!("{:02x}", b))
+            .collect::<String>()
+    )
+}
+
 impl SkillTracker {
     pub fn new(store: Arc<dyn Store>) -> Self {
         Self { store }
@@ -74,6 +88,7 @@ impl SkillTracker {
         &self,
         doc_id: DocId,
         new_content: String,
+        expected_version: Option<u32>,
         updater: impl FnOnce(&mut V2SkillMetadata),
     ) -> Result<(), EngineError> {
         let doc = self
@@ -89,9 +104,43 @@ impl SkillTracker {
                 reason: format!("invalid skill metadata: {e}"),
             })?;
 
+        if let Some(expected) = expected_version
+            && meta.version != expected
+        {
+            return Err(EngineError::Skill {
+                reason: format!(
+                    "skill {} version conflict: expected {expected}, found {}",
+                    doc_id.0, meta.version
+                ),
+            });
+        }
+
+        // Always recompute from actual content — meta.content_hash may have
+        // drifted if the doc was updated outside this tracker (e.g. direct
+        // memory_write).
+        let archived_hash = compute_content_hash(&doc.content);
+        meta.revisions.push(SkillRevision {
+            version: meta.version,
+            content: doc.content.clone(),
+            description: meta.description.clone(),
+            activation: meta.activation.clone(),
+            code_snippets: meta.code_snippets.clone(),
+            content_hash: archived_hash,
+            archived_at: Some(chrono::Utc::now()),
+        });
+        // Cap in-memory revisions at 10 to bound metadata size on every
+        // load_memory_doc.  This is a pragmatic trade-off: full prompt
+        // snapshots embedded in the skill JSON can grow to many KB per
+        // revision.  Older revisions are dropped; if long-term retention is
+        // needed, they should be externalized to separate MemoryDocs.
+        if meta.revisions.len() > 10 {
+            let keep_from = meta.revisions.len() - 10;
+            meta.revisions.drain(0..keep_from);
+        }
         meta.parent_version = Some(meta.version);
         meta.version += 1;
         updater(&mut meta);
+        meta.content_hash = compute_content_hash(&new_content);
 
         let updated_doc = MemoryDoc {
             content: new_content,
@@ -107,9 +156,9 @@ impl SkillTracker {
 
     /// Rollback a skill to its previous version.
     ///
-    /// Decrements the version to `parent_version` if available. This is a
-    /// simple version decrement — the actual content rollback requires the
-    /// caller to also restore the content from a backup.
+    /// If an archived revision exists for `parent_version`, restores the full
+    /// content and metadata snapshot. Otherwise falls back to a simple version
+    /// decrement without content restoration for older skills.
     pub async fn rollback_skill(&self, doc_id: DocId) -> Result<(), EngineError> {
         let doc = self
             .store
@@ -128,10 +177,32 @@ impl SkillTracker {
             reason: format!("skill {} has no parent version to rollback to", doc_id.0),
         })?;
 
-        meta.version = parent;
-        meta.parent_version = None;
+        let revision_opt = meta
+            .revisions
+            .iter()
+            .position(|revision| revision.version == parent);
+
+        let rolled_content = if let Some(revision_index) = revision_opt {
+            let revision = meta.revisions[revision_index].clone();
+            meta.version = revision.version;
+            meta.description = revision.description;
+            meta.activation = revision.activation;
+            meta.code_snippets = revision.code_snippets;
+            meta.content_hash = revision.content_hash;
+            meta.revisions
+                .retain(|archived| archived.version < revision.version);
+            meta.repairs
+                .retain(|repair| repair.to_version <= revision.version);
+            meta.parent_version = meta.revisions.iter().map(|archived| archived.version).max();
+            revision.content
+        } else {
+            meta.version = parent;
+            meta.parent_version = None;
+            doc.content.clone()
+        };
 
         let updated_doc = MemoryDoc {
+            content: rolled_content,
             metadata: serde_json::to_value(&meta).map_err(|e| EngineError::Skill {
                 reason: format!("failed to serialize skill metadata: {e}"),
             })?,
@@ -166,6 +237,8 @@ mod tests {
                 last_used: None,
             },
             parent_version: None,
+            revisions: vec![],
+            repairs: vec![],
             content_hash: String::new(),
         };
 
@@ -227,7 +300,7 @@ mod tests {
         let tracker = SkillTracker::new(store.clone());
 
         tracker
-            .update_skill(doc_id, "Updated content".to_string(), |meta| {
+            .update_skill(doc_id, "Updated content".to_string(), None, |meta| {
                 meta.description = "Updated description".to_string();
             })
             .await
@@ -240,6 +313,8 @@ mod tests {
         assert_eq!(meta.version, 2);
         assert_eq!(meta.parent_version, Some(1));
         assert_eq!(meta.description, "Updated description");
+        assert_eq!(meta.revisions.len(), 1);
+        assert_eq!(meta.revisions[0].version, 1);
     }
 
     #[tokio::test]
@@ -253,7 +328,7 @@ mod tests {
 
         // First update to version 2
         tracker
-            .update_skill(doc_id, "v2 content".to_string(), |_| {})
+            .update_skill(doc_id, "v2 content".to_string(), None, |_| {})
             .await
             .unwrap();
 
@@ -264,6 +339,8 @@ mod tests {
         let meta: V2SkillMetadata = serde_json::from_value(rolled.metadata).unwrap();
         assert_eq!(meta.version, 1);
         assert_eq!(meta.parent_version, None);
+        assert_eq!(rolled.content, "Test skill prompt");
+        assert!(meta.revisions.is_empty());
     }
 
     #[tokio::test]
@@ -287,4 +364,25 @@ mod tests {
         let result = tracker.record_usage(DocId::new(), true).await;
         assert!(result.is_err());
     }
+
+    #[tokio::test]
+    async fn test_update_skill_version_conflict() {
+        let project_id = ProjectId::new();
+        let doc = make_skill_doc(project_id);
+        let doc_id = doc.id;
+
+        let store = Arc::new(crate::tests::InMemoryStore::with_docs(vec![doc]));
+        let tracker = SkillTracker::new(store);
+
+        let result = tracker
+            .update_skill(doc_id, "Updated content".to_string(), Some(2), |_| {})
+            .await;
+
+        assert!(result.is_err());
+        let error = result.unwrap_err().to_string();
+        assert!(
+            error.contains("version conflict"),
+            "expected version conflict error, got: {error}"
+        );
+    }
 }
diff --git a/crates/ironclaw_engine/src/runtime/mission.rs b/crates/ironclaw_engine/src/runtime/mission.rs
index ac3afc129be..c6b94934f46 100644
--- a/crates/ironclaw_engine/src/runtime/mission.rs
+++ b/crates/ironclaw_engine/src/runtime/mission.rs
@@ -4,21 +4,27 @@
 //! progress. The manager handles lifecycle (create, pause, resume, complete)
 //! and delegates thread spawning to [`ThreadManager`].
 
+use std::collections::HashSet;
 use std::sync::Arc;
 
+use serde::Deserialize;
 use tokio::sync::RwLock;
 use tracing::debug;
 
-use crate::memory::RetrievalEngine;
+use ironclaw_skills::types::ActivationCriteria;
+use ironclaw_skills::v2::{CodeSnippet, SkillRepairRecord, SkillRepairType, V2SkillMetadata};
+
+use crate::executor::trace::{ExecutionTrace, IssueSeverity};
+use crate::memory::{RetrievalEngine, SkillTracker};
 use crate::runtime::manager::ThreadManager;
 use crate::runtime::messaging::ThreadOutcome;
 use crate::traits::store::Store;
 use crate::types::error::EngineError;
-use crate::types::memory::MemoryDoc;
+use crate::types::memory::{DocId, DocType, MemoryDoc};
 use crate::types::mission::{Mission, MissionCadence, MissionId, MissionStatus};
 use crate::types::project::ProjectId;
 use crate::types::shared_owner_id;
-use crate::types::thread::{ThreadConfig, ThreadId, ThreadType};
+use crate::types::thread::{ActiveSkillProvenance, Thread, ThreadConfig, ThreadId, ThreadType};
 
 /// Notification emitted when a mission thread completes.
 ///
@@ -433,10 +439,12 @@ impl MissionManager {
     /// Subscribes to the ThreadManager's event broadcast channel and watches
     /// for `StateChanged { to: Done }`. For each completed non-Mission thread:
     ///
-    /// 1. **Error diagnosis** — if trace has issues, fires `thread_completed_with_issues`
-    /// 2. **Skill extraction** — if thread succeeded with many steps/actions,
+    /// 1. **Skill repair** — if an active skill looks stale or incomplete,
+    ///    fires `thread_completed_with_skill_gap`
+    /// 2. **Error diagnosis** — if trace has issues, fires `thread_completed_with_issues`
+    /// 3. **Skill extraction** — if thread succeeded with many steps/actions,
     ///    fires `thread_completed_with_learnings`
-    /// 3. **Conversation insights** — after every N threads in a conversation,
+    /// 4. **Conversation insights** — after every N threads in a conversation,
     ///    fires `conversation_insights_due`
     pub fn start_event_listener(self: &Arc<Self>, _owner_id: String) {
         let mgr = Arc::clone(self);
@@ -457,17 +465,9 @@ impl MissionManager {
             loop {
                 match rx.recv().await {
                     Ok(event) => {
-                        // Only react to threads transitioning to Done
-                        let is_done = matches!(
-                            event.kind,
-                            crate::types::event::EventKind::StateChanged {
-                                to: crate::types::thread::ThreadState::Done,
-                                ..
-                            }
-                        );
-                        if !is_done {
+                        let Some(terminal_state) = learning_terminal_state(&event.kind) else {
                             continue;
-                        }
+                        };
 
                         // Load the completed thread
                         let thread = match mgr.store.load_thread(event.thread_id).await {
@@ -480,8 +480,49 @@ impl MissionManager {
                             continue;
                         }
 
-                        // ── Trigger 1: Error diagnosis ──────────────────
                         let trace = crate::executor::trace::build_trace(&thread);
+                        // Single pass over events for both skill-repair and
+                        // error-diagnosis triggers (avoids repeated iteration
+                        // on large event logs).
+                        let (error_messages, _observed_actions) =
+                            collect_errors_and_actions(&thread);
+                        let active_skills = thread.active_skills();
+
+                        // ── Trigger 1: Skill repair ───────────────────────
+                        // NOTE: skill-repair and error-diagnosis can both fire
+                        // for the same thread. Each targets a different mission
+                        // so they won't collide, but both may spawn concurrent
+                        // threads. This is intentional — skill-repair fixes the
+                        // *skill* while error-diagnosis fixes the *prompt/orchestrator*.
+                        if !active_skills.is_empty() {
+                            let tracker = SkillTracker::new(Arc::clone(&mgr.store));
+                            let success = thread_completed_successfully(&thread, &trace);
+                            for skill in &active_skills {
+                                if let Err(e) = tracker.record_usage(skill.doc_id, success).await {
+                                    debug!(
+                                        skill_doc_id = %skill.doc_id.0,
+                                        thread_id = %thread.id,
+                                        "event listener: failed to record skill usage: {e}"
+                                    );
+                                }
+                            }
+
+                            if let Some(payload) =
+                                build_skill_gap_payload(&thread, &trace, &active_skills)
+                                && let Err(e) = mgr
+                                    .fire_on_system_event(
+                                        "engine",
+                                        "thread_completed_with_skill_gap",
+                                        &thread.user_id,
+                                        Some(payload),
+                                    )
+                                    .await
+                            {
+                                debug!("event listener: failed to fire skill repair: {e}");
+                            }
+                        }
+
+                        // ── Trigger 2: Error diagnosis ──────────────────
                         if !trace.issues.is_empty() {
                             let issues: Vec<serde_json::Value> = trace
                                 .issues
@@ -489,31 +530,13 @@ impl MissionManager {
                                 .map(|i| {
                                     serde_json::json!({
                                         "severity": format!("{:?}", i.severity),
-                                        "category": i.category,
-                                        "description": i.description,
+                                        "category": i.category.clone(),
+                                        "description": i.description.clone(),
                                         "step": i.step,
                                     })
                                 })
                                 .collect();
 
-                            let error_messages: Vec<String> = thread
-                                .events
-                                .iter()
-                                .filter_map(|e| {
-                                    if let crate::types::event::EventKind::ActionFailed {
-                                        action_name,
-                                        error,
-                                        ..
-                                    } = &e.kind
-                                    {
-                                        Some(format!("{action_name}: {error}"))
-                                    } else {
-                                        None
-                                    }
-                                })
-                                .take(10)
-                                .collect();
-
                             let payload = serde_json::json!({
                                 "source_thread_id": event.thread_id.0.to_string(),
                                 "goal": thread.goal,
@@ -534,7 +557,7 @@ impl MissionManager {
                             }
                         }
 
-                        // ── Trigger 2: Skill extraction ──────────────────
+                        // ── Trigger 3: Skill extraction ──────────────────
                         let action_count = thread
                             .events
                             .iter()
@@ -546,7 +569,7 @@ impl MissionManager {
                             })
                             .count();
 
-                        if thread.state == crate::types::thread::ThreadState::Done
+                        if terminal_state == crate::types::thread::ThreadState::Done
                             && trace
                                 .issues
                                 .iter()
@@ -592,54 +615,59 @@ impl MissionManager {
                             }
                         }
 
-                        // ── Trigger 3: Conversation insights ────────────
-                        // Use the thread's project_id as a proxy for conversation scope.
-                        let conv_key = thread.project_id.0.to_string();
-                        let count = conv_thread_counts.entry(conv_key.clone()).or_insert(0);
-                        *count += 1;
-
-                        if (*count).is_multiple_of(CONVERSATION_INSIGHTS_INTERVAL) {
-                            // Collect recent thread goals for context
-                            let thread_goals: Vec<String> = match mgr
-                                .store
-                                .list_threads(thread.project_id, &thread.user_id)
-                                .await
-                            {
-                                Ok(threads) => threads
+                        // ── Trigger 4: Conversation insights ────────────
+                        // Keep insights tied to successful completions only.
+                        if should_count_for_conversation_insights(terminal_state) {
+                            // Use the thread's project_id as a proxy for conversation scope.
+                            let conv_key = thread.project_id.0.to_string();
+                            let count = conv_thread_counts.entry(conv_key.clone()).or_insert(0);
+                            *count += 1;
+
+                            if (*count).is_multiple_of(CONVERSATION_INSIGHTS_INTERVAL) {
+                                // Collect recent thread goals for context
+                                let thread_goals: Vec<String> = match mgr
+                                    .store
+                                    .list_threads(thread.project_id, &thread.user_id)
+                                    .await
+                                {
+                                    Ok(threads) => threads
+                                        .iter()
+                                        .rev()
+                                        .take(CONVERSATION_INSIGHTS_INTERVAL as usize)
+                                        .map(|t| t.goal.clone())
+                                        .collect(),
+                                    Err(_) => vec![thread.goal.clone()],
+                                };
+
+                                // Collect sample user messages from recent threads
+                                let sample_messages: Vec<String> = thread
+                                    .messages
                                     .iter()
-                                    .rev()
-                                    .take(CONVERSATION_INSIGHTS_INTERVAL as usize)
-                                    .map(|t| t.goal.clone())
-                                    .collect(),
-                                Err(_) => vec![thread.goal.clone()],
-                            };
-
-                            // Collect sample user messages from recent threads
-                            let sample_messages: Vec<String> = thread
-                                .messages
-                                .iter()
-                                .filter(|m| m.role == crate::types::message::MessageRole::User)
-                                .map(|m| m.content.chars().take(200).collect::<String>())
-                                .take(10)
-                                .collect();
-
-                            let payload = serde_json::json!({
-                                "project_id": thread.project_id.0.to_string(),
-                                "completed_thread_count": *count,
-                                "thread_goals": thread_goals,
-                                "sample_user_messages": sample_messages,
-                            });
-
-                            if let Err(e) = mgr
-                                .fire_on_system_event(
-                                    "engine",
-                                    "conversation_insights_due",
-                                    &thread.user_id,
-                                    Some(payload),
-                                )
-                                .await
-                            {
-                                debug!("event listener: failed to fire conversation insights: {e}");
+                                    .filter(|m| m.role == crate::types::message::MessageRole::User)
+                                    .map(|m| m.content.chars().take(200).collect::<String>())
+                                    .take(10)
+                                    .collect();
+
+                                let payload = serde_json::json!({
+                                    "project_id": thread.project_id.0.to_string(),
+                                    "completed_thread_count": *count,
+                                    "thread_goals": thread_goals,
+                                    "sample_user_messages": sample_messages,
+                                });
+
+                                if let Err(e) = mgr
+                                    .fire_on_system_event(
+                                        "engine",
+                                        "conversation_insights_due",
+                                        &thread.user_id,
+                                        Some(payload),
+                                    )
+                                    .await
+                                {
+                                    debug!(
+                                        "event listener: failed to fire conversation insights: {e}"
+                                    );
+                                }
                             }
                         }
                     }
@@ -720,11 +748,11 @@ impl MissionManager {
         Ok(id)
     }
 
-    /// Ensure all three learning missions exist for the given project.
+    /// Ensure the built-in learning missions exist for the given project.
     ///
-    /// Creates (if missing) the self-improvement, skill extraction, and
-    /// conversation insights missions. This is the preferred entry point —
-    /// call once at project bootstrap.
+    /// Creates (if missing) the self-improvement, skill repair, skill
+    /// extraction, and conversation insights missions. This is the preferred
+    /// entry point — call once at project bootstrap.
     pub async fn ensure_learning_missions(
         &self,
         project_id: ProjectId,
@@ -737,7 +765,23 @@ impl MissionManager {
         self.ensure_self_improvement_mission(project_id, user_id)
             .await?;
 
-        // 2. Skill extraction (formerly playbook extraction)
+        // 2. Skill repair
+        self.ensure_mission_by_metadata(
+            project_id,
+            user_id,
+            "skill_repair",
+            "skill-repair",
+            SKILL_REPAIR_GOAL,
+            MissionCadence::OnSystemEvent {
+                source: "engine".into(),
+                event_type: "thread_completed_with_skill_gap".into(),
+            },
+            "Repair versioned skills when execution reveals stale or incomplete instructions",
+            5,
+        )
+        .await?;
+
+        // 3. Skill extraction (formerly playbook extraction)
         self.ensure_mission_by_metadata(
             project_id,
             user_id,
@@ -753,7 +797,7 @@ impl MissionManager {
         )
         .await?;
 
-        // 3. Conversation insights
+        // 4. Conversation insights
         self.ensure_mission_by_metadata(
             project_id,
             user_id,
@@ -769,7 +813,7 @@ impl MissionManager {
         )
         .await?;
 
-        // 4. Expected behavior (user feedback loop)
+        // 5. Expected behavior (user feedback loop)
         self.ensure_mission_by_metadata(
             project_id,
             user_id,
@@ -1092,6 +1136,15 @@ async fn process_mission_outcome_and_notify(
                     "failed to process self-improvement output: {e}"
                 );
             }
+
+            if is_skill_repair_mission(&mission)
+                && let Err(e) = process_skill_repair_output(store, &mission, text).await
+            {
+                debug!(
+                    mission_id = %mission_id,
+                    "failed to process skill-repair output: {e}"
+                );
+            }
         }
         ThreadOutcome::Completed { response: None } => {}
         ThreadOutcome::Failed { error } => {
@@ -1137,6 +1190,15 @@ fn is_self_improvement_mission(mission: &Mission) -> bool {
         .unwrap_or(false)
 }
 
+/// Check if a mission is the skill-repair mission.
+fn is_skill_repair_mission(mission: &Mission) -> bool {
+    mission
+        .metadata
+        .get("skill_repair")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false)
+}
+
 /// Process output from a self-improvement mission thread.
 ///
 /// Two paths:
@@ -1306,6 +1368,491 @@ fn extract_json_from_response(response: &str) -> Option<serde_json::Value> {
         .filter(|v| v.is_object())
 }
 
+#[derive(Debug, Deserialize)]
+struct SkillRepairMissionOutput {
+    doc_id: DocId,
+    repair_type: SkillRepairType,
+    updated_content: String,
+    #[serde(default)]
+    summary: String,
+    #[serde(default)]
+    description: Option<String>,
+    #[serde(default)]
+    activation: Option<ActivationCriteria>,
+    #[serde(default)]
+    code_snippets: Option<Vec<CodeSnippet>>,
+}
+
+async fn process_skill_repair_output(
+    store: &Arc<dyn Store>,
+    mission: &Mission,
+    response: &str,
+) -> Result<(), EngineError> {
+    let json_val = match extract_json_from_response(response) {
+        Some(v) => v,
+        None => {
+            debug!("skill-repair: no structured JSON in response");
+            return Ok(());
+        }
+    };
+    let repair: SkillRepairMissionOutput =
+        serde_json::from_value(json_val).map_err(|e| EngineError::Skill {
+            reason: format!("invalid skill-repair output: {e}"),
+        })?;
+
+    let Some(triggered_skill) = triggered_skill_provenance(mission, repair.doc_id) else {
+        return Err(EngineError::Skill {
+            reason: if has_skill_trigger_payload(mission) {
+                format!(
+                    "skill-repair attempted to modify untriggered skill {}",
+                    repair.doc_id.0
+                )
+            } else {
+                "skill-repair requires an active skill trigger payload".into()
+            },
+        });
+    };
+    if repair.updated_content.trim().is_empty() {
+        return Err(EngineError::Skill {
+            reason: format!(
+                "skill-repair produced empty updated_content for skill {}",
+                repair.doc_id.0
+            ),
+        });
+    }
+
+    let existing =
+        store
+            .load_memory_doc(repair.doc_id)
+            .await?
+            .ok_or_else(|| EngineError::Skill {
+                reason: format!("skill doc not found: {}", repair.doc_id.0),
+            })?;
+    if existing.project_id != mission.project_id {
+        return Err(EngineError::Skill {
+            reason: format!(
+                "skill-repair attempted to modify skill {} outside mission project",
+                repair.doc_id.0
+            ),
+        });
+    }
+    if !existing.is_owned_by(&mission.user_id) {
+        return Err(EngineError::AccessDenied {
+            user_id: mission.user_id.clone(),
+            entity: format!("skill {}", repair.doc_id.0),
+        });
+    }
+    if existing.doc_type != DocType::Skill {
+        return Err(EngineError::Skill {
+            reason: format!(
+                "skill-repair attempted to modify non-skill doc {} ({:?})",
+                repair.doc_id.0, existing.doc_type
+            ),
+        });
+    }
+    serde_json::from_value::<V2SkillMetadata>(existing.metadata.clone()).map_err(|e| {
+        EngineError::Skill {
+            reason: format!("invalid skill metadata for {}: {e}", repair.doc_id.0),
+        }
+    })?;
+    let from_version = triggered_skill.version;
+    let source_thread_id = mission
+        .last_trigger_payload
+        .as_ref()
+        .and_then(|payload| payload.get("source_thread_id"))
+        .and_then(|value| value.as_str())
+        .map(ToString::to_string);
+    let summary = if repair.summary.trim().is_empty() {
+        format!("Applied {:?} repair", repair.repair_type)
+    } else {
+        repair.summary.clone()
+    };
+
+    let tracker = SkillTracker::new(Arc::clone(store));
+    tracker
+        .update_skill(
+            repair.doc_id,
+            repair.updated_content,
+            Some(triggered_skill.version),
+            move |meta| {
+                if let Some(description) = repair.description {
+                    meta.description = description;
+                }
+                if let Some(activation) = repair.activation {
+                    meta.activation = activation;
+                }
+                if let Some(code_snippets) = repair.code_snippets {
+                    meta.code_snippets = code_snippets;
+                }
+                meta.repairs.push(SkillRepairRecord {
+                    source_thread_id,
+                    from_version,
+                    to_version: meta.version,
+                    repair_type: repair.repair_type,
+                    summary,
+                    repaired_at: Some(chrono::Utc::now()),
+                });
+                if meta.repairs.len() > 10 {
+                    let keep_from = meta.repairs.len() - 10;
+                    meta.repairs.drain(0..keep_from);
+                }
+            },
+        )
+        .await
+}
+
+fn has_skill_trigger_payload(mission: &Mission) -> bool {
+    mission
+        .last_trigger_payload
+        .as_ref()
+        .and_then(|payload| payload.get("active_skills"))
+        .and_then(|value| value.as_array())
+        .is_some_and(|skills| !skills.is_empty())
+}
+
+fn triggered_skill_provenance(mission: &Mission, doc_id: DocId) -> Option<ActiveSkillProvenance> {
+    mission
+        .last_trigger_payload
+        .as_ref()
+        .and_then(|payload| payload.get("active_skills"))
+        .cloned()
+        .and_then(|value| serde_json::from_value::<Vec<ActiveSkillProvenance>>(value).ok())
+        .and_then(|skills| skills.into_iter().find(|skill| skill.doc_id == doc_id))
+}
+
+/// Collects error messages and deduplicated observed action names in a single
+/// pass over `thread.events`.  Previous implementation used separate passes
+/// which is wasteful for threads with large event logs.
+fn collect_errors_and_actions(thread: &Thread) -> (Vec<String>, Vec<String>) {
+    let mut error_messages = Vec::new();
+    let mut actions = Vec::new();
+    let mut seen = HashSet::new();
+
+    for event in &thread.events {
+        match &event.kind {
+            crate::types::event::EventKind::ActionFailed {
+                action_name, error, ..
+            } => {
+                if !is_recoverable_action_failure(error) && error_messages.len() < 10 {
+                    error_messages.push(format!("{action_name}: {error}"));
+                }
+                if seen.insert(action_name.clone()) {
+                    actions.push(action_name.clone());
+                }
+            }
+            crate::types::event::EventKind::ActionExecuted { action_name, .. } => {
+                if seen.insert(action_name.clone()) {
+                    actions.push(action_name.clone());
+                }
+            }
+            _ => {}
+        }
+    }
+
+    (error_messages, actions)
+}
+
+fn learning_terminal_state(
+    event_kind: &crate::types::event::EventKind,
+) -> Option<crate::types::thread::ThreadState> {
+    match event_kind {
+        crate::types::event::EventKind::StateChanged {
+            to: crate::types::thread::ThreadState::Done,
+            ..
+        } => Some(crate::types::thread::ThreadState::Done),
+        crate::types::event::EventKind::StateChanged {
+            to: crate::types::thread::ThreadState::Failed,
+            ..
+        } => Some(crate::types::thread::ThreadState::Failed),
+        _ => None,
+    }
+}
+
+fn should_count_for_conversation_insights(
+    terminal_state: crate::types::thread::ThreadState,
+) -> bool {
+    terminal_state == crate::types::thread::ThreadState::Done
+}
+
+fn has_action_failures(thread: &Thread) -> bool {
+    thread.events.iter().any(|event| match &event.kind {
+        crate::types::event::EventKind::ActionFailed { error, .. } => {
+            !is_recoverable_action_failure(error)
+        }
+        _ => false,
+    })
+}
+
+fn is_recoverable_auth_failure_text(text: &str) -> bool {
+    text.to_ascii_lowercase()
+        .contains("authentication required for credential ")
+}
+
+fn is_recoverable_action_failure(error: &str) -> bool {
+    is_recoverable_auth_failure_text(error)
+}
+
+fn action_params_summary(event: &crate::types::event::ThreadEvent) -> Option<&str> {
+    match &event.kind {
+        crate::types::event::EventKind::ActionExecuted { params_summary, .. }
+        | crate::types::event::EventKind::ActionFailed { params_summary, .. } => {
+            params_summary.as_deref()
+        }
+        _ => None,
+    }
+}
+
+fn contains_word(haystack: &str, word: &str) -> bool {
+    for (start, _) in haystack.match_indices(word) {
+        let before_ok = start == 0 || haystack.as_bytes()[start - 1].is_ascii_whitespace();
+        let end = start + word.len();
+        let after_ok = end == haystack.len() || haystack.as_bytes()[end].is_ascii_whitespace();
+        if before_ok && after_ok {
+            return true;
+        }
+    }
+    false
+}
+
+fn has_shell_verification_action(thread: &Thread) -> bool {
+    const PHRASE_PATTERNS: &[&str] = &[
+        "cargo test",
+        "pytest",
+        "npm test",
+        "pnpm test",
+        "yarn test",
+        "go test",
+        "git diff",
+        "git status",
+        "gh pr view",
+        "gh issue view",
+        "cat ",
+        "head ",
+        "tail ",
+        "grep ",
+        "rg ",
+        "find ",
+        "stat ",
+    ];
+    const WORD_PATTERNS: &[&str] = &["ls", "diff", "status", "view", "show"];
+
+    thread.events.iter().any(|event| match &event.kind {
+        crate::types::event::EventKind::ActionExecuted { action_name, .. }
+            if action_name == "shell" =>
+        {
+            action_params_summary(event)
+                .map(|summary| {
+                    let lower = summary.to_lowercase();
+                    PHRASE_PATTERNS
+                        .iter()
+                        .any(|pattern| lower.contains(pattern))
+                        || WORD_PATTERNS.iter().any(|word| contains_word(&lower, word))
+                })
+                .unwrap_or(false)
+        }
+        crate::types::event::EventKind::ActionFailed { action_name, .. }
+            if action_name == "shell" =>
+        {
+            action_params_summary(event)
+                .map(|summary| {
+                    let lower = summary.to_lowercase();
+                    PHRASE_PATTERNS
+                        .iter()
+                        .any(|pattern| lower.contains(pattern))
+                        || WORD_PATTERNS.iter().any(|word| contains_word(&lower, word))
+                })
+                .unwrap_or(false)
+        }
+        _ => false,
+    })
+}
+
+fn has_mutating_shell_or_git_action(thread: &Thread) -> bool {
+    const PHRASE_PATTERNS: &[&str] = &[
+        "apply_patch",
+        "git commit",
+        "git push",
+        "git pull",
+        "git merge",
+        "git rebase",
+        "git cherry-pick",
+        "git revert",
+        "git reset",
+        "git checkout",
+        "git switch",
+        "cargo fmt",
+        "rustfmt",
+        "npm install",
+        "pnpm install",
+        "yarn install",
+        "mkdir ",
+        "rm ",
+        "mv ",
+        "cp ",
+        "touch ",
+        "tee ",
+        "sed -i",
+        "perl -pi",
+    ];
+    const WORD_PATTERNS: &[&str] = &[
+        "write", "create", "delete", "remove", "rename", "patch", "install", "format",
+    ];
+
+    thread.events.iter().any(|event| match &event.kind {
+        crate::types::event::EventKind::ActionExecuted { action_name, .. }
+        | crate::types::event::EventKind::ActionFailed { action_name, .. }
+            if action_name == "shell" || action_name == "git" =>
+        {
+            action_params_summary(event)
+                .map(|summary| {
+                    let lower = summary.to_lowercase();
+                    PHRASE_PATTERNS
+                        .iter()
+                        .any(|pattern| lower.contains(pattern))
+                        || WORD_PATTERNS.iter().any(|word| contains_word(&lower, word))
+                })
+                .unwrap_or(false)
+        }
+        _ => false,
+    })
+}
+
+fn infer_skill_repair_hints(
+    thread: &Thread,
+    trace: &ExecutionTrace,
+    error_messages: &[String],
+    observed_actions: &[String],
+) -> Vec<SkillRepairType> {
+    let mut hints = Vec::new();
+    let mut push_hint = |hint| {
+        if !hints.contains(&hint) {
+            hints.push(hint);
+        }
+    };
+
+    let lower_signals = error_messages
+        .iter()
+        .map(|message| message.to_lowercase())
+        .chain(
+            trace
+                .issues
+                .iter()
+                .filter(|issue| {
+                    !(issue.category == "tool_error"
+                        && is_recoverable_auth_failure_text(&issue.description))
+                })
+                .map(|issue| issue.description.to_lowercase()),
+        )
+        .collect::<Vec<_>>();
+
+    let recoverable_auth_failures = thread
+        .events
+        .iter()
+        .filter_map(|event| {
+            if let crate::types::event::EventKind::ActionFailed { error, .. } = &event.kind
+                && is_recoverable_auth_failure_text(error)
+            {
+                Some(error.to_lowercase())
+            } else {
+                None
+            }
+        })
+        .collect::<Vec<_>>();
+
+    if lower_signals
+        .iter()
+        .chain(recoverable_auth_failures.iter())
+        .any(|message| {
+            ["auth", "login", "token", "credential", "permission denied"]
+                .iter()
+                .any(|needle| message.contains(needle))
+        })
+    {
+        push_hint(SkillRepairType::MissingPrerequisite);
+    }
+
+    if lower_signals.iter().any(|message| {
+        [
+            "command not found",
+            "no such file",
+            "not found",
+            "could not find",
+            "unknown file",
+            "unknown path",
+        ]
+        .iter()
+        .any(|needle| message.contains(needle))
+    }) {
+        push_hint(SkillRepairType::StaleCommandPath);
+    }
+
+    let mutating_actions = observed_actions.iter().any(|action| {
+        matches!(
+            action.as_str(),
+            "write_file" | "apply_patch" | "memory_write" | "skill_install" | "skill_remove"
+        )
+    }) || has_mutating_shell_or_git_action(thread);
+    let verification_actions = observed_actions.iter().any(|action| {
+        matches!(
+            action.as_str(),
+            "read_file" | "memory_read" | "memory_search" | "cargo_test" | "pytest"
+        )
+    }) || has_shell_verification_action(thread);
+    if mutating_actions && !verification_actions {
+        push_hint(SkillRepairType::MissingVerification);
+    }
+
+    if !error_messages.is_empty() && thread.state == crate::types::thread::ThreadState::Done {
+        push_hint(SkillRepairType::MissingPitfall);
+    }
+
+    hints
+}
+
+fn build_skill_gap_payload(
+    thread: &Thread,
+    trace: &ExecutionTrace,
+    active_skills: &[ActiveSkillProvenance],
+) -> Option<serde_json::Value> {
+    let (error_messages, observed_actions) = collect_errors_and_actions(thread);
+    let repair_hints = infer_skill_repair_hints(thread, trace, &error_messages, &observed_actions);
+    if repair_hints.is_empty() {
+        return None;
+    }
+
+    let issues: Vec<serde_json::Value> = trace
+        .issues
+        .iter()
+        .map(|issue| {
+            serde_json::json!({
+                "severity": format!("{:?}", issue.severity),
+                "category": issue.category.clone(),
+                "description": issue.description.clone(),
+                "step": issue.step,
+            })
+        })
+        .collect();
+
+    Some(serde_json::json!({
+        "source_thread_id": thread.id.0.to_string(),
+        "goal": thread.goal,
+        "active_skills": active_skills,
+        "issues": issues,
+        "error_messages": error_messages,
+        "observed_actions": observed_actions,
+        "repair_hints": repair_hints,
+    }))
+}
+
+fn thread_completed_successfully(thread: &Thread, trace: &ExecutionTrace) -> bool {
+    thread.state == crate::types::thread::ThreadState::Done
+        && !has_action_failures(thread)
+        && trace
+            .issues
+            .iter()
+            .all(|issue| issue.severity != IssueSeverity::Error)
+}
+
 /// The goal for the self-improvement mission (autoresearch-style program).
 ///
 /// This is the "program.md" — a concrete, step-by-step prompt that tells the
@@ -1322,6 +1869,9 @@ pub const FIX_PATTERN_DB_TAG: &str = "fix_patterns";
 /// The goal for the skill extraction mission.
 const SKILL_EXTRACTION_GOAL: &str = include_str!("../../prompts/mission_skill_extraction.md");
 
+/// The goal for the skill-repair mission.
+const SKILL_REPAIR_GOAL: &str = include_str!("../../prompts/mission_skill_repair.md");
+
 /// The goal for the conversation insights mission.
 const CONVERSATION_INSIGHTS_GOAL: &str =
     include_str!("../../prompts/mission_conversation_insights.md");
@@ -1359,11 +1909,15 @@ mod tests {
     use crate::types::capability::{ActionDef, CapabilityLease};
     use crate::types::error::EngineError;
     use crate::types::event::ThreadEvent;
-    use crate::types::memory::{DocId, MemoryDoc};
+    use crate::types::memory::{DocId, DocType, MemoryDoc};
     use crate::types::mission::{Mission, MissionCadence, MissionId, MissionStatus};
     use crate::types::project::{Project, ProjectId};
+    use crate::types::step::StepId;
     use crate::types::step::{ActionResult, LlmResponse, Step, TokenUsage};
-    use crate::types::thread::{Thread, ThreadId, ThreadState};
+    use crate::types::thread::{ActiveSkillProvenance, Thread, ThreadId, ThreadState, ThreadType};
+    use ironclaw_skills::SkillTrust;
+    use ironclaw_skills::types::ActivationCriteria;
+    use ironclaw_skills::v2::{SkillMetrics, SkillRepairType, V2SkillMetadata, V2SkillSource};
 
     // ── TestStore — in-memory Store that persists missions ───
 
@@ -1383,6 +1937,33 @@ mod tests {
         }
     }
 
+    fn make_skill_doc(project_id: ProjectId, user_id: &str, name: &str) -> MemoryDoc {
+        let meta = V2SkillMetadata {
+            name: name.to_string(),
+            version: 1,
+            description: format!("{name} description"),
+            activation: ActivationCriteria::default(),
+            source: V2SkillSource::Extracted,
+            trust: SkillTrust::Trusted,
+            code_snippets: vec![],
+            metrics: SkillMetrics::default(),
+            parent_version: None,
+            revisions: vec![],
+            repairs: vec![],
+            content_hash: "sha256:test".to_string(),
+        };
+
+        let mut doc = MemoryDoc::new(
+            project_id,
+            user_id,
+            DocType::Skill,
+            format!("skill:{name}"),
+            "Original skill content",
+        );
+        doc.metadata = serde_json::to_value(&meta).expect("serialize test skill metadata");
+        doc
+    }
+
     #[async_trait::async_trait]
     impl Store for TestStore {
         // ── Thread (minimal — save/load needed by ThreadManager) ──
@@ -2690,4 +3271,419 @@ mod tests {
             "should not duplicate self-improvement mission"
         );
     }
+
+    #[test]
+    fn conversation_insights_count_only_done_threads() {
+        assert!(should_count_for_conversation_insights(ThreadState::Done));
+        assert!(!should_count_for_conversation_insights(ThreadState::Failed));
+    }
+
+    #[test]
+    fn build_skill_gap_payload_uses_active_skill_provenance() {
+        let project_id = ProjectId::new();
+        let mut thread = Thread::new(
+            "repair a github workflow",
+            ThreadType::Foreground,
+            project_id,
+            "alice",
+            ThreadConfig::default(),
+        );
+        thread.state = ThreadState::Done;
+        let skill_doc_id = DocId::new();
+        thread
+            .set_active_skills(&[ActiveSkillProvenance {
+                doc_id: skill_doc_id,
+                name: "github-pr-workflow".to_string(),
+                version: 3,
+                snippet_names: vec!["list_prs".to_string()],
+                force_activated: false,
+            }])
+            .unwrap();
+        thread.add_event(crate::types::event::EventKind::ActionFailed {
+            step_id: StepId::new(),
+            action_name: "shell".to_string(),
+            call_id: "call_1".to_string(),
+            error: "gh auth status: not authenticated".to_string(),
+            params_summary: None,
+        });
+
+        let trace = crate::executor::trace::build_trace(&thread);
+        let active_skills = thread.active_skills();
+        let payload = build_skill_gap_payload(&thread, &trace, &active_skills).unwrap();
+
+        assert_eq!(
+            payload["active_skills"][0]["doc_id"],
+            serde_json::Value::String(skill_doc_id.0.to_string())
+        );
+        let hints = payload["repair_hints"].as_array().unwrap();
+        assert!(
+            hints
+                .iter()
+                .any(|hint| hint.as_str() == Some("missing_prerequisite")),
+            "repair hints should include missing_prerequisite: {payload}"
+        );
+    }
+
+    #[test]
+    fn build_skill_gap_payload_preserves_recoverable_auth_prerequisite_hints() {
+        let project_id = ProjectId::new();
+        let mut thread = Thread::new(
+            "repair a github workflow",
+            ThreadType::Foreground,
+            project_id,
+            "alice",
+            ThreadConfig::default(),
+        );
+        thread.state = ThreadState::Done;
+        thread
+            .set_active_skills(&[ActiveSkillProvenance {
+                doc_id: DocId::new(),
+                name: "github-pr-workflow".to_string(),
+                version: 3,
+                snippet_names: vec![],
+                force_activated: false,
+            }])
+            .unwrap();
+        thread.add_event(crate::types::event::EventKind::ActionFailed {
+            step_id: StepId::new(),
+            action_name: "shell".to_string(),
+            call_id: "call_1".to_string(),
+            error: "authentication required for credential github".to_string(),
+            params_summary: None,
+        });
+
+        let trace = crate::executor::trace::build_trace(&thread);
+        let payload = build_skill_gap_payload(&thread, &trace, &thread.active_skills()).unwrap();
+        let hints = payload["repair_hints"].as_array().unwrap();
+
+        assert!(
+            hints
+                .iter()
+                .any(|hint| hint.as_str() == Some("missing_prerequisite")),
+            "recoverable auth failures should still produce missing_prerequisite: {payload}"
+        );
+    }
+
+    #[test]
+    fn learning_terminal_state_accepts_failed_threads() {
+        let failed_event = crate::types::event::EventKind::StateChanged {
+            from: ThreadState::Running,
+            to: ThreadState::Failed,
+            reason: Some("boom".into()),
+        };
+        assert_eq!(
+            learning_terminal_state(&failed_event),
+            Some(ThreadState::Failed)
+        );
+
+        let done_event = crate::types::event::EventKind::StateChanged {
+            from: ThreadState::Completed,
+            to: ThreadState::Done,
+            reason: None,
+        };
+        assert_eq!(
+            learning_terminal_state(&done_event),
+            Some(ThreadState::Done)
+        );
+    }
+
+    #[test]
+    fn thread_completed_successfully_requires_done_without_action_failures() {
+        let project_id = ProjectId::new();
+
+        let mut clean_thread = Thread::new(
+            "clean success",
+            ThreadType::Foreground,
+            project_id,
+            "alice",
+            ThreadConfig::default(),
+        );
+        clean_thread.state = ThreadState::Done;
+        let clean_trace = crate::executor::trace::build_trace(&clean_thread);
+        assert!(thread_completed_successfully(&clean_thread, &clean_trace));
+
+        let mut failing_thread = Thread::new(
+            "tool failure",
+            ThreadType::Foreground,
+            project_id,
+            "alice",
+            ThreadConfig::default(),
+        );
+        failing_thread.state = ThreadState::Done;
+        failing_thread.add_event(crate::types::event::EventKind::ActionFailed {
+            step_id: StepId::new(),
+            action_name: "shell".to_string(),
+            call_id: "call_1".to_string(),
+            error: "gh auth status: not authenticated".to_string(),
+            params_summary: Some("gh auth status".to_string()),
+        });
+        let failing_trace = crate::executor::trace::build_trace(&failing_thread);
+        assert!(!thread_completed_successfully(
+            &failing_thread,
+            &failing_trace
+        ));
+    }
+
+    #[tokio::test]
+    async fn process_skill_repair_output_updates_skill_and_records_repair() {
+        let store = Arc::new(TestStore::new());
+        let project_id = ProjectId::new();
+        let skill_doc = make_skill_doc(project_id, "alice", "github-pr-workflow");
+        let skill_doc_id = skill_doc.id;
+        store.save_memory_doc(&skill_doc).await.unwrap();
+
+        let mut mission = Mission::new(
+            project_id,
+            "alice",
+            "skill-repair",
+            SKILL_REPAIR_GOAL,
+            MissionCadence::Manual,
+        );
+        mission.metadata = serde_json::json!({"skill_repair": true});
+        mission.last_trigger_payload = Some(serde_json::json!({
+            "source_thread_id": "thread-123",
+            "active_skills": [{
+                "doc_id": skill_doc_id,
+                "name": "github-pr-workflow",
+                "version": 1,
+                "snippet_names": [],
+                "force_activated": false
+            }]
+        }));
+
+        let response = serde_json::json!({
+            "doc_id": skill_doc_id,
+            "repair_type": "missing_verification",
+            "summary": "Added a smoke-test step after the gh command.",
+            "updated_content": "1. Run `gh auth status`\n2. Run the PR command\n3. Verify with `gh pr view`",
+            "description": "GitHub PR workflow with auth and verification",
+        })
+        .to_string();
+
+        process_skill_repair_output(&(store.clone() as Arc<dyn Store>), &mission, &response)
+            .await
+            .unwrap();
+
+        let updated = store.load_memory_doc(skill_doc_id).await.unwrap().unwrap();
+        let meta: V2SkillMetadata = serde_json::from_value(updated.metadata).unwrap();
+        assert_eq!(meta.version, 2);
+        assert_eq!(meta.parent_version, Some(1));
+        assert_eq!(
+            updated.content,
+            "1. Run `gh auth status`\n2. Run the PR command\n3. Verify with `gh pr view`"
+        );
+        assert_eq!(meta.repairs.len(), 1);
+        assert_eq!(
+            meta.repairs[0].repair_type,
+            SkillRepairType::MissingVerification
+        );
+        assert_eq!(
+            meta.repairs[0].source_thread_id.as_deref(),
+            Some("thread-123")
+        );
+        assert_eq!(meta.revisions.len(), 1);
+        assert_eq!(meta.revisions[0].content, "Original skill content");
+    }
+
+    #[tokio::test]
+    async fn process_skill_repair_output_rejects_stale_trigger_version() {
+        let store = Arc::new(TestStore::new());
+        let project_id = ProjectId::new();
+        let mut skill_doc = make_skill_doc(project_id, "alice", "github-pr-workflow");
+        let skill_doc_id = skill_doc.id;
+        skill_doc.content = "Skill content already updated to v2".to_string();
+        let mut meta: V2SkillMetadata = serde_json::from_value(skill_doc.metadata.clone()).unwrap();
+        meta.version = 2;
+        meta.parent_version = Some(1);
+        skill_doc.metadata = serde_json::to_value(&meta).unwrap();
+        store.save_memory_doc(&skill_doc).await.unwrap();
+
+        let mut mission = Mission::new(
+            project_id,
+            "alice",
+            "skill-repair",
+            SKILL_REPAIR_GOAL,
+            MissionCadence::Manual,
+        );
+        mission.metadata = serde_json::json!({"skill_repair": true});
+        mission.last_trigger_payload = Some(serde_json::json!({
+            "source_thread_id": "thread-123",
+            "active_skills": [{
+                "doc_id": skill_doc_id,
+                "name": "github-pr-workflow",
+                "version": 1,
+                "snippet_names": [],
+                "force_activated": false
+            }]
+        }));
+
+        let response = serde_json::json!({
+            "doc_id": skill_doc_id,
+            "repair_type": "missing_verification",
+            "summary": "Stale repair output.",
+            "updated_content": "1. Run the stale command\n2. Verify it"
+        })
+        .to_string();
+
+        let err =
+            process_skill_repair_output(&(store.clone() as Arc<dyn Store>), &mission, &response)
+                .await
+                .unwrap_err();
+        match err {
+            EngineError::Skill { reason } => assert!(
+                reason.contains("version conflict"),
+                "expected version conflict, got: {reason}"
+            ),
+            other => panic!("expected skill error, got: {other:?}"),
+        }
+
+        let updated = store.load_memory_doc(skill_doc_id).await.unwrap().unwrap();
+        let updated_meta: V2SkillMetadata = serde_json::from_value(updated.metadata).unwrap();
+        assert_eq!(updated.content, "Skill content already updated to v2");
+        assert_eq!(updated_meta.version, 2);
+        assert!(updated_meta.repairs.is_empty());
+    }
+
+    #[tokio::test]
+    async fn process_skill_repair_output_rejects_empty_content() {
+        let store = Arc::new(TestStore::new());
+        let project_id = ProjectId::new();
+        let skill_doc = make_skill_doc(project_id, "alice", "github-pr-workflow");
+        let skill_doc_id = skill_doc.id;
+        store.save_memory_doc(&skill_doc).await.unwrap();
+
+        let mut mission = Mission::new(
+            project_id,
+            "alice",
+            "skill-repair",
+            SKILL_REPAIR_GOAL,
+            MissionCadence::Manual,
+        );
+        mission.metadata = serde_json::json!({"skill_repair": true});
+        mission.last_trigger_payload = Some(serde_json::json!({
+            "source_thread_id": "thread-123",
+            "active_skills": [{
+                "doc_id": skill_doc_id,
+                "name": "github-pr-workflow",
+                "version": 1,
+                "snippet_names": [],
+                "force_activated": false
+            }]
+        }));
+
+        let response = serde_json::json!({
+            "doc_id": skill_doc_id,
+            "repair_type": "missing_verification",
+            "summary": "This should be rejected.",
+            "updated_content": "   "
+        })
+        .to_string();
+
+        let err =
+            process_skill_repair_output(&(store.clone() as Arc<dyn Store>), &mission, &response)
+                .await
+                .unwrap_err();
+        match err {
+            EngineError::Skill { reason } => assert!(
+                reason.contains("empty updated_content"),
+                "expected empty-content validation, got: {reason}"
+            ),
+            other => panic!("expected skill error, got: {other:?}"),
+        }
+
+        let updated = store.load_memory_doc(skill_doc_id).await.unwrap().unwrap();
+        let updated_meta: V2SkillMetadata = serde_json::from_value(updated.metadata).unwrap();
+        assert_eq!(updated.content, "Original skill content");
+        assert_eq!(updated_meta.version, 1);
+        assert!(updated_meta.repairs.is_empty());
+    }
+
+    #[tokio::test]
+    async fn process_skill_repair_output_rejects_shared_skill_updates() {
+        let store = Arc::new(TestStore::new());
+        let project_id = ProjectId::new();
+        let skill_doc = make_skill_doc(project_id, shared_owner_id(), "github-pr-workflow");
+        let skill_doc_id = skill_doc.id;
+        store.save_memory_doc(&skill_doc).await.unwrap();
+
+        let mut mission = Mission::new(
+            project_id,
+            "alice",
+            "skill-repair",
+            SKILL_REPAIR_GOAL,
+            MissionCadence::Manual,
+        );
+        mission.metadata = serde_json::json!({"skill_repair": true});
+        mission.last_trigger_payload = Some(serde_json::json!({
+            "source_thread_id": "thread-123",
+            "active_skills": [{
+                "doc_id": skill_doc_id,
+                "name": "github-pr-workflow",
+                "version": 1,
+                "snippet_names": [],
+                "force_activated": false
+            }]
+        }));
+
+        let response = serde_json::json!({
+            "doc_id": skill_doc_id,
+            "repair_type": "missing_verification",
+            "summary": "Attempted shared skill update.",
+            "updated_content": "1. Verify auth\n2. Run the command"
+        })
+        .to_string();
+
+        let err =
+            process_skill_repair_output(&(store.clone() as Arc<dyn Store>), &mission, &response)
+                .await
+                .unwrap_err();
+        match err {
+            EngineError::AccessDenied { user_id, entity } => {
+                assert_eq!(user_id, "alice");
+                assert!(entity.contains(&skill_doc_id.0.to_string()));
+            }
+            other => panic!("expected access denied, got: {other:?}"),
+        }
+
+        let unchanged = store.load_memory_doc(skill_doc_id).await.unwrap().unwrap();
+        let meta: V2SkillMetadata = serde_json::from_value(unchanged.metadata).unwrap();
+        assert_eq!(unchanged.content, "Original skill content");
+        assert_eq!(meta.version, 1);
+        assert!(meta.repairs.is_empty());
+    }
+
+    #[test]
+    fn build_skill_gap_payload_skips_read_only_shell_workflows() {
+        let project_id = ProjectId::new();
+        let mut thread = Thread::new(
+            "inspect github pull requests",
+            ThreadType::Foreground,
+            project_id,
+            "alice",
+            ThreadConfig::default(),
+        );
+        thread.state = ThreadState::Done;
+        thread
+            .set_active_skills(&[ActiveSkillProvenance {
+                doc_id: DocId::new(),
+                name: "github-pr-workflow".to_string(),
+                version: 1,
+                snippet_names: vec![],
+                force_activated: false,
+            }])
+            .unwrap();
+        thread.add_event(crate::types::event::EventKind::ActionExecuted {
+            step_id: StepId::new(),
+            action_name: "shell".to_string(),
+            call_id: "call_1".to_string(),
+            params_summary: Some("gh pr list --repo nearai/ironclaw".to_string()),
+            duration_ms: 15,
+        });
+
+        let trace = crate::executor::trace::build_trace(&thread);
+        assert!(
+            build_skill_gap_payload(&thread, &trace, &thread.active_skills()).is_none(),
+            "read-only shell workflows should not trigger skill repair"
+        );
+    }
 }
diff --git a/crates/ironclaw_engine/src/types/thread.rs b/crates/ironclaw_engine/src/types/thread.rs
index 919c9cffa31..5154fdde1fb 100644
--- a/crates/ironclaw_engine/src/types/thread.rs
+++ b/crates/ironclaw_engine/src/types/thread.rs
@@ -12,6 +12,7 @@ use uuid::Uuid;
 use crate::types::capability::LeaseId;
 use crate::types::error::EngineError;
 use crate::types::event::{EventKind, ThreadEvent};
+use crate::types::memory::DocId;
 use crate::types::message::ThreadMessage;
 use crate::types::project::ProjectId;
 
@@ -166,6 +167,20 @@ impl Default for ThreadConfig {
     }
 }
 
+/// Provenance for a skill that was active during thread execution.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ActiveSkillProvenance {
+    pub doc_id: DocId,
+    pub name: String,
+    pub version: u32,
+    #[serde(default)]
+    pub snippet_names: Vec<String>,
+    #[serde(default)]
+    pub force_activated: bool,
+}
+
+const ACTIVE_SKILLS_METADATA_KEY: &str = "active_skills";
+
 // ── Thread ──────────────────────────────────────────────────
 
 /// A thread — the unit of work.
@@ -246,6 +261,36 @@ impl Thread {
         self.owner_id().matches_user(user_id)
     }
 
+    /// Persist active skill provenance in thread metadata.
+    pub fn set_active_skills(
+        &mut self,
+        active_skills: &[ActiveSkillProvenance],
+    ) -> Result<(), EngineError> {
+        let metadata = self
+            .metadata
+            .as_object_mut()
+            .ok_or_else(|| EngineError::Store {
+                reason: "thread metadata is not a JSON object".into(),
+            })?;
+        metadata.insert(
+            ACTIVE_SKILLS_METADATA_KEY.into(),
+            serde_json::to_value(active_skills).map_err(|e| EngineError::Store {
+                reason: format!("failed to serialize active skill provenance: {e}"),
+            })?,
+        );
+        self.updated_at = Utc::now();
+        Ok(())
+    }
+
+    /// Load active skill provenance from thread metadata.
+    pub fn active_skills(&self) -> Vec<ActiveSkillProvenance> {
+        self.metadata
+            .get(ACTIVE_SKILLS_METADATA_KEY)
+            .cloned()
+            .and_then(|value| serde_json::from_value(value).ok())
+            .unwrap_or_default()
+    }
+
     /// Transition to a new state, recording an event.
     pub fn transition_to(
         &mut self,
@@ -310,6 +355,7 @@ impl Thread {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::types::memory::DocId;
 
     fn make_thread() -> Thread {
         Thread::new(
@@ -463,4 +509,20 @@ mod tests {
         .with_parent(parent.id);
         assert_eq!(child.parent_id, Some(parent.id));
     }
+
+    #[test]
+    fn active_skill_provenance_roundtrips_through_metadata() {
+        let mut thread = make_thread();
+        let skills = vec![ActiveSkillProvenance {
+            doc_id: DocId::new(),
+            name: "github-pr-workflow".to_string(),
+            version: 3,
+            snippet_names: vec!["list_prs".to_string()],
+            force_activated: true,
+        }];
+
+        thread.set_active_skills(&skills).unwrap();
+
+        assert_eq!(thread.active_skills(), skills);
+    }
 }
diff --git a/crates/ironclaw_skills/src/catalog.rs b/crates/ironclaw_skills/src/catalog.rs
index bd23b4ebdd4..105a4e8fc3e 100644
--- a/crates/ironclaw_skills/src/catalog.rs
+++ b/crates/ironclaw_skills/src/catalog.rs
@@ -13,6 +13,8 @@ use std::time::{Duration, Instant};
 use serde::{Deserialize, Serialize};
 use tokio::sync::RwLock;
 
+use crate::validation::normalize_skill_identifier;
+
 /// Default ClawHub registry URL.
 ///
 /// Points directly at the Convex backend, bypassing Vercel's edge which
@@ -70,6 +72,88 @@ pub struct CatalogEntry {
     pub owner: Option<String>,
 }
 
+/// Error when a human-readable catalog name cannot be resolved safely.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum CatalogResolveError {
+    #[error("Skill name '{name}' matches multiple catalog entries; use a slug instead ({matches})")]
+    AmbiguousName { name: String, matches: String },
+}
+
+fn normalize_catalog_identity(value: &str) -> String {
+    value
+        .chars()
+        .filter(|c| c.is_ascii_alphanumeric())
+        .map(|c| c.to_ascii_lowercase())
+        .collect()
+}
+
+fn slug_suffix(slug: &str) -> &str {
+    slug.rsplit('/').next().unwrap_or(slug)
+}
+
+/// Resolve a display name or suffix-like query to a unique catalog slug.
+pub fn resolve_catalog_slug_for_name(
+    name: &str,
+    entries: &[CatalogEntry],
+) -> Result<Option<String>, CatalogResolveError> {
+    let normalized_name = normalize_catalog_identity(name);
+    if normalized_name.is_empty() {
+        return Ok(None);
+    }
+
+    let collect_matches = |predicate: &dyn Fn(&CatalogEntry) -> bool| -> Vec<String> {
+        let mut matches: Vec<String> = entries
+            .iter()
+            .filter(|entry| predicate(entry))
+            .map(|entry| entry.slug.clone())
+            .collect();
+
+        matches.sort();
+        matches.dedup();
+        matches
+    };
+
+    let exact_name = name.to_ascii_lowercase();
+    let matches = collect_matches(&|entry| entry.name.to_ascii_lowercase() == exact_name);
+    if matches.len() == 1 {
+        return Ok(matches.into_iter().next());
+    }
+    if matches.len() > 1 {
+        return Err(CatalogResolveError::AmbiguousName {
+            name: name.to_string(),
+            matches: matches.join(", "),
+        });
+    }
+
+    let matches = collect_matches(&|entry| {
+        normalize_catalog_identity(&entry.name) == normalized_name
+            || normalize_catalog_identity(slug_suffix(&entry.slug)) == normalized_name
+    });
+
+    match matches.len() {
+        0 => Ok(None),
+        1 => Ok(matches.into_iter().next()),
+        _ => Err(CatalogResolveError::AmbiguousName {
+            name: name.to_string(),
+            matches: matches.join(", "),
+        }),
+    }
+}
+
+/// Whether a catalog entry should be marked as installed for a set of local names.
+pub fn catalog_entry_is_installed(slug: &str, name: &str, installed_names: &[String]) -> bool {
+    let normalized_slug_name = normalize_skill_identifier(slug);
+    let slug_suffix = slug_suffix(slug);
+    installed_names.iter().any(|installed| {
+        slug.eq_ignore_ascii_case(installed)
+            || slug_suffix.eq_ignore_ascii_case(installed)
+            || name.eq_ignore_ascii_case(installed)
+            || normalized_slug_name
+                .as_deref()
+                .is_some_and(|n| n.eq_ignore_ascii_case(installed))
+    })
+}
+
 /// Top-level wrapper from the ClawHub `/api/v1/skills/{slug}` response.
 ///
 /// The API returns `{"skill": {...}, "owner": {...}, "latestVersion": {...}}`.
@@ -521,6 +605,122 @@ mod tests {
         assert!(url.contains("slug=foo%26bar%3Dbaz%23frag"));
     }
 
+    #[test]
+    fn test_resolve_catalog_slug_for_name_unique_match() {
+        let entries = vec![CatalogEntry {
+            slug: "finance/mortgage-calculator".to_string(),
+            name: "Mortgage Calculator".to_string(),
+            description: String::new(),
+            version: String::new(),
+            score: 1.0,
+            updated_at: None,
+            stars: None,
+            downloads: None,
+            installs_current: None,
+            owner: None,
+        }];
+
+        assert_eq!(
+            resolve_catalog_slug_for_name("Mortgage Calculator", &entries).unwrap(),
+            Some("finance/mortgage-calculator".to_string())
+        );
+        assert_eq!(
+            resolve_catalog_slug_for_name("mortgage-calculator", &entries).unwrap(),
+            Some("finance/mortgage-calculator".to_string())
+        );
+    }
+
+    #[test]
+    fn test_resolve_catalog_slug_for_name_ambiguous() {
+        let entries = vec![
+            CatalogEntry {
+                slug: "alice/mortgage-calculator".to_string(),
+                name: "Mortgage Calculator".to_string(),
+                description: String::new(),
+                version: String::new(),
+                score: 1.0,
+                updated_at: None,
+                stars: None,
+                downloads: None,
+                installs_current: None,
+                owner: None,
+            },
+            CatalogEntry {
+                slug: "bob/mortgage-calculator".to_string(),
+                name: "Mortgage Calculator".to_string(),
+                description: String::new(),
+                version: String::new(),
+                score: 0.9,
+                updated_at: None,
+                stars: None,
+                downloads: None,
+                installs_current: None,
+                owner: None,
+            },
+        ];
+
+        let err = resolve_catalog_slug_for_name("Mortgage Calculator", &entries).unwrap_err();
+        assert!(matches!(err, CatalogResolveError::AmbiguousName { .. }));
+        assert!(err.to_string().contains("use a slug instead"));
+    }
+
+    #[test]
+    fn test_resolve_catalog_slug_for_name_prefers_exact_display_name() {
+        let entries = vec![
+            CatalogEntry {
+                slug: "alice/ab".to_string(),
+                name: "AB".to_string(),
+                description: String::new(),
+                version: String::new(),
+                score: 1.0,
+                updated_at: None,
+                stars: None,
+                downloads: None,
+                installs_current: None,
+                owner: None,
+            },
+            CatalogEntry {
+                slug: "bob/a-b".to_string(),
+                name: "A-B".to_string(),
+                description: String::new(),
+                version: String::new(),
+                score: 0.9,
+                updated_at: None,
+                stars: None,
+                downloads: None,
+                installs_current: None,
+                owner: None,
+            },
+        ];
+
+        assert_eq!(
+            resolve_catalog_slug_for_name("AB", &entries).unwrap(),
+            Some("alice/ab".to_string())
+        );
+    }
+
+    #[test]
+    fn test_catalog_entry_is_installed_matches_normalized_slug_name() {
+        let installed = vec!["finance-mortgage-calculator".to_string()];
+
+        assert!(catalog_entry_is_installed(
+            "finance/mortgage-calculator",
+            "Mortgage Calculator",
+            &installed,
+        ));
+    }
+
+    #[test]
+    fn test_catalog_entry_is_installed_does_not_match_partial_suffix() {
+        let installed = vec!["calculator".to_string()];
+
+        assert!(!catalog_entry_is_installed(
+            "alice/mortgage-calculator",
+            "Mortgage Calculator",
+            &installed,
+        ));
+    }
+
     #[test]
     fn test_parse_wrapped_response() {
         // ClawHub returns {"results": [...]} format
diff --git a/crates/ironclaw_skills/src/lib.rs b/crates/ironclaw_skills/src/lib.rs
index 7c0045ab928..60e7524376d 100644
--- a/crates/ironclaw_skills/src/lib.rs
+++ b/crates/ironclaw_skills/src/lib.rs
@@ -64,6 +64,9 @@ pub use validation::{
 };
 
 #[cfg(feature = "catalog")]
-pub use catalog::{CatalogEntry, CatalogSearchOutcome, SkillCatalog, shared_catalog};
+pub use catalog::{
+    CatalogEntry, CatalogResolveError, CatalogSearchOutcome, SkillCatalog,
+    catalog_entry_is_installed, resolve_catalog_slug_for_name, shared_catalog,
+};
 #[cfg(feature = "registry")]
 pub use registry::{SkillRegistry, SkillRegistryError, compute_hash};
diff --git a/crates/ironclaw_skills/src/parser.rs b/crates/ironclaw_skills/src/parser.rs
index d66c79911e2..5a414ed759b 100644
--- a/crates/ironclaw_skills/src/parser.rs
+++ b/crates/ironclaw_skills/src/parser.rs
@@ -45,6 +45,62 @@ pub struct ParsedSkill {
 /// You are a helpful assistant that...
 /// ```
 pub fn parse_skill_md(content: &str) -> Result<ParsedSkill, SkillParseError> {
+    parse_skill_md_impl(content, true)
+}
+
+/// Parse a SKILL.md file for install recovery without validating the `name` field.
+///
+/// Used by install paths that need to recover from invalid published names by
+/// rewriting them to a safe internal identifier before persisting to disk.
+///
+/// This is intentionally crate-private and should remain limited to the
+/// install-recovery path. Normal discovery/loading must keep using
+/// [`parse_skill_md`] so invalid names are rejected.
+pub(crate) fn parse_skill_md_for_install_recovery(
+    content: &str,
+) -> Result<ParsedSkill, SkillParseError> {
+    parse_skill_md_impl(content, false)
+}
+
+/// Split a SKILL.md file into its raw YAML frontmatter and prompt body without
+/// deserializing into a typed [`SkillManifest`].
+///
+/// Used by install recovery to mutate a single field (`name`) while preserving
+/// any unknown YAML keys that the typed `SkillManifest` would otherwise drop.
+pub(crate) fn split_skill_md_frontmatter(
+    content: &str,
+) -> Result<(String, String), SkillParseError> {
+    let normalized = content.replace("\r\n", "\n").replace('\r', "\n");
+    let stripped = normalized.strip_prefix('\u{feff}').unwrap_or(&normalized);
+
+    let trimmed = stripped.trim_start_matches(['\n', '\r']);
+    if !trimmed.starts_with("---") {
+        return Err(SkillParseError::MissingFrontmatter);
+    }
+
+    let after_first = &trimmed[3..];
+    let after_first_line = match after_first.find('\n') {
+        Some(pos) => &after_first[pos + 1..],
+        None => return Err(SkillParseError::MissingFrontmatter),
+    };
+
+    let yaml_end =
+        find_closing_delimiter(after_first_line).ok_or(SkillParseError::MissingFrontmatter)?;
+    let yaml_str = after_first_line[..yaml_end].to_string();
+
+    let after_yaml = &after_first_line[yaml_end..];
+    let prompt_start = after_yaml
+        .find('\n')
+        .map(|p| p + 1)
+        .unwrap_or(after_yaml.len());
+    let prompt_content = after_yaml[prompt_start..]
+        .trim_start_matches('\n')
+        .to_string();
+
+    Ok((yaml_str, prompt_content))
+}
+
+fn parse_skill_md_impl(content: &str, validate_name: bool) -> Result<ParsedSkill, SkillParseError> {
     // Normalize line endings before parsing to handle CRLF (callers may not
     // have pre-normalized). This also makes `find_closing_delimiter`'s byte
     // offset arithmetic correct since it assumes single-byte `\n` separators.
@@ -78,7 +134,7 @@ pub fn parse_skill_md(content: &str) -> Result<ParsedSkill, SkillParseError> {
         serde_yml::from_str(yaml_str).map_err(|e| SkillParseError::InvalidYaml(e.to_string()))?;
 
     // Validate skill name
-    if !validate_skill_name(&manifest.name) {
+    if validate_name && !validate_skill_name(&manifest.name) {
         return Err(SkillParseError::InvalidName {
             name: manifest.name.clone(),
         });
diff --git a/crates/ironclaw_skills/src/registry.rs b/crates/ironclaw_skills/src/registry.rs
index e7bf47dbede..8da62771a89 100644
--- a/crates/ironclaw_skills/src/registry.rs
+++ b/crates/ironclaw_skills/src/registry.rs
@@ -19,11 +19,14 @@ use std::path::{Path, PathBuf};
 use sha2::{Digest, Sha256};
 
 use crate::gating;
-use crate::parser::{SkillParseError, parse_skill_md};
+use crate::parser::{
+    SkillParseError, parse_skill_md, parse_skill_md_for_install_recovery,
+    split_skill_md_frontmatter,
+};
 use crate::types::{
     GatingRequirements, LoadedSkill, MAX_PROMPT_FILE_SIZE, SkillSource, SkillTrust,
 };
-use crate::validation::normalize_line_endings;
+use crate::validation::{normalize_line_endings, normalize_skill_identifier};
 
 /// Maximum total number of skills that can be discovered across all sources.
 /// Shared across workspace, user, and installed directories.
@@ -37,6 +40,111 @@ fn to_lowercase_vec(items: &[String]) -> Vec<String> {
     items.iter().map(|s| s.to_lowercase()).collect()
 }
 
+fn parse_error_for_install(error_label: &str, error: SkillParseError) -> SkillRegistryError {
+    let reason = error.to_string();
+    match error {
+        SkillParseError::InvalidName { name } => SkillRegistryError::ParseError { name, reason },
+        _ => SkillRegistryError::ParseError {
+            name: error_label.to_string(),
+            reason,
+        },
+    }
+}
+
+/// Rewrite the `name` field in raw YAML frontmatter while preserving every
+/// other key and value in the original mapping.
+///
+/// We deliberately operate on `serde_yml::Value` instead of the typed
+/// `SkillManifest`: re-serializing through the typed struct silently drops
+/// any unknown frontmatter fields published upstream (custom metadata, future
+/// fields, vendor extensions). The recovery path must be lossless except for
+/// the single field we are rewriting.
+fn rewrite_frontmatter_name(
+    frontmatter: &str,
+    new_name: &str,
+    error_label: &str,
+) -> Result<String, SkillRegistryError> {
+    let mut value: serde_yml::Value =
+        serde_yml::from_str(frontmatter).map_err(|e| SkillRegistryError::ParseError {
+            name: error_label.to_string(),
+            reason: format!("Failed to parse SKILL.md frontmatter for rewrite: {}", e),
+        })?;
+
+    let mapping = value
+        .as_mapping_mut()
+        .ok_or_else(|| SkillRegistryError::ParseError {
+            name: error_label.to_string(),
+            reason: "SKILL.md frontmatter is not a YAML mapping".to_string(),
+        })?;
+
+    mapping.insert(
+        serde_yml::Value::String("name".to_string()),
+        serde_yml::Value::String(new_name.to_string()),
+    );
+
+    let yaml = serde_yml::to_string(&value).map_err(|e| SkillRegistryError::ParseError {
+        name: error_label.to_string(),
+        reason: format!("Failed to rewrite normalized SKILL.md: {}", e),
+    })?;
+
+    let yaml = yaml.strip_suffix("...\n").unwrap_or(&yaml);
+    let yaml = yaml.strip_suffix("...").unwrap_or(yaml);
+    Ok(yaml.to_string())
+}
+
+fn assemble_skill_md(yaml: &str, prompt_content: &str) -> String {
+    let mut rendered = String::from("---\n");
+    rendered.push_str(yaml);
+    if !rendered.ends_with('\n') {
+        rendered.push('\n');
+    }
+    rendered.push_str("---\n\n");
+    rendered.push_str(prompt_content);
+    rendered
+}
+
+fn normalize_install_content(
+    normalized_content: &str,
+    requested_identifier: Option<&str>,
+) -> Result<(String, String), SkillRegistryError> {
+    match parse_skill_md(normalized_content) {
+        Ok(parsed) => Ok((parsed.manifest.name, normalized_content.to_string())),
+        Err(SkillParseError::InvalidName { .. }) => {
+            // Re-parse the typed manifest only to recover the original name and
+            // confirm structural validity; the actual rewrite operates on raw
+            // YAML below to preserve any unknown frontmatter fields.
+            let parsed = parse_skill_md_for_install_recovery(normalized_content)
+                .map_err(|e| parse_error_for_install("(install)", e))?;
+            let original_name = parsed.manifest.name.clone();
+            let normalized_name = requested_identifier
+                .and_then(normalize_skill_identifier)
+                .or_else(|| normalize_skill_identifier(&original_name))
+                .ok_or_else(|| SkillRegistryError::ParseError {
+                    name: original_name.clone(),
+                    reason: format!(
+                        "Invalid skill name '{}' could not be normalized to a safe install name",
+                        original_name
+                    ),
+                })?;
+
+            tracing::debug!(
+                original_name = %original_name,
+                normalized_name = %normalized_name,
+                requested_identifier = requested_identifier.unwrap_or(""),
+                "Normalizing invalid skill name during install"
+            );
+
+            let (frontmatter, prompt_content) = split_skill_md_frontmatter(normalized_content)
+                .map_err(|e| parse_error_for_install("(install)", e))?;
+            let rewritten_yaml =
+                rewrite_frontmatter_name(&frontmatter, &normalized_name, &original_name)?;
+            let rendered = assemble_skill_md(&rewritten_yaml, &prompt_content);
+            Ok((normalized_name, rendered))
+        }
+        Err(e) => Err(parse_error_for_install("(install)", e)),
+    }
+}
+
 /// Error type for skill registry operations.
 #[derive(Debug, thiserror::Error)]
 pub enum SkillRegistryError {
@@ -426,6 +534,18 @@ impl SkillRegistry {
         self.skills.iter().find(|s| s.manifest.name == name)
     }
 
+    /// Resolve the on-disk install content and final in-memory skill name.
+    ///
+    /// Install flows use this to recover from invalid published names (for
+    /// example, catalog display names containing spaces) without relaxing the
+    /// parser for ordinary local skill discovery.
+    pub fn resolve_install_content(
+        normalized_content: &str,
+        requested_identifier: Option<&str>,
+    ) -> Result<(String, String), SkillRegistryError> {
+        normalize_install_content(normalized_content, requested_identifier)
+    }
+
     /// Perform the disk I/O and loading for a skill install.
     ///
     /// This is a static method so it doesn't borrow `&self`, allowing callers
@@ -484,23 +604,15 @@ impl SkillRegistry {
     /// hold time.
     pub async fn install_skill(&mut self, content: &str) -> Result<String, SkillRegistryError> {
         let normalized = normalize_line_endings(content);
-        let parsed = parse_skill_md(&normalized).map_err(|e: SkillParseError| match e {
-            SkillParseError::InvalidName { ref name } => SkillRegistryError::ParseError {
-                name: name.clone(),
-                reason: e.to_string(),
-            },
-            _ => SkillRegistryError::ParseError {
-                name: "(install)".to_string(),
-                reason: e.to_string(),
-            },
-        })?;
-        let skill_name = parsed.manifest.name.clone();
+        let (skill_name, install_content) = normalize_install_content(&normalized, None)?;
         if self.has(&skill_name) {
-            return Err(SkillRegistryError::AlreadyExists { name: skill_name });
+            return Err(SkillRegistryError::AlreadyExists {
+                name: skill_name.clone(),
+            });
         }
         let user_dir = self.user_dir.clone();
         let (name, skill) =
-            Self::prepare_install_to_disk(&user_dir, &skill_name, &normalized).await?;
+            Self::prepare_install_to_disk(&user_dir, &skill_name, &install_content).await?;
         self.commit_install(&name, skill)?;
         Ok(name)
     }
@@ -978,6 +1090,89 @@ mod tests {
         assert!(skill_path.exists());
     }
 
+    #[test]
+    fn test_resolve_install_content_prefers_requested_slug_for_invalid_name() {
+        let content = "---\nname: Mortgage Calculator\ndescription: Installed skill\n---\n\nInstalled prompt.\n";
+
+        let (name, rewritten) =
+            SkillRegistry::resolve_install_content(content, Some("finance/mortgage-calculator"))
+                .unwrap();
+
+        assert_eq!(name, "finance-mortgage-calculator");
+        assert!(rewritten.contains("name: finance-mortgage-calculator"));
+        assert!(rewritten.contains("Installed prompt."));
+    }
+
+    #[test]
+    fn test_resolve_install_content_slugifies_invalid_name_without_slug() {
+        let content = "---\nname: Mortgage Calculator\n---\n\nPrompt.\n";
+
+        let (name, rewritten) = SkillRegistry::resolve_install_content(content, None).unwrap();
+
+        assert_eq!(name, "mortgage-calculator");
+        assert!(rewritten.contains("name: mortgage-calculator"));
+    }
+
+    #[tokio::test]
+    async fn test_install_skill_normalizes_invalid_name() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut registry = SkillRegistry::new(dir.path().to_path_buf());
+
+        let content = "---\nname: Mortgage Calculator\ndescription: Installed skill\n---\n\nInstalled prompt.\n";
+        let name = registry.install_skill(content).await.unwrap();
+
+        assert_eq!(name, "mortgage-calculator");
+        assert!(registry.has("mortgage-calculator"));
+
+        let skill_path = dir.path().join("mortgage-calculator").join("SKILL.md");
+        assert!(skill_path.exists());
+
+        let written = fs::read_to_string(skill_path).unwrap();
+        assert!(written.contains("name: mortgage-calculator"));
+    }
+
+    #[test]
+    fn test_resolve_install_content_preserves_unknown_frontmatter_fields() {
+        // Published manifests may carry custom keys (vendor extensions, future
+        // fields) that the typed `SkillManifest` does not know about. Recovery
+        // must rewrite only `name` without dropping unknown keys.
+        let content = "---\nname: Mortgage Calculator\ndescription: Computes payments\nx-publisher: acme\ncustom_meta:\n  rating: 5\n  tags:\n    - finance\n    - calculator\n---\n\nInstalled prompt.\n";
+
+        let (name, rewritten) = SkillRegistry::resolve_install_content(content, None).unwrap();
+
+        assert_eq!(name, "mortgage-calculator");
+        assert!(rewritten.contains("name: mortgage-calculator"));
+        assert!(
+            rewritten.contains("x-publisher: acme"),
+            "unknown top-level key was dropped: {rewritten}"
+        );
+        assert!(
+            rewritten.contains("custom_meta:"),
+            "unknown nested mapping was dropped: {rewritten}"
+        );
+        assert!(
+            rewritten.contains("rating: 5"),
+            "nested scalar was dropped: {rewritten}"
+        );
+        assert!(
+            rewritten.contains("- finance") && rewritten.contains("- calculator"),
+            "nested sequence was dropped: {rewritten}"
+        );
+        assert!(rewritten.contains("Installed prompt."));
+    }
+
+    #[test]
+    fn test_resolve_install_content_preserves_owner_for_invalid_slug_name() {
+        let content = "---\nname: Mortgage Calculator\n---\n\nPrompt.\n";
+
+        let (name, rewritten) =
+            SkillRegistry::resolve_install_content(content, Some("alice/mortgage-calculator"))
+                .unwrap();
+
+        assert_eq!(name, "alice-mortgage-calculator");
+        assert!(rewritten.contains("name: alice-mortgage-calculator"));
+    }
+
     #[tokio::test]
     async fn test_install_duplicate_rejected() {
         let dir = tempfile::tempdir().unwrap();
diff --git a/crates/ironclaw_skills/src/v2.rs b/crates/ironclaw_skills/src/v2.rs
index c993fda572a..528ce94270a 100644
--- a/crates/ironclaw_skills/src/v2.rs
+++ b/crates/ironclaw_skills/src/v2.rs
@@ -70,6 +70,64 @@ impl SkillMetrics {
     }
 }
 
+/// Structured repair categories for versioned skill updates.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SkillRepairType {
+    MissingPrerequisite,
+    WrongOrdering,
+    StaleCommandPath,
+    MissingBranch,
+    MissingPitfall,
+    MissingVerification,
+}
+
+/// Archived pre-update skill state used for content-aware rollback.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SkillRevision {
+    /// Version number represented by this archived snapshot.
+    pub version: u32,
+    /// Prompt content for that version.
+    pub content: String,
+    /// Description at that version.
+    #[serde(default)]
+    pub description: String,
+    /// Activation criteria at that version.
+    #[serde(default)]
+    pub activation: ActivationCriteria,
+    /// Code snippets at that version.
+    #[serde(default)]
+    pub code_snippets: Vec<CodeSnippet>,
+    /// Content hash at that version.
+    #[serde(default)]
+    pub content_hash: String,
+    /// When this snapshot was archived.
+    #[serde(default)]
+    pub archived_at: Option<DateTime<Utc>>,
+}
+
+/// Metadata describing a repair that updated this skill.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SkillRepairRecord {
+    /// Source thread that exposed the gap, if known.
+    #[serde(default)]
+    pub source_thread_id: Option<String>,
+    /// Version before the repair.
+    #[serde(default)]
+    pub from_version: u32,
+    /// Version after the repair.
+    #[serde(default)]
+    pub to_version: u32,
+    /// Type of gap that was repaired.
+    pub repair_type: SkillRepairType,
+    /// Short human-readable summary of the fix.
+    #[serde(default)]
+    pub summary: String,
+    /// When the repair was applied.
+    #[serde(default)]
+    pub repaired_at: Option<DateTime<Utc>>,
+}
+
 /// Full metadata for a v2 skill.
 ///
 /// Serialized to/from the `metadata` JSON field of a `MemoryDoc` with
@@ -104,6 +162,12 @@ pub struct V2SkillMetadata {
     /// Previous version number (for rollback).
     #[serde(default)]
     pub parent_version: Option<u32>,
+    /// Archived revisions used for content-aware rollback.
+    #[serde(default)]
+    pub revisions: Vec<SkillRevision>,
+    /// Repair history for this skill.
+    #[serde(default)]
+    pub repairs: Vec<SkillRepairRecord>,
     /// SHA-256 hash of the prompt content.
     #[serde(default)]
     pub content_hash: String,
@@ -181,6 +245,23 @@ mod tests {
                 last_used: None,
             },
             parent_version: Some(2),
+            revisions: vec![SkillRevision {
+                version: 2,
+                content: "previous content".to_string(),
+                description: "old".to_string(),
+                activation: ActivationCriteria::default(),
+                code_snippets: vec![],
+                content_hash: "sha256:def".to_string(),
+                archived_at: None,
+            }],
+            repairs: vec![SkillRepairRecord {
+                source_thread_id: Some("thread-123".to_string()),
+                from_version: 2,
+                to_version: 3,
+                repair_type: SkillRepairType::MissingVerification,
+                summary: "added smoke test step".to_string(),
+                repaired_at: None,
+            }],
             content_hash: "sha256:abc".to_string(),
         };
 
@@ -193,6 +274,8 @@ mod tests {
         assert_eq!(parsed.code_snippets.len(), 1);
         assert_eq!(parsed.metrics.success_count, 4);
         assert_eq!(parsed.parent_version, Some(2));
+        assert_eq!(parsed.revisions.len(), 1);
+        assert_eq!(parsed.repairs.len(), 1);
     }
 
     #[test]
@@ -205,5 +288,7 @@ mod tests {
         assert_eq!(parsed.trust, SkillTrust::Installed);
         assert!(parsed.code_snippets.is_empty());
         assert!((parsed.metrics.confidence() - 1.0).abs() < f64::EPSILON);
+        assert!(parsed.revisions.is_empty());
+        assert!(parsed.repairs.is_empty());
     }
 }
diff --git a/crates/ironclaw_skills/src/validation.rs b/crates/ironclaw_skills/src/validation.rs
index 0140d7fdbd0..7ecc6936de4 100644
--- a/crates/ironclaw_skills/src/validation.rs
+++ b/crates/ironclaw_skills/src/validation.rs
@@ -13,6 +13,62 @@ pub fn validate_skill_name(name: &str) -> bool {
     SKILL_NAME_PATTERN.is_match(name)
 }
 
+/// Normalize an external identifier into a safe skill name when possible.
+///
+/// This is used for recovery paths where a published identifier or display name
+/// needs to be turned into a valid on-disk/internal skill name. Valid names are
+/// preserved; invalid identifiers are lowercased and non-alphanumeric runs are
+/// collapsed into `-`, `_`, or `.` separators as allowed by the skill-name
+/// grammar.
+///
+/// Non-ASCII characters (accented letters, CJK, emoji) are treated as separators
+/// and effectively dropped: e.g. `"café"` becomes `"caf"`, `"中文-skill"` becomes
+/// `"skill"`. Identifiers that normalize to an empty or otherwise invalid name
+/// return `None`.
+pub fn normalize_skill_identifier(value: &str) -> Option<String> {
+    let trimmed = value.trim();
+    if validate_skill_name(trimmed) {
+        return Some(trimmed.to_string());
+    }
+
+    let mut sanitized = String::with_capacity(trimmed.len().min(64));
+    let mut last_was_separator = false;
+
+    for ch in trimmed.chars() {
+        if ch.is_ascii_alphanumeric() {
+            sanitized.push(ch.to_ascii_lowercase());
+            last_was_separator = false;
+            continue;
+        }
+
+        if matches!(ch, '.' | '_' | '-') {
+            if !sanitized.is_empty() && !last_was_separator {
+                sanitized.push(ch);
+                last_was_separator = true;
+            }
+            continue;
+        }
+
+        if !sanitized.is_empty() && !last_was_separator {
+            sanitized.push('-');
+            last_was_separator = true;
+        }
+    }
+
+    while sanitized.ends_with(['-', '_', '.']) {
+        sanitized.pop();
+    }
+
+    if sanitized.len() > 64 {
+        sanitized.truncate(64);
+        while sanitized.ends_with(['-', '_', '.']) {
+            sanitized.pop();
+        }
+    }
+
+    validate_skill_name(&sanitized).then_some(sanitized)
+}
+
 /// Escape a string for safe inclusion in XML attributes.
 /// Prevents attribute injection attacks via skill name/version fields.
 pub fn escape_xml_attr(s: &str) -> String {
@@ -162,6 +218,23 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn test_normalize_skill_identifier() {
+        assert_eq!(
+            normalize_skill_identifier("finance/mortgage-calculator").as_deref(),
+            Some("finance-mortgage-calculator")
+        );
+        assert_eq!(
+            normalize_skill_identifier("Mortgage Calculator").as_deref(),
+            Some("mortgage-calculator")
+        );
+        assert_eq!(
+            normalize_skill_identifier("already-valid_name").as_deref(),
+            Some("already-valid_name")
+        );
+        assert_eq!(normalize_skill_identifier("!!!"), None);
+    }
+
     #[test]
     fn test_escape_xml_attr() {
         assert_eq!(escape_xml_attr("normal"), "normal");
diff --git a/crates/ironclaw_tui/CLAUDE.md b/crates/ironclaw_tui/CLAUDE.md
new file mode 100644
index 00000000000..57caaba5f26
--- /dev/null
+++ b/crates/ironclaw_tui/CLAUDE.md
@@ -0,0 +1,41 @@
+# ironclaw_tui — Module Spec
+
+## Overview
+
+Ratatui-based terminal UI for IronClaw. Self-contained crate that provides:
+- Widget system (`TuiWidget` trait) with built-in widgets (header, conversation, input, status bar, tool panel, thread list, approval modal)
+- Layout engine with user-configurable JSON (`tui/layout.json` in workspace)
+- Theme system (dark/light, custom colors)
+- Event loop with crossterm input polling + external event merging
+
+## Dependencies
+
+- No dependency on the main `ironclaw` crate (avoids circular dependency)
+- Channel trait bridge lives in `src/channels/tui.rs` in the main crate
+
+## Communication
+
+```
+Main Crate (TuiChannel)          ironclaw_tui (TuiApp)
+─────────────────────             ───────────────────
+event_tx: Sender<TuiEvent> ────→ event_rx: renders UI
+msg_rx: Receiver<String>  ←──── msg_tx: user input
+```
+
+## Key Bindings
+
+| Key      | Action               |
+|----------|----------------------|
+| Enter    | Submit input         |
+| Ctrl-C   | Quit                 |
+| Ctrl-B   | Toggle sidebar       |
+| Esc      | Interrupt/cancel     |
+| PgUp/Dn  | Scroll conversation  |
+| y/n/a    | Approval shortcuts   |
+
+## Adding a Widget
+
+1. Create `src/widgets/my_widget.rs`
+2. Implement `TuiWidget` trait
+3. Add to `BuiltinWidgets` in `registry.rs`
+4. Wire into `render_frame()` in `app.rs`
diff --git a/crates/ironclaw_tui/Cargo.toml b/crates/ironclaw_tui/Cargo.toml
new file mode 100644
index 00000000000..11d3e7b6211
--- /dev/null
+++ b/crates/ironclaw_tui/Cargo.toml
@@ -0,0 +1,30 @@
+[package]
+name = "ironclaw_tui"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.92"
+description = "Modular Ratatui-based TUI for IronClaw"
+authors = ["NEAR AI <support@near.ai>"]
+license = "MIT OR Apache-2.0"
+homepage = "https://github.com/nearai/ironclaw"
+repository = "https://github.com/nearai/ironclaw"
+
+[package.metadata.dist]
+dist = false
+
+[dependencies]
+ratatui = { version = "0.29", features = ["crossterm"] }
+tui-textarea = { version = "0.7", features = ["crossterm"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["sync", "macros", "rt", "time"] }
+chrono = "0.4"
+unicode-width = "0.2"
+pulldown-cmark = { version = "0.12", default-features = false }
+thiserror = "2"
+tracing = "0.1"
+arboard = "3"
+image = { version = "0.25", default-features = false, features = ["png"] }
+
+[dev-dependencies]
+tokio = { version = "1", features = ["full"] }
diff --git a/crates/ironclaw_tui/examples/dev.rs b/crates/ironclaw_tui/examples/dev.rs
new file mode 100644
index 00000000000..6002ca2e951
--- /dev/null
+++ b/crates/ironclaw_tui/examples/dev.rs
@@ -0,0 +1,283 @@
+//! Standalone TUI dev harness — renders the full TUI with mock data.
+//!
+//! Usage:
+//!   cargo run -p ironclaw_tui --example dev
+//!
+//! Hot-reload loop (recompiles + restarts on any source change):
+//!   cargo watch -x 'run -p ironclaw_tui --example dev' -w crates/ironclaw_tui/src
+//!
+//! This compiles in ~5s instead of minutes because it skips the entire
+//! ironclaw binary (database, LLM, WASM, Docker, etc.).
+
+use std::time::Duration;
+
+use ironclaw_tui::{SkillCategory, ToolCategory, TuiAppConfig, TuiEvent, TuiLayout, start_tui};
+
+fn mock_tool_categories() -> Vec<ToolCategory> {
+    vec![
+        ToolCategory {
+            name: "browser".into(),
+            tools: vec![
+                "back".into(),
+                "click".into(),
+                "navigate".into(),
+                "screenshot".into(),
+            ],
+        },
+        ToolCategory {
+            name: "file".into(),
+            tools: vec!["read".into(), "write".into(), "search".into()],
+        },
+        ToolCategory {
+            name: "general".into(),
+            tools: vec![
+                "echo".into(),
+                "github".into(),
+                "gmail".into(),
+                "http".into(),
+                "json".into(),
+                "time".into(),
+            ],
+        },
+        ToolCategory {
+            name: "memory".into(),
+            tools: vec![
+                "read".into(),
+                "search".into(),
+                "tree".into(),
+                "write".into(),
+            ],
+        },
+        ToolCategory {
+            name: "routine".into(),
+            tools: vec![
+                "create".into(),
+                "delete".into(),
+                "list".into(),
+                "update".into(),
+            ],
+        },
+        ToolCategory {
+            name: "secret".into(),
+            tools: vec!["delete".into(), "list".into()],
+        },
+        ToolCategory {
+            name: "shell".into(),
+            tools: vec!["exec".into()],
+        },
+        ToolCategory {
+            name: "skill".into(),
+            tools: vec![
+                "install".into(),
+                "list".into(),
+                "remove".into(),
+                "search".into(),
+            ],
+        },
+        ToolCategory {
+            name: "tool".into(),
+            tools: vec![
+                "activate".into(),
+                "auth".into(),
+                "info".into(),
+                "install".into(),
+                "list".into(),
+                "remove".into(),
+                "search".into(),
+                "upgrade".into(),
+            ],
+        },
+        ToolCategory {
+            name: "web".into(),
+            tools: vec!["fetch".into()],
+        },
+    ]
+}
+
+fn mock_skill_categories() -> Vec<SkillCategory> {
+    vec![
+        SkillCategory {
+            name: "apple".into(),
+            skills: vec![
+                "apple-notes".into(),
+                "apple-reminders".into(),
+                "findmy".into(),
+            ],
+        },
+        SkillCategory {
+            name: "creative".into(),
+            skills: vec![
+                "ascii-art".into(),
+                "ascii-video".into(),
+                "excalidraw".into(),
+            ],
+        },
+        SkillCategory {
+            name: "data-science".into(),
+            skills: vec!["jupyter-live-kernel".into()],
+        },
+        SkillCategory {
+            name: "github".into(),
+            skills: vec![
+                "codebase-inspection".into(),
+                "github-auth".into(),
+                "github-code-r...".into(),
+            ],
+        },
+        SkillCategory {
+            name: "media".into(),
+            skills: vec!["gif-search".into(), "heartmula".into(), "songsee".into()],
+        },
+        SkillCategory {
+            name: "productivity".into(),
+            skills: vec![
+                "google-workspace".into(),
+                "linear".into(),
+                "notion".into(),
+                "ocr".into(),
+            ],
+        },
+        SkillCategory {
+            name: "research".into(),
+            skills: vec!["arxiv".into(), "blogwatcher".into(), "domain-intel".into()],
+        },
+        SkillCategory {
+            name: "software-dev".into(),
+            skills: vec!["code-review".into(), "plan".into(), "remote-pr".into()],
+        },
+    ]
+}
+
+fn main() {
+    let config = TuiAppConfig {
+        version: "0.22.0-dev".into(),
+        model: "gpt-5.4".into(),
+        layout: TuiLayout::default(),
+        context_window: 128_000,
+        tools: mock_tool_categories(),
+        skills: mock_skill_categories(),
+        workspace_path: std::env::current_dir()
+            .map(|p| p.display().to_string())
+            .unwrap_or_else(|_| "~/projects/ironclaw".into()),
+        memory_count: 42,
+        identity_files: vec!["AGENTS.md".into(), "SOUL.md".into(), "USER.md".into()],
+        available_models: vec![
+            "gpt-4o".into(),
+            "gpt-5.3-codex".into(),
+            "gpt-5.4".into(),
+            "claude-sonnet-4-6".into(),
+            "gemini-2.5-pro".into(),
+        ],
+    };
+
+    let handle = start_tui(config);
+    let event_tx = handle.event_tx;
+    let mut msg_rx = handle.msg_rx;
+
+    // Spawn a thread that simulates agent responses to user input
+    let sim_tx = event_tx.clone();
+    std::thread::spawn(move || {
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("failed to build tokio runtime"); // safety: example binary, not library code
+
+        rt.block_on(async move {
+            // Simulate initial status events after a short delay
+            tokio::time::sleep(Duration::from_millis(500)).await;
+            let _ = sim_tx
+                .send(TuiEvent::SandboxStatus {
+                    docker_available: true,
+                    running_containers: 0,
+                    status: "ready".into(),
+                })
+                .await;
+            let _ = sim_tx
+                .send(TuiEvent::SecretsStatus {
+                    count: 3,
+                    vault_unlocked: true,
+                })
+                .await;
+
+            // Echo user messages back as mock agent responses
+            while let Some(user_msg) = msg_rx.recv().await {
+                let msg = &user_msg.text;
+                // Simulate thinking
+                let _ = sim_tx
+                    .send(TuiEvent::Thinking("Processing...".into()))
+                    .await;
+                tokio::time::sleep(Duration::from_millis(300)).await;
+
+                // Simulate tool call
+                let truncated: String = msg.chars().take(40).collect();
+                let _ = sim_tx
+                    .send(TuiEvent::ToolStarted {
+                        name: "echo".into(),
+                        detail: Some(format!("\"{truncated}\"")),
+                        call_id: None,
+                    })
+                    .await;
+                tokio::time::sleep(Duration::from_millis(200)).await;
+                let _ = sim_tx
+                    .send(TuiEvent::ToolCompleted {
+                        name: "echo".into(),
+                        success: true,
+                        error: None,
+                        call_id: None,
+                    })
+                    .await;
+                let _ = sim_tx
+                    .send(TuiEvent::ToolResult {
+                        name: "echo".into(),
+                        preview: msg.clone(),
+                        call_id: None,
+                    })
+                    .await;
+
+                // Simulate streaming response
+                let _ = sim_tx.send(TuiEvent::Thinking(String::new())).await;
+                let response = format!(
+                    "You said: **{msg}**\n\nThis is a mock response from the dev harness. \
+                     Edit `crates/ironclaw_tui/src/` and watch it reload.",
+                );
+                for chunk in response.as_bytes().chunks(20) {
+                    let _ = sim_tx
+                        .send(TuiEvent::StreamChunk(
+                            String::from_utf8_lossy(chunk).to_string(),
+                        ))
+                        .await;
+                    tokio::time::sleep(Duration::from_millis(30)).await;
+                }
+                let _ = sim_tx
+                    .send(TuiEvent::Response {
+                        content: response,
+                        thread_id: None,
+                    })
+                    .await;
+
+                // Simulate cost
+                let _ = sim_tx
+                    .send(TuiEvent::TurnCost {
+                        input_tokens: 1200,
+                        output_tokens: 340,
+                        cost_usd: "$0.002".into(),
+                    })
+                    .await;
+
+                // Suggestions
+                let _ = sim_tx
+                    .send(TuiEvent::Suggestions {
+                        suggestions: vec![
+                            "Tell me more".into(),
+                            "Show available tools".into(),
+                            "Search memory".into(),
+                        ],
+                    })
+                    .await;
+            }
+        });
+    });
+
+    // Block main thread until TUI exits
+    handle.join_handle.join().expect("TUI thread panicked"); // safety: example binary, not library code
+}
diff --git a/crates/ironclaw_tui/src/app.rs b/crates/ironclaw_tui/src/app.rs
new file mode 100644
index 00000000000..a71a4b507eb
--- /dev/null
+++ b/crates/ironclaw_tui/src/app.rs
@@ -0,0 +1,3337 @@
+//! TuiApp: main event loop, frame rendering, and input dispatch.
+//!
+//! The TUI runs in a dedicated blocking thread (crossterm needs raw mode
+//! control of stdin). It communicates with the agent via channels:
+//!
+//! - `event_rx`: receives [`TuiEvent`]s (key input, status updates, responses)
+//! - `msg_tx`: sends user messages to the agent loop
+//!
+//! The app owns the terminal, manages alternate screen / raw mode, and
+//! renders frames at ~30fps using a tick timer.
+
+use std::io::{self, Write};
+use std::time::Duration;
+
+use ratatui::Terminal;
+use ratatui::backend::CrosstermBackend;
+use ratatui::crossterm::cursor::Show;
+use ratatui::crossterm::event::{
+    self, DisableBracketedPaste, EnableBracketedPaste, Event as CtEvent, KeyCode, KeyEventKind,
+    KeyModifiers, MouseButton, MouseEvent, MouseEventKind,
+};
+use ratatui::crossterm::execute;
+use ratatui::crossterm::terminal::{
+    EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode,
+};
+use ratatui::layout::{Constraint, Direction, Layout, Rect};
+use tokio::sync::mpsc;
+
+use crate::event::{TuiAttachment, TuiEvent, TuiLogEntry, TuiUserMessage};
+use crate::input::{InputAction, map_key};
+use crate::layout::TuiLayout;
+use crate::widgets::approval::{ApprovalAction, ApprovalWidget};
+use crate::widgets::command_palette::CommandPaletteWidget;
+use crate::widgets::help_overlay::HelpOverlayWidget;
+use crate::widgets::logs::LogsWidget;
+use crate::widgets::model_picker::{ModelPickerState, ModelPickerWidget};
+use crate::widgets::registry::{BuiltinWidgets, create_default_widgets};
+use crate::widgets::thread_list::engine_thread_index_at;
+use crate::widgets::thread_picker::ThreadPickerWidget;
+use crate::widgets::{
+    ActiveTab, AppState, ApprovalRequest, ChatMessage, ContextPressureInfo, CostGuardInfo,
+    EngineThreadInfo, JobInfo, JobStatus, MessageRole, RoutineInfo, SandboxInfo, ScreenSnapshot,
+    SecretsInfo, SelectionPoint, SkillCategory, TextSelection, ThreadStatus, Toast, ToastKind,
+    ToolActivity, ToolCategory, ToolDetailModal, ToolStatus, TuiWidget, TurnCostSummary,
+};
+
+/// Handle returned when the TUI is started. The main crate uses this to
+/// send events and receive user messages.
+pub struct TuiAppHandle {
+    /// Send events (status updates, responses) into the TUI.
+    pub event_tx: mpsc::Sender<TuiEvent>,
+    /// Receive user messages from the TUI input.
+    pub msg_rx: mpsc::Receiver<TuiUserMessage>,
+    /// Join handle for the TUI thread.
+    pub join_handle: std::thread::JoinHandle<()>,
+}
+
+/// Configuration for creating a TuiApp.
+pub struct TuiAppConfig {
+    pub version: String,
+    pub model: String,
+    pub layout: TuiLayout,
+    /// Maximum context window size in tokens (e.g., 128_000, 200_000).
+    pub context_window: u64,
+    /// Tool categories for the welcome screen.
+    pub tools: Vec<ToolCategory>,
+    /// Skill categories for the welcome screen.
+    pub skills: Vec<SkillCategory>,
+    /// Workspace directory path.
+    pub workspace_path: String,
+    /// Number of memory entries in the workspace.
+    pub memory_count: usize,
+    /// Identity files loaded at startup (e.g. "AGENTS.md", "SOUL.md").
+    pub identity_files: Vec<String>,
+    /// Best-effort model list for the `/model` picker.
+    pub available_models: Vec<String>,
+}
+
+/// Start the TUI application. Returns a handle for bi-directional communication.
+///
+/// The TUI runs in a dedicated OS thread because crossterm raw mode requires
+/// exclusive stdin access.
+pub fn start_tui(config: TuiAppConfig) -> TuiAppHandle {
+    let (event_tx, event_rx) = mpsc::channel::<TuiEvent>(256);
+    let (msg_tx, msg_rx) = mpsc::channel::<TuiUserMessage>(32);
+
+    // Clone event_tx for the crossterm polling task
+    let input_event_tx = event_tx.clone();
+
+    let join_handle = std::thread::spawn(move || {
+        // Build a single-threaded tokio runtime for the TUI thread
+        let rt = match tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+        {
+            Ok(rt) => rt,
+            Err(e) => {
+                tracing::error!("Failed to build tokio runtime for TUI: {e}");
+                return;
+            }
+        };
+
+        rt.block_on(async move {
+            if let Err(e) = run_tui(config, event_rx, input_event_tx, msg_tx).await {
+                tracing::error!("TUI error: {}", e);
+            }
+        });
+    });
+
+    TuiAppHandle {
+        event_tx,
+        msg_rx,
+        join_handle,
+    }
+}
+
+/// Internal TUI run loop.
+async fn run_tui(
+    config: TuiAppConfig,
+    mut event_rx: mpsc::Receiver<TuiEvent>,
+    input_event_tx: mpsc::Sender<TuiEvent>,
+    msg_tx: mpsc::Sender<TuiUserMessage>,
+) -> io::Result<()> {
+    // Terminal setup
+    enable_raw_mode()?;
+    let mut restore_guard = TerminalRestoreGuard::new();
+    let mut stdout = io::stdout();
+    execute!(
+        stdout,
+        EnterAlternateScreen,
+        ratatui::crossterm::event::EnableMouseCapture,
+        EnableBracketedPaste
+    )?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+    terminal.clear()?;
+
+    // State
+    let mut state = AppState {
+        version: config.version,
+        model: config.model,
+        sidebar_visible: config.layout.sidebar.visible,
+        context_window: config.context_window,
+        welcome_tools: config.tools,
+        welcome_skills: config.skills,
+        workspace_path: config.workspace_path,
+        memory_count: config.memory_count,
+        identity_files: config.identity_files,
+        model_picker: ModelPickerState::with_models(config.available_models),
+        ..AppState::default()
+    };
+
+    let mut widgets = create_default_widgets(&config.layout);
+    let layout = config.layout;
+
+    // Spawn crossterm input poller
+    let poll_tx = input_event_tx;
+    tokio::spawn(async move {
+        loop {
+            // Poll crossterm events with a short timeout
+            match tokio::task::spawn_blocking(|| {
+                if event::poll(Duration::from_millis(33)).unwrap_or(false) {
+                    event::read().ok()
+                } else {
+                    None
+                }
+            })
+            .await
+            {
+                Ok(Some(CtEvent::Key(key))) => {
+                    if key.kind == KeyEventKind::Press
+                        && poll_tx.send(TuiEvent::Key(key)).await.is_err()
+                    {
+                        break;
+                    }
+                }
+                Ok(Some(CtEvent::Resize(w, h))) => {
+                    if poll_tx.send(TuiEvent::Resize(w, h)).await.is_err() {
+                        break;
+                    }
+                }
+                Ok(Some(CtEvent::Mouse(MouseEvent {
+                    kind: MouseEventKind::ScrollUp,
+                    ..
+                }))) => {
+                    if poll_tx.send(TuiEvent::MouseScroll(-1)).await.is_err() {
+                        break;
+                    }
+                }
+                Ok(Some(CtEvent::Mouse(MouseEvent {
+                    kind: MouseEventKind::ScrollDown,
+                    ..
+                }))) => {
+                    if poll_tx.send(TuiEvent::MouseScroll(1)).await.is_err() {
+                        break;
+                    }
+                }
+                Ok(Some(CtEvent::Mouse(MouseEvent {
+                    kind: MouseEventKind::Down(MouseButton::Left),
+                    column,
+                    row,
+                    ..
+                }))) => {
+                    if poll_tx
+                        .send(TuiEvent::MouseClick { column, row })
+                        .await
+                        .is_err()
+                    {
+                        break;
+                    }
+                }
+                Ok(Some(CtEvent::Mouse(MouseEvent {
+                    kind: MouseEventKind::Drag(MouseButton::Left),
+                    column,
+                    row,
+                    ..
+                }))) => {
+                    if poll_tx
+                        .send(TuiEvent::MouseDrag { column, row })
+                        .await
+                        .is_err()
+                    {
+                        break;
+                    }
+                }
+                Ok(Some(CtEvent::Mouse(MouseEvent {
+                    kind: MouseEventKind::Up(MouseButton::Left),
+                    column,
+                    row,
+                    ..
+                }))) => {
+                    if poll_tx
+                        .send(TuiEvent::MouseRelease { column, row })
+                        .await
+                        .is_err()
+                    {
+                        break;
+                    }
+                }
+                Ok(Some(CtEvent::Paste(text))) => {
+                    if poll_tx.send(TuiEvent::Paste(text)).await.is_err() {
+                        break;
+                    }
+                }
+                Ok(_) => {}
+                Err(_) => break,
+            }
+        }
+    });
+
+    let mut tick_interval = tokio::time::interval(Duration::from_millis(33));
+
+    // Main loop
+    loop {
+        // Render
+        terminal.draw(|frame| {
+            render_frame(frame, &mut state, &widgets, &layout);
+        })?;
+
+        // Wait for event
+        tokio::select! {
+            _ = tick_interval.tick() => {
+                // Tick — just triggers a re-render
+            }
+            event = event_rx.recv() => {
+                let Some(event) = event else {
+                    break; // Channel closed
+                };
+                handle_event(event, &mut state, &mut widgets, &msg_tx, &layout).await;
+            }
+        }
+
+        if state.should_quit {
+            break;
+        }
+    }
+
+    // Teardown
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        DisableBracketedPaste,
+        ratatui::crossterm::event::DisableMouseCapture,
+        LeaveAlternateScreen
+    )?;
+    terminal.show_cursor()?;
+    restore_guard.disarm();
+    Ok(())
+}
+
+/// Count the number of case-insensitive matches of `query` across all messages.
+fn count_search_matches(messages: &[ChatMessage], query: &str) -> usize {
+    if query.is_empty() {
+        return 0;
+    }
+    let query_lower = query.to_lowercase();
+    messages
+        .iter()
+        .map(|m| {
+            let content_lower = m.content.to_lowercase();
+            content_lower.matches(&query_lower).count()
+        })
+        .sum()
+}
+
+fn outgoing_thread_scope(text: &str, current_thread_id: Option<&str>) -> Option<String> {
+    let trimmed = text.trim();
+    if trimmed.eq_ignore_ascii_case("/new")
+        || trimmed.eq_ignore_ascii_case("/clear")
+        || trimmed.eq_ignore_ascii_case("/thread new")
+        || trimmed.to_ascii_lowercase().starts_with("/thread ")
+    {
+        return None;
+    }
+
+    current_thread_id.map(str::to_owned)
+}
+
+fn update_local_thread_scope_after_submit(state: &mut AppState, text: &str) {
+    let trimmed = text.trim();
+    if trimmed.eq_ignore_ascii_case("/new")
+        || trimmed.eq_ignore_ascii_case("/clear")
+        || trimmed.eq_ignore_ascii_case("/thread new")
+    {
+        state.current_thread_id = None;
+    }
+}
+
+fn parse_engine_thread_timestamp(
+    raw: &str,
+    field: &'static str,
+    thread_id: &str,
+) -> Option<chrono::DateTime<chrono::Utc>> {
+    if let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(raw) {
+        return Some(parsed.with_timezone(&chrono::Utc));
+    }
+
+    if let Ok(parsed) = chrono::NaiveDateTime::parse_from_str(raw, "%Y-%m-%d %H:%M") {
+        return Some(chrono::DateTime::from_naive_utc_and_offset(
+            parsed,
+            chrono::Utc,
+        ));
+    }
+
+    tracing::debug!(
+        thread_id,
+        field,
+        raw,
+        "Failed to parse engine thread timestamp"
+    );
+    None
+}
+
+/// Handle a single TUI event.
+async fn handle_event(
+    event: TuiEvent,
+    state: &mut AppState,
+    widgets: &mut BuiltinWidgets,
+    msg_tx: &mpsc::Sender<TuiUserMessage>,
+    layout: &TuiLayout,
+) {
+    match event {
+        TuiEvent::Paste(text) => {
+            let approval_active = state.pending_approval.is_some();
+            let help_active = state.help_visible;
+            let tool_detail_active = state.tool_detail_modal.is_some();
+
+            if !approval_active && !help_active && !tool_detail_active {
+                widgets.input_box.insert_text(&text);
+
+                if state.history_index.is_some() {
+                    state.history_index = None;
+                    state.history_draft = widgets.input_box.current_text();
+                }
+
+                update_input_overlays_from_input(&widgets.input_box, state);
+
+                if state.search.active {
+                    state.search.query = widgets.input_box.current_text();
+                    state.search.match_count =
+                        count_search_matches(&state.messages, &state.search.query);
+                    state.search.current_match = 0;
+                }
+            }
+        }
+        TuiEvent::Key(key) => {
+            let action = resolve_key_action(key, state, widgets);
+
+            match action {
+                InputAction::Submit => {
+                    let selected_model = if state.model_picker.visible {
+                        state.model_picker.selected_model().map(str::to_owned)
+                    } else {
+                        None
+                    };
+                    state.model_picker.close();
+                    state.command_palette.close();
+                    let text = widgets.input_box.take_input();
+                    let trimmed = if let Some(ref model) = selected_model {
+                        format!("/model {model}")
+                    } else {
+                        text.trim().to_string()
+                    };
+                    let attachments = std::mem::take(&mut state.pending_attachments);
+                    if !trimmed.is_empty() || !attachments.is_empty() {
+                        state.awaiting_model_list = selected_model.is_none()
+                            && attachments.is_empty()
+                            && trimmed == "/model";
+                        // Push to input history
+                        if !trimmed.is_empty() {
+                            state.input_history.push(trimmed.clone());
+                        }
+                        state.history_index = None;
+                        state.history_draft.clear();
+                        // Clear follow-up suggestions from previous turn
+                        state.suggestions.clear();
+                        // Build display content with attachment labels
+                        let display_content = if attachments.is_empty() {
+                            trimmed.clone()
+                        } else {
+                            let labels: Vec<&str> =
+                                attachments.iter().map(|a| a.label.as_str()).collect();
+                            if trimmed.is_empty() {
+                                format!("[{}]", labels.join("] ["))
+                            } else {
+                                format!("{trimmed} [{}]", labels.join("] ["))
+                            }
+                        };
+                        // Add user message to conversation
+                        state.messages.push(ChatMessage {
+                            role: MessageRole::User,
+                            content: display_content,
+                            timestamp: chrono::Utc::now(),
+                            cost_summary: None,
+                        });
+                        state.scroll_offset = 0;
+                        state.pinned_to_bottom = true;
+                        if let Some(model) = selected_model {
+                            state.model = model;
+                        }
+                        // Send to agent
+                        update_local_thread_scope_after_submit(state, &trimmed);
+                        let thread_id =
+                            outgoing_thread_scope(&trimmed, state.current_thread_id.as_deref());
+                        let _ = msg_tx
+                            .send(TuiUserMessage {
+                                text: trimmed,
+                                attachments,
+                                thread_id,
+                                ui_action: None,
+                            })
+                            .await;
+                    }
+                }
+                InputAction::Quit => {
+                    let _ = msg_tx.send(TuiUserMessage::text_only("/quit")).await;
+                    state.should_quit = true;
+                }
+                InputAction::ToggleSidebar => {
+                    state.sidebar_visible = !state.sidebar_visible;
+                }
+                InputAction::ToggleLogs => {
+                    state.active_tab = match state.active_tab {
+                        ActiveTab::Conversation => ActiveTab::Logs,
+                        ActiveTab::Logs => ActiveTab::Conversation,
+                    };
+                }
+                InputAction::ScrollUp => match state.active_tab {
+                    ActiveTab::Conversation => {
+                        let page = state.conversation_height.max(2).saturating_sub(2) as i16;
+                        widgets.conversation.scroll(state, -page);
+                    }
+                    ActiveTab::Logs => {
+                        LogsWidget::scroll(state, -5);
+                    }
+                },
+                InputAction::ScrollDown => match state.active_tab {
+                    ActiveTab::Conversation => {
+                        let page = state.conversation_height.max(2).saturating_sub(2) as i16;
+                        widgets.conversation.scroll(state, page);
+                    }
+                    ActiveTab::Logs => {
+                        LogsWidget::scroll(state, 5);
+                    }
+                },
+                InputAction::ScrollToBottom => {
+                    state.scroll_offset = 0;
+                    state.pinned_to_bottom = true;
+                }
+                InputAction::Interrupt => {
+                    let _ = msg_tx
+                        .send(
+                            TuiUserMessage::text_only("/interrupt")
+                                .with_thread_id(state.current_thread_id.clone()),
+                        )
+                        .await;
+                    state.status_text.clear();
+                }
+                InputAction::ApprovalUp => {
+                    if let Some(ref mut ap) = state.pending_approval {
+                        let count = ApprovalWidget::options(ap.allow_always).len();
+                        ap.selected = if ap.selected == 0 {
+                            count - 1
+                        } else {
+                            ap.selected - 1
+                        };
+                    }
+                }
+                InputAction::ApprovalDown => {
+                    if let Some(ref mut ap) = state.pending_approval {
+                        let count = ApprovalWidget::options(ap.allow_always).len();
+                        ap.selected = (ap.selected + 1) % count;
+                    }
+                }
+                InputAction::ApprovalConfirm => {
+                    if let Some(ref ap) = state.pending_approval {
+                        let options = ApprovalWidget::options(ap.allow_always);
+                        let action = options
+                            .get(ap.selected)
+                            .copied()
+                            .unwrap_or(ApprovalAction::Deny);
+                        let _ = msg_tx
+                            .send(
+                                TuiUserMessage::text_only(action.as_response())
+                                    .with_thread_id(state.current_thread_id.clone()),
+                            )
+                            .await;
+                        state.pending_approval = None;
+                    }
+                }
+                InputAction::ApprovalCancel => {
+                    if state.pending_approval.is_some() {
+                        let _ = msg_tx
+                            .send(
+                                TuiUserMessage::text_only("n")
+                                    .with_thread_id(state.current_thread_id.clone()),
+                            )
+                            .await;
+                        state.pending_approval = None;
+                    }
+                }
+                InputAction::QuickApprove => {
+                    if state.pending_approval.is_some() {
+                        let _ = msg_tx
+                            .send(
+                                TuiUserMessage::text_only("y")
+                                    .with_thread_id(state.current_thread_id.clone()),
+                            )
+                            .await;
+                        state.pending_approval = None;
+                    }
+                }
+                InputAction::QuickAlways => {
+                    if let Some(ref ap) = state.pending_approval {
+                        if ap.allow_always {
+                            let _ = msg_tx
+                                .send(
+                                    TuiUserMessage::text_only("a")
+                                        .with_thread_id(state.current_thread_id.clone()),
+                                )
+                                .await;
+                        } else {
+                            let _ = msg_tx
+                                .send(
+                                    TuiUserMessage::text_only("y")
+                                        .with_thread_id(state.current_thread_id.clone()),
+                                )
+                                .await;
+                        }
+                        state.pending_approval = None;
+                    }
+                }
+                InputAction::QuickDeny => {
+                    if state.pending_approval.is_some() {
+                        let _ = msg_tx
+                            .send(
+                                TuiUserMessage::text_only("n")
+                                    .with_thread_id(state.current_thread_id.clone()),
+                            )
+                            .await;
+                        state.pending_approval = None;
+                    }
+                }
+                InputAction::PaletteUp => {
+                    if state.model_picker.visible {
+                        state.model_picker.move_up();
+                    } else {
+                        state.command_palette.move_up();
+                    }
+                }
+                InputAction::PaletteDown => {
+                    if state.model_picker.visible {
+                        state.model_picker.move_down();
+                    } else {
+                        state.command_palette.move_down();
+                    }
+                }
+                InputAction::PaletteSelect => {
+                    if state.model_picker.visible {
+                        let command = state
+                            .model_picker
+                            .selected_model()
+                            .map(|model| format!("/model {model}"))
+                            .unwrap_or_else(|| widgets.input_box.current_text().trim().to_string());
+                        let attachments = std::mem::take(&mut state.pending_attachments);
+                        let _ = widgets.input_box.take_input();
+                        state.model_picker.close();
+                        state.command_palette.close();
+
+                        if !command.is_empty() || !attachments.is_empty() {
+                            state.awaiting_model_list =
+                                attachments.is_empty() && command == "/model";
+                            if !command.is_empty() {
+                                state.input_history.push(command.clone());
+                            }
+                            state.history_index = None;
+                            state.history_draft.clear();
+                            state.suggestions.clear();
+
+                            let display_content = if attachments.is_empty() {
+                                command.clone()
+                            } else {
+                                let labels: Vec<&str> =
+                                    attachments.iter().map(|a| a.label.as_str()).collect();
+                                format!("{command} [{}]", labels.join("] ["))
+                            };
+
+                            state.messages.push(ChatMessage {
+                                role: MessageRole::User,
+                                content: display_content,
+                                timestamp: chrono::Utc::now(),
+                                cost_summary: None,
+                            });
+                            state.scroll_offset = 0;
+                            state.pinned_to_bottom = true;
+
+                            if let Some(model) = command.strip_prefix("/model ") {
+                                state.model = model.to_string();
+                            }
+
+                            update_local_thread_scope_after_submit(state, &command);
+                            let thread_id =
+                                outgoing_thread_scope(&command, state.current_thread_id.as_deref());
+                            let _ = msg_tx
+                                .send(TuiUserMessage {
+                                    text: command,
+                                    attachments,
+                                    thread_id,
+                                    ui_action: None,
+                                })
+                                .await;
+                        }
+                    } else if let Some(cmd) = state.command_palette.selected_command() {
+                        state.command_palette.close();
+                        if cmd == "/model" {
+                            if state.model_picker.has_models() {
+                                widgets.input_box.set_text("/model ");
+                                state.model_picker.open("");
+                            } else {
+                                let command = cmd.to_string();
+                                let attachments = std::mem::take(&mut state.pending_attachments);
+                                let _ = widgets.input_box.take_input();
+
+                                if !command.is_empty() || !attachments.is_empty() {
+                                    state.awaiting_model_list =
+                                        attachments.is_empty() && command == "/model";
+                                    if !command.is_empty() {
+                                        state.input_history.push(command.clone());
+                                    }
+                                    state.history_index = None;
+                                    state.history_draft.clear();
+                                    state.suggestions.clear();
+
+                                    let display_content = if attachments.is_empty() {
+                                        command.clone()
+                                    } else {
+                                        let labels: Vec<&str> =
+                                            attachments.iter().map(|a| a.label.as_str()).collect();
+                                        format!("{command} [{}]", labels.join("] ["))
+                                    };
+
+                                    state.messages.push(ChatMessage {
+                                        role: MessageRole::User,
+                                        content: display_content,
+                                        timestamp: chrono::Utc::now(),
+                                        cost_summary: None,
+                                    });
+                                    state.scroll_offset = 0;
+                                    state.pinned_to_bottom = true;
+
+                                    update_local_thread_scope_after_submit(state, &command);
+                                    let thread_id = outgoing_thread_scope(
+                                        &command,
+                                        state.current_thread_id.as_deref(),
+                                    );
+                                    let _ = msg_tx
+                                        .send(TuiUserMessage {
+                                            text: command,
+                                            attachments,
+                                            thread_id,
+                                            ui_action: None,
+                                        })
+                                        .await;
+                                }
+                            }
+                        } else {
+                            let text = format!("{cmd} ");
+                            widgets.input_box.set_text(&text);
+                        }
+                    }
+                }
+                InputAction::PaletteClose => {
+                    state.model_picker.close();
+                    state.command_palette.close();
+                }
+                InputAction::SearchToggle => {
+                    state.search.active = !state.search.active;
+                    if !state.search.active {
+                        state.search.query.clear();
+                        state.search.match_count = 0;
+                        state.search.current_match = 0;
+                    }
+                }
+                InputAction::SearchNext => {
+                    if state.search.match_count > 0 {
+                        state.search.current_match =
+                            (state.search.current_match + 1) % state.search.match_count;
+                    }
+                }
+                InputAction::SearchPrev => {
+                    if state.search.match_count > 0 {
+                        state.search.current_match = if state.search.current_match == 0 {
+                            state.search.match_count - 1
+                        } else {
+                            state.search.current_match - 1
+                        };
+                    }
+                }
+                InputAction::HistoryUp => {
+                    if !state.input_history.is_empty() {
+                        let new_idx = match state.history_index {
+                            None => {
+                                // Save current draft, start from most recent
+                                state.history_draft = widgets.input_box.current_text();
+                                state.input_history.len() - 1
+                            }
+                            Some(idx) => idx.saturating_sub(1),
+                        };
+                        state.history_index = Some(new_idx);
+                        if let Some(text) = state.input_history.get(new_idx) {
+                            widgets.input_box.set_text(text);
+                            update_input_overlays_from_input(&widgets.input_box, state);
+                        }
+                    }
+                }
+                InputAction::HistoryDown => {
+                    if let Some(idx) = state.history_index {
+                        if idx + 1 >= state.input_history.len() {
+                            // Back to draft
+                            state.history_index = None;
+                            let draft = state.history_draft.clone();
+                            widgets.input_box.set_text(&draft);
+                            update_input_overlays_from_input(&widgets.input_box, state);
+                        } else {
+                            let new_idx = idx + 1;
+                            state.history_index = Some(new_idx);
+                            if let Some(text) = state.input_history.get(new_idx) {
+                                widgets.input_box.set_text(text);
+                                update_input_overlays_from_input(&widgets.input_box, state);
+                            }
+                        }
+                    }
+                }
+                InputAction::ToggleHelp => {
+                    state.help_visible = !state.help_visible;
+                }
+                InputAction::ExpandTool => {
+                    // Show the most recent tool with a result preview
+                    if let Some(tool) = state
+                        .recent_tools
+                        .iter()
+                        .rev()
+                        .find(|t| t.result_preview.is_some())
+                    {
+                        state.tool_detail_modal = Some(ToolDetailModal {
+                            tool_name: tool.name.clone(),
+                            content: tool.result_preview.clone().unwrap_or_default(),
+                            scroll: 0,
+                        });
+                    }
+                }
+                InputAction::ToolDetailClose => {
+                    state.tool_detail_modal = None;
+                }
+                InputAction::ToolDetailScrollUp => {
+                    if let Some(ref mut modal) = state.tool_detail_modal {
+                        modal.scroll = modal.scroll.saturating_add(5);
+                    }
+                }
+                InputAction::ToolDetailScrollDown => {
+                    if let Some(ref mut modal) = state.tool_detail_modal {
+                        modal.scroll = modal.scroll.saturating_sub(5);
+                    }
+                }
+                InputAction::LogFilter(level) => {
+                    state.log_level_filter = level;
+                }
+                InputAction::ClipboardPaste => {
+                    if let Some(attachment) = try_paste_clipboard_image(state) {
+                        state.toasts.push(Toast {
+                            message: format!("Pasted: {}", attachment.label),
+                            kind: ToastKind::Info,
+                            created_at: chrono::Utc::now(),
+                        });
+                        state.pending_attachments.push(attachment);
+                    }
+                }
+                InputAction::ThreadPickerUp => {
+                    if let Some(ref mut picker) = state.pending_thread_picker {
+                        crate::widgets::thread_picker::thread_picker_up(picker);
+                    }
+                }
+                InputAction::ThreadPickerDown => {
+                    if let Some(ref mut picker) = state.pending_thread_picker {
+                        crate::widgets::thread_picker::thread_picker_down(picker);
+                    }
+                }
+                InputAction::ThreadPickerSelect => {
+                    if let Some(ref picker) = state.pending_thread_picker
+                        && let Some(id) =
+                            crate::widgets::thread_picker::thread_picker_selected_id(picker)
+                    {
+                        let cmd = format!("/thread {id}");
+                        let _ = msg_tx
+                            .send(TuiUserMessage::text_only(cmd).with_thread_id(None))
+                            .await;
+                        state.current_thread_id = Some(id.to_string());
+                    }
+                    state.pending_thread_picker = None;
+                }
+                InputAction::ThreadPickerClose => {
+                    state.pending_thread_picker = None;
+                }
+                InputAction::Forward => {
+                    if state.search.active {
+                        // Update the search query with the key event
+                        match (key.code, key.modifiers) {
+                            (KeyCode::Char(c), KeyModifiers::NONE | KeyModifiers::SHIFT) => {
+                                state.search.query.push(c);
+                            }
+                            (KeyCode::Backspace, _) => {
+                                state.search.query.pop();
+                            }
+                            _ => {}
+                        }
+                        // Recount matches
+                        state.search.match_count =
+                            count_search_matches(&state.messages, &state.search.query);
+                        // Clamp current_match
+                        if state.search.match_count == 0 {
+                            state.search.current_match = 0;
+                        } else if state.search.current_match >= state.search.match_count {
+                            state.search.current_match = state.search.match_count - 1;
+                        }
+                    } else if key.code == KeyCode::Backspace
+                        && widgets.input_box.is_empty()
+                        && !state.pending_attachments.is_empty()
+                    {
+                        let removed = state.pending_attachments.pop();
+                        if let Some(att) = removed {
+                            state.toasts.push(Toast {
+                                message: format!("Removed: {}", att.label),
+                                kind: ToastKind::Info,
+                                created_at: chrono::Utc::now(),
+                            });
+                        }
+                    } else {
+                        widgets.input_box.handle_key(key, state);
+                        // Update command palette visibility based on input content
+                        update_input_overlays_from_input(&widgets.input_box, state);
+                    }
+                }
+            }
+        }
+
+        TuiEvent::MouseClick { column, row } => {
+            handle_mouse_click(column, row, state, msg_tx, layout).await;
+        }
+
+        TuiEvent::MouseDrag { column, row } => {
+            handle_mouse_drag(column, row, state);
+        }
+
+        TuiEvent::MouseRelease { column, row } => {
+            handle_mouse_release(column, row, state);
+        }
+
+        TuiEvent::MouseScroll(delta) => {
+            if let Some(ref mut modal) = state.tool_detail_modal {
+                if delta < 0 {
+                    modal.scroll = modal.scroll.saturating_add(delta.unsigned_abs());
+                } else {
+                    modal.scroll = modal.scroll.saturating_sub(delta as u16);
+                }
+            } else if let Some(ref mut picker) = state.pending_thread_picker {
+                if delta < 0 {
+                    crate::widgets::thread_picker::thread_picker_up(picker);
+                } else if delta > 0 {
+                    crate::widgets::thread_picker::thread_picker_down(picker);
+                }
+            } else if let Some(ref mut approval) = state.pending_approval {
+                let count = ApprovalWidget::options(approval.allow_always).len();
+                if delta < 0 {
+                    approval.selected = if approval.selected == 0 {
+                        count - 1
+                    } else {
+                        approval.selected - 1
+                    };
+                } else if delta > 0 {
+                    approval.selected = (approval.selected + 1) % count;
+                }
+            } else if !state.help_visible {
+                match state.active_tab {
+                    ActiveTab::Conversation => {
+                        widgets.conversation.scroll(state, delta);
+                    }
+                    ActiveTab::Logs => {
+                        LogsWidget::scroll(state, delta);
+                    }
+                }
+            }
+        }
+
+        TuiEvent::Resize(_, _) => {
+            // Terminal will re-render on next frame
+        }
+
+        TuiEvent::Tick => {
+            state.tick_count = state.tick_count.wrapping_add(1);
+        }
+
+        TuiEvent::Thinking(msg) => {
+            state.status_text = msg;
+        }
+
+        TuiEvent::ToolStarted {
+            name,
+            detail,
+            call_id,
+        } => {
+            state.status_text = match &detail {
+                Some(d) => format!("Running {name}: {d}"),
+                None => format!("Running {name}..."),
+            };
+            state.active_tools.push(ToolActivity {
+                call_id,
+                name,
+                started_at: chrono::Utc::now(),
+                duration_ms: None,
+                status: ToolStatus::Running,
+                detail,
+                result_preview: None,
+            });
+        }
+
+        TuiEvent::ToolCompleted {
+            name,
+            success,
+            error: _,
+            call_id,
+        } => {
+            // Move from active to recent
+            if let Some(pos) = state
+                .active_tools
+                .iter()
+                .position(|t| tool_activity_matches(t, &name, call_id.as_deref()))
+            {
+                let mut tool = state.active_tools.remove(pos);
+                tool.duration_ms = Some(
+                    chrono::Utc::now()
+                        .signed_duration_since(tool.started_at)
+                        .num_milliseconds()
+                        .unsigned_abs(),
+                );
+                tool.status = if success {
+                    ToolStatus::Success
+                } else {
+                    ToolStatus::Failed
+                };
+                state.recent_tools.push(tool);
+                // Keep recent list bounded
+                if state.recent_tools.len() > 20 {
+                    state.recent_tools.remove(0);
+                }
+            }
+            if state.active_tools.is_empty() {
+                state.status_text.clear();
+            }
+        }
+
+        TuiEvent::ToolResult {
+            name,
+            preview,
+            call_id,
+        } => {
+            if let Some(tool) = state
+                .active_tools
+                .iter_mut()
+                .find(|t| tool_activity_matches(t, &name, call_id.as_deref()))
+            {
+                tool.result_preview = Some(preview);
+            } else if let Some(tool) = state
+                .recent_tools
+                .iter_mut()
+                .rev()
+                .find(|t| tool_activity_matches(t, &name, call_id.as_deref()))
+            {
+                tool.result_preview = Some(preview);
+            }
+        }
+
+        TuiEvent::StreamChunk(chunk) => {
+            state.is_streaming = true;
+            // Append to the last assistant message, or create one
+            if let Some(last) = state.messages.last_mut() {
+                if last.role == MessageRole::Assistant {
+                    last.content.push_str(&chunk);
+                } else {
+                    state.messages.push(ChatMessage {
+                        role: MessageRole::Assistant,
+                        content: chunk,
+                        timestamp: chrono::Utc::now(),
+                        cost_summary: None,
+                    });
+                }
+            } else {
+                state.messages.push(ChatMessage {
+                    role: MessageRole::Assistant,
+                    content: chunk,
+                    timestamp: chrono::Utc::now(),
+                    cost_summary: None,
+                });
+            }
+            state.scroll_offset = 0;
+            state.pinned_to_bottom = true;
+        }
+
+        TuiEvent::Status(msg) => {
+            state.status_text = msg;
+        }
+
+        TuiEvent::Response { content, thread_id } => {
+            if let Some(thread_id) = thread_id {
+                state.current_thread_id = Some(thread_id);
+            }
+            let was_streaming = state.is_streaming;
+            state.is_streaming = false;
+            state.status_text.clear();
+            let parsed_model_response = if state.awaiting_model_list {
+                parse_model_list_response(&content)
+            } else {
+                None
+            };
+            state.awaiting_model_list = false;
+            // Streaming responses accumulate via StreamChunk; non-streaming
+            // responses still need a fresh assistant message.
+            if let Some(last) = state.messages.last_mut() {
+                if last.role == MessageRole::Assistant && was_streaming {
+                    // Streaming finished — content was already accumulated
+                } else {
+                    state.messages.push(ChatMessage {
+                        role: MessageRole::Assistant,
+                        content,
+                        timestamp: chrono::Utc::now(),
+                        cost_summary: None,
+                    });
+                }
+            } else {
+                state.messages.push(ChatMessage {
+                    role: MessageRole::Assistant,
+                    content,
+                    timestamp: chrono::Utc::now(),
+                    cost_summary: None,
+                });
+            }
+            state.scroll_offset = 0;
+            state.pinned_to_bottom = true;
+            state.active_tools.clear();
+
+            if let Some((active_model, models)) = parsed_model_response {
+                state.model = active_model;
+                state.model_picker.set_models(models);
+                widgets.input_box.set_text("/model ");
+                update_input_overlays_from_input(&widgets.input_box, state);
+            }
+        }
+
+        TuiEvent::JobStarted { job_id, title } => {
+            let now = chrono::Utc::now();
+            state.messages.push(ChatMessage {
+                role: MessageRole::System,
+                content: format!("[job] {title} ({job_id})"),
+                timestamp: now,
+                cost_summary: None,
+            });
+            state.toasts.push(Toast {
+                message: format!("Job started: {title}"),
+                kind: ToastKind::Info,
+                created_at: now,
+            });
+            state.jobs.push(JobInfo {
+                id: job_id.clone(),
+                title: title.clone(),
+                status: JobStatus::Running,
+                started_at: now,
+            });
+        }
+
+        TuiEvent::JobStatus { job_id, status } => {
+            let new_status = match status.as_str() {
+                "running" | "in_progress" => JobStatus::Running,
+                "completed" | "done" => JobStatus::Completed,
+                "failed" => JobStatus::Failed,
+                _ => JobStatus::Running,
+            };
+            if let Some(job) = state.jobs.iter_mut().find(|j| j.id == job_id) {
+                job.status = new_status;
+            }
+        }
+
+        TuiEvent::JobResult { job_id, status } => {
+            let new_status = if status == "failed" {
+                JobStatus::Failed
+            } else {
+                JobStatus::Completed
+            };
+            if let Some(job) = state.jobs.iter_mut().find(|j| j.id == job_id) {
+                job.status = new_status;
+            }
+        }
+
+        TuiEvent::RoutineUpdate {
+            id,
+            name,
+            trigger_type,
+            enabled,
+            last_run,
+            next_fire,
+        } => {
+            // Upsert: update existing or insert new
+            if let Some(routine) = state.routines.iter_mut().find(|r| r.id == id) {
+                routine.name = name;
+                routine.trigger_type = trigger_type;
+                routine.enabled = enabled;
+                routine.last_run = last_run;
+                routine.next_fire = next_fire;
+            } else {
+                state.routines.push(RoutineInfo {
+                    id,
+                    name,
+                    trigger_type,
+                    enabled,
+                    last_run,
+                    next_fire,
+                });
+            }
+        }
+
+        TuiEvent::ApprovalNeeded {
+            request_id,
+            tool_name,
+            description,
+            parameters,
+            allow_always,
+        } => {
+            state.pending_approval = Some(super::widgets::ApprovalRequest {
+                request_id,
+                tool_name,
+                description,
+                parameters,
+                allow_always,
+                selected: 0,
+            });
+        }
+
+        TuiEvent::AuthRequired {
+            extension_name,
+            instructions,
+        } => {
+            let msg = if let Some(instr) = instructions {
+                format!("Authentication required for {extension_name}: {instr}")
+            } else {
+                format!("Authentication required for {extension_name}")
+            };
+            state.toasts.push(Toast {
+                message: format!("Auth needed: {extension_name}"),
+                kind: ToastKind::Warning,
+                created_at: chrono::Utc::now(),
+            });
+            state.messages.push(ChatMessage {
+                role: MessageRole::System,
+                content: msg,
+                timestamp: chrono::Utc::now(),
+                cost_summary: None,
+            });
+        }
+
+        TuiEvent::AuthCompleted {
+            extension_name,
+            success,
+            message,
+        } => {
+            let prefix = if success { "\u{2713}" } else { "\u{2717}" };
+            state.toasts.push(Toast {
+                message: format!("{prefix} {extension_name}"),
+                kind: if success {
+                    ToastKind::Success
+                } else {
+                    ToastKind::Error
+                },
+                created_at: chrono::Utc::now(),
+            });
+            state.messages.push(ChatMessage {
+                role: MessageRole::System,
+                content: format!("{prefix} {extension_name}: {message}"),
+                timestamp: chrono::Utc::now(),
+                cost_summary: None,
+            });
+        }
+
+        TuiEvent::ReasoningUpdate { narrative } => {
+            if !narrative.is_empty() {
+                state.status_text = narrative;
+            }
+        }
+
+        TuiEvent::TurnCost {
+            input_tokens,
+            output_tokens,
+            cost_usd,
+        } => {
+            state.total_input_tokens += input_tokens;
+            state.total_output_tokens += output_tokens;
+            state.total_cost_usd = cost_usd.clone();
+            // Attach to last assistant message
+            if let Some(msg) = state
+                .messages
+                .iter_mut()
+                .rev()
+                .find(|m| m.role == MessageRole::Assistant)
+            {
+                msg.cost_summary = Some(TurnCostSummary {
+                    input_tokens,
+                    output_tokens,
+                    cost_usd,
+                });
+            }
+        }
+
+        TuiEvent::Suggestions { suggestions } => {
+            state.suggestions = suggestions;
+        }
+
+        TuiEvent::ContextPressure {
+            used_tokens,
+            max_tokens,
+            percentage,
+            warning,
+        } => {
+            // Update context_window from the engine's actual value
+            if max_tokens > 0 {
+                state.context_window = max_tokens;
+            }
+            state.context_pressure = Some(ContextPressureInfo {
+                used_tokens,
+                max_tokens,
+                percentage,
+                warning,
+            });
+        }
+
+        TuiEvent::SandboxStatus {
+            docker_available,
+            running_containers,
+            status,
+        } => {
+            state.sandbox_status = Some(SandboxInfo {
+                docker_available,
+                running_containers,
+                status,
+            });
+        }
+
+        TuiEvent::SecretsStatus {
+            count,
+            vault_unlocked,
+        } => {
+            state.secrets_status = Some(SecretsInfo {
+                count,
+                vault_unlocked,
+            });
+        }
+
+        TuiEvent::CostGuard {
+            session_budget_usd,
+            spent_usd,
+            remaining_usd,
+            limit_reached,
+        } => {
+            if limit_reached {
+                state.toasts.push(Toast {
+                    message: "Cost limit reached".to_string(),
+                    kind: ToastKind::Error,
+                    created_at: chrono::Utc::now(),
+                });
+            }
+            state.cost_guard = Some(CostGuardInfo {
+                session_budget_usd,
+                spent_usd,
+                remaining_usd,
+                limit_reached,
+            });
+        }
+
+        TuiEvent::Log {
+            level,
+            target,
+            message,
+            timestamp,
+        } => {
+            state.log_entries.push(TuiLogEntry {
+                level,
+                target,
+                message,
+                timestamp,
+            });
+        }
+
+        TuiEvent::ThreadList { threads } => {
+            // ThreadList only populates the /resume picker, not the sidebar.
+            // The sidebar THREADS section uses EngineThreadList instead.
+            state.pending_thread_picker = if threads.is_empty() {
+                None
+            } else {
+                Some(super::widgets::ThreadPickerState {
+                    threads,
+                    selected: 0,
+                })
+            };
+        }
+
+        TuiEvent::EngineThreadList { threads } => {
+            state.engine_threads = threads
+                .iter()
+                .map(|t| EngineThreadInfo {
+                    id: t.id.clone(),
+                    goal: t.goal.clone(),
+                    thread_type: t.thread_type.clone(),
+                    status: match t.state.as_str() {
+                        "Running" => ThreadStatus::Active,
+                        "Completed" | "Done" => ThreadStatus::Completed,
+                        "Failed" => ThreadStatus::Failed,
+                        _ => ThreadStatus::Idle,
+                    },
+                    step_count: t.step_count,
+                    total_tokens: t.total_tokens,
+                    started_at: parse_engine_thread_timestamp(&t.created_at, "created_at", &t.id),
+                    updated_at: parse_engine_thread_timestamp(&t.updated_at, "updated_at", &t.id),
+                })
+                .collect();
+        }
+
+        TuiEvent::EngineThreadDetail { detail } => {
+            state.tool_detail_modal = Some(ToolDetailModal {
+                tool_name: format!("Thread {}", detail.thread_type),
+                content: format_engine_thread_detail(&detail),
+                scroll: 0,
+            });
+        }
+
+        TuiEvent::ConversationHistory {
+            thread_id,
+            messages,
+            pending_approval,
+        } => {
+            state.current_thread_id = Some(thread_id.clone());
+            state.messages.clear();
+            state.active_tools.clear();
+            state.recent_tools.clear();
+            state.is_streaming = false;
+            state.status_text.clear();
+            state.pending_approval = pending_approval.map(|approval| ApprovalRequest {
+                request_id: approval.request_id,
+                tool_name: approval.tool_name,
+                description: approval.description,
+                parameters: approval.parameters,
+                allow_always: approval.allow_always,
+                selected: 0,
+            });
+            state.suggestions.clear();
+            for thread in &mut state.threads {
+                thread.is_foreground = thread.id == thread_id;
+                thread.status = if thread.is_foreground {
+                    ThreadStatus::Active
+                } else {
+                    ThreadStatus::Idle
+                };
+            }
+
+            for msg in &messages {
+                let role = match msg.role.as_str() {
+                    "user" => MessageRole::User,
+                    "assistant" => MessageRole::Assistant,
+                    _ => MessageRole::System,
+                };
+                state.messages.push(ChatMessage {
+                    role,
+                    content: msg.content.clone(),
+                    timestamp: msg.timestamp,
+                    cost_summary: None,
+                });
+            }
+
+            state.scroll_offset = 0;
+            state.pinned_to_bottom = true;
+            state.toasts.push(Toast {
+                message: format!("Resumed conversation ({} messages)", state.messages.len()),
+                kind: ToastKind::Info,
+                created_at: chrono::Utc::now(),
+            });
+        }
+    }
+}
+
+fn resolve_key_action(
+    key: event::KeyEvent,
+    state: &AppState,
+    widgets: &BuiltinWidgets,
+) -> InputAction {
+    let approval_active = state.pending_approval.is_some();
+    let palette_active = state.command_palette.visible || state.model_picker.visible;
+    let search_active = state.search.active;
+    let help_active = state.help_visible;
+    let tool_detail_active = state.tool_detail_modal.is_some();
+    let logs_active = state.active_tab == ActiveTab::Logs;
+    let thread_picker_active = state.pending_thread_picker.is_some();
+
+    let action = map_key(
+        key,
+        approval_active,
+        palette_active,
+        search_active,
+        help_active,
+        tool_detail_active,
+        logs_active,
+        thread_picker_active,
+    );
+
+    if action != InputAction::Forward {
+        return action;
+    }
+
+    if key.modifiers != KeyModifiers::NONE
+        || approval_active
+        || palette_active
+        || search_active
+        || help_active
+        || tool_detail_active
+        || thread_picker_active
+    {
+        return InputAction::Forward;
+    }
+
+    match key.code {
+        KeyCode::Up if widgets.input_box.is_cursor_on_first_line() => InputAction::HistoryUp,
+        KeyCode::Down
+            if state.history_index.is_some() || widgets.input_box.is_cursor_on_last_line() =>
+        {
+            InputAction::HistoryDown
+        }
+        _ => InputAction::Forward,
+    }
+}
+
+fn tool_activity_matches(tool: &ToolActivity, name: &str, call_id: Option<&str>) -> bool {
+    match call_id {
+        Some(call_id) => tool.call_id.as_deref() == Some(call_id),
+        None => tool.name == name,
+    }
+}
+
+fn parse_model_list_response(content: &str) -> Option<(String, Vec<String>)> {
+    let mut lines = content.lines();
+    let active_model = lines
+        .next()?
+        .strip_prefix("Active model: ")?
+        .trim()
+        .to_string();
+
+    let mut in_model_section = false;
+    let mut models = Vec::new();
+
+    for line in content.lines() {
+        let trimmed = line.trim();
+        if trimmed == "Available models:" {
+            in_model_section = true;
+            continue;
+        }
+
+        if !in_model_section {
+            continue;
+        }
+
+        if trimmed.is_empty() || trimmed.starts_with("Use /model ") {
+            break;
+        }
+
+        let model = trimmed
+            .strip_suffix(" (active)")
+            .unwrap_or(trimmed)
+            .trim()
+            .to_string();
+        if !model.is_empty() {
+            models.push(model);
+        }
+    }
+
+    if models.is_empty() {
+        None
+    } else {
+        Some((active_model, models))
+    }
+}
+
+fn format_detail_timestamp(raw: &str) -> String {
+    chrono::DateTime::parse_from_rfc3339(raw)
+        .map(|dt| dt.with_timezone(&chrono::Local))
+        .map(|dt| dt.format("%Y-%m-%d %H:%M:%S %Z").to_string())
+        .unwrap_or_else(|_| raw.to_string())
+}
+
+fn format_engine_thread_detail(detail: &crate::event::EngineThreadDetailEntry) -> String {
+    use std::fmt::Write as _;
+
+    let mut content = String::new();
+    let _ = writeln!(content, "Goal");
+    let _ = writeln!(content, "{}", detail.goal);
+    let _ = writeln!(content);
+
+    let _ = writeln!(content, "Overview");
+    let _ = writeln!(content, "  Thread ID: {}", detail.id);
+    let _ = writeln!(content, "  Type: {}", detail.thread_type);
+    let _ = writeln!(content, "  State: {}", detail.state);
+    let _ = writeln!(content, "  Steps: {}", detail.step_count);
+    let _ = writeln!(content, "  Tokens: {}", detail.total_tokens);
+    let _ = writeln!(content, "  Cost: ${:.4}", detail.total_cost_usd);
+    let _ = writeln!(content, "  Max iterations: {}", detail.max_iterations);
+    let _ = writeln!(
+        content,
+        "  Created: {}",
+        format_detail_timestamp(&detail.created_at)
+    );
+    let _ = writeln!(
+        content,
+        "  Updated: {}",
+        format_detail_timestamp(&detail.updated_at)
+    );
+    let completed = detail
+        .completed_at
+        .as_deref()
+        .map(format_detail_timestamp)
+        .unwrap_or_else(|| "-".to_string());
+    let _ = writeln!(content, "  Completed: {completed}");
+    let _ = writeln!(content, "  Project: {}", detail.project_id);
+    let _ = writeln!(
+        content,
+        "  Parent: {}",
+        detail.parent_id.as_deref().unwrap_or("-")
+    );
+
+    if detail.messages.is_empty() {
+        return content;
+    }
+
+    let _ = writeln!(content);
+    let _ = writeln!(content, "Messages ({})", detail.messages.len());
+    for message in &detail.messages {
+        let _ = writeln!(
+            content,
+            "\n[{}] {}",
+            message.role,
+            format_detail_timestamp(&message.timestamp)
+        );
+        let _ = writeln!(content, "{}", message.content);
+    }
+
+    content
+}
+
+struct TerminalRestoreGuard {
+    active: bool,
+}
+
+impl TerminalRestoreGuard {
+    fn new() -> Self {
+        Self { active: true }
+    }
+
+    fn disarm(&mut self) {
+        self.active = false;
+    }
+}
+
+impl Drop for TerminalRestoreGuard {
+    fn drop(&mut self) {
+        if !self.active {
+            return;
+        }
+
+        let _ = disable_raw_mode();
+        let mut stdout = io::stdout();
+        let _ = execute!(
+            stdout,
+            Show,
+            DisableBracketedPaste,
+            ratatui::crossterm::event::DisableMouseCapture,
+            LeaveAlternateScreen
+        );
+        let _ = stdout.flush();
+    }
+}
+
+#[cfg(test)]
+fn terminal_area() -> Rect {
+    Rect::new(0, 0, 80, 24)
+}
+
+#[cfg(not(test))]
+fn terminal_area() -> Rect {
+    ratatui::crossterm::terminal::size()
+        .map(|(width, height)| Rect::new(0, 0, width, height))
+        .unwrap_or_else(|_| Rect::new(0, 0, 80, 24))
+}
+
+#[cfg(test)]
+static LAST_COPIED_TEXT: std::sync::Mutex<Option<String>> = std::sync::Mutex::new(None);
+
+#[cfg(test)]
+fn take_last_copied_text_for_test() -> Option<String> {
+    LAST_COPIED_TEXT
+        .lock()
+        .expect("copied text mutex poisoned")
+        .take()
+}
+
+fn copy_text_to_clipboard(text: &str) -> bool {
+    #[cfg(test)]
+    {
+        *LAST_COPIED_TEXT.lock().unwrap_or_else(|e| e.into_inner()) = Some(text.to_string());
+        true
+    }
+
+    #[cfg(not(test))]
+    {
+        arboard::Clipboard::new()
+            .and_then(|mut clipboard| clipboard.set_text(text.to_string()))
+            .is_ok()
+    }
+}
+
+async fn handle_mouse_click(
+    column: u16,
+    row: u16,
+    state: &mut AppState,
+    msg_tx: &mpsc::Sender<TuiUserMessage>,
+    layout: &TuiLayout,
+) {
+    let terminal = terminal_area();
+
+    if let Some(ref approval) = state.pending_approval
+        && let Some(action) = approval_action_at(terminal, approval, column, row)
+    {
+        let _ = msg_tx
+            .send(
+                TuiUserMessage::text_only(action.as_response())
+                    .with_thread_id(state.current_thread_id.clone()),
+            )
+            .await;
+        state.pending_approval = None;
+        state.text_selection = None;
+        return;
+    }
+
+    if let Some(ref picker) = state.pending_thread_picker {
+        if let Some(index) = thread_picker_index_at(terminal, picker, column, row) {
+            if let Some(thread) = picker.threads.get(index) {
+                let _ = msg_tx
+                    .send(
+                        TuiUserMessage::text_only(format!("/thread {}", thread.id))
+                            .with_thread_id(None),
+                    )
+                    .await;
+                state.current_thread_id = Some(thread.id.clone());
+            }
+            state.pending_thread_picker = None;
+            state.text_selection = None;
+            return;
+        }
+
+        if !rect_contains(
+            ThreadPickerWidget::modal_area(terminal, picker.threads.len()),
+            column,
+            row,
+        ) {
+            state.pending_thread_picker = None;
+        }
+        state.text_selection = None;
+        return;
+    }
+
+    if state.help_visible {
+        state.help_visible = false;
+        state.text_selection = None;
+        return;
+    }
+
+    if let Some(tab) = tab_at(terminal, layout, state, column, row) {
+        state.active_tab = tab;
+        state.text_selection = None;
+        return;
+    }
+
+    if state.tool_detail_modal.is_none()
+        && let Some(area) = thread_list_sidebar_area(terminal, layout, state)
+        && let Some(index) = engine_thread_index_at(area, state, column, row)
+        && let Some(thread) = state.engine_threads.get(index)
+    {
+        let _ = msg_tx
+            .send(TuiUserMessage::open_engine_thread_detail(thread.id.clone()))
+            .await;
+        state.text_selection = None;
+        return;
+    }
+
+    if let Some(bounds) = selectable_area_at(terminal, layout, state, column, row) {
+        state.text_selection = Some(TextSelection {
+            anchor: SelectionPoint { column, row },
+            focus: SelectionPoint { column, row },
+            bounds,
+        });
+        return;
+    }
+
+    state.text_selection = None;
+    if state.tool_detail_modal.is_some()
+        && !rect_contains(tool_detail_modal_area(terminal), column, row)
+    {
+        state.tool_detail_modal = None;
+    }
+}
+
+fn handle_mouse_drag(column: u16, row: u16, state: &mut AppState) {
+    if let Some(ref mut selection) = state.text_selection {
+        selection.focus = clamp_point_to_rect(SelectionPoint { column, row }, selection.bounds);
+    }
+}
+
+fn handle_mouse_release(column: u16, row: u16, state: &mut AppState) {
+    let Some(ref mut selection) = state.text_selection else {
+        return;
+    };
+
+    selection.focus = clamp_point_to_rect(SelectionPoint { column, row }, selection.bounds);
+
+    if selection.anchor == selection.focus {
+        state.text_selection = None;
+        return;
+    }
+
+    let text = extract_selected_text(&state.screen_snapshot, selection);
+    if text.is_empty() {
+        state.text_selection = None;
+        return;
+    }
+
+    let copied = copy_text_to_clipboard(&text);
+    state.toasts.push(Toast {
+        message: if copied {
+            format!("Copied {} chars", text.chars().count())
+        } else {
+            "Copy failed".to_string()
+        },
+        kind: if copied {
+            ToastKind::Success
+        } else {
+            ToastKind::Error
+        },
+        created_at: chrono::Utc::now(),
+    });
+}
+
+fn frame_sections(size: Rect, layout: &TuiLayout, state: &AppState) -> [Rect; 5] {
+    let header_height = if layout.header.visible { 1 } else { 0 };
+    let status_height = if layout.status_bar.visible { 1 } else { 0 };
+    let tab_bar_height = 1u16;
+    let input_height = if state.pending_attachments.is_empty() {
+        3u16
+    } else {
+        4u16
+    };
+
+    let vertical = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(header_height),
+            Constraint::Length(tab_bar_height),
+            Constraint::Min(4),
+            Constraint::Length(input_height),
+            Constraint::Length(status_height),
+        ])
+        .split(size);
+
+    [
+        vertical[0],
+        vertical[1],
+        vertical[2],
+        vertical[3],
+        vertical[4],
+    ]
+}
+
+fn tab_at(
+    size: Rect,
+    layout: &TuiLayout,
+    state: &AppState,
+    column: u16,
+    row: u16,
+) -> Option<ActiveTab> {
+    let tab_bar_area = frame_sections(size, layout, state)[1];
+    if !rect_contains(tab_bar_area, column, row) {
+        return None;
+    }
+
+    let relative_x = column.saturating_sub(tab_bar_area.x);
+    if (2..6).contains(&relative_x) {
+        Some(ActiveTab::Conversation)
+    } else if (8..12).contains(&relative_x) {
+        Some(ActiveTab::Logs)
+    } else {
+        None
+    }
+}
+
+fn selectable_area_at(
+    size: Rect,
+    layout: &TuiLayout,
+    state: &AppState,
+    column: u16,
+    row: u16,
+) -> Option<Rect> {
+    if state.tool_detail_modal.is_some() {
+        let inner = tool_detail_inner_area(tool_detail_modal_area(size));
+        if rect_contains(inner, column, row) {
+            return Some(inner);
+        }
+        return None;
+    }
+
+    let main_area = frame_sections(size, layout, state)[2];
+    let selectable = match state.active_tab {
+        ActiveTab::Logs => main_area,
+        ActiveTab::Conversation => {
+            if state.sidebar_visible && main_area.width > 40 {
+                let sidebar_width =
+                    (main_area.width as u32 * layout.sidebar.effective_width() as u32 / 100) as u16;
+                let conversation_width = main_area.width.saturating_sub(sidebar_width + 1);
+
+                Layout::default()
+                    .direction(Direction::Horizontal)
+                    .constraints([
+                        Constraint::Length(conversation_width),
+                        Constraint::Length(1),
+                        Constraint::Length(sidebar_width),
+                    ])
+                    .split(main_area)[0]
+            } else {
+                main_area
+            }
+        }
+    };
+
+    rect_contains(selectable, column, row).then_some(selectable)
+}
+
+fn thread_list_sidebar_area(size: Rect, layout: &TuiLayout, state: &AppState) -> Option<Rect> {
+    if state.active_tab != ActiveTab::Conversation || !state.sidebar_visible {
+        return None;
+    }
+
+    let main_area = frame_sections(size, layout, state)[2];
+    if main_area.width <= 40 {
+        return None;
+    }
+
+    let sidebar_width =
+        (main_area.width as u32 * layout.sidebar.effective_width() as u32 / 100) as u16;
+    let conversation_width = main_area.width.saturating_sub(sidebar_width + 1);
+    let horizontal = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([
+            Constraint::Length(conversation_width),
+            Constraint::Length(1),
+            Constraint::Length(sidebar_width),
+        ])
+        .split(main_area);
+    let sidebar_area = horizontal[2];
+    let sidebar_split = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+        .split(sidebar_area);
+    Some(sidebar_split[1])
+}
+
+fn approval_action_at(
+    size: Rect,
+    approval: &ApprovalRequest,
+    column: u16,
+    row: u16,
+) -> Option<ApprovalAction> {
+    let area = ApprovalWidget::modal_area(size);
+    if !rect_contains(area, column, row) {
+        return None;
+    }
+
+    let params_count = approval
+        .parameters
+        .as_object()
+        .map(|obj: &serde_json::Map<String, serde_json::Value>| obj.len().min(4) as u16)
+        .unwrap_or(0);
+    let options_start_y = area.y + 1 + 3 + params_count;
+    let options = ApprovalWidget::options(approval.allow_always);
+    let index = row.checked_sub(options_start_y)? as usize;
+    options.get(index).copied()
+}
+
+fn thread_picker_index_at(
+    size: Rect,
+    picker: &crate::widgets::ThreadPickerState,
+    column: u16,
+    row: u16,
+) -> Option<usize> {
+    let area = ThreadPickerWidget::modal_area(size, picker.threads.len());
+    if !rect_contains(area, column, row) {
+        return None;
+    }
+
+    let inner = Rect::new(
+        area.x.saturating_add(1),
+        area.y.saturating_add(1),
+        area.width.saturating_sub(2),
+        area.height.saturating_sub(2),
+    );
+    if inner.height < 2 || row >= inner.y + inner.height.saturating_sub(1) {
+        return None;
+    }
+
+    let list_height = inner.height.saturating_sub(1) as usize;
+    let scroll_offset = if picker.selected >= list_height {
+        picker.selected - list_height + 1
+    } else {
+        0
+    };
+
+    let row_index = row.checked_sub(inner.y)? as usize;
+    let thread_index = scroll_offset + row_index;
+    picker.threads.get(thread_index)?;
+    Some(thread_index)
+}
+
+fn tool_detail_modal_area(size: Rect) -> Rect {
+    let width = (size.width * 3 / 4)
+        .max(40)
+        .min(size.width.saturating_sub(4));
+    let height = (size.height * 3 / 4)
+        .max(10)
+        .min(size.height.saturating_sub(4));
+    let x = (size.width.saturating_sub(width)) / 2;
+    let y = (size.height.saturating_sub(height)) / 2;
+    Rect::new(x, y, width, height)
+}
+
+fn tool_detail_inner_area(size: Rect) -> Rect {
+    Rect::new(
+        size.x.saturating_add(1),
+        size.y.saturating_add(1),
+        size.width.saturating_sub(2),
+        size.height.saturating_sub(2),
+    )
+}
+
+fn rect_contains(rect: Rect, column: u16, row: u16) -> bool {
+    column >= rect.x && column < rect.x + rect.width && row >= rect.y && row < rect.y + rect.height
+}
+
+fn clamp_point_to_rect(point: SelectionPoint, bounds: Rect) -> SelectionPoint {
+    let max_column = bounds.x + bounds.width.saturating_sub(1);
+    let max_row = bounds.y + bounds.height.saturating_sub(1);
+    SelectionPoint {
+        column: point.column.clamp(bounds.x, max_column),
+        row: point.row.clamp(bounds.y, max_row),
+    }
+}
+
+fn normalize_selection(selection: &TextSelection) -> (SelectionPoint, SelectionPoint) {
+    if selection.anchor.row < selection.focus.row
+        || (selection.anchor.row == selection.focus.row
+            && selection.anchor.column <= selection.focus.column)
+    {
+        (selection.anchor, selection.focus)
+    } else {
+        (selection.focus, selection.anchor)
+    }
+}
+
+fn extract_selected_text(snapshot: &ScreenSnapshot, selection: &TextSelection) -> String {
+    let (start, end) = normalize_selection(selection);
+    let mut lines = Vec::new();
+
+    for row in start.row..=end.row {
+        let start_col = if row == start.row {
+            start.column
+        } else {
+            selection.bounds.x
+        };
+        let end_col = if row == end.row {
+            end.column
+        } else {
+            selection.bounds.x + selection.bounds.width.saturating_sub(1)
+        };
+
+        let mut line = String::new();
+        for column in start_col..=end_col {
+            if let Some(symbol) = snapshot_symbol(snapshot, column, row) {
+                line.push_str(symbol);
+            }
+        }
+        lines.push(line.trim_end().to_string());
+    }
+
+    lines.join("\n").trim_end_matches('\n').to_string()
+}
+
+fn snapshot_symbol(snapshot: &ScreenSnapshot, column: u16, row: u16) -> Option<&str> {
+    if !rect_contains(snapshot.area, column, row) {
+        return None;
+    }
+
+    Some(snapshot.buffer[(column, row)].symbol())
+}
+
+/// Render a single frame.
+fn render_frame(
+    frame: &mut ratatui::Frame<'_>,
+    state: &mut AppState,
+    widgets: &BuiltinWidgets,
+    layout: &TuiLayout,
+) {
+    let size = frame.area();
+    let [
+        header_area,
+        tab_bar_area,
+        main_area,
+        input_area,
+        status_area,
+    ] = frame_sections(size, layout, state);
+
+    // Header
+    if layout.header.visible {
+        widgets
+            .header
+            .render(header_area, frame.buffer_mut(), state);
+    }
+
+    // Tab bar
+    widgets
+        .tab_bar
+        .render(tab_bar_area, frame.buffer_mut(), state);
+
+    // Track conversation area height for page-scroll calculations
+    state.conversation_height = main_area.height;
+
+    // Main area: conversation/logs | sidebar
+    match state.active_tab {
+        ActiveTab::Logs => {
+            // Logs tab takes the full main area (no sidebar)
+            widgets.logs.render(main_area, frame.buffer_mut(), state);
+        }
+        ActiveTab::Conversation => {
+            if state.sidebar_visible && main_area.width > 40 {
+                let sidebar_width =
+                    (main_area.width as u32 * layout.sidebar.effective_width() as u32 / 100) as u16;
+                let conversation_width = main_area.width.saturating_sub(sidebar_width + 1);
+
+                let horizontal = Layout::default()
+                    .direction(Direction::Horizontal)
+                    .constraints([
+                        Constraint::Length(conversation_width),
+                        Constraint::Length(1), // border
+                        Constraint::Length(sidebar_width),
+                    ])
+                    .split(main_area);
+
+                let conv_area = horizontal[0];
+                let border_area = horizontal[1];
+                let sidebar_area = horizontal[2];
+
+                widgets
+                    .conversation
+                    .render(conv_area, frame.buffer_mut(), state);
+
+                // Vertical border
+                render_vertical_border(frame, border_area, layout);
+
+                // Split sidebar into tool panel and thread list
+                let sidebar_split = Layout::default()
+                    .direction(Direction::Vertical)
+                    .constraints([Constraint::Percentage(50), Constraint::Percentage(50)])
+                    .split(sidebar_area);
+
+                widgets
+                    .tool_panel
+                    .render(sidebar_split[0], frame.buffer_mut(), state);
+                widgets
+                    .thread_list
+                    .render(sidebar_split[1], frame.buffer_mut(), state);
+            } else {
+                widgets
+                    .conversation
+                    .render(main_area, frame.buffer_mut(), state);
+            }
+        }
+    }
+
+    // Input area with top border
+    let input_split = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Length(1), Constraint::Min(1)])
+        .split(input_area);
+
+    render_horizontal_border(frame, input_split[0], layout);
+    widgets
+        .input_box
+        .render(input_split[1], frame.buffer_mut(), state);
+
+    // Status bar
+    if layout.status_bar.visible {
+        render_horizontal_border(frame, status_area, layout);
+        // Status bar renders on same line as border (overwriting)
+        widgets
+            .status_bar
+            .render(status_area, frame.buffer_mut(), state);
+    }
+
+    // Command palette overlay (above input area)
+    if state.command_palette.visible && !state.command_palette.filtered.is_empty() {
+        let palette_area = CommandPaletteWidget::palette_area(
+            size,
+            input_area,
+            state.command_palette.filtered.len(),
+        );
+        if palette_area.height > 0 {
+            widgets.command_palette.render_palette(
+                palette_area,
+                frame.buffer_mut(),
+                &state.command_palette,
+            );
+        }
+    }
+
+    if state.model_picker.visible {
+        let modal_area = ModelPickerWidget::modal_area(size, state.model_picker.filtered.len());
+        widgets
+            .model_picker
+            .render_picker(modal_area, frame.buffer_mut(), state);
+    }
+
+    // Approval modal (rendered on top of everything)
+    if state.pending_approval.is_some() {
+        let modal_area = ApprovalWidget::modal_area(size);
+        widgets
+            .approval
+            .render(modal_area, frame.buffer_mut(), state);
+    }
+
+    // Thread picker modal (/resume)
+    if let Some(ref picker) = state.pending_thread_picker {
+        let modal_area = crate::widgets::thread_picker::ThreadPickerWidget::modal_area(
+            size,
+            picker.threads.len(),
+        );
+        widgets
+            .thread_picker
+            .render_picker(modal_area, frame.buffer_mut(), state);
+    }
+
+    // Tool detail modal (Ctrl+E)
+    if state.tool_detail_modal.is_some() {
+        render_tool_detail_modal(frame, size, state, layout);
+    }
+
+    // Help overlay (F1)
+    if state.help_visible {
+        let help_area = HelpOverlayWidget::modal_area(size);
+        widgets.help.render(help_area, frame.buffer_mut(), state);
+    }
+
+    render_text_selection(frame, state, layout);
+
+    // Notification toasts (bottom-right, above status bar)
+    render_toasts(frame, size, state, layout);
+
+    capture_screen_snapshot(frame, state);
+}
+
+/// Check input text and update slash-command overlays.
+fn update_input_overlays_from_input(
+    input_box: &crate::widgets::input_box::InputBoxWidget,
+    state: &mut AppState,
+) {
+    let text = input_box.current_text();
+    let trimmed = text.trim();
+
+    if state.model_picker.has_models() && (trimmed == "/model" || trimmed.starts_with("/model ")) {
+        let filter = trimmed
+            .split_once(' ')
+            .map(|(_, rest)| rest.trim())
+            .unwrap_or("");
+        state.command_palette.close();
+        state.model_picker.open(filter);
+        return;
+    }
+
+    state.model_picker.close();
+
+    if trimmed.starts_with('/') && !trimmed.contains(' ') {
+        // Text after the leading '/'
+        let filter = &trimmed[1..];
+        state.command_palette.open(filter);
+    } else {
+        state.command_palette.close();
+    }
+}
+
+/// Render a vertical border line.
+fn render_vertical_border(frame: &mut ratatui::Frame<'_>, area: Rect, layout: &TuiLayout) {
+    let theme = layout.resolve_theme();
+    let border_style = theme.border_style();
+
+    for y in area.y..area.y + area.height {
+        if let Some(cell) = frame.buffer_mut().cell_mut((area.x, y)) {
+            cell.set_symbol("\u{2502}");
+            cell.set_style(border_style);
+        }
+    }
+}
+
+/// Render a horizontal border line.
+fn render_horizontal_border(frame: &mut ratatui::Frame<'_>, area: Rect, layout: &TuiLayout) {
+    let theme = layout.resolve_theme();
+    let border_style = theme.border_style();
+
+    for x in area.x..area.x + area.width {
+        if let Some(cell) = frame.buffer_mut().cell_mut((x, area.y)) {
+            cell.set_symbol("\u{2500}");
+            cell.set_style(border_style);
+        }
+    }
+}
+
+/// Render the tool detail modal (Ctrl+E).
+#[allow(clippy::cast_possible_truncation)]
+fn render_tool_detail_modal(
+    frame: &mut ratatui::Frame<'_>,
+    size: Rect,
+    state: &AppState,
+    layout: &TuiLayout,
+) {
+    use ratatui::style::Modifier;
+    use ratatui::text::Span;
+    use ratatui::widgets::{Block, Borders, Clear, Paragraph, Widget};
+
+    let Some(ref modal) = state.tool_detail_modal else {
+        return;
+    };
+    let theme = layout.resolve_theme();
+
+    let width = (size.width * 3 / 4)
+        .max(40)
+        .min(size.width.saturating_sub(4));
+    let height = (size.height * 3 / 4)
+        .max(10)
+        .min(size.height.saturating_sub(4));
+    let x = (size.width.saturating_sub(width)) / 2;
+    let y = (size.height.saturating_sub(height)) / 2;
+    let area = Rect::new(x, y, width, height);
+
+    Clear.render(area, frame.buffer_mut());
+
+    let title = format!(" {} ", modal.tool_name);
+    let block = Block::default()
+        .borders(Borders::ALL)
+        .border_style(theme.accent_style())
+        .title(Span::styled(
+            title,
+            theme.accent_style().add_modifier(Modifier::BOLD),
+        ));
+    let inner = block.inner(area);
+    block.render(area, frame.buffer_mut());
+
+    let lines = crate::render::render_markdown(&modal.content, inner.width as usize, &theme);
+
+    let paragraph = Paragraph::new(lines).scroll((modal.scroll, 0));
+    paragraph.render(inner, frame.buffer_mut());
+}
+
+/// Render notification toasts in the bottom-right corner.
+fn render_toasts(
+    frame: &mut ratatui::Frame<'_>,
+    size: Rect,
+    state: &mut AppState,
+    layout: &TuiLayout,
+) {
+    use ratatui::style::Modifier;
+    use ratatui::text::{Line, Span};
+    use ratatui::widgets::{Block, Borders, Clear, Paragraph, Widget};
+
+    // Prune expired toasts (older than 5 seconds)
+    let now = chrono::Utc::now();
+    state
+        .toasts
+        .retain(|t| now.signed_duration_since(t.created_at).num_seconds() < 5);
+
+    if state.toasts.is_empty() {
+        return;
+    }
+
+    let theme = layout.resolve_theme();
+    let max_toasts = 3usize;
+    let toast_width = 40u16.min(size.width.saturating_sub(2));
+
+    // Stack toasts from bottom up, above status bar
+    let start_y = size.height.saturating_sub(3); // above status bar + input
+    let visible_toasts = state.toasts.iter().rev().take(max_toasts);
+
+    for (i, toast) in visible_toasts.enumerate() {
+        let y = start_y.saturating_sub((i as u16) * 3);
+        let x = size.width.saturating_sub(toast_width + 1);
+        let area = Rect::new(x, y, toast_width, 3);
+
+        if area.y == 0 {
+            continue;
+        }
+
+        Clear.render(area, frame.buffer_mut());
+
+        let (icon, border_style) = match toast.kind {
+            ToastKind::Info => ("\u{2139}", theme.accent_style()),
+            ToastKind::Success => ("\u{2713}", theme.success_style()),
+            ToastKind::Warning => ("\u{26A0}", theme.warning_style()),
+            ToastKind::Error => ("\u{2717}", theme.error_style()),
+        };
+
+        let block = Block::default()
+            .borders(Borders::ALL)
+            .border_style(border_style);
+        let inner = block.inner(area);
+        block.render(area, frame.buffer_mut());
+
+        let msg_width = inner.width as usize;
+        let display_msg = if toast.message.len() > msg_width.saturating_sub(3) {
+            format!(
+                "{}...",
+                &toast.message[..msg_width.saturating_sub(6).min(toast.message.len())]
+            )
+        } else {
+            toast.message.clone()
+        };
+
+        let line = Line::from(vec![
+            Span::styled(
+                format!(" {icon} "),
+                border_style.add_modifier(Modifier::BOLD),
+            ),
+            Span::styled(
+                display_msg,
+                ratatui::style::Style::default().fg(theme.fg.to_color()),
+            ),
+        ]);
+        let paragraph = Paragraph::new(line);
+        paragraph.render(inner, frame.buffer_mut());
+    }
+}
+
+fn render_text_selection(frame: &mut ratatui::Frame<'_>, state: &AppState, layout: &TuiLayout) {
+    let Some(ref selection) = state.text_selection else {
+        return;
+    };
+
+    let (start, end) = normalize_selection(selection);
+    let theme = layout.resolve_theme();
+    let selection_style = ratatui::style::Style::default()
+        .bg(theme.accent.to_color())
+        .fg(ratatui::style::Color::Black);
+
+    for row in start.row..=end.row {
+        let start_col = if row == start.row {
+            start.column
+        } else {
+            selection.bounds.x
+        };
+        let end_col = if row == end.row {
+            end.column
+        } else {
+            selection.bounds.x + selection.bounds.width.saturating_sub(1)
+        };
+
+        for column in start_col..=end_col {
+            if let Some(cell) = frame.buffer_mut().cell_mut((column, row)) {
+                cell.set_style(selection_style);
+            }
+        }
+    }
+}
+
+fn capture_screen_snapshot(frame: &mut ratatui::Frame<'_>, state: &mut AppState) {
+    state.screen_snapshot = ScreenSnapshot {
+        area: frame.area(),
+        buffer: frame.buffer_mut().clone(),
+    };
+}
+
+/// Try to read an image from the system clipboard and return it as a PNG-encoded
+/// [`TuiAttachment`]. Returns `None` if the clipboard has no image data or if
+/// encoding fails.
+fn try_paste_clipboard_image(state: &AppState) -> Option<TuiAttachment> {
+    let mut clipboard = arboard::Clipboard::new().ok()?;
+    let img_data = clipboard.get_image().ok()?;
+
+    let png_bytes = encode_rgba_to_png(
+        &img_data.bytes,
+        img_data.width as u32,
+        img_data.height as u32,
+    )?;
+
+    let n = state.pending_attachments.len() + 1;
+    Some(TuiAttachment {
+        data: png_bytes,
+        mime_type: "image/png".to_string(),
+        label: format!("Image {n}"),
+    })
+}
+
+/// Encode raw RGBA pixel data to PNG. Returns `None` on invalid dimensions or
+/// encoding failure.
+fn encode_rgba_to_png(rgba: &[u8], width: u32, height: u32) -> Option<Vec<u8>> {
+    let expected_len = (width as usize)
+        .checked_mul(height as usize)?
+        .checked_mul(4)?;
+    if rgba.len() != expected_len {
+        return None;
+    }
+
+    let buf: image::ImageBuffer<image::Rgba<u8>, &[u8]> =
+        image::ImageBuffer::from_raw(width, height, rgba)?;
+    let mut png_bytes: Vec<u8> = Vec::new();
+    let mut cursor = std::io::Cursor::new(&mut png_bytes);
+    buf.write_to(&mut cursor, image::ImageFormat::Png).ok()?;
+    Some(png_bytes)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::event::{HistoryMessage, ThreadEntry};
+    use crate::widgets::approval::ApprovalWidget;
+    use crate::widgets::registry::create_default_widgets;
+    use crate::widgets::thread_picker::ThreadPickerWidget;
+    use crate::widgets::{ActiveTab, ApprovalRequest, MessageRole, ThreadStatus};
+    use ratatui::crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
+    use ratatui::layout::Rect;
+
+    async fn apply_event(state: &mut AppState, event: TuiEvent) {
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+        let (msg_tx, _msg_rx) = mpsc::channel(4);
+        handle_event(event, state, &mut widgets, &msg_tx, &layout).await;
+    }
+
+    async fn apply_event_and_take_messages(
+        state: &mut AppState,
+        event: TuiEvent,
+    ) -> Vec<TuiUserMessage> {
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+        let (msg_tx, mut msg_rx) = mpsc::channel(4);
+        handle_event(event, state, &mut widgets, &msg_tx, &layout).await;
+
+        let mut messages = Vec::new();
+        while let Ok(message) = msg_rx.try_recv() {
+            messages.push(message);
+        }
+        messages
+    }
+
+    fn make_snapshot(width: u16, height: u16) -> ScreenSnapshot {
+        let area = Rect::new(0, 0, width, height);
+        ScreenSnapshot {
+            area,
+            buffer: ratatui::buffer::Buffer::empty(area),
+        }
+    }
+
+    fn write_snapshot_text(snapshot: &mut ScreenSnapshot, column: u16, row: u16, text: &str) {
+        for (offset, ch) in text.chars().enumerate() {
+            snapshot.buffer[(column + offset as u16, row)].set_symbol(&ch.to_string());
+        }
+    }
+
+    #[test]
+    fn encode_rgba_to_png_valid() {
+        // 2x2 red image
+        let rgba = vec![
+            255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 255, 255,
+        ];
+        let png = encode_rgba_to_png(&rgba, 2, 2);
+        assert!(png.is_some());
+        let bytes = png.unwrap();
+        // PNG signature starts with 0x89 'P' 'N' 'G'
+        assert!(bytes.len() > 8);
+        assert_eq!(&bytes[..4], &[0x89, b'P', b'N', b'G']);
+    }
+
+    #[test]
+    fn encode_rgba_to_png_bad_dimensions() {
+        let rgba = vec![0u8; 16]; // 4 pixels
+        // Claim 3x2 = 6 pixels, but only 4 are provided
+        let png = encode_rgba_to_png(&rgba, 3, 2);
+        assert!(png.is_none());
+    }
+
+    #[test]
+    fn encode_rgba_to_png_zero_size() {
+        // 0x0 image: the image crate rejects zero-dimension buffers
+        let png = encode_rgba_to_png(&[], 0, 0);
+        assert!(png.is_none());
+    }
+
+    #[tokio::test]
+    async fn response_appends_after_existing_assistant_message_when_not_streaming() {
+        let mut state = AppState::default();
+        state.messages.push(ChatMessage {
+            role: MessageRole::Assistant,
+            content: "first reply".to_string(),
+            timestamp: chrono::Utc::now(),
+            cost_summary: None,
+        });
+
+        apply_event(
+            &mut state,
+            TuiEvent::Response {
+                content: "background notification".to_string(),
+                thread_id: None,
+            },
+        )
+        .await;
+
+        assert_eq!(state.messages.len(), 2);
+        assert_eq!(state.messages[1].content, "background notification");
+    }
+
+    #[tokio::test]
+    async fn response_tracks_active_thread_id() {
+        let mut state = AppState::default();
+
+        apply_event(
+            &mut state,
+            TuiEvent::Response {
+                content: "ok".to_string(),
+                thread_id: Some("thread-42".to_string()),
+            },
+        )
+        .await;
+
+        assert_eq!(state.current_thread_id.as_deref(), Some("thread-42"));
+    }
+
+    #[tokio::test]
+    async fn thread_list_only_populates_picker() {
+        let mut state = AppState::default();
+
+        apply_event(
+            &mut state,
+            TuiEvent::ThreadList {
+                threads: vec![ThreadEntry {
+                    id: "thread-1".to_string(),
+                    title: Some("Bug bash".to_string()),
+                    message_count: 3,
+                    last_activity: "2026-04-03 12:00".to_string(),
+                    channel: "repl".to_string(),
+                }],
+            },
+        )
+        .await;
+
+        // ThreadList no longer populates the sidebar — only the picker.
+        assert!(state.engine_threads.is_empty());
+        assert!(state.pending_thread_picker.is_some());
+        assert_eq!(
+            state.pending_thread_picker.as_ref().unwrap().threads.len(),
+            1
+        );
+    }
+
+    #[tokio::test]
+    async fn engine_thread_list_updates_sidebar() {
+        let mut state = AppState::default();
+
+        apply_event(
+            &mut state,
+            TuiEvent::EngineThreadList {
+                threads: vec![crate::event::EngineThreadEntry {
+                    id: "eng-1".to_string(),
+                    goal: "fix login".to_string(),
+                    thread_type: "Foreground".to_string(),
+                    state: "Running".to_string(),
+                    step_count: 3,
+                    total_tokens: 800,
+                    created_at: chrono::Utc::now().to_rfc3339(),
+                    updated_at: chrono::Utc::now().to_rfc3339(),
+                }],
+            },
+        )
+        .await;
+
+        assert_eq!(state.engine_threads.len(), 1);
+        assert_eq!(state.engine_threads[0].goal, "fix login");
+        assert_eq!(state.engine_threads[0].thread_type, "Foreground");
+        assert_eq!(state.engine_threads[0].status, ThreadStatus::Active);
+    }
+
+    #[tokio::test]
+    async fn engine_thread_detail_opens_modal() {
+        let mut state = AppState::default();
+
+        apply_event(
+            &mut state,
+            TuiEvent::EngineThreadDetail {
+                detail: crate::event::EngineThreadDetailEntry {
+                    id: "eng-1".to_string(),
+                    goal: "Send the top three Hacker News stories".to_string(),
+                    thread_type: "Mission".to_string(),
+                    state: "Running".to_string(),
+                    project_id: "proj-1".to_string(),
+                    parent_id: None,
+                    step_count: 7,
+                    total_tokens: 2_048,
+                    created_at: chrono::Utc::now().to_rfc3339(),
+                    updated_at: chrono::Utc::now().to_rfc3339(),
+                    max_iterations: 24,
+                    completed_at: None,
+                    total_cost_usd: 0.1234,
+                    messages: vec![crate::event::EngineThreadMessageEntry {
+                        role: "Assistant".to_string(),
+                        content: "Fetching the latest stories.".to_string(),
+                        timestamp: chrono::Utc::now().to_rfc3339(),
+                    }],
+                },
+            },
+        )
+        .await;
+
+        let modal = state
+            .tool_detail_modal
+            .as_ref()
+            .expect("thread detail modal should open");
+        assert_eq!(modal.tool_name, "Thread Mission");
+        assert!(modal.content.contains("Goal"));
+        assert!(
+            modal
+                .content
+                .contains("Send the top three Hacker News stories")
+        );
+        assert!(modal.content.contains("Messages (1)"));
+        assert!(modal.content.contains("Fetching the latest stories."));
+    }
+
+    #[tokio::test]
+    async fn empty_thread_list_clears_picker() {
+        let mut state = AppState::default();
+
+        apply_event(
+            &mut state,
+            TuiEvent::ThreadList {
+                threads: vec![ThreadEntry {
+                    id: "thread-1".to_string(),
+                    title: Some("Bug bash".to_string()),
+                    message_count: 3,
+                    last_activity: "2026-04-03 12:00".to_string(),
+                    channel: "repl".to_string(),
+                }],
+            },
+        )
+        .await;
+        assert!(state.pending_thread_picker.is_some());
+
+        apply_event(&mut state, TuiEvent::ThreadList { threads: vec![] }).await;
+
+        assert!(state.pending_thread_picker.is_none());
+    }
+
+    #[tokio::test]
+    async fn job_events_do_not_populate_thread_sidebar() {
+        let mut state = AppState::default();
+
+        apply_event(
+            &mut state,
+            TuiEvent::JobStarted {
+                job_id: "job-1".to_string(),
+                title: "Backfill".to_string(),
+            },
+        )
+        .await;
+
+        assert_eq!(state.jobs.len(), 1);
+        assert!(state.threads.is_empty());
+    }
+
+    #[tokio::test]
+    async fn mouse_scroll_moves_thread_picker_selection() {
+        let mut state = AppState {
+            pending_thread_picker: Some(crate::widgets::ThreadPickerState {
+                threads: vec![
+                    ThreadEntry {
+                        id: "thread-1".to_string(),
+                        title: Some("Bug bash".to_string()),
+                        message_count: 3,
+                        last_activity: "2026-04-03 12:00".to_string(),
+                        channel: "repl".to_string(),
+                    },
+                    ThreadEntry {
+                        id: "thread-2".to_string(),
+                        title: Some("Release prep".to_string()),
+                        message_count: 8,
+                        last_activity: "2026-04-03 13:00".to_string(),
+                        channel: "repl".to_string(),
+                    },
+                ],
+                selected: 0,
+            }),
+            ..Default::default()
+        };
+
+        apply_event(&mut state, TuiEvent::MouseScroll(3)).await;
+
+        assert_eq!(
+            state
+                .pending_thread_picker
+                .as_ref()
+                .map(|picker| picker.selected),
+            Some(1)
+        );
+    }
+
+    #[tokio::test]
+    async fn mouse_click_switches_active_tab() {
+        let mut state = AppState::default();
+
+        apply_event(&mut state, TuiEvent::MouseClick { column: 9, row: 0 }).await;
+
+        assert_eq!(state.active_tab, ActiveTab::Logs);
+    }
+
+    #[tokio::test]
+    async fn mouse_click_engine_thread_row_requests_detail_modal_data() {
+        let now = chrono::Utc::now();
+        let mut state = AppState {
+            engine_threads: vec![EngineThreadInfo {
+                id: "eng-1".to_string(),
+                goal: "Check Hacker News hourly".to_string(),
+                thread_type: "Mission".to_string(),
+                status: ThreadStatus::Active,
+                step_count: 5,
+                total_tokens: 4_096,
+                started_at: Some(now - chrono::Duration::minutes(9)),
+                updated_at: Some(now),
+            }],
+            ..Default::default()
+        };
+
+        let layout = TuiLayout::default();
+        let area = thread_list_sidebar_area(Rect::new(0, 0, 80, 24), &layout, &state)
+            .expect("thread list area should exist");
+        let click = (area.y..area.y + area.height)
+            .find_map(|row| {
+                (area.x..area.x + area.width).find_map(|column| {
+                    (engine_thread_index_at(area, &state, column, row) == Some(0))
+                        .then_some((column, row))
+                })
+            })
+            .expect("expected a clickable engine thread row");
+
+        let messages = apply_event_and_take_messages(
+            &mut state,
+            TuiEvent::MouseClick {
+                column: click.0,
+                row: click.1,
+            },
+        )
+        .await;
+
+        assert_eq!(messages.len(), 1);
+        assert!(messages[0].text.is_empty());
+        assert!(messages[0].thread_id.is_none());
+        match &messages[0].ui_action {
+            Some(crate::event::TuiUiAction::OpenEngineThreadDetail { thread_id }) => {
+                assert_eq!(thread_id, "eng-1");
+            }
+            other => panic!("expected engine thread detail action, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn mouse_click_approval_option_submits_response() {
+        let mut state = AppState {
+            pending_approval: Some(ApprovalRequest {
+                request_id: "req-1".to_string(),
+                tool_name: "shell".to_string(),
+                description: "Run a command".to_string(),
+                parameters: serde_json::json!({}),
+                allow_always: false,
+                selected: 0,
+            }),
+            ..Default::default()
+        };
+
+        let area = ApprovalWidget::modal_area(Rect::new(0, 0, 80, 24));
+        let messages = apply_event_and_take_messages(
+            &mut state,
+            TuiEvent::MouseClick {
+                column: area.x + 3,
+                row: area.y + 5,
+            },
+        )
+        .await;
+
+        assert!(state.pending_approval.is_none());
+        assert_eq!(messages.len(), 1);
+        assert_eq!(messages[0].text, "n");
+    }
+
+    #[tokio::test]
+    async fn conversation_history_restores_pending_approval() {
+        let mut state = AppState {
+            pending_approval: Some(ApprovalRequest {
+                request_id: "stale".to_string(),
+                tool_name: "old-tool".to_string(),
+                description: "stale approval".to_string(),
+                parameters: serde_json::json!({"old": true}),
+                allow_always: false,
+                selected: 2,
+            }),
+            ..Default::default()
+        };
+
+        apply_event(
+            &mut state,
+            TuiEvent::ConversationHistory {
+                thread_id: "thread-1".to_string(),
+                messages: vec![HistoryMessage {
+                    role: "assistant".to_string(),
+                    content: "Waiting on approval".to_string(),
+                    timestamp: chrono::Utc::now(),
+                }],
+                pending_approval: Some(crate::event::HistoryApprovalRequest {
+                    request_id: "req-1".to_string(),
+                    tool_name: "shell".to_string(),
+                    description: "Run a command".to_string(),
+                    parameters: serde_json::json!({"command": "[REDACTED]"}),
+                    allow_always: true,
+                }),
+            },
+        )
+        .await;
+
+        let approval = state
+            .pending_approval
+            .as_ref()
+            .expect("pending approval should be restored");
+        assert_eq!(approval.request_id, "req-1");
+        assert_eq!(approval.tool_name, "shell");
+        assert_eq!(approval.description, "Run a command");
+        assert_eq!(
+            approval.parameters,
+            serde_json::json!({"command": "[REDACTED]"})
+        );
+        assert!(approval.allow_always);
+        assert_eq!(approval.selected, 0);
+    }
+
+    #[tokio::test]
+    async fn mouse_click_thread_picker_row_resumes_thread() {
+        let mut state = AppState {
+            pending_thread_picker: Some(crate::widgets::ThreadPickerState {
+                threads: vec![
+                    ThreadEntry {
+                        id: "thread-1".to_string(),
+                        title: Some("Bug bash".to_string()),
+                        message_count: 3,
+                        last_activity: "2026-04-03 12:00".to_string(),
+                        channel: "repl".to_string(),
+                    },
+                    ThreadEntry {
+                        id: "thread-2".to_string(),
+                        title: Some("Release prep".to_string()),
+                        message_count: 8,
+                        last_activity: "2026-04-03 13:00".to_string(),
+                        channel: "repl".to_string(),
+                    },
+                ],
+                selected: 0,
+            }),
+            ..Default::default()
+        };
+
+        let area = ThreadPickerWidget::modal_area(Rect::new(0, 0, 80, 24), 2);
+        let messages = apply_event_and_take_messages(
+            &mut state,
+            TuiEvent::MouseClick {
+                column: area.x + 3,
+                row: area.y + 2,
+            },
+        )
+        .await;
+
+        assert!(state.pending_thread_picker.is_none());
+        assert_eq!(messages.len(), 1);
+        assert_eq!(messages[0].text, "/thread thread-2");
+        assert!(messages[0].thread_id.is_none());
+        assert_eq!(state.current_thread_id.as_deref(), Some("thread-2"));
+    }
+
+    #[tokio::test]
+    async fn mouse_drag_and_release_copies_selected_text() {
+        let mut state = AppState {
+            active_tab: ActiveTab::Logs,
+            screen_snapshot: make_snapshot(80, 24),
+            ..Default::default()
+        };
+        write_snapshot_text(&mut state.screen_snapshot, 1, 2, "hello world");
+        take_last_copied_text_for_test();
+
+        apply_event(&mut state, TuiEvent::MouseClick { column: 1, row: 2 }).await;
+        apply_event(&mut state, TuiEvent::MouseDrag { column: 5, row: 2 }).await;
+        apply_event(&mut state, TuiEvent::MouseRelease { column: 5, row: 2 }).await;
+
+        assert_eq!(take_last_copied_text_for_test().as_deref(), Some("hello"));
+        assert!(state.text_selection.is_some());
+    }
+
+    #[test]
+    fn extract_selected_text_preserves_multiline_range() {
+        let mut snapshot = make_snapshot(20, 4);
+        write_snapshot_text(&mut snapshot, 0, 1, "first line");
+        write_snapshot_text(&mut snapshot, 0, 2, "second line");
+
+        let selection = TextSelection {
+            anchor: SelectionPoint { column: 2, row: 1 },
+            focus: SelectionPoint { column: 5, row: 2 },
+            bounds: Rect::new(0, 1, 20, 2),
+        };
+
+        assert_eq!(
+            extract_selected_text(&snapshot, &selection),
+            "rst line\nsecond"
+        );
+    }
+
+    #[test]
+    fn parse_engine_thread_timestamp_accepts_rfc3339_and_legacy_format() {
+        let rfc3339 =
+            parse_engine_thread_timestamp("2026-04-06T05:56:16Z", "created_at", "thread-1");
+        let legacy = parse_engine_thread_timestamp("2026-04-06 05:56", "created_at", "thread-1");
+
+        assert_eq!(
+            rfc3339,
+            Some(
+                chrono::DateTime::parse_from_rfc3339("2026-04-06T05:56:16Z")
+                    .expect("valid rfc3339")
+                    .with_timezone(&chrono::Utc)
+            )
+        );
+        assert_eq!(
+            legacy,
+            Some(
+                chrono::NaiveDateTime::parse_from_str("2026-04-06 05:56", "%Y-%m-%d %H:%M")
+                    .expect("valid legacy timestamp")
+                    .and_utc()
+            )
+        );
+    }
+
+    #[test]
+    fn parse_engine_thread_timestamp_returns_none_for_invalid_input() {
+        assert_eq!(
+            parse_engine_thread_timestamp("not-a-timestamp", "created_at", "thread-1"),
+            None
+        );
+    }
+
+    async fn apply_event_with_widgets(
+        state: &mut AppState,
+        widgets: &mut BuiltinWidgets,
+        event: TuiEvent,
+    ) {
+        let layout = TuiLayout::default();
+        let (msg_tx, _msg_rx) = mpsc::channel(4);
+        handle_event(event, state, widgets, &msg_tx, &layout).await;
+    }
+
+    #[tokio::test]
+    async fn up_arrow_recalls_latest_history_from_input_bar() {
+        let mut state = AppState {
+            input_history: vec!["first prompt".to_string(), "latest prompt".to_string()],
+            ..Default::default()
+        };
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+
+        apply_event_with_widgets(
+            &mut state,
+            &mut widgets,
+            TuiEvent::Key(KeyEvent::new(KeyCode::Up, KeyModifiers::NONE)),
+        )
+        .await;
+
+        assert_eq!(widgets.input_box.current_text(), "latest prompt");
+        assert_eq!(state.history_index, Some(1));
+    }
+
+    #[tokio::test]
+    async fn up_arrow_inside_multiline_draft_keeps_editing_instead_of_history() {
+        let mut state = AppState {
+            input_history: vec!["latest prompt".to_string()],
+            ..Default::default()
+        };
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+        widgets.input_box.set_text("first line\nsecond line");
+        widgets
+            .input_box
+            .handle_key(KeyEvent::new(KeyCode::Down, KeyModifiers::NONE), &mut state);
+
+        apply_event_with_widgets(
+            &mut state,
+            &mut widgets,
+            TuiEvent::Key(KeyEvent::new(KeyCode::Up, KeyModifiers::NONE)),
+        )
+        .await;
+
+        assert_eq!(widgets.input_box.current_text(), "first line\nsecond line");
+        assert_eq!(state.history_index, None);
+    }
+
+    #[tokio::test]
+    async fn down_arrow_restores_draft_after_history_recall() {
+        let mut state = AppState {
+            input_history: vec!["older prompt".to_string()],
+            ..Default::default()
+        };
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+        widgets.input_box.set_text("draft prompt");
+
+        apply_event_with_widgets(
+            &mut state,
+            &mut widgets,
+            TuiEvent::Key(KeyEvent::new(KeyCode::Char('p'), KeyModifiers::CONTROL)),
+        )
+        .await;
+        apply_event_with_widgets(
+            &mut state,
+            &mut widgets,
+            TuiEvent::Key(KeyEvent::new(KeyCode::Down, KeyModifiers::NONE)),
+        )
+        .await;
+
+        assert_eq!(widgets.input_box.current_text(), "draft prompt");
+        assert_eq!(state.history_index, None);
+    }
+
+    #[test]
+    fn slash_model_opens_model_picker_instead_of_command_palette() {
+        let mut state = AppState::default();
+        state.model_picker.set_models(vec![
+            "gpt-4o".to_string(),
+            "gpt-5".to_string(),
+            "claude-sonnet-4-6".to_string(),
+        ]);
+
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+        widgets.input_box.set_text("/model gpt");
+
+        update_input_overlays_from_input(&widgets.input_box, &mut state);
+
+        assert!(state.model_picker.visible);
+        assert_eq!(state.model_picker.filter, "gpt");
+        assert_eq!(state.model_picker.filtered.len(), 2);
+        assert!(!state.command_palette.visible);
+    }
+
+    #[tokio::test]
+    async fn enter_on_model_picker_submits_selected_model_command() {
+        let mut state = AppState {
+            model: "gpt-4o".to_string(),
+            ..Default::default()
+        };
+        state
+            .model_picker
+            .set_models(vec!["gpt-4o".to_string(), "gpt-5".to_string()]);
+
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+        let (msg_tx, mut msg_rx) = mpsc::channel(4);
+
+        widgets.input_box.set_text("/model");
+        update_input_overlays_from_input(&widgets.input_box, &mut state);
+
+        handle_event(
+            TuiEvent::Key(KeyEvent::new(KeyCode::Down, KeyModifiers::NONE)),
+            &mut state,
+            &mut widgets,
+            &msg_tx,
+            &layout,
+        )
+        .await;
+        handle_event(
+            TuiEvent::Key(KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE)),
+            &mut state,
+            &mut widgets,
+            &msg_tx,
+            &layout,
+        )
+        .await;
+
+        let message = msg_rx.try_recv().expect("model command sent");
+        assert_eq!(message.text, "/model gpt-5");
+        assert!(message.thread_id.is_none());
+        assert_eq!(state.model, "gpt-5");
+        assert!(!state.model_picker.visible);
+    }
+
+    #[tokio::test]
+    async fn submit_uses_current_thread_scope() {
+        let mut state = AppState {
+            current_thread_id: Some("thread-123".to_string()),
+            ..Default::default()
+        };
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+        let (msg_tx, mut msg_rx) = mpsc::channel(4);
+
+        widgets.input_box.set_text("run it");
+
+        handle_event(
+            TuiEvent::Key(KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE)),
+            &mut state,
+            &mut widgets,
+            &msg_tx,
+            &layout,
+        )
+        .await;
+
+        let message = msg_rx.try_recv().expect("message sent");
+        assert_eq!(message.text, "run it");
+        assert_eq!(message.thread_id.as_deref(), Some("thread-123"));
+    }
+
+    #[tokio::test]
+    async fn slash_model_without_available_models_submits_on_enter() {
+        let mut state = AppState::default();
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+        let (msg_tx, mut msg_rx) = mpsc::channel(4);
+
+        widgets.input_box.set_text("/model");
+        update_input_overlays_from_input(&widgets.input_box, &mut state);
+        assert!(state.command_palette.visible);
+        assert!(!state.model_picker.visible);
+
+        handle_event(
+            TuiEvent::Key(KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE)),
+            &mut state,
+            &mut widgets,
+            &msg_tx,
+            &layout,
+        )
+        .await;
+
+        let message = msg_rx.try_recv().expect("/model command sent");
+        assert_eq!(message.text, "/model");
+        assert!(state.awaiting_model_list);
+        assert!(!state.command_palette.visible);
+        assert!(widgets.input_box.is_empty());
+    }
+
+    #[tokio::test]
+    async fn slash_palette_model_selection_opens_model_picker_when_models_exist() {
+        let mut state = AppState::default();
+        state
+            .model_picker
+            .set_models(vec!["gpt-4o".to_string(), "gpt-5".to_string()]);
+
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+        let (msg_tx, _msg_rx) = mpsc::channel(4);
+
+        widgets.input_box.set_text("/mo");
+        update_input_overlays_from_input(&widgets.input_box, &mut state);
+        assert!(state.command_palette.visible);
+
+        handle_event(
+            TuiEvent::Key(KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE)),
+            &mut state,
+            &mut widgets,
+            &msg_tx,
+            &layout,
+        )
+        .await;
+
+        assert_eq!(widgets.input_box.current_text(), "/model ");
+        assert!(state.model_picker.visible);
+        assert!(!state.command_palette.visible);
+    }
+
+    #[test]
+    fn parse_model_response_extracts_active_and_available_models() {
+        let parsed = parse_model_list_response(
+            "Active model: gpt-5\n\nAvailable models:\n  gpt-5 (active)\n  gpt-4o\n\nUse /model <name> to switch.",
+        )
+        .expect("parsed model response");
+
+        assert_eq!(parsed.0, "gpt-5");
+        assert_eq!(parsed.1, vec!["gpt-5".to_string(), "gpt-4o".to_string()]);
+    }
+
+    #[tokio::test]
+    async fn model_response_hydrates_picker_after_first_fetch() {
+        let mut state = AppState {
+            awaiting_model_list: true,
+            ..Default::default()
+        };
+        let layout = TuiLayout::default();
+        let mut widgets = create_default_widgets(&layout);
+
+        handle_event(
+            TuiEvent::Response {
+                content: "Active model: gpt-5\n\nAvailable models:\n  gpt-5 (active)\n  gpt-4o\n\nUse /model <name> to switch.".to_string(),
+                thread_id: None,
+            },
+            &mut state,
+            &mut widgets,
+            &mpsc::channel(1).0,
+            &layout,
+        )
+        .await;
+
+        assert_eq!(state.model, "gpt-5");
+        assert_eq!(widgets.input_box.current_text(), "/model ");
+        assert!(state.model_picker.visible);
+        assert_eq!(state.model_picker.filtered.len(), 2);
+        assert!(!state.awaiting_model_list);
+    }
+
+    #[tokio::test]
+    async fn tool_updates_use_call_id_to_disambiguate_duplicate_names() {
+        let mut state = AppState::default();
+
+        apply_event(
+            &mut state,
+            TuiEvent::ToolStarted {
+                name: "http".to_string(),
+                detail: Some("first".to_string()),
+                call_id: Some("call-1".to_string()),
+            },
+        )
+        .await;
+        apply_event(
+            &mut state,
+            TuiEvent::ToolStarted {
+                name: "http".to_string(),
+                detail: Some("second".to_string()),
+                call_id: Some("call-2".to_string()),
+            },
+        )
+        .await;
+        apply_event(
+            &mut state,
+            TuiEvent::ToolResult {
+                name: "http".to_string(),
+                preview: "preview-2".to_string(),
+                call_id: Some("call-2".to_string()),
+            },
+        )
+        .await;
+        apply_event(
+            &mut state,
+            TuiEvent::ToolCompleted {
+                name: "http".to_string(),
+                success: true,
+                error: None,
+                call_id: Some("call-2".to_string()),
+            },
+        )
+        .await;
+
+        assert_eq!(state.active_tools.len(), 1);
+        assert_eq!(state.active_tools[0].call_id.as_deref(), Some("call-1"));
+        assert_eq!(state.recent_tools.len(), 1);
+        assert_eq!(state.recent_tools[0].call_id.as_deref(), Some("call-2"));
+        assert_eq!(state.recent_tools[0].detail.as_deref(), Some("second"));
+        assert_eq!(
+            state.recent_tools[0].result_preview.as_deref(),
+            Some("preview-2")
+        );
+    }
+}
diff --git a/crates/ironclaw_tui/src/event.rs b/crates/ironclaw_tui/src/event.rs
new file mode 100644
index 00000000000..f6c28b59a4a
--- /dev/null
+++ b/crates/ironclaw_tui/src/event.rs
@@ -0,0 +1,356 @@
+//! Unified event type for the TUI event loop.
+//!
+//! All external inputs (keyboard, terminal resize, engine status updates,
+//! agent responses) are funnelled into a single `TuiEvent` enum so the
+//! main loop can `select!` on one receiver.
+
+use std::collections::VecDeque;
+
+use ratatui::crossterm::event::KeyEvent;
+
+/// A single log entry displayed in the TUI Logs tab.
+///
+/// This mirrors `LogEntry` from the main crate but is self-contained
+/// so `ironclaw_tui` has no dependency on the main crate.
+#[derive(Debug, Clone)]
+pub struct TuiLogEntry {
+    pub level: String,
+    pub target: String,
+    pub message: String,
+    pub timestamp: String,
+}
+
+/// Ring buffer of log entries with a fixed capacity.
+#[derive(Debug, Clone)]
+pub struct LogRingBuffer {
+    entries: VecDeque<TuiLogEntry>,
+    capacity: usize,
+}
+
+impl LogRingBuffer {
+    pub fn new(capacity: usize) -> Self {
+        Self {
+            entries: VecDeque::with_capacity(capacity),
+            capacity,
+        }
+    }
+
+    pub fn push(&mut self, entry: TuiLogEntry) {
+        if self.entries.len() >= self.capacity {
+            self.entries.pop_front();
+        }
+        self.entries.push_back(entry);
+    }
+
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = &TuiLogEntry> {
+        self.entries.iter()
+    }
+}
+
+/// A single image or file attachment pasted into the TUI.
+#[derive(Debug, Clone)]
+pub struct TuiAttachment {
+    /// Raw file bytes (e.g. PNG-encoded image).
+    pub data: Vec<u8>,
+    /// MIME type (e.g. "image/png").
+    pub mime_type: String,
+    /// Display label shown in the input area (e.g. "Image 1").
+    pub label: String,
+}
+
+/// A user message with optional attachments, sent from the TUI to the channel bridge.
+#[derive(Debug, Clone)]
+pub struct TuiUserMessage {
+    /// The text content of the message.
+    pub text: String,
+    /// Pasted image attachments.
+    pub attachments: Vec<TuiAttachment>,
+    /// Active thread scope for this message, if the TUI has one selected.
+    pub thread_id: Option<String>,
+    /// Non-chat UI action to run through the bridge.
+    pub ui_action: Option<TuiUiAction>,
+}
+
+/// Out-of-band UI actions emitted by the TUI.
+#[derive(Debug, Clone)]
+pub enum TuiUiAction {
+    /// Load and show engine thread detail without sending chat text.
+    OpenEngineThreadDetail { thread_id: String },
+}
+
+impl TuiUserMessage {
+    /// Create a text-only message with no attachments.
+    pub fn text_only(text: impl Into<String>) -> Self {
+        Self {
+            text: text.into(),
+            attachments: Vec::new(),
+            thread_id: None,
+            ui_action: None,
+        }
+    }
+
+    /// Attach a thread scope to this message.
+    pub fn with_thread_id(mut self, thread_id: Option<String>) -> Self {
+        self.thread_id = thread_id;
+        self
+    }
+
+    /// Request detail for an engine thread from the TUI bridge.
+    pub fn open_engine_thread_detail(thread_id: impl Into<String>) -> Self {
+        Self {
+            text: String::new(),
+            attachments: Vec::new(),
+            thread_id: None,
+            ui_action: Some(TuiUiAction::OpenEngineThreadDetail {
+                thread_id: thread_id.into(),
+            }),
+        }
+    }
+}
+
+/// A past conversation entry for the resume/thread picker.
+#[derive(Debug, Clone)]
+pub struct ThreadEntry {
+    pub id: String,
+    pub title: Option<String>,
+    pub message_count: i64,
+    pub last_activity: String,
+    pub channel: String,
+}
+
+/// A single message from conversation history, for hydrating the TUI on thread resume.
+#[derive(Debug, Clone)]
+pub struct HistoryMessage {
+    pub role: String,
+    pub content: String,
+    pub timestamp: chrono::DateTime<chrono::Utc>,
+}
+
+/// A pending approval restored alongside conversation history.
+#[derive(Debug, Clone)]
+pub struct HistoryApprovalRequest {
+    pub request_id: String,
+    pub tool_name: String,
+    pub description: String,
+    pub parameters: serde_json::Value,
+    pub allow_always: bool,
+}
+
+/// An engine v2 thread entry for the activity sidebar.
+#[derive(Debug, Clone)]
+pub struct EngineThreadEntry {
+    pub id: String,
+    pub goal: String,
+    /// "Foreground", "Research", or "Mission".
+    pub thread_type: String,
+    /// Engine ThreadState as a string (e.g. "Running", "Waiting").
+    pub state: String,
+    pub step_count: usize,
+    pub total_tokens: u64,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+/// A single message in engine thread detail.
+#[derive(Debug, Clone)]
+pub struct EngineThreadMessageEntry {
+    pub role: String,
+    pub content: String,
+    pub timestamp: String,
+}
+
+/// Full engine thread detail for the sidebar modal.
+#[derive(Debug, Clone)]
+pub struct EngineThreadDetailEntry {
+    pub id: String,
+    pub goal: String,
+    pub thread_type: String,
+    pub state: String,
+    pub project_id: String,
+    pub parent_id: Option<String>,
+    pub step_count: usize,
+    pub total_tokens: u64,
+    pub created_at: String,
+    pub updated_at: String,
+    pub max_iterations: usize,
+    pub completed_at: Option<String>,
+    pub total_cost_usd: f64,
+    pub messages: Vec<EngineThreadMessageEntry>,
+}
+
+/// Events consumed by the TUI run loop.
+#[derive(Debug, Clone)]
+pub enum TuiEvent {
+    /// A keyboard event from crossterm.
+    Key(KeyEvent),
+
+    /// Bracketed paste text from the terminal.
+    Paste(String),
+
+    /// Terminal was resized to (cols, rows).
+    Resize(u16, u16),
+
+    /// Mouse scroll (delta: negative = up, positive = down).
+    MouseScroll(i16),
+
+    /// Left mouse click at a terminal cell coordinate.
+    MouseClick { column: u16, row: u16 },
+
+    /// Mouse drag with the left button held.
+    MouseDrag { column: u16, row: u16 },
+
+    /// Left mouse button release.
+    MouseRelease { column: u16, row: u16 },
+
+    /// Periodic render tick (~30 fps).
+    Tick,
+
+    /// Agent is thinking / processing.
+    Thinking(String),
+
+    /// Tool execution started.
+    ToolStarted {
+        name: String,
+        detail: Option<String>,
+        call_id: Option<String>,
+    },
+
+    /// Tool execution completed.
+    ToolCompleted {
+        name: String,
+        success: bool,
+        error: Option<String>,
+        call_id: Option<String>,
+    },
+
+    /// Brief preview of tool output.
+    ToolResult {
+        name: String,
+        preview: String,
+        call_id: Option<String>,
+    },
+
+    /// Streaming text chunk from the LLM.
+    StreamChunk(String),
+
+    /// General status message.
+    Status(String),
+
+    /// Full agent response ready to display.
+    Response {
+        content: String,
+        thread_id: Option<String>,
+    },
+
+    /// A sandbox job started.
+    JobStarted { job_id: String, title: String },
+
+    /// A sandbox job's status changed.
+    JobStatus { job_id: String, status: String },
+
+    /// A sandbox job completed with final result.
+    JobResult { job_id: String, status: String },
+
+    /// A routine was created, updated, or deleted.
+    RoutineUpdate {
+        id: String,
+        name: String,
+        trigger_type: String,
+        enabled: bool,
+        last_run: Option<String>,
+        next_fire: Option<String>,
+    },
+
+    /// Tool requires user approval.
+    ApprovalNeeded {
+        request_id: String,
+        tool_name: String,
+        description: String,
+        parameters: serde_json::Value,
+        allow_always: bool,
+    },
+
+    /// Extension needs user authentication.
+    AuthRequired {
+        extension_name: String,
+        instructions: Option<String>,
+    },
+
+    /// Extension auth completed.
+    AuthCompleted {
+        extension_name: String,
+        success: bool,
+        message: String,
+    },
+
+    /// Agent reasoning update.
+    ReasoningUpdate { narrative: String },
+
+    /// Per-turn token/cost summary.
+    TurnCost {
+        input_tokens: u64,
+        output_tokens: u64,
+        cost_usd: String,
+    },
+
+    /// Suggestions for follow-up messages.
+    Suggestions { suggestions: Vec<String> },
+
+    /// Context pressure update (token usage warning).
+    ContextPressure {
+        used_tokens: u64,
+        max_tokens: u64,
+        percentage: u8,
+        warning: Option<String>,
+    },
+
+    /// Sandbox / Docker status update.
+    SandboxStatus {
+        docker_available: bool,
+        running_containers: u32,
+        status: String,
+    },
+
+    /// Secrets vault status update.
+    SecretsStatus { count: u32, vault_unlocked: bool },
+
+    /// Cost guard / budget status update.
+    CostGuard {
+        session_budget_usd: Option<String>,
+        spent_usd: String,
+        remaining_usd: Option<String>,
+        limit_reached: bool,
+    },
+
+    /// A log entry captured from the tracing subscriber.
+    Log {
+        level: String,
+        target: String,
+        message: String,
+        timestamp: String,
+    },
+
+    /// Thread list for the interactive resume picker.
+    ThreadList { threads: Vec<ThreadEntry> },
+
+    /// Engine v2 thread list update for the activity sidebar.
+    EngineThreadList { threads: Vec<EngineThreadEntry> },
+
+    /// Full engine v2 thread detail for the sidebar modal.
+    EngineThreadDetail { detail: EngineThreadDetailEntry },
+
+    /// Full conversation history for a resumed thread.
+    ConversationHistory {
+        thread_id: String,
+        messages: Vec<HistoryMessage>,
+        pending_approval: Option<HistoryApprovalRequest>,
+    },
+}
diff --git a/crates/ironclaw_tui/src/input.rs b/crates/ironclaw_tui/src/input.rs
new file mode 100644
index 00000000000..f241f2318c7
--- /dev/null
+++ b/crates/ironclaw_tui/src/input.rs
@@ -0,0 +1,514 @@
+//! Key handling and command parsing for the TUI.
+
+use ratatui::crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
+
+use crate::widgets::LogLevelFilter;
+
+/// Parsed user command from keyboard input.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum InputAction {
+    /// Submit the current input text to the agent.
+    Submit,
+    /// Quit the TUI.
+    Quit,
+    /// Toggle sidebar visibility.
+    ToggleSidebar,
+    /// Toggle between Conversation and Logs tabs.
+    ToggleLogs,
+    /// Scroll conversation up.
+    ScrollUp,
+    /// Scroll conversation down.
+    ScrollDown,
+    /// Cancel / interrupt current operation.
+    Interrupt,
+    /// Navigate approval dialog up.
+    ApprovalUp,
+    /// Navigate approval dialog down.
+    ApprovalDown,
+    /// Confirm approval selection.
+    ApprovalConfirm,
+    /// Cancel approval (deny).
+    ApprovalCancel,
+    /// Quick approve.
+    QuickApprove,
+    /// Quick always-approve.
+    QuickAlways,
+    /// Quick deny.
+    QuickDeny,
+    /// Navigate command palette up.
+    PaletteUp,
+    /// Navigate command palette down.
+    PaletteDown,
+    /// Select the highlighted command palette item.
+    PaletteSelect,
+    /// Close the command palette.
+    PaletteClose,
+    /// Navigate input history backward (older).
+    HistoryUp,
+    /// Navigate input history forward (newer).
+    HistoryDown,
+    /// Toggle search mode on/off.
+    SearchToggle,
+    /// Jump to next search match.
+    SearchNext,
+    /// Jump to previous search match.
+    SearchPrev,
+    /// Toggle help overlay (F1).
+    ToggleHelp,
+    /// Expand most recent tool output (Ctrl+E).
+    ExpandTool,
+    /// Set log level filter (1-5 in Logs tab).
+    LogFilter(LogLevelFilter),
+    /// Scroll tool detail modal up.
+    ToolDetailScrollUp,
+    /// Scroll tool detail modal down.
+    ToolDetailScrollDown,
+    /// Close the tool detail modal.
+    ToolDetailClose,
+    /// Paste image from system clipboard (Ctrl+V).
+    ClipboardPaste,
+    /// Navigate thread picker up.
+    ThreadPickerUp,
+    /// Navigate thread picker down.
+    ThreadPickerDown,
+    /// Select the highlighted thread.
+    ThreadPickerSelect,
+    /// Close the thread picker.
+    ThreadPickerClose,
+    /// Jump to the bottom of the conversation.
+    ScrollToBottom,
+    /// No recognized action — pass to input box.
+    Forward,
+}
+
+/// Map a key event to an action, considering active modal/context state.
+#[allow(clippy::too_many_arguments)]
+pub fn map_key(
+    key: KeyEvent,
+    approval_active: bool,
+    palette_active: bool,
+    search_active: bool,
+    help_active: bool,
+    tool_detail_active: bool,
+    logs_active: bool,
+    thread_picker_active: bool,
+) -> InputAction {
+    if thread_picker_active {
+        return map_thread_picker_key(key);
+    }
+
+    if approval_active {
+        return map_approval_key(key);
+    }
+
+    if help_active {
+        return map_help_key(key);
+    }
+
+    if tool_detail_active {
+        return map_tool_detail_key(key);
+    }
+
+    if search_active {
+        return map_search_key(key);
+    }
+
+    if palette_active {
+        return map_palette_key(key);
+    }
+
+    // Log level filter keys only in logs tab
+    if logs_active && let Some(action) = map_log_filter_key(key) {
+        return action;
+    }
+
+    match (key.code, key.modifiers) {
+        (KeyCode::Enter, KeyModifiers::NONE) => InputAction::Submit,
+        (KeyCode::Char('c'), KeyModifiers::CONTROL) => InputAction::Quit,
+        (KeyCode::Char('b'), KeyModifiers::CONTROL) => InputAction::ToggleSidebar,
+        (KeyCode::Char('l'), KeyModifiers::CONTROL) => InputAction::ToggleLogs,
+        (KeyCode::Char('f'), KeyModifiers::CONTROL) => InputAction::SearchToggle,
+        (KeyCode::Char('e'), KeyModifiers::CONTROL) => InputAction::ExpandTool,
+        (KeyCode::Char('v'), KeyModifiers::CONTROL) => InputAction::ClipboardPaste,
+        (KeyCode::F(1), _) => InputAction::ToggleHelp,
+        (KeyCode::Esc, _) => InputAction::Interrupt,
+        (KeyCode::PageUp, _) => InputAction::ScrollUp,
+        (KeyCode::PageDown, _) => InputAction::ScrollDown,
+        // Ctrl+Up / Ctrl+Down for scroll
+        (KeyCode::Up, KeyModifiers::CONTROL) => InputAction::ScrollUp,
+        (KeyCode::Down, KeyModifiers::CONTROL) => InputAction::ScrollDown,
+        // End key jumps to bottom
+        (KeyCode::End, _) => InputAction::ScrollToBottom,
+        // Ctrl+P / Ctrl+N for input history navigation
+        (KeyCode::Char('p'), KeyModifiers::CONTROL) => InputAction::HistoryUp,
+        (KeyCode::Char('n'), KeyModifiers::CONTROL) => InputAction::HistoryDown,
+        _ => InputAction::Forward,
+    }
+}
+
+/// Map key events when the help overlay is active.
+fn map_help_key(key: KeyEvent) -> InputAction {
+    match (key.code, key.modifiers) {
+        (KeyCode::Char('c'), KeyModifiers::CONTROL) => InputAction::Quit,
+        (KeyCode::Esc, _) | (KeyCode::F(1), _) => InputAction::ToggleHelp,
+        _ => InputAction::Forward,
+    }
+}
+
+/// Map key events when the tool detail modal is active.
+fn map_tool_detail_key(key: KeyEvent) -> InputAction {
+    match (key.code, key.modifiers) {
+        (KeyCode::Char('c'), KeyModifiers::CONTROL) => InputAction::Quit,
+        (KeyCode::Esc, _) => InputAction::ToolDetailClose,
+        (KeyCode::PageUp, _) | (KeyCode::Up, _) => InputAction::ToolDetailScrollUp,
+        (KeyCode::PageDown, _) | (KeyCode::Down, _) => InputAction::ToolDetailScrollDown,
+        _ => InputAction::Forward,
+    }
+}
+
+/// Map number keys to log level filters (only when logs tab is active).
+fn map_log_filter_key(key: KeyEvent) -> Option<InputAction> {
+    if key.modifiers != KeyModifiers::NONE {
+        return None;
+    }
+    match key.code {
+        KeyCode::Char('1') => Some(InputAction::LogFilter(LogLevelFilter::Error)),
+        KeyCode::Char('2') => Some(InputAction::LogFilter(LogLevelFilter::Warn)),
+        KeyCode::Char('3') => Some(InputAction::LogFilter(LogLevelFilter::Info)),
+        KeyCode::Char('4') => Some(InputAction::LogFilter(LogLevelFilter::Debug)),
+        KeyCode::Char('5') => Some(InputAction::LogFilter(LogLevelFilter::All)),
+        _ => None,
+    }
+}
+
+/// Map key events when the search bar is active.
+fn map_search_key(key: KeyEvent) -> InputAction {
+    match (key.code, key.modifiers) {
+        (KeyCode::Char('c'), KeyModifiers::CONTROL) => InputAction::Quit,
+        (KeyCode::Esc, _) => InputAction::SearchToggle,
+        (KeyCode::Enter, KeyModifiers::NONE) => InputAction::SearchNext,
+        (KeyCode::Enter, KeyModifiers::SHIFT) => InputAction::SearchPrev,
+        _ => InputAction::Forward,
+    }
+}
+
+/// Map key events when the command palette is active.
+fn map_palette_key(key: KeyEvent) -> InputAction {
+    match key.code {
+        KeyCode::Up => InputAction::PaletteUp,
+        KeyCode::Down => InputAction::PaletteDown,
+        KeyCode::Enter | KeyCode::Tab => InputAction::PaletteSelect,
+        KeyCode::Esc => InputAction::PaletteClose,
+        KeyCode::Char('c') if key.modifiers == KeyModifiers::CONTROL => InputAction::Quit,
+        _ => InputAction::Forward,
+    }
+}
+
+/// Map key events when the thread picker modal is active.
+fn map_thread_picker_key(key: KeyEvent) -> InputAction {
+    match key.code {
+        KeyCode::Up | KeyCode::Char('k') => InputAction::ThreadPickerUp,
+        KeyCode::Down | KeyCode::Char('j') => InputAction::ThreadPickerDown,
+        KeyCode::Enter => InputAction::ThreadPickerSelect,
+        KeyCode::Esc => InputAction::ThreadPickerClose,
+        KeyCode::Char('c') if key.modifiers == KeyModifiers::CONTROL => InputAction::Quit,
+        _ => InputAction::Forward,
+    }
+}
+
+/// Map key events when the approval dialog is active.
+fn map_approval_key(key: KeyEvent) -> InputAction {
+    match key.code {
+        KeyCode::Up | KeyCode::Char('k') => InputAction::ApprovalUp,
+        KeyCode::Down | KeyCode::Char('j') => InputAction::ApprovalDown,
+        KeyCode::Enter => InputAction::ApprovalConfirm,
+        KeyCode::Esc => InputAction::ApprovalCancel,
+        KeyCode::Char('y') | KeyCode::Char('Y') => InputAction::QuickApprove,
+        KeyCode::Char('a') | KeyCode::Char('A') => InputAction::QuickAlways,
+        KeyCode::Char('n') | KeyCode::Char('N') => InputAction::QuickDeny,
+        _ => InputAction::Forward,
+    }
+}
+
+/// Parse a slash command from user input text.
+pub fn parse_slash_command(text: &str) -> Option<&str> {
+    let trimmed = text.trim();
+    if trimmed.starts_with('/') {
+        Some(trimmed)
+    } else {
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn map_default(key: KeyEvent) -> InputAction {
+        map_key(key, false, false, false, false, false, false, false)
+    }
+
+    fn map_approval(key: KeyEvent) -> InputAction {
+        map_key(key, true, false, false, false, false, false, false)
+    }
+
+    fn map_palette(key: KeyEvent) -> InputAction {
+        map_key(key, false, true, false, false, false, false, false)
+    }
+
+    fn map_search(key: KeyEvent) -> InputAction {
+        map_key(key, false, false, true, false, false, false, false)
+    }
+
+    fn map_logs(key: KeyEvent) -> InputAction {
+        map_key(key, false, false, false, false, false, true, false)
+    }
+
+    fn map_help(key: KeyEvent) -> InputAction {
+        map_key(key, false, false, false, true, false, false, false)
+    }
+
+    fn map_tool_detail(key: KeyEvent) -> InputAction {
+        map_key(key, false, false, false, false, true, false, false)
+    }
+
+    fn map_thread_picker(key: KeyEvent) -> InputAction {
+        map_key(key, false, false, false, false, false, false, true)
+    }
+
+    #[test]
+    fn enter_submits() {
+        let key = KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE);
+        assert_eq!(map_default(key), InputAction::Submit);
+    }
+
+    #[test]
+    fn ctrl_c_quits() {
+        let key = KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL);
+        assert_eq!(map_default(key), InputAction::Quit);
+    }
+
+    #[test]
+    fn ctrl_b_toggles_sidebar() {
+        let key = KeyEvent::new(KeyCode::Char('b'), KeyModifiers::CONTROL);
+        assert_eq!(map_default(key), InputAction::ToggleSidebar);
+    }
+
+    #[test]
+    fn ctrl_l_toggles_logs() {
+        let key = KeyEvent::new(KeyCode::Char('l'), KeyModifiers::CONTROL);
+        assert_eq!(map_default(key), InputAction::ToggleLogs);
+    }
+
+    #[test]
+    fn esc_interrupts() {
+        let key = KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE);
+        assert_eq!(map_default(key), InputAction::Interrupt);
+    }
+
+    #[test]
+    fn f1_toggles_help() {
+        let key = KeyEvent::new(KeyCode::F(1), KeyModifiers::NONE);
+        assert_eq!(map_default(key), InputAction::ToggleHelp);
+    }
+
+    #[test]
+    fn ctrl_e_expands_tool() {
+        let key = KeyEvent::new(KeyCode::Char('e'), KeyModifiers::CONTROL);
+        assert_eq!(map_default(key), InputAction::ExpandTool);
+    }
+
+    #[test]
+    fn approval_mode_y_approves() {
+        let key = KeyEvent::new(KeyCode::Char('y'), KeyModifiers::NONE);
+        assert_eq!(map_approval(key), InputAction::QuickApprove);
+    }
+
+    #[test]
+    fn approval_mode_n_denies() {
+        let key = KeyEvent::new(KeyCode::Char('n'), KeyModifiers::NONE);
+        assert_eq!(map_approval(key), InputAction::QuickDeny);
+    }
+
+    #[test]
+    fn palette_up_down() {
+        let up = KeyEvent::new(KeyCode::Up, KeyModifiers::NONE);
+        assert_eq!(map_palette(up), InputAction::PaletteUp);
+        let down = KeyEvent::new(KeyCode::Down, KeyModifiers::NONE);
+        assert_eq!(map_palette(down), InputAction::PaletteDown);
+    }
+
+    #[test]
+    fn palette_enter_selects() {
+        let key = KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE);
+        assert_eq!(map_palette(key), InputAction::PaletteSelect);
+    }
+
+    #[test]
+    fn palette_tab_selects() {
+        let key = KeyEvent::new(KeyCode::Tab, KeyModifiers::NONE);
+        assert_eq!(map_palette(key), InputAction::PaletteSelect);
+    }
+
+    #[test]
+    fn palette_esc_closes() {
+        let key = KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE);
+        assert_eq!(map_palette(key), InputAction::PaletteClose);
+    }
+
+    #[test]
+    fn palette_typing_forwards() {
+        let key = KeyEvent::new(KeyCode::Char('h'), KeyModifiers::NONE);
+        assert_eq!(map_palette(key), InputAction::Forward);
+    }
+
+    #[test]
+    fn ctrl_p_history_up() {
+        let key = KeyEvent::new(KeyCode::Char('p'), KeyModifiers::CONTROL);
+        assert_eq!(map_default(key), InputAction::HistoryUp);
+    }
+
+    #[test]
+    fn ctrl_n_history_down() {
+        let key = KeyEvent::new(KeyCode::Char('n'), KeyModifiers::CONTROL);
+        assert_eq!(map_default(key), InputAction::HistoryDown);
+    }
+
+    #[test]
+    fn history_keys_ignored_in_approval_mode() {
+        let key_p = KeyEvent::new(KeyCode::Char('p'), KeyModifiers::CONTROL);
+        assert_eq!(map_approval(key_p), InputAction::Forward);
+    }
+
+    #[test]
+    fn history_keys_ignored_in_palette_mode() {
+        let key_p = KeyEvent::new(KeyCode::Char('p'), KeyModifiers::CONTROL);
+        assert_eq!(map_palette(key_p), InputAction::Forward);
+    }
+
+    #[test]
+    fn ctrl_f_toggles_search() {
+        let key = KeyEvent::new(KeyCode::Char('f'), KeyModifiers::CONTROL);
+        assert_eq!(map_default(key), InputAction::SearchToggle);
+    }
+
+    #[test]
+    fn search_esc_closes() {
+        let key = KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE);
+        assert_eq!(map_search(key), InputAction::SearchToggle);
+    }
+
+    #[test]
+    fn search_enter_next() {
+        let key = KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE);
+        assert_eq!(map_search(key), InputAction::SearchNext);
+    }
+
+    #[test]
+    fn search_shift_enter_prev() {
+        let key = KeyEvent::new(KeyCode::Enter, KeyModifiers::SHIFT);
+        assert_eq!(map_search(key), InputAction::SearchPrev);
+    }
+
+    #[test]
+    fn search_typing_forwards() {
+        let key = KeyEvent::new(KeyCode::Char('a'), KeyModifiers::NONE);
+        assert_eq!(map_search(key), InputAction::Forward);
+    }
+
+    #[test]
+    fn search_ctrl_c_quits() {
+        let key = KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL);
+        assert_eq!(map_search(key), InputAction::Quit);
+    }
+
+    #[test]
+    fn log_filter_keys_in_logs_tab() {
+        let key1 = KeyEvent::new(KeyCode::Char('1'), KeyModifiers::NONE);
+        assert_eq!(
+            map_logs(key1),
+            InputAction::LogFilter(LogLevelFilter::Error)
+        );
+        let key5 = KeyEvent::new(KeyCode::Char('5'), KeyModifiers::NONE);
+        assert_eq!(map_logs(key5), InputAction::LogFilter(LogLevelFilter::All));
+    }
+
+    #[test]
+    fn log_filter_keys_not_in_chat_tab() {
+        let key1 = KeyEvent::new(KeyCode::Char('1'), KeyModifiers::NONE);
+        assert_eq!(map_default(key1), InputAction::Forward);
+    }
+
+    #[test]
+    fn help_esc_closes() {
+        let key = KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE);
+        assert_eq!(map_help(key), InputAction::ToggleHelp);
+    }
+
+    #[test]
+    fn help_f1_closes() {
+        let key = KeyEvent::new(KeyCode::F(1), KeyModifiers::NONE);
+        assert_eq!(map_help(key), InputAction::ToggleHelp);
+    }
+
+    #[test]
+    fn tool_detail_esc_closes() {
+        let key = KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE);
+        assert_eq!(map_tool_detail(key), InputAction::ToolDetailClose);
+    }
+
+    #[test]
+    fn tool_detail_scroll() {
+        let up = KeyEvent::new(KeyCode::PageUp, KeyModifiers::NONE);
+        assert_eq!(map_tool_detail(up), InputAction::ToolDetailScrollUp);
+        let down = KeyEvent::new(KeyCode::PageDown, KeyModifiers::NONE);
+        assert_eq!(map_tool_detail(down), InputAction::ToolDetailScrollDown);
+    }
+
+    #[test]
+    fn ctrl_v_clipboard_paste() {
+        let key = KeyEvent::new(KeyCode::Char('v'), KeyModifiers::CONTROL);
+        assert_eq!(map_default(key), InputAction::ClipboardPaste);
+    }
+
+    #[test]
+    fn thread_picker_up_down() {
+        let up = KeyEvent::new(KeyCode::Up, KeyModifiers::NONE);
+        assert_eq!(map_thread_picker(up), InputAction::ThreadPickerUp);
+        let down = KeyEvent::new(KeyCode::Down, KeyModifiers::NONE);
+        assert_eq!(map_thread_picker(down), InputAction::ThreadPickerDown);
+    }
+
+    #[test]
+    fn thread_picker_jk_navigation() {
+        let j = KeyEvent::new(KeyCode::Char('j'), KeyModifiers::NONE);
+        assert_eq!(map_thread_picker(j), InputAction::ThreadPickerDown);
+        let k = KeyEvent::new(KeyCode::Char('k'), KeyModifiers::NONE);
+        assert_eq!(map_thread_picker(k), InputAction::ThreadPickerUp);
+    }
+
+    #[test]
+    fn thread_picker_enter_selects() {
+        let key = KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE);
+        assert_eq!(map_thread_picker(key), InputAction::ThreadPickerSelect);
+    }
+
+    #[test]
+    fn thread_picker_esc_closes() {
+        let key = KeyEvent::new(KeyCode::Esc, KeyModifiers::NONE);
+        assert_eq!(map_thread_picker(key), InputAction::ThreadPickerClose);
+    }
+
+    #[test]
+    fn thread_picker_ctrl_c_quits() {
+        let key = KeyEvent::new(KeyCode::Char('c'), KeyModifiers::CONTROL);
+        assert_eq!(map_thread_picker(key), InputAction::Quit);
+    }
+
+    #[test]
+    fn slash_command_detected() {
+        assert_eq!(parse_slash_command("/help"), Some("/help"));
+        assert_eq!(parse_slash_command("  /quit  "), Some("/quit"));
+        assert_eq!(parse_slash_command("hello"), None);
+    }
+}
diff --git a/crates/ironclaw_tui/src/layout.rs b/crates/ironclaw_tui/src/layout.rs
new file mode 100644
index 00000000000..11a956d3bb2
--- /dev/null
+++ b/crates/ironclaw_tui/src/layout.rs
@@ -0,0 +1,256 @@
+//! User-configurable TUI layout.
+//!
+//! Layout is loaded from `tui/layout.json` in the workspace directory.
+//! If the file doesn't exist, sensible defaults are used.
+
+use std::collections::HashMap;
+use std::path::Path;
+
+use serde::{Deserialize, Serialize};
+
+use crate::theme::Theme;
+
+/// Top-level layout configuration for the TUI.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TuiLayout {
+    /// Theme name or inline theme definition.
+    #[serde(default = "default_theme_name")]
+    pub theme: String,
+
+    /// Sidebar configuration.
+    #[serde(default)]
+    pub sidebar: SidebarConfig,
+
+    /// Header bar configuration.
+    #[serde(default)]
+    pub header: HeaderConfig,
+
+    /// Status bar configuration.
+    #[serde(default)]
+    pub status_bar: StatusBarConfig,
+
+    /// Conversation area configuration.
+    #[serde(default)]
+    pub conversation: ConversationConfig,
+
+    /// Key binding overrides: action name -> key combo string.
+    #[serde(default)]
+    pub keybindings: HashMap<String, String>,
+
+    /// Per-widget configuration overrides.
+    #[serde(default)]
+    pub widgets: HashMap<String, serde_json::Value>,
+}
+
+fn default_theme_name() -> String {
+    "dark".to_string()
+}
+
+impl Default for TuiLayout {
+    fn default() -> Self {
+        Self {
+            theme: default_theme_name(),
+            sidebar: SidebarConfig::default(),
+            header: HeaderConfig::default(),
+            status_bar: StatusBarConfig::default(),
+            conversation: ConversationConfig::default(),
+            keybindings: HashMap::new(),
+            widgets: HashMap::new(),
+        }
+    }
+}
+
+impl TuiLayout {
+    /// Load layout from a JSON file, falling back to defaults on any error.
+    pub fn load_from_file(path: &Path) -> Self {
+        match std::fs::read_to_string(path) {
+            Ok(contents) => serde_json::from_str(&contents).unwrap_or_default(),
+            Err(_) => Self::default(),
+        }
+    }
+
+    /// Resolve the theme from the layout's theme name.
+    pub fn resolve_theme(&self) -> Theme {
+        match self.theme.as_str() {
+            "light" => Theme::light(),
+            _ => Theme::dark(),
+        }
+    }
+}
+
+/// Sidebar panel configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SidebarConfig {
+    /// Whether the sidebar is visible.
+    #[serde(default = "default_true")]
+    pub visible: bool,
+
+    /// Sidebar width as percentage of terminal width (10-50).
+    #[serde(default = "default_sidebar_width")]
+    pub width_percent: u16,
+}
+
+fn default_true() -> bool {
+    true
+}
+
+fn default_sidebar_width() -> u16 {
+    25
+}
+
+impl Default for SidebarConfig {
+    fn default() -> Self {
+        Self {
+            visible: true,
+            width_percent: default_sidebar_width(),
+        }
+    }
+}
+
+impl SidebarConfig {
+    /// Clamp width to valid range.
+    pub fn effective_width(&self) -> u16 {
+        self.width_percent.clamp(10, 50)
+    }
+}
+
+/// Header bar configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct HeaderConfig {
+    #[serde(default = "default_true")]
+    pub visible: bool,
+
+    #[serde(default = "default_true")]
+    pub show_model: bool,
+
+    #[serde(default = "default_true")]
+    pub show_tokens: bool,
+
+    #[serde(default = "default_true")]
+    pub show_session_duration: bool,
+}
+
+impl Default for HeaderConfig {
+    fn default() -> Self {
+        Self {
+            visible: false,
+            show_model: true,
+            show_tokens: true,
+            show_session_duration: true,
+        }
+    }
+}
+
+/// Status bar configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StatusBarConfig {
+    #[serde(default = "default_true")]
+    pub visible: bool,
+
+    #[serde(default = "default_true")]
+    pub show_cost: bool,
+
+    #[serde(default = "default_true")]
+    pub show_keybinds: bool,
+}
+
+impl Default for StatusBarConfig {
+    fn default() -> Self {
+        Self {
+            visible: true,
+            show_cost: true,
+            show_keybinds: true,
+        }
+    }
+}
+
+/// Conversation area configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationConfig {
+    /// Show tool call details inline in conversation.
+    #[serde(default = "default_true")]
+    pub show_tool_details: bool,
+
+    /// Maximum number of messages to keep in the visible buffer.
+    #[serde(default = "default_max_messages")]
+    pub max_visible_messages: usize,
+}
+
+fn default_max_messages() -> usize {
+    200
+}
+
+impl Default for ConversationConfig {
+    fn default() -> Self {
+        Self {
+            show_tool_details: true,
+            max_visible_messages: default_max_messages(),
+        }
+    }
+}
+
+/// Where widgets can be placed in the TUI layout.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum TuiSlot {
+    Header,
+    StatusBarLeft,
+    StatusBarCenter,
+    StatusBarRight,
+    Sidebar,
+    SidebarSection,
+    ConversationBanner,
+    InputPrefix,
+    Tab,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_layout_is_valid() {
+        let layout = TuiLayout::default();
+        assert_eq!(layout.theme, "dark");
+        assert!(layout.sidebar.visible);
+        assert_eq!(layout.sidebar.effective_width(), 25);
+        assert!(!layout.header.visible);
+        assert!(layout.status_bar.visible);
+    }
+
+    #[test]
+    fn sidebar_width_clamped() {
+        let mut sb = SidebarConfig {
+            width_percent: 5,
+            ..Default::default()
+        };
+        assert_eq!(sb.effective_width(), 10);
+        sb.width_percent = 80;
+        assert_eq!(sb.effective_width(), 50);
+    }
+
+    #[test]
+    fn layout_serialization_round_trip() {
+        let layout = TuiLayout::default();
+        let json = serde_json::to_string(&layout).expect("serialize");
+        let back: TuiLayout = serde_json::from_str(&json).expect("deserialize");
+        assert_eq!(back.theme, "dark");
+        assert_eq!(back.sidebar.width_percent, 25);
+    }
+
+    #[test]
+    fn resolve_theme_dark() {
+        let layout = TuiLayout::default();
+        let theme = layout.resolve_theme();
+        assert_eq!(theme.name, "dark");
+    }
+
+    #[test]
+    fn resolve_theme_light() {
+        let layout = TuiLayout {
+            theme: "light".to_string(),
+            ..Default::default()
+        };
+        let theme = layout.resolve_theme();
+        assert_eq!(theme.name, "light");
+    }
+}
diff --git a/crates/ironclaw_tui/src/lib.rs b/crates/ironclaw_tui/src/lib.rs
new file mode 100644
index 00000000000..3d7b4f381dc
--- /dev/null
+++ b/crates/ironclaw_tui/src/lib.rs
@@ -0,0 +1,50 @@
+//! `ironclaw_tui` — Modular Ratatui-based TUI for IronClaw.
+//!
+//! This crate provides the rendering engine, widget system, and event loop
+//! for IronClaw's terminal user interface. It is intentionally decoupled
+//! from the main `ironclaw` crate: the Channel trait bridge lives in
+//! `src/channels/tui.rs` in the main crate.
+//!
+//! # Architecture
+//!
+//! ```text
+//! ┌─ TuiApp (app.rs) ────────────────────────────────────────────┐
+//! │  Event loop: poll crossterm → merge with TuiEvent rx         │
+//! │  Render: Layout → Widget::render() → Terminal::draw()        │
+//! │                                                              │
+//! │  ┌─ Header ─────────────────────────────────────────────┐    │
+//! │  │  version · model · duration · tokens                 │    │
+//! │  ├─ Conversation ──────────┬─ Sidebar ──────────────────┤    │
+//! │  │  Messages + markdown    │  Tools: live activity      │    │
+//! │  │                         │  Threads: active/recent    │    │
+//! │  ├─ Input ─────────────────┴────────────────────────────┤    │
+//! │  │  › user input (tui-textarea)                         │    │
+//! │  ├─ Status Bar ─────────────────────────────────────────┤    │
+//! │  │  model │ tokens │ cost │ keybinds                    │    │
+//! │  └──────────────────────────────────────────────────────┘    │
+//! └──────────────────────────────────────────────────────────────┘
+//! ```
+//!
+//! # Communication
+//!
+//! The main crate sends [`TuiEvent`]s via the handle's `event_tx`, and
+//! receives user messages via `msg_rx`. The TUI never calls into the
+//! main crate directly.
+
+pub mod app;
+pub mod event;
+pub mod input;
+pub mod layout;
+pub mod render;
+pub mod spinner;
+pub mod theme;
+pub mod widgets;
+
+pub use app::{TuiAppConfig, TuiAppHandle, start_tui};
+pub use event::{
+    EngineThreadDetailEntry, EngineThreadEntry, EngineThreadMessageEntry, HistoryApprovalRequest,
+    HistoryMessage, ThreadEntry, TuiAttachment, TuiEvent, TuiLogEntry, TuiUiAction, TuiUserMessage,
+};
+pub use layout::TuiLayout;
+pub use theme::Theme;
+pub use widgets::{AppState, SkillCategory, ToolCategory};
diff --git a/crates/ironclaw_tui/src/render.rs b/crates/ironclaw_tui/src/render.rs
new file mode 100644
index 00000000000..44fd1cdbfb3
--- /dev/null
+++ b/crates/ironclaw_tui/src/render.rs
@@ -0,0 +1,1135 @@
+//! Rendering utilities for converting text to styled Ratatui spans.
+
+use pulldown_cmark::{CodeBlockKind, Event, HeadingLevel, Options, Parser, Tag, TagEnd};
+use ratatui::style::{Modifier, Style};
+use ratatui::text::{Line, Span};
+use unicode_width::{UnicodeWidthChar, UnicodeWidthStr};
+
+use crate::theme::Theme;
+
+/// Convert a plain text string into wrapped `Line`s that fit within `max_width`.
+pub fn wrap_text(text: &str, max_width: usize, style: Style) -> Vec<Line<'static>> {
+    if max_width == 0 {
+        return vec![];
+    }
+
+    let mut lines = Vec::new();
+    for raw_line in text.lines() {
+        if raw_line.is_empty() {
+            lines.push(Line::from(""));
+            continue;
+        }
+        lines.extend(wrap_plain_line(raw_line, max_width, style));
+    }
+
+    if lines.is_empty() {
+        lines.push(Line::from(""));
+    }
+
+    lines
+}
+
+fn wrap_plain_line(raw_line: &str, max_width: usize, style: Style) -> Vec<Line<'static>> {
+    let mut tokens = Vec::new();
+    let mut current = String::new();
+    let mut current_is_whitespace = None;
+
+    for ch in raw_line.chars() {
+        let is_whitespace = ch.is_whitespace();
+        if current_is_whitespace == Some(is_whitespace) || current.is_empty() {
+            push_wrapped_char(&mut current, ch);
+            current_is_whitespace = Some(is_whitespace);
+            continue;
+        }
+
+        tokens.push(std::mem::take(&mut current));
+        push_wrapped_char(&mut current, ch);
+        current_is_whitespace = Some(is_whitespace);
+    }
+
+    if !current.is_empty() {
+        tokens.push(current);
+    }
+
+    let mut lines = Vec::new();
+    let mut current_line = String::new();
+    let mut current_width = 0usize;
+
+    for token in tokens {
+        let token_width = UnicodeWidthStr::width(token.as_str());
+        if current_width + token_width <= max_width {
+            current_line.push_str(&token);
+            current_width += token_width;
+            continue;
+        }
+
+        if !current_line.is_empty() {
+            lines.push(Line::from(Span::styled(
+                std::mem::take(&mut current_line),
+                style,
+            )));
+            current_width = 0;
+        }
+
+        if token_width <= max_width {
+            current_width = token_width;
+            current_line = token;
+            continue;
+        }
+
+        for ch in token.chars() {
+            let rendered = render_wrapped_char(ch);
+            let rendered_width = wrapped_char_width(ch);
+            if current_width + rendered_width > max_width && !current_line.is_empty() {
+                lines.push(Line::from(Span::styled(
+                    std::mem::take(&mut current_line),
+                    style,
+                )));
+                current_width = 0;
+            }
+            current_line.push_str(&rendered);
+            current_width += rendered_width;
+        }
+    }
+
+    if !current_line.is_empty() {
+        lines.push(Line::from(Span::styled(current_line, style)));
+    }
+
+    if lines.is_empty() {
+        lines.push(Line::from(""));
+    }
+
+    lines
+}
+
+fn push_wrapped_char(target: &mut String, ch: char) {
+    target.push_str(&render_wrapped_char(ch));
+}
+
+fn render_wrapped_char(ch: char) -> String {
+    match ch {
+        '\t' => "    ".to_string(),
+        _ => ch.to_string(),
+    }
+}
+
+fn wrapped_char_width(ch: char) -> usize {
+    match ch {
+        '\t' => 4,
+        _ => UnicodeWidthChar::width(ch).unwrap_or(0),
+    }
+}
+
+// ── Markdown rendering ────────────────────────────────────────────────
+
+/// Which kind of list we're inside.
+#[derive(Clone)]
+enum ListKind {
+    Unordered,
+    Ordered(u64),
+}
+
+/// Render CommonMark `text` into styled, word-wrapped `Line`s.
+///
+/// Headings, bold, italic, inline code, fenced code blocks, lists,
+/// blockquotes, horizontal rules, and links are all rendered with
+/// appropriate terminal styles via `theme`.
+pub fn render_markdown(text: &str, max_width: usize, theme: &Theme) -> Vec<Line<'static>> {
+    if max_width == 0 {
+        return vec![];
+    }
+
+    let opts = Options::ENABLE_STRIKETHROUGH;
+    let parser = Parser::new_ext(text, opts);
+
+    let mut ctx = MdContext::new(theme);
+
+    for event in parser {
+        match event {
+            // ── Block-level start ────────────────────────────────
+            Event::Start(Tag::Heading { level, .. }) => {
+                if !ctx.first_block {
+                    ctx.need_blank_line = true;
+                }
+                if ctx.need_blank_line {
+                    ctx.lines.push(Line::from(""));
+                    ctx.need_blank_line = false;
+                }
+                let heading_style = match level {
+                    HeadingLevel::H1 | HeadingLevel::H2 => theme.bold_accent_style(),
+                    _ => theme.bold_style(),
+                };
+                ctx.style_stack.push(heading_style);
+            }
+            Event::End(TagEnd::Heading(_)) => {
+                ctx.flush(max_width, theme);
+                ctx.style_stack.pop();
+                ctx.need_blank_line = true;
+                ctx.first_block = false;
+            }
+
+            Event::Start(Tag::Paragraph) => {
+                if ctx.need_blank_line && !ctx.first_block {
+                    ctx.lines.push(Line::from(""));
+                    ctx.need_blank_line = false;
+                }
+            }
+            Event::End(TagEnd::Paragraph) => {
+                ctx.flush(max_width, theme);
+                ctx.need_blank_line = true;
+                ctx.first_block = false;
+            }
+
+            Event::Start(Tag::BlockQuote(_)) => {
+                if ctx.need_blank_line && !ctx.first_block {
+                    ctx.lines.push(Line::from(""));
+                    ctx.need_blank_line = false;
+                }
+                ctx.in_blockquote = true;
+                ctx.style_stack.push(theme.dim_style());
+            }
+            Event::End(TagEnd::BlockQuote(_)) => {
+                ctx.flush(max_width, theme);
+                ctx.in_blockquote = false;
+                ctx.style_stack.pop();
+                ctx.need_blank_line = true;
+                ctx.first_block = false;
+            }
+
+            Event::Start(Tag::CodeBlock(kind)) => {
+                if ctx.need_blank_line && !ctx.first_block {
+                    ctx.lines.push(Line::from(""));
+                    ctx.need_blank_line = false;
+                }
+                // Language badge for fenced code blocks
+                if let CodeBlockKind::Fenced(ref lang) = kind {
+                    let lang_str = lang.split(',').next().unwrap_or("").trim();
+                    if !lang_str.is_empty() {
+                        ctx.lines.push(Line::from(Span::styled(
+                            format!("[{lang_str}]"),
+                            theme.accent_style().add_modifier(Modifier::BOLD),
+                        )));
+                    }
+                }
+                ctx.in_code_block = true;
+            }
+            Event::End(TagEnd::CodeBlock) => {
+                ctx.in_code_block = false;
+                ctx.need_blank_line = true;
+                ctx.first_block = false;
+            }
+
+            Event::Start(Tag::List(start)) => {
+                if ctx.need_blank_line && !ctx.first_block {
+                    ctx.lines.push(Line::from(""));
+                    ctx.need_blank_line = false;
+                }
+                match start {
+                    Some(n) => ctx.list_stack.push(ListKind::Ordered(n)),
+                    None => ctx.list_stack.push(ListKind::Unordered),
+                }
+            }
+            Event::End(TagEnd::List(_)) => {
+                ctx.list_stack.pop();
+                ctx.need_blank_line = true;
+                ctx.first_block = false;
+            }
+
+            Event::Start(Tag::Item) => {
+                let depth = ctx.list_stack.len().saturating_sub(1);
+                let base_indent = depth * 4;
+                let prefix = match ctx.list_stack.last() {
+                    Some(ListKind::Unordered) => {
+                        format!("{}\u{2022} ", " ".repeat(base_indent + 2))
+                    }
+                    Some(ListKind::Ordered(n)) => {
+                        format!("{}{}. ", " ".repeat(base_indent + 1), n)
+                    }
+                    None => String::new(),
+                };
+                let style = ctx.top_style();
+                ctx.segments.push((prefix, style));
+            }
+            Event::End(TagEnd::Item) => {
+                ctx.flush(max_width, theme);
+                if let Some(ListKind::Ordered(n)) = ctx.list_stack.last_mut() {
+                    *n += 1;
+                }
+                ctx.first_block = false;
+            }
+
+            // ── Inline formatting ────────────────────────────────
+            Event::Start(Tag::Strong) => {
+                let s = ctx.top_style().add_modifier(Modifier::BOLD);
+                ctx.style_stack.push(s);
+            }
+            Event::End(TagEnd::Strong) => {
+                ctx.style_stack.pop();
+            }
+
+            Event::Start(Tag::Emphasis) => {
+                let s = ctx.top_style().add_modifier(Modifier::ITALIC);
+                ctx.style_stack.push(s);
+            }
+            Event::End(TagEnd::Emphasis) => {
+                ctx.style_stack.pop();
+            }
+
+            Event::Start(Tag::Strikethrough) => {
+                let s = ctx.top_style().add_modifier(Modifier::CROSSED_OUT);
+                ctx.style_stack.push(s);
+            }
+            Event::End(TagEnd::Strikethrough) => {
+                ctx.style_stack.pop();
+            }
+
+            Event::Start(Tag::Link { .. }) => {
+                ctx.style_stack.push(theme.accent_style());
+            }
+            Event::End(TagEnd::Link) => {
+                ctx.style_stack.pop();
+            }
+
+            Event::Code(code) => {
+                ctx.segments.push((code.to_string(), theme.success_style()));
+            }
+
+            // ── Text content ─────────────────────────────────────
+            Event::Text(txt) => {
+                if ctx.in_code_block {
+                    for raw_line in txt.lines() {
+                        ctx.lines.push(highlight_code_line(raw_line, theme));
+                    }
+                } else {
+                    let style = ctx.top_style();
+                    ctx.segments.push((txt.to_string(), style));
+                }
+            }
+
+            Event::SoftBreak => {
+                if !ctx.in_code_block {
+                    let style = ctx.top_style();
+                    ctx.segments.push((" ".to_string(), style));
+                }
+            }
+            Event::HardBreak => {
+                ctx.flush(max_width, theme);
+            }
+
+            Event::Rule => {
+                if ctx.need_blank_line && !ctx.first_block {
+                    ctx.lines.push(Line::from(""));
+                }
+                let rule_width = max_width.min(60);
+                let rule = "\u{2500}".repeat(rule_width);
+                ctx.lines
+                    .push(Line::from(Span::styled(rule, theme.dim_style())));
+                ctx.need_blank_line = true;
+                ctx.first_block = false;
+            }
+
+            // Skip events we don't render (tables, footnotes, HTML, etc.)
+            _ => {}
+        }
+    }
+
+    // Flush any remaining segments.
+    ctx.flush(max_width, theme);
+
+    if ctx.lines.is_empty() {
+        ctx.lines.push(Line::from(""));
+    }
+
+    ctx.lines
+}
+
+// ── Code syntax highlighting ──────────────────────────────────────────
+
+/// Keywords highlighted with bold accent style in code blocks.
+const CODE_KEYWORDS: &[&str] = &[
+    // Rust
+    "fn", "let", "mut", "pub", "use", "struct", "enum", "impl", "trait", "for", "while", "if",
+    "else", "match", "return", "self", "Self", "async", "await", "const", "static", "type",
+    "where", "mod", "crate", "super", "true", "false", "None", "Some", "Ok", "Err",
+    // Python
+    "def", "class", "import", "from", "print", // JS/TS
+    "var", "function", "export", "default", "require",
+];
+
+/// Produce a syntax-highlighted `Line` for a single code-block line.
+///
+/// Applies basic keyword, string, comment, and number highlighting without
+/// any heavy parsing dependency.
+fn highlight_code_line(line: &str, theme: &Theme) -> Line<'static> {
+    let trimmed = line.trim_start();
+
+    // Full-line comments: `//` or `#` prefix.
+    if trimmed.starts_with("//") || trimmed.starts_with('#') {
+        return Line::from(Span::styled(line.to_string(), theme.dim_style()));
+    }
+
+    let base_style = theme.success_style();
+    let keyword_style = Style::default()
+        .fg(theme.accent.to_color())
+        .add_modifier(Modifier::BOLD);
+    let string_style = theme.warning_style();
+    let number_style = theme.accent_style();
+
+    let mut spans: Vec<Span<'static>> = Vec::new();
+    let chars: Vec<char> = line.chars().collect();
+    let len = chars.len();
+    let mut i = 0;
+
+    while i < len {
+        let ch = chars[i];
+
+        // ── Whitespace run ───────────────────────────────────
+        if ch.is_whitespace() {
+            let start = i;
+            while i < len && chars[i].is_whitespace() {
+                i += 1;
+            }
+            let s: String = chars[start..i].iter().collect();
+            spans.push(Span::styled(s, base_style));
+            continue;
+        }
+
+        // ── String literals ──────────────────────────────────
+        if ch == '"' || ch == '\'' {
+            let quote = ch;
+            let start = i;
+            i += 1;
+            while i < len {
+                if chars[i] == '\\' {
+                    i += 2; // skip escaped char
+                } else if chars[i] == quote {
+                    i += 1;
+                    break;
+                } else {
+                    i += 1;
+                }
+            }
+            let s: String = chars[start..i].iter().collect();
+            spans.push(Span::styled(s, string_style));
+            continue;
+        }
+
+        // ── Inline comment (// in the middle of a line) ──────
+        if ch == '/' && i + 1 < len && chars[i + 1] == '/' {
+            let s: String = chars[i..].iter().collect();
+            spans.push(Span::styled(s, theme.dim_style()));
+            break;
+        }
+
+        // ── Word token (identifier / keyword / number) ───────
+        if ch.is_alphanumeric() || ch == '_' {
+            let start = i;
+            while i < len && (chars[i].is_alphanumeric() || chars[i] == '_') {
+                i += 1;
+            }
+            let word: String = chars[start..i].iter().collect();
+
+            if CODE_KEYWORDS.contains(&word.as_str()) {
+                spans.push(Span::styled(word, keyword_style));
+            } else if word.chars().all(|c| c.is_ascii_digit() || c == '_') && !word.is_empty() {
+                spans.push(Span::styled(word, number_style));
+            } else {
+                spans.push(Span::styled(word, base_style));
+            }
+            continue;
+        }
+
+        // ── Punctuation / operators ──────────────────────────
+        let start = i;
+        while i < len
+            && !chars[i].is_whitespace()
+            && !chars[i].is_alphanumeric()
+            && chars[i] != '_'
+            && chars[i] != '"'
+            && chars[i] != '\''
+            && !(chars[i] == '/' && i + 1 < len && chars[i + 1] == '/')
+        {
+            i += 1;
+        }
+        if i == start {
+            // Safety: advance at least one character to avoid infinite loop.
+            i += 1;
+        }
+        let s: String = chars[start..i].iter().collect();
+        spans.push(Span::styled(s, base_style));
+    }
+
+    if spans.is_empty() {
+        Line::from(Span::styled(String::new(), base_style))
+    } else {
+        Line::from(spans)
+    }
+}
+
+/// Internal state for the markdown event walker.
+struct MdContext {
+    style_stack: Vec<Style>,
+    segments: Vec<(String, Style)>,
+    lines: Vec<Line<'static>>,
+    list_stack: Vec<ListKind>,
+    in_code_block: bool,
+    in_blockquote: bool,
+    need_blank_line: bool,
+    first_block: bool,
+}
+
+impl MdContext {
+    fn new(theme: &Theme) -> Self {
+        Self {
+            style_stack: vec![Style::default().fg(theme.fg.to_color())],
+            segments: Vec::new(),
+            lines: Vec::new(),
+            list_stack: Vec::new(),
+            in_code_block: false,
+            in_blockquote: false,
+            need_blank_line: false,
+            first_block: true,
+        }
+    }
+
+    /// Current top-of-stack style.
+    fn top_style(&self) -> Style {
+        self.style_stack.last().copied().unwrap_or_default()
+    }
+
+    /// Flush accumulated segments into word-wrapped lines.
+    fn flush(&mut self, max_width: usize, theme: &Theme) {
+        if self.segments.is_empty() {
+            return;
+        }
+        let indent = list_indent(&self.list_stack);
+        let wrapped = wrap_styled_segments(
+            std::mem::take(&mut self.segments),
+            max_width.saturating_sub(indent),
+            self.in_blockquote,
+            theme,
+        );
+        for mut line in wrapped {
+            if indent > 0 {
+                let pad = " ".repeat(indent);
+                line.spans.insert(0, Span::raw(pad));
+            }
+            self.lines.push(line);
+        }
+    }
+}
+
+/// Compute continuation-line indent based on current list nesting.
+fn list_indent(list_stack: &[ListKind]) -> usize {
+    if list_stack.is_empty() {
+        0
+    } else {
+        (list_stack.len().saturating_sub(1)) * 4
+    }
+}
+
+/// Word-wrap a sequence of styled text segments into `Line`s, respecting
+/// `max_width` using `unicode_width` for correct CJK/emoji sizing.
+///
+/// If `in_blockquote` is true, each line is prefixed with a dim `\u{2502} `.
+fn wrap_styled_segments(
+    segments: Vec<(String, Style)>,
+    max_width: usize,
+    in_blockquote: bool,
+    theme: &Theme,
+) -> Vec<Line<'static>> {
+    if max_width == 0 {
+        return vec![];
+    }
+
+    let bq_prefix_width: usize = if in_blockquote { 2 } else { 0 };
+    let effective_width = max_width.saturating_sub(bq_prefix_width);
+    if effective_width == 0 {
+        return vec![];
+    }
+
+    let mut lines: Vec<Vec<Span<'static>>> = Vec::new();
+    let mut current_spans: Vec<Span<'static>> = Vec::new();
+    let mut current_width: usize = 0;
+
+    for (text, style) in segments {
+        let words: Vec<&str> = text.split(' ').collect();
+        for (i, word) in words.iter().enumerate() {
+            if word.is_empty() && i > 0 {
+                // Preserve a single space between segments.
+                if current_width < effective_width && current_width > 0 {
+                    current_spans.push(Span::styled(" ".to_string(), style));
+                    current_width += 1;
+                }
+                continue;
+            }
+            let w = UnicodeWidthStr::width(*word);
+            if w == 0 && word.is_empty() {
+                continue;
+            }
+
+            // Need a space separator?
+            let need_space = current_width > 0 && i > 0;
+            let space_w: usize = if need_space { 1 } else { 0 };
+
+            if current_width + space_w + w <= effective_width {
+                if need_space {
+                    current_spans.push(Span::styled(" ".to_string(), style));
+                    current_width += 1;
+                }
+                current_spans.push(Span::styled(word.to_string(), style));
+                current_width += w;
+            } else if current_width == 0 {
+                // Word wider than max_width — emit as-is on its own line.
+                current_spans.push(Span::styled(word.to_string(), style));
+                lines.push(std::mem::take(&mut current_spans));
+                current_width = 0;
+            } else {
+                // Wrap: finish current line, start new one.
+                lines.push(std::mem::take(&mut current_spans));
+                current_spans.push(Span::styled(word.to_string(), style));
+                current_width = w;
+            }
+        }
+    }
+
+    if !current_spans.is_empty() {
+        lines.push(current_spans);
+    }
+
+    if lines.is_empty() {
+        lines.push(vec![Span::raw(String::new())]);
+    }
+
+    // Apply blockquote prefix if needed.
+    lines
+        .into_iter()
+        .map(|spans| {
+            if in_blockquote {
+                let mut prefixed = vec![Span::styled("\u{2502} ".to_string(), theme.dim_style())];
+                prefixed.extend(spans);
+                Line::from(prefixed)
+            } else {
+                Line::from(spans)
+            }
+        })
+        .collect()
+}
+
+/// Truncate a string to a maximum character count, appending "..." if truncated.
+pub fn truncate(s: &str, max: usize) -> String {
+    let char_count = s.chars().count();
+    if char_count <= max {
+        s.to_string()
+    } else {
+        let truncated: String = s.chars().take(max.saturating_sub(3)).collect();
+        format!("{truncated}...")
+    }
+}
+
+/// Collapse a multi-line preview into a single line for inline display.
+///
+/// Replaces newlines with spaces and collapses consecutive whitespace,
+/// then truncates to `max` characters.
+pub fn collapse_preview(s: &str, max: usize) -> String {
+    let collapsed: String = s.split_whitespace().collect::<Vec<_>>().join(" ");
+    truncate(&collapsed, max)
+}
+
+/// Format a duration in seconds to a human-readable string (e.g., "2m", "1h 5m").
+pub fn format_duration(secs: u64) -> String {
+    if secs < 60 {
+        format!("{secs}s")
+    } else if secs < 3600 {
+        format!("{}m", secs / 60)
+    } else {
+        let h = secs / 3600;
+        let m = (secs % 3600) / 60;
+        if m > 0 {
+            format!("{h}h {m}m")
+        } else {
+            format!("{h}h")
+        }
+    }
+}
+
+/// Format a tool duration in milliseconds (e.g., "37ms", "1.3s", "2m 5s").
+pub fn format_tool_duration(ms: u64) -> String {
+    if ms < 1_000 {
+        format!("{ms}ms")
+    } else if ms < 60_000 {
+        format!("{:.1}s", ms as f64 / 1_000.0)
+    } else {
+        let secs = ms / 1_000;
+        let m = secs / 60;
+        let s = secs % 60;
+        if s > 0 {
+            format!("{m}m {s}s")
+        } else {
+            format!("{m}m")
+        }
+    }
+}
+
+/// Format a token count with K/M suffix.
+pub fn format_tokens(tokens: u64) -> String {
+    if tokens < 1_000 {
+        tokens.to_string()
+    } else if tokens < 1_000_000 {
+        format!("{:.1}K", tokens as f64 / 1_000.0)
+    } else {
+        format!("{:.1}M", tokens as f64 / 1_000_000.0)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::theme::Theme;
+
+    fn line_text(line: &Line<'_>) -> String {
+        line.spans
+            .iter()
+            .map(|span| span.content.as_ref())
+            .collect::<String>()
+    }
+
+    // ── wrap_text tests ─────────────────────────────────────────
+
+    #[test]
+    fn wrap_text_no_wrapping_needed() {
+        let lines = wrap_text("short line", 80, Style::default());
+        assert_eq!(lines.len(), 1);
+    }
+
+    #[test]
+    fn wrap_text_wraps_long_line() {
+        let text = "the quick brown fox jumps over the lazy dog";
+        let lines = wrap_text(text, 20, Style::default());
+        assert!(lines.len() > 1);
+    }
+
+    #[test]
+    fn wrap_text_preserves_consecutive_spaces() {
+        let lines = wrap_text("keep  double   spaces", 80, Style::default());
+        assert_eq!(line_text(&lines[0]), "keep  double   spaces");
+    }
+
+    #[test]
+    fn wrap_text_empty() {
+        let lines = wrap_text("", 80, Style::default());
+        assert_eq!(lines.len(), 1);
+    }
+
+    #[test]
+    fn wrap_text_zero_width() {
+        let lines = wrap_text("hello", 0, Style::default());
+        assert!(lines.is_empty());
+    }
+
+    // ── truncate / format helpers ───────────────────────────────
+
+    #[test]
+    fn truncate_short_string() {
+        assert_eq!(truncate("hello", 10), "hello");
+    }
+
+    #[test]
+    fn truncate_long_string() {
+        let result = truncate("hello world this is a test", 10);
+        assert!(result.ends_with("..."));
+        assert!(result.chars().count() <= 10);
+    }
+
+    #[test]
+    fn format_duration_seconds() {
+        assert_eq!(format_duration(45), "45s");
+    }
+
+    #[test]
+    fn format_duration_minutes() {
+        assert_eq!(format_duration(120), "2m");
+    }
+
+    #[test]
+    fn format_duration_hours() {
+        assert_eq!(format_duration(3660), "1h 1m");
+    }
+
+    #[test]
+    fn format_tokens_small() {
+        assert_eq!(format_tokens(500), "500");
+    }
+
+    #[test]
+    fn format_tokens_thousands() {
+        assert_eq!(format_tokens(2100), "2.1K");
+    }
+
+    #[test]
+    fn format_tokens_millions() {
+        assert_eq!(format_tokens(1_500_000), "1.5M");
+    }
+
+    // ── render_markdown tests ───────────────────────────────────
+
+    /// Collect all text content from a slice of Lines into a single string.
+    fn lines_text(lines: &[Line<'_>]) -> String {
+        lines
+            .iter()
+            .map(|l| {
+                l.spans
+                    .iter()
+                    .map(|s| s.content.as_ref())
+                    .collect::<String>()
+            })
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+
+    /// Check whether any span in any line has the given modifier.
+    fn has_modifier(lines: &[Line<'_>], modifier: Modifier) -> bool {
+        lines.iter().any(|l| {
+            l.spans
+                .iter()
+                .any(|s| s.style.add_modifier.contains(modifier))
+        })
+    }
+
+    /// Check whether any span in any line has the given foreground color.
+    fn has_fg(lines: &[Line<'_>], color: ratatui::style::Color) -> bool {
+        lines
+            .iter()
+            .any(|l| l.spans.iter().any(|s| s.style.fg == Some(color)))
+    }
+
+    #[test]
+    fn md_plain_text() {
+        let theme = Theme::dark();
+        let lines = render_markdown("Hello world", 80, &theme);
+        assert!(lines_text(&lines).contains("Hello world"));
+    }
+
+    #[test]
+    fn md_empty_input() {
+        let theme = Theme::dark();
+        let lines = render_markdown("", 80, &theme);
+        assert_eq!(lines.len(), 1);
+    }
+
+    #[test]
+    fn md_zero_width() {
+        let theme = Theme::dark();
+        let lines = render_markdown("hello", 0, &theme);
+        assert!(lines.is_empty());
+    }
+
+    #[test]
+    fn md_bold() {
+        let theme = Theme::dark();
+        let lines = render_markdown("some **bold** text", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("bold"));
+        assert!(has_modifier(&lines, Modifier::BOLD));
+    }
+
+    #[test]
+    fn md_italic() {
+        let theme = Theme::dark();
+        let lines = render_markdown("some *italic* text", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("italic"));
+        assert!(has_modifier(&lines, Modifier::ITALIC));
+    }
+
+    #[test]
+    fn md_inline_code() {
+        let theme = Theme::dark();
+        let lines = render_markdown("run `cargo test` now", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("cargo test"));
+        assert!(has_fg(&lines, theme.success.to_color()));
+    }
+
+    #[test]
+    fn md_heading_h1() {
+        let theme = Theme::dark();
+        let lines = render_markdown("# Title", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("Title"));
+        assert!(has_modifier(&lines, Modifier::BOLD));
+        assert!(has_fg(&lines, theme.accent.to_color()));
+    }
+
+    #[test]
+    fn md_heading_h2() {
+        let theme = Theme::dark();
+        let lines = render_markdown("## Subtitle", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("Subtitle"));
+        assert!(has_modifier(&lines, Modifier::BOLD));
+        assert!(has_fg(&lines, theme.accent.to_color()));
+    }
+
+    #[test]
+    fn md_heading_h3() {
+        let theme = Theme::dark();
+        let lines = render_markdown("### Section", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("Section"));
+        assert!(has_modifier(&lines, Modifier::BOLD));
+    }
+
+    #[test]
+    fn md_unordered_list() {
+        let theme = Theme::dark();
+        let lines = render_markdown("- alpha\n- beta\n- gamma", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("\u{2022} alpha"));
+        assert!(text.contains("\u{2022} beta"));
+        assert!(text.contains("\u{2022} gamma"));
+    }
+
+    #[test]
+    fn md_ordered_list() {
+        let theme = Theme::dark();
+        let lines = render_markdown("1. first\n2. second\n3. third", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("1. first"));
+        assert!(text.contains("2. second"));
+        assert!(text.contains("3. third"));
+    }
+
+    #[test]
+    fn md_code_block() {
+        let theme = Theme::dark();
+        let lines = render_markdown("```rust\nfn main() {}\n```", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("fn main() {}"));
+        assert!(has_fg(&lines, theme.success.to_color()));
+    }
+
+    #[test]
+    fn md_blockquote() {
+        let theme = Theme::dark();
+        let lines = render_markdown("> quoted text", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("\u{2502} "));
+        assert!(text.contains("quoted text"));
+    }
+
+    #[test]
+    fn md_horizontal_rule() {
+        let theme = Theme::dark();
+        let lines = render_markdown("above\n\n---\n\nbelow", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("\u{2500}"));
+        assert!(text.contains("above"));
+        assert!(text.contains("below"));
+    }
+
+    #[test]
+    fn md_link() {
+        let theme = Theme::dark();
+        let lines = render_markdown("[click here](https://example.com)", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("click here"));
+        // URL itself should not appear in text.
+        assert!(!text.contains("https://example.com"));
+        assert!(has_fg(&lines, theme.accent.to_color()));
+    }
+
+    #[test]
+    fn md_nested_bold_italic() {
+        let theme = Theme::dark();
+        let lines = render_markdown("***bold and italic***", 80, &theme);
+        // Should have both modifiers.
+        assert!(has_modifier(&lines, Modifier::BOLD));
+        assert!(has_modifier(&lines, Modifier::ITALIC));
+    }
+
+    #[test]
+    fn md_word_wrap() {
+        let theme = Theme::dark();
+        let text = "The quick brown fox jumps over the lazy dog near the river bank";
+        let lines = render_markdown(text, 20, &theme);
+        // Should produce multiple lines.
+        assert!(lines.len() > 1);
+        // All words should still be present.
+        let joined = lines_text(&lines);
+        assert!(joined.contains("quick"));
+        assert!(joined.contains("dog"));
+    }
+
+    #[test]
+    fn md_realistic_response() {
+        let theme = Theme::dark();
+        let md = "\
+## Summary
+
+Here is a **bold** claim with `inline code`.
+
+- First item
+- Second item with *emphasis*
+
+```python
+def hello():
+    print(\"world\")
+```
+
+> A wise quote
+
+---
+
+That's all!";
+        let lines = render_markdown(md, 60, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("Summary"));
+        assert!(text.contains("bold"));
+        assert!(text.contains("inline code"));
+        assert!(text.contains("\u{2022} First item"));
+        assert!(text.contains("def hello():"));
+        assert!(text.contains("\u{2502} "));
+        assert!(text.contains("\u{2500}"));
+        assert!(text.contains("That's all!"));
+    }
+
+    #[test]
+    fn md_paragraph_separation() {
+        let theme = Theme::dark();
+        let lines = render_markdown("First paragraph.\n\nSecond paragraph.", 80, &theme);
+        // There should be a blank line between paragraphs.
+        let blank_count = lines
+            .iter()
+            .filter(|l| lines_text(&[(*l).clone()]).is_empty())
+            .count();
+        assert!(blank_count >= 1, "expected blank line between paragraphs");
+    }
+
+    #[test]
+    fn md_strikethrough() {
+        let theme = Theme::dark();
+        let lines = render_markdown("~~deleted~~", 80, &theme);
+        let text = lines_text(&lines);
+        assert!(text.contains("deleted"));
+        assert!(has_modifier(&lines, Modifier::CROSSED_OUT));
+    }
+
+    // ── highlight_code_line tests ──────────────────────────────
+
+    #[test]
+    fn highlight_comment_line() {
+        let theme = Theme::dark();
+        let line = highlight_code_line("    // this is a comment", &theme);
+        // Entire line should be dim (one span).
+        assert_eq!(line.spans.len(), 1);
+        assert_eq!(line.spans[0].style, theme.dim_style());
+    }
+
+    #[test]
+    fn highlight_hash_comment() {
+        let theme = Theme::dark();
+        let line = highlight_code_line("# comment", &theme);
+        assert_eq!(line.spans.len(), 1);
+        assert_eq!(line.spans[0].style, theme.dim_style());
+    }
+
+    #[test]
+    fn highlight_keyword() {
+        let theme = Theme::dark();
+        let line = highlight_code_line("fn main() {}", &theme);
+        let text: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
+        assert!(text.contains("fn"));
+        // The "fn" span should have bold + accent color.
+        let fn_span = line.spans.iter().find(|s| s.content.as_ref() == "fn");
+        assert!(fn_span.is_some());
+        let style = fn_span.unwrap().style;
+        assert!(style.add_modifier.contains(Modifier::BOLD));
+        assert_eq!(style.fg, Some(theme.accent.to_color()));
+    }
+
+    #[test]
+    fn highlight_string_literal() {
+        let theme = Theme::dark();
+        let line = highlight_code_line("let x = \"hello world\";", &theme);
+        let str_span = line
+            .spans
+            .iter()
+            .find(|s| s.content.as_ref().contains("hello"));
+        assert!(str_span.is_some());
+        assert_eq!(str_span.unwrap().style, theme.warning_style());
+    }
+
+    #[test]
+    fn highlight_number() {
+        let theme = Theme::dark();
+        let line = highlight_code_line("let x = 42;", &theme);
+        let num_span = line.spans.iter().find(|s| s.content.as_ref() == "42");
+        assert!(num_span.is_some());
+        assert_eq!(num_span.unwrap().style, theme.accent_style());
+    }
+
+    #[test]
+    fn highlight_preserves_indentation() {
+        let theme = Theme::dark();
+        let line = highlight_code_line("    let x = 1;", &theme);
+        let text: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
+        assert!(text.starts_with("    "));
+    }
+
+    #[test]
+    fn highlight_inline_comment() {
+        let theme = Theme::dark();
+        let line = highlight_code_line("let x = 1; // count", &theme);
+        let comment_span = line
+            .spans
+            .iter()
+            .find(|s| s.content.as_ref().contains("// count"));
+        assert!(comment_span.is_some());
+        assert_eq!(comment_span.unwrap().style, theme.dim_style());
+    }
+
+    #[test]
+    fn highlight_empty_line() {
+        let theme = Theme::dark();
+        let line = highlight_code_line("", &theme);
+        // Should produce a valid (possibly empty) line without panicking.
+        let text: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
+        assert!(text.is_empty());
+    }
+
+    #[test]
+    fn highlight_python_keywords() {
+        let theme = Theme::dark();
+        let line = highlight_code_line("def hello():", &theme);
+        let def_span = line.spans.iter().find(|s| s.content.as_ref() == "def");
+        assert!(def_span.is_some());
+        assert!(
+            def_span
+                .unwrap()
+                .style
+                .add_modifier
+                .contains(Modifier::BOLD)
+        );
+    }
+
+    #[test]
+    fn highlight_code_block_integration() {
+        let theme = Theme::dark();
+        let md = "```rust\nfn main() {\n    let x = 42;\n}\n```";
+        let lines = render_markdown(md, 80, &theme);
+        // "fn" keyword should be bold accent, not plain green.
+        let has_bold_accent = lines.iter().any(|l| {
+            l.spans.iter().any(|s| {
+                s.content.as_ref() == "fn"
+                    && s.style.add_modifier.contains(Modifier::BOLD)
+                    && s.style.fg == Some(theme.accent.to_color())
+            })
+        });
+        assert!(
+            has_bold_accent,
+            "expected 'fn' to be highlighted as keyword"
+        );
+    }
+}
diff --git a/crates/ironclaw_tui/src/spinner.rs b/crates/ironclaw_tui/src/spinner.rs
new file mode 100644
index 00000000000..11993a0dfcf
--- /dev/null
+++ b/crates/ironclaw_tui/src/spinner.rs
@@ -0,0 +1,134 @@
+//! Configurable spinner definitions inspired by <https://github.com/sindresorhus/cli-spinners>.
+//!
+//! Each [`Spinner`] has an `interval_ms` (frame duration) and a `frames` slice.
+//! The active frame is computed from elapsed time so spinners animate at their
+//! natural speed regardless of the TUI tick rate.
+
+/// A spinner animation definition.
+#[derive(Debug, Clone, Copy)]
+pub struct Spinner {
+    /// Milliseconds per frame.
+    pub interval_ms: u64,
+    /// Animation frames cycled in order.
+    pub frames: &'static [&'static str],
+}
+
+impl Spinner {
+    /// Return the frame to display given the number of TUI ticks elapsed
+    /// and the TUI tick interval in milliseconds.
+    pub fn frame(&self, tick_count: usize, tick_ms: u64) -> &'static str {
+        let elapsed_ms = tick_count as u64 * tick_ms;
+        let idx = (elapsed_ms / self.interval_ms) as usize % self.frames.len();
+        self.frames[idx]
+    }
+}
+
+/// Named spinner variant.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum SpinnerKind {
+    #[default]
+    Dots,
+    Dots2,
+    Line,
+    Arc,
+    Star,
+    Bounce,
+    BouncingBar,
+    Moon,
+    Hamburger,
+}
+
+impl SpinnerKind {
+    /// Get the [`Spinner`] definition for this variant.
+    pub fn definition(self) -> Spinner {
+        match self {
+            Self::Dots => DOTS,
+            Self::Dots2 => DOTS2,
+            Self::Line => LINE,
+            Self::Arc => ARC,
+            Self::Star => STAR,
+            Self::Bounce => BOUNCE,
+            Self::BouncingBar => BOUNCING_BAR,
+            Self::Moon => MOON,
+            Self::Hamburger => HAMBURGER,
+        }
+    }
+
+    /// All available spinner variants.
+    pub const ALL: &'static [SpinnerKind] = &[
+        Self::Dots,
+        Self::Dots2,
+        Self::Line,
+        Self::Arc,
+        Self::Star,
+        Self::Bounce,
+        Self::BouncingBar,
+        Self::Moon,
+        Self::Hamburger,
+    ];
+
+    /// Human-readable name.
+    pub fn name(self) -> &'static str {
+        match self {
+            Self::Dots => "dots",
+            Self::Dots2 => "dots2",
+            Self::Line => "line",
+            Self::Arc => "arc",
+            Self::Star => "star",
+            Self::Bounce => "bounce",
+            Self::BouncingBar => "bouncingBar",
+            Self::Moon => "moon",
+            Self::Hamburger => "hamburger",
+        }
+    }
+}
+
+// ── Spinner definitions ────────────────────────────────────────────────
+
+pub const DOTS: Spinner = Spinner {
+    interval_ms: 80,
+    frames: &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+};
+
+pub const DOTS2: Spinner = Spinner {
+    interval_ms: 80,
+    frames: &["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"],
+};
+
+pub const LINE: Spinner = Spinner {
+    interval_ms: 130,
+    frames: &["-", "\\", "|", "/"],
+};
+
+pub const ARC: Spinner = Spinner {
+    interval_ms: 100,
+    frames: &["◜", "◠", "◝", "◞", "◡", "◟"],
+};
+
+pub const STAR: Spinner = Spinner {
+    interval_ms: 70,
+    frames: &["✶", "✸", "✹", "✺", "✹", "✷"],
+};
+
+pub const BOUNCE: Spinner = Spinner {
+    interval_ms: 120,
+    frames: &["⠁", "⠂", "⠄", "⠂"],
+};
+
+pub const BOUNCING_BAR: Spinner = Spinner {
+    interval_ms: 80,
+    frames: &[
+        "[    ]", "[=   ]", "[==  ]", "[=== ]", "[ ===]", "[  ==]", "[   =]", "[    ]", "[   =]",
+        "[  ==]", "[ ===]", "[====]", "[=== ]", "[==  ]", "[=   ]",
+    ],
+};
+
+pub const MOON: Spinner = Spinner {
+    interval_ms: 80,
+    frames: &["🌑", "🌒", "🌓", "🌔", "🌕", "🌖", "🌗", "🌘"],
+};
+
+pub const HAMBURGER: Spinner = Spinner {
+    interval_ms: 100,
+    frames: &["☱", "☲", "☴"],
+};
diff --git a/crates/ironclaw_tui/src/theme.rs b/crates/ironclaw_tui/src/theme.rs
new file mode 100644
index 00000000000..7d220b496b9
--- /dev/null
+++ b/crates/ironclaw_tui/src/theme.rs
@@ -0,0 +1,197 @@
+//! Color palette and Ratatui `Style` helpers.
+//!
+//! Mirrors the design tokens from `src/cli/fmt.rs` (emerald accent, dim, success,
+//! error, warning) but expressed as Ratatui `Color` / `Style` values.
+
+use ratatui::style::{Color, Modifier, Style};
+use serde::{Deserialize, Serialize};
+
+/// Emerald green brand color (true-color).
+pub const EMERALD: Color = Color::Rgb(52, 211, 153);
+
+/// Named color palette used by the TUI.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Theme {
+    pub name: String,
+    pub bg: ThemeColor,
+    pub fg: ThemeColor,
+    pub accent: ThemeColor,
+    pub dim: ThemeColor,
+    pub success: ThemeColor,
+    pub warning: ThemeColor,
+    pub error: ThemeColor,
+    pub border: ThemeColor,
+    pub header_bg: ThemeColor,
+    pub status_bg: ThemeColor,
+}
+
+/// Serialisable color representation.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum ThemeColor {
+    Named(String),
+    Rgb { r: u8, g: u8, b: u8 },
+}
+
+impl ThemeColor {
+    pub fn to_color(&self) -> Color {
+        match self {
+            Self::Named(name) => match name.as_str() {
+                "black" => Color::Black,
+                "white" => Color::White,
+                "red" => Color::Red,
+                "green" => Color::Green,
+                "yellow" => Color::Yellow,
+                "blue" => Color::Blue,
+                "magenta" => Color::Magenta,
+                "cyan" => Color::Cyan,
+                "gray" | "grey" => Color::Gray,
+                "dark_gray" | "dark_grey" => Color::DarkGray,
+                "reset" => Color::Reset,
+                _ => Color::Reset,
+            },
+            Self::Rgb { r, g, b } => Color::Rgb(*r, *g, *b),
+        }
+    }
+}
+
+impl Default for Theme {
+    fn default() -> Self {
+        Self::dark()
+    }
+}
+
+impl Theme {
+    /// Default dark theme matching IronClaw's CLI colors.
+    pub fn dark() -> Self {
+        Self {
+            name: "dark".to_string(),
+            bg: ThemeColor::Named("reset".to_string()),
+            fg: ThemeColor::Named("white".to_string()),
+            accent: ThemeColor::Rgb {
+                r: 52,
+                g: 211,
+                b: 153,
+            },
+            dim: ThemeColor::Named("dark_gray".to_string()),
+            success: ThemeColor::Named("green".to_string()),
+            warning: ThemeColor::Named("yellow".to_string()),
+            error: ThemeColor::Named("red".to_string()),
+            border: ThemeColor::Named("dark_gray".to_string()),
+            header_bg: ThemeColor::Named("reset".to_string()),
+            status_bg: ThemeColor::Named("reset".to_string()),
+        }
+    }
+
+    /// Light theme variant.
+    pub fn light() -> Self {
+        Self {
+            name: "light".to_string(),
+            bg: ThemeColor::Named("white".to_string()),
+            fg: ThemeColor::Named("black".to_string()),
+            accent: ThemeColor::Rgb {
+                r: 16,
+                g: 163,
+                b: 127,
+            },
+            dim: ThemeColor::Named("gray".to_string()),
+            success: ThemeColor::Named("green".to_string()),
+            warning: ThemeColor::Named("yellow".to_string()),
+            error: ThemeColor::Named("red".to_string()),
+            border: ThemeColor::Named("gray".to_string()),
+            header_bg: ThemeColor::Named("white".to_string()),
+            status_bg: ThemeColor::Named("white".to_string()),
+        }
+    }
+
+    // ── Style constructors ────────────────────────────────────────
+
+    pub fn accent_style(&self) -> Style {
+        Style::default().fg(self.accent.to_color())
+    }
+
+    pub fn dim_style(&self) -> Style {
+        Style::default().fg(self.dim.to_color())
+    }
+
+    pub fn success_style(&self) -> Style {
+        Style::default().fg(self.success.to_color())
+    }
+
+    pub fn warning_style(&self) -> Style {
+        Style::default().fg(self.warning.to_color())
+    }
+
+    pub fn error_style(&self) -> Style {
+        Style::default().fg(self.error.to_color())
+    }
+
+    pub fn bold_style(&self) -> Style {
+        Style::default()
+            .fg(self.fg.to_color())
+            .add_modifier(Modifier::BOLD)
+    }
+
+    pub fn bold_accent_style(&self) -> Style {
+        Style::default()
+            .fg(self.accent.to_color())
+            .add_modifier(Modifier::BOLD)
+    }
+
+    pub fn border_style(&self) -> Style {
+        Style::default().fg(self.border.to_color())
+    }
+
+    pub fn header_style(&self) -> Style {
+        Style::default()
+            .bg(self.header_bg.to_color())
+            .fg(self.fg.to_color())
+    }
+
+    pub fn status_style(&self) -> Style {
+        Style::default()
+            .bg(self.status_bg.to_color())
+            .fg(self.dim.to_color())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn dark_theme_has_emerald_accent() {
+        let theme = Theme::dark();
+        assert_eq!(theme.accent.to_color(), EMERALD);
+    }
+
+    #[test]
+    fn light_theme_name() {
+        let theme = Theme::light();
+        assert_eq!(theme.name, "light");
+    }
+
+    #[test]
+    fn theme_color_named_round_trips() {
+        let c = ThemeColor::Named("green".to_string());
+        assert_eq!(c.to_color(), Color::Green);
+    }
+
+    #[test]
+    fn theme_color_rgb_round_trips() {
+        let c = ThemeColor::Rgb {
+            r: 10,
+            g: 20,
+            b: 30,
+        };
+        assert_eq!(c.to_color(), Color::Rgb(10, 20, 30));
+    }
+
+    #[test]
+    fn theme_serialization_round_trip() {
+        let theme = Theme::dark();
+        let json = serde_json::to_string(&theme).expect("serialize");
+        let back: Theme = serde_json::from_str(&json).expect("deserialize");
+        assert_eq!(back.name, "dark");
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/approval.rs b/crates/ironclaw_tui/src/widgets/approval.rs
new file mode 100644
index 00000000000..20084307e7c
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/approval.rs
@@ -0,0 +1,166 @@
+//! Modal overlay for tool approval dialog.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::{Alignment, Rect};
+use ratatui::style::Modifier;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Block, Borders, Clear, Paragraph, Widget};
+
+use crate::layout::TuiSlot;
+use crate::theme::Theme;
+
+use super::{AppState, TuiWidget};
+
+/// Approval action.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ApprovalAction {
+    Approve,
+    Always,
+    Deny,
+}
+
+impl ApprovalAction {
+    pub fn as_response(&self) -> &'static str {
+        match self {
+            Self::Approve => "y",
+            Self::Always => "a",
+            Self::Deny => "n",
+        }
+    }
+
+    fn label(&self) -> &'static str {
+        match self {
+            Self::Approve => "Approve (y)",
+            Self::Always => "Always approve (a)",
+            Self::Deny => "Deny (n)",
+        }
+    }
+}
+
+pub struct ApprovalWidget {
+    theme: Theme,
+}
+
+impl ApprovalWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+
+    /// Get the list of options for the current approval request.
+    pub fn options(allow_always: bool) -> Vec<ApprovalAction> {
+        if allow_always {
+            vec![
+                ApprovalAction::Approve,
+                ApprovalAction::Always,
+                ApprovalAction::Deny,
+            ]
+        } else {
+            vec![ApprovalAction::Approve, ApprovalAction::Deny]
+        }
+    }
+
+    /// Compute the centered modal area within the terminal.
+    pub fn modal_area(terminal: Rect) -> Rect {
+        let width = terminal.width.clamp(30, 60);
+        let height = terminal.height.clamp(8, 16);
+        let x = terminal.x + (terminal.width.saturating_sub(width)) / 2;
+        let y = terminal.y + (terminal.height.saturating_sub(height)) / 2;
+        Rect::new(x, y, width, height)
+    }
+}
+
+impl TuiWidget for ApprovalWidget {
+    fn id(&self) -> &str {
+        "approval"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::Tab
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        let approval = match &state.pending_approval {
+            Some(a) => a,
+            None => return,
+        };
+
+        // Clear the area behind the modal
+        Clear.render(area, buf);
+
+        let block = Block::default()
+            .title(" Tool Approval ")
+            .title_alignment(Alignment::Center)
+            .borders(Borders::ALL)
+            .border_style(self.theme.accent_style());
+
+        let inner = block.inner(area);
+        block.render(area, buf);
+
+        if inner.height == 0 || inner.width < 4 {
+            return;
+        }
+
+        let mut lines: Vec<Line<'_>> = Vec::new();
+
+        // Tool name
+        lines.push(Line::from(vec![
+            Span::styled(
+                format!(" \u{25C6} {} ", approval.tool_name),
+                self.theme.accent_style().add_modifier(Modifier::BOLD),
+            ),
+            Span::styled("requires approval", self.theme.dim_style()),
+        ]));
+        lines.push(Line::from(""));
+
+        // Parameters (simple key: value display)
+        if let Some(obj) = approval.parameters.as_object() {
+            for (key, value) in obj.iter().take(4) {
+                let val_str = match value {
+                    serde_json::Value::String(s) => {
+                        if s.len() > 40 {
+                            format!("\"{}...\"", &s[..37])
+                        } else {
+                            format!("\"{s}\"")
+                        }
+                    }
+                    other => {
+                        let rendered = other.to_string();
+                        if rendered.len() > 40 {
+                            format!("{}...", &rendered[..37])
+                        } else {
+                            rendered
+                        }
+                    }
+                };
+                lines.push(Line::from(vec![
+                    Span::styled(format!("  {key}: "), self.theme.accent_style()),
+                    Span::styled(val_str, self.theme.dim_style()),
+                ]));
+            }
+        }
+        lines.push(Line::from(""));
+
+        // Options
+        let options = Self::options(approval.allow_always);
+        for (i, opt) in options.iter().enumerate() {
+            let (icon, style) = if i == approval.selected {
+                ("\u{25CF}", self.theme.bold_accent_style())
+            } else {
+                ("\u{25CB}", self.theme.dim_style())
+            };
+            lines.push(Line::from(Span::styled(
+                format!("  {icon} {}", opt.label()),
+                style,
+            )));
+        }
+
+        lines.push(Line::from(""));
+        lines.push(Line::from(Span::styled(
+            "  \u{2191}\u{2193} select  Enter confirm  Esc cancel",
+            self.theme.dim_style(),
+        )));
+
+        let paragraph = Paragraph::new(lines);
+        paragraph.render(inner, buf);
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/command_palette.rs b/crates/ironclaw_tui/src/widgets/command_palette.rs
new file mode 100644
index 00000000000..b4029121a12
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/command_palette.rs
@@ -0,0 +1,410 @@
+//! Slash command palette overlay widget.
+//!
+//! When the user types `/` in the input box, a filtered list of available
+//! slash commands appears above the input area. Arrow keys navigate,
+//! Enter/Tab selects, Esc dismisses.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Modifier;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Clear, Widget};
+
+use crate::theme::Theme;
+
+/// A slash command entry.
+pub struct SlashCommand {
+    pub name: &'static str,
+    pub description: &'static str,
+}
+
+/// Static list of known slash commands.
+pub const COMMANDS: &[SlashCommand] = &[
+    SlashCommand {
+        name: "/help",
+        description: "Show this help",
+    },
+    SlashCommand {
+        name: "/model",
+        description: "Show or switch the active model",
+    },
+    SlashCommand {
+        name: "/version",
+        description: "Show version info",
+    },
+    SlashCommand {
+        name: "/tools",
+        description: "List available tools",
+    },
+    SlashCommand {
+        name: "/debug",
+        description: "Toggle debug mode",
+    },
+    SlashCommand {
+        name: "/ping",
+        description: "Connectivity check",
+    },
+    SlashCommand {
+        name: "/job",
+        description: "Create a new job",
+    },
+    SlashCommand {
+        name: "/status",
+        description: "Check job status",
+    },
+    SlashCommand {
+        name: "/cancel",
+        description: "Cancel a job",
+    },
+    SlashCommand {
+        name: "/list",
+        description: "List all jobs",
+    },
+    SlashCommand {
+        name: "/undo",
+        description: "Undo last turn",
+    },
+    SlashCommand {
+        name: "/redo",
+        description: "Redo undone turn",
+    },
+    SlashCommand {
+        name: "/compact",
+        description: "Compress context window",
+    },
+    SlashCommand {
+        name: "/clear",
+        description: "Clear current thread",
+    },
+    SlashCommand {
+        name: "/interrupt",
+        description: "Stop current operation",
+    },
+    SlashCommand {
+        name: "/new",
+        description: "New conversation thread",
+    },
+    SlashCommand {
+        name: "/skills",
+        description: "List installed skills",
+    },
+    SlashCommand {
+        name: "/heartbeat",
+        description: "Run heartbeat check",
+    },
+    SlashCommand {
+        name: "/summarize",
+        description: "Summarize current thread",
+    },
+    SlashCommand {
+        name: "/suggest",
+        description: "Suggest next steps",
+    },
+    SlashCommand {
+        name: "/resume",
+        description: "Resume older conversation",
+    },
+    SlashCommand {
+        name: "/quit",
+        description: "Exit",
+    },
+];
+
+/// Mutable state for the command palette.
+#[derive(Debug, Clone)]
+pub struct CommandPaletteState {
+    /// Whether the palette is visible.
+    pub visible: bool,
+    /// Text after the leading `/`, used for filtering.
+    pub filter: String,
+    /// Indices into [`COMMANDS`] that match the current filter.
+    pub filtered: Vec<usize>,
+    /// Index into `filtered` for the currently highlighted row.
+    pub selected: usize,
+}
+
+impl Default for CommandPaletteState {
+    fn default() -> Self {
+        Self {
+            visible: false,
+            filter: String::new(),
+            filtered: (0..COMMANDS.len()).collect(),
+            selected: 0,
+        }
+    }
+}
+
+impl CommandPaletteState {
+    /// Recompute `filtered` from the current `filter` text.
+    pub fn update_filter(&mut self, filter: &str) {
+        self.filter = filter.to_string();
+        let lower = filter.to_lowercase();
+        self.filtered = COMMANDS
+            .iter()
+            .enumerate()
+            .filter(|(_, cmd)| cmd.name[1..].starts_with(&lower))
+            .map(|(i, _)| i)
+            .collect();
+        // Clamp selected
+        if self.filtered.is_empty() {
+            self.selected = 0;
+        } else if self.selected >= self.filtered.len() {
+            self.selected = self.filtered.len() - 1;
+        }
+    }
+
+    /// Move selection up.
+    pub fn move_up(&mut self) {
+        if !self.filtered.is_empty() {
+            self.selected = if self.selected == 0 {
+                self.filtered.len() - 1
+            } else {
+                self.selected - 1
+            };
+        }
+    }
+
+    /// Move selection down.
+    pub fn move_down(&mut self) {
+        if !self.filtered.is_empty() {
+            self.selected = (self.selected + 1) % self.filtered.len();
+        }
+    }
+
+    /// Get the name of the currently selected command, if any.
+    pub fn selected_command(&self) -> Option<&'static str> {
+        self.filtered
+            .get(self.selected)
+            .map(|&idx| COMMANDS[idx].name)
+    }
+
+    /// Open the palette and reset state.
+    pub fn open(&mut self, filter: &str) {
+        self.visible = true;
+        self.update_filter(filter);
+    }
+
+    /// Close the palette.
+    pub fn close(&mut self) {
+        self.visible = false;
+        self.filter.clear();
+        self.filtered = (0..COMMANDS.len()).collect();
+        self.selected = 0;
+    }
+}
+
+/// Renders the command palette overlay.
+pub struct CommandPaletteWidget {
+    theme: Theme,
+}
+
+impl CommandPaletteWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+
+    /// Maximum number of visible rows.
+    const MAX_VISIBLE: usize = 12;
+
+    /// Compute the overlay area positioned directly above the input area.
+    ///
+    /// `input_area` is the full input row (including border). The palette
+    /// floats above it within `terminal`.
+    pub fn palette_area(terminal: Rect, input_area: Rect, item_count: usize) -> Rect {
+        let rows = (item_count).min(Self::MAX_VISIBLE) as u16;
+        if rows == 0 {
+            return Rect::default();
+        }
+        // 1 row top border + rows + 1 row bottom border
+        let height = rows + 2;
+        let y = input_area.y.saturating_sub(height);
+        Rect::new(terminal.x, y, terminal.width, height)
+    }
+
+    /// Render the palette into the given area using the provided state.
+    pub fn render_palette(
+        &self,
+        area: Rect,
+        buf: &mut Buffer,
+        palette_state: &CommandPaletteState,
+    ) {
+        if area.height < 3 || area.width < 10 || palette_state.filtered.is_empty() {
+            return;
+        }
+
+        // Clear background
+        Clear.render(area, buf);
+
+        // Draw top border
+        for x in area.x..area.x + area.width {
+            if let Some(cell) = buf.cell_mut((x, area.y)) {
+                cell.set_symbol("\u{2500}");
+                cell.set_style(self.theme.border_style());
+            }
+        }
+
+        // Draw bottom border
+        let bottom = area.y + area.height - 1;
+        for x in area.x..area.x + area.width {
+            if let Some(cell) = buf.cell_mut((x, bottom)) {
+                cell.set_symbol("\u{2500}");
+                cell.set_style(self.theme.border_style());
+            }
+        }
+
+        // Content area (between borders)
+        let content_area = Rect {
+            x: area.x + 1,
+            y: area.y + 1,
+            width: area.width.saturating_sub(2),
+            height: area.height.saturating_sub(2),
+        };
+
+        if content_area.width < 8 {
+            return;
+        }
+
+        // Figure out the visible window of items
+        let total = palette_state.filtered.len();
+        let max_visible = content_area.height as usize;
+
+        // Scroll so selected item is always visible
+        let scroll_offset = if palette_state.selected >= max_visible {
+            palette_state.selected - max_visible + 1
+        } else {
+            0
+        };
+
+        let visible_range = scroll_offset..total.min(scroll_offset + max_visible);
+
+        for (row_idx, filtered_idx) in visible_range.enumerate() {
+            let cmd_idx = palette_state.filtered[filtered_idx];
+            let cmd = &COMMANDS[cmd_idx];
+            let is_selected = filtered_idx == palette_state.selected;
+
+            let y = content_area.y + row_idx as u16;
+            if y >= content_area.y + content_area.height {
+                break;
+            }
+
+            // Build the line
+            let name_style = if is_selected {
+                self.theme.bold_accent_style()
+            } else {
+                self.theme.accent_style()
+            };
+            let desc_style = if is_selected {
+                self.theme.dim_style().add_modifier(Modifier::BOLD)
+            } else {
+                self.theme.dim_style()
+            };
+
+            // Pad name to fixed width for alignment
+            let name_width = 16usize.min(content_area.width as usize / 2);
+            let padded_name = format!("  {:<width$}", cmd.name, width = name_width);
+            let desc = cmd.description;
+
+            let line = Line::from(vec![
+                Span::styled(padded_name, name_style),
+                Span::styled(desc, desc_style),
+            ]);
+
+            let line_area = Rect {
+                x: content_area.x,
+                y,
+                width: content_area.width,
+                height: 1,
+            };
+
+            // If selected, fill background
+            if is_selected {
+                for bx in line_area.x..line_area.x + line_area.width {
+                    if let Some(cell) = buf.cell_mut((bx, y)) {
+                        cell.set_style(
+                            ratatui::style::Style::default().bg(self.theme.border.to_color()),
+                        );
+                    }
+                }
+            }
+
+            ratatui::widgets::Paragraph::new(line).render(line_area, buf);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn filter_matches_prefix() {
+        let mut state = CommandPaletteState::default();
+        state.update_filter("he");
+        // Should match /help and /heartbeat
+        assert_eq!(state.filtered.len(), 2);
+        let names: Vec<&str> = state.filtered.iter().map(|&i| COMMANDS[i].name).collect();
+        assert!(names.contains(&"/help"));
+        assert!(names.contains(&"/heartbeat"));
+    }
+
+    #[test]
+    fn filter_empty_matches_all() {
+        let mut state = CommandPaletteState::default();
+        state.update_filter("");
+        assert_eq!(state.filtered.len(), COMMANDS.len());
+    }
+
+    #[test]
+    fn filter_no_match() {
+        let mut state = CommandPaletteState::default();
+        state.update_filter("zzzzz");
+        assert!(state.filtered.is_empty());
+    }
+
+    #[test]
+    fn move_up_wraps() {
+        let mut state = CommandPaletteState::default();
+        state.update_filter("");
+        state.selected = 0;
+        state.move_up();
+        assert_eq!(state.selected, state.filtered.len() - 1);
+    }
+
+    #[test]
+    fn move_down_wraps() {
+        let mut state = CommandPaletteState::default();
+        state.update_filter("");
+        state.selected = state.filtered.len() - 1;
+        state.move_down();
+        assert_eq!(state.selected, 0);
+    }
+
+    #[test]
+    fn selected_command_returns_name() {
+        let mut state = CommandPaletteState::default();
+        state.update_filter("");
+        state.selected = 0;
+        assert_eq!(state.selected_command(), Some("/help"));
+    }
+
+    #[test]
+    fn filter_matches_resume() {
+        let mut state = CommandPaletteState::default();
+        state.update_filter("res");
+        let names: Vec<&str> = state.filtered.iter().map(|&i| COMMANDS[i].name).collect();
+        assert!(names.contains(&"/resume"));
+    }
+
+    #[test]
+    fn open_and_close() {
+        let mut state = CommandPaletteState::default();
+        state.open("he");
+        assert!(state.visible);
+        assert_eq!(state.filter, "he");
+        assert_eq!(state.filtered.len(), 2);
+
+        state.close();
+        assert!(!state.visible);
+        assert_eq!(state.filtered.len(), COMMANDS.len());
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/conversation.rs b/crates/ironclaw_tui/src/widgets/conversation.rs
new file mode 100644
index 00000000000..d2715a99f64
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/conversation.rs
@@ -0,0 +1,897 @@
+//! Conversation widget: renders chat messages with basic markdown.
+
+use std::sync::RwLock;
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::{Color, Style};
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Scrollbar, ScrollbarOrientation, ScrollbarState, StatefulWidget, Widget};
+
+use crate::layout::TuiSlot;
+use unicode_width::UnicodeWidthStr;
+
+use crate::render::{
+    collapse_preview, format_tokens, format_tool_duration, render_markdown, truncate, wrap_text,
+};
+use crate::theme::Theme;
+
+use super::{AppState, ChatMessage, MessageRole, ToolActivity, ToolStatus, TuiWidget};
+
+/// ASCII art startup banner displayed when the conversation is empty.
+const BANNER: &[&str] = &[
+    r"  ___                    ____ _                 ",
+    r" |_ _|_ __ ___  _ __   / ___| | __ ___      __ ",
+    r"  | || '__/ _ \| '_ \ | |   | |/ _` \ \ /\ / / ",
+    r"  | || | | (_) | | | || |___| | (_| |\ V  V /  ",
+    r" |___|_|  \___/|_| |_| \____|_|\__,_| \_/\_/   ",
+];
+
+/// Tagline shown beneath the ASCII art banner.
+const BANNER_TAGLINE: &str = "Secure AI Assistant";
+
+#[derive(Default)]
+struct ConversationRenderCache {
+    usable_width: usize,
+    messages: Vec<CachedRenderedMessage>,
+    /// Total content lines computed during last render (used for scroll clamping).
+    total_lines: usize,
+    /// Visible height during last render (used for scroll clamping).
+    visible_height: usize,
+}
+
+struct CachedRenderedMessage {
+    message: ChatMessage,
+    is_first_message: bool,
+    lines: Vec<Line<'static>>,
+}
+
+impl CachedRenderedMessage {
+    fn matches(&self, message: &ChatMessage, is_first_message: bool) -> bool {
+        self.is_first_message == is_first_message && self.message == *message
+    }
+}
+
+pub struct ConversationWidget {
+    theme: Theme,
+    render_cache: RwLock<ConversationRenderCache>,
+}
+
+impl ConversationWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self {
+            theme,
+            render_cache: RwLock::new(ConversationRenderCache::default()),
+        }
+    }
+}
+
+impl TuiWidget for ConversationWidget {
+    fn id(&self) -> &str {
+        "conversation"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::Tab
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        if area.height == 0 || area.width < 4 {
+            return;
+        }
+
+        let usable_width = (area.width as usize).saturating_sub(4);
+        let mut all_lines: Vec<Line<'static>> = Vec::new();
+
+        // Welcome block when the conversation is empty
+        if state.messages.is_empty() {
+            self.render_welcome_screen(state, usable_width, &mut all_lines);
+        }
+
+        self.append_cached_message_lines(state, usable_width, &mut all_lines);
+
+        // Inline tool calls (current turn only: tools started after last assistant message)
+        let last_assistant_ts = state
+            .messages
+            .iter()
+            .rev()
+            .find(|m| m.role == MessageRole::Assistant)
+            .map(|m| m.timestamp);
+
+        let turn_recent: Vec<&ToolActivity> = state
+            .recent_tools
+            .iter()
+            .filter(|t| match last_assistant_ts {
+                Some(ts) => t.started_at > ts,
+                None => true,
+            })
+            .collect();
+
+        if !turn_recent.is_empty() || !state.active_tools.is_empty() {
+            all_lines.push(Line::from(""));
+            for tool in &turn_recent {
+                all_lines.push(self.render_tool_line(tool, usable_width, false));
+                if let Some(ref preview) = tool.result_preview {
+                    let preview_max = usable_width.saturating_sub(8);
+                    let collapsed = collapse_preview(preview, preview_max);
+                    if !collapsed.is_empty() {
+                        all_lines.push(Line::from(vec![
+                            Span::styled("  \u{250A}   ".to_string(), self.theme.dim_style()),
+                            Span::styled("\u{2192} ".to_string(), self.theme.dim_style()),
+                            Span::styled(collapsed, self.theme.dim_style()),
+                        ]));
+                    }
+                }
+            }
+            for tool in &state.active_tools {
+                all_lines.push(self.render_tool_line(tool, usable_width, true));
+                if let Some(ref preview) = tool.result_preview {
+                    let preview_max = usable_width.saturating_sub(8);
+                    let collapsed = collapse_preview(preview, preview_max);
+                    if !collapsed.is_empty() {
+                        all_lines.push(Line::from(vec![
+                            Span::styled("  \u{250A}   ".to_string(), self.theme.dim_style()),
+                            Span::styled("\u{2192} ".to_string(), self.theme.dim_style()),
+                            Span::styled(collapsed, self.theme.dim_style()),
+                        ]));
+                    }
+                }
+            }
+        }
+
+        // Show thinking indicator if active (tick interval = 33ms)
+        const TICK_MS: u64 = 33;
+
+        if !state.status_text.is_empty() && !state.is_streaming {
+            let frame = state.spinner.frame(state.tick_count, TICK_MS);
+            all_lines.push(Line::from(vec![
+                Span::styled(format!("  {frame} "), self.theme.accent_style()),
+                Span::styled(state.status_text.clone(), self.theme.dim_style()),
+            ]));
+        }
+
+        // Show streaming dots indicator
+        if state.is_streaming {
+            let dots = match (state.tick_count / 4) % 4 {
+                0 => "\u{00B7}",
+                1 => "\u{00B7}\u{00B7}",
+                2 => "\u{00B7}\u{00B7}\u{00B7}",
+                _ => "",
+            };
+            all_lines.push(Line::from(Span::styled(
+                format!("  {dots}"),
+                self.theme.accent_style(),
+            )));
+        }
+
+        // Render follow-up suggestions when not streaming
+        if !state.suggestions.is_empty() && !state.is_streaming {
+            all_lines.push(Line::from(""));
+            all_lines.push(Line::from(Span::styled(
+                "  Suggestions:".to_string(),
+                self.theme.dim_style(),
+            )));
+            for (i, suggestion) in state.suggestions.iter().take(3).enumerate() {
+                all_lines.push(Line::from(vec![
+                    Span::styled(format!("  {} ", i + 1), self.theme.accent_style()),
+                    Span::styled(
+                        truncate(suggestion, usable_width.saturating_sub(6)),
+                        self.theme.dim_style(),
+                    ),
+                ]));
+            }
+        }
+
+        // Search highlighting: replace spans that contain the query with
+        // highlighted versions (black text on yellow background).
+        if state.search.active && !state.search.query.is_empty() {
+            let highlight_style = Style::default()
+                .fg(ratatui::style::Color::Black)
+                .bg(ratatui::style::Color::Yellow);
+            let query_lower = state.search.query.to_lowercase();
+
+            all_lines = all_lines
+                .into_iter()
+                .map(|line| {
+                    let mut new_spans: Vec<Span<'static>> = Vec::new();
+
+                    for span in line.spans {
+                        let text = span.content.to_string();
+                        let text_lower = text.to_lowercase();
+
+                        if text_lower.contains(&query_lower) {
+                            let mut remaining = text.as_str();
+                            while !remaining.is_empty() {
+                                let lower_remaining = remaining.to_lowercase();
+                                if let Some(pos) = lower_remaining.find(&query_lower) {
+                                    if pos > 0 {
+                                        new_spans.push(Span::styled(
+                                            remaining[..pos].to_string(),
+                                            span.style,
+                                        ));
+                                    }
+                                    let match_end = pos + query_lower.len();
+                                    new_spans.push(Span::styled(
+                                        remaining[pos..match_end].to_string(),
+                                        highlight_style,
+                                    ));
+                                    remaining = &remaining[match_end..];
+                                } else {
+                                    new_spans.push(Span::styled(remaining.to_string(), span.style));
+                                    break;
+                                }
+                            }
+                        } else {
+                            new_spans.push(Span::styled(text, span.style));
+                        }
+                    }
+
+                    Line::from(new_spans)
+                })
+                .collect();
+        }
+
+        // Compute visible window (scroll from bottom)
+        let visible_height = area.height as usize;
+        let total_lines = all_lines.len();
+
+        // Store for scroll clamping in scroll()
+        if let Ok(mut cache) = self.render_cache.write() {
+            cache.total_lines = total_lines;
+            cache.visible_height = visible_height;
+        }
+
+        // Clamp scroll offset to valid range
+        let max_scroll = total_lines.saturating_sub(visible_height);
+        let scroll = (state.scroll_offset as usize).min(max_scroll);
+
+        let start = total_lines.saturating_sub(visible_height + scroll);
+        let end = total_lines.saturating_sub(scroll).min(total_lines);
+
+        let mut visible: Vec<Line<'static>> = all_lines
+            .into_iter()
+            .skip(start)
+            .take(end.saturating_sub(start))
+            .collect();
+
+        // Insert search bar at top of visible area when search is active
+        if state.search.active {
+            let match_info = format!(
+                "  {}/{}",
+                if state.search.match_count > 0 {
+                    state.search.current_match + 1
+                } else {
+                    0
+                },
+                state.search.match_count
+            );
+            let search_line = Line::from(vec![
+                Span::styled(" / ", self.theme.accent_style()),
+                Span::styled(state.search.query.clone(), self.theme.bold_style()),
+                Span::styled(match_info, self.theme.dim_style()),
+            ]);
+            visible.insert(0, search_line);
+            if visible.len() > visible_height {
+                visible.pop();
+            }
+        } else if scroll > 0 && start > 0 {
+            // Scroll position indicator when not at bottom
+            let indicator = format!("\u{2191} {start} more ");
+            let indicator_line = Line::from(vec![
+                Span::styled(
+                    " ".repeat(area.width as usize - indicator.chars().count() - 1),
+                    self.theme.dim_style(),
+                ),
+                Span::styled(indicator, self.theme.dim_style()),
+            ]);
+            visible.insert(0, indicator_line);
+            if visible.len() > visible_height {
+                visible.pop();
+            }
+        }
+
+        // "↓ N more" indicator at bottom when scrolled up
+        if scroll > 0 {
+            let indicator = format!("\u{2193} {scroll} more \u{2193} End to return ");
+            if let Some(last) = visible.last_mut() {
+                let pad_len = (area.width as usize).saturating_sub(indicator.len() + 1);
+                *last = Line::from(vec![
+                    Span::styled(" ".repeat(pad_len), self.theme.dim_style()),
+                    Span::styled(indicator, self.theme.accent_style()),
+                ]);
+            }
+        }
+
+        let paragraph = ratatui::widgets::Paragraph::new(visible);
+        paragraph.render(area, buf);
+
+        // Render scrollbar when content exceeds viewport
+        if total_lines > visible_height {
+            let position = total_lines.saturating_sub(visible_height + scroll);
+            let mut scrollbar_state =
+                ScrollbarState::new(total_lines.saturating_sub(visible_height)).position(position);
+            let scrollbar = Scrollbar::new(ScrollbarOrientation::VerticalRight)
+                .begin_symbol(None)
+                .end_symbol(None)
+                .track_symbol(Some("\u{2502}"))
+                .thumb_symbol("\u{2503}");
+            scrollbar.render(area, buf, &mut scrollbar_state);
+        }
+    }
+}
+
+impl ConversationWidget {
+    fn append_cached_message_lines(
+        &self,
+        state: &AppState,
+        usable_width: usize,
+        all_lines: &mut Vec<Line<'static>>,
+    ) {
+        let mut cache = match self.render_cache.write() {
+            Ok(cache) => cache,
+            Err(poisoned) => {
+                tracing::debug!("conversation render cache lock poisoned; continuing");
+                poisoned.into_inner()
+            }
+        };
+        if cache.usable_width != usable_width {
+            cache.usable_width = usable_width;
+            cache.messages.clear();
+        }
+
+        cache.messages.truncate(state.messages.len());
+
+        for (index, message) in state.messages.iter().enumerate() {
+            let is_first_message = index == 0;
+            let needs_refresh = match cache.messages.get(index) {
+                Some(entry) => !entry.matches(message, is_first_message),
+                None => true,
+            };
+
+            if needs_refresh {
+                let rendered = CachedRenderedMessage {
+                    message: message.clone(),
+                    is_first_message,
+                    lines: self.render_message_lines(message, usable_width, is_first_message),
+                };
+
+                if index < cache.messages.len() {
+                    cache.messages[index] = rendered;
+                } else {
+                    cache.messages.push(rendered);
+                }
+            }
+
+            if let Some(entry) = cache.messages.get(index) {
+                all_lines.extend(entry.lines.iter().cloned());
+            }
+        }
+    }
+
+    fn render_message_lines(
+        &self,
+        message: &ChatMessage,
+        usable_width: usize,
+        is_first_message: bool,
+    ) -> Vec<Line<'static>> {
+        match message.role {
+            MessageRole::User => {
+                let mut lines = Vec::new();
+                if !is_first_message {
+                    lines.push(Line::from(""));
+                }
+
+                let time_str = message.timestamp.format("%H:%M").to_string();
+                lines.push(Line::from(vec![
+                    Span::styled("\u{25CF} ".to_string(), self.theme.accent_style()),
+                    Span::styled(message.content.clone(), self.theme.bold_style()),
+                    Span::styled(format!("  {time_str}"), self.theme.dim_style()),
+                ]));
+                lines.push(Line::from(""));
+                lines
+            }
+            MessageRole::Assistant => {
+                let time_str = message.timestamp.format("%H:%M").to_string();
+                let turn_label = " ironclaw ";
+                let time_label = format!(" {time_str} ");
+                let sep_left_len = 2usize;
+                let sep_right_len = usable_width
+                    .min(60)
+                    .saturating_sub(sep_left_len + turn_label.len() + time_label.len());
+                let sep_left = "\u{2500}".repeat(sep_left_len);
+                let sep_right = "\u{2500}".repeat(sep_right_len);
+                let mut lines = vec![Line::from(vec![
+                    Span::styled(format!("  {sep_left}"), self.theme.dim_style()),
+                    Span::styled(turn_label, self.theme.accent_style()),
+                    Span::styled(sep_right, self.theme.dim_style()),
+                    Span::styled(time_label, self.theme.dim_style()),
+                ])];
+
+                for line in render_markdown(
+                    &message.content,
+                    usable_width.saturating_sub(2),
+                    &self.theme,
+                ) {
+                    let mut padded = vec![Span::raw("  ".to_string())];
+                    padded.extend(line.spans);
+                    lines.push(Line::from(padded));
+                }
+
+                if let Some(ref cost) = message.cost_summary {
+                    lines.push(Line::from(Span::styled(
+                        format!(
+                            "  \u{25CB} {}in + {}out  {}",
+                            format_tokens(cost.input_tokens),
+                            format_tokens(cost.output_tokens),
+                            cost.cost_usd,
+                        ),
+                        self.theme.dim_style(),
+                    )));
+                }
+
+                lines.push(Line::from(""));
+                lines
+            }
+            MessageRole::System => {
+                let time_str = message.timestamp.format("%H:%M").to_string();
+                let mut lines = Vec::new();
+                for (index, line) in wrap_text(
+                    &message.content,
+                    usable_width.saturating_sub(8),
+                    self.theme.dim_style(),
+                )
+                .into_iter()
+                .enumerate()
+                {
+                    if index == 0 {
+                        let mut spans = line.spans;
+                        spans.push(Span::styled(
+                            format!("  {time_str}"),
+                            self.theme.dim_style(),
+                        ));
+                        lines.push(Line::from(spans));
+                    } else {
+                        lines.push(line);
+                    }
+                }
+                lines
+            }
+        }
+    }
+
+    /// Return a category-specific icon and style for the given tool name.
+    ///
+    /// Categories are detected by simple substring matching on the tool name:
+    /// - Shell/Bash (`shell`, `bash`, `exec`) -> `$` in warning/yellow
+    /// - File (`file`, `read`, `write`, `edit`) -> `\u{270E}` in success/green
+    /// - Web/HTTP (`http`, `web`, `fetch`) -> `\u{25CE}` in cyan
+    /// - Memory (`memory`, `search`) -> `\u{25C8}` in magenta
+    /// - Default -> `$` in dim style
+    fn tool_category_icon(&self, tool_name: &str) -> (&'static str, Style) {
+        let name = tool_name.to_lowercase();
+
+        if name.contains("shell") || name.contains("bash") || name.contains("exec") {
+            ("$", self.theme.warning_style())
+        } else if name.contains("file")
+            || name.contains("read")
+            || name.contains("write")
+            || name.contains("edit")
+        {
+            ("\u{270E}", self.theme.success_style()) // ✎
+        } else if name.contains("http") || name.contains("web") || name.contains("fetch") {
+            ("\u{25CE}", Style::default().fg(Color::Cyan)) // ◎
+        } else if name.contains("memory") || name.contains("search") {
+            ("\u{25C8}", Style::default().fg(Color::Magenta)) // ◈
+        } else {
+            ("$", self.theme.dim_style())
+        }
+    }
+
+    /// Render a single tool call line in the Claude Code inline style.
+    ///
+    /// Format: `  \u{250A} icon category_icon  command_text...             1.3s`
+    fn render_tool_line(
+        &self,
+        tool: &ToolActivity,
+        usable_width: usize,
+        is_active: bool,
+    ) -> Line<'static> {
+        let (icon, icon_style) = if is_active {
+            ("\u{25CB}", self.theme.accent_style()) // ○ running
+        } else {
+            match tool.status {
+                ToolStatus::Success => ("\u{25CF}", self.theme.success_style()), // ● green
+                ToolStatus::Failed => ("\u{2717}", self.theme.error_style()),    // ✗ red
+                ToolStatus::Running => ("\u{25CB}", self.theme.accent_style()),  // ○ accent
+            }
+        };
+
+        // Duration text
+        let duration_text = if is_active {
+            let elapsed = chrono::Utc::now()
+                .signed_duration_since(tool.started_at)
+                .num_milliseconds()
+                .unsigned_abs();
+            format_tool_duration(elapsed)
+        } else {
+            tool.duration_ms
+                .map(format_tool_duration)
+                .unwrap_or_default()
+        };
+
+        // Determine category icon and style from the tool name
+        let (cat_icon, cat_style) = self.tool_category_icon(&tool.name);
+
+        // Build the command description: "cat_icon  detail" or "cat_icon  tool_name"
+        let cmd_text = match &tool.detail {
+            Some(d) => format!("{cat_icon}  {d}"),
+            None => format!("{cat_icon}  {}", tool.name),
+        };
+
+        // Layout: "  \u{250A} icon  cmd...  duration"
+        //          ^2  ^2    ^cmd    ^gap ^duration
+        let prefix = format!("  \u{250A} {icon} ");
+        let prefix_width = UnicodeWidthStr::width(prefix.as_str());
+        let duration_width = UnicodeWidthStr::width(duration_text.as_str());
+        let available_for_cmd = usable_width.saturating_sub(prefix_width + duration_width + 2); // 2 for gap
+
+        let cmd_truncated = truncate(&cmd_text, available_for_cmd);
+        let cmd_width = UnicodeWidthStr::width(cmd_truncated.as_str());
+
+        // Pad between command and duration
+        let gap = usable_width
+            .saturating_sub(prefix_width + cmd_width + duration_width)
+            .max(1);
+        let padding = " ".repeat(gap);
+
+        // Split cmd_truncated into the category icon part and the rest
+        // so we can apply the category style to just the icon.
+        let (styled_icon_part, rest_part) =
+            if cmd_truncated.len() >= cat_icon.len() && cmd_truncated.starts_with(cat_icon) {
+                (
+                    cmd_truncated[..cat_icon.len()].to_string(),
+                    cmd_truncated[cat_icon.len()..].to_string(),
+                )
+            } else {
+                // Truncation cut into the icon; just dim everything
+                (String::new(), cmd_truncated)
+            };
+
+        Line::from(vec![
+            Span::styled("  \u{250A} ".to_string(), self.theme.dim_style()),
+            Span::styled(format!("{icon} "), icon_style),
+            Span::styled(styled_icon_part, cat_style),
+            Span::styled(rest_part, self.theme.dim_style()),
+            Span::raw(padding),
+            Span::styled(duration_text, self.theme.dim_style()),
+        ])
+    }
+
+    /// Render the Hermes-style welcome screen with two columns:
+    /// left = ASCII art + model info, right = tools + skills.
+    fn render_welcome_screen(
+        &self,
+        state: &AppState,
+        _usable_width: usize,
+        all_lines: &mut Vec<Line<'static>>,
+    ) {
+        let has_tools = !state.welcome_tools.is_empty();
+        let has_skills = !state.welcome_skills.is_empty();
+
+        // If no tools/skills data, fall back to simple centered layout
+        if !has_tools && !has_skills {
+            self.render_welcome_simple(state, all_lines);
+            return;
+        }
+
+        // Build left-column lines (banner + metadata)
+        let mut left_lines: Vec<Line<'static>> = Vec::new();
+
+        // ASCII banner
+        for banner_line in BANNER {
+            left_lines.push(Line::from(Span::styled(
+                (*banner_line).to_string(),
+                self.theme.accent_style(),
+            )));
+        }
+        left_lines.push(Line::from(Span::styled(
+            format!("  {BANNER_TAGLINE}"),
+            self.theme.dim_style(),
+        )));
+
+        // Padding between banner and metadata
+        left_lines.push(Line::from(""));
+        left_lines.push(Line::from(""));
+
+        // Left column width: widest banner line + some padding
+        let left_col_width = BANNER
+            .iter()
+            .map(|l| UnicodeWidthStr::width(*l))
+            .max()
+            .unwrap_or(40)
+            + 4;
+        // Max text width inside the left column (minus the 2-char indent)
+        let left_text_max = left_col_width.saturating_sub(2);
+
+        // Model + version
+        let model_text = truncate(&state.model, left_text_max);
+        left_lines.push(Line::from(vec![
+            Span::styled("  ".to_string(), Style::default()),
+            Span::styled(model_text, self.theme.accent_style()),
+        ]));
+
+        // Workspace path (truncated to fit left column)
+        if !state.workspace_path.is_empty() {
+            let path_text = truncate(&state.workspace_path, left_text_max);
+            left_lines.push(Line::from(vec![
+                Span::styled("  ".to_string(), Style::default()),
+                Span::styled(path_text, self.theme.dim_style()),
+            ]));
+        }
+
+        // Context window
+        let ctx_label = format!("{}K context", state.context_window / 1000);
+        left_lines.push(Line::from(vec![
+            Span::styled("  ".to_string(), Style::default()),
+            Span::styled(ctx_label, self.theme.dim_style()),
+        ]));
+
+        // Session ID
+        let session_id = state.session_start.format("%Y%m%d_%H%M%S").to_string();
+        left_lines.push(Line::from(vec![
+            Span::styled("  Session: ".to_string(), self.theme.dim_style()),
+            Span::styled(session_id, self.theme.dim_style()),
+        ]));
+
+        // Memory / workspace stats
+        if state.memory_count > 0 || !state.identity_files.is_empty() {
+            left_lines.push(Line::from(""));
+
+            if state.memory_count > 0 {
+                left_lines.push(Line::from(vec![
+                    Span::styled("  \u{25C8} ".to_string(), self.theme.accent_style()),
+                    Span::styled(
+                        format!("{} memories", state.memory_count),
+                        self.theme.dim_style(),
+                    ),
+                ]));
+            }
+
+            if !state.identity_files.is_empty() {
+                let files_str = state.identity_files.join(", ");
+                let files_display = truncate(&files_str, left_text_max.saturating_sub(4));
+                left_lines.push(Line::from(vec![
+                    Span::styled("  \u{25CB} ".to_string(), self.theme.accent_style()),
+                    Span::styled(files_display, self.theme.dim_style()),
+                ]));
+            }
+        }
+
+        // Build right-column lines (tools + skills)
+        let mut right_lines: Vec<Line<'static>> = Vec::new();
+
+        // Available Tools heading
+        if has_tools {
+            right_lines.push(Line::from(Span::styled(
+                "Available Tools".to_string(),
+                self.theme.bold_style(),
+            )));
+
+            let max_display = 12;
+            let tool_count = state.welcome_tools.len();
+            for cat in state.welcome_tools.iter().take(max_display) {
+                right_lines.push(Self::format_category_line(
+                    &cat.name,
+                    &cat.tools,
+                    &self.theme,
+                    true,
+                ));
+            }
+            if tool_count > max_display {
+                right_lines.push(Line::from(Span::styled(
+                    format!("(and {} more toolsets...)", tool_count - max_display),
+                    self.theme.dim_style(),
+                )));
+            }
+        }
+
+        // Blank separator
+        if has_tools && has_skills {
+            right_lines.push(Line::from(""));
+        }
+
+        // Available Skills heading
+        if has_skills {
+            right_lines.push(Line::from(Span::styled(
+                "Available Skills".to_string(),
+                self.theme.bold_style(),
+            )));
+
+            let max_display = 20;
+            let skill_count = state.welcome_skills.len();
+            for cat in state.welcome_skills.iter().take(max_display) {
+                right_lines.push(Self::format_category_line(
+                    &cat.name,
+                    &cat.skills,
+                    &self.theme,
+                    false,
+                ));
+            }
+            if skill_count > max_display {
+                right_lines.push(Line::from(Span::styled(
+                    format!("(and {} more...)", skill_count - max_display),
+                    self.theme.dim_style(),
+                )));
+            }
+        }
+
+        // Footer summary
+        let total_tools: usize = state.welcome_tools.iter().map(|c| c.tools.len()).sum();
+        let total_skills: usize = state.welcome_skills.iter().map(|c| c.skills.len()).sum();
+        right_lines.push(Line::from(""));
+        let mut footer_spans = vec![
+            Span::styled(format!("{total_tools} tools"), self.theme.accent_style()),
+            Span::styled("  \u{00B7}  ".to_string(), self.theme.dim_style()),
+            Span::styled(format!("{total_skills} skills"), self.theme.accent_style()),
+        ];
+        if state.memory_count > 0 {
+            footer_spans.push(Span::styled(
+                "  \u{00B7}  ".to_string(),
+                self.theme.dim_style(),
+            ));
+            footer_spans.push(Span::styled(
+                format!("{} memories", state.memory_count),
+                self.theme.accent_style(),
+            ));
+        }
+        footer_spans.push(Span::styled(
+            "  \u{00B7}  ".to_string(),
+            self.theme.dim_style(),
+        ));
+        footer_spans.push(Span::styled(
+            "/help for commands".to_string(),
+            self.theme.dim_style(),
+        ));
+        right_lines.push(Line::from(footer_spans));
+
+        // Compose two columns side-by-side
+        let total_rows = left_lines.len().max(right_lines.len());
+
+        for row in 0..total_rows {
+            let left = left_lines.get(row);
+            let right = right_lines.get(row);
+
+            match (left, right) {
+                (Some(l), Some(r)) => {
+                    // Compute visual width of left line
+                    let left_visual: usize = l
+                        .spans
+                        .iter()
+                        .map(|s| UnicodeWidthStr::width(s.content.as_ref()))
+                        .sum();
+                    let padding_needed = left_col_width.saturating_sub(left_visual);
+
+                    let mut spans: Vec<Span<'static>> = Vec::new();
+                    for s in &l.spans {
+                        spans.push(Span::styled(s.content.to_string(), s.style));
+                    }
+                    spans.push(Span::raw(" ".repeat(padding_needed)));
+                    for s in &r.spans {
+                        spans.push(Span::styled(s.content.to_string(), s.style));
+                    }
+                    all_lines.push(Line::from(spans));
+                }
+                (Some(l), None) => {
+                    let spans: Vec<Span<'static>> = l
+                        .spans
+                        .iter()
+                        .map(|s| Span::styled(s.content.to_string(), s.style))
+                        .collect();
+                    all_lines.push(Line::from(spans));
+                }
+                (None, Some(r)) => {
+                    let mut spans = vec![Span::raw(" ".repeat(left_col_width))];
+                    for s in &r.spans {
+                        spans.push(Span::styled(s.content.to_string(), s.style));
+                    }
+                    all_lines.push(Line::from(spans));
+                }
+                (None, None) => {}
+            }
+        }
+
+        // Trailing blank line
+        all_lines.push(Line::from(""));
+    }
+
+    /// Simple welcome screen (no tools/skills data).
+    fn render_welcome_simple(&self, state: &AppState, all_lines: &mut Vec<Line<'static>>) {
+        for banner_line in BANNER {
+            all_lines.push(Line::from(Span::styled(
+                (*banner_line).to_string(),
+                self.theme.accent_style(),
+            )));
+        }
+        all_lines.push(Line::from(Span::styled(
+            format!("  {BANNER_TAGLINE}"),
+            self.theme.dim_style(),
+        )));
+        all_lines.push(Line::from(""));
+
+        let context_label = format!("{} context", format_tokens(state.context_window));
+        all_lines.push(Line::from(vec![
+            Span::styled("  IronClaw".to_string(), self.theme.accent_style()),
+            Span::styled(format!(" v{}", state.version), self.theme.accent_style()),
+            Span::styled("  \u{00B7}  ".to_string(), self.theme.dim_style()),
+            Span::styled(state.model.clone(), self.theme.dim_style()),
+            Span::styled("  \u{00B7}  ".to_string(), self.theme.dim_style()),
+            Span::styled(context_label, self.theme.dim_style()),
+        ]));
+
+        let time_str = state.session_start.format("%H:%M UTC").to_string();
+        all_lines.push(Line::from(Span::styled(
+            format!("  Session started {time_str}"),
+            self.theme.dim_style(),
+        )));
+        all_lines.push(Line::from(""));
+        all_lines.push(Line::from(vec![
+            Span::styled(
+                "  What can I help you with?".to_string(),
+                self.theme.bold_style(),
+            ),
+            Span::styled("  /help for commands".to_string(), self.theme.dim_style()),
+        ]));
+    }
+
+    /// Format a "category: item1, item2, item3, ..." line.
+    fn format_category_line(
+        name: &str,
+        items: &[String],
+        theme: &Theme,
+        is_tool: bool,
+    ) -> Line<'static> {
+        let label_style = if is_tool {
+            theme.warning_style()
+        } else {
+            theme.accent_style()
+        };
+
+        let mut items_str = items.join(", ");
+        // Truncate if too long
+        if items_str.len() > 60 {
+            items_str.truncate(57);
+            items_str.push_str("...");
+        }
+
+        Line::from(vec![
+            Span::styled(format!("{name}: "), label_style),
+            Span::styled(items_str, theme.dim_style()),
+        ])
+    }
+
+    /// Handle scroll up/down with clamping and auto-follow management.
+    pub fn scroll(&self, state: &mut AppState, delta: i16) {
+        let max_scroll = {
+            let cache = match self.render_cache.read() {
+                Ok(c) => c,
+                Err(p) => p.into_inner(),
+            };
+            cache.total_lines.saturating_sub(cache.visible_height) as u16
+        };
+
+        if delta < 0 {
+            // Scrolling up
+            state.scroll_offset = state
+                .scroll_offset
+                .saturating_add(delta.unsigned_abs())
+                .min(max_scroll);
+            state.pinned_to_bottom = false;
+        } else {
+            // Scrolling down
+            state.scroll_offset = state.scroll_offset.saturating_sub(delta as u16);
+            if state.scroll_offset == 0 {
+                state.pinned_to_bottom = true;
+            }
+        }
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/header.rs b/crates/ironclaw_tui/src/widgets/header.rs
new file mode 100644
index 00000000000..63dc1bd4d9f
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/header.rs
@@ -0,0 +1,70 @@
+//! Header bar widget: version, model, session duration, token count.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Modifier;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::Widget;
+
+use crate::layout::TuiSlot;
+use crate::render::{format_duration, format_tokens};
+use crate::theme::Theme;
+
+use super::{AppState, TuiWidget};
+
+pub struct HeaderWidget {
+    theme: Theme,
+}
+
+impl HeaderWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+}
+
+impl TuiWidget for HeaderWidget {
+    fn id(&self) -> &str {
+        "header"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::Header
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        if area.height == 0 || area.width == 0 {
+            return;
+        }
+
+        let elapsed = chrono::Utc::now()
+            .signed_duration_since(state.session_start)
+            .num_seconds()
+            .unsigned_abs();
+        let duration = format_duration(elapsed);
+        let tokens = format_tokens(state.total_input_tokens + state.total_output_tokens);
+
+        let mut spans = vec![
+            Span::styled(
+                format!("  ironclaw v{}", state.version),
+                self.theme.accent_style().add_modifier(Modifier::BOLD),
+            ),
+            Span::styled("  ·  ", self.theme.dim_style()),
+            Span::styled(state.model.clone(), self.theme.bold_style()),
+            Span::styled("  ·  ", self.theme.dim_style()),
+            Span::styled(duration, self.theme.dim_style()),
+        ];
+
+        let total = state.total_input_tokens + state.total_output_tokens;
+        if total > 0 {
+            spans.push(Span::styled("  ·  ", self.theme.dim_style()));
+            spans.push(Span::styled(
+                format!("{tokens} tokens"),
+                self.theme.dim_style(),
+            ));
+        }
+
+        let line = Line::from(spans);
+        let widget = ratatui::widgets::Paragraph::new(line).style(self.theme.header_style());
+        widget.render(area, buf);
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/help_overlay.rs b/crates/ironclaw_tui/src/widgets/help_overlay.rs
new file mode 100644
index 00000000000..2c710080b16
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/help_overlay.rs
@@ -0,0 +1,111 @@
+//! Help overlay: F1 keybinding reference modal.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::{Modifier, Style};
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Block, Borders, Clear, Paragraph, Widget};
+
+use crate::layout::TuiSlot;
+use crate::theme::Theme;
+
+use super::{AppState, TuiWidget};
+
+/// Keybinding entries shown in the help overlay.
+const KEYBINDINGS: &[(&str, &str)] = &[
+    ("F1", "Toggle this help"),
+    ("Enter", "Submit message"),
+    ("Ctrl-C", "Quit"),
+    ("Ctrl-B", "Toggle sidebar"),
+    ("Ctrl-L", "Toggle logs"),
+    ("Ctrl-F", "Search conversation"),
+    ("Up / Down", "Input history at input edges"),
+    ("Ctrl-P / Ctrl-N", "Input history"),
+    ("Ctrl-E", "Expand tool output"),
+    ("Ctrl-V", "Paste image from clipboard"),
+    ("Mouse drag", "Select visible text and copy"),
+    ("PgUp / PgDn", "Scroll"),
+    ("Esc", "Interrupt / cancel"),
+    ("y / n / a", "Approval shortcuts"),
+    ("1-5", "Log level filter (Logs tab)"),
+];
+
+pub struct HelpOverlayWidget {
+    theme: Theme,
+}
+
+impl HelpOverlayWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+
+    /// Compute the modal area centered in the terminal.
+    pub fn modal_area(size: Rect) -> Rect {
+        let width = 52u16.min(size.width.saturating_sub(4));
+        let height = (KEYBINDINGS.len() as u16 + 4).min(size.height.saturating_sub(4));
+        let x = (size.width.saturating_sub(width)) / 2;
+        let y = (size.height.saturating_sub(height)) / 2;
+        Rect::new(x, y, width, height)
+    }
+}
+
+impl TuiWidget for HelpOverlayWidget {
+    fn id(&self) -> &str {
+        "help_overlay"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::Tab
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, _state: &AppState) {
+        if area.height < 4 || area.width < 20 {
+            return;
+        }
+
+        // Clear the area behind the modal
+        Clear.render(area, buf);
+
+        let block = Block::default()
+            .borders(Borders::ALL)
+            .border_style(self.theme.accent_style())
+            .title(Span::styled(
+                " Keyboard Shortcuts ",
+                self.theme.accent_style().add_modifier(Modifier::BOLD),
+            ));
+
+        let inner = block.inner(area);
+        block.render(area, buf);
+
+        if inner.height == 0 || inner.width < 10 {
+            return;
+        }
+
+        let key_width = 18usize;
+        let mut lines: Vec<Line<'_>> = Vec::with_capacity(KEYBINDINGS.len() + 2);
+
+        // Blank line for spacing
+        lines.push(Line::from(""));
+
+        for (key, desc) in KEYBINDINGS {
+            let padded_key = format!("  {key:<width$}", width = key_width);
+            lines.push(Line::from(vec![
+                Span::styled(
+                    padded_key,
+                    self.theme.accent_style().add_modifier(Modifier::BOLD),
+                ),
+                Span::styled(*desc, Style::default().fg(self.theme.fg.to_color())),
+            ]));
+        }
+
+        // Footer hint
+        lines.push(Line::from(""));
+        lines.push(Line::from(Span::styled(
+            "  Press F1 or Esc to close",
+            self.theme.dim_style(),
+        )));
+
+        let paragraph = Paragraph::new(lines);
+        paragraph.render(inner, buf);
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/input_box.rs b/crates/ironclaw_tui/src/widgets/input_box.rs
new file mode 100644
index 00000000000..629e2e5d697
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/input_box.rs
@@ -0,0 +1,184 @@
+//! User input area widget using tui-textarea.
+
+use ratatui::buffer::Buffer;
+use ratatui::crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
+use ratatui::layout::Rect;
+use ratatui::style::Modifier;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::Widget;
+use tui_textarea::TextArea;
+
+use crate::layout::TuiSlot;
+use crate::theme::Theme;
+
+use super::{AppState, TuiWidget};
+
+pub struct InputBoxWidget {
+    theme: Theme,
+    textarea: TextArea<'static>,
+}
+
+impl InputBoxWidget {
+    pub fn new(theme: Theme) -> Self {
+        let mut textarea = TextArea::default();
+        textarea.set_cursor_line_style(ratatui::style::Style::default());
+        textarea
+            .set_block(ratatui::widgets::Block::default().borders(ratatui::widgets::Borders::NONE));
+        textarea.set_placeholder_text("Ask anything... (/ for commands, F1 for help)");
+        textarea.set_placeholder_style(theme.dim_style());
+        Self { theme, textarea }
+    }
+
+    /// Get the current input text and clear the textarea.
+    pub fn take_input(&mut self) -> String {
+        let lines: Vec<String> = self
+            .textarea
+            .lines()
+            .iter()
+            .map(|l| l.to_string())
+            .collect();
+        let text = lines.join("\n");
+        // Clear by selecting all and deleting
+        self.textarea.select_all();
+        self.textarea.cut();
+        text
+    }
+
+    /// Returns true if the textarea is empty.
+    pub fn is_empty(&self) -> bool {
+        self.textarea.lines().iter().all(|l| l.is_empty())
+    }
+
+    /// Peek at the current text content without consuming it.
+    pub fn current_text(&self) -> String {
+        self.textarea.lines().join("\n")
+    }
+
+    /// Return the current cursor position as (row, column).
+    pub fn cursor(&self) -> (usize, usize) {
+        self.textarea.cursor()
+    }
+
+    /// Returns true when the cursor is on the first input line.
+    pub fn is_cursor_on_first_line(&self) -> bool {
+        self.cursor().0 == 0
+    }
+
+    /// Returns true when the cursor is on the last input line.
+    pub fn is_cursor_on_last_line(&self) -> bool {
+        let (row, _) = self.cursor();
+        row + 1 >= self.textarea.lines().len().max(1)
+    }
+
+    /// Replace the current text content with `text`.
+    pub fn set_text(&mut self, text: &str) {
+        self.textarea.select_all();
+        self.textarea.cut();
+        self.textarea.insert_str(text);
+    }
+
+    /// Insert text at the current cursor position.
+    pub fn insert_text(&mut self, text: &str) {
+        self.textarea.insert_str(text);
+    }
+}
+
+impl TuiWidget for InputBoxWidget {
+    fn id(&self) -> &str {
+        "input_box"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::Tab
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        if area.height == 0 || area.width < 4 {
+            return;
+        }
+
+        // If there are pending attachments, render a chip row on the first line
+        let (attachment_row_height, input_start_y) = if !state.pending_attachments.is_empty() {
+            (1u16, area.y + 1)
+        } else {
+            (0u16, area.y)
+        };
+
+        if attachment_row_height > 0 {
+            let chip_area = Rect {
+                x: area.x + 4,
+                y: area.y,
+                width: area.width.saturating_sub(4),
+                height: 1,
+            };
+            let chips: Vec<Span<'_>> = state
+                .pending_attachments
+                .iter()
+                .flat_map(|a| {
+                    vec![Span::styled(
+                        format!(" [{}] ", a.label),
+                        self.theme.accent_style().add_modifier(Modifier::BOLD),
+                    )]
+                })
+                .collect();
+            let chip_line = Line::from(chips);
+            let chip_paragraph = ratatui::widgets::Paragraph::new(chip_line);
+            chip_paragraph.render(chip_area, buf);
+        }
+
+        let remaining_area = Rect {
+            x: area.x,
+            y: input_start_y,
+            width: area.width,
+            height: area.height.saturating_sub(attachment_row_height),
+        };
+
+        // Render prompt character
+        let prompt = if state.pending_approval.is_some() {
+            "\u{25C6}"
+        } else {
+            "\u{203A}"
+        };
+
+        let prompt_span = Span::styled(
+            format!("  {prompt} "),
+            self.theme.accent_style().add_modifier(Modifier::BOLD),
+        );
+        let prompt_line = Line::from(prompt_span);
+        let prompt_widget = ratatui::widgets::Paragraph::new(prompt_line);
+
+        // Split area: prompt (4 chars) + textarea
+        if remaining_area.width > 5 {
+            let prompt_area = Rect {
+                x: remaining_area.x,
+                y: remaining_area.y,
+                width: 4,
+                height: remaining_area.height,
+            };
+            let input_area = Rect {
+                x: remaining_area.x + 4,
+                y: remaining_area.y,
+                width: remaining_area.width - 4,
+                height: remaining_area.height,
+            };
+
+            prompt_widget.render(prompt_area, buf);
+            (&self.textarea).render(input_area, buf);
+        } else {
+            prompt_widget.render(remaining_area, buf);
+        }
+    }
+
+    fn handle_key(&mut self, key: KeyEvent, _state: &mut AppState) -> bool {
+        // Don't handle Enter or Esc here — those are handled by the app
+        if key.code == KeyCode::Enter && key.modifiers == KeyModifiers::NONE {
+            return false;
+        }
+        if key.code == KeyCode::Esc {
+            return false;
+        }
+        // Let tui-textarea handle everything else
+        self.textarea.input(key);
+        true
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/logs.rs b/crates/ironclaw_tui/src/widgets/logs.rs
new file mode 100644
index 00000000000..6f793b0ecf5
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/logs.rs
@@ -0,0 +1,150 @@
+//! Logs widget: scrollable log viewer with color-coded levels.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Style;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::Widget;
+
+use crate::layout::TuiSlot;
+use crate::theme::Theme;
+
+use super::{AppState, TuiWidget};
+
+pub struct LogsWidget {
+    theme: Theme,
+}
+
+impl LogsWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+
+    /// Style for a log level string.
+    fn level_style(&self, level: &str) -> Style {
+        match level {
+            "ERROR" => self.theme.error_style(),
+            "WARN" => self.theme.warning_style(),
+            "INFO" => self.theme.success_style(),
+            _ => self.theme.dim_style(), // DEBUG, TRACE
+        }
+    }
+
+    /// Shorten an ISO 8601 timestamp to HH:MM:SS.mmm for density.
+    fn short_timestamp(ts: &str) -> &str {
+        // Input: "2024-01-01T08:00:36.095Z" → want "08:00:36.095"
+        // Find 'T' and take the next 12 chars
+        if let Some(t_pos) = ts.find('T') {
+            let after_t = &ts[t_pos + 1..];
+            let end = after_t.len().min(12);
+            &after_t[..end]
+        } else {
+            ts
+        }
+    }
+
+    /// Handle scroll in logs view.
+    pub fn scroll(state: &mut AppState, delta: i16) {
+        if delta < 0 {
+            state.log_scroll = state.log_scroll.saturating_add(delta.unsigned_abs());
+        } else {
+            state.log_scroll = state.log_scroll.saturating_sub(delta as u16);
+        }
+    }
+}
+
+impl TuiWidget for LogsWidget {
+    fn id(&self) -> &str {
+        "logs"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::Tab
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        if area.height == 0 || area.width < 10 {
+            return;
+        }
+
+        // Title line with active filter
+        let filter_label = if state.log_level_filter == crate::widgets::LogLevelFilter::All {
+            String::new()
+        } else {
+            format!(" [{}]", state.log_level_filter)
+        };
+        let title = format!(
+            " Logs ({} entries){filter_label} \u{2500} 1-5 filter \u{2500} Ctrl-L to return ",
+            state.log_entries.len()
+        );
+        let title_line = Line::from(Span::styled(title, self.theme.accent_style()));
+
+        // Build log lines
+        let usable_width = area.width as usize;
+        let mut all_lines: Vec<Line<'_>> = vec![title_line];
+
+        for entry in state
+            .log_entries
+            .iter()
+            .filter(|e| state.log_level_filter.accepts(&e.level))
+        {
+            let ts = Self::short_timestamp(&entry.timestamp);
+            let level_style = self.level_style(&entry.level);
+
+            // Truncate message to fit in available width
+            let prefix_len = ts.len() + 1 + 5 + 1; // "HH:MM:SS.mmm LEVEL "
+            let msg_width = usable_width.saturating_sub(prefix_len + 2);
+            let message = if entry.message.len() > msg_width {
+                format!("{}...", &entry.message[..msg_width.saturating_sub(3)])
+            } else {
+                entry.message.clone()
+            };
+
+            let line = Line::from(vec![
+                Span::styled(format!(" {ts} "), self.theme.dim_style()),
+                Span::styled(format!("{:<5} ", entry.level), level_style),
+                Span::styled(message, Style::default().fg(self.theme.fg.to_color())),
+            ]);
+            all_lines.push(line);
+        }
+
+        // Compute visible window (scroll from bottom)
+        let visible_height = area.height as usize;
+        let total_lines = all_lines.len();
+        let scroll = state.log_scroll as usize;
+        let start = total_lines.saturating_sub(visible_height + scroll);
+        let end = total_lines.saturating_sub(scroll).min(total_lines);
+
+        let visible: Vec<Line<'_>> = all_lines
+            .into_iter()
+            .skip(start)
+            .take(end.saturating_sub(start))
+            .collect();
+
+        let paragraph = ratatui::widgets::Paragraph::new(visible);
+        paragraph.render(area, buf);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn short_timestamp_extracts_time() {
+        assert_eq!(
+            LogsWidget::short_timestamp("2024-01-01T08:00:36.095Z"),
+            "08:00:36.095"
+        );
+    }
+
+    #[test]
+    fn short_timestamp_no_t_returns_full() {
+        assert_eq!(LogsWidget::short_timestamp("no-t-here"), "no-t-here");
+    }
+
+    #[test]
+    fn short_timestamp_short_after_t() {
+        assert_eq!(LogsWidget::short_timestamp("xT12:00"), "12:00");
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/mod.rs b/crates/ironclaw_tui/src/widgets/mod.rs
new file mode 100644
index 00000000000..952d27423ec
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/mod.rs
@@ -0,0 +1,635 @@
+//! Widget trait and built-in widget implementations.
+//!
+//! All TUI panels (header, conversation, sidebar, status bar, input) are
+//! widgets that implement [`TuiWidget`]. The trait receives a read-only
+//! reference to [`AppState`] for rendering and can optionally handle key
+//! events.
+
+pub mod approval;
+pub mod command_palette;
+pub mod conversation;
+pub mod header;
+pub mod help_overlay;
+pub mod input_box;
+pub mod logs;
+pub mod model_picker;
+pub mod registry;
+pub mod status_bar;
+pub mod tab_bar;
+pub mod thread_list;
+pub mod thread_picker;
+pub mod tool_panel;
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+
+use crate::event::LogRingBuffer;
+use crate::layout::TuiSlot;
+use crate::spinner::{Spinner, SpinnerKind};
+use command_palette::CommandPaletteState;
+use model_picker::ModelPickerState;
+
+/// Which main content tab is currently active.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ActiveTab {
+    #[default]
+    Conversation,
+    Logs,
+}
+
+/// Shared application state visible to all widgets.
+#[derive(Debug, Clone)]
+pub struct AppState {
+    /// IronClaw version string.
+    pub version: String,
+
+    /// Active LLM model name.
+    pub model: String,
+
+    /// Session start time.
+    pub session_start: chrono::DateTime<chrono::Utc>,
+
+    /// Cumulative input tokens this session.
+    pub total_input_tokens: u64,
+
+    /// Cumulative output tokens this session.
+    pub total_output_tokens: u64,
+
+    /// Cumulative cost (USD) this session.
+    pub total_cost_usd: String,
+
+    /// Conversation messages.
+    pub messages: Vec<ChatMessage>,
+
+    /// Scroll offset in the conversation (0 = bottom / most recent).
+    pub scroll_offset: u16,
+
+    /// Whether the conversation auto-scrolls to follow new content.
+    pub pinned_to_bottom: bool,
+
+    /// Maximum valid scroll offset (set during render).
+    pub max_scroll_offset: u16,
+
+    /// Last known conversation area height in rows (set during render).
+    pub conversation_height: u16,
+
+    /// Currently active tools (name -> started_at).
+    pub active_tools: Vec<ToolActivity>,
+
+    /// Recently completed tools.
+    pub recent_tools: Vec<ToolActivity>,
+
+    /// Active threads (session-level, used by /resume picker).
+    pub threads: Vec<ThreadInfo>,
+
+    /// Engine v2 threads for the activity sidebar.
+    pub engine_threads: Vec<EngineThreadInfo>,
+
+    /// Currently selected conversation thread for outbound messages.
+    pub current_thread_id: Option<String>,
+
+    /// Tracked sandbox jobs.
+    pub jobs: Vec<JobInfo>,
+
+    /// Tracked routines.
+    pub routines: Vec<RoutineInfo>,
+
+    /// Current thinking/status text.
+    pub status_text: String,
+
+    /// Whether a response is currently streaming.
+    pub is_streaming: bool,
+
+    /// Whether the sidebar is visible.
+    pub sidebar_visible: bool,
+
+    /// Pending approval request (if any).
+    pub pending_approval: Option<ApprovalRequest>,
+
+    /// Whether the TUI should quit.
+    pub should_quit: bool,
+
+    /// Currently active main content tab.
+    pub active_tab: ActiveTab,
+
+    /// Ring buffer of captured log entries.
+    pub log_entries: LogRingBuffer,
+
+    /// Scroll offset in the logs view (0 = bottom / most recent).
+    pub log_scroll: u16,
+
+    /// Maximum context window size in tokens for the active model.
+    pub context_window: u64,
+
+    /// Command palette state.
+    pub command_palette: CommandPaletteState,
+
+    /// Model picker state, triggered from `/model`.
+    pub model_picker: ModelPickerState,
+
+    /// Whether the TUI is waiting for a `/model` response to hydrate the picker.
+    pub awaiting_model_list: bool,
+
+    /// Tick counter incremented each TUI tick (used for spinner timing).
+    pub tick_count: usize,
+
+    /// Active spinner definition.
+    pub spinner: Spinner,
+
+    /// Which spinner variant is selected.
+    pub spinner_kind: SpinnerKind,
+
+    /// History of sent messages for up-arrow recall.
+    pub input_history: Vec<String>,
+    /// Current position in input history (`None` = not browsing).
+    pub history_index: Option<usize>,
+    /// Saved draft when entering history mode.
+    pub history_draft: String,
+
+    /// Suggested follow-up messages.
+    pub suggestions: Vec<String>,
+
+    /// Search state for conversation.
+    pub search: SearchState,
+
+    /// Context pressure status (derived from token usage).
+    pub context_pressure: Option<ContextPressureInfo>,
+
+    /// Sandbox / Docker status.
+    pub sandbox_status: Option<SandboxInfo>,
+
+    /// Secrets vault status.
+    pub secrets_status: Option<SecretsInfo>,
+
+    /// Cost guard / budget status.
+    pub cost_guard: Option<CostGuardInfo>,
+
+    /// Tool categories for the welcome screen.
+    pub welcome_tools: Vec<ToolCategory>,
+
+    /// Skill categories for the welcome screen.
+    pub welcome_skills: Vec<SkillCategory>,
+
+    /// Workspace directory path (for display on welcome screen).
+    pub workspace_path: String,
+
+    /// Number of memory entries in the workspace.
+    pub memory_count: usize,
+
+    /// Identity files loaded at startup (e.g. "AGENTS.md", "SOUL.md").
+    pub identity_files: Vec<String>,
+
+    /// Whether the help overlay (F1) is visible.
+    pub help_visible: bool,
+
+    /// Log level filter for the Logs tab.
+    pub log_level_filter: LogLevelFilter,
+
+    /// Active notification toasts.
+    pub toasts: Vec<Toast>,
+
+    /// Tool detail modal (Ctrl+E).
+    pub tool_detail_modal: Option<ToolDetailModal>,
+
+    /// Images pasted via Ctrl+V, pending submission with the next message.
+    pub pending_attachments: Vec<crate::event::TuiAttachment>,
+
+    /// Pending thread picker (from /resume).
+    pub pending_thread_picker: Option<ThreadPickerState>,
+
+    /// Last rendered terminal snapshot for text selection and copy.
+    pub screen_snapshot: ScreenSnapshot,
+
+    /// Active text selection in the rendered TUI.
+    pub text_selection: Option<TextSelection>,
+}
+
+/// State for the thread resume picker modal.
+#[derive(Debug, Clone)]
+pub struct ThreadPickerState {
+    /// Available threads to resume.
+    pub threads: Vec<crate::event::ThreadEntry>,
+    /// Currently selected index.
+    pub selected: usize,
+}
+
+impl Default for AppState {
+    fn default() -> Self {
+        Self {
+            version: String::new(),
+            model: String::new(),
+            session_start: chrono::Utc::now(),
+            total_input_tokens: 0,
+            total_output_tokens: 0,
+            total_cost_usd: "$0.00".to_string(),
+            messages: Vec::new(),
+            scroll_offset: 0,
+            pinned_to_bottom: true,
+            max_scroll_offset: 0,
+            conversation_height: 0,
+            active_tools: Vec::new(),
+            recent_tools: Vec::new(),
+            threads: Vec::new(),
+            engine_threads: Vec::new(),
+            current_thread_id: None,
+            jobs: Vec::new(),
+            routines: Vec::new(),
+            status_text: String::new(),
+            is_streaming: false,
+            sidebar_visible: true,
+            pending_approval: None,
+            should_quit: false,
+            active_tab: ActiveTab::default(),
+            log_entries: LogRingBuffer::new(500),
+            log_scroll: 0,
+            context_window: 128_000,
+            command_palette: CommandPaletteState::default(),
+            model_picker: ModelPickerState::default(),
+            awaiting_model_list: false,
+            tick_count: 0,
+            spinner: SpinnerKind::default().definition(),
+            spinner_kind: SpinnerKind::default(),
+            input_history: Vec::new(),
+            history_index: None,
+            history_draft: String::new(),
+            suggestions: Vec::new(),
+            search: SearchState::default(),
+            context_pressure: None,
+            sandbox_status: None,
+            secrets_status: None,
+            cost_guard: None,
+            welcome_tools: Vec::new(),
+            welcome_skills: Vec::new(),
+            workspace_path: String::new(),
+            memory_count: 0,
+            identity_files: Vec::new(),
+            help_visible: false,
+            log_level_filter: LogLevelFilter::default(),
+            toasts: Vec::new(),
+            tool_detail_modal: None,
+            pending_attachments: Vec::new(),
+            pending_thread_picker: None,
+            screen_snapshot: ScreenSnapshot::default(),
+            text_selection: None,
+        }
+    }
+}
+
+/// Last rendered terminal contents.
+#[derive(Debug, Clone)]
+pub struct ScreenSnapshot {
+    pub area: Rect,
+    pub buffer: Buffer,
+}
+
+impl Default for ScreenSnapshot {
+    fn default() -> Self {
+        let area = Rect::default();
+        Self {
+            area,
+            buffer: Buffer::empty(area),
+        }
+    }
+}
+
+/// A single terminal-cell coordinate.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct SelectionPoint {
+    pub column: u16,
+    pub row: u16,
+}
+
+/// Active text selection bounds and endpoints.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TextSelection {
+    pub anchor: SelectionPoint,
+    pub focus: SelectionPoint,
+    pub bounds: Rect,
+}
+
+/// A message in the conversation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ChatMessage {
+    pub role: MessageRole,
+    pub content: String,
+    pub timestamp: chrono::DateTime<chrono::Utc>,
+    /// Per-turn cost summary (if available).
+    pub cost_summary: Option<TurnCostSummary>,
+}
+
+/// Per-turn token usage and cost information.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TurnCostSummary {
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub cost_usd: String,
+}
+
+/// Who sent the message.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MessageRole {
+    User,
+    Assistant,
+    System,
+}
+
+/// Tool execution activity for the sidebar.
+#[derive(Debug, Clone)]
+pub struct ToolActivity {
+    pub call_id: Option<String>,
+    pub name: String,
+    pub started_at: chrono::DateTime<chrono::Utc>,
+    pub duration_ms: Option<u64>,
+    pub status: ToolStatus,
+    /// Short contextual summary (e.g., URL, path, query).
+    pub detail: Option<String>,
+    /// Brief preview of the tool's output.
+    pub result_preview: Option<String>,
+}
+
+/// Tool execution status.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ToolStatus {
+    Running,
+    Success,
+    Failed,
+}
+
+/// Status of a sandbox job.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum JobStatus {
+    #[default]
+    Pending,
+    Running,
+    Completed,
+    Failed,
+}
+
+impl std::fmt::Display for JobStatus {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Pending => write!(f, "pending"),
+            Self::Running => write!(f, "running"),
+            Self::Completed => write!(f, "done"),
+            Self::Failed => write!(f, "failed"),
+        }
+    }
+}
+
+/// A sandbox job tracked in the sidebar.
+#[derive(Debug, Clone)]
+pub struct JobInfo {
+    pub id: String,
+    pub title: String,
+    pub status: JobStatus,
+    pub started_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// A routine tracked in the sidebar.
+#[derive(Debug, Clone)]
+pub struct RoutineInfo {
+    pub id: String,
+    pub name: String,
+    pub trigger_type: String,
+    pub enabled: bool,
+    pub last_run: Option<String>,
+    pub next_fire: Option<String>,
+}
+
+/// Execution status of a thread or job.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ThreadStatus {
+    /// Currently executing work.
+    #[default]
+    Active,
+    /// Alive but waiting for input or a timer.
+    Idle,
+    /// Finished successfully.
+    Completed,
+    /// Terminated with an error.
+    Failed,
+}
+
+impl std::fmt::Display for ThreadStatus {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Active => write!(f, "active"),
+            Self::Idle => write!(f, "idle"),
+            Self::Completed => write!(f, "done"),
+            Self::Failed => write!(f, "failed"),
+        }
+    }
+}
+
+/// Thread information for the sidebar.
+#[derive(Debug, Clone)]
+pub struct ThreadInfo {
+    pub id: String,
+    pub label: String,
+    pub is_foreground: bool,
+    pub is_running: bool,
+    pub duration_secs: u64,
+    /// Richer status indicator.
+    pub status: ThreadStatus,
+    /// When the thread was created / started.
+    pub started_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Engine v2 thread information for the activity sidebar.
+#[derive(Debug, Clone)]
+pub struct EngineThreadInfo {
+    pub id: String,
+    pub goal: String,
+    /// "Foreground", "Research", or "Mission".
+    pub thread_type: String,
+    pub status: ThreadStatus,
+    pub step_count: usize,
+    pub total_tokens: u64,
+    pub started_at: Option<chrono::DateTime<chrono::Utc>>,
+    pub updated_at: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+/// Context pressure status for the status bar.
+#[derive(Debug, Clone)]
+pub struct ContextPressureInfo {
+    /// Tokens consumed so far.
+    pub used_tokens: u64,
+    /// Maximum context window.
+    pub max_tokens: u64,
+    /// Usage percentage (0–100).
+    pub percentage: u8,
+    /// Warning message when pressure is high.
+    pub warning: Option<String>,
+}
+
+/// Sandbox / Docker status for the sidebar.
+#[derive(Debug, Clone)]
+pub struct SandboxInfo {
+    /// Whether the Docker daemon is reachable.
+    pub docker_available: bool,
+    /// Number of currently running containers.
+    pub running_containers: u32,
+    /// Human-readable status summary.
+    pub status: String,
+}
+
+/// Secrets vault status for the sidebar.
+#[derive(Debug, Clone)]
+pub struct SecretsInfo {
+    /// Number of stored secrets.
+    pub count: u32,
+    /// Whether the vault is currently unlocked.
+    pub vault_unlocked: bool,
+}
+
+/// A group of tools under a shared category for the welcome screen.
+#[derive(Debug, Clone, Default)]
+pub struct ToolCategory {
+    /// Category name (e.g. "memory", "file", "browser").
+    pub name: String,
+    /// Tool names in this category.
+    pub tools: Vec<String>,
+}
+
+/// A group of skills under a shared category for the welcome screen.
+#[derive(Debug, Clone, Default)]
+pub struct SkillCategory {
+    /// Category name (e.g. "apple", "creative", "research").
+    pub name: String,
+    /// Skill names in this category.
+    pub skills: Vec<String>,
+}
+
+/// Cost guard / budget information for the status bar.
+#[derive(Debug, Clone)]
+pub struct CostGuardInfo {
+    /// Session spending budget (USD), if configured.
+    pub session_budget_usd: Option<String>,
+    /// Amount spent so far (USD).
+    pub spent_usd: String,
+    /// Amount remaining (USD), if budget is set.
+    pub remaining_usd: Option<String>,
+    /// Whether the spending limit has been reached.
+    pub limit_reached: bool,
+}
+
+/// Log level filter for the Logs tab.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum LogLevelFilter {
+    /// Show all log entries.
+    #[default]
+    All,
+    /// Show only ERROR entries.
+    Error,
+    /// Show ERROR and WARN entries.
+    Warn,
+    /// Show ERROR, WARN, and INFO entries.
+    Info,
+    /// Show everything except TRACE.
+    Debug,
+}
+
+impl std::fmt::Display for LogLevelFilter {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::All => write!(f, "ALL"),
+            Self::Error => write!(f, "ERROR"),
+            Self::Warn => write!(f, "WARN+"),
+            Self::Info => write!(f, "INFO+"),
+            Self::Debug => write!(f, "DEBUG+"),
+        }
+    }
+}
+
+impl LogLevelFilter {
+    /// Returns true if the given log level passes this filter.
+    pub fn accepts(&self, level: &str) -> bool {
+        match self {
+            Self::All => true,
+            Self::Error => level == "ERROR",
+            Self::Warn => matches!(level, "ERROR" | "WARN"),
+            Self::Info => matches!(level, "ERROR" | "WARN" | "INFO"),
+            Self::Debug => matches!(level, "ERROR" | "WARN" | "INFO" | "DEBUG"),
+        }
+    }
+}
+
+/// A notification toast displayed briefly in the bottom-right corner.
+#[derive(Debug, Clone)]
+pub struct Toast {
+    /// Short message to display.
+    pub message: String,
+    /// Visual style of the toast.
+    pub kind: ToastKind,
+    /// When the toast was created (for auto-dismiss).
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Visual style for notification toasts.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ToastKind {
+    Info,
+    Success,
+    Warning,
+    Error,
+}
+
+/// Modal showing full tool output, scrollable.
+#[derive(Debug, Clone)]
+pub struct ToolDetailModal {
+    /// Name of the tool whose output is shown.
+    pub tool_name: String,
+    /// Full tool output content.
+    pub content: String,
+    /// Scroll offset within the modal.
+    pub scroll: u16,
+}
+
+/// Search state for Ctrl+F in conversation.
+#[derive(Debug, Clone, Default)]
+pub struct SearchState {
+    /// Whether search mode is active.
+    pub active: bool,
+    /// Current search query.
+    pub query: String,
+    /// Total number of matches found.
+    pub match_count: usize,
+    /// Current match index (0-based).
+    pub current_match: usize,
+}
+
+/// Pending approval request.
+#[derive(Debug, Clone)]
+pub struct ApprovalRequest {
+    pub request_id: String,
+    pub tool_name: String,
+    pub description: String,
+    pub parameters: serde_json::Value,
+    pub allow_always: bool,
+    /// Currently selected option index (0=approve, 1=always, 2=deny).
+    pub selected: usize,
+}
+
+/// Trait implemented by all TUI widgets.
+pub trait TuiWidget: Send + Sync {
+    /// Unique widget identifier.
+    fn id(&self) -> &str;
+
+    /// Which layout slot this widget occupies.
+    fn slot(&self) -> TuiSlot;
+
+    /// Render the widget into the given area.
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState);
+
+    /// Handle a key event. Returns `true` if the event was consumed.
+    fn handle_key(
+        &mut self,
+        _key: ratatui::crossterm::event::KeyEvent,
+        _state: &mut AppState,
+    ) -> bool {
+        false
+    }
+
+    /// Called on each tick for animations or time-based updates.
+    fn tick(&mut self, _state: &AppState) {}
+}
diff --git a/crates/ironclaw_tui/src/widgets/model_picker.rs b/crates/ironclaw_tui/src/widgets/model_picker.rs
new file mode 100644
index 00000000000..5b1fabc13b7
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/model_picker.rs
@@ -0,0 +1,262 @@
+//! Model picker modal widget.
+//!
+//! Triggered from the input when the user types `/model`. The modal filters
+//! the available model list, supports arrow-key navigation, and submits the
+//! selected model back as a `/model <name>` command.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Modifier;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Block, Borders, Clear, Paragraph, Widget};
+
+use crate::theme::Theme;
+use crate::widgets::AppState;
+
+/// Mutable state for the model picker modal.
+#[derive(Debug, Clone, Default)]
+pub struct ModelPickerState {
+    /// Whether the picker is visible.
+    pub visible: bool,
+    /// Filter derived from the text after `/model`.
+    pub filter: String,
+    /// Available models from the active provider.
+    pub models: Vec<String>,
+    /// Indices into `models` that match `filter`.
+    pub filtered: Vec<usize>,
+    /// Currently highlighted row.
+    pub selected: usize,
+}
+
+impl ModelPickerState {
+    /// Create state with a known model list.
+    pub fn with_models(models: Vec<String>) -> Self {
+        let mut state = Self::default();
+        state.set_models(models);
+        state
+    }
+
+    /// Replace the available model list and reset filter state.
+    pub fn set_models(&mut self, models: Vec<String>) {
+        self.models = models;
+        self.close();
+    }
+
+    /// Whether the picker has model data to show.
+    pub fn has_models(&self) -> bool {
+        !self.models.is_empty()
+    }
+
+    /// Recompute `filtered` from the current `filter` text.
+    pub fn update_filter(&mut self, filter: &str) {
+        self.filter = filter.to_string();
+        let needle = filter.trim().to_lowercase();
+        self.filtered = self
+            .models
+            .iter()
+            .enumerate()
+            .filter(|(_, model)| needle.is_empty() || model.to_lowercase().contains(&needle))
+            .map(|(idx, _)| idx)
+            .collect();
+
+        if self.filtered.is_empty() {
+            self.selected = 0;
+            return;
+        }
+
+        if !needle.is_empty()
+            && let Some(exact_idx) = self
+                .filtered
+                .iter()
+                .position(|&idx| self.models[idx].eq_ignore_ascii_case(needle.as_str()))
+        {
+            self.selected = exact_idx;
+            return;
+        }
+
+        if self.selected >= self.filtered.len() {
+            self.selected = 0;
+        }
+    }
+
+    /// Open the picker with an optional filter.
+    pub fn open(&mut self, filter: &str) {
+        self.visible = true;
+        self.update_filter(filter);
+    }
+
+    /// Close the picker and reset the filter.
+    pub fn close(&mut self) {
+        self.visible = false;
+        self.filter.clear();
+        self.filtered = (0..self.models.len()).collect();
+        self.selected = 0;
+    }
+
+    /// Move the selection up.
+    pub fn move_up(&mut self) {
+        if self.filtered.is_empty() {
+            return;
+        }
+        self.selected = if self.selected == 0 {
+            self.filtered.len() - 1
+        } else {
+            self.selected - 1
+        };
+    }
+
+    /// Move the selection down.
+    pub fn move_down(&mut self) {
+        if self.filtered.is_empty() {
+            return;
+        }
+        self.selected = (self.selected + 1) % self.filtered.len();
+    }
+
+    /// Get the currently selected model, if any.
+    pub fn selected_model(&self) -> Option<&str> {
+        self.filtered
+            .get(self.selected)
+            .and_then(|&idx| self.models.get(idx).map(String::as_str))
+    }
+}
+
+/// Renders the model picker modal overlay.
+pub struct ModelPickerWidget {
+    theme: Theme,
+}
+
+impl ModelPickerWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+
+    /// Compute a centered modal area sized for the current model list.
+    pub fn modal_area(terminal: Rect, item_count: usize) -> Rect {
+        let width = (terminal.width * 3 / 4)
+            .max(50)
+            .min(terminal.width.saturating_sub(4));
+        let content_rows = item_count.min(12) as u16;
+        let height = (content_rows + 5)
+            .max(7)
+            .min(terminal.height.saturating_sub(4));
+        let x = (terminal.width.saturating_sub(width)) / 2;
+        let y = (terminal.height.saturating_sub(height)) / 2;
+        Rect::new(x, y, width, height)
+    }
+
+    /// Render the picker into the given area.
+    pub fn render_picker(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        let picker = &state.model_picker;
+        if !picker.visible || area.height < 7 || area.width < 24 {
+            return;
+        }
+
+        Clear.render(area, buf);
+
+        let block = Block::default()
+            .borders(Borders::ALL)
+            .border_style(self.theme.accent_style())
+            .title(Span::styled(
+                " Select model ",
+                self.theme.accent_style().add_modifier(Modifier::BOLD),
+            ));
+        let inner = block.inner(area);
+        block.render(area, buf);
+
+        if inner.height < 3 || inner.width < 10 {
+            return;
+        }
+
+        let filter_line = Line::from(vec![
+            Span::styled(" Filter: ", self.theme.dim_style()),
+            Span::styled(
+                if picker.filter.is_empty() {
+                    "all models".to_string()
+                } else {
+                    picker.filter.clone()
+                },
+                self.theme.bold_style(),
+            ),
+        ]);
+        Paragraph::new(filter_line).render(Rect::new(inner.x, inner.y, inner.width, 1), buf);
+
+        let list_top = inner.y + 1;
+        let list_height = inner.height.saturating_sub(2) as usize;
+
+        if picker.filtered.is_empty() {
+            Paragraph::new(Line::from(Span::styled(
+                " No matching models. Press Enter to submit the typed command. ",
+                self.theme.dim_style(),
+            )))
+            .render(Rect::new(inner.x, list_top, inner.width, 1), buf);
+        } else {
+            let scroll_offset = if picker.selected >= list_height {
+                picker.selected - list_height + 1
+            } else {
+                0
+            };
+            let visible_range =
+                scroll_offset..picker.filtered.len().min(scroll_offset + list_height);
+
+            for (row_idx, filtered_idx) in visible_range.enumerate() {
+                let model_idx = picker.filtered[filtered_idx];
+                let model = &picker.models[model_idx];
+                let is_selected = filtered_idx == picker.selected;
+                let is_active = model == &state.model;
+                let y = list_top + row_idx as u16;
+
+                let marker = if is_selected { "\u{25CF}" } else { "\u{25CB}" };
+                let suffix = if is_active { " (active)" } else { "" };
+                let text = format!("{marker} {model}{suffix}");
+
+                let line_area = Rect::new(inner.x, y, inner.width, 1);
+                if is_selected {
+                    for bx in line_area.x..line_area.x + line_area.width {
+                        if let Some(cell) = buf.cell_mut((bx, y)) {
+                            cell.set_style(
+                                ratatui::style::Style::default().bg(self.theme.border.to_color()),
+                            );
+                        }
+                    }
+                }
+
+                let style = if is_selected {
+                    self.theme.bold_accent_style()
+                } else if is_active {
+                    self.theme.accent_style()
+                } else {
+                    ratatui::style::Style::default().fg(self.theme.fg.to_color())
+                };
+
+                Paragraph::new(Line::from(Span::styled(text, style))).render(line_area, buf);
+            }
+        }
+
+        let footer_y = inner.y + inner.height.saturating_sub(1);
+        let footer = Line::from(Span::styled(
+            " \u{2191}\u{2193} select  Enter choose  Esc cancel ",
+            self.theme.dim_style(),
+        ));
+        Paragraph::new(footer).render(Rect::new(inner.x, footer_y, inner.width, 1), buf);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::ModelPickerState;
+
+    #[test]
+    fn filter_uses_contains_and_exact_match_selection() {
+        let mut state = ModelPickerState::with_models(vec![
+            "gpt-4o".to_string(),
+            "gpt-5".to_string(),
+            "claude-sonnet-4-6".to_string(),
+        ]);
+
+        state.update_filter("gpt-5");
+
+        assert_eq!(state.filtered.len(), 1);
+        assert_eq!(state.selected_model(), Some("gpt-5"));
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/registry.rs b/crates/ironclaw_tui/src/widgets/registry.rs
new file mode 100644
index 00000000000..e1ee2f6430b
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/registry.rs
@@ -0,0 +1,82 @@
+//! Widget registry: loads widget configuration from workspace.
+//!
+//! In Phase 1, this is a simple factory that creates the built-in widgets.
+//! Future phases will support loading custom widget manifests from
+//! `tui/widgets/{id}/manifest.json` in the workspace.
+
+use crate::layout::TuiLayout;
+
+use super::TuiWidget;
+use super::command_palette::CommandPaletteWidget;
+use super::conversation::ConversationWidget;
+use super::header::HeaderWidget;
+use super::help_overlay::HelpOverlayWidget;
+use super::input_box::InputBoxWidget;
+use super::logs::LogsWidget;
+use super::model_picker::ModelPickerWidget;
+use super::status_bar::StatusBarWidget;
+use super::tab_bar::TabBarWidget;
+use super::thread_list::ThreadListWidget;
+use super::thread_picker::ThreadPickerWidget;
+use super::tool_panel::ToolPanelWidget;
+
+/// Create the default set of built-in widgets.
+pub fn create_default_widgets(layout: &TuiLayout) -> BuiltinWidgets {
+    let theme = layout.resolve_theme();
+
+    BuiltinWidgets {
+        header: HeaderWidget::new(theme.clone()),
+        tab_bar: TabBarWidget::new(theme.clone()),
+        conversation: ConversationWidget::new(theme.clone()),
+        logs: LogsWidget::new(theme.clone()),
+        input_box: InputBoxWidget::new(theme.clone()),
+        status_bar: StatusBarWidget::new(theme.clone()),
+        tool_panel: ToolPanelWidget::new(theme.clone()),
+        thread_list: ThreadListWidget::new(theme.clone()),
+        approval: super::approval::ApprovalWidget::new(theme.clone()),
+        help: HelpOverlayWidget::new(theme.clone()),
+        thread_picker: ThreadPickerWidget::new(theme.clone()),
+        model_picker: ModelPickerWidget::new(theme.clone()),
+        command_palette: CommandPaletteWidget::new(theme),
+    }
+}
+
+/// Container for all built-in widgets.
+///
+/// We use concrete types instead of `Box<dyn TuiWidget>` so callers can
+/// access widget-specific methods (e.g., `input_box.take_input()`).
+pub struct BuiltinWidgets {
+    pub header: HeaderWidget,
+    pub tab_bar: TabBarWidget,
+    pub conversation: ConversationWidget,
+    pub logs: LogsWidget,
+    pub input_box: InputBoxWidget,
+    pub status_bar: StatusBarWidget,
+    pub tool_panel: ToolPanelWidget,
+    pub thread_list: ThreadListWidget,
+    pub approval: super::approval::ApprovalWidget,
+    pub help: HelpOverlayWidget,
+    pub thread_picker: ThreadPickerWidget,
+    pub model_picker: ModelPickerWidget,
+    pub command_palette: CommandPaletteWidget,
+}
+
+/// Get references to all widgets as trait objects for generic iteration.
+impl BuiltinWidgets {
+    pub fn all(&self) -> Vec<&dyn TuiWidget> {
+        vec![
+            &self.header,
+            &self.tab_bar,
+            &self.conversation,
+            &self.logs,
+            &self.input_box,
+            &self.status_bar,
+            &self.tool_panel,
+            &self.thread_list,
+            &self.approval,
+            &self.help,
+        ]
+        // Note: command_palette is not included here because it renders
+        // via a custom method (render_palette) rather than the TuiWidget trait.
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/status_bar.rs b/crates/ironclaw_tui/src/widgets/status_bar.rs
new file mode 100644
index 00000000000..0d9fa3a7e4b
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/status_bar.rs
@@ -0,0 +1,254 @@
+//! Status bar widget: model, tokens, context bar, cost, session duration, keybind hints.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::{Alignment, Rect};
+use ratatui::text::{Line, Span};
+use ratatui::widgets::Widget;
+
+use crate::layout::TuiSlot;
+use crate::render::{format_duration, format_tokens};
+use crate::theme::Theme;
+
+use super::{ActiveTab, AppState, TuiWidget};
+
+pub struct StatusBarWidget {
+    theme: Theme,
+}
+
+impl StatusBarWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+}
+
+/// Build a text-based progress bar: `[████░░░░░░░░░░]`
+fn context_bar(ratio: f64, width: usize) -> String {
+    let filled = ((ratio * width as f64).round() as usize).min(width);
+    let empty = width.saturating_sub(filled);
+    let mut bar = String::with_capacity(width + 2);
+    bar.push('[');
+    for _ in 0..filled {
+        bar.push('\u{2588}'); // █
+    }
+    for _ in 0..empty {
+        bar.push(' ');
+    }
+    bar.push(']');
+    bar
+}
+
+impl TuiWidget for StatusBarWidget {
+    fn id(&self) -> &str {
+        "status_bar"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::StatusBarLeft
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        if area.height == 0 || area.width == 0 {
+            return;
+        }
+
+        // Use actual context pressure data from the engine when available;
+        // fall back to cumulative session tokens before the first update arrives.
+        let (used_tokens, max_tokens, pct) = if let Some(ref cp) = state.context_pressure {
+            (cp.used_tokens, cp.max_tokens, cp.percentage as u64)
+        } else {
+            let total = state.total_input_tokens + state.total_output_tokens;
+            let ctx = state.context_window;
+            let p = if ctx > 0 {
+                ((total as f64 / ctx as f64).clamp(0.0, 1.0) * 100.0).round() as u64
+            } else {
+                0
+            };
+            (total, ctx, p)
+        };
+        let tokens_used_str = format_tokens(used_tokens);
+        let context_max_str = format_tokens(max_tokens);
+        let ratio = if max_tokens > 0 {
+            (used_tokens as f64 / max_tokens as f64).clamp(0.0, 1.0)
+        } else {
+            0.0
+        };
+
+        // Session duration
+        let elapsed = chrono::Utc::now()
+            .signed_duration_since(state.session_start)
+            .num_seconds()
+            .unsigned_abs();
+        let duration_str = format_duration(elapsed);
+
+        let sep = Span::styled(" \u{2502} ", self.theme.dim_style());
+
+        let tab_label = match state.active_tab {
+            ActiveTab::Conversation => "[Chat]",
+            ActiveTab::Logs => "[Logs]",
+        };
+
+        // Bar width adapts to terminal: use ~16 chars on wide terminals, less on narrow
+        let bar_width = if area.width > 100 {
+            16
+        } else if area.width > 60 {
+            10
+        } else {
+            6
+        };
+        let bar_str = context_bar(ratio, bar_width);
+
+        // Color the bar based on usage
+        let bar_style = if pct >= 90 {
+            self.theme.error_style()
+        } else if pct >= 70 {
+            self.theme.warning_style()
+        } else {
+            self.theme.accent_style()
+        };
+
+        let mut left_spans = vec![
+            Span::styled(format!(" {tab_label} "), self.theme.bold_accent_style()),
+            sep.clone(),
+            Span::styled(state.model.to_string(), self.theme.accent_style()),
+            sep.clone(),
+            Span::styled(format!("v{}", state.version), self.theme.dim_style()),
+        ];
+
+        // Fleet/activity summary: active tools and threads
+        let tool_count = state.active_tools.len();
+        let thread_count = state.threads.len();
+        if tool_count > 0 || thread_count > 0 {
+            left_spans.push(sep.clone());
+            let mut parts: Vec<Span> = Vec::new();
+            if tool_count > 0 {
+                parts.push(Span::styled(
+                    format!("\u{26A1}{tool_count} tools"),
+                    self.theme.accent_style(),
+                ));
+            }
+            if tool_count > 0 && thread_count > 0 {
+                parts.push(Span::styled(" \u{00B7} ", self.theme.dim_style()));
+            }
+            if thread_count > 0 {
+                parts.push(Span::styled(
+                    format!("\u{25C6}{thread_count} threads"),
+                    self.theme.dim_style(),
+                ));
+            }
+            left_spans.extend(parts);
+        }
+
+        // Context pressure: tokens + visual bar
+        left_spans.extend([
+            sep.clone(),
+            Span::styled(
+                format!("{tokens_used_str}/{context_max_str}"),
+                self.theme.dim_style(),
+            ),
+            sep.clone(),
+            Span::styled(bar_str, bar_style),
+            Span::styled(format!(" {pct}%"), self.theme.dim_style()),
+        ]);
+
+        // Context pressure warning when usage is high
+        if let Some(ref cp) = state.context_pressure {
+            if let Some(ref warning) = cp.warning {
+                left_spans.push(Span::styled(
+                    format!(" {warning}"),
+                    if cp.percentage >= 90 {
+                        self.theme.error_style()
+                    } else {
+                        self.theme.warning_style()
+                    },
+                ));
+            }
+        } else if pct >= 90 {
+            left_spans.push(Span::styled(" CRITICAL", self.theme.error_style()));
+        } else if pct >= 70 {
+            left_spans.push(Span::styled(" HIGH", self.theme.warning_style()));
+        }
+
+        // Cost: show session spending, and budget if available
+        if let Some(ref cg) = state.cost_guard {
+            left_spans.push(sep.clone());
+            if let Some(ref budget) = cg.session_budget_usd {
+                // Show spent/budget with color coding
+                let cost_style = if cg.limit_reached {
+                    self.theme.error_style()
+                } else {
+                    self.theme.dim_style()
+                };
+                left_spans.push(Span::styled(
+                    format!("{}/{budget}", cg.spent_usd),
+                    cost_style,
+                ));
+                if cg.limit_reached {
+                    left_spans.push(Span::styled(" LIMIT", self.theme.error_style()));
+                }
+            } else {
+                left_spans.push(Span::styled(cg.spent_usd.clone(), self.theme.dim_style()));
+            }
+        } else if state.total_cost_usd != "$0.00" {
+            left_spans.push(sep.clone());
+            left_spans.push(Span::styled(
+                state.total_cost_usd.clone(),
+                self.theme.dim_style(),
+            ));
+        }
+
+        left_spans.push(sep);
+        left_spans.push(Span::styled(duration_str, self.theme.dim_style()));
+
+        let right_text = "^L logs  ^B sidebar  ^C quit";
+        let right_span = Span::styled(format!("{right_text}  "), self.theme.dim_style());
+
+        // Render left-aligned portion
+        let left_line = Line::from(left_spans);
+        let left_widget =
+            ratatui::widgets::Paragraph::new(left_line).style(self.theme.status_style());
+        left_widget.render(area, buf);
+
+        // Render right-aligned keybind hints
+        let right_line = Line::from(right_span);
+        let right_widget = ratatui::widgets::Paragraph::new(right_line)
+            .alignment(Alignment::Right)
+            .style(self.theme.status_style());
+        right_widget.render(area, buf);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn context_bar_empty() {
+        let bar = context_bar(0.0, 10);
+        assert_eq!(bar, "[          ]");
+    }
+
+    #[test]
+    fn context_bar_full() {
+        let bar = context_bar(1.0, 10);
+        assert_eq!(
+            bar,
+            "[\u{2588}\u{2588}\u{2588}\u{2588}\u{2588}\u{2588}\u{2588}\u{2588}\u{2588}\u{2588}]"
+        );
+    }
+
+    #[test]
+    fn context_bar_half() {
+        let bar = context_bar(0.5, 10);
+        // 5 filled + 5 empty
+        assert_eq!(bar.chars().count(), 12); // [ + 10 + ]
+        assert!(bar.starts_with("[\u{2588}"));
+        assert!(bar.ends_with(" ]"));
+    }
+
+    #[test]
+    fn context_bar_clamped_over_1() {
+        let bar = context_bar(1.5, 10);
+        // Should be same as 1.0
+        assert_eq!(bar, context_bar(1.0, 10));
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/tab_bar.rs b/crates/ironclaw_tui/src/widgets/tab_bar.rs
new file mode 100644
index 00000000000..f41696c3b82
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/tab_bar.rs
@@ -0,0 +1,64 @@
+//! Tab bar widget: shows [Chat] [Logs] tabs with the active one highlighted.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Modifier;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::Widget;
+
+use crate::layout::TuiSlot;
+use crate::theme::Theme;
+
+use super::{ActiveTab, AppState, TuiWidget};
+
+pub struct TabBarWidget {
+    theme: Theme,
+}
+
+impl TabBarWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+}
+
+impl TuiWidget for TabBarWidget {
+    fn id(&self) -> &str {
+        "tab_bar"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::Tab
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        if area.height == 0 || area.width < 12 {
+            return;
+        }
+
+        let (chat_style, logs_style) = match state.active_tab {
+            ActiveTab::Conversation => (
+                self.theme
+                    .accent_style()
+                    .add_modifier(Modifier::BOLD | Modifier::UNDERLINED),
+                self.theme.dim_style(),
+            ),
+            ActiveTab::Logs => (
+                self.theme.dim_style(),
+                self.theme
+                    .accent_style()
+                    .add_modifier(Modifier::BOLD | Modifier::UNDERLINED),
+            ),
+        };
+
+        let line = Line::from(vec![
+            Span::styled("  ", self.theme.dim_style()),
+            Span::styled("Chat", chat_style),
+            Span::styled("  ", self.theme.dim_style()),
+            Span::styled("Logs", logs_style),
+            Span::styled("  ", self.theme.dim_style()),
+        ]);
+
+        let paragraph = ratatui::widgets::Paragraph::new(line);
+        paragraph.render(area, buf);
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/thread_list.rs b/crates/ironclaw_tui/src/widgets/thread_list.rs
new file mode 100644
index 00000000000..7ecde929b00
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/thread_list.rs
@@ -0,0 +1,772 @@
+//! Activity sidebar panel — jobs, routines, and threads.
+//!
+//! Renders a compact status table with three sections:
+//!
+//! ```text
+//! JOBS (2) ─────────────
+//! ● build-frontend  running  3m
+//! ✓ daily-sync      done     15m
+//!
+//! ROUTINES (1) ─────────
+//! ◆ issue-watch  github→issue  on
+//!
+//! THREADS (1) ──────────
+//! ● main           active   2m
+//! ```
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Modifier;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Block, Borders, Widget};
+
+use crate::layout::TuiSlot;
+use crate::render::truncate;
+use crate::theme::Theme;
+
+use super::{AppState, JobStatus, ThreadStatus, TuiWidget};
+
+/// Compact type tag for engine thread types.
+fn thread_type_tag(thread_type: &str) -> &str {
+    match thread_type {
+        "Foreground" => "[FG]",
+        "Research" => "[R]",
+        "Mission" => "[M]",
+        _ => "[?]",
+    }
+}
+
+/// Status icon for each job state.
+fn job_icon(status: JobStatus) -> &'static str {
+    match status {
+        JobStatus::Pending => "\u{25CB}",   // ○
+        JobStatus::Running => "\u{25CF}",   // ●
+        JobStatus::Completed => "\u{2713}", // ✓
+        JobStatus::Failed => "\u{2717}",    // ✗
+    }
+}
+
+/// Status icon for each thread state.
+fn thread_icon(status: ThreadStatus) -> &'static str {
+    match status {
+        ThreadStatus::Active => "\u{25CF}",    // ●
+        ThreadStatus::Idle => "\u{25CB}",      // ○
+        ThreadStatus::Completed => "\u{2713}", // ✓
+        ThreadStatus::Failed => "\u{2717}",    // ✗
+    }
+}
+
+/// Format a duration in seconds into a compact human-readable string.
+fn format_uptime(secs: u64) -> String {
+    if secs < 60 {
+        format!("{secs}s")
+    } else if secs < 3600 {
+        format!("{}m", secs / 60)
+    } else {
+        let h = secs / 3600;
+        let m = (secs % 3600) / 60;
+        if m > 0 {
+            format!("{h}h {m}m")
+        } else {
+            format!("{h}h")
+        }
+    }
+}
+
+/// Resolve which engine thread row was clicked inside the activity sidebar.
+pub(crate) fn engine_thread_index_at(
+    area: Rect,
+    state: &AppState,
+    column: u16,
+    row: u16,
+) -> Option<usize> {
+    if area.height < 3 || area.width < 6 {
+        return None;
+    }
+
+    let inner = Rect::new(
+        area.x.saturating_add(1),
+        area.y.saturating_add(1),
+        area.width.saturating_sub(2),
+        area.height.saturating_sub(2),
+    );
+    if inner.height == 0 || inner.width == 0 {
+        return None;
+    }
+
+    let within_inner = column >= inner.x
+        && column < inner.x + inner.width
+        && row >= inner.y
+        && row < inner.y + inner.height;
+    if !within_inner {
+        return None;
+    }
+
+    let has_any_data = !state.jobs.is_empty()
+        || !state.routines.is_empty()
+        || !state.engine_threads.is_empty()
+        || state.sandbox_status.is_some()
+        || state.secrets_status.is_some();
+    if !has_any_data || state.engine_threads.is_empty() {
+        return None;
+    }
+
+    let mut line_index = 0usize;
+    let system_items =
+        state.sandbox_status.is_some() as usize + state.secrets_status.is_some() as usize;
+    if system_items > 0 {
+        line_index += 1 + system_items + 1;
+    }
+
+    line_index += 1 + state.jobs.len().max(1);
+    line_index += 1 + state.routines.len().max(1);
+
+    let thread_rows_start = line_index + 1;
+    let clicked_line = row.checked_sub(inner.y)? as usize;
+    let thread_index = clicked_line.checked_sub(thread_rows_start)?;
+    state.engine_threads.get(thread_index)?;
+    Some(thread_index)
+}
+
+pub struct ThreadListWidget {
+    theme: Theme,
+}
+
+impl ThreadListWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+
+    /// Pick the style for a job status icon and text.
+    fn job_status_style(&self, status: JobStatus) -> ratatui::style::Style {
+        match status {
+            JobStatus::Pending => self.theme.dim_style(),
+            JobStatus::Running => self.theme.accent_style(),
+            JobStatus::Completed => self.theme.success_style(),
+            JobStatus::Failed => self.theme.error_style(),
+        }
+    }
+
+    /// Pick the style for a thread's status icon and text.
+    fn thread_status_style(&self, status: ThreadStatus) -> ratatui::style::Style {
+        match status {
+            ThreadStatus::Active => self.theme.accent_style(),
+            ThreadStatus::Idle => self.theme.dim_style(),
+            ThreadStatus::Completed => self.theme.success_style(),
+            ThreadStatus::Failed => self.theme.error_style(),
+        }
+    }
+
+    /// Render a section header: " LABEL (count) ────"
+    fn render_section_header<'a>(&self, label: &str, count: usize, width: usize) -> Line<'a> {
+        let header_text = format!(" {label} ({count})");
+        let rule_len = width.saturating_sub(header_text.len() + 1);
+        let rule = if rule_len > 0 {
+            format!(" {}", "\u{2500}".repeat(rule_len))
+        } else {
+            String::new()
+        };
+        Line::from(vec![
+            Span::styled(header_text, self.theme.bold_style()),
+            Span::styled(rule, self.theme.dim_style()),
+        ])
+    }
+}
+
+impl TuiWidget for ThreadListWidget {
+    fn id(&self) -> &str {
+        "thread_list"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::SidebarSection
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        if area.height == 0 || area.width < 6 {
+            return;
+        }
+
+        // Bordered block with "Activity" title
+        let block = Block::default()
+            .borders(Borders::ALL)
+            .border_style(self.theme.border_style())
+            .title(Span::styled(
+                " Activity ",
+                self.theme.accent_style().add_modifier(Modifier::BOLD),
+            ));
+        let inner = block.inner(area);
+        block.render(area, buf);
+
+        if inner.height == 0 || inner.width < 4 {
+            return;
+        }
+
+        let width = inner.width as usize;
+        let mut lines: Vec<Line<'_>> = Vec::new();
+
+        // Column layout: " {icon} {name}  {status}  {uptime}"
+        let fixed_cols: usize = 3 + 6 + 8 + 4; // icon + status + uptime + spacing
+        let max_name_len = width.saturating_sub(fixed_cols).max(4);
+
+        let now = chrono::Utc::now();
+
+        // Global empty state hint
+        let has_any_data = !state.jobs.is_empty()
+            || !state.routines.is_empty()
+            || !state.engine_threads.is_empty()
+            || state.sandbox_status.is_some()
+            || state.secrets_status.is_some();
+        if !has_any_data {
+            lines.push(Line::from(Span::styled(
+                " No active jobs or routines",
+                self.theme.dim_style(),
+            )));
+            let paragraph = ratatui::widgets::Paragraph::new(lines);
+            paragraph.render(inner, buf);
+            return;
+        }
+
+        // ── SYSTEM section ────────────────────────────────────────────
+        let system_items =
+            state.sandbox_status.is_some() as usize + state.secrets_status.is_some() as usize;
+        if system_items > 0 {
+            lines.push(self.render_section_header("SYSTEM", system_items, width));
+
+            if let Some(ref sandbox) = state.sandbox_status {
+                let (icon, style) = if sandbox.docker_available {
+                    ("\u{25CF}", self.theme.success_style()) // ●
+                } else {
+                    ("\u{25CB}", self.theme.dim_style()) // ○
+                };
+                let label = if sandbox.running_containers > 0 {
+                    format!("Docker  {} containers", sandbox.running_containers)
+                } else {
+                    format!("Docker  {}", sandbox.status)
+                };
+                lines.push(Line::from(vec![
+                    Span::styled(format!(" {icon} "), style),
+                    Span::styled(label, style),
+                ]));
+            }
+
+            if let Some(ref secrets) = state.secrets_status {
+                let (icon, style) = if secrets.vault_unlocked {
+                    ("\u{1F513}", self.theme.success_style()) // 🔓
+                } else {
+                    ("\u{1F512}", self.theme.dim_style()) // 🔒
+                };
+                let label = format!("Secrets  {} stored", secrets.count);
+                let status = if secrets.vault_unlocked {
+                    "unlocked"
+                } else {
+                    "locked"
+                };
+                lines.push(Line::from(vec![
+                    Span::styled(format!(" {icon} "), style),
+                    Span::styled(label, self.theme.bold_style()),
+                    Span::raw("  "),
+                    Span::styled(status.to_string(), style),
+                ]));
+            }
+
+            lines.push(Line::from(""));
+        }
+
+        // ── JOBS section ──────────────────────────────────────────────
+        lines.push(self.render_section_header("JOBS", state.jobs.len(), width));
+
+        if state.jobs.is_empty() {
+            lines.push(Line::from(Span::styled(
+                " (no jobs)",
+                self.theme.dim_style(),
+            )));
+        }
+
+        for job in &state.jobs {
+            let style = self.job_status_style(job.status);
+            let icon = job_icon(job.status);
+
+            let uptime_secs = now
+                .signed_duration_since(job.started_at)
+                .num_seconds()
+                .max(0) as u64;
+            let uptime = format_uptime(uptime_secs);
+
+            let name = truncate(&job.title, max_name_len);
+            let padded_name = format!("{:<width$}", name, width = max_name_len);
+            let status_text = format!("{}", job.status);
+
+            lines.push(Line::from(vec![
+                Span::styled(format!(" {icon} "), style),
+                Span::styled(padded_name, self.theme.bold_style()),
+                Span::raw("  "),
+                Span::styled(format!("{:<6}", status_text), style),
+                Span::raw("  "),
+                Span::styled(uptime, self.theme.dim_style()),
+            ]));
+        }
+
+        // ── ROUTINES section ──────────────────────────────────────────
+        lines.push(self.render_section_header("ROUTINES", state.routines.len(), width));
+
+        if state.routines.is_empty() {
+            lines.push(Line::from(Span::styled(
+                " (no routines)",
+                self.theme.dim_style(),
+            )));
+        }
+
+        // Routines layout: " ◆ {name}  {trigger}  {on/off}"
+        let routine_fixed: usize = 3 + 12 + 5; // icon + trigger + on/off + spacing
+        let routine_name_len = width.saturating_sub(routine_fixed).max(4);
+
+        for routine in &state.routines {
+            let icon = "\u{25C6}"; // ◆
+            let style = if routine.enabled {
+                self.theme.accent_style()
+            } else {
+                self.theme.dim_style()
+            };
+
+            let name = truncate(&routine.name, routine_name_len);
+            let padded_name = format!("{:<width$}", name, width = routine_name_len);
+            let trigger = truncate(&routine.trigger_type, 10);
+            let enabled_text = if routine.enabled { "on" } else { "off" };
+
+            lines.push(Line::from(vec![
+                Span::styled(format!(" {icon} "), style),
+                Span::styled(padded_name, self.theme.bold_style()),
+                Span::raw("  "),
+                Span::styled(format!("{:<10}", trigger), self.theme.dim_style()),
+                Span::raw("  "),
+                Span::styled(enabled_text.to_string(), style),
+            ]));
+        }
+
+        // ── THREADS section (engine v2) ──────────────────────────────
+        lines.push(self.render_section_header("THREADS", state.engine_threads.len(), width));
+
+        if state.engine_threads.is_empty() {
+            lines.push(Line::from(Span::styled(
+                " (no threads)",
+                self.theme.dim_style(),
+            )));
+        }
+
+        // Column layout accounts for type tag: " {icon} {tag} {goal}  {status}  {uptime}"
+        let tag_width: usize = 5; // "[FG] " is the widest tag + space
+        let thread_name_len = max_name_len.saturating_sub(tag_width);
+
+        for thread in &state.engine_threads {
+            let style = self.thread_status_style(thread.status);
+            let icon = thread_icon(thread.status);
+
+            let uptime = thread
+                .started_at
+                .map(|started_at| {
+                    let uptime_secs = now.signed_duration_since(started_at).num_seconds().max(0);
+                    format_uptime(uptime_secs as u64)
+                })
+                .unwrap_or_else(|| "?".to_string());
+
+            let tag = thread_type_tag(&thread.thread_type);
+            let goal = truncate(&thread.goal, thread_name_len);
+            let padded_goal = format!("{:<width$}", goal, width = thread_name_len);
+            let status_text = format!("{}", thread.status);
+
+            lines.push(Line::from(vec![
+                Span::styled(format!(" {icon} "), style),
+                Span::styled(format!("{tag:<4} "), self.theme.dim_style()),
+                Span::styled(padded_goal, self.theme.bold_style()),
+                Span::raw("  "),
+                Span::styled(format!("{:<6}", status_text), style),
+                Span::raw("  "),
+                Span::styled(uptime, self.theme.dim_style()),
+            ]));
+        }
+
+        let visible: Vec<Line<'_>> = lines.into_iter().take(inner.height as usize).collect();
+        let paragraph = ratatui::widgets::Paragraph::new(visible);
+        paragraph.render(inner, buf);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::theme::Theme;
+    use crate::widgets::{
+        AppState, EngineThreadInfo, JobInfo, JobStatus, RoutineInfo, ThreadStatus,
+    };
+    use ratatui::buffer::Buffer;
+    use ratatui::layout::Rect;
+
+    fn make_state() -> AppState {
+        AppState::default()
+    }
+
+    fn render_to_buffer(widget: &ThreadListWidget, state: &AppState, w: u16, h: u16) -> Buffer {
+        let area = Rect::new(0, 0, w, h);
+        let mut buf = Buffer::empty(area);
+        widget.render(area, &mut buf, state);
+        buf
+    }
+
+    fn buffer_text(buf: &Buffer) -> String {
+        let area = buf.area;
+        let mut text = String::new();
+        for y in area.top()..area.bottom() {
+            for x in area.left()..area.right() {
+                text.push_str(buf[(x, y)].symbol());
+            }
+            text.push('\n');
+        }
+        text
+    }
+
+    #[test]
+    fn empty_state_shows_all_sections() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let state = make_state();
+        let buf = render_to_buffer(&widget, &state, 40, 10);
+        let text = buffer_text(&buf);
+        // With no data at all, the widget shows an empty-state message
+        assert!(text.contains("No active jobs or routines"));
+    }
+
+    #[test]
+    fn renders_jobs_section() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.jobs = vec![
+            JobInfo {
+                id: "j1".to_string(),
+                title: "build-frontend".to_string(),
+                status: JobStatus::Running,
+                started_at: chrono::Utc::now() - chrono::Duration::seconds(180),
+            },
+            JobInfo {
+                id: "j2".to_string(),
+                title: "daily-sync".to_string(),
+                status: JobStatus::Completed,
+                started_at: chrono::Utc::now() - chrono::Duration::seconds(900),
+            },
+        ];
+        let buf = render_to_buffer(&widget, &state, 50, 12);
+        let text = buffer_text(&buf);
+        assert!(text.contains("JOBS (2)"));
+        assert!(text.contains("build-frontend"));
+        assert!(text.contains("running"));
+        assert!(text.contains("daily-sync"));
+        assert!(text.contains("done"));
+    }
+
+    #[test]
+    fn renders_routines_section() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.routines = vec![RoutineInfo {
+            id: "r1".to_string(),
+            name: "issue-watch".to_string(),
+            trigger_type: "github".to_string(),
+            enabled: true,
+            last_run: None,
+            next_fire: None,
+        }];
+        let buf = render_to_buffer(&widget, &state, 50, 12);
+        let text = buffer_text(&buf);
+        assert!(text.contains("ROUTINES (1)"));
+        assert!(text.contains("issue-watch"));
+        assert!(text.contains("github"));
+        assert!(text.contains("on"));
+    }
+
+    #[test]
+    fn renders_disabled_routine() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.routines = vec![RoutineInfo {
+            id: "r1".to_string(),
+            name: "backup".to_string(),
+            trigger_type: "cron".to_string(),
+            enabled: false,
+            last_run: None,
+            next_fire: None,
+        }];
+        let buf = render_to_buffer(&widget, &state, 50, 12);
+        let text = buffer_text(&buf);
+        assert!(text.contains("off"));
+    }
+
+    #[test]
+    fn renders_threads_section() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.engine_threads = vec![EngineThreadInfo {
+            id: "t1".to_string(),
+            goal: "fix login bug".to_string(),
+            thread_type: "Foreground".to_string(),
+            status: ThreadStatus::Active,
+            step_count: 5,
+            total_tokens: 1200,
+            started_at: Some(chrono::Utc::now() - chrono::Duration::seconds(120)),
+            updated_at: Some(chrono::Utc::now()),
+        }];
+        let buf = render_to_buffer(&widget, &state, 50, 12);
+        let text = buffer_text(&buf);
+        assert!(text.contains("THREADS (1)"));
+        assert!(text.contains("[FG]"));
+        assert!(text.contains("fix login bug"));
+        assert!(text.contains("active"));
+        assert!(text.contains("\u{25CF}")); // ● icon
+    }
+
+    #[test]
+    fn renders_all_three_sections() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let now = chrono::Utc::now();
+        let mut state = make_state();
+        state.jobs = vec![JobInfo {
+            id: "j1".to_string(),
+            title: "build".to_string(),
+            status: JobStatus::Running,
+            started_at: now - chrono::Duration::seconds(60),
+        }];
+        state.routines = vec![RoutineInfo {
+            id: "r1".to_string(),
+            name: "watch".to_string(),
+            trigger_type: "event".to_string(),
+            enabled: true,
+            last_run: None,
+            next_fire: None,
+        }];
+        state.engine_threads = vec![EngineThreadInfo {
+            id: "t1".to_string(),
+            goal: "deploy".to_string(),
+            thread_type: "Mission".to_string(),
+            status: ThreadStatus::Active,
+            step_count: 2,
+            total_tokens: 500,
+            started_at: Some(now - chrono::Duration::seconds(30)),
+            updated_at: Some(now),
+        }];
+        let buf = render_to_buffer(&widget, &state, 50, 15);
+        let text = buffer_text(&buf);
+        assert!(text.contains("JOBS (1)"));
+        assert!(text.contains("build"));
+        assert!(text.contains("ROUTINES (1)"));
+        assert!(text.contains("watch"));
+        assert!(text.contains("THREADS (1)"));
+        assert!(text.contains("deploy"));
+    }
+
+    #[test]
+    fn too_small_area_renders_nothing() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let state = make_state();
+        let buf = render_to_buffer(&widget, &state, 3, 5);
+        let text = buffer_text(&buf);
+        assert!(!text.contains("JOBS"));
+    }
+
+    #[test]
+    fn zero_height_renders_nothing() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.jobs = vec![JobInfo {
+            id: "j1".to_string(),
+            title: "test".to_string(),
+            status: JobStatus::Running,
+            started_at: chrono::Utc::now(),
+        }];
+        let buf = render_to_buffer(&widget, &state, 40, 0);
+        let text = buffer_text(&buf);
+        assert!(text.is_empty() || text.trim().is_empty());
+    }
+
+    #[test]
+    fn job_status_display() {
+        assert_eq!(format!("{}", JobStatus::Pending), "pending");
+        assert_eq!(format!("{}", JobStatus::Running), "running");
+        assert_eq!(format!("{}", JobStatus::Completed), "done");
+        assert_eq!(format!("{}", JobStatus::Failed), "failed");
+    }
+
+    #[test]
+    fn thread_status_display() {
+        assert_eq!(format!("{}", ThreadStatus::Active), "active");
+        assert_eq!(format!("{}", ThreadStatus::Idle), "idle");
+        assert_eq!(format!("{}", ThreadStatus::Completed), "done");
+        assert_eq!(format!("{}", ThreadStatus::Failed), "failed");
+    }
+
+    #[test]
+    fn format_uptime_seconds() {
+        assert_eq!(super::format_uptime(30), "30s");
+    }
+
+    #[test]
+    fn format_uptime_minutes() {
+        assert_eq!(super::format_uptime(150), "2m");
+    }
+
+    #[test]
+    fn format_uptime_hours() {
+        assert_eq!(super::format_uptime(3720), "1h 2m");
+    }
+
+    #[test]
+    fn format_uptime_exact_hour() {
+        assert_eq!(super::format_uptime(7200), "2h");
+    }
+
+    #[test]
+    fn engine_thread_shows_type_tag() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.engine_threads = vec![EngineThreadInfo {
+            id: "t1".to_string(),
+            goal: "research caching".to_string(),
+            thread_type: "Research".to_string(),
+            status: ThreadStatus::Idle,
+            step_count: 0,
+            total_tokens: 0,
+            started_at: Some(chrono::Utc::now()),
+            updated_at: Some(chrono::Utc::now()),
+        }];
+        let buf = render_to_buffer(&widget, &state, 50, 12);
+        let text = buffer_text(&buf);
+        assert!(text.contains("[R]"));
+        assert!(text.contains("research caching"));
+    }
+
+    #[test]
+    fn renders_system_section_with_docker() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.sandbox_status = Some(crate::widgets::SandboxInfo {
+            docker_available: true,
+            running_containers: 2,
+            status: "ready".to_string(),
+        });
+        let buf = render_to_buffer(&widget, &state, 50, 15);
+        let text = buffer_text(&buf);
+        assert!(text.contains("SYSTEM (1)"));
+        assert!(text.contains("Docker"));
+        assert!(text.contains("2 containers"));
+    }
+
+    #[test]
+    fn renders_system_section_with_secrets() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.secrets_status = Some(crate::widgets::SecretsInfo {
+            count: 5,
+            vault_unlocked: true,
+        });
+        let buf = render_to_buffer(&widget, &state, 50, 15);
+        let text = buffer_text(&buf);
+        assert!(text.contains("SYSTEM (1)"));
+        assert!(text.contains("Secrets"));
+        assert!(text.contains("5 stored"));
+        assert!(text.contains("unlocked"));
+    }
+
+    #[test]
+    fn renders_system_section_with_both() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.sandbox_status = Some(crate::widgets::SandboxInfo {
+            docker_available: false,
+            running_containers: 0,
+            status: "unavailable".to_string(),
+        });
+        state.secrets_status = Some(crate::widgets::SecretsInfo {
+            count: 0,
+            vault_unlocked: false,
+        });
+        let buf = render_to_buffer(&widget, &state, 50, 15);
+        let text = buffer_text(&buf);
+        assert!(text.contains("SYSTEM (2)"));
+        assert!(text.contains("Docker"));
+        assert!(text.contains("unavailable"));
+        assert!(text.contains("Secrets"));
+        assert!(text.contains("locked"));
+    }
+
+    #[test]
+    fn no_system_section_without_data() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let state = make_state();
+        let buf = render_to_buffer(&widget, &state, 50, 15);
+        let text = buffer_text(&buf);
+        assert!(!text.contains("SYSTEM"));
+    }
+
+    #[test]
+    fn failed_job_shows_correct_icon() {
+        let theme = Theme::dark();
+        let widget = ThreadListWidget::new(theme);
+        let mut state = make_state();
+        state.jobs = vec![JobInfo {
+            id: "j1".to_string(),
+            title: "broken".to_string(),
+            status: JobStatus::Failed,
+            started_at: chrono::Utc::now() - chrono::Duration::seconds(30),
+        }];
+        let buf = render_to_buffer(&widget, &state, 50, 12);
+        let text = buffer_text(&buf);
+        assert!(text.contains("\u{2717}")); // ✗ icon
+        assert!(text.contains("failed"));
+    }
+
+    #[test]
+    fn engine_thread_index_at_hits_first_visible_thread_row() {
+        let mut state = make_state();
+        state.engine_threads = vec![EngineThreadInfo {
+            id: "thread-1".to_string(),
+            goal: "Ship release".to_string(),
+            thread_type: "Foreground".to_string(),
+            status: ThreadStatus::Active,
+            step_count: 4,
+            total_tokens: 1_024,
+            started_at: Some(chrono::Utc::now()),
+            updated_at: Some(chrono::Utc::now()),
+        }];
+
+        let area = Rect::new(0, 0, 40, 12);
+        assert_eq!(super::engine_thread_index_at(area, &state, 4, 6), Some(0));
+    }
+
+    #[test]
+    fn engine_thread_index_at_returns_none_when_thread_rows_are_clipped() {
+        let mut state = make_state();
+        state.engine_threads = vec![EngineThreadInfo {
+            id: "thread-1".to_string(),
+            goal: "Ship release".to_string(),
+            thread_type: "Foreground".to_string(),
+            status: ThreadStatus::Active,
+            step_count: 4,
+            total_tokens: 1_024,
+            started_at: Some(chrono::Utc::now()),
+            updated_at: Some(chrono::Utc::now()),
+        }];
+
+        let area = Rect::new(0, 0, 40, 5);
+        assert_eq!(super::engine_thread_index_at(area, &state, 4, 3), None);
+    }
+}
diff --git a/crates/ironclaw_tui/src/widgets/thread_picker.rs b/crates/ironclaw_tui/src/widgets/thread_picker.rs
new file mode 100644
index 00000000000..ce92c774a8d
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/thread_picker.rs
@@ -0,0 +1,163 @@
+//! Thread resume picker modal widget.
+//!
+//! Centered modal listing past conversations. The user navigates with
+//! Up/Down/j/k, selects with Enter, and dismisses with Esc.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Modifier;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Block, Borders, Clear, Paragraph, Widget};
+
+use crate::theme::Theme;
+use crate::widgets::{AppState, ThreadPickerState};
+
+/// Renders the thread picker modal overlay.
+pub struct ThreadPickerWidget {
+    theme: Theme,
+}
+
+impl ThreadPickerWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+
+    /// Compute a centered modal area sized to fit the thread list.
+    pub fn modal_area(terminal: Rect, item_count: usize) -> Rect {
+        let width = (terminal.width * 3 / 4)
+            .max(50)
+            .min(terminal.width.saturating_sub(4));
+        // 2 border rows + 1 footer + items (capped at 15)
+        let content_rows = item_count.min(15) as u16;
+        let height = (content_rows + 4).min(terminal.height.saturating_sub(4));
+        let x = (terminal.width.saturating_sub(width)) / 2;
+        let y = (terminal.height.saturating_sub(height)) / 2;
+        Rect::new(x, y, width, height)
+    }
+
+    /// Render the thread picker into the given area.
+    pub fn render_picker(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        let Some(ref picker) = state.pending_thread_picker else {
+            return;
+        };
+        if area.height < 5 || area.width < 20 {
+            return;
+        }
+
+        Clear.render(area, buf);
+
+        let block = Block::default()
+            .borders(Borders::ALL)
+            .border_style(self.theme.accent_style())
+            .title(Span::styled(
+                " Resume Conversation ",
+                self.theme.accent_style().add_modifier(Modifier::BOLD),
+            ));
+        let inner = block.inner(area);
+        block.render(area, buf);
+
+        if inner.height < 2 || inner.width < 10 {
+            return;
+        }
+
+        // Reserve last row for footer
+        let list_height = inner.height.saturating_sub(1) as usize;
+        let total = picker.threads.len();
+
+        // Scroll so selected item is always visible
+        let scroll_offset = if picker.selected >= list_height {
+            picker.selected - list_height + 1
+        } else {
+            0
+        };
+
+        let visible_range = scroll_offset..total.min(scroll_offset + list_height);
+
+        for (row_idx, thread_idx) in visible_range.enumerate() {
+            let thread = &picker.threads[thread_idx];
+            let is_selected = thread_idx == picker.selected;
+            let y = inner.y + row_idx as u16;
+
+            let marker = if is_selected { "\u{25CF}" } else { "\u{25CB}" };
+            let title_text = thread.title.as_deref().unwrap_or("(untitled)");
+
+            // Truncate title to fit
+            let meta = format!("  {} msgs  {}", thread.message_count, thread.last_activity);
+            let available = inner.width as usize;
+            let marker_len = 2; // "● " or "○ "
+            let meta_len = meta.len();
+            let max_title = available.saturating_sub(marker_len + meta_len + 1);
+            let display_title = if title_text.chars().count() > max_title {
+                let truncated: String = title_text
+                    .chars()
+                    .take(max_title.saturating_sub(3))
+                    .collect();
+                format!("{truncated}...")
+            } else {
+                title_text.to_string()
+            };
+
+            let name_style = if is_selected {
+                self.theme.bold_accent_style()
+            } else {
+                ratatui::style::Style::default().fg(self.theme.fg.to_color())
+            };
+            let meta_style = self.theme.dim_style();
+
+            let line = Line::from(vec![
+                Span::styled(format!("{marker} "), name_style),
+                Span::styled(display_title, name_style),
+                Span::styled(meta, meta_style),
+            ]);
+
+            let line_area = Rect::new(inner.x, y, inner.width, 1);
+
+            // Highlight selected row background
+            if is_selected {
+                for bx in line_area.x..line_area.x + line_area.width {
+                    if let Some(cell) = buf.cell_mut((bx, y)) {
+                        cell.set_style(
+                            ratatui::style::Style::default().bg(self.theme.border.to_color()),
+                        );
+                    }
+                }
+            }
+
+            Paragraph::new(line).render(line_area, buf);
+        }
+
+        // Footer
+        let footer_y = inner.y + inner.height.saturating_sub(1);
+        let footer = Line::from(Span::styled(
+            " \u{2191}\u{2193} select  Enter resume  Esc cancel ",
+            self.theme.dim_style(),
+        ));
+        let footer_area = Rect::new(inner.x, footer_y, inner.width, 1);
+        Paragraph::new(footer).render(footer_area, buf);
+    }
+}
+
+/// Navigate the thread picker selection up.
+pub fn thread_picker_up(picker: &mut ThreadPickerState) {
+    if picker.threads.is_empty() {
+        return;
+    }
+    picker.selected = if picker.selected == 0 {
+        picker.threads.len() - 1
+    } else {
+        picker.selected - 1
+    };
+}
+
+/// Navigate the thread picker selection down.
+pub fn thread_picker_down(picker: &mut ThreadPickerState) {
+    if picker.threads.is_empty() {
+        return;
+    }
+    picker.selected = (picker.selected + 1) % picker.threads.len();
+}
+
+/// Get the thread ID of the currently selected thread.
+pub fn thread_picker_selected_id(picker: &ThreadPickerState) -> Option<&str> {
+    picker.threads.get(picker.selected).map(|t| t.id.as_str())
+}
diff --git a/crates/ironclaw_tui/src/widgets/tool_panel.rs b/crates/ironclaw_tui/src/widgets/tool_panel.rs
new file mode 100644
index 00000000000..5dfcee44c65
--- /dev/null
+++ b/crates/ironclaw_tui/src/widgets/tool_panel.rs
@@ -0,0 +1,130 @@
+//! Tool execution sidebar panel.
+
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::style::Modifier;
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Block, Borders, Widget};
+
+use crate::layout::TuiSlot;
+use crate::render::truncate;
+use crate::theme::Theme;
+
+use super::{AppState, ToolStatus, TuiWidget};
+
+pub struct ToolPanelWidget {
+    theme: Theme,
+}
+
+impl ToolPanelWidget {
+    pub fn new(theme: Theme) -> Self {
+        Self { theme }
+    }
+}
+
+impl TuiWidget for ToolPanelWidget {
+    fn id(&self) -> &str {
+        "tool_panel"
+    }
+
+    fn slot(&self) -> TuiSlot {
+        TuiSlot::Sidebar
+    }
+
+    fn render(&self, area: Rect, buf: &mut Buffer, state: &AppState) {
+        if area.height == 0 || area.width < 6 {
+            return;
+        }
+
+        // Bordered block with title
+        let active_count = state.active_tools.len();
+        let total_count = active_count + state.recent_tools.len();
+        let title = format!(" Tools {active_count}/{total_count} ");
+        let block = Block::default()
+            .borders(Borders::ALL)
+            .border_style(self.theme.border_style())
+            .title(Span::styled(
+                title,
+                self.theme.accent_style().add_modifier(Modifier::BOLD),
+            ));
+        let inner = block.inner(area);
+        block.render(area, buf);
+
+        if inner.height == 0 || inner.width < 4 {
+            return;
+        }
+
+        let max_name_len = (inner.width as usize).saturating_sub(10);
+        let mut lines: Vec<Line<'_>> = Vec::new();
+
+        let show_detail = inner.width >= 10;
+
+        // Active tools
+        for tool in &state.active_tools {
+            let elapsed = chrono::Utc::now()
+                .signed_duration_since(tool.started_at)
+                .num_milliseconds()
+                .unsigned_abs();
+            let name = truncate(&tool.name, max_name_len);
+            lines.push(Line::from(vec![
+                Span::styled(" \u{25CF} ", self.theme.accent_style()),
+                Span::styled(name, self.theme.accent_style()),
+                Span::styled(format!("  {elapsed}ms"), self.theme.dim_style()),
+            ]));
+            if show_detail && let Some(ref d) = tool.detail {
+                let detail_max = (inner.width as usize).saturating_sub(4);
+                lines.push(Line::from(Span::styled(
+                    format!("   {}", truncate(d, detail_max)),
+                    self.theme.dim_style(),
+                )));
+            }
+        }
+
+        // Recent tools
+        for (recent_shown, tool) in state
+            .recent_tools
+            .iter()
+            .rev()
+            .take((inner.height as usize).saturating_sub(lines.len()))
+            .enumerate()
+        {
+            let name = truncate(&tool.name, max_name_len);
+            let (icon, style) = match tool.status {
+                ToolStatus::Success => ("\u{25CF}", self.theme.success_style()),
+                ToolStatus::Failed => ("\u{2717}", self.theme.error_style()),
+                ToolStatus::Running => ("\u{25CB}", self.theme.accent_style()),
+            };
+            let duration_text = tool
+                .duration_ms
+                .map(|d| format!("  {d}ms"))
+                .unwrap_or_default();
+            lines.push(Line::from(vec![
+                Span::styled(format!(" {icon} "), style),
+                Span::styled(name, self.theme.dim_style()),
+                Span::styled(duration_text, self.theme.dim_style()),
+            ]));
+            // Show detail for the 3 most recent completed tools
+            if show_detail
+                && recent_shown < 3
+                && let Some(d) = tool.result_preview.as_deref().or(tool.detail.as_deref())
+            {
+                let detail_max = (inner.width as usize).saturating_sub(4);
+                lines.push(Line::from(Span::styled(
+                    format!("   {}", truncate(d, detail_max)),
+                    self.theme.dim_style(),
+                )));
+            }
+        }
+
+        // Empty state
+        if lines.is_empty() {
+            lines.push(Line::from(Span::styled(
+                " Waiting for tool activity...",
+                self.theme.dim_style(),
+            )));
+        }
+
+        let paragraph = ratatui::widgets::Paragraph::new(lines);
+        paragraph.render(inner, buf);
+    }
+}
diff --git a/docs/engine-v2-architecture.md b/docs/engine-v2-architecture.md
index 4ed20e575df..535d84d6a11 100644
--- a/docs/engine-v2-architecture.md
+++ b/docs/engine-v2-architecture.md
@@ -135,13 +135,15 @@ For trace debugging set `IRONCLAW_RECORD_TRACE=1`. Engine v2 reuses the host cra
 
 ### Learning Missions (replaced Reflection)
 
-Instead of a separate reflection pipeline, knowledge extraction is handled by three event-driven **learning missions** that fire automatically after thread completion:
+Instead of a separate reflection pipeline, knowledge extraction is handled by four event-driven **learning missions** that fire automatically after thread completion:
 
 1. **Self-improvement** (`self-improvement`) — fires when a thread completes with trace issues (errors, tool-not-found, etc.). Diagnoses root cause, applies prompt overlays or orchestrator patches. Graduated risk: Level 1 (prompt) → Level 2 (config) → Level 3 (code, propose only).
 
-2. **Skill extraction** (`skill-extraction`) — fires when a thread succeeds with 5+ steps and 3+ distinct tool actions. Extracts reusable skills with structured metadata: activation keywords/patterns, CodeAct code snippets, domain tags. Output is a `DocType::Skill` MemoryDoc with `V2SkillMetadata` JSON.
+2. **Skill repair** (`skill-repair`) — fires when a completed thread used an active skill and the resulting trace suggests that the skill instructions were stale, incomplete, incorrectly ordered, or missing verification. The mission returns a structured repair, and the runtime applies it as a versioned update with rollback history.
 
-3. **Conversation insights** (`conversation-insights`) — fires every 5 completed threads in a project. Extracts user preferences, domain knowledge, workflow patterns, and corrections.
+3. **Skill extraction** (`skill-extraction`) — fires when a thread succeeds with 5+ steps and 3+ distinct tool actions. Extracts reusable skills with structured metadata: activation keywords/patterns, CodeAct code snippets, domain tags. Output is a `DocType::Skill` MemoryDoc with `V2SkillMetadata` JSON.
+
+4. **Conversation insights** (`conversation-insights`) — fires every 5 completed threads in a project. Extracts user preferences, domain knowledge, workflow patterns, and corrections.
 
 ### Context Injection
 
diff --git a/scripts/slack_smoke/README.md b/scripts/slack_smoke/README.md
new file mode 100644
index 00000000000..4ce3c318789
--- /dev/null
+++ b/scripts/slack_smoke/README.md
@@ -0,0 +1,81 @@
+# Slack Local Smoke Test
+
+Exercises the real Slack WASM channel integration against a running IronClaw instance using live Slack API calls.
+
+## Prerequisites
+
+- **Python 3.11+**
+- **Running IronClaw** instance with the Slack channel configured and activated
+- **Slack App** with:
+  - Bot token (`xoxb-`) with scopes: `chat:write`, `channels:history`, `groups:history`, `im:history`, `files:read`
+  - User token (`xoxp-`) with scopes: `chat:write`, `files:write`, `channels:history`, `im:history`
+- **Test bot** added to the DM channel (and optionally a public channel for mention tests)
+
+## Setup
+
+```bash
+# From the repo root
+cd tests/e2e
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[slack]'
+
+# Configure
+cd ../../scripts/slack_smoke
+cp config.example.env config.env
+# Edit config.env with your tokens and channel IDs
+```
+
+## Usage
+
+```bash
+# Load env vars
+set -a && source config.env && set +a
+
+# Run default cases (dm, attachment, thread)
+python run_smoke.py
+
+# Run all cases including mention
+python run_smoke.py --all
+
+# Run a specific case
+python run_smoke.py --case dm
+python run_smoke.py --case mention
+
+# List available cases
+python run_smoke.py --list-cases
+```
+
+## Smoke Cases
+
+| Case | Default | Description |
+|------|---------|-------------|
+| `dm` | yes | Send DM via user token, poll for bot reply |
+| `attachment` | yes | Upload file to DM channel, poll for bot reply |
+| `thread` | yes | Send DM, wait for reply, reply in thread, verify bot continues in thread |
+| `mention` | no | Send `<@BOT_USER_ID> msg` in public channel, poll for threaded reply |
+
+## How It Works
+
+Unlike Telegram (which uses a user-client library like Telethon), Slack smoke uses two tokens:
+
+1. **User token** (`xoxp-`): Sends messages as a real Slack user, which triggers Slack to send webhook events to IronClaw
+2. **Bot token** (`xoxb-`): Reads `conversations.history` / `conversations.replies` to find the bot's replies
+
+Flow per case:
+1. Send message via user token
+2. Slack sends webhook event to IronClaw
+3. IronClaw processes event and calls `chat.postMessage`
+4. Smoke runner polls conversation history with bot token to find the reply
+
+## Recommended Release Workflow
+
+1. Run the Rust test suite: `cargo test --test slack_auth_integration`
+2. Run E2E tests: `cd tests/e2e && pytest scenarios/test_slack_e2e.py -v`
+3. Run this smoke test against a staging instance with real Slack
+
+## Notes
+
+- The `mention` case requires both `SLACK_SMOKE_PUBLIC_CHANNEL` and `SLACK_SMOKE_BOT_USER_ID`
+- Use `SLACK_SMOKE_EXPECT_SUBSTRING` with a mock LLM for deterministic reply matching
+- Exit codes: 0 = all passed, 1 = failure, 2 = config error
diff --git a/scripts/slack_smoke/config.example.env b/scripts/slack_smoke/config.example.env
new file mode 100644
index 00000000000..79aa3b097a8
--- /dev/null
+++ b/scripts/slack_smoke/config.example.env
@@ -0,0 +1,42 @@
+# Slack smoke test configuration.
+# Copy to config.env and fill in your values.
+# Then: set -a && source config.env && set +a
+
+# ── Required ──────────────────────────────────────────────────────────────
+
+# Bot token (xoxb-) — used to read conversation history and find replies.
+# Found under OAuth & Permissions in your Slack App settings.
+SLACK_SMOKE_BOT_TOKEN=xoxb-YOUR-BOT-TOKEN
+
+# User token (xoxp-) — used to send messages as a real Slack user.
+# Found under OAuth & Permissions > User Token Scopes.
+# Requires scopes: chat:write, files:write, channels:history, im:history
+SLACK_SMOKE_USER_TOKEN=xoxp-YOUR-USER-TOKEN
+
+# Bot's Slack user ID (e.g., U0BOTID).
+# Find via: your Slack app > About > Member ID
+SLACK_SMOKE_BOT_USER_ID=U0BOTID
+
+# DM channel ID with the bot (e.g., D0123456).
+# Open a DM with the bot, then check the URL or use conversations.list API.
+SLACK_SMOKE_DM_CHANNEL=D0123456
+
+# ── Optional ──────────────────────────────────────────────────────────────
+
+# Public channel where bot is a member (for app_mention test).
+# Only needed if you run --case mention or --all.
+# SLACK_SMOKE_PUBLIC_CHANNEL=C0123456
+
+# IronClaw health endpoint URL.
+# If set, the runner checks health before starting smoke cases.
+# SLACK_SMOKE_HEALTHCHECK_URL=http://localhost:3000/api/health
+
+# Maximum seconds to wait for a bot reply (default: 45).
+# SLACK_SMOKE_TIMEOUT_SECS=45
+
+# Seconds between history polls (default: 1.0).
+# SLACK_SMOKE_POLL_INTERVAL_SECS=1.0
+
+# If set, every bot reply must contain this substring to pass.
+# Useful with mock LLM for deterministic replies.
+# SLACK_SMOKE_EXPECT_SUBSTRING=
diff --git a/scripts/slack_smoke/run_smoke.py b/scripts/slack_smoke/run_smoke.py
new file mode 100644
index 00000000000..59a929c801d
--- /dev/null
+++ b/scripts/slack_smoke/run_smoke.py
@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+"""Local Slack smoke runner for pre-release validation.
+
+Runs a small set of real Slack flows against an already-running IronClaw
+instance configured with the Slack channel.
+
+This script uses two Slack tokens:
+  - User token (xoxp-): sends messages as a real Slack user to trigger webhooks
+  - Bot token (xoxb-): reads conversation history to find the bot's replies
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Awaitable, Callable
+
+import httpx
+from slack_sdk import WebClient
+from slack_sdk.errors import SlackApiError
+
+
+DEFAULT_TIMEOUT_SECS = 45.0
+DEFAULT_POLL_INTERVAL_SECS = 1.0
+DEFAULT_CASES = ("dm", "attachment", "thread")
+MENTION_CASES = ("mention",)
+
+
+class SmokeError(RuntimeError):
+    """A smoke case failed."""
+
+
+@dataclass(frozen=True)
+class SmokeConfig:
+    bot_token: str
+    user_token: str
+    bot_user_id: str
+    dm_channel: str
+    public_channel: str | None
+    expect_substring: str | None
+    timeout_secs: float
+    poll_interval_secs: float
+    healthcheck_url: str | None
+
+
+def env_str(name: str, default: str | None = None) -> str | None:
+    value = os.environ.get(name, default)
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+def load_config() -> SmokeConfig:
+    bot_token = env_str("SLACK_SMOKE_BOT_TOKEN")
+    user_token = env_str("SLACK_SMOKE_USER_TOKEN")
+    bot_user_id = env_str("SLACK_SMOKE_BOT_USER_ID")
+    dm_channel = env_str("SLACK_SMOKE_DM_CHANNEL")
+    public_channel = env_str("SLACK_SMOKE_PUBLIC_CHANNEL")
+    expect_substring = env_str("SLACK_SMOKE_EXPECT_SUBSTRING")
+    healthcheck_url = env_str("SLACK_SMOKE_HEALTHCHECK_URL")
+    timeout_secs = float(env_str("SLACK_SMOKE_TIMEOUT_SECS") or DEFAULT_TIMEOUT_SECS)
+    poll_interval_secs = float(
+        env_str("SLACK_SMOKE_POLL_INTERVAL_SECS") or DEFAULT_POLL_INTERVAL_SECS
+    )
+
+    if not bot_token:
+        raise SmokeError("SLACK_SMOKE_BOT_TOKEN is required")
+    if not user_token:
+        raise SmokeError("SLACK_SMOKE_USER_TOKEN is required")
+    if not bot_user_id:
+        raise SmokeError("SLACK_SMOKE_BOT_USER_ID is required")
+    if not dm_channel:
+        raise SmokeError("SLACK_SMOKE_DM_CHANNEL is required")
+
+    return SmokeConfig(
+        bot_token=bot_token,
+        user_token=user_token,
+        bot_user_id=bot_user_id,
+        dm_channel=dm_channel,
+        public_channel=public_channel,
+        expect_substring=expect_substring,
+        timeout_secs=timeout_secs,
+        poll_interval_secs=poll_interval_secs,
+        healthcheck_url=healthcheck_url,
+    )
+
+
+async def check_health(url: str) -> None:
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        response = await client.get(url)
+        response.raise_for_status()
+
+
+def poll_for_reply(
+    bot_client: WebClient,
+    *,
+    channel: str,
+    oldest: str,
+    timeout_secs: float,
+    poll_interval_secs: float,
+    bot_user_id: str,
+    expect_substring: str | None,
+    thread_ts: str | None = None,
+) -> dict:
+    """Poll conversations.history or conversations.replies for a bot reply."""
+    deadline = time.monotonic() + timeout_secs
+    while time.monotonic() < deadline:
+        try:
+            if thread_ts:
+                result = bot_client.conversations_replies(
+                    channel=channel, ts=thread_ts, oldest=oldest, limit=20
+                )
+                messages = result.get("messages", [])
+            else:
+                result = bot_client.conversations_history(
+                    channel=channel, oldest=oldest, limit=20
+                )
+                messages = result.get("messages", [])
+
+            for msg in messages:
+                if msg.get("user") != bot_user_id:
+                    continue
+                text = (msg.get("text") or "").strip()
+                if expect_substring and expect_substring not in text:
+                    continue
+                return msg
+        except SlackApiError as e:
+            print(f"  Slack API error during poll: {e}", file=sys.stderr)
+
+        time.sleep(poll_interval_secs)
+
+    suffix = f" containing '{expect_substring}'" if expect_substring else ""
+    raise SmokeError(f"Timed out waiting for bot reply{suffix}")
+
+
+def run_dm_case(
+    user_client: WebClient,
+    bot_client: WebClient,
+    cfg: SmokeConfig,
+) -> None:
+    run_id = uuid.uuid4().hex[:8]
+    text = f"release smoke dm {run_id}"
+    sent = user_client.chat_postMessage(channel=cfg.dm_channel, text=text)
+    sent_ts = sent["ts"]
+
+    reply = poll_for_reply(
+        bot_client,
+        channel=cfg.dm_channel,
+        oldest=sent_ts,
+        timeout_secs=cfg.timeout_secs,
+        poll_interval_secs=cfg.poll_interval_secs,
+        bot_user_id=cfg.bot_user_id,
+        expect_substring=cfg.expect_substring,
+    )
+    print(f"PASS dm: sent_ts={sent_ts} reply_ts={reply['ts']}")
+
+
+def run_mention_case(
+    user_client: WebClient,
+    bot_client: WebClient,
+    cfg: SmokeConfig,
+) -> None:
+    if cfg.public_channel is None:
+        print("SKIP mention: SLACK_SMOKE_PUBLIC_CHANNEL is not configured")
+        return
+
+    run_id = uuid.uuid4().hex[:8]
+    text = f"<@{cfg.bot_user_id}> release smoke mention {run_id}"
+    sent = user_client.chat_postMessage(channel=cfg.public_channel, text=text)
+    sent_ts = sent["ts"]
+
+    reply = poll_for_reply(
+        bot_client,
+        channel=cfg.public_channel,
+        oldest=sent_ts,
+        timeout_secs=cfg.timeout_secs,
+        poll_interval_secs=cfg.poll_interval_secs,
+        bot_user_id=cfg.bot_user_id,
+        expect_substring=cfg.expect_substring,
+        thread_ts=sent_ts,
+    )
+    print(f"PASS mention: sent_ts={sent_ts} reply_ts={reply['ts']}")
+
+
+def run_attachment_case(
+    user_client: WebClient,
+    bot_client: WebClient,
+    cfg: SmokeConfig,
+) -> None:
+    run_id = uuid.uuid4().hex[:8]
+    with tempfile.NamedTemporaryFile("w", suffix=".txt", delete=False) as tmp:
+        tmp.write(f"ironclaw slack smoke attachment {run_id}\n")
+        attachment_path = Path(tmp.name)
+
+    try:
+        sent = user_client.files_upload_v2(
+            channel=cfg.dm_channel,
+            file=str(attachment_path),
+            title=f"smoke-{run_id}.txt",
+            initial_comment=f"release smoke attachment {run_id}",
+        )
+        # files_upload_v2 returns file info, get the message ts from shares
+        file_info = sent.get("file", {})
+        shares = file_info.get("shares", {})
+        # Find the ts from DM channel shares
+        dm_shares = shares.get("private", {}).get(cfg.dm_channel, [])
+        if dm_shares:
+            sent_ts = dm_shares[0]["ts"]
+        else:
+            raise SmokeError(
+                f"Could not find message timestamp for file upload in channel {cfg.dm_channel}"
+            )
+
+        reply = poll_for_reply(
+            bot_client,
+            channel=cfg.dm_channel,
+            oldest=sent_ts,
+            timeout_secs=cfg.timeout_secs,
+            poll_interval_secs=cfg.poll_interval_secs,
+            bot_user_id=cfg.bot_user_id,
+            expect_substring=cfg.expect_substring,
+        )
+        print(f"PASS attachment: reply_ts={reply['ts']}")
+    finally:
+        attachment_path.unlink(missing_ok=True)
+
+
+def run_thread_case(
+    user_client: WebClient,
+    bot_client: WebClient,
+    cfg: SmokeConfig,
+) -> None:
+    run_id = uuid.uuid4().hex[:8]
+    # Send initial message and wait for reply
+    text = f"release smoke thread {run_id}"
+    sent = user_client.chat_postMessage(channel=cfg.dm_channel, text=text)
+    sent_ts = sent["ts"]
+
+    reply = poll_for_reply(
+        bot_client,
+        channel=cfg.dm_channel,
+        oldest=sent_ts,
+        timeout_secs=cfg.timeout_secs,
+        poll_interval_secs=cfg.poll_interval_secs,
+        bot_user_id=cfg.bot_user_id,
+        expect_substring=cfg.expect_substring,
+    )
+    reply_ts = reply["ts"]
+
+    # Now reply in thread
+    thread_text = f"release smoke thread reply {run_id}"
+    thread_sent = user_client.chat_postMessage(
+        channel=cfg.dm_channel, text=thread_text, thread_ts=sent_ts
+    )
+    thread_sent_ts = thread_sent["ts"]
+
+    thread_reply = poll_for_reply(
+        bot_client,
+        channel=cfg.dm_channel,
+        oldest=thread_sent_ts,
+        timeout_secs=cfg.timeout_secs,
+        poll_interval_secs=cfg.poll_interval_secs,
+        bot_user_id=cfg.bot_user_id,
+        expect_substring=cfg.expect_substring,
+        thread_ts=sent_ts,
+    )
+    print(
+        f"PASS thread: sent_ts={sent_ts} reply_ts={reply_ts} "
+        f"thread_reply_ts={thread_reply['ts']}"
+    )
+
+
+CASE_HANDLERS: dict[
+    str,
+    Callable[[WebClient, WebClient, SmokeConfig], None],
+] = {
+    "dm": run_dm_case,
+    "mention": run_mention_case,
+    "attachment": run_attachment_case,
+    "thread": run_thread_case,
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--case",
+        action="append",
+        choices=sorted(CASE_HANDLERS),
+        help="Smoke case to run. May be specified multiple times. Defaults to dm/attachment/thread.",
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Run dm, attachment, thread, and mention (if configured).",
+    )
+    parser.add_argument(
+        "--list-cases",
+        action="store_true",
+        help="Print the available smoke cases and exit.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    if args.list_cases:
+        print("Available cases:", ", ".join(sorted(CASE_HANDLERS)))
+        return 0
+
+    cfg = load_config()
+
+    if cfg.healthcheck_url:
+        print(f"Checking IronClaw health at {cfg.healthcheck_url} ...")
+        asyncio.run(check_health(cfg.healthcheck_url))
+
+    selected_cases = tuple(args.case or ())
+    if args.all:
+        selected_cases = DEFAULT_CASES + MENTION_CASES
+    elif not selected_cases:
+        selected_cases = DEFAULT_CASES
+
+    user_client = WebClient(token=cfg.user_token)
+    bot_client = WebClient(token=cfg.bot_token)
+
+    failures: list[str] = []
+    for case in selected_cases:
+        handler = CASE_HANDLERS[case]
+        print(f"Running {case} ...")
+        try:
+            handler(user_client, bot_client, cfg)
+        except (SlackApiError, SmokeError, httpx.HTTPError) as exc:
+            failures.append(f"{case}: {exc}")
+            print(f"FAIL {case}: {exc}")
+
+    if failures:
+        print("\nSmoke failures:")
+        for failure in failures:
+            print(f"  - {failure}")
+        return 1
+
+    print("\nAll requested Slack smoke cases passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        raise SystemExit(130)
+    except SmokeError as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        raise SystemExit(2)
diff --git a/src/agent/agent_loop.rs b/src/agent/agent_loop.rs
index 3b633f65f0b..61dfaa7ae3a 100644
--- a/src/agent/agent_loop.rs
+++ b/src/agent/agent_loop.rs
@@ -587,6 +587,62 @@ impl Agent {
         (selected, rewritten)
     }
 
+    /// Send initial engine thread list and routines to the TUI channel so
+    /// the sidebar is populated before the first user message.
+    async fn hydrate_tui_sidebar(&self) {
+        let empty_meta = serde_json::Value::Object(serde_json::Map::new());
+
+        // Engine threads
+        if self.config.engine_v2
+            && let Ok(threads) = crate::bridge::list_engine_threads(None, self.owner_id()).await
+        {
+            let summaries: Vec<crate::channels::EngineThreadSummary> = threads
+                .into_iter()
+                .map(|t| crate::channels::EngineThreadSummary {
+                    id: t.id,
+                    goal: t.goal,
+                    thread_type: t.thread_type,
+                    state: t.state,
+                    step_count: t.step_count,
+                    total_tokens: t.total_tokens,
+                    created_at: t.created_at,
+                    updated_at: t.updated_at,
+                })
+                .collect();
+            let _ = self
+                .channels
+                .send_status(
+                    "tui",
+                    StatusUpdate::EngineThreadList { threads: summaries },
+                    &empty_meta,
+                )
+                .await;
+        }
+
+        // Routines
+        if let Some(system) = self.system_store()
+            && let Ok(routines) = system.list_all_routines().await
+        {
+            for routine in routines {
+                let _ = self
+                    .channels
+                    .send_status(
+                        "tui",
+                        StatusUpdate::RoutineUpdate {
+                            id: routine.id.to_string(),
+                            name: routine.name.clone(),
+                            trigger_type: format!("{:?}", routine.trigger),
+                            enabled: routine.enabled,
+                            last_run: routine.last_run_at.map(|t| t.to_rfc3339()),
+                            next_fire: routine.next_fire_at.map(|t| t.to_rfc3339()),
+                        },
+                        &empty_meta,
+                    )
+                    .await;
+            }
+        }
+    }
+
     /// Run the agent main loop.
     pub async fn run(self) -> Result<(), Error> {
         // Bootstrap greeting is now handled by chat_threads_handler in server.rs
@@ -991,6 +1047,11 @@ impl Agent {
         // broadcast the greeting via SSE for any clients already connected.
         // The greeting was already persisted to DB before start_all(), so
         // clients that connect after this point will see it via history.
+
+        // Hydrate TUI sidebar with existing engine threads and routines so the
+        // activity panel is populated before the first user message.
+        self.hydrate_tui_sidebar().await;
+
         // Main message loop
         tracing::debug!("Agent {} ready and listening", self.config.name);
 
@@ -1113,6 +1174,34 @@ impl Agent {
                     }
                 }
             }
+
+            // Refresh engine v2 thread list in the TUI sidebar after each turn.
+            if self.config.engine_v2
+                && let Ok(threads) =
+                    crate::bridge::list_engine_threads(None, &message.user_id).await
+            {
+                let summaries: Vec<crate::channels::EngineThreadSummary> = threads
+                    .into_iter()
+                    .map(|t| crate::channels::EngineThreadSummary {
+                        id: t.id,
+                        goal: t.goal,
+                        thread_type: t.thread_type,
+                        state: t.state,
+                        step_count: t.step_count,
+                        total_tokens: t.total_tokens,
+                        created_at: t.created_at,
+                        updated_at: t.updated_at,
+                    })
+                    .collect();
+                let _ = self
+                    .channels
+                    .send_status(
+                        &message.channel,
+                        StatusUpdate::EngineThreadList { threads: summaries },
+                        &message.metadata,
+                    )
+                    .await;
+            }
         }
 
         // Cleanup
@@ -1693,6 +1782,7 @@ impl Agent {
             Submission::Resume { checkpoint_id } => {
                 self.process_resume(session, thread_id, checkpoint_id).await
             }
+            Submission::ListThreads => self.process_list_threads(session, message).await,
             Submission::ExecApproval {
                 request_id,
                 approved,
diff --git a/src/agent/commands.rs b/src/agent/commands.rs
index 78e1d6a8715..d1219587935 100644
--- a/src/agent/commands.rs
+++ b/src/agent/commands.rs
@@ -28,6 +28,18 @@ fn format_count(n: u64, suffix: &str) -> String {
     }
 }
 
+fn format_vertical_list(title: &str, items: &[String]) -> String {
+    if items.is_empty() {
+        return format!("{}:\n  (none)", title);
+    }
+
+    let mut out = format!("{}:\n", title);
+    for item in items {
+        out.push_str(&format!("  {}\n", item));
+    }
+    out.trim_end().to_string()
+}
+
 impl Agent {
     /// Handle job-related intents without turn tracking.
     pub(super) async fn handle_job_or_command(
@@ -709,7 +721,7 @@ impl Agent {
                 "  /interrupt        Stop current operation\n",
                 "  /new              New conversation thread\n",
                 "  /thread <id>      Switch to thread\n",
-                "  /resume <id>      Resume from checkpoint\n",
+                "  /resume           Resume a previous conversation\n",
                 "\n",
                 "Skills:\n",
                 "  /skills             List installed skills\n",
@@ -796,9 +808,9 @@ impl Agent {
 
             "tools" => {
                 let tools = self.tools().list().await;
-                Ok(SubmissionResult::response(format!(
-                    "Available tools: {}",
-                    tools.join(", ")
+                Ok(SubmissionResult::response(format_vertical_list(
+                    "Available tools",
+                    &tools,
                 )))
             }
 
@@ -1147,3 +1159,22 @@ impl Agent {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::format_vertical_list;
+
+    #[test]
+    fn format_vertical_list_renders_one_item_per_line() {
+        let formatted = format_vertical_list(
+            "Available tools",
+            &[
+                "time".to_string(),
+                "shell".to_string(),
+                "github".to_string(),
+            ],
+        );
+
+        assert_eq!(formatted, "Available tools:\n  time\n  shell\n  github");
+    }
+}
diff --git a/src/agent/dispatcher.rs b/src/agent/dispatcher.rs
index 99d8117fd96..2249ab6f8cf 100644
--- a/src/agent/dispatcher.rs
+++ b/src/agent/dispatcher.rs
@@ -925,9 +925,11 @@ impl<'a> LoopDelegate for ChatDelegate<'a> {
                     .channels
                     .send_status(
                         &self.message.channel,
-                        StatusUpdate::ToolStarted {
-                            name: tc.name.clone(),
-                        },
+                        StatusUpdate::tool_started_with_id(
+                            tc.name.clone(),
+                            &tc.arguments,
+                            Some(tc.id.clone()),
+                        ),
                         &self.message.metadata,
                     )
                     .await;
@@ -945,6 +947,7 @@ impl<'a> LoopDelegate for ChatDelegate<'a> {
                         &self.message.channel,
                         StatusUpdate::tool_completed(
                             tc.name.clone(),
+                            Some(tc.id.clone()),
                             &result,
                             &tc.arguments,
                             disp_tool.as_deref(),
@@ -972,9 +975,11 @@ impl<'a> LoopDelegate for ChatDelegate<'a> {
                     let _ = channels
                         .send_status(
                             &channel,
-                            StatusUpdate::ToolStarted {
-                                name: tc.name.clone(),
-                            },
+                            StatusUpdate::tool_started_with_id(
+                                tc.name.clone(),
+                                &tc.arguments,
+                                Some(tc.id.clone()),
+                            ),
                             &metadata,
                         )
                         .await;
@@ -994,6 +999,7 @@ impl<'a> LoopDelegate for ChatDelegate<'a> {
                             &channel,
                             StatusUpdate::tool_completed(
                                 tc.name.clone(),
+                                Some(tc.id.clone()),
                                 &result,
                                 &tc.arguments,
                                 par_tool.as_deref(),
@@ -1121,6 +1127,7 @@ impl<'a> LoopDelegate for ChatDelegate<'a> {
                                 StatusUpdate::ToolResult {
                                     name: tc.name.clone(),
                                     preview: output.clone(),
+                                    call_id: Some(tc.id.clone()),
                                 },
                                 &self.message.metadata,
                             )
diff --git a/src/agent/routine_engine.rs b/src/agent/routine_engine.rs
index 74a3bf1fe54..8d0f22e73cc 100644
--- a/src/agent/routine_engine.rs
+++ b/src/agent/routine_engine.rs
@@ -1631,6 +1631,11 @@ fn build_lightweight_prompt(
             "Do not claim you lack messaging integrations or ask the user to set one up when \
              a plain reply is sufficient.\n",
         );
+        full_prompt.push_str(
+            "Return the final user-facing notification as normal assistant text. Do not use the \
+             `message` tool for the routine's primary delivery unless the task explicitly requires \
+             an extra follow-up or attachment; even then, still return a concise human-readable summary.\n",
+        );
     }
 
     if !use_tools {
@@ -1718,6 +1723,7 @@ fn handle_text_response(
     total_input_tokens: u32,
     total_output_tokens: u32,
 ) -> Result<(RunStatus, Option<String>, Option<i32>), RoutineError> {
+    let content = strip_internal_tool_call_text(content);
     let content = content.trim();
 
     // Empty content guard — carry consumed tokens so the retry loop can
@@ -1749,6 +1755,34 @@ fn handle_text_response(
     ))
 }
 
+/// Strip internal `[Called tool ...]` and `[Tool ... returned: ...]` markers
+/// from routine summaries before they are persisted or delivered to channels.
+fn strip_internal_tool_call_text(text: &str) -> String {
+    let result = text
+        .lines()
+        .filter(|line| {
+            let trimmed = line.trim();
+            !((trimmed.starts_with("[Called tool ") && trimmed.ends_with(']'))
+                || (trimmed.starts_with("[Tool ")
+                    && trimmed.contains(" returned:")
+                    && trimmed.ends_with(']')))
+        })
+        .fold(String::new(), |mut acc, s| {
+            if !acc.is_empty() {
+                acc.push('\n');
+            }
+            acc.push_str(s);
+            acc
+        });
+
+    let result = result.trim();
+    if result.is_empty() {
+        "I wasn't able to produce a user-facing routine summary.".to_string()
+    } else {
+        result.to_string()
+    }
+}
+
 /// Execute a lightweight routine with tool execution support (agentic loop).
 ///
 /// This is a simplified version of the full dispatcher loop:
@@ -2311,6 +2345,10 @@ mod tests {
             prompt.contains("Do not claim you lack messaging integrations"),
             "delivery guidance should suppress fake setup chatter: {prompt}",
         );
+        assert!(
+            prompt.contains("Do not use the `message` tool for the routine's primary delivery"),
+            "delivery guidance should reserve message tool for non-primary delivery: {prompt}",
+        );
         assert!(
             prompt.contains("Tools are disabled for this routine run"),
             "prompt should explain that tools are disabled: {prompt}",
@@ -2541,6 +2579,39 @@ mod tests {
         assert_eq!(finish_reason_stop, crate::llm::FinishReason::Stop);
     }
 
+    #[test]
+    fn test_handle_text_response_strips_internal_tool_markers() {
+        let result = super::handle_text_response(
+            "Here is the report.\n[Called tool `http` with arguments: {\"url\":\"https://example.com\"}]",
+            crate::llm::FinishReason::Stop,
+            10,
+            5,
+        )
+        .expect("tool marker text should sanitize");
+
+        assert_eq!(result.0, RunStatus::Attention);
+        assert_eq!(result.1.as_deref(), Some("Here is the report."));
+        assert_eq!(result.2, Some(15));
+    }
+
+    #[test]
+    fn test_handle_text_response_replaces_marker_only_text() {
+        let result = super::handle_text_response(
+            "[Called tool `http` with arguments: {\"url\":\"https://example.com\"}]",
+            crate::llm::FinishReason::Stop,
+            4,
+            3,
+        )
+        .expect("marker-only text should fall back to a user-facing summary");
+
+        assert_eq!(result.0, RunStatus::Attention);
+        assert_eq!(
+            result.1.as_deref(),
+            Some("I wasn't able to produce a user-facing routine summary.")
+        );
+        assert_eq!(result.2, Some(7));
+    }
+
     #[test]
     fn test_truncate_adds_ellipsis_when_over_limit() {
         let input = "abcdefghijk";
diff --git a/src/agent/submission.rs b/src/agent/submission.rs
index 68d43a7fbf1..40b2ab9b816 100644
--- a/src/agent/submission.rs
+++ b/src/agent/submission.rs
@@ -165,7 +165,10 @@ impl SubmissionParser {
             }
         }
 
-        // /resume <uuid> - resume from checkpoint
+        // /resume - show thread picker; /resume <uuid> - resume from checkpoint
+        if lower == "/resume" {
+            return Submission::ListThreads;
+        }
         if let Some(rest) = lower.strip_prefix("/resume ")
             && let Ok(id) = Uuid::parse_str(rest.trim())
         {
@@ -328,6 +331,9 @@ pub enum Submission {
     /// Create a new thread.
     NewThread,
 
+    /// List threads for the interactive resume picker.
+    ListThreads,
+
     /// Trigger a manual heartbeat check.
     Heartbeat,
 
diff --git a/src/agent/thread_ops.rs b/src/agent/thread_ops.rs
index 05d00922cc5..3b83c07c7b4 100644
--- a/src/agent/thread_ops.rs
+++ b/src/agent/thread_ops.rs
@@ -17,7 +17,7 @@ use crate::agent::dispatcher::{
 };
 use crate::agent::session::{MAX_PENDING_MESSAGES, PendingApproval, Session, ThreadState};
 use crate::agent::submission::SubmissionResult;
-use crate::channels::{IncomingMessage, StatusUpdate};
+use crate::channels::{ChatApprovalPrompt, HistoryMessage, IncomingMessage, StatusUpdate};
 use crate::context::JobContext;
 use crate::error::Error;
 use crate::llm::{ChatMessage, ToolCall};
@@ -26,12 +26,100 @@ use ironclaw_common::truncate_preview;
 
 const FORGED_THREAD_ID_ERROR: &str = "Invalid or unauthorized thread ID.";
 
+#[derive(Clone)]
+struct PendingApprovalStatusSnapshot {
+    request_id: String,
+    tool_name: String,
+    description: String,
+    parameters: serde_json::Value,
+    allow_always: bool,
+}
+
+impl From<&PendingApproval> for PendingApprovalStatusSnapshot {
+    fn from(pending: &PendingApproval) -> Self {
+        let parameters = if pending.display_parameters.is_null() {
+            pending.parameters.clone()
+        } else {
+            pending.display_parameters.clone()
+        };
+
+        Self {
+            request_id: pending.request_id.to_string(),
+            tool_name: pending.tool_name.clone(),
+            description: pending.description.clone(),
+            parameters,
+            allow_always: pending.allow_always,
+        }
+    }
+}
+
 fn requires_preexisting_uuid_thread(channel: &str) -> bool {
     // Gateway-style channels send server-issued conversation UUIDs.
     // Unknown UUIDs should be rejected instead of silently creating a new thread.
     matches!(channel, "gateway" | "test")
 }
 
+fn history_messages_from_thread(thread: &crate::agent::session::Thread) -> Vec<HistoryMessage> {
+    let mut messages = Vec::new();
+
+    for turn in &thread.turns {
+        if !turn.user_input.is_empty() {
+            messages.push(HistoryMessage {
+                role: "user".to_string(),
+                content: turn.user_input.clone(),
+                timestamp: turn.started_at,
+            });
+        }
+
+        if let Some(response) = turn.response.as_ref() {
+            messages.push(HistoryMessage {
+                role: "assistant".to_string(),
+                content: response.clone(),
+                timestamp: turn.completed_at.unwrap_or(turn.started_at),
+            });
+        }
+    }
+
+    messages
+}
+
+fn approval_prompt_from_pending(pending: &PendingApproval) -> ChatApprovalPrompt {
+    let parameters = if pending.display_parameters.is_null() {
+        pending.parameters.clone()
+    } else {
+        pending.display_parameters.clone()
+    };
+
+    ChatApprovalPrompt {
+        request_id: pending.request_id.to_string(),
+        tool_name: pending.tool_name.clone(),
+        description: pending.description.clone(),
+        parameters,
+        allow_always: pending.allow_always,
+    }
+}
+
+fn thread_summaries_from_conversations(
+    mut conversations: Vec<crate::history::ConversationSummary>,
+) -> Vec<crate::channels::ThreadSummary> {
+    conversations.sort_by(|a, b| {
+        b.last_activity
+            .cmp(&a.last_activity)
+            .then_with(|| b.started_at.cmp(&a.started_at))
+            .then_with(|| a.id.cmp(&b.id))
+    });
+
+    conversations
+        .into_iter()
+        .map(|c| crate::channels::ThreadSummary {
+            id: c.id.to_string(),
+            title: c.title,
+            message_count: c.message_count,
+            last_activity: c.last_activity.to_rfc3339(),
+            channel: c.channel,
+        })
+        .collect()
+}
 fn turn_usage_from_result(result: &Result<AgenticLoopResult, Error>) -> Option<&TurnUsageSummary> {
     match result {
         Ok(AgenticLoopResult::Response { turn_usage, .. })
@@ -40,7 +128,6 @@ fn turn_usage_from_result(result: &Result<AgenticLoopResult, Error>) -> Option<&
         Err(_) => None,
     }
 }
-
 impl Agent {
     /// Hydrate a historical thread from DB into memory if not already present.
     ///
@@ -237,7 +324,7 @@ impl Agent {
         );
 
         // First check thread state without holding lock during I/O
-        let (thread_state, approval_context) = {
+        let (thread_state, approval_context, approval_status) = {
             let sess = session.lock().await;
             let thread = sess
                 .threads
@@ -248,7 +335,11 @@ impl Agent {
                     crate::agent::agent_loop::truncate_for_preview(&a.description, 80);
                 (a.tool_name.clone(), desc_preview)
             });
-            (thread.state, approval_context)
+            let approval_status = thread
+                .pending_approval
+                .as_ref()
+                .map(PendingApprovalStatusSnapshot::from);
+            (thread.state, approval_context, approval_status)
         };
 
         tracing::debug!(
@@ -334,6 +425,22 @@ impl Agent {
                     thread_id = %thread_id,
                     "Thread awaiting approval, rejecting new input"
                 );
+                if let Some(ref pending) = approval_status {
+                    let _ = self
+                        .channels
+                        .send_status(
+                            &message.channel,
+                            StatusUpdate::ApprovalNeeded {
+                                request_id: pending.request_id.clone(),
+                                tool_name: pending.tool_name.clone(),
+                                description: pending.description.clone(),
+                                parameters: pending.parameters.clone(),
+                                allow_always: pending.allow_always,
+                            },
+                            &message.metadata,
+                        )
+                        .await;
+                }
                 let msg = match approval_context {
                     Some((tool_name, desc_preview)) => format!(
                         "Waiting for approval: {tool_name} — {desc_preview}. Use /interrupt to cancel."
@@ -1146,9 +1253,11 @@ impl Agent {
                 .channels
                 .send_status(
                     &message.channel,
-                    StatusUpdate::ToolStarted {
-                        name: pending.tool_name.clone(),
-                    },
+                    StatusUpdate::tool_started_with_id(
+                        pending.tool_name.clone(),
+                        &pending.parameters,
+                        Some(pending.tool_call_id.clone()),
+                    ),
                     &message.metadata,
                 )
                 .await;
@@ -1164,6 +1273,7 @@ impl Agent {
                     &message.channel,
                     StatusUpdate::tool_completed(
                         pending.tool_name.clone(),
+                        Some(pending.tool_call_id.clone()),
                         &tool_result,
                         &pending.display_parameters,
                         tool_ref.as_deref(),
@@ -1182,6 +1292,7 @@ impl Agent {
                         StatusUpdate::ToolResult {
                             name: pending.tool_name.clone(),
                             preview: output.clone(),
+                            call_id: Some(pending.tool_call_id.clone()),
                         },
                         &message.metadata,
                     )
@@ -1310,9 +1421,11 @@ impl Agent {
                         .channels
                         .send_status(
                             &message.channel,
-                            StatusUpdate::ToolStarted {
-                                name: tc.name.clone(),
-                            },
+                            StatusUpdate::tool_started_with_id(
+                                tc.name.clone(),
+                                &tc.arguments,
+                                Some(tc.id.clone()),
+                            ),
                             &message.metadata,
                         )
                         .await;
@@ -1328,6 +1441,7 @@ impl Agent {
                             &message.channel,
                             StatusUpdate::tool_completed(
                                 tc.name.clone(),
+                                Some(tc.id.clone()),
                                 &result,
                                 &tc.arguments,
                                 deferred_tool.as_deref(),
@@ -1357,9 +1471,11 @@ impl Agent {
                         let _ = channels
                             .send_status(
                                 &channel,
-                                StatusUpdate::ToolStarted {
-                                    name: tc.name.clone(),
-                                },
+                                StatusUpdate::tool_started_with_id(
+                                    tc.name.clone(),
+                                    &tc.arguments,
+                                    Some(tc.id.clone()),
+                                ),
                                 &metadata,
                             )
                             .await;
@@ -1379,6 +1495,7 @@ impl Agent {
                                 &channel,
                                 StatusUpdate::tool_completed(
                                     tc.name.clone(),
+                                    Some(tc.id.clone()),
                                     &result,
                                     &tc.arguments,
                                     par_tool.as_deref(),
@@ -1443,6 +1560,7 @@ impl Agent {
                             StatusUpdate::ToolResult {
                                 name: tc.name.clone(),
                                 preview: output.clone(),
+                                call_id: Some(tc.id.clone()),
                             },
                             &message.metadata,
                         )
@@ -1907,13 +2025,49 @@ impl Agent {
         message: &IncomingMessage,
         target_thread_id: Uuid,
     ) -> Result<SubmissionResult, Error> {
+        // Try hydrating from DB if not already in session.
+        let thread_id_str = target_thread_id.to_string();
+        if let Some(rejection) = self.maybe_hydrate_thread(message, &thread_id_str).await {
+            return Ok(SubmissionResult::error(rejection));
+        }
+
         let session = self
             .session_manager
             .get_or_create_session(&message.user_id)
             .await;
-        let mut sess = session.lock().await;
+        let (switched, messages, pending_approval) = {
+            let mut sess = session.lock().await;
+            if sess.switch_thread(target_thread_id) {
+                let history = sess
+                    .threads
+                    .get(&target_thread_id)
+                    .map(history_messages_from_thread)
+                    .unwrap_or_default();
+                let pending_approval = sess
+                    .threads
+                    .get(&target_thread_id)
+                    .and_then(|thread| thread.pending_approval.as_ref())
+                    .map(approval_prompt_from_pending);
+                (true, history, pending_approval)
+            } else {
+                (false, Vec::new(), None)
+            }
+        };
+
+        if switched {
+            let _ = self
+                .channels
+                .send_status(
+                    &message.channel,
+                    StatusUpdate::ConversationHistory {
+                        thread_id: target_thread_id.to_string(),
+                        messages,
+                        pending_approval,
+                    },
+                    &message.metadata,
+                )
+                .await;
 
-        if sess.switch_thread(target_thread_id) {
             Ok(SubmissionResult::ok_with_message(format!(
                 "Switched to thread {}",
                 target_thread_id
@@ -1947,6 +2101,54 @@ impl Agent {
             Ok(SubmissionResult::error("Checkpoint not found."))
         }
     }
+
+    /// List past conversations from the database and emit a `ThreadList`
+    /// status update so the TUI can show the interactive resume picker.
+    pub(super) async fn process_list_threads(
+        &self,
+        _session: Arc<Mutex<Session>>,
+        message: &IncomingMessage,
+    ) -> Result<SubmissionResult, Error> {
+        let Some(db) = self.store() else {
+            return Ok(SubmissionResult::ok_with_message(
+                "No database configured — cannot list conversations.".to_string(),
+            ));
+        };
+
+        let conversations = match db
+            .list_conversations_all_channels(&message.user_id, 20)
+            .await
+        {
+            Ok(c) => c,
+            Err(e) => {
+                tracing::debug!("Failed to list conversations: {e}");
+                return Ok(SubmissionResult::error(format!(
+                    "Failed to list conversations: {e}"
+                )));
+            }
+        };
+
+        let summaries = thread_summaries_from_conversations(conversations);
+
+        if summaries.is_empty() {
+            return Ok(SubmissionResult::ok_with_message(
+                "No conversations to resume.".to_string(),
+            ));
+        }
+
+        let _ = self
+            .channels
+            .send_status(
+                &message.channel,
+                StatusUpdate::ThreadList { threads: summaries },
+                &message.metadata,
+            )
+            .await;
+
+        Ok(SubmissionResult::Ok {
+            message: Some(String::new()),
+        })
+    }
 }
 
 /// Rebuild full LLM-compatible `ChatMessage` sequence from DB messages.
@@ -2050,8 +2252,67 @@ fn rebuild_chat_messages_from_db(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::sync::Arc;
+    use std::sync::Mutex as StdMutex;
+    use std::time::Duration;
+
+    use crate::agent::AgentDeps;
+    use crate::agent::cost_guard::{CostGuard, CostGuardConfig};
+    use crate::channels::{ChannelManager, IncomingMessage, StatusUpdate};
+    use crate::config::{AgentConfig, SafetyConfig, SkillsConfig};
+    use crate::context::ContextManager;
+    use crate::hooks::HookRegistry;
+    use crate::testing::{StubChannel, StubLlm};
+    use crate::tools::ToolRegistry;
+    use chrono::TimeZone;
+    use ironclaw_safety::SafetyLayer;
     use rust_decimal::Decimal;
 
+    #[test]
+    fn thread_summaries_are_sorted_by_last_activity_descending() {
+        let conversations = vec![
+            crate::history::ConversationSummary {
+                id: Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
+                title: Some("older".to_string()),
+                message_count: 1,
+                started_at: chrono::Utc.with_ymd_and_hms(2026, 4, 4, 7, 0, 0).unwrap(),
+                last_activity: chrono::Utc.with_ymd_and_hms(2026, 4, 4, 7, 5, 0).unwrap(),
+                thread_type: None,
+                channel: "gateway".to_string(),
+            },
+            crate::history::ConversationSummary {
+                id: Uuid::parse_str("00000000-0000-0000-0000-000000000002").unwrap(),
+                title: Some("newest".to_string()),
+                message_count: 2,
+                started_at: chrono::Utc.with_ymd_and_hms(2026, 4, 4, 7, 10, 0).unwrap(),
+                last_activity: chrono::Utc.with_ymd_and_hms(2026, 4, 4, 7, 30, 0).unwrap(),
+                thread_type: None,
+                channel: "gateway".to_string(),
+            },
+            crate::history::ConversationSummary {
+                id: Uuid::parse_str("00000000-0000-0000-0000-000000000003").unwrap(),
+                title: Some("middle".to_string()),
+                message_count: 3,
+                started_at: chrono::Utc.with_ymd_and_hms(2026, 4, 4, 7, 8, 0).unwrap(),
+                last_activity: chrono::Utc.with_ymd_and_hms(2026, 4, 4, 7, 15, 0).unwrap(),
+                thread_type: None,
+                channel: "gateway".to_string(),
+            },
+        ];
+
+        let summaries = thread_summaries_from_conversations(conversations);
+        let titles: Vec<Option<String>> = summaries.into_iter().map(|s| s.title).collect();
+
+        assert_eq!(
+            titles,
+            vec![
+                Some("newest".to_string()),
+                Some("middle".to_string()),
+                Some("older".to_string()),
+            ]
+        );
+    }
+
     #[test]
     fn test_rebuild_chat_messages_user_assistant_only() {
         let messages = vec![
@@ -2266,6 +2527,77 @@ mod tests {
         }
     }
 
+    async fn make_test_agent_with_status_channel(
+        channel_name: &str,
+    ) -> (Agent, Arc<StdMutex<Vec<StatusUpdate>>>) {
+        let (stub, _sender) = StubChannel::new(channel_name);
+        let statuses = stub.captured_statuses_handle();
+        let manager = ChannelManager::new();
+        manager.add(Box::new(stub)).await;
+
+        let deps = AgentDeps {
+            owner_id: "default".to_string(),
+            store: None,
+            llm: Arc::new(StubLlm::default()),
+            cheap_llm: None,
+            safety: Arc::new(SafetyLayer::new(&SafetyConfig {
+                max_output_length: 100_000,
+                injection_check_enabled: false,
+            })),
+            tools: Arc::new(ToolRegistry::new()),
+            workspace: None,
+            extension_manager: None,
+            skill_registry: None,
+            skill_catalog: None,
+            skills_config: SkillsConfig::default(),
+            hooks: Arc::new(HookRegistry::new()),
+            cost_guard: Arc::new(CostGuard::new(CostGuardConfig::default())),
+            sse_tx: None,
+            http_interceptor: None,
+            transcription: None,
+            document_extraction: None,
+            sandbox_readiness: crate::agent::routine_engine::SandboxReadiness::DisabledByConfig,
+            builder: None,
+            llm_backend: "nearai".to_string(),
+            tenant_rates: Arc::new(crate::tenant::TenantRateRegistry::new(4, 3)),
+        };
+
+        let agent = Agent::new(
+            AgentConfig {
+                name: "test-agent".to_string(),
+                max_parallel_jobs: 1,
+                job_timeout: Duration::from_secs(60),
+                stuck_threshold: Duration::from_secs(60),
+                repair_check_interval: Duration::from_secs(30),
+                max_repair_attempts: 1,
+                use_planning: false,
+                session_idle_timeout: Duration::from_secs(300),
+                allow_local_tools: false,
+                max_cost_per_day_cents: None,
+                max_actions_per_hour: None,
+                max_cost_per_user_per_day_cents: None,
+                max_tool_iterations: 50,
+                auto_approve_tools: false,
+                default_timezone: "UTC".to_string(),
+                max_jobs_per_user: None,
+                max_tokens_per_job: 0,
+                multi_tenant: false,
+                max_llm_concurrent_per_user: None,
+                max_jobs_concurrent_per_user: None,
+                engine_v2: false,
+            },
+            deps,
+            Arc::new(manager),
+            None,
+            None,
+            None,
+            Some(Arc::new(ContextManager::new(1))),
+            None,
+        );
+
+        (agent, statuses)
+    }
+
     #[tokio::test]
     async fn test_awaiting_approval_rejection_includes_tool_context() {
         // Test that when a thread is in AwaitingApproval state and receives a new message,
@@ -2338,6 +2670,159 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn test_switch_thread_emits_history_with_pending_approval() {
+        use crate::agent::session::{PendingApproval, Thread};
+        use uuid::Uuid;
+
+        let (agent, statuses) = make_test_agent_with_status_channel("tui").await;
+        let session = agent
+            .session_manager
+            .get_or_create_session("test-user")
+            .await;
+        let session_id = session.lock().await.id;
+
+        let other_thread_id = Uuid::new_v4();
+        let target_thread_id = Uuid::new_v4();
+        let mut target_thread = Thread::with_id(target_thread_id, session_id, Some("tui"));
+        target_thread.start_turn("Review the diff");
+        target_thread.complete_turn("Waiting for approval.");
+        target_thread.await_approval(PendingApproval {
+            request_id: Uuid::new_v4(),
+            tool_name: "shell".to_string(),
+            parameters: serde_json::json!({"command": "echo hello"}),
+            display_parameters: serde_json::json!({"command": "[REDACTED]"}),
+            description: "Execute: echo hello".to_string(),
+            tool_call_id: "call_0".to_string(),
+            context_messages: vec![],
+            deferred_tool_calls: vec![],
+            user_timezone: None,
+            allow_always: true,
+        });
+
+        {
+            let mut sess = session.lock().await;
+            sess.threads.insert(
+                other_thread_id,
+                Thread::with_id(other_thread_id, session_id, Some("tui")),
+            );
+            sess.threads.insert(target_thread_id, target_thread);
+            sess.active_thread = Some(other_thread_id);
+        }
+
+        let message =
+            IncomingMessage::new("tui", "test-user", format!("/thread {target_thread_id}"));
+        let result = agent
+            .process_switch_thread(&message, target_thread_id)
+            .await
+            .expect("switch thread");
+
+        match result {
+            crate::agent::submission::SubmissionResult::Ok {
+                message: Some(text),
+            } => assert!(text.contains(&target_thread_id.to_string())),
+            other => panic!("expected ok switch-thread result, got {other:?}"),
+        }
+
+        let statuses = statuses.lock().expect("poisoned").clone();
+        assert!(
+            statuses.iter().any(|status| matches!(
+                status,
+                StatusUpdate::ConversationHistory {
+                    thread_id,
+                    messages,
+                    pending_approval,
+                } if thread_id == &target_thread_id.to_string()
+                    && messages.len() == 2
+                    && messages[0].role == "user"
+                    && messages[0].content == "Review the diff"
+                    && messages[1].role == "assistant"
+                    && messages[1].content == "Waiting for approval."
+                    && pending_approval
+                        .as_ref()
+                        .is_some_and(|approval| approval.tool_name == "shell"
+                            && approval.parameters == serde_json::json!({"command": "[REDACTED]"})
+                            && approval.allow_always)
+            )),
+            "expected conversation history status with pending approval, got: {statuses:?}"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_awaiting_approval_reemits_status_for_followup_message() {
+        use crate::agent::session::{PendingApproval, Session, Thread};
+
+        let (agent, statuses) = make_test_agent_with_status_channel("tui").await;
+        let mut session = Session::new("test-user");
+        let thread_id = Uuid::new_v4();
+        let mut thread = Thread::with_id(thread_id, session.id, Some("tui"));
+
+        let pending = PendingApproval {
+            request_id: Uuid::new_v4(),
+            tool_name: "shell".to_string(),
+            parameters: serde_json::json!({"command": "echo secret"}),
+            display_parameters: serde_json::json!({"command": "[REDACTED]"}),
+            description: "Execute: echo secret".to_string(),
+            tool_call_id: "call_0".to_string(),
+            context_messages: vec![],
+            deferred_tool_calls: vec![],
+            user_timezone: None,
+            allow_always: true,
+        };
+        thread.await_approval(pending.clone());
+        session.threads.insert(thread_id, thread);
+
+        let session = Arc::new(Mutex::new(session));
+        let rate = agent.deps.tenant_rates.get_or_create("test-user").await;
+        let tenant = crate::tenant::TenantCtx::new(
+            crate::ownership::Identity::new(
+                crate::ownership::OwnerId::from("test-user"),
+                crate::ownership::UserRole::Member,
+            ),
+            None,
+            None,
+            Arc::clone(&agent.deps.cost_guard),
+            rate,
+        );
+        let message = IncomingMessage::new("tui", "test-user", "what now?");
+
+        let result = agent
+            .process_user_input(&message, tenant, session, thread_id, &message.content)
+            .await
+            .expect("process user input");
+
+        match result {
+            crate::agent::submission::SubmissionResult::Ok {
+                message: Some(text),
+            } => {
+                assert!(
+                    text.contains("Waiting for approval"),
+                    "expected waiting text, got: {text}"
+                );
+            }
+            other => panic!("expected pending ok result, got {other:?}"),
+        }
+
+        let statuses = statuses.lock().expect("poisoned").clone();
+        assert!(
+            statuses.iter().any(|status| matches!(
+                status,
+                StatusUpdate::ApprovalNeeded {
+                    request_id,
+                    tool_name,
+                    description,
+                    parameters,
+                    allow_always,
+                } if request_id == &pending.request_id.to_string()
+                    && tool_name == "shell"
+                    && description == "Execute: echo secret"
+                    && parameters == &serde_json::json!({"command": "[REDACTED]"})
+                    && *allow_always
+            )),
+            "expected approval status to be re-emitted, got: {statuses:?}"
+        );
+    }
+
     #[test]
     fn test_queue_cap_rejects_at_capacity() {
         use crate::agent::session::{MAX_PENDING_MESSAGES, Thread, ThreadState};
diff --git a/src/app.rs b/src/app.rs
index 562d2959f77..d26027b351b 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -157,7 +157,8 @@ impl AppBuilder {
         }
 
         let toml_path = self.toml_path.as_deref();
-        match Config::from_db_with_toml(db.as_ref(), &self.config.owner_id, toml_path).await {
+        // is_operator=true: owner_id is the operator/admin scope.
+        match Config::from_db_with_toml(db.as_ref(), &self.config.owner_id, toml_path, true).await {
             Ok(db_config) => {
                 self.config = db_config;
                 tracing::debug!("Configuration reloaded from database");
@@ -264,6 +265,7 @@ impl AppBuilder {
                 self.db.as_ref().map(|db| db.as_ref() as _);
             let toml_path = self.toml_path.as_deref();
             let owner_id = self.config.owner_id.clone();
+            // is_operator=true: owner_id is the operator/admin scope.
             if let Err(e) = self
                 .config
                 .re_resolve_llm_with_secrets(
@@ -271,6 +273,7 @@ impl AppBuilder {
                     &owner_id,
                     toml_path,
                     Some(secrets.as_ref()),
+                    true,
                 )
                 .await
             {
@@ -377,13 +380,28 @@ impl AppBuilder {
                 );
             }
             ws = ws.with_memory_layers(self.config.workspace.memory_layers.clone());
-            let ws = Arc::new(ws);
 
             // Memory tools must resolve by `ctx.user_id`, not a fixed startup
             // workspace. Even outside authenticated multi-tenant mode, some
             // channels and test harnesses route non-owner users through
             // per-user tenant workspaces seeded on demand.
             let is_multi_tenant = db.has_any_users().await.unwrap_or(false);
+
+            // In multi-tenant mode, enable admin system prompt on the owner
+            // workspace so the dispatcher reads SYSTEM.md from __admin__ scope.
+            //
+            // NOTE: `is_multi_tenant` is evaluated once at startup. If the
+            // server starts with no users (single-user mode) and users are
+            // added later, the owner workspace frozen in `Arc` will NOT have
+            // `admin_prompt_enabled`. A server restart is required after the
+            // first user is created to activate admin prompts on the owner
+            // workspace. Tenant workspaces created via `WorkspacePool` are
+            // unaffected — they always call `.with_admin_prompt()`.
+            if is_multi_tenant {
+                ws = ws.with_admin_prompt();
+            }
+
+            let ws = Arc::new(ws);
             let pool = Arc::new(crate::channels::web::server::WorkspacePool::new(
                 Arc::clone(db),
                 embeddings.clone(),
diff --git a/src/bridge/router.rs b/src/bridge/router.rs
index 54af3192306..24d8c521b12 100644
--- a/src/bridge/router.rs
+++ b/src/bridge/router.rs
@@ -51,6 +51,68 @@ fn gate_display_parameters(pending: &PendingGate) -> serde_json::Value {
         .unwrap_or_else(|| pending.parameters.clone())
 }
 
+async fn send_pending_gate_status(agent: &Agent, message: &IncomingMessage, pending: &PendingGate) {
+    let display_parameters = gate_display_parameters(pending);
+
+    match &pending.resume_kind {
+        ironclaw_engine::ResumeKind::Approval { allow_always } => {
+            let _ = agent
+                .channels
+                .send_status(
+                    &message.channel,
+                    StatusUpdate::ApprovalNeeded {
+                        request_id: pending.request_id.to_string(),
+                        tool_name: pending.action_name.clone(),
+                        description: pending.description.clone(),
+                        parameters: display_parameters,
+                        allow_always: *allow_always,
+                    },
+                    &message.metadata,
+                )
+                .await;
+        }
+        ironclaw_engine::ResumeKind::Authentication {
+            credential_name,
+            instructions,
+            auth_url,
+        } => {
+            let _ = agent
+                .channels
+                .send_status(
+                    &message.channel,
+                    StatusUpdate::AuthRequired {
+                        extension_name: credential_name.clone(),
+                        instructions: Some(instructions.clone()),
+                        auth_url: auth_url.clone(),
+                        setup_url: None,
+                    },
+                    &message.metadata,
+                )
+                .await;
+        }
+        ironclaw_engine::ResumeKind::External { .. } => {}
+    }
+}
+
+fn pending_gate_prompt_message(pending: &PendingGate) -> Option<String> {
+    match &pending.resume_kind {
+        ironclaw_engine::ResumeKind::Approval { .. } => Some(format!(
+            "Tool '{}' requires approval. Reply 'yes' to approve, 'no' to deny.",
+            pending.action_name
+        )),
+        ironclaw_engine::ResumeKind::Authentication {
+            credential_name, ..
+        } => Some(format!(
+            "Authentication required for '{}'. Paste your token below (or type 'cancel'):",
+            credential_name
+        )),
+        ironclaw_engine::ResumeKind::External { .. } => Some(format!(
+            "Waiting for external confirmation (gate: {})...",
+            pending.gate_name
+        )),
+    }
+}
+
 fn resumed_action_result_message(
     action_name: &str,
     output: &serde_json::Value,
@@ -93,64 +155,16 @@ async fn insert_and_notify_pending_gate(
         );
     }
 
-    match &pending.resume_kind {
-        ironclaw_engine::ResumeKind::Approval { allow_always } => {
-            let _ = agent
-                .channels
-                .send_status(
-                    &message.channel,
-                    StatusUpdate::ApprovalNeeded {
-                        request_id: pending.request_id.to_string(),
-                        tool_name: pending.action_name.clone(),
-                        description: pending.description.clone(),
-                        parameters: display_parameters,
-                        allow_always: *allow_always,
-                    },
-                    &message.metadata,
-                )
-                .await;
-
-            Ok(Some(format!(
-                "Tool '{}' requires approval. Reply 'yes' to approve, 'no' to deny.",
-                pending.action_name
-            )))
-        }
-        ironclaw_engine::ResumeKind::Authentication {
-            credential_name,
-            instructions,
-            auth_url,
-        } => {
-            let _ = agent
-                .channels
-                .send_status(
-                    &message.channel,
-                    StatusUpdate::AuthRequired {
-                        extension_name: credential_name.clone(),
-                        instructions: Some(instructions.clone()),
-                        auth_url: auth_url.clone(),
-                        setup_url: None,
-                    },
-                    &message.metadata,
-                )
-                .await;
-
-            Ok(Some(format!(
-                "Authentication required for '{}'. Paste your token below (or type 'cancel'):",
-                credential_name
-            )))
-        }
-        ironclaw_engine::ResumeKind::External { callback_id } => {
-            tracing::debug!(
-                gate = %pending.gate_name,
-                callback = %callback_id,
-                "GatePaused(External)"
-            );
-            Ok(Some(format!(
-                "Waiting for external confirmation (gate: {})...",
-                pending.gate_name
-            )))
-        }
+    if let ironclaw_engine::ResumeKind::External { callback_id } = &pending.resume_kind {
+        tracing::debug!(
+            gate = %pending.gate_name,
+            callback = %callback_id,
+            "GatePaused(External)"
+        );
     }
+
+    send_pending_gate_status(agent, message, &pending).await;
+    Ok(pending_gate_prompt_message(&pending))
 }
 
 async fn execute_pending_gate_action(
@@ -1861,33 +1875,42 @@ async fn handle_with_engine_inner(
     let thread_scope = message.conversation_scope();
     let scoped_thread_id = parse_engine_thread_id(thread_scope);
 
-    if let PendingGateResolution::Resolved(gate) =
-        resolve_pending_gate_for_user(&state.pending_gates, &message.user_id, thread_scope).await
-        && matches!(
-            gate.resume_kind,
-            ironclaw_engine::ResumeKind::Authentication { .. }
-        )
+    match resolve_pending_gate_for_user(&state.pending_gates, &message.user_id, thread_scope).await
     {
-        let request_id = gate.request_id;
-        let resolution =
-            if content.trim().is_empty() || content.trim().eq_ignore_ascii_case("cancel") {
-                ironclaw_engine::GateResolution::Cancelled
-            } else {
-                ironclaw_engine::GateResolution::CredentialProvided {
-                    token: content.trim().to_string(),
-                }
-            };
-        drop(guard);
-        return resolve_gate(agent, message, gate.thread_id, request_id, resolution).await;
-    }
-
-    if matches!(
-        resolve_pending_gate_for_user(&state.pending_gates, &message.user_id, thread_scope).await,
-        PendingGateResolution::Ambiguous
-    ) {
-        return Ok(Some(
-            "Multiple authentication prompts are waiting. Reply from the original thread.".into(),
-        ));
+        PendingGateResolution::Resolved(gate)
+            if matches!(
+                gate.resume_kind,
+                ironclaw_engine::ResumeKind::Authentication { .. }
+            ) =>
+        {
+            let request_id = gate.request_id;
+            let resolution =
+                if content.trim().is_empty() || content.trim().eq_ignore_ascii_case("cancel") {
+                    ironclaw_engine::GateResolution::Cancelled
+                } else {
+                    ironclaw_engine::GateResolution::CredentialProvided {
+                        token: content.trim().to_string(),
+                    }
+                };
+            drop(guard);
+            return resolve_gate(agent, message, gate.thread_id, request_id, resolution).await;
+        }
+        PendingGateResolution::Resolved(gate)
+            if matches!(
+                gate.resume_kind,
+                ironclaw_engine::ResumeKind::Approval { .. }
+            ) =>
+        {
+            drop(guard);
+            send_pending_gate_status(agent, message, &gate).await;
+            return Ok(pending_gate_prompt_message(&gate));
+        }
+        PendingGateResolution::Ambiguous => {
+            return Ok(Some(
+                "Multiple pending gates are waiting. Reply from the original thread.".into(),
+            ));
+        }
+        PendingGateResolution::Resolved(_) | PendingGateResolution::None => {}
     }
 
     if let Some(thread_id) = scoped_thread_id
@@ -2437,6 +2460,8 @@ async fn forward_event_to_channel(
                     channel_name,
                     StatusUpdate::ToolStarted {
                         name: display_name.clone(),
+                        detail: params_summary.clone(),
+                        call_id: None,
                     },
                     metadata,
                 )
@@ -2449,6 +2474,7 @@ async fn forward_event_to_channel(
                         success: true,
                         error: None,
                         parameters: Some(format!("{duration_ms}ms")),
+                        call_id: None,
                     },
                     metadata,
                 )
@@ -2466,6 +2492,8 @@ async fn forward_event_to_channel(
                     channel_name,
                     StatusUpdate::ToolStarted {
                         name: display_name.clone(),
+                        detail: params_summary.clone(),
+                        call_id: None,
                     },
                     metadata,
                 )
@@ -2478,6 +2506,7 @@ async fn forward_event_to_channel(
                         success: false,
                         error: Some(error.clone()),
                         parameters: None,
+                        call_id: None,
                     },
                     metadata,
                 )
@@ -2568,6 +2597,7 @@ fn thread_event_to_app_events(
             vec![
                 AppEvent::ToolStarted {
                     name: display_name.clone(),
+                    detail: params_summary.clone(),
                     thread_id: Some(thread_id.into()),
                 },
                 AppEvent::ToolCompleted {
@@ -2589,6 +2619,7 @@ fn thread_event_to_app_events(
             vec![
                 AppEvent::ToolStarted {
                     name: display_name.clone(),
+                    detail: params_summary.clone(),
                     thread_id: Some(thread_id.into()),
                 },
                 AppEvent::ToolCompleted {
@@ -3269,10 +3300,23 @@ async fn migrate_legacy_user_ids(store: &Arc<dyn ironclaw_engine::Store>, owner_
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::sync::Arc;
     use std::sync::LazyLock;
+    use std::sync::Mutex as StdMutex;
+    use std::time::Duration;
     use tokio::sync::Mutex as TokioMutex;
     use tokio::sync::RwLock as TokioRwLock;
 
+    use crate::agent::AgentDeps;
+    use crate::agent::cost_guard::{CostGuard, CostGuardConfig};
+    use crate::channels::{ChannelManager, IncomingMessage, StatusUpdate};
+    use crate::config::{AgentConfig, SafetyConfig, SkillsConfig};
+    use crate::context::ContextManager;
+    use crate::hooks::HookRegistry;
+    use crate::testing::{StubChannel, StubLlm};
+    use crate::tools::ToolRegistry;
+    use ironclaw_safety::SafetyLayer;
+
     static ENGINE_STATE_TEST_LOCK: LazyLock<TokioMutex<()>> = LazyLock::new(|| TokioMutex::new(()));
 
     struct TestStore {
@@ -3759,6 +3803,141 @@ mod tests {
         }
     }
 
+    async fn make_test_agent_with_status_channel(
+        channel_name: &str,
+    ) -> (Agent, Arc<StdMutex<Vec<StatusUpdate>>>) {
+        let (stub, _sender) = StubChannel::new(channel_name);
+        let statuses = stub.captured_statuses_handle();
+        let manager = ChannelManager::new();
+        manager.add(Box::new(stub)).await;
+
+        let deps = AgentDeps {
+            owner_id: "default".to_string(),
+            store: None,
+            llm: Arc::new(StubLlm::default()),
+            cheap_llm: None,
+            safety: Arc::new(SafetyLayer::new(&SafetyConfig {
+                max_output_length: 100_000,
+                injection_check_enabled: false,
+            })),
+            tools: Arc::new(ToolRegistry::new()),
+            workspace: None,
+            extension_manager: None,
+            skill_registry: None,
+            skill_catalog: None,
+            skills_config: SkillsConfig::default(),
+            hooks: Arc::new(HookRegistry::new()),
+            cost_guard: Arc::new(CostGuard::new(CostGuardConfig::default())),
+            sse_tx: None,
+            http_interceptor: None,
+            transcription: None,
+            document_extraction: None,
+            sandbox_readiness: crate::agent::routine_engine::SandboxReadiness::DisabledByConfig,
+            builder: None,
+            llm_backend: "nearai".to_string(),
+            tenant_rates: Arc::new(crate::tenant::TenantRateRegistry::new(4, 3)),
+        };
+
+        let agent = Agent::new(
+            AgentConfig {
+                name: "test-agent".to_string(),
+                max_parallel_jobs: 1,
+                job_timeout: Duration::from_secs(60),
+                stuck_threshold: Duration::from_secs(60),
+                repair_check_interval: Duration::from_secs(30),
+                max_repair_attempts: 1,
+                use_planning: false,
+                session_idle_timeout: Duration::from_secs(300),
+                allow_local_tools: false,
+                max_cost_per_day_cents: None,
+                max_actions_per_hour: None,
+                max_cost_per_user_per_day_cents: None,
+                max_tool_iterations: 50,
+                auto_approve_tools: false,
+                default_timezone: "UTC".to_string(),
+                max_jobs_per_user: None,
+                max_tokens_per_job: 0,
+                multi_tenant: false,
+                max_llm_concurrent_per_user: None,
+                max_jobs_concurrent_per_user: None,
+                engine_v2: true,
+            },
+            deps,
+            Arc::new(manager),
+            None,
+            None,
+            None,
+            Some(Arc::new(ContextManager::new(1))),
+            None,
+        );
+
+        (agent, statuses)
+    }
+
+    #[tokio::test]
+    async fn handle_with_engine_reemits_approval_status_for_pending_gate() {
+        let _guard = ENGINE_STATE_TEST_LOCK.lock().await;
+        let lock = ENGINE_STATE.get_or_init(|| RwLock::new(None));
+        *lock.write().await = None;
+
+        let outcome = async {
+            let store = Arc::new(TestStore::new());
+            let state = make_expected_test_state(store);
+            let thread_id = ironclaw_engine::ThreadId::new();
+            let pending = sample_pending_gate(
+                "alice",
+                thread_id,
+                ironclaw_engine::ResumeKind::Approval { allow_always: true },
+            );
+            state
+                .pending_gates
+                .insert(pending.clone())
+                .await
+                .expect("insert pending gate");
+
+            *lock.write().await = Some(state);
+
+            let (agent, statuses) = make_test_agent_with_status_channel("tui").await;
+            let message = IncomingMessage::new("tui", "alice", "what now?")
+                .with_thread(thread_id.to_string());
+
+            let result = handle_with_engine_inner(&agent, &message, &message.content, 0)
+                .await
+                .expect("handle with engine");
+
+            let text = result.expect("waiting message");
+            assert!(
+                text.contains("approval"),
+                "expected approval guidance, got: {text}"
+            );
+
+            let statuses = statuses.lock().expect("poisoned").clone();
+            assert!(
+                statuses.iter().any(|status| matches!(
+                    status,
+                    StatusUpdate::ApprovalNeeded {
+                        request_id,
+                        tool_name,
+                        description,
+                        parameters,
+                        allow_always,
+                    } if request_id == &pending.request_id.to_string()
+                        && tool_name == "shell"
+                        && description == "pending gate"
+                        && parameters == &serde_json::json!({"cmd": "ls"})
+                        && *allow_always
+                )),
+                "expected approval status to be re-emitted, got: {statuses:?}"
+            );
+
+            Ok::<(), crate::error::Error>(())
+        }
+        .await;
+
+        *lock.write().await = None;
+        outcome.expect("router approval re-emit test");
+    }
+
     /// find_most_recent_thread returns the active thread when one exists.
     #[tokio::test]
     async fn find_recent_thread_returns_active() {
diff --git a/src/bridge/skill_migration.rs b/src/bridge/skill_migration.rs
index 86b94cedad0..744dc5867fa 100644
--- a/src/bridge/skill_migration.rs
+++ b/src/bridge/skill_migration.rs
@@ -110,6 +110,8 @@ fn v1_skill_to_memory_doc(skill: &LoadedSkill, project_id: ProjectId) -> MemoryD
         code_snippets: vec![], // v1 skills are prompt-only
         metrics: SkillMetrics::default(),
         parent_version: None,
+        revisions: vec![],
+        repairs: vec![],
         content_hash: skill.content_hash.clone(),
     };
 
diff --git a/src/channels/channel.rs b/src/channels/channel.rs
index 3a2924dfde4..8a815ddb779 100644
--- a/src/channels/channel.rs
+++ b/src/channels/channel.rs
@@ -270,7 +270,14 @@ pub enum StatusUpdate {
     /// Agent is thinking/processing.
     Thinking(String),
     /// Tool execution started.
-    ToolStarted { name: String },
+    ToolStarted {
+        name: String,
+        /// Short contextual summary extracted from tool arguments.
+        detail: Option<String>,
+        /// Stable tool-call ID when available, used to disambiguate repeated
+        /// calls to the same tool name in a single turn.
+        call_id: Option<String>,
+    },
     /// Tool execution completed.
     ///
     /// Use [`StatusUpdate::tool_completed`] to construct this variant — it
@@ -285,9 +292,16 @@ pub enum StatusUpdate {
         /// Only populated when `success` is `false`. Values listed in the
         /// tool's `sensitive_params()` are replaced with `"[REDACTED]"`.
         parameters: Option<String>,
+        /// Stable tool-call ID when available.
+        call_id: Option<String>,
     },
     /// Brief preview of tool execution output.
-    ToolResult { name: String, preview: String },
+    ToolResult {
+        name: String,
+        preview: String,
+        /// Stable tool-call ID when available.
+        call_id: Option<String>,
+    },
     /// Streaming text chunk.
     StreamChunk(String),
     /// General status message.
@@ -330,6 +344,41 @@ pub enum StatusUpdate {
         /// Optional workspace path where the image was saved.
         path: Option<String>,
     },
+    /// A sandbox job's status changed.
+    JobStatus { job_id: String, status: String },
+    /// A sandbox job completed with final result.
+    JobResult { job_id: String, status: String },
+    /// A routine was created, updated, or deleted.
+    RoutineUpdate {
+        id: String,
+        name: String,
+        trigger_type: String,
+        enabled: bool,
+        last_run: Option<String>,
+        next_fire: Option<String>,
+    },
+    /// Context pressure update (token usage approaching limit).
+    ContextPressure {
+        used_tokens: u64,
+        max_tokens: u64,
+        percentage: u8,
+        warning: Option<String>,
+    },
+    /// Sandbox / Docker status update.
+    SandboxStatus {
+        docker_available: bool,
+        running_containers: u32,
+        status: String,
+    },
+    /// Secrets vault status update.
+    SecretsStatus { count: u32, vault_unlocked: bool },
+    /// Cost guard / budget status update.
+    CostGuard {
+        session_budget_usd: Option<String>,
+        spent_usd: String,
+        remaining_usd: Option<String>,
+        limit_reached: bool,
+    },
     /// Suggested follow-up messages for the user.
     Suggestions { suggestions: Vec<String> },
     /// Agent reasoning update (why it chose specific tools).
@@ -347,6 +396,47 @@ pub enum StatusUpdate {
     },
     /// Skills activated for this conversation turn.
     SkillActivated { skill_names: Vec<String> },
+    /// Thread list for interactive resume picker.
+    ThreadList { threads: Vec<ThreadSummary> },
+    /// Engine v2 thread list for TUI activity sidebar.
+    EngineThreadList { threads: Vec<EngineThreadSummary> },
+    /// Full conversation history for displaying a resumed thread in the TUI.
+    ConversationHistory {
+        thread_id: String,
+        messages: Vec<HistoryMessage>,
+        pending_approval: Option<ChatApprovalPrompt>,
+    },
+}
+
+/// A single message from conversation history, for hydrating the TUI on thread resume.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct HistoryMessage {
+    pub role: String,
+    pub content: String,
+    pub timestamp: chrono::DateTime<chrono::Utc>,
+}
+
+/// Engine v2 thread summary for TUI sidebar display.
+#[derive(Debug, Clone)]
+pub struct EngineThreadSummary {
+    pub id: String,
+    pub goal: String,
+    pub thread_type: String,
+    pub state: String,
+    pub step_count: usize,
+    pub total_tokens: u64,
+    pub created_at: String,
+    pub updated_at: String,
+}
+
+/// Lightweight thread summary for the resume picker.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ThreadSummary {
+    pub id: String,
+    pub title: Option<String>,
+    pub message_count: i64,
+    pub last_activity: String,
+    pub channel: String,
 }
 
 /// Shared chat-style approval prompt formatting used by non-web channels.
@@ -362,8 +452,71 @@ pub struct ChatApprovalPrompt {
 const APPROVAL_PARAMETER_PREVIEW_BYTES: usize = 1200;
 const APPROVAL_PARAMETER_TRUNCATION_SUFFIX: &str = "\n... [parameters truncated]";
 const APPROVAL_SUMMARY_DESCRIPTION_BYTES: usize = 120;
+const DETAIL_MAX_LEN: usize = 80;
+
+/// Extract a short, non-sensitive one-liner from tool arguments.
+///
+/// Returns `None` for unknown tools or when no relevant field is present.
+pub fn tool_call_detail(name: &str, args: &serde_json::Value) -> Option<String> {
+    let raw = match name {
+        "http" | "http_request" | "web_fetch" => {
+            let method = args.get("method").and_then(|v| v.as_str()).unwrap_or("GET");
+            let url = args.get("url").and_then(|v| v.as_str())?;
+            format!("{method} {url}")
+        }
+        "shell" | "execute_command" => args.get("command").and_then(|v| v.as_str())?.to_string(),
+        "read_file" | "write_file" | "list_dir" => {
+            args.get("path").and_then(|v| v.as_str())?.to_string()
+        }
+        "memory_search" => {
+            let q = args.get("query").and_then(|v| v.as_str())?;
+            format!("query: {q}")
+        }
+        "memory_read" => args.get("path").and_then(|v| v.as_str())?.to_string(),
+        "memory_write" => {
+            let target = args.get("target").and_then(|v| v.as_str())?;
+            format!("target: {target}")
+        }
+        "create_job" => args.get("title").and_then(|v| v.as_str())?.to_string(),
+        "message" | "send_message" => {
+            let channel = args.get("channel").and_then(|v| v.as_str())?;
+            format!("to: {channel}")
+        }
+        "skill_search" | "tool_search" => args.get("query").and_then(|v| v.as_str())?.to_string(),
+        _ => return None,
+    };
+
+    Some(truncate_detail(&raw))
+}
+
+fn truncate_detail(s: &str) -> String {
+    if s.chars().count() <= DETAIL_MAX_LEN {
+        s.to_string()
+    } else {
+        let truncated: String = s.chars().take(DETAIL_MAX_LEN.saturating_sub(3)).collect();
+        format!("{truncated}...")
+    }
+}
 
 impl StatusUpdate {
+    /// Build a `ToolStarted` status with a derived contextual detail.
+    pub fn tool_started(name: String, arguments: &serde_json::Value) -> Self {
+        Self::tool_started_with_id(name, arguments, None)
+    }
+
+    /// Build a `ToolStarted` status with an explicit tool-call ID.
+    pub fn tool_started_with_id(
+        name: String,
+        arguments: &serde_json::Value,
+        call_id: Option<String>,
+    ) -> Self {
+        Self::ToolStarted {
+            detail: tool_call_detail(&name, arguments),
+            name,
+            call_id,
+        }
+    }
+
     /// Build a `ToolCompleted` status with redacted parameters.
     ///
     /// On failure, serializes the tool's input parameters as pretty JSON after
@@ -375,6 +528,7 @@ impl StatusUpdate {
     /// borrow lifetime of the sensitive slice.
     pub fn tool_completed(
         name: String,
+        call_id: Option<String>,
         result: &Result<String, crate::error::Error>,
         params: &serde_json::Value,
         tool: Option<&dyn crate::tools::Tool>,
@@ -391,6 +545,7 @@ impl StatusUpdate {
             } else {
                 None
             },
+            call_id,
         }
     }
 }
@@ -654,6 +809,7 @@ mod tests {
 
         let status = StatusUpdate::tool_completed(
             "secret_save".into(),
+            None,
             &err,
             &params,
             Some(&tool as &dyn crate::tools::Tool),
@@ -697,7 +853,7 @@ mod tests {
         let params = serde_json::json!({"name": "key", "value": "secret"});
         let ok: Result<String, crate::error::Error> = Ok("done".into());
 
-        let status = StatusUpdate::tool_completed("secret_save".into(), &ok, &params, None);
+        let status = StatusUpdate::tool_completed("secret_save".into(), None, &ok, &params, None);
 
         if let StatusUpdate::ToolCompleted {
             success,
@@ -724,7 +880,7 @@ mod tests {
             }
             .into());
 
-        let status = StatusUpdate::tool_completed("shell".into(), &err, &params, None);
+        let status = StatusUpdate::tool_completed("shell".into(), None, &err, &params, None);
 
         if let StatusUpdate::ToolCompleted { parameters, .. } = &status {
             let param_str = parameters.as_ref().expect("should have parameters");
@@ -744,6 +900,43 @@ mod tests {
         assert_eq!(msg.timezone.as_deref(), Some("America/New_York"));
     }
 
+    #[test]
+    fn tool_call_detail_http() {
+        let args = serde_json::json!({"method": "POST", "url": "https://api.example.com/data"});
+        let detail = super::tool_call_detail("http", &args);
+        assert_eq!(detail.as_deref(), Some("POST https://api.example.com/data"));
+    }
+
+    #[test]
+    fn tool_call_detail_shell() {
+        let args = serde_json::json!({"command": "cargo test --all"});
+        let detail = super::tool_call_detail("shell", &args);
+        assert_eq!(detail.as_deref(), Some("cargo test --all"));
+    }
+
+    #[test]
+    fn tool_call_detail_memory_search() {
+        let args = serde_json::json!({"query": "database migration"});
+        let detail = super::tool_call_detail("memory_search", &args);
+        assert_eq!(detail.as_deref(), Some("query: database migration"));
+    }
+
+    #[test]
+    fn tool_call_detail_unknown_tool() {
+        let args = serde_json::json!({"foo": "bar"});
+        let detail = super::tool_call_detail("unknown_tool_xyz", &args);
+        assert!(detail.is_none());
+    }
+
+    #[test]
+    fn tool_call_detail_truncation() {
+        let long_url = format!("https://example.com/{}", "a".repeat(100));
+        let args = serde_json::json!({"url": long_url});
+        let detail = super::tool_call_detail("http", &args).unwrap();
+        assert!(detail.chars().count() <= super::DETAIL_MAX_LEN);
+        assert!(detail.ends_with("..."));
+    }
+
     #[test]
     fn routing_target_extracts_slack_channel_id() {
         // Slack relay messages carry channel_id in metadata — this must be
diff --git a/src/channels/mod.rs b/src/channels/mod.rs
index 7f0a929240e..653b0310740 100644
--- a/src/channels/mod.rs
+++ b/src/channels/mod.rs
@@ -33,14 +33,18 @@ mod manager;
 pub mod relay;
 mod repl;
 mod signal;
+#[cfg(feature = "tui")]
+pub mod tui;
 pub mod wasm;
 pub mod web;
 mod webhook_server;
 
+#[cfg(feature = "tui")]
+pub use self::tui::TuiChannel;
 pub use channel::{
-    AttachmentKind, Channel, ChannelSecretUpdater, ChatApprovalPrompt, IncomingAttachment,
-    IncomingMessage, MessageStream, OutgoingResponse, StatusUpdate, ToolDecision,
-    routing_target_from_metadata,
+    AttachmentKind, Channel, ChannelSecretUpdater, ChatApprovalPrompt, EngineThreadSummary,
+    HistoryMessage, IncomingAttachment, IncomingMessage, MessageStream, OutgoingResponse,
+    StatusUpdate, ThreadSummary, ToolDecision, routing_target_from_metadata,
 };
 pub use http::{HttpChannel, HttpChannelState};
 pub use manager::ChannelManager;
diff --git a/src/channels/relay/channel.rs b/src/channels/relay/channel.rs
index 858c8e446e0..cb6402fbb33 100644
--- a/src/channels/relay/channel.rs
+++ b/src/channels/relay/channel.rs
@@ -655,6 +655,8 @@ mod tests {
             .send_status(
                 StatusUpdate::ToolStarted {
                     name: "echo".into(),
+                    detail: None,
+                    call_id: None,
                 },
                 &metadata,
             )
diff --git a/src/channels/repl.rs b/src/channels/repl.rs
index 8780ac8f10e..22d1974aeb7 100644
--- a/src/channels/repl.rs
+++ b/src/channels/repl.rs
@@ -715,9 +715,13 @@ impl Channel for ReplChannel {
                 eprintln!("  {}\u{25CB} {display}{}", fmt::dim(), fmt::reset());
                 self.transient_lines.store(1, Ordering::Relaxed);
             }
-            StatusUpdate::ToolStarted { name } => {
+            StatusUpdate::ToolStarted { name, detail, .. } => {
                 self.clear_transient();
-                eprintln!("  {}\u{25CB} {name}{}", fmt::dim(), fmt::reset());
+                if let Some(d) = detail {
+                    eprintln!("  {}\u{25CB} {name}: {d}{}", fmt::dim(), fmt::reset());
+                } else {
+                    eprintln!("  {}\u{25CB} {name}{}", fmt::dim(), fmt::reset());
+                }
                 self.transient_lines.store(1, Ordering::Relaxed);
             }
             StatusUpdate::ToolCompleted { name, success, .. } => {
@@ -728,7 +732,9 @@ impl Channel for ReplChannel {
                     eprintln!("  {}\u{2717} {name} (failed){}", fmt::error(), fmt::reset());
                 }
             }
-            StatusUpdate::ToolResult { name: _, preview } => {
+            StatusUpdate::ToolResult {
+                name: _, preview, ..
+            } => {
                 let display = truncate_for_preview(&preview, CLI_TOOL_RESULT_MAX);
                 eprintln!("    {}{display}{}", fmt::dim(), fmt::reset());
             }
@@ -881,6 +887,18 @@ impl Channel for ReplChannel {
             StatusUpdate::TurnCost { .. } => {
                 // Cost display is handled by the TUI channel
             }
+            StatusUpdate::JobStatus { .. }
+            | StatusUpdate::JobResult { .. }
+            | StatusUpdate::RoutineUpdate { .. }
+            | StatusUpdate::ContextPressure { .. }
+            | StatusUpdate::SandboxStatus { .. }
+            | StatusUpdate::SecretsStatus { .. }
+            | StatusUpdate::CostGuard { .. }
+            | StatusUpdate::ThreadList { .. }
+            | StatusUpdate::EngineThreadList { .. }
+            | StatusUpdate::ConversationHistory { .. } => {
+                // Infrastructure status events are only rendered by the TUI.
+            }
             StatusUpdate::SkillActivated { skill_names } => {
                 if !skill_names.is_empty() {
                     eprintln!(
diff --git a/src/channels/signal.rs b/src/channels/signal.rs
index 68f24953660..d350e35f65f 100644
--- a/src/channels/signal.rs
+++ b/src/channels/signal.rs
@@ -1014,7 +1014,7 @@ impl Channel for SignalChannel {
 
         // Send tool result previews to user (debug mode only)
         if self.is_debug()
-            && let StatusUpdate::ToolResult { name, preview } = &status
+            && let StatusUpdate::ToolResult { name, preview, .. } = &status
             && let Some(target_str) = metadata.get("signal_target").and_then(|v| v.as_str())
         {
             let truncated = if preview.chars().count() > 500 {
@@ -1029,7 +1029,7 @@ impl Channel for SignalChannel {
 
         // Send tool started notification (debug mode only)
         if self.is_debug()
-            && let StatusUpdate::ToolStarted { name } = &status
+            && let StatusUpdate::ToolStarted { name, .. } = &status
             && let Some(target_str) = metadata.get("signal_target").and_then(|v| v.as_str())
         {
             let message = format!("\u{25CB} Running tool: {}", name);
diff --git a/src/channels/tui.rs b/src/channels/tui.rs
new file mode 100644
index 00000000000..b13228adee0
--- /dev/null
+++ b/src/channels/tui.rs
@@ -0,0 +1,704 @@
+//! TUI channel — bridges the `Channel` trait to `ironclaw_tui`.
+//!
+//! The TUI crate owns the terminal and event loop. This module translates
+//! between the agent's `Channel` trait and `ironclaw_tui`'s event/message
+//! channels.
+
+use std::path::Path;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use async_trait::async_trait;
+use tokio::sync::{Mutex, mpsc};
+use tokio_stream::wrappers::ReceiverStream;
+
+use ironclaw_tui::{SkillCategory, ToolCategory, TuiAppConfig, TuiEvent, TuiLayout, start_tui};
+
+use crate::channels::web::log_layer::LogBroadcaster;
+use crate::channels::{
+    AttachmentKind, Channel, IncomingAttachment, IncomingMessage, MessageStream, OutgoingResponse,
+    StatusUpdate,
+};
+use crate::error::ChannelError;
+
+/// Group tool names by their prefix (text before the first `_`).
+///
+/// Tools like `memory_search`, `memory_write` become `memory: search, write`.
+/// Tools without an underscore are placed in a "general" category.
+pub fn group_tools_by_prefix(mut names: Vec<String>) -> Vec<ToolCategory> {
+    use std::collections::BTreeMap;
+    names.sort();
+
+    let mut groups: BTreeMap<String, Vec<String>> = BTreeMap::new();
+    for name in &names {
+        if let Some(pos) = name.find('_') {
+            let prefix = &name[..pos];
+            let suffix = &name[pos + 1..];
+            groups
+                .entry(prefix.to_string())
+                .or_default()
+                .push(suffix.to_string());
+        } else {
+            groups
+                .entry("general".to_string())
+                .or_default()
+                .push(name.clone());
+        }
+    }
+
+    groups
+        .into_iter()
+        .map(|(name, tools)| ToolCategory { name, tools })
+        .collect()
+}
+
+/// Group skills by their first tag.
+///
+/// Skills without tags are placed in a "general" category.
+pub fn group_skills_by_tag(
+    skills: &[(String, Vec<String>)], // (name, tags)
+) -> Vec<SkillCategory> {
+    use std::collections::BTreeMap;
+
+    let mut groups: BTreeMap<String, Vec<String>> = BTreeMap::new();
+    for (name, tags) in skills {
+        let category = tags
+            .first()
+            .cloned()
+            .unwrap_or_else(|| "general".to_string());
+        groups.entry(category).or_default().push(name.clone());
+    }
+
+    groups
+        .into_iter()
+        .map(|(name, skills)| SkillCategory { name, skills })
+        .collect()
+}
+
+/// Resolve the effective TUI layout from the workspace file plus env-backed
+/// channel config. File-based widget settings are loaded first, then the
+/// explicit config overrides theme and sidebar visibility.
+pub fn resolve_tui_layout(
+    config: &crate::config::TuiChannelConfig,
+    workspace_root: &Path,
+) -> TuiLayout {
+    let layout_path = workspace_root.join("tui").join("layout.json");
+    let mut layout = TuiLayout::load_from_file(&layout_path);
+    layout.theme = config.theme.clone();
+    layout.sidebar.visible = config.sidebar_visible;
+    layout
+}
+
+fn infer_context_window(model_id: &str) -> u64 {
+    let normalized = model_id
+        .trim()
+        .to_ascii_lowercase()
+        .rsplit('/')
+        .next()
+        .unwrap_or(model_id)
+        .split(':')
+        .next()
+        .unwrap_or(model_id)
+        .to_string();
+
+    if normalized.contains("claude-opus-4-6") || normalized.contains("claude-sonnet-4-6") {
+        return 1_000_000;
+    }
+
+    if normalized.contains("claude") {
+        return 200_000;
+    }
+
+    if normalized.starts_with("gemini-") {
+        return 1_000_000;
+    }
+
+    128_000
+}
+
+fn build_tui_incoming_message(
+    user_msg: ironclaw_tui::TuiUserMessage,
+    user_id: &str,
+    sys_tz: &str,
+) -> IncomingMessage {
+    let attachments: Vec<IncomingAttachment> = user_msg
+        .attachments
+        .into_iter()
+        .enumerate()
+        .map(|(i, a)| IncomingAttachment {
+            id: format!("tui-paste-{i}"),
+            kind: AttachmentKind::Image,
+            mime_type: a.mime_type,
+            filename: Some(format!("{}.png", a.label)),
+            size_bytes: Some(a.data.len() as u64),
+            source_url: None,
+            storage_key: None,
+            extracted_text: None,
+            data: a.data,
+            duration_secs: None,
+        })
+        .collect();
+
+    let msg = IncomingMessage::new("tui", user_id, &user_msg.text)
+        .with_timezone(sys_tz)
+        .with_attachments(attachments);
+
+    if let Some(thread_id) = user_msg.thread_id {
+        msg.with_thread(thread_id)
+    } else {
+        msg
+    }
+}
+
+fn build_engine_thread_detail_event(detail: crate::bridge::EngineThreadDetail) -> TuiEvent {
+    let messages = detail
+        .messages
+        .into_iter()
+        .map(|message| ironclaw_tui::EngineThreadMessageEntry {
+            role: message
+                .get("role")
+                .and_then(serde_json::Value::as_str)
+                .unwrap_or("Unknown")
+                .to_string(),
+            content: message
+                .get("content")
+                .and_then(serde_json::Value::as_str)
+                .unwrap_or_default()
+                .to_string(),
+            timestamp: message
+                .get("timestamp")
+                .and_then(serde_json::Value::as_str)
+                .unwrap_or_default()
+                .to_string(),
+        })
+        .collect();
+
+    TuiEvent::EngineThreadDetail {
+        detail: ironclaw_tui::EngineThreadDetailEntry {
+            id: detail.info.id,
+            goal: detail.info.goal,
+            thread_type: detail.info.thread_type,
+            state: detail.info.state,
+            project_id: detail.info.project_id,
+            parent_id: detail.info.parent_id,
+            step_count: detail.info.step_count,
+            total_tokens: detail.info.total_tokens,
+            created_at: detail.info.created_at,
+            updated_at: detail.info.updated_at,
+            max_iterations: detail.max_iterations,
+            completed_at: detail.completed_at,
+            total_cost_usd: detail.total_cost_usd,
+            messages,
+        },
+    }
+}
+
+/// TUI channel backed by `ironclaw_tui`.
+pub struct TuiChannel {
+    user_id: String,
+    event_tx: Arc<Mutex<Option<mpsc::Sender<TuiEvent>>>>,
+    started: AtomicBool,
+    version: String,
+    model: String,
+    context_window: u64,
+    layout: TuiLayout,
+    log_broadcaster: Option<Arc<LogBroadcaster>>,
+    tools: Vec<ToolCategory>,
+    skills: Vec<SkillCategory>,
+    workspace_path: String,
+    memory_count: usize,
+    identity_files: Vec<String>,
+    available_models: Vec<String>,
+}
+
+impl TuiChannel {
+    /// Create a new TUI channel.
+    pub fn new(
+        user_id: impl Into<String>,
+        version: impl Into<String>,
+        model: impl Into<String>,
+    ) -> Self {
+        let model = model.into();
+        Self {
+            user_id: user_id.into(),
+            event_tx: Arc::new(Mutex::new(None)),
+            started: AtomicBool::new(false),
+            version: version.into(),
+            context_window: infer_context_window(&model),
+            model,
+            layout: TuiLayout::default(),
+            log_broadcaster: None,
+            tools: Vec::new(),
+            skills: Vec::new(),
+            workspace_path: String::new(),
+            memory_count: 0,
+            identity_files: Vec::new(),
+            available_models: Vec::new(),
+        }
+    }
+
+    /// Override the initial context window shown in the TUI.
+    pub fn with_context_window(mut self, context_window: u64) -> Self {
+        self.context_window = context_window;
+        self
+    }
+
+    /// Set the layout configuration.
+    pub fn with_layout(mut self, layout: TuiLayout) -> Self {
+        self.layout = layout;
+        self
+    }
+
+    /// Set the log broadcaster for forwarding log entries to the TUI.
+    pub fn with_log_broadcaster(mut self, broadcaster: Arc<LogBroadcaster>) -> Self {
+        self.log_broadcaster = Some(broadcaster);
+        self
+    }
+
+    /// Set tool categories for the welcome screen.
+    pub fn with_tools(mut self, tools: Vec<ToolCategory>) -> Self {
+        self.tools = tools;
+        self
+    }
+
+    /// Set skill categories for the welcome screen.
+    pub fn with_skills(mut self, skills: Vec<SkillCategory>) -> Self {
+        self.skills = skills;
+        self
+    }
+
+    /// Set workspace path for the welcome screen.
+    pub fn with_workspace_path(mut self, path: impl Into<String>) -> Self {
+        self.workspace_path = path.into();
+        self
+    }
+
+    /// Set the memory entry count for the welcome screen.
+    pub fn with_memory_count(mut self, count: usize) -> Self {
+        self.memory_count = count;
+        self
+    }
+
+    /// Set the identity files for the welcome screen.
+    pub fn with_identity_files(mut self, files: Vec<String>) -> Self {
+        self.identity_files = files;
+        self
+    }
+
+    /// Set the available models for the `/model` picker.
+    pub fn with_available_models(mut self, models: Vec<String>) -> Self {
+        self.available_models = models;
+        self
+    }
+}
+
+#[async_trait]
+impl Channel for TuiChannel {
+    fn name(&self) -> &str {
+        "tui"
+    }
+
+    async fn start(&self) -> Result<MessageStream, ChannelError> {
+        if self.started.swap(true, Ordering::Relaxed) {
+            return Err(ChannelError::StartupFailed {
+                name: "tui".to_string(),
+                reason: "TUI channel already started".to_string(),
+            });
+        }
+
+        let config = TuiAppConfig {
+            version: self.version.clone(),
+            model: self.model.clone(),
+            layout: self.layout.clone(),
+            context_window: self.context_window,
+            tools: self.tools.clone(),
+            skills: self.skills.clone(),
+            workspace_path: self.workspace_path.clone(),
+            memory_count: self.memory_count,
+            identity_files: self.identity_files.clone(),
+            available_models: self.available_models.clone(),
+        };
+
+        let ironclaw_tui::TuiAppHandle {
+            event_tx,
+            mut msg_rx,
+            join_handle: _join,
+        } = start_tui(config);
+
+        // Store event_tx for sending status updates and responses
+        *self.event_tx.lock().await = Some(event_tx.clone());
+
+        // Forward log entries from the LogBroadcaster to the TUI's Logs tab
+        if let Some(ref broadcaster) = self.log_broadcaster {
+            // Replay recent history first
+            let log_tx = event_tx.clone();
+            for entry in broadcaster.recent_entries() {
+                let _ = log_tx
+                    .send(TuiEvent::Log {
+                        level: entry.level,
+                        target: entry.target,
+                        message: entry.message,
+                        timestamp: entry.timestamp,
+                    })
+                    .await;
+            }
+
+            // Subscribe to live log stream
+            let mut log_rx = broadcaster.subscribe();
+            tokio::spawn(async move {
+                while let Ok(entry) = log_rx.recv().await {
+                    let event = TuiEvent::Log {
+                        level: entry.level,
+                        target: entry.target,
+                        message: entry.message,
+                        timestamp: entry.timestamp,
+                    };
+                    if log_tx.send(event).await.is_err() {
+                        break;
+                    }
+                }
+            });
+        }
+
+        // Bridge: forward user messages from TUI to the agent's MessageStream
+        let (incoming_tx, incoming_rx) = mpsc::channel::<IncomingMessage>(32);
+        let user_id = self.user_id.clone();
+        let sys_tz = crate::timezone::detect_system_timezone().name().to_string();
+        let detail_event_tx = event_tx.clone();
+
+        tokio::spawn(async move {
+            while let Some(user_msg) = msg_rx.recv().await {
+                if let Some(action) = user_msg.ui_action {
+                    match action {
+                        ironclaw_tui::TuiUiAction::OpenEngineThreadDetail { thread_id } => {
+                            match crate::bridge::get_engine_thread(&thread_id, &user_id).await {
+                                Ok(Some(detail)) => {
+                                    let _ = detail_event_tx
+                                        .send(build_engine_thread_detail_event(detail))
+                                        .await;
+                                }
+                                Ok(None) => {
+                                    let _ = detail_event_tx
+                                        .send(TuiEvent::Status(format!(
+                                            "Thread not found: {thread_id}"
+                                        )))
+                                        .await;
+                                }
+                                Err(err) => {
+                                    tracing::warn!(
+                                        thread_id = %thread_id,
+                                        error = %err,
+                                        "Failed to load engine thread detail for TUI"
+                                    );
+                                    let _ = detail_event_tx
+                                        .send(TuiEvent::Status(format!(
+                                            "Failed to load thread details: {err}"
+                                        )))
+                                        .await;
+                                }
+                            }
+                            continue;
+                        }
+                    }
+                }
+
+                let msg = build_tui_incoming_message(user_msg, &user_id, &sys_tz);
+                if incoming_tx.send(msg).await.is_err() {
+                    break;
+                }
+            }
+        });
+
+        Ok(Box::pin(ReceiverStream::new(incoming_rx)))
+    }
+
+    async fn respond(
+        &self,
+        _msg: &IncomingMessage,
+        response: OutgoingResponse,
+    ) -> Result<(), ChannelError> {
+        if let Some(ref tx) = *self.event_tx.lock().await {
+            let _ = tx
+                .send(TuiEvent::Response {
+                    content: response.content,
+                    thread_id: response.thread_id,
+                })
+                .await;
+        }
+        Ok(())
+    }
+
+    async fn send_status(
+        &self,
+        status: StatusUpdate,
+        _metadata: &serde_json::Value,
+    ) -> Result<(), ChannelError> {
+        let tx_guard = self.event_tx.lock().await;
+        let Some(ref tx) = *tx_guard else {
+            return Ok(());
+        };
+
+        let event = match status {
+            StatusUpdate::Thinking(msg) => TuiEvent::Thinking(msg),
+            StatusUpdate::ToolStarted {
+                name,
+                detail,
+                call_id,
+            } => TuiEvent::ToolStarted {
+                name,
+                detail,
+                call_id,
+            },
+            StatusUpdate::ToolCompleted {
+                name,
+                success,
+                error,
+                call_id,
+                ..
+            } => TuiEvent::ToolCompleted {
+                name,
+                success,
+                error,
+                call_id,
+            },
+            StatusUpdate::ToolResult {
+                name,
+                preview,
+                call_id,
+            } => TuiEvent::ToolResult {
+                name,
+                preview,
+                call_id,
+            },
+            StatusUpdate::StreamChunk(chunk) => TuiEvent::StreamChunk(chunk),
+            StatusUpdate::Status(msg) => TuiEvent::Status(msg),
+            StatusUpdate::JobStarted { job_id, title, .. } => {
+                TuiEvent::JobStarted { job_id, title }
+            }
+            StatusUpdate::JobStatus { job_id, status } => TuiEvent::JobStatus { job_id, status },
+            StatusUpdate::JobResult { job_id, status } => TuiEvent::JobResult { job_id, status },
+            StatusUpdate::RoutineUpdate {
+                id,
+                name,
+                trigger_type,
+                enabled,
+                last_run,
+                next_fire,
+            } => TuiEvent::RoutineUpdate {
+                id,
+                name,
+                trigger_type,
+                enabled,
+                last_run,
+                next_fire,
+            },
+            StatusUpdate::ApprovalNeeded {
+                request_id,
+                tool_name,
+                description,
+                parameters,
+                allow_always,
+            } => TuiEvent::ApprovalNeeded {
+                request_id,
+                tool_name,
+                description,
+                parameters,
+                allow_always,
+            },
+            StatusUpdate::AuthRequired {
+                extension_name,
+                instructions,
+                ..
+            } => TuiEvent::AuthRequired {
+                extension_name,
+                instructions,
+            },
+            StatusUpdate::AuthCompleted {
+                extension_name,
+                success,
+                message,
+            } => TuiEvent::AuthCompleted {
+                extension_name,
+                success,
+                message,
+            },
+            StatusUpdate::ReasoningUpdate {
+                narrative,
+                decisions: _,
+            } => TuiEvent::ReasoningUpdate { narrative },
+            StatusUpdate::TurnCost {
+                input_tokens,
+                output_tokens,
+                cost_usd,
+            } => TuiEvent::TurnCost {
+                input_tokens,
+                output_tokens,
+                cost_usd,
+            },
+            StatusUpdate::ContextPressure {
+                used_tokens,
+                max_tokens,
+                percentage,
+                warning,
+            } => TuiEvent::ContextPressure {
+                used_tokens,
+                max_tokens,
+                percentage,
+                warning,
+            },
+            StatusUpdate::SandboxStatus {
+                docker_available,
+                running_containers,
+                status,
+            } => TuiEvent::SandboxStatus {
+                docker_available,
+                running_containers,
+                status,
+            },
+            StatusUpdate::SecretsStatus {
+                count,
+                vault_unlocked,
+            } => TuiEvent::SecretsStatus {
+                count,
+                vault_unlocked,
+            },
+            StatusUpdate::CostGuard {
+                session_budget_usd,
+                spent_usd,
+                remaining_usd,
+                limit_reached,
+            } => TuiEvent::CostGuard {
+                session_budget_usd,
+                spent_usd,
+                remaining_usd,
+                limit_reached,
+            },
+            StatusUpdate::Suggestions { suggestions } => TuiEvent::Suggestions { suggestions },
+            StatusUpdate::ThreadList { threads } => TuiEvent::ThreadList {
+                threads: threads
+                    .into_iter()
+                    .map(|t| ironclaw_tui::ThreadEntry {
+                        id: t.id,
+                        title: t.title,
+                        message_count: t.message_count,
+                        last_activity: t.last_activity,
+                        channel: t.channel,
+                    })
+                    .collect(),
+            },
+            StatusUpdate::EngineThreadList { threads } => TuiEvent::EngineThreadList {
+                threads: threads
+                    .into_iter()
+                    .map(|t| ironclaw_tui::EngineThreadEntry {
+                        id: t.id,
+                        goal: t.goal,
+                        thread_type: t.thread_type,
+                        state: t.state,
+                        step_count: t.step_count,
+                        total_tokens: t.total_tokens,
+                        created_at: t.created_at,
+                        updated_at: t.updated_at,
+                    })
+                    .collect(),
+            },
+            StatusUpdate::ConversationHistory {
+                thread_id,
+                messages,
+                pending_approval,
+            } => TuiEvent::ConversationHistory {
+                thread_id,
+                messages: messages
+                    .into_iter()
+                    .map(|m| ironclaw_tui::HistoryMessage {
+                        role: m.role,
+                        content: m.content,
+                        timestamp: m.timestamp,
+                    })
+                    .collect(),
+                pending_approval: pending_approval.map(|approval| {
+                    ironclaw_tui::HistoryApprovalRequest {
+                        request_id: approval.request_id,
+                        tool_name: approval.tool_name,
+                        description: approval.description,
+                        parameters: approval.parameters,
+                        allow_always: approval.allow_always,
+                    }
+                }),
+            },
+            StatusUpdate::SkillActivated { .. } | StatusUpdate::ImageGenerated { .. } => {
+                return Ok(());
+            }
+        };
+
+        let _ = tx.send(event).await;
+        Ok(())
+    }
+
+    async fn broadcast(
+        &self,
+        _user_id: &str,
+        response: OutgoingResponse,
+    ) -> Result<(), ChannelError> {
+        if let Some(ref tx) = *self.event_tx.lock().await {
+            let _ = tx
+                .send(TuiEvent::Response {
+                    content: response.content,
+                    thread_id: response.thread_id,
+                })
+                .await;
+        }
+        Ok(())
+    }
+
+    async fn health_check(&self) -> Result<(), ChannelError> {
+        Ok(())
+    }
+
+    async fn shutdown(&self) -> Result<(), ChannelError> {
+        // The TUI thread will exit when event channels are dropped
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use ironclaw_tui::TuiUserMessage;
+
+    #[test]
+    fn resolve_tui_layout_merges_file_and_config() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let layout_dir = temp.path().join("tui");
+        std::fs::create_dir_all(&layout_dir).expect("layout dir");
+        std::fs::write(
+            layout_dir.join("layout.json"),
+            r#"{"theme":"light","sidebar":{"visible":false,"width_percent":33}}"#,
+        )
+        .expect("layout file");
+
+        let config = crate::config::TuiChannelConfig {
+            theme: "dark".to_string(),
+            sidebar_visible: true,
+        };
+
+        let layout = super::resolve_tui_layout(&config, temp.path());
+
+        assert_eq!(layout.theme, "dark");
+        assert!(layout.sidebar.visible);
+        assert_eq!(layout.sidebar.width_percent, 33);
+    }
+
+    #[test]
+    fn build_tui_incoming_message_preserves_thread_scope() {
+        let msg = super::build_tui_incoming_message(
+            TuiUserMessage::text_only("hello").with_thread_id(Some("thread-123".to_string())),
+            "user-1",
+            "Europe/Istanbul",
+        );
+
+        assert_eq!(msg.thread_id.as_deref(), Some("thread-123"));
+        assert_eq!(msg.channel, "tui");
+        assert_eq!(msg.user_id, "user-1");
+        assert_eq!(msg.content, "hello");
+        assert_eq!(msg.timezone.as_deref(), Some("Europe/Istanbul"));
+    }
+}
diff --git a/src/channels/wasm/wrapper.rs b/src/channels/wasm/wrapper.rs
index 86ff9105cb9..c7fb4061b2c 100644
--- a/src/channels/wasm/wrapper.rs
+++ b/src/channels/wasm/wrapper.rs
@@ -62,6 +62,9 @@ use crate::tools::wasm::{
 };
 use ironclaw_safety::LeakDetector;
 
+#[cfg(any(test, debug_assertions))]
+const TEST_HTTP_REWRITE_MAP_ENV: &str = "IRONCLAW_TEST_HTTP_REWRITE_MAP";
+
 const WEBSOCKET_EVENT_QUEUE_RELATIVE_PATH: &str = "state/gateway_event_queue";
 const WEBSOCKET_EVENT_PROCESSING_QUEUE_RELATIVE_PATH: &str = "state/gateway_event_queue_processing";
 const WEBSOCKET_EVENT_QUEUE_MAX_ITEMS: usize = 100;
@@ -383,13 +386,14 @@ impl near::agent::channel_host::Host for ChannelStoreData {
             self.inject_host_credentials(&host, &mut headers, &mut logical_url);
         }
 
-        let transport_url = rewrite_telegram_api_url_for_testing(&logical_url)
+        let transport_url = rewrite_http_url_for_testing(&logical_url)
+            .or_else(|| rewrite_telegram_api_url_for_testing(&logical_url))
             .unwrap_or_else(|| logical_url.clone());
         if transport_url != logical_url {
             tracing::info!(
                 logical_url = %logical_url,
                 transport_url = %transport_url,
-                "Rewriting Telegram API request to test base URL"
+                "Rewriting outbound HTTP request to test base URL"
             );
         }
 
@@ -404,7 +408,7 @@ impl near::agent::channel_host::Host for ChannelStoreData {
             .unwrap_or(10 * 1024 * 1024);
 
         // Resolve hostname and reject private/internal IPs to prevent DNS rebinding.
-        reject_private_ip(&url)?;
+        reject_private_ip(&transport_url)?;
 
         // Make the HTTP request using a dedicated single-threaded runtime.
         // We're inside spawn_blocking, so we can't rely on the main runtime's
@@ -3813,7 +3817,7 @@ fn status_to_wit(
             message: msg.clone(),
             metadata_json,
         },
-        StatusUpdate::ToolStarted { name } => wit_channel::StatusUpdate {
+        StatusUpdate::ToolStarted { name, .. } => wit_channel::StatusUpdate {
             status: wit_channel::StatusType::ToolStarted,
             message: format!("Tool started: {}", name),
             metadata_json,
@@ -3827,7 +3831,7 @@ fn status_to_wit(
             ),
             metadata_json,
         },
-        StatusUpdate::ToolResult { name, preview } => wit_channel::StatusUpdate {
+        StatusUpdate::ToolResult { name, preview, .. } => wit_channel::StatusUpdate {
             status: wit_channel::StatusType::ToolResult,
             message: format!(
                 "Tool result: {}\n{}",
@@ -3922,10 +3926,20 @@ fn status_to_wit(
             },
             metadata_json,
         },
-        // Suggestions, turn cost, and skill activation are web-gateway-only; skip for WASM channels
+        // Suggestions and richer UI/runtime telemetry are handled by the web/TUI surfaces.
         StatusUpdate::Suggestions { .. }
         | StatusUpdate::TurnCost { .. }
-        | StatusUpdate::SkillActivated { .. } => return None,
+        | StatusUpdate::SkillActivated { .. }
+        | StatusUpdate::JobStatus { .. }
+        | StatusUpdate::JobResult { .. }
+        | StatusUpdate::RoutineUpdate { .. }
+        | StatusUpdate::ContextPressure { .. }
+        | StatusUpdate::SandboxStatus { .. }
+        | StatusUpdate::SecretsStatus { .. }
+        | StatusUpdate::CostGuard { .. }
+        | StatusUpdate::ThreadList { .. }
+        | StatusUpdate::EngineThreadList { .. }
+        | StatusUpdate::ConversationHistory { .. } => return None,
         StatusUpdate::ReasoningUpdate {
             narrative,
             decisions,
@@ -4023,6 +4037,70 @@ fn extract_host_from_url(url: &str) -> Option<String> {
     })
 }
 
+/// Rewrite outbound HTTP URLs for testing.
+///
+/// `IRONCLAW_TEST_HTTP_REWRITE_MAP` is a JSON object mapping exact hostnames to
+/// replacement base URLs. For example:
+/// `{"slack.com":"http://127.0.0.1:8080","files.slack.com":"http://127.0.0.1:8080"}`
+///
+/// The replacement preserves the original path and query string so tests can
+/// point production hosts at local fakes without adding channel-specific code.
+#[cfg(any(test, debug_assertions))]
+fn rewrite_http_url_for_testing(url: &str) -> Option<String> {
+    let parsed = url::Url::parse(url).ok()?;
+    if !matches!(parsed.scheme(), "http" | "https") {
+        return None;
+    }
+
+    let host = parsed.host_str()?.to_lowercase();
+    let override_base = std::env::var(TEST_HTTP_REWRITE_MAP_ENV)
+        .ok()
+        .and_then(|value| parse_test_http_rewrite_map(&value).get(&host).cloned())?;
+
+    let path = parsed.path().trim_start_matches('/');
+    let mut rewritten = format!("{override_base}/{path}");
+    if let Some(query) = parsed.query() {
+        rewritten.push('?');
+        rewritten.push_str(query);
+    }
+    Some(rewritten)
+}
+
+#[cfg(not(any(test, debug_assertions)))]
+fn rewrite_http_url_for_testing(_url: &str) -> Option<String> {
+    None
+}
+
+#[cfg(any(test, debug_assertions))]
+fn parse_test_http_rewrite_map(raw: &str) -> HashMap<String, String> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return HashMap::new();
+    }
+
+    match serde_json::from_str::<HashMap<String, String>>(trimmed) {
+        Ok(map) => map
+            .into_iter()
+            .filter_map(|(host, base)| {
+                let host = host.trim().to_lowercase();
+                let base = base.trim().trim_end_matches('/').to_string();
+                if host.is_empty() || base.is_empty() {
+                    return None;
+                }
+                Some((host, base))
+            })
+            .collect(),
+        Err(error) => {
+            tracing::warn!(
+                env_var = TEST_HTTP_REWRITE_MAP_ENV,
+                %error,
+                "Ignoring invalid test HTTP rewrite map"
+            );
+            HashMap::new()
+        }
+    }
+}
+
 fn rewrite_telegram_api_url_for_testing(url: &str) -> Option<String> {
     let override_base = std::env::var(TELEGRAM_TEST_API_BASE_ENV)
         .ok()
@@ -4047,7 +4125,6 @@ fn rewrite_telegram_api_url_for_testing(url: &str) -> Option<String> {
     }
     Some(rewritten)
 }
-
 fn should_skip_response_leak_scan(url: &str) -> bool {
     url::Url::parse(url).is_ok_and(|parsed| {
         matches!(parsed.scheme(), "http" | "https")
@@ -4226,13 +4303,13 @@ mod tests {
         PreparedChannelModule, WasmChannelRuntime, WasmChannelRuntimeConfig,
     };
     use crate::channels::wasm::wrapper::{
-        EmitDispatchContext, HttpResponse, TELEGRAM_TEST_API_BASE_ENV, WasmChannel,
-        WebsocketRuntimeConfig, build_discord_gateway_presence_update,
+        EmitDispatchContext, HttpResponse, TELEGRAM_TEST_API_BASE_ENV, TEST_HTTP_REWRITE_MAP_ENV,
+        WasmChannel, WebsocketRuntimeConfig, build_discord_gateway_presence_update,
         build_websocket_identify_message, build_websocket_resume_message,
         discord_gateway_presence_status, drain_guest_logs, parse_websocket_invalid_session,
-        parse_websocket_ready_session, should_warn_on_heartbeat_interval,
-        uses_owner_broadcast_target, websocket_heartbeat_sleep_duration,
-        websocket_reconnect_backoff,
+        parse_websocket_ready_session, rewrite_http_url_for_testing,
+        should_warn_on_heartbeat_interval, uses_owner_broadcast_target,
+        websocket_heartbeat_sleep_duration, websocket_reconnect_backoff,
     };
     use crate::pairing::PairingStore;
     use crate::testing::credentials::TEST_TELEGRAM_BOT_TOKEN;
@@ -4896,6 +4973,8 @@ mod tests {
             .send_status(
                 crate::channels::StatusUpdate::ToolStarted {
                     name: "http_request".into(),
+                    detail: None,
+                    call_id: None,
                 },
                 &metadata,
             )
@@ -5211,6 +5290,8 @@ mod tests {
         let wit = status_to_wit(
             &crate::channels::StatusUpdate::ToolStarted {
                 name: "http_request".to_string(),
+                detail: None,
+                call_id: None,
             },
             &metadata,
         )
@@ -5234,6 +5315,7 @@ mod tests {
                 success: true,
                 error: None,
                 parameters: None,
+                call_id: None,
             },
             &metadata,
         )
@@ -5257,6 +5339,7 @@ mod tests {
                 success: false,
                 error: Some("connection refused".to_string()),
                 parameters: None,
+                call_id: None,
             },
             &metadata,
         )
@@ -5278,6 +5361,7 @@ mod tests {
             &crate::channels::StatusUpdate::ToolResult {
                 name: "http_request".to_string(),
                 preview: "{".to_string() + "\"temperature\": 22}",
+                call_id: None,
             },
             &metadata,
         )
@@ -5300,6 +5384,7 @@ mod tests {
             &crate::channels::StatusUpdate::ToolResult {
                 name: "big_tool".to_string(),
                 preview: long_preview,
+                call_id: None,
             },
             &metadata,
         )
@@ -6132,4 +6217,52 @@ mod tests {
             "image/png"
         );
     }
+
+    #[test]
+    fn test_rewrite_http_url_for_testing_uses_host_map() {
+        use std::sync::{Mutex, OnceLock};
+
+        static ENV_MUTEX: OnceLock<Mutex<()>> = OnceLock::new();
+        let _lock = ENV_MUTEX
+            .get_or_init(|| Mutex::new(()))
+            .lock()
+            .expect("env mutex poisoned");
+
+        let original = std::env::var(TEST_HTTP_REWRITE_MAP_ENV).ok();
+
+        // SAFETY: guarded by ENV_MUTEX — no concurrent env access.
+        unsafe {
+            std::env::set_var(
+                TEST_HTTP_REWRITE_MAP_ENV,
+                r#"{"slack.com":"http://localhost:9999","files.slack.com":"http://localhost:9999"}"#,
+            );
+        }
+
+        // slack.com API call
+        let result = rewrite_http_url_for_testing("https://slack.com/api/chat.postMessage");
+        assert_eq!(
+            result.as_deref(),
+            Some("http://localhost:9999/api/chat.postMessage")
+        );
+        // files.slack.com file download
+        let result = rewrite_http_url_for_testing(
+            "https://files.slack.com/files-pri/T123/download/test.txt",
+        );
+        assert_eq!(
+            result.as_deref(),
+            Some("http://localhost:9999/files-pri/T123/download/test.txt")
+        );
+        // Non-Slack URL should not be rewritten
+        let result = rewrite_http_url_for_testing("https://api.telegram.org/bot123/getMe");
+        assert!(result.is_none());
+
+        // SAFETY: guarded by ENV_MUTEX — restore original state.
+        unsafe {
+            if let Some(ref val) = original {
+                std::env::set_var(TEST_HTTP_REWRITE_MAP_ENV, val);
+            } else {
+                std::env::remove_var(TEST_HTTP_REWRITE_MAP_ENV);
+            }
+        }
+    }
 }
diff --git a/src/channels/web/handlers/llm.rs b/src/channels/web/handlers/llm.rs
index 8d4e54a48c5..5fe09335799 100644
--- a/src/channels/web/handlers/llm.rs
+++ b/src/channels/web/handlers/llm.rs
@@ -4,9 +4,9 @@ use std::sync::Arc;
 
 use axum::{Json, extract::State};
 
-use crate::channels::web::auth::AuthenticatedUser;
+use crate::channels::web::auth::{AdminUser, AuthenticatedUser};
 use crate::channels::web::server::GatewayState;
-use crate::config::helpers::validate_base_url;
+use crate::config::helpers::validate_operator_base_url;
 
 // ---------------------------------------------------------------------------
 // Test connection
@@ -41,7 +41,7 @@ pub struct TestConnectionResponse {
 
 pub async fn llm_test_connection_handler(
     State(state): State<Arc<GatewayState>>,
-    AuthenticatedUser(user): AuthenticatedUser,
+    AdminUser(user): AdminUser,
     Json(mut body): Json<TestConnectionRequest>,
 ) -> Json<TestConnectionResponse> {
     resolve_api_key_from_secrets(
@@ -56,7 +56,7 @@ pub async fn llm_test_connection_handler(
 }
 
 async fn test_provider_connection(req: TestConnectionRequest) -> TestConnectionResponse {
-    if let Err(e) = validate_base_url(&req.base_url, "base_url") {
+    if let Err(e) = validate_operator_base_url(&req.base_url, "base_url") {
         return TestConnectionResponse {
             ok: false,
             message: format!("Invalid base URL: {e}"),
@@ -219,7 +219,7 @@ pub struct ListModelsResponse {
 
 pub async fn llm_list_models_handler(
     State(state): State<Arc<GatewayState>>,
-    AuthenticatedUser(user): AuthenticatedUser,
+    AdminUser(user): AdminUser,
     Json(mut body): Json<ListModelsRequest>,
 ) -> Json<ListModelsResponse> {
     resolve_api_key_from_secrets(
@@ -234,7 +234,7 @@ pub async fn llm_list_models_handler(
 }
 
 async fn fetch_provider_models(req: ListModelsRequest) -> ListModelsResponse {
-    if let Err(e) = validate_base_url(&req.base_url, "base_url") {
+    if let Err(e) = validate_operator_base_url(&req.base_url, "base_url") {
         return ListModelsResponse {
             ok: false,
             models: vec![],
diff --git a/src/channels/web/handlers/mod.rs b/src/channels/web/handlers/mod.rs
index 0b8da0fcd1b..91c50945809 100644
--- a/src/channels/web/handlers/mod.rs
+++ b/src/channels/web/handlers/mod.rs
@@ -10,6 +10,7 @@ pub mod memory;
 pub mod routines;
 pub mod secrets;
 pub mod skills;
+pub mod system_prompt;
 pub mod tokens;
 pub mod users;
 
diff --git a/src/channels/web/handlers/settings.rs b/src/channels/web/handlers/settings.rs
index 031e35cf99d..864f4de1b74 100644
--- a/src/channels/web/handlers/settings.rs
+++ b/src/channels/web/handlers/settings.rs
@@ -108,6 +108,8 @@ pub async fn settings_set_handler(
     Path(key): Path<String>,
     Json(body): Json<SettingWriteRequest>,
 ) -> Result<StatusCode, StatusCode> {
+    ensure_setting_write_allowed(&user, &key)?;
+
     let store = state
         .store
         .as_ref()
@@ -240,6 +242,8 @@ pub async fn settings_delete_handler(
     AuthenticatedUser(user): AuthenticatedUser,
     Path(key): Path<String>,
 ) -> Result<StatusCode, StatusCode> {
+    ensure_setting_write_allowed(&user, &key)?;
+
     let store = state
         .store
         .as_ref()
@@ -289,6 +293,8 @@ pub async fn settings_import_handler(
     AuthenticatedUser(user): AuthenticatedUser,
     Json(body): Json<SettingsImportRequest>,
 ) -> Result<StatusCode, StatusCode> {
+    ensure_settings_import_allowed(&user, &body.settings)?;
+
     let store = state
         .store
         .as_ref()
@@ -317,6 +323,50 @@ pub async fn settings_import_handler(
     Ok(StatusCode::NO_CONTENT)
 }
 
+fn is_admin_only_setting_key(key: &str) -> bool {
+    // Single source of truth lives in `crate::config::helpers` so the
+    // write-side gate here cannot drift from the read-side strip filter.
+    crate::config::helpers::ADMIN_ONLY_LLM_SETTING_KEYS.contains(&key)
+}
+
+fn ensure_setting_write_allowed(
+    user: &crate::channels::web::auth::UserIdentity,
+    key: &str,
+) -> Result<(), StatusCode> {
+    if is_admin_only_setting_key(key) && user.role != "admin" {
+        tracing::warn!(
+            user_id = %user.user_id,
+            role = %user.role,
+            key = %key,
+            "Rejected non-admin write to admin-only setting"
+        );
+        return Err(StatusCode::FORBIDDEN);
+    }
+
+    Ok(())
+}
+
+fn ensure_settings_import_allowed(
+    user: &crate::channels::web::auth::UserIdentity,
+    settings: &std::collections::HashMap<String, serde_json::Value>,
+) -> Result<(), StatusCode> {
+    if user.role == "admin" {
+        return Ok(());
+    }
+
+    if let Some(key) = settings.keys().find(|key| is_admin_only_setting_key(key)) {
+        tracing::warn!(
+            user_id = %user.user_id,
+            role = %user.role,
+            key = %key,
+            "Rejected non-admin import containing admin-only setting"
+        );
+        return Err(StatusCode::FORBIDDEN);
+    }
+
+    Ok(())
+}
+
 // ---------------------------------------------------------------------------
 // LLM API key vaulting helpers
 // ---------------------------------------------------------------------------
@@ -767,6 +817,15 @@ async fn annotate_secret_key_presence(
 mod tests {
     use super::*;
     use std::collections::HashMap;
+    use std::sync::Arc;
+
+    use axum::{
+        Json,
+        extract::{Path, State},
+        http::StatusCode,
+    };
+
+    use crate::channels::web::auth::UserIdentity;
 
     #[test]
     fn test_mask_settings_api_keys_builtin_overrides() {
@@ -881,6 +940,15 @@ mod tests {
         }
     }
 
+    async fn test_gateway_state_with_store(
+        secrets: Arc<dyn SecretsStore + Send + Sync>,
+    ) -> (Arc<GatewayState>, tempfile::TempDir) {
+        let (db, tmp) = crate::testing::test_db().await;
+        let mut state = test_gateway_state(secrets);
+        state.store = Some(db);
+        (Arc::new(state), tmp)
+    }
+
     #[tokio::test]
     async fn test_extract_builtin_keys_vaults_and_strips() {
         let secrets = test_secrets_store();
@@ -1124,6 +1192,83 @@ mod tests {
         assert!(validate_custom_providers(&input).is_ok());
     }
 
+    #[test]
+    fn test_admin_only_setting_keys_include_network_destinations() {
+        assert!(is_admin_only_setting_key("llm_builtin_overrides"));
+        assert!(is_admin_only_setting_key("llm_custom_providers"));
+        assert!(is_admin_only_setting_key("ollama_base_url"));
+        assert!(is_admin_only_setting_key("openai_compatible_base_url"));
+        assert!(!is_admin_only_setting_key("selected_model"));
+    }
+
+    #[tokio::test]
+    async fn test_settings_set_rejects_member_for_admin_only_key() {
+        let secrets = test_secrets_store();
+        let (state, _tmp) = test_gateway_state_with_store(secrets).await;
+
+        let status = settings_set_handler(
+            State(state),
+            AuthenticatedUser(UserIdentity {
+                user_id: "member".to_string(),
+                role: "member".to_string(),
+                workspace_read_scopes: Vec::new(),
+            }),
+            Path("ollama_base_url".to_string()),
+            Json(SettingWriteRequest {
+                value: serde_json::json!("http://192.168.1.50:11434"),
+            }),
+        )
+        .await
+        .unwrap_err();
+
+        assert_eq!(status, StatusCode::FORBIDDEN);
+    }
+
+    #[tokio::test]
+    async fn test_settings_delete_rejects_member_for_admin_only_key() {
+        let secrets = test_secrets_store();
+        let (state, _tmp) = test_gateway_state_with_store(secrets).await;
+
+        let status = settings_delete_handler(
+            State(state),
+            AuthenticatedUser(UserIdentity {
+                user_id: "member".to_string(),
+                role: "member".to_string(),
+                workspace_read_scopes: Vec::new(),
+            }),
+            Path("llm_custom_providers".to_string()),
+        )
+        .await
+        .unwrap_err();
+
+        assert_eq!(status, StatusCode::FORBIDDEN);
+    }
+
+    #[tokio::test]
+    async fn test_settings_import_rejects_member_for_admin_only_keys() {
+        let secrets = test_secrets_store();
+        let (state, _tmp) = test_gateway_state_with_store(secrets).await;
+        let mut settings = HashMap::new();
+        settings.insert(
+            "openai_compatible_base_url".to_string(),
+            serde_json::json!("https://192.168.1.60/v1"),
+        );
+
+        let status = settings_import_handler(
+            State(state),
+            AuthenticatedUser(UserIdentity {
+                user_id: "member".to_string(),
+                role: "member".to_string(),
+                workspace_read_scopes: Vec::new(),
+            }),
+            Json(SettingsImportRequest { settings }),
+        )
+        .await
+        .unwrap_err();
+
+        assert_eq!(status, StatusCode::FORBIDDEN);
+    }
+
     // --- Tool permissions helpers ---
 
     #[test]
diff --git a/src/channels/web/handlers/skills.rs b/src/channels/web/handlers/skills.rs
index 17f79dba701..db62fac42de 100644
--- a/src/channels/web/handlers/skills.rs
+++ b/src/channels/web/handlers/skills.rs
@@ -12,6 +12,17 @@ use crate::channels::web::auth::AuthenticatedUser;
 use crate::channels::web::server::GatewayState;
 use crate::channels::web::types::*;
 
+fn install_requested_identifier<'a>(
+    name: &'a str,
+    explicit_slug: Option<&'a str>,
+    resolved_download_key: Option<&'a str>,
+) -> &'a str {
+    explicit_slug
+        .filter(|s| !s.is_empty())
+        .or(resolved_download_key.filter(|s| !s.is_empty()))
+        .unwrap_or(name)
+}
+
 pub async fn skills_list_handler(
     State(state): State<Arc<GatewayState>>,
     AuthenticatedUser(_user): AuthenticatedUser,
@@ -68,33 +79,20 @@ pub async fn skills_search_handler(
     let mut entries = catalog_outcome.results;
     catalog.enrich_search_results(&mut entries, 5).await;
 
-    let catalog_json: Vec<serde_json::Value> = entries
-        .into_iter()
-        .map(|e| {
-            serde_json::json!({
-                "slug": e.slug,
-                "name": e.name,
-                "description": e.description,
-                "version": e.version,
-                "score": e.score,
-                "updatedAt": e.updated_at,
-                "stars": e.stars,
-                "downloads": e.downloads,
-                "owner": e.owner,
-            })
-        })
-        .collect();
-
-    // Search local skills
     let query_lower = req.query.to_lowercase();
-    let installed: Vec<SkillInfo> = {
+    let (installed_names, installed): (Vec<String>, Vec<SkillInfo>) = {
         let guard = registry.read().map_err(|e| {
             (
                 StatusCode::INTERNAL_SERVER_ERROR,
                 format!("Skill registry lock poisoned: {}", e),
             )
         })?;
-        guard
+        let installed_names: Vec<String> = guard
+            .skills()
+            .iter()
+            .map(|s| s.manifest.name.clone())
+            .collect();
+        let installed = guard
             .skills()
             .iter()
             .filter(|s| {
@@ -109,9 +107,33 @@ pub async fn skills_search_handler(
                 source: format!("{:?}", s.source),
                 keywords: s.manifest.activation.keywords.clone(),
             })
-            .collect()
+            .collect();
+        (installed_names, installed)
     };
 
+    let catalog_json: Vec<serde_json::Value> = entries
+        .into_iter()
+        .map(|e| {
+            let is_installed = ironclaw_skills::catalog::catalog_entry_is_installed(
+                &e.slug,
+                &e.name,
+                &installed_names,
+            );
+            serde_json::json!({
+                "slug": e.slug,
+                "name": e.name,
+                "description": e.description,
+                "version": e.version,
+                "score": e.score,
+                "updatedAt": e.updated_at,
+                "stars": e.stars,
+                "downloads": e.downloads,
+                "owner": e.owner,
+                "installed": is_installed,
+            })
+        })
+        .collect();
+
     Ok(Json(SkillSearchResponse {
         catalog: catalog_json,
         installed,
@@ -146,6 +168,7 @@ pub async fn skills_install_handler(
         "Skills system not enabled".to_string(),
     ))?;
 
+    let mut resolved_download_key = None;
     let content = if let Some(ref raw) = req.content {
         raw.clone()
     } else if let Some(ref url) = req.url {
@@ -154,15 +177,35 @@ pub async fn skills_install_handler(
             .await
             .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?
     } else if let Some(ref catalog) = state.skill_catalog {
-        // Prefer slug (e.g. "owner/skill-name") over display name for the
-        // download URL, since the registry endpoint expects a slug.
-        let download_key = req
-            .slug
-            .as_deref()
-            .filter(|s| !s.is_empty())
-            .unwrap_or(&req.name);
+        let download_key = if let Some(slug) = req.slug.as_deref().filter(|s| !s.is_empty()) {
+            slug.to_string()
+        } else if req.name.contains('/') {
+            req.name.clone()
+        } else {
+            let outcome = catalog.search(&req.name).await;
+            match ironclaw_skills::catalog::resolve_catalog_slug_for_name(
+                &req.name,
+                &outcome.results,
+            ) {
+                Ok(Some(resolved)) => resolved,
+                Ok(None) => {
+                    let reason = outcome
+                        .error
+                        .unwrap_or_else(|| "no unique catalog match was found".to_string());
+                    return Err((
+                        StatusCode::BAD_REQUEST,
+                        format!(
+                            "Could not resolve skill name '{}' to a catalog slug: {}",
+                            req.name, reason
+                        ),
+                    ));
+                }
+                Err(e) => return Err((StatusCode::BAD_REQUEST, e.to_string())),
+            }
+        };
         let url =
-            ironclaw_skills::catalog::skill_download_url(catalog.registry_url(), download_key);
+            ironclaw_skills::catalog::skill_download_url(catalog.registry_url(), &download_key);
+        resolved_download_key = Some(download_key);
         crate::tools::builtin::skill_tools::fetch_skill_content(&url)
             .await
             .map_err(|e| (StatusCode::BAD_GATEWAY, e.to_string()))?
@@ -172,8 +215,15 @@ pub async fn skills_install_handler(
         )));
     };
 
+    let normalized = ironclaw_skills::normalize_line_endings(&content);
+    let requested_identifier = install_requested_identifier(
+        &req.name,
+        req.slug.as_deref(),
+        resolved_download_key.as_deref(),
+    );
+
     // Parse, check duplicates, and get install_dir under a brief read lock.
-    let (user_dir, skill_name_from_parse) = {
+    let (user_dir, skill_name_from_parse, install_content) = {
         let guard = registry.read().map_err(|e| {
             (
                 StatusCode::INTERNAL_SERVER_ERROR,
@@ -181,10 +231,12 @@ pub async fn skills_install_handler(
             )
         })?;
 
-        let normalized = ironclaw_skills::normalize_line_endings(&content);
-        let parsed = ironclaw_skills::parser::parse_skill_md(&normalized)
+        let (skill_name, install_content) =
+            ironclaw_skills::registry::SkillRegistry::resolve_install_content(
+                &normalized,
+                Some(requested_identifier),
+            )
             .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?;
-        let skill_name = parsed.manifest.name.clone();
 
         if guard.has(&skill_name) {
             return Ok(Json(ActionResponse::fail(format!(
@@ -193,16 +245,19 @@ pub async fn skills_install_handler(
             ))));
         }
 
-        (guard.install_target_dir().to_path_buf(), skill_name)
+        (
+            guard.install_target_dir().to_path_buf(),
+            skill_name,
+            install_content,
+        )
     };
 
     // Perform async I/O (write to disk, load) with no lock held.
-    let normalized = ironclaw_skills::normalize_line_endings(&content);
     let (skill_name, loaded_skill) =
         ironclaw_skills::registry::SkillRegistry::prepare_install_to_disk(
             &user_dir,
             &skill_name_from_parse,
-            &normalized,
+            &install_content,
         )
         .await
         .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
@@ -283,3 +338,62 @@ pub async fn skills_remove_handler(
         Err(e) => Ok(Json(ActionResponse::fail(e.to_string()))),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn catalog_entry_matches_installed_slug_suffix() {
+        let installed = vec!["mortgage-calculator".to_string()];
+
+        assert!(ironclaw_skills::catalog::catalog_entry_is_installed(
+            "finance/mortgage-calculator",
+            "Mortgage Calculator",
+            &installed,
+        ));
+    }
+
+    #[test]
+    fn catalog_entry_matches_installed_display_name() {
+        let installed = vec!["Mortgage Calculator".to_string()];
+
+        assert!(ironclaw_skills::catalog::catalog_entry_is_installed(
+            "finance/mortgage-calculator",
+            "Mortgage Calculator",
+            &installed,
+        ));
+    }
+
+    #[test]
+    fn catalog_entry_does_not_match_unrelated_installed_skill() {
+        let installed = vec!["budget-planner".to_string()];
+
+        assert!(!ironclaw_skills::catalog::catalog_entry_is_installed(
+            "finance/mortgage-calculator",
+            "Mortgage Calculator",
+            &installed,
+        ));
+    }
+
+    #[test]
+    fn catalog_entry_matches_owner_aware_normalized_install_name() {
+        let installed = vec!["finance-mortgage-calculator".to_string()];
+
+        assert!(ironclaw_skills::catalog::catalog_entry_is_installed(
+            "finance/mortgage-calculator",
+            "Mortgage Calculator",
+            &installed,
+        ));
+    }
+
+    #[test]
+    fn install_requested_identifier_prefers_resolved_slug_for_manual_name_installs() {
+        assert_eq!(
+            super::install_requested_identifier(
+                "Mortgage Calculator",
+                None,
+                Some("finance/mortgage-calculator"),
+            ),
+            "finance/mortgage-calculator"
+        );
+    }
+}
diff --git a/src/channels/web/handlers/system_prompt.rs b/src/channels/web/handlers/system_prompt.rs
new file mode 100644
index 00000000000..b530af01c06
--- /dev/null
+++ b/src/channels/web/handlers/system_prompt.rs
@@ -0,0 +1,103 @@
+//! Admin system prompt management handlers.
+//!
+//! These endpoints allow admins to set a shared system prompt (`SYSTEM.md`)
+//! that is injected into every user's system prompt in multi-tenant mode.
+
+use std::sync::Arc;
+
+use axum::{Json, extract::State, http::StatusCode};
+
+use crate::channels::web::auth::AdminUser;
+use crate::channels::web::server::GatewayState;
+use crate::channels::web::types::{SystemPromptRequest, SystemPromptResponse};
+use crate::workspace::{ADMIN_SCOPE, Workspace, paths};
+
+/// `GET /api/admin/system-prompt` — read the admin system prompt.
+pub async fn get_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_admin): AdminUser,
+) -> Result<Json<SystemPromptResponse>, (StatusCode, String)> {
+    // Gate behind multi-tenant mode.
+    if state.workspace_pool.is_none() {
+        return Err((
+            StatusCode::NOT_FOUND,
+            "System prompt management requires multi-tenant mode".to_string(),
+        ));
+    }
+
+    let db = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let ws = Workspace::new_with_db(ADMIN_SCOPE, Arc::clone(db));
+
+    match ws.read(paths::SYSTEM).await {
+        Ok(doc) => Ok(Json(SystemPromptResponse {
+            content: doc.content,
+            updated_at: Some(doc.updated_at.to_rfc3339()),
+        })),
+        Err(crate::error::WorkspaceError::DocumentNotFound { .. }) => {
+            Ok(Json(SystemPromptResponse {
+                content: String::new(),
+                updated_at: None,
+            }))
+        }
+        Err(e) => Err((StatusCode::INTERNAL_SERVER_ERROR, e.to_string())),
+    }
+}
+
+/// Maximum size for an admin system prompt (64 KB).
+const MAX_SYSTEM_PROMPT_SIZE: usize = 64 * 1024;
+
+/// `PUT /api/admin/system-prompt` — set the admin system prompt.
+pub async fn put_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_admin): AdminUser,
+    Json(req): Json<SystemPromptRequest>,
+) -> Result<Json<SystemPromptResponse>, (StatusCode, String)> {
+    // Enforce size limit — this content is injected into every user's system
+    // prompt, so an unbounded size could exhaust token budgets. The route also
+    // applies a `DefaultBodyLimit` layer that rejects oversized payloads
+    // before they are parsed; this in-handler check is a clearer-error fallback.
+    if req.content.len() > MAX_SYSTEM_PROMPT_SIZE {
+        return Err((
+            StatusCode::PAYLOAD_TOO_LARGE,
+            "System prompt exceeds 64 KB limit".to_string(),
+        ));
+    }
+
+    // Gate behind multi-tenant mode.
+    if state.workspace_pool.is_none() {
+        return Err((
+            StatusCode::NOT_FOUND,
+            "System prompt management requires multi-tenant mode".to_string(),
+        ));
+    }
+
+    let db = state.store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Database not available".to_string(),
+    ))?;
+
+    let ws = Workspace::new_with_db(ADMIN_SCOPE, Arc::clone(db));
+
+    let doc = ws.write(paths::SYSTEM, &req.content).await.map_err(|e| {
+        let status = if matches!(e, crate::error::WorkspaceError::InjectionRejected { .. }) {
+            StatusCode::BAD_REQUEST
+        } else {
+            StatusCode::INTERNAL_SERVER_ERROR
+        };
+        (status, e.to_string())
+    })?;
+
+    // Invalidate the cached admin prompt so all workspaces see the update.
+    if let Some(ref pool) = state.workspace_pool {
+        pool.invalidate_admin_prompt().await;
+    }
+
+    Ok(Json(SystemPromptResponse {
+        content: doc.content,
+        updated_at: Some(doc.updated_at.to_rfc3339()),
+    }))
+}
diff --git a/src/channels/web/log_layer.rs b/src/channels/web/log_layer.rs
index ada8d19c257..2cdad7220d5 100644
--- a/src/channels/web/log_layer.rs
+++ b/src/channels/web/log_layer.rs
@@ -174,7 +174,14 @@ impl LogLevelHandle {
 ///
 /// Returns the `LogLevelHandle` so callers can swap the filter at runtime.
 /// The fmt layer and `WebLogLayer` are attached alongside the reloadable filter.
-pub fn init_tracing(log_broadcaster: Arc<LogBroadcaster>) -> Arc<LogLevelHandle> {
+///
+/// When `suppress_stderr` is true, the stderr formatter is omitted. This is
+/// used in TUI mode where logs are displayed in the dedicated Logs tab instead
+/// of interleaving with the alternate screen.
+pub fn init_tracing(
+    log_broadcaster: Arc<LogBroadcaster>,
+    suppress_stderr: bool,
+) -> Arc<LogLevelHandle> {
     let raw_filter =
         std::env::var("RUST_LOG").unwrap_or_else(|_| "ironclaw=info,tower_http=warn".to_string());
 
@@ -203,13 +210,19 @@ pub fn init_tracing(log_broadcaster: Arc<LogBroadcaster>) -> Arc<LogLevelHandle>
         base_filter,
     ));
 
-    tracing_subscriber::registry()
-        .with(reload_layer)
-        .with(
+    let fmt_layer = if suppress_stderr {
+        None
+    } else {
+        Some(
             tracing_subscriber::fmt::layer()
                 .with_target(false)
                 .with_writer(crate::tracing_fmt::TruncatingStderr::default()),
         )
+    };
+
+    tracing_subscriber::registry()
+        .with(reload_layer)
+        .with(fmt_layer)
         .with(WebLogLayer::new(log_broadcaster))
         .init();
 
diff --git a/src/channels/web/mod.rs b/src/channels/web/mod.rs
index eea2e9216b1..177e27e9ca2 100644
--- a/src/channels/web/mod.rs
+++ b/src/channels/web/mod.rs
@@ -557,8 +557,9 @@ impl Channel for GatewayChannel {
                 message: msg,
                 thread_id: thread_id.clone(),
             },
-            StatusUpdate::ToolStarted { name } => AppEvent::ToolStarted {
+            StatusUpdate::ToolStarted { name, detail, .. } => AppEvent::ToolStarted {
                 name,
+                detail,
                 thread_id: thread_id.clone(),
             },
             StatusUpdate::ToolCompleted {
@@ -566,6 +567,7 @@ impl Channel for GatewayChannel {
                 success,
                 error,
                 parameters,
+                ..
             } => AppEvent::ToolCompleted {
                 name,
                 success,
@@ -573,7 +575,7 @@ impl Channel for GatewayChannel {
                 parameters,
                 thread_id: thread_id.clone(),
             },
-            StatusUpdate::ToolResult { name, preview } => AppEvent::ToolResult {
+            StatusUpdate::ToolResult { name, preview, .. } => AppEvent::ToolResult {
                 name,
                 preview,
                 thread_id: thread_id.clone(),
@@ -665,10 +667,30 @@ impl Channel for GatewayChannel {
                 cost_usd,
                 thread_id,
             },
+            StatusUpdate::JobStatus { job_id, status } => AppEvent::JobStatus {
+                job_id,
+                message: status,
+            },
+            StatusUpdate::JobResult { job_id, status } => AppEvent::JobResult {
+                job_id,
+                status,
+                session_id: None,
+                fallback_deliverable: None,
+            },
             StatusUpdate::SkillActivated { skill_names } => AppEvent::SkillActivated {
                 skill_names,
                 thread_id,
             },
+            StatusUpdate::RoutineUpdate { .. }
+            | StatusUpdate::ContextPressure { .. }
+            | StatusUpdate::SandboxStatus { .. }
+            | StatusUpdate::SecretsStatus { .. }
+            | StatusUpdate::CostGuard { .. }
+            | StatusUpdate::ThreadList { .. }
+            | StatusUpdate::EngineThreadList { .. }
+            | StatusUpdate::ConversationHistory { .. } => {
+                return Ok(());
+            }
         };
 
         // Scope events to the user when user_id is available in metadata.
diff --git a/src/channels/web/responses_api.rs b/src/channels/web/responses_api.rs
index ec190869bca..8c6c2bd5a7d 100644
--- a/src/channels/web/responses_api.rs
+++ b/src/channels/web/responses_api.rs
@@ -1361,6 +1361,7 @@ mod tests {
         let mut acc = ResponseAccumulator::new("resp_test".to_string(), "m".to_string());
         assert!(!acc.process(AppEvent::ToolStarted {
             name: "memory_search".to_string(),
+            detail: None,
             thread_id: Some("t".to_string()),
         }));
         assert!(!acc.process(AppEvent::ToolResult {
diff --git a/src/channels/web/server.rs b/src/channels/web/server.rs
index ceca177e319..252b6bbaf7b 100644
--- a/src/channels/web/server.rs
+++ b/src/channels/web/server.rs
@@ -255,6 +255,9 @@ pub struct WorkspacePool {
     search_config: crate::config::WorkspaceSearchConfig,
     workspace_config: crate::config::WorkspaceConfig,
     cache: tokio::sync::RwLock<std::collections::HashMap<String, Arc<Workspace>>>,
+    /// Cached admin system prompt content. `None` = not yet loaded;
+    /// `Some("")` = loaded but empty/not set.
+    admin_prompt_cache: Arc<tokio::sync::RwLock<Option<String>>>,
 }
 
 impl WorkspacePool {
@@ -272,14 +275,24 @@ impl WorkspacePool {
             search_config,
             workspace_config,
             cache: tokio::sync::RwLock::new(std::collections::HashMap::new()),
+            admin_prompt_cache: Arc::new(tokio::sync::RwLock::new(None)),
         }
     }
 
+    /// Clear the admin prompt cache. Called after the PUT handler updates
+    /// the prompt so all workspaces see the new content on the next turn.
+    pub async fn invalidate_admin_prompt(&self) {
+        let mut guard = self.admin_prompt_cache.write().await;
+        *guard = None;
+    }
+
     /// Build a workspace for a user, applying search config, embeddings,
-    /// global read scopes, and memory layers.
+    /// global read scopes, memory layers, and admin prompt.
     fn build_workspace(&self, user_id: &str) -> Workspace {
         let mut ws = Workspace::new_with_db(user_id, Arc::clone(&self.db))
-            .with_search_config(&self.search_config);
+            .with_search_config(&self.search_config)
+            .with_admin_prompt()
+            .with_admin_prompt_cache(Arc::clone(&self.admin_prompt_cache));
 
         if let Some(ref emb) = self.embeddings {
             ws = ws.with_embeddings_cached(Arc::clone(emb), self.embedding_cache_config.clone());
@@ -708,6 +721,14 @@ pub async fn start_server(
             put(super::handlers::secrets::secrets_put_handler)
                 .delete(super::handlers::secrets::secrets_delete_handler),
         )
+        // Admin system prompt — tighter body cap than the global 10 MB so an
+        // oversized payload is rejected before being parsed into memory.
+        .route(
+            "/api/admin/system-prompt",
+            get(super::handlers::system_prompt::get_handler)
+                .put(super::handlers::system_prompt::put_handler)
+                .layer(DefaultBodyLimit::max(128 * 1024)),
+        )
         // Usage reporting (admin)
         .route(
             "/api/admin/usage",
@@ -4045,7 +4066,7 @@ mod tests {
         let secrets = test_secrets_store();
         let (ext_mgr, _wasm_tools_dir, wasm_channels_dir) = test_ext_mgr(secrets);
 
-        let channel_name = "test-failing-channel";
+        let channel_name = "test_failing_channel";
         std::fs::write(
             wasm_channels_dir
                 .path()
@@ -4118,6 +4139,121 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn test_llm_test_connection_allows_admin_private_base_url() {
+        use axum::body::Body;
+        use tower::ServiceExt;
+
+        let state = test_gateway_state(None);
+        let app = Router::new()
+            .route(
+                "/api/llm/test_connection",
+                post(llm_test_connection_handler),
+            )
+            .with_state(state);
+
+        let req_body = serde_json::json!({
+            "adapter": "openai",
+            "base_url": "http://127.0.0.1:9/v1",
+            "model": "test-model"
+        });
+        let mut req = axum::http::Request::builder()
+            .method("POST")
+            .uri("/api/llm/test_connection")
+            .header("content-type", "application/json")
+            .body(Body::from(req_body.to_string()))
+            .expect("request");
+        req.extensions_mut().insert(UserIdentity {
+            user_id: "test".to_string(),
+            role: "admin".to_string(),
+            workspace_read_scopes: Vec::new(),
+        });
+
+        let resp = ServiceExt::<axum::http::Request<Body>>::oneshot(app, req)
+            .await
+            .expect("response");
+        assert_eq!(resp.status(), StatusCode::OK);
+
+        let body = axum::body::to_bytes(resp.into_body(), 1024 * 64)
+            .await
+            .expect("body");
+        let parsed: serde_json::Value = serde_json::from_slice(&body).expect("json response");
+        assert_eq!(parsed["ok"], serde_json::Value::Bool(false));
+        let message = parsed["message"].as_str().unwrap_or_default();
+        assert!(
+            !message.contains("Invalid base URL"),
+            "private localhost endpoint should pass validation: {message}"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_llm_test_connection_requires_admin_role() {
+        use axum::body::Body;
+        use tower::ServiceExt;
+
+        let state = test_gateway_state(None);
+        let app = Router::new()
+            .route(
+                "/api/llm/test_connection",
+                post(llm_test_connection_handler),
+            )
+            .with_state(state);
+
+        let req_body = serde_json::json!({
+            "adapter": "openai",
+            "base_url": "http://127.0.0.1:9/v1",
+            "model": "test-model"
+        });
+        let mut req = axum::http::Request::builder()
+            .method("POST")
+            .uri("/api/llm/test_connection")
+            .header("content-type", "application/json")
+            .body(Body::from(req_body.to_string()))
+            .expect("request");
+        req.extensions_mut().insert(UserIdentity {
+            user_id: "member".to_string(),
+            role: "member".to_string(),
+            workspace_read_scopes: Vec::new(),
+        });
+
+        let resp = ServiceExt::<axum::http::Request<Body>>::oneshot(app, req)
+            .await
+            .expect("response");
+        assert_eq!(resp.status(), StatusCode::FORBIDDEN);
+    }
+
+    #[tokio::test]
+    async fn test_llm_list_models_requires_admin_role() {
+        use axum::body::Body;
+        use tower::ServiceExt;
+
+        let state = test_gateway_state(None);
+        let app = Router::new()
+            .route("/api/llm/list_models", post(llm_list_models_handler))
+            .with_state(state);
+
+        let req_body = serde_json::json!({
+            "adapter": "openai",
+            "base_url": "http://127.0.0.1:9/v1"
+        });
+        let mut req = axum::http::Request::builder()
+            .method("POST")
+            .uri("/api/llm/list_models")
+            .header("content-type", "application/json")
+            .body(Body::from(req_body.to_string()))
+            .expect("request");
+        req.extensions_mut().insert(UserIdentity {
+            user_id: "member".to_string(),
+            role: "member".to_string(),
+            workspace_read_scopes: Vec::new(),
+        });
+
+        let resp = ServiceExt::<axum::http::Request<Body>>::oneshot(app, req)
+            .await
+            .expect("response");
+        assert_eq!(resp.status(), StatusCode::FORBIDDEN);
+    }
+
     fn expired_flow_created_at() -> Option<std::time::Instant> {
         std::time::Instant::now()
             .checked_sub(oauth_defaults::OAUTH_FLOW_EXPIRY + std::time::Duration::from_secs(1))
diff --git a/src/channels/web/static/app.js b/src/channels/web/static/app.js
index 6d52280f141..8fa62f82697 100644
--- a/src/channels/web/static/app.js
+++ b/src/channels/web/static/app.js
@@ -6231,7 +6231,8 @@ function renderCatalogSkillCard(entry, installedNames) {
   actions.className = 'ext-actions';
 
   var slug = entry.slug || entry.name;
-  var isInstalled = installedNames[entry.name] || installedNames[slug];
+  var slugSuffix = slug.indexOf('/') >= 0 ? slug.split('/').pop() : slug;
+  var isInstalled = entry.installed || installedNames[entry.name] || installedNames[slug] || installedNames[slugSuffix];
 
   if (isInstalled) {
     var label = document.createElement('span');
@@ -6242,14 +6243,14 @@ function renderCatalogSkillCard(entry, installedNames) {
     var installBtn = document.createElement('button');
     installBtn.className = 'btn-ext install';
     installBtn.textContent = I18n.t('extensions.install');
-    installBtn.addEventListener('click', (function(s, btn) {
+    installBtn.addEventListener('click', (function(displayName, slugValue, btn) {
       return function() {
-        if (!confirm(I18n.t('skills.confirmInstallHub', { name: s }))) return;
+        if (!confirm(I18n.t('skills.confirmInstallHub', { name: displayName }))) return;
         btn.disabled = true;
         btn.textContent = I18n.t('extensions.installing');
-        installSkill(s, null, btn);
+        installSkill(displayName, null, btn, slugValue);
       };
-    })(slug, installBtn));
+    })(entry.name || slug, slug, installBtn));
     actions.appendChild(installBtn);
   }
 
@@ -6278,8 +6279,9 @@ function formatTimeAgo(epochMs) {
   return Math.floor(months / 12) + 'y ago';
 }
 
-function installSkill(nameOrSlug, url, btn) {
-  var body = { name: nameOrSlug, slug: nameOrSlug };
+function installSkill(name, url, btn, slug) {
+  var body = { name: name };
+  if (slug) body.slug = slug;
   if (url) body.url = url;
 
   apiFetch('/api/skills/install', {
@@ -6288,12 +6290,19 @@ function installSkill(nameOrSlug, url, btn) {
     body: body,
   }).then(function(res) {
     if (res.success) {
-      showToast(I18n.t('skills.installedSuccess', {name: nameOrSlug}), 'success');
+      showToast(I18n.t('skills.installedSuccess', {name: name}), 'success');
+      if (btn && btn.parentNode) {
+        var label = document.createElement('span');
+        label.className = 'ext-active-label';
+        label.textContent = I18n.t('status.installed');
+        btn.parentNode.innerHTML = '';
+        btn.parentNode.appendChild(label);
+      }
     } else {
       showToast(I18n.t('extensions.installFailed', { message: res.message || 'unknown error' }), 'error');
     }
     loadSkills();
-    if (btn) { btn.disabled = false; btn.textContent = I18n.t('extensions.install'); }
+    if (btn && !res.success) { btn.disabled = false; btn.textContent = I18n.t('extensions.install'); }
   }).catch(function(err) {
     showToast(I18n.t('extensions.installFailed', { message: err.message }), 'error');
     if (btn) { btn.disabled = false; btn.textContent = I18n.t('extensions.install'); }
diff --git a/src/channels/web/types.rs b/src/channels/web/types.rs
index 162c5214791..b2765b976ee 100644
--- a/src/channels/web/types.rs
+++ b/src/channels/web/types.rs
@@ -146,6 +146,20 @@ pub struct GateResolveRequest {
 
 pub use ironclaw_common::{AppEvent, ToolDecisionDto};
 
+// --- Admin System Prompt ---
+
+#[derive(Debug, Deserialize)]
+pub struct SystemPromptRequest {
+    pub content: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct SystemPromptResponse {
+    pub content: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub updated_at: Option<String>,
+}
+
 // --- Memory ---
 
 #[derive(Debug, Serialize)]
diff --git a/src/config/channels.rs b/src/config/channels.rs
index 9650bacd2db..b23f54880ae 100644
--- a/src/config/channels.rs
+++ b/src/config/channels.rs
@@ -18,6 +18,7 @@ pub struct ChannelsConfig {
     pub http: Option<HttpConfig>,
     pub gateway: Option<GatewayConfig>,
     pub signal: Option<SignalConfig>,
+    pub tui: Option<TuiChannelConfig>,
     /// Directory containing WASM channel modules (default: ~/.ironclaw/channels/).
     pub wasm_channels_dir: std::path::PathBuf,
     /// Whether WASM channels are enabled.
@@ -32,6 +33,12 @@ pub struct CliConfig {
     pub enabled: bool,
 }
 
+#[derive(Debug, Clone)]
+pub struct TuiChannelConfig {
+    pub theme: String,
+    pub sidebar_visible: bool,
+}
+
 #[derive(Debug, Clone)]
 pub struct HttpConfig {
     pub host: String,
@@ -362,6 +369,15 @@ impl ChannelsConfig {
         };
 
         let cli_enabled = db_first_bool(cs.cli_enabled, defaults.cli_enabled, "CLI_ENABLED")?;
+        let cli_mode = optional_env("CLI_MODE")?.unwrap_or_default();
+        let tui = if cli_mode.eq_ignore_ascii_case("tui") {
+            Some(TuiChannelConfig {
+                theme: optional_env("TUI_THEME")?.unwrap_or_else(|| "dark".to_string()),
+                sidebar_visible: parse_bool_env("TUI_SIDEBAR", true)?,
+            })
+        } else {
+            None
+        };
 
         Ok(Self {
             cli: CliConfig {
@@ -370,6 +386,7 @@ impl ChannelsConfig {
             http,
             gateway,
             signal,
+            tui,
             wasm_channels_dir: {
                 // DB-first: use settings if explicitly set, else env, else default.
                 // defaults.wasm_channels_dir is None, so any Some(..) is an explicit DB override.
@@ -536,6 +553,7 @@ mod tests {
             http: None,
             gateway: None,
             signal: None,
+            tui: None,
             wasm_channels_dir: PathBuf::from("/tmp/channels"),
             wasm_channels_enabled: true,
             wasm_channel_owner_ids: HashMap::new(),
@@ -560,6 +578,7 @@ mod tests {
             http: None,
             gateway: None,
             signal: None,
+            tui: None,
             wasm_channels_dir: PathBuf::from("/opt/channels"),
             wasm_channels_enabled: false,
             wasm_channel_owner_ids: ids,
@@ -622,4 +641,29 @@ mod tests {
         // SAFETY: under ENV_MUTEX
         unsafe { std::env::remove_var("GATEWAY_AUTH_TOKEN") };
     }
+
+    #[test]
+    fn resolve_enables_tui_mode_from_env() {
+        let _guard = lock_env();
+        let settings = Settings::default();
+
+        // SAFETY: under ENV_MUTEX
+        unsafe {
+            std::env::set_var("CLI_MODE", "tui");
+            std::env::set_var("TUI_THEME", "light");
+            std::env::set_var("TUI_SIDEBAR", "false");
+        }
+
+        let cfg = ChannelsConfig::resolve(&settings, "owner-scope").expect("resolve");
+        let tui = cfg.tui.expect("tui config");
+        assert_eq!(tui.theme, "light");
+        assert!(!tui.sidebar_visible);
+
+        // SAFETY: under ENV_MUTEX
+        unsafe {
+            std::env::remove_var("CLI_MODE");
+            std::env::remove_var("TUI_THEME");
+            std::env::remove_var("TUI_SIDEBAR");
+        }
+    }
 }
diff --git a/src/config/embeddings.rs b/src/config/embeddings.rs
index a6d0c717bad..59a95f301f2 100644
--- a/src/config/embeddings.rs
+++ b/src/config/embeddings.rs
@@ -3,7 +3,8 @@ use std::sync::Arc;
 use secrecy::{ExposeSecret, SecretString};
 
 use crate::config::helpers::{
-    db_first_bool, db_first_or_default, optional_env, parse_optional_env, validate_base_url,
+    db_first_bool, db_first_or_default, optional_env, parse_optional_env,
+    validate_operator_base_url,
 };
 use crate::error::ConfigError;
 use crate::llm::{BedrockConfig, SessionManager};
@@ -128,9 +129,9 @@ impl EmbeddingsConfig {
         let openai_base_url = optional_env("EMBEDDING_BASE_URL")?;
 
         // Validate base URLs to prevent SSRF attacks (#1103).
-        validate_base_url(&ollama_base_url, "OLLAMA_BASE_URL")?;
+        validate_operator_base_url(&ollama_base_url, "OLLAMA_BASE_URL")?;
         if let Some(ref url) = openai_base_url {
-            validate_base_url(url, "EMBEDDING_BASE_URL")?;
+            validate_operator_base_url(url, "EMBEDDING_BASE_URL")?;
         }
 
         let cache_size = parse_optional_env("EMBEDDING_CACHE_SIZE", DEFAULT_EMBEDDING_CACHE_SIZE)?;
diff --git a/src/config/helpers.rs b/src/config/helpers.rs
index 320add41999..e970a1ae508 100644
--- a/src/config/helpers.rs
+++ b/src/config/helpers.rs
@@ -186,6 +186,37 @@ pub(crate) fn parse_string_env(
     Ok(optional_env(key)?.unwrap_or_else(|| default.into()))
 }
 
+/// Setting keys that influence LLM/embeddings provider base URLs.
+///
+/// These keys are validated with the operator policy (which allows
+/// private/loopback endpoints), so they must only be writable and
+/// resolvable for admin users. The settings HTTP handlers reject
+/// non-admin writes/imports of these keys; `strip_admin_only_llm_keys`
+/// is the matching defense for the read/resolve path so a non-admin
+/// user (or pre-existing legacy DB row) cannot reactivate a private
+/// endpoint after this restriction landed.
+pub(crate) const ADMIN_ONLY_LLM_SETTING_KEYS: &[&str] = &[
+    "llm_builtin_overrides",
+    "llm_custom_providers",
+    "ollama_base_url",
+    "openai_compatible_base_url",
+];
+
+/// Remove admin-only LLM setting keys from a flat DB settings map.
+///
+/// Used by config resolution paths that load per-user DB settings for a
+/// non-operator user, to ensure they cannot inject private/loopback
+/// provider endpoints into the active LLM/embeddings configuration.
+pub(crate) fn strip_admin_only_llm_keys(map: &mut HashMap<String, serde_json::Value>) {
+    map.retain(|key, _| !ADMIN_ONLY_LLM_SETTING_KEYS.contains(&key.as_str()));
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum BaseUrlPolicy {
+    StrictSsrf,
+    AllowPrivateNetwork,
+}
+
 /// Validate a user-configurable base URL to prevent SSRF attacks (#1103).
 ///
 /// Rejects:
@@ -196,8 +227,63 @@ pub(crate) fn parse_string_env(
 /// This is intended for config-time validation of base URLs like
 /// `OLLAMA_BASE_URL`, `EMBEDDING_BASE_URL`, `NEARAI_BASE_URL`, etc.
 pub(crate) fn validate_base_url(url: &str, field_name: &str) -> Result<(), ConfigError> {
+    validate_base_url_with_policy(url, field_name, BaseUrlPolicy::StrictSsrf)
+}
+
+/// Validate an operator-configured model endpoint.
+///
+/// Unlike generic SSRF validation, this allows private/loopback LLM endpoints
+/// over both HTTP and HTTPS because they are explicitly configured by the
+/// operator. Public HTTP endpoints remain blocked to avoid sending credentials
+/// over plaintext transport.
+pub(crate) fn validate_operator_base_url(url: &str, field_name: &str) -> Result<(), ConfigError> {
+    validate_base_url_with_policy(url, field_name, BaseUrlPolicy::AllowPrivateNetwork)
+}
+
+fn classify_ip(ip: &std::net::IpAddr) -> IpClass {
     use std::net::{IpAddr, Ipv4Addr};
 
+    match ip {
+        IpAddr::V4(v4) => {
+            if v4.is_unspecified()
+                || v4.is_multicast()
+                || v4.is_link_local()
+                || *v4 == Ipv4Addr::new(169, 254, 169, 254)
+            {
+                IpClass::AlwaysBlocked
+            } else if v4.is_private()
+                || v4.is_loopback()
+                || (v4.octets()[0] == 100 && (v4.octets()[1] & 0xC0) == 64)
+            {
+                IpClass::PrivateOrLoopback
+            } else {
+                IpClass::Public
+            }
+        }
+        IpAddr::V6(v6) => {
+            if let Some(v4) = v6.to_ipv4_mapped() {
+                classify_ip(&IpAddr::V4(v4))
+            } else if v6.is_unspecified()
+                || v6.octets()[0] == 0xff
+                || (v6.segments()[0] & 0xffc0) == 0xfe80
+            {
+                IpClass::AlwaysBlocked
+            } else if v6.is_loopback() || (v6.octets()[0] & 0xfe) == 0xfc {
+                IpClass::PrivateOrLoopback
+            } else {
+                IpClass::Public
+            }
+        }
+    }
+}
+
+fn validate_base_url_with_policy(
+    url: &str,
+    field_name: &str,
+    policy: BaseUrlPolicy,
+) -> Result<(), ConfigError> {
+    use std::net::{IpAddr, ToSocketAddrs};
+
     let parsed = reqwest::Url::parse(url).map_err(|e| ConfigError::InvalidValue {
         key: field_name.to_string(),
         message: format!("invalid URL '{}': {}", url, e),
@@ -217,127 +303,140 @@ pub(crate) fn validate_base_url(url: &str, field_name: &str) -> Result<(), Confi
     })?;
 
     let host_lower = host.to_lowercase();
+    let normalized_host = host.trim_start_matches('[').trim_end_matches(']');
 
-    // For HTTP (non-TLS), only allow localhost — remote HTTP endpoints
-    // risk credential leakage (e.g. NEAR AI bearer tokens sent over plaintext).
-    if scheme == "http" {
-        let is_localhost = host_lower == "localhost"
+    let is_localhost_name = || {
+        host_lower == "localhost"
             || host_lower == "127.0.0.1"
-            || host_lower == "::1"
-            || host_lower == "[::1]"
-            || host_lower.ends_with(".localhost");
-        if !is_localhost {
-            return Err(ConfigError::InvalidValue {
-                key: field_name.to_string(),
-                message: format!(
-                    "HTTP (non-TLS) is only allowed for localhost, got '{}'. \
-                     Use HTTPS for remote endpoints.",
-                    host
-                ),
-            });
-        }
-        return Ok(());
-    }
-
-    // Check whether an IP is in a blocked range (private, loopback,
-    // link-local, multicast, metadata, CGN, ULA).
-    let is_dangerous_ip = |ip: &IpAddr| -> bool {
-        match ip {
-            IpAddr::V4(v4) => {
-                v4.is_private()
-                    || v4.is_loopback()
-                    || v4.is_link_local()
-                    || v4.is_multicast()
-                    || v4.is_unspecified()
-                    || *v4 == Ipv4Addr::new(169, 254, 169, 254)
-                    || (v4.octets()[0] == 100 && (v4.octets()[1] & 0xC0) == 64) // CGN
-            }
-            IpAddr::V6(v6) => {
-                if let Some(v4) = v6.to_ipv4_mapped() {
-                    v4.is_private()
-                        || v4.is_loopback()
-                        || v4.is_link_local()
-                        || v4.is_multicast()
-                        || v4.is_unspecified()
-                        || v4 == Ipv4Addr::new(169, 254, 169, 254)
-                        || (v4.octets()[0] == 100 && (v4.octets()[1] & 0xC0) == 64) // CGN
-                } else {
-                    v6.is_loopback()
-                        || v6.is_unspecified()
-                        || (v6.octets()[0] & 0xfe) == 0xfc // ULA (fc00::/7)
-                        || (v6.segments()[0] & 0xffc0) == 0xfe80 // link-local (fe80::/10)
-                        || v6.octets()[0] == 0xff // multicast (ff00::/8)
-                }
-            }
-        }
+            || normalized_host == "::1"
+            || host_lower.ends_with(".localhost")
     };
 
-    // For HTTPS, reject private/loopback/link-local/metadata IPs.
-    // Check both IP literals and resolved hostnames to prevent DNS-based SSRF.
-    //
-    // `Url::host_str()` returns IPv6 literals WITH the surrounding brackets
-    // (e.g. "[::1]"), but `IpAddr::parse` does not accept brackets — it wants
-    // bare "::1". Strip them so we recognize IPv6 literals before falling
-    // through to the DNS-resolution branch (which on some systems with DNS
-    // hijacking can produce a non-private IP and bypass this check).
-    let host_for_parse = host.trim_matches(|c| c == '[' || c == ']');
-    if let Ok(ip) = host_for_parse.parse::<IpAddr>() {
-        if is_dangerous_ip(&ip) {
-            return Err(ConfigError::InvalidValue {
-                key: field_name.to_string(),
-                message: format!(
-                    "URL points to a private/internal IP '{}'. \
-                     This is blocked to prevent SSRF attacks.",
-                    ip
-                ),
-            });
-        }
+    if scheme == "http" && policy == BaseUrlPolicy::StrictSsrf && !is_localhost_name() {
+        return Err(ConfigError::InvalidValue {
+            key: field_name.to_string(),
+            message: format!(
+                "HTTP (non-TLS) is only allowed for localhost, got '{}'. \
+                 Use HTTPS for remote endpoints.",
+                host
+            ),
+        });
+    }
+
+    let resolved_ips = if let Ok(ip) = normalized_host.parse::<IpAddr>() {
+        vec![ip]
     } else {
-        // Hostname — resolve and check all resulting IPs as defense-in-depth.
-        // NOTE: This does NOT fully prevent DNS rebinding attacks (the hostname
-        // could resolve to a different IP at request time). Full protection
-        // would require pinning the resolved IP in the HTTP client's connector.
-        // This validation catches the common case of misconfigured or malicious URLs.
-        //
-        // NOTE: `to_socket_addrs()` performs blocking DNS resolution. This is
-        // acceptable because `validate_base_url` runs at config-load time only,
-        // before the async runtime is fully driving I/O. If this ever moves to
-        // a hot path, wrap in `tokio::task::spawn_blocking` or use
-        // `tokio::net::lookup_host`.
-        use std::net::ToSocketAddrs;
-        let port = parsed.port().unwrap_or(443);
-        match (host, port).to_socket_addrs() {
-            Ok(addrs) => {
-                for addr in addrs {
-                    if is_dangerous_ip(&addr.ip()) {
-                        return Err(ConfigError::InvalidValue {
-                            key: field_name.to_string(),
-                            message: format!(
-                                "hostname '{}' resolves to private/internal IP '{}'. \
-                                 This is blocked to prevent SSRF attacks.",
-                                host,
-                                addr.ip()
-                            ),
-                        });
-                    }
-                }
+        let port = parsed
+            .port()
+            .unwrap_or(if scheme == "http" { 80 } else { 443 });
+        // `to_socket_addrs` performs blocking DNS resolution. This helper is
+        // also called from async request handlers (e.g. the LLM utility
+        // routes), so wrap the lookup in `block_in_place` when running on a
+        // multi-threaded tokio worker to avoid stalling other tasks. The
+        // `try_current()` check keeps sync callers (config bootstrap, CLI)
+        // working unchanged.
+        let resolve = || -> std::io::Result<Vec<IpAddr>> {
+            Ok((host, port)
+                .to_socket_addrs()?
+                .map(|addr| addr.ip())
+                .collect())
+        };
+        let lookup = match tokio::runtime::Handle::try_current() {
+            Ok(handle) if handle.runtime_flavor() == tokio::runtime::RuntimeFlavor::MultiThread => {
+                tokio::task::block_in_place(resolve)
             }
-            Err(e) => {
+            _ => resolve(),
+        };
+        lookup.map_err(|e| ConfigError::InvalidValue {
+            key: field_name.to_string(),
+            message: format!(
+                "failed to resolve hostname '{}': {}. \
+                 Base URLs must be resolvable at config time.",
+                host, e
+            ),
+        })?
+    };
+
+    if scheme == "http" {
+        if is_localhost_name() {
+            return Ok(());
+        }
+
+        let all_private = !resolved_ips.is_empty()
+            && resolved_ips
+                .iter()
+                .all(|ip| matches!(classify_ip(ip), IpClass::PrivateOrLoopback));
+        let any_blocked = resolved_ips
+            .iter()
+            .any(|ip| matches!(classify_ip(ip), IpClass::AlwaysBlocked));
+
+        if policy == BaseUrlPolicy::AllowPrivateNetwork && all_private && !any_blocked {
+            return Ok(());
+        }
+
+        return Err(ConfigError::InvalidValue {
+            key: field_name.to_string(),
+            message: if policy == BaseUrlPolicy::AllowPrivateNetwork {
+                format!(
+                    "HTTP (non-TLS) is only allowed for localhost or private/internal endpoints, got '{}'. \
+                     Use HTTPS for public endpoints.",
+                    host
+                )
+            } else {
+                format!(
+                    "HTTP (non-TLS) is only allowed for localhost, got '{}'. \
+                     Use HTTPS for remote endpoints.",
+                    host
+                )
+            },
+        });
+    }
+
+    for ip in resolved_ips {
+        match classify_ip(&ip) {
+            IpClass::AlwaysBlocked => {
                 return Err(ConfigError::InvalidValue {
                     key: field_name.to_string(),
                     message: format!(
-                        "failed to resolve hostname '{}': {}. \
-                         Base URLs must be resolvable at config time.",
-                        host, e
+                        "URL points to a blocked IP '{}'. \
+                         This is blocked to prevent SSRF attacks.",
+                        ip
                     ),
                 });
             }
+            IpClass::PrivateOrLoopback if policy == BaseUrlPolicy::StrictSsrf => {
+                let message = if normalized_host.parse::<IpAddr>().is_ok() {
+                    format!(
+                        "URL points to a private/internal IP '{}'. \
+                         This is blocked to prevent SSRF attacks.",
+                        ip
+                    )
+                } else {
+                    format!(
+                        "hostname '{}' resolves to private/internal IP '{}'. \
+                         This is blocked to prevent SSRF attacks.",
+                        host, ip
+                    )
+                };
+                return Err(ConfigError::InvalidValue {
+                    key: field_name.to_string(),
+                    message,
+                });
+            }
+            _ => {}
         }
     }
 
     Ok(())
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum IpClass {
+    Public,
+    PrivateOrLoopback,
+    AlwaysBlocked,
+}
+
 // ---------------------------------------------------------------------------
 // DB-first resolution helpers (DB > env > default)
 // ---------------------------------------------------------------------------
@@ -524,6 +623,20 @@ mod tests {
         assert!(validate_base_url("http://192.168.1.1", "TEST").is_err());
     }
 
+    #[test]
+    fn validate_base_url_rejects_http_remote_without_dns_resolution() {
+        let result = validate_base_url("http://ssrf-test.invalid", "TEST");
+        let err = result.unwrap_err().to_string();
+        assert!(
+            err.contains("only allowed for localhost"),
+            "strict HTTP validation should short-circuit before DNS lookup: {err}"
+        );
+        assert!(
+            !err.contains("failed to resolve"),
+            "strict HTTP validation should not require DNS resolution: {err}"
+        );
+    }
+
     #[test]
     fn validate_base_url_rejects_non_http_schemes() {
         assert!(validate_base_url("file:///etc/passwd", "TEST").is_err());
@@ -639,6 +752,31 @@ mod tests {
         );
     }
 
+    #[test]
+    fn validate_operator_base_url_allows_https_private_ips() {
+        assert!(validate_operator_base_url("https://100.64.0.1/v1", "TEST").is_ok());
+        assert!(validate_operator_base_url("https://127.0.0.1/v1", "TEST").is_ok());
+        assert!(validate_operator_base_url("https://[::1]/v1", "TEST").is_ok());
+    }
+
+    #[test]
+    fn validate_operator_base_url_allows_http_private_ips() {
+        assert!(validate_operator_base_url("http://100.64.0.1:8000/v1", "TEST").is_ok());
+        assert!(validate_operator_base_url("http://192.168.1.50:8000/v1", "TEST").is_ok());
+    }
+
+    #[test]
+    fn validate_operator_base_url_still_rejects_public_http_and_metadata() {
+        assert!(validate_operator_base_url("http://8.8.8.8/v1", "TEST").is_err());
+        assert!(validate_operator_base_url("https://169.254.169.254/v1", "TEST").is_err());
+    }
+
+    #[test]
+    fn validate_operator_base_url_rejects_link_local_ips() {
+        assert!(validate_operator_base_url("http://169.254.1.10:8000/v1", "TEST").is_err());
+        assert!(validate_operator_base_url("https://[fe80::1]/v1", "TEST").is_err());
+    }
+
     // --- db_first_* helper tests ---
 
     #[test]
@@ -778,4 +916,87 @@ mod tests {
 
         unsafe { std::env::remove_var(key) };
     }
+
+    // --- admin-only LLM key stripping (defense-in-depth for #1955) ---
+
+    #[test]
+    fn strip_admin_only_llm_keys_removes_all_known_keys() {
+        let mut map = HashMap::new();
+        map.insert(
+            "llm_builtin_overrides".to_string(),
+            serde_json::json!({"openai": {"base_url": "http://10.0.0.5"}}),
+        );
+        map.insert(
+            "llm_custom_providers".to_string(),
+            serde_json::json!([{"id": "x"}]),
+        );
+        map.insert(
+            "ollama_base_url".to_string(),
+            serde_json::json!("http://192.168.1.20:11434"),
+        );
+        map.insert(
+            "openai_compatible_base_url".to_string(),
+            serde_json::json!("http://100.64.0.1"),
+        );
+        map.insert("selected_model".to_string(), serde_json::json!("gpt-4o"));
+        map.insert("agent.name".to_string(), serde_json::json!("Iron"));
+
+        strip_admin_only_llm_keys(&mut map);
+
+        assert!(!map.contains_key("llm_builtin_overrides"));
+        assert!(!map.contains_key("llm_custom_providers"));
+        assert!(!map.contains_key("ollama_base_url"));
+        assert!(!map.contains_key("openai_compatible_base_url"));
+        // Non-admin keys must survive.
+        assert_eq!(
+            map.get("selected_model"),
+            Some(&serde_json::json!("gpt-4o"))
+        );
+        assert_eq!(map.get("agent.name"), Some(&serde_json::json!("Iron")));
+    }
+
+    #[test]
+    fn strip_admin_only_llm_keys_is_a_no_op_for_clean_map() {
+        let mut map = HashMap::new();
+        map.insert("selected_model".to_string(), serde_json::json!("gpt-4o"));
+        map.insert("llm_backend".to_string(), serde_json::json!("openai"));
+
+        strip_admin_only_llm_keys(&mut map);
+
+        assert_eq!(map.len(), 2);
+        assert!(map.contains_key("selected_model"));
+        assert!(map.contains_key("llm_backend"));
+    }
+
+    // --- async DNS regression (#1955: don't stall the tokio worker) ---
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn validate_base_url_safe_to_call_from_async_handler() {
+        // Regression test: validate_base_url_with_policy used to call the
+        // blocking `to_socket_addrs()` directly, which can stall a tokio
+        // worker thread when invoked from an async handler. The function
+        // now wraps the lookup in `block_in_place` on multi-threaded
+        // runtimes, so calling it from an async context must not panic
+        // and must produce a deterministic error.
+        let result = validate_base_url("http://ssrf-test.invalid", "TEST");
+        let err = result.expect_err("invalid host should fail validation");
+        let msg = err.to_string();
+        // Strict policy short-circuits before DNS, so we should get the
+        // localhost-only message rather than a DNS error.
+        assert!(
+            msg.contains("only allowed for localhost"),
+            "expected strict short-circuit, got: {msg}"
+        );
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn validate_operator_base_url_safe_to_call_from_async_handler() {
+        // The operator policy must also tolerate being called from async
+        // handlers (it is reachable from /api/llm/test_connection and
+        // /api/llm/list_models). Use IP literals so we don't depend on
+        // a working resolver.
+        assert!(validate_operator_base_url("http://127.0.0.1:11434", "TEST").is_ok());
+        assert!(validate_operator_base_url("http://192.168.1.10:11434", "TEST").is_ok());
+        assert!(validate_operator_base_url("http://169.254.169.254", "TEST").is_err());
+    }
 }
diff --git a/src/config/llm.rs b/src/config/llm.rs
index cf3fc19f9ea..3d4ccc65d0e 100644
--- a/src/config/llm.rs
+++ b/src/config/llm.rs
@@ -4,7 +4,9 @@ use std::sync::Once;
 use secrecy::SecretString;
 
 use crate::bootstrap::ironclaw_base_dir;
-use crate::config::helpers::{optional_env, parse_optional_env, validate_base_url};
+use crate::config::helpers::{
+    optional_env, parse_optional_env, validate_base_url, validate_operator_base_url,
+};
 use crate::error::ConfigError;
 use crate::llm::config::*;
 use crate::llm::registry::{ProviderProtocol, ProviderRegistry};
@@ -360,7 +362,7 @@ impl LlmConfig {
         if base_url.is_empty() {
             tracing::warn!(id = %custom.id, "Custom provider has no base_url configured — requests will fail");
         } else {
-            validate_base_url(
+            validate_operator_base_url(
                 &base_url,
                 &format!("custom provider '{}' base_url", custom.id),
             )?;
@@ -531,10 +533,12 @@ impl LlmConfig {
             });
         }
 
-        // Validate base URL to prevent SSRF (#1103).
+        // Provider base URLs are explicit operator configuration, so allow
+        // private/local endpoints while still rejecting unsafe schemes,
+        // public plaintext HTTP, and special blocked addresses.
         if !base_url.is_empty() {
             let field = base_url_env.unwrap_or("LLM_BASE_URL");
-            validate_base_url(&base_url, field)?;
+            validate_operator_base_url(&base_url, field)?;
         }
 
         // Resolve model: selected_model (DB) > per-provider override (DB) > env var > registry default
@@ -911,6 +915,40 @@ mod tests {
         );
     }
 
+    #[test]
+    fn openai_compatible_allows_https_localhost_base_url() {
+        let _guard = lock_env();
+        clear_openai_compatible_env();
+
+        let settings = Settings {
+            llm_backend: Some("openai_compatible".to_string()),
+            openai_compatible_base_url: Some("https://localhost:8443/v1".to_string()),
+            ..Default::default()
+        };
+
+        let cfg = LlmConfig::resolve(&settings).expect("resolve should succeed");
+        let provider = cfg.provider.expect("provider config should be present");
+
+        assert_eq!(provider.base_url, "https://localhost:8443/v1");
+    }
+
+    #[test]
+    fn openai_compatible_allows_http_private_network_base_url() {
+        let _guard = lock_env();
+        clear_openai_compatible_env();
+
+        let settings = Settings {
+            llm_backend: Some("openai_compatible".to_string()),
+            openai_compatible_base_url: Some("http://100.64.0.10:8000/v1".to_string()),
+            ..Default::default()
+        };
+
+        let cfg = LlmConfig::resolve(&settings).expect("resolve should succeed");
+        let provider = cfg.provider.expect("provider config should be present");
+
+        assert_eq!(provider.base_url, "http://100.64.0.10:8000/v1");
+    }
+
     #[test]
     fn registry_provider_resolves_groq() {
         let _guard = lock_env();
diff --git a/src/config/mod.rs b/src/config/mod.rs
index ae7a3e2904f..d4fb67663f4 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -52,7 +52,7 @@ pub use self::agent::AgentConfig;
 pub use self::builder::BuilderModeConfig;
 pub use self::channels::{
     ChannelsConfig, CliConfig, DEFAULT_GATEWAY_PORT, GatewayConfig, GatewayOidcConfig, HttpConfig,
-    SignalConfig,
+    SignalConfig, TuiChannelConfig,
 };
 pub use self::database::{DatabaseBackend, DatabaseConfig, SslMode, default_libsql_path};
 pub use self::embeddings::{DEFAULT_EMBEDDING_CACHE_SIZE, EmbeddingsConfig};
@@ -161,6 +161,7 @@ impl Config {
                 http: None,
                 gateway: None,
                 signal: None,
+                tui: None,
                 wasm_channels_dir: std::env::temp_dir().join("ironclaw-test-channels"),
                 wasm_channels_enabled: false,
                 wasm_channel_owner_ids: HashMap::new(),
@@ -215,17 +216,27 @@ impl Config {
         store: &(dyn crate::db::SettingsStore + Sync),
         user_id: &str,
     ) -> Result<Self, ConfigError> {
-        Self::from_db_with_toml(store, user_id, None).await
+        // Existing call sites pass the workspace owner_id, which is the
+        // operator/admin scope.
+        Self::from_db_with_toml(store, user_id, None, true).await
     }
 
     /// Load from DB with an optional TOML config file overlay.
     ///
     /// Priority: DB/TOML > env > default. TOML is loaded as the base,
     /// then DB values are merged on top. See module docs for exceptions.
+    ///
+    /// `is_operator` controls defense-in-depth filtering of admin-only LLM
+    /// setting keys (`llm_builtin_overrides`, `llm_custom_providers`,
+    /// `ollama_base_url`, `openai_compatible_base_url`). When `false`, those
+    /// keys are stripped from the DB overlay so a non-admin user (or a
+    /// pre-existing legacy DB row) cannot reactivate a private/loopback
+    /// provider endpoint via per-user settings.
     pub async fn from_db_with_toml(
         store: &(dyn crate::db::SettingsStore + Sync),
         user_id: &str,
         toml_path: Option<&std::path::Path>,
+        is_operator: bool,
     ) -> Result<Self, ConfigError> {
         let _ = dotenvy::dotenv();
         crate::bootstrap::load_ironclaw_env();
@@ -236,7 +247,10 @@ impl Config {
 
         // Overlay DB settings on top so DB values win over TOML.
         match store.get_all_settings(user_id).await {
-            Ok(map) => {
+            Ok(mut map) => {
+                if !is_operator {
+                    crate::config::helpers::strip_admin_only_llm_keys(&mut map);
+                }
                 let db_settings = Settings::from_db_map(&map);
                 settings.merge_from(&db_settings);
             }
@@ -320,23 +334,31 @@ impl Config {
         user_id: &str,
         toml_path: Option<&std::path::Path>,
     ) -> Result<(), ConfigError> {
-        self.re_resolve_llm_with_secrets(store, user_id, toml_path, None)
+        let is_operator = user_id == self.owner_id;
+        self.re_resolve_llm_with_secrets(store, user_id, toml_path, None, is_operator)
             .await
     }
 
     /// Re-resolve LLM config, hydrating API keys from the secrets store.
+    ///
+    /// `is_operator` controls defense-in-depth filtering of admin-only LLM
+    /// setting keys; see [`Config::from_db_with_toml`] for details.
     pub async fn re_resolve_llm_with_secrets(
         &mut self,
         store: Option<&(dyn crate::db::SettingsStore + Sync)>,
         user_id: &str,
         toml_path: Option<&std::path::Path>,
         secrets: Option<&(dyn crate::secrets::SecretsStore + Send + Sync)>,
+        is_operator: bool,
     ) -> Result<(), ConfigError> {
         let mut settings = if let Some(store) = store {
             // TOML as base, then DB on top (DB wins).
             let mut s = Settings::default();
             Self::apply_toml_overlay(&mut s, toml_path)?;
-            if let Ok(map) = store.get_all_settings(user_id).await {
+            if let Ok(mut map) = store.get_all_settings(user_id).await {
+                if !is_operator {
+                    crate::config::helpers::strip_admin_only_llm_keys(&mut map);
+                }
                 let db_settings = Settings::from_db_map(&map);
                 s.merge_from(&db_settings);
             }
@@ -812,6 +834,192 @@ mod tests {
         );
     }
 
+    /// Minimal in-memory `SettingsStore` for unit tests.
+    ///
+    /// Only the methods exercised by the resolve path are wired up; the
+    /// rest return errors so unintended use during a test is loud.
+    struct FakeSettingsStore {
+        rows: tokio::sync::RwLock<
+            std::collections::HashMap<String, std::collections::HashMap<String, serde_json::Value>>,
+        >,
+    }
+
+    impl FakeSettingsStore {
+        fn new() -> Self {
+            Self {
+                rows: tokio::sync::RwLock::new(std::collections::HashMap::new()),
+            }
+        }
+
+        async fn seed(&self, user_id: &str, key: &str, value: serde_json::Value) {
+            let mut rows = self.rows.write().await;
+            rows.entry(user_id.to_string())
+                .or_default()
+                .insert(key.to_string(), value);
+        }
+    }
+
+    #[async_trait::async_trait]
+    impl crate::db::SettingsStore for FakeSettingsStore {
+        async fn get_setting(
+            &self,
+            user_id: &str,
+            key: &str,
+        ) -> Result<Option<serde_json::Value>, crate::error::DatabaseError> {
+            let rows = self.rows.read().await;
+            Ok(rows.get(user_id).and_then(|m| m.get(key).cloned()))
+        }
+
+        async fn get_setting_full(
+            &self,
+            _user_id: &str,
+            _key: &str,
+        ) -> Result<Option<crate::history::SettingRow>, crate::error::DatabaseError> {
+            Err(crate::error::DatabaseError::Query(
+                "FakeSettingsStore::get_setting_full not implemented".into(),
+            ))
+        }
+
+        async fn set_setting(
+            &self,
+            user_id: &str,
+            key: &str,
+            value: &serde_json::Value,
+        ) -> Result<(), crate::error::DatabaseError> {
+            self.seed(user_id, key, value.clone()).await;
+            Ok(())
+        }
+
+        async fn delete_setting(
+            &self,
+            user_id: &str,
+            key: &str,
+        ) -> Result<bool, crate::error::DatabaseError> {
+            let mut rows = self.rows.write().await;
+            Ok(rows
+                .get_mut(user_id)
+                .map(|m| m.remove(key).is_some())
+                .unwrap_or(false))
+        }
+
+        async fn list_settings(
+            &self,
+            _user_id: &str,
+        ) -> Result<Vec<crate::history::SettingRow>, crate::error::DatabaseError> {
+            Err(crate::error::DatabaseError::Query(
+                "FakeSettingsStore::list_settings not implemented".into(),
+            ))
+        }
+
+        async fn get_all_settings(
+            &self,
+            user_id: &str,
+        ) -> Result<std::collections::HashMap<String, serde_json::Value>, crate::error::DatabaseError>
+        {
+            let rows = self.rows.read().await;
+            Ok(rows.get(user_id).cloned().unwrap_or_default())
+        }
+
+        async fn set_all_settings(
+            &self,
+            user_id: &str,
+            settings: &std::collections::HashMap<String, serde_json::Value>,
+        ) -> Result<(), crate::error::DatabaseError> {
+            let mut rows = self.rows.write().await;
+            rows.insert(user_id.to_string(), settings.clone());
+            Ok(())
+        }
+
+        async fn has_settings(&self, user_id: &str) -> Result<bool, crate::error::DatabaseError> {
+            let rows = self.rows.read().await;
+            Ok(rows.get(user_id).is_some_and(|m| !m.is_empty()))
+        }
+    }
+
+    fn member_settings_with_private_endpoint() -> serde_json::Value {
+        // A leftover DB row written by a non-admin user before the
+        // admin-only restriction landed: points the openai backend at a
+        // private LAN address that would normally fail SSRF validation.
+        serde_json::json!({
+            "openai": {
+                "base_url": "http://192.168.1.50:11434",
+                "model": "leak-bait"
+            }
+        })
+    }
+
+    fn config_for_owner(owner_id: &str) -> Config {
+        let tmp = std::env::temp_dir().join(format!("ironclaw-resolve-test-{owner_id}"));
+        let mut cfg = Config::for_testing(tmp.clone(), tmp.clone(), tmp);
+        cfg.owner_id = owner_id.to_string();
+        cfg
+    }
+
+    #[tokio::test]
+    async fn re_resolve_llm_strips_admin_only_keys_for_non_operator_user() {
+        use crate::db::SettingsStore;
+
+        let store = FakeSettingsStore::new();
+        // Seed a non-admin user's per-user settings with an admin-only key
+        // that points at a private endpoint.
+        store
+            .seed(
+                "member-user",
+                "llm_builtin_overrides",
+                member_settings_with_private_endpoint(),
+            )
+            .await;
+
+        let mut cfg = config_for_owner("operator-user");
+        cfg.re_resolve_llm_with_secrets(
+            Some(&store as &(dyn crate::db::SettingsStore + Sync)),
+            "member-user",
+            None,
+            None,
+            false, // <- non-operator: admin-only keys must be stripped
+        )
+        .await
+        .expect("resolve should not fail");
+
+        // Re-load via the store and apply the same filter the resolver
+        // uses, to assert the helper actually drops the poisoned key.
+        let mut filtered = store.get_all_settings("member-user").await.unwrap();
+        crate::config::helpers::strip_admin_only_llm_keys(&mut filtered);
+        assert!(
+            !filtered.contains_key("llm_builtin_overrides"),
+            "filter helper must remove the admin-only key"
+        );
+    }
+
+    #[tokio::test]
+    async fn re_resolve_llm_keeps_admin_only_keys_for_operator() {
+        let store = FakeSettingsStore::new();
+        store
+            .seed(
+                "operator-user",
+                "llm_builtin_overrides",
+                serde_json::json!({
+                    "openai": {
+                        "model": "gpt-4o"
+                    }
+                }),
+            )
+            .await;
+
+        let mut cfg = config_for_owner("operator-user");
+        // is_operator=true: admin/operator may legitimately configure
+        // builtin overrides, so the resolve path must keep them.
+        cfg.re_resolve_llm_with_secrets(
+            Some(&store as &(dyn crate::db::SettingsStore + Sync)),
+            "operator-user",
+            None,
+            None,
+            true,
+        )
+        .await
+        .expect("resolve should succeed for operator");
+    }
+
     #[tokio::test]
     async fn hydrate_skips_when_key_already_present() {
         let secrets = test_secrets_store();
diff --git a/src/extensions/manager.rs b/src/extensions/manager.rs
index 22f10d10248..6578e1745d5 100644
--- a/src/extensions/manager.rs
+++ b/src/extensions/manager.rs
@@ -135,12 +135,7 @@ pub struct ExtensionSetupSchema {
 
 /// Only these global (non-namespaced) setting paths may be written by extension
 /// setup fields. Everything else must be under `extensions.<name>.*`.
-const ALLOWED_GLOBAL_SETUP_SETTING_PATHS: &[&str] = &[
-    "llm_backend",
-    "selected_model",
-    "ollama_base_url",
-    "openai_compatible_base_url",
-];
+const ALLOWED_GLOBAL_SETUP_SETTING_PATHS: &[&str] = &["llm_backend", "selected_model"];
 
 #[cfg(test)]
 type TestWasmChannelLoader =
@@ -6711,6 +6706,61 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn test_configure_rejects_admin_only_global_base_url_setting_path() {
+        let dir = tempfile::tempdir().expect("temp dir");
+        let (store, _db_dir) = make_test_store().await;
+        let tools_dir = write_test_tool(
+            dir.path(),
+            "base-url-tool",
+            r#"{
+                "setup": {
+                    "required_fields": [
+                        {
+                            "name": "base_url",
+                            "prompt": "Base URL",
+                            "setting_path": "ollama_base_url"
+                        }
+                    ]
+                }
+            }"#,
+        );
+        let channels_dir = dir.path().join("channels");
+
+        let mgr =
+            make_test_manager_with_dirs(None, tools_dir, channels_dir, Some(Arc::clone(&store)));
+        let mut fields = std::collections::HashMap::new();
+        fields.insert(
+            "base_url".to_string(),
+            "http://192.168.1.50:11434".to_string(),
+        );
+
+        let err = match mgr
+            .configure(
+                "base-url-tool",
+                &std::collections::HashMap::new(),
+                &fields,
+                "test-user",
+            )
+            .await
+        {
+            Ok(_) => panic!("admin-only global setting_path should fail"),
+            Err(err) => err,
+        };
+        let msg = err.to_string();
+        assert!(
+            msg.contains("Invalid setting_path"),
+            "unexpected error message: {msg}"
+        );
+        assert_eq!(
+            store
+                .get_setting("test", "ollama_base_url")
+                .await
+                .expect("get admin-only setting"),
+            None
+        );
+    }
+
     #[tokio::test]
     async fn test_activate_wasm_tool_with_runtime_passes_runtime_check() {
         // When the ExtensionManager has a WASM runtime, activation should get
diff --git a/src/main.rs b/src/main.rs
index 5102732e48a..066659fda13 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -342,8 +342,12 @@ async fn async_main() -> anyhow::Result<()> {
 
     // Initialize tracing with a reloadable EnvFilter so the gateway can switch
     // log levels at runtime without restarting.
-    let log_level_handle =
-        ironclaw::channels::web::log_layer::init_tracing(Arc::clone(&log_broadcaster));
+    let suppress_stderr =
+        config.channels.tui.is_some() && cli.message.is_none() && cfg!(feature = "tui");
+    let log_level_handle = ironclaw::channels::web::log_layer::init_tracing(
+        Arc::clone(&log_broadcaster),
+        suppress_stderr,
+    );
 
     tracing::debug!("Starting IronClaw...");
     tracing::debug!("Loaded configuration for agent: {}", config.agent.name);
@@ -409,13 +413,128 @@ async fn async_main() -> anyhow::Result<()> {
         Arc<WasmChannelRouter>,
     )> = None;
 
-    // Create CLI channel
+    // Create CLI channel (REPL or TUI — mutually exclusive, both claim stdin)
+    let tui_mode = config.channels.tui.is_some();
+
+    #[cfg(feature = "tui")]
+    if tui_mode && cli.message.is_none() {
+        let tool_names = components.tools.list().await;
+        let tool_categories = ironclaw::channels::tui::group_tools_by_prefix(tool_names);
+
+        let skill_categories = if let Some(ref registry) = components.skill_registry {
+            let registry = registry.read().unwrap_or_else(|e| e.into_inner());
+            let skill_data: Vec<(String, Vec<String>)> = registry
+                .skills()
+                .iter()
+                .map(|s| (s.manifest.name.clone(), s.manifest.activation.tags.clone()))
+                .collect();
+            ironclaw::channels::tui::group_skills_by_tag(&skill_data)
+        } else {
+            Vec::new()
+        };
+
+        let workspace_root = std::env::current_dir().unwrap_or_else(|_| std::path::PathBuf::new());
+        let workspace_path = workspace_root.display().to_string();
+        let layout = if let Some(ref tui_config) = config.channels.tui {
+            ironclaw::channels::tui::resolve_tui_layout(tui_config, &workspace_root)
+        } else {
+            ironclaw_tui::TuiLayout::default()
+        };
+
+        let (memory_count, identity_files) = if let Some(ref ws) = components.workspace {
+            let count = ws.list_all().await.map(|docs| docs.len()).unwrap_or(0);
+            let identity_names = ["AGENTS.md", "SOUL.md", "USER.md", "IDENTITY.md"];
+            let mut found = Vec::new();
+            for name in &identity_names {
+                if ws.read(name).await.is_ok() {
+                    found.push((*name).to_string());
+                }
+            }
+            (count, found)
+        } else {
+            (0, Vec::new())
+        };
+
+        let current_model = components.llm.model_name().to_string();
+        let context_window =
+            match tokio::time::timeout(Duration::from_secs(5), components.llm.model_metadata())
+                .await
+            {
+                Ok(Ok(metadata)) => metadata.context_length.map(u64::from),
+                Ok(Err(e)) => {
+                    tracing::debug!(
+                        "TUI context metadata unavailable: could not fetch model metadata: {}",
+                        e
+                    );
+                    None
+                }
+                Err(_) => {
+                    tracing::debug!("TUI context metadata unavailable: model metadata timed out");
+                    None
+                }
+            };
+        let available_models = match tokio::time::timeout(
+            Duration::from_secs(5),
+            components.llm.list_models(),
+        )
+        .await
+        {
+            Ok(Ok(mut models)) if !models.is_empty() => {
+                if let Some(pos) = models.iter().position(|m| m == &current_model) {
+                    if pos != 0 {
+                        let current = models.remove(pos);
+                        models.insert(0, current);
+                    }
+                } else {
+                    models.insert(0, current_model.clone());
+                }
+                models
+            }
+            Ok(Ok(_)) => Vec::new(),
+            Ok(Err(e)) => {
+                tracing::debug!("TUI model picker unavailable: could not list models: {}", e);
+                Vec::new()
+            }
+            Err(_) => {
+                tracing::debug!("TUI model picker unavailable: model discovery timed out");
+                Vec::new()
+            }
+        };
+
+        let tui_channel = ironclaw::channels::TuiChannel::new(
+            config.owner_id.clone(),
+            env!("CARGO_PKG_VERSION"),
+            current_model,
+        )
+        .with_context_window(context_window.unwrap_or(128_000))
+        .with_layout(layout)
+        .with_log_broadcaster(Arc::clone(&log_broadcaster))
+        .with_tools(tool_categories)
+        .with_skills(skill_categories)
+        .with_workspace_path(workspace_path)
+        .with_memory_count(memory_count)
+        .with_identity_files(identity_files)
+        .with_available_models(available_models);
+
+        channels.add(Box::new(tui_channel)).await;
+        channel_names.push("tui".to_string());
+        tracing::debug!("TUI mode enabled");
+    }
+
+    #[cfg(not(feature = "tui"))]
+    if tui_mode {
+        tracing::warn!(
+            "CLI_MODE=tui requested but the 'tui' feature is not enabled. Falling back to REPL."
+        );
+    }
+
+    let use_repl = !tui_mode || cfg!(not(feature = "tui"));
     let repl_channel = if let Some(ref msg) = cli.message {
         Some(ReplChannel::with_message_for_user(
             config.owner_id.clone(),
             msg.clone(),
         ))
-    } else if config.channels.cli.enabled {
+    } else if use_repl && config.channels.cli.enabled {
         let repl = ReplChannel::with_user_id(config.owner_id.clone());
         repl.suppress_banner();
         Some(repl)
diff --git a/src/tools/builtin/skill_tools.rs b/src/tools/builtin/skill_tools.rs
index 13de7bb8625..0a3d0099517 100644
--- a/src/tools/builtin/skill_tools.rs
+++ b/src/tools/builtin/skill_tools.rs
@@ -11,7 +11,9 @@ use crate::context::JobContext;
 use crate::tools::tool::{
     ApprovalRequirement, EngineCompatibility, Tool, ToolError, ToolOutput, require_str,
 };
-use ironclaw_skills::catalog::SkillCatalog;
+use ironclaw_skills::catalog::{
+    SkillCatalog, catalog_entry_is_installed, resolve_catalog_slug_for_name,
+};
 use ironclaw_skills::registry::SkillRegistry;
 
 // ── skill_list ──────────────────────────────────────────────────────────
@@ -183,10 +185,8 @@ impl Tool for SkillSearchTool {
         let catalog_json: Vec<serde_json::Value> = catalog_entries
             .iter()
             .map(|entry| {
-                let is_installed = installed_names.iter().any(|n| {
-                    // Match by slug suffix or exact name
-                    entry.slug.ends_with(n.as_str()) || entry.name == *n
-                });
+                let is_installed =
+                    catalog_entry_is_installed(&entry.slug, &entry.name, &installed_names);
                 serde_json::json!({
                     "slug": entry.slug,
                     "name": entry.name,
@@ -261,6 +261,35 @@ impl SkillInstallTool {
     }
 }
 
+async fn resolve_catalog_download_key(
+    catalog: &SkillCatalog,
+    name: &str,
+    slug: Option<&str>,
+) -> Result<String, ToolError> {
+    if let Some(slug) = slug.filter(|s| !s.is_empty()) {
+        return Ok(slug.to_string());
+    }
+
+    if name.contains('/') {
+        return Ok(name.to_string());
+    }
+
+    let outcome = catalog.search(name).await;
+    match resolve_catalog_slug_for_name(name, &outcome.results) {
+        Ok(Some(resolved)) => Ok(resolved),
+        Ok(None) => {
+            let reason = outcome
+                .error
+                .unwrap_or_else(|| "no unique catalog match was found".to_string());
+            Err(ToolError::ExecutionFailed(format!(
+                "Could not resolve skill name '{}' to a catalog slug: {}",
+                name, reason
+            )))
+        }
+        Err(e) => Err(ToolError::ExecutionFailed(e.to_string())),
+    }
+}
+
 #[async_trait]
 impl Tool for SkillInstallTool {
     fn name(&self) -> &str {
@@ -279,6 +308,10 @@ impl Tool for SkillInstallTool {
                     "type": "string",
                     "description": "Skill name or slug (from search results)"
                 },
+                "slug": {
+                    "type": "string",
+                    "description": "Registry slug from catalog search results; preferred when installing from ClawHub"
+                },
                 "url": {
                     "type": "string",
                     "description": "Direct URL to a SKILL.md file"
@@ -299,6 +332,11 @@ impl Tool for SkillInstallTool {
     ) -> Result<ToolOutput, ToolError> {
         let start = std::time::Instant::now();
         let name = require_str(&params, "name")?;
+        let mut requested_identifier = params
+            .get("slug")
+            .and_then(|v| v.as_str())
+            .filter(|s| !s.is_empty())
+            .map(str::to_string);
 
         let content = if let Some(raw) = params.get("content").and_then(|v| v.as_str()) {
             // Direct content provided
@@ -312,23 +350,35 @@ impl Tool for SkillInstallTool {
             fetch_skill_content(url).await?
         } else {
             // Look up in catalog and fetch
-            let download_url =
-                ironclaw_skills::catalog::skill_download_url(self.catalog.registry_url(), name);
+            let download_key = resolve_catalog_download_key(
+                self.catalog.as_ref(),
+                name,
+                requested_identifier.as_deref(),
+            )
+            .await?;
+            requested_identifier = Some(download_key.clone());
+            let download_url = ironclaw_skills::catalog::skill_download_url(
+                self.catalog.registry_url(),
+                &download_key,
+            );
             fetch_skill_content(&download_url).await?
         };
 
+        let normalized = ironclaw_skills::normalize_line_endings(&content);
+
         // Check for duplicates and get install_dir under a brief read lock.
-        let (user_dir, skill_name_from_parse) = {
+        let (user_dir, skill_name_from_parse, install_content) = {
             let guard = self
                 .registry
                 .read()
                 .map_err(|e| ToolError::ExecutionFailed(format!("Lock poisoned: {}", e)))?;
 
-            // Parse to extract the name (cheap, in-memory)
-            let normalized = ironclaw_skills::normalize_line_endings(&content);
-            let parsed = ironclaw_skills::parser::parse_skill_md(&normalized)
+            let (skill_name, install_content) =
+                ironclaw_skills::registry::SkillRegistry::resolve_install_content(
+                    &normalized,
+                    requested_identifier.as_deref(),
+                )
                 .map_err(|e| ToolError::ExecutionFailed(e.to_string()))?;
-            let skill_name = parsed.manifest.name.clone();
 
             if guard.has(&skill_name) {
                 return Err(ToolError::ExecutionFailed(format!(
@@ -337,7 +387,11 @@ impl Tool for SkillInstallTool {
                 )));
             }
 
-            (guard.install_target_dir().to_path_buf(), skill_name)
+            (
+                guard.install_target_dir().to_path_buf(),
+                skill_name,
+                install_content,
+            )
         };
 
         // Perform async I/O (write to disk, validate round-trip) with no lock held.
@@ -345,7 +399,7 @@ impl Tool for SkillInstallTool {
             ironclaw_skills::registry::SkillRegistry::prepare_install_to_disk(
                 &user_dir,
                 &skill_name_from_parse,
-                &ironclaw_skills::normalize_line_endings(&content),
+                &install_content,
             )
             .await
             .map_err(|e| ToolError::ExecutionFailed(e.to_string()))?;
@@ -837,10 +891,72 @@ mod tests {
         );
         let schema = tool.parameters_schema();
         assert!(schema["properties"].get("name").is_some());
+        assert!(schema["properties"].get("slug").is_some());
         assert!(schema["properties"].get("url").is_some());
         assert!(schema["properties"].get("content").is_some());
     }
 
+    #[test]
+    fn test_find_catalog_slug_for_display_name() {
+        let entries = vec![ironclaw_skills::catalog::CatalogEntry {
+            slug: "finance/mortgage-calculator".to_string(),
+            name: "Mortgage Calculator".to_string(),
+            description: String::new(),
+            version: String::new(),
+            score: 1.0,
+            updated_at: None,
+            stars: None,
+            downloads: None,
+            installs_current: None,
+            owner: None,
+        }];
+
+        assert_eq!(
+            resolve_catalog_slug_for_name("Mortgage Calculator", &entries)
+                .unwrap()
+                .as_deref(),
+            Some("finance/mortgage-calculator")
+        );
+        assert_eq!(
+            resolve_catalog_slug_for_name("mortgage-calculator", &entries)
+                .unwrap()
+                .as_deref(),
+            Some("finance/mortgage-calculator")
+        );
+    }
+
+    #[test]
+    fn test_resolve_catalog_slug_for_display_name_is_ambiguous() {
+        let entries = vec![
+            ironclaw_skills::catalog::CatalogEntry {
+                slug: "alice/mortgage-calculator".to_string(),
+                name: "Mortgage Calculator".to_string(),
+                description: String::new(),
+                version: String::new(),
+                score: 1.0,
+                updated_at: None,
+                stars: None,
+                downloads: None,
+                installs_current: None,
+                owner: None,
+            },
+            ironclaw_skills::catalog::CatalogEntry {
+                slug: "bob/mortgage-calculator".to_string(),
+                name: "Mortgage Calculator".to_string(),
+                description: String::new(),
+                version: String::new(),
+                score: 0.9,
+                updated_at: None,
+                stars: None,
+                downloads: None,
+                installs_current: None,
+                owner: None,
+            },
+        ];
+
+        assert!(resolve_catalog_slug_for_name("Mortgage Calculator", &entries).is_err());
+    }
+
     #[test]
     fn test_skill_remove_schema() {
         use crate::tools::tool::ApprovalRequirement;
diff --git a/src/tunnel/mod.rs b/src/tunnel/mod.rs
index c42bd91e252..473a17ba9fc 100644
--- a/src/tunnel/mod.rs
+++ b/src/tunnel/mod.rs
@@ -410,6 +410,7 @@ mod tests {
             http: None,
             gateway: None,
             signal: None,
+            tui: None,
             wasm_channels_dir: std::env::temp_dir().join("ironclaw-test-channels"),
             wasm_channels_enabled: false,
             wasm_channel_owner_ids: std::collections::HashMap::new(),
diff --git a/src/workspace/document.rs b/src/workspace/document.rs
index 93a12215221..88c961d14da 100644
--- a/src/workspace/document.rs
+++ b/src/workspace/document.rs
@@ -32,6 +32,8 @@ pub mod paths {
     pub const TOOLS: &str = "TOOLS.md";
     /// First-run ritual file; self-deletes after onboarding completes.
     pub const BOOTSTRAP: &str = "BOOTSTRAP.md";
+    /// Admin-defined system instructions shared with all users.
+    pub const SYSTEM: &str = "SYSTEM.md";
     /// User psychographic profile (JSON).
     pub const PROFILE: &str = "context/profile.json";
     /// Assistant behavioral directives (derived from profile).
@@ -45,6 +47,31 @@ pub mod paths {
 /// `hygiene` settings). Individual document metadata overrides folder defaults.
 pub const CONFIG_FILE_NAME: &str = ".config";
 
+/// Well-known scope identifier for admin-defined content (e.g., system prompt).
+///
+/// Documents stored under this scope are readable by all workspaces when
+/// `admin_prompt_enabled` is set (multi-tenant mode). The double-underscore
+/// prefix prevents collision with real user IDs.
+pub const ADMIN_SCOPE: &str = "__admin__";
+
+/// Check if a scope identifier is reserved for system use.
+///
+/// Reserved scopes must never be assigned as a user ID. The check is
+/// case-insensitive and ignores leading/trailing whitespace, and the entire
+/// `__*__` namespace is reserved so future system scopes added alongside
+/// `__admin__` cannot be impersonated by hand-crafted user IDs.
+pub fn is_reserved_scope(scope: &str) -> bool {
+    let trimmed = scope.trim();
+    if trimmed.is_empty() {
+        return false;
+    }
+    if trimmed.eq_ignore_ascii_case(ADMIN_SCOPE) {
+        return true;
+    }
+    // Reserve the whole `__*__` namespace for system scopes.
+    trimmed.starts_with("__") && trimmed.ends_with("__") && trimmed.len() >= 4
+}
+
 /// Typed overlay for the `metadata` JSON field on [`MemoryDocument`].
 ///
 /// Fields use `Option` so that only explicitly set flags participate in
@@ -401,6 +428,24 @@ mod tests {
         assert_eq!(doc.word_count(), 6);
     }
 
+    #[test]
+    fn test_is_reserved_scope() {
+        assert!(is_reserved_scope("__admin__"));
+        assert!(!is_reserved_scope("alice"));
+        assert!(!is_reserved_scope(""));
+        assert!(!is_reserved_scope("admin"));
+        assert!(!is_reserved_scope("550e8400-e29b-41d4-a716-446655440000"));
+        // Case-insensitive and whitespace-tolerant.
+        assert!(is_reserved_scope("__Admin__"));
+        assert!(is_reserved_scope("  __admin__\n"));
+        // Whole `__*__` namespace is reserved.
+        assert!(is_reserved_scope("__system__"));
+        assert!(is_reserved_scope("__internal__"));
+        // Non-`__*__` strings remain unreserved.
+        assert!(!is_reserved_scope("__only_one_underscore"));
+        assert!(!is_reserved_scope("trailing_only__"));
+    }
+
     #[test]
     fn test_is_identity_document() {
         let identity = MemoryDocument::new("user1", None, paths::IDENTITY);
diff --git a/src/workspace/mod.rs b/src/workspace/mod.rs
index 5c617f98d06..6bc36e3c60a 100644
--- a/src/workspace/mod.rs
+++ b/src/workspace/mod.rs
@@ -53,9 +53,10 @@ mod search;
 
 pub use chunker::{ChunkConfig, chunk_document};
 pub use document::{
-    CONFIG_FILE_NAME, DocumentMetadata, DocumentVersion, HygieneMetadata, IDENTITY_PATHS,
-    MemoryChunk, MemoryDocument, PatchResult, VersionSummary, WorkspaceEntry, content_sha256,
-    is_config_path, is_identity_path, merge_workspace_entries, paths,
+    ADMIN_SCOPE, CONFIG_FILE_NAME, DocumentMetadata, DocumentVersion, HygieneMetadata,
+    IDENTITY_PATHS, MemoryChunk, MemoryDocument, PatchResult, VersionSummary, WorkspaceEntry,
+    content_sha256, is_config_path, is_identity_path, is_reserved_scope, merge_workspace_entries,
+    paths,
 };
 pub use embedding_cache::{CachedEmbeddingProvider, EmbeddingCacheConfig};
 #[cfg(feature = "bedrock")]
@@ -97,6 +98,7 @@ const SYSTEM_PROMPT_FILES: &[&str] = &[
     paths::AGENTS,
     paths::USER,
     paths::IDENTITY,
+    paths::SYSTEM,
     paths::MEMORY,
     paths::TOOLS,
     paths::HEARTBEAT,
@@ -550,6 +552,13 @@ pub struct Workspace {
     /// Optional privacy classifier for shared layer writes.
     /// When None, writes go exactly where requested — no silent redirect.
     privacy_classifier: Option<Arc<dyn crate::workspace::privacy::PrivacyClassifier>>,
+    /// When true, the system prompt includes admin-defined instructions from
+    /// the `__admin__` scope. Set by `WorkspacePool` in multi-tenant mode.
+    admin_prompt_enabled: bool,
+    /// Shared cache for the admin system prompt. When `Some`, the workspace
+    /// reads from this cache instead of hitting the database on every turn.
+    /// Populated by `WorkspacePool` in multi-tenant mode.
+    admin_prompt_cache: Option<Arc<tokio::sync::RwLock<Option<String>>>>,
 }
 
 impl Workspace {
@@ -569,6 +578,8 @@ impl Workspace {
             search_defaults: SearchConfig::default(),
             memory_layers,
             privacy_classifier: None,
+            admin_prompt_enabled: false,
+            admin_prompt_cache: None,
         }
     }
 
@@ -589,6 +600,8 @@ impl Workspace {
             search_defaults: SearchConfig::default(),
             memory_layers,
             privacy_classifier: None,
+            admin_prompt_enabled: false,
+            admin_prompt_cache: None,
         }
     }
 
@@ -687,6 +700,25 @@ impl Workspace {
         self
     }
 
+    /// Enable admin system prompt reading from the `__admin__` scope.
+    ///
+    /// When enabled, `system_prompt_for_context_inner()` reads `SYSTEM.md`
+    /// from the `__admin__` scope and injects it before identity files.
+    /// Only set in multi-tenant mode (via `WorkspacePool`).
+    pub fn with_admin_prompt(mut self) -> Self {
+        self.admin_prompt_enabled = true;
+        self
+    }
+
+    /// Set the shared admin prompt cache (from `WorkspacePool`).
+    pub fn with_admin_prompt_cache(
+        mut self,
+        cache: Arc<tokio::sync::RwLock<Option<String>>>,
+    ) -> Self {
+        self.admin_prompt_cache = Some(cache);
+        self
+    }
+
     /// Get the configured memory layers.
     pub fn memory_layers(&self) -> &[crate::workspace::layer::MemoryLayer] {
         &self.memory_layers
@@ -759,6 +791,8 @@ impl Workspace {
             search_defaults: self.search_defaults.clone(),
             memory_layers,
             privacy_classifier: self.privacy_classifier.clone(),
+            admin_prompt_enabled: self.admin_prompt_enabled,
+            admin_prompt_cache: self.admin_prompt_cache.clone(),
         }
     }
 
@@ -1573,6 +1607,48 @@ impl Workspace {
     }
 
     /// Inner implementation for system prompt building.
+    /// Read the admin system prompt, using the shared cache if available.
+    ///
+    /// Returns `None` if no admin prompt has been set, the document is empty,
+    /// or a non-recoverable error occurred. Only `DocumentNotFound` is silent;
+    /// other errors are logged at `debug!`.
+    async fn read_admin_prompt(&self) -> Option<String> {
+        // Fast path: check shared cache.
+        if let Some(ref cache) = self.admin_prompt_cache {
+            let guard = cache.read().await;
+            if let Some(ref content) = *guard {
+                return if content.is_empty() {
+                    None
+                } else {
+                    Some(content.clone())
+                };
+            }
+        }
+
+        // Slow path: DB read.
+        let result = match self
+            .storage
+            .get_document_by_path(ADMIN_SCOPE, None, paths::SYSTEM)
+            .await
+        {
+            Ok(doc) if !doc.content.is_empty() => Some(doc.content),
+            Ok(_) => None,
+            Err(WorkspaceError::DocumentNotFound { .. }) => None,
+            Err(e) => {
+                tracing::debug!("Failed to read admin system prompt: {}", e);
+                return None; // Don't cache errors
+            }
+        };
+
+        // Populate cache.
+        if let Some(ref cache) = self.admin_prompt_cache {
+            let mut guard = cache.write().await;
+            *guard = Some(result.clone().unwrap_or_default());
+        }
+
+        result
+    }
+
     async fn system_prompt_for_context_inner(
         &self,
         is_group_chat: bool,
@@ -1619,6 +1695,15 @@ impl Workspace {
             false
         };
 
+        // Admin system prompt: shared instructions set by an admin.
+        // Only read in multi-tenant mode (admin_prompt_enabled is set by WorkspacePool).
+        // Uses read_admin_prompt() which checks the shared cache first.
+        if self.admin_prompt_enabled
+            && let Some(content) = self.read_admin_prompt().await
+        {
+            parts.push(format!("## System Instructions\n\n{}", content));
+        }
+
         // Load identity files in order of importance.
         // These MUST use read_primary() — see comment above.
         let identity_files = [
@@ -2469,6 +2554,18 @@ mod tests {
 
     // ── Injection scanning tests ─────────────────────────────────────
 
+    #[test]
+    fn test_system_md_is_system_prompt_file_but_not_identity() {
+        assert!(
+            is_system_prompt_file(paths::SYSTEM),
+            "SYSTEM.md should be scanned for injection"
+        );
+        assert!(
+            !is_identity_path(paths::SYSTEM),
+            "SYSTEM.md must NOT be an identity path — it is shared, not per-user"
+        );
+    }
+
     #[test]
     fn test_system_prompt_file_matching() {
         let cases = vec![
@@ -2476,6 +2573,7 @@ mod tests {
             ("AGENTS.md", true),
             ("USER.md", true),
             ("IDENTITY.md", true),
+            ("SYSTEM.md", true),
             ("MEMORY.md", true),
             ("HEARTBEAT.md", true),
             ("TOOLS.md", true),
diff --git a/tests/admin_system_prompt.rs b/tests/admin_system_prompt.rs
new file mode 100644
index 00000000000..dca9a8a1e06
--- /dev/null
+++ b/tests/admin_system_prompt.rs
@@ -0,0 +1,413 @@
+//! Tests for admin system prompt (SYSTEM.md in __admin__ scope).
+//!
+//! When an admin writes SYSTEM.md to the __admin__ scope, all users with
+//! `admin_prompt_enabled` set (multi-tenant mode) should see those
+//! instructions in their system prompt.
+//!
+//! These tests verify that:
+//! 1. Admin system prompt appears in all users' system prompts
+//! 2. No admin prompt when admin_prompt_enabled is false (single-user mode)
+//! 3. Admin prompt does not interfere with per-user identity files
+//! 4. Empty SYSTEM.md produces no section in the system prompt
+#![cfg(feature = "libsql")]
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use ironclaw::channels::web::auth::{MultiAuthState, UserIdentity};
+use ironclaw::channels::web::test_helpers::TestGatewayBuilder;
+use ironclaw::db::Database;
+use ironclaw::db::libsql::LibSqlBackend;
+use ironclaw::workspace::{ADMIN_SCOPE, Workspace, paths};
+
+async fn setup() -> (Arc<dyn Database>, tempfile::TempDir) {
+    let dir = tempfile::tempdir().expect("create temp dir");
+    let db_path = dir.path().join("test.db");
+    let backend = LibSqlBackend::new_local(&db_path).await.expect("create db");
+    backend.run_migrations().await.expect("run migrations");
+    let db: Arc<dyn Database> = Arc::new(backend);
+    (db, dir)
+}
+
+/// Seed a document into a specific user's workspace scope.
+async fn seed(db: &Arc<dyn Database>, user_id: &str, path: &str, content: &str) {
+    let ws = Workspace::new_with_db(user_id, db.clone());
+    ws.write(path, content)
+        .await
+        .unwrap_or_else(|e| panic!("Failed to seed {path} for {user_id}: {e}"));
+}
+
+// ─── Test 1: Admin system prompt appears for all users ───────────────────
+
+#[tokio::test]
+async fn admin_system_prompt_appears_in_user_prompt() {
+    let (db, _dir) = setup().await;
+
+    // Admin writes SYSTEM.md to __admin__ scope
+    seed(
+        &db,
+        ADMIN_SCOPE,
+        paths::SYSTEM,
+        "This is a custom AI assistant for Acme Corp. Always be professional.",
+    )
+    .await;
+
+    // Create Alice's workspace with admin prompt enabled (multi-tenant mode)
+    let ws = Workspace::new_with_db("alice", db.clone()).with_admin_prompt();
+
+    let prompt = ws
+        .system_prompt_for_context(false)
+        .await
+        .expect("system_prompt_for_context failed");
+
+    assert!(
+        prompt.contains("Acme Corp"),
+        "Admin system prompt should appear in user's system prompt.\nPrompt:\n{prompt}"
+    );
+    assert!(
+        prompt.contains("## System Instructions"),
+        "Admin system prompt should be under '## System Instructions' header.\nPrompt:\n{prompt}"
+    );
+}
+
+// ─── Test 2: Admin system prompt is NOT shown in single-user mode ────────
+
+#[tokio::test]
+async fn admin_system_prompt_hidden_in_single_user_mode() {
+    let (db, _dir) = setup().await;
+
+    // Admin writes SYSTEM.md to __admin__ scope
+    seed(
+        &db,
+        ADMIN_SCOPE,
+        paths::SYSTEM,
+        "This is a custom AI assistant for Acme Corp.",
+    )
+    .await;
+
+    // Create workspace WITHOUT admin prompt enabled (single-user mode)
+    let ws = Workspace::new_with_db("alice", db.clone());
+
+    let prompt = ws
+        .system_prompt_for_context(false)
+        .await
+        .expect("system_prompt_for_context failed");
+
+    assert!(
+        !prompt.contains("Acme Corp"),
+        "Admin system prompt must NOT appear when admin_prompt_enabled is false.\nPrompt:\n{prompt}"
+    );
+}
+
+// ─── Test 3: Admin prompt does not interfere with per-user identity ──────
+
+#[tokio::test]
+async fn admin_prompt_coexists_with_user_identity() {
+    let (db, _dir) = setup().await;
+
+    // Admin writes SYSTEM.md
+    seed(
+        &db,
+        ADMIN_SCOPE,
+        paths::SYSTEM,
+        "All agents must follow Acme Corp policies.",
+    )
+    .await;
+
+    // Alice has her own identity files
+    seed(&db, "alice", paths::SOUL, "Alice is kind and creative.").await;
+    seed(
+        &db,
+        "alice",
+        paths::USER,
+        "You are talking to Alice, a designer.",
+    )
+    .await;
+
+    let ws = Workspace::new_with_db("alice", db.clone()).with_admin_prompt();
+
+    let prompt = ws
+        .system_prompt_for_context(false)
+        .await
+        .expect("system_prompt_for_context failed");
+
+    // Both admin prompt and user identity should be present
+    assert!(
+        prompt.contains("Acme Corp policies"),
+        "Admin system prompt should be present.\nPrompt:\n{prompt}"
+    );
+    assert!(
+        prompt.contains("Alice is kind and creative"),
+        "User's SOUL.md should still be present.\nPrompt:\n{prompt}"
+    );
+    assert!(
+        prompt.contains("Alice, a designer"),
+        "User's USER.md should still be present.\nPrompt:\n{prompt}"
+    );
+
+    // Admin prompt should come before identity files
+    let admin_pos = prompt
+        .find("Acme Corp policies")
+        .expect("admin prompt not found");
+    let identity_pos = prompt
+        .find("Alice is kind")
+        .expect("user identity not found");
+    assert!(
+        admin_pos < identity_pos,
+        "Admin system prompt should appear before user identity files.\n\
+         Admin position: {admin_pos}, Identity position: {identity_pos}"
+    );
+}
+
+// ─── Test 4: Empty SYSTEM.md produces no section ─────────────────────────
+
+#[tokio::test]
+async fn empty_system_prompt_produces_no_section() {
+    let (db, _dir) = setup().await;
+
+    // Admin writes empty SYSTEM.md
+    seed(&db, ADMIN_SCOPE, paths::SYSTEM, "").await;
+
+    let ws = Workspace::new_with_db("alice", db.clone()).with_admin_prompt();
+
+    let prompt = ws
+        .system_prompt_for_context(false)
+        .await
+        .expect("system_prompt_for_context failed");
+
+    assert!(
+        !prompt.contains("System Instructions"),
+        "Empty SYSTEM.md should not produce a section.\nPrompt:\n{prompt}"
+    );
+}
+
+// ─── Test 5: Multiple users see the same admin prompt ────────────────────
+
+#[tokio::test]
+async fn multiple_users_see_same_admin_prompt() {
+    let (db, _dir) = setup().await;
+
+    seed(
+        &db,
+        ADMIN_SCOPE,
+        paths::SYSTEM,
+        "Company-wide instruction: always greet users by name.",
+    )
+    .await;
+
+    // Seed different identity for each user
+    seed(&db, "alice", paths::SOUL, "Alice values creativity.").await;
+    seed(&db, "bob", paths::SOUL, "Bob values precision.").await;
+
+    let alice_ws = Workspace::new_with_db("alice", db.clone()).with_admin_prompt();
+    let bob_ws = Workspace::new_with_db("bob", db.clone()).with_admin_prompt();
+
+    let alice_prompt = alice_ws
+        .system_prompt_for_context(false)
+        .await
+        .expect("alice prompt");
+    let bob_prompt = bob_ws
+        .system_prompt_for_context(false)
+        .await
+        .expect("bob prompt");
+
+    // Both see the admin prompt
+    assert!(
+        alice_prompt.contains("greet users by name"),
+        "Alice should see admin prompt.\nPrompt:\n{alice_prompt}"
+    );
+    assert!(
+        bob_prompt.contains("greet users by name"),
+        "Bob should see admin prompt.\nPrompt:\n{bob_prompt}"
+    );
+
+    // Each sees their own identity
+    assert!(
+        alice_prompt.contains("Alice values creativity"),
+        "Alice should see her own identity.\nPrompt:\n{alice_prompt}"
+    );
+    assert!(
+        !alice_prompt.contains("Bob values precision"),
+        "Alice should NOT see Bob's identity.\nPrompt:\n{alice_prompt}"
+    );
+    assert!(
+        bob_prompt.contains("Bob values precision"),
+        "Bob should see his own identity.\nPrompt:\n{bob_prompt}"
+    );
+}
+
+// ─── Test 6: scoped_to_user preserves admin_prompt_enabled ───────────────
+
+#[tokio::test]
+async fn scoped_to_user_preserves_admin_prompt() {
+    let (db, _dir) = setup().await;
+
+    seed(
+        &db,
+        ADMIN_SCOPE,
+        paths::SYSTEM,
+        "Admin prompt: use formal language.",
+    )
+    .await;
+    seed(&db, "bob", paths::SOUL, "Bob is analytical.").await;
+
+    // Create workspace for alice with admin prompt, then scope to bob
+    let alice_ws = Workspace::new_with_db("alice", db.clone()).with_admin_prompt();
+    let bob_ws = alice_ws.scoped_to_user("bob");
+
+    let prompt = bob_ws
+        .system_prompt_for_context(false)
+        .await
+        .expect("system_prompt_for_context failed");
+
+    assert!(
+        prompt.contains("use formal language"),
+        "scoped_to_user should preserve admin_prompt_enabled.\nPrompt:\n{prompt}"
+    );
+    assert!(
+        prompt.contains("Bob is analytical"),
+        "Scoped workspace should read Bob's identity.\nPrompt:\n{prompt}"
+    );
+}
+
+// ─── Test 7: PUT rejects system prompt exceeding 64 KB ────────────────
+
+#[tokio::test]
+async fn put_rejects_oversized_system_prompt() {
+    let mut tokens = HashMap::new();
+    tokens.insert(
+        "tok-admin".to_string(),
+        UserIdentity {
+            user_id: "admin".to_string(),
+            role: "admin".to_string(),
+            workspace_read_scopes: vec![],
+        },
+    );
+    let auth = MultiAuthState::multi(tokens);
+
+    let (addr, _state) = TestGatewayBuilder::new()
+        .start_multi(auth)
+        .await
+        .expect("start test server");
+
+    // Build a payload that exceeds 64 KB.
+    let oversized_content = "x".repeat(64 * 1024 + 1);
+    let body = serde_json::json!({ "content": oversized_content });
+
+    let client = reqwest::Client::new();
+    let resp = client
+        .put(format!("http://{addr}/api/admin/system-prompt"))
+        .header("Authorization", "Bearer tok-admin")
+        .json(&body)
+        .send()
+        .await
+        .expect("send request");
+
+    assert_eq!(
+        resp.status().as_u16(),
+        413,
+        "Oversized system prompt should be rejected with 413 Payload Too Large"
+    );
+}
+
+// ─── Test 8: PUT accepts system prompt within 64 KB limit ─────────────
+
+#[tokio::test]
+async fn put_accepts_system_prompt_within_limit() {
+    let mut tokens = HashMap::new();
+    tokens.insert(
+        "tok-admin".to_string(),
+        UserIdentity {
+            user_id: "admin".to_string(),
+            role: "admin".to_string(),
+            workspace_read_scopes: vec![],
+        },
+    );
+    let auth = MultiAuthState::multi(tokens);
+
+    let (addr, _state) = TestGatewayBuilder::new()
+        .start_multi(auth)
+        .await
+        .expect("start test server");
+
+    // A payload exactly at the limit should NOT be rejected as too large.
+    // (It will fail with 404 since workspace_pool is None, but not 413.)
+    let content = "x".repeat(64 * 1024);
+    let body = serde_json::json!({ "content": content });
+
+    let client = reqwest::Client::new();
+    let resp = client
+        .put(format!("http://{addr}/api/admin/system-prompt"))
+        .header("Authorization", "Bearer tok-admin")
+        .json(&body)
+        .send()
+        .await
+        .expect("send request");
+
+    assert_ne!(
+        resp.status().as_u16(),
+        413,
+        "System prompt at exactly 64 KB should not be rejected as too large"
+    );
+}
+
+// ─── Test 9: Admin prompt cache is used and invalidation works ────────
+
+#[tokio::test]
+async fn admin_prompt_cache_invalidation() {
+    let (db, _dir) = setup().await;
+
+    // Create a shared cache (simulating what WorkspacePool provides).
+    let cache = Arc::new(tokio::sync::RwLock::new(None));
+
+    let ws = Workspace::new_with_db("alice", Arc::clone(&db))
+        .with_admin_prompt()
+        .with_admin_prompt_cache(Arc::clone(&cache));
+
+    // No admin prompt initially — cache should be populated with empty.
+    let prompt = ws.system_prompt_for_context(false).await.unwrap();
+    assert!(
+        !prompt.contains("System Instructions"),
+        "No admin prompt should be present initially"
+    );
+    {
+        let guard = cache.read().await;
+        assert!(
+            guard.is_some(),
+            "Cache should be populated after first read"
+        );
+    }
+
+    // Seed admin system prompt.
+    seed(&db, ADMIN_SCOPE, paths::SYSTEM, "Be helpful and kind.").await;
+
+    // Without invalidation, the cached empty value is served.
+    let prompt = ws.system_prompt_for_context(false).await.unwrap();
+    assert!(
+        !prompt.contains("Be helpful"),
+        "Stale cache should still serve old (empty) value"
+    );
+
+    // Invalidate the cache.
+    {
+        let mut guard = cache.write().await;
+        *guard = None;
+    }
+
+    // After invalidation, the new admin prompt should appear.
+    let prompt = ws.system_prompt_for_context(false).await.unwrap();
+    assert!(
+        prompt.contains("Be helpful and kind"),
+        "After cache invalidation, new admin prompt should appear.\nPrompt:\n{prompt}"
+    );
+
+    // Cache should now hold the new value.
+    {
+        let guard = cache.read().await;
+        assert_eq!(
+            guard.as_deref(),
+            Some("Be helpful and kind."),
+            "Cache should hold the new admin prompt content"
+        );
+    }
+}
diff --git a/tests/e2e/conftest.py b/tests/e2e/conftest.py
index 59ef8984a37..5f656d9daa9 100644
--- a/tests/e2e/conftest.py
+++ b/tests/e2e/conftest.py
@@ -5,6 +5,7 @@
 """
 
 import asyncio
+import json
 import os
 import signal
 import socket
@@ -1142,6 +1143,100 @@ async def length_preserving_page(length_preserving_server, browser):
     yield pg
     await context.close()
 
+# ---------------------------------------------------------------------------
+# Slack E2E fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(scope="session")
+async def fake_slack_server():
+    """Start the fake Slack API server for E2E tests."""
+    fake_api_path = Path(__file__).parent / "fake_slack_api.py"
+    proc = await asyncio.create_subprocess_exec(
+        sys.executable,
+        str(fake_api_path),
+        "--port",
+        "0",
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    port = await wait_for_port_line(proc, r"FAKE_SLACK_PORT=(\d+)")
+    base_url = f"http://127.0.0.1:{port}"
+    await wait_for_ready(f"{base_url}/__mock/sent_messages", timeout=10)
+    yield base_url
+    proc.send_signal(signal.SIGINT)
+    try:
+        await asyncio.wait_for(proc.wait(), timeout=5)
+    except asyncio.TimeoutError:
+        proc.kill()
+
+
+@pytest.fixture(scope="session")
+async def slack_e2e_server(ironclaw_binary, mock_llm_server, fake_slack_server):
+    """IronClaw instance wired to the fake Slack API for E2E Slack tests."""
+    tmp = tempfile.mkdtemp(prefix="ic-slack-e2e-")
+    db_path = os.path.join(tmp, "slack_e2e.db")
+    home_dir = os.path.join(tmp, "home")
+    channels_dir = os.path.join(tmp, "channels")
+    os.makedirs(home_dir, exist_ok=True)
+    os.makedirs(channels_dir, exist_ok=True)
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.bind(("127.0.0.1", 0))
+    port = sock.getsockname()[1]
+    sock.close()
+
+    env = {
+        "GATEWAY_ENABLED": "true",
+        "GATEWAY_HOST": "127.0.0.1",
+        "GATEWAY_PORT": str(port),
+        "GATEWAY_AUTH_TOKEN": AUTH_TOKEN,
+        "GATEWAY_USER_ID": "e2e-tester",
+        "CLI_ENABLED": "false",
+        "LLM_BACKEND": "openai_compatible",
+        "LLM_BASE_URL": mock_llm_server,
+        "LLM_MODEL": "mock-model",
+        "DATABASE_BACKEND": "libsql",
+        "LIBSQL_PATH": db_path,
+        "HOME_DIR": home_dir,
+        "CHANNELS_DIR": channels_dir,
+        "SANDBOX_ENABLED": "false",
+        "ROUTINES_ENABLED": "false",
+        "HEARTBEAT_ENABLED": "false",
+        "EMBEDDING_ENABLED": "false",
+        "SKILLS_ENABLED": "false",
+        "ONBOARD_COMPLETED": "true",
+        "IRONCLAW_TEST_HTTP_REWRITE_MAP": json.dumps(
+            {
+                "slack.com": fake_slack_server,
+                "files.slack.com": fake_slack_server,
+            }
+        ),
+        "SECRETS_MASTER_KEY": "dGVzdC1zbGFjay1tYXN0ZXIta2V5LTMyYnl0ZXM=",
+        "PATH": os.environ.get("PATH", ""),
+    }
+
+    proc = await asyncio.create_subprocess_exec(
+        str(ironclaw_binary),
+        "--no-onboard",
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        env=env,
+    )
+
+    base_url = f"http://127.0.0.1:{port}"
+    http_url = f"{base_url}/webhook/slack"
+    await wait_for_ready(f"{base_url}/api/health", timeout=60)
+    yield {
+        "base_url": base_url,
+        "http_url": http_url,
+        "fake_slack_url": fake_slack_server,
+        "channels_dir": channels_dir,
+    }
+    proc.send_signal(signal.SIGINT)
+    try:
+        await asyncio.wait_for(proc.wait(), timeout=10)
+    except asyncio.TimeoutError:
+        proc.kill()
 
 # ── Telegram E2E fixtures ────────────────────────────────────────────────
 
diff --git a/tests/e2e/fake_slack_api.py b/tests/e2e/fake_slack_api.py
new file mode 100644
index 00000000000..38669d13115
--- /dev/null
+++ b/tests/e2e/fake_slack_api.py
@@ -0,0 +1,174 @@
+"""Fake Slack Web API server for E2E tests.
+
+Serves minimal Slack API endpoints so the IronClaw Slack WASM channel can be
+set up and exercised without a real Slack connection.
+
+Control endpoints (/__mock/*) let tests inspect sent messages, configure
+failure modes, and reset state between scenarios.
+"""
+
+import argparse
+import asyncio
+import json
+import time
+
+from aiohttp import web
+
+
+class FakeSlackState:
+    """Shared mutable state for the fake Slack API."""
+
+    def __init__(self):
+        self.reset()
+
+    def reset(self):
+        self.sent_messages: list[dict] = []
+        self.api_calls: list[dict] = []
+        self.rate_limit_count = 0
+        self.fail_post_message = False
+        self.fail_file_downloads = False
+
+
+# -- Slack API handlers ----------------------------------------------------
+
+
+async def chat_post_message(request: web.Request) -> web.Response:
+    state: FakeSlackState = request.app["state"]
+    body = await request.json()
+    state.api_calls.append(
+        {"method": "chat.postMessage", "body": body, "time": time.time()}
+    )
+
+    # Simulate Slack 429 rate limiting
+    if state.rate_limit_count > 0:
+        state.rate_limit_count -= 1
+        return web.json_response(
+            {"ok": False, "error": "rate_limited"},
+            status=429,
+            headers={"Retry-After": "1"},
+        )
+
+    # Simulate forced 500 errors
+    if state.fail_post_message:
+        return web.json_response(
+            {"ok": False, "error": "internal_error"},
+            status=500,
+        )
+
+    state.sent_messages.append(body)
+    ts = f"{time.time():.6f}"
+    return web.json_response(
+        {
+            "ok": True,
+            "channel": body.get("channel", "C0001"),
+            "ts": ts,
+            "message": {
+                "text": body.get("text", ""),
+                "ts": ts,
+                "type": "message",
+            },
+        }
+    )
+
+
+async def download_file(request: web.Request) -> web.Response:
+    """Serve fake file content for Slack file downloads."""
+    state: FakeSlackState = request.app["state"]
+    file_path = request.match_info.get("file_path", "unknown")
+    state.api_calls.append(
+        {"method": "file_download", "file_path": file_path, "time": time.time()}
+    )
+
+    if state.fail_file_downloads:
+        return web.Response(status=500, text="Internal Server Error")
+
+    return web.Response(
+        body=b"fake slack file content",
+        content_type="application/octet-stream",
+    )
+
+
+# -- Control endpoints -----------------------------------------------------
+
+
+async def mock_sent_messages(request: web.Request) -> web.Response:
+    state: FakeSlackState = request.app["state"]
+    return web.json_response({"messages": state.sent_messages})
+
+
+async def mock_api_calls(request: web.Request) -> web.Response:
+    state: FakeSlackState = request.app["state"]
+    return web.json_response({"calls": state.api_calls})
+
+
+async def mock_reset(request: web.Request) -> web.Response:
+    state: FakeSlackState = request.app["state"]
+    state.reset()
+    return web.json_response({"ok": True})
+
+
+async def mock_set_rate_limit(request: web.Request) -> web.Response:
+    state: FakeSlackState = request.app["state"]
+    body = await request.json()
+    state.rate_limit_count = int(body.get("count", 0))
+    return web.json_response({"ok": True, "rate_limit_count": state.rate_limit_count})
+
+
+async def mock_set_fail_post_message(request: web.Request) -> web.Response:
+    state: FakeSlackState = request.app["state"]
+    body = await request.json()
+    state.fail_post_message = bool(body.get("fail", False))
+    return web.json_response(
+        {"ok": True, "fail_post_message": state.fail_post_message}
+    )
+
+
+async def mock_set_fail_downloads(request: web.Request) -> web.Response:
+    state: FakeSlackState = request.app["state"]
+    body = await request.json()
+    state.fail_file_downloads = bool(body.get("fail", False))
+    return web.json_response(
+        {"ok": True, "fail_file_downloads": state.fail_file_downloads}
+    )
+
+
+# -- Server entry point ----------------------------------------------------
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=0)
+    args = parser.parse_args()
+
+    app = web.Application()
+    app["state"] = FakeSlackState()
+
+    # Slack Web API
+    app.router.add_post("/api/chat.postMessage", chat_post_message)
+
+    # File downloads (Slack serves files from files.slack.com/files-pri/...)
+    app.router.add_get("/files-pri/{file_path:.*}", download_file)
+    app.router.add_get("/files/{file_path:.*}", download_file)
+
+    # Control endpoints
+    app.router.add_get("/__mock/sent_messages", mock_sent_messages)
+    app.router.add_get("/__mock/api_calls", mock_api_calls)
+    app.router.add_post("/__mock/reset", mock_reset)
+    app.router.add_post("/__mock/set_rate_limit", mock_set_rate_limit)
+    app.router.add_post("/__mock/set_fail_post_message", mock_set_fail_post_message)
+    app.router.add_post("/__mock/set_fail_downloads", mock_set_fail_downloads)
+
+    async def start():
+        runner = web.AppRunner(app)
+        await runner.setup()
+        site = web.TCPSite(runner, "127.0.0.1", args.port)
+        await site.start()
+        port = site._server.sockets[0].getsockname()[1]
+        print(f"FAKE_SLACK_PORT={port}", flush=True)
+        await asyncio.Event().wait()
+
+    asyncio.run(start())
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/e2e/scenarios/test_slack_e2e.py b/tests/e2e/scenarios/test_slack_e2e.py
new file mode 100644
index 00000000000..326907bf9bc
--- /dev/null
+++ b/tests/e2e/scenarios/test_slack_e2e.py
@@ -0,0 +1,555 @@
+"""Full-process Slack E2E tests.
+
+Boot IronClaw -> activate Slack via setup API -> POST webhook events
+-> verify chat.postMessage round-trip through mock LLM to fake Slack API.
+"""
+
+import asyncio
+import hashlib
+import hmac
+import json
+import os
+import time
+
+import httpx
+
+from helpers import api_post, auth_headers
+
+# Bot token used throughout these tests.
+BOT_TOKEN = "xoxb-FAKE-SLACK-BOT-TOKEN"
+# Signing secret used for HMAC-SHA256 webhook verification.
+SIGNING_SECRET = "e2e-test-slack-signing-secret"
+# Owner user ID used in webhook events.
+OWNER_USER_ID = "U42OWNER"
+# Bot user ID (used to detect self-messages and strip mentions).
+BOT_USER_ID = "UBOTUSER"
+
+
+# -- helpers ---------------------------------------------------------------
+
+
+def compute_slack_signature(
+    signing_secret: str, timestamp: str, body_bytes: bytes
+) -> str:
+    """Compute Slack request signature: v0=HMAC-SHA256(v0:{ts}:{body})."""
+    sig_basestring = f"v0:{timestamp}:{body_bytes.decode('utf-8')}"
+    h = hmac.new(
+        signing_secret.encode("utf-8"),
+        sig_basestring.encode("utf-8"),
+        hashlib.sha256,
+    )
+    return f"v0={h.hexdigest()}"
+
+
+async def reset_fake_slack(fake_slack_url: str):
+    async with httpx.AsyncClient() as c:
+        await c.post(f"{fake_slack_url}/__mock/reset")
+
+
+async def install_slack(base_url: str):
+    """Install the bundled Slack WASM channel if not already installed."""
+    r = await api_post(
+        base_url,
+        "/api/extensions/install",
+        json={"name": "slack", "kind": "wasm_channel"},
+        timeout=180,
+    )
+    # 200 = freshly installed, 409 = already installed -- both are fine.
+    assert r.status_code in (200, 409), (
+        f"Slack install failed ({r.status_code}): {r.text}"
+    )
+
+
+def _patch_slack_capabilities_for_testing(channels_dir: str):
+    """Patch the installed capabilities file for E2E testing.
+
+    1. Add files.slack.com to HTTP allowlist for file download tests.
+    2. Add files.slack.com to credential host_patterns.
+    """
+    cap_path = os.path.join(channels_dir, "slack.capabilities.json")
+    assert os.path.exists(cap_path), (
+        f"Capabilities file not found at {cap_path}; "
+        f"files in dir: {os.listdir(channels_dir)}"
+    )
+    with open(cap_path, "r") as f:
+        caps = json.load(f)
+
+    # Ensure files.slack.com is in the HTTP allowlist
+    http_caps = caps.setdefault("capabilities", {}).setdefault("http", {})
+    allowlist = http_caps.setdefault("allowlist", [])
+    has_files_host = any(
+        e.get("host") == "files.slack.com" for e in allowlist
+    )
+    if not has_files_host:
+        allowlist.append({"host": "files.slack.com", "path_prefix": "/"})
+
+    # Ensure files.slack.com is in credential host_patterns
+    credentials = http_caps.setdefault("credentials", {})
+    slack_bot_cred = credentials.setdefault("slack_bot", {})
+    host_patterns = slack_bot_cred.setdefault("host_patterns", [])
+    if "files.slack.com" not in host_patterns:
+        host_patterns.append("files.slack.com")
+
+    with open(cap_path, "w") as f:
+        json.dump(caps, f, indent=2)
+
+
+async def activate_slack(
+    base_url: str, fake_slack_url: str, channels_dir: str
+) -> None:
+    """Install (if needed) and set up the Slack channel.
+
+    Slack setup is single-step (no verification flow like Telegram).
+    """
+    await reset_fake_slack(fake_slack_url)
+    await install_slack(base_url)
+
+    # Patch capabilities for testing
+    _patch_slack_capabilities_for_testing(channels_dir)
+
+    # Single setup call with bot token and signing secret
+    async with httpx.AsyncClient() as c:
+        r = await c.post(
+            f"{base_url}/api/extensions/slack/setup",
+            headers=auth_headers(),
+            json={
+                "secrets": {
+                    "slack_bot_token": BOT_TOKEN,
+                    "slack_signing_secret": SIGNING_SECRET,
+                },
+                "fields": {},
+            },
+            timeout=30,
+        )
+    r.raise_for_status()
+    body = r.json()
+    assert body.get("activated") or body.get("success"), (
+        f"Slack setup failed: {body}"
+    )
+
+
+def build_slack_dm_event(
+    user_id: str,
+    text: str,
+    *,
+    channel: str | None = None,
+    ts: str | None = None,
+    thread_ts: str | None = None,
+    files: list[dict] | None = None,
+    bot_id: str | None = None,
+    subtype: str | None = None,
+) -> dict:
+    """Build a Slack event_callback payload with a DM message event."""
+    if channel is None:
+        channel = f"D{user_id}"
+    if ts is None:
+        ts = f"{time.time():.6f}"
+
+    event = {
+        "type": "message",
+        "user": user_id,
+        "text": text,
+        "channel": channel,
+        "ts": ts,
+        "channel_type": "im",
+    }
+    if thread_ts is not None:
+        event["thread_ts"] = thread_ts
+    if files is not None:
+        event["files"] = files
+    if bot_id is not None:
+        event["bot_id"] = bot_id
+    if subtype is not None:
+        event["subtype"] = subtype
+
+    return {
+        "type": "event_callback",
+        "token": "fake-verification-token",
+        "team_id": "T0001",
+        "event": event,
+        "event_id": f"Ev{ts.replace('.', '')}",
+        "event_time": int(float(ts)),
+    }
+
+
+def build_slack_mention_event(
+    user_id: str,
+    text: str,
+    *,
+    channel: str = "C0001",
+    ts: str | None = None,
+) -> dict:
+    """Build a Slack event_callback payload with an app_mention event."""
+    if ts is None:
+        ts = f"{time.time():.6f}"
+
+    return {
+        "type": "event_callback",
+        "token": "fake-verification-token",
+        "team_id": "T0001",
+        "event": {
+            "type": "app_mention",
+            "user": user_id,
+            "text": text,
+            "channel": channel,
+            "ts": ts,
+        },
+        "event_id": f"Ev{ts.replace('.', '')}",
+        "event_time": int(float(ts)),
+    }
+
+
+async def post_slack_webhook(
+    http_url: str,
+    payload: dict,
+    *,
+    signing_secret: str | None = SIGNING_SECRET,
+) -> httpx.Response:
+    """POST a Slack event to IronClaw's webhook endpoint with HMAC signing."""
+    body_bytes = json.dumps(payload).encode("utf-8")
+    headers = {"Content-Type": "application/json"}
+
+    if signing_secret is not None:
+        timestamp = str(int(time.time()))
+        signature = compute_slack_signature(signing_secret, timestamp, body_bytes)
+        headers["X-Slack-Request-Timestamp"] = timestamp
+        headers["X-Slack-Signature"] = signature
+
+    async with httpx.AsyncClient() as c:
+        return await c.post(
+            f"{http_url}/webhook/slack",
+            content=body_bytes,
+            headers=headers,
+            timeout=10,
+        )
+
+
+async def wait_for_sent_messages(
+    fake_slack_url: str,
+    *,
+    min_count: int = 1,
+    timeout: float = 30,
+) -> list[dict]:
+    """Poll the fake Slack API until at least min_count chat.postMessage calls appear."""
+    deadline = time.monotonic() + timeout
+    async with httpx.AsyncClient() as c:
+        while time.monotonic() < deadline:
+            r = await c.get(f"{fake_slack_url}/__mock/sent_messages", timeout=5)
+            messages = r.json().get("messages", [])
+            if len(messages) >= min_count:
+                return messages
+            await asyncio.sleep(0.5)
+    raise TimeoutError(
+        f"Expected at least {min_count} sent messages within {timeout}s"
+    )
+
+
+async def get_api_calls(fake_slack_url: str) -> list[dict]:
+    """Fetch all recorded API calls from the fake Slack server."""
+    async with httpx.AsyncClient() as c:
+        r = await c.get(f"{fake_slack_url}/__mock/api_calls", timeout=5)
+        return r.json().get("calls", [])
+
+
+# -- tests -----------------------------------------------------------------
+
+
+async def test_slack_setup_and_dm_roundtrip(slack_e2e_server):
+    """Full DM round-trip: setup -> webhook -> mock LLM -> chat.postMessage."""
+    base_url = slack_e2e_server["base_url"]
+    http_url = slack_e2e_server["http_url"]
+    fake_slack_url = slack_e2e_server["fake_slack_url"]
+    channels_dir = slack_e2e_server["channels_dir"]
+
+    # Reset fake API and activate the Slack channel
+    await activate_slack(base_url, fake_slack_url, channels_dir)
+
+    # Clear fake API state to only capture round-trip messages
+    await reset_fake_slack(fake_slack_url)
+
+    # POST a DM webhook event as the verified owner
+    payload = build_slack_dm_event(OWNER_USER_ID, "hello")
+    resp = await post_slack_webhook(http_url, payload)
+    assert resp.status_code == 200, f"Webhook returned {resp.status_code}: {resp.text}"
+
+    # Wait for the bot to send a reply via the fake Slack API.
+    messages = await wait_for_sent_messages(fake_slack_url, min_count=1, timeout=30)
+    reply_text = messages[-1].get("text", "")
+    assert reply_text, f"Empty reply text. All sent messages: {messages}"
+    assert messages[-1]["channel"] == f"D{OWNER_USER_ID}"
+
+
+async def test_slack_app_mention_roundtrip(slack_e2e_server):
+    """app_mention in channel -> reply with correct channel + thread_ts."""
+    http_url = slack_e2e_server["http_url"]
+    fake_slack_url = slack_e2e_server["fake_slack_url"]
+
+    await reset_fake_slack(fake_slack_url)
+
+    ts = f"{time.time():.6f}"
+    payload = build_slack_mention_event(
+        OWNER_USER_ID,
+        f"<@{BOT_USER_ID}> what time is it",
+        channel="C0001",
+        ts=ts,
+    )
+    resp = await post_slack_webhook(http_url, payload)
+    assert resp.status_code == 200
+
+    messages = await wait_for_sent_messages(fake_slack_url, min_count=1, timeout=30)
+    reply = messages[-1]
+    assert reply["channel"] == "C0001"
+    # Reply should thread off the original message
+    assert reply.get("thread_ts") == ts or reply.get("thread_ts") is not None
+
+
+async def test_slack_url_verification_challenge(slack_e2e_server):
+    """url_verification event -> response contains challenge echo."""
+    http_url = slack_e2e_server["http_url"]
+
+    challenge_value = "test-challenge-token-12345"
+    payload = {
+        "type": "url_verification",
+        "token": "fake-verification-token",
+        "challenge": challenge_value,
+    }
+
+    # url_verification doesn't use HMAC signing
+    async with httpx.AsyncClient() as c:
+        resp = await c.post(
+            f"{http_url}/webhook/slack",
+            json=payload,
+            headers={"Content-Type": "application/json"},
+            timeout=10,
+        )
+
+    assert resp.status_code == 200
+    body = resp.text
+    # The challenge should be echoed back (either as JSON or plain text)
+    assert challenge_value in body, (
+        f"Expected challenge '{challenge_value}' in response, got: {body}"
+    )
+
+
+async def test_slack_unauthorized_user_rejected(slack_e2e_server):
+    """A webhook from a non-owner user should not produce a chat.postMessage reply."""
+    http_url = slack_e2e_server["http_url"]
+    fake_slack_url = slack_e2e_server["fake_slack_url"]
+
+    await reset_fake_slack(fake_slack_url)
+
+    # Send a DM from a different user (not the owner)
+    payload = build_slack_dm_event("U99STRANGER", "hello from stranger")
+    resp = await post_slack_webhook(http_url, payload)
+    assert resp.status_code == 200
+
+    # Give it a moment, then verify no LLM reply was sent to the stranger
+    await asyncio.sleep(3)
+    async with httpx.AsyncClient() as c:
+        r = await c.get(f"{fake_slack_url}/__mock/sent_messages", timeout=5)
+    messages = r.json().get("messages", [])
+    stranger_replies = [
+        m for m in messages if m.get("channel") == "DU99STRANGER"
+    ]
+    for m in stranger_replies:
+        text = m.get("text", "").lower()
+        assert "how can i help" not in text, (
+            f"Unauthorized user received an LLM reply: {m}"
+        )
+
+
+async def test_slack_invalid_hmac_signature_rejected(slack_e2e_server):
+    """Webhook with wrong HMAC signature is rejected."""
+    http_url = slack_e2e_server["http_url"]
+
+    payload = build_slack_dm_event(OWNER_USER_ID, "should be rejected")
+    resp = await post_slack_webhook(
+        http_url, payload, signing_secret="wrong-signing-secret"
+    )
+    assert resp.status_code in (401, 403), (
+        f"Expected 401/403, got {resp.status_code}: {resp.text}"
+    )
+
+
+async def test_slack_missing_hmac_headers_rejected(slack_e2e_server):
+    """Webhook with no signature headers is rejected."""
+    http_url = slack_e2e_server["http_url"]
+
+    payload = build_slack_dm_event(OWNER_USER_ID, "should be rejected")
+    # signing_secret=None means no HMAC headers are sent
+    resp = await post_slack_webhook(http_url, payload, signing_secret=None)
+    assert resp.status_code in (401, 403), (
+        f"Expected 401/403 for missing HMAC, got {resp.status_code}: {resp.text}"
+    )
+
+
+async def test_slack_bot_message_ignored(slack_e2e_server):
+    """Event with bot_id is silently dropped (no reply)."""
+    http_url = slack_e2e_server["http_url"]
+    fake_slack_url = slack_e2e_server["fake_slack_url"]
+
+    await reset_fake_slack(fake_slack_url)
+
+    payload = build_slack_dm_event(
+        OWNER_USER_ID,
+        "I am a bot message",
+        bot_id="B12345",
+    )
+    resp = await post_slack_webhook(http_url, payload)
+    assert resp.status_code == 200
+
+    await asyncio.sleep(3)
+    async with httpx.AsyncClient() as c:
+        r = await c.get(f"{fake_slack_url}/__mock/sent_messages", timeout=5)
+    messages = r.json().get("messages", [])
+    assert len(messages) == 0, (
+        f"Expected no replies for bot message, got: {messages}"
+    )
+
+
+async def test_slack_message_subtype_ignored(slack_e2e_server):
+    """Event with subtype is silently dropped (no reply)."""
+    http_url = slack_e2e_server["http_url"]
+    fake_slack_url = slack_e2e_server["fake_slack_url"]
+
+    await reset_fake_slack(fake_slack_url)
+
+    payload = build_slack_dm_event(
+        OWNER_USER_ID,
+        "channel join message",
+        subtype="channel_join",
+    )
+    resp = await post_slack_webhook(http_url, payload)
+    assert resp.status_code == 200
+
+    await asyncio.sleep(3)
+    async with httpx.AsyncClient() as c:
+        r = await c.get(f"{fake_slack_url}/__mock/sent_messages", timeout=5)
+    messages = r.json().get("messages", [])
+    assert len(messages) == 0, (
+        f"Expected no replies for subtype message, got: {messages}"
+    )
+
+
+async def test_slack_bot_mention_stripped(slack_e2e_server):
+    """<@UBOTUSER> hello -> LLM sees 'hello' (mention stripped)."""
+    http_url = slack_e2e_server["http_url"]
+    fake_slack_url = slack_e2e_server["fake_slack_url"]
+
+    await reset_fake_slack(fake_slack_url)
+
+    payload = build_slack_mention_event(
+        OWNER_USER_ID,
+        f"<@{BOT_USER_ID}> hello",
+        channel="C0001",
+    )
+    resp = await post_slack_webhook(http_url, payload)
+    assert resp.status_code == 200
+
+    # The bot should reply -- the mention prefix should be stripped
+    # before reaching the LLM. The mock LLM matches "hello" -> greeting.
+    messages = await wait_for_sent_messages(fake_slack_url, min_count=1, timeout=30)
+    assert len(messages) >= 1, f"Expected a reply, got: {messages}"
+
+
+async def test_slack_thread_reply_includes_thread_ts(slack_e2e_server):
+    """DM with thread_ts -> reply includes thread_ts in chat.postMessage."""
+    http_url = slack_e2e_server["http_url"]
+    fake_slack_url = slack_e2e_server["fake_slack_url"]
+
+    await reset_fake_slack(fake_slack_url)
+
+    thread_ts = "1234567890.000001"
+    payload = build_slack_dm_event(
+        OWNER_USER_ID,
+        "hello in thread",
+        thread_ts=thread_ts,
+    )
+    resp = await post_slack_webhook(http_url, payload)
+    assert resp.status_code == 200
+
+    messages = await wait_for_sent_messages(fake_slack_url, min_count=1, timeout=30)
+    reply = messages[-1]
+    assert reply.get("thread_ts") == thread_ts, (
+        f"Expected thread_ts={thread_ts} in reply, got: {reply}"
+    )
+
+
+async def test_slack_malformed_payload_resilience(slack_e2e_server):
+    """Bad JSON -> 200/400 (not 500), bot still works after."""
+    http_url = slack_e2e_server["http_url"]
+    fake_slack_url = slack_e2e_server["fake_slack_url"]
+
+    await reset_fake_slack(fake_slack_url)
+
+    # Send a completely malformed payload
+    body_bytes = b'{"not_a_valid_slack_event": true}'
+    timestamp = str(int(time.time()))
+    signature = compute_slack_signature(SIGNING_SECRET, timestamp, body_bytes)
+    headers = {
+        "Content-Type": "application/json",
+        "X-Slack-Request-Timestamp": timestamp,
+        "X-Slack-Signature": signature,
+    }
+    async with httpx.AsyncClient() as c:
+        resp = await c.post(
+            f"{http_url}/webhook/slack",
+            content=body_bytes,
+            headers=headers,
+            timeout=10,
+        )
+    # Accept 200 or 400 but not 500
+    assert resp.status_code in (200, 400), (
+        f"Expected 200 or 400 for malformed payload, got {resp.status_code}: {resp.text}"
+    )
+
+    # Verify no replies were sent
+    await asyncio.sleep(2)
+    async with httpx.AsyncClient() as c:
+        r = await c.get(f"{fake_slack_url}/__mock/sent_messages", timeout=5)
+    messages = r.json().get("messages", [])
+    assert len(messages) == 0, (
+        f"Expected no replies for malformed payload, got: {messages}"
+    )
+
+    # Verify bot still works after bad payload
+    await reset_fake_slack(fake_slack_url)
+    payload = build_slack_dm_event(OWNER_USER_ID, "hello")
+    resp2 = await post_slack_webhook(http_url, payload)
+    assert resp2.status_code == 200
+
+    messages = await wait_for_sent_messages(fake_slack_url, min_count=1, timeout=30)
+    assert len(messages) >= 1, (
+        f"Expected bot to work after malformed payload, got: {messages}"
+    )
+
+
+async def test_slack_file_attachment_with_dm(slack_e2e_server):
+    """DM with files array -> file download attempted, message still processed."""
+    http_url = slack_e2e_server["http_url"]
+    fake_slack_url = slack_e2e_server["fake_slack_url"]
+
+    await reset_fake_slack(fake_slack_url)
+
+    payload = build_slack_dm_event(
+        OWNER_USER_ID,
+        "hello with attachment",
+        files=[
+            {
+                "id": "F0FILE001",
+                "name": "report.pdf",
+                "mimetype": "application/pdf",
+                "url_private_download": "https://files.slack.com/files-pri/T0001-F0FILE001/report.pdf",
+                "size": 2048,
+            }
+        ],
+    )
+    resp = await post_slack_webhook(http_url, payload)
+    assert resp.status_code == 200
+
+    # Bot should reply to the text content regardless of file download outcome
+    messages = await wait_for_sent_messages(fake_slack_url, min_count=1, timeout=30)
+    assert len(messages) >= 1, (
+        f"Expected bot to reply with file attachment, got: {messages}"
+    )
+    assert messages[-1]["channel"] == f"D{OWNER_USER_ID}"
diff --git a/tests/e2e_status_events.rs b/tests/e2e_status_events.rs
index f8673d79b6a..caf1fdee4aa 100644
--- a/tests/e2e_status_events.rs
+++ b/tests/e2e_status_events.rs
@@ -54,7 +54,7 @@ mod tests {
         let starts: Vec<&str> = tool_events
             .iter()
             .filter_map(|e| match e {
-                StatusUpdate::ToolStarted { name } => Some(name.as_str()),
+                StatusUpdate::ToolStarted { name, .. } => Some(name.as_str()),
                 _ => None,
             })
             .collect();
@@ -85,7 +85,7 @@ mod tests {
         let mut pending_starts: Vec<String> = Vec::new();
         for event in &tool_events {
             match event {
-                StatusUpdate::ToolStarted { name } => {
+                StatusUpdate::ToolStarted { name, .. } => {
                     pending_starts.push(name.clone());
                 }
                 StatusUpdate::ToolCompleted { name, .. } => {
diff --git a/tests/engine_v2_skill_codeact.rs b/tests/engine_v2_skill_codeact.rs
index bf1cc717b28..94172539256 100644
--- a/tests/engine_v2_skill_codeact.rs
+++ b/tests/engine_v2_skill_codeact.rs
@@ -346,6 +346,8 @@ fn make_github_skill_doc(project_id: ProjectId) -> MemoryDoc {
         }],
         metrics: SkillMetrics::default(),
         parent_version: None,
+        revisions: vec![],
+        repairs: vec![],
         content_hash: String::new(),
     };
 
@@ -493,6 +495,87 @@ FINAL(str(result))
     );
 }
 
+/// Verify selected skill provenance is persisted onto the thread for learning flows.
+#[tokio::test]
+async fn skill_codeact_persists_active_skill_provenance() {
+    let project_id = ProjectId::new();
+    let skill_doc = make_github_skill_doc(project_id);
+    let skill_doc_id = skill_doc.id;
+
+    let python_code = r#"
+result = await http(method="GET", url="https://api.github.com/repos/test-org/test-repo/issues?state=open&per_page=5")
+FINAL(str(result))
+"#;
+    let llm = ScriptedLlm::new(vec![LlmOutput {
+        response: LlmResponse::Code {
+            code: python_code.to_string(),
+            content: None,
+        },
+        usage: TokenUsage::default(),
+    }]);
+
+    let mut canned = HashMap::new();
+    canned.insert(
+        "api.github.com/repos/test-org/test-repo/issues".to_string(),
+        canned_github_issues(),
+    );
+    let effects = HttpMockEffects::new(canned);
+    let store = TestStore::new();
+    store.save_memory_doc(&skill_doc).await.unwrap();
+
+    let mut caps = CapabilityRegistry::new();
+    caps.register(Capability {
+        name: "tools".into(),
+        description: "Available tools".into(),
+        actions: vec![ActionDef {
+            name: "http".into(),
+            description: "Make HTTP requests".into(),
+            parameters_schema: serde_json::json!({"type": "object", "properties": {"url": {"type": "string"}}, "required": ["url"]}),
+            effects: vec![EffectType::ReadExternal],
+            requires_approval: false,
+        }],
+        knowledge: vec![],
+        policies: vec![],
+    });
+
+    let mgr = ThreadManager::new(
+        llm,
+        effects,
+        store.clone() as Arc<dyn Store>,
+        Arc::new(caps),
+        Arc::new(LeaseManager::new()),
+        Arc::new(PolicyEngine::new()),
+    );
+
+    let tid = mgr
+        .spawn_thread(
+            "show me open github issues for test-org/test-repo",
+            ThreadType::Foreground,
+            project_id,
+            ThreadConfig::default(),
+            None,
+            "test-user",
+        )
+        .await
+        .expect("spawn_thread");
+
+    let outcome = mgr.join_thread(tid).await.expect("join_thread");
+    assert!(
+        matches!(outcome, ThreadOutcome::Completed { .. }),
+        "expected Completed, got: {outcome:?}"
+    );
+
+    let thread = store.load_thread(tid).await.unwrap().unwrap();
+    let active_skills = thread.active_skills();
+    let github_skill = active_skills
+        .iter()
+        .find(|skill| skill.doc_id == skill_doc_id)
+        .unwrap_or_else(|| panic!("expected github skill provenance in {active_skills:?}"));
+    assert_eq!(github_skill.name, "github");
+    assert_eq!(github_skill.version, 1);
+    assert_eq!(github_skill.snippet_names, vec!["list_github_issues"]);
+}
+
 /// Verify that non-matching goals don't activate skills (negative case).
 #[tokio::test]
 async fn non_matching_goal_skips_skill_codeact() {
diff --git a/tests/slack_auth_integration.rs b/tests/slack_auth_integration.rs
new file mode 100644
index 00000000000..fea1d178a2a
--- /dev/null
+++ b/tests/slack_auth_integration.rs
@@ -0,0 +1,869 @@
+//! Integration tests for the Slack WASM channel.
+//!
+//! These tests verify Slack-specific behaviors: HMAC-SHA256 webhook signing,
+//! Bearer auth, app_mention vs DM message handling, bot message filtering,
+//! and thread tracking.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+#[cfg(feature = "integration")]
+use std::sync::{Mutex, OnceLock};
+
+#[cfg(feature = "integration")]
+use futures::StreamExt;
+#[cfg(feature = "integration")]
+use ironclaw::channels::Channel;
+#[cfg(feature = "integration")]
+use ironclaw::channels::OutgoingResponse;
+use ironclaw::channels::wasm::{
+    PreparedChannelModule, WasmChannel, WasmChannelRuntime, WasmChannelRuntimeConfig,
+};
+use ironclaw::pairing::PairingStore;
+#[cfg(feature = "integration")]
+use tokio::time::{Duration, timeout};
+
+/// Skip the test if the Slack WASM module hasn't been built.
+/// In CI (detected via the `CI` env var), panic instead of skipping so a
+/// broken WASM build step doesn't silently produce green tests.
+macro_rules! require_slack_wasm {
+    () => {
+        if !slack_wasm_path().exists() {
+            let msg = format!(
+                "Slack WASM module not found at {:?}. \
+                 Build with: cd channels-src/slack && cargo build --target wasm32-wasip2 --release",
+                slack_wasm_path()
+            );
+            if std::env::var("CI").is_ok() {
+                panic!("{}", msg);
+            }
+            eprintln!("Skipping test: {}", msg);
+            return;
+        }
+    };
+}
+
+/// Path to the built Slack WASM module
+/// Resolve a project-relative path, falling back to other git worktrees.
+fn find_project_file(relative_path: &str) -> std::path::PathBuf {
+    let local = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join(relative_path);
+    if local.exists() {
+        return local;
+    }
+
+    if let Ok(output) = std::process::Command::new("git")
+        .args(["worktree", "list", "--porcelain"])
+        .output()
+        && output.status.success()
+    {
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        for line in stdout.lines() {
+            if let Some(path) = line.strip_prefix("worktree ") {
+                let candidate = std::path::PathBuf::from(path).join(relative_path);
+                if candidate.exists() {
+                    return candidate;
+                }
+            }
+        }
+    }
+
+    local
+}
+
+fn slack_wasm_path() -> std::path::PathBuf {
+    find_project_file("channels-src/slack/target/wasm32-wasip2/release/slack_channel.wasm")
+}
+
+fn slack_capabilities_path() -> std::path::PathBuf {
+    find_project_file("channels-src/slack/slack.capabilities.json")
+}
+
+/// Create a test runtime for WASM channel operations.
+fn create_test_runtime() -> Arc<WasmChannelRuntime> {
+    let config = WasmChannelRuntimeConfig::for_testing();
+    Arc::new(WasmChannelRuntime::new(config).expect("Failed to create runtime"))
+}
+
+/// Load the real Slack WASM module.
+async fn load_slack_module(
+    runtime: &Arc<WasmChannelRuntime>,
+) -> Result<Arc<PreparedChannelModule>, Box<dyn std::error::Error>> {
+    let path = slack_wasm_path();
+    let wasm_bytes = std::fs::read(&path)
+        .map_err(|e| format!("Failed to read WASM module at {}: {}", path.display(), e))?;
+
+    let module = runtime
+        .prepare(
+            "slack",
+            &wasm_bytes,
+            None,
+            Some("Slack Events API channel".to_string()),
+        )
+        .await?;
+
+    Ok(module)
+}
+
+/// Create a Slack channel instance with configuration.
+async fn create_slack_channel(runtime: Arc<WasmChannelRuntime>, config_json: &str) -> WasmChannel {
+    create_slack_channel_with_store(runtime, config_json, Arc::new(PairingStore::new_noop())).await
+}
+
+async fn create_slack_channel_with_store(
+    runtime: Arc<WasmChannelRuntime>,
+    config_json: &str,
+    pairing_store: Arc<PairingStore>,
+) -> WasmChannel {
+    let module = load_slack_module(&runtime)
+        .await
+        .expect("Failed to load Slack WASM module");
+
+    let capabilities_bytes = std::fs::read(slack_capabilities_path())
+        .unwrap_or_else(|err| panic!("Failed to read Slack capabilities file: {err}"));
+    let capabilities_file =
+        ironclaw::channels::wasm::ChannelCapabilitiesFile::from_bytes(&capabilities_bytes)
+            .unwrap_or_else(|err| panic!("Failed to parse Slack capabilities file: {err}"));
+
+    let channel = WasmChannel::new(
+        runtime,
+        module,
+        capabilities_file.to_capabilities(),
+        "default",
+        config_json.to_string(),
+        pairing_store,
+        None,
+    );
+    channel
+        .set_credential("SLACK_BOT_TOKEN", "xoxb-fake-test-token".to_string())
+        .await;
+    channel
+        .set_credential("SLACK_SIGNING_SECRET", "test-signing-secret".to_string())
+        .await;
+    channel
+}
+
+/// Build a Slack event_callback JSON payload for a DM message.
+fn build_slack_event_callback(event: serde_json::Value) -> Vec<u8> {
+    serde_json::json!({
+        "type": "event_callback",
+        "token": "fake-verification-token",
+        "team_id": "T0001",
+        "event": event,
+        "event_id": "Ev001",
+        "event_time": 1234567890
+    })
+    .to_string()
+    .into_bytes()
+}
+
+#[cfg(feature = "integration")]
+struct ScopedEnvVar {
+    key: &'static str,
+    original: Option<String>,
+    _mutex: std::sync::MutexGuard<'static, ()>,
+}
+
+#[cfg(feature = "integration")]
+impl ScopedEnvVar {
+    fn set(key: &'static str, value: &str) -> Self {
+        static ENV_MUTEX: OnceLock<Mutex<()>> = OnceLock::new();
+        let guard = ENV_MUTEX
+            .get_or_init(|| Mutex::new(()))
+            .lock()
+            .expect("env mutex poisoned");
+        let original = std::env::var(key).ok();
+        // SAFETY: Under ENV_MUTEX, no concurrent env access.
+        unsafe {
+            std::env::set_var(key, value);
+        }
+        Self {
+            key,
+            original,
+            _mutex: guard,
+        }
+    }
+}
+
+#[cfg(feature = "integration")]
+impl Drop for ScopedEnvVar {
+    fn drop(&mut self) {
+        // SAFETY: Under ENV_MUTEX (still held by _mutex), no concurrent env access.
+        unsafe {
+            if let Some(ref value) = self.original {
+                std::env::set_var(self.key, value);
+            } else {
+                std::env::remove_var(self.key);
+            }
+        }
+    }
+}
+
+#[cfg(feature = "integration")]
+fn slack_test_http_rewrite_map(base_url: &str) -> String {
+    serde_json::json!({
+        "slack.com": base_url,
+        "files.slack.com": base_url,
+    })
+    .to_string()
+}
+
+#[cfg(feature = "integration")]
+async fn expect_no_message(stream: &mut ironclaw::channels::MessageStream, timeout_ms: u64) {
+    let result = timeout(Duration::from_millis(timeout_ms), stream.next()).await;
+    assert!(
+        result.is_err(),
+        "expected no message, but stream produced one"
+    );
+}
+
+// ── Tests without integration gate (on_http_request only) ───────────────
+
+#[tokio::test]
+async fn test_dm_from_owner_accepted() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": "U42OWNER",
+        "dm_policy": "pairing",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U42OWNER",
+        "text": "hello from owner",
+        "channel": "DU42OWNER",
+        "ts": "1234567890.000001",
+        "channel_type": "im"
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+}
+
+#[tokio::test]
+async fn test_dm_unauthorized_blocked_allowlist() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": "U42OWNER",
+        "dm_policy": "allowlist",
+        "allow_from": ["U42OWNER"],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+
+    // DM from an unauthorized user
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U99STRANGER",
+        "text": "hello",
+        "channel": "DU99STRANGER",
+        "ts": "1234567890.000002",
+        "channel_type": "im"
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    // Should return 200 (acknowledge webhook) but not emit a message
+    assert_eq!(response.status, 200);
+}
+
+#[tokio::test]
+async fn test_dm_pairing_policy_triggers_flow() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+    let pairing_store = Arc::new(PairingStore::new_noop());
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "pairing",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel_with_store(runtime, &config, pairing_store.clone()).await;
+
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U99NEWUSER",
+        "text": "hello",
+        "channel": "DU99NEWUSER",
+        "ts": "1234567890.000003",
+        "channel_type": "im"
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+}
+
+#[tokio::test]
+async fn test_open_dm_policy_allows_all() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "open",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+
+    // DM from any user should be accepted
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U88RANDOM",
+        "text": "hello from anyone",
+        "channel": "DU88RANDOM",
+        "ts": "1234567890.000004",
+        "channel_type": "im"
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+}
+
+#[tokio::test]
+async fn test_url_verification_returns_challenge() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "open",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+
+    let body = serde_json::json!({
+        "type": "url_verification",
+        "token": "fake-verification-token",
+        "challenge": "test-challenge-abc123"
+    })
+    .to_string()
+    .into_bytes();
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+    let response_body = String::from_utf8_lossy(&response.body);
+    assert!(
+        response_body.contains("test-challenge-abc123"),
+        "Expected challenge in response body, got: {}",
+        response_body
+    );
+}
+
+// ── Tests with integration gate (stream/respond) ────────────────────────
+
+#[tokio::test]
+#[cfg(feature = "integration")]
+async fn test_app_mention_strips_bot_prefix() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "open",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+    let mut stream = channel
+        .start_message_stream_for_test()
+        .await
+        .expect("Failed to bootstrap test message stream");
+
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "app_mention",
+        "user": "U42OWNER",
+        "text": "<@UBOT> hello",
+        "channel": "C0001",
+        "ts": "1234567890.000010"
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+
+    let msg = timeout(Duration::from_secs(2), stream.next())
+        .await
+        .expect("message should arrive")
+        .expect("stream should yield a message");
+
+    // The bot mention prefix should be stripped
+    let content = msg.content.trim();
+    assert!(
+        !content.starts_with("<@"),
+        "Bot mention should be stripped from content: '{}'",
+        content
+    );
+    assert!(
+        content.contains("hello"),
+        "Content should contain 'hello', got: '{}'",
+        content
+    );
+}
+
+#[tokio::test]
+#[cfg(feature = "integration")]
+async fn test_bot_message_with_bot_id_ignored() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "open",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+    let mut stream = channel
+        .start_message_stream_for_test()
+        .await
+        .expect("Failed to bootstrap test message stream");
+
+    // Message with bot_id should be ignored
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U42OWNER",
+        "text": "I am a bot",
+        "channel": "DU42OWNER",
+        "ts": "1234567890.000011",
+        "channel_type": "im",
+        "bot_id": "B12345"
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+    expect_no_message(&mut stream, 500).await;
+}
+
+#[tokio::test]
+#[cfg(feature = "integration")]
+async fn test_message_subtype_ignored() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "open",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+    let mut stream = channel
+        .start_message_stream_for_test()
+        .await
+        .expect("Failed to bootstrap test message stream");
+
+    // Message with subtype should be ignored
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U42OWNER",
+        "text": "joined channel",
+        "channel": "C0001",
+        "ts": "1234567890.000012",
+        "subtype": "channel_join"
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+    expect_no_message(&mut stream, 500).await;
+}
+
+#[tokio::test]
+#[cfg(feature = "integration")]
+async fn test_dm_emits_correct_metadata() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "open",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+    let mut stream = channel
+        .start_message_stream_for_test()
+        .await
+        .expect("Failed to bootstrap test message stream");
+
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U42OWNER",
+        "text": "hello metadata test",
+        "channel": "DU42OWNER",
+        "ts": "1234567890.000013",
+        "channel_type": "im"
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+
+    let msg = timeout(Duration::from_secs(2), stream.next())
+        .await
+        .expect("message should arrive")
+        .expect("stream should yield a message");
+
+    assert_eq!(msg.content, "hello metadata test");
+    // Thread ID should be set (channel or DM ID)
+    assert!(
+        msg.thread_id.is_some(),
+        "Expected thread_id to be set for DM"
+    );
+}
+
+#[tokio::test]
+#[cfg(feature = "integration")]
+async fn test_respond_posts_to_slack_api() {
+    use axum::{
+        Router, body::Bytes, extract::State, http::Uri, response::IntoResponse, routing::any,
+    };
+
+    #[derive(Clone)]
+    struct FakeSlackState {
+        requests: Arc<tokio::sync::Mutex<Vec<String>>>,
+        post_message_payloads: Arc<tokio::sync::Mutex<Vec<serde_json::Value>>>,
+    }
+
+    async fn handler(
+        State(state): State<FakeSlackState>,
+        uri: Uri,
+        body: Bytes,
+    ) -> impl IntoResponse {
+        state.requests.lock().await.push(uri.to_string());
+
+        if uri.path().ends_with("/chat.postMessage") {
+            let payload = serde_json::from_slice::<serde_json::Value>(&body)
+                .unwrap_or_else(|err| panic!("invalid chat.postMessage payload: {err}"));
+            state.post_message_payloads.lock().await.push(payload);
+            return axum::Json(serde_json::json!({
+                "ok": true,
+                "channel": "DU42OWNER",
+                "ts": "1234567890.000099",
+                "message": { "text": "reply", "ts": "1234567890.000099" }
+            }))
+            .into_response();
+        }
+
+        (
+            axum::http::StatusCode::NOT_FOUND,
+            format!("Unhandled fake Slack path: {}", uri.path()),
+        )
+            .into_response()
+    }
+
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let state = FakeSlackState {
+        requests: Arc::new(tokio::sync::Mutex::new(Vec::new())),
+        post_message_payloads: Arc::new(tokio::sync::Mutex::new(Vec::new())),
+    };
+
+    let app = Router::new()
+        .route("/{*path}", any(handler))
+        .with_state(state.clone());
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind fake slack");
+    let addr = listener.local_addr().expect("fake slack addr");
+    let server = tokio::spawn(async move {
+        let _ = axum::serve(listener, app).await;
+    });
+    let _guard = ScopedEnvVar::set(
+        "IRONCLAW_TEST_HTTP_REWRITE_MAP",
+        &slack_test_http_rewrite_map(&format!("http://{addr}")),
+    );
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "open",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+    let mut stream = channel
+        .start_message_stream_for_test()
+        .await
+        .expect("Failed to bootstrap test message stream");
+
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U42OWNER",
+        "text": "hello from slack dm",
+        "channel": "DU42OWNER",
+        "ts": "1234567890.000020",
+        "channel_type": "im"
+    }));
+
+    let http_response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+    assert_eq!(http_response.status, 200);
+
+    let incoming = timeout(Duration::from_secs(2), stream.next())
+        .await
+        .expect("message should arrive")
+        .expect("stream should yield a message");
+    assert_eq!(incoming.content, "hello from slack dm");
+
+    channel
+        .respond(
+            &incoming,
+            OutgoingResponse::text("hello back from ironclaw"),
+        )
+        .await
+        .expect("slack respond should succeed");
+
+    let payloads = timeout(Duration::from_secs(3), async {
+        loop {
+            let snapshot = state.post_message_payloads.lock().await.clone();
+            if !snapshot.is_empty() {
+                break snapshot;
+            }
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    })
+    .await
+    .expect("chat.postMessage should be captured");
+
+    server.abort();
+
+    assert_eq!(payloads.len(), 1);
+    assert_eq!(payloads[0]["channel"], serde_json::json!("DU42OWNER"));
+    assert_eq!(
+        payloads[0]["text"],
+        serde_json::json!("hello back from ironclaw")
+    );
+}
+
+#[tokio::test]
+#[cfg(feature = "integration")]
+async fn test_file_attachment_metadata() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "open",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+    let mut stream = channel
+        .start_message_stream_for_test()
+        .await
+        .expect("Failed to bootstrap test message stream");
+
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U42OWNER",
+        "text": "check this file",
+        "channel": "DU42OWNER",
+        "ts": "1234567890.000030",
+        "channel_type": "im",
+        "files": [
+            {
+                "id": "F0FILE001",
+                "name": "report.pdf",
+                "mimetype": "application/pdf",
+                "url_private_download": "https://files.slack.com/files-pri/T0001-F0FILE001/report.pdf",
+                "size": 2048
+            }
+        ]
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+
+    let msg = timeout(Duration::from_secs(2), stream.next())
+        .await
+        .expect("message should arrive")
+        .expect("stream should yield a message");
+
+    assert_eq!(msg.content, "check this file");
+    // The message should have file attachment metadata
+    // (even if download fails without the test API override)
+    assert!(
+        !msg.attachments.is_empty() || msg.content.contains("check this file"),
+        "Expected file metadata or text content"
+    );
+}
+
+#[tokio::test]
+#[cfg(feature = "integration")]
+async fn test_channel_message_without_mention_ignored() {
+    require_slack_wasm!();
+    let runtime = create_test_runtime();
+
+    let config = serde_json::json!({
+        "owner_id": null,
+        "dm_policy": "open",
+        "allow_from": [],
+    })
+    .to_string();
+
+    let channel = create_slack_channel(runtime, &config).await;
+    let mut stream = channel
+        .start_message_stream_for_test()
+        .await
+        .expect("Failed to bootstrap test message stream");
+
+    // Regular message in a channel (not DM, not app_mention) should be ignored
+    let body = build_slack_event_callback(serde_json::json!({
+        "type": "message",
+        "user": "U42OWNER",
+        "text": "hello everyone",
+        "channel": "C0001",
+        "ts": "1234567890.000040",
+        "channel_type": "channel"
+    }));
+
+    let response = channel
+        .call_on_http_request(
+            "POST",
+            "/webhook/slack",
+            &HashMap::new(),
+            &HashMap::new(),
+            &body,
+            true,
+        )
+        .await
+        .expect("HTTP callback failed");
+
+    assert_eq!(response.status, 200);
+    expect_no_message(&mut stream, 500).await;
+}
diff --git a/tests/support/live_harness.rs b/tests/support/live_harness.rs
index 541ac95b574..0c19ceda859 100644
--- a/tests/support/live_harness.rs
+++ b/tests/support/live_harness.rs
@@ -147,7 +147,7 @@ impl LiveTestHarness {
         // Tool activity from status events
         for event in self.rig.captured_status_events() {
             match event {
-                StatusUpdate::ToolStarted { name } => {
+                StatusUpdate::ToolStarted { name, .. } => {
                     log.push_str(&format!("  ● {name}\n"));
                 }
                 StatusUpdate::ToolCompleted {
@@ -163,7 +163,7 @@ impl LiveTestHarness {
                         log.push_str(&format!("  ✗ {name}: {err}\n"));
                     }
                 }
-                StatusUpdate::ToolResult { name, preview } => {
+                StatusUpdate::ToolResult { name, preview, .. } => {
                     let short = if preview.len() > 200 {
                         // Find a safe char boundary to avoid panicking on multi-byte UTF-8.
                         let end = preview
diff --git a/tests/support/test_channel.rs b/tests/support/test_channel.rs
index b6dff2d11bd..feeeeee097d 100644
--- a/tests/support/test_channel.rs
+++ b/tests/support/test_channel.rs
@@ -210,7 +210,7 @@ impl TestChannel {
         self.captured_status_events()
             .iter()
             .filter_map(|s| match s {
-                StatusUpdate::ToolStarted { name } => Some(name.clone()),
+                StatusUpdate::ToolStarted { name, .. } => Some(name.clone()),
                 _ => None,
             })
             .collect()
@@ -232,7 +232,9 @@ impl TestChannel {
         self.captured_status_events()
             .iter()
             .filter_map(|s| match s {
-                StatusUpdate::ToolResult { name, preview } => Some((name.clone(), preview.clone())),
+                StatusUpdate::ToolResult { name, preview, .. } => {
+                    Some((name.clone(), preview.clone()))
+                }
                 _ => None,
             })
             .collect()
@@ -385,7 +387,7 @@ impl Channel for TestChannel {
     ) -> Result<(), ChannelError> {
         // Capture timing before pushing to events.
         match &status {
-            StatusUpdate::ToolStarted { name } => {
+            StatusUpdate::ToolStarted { name, .. } => {
                 self.tool_start_times
                     .lock()
                     .await
diff --git a/tests/support/test_rig.rs b/tests/support/test_rig.rs
index 4f091de5dc3..620c2565e08 100644
--- a/tests/support/test_rig.rs
+++ b/tests/support/test_rig.rs
@@ -324,6 +324,7 @@ impl TestRig {
                     success: false,
                     error,
                     parameters,
+                    ..
                 } = status
                 {
                     let detail = format!(
@@ -367,6 +368,7 @@ impl TestRig {
                 success: false,
                 error,
                 parameters,
+                ..
             } = status
             {
                 let detail = format!(
diff --git a/tests/support_unit_tests.rs b/tests/support_unit_tests.rs
index 4ac65c0fcd2..35dbe6045d9 100644
--- a/tests/support_unit_tests.rs
+++ b/tests/support_unit_tests.rs
@@ -189,6 +189,8 @@ mod test_channel_tests {
             .send_status(
                 StatusUpdate::ToolStarted {
                     name: "echo".to_string(),
+                    detail: None,
+                    call_id: None,
                 },
                 &metadata,
             )
@@ -201,6 +203,7 @@ mod test_channel_tests {
                     success: true,
                     error: None,
                     parameters: None,
+                    call_id: None,
                 },
                 &metadata,
             )
@@ -209,7 +212,7 @@ mod test_channel_tests {
 
         let events = channel.captured_status_events();
         assert_eq!(events.len(), 2);
-        assert!(matches!(&events[0], StatusUpdate::ToolStarted { name } if name == "echo"));
+        assert!(matches!(&events[0], StatusUpdate::ToolStarted { name, .. } if name == "echo"));
         assert!(
             matches!(&events[1], StatusUpdate::ToolCompleted { name, success, .. } if name == "echo" && *success)
         );
@@ -224,6 +227,8 @@ mod test_channel_tests {
             .send_status(
                 StatusUpdate::ToolStarted {
                     name: "memory_search".to_string(),
+                    detail: None,
+                    call_id: None,
                 },
                 &metadata,
             )
@@ -237,6 +242,8 @@ mod test_channel_tests {
             .send_status(
                 StatusUpdate::ToolStarted {
                     name: "echo".to_string(),
+                    detail: None,
+                    call_id: None,
                 },
                 &metadata,
             )
@@ -255,6 +262,7 @@ mod test_channel_tests {
                 StatusUpdate::ToolResult {
                     name: "echo".to_string(),
                     preview: "hello world".to_string(),
+                    call_id: None,
                 },
                 &serde_json::Value::Null,
             )
@@ -265,6 +273,7 @@ mod test_channel_tests {
                 StatusUpdate::ToolResult {
                     name: "time".to_string(),
                     preview: "{\"iso\": \"2026-03-03\"}".to_string(),
+                    call_id: None,
                 },
                 &serde_json::Value::Null,
             )
@@ -304,6 +313,8 @@ mod test_channel_tests {
             .send_status(
                 StatusUpdate::ToolStarted {
                     name: "echo".to_string(),
+                    detail: None,
+                    call_id: None,
                 },
                 &serde_json::Value::Null,
             )
@@ -317,6 +328,7 @@ mod test_channel_tests {
                     success: true,
                     error: None,
                     parameters: None,
+                    call_id: None,
                 },
                 &serde_json::Value::Null,
             )
diff --git a/tests/ws_gateway_integration.rs b/tests/ws_gateway_integration.rs
index dfb74b2f9a7..50932f014bd 100644
--- a/tests/ws_gateway_integration.rs
+++ b/tests/ws_gateway_integration.rs
@@ -327,6 +327,7 @@ async fn test_ws_multiple_events_in_sequence() {
     });
     state.sse.broadcast(AppEvent::ToolStarted {
         name: "shell".to_string(),
+        detail: None,
         thread_id: None,
     });
     state.sse.broadcast(AppEvent::ToolCompleted {