fix(build): exec native esbuild binary directly in prepublish (dast-smoke base-red) (#9558)

* fix(build): exec native tool binaries directly in runBuildTool

#8858 routed every resolved local bin through process.execPath to avoid
Windows .cmd shims — but esbuild >=0.25 ships bin/esbuild as the NATIVE
platform executable (ELF on Linux), so Node parsed machine code as JS and
build:cli died with 'SyntaxError: Invalid or unexpected token', turning
dast-smoke red for every PR.

runBuildTool now sniffs the entry's magic bytes (ELF / Mach-O / PE) and
execs native binaries directly; JS entries keep going through this Node
binary (the .cmd-shim avoidance #8858 wanted).

Validation (RED->GREEN on this box):
- RED: node node_modules/esbuild/bin/esbuild --version -> SyntaxError (ELF)
- GREEN: the exact failing CI step reproduced via the new logic bundles
  open-sse/mcp-server/server.ts successfully (4.2MB output, 1.3s).

* fix(docs): add MDX frontmatter to the 20 remaining docs without it

Same failure class as AGENTROUTER_WAF (#9503) and DOCKER_RELEASE_CHANNELS
(this run's dast-smoke red): any doc without frontmatter breaks the
fumadocs MDX loader during next build, killing build:cli/dast-smoke for
every PR. Swept ALL of docs/ (i18n mirrors excluded) in one pass so this
class cannot recur one file at a time.

* docs(env): document OMNIROUTE_INTERNAL_SERVICE_TOKEN(+_FILE), OPENROUTER_PROVIDER_STATS_* and embedded-Redis binding vars

Pre-existing env/docs contract drift from recently merged features made
check:env-doc-sync red for any docs-touching PR. Values and defaults read
from the defining modules (internalServiceAuth.ts, openrouterProviderStats.ts).

* fix(build): resolve bundled npm-cli.js in the standard Unix layout + safe npm fallback off-Windows

The opencode-plugin step hard-failed on GitHub runners because
resolveBundledNpmEntry only looked next to the node binary (Windows zip
layout); hostedtoolcache Node keeps npm at <prefix>/lib/node_modules/npm.
Added that candidate, and when neither exists on non-Windows the step now
falls back to plain 'npm' — the .cmd-shim hazard #8858 avoids is
Windows-only.

* test(mutation): register xai-agent-tools-passthrough.test.ts in stryker tap.testFiles

The test landed on release/v3.8.50 covering
open-sse/handlers/chatCore/passthroughHelpers.ts without the stryker
registration, so Fast Quality Gates' drift detection reds any PR that
carries it. Mechanical registration so its mutant kills count.

---------

Co-authored-by: diegosouzapw <diegosouzapw@users.noreply.github.com>

docs/INCIDENT_RESPONSE.md

@@ -1,3 +1,9 @@
+---
+title: "Incident Response Runbook — OmniRoute (2026-06-18)"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Incident Response Runbook — OmniRoute (2026-06-18)
 
 **Status**: Authoritative. The 71-pillar audit (L61) references this doc

docs/PERF_BUDGETS.md

@@ -1,3 +1,9 @@
+---
+title: "Performance Budgets — OmniRoute (2026-06-18)"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Performance Budgets — OmniRoute (2026-06-18)
 
 **Status**: Authoritative. SLO targets that the 71-pillar audit (L13)

docs/ROADMAP.md

@@ -1,3 +1,9 @@
+---
+title: "OmniRoute Roadmap"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # OmniRoute Roadmap
 
 > Version-gated, not date-gated: each milestone ships when its quality gates pass.

docs/assets/flags/README.md

@@ -1,3 +1,9 @@
+---
+title: "Flag icons"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Flag icons
 
 SVG country flags used by the language selector in the root `README.md`.

docs/combo-context-requirements.md

@@ -1,3 +1,9 @@
+---
+title: "Combo Context Requirements Feature"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Combo Context Requirements Feature
 
 ## Overview

docs/getting-started/AUTO-COMBO-GUIDE.md

@@ -1,3 +1,9 @@
+---
+title: "Auto-Combo: Let OmniRoute Pick the Best AI for You"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Auto-Combo: Let OmniRoute Pick the Best AI for You
 
 > **TL;DR**: Set your model to `auto` and OmniRoute automatically picks the best AI provider for each request. No configuration needed.

docs/getting-started/FREE-TIERS-GUIDE.md

@@ -1,3 +1,9 @@
+---
+title: "Free Tiers Guide: Get Free AI Without a Credit Card"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Free Tiers Guide: Get Free AI Without a Credit Card
 
 > **TL;DR**: OmniRoute aggregates free tiers from 50+ providers. Connect multiple free providers for unlimited free AI with automatic fallback.

docs/getting-started/PROVIDERS-GUIDE.md

@@ -1,3 +1,9 @@
+---
+title: "Providers Guide: Connect AI Models to OmniRoute"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Providers Guide: Connect AI Models to OmniRoute
 
 > **TL;DR**: A provider is a connection to an AI service (like OpenAI, Anthropic, Google). You need at least one provider to use OmniRoute.

docs/getting-started/QUICK-START.md

@@ -1,3 +1,9 @@
+---
+title: "Quick Start: Get OmniRoute Running in 3 Minutes"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Quick Start: Get OmniRoute Running in 3 Minutes
 
 > **TL;DR**: Install → Connect a free provider → Point your IDE to OmniRoute. Done.

docs/guides/DOCKER_RELEASE_CHANNELS.md

@@ -1,3 +1,9 @@
+---
+title: "Docker Release Channels"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Docker Release Channels
 
 OmniRoute publishes separate Docker channels for stable releases, active release-branch testing, and development builds.

docs/proxy-port-clash-report.md

@@ -1,3 +1,9 @@
+---
+title: "Proxy Port Clash Investigation"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Proxy Port Clash Investigation
 
 ## Summary

docs/proxy-subscriptions.md

@@ -1,3 +1,9 @@
+---
+title: "Operator Proxy Subscriptions (Karing-style)"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Operator Proxy Subscriptions (Karing-style)
 
 > Feature design + implementation notes for OmniRoute's operator-level proxy

docs/redis-production-config.md

@@ -1,3 +1,9 @@
+---
+title: "Redis Production Configuration Guide"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Redis Production Configuration Guide
 
 ## Overview

docs/reference/ENVIRONMENT.md

@@ -1312,3 +1312,25 @@ Used by `src/lib/vncSession/manifest.ts` to configure Docker-based headless Chro
 | `OMNIROUTE_VNC_READY_MS`              | `45000`                       | `src/lib/vncSession/manifest.ts`  | Browser readiness timeout (ms).                                                |
 | `OMNIROUTE_VNC_HARVEST_MS`            | `20000`                       | `src/lib/vncSession/manifest.ts`  | Harvest/cleanup timeout (ms).                                                  |
 | `VIBEPROXY_DATA_DIR`                  | _(unset)_                     | `open-sse/services/notionThreadSessions.ts` | Directory for Notion thread session persistence.                               |
+
+### Internal service auth
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `OMNIROUTE_INTERNAL_SERVICE_TOKEN` | – | Inline token for management-plane service-to-service authentication. |
+| `OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE` | – | Path to a file containing the internal service token (preferred in containers; overrides the inline variable). |
+
+### OpenRouter provider stats
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `OPENROUTER_PROVIDER_STATS_ENABLED` | `true` | Set to `false` to skip fetching OpenRouter per-provider stats for catalog enrichment. |
+| `OPENROUTER_PROVIDER_STATS_TTL_MS` | `3600000` | Cache TTL (ms) for the fetched OpenRouter provider stats. |
+
+### Embedded Redis binding
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `REDIS_BIND_HOST` | `127.0.0.1` | Bind address for the embedded Redis service. |
+| `REDIS_PORT` | `6379` | Port for the embedded Redis service. |
+| `OMNIROUTE_REDIS_BIND_HOST` | – | OmniRoute-scoped override for the embedded Redis bind address. |

docs/sessions/20260714-issue-agent-executable-triage/00_SESSION_OVERVIEW.md

@@ -1,3 +1,9 @@
+---
+title: "Issue-Agent Executable Triage: Session Overview"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Issue-Agent Executable Triage: Session Overview
 
 Machine status: `in_progress`

docs/sessions/20260714-issue-agent-executable-triage/01_RESEARCH.md

@@ -1,3 +1,9 @@
+---
+title: "Issue-Agent Executable Triage: Research"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Issue-Agent Executable Triage: Research
 
 Machine status: `complete_for_current_phase`

docs/sessions/20260714-issue-agent-executable-triage/02_SPECIFICATIONS.md

@@ -1,3 +1,9 @@
+---
+title: "Issue-Agent Executable Triage: Specifications"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Issue-Agent Executable Triage: Specifications
 
 Machine status: `in_progress`

docs/sessions/20260714-issue-agent-executable-triage/03_DAG_WBS.md

@@ -1,3 +1,9 @@
+---
+title: "Issue-Agent Executable Triage: DAG and WBS"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Issue-Agent Executable Triage: DAG and WBS
 
 Machine status: `in_progress`

docs/sessions/20260714-issue-agent-executable-triage/04_IMPLEMENTATION_STRATEGY.md

@@ -1,3 +1,9 @@
+---
+title: "Issue-Agent Executable Triage: Implementation Strategy"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Issue-Agent Executable Triage: Implementation Strategy
 
 Machine status: `in_progress`

docs/sessions/20260714-issue-agent-executable-triage/05_KNOWN_ISSUES.md

@@ -1,3 +1,9 @@
+---
+title: "Issue-Agent Executable Triage: Known Issues"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Issue-Agent Executable Triage: Known Issues
 
 Machine status: `open`

docs/sessions/20260714-issue-agent-executable-triage/06_TESTING_STRATEGY.md

@@ -1,3 +1,9 @@
+---
+title: "Issue-Agent Executable Triage: Testing Strategy"
+version: 3.8.50
+lastUpdated: 2026-08-06
+---
+
 # Issue-Agent Executable Triage: Testing Strategy
 
 Machine status: `in_progress`