Merge branch 'compression-core' of github.com:Egorich-print/OmniRoute into fix/combine-9115

- memoryTools: apiKeyId now optional; falls back to caller principal
  (HTTP auth headers / OMNIROUTE_API_KEY env) so agents can store memory
  without knowing their key id
- memorySkillsInjection: server-side memory_* builtins only injected for
  non-stream requests (stream clients execute tools client-side via MCP)
- memoryBuiltins: memory_save/update/search/delete builtin tools with
  per-provider schemas + interception dispatch
- retrieval: fix toFts5MatchQuery import (ReferenceError on FTS5 path)
- tests: MCP auto-owner fallback, cross-principal isolation, stream guard

.cbmignore

@@ -119,10 +119,11 @@ omnirouteSite/
 # 4. Diretorios de dados / runtime locais (storage, env, secrets, scratch)
 # ─────────────────────────────────────────────────────────────────────────────
 data/
-# NOTA: src/lib/env/, src/app/api/{cloud,sync/cloud,system/env,agent-skills/coverage}/
-# foram removidos daqui (2026-08-05). Os nomes sugerem dados/segredos locais, mas os
-# 8 arquivos sao route handlers e modulos rastreados no git — escondia-los do grafo
-# criava pontos cegos em buscas e em analise de impacto.
+src/lib/env/
+src/app/api/agent-skills/coverage/
+src/app/api/cloud/
+src/app/api/sync/cloud/
+src/app/api/system/env/
 tests/golden-set/data/
 
 # Logs e saida de teste
@@ -141,10 +142,6 @@ obsidian-plugin/node_modules/
 # 6. Diretorios de documentacao interna / workflow
 # ─────────────────────────────────────────────────────────────────────────────
 docs/superpowers/
-# Docs traduzidas: 1.215 arquivos / 94 MB (inclui 20+ copias do CHANGELOG).
-# Sao traducoes do tree em ingles, ja indexado — no grafo so geram ruido em
-# search_code e consomem o auto_index_limit.
-docs/i18n/
 
 # ─────────────────────────────────────────────────────────────────────────────
 # 7. Arquivos especificos (nao diretorios inteiros)
@@ -191,9 +188,8 @@ audit-report.json
 scripts/i18n/_audit.json
 scripts/i18n/_pending-keys.json
 
-# NOTA: bin/omniroute.mjs foi removido daqui (2026-08-05). Estava marcado como
-# "scratch", mas e o entrypoint real do CLI publicado (package.json -> bin.omniroute)
-# e consta em PACK_ARTIFACT_REQUIRED_PATHS. Precisa estar no grafo.
+# Cli binario local (scratch)
+bin/omniroute.mjs
 
 # Deploy / docker backups
 deploy.sh

.dockerignore

@@ -7,13 +7,7 @@
 **/.vscode
 
 # Dependencies and build output
-# `node_modules` alone matches the ROOT only — Docker's matcher does not cross
-# `/` like .gitignore does. Without the `**/` form, nested installs ship in the
-# build context (e.g. @omniroute/opencode-provider/node_modules, ~79 MB of
-# devDependencies). Both forms are kept: the bare one is the documented root
-# rule, the `**/` one covers every nested package.
 node_modules
-**/node_modules
 .next
 .build
 out
@@ -24,6 +18,7 @@ coverage
 # Runtime data and logs
 data
 logs
+.sandbox
 
 # Local env files (inject at runtime via --env-file or -e)
 .env
@@ -43,17 +38,6 @@ tests
 test-results
 playwright-report
 blob-report
-output
-.playwright-cli
-.playwright-mcp
-.stryker-tmp
-reports/mutation
-
-# Local caches and quality-gate artifacts (all gitignored). `_*` does not match
-# dot-prefixed names, so these need explicit entries.
-.artifacts
-.eslintcache
-.eslintcache-complexity
 
 # Documentation
 # Issue #2348: The Dashboard Docs viewer reads markdown from `/app/docs` at
@@ -66,10 +50,6 @@ reports/mutation
 # (English) sources at runtime, so translations are not required in the
 # container image.
 docs/i18n/**
-# Internal planning artifacts (gitignored). `*.md` above only matches the root,
-# so without this rule these land in /app/docs and become readable through the
-# dashboard's Docs viewer at runtime.
-docs/superpowers/**
 docs/diagrams/**/*.png
 docs/diagrams/**/*.jpg
 docs/diagrams/**/*.jpeg

.env.devin-bridge.example

@@ -0,0 +1,6 @@
+ENABLE_LIVE_DEVIN_TESTS=0
+DEVIN_BRIDGE_MODEL=devin-cli-agentic/swe-1-7
+DEVIN_BRIDGE_SONNET_MODEL=devin-cli-agentic/swe-1-7
+DEVIN_BRIDGE_OPUS_MODEL=devin-cli-agentic/swe-1-7
+DEVIN_BRIDGE_HAIKU_MODEL=devin-cli-agentic/swe-1-7
+DEVIN_BRIDGE_SUBAGENT_MODEL=devin-cli-agentic/swe-1-7

.env.example

@@ -1839,6 +1839,18 @@ APP_LOG_TO_FILE=true
 # ── Devin CLI binary path ──
 # Used by: open-sse/executors/devin-cli.ts. Default: looked up via PATH.
 # CLI_DEVIN_BIN=devin
+# Agentic bridge-only binary override. The bridge still executes ACP stdio only.
+# CLI_DEVIN_AGENTIC_BIN=devin
+# Required isolated HOME for the agentic Devin child process.
+# DEVIN_AGENTIC_HOME=/home/bridge
+# Bounded ACP turn timeout in milliseconds. Default: 120000.
+# DEVIN_AGENTIC_ACP_TIMEOUT_MS=120000
+# Agentic bridge model aliases. Values must keep the devin-cli-agentic/ prefix.
+# DEVIN_BRIDGE_MODEL=devin-cli-agentic/swe-1-7
+# DEVIN_BRIDGE_SONNET_MODEL=devin-cli-agentic/swe-1-7
+# DEVIN_BRIDGE_OPUS_MODEL=devin-cli-agentic/swe-1-7
+# DEVIN_BRIDGE_HAIKU_MODEL=devin-cli-agentic/swe-1-7
+# DEVIN_BRIDGE_SUBAGENT_MODEL=devin-cli-agentic/swe-1-7
 
 # ── Command Code (custom CLI) callback ──
 # Local port used for OAuth-style callbacks from the Command Code CLI helper.
@@ -2300,6 +2312,18 @@ QUOTA_STORE_DRIVER=sqlite              # sqlite | redis
 # ─────────────────────────────────────────────────────────────────────────────
 # HYPERAGENT_USAGE_URL=https://hyperagent.com/api/settings/billing/usage
 
+# ─────────────────────────────────────────────────────────────────────────────
+# ChatGPT Web (Codex) headless browser and outbound tool tunnel
+# Used by: open-sse/executors/chatgpt-web-codex.ts
+# Connection values entered in the dashboard override these global defaults.
+# ─────────────────────────────────────────────────────────────────────────────
+# CHATGPT_WEB_CODEX_CHROME_PATH=/usr/bin/chromium
+# CHROME_PATH=/usr/bin/chromium
+# CHATGPT_WEB_CODEX_CDP_URL=http://chatgpt-web-codex-browser:9223
+# CHATGPT_WEB_CODEX_TUNNEL_ID=tunnel_0123456789abcdef0123456789abcdef
+# CHATGPT_WEB_CODEX_RUNTIME_KEY=
+# CHATGPT_WEB_CODEX_CONNECTOR_NAME=OmniRoute Codex
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Browser-login VNC sessions (optional — src/lib/vncSession/manifest.ts)
 # Containerized Chromium+VNC used for interactive browser-login credential

.github/dependabot.yml

@@ -39,17 +39,6 @@ updates:
       # the duplication gate — migrate the gate intentionally, not via dependabot.
       - dependency-name: "jscpd"
         update-types: ["version-update:semver-major"]
-      # ioredis is a SOFT/optional dependency loaded through a dynamic import
-      # (src/lib/quota/redisQuotaStore.ts — "Redis driver requires ioredis package"),
-      # so a breaking major never fails at build or typecheck time: the only consumers
-      # are the distributed quota store (redisQuotaStore.ts, storeFactory.ts) and the
-      # `import type Redis` in src/shared/utils/rateLimiter.ts. Nothing in the unit or
-      # vitest suites exercises a live Redis connection, so a v5→v6 API break would ship
-      # green and only surface at runtime for operators running distributed quota — the
-      # exact users least able to absorb it. #9310 grouped that major with 9 harmless
-      # bumps; majors here need their own PR and a deliberate migration review.
-      - dependency-name: "ioredis"
-        update-types: ["version-update:semver-major"]
       # @huggingface/transformers is HARD-PINNED at 3.5.2 (exact, no caret) — FROZEN.
       # It is load-bearing for the LLMLingua ONNX compression engine (open-sse/services/
       # compression/engines/llmlingua/ — worker.ts pins @huggingface/transformers@3.5.2)

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ env:
 jobs:
   changes:
     name: Change Classification
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     outputs:
       code: ${{ steps.classify.outputs.code }}
       docs: ${{ steps.classify.outputs.docs }}
@@ -35,13 +35,10 @@ jobs:
       workflow: ${{ steps.classify.outputs.workflow }}
       testsOnly: ${{ steps.classify.outputs.testsOnly }}
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
       # Refuse a PR that targets its own head branch before spending anything on it. #8912 has
       # head == base == release/v3.8.50: no diff, can never merge, and it sits in the queue with
       # a full check board attached on every push to that branch. One field comparison.
@@ -77,7 +74,7 @@ jobs:
 
   lint:
     name: Lint
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: changes
     # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
     # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
@@ -91,13 +88,9 @@ jobs:
       API_KEY_SECRET: ci-lint-api-key-secret-long
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - run: npm run audit:deps
@@ -171,7 +164,7 @@ jobs:
 
   quality-gate:
     name: Quality Ratchet
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # needs lint so eslint-results artifact is available (same inventory as the
     # blocking lint step). Allow lint failure so other ratchets still run.
     needs: [changes, test-coverage, lint]
@@ -191,13 +184,9 @@ jobs:
       contents: read
       security-events: read
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - name: Restore ESLint file cache
         uses: actions/cache@v6
@@ -289,7 +278,7 @@ jobs:
   # SonarQube needs SONAR_TOKEN/SONAR_HOST_URL secrets.
   quality-extended:
     name: Quality Gates (Extended)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: changes
     # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
     # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
@@ -299,14 +288,10 @@ jobs:
       # fetch-depth: 0 — the OpenAPI breaking-change gate (oasdiff) reads the base
       # spec via `git show <base_ref>:docs/openapi.yaml`; a shallow clone
       # would lack the base ref and the gate would self-skip (base-unresolved).
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       # Dead-code, cognitive-complexity, type-coverage foram promovidos ao job
       # quality-gate (bloqueante) na Fase 7 INT — não rodam aqui para evitar duplo custo.
@@ -409,20 +394,16 @@ jobs:
 
   docs-sync-strict:
     name: Docs Sync (Strict)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: changes
     # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
     # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
     # Run when docs OR code change: API/route code can break doc/OpenAPI contract gates.
     if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && (needs.changes.outputs.docs == 'true' || needs.changes.outputs.code == 'true')) }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:docs-all
       # Previously-orphaned contract gates (existed as files, never wired anywhere).
@@ -442,7 +423,7 @@ jobs:
 
   docs-lint:
     name: Docs Lint (prose — advisory)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: changes
     # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
     # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
@@ -452,13 +433,9 @@ jobs:
     # existing doc corpus is brought up to style. Promote to blocking once it converges.
     continue-on-error: true
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - name: markdownlint (docs + root, advisory)
         run: npx --yes markdownlint-cli2 "docs/**/*.md" "*.md" "!docs/i18n" "!docs/research" || true
       - name: Vale prose lint (Microsoft style, advisory)
@@ -473,7 +450,7 @@ jobs:
 
   i18n-ui-coverage:
     name: i18n UI Coverage
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: changes
     # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
     # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
@@ -483,14 +460,10 @@ jobs:
       # fetch-depth: 0 — the value-drift gate diffs en.json against the merge base to
       # find rewritten English strings. On a shallow clone the base ref is missing and
       # the gate self-skips (base-unresolved), so it would never actually run.
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: node scripts/i18n/check-ui-keys-coverage.mjs --threshold=65
       # #8463: a rewritten English value used to leave its 39 translations behind
@@ -506,17 +479,13 @@ jobs:
   # without needing app-boot/Playwright infra. Same gating as i18n-ui-coverage.
   i18n-glossary-zhcn:
     name: i18n Glossary (zh-CN)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: changes
     if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && (needs.changes.outputs.i18n == 'true' || needs.changes.outputs.code == 'true')) }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: node scripts/i18n/check-glossary-consistency.mjs --locale=zh-CN
       - run: node scripts/i18n/check-glossary-consistency.mjs --locale=zh-TW
@@ -528,7 +497,7 @@ jobs:
   # idioma (a matrix antiga subia 40 artifacts cujo result.txt colidia no merge-multiple).
   i18n:
     name: i18n Validation (all languages)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: changes
     # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
     # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
@@ -536,7 +505,7 @@ jobs:
     if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && needs.changes.outputs.i18n == 'true') }}
     continue-on-error: true
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - uses: actions/setup-python@v7
@@ -571,15 +540,12 @@ jobs:
   pr-test-policy:
     name: PR Test Policy
     if: ${{ github.event_name == 'pull_request' && github.event.pull_request.draft == false }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
       - name: Fetch base branch
         run: git fetch --no-tags origin "${GITHUB_BASE_REF}"
       - name: Validate source changes include tests
@@ -606,17 +572,17 @@ jobs:
     # online), the heavy jobs run on the dedicated 32-core VPS runners (label
     # omni-release) instead of queueing on the 20-concurrent-job hosted pool.
     # Safety: fork PRs NEVER reach the self-hosted runner — the expression falls
-    # back to ubuntu-latest unless the PR head repo is this repository (push /
+    # back to ubuntu-26.04 unless the PR head repo is this repository (push /
     # dispatch events are own-origin by definition). Any failure path (VM down,
-    # var unset/false) also falls back to ubuntu-latest.
-    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-latest' }}
+    # var unset/false) also falls back to ubuntu-26.04.
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-26.04' }}
     needs: changes
     if: ${{ github.event_name != 'pull_request' || (needs.changes.outputs.code == 'true' && github.event.pull_request.draft == false) }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
@@ -656,18 +622,14 @@ jobs:
 
   package-artifact:
     name: Package Artifact
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: build
     env:
       JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - name: Download Next.js build artifact
@@ -703,15 +665,15 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-26.04, windows-latest]
     env:
       JWT_SECRET: ci-build-secret-with-sufficient-length-for-validation
       CSC_IDENTITY_AUTO_DISCOVERY: "false"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
@@ -750,14 +712,14 @@ jobs:
 
   test-unit:
     name: Unit Tests (${{ matrix.shard }}/8)
-    # Same dynamic-runner rule as Build (own-origin only; fallback ubuntu-latest).
+    # Same dynamic-runner rule as Build (own-origin only; fallback ubuntu-26.04).
     # PINNED to hosted, deliberately not on the USE_VPS_RUNNER switch (gap 19). One variable
     # governed the build and the test jobs, which want OPPOSITE machines: the build needs the
     # .113's RAM, the tests need the hosted runner's link. Measured on 2026-07-29 —
     # actions/setup-node took 20m06s on .113 with 4 concurrent runners versus 16s hosted (npm
     # cache restore saturating the link), while the tests themselves tied, 2m54 vs 2m31. So
     # self-hosted is strictly worse here and there is nothing to configure.
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 25
     # needs: changes (not build) — this job never downloads the next-build artifact;
     # gating it on Build only serialized ~20min of wall-clock for nothing. Jobs that
@@ -775,13 +737,9 @@ jobs:
       API_KEY_SECRET: ci-test-api-key-secret-long
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       # QW-d (plano mestre): fonte única — o MESMO npm script dos runs locais (adiciona o
@@ -811,31 +769,27 @@ jobs:
 
   test-bun-sqlite:
     name: Bun SQLite Compatibility
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 10
     needs: changes
     if: ${{ github.event_name != 'pull_request' || (needs.changes.outputs.code == 'true' && github.event.pull_request.draft == false) }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run test:bun:db
 
   test-vitest:
     name: Vitest (MCP / autoCombo / UI components)
-    # Same dynamic-runner rule as Build (own-origin only; fallback ubuntu-latest).
+    # Same dynamic-runner rule as Build (own-origin only; fallback ubuntu-26.04).
     # PINNED to hosted, deliberately not on the USE_VPS_RUNNER switch (gap 19). One variable
     # governed the build and the test jobs, which want OPPOSITE machines: the build needs the
     # .113's RAM, the tests need the hosted runner's link. Measured on 2026-07-29 —
     # actions/setup-node took 20m06s on .113 with 4 concurrent runners versus 16s hosted (npm
     # cache restore saturating the link), while the tests themselves tied, 2m54 vs 2m31. So
     # self-hosted is strictly worse here and there is nothing to configure.
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 15
     # needs: changes (not build) — no artifact consumed; see test-unit note.
     needs: changes
@@ -845,13 +799,9 @@ jobs:
       API_KEY_SECRET: ci-test-api-key-secret-long
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       # The second test runner (CLAUDE.md: "Both test runners must pass") — was never
       # wired into CI until the 2026-06-09 quality audit (Fase 6A.2).
@@ -879,7 +829,7 @@ jobs:
   # the release gate can still exercise them via workflow_dispatch when needed).
   test-coverage:
     name: Coverage
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # 10min was sized before #7114 added the lcov reporter (Codecov/Sonar need it);
     # merging 8 shard JSONs + text+json+lcov now takes ~10-12min — three consecutive
     # release-tip runs died at exactly 10m as job-timeout "cancelled" (2026-07-15/16).
@@ -890,13 +840,9 @@ jobs:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - name: Download all shard coverage
         uses: actions/download-artifact@v8
@@ -980,14 +926,14 @@ jobs:
 
   sonarqube:
     name: SonarQube
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: test-coverage
     if: ${{ !cancelled() && needs.test-coverage.result == 'success' }}
     env:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
       SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
@@ -1032,7 +978,7 @@ jobs:
 
   coverage-pr-comment:
     name: PR Coverage Comment
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.draft == false && github.event.pull_request.head.repo.fork == false && needs.changes.outputs.code == 'true' }}
     needs:
       - changes
@@ -1111,7 +1057,7 @@ jobs:
 
   test-e2e:
     name: E2E Tests (${{ matrix.shard }}/9)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # Build artifact from the `build` job is downloaded instead of rebuilding
     # (~5min saved per shard). 9 shards (up from 6) reduces tests per shard by
     # ~33%. Playwright browser is cached across runs (~1.5min saved per shard).
@@ -1133,13 +1079,9 @@ jobs:
       DISABLE_SQLITE_AUTO_BACKUP: "true"
       OMNIROUTE_PLAYWRIGHT_SKIP_BUILD: "1"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - name: Cache Playwright browsers
@@ -1188,7 +1130,7 @@ jobs:
 
   test-integration:
     name: Integration Tests (${{ matrix.shard }}/2)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 15
     # needs: changes (not build) — no artifact consumed; see test-unit note.
     needs: changes
@@ -1204,13 +1146,9 @@ jobs:
       DATA_DIR: /tmp/omniroute-ci-${{ matrix.shard }}
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       # (tsx/esm = QW-b; o alinhamento de ESCOPO do integration com o npm script fica p/ follow-up)
@@ -1218,7 +1156,7 @@ jobs:
 
   test-security:
     name: Security Tests
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # needs: changes (not build) — no artifact consumed; see test-unit note.
     needs: changes
     if: ${{ github.event_name != 'pull_request' || (needs.changes.outputs.code == 'true' && github.event.pull_request.draft == false) }}
@@ -1227,20 +1165,16 @@ jobs:
       API_KEY_SECRET: ci-test-api-key-secret-long
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - run: npm run test:security
 
   ci-summary:
     name: CI Dashboard
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     if: ${{ !cancelled() }}
     needs:
       - changes

.github/workflows/claude.yml

@@ -21,7 +21,7 @@ jobs:
       (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
       (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
       (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       contents: read
       pull-requests: read
@@ -30,7 +30,7 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 1

.github/workflows/codeql.yml

@@ -13,7 +13,7 @@ permissions:
 jobs:
   analyze:
     name: Analyze (javascript-typescript)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       security-events: write
       actions: read

.github/workflows/dast-smoke.yml

@@ -18,7 +18,7 @@ concurrency:
   cancel-in-progress: true
 jobs:
   dast-smoke:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # ADVISORY while this new gate matures (repo convention: advisory -> blocking).
     # Flip to blocking (remove continue-on-error) once it's proven stable across a few PRs.
     continue-on-error: true
@@ -33,10 +33,6 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
-        with:
-          node-version: "24"
-          cache: npm
       - run: npm ci
       - name: Build CLI bundle
         env:

.github/workflows/deploy-vps.yml

@@ -15,7 +15,7 @@ jobs:
       (github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success')
       && vars.DEPLOY_ENABLED == 'true'
     name: Deploy OmniRoute to VPS
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
       - name: Check VPS SSH reachability from runner
         id: reach

.github/workflows/docker-publish.yml

@@ -33,7 +33,7 @@ permissions:
 jobs:
   prepare:
     name: Resolve Docker release metadata
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     outputs:
       version: ${{ steps.version.outputs.version }}
       promote_latest: ${{ steps.version.outputs.promote_latest }}
@@ -42,7 +42,7 @@ jobs:
       IMAGE_NAME: diegosouzapw/omniroute
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/v{0}', inputs.version) || '' }}
@@ -145,7 +145,7 @@ jobs:
       GHCR_IMAGE_NAME: ghcr.io/diegosouzapw/omniroute
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/v{0}', inputs.version) || '' }}
@@ -155,13 +155,13 @@ jobs:
         uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v4.5.2
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@v4.5.2
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -233,7 +233,7 @@ jobs:
       - prepare
       - build
     if: needs.prepare.outputs.skip != 'true'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       contents: read
       packages: write
@@ -245,7 +245,7 @@ jobs:
       PROMOTE_LATEST: ${{ needs.prepare.outputs.promote_latest }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/v{0}', inputs.version) || '' }}
@@ -255,13 +255,13 @@ jobs:
         uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v4.5.2
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@v4.5.2
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -390,7 +390,7 @@ jobs:
       - name: Upload Trivy SARIF to Security tab
         if: needs.prepare.outputs.version != 'main'
         continue-on-error: true
-        uses: github/codeql-action/upload-sarif@v4.37.3
+        uses: github/codeql-action/upload-sarif@v4
         with:
           sarif_file: trivy-results.sarif
           category: trivy-image

.github/workflows/electron-release.yml

@@ -20,14 +20,14 @@ permissions:
 jobs:
   validate:
     name: Validate version
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       contents: read
     outputs:
       version: ${{ steps.validate.outputs.version }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
@@ -78,17 +78,17 @@ jobs:
             target: mac-arm64
             ext: -arm64.dmg
           - platform: linux
-            runner: ubuntu-latest
+            runner: ubuntu-26.04
             target: linux
             ext: .AppImage
             deb_ext: .deb
 
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Setup Node
-        uses: actions/setup-node@v7
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: 24
           cache: npm
@@ -239,12 +239,12 @@ jobs:
     # Now: attach everything that did build, then fail the job loudly (see the last
     # step) so an incomplete channel is visible instead of silent.
     if: ${{ !cancelled() && needs.validate.result == 'success' }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       contents: write # softprops/action-gh-release creates the GitHub Release
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
@@ -329,7 +329,7 @@ jobs:
     # of passing unnoticed — the v3.8.49 release had ZERO assets and every gate was
     # green, because nothing ever asserted the release HAS binaries.
     if: ${{ !cancelled() && needs.release.result == 'success' }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       contents: read
     steps:

.github/workflows/lock-released-branch.yml

@@ -40,7 +40,7 @@ jobs:
   # ─────────────────────────────────────────────────────────────────────────
   lock-branch:
     if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
       - name: Lock release/<tag> branch
         env:
@@ -97,7 +97,7 @@ jobs:
   # ─────────────────────────────────────────────────────────────────────────
   guard-no-push-after-release:
     if: github.event_name == 'push'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
       - name: Reject push if matching release tag exists
         env:

.github/workflows/mutation-redundancy.yml

@@ -22,7 +22,7 @@ permissions:
 jobs:
   stryker-nobail:
     name: Stryker disableBail (batch ${{ matrix.batch.name }})
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     strategy:
       fail-fast: false
       matrix:
@@ -41,13 +41,9 @@ jobs:
             mutate: "open-sse/handlers/chatCore/telemetryHelpers.ts,open-sse/handlers/chatCore/memorySkillsInjection.ts,open-sse/handlers/chatCore/semanticCache.ts"
     timeout-minutes: 300
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "24"
-          cache: npm
       - run: npm ci
       - name: Run Stryker (disableBail)
         env:

.github/workflows/nightly-compat.yml

@@ -28,11 +28,11 @@ concurrency:
 jobs:
   resolve-branch:
     name: Resolve active release branch
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     outputs:
       target: ${{ steps.branch.outputs.target }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -58,15 +58,15 @@ jobs:
 
   compat-build-26:
     name: Node 26 Compatibility Build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 25
     needs: resolve-branch
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.resolve-branch.outputs.target }}
           persist-credentials: false
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "26"
           cache: npm
@@ -75,7 +75,7 @@ jobs:
       # CI_NODE_VERSION=24). It failed every nightly with the runner-reclaimed
       # signature ("The runner has received a shutdown signal" / "The operation was
       # canceled", no exit code) always at the same Turbopack compile phase — a
-      # classic OOM kill on the memory-constrained ubuntu-latest runner. Turbopack's
+      # classic OOM kill on the memory-constrained 16 GB hosted runner. Turbopack's
       # native (Rust, off-V8-heap) allocation is NOT bounded by --max-old-space-size
       # and peaks far higher than webpack on this large module graph (#6409), and is
       # heavier still under Node 26. Use the documented webpack fallback here: it still
@@ -88,7 +88,7 @@ jobs:
 
   compat-tests:
     name: Node ${{ matrix.node }} Compat Tests (${{ matrix.shard }}/4)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 25
     needs: resolve-branch
     strategy:
@@ -102,11 +102,11 @@ jobs:
       DISABLE_SQLITE_AUTO_BACKUP: "true"
       TEST_SHARD: ${{ matrix.shard }}/4
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ needs.resolve-branch.outputs.target }}
           persist-credentials: false
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: ${{ matrix.node }}
           cache: npm
@@ -116,7 +116,7 @@ jobs:
 
   report:
     name: Open / update tracking issue on failure
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     if: ${{ !cancelled() && (needs.compat-tests.result == 'failure' || needs.compat-build-26.result == 'failure') }}
     needs: [resolve-branch, compat-build-26, compat-tests]
     permissions:

.github/workflows/nightly-llm-security.yml

@@ -10,13 +10,11 @@ permissions:
 jobs:
   promptfoo-guard:
     name: promptfoo — injection guard (block mode, no secret)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with: { node-version: "24", cache: npm }
       - run: npm ci
       - name: Build CLI bundle
         env:
@@ -46,7 +44,7 @@ jobs:
 
   garak:
     name: garak probes (skip without provider secret)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # NOTE: the `secrets` context is NOT available in a job-level `if:` — referencing
     # it there makes GitHub reject the file on push (startup_failure on every push).
     # Map the secret into a job-level env and gate each step on a presence check, so
@@ -63,13 +61,10 @@ jobs:
             echo "run=false" >> "$GITHUB_OUTPUT"
             echo "::notice::PROMPTFOO_PROVIDER_KEY not set — skipping garak probes (advisory)."
           fi
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
         if: steps.gate.outputs.run == 'true'
-      - uses: actions/setup-node@v7
-        if: steps.gate.outputs.run == 'true'
-        with: { node-version: "24", cache: npm }
       - run: npm ci
         if: steps.gate.outputs.run == 'true'
       - name: Build CLI bundle

.github/workflows/nightly-mutation.yml

@@ -10,7 +10,7 @@ permissions:
 jobs:
   stryker:
     name: Stryker mutation (batch ${{ matrix.batch.name }} — advisory)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # Mutation testing is expensive. History of the budget:
     #   - Full 8-module set TIMED OUT at the 180min cap (run 27705123780 = exactly 180min).
     #     The two god-files chatCore.ts/combo.ts dominated ~2/3 of the mutants and were
@@ -104,13 +104,9 @@ jobs:
     # scripts/quality/mutation-radiography.mjs both merge per file).
     timeout-minutes: ${{ matrix.batch.timeout || 180 }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "24"
-          cache: npm
       - run: npm ci
       - name: Restore Stryker incremental cache
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
@@ -145,15 +141,12 @@ jobs:
     name: Mutation score ratchet (blocking)
     needs: stryker
     if: always()
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "24"
       - name: Download all mutation reports
         uses: actions/download-artifact@v8
         with:

.github/workflows/nightly-property.yml

@@ -8,15 +8,11 @@ permissions:
   issues: write
 jobs:
   property-random-seed:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "24"
-          cache: npm
       - run: npm ci
       - name: fast-check random seed (high runs)
         id: prop

.github/workflows/nightly-release-green.yml

@@ -68,13 +68,13 @@ jobs:
     # this runs on the dedicated VPS runner — clean env (no operator OMNIROUTE_API_KEY,
     # no local noauth CLIs => zero machine-specific false positives) and no contention.
     # Nightly cron normally finds the var false (VM off) and falls back to hosted.
-    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && fromJSON('["self-hosted","omni-release"]')) || 'ubuntu-latest' }}
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && fromJSON('["self-hosted","omni-release"]')) || 'ubuntu-26.04' }}
     env:
       JWT_SECRET: ci-nightly-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-nightly-api-key-secret-long
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -116,7 +116,7 @@ jobs:
           git checkout "$TARGET"
           git log -1 --oneline
 
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "24"
           cache: npm
@@ -217,19 +217,19 @@ jobs:
     # On a push, only run for a push to main — a push to release/* is handled by
     # release-green above. Schedule/dispatch always run (they also sweep main).
     if: ${{ github.event_name != 'push' || github.ref_name == 'main' }}
-    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && fromJSON('["self-hosted","omni-release"]')) || 'ubuntu-latest' }}
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && fromJSON('["self-hosted","omni-release"]')) || 'ubuntu-26.04' }}
     env:
       JWT_SECRET: ci-nightly-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-nightly-api-key-secret-long
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: main # literal — no injection surface; scheduled runs default to the repo default branch (a release/v*), so pin main explicitly
           fetch-depth: 0
           persist-credentials: false
 
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "24"
           cache: npm
@@ -331,12 +331,12 @@ jobs:
   bank-ratchet-shrinks:
     name: Bank ratchet shrinks
     if: ${{ github.event_name != 'push' }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       contents: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
@@ -371,11 +371,6 @@ jobs:
           git checkout "$TARGET"
           git log -1 --oneline
 
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "24"
-          cache: npm
-
       - uses: ./.github/actions/npm-ci-retry
 
       - name: Ratchet the baselines down

.github/workflows/nightly-resilience.yml

@@ -10,43 +10,31 @@ permissions:
 jobs:
   heap:
     name: Heap-growth gate
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "24"
-          cache: npm
       - run: npm ci
       - run: npm run test:heap
 
   chaos:
     name: Resilience chaos (fault injection)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "24"
-          cache: npm
       - run: npm ci
       - run: npm run test:chaos
 
   k6-soak:
     name: k6 load/soak
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "24"
-          cache: npm
       - run: npm ci
       - name: Build CLI bundle
         env:
@@ -78,7 +66,7 @@ jobs:
 
   a11y:
     name: A11y axe (nightly, freeze-and-alert)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # The Playwright webServer (`start` mode) builds Next via build-next-isolated.mjs and
     # boots the standalone server itself (waits on /api/monitoring/health, 15min webServer
     # timeout). Unlike the per-PR test-e2e job, this nightly job has no pre-built artifact,
@@ -92,13 +80,9 @@ jobs:
       DISABLE_SQLITE_AUTO_BACKUP: "true"
       REQUIRE_AXE: "1"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "24"
-          cache: npm
       - run: npm ci
       - name: Cache Playwright browsers
         uses: actions/cache@v6.1.0

.github/workflows/nightly-schemathesis.yml

@@ -10,14 +10,12 @@ permissions:
 jobs:
   schemathesis:
     name: Schemathesis — OpenAPI contract fuzz (advisory)
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with: { node-version: "24", cache: npm }
       - run: npm ci
       - name: Build CLI bundle
         env:

.github/workflows/npm-publish.yml

@@ -62,7 +62,7 @@ jobs:
     # mid-"Creating an optimized production build" while v3.8.48 had still fit in 16min.
     # This job never runs on `pull_request`, so the fork-safety clause is always true here;
     # it is kept verbatim so the expression stays greppable against ci.yml.
-    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-latest' }}
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-26.04' }}
     permissions:
       actions: read # find + download the CI run's next-build artifact for this SHA
       contents: write # gh release upload (attach SBOM to the GitHub Release)
@@ -70,7 +70,7 @@ jobs:
       packages: write # publish to npm.pkg.github.com
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           # Need full tag history to compare against highest semver when
@@ -78,7 +78,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup Node.js
-        uses: actions/setup-node@v7
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: ${{ env.NPM_PUBLISH_NODE_VERSION }}
           registry-url: https://registry.npmjs.org
@@ -339,20 +339,20 @@ jobs:
           echo "✅ Action finished for GitHub Packages"
 
   publish-opencode-plugin:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       contents: read
       id-token: write # npm provenance
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
           # Full history needed for auto-bump: git diff against previous release tag
 
       - name: Setup Node.js
-        uses: actions/setup-node@v7
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: ${{ env.NPM_PUBLISH_NODE_VERSION }}
           registry-url: https://registry.npmjs.org

.github/workflows/opencode-plugin-ci.yml

@@ -26,16 +26,16 @@ defaults:
 jobs:
   test:
     name: Test (Node ${{ matrix.node }})
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     strategy:
       fail-fast: false
       matrix:
         node: ["22", "24"]
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: ${{ matrix.node }}
           cache: npm
@@ -46,13 +46,13 @@ jobs:
 
   build:
     name: Build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: test
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "22"
           cache: npm

.github/workflows/opencode-provider-ci.yml

@@ -26,16 +26,16 @@ defaults:
 jobs:
   test:
     name: Test (Node ${{ matrix.node }})
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     strategy:
       fail-fast: false
       matrix:
         node: ["20", "22", "24"]
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: ${{ matrix.node }}
           cache: npm
@@ -45,13 +45,13 @@ jobs:
 
   build:
     name: Build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     needs: test
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version: "20"
           cache: npm

.github/workflows/quality.yml

@@ -25,20 +25,17 @@ jobs:
   # path filters share existence reasons: code / docs / i18n / workflow.
   changes:
     name: Change Classification
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     outputs:
       code: ${{ steps.classify.outputs.code }}
       docs: ${{ steps.classify.outputs.docs }}
       i18n: ${{ steps.classify.outputs.i18n }}
       workflow: ${{ steps.classify.outputs.workflow }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           fetch-depth: 0
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
       - id: classify
         env:
           EVENT_NAME: ${{ github.event_name }}
@@ -61,19 +58,16 @@ jobs:
     name: Build (advisory)
     needs: changes
     if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
-    # Dynamic runner — same fork-safe rule as ci.yml / fast-gates.
-    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-latest' }}
+    # Fork-safe fallback uses Ubuntu 26.04's bundled Node 24 without setup-node.
+    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-26.04' }}
     # #7307: advisory for the first week of release-PR runs; remove
     # continue-on-error after the production-build signal is stable.
     continue-on-error: true
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
+      - run: node -e 'if (process.versions.node.split(".")[0] !== process.env.CI_NODE_VERSION) throw new Error("Expected Node " + process.env.CI_NODE_VERSION)'
       - uses: ./.github/actions/npm-ci-retry
       - run: npm run check:node-runtime
       - run: npm run build
@@ -88,15 +82,11 @@ jobs:
     name: Docs Gates (fast-path)
     needs: changes
     if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && (needs.changes.outputs.docs == 'true' || needs.changes.outputs.code == 'true')) }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - run: npm ci
       # One walk of src/app/api for openapi-routes + docs-symbols (both still fail independently).
       - run: npm run check:api-docs-refs
@@ -111,7 +101,7 @@ jobs:
     # Dynamic runner (same rule as ci.yml): use the self-hosted VPS pool only when the
     # release captain has USE_VPS_RUNNER=true AND this is not a fork PR (own-origin
     # branches only — a fork PR must never execute on the LAN runner). Var unset/false
-    # or a fork PR falls back to ubuntu-latest, so this is inert until the flag flips.
+    # or a fork PR falls back to ubuntu-26.04, so this is inert until the flag flips.
     # PINNED to hosted (gap 19). This job carried the USE_VPS_RUNNER expression, and that
     # expression was DEAD CONFIGURATION: across 160 quality.yml runs the job never once landed on
     # a self-hosted runner — every non-skipped sample is `GitHub Actions NNNN`. The classifier is
@@ -125,7 +115,7 @@ jobs:
     #
     # With this pinned, USE_VPS_RUNNER governs ONLY build-like jobs — one variable, one coherent
     # purpose. That is what gap 19 asked for; a second variable turned out to be unnecessary.
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # tsx gates (known-symbols, route-guard-membership) import modules that open
     # SQLite on load; provide DB env so a fresh CI DB initializes cleanly.
     env:
@@ -133,14 +123,10 @@ jobs:
       API_KEY_SECRET: ci-lint-api-key-secret-long
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - run: npm ci
       - name: Restore ESLint file cache
         uses: actions/cache@v6
@@ -155,18 +141,7 @@ jobs:
       - run: npm run check:fetch-targets
       # docs-all / openapi-routes / docs-symbols live in docs-gates (path-filtered).
       - run: npm run check:deps
-      # #8522: --base-ref mode for PR events — compare against max(frozen, base) so
-      # inherited drift (base already over frozen cap) doesn't red an innocent PR.
-      # workflow_dispatch (no PR base) falls back to absolute comparison.
-      - name: File-size ratchet (base-relative on PR)
-        env:
-          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
-        run: |
-          if [ -n "$PR_BASE_SHA" ]; then
-            npm run check:file-size -- --base-ref "$PR_BASE_SHA"
-          else
-            npm run check:file-size
-          fi
+      - run: npm run check:file-size
       - run: npm run check:error-helper
       - run: npm run check:migration-numbering
       - run: npm run check:public-creds
@@ -290,7 +265,7 @@ jobs:
       # selector returns __RUN_ALL__ — full-suite authority is the parallel
       # `fast-unit` 4-shard job (test:unit:ci:shard; was 2-shard, #6781), NOT an
       # unsharded re-run here. Stacking unsharded test:unit:ci on top of fast-unit
-      # doubled wall time (~16 min extra on ubuntu-latest) without extra coverage.
+      # doubled wall time (~16 min extra on the hosted runner) without extra coverage.
       #
       # BLOCKING for the *impacted subset* (flipped 2026-06-17). Fail-safe full
       # coverage remains required via `Unit Tests fast-path` (fast-unit).
@@ -354,36 +329,15 @@ jobs:
           if-no-files-found: ignore
           retention-days: 30
 
-  fast-vitest:
-    name: Vitest (fast-path)
-    needs: changes
-    if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
-    # Dynamic runner — see fast-gates (own-origin + flag; fork/unset → ubuntu-latest).
-    # PINNED to hosted, deliberately not on the USE_VPS_RUNNER switch (gap 19). One variable
-    # governed the build and the test jobs, which want OPPOSITE machines: the build needs the
-    # .113's RAM, the tests need the hosted runner's link. Measured on 2026-07-29 —
-    # actions/setup-node took 20m06s on .113 with 4 concurrent runners versus 16s hosted (npm
-    # cache restore saturating the link), while the tests themselves tied, 2m54 vs 2m31. So
-    # self-hosted is strictly worse here and there is nothing to configure.
-    runs-on: ubuntu-latest
-    env:
-      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
-      API_KEY_SECRET: ci-lint-api-key-secret-long
-      DISABLE_SQLITE_AUTO_BACKUP: "true"
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
-      - run: npm ci
-      # WS5.2/5.3: JUnit feeds Trunk Flaky Tests — the fast-path runs on EVERY PR,
-      # which is where flaky-detection volume actually comes from (ci.yml's heavy
-      # jobs only run on the release PR). Advisory upload, own-origin only.
-      - run: npm run test:vitest -- --reporter=default --reporter=junit --outputFile.junit=trunk-junit/vitest-fastpath.xml
-      - name: Upload test results to Trunk (advisory)
+      # Share fast-gates' checkout + npm ci instead of spending ~80s preparing a
+      # separate runner for a ~13s Vitest invocation. !cancelled() preserves the
+      # independent test signal when an earlier fast gate fails.
+      - name: Vitest
+        if: ${{ !cancelled() }}
+        run: npm run test:vitest -- --reporter=default --reporter=junit --outputFile.junit=trunk-junit/vitest-fastpath.xml
+      # WS5.2/5.3: JUnit feeds Trunk Flaky Tests — the fast path runs on every PR.
+      # Advisory upload, own-origin only.
+      - name: Upload Vitest results to Trunk (advisory)
         if: ${{ always() && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
         continue-on-error: true
         uses: trunk-io/analytics-uploader@385f1ccdf345b4532dc4b6c665dd432b702b8e28 # v2.1.2
@@ -396,9 +350,9 @@ jobs:
     name: Unit Tests fast-path (${{ matrix.shard }}/4)
     needs: changes
     if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
-    # Dynamic runner — see fast-gates (own-origin + flag; fork/unset → ubuntu-latest).
+    # Dynamic runner — see fast-gates (own-origin + flag; fork/unset → ubuntu-26.04).
     # This is the heaviest fast-path job; 4-way sharding (was 2, #6781) halves the
-    # critical path again (~8.5min → ~4.5min on ubuntu-latest; ~2min on the 8-slot
+    # critical path again (~8.5min → ~4.5min hosted; ~2min on the 8-slot
     # runner box). Node's native --test-shard=N/total takes any denominator — only
     # this matrix and the TEST_SHARD env below encode the shard count.
     # PINNED to hosted, deliberately not on the USE_VPS_RUNNER switch (gap 19). One variable
@@ -407,7 +361,7 @@ jobs:
     # actions/setup-node took 20m06s on .113 with 4 concurrent runners versus 16s hosted (npm
     # cache restore saturating the link), while the tests themselves tied, 2m54 vs 2m31. So
     # self-hosted is strictly worse here and there is nothing to configure.
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     strategy:
       fail-fast: false
       matrix:
@@ -417,13 +371,9 @@ jobs:
       API_KEY_SECRET: ci-lint-api-key-secret-long
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - run: npm ci
       # QW-d: fonte única — o mesmo npm script do CI pesado/local. Fecha dois drifts do
       # comando inline antigo: os dirs `memory` e `usage` estavam FORA do glob (testes
@@ -448,7 +398,7 @@ jobs:
     name: No new ESLint warnings
     needs: changes
     if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     continue-on-error: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true }}
     # G0 (trilho .50): security-events:read lets the CodeQL ratchet below read open
     # code-scanning alerts via `gh api .../code-scanning/alerts` (same as ci.yml's
@@ -457,13 +407,9 @@ jobs:
       contents: read
       security-events: read
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/setup-node@v7
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - run: npm ci
       - name: Restore ESLint file cache
         uses: actions/cache@v6
@@ -516,21 +462,17 @@ jobs:
     name: Merge integrity (changelog + generated skills)
     # Always on non-draft PRs — CHANGELOG/skills can break on docs-only merges too.
     if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     continue-on-error: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true }}
     env:
       JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-lint-api-key-secret-long
       DISABLE_SQLITE_AUTO_BACKUP: "true"
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v6
-        with:
-          node-version: ${{ env.CI_NODE_VERSION }}
-          cache: npm
       - run: npm ci
       - name: CHANGELOG integrity (nenhum bullet da base pode sumir no merge-result)
         run: npm run check:changelog-integrity

.github/workflows/scorecard.yml

@@ -11,7 +11,7 @@ permissions: read-all
 jobs:
   analysis:
     name: Scorecard analysis
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     permissions:
       # security-events: write removed — Scorecard findings are advisory and no longer
       # uploaded to the code-scanning Security tab (they are supply-chain/posture scores,
@@ -21,7 +21,7 @@ jobs:
       contents: read
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 

.github/workflows/semgrep.yml

@@ -14,7 +14,7 @@ concurrency:
   cancel-in-progress: true
 jobs:
   semgrep:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     container:
       image: semgrep/semgrep
     steps:

.github/workflows/wiki-sync.yml

@@ -34,15 +34,10 @@ concurrency:
 jobs:
   sync-wiki:
     name: Sync wiki with docs
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v7
-
-      - name: Setup Node
-        uses: actions/setup-node@v7
-        with:
-          node-version: "24"
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Clone wiki
         env:

.gitignore

@@ -72,6 +72,7 @@ yarn-error.log*
 # env files (can opt-in for committing if needed)
 .env*
 !.env.example
+!.env.devin-bridge.example
 !.env.homolog.example
 # Provider API keys (never commit)
 *.api-key
@@ -209,6 +210,8 @@ scripts/i18n/_pending-keys.json
 .agents/
 .antigravitycli/
 .claude/
+!tests/fixtures/devin-bridge/e2e-workspace/.claude/
+!tests/fixtures/devin-bridge/e2e-workspace/.claude/**
 
 # PR Reviews and local feedback files
 pr_reviews*.json
@@ -235,10 +238,7 @@ omniroute.md
 
 # mise configuration
 mise.toml
-# release-green artifacts (.gitignore has no inline comments — a trailing
-# `# ...` becomes part of the pattern, so it must sit on its own line).
-# Already covered by /_*/ above; kept explicit for discoverability.
-_artifacts/
+_artifacts/          # release-green artifacts
 .claude-flow/
 
 # ESLint file cache (npm run lint --cache / complexity ratchets)
@@ -248,6 +248,8 @@ _artifacts/
 
 # CI/local quality artifacts (eslint-results.json, quality-ratchet.md, etc.)
 .artifacts/
+# Isolated Devin bridge workspaces, evidence, and test databases
+.sandbox/
 
 # Homologation E2E suite (npm run homolog) — real-environment credentials + report output
 .env.homolog
@@ -256,7 +258,3 @@ tests/homolog/ui/.auth/
 homolog-report/
 docker-compose.yml.bak
 .playwright-cli/
-# Playwright screenshot/log output. Today every artifact happens to land inside
-# output/**/.playwright-cli/ (covered above), but anything written directly to
-# output/ would otherwise show up as untracked.
-/output/

.mergify.yml

@@ -17,13 +17,6 @@
 #   • Fallback path if Mergify misbehaves or the OSS plan changes: the manual
 #     merge-train runbook (docs/ops/MERGE_TRAIN.md) — remove labels, proceed by hand.
 
-# Auto-enqueue (current Mergify model, 2026): auto_merge_conditions in
-# merge_protections_settings — the rules-based queue action / autoqueue path is
-# deprecated (EOL 2026-07-16). The owner-applied `queue` label IS the approval.
-merge_protections_settings:
-  auto_merge_conditions:
-    - label = queue
-
 queue_rules:
   - name: release
     # Any current or future release branch — the reason GitHub's native queue was
@@ -41,26 +34,14 @@ queue_rules:
     # is intentionally NOT a condition here: the owner-applied `queue` label IS the
     # approval in this repo's single-maintainer model (see governance header).
     merge_conditions:
-      # "Zero failures" — EXCEPT the advisory "Build (advisory)" job (quality.yml):
-      # continue-on-error by design, and its GH-hosted Turbopack build hangs
-      # recurrently mid-"Creating an optimized production build" (100% failure rate
-      # across every sampled PR since the job was added 2026-07-27, always killed by
-      # a runner timeout/shutdown signal, never a real compile error). Any OTHER
-      # failure still blocks (anti-fail-open kept). The prior dast-smoke exception
-      # (#7225) was dropped here: dast-smoke's hang (#7226) has been dormant for
-      # weeks (0 failures in the last 30 runs; 2 all-time, none since 2026-07-13) —
-      # carrying its tolerance forward would mask problems it no longer causes.
-      - or:
-          - "#check-failure=0"
-          - and:
-              - "#check-failure=1"
-              - check-failure=Build (advisory)
+      - "#check-failure=0"
       - "#check-pending=0"
       - "#check-success>=1"
       - check-success=Merge integrity (changelog + generated skills)
-    # NO batching: 'Merge Queue Batch' requires a paid Mergify tier (live finding
-    # 2026-07-15 — the queue command fails with "Cannot use Merge Queue batch" on
-    # the free plan). Serial queue (1 PR at a time) still automates the train.
+    # Batching: validate up to 10 queued PRs together (the manual train's sweet spot);
+    # don't hold a lone PR hostage waiting for siblings.
+    batch_size: 10
+    batch_max_wait_time: 5 min
     # Squash keeps the one-commit-per-PR history the CHANGELOG reconciliation expects.
     merge_method: squash
 

.npmignore

@@ -4,14 +4,11 @@ data/
 **/db.json
 
 # VS Code extension test runtime (large binary, not needed in npm package)
+app/vscode-extension/
 **/data/
 **/db.json
 
-# Source code (pre-built dist/ is published instead)
-#
-# NOTA (2026-08-05): as entradas `app/*` foram removidas — o diretorio `app/`
-# foi renomeado para `dist/` na Layer 1 e nao existe mais. Elas sugeriam um
-# layout que ja nao e o do projeto.
+# Source code (pre-built app/ is published instead)
 #
 # NOTE (#3578 / #3821-review): package.json "files" is the source of truth for what
 # ships. It now allowlists the backend source closure the MCP server needs at runtime
@@ -52,6 +49,8 @@ scripts/
 .vscode/
 .agents/
 .env*
+app/.env
+app/.env*
 eslint.config.mjs
 prettier.config.mjs
 postcss.config.mjs
@@ -83,6 +82,8 @@ bun.lock
 *.deb
 *.rpm
 electron/
+app/electron/
+app/vscode-extension/
 
 # Subprojects
 clipr/
@@ -92,6 +93,10 @@ vscode-extension/
 
 # Root-level underscore-prefixed directories (private/draft — never publish)
 /_*/
+app/_*/
+app/coverage/
+app/logs/
+app/tests/
 
 # Consistent with .gitignore and .dockerignore
 .DS_Store

.prettierignore

@@ -1,11 +1,6 @@
 # Long reference tables are manually aligned; formatting the whole file causes noisy diffs.
 docs/reference/ENVIRONMENT.md
 
-# Generated by `npm run gen:provider-reference`; the generator aligns the tables and
-# is their formatter of record. Without this, lint-staged reformats the file whenever
-# it is staged and the next generator run reverts it — a diff ping-pong.
-docs/reference/PROVIDER_REFERENCE.md
-
 # Dense auto-generated free-tier budget rows (one object per line) — prettier multi-line expand blows past file-size cap 800.
 open-sse/config/freeModelCatalog.data.ts
 

@omniroute/opencode-plugin/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@omniroute/opencode-plugin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@omniroute/opencode-plugin",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "license": "MIT",
       "dependencies": {
         "zod": "^4.4.3"

@omniroute/openhands-plugin/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+*.log
+.DS_Store
+.env

@omniroute/openhands-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OmniRoute contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

@omniroute/openhands-plugin/README.md

@@ -0,0 +1,118 @@
+# @omniroute/openhands-plugin
+
+OpenHands integration for the **OmniRoute AI Gateway**. Generates the OpenHands
+environment and Docker config that wires an OpenHands agent-server to a running
+OmniRoute instance — with the integration gotchas already handled.
+
+## Why
+
+Running OpenHands against OmniRoute directly hits several wall:
+
+1. **Model name mismatch** — OpenHands sends `model: "deepseek-chat"`, OmniRoute
+   uses provider-prefixed IDs (`ds/deepseek-v4-flash`) or combos.
+2. **Python 3.13 sandbox** — `socket.socketpair()` fails under Docker's default
+   seccomp profile; the agent-server needs `privileged: true`.
+3. **Host reachability** — the sandbox can't resolve `localhost` to the OmniRoute
+   host; needs `host.docker.internal:host-gateway`.
+4. **Lost state** — conversations die with the container unless
+   `OH_PERSISTENCE_DIR` is a host volume.
+5. **CORS** — the dashboard origin can't reach agent-server unless
+   `PERMITTED_CORS_ORIGINS` allows it.
+
+This plugin encodes all of that into one command.
+
+## Install
+
+```bash
+npm install -g @omniroute/openhands-plugin
+# or: npx @omniroute/openhands-plugin ...
+```
+
+## Quick start
+
+Generate the OpenHands `.env`:
+
+```bash
+omniroute-openhands env \
+  --api-key sk-... \
+  --model deepseek-chat \
+  --url http://192.168.3.106:20128
+```
+
+Generate a `docker-compose.yml` service:
+
+```bash
+omniroute-openhands compose \
+  --api-key sk-... \
+  --model glm-5.2 \
+  --persistence-dir /Users/me/.openhands-state \
+  --cors-origins http://100.73.44.17:3000
+```
+
+Or a plain `docker run`:
+
+```bash
+omniroute-openhands docker-run \
+  --api-key sk-... \
+  --model vivanta-core \
+  --persistence-dir /Users/me/.openhands-state
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `env` | Print OpenHands `.env` contents |
+| `compose` | Print a Docker Compose service block |
+| `docker-run` | Print a full `docker run` command |
+| `models` | Print the default OpenHands → OmniRoute model map |
+
+### Common options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--api-key` | OmniRoute API key (`sk-...`) | — |
+| `--model` | OpenHands model name or OmniRoute combo | — |
+| `--url` | OmniRoute base URL | `http://localhost:20128` |
+| `--persistence-dir` | Host dir for conversation state | `.openhands-state` |
+| `--cors-origins` | Comma-separated allowed origins | `localhost:3000,3001` |
+| `--sandbox-image` | OpenHands sandbox base image | — |
+
+## Model mapping
+
+OpenHands-friendly names are mapped to OmniRoute IDs/combo names:
+
+| OpenHands sends | OmniRoute resolves to |
+|-----------------|----------------------|
+| `deepseek-chat` | `ds/deepseek-v4-flash` |
+| `deepseek-reasoner` | `ds/deepseek-v4-pro` |
+| `glm-5.2` | `nvidia/z-ai/glm-5.2` |
+| `gpt-4o` | `openai/gpt-4o` |
+| `claude-sonnet-4.5` | `anthropic/claude-sonnet-4.5` |
+| ... | ... |
+
+Or just pass an OmniRoute combo name (e.g. `--model vivanta-core`) — the Model
+Alias Resolver and combo router accept it directly.
+
+## Library usage
+
+```ts
+import {
+  buildOpenHandsEnv,
+  serializeOpenHandsEnv,
+  buildOpenHandsCompose,
+  resolveOpenHandsModel,
+} from "@omniroute/openhands-plugin";
+
+const env = buildOpenHandsEnv({
+  apiKey: "sk-...",
+  model: resolveOpenHandsModel("deepseek-chat"),
+  omnirouteUrl: "http://localhost:20128",
+  persistenceDir: "/Users/me/.openhands-state",
+});
+console.log(serializeOpenHandsEnv(env));
+```
+
+## License
+
+MIT — same as OmniRoute.

@omniroute/openhands-plugin/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@omniroute/openhands-plugin",
+  "version": "0.1.0",
+  "description": "OpenHands integration for the OmniRoute AI Gateway. Generates OpenHands env + Docker Compose config (model mapping, sandbox, CORS, persistence) so OpenHands agents talk to OmniRoute out of the box.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "omniroute-openhands": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./env": {
+      "types": "./dist/env.d.ts",
+      "import": "./dist/env.js"
+    },
+    "./docker": {
+      "types": "./dist/docker.d.ts",
+      "import": "./dist/docker.js"
+    },
+    "./model-map": {
+      "types": "./dist/model-map.d.ts",
+      "import": "./dist/model-map.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "node --import tsx/esm --test tests/env.test.ts tests/model-map.test.ts tests/docker.test.ts",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "omniroute",
+    "openhands",
+    "open-hands",
+    "openhands-plugin",
+    "openai-compatible",
+    "docker",
+    "agent"
+  ],
+  "author": "OmniRoute contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/diegosouzapw/OmniRoute.git",
+    "directory": "@omniroute/openhands-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/diegosouzapw/OmniRoute/issues"
+  },
+  "homepage": "https://github.com/diegosouzapw/OmniRoute/tree/main/%40omniroute/openhands-plugin#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@omniroute/open-sse": "*"
+  },
+  "peerDependenciesMeta": {
+    "@omniroute/open-sse": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "tsup": "^8.5.1",
+    "tsx": "^4.22.3"
+  }
+}

@omniroute/openhands-plugin/src/cli.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * @omniroute/openhands-plugin CLI — generate OpenHands .env / Docker config
+ * for a running OmniRoute instance.
+ *
+ * Usage:
+ *   omniroute-openhands env   --api-key sk-... --model deepseek-chat [--url http://localhost:20128]
+ *   omniroute-openhands compose --api-key sk-... --model deepseek-chat [--persistence-dir /path]
+ *   omniroute-openhands docker-run --api-key sk-... --model deepseek-chat
+ *   omniroute-openhands models  (print the default model map)
+ */
+import { buildOpenHandsEnv, serializeOpenHandsEnv } from "./env.ts";
+import { buildOpenHandsCompose, buildOpenHandsDockerRun } from "./docker.ts";
+import { DEFAULT_OPENHANDS_MODEL_MAP } from "./model-map.ts";
+
+function parseArgs(argv: string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      out[key] = next;
+      i++;
+    } else {
+      out[key] = "true";
+    }
+  }
+  return out;
+}
+
+function requireArgs(args: Record<string, string>, names: string[]): void {
+  for (const name of names) {
+    if (!args[name]) {
+      console.error(`Missing required --${name}`);
+      process.exit(2);
+    }
+  }
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+const args = parseArgs(rest);
+
+switch (cmd) {
+  case "env": {
+    requireArgs(args, ["api-key", "model"]);
+    const env = buildOpenHandsEnv({
+      apiKey: args["api-key"],
+      model: args.model,
+      omnirouteUrl: args.url,
+      persistenceDir: args["persistence-dir"],
+      corsOrigins: args["cors-origins"]?.split(","),
+    });
+    process.stdout.write(serializeOpenHandsEnv(env));
+    break;
+  }
+  case "compose": {
+    requireArgs(args, ["api-key", "model"]);
+    process.stdout.write(
+      buildOpenHandsCompose({
+        apiKey: args["api-key"],
+        model: args.model,
+        omnirouteUrl: args.url,
+        persistenceDir: args["persistence-dir"] ?? ".openhands-state",
+        corsOrigins: args["cors-origins"]?.split(","),
+        sandboxBaseImage: args["sandbox-image"],
+      })
+    );
+    break;
+  }
+  case "docker-run": {
+    requireArgs(args, ["api-key", "model"]);
+    process.stdout.write(
+      buildOpenHandsDockerRun({
+        apiKey: args["api-key"],
+        model: args.model,
+        omnirouteUrl: args.url,
+        persistenceDir: args["persistence-dir"] ?? ".openhands-state",
+        corsOrigins: args["cors-origins"]?.split(","),
+        sandboxBaseImage: args["sandbox-image"],
+      })
+    );
+    break;
+  }
+  case "models": {
+    for (const [name, target] of Object.entries(DEFAULT_OPENHANDS_MODEL_MAP)) {
+      process.stdout.write(`${name}\t->\t${target}\n`);
+    }
+    break;
+  }
+  default:
+    console.error(
+      "Usage: omniroute-openhands <env|compose|docker-run|models> [options]\n" +
+        "Options:\n" +
+        "  --api-key <sk-...>         OmniRoute API key (required for env/compose/docker-run)\n" +
+        "  --model <name>             OpenHands model name or OmniRoute combo\n" +
+        "  --url <base>               OmniRoute URL (default http://localhost:20128)\n" +
+        "  --persistence-dir <path>   Host dir for conversation state\n" +
+        "  --cors-origins <a,b,...>   Allowed CORS origins\n" +
+        "  --sandbox-image <image>    OpenHands sandbox base image"
+    );
+    process.exit(1);
+}

@omniroute/openhands-plugin/src/docker.ts

@@ -0,0 +1,92 @@
+/**
+ * OpenHands agent-server Docker Compose generator for OmniRoute.
+ *
+ * Bakes in the integration fixes that were needed to run OpenHands against
+ * OmniRoute reliably:
+ *   - `privileged: true`       — Python 3.13 socket.socketpair() needs it under
+ *                                Docker's default seccomp profile
+ *   - `extra_hosts`            — host.docker.internal → host-gateway so the
+ *                                sandbox can reach OmniRoute on the host
+ *   - host volume for OH_PERSISTENCE_DIR so conversations survive `docker rm`
+ *   - PERMITTED_CORS_ORIGINS   — allow the dashboard origin to hit agent-server
+ */
+
+export interface OpenHandsDockerOptions {
+  /** Agent-server image (default: the official OpenHands runtime image). */
+  image?: string;
+  /** Container name (default: openhands-agent). */
+  containerName?: string;
+  /** Model name to pass via LLM_MODEL. */
+  model: string;
+  /** OmniRoute API key. */
+  apiKey: string;
+  /** OmniRoute base URL reachable from the sandbox (default http://localhost:20128). */
+  omnirouteUrl?: string;
+  /** Host directory for OH_PERSISTENCE_DIR (must match env.ts persistenceDir). */
+  persistenceDir: string;
+  /** CORS origins to permit. */
+  corsOrigins?: string[];
+  /** Sandbox base image (defaults to OpenHands default). */
+  sandboxBaseImage?: string;
+  /** Set true to use host networking instead of extra_hosts. */
+  hostNetwork?: boolean;
+}
+
+export function buildOpenHandsCompose(opts: OpenHandsDockerOptions): string {
+  const image = opts.image ?? "docker.all-hands.dev/all-hands-ai/openhands:latest";
+  const containerName = opts.containerName ?? "openhands-agent";
+  const omnirouteHost = (opts.omnirouteUrl ?? "http://localhost:20128").replace(/\/+$/, "");
+  const cors =
+    opts.corsOrigins && opts.corsOrigins.length > 0
+      ? opts.corsOrigins
+      : ["http://localhost:3000", "http://localhost:3001"];
+
+  const lines: string[] = [];
+  lines.push(`services:`);
+  lines.push(`  openhands:`);
+  lines.push(`    image: ${image}`);
+  lines.push(`    container_name: ${containerName}`);
+  lines.push(`    privileged: true`);
+  lines.push(`    environment:`);
+  lines.push(`      LLM_MODEL: "${opts.model}"`);
+  lines.push(`      LLM_BASE_URL: "${omnirouteHost}/v1"`);
+  lines.push(`      LLM_API_KEY: "${opts.apiKey}"`);
+  lines.push(`      OH_PERSISTENCE_DIR: "/opt/.openhands-state"`);
+  lines.push(`      PERMITTED_CORS_ORIGINS: "${cors.join(",")}"`);
+  if (opts.sandboxBaseImage) {
+    lines.push(`      SANDBOX_BASE_IMAGE: "${opts.sandboxBaseImage}"`);
+  }
+  lines.push(`    volumes:`);
+  lines.push(`      - ${opts.persistenceDir}:/opt/.openhands-state`);
+  lines.push(`    extra_hosts:`);
+  lines.push(`      - "host.docker.internal:host-gateway"`);
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * docker run equivalent of {@link buildOpenHandsCompose} — returns the full
+ * `docker run` command line.
+ */
+export function buildOpenHandsDockerRun(opts: OpenHandsDockerOptions): string {
+  const image = opts.image ?? "docker.all-hands.dev/all-hands-ai/openhands:latest";
+  const omnirouteHost = (opts.omnirouteUrl ?? "http://localhost:20128").replace(/\/+$/, "");
+  const cors =
+    opts.corsOrigins && opts.corsOrigins.length > 0
+      ? opts.corsOrigins
+      : ["http://localhost:3000", "http://localhost:3001"];
+
+  const parts = [
+    "docker run",
+    "--privileged",
+    "--add-host host.docker.internal:host-gateway",
+    `-e LLM_MODEL="${opts.model}"`,
+    `-e LLM_BASE_URL="${omnirouteHost}/v1"`,
+    `-e LLM_API_KEY="${opts.apiKey}"`,
+    `-e OH_PERSISTENCE_DIR=/opt/.openhands-state`,
+    `-e PERMITTED_CORS_ORIGINS="${cors.join(",")}"`,
+    `-v "${opts.persistenceDir}:/opt/.openhands-state"`,
+    image,
+  ];
+  return parts.join(" ") + "\n";
+}

@omniroute/openhands-plugin/src/env.ts

@@ -0,0 +1,63 @@
+/**
+ * OpenHands `.env` generator for the OmniRoute AI Gateway.
+ *
+ * Produces the OpenHands environment that points an OpenHands agent-server at
+ * a running OmniRoute instance and fixes the integration gotchas found in the
+ * field:
+ *   - LLM_MODEL   — OpenHands-friendly model name → OmniRoute model/combo
+ *   - LLM_BASE_URL — OmniRoute OpenAI-compatible endpoint
+ *   - LLM_API_KEY  — OmniRoute key (sk-...)
+ *   - OH_PERSISTENCE_DIR — host-mounted SQLite/conversation persistence
+ *   - PERMITTED_CORS_ORIGINS — allow the dashboard origin to reach agent-server
+ */
+
+export interface OpenHandsEnvOptions {
+  /** OmniRoute base URL as seen from the agent-server (default localhost:20128). */
+  omnirouteUrl?: string;
+  /** OmniRoute API key (sk-...). */
+  apiKey: string;
+  /** OpenHands model name (e.g. "deepseek-chat") or OmniRoute combo/model. */
+  model: string;
+  /** Host directory for OH_PERSISTENCE_DIR (default: current dir + .openhands-state). */
+  persistenceDir?: string;
+  /** CORS origins that must reach the agent-server (default dashboard origin + localhost). */
+  corsOrigins?: string[];
+  /** Optional OpenHands sandbox base image. */
+  sandboxBaseImage?: string;
+}
+
+export function buildOpenHandsEnv(opts: OpenHandsEnvOptions): Record<string, string> {
+  const omnirouteHost = (opts.omnirouteUrl ?? "http://localhost:20128").replace(/\/+$/, "");
+  const persistence = opts.persistenceDir ?? `${process.cwd()}/.openhands-state`;
+  const cors =
+    opts.corsOrigins && opts.corsOrigins.length > 0
+      ? opts.corsOrigins
+      : ["http://localhost:3000", "http://localhost:3001"];
+
+  const env: Record<string, string> = {
+    LLM_MODEL: opts.model,
+    LLM_BASE_URL: `${omnirouteHost}/v1`,
+    LLM_API_KEY: opts.apiKey,
+    OH_PERSISTENCE_DIR: persistence,
+    PERMITTED_CORS_ORIGINS: cors.join(","),
+  };
+
+  if (opts.sandboxBaseImage) {
+    env.SANDBOX_BASE_IMAGE = opts.sandboxBaseImage;
+  }
+
+  return env;
+}
+
+/**
+ * Serialize the env record to `.env` file content (KEY=VALUE lines).
+ * Values are not quoted unless they contain whitespace or `#`.
+ */
+export function serializeOpenHandsEnv(env: Record<string, string>): string {
+  const lines: string[] = [];
+  for (const [key, value] of Object.entries(env)) {
+    const needsQuotes = /[\s#]/.test(value);
+    lines.push(needsQuotes ? `${key}="${value}"` : `${key}=${value}`);
+  }
+  return lines.join("\n") + "\n";
+}

@omniroute/openhands-plugin/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @omniroute/openhands-plugin — OpenHands integration for the OmniRoute AI Gateway.
+ *
+ * Generates the OpenHands environment and Docker Compose / docker run config
+ * that wires an OpenHands agent-server to a running OmniRoute instance:
+ * model mapping, sandbox privileges, host-gateway networking, persistent
+ * conversation state and CORS.
+ */
+export { buildOpenHandsEnv, serializeOpenHandsEnv } from "./env.ts";
+export type { OpenHandsEnvOptions } from "./env.ts";
+export { buildOpenHandsCompose, buildOpenHandsDockerRun } from "./docker.ts";
+export type { OpenHandsDockerOptions } from "./docker.ts";
+export {
+  DEFAULT_OPENHANDS_MODEL_MAP,
+  resolveOpenHandsModel,
+  buildOpenHandsModel,
+} from "./model-map.ts";
+export type { OpenHandsModelMap } from "./model-map.ts";

@omniroute/openhands-plugin/src/model-map.ts

@@ -0,0 +1,64 @@
+/**
+ * OpenHands → OmniRoute model mapping.
+ *
+ * OpenHands sends `model: "<LLM_MODEL>"` and expects the OpenAI-compatible
+ * endpoint to accept that exact string. OmniRoute uses provider-prefixed
+ * model IDs (`ds/deepseek-v4-flash`) and combo names. This module maps
+ * common OpenHands-friendly names to the OmniRoute model/combo they should
+ * resolve to, and back-fills the `LLM_MODEL` value for OpenHands.
+ */
+
+export interface OpenHandsModelMap {
+  /** OpenHands-friendly model name (e.g. "deepseek-chat") */
+  [openHandsName: string]: string;
+}
+
+/**
+ * Default mapping for the model names OpenHands and the broader ecosystem
+ * commonly send. Values are OmniRoute model IDs or combo names. Extend or
+ * override via {@link resolveOpenHandsModel}.
+ */
+export const DEFAULT_OPENHANDS_MODEL_MAP: OpenHandsModelMap = Object.freeze({
+  // DeepSeek
+  "deepseek-chat": "ds/deepseek-v4-flash",
+  "deepseek-reasoner": "ds/deepseek-v4-pro",
+  // Claude / Anthropic
+  "claude-sonnet-4.5": "anthropic/claude-sonnet-4.5",
+  "claude-opus-4.1": "anthropic/claude-opus-4.1",
+  "claude-haiku-4.5": "anthropic/claude-haiku-4.5",
+  // GPT / OpenAI
+  "gpt-4o": "openai/gpt-4o",
+  "gpt-4o-mini": "openai/gpt-4o-mini",
+  "gpt-5": "openai/gpt-5",
+  // Gemini
+  "gemini-2.5-flash": "gemini/gemini-2.5-flash",
+  "gemini-2.5-pro": "gemini/gemini-2.5-pro",
+  // GLM / Z.AI (NVIDIA NIM free endpoint)
+  "glm-5.2": "nvidia/z-ai/glm-5.2",
+});
+
+/**
+ * Resolve the OmniRoute model ID for an OpenHands-friendly model name.
+ * Returns the input unchanged when no mapping exists (OmniRoute will try to
+ * resolve it as a literal model/combo).
+ */
+export function resolveOpenHandsModel(
+  openHandsModel: string,
+  map: OpenHandsModelMap = DEFAULT_OPENHANDS_MODEL_MAP
+): string {
+  if (!openHandsModel) return openHandsModel;
+  const mapped = map[openHandsModel];
+  return mapped ?? openHandsModel;
+}
+
+/**
+ * Build the `LLM_MODEL` value for OpenHands from an OmniRoute model ID/combo.
+ *
+ * OpenHands only surfaces the literal `LLM_MODEL` string in its UI, so for
+ * OmniRoute combos (e.g. "vivanta-core") that's already the right value.
+ * For provider-prefixed IDs, we return them as-is — the OmniRoute Model
+ * Alias Resolver accepts both the raw ID and aliases on the `/v1` endpoint.
+ */
+export function buildOpenHandsModel(omnirouteModelOrCombo: string): string {
+  return omnirouteModelOrCombo;
+}

@omniroute/openhands-plugin/tests/env.test.ts

@@ -0,0 +1,76 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildOpenHandsEnv, serializeOpenHandsEnv } from "../src/env.ts";
+import { resolveOpenHandsModel, buildOpenHandsModel } from "../src/model-map.ts";
+import { buildOpenHandsCompose, buildOpenHandsDockerRun } from "../src/docker.ts";
+
+test("buildOpenHandsEnv produces LLM vars pointing at OmniRoute", () => {
+  const env = buildOpenHandsEnv({
+    apiKey: "sk-test-123",
+    model: "deepseek-chat",
+    omnirouteUrl: "http://192.168.3.106:20128",
+    persistenceDir: "/opt/state",
+    corsOrigins: ["http://100.73.44.17:3000"],
+  });
+  assert.equal(env.LLM_MODEL, "deepseek-chat");
+  assert.equal(env.LLM_BASE_URL, "http://192.168.3.106:20128/v1");
+  assert.equal(env.LLM_API_KEY, "sk-test-123");
+  assert.equal(env.OH_PERSISTENCE_DIR, "/opt/state");
+  assert.equal(env.PERMITTED_CORS_ORIGINS, "http://100.73.44.17:3000");
+});
+
+test("serializeOpenHandsEnv quotes values with whitespace/#", () => {
+  const out = serializeOpenHandsEnv({ LLM_MODEL: "deepseek-chat", LLM_BASE_URL: "http://localhost:20128/v1" });
+  const lines = out.trim().split("\n");
+  assert.ok(lines.some((l) => l.startsWith("LLM_MODEL=deepseek-chat")));
+  assert.ok(lines.some((l) => l.startsWith("LLM_BASE_URL=http://localhost:20128/v1")));
+});
+
+test("resolveOpenHandsModel maps known names to OmniRoute IDs", () => {
+  assert.equal(resolveOpenHandsModel("deepseek-chat"), "ds/deepseek-v4-flash");
+  assert.equal(resolveOpenHandsModel("glm-5.2"), "nvidia/z-ai/glm-5.2");
+  assert.equal(resolveOpenHandsModel("gpt-4o"), "openai/gpt-4o");
+});
+
+test("resolveOpenHandsModel passes unknown names through unchanged", () => {
+  assert.equal(resolveOpenHandsModel("vivanta-core"), "vivanta-core");
+  assert.equal(resolveOpenHandsModel(""), "");
+});
+
+test("resolveOpenHandsModel accepts custom map overrides", () => {
+  const custom = { "my-alias": "nvidia/z-ai/glm-5.2" };
+  assert.equal(resolveOpenHandsModel("my-alias", custom), "nvidia/z-ai/glm-5.2");
+  assert.equal(resolveOpenHandsModel("deepseek-chat", custom), "deepseek-chat");
+});
+
+test("buildOpenHandsModel passes combo names through", () => {
+  assert.equal(buildOpenHandsModel("vivanta-core"), "vivanta-core");
+  assert.equal(buildOpenHandsModel("ds/deepseek-v4-flash"), "ds/deepseek-v4-flash");
+});
+
+test("buildOpenHandsCompose includes privileged, extra_hosts, volume, CORS", () => {
+  const compose = buildOpenHandsCompose({
+    apiKey: "sk-x",
+    model: "deepseek-chat",
+    persistenceDir: "/Users/me/.openhands-state",
+    corsOrigins: ["http://localhost:3000"],
+  });
+  assert.ok(compose.includes("privileged: true"), "privileged present");
+  assert.ok(compose.includes("host.docker.internal:host-gateway"), "host-gateway present");
+  assert.ok(compose.includes("/Users/me/.openhands-state"), "persistence volume present");
+  assert.ok(compose.includes("LLM_BASE_URL: \"http://localhost:20128/v1\""), "base url present");
+  assert.ok(compose.includes("PERMITTED_CORS_ORIGINS: \"http://localhost:3000\""), "cors present");
+});
+
+test("buildOpenHandsDockerRun produces a runnable docker command", () => {
+  const run = buildOpenHandsDockerRun({
+    apiKey: "sk-x",
+    model: "glm-5.2",
+    persistenceDir: "/opt/state",
+  });
+  assert.ok(run.startsWith("docker run"));
+  assert.ok(run.includes("--privileged"));
+  assert.ok(run.includes("--add-host host.docker.internal:host-gateway"));
+  assert.ok(run.includes("LLM_MODEL=\"glm-5.2\""));
+  assert.ok(run.includes("LLM_BASE_URL=\"http://localhost:20128/v1\""));
+});

@omniroute/openhands-plugin/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "ignoreDeprecations": "6.0",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "declaration": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": false,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules", "tests"]
+}

@omniroute/openhands-plugin/tsup.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts", "src/cli.ts"],
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  sourcemap: false,
+  splitting: false,
+  treeshake: false,
+  target: "node18",
+  outDir: "dist",
+  minify: false,
+  cjsInterop: false,
+});

AGENTS.md

@@ -1,117 +1,600 @@
-# OmniRoute agent guide
+# omniroute — Agent Guidelines
 
 ## Project
 
-OmniRoute is a unified AI proxy/router. The repository contains the Next.js application
-(`src/`), streaming engine workspace (`open-sse/`), Electron desktop app (`electron/`),
-CLI (`bin/`), and tests (`tests/`).
+Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
+with **290 provider entries** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
+Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepInfra,
+SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more)
+with **MCP Server** (104 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
 
-## Setup and focused checks
+> **Live counts (v3.8.49)**: providers 290 · MCP tools 104 · MCP scopes 30 · A2A skills 6 ·
+> open-sse services 134 · routing strategies 17 · auto-combo scoring factors 12 ·
+> DB modules 95 · DB migrations 110 · base tables 17 · search providers 11 ·
+> i18n locales 42. **Refresh with `npm run check:docs-all`.**
 
-- Runtime: Node.js `>=22.22.3 <23` or `>=24.0.0 <27`; npm 10+.
-- Install dependencies: `npm install`.
-- Start development: `npm run dev`.
-- Build: `npm run build`; release build: `npm run build:release`.
-- Lint: `npm run lint`.
-- Core type check: `npm run typecheck:core`.
-- Run the most focused test for changed code first:
-  `node --import tsx/esm --test tests/unit/<file>.test.ts`.
-- Other suites: `npm run test:vitest`, `npm run test:e2e`,
-  `npm run test:protocols:e2e`, and `npm run test:ecosystem`.
-- Run `npm run check:docs-all` after changing documentation.
+## Doc Accuracy Discipline (read before writing any doc)
 
-For the complete test matrix, coverage requirements, and pull-request gates, read
-[`CONTRIBUTING.md`](CONTRIBUTING.md#running-tests).
+> **If `grep -rn "name" src/ open-sse/ bin/` returns nothing, the name does not exist. Do not document it.**
 
-## Documentation accuracy
+The recurring failure mode in AI-generated docs is _plausible-but-unverified specifics_.
+Every claim in a `.md` file under `docs/` should be verifiable against the source.
 
-Documentation must describe verified behavior, not plausible behavior.
+**Rules (enforced by `npm run check:fabricated-docs`):**
 
-1. Before documenting an API name, endpoint, path, CLI command, or environment variable,
-   search for it: `rg -n "name" src/ open-sse/ bin/`. If it has no source match, do not
-   document it.
-2. Measure mutable counts instead of writing them from memory: use `wc -l <file>` or a
-   directory-specific count command.
-3. Copy code examples from working usage or run them. Prefer a source link such as
-   `path/to/file.ts:line` to an invented signature.
-4. Run `npm run check:docs-all` for edits under `docs/`; it includes the fabricated-docs
-   validation.
+1. **Never state an API name, endpoint, path, CLI command, or env var without grepping for it first.**
+   ```bash
+   grep -rn "theName" src/ open-sse/ bin/
+   # 0 hits → do not document
+   ```
+2. **Never write a line count, file size, migration count, provider count, or strategy count from memory.**
+   ```bash
+   wc -l <file>           # exact line count
+   ls <dir>/*.ts | wc -l  # file count
+   ```
+3. **Every code example should be copy-pasted from real usage or actually run** — not synthesized.
+   Link to a real call site (`path:line`) instead of inventing a signature.
+4. **Prefer citing real source (`file.ts:line`) over paraphrasing behavior** — verifiable and self-correcting.
+5. **A shorter doc that is 100% accurate beats a comprehensive one with fabrications.**
+   Wrong docs cost more than missing docs, because people trust and act on them.
 
-## Code conventions
+The script `scripts/check/check-fabricated-docs.mjs` extracts every route path, env var, hook
+name, function name, and file reference from `docs/**/*.md` and verifies each one against the
+codebase. Run it locally before pushing docs; it runs in CI via `npm run check:docs-all`.
 
-- Format with Prettier: two spaces, semicolons, double quotes, 100-character line width,
-  and ES5 trailing commas. Run Prettier on changed files.
-- TypeScript target is ES2022 with bundler module resolution. Prefer explicit types.
-- Import order: external, internal (`@/` and `@omniroute/open-sse`), then relative.
-- Do not add logic to `src/lib/localDb.ts`; import from the owning `src/lib/db/` module.
-- Use specific errors and contextual logging. Do not silently swallow SSE-stream failures;
-  use abort signals for cleanup and return appropriate HTTP status codes.
+## Stack
 
-## Security requirements
+- **Runtime**: Next.js 16 (App Router), Node.js `>=22.0.0 <23 || >=24.0.0 <27`, ES Modules (`"type": "module"`)
+- **Language**: TypeScript 6.0 (`src/`) + JavaScript (`open-sse/`, `electron/`)
+- **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/`
+- **Streaming**: SSE via `open-sse` internal workspace package
+- **Styling**: Tailwind CSS v4
+- **i18n**: next-intl with 42 locales (`src/i18n/messages/`) — refresh with `ls src/i18n/messages/*.json | wc -l`
+- **Desktop**: Electron (cross-platform: Windows, macOS, Linux)
+- **Schemas**: Zod v4 for all API / MCP input validation
 
-- Never commit credentials or log SQLite encryption keys.
-- Validate API inputs with Zod and use the route's required authentication path.
-- Sanitize user HTML with DOMPurify.
-- Use `resolvePublicCred()` for public upstream OAuth identifiers; never add them as string
-  literals. See [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md).
-- Use `buildErrorBody()` or `sanitizeErrorMessage()` for HTTP, SSE, executor, and MCP errors;
-  do not return raw `err.stack` or `err.message`. See
-  [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md).
-- Pass runtime values to `exec()` or `spawn()` through `env`, not interpolation into a script.
+---
 
-## Repository map
+## Build, Lint, and Test Commands
 
-Read the nearest `AGENTS.md` and the linked deep-dive before making a non-trivial change.
+| Command                             | Description                                                        |
+| ----------------------------------- | ------------------------------------------------------------------ |
+| `npm run dev`                       | Start Next.js dev server                                           |
+| `npm run build`                     | Production build: `next build` → `.build/next/` + assemble `dist/` |
+| `npm run build:release`             | Clean rebuild + HEAD sentinel (`dist/BUILD_SHA`) — use for deploy  |
+| `npm run start`                     | Run production build                                               |
+| `npm run build:cli`                 | Build CLI package                                                  |
+| `npm run lint`                      | ESLint on all source files                                         |
+| `npm run typecheck:core`            | TypeScript core type checking                                      |
+| `npm run typecheck:noimplicit:core` | Strict checking (no implicit any)                                  |
+| `npm run check`                     | Run lint + test                                                    |
+| `npm run check:cycles`              | Check for circular dependencies                                    |
+| `npm run electron:dev`              | Run Electron app in dev mode                                       |
+| `npm run electron:build`            | Build Electron app for current OS                                  |
 
-| Area                               | Location                                                | Start here                                                                                                                                       |
-| ---------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| API routes                         | `src/app/api/v1/`                                       | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)                                                                         |
-| Streaming request handling         | `open-sse/handlers/`                                    | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)                                                                         |
-| Provider execution and translation | `open-sse/executors/`, `open-sse/translator/`           | [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md)                                                     |
-| Routing and resilience             | `open-sse/services/`                                    | [`open-sse/services/AGENTS.md`](open-sse/services/AGENTS.md), [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)                         |
-| Database and migrations            | `src/lib/db/`, `db/migrations/`                         | [`src/lib/db/AGENTS.md`](src/lib/db/AGENTS.md)                                                                                                   |
-| Domain policy                      | `src/domain/`                                           | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)                                                                         |
-| MCP and A2A                        | `open-sse/mcp-server/`, `src/lib/a2a/`                  | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md), [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md)               |
-| Agent features                     | `src/lib/{acp,memory,skills,cloudAgent}/`               | [`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md), [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md) |
-| Safety and governance              | `src/lib/{guardrails,compliance}/`, `src/server/authz/` | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md), [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md)             |
-| Operations                         | `src/mitm/`, tunnel modules, `electron/`                | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md), [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md)                       |
+**Build output layout:**
 
-## Review focus
+| Directory | Purpose                                            | Gitignored |
+| --------- | -------------------------------------------------- | ---------- |
+| `src/`    | Application source (TypeScript / TSX)              | No         |
+| `.build/` | Build intermediates (`distDir = .build/next`)      | Yes        |
+| `dist/`   | Shippable bundle assembled by `assembleStandalone` | Yes        |
 
-- Keep database operations in `src/lib/db/`; do not issue raw SQL from routes.
-- Send provider requests through `open-sse/handlers/`.
-- Keep MCP and A2A pages as tabs inside `/dashboard/endpoint`.
-- Preserve SSE cleanup, rate-limit header parsing, Zod validation, and provider-schema
-  validation.
-- Treat Memory and Skills as cross-cutting changes that can affect MCP tools, the request
-  pipeline, and A2A skills.
-- Do not close a contributor pull request after using its code; merge it through GitHub so
-  the contributor receives credit.
+The pipeline is a single `next build` pass — intermediates land in `.build/next/`, the
+assembled bundle in `dist/`. VPS deploys rsync `dist/` into the remote
+`/usr/lib/node_modules/omniroute/app/` directory (VPS image path is unchanged).
 
-## Upstream contributions
+### Running Tests
 
-This checkout is a fork of `diegosouzapw/OmniRoute`. Keep fork-only deployment and personal
-automation changes out of upstream PRs.
+```bash
+# All tests (unit + vitest + ecosystem + e2e)
+npm run test:all
 
-Start upstream work from the active upstream default branch, not `main`:
+# Single test file (Node.js native test runner — most tests use this)
+node --import tsx/esm --test tests/unit/your-file.test.ts
+node --import tsx/esm --test tests/unit/plan3-p0.test.ts
+node --import tsx/esm --test tests/unit/fixes-p1.test.ts
+node --import tsx/esm --test tests/unit/security-fase01.test.ts
+
+# Integration tests
+node --import tsx/esm --test tests/integration/*.test.ts
+
+# Vitest (MCP server, autoCombo)
+npm run test:vitest
+
+# E2E with Playwright
+npm run test:e2e
+
+# Protocol clients E2E (MCP transports, A2A)
+npm run test:protocols:e2e
+
+# Ecosystem compatibility tests
+npm run test:ecosystem
+
+# Coverage (see CONTRIBUTING.md)
+npm run test:coverage
+```
+
+**For authoritative coverage requirements, test execution, and PR gates, see [`CONTRIBUTING.md`](CONTRIBUTING.md#running-tests).**
+
+---
+
+## Code Style Guidelines
+
+### Formatting (Prettier — enforced via lint-staged)
+
+2 spaces · semicolons required · double quotes (`"`) · 100 char width · es5 trailing commas.
+Always run `prettier --write` on changed files.
+
+### TypeScript
+
+- **Target**: ES2022 · **Module**: `esnext` · **Resolution**: `bundler`
+- `strict: false` — prefer explicit types, don't rely on inference
+- Path aliases: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
+
+### ESLint Rules
+
+- **Security (error, everywhere)**: `no-eval`, `no-implied-eval`, `no-new-func`
+- **Relaxed in `open-sse/` and `tests/`**: `@typescript-eslint/no-explicit-any` = warn
+- React hooks rules and `@next/next/no-assign-module-variable` disabled in `open-sse/` and `tests/`
+
+### Naming
+
+| Element             | Convention                       | Example                              |
+| ------------------- | -------------------------------- | ------------------------------------ |
+| Files               | camelCase / kebab-case           | `chatCore.ts`, `tokenHealthCheck.ts` |
+| React components    | PascalCase                       | `Dashboard.tsx`, `ProviderCard.tsx`  |
+| Functions/variables | camelCase                        | `getHealth()`, `switchCombo()`       |
+| Constants           | UPPER_SNAKE                      | `MAX_RETRIES`, `DEFAULT_TIMEOUT`     |
+| Interfaces          | PascalCase (`I` prefix optional) | `ProviderConfig`                     |
+| Enums               | PascalCase (members too)         | `LogLevel.Error`                     |
+
+### Imports
+
+- **Order**: external → internal (`@/`, `@omniroute/open-sse`) → relative (`./`, `../`)
+- **No barrel imports** from `localDb.ts` — import from the specific `db/` module instead
+
+### Error Handling
+
+- try/catch with specific error types; always log with context (pino logger)
+- Never silently swallow errors in SSE streams — use abort signals for cleanup
+- Return proper HTTP status codes (4xx client, 5xx server)
+
+### Security
+
+- **NEVER** commit API keys, secrets, or credentials
+- Validate all user inputs with Zod schemas
+- Auth middleware required on all API routes
+- Never log SQLite encryption keys
+- Sanitize user content (dompurify for HTML)
+- **Public upstream OAuth identifiers** (Gemini / Antigravity / Windsurf-style client_id/secret + Firebase Web keys extracted from public CLIs): use `resolvePublicCred()` from `open-sse/utils/publicCreds.ts`, **never** as string literals. Full pattern in `docs/security/PUBLIC_CREDS.md`.
+- **Error responses** (HTTP / SSE / executor / MCP): use `buildErrorBody()` or `sanitizeErrorMessage()` from `open-sse/utils/error.ts`, **never** put raw `err.stack` / `err.message` in a Response body. Full pattern in `docs/security/ERROR_SANITIZATION.md`.
+- **`exec()` / `spawn()` with runtime values**: pass via the `env` option, **never** string-interpolate paths/values into the script body. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.
+- Prefer secure-by-default libraries when available — see [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) for the curated list (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink, etc.).
+
+---
+
+## Architecture
+
+### Data Layer (`src/lib/db/`)
+
+All persistence uses SQLite through **95 domain-specific modules** in `src/lib/db/`. Top modules:
+
+- Core: `core.ts`, `migrationRunner.ts`, `encryption.ts`, `stateReset.ts`
+- Providers / catalog: `providers.ts`, `models.ts`, `providerLimits.ts`, `compressionAnalytics.ts`
+- Routing: `combos.ts`, `modelComboMappings.ts`, `domainState.ts`, `commandCodeAuth.ts`
+- Auth: `apiKeys.ts`, `secrets.ts`, `registeredKeys.ts`, `sessionAccountAffinity.ts`
+- Usage / billing: `quotaSnapshots.ts`, `creditBalance.ts`, `usage*.ts`, `compressionCacheStats.ts`
+- Storage: `backup.ts`, `cleanup.ts`, `jsonMigration.ts`, `healthCheck.ts`, `databaseSettings.ts`
+- Extension modules: `evals.ts`, `webhooks.ts`, `reasoningCache.ts`, `readCache.ts`, `tierConfig.ts`, `compressionCombos.ts`, `compressionScheduler.ts`, `batches.ts`, `files.ts`, `syncTokens.ts`, `proxies.ts`, `oneproxy.ts`, `upstreamProxy.ts`, `versionManager.ts`, `cliToolState.ts`, `prompts.ts`, `detailedLogs.ts`, `contextHandoffs.ts`, `compression.ts`, `stats.ts`
+
+Live count: `ls src/lib/db/*.ts | wc -l` (currently 95). Drift detection: `npm run check:docs-counts`.
+Schema migrations live in `db/migrations/` (**110 files** as of v3.8.43) and run via `migrationRunner.ts`.
+`src/lib/localDb.ts` is a **re-export layer only** — never add logic there.
+
+#### DB Internals
+
+- **`core.ts`**: `getDbInstance()` returns a singleton `better-sqlite3` instance with WAL
+  journaling. `SCHEMA_SQL` defines **17 base tables** (verify with `grep -c "CREATE TABLE" src/lib/db/core.ts` minus 1 for the bookkeeping `_omniroute_migrations` table). Helpers: `rowToCamel`, `encryptConnectionFields`.
+- **`migrationRunner.ts`**: Applies versioned SQL files from `db/migrations/` inside transactions.
+  Tracks applied migrations in `_omniroute_migrations` table.
+- **Migrations**: 110 files (`001_initial_schema.sql` → `110_*.sql`).
+  Each migration is idempotent and runs in a transaction. Live count: `ls src/lib/db/migrations/*.sql | wc -l`.
+- **Domain modules** import `getDbInstance()` from `core.ts` for all CRUD operations.
+  Each module owns a specific table/set of tables (e.g., `providers.ts` → `provider_connections`,
+  `combos.ts` → `combos`). Encryption helpers protect sensitive fields at rest.
+- **`localDb.ts`** re-exports all domain modules — consumers import from here for convenience.
+
+### API Route Layer (`src/app/api/v1/`)
+
+Next.js App Router routes — each follows a consistent pattern:
+
+```
+Route → CORS preflight → Body validation (Zod) → Optional auth (extractApiKey/isValidApiKey)
+  → API key policy enforcement (enforceApiKeyPolicy) → Handler delegation (open-sse)
+```
+
+| Route                           | Handler                   | Notes                                                         |
+| ------------------------------- | ------------------------- | ------------------------------------------------------------- |
+| `chat/completions/route.ts`     | `handleChat()`            | + prompt injection guard (clones request)                     |
+| `responses/route.ts`            | `handleChat()` (unified)  | Responses API format                                          |
+| `embeddings/route.ts`           | `handleEmbedding()`       | Model listing + creation                                      |
+| `images/generations/route.ts`   | `handleImageGeneration()` | Model listing + creation                                      |
+| `audio/transcriptions/route.ts` | audio handler             | Multipart form data                                           |
+| `audio/speech/route.ts`         | TTS handler               | Binary audio response                                         |
+| `videos/generations/route.ts`   | video handler             | ComfyUI/SD WebUI                                              |
+| `music/generations/route.ts`    | music handler             | ComfyUI workflows                                             |
+| `moderations/route.ts`          | moderation handler        | Content safety                                                |
+| `rerank/route.ts`               | rerank handler            | Document relevance                                            |
+| `search/route.ts`               | search handler            | Web search (12 providers per `open-sse/handlers/search.ts:6`) |
+
+**No global Next.js middleware file** — interception is route-specific. Auth is optional
+(controlled by `REQUIRE_API_KEY` env). Prompt injection guard is unique to chat completions.
+
+### Request Pipeline (`open-sse/`)
+
+The `open-sse/` workspace is the core streaming engine. Full request flow:
+
+```
+Client Request
+  → src/app/api/v1/.../route.ts (Next.js route)
+    → open-sse/handlers/chatCore.ts::handleChatCore()
+      → Semantic/signature cache check
+      → Rate limit check (rateLimitManager)
+      → Combo routing? → open-sse/services/combo.ts::handleComboChat()
+        → resolveComboTargets() → ordered ResolvedComboTarget[]
+        → For each target: handleSingleModel() (wraps chatCore)
+      → translateRequest() (open-sse/translator/)
+        → Convert source format (e.g., OpenAI) → target format (e.g., Claude)
+      → getExecutor() → provider-specific executor instance
+        → executor.execute() (BaseExecutor → DefaultExecutor or provider-specific)
+          → buildUrl() + buildHeaders() + transformRequest()
+          → fetch() to upstream provider
+          → Retry logic with exponential backoff
+      → Response translation back to client format
+      → If Responses API: responsesTransformer.ts TransformStream
+  → SSE stream or JSON response to client
+```
+
+**Handlers** (`open-sse/handlers/`): `chatCore.ts`, `responsesHandler.ts`, `embeddings.ts`,
+`imageGeneration.ts`, `videoGeneration.ts`, `musicGeneration.ts`, `audioSpeech.ts`,
+`audioTranscription.ts`, `moderations.ts`, `rerank.ts`, `search.ts`.
+
+**Upstream headers**: merged after default auth; same header name replaces executor value.
+**T5 intra-family fallback** recomputes headers using only the fallback model id.
+Forbidden header names: `src/shared/constants/upstreamHeaders.ts` — keep sanitize,
+Zod schemas, and unit tests aligned when editing.
+
+### Provider Categories
+
+- **Free** (2): Qoder AI, Kiro AI
+- **OAuth** (13): Claude Code, Antigravity, Codex, GitHub Copilot, Cursor, Kimi Coding, Kilo Code, Cline, Kiro, Qoder, Gemini, Windsurf (v3.8), GitLab Duo (v3.8)
+- **API Key** (120+): OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Perplexity,
+  Together, Fireworks, Cerebras, Cohere, NVIDIA, Nebius, SiliconFlow, Hyperbolic,
+  HuggingFace, OpenRouter, Vertex AI, Cloudflare AI, Scaleway, AI/ML API, Pollinations,
+  Puter, Longcat, Alibaba, Kimi, Minimax, Blackbox, Synthetic, Kilo Gateway,
+  Z.AI, GLM, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld,
+  NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper, Brave, Exa,
+  Tavily, OpenCode Zen/Go, Bailian Coding Plan, DeepInfra, Vercel AI Gateway,
+  Lambda AI, SambaNova, nScale, OVHcloud AI, Baseten, PublicAI, Moonshot AI,
+  Meta Llama API, v0 (Vercel), Morph, Featherless AI, FriendliAI, LlamaGate,
+  Galadriel, Weights & Biases Inference, Volcengine, AI21 Labs, Venice.ai,
+  Codestral, Upstage, Maritalk, Xiaomi MiMo, Inference.net, NanoGPT, Predibase,
+  Bytez, Heroku AI, Databricks, Snowflake Cortex, GigaChat (Sber), CrofAI,
+  AgentRouter, ChatGPT Web, Baidu Qianfan, AWS Polly, RunwayML, GitLab Duo,
+  Amazon Q, Empower, Poe, and many more.
+- **Self-Hosted** (8+): LM Studio, vLLM, Lemonade, Llamafile, Triton, Docker Model Runner, Xinference, Oobabooga
+- **Custom**: OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) prefixes
+
+Providers are registered in `src/shared/constants/providers.ts` with Zod validation at module load.
+
+### Executors (`open-sse/executors/`)
+
+Provider-specific request executors: `base.ts`, `default.ts`, `cursor.ts`, `codex.ts`,
+`antigravity.ts`, `github.ts`, `kiro.ts`, `qoder.ts`, `vertex.ts`,
+`cloudflare-ai.ts`, `opencode.ts`, `pollinations.ts`, `puter.ts`.
+
+#### Executor Internals
+
+- **`base.ts`** (`BaseExecutor`): Abstract base with `buildUrl()`, `buildHeaders()`,
+  `transformRequest()`, retry logic (exponential backoff), and `execute()`. Subclasses
+  override URL/header/transform methods for provider-specific behavior.
+- **`default.ts`** (`DefaultExecutor extends BaseExecutor`): Handles most OpenAI-compatible
+  providers. Reads provider config from `providerRegistry.ts` to resolve base URL, auth
+  header format, and request transformations.
+- **`getExecutor()`** (`executors/index.ts`): Factory that returns the correct executor
+  instance based on provider ID. Provider-specific executors (Cursor, Codex, Vertex, etc.)
+  override only what differs from the default.
+
+### Translator (`open-sse/translator/`)
+
+Translates between API formats (OpenAI-format ↔ Anthropic, Gemini, etc.).
+Includes request/response translators with helpers for image handling.
+
+#### Translator Internals
+
+- **`translator/index.ts`**: Exports `translateRequest()` and format constants. Called by
+  `chatCore.ts` before executor dispatch.
+- **Flow**: `translateRequest(body, sourceFormat, targetFormat)` → detects source format
+  (OpenAI, Anthropic, Gemini) → applies the matching translator module → returns
+  transformed body ready for the target provider.
+- **Response translation** runs in reverse after upstream response, converting back to
+  the client's expected format.
+
+### Transformer (`open-sse/transformer/`)
+
+`responsesTransformer.ts` — transforms Responses API format to/from Chat Completions format.
+
+#### Transformer Internals
+
+- **`createResponsesApiTransformStream()`**: Returns a `TransformStream` that converts
+  Chat Completions SSE chunks (`data: {"choices":[...]}`) into Responses API SSE events
+  (`response.output_item.added`, `response.output_text.delta`, etc.).
+- Used when the client sends a Responses API request: the request is internally converted
+  to Chat Completions format, dispatched normally, and the response is piped through this
+  transform stream before reaching the client.
+
+### Services (`open-sse/services/`)
+
+134 service modules in `open-sse/services/` (top-level only; more including sub-dirs like `autoCombo/` and `compression/`). Refresh: `ls open-sse/services/*.ts | wc -l`. Key modules:
+`combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`,
+`rateLimitManager.ts`, `accountFallback.ts`, `sessionManager.ts`, `wildcardRouter.ts`,
+`autoCombo/`, `intentClassifier.ts`, `taskAwareRouter.ts`, `thinkingBudget.ts`,
+`contextManager.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`,
+`emergencyFallback.ts`, `workflowFSM.ts`, `backgroundTaskDetector.ts`, `ipFilter.ts`,
+`signatureCache.ts`, `volumeDetector.ts`, `contextHandoff.ts`, `compression/` (prompt
+compression pipeline), and more.
+
+#### Prompt Compression Pipeline (`compression/`)
+
+Modular prompt compression that runs proactively before the existing reactive context manager.
+
+- **`strategySelector.ts`**: Selects compression mode based on config, compression combo assignments,
+  combo overrides, auto-trigger thresholds, and defaults. Priority: assigned compression combo >
+  combo override > auto-trigger > default mode > off.
+- **`lite.ts`**: 5 lite-mode techniques: `collapseWhitespace`, `dedupSystemPrompt`,
+  `compressToolResults`, `removeRedundantContent`, `replaceImageUrls`. Target: 10-15% savings at
+  <1ms latency.
+- **`caveman.ts` / `cavemanRules.ts`**: Caveman-style semantic condensation backed by built-in
+  rules plus file-loaded language packs under `compression/rules/`.
+- **`engines/rtk/`**: Rule-based terminal/tool-output compression inspired by RTK patterns. Detects
+  command output classes, applies JSON filter packs, deduplicates repeated lines, strips ANSI/code
+  noise, and preserves errors/actionable context. The RTK JSON DSL supports replace,
+  match-output short-circuit, strip/keep, per-line truncation, head/tail/max-line truncation,
+  inline tests, trust-gated project/global custom filters, and optional redacted raw-output
+  retention for authenticated recovery.
+- **`engines/registry.ts`**: Registers engines (`caveman`, `rtk`) and powers stacked pipelines.
+- **`stats.ts`**: Per-request compression stats tracking (original tokens, compressed tokens,
+  savings %, techniques used, engine breakdown, compression combo id).
+- **`types.ts`**: `CompressionMode` (off/lite/standard/aggressive/ultra/rtk/stacked),
+  `CompressionConfig`, `CompressionStats`, `CompressionResult`.
+- DB settings in `src/lib/db/compression.ts`, compression combos in
+  `src/lib/db/compressionCombos.ts`, API routes under `src/app/api/settings/compression/`,
+  `src/app/api/context/*`, and preview/language-pack routes under `src/app/api/compression/*`.
+
+#### Combo Routing Engine (`combo.ts`)
+
+- **`handleComboChat()`**: Entry point for combo-routed requests. Receives the combo config
+  and iterates through targets in order until one succeeds or all fail.
+- **`resolveComboTargets()`**: Expands a combo configuration into an ordered array of
+  `ResolvedComboTarget[]`, each specifying provider + model + account + credentials.
+- **Strategies** (17): priority, weighted, fill-first, round-robin, P2C, random, least-used, reset-aware (v3.8),
+  reset-window, cost-optimized, strict-random, auto, lkgp, context-optimized, context-relay, headroom, fusion. Source: `ROUTING_STRATEGY_VALUES` in `src/shared/constants/routingStrategies.ts`.
+- Each target calls **`handleSingleModel()`** which wraps `handleChatCore()` with
+  per-target error handling and circuit breaker checks.
+
+### Domain Layer (`src/domain/`)
+
+Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`,
+`degradation.ts`, `fallbackPolicy.ts`, `lockoutPolicy.ts`, `modelAvailability.ts`,
+`providerExpiration.ts`, `quotaCache.ts`, `responses.ts`, `configAudit.ts`.
+
+### MCP Server (`open-sse/mcp-server/`)
+
+**104 tools** total (`TOTAL_MCP_TOOL_COUNT`, `open-sse/mcp-server/server.ts`): a 42-entry base registry (`MCP_TOOLS` in `schemas/tools.ts`, bundling the core / cache / compression / 1proxy / advanced tools) **plus** standalone module sets — memory (3), skill (4), agentSkill (3), pool (6), gamification (8), plugin (8), notion (6), obsidian (22). 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (31 scopes — see `OMNIROUTE_MCP_SCOPES`), Zod schemas. See [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md).
+
+**Core tools** (20): get_health, list_combos, get_combo_metrics, switch_combo, check_quota,
+route_request, cost_report, list_models_catalog, web_search, simulate_route, set_budget_guard,
+set_routing_strategy, set_resilience_profile, test_combo, get_provider_metrics,
+best_combo_for_task, explain_route, get_session_snapshot, db_health_check, sync_pricing.
+
+**Cache tools** (2): cache_stats, cache_flush.
+
+**Compression tools** (5): compression_status, compression_configure, set_compression_engine,
+list_compression_combos, compression_combo_stats.
+
+**1proxy tools** (3): oneproxy_fetch, oneproxy_rotate, oneproxy_stats.
+
+**Memory tools** (3): memory_search, memory_add, memory_clear.
+
+**Skill tools** (4): skills_list, skills_enable, skills_execute, skills_executions.
+
+**Agent-skill tools** (3): A2A skill discovery / invocation bridges.
+
+**Gamification tools** (8): levels, badges, leaderboard, and community-federation queries.
+
+**Plugin tools** (8): plugin marketplace listing, install/enable/disable, and runtime inspection.
+
+**Notion tools** (6) + **Obsidian tools** (22): knowledge-base read/write integrations (the largest tool family — vault search, note CRUD, WebDAV-backed file ops).
+
+#### MCP Internals
+
+- **Tool registration**: Each tool is an object with `{ name, description, inputSchema: ZodSchema,
+handler: async (args) => {...} }`. Zod validates inputs before the handler fires.
+- **`createMcpServer()`** and **`startMcpStdio()`** exported from `mcp-server/index.ts`.
+  `createMcpServer()` wires all tool sets; `startMcpStdio()` launches the stdio transport.
+- **Transports**: stdio (CLI `omniroute --mcp`), SSE (`/api/mcp/sse`), Streamable HTTP
+  (`/api/mcp/stream`). All share the same tool/scope engine.
+- **Scopes** (30): Control which tool categories an API key can access. Enforcement happens
+  before handler dispatch.
+- **Audit**: Every tool invocation is logged to SQLite (`mcp_audit` table) with tool name,
+  args, success/failure, API key attribution, and timestamp.
+
+### A2A Server (`src/lib/a2a/`)
+
+JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup.
+Agent Card at `/.well-known/agent.json`.
+Skills (6): `smartRouting.ts`, `quotaManagement.ts`, `providerDiscovery.ts`, `costAnalysis.ts`, `healthReport.ts`, `listCapabilities.ts`.
+
+#### A2A Internals
+
+- **`taskManager.ts`**: State machine lifecycle for tasks: `submitted → working →
+completed | failed | canceled`. Tasks have TTL and are cleaned up automatically.
+- **JSON-RPC methods**: `message/send` (sync), `message/stream` (SSE), `tasks/get`,
+  `tasks/cancel`. Dispatched via `POST /a2a`.
+- **Skills**: Registered in a DB-backed registry. Each skill receives task context
+  (messages, metadata) and returns structured results. `quotaManagement.ts` summarizes
+  quota; `smartRouting.ts` recommends routing decisions.
+- **Agent Card**: `/.well-known/agent.json` exposes capabilities, skills, and metadata
+  for client auto-discovery.
+
+### ACP Module (`src/lib/acp/`)
+
+Agent Communication Protocol registry and manager.
+
+### Memory System (`src/lib/memory/`)
+
+Extraction, injection, retrieval, summarization, and store modules for persistent
+conversational memory across sessions.
+
+### Skills System (`src/lib/skills/`)
+
+Extensible skill framework: registry, executor, sandbox, built-in skills,
+custom skill support, interception, and injection.
+
+#### Skills Internals
+
+- **`registry.ts`**: DB-backed skill registration and discovery. Skills have metadata
+  (name, description, version, enabled status) stored in SQLite.
+- **`executor.ts`**: Execution engine with configurable timeout and retry logic.
+  Receives skill name + input, looks up the skill, runs it in the sandbox.
+- **`sandbox.ts`**: Isolation layer for custom (user-provided) skills. Limits resource
+  access and execution time.
+- **Built-in skills**: Ship with OmniRoute (e.g., quota management, routing). Located
+  alongside the registry.
+- **Interception/Injection**: Skills can intercept requests in the pipeline (pre/post
+  processing) or inject context into prompts.
+
+### Compliance (`src/lib/compliance/`)
+
+Policy index for compliance enforcement.
+
+### MITM Proxy (`src/mitm/`)
+
+MITM proxy capability with certificate management, DNS handling, and target routing.
+
+### Middleware (`src/middleware/`)
+
+Request middleware including `promptInjectionGuard.ts`.
+
+### Guardrails (`src/lib/guardrails/`)
+
+Hot-reloadable guardrails framework (3 built-in: pii-masker, prompt-injection, vision-bridge). Fail-open. The `pii-masker` guardrail is registered and runs on every request, but its data-mutating logic is **opt-in** and OFF by default — it only redacts when `PII_REDACTION_ENABLED` (request) / `PII_RESPONSE_SANITIZATION` (response + streaming) are enabled (both `defaultValue: "false"`); with them off, payloads pass through untouched. A request can additionally opt OUT of any guardrail via header (`x-omniroute-disabled-guardrails`). Never make PII default-on (Hard Rule #20). See [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md).
+
+### Cloud Agents (`src/lib/cloudAgent/`)
+
+`CloudAgentBase` abstract class + 3 agents (codex-cloud, devin, jules). Tasks persisted in `cloud_agent_tasks`; management auth required. See [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md).
+
+### Evals (`src/lib/evals/`)
+
+Generic eval framework: `evalRunner.ts`, `runtime.ts`. Targets: combo / model / suite-default. See [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md).
+
+### Webhooks (`src/lib/webhookDispatcher.ts`)
+
+HMAC-signed delivery, exponential backoff, auto-disable after 10 failures. 7 event types. See [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md).
+
+### Authorization Pipeline (`src/server/authz/`)
+
+`classify → policies → enforce`. 3 route classes (PUBLIC / CLIENT_API / MANAGEMENT). See [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md).
+
+### Reasoning Replay (`src/lib/db/reasoningCache.ts` + `open-sse/services/reasoningCache.ts`)
+
+Hybrid in-memory + SQLite cache for `reasoning_content`. Re-injects on multi-turn for strict providers (DeepSeek V4, Kimi K2, Qwen-Thinking, GLM, xiaomi-mimo). See [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md).
+
+### Tunnels (`src/lib/{cloudflaredTunnel,ngrokTunnel}.ts` + `src/app/api/tunnels/`)
+
+Cloudflare Quick/Named, ngrok, Tailscale Funnel. See [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md).
+
+### Adding a New Provider
+
+1. Register in `src/shared/constants/providers.ts`
+2. Add executor in `open-sse/executors/` (if custom logic needed)
+3. Add translator in `open-sse/translator/` (if non-OpenAI format)
+4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` (if OAuth-based)
+5. Add models in `open-sse/config/providerRegistry.ts`
+
+---
+
+## Subdirectory AGENTS.md Files
+
+- **[`src/lib/db/AGENTS.md`](src/lib/db/AGENTS.md)** — SQLite persistence, domain modules, migrations
+- **[`open-sse/services/AGENTS.md`](open-sse/services/AGENTS.md)** — Routing engine, combo resolution, strategy selection
+
+## Reference Documentation (docs/)
+
+For any non-trivial change, read the matching deep-dive first:
+
+| Area                                       | Doc                                                                                                             |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| Repo navigation                            | [`docs/architecture/REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md)                                    |
+| Architecture                               | [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)                                        |
+| Engineering reference                      | [`docs/architecture/CODEBASE_DOCUMENTATION.md`](docs/architecture/CODEBASE_DOCUMENTATION.md)                    |
+| Auto-Combo (12-factor, 18 strategies)      | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md)                                                      |
+| Resilience (3 layers)                      | [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md)                                |
+| Skills                                     | [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md)                                                        |
+| Memory                                     | [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md)                                                        |
+| Cloud agents                               | [`docs/frameworks/CLOUD_AGENT.md`](docs/frameworks/CLOUD_AGENT.md)                                              |
+| Guardrails                                 | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md)                                                    |
+| Evals                                      | [`docs/frameworks/EVALS.md`](docs/frameworks/EVALS.md)                                                          |
+| Compliance                                 | [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md)                                                    |
+| Webhooks                                   | [`docs/frameworks/WEBHOOKS.md`](docs/frameworks/WEBHOOKS.md)                                                    |
+| Authz                                      | [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md)                                          |
+| Stealth                                    | [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md)                                              |
+| Reasoning replay                           | [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md)                                          |
+| Agent protocols (A2A / ACP / Cloud)        | [`docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)                          |
+| MCP server                                 | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md)                                                |
+| A2A server                                 | [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md)                                                |
+| API reference                              | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) + [`docs/openapi.yaml`](docs/openapi.yaml) |
+| Provider catalog (auto-generated)          | [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)                                  |
+| Tunnels                                    | [`docs/ops/TUNNELS_GUIDE.md`](docs/ops/TUNNELS_GUIDE.md)                                                        |
+| Electron desktop                           | [`docs/guides/ELECTRON_GUIDE.md`](docs/guides/ELECTRON_GUIDE.md)                                                |
+| Release flow                               | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md)                                                |
+| Quality gates (35 gates, allowlist policy) | [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md)                                      |
+| Cluster opt-in profiles (memory, bifrost)  | [`docs/architecture/cluster-decisions.md`](docs/architecture/cluster-decisions.md)                              |
+
+---
+
+## Fork / Upstream Workflow
+
+This repository is a fork of `diegosouzapw/OmniRoute`. Keep fork-only operational
+changes (for example GHCR image publishing, personal deployment workflows, or local
+automation) out of upstream contribution PRs.
+
+When preparing a PR for upstream, always start the work branch from the upstream
+**default branch** — the active `release/vX.Y.Z` line (today `release/v3.8.49`).
+Never branch from `main`: `main` only receives release squash-merges, so a branch
+cut there is weeks behind and produces conflict-heavy PRs
+(see `CONTRIBUTING.md` and `docs/ops/BRANCHING_MODEL.md`):
 
 ```bash
 git fetch upstream
-git switch -c <branch-name> upstream/<default-branch>
+# the default branch is the active release line, e.g. release/v3.8.49
+git switch -c <branch-name> upstream/release/vX.Y.Z
 ```
 
-Target that same release branch in the pull request. Stage only the intended files, run the
-focused checks, and use a Conventional Commit message (for example, `docs: slim AGENTS.md`).
+Only cherry-pick or reapply the changes intended for the upstream PR.
 
-## Reference documentation
+---
 
-Use the source of truth for the area you are changing:
+## Review Focus
 
-| Area                                   | Reference                                                                                                                                                                                                                                              |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Repository navigation and architecture | [`docs/architecture/REPOSITORY_MAP.md`](docs/architecture/REPOSITORY_MAP.md), [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md)                                                                                                 |
-| API and providers                      | [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md), [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md), [`docs/openapi.yaml`](docs/openapi.yaml)                                                         |
-| Routing, resilience, and reasoning     | [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md), [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md), [`docs/routing/REASONING_REPLAY.md`](docs/routing/REASONING_REPLAY.md)                                   |
-| Security                               | [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md), [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md), [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md)                                                         |
-| Platform features                      | [`docs/frameworks/MCP-SERVER.md`](docs/frameworks/MCP-SERVER.md), [`docs/frameworks/A2A-SERVER.md`](docs/frameworks/A2A-SERVER.md), [`docs/frameworks/SKILLS.md`](docs/frameworks/SKILLS.md), [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md) |
-| Releases and quality                   | [`docs/ops/RELEASE_CHECKLIST.md`](docs/ops/RELEASE_CHECKLIST.md), [`docs/architecture/QUALITY_GATES.md`](docs/architecture/QUALITY_GATES.md)                                                                                                           |
+- **DB ops** go through `src/lib/db/` modules, never raw SQL in routes
+- **Provider requests** flow through `open-sse/handlers/`
+- **MCP/A2A pages** are tabs inside `/dashboard/endpoint`, not standalone routes
+- **No memory leaks** in SSE streams (abort signals, cleanup)
+- **Rate limit headers** must be parsed correctly
+- All API inputs validated with **Zod schemas**
+- **Provider constants** validated at module load via Zod (`src/shared/validation/providerSchema.ts`)
+- **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts`
+- **Memory/Skills** are cross-cutting: affect MCP tools, request pipeline, and A2A skills
+- **⛔ NEVER close a contributor's PR** after using their code — always merge via GitHub so they get credit. See `.agents/workflows/review-prs.md` for full policy.

Dockerfile

@@ -236,6 +236,11 @@ FROM runner-base AS runner-cli
 # runner-base runs.
 USER root
 
+# The CLI image can use the internal ChatGPT Web (Codex) Chromium sidecar over
+# CDP without installing a second browser in this container.
+COPY --from=builder /app/node_modules/playwright-core ./node_modules/playwright-core
+COPY --from=builder /app/node_modules/playwright ./node_modules/playwright
+
 # Install system dependencies required by openclaw (git+ssh references).
 RUN --mount=type=cache,id=apt-cache,target=/var/cache/apt,sharing=locked \
   --mount=type=cache,id=apt-lists,target=/var/lib/apt/lists,sharing=locked \

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,26 @@
+# Third-Party Notices
+
+## codex-chatgpt-web
+
+Parts of `open-sse/vendor/codex-chatgpt-web/` are adapted from
+[`miuuyy/codex-chatgpt-web`](https://github.com/miuuyy/codex-chatgpt-web), commit
+`55592fca0ba19a27f1b769cec8fff61ff340a785`.
+
+MIT License
+
+Copyright (c) 2026 codex-chatgpt-web contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
+OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

bin/chatgpt-web-codex-mcp.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, "..");
+
+export function resolveChatGptWebCodexMcpEntry(rootDir = root, exists = existsSync) {
+  const candidates = [
+    join(
+      rootDir,
+      "dist",
+      "open-sse",
+      "vendor",
+      "codex-chatgpt-web",
+      "adapters",
+      "chatgpt-web",
+      "mcp-server.js"
+    ),
+    join(
+      rootDir,
+      "open-sse",
+      "vendor",
+      "codex-chatgpt-web",
+      "adapters",
+      "chatgpt-web",
+      "mcp-server.ts"
+    ),
+  ];
+  return candidates.find((candidate) => exists(candidate)) ?? null;
+}
+
+export async function startChatGptWebCodexMcp(args = process.argv.slice(2), rootDir = root) {
+  const socketIndex = args.indexOf("--broker-socket");
+  const brokerSocketPath = socketIndex >= 0 ? args[socketIndex + 1] : undefined;
+  if (!brokerSocketPath) throw new Error("--broker-socket is required");
+  const entry = resolveChatGptWebCodexMcpEntry(rootDir);
+  if (!entry) throw new Error("ChatGPT Web (Codex) MCP entrypoint was not found");
+  if (entry.endsWith(".ts")) {
+    const { register } = await import("node:module");
+    register("tsx/esm", pathToFileURL(`${rootDir}/`));
+  }
+  const module = await import(pathToFileURL(entry).href);
+  await module.runChatGptMcpServer({ brokerSocketPath });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  startChatGptWebCodexMcp().catch((error) => {
+    console.error(
+      `ChatGPT Web (Codex) MCP konnte nicht gestartet werden: ${error?.message || error}`
+    );
+    process.exit(1);
+  });
+}

changelog.d/features/5696-layer-a-capability-filter.md

@@ -1 +0,0 @@
-- **feat(core):** add Layer A capability filter at router (#5696)

changelog.d/features/7786-management-auth-terminology-docs.md

@@ -1 +0,0 @@
-- **docs:** add management authentication terminology guide ([#7786](https://github.com/diegosouzapw/OmniRoute/issues/7786))

changelog.d/features/9247-provider-detail-connections.md

@@ -1 +0,0 @@
-- **feat(providers):** filter provider detail connections server-side while preserving full-page search and pagination. (thanks @RobertsXML)

changelog.d/fixes/8430-fix.plan.md

@@ -1,3 +0,0 @@
-- fix(vision-bridge): describe-model no longer returns unreachable "openai/gpt-4o-mini" when every vision-capable provider is unreachable on the instance — returns null instead and surfaces a clear error (#8430)
-- fix(vision-bridge): validate fixedModel against usable credentials before short-circuiting in getBestVisionModel, so the default "openai/gpt-4o-mini" is not unconditionally selected when no OpenAI connection exists (#8430)
-- fix(vision-bridge): in the combo describe path, replace raw images with an error text stub when all describe attempts fail, instead of forwarding images to a confirmed non-vision backend that would reject them with an opaque serde error (#8430)

changelog.d/fixes/8522-fix.plan.md

@@ -1 +0,0 @@
-- fix(quality): add base-relative file-size check so inherited drift does not red innocent PRs (#8522)

changelog.d/fixes/8653-fix.plan.md

@@ -1 +0,0 @@
-- fix(executor): guard claude/anthropic buildHeaders against empty credentials and extend dual-Bearer parity for third-party baseUrls (#8653)

changelog.d/fixes/8843-provider-media-body-limits.md

@@ -1 +0,0 @@
-- **fix(api):** Let image and video providers enforce their own request-size limits instead of rejecting media payloads at OmniRoute's 10 MB global default ([#8843](https://github.com/diegosouzapw/OmniRoute/pull/8843)) — thanks @artickc

changelog.d/fixes/8853-fix.plan.md

@@ -1 +0,0 @@
-- fix(proxy-health): include credentials in proxy health check URLs (#8853)

changelog.d/fixes/8909-vertex-claude-rawpredict-streaming.md

@@ -0,0 +1 @@
+- **fix(executors):** Vertex AI now routes Claude models through the native Anthropic `rawPredict` endpoint instead of the generic OpenAI-compatible partner endpoint, and synthesizes a real streaming response so Claude-via-Vertex works with `stream: true` ([#8909](https://github.com/diegosouzapw/OmniRoute/pull/8909)) — thanks @wgordon17

changelog.d/fixes/8950-fix.plan.md

@@ -1 +0,0 @@
-- fix(auth): setting first dashboard login password no longer fails with HTTP 400 PASSWORD_REQUIRED (#8950)

changelog.d/fixes/8956-fix.plan.md

@@ -1 +0,0 @@
-- fix(auto-update): skip synthetic Next.js standalone package.json without `name` field in resolveProjectRoot (#8956)

changelog.d/fixes/8971-fix.plan.md

@@ -1 +0,0 @@
-- fix(providers): copilot-m365-web enterprise turns send disconnectBehavior=continue (#8971)

changelog.d/fixes/9006-vertex-claude-catalog-dispatch.md

@@ -0,0 +1,14 @@
+- **fix(sse):** Claude reasoning-effort suffix ids (`-high`/`-low`/`-medium`/`-xhigh`) now strip
+  correctly on any provider serving a real Claude model, not just the direct Anthropic provider
+  ([#9006](https://github.com/diegosouzapw/OmniRoute/pull/9006))
+- **fix(sse):** the no-thinking (`no-think/`) catalog variant's provider-qualification bug — which
+  made it unusable outside the direct provider, both in the discovery catalog and the dashboard
+  playground — is fixed ([#9006](https://github.com/diegosouzapw/OmniRoute/pull/9006))
+- **fix(sse):** a single unrecognized model id on a Vertex connection no longer cools down every
+  other model on that connection for 2 minutes — Vertex 404s are now scoped to a per-model
+  lockout via `passthroughModels` instead of a connection-wide cooldown
+  ([#9006](https://github.com/diegosouzapw/OmniRoute/pull/9006))
+- **fix(sse):** Vertex `PERMISSION_DENIED` 403s are now disambiguated using Google's own
+  documented error format — a genuinely connection-wide cause (API disabled, project-level IAM
+  denial) still cools the whole connection, while a model-specific denial locks out only that
+  model ([#9006](https://github.com/diegosouzapw/OmniRoute/pull/9006))

changelog.d/fixes/9013-model-param-filter-save.md

@@ -0,0 +1 @@
+- **fix(dashboard):** model-level allowed/blocked param edits now persist when the compatibility popover is closed by clicking outside, and a failed save no longer clears the edit or reports success ([#9013](https://github.com/diegosouzapw/OmniRoute/pull/9013))

changelog.d/fixes/9022-stream-error-diagnostic.md

@@ -1 +0,0 @@
-- **fix(sse):** error-only streams now preserve sanitized executor diagnostics for operators without changing stream-readiness fallback classification ([#9022](https://github.com/diegosouzapw/OmniRoute/pull/9022)) — thanks @shixi-li

changelog.d/fixes/9033-fix.plan.md

@@ -1 +0,0 @@
-- fix(auth): IP blacklist now blocks on direct connections via trusted peer stamp and re-reads config without restart (#9033)

changelog.d/fixes/9053-claude-to-openai-max-passthrough.md

@@ -1 +0,0 @@
-- **fix(translator):** pass `output_config.effort="max"` through verbatim instead of unconditionally rewriting it to `xhigh`, so Anthropic → OpenAI-shape upstream calls reach `sanitizeReasoningEffortForProvider` with the carrier intact and providers that accept `max` literally (Ollama Cloud, opencode-go DeepSeek, Moonshot K3, native Claude) no longer 400 on `invalid reasoning value: 'xhigh'`. Regression guard: end-to-end test in `tests/unit/base-executor-sanitize-effort.test.ts`.

changelog.d/fixes/9064-fix-anthropic-code-execution-skills-beta.plan.md

@@ -1 +0,0 @@
-- fix(providers): anthropic strips code-execution/skills beta flag, causing container rejection (#9064)

changelog.d/fixes/9149-autosync-per-connection.md

@@ -1 +0,0 @@
-- **fix(dashboard):** the provider "Auto Sync" toggle now applies to every active connection and each connection gets its own Auto Sync toggle — previously only the lowest-priority connection was updated. ([#9149](https://github.com/diegosouzapw/OmniRoute/pull/9149))

changelog.d/fixes/9250-cli-compatible-provider-apply.md

@@ -1 +0,0 @@
-- **fix(cli-tools):** keep Apply enabled for active OpenAI-compatible and Anthropic-compatible providers without static catalog entries. (thanks @lazysaltyfish)

changelog.d/fixes/9253-translator-format-detection-2949.md

@@ -1 +0,0 @@
-- **fix(translator):** harden Claude format detection for relative message endpoints and kebab-case version metadata. (thanks @ervareza)

changelog.d/fixes/9276-fix.plan.md

@@ -1 +0,0 @@
-- fix(claude): remove unconditional "always" return in claudeClassifierCompat so normal chat requests are not swallowed (#9276)

changelog.d/fixes/9291-proxy-logs-egress-ip.md

@@ -1 +0,0 @@
-- **fix(db):** persist the account egress IP into `proxy_logs.egress_ip` (migration 134 + schema reconciler) so real traffic stays attributable to the actual node/IP even after restart — the egress IP was previously computed and logged but silently dropped from persistence ([#9291](https://github.com/diegosouzapw/OmniRoute/pull/9291)) — thanks @maxmad64bis

changelog.d/fixes/9297-fix.plan.md

@@ -1 +0,0 @@
-- fix(mcp): break circular import between googApiKeyAuth.ts and auth.ts to fix esbuild SyntaxError in MCP server bundle (#9297)

changelog.d/fixes/9320-fix.plan.md

@@ -1 +0,0 @@
-- fix(security): require auth for /v1/models when management auth is configured (#9320)

changelog.d/fixes/9338-kimi-web-k3-exhausted.md

@@ -1 +0,0 @@
-- fix(providers): map kimi-web/K3 to K2D5 scenario instead of OK Computer premium mode to fix resource_exhausted on non-subscriber accounts (#9338)

changelog.d/fixes/9343-bare-json-tool-calls.md

@@ -1 +0,0 @@
-- fix(security): require explicit tool envelope to prevent bare JSON from being promoted to real tool_calls (#9343)

changelog.d/fixes/9406-claude-web-429-test.md

@@ -1,2 +0,0 @@
-- fix(providers): treat claude-web 429 as unhealthy and forward upstream Retry-After header (#9406)
-- fix(providers): treat muse-spark-web 429 as unhealthy (#9406)

changelog.d/fixes/9407-gemini-web-false-positive.md

@@ -1 +0,0 @@
-- fix(providers): detect expired gemini-web sessions via ServiceLogin redirect and add testConnection override (#9407)

changelog.d/fixes/9408-claude-web-tool-use.md

@@ -1 +0,0 @@
-- fix(providers): add tool_use block handling to claude-web stream parser for OpenAI tool_calls projection (#9408)

changelog.d/fixes/9416-internal-provider-prefixes.md

@@ -1 +0,0 @@
-- fix(api): fall back to slugified provider name when prefix is empty to prevent UUID leak in /v1/models (#9416)

changelog.d/fixes/9447-bare-model-codex-preemption.md

@@ -1 +0,0 @@
-- **fix(routing):** a Codex-native bare model id (`gpt-5.5`, the `gpt-5.6-sol`/`terra`/`luna` tiers) no longer routes to `codex` when no codex connection is active — an OpenAI-only install was getting `no active credentials for provider: codex` for a model OpenAI serves, and an install whose codex connection was merely inactive failed the same way. With codex active the Codex preference still wins over OpenAI, and ids only codex catalogs (`codex-auto-review`) still resolve to codex with no connection at all ([#9447](https://github.com/diegosouzapw/OmniRoute/pull/9447))

changelog.d/maintenance/9425-dependabot-ioredis-major.md

@@ -1 +0,0 @@
-- **chore(ci):** stopped dependabot from grouping `ioredis` majors with routine production bumps — the package is resolved through a dynamic import in the distributed quota store, so a breaking major passes build, typecheck and both test suites and only surfaces at runtime for operators running Redis-backed quota ([#9425](https://github.com/diegosouzapw/OmniRoute/pull/9425))

changelog.d/maintenance/base-reds-v3850-golden-and-any.md

@@ -1 +0,0 @@
-- **chore(tests):** cleared two base-reds sitting on `release/v3.8.50` itself, both of which turned every open PR red the moment it merged the release. `tests/snapshots/provider/translate-path.json` was stale: #9064 added the `code-execution-2025-08-25` and `skills-2025-10-02` beta flags to the Anthropic header without regenerating the golden, so `provider-translate-path-golden` failed on the bare release tip (2 pass / 1 fail with zero PRs boarded). And `tests/unit/v1-models-auth-leak-9320.test.ts:83` shipped a `(k: any)` in a file new enough that `config/quality/eslint-suppressions.json` does not cover it — with `@typescript-eslint/no-explicit-any` set to `error` under `tests/`, that single cast failed the `No new ESLint warnings` gate repo-wide. Same class in `tests/unit/issue-9407-gemini-web-validation-false-positive.test.ts:50` (`(executor as any).testConnection`), which entered at `f1ea77fd04` — `testConnection` is a declared public method on `GeminiWebExecutor`, so that cast was redundant too. Regenerating the snapshot and dropping both casts restores the gates.

changelog.d/maintenance/basereds-eslint-baseline-tighten.md

@@ -1 +0,0 @@
-- fix(quality): tighten eslintWarnings baseline 5000->0 to match the gate's suppressions-applied measurement (unblocks require-tighten on every code PR)

compression-core/.gitignore

@@ -0,0 +1,2 @@
+/target
+Cargo.lock

compression-core/Cargo.toml

@@ -0,0 +1,27 @@
+[workspace]
+resolver = "2"
+members = [
+    "crates/core-api",
+    "crates/tokenizer",
+    "crates/tests",
+    "crates/bench",
+    "crates/ffi",
+]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/Egorich-print/OmniRoute"
+
+[workspace.dependencies]
+core-api = { path = "crates/core-api" }
+tokenizer = { path = "crates/tokenizer" }
+tiktoken-rs = "0.6"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+thiserror = "2"
+
+[profile.release]
+lto = true
+codegen-units = 1

compression-core/README.md

@@ -0,0 +1,61 @@
+# compression-core
+
+Standalone Rust core for AI context optimization — tokenization, compression,
+hashing, translation primitives. Independent OSS library usable by OmniRoute,
+OpenCode, Cline, Roo, and any AI proxy. No OmniRoute imports anywhere.
+
+## Layout
+
+```
+compression-core/
+├── Cargo.toml            # workspace
+├── crates/
+│   ├── core-api/         # stable public API (traits + types) — no host deps
+│   ├── tokenizer/        # tiktoken (cl100k_base, o200k_base) — PORTED
+│   ├── tests/            # golden tests against fixtures/expected/
+│   ├── bench/            # criterion benchmarks
+│   └── ffi/              # N-API adapter (integration phase)
+├── fixtures/
+│   ├── tokenizer/        # JS-generated token counts (13 samples)
+│   └── expected/         # manifests
+└── scripts/
+    ├── generate-fixtures.ts  # JS reference output (source of truth)
+    └── verify-golden.ts      # regen + cargo test
+```
+
+## Porting order (per design)
+
+1. tiktoken (done — golden 100%)
+2. ionizer
+3. headroom
+4. caveman
+5. RTK (last — biggest, requires proven harness)
+
+## Golden pipeline
+
+```text
+fixtures → JS implementation → expected.json → Rust → assert_eq!
+```
+
+`node scripts/verify-golden.ts` regenerates fixtures from the current JS code
+and runs `cargo test -p compression-tests`. Until 100% match, JS stays in prod.
+
+## Measured baseline
+
+| Impl | Input | Cost |
+|---|---|---|
+| JS js-tiktoken (cl100k) | 230K chars | 37.9 ms |
+| Rust tiktoken-rs (cl100k) | ~440K chars | 21.4 ms |
+
+Per-char Rust is ~3x faster; golden output is byte-identical on all fixtures.
+
+## Status
+
+- [x] workspace + stable API (`core-api`)
+- [x] tokenizer port + golden tests (100% match)
+- [x] bench harness (criterion)
+- [ ] ionizer
+- [ ] headroom
+- [ ] caveman
+- [ ] RTK
+- [ ] N-API adapter

compression-core/crates/bench/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "compression-bench"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[dependencies]
+core-api = { workspace = true }
+tokenizer = { workspace = true }
+
+[dev-dependencies]
+criterion = "0.5"
+
+[[bench]]
+name = "tokenizer"
+harness = false

compression-core/crates/bench/benches/tokenizer.rs

@@ -0,0 +1,19 @@
+//! Criterion bench for the tokenizer. Baseline target: < 5 ms per 57K tokens
+//! (JS js-tiktoken measures ~38 ms on the same input).
+
+use core_api::TokenCounter;
+use criterion::{criterion_group, criterion_main, Criterion};
+use tokenizer::TiktokenCounter;
+
+fn bench_tokenizer(c: &mut Criterion) {
+    let counter = TiktokenCounter::default();
+    // ~230K chars ≈ 57K cl100k tokens (mirrors the measured JS baseline).
+    let text = "Hello world! This is a test of tokenization performance. \
+                The quick brown fox jumps over the lazy dog. "
+        .repeat(4000);
+
+    c.bench_function("cl100k_57k_tokens", |b| b.iter(|| counter.count(&text)));
+}
+
+criterion_group!(benches, bench_tokenizer);
+criterion_main!(benches);

compression-core/crates/core-api/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "core-api"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }

compression-core/crates/core-api/src/lib.rs

@@ -0,0 +1,76 @@
+//! Stable public API of the compression core.
+//!
+//! This crate is intentionally free of any OmniRoute-specific types.
+//! It defines the contracts that every adapter (N-API, sidecar, CLI)
+//! implements, so algorithms stay independent of the host project.
+
+use serde::{Deserialize, Serialize};
+
+/// Role of a message in a conversation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Role {
+    System,
+    User,
+    Assistant,
+    Tool,
+}
+
+/// One chat message. Field-compatible with OpenAI `messages[]` entries.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Message {
+    pub role: Role,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub content: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_call_id: Option<String>,
+}
+
+/// Tokenizer encodings supported by the core.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum Encoding {
+    #[serde(rename = "cl100k_base")]
+    Cl100kBase,
+    #[serde(rename = "o200k_base")]
+    O200kBase,
+}
+
+/// Configuration for a compression pass.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
+pub struct CompressionConfig {
+    /// Target token budget for the compressed messages.
+    pub budget_tokens: Option<u64>,
+    /// Engine stack priority hint (rtk=10, ionizer=13, headroom=15, ...).
+    pub stack_priority: Option<u32>,
+}
+
+/// Outcome of a compression pass.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CompressionResult {
+    pub messages: Vec<Message>,
+    pub compressed: bool,
+    pub stats: Option<CompressionStats>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CompressionStats {
+    pub saved_tokens: Option<u64>,
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+}
+
+/// A token counter. Pure, stateless, thread-safe.
+pub trait TokenCounter {
+    fn count(&self, text: &str) -> usize;
+}
+
+/// A compressor. Pure, deterministic, stateless per call.
+pub trait Compressor {
+    fn compress(
+        &self,
+        messages: &[Message],
+        config: &CompressionConfig,
+    ) -> CompressionResult;
+}

compression-core/crates/ffi/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "compression-ffi"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[dependencies]
+core-api = { workspace = true }
+tokenizer = { workspace = true }
+
+# napi-rs bindings are added in the integration phase. This crate exists to
+# keep the N-API adapter out of the algorithm crates.

compression-core/crates/ffi/src/lib.rs

@@ -0,0 +1,8 @@
+//! N-API binding crate (integration phase).
+//!
+//! This crate is intentionally empty until the N-API phase. It will expose
+//! `count_tokens` / `compress` over napi-rs using the core-api traits, so the
+//! algorithms in `tokenizer` and the future `compression` crates stay free of
+//! any Node bindings.
+
+pub use core_api;

compression-core/crates/tests/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "compression-tests"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[dependencies]
+core-api = { workspace = true }
+tokenizer = { workspace = true }
+serde_json = { workspace = true }

compression-core/crates/tests/src/lib.rs

@@ -0,0 +1,66 @@
+//! Golden tests: run the Rust implementations against fixtures and compare
+//! byte-for-byte with the JS-produced `expected/` files.
+//!
+//! The `verify-golden.ts` script regenerates fixtures from the OmniRoute JS
+//! implementation. Until this crate passes 100% of golden fixtures, the JS
+//! implementation must NOT be replaced in production.
+
+use core_api::{Encoding, TokenCounter};
+use std::path::Path;
+use tokenizer::TiktokenCounter;
+
+const FIXTURES_DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../fixtures");
+
+fn fixture_path(relative: &str) -> String {
+    Path::new(FIXTURES_DIR).join(relative).to_string_lossy().into_owned()
+}
+
+#[test]
+fn tokenizer_golden_cl100k() {
+    let counter = TiktokenCounter::default();
+    let dir = fixture_path("tokenizer");
+    let entries = std::fs::read_dir(&dir).expect("fixtures/tokenizer must exist");
+    let mut checked = 0;
+    for entry in entries {
+        let path = entry.unwrap().path();
+        if path.extension().map(|e| e == "json").unwrap_or(false) {
+            let input: serde_json::Value =
+                serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+            let text = input["text"].as_str().unwrap();
+            let expected = input["cl100k_tokens"].as_u64().unwrap() as usize;
+            assert_eq!(
+                counter.count(text),
+                expected,
+                "cl100k mismatch on {}",
+                path.display()
+            );
+            checked += 1;
+        }
+    }
+    assert!(checked > 0, "no tokenizer fixtures found");
+}
+
+#[test]
+fn tokenizer_golden_o200k() {
+    let counter = TiktokenCounter::default();
+    let dir = fixture_path("tokenizer");
+    let entries = std::fs::read_dir(&dir).expect("fixtures/tokenizer must exist");
+    let mut checked = 0;
+    for entry in entries {
+        let path = entry.unwrap().path();
+        if path.extension().map(|e| e == "json").unwrap_or(false) {
+            let input: serde_json::Value =
+                serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+            let text = input["text"].as_str().unwrap();
+            let expected = input["o200k_tokens"].as_u64().unwrap() as usize;
+            assert_eq!(
+                counter.count_with_encoding(text, Encoding::O200kBase),
+                expected,
+                "o200k mismatch on {}",
+                path.display()
+            );
+            checked += 1;
+        }
+    }
+    assert!(checked > 0, "no tokenizer fixtures found");
+}

compression-core/crates/tokenizer/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "tokenizer"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+core-api = { workspace = true }
+tiktoken-rs = { workspace = true }
+anyhow = "1"
+
+[dev-dependencies]
+serde_json = { workspace = true }

compression-core/crates/tokenizer/src/lib.rs

@@ -0,0 +1,71 @@
+//! Tiktoken token counter backed by `tiktoken-rs`.
+//!
+//! Port target: `src/shared/utils/tiktokenCounter.ts` in OmniRoute.
+//! Encodings: cl100k_base (default), o200k_base (Codex).
+
+use core_api::{Encoding, TokenCounter};
+use tiktoken_rs::tokenizer::Tokenizer;
+
+pub struct TiktokenCounter {
+    cl100k: tiktoken_rs::CoreBPE,
+    o200k: tiktoken_rs::CoreBPE,
+}
+
+impl TiktokenCounter {
+    pub fn new() -> Result<Self, anyhow::Error> {
+        let cl100k = tiktoken_rs::get_bpe_from_tokenizer(Tokenizer::Cl100kBase)?;
+        let o200k = tiktoken_rs::get_bpe_from_tokenizer(Tokenizer::O200kBase)?;
+        Ok(Self { cl100k, o200k })
+    }
+
+    pub fn count_with_encoding(&self, text: &str, encoding: Encoding) -> usize {
+        let bpe = match encoding {
+            Encoding::Cl100kBase => &self.cl100k,
+            Encoding::O200kBase => &self.o200k,
+        };
+        // CoreBPE::encode_with_special_tokens requires allocation; the
+        // plain encode is the closest equivalent to the JS byte-pair count.
+        bpe.encode_ordinary(text).len()
+    }
+}
+
+impl Default for TiktokenCounter {
+    fn default() -> Self {
+        Self::new().expect("tiktoken rank tables must load")
+    }
+}
+
+impl TokenCounter for TiktokenCounter {
+    fn count(&self, text: &str) -> usize {
+        self.count_with_encoding(text, Encoding::Cl100kBase)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn counts_known_tokens_cl100k() {
+        let counter = TiktokenCounter::default();
+        // "Hello world" is 2 tokens in cl100k_base.
+        assert_eq!(counter.count("Hello world"), 2);
+    }
+
+    #[test]
+    fn empty_string_is_zero() {
+        let counter = TiktokenCounter::default();
+        assert_eq!(counter.count(""), 0);
+    }
+
+    #[test]
+    fn o200k_differs_from_cl100k_on_emoji() {
+        let counter = TiktokenCounter::default();
+        let emoji = "🎉";
+        let cl100k = counter.count_with_encoding(emoji, Encoding::Cl100kBase);
+        let o200k = counter.count_with_encoding(emoji, Encoding::O200kBase);
+        // o200k has dedicated emoji tokens; counts may differ. Just assert both are > 0.
+        assert!(cl100k > 0);
+        assert!(o200k > 0);
+    }
+}

compression-core/fixtures/expected/tokenizer-manifest.json

@@ -0,0 +1,80 @@
+[
+  {
+    "id": "000",
+    "chars": 28,
+    "cl100k_tokens": 8,
+    "o200k_tokens": 8
+  },
+  {
+    "id": "001",
+    "chars": 44,
+    "cl100k_tokens": 10,
+    "o200k_tokens": 10
+  },
+  {
+    "id": "002",
+    "chars": 40,
+    "cl100k_tokens": 15,
+    "o200k_tokens": 12
+  },
+  {
+    "id": "003",
+    "chars": 38,
+    "cl100k_tokens": 15,
+    "o200k_tokens": 15
+  },
+  {
+    "id": "004",
+    "chars": 47,
+    "cl100k_tokens": 15,
+    "o200k_tokens": 15
+  },
+  {
+    "id": "005",
+    "chars": 100,
+    "cl100k_tokens": 100,
+    "o200k_tokens": 50
+  },
+  {
+    "id": "006",
+    "chars": 100,
+    "cl100k_tokens": 41,
+    "o200k_tokens": 23
+  },
+  {
+    "id": "007",
+    "chars": 10000,
+    "cl100k_tokens": 1250,
+    "o200k_tokens": 1250
+  },
+  {
+    "id": "008",
+    "chars": 1,
+    "cl100k_tokens": 1,
+    "o200k_tokens": 1
+  },
+  {
+    "id": "009",
+    "chars": 0,
+    "cl100k_tokens": 0,
+    "o200k_tokens": 0
+  },
+  {
+    "id": "010",
+    "chars": 49,
+    "cl100k_tokens": 18,
+    "o200k_tokens": 14
+  },
+  {
+    "id": "011",
+    "chars": 69,
+    "cl100k_tokens": 24,
+    "o200k_tokens": 24
+  },
+  {
+    "id": "012",
+    "chars": 405000,
+    "cl100k_tokens": 90001,
+    "o200k_tokens": 90001
+  }
+]

compression-core/fixtures/tokenizer/sample-000.json

@@ -0,0 +1,6 @@
+{
+  "id": "000",
+  "text": "Hello world! This is a test.",
+  "cl100k_tokens": 8,
+  "o200k_tokens": 8
+}