docs(benchmarks): stop native_hook_spawn claiming to be the per-chunk path

The journey's comment, docstring, README row and CLI description all say it spawns "the per-chunk MessageDisplay hook exactly as Claude Code does". That stopped being true when MessageDisplay moved to a /bin/sh appender and evaluate-policy moved to a curl against the runner's relay. Both are pinned by tests — test_message_display_shell_command_round_trips asserts "python" is absent from the installed command — so the number the journey reports (~40ms here) is not on any per-chunk or per-tool-call path. Left as it was, the number reads as ~40ms of blocked TUI per streamed chunk, which would make it the largest single cost in the system and the obvious thing to go fix. It isn't, and I went and measured a replacement for an optimization the repo already has. Say what it measures instead: the lifetime of a hook that is Python, which is what the per-turn hooks (SessionStart / Stop / UserPromptSubmit / PreCompact / Task*), the PostToolUse TodoWrite+TaskUpdate matchers, and the policy hook's pre-relay fallback still pay — and which is the standing argument for keeping the hot paths off the interpreter. Naming the tests that pin it points the next reader at the evidence rather than at a stale comment. No behaviour change; comments, docstring, description and README only. Co-authored-by: Isaac <no-reply@databricks.com> Signed-off-by: harry-yao_data <harry.yao@databricks.com>
fix(cli): forward non-uuid session ids on remote resume (#5218 )
2026-08-22 08:50:20 +00:00 · 2026-08-21 15:54:45 -07:00 · 2026-08-21 15:38:03 -07:00 · 2026-08-21 22:24:09 +00:00 · 2026-08-22 07:23:32 +09:00 · 2026-08-21 21:21:46 +00:00
732 changed files with 69877 additions and 11096 deletions
@@ -146,7 +146,7 @@ streaming, harness.

 ```bash
 # Unit tests (use --frozen; the cwsandbox extra is unsatisfiable on public PyPI here)
-uv run --frozen --extra dev python -m pytest \
+uv run --frozen --group test python -m pytest \
  tests/inner/test_antigravity_executor.py \
  tests/inner/test_antigravity_harness.py \
  tests/runtime/test_antigravity_spawn_env.py \
@@ -157,7 +157,7 @@ already has complementary CUJ coverage — use both:
 - **Deeper end-to-end journeys → `tests/e2e/test_journey_*.py`** (first session
  to code, resume/disconnect, fork/explore, file upload, collaboration, …).
  Run a slice with the project's gated runner, e.g.
-  `uv run --frozen --extra dev python -m pytest tests/e2e/test_journey_first_session_to_code.py -q`.
+  `uv run --frozen --group test python -m pytest tests/e2e/test_journey_first_session_to_code.py -q`.
 - **Reusable PTY helpers** live in `tests/e2e/omnigent/_pexpect_harness.py`
  (`spawn_omnigent_run`, `wait_for_ready`, `submit_prompt`, `await_turn_complete`,
  `clean_exit`) and the snapshot comparator in `tests/e2e/omnigent/_snapshot.py`
@@ -20,8 +20,8 @@ the unit tests.

 1. **You're on the branch you want to test.** The copilot harness is an
   optional extra — install it (without disturbing other extras) with
-   `uv sync --frozen --extra dev --extra copilot`. NB: a bare
-   `uv run --frozen --extra dev` re-syncs the venv and **prunes** the copilot
+   `uv sync --frozen --group test --extra copilot`. NB: a bare
+   `uv run --frozen --group test` re-syncs the venv and **prunes** the copilot
   SDK; for live testing call `.venv/bin/omni` / `.venv/bin/python` directly and
   avoid `uv run` mid-session.
 2. **The SDK is installed:**
@@ -169,7 +169,7 @@ final answer lands server-side — read it over the AP API
 - **Spawn env:** `_build_copilot_spawn_env` in `omnigent/runtime/workflow.py`

 ```bash
-uv run --frozen --extra dev python -m pytest \
+uv run --frozen --group test python -m pytest \
  tests/inner/test_copilot_executor.py \
  tests/inner/test_copilot_harness.py \
  tests/runtime/test_copilot_spawn_env.py \
@@ -128,12 +128,12 @@ that works, the full stack is good: key, egress, bridge, harness.

 ```bash
 # Unit tests (use --frozen; the cwsandbox extra is unsatisfiable on public PyPI here)
-uv run --frozen --extra dev python -m pytest \
+uv run --frozen --group test python -m pytest \
  tests/inner/test_cursor_executor.py \
  tests/runtime/test_cursor_spawn_env.py \
  tests/onboarding/test_cursor_auth.py -q
 # Gated end-to-end harness test
-uv run --frozen --extra dev python -m pytest tests/e2e/omnigent/test_per_harness_cursor.py -q
+uv run --frozen --group test python -m pytest tests/e2e/omnigent/test_per_harness_cursor.py -q
 ```

 ## Bug-bash (fan out)
@@ -203,7 +203,7 @@ side effects.

 ```bash
 # Existing pytest e2e for polly (mock-LLM) — complementary to this skill:
-uv run --frozen --extra dev python -m pytest \
+uv run --frozen --group test python -m pytest \
  tests/e2e/test_polly_e2e.py \
  tests/e2e/test_polly_cost_advisor_e2e.py \
  tests/e2e/test_polly_subagent_model_e2e.py -q
@@ -19,7 +19,7 @@ micro-benchmarks (not concurrency), that is a different tool: `dev/benchmarks/`.
 ## 1. Ensure deps (repo checkout)

 ```bash
-pip install -e '.[loadtest,dev,agents-sdk]'   # or: uv sync --extra loadtest --extra dev --extra agents-sdk
+uv sync --extra loadtest --extra agents-sdk
 ```

 Run with that same interpreter (e.g. `.venv/bin/python`), from the repo root.
@@ -2,8 +2,8 @@
 web/electron/icons/AppIcon.icon/** binary -merge

 # Protobuf bindings regenerated by scripts/gen_routing_pb2.py from the .proto
-# schema. Mark them generated so review/code-quality tooling skips them (ruff
-# and mypy already exclude them in pyproject.toml); the protoc output isn't
+# schema. Mark them generated so review/code-quality tooling skips them (Ruff
+# excludes them and Pyrefly ignores generated-code errors); the protoc output isn't
 # hand-editable, so its unused-import/global artifacts are expected.
 omnigent/api/**/*_pb2.py linguist-generated=true
 omnigent/api/**/*_pb2.pyi linguist-generated=true
@@ -0,0 +1,143 @@
+name: "Run e2e compat smoke tests"
+description: >
+  Run @pytest.mark.compat_smoke tests from tests/e2e/ in one configuration:
+  either the server or the runner subprocess is pinned to an older released
+  build while the other side stays on the checked-out code. Exactly one of
+  server_version / runner_version must be set.
+
+  Reuses the same install steps as .github/actions/e2e-run so the two
+  never drift on Python/uv/binary-dep setup. Unlike e2e-run this action
+  is not sharded and runs only the compat_smoke marker, keeping wall-clock
+  time under ~15 minutes.
+
+inputs:
+  server_version:
+    description: >
+      Release tag for the OLD server build (e.g. v0.9.0).
+      Set this for Config 1 (new runner, old server). Leave empty for Config 2.
+    required: false
+    default: ""
+  runner_version:
+    description: >
+      Release tag for the OLD runner build (e.g. v0.9.0).
+      Set this for Config 2 (new server, old runner). Leave empty for Config 1.
+    required: false
+    default: ""
+  artifact_suffix:
+    description: >
+      Appended to uploaded-artifact names to keep them unique across jobs
+      (e.g. "-config1"). Default empty — fine for single-run cases.
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Configure environment
+      shell: bash
+      run: |
+        {
+          echo "OMNIGENT_SKIP_WEB_UI=true"
+          echo "ANTHROPIC_API_KEY="
+          echo "OPENAI_API_KEY="
+          echo "CODEX="
+          echo "CLAUDE_CODE="
+        } >> "$GITHUB_ENV"
+
+    - name: Set up Python
+      uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+      with:
+        python-version-file: ".python-version"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a  # v4
+      with:
+        enable-cache: true
+
+    - name: Cache virtualenv
+      uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684  # v4
+      with:
+        path: .venv
+        key: venv-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}
+
+    - name: Install project and test dependencies
+      shell: bash
+      run: uv sync --locked --extra all --group test
+
+    - name: Install binary dependencies
+      working-directory: .github/ci-deps
+      shell: bash
+      run: |
+        sudo apt-get install -y tmux bubblewrap
+        sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+        npm install --ignore-scripts
+        node node_modules/@anthropic-ai/claude-code/install.cjs
+        echo "${GITHUB_WORKSPACE}/.github/ci-deps/node_modules/.bin" >> "$GITHUB_PATH"
+
+    - name: "Build pinned old server (Config 2: new runner, old server)"
+      if: ${{ inputs.server_version != '' }}
+      shell: bash
+      env:
+        SERVER_VERSION_INPUT: ${{ inputs.server_version }}
+      run: |
+        tag="$SERVER_VERSION_INPUT"
+        if ! [[ "$tag" =~ ^v?[0-9]+\.[0-9]+(\.[0-9]+)?([a-z0-9.]*)?$ ]]; then
+          echo "Invalid server_version: '$tag'" >&2; exit 1
+        fi
+        src="$RUNNER_TEMP/server-src"
+        venv="$RUNNER_TEMP/server-env"
+        git worktree add --detach "$src" "$tag"
+        uv venv --python 3.12 "$venv"
+        uv pip install --python "$venv/bin/python" \
+          -e "$src" -e "$src/sdks/python-client" -e "$src/sdks/ui"
+        "$venv/bin/omnigent" --version
+        echo "OMNIGENT_COMPAT_SERVER_PYTHON=$venv/bin/python" >> "$GITHUB_ENV"
+        echo "OMNIGENT_COMPAT_SERVER_VERSION=${tag#v}" >> "$GITHUB_ENV"
+
+    - name: "Build pinned old runner/host (Config 1: new server, old runner)"
+      if: ${{ inputs.runner_version != '' }}
+      shell: bash
+      env:
+        RUNNER_VERSION_INPUT: ${{ inputs.runner_version }}
+      run: |
+        tag="$RUNNER_VERSION_INPUT"
+        if ! [[ "$tag" =~ ^v?[0-9]+\.[0-9]+(\.[0-9]+)?([a-z0-9.]*)?$ ]]; then
+          echo "Invalid runner_version: '$tag'" >&2; exit 1
+        fi
+        src="$RUNNER_TEMP/runner-src"
+        venv="$RUNNER_TEMP/runner-env"
+        git worktree add --detach "$src" "$tag"
+        uv venv --python 3.12 "$venv"
+        uv pip install --python "$venv/bin/python" \
+          -e "$src" -e "$src/sdks/python-client" -e "$src/sdks/ui"
+        "$venv/bin/omnigent" --version
+        echo "OMNIGENT_COMPAT_RUNNER_PYTHON=$venv/bin/python" >> "$GITHUB_ENV"
+        echo "OMNIGENT_COMPAT_RUNNER_VERSION=${tag#v}" >> "$GITHUB_ENV"
+
+    - name: Run compat smoke tests
+      shell: bash
+      env:
+        E2E_TMP_BASE: /tmp/omnigent-compat-smoke-${{ github.run_id }}
+      run: |
+        mkdir -p "$E2E_TMP_BASE"
+        uv run pytest tests/e2e/ \
+          -m compat_smoke \
+          -v --tb=long --showlocals --log-level=INFO \
+          --timeout=120 \
+          --timeout-method=thread \
+          --basetemp="$E2E_TMP_BASE" \
+          --junitxml="$E2E_TMP_BASE/junit.xml"
+
+    - name: Upload logs on failure
+      if: ${{ failure() || cancelled() }}
+      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+      with:
+        name: compat-smoke-logs-${{ github.run_id }}${{ inputs.artifact_suffix }}
+        path: |
+          /tmp/omnigent-compat-smoke-${{ github.run_id }}/**/server.log
+          /tmp/omnigent-compat-smoke-${{ github.run_id }}/**/runner.log
+          /tmp/omnigent-compat-smoke-${{ github.run_id }}/**/.omnigent/logs/**/*.log
+          /tmp/omnigent-compat-smoke-${{ github.run_id }}/junit.xml
+        retention-days: 7
+        if-no-files-found: warn
+        include-hidden-files: true
@@ -0,0 +1,227 @@
+name: "Run UI compat tests (smoke or full suite)"
+description: >
+  Run tests/e2e_ui/ in one of two cross-version configurations:
+
+  Config A — new SPA + new runner, old server (server_version set):
+    The server subprocess is pinned to the released tag while the SPA is
+    built from HEAD. Tests the common deploy ordering where the server
+    lags behind the frontend.
+
+  Config B — old SPA, new server + new runner (ui_version set):
+    The SPA is built from the released tag's web/ source and the HEAD
+    server is pointed at it via OMNIGENT_WEB_UI_DIST. Tests cached-SPA
+    scenarios where a user's browser has an older bundle after a server
+    upgrade.
+
+  Exactly one of server_version / ui_version must be set.
+
+  Two run modes:
+  - full_suite=false (default): run only @pytest.mark.compat_smoke tests.
+  - full_suite=true: run the complete tests/e2e_ui/ suite, sharded.
+
+inputs:
+  server_version:
+    description: >
+      Release tag for the OLD server (e.g. v0.9.0). SPA and runner stay
+      on HEAD. Mutually exclusive with ui_version.
+    required: false
+    default: ""
+  ui_version:
+    description: >
+      Release tag whose web/ source is used to build the OLD SPA (e.g.
+      v0.9.0). Server and runner stay on HEAD; OMNIGENT_WEB_UI_DIST is
+      set to the old built bundle. Mutually exclusive with server_version.
+    required: false
+    default: ""
+  full_suite:
+    description: >
+      "true" = run the full tests/e2e_ui/ suite with sharding (overnight matrix).
+      "false" (default) = run only @pytest.mark.compat_smoke tests (PR gate).
+    required: false
+    default: "false"
+  shard_id:
+    description: "0-based shard index (only used when full_suite=true)."
+    required: false
+    default: "0"
+  num_shards:
+    description: "Total shard count (only used when full_suite=true)."
+    required: false
+    default: "1"
+  artifact_suffix:
+    description: >
+      Appended to uploaded-artifact names (e.g. "-ui-config"). Default empty.
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Configure environment
+      shell: bash
+      run: |
+        {
+          echo "OMNIGENT_SKIP_WEB_UI=true"
+          echo "ANTHROPIC_API_KEY="
+          echo "OPENAI_API_KEY="
+          echo "CODEX="
+          echo "CLAUDE_CODE="
+        } >> "$GITHUB_ENV"
+
+    - name: Set up Python
+      uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+      with:
+        python-version-file: ".python-version"
+
+    - name: Set up pnpm + Node
+      uses: ./.github/actions/setup-pnpm
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a  # v4
+      with:
+        enable-cache: true
+
+    - name: Cache virtualenv
+      uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684  # v4
+      with:
+        path: .venv
+        key: venv-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}
+
+    - name: Install project and test dependencies
+      shell: bash
+      run: uv sync --locked --extra all --group test
+
+    - name: Install bubblewrap and tmux
+      shell: bash
+      run: |
+        sudo apt-get install -y bubblewrap tmux
+        sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+
+    - name: Cache Playwright browsers
+      uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684  # v4
+      with:
+        path: ~/.cache/ms-playwright
+        key: ${{ runner.os }}-playwright-${{ hashFiles('uv.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-playwright-
+
+    - name: Install Playwright Chromium
+      shell: bash
+      run: uv run playwright install --with-deps chromium
+
+    - name: Build HEAD SPA
+      # Always build the HEAD SPA so the built_spa fixture's tombstone assertion
+      # passes. In Config B OMNIGENT_WEB_UI_DIST is then set to the old bundle,
+      # so the server serves that instead — but the HEAD build must exist for the
+      # fixture's structural check.
+      shell: bash
+      env:
+        NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
+      run: |
+        pnpm install --frozen-lockfile --filter web
+        pnpm --filter web run build
+
+    - name: "Build pinned old server (Config A)"
+      if: ${{ inputs.server_version != '' }}
+      shell: bash
+      env:
+        SERVER_VERSION_INPUT: ${{ inputs.server_version }}
+      run: |
+        tag="$SERVER_VERSION_INPUT"
+        if ! [[ "$tag" =~ ^v?[0-9]+\.[0-9]+(\.[0-9]+)?([a-z0-9.]*)?$ ]]; then
+          echo "Invalid server_version: '$tag'" >&2; exit 1
+        fi
+        src="$RUNNER_TEMP/ui-server-src"
+        venv="$RUNNER_TEMP/ui-server-env"
+        git worktree add --detach "$src" "$tag"
+        uv venv --python 3.12 "$venv"
+        uv pip install --python "$venv/bin/python" \
+          -e "$src" -e "$src/sdks/python-client" -e "$src/sdks/ui"
+        "$venv/bin/omnigent" --version
+        echo "OMNIGENT_COMPAT_SERVER_PYTHON=$venv/bin/python" >> "$GITHUB_ENV"
+        echo "OMNIGENT_COMPAT_SERVER_VERSION=${tag#v}" >> "$GITHUB_ENV"
+
+    - name: "Build old SPA from release tag (Config B: old SPA / new server)"
+      # Check out the old tag's web/ source into a temp dir, build it there,
+      # then set OMNIGENT_WEB_UI_DIST so the HEAD server serves that bundle.
+      if: ${{ inputs.ui_version != '' }}
+      shell: bash
+      env:
+        UI_VERSION_INPUT: ${{ inputs.ui_version }}
+        NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
+      run: |
+        tag="$UI_VERSION_INPUT"
+        if ! [[ "$tag" =~ ^v?[0-9]+\.[0-9]+(\.[0-9]+)?([a-z0-9.]*)?$ ]]; then
+          echo "Invalid ui_version: '$tag'" >&2; exit 1
+        fi
+        src="$RUNNER_TEMP/ui-spa-src"
+        git worktree add --detach "$src" "$tag"
+        # Build the old SPA in its own directory. pnpm install uses the
+        # old lock file; the build output lands in web/dist/ inside src.
+        cd "$src"
+        pnpm install --frozen-lockfile --filter web
+        pnpm --filter web run build
+        # vite.config.ts writes to ../omnigent/server/static/web-ui relative
+        # to web/ — resolve to the absolute path inside the old checkout.
+        built=$(cd web && node -e "const p=require('./vite.config.ts')" 2>/dev/null \
+          || echo "$src/omnigent/server/static/web-ui")
+        # Fall back to checking both known locations.
+        if [ -d "$src/omnigent/server/static/web-ui" ]; then
+          built="$src/omnigent/server/static/web-ui"
+        elif [ -d "$src/web/dist" ]; then
+          built="$src/web/dist"
+        else
+          echo "Could not locate built SPA under $src" >&2; exit 1
+        fi
+        # Set OMNIGENT_WEB_UI_DIST so the HEAD server serves this old bundle.
+        # The HEAD SPA is still built above (built_spa fixture needs it for the
+        # tombstone assertion); the server uses OMNIGENT_WEB_UI_DIST to override
+        # which bundle it actually mounts.
+        echo "OMNIGENT_WEB_UI_DIST=$built" >> "$GITHUB_ENV"
+
+    - name: Run UI compat tests
+      shell: bash
+      env:
+        FULL_SUITE: ${{ inputs.full_suite }}
+        SHARD_ID: ${{ inputs.shard_id }}
+        NUM_SHARDS: ${{ inputs.num_shards }}
+        E2E_TMP_BASE: /tmp/omnigent-compat-ui-${{ github.run_id }}
+      run: |
+        mkdir -p "$E2E_TMP_BASE"
+        if [[ "$FULL_SUITE" == "true" ]]; then
+          uv run pytest tests/e2e_ui/ \
+            -m "not visual and not nightly" \
+            --ui-skip-build \
+            --splits="$NUM_SHARDS" \
+            --group="$((SHARD_ID + 1))" \
+            --tracing=retain-on-failure \
+            --screenshot=only-on-failure \
+            -v --tb=long --showlocals --log-level=INFO \
+            --timeout=180 \
+            --timeout-method=thread \
+            --basetemp="$E2E_TMP_BASE" \
+            --junitxml="$E2E_TMP_BASE/junit.xml" \
+            || { rc=$?; [ "$rc" -eq 5 ] && echo "::notice::No tests collected in this shard; treating as a pass." || exit "$rc"; }
+        else
+          uv run pytest tests/e2e_ui/ \
+            -m compat_smoke \
+            --ui-skip-build \
+            -v --tb=long --showlocals --log-level=INFO \
+            --timeout=120 \
+            --timeout-method=thread \
+            --basetemp="$E2E_TMP_BASE" \
+            --junitxml="$E2E_TMP_BASE/junit.xml"
+        fi
+
+    - name: Upload logs on failure
+      if: ${{ failure() || cancelled() }}
+      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+      with:
+        name: compat-ui-smoke-logs-${{ github.run_id }}${{ inputs.artifact_suffix }}
+        path: |
+          /tmp/omnigent-compat-ui-${{ github.run_id }}/**/server.log
+          /tmp/omnigent-compat-ui-${{ github.run_id }}/**/runner.log
+          /tmp/omnigent-compat-ui-${{ github.run_id }}/**/.omnigent/logs/**/*.log
+          /tmp/omnigent-compat-ui-${{ github.run_id }}/junit.xml
+        retention-days: 7
+        if-no-files-found: warn
+        include-hidden-files: true
@@ -81,9 +81,9 @@ runs:
        path: .venv
        key: venv-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}

-    - name: Install project and dev dependencies
+    - name: Install project and test dependencies
      shell: bash
-      run: uv sync --locked --extra all --extra dev
+      run: uv sync --locked --extra all --group test

    - name: Install binary dependencies
      # npm install against .github/ci-deps/package.json with --ignore-scripts
@@ -71,9 +71,9 @@ runs:
        path: .venv
        key: venv-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}

-    - name: Install project and dev dependencies
+    - name: Install project and test dependencies
      shell: bash
-      run: uv sync --locked --extra all --extra dev
+      run: uv sync --locked --extra all --group test

    - name: Install binary dependencies
      # Mirrors e2e.yml. --ignore-scripts blocks npm postinstall hooks; we run
@@ -58,7 +58,8 @@ runs:
    - name: Install dependencies
      shell: bash
      working-directory: ${{ inputs.workdir }}
-      run: uv sync --extra all --extra dev
+      # Current callers are tools-less prose/JSON agents; repository checks never run.
+      run: uv sync --extra all

    - name: Install Claude Code CLI
      shell: bash
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Emit the UI backwards-compat matrix on $GITHUB_OUTPUT as `ui_matrix`.
+#
+# The UI matrix is server-only: for each final (non-prerelease) release tag
+# at or above the backcompat floor, emit one cell per shard where the server
+# is that release and the SPA + runner are both main. The runner axis is
+# omitted because the SPA is always served by the server binary in production,
+# so "new SPA vs old runner" is not a meaningful compat scenario for the UI.
+#
+# Env in:
+#   VERSIONS    optional comma-separated override (e.g. "main,v0.9.0").
+#               When set, only release tokens (non-"main") become cells.
+#   NUM_SHARDS  e2e_ui shard count per cell (default 3, mirrors e2e-ui.yml).
+# Out (GITHUB_OUTPUT):
+#   ui_matrix={"include":[{"server":..,"shard_id":..,"num_shards":..}, ...]}
+
+set -euo pipefail
+
+_valid_version() {
+  [ "$1" = "main" ] || [[ "$1" =~ ^v?[0-9]+\.[0-9]+(\.[0-9]+)?([a-z0-9.]*)?$ ]]
+}
+
+MIN_VERSION="${BACKCOMPAT_MIN_VERSION:-0.9.0}"
+MIN_VERSION="${MIN_VERSION#v}"
+
+_below_floor() {
+  [ "$1" = "main" ] && return 1
+  local v="${1#v}"
+  [ "$v" = "$MIN_VERSION" ] && return 1
+  [ "$(printf '%s\n%s\n' "$v" "$MIN_VERSION" | sort -V | head -1)" = "$v" ]
+}
+
+raw=()
+if [ -n "${VERSIONS:-}" ]; then
+  IFS=',' read -ra raw <<<"$VERSIONS"
+else
+  raw=()
+  while IFS= read -r tag; do raw+=("$tag"); done < <(git tag --sort=-v:refname | grep -viE '(^|[^a-z])(rc|dev|pre)[0-9]')
+fi
+
+# Collect only release tokens (skip "main" — "main vs main" is the normal gate).
+V=()
+for v in "${raw[@]}"; do
+  v="${v#"${v%%[![:space:]]*}"}"
+  v="${v%"${v##*[![:space:]]}"}"
+  [ -z "$v" ] && continue
+  [ "$v" = "main" ] && continue
+  if ! _valid_version "$v"; then
+    echo "skipping invalid version token: '$v'" >&2; continue
+  fi
+  if _below_floor "$v"; then
+    echo "skipping '$v': below UI backcompat floor $MIN_VERSION" >&2; continue
+  fi
+  V+=("$v")
+done
+
+num_shards="${NUM_SHARDS:-3}"
+
+# Each release tag produces 2 × num_shards jobs: one Config A cell
+# (server=tag) and one Config B cell (ui=tag). Cap at 256 total.
+max_ui=256
+while [ "${#V[@]}" -gt 0 ] && [ "$(( ${#V[@]} * 2 * num_shards ))" -gt "$max_ui" ]; do
+  dropped="${V[${#V[@]} - 1]}"
+  unset 'V[${#V[@]}-1]'
+  V=("${V[@]}")
+  echo "ui-matrix cap: dropped oldest version '$dropped' to keep UI jobs <= $max_ui" >&2
+done
+
+items=()
+for v in "${V[@]}"; do
+  # Config A: new SPA (HEAD), old server
+  for ((i = 0; i < num_shards; i++)); do
+    items+=("{\"server\":\"$v\",\"ui\":\"\",\"config\":\"A\",\"shard_id\":$i,\"num_shards\":$num_shards}")
+  done
+  # Config B: old SPA (tag), new server (HEAD)
+  for ((i = 0; i < num_shards; i++)); do
+    items+=("{\"server\":\"\",\"ui\":\"$v\",\"config\":\"B\",\"shard_id\":$i,\"num_shards\":$num_shards}")
+  done
+done
+
+json=$(IFS=,; echo "${items[*]:-}")
+echo "ui_matrix={\"include\":[$json]}" >>"${GITHUB_OUTPUT:-/dev/stdout}"
+echo "versions: ${V[*]:-(none)}; UI jobs: ${#items[@]} (${#V[@]} tags × 2 configs × $num_shards shards)" >&2
@@ -21,6 +21,7 @@ REVIEW_LABEL = "waiting-for-review"
 WAITING_DAYS = 7
 CANONICAL_REPO = "omnigent-ai/omnigent"
 MAX_CLOSURES_PER_RUN = 30
+REVIEW_EVENTS = {"pull_request_review", "pull_request_review_comment"}


 def label_names(item: dict[str, Any]) -> list[str]:
@@ -114,6 +115,16 @@ class GitHubAPI:
        pull, _ = self.request("GET", f"/repos/{self.repo}/pulls/{pull_number}")
        return pull

+    def get_review(self, pull_number: int, review_id: int) -> dict[str, Any]:
+        review, _ = self.request(
+            "GET", f"/repos/{self.repo}/pulls/{pull_number}/reviews/{review_id}"
+        )
+        return review
+
+    def get_review_comment(self, comment_id: int) -> dict[str, Any]:
+        comment, _ = self.request("GET", f"/repos/{self.repo}/pulls/comments/{comment_id}")
+        return comment
+
    def remove_label(self, issue_number: int, label: str) -> bool:
        quoted = urllib.parse.quote(label, safe="")
        try:
@@ -355,10 +366,14 @@ def apply_waiting_on_maintainer_activity(
        pull_number = payload["pull_request"]["number"]
        review = payload.get("review") or {}
        actor = (review.get("user") or {}).get("login")
+        review_state = (review.get("state") or "").lower()
        # An approval asks nothing of the author; it means the PR is ready.
-        if (review.get("state") or "").lower() == "approved":
+        if review_state == "approved":
            print(f"#{pull_number}: approving review, leaving the label alone.")
            return False
+        if review_state not in {"commented", "changes_requested"}:
+            print(f"#{pull_number}: {review_state or 'unknown'} review, leaving the label alone.")
+            return False
        if is_slash_command(review.get("body")):
            return False
        reason = "a maintainer reviewed"
@@ -473,6 +488,42 @@ def close_stale_waiting_prs(api: GitHubAPI, now: datetime | None = None) -> int:
    return closed


+def relay_integer(record: dict[str, Any], field: str) -> int:
+    value = record.get(field)
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ValueError(f"Relay field {field!r} must be a positive integer")
+    return value
+
+
+def hydrate_relay_event(
+    record: dict[str, Any], api: GitHubAPI, repo: str, expected_event: str
+) -> tuple[str, dict[str, Any]]:
+    event_name = record.get("event_name")
+    if event_name not in REVIEW_EVENTS:
+        raise ValueError(f"Unsupported relayed event: {event_name!r}")
+    if event_name != expected_event:
+        raise ValueError(
+            f"Relayed event {event_name!r} does not match workflow event {expected_event!r}"
+        )
+
+    pull_number = relay_integer(record, "pull_number")
+    activity_id = relay_integer(record, "activity_id")
+    pull = api.get_pull(pull_number)
+    base_repo = ((pull.get("base") or {}).get("repo") or {}).get("full_name") or ""
+    if base_repo.lower() != repo.lower():
+        raise ValueError(f"Relayed PR #{pull_number} targets {base_repo!r}, not {repo!r}")
+
+    if event_name == "pull_request_review":
+        review = api.get_review(pull_number, activity_id)
+        return event_name, {"pull_request": pull, "review": review}
+
+    comment = api.get_review_comment(activity_id)
+    expected_url = f"https://api.github.com/repos/{repo}/pulls/{pull_number}"
+    if comment.get("pull_request_url") != expected_url:
+        raise ValueError(f"Review comment {activity_id} does not belong to PR #{pull_number}")
+    return event_name, {"pull_request": pull, "comment": comment}
+
+
 def run(
    event_name: str,
    payload: dict[str, Any],
@@ -495,8 +546,7 @@ def run(
    apply_waiting_on_maintainer_activity(event_name, payload, api)


-def load_event_payload() -> dict[str, Any]:
-    path = os.environ.get("GITHUB_EVENT_PATH")
+def load_json(path: str | None) -> dict[str, Any]:
    if not path:
        return {}
    with open(path, encoding="utf-8") as handle:
@@ -509,8 +559,15 @@ def main() -> int:
    if not token:
        print("GITHUB_TOKEN is required", file=sys.stderr)
        return 1
-    event_name = os.environ.get("GITHUB_EVENT_NAME", "")
-    run(event_name, load_event_payload(), GitHubAPI(token, repo), repo)
+    api = GitHubAPI(token, repo)
+    relay_path = os.environ.get("WAITING_ON_AUTHOR_RELAY_PATH")
+    if relay_path:
+        expected_event = os.environ.get("WAITING_ON_AUTHOR_RELAY_EVENT", "")
+        event_name, payload = hydrate_relay_event(load_json(relay_path), api, repo, expected_event)
+    else:
+        event_name = os.environ.get("GITHUB_EVENT_NAME", "")
+        payload = load_json(os.environ.get("GITHUB_EVENT_PATH"))
+    run(event_name, payload, api, repo)
    return 0


@@ -63,6 +63,8 @@ class FakeAPI:
        issue_comments: dict[int, list[dict[str, Any]]] | None = None,
        review_comments: dict[int, list[dict[str, Any]]] | None = None,
        reviews: dict[int, list[dict[str, Any]]] | None = None,
+        review_by_id: dict[tuple[int, int], dict[str, Any]] | None = None,
+        review_comment_by_id: dict[int, dict[str, Any]] | None = None,
        commits: dict[int, list[dict[str, Any]]] | None = None,
        writers: list[str] | None = None,
    ):
@@ -73,6 +75,8 @@ class FakeAPI:
        self.issue_comments = issue_comments or {}
        self.review_comments = review_comments or {}
        self.reviews = reviews or {}
+        self.review_by_id = review_by_id or {}
+        self.review_comment_by_id = review_comment_by_id or {}
        self.commits = commits or {}
        self.removed: list[tuple[int, str]] = []
        self.closed: list[int] = []
@@ -83,6 +87,12 @@ class FakeAPI:
    def get_pull(self, pull_number: int) -> dict[str, Any]:
        return self.pull | {"number": pull_number}

+    def get_review(self, pull_number: int, review_id: int) -> dict[str, Any]:
+        return self.review_by_id[(pull_number, review_id)]
+
+    def get_review_comment(self, comment_id: int) -> dict[str, Any]:
+        return self.review_comment_by_id[comment_id]
+
    def remove_label(self, issue_number: int, label: str) -> bool:
        self.removed.append((issue_number, label))
        return True
@@ -442,6 +452,21 @@ class AutoWaitingOnAuthorTest(unittest.TestCase):
        )
        self.assertEqual(api.added, [])

+    def test_dismissed_review_leaves_the_label_alone(self) -> None:
+        api = self.dispatch(
+            "pull_request_review",
+            {
+                "pull_request": {"number": 12},
+                "review": {
+                    "user": {"login": "maintainer1"},
+                    "state": "dismissed",
+                    "body": "stale feedback",
+                },
+            },
+            pull=pr(labels=[]),
+        )
+        self.assertEqual(api.added, [])
+
    def test_commenting_review_applies_the_label(self) -> None:
        api = self.dispatch(
            "pull_request_review",
@@ -483,6 +508,99 @@ class AutoWaitingOnAuthorTest(unittest.TestCase):
        )
        self.assertEqual(api.added, [(12, waiting_on_author.LABEL)])

+    def test_relayed_review_rehydrates_trusted_api_data(self) -> None:
+        pull = pr(labels=[]) | {"base": {"repo": {"full_name": waiting_on_author.CANONICAL_REPO}}}
+        api = FakeAPI(
+            pull=pull,
+            review_by_id={
+                (12, 41): {
+                    "id": 41,
+                    "user": {"login": "maintainer1"},
+                    "state": "changes_requested",
+                    "body": "please fix",
+                }
+            },
+        )
+        event, payload = waiting_on_author.hydrate_relay_event(
+            {"event_name": "pull_request_review", "pull_number": 12, "activity_id": 41},
+            api,
+            waiting_on_author.CANONICAL_REPO,
+            "pull_request_review",
+        )
+
+        waiting_on_author.run(event, payload, api, waiting_on_author.CANONICAL_REPO)
+
+        self.assertEqual(api.added, [(12, waiting_on_author.LABEL)])
+
+    def test_relayed_review_comment_rehydrates_author_reply(self) -> None:
+        pull = pr(author="alice") | {
+            "base": {"repo": {"full_name": waiting_on_author.CANONICAL_REPO}}
+        }
+        api = FakeAPI(
+            pull=pull,
+            review_comment_by_id={
+                73: {
+                    "id": 73,
+                    "user": {"login": "alice"},
+                    "body": "fixed",
+                    "pull_request_url": (
+                        "https://api.github.com/repos/omnigent-ai/omnigent/pulls/12"
+                    ),
+                }
+            },
+        )
+        event, payload = waiting_on_author.hydrate_relay_event(
+            {
+                "event_name": "pull_request_review_comment",
+                "pull_number": 12,
+                "activity_id": 73,
+            },
+            api,
+            waiting_on_author.CANONICAL_REPO,
+            "pull_request_review_comment",
+        )
+
+        waiting_on_author.run(event, payload, api, waiting_on_author.CANONICAL_REPO)
+
+        self.assertEqual(api.removed, [(12, waiting_on_author.LABEL)])
+
+    def test_relayed_review_comment_must_match_pull(self) -> None:
+        pull = pr() | {"base": {"repo": {"full_name": waiting_on_author.CANONICAL_REPO}}}
+        api = FakeAPI(
+            pull=pull,
+            review_comment_by_id={
+                73: {
+                    "id": 73,
+                    "pull_request_url": (
+                        "https://api.github.com/repos/omnigent-ai/omnigent/pulls/99"
+                    ),
+                }
+            },
+        )
+
+        with self.assertRaisesRegex(ValueError, "does not belong"):
+            waiting_on_author.hydrate_relay_event(
+                {
+                    "event_name": "pull_request_review_comment",
+                    "pull_number": 12,
+                    "activity_id": 73,
+                },
+                api,
+                waiting_on_author.CANONICAL_REPO,
+                "pull_request_review_comment",
+            )
+
+    def test_relayed_event_must_match_workflow_event(self) -> None:
+        api = FakeAPI()
+
+        with self.assertRaisesRegex(ValueError, "does not match workflow event"):
+            waiting_on_author.hydrate_relay_event(
+                {"event_name": "pull_request_review", "pull_number": 12, "activity_id": 41},
+                api,
+                waiting_on_author.CANONICAL_REPO,
+                "pull_request_review_comment",
+            )
+
    def test_applying_clears_waiting_for_review(self) -> None:
        api = self.dispatch(
            "issue_comment",
@@ -0,0 +1,118 @@
+name: Benchmark (host sessions)
+
+# Profiles the host-bound session lifecycle — create → host.launch_runner →
+# runner boot → first token (`session_cold_start`), plus restart and the
+# common session actions around it — and renders the journey × metric matrix
+# into the job summary. Informational: no thresholds, so a noisy shared
+# runner can't block a PR; regression *gating* stays with benchmark-pr.yml
+# (store paths) and release.yml (release cuts). The seeded, backend-matrix
+# trend numbers stay with the nightly benchmark.yml; this workflow's value is
+# a fresh matrix on the PRs that actually move these numbers.
+#
+# Uses dev/benchmarks/omnigent (real server + real `omni host` daemon +
+# runner against a zero-latency mock LLM — no agent CLI or credentials).
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "omnigent/host/**"
+      - "omnigent/runner/**"
+      - "omnigent/server/**"
+      - "dev/benchmarks/**"
+      - ".github/workflows/benchmark-host.yml"
+  workflow_dispatch:
+    inputs:
+      journeys:
+        description: "Comma-separated journeys (blank = the host-session set)"
+        required: false
+        default: ""
+      iterations:
+        description: "Requests per run (runner journeys stay capped at 5)"
+        required: false
+        default: "100"
+      runs:
+        description: "Timed runs per journey"
+        required: false
+        default: "3"
+
+permissions:
+  contents: read
+
+env:
+  # No web SPA build during `uv sync` (setup.py _build_web_ui): nothing here
+  # serves the bundle, and the build otherwise times out on public npm.
+  OMNIGENT_SKIP_WEB_UI: "true"
+  UV_INDEX_URL: https://pypi.org/simple
+  PIP_INDEX_URL: https://pypi.org/simple
+  # The host-session set: the host-bound lifecycle journeys first, then the
+  # common HTTP session actions a user drives around them. Matches the
+  # journey names in dev/benchmarks/omnigent/journeys.py (ALL_JOURNEYS).
+  DEFAULT_JOURNEYS: >-
+    session_cold_start,session_cold_restart,warm_turn,time_to_first_token,interrupt,create_session,fork_session,list_sessions,get_session,load_conversation_history
+  JOURNEYS: ${{ (github.event_name == 'workflow_dispatch' && inputs.journeys) || '' }}
+  ITERATIONS: ${{ github.event_name == 'workflow_dispatch' && inputs.iterations || '100' }}
+  RUNS: ${{ github.event_name == 'workflow_dispatch' && inputs.runs || '3' }}
+
+concurrency:
+  # PR pushes cancel the previous run; manual dispatches never cancel each
+  # other (unique run_id).
+  group: benchmark-host-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  benchmark-host:
+    name: Host session benchmark (sqlite)
+    if: github.repository == 'omnigent-ai/omnigent' && !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version-file: ".python-version"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        # Same runtime install as the other benchmark workflows so numbers stay
+        # comparable across them.
+        run: uv sync --extra databricks
+
+      - name: Run host-session benchmark
+        # Throwaway empty SQLite DB (run.py default): these journeys measure
+        # process spin-up and turn latency, not query scale — corpus-scale
+        # numbers live in the nightly benchmark.yml.
+        run: |
+          uv run --no-sync dev/benchmarks/omnigent/run.py \
+            --journeys "${JOURNEYS:-$DEFAULT_JOURNEYS}" \
+            --iterations "$ITERATIONS" \
+            --runs "$RUNS" \
+            --output benchmark-results-host.json
+
+      - name: Render results matrix to job summary
+        if: always()
+        run: |
+          if [[ -f benchmark-results-host.json ]]; then
+            uv run --no-sync dev/benchmarks/omnigent/report_markdown.py \
+              --title "Host session benchmark" \
+              benchmark-results-host.json >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: benchmark-results-host-${{ github.run_id }}
+          path: benchmark-results-host.json
+          retention-days: 30
+          if-no-files-found: warn
@@ -55,7 +55,10 @@ jobs:
          enable-cache: true

      - name: Install dependencies
-        run: uv sync --extra dev --extra databricks
+        # pexpect drives omnigent polly via PTY for the cli_startup journey.
+        run: |
+          uv sync --extra databricks
+          uv pip install pexpect

      # Use the same corpus size as the nightly so baseline numbers are
      # directly comparable. Cache the seeded DB on the schema head + seed
@@ -127,7 +127,7 @@ jobs:

      - name: Install dependencies
        # `databricks` extra carries psycopg[binary] for the Postgres backend.
-        run: uv sync --extra dev --extra databricks
+        run: uv sync --extra databricks

      - name: Install MySQL driver
        # mysqlclient (mysql+mysqldb://) needs the system client library and is
@@ -180,6 +180,10 @@ jobs:
            --database-uri "${{ steps.db.outputs.uri }}" \
            --sessions "$SESSIONS" --items-per-session "$ITEMS"

+      # pexpect drives omnigent polly via PTY for the cli_startup journey.
+      - name: Install CLI startup dependencies
+        run: uv pip install pexpect
+
      - name: Run benchmark
        run: |
          uv run --no-sync dev/benchmarks/omnigent/run.py \
@@ -189,6 +193,17 @@ jobs:
            --network-delay-ms "$NETWORK_DELAY_MS" \
            --output "benchmark-results-${{ matrix.backend }}.json"

+      - name: Render results matrix to job summary
+        # The JSON artifact feeds the trend dashboard; this makes the same
+        # numbers readable on the run page without downloading it.
+        if: always()
+        run: |
+          if [[ -f "benchmark-results-${{ matrix.backend }}.json" ]]; then
+            uv run --no-sync dev/benchmarks/omnigent/report_markdown.py \
+              --title "Benchmark results" \
+              "benchmark-results-${{ matrix.backend }}.json" >> "$GITHUB_STEP_SUMMARY"
+          fi
+
      - name: Upload benchmark results
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        if: always()
@@ -188,7 +188,7 @@ jobs:
      - name: Install dependencies
        # matrix.extra (e.g. "databricks") adds an extra for lanes that need it;
        # empty for the default lanes.
-        run: uv sync --locked --extra all --extra dev ${{ matrix.extra && format('--extra {0}', matrix.extra) || '' }}
+        run: uv sync --locked --extra all --group test ${{ matrix.extra && format('--extra {0}', matrix.extra) || '' }}

      - name: Run pytest
        shell: bash
@@ -266,7 +266,7 @@ jobs:
        with:
          enable-cache: true
      - name: Install dependencies
-        run: uv sync --locked --extra all --extra dev --extra databricks
+        run: uv sync --locked --extra all --group test --extra databricks
      - name: Run store + DB tests against PostgreSQL
        env:
          OMNIGENT_TEST_DB_URI: postgresql+psycopg://postgres:omnigent@localhost:5432/omnigent_root
@@ -314,7 +314,7 @@ jobs:
      - name: Install system MySQL client library
        run: sudo apt-get update -qq && sudo apt-get install -y -q libmysqlclient-dev
      - name: Install dependencies
-        run: uv sync --locked --extra all --extra dev --extra databricks && uv pip install mysqlclient
+        run: uv sync --locked --extra all --group test --extra databricks && uv pip install mysqlclient
      - name: Run store + DB tests against MySQL
        env:
          OMNIGENT_TEST_DB_URI: mysql+mysqldb://root:omnigent@127.0.0.1:3306/omnigent_root
@@ -389,7 +389,7 @@ jobs:
          key: venv-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}

      - name: Install dependencies
-        run: uv sync --locked --extra all --extra dev
+        run: uv sync --locked --extra all --group test

      - name: Build parity sidecar
        if: steps.sidecar-cache.outputs.cache-hit != 'true'
@@ -247,7 +247,8 @@ jobs:

      - name: Install dependencies
        if: steps.plan.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
-        run: uv sync --extra all --extra dev
+        # Agents classify or edit external-site prose; repository checks never run.
+        run: uv sync --extra all

      - name: Install Claude Code CLI
        if: steps.plan.outputs.proceed == 'true' && steps.creds.outputs.available == 'true'
@@ -181,8 +181,8 @@ jobs:
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}
-      - name: Install project + dev extras
-        run: uv sync --locked --extra all --extra dev
+      - name: Install project + test dependencies
+        run: uv sync --locked --extra all --group test

      - name: Install bubblewrap + tmux
        # bubblewrap: the UI tests open terminals under os_env, whose
@@ -1,119 +0,0 @@
-name: Electron Build
-
-# Manually-triggered build of the Electron desktop shell (web/electron) for
-# Linux and Windows. Each platform packages on its own native runner —
-# electron-builder does not reliably cross-compile installers — and uploads the
-# installers PLUS the electron-updater feed manifests (latest-linux.yml /
-# latest.yml) as downloadable workflow artifacts. Unsigned: no signing creds are
-# wired here, so `CSC_IDENTITY_AUTO_DISCOVERY=false` forces an unsigned build
-# rather than failing when a cert is absent. No publishing to a provider / no
-# release upload (`--publish never`): the artifacts are captured here for manual
-# placement onto the omnigent.ai update feed (omnigent-site repo + artifact host).
-#
-# Run it from the Actions tab (Run workflow). macOS is intentionally omitted —
-# its signed/notarized build lives elsewhere.
-
-on:
-  workflow_dispatch:
-    inputs:
-      ref:
-        description: "Branch, tag, or SHA to build."
-        required: false
-        default: ""
-
-permissions:
-  contents: read
-
-concurrency:
-  # One build per ref: back-to-back manual dispatches on the same ref queue
-  # instead of running concurrently (keyed on ref only — including run_id would
-  # make every run its own group, defeating the serialization).
-  group: electron-build-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  build:
-    name: Build (${{ matrix.platform }})
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 30
-    strategy:
-      # Keep building the other platform even if one fails, so a Windows-only
-      # break still yields the Linux installers (and vice versa).
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-latest
-            platform: linux
-            build-script: build:linux
-          - os: windows-latest
-            platform: win
-            build-script: build:win
-
-    steps:
-      - name: Check out repo
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
-        with:
-          ref: ${{ github.event.inputs.ref || github.ref }}
-
-      - name: Set up pnpm
-        uses: ./.github/actions/setup-pnpm
-
-      - name: Install dependencies
-        env:
-          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
-        run: |-
-          pnpm install --frozen-lockfile --filter @omnigent/electron
-          pnpm install --frozen-lockfile --filter web
-
-      - name: Build ${{ matrix.platform }} app
-        working-directory: web/electron
-        env:
-          NPM_CONFIG_REGISTRY: https://registry.npmjs.org/
-          # No signing credentials in CI: force an unsigned build instead of
-          # letting electron-builder fail hunting for a certificate.
-          CSC_IDENTITY_AUTO_DISCOVERY: "false"
-          # electron-builder downloads Electron/tooling from GitHub; the token
-          # lifts the anonymous rate limit that otherwise flakes downloads.
-          GH_TOKEN: ${{ github.token }}
-        run: pnpm run ${{ matrix.build-script }} -- --publish never
-
-      # One artifact per platform bundling the COMPLETE electron-updater feed —
-      # the installer(s), the .blockmap electron-updater needs for differential
-      # downloads (referenced by path inside latest*.yml; the .deb has no
-      # blockmap since debs aren't differentially updated), and the feed
-      # manifest (latest-linux.yml / latest.yml). upload-artifact zips all
-      # matched files into a single download, so each platform yields one zip
-      # whose contents can be dropped straight onto a feed root (local HTTP
-      # server for testing, or public/_desktop/updates/ on the artifact host).
-      # Ship only the distributables + feed files, not electron-builder's
-      # unpacked intermediates (dist/*-unpacked).
-      #
-      # electron-builder writes the latest*.yml manifests to dist/ even under
-      # --publish never (a publish config exists in build.*.publish, so
-      # update-info generation runs; --publish only skips the provider upload).
-      # The manifest lists each artifact with sha512 + size + relative url.
-
-      - name: Upload Linux feed
-        if: matrix.platform == 'linux'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: omnigent-desktop-linux
-          path: |
-            web/electron/dist/*.AppImage
-            web/electron/dist/*.AppImage.blockmap
-            web/electron/dist/*.deb
-            web/electron/dist/latest-linux.yml
-          if-no-files-found: error
-          retention-days: 14
-
-      - name: Upload Windows feed
-        if: matrix.platform == 'win'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: omnigent-desktop-win
-          path: |
-            web/electron/dist/*.exe
-            web/electron/dist/*.exe.blockmap
-            web/electron/dist/latest.yml
-          if-no-files-found: error
-          retention-days: 14
@@ -233,10 +233,10 @@ jobs:
          # PAT passthrough for the codex / claude-sdk auth commands.
          echo "DATABRICKS_BEARER=$LLM_API_KEY" >> "$GITHUB_ENV"

-      - name: Install project and dev dependencies
+      - name: Install project and test dependencies
        # Matches e2e.yml; ``--extra all`` pulls the harness SDKs so the
        # executor adapters import at collection time.
-        run: uv sync --extra all --extra dev
+        run: uv sync --extra all --group test

      - name: Set up pnpm
        uses: ./.github/actions/setup-pnpm
@@ -229,8 +229,8 @@ jobs:
          path: .venv
          key: venv-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}

-      - name: Install project + dev extras
-        run: uv sync --locked --extra all --extra dev
+      - name: Install project + test dependencies
+        run: uv sync --locked --extra all --group test

      - name: Install bubblewrap + tmux
        # bubblewrap: the UI tests open terminals under os_env, whose
@@ -157,7 +157,7 @@ jobs:
      - name: Install dependencies
        # Matches ci.yml; ``--extra all`` pulls the harness SDKs so
        # executor adapters import at collection time.
-        run: uv sync --extra all --extra dev
+        run: uv sync --extra all --group test

      - name: Run pytest target
        # Inputs validated by prep. Word-splitting on $TEST_TARGET /
@@ -25,8 +25,10 @@ name: Issue Triage
 #   5. Flags incomplete issues — `needs-info` (replaces priority label)
 #   6. Optionally comments when a duplicate or related issue is found
 #      (disabled by default; never comments when nothing matches)
-#   7. Optionally closes validated high-confidence duplicates (disabled by default)
-#   8. Assigns P0/P1 issues to a maintainer via round-robin
+#   7. Assigns an owner to every triaged open issue via round-robin — duplicates
+#      included, so the owner persists if the issue is later reopened
+#   8. Optionally closes validated high-confidence duplicates (disabled by
+#      default), after the owner above is assigned

 on:
  issues:
@@ -233,7 +235,8 @@ jobs:

      - name: Install dependencies
        if: steps.creds.outputs.available == 'true'
-        run: uv sync --extra all --extra dev
+        # The tools-less triage agent emits JSON; no repository checks run.
+        run: uv sync --extra all

      - name: Install Claude Code CLI
        if: steps.creds.outputs.available == 'true'
@@ -713,40 +716,25 @@ jobs:
            exit 0
          fi

-          duplicate_decision=$(jq -r '.duplicate_decision' /tmp/triage_result.json)
-          if [ "$duplicate_decision" = "duplicate" ]; then
-            close_duplicate_issue=$(jq -r '.close_duplicate_issue' /tmp/triage_result.json)
-            if [ "$close_duplicate_issue" = "true" ]; then
-              duplicate_of=$(jq -r '.duplicate_of' /tmp/triage_result.json)
-              issue_state=$(gh issue view "$ISSUE_NUMBER" --repo "$REPO" \
-                --json state --jq '.state')
-              if [ "$issue_state" = "OPEN" ]; then
-                gh issue close "$ISSUE_NUMBER" --repo "$REPO" \
-                  --duplicate-of "$duplicate_of"
-              fi
-            else
-              echo "Duplicate closure disabled; leaving issue open."
-            fi
-            exit 0
-          fi
+          # Assign an owner to every triaged open issue, BEFORE the duplicate
+          # closure below. Duplicates get an owner too, and it persists if the
+          # issue is later reopened — triage only fires on `opened`, so a
+          # reopened issue would otherwise come back unassigned.

          # If the issue was filed by a maintainer, assign it to them directly.
          author=$(jq -r '.author.login // empty' /tmp/issue.json)
          maintainer_assigned=false
          if [ -n "$author" ] && grep -qxF "$author" .github/MAINTAINER; then
            echo "Issue filed by maintainer $author — assigning to author"
-            issue_state=$(gh issue view "$ISSUE_NUMBER" --repo "$REPO" \
-              --json state --jq '.state')
-            if [ "$issue_state" = "OPEN" ]; then
-              gh issue edit "$ISSUE_NUMBER" --repo "$REPO" --add-assignee "$author"
-              maintainer_assigned=true
-            fi
+            gh issue edit "$ISSUE_NUMBER" --repo "$REPO" --add-assignee "$author"
+            maintainer_assigned=true
          fi

          # Otherwise, assign an owner: the least-loaded area owner, with LLM
          # rank as a tiebreaker (load primary, rank secondary). Symmetric with
          # the PR reviewer path. Skipped if the maintainer-author was already
-          # assigned above. Every triaged issue gets an owner — the only issues
+          # assigned above. Every triaged issue gets an owner — duplicates
+          # included, even ones about to be closed below — so the only issues
          # left unassigned are needs_info ones (too vague to route until the
          # reporter adds detail).
          needs_info=$(jq -r '.needs_info // false' /tmp/triage_result.json)
@@ -793,11 +781,26 @@ jobs:

            assignee=$(cat /tmp/assignee.txt)
            if [ -n "$assignee" ]; then
+              gh issue edit "$ISSUE_NUMBER" --repo "$REPO" --add-assignee "$assignee"
+            fi
+          fi
+
+          # Finally, close the issue if it is a high-confidence duplicate and
+          # closure is enabled. The owner assigned above stays on the issue,
+          # ready if it is reopened.
+          duplicate_decision=$(jq -r '.duplicate_decision' /tmp/triage_result.json)
+          if [ "$duplicate_decision" = "duplicate" ]; then
+            close_duplicate_issue=$(jq -r '.close_duplicate_issue' /tmp/triage_result.json)
+            if [ "$close_duplicate_issue" = "true" ]; then
+              duplicate_of=$(jq -r '.duplicate_of' /tmp/triage_result.json)
              issue_state=$(gh issue view "$ISSUE_NUMBER" --repo "$REPO" \
                --json state --jq '.state')
              if [ "$issue_state" = "OPEN" ]; then
-                gh issue edit "$ISSUE_NUMBER" --repo "$REPO" --add-assignee "$assignee"
+                gh issue close "$ISSUE_NUMBER" --repo "$REPO" \
+                  --duplicate-of "$duplicate_of"
              fi
+            else
+              echo "Duplicate closure disabled; leaving issue open."
            fi
          fi

@@ -0,0 +1,55 @@
+name: Kustomize validate
+
+# Renders every deploy/kubernetes overlay with `kustomize build` so manifest
+# drift (duplicate bases, missing patches, invalid YAML) is caught in CI
+# rather than at deploy time. Only runs when overlay or base files change.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - 'deploy/kubernetes/**'
+  push:
+    branches:
+      - main
+      - 'release/v[0-9]*'
+    paths:
+      - 'deploy/kubernetes/**'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: kustomize-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Kustomize build (overlays)
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+
+      - name: Install kustomize
+        run: |
+          curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
+          sudo mv kustomize /usr/local/bin/
+
+      - name: Render all overlays
+        run: |
+          failed=0
+          for overlay in deploy/kubernetes/overlays/*/; do
+            name="$(basename "$overlay")"
+            echo "::group::$name"
+            if kustomize build "$overlay"; then
+              echo "::endgroup::"
+            else
+              echo "::endgroup::"
+              echo "::error::kustomize build failed for overlay '$name'"
+              failed=1
+            fi
+          done
+          exit "$failed"
@@ -75,7 +75,15 @@ jobs:
        # `--locked` is the hard gate: fails if uv.lock is out of sync with
        # pyproject.toml (a bare `uv run pre-commit` would re-lock first and mask
        # a stale lockfile). Fix locally with `uv lock`.
-        run: uv sync --locked --extra dev
+        # Pyrefly checks optional integrations against their real packages.
+        # Compose capability extras with lint tooling instead of duplicating
+        # runtime dependencies in the repository-only lint group.
+        run: |
+          uv sync --locked --group lint \
+            --extra hindsight \
+            --extra nimble \
+            --extra s3 \
+            --extra tracing

      # Sets up Node 20 + pnpm, with pnpm dependency caching keyed on the
      # workspace lockfile. pnpm is pinned in .github/actions/setup-pnpm.
@@ -164,7 +164,8 @@ jobs:

      - name: Install dependencies
        if: steps.trigger.outputs.skip != 'true' && steps.creds.outputs.available == 'true'
-        run: uv sync --extra all --extra dev
+        # Reviews a prefetched diff against trusted main; it does not run PR checks.
+        run: uv sync --extra all

      - name: Install Claude Code CLI
        if: steps.trigger.outputs.skip != 'true' && steps.creds.outputs.available == 'true'
@@ -283,7 +283,7 @@ jobs:
          enable-cache: true

      - name: Install dependencies
-        run: uv sync --extra dev
+        run: uv sync

      - name: Find previous stable release tag
        id: prev
@@ -308,7 +308,7 @@ jobs:
        if: steps.prev.outputs.found == 'true'
        run: |
          git checkout "${{ steps.prev.outputs.tag }}"
-          uv sync --extra dev
+          uv sync
          uv run --no-sync dev/benchmarks/omnigent/seed.py \
            --database-uri "sqlite:///bench.db" \
            --sessions 5000 --items-per-session 200
@@ -362,7 +362,7 @@ jobs:
          enable-cache: true

      - name: Install dependencies
-        run: uv sync --extra dev
+        run: uv sync

      - name: Run baseline benchmark
        run: |
@@ -413,7 +413,7 @@ jobs:
          enable-cache: true

      - name: Install dependencies
-        run: uv sync --extra dev
+        run: uv sync

      # The seeded bench.db is at the previous release's schema head. The
      # candidate (newer code) auto-migrates on server boot, but the z7
@@ -473,7 +473,7 @@ jobs:
          enable-cache: true

      - name: Install dependencies
-        run: uv sync --extra dev
+        run: uv sync

      - name: Download results
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -188,7 +188,8 @@ jobs:

      - name: Install dependencies
        if: steps.creds.outputs.available == 'true'
-        run: uv sync --extra all --extra dev
+        # The tools-less triage agent emits JSON; no repository checks run.
+        run: uv sync --extra all

      - name: Install Claude Code CLI
        if: steps.creds.outputs.available == 'true'
@@ -30,6 +30,23 @@ on:
  schedule:
    # Every 12 hours (00:00 and 12:00 UTC).
    - cron: "0 */12 * * *"
+  # Fast smoke on PRs that touch the server↔runner contract surface.
+  # Runs both Config 1 (new server, old runner) and Config 2 (new runner,
+  # old server) against the latest stable release so protocol regressions
+  # surface before merge, not in the overnight full matrix.
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "omnigent/runner/**"
+      - "omnigent/server/**"
+      - "omnigent/host/**"
+      - "web/src/**"
+      - "tests/e2e/**"
+      - "tests/e2e_ui/**"
+      - "tests/_helpers/compat.py"
+      - ".github/actions/compat-smoke-run/**"
+      - ".github/actions/compat-smoke-ui-run/**"
+      - ".github/workflows/server-compat.yml"

 concurrency:
  group: backcompat-${{ github.workflow }}-${{ github.sha }}
@@ -39,11 +56,118 @@ permissions:
  contents: read

 jobs:
-  # Compute the full pairwise (server, runner) matrices. Integration is the
-  # single openai-agents leg (claude-sdk/codex reject the mock LLM's
-  # "mock-model"); e2e is sharded per cell. See backcompat-pairwise-matrix.sh.
+  # ── Fast smoke: both compat configs against the latest stable release ──────
+  # Runs on every PR that touches the server↔runner contract surface (paths
+  # filter above), plus every schedule/dispatch run. Resolves the latest
+  # final (non-prerelease) tag once, then fans out to Config 1 and Config 2.
+  # The full pairwise matrix (backcompat-e2e / backcompat-integration) still
+  # runs on schedule/dispatch and covers the broader version history.
+  resolve-latest:
+    name: Resolve latest stable tag
+    # PRs: always. Schedule/dispatch: always.
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      latest_tag: ${{ steps.tag.outputs.latest_tag }}
+    steps:
+      - name: Checkout (tags only)
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          fetch-depth: 0
+          sparse-checkout: .github/scripts/ci
+          persist-credentials: false
+      - name: Resolve latest final tag
+        id: tag
+        shell: bash
+        run: |
+          # Latest final (non-prerelease) tag by version sort.
+          tag=$(git tag --sort=-v:refname \
+            | grep -viE '(^|[^a-z])(rc|dev|pre)[0-9]' \
+            | head -1)
+          if [ -z "$tag" ]; then
+            echo "No stable release tag found" >&2; exit 1
+          fi
+          echo "latest_tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "Resolved latest stable tag: $tag" >&2
+
+  compat-smoke-config1:
+    name: "Compat smoke – Config 1 (new server / old runner ${{ needs.resolve-latest.outputs.latest_tag }})"
+    needs: resolve-latest
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.number && format('refs/pull/{0}/merge', github.event.pull_request.number) || github.ref }}
+          fetch-depth: 0
+      - name: Run compat smoke (Config 1)
+        uses: ./.github/actions/compat-smoke-run
+        with:
+          runner_version: ${{ needs.resolve-latest.outputs.latest_tag }}
+          artifact_suffix: "-config1"
+
+  compat-smoke-config2:
+    name: "Compat smoke – Config 2 (new runner / old server ${{ needs.resolve-latest.outputs.latest_tag }})"
+    needs: resolve-latest
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.number && format('refs/pull/{0}/merge', github.event.pull_request.number) || github.ref }}
+          fetch-depth: 0
+      - name: Run compat smoke (Config 2)
+        uses: ./.github/actions/compat-smoke-run
+        with:
+          server_version: ${{ needs.resolve-latest.outputs.latest_tag }}
+          artifact_suffix: "-config2"
+
+  compat-smoke-ui-config-a:
+    name: "Compat smoke – UI Config A (new SPA / old server ${{ needs.resolve-latest.outputs.latest_tag }})"
+    needs: resolve-latest
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.number && format('refs/pull/{0}/merge', github.event.pull_request.number) || github.ref }}
+          fetch-depth: 0
+      - name: Run UI compat smoke (Config A)
+        uses: ./.github/actions/compat-smoke-ui-run
+        with:
+          server_version: ${{ needs.resolve-latest.outputs.latest_tag }}
+          artifact_suffix: "-ui-config-a"
+
+  compat-smoke-ui-config-b:
+    name: "Compat smoke – UI Config B (old SPA ${{ needs.resolve-latest.outputs.latest_tag }} / new server)"
+    needs: resolve-latest
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.number && format('refs/pull/{0}/merge', github.event.pull_request.number) || github.ref }}
+          fetch-depth: 0
+      - name: Run UI compat smoke (Config B)
+        uses: ./.github/actions/compat-smoke-ui-run
+        with:
+          ui_version: ${{ needs.resolve-latest.outputs.latest_tag }}
+          artifact_suffix: "-ui-config-b"
+
+  # ── Full pairwise matrix (schedule + dispatch only) ────────────────────────
+  # Compute the full pairwise (server, runner) and UI matrices.
+  # Integration is the single openai-agents leg (claude-sdk/codex reject the
+  # mock LLM's "mock-model"); e2e is sharded per cell.
+  # UI matrix is server-only (runner is always main; the SPA is always HEAD).
  setup:
    name: setup
+    # The full pairwise matrix is expensive — skip it on PR triggers (the
+    # fast smoke jobs above cover the PR case).
+    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
@@ -132,3 +256,50 @@ jobs:
          harness: ${{ matrix.harness }}
          model: ${{ matrix.model }}
          workers: ${{ matrix.workers }}
+
+  # tests/e2e_ui for every old server tag × shard (server axis only).
+  setup-ui:
+    name: setup-ui
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      ui_matrix: ${{ steps.matrix.outputs.ui_matrix }}
+    steps:
+      - name: Check out CI scripts + tags
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          sparse-checkout: .github/scripts/ci
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Compute UI matrix
+        id: matrix
+        env:
+          VERSIONS: ${{ github.event.inputs.versions }}
+          NUM_SHARDS: "3"
+        run: bash .github/scripts/ci/backcompat-ui-matrix.sh
+
+  backcompat-e2e-ui:
+    name: "Backcompat e2e-ui (Config ${{ matrix.config }}: ${{ matrix.config == 'A' && matrix.server || matrix.ui }}, shard ${{ matrix.shard_id }}/${{ matrix.num_shards }})"
+    needs: setup-ui
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      max-parallel: 6
+      matrix: ${{ fromJSON(needs.setup-ui.outputs.ui_matrix) }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+      - name: Run e2e-ui suite for this cell
+        uses: ./.github/actions/compat-smoke-ui-run
+        with:
+          server_version: ${{ matrix.server }}
+          ui_version: ${{ matrix.ui }}
+          full_suite: "true"
+          shard_id: ${{ matrix.shard_id }}
+          num_shards: ${{ matrix.num_shards }}
+          artifact_suffix: "-config${{ matrix.config }}-${{ matrix.config == 'A' && matrix.server || matrix.ui }}-shard${{ matrix.shard_id }}"
@@ -106,8 +106,8 @@ jobs:
          # the container's system Python, not the host interpreter).
          key: venv-uisnapshot-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}

-      - name: Install project + dev extras
-        run: uv sync --extra all --extra dev
+      - name: Install project + test dependencies
+        run: uv sync --extra all --group test

      # No "playwright install": the pinned image ships matching Chromium + deps
      # under $PLAYWRIGHT_BROWSERS_PATH (/ms-playwright).
@@ -157,8 +157,8 @@ jobs:
          # must not share a key or a cross-restore would mismatch.
          key: venv-uisnapshot-${{ runner.os }}-${{ hashFiles('.python-version') }}-${{ hashFiles('uv.lock') }}

-      - name: Install project + dev extras
-        run: uv sync --extra all --extra dev
+      - name: Install project + test dependencies
+        run: uv sync --extra all --group test

      # No "playwright install": the pinned image already ships matching Chromium
      # + system deps under $PLAYWRIGHT_BROWSERS_PATH (/ms-playwright), so the
@@ -0,0 +1,78 @@
+name: Waiting on Author Review Run
+
+# Privileged half of the fork-review relay. The artifact contains numeric IDs
+# only; the script re-fetches the PR and review/comment from GitHub before using
+# actor identity, review state, or comment content. No PR code is checked out.
+
+on:
+  workflow_run:
+    workflows: [Waiting on Author Review]
+    types: [completed]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: waiting-on-author-review-run-${{ github.event.workflow_run.head_sha }}
+  cancel-in-progress: false
+
+jobs:
+  hygiene:
+    if: >-
+      github.repository == 'omnigent-ai/omnigent'
+      && github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      actions: read
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Download recorded review event IDs
+        id: download
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const fs = require('fs');
+            const { owner, repo } = context.repo;
+            const arts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner, repo, run_id: context.payload.workflow_run.id,
+            });
+            const art = arts.data.artifacts.find(
+              a => a.name === 'waiting-on-author-review-event'
+            );
+            if (!art) {
+              core.info('No fork-review artifact; the direct review job handled this event.');
+              core.setOutput('found', 'false');
+              return;
+            }
+            const dl = await github.rest.actions.downloadArtifact({
+              owner, repo, artifact_id: art.id, archive_format: 'zip',
+            });
+            fs.writeFileSync(
+              `${process.env.RUNNER_TEMP}/waiting-on-author-review.zip`,
+              Buffer.from(dl.data)
+            );
+            core.setOutput('found', 'true');
+
+      - name: Check out trusted .github
+        if: steps.download.outputs.found == 'true'
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github
+          persist-credentials: false
+
+      - name: Apply relayed waiting-on-author state
+        if: steps.download.outputs.found == 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          RELAY_ZIP: ${{ runner.temp }}/waiting-on-author-review.zip
+          RELAY_DIR: ${{ runner.temp }}/waiting-on-author-review
+          WAITING_ON_AUTHOR_RELAY_EVENT: ${{ github.event.workflow_run.event }}
+          WAITING_ON_AUTHOR_RELAY_PATH: ${{ runner.temp }}/waiting-on-author-review/event.json
+        run: |
+          mkdir -p "$RELAY_DIR"
+          unzip -q "$RELAY_ZIP" -d "$RELAY_DIR"
+          python3 .github/scripts/waiting_on_author.py
@@ -0,0 +1,71 @@
+name: Waiting on Author Review
+
+# Review events on fork PRs receive a read-only token. Same-repo reviews run the
+# hygiene script directly; fork reviews record only GitHub-provided numeric IDs
+# for the privileged workflow_run consumer. No PR code is checked out.
+
+on:
+  pull_request_review_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: waiting-on-author-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  hygiene:
+    if: >-
+      github.repository == 'omnigent-ai/omnigent'
+      && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Check out .github
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github
+          persist-credentials: false
+      - name: Update waiting-on-author state
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python3 .github/scripts/waiting_on_author.py
+
+  record:
+    if: >-
+      github.repository == 'omnigent-ai/omnigent'
+      && github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - name: Record review event IDs
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PULL_NUMBER: ${{ github.event.pull_request.number }}
+          ACTIVITY_ID: ${{ github.event.review.id || github.event.comment.id }}
+        run: |
+          mkdir -p relay
+          jq -n \
+            --arg event_name "$EVENT_NAME" \
+            --argjson pull_number "$PULL_NUMBER" \
+            --argjson activity_id "$ACTIVITY_ID" \
+            '{event_name: $event_name, pull_number: $pull_number, activity_id: $activity_id}' \
+            > relay/event.json
+      - name: Upload review event IDs
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: waiting-on-author-review-event
+          path: relay/event.json
+          retention-days: 1
+          if-no-files-found: error
@@ -9,6 +9,8 @@ on:
      - .github/scripts/waiting_on_author.py
      - .github/scripts/waiting_on_author_test.py
      - .github/workflows/waiting-on-author.yml
+      - .github/workflows/waiting-on-author-review.yml
+      - .github/workflows/waiting-on-author-review-run.yml
      - .github/workflows/waiting-on-author-test.yml
  workflow_dispatch:

@@ -6,16 +6,14 @@ name: Waiting on Author Hygiene
 # once a review is submitted). The two labels are mutually exclusive. PRs left
 # waiting on the author for 7 days are closed. The workflow runs from trusted
 # default-branch code and never checks out PR-authored files.
+# Review events use the read-only -> workflow_run relay in
+# waiting-on-author-review.yml and waiting-on-author-review-run.yml.

 on:
  pull_request_target:
    types: [synchronize, labeled]
  issue_comment:
    types: [created]
-  pull_request_review_comment:
-    types: [created]
-  pull_request_review:
-    types: [submitted]
  schedule:
    - cron: "0 */12 * * *"
  workflow_dispatch:
@@ -50,7 +50,8 @@ jobs:
          enable-cache: true

      - name: Install dependencies
-        run: uv sync --locked --extra dev
+        # tests/inner includes tracing tests that import the OpenTelemetry SDK.
+        run: uv sync --locked --group test --extra tracing

      - name: Import + CLI smoke
        run: |
@@ -142,7 +142,7 @@ repos:

      # Fail if routing.proto changed without regenerating the committed
      # bindings (or vice versa). Verify-only, not a fixer: regen needs
-      # grpcio-tools, so CI's `uv sync --extra dev` enforces it (like ktlint).
+      # grpcio-tools, so CI's `uv sync --group lint` enforces it (like ktlint).
      - id: routing-pb2-fresh
        name: routing protobuf bindings are up to date
        language: system
@@ -5,6 +5,183 @@ generated at release time from each PR's `## Changelog` section, tagged by the
 PR's `Type of change` (e.g. `[UI]`); the concise, curated highlights live on the
 website under `/releases`.

+## [v0.10.0] — 2026-08-19
+
+- [Bug fix / Test/CI] Host daemons now honor standard proxy environment variables without forwarding (#1029)
+- [UI / Feature] Route host- and session-scoped server requests to the replica holding the host's tunnel, and signal `wrong_replica` (HTTP 400 / WS 4400) so clients re-address on a miss. (#2037)
+- [Bug fix] Keep `serve-mcp` responsive to pings and additional requests during slow tool calls. (#2813)
+- [UI / Feature / Docs / Test/CI] White-label the web UI from server config with custom names, headings, safe logo assets, favicon, and optional Omnigent attribution. (#2857)
+- [Bug fix] A transient server hiccup no longer pins a session to the wrong working directory for the rest of the conversation. (#3017)
+- [Bug fix] Claude SDK agents now discover large MCP tool definitions on demand instead of loading every schema up front. (#3134)
+- [Bug fix / Docs] Sub-agents no longer inherit their parent's bundle directory (skills, local tools); resolvable children use their own, while unresolvable children never fall back to the parent's (#3567)
+- [UI / Bug fix] Native-harness sessions no longer leave a stale duplicate of your message (or of the assistant's reply) pinned to the bottom of the web transcript. (#3595)
+- [Feature] GitHub policy blocks tag pushes (`--tags` / `--follow-tags` / `refs/tags/` refspecs) by default; opt out with `deny_tag_push: false`. (#3620)
+- [Bug fix] Server URLs and log paths in `omni host status` are now proper clickable links instead of text the terminal has to guess at (#3862)
+- [UI / Bug fix / Feature] agy sessions now mirror tool calls and sub-agents into the web UI, and no longer duplicate or truncate replies (#3890)
+- [Bug fix] `force_sandbox` (and any declared `os_env.sandbox`) now actually applies to a Claude Code native session's file/shell tools, not just the terminal process (#3910)
+- [Bug fix] Native sessions no longer fail with "terminal failed to start" when the host daemon was launched from a directory that has since been deleted (#3974)
+- [UI / Feature] The server can offer several sandbox providers at once (`sandbox.providers`), and the new-session picker lists one option per provider (#4006)
+- [Bug fix / Feature / Chore] Switching between conversations is instant — background conversations stay connected, so returning to one shows messages that arrived while you were away (#4113)
+- [Bug fix] `omnigent pi` now uses each model's real context window and output limit, instead of compacting early and truncating long replies on high-context models. (#4178)
+- [Feature] Route a host's tunnel, its runners, and its session traffic to one replica so multi-replica deployments keep host-scoped requests sticky. (#4185)
+- [Bug fix] A custom agent that declares its own provider auth now launches on codex-native instead of stalling on the Codex sign-in screen. (#4208)
+- [Bug fix] `omnigent server --host 0.0.0.0` with `OMNIGENT_LOCAL_SINGLE_USER=1` no longer 401s every request and 403s the host tunnel; the single-user marker is honored on network-exposed binds, with a warning that the server serves unauthenticated requests (#4224)
+- [UI / Bug fix] New chats in a project with a default base branch now fork a fresh branch off that default instead of reopening your last-used worktree (#4229)
+- [UI] New-chat landing header uses tighter Otto sizing and responsive headline scale (#4233)
+- [Bug fix] Changing effort or model mid-conversation on a Claude Code session no longer risks wedging the terminal or silently keeping the old setting. (#4250)
+- [Bug fix] `omnigent chat <remote-url>` can now start a new conversation with an agent registered on the remote server (#4260)
+- [UI / Bug fix] Collapsed "Worked for …" rows in a chat transcript now sit at an even spacing and draw their full-width divider (#4284)
+- [UI / Bug fix] Voice dictation now inserts text at your cursor instead of appending it to the end of the composer (#4290)
+- [UI / Feature] The file panel can now browse anywhere the session can reach, not just the folder it started in (#4306)
+- [UI / Bug fix] Navigating to another session while a new one is still being created no longer yanks you into the new session when it finishes (#4307)
+- [UI / Bug fix] New polly and debby sessions now show the same "Starting up…" spinner as claude-code, instead of a "Connecting…" row under the composer (#4312)
+- [Bug fix] Duplicate-detection comments no longer ask you to close your issue when the matching issue is already closed — an already-fixed match now asks whether you're on a build with the fix, and treats a still-reproducing report as a regression. (#4313)
+- [Bug fix] Kimi and Hermes sessions launch again — their version checks compared against the wrong version series and rejected every current CLI. (#4314)
+- [UI / Feature] Organizations can preconfigure Omnigent server URLs through Android managed configuration, and they show up ready to tap in the app's server list. (#4315)
+- [Feature] `omnigent host --background` starts the local server and registers this machine as a host without tying up a terminal. (#4317)
+- [UI / Breaking] Reverts the shared-session approval-authority and message-attribution features (#2150 stack); session approvals are again available to any shared editor. (#4318)
+- [UI] Administrators can preset the iOS app's server URLs with a managed app configuration, so managed users pick their organization's server instead of typing it (#4319)
+- [Bug fix] Fixed a bug where an archived session (or an archived sub-agent) could be gated as if it had spent nothing, letting a tool call proceed over its actual budget. (#4320)
+- [Feature] `omnigent start` starts the local server and registers this machine as a host — the on switch to go with `omnigent stop`. (#4321)
+- [Bug fix / Test/CI] Fix `omnidev` restart loop on Linux caused by non-mutating file access events (#4330)
+- [Feature / Docs] Issue triage now explains its impact assessment and priority in one bot comment instead of adding severity labels. (#4334)
+- [UI / Bug fix] Opening the left sidebar no longer squeezes the chat below its minimum width — the browser/workspace panel yields instead and restores its width when the sidebar collapses. (#4337)
+- [Bug fix] Pi sessions on a Databricks workspace no longer hang when the workspace model list is unavailable — non-Claude models are routed by family, and a model that truly can't be served now says so instead of never replying (#4339)
+- [Chore] Files in the viewer load faster — workspace-file reads are now gzipped, cutting a 1 MB text file from ~2.3 s to ~1.3 s (#4341)
+- [Bug fix / Chore] A claude-native session no longer shows "Working…" forever when Claude exits (#4344)
+- [UI] The sidebar "Needs response" badge now uses the brand accent color (pink by default), matching the unread indicator. (#4346)
+- [UI] Refreshed modal styling — larger rounded corners, softer drop shadow, and roomier padding (#4347)
+- [Bug fix] Pi sessions on a proxy that exposes both Anthropic and OpenAI surfaces now send each model to the surface its family speaks, instead of routing everything through Anthropic and hanging (#4348)
+- [Bug fix] Session snapshots no longer fail when a session contains a malformed legacy agent id. (#4350)
+- [Bug fix] A session whose message the runner refuses now reports the failure and its reason instead of appearing to finish successfully. (#4354)
+- [UI / Feature] Hover the collapsed sidebar toggle to peek the conversation list without pinning it open. (#4355)
+- [Bug fix] Generic-ACP / Goose / Qwen turns that fail now report the exception type instead of a blank "inner executor error: " with no detail. (#4362)
+- [UI / Bug fix] Messages sent from the chat UI no longer stop reaching the agent after a dropped network request (#4366)
+- [UI / Chore] The Files panel is now split into separate **Files** (folder tree) and **Changes** (changed files) tabs (#4367)
+- [UI / Feature] Chat messages now show their timestamp beside the Copy/Fork actions. (#4372)
+- [Bug fix] A conversation link copied from your browser now works wherever a server URL is expected, instead of failing later with an opaque "Method Not Allowed" crash (#4374)
+- [UI / Bug fix / Test/CI] Clicking a sidebar session that needs a response no longer runs its title under the "Needs response" tag, and the Inbox count badge now matches the sidebar's pink accent (#4375)
+- [UI / Bug fix] Maximized workspace panel no longer shows chat content through a transparent background in dark mode. (#4376)
+- [Bug fix] Agents now inherit your ssh-agent, so git-over-SSH and SSH-cert-authenticated tooling work in agent shells and terminals (#4377)
+- [Bug fix] The sidebar remembers your session filter across reloads instead of resetting to "All sessions" (#4381)
+- [Feature / Docs / Test/CI] Blaxel is now available as a sandbox provider for CLI and managed-host deployments. (#4383)
+- [UI] The Chat/Terminal switcher is now a segmented toggle — both views are visible at a glance and switching takes one click (#4385)
+- [Bug fix / Feature] `omnigent run --server local` runs against a local server, overriding any configured server default — and the no-AGENT `omnigent run --server ""` no longer fails with `Agent path not found: https:` (#4387)
+- [UI / Bug fix] Terminal-first sessions return to chat automatically when the runner stops or disconnects, instead of stranding on an empty "No terminals available" terminal view (#4388)
+- [Bug fix] The `build-omnigent` skill is available again in native `omnigent claude` and `omnigent codex` sessions (#4391)
+- [Bug fix] A custom ACP agent can declare the environment variables it authenticates with via `env_passthrough`, and a stalled ACP handshake now reports which call timed out instead of failing with an empty message. (#4392)
+- [Bug fix / Feature] The Copilot harness now authenticates with your existing `gh auth login` session, and a GitHub Enterprise host can be set via `omnigent setup` (#4396)
+- [Bug fix] MCP server configs can now use `${VAR}` placeholders in the `url` field, not just in `headers` — so a config can be committed to version control without hardcoding the endpoint. (#4398)
+- [Bug fix] `kimi-native` sub-agents honor `executor.config.yolo: true` (launching `kimi --yolo`) and `antigravity-native` sub-agents honor `permission_mode: bypassPermissions`, so server-spawned workers no longer stall on interactive approval prompts. (#4401)
+- [Bug fix] Resuming a claude-native session no longer drops a message sent right after the session starts. (#4403)
+- [Bug fix] A sub-agent session no longer logs a spurious "did not resolve in the parent spec" warning on every turn. (#4435)
+- [UI / Bug fix] Bulk-select sessions and move them to a project in one action via the new folder icon in the selection bar. (#4452)
+- [UI] Codex's bypass-approvals option now matches Claude's clean permission UX — no more red warning banners (#4467)
+- [Bug fix] Compaction snapshots no longer store raw image data, which cuts the size of newly written compacted conversation rows substantially. (#4470)
+- [UI / Bug fix] The new-session workspace picker now navigates to `~/…` paths and shows a clear error when a typed path doesn't exist (#4480)
+- [UI / Feature] Harness launch failures now show a clear title, cause, and suggested fix instead of a raw error code and truncated log tail. (#4485)
+- [UI / Feature] Sub-agents are now auto-assigned readable structured names (e.g. `researcher-1`) and a task-derived display label in the Agents panel (#4489)
+- [UI] Restored the down chevrons on the new-session composer's chips and made every dropdown trigger show a pointer cursor (#4493)
+- [UI / Bug fix] Modal dialogs and the workspace "Open new" menu no longer render behind the embedded browser pane (#4500)
+- [Bug fix] Named `sys_session_send` no longer returns a spurious 404 on the second and later sub-agent sends from a bundled agent (#4501)
+- [Bug fix] Session search no longer hangs on "Searching…" — content search is now backed by a trigram index and bounded by a timeout. (#4502)
+- [Bug fix / Test/CI] Fixes an HTTP client resource leak when OpenAI Agents SDK executors shut down. (#4508)
+- [Bug fix / Test/CI] Honor OmnigentClient timeout for ordinary Python SDK HTTP requests. (#4509)
+- [Bug fix] Sessions ride out brief runner-tunnel drops (laptop sleep-wake, ingress recycles) without flashing Failed or truncating the streaming reply. (#4516)
+- [Bug fix] `omnigent` no longer crashes on startup when your shell sets a SOCKS proxy (e.g. `ALL_PROXY=socks5://…`) and the `httpx[socks]` extra isn't installed (#4517)
+- [UI / Bug fix] Attaching an unsupported file in a new chat now tells you why up front and keeps your message instead of losing it (#4519)
+- [Bug fix] `omni` now works on machines with an HTTP proxy configured, and reports an unreachable server as a clear error instead of a crash. (#4520)
+- [Bug fix] Sessions that outlive their 60-minute runner bearer no longer permanently lose runner→server auth when the token re-mint is rejected — the runner now falls back to the machine's SDK/OIDC credential. (#4521)
+- [Bug fix] Harness logs now go to a file under `~/.omnigent/logs/harness/` (or the runner's log), and a failing ACP turn quotes the agent's own error output instead of dropping it. (#4523)
+- [Bug fix] An `openai-agents` agent with no pinned model no longer fails with a confusing "install databricks-sdk" error when only OpenAI credentials are missing (#4526)
+- [Bug fix] Claude native sessions now report per-turn token usage (`gen_ai.usage.input_tokens` / `output_tokens`) to MLflow and other OpenTelemetry backends. (#4530)
+- [UI / Bug fix / Feature] Move a running session to another machine from the host badge in the composer. (#4531)
+- [Bug fix] Upgrading omnigent in place no longer breaks harness launches on already-running runners (#4539)
+- [Chore] The session-search index migration builds its Postgres indexes concurrently, so upgrades no longer block writes while the indexes build. (#4541)
+- [Feature] The Android app now opens Databricks workspaces on their `/omnigent` app instead of the workspace landing page. (#4543)
+- [Bug fix] `omnigent host` pointed at a local server that has exited now stops after ~5 minutes with a clear error instead of reconnecting forever. (#4544)
+- [Bug fix] Runners no longer crash-loop at session start when signal-handler registration fails; they log one warning and keep working. (#4545)
+- [Bug fix] Session search now returns results instead of timing out on large workspaces. (#4546)
+- [UI / Bug fix] Modal buttons like Stop session and Clone now show a spinner while the action is running, instead of just greying out. (#4548)
+- [UI / Bug fix] The desktop server picker moved from the window title bar to the bottom of the sidebar, fixing an overlap with the chat header on narrow windows — and Windows and Linux desktop now have it too (#4551)
+- [UI] The embedded terminal connects in the background and stays connected across Chat/Terminal flips and recent-session switches, so opening it is near-instant instead of reconnecting every time. (#4552)
+- [Bug fix] The Android app no longer shows the Databricks workspace navigation bar around Omnigent when connecting to a workspace-hosted server. (#4555)
+- [UI / Feature] On the macOS desktop app, the sidebar header now shares the title-bar row with the window controls — the empty strip above the sidebar and the redundant wordmark row are gone, and the Collapse/Search/Settings buttons sit beside the traffic lights. (#4557)
+- [Bug fix] Codex sessions on a ChatGPT-account or API-key login launch again, instead of failing with "model is not supported when using Codex with a ChatGPT account" (#4558)
+- [UI] Connecting the iOS app to a Databricks workspace now opens Omnigent directly and hides the workspace navigation bar (#4559)
+- [Bug fix] kiro sessions no longer fail the first message with a connection error when the kiro TUI is slow to start (#4562)
+- [Bug fix] `omnigent host` now warns once and backs off when a server accepts connections but never responds, waits out (up to 120s) a slow-booting local server instead of stranding it — stopping it if it truly fails — recovers fast runner starts after a zygote crash, and no longer leaves empty log files behind. (#4563)
+- [Bug fix] Named `sys_session_send` no longer returns a spurious 404 on the second and later sub-agent sends from a bundled agent (#4564)
+- [UI / Bug fix] Deleting a session removes it from the sidebar immediately instead of waiting for the server to finish tearing it down (#4566)
+- [Bug fix] Session search no longer times out on large workspaces. (#4567)
+- [UI / Bug fix] Fixed iOS controls rendering under the status bar on Databricks workspace-hosted servers (#4568)
+- [UI / Feature] You can now leave a session someone shared with you — pick "Leave session" from its sidebar row menu to clear it from your sidebar without asking the owner (#4571)
+- [UI / Bug fix] The workspace Files panel now shows hidden files by default, and its eye icon shows whether they are visible rather than what clicking will do. (#4575)
+- [Bug fix] Switching a session's agent now updates the tools its native harness can call, instead of leaving the previous agent's tools in place (#4576)
+- [Bug fix] The native pane reaper no longer kills a terminal that is actively producing output when the harness status pipeline stalls; it now checks tmux's own activity clock before reaping. (#4577)
+- [Bug fix] A silently stalled claude-native transcript forwarder now self-recovers within five minutes and logs exactly where it stalled, instead of freezing mirroring and session status indefinitely. (#4578)
+- [Bug fix] A claude-native transcript forwarder that stops — cancelled, crashed, or returned — now always logs an attributed exit line instead of dying silently. (#4579)
+- [Bug fix] A stray hook event from another Claude session can no longer silently redirect a claude-native session's transcript mirroring; session identity now changes only via SessionStart announcements. (#4580)
+- [Bug fix] `omni claude` streaming, statusline, and typing during tool-running turns now respond at native speed: hook subprocesses skip the framework's eager import graph, and the blocking hook path runs as shell + a loopback `curl` relayed by the long-lived runner instead of spawning a Python interpreter per event. (#4582)
+- [UI / Bug fix / Feature] Fork a sub-agent to promote it into a top-level session of its own. (#4584)
+- [Bug fix] Upgrading omnigent in place no longer breaks runner launches on already-running hosts (#4587)
+- [UI / Bug fix] Native-harness sessions no longer briefly drop your in-flight message bubble when an interrupt marker is reconciled at the same time. (#4591)
+- [UI / Bug fix / Chore] Native assistant text now reconciles cleanly with committed transcript messages without duplicate streaming output. (#4593)
+- [Bug fix] The embedded browser pane no longer lingers over the welcome screen after switching or disconnecting from a server (#4595)
+- [Chore] Removed the "A new version of Omnigent is available" prompt and browser PWA install support; the desktop and mobile apps remain the installable clients. (#4617)
+- [Chore] OpenTelemetry exporters and automatic instrumentors are now installed through `omnigent[tracing]` instead of the default package. (#4621)
+- [Bug fix] Development builds no longer show an update reminder for the matching final release. (#4628)
+- [Bug fix] `omni host` no longer prints a zygote traceback — and keeps copy-on-write runner forking — when started from a directory that contains an `omnigent` checkout (#4631)
+- [UI / Bug fix] Clicking a file an agent mentions in its reply now opens it, including `path:line` citations and markdown links (#4644)
+- [UI / Bug fix] Fixed long unbroken text or inline code in chat messages overflowing or getting cut off at narrow window widths. (#4651)
+- [Bug fix] Fixed a duplicate assistant message that could appear after reconnecting to a Claude Code (native) session (#4656)
+- [Bug fix / Chore] Resuming or forking a Claude Code session containing screenshots no longer duplicates image payloads into metadata and inflates the request past the context limit. (#4659)
+- [UI / Bug fix] Archiving the current session now redirects to the home page instead of leaving you on the archived session (#4671)
+- [UI / Feature] Usage page shows session costs, daily spend timeline, and breakdowns by harness and model (#4673)
+- [Bug fix] Sessions whose workspace is an omnigent checkout no longer run a different omnigent than the one you installed (#4688)
+- [Bug fix] `omnigent run --harness acp:<agent>` now launches the ACP agent you asked for instead of the first one configured (#4689)
+- [UI / Bug fix] The desktop app now auto-selects this machine after "Run on this machine" (#4691)
+- [UI / Bug fix] The managed sandbox host option (and other capability-gated UI) now appears on its own after a slow `/v1/info` probe, instead of staying hidden until a page reload. (#4694)
+- [Chore] Runner-backed resource APIs now avoid redundant session reads, improving responsiveness under load. (#4695)
+- [Bug fix] ACP agents now report cached-read tokens, so token usage reflects what was actually billed (#4699)
+- [Bug fix] Built-in ACP agents like Grok Build now appear in `omni setup` instead of being invisible (#4700)
+- [Bug fix] `omnigent run --harness acp:<slug>` now works with remote servers by resolving the slug client-side and embedding the full agent config in the spec. ACP agent settings (session_id_mode, send_model, omnigent_mcp, env_passthrough) are now preserved through embedding. (#4702)
+- [Bug fix / Feature] `/model` now switches an ACP agent's model mid-conversation instead of being ignored, and keeps the chat history (#4703)
+- [Bug fix] A host name set in `config.yaml` is now kept when no `host_id` is present — the id is generated instead of overwriting your chosen name. (#4708)
+- [Bug fix] `omnigent resume` now lists only your own sessions, not ones shared with you (#4709)
+- [UI / Bug fix] The Inbox count badge now uses the same text and background colors as the selected session item in the sidebar (#4714)
+- [UI / Feature] Multi-session delete now shows a table of worktree branches you can pick to clean up (with a tri-state select-all header), instead of blocking branch cleanup behind single-session delete (#4715)
+- [Bug fix] OpenCode 1.18.x installs are now accepted; the version gate no longer rejects users who installed OpenCode via its official upstream route. (#4725)
+- [UI / Bug fix / Chore / Test/CI] Approval prompts now name the assistant that asked (Claude Code, Codex, Cursor, Antigravity, Kiro, Goose, Qwen Code, Hermes) instead of an internal policy id (#4735)
+- [UI / Bug fix] Opening the workspace folder browser no longer flashes an "Up one level" tooltip over the listing (#4742)
+- [Feature] Kubernetes sandbox runners now use Jobs with automatic restart on crash (up to 3 retries) and a liveness probe, replacing bare Pods that required manual intervention after a failure. (#4744)
+- [UI / Bug fix] The chat transcript now detects a silently dead live connection and reconnects on its own — worst case 45 s, instantly on tab refocus — instead of freezing until the page is reloaded. (#4750)
+- [Bug fix] Chat messages sent while the terminal's Claude composer is covered by the ctrl+r history search or a hand-opened `/model` picker now dismiss the overlay and deliver, instead of silently vanishing (#4751)
+- [Bug fix] Creating a session from the web UI is faster end-to-end: the chat page opens immediately and the terminal is ready sooner — including the first session after a host restart, which no longer pays a multi-second warmup. (#4752)
+- [UI / Bug fix] Answered question and plan cards stay outside the "Worked for" fold, read as settled, and survive a page reload (#4760)
+- [UI / Feature] Web terminals now attach directly over loopback when the runner is on the same machine as the browser, cutting keystroke echo from ~250 ms to under 10 ms against a remote server. (#4763)
+- [UI / Bug fix / Test/CI] The Sessions filter is now always visible, so session filtering is discoverable without hovering the sidebar header. (#4764)
+- [Feature] New `OMNIGENT_REQUIRE_WRAPPER` env var lets operators require the CLI be run through a wrapper (e.g. `isaac omni`) and refuse direct `omni` calls (#4766)
+- [UI / Bug fix / Chore / Test/CI] Chat output stays visible above a growing composer; bottom-following readers remain pinned while readers who scroll up—even just 50px—keep the same visible content. (#4767)
+- [Bug fix] `omnidev --vite-port` once again starts the frontend on the requested port. (#4770)
+- [Feature / Test/CI] macOS desktop app now ships an Intel (x64) build alongside Apple Silicon. (#4772)
+- [UI / Feature / Docs] Usage and web-driven harness setup can now be enabled per deployment with `OMNIGENT_FEATURES`. (#4775)
+- [UI / Bug fix / Feature] In-chat errors now provide expandable diagnostics and recovery-aware Retry, copy, and dismiss actions without replaying failed input, and cancelled retry requests no longer leave stale recovery results cached. (#4787)
+- [Feature / Docs] ArgoCD quick-start overlay for deploying Omnigent with the kubernetes sandbox provider (#4788)
+- [Bug fix] `omnigent[antigravity]` no longer crashes with a protobuf gencode/runtime version mismatch on startup. (#4795)
+- [UI / Bug fix] Server URLs in copyable connection and reconnect commands are now safely quoted. (#4817)
+- [Bug fix] Resumed Codex conversations now keep the authentication provider selected in Codex configuration. (#4818)
+- [Bug fix] `omnidev omnigent` commands now keep runtime state and configuration inside their development pod. (#4822)
+- [Bug fix] Native Windows: harness CLIs (codex, pi, claude-sdk, antigravity) no longer hang on spawn due to missing `SYSTEMROOT`/`COMSPEC`; Windows drive-letter workspace paths (`C:\…`) are now accepted; pre-release harness CLI versions (e.g. `0.146.0-alpha.9.2`) no longer fail the version gate. (#4886)
+- [UI / Feature] Background tasks that keep running after a turn ends now show as a pill above the composer instead of a "Working…" spinner (#4893)
+- [UI / Bug fix] Maximizing the workspace panel in the desktop app no longer tucks its tab icons under the macOS window controls. (#4897)
+- [Feature] Configured ACP agents (e.g. Devin) and installed ACP CLI harnesses (e.g. Grok Build) now appear in the web New Chat picker, like the native harnesses (#4909)
+- [Bug fix] Managed codex, claude-sdk (Polly/Debby), and pi harnesses resolve their launch model from the workspace's Unity Catalog model services, so they no longer fail against a Databricks AI Gateway that has retired the legacy `databricks-*` model namespace (#4915)
+- [UI / Feature] Devin is now a built-in harness — set it up in `omni setup`, launch it with `--harness devin` or from the New Chat picker, no `acp:` config needed (#4920)
+- [Bug fix] `omni setup` and the New Chat picker no longer show a duplicate — or silently ignore — a built-in ACP harness you configured yourself under the same name; your own command wins. (#4927)
+- [UI] Chat error banners are now a compact centered pill with inline Retry, matching the design prototype (#4931)
+- [UI / Feature] The chat header now shows the conversation's name, its project folder, and the sub-agent path, and title bars are a consistent 48px. (#4940)
+
 ## [v0.9.0] — 2026-08-11

 - [UI / Bug fix] Recent servers remain one-click connectable and now include a separate copy action. (#2555)
@@ -85,19 +85,23 @@ cd omnigent

 uv python install
 uv venv --python "$(cat .python-version)"
-uv sync --extra all --extra dev
+uv sync --extra all --group dev
 source .venv/bin/activate    # or prefix commands with `uv run`
 ```

+Repository-only dependencies use PEP 735 groups: `lint` for static checks and
+code generation, `test` for pytest, and `dev` for both. Product capabilities
+remain installable extras. Plain `uv sync` installs neither group by default.
+
 Common checks:

 Pyrefly is the canonical Python type checker for the repository.

 ```bash
-uv run pytest                      # Python tests (e2e/live skipped by default)
-uv run ruff check . && uv run ruff format --check .
-uv run --no-sync pyrefly check     # Python type checking (core and client SDK)
-uv run pre-commit run --all-files
+uv run --no-sync pytest                      # Python tests (e2e/live skipped by default)
+uv run --no-sync ruff check . && uv run --no-sync ruff format --check .
+uv run --no-sync pyrefly check               # Python type checking (core and client SDK)
+uv run --no-sync pre-commit run --all-files
 ```

 When touching `web/`:
@@ -135,7 +139,7 @@ test. A fresh worktree needs its own Python environment first:

 ```bash
 cd /path/to/omnigent-worktree
-uv sync --extra all --extra dev
+uv sync --extra all --group dev
 omnidev
 ```

@@ -365,8 +365,10 @@ Face Spaces**, **Modal**, **Cloudflare** (serverless, scale-to-zero), and
 covered too — and a **Cloudflare quick tunnel** (public) or **Tailscale**
 (private) reaches a server running on your own laptop without a deploy. The
 server can also provision a cloud sandbox per session (*managed hosts*), so no
-laptop has to stay online. The full menu of targets, the database options, and
-the sandbox setup live in
+laptop has to stay online. The full menu of targets, the database options, the
+sandbox setup, and
+[branding/white-labeling](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md#branding-white-labeling)
+live in
 [`deploy/README.md`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md).

 Once the server is up, sign in and register your laptop as a host:
@@ -411,6 +413,9 @@ and they're in. Signup is invite-only.

 - **Share a live session.** Hit **Share** in the web UI and send the link;
  teammates watch your agent work and chat with it in real time.
+- **Leave a shared session.** Done with a session someone shared with you?
+  Pick **Leave session** from its sidebar row menu to drop it from your
+  sidebar. Nothing is deleted — the owner keeps it and can share it again.
 - **Co-drive.** A teammate co-attaches to your running session; their
  messages execute on **your** machine. Great for pairing or handing the
  keyboard to a domain expert mid-investigation.
@@ -498,6 +498,40 @@ to set and sanitize the identity header, and read
 [`docker/README.md#header-proxy-mode-for-deploys-behind-an-existing-sso-proxy`](docker/README.md#header-proxy-mode-for-deploys-behind-an-existing-sso-proxy)
 first.

+## Branding (white-labeling)
+
+Customize the app name, landing heading, and logos with a `branding:` block in
+the server config (`omnigent server -c config.yaml`, or `<data_dir>/config.yaml`
+— `/data/config.yaml` in the Docker stack). Takes effect on the next server
+start.
+
+```yaml
+branding:
+  app_name: "Acme Agent"        # tab title, sidebar wordmark, login screen
+  heading: "How can I help?"     # landing hero; "" hides it, omit to keep the default
+  logo:                          # a bare string sets `main`; or per-variant:
+    main: logo.png               # branding-assets/logo.png
+    loading: loading.webp        # working indicator (falls back to main)
+    favicon: favicon.png         # browser-tab icon
+  powered_by: true               # "Powered by Omnigent" credit; false to hide
+```
+
+Logo files must live under a dedicated `branding-assets/` directory beside the
+config file (for example, `/data/branding-assets/logo.png`). PNG, JPEG, GIF,
+WebP, and ICO files up to 5 MiB are accepted only after full decoder validation.
+ICO files must contain only PNG-backed entries; every directory entry is bounded
+and decoded independently, while DIB/BMP-backed entries are rejected. Malformed,
+truncated, oversized, overlapping, trailing-payload, SVG, symlinked, escaped, and
+non-image files are ignored. Images are also bounded to 4096 pixels per side,
+128 frames, 16 megapixels per frame, and 64 megapixels across all decoded frames.
+The values are served over the unauthenticated `GET /v1/info` and
+`GET /v1/branding/logo/<variant>` endpoints so the login screen is branded before
+sign-in. Any unset field keeps its built-in default, so a partial block is fine.
+
+The small "Powered by Omnigent" credit under the landing composer appears only
+once you set custom branding; `powered_by: false` hides it even then. It always
+shows the Omnigent mascot, never your logo.
+
 ## Adding a new deploy target

 Drop a new subdirectory under `deploy/<target>/` with a `README.md`
@@ -147,6 +147,17 @@ UC Volume wheel paths because `uv lock` validates path sources locally.

 Re-running is safe — every step is idempotent.

+Release features are off by default. Enable one or more for the whole app by
+adding the comma-separated deploy argument, then reload the web app after the
+redeploy:
+
+```bash
+--features usage_page,harness_install
+```
+
+See [`designs/FEATURE_FLAGS.md`](../../designs/FEATURE_FLAGS.md) for the current
+inventory and rollback procedure.
+
 > [!TIP]
 > To lock against a private PyPI mirror or proxy instead of public
 > PyPI, set `UV_INDEX_URL` before running `deploy.py`.
@@ -21,6 +21,9 @@ variables:
      UC schema (catalog.schema) holding the OTel destination tables.
      The platform writes to <schema>.otel_logs, otel_metrics, otel_spans.
    default: main.omnigent_logs
+  features:
+    description: "Comma-separated deployment-wide release features."
+    default: ""

 resources:
  apps:
@@ -44,6 +47,8 @@ resources:
            value_from: artifact_volume
          - name: OTEL_TRACES_SAMPLER
            value: 'always_on'
+          - name: OMNIGENT_FEATURES
+            value: "${var.features}"
      resources:
        - name: postgres
          postgres:
@@ -567,6 +567,14 @@ def _parse_args() -> argparse.Namespace:
            "<schema>.otel_{logs,metrics,spans}."
        ),
    )
+    parser.add_argument(
+        "--features",
+        default="",
+        help=(
+            "Comma-separated deployment-wide release features, e.g. "
+            "'usage_page'. Empty keeps every release feature off."
+        ),
+    )
    parser.add_argument(
        "--target",
        default="prod",
@@ -746,6 +754,8 @@ def _bundle_vars(args: argparse.Namespace) -> list[str]:
        f"volume_name={args.volume_name}",
        "--var",
        f"otel_table_schema={args.otel_table_schema}",
+        "--var",
+        f"features={args.features}",
    ]


@@ -15,6 +15,12 @@ POSTGRES_PASSWORD=change-me-please
 # Host port the omnigent container is published on. Default 8000.
 # OMNIGENT_PORT=8000

+# ── Release features ─────────────────────────────────────
+# Comma-separated deployment-wide release features. Empty/unset keeps every
+# release feature off. Unknown names fail startup so typos cannot silently
+# change rollout behavior. Current keys: usage_page, harness_install.
+# OMNIGENT_FEATURES=usage_page
+
 # ── Image ────────────────────────────────────────────────
 # The compose stack pulls a pre-built image from GHCR (built by CI on
 # every main-branch merge). Default: ghcr.io/omnigent-ai/omnigent-server.
@@ -153,6 +159,13 @@ POSTGRES_PASSWORD=change-me-please

 # ── Optional OIDC tuning ─────────────────────────────────
 # OMNIGENT_OIDC_SESSION_TTL_HOURS=8
+#
+# Absolute lifetime (days) of login-issued refresh grants — how long a
+# host/CLI that logged in with `omnigent login` can keep renewing its
+# access before a human must log in again. Default 30. Unattended hosts
+# renew automatically within this window; each host replica needs its
+# own login (refresh tokens rotate — shared copies revoke each other).
+# OMNIGENT_GRANT_MAX_LIFETIME_DAYS=30
 # OMNIGENT_OIDC_LOGOUT_REDIRECT_URI=https://omnigent.example.com/
 #
 # Skip the email_verified claim check on id_tokens. Some IdPs (e.g.
@@ -39,6 +39,27 @@ Reset everything (drops the DB and the artifact store):
 docker compose down -v
 ```

+## Release features
+
+Release features are deployment-wide and off by default. Enable one or more
+with the comma-separated `OMNIGENT_FEATURES` variable in `.env`, then recreate
+the server container:
+
+```dotenv
+OMNIGENT_FEATURES=usage_page
+```
+
+```bash
+docker compose up -d
+curl -s http://localhost:8000/v1/info | jq '.features'
+```
+
+Known keys and their lifecycle are documented in
+[`designs/FEATURE_FLAGS.md`](../../designs/FEATURE_FLAGS.md). Unknown keys fail
+server startup so a typo cannot silently produce the wrong rollout. To roll
+back, remove the key (or empty the variable), run `docker compose up -d` again,
+and reload the web app.
+
 ## Multi-user mode (accounts — default)

 Built-in accounts auth: no IdP to register, no proxy to host.
@@ -47,3 +47,16 @@ allowed_domains:
 # the built-in defaults (20 files / 256 MiB total).
 # copy_max_files: 20
 # copy_max_total_bytes: 268435456
+
+# Branding / white-labeling. Customize the app name, landing heading, and
+# logos shown in the web UI. Logo files must live under branding-assets/ beside
+# this config file; served pre-auth so the login screen is branded too. Any unset
+# field keeps its built-in default. See deploy/README.md#branding-white-labeling.
+# branding:
+#   app_name: "Acme Agent"      # tab title, sidebar wordmark, login screen
+#   heading: "How can I help?"   # landing hero; "" hides it, omit for the default
+#   logo:                        # a bare string sets `main`; or per-variant:
+#     main: logo.png             # hero / primary mark
+#     loading: loading.webp      # working indicator (falls back to main)
+#     favicon: favicon.png       # browser-tab icon
+#   powered_by: true             # "Powered by Omnigent" credit (only when branded); false to hide
@@ -62,6 +62,9 @@ services:
      ARTIFACT_DIR: /data/artifacts
      HOST: 0.0.0.0
      PORT: "8000"
+      # Comma-separated deployment-wide release features. Empty means all
+      # release features are off; see .env.example for the known keys.
+      OMNIGENT_FEATURES: "${OMNIGENT_FEATURES:-}"
      # Anchor the server's data dir on the persistent volume so
      # file-backed operator config survives container restarts:
      # the admin roster (/data/admins) and allowed-domains file
@@ -304,6 +304,11 @@ def _build_routing(
    return _build_local_llm_routing_client(server_llm), settings


+def _resolve_execution_timeout(cfg: dict[str, Any]) -> int:
+    """Return the configured execution limit or the RuntimeCaps default."""
+    return int(cfg.get("execution_timeout") or 7200)
+
+
 def build_app(resolved_config: _ResolvedConfig | None = None) -> _BuiltApp:
    """Resolve config if needed, wire the stores, and build the app.

@@ -374,6 +379,7 @@ def build_app(resolved_config: _ResolvedConfig | None = None) -> _BuiltApp:
    routing_client, routing_settings = _build_routing(cfg, server_llm)

    caps = RuntimeCaps(
+        execution_timeout=_resolve_execution_timeout(cfg),
        default_policies=parse_default_policies(cfg.get("policies")),
        llm=server_llm,
        routing_client=routing_client,
@@ -91,6 +91,22 @@ Apply your chosen issuer with `kubectl apply -f <file>`. Without it, cert-manage
 logs `IssuerNotFound` and no certificate is issued (the server still runs — only
 TLS is affected).

+## Release features
+
+Release features are deployment-wide and off by default. Set the
+comma-separated `OMNIGENT_FEATURES` value in `base/configmap.yaml`, apply your
+Kustomize target, and restart the Deployment so every pod receives one fresh
+startup snapshot:
+
+```bash
+kubectl kustomize deploy/kubernetes/base/ | kubectl apply -f -
+kubectl rollout restart deployment/omnigent
+kubectl rollout status deployment/omnigent
+```
+
+Use the same restart after removing a feature for rollback. See
+[`designs/FEATURE_FLAGS.md`](../../designs/FEATURE_FLAGS.md) for known keys.
+
 ## Deploy with an external database

 Use this path when you have a managed Postgres (RDS, Cloud SQL, Neon, etc.).
@@ -270,6 +286,38 @@ kubectl apply -k deploy/kubernetes/overlays/sandbox-runners
 Both are detailed in
 [`overlays/sandbox-runners/README.md`](overlays/sandbox-runners/README.md#server-auth-managed-hosts).

+## Deploy with ArgoCD
+
+The `overlays/argocd/` overlay adds ArgoCD safety annotations (`Prune=false` on
+stateful resources, `ignoreDifferences` for operator-managed Secrets) onto
+`sandbox-runners`. ArgoCD renders Kustomize natively — no plugin needed.
+
+**Prerequisites:** fork the repo and replace the placeholder values in
+`base/secret.yaml` in your fork (ArgoCD reads from Git, not your disk). The
+default `accounts` auth provider refuses the managed runner dial-back — use
+header/OIDC auth or single-user (see
+[sandbox-runners README § Server auth](overlays/sandbox-runners/README.md#server-auth-managed-hosts)).
+
+```bash
+# 1. Edit application.yaml — set repoURL to your fork, targetRevision to your
+#    branch — then apply:
+kubectl apply -f deploy/kubernetes/overlays/argocd/application.yaml
+
+# 2. Wait for ArgoCD to create the runner namespace (up to 3 min without a webhook):
+kubectl wait --for=jsonpath='{.status.phase}'=Active \
+  namespace/omnigent-sandboxes --timeout=300s
+
+# 3. Create the harness-credentials Secret (see sandbox-runners README):
+kubectl create secret generic omnigent-creds -n omnigent-sandboxes \
+  --from-literal=ANTHROPIC_API_KEY=sk-ant-... \
+  --from-literal=OPENAI_API_KEY=sk-...
+```
+
+For production, manage `omnigent-creds` with
+[sealed-secrets](https://github.com/bitnami-labs/sealed-secrets) or
+[external-secrets](https://external-secrets.io/). See
+[`overlays/argocd/README.md`](overlays/argocd/README.md) for the full guide.
+
 ## Verify the deployment

 Check the rollout and reach the server without a public domain:
@@ -8,6 +8,8 @@ data:
  HOST: "0.0.0.0"
  PORT: "8000"
  ARTIFACT_DIR: "/data/artifacts"
+  # Comma-separated release features; empty keeps every feature off.
+  OMNIGENT_FEATURES: ""
  OMNIGENT_ADMIN_CREDENTIALS_PATH: "/data/admin-credentials"
  OMNIGENT_AUTH_ENABLED: "1"
  OMNIGENT_AUTH_PROVIDER: "accounts"
@@ -0,0 +1,135 @@
+# ArgoCD overlay
+
+Deploy Omnigent with the kubernetes sandbox provider via ArgoCD. This overlay
+adds safety annotations onto the
+[`sandbox-runners`](../sandbox-runners/README.md) overlay:
+
+- **`Prune=false`** on Namespaces and the artifact PVC, so an accidental prune
+  or Application deletion does not cascade to operator-created Secrets and
+  runner Pods.
+- **Ingress in wave 1**, so its health check (which requires an ingress
+  controller) does not gate the rest of the sync.
+
+ArgoCD's built-in kind ordering already applies resources in dependency order
+(Namespace → SA → Role → ConfigMap → Secret → Service → Deployment → Ingress),
+so explicit sync-wave ordering for every resource is unnecessary.
+
+ArgoCD renders Kustomize natively — no plugin or Helm chart needed.
+
+## Quick start
+
+1. **Fork the repo** — ArgoCD reads from Git, not your local disk. All edits
+   below go into your fork and must be committed and pushed to the branch
+   `targetRevision` names (default: `HEAD` / your default branch).
+
+2. **Replace placeholder secrets** — `base/secret.yaml` ships `changeme`
+   values. In your fork, set real values and commit:
+
+   ```yaml
+   # deploy/kubernetes/base/secret.yaml
+   DATABASE_URL: "postgresql+psycopg://user:pass@your-db-host:5432/omnigent"
+   OMNIGENT_ACCOUNTS_COOKIE_SECRET: "<run: openssl rand -hex 32>"
+   ```
+
+   For production, manage `omnigent-secrets` externally (sealed-secrets or
+   external-secrets) and remove `secret.yaml` from the overlay render with a
+   `$patch: delete` — see `openshift/kustomization.yaml:12-20` for the pattern.
+   The Application's `ignoreDifferences` entry prevents `selfHeal` from
+   reverting out-of-band edits to this Secret's data.
+
+3. **Configure server auth** — the default `accounts` provider refuses the
+   managed runner dial-back (`403`). Front the server with **header or OIDC
+   auth**, or run single-user. See
+   [`sandbox-runners/README.md` § Server auth](../sandbox-runners/README.md#server-auth-managed-hosts).
+
+4. **Set your domain** *(optional)* — replace `omnigent.example.com` in
+   `base/ingress.yaml`. To skip the Ingress entirely, add a `$patch: delete`
+   in your fork's overlay (see `openshift/kustomization.yaml:12-20` for the
+   pattern — do not delete `base/ingress.yaml` itself, as it is shared by all
+   overlays).
+
+5. **Edit and apply the Application CR:**
+
+   ```bash
+   # In application.yaml, set repoURL to your fork and targetRevision to
+   # the branch you pushed to:
+   kubectl apply -f deploy/kubernetes/overlays/argocd/application.yaml
+   ```
+
+6. **Wait for the sync** — ArgoCD creates the namespaces asynchronously (up
+   to 3 minutes without a webhook). Wait before creating the harness Secret:
+
+   ```bash
+   kubectl wait --for=jsonpath='{.status.phase}'=Active \
+     namespace/omnigent-sandboxes --timeout=300s
+   ```
+
+7. **Create the harness-credentials Secret** — LLM API keys for runner Pods.
+   Not in Git (credentials don't belong there):
+
+   ```bash
+   kubectl create secret generic omnigent-creds -n omnigent-sandboxes \
+     --from-literal=ANTHROPIC_API_KEY=sk-ant-... \
+     --from-literal=OPENAI_API_KEY=sk-...
+   ```
+
+   For production, manage this with
+   [sealed-secrets](https://github.com/bitnami-labs/sealed-secrets) or
+   [external-secrets](https://external-secrets.io/).
+
+## What ArgoCD does not create
+
+ArgoCD does not *create* these resources — but it **owns the namespaces they
+live in**. Deleting the Application (with the default finalizer) deletes both
+namespaces and garbage-collects everything inside them, including:
+
+- **`omnigent-creds` Secret** (step 7 above) — without it, runner Pods stall
+  in `CreateContainerConfigError`. See the
+  [sandbox-runners README](../sandbox-runners/README.md#apply) for which keys
+  to set.
+- **OIDC / external-auth Secrets** — if you front the server with OIDC, create
+  the provider Secret separately (see the
+  [base README](../../README.md#use-your-own-idp-instead-oidc--optional)).
+
+The `Prune=false` annotations protect Namespaces and the PVC during **sync**
+(accidental prune from a Git rename), but the Application finalizer bypasses
+them on **deletion**. To make `kubectl delete application` orphan resources
+instead of cascading, remove the `resources-finalizer.argocd.argoproj.io`
+finalizer from `application.yaml`.
+
+## What automated sync does
+
+- **`prune: true`** — resources that leave Git are deleted from the cluster on
+  the next sync. `Prune=false` annotations on Namespaces and the PVC exempt
+  them.
+- **`selfHeal: true`** — manual cluster edits are reverted to match Git.
+  `ignoreDifferences` on `omnigent-secrets` and `omnigent-artifacts` exempts
+  their data, so out-of-band credential edits and volume expansions are kept.
+- **Deleting the Application** — with the finalizer, deletes both namespaces,
+  the artifact PVC, and everything inside them. Without it, orphans everything.
+
+## Customizing
+
+Fork the repo, edit, commit, and push — ArgoCD picks up changes on the next
+sync. Common adjustments:
+
+- **Sandbox config** — `../sandbox-runners/sandbox-config.yaml` (namespace,
+  image, node selector, resource limits, PVC mounts). Note: changes to
+  ConfigMaps require a Pod restart to take effect (the server reads config at
+  startup). Use `configMapGenerator` with a name-suffix hash to trigger an
+  automatic rollout, or restart the Deployment manually after sync.
+- **Server resources** — `../../base/deployment.yaml`.
+- **Ingress** — `../../base/ingress.yaml` (hostname, TLS, annotations). To
+  remove the Ingress, add a `$patch: delete` in the overlay (see
+  `openshift/kustomization.yaml`).
+- **In-cluster Postgres** — use `overlays/openshift-postgres/` as a reference
+  for composing two overlays that share a base; adding `../postgres/` as a
+  direct resource causes a duplicate-base error. Alternatively, apply the
+  Postgres StatefulSet separately.
+
+## ApplicationSet (multi-environment)
+
+For staging/production splits, use an ArgoCD
+[ApplicationSet](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/)
+with a list generator. Point each entry at a different `targetRevision` (branch)
+or fork the overlay directory per environment with its own config values.
@@ -0,0 +1,79 @@
+---
+# Sample ArgoCD Application CR for deploying Omnigent with the kubernetes
+# sandbox provider. Fork the repo, edit config/secrets in your fork, then
+# set repoURL and targetRevision below. Apply to the argocd namespace.
+#
+# ArgoCD renders the Kustomize output natively — no Helm chart or plugin needed.
+#
+# TWO SECRETS ARE NOT IN GIT and must be created out of band (or via
+# sealed-secrets / external-secrets):
+#
+#   1. omnigent-secrets  — DATABASE_URL + cookie secret (see base/secret.yaml
+#      for the keys; replace the placeholder values in your fork, or manage
+#      the Secret externally and remove secret.yaml from the overlay render
+#      with a $patch: delete — see openshift/kustomization.yaml for the
+#      pattern).
+#   2. omnigent-creds    — harness LLM API keys for runner Pods (see the
+#      sandbox-runners README).
+#
+# DELETION WARNING: the resources-finalizer below means
+# `kubectl delete application omnigent` deletes every tracked resource,
+# including both Namespace objects and the artifact PVC. The overlay's
+# Prune=false annotations prevent accidental pruning during sync, but the
+# finalizer bypasses them on Application deletion. Remove the finalizer
+# if you want `kubectl delete application` to orphan resources instead of
+# cascading.
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: omnigent
+  namespace: argocd
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/omnigent-ai/omnigent.git
+    targetRevision: HEAD
+    path: deploy/kubernetes/overlays/argocd
+  destination:
+    # Resources set their own namespaces explicitly (omnigent and
+    # omnigent-sandboxes), so destination.namespace is not injected.
+    server: https://kubernetes.default.svc
+  ignoreDifferences:
+    # The checked-in secret.yaml ships placeholder values. Operators replace
+    # them out of band (kubectl edit, sealed-secrets, external-secrets), and
+    # selfHeal must not revert those edits. Without this, selfHeal
+    # continuously overwrites live credentials with the placeholder.
+    #
+    # The pointer targets /data, not /stringData, because ArgoCD normalizes
+    # stringData into base64 /data on the live object before diffing.
+    - group: ""
+      kind: Secret
+      name: omnigent-secrets
+      namespace: omnigent
+      jsonPointers:
+        - /data
+    # The API server mutates spec.resources.requests.storage on PVC creation
+    # (rounding, defaulting). selfHeal would report a perpetual diff.
+    - group: ""
+      kind: PersistentVolumeClaim
+      name: omnigent-artifacts
+      namespace: omnigent
+      jsonPointers:
+        - /spec/resources/requests/storage
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      # Honour the ignoreDifferences entries above during sync, not just
+      # during diff. Without this, a manual sync still overwrites the live
+      # secret values even though the diff view hides them.
+      - RespectIgnoreDifferences=true
+    retry:
+      limit: 3
+      backoff:
+        duration: 10s
+        factor: 2
+        maxDuration: 3m
@@ -0,0 +1,46 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+# ArgoCD overlay for the kubernetes sandbox provider. Adds safety annotations
+# (Prune=false on stateful resources, Ingress in a late wave) onto the
+# sandbox-runners overlay. ArgoCD's built-in kind ordering already sequences
+# Namespace → SA → Role → ConfigMap → Secret → Service → Deployment → Ingress,
+# so explicit sync waves are not needed for ordering — only to prevent the
+# Ingress health gate from blocking the sync on clusters without a controller.
+
+resources:
+  - ../sandbox-runners
+
+patches:
+  # Namespaces and the artifact PVC must survive Application deletion and
+  # accidental prune (a rename in base/ or a stale targetRevision). Without
+  # Prune=false, `kubectl delete application omnigent` cascades through the
+  # finalizer to both namespaces and everything inside them — including the
+  # operator-created omnigent-creds Secret and any pvc_mounts claims.
+  - target:
+      kind: Namespace
+    patch: |
+      - op: add
+        path: /metadata/annotations/argocd.argoproj.io~1sync-options
+        value: Prune=false
+  - target:
+      kind: PersistentVolumeClaim
+    patch: |
+      - op: add
+        path: /metadata/annotations/argocd.argoproj.io~1sync-options
+        value: Prune=false
+
+  # The Ingress depends on an ingress controller (nginx by default) and
+  # cert-manager. ArgoCD scores an Ingress without status.loadBalancer as
+  # Progressing. Wave 1 (everything else is implicit wave 0) means no later
+  # sync wave gates on its health, so the *sync* completes. The Application
+  # itself may still report Progressing indefinitely on a cluster without a
+  # controller — with automated + selfHeal, that keeps the Application in a
+  # perpetual reconcile loop (harmless but noisy). Install the controller or
+  # add a custom health check that treats the Ingress as healthy.
+  - target:
+      kind: Ingress
+    patch: |
+      - op: add
+        path: /metadata/annotations/argocd.argoproj.io~1sync-wave
+        value: "1"
@@ -1,42 +1,43 @@
 # Kubernetes sandbox runners (on-demand host Pods)

 This Kustomize overlay turns on the **`kubernetes`** managed-sandbox provider: a
-`host_type: managed` session spawns one **runner Pod** that runs `omnigent host`
-as its container entrypoint and dials back to the server over the existing
-launch-token tunnel. It layers the RBAC + config the provider needs onto the
-base server deployment.
+`host_type: managed` session spawns a **batch/v1 Job** whose child Pod runs
+`omnigent host` as its container entrypoint and dials back to the server over the
+existing launch-token tunnel. It layers the RBAC + config the provider needs onto
+the base server deployment.

 ## Launch model: entrypoint-as-host

-The runner Pod's container command **is** the host. An **init container**
-prepares the workspace (`mkdir` + optional `git clone`); the **main container**
-then runs `omnigent host` under a tiny PID-1 reaper. The host re-parents runner
-processes to PID 1, which the reaper reaps; SIGTERM is forwarded for graceful
-shutdown.
+The runner is launched as a **batch/v1 Job** (one Pod, `backoffLimit: 6`). The
+Job's child Pod runs `omnigent host` as its container command. An **init
+container** prepares the workspace (`mkdir` + optional `git clone`); the **main
+container** then runs `omnigent host` under a tiny PID-1 reaper. The host
+re-parents runner processes to PID 1, which the reaper reaps; SIGTERM is
+forwarded for graceful shutdown.

-The launch token is delivered through a **per-Pod Kubernetes Secret** referenced
+The launch token is delivered through a **per-Job Kubernetes Secret** referenced
 by the Pod's `secretKeyRef` — it never enters the Pod spec, a command line, or
 an audit log. The launcher creates that Secret at provision and deletes it
-alongside the Pod at terminate.
+alongside the Job at terminate.

 Because the host is **never started by `exec`-ing into an already-running
 container**, this provider needs **no `pods/exec` grant** — and avoids the
 exec-into-running-container class of runtime issues entirely. The server SA's
-rights are the minimum the launcher calls: create/get/delete Pods, get
-`pods/log` (start-failure diagnostics only), create/delete Secrets (the per-Pod
-token), and list events.
+rights are the minimum the launcher calls: create/get/delete Jobs,
+list/get Pods (to poll the Job's child), get `pods/log` (start-failure
+diagnostics only), create/delete Secrets (the per-Job token), and list events.

 ## Two-namespace, least-blast-radius design

 | Namespace | Holds |
 |---|---|
 | `omnigent` | the server, its DB/PVC, its Secrets, the `omnigent-server` SA |
-| `omnigent-sandboxes` | runner Pods, the per-Pod token Secrets, the harness-creds Secret, the powerless `omnigent-runner` SA, the scoped Role + RoleBinding |
+| `omnigent-sandboxes` | runner Jobs (and their child Pods), the per-Job token Secrets, the harness-creds Secret, the powerless `omnigent-runner` SA, the scoped Role + RoleBinding |

-The server SA's Pod/Secret rights are a **namespaced Role** bound (cross-namespace)
-to `omnigent-sandboxes` only — so a compromised server can manage runner Pods but
-**cannot** delete the server/DB Pods, read the server's Secrets, or execute
-commands inside any Pod. The runner namespace enforces Pod Security `restricted`;
+The server SA's Job/Pod/Secret rights are a **namespaced Role** bound
+(cross-namespace) to `omnigent-sandboxes` only — so a compromised server can
+manage runner Jobs but **cannot** delete the server/DB Pods, read the server's
+Secrets, or execute commands inside any Pod. The runner namespace enforces Pod Security `restricted`;
 the generated runner Pod is already restricted-compliant (non-root uid 1000, drop
 `ALL` caps, `seccompProfile: RuntimeDefault`, no privilege escalation).

@@ -83,7 +84,7 @@ runner Pod unexpectedly carries no credential:
  (`omnigent/server/managed_hosts.py`), e.g. "agent … is not a genuine built-in;
  omitting agent label".
 - A name that is not a valid label value logs a `WARNING` from
-  `build_pod_manifest` (`omnigent/onboarding/sandboxes/kubernetes.py`), e.g.
+  `build_job_manifest` (`omnigent/onboarding/sandboxes/kubernetes.py`), e.g.
  "agent … is not a valid omnigent.ai/agent value; runner Pod … stays
  unclassified". Note the gate upstream will already have logged this agent as
  classified, so this is the line that explains the missing label.
@@ -1,10 +1,15 @@
 ---
-# Namespaced Role granting the server EXACTLY what the entrypoint-as-host
-# launcher calls — nothing more (no watch, no pods/exec). Lives in the DEDICATED
-# runner namespace `omnigent-sandboxes` and is bound to the omnigent-server SA
-# (in `omnigent`) via the cross-namespace rolebinding.yaml. Because the grant is
-# a namespaced Role here, it can ONLY ever touch objects in `omnigent-sandboxes`,
-# never the server/DB Pods or Secrets in `omnigent`.
+# Namespaced Role granting what the entrypoint-as-host launcher needs (no watch,
+# no pods/exec). Lives in the DEDICATED runner namespace `omnigent-sandboxes`
+# and is bound to the omnigent-server SA (in `omnigent`) via the cross-namespace
+# rolebinding.yaml. Because the grant is a namespaced Role here, it can ONLY
+# ever touch objects in `omnigent-sandboxes`, never the server/DB Pods or
+# Secrets in `omnigent`.
+#
+# pods:create is retained temporarily for the bare-Pod → Job migration (see
+# TODO below). secrets:get is deliberately withheld — the launcher never reads
+# Secrets back, and the harness-credentials Secret is operator-managed.
+# pods/exec is withheld — the host is an entrypoint, not exec'd into.
 apiVersion: rbac.authorization.k8s.io/v1
 kind: Role
 metadata:
@@ -14,34 +19,31 @@ metadata:
    app.kubernetes.io/name: omnigent
    app.kubernetes.io/component: server
 rules:
-  # Manage the lifecycle of runner Pods, scoped to exactly what the launcher
-  # calls: provision_managed_host() creates them, the pod-start wait reads them
-  # (read_namespaced_pod is a `get`), and terminate() deletes them. The launcher
-  # never watches Pods, so `watch` is omitted. NOTE: there is deliberately NO
-  # `pods/exec` grant — the host runs as the Pod's OWN entrypoint
-  # (`omnigent host` under a PID-1 reaper), so the server never execs into a
-  # running container. Dropping exec removes the most powerful grant a
-  # compromised server could abuse (arbitrary in-Pod command execution).
+  # Manage the lifecycle of runner Jobs.  The launcher creates a batch/v1 Job
+  # (which spawns a child Pod), reads the Job's child Pod to poll start
+  # readiness, and deletes the Job (cascading to its Pods) at terminate.
+  - apiGroups: ["batch"]
+    resources: ["jobs"]
+    verbs: ["create", "get", "delete"]
+  # The launcher lists Pods by job-name label to find the Job's child Pod,
+  # then reads it to poll for Running phase. create/delete are retained so
+  # old-server (bare Pod) + new-Role doesn't break, and so terminate() can
+  # fall back to deleting a bare Pod created before the Job migration.
+  # TODO(v0.29): remove create/delete once all runners have rolled past v0.28.
  - apiGroups: [""]
    resources: ["pods"]
-    verbs: ["create", "get", "delete"]
-  # Start-failure diagnostics ONLY: when a Pod won't start, the launcher tails
-  # the failed container's log (e.g. the init container's `git clone` error) so
-  # the launch error names WHAT failed instead of a generic timeout. Read-only.
+    verbs: ["create", "list", "get", "delete"]
+  # Start-failure diagnostics ONLY: tails the failed container's log.
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]
-  # The per-launch token rides a per-Pod Secret (referenced by the Pod's
-  # `secretKeyRef`), so the launch token never enters the Pod spec or any
-  # audit-logged surface. The launcher creates that Secret at provision and
-  # deletes it alongside the Pod at terminate — hence create + delete (no get:
-  # the launcher never reads Secrets back, and the harness-credentials Secret is
-  # operator-managed, not touched here).
+  # The per-launch token rides a per-Job Secret (referenced by the Pod's
+  # `secretKeyRef`).  The launcher creates that Secret before the Job and
+  # deletes it alongside the Job at terminate.
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["create", "delete"]
-  # Surface scheduler/kubelet events (FailedScheduling, Failed pull, …) in the
-  # provider's error messages when a Pod won't become ready.
+  # Surface scheduler/kubelet events in the provider's error messages.
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["list"]
@@ -404,6 +404,6 @@ upload, foreground streaming, attach, terminate, env passthrough, error handling
 and the managed-config parsing:

 ```bash
-uv pip install -e '.[openshell,dev]'
-pytest tests/onboarding/sandboxes/test_openshell.py tests/server/test_managed_hosts.py
+uv sync --extra openshell --group test
+uv run --no-sync pytest tests/onboarding/sandboxes/test_openshell.py tests/server/test_managed_hosts.py
 ```
@@ -73,6 +73,14 @@ steps below are validated end-to-end:
 > visitor. Pre-seed `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD`, or complete setup
 > promptly after the deploy goes live.

+## Release features
+
+In the Omnigent service's **Variables** tab, set `OMNIGENT_FEATURES` to a
+comma-separated enabled set such as `usage_page`. Railway redeploys the service
+automatically. Remove the key from the value to roll back, then reload the web
+app. See [`designs/FEATURE_FLAGS.md`](../../designs/FEATURE_FLAGS.md) for known
+keys.
+
 ## Use your own IdP instead (OIDC)

 Prefer GitHub / Google / Okta login over built-in accounts? Switch the provider
@@ -17,9 +17,11 @@
 > enforcement in `omnigent/server/auth.py` (`delegated_path_allowed`,
 > `set_grant_revocation_check`). Wired in `omnigent/server/app.py`,
 > **opt-in and default-off** via `OMNIGENT_DEVICE_GRANT_ENABLED` (the
-> `/oauth/*` routes are unmounted unless it is truthy), and then only in
-> **accounts** mode (OIDC delegates login to the IdP via the cli-ticket
-> flow and never mounts these routes).
+> `/oauth/device/*` consent routes are unmounted unless it is truthy), and
+> then only in **accounts** mode (OIDC delegates login to the IdP via the
+> cli-ticket flow and never mounts the consent routes). The token/revoke
+> half (`/oauth/token`, `/oauth/revoke`) mounts **unconditionally** in both
+> accounts and OIDC modes: login-issued refresh grants (below) need it.
 > Slack: `integrations/slack/src/omnigent_slack/oauth.py`,
 > `tokens.py` (Fernet-encrypted `oauth_tokens`), `auth_manager.py`, plus
 > the bearer/refresh wiring in `omnigent.py` (`ClientAuth`,
@@ -182,15 +184,20 @@ approved it.

 ### Router `omnigent/server/routes/device_auth.py`

-Mounted in `app.py` only when **`OMNIGENT_DEVICE_GRANT_ENABLED` is truthy**
-(opt-in, **default-off** — the `/oauth/*` routes are absent otherwise), and
-then **only in `accounts` mode** (OIDC delegates login to the IdP via the
-cli-ticket flow and never mounts these routes; header mode has no
-server-mintable identity — see `create_device_auth_router`, which raises if
-constructed for any other source). The `device_grants` table is created
-unconditionally by the migration regardless of the flag; only the router
-mount is gated. This router **owns** `mint_delegated_token` and
-`DELEGATED_SCOPE`.
+The RFC 8628 consent surface (`/oauth/device/*`) is mounted in `app.py`
+only when **`OMNIGENT_DEVICE_GRANT_ENABLED` is truthy** (opt-in,
+**default-off**), and then **only in `accounts` mode** (the in-browser
+consent needs the accounts login page; header mode has no server-mintable
+identity — see `create_device_auth_router`, which raises if constructed for
+any other source). The token/revoke half is factored into
+`create_oauth_token_router` and mounts **unconditionally** in both accounts
+and OIDC modes — login-issued refresh grants need `/oauth/token` even where
+the device flow is off; a standalone mount refuses the `device_code` grant
+type with `unsupported_grant_type`. The `device_grants` table is created
+unconditionally by the migration regardless of the flag; only the consent
+mount is gated. This router also **owns** `mint_delegated_token` and
+`DELEGATED_SCOPE` (moved here from `oidc.py`, which retains only
+`mint_session_token` / `mint_session_cookie`).

 - `POST /oauth/device/authorize` — **public** (rate-limited). Generates a
  high-entropy `device_code` (`secrets.token_urlsafe`, stored **hashed**), a
@@ -355,3 +362,72 @@ stateless. This added invariant is the main thing for reviewers to scrutinize.
 - Applying the same delegated grant to other non-browser clients (the CLI could
  use it too, superseding the in-memory `_cli_tickets` store).
 - Per-scope consent granularity beyond the single "session APIs, no admin" scope.
+
+## Login-issued refresh grants
+
+The fix for unattended hosts dying at session-JWT expiry (a host
+authenticated via `omnigent login` previously had **no renewal path** —
+the stored `{token, user_id, expires_at}` record simply lapsed, default
+8 h, and the next tunnel reconnect got a misleading 403).
+
+- **Issuance** — both interactive login flows create a grant born
+  `redeemed` (`DeviceGrantStore.create_redeemed_grant`; the interactive
+  login *is* the consent step, so no device-code dance): the OIDC
+  cli-ticket fulfillment always, and accounts `POST /auth/login` when the
+  body carries `issue_refresh: true` (sent by the CLI, never the web
+  form — a browser must not receive refresh material). The raw refresh
+  token rides back once (`/auth/cli-poll` / the login response) as an
+  optional `refresh_token` key — old CLIs ignore it, new CLIs against old
+  servers see it absent. `client_id` is `"omnigent-cli"`.
+- **Authority** — a refreshed login-grant token carries `grant_id` (so
+  revocation still kills it) but **no `scope` claim**, so the delegated
+  path allowlist does not apply: it renews the session JWT and keeps that
+  same authority. Scoping it like a third-party device grant instead made
+  every non-allowlisted route (`/v1/usage`, `/v1/scheduled-tasks`,
+  `/v1/policy-registry`) 401 after the first refresh. `LOGIN_GRANT_CLIENT_ID`
+  is the marker and is **reserved** — `/oauth/device/authorize` refuses a
+  request naming it, so a device client cannot self-declare into this class.
+- **No rotation** — login grants return the SAME refresh token on every
+  renewal. Rotation + reuse detection is right for a browser-adjacent
+  third-party client, but for an unattended host it turns any ambiguous
+  network failure (lost response, crash between the server committing and
+  the client persisting) into a permanently revoked grant. Only the
+  short-lived access token is renewed; revocation and the absolute lifetime
+  cap still bound exposure. Device grants keep rotating.
+- **Renewal** — `omnigent.cli_auth.refresh_stored_token` POSTs
+  `grant_type=refresh_token`, persists the result, and returns the
+  fresh access token. The runner/host auth-token factory
+  calls it when the stored token lapses, and the host tunnel rebuilds
+  headers through that factory on every reconnect — so an unattended
+  host renews itself for the grant's lifetime. Refreshes on one machine
+  are serialized by an advisory file lock with a re-check after acquire,
+  so a losing racer picks up the winner's rotated pair instead of
+  replaying the stale token (which reuse detection would punish by
+  revoking the grant).
+- **One grant per host replica (recommended)** — since login grants do
+  not rotate, N replicas sharing one token file no longer revoke each
+  other. A per-replica login is still preferred so a single host can be
+  revoked without cutting off the rest.
+- **Lifetime** — the absolute grant lifetime stays 30 days by default;
+  `OMNIGENT_GRANT_MAX_LIFETIME_DAYS` lets an operator extend it
+  deliberately for long-lived unattended hosts. Invalid values fall back
+  to the default (never fail open to unbounded).
+- **Client-secret interaction** — `OMNIGENT_DEVICE_CLIENT_SECRET` gates
+  the endpoints that mint from an ephemeral code (device authorize + the
+  `device_code` exchange). Refresh and revoke are NOT gated: the presented
+  refresh/access token is itself the credential, and a CLI renewing its own
+  login has no way to carry that secret (gating it made every automatic
+  refresh 401 in a Slack-serving deployment).
+- **Housekeeping** — `/oauth/token` opportunistically purges expired and
+  aged-out grants. The device flow purges on `authorize`, which a
+  standalone token-router mount does not have, so login-grant rows would
+  otherwise accumulate one per login.
+
+### Known limitation
+
+General CLI commands (`omnigent usage`, session commands, direct
+remote-URL chat) still read the stored token without attempting a refresh —
+only the host/runner auth-token factory renews today. An expired login with
+valid refresh material therefore leaves those commands unauthenticated
+until something on the host path renews the shared file. Wiring the
+remaining CLI entrypoints is follow-up work.
@@ -0,0 +1,41 @@
+# Release feature flags
+
+Omnigent release features are deployment-wide, temporary rollout switches. They
+are not authorization controls or user preferences.
+
+## Configuration
+
+Set the comma-separated `OMNIGENT_FEATURES` environment variable and restart or
+redeploy the server:
+
+```bash
+OMNIGENT_FEATURES=usage_page,harness_install
+```
+
+Unset or empty means every release feature is off. Unknown names fail startup.
+The former `OMNIGENT_HARNESS_INSTALL_ENABLED` switch is rejected with a
+migration hint; use `OMNIGENT_FEATURES=harness_install` instead. The server resolves the set once at startup and publishes frontend-visible
+values in `GET /v1/info` under `features`. Users must reload the web app after a
+flag change because server capabilities are cached at page boot.
+
+`omnigent/server/feature_flags.py` is the source of truth for known keys and
+lifecycle metadata.
+
+## Inventory
+
+| Key | Default | Owner | Review by | Purpose |
+| --- | --- | --- | --- | --- |
+| `usage_page` | Off | Web | 0.11.0 | Exposes the web Usage route, sidebar navigation, timeline, and cost breakdown details. The existing `GET /v1/usage` CLI API remains available while off. |
+| `harness_install` | Off | Onboarding | 0.11.0 | Allows the web UI to install or configure supported harnesses on a connected host. |
+
+At the review release, each flag must be removed by making the feature
+unconditional, removing the feature, or moving a genuinely permanent operator
+policy into normal server configuration.
+
+## Rollout and rollback
+
+1. Deploy an immutable image with the feature absent from `OMNIGENT_FEATURES`.
+2. Enable it on one deployment, consistently across all replicas.
+3. Verify `GET /v1/info`, then reload and exercise the gated UI.
+4. Expand by deployment cohort.
+5. Roll back by removing the key and redeploying the same image.
@@ -68,6 +68,32 @@ an empty DB they self-seed a small fallback session over HTTP (the
 `external_conversation_item` event — appends items without starting a task), so
 they still work with no runner or LLM.

+### Hook spawn (no server)
+
+| Journey | Operation timed |
+| --- | --- |
+| `native_hook_spawn` | Spawn one **Python** command hook — isolated interpreter, module entrypoint, JSON payload on stdin — and time its whole lifetime |
+
+Claude Code **blocks its TUI** on command hooks, so one hook subprocess's
+lifetime is user-visible latency. Read this number as *"what a hook costs if it
+is Python"*.
+
+It is **not** the per-chunk streaming cost, and treating it as one leads
+straight to wasted work. The hooks that fire per chunk (`MessageDisplay`) and
+per tool call (`evaluate-policy`) were deliberately moved off the interpreter —
+a `/bin/sh` appender and a `curl` to the runner's relay — and
+`test_message_display_shell_command_round_trips` pins that by asserting
+`"python"` is absent from the installed command. What still pays this number is
+the per-turn set (`SessionStart` / `Stop` / `UserPromptSubmit` / `PreCompact` /
+`Task*`), the `PostToolUse` `TodoWrite`+`TaskUpdate` matchers, and the policy
+hook's Python fallback before the relay is up. So the journey's real job is to
+keep the argument for staying off the interpreter measurable. The
+journey needs no server or runner; registering it here rides hook spawn cost
+on the same nightly/release regression comparison as everything else
+(`omnigent/__init__` re-exports lazily so this stays ~interpreter-sized). The
+import-graph side of the guarantee is pinned deterministically by
+`tests/test_claude_native_message_display_hook.py`.
+
 ### Full-turn (runner + mock LLM)

 These drive a real agent turn end-to-end — `POST …/events` → server → **runner**
@@ -44,6 +44,12 @@ from __future__ import annotations

 import asyncio
 import contextlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
 import time
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
@@ -97,6 +103,9 @@ class Journey:
        per op, so 100+ iterations would blow the CI time budget; they cap at a
        few samples per run and lean on ``--runs`` for repeats. ``None`` (HTTP
        journeys) means no cap.
+    :param skip_warmup: When ``True``, the warmup phase is skipped regardless
+        of ``--warmup``. Useful for expensive journeys where even a single
+        warmup iteration would waste significant time.
    :param description: Human-readable one-liner for ``--list``.
    """

@@ -110,6 +119,7 @@ class Journey:
    needs_runner: bool = False
    needs_host: bool = False
    max_iterations: int | None = None
+    skip_warmup: bool = False
    description: str = ""

    async def run_setup(self, env: BenchEnvironment) -> JourneyContext:
@@ -131,10 +141,13 @@ def _failure_reason(exc: Exception) -> str:
    """Classify an exception into a stable failure-breakdown label.

    HTTP status errors key off their status code (``"HTTP 500"``) so the same
-    server error groups across ops; anything else keys off its class name.
+    server error groups across ops; RuntimeErrors include the message so CI
+    failure breakdowns show the actual cause; anything else keys off class name.
    """
    if isinstance(exc, httpx.HTTPStatusError):
        return f"HTTP {exc.response.status_code}"
+    if isinstance(exc, RuntimeError):
+        return f"RuntimeError: {exc}"
    return exc.__class__.__name__


@@ -235,7 +248,8 @@ async def run_latency(
    except Exception as exc:  # noqa: BLE001 — a setup failure is a recorded data point
        return _setup_failed_result(exc)
    try:
-        for _ in range(warmup):
+        effective_warmup = 0 if journey.skip_warmup else warmup
+        for _ in range(effective_warmup):
            with contextlib.suppress(Exception):  # warmup errors are non-fatal
                await journey.run_prepare(env, ctx)
                await journey.measure(env, ctx)
@@ -681,6 +695,12 @@ async def _measure_read_runner_file(env: BenchEnvironment, ctx: JourneyContext)

 # ── policy evaluate ──────────────────────────────────────────

+
+def _bench_policy_allow(_event: dict) -> dict:  # type: ignore[type-arg]
+    """Benchmark policy function: always ALLOW. Self-contained in this module."""
+    return {"result": "allow"}
+
+
 _POLICY_EVALUATE_PAYLOAD = {
    "event": {
        "type": "PHASE_TOOL_CALL",
@@ -707,15 +727,24 @@ async def _setup_policy_evaluate_session(env: BenchEnvironment) -> str:

    import yaml

+    # Build a bundle like BenchEnvironment._agent_bundle but with a policy
+    # declared so any_policies_apply is true and the full engine runs.
+    executor: dict[str, object] = {
+        "type": "omnigent",
+        "model": env.model,
+        "config": {"harness": env.harness},
+    }
    config: dict[str, object] = {
        "spec_version": 1,
        "name": "bench-policy-agent",
+        "prompt": "benchmark",
+        "executor": executor,
        "guardrails": {
            "policies": {
                "allow_all": {
                    "type": "function",
                    "on": ["tool_call"],
-                    "function": "tests.runtime.policies.conftest._always_allow",
+                    "function": "dev.benchmarks.omnigent.journeys._bench_policy_allow",
                }
            }
        },
@@ -728,16 +757,17 @@ async def _setup_policy_evaluate_session(env: BenchEnvironment) -> str:
        tar.addfile(info, io.BytesIO(payload))
    bundle = buf.getvalue()

+    # Register the agent + create a session in one call via the bundle upload
+    # path (``POST /v1/sessions`` multipart). ``/v1/agents`` is GET-only.
    resp = await env.client.post(
-        "/v1/agents",
+        "/v1/sessions",
+        data={"metadata": "{}"},
        files={"bundle": ("agent.tar.gz", bundle, "application/gzip")},
    )
    resp.raise_for_status()
-    agent_id = resp.json()["id"]
-
-    session_resp = await env.client.post("/v1/sessions", json={"agent_id": agent_id})
-    session_resp.raise_for_status()
-    session_id = session_resp.json()["id"]
+    body = resp.json()
+    # Bundle upload returns ``session_id`` (not ``id``).
+    session_id = body.get("session_id") or body["id"]

    # Warm the spec + policy caches — the measured iteration is steady-state.
    for _ in range(2):
@@ -759,6 +789,157 @@ async def _measure_policy_evaluate(env: BenchEnvironment, ctx: JourneyContext) -
    resp.raise_for_status()


+# ── CLI startup (omnigent polly against the local bench server) ──────────────
+
+# Signal that the REPL is ready — the last spinner message before the prompt.
+# polly (omnigent run) emits this just before the agent REPL appears.
+_CLI_STARTUP_READY_SIGNAL = "Launching your agent"
+
+# Per-attempt timeout. With the bench host daemon pre-running (needs_host=True),
+# polly reuses it; remaining work is session + runner connect ~5-20s on CI.
+_CLI_STARTUP_TIMEOUT_S = 60
+
+# ~5s per attempt; cap so a large --iterations stays in budget.
+_CLI_STARTUP_MAX_ITERATIONS = 3
+
+
+async def _prepare_cli_startup(env: BenchEnvironment, _ctx: JourneyContext) -> None:
+    """Stop stale daemons before each timed cli_startup iteration.
+
+    A leftover host daemon from the previous iteration causes the next
+    ``omnigent polly`` to fail with "runner tunnel rejection (HTTP 401)"
+    or "host is on another replica". Runs outside the latency timer.
+    """
+    del env
+    omnigent_bin = os.environ.get("OMNIGENT_BIN") or shutil.which("omnigent")
+    if omnigent_bin is None:
+        return
+    await asyncio.to_thread(
+        subprocess.run,
+        [omnigent_bin, "stop"],
+        capture_output=True,
+        timeout=15,
+        check=False,
+    )
+
+
+async def _measure_cli_startup(env: BenchEnvironment, _ctx: JourneyContext) -> None:
+    """Time ``omnigent polly --server`` from invocation to REPL ready.
+
+    Spawns ``omnigent polly --server <local>`` via pexpect and times until
+    ``"Launching your agent…"`` appears — the last spinner message before the
+    agent REPL. Using polly (the bundled openai-agents harness) avoids any
+    external binary dependency while exercising the same startup path as
+    ``omnigent claude``: daemon start, session create, runner launch, and
+    runner connect.
+
+    Requires ``pexpect``. No external LLM binary needed.
+
+    :param env: Benchmark environment — ``env.base_url`` is the local server URL.
+    :param _ctx: Unused (no setup context).
+    :raises RuntimeError: On timeout or process exit before the ready signal.
+    """
+    try:
+        import pexpect
+    except ImportError as exc:
+        raise RuntimeError(
+            "pexpect is required for cli_startup. Install with: pip install pexpect"
+        ) from exc
+
+    omnigent_bin = os.environ.get("OMNIGENT_BIN") or shutil.which("omnigent")
+    if omnigent_bin is None:
+        raise RuntimeError("omnigent binary not found. Set OMNIGENT_BIN or add omnigent to PATH.")
+
+    child = pexpect.spawn(
+        omnigent_bin,
+        args=["polly", "--server", env.base_url],
+        timeout=_CLI_STARTUP_TIMEOUT_S,
+        encoding="utf-8",
+        codec_errors="ignore",
+        env=dict(os.environ),
+    )
+    try:
+        idx = child.expect([pexpect.TIMEOUT, pexpect.EOF, _CLI_STARTUP_READY_SIGNAL])
+        if idx == 0:
+            raise RuntimeError(
+                f"Timed out after {_CLI_STARTUP_TIMEOUT_S}s waiting for "
+                f"{_CLI_STARTUP_READY_SIGNAL!r}"
+            )
+        if idx == 1:
+            output = (child.before or "").strip()
+            raise RuntimeError(
+                f"Process exited before {_CLI_STARTUP_READY_SIGNAL!r}. "
+                f"Last output: {output[-200:]!r}"
+            )
+        child.sendline("/exit")
+        child.expect([pexpect.EOF, pexpect.TIMEOUT], timeout=10)
+    finally:
+        if child.isalive():
+            child.terminate(force=True)
+
+
+# ── native hook spawn (no server involved) ───────────────────
+
+# Claude Code blocks its TUI on command hooks, so one hook subprocess's whole
+# lifetime is user-visible latency. This journey times that lifetime for a
+# Python hook — isolated interpreter, module entrypoint, JSON payload on stdin —
+# which is the cost of ANY hook the bridge installs as a `python -m` command.
+#
+# It is NOT the per-chunk streaming path. The hooks that fire per chunk
+# (MessageDisplay) and per tool call (evaluate-policy) were deliberately moved
+# off the interpreter — a /bin/sh appender and a curl to the runner's relay
+# respectively — and tests pin that (`test_message_display_shell_command_round_trips`
+# asserts "python" is absent from the installed command). What still pays this
+# is the per-turn set (SessionStart / Stop / UserPromptSubmit / PreCompact /
+# Task*), the PostToolUse TodoWrite+TaskUpdate matchers, and the policy hook's
+# Python fallback when the relay is not yet up. So read this number as
+# "what a hook costs if it is Python", and as the standing argument for keeping
+# the hot paths off it — not as a per-chunk cost. The import-graph side is
+# pinned by tests/test_claude_native_message_display_hook.py.
+_HOOK_SPAWN_PAYLOAD = json.dumps(
+    {
+        "hook_event_name": "MessageDisplay",
+        "message_id": "bench-message",
+        "index": 0,
+        "final": False,
+        "delta": "benchmark chunk",
+    }
+).encode()
+
+
+async def _setup_hook_spawn(env: BenchEnvironment) -> JourneyContext:
+    """A throwaway bridge dir for the hook's appended deltas file."""
+    del env
+    return tempfile.mkdtemp(prefix="omnigent-bench-hook-")
+
+
+async def _measure_hook_spawn(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    """Spawn one Python hook subprocess and wait, as Claude Code would."""
+    del env
+    proc = await asyncio.create_subprocess_exec(
+        sys.executable,
+        "-I",
+        "-m",
+        "omnigent.claude_native_message_display_hook",
+        "--bridge-dir",
+        str(ctx),
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.DEVNULL,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    _, stderr = await proc.communicate(_HOOK_SPAWN_PAYLOAD)
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"hook exited {proc.returncode}: {stderr.decode('utf-8', 'replace')[:200]}"
+        )
+
+
+async def _teardown_hook_spawn(env: BenchEnvironment, ctx: JourneyContext) -> None:
+    """Remove the throwaway bridge dir."""
+    del env
+    shutil.rmtree(str(ctx), ignore_errors=True)
+
+
 # ── registry ─────────────────────────────────────────────────

 ALL_JOURNEYS: dict[str, Journey] = {
@@ -904,9 +1085,38 @@ ALL_JOURNEYS: dict[str, Journey] = {
            max_iterations=_RUNNER_FS_MAX_ITERATIONS,
            description="GET .../environments/default/filesystem/{path} — runner file read proxy.",
        ),
+        Journey(
+            name="native_hook_spawn",
+            kind="latency",
+            measure=_measure_hook_spawn,
+            setup=_setup_hook_spawn,
+            teardown=_teardown_hook_spawn,
+            description=(
+                "Spawn one Python command hook (isolated interpreter, module "
+                "entrypoint) and time its whole lifetime — what any `python -m` "
+                "hook costs Claude's blocked TUI. Not the per-chunk path: that "
+                "one is a /bin/sh appender."
+            ),
+        ),
+        Journey(
+            name="cli_startup",
+            kind="latency",
+            measure=_measure_cli_startup,
+            prepare=_prepare_cli_startup,
+            max_iterations=_CLI_STARTUP_MAX_ITERATIONS,
+            skip_warmup=True,
+            description=(
+                "Spawn `omnigent polly --server` and time invocation → REPL ready "
+                "(daemon + session + runner connect). No LLM call needed. "
+                "Requires pexpect."
+            ),
+        ),
    )
 }

+# Registry alias — kept for callers that enumerate opt-in journeys explicitly.
+OPT_IN_JOURNEYS: dict[str, Journey] = {}
+

 def resolve_journeys(names: list[str] | None) -> list[Journey]:
    """Resolve requested journey *names* (or all when ``None``/empty).
@@ -0,0 +1,190 @@
+"""Render ``run.py`` JSON reports as GitHub-flavoured markdown result matrices.
+
+Where ``compare.py`` renders a baseline-vs-candidate regression table, this
+renders the absolute numbers of one or more standalone reports — the
+journey × metric matrix a CI job appends to ``$GITHUB_STEP_SUMMARY``. Given
+several reports (e.g. the nightly's sqlite / postgres / mysql legs) it also
+leads with a cross-report P50 matrix so the backends can be compared side by
+side.
+
+Usage::
+
+    report_markdown.py REPORT.json [REPORT.json ...] [--title TEXT]
+
+Prints markdown to stdout. Report labels come from each report's
+``config.backend``; when two reports share a backend the filename stem is
+appended to keep the columns distinguishable.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Keep table cells one-line and skimmable: a skip reason is an exception
+# rendering, which can run long and embed newlines that would break the row.
+_MAX_NOTE_LEN = 100
+
+
+def _fmt_ms(value: object) -> str:
+    """Format a millisecond metric, or ``—`` when it is absent."""
+    return f"{value:.1f}" if isinstance(value, (int, float)) else "—"
+
+
+def _fmt_rps(value: object) -> str:
+    """Format a requests-per-second metric, or ``—`` when it is absent."""
+    return f"{value:.0f}" if isinstance(value, (int, float)) else "—"
+
+
+def _one_line(text: str) -> str:
+    """Collapse *text* onto one bounded line so it can live in a table cell."""
+    flattened = " ".join(str(text).split())
+    if len(flattened) > _MAX_NOTE_LEN:
+        return flattened[: _MAX_NOTE_LEN - 1] + "…"
+    return flattened
+
+
+def _journey_note(block: dict) -> str:
+    """The Notes cell for one journey block: skip reason / failure marker."""
+    if block.get("skipped"):
+        return _one_line(f"⚠️ skipped — {block.get('error', 'unknown error')}")
+    summary = block.get("summary") or {}
+    if summary and not summary.get("runs_ok"):
+        return "❌ every run failed"
+    return ""
+
+
+def _runs_cell(block: dict) -> str:
+    """The Runs cell: ``ok/total``, or ``—`` for a skipped journey."""
+    summary = block.get("summary") or {}
+    total = summary.get("runs_total")
+    if not isinstance(total, int):
+        return "—"
+    return f"{summary.get('runs_ok', 0)}/{total}"
+
+
+def _caption(report: dict) -> str:
+    """One italic line of run context under a section heading."""
+    config = report.get("config") or {}
+    parts: list[str] = []
+    iterations = config.get("iterations")
+    runs = config.get("runs")
+    if iterations is not None and runs is not None:
+        parts.append(f"{iterations} iterations × {runs} runs")
+    warmup = config.get("warmup")
+    if warmup is not None:
+        parts.append(f"warmup {warmup}")
+    harness = report.get("harness")
+    if harness:
+        parts.append(str(harness))
+    sha = report.get("git_sha")
+    if sha:
+        parts.append(f"`{str(sha)[:8]}`")
+    return f"_{' · '.join(parts)}_" if parts else ""
+
+
+def _report_section(label: str, report: dict) -> list[str]:
+    """Markdown lines for one report: heading, caption, journey × metric table."""
+    lines = [f"### {label}", ""]
+    caption = _caption(report)
+    if caption:
+        lines.extend([caption, ""])
+    lines.extend(
+        [
+            "| Journey | Mean ms | P50 ms | P95 ms | P99 ms | Req/s | Runs | Notes |",
+            "| --- | ---: | ---: | ---: | ---: | ---: | ---: | --- |",
+        ]
+    )
+    for name, block in (report.get("journeys") or {}).items():
+        summary = block.get("summary") or {}
+        lines.append(
+            f"| {name} "
+            f"| {_fmt_ms(summary.get('avg_mean_ms'))} "
+            f"| {_fmt_ms(summary.get('avg_p50_ms'))} "
+            f"| {_fmt_ms(summary.get('avg_p95_ms'))} "
+            f"| {_fmt_ms(summary.get('avg_p99_ms'))} "
+            f"| {_fmt_rps(summary.get('avg_rps'))} "
+            f"| {_runs_cell(block)} "
+            f"| {_journey_note(block)} |"
+        )
+    lines.append("")
+    return lines
+
+
+def _journey_order(labeled_reports: list[tuple[str, dict]]) -> list[str]:
+    """Union of journey names, keeping each report's insertion order."""
+    ordered: list[str] = []
+    for _, report in labeled_reports:
+        for name in report.get("journeys") or {}:
+            if name not in ordered:
+                ordered.append(name)
+    return ordered
+
+
+def _cross_matrix(labeled_reports: list[tuple[str, dict]]) -> list[str]:
+    """Journey × report P50 matrix so several reports compare side by side."""
+    labels = [label for label, _ in labeled_reports]
+    lines = [
+        "### P50 across reports",
+        "",
+        "| Journey | " + " | ".join(f"{label} P50 ms" for label in labels) + " |",
+        "| --- | " + " | ".join("---:" for _ in labels) + " |",
+    ]
+    for name in _journey_order(labeled_reports):
+        cells = []
+        for _, report in labeled_reports:
+            block = (report.get("journeys") or {}).get(name) or {}
+            cells.append(_fmt_ms((block.get("summary") or {}).get("avg_p50_ms")))
+        lines.append(f"| {name} | " + " | ".join(cells) + " |")
+    lines.append("")
+    return lines
+
+
+def build_markdown(labeled_reports: list[tuple[str, dict]], title: str | None = None) -> str:
+    """Render *labeled_reports* as one markdown document.
+
+    :param labeled_reports: ``(label, report)`` pairs, where *report* is a
+        parsed ``run.py`` JSON report and *label* names it (e.g. its backend).
+    :param title: Optional top-level heading, e.g. ``"Benchmark results"``.
+    :returns: GitHub-flavoured markdown ending in a newline.
+    """
+    lines: list[str] = []
+    if title:
+        lines.extend([f"## {title}", ""])
+    if len(labeled_reports) > 1:
+        lines.extend(_cross_matrix(labeled_reports))
+    for label, report in labeled_reports:
+        lines.extend(_report_section(label, report))
+    return "\n".join(lines).rstrip("\n") + "\n"
+
+
+def _label_for(path: Path, report: dict, seen: set[str]) -> str:
+    """Label a report by backend, disambiguating duplicates with the filename."""
+    backend = (report.get("config") or {}).get("backend")
+    label = str(backend) if backend else path.stem
+    if label in seen:
+        label = f"{label} ({path.stem})"
+    seen.add(label)
+    return label
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point: render the given report files to stdout."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("reports", nargs="+", type=Path, help="run.py JSON report file(s).")
+    parser.add_argument("--title", default=None, help="Optional top-level heading.")
+    args = parser.parse_args(argv)
+
+    labeled: list[tuple[str, dict]] = []
+    seen: set[str] = set()
+    for path in args.reports:
+        report = json.loads(path.read_text())
+        labeled.append((_label_for(path, report, seen), report))
+    sys.stdout.write(build_markdown(labeled, title=args.title))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -32,8 +32,7 @@ Runs from a **repo checkout** (it imports `dev.benchmarks` + `tests`), with the
 harness + bench deps:

 ```bash
-pip install -e '.[loadtest,dev,agents-sdk]'
-# or: uv sync --extra loadtest --extra dev --extra agents-sdk
+uv sync --extra loadtest --extra agents-sdk
 ```

 ## Run
@@ -26,7 +26,7 @@ Writes a timestamped result set:
      summary.md              human-readable latency write-up (this tool)

 Runs from a repo checkout only (imports ``dev.benchmarks`` + ``tests``), with
-the ``[loadtest,dev,agents-sdk]`` extras. Knobs: ``--users`` (N hosts),
+the ``loadtest`` and ``agents-sdk`` extras. Knobs: ``--users`` (N hosts),
 ``--spawn-rate``, ``--run-time``, ``--sessions-per-user``, ``--turns-per-session``,
 ``--reply-words``, ``--out-dir``.
 """
@@ -363,7 +363,7 @@ def main() -> int:
        if importlib.util.find_spec(mod) is None:
            sys.exit(
                f"{pkg} not importable under {sys.executable} — install the extras: "
-                "pip install -e '.[loadtest,dev,agents-sdk]' (run from a repo checkout)."
+                "uv sync --extra loadtest --extra agents-sdk (run from a repo checkout)."
            )
    out_dir = _resolve_out_dir(args.out_dir)
    return asyncio.run(_boot_and_run(args, out_dir))
@@ -50,7 +50,7 @@ Run it from anywhere inside the checkout — it walks up to the repo root
 |---|---|---|
 | server | `uv run omnigent --log-to-stderr server --host 127.0.0.1 --port <p> --database-uri … --artifact-location …` | Waited on via `GET /health`. |
 | host   | `uv run omnigent --log-to-stderr host --server http://127.0.0.1:<p>` | Started once the server is healthy. |
-| vite   | `pnpm run dev -- --host <host> --port <p> --strictPort` (cwd `web/`) | `OMNIGENT_URL` points its proxy at the pod's server. |
+| vite   | `pnpm run dev --host <host> --port <p> --strictPort` (cwd `web/`) | `OMNIGENT_URL` points its proxy at the pod's server. |

 Before Vite starts (and on a manual Vite restart), omnidev runs `pnpm install`
 in `web/` when needed — `node_modules/` is missing, or `package.json` /
@@ -143,6 +143,16 @@ mod tests {
            .find(|(k, _)| k == "OMNIGENT_DATABASE_URI")
            .map(|(_, v)| v.clone());
        assert_eq!(db, Some(pod.db_uri()));
+
+        let config_home = cmd
+            .env
+            .iter()
+            .find(|(k, _)| k == "OMNIGENT_CONFIG_HOME")
+            .map(|(_, v)| v.clone());
+        assert_eq!(config_home, Some(pod.config_dir().display().to_string()));
+
+        assert!(cmd.env.iter().all(|(k, _)| k != "HOME"));
+        assert!(cmd.env.iter().all(|(k, _)| !k.starts_with("XDG_")));
    }

    #[test]
@@ -120,7 +120,7 @@ impl ProcSpec {
        }
    }

-    /// `pnpm run dev -- --host <host> --port <p> --strictPort`, from `web/`.
+    /// `pnpm run dev --host <host> --port <p> --strictPort`, from `web/`.
    /// `OMNIGENT_URL` (in the pod env) points Vite's proxy at this pod's backend.
    pub fn vite(pod: &Pod) -> ProcSpec {
        if let Some(profile) = &pod.profile {
@@ -128,10 +128,10 @@ impl ProcSpec {
        }
        ProcSpec {
            program: "pnpm".into(),
+            // pnpm forwards script arguments directly; `--` would make Vite ignore the flags.
            args: vec![
                "run".into(),
                "dev".into(),
-                "--".into(),
                "--host".into(),
                pod.vite_host.clone(),
                "--port".into(),
@@ -151,7 +151,7 @@ mod tests {
    use crate::profile::{ProcessProfile, Profile};

    #[test]
-    fn vite_uses_configured_bind_host_but_backend_url_stays_loopback() {
+    fn vite_forwards_configured_host_and_port_but_backend_url_stays_loopback() {
        let repo = tempdir();
        let pod_dir = tempdir();
        let pod = Pod::create(
@@ -167,8 +167,18 @@ mod tests {
        .unwrap();

        let vite = ProcSpec::vite(&pod);
-        let host_flag = vite.args.iter().position(|arg| arg == "--host").unwrap();
-        assert_eq!(vite.args[host_flag + 1], "0.0.0.0");
+        assert_eq!(
+            vite.args,
+            [
+                "run",
+                "dev",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "19292",
+                "--strictPort",
+            ]
+        );
        assert_eq!(pod.server_url(), "http://127.0.0.1:19191");
    }

@@ -13,7 +13,7 @@
 ## Global Constraints

 - Python deps via `uv` only (never pip); JS/TS via `bun`. Latest stable deps.
- Pre-commit gate (must pass): `uv run ruff check --fix && uv run ruff format && uv run mypy --strict . && uv run pytest`. Never disable a lint/type rule — fix the root cause.
+- Pre-commit gate (must pass): `uv sync --group dev && uv run --no-sync ruff check --fix && uv run --no-sync ruff format && uv run --no-sync pyrefly check && uv run --no-sync pytest`. Never disable a lint/type rule — fix the root cause.
 - agy pinned: `AGY_EXPECTED_VERSION=1.0.10` (Docker build fails on mismatch). All RPC shapes are version-sensitive.
 - connect-RPC: JSON (`Content-Type: application/json`), `verify=False`, every URL passes `_assert_loopback_url`. Reuse `antigravity_native_rpc.py` discovery (`discover_language_server_port` / `_candidate_agy_rpc_ports` / `_conversation_matches`).
 - Identity: `cascadeId == conversationId == brain-dir UUID` (no separate id lookup).
@@ -80,7 +80,7 @@ def test_cancel_cascade_steps_true_on_200(monkeypatch):
    assert rpc.cancel_cascade_steps(52548, "conv-uuid") is True
 ```

- [ ] **Step 2: Run, verify FAIL** — `uv run pytest tests/test_antigravity_native_rpc.py -k "trajectory_steps or cancel_cascade" -v` → fail (undefined).
+- [ ] **Step 2: Run, verify FAIL** — `uv run --group test pytest tests/test_antigravity_native_rpc.py -k "trajectory_steps or cancel_cascade" -v` → fail (undefined).
 - [ ] **Step 3: Implement** `get_trajectory_steps` (POST `{"cascadeId": cascade_id}` to `GetCascadeTrajectorySteps`, parse `.get("steps", [])`) and `cancel_cascade_steps` (POST `{"cascadeId": cascade_id}` to `CancelCascadeSteps`, return `resp.status_code < 400`), both via `_sync_client` + `_assert_loopback_url`, mirroring `_conversation_matches`.
 - [ ] **Step 4: Run, verify PASS.**
 - [ ] **Step 5: Commit** (`feat(antigravity-native): RPC client — trajectory steps + cancel`).
@@ -241,7 +241,7 @@ def test_handle_user_interaction_raises_on_500(monkeypatch):

 - [ ] **Step 1:** Grep for `antigravity_native_forwarder` / `forwarded_steps` / `update_forwarded_steps` references; confirm only the reader path remains.
 - [ ] **Step 2:** Delete the forwarder module + its tests; remove the cursor fields/methods from the bridge; relocate the shared types.
- [ ] **Step 3:** Run the full gate: `uv run ruff check --fix && uv run ruff format && uv run mypy --strict . && uv run pytest` (targeted antigravity suites + server).
+- [ ] **Step 3:** Run the full gate: `uv sync --group dev && uv run --no-sync ruff check --fix && uv run --no-sync ruff format && uv run --no-sync pyrefly check && uv run --no-sync pytest` (targeted antigravity suites + server).
 - [ ] **Step 4:** Commit (`refactor(antigravity-native): retire transcript forwarder + durable cursor (RPC reader supersedes)`).

 ---
@@ -143,7 +143,7 @@ guardrails:
          gate_pushes: false

 tools:
-  # The two brainstorming partners — see agents/<name>/. Both reason and write,
+  # The two brainstorming partners — see agents/<dir>/. Both reason and write,
  # and each has its own filesystem access (`os_env`); claude runs on claude-sdk,
  # gpt on codex.
  agents:
@@ -245,7 +245,7 @@ prompt: |

  Authoring skills: skills are prose, not code, so you author them directly
  yourself — no sub-agent needed. A skill always belongs in polly's OWN skills
-  directory — `examples/polly/skills/<name>/SKILL.md` in this repo — NEVER the
+  directory — `examples/polly/skills/<dir>/SKILL.md` in this repo — NEVER the
  host `~/.claude/skills/` directory. Your claude-sdk brain lists host skills
  under `~/.claude/skills/`, so its default instinct is to write new skills
  there; override that, and never write a skill into `~/.claude/skills/` (or any
@@ -324,7 +324,7 @@ terminals:
        type: none

 tools:
-  # Coding sub-agents — see agents/<name>/. claude_code, codex, opencode,
+  # Coding sub-agents — see agents/<dir>/. claude_code, codex, opencode,
  # cursor, hermes, and agy are real CLI coding harnesses; pi is a headless
  # multi-model worker. Each implements, reviews (cross-vendor), and explores.
  agents:
@@ -44,7 +44,7 @@ prompt: |
  even across several files; any change to source code or tests, and any deep
  code investigation, goes to a sub-agent.

-  You have exactly TWO sub-agents (see agents/<name>/):
+  You have exactly TWO sub-agents (see agents/<dir>/):
  - `researcher` — a read-only repo explorer (claude-sdk). Ask it how something
    actually works, what a diff changed, or to trace behavior across files; it
    returns a findings report and edits nothing.
@@ -107,7 +107,7 @@ prompt: |
  - api-docs — document a module or public API surface.

  Skills are prose, so you author new ones yourself into Scribe's OWN skills
-  directory (`examples/scribe/skills/<name>/SKILL.md`), never the host
+  directory (`examples/scribe/skills/<dir>/SKILL.md`), never the host
  `~/.claude/skills/` directory.

 async: true
@@ -139,7 +139,7 @@ guardrails:
          gate_pushes: false

 tools:
-  # The two sub-agents — see agents/<name>/. `researcher` explores read-only on
+  # The two sub-agents — see agents/<dir>/. `researcher` explores read-only on
  # claude-sdk; `reviewer` fact-checks on codex (a different vendor) so the
  # cross-model check is meaningful.
  agents:
@@ -42,7 +42,7 @@ prompt: |
  by the `read_only_os` policy: any `sys_os_write` / `sys_os_edit` is DENIED, so
  write the fix into your report, not into the file.

-  You have exactly TWO sub-agents (see agents/<name>/):
+  You have exactly TWO sub-agents (see agents/<dir>/):
  - `scanner` — a read-only repo explorer (claude-sdk). Ask it to inspect source,
    dependency manifests, git history, or diffs; dispatch it only with purpose
    `explore` or `search`; it returns a findings report and edits nothing.
@@ -115,7 +115,7 @@ prompt: |
    findings report.

  Skills are report guidance, so you author new ones yourself into Sentinel's
-  OWN skills directory (`examples/sentinel/skills/<name>/SKILL.md`), never the
+  OWN skills directory (`examples/sentinel/skills/<dir>/SKILL.md`), never the
  host `~/.claude/skills/` directory.

 async: true
@@ -177,7 +177,7 @@ guardrails:
          allowed_purposes: [explore, search, review]

 tools:
-  # The two sub-agents — see agents/<name>/. `scanner` explores read-only on
+  # The two sub-agents — see agents/<dir>/. `scanner` explores read-only on
  # claude-sdk; `reviewer` fact-checks on codex (a different vendor) so the
  # cross-vendor check is meaningful.
  agents:
@@ -293,11 +293,11 @@ This integration is a **separate package** (`omnigent-slack`) with heavy deps
 (slack_bolt, aiohttp) kept out of the core `omnigent` install. It resolves as an
 editable path dep of the root `omnigent` package via the `slack` extra (see
 `[tool.uv.sources]` in the root `pyproject.toml`), and shares the root's dev
-tooling (ruff, mypy, pytest) and config rather than carrying its own. Work on it
+tooling (Ruff, Pyrefly, pytest) and config rather than carrying its own. Work on it
 from the repo-root env:

 ```bash
-# From the repo root — add the slack extra to your existing extras:
-uv sync --extra slack       # e.g. --extra all --extra dev --extra slack
-uv run omni integration slack
+# From the repo root — install the Slack capability and contributor tooling:
+uv sync --extra slack --group dev
+uv run --no-sync omni integration slack
 ```
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "omnigent-slack"
-version = "0.10.0.dev0"
+version = "0.11.0.dev0"
 description = "Slack Socket Mode bot that drives Omnigent sessions."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -180,7 +180,12 @@ def _register_error_handler(app: AsyncApp, logger: logging.Logger) -> None:

    @app.error
    async def _on_error(error: Exception, body: dict[str, Any]) -> None:
-        logger.exception("Unhandled Slack listener error; body_type=%s", body.get("type"))
+        logger.error(
+            "Unhandled Slack listener error: %s; body_type=%s",
+            error,
+            body.get("type"),
+            exc_info=(type(error), error, error.__traceback__),
+        )


 def register_handlers(app: AsyncApp, service: SlackOmnigentService) -> None:
@@ -20,12 +20,37 @@ async def test_error_handler_logs_with_traceback(caplog: pytest.LogCaptureFixtur
    error_handler = app._async_middleware_error_handler
    assert error_handler is not None

-    with caplog.at_level(logging.ERROR, logger="test-app-error"):
+    def raise_error() -> RuntimeError:
        try:
            raise RuntimeError("boom")
        except RuntimeError as exc:
-            await error_handler.func(error=exc, body={"type": "event_callback"})
+            return exc

-    assert any("Unhandled Slack listener error" in r.message for r in caplog.records)
-    # The exception traceback is attached (logger.exception), not just the message.
-    assert any(r.exc_info for r in caplog.records)
+    error = raise_error()
+    with caplog.at_level(logging.ERROR, logger="test-app-error"):
+        await error_handler.func(error=error, body={"type": "event_callback"})
+
+    record = caplog.records[-1]
+    assert "Unhandled Slack listener error: boom" in record.message
+    assert record.exc_info == (RuntimeError, error, error.__traceback__)
+
+
+@pytest.mark.asyncio
+async def test_error_handler_logs_exception_without_active_traceback(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """An exception passed outside an ``except`` block still logs usefully."""
+    app = AsyncApp(token="xoxb-dummy", signing_secret="x")
+    logger = logging.getLogger("test-app-error-no-traceback")
+    _register_error_handler(app, logger)
+    error_handler = app._async_middleware_error_handler
+    assert error_handler is not None
+
+    error = ValueError("created outside an except block")
+    with caplog.at_level(logging.ERROR, logger="test-app-error-no-traceback"):
+        await error_handler.func(error=error, body={"type": "event_callback"})
+
+    record = caplog.records[-1]
+    assert "created outside an except block" in record.message
+    assert record.exc_info == (ValueError, error, None)
+    assert "NoneType: None" not in caplog.text
@@ -938,7 +938,7 @@ async def test_exhausted_reconnect_shows_non_alarming_text(tmp_path: Path) -> No
        client=slack,
        context={"bot_user_id": "B1"},
    )
-    await _wait_for_posts(slack, 1)
+    await _wait_for_ack_deleted(slack)
    await service.shutdown()

    # The notice is a public post (not ephemeral): the non-alarming stream-drop
@@ -1719,6 +1719,16 @@ async def _wait_for_posts(client: FakeSlackClient, count: int) -> None:
    raise AssertionError(f"Timed out waiting for {count} posts")


+async def _wait_for_ack_deleted(client: FakeSlackClient) -> None:
+    # Wait until the "Working on it…" ack has been deleted and a follow-up post
+    # has landed — i.e. stop_with() fully completed (delete then postMessage).
+    for _ in range(50):
+        if client.deleted_ts and client.posts:
+            return
+        await asyncio.sleep(0.02)
+    raise AssertionError("Timed out waiting for ack deletion and follow-up post")
+
+
 async def test_unreachable_server_prompts_config_command(tmp_path: Path) -> None:
    store = await _store(tmp_path)
    slack = FakeSlackClient()
@@ -14,7 +14,7 @@ _check-uv:
    uv run --no-sync pre-commit --version

 _ensure-uv:
-    uv sync --extra all --extra dev
+    uv sync --extra all --group dev

 # --- iOS Ruby dependencies ---

@@ -87,11 +87,11 @@ electron-build: _ensure-web _ensure-electron

 [group('lint')]
 lint: _ensure-uv
-    uv run pre-commit run
+    uv run --no-sync pre-commit run

 [group('lint')]
 lint-all: _ensure-uv
-    uv run pre-commit run --all-files
+    uv run --no-sync pre-commit run --all-files

 [group('lint')]
 typecheck-python: _ensure-uv
@@ -108,4 +108,4 @@ lint-ts:

 [group('lint')]
 normalize-locks: _ensure-uv
-    uv run scripts/normalize_uv_lock_registry.py uv.lock || true
+    uv run --no-sync scripts/normalize_uv_lock_registry.py uv.lock || true
@@ -29,72 +29,211 @@ from omnigent._env_compat import mirror_legacy_env as _mirror_legacy_env  # noqa

 _mirror_legacy_env()

-from omnigent.inner.datamodel import (  # noqa: E402 — must follow md5 patch
-    AgentDef,
-    Connection,
-    Credentials,
-    History,
-    Memory,
-    MemoryConfig,
-    Message,
-    ParamDef,
-    SessionState,
-)
-from omnigent.inner.executor import (  # noqa: E402 — must follow md5 patch
-    Executor,
-    ExecutorConfig,
-    ExecutorError,
-    ExecutorEvent,
-    TextChunk,
-    ToolCallComplete,
-    ToolCallRequest,
-    TurnCancelled,
-    TurnComplete,
-)
-from omnigent.inner.policies import (  # noqa: E402 — must follow md5 patch
-    FunctionPolicy,
-    Policy,
-    PolicyAction,
-    PolicyResult,
-    PromptPolicy,
-)
-from omnigent.inner.tools import (  # noqa: E402 — must follow md5 patch
-    AgentTool,
-    CancellableFunctionTool,
-    FunctionTool,
-    HandoffTool,
-    InheritedTool,
-    MCPTool,
-    SkillTool,
-    Tool,
-)
+# The public names below re-export lazily (PEP 562). This package init is on
+# the hot path of every ``python -m omnigent.<hook>`` subprocess Claude Code
+# spawns — once per streamed text chunk (the TUI blocks on the MessageDisplay
+# hook), per statusline refresh, and per tool call — and eagerly importing the
+# datamodel/executor graph here cost those spawns ~250 ms each. Names resolve
+# on first attribute access and are cached in module globals; the import-graph
+# guards live in tests/test_claude_native_message_display_hook.py and the
+# wall-clock trend in the ``native_hook_spawn`` benchmark journey.
+import importlib  # noqa: E402
+from typing import TYPE_CHECKING, Any  # noqa: E402
+
+if TYPE_CHECKING:
+    from omnigent.inner.claude_sdk_executor import ClaudeSDKExecutor as ClaudeSDKExecutor
+    from omnigent.inner.codex_executor import CodexExecutor as CodexExecutor
+    from omnigent.inner.databricks_executor import DatabricksExecutor as DatabricksExecutor
+    from omnigent.inner.datamodel import (
+        AgentDef as AgentDef,
+    )
+    from omnigent.inner.datamodel import (
+        Connection as Connection,
+    )
+    from omnigent.inner.datamodel import (
+        Credentials as Credentials,
+    )
+    from omnigent.inner.datamodel import (
+        History as History,
+    )
+    from omnigent.inner.datamodel import (
+        Memory as Memory,
+    )
+    from omnigent.inner.datamodel import (
+        MemoryConfig as MemoryConfig,
+    )
+    from omnigent.inner.datamodel import (
+        Message as Message,
+    )
+    from omnigent.inner.datamodel import (
+        ParamDef as ParamDef,
+    )
+    from omnigent.inner.datamodel import (
+        SessionState as SessionState,
+    )
+    from omnigent.inner.executor import (
+        Executor as Executor,
+    )
+    from omnigent.inner.executor import (
+        ExecutorConfig as ExecutorConfig,
+    )
+    from omnigent.inner.executor import (
+        ExecutorError as ExecutorError,
+    )
+    from omnigent.inner.executor import (
+        ExecutorEvent as ExecutorEvent,
+    )
+    from omnigent.inner.executor import (
+        TextChunk as TextChunk,
+    )
+    from omnigent.inner.executor import (
+        ToolCallComplete as ToolCallComplete,
+    )
+    from omnigent.inner.executor import (
+        ToolCallRequest as ToolCallRequest,
+    )
+    from omnigent.inner.executor import (
+        TurnCancelled as TurnCancelled,
+    )
+    from omnigent.inner.executor import (
+        TurnComplete as TurnComplete,
+    )
+    from omnigent.inner.loader import load_agent_def as load_agent_def
+    from omnigent.inner.open_responses_sdk import OpenResponsesExecutor as OpenResponsesExecutor
+    from omnigent.inner.openai_agents_sdk_executor import (
+        OpenAIAgentsSDKExecutor as OpenAIAgentsSDKExecutor,
+    )
+    from omnigent.inner.policies import (
+        FunctionPolicy as FunctionPolicy,
+    )
+    from omnigent.inner.policies import (
+        Policy as Policy,
+    )
+    from omnigent.inner.policies import (
+        PolicyAction as PolicyAction,
+    )
+    from omnigent.inner.policies import (
+        PolicyResult as PolicyResult,
+    )
+    from omnigent.inner.policies import (
+        PromptPolicy as PromptPolicy,
+    )
+    from omnigent.inner.tools import (
+        AgentTool as AgentTool,
+    )
+    from omnigent.inner.tools import (
+        CancellableFunctionTool as CancellableFunctionTool,
+    )
+    from omnigent.inner.tools import (
+        FunctionTool as FunctionTool,
+    )
+    from omnigent.inner.tools import (
+        HandoffTool as HandoffTool,
+    )
+    from omnigent.inner.tools import (
+        InheritedTool as InheritedTool,
+    )
+    from omnigent.inner.tools import (
+        MCPTool as MCPTool,
+    )
+    from omnigent.inner.tools import (
+        SkillTool as SkillTool,
+    )
+    from omnigent.inner.tools import (
+        Tool as Tool,
+    )
+    from omnigent.inner.tracing import (
+        disable_tracing as disable_tracing,
+    )
+    from omnigent.inner.tracing import (
+        enable_tracing as enable_tracing,
+    )
+    from omnigent.inner.tracing import (
+        is_tracing_enabled as is_tracing_enabled,
+    )
+
+# Public name → defining module for the always-present re-exports.
+_LAZY_EXPORTS = {
+    "AgentDef": "omnigent.inner.datamodel",
+    "Connection": "omnigent.inner.datamodel",
+    "Credentials": "omnigent.inner.datamodel",
+    "History": "omnigent.inner.datamodel",
+    "Memory": "omnigent.inner.datamodel",
+    "MemoryConfig": "omnigent.inner.datamodel",
+    "Message": "omnigent.inner.datamodel",
+    "ParamDef": "omnigent.inner.datamodel",
+    "SessionState": "omnigent.inner.datamodel",
+    "Executor": "omnigent.inner.executor",
+    "ExecutorConfig": "omnigent.inner.executor",
+    "ExecutorError": "omnigent.inner.executor",
+    "ExecutorEvent": "omnigent.inner.executor",
+    "TextChunk": "omnigent.inner.executor",
+    "ToolCallComplete": "omnigent.inner.executor",
+    "ToolCallRequest": "omnigent.inner.executor",
+    "TurnCancelled": "omnigent.inner.executor",
+    "TurnComplete": "omnigent.inner.executor",
+    "FunctionPolicy": "omnigent.inner.policies",
+    "Policy": "omnigent.inner.policies",
+    "PolicyAction": "omnigent.inner.policies",
+    "PolicyResult": "omnigent.inner.policies",
+    "PromptPolicy": "omnigent.inner.policies",
+    "AgentTool": "omnigent.inner.tools",
+    "CancellableFunctionTool": "omnigent.inner.tools",
+    "FunctionTool": "omnigent.inner.tools",
+    "HandoffTool": "omnigent.inner.tools",
+    "InheritedTool": "omnigent.inner.tools",
+    "MCPTool": "omnigent.inner.tools",
+    "SkillTool": "omnigent.inner.tools",
+    "Tool": "omnigent.inner.tools",
+    "load_agent_def": "omnigent.inner.loader",
+    "disable_tracing": "omnigent.inner.tracing",
+    "enable_tracing": "omnigent.inner.tracing",
+    "is_tracing_enabled": "omnigent.inner.tracing",
+}
+
+# Optional executors resolve to ``None`` when their extra's dependencies are
+# absent, matching the former eager try/except imports. Databricks also
+# tolerates ``OSError``: its SDK can raise one probing credentials at import.
+_OPTIONAL_EXPORTS = {
+    "DatabricksExecutor": ("omnigent.inner.databricks_executor", (OSError, ImportError)),
+    "ClaudeSDKExecutor": ("omnigent.inner.claude_sdk_executor", (ImportError,)),
+    "OpenResponsesExecutor": ("omnigent.inner.open_responses_sdk", (ImportError,)),
+    "OpenAIAgentsSDKExecutor": ("omnigent.inner.openai_agents_sdk_executor", (ImportError,)),
+    "CodexExecutor": ("omnigent.inner.codex_executor", (ImportError,)),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve a lazy re-export (or submodule) on first attribute access."""
+    target = _LAZY_EXPORTS.get(name)
+    if target is not None:
+        value = getattr(importlib.import_module(target), name)
+        globals()[name] = value
+        return value
+    optional = _OPTIONAL_EXPORTS.get(name)
+    if optional is not None:
+        target, absent_exceptions = optional
+        try:
+            value = getattr(importlib.import_module(target), name)
+        except absent_exceptions:
+            value = None
+        globals()[name] = value
+        return value
+    # The eager imports used to bind ``inner`` (and other submodules touched
+    # by them) as package attributes; keep ``omnigent.<submodule>`` access
+    # working for consumers that only ran ``import omnigent``.
+    try:
+        return importlib.import_module(f"{__name__}.{name}")
+    except ModuleNotFoundError as exc:
+        if exc.name != f"{__name__}.{name}":
+            raise
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+
+
+def __dir__() -> list[str]:
+    """Include the lazy re-exports in ``dir(omnigent)``."""
+    return sorted(set(globals()) | set(__all__))

-try:
-    from omnigent.inner.databricks_executor import DatabricksExecutor
-except (OSError, ImportError):
-    DatabricksExecutor = None  # type: ignore[misc,assignment]
-try:
-    from omnigent.inner.claude_sdk_executor import ClaudeSDKExecutor
-except ImportError:
-    ClaudeSDKExecutor = None  # type: ignore[misc,assignment]
-try:
-    from omnigent.inner.open_responses_sdk import OpenResponsesExecutor
-except ImportError:
-    OpenResponsesExecutor = None  # type: ignore[misc,assignment]
-try:
-    from omnigent.inner.openai_agents_sdk_executor import OpenAIAgentsSDKExecutor
-except ImportError:
-    OpenAIAgentsSDKExecutor = None  # type: ignore[misc,assignment]
-try:
-    from omnigent.inner.codex_executor import CodexExecutor
-except ImportError:
-    CodexExecutor = None  # type: ignore[misc,assignment]
-from omnigent.inner.loader import load_agent_def  # noqa: E402 — must follow md5 patch
-from omnigent.inner.tracing import (  # noqa: E402 — must follow md5 patch
-    disable_tracing,
-    enable_tracing,
-    is_tracing_enabled,
-)

 __all__ = [
    "AgentDef",
@@ -49,6 +49,19 @@ def record_post_failure(event_type: str, error: BaseException) -> None:
    _state["last_post_failure"] = (time.monotonic(), f"{event_type}: {error!r}")


+def record_transport_failure(detail: str) -> None:
+    """Record an already-formatted transport failure into the shared slot.
+
+    The SDK codex head has no forwarder POST path, but its subprocess still
+    runs under the same idle-turn watchdog. When the model gateway rejects the
+    CLI (e.g. a 401 read off the CLI's stderr), the turn emits no events and the
+    watchdog would otherwise blame a generic "wedged LLM". Recording the parsed
+    cause here lets the watchdog attribute the real failure, exactly as the
+    native forwarder path does. *detail* is a ready-to-surface human string.
+    """
+    _state["last_post_failure"] = (time.monotonic(), detail)
+
+
 def note_post_success() -> None:
    """
    Clear the failure record after a POST that reached the server.
@@ -146,6 +146,10 @@ def post_may_have_been_delivered(exc: httpx.HTTPError) -> bool:
    - Connection-establishment / pool-acquire failures
      (:data:`_DELIVERY_SAFE_RETRY_ERRORS`): no bytes were sent → not
      delivered → safe to retry, so ``False``.
+    - An unbound ``RequestError``: the failure occurred before httpx
+      associated the exception with the outbound request (for example,
+      an auth flow failed before yielding it). No bytes were sent → safe
+      to retry, so ``False``.
    - Any other transport error (read/write timeout, read/write error,
      remote protocol error): the request was sent and we never saw a
      response, so the server may have processed it → ambiguous →
@@ -159,6 +163,10 @@ def post_may_have_been_delivered(exc: httpx.HTTPError) -> bool:
        return False
    if isinstance(exc, _DELIVERY_SAFE_RETRY_ERRORS):
        return False
+    try:
+        _ = exc.request
+    except RuntimeError:
+        return False
    return True


@@ -24,6 +24,14 @@ spawn-env builder. Rows own their auth and model selection (``OWN_AUTH``): no
 Omnigent credential or model override is wired, so a ``/model`` pick is
 rejected up front rather than silently dropped.

+One consequence worth knowing before adding a row: the generic ACP spawn env is
+deny-by-default and a row has no ``env_passthrough`` of its own (only a
+user-configured ``acp:<slug>`` agent can declare one), so a row's CLI reaches the
+agent with the base environment only. A vendor that configures or authenticates
+*solely* from an environment variable therefore needs a user-configured agent
+rather than a row here; a vendor that reads stored credentials from disk (Devin,
+Grok's OAuth login) works as a row.
+
 This module stays import-light (stdlib + :mod:`omnigent.harness_install_spec`)
 so the registry, onboarding, and runner layers can all read it without cycles.
 """
@@ -73,6 +81,24 @@ class AcpCliHarness:
 # Keyed by canonical harness id. Keep keys sorted; each row's registrations
 # derive from here (see the module docstring for the full list).
 ACP_CLI_HARNESSES: dict[str, AcpCliHarness] = {
+    # Devin (Cognition's ``devin`` CLI) drives ``devin acp`` — its ACP stdio
+    # server. Ships via a curl installer (not npm) and authenticates through its
+    # own ``devin auth login``, which writes a credential file it reads back at
+    # spawn; Omnigent stores nothing. The row runs Devin's account-default model:
+    # a row carries no per-user model, and ``DEVIN_MODEL`` cannot reach the agent
+    # (see the env note above), so pinning a model needs a user-configured
+    # ``acp:<slug>`` agent whose command passes ``--model``.
+    "devin": AcpCliHarness(
+        install=HarnessInstallSpec(
+            "Devin",
+            "devin",
+            None,
+            login_args=("auth", "login"),
+            install_hint="curl -fsSL https://cli.devin.ai/install.sh | bash",
+            auth_hint="run `devin auth login` (Omnigent stores no Devin credential)",
+        ),
+        args=("acp",),
+    ),
    # Grok Build (xAI's ``grok`` CLI) drives ``grok agent stdio``. Ships via a
    # curl installer (not npm) and authenticates through its own ``grok login``
    # (xAI OAuth, device-code capable) or ``XAI_API_KEY``; Omnigent stores no
@@ -75,7 +75,6 @@ from tempfile import TemporaryDirectory
 import click
 import httpx
 import yaml
-from omnigent_client._http import is_loopback_url

 from omnigent._native_resume_hint import echo_native_resume_hint
 from omnigent._runner_startup import RunnerStartupProgress, runner_startup_progress
@@ -131,6 +130,7 @@ from omnigent.entities.session_resources import terminal_resource_id
 from omnigent.host.daemon_launch import (
    error_text,
    launch_or_reuse_daemon_runner,
+    open_daemon_client,
    wait_for_host_online,
    wait_for_runner_online,
 )
@@ -479,7 +479,11 @@ def _run_with_remote_server(
    from omnigent.cli import _ensure_host_daemon
    from omnigent.host.identity import load_or_create_host_identity

-    headers = _remote_headers(server_url=base_url)
+    # This machine's host id keys the WebSocket attach handshake (and its
+    # reconnects) to the replica holding the runner's tunnel; the CLI can set WS
+    # headers, so it rides the header (emitted only on a host-sharded deployment).
+    host_id = load_or_create_host_identity().host_id
+    headers = _remote_headers(server_url=base_url, host_id=host_id)
    try:
        resolved_session_id = _resolve_session_id_for_resume(
            base_url=base_url,
@@ -499,7 +503,6 @@ def _run_with_remote_server(
            with runner_startup_progress(initial_message="Preparing Antigravity...") as progress:
                progress.update("Connecting to local daemon...")
                _ensure_host_daemon(base_url)
-                host_id = load_or_create_host_identity().host_id
                bundle = None if resolved_session_id is not None else _bundle_agent(spec_path)
                prepared = await _prepare_antigravity_terminal_via_daemon(
                    base_url=base_url,
@@ -529,7 +532,7 @@ def _run_with_remote_server(

                :returns: None.
                """
-                new_headers = _remote_headers(server_url=base_url)
+                new_headers = _remote_headers(server_url=base_url, host_id=host_id)
                headers.clear()
                headers.update(new_headers)

@@ -590,12 +593,9 @@ async def _prepare_antigravity_terminal(
    :raises click.ClickException: If any server operation fails.
    """
    timeout = httpx.Timeout(30.0, read=120.0)
-    async with httpx.AsyncClient(
-        base_url=base_url,
-        headers=headers,
-        timeout=timeout,
-        trust_env=not is_loopback_url(base_url),
-    ) as client:
+    from omnigent.cli_auth import open_server_client
+
+    async with open_server_client(base_url, headers=headers, timeout=timeout) as client:
        bridge_id: str
        conversation_id: str
        resume = False
@@ -787,15 +787,11 @@ async def _prepare_antigravity_terminal_via_daemon(
    :raises click.ClickException: If setup fails.
    """
    timeout = httpx.Timeout(30.0, read=120.0)
-    async with httpx.AsyncClient(
-        base_url=base_url,
-        headers=headers,
-        timeout=timeout,
-        trust_env=not is_loopback_url(base_url),
-    ) as client:
+    async with open_daemon_client(base_url, headers, host_id, timeout=timeout) as client:
        bridge_id: str
        conversation_id: str
        resume = False
+        fresh_session = session_id is None
        if session_id is None:
            if session_bundle is None:
                raise click.ClickException(
@@ -804,10 +800,13 @@ async def _prepare_antigravity_terminal_via_daemon(
            _update_progress(startup_progress, "Creating Antigravity session...")
            bridge_id = _mint_agy_conversation_id()
            conversation_id = bridge_id
-            session_id = await _create_antigravity_session(
-                client,
-                session_bundle,
-                bridge_id=bridge_id,
+            session_id, _ = await asyncio.gather(
+                _create_antigravity_session(
+                    client,
+                    session_bundle,
+                    bridge_id=bridge_id,
+                ),
+                wait_for_host_online(client, host_id, timeout_s=_DAEMON_HOST_ONLINE_TIMEOUT_S),
            )
        else:
            _update_progress(startup_progress, "Loading Antigravity session...")
@@ -851,13 +850,15 @@ async def _prepare_antigravity_terminal_via_daemon(
            conversation_id = external if isinstance(external, str) and external else bridge_id
            resume = isinstance(external, str) and bool(external)

-        await wait_for_host_online(client, host_id, timeout_s=_DAEMON_HOST_ONLINE_TIMEOUT_S)
+        if not fresh_session:
+            await wait_for_host_online(client, host_id, timeout_s=_DAEMON_HOST_ONLINE_TIMEOUT_S)
        _update_progress(startup_progress, "Starting runner...")
        runner_id = await launch_or_reuse_daemon_runner(
            client,
            host_id=host_id,
            session_id=session_id,
            workspace=workspace,
+            fresh=fresh_session,
        )
        _update_progress(startup_progress, "Waiting for runner...")
        await wait_for_runner_online(client, runner_id, timeout_s=_DAEMON_RUNNER_ONLINE_TIMEOUT_S)
@@ -1620,10 +1621,11 @@ async def _close_antigravity_terminal(
    :param terminal_id: Terminal resource id.
    :returns: None.
    """
+    from omnigent.cli_auth import open_server_client
+
    try:
-        async with httpx.AsyncClient(
-            base_url=base_url,
-            trust_env=not is_loopback_url(base_url),
+        async with open_server_client(
+            base_url,
            headers=headers,
            timeout=httpx.Timeout(10.0),
        ) as client:
@@ -3269,8 +3269,10 @@ async def run_reader_with_bridge(
    # would keep targeting the rotated-away session).
    current = {"session_id": session_id}

-    async with httpx.AsyncClient(
-        base_url=base_url,
+    from omnigent.cli_auth import open_server_client
+
+    async with open_server_client(
+        base_url,
        headers=headers,
        auth=auth,
        timeout=httpx.Timeout(_READER_CLIENT_TIMEOUT_SECONDS),
@@ -603,9 +603,51 @@ def _is_url(target: str) -> bool:
 # Server URL client helpers
 # ---------------------------------------------------------------------------

+# Client-side ``session_id → host_id`` tracking, for routing a session's
+# tunnel-bound traffic to the right server replica when the server runs
+# multiple.
+#
+# A host's control tunnel and its runners' tunnels register on a single
+# replica, so the turn / resource / stream calls for a session running on that
+# host must name the host or they can reach a different replica than the runner
+# tunnel they need. The host_id is the routing key; it's populated when the CLI
+# learns a session's host (session GETs, daemon launch) and read once when a
+# client for that session is built — callers pass the session_id they already
+# have to ``_server_auth`` rather than the auth re-deriving it per request. This
+# is the Python peer of the web UI's ``sessionHost.ts``. (The host_id is
+# translated into the routing header inside ``cli_auth.databricks_request_headers``;
+# OSS only ever threads a host_id.)
+_session_hosts: dict[str, str] = {}
+
+
+def set_session_host(session_id: str, host_id: str | None) -> None:
+    """Record (or clear) the host a session is bound to.
+
+    A ``None``/empty host clears any stale mapping so a session that loses its
+    host binding stops routing to the old replica.
+
+    :param session_id: Session id, e.g. ``"conv_abc123"``.
+    :param host_id: The bound host id, e.g. ``"host_abc123"``, or ``None``.
+    """
+    if host_id:
+        _session_hosts[session_id] = host_id
+    else:
+        _session_hosts.pop(session_id, None)
+
+
+def get_session_host(session_id: str) -> str | None:
+    """Return a session's bound host id, or ``None`` when unknown.
+
+    :param session_id: Session id, e.g. ``"conv_abc123"``.
+    :returns: The host id, or ``None`` (session not seen yet, or hostless).
+    """
+    return _session_hosts.get(session_id)
+

 def _remote_headers(
    server_url: str | None = None,
+    *,
+    host_id: str | None,
 ) -> dict[str, str]:
    """
    Build headers for remote AP-server requests.
@@ -626,6 +668,11 @@ def _remote_headers(

    :param server_url: Optional remote server URL for looking up
        stored OIDC tokens, e.g. ``"http://localhost:6767"``.
+    :param host_id: The host a request is scoped to, or ``None`` when the
+        caller has no host to name (a host-less read, or a runner-internal
+        request that keys off the runner-env host_id). Required-keyword with
+        no default so every call site consciously decides — pass the request
+        path's host when it has one rather than silently defaulting to unkeyed.
    :returns: Headers to pass to httpx / OmnigentClient.
    """
    # Resolve the bearer in the documented precedence order (one credential
@@ -654,14 +701,25 @@ def _remote_headers(
            headers["Authorization"] = f"Bearer {creds.token}"
    # Workspace routing: when a ?o= selector was recorded at login, name the
    # workspace or the request routes to the account. Merged onto the result
-    # because these ad-hoc requests carry no httpx Auth.
+    # because these ad-hoc requests carry no httpx Auth. ``host_id`` pins a
+    # host-scoped request to the server replica holding that host's tunnel
+    # (translated to the routing header inside the builder); callers derive it
+    # from the request path.
    if server_url:
        from omnigent.cli_auth import databricks_request_headers

-        headers.update(databricks_request_headers(server_url))
+        headers.update(databricks_request_headers(server_url, host_id=host_id))
    return headers


+# Cache the resolved _DatabricksBearerAuth object per server URL so that
+# repeated calls to _remote_headers for the same URL reuse the same SDK
+# Config instance. The SDK's Config.authenticate() caches the OAuth token
+# in memory and only re-runs the CLI shell-out when it nears expiry, so
+# reusing the object is both fast and correct for long-running callers.
+_databricks_auth_cache: dict[str, object] = {}
+
+
 def _stored_databricks_record_token(server_url: str) -> str | None:
    """Mint a workspace token from a stored Databricks Apps record.

@@ -671,6 +729,12 @@ def _stored_databricks_record_token(server_url: str) -> str | None:
    that issue many requests should use :class:`_DatabricksTokenAuth`,
    which reuses the SDK config across requests.

+    The resolved ``_DatabricksBearerAuth`` object is cached per
+    ``server_url`` so repeated calls reuse the same SDK ``Config``
+    instance. The SDK serves the cached OAuth token from memory and only
+    re-runs the Databricks CLI when the token nears expiry, so this is
+    both fast on repeat calls and safe for long-running callers.
+
    :param server_url: The remote server URL, e.g.
        ``"https://myapp-123.aws.databricksapps.com"``.
    :returns: A bearer token, or ``None`` when no pointer record is
@@ -686,8 +750,11 @@ def _stored_databricks_record_token(server_url: str) -> str | None:
    if workspace_host is None:
        return None
    try:
-        auth, _host = _resolve_databricks_auth(host=workspace_host)
-        return auth.current_token()
+        auth = _databricks_auth_cache.get(server_url)
+        if auth is None:
+            auth, _host = _resolve_databricks_auth(host=workspace_host)
+            _databricks_auth_cache[server_url] = auth
+        return auth.current_token()  # type: ignore[union-attr]
    except (DatabricksAuthError, ImportError, ValueError):
        return None

@@ -708,12 +775,18 @@ class _DatabricksTokenAuth(httpx.Auth):
    def __init__(
        self,
        server_url: str | None = None,
+        *,
+        session_id: str | None = None,
    ) -> None:
        """
        :param server_url: Remote server URL for looking up stored
            OIDC tokens, e.g. ``"http://localhost:6767"``.
+        :param session_id: The single session this client drives; its
+            requests are pinned to that session's host replica. ``None``
+            for a hostless / local client.
        """
        self._server_url = server_url
+        self._session_id = session_id
        raw = os.environ.get(_REMOTE_AUTH_TOKEN_ENV)
        self._static_token = raw.strip() if raw else None
        # Lazily-resolved, then reused, SDK auth (one Config → one token
@@ -723,6 +796,19 @@ class _DatabricksTokenAuth(httpx.Auth):
        self._sdk_auth: _DatabricksBearerAuth | None = None
        self._sdk_auth_resolved = False

+    def pin_session(self, session_id: str | None) -> None:
+        """Repoint this auth at a different session's host.
+
+        ``auth_flow`` reads ``get_session_host(self._session_id)`` per request,
+        so changing the pinned session id changes which host replica the slice
+        key routes to — without rebuilding the client. Used when a client
+        outlives the session it was built for (e.g. a ``--fork`` in the REPL
+        resumes under a new conversation id on a new host).
+
+        :param session_id: The session id to pin to, or ``None`` to unpin.
+        """
+        self._session_id = session_id
+
    def _sdk_token(self) -> str | None:
        """
        Return a bearer token from the reused SDK auth, or ``None``.
@@ -777,27 +863,34 @@ class _DatabricksTokenAuth(httpx.Auth):
        :yields: The request with auth header set.
        """
        # Workspace routing (empty when none recorded); independent of the
-        # credential branch below.
+        # credential branch below. On a host-sharded deployment, also pin the
+        # turn/resource/stream traffic for this client's session to the replica
+        # holding its runner tunnel — the slice key is the session's host_id,
+        # from the session→host map. An unsharded server has no sharding layer,
+        # so no key.
        if self._server_url:
            from omnigent.cli_auth import databricks_request_headers

-            request.headers.update(databricks_request_headers(self._server_url))
+            session_host = get_session_host(self._session_id) if self._session_id else None
+            request.headers.update(
+                databricks_request_headers(self._server_url, host_id=session_host)
+            )
        if self._static_token:
            request.headers["Authorization"] = f"Bearer {self._static_token}"
-            yield request
-            return
-        # Check stored OIDC token from `omnigent login`.
-        if self._server_url:
-            from omnigent.cli_auth import load_token
+        else:
+            # Check stored OIDC token from `omnigent login`, then fall back to
+            # the reused Databricks SDK auth.
+            oidc_token = None
+            if self._server_url:
+                from omnigent.cli_auth import load_token

-            oidc_token = load_token(self._server_url)
+                oidc_token = load_token(self._server_url)
            if oidc_token:
                request.headers["Authorization"] = f"Bearer {oidc_token}"
-                yield request
-                return
-        token = self._sdk_token()
-        if token:
-            request.headers["Authorization"] = f"Bearer {token}"
+            else:
+                token = self._sdk_token()
+                if token:
+                    request.headers["Authorization"] = f"Bearer {token}"
        yield request


@@ -825,6 +918,8 @@ def _server_headers(

 def _server_auth(
    server_url: str | None = None,
+    *,
+    session_id: str | None,
 ) -> httpx.Auth | None:
    """
    Build an httpx Auth for a remote Omnigent server client.
@@ -837,21 +932,29 @@ def _server_auth(

    :param server_url: Optional remote server URL for looking up
        stored OIDC tokens.
+    :param session_id: The single session this client drives, e.g.
+        ``"conv_abc123"``. When set, the auth pins every request to the
+        replica holding that session's runner tunnel (its host, looked up
+        in the session→host map). Required-keyword with no default so every
+        caller consciously decides: pass the session when known so its
+        traffic co-locates, or ``None`` before a session exists / for a
+        host-less client (the slice key then falls back to the runner-env
+        or CLI-own-host id inside ``databricks_request_headers``).
    :returns: Auth instance, or ``None``.
    """
    raw = os.environ.get(_REMOTE_AUTH_TOKEN_ENV)
    if raw and raw.strip():
-        return _DatabricksTokenAuth(server_url=server_url)
+        return _DatabricksTokenAuth(server_url=server_url, session_id=session_id)
    # Check stored `omnigent login` records: a session JWT or a
    # Databricks Apps pointer record.
    if server_url:
        from omnigent.cli_auth import load_databricks_workspace_host, load_token

        if load_token(server_url) or load_databricks_workspace_host(server_url):
-            return _DatabricksTokenAuth(server_url=server_url)
+            return _DatabricksTokenAuth(server_url=server_url, session_id=session_id)
    creds = _read_databrickscfg(None)
    if creds is not None and creds.token:
-        return _DatabricksTokenAuth(server_url=server_url)
+        return _DatabricksTokenAuth(server_url=server_url, session_id=session_id)
    return None


@@ -1129,7 +1232,7 @@ def _wrapper_label_for_conversation(
    try:
        resp = httpx.get(
            f"{base_url}/v1/sessions/{conversation_id}",
-            headers=_remote_headers(server_url=base_url),
+            headers=_remote_headers(server_url=base_url, host_id=None),
            timeout=10.0,
        )
    except httpx.HTTPError as exc:
@@ -1218,7 +1321,7 @@ def _attach_session_info(
    try:
        resp = httpx.get(
            f"{base_url}/v1/sessions/{conversation_id}",
-            headers=_remote_headers(server_url=base_url),
+            headers=_remote_headers(server_url=base_url, host_id=None),
            timeout=10.0,
        )
    except httpx.HTTPError as exc:
@@ -1232,6 +1335,15 @@ def _attach_session_info(
        return empty
    if not isinstance(body, dict):
        return empty
+    # Record the session's host so host-scoped requests (turn dispatch,
+    # resource, stream) can reach the replica holding that host's runner tunnel.
+    # Always write — clearing a stale mapping when the server now reports no
+    # host (e.g. the session's runner was torn down) is as important as setting
+    # one, so later requests for a hostless session don't keep a dead slice key.
+    session_host = body.get("host_id")
+    set_session_host(
+        conversation_id, session_host if isinstance(session_host, str) and session_host else None
+    )
    runner_id = body.get("runner_id")
    snapshot_online = body.get("runner_online")
    if not isinstance(runner_id, str) or not runner_id:
@@ -1269,7 +1381,7 @@ def _pick_agent(base_url: str, *, quiet: bool = False) -> str:
    """
    resp = httpx.get(
        f"{base_url}/v1/sessions",
-        headers=_remote_headers(server_url=base_url),
+        headers=_remote_headers(server_url=base_url, host_id=None),
        params={"limit": 100},
        timeout=10.0,
    )
@@ -1477,24 +1589,29 @@ async def _prepare_chat_session_via_daemon(
    )
    from omnigent.host.daemon_launch import (
        launch_or_reuse_daemon_runner,
+        open_daemon_client,
        wait_for_host_online,
        wait_for_runner_online,
    )
    from omnigent.native_terminal import bind_session_runner

-    try:
+    async def resolve_session() -> tuple[str, bool]:
+        """Fork, resume, or create the session to bind, and say if it is fresh.
+
+        :returns: The session id and whether it was created just now.
+        :raises click.ClickException: If the server rejects the create/fork.
+        """
        async with OmnigentClient(base_url=base_url, headers=headers, auth=auth) as sdk:
            try:
                if fork_session_id is not None:
                    fork_result = await sdk.sessions.fork(fork_session_id)
-                    session_id = fork_result["id"]
-                elif resume_conversation_id is not None:
-                    session_id = resume_conversation_id
-                else:
-                    created = await sdk.sessions.create(
-                        bundle, filename="agent.tar.gz", workspace=workspace
-                    )
-                    session_id = created.id
+                    return fork_result["id"], False
+                if resume_conversation_id is not None:
+                    return resume_conversation_id, False
+                created = await sdk.sessions.create(
+                    bundle, filename="agent.tar.gz", workspace=workspace
+                )
+                return created.id, True
            except ClientOmnigentError as exc:
                # Any create/fork/resume rejection here is a server-side answer, not
                # a client bug worth a traceback: a wrong base URL that answers
@@ -1505,25 +1622,32 @@ async def _prepare_chat_session_via_daemon(
                    f"Could not start a session on {base_url}: {exc}"
                ) from exc

+    try:
        # A separate raw httpx client for the host-runner protocol (the daemon
-        # launch helpers operate on httpx, not the SDK).
+        # launch helpers operate on httpx, not the SDK), pinned to the host's replica.
        timeout = httpx.Timeout(30.0, read=120.0)
-        async with httpx.AsyncClient(
-            base_url=base_url,
-            headers=headers,
-            auth=auth,
-            timeout=timeout,
-            trust_env=not is_loopback_url(base_url),
+        async with open_daemon_client(
+            base_url, headers, host_id, auth=auth, timeout=timeout
        ) as client:
            if progress is not None:
                progress.update(STARTUP_PHASE_CONNECTING)
-            await wait_for_host_online(
-                client, host_id, timeout_s=_DAEMON_CHAT_HOST_ONLINE_TIMEOUT_S
+            (session_id, fresh_session), _ = await asyncio.gather(
+                resolve_session(),
+                wait_for_host_online(
+                    client, host_id, timeout_s=_DAEMON_CHAT_HOST_ONLINE_TIMEOUT_S
+                ),
            )
            if progress is not None:
                progress.update(STARTUP_PHASE_LAUNCHING_AGENT)
+            # Record the session's host so its turn/resource/stream traffic reaches
+            # the replica holding the host's runner tunnel.
+            set_session_host(session_id, host_id)
            runner_id = await launch_or_reuse_daemon_runner(
-                client, host_id=host_id, session_id=session_id, workspace=workspace
+                client,
+                host_id=host_id,
+                session_id=session_id,
+                workspace=workspace,
+                fresh=fresh_session,
            )
            await wait_for_runner_online(
                client, runner_id, timeout_s=_DAEMON_CHAT_RUNNER_ONLINE_TIMEOUT_S
@@ -1627,8 +1751,8 @@ def _chat_via_daemon(
            # the spinner before printing its interactive prompt.
            _await_accounts_first_run_setup(base_url, progress=progress)

-            headers = _remote_headers(server_url=base_url)
-            auth = _server_auth(server_url=base_url)
+            headers = _remote_headers(server_url=base_url, host_id=None)
+            auth = _server_auth(server_url=base_url, session_id=None)
            host_id = load_or_create_host_identity().host_id
            workspace = str(Path.cwd().resolve())

@@ -2077,7 +2201,7 @@ def _run_headless_prompt(
        async with OmnigentClient(
            base_url=base_url,
            headers=_server_headers(runner_id=runner_id),
-            auth=_server_auth(server_url=base_url),
+            auth=_server_auth(server_url=base_url, session_id=None),
        ) as client:
            # Both a local bundle and a remote registered agent go through
            # the sessions API; _query_sessions_once picks the create route
@@ -3838,10 +3962,13 @@ def _run_repl(
        if attach_harness is not None:
            launch_harness = attach_harness

+        # Named so a --fork below can repoint it: the auth pins the slice key
+        # to whichever session it names, and a fork lands under a new id.
+        server_auth = _server_auth(server_url=base_url, session_id=resume_conversation_id)
        async with OmnigentClient(
            base_url=base_url,
            headers=_server_headers(runner_id=runner_id),
-            auth=_server_auth(server_url=base_url),
+            auth=server_auth,
        ) as client:
            # When --fork is set, call the fork endpoint before
            # entering the REPL so the user lands in the fork.
@@ -3852,6 +3979,17 @@ def _run_repl(
                except Exception as exc:
                    raise click.ClickException(f"Fork failed: {exc}") from exc
                effective_resume_id = fork_result["id"]
+                # The fork is a fresh session on (possibly) a different host.
+                # Record its host and repoint the auth from the source session
+                # to the fork, so this client's requests route to the fork's
+                # replica instead of the source's for the rest of the REPL.
+                fork_host = fork_result.get("host_id")
+                set_session_host(
+                    effective_resume_id,
+                    fork_host if isinstance(fork_host, str) and fork_host else None,
+                )
+                if isinstance(server_auth, _DatabricksTokenAuth):
+                    server_auth.pin_session(effective_resume_id)
                click.echo(
                    f"Conversation forked. To return to the previous "
                    f"conversation, run --resume {fork_session_id}",
@@ -3932,7 +4070,7 @@ def _run_one_shot(
        async with OmnigentClient(
            base_url=base_url,
            headers=_server_headers(runner_id=runner_id),
-            auth=_server_auth(server_url=base_url),
+            auth=_server_auth(server_url=base_url, session_id=resume_conversation_id),
        ) as client:
            # Both a local bundle and a remote registered agent go through
            # the sessions API; _query_sessions_once picks the create route
@@ -55,6 +55,21 @@ CUSTOM_MODEL_OPTION_ENV_VAR = "ANTHROPIC_CUSTOM_MODEL_OPTION"
 #: takes — so it is not part of the vocabulary below.
 CUSTOM_MODEL_OPTION_NAME_ENV_VAR = "ANTHROPIC_CUSTOM_MODEL_OPTION_NAME"

+#: BACK-COMPAT. Omnigent's picker-row id for the custom slot. Named for the
+#: model the slot first carried (Sonnet 5, which had no family alias of its
+#: own), but a Smart Routing launch pins ITS model there, so the id does not
+#: describe the contents — read the slot, never this name. Sessions persist
+#: it as a model override, so retiring it needs a migration; slated for
+#: removal in 0.10.0 along with the row, once the ``sonnet`` pin is Sonnet 5.
+LEGACY_CUSTOM_SLOT_ROW_ID = "sonnet_5"
+
+#: BACK-COMPAT. Spellings the pre-0.10 substring test read as "this is the
+#: custom slot's model", kept because :func:`normalized_model_id` does not
+#: fold a vendor-prefixed ``anthropic/claude-sonnet-5`` onto the catalog id
+#: the slot holds. Consulted only after an exact match misses; retired with
+#: :data:`LEGACY_CUSTOM_SLOT_ROW_ID` in 0.10.0.
+LEGACY_CUSTOM_SLOT_SPELLINGS: tuple[str, ...] = ("sonnet-5", "sonnet_5")
+
 #: Launch-env keys that define this session's model vocabulary.
 MODEL_VOCABULARY_ENV_VARS: tuple[str, ...] = (
    *ALIAS_MODEL_ENV_VARS.values(),
@@ -162,6 +177,14 @@ def claude_model_alias(
    candidate = model.strip().lower()
    if candidate in CLAUDE_MODEL_ALIASES:
        return candidate
+    # Bracket variants of the family aliases (``sonnet[1m]``) are settable
+    # aliases in their own right — the harness enumerates them in /model's
+    # usage line and resolves the marker itself (the family pin plus the
+    # marker on a pinned env). Stepping one down to its family would
+    # silently drop the marker; refusing it blocks a switch the pane accepts.
+    base, bracket, marker = candidate.partition("[")
+    if bracket and marker.endswith("]") and base in CLAUDE_MODEL_ALIASES:
+        return candidate
    pins = alias_pins(env)
    normalized = normalized_model_id(model)
    for alias, pinned in pins.items():
@@ -202,4 +225,14 @@ def claude_model_command_arg(
    custom = environ.get(CUSTOM_MODEL_OPTION_ENV_VAR, "").strip()
    if custom and normalized_model_id(custom) == normalized_model_id(model):
        return custom
+    candidate = model.strip()
+    if not alias_pins(env) and candidate.lower().startswith("claude-"):
+        # A full Anthropic model id names an EXACT generation, and ``/model``
+        # on an unpinned (canonical-endpoint) session accepts full ids
+        # verbatim — the same spelling the harness's own enumeration
+        # resolves. Stepping down to the family alias here would switch to
+        # claude's CURRENT generation of that family instead (picking
+        # "Opus 4.8 (1M context)" used to type ``/model opus`` and land on
+        # Opus 5).
+        return candidate
    return claude_model_alias(model, env)
@@ -55,23 +55,22 @@ from urllib import error, request
 from omnigent._platform import stable_user_id
 from omnigent.claude_model_vocabulary import MODEL_VOCABULARY_ENV_VARS
 from omnigent.claude_native_message_display_hook import MESSAGE_DELTAS_FILE
+from omnigent.claude_native_status import CONTEXT_RAW_FILE
 from omnigent.json_types import JsonObject as _JsonObject
 from omnigent.kiro_native_bridge import bridge_root as kiro_bridge_root

 if TYPE_CHECKING:
    import httpx

+    from omnigent.inner.datamodel import OSEnvSandboxSpec
+    from omnigent.inner.os_env import OSEnvironment
    from omnigent.llms.context_window import ModelPricing

-from omnigent.inner.bundle_skills import claude_native_skill_args
-from omnigent.inner.datamodel import OSEnvSandboxSpec, OSEnvSpec
 from omnigent.inner.hook_scripts.subagent_router import (
    AGENT_TOOL_MATCHER as CLAUDE_SUBAGENT_TOOL_MATCHER,
 )
-from omnigent.inner.os_env import OSEnvironment, create_os_environment
 from omnigent.reasoning_effort import CLAUDE_EFFORTS
 from omnigent.tools.base import Tool, ToolContext
-from omnigent.tools.builtins.os_env import build_os_env_tools

 _logger = logging.getLogger(__name__)

@@ -96,6 +95,10 @@ _RECENT_LOCAL_COMMAND_LINE_LIMIT = 200
 _RECENT_LOCAL_COMMAND_WINDOW_S = 10.0
 _FORKED_FROM_LINE_LIMIT = 200
 _TOOL_RELAY_FILE = "tool_relay.json"
+# Shell-sourceable sibling of tool_relay.json so the curl-based hook
+# commands can discover the live relay without a JSON parser. Re-written
+# on every relay start, so hooks survive runner restarts (new port).
+_TOOL_RELAY_ENV_FILE = "tool_relay.env"
 _TMUX_FILE = "tmux.json"
 _PERMISSION_HOOK_FILE = "permission_hook.json"
 _CONTEXT_FILE = "context.json"
@@ -176,11 +179,58 @@ _PASTED_PLACEHOLDER_PREFIX = "[Pasted text"
 # whether the draft is rendered in the input box. Short enough to fit
 # on the prompt row of a default 80-column detached pane.
 _DRAFT_NEEDLE_MAX_CHARS = 24
+# Mode footer Claude Code renders below its input box, keyed by
+# ``--permission-mode`` value. There is no non-interactive mode command, so
+# a live switch cycles with shift+tab and reads this footer to know where it
+# landed. The prompting mode is ``default`` on the CLI, "manual" on screen.
+_PERMISSION_MODE_FOOTERS: dict[str, str] = {
+    "default": "manual mode on",
+    "acceptEdits": "accept edits on",
+    "plan": "plan mode on",
+    "auto": "auto mode on",
+}
+# Modes shift+tab can reach. ``dontAsk`` is never in the cycle and
+# ``bypassPermissions`` only joins it when launched into, so both are
+# rejected up front.
+CYCLEABLE_PERMISSION_MODES = frozenset(_PERMISSION_MODE_FOOTERS)
+# Cap on shift+tab presses. The cycle is 3-5 modes wide depending on which
+# optional modes are enabled, so a full lap plus slack proves the target is
+# unreachable rather than slow.
+_MODE_CYCLE_MAX_PRESSES = 8
+# Wait for the footer to repaint after a shift+tab before reading it.
+_MODE_FOOTER_SETTLE_TIMEOUT_S = 2.0
+_MODE_FOOTER_POLL_INTERVAL_S = 0.1
 # Footer Claude Code's interactive ``/model`` picker renders while it is open.
 # Omnigent never drives that picker — it switches with ``/model <id>`` — but a
 # picker the person opened by hand covers the input box, so an injection would
 # be lost; the readiness gate treats it as "not ready".
 _MODEL_PICKER_OPEN_HINT = "use this session only"
+# Header of the ctrl+r prompt-history search. Like the picker it covers the
+# input box, but its selected history row renders the composer's ``❯`` glyph
+# above the filter box's frame rule, so the readiness scan alone reads it as
+# a mounted input box — keystrokes would land in the filter field, and the
+# submit Enter would replay whatever old prompt is selected.
+_REVERSE_SEARCH_OPEN_HINT = "Search prompts ·"
+# Surfaces a person can leave covering the composer from the embedded
+# terminal. Each documents Escape as its dismissal ("Esc to cancel"), which
+# closes it without committing anything and restores the empty input box, so
+# an injected web-UI message reclaims the pane instead of typing into the
+# surface. Shell mode (``!``) also occupies the composer but has no safe
+# textual marker: its footer line ("! for shell mode") appears verbatim in
+# the ``?`` shortcuts panel while the composer is fully usable.
+_OCCUPIED_INPUT_HINTS: tuple[str, ...] = (
+    _REVERSE_SEARCH_OPEN_HINT,
+    _MODEL_PICKER_OPEN_HINT,
+)
+# How long to keep dismissing an occupying surface that verifiably stays on
+# screen, and the spacing between repeated Escapes — a busy repaint can
+# swallow one (same reasoning as ``_SUBMIT_RETRY_INTERVAL_S``). The spacing
+# also bounds a residual hazard: were a successful Escape's repaint to
+# outlast it, the stale hint would draw a retry onto the bare composer
+# (interrupting a turn). 0.75s dwarfs a TUI repaint, so that window is
+# accepted rather than confirmation-gated.
+_OCCUPIED_INPUT_DISMISS_TIMEOUT_S = 3.0
+_OCCUPIED_INPUT_DISMISS_RETRY_INTERVAL_S = 0.75
 # Titles of the confirmation dialog Claude Code pops when a switch invalidates
 # the prompt cache — one component, titled for what is being switched. It only
 # appears on a session with history, and it took ~1.9s to render on a warm
@@ -224,6 +274,14 @@ _INVOCATION_SETTINGS_FILE = "claude-settings.json"
 ToolExecutor = Callable[[str, _JsonObject], Awaitable[object]]


+class ClaudePromptTimeout(RuntimeError):
+    """Claude Code's input box did not render before delivery timed out."""
+
+
+class TmuxSessionNotAdvertised(RuntimeError):
+    """The bridge's tmux target was not advertised before the deadline."""
+
+
 def _absolute_syntactic_path(path: Path) -> Path:
    """
    Return an absolute path without following symlinks.
@@ -417,6 +475,11 @@ class TranscriptReadResult:
        entry was scanned.
    :param latest_model: ``message.model`` from the most recent
        assistant entry, or ``None``.
+    :param latest_custom_title: ``customTitle`` from the most recent
+        ``custom-title`` record — the explicit title a ``/rename`` typed
+        in the Claude Code pane writes. ``None`` when no such record was
+        scanned. Claude's own auto-generated ``aiTitle`` is deliberately
+        not surfaced here; Omnigent titles unnamed sessions itself.
    """

    line_cursor: int
@@ -425,6 +488,7 @@ class TranscriptReadResult:
    items: list[ClaudeTranscriptItem]
    latest_usage: dict[str, int] | None = None
    latest_model: str | None = None
+    latest_custom_title: str | None = None


@dataclass(frozen=True)
@@ -1184,6 +1248,48 @@ def read_model_env(bridge_dir: Path) -> dict[str, str]:
    }


+def record_model_vocabulary(
+    bridge_dir: Path,
+    *,
+    launch_env: Mapping[str, str] | None,
+    launch_model: str | None,
+) -> None:
+    """
+    Persist the launch's model vocabulary after the bridge dir exists.
+
+    The runner prepares the bridge before it resolves the provider config,
+    so the vocabulary (alias pins + custom slot) and the launch model land
+    here in a second write once known — the same keys
+    :func:`prepare_bridge_dir` records on the CLI path, so
+    :func:`read_model_env` / :func:`read_launch_model` serve both paths
+    identically.
+
+    :param bridge_dir: Bridge directory path.
+    :param launch_env: The resolved launch env (pins + custom slot), or
+        ``None`` for a bare subscription launch.
+    :param launch_model: The model the launch pins via ``--model``, or
+        ``None``.
+    :returns: None.
+    """
+    config = _read_json_file(bridge_dir / _CONFIG_FILE)
+    if not isinstance(config, dict):
+        return
+    model_env = {
+        key: launch_env[key]
+        for key in MODEL_VOCABULARY_ENV_VARS
+        if launch_env is not None and launch_env.get(key)
+    }
+    changed = False
+    if model_env and config.get("model_env") != model_env:
+        config["model_env"] = model_env
+        changed = True
+    if launch_model and config.get("launch_model") != launch_model:
+        config["launch_model"] = launch_model
+        changed = True
+    if changed:
+        _write_json_file(bridge_dir / _CONFIG_FILE, config)
+
+
 def read_bridge_id(bridge_dir: Path) -> str | None:
    """
    Read the opaque bridge id from bridge config.
@@ -1356,22 +1462,18 @@ def build_hook_settings(
        "command": command,
    }
    # ``MessageDisplay`` fires once per streamed assistant-text chunk and
-    # Claude blocks on the hook, so it gets a dedicated stdlib-only
-    # appender module instead of the heavier observer ``hook`` above —
-    # the per-chunk subprocess must stay cheap. It just appends the
-    # chunk to ``<bridge_dir>/message_deltas.jsonl``; the forwarder tails
-    # that file and publishes ``response.output_text.delta`` events.
-    message_display_command_parts = [
-        python,
-        "-I",
-        "-m",
-        "omnigent.claude_native_message_display_hook",
-        "--bridge-dir",
-        str(bridge_dir),
-    ]
+    # Claude blocks on the hook, so the hot path must not even pay an
+    # interpreter spawn: a /bin/sh appender writes Claude's raw payload
+    # (flattened to one line — JSON strings never carry literal newlines)
+    # to ``message_deltas.jsonl``. The reader parses records by key and
+    # skips non-delta lines, so raw envelopes need no Python-side shaping.
+    deltas_quoted = shlex.quote(str(bridge_dir / MESSAGE_DELTAS_FILE))
    message_display_hook = {
        "type": "command",
-        "command": shlex.join(message_display_command_parts),
+        "command": (
+            "p=$(cat | tr -d '\\r\\n'); "
+            f'[ -n "$p" ] && printf \'%s\\n\' "$p" >> {deltas_quoted}; :'
+        ),
    }
    hooks: dict[str, list[_JsonObject]] = {
        "SessionStart": [{"hooks": [session_start_hook]}],
@@ -1462,19 +1564,43 @@ def build_hook_settings(
        hooks["PermissionRequest"] = [{"hooks": [permission_hook]}]

        # Policy-gate native Claude Code tools, not just relay/MCP tools.
-        evaluate_policy_command_parts = [
-            python,
-            "-I",
-            "-m",
-            "omnigent.claude_native_hook",
-            "evaluate-policy",
-            "--bridge-dir",
-            str(bridge_dir),
-        ]
+        # The hook is a bare curl against the relay's evaluate-policy
+        # endpoint (which owns all transformation and verdict logic), so
+        # Claude's blocking tool-call path pays no interpreter spawn. The
+        # relay's coordinates are re-read from tool_relay.env on every
+        # event, so hooks survive runner restarts. Before the relay exists
+        # (it starts in the background at session create — a very early
+        # hook can beat it) or when curl fails, the same stdin is
+        # replayed into the Python hook, which owns the direct-server
+        # path and the phase-aware fail-closed contract — exactly the
+        # pre-curl behavior.
+        relay_env_quoted = shlex.quote(str(bridge_dir / _TOOL_RELAY_ENV_FILE))
+        evaluate_policy_python = shlex.join(
+            [
+                python,
+                "-I",
+                "-m",
+                "omnigent.claude_native_hook",
+                "evaluate-policy",
+                "--bridge-dir",
+                str(bridge_dir),
+            ]
+        )
+        evaluate_policy_command = (
+            "p=$(cat); "
+            f"if [ -r {relay_env_quoted} ]; then . {relay_env_quoted}; "
+            "out=$(printf '%s' \"$p\" | curl -sf --max-time 86400 "
+            '-H "Authorization: Bearer $OMNIGENT_RELAY_TOKEN" '
+            "-H 'Content-Type: application/json' --data-binary @- "
+            '"$OMNIGENT_RELAY_URL/hook/claude/evaluate-policy" 2>/dev/null) '
+            "&& { printf '%s' \"$out\"; exit 0; }; fi; "
+            f"printf '%s' \"$p\" | {evaluate_policy_python}"
+        )
        evaluate_policy_hook: _JsonObject = {
            "type": "command",
-            "command": shlex.join(evaluate_policy_command_parts),
+            "command": evaluate_policy_command,
        }
+
        # In bypassPermissions mode PermissionRequest never fires, so
        # AskUserQuestion needs its own PreToolUse hook to surface the
        # form. It's a no-op in other modes to avoid double-surfacing.
@@ -1559,20 +1685,20 @@ def build_hook_settings(
    if api_key_helper:
        settings["apiKeyHelper"] = api_key_helper
    # Override Claude Code's statusLine so we receive its stdin (the
-    # only place ``context_window`` surfaces). Chain to whatever the
-    # user had globally so claude-hud / their bar still renders.
-    status_parts = [
-        python,
-        "-I",
-        "-m",
-        "omnigent.claude_native_status",
-        "--bridge-dir",
-        str(bridge_dir),
-    ]
+    # only place ``context_window`` surfaces). A /bin/sh shim captures
+    # the raw payload atomically (no interpreter spawn on Claude's
+    # blocking statusLine path — the forwarder normalizes it into
+    # ``context.json``) and chains to whatever the user had globally so
+    # claude-hud / their bar still renders.
+    raw_quoted = shlex.quote(str(bridge_dir / CONTEXT_RAW_FILE))
+    status_command = (
+        f"p=$(cat); printf '%s' \"$p\" > {raw_quoted}.$$.tmp"
+        f" && mv -f {raw_quoted}.$$.tmp {raw_quoted}"
+    )
    chain_command = read_user_status_line_command()
    if chain_command is not None:
-        status_parts.extend(["--chain", chain_command])
-    settings["statusLine"] = {"type": "command", "command": shlex.join(status_parts)}
+        status_command += f"; printf '%s' \"$p\" | ( {chain_command} )"
+    settings["statusLine"] = {"type": "command", "command": status_command}
    return settings


@@ -1730,6 +1856,9 @@ def augment_claude_args(
    )
    if append_system_prompt:
        args.extend(["--append-system-prompt", append_system_prompt])
+    # Imported here: bundle-skills parsing rides the spec graph; launch-only.
+    from omnigent.inner.bundle_skills import claude_native_skill_args
+
    args.extend(
        claude_native_skill_args(
            bundle_dir,
@@ -2142,11 +2271,14 @@ def read_transcript_items_since(

    Claude Code writes append-only JSONL records whose ``message``
    payloads include user prompts, assistant text, native tool calls,
-    and native tool results. This parser intentionally ignores
-    metadata records (title, file-history, permission mode, system
-    bookkeeping) and raw ``thinking`` blocks, while translating the
-    user-visible semantic records into Omnigent item types the web UI
-    already understands.
+    and native tool results. This parser intentionally renders no
+    conversation item for metadata records (title, file-history,
+    permission mode, system bookkeeping) or raw ``thinking`` blocks,
+    while translating the user-visible semantic records into Omnigent
+    item types the web UI already understands. Some metadata is still
+    read for out-of-band mirroring rather than dropped outright — a
+    ``custom-title`` record surfaces on
+    :attr:`TranscriptReadResult.latest_custom_title`.

    :param transcript_path: Claude transcript path, e.g.
        ``"/home/user/.claude/projects/x/session.jsonl"``.
@@ -2207,6 +2339,7 @@ def read_transcript_items_since_with_position(
    active_settled_id = settled_response_id
    latest_usage: dict[str, int] | None = None
    latest_model: str | None = None
+    latest_custom_title: str | None = None
    for record in read_result.records:
        if record.text is None:
            continue
@@ -2236,6 +2369,9 @@ def read_transcript_items_since_with_position(
        model = _model_from_transcript_entry(entry)
        if model is not None:
            latest_model = model
+        custom_title = _custom_title_from_transcript_entry(entry)
+        if custom_title is not None:
+            latest_custom_title = custom_title
    return TranscriptReadResult(
        line_cursor=read_result.line_cursor,
        byte_offset=read_result.byte_offset,
@@ -2243,6 +2379,7 @@ def read_transcript_items_since_with_position(
        items=items,
        latest_usage=latest_usage,
        latest_model=latest_model,
+        latest_custom_title=latest_custom_title,
    )


@@ -2295,6 +2432,7 @@ def read_transcript_items_from_offset(
    active_settled_id = settled_response_id
    latest_usage: dict[str, int] | None = None
    latest_model: str | None = None
+    latest_custom_title: str | None = None
    for record in read_result.records:
        if record.text is None:
            continue
@@ -2325,6 +2463,9 @@ def read_transcript_items_from_offset(
        model = _model_from_transcript_entry(entry)
        if model is not None:
            latest_model = model
+        custom_title = _custom_title_from_transcript_entry(entry)
+        if custom_title is not None:
+            latest_custom_title = custom_title
    return TranscriptReadResult(
        line_cursor=read_result.line_cursor,
        byte_offset=read_result.byte_offset,
@@ -2332,6 +2473,7 @@ def read_transcript_items_from_offset(
        items=items,
        latest_usage=latest_usage,
        latest_model=latest_model,
+        latest_custom_title=latest_custom_title,
    )


@@ -2871,6 +3013,11 @@ def inject_user_message(
    (see :func:`_wait_for_claude_prompt_ready`). The second gate closes
    a race on freshly-created sessions where the first message would
    otherwise be typed into a still-booting TUI and silently dropped.
+    Between the two, any surface the person left covering the composer
+    from the embedded terminal — a ctrl+r history search, a hand-opened
+    ``/model`` picker — is dismissed with Escape
+    (see :func:`_restore_occupied_input`), so the message reclaims the
+    input box instead of typing into that surface.

    Delivered as one bracketed paste via ``tmux load-buffer`` (from a
    temp file) + ``paste-buffer -p`` so interior newlines ride as raw CR
@@ -2904,6 +3051,11 @@ def inject_user_message(
        after repeated submit Enters (message not delivered).
    """
    info = _wait_for_tmux_info(bridge_dir, timeout_s=timeout_s)
+    # A ctrl+r history search or hand-opened /model picker left covering
+    # the composer swallows everything typed below — and can hide the
+    # prompt glyph, wedging the readiness gate — so reclaim the input box
+    # before waiting on it.
+    _restore_occupied_input(info["socket_path"], info["tmux_target"])
    # tmux.json only means the tmux session exists; Claude Code's input
    # box mounts a few seconds later. Block until the prompt renders so
    # the first message isn't typed into a still-booting TUI and dropped.
@@ -3106,10 +3258,16 @@ def kill_session(
        there is no live session to kill.
    :returns: None.
    :raises RuntimeError: If the tmux target is not advertised in
-        time, or if the ``tmux kill-session`` invocation fails.
+        time, or if ``tmux kill-session`` fails for an unexpected reason.
    """
    info = _wait_for_tmux_info(bridge_dir, timeout_s=timeout_s)
-    _run_tmux(info["socket_path"], "kill-session", "-t", info["tmux_target"])
+    try:
+        _run_tmux(info["socket_path"], "kill-session", "-t", info["tmux_target"])
+    except RuntimeError as exc:
+        detail = str(exc).lower()
+        if "can't find session" in detail or "no server running on" in detail:
+            return
+        raise


 def inject_slash_command(
@@ -3123,6 +3281,11 @@ def inject_slash_command(
    """
    Type a Claude Code slash command into the tmux pane and submit it.

+    A surface the person left covering the composer from the embedded
+    terminal (ctrl+r history search, hand-opened ``/model`` picker) is
+    dismissed first — see :func:`_restore_occupied_input` — so the
+    command cannot be typed into it.
+
    :param bridge_dir: Bridge directory path, e.g.
        ``/tmp/omnigent/claude-native/<digest>``.
    :param command: Single-line slash command including the leading
@@ -3159,6 +3322,10 @@ def inject_slash_command(
    info = _wait_for_tmux_info(bridge_dir, timeout_s=timeout_s)
    socket_path = info["socket_path"]
    tmux_target = info["tmux_target"]
+    # Same reclaim as inject_user_message: a ctrl+r search or hand-opened
+    # /model picker left covering the composer would swallow the C-u and
+    # the typed command.
+    _restore_occupied_input(socket_path, tmux_target)
    # ``C-u`` clears any draft the user is mid-typing; otherwise the
    # paste below concatenates with their text and Enter submits
    # ``<their-draft>/effort high`` as a turn. Unlike Escape it does
@@ -3266,6 +3433,171 @@ def _confirm_tui_dialog(
    return False


+def _permission_mode_from_pane(pane: str) -> str | None:
+    """
+    Read Claude Code's current permission mode off a captured pane.
+
+    The footer (``⏵⏵ auto mode on``, ``⏸ plan mode on``, ...) always sits
+    below the input box's closing rule, so the scan starts there rather than
+    at a fixed offset from the bottom: the footer's height scales with
+    concurrent subagents, which a fixed window cannot bound (the same reason
+    :func:`_claude_prompt_rendered` anchors on :func:`_is_box_rule`). Anchoring
+    also excludes transcript text structurally — a mode name Claude echoed
+    while *discussing* modes sits above the box and can't be misread as live.
+
+    :param pane: Captured pane text from :func:`_capture_pane`.
+    :returns: The ``--permission-mode`` value for the rendered footer,
+        e.g. ``"auto"``, or ``None`` when no footer is visible (the
+        pane is mid-repaint, or the mode is one with no footer).
+    """
+    lines = [line for line in pane.splitlines() if line.strip()]
+    # Below the last box rule is the footer region. With no rule the input box
+    # isn't mounted; fall back to the tail so a footer still reads during boot.
+    last_rule = max((i for i, line in enumerate(lines) if _is_box_rule(line)), default=None)
+    region = lines[last_rule + 1 :] if last_rule is not None else lines[-_PROMPT_SCAN_TAIL_LINES:]
+    for line in reversed(region):
+        for mode, footer in _PERMISSION_MODE_FOOTERS.items():
+            if footer in line:
+                return mode
+    return None
+
+
+def _read_settled_permission_mode(
+    socket_path: str,
+    tmux_target: str,
+    *,
+    previous: str | None = None,
+) -> str | None:
+    """
+    Poll the pane until its permission-mode footer settles.
+
+    A shift+tab repaints the footer asynchronously, so an immediate
+    capture can read nothing — or, worse, still read the PREVIOUS mode
+    and make the cycler believe the keystroke did nothing. Passing
+    *previous* waits for the footer to actually change.
+
+    :param socket_path: Absolute path to the tmux socket.
+    :param tmux_target: tmux pane target string, e.g. ``"main"``.
+    :param previous: Mode read before the keystroke that prompted this
+        read, e.g. ``"plan"``. The pane keeps rendering it until the TUI
+        repaints, so a read that returns it is treated as not-yet-settled
+        and retried; ``None`` accepts the first mode seen (the initial
+        read, where there is nothing to change from).
+    :returns: The rendered mode, or ``None`` if none appeared — or the
+        footer never moved off *previous* — before
+        :data:`_MODE_FOOTER_SETTLE_TIMEOUT_S`.
+    """
+    deadline = time.monotonic() + _MODE_FOOTER_SETTLE_TIMEOUT_S
+    while True:
+        mode = _permission_mode_from_pane(_capture_pane(socket_path, tmux_target))
+        if mode is not None and mode != previous:
+            return mode
+        if time.monotonic() >= deadline:
+            # Timed out: report the last mode seen so a pane that legitimately
+            # stayed put is distinguished from one with no footer at all.
+            return mode
+        time.sleep(_MODE_FOOTER_POLL_INTERVAL_S)
+
+
+def set_permission_mode(
+    bridge_dir: Path,
+    *,
+    mode: str,
+    timeout_s: float = _TMUX_READY_TIMEOUT_S,
+) -> str:
+    """
+    Switch the running Claude terminal to *mode* by cycling shift+tab.
+
+    Claude Code has no non-interactive way to set a live session's mode
+    (``--permission-mode`` is launch-only, ``/permissions`` is an interactive
+    dialog, settings load at startup), so this drives the TUI's shift+tab
+    cycle, reading the mode footer after each press. The cycle is walked
+    rather than computed: its width varies with which optional modes are
+    enabled, so a fixed press count could land on the wrong mode.
+
+    :param bridge_dir: Bridge directory path, e.g.
+        ``/tmp/omnigent/claude-native/<digest>``.
+    :param mode: Target ``--permission-mode`` value, one of
+        :data:`CYCLEABLE_PERMISSION_MODES`, e.g. ``"auto"``.
+    :param timeout_s: Seconds to wait for ``tmux.json`` to be
+        advertised by the runner, e.g. ``30.0``.
+    :returns: The mode now rendered in the pane (== *mode*).
+    :raises ValueError: If *mode* is not cycle-reachable.
+    :raises RuntimeError: If the tmux target is not advertised in time,
+        a ``tmux`` invocation fails, the pane never renders a mode
+        footer, or the target is not reached within
+        :data:`_MODE_CYCLE_MAX_PRESSES` presses (the mode is not in
+        this session's cycle).
+    """
+    if mode not in CYCLEABLE_PERMISSION_MODES:
+        raise ValueError(
+            f"permission mode {mode!r} cannot be switched on a running session; "
+            f"expected one of {sorted(CYCLEABLE_PERMISSION_MODES)}"
+        )
+    info = _wait_for_tmux_info(bridge_dir, timeout_s=timeout_s)
+    socket_path, tmux_target = info["socket_path"], info["tmux_target"]
+    # The footer only renders once the input box is mounted; without
+    # this gate a shift+tab sent mid-boot is dropped and the read below
+    # reports a mode the keystroke never reached.
+    _wait_for_claude_prompt_ready(socket_path, tmux_target, timeout_s=timeout_s)
+    current = _read_settled_permission_mode(socket_path, tmux_target)
+    if current is None:
+        pane = _capture_pane(socket_path, tmux_target)
+        raise RuntimeError(
+            "Claude Code did not render a permission-mode footer, so its current "
+            f"mode could not be read.{_format_terminal_failure_tail(pane)}"
+        )
+    seen = [current]
+    for _ in range(_MODE_CYCLE_MAX_PRESSES):
+        if current == mode:
+            return current
+        # No ``-l``: tmux must interpret ``BTab`` as the shift+tab key.
+        _run_tmux(socket_path, "send-keys", "-t", tmux_target, "BTab")
+        settled = _read_settled_permission_mode(socket_path, tmux_target, previous=current)
+        if settled is not None:
+            current = settled
+            seen.append(current)
+    if current == mode:
+        return current
+    raise RuntimeError(
+        f"Could not switch Claude Code to {mode!r} mode: cycled shift+tab "
+        f"{_MODE_CYCLE_MAX_PRESSES} times and only reached {sorted(set(seen))}. "
+        "The mode is not available in this session's cycle."
+    )
+
+
+def confirm_dialog_if_open(bridge_dir: Path, *, hint: str) -> bool:
+    """
+    Accept the *hint* dialog iff it is on screen RIGHT NOW; never blind-Enter.
+
+    Loop-safe building block for watchers that outlive a single injection
+    (a mid-turn ``/model`` queues in Claude's composer and pops its confirm
+    dialog only when the turn settles — minutes later). Unlike
+    :func:`_confirm_tui_dialog` there is no timeout fallback Enter, so
+    calling this every few seconds can never type into a surface that is
+    not the named dialog.
+
+    :param bridge_dir: Bridge directory path.
+    :param hint: Text the dialog renders, e.g.
+        :data:`SWITCH_MODEL_DIALOG_HINT`.
+    :returns: ``True`` when the dialog was on screen and confirmed.
+    """
+    try:
+        info = _wait_for_tmux_info(bridge_dir, timeout_s=1.0)
+    except (RuntimeError, OSError):
+        return False
+    socket_path = info["socket_path"]
+    tmux_target = info["tmux_target"]
+    try:
+        pane = _capture_pane(socket_path, tmux_target)
+        if hint not in pane:
+            return False
+        _confirm_and_verify_dialog_closed(socket_path, tmux_target, hint=hint)
+    except (RuntimeError, OSError):
+        return False
+    return True
+
+
 def _confirm_and_verify_dialog_closed(
    socket_path: str,
    tmux_target: str,
@@ -3514,6 +3846,55 @@ def claude_pane_ready(bridge_dir: Path) -> bool:
    return _claude_prompt_rendered(pane)


+def _restore_occupied_input(socket_path: str, tmux_target: str) -> None:
+    """
+    Dismiss a terminal-opened surface occupying Claude's input box.
+
+    A person can leave the composer covered from the embedded terminal —
+    the ctrl+r prompt-history search, or a hand-opened ``/model`` picker
+    (:data:`_OCCUPIED_INPUT_HINTS`). Keystrokes injected while one is up
+    land in that surface instead of the chat input: the history search
+    filters on the pasted text and its Enter replays whatever old prompt
+    is selected. Each surface documents Escape as its dismissal ("Esc to
+    cancel"), closing it without committing anything and restoring the
+    empty input box, so the web-UI message wins the pane.
+
+    Escape is only sent while a hint is verifiably in the current
+    capture — never blind, because on the bare composer Escape interrupts
+    an in-flight turn. An empty (torn) capture means "unknown" and gets
+    no Escape. A swallowed Escape is re-sent while the surface remains,
+    spaced by :data:`_OCCUPIED_INPUT_DISMISS_RETRY_INTERVAL_S`.
+    Best-effort: a surface that outlives
+    :data:`_OCCUPIED_INPUT_DISMISS_TIMEOUT_S` is left on screen and the
+    caller's readiness gate or delivery verification fails loud, exactly
+    as it did before this restore existed.
+
+    :param socket_path: Absolute path to the tmux socket.
+    :param tmux_target: tmux pane target string, e.g. ``"main"``.
+    :returns: None.
+    """
+    deadline = time.monotonic() + _OCCUPIED_INPUT_DISMISS_TIMEOUT_S
+    last_escape: float | None = None
+    while True:
+        pane = _capture_pane(socket_path, tmux_target)
+        hint = next((text for text in _OCCUPIED_INPUT_HINTS if text in pane), None)
+        if hint is None:
+            return
+        now = time.monotonic()
+        if now >= deadline:
+            _logger.warning(
+                "claude-native: input box still occupied (%r) after %.1fs; proceeding",
+                hint,
+                _OCCUPIED_INPUT_DISMISS_TIMEOUT_S,
+            )
+            return
+        if last_escape is None or now - last_escape >= _OCCUPIED_INPUT_DISMISS_RETRY_INTERVAL_S:
+            _logger.info("claude-native: dismissing %r covering the input box", hint)
+            _run_tmux(socket_path, "send-keys", "-t", tmux_target, "Escape")
+            last_escape = now
+        time.sleep(_CLAUDE_READY_POLL_INTERVAL_S)
+
+
 def _claude_prompt_rendered(pane: str) -> bool:
    """
    Return whether Claude Code's input prompt is rendered in a pane.
@@ -3707,7 +4088,7 @@ def _wait_for_claude_prompt_ready(
    :param tmux_target: tmux pane target string, e.g. ``"main"``.
    :param timeout_s: Seconds to wait for the prompt, e.g. ``30.0``.
    :returns: None.
-    :raises RuntimeError: If the prompt never renders within
+    :raises ClaudePromptTimeout: If the prompt never renders within
        *timeout_s* (Claude failed to boot). The message carries a poll
        count, how many of those polls saw an empty capture, and the tail
        of the last non-empty capture the loop actually observed (see
@@ -3744,7 +4125,7 @@ def _wait_for_claude_prompt_ready(
    # session is alive but capture-pane came back blank); non-empty captures
    # with no box point at Claude never rendering the prompt (a boot crash,
    # e.g. a ``JSON Parse error``, whose text the tail then surfaces).
-    raise RuntimeError(
+    raise ClaudePromptTimeout(
        f"Claude Code terminal did not become ready within {timeout_s}s "
        f"(input prompt never rendered in {polls} polls, "
        f"{empty_polls} empty captures). The message was not delivered."
@@ -3800,7 +4181,7 @@ def _wait_for_tmux_info(bridge_dir: Path, *, timeout_s: float) -> dict[str, str]
    :param bridge_dir: Bridge directory path.
    :param timeout_s: Seconds to wait, e.g. ``30.0``.
    :returns: ``{"socket_path": ..., "tmux_target": ...}``.
-    :raises RuntimeError: If the file never appears with valid
+    :raises TmuxSessionNotAdvertised: If the file never appears with valid
        ``socket_path`` and ``tmux_target`` fields.
    """
    deadline = time.monotonic() + timeout_s
@@ -3812,7 +4193,7 @@ def _wait_for_tmux_info(bridge_dir: Path, *, timeout_s: float) -> dict[str, str]
        if isinstance(socket_path, str) and isinstance(tmux_target, str):
            return {"socket_path": socket_path, "tmux_target": tmux_target}
        time.sleep(0.05)
-    raise RuntimeError(
+    raise TmuxSessionNotAdvertised(
        "Claude terminal tmux target is not advertised yet. Wait for the "
        "terminal to launch before sending messages from the web UI."
    )
@@ -3856,6 +4237,7 @@ def start_tool_relay(
        loop,
        policy_client=policy_client,
        session_id=session_id,
+        bridge_dir=bridge_dir,
    )
    httpd = ThreadingHTTPServer(("127.0.0.1", 0), handler_cls)
    host, port = _http_server_host_port(httpd)
@@ -3869,6 +4251,13 @@ def start_tool_relay(
    if session_id is not None:
        relay_info["session_id"] = session_id
    _write_json_file(bridge_dir / _TOOL_RELAY_FILE, relay_info)
+    # token_urlsafe's alphabet is [A-Za-z0-9_-], safe inside single quotes.
+    env_path = bridge_dir / _TOOL_RELAY_ENV_FILE
+    env_path.write_text(
+        f"OMNIGENT_RELAY_URL='http://{host}:{port}'\nOMNIGENT_RELAY_TOKEN='{token}'\n",
+        encoding="utf-8",
+    )
+    os.chmod(env_path, 0o600)
    thread = threading.Thread(
        target=httpd.serve_forever,
        name="claude-native-tool-relay",
@@ -4069,6 +4458,7 @@ def _tool_relay_handler_factory(
    *,
    policy_client: httpx.AsyncClient | None = None,
    session_id: str | None = None,
+    bridge_dir: Path | None = None,
 ) -> type[BaseHTTPRequestHandler]:
    """
    Create an HTTP handler class for active-turn tool calls.
@@ -4103,7 +4493,11 @@ def _tool_relay_handler_factory(

            :returns: None.
            """
-            if self.path not in ("/tool", "/policies/evaluate"):
+            if self.path not in (
+                "/tool",
+                "/policies/evaluate",
+                "/hook/claude/evaluate-policy",
+            ):
                self.send_error(HTTPStatus.NOT_FOUND)
                return
            if self.headers.get("Authorization") != f"Bearer {token}":
@@ -4113,6 +4507,9 @@ def _tool_relay_handler_factory(
            if payload is None:
                self.send_error(HTTPStatus.BAD_REQUEST)
                return
+            if self.path == "/hook/claude/evaluate-policy":
+                self._handle_hook_evaluate(payload)
+                return
            if self.path == "/policies/evaluate":
                self._handle_policy_evaluate(payload)
                return
@@ -4125,6 +4522,89 @@ def _tool_relay_handler_factory(
                arguments = {}
            self._send_json(_run_relay_tool(tool_executor, loop, name, arguments))

+        def _respond_hook_output(self, output: dict[str, object] | None) -> None:
+            """Answer a hook-evaluate request with final hook output JSON.
+
+            :param output: Hook output dict, or ``None`` for "no opinion"
+                (empty body — Claude proceeds).
+            """
+            raw = b"" if output is None else json.dumps(output).encode("utf-8")
+            self.send_response(HTTPStatus.OK)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(raw)))
+            self.end_headers()
+            if raw:
+                self.wfile.write(raw)
+
+        def _handle_hook_evaluate(self, payload: _JsonObject) -> None:
+            """Serve one Claude policy hook event end to end.
+
+            The hook subprocess is a bare curl: this endpoint does the
+            payload→EvaluationRequest transform, the upstream evaluate
+            call, and the EvaluationResponse→hook-output transform, so the
+            blocking hook path pays no interpreter spawn. Responses are
+            always 200; enforcement failures are expressed as fail-closed
+            hook output.
+            """
+            # Heavy policy imports stay off this module's import path (hook
+            # subprocesses import it); the relay runs inside the runner
+            # process where these modules are already loaded.
+            from omnigent.native_policy_hook import (
+                evaluation_response_to_hook_output,
+                fail_closed_hook_output,
+                hook_payload_to_evaluation_request,
+            )
+
+            raw_event = payload.get("hook_event_name")
+            hook_event = raw_event if isinstance(raw_event, str) else ""
+            if policy_client is None or session_id is None:
+                self._respond_hook_output(None)
+                return
+            eval_request = hook_payload_to_evaluation_request(hook_event, payload)
+            if eval_request is None:
+                self._respond_hook_output(None)
+                return
+            context = eval_request["event"]["context"]
+            context["harness"] = "claude-native"
+            if bridge_dir is not None:
+                status_model = read_claude_status_model(bridge_dir)
+                if status_model:
+                    context["model"] = status_model
+            # Stable re-attach id: a retried long-poll reattaches to the
+            # same parked ASK instead of raising a second approval card.
+            request_body = {
+                **eval_request,
+                "_omnigent_elicitation_id": f"elicit_evaluate_{secrets.token_hex(16)}",
+            }
+            import urllib.parse as _up
+
+            url = f"/v1/sessions/{_up.quote(session_id, safe='')}/policies/evaluate"
+            verdict: object = None
+            last_error: str | None = None
+            for attempt in range(3):
+                if attempt:
+                    time.sleep(0.4)
+                future = asyncio.run_coroutine_threadsafe(
+                    policy_client.post(url, json=request_body), loop
+                )
+                try:
+                    resp = future.result(timeout=86400.0)
+                except Exception as exc:  # noqa: BLE001 — shaped fail-closed below
+                    last_error = str(exc).strip() or type(exc).__name__
+                    continue
+                if resp.status_code != HTTPStatus.OK:
+                    last_error = f"server returned HTTP {resp.status_code}"
+                    continue
+                try:
+                    verdict = json.loads(resp.content)
+                except (ValueError, TypeError):
+                    last_error = "malformed EvaluationResponse body"
+                break
+            if not isinstance(verdict, dict) or not verdict.get("result"):
+                self._respond_hook_output(fail_closed_hook_output(hook_event, last_error))
+                return
+            self._respond_hook_output(evaluation_response_to_hook_output(hook_event, verdict))
+
        def _handle_policy_evaluate(self, payload: _JsonObject) -> None:
            if policy_client is None or session_id is None:
                self.send_error(HTTPStatus.SERVICE_UNAVAILABLE)
@@ -4692,6 +5172,14 @@ def _build_tools(config: _JsonObject) -> tuple[dict[str, Tool], Callable[[], Non
    :returns: ``(tools, close_tools)`` where ``close_tools``
        releases any helper processes.
    """
+    # Imported here, not at module top: this drags the tools/spec/pydantic
+    # graph (~300 ms of interpreter startup), and this module is on the
+    # import path of every per-chunk/per-tool-call Claude hook subprocess.
+    # Only the bridge MCP server (launch path) ever builds these tools.
+    from omnigent.inner.datamodel import OSEnvSandboxSpec, OSEnvSpec
+    from omnigent.inner.os_env import create_os_environment
+    from omnigent.tools.builtins.os_env import build_os_env_tools
+
    workspace_raw = config.get("workspace")
    workspace = Path(workspace_raw) if isinstance(workspace_raw, str) and workspace_raw else None
    os_env: OSEnvironment | None = None
@@ -4766,6 +5254,32 @@ def _model_from_transcript_entry(entry: _JsonObject) -> str | None:
    return None


+def _custom_title_from_transcript_entry(entry: _JsonObject) -> str | None:
+    """
+    Return ``customTitle`` from a ``custom-title`` transcript record.
+
+    Claude Code appends this metadata record when the operator renames
+    the session from the pane (``/rename``). It carries no ``message``,
+    so it renders no conversation item; the forwarder mirrors it onto the
+    Omnigent session title instead.
+
+    Only the explicit user title is read. Claude also writes an
+    ``aiTitle`` record holding its own generated summary, which is
+    ignored here because Omnigent runs its own background titler and two
+    auto-titlers would fight over one field.
+
+    :param entry: One decoded transcript JSONL record.
+    :returns: The operator-chosen title, e.g. ``"auth-refactor"``, or
+        ``None`` for other record types and blank values.
+    """
+    if entry.get("type") != "custom-title":
+        return None
+    title = entry.get("customTitle")
+    if isinstance(title, str) and title.strip():
+        return title
+    return None
+
+
 def read_claude_context_state(bridge_dir: Path) -> _JsonObject | None:
    """
    Read the most recent statusLine snapshot from ``context.json``.
@@ -4800,6 +5314,31 @@ def read_claude_context_state(bridge_dir: Path) -> _JsonObject | None:
    return parsed


+def read_permission_mode(bridge_dir: Path) -> str | None:
+    """
+    Read the permission mode currently rendered in the Claude pane.
+
+    Non-blocking and best-effort: the forwarder calls this every poll so an
+    in-pane shift+tab switch reaches the web UI, which otherwise never sees it
+    (only UI-driven switches stamp the mode label). Returns ``None`` when the
+    terminal isn't up or the pane shows no mode footer, so a caller can treat
+    "unknown" as "no fresh observation" rather than a change.
+
+    :param bridge_dir: Bridge directory path, e.g.
+        ``/tmp/omnigent/claude-native/<digest>``.
+    :returns: The ``--permission-mode`` value rendered in the pane, e.g.
+        ``"auto"``, or ``None`` when it cannot be determined.
+    """
+    payload = _read_json_file(bridge_dir / _TMUX_FILE)
+    if not isinstance(payload, dict):
+        return None
+    socket_path = payload.get("socket_path")
+    tmux_target = payload.get("tmux_target")
+    if not isinstance(socket_path, str) or not isinstance(tmux_target, str):
+        return None
+    return _permission_mode_from_pane(_capture_pane(socket_path, tmux_target))
+
+
 def read_claude_status_model(bridge_dir: Path) -> str | None:
    """
    Read the active model id from the statusLine snapshot ``context.json``.
@@ -36,6 +36,7 @@ from omnigent.claude_native_bridge import (
    read_hook_events_from_offset,
    read_hook_events_since_with_position,
    read_message_deltas_from_offset,
+    read_permission_mode,
    read_transcript_items_from_offset,
    read_transcript_items_since_with_position,
    read_transcript_path,
@@ -45,6 +46,7 @@ from omnigent.claude_native_bridge import (
    write_active_session_id,
 )
 from omnigent.claude_native_message_display_hook import MESSAGE_DELTAS_FILE
+from omnigent.claude_native_status import sync_raw_status_context
 from omnigent.entities.session_resources import terminal_resource_id
 from omnigent.reasoning_effort import CLAUDE_EFFORTS, EFFORT_CLEAR_VALUES

@@ -81,6 +83,11 @@ _SUBAGENT_IDLE_QUIESCENCE_S = 5.0
 # ``agent-<id>.jsonl`` transcript.
 _SUBAGENT_META_GLOB = "agent-*.meta.json"
 _DEFAULT_POLL_INTERVAL_S = 0.25
+# Minimum spacing between permission-mode pane reads. Unlike the model mirror
+# (which reads a JSON file), this spawns a ``tmux capture-pane`` subprocess, so
+# it runs well below the poll interval; a mode switch is a human action and 2s
+# of lag is imperceptible.
+_PERMISSION_MODE_POLL_INTERVAL_S = 2.0
 # Hard ceiling on one poll iteration of the forward loop. A silently stalled
 # await anywhere in the pipeline used to stop mirroring, status and the busy
 # signal forever; the deadline cancels the stall (the traceback names it) and
@@ -489,16 +496,15 @@ class _ForwardDedupeState:
    :param usage: Last ``message.usage`` snapshot POSTed via
        ``external_session_usage``, or ``None`` if none yet.
    :param context_window: Last context-window POSTed, or ``None``.
-    :param observed_model: Last tier alias seen in the transcript,
-        sticky across polls (the incremental window often carries no
-        fresh ``message.model``), e.g. ``"opus"``. ``None`` until first
-        seen.
-    :param posted_model: Last tier alias POSTed via
-        ``external_model_change``. Seeded from the first observation
-        WITHOUT a POST so a passive spawn default never overwrites a
-        pending silent model handoff; only a later in-TUI switch is
-        mirrored. Left behind ``observed_model`` on a failed POST so the
-        next poll retries. ``None`` until the first observation.
+    :param observed_model: Last VERBATIM model seen (statusLine or
+        transcript), sticky across polls (the incremental window often
+        carries no fresh ``message.model``), e.g.
+        ``"claude-opus-4-8[1m]"``. ``None`` until first seen.
+    :param posted_model: Last verbatim model POSTed via
+        ``external_model_change``. Every observation posts — the first
+        one is the launch report that seeds the session's
+        ``reported_model``. Left behind ``observed_model`` on a failed
+        POST so the next poll retries. ``None`` until the first post.
    :param posted_cost: Last DISPLAY cost (USD) POSTed as
        ``cumulative_cost_usd`` — the statusLine total ``S`` verbatim.
        ``None`` until the first cost post. Used to dedupe so a steady
@@ -509,6 +515,15 @@ class _ForwardDedupeState:
        from ``posted_cost`` because it advances mid-turn (with in-flight
        sub-agent spend) while ``S`` stays frozen. ``None`` until first
        post.
+    :param observed_title: Last ``custom-title`` seen in the transcript,
+        sticky across polls, e.g. ``"auth-refactor"``. ``None`` until the
+        operator runs ``/rename``.
+    :param posted_title: Last title POSTed via
+        ``external_session_title``. Unlike ``posted_model`` this is NOT
+        seeded without a POST — a ``custom-title`` record only exists
+        because the operator renamed the session, so the first
+        observation is a real change worth mirroring. Left behind
+        ``observed_title`` on a failed POST so the next poll retries.
    :param recorded_token_usage: Last token counters recorded on a
        ``claude_native.usage`` span as ``gen_ai.usage.*``. Deduped
        separately from ``usage`` because that snapshot also moves on
@@ -522,6 +537,8 @@ class _ForwardDedupeState:
    recorded_token_usage: dict[str, int] | None = None
    observed_model: str | None = None
    posted_model: str | None = None
+    observed_title: str | None = None
+    posted_title: str | None = None
    # Last DISPLAY cost (USD) POSTed as ``cumulative_cost_usd`` — the
    # statusLine total ``S`` verbatim (matches /cost in the Claude TUI).
    # Kept to suppress duplicate posts when S hasn't advanced.
@@ -531,6 +548,13 @@ class _ForwardDedupeState:
    # sub-agent spend so the gate can block mid-turn. Separate baseline
    # because it can advance while ``posted_cost`` (S) is frozen.
    posted_policy_cost: float | None = None
+    # Last permission mode POSTed as ``external_permission_mode_change`` —
+    # mirrors the launch mode and any in-pane shift+tab switch, neither of
+    # which the web UI can observe on its own.
+    posted_permission_mode: str | None = None
+    # Monotonic deadline before which the next pane read is skipped, so the
+    # subprocess spawn runs at _PERMISSION_MODE_POLL_INTERVAL_S, not every poll.
+    permission_mode_next_read: float = 0.0
    # Turn-settle latch driving the scheduled-wake boundary. The Stop edge
    # records the ended turn's id as PENDING; it activates (moves to
    # ``settled_response_id``) only once a fully-consumed transcript batch
@@ -782,6 +806,9 @@ async def forward_claude_transcript_to_session(
    # the per-poll cost reconciliation from re-parsing unchanged transcripts.
    # Reset on /clear and /fork rotations alongside ``dedupe``.
    cost_cache: dict[Path, _TranscriptCostCacheEntry] = {}
+    # (mtime_ns, size) of the statusLine shim's raw capture last normalized
+    # into context.json (see claude_native_status.sync_raw_status_context).
+    status_raw_sig: tuple[int, int] | None = None
    # Per-process latch: once we PATCH the conversation with the
    # Claude-native session id, never PATCH again. Persists for the
    # lifetime of the forwarder task; the server's idempotence handles
@@ -794,9 +821,9 @@ async def forward_claude_transcript_to_session(
    task_statuses: dict[str, str] = {}
    task_order: list[str] = []
    timeout = httpx.Timeout(_POST_TIMEOUT_S)
-    async with httpx.AsyncClient(
-        base_url=base_url, headers=headers, auth=auth, timeout=timeout
-    ) as client:
+    from omnigent.cli_auth import open_server_client
+
+    async with open_server_client(base_url, headers=headers, auth=auth, timeout=timeout) as client:
        while True:
            try:
                async with asyncio.timeout(_FORWARD_LOOP_STALL_DEADLINE_S):
@@ -901,6 +928,9 @@ async def forward_claude_transcript_to_session(
                            session_id=current_session_id,
                            bridge_dir=bridge_dir,
                        )
+                    # Normalize the statusLine shim's raw capture into
+                    # context.json (one stat when nothing changed).
+                    status_raw_sig = sync_raw_status_context(bridge_dir, status_raw_sig)
                    transcript_path = read_transcript_path(bridge_dir)
                    if transcript_path is not None:
                        state = await _ensure_state_for_transcript(
@@ -994,6 +1024,14 @@ async def forward_claude_transcript_to_session(
                            bridge_dir=bridge_dir,
                            dedupe=dedupe,
                        )
+                        # Same rationale for the permission mode: a shift+tab in
+                        # the pane emits no event, so poll the footer.
+                        await _forward_permission_mode_from_pane(
+                            client=client,
+                            session_id=current_session_id,
+                            bridge_dir=bridge_dir,
+                            dedupe=dedupe,
+                        )
            except asyncio.CancelledError:
                raise
            except TimeoutError:
@@ -3554,19 +3592,27 @@ async def _forward_available_items(
                _http_status_for_log(exc),
                exc_info=True,
            )
-    # Mirror a TUI-side `/model` switch to the web picker. The transcript
-    # records the resolved concrete id (e.g. "claude-opus-4-8"); collapse
-    # it to the picker's tier alias. This transcript-derived observation
-    # only fires when a turn produces a fresh ``message.model``, so it lags
-    # an in-pane switch by one turn — the per-poll statusLine sync
-    # (:func:`_forward_model_from_status`) is the primary, low-latency
-    # source; this stays as a fallback for cold-resume before the first
-    # statusLine render. Both share ``dedupe`` so neither double-posts.
+    # Report the transcript's model verbatim. This transcript-derived
+    # observation only fires when a turn produces a fresh
+    # ``message.model``, so it lags an in-pane switch by one turn — the
+    # per-poll statusLine sync (:func:`_forward_model_from_status`) is the
+    # primary, low-latency source; this stays as a fallback for cold-resume
+    # before the first statusLine render. Both share ``dedupe`` so neither
+    # double-posts.
    await _post_model_change_if_new(
        client,
        session_id=session_id,
        dedupe=dedupe,
-        alias=_model_alias_for(result.latest_model),
+        model=result.latest_model,
+    )
+    # Mirror a TUI-side `/rename` to the web session list. Claude writes the
+    # operator's title as a `custom-title` metadata record, which renders no
+    # conversation item, so this is the only path that surfaces it.
+    await _post_title_change_if_new(
+        client,
+        session_id=session_id,
+        dedupe=dedupe,
+        title=result.latest_custom_title,
    )
    return updated

@@ -4150,38 +4196,81 @@ def _gen_ai_usage_tokens(usage: Mapping[str, float | str] | None) -> dict[str, i
    return tokens


-def _model_alias_for(model: str | None) -> str | None:
+async def _post_external_permission_mode_change(
+    client: httpx.AsyncClient,
+    *,
+    session_id: str,
+    mode: str,
+) -> None:
    """
-    Collapse a concrete Claude model id to the picker's tier alias.
+    Post one ``external_permission_mode_change`` event to the Sessions API.

-    The web model picker speaks Claude Code's version-agnostic aliases
-    (``"fable"`` / ``"opus"`` / ``"sonnet"`` / ``"haiku"``), plus the one
-    extra concrete-id slot ``"sonnet_5"`` (see
-    :data:`omnigent.claude_native._UCODE_CLAUDE_CUSTOM_TIER`) for the newer
-    Sonnet generation offered alongside the default ``"sonnet"`` tier; the
-    transcript records the resolved concrete id (e.g.
-    ``"claude-opus-4-8"`` or ``"databricks-claude-sonnet-5"``).
-    Mapping to the tier keeps the mirrored value in the picker's
-    vocabulary and makes a web→TUI round-trip a no-op. The older Sonnet
-    (``sonnet-4-6``) collapses to the generic ``"sonnet"`` alias — it is the
-    default that row is bound to.
+    Lets the web mode picker reflect a shift+tab switch made inside the Claude
+    Code terminal, which Omnigent has no other way to observe.

-    :param model: Concrete model id from the transcript, e.g.
-        ``"claude-opus-4-8"``; ``None`` when none observed yet.
-    :returns: ``"fable"`` / ``"opus"`` / ``"sonnet"`` / ``"sonnet_5"`` /
-        ``"haiku"`` when the id carries a known tier token, else ``None``
-        (the caller skips the post rather than surface an id the picker
-        can't render).
+    :param client: Omnigent HTTP client.
+    :param session_id: Omnigent session/conversation id, e.g. ``"conv_abc123"``.
+    :param mode: Permission mode the pane now shows, e.g. ``"auto"``.
+    :raises httpx.HTTPError: If the Omnigent request fails or is rejected.
    """
-    if not model:
-        return None
-    lowered = model.lower()
-    if "sonnet-5" in lowered or "sonnet_5" in lowered:
-        return "sonnet_5"
-    for tier in ("fable", "opus", "sonnet", "haiku"):
-        if tier in lowered:
-            return tier
-    return None
+    resp = await client.post(
+        f"/v1/sessions/{session_id}/events",
+        json={"type": "external_permission_mode_change", "data": {"permission_mode": mode}},
+    )
+    resp.raise_for_status()
+
+
+async def _forward_permission_mode_from_pane(
+    client: httpx.AsyncClient,
+    *,
+    session_id: str,
+    bridge_dir: Path,
+    dedupe: _ForwardDedupeState,
+) -> None:
+    """
+    Mirror the pane's permission-mode footer to the session label each poll.
+
+    A shift+tab pressed inside the TUI produces no event Omnigent can see, so
+    without this the web picker shows a stale mode until the next UI-driven
+    switch. Polling the footer is the only signal available: Claude Code emits
+    nothing on a mode change, and hook payloads only arrive on tool use.
+
+    The launch mode is posted too, not just later switches: a session started
+    in manual mode carries no ``--permission-mode`` arg and no mode label, so
+    with nothing posted the web picker has no mode to render and hides itself.
+    Best-effort and idempotent — the server ignores a mode equal to the stored
+    label, an unchanged mode or unreadable pane is a no-op, and a failed POST
+    is retried next poll.
+
+    :param client: Omnigent HTTP client.
+    :param session_id: Omnigent session/conversation id.
+    :param bridge_dir: Native Claude bridge directory.
+    :param dedupe: Shared per-session dedupe state; mutated in place.
+    """
+    # Throttled: this spawns a tmux subprocess, unlike the file-backed model
+    # mirror that shares this poll loop.
+    now = time.monotonic()
+    if now < dedupe.permission_mode_next_read:
+        return
+    dedupe.permission_mode_next_read = now + _PERMISSION_MODE_POLL_INTERVAL_S
+    mode = await asyncio.to_thread(read_permission_mode, bridge_dir)
+    if mode is None or mode == dedupe.posted_permission_mode:
+        return
+    try:
+        await _post_external_permission_mode_change(
+            client,
+            session_id=session_id,
+            mode=mode,
+        )
+    except httpx.HTTPError:
+        _logger.debug(
+            "external_permission_mode_change post failed; session=%s mode=%s",
+            session_id,
+            mode,
+            exc_info=True,
+        )
+        return
+    dedupe.posted_permission_mode = mode


 async def _post_external_model_change(
@@ -4193,13 +4282,15 @@ async def _post_external_model_change(
    """
    Post one ``external_model_change`` event to the Sessions API.

-    Lets the web model picker reflect a model switch made inside the
-    Claude Code terminal (a ``/model`` command or the in-TUI picker).
+    Reports the model the pane is actually on — the launch's own model
+    included — so every surface renders the harness's truth.

    :param client: Omnigent HTTP client.
    :param session_id: Omnigent session/conversation id, e.g.
        ``"conv_abc123"``.
-    :param model: Tier alias the session is now on, e.g. ``"opus"``.
+    :param model: The harness's VERBATIM model, e.g.
+        ``"claude-opus-4-8[1m]"`` — never collapsed to a picker alias
+        (a family word claims a generation the pane may not be on).
    :raises httpx.HTTPError: If the Omnigent request fails or is rejected.
    """
    resp = await client.post(
@@ -4209,45 +4300,121 @@ async def _post_external_model_change(
    resp.raise_for_status()


+async def _post_external_session_title(
+    client: httpx.AsyncClient,
+    *,
+    session_id: str,
+    title: str,
+) -> None:
+    """
+    Post one ``external_session_title`` event to the Sessions API.
+
+    Mirrors a ``/rename`` typed in the Claude Code pane onto the Omnigent
+    session title so the web session list stops showing the stale
+    auto-generated one.
+
+    :param client: Omnigent HTTP client.
+    :param session_id: Omnigent session/conversation id, e.g.
+        ``"conv_abc123"``.
+    :param title: Operator-chosen title, e.g. ``"auth-refactor"``.
+    :raises httpx.HTTPError: If the Omnigent request fails or is rejected.
+    """
+    resp = await client.post(
+        f"/v1/sessions/{session_id}/events",
+        json={"type": "external_session_title", "data": {"title": title}},
+    )
+    resp.raise_for_status()
+
+
+async def _post_title_change_if_new(
+    client: httpx.AsyncClient,
+    *,
+    session_id: str,
+    dedupe: _ForwardDedupeState,
+    title: str | None,
+) -> None:
+    """
+    Mirror an observed ``/rename`` title to the session, deduped.
+
+    Unlike :func:`_post_model_change_if_new`, the FIRST observation is
+    posted rather than used to seed the baseline silently: a
+    ``custom-title`` record exists only because the operator ran
+    ``/rename``, so there is no passive spawn default to protect.
+
+    A steady-state poll reads only records past its byte cursor, so the
+    dedupe is not for the ordinary case — it covers the cursor rewind /
+    restart path that re-reads an already-posted record, and it is what
+    makes the retry below safe to attempt on every poll.
+
+    Best-effort: a failed POST leaves ``posted_title`` behind
+    ``observed_title`` so the next poll retries. ``observed_title`` is
+    sticky for exactly this reason — the retry must survive polls whose
+    own window carries no rename.
+
+    :param client: Omnigent HTTP client.
+    :param session_id: Omnigent session/conversation id.
+    :param dedupe: Shared per-session dedupe state; mutated in place.
+    :param title: Title just observed, or ``None`` when this poll's
+        window carried no ``custom-title`` record. ``observed_title`` is
+        sticky, so ``None`` does not clear it — a previously-observed but
+        unposted title is still retried here.
+    """
+    if title is not None:
+        dedupe.observed_title = title
+    if dedupe.observed_title is None or dedupe.observed_title == dedupe.posted_title:
+        return
+    try:
+        await _post_external_session_title(
+            client,
+            session_id=session_id,
+            title=dedupe.observed_title,
+        )
+        dedupe.posted_title = dedupe.observed_title
+    except httpx.HTTPError:
+        # Leave posted_title behind observed_title so the next poll retries.
+        _logger.warning(
+            "Failed to mirror /rename to Omnigent session=%s; the web session "
+            "list may show a stale title until the next poll",
+            session_id,
+            exc_info=True,
+        )
+
+
 async def _post_model_change_if_new(
    client: httpx.AsyncClient,
    *,
    session_id: str,
    dedupe: _ForwardDedupeState,
-    alias: str | None,
+    model: str | None,
 ) -> None:
    """
-    Mirror an observed model tier alias to ``model_override``, deduped.
+    Report the observed model to ``reported_model``, verbatim and deduped.

    Shared by the transcript-driven path (:func:`_forward_available_items`)
    and the statusLine-driven per-poll path
-    (:func:`_forward_model_from_status`). The FIRST observation is the
-    session's spawn default, not a switch, so it seeds the dedupe baseline
-    WITHOUT posting (posting it could clobber a pending silent model
-    handoff). Every later change posts ``external_model_change``. Both
-    callers pass the same ``dedupe`` so whichever observes a switch first
-    posts it and the other no-ops. Best-effort: a failed POST leaves
-    ``posted_model`` behind ``observed_model`` so the next poll retries.
+    (:func:`_forward_model_from_status`). EVERY observation posts — the
+    first one is the launch report that seeds the session's
+    ``reported_model``, so surfaces show the pane's truth within seconds
+    of spawn; the server dedupes by equality, so a steady model costs one
+    POST total. Both callers pass the same ``dedupe`` so whichever
+    observes a change first posts it and the other no-ops. Best-effort: a
+    failed POST leaves ``posted_model`` behind ``observed_model`` so the
+    next poll retries.

    :param client: Omnigent HTTP client.
    :param session_id: Omnigent session/conversation id.
    :param dedupe: Shared per-session dedupe state; mutated in place.
-    :param alias: Tier alias just observed (``"opus"`` / ``"sonnet"`` /
-        …), or ``None`` when this source carried no recognizable model on
-        this poll. ``observed_model`` is sticky across polls, so passing
-        ``None`` does NOT clear it — it just means "no fresh observation,"
-        and a previously-observed-but-unposted model is still reconciled
-        (retried) here.
+    :param model: The harness's verbatim model just observed (e.g.
+        ``"claude-opus-4-8[1m]"``), or ``None`` when this source carried
+        no model on this poll. ``observed_model`` is sticky across
+        polls, so passing ``None`` does NOT clear it — it just means "no
+        fresh observation," and a previously-observed-but-unposted model
+        is still reconciled (retried) here.
    """
-    if alias is not None:
-        dedupe.observed_model = alias
+    if model is not None:
+        dedupe.observed_model = model
    if dedupe.observed_model is None or dedupe.observed_model == dedupe.posted_model:
        return
-    if dedupe.posted_model is None:
-        # First observation = the spawn default; seed the baseline without
-        # posting so it can't clobber a pending silent model handoff.
-        dedupe.posted_model = dedupe.observed_model
-        return
    try:
        await _post_external_model_change(
            client,
@@ -4273,7 +4440,7 @@ async def _forward_model_from_status(
    dedupe: _ForwardDedupeState,
 ) -> None:
    """
-    Mirror the statusLine-reported active model to ``model_override`` each poll.
+    Report the statusLine's active model to ``reported_model`` each poll.

    Claude Code rewrites the statusLine stdin on every TUI render — including
    right after an in-pane ``/model`` switch, BEFORE the next turn runs. The
@@ -4285,8 +4452,9 @@ async def _forward_model_from_status(
    turn later, which is what happened when the model was derived solely
    from the next turn's transcript ``message.model``.

-    Best-effort and idempotent: shares ``dedupe`` with the transcript path,
-    so a no-op when the model is unchanged.
+    The value posts VERBATIM — the harness's own spelling, never collapsed
+    to a picker alias. Best-effort and idempotent: shares ``dedupe`` with
+    the transcript path, so a no-op when the model is unchanged.

    :param client: Omnigent HTTP client.
    :param session_id: Omnigent session/conversation id.
@@ -4297,12 +4465,11 @@ async def _forward_model_from_status(
    if status_state is None:
        return
    model = status_state.get("model")
-    alias = _model_alias_for(model if isinstance(model, str) else None)
    await _post_model_change_if_new(
        client,
        session_id=session_id,
        dedupe=dedupe,
-        alias=alias,
+        model=model.strip() if isinstance(model, str) and model.strip() else None,
    )


@@ -11,8 +11,7 @@ import sys
 import time
 from collections.abc import Callable
 from pathlib import Path
-
-import httpx
+from typing import TYPE_CHECKING

 from omnigent.claude_native_bridge import (
    BRIDGE_ID_LABEL_KEY,
@@ -28,17 +27,13 @@ from omnigent.claude_native_bridge import (
    url_component,
    write_active_session_id,
 )
-from omnigent.entities.session_resources import terminal_resource_id
-from omnigent.native_policy_hook import (
-    _is_login_redirect_or_unauthorized,
-    evaluation_response_to_hook_output,
-    fail_closed_hook_output,
-    hook_payload_to_evaluation_request,
-    policy_hook_reauth,
-    post_evaluate_with_retry,
-    read_relay_policy_config,
-    relay_policy_evaluate_url,
-)
+
+# The observer path (the default, most frequent invocation — Claude blocks
+# on it per Stop/UserPromptSubmit/TaskCreated/...) must not pay the
+# httpx/policy import cost; those are imported inside the subcommands and
+# helpers that actually speak HTTP.
+if TYPE_CHECKING:
+    import httpx

 # Client-side budget for the permission-request long-poll to AP. Held
 # at one day so the hook subprocess waits ~indefinitely for a verdict
@@ -128,17 +123,23 @@ def _env_float(name: str, default: float) -> float:
 # down server can no longer re-POST for a day. Overridable for operators who
 # want more slack against a flaky upstream.
 _PERMISSION_MAX_CONSECUTIVE_FAILURES = max(1, _env_int("OMNIGENT_HOOK_MAX_RETRIES", 8))
-# httpx errors that mean the request never reached a live server (no response
-# was ever begun). These are unambiguous hard failures — the server is down /
-# unreachable, not holding a poll. Everything else under ``httpx.HTTPError``
-# that is not a 4xx/5xx status (RemoteProtocolError, ReadError, ReadTimeout, …)
-# means the connection was established and then severed mid-poll.
-_NEVER_CONNECTED_ERRORS = (
-    httpx.ConnectError,
-    httpx.ConnectTimeout,
-    httpx.PoolTimeout,
-    httpx.ProxyError,
-)
+
+
+def _never_connected_errors() -> tuple[type[Exception], ...]:
+    """httpx errors meaning the request never reached a live server.
+
+    No response was ever begun — unambiguous hard failures (the server is
+    down / unreachable), not a held poll. Everything else under
+    ``httpx.HTTPError`` that is not a 4xx/5xx status (RemoteProtocolError,
+    ReadError, ReadTimeout, …) means the connection was established and
+    then severed mid-poll. A function, not a module constant, so the
+    hook's hot observer path never imports httpx.
+    """
+    import httpx
+
+    return (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout, httpx.ProxyError)
+
+
 # An established connection that drops in under this many seconds is treated as
 # a flapping/crash-looping server (a hard failure), NOT a genuinely-parked poll
 # a proxy severed. Comfortably below any real idle-proxy timeout (typically
@@ -365,6 +366,18 @@ def _rotate_session_on_clear(bridge_dir: Path) -> str | None:
        if isinstance(raw_headers, dict)
        else {}
    )
+    import httpx
+
+    # Route the whole rotation sequence (GET old, POST /v1/sessions or /fork,
+    # PATCH new, DELETE old) to the replica holding this host's tunnel: a managed
+    # create/fork notifies the host inline over its pod-local tunnel, so an
+    # off-replica request can't reach it. This hook client carries no
+    # _RunnerDatabricksAuth, so key the reused headers dict from the runner-env
+    # host_id (databricks_request_headers reads OMNIGENT_RUNNER_SLICE_KEY when no
+    # explicit host_id; emitted only on the workspace mount).
+    from omnigent.cli_auth import databricks_request_headers
+
+    headers.update(databricks_request_headers(ap_server_url))
    try:
        with httpx.Client(
            headers=headers, timeout=httpx.Timeout(_SESSION_ROTATION_TIMEOUT_S)
@@ -411,6 +424,18 @@ def _rotate_session_on_fork(bridge_dir: Path) -> str | None:
        if isinstance(raw_headers, dict)
        else {}
    )
+    import httpx
+
+    # Route the whole rotation sequence (GET old, POST /v1/sessions or /fork,
+    # PATCH new, DELETE old) to the replica holding this host's tunnel: a managed
+    # create/fork notifies the host inline over its pod-local tunnel, so an
+    # off-replica request can't reach it. This hook client carries no
+    # _RunnerDatabricksAuth, so key the reused headers dict from the runner-env
+    # host_id (databricks_request_headers reads OMNIGENT_RUNNER_SLICE_KEY when no
+    # explicit host_id; emitted only on the workspace mount).
+    from omnigent.cli_auth import databricks_request_headers
+
+    headers.update(databricks_request_headers(ap_server_url))
    try:
        with httpx.Client(
            headers=headers, timeout=httpx.Timeout(_SESSION_ROTATION_TIMEOUT_S)
@@ -489,6 +514,8 @@ def _create_clear_replacement_session(
        )
        bind_resp.raise_for_status()

+    from omnigent.entities.session_resources import terminal_resource_id
+
    terminal_id = terminal_resource_id("claude", "main")
    transfer_resp = client.post(
        (
@@ -569,6 +596,8 @@ def _create_fork_replacement_session(
        )
        bind_resp.raise_for_status()

+    from omnigent.entities.session_resources import terminal_resource_id
+
    terminal_id = terminal_resource_id("claude", "main")
    transfer_resp = client.post(
        (
@@ -648,7 +677,7 @@ def _post_hook_with_reattach(
    Failure classification:

    * **Hard failure → count toward the cap.** A 5xx, or a connection that
-      never established (:data:`_NEVER_CONNECTED_ERRORS`), or an established
+      never established (:func:`_never_connected_errors`), or an established
      connection that dropped in under :data:`_PERMISSION_HELD_POLL_FLOOR_S`
      (a flapping/crash-looping server). This is the spin.
    * **Held-poll sever → reset the counter.** An established connection that
@@ -701,6 +730,10 @@ def _post_hook_with_reattach(
        "_omnigent_elicitation_id": f"elicit_claude_{secrets.token_hex(16)}",
    }
    backoff_s = _PERMISSION_RETRY_INITIAL_BACKOFF_S
+    import httpx
+
+    from omnigent.native_policy_hook import _is_login_redirect_or_unauthorized
+
    timeout = httpx.Timeout(_PERMISSION_TIMEOUT_S, connect=_PERMISSION_CONNECT_TIMEOUT_S)
    # Absolute backstop: even a run of held-poll severs (which don't count
    # toward the hard-failure cap) can't loop past the day-long human-answer
@@ -751,7 +784,7 @@ def _post_hook_with_reattach(
            # Classify by HOW it failed, not by elapsed time (a proxy severs a
            # legitimately-held poll in seconds-to-minutes, so wall-clock can't
            # tell it from a down server — #1782 Polly review).
-            never_connected = isinstance(exc, _NEVER_CONNECTED_ERRORS)
+            never_connected = isinstance(exc, _never_connected_errors())
            held_s = time.monotonic() - attempt_started
            # Hard failure iff the server was never reached, OR an established
            # connection dropped so fast it's a flap rather than a parked poll.
@@ -801,6 +834,8 @@ def _main_permission_request(argv: list[str]) -> int:
    :returns: Process exit code. Returns ``0`` on transport failures so
        Claude Code falls back to its terminal prompt.
    """
+    from omnigent.native_policy_hook import policy_hook_reauth
+
    args = _parse_permission_args(argv)
    raw = sys.stdin.read()
    try:
@@ -826,6 +861,13 @@ def _main_permission_request(argv: list[str]) -> int:
        raw_headers = config.get("ap_auth_headers")
        if isinstance(raw_headers, dict):
            headers = {str(key): str(value) for key, value in raw_headers.items()}
+    # A permission request raises a web elicitation that parks in the pod-local
+    # registry on the replica holding this session's runner tunnel; an unkeyed
+    # POST lands elsewhere and the approval is silently lost. Key from the
+    # runner-env host_id (reads OMNIGENT_RUNNER_SLICE_KEY; workspace mount only).
+    from omnigent.cli_auth import databricks_request_headers
+
+    headers.update(databricks_request_headers(ap_server_url))
    url = (
        f"{ap_server_url.rstrip('/')}/v1/sessions/"
        f"{url_component(session_id)}/hooks/permission-request"
@@ -867,6 +909,8 @@ def _main_ask_user_question(argv: list[str]) -> int:
    :returns: Process exit code. Returns ``0`` on any failure so Claude Code
        falls back to its terminal TUI prompt rather than blocking.
    """
+    from omnigent.native_policy_hook import policy_hook_reauth
+
    args = _parse_permission_args(argv)
    raw = sys.stdin.read()
    try:
@@ -898,6 +942,12 @@ def _main_ask_user_question(argv: list[str]) -> int:
        raw_headers = config.get("ap_auth_headers")
        if isinstance(raw_headers, dict):
            headers = {str(key): str(value) for key, value in raw_headers.items()}
+    # Same as the permission-request hook: the elicitation parks in the pod-local
+    # registry on the session's tunnel replica, so key the POST from the
+    # runner-env host_id or an off-replica landing silently drops the prompt.
+    from omnigent.cli_auth import databricks_request_headers
+
+    headers.update(databricks_request_headers(ap_server_url))
    url = (
        f"{ap_server_url.rstrip('/')}/v1/sessions/"
        f"{url_component(session_id)}/hooks/permission-request"
@@ -995,6 +1045,16 @@ def _main_evaluate_policy(argv: list[str]) -> int:
    :returns: Process exit code. Always ``0`` — blocking verdicts
        are expressed via the JSON output, not exit codes.
    """
+    from omnigent.native_policy_hook import (
+        evaluation_response_to_hook_output,
+        fail_closed_hook_output,
+        hook_payload_to_evaluation_request,
+        policy_hook_reauth,
+        post_evaluate_with_retry,
+        read_relay_policy_config,
+        relay_policy_evaluate_url,
+    )
+
    args = _parse_evaluate_policy_args(argv)
    raw = sys.stdin.read()
    try:
@@ -1048,6 +1108,12 @@ def _main_evaluate_policy(argv: list[str]) -> int:
        raw_headers = config.get("ap_auth_headers")
        if isinstance(raw_headers, dict):
            headers = {str(k): str(v) for k, v in raw_headers.items()}
+        # This posts to the session's policy registry on the replica holding its
+        # tunnel; key from the runner-env host_id so it isn't misrouted. (The
+        # relay branch above targets a relay token URL, so it needs no key.)
+        from omnigent.cli_auth import databricks_request_headers
+
+        headers.update(databricks_request_headers(ap_server_url))
        session_component = url_component(session_id)
        url = f"{ap_server_url.rstrip('/')}/v1/sessions/{session_component}/policies/evaluate"
        reauth = policy_hook_reauth(ap_server_url, headers)
@@ -47,6 +47,8 @@ import os
 from dataclasses import dataclass
 from pathlib import Path

+from omnigent.process_logging import data_dir
+
 # Env-var override for the persistent state root. Reserved for tests
 # (and for advanced users who want to put state on a non-default
 # volume). When unset, the module falls back to
@@ -91,8 +93,8 @@ def _claude_native_state_root() -> Path:

    Honors the :data:`_STATE_ROOT_ENV_VAR` override so tests can
    point the state tree at a per-test ``tmp_path`` without
-    clobbering the user's real home directory. Production callers
-    leave the env unset and get the default
+    clobbering the user's state. Otherwise the root follows
+    ``OMNIGENT_DATA_DIR``, falling back to
    ``~/.omnigent/claude-native``.

    Lazy: created on first write, never on read (the resume / picker
@@ -105,7 +107,7 @@ def _claude_native_state_root() -> Path:
    override = os.environ.get(_STATE_ROOT_ENV_VAR)
    if override:
        return Path(override)
-    return Path.home() / ".omnigent" / "claude-native"
+    return data_dir() / "claude-native"


 def _state_dir_for_conversation_id(conversation_id: str) -> Path:
@@ -20,6 +20,93 @@ import tempfile
 from pathlib import Path

 _CONTEXT_FILE = "context.json"
+# Raw statusLine stdin captured by the shell shim the settings now install
+# (no Python spawn on Claude's blocking statusLine path). The forwarder
+# normalizes it into ``context.json`` via :func:`sync_raw_status_context`.
+CONTEXT_RAW_FILE = "context_raw.json"
+
+
+def normalize_status_payload(payload: dict[str, object]) -> dict[str, object] | None:
+    """
+    Extract the ``context.json`` record from a raw statusLine payload.
+
+    :param payload: Decoded statusLine stdin JSON from Claude Code.
+    :returns: The record to persist, or ``None`` when the payload carries
+        no usable ``context_window`` (nothing worth recording).
+    """
+    context = payload.get("context_window")
+    if not isinstance(context, dict):
+        return None
+    size = context.get("context_window_size")
+    usage = context.get("current_usage")
+    if not isinstance(size, int) or size <= 0:
+        return None
+    record: dict[str, object] = {"context_window_size": size}
+    if isinstance(usage, dict):
+        record["current_usage"] = usage
+    used_pct = context.get("used_percentage")
+    if isinstance(used_pct, (int, float)):
+        record["used_percentage"] = used_pct
+    # Claude Code's statusLine stdin carries a top-level ``cost`` block with
+    # its own cumulative session billing; the forwarder reports it because
+    # claude-native produces no ``response.completed`` cost events.
+    cost = payload.get("cost")
+    if isinstance(cost, dict):
+        total_cost = cost.get("total_cost_usd")
+        if (
+            isinstance(total_cost, (int, float))
+            and not isinstance(total_cost, bool)
+            and total_cost >= 0
+        ):
+            record["total_cost_usd"] = float(total_cost)
+    # The active model, rewritten on every render — including right after an
+    # in-pane ``/model`` switch — so gates see the switch before the next turn.
+    model = payload.get("model")
+    model_id: str | None = None
+    if isinstance(model, dict):
+        raw_model = model.get("id") or model.get("display_name")
+        if isinstance(raw_model, str) and raw_model.strip():
+            model_id = raw_model.strip()
+    elif isinstance(model, str) and model.strip():
+        model_id = model.strip()
+    if model_id is not None:
+        record["model"] = model_id
+    return record
+
+
+def sync_raw_status_context(
+    bridge_dir: Path,
+    last_sig: tuple[int, int] | None,
+) -> tuple[int, int] | None:
+    """
+    Normalize the shim's raw statusLine capture into ``context.json``.
+
+    Called from the forwarder's poll loop. Cheap when nothing changed —
+    one ``stat`` against the remembered ``(mtime_ns, size)`` signature.
+
+    :param bridge_dir: Bridge directory shared with the statusLine shim.
+    :param last_sig: Signature returned by the previous call, or ``None``.
+    :returns: The new signature to carry forward (unchanged on a miss or
+        an unparseable file, so the next poll retries).
+    """
+    raw_path = bridge_dir / CONTEXT_RAW_FILE
+    try:
+        stat = raw_path.stat()
+    except OSError:
+        return last_sig
+    sig = (stat.st_mtime_ns, stat.st_size)
+    if sig == last_sig:
+        return last_sig
+    try:
+        payload = json.loads(raw_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return last_sig
+    if not isinstance(payload, dict):
+        return sig
+    record = normalize_status_payload(payload)
+    if record is not None:
+        _write_record_atomic(bridge_dir, record)
+    return sig


 def main(argv: list[str] | None = None) -> int:
@@ -67,71 +154,43 @@ def _write_context_atomic(bridge_dir: Path, payload: dict[str, object]) -> None:
    Persist the statusLine payload's context fields to ``context.json``.

    Atomic write so the forwarder never observes a half-written file.
-    Soft-fails (writes nothing) when ``context_window`` is missing or
-    malformed — there's nothing useful to record.
+    Soft-fails (writes nothing) when the payload carries no usable
+    ``context_window``. Retained for older bridge dirs whose settings
+    still invoke this module; new settings install a shell shim and the
+    forwarder normalizes via :func:`sync_raw_status_context`.

    :param bridge_dir: Bridge directory shared with the forwarder.
    :param payload: Decoded statusLine stdin JSON.
    """
-    context = payload.get("context_window")
-    if not isinstance(context, dict):
+    record = normalize_status_payload(payload)
+    if record is None:
        return
-    size = context.get("context_window_size")
-    usage = context.get("current_usage")
-    if not isinstance(size, int) or size <= 0:
-        return
-    record: dict[str, object] = {"context_window_size": size}
-    if isinstance(usage, dict):
-        record["current_usage"] = usage
-    used_pct = context.get("used_percentage")
-    if isinstance(used_pct, (int, float)):
-        record["used_percentage"] = used_pct
-    # Claude Code's statusLine stdin carries a top-level ``cost`` block with
-    # its own cumulative session billing. Capture ``total_cost_usd`` so the
-    # forwarder can report it (claude-native produces no ``response.completed``
-    # event, so the Omnigent relay's cost accumulation never runs for it).
-    cost = payload.get("cost")
-    if isinstance(cost, dict):
-        total_cost = cost.get("total_cost_usd")
-        if (
-            isinstance(total_cost, (int, float))
-            and not isinstance(total_cost, bool)
-            and total_cost >= 0
-        ):
-            record["total_cost_usd"] = float(total_cost)
-    # Claude Code's statusLine stdin carries the active model as a ``model``
-    # block (``{"id": "claude-opus-4-8", "display_name": "Opus"}``), rewritten
-    # on every render — including right after an in-pane ``/model`` switch.
-    # Capture the concrete id so the forwarder can mirror the switch to
-    # ``model_override`` on the next poll, before the user's next message,
-    # rather than waiting for the next turn's transcript to reveal the model
-    # (which lagged model-gated policies by one turn). Defensive about the
-    # shape: accept a ``{id|display_name}`` dict or a bare string.
-    model = payload.get("model")
-    model_id: str | None = None
-    if isinstance(model, dict):
-        raw_model = model.get("id") or model.get("display_name")
-        if isinstance(raw_model, str) and raw_model.strip():
-            model_id = raw_model.strip()
-    elif isinstance(model, str) and model.strip():
-        model_id = model.strip()
-    if model_id is not None:
-        record["model"] = model_id
    try:
-        bridge_dir.mkdir(parents=True, exist_ok=True)
-        fd, tmp_path = tempfile.mkstemp(prefix=".context-", dir=str(bridge_dir))
-        try:
-            with os.fdopen(fd, "w", encoding="utf-8") as handle:
-                json.dump(record, handle, separators=(",", ":"))
-            os.replace(tmp_path, str(bridge_dir / _CONTEXT_FILE))
-        except OSError:
-            with contextlib.suppress(OSError):
-                os.unlink(tmp_path)
-            raise
+        _write_record_atomic(bridge_dir, record)
    except OSError as exc:
        print(f"omnigent claude status: write failed: {exc}", file=sys.stderr)


+def _write_record_atomic(bridge_dir: Path, record: dict[str, object]) -> None:
+    """
+    Atomically write one normalized record to ``context.json``.
+
+    :param bridge_dir: Bridge directory shared with the forwarder.
+    :param record: Normalized record from :func:`normalize_status_payload`.
+    :raises OSError: When the temp-file write or replace fails.
+    """
+    bridge_dir.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(prefix=".context-", dir=str(bridge_dir))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(record, handle, separators=(",", ":"))
+        os.replace(tmp_path, str(bridge_dir / _CONTEXT_FILE))
+    except OSError:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp_path)
+        raise
+
+
 def _chain(command: str, stdin_payload: str) -> None:
    """
    Exec the user's pre-existing statusLine command, piping our stdin.
@@ -70,7 +70,7 @@ from omnigent.inner import _proc, ui
 from omnigent.integration_daemon import IntegrationDaemon
 from omnigent.json_types import JsonObject as _JsonObject
 from omnigent.onboarding.sandboxes import available_providers as _sandbox_providers
-from omnigent.process_logging import LOG_LEVEL_ENV_VAR, LOG_TO_STDERR_ENV_VAR
+from omnigent.process_logging import LOG_LEVEL_ENV_VAR, LOG_TO_STDERR_ENV_VAR, data_dir, env_truthy

 if TYPE_CHECKING:
    import socket
@@ -1781,6 +1781,98 @@ def _set_log_to_stderr(
    return value


+def _finish_cli_profile(profiler: Any, output_path: Path) -> None:  # type: ignore[explicit-any]
+    """Stop a requested cProfile run and render a focused bottleneck summary."""
+    import pstats
+
+    profiler.disable()
+    profiler.dump_stats(output_path)
+    stats = pstats.Stats(profiler)
+    stats_state = vars(stats)
+    raw_stats = cast(
+        dict[tuple[str, int, str], tuple[int, int, float, float, object]],
+        stats_state["stats"],
+    )
+    total_time = float(stats_state["total_tt"])
+    total_calls = int(stats_state["total_calls"])
+    primitive_calls = int(stats_state["prim_calls"])
+    package_root = Path(__file__).resolve().parent
+    source_root = package_root.parent
+
+    # (filename, line, function, primitive calls, total calls, self, cumulative)
+    rows = [(*key, cc, nc, tt, ct) for key, (cc, nc, tt, ct, _) in raw_stats.items()]
+
+    def _location(filename: str, line: int, function: str) -> str:
+        path = Path(filename).resolve()
+        try:
+            display = str(path.relative_to(source_root))
+        except ValueError:
+            display = path.name
+        return f"{display}:{line}({function})"
+
+    def _duration(seconds: float) -> str:
+        if seconds < 0.01:
+            return f"{seconds * 1_000:.2f} ms"
+        if seconds < 1:
+            return f"{seconds * 1_000:.1f} ms"
+        return f"{seconds:.3f} s"
+
+    def _print_rows(
+        title: str,
+        selected: list[tuple[str, int, str, int, int, float, float]],
+    ) -> None:
+        click.echo(f"\n{title}", err=True)
+        click.echo(f"  {'self':>9}  {'cumulative':>10}  {'calls':>9}  function", err=True)
+        for filename, line, function, primitive, calls, self_time, cumulative in selected[:10]:
+            call_count = str(calls) if calls == primitive else f"{calls}/{primitive}"
+            click.echo(
+                f"  {_duration(self_time):>9}  {_duration(cumulative):>10}  "
+                f"{call_count:>9}  {_location(filename, line, function)}",
+                err=True,
+            )
+
+    omnigent_rows = [
+        row for row in rows if Path(row[0]).resolve().is_relative_to(package_root) and row[6] > 0
+    ]
+    omnigent_rows.sort(key=lambda row: row[6], reverse=True)
+    self_time_rows = [row for row in omnigent_rows if row[5] > 0]
+    self_time_rows.sort(key=lambda row: row[5], reverse=True)
+
+    click.echo(
+        f"\nCLI profile: {_duration(total_time)}, "
+        f"{total_calls:,} calls ({primitive_calls:,} primitive)",
+        err=True,
+    )
+    _print_rows("Top Omnigent call paths", omnigent_rows)
+    _print_rows("Top Omnigent functions by self time", self_time_rows)
+    click.echo(f"\nFull profile data: {output_path}", err=True)
+
+
+def _start_cli_profile(
+    ctx: click.Context,
+    _param: click.Parameter,
+    value: bool,
+) -> bool:
+    """Start cProfile early and finish it after the selected command exits."""
+    if not value:
+        return value
+
+    import cProfile
+
+    timestamp = time.strftime("%Y%m%d-%H%M%S")
+    microseconds = time.time_ns() // 1_000 % 1_000_000
+    profile_dir = data_dir() / "profiles"
+    profile_dir.mkdir(parents=True, exist_ok=True)
+    output_path = profile_dir / (f"omnigent-cli-{timestamp}-{microseconds:06d}-{os.getpid()}.prof")
+    profiler = cProfile.Profile()
+    profiler.enable()
+    ctx.call_on_close(lambda: _finish_cli_profile(profiler, output_path))
+    # Click closes callbacks last-in-first-out, so measurement stops before
+    # rendering the summary above.
+    ctx.call_on_close(profiler.disable)
+    return value
+
+
 def _extract_global_logging_flags(argv: list[str]) -> tuple[list[str], bool, bool]:
    """Remove global logging flags before run-shorthand rewriting."""
    debug_logging = False
@@ -1801,6 +1893,17 @@ def _extract_global_logging_flags(argv: list[str]) -> tuple[list[str], bool, boo


@click.group(cls=_OmnigentCLI)
+@click.option(
+    "--profiling",
+    is_flag=True,
+    is_eager=True,
+    expose_value=False,
+    callback=_start_cli_profile,
+    help=(
+        "Profile CLI execution, print a summary, and write a timestamped .prof file. "
+        "Place before COMMAND."
+    ),
+)
@click.option(
    "--debug",
    "debug_logging",
@@ -1930,6 +2033,44 @@ def _warn_deprecated_harness_path_env_vars() -> None:
        )


+REQUIRE_WRAPPER_ENV = "OMNIGENT_REQUIRE_WRAPPER"
+WRAPPER_COMMAND_ENV = "OMNIGENT_WRAPPER_COMMAND"
+WRAPPER_BYPASS_ENV = "OMNIGENT_WRAPPER_BYPASS"
+
+
+def _wrapper_guard_error(env: Mapping[str, str], prog: str) -> str | None:
+    """Return the block message when a naked ``omni`` call is refused, else ``None``.
+
+    A deployment that wraps the CLI (e.g. ``isaac omni``) sets
+    ``OMNIGENT_REQUIRE_WRAPPER`` so direct calls are refused; the wrapper sets
+    ``OMNIGENT_WRAPPER_BYPASS`` around its own invocation to pass through, and
+    ``OMNIGENT_WRAPPER_COMMAND`` names the command to suggest instead.
+    """
+    if not env_truthy(env.get(REQUIRE_WRAPPER_ENV)):
+        return None
+    if env_truthy(env.get(WRAPPER_BYPASS_ENV)):
+        return None
+    redirect = (env.get(WRAPPER_COMMAND_ENV) or "").strip()
+    if redirect:
+        detail = f"Use `{redirect}` instead, or set {WRAPPER_BYPASS_ENV}=1 to run it directly."
+    else:
+        detail = f"Set {WRAPPER_BYPASS_ENV}=1 to run it directly."
+    return f"Error: running `{prog}` directly is disabled in this environment.\n{detail}"
+
+
+def _enforce_wrapper_guard() -> None:
+    """Exit early when a naked ``omni``/``omnigent`` call is blocked by an operator."""
+    # argv[0] is the console-script name (``omni``/``omnigent``); ``python -m
+    # omnigent`` reports ``__main__.py``, so fall back to the canonical name.
+    prog = os.path.basename(sys.argv[0])
+    if not prog or prog == "__main__.py":
+        prog = "omnigent"
+    message = _wrapper_guard_error(os.environ, prog)
+    if message is not None:
+        click.echo(message, err=True)
+        raise SystemExit(2)
+
+
 def main() -> None:
    """
    Console-script entry point for ``omnigent``.
@@ -1961,6 +2102,11 @@ def main() -> None:

    install_crash_handler(app_name="omnigent", repo="omnigent-ai/omnigent")

+    # Operators can force all use through a wrapper (e.g. `isaac omni`) by
+    # setting OMNIGENT_REQUIRE_WRAPPER; the wrapper sets OMNIGENT_WRAPPER_BYPASS
+    # to pass through. Refuse naked calls before any work happens.
+    _enforce_wrapper_guard()
+
    cwd = os.getcwd()
    if cwd not in sys.path:
        sys.path.insert(0, cwd)
@@ -1988,7 +2134,17 @@ def main() -> None:
    # intentionally tiny (currently only help/version); runner flags live on
    # ``run``. Treat a leading non-top-level flag as bare-run shorthand so
    # users can type the natural no-AGENT launcher form.
-    if argv and argv[0].startswith("-") and argv[0] not in {"--help", "-h", "--version"}:
+    if (
+        argv
+        and argv[0].startswith("-")
+        and argv[0]
+        not in {
+            "--help",
+            "-h",
+            "--version",
+            "--profiling",
+        }
+    ):
        argv = ["run", *argv]

    # Shorthand: ``omnigent myagent.yaml [opts]`` → ``run myagent.yaml [opts]``.
@@ -2158,6 +2314,10 @@ def _is_removed_ad_hoc_invocation(argv: list[str]) -> bool:
    # help listing subcommands, not the legacy argparse help.
    if argv[0] in {"--help", "-h", "--version"}:
        return False
+    # A root profiling flag may precede an eager help/version flag or stand
+    # alone. These are valid Click invocations, not removed ad-hoc chat.
+    if all(token in {"--profiling", "--help", "-h", "--version"} for token in argv):
+        return False
    # Skip leading flags to find the first positional. If all
    # tokens are flags (e.g. ``omnigent --system-prompt "..."``),
    # treat it as removed ad-hoc chat rather than handing it to click
@@ -2185,7 +2345,7 @@ def _runner_loopback_host(host: str) -> str:
    return "127.0.0.1" if host in {"0.0.0.0", "::", ""} else host


-_HOST_PID_PATH = Path.home() / ".omnigent" / "host.pid"
+_HOST_PID_PATH = data_dir() / "host.pid"


 # host.pid records the daemon PID + the "target" it serves: a normalized
@@ -2394,6 +2554,7 @@ def _daemon_host_online(record: _HostDaemonRecord, *, timeout_s: float = 2.0) ->
        method="GET",
        path=f"/v1/hosts/{url_component(host_id)}",
        timeout_s=timeout_s,
+        host_id=host_id,
    )
    if result.status_code != 200 or not isinstance(result.body, dict):
        return False
@@ -2819,6 +2980,7 @@ def _spawn_host_daemon_process(
            proc = subprocess.Popen(
                args,
                env=env,
+                stdin=subprocess.DEVNULL,
                stdout=log_fh,
                stderr=log_fh,
                **_proc.spawn_kwargs(),
@@ -2887,7 +3049,7 @@ def _foreground_daemon_record(
        started_at=int(time.time()),
        host_id=host_id,
        resolved_server_url=server_url.rstrip("/") if mode == "local" else None,
-        config_sig=server_config_signature(),
+        config_sig=server_config_signature(include_features=mode == "local"),
    )


@@ -2927,11 +3089,13 @@ def _claim_foreground_daemon_record(
    """
    conflict = _live_daemon_conflict(record)
    if conflict is not None:
+        # server_url is None in local mode; "" makes the hint say --server "".
+        stop_command = _host_stop_command(conflict.server_url or "")
        raise click.ClickException(
            "A host daemon is already running for this server "
            f"(pid={conflict.pid}, target={conflict.target}). "
-            "Run `omnigent host status` to inspect it or "
-            "`omnigent host stop --server ...` to stop it first."
+            f"Run `omnigent host status` to inspect it or `{stop_command}` "
+            "to stop it first."
        )
    previous = _find_daemon_record(record.target)
    if previous is not None and not _pid_alive(previous.pid):
@@ -3007,14 +3171,15 @@ def _ensure_host_daemon(server_url: str | None) -> bool:
    mode_args = ["--local"] if not server_url else ["--server", server_url]
    args = [sys.executable, "-m", "omnigent.host._daemon_entry", *mode_args]
    spawned = _spawn_host_daemon_process(
-        args=args, env=_build_host_daemon_env(server_url=server_url)
+        args=args,
+        env=_build_host_daemon_env(server_url=server_url),
    )
    if spawned is None:
        return False
    _persist_spawned_daemon(
        target=target,
        spawned=spawned,
-        config_sig=server_config_signature(),
+        config_sig=server_config_signature(include_features=not server_url),
    )
    return decision.config_changed

@@ -3114,9 +3279,10 @@ def _ensure_databricks_server_auth(server: str, *, non_interactive: bool = False
    today. A non-200 answer that carries the Databricks edge signature
    (302 to the workspace OAuth page, or a DatabricksRealm 401) means
    the run would otherwise die much later with an opaque "non-JSON
-    response (status=302)" traceback from the session-create call. On a
-    TTY we run the same flow ``omnigent login`` would and continue;
-    headless invocations get the exact command to run instead.
+    response (status=302)" traceback from the session-create call. First,
+    it asks the SDK for a fresh workspace token; only then does a TTY run
+    the same flow ``omnigent login`` would, while headless invocations get
+    the exact command to run instead.

    Non-Databricks postures are deliberately left alone: local accounts
    servers auto-authenticate downstream (magic-link redeem), and
@@ -3136,11 +3302,12 @@ def _ensure_databricks_server_auth(server: str, *, non_interactive: bool = False
    import httpx as _httpx

    from omnigent.chat import _remote_headers
+    from omnigent.cli_auth import load_databricks_org_id, store_databricks_auth

    try:
        probe = _httpx.get(
            f"{server}/v1/me",
-            headers=_remote_headers(server_url=server),
+            headers=_remote_headers(server_url=server, host_id=None),
            timeout=10.0,
        )
    except _httpx.HTTPError:
@@ -3152,6 +3319,13 @@ def _ensure_databricks_server_auth(server: str, *, non_interactive: bool = False
    workspace_host = _databricks_workspace_login_target(server, probe)
    if workspace_host is None:
        return
+    org_id = load_databricks_org_id(server)
+    token = _databricks_workspace_token(workspace_host)
+    if token is not None:
+        refreshed_probe = _verify_databricks_server_token(server, token, org_id)
+        if refreshed_probe.status_code == 200:
+            store_databricks_auth(server, workspace_host, org_id=org_id)
+            return
    login_cmd = f"omnigent login {server}"
    if non_interactive or not sys.stdin.isatty():
        raise click.ClickException(
@@ -3159,11 +3333,7 @@ def _ensure_databricks_server_auth(server: str, *, non_interactive: bool = False
            f"HTTP {probe.status_code}). Run `{login_cmd}` and retry."
        )
    click.echo(f"Not signed in to {server} — running `{login_cmd}` first.")
-    # Recover the ``?o=`` selector from a prior login record so a re-login
-    # still targets the right workspace.
-    from omnigent.cli_auth import load_databricks_org_id
-
-    _databricks_login(server, workspace_host, org_id=load_databricks_org_id(server))
+    _databricks_login(server, workspace_host, org_id=org_id)


 def _ensure_backend(server: str | None) -> str:
@@ -3199,10 +3369,24 @@ def _ensure_backend(server: str | None) -> str:
        # otherwise the session-create call deep in the REPL bring-up
        # surfaces the edge redirect as an opaque non-JSON-response
        # traceback.
+        #
+        # The auth probe (GET /v1/me, ~0.65s) and the daemon tunnel start
+        # (~2s) are independent — run them concurrently so the auth check
+        # is hidden under the longer daemon wait.
+        import concurrent.futures
+
        server = _resolve_server_url(server)
-        _ensure_databricks_server_auth(server)
-        with runner_startup_progress(initial_message=STARTUP_PHASE_CONNECTING_REMOTE):
-            _ensure_host_daemon(server)
+        with (
+            runner_startup_progress(initial_message=STARTUP_PHASE_CONNECTING_REMOTE),
+            concurrent.futures.ThreadPoolExecutor(max_workers=2) as pool,
+        ):
+            auth_future = pool.submit(_ensure_databricks_server_auth, server)
+            daemon_future = pool.submit(_ensure_host_daemon, server)
+            # Raise auth errors before daemon errors: a login failure is
+            # more actionable than a daemon-connect failure that would
+            # have been caused by the same missing credentials.
+            auth_future.result()
+            daemon_future.result()
        return server
    # Local mode: the daemon spawns (or reuses) a persistent local Omnigent server.
    # On a cold start this is the longest silent gap between the user pressing
@@ -3427,7 +3611,11 @@ def _start_cli_runner_process(
    try:
        with child_logging_popen_kwargs(env) as logging_kwargs:
            runner_proc: subprocess.Popen[bytes] = subprocess.Popen(
-                [sys.executable, "-m", "omnigent.runner._entry"],
+                # This runner inherits the CLI's cwd, so -P is what stops a
+                # checkout you launched from shadowing the installed omnigent
+                # (the daemon and zygote spawns do the same). _entry re-adds the
+                # cwd afterwards, keeping spec-declared local tools importable.
+                [sys.executable, "-P", "-m", "omnigent.runner._entry"],
                env=env,
                stdout=log_fh,
                stderr=log_fh,
@@ -3770,6 +3958,10 @@ def server(

    cfg = _load_config(config_path)

+    # Let the server-config reader (branding) see the same ``-c`` file.
+    if config_path:
+        os.environ["OMNIGENT_CONFIG"] = str(Path(config_path).resolve())
+
    # CLI args take precedence over config file, which takes precedence
    # over defaults.
    db_uri = database_uri or cfg.get("database_uri", _default_db_uri())
@@ -5668,6 +5860,7 @@ def import_session_command(
    import httpx

    from omnigent.chat import _remote_headers
+    from omnigent.conversation_browser import conversation_url
    from omnigent.session_import import (
        ImportSource,
        SessionImportNotFoundError,
@@ -5736,7 +5929,7 @@ def import_session_command(
            response = httpx.post(
                f"{base_url}/v1/imports",
                json=payload,
-                headers=_remote_headers(server_url=base_url),
+                headers=_remote_headers(server_url=base_url, host_id=None),
                timeout=120.0,
            )
        except httpx.RequestError as exc:
@@ -5773,13 +5966,17 @@ def import_session_command(
            )
            continue
        imported_count += 1
+        # Surface the browser URL, not the bare id, so the user can open the
+        # imported session straight into the web (where it offers the resume
+        # picker). Maps a Databricks API base to its workspace SPA link.
+        session_link = conversation_url(base_url, session_id)
        if is_batch:
            click.echo(
                f"Imported {item_count} item(s) from {current_source_session_id} "
-                f"into {session_id}."
+                f"into {session_link}"
            )
        else:
-            click.echo(f"Imported {item_count} item(s) into {session_id}.")
+            click.echo(f"Imported {item_count} item(s) into {session_link}")

    if is_batch:
        click.echo(f"\nImported: {imported_count}")
@@ -5934,7 +6131,7 @@ def usage(limit: int, server: str | None, as_json: bool) -> None:

    with httpx.Client(
        base_url=base_url,
-        headers=_remote_headers(server_url=base_url),
+        headers=_remote_headers(server_url=base_url, host_id=None),
        timeout=60.0,
        trust_env=_trust_env_for(base_url),
    ) as client:
@@ -6018,7 +6215,7 @@ def session_export(session_id: str, output: str | None, server: str | None) -> N

    with httpx.Client(
        base_url=base_url,
-        headers=_remote_headers(server_url=base_url),
+        headers=_remote_headers(server_url=base_url, host_id=None),
        timeout=30.0,
        trust_env=_trust_env_for(base_url),
    ) as client:
@@ -6260,7 +6457,7 @@ def session_import(input_path: str, title: str | None, server: str | None) -> No

    with httpx.Client(
        base_url=base_url,
-        headers=_remote_headers(server_url=base_url),
+        headers=_remote_headers(server_url=base_url, host_id=None),
        timeout=120.0,
        trust_env=_trust_env_for(base_url),
    ) as client:
@@ -6479,10 +6676,24 @@ def _materialize_harness_launcher_file(
    if acp_agent is not None:
        if canonical != "acp":
            raise click.ClickException("An ephemeral ACP agent requires the acp harness.")
-        executor["acp_agent"] = {
+        # Embed all fields that affect spawn so the remote server sees the same
+        # agent config as the client. Preserve session_id_mode, send_model,
+        # omnigent_mcp, env_passthrough, and model.
+        agent_dict: dict[str, object] = {
            "name": acp_agent.name,
            "command": acp_agent.command,
        }
+        if acp_agent.model is not None:
+            agent_dict["model"] = acp_agent.model
+        if acp_agent.session_id_mode != "server":
+            agent_dict["session_id_mode"] = acp_agent.session_id_mode
+        if acp_agent.send_model:
+            agent_dict["send_model"] = acp_agent.send_model
+        if not acp_agent.omnigent_mcp:
+            agent_dict["omnigent_mcp"] = acp_agent.omnigent_mcp
+        if acp_agent.env_passthrough:
+            agent_dict["env_passthrough"] = list(acp_agent.env_passthrough)
+        executor["acp_agent"] = agent_dict

    raw = {
        "name": display_name,
@@ -6776,7 +6987,7 @@ def _dispatch_native_terminal_harness(
        session_id = _resolve_latest_conversation_id(
            base_url=server,
            agent_name=native_agent.agent_name,
-            headers=_remote_headers(server_url=server),
+            headers=_remote_headers(server_url=server, host_id=None),
        )
        # The user explicitly asked to continue; if there's nothing to continue,
        # fail loud rather than silently starting fresh (matches the REPL's
@@ -7558,6 +7769,17 @@ def run(
            raise click.ClickException("--from-openclaw cannot be combined with --harness.")
        acp_agent = _resolve_openclaw_run_agent(from_openclaw)
        harness = f"acp:{acp_agent.slug}"
+    # Client-side harness resolution for acp:<slug>: resolve the slug before
+    # embedding in the spec so it works with remote servers. The server would resolve
+    # the slug from ITS config (if present), but fails when the agent is only
+    # configured locally on the client. Embedding the resolved agent avoids this gap.
+    # Preserve the existing config-lookup path as fallback; specs authored by hand
+    # still use it.
+    if acp_agent is None and harness is not None and harness.startswith("acp:"):
+        from omnigent.onboarding.acp_auth import resolve_acp_agent
+
+        slug = harness.split(":", 1)[1]
+        acp_agent = resolve_acp_agent(slug)
    direct_server_cli = (
        target is None
        and server_from_cli
@@ -7780,6 +8002,9 @@ def _prompt_stop_local_server() -> None:
 # server URL, missing credentials) leaves nothing on the terminal, so we wait
 # this long and surface its log instead of falsely reporting success.
 _BACKGROUND_HOST_GRACE_S = 2.0
+# A detached process isn't ready merely because its PID survived. Wait until
+# the server confirms the host row and live tunnel are online.
+_BACKGROUND_HOST_REGISTRATION_GRACE_S = 30.0


 def _confirm_background_host_alive(record: _HostDaemonRecord) -> None:
@@ -7792,18 +8017,50 @@ def _confirm_background_host_alive(record: _HostDaemonRecord) -> None:
    deadline = time.time() + _BACKGROUND_HOST_GRACE_S
    while True:
        if not _pid_alive(record.pid):
-            from omnigent._runner_startup import format_runner_log_tail
-
-            log_path = Path(record.log_path) if record.log_path else None
            raise click.ClickException(
                "The host daemon exited immediately after starting."
-                f"{format_runner_log_tail(log_path)}"
+                f"{_background_host_log_detail(record.log_path)}"
            )
        if time.time() >= deadline:
            return
        time.sleep(0.1)


+def _background_host_log_detail(log_path: str | None) -> str:
+    """Return the host log path and a short failure tail."""
+    if log_path is None:
+        return ""
+    path = Path(log_path)
+    detail = f"\nHost log: {path}"
+    try:
+        tail = path.read_bytes()[-4096:].decode("utf-8", errors="replace").strip()
+    except OSError:
+        return detail
+    if tail:
+        detail += "\n--- host log tail ---\n" + "\n".join(tail.splitlines()[-12:])
+    return detail
+
+
+def _confirm_background_host_registered(record: _HostDaemonRecord) -> None:
+    """Wait until the detached daemon completes server registration."""
+    deadline = time.monotonic() + _BACKGROUND_HOST_REGISTRATION_GRACE_S
+    while True:
+        if not _pid_alive(record.pid):
+            raise click.ClickException(
+                "The host daemon exited before registering with the server."
+                f"{_background_host_log_detail(record.log_path)}"
+            )
+        if _daemon_host_online(record, timeout_s=1.0):
+            return
+        if time.monotonic() >= deadline:
+            raise click.ClickException(
+                "The host daemon started but did not register with the server "
+                f"within {_BACKGROUND_HOST_REGISTRATION_GRACE_S:.0f}s."
+                f"{_background_host_log_detail(record.log_path)}"
+            )
+        time.sleep(0.2)
+
+
 def _run_background_host(
    server: str | None,
    *,
@@ -7831,7 +8088,7 @@ def _run_background_host(
    :param non_interactive: When ``True``, never launch the browser login —
        fail with the ``omnigent login`` hint instead.
    :raises click.ClickException: If the daemon cannot be spawned, exits
-        immediately after starting, or (local mode) never serves its local
+        immediately, fails to register, or (local mode) never serves its local
        Omnigent server.
    """
    if server:
@@ -7841,30 +8098,40 @@ def _run_background_host(
    _ensure_host_daemon(server or None)
    record = _find_daemon_record(target)
    if record is None:
-        # No record for this target: either the live local-mode daemon already
-        # serves the requested URL, or the spawn itself failed.
+        # A local daemon may already own the requested URL under its local
+        # registry key. It is reusable only after its host is online too.
        if _local_daemon_serves_target(target, server or None):
-            click.echo(f"The local host daemon already serves {target}.")
-            return
+            local_record = _find_daemon_record(_LOCAL_DAEMON_MARKER)
+            if local_record is not None:
+                _confirm_background_host_registered(local_record)
+                click.echo(f"The local host daemon already serves {target}.")
+                return
        raise click.ClickException(
            "Could not spawn the background host daemon. See ~/.omnigent/logs/host/ for details."
        )
-    if previous is not None and previous.pid == record.pid:
-        headline = _cli_style("Host daemon already running", fg="yellow", bold=True)
-    else:
-        _confirm_background_host_alive(record)
-        headline = _cli_style("Started the host daemon in the background", fg="green", bold=True)
+    reused = previous is not None and previous.pid == record.pid
+    try:
+        if not reused:
+            _confirm_background_host_alive(record)
+        if record.mode == "local":
+            # The status probe needs the daemon-owned server's loopback URL.
+            server_url = _discover_local_server_url()
+            _update_daemon_resolved_server_url(target, server_url)
+            record = _find_daemon_record(target) or record
+        else:
+            server_url = target
+        _confirm_background_host_registered(record)
+    except click.ClickException:
+        if not reused:
+            with contextlib.suppress(click.ClickException):
+                _terminate_daemon(record, force=True)
+        raise
+    headline = _cli_style(
+        "Host daemon already running" if reused else "Started the host daemon in the background",
+        fg="yellow" if reused else "green",
+        bold=True,
+    )
    click.echo(f"{headline} (pid {record.pid}).")
-    if record.mode == "local":
-        # A local-mode daemon owns the local Omnigent server, so this command is
-        # the whole "start everything" step — wait for that server and report
-        # its URL, otherwise the Web UI is unreachable without a follow-up
-        # `omnigent server status`. Resolved after the headline above so a cold
-        # start isn't a silent terminal.
-        server_url = _discover_local_server_url()
-        _update_daemon_resolved_server_url(target, server_url)
-    else:
-        server_url = target
    _echo_host_field("server", _cli_style(server_url, fg="cyan"))
    if record.log_path is not None:
        _echo_host_field("log", _display_path(Path(record.log_path)))
@@ -8119,7 +8386,7 @@ def _selected_daemon_records(
 # Databricks CLI). Within a single CLI invocation the token is valid, so
 # resolving once and reusing it is safe. The lock serialises concurrent
 # resolution for the same URL (two threads must not both pay the cost).
-_host_http_headers_cache: dict[str, dict[str, str]] = {}
+_host_http_headers_cache: dict[tuple[str, str | None], dict[str, str]] = {}
 _host_http_headers_lock = threading.Lock()


@@ -8146,6 +8413,7 @@ def _host_http_json(
    params: dict[str, str | int] | None = None,
    json_body: _HostJsonObject | None = None,
    timeout_s: float = 10.0,
+    host_id: str | None = None,
 ) -> _HostHttpResult:
    """
    Send one management request to an Omnigent server.
@@ -8160,6 +8428,10 @@ def _host_http_json(
        ``{"type": "stop_session", "data": {}}``.
    :param timeout_s: Request timeout in seconds, e.g. ``2.0`` for a
        quick liveness probe. Defaults to ``10.0`` for management calls.
+    :param host_id: The host this request is scoped to (host-control, or a
+        host-backed session event like stop_session), so it reaches the replica
+        holding that host's tunnel. ``None`` for non-host-scoped calls; the
+        builder emits the routing header only on the workspace-hosted server.
    :returns: Decoded HTTP result.
    """
    import httpx
@@ -8167,11 +8439,17 @@ def _host_http_json(
    from omnigent.chat import _remote_headers

    try:
-        if base_url not in _host_http_headers_cache:
+        # Cache the resolved headers per (base_url, host_id): the auth resolution
+        # is the expensive part (token mint / CLI shell-out), and the slice-key
+        # varies by the host a call is scoped to, so both belong in the key.
+        cache_key = (base_url, host_id)
+        if cache_key not in _host_http_headers_cache:
            with _host_http_headers_lock:
-                if base_url not in _host_http_headers_cache:
-                    _host_http_headers_cache[base_url] = _remote_headers(server_url=base_url)
-        headers = _host_http_headers_cache[base_url]
+                if cache_key not in _host_http_headers_cache:
+                    _host_http_headers_cache[cache_key] = _remote_headers(
+                        server_url=base_url, host_id=host_id
+                    )
+        headers = _host_http_headers_cache[cache_key]
        with httpx.Client(
            base_url=base_url,
            headers=headers,
@@ -8386,12 +8664,22 @@ def _runner_online_map(
            if isinstance((runner_id := session.get("runner_id")), str) and runner_id
        }
    )
+    # A runner is spawned on exactly one host; its status endpoint reads the
+    # in-memory tunnel registry, so the check must reach that host's replica or
+    # it reports the runner offline. The session rows carry each runner's host.
+    runner_host: dict[str, str] = {}
+    for session in sessions:
+        rid = session.get("runner_id")
+        host = session.get("host_id")
+        if isinstance(rid, str) and rid and isinstance(host, str) and host:
+            runner_host.setdefault(rid, host)
    statuses: dict[str, bool | None] = {}
    for runner_id in runner_ids:
        result = _host_http_json(
            base_url=base_url,
            method="GET",
            path=f"/v1/runners/{url_component(runner_id)}/status",
+            host_id=runner_host.get(runner_id),
        )
        if result.status_code == 200 and isinstance(result.body, dict):
            online = result.body.get("online")
@@ -8472,6 +8760,7 @@ def _add_daemon_host_status(
        base_url=base_url,
        method="GET",
        path=f"/v1/hosts/{url_component(host_id)}",
+        host_id=host_id,
    )
    if host_result.status_code == 200 and isinstance(host_result.body, dict):
        status = host_result.body.get("status")
@@ -8952,11 +9241,27 @@ def _stop_session_on_server(
    """
    from omnigent.claude_native_bridge import url_component

+    # This is a standalone CLI process with an empty session→host map, so read
+    # the session's host from its record first: the stop_session event is a
+    # server→runner forward and must reach the replica holding the runner's
+    # tunnel. The metadata GET itself is host-agnostic (served from any replica).
+    host_id: str | None = None
+    info = _host_http_json(
+        base_url=base_url,
+        method="GET",
+        path=f"/v1/sessions/{url_component(session_id)}",
+    )
+    if info.status_code == 200 and isinstance(info.body, dict):
+        host_value = info.body.get("host_id")
+        if isinstance(host_value, str) and host_value:
+            host_id = host_value
+
    result = _host_http_json(
        base_url=base_url,
        method="POST",
        path=f"/v1/sessions/{url_component(session_id)}/events",
        json_body={"type": "stop_session", "data": {}},
+        host_id=host_id,
    )
    if result.status_code == 0:
        raise click.ClickException(
@@ -9013,6 +9318,50 @@ def _stop_daemon_sessions(
    return stopped


+def _signal_daemon_pid(record: _HostDaemonRecord, sig: int) -> bool:
+    """
+    Signal a daemon's recorded PID, tolerating a stale foreign entry.
+
+    A daemon registry record can outlive the process it names. The recorded
+    PID may since have been reused by an unrelated process — often owned by
+    another user — or the real daemon may have been started under a different
+    account (e.g. ``sudo``). In both cases the PID is no longer this user's
+    daemon and must not be killed.
+
+    ``os.kill`` raises ``PermissionError`` (EPERM) when the caller lacks
+    permission to signal the target — which, since we only ever signal our
+    own daemons, means the record is stale and points at someone else's
+    process. ``_pid_alive`` reports such a PID as alive (``psutil`` maps the
+    same permission failure to ``AccessDenied``), so without this guard
+    ``_terminate_daemon`` would fall through to ``os.kill`` and crash on the
+    unsuppressed EPERM — ``--force`` included, since it dies before the
+    SIGKILL path. Log a warning and treat the record as stale instead.
+
+    :param record: Daemon record whose PID should be signalled.
+    :param sig: Signal number to send, e.g. ``signal.SIGTERM``.
+    :returns: ``True`` if the record is stale and the caller should drop it
+        and stop (either the PID is not ours, or it already exited); ``False``
+        if the signal was delivered and termination should proceed as usual.
+    """
+    try:
+        os.kill(record.pid, sig)
+    except ProcessLookupError:
+        # The process exited between the liveness check and the signal —
+        # nothing left to kill, so the record is stale.
+        return True
+    except PermissionError:
+        # Not our daemon: the record points at another user's process (PID
+        # reuse, or a daemon started under a different account). Drop the
+        # stale record and warn rather than crashing the CLI on the EPERM.
+        click.echo(
+            f"Skipping stale daemon record for {record.target!r}: pid "
+            f"{record.pid} is owned by another user and is not this daemon.",
+            err=True,
+        )
+        return True
+    return False
+
+
 def _terminate_daemon(record: _HostDaemonRecord, *, force: bool) -> None:
    """
    Terminate one local daemon process.
@@ -9024,8 +9373,9 @@ def _terminate_daemon(record: _HostDaemonRecord, *, force: bool) -> None:
    if not _pid_alive(record.pid):
        _delete_daemon_record(record)
        return
-    with contextlib.suppress(ProcessLookupError):
-        os.kill(record.pid, signal.SIGTERM)
+    if _signal_daemon_pid(record, signal.SIGTERM):
+        _delete_daemon_record(record)
+        return
    deadline = time.monotonic() + _HOST_DAEMON_STOP_GRACE_S
    while time.monotonic() < deadline:
        if not _pid_alive(record.pid):
@@ -9033,8 +9383,9 @@ def _terminate_daemon(record: _HostDaemonRecord, *, force: bool) -> None:
            return
        time.sleep(0.1)
    if force:
-        with contextlib.suppress(ProcessLookupError):
-            os.kill(record.pid, getattr(signal, "SIGKILL", signal.SIGTERM))
+        if _signal_daemon_pid(record, getattr(signal, "SIGKILL", signal.SIGTERM)):
+            _delete_daemon_record(record)
+            return
        deadline = time.monotonic() + 2.0
        while time.monotonic() < deadline:
            if not _pid_alive(record.pid):
@@ -10717,6 +11068,12 @@ def _run_databricks_browser_login(workspace_host: str, org_id: str | None = None
        the workspace rejects it).
    :raises click.ClickException: When the Databricks CLI binary is
        missing or the login exits non-zero.
+
+    The login writes to a ``.databrickscfg`` profile named after the
+    workspace's first DNS label (e.g. ``acme`` for
+    ``acme.cloud.databricks.com``), keeping distinct workspaces off the
+    shared ``DEFAULT`` profile. The OAuth grant itself stays host-keyed,
+    so :func:`_databricks_workspace_token` still resolves it by host.
    """
    databricks_bin = shutil.which("databricks")
    if databricks_bin is None:
@@ -10725,14 +11082,21 @@ def _run_databricks_browser_login(workspace_host: str, org_id: str | None = None
            "Install it first: https://docs.databricks.com/dev-tools/cli/install.html"
        )
    login_host = _host_with_org(workspace_host, org_id)
-    click.echo(f"Opening browser to log in to {login_host} ...")
+    # Pin the grant to a profile named for the workspace's first DNS label so
+    # distinct workspaces don't clobber each other under the CLI's ``DEFAULT``.
+    from urllib.parse import urlsplit
+
+    split = urlsplit(workspace_host.rstrip("/"))
+    host = split.hostname or split.netloc or split.path
+    profile = host.split(".")[0]
+    click.echo(f"Opening browser to log in to {login_host} (profile {profile}) ...")
    result = subprocess.run(
-        [databricks_bin, "auth", "login", "--host", login_host],
+        [databricks_bin, "auth", "login", "--host", login_host, "--profile", profile],
        check=False,
    )
    if result.returncode != 0:
        raise click.ClickException(
-            f"`databricks auth login --host {login_host}` failed "
+            f"`databricks auth login --host {login_host} --profile {profile}` failed "
            f"(exit {result.returncode}). If the workspace is unreachable from "
            "this machine (VPN / IP access lists), resolve that and retry."
        )
@@ -10785,7 +11149,7 @@ def _databricks_workspace_token(workspace_host: str) -> str | None:
    try:
        auth, _host = _resolve_databricks_auth(host=workspace_host)
        return auth.current_token()
-    except (DatabricksAuthError, ValueError):
+    except (DatabricksAuthError, ImportError, ValueError):
        return None


@@ -10955,6 +11319,9 @@ def login(server_url: str) -> None:
                token=token,
                user_id=user_id,
                expires_at=_time.time() + expires_in,
+                # Login-issued refresh grant (newer servers) — lets the
+                # host/CLI renew past session expiry unattended.
+                refresh_token=result.get("refresh_token"),
            )
            click.echo(f"Logged in as {user_id}")
            _remember_default_server(server)
@@ -11034,6 +11401,7 @@ def _accounts_login(server: str) -> None:
        token=token,
        user_id=user_id,
        expires_at=_time.time() + expires_in,
+        refresh_token=body.get("refresh_token"),
    )
    click.echo(f"Logged in as {user_id}.")

@@ -21,22 +21,38 @@ from __future__ import annotations
 import contextlib
 import json
 import logging
+import math
 import os
 import stat
 import tempfile
 import time
+import urllib.parse
+from collections.abc import Iterator
 from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import httpx

 _logger = logging.getLogger(__name__)
 _TOKEN_FILE_NAME = "auth_tokens.json"

+# Treat a stored token with less than this much life left as needing
+# renewal. Shared by the "is it still usable" read path and the refresh
+# path's already-renewed check, so a caller that decides to refresh is
+# never handed back the same near-expiry token it wanted to replace.
+# Comfortably longer than a WebSocket handshake, far shorter than the
+# server's 1-hour access-token TTL.
+REFRESH_MIN_REMAINING_SECONDS = 90.0
+

 def _token_file_path() -> Path:
    """Return the path to the auth token storage file.

-    Uses the shared ``~/.omnigent`` state directory.
+    Uses the shared Omnigent state directory, honoring
+    ``OMNIGENT_DATA_DIR``.

-    :returns: Path to ``~/.omnigent/auth_tokens.json``.
+    :returns: Path to ``<data-dir>/auth_tokens.json``.
    """
    from omnigent_ui_sdk.terminal._config import state_dir

@@ -128,6 +144,10 @@ def _store_entry(server_url: str, entry: dict[str, str | float]) -> None:
        except (json.JSONDecodeError, OSError):
            data = {}

+    # Corrupt token files (non-dict JSON) read as empty — never crash.
+    if not isinstance(data, dict):
+        data = {}
+
    data[_normalize_server_url(server_url)] = entry

    _write_tokens_file(path, data)
@@ -138,6 +158,7 @@ def store_token(
    token: str,
    user_id: str,
    expires_at: float,
+    refresh_token: str | None = None,
 ) -> None:
    """Persist a session token for a server.

@@ -147,15 +168,19 @@ def store_token(
    :param user_id: The authenticated user's email, e.g.
        ``"alice@example.com"``.
    :param expires_at: Unix timestamp when the token expires.
+    :param refresh_token: Login-issued refresh grant token, when the
+        server handed one out. Lets :func:`refresh_stored_token` renew
+        the access token past expiry without a human re-running
+        ``omnigent login``.
    """
-    _store_entry(
-        server_url,
-        {
-            "token": token,
-            "user_id": user_id,
-            "expires_at": expires_at,
-        },
-    )
+    entry: dict[str, str | float] = {
+        "token": token,
+        "user_id": user_id,
+        "expires_at": expires_at,
+    }
+    if refresh_token is not None:
+        entry["refresh_token"] = refresh_token
+    _store_entry(server_url, entry)


 def store_databricks_auth(
@@ -211,11 +236,15 @@ def _load_entry(server_url: str) -> dict[str, str | float] | None:
    except (json.JSONDecodeError, OSError):
        return None

+    # A token file holding valid JSON of the wrong shape (``[]``, ``null``,
+    # a bare string) is corrupt, not fatal — read as "nothing stored".
+    if not isinstance(data, dict):
+        return None
    entry = data.get(_normalize_server_url(server_url))
    return entry if isinstance(entry, dict) else None


-def load_token(server_url: str) -> str | None:
+def load_token(server_url: str, *, min_remaining_seconds: float = 0.0) -> str | None:
    """Load a stored session token for a server.

    Returns ``None`` if no token is stored, the token has expired,
@@ -225,6 +254,11 @@ def load_token(server_url: str) -> str | None:

    :param server_url: The server URL, e.g.
        ``"http://localhost:6767"``.
+    :param min_remaining_seconds: Require at least this much remaining
+        lifetime. ``0`` (the default) accepts any not-yet-expired token —
+        the historical behaviour. A caller that can renew passes
+        :data:`REFRESH_MIN_REMAINING_SECONDS` so a token about to lapse
+        mid-handshake is refreshed instead of used.
    :returns: The session JWT string, or ``None``.
    """
    entry = _load_entry(server_url)
@@ -233,13 +267,238 @@ def load_token(server_url: str) -> str | None:

    expires_at = entry.get("expires_at", 0)
    if isinstance(expires_at, (int, float)) and expires_at < time.time():
-        _logger.debug("Stored token for %s has expired", _normalize_server_url(server_url))
+        _warn_expired_once(server_url, expires_at, has_refresh="refresh_token" in entry)
+        return None
+    # Near-expiry but still valid: decline quietly (no expiry warning — it
+    # has not expired) so the caller can choose to renew.
+    if (
+        min_remaining_seconds > 0
+        and isinstance(expires_at, (int, float))
+        and expires_at - time.time() < min_remaining_seconds
+    ):
        return None

    token = entry.get("token")
    return token if isinstance(token, str) else None


+# Servers already warned about an expired stored token, so a poll/retry
+# loop doesn't repeat the warning every few seconds.
+_warned_expired_servers: set[str] = set()
+
+
+def _warn_expired_once(server_url: str, expires_at: float, *, has_refresh: bool) -> None:
+    """Warn (once per process per server) that a stored token expired.
+
+    Expiry used to be a DEBUG line, which left the host dialing
+    unauthenticated into a misleading 403 with no breadcrumb — an
+    operator's first actionable signal must name the cause and the
+    remedy.
+    """
+    normalized = _normalize_server_url(server_url)
+    if normalized in _warned_expired_servers:
+        return
+    _warned_expired_servers.add(normalized)
+    expired_on = time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime(expires_at))
+    if has_refresh:
+        _logger.warning(
+            "Stored login session for %s expired on %s; refresh will be "
+            "attempted on the next command if possible",
+            normalized,
+            expired_on,
+        )
+    else:
+        _logger.warning(
+            "Stored login session for %s expired on %s and holds no refresh "
+            "material. Run `omnigent login %s` to re-authenticate.",
+            normalized,
+            expired_on,
+            normalized,
+        )
+
+
+def stored_token_status(server_url: str) -> str:
+    """Classify the stored auth state for a server.
+
+    Lets callers distinguish "never logged in" from "logged in but the
+    session lapsed" — the difference between proceeding unauthenticated
+    (header-mode servers accept that) and surfacing an actionable
+    re-login message.
+
+    :param server_url: The server URL.
+    :returns: ``"ok"`` (valid token stored), ``"expired"`` (entry exists
+        but the token lapsed), or ``"absent"`` (no token entry at all;
+        includes Databricks pointer records, which hold no token).
+    """
+    entry = _load_entry(server_url)
+    if entry is None or not isinstance(entry.get("token"), str):
+        return "absent"
+    expires_at = entry.get("expires_at", 0)
+    if isinstance(expires_at, (int, float)) and expires_at < time.time():
+        return "expired"
+    return "ok"
+
+
+@contextlib.contextmanager
+def _token_file_lock() -> Iterator[None]:
+    """Exclusive advisory lock over token-file read-modify-write cycles.
+
+    Serializes concurrent refreshes on one machine (host + CLI sharing
+    ``auth_tokens.json``) so only one performs the network exchange and
+    the other picks up its result. Best-effort on platforms without
+    ``fcntl`` (Windows): the refresh still works, only the local
+    serialization is lost.
+
+    :raises OSError: If the lock file cannot be created or opened — the
+        caller degrades to "cannot refresh" (a state directory we cannot
+        write is one we could not persist the result to either).
+    """
+    lock_path = _token_file_path().with_suffix(".lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        import fcntl
+    except ImportError:
+        yield
+        return
+    with open(lock_path, "w") as lock_file:
+        fcntl.flock(lock_file, fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(lock_file, fcntl.LOCK_UN)
+
+
+def refresh_stored_token(server_url: str, *, timeout: float = 10.0) -> str | None:
+    """Renew the stored access token from its login-issued refresh grant.
+
+    POSTs ``grant_type=refresh_token`` to the server's ``/oauth/token``,
+    persists the result, and returns the fresh access token. Safe to call
+    opportunistically: returns ``None`` when there is nothing to refresh
+    (no entry / no refresh material) or when the server refuses (grant
+    revoked, past its absolute lifetime, or an older server without the
+    endpoint).
+
+    Runs under the token-file lock and re-checks state after acquiring
+    it, so of two concurrent callers only one performs the network
+    refresh and the other returns the already-renewed token.
+
+    :param server_url: The server URL, e.g. ``"http://localhost:6767"``.
+    :param timeout: HTTP timeout in seconds.
+    :returns: A valid access token, or ``None``.
+    """
+    normalized = _normalize_server_url(server_url)
+    # Cheap pre-check BEFORE touching the lock file: with no refresh
+    # material there is nothing to do, and creating a lock file would
+    # raise on a read-only state directory — masking the caller's other
+    # credential sources (e.g. the Databricks SDK fallback).
+    pre = _load_entry(server_url)
+    if pre is None or not isinstance(pre.get("refresh_token"), str) or not pre["refresh_token"]:
+        return None
+    try:
+        with _token_file_lock():
+            return _refresh_locked(server_url, normalized, timeout)
+    except OSError as exc:
+        # Cannot lock/persist (read-only or full state dir) — a refresh we
+        # could not store is worse than none, so decline and let the caller
+        # fall through to its other credential sources.
+        _logger.debug("Token refresh for %s skipped, state dir unusable: %s", normalized, exc)
+        return None
+
+
+def _refresh_locked(server_url: str, normalized: str, timeout: float) -> str | None:
+    """Perform the refresh exchange; caller holds the token-file lock."""
+    entry = _load_entry(server_url)
+    if entry is None:
+        return None
+    # Another process may have refreshed while we waited on the lock. A
+    # freshly minted token is far from expiry, so this cleanly separates
+    # "someone already renewed" from "this is the same near-expiry token".
+    expires_at = entry.get("expires_at", 0)
+    token = entry.get("token")
+    if (
+        isinstance(token, str)
+        and isinstance(expires_at, (int, float))
+        and expires_at - time.time() > REFRESH_MIN_REMAINING_SECONDS
+    ):
+        return token
+    refresh_token = entry.get("refresh_token")
+    if not isinstance(refresh_token, str) or not refresh_token:
+        return None
+
+    import httpx
+
+    try:
+        resp = httpx.post(
+            f"{normalized}/oauth/token",
+            data={"grant_type": "refresh_token", "refresh_token": refresh_token},
+            timeout=timeout,
+        )
+    except httpx.HTTPError as exc:
+        _logger.warning("Token refresh against %s failed: %s", normalized, exc)
+        return None
+    if resp.status_code != 200:
+        _logger.warning(
+            "Token refresh against %s refused (HTTP %d) — run `omnigent login %s` "
+            "to re-authenticate.",
+            normalized,
+            resp.status_code,
+            normalized,
+        )
+        return None
+    try:
+        payload = resp.json()
+    except ValueError:
+        _logger.warning("Token refresh against %s returned a malformed response", normalized)
+        return None
+    if not isinstance(payload, dict):
+        _logger.warning("Token refresh against %s returned a malformed response", normalized)
+        return None
+    access_token = payload.get("access_token")
+    new_refresh = payload.get("refresh_token")
+    # Only overwrite the stored pair with genuinely usable material —
+    # a null/non-string field must never clobber a working credential.
+    if not isinstance(access_token, str) or not access_token:
+        _logger.warning("Token refresh against %s returned no access token", normalized)
+        return None
+    if not isinstance(new_refresh, str) or not new_refresh:
+        # A server that renews without returning refresh material keeps the
+        # one we already hold (login grants deliberately do not rotate).
+        new_refresh = refresh_token
+    expires_in = _coerce_expires_in(payload.get("expires_in"))
+
+    user_id = entry.get("user_id")
+    store_token(
+        server_url,
+        token=access_token,
+        user_id=user_id if isinstance(user_id, str) else "",
+        expires_at=time.time() + expires_in,
+        refresh_token=new_refresh,
+    )
+    # A fresh token means any earlier expiry warning is stale; allow
+    # a new one if this credential ever lapses again.
+    _warned_expired_servers.discard(normalized)
+    _logger.info("Refreshed login session for %s", normalized)
+    return access_token
+
+
+def _coerce_expires_in(raw: object) -> float:
+    """Return a sane access-token lifetime in seconds from *raw*.
+
+    Falls back to one hour for anything missing, non-numeric, or
+    non-finite — ``float("NaN")``/``float("Infinity")`` parse happily but
+    would yield an expiry that never compares as expired, pinning a dead
+    token forever.
+    """
+    default = 3600.0
+    try:
+        value = float(raw)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return default
+    if not math.isfinite(value) or value <= 0:
+        return default
+    return value
+
+
 def load_databricks_workspace_host(server_url: str) -> str | None:
    """Load the workspace host from a Databricks Apps pointer record.

@@ -277,6 +536,34 @@ def load_databricks_org_id(server_url: str) -> str | None:
 # workspace request by this header (equivalently to the ``?o=`` query param).
 DATABRICKS_ORG_ID_HEADER = "X-Databricks-Org-Id"

+# Replica-routing header for a host-sharded deployment. The sharding layer
+# routes requests by this value — else the default fallback — so a host's
+# control tunnel, its runners' tunnels, and their session traffic all land on
+# one replica when they carry the same key (the host_id). Omitted for an
+# unsharded / single-replica deployment, which needs no sticky routing.
+OMNIGENT_SLICE_KEY_HEADER = "X-Databricks-Omnigent-Slice-Key"
+
+# A host-sharded deployment mounts the API at this path; an unsharded /
+# single-replica server mounts elsewhere (usually the root). This is the
+# routing-relevant shape of a server URL, so it lives here next to the
+# request-header builder that keys off it (rather than in the browser-link
+# helpers, which only borrow it).
+WORKSPACE_API_PATH = "/api/2.0/omnigent"
+
+
+def is_workspace_hosted_url(base_url: str) -> bool:
+    """Whether *base_url* is a host-sharded deployment mount.
+
+    True for the host-sharded mount (``https://<host>/api/2.0/omnigent``), which
+    is the only deployment fronted by the sharding layer. Used to gate behavior
+    that only applies there (see :func:`databricks_request_headers`).
+
+    :param base_url: Omnigent server base URL, e.g.
+        ``"https://example.databricks.com/api/2.0/omnigent"``.
+    :returns: ``True`` when the URL path is the workspace API mount.
+    """
+    return urllib.parse.urlsplit(base_url.rstrip("/")).path == WORKSPACE_API_PATH
+

 # Opaque extra request headers for dev/test: a JSON object of header name→value
 # in :data:`DATABRICKS_EXTRA_HEADERS_ENV_VAR`. Databricks deployments use it to
@@ -310,7 +597,10 @@ def _databricks_extra_headers() -> dict[str, str]:


 def databricks_request_headers(
-    server_url: str, *, bearer_token: str | None = None
+    server_url: str,
+    *,
+    bearer_token: str | None = None,
+    host_id: str | None = None,
 ) -> dict[str, str]:
    """Build the headers for a request to a Databricks-fronted server.

@@ -335,8 +625,17 @@ def databricks_request_headers(
        ``"https://example.databricks.com/api/2.0/omnigent"``.
    :param bearer_token: The workspace bearer token, or ``None`` when the
        credential is supplied by a separate mechanism (or there is none).
+    :param host_id: The host a request is scoped to (its control tunnel, its
+        runners, and their session traffic all name it so they co-locate on one
+        replica). Pass it unconditionally: it is emitted (as the
+        :data:`OMNIGENT_SLICE_KEY_HEADER` routing header) only when *server_url*
+        is a host-sharded mount, since that is the only deployment with the
+        sharding layer that reads it. ``None`` defaults to the runner's own
+        host_id inside a runner process (via ``OMNIGENT_RUNNER_SLICE_KEY``) and
+        otherwise leaves routing to the default.
    :returns: A header dict carrying ``Authorization``, ``X-Databricks-Org-Id``,
-        and/or the configured extra headers as available, possibly empty.
+        ``X-Databricks-Omnigent-Slice-Key``, and/or the configured extra headers
+        as available, possibly empty.
    """
    headers: dict[str, str] = {}
    if bearer_token:
@@ -344,12 +643,131 @@ def databricks_request_headers(
    org_id = load_databricks_org_id(server_url)
    if org_id:
        headers[DATABRICKS_ORG_ID_HEADER] = org_id
+    # Resolve the slice-key host_id when the caller names none, so every
+    # request still carries a key (routed by the sharding layer rather than
+    # depending on its default). Two ordered fallbacks, both host_ids:
+    #   1. In a runner process, the runner's own host_id (exported at launch as
+    #      OMNIGENT_RUNNER_SLICE_KEY) — keys the runner's server traffic
+    #      (transcript posts, uploads, policy checks) onto its host's replica,
+    #      co-located with its tunnel.
+    #   2. Otherwise, on the CLI, this machine's OWN host_id if it already has a
+    #      host identity — a host-less CLI request (session list, /me-adjacent
+    #      reads, export) then keys to the replica holding this CLI's own hosts'
+    #      tunnels. Read-only (never mints an identity), so a non-host machine
+    #      stays unkeyed (→ default). Gated on the host-sharded mount below so
+    #      the file read only happens for requests that could use it.
+    # Only a host-sharded deployment runs the sharding layer that reads the
+    # header; an unsharded server is single-replica and would just log a header
+    # it ignores — so gate emission (and the CLI identity lookup) on the mount.
+    # Callers never reason about the deployment; a new RPC routed through this
+    # builder is keyed automatically.
+    on_workspace_mount = is_workspace_hosted_url(server_url)
+    if host_id is None:
+        from omnigent.runner.identity import RUNNER_SLICE_KEY_ENV_VAR
+
+        host_id = os.environ.get(RUNNER_SLICE_KEY_ENV_VAR)
+    if host_id is None and on_workspace_mount:
+        from omnigent.host.identity import load_host_identity_if_present
+
+        identity = load_host_identity_if_present()
+        if identity is not None:
+            host_id = identity.host_id
+    # Kill switch: slice-key emission is ON by default; export
+    # ``OMNIGENT_HOST_SLICE_KEY_ENABLED=0`` to turn it off and fall back to the
+    # server's default (workspace-id) routing with no redeploy — a per-process
+    # escape hatch for a bad rollout, since this emits from sidecar-less
+    # processes (laptop CLI, managed sandbox host, spawned runner) that can't
+    # evaluate a server-side flag. Only the exact value "0" disables it; unset,
+    # "1", or anything else leaves emission on.
+    slice_key_enabled = os.environ.get("OMNIGENT_HOST_SLICE_KEY_ENABLED", "1") != "0"
+    if host_id and on_workspace_mount and slice_key_enabled:
+        headers[OMNIGENT_SLICE_KEY_HEADER] = host_id
    # Opaque dev/test extra headers (request-routing selectors); no-op in prod
    # (env unset).
    headers.update(_databricks_extra_headers())
    return headers


+# Sentinel for the ``timeout`` argument of :func:`open_server_client`. ``None``
+# is a meaningful httpx value ("disable timeout"), so it can't stand in for
+# "unset". When the caller passes nothing we omit ``timeout`` entirely and let
+# httpx apply its own default, rather than silently changing it.
+_TIMEOUT_UNSET: Any = object()
+
+
+def open_server_client(
+    server_url: str,
+    *,
+    auth: httpx.Auth | None = None,
+    bearer_token: str | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: Any = _TIMEOUT_UNSET,
+    follow_redirects: bool = False,
+    transport: httpx.AsyncBaseTransport | None = None,
+    host_id: str | None = None,
+) -> httpx.AsyncClient:
+    """Open an :class:`httpx.AsyncClient` to an Omnigent server, keyed for routing.
+
+    The one way to open a client to the server. It folds
+    :func:`databricks_request_headers` in for you, so a request to a host-sharded
+    mount automatically carries the org-id and slice-key routing headers (and any
+    dev/test selectors) — and a request to an unsharded server carries none.
+    Callers never reason about the deployment; a new server RPC opened through
+    this factory is routed correctly by construction, which is why it exists
+    rather than each site building headers by hand.
+
+    :param server_url: The server base URL, e.g.
+        ``"https://example.databricks.com/api/2.0/omnigent"``. Both the client's
+        ``base_url`` and the input to the routing-header builder.
+    :param auth: An httpx ``Auth`` when the credential is minted per request
+        (e.g. :class:`_RunnerDatabricksAuth`, which re-injects a fresh bearer and
+        the routing headers on the OAuth-redirect retry). Mutually exclusive with
+        *bearer_token* in practice: pass one or the other, not both.
+    :param bearer_token: A static workspace bearer, folded in as
+        ``Authorization``. Leave ``None`` when *auth* supplies the credential or
+        there is none.
+    :param headers: Extra request headers (e.g. the runner ``Origin`` sentinel).
+        Merged *under* the routing headers, so routing always wins over a
+        caller-supplied collision.
+    :param timeout: An httpx timeout (``httpx.Timeout``, ``float``, or ``None``
+        to disable). Omitted by default so httpx applies its own default rather
+        than this factory silently overriding it.
+    :param follow_redirects: Passed through to httpx. Defaults to ``False``
+        (httpx's own default); callers relying on seeing a 3xx — e.g. an auth
+        flow that re-mints on the Databricks Apps OAuth login redirect — keep it
+        ``False``.
+    :param transport: An httpx ``AsyncBaseTransport`` to substitute for the
+        default network transport. Its one production-adjacent use is injecting a
+        test transport (e.g. ``httpx.MockTransport``); ``None`` uses the default.
+    :param host_id: The host a request is scoped to, forwarded to
+        :func:`databricks_request_headers` (which emits it as the slice-key only
+        on a host-sharded mount and otherwise falls back to the runner's own
+        host_id). Pass it unconditionally when known.
+    :returns: A configured :class:`httpx.AsyncClient`.
+    """
+    import httpx
+    from omnigent_client._http import is_loopback_url
+
+    pinned = {
+        **(headers or {}),
+        **databricks_request_headers(server_url, bearer_token=bearer_token, host_id=host_id),
+    }
+    kwargs: dict[str, Any] = {}
+    if timeout is not _TIMEOUT_UNSET:
+        kwargs["timeout"] = timeout
+    if transport is not None:
+        kwargs["transport"] = transport
+    return httpx.AsyncClient(
+        base_url=server_url,
+        headers=pinned,
+        auth=auth,
+        follow_redirects=follow_redirects,
+        # A proxy cannot reach a loopback server, so local targets bypass it.
+        trust_env=not is_loopback_url(server_url),
+        **kwargs,
+    )
+
+
 def clear_token(server_url: str) -> None:
    """Remove a stored token for a server.

@@ -2136,6 +2136,40 @@ def _launch_goose_configure() -> str | None:
    return "Provider not detected yet"


+def _show_acp_cli_harness(name: str) -> None:
+    """Show install + sign-in instructions for one builtin ACP CLI harness.
+
+    These harnesses own their credentials (``OWN_AUTH``) and install out-of-band,
+    so there is nothing for Omnigent to store or run on the user's behalf — the
+    drill-in reports what it can and names the two commands. Read-only: it
+    changes no config, which is why it's a display rather than a manage loop.
+
+    :param name: The :data:`ACP_CLI_HARNESSES` row key, e.g. ``"grok"``.
+    """
+    from omnigent._platform import resolve_cli_binary
+    from omnigent.acp_cli_harnesses import ACP_CLI_HARNESSES
+    from omnigent.onboarding.interactive import console
+
+    row = ACP_CLI_HARNESSES.get(name)
+    if row is None:  # defensive: a stale key from a concurrent config change
+        return
+
+    installed = resolve_cli_binary(row.binary) is not None
+    console.print(f"\n  [bold]{row.label}[/bold] — ACP agent (owns its own auth)")
+    if installed:
+        console.print(f"    ✓ `{row.binary}` found on PATH")
+    else:
+        hint = row.install.install_hint or row.binary
+        console.print(
+            f"    ○ `{row.binary}` not found. Install with:\n        [bold]{hint}[/bold]"
+        )
+    if row.login_command:
+        console.print(f"    Sign in with:\n        [bold]{row.login_command}[/bold]")
+    if row.install.auth_hint:
+        console.print(f"    {row.install.auth_hint}")
+    console.print(f"    Launch with: [bold]omnigent run --harness {name}[/bold]\n")
+
+
 def _manage_goose_harness() -> None:
    """Run the level-2 loop for Goose: ensure the CLI, then guide ``goose configure``.

@@ -3475,6 +3509,7 @@ def _run_configure_harnesses_interactive() -> None:
    _ACP_IMPORT = "\x00acp-import-openclaw"
    _ACP_ADD = "\x00acp-add"
    _ACP_AGENT_PREFIX = "\x00acp-agent:"
+    _ACP_CLI_PREFIX = "\x00acp-cli:"
    families = [ANTHROPIC_FAMILY, OPENAI_FAMILY, PI_SURFACE]

    # Status glyph + Rich color per readiness kind: "ready" is a configured,
@@ -3752,6 +3787,50 @@ def _run_configure_harnesses_interactive() -> None:
                    (_GOOSE, "Goose", "Not configured", "warn", "Open to run `goose configure`."),
                )

+        # Builtin ACP CLI harnesses (omnigent/acp_cli_harnesses.py) — vendor CLIs
+        # that speak ACP on stdio. Derived from the catalog so adding a row there
+        # surfaces it here too; without this they were addressable via
+        # `--harness <name>` but invisible in setup, making a shipped harness less
+        # discoverable than a user's own `acp:` entry.
+        from omnigent._platform import resolve_cli_binary
+        from omnigent.acp_cli_harnesses import ACP_CLI_HARNESSES
+        from omnigent.onboarding.acp_auth import acp_agents, shadowed_builtin_acp_rows
+
+        # Skip a row a configured `acp:` agent already claims, so the list shows
+        # one "Devin" (the user's, with its command) rather than two identically
+        # labeled rows. A config error is reported by the custom-ACP block below.
+        try:
+            _shadowed_acp_rows: frozenset[str] = shadowed_builtin_acp_rows(acp_agents(config))
+        except ValueError:
+            _shadowed_acp_rows = frozenset()
+
+        for _acp_cli_name, _acp_cli_row in sorted(ACP_CLI_HARNESSES.items()):
+            if _acp_cli_name in _shadowed_acp_rows:
+                continue
+            _acp_cli_key = _ACP_CLI_PREFIX + _acp_cli_name
+            if resolve_cli_binary(_acp_cli_row.binary) is None:
+                rows.append(
+                    (
+                        _acp_cli_key,
+                        _acp_cli_row.label,
+                        "Not installed",
+                        "missing",
+                        _install_hint(_acp_cli_row.install.install_hint or _acp_cli_row.binary),
+                    )
+                )
+            else:
+                # The vendor owns its auth, so we can report the binary is present
+                # but not whether it is signed in.
+                rows.append(
+                    (
+                        _acp_cli_key,
+                        _acp_cli_row.label,
+                        "ACP · own auth",
+                        "ready",
+                        "Select for install and sign-in instructions.",
+                    )
+                )
+
        # Copilot — GitHub token (github-copilot-sdk extra is soft).
        if copilot_github_token_configured(config) or any(
            os.environ.get(v) for v in COPILOT_TOKEN_ENV_VARS
@@ -3939,6 +4018,8 @@ def _run_configure_harnesses_interactive() -> None:
            _add_acp_agent()
        elif isinstance(selected_target, str) and selected_target.startswith(_ACP_AGENT_PREFIX):
            _manage_acp_agent(selected_target[len(_ACP_AGENT_PREFIX) :])
+        elif isinstance(selected_target, str) and selected_target.startswith(_ACP_CLI_PREFIX):
+            _show_acp_cli_harness(selected_target[len(_ACP_CLI_PREFIX) :])
        elif selected_target == _HERMES:
            _manage_hermes_harness()
        elif selected_target == _KIRO:
@@ -22,7 +22,6 @@ from tempfile import TemporaryDirectory
 import click
 import httpx
 import yaml
-from omnigent_client._http import is_loopback_url

 from omnigent._native_resume_hint import echo_native_resume_hint
 from omnigent._runner_startup import RunnerStartupProgress, runner_startup_progress
@@ -72,6 +71,7 @@ from omnigent.harness_availability import (
 from omnigent.host.daemon_launch import (
    error_text,
    launch_or_reuse_daemon_runner,
+    open_daemon_client,
    wait_for_host_online,
    wait_for_runner_online,
 )
@@ -713,8 +713,12 @@ def _run_with_remote_server(
    from omnigent.cli import _ensure_host_daemon
    from omnigent.host.identity import load_or_create_host_identity

-    headers = _remote_headers(server_url=base_url)
-    attach_auth = _server_auth(server_url=base_url)
+    # This machine's host id keys the WebSocket attach handshake (and its
+    # reconnects) to the replica holding the runner's tunnel; the CLI can set WS
+    # headers, so it rides the header (emitted only on a host-sharded deployment).
+    host_id = load_or_create_host_identity().host_id
+    headers = _remote_headers(server_url=base_url, host_id=host_id)
+    attach_auth = _server_auth(server_url=base_url, session_id=None)
    try:
        resolved_session_id = _resolve_session_id_for_resume(
            base_url=base_url,
@@ -736,7 +740,6 @@ def _run_with_remote_server(
            with runner_startup_progress(initial_message="Preparing Codex...") as progress:
                _update_startup_progress(progress, "Connecting to local daemon...")
                _ensure_host_daemon(base_url)
-                host_id = load_or_create_host_identity().host_id
                bundle = None if resolved_session_id is not None else _bundle_agent(spec_path)
                prepared = await _prepare_codex_terminal_via_daemon(
                    base_url=base_url,
@@ -765,7 +768,7 @@ def _run_with_remote_server(

                :returns: None.
                """
-                new_headers = _remote_headers(server_url=base_url)
+                new_headers = _remote_headers(server_url=base_url, host_id=host_id)
                headers.clear()
                headers.update(new_headers)

@@ -843,22 +846,21 @@ async def _prepare_codex_terminal_via_daemon(
    """
    persist_args = list(codex_args)
    timeout = httpx.Timeout(30.0, read=120.0)
-    async with httpx.AsyncClient(
-        base_url=base_url,
-        headers=headers,
-        timeout=timeout,
-        trust_env=not is_loopback_url(base_url),
-    ) as client:
+    async with open_daemon_client(base_url, headers, host_id, timeout=timeout) as client:
        reattached = session_id is not None
+        fresh_session = session_id is None
        if session_id is None:
            if session_bundle is None:
                raise click.ClickException("Creating a Codex session requires a session bundle.")
            _update_startup_progress(startup_progress, "Creating Codex session...")
-            session_id = await _create_codex_session(
-                client,
-                session_bundle,
-                bridge_id=None,
-                terminal_launch_args=persist_args or None,
+            session_id, _ = await asyncio.gather(
+                _create_codex_session(
+                    client,
+                    session_bundle,
+                    bridge_id=None,
+                    terminal_launch_args=persist_args or None,
+                ),
+                wait_for_host_online(client, host_id, timeout_s=_DAEMON_HOST_ONLINE_TIMEOUT_S),
            )
        else:
            _update_startup_progress(startup_progress, "Loading Codex session...")
@@ -911,13 +913,15 @@ async def _prepare_codex_terminal_via_daemon(
                        f"({resp.status_code}): {error_text(resp)}"
                    )

-        await wait_for_host_online(client, host_id, timeout_s=_DAEMON_HOST_ONLINE_TIMEOUT_S)
+        if not fresh_session:
+            await wait_for_host_online(client, host_id, timeout_s=_DAEMON_HOST_ONLINE_TIMEOUT_S)
        _update_startup_progress(startup_progress, "Starting runner...")
        runner_id = await launch_or_reuse_daemon_runner(
            client,
            host_id=host_id,
            session_id=session_id,
            workspace=workspace,
+            fresh=fresh_session,
        )
        _update_startup_progress(startup_progress, "Waiting for runner...")
        await wait_for_runner_online(client, runner_id, timeout_s=_DAEMON_RUNNER_ONLINE_TIMEOUT_S)
@@ -1019,9 +1023,10 @@ async def _post_initial_prompt(
    :returns: None.
    :raises click.ClickException: If Omnigent rejects the prompt.
    """
-    async with httpx.AsyncClient(
-        base_url=base_url,
-        trust_env=not is_loopback_url(base_url),
+    from omnigent.cli_auth import open_server_client
+
+    async with open_server_client(
+        base_url,
        headers=headers,
        auth=auth,
        timeout=httpx.Timeout(30.0),
@@ -1070,12 +1075,9 @@ async def _prepare_codex_terminal(
    :returns: Prepared terminal details.
    """
    timeout = httpx.Timeout(30.0, read=120.0)
-    async with httpx.AsyncClient(
-        base_url=base_url,
-        headers=headers,
-        timeout=timeout,
-        trust_env=not is_loopback_url(base_url),
-    ) as client:
+    from omnigent.cli_auth import open_server_client
+
+    async with open_server_client(base_url, headers=headers, timeout=timeout) as client:
        bridge_id: str
        thread_id: str | None = None
        if session_id is None:
@@ -1198,6 +1200,7 @@ async def _prepare_codex_terminal(
                        socket_path=codex_ws_url,
                        thread_id=thread_id,
                        codex_home=str(codex_home),
+                        cwd=str(Path.cwd()),
                    ),
                )
            if runner_id is not None:
@@ -1404,9 +1407,10 @@ async def _initialize_fresh_terminal_thread(
        raise click.ClickException("Codex event listener was not initialized.")
    app_server_url = _require_codex_app_server_url(prepared)
    thread_id = await _wait_for_thread_started(prepared.event_client)
-    async with httpx.AsyncClient(
-        base_url=base_url,
-        trust_env=not is_loopback_url(base_url),
+    from omnigent.cli_auth import open_server_client
+
+    async with open_server_client(
+        base_url,
        headers=headers,
        timeout=httpx.Timeout(30.0),
    ) as client:
@@ -1418,6 +1422,7 @@ async def _initialize_fresh_terminal_thread(
            socket_path=app_server_url,
            thread_id=thread_id,
            codex_home=str(codex_home_for_bridge_dir(prepared.bridge_dir)),
+            cwd=str(Path.cwd()),
        ),
    )
    return thread_id
@@ -2712,10 +2717,11 @@ async def _close_codex_terminal(
    :param terminal_id: Terminal resource id.
    :returns: None.
    """
+    from omnigent.cli_auth import open_server_client
+
    with contextlib.suppress(Exception):
-        async with httpx.AsyncClient(
-            base_url=base_url,
-            trust_env=not is_loopback_url(base_url),
+        async with open_server_client(
+            base_url,
            headers=headers,
            timeout=httpx.Timeout(10.0),
        ) as client:
--- a/Show More
+++ b/Show More