Merge release/v3.8.8 into main

.agents/skills/deploy-vps-akamai-cc/SKILL.md

@@ -30,7 +30,7 @@ scp omniroute-*.tgz root@69.164.221.35:/tmp/
 ```
 
 ```bash
-ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
+ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
 ```
 
 ### 3. Verify the deployment

.agents/skills/deploy-vps-both-cc/SKILL.md

@@ -35,11 +35,11 @@ scp omniroute-*.tgz root@69.164.221.35:/tmp/ && scp omniroute-*.tgz root@192.168
 ```
 
 ```bash
-ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
+ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
 ```
 
 ```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
 ```
 
 ### 3. Verify the deployment

.agents/skills/deploy-vps-local-ag/SKILL.md

@@ -30,7 +30,7 @@ scp omniroute-*.tgz root@192.168.0.15:/tmp/
 ```
 
 ```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
 ```
 
 ### 3. Verify the deployment

.agents/skills/deploy-vps-local-cc/SKILL.md

@@ -30,7 +30,7 @@ scp omniroute-*.tgz root@192.168.0.15:/tmp/
 ```
 
 ```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
 ```
 
 ### 3. Verify the deployment

.agents/skills/deploy-vps-local-cx/SKILL.md

@@ -35,7 +35,7 @@ scp omniroute-*.tgz root@192.168.0.15:/tmp/
 ```
 
 ```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
 ```
 
 ### 3. Verify the deployment

.env.example

@@ -257,6 +257,14 @@ ALLOW_API_KEY_REVEAL=false
 # Used by: src/middleware/promptInjectionGuard.ts — extends injection guard.
 # PII_REDACTION_ENABLED=false
 
+# Minimum streaming window size for PII detection (bytes). Default: 200.
+# Used by: src/lib/streamingPiiTransform.ts.
+# PII_WINDOW_SIZE=200
+
+# Test bypass: allow setting PII_WINDOW_SIZE below minimum. Default: false.
+# Used by: src/lib/streamingPiiTransform.ts.
+# PII_TEST_BYPASS_MIN_WINDOW=false
+
 # ── Response-Side: PII Sanitizer ──
 # Scans LLM responses for leaked PII before returning to the client.
 # Used by: src/lib/piiSanitizer.ts
@@ -563,6 +571,18 @@ CLAUDE_OAUTH_CLIENT_ID=9d1c250a-e61b-44d9-88ed-5944d1962f5e
 # ── Codex / OpenAI ──
 CODEX_OAUTH_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
 
+# Milliseconds to wait between consecutive Codex token refreshes.
+# Used by: open-sse/services/refreshSerializer.ts. Default: 0 (no spacing).
+# CODEX_REFRESH_SPACING_MS=0
+
+# ── Trae (ByteDance) ──
+# Trae stream idle timeout (ms). Default: 300000 (5 min).
+# Used by: open-sse/executors/trae.ts.
+# TRAE_STREAM_TIMEOUT_MS=300000
+
+# Trae OAuth token override. Used by: open-sse/executors/trae.ts.
+# TRAE_TOKEN=
+
 # ── Gemini / Gemini CLI / Antigravity / Windsurf (all Google-based) ──
 # These providers ship public OAuth client_id/secret values (or Firebase Web
 # keys) embedded in their public CLIs/binaries. Defaults are baked into the
@@ -929,10 +949,25 @@ APP_LOG_TO_FILE=true
 
 # Node.js V8 heap limit in MB, passed to the server via --max-old-space-size.
 # Used by the standalone launcher (Docker CMD) and `omniroute serve`.
-# Default: 512. Clamped to [64, 16384]. Raise it (e.g. 1024) if you see random
-# OOM crashes under load or with a large SQLite DB (#2939).
+# Clamped to [64, 16384]. Default: 512 (safe for a 1 GB / 1 core VPS). Size it to
+# roughly half the box's RAM, leaving the rest for native memory (better-sqlite3,
+# buffers — ~300 MB) and the OS:
+#   1 GB RAM  → 512   (default)
+#   2 GB RAM  → 1024
+#   4 GB RAM  → 2048
+# In a memory-capped container, set this EXPLICITLY: Node reads the HOST's RAM,
+# not the cgroup limit, so leaving it to a RAM heuristic can oversize the heap and
+# get the container OOM-killed. (#2939)
 # OMNIROUTE_MEMORY_MB=512
 
+# Heap-pressure shed threshold (MB) — chatCore returns 503 when V8 heapUsed exceeds
+# it, to avoid hard OOM under concurrent large-context load.
+# LEAVE UNSET: it now AUTO-CALIBRATES to 85% of the actual V8 heap ceiling, so it
+# tracks OMNIROUTE_MEMORY_MB above and never sits below the ~260 MB runtime baseline
+# (a fixed 200 here used to reject every request). Used by: open-sse/utils/heapPressure.ts.
+# Override only to hand-tune for a known workload.
+# HEAP_PRESSURE_THRESHOLD_MB=
+
 # ── CLI helpers (bin/cli/) ──
 # Override UI language for CLI output. Accepts BCP-47 locale (e.g. en, pt-BR).
 # Falls back to LC_ALL / LC_MESSAGES / LANG / en if unset.
@@ -957,6 +992,10 @@ APP_LOG_TO_FILE=true
 # Default: ~/.omniroute/plugins/  Override in dev/CI to point at a local plugin tree.
 # OMNIROUTE_PLUGIN_PATH=
 
+# Allow plugins to request the 'exec' permission (spawn child processes from the
+# plugin worker sandbox). Disabled by default; set to 1 to enable (local operator only).
+# OMNIROUTE_PLUGINS_ALLOW_EXEC=0
+
 # ── Prompt cache (system prompt deduplication) ──
 # Used by: open-sse/services — caches identical system prompts across requests.
 # PROMPT_CACHE_MAX_SIZE=50              # Max cached entries (default: 50)
@@ -1125,6 +1164,13 @@ APP_LOG_TO_FILE=true
 # CURSOR_STREAM_DEBUG is kept as a backward-compatible alias.
 # Used by: open-sse/executors/cursor.ts
 # CURSOR_DEBUG=1
+
+# Enable verbose trace logging for OmniRoute internals.
+# Used by: open-sse/handlers/chatCore.ts.
+# OMNIRROUTE_TRACE=true
+
+# Standard DEBUG flag (same effect as OMNIRROUTE_TRACE).
+# DEBUG=true
 # CURSOR_STREAM_DEBUG=1
 
 # When CURSOR_DEBUG=1, also append raw decoded chunks to this file path.