From 94aa978c2a720c163a1d8c17765bea84c5bf7bf7 Mon Sep 17 00:00:00 2001
From: Diego Rodrigues de Sa e Souza <diegosouza.pw@gmail.com>
Date: Fri, 18 Sep 2026 08:13:32 -0300
Subject: [PATCH] =?UTF-8?q?fix(ci):=20document=20OMNIROUTE=5FSTRIP=5FSYSTE?=
 =?UTF-8?q?M=5FPREAMBLE=20=E2=80=94=20the=20env/docs=20base=20red=20blocki?=
 =?UTF-8?q?ng=20every=20PR=20(#14022)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(ci): document OMNIROUTE_STRIP_SYSTEM_PREAMBLE (env/docs contract base-red)

* fix(ci): allowlist COMBO_LOOP_SAFETY_TIMEOUT_MS as a doc-only source constant

The env/docs contract gate had a SECOND violation on the release tip, added after
this branch was cut: #13857's comboTimeoutMs narrative in ENVIRONMENT.md cites
COMBO_LOOP_SAFETY_TIMEOUT_MS, which is a source constant
(open-sse/services/combo/comboPredicates.ts:35 — `10 * 60 * 1000`), not an
operator-facing env var. The doc regex captured the SHOUTY_NAME and reported it
as documented-but-missing-from-.env.example.

DOC_ONLY_ALLOWLIST already exists for exactly this class (see CLI_COMPAT_OMITTED_PROVIDER_IDS,
LOCAL_ONLY_API_PREFIXES, VACUUM). Gate now reports all three directions in sync.
---
 .env.example                         | 9 +++++++++
 docs/reference/ENVIRONMENT.md        | 1 +
 scripts/check/check-env-doc-sync.mjs | 4 ++++
 3 files changed, 14 insertions(+)

diff --git a/.env.example b/.env.example
index c8e2883135..0d02dea705 100644
--- a/.env.example
+++ b/.env.example
@@ -2407,6 +2407,15 @@ APP_LOG_TO_FILE=true
 # Used by: open-sse/translator/request/claude-to-openai.ts, open-sse/translator/response/openai-to-claude.ts.
 # OMNIROUTE_SYSTEM_INSTRUCTION_APPEND=
 
+# Set to "1" to also strip echoed system-prompt PREAMBLE blocks
+# (<analysis>/<system-reminder>/<summary> blocks, prose reproductions of the skill
+# section) from the start of an openai->claude stream. OFF by default: it recognises
+# constructs by English-prose heuristics and DOES mutate the response payload, so a
+# reply that genuinely opens with such a section would lose it. Turn it on only when
+# you actually hit the system-echo leak.
+# Used by: open-sse/translator/response/openai-to-claude.ts, open-sse/utils/directivePreambleStripper.ts.
+# OMNIROUTE_STRIP_SYSTEM_PREAMBLE=0
+
 # Per-image fetch timeout (ms) for remote image_url vision input. Default: 15000.
 # Used by: open-sse/utils/cursorImages.ts.
 # CURSOR_IMAGE_FETCH_TIMEOUT_MS=15000
diff --git a/docs/reference/ENVIRONMENT.md b/docs/reference/ENVIRONMENT.md
index 126b3225f0..3ca603874c 100644
--- a/docs/reference/ENVIRONMENT.md
+++ b/docs/reference/ENVIRONMENT.md
@@ -1195,6 +1195,7 @@ changing them requires a code edit, not an env var:
 | `CURSOR_KV_GRACE_MS`             | `2000`              | `open-sse/executors/cursor.ts`             | Grace window (ms) after a composer kv_after_text soft terminator when bytes remain buffered — gives a trailing exec_mcp tool call time to complete its frame. |
 | `CURSOR_TOOL_DIRECTIVE`          | enabled (`!== "0"`) | `open-sse/executors/cursor.ts`             | Tool-commit directive that makes composer-2.5 reliably issue tool calls. Set `0` to disable. |
 | `OMNIROUTE_SYSTEM_INSTRUCTION_APPEND` | _(unset)_ | `open-sse/translator/request/claude-to-openai.ts`, `open-sse/translator/response/openai-to-claude.ts` | Operator-defined system prompt text appended to the system message AFTER translation (post-translation injection), reaching codex/Responses and `/v1/messages` paths. Also used as the directive prefix stripped from echoed system preamble blocks. Leave unset to disable. |
+| `OMNIROUTE_STRIP_SYSTEM_PREAMBLE` | `0` (off) | `open-sse/translator/response/openai-to-claude.ts`, `open-sse/utils/directivePreambleStripper.ts` | Set to `1` to strip echoed system-prompt preamble blocks from the start of an openai→claude stream. Off by default — the heuristics are English-prose shaped and mutate the response payload, so a reply that legitimately opens with such a section would lose it. |
 | `CURSOR_IMAGE_FETCH_TIMEOUT_MS`  | `15000`             | `open-sse/utils/cursorImages.ts`           | Per-image fetch timeout (ms) for remote `image_url` vision input.                            |
 | `CURSOR_STATE_DB_PATH`           | _(probed)_          | `open-sse/utils/cursorVersionDetector.ts`  | Override the Cursor IDE state DB lookup used for IDE version detection.                      |
 | `CURSOR_AGENT_CLI_VERSION`       | _(detect / pin)_    | `open-sse/utils/cursorAgentCliVersion.ts`  | Agent CLI build id (`YYYY.MM.DD-<hash>`) for `x-cursor-client-version: cli-…` on Agent Run.   |
diff --git a/scripts/check/check-env-doc-sync.mjs b/scripts/check/check-env-doc-sync.mjs
index d333a89649..272ae00b72 100644
--- a/scripts/check/check-env-doc-sync.mjs
+++ b/scripts/check/check-env-doc-sync.mjs
@@ -272,6 +272,10 @@ const DOC_ONLY_ALLOWLIST = new Set([
   // SQL keyword mentioned in the new VACUUM scheduler docs (#4437).
   // The check's regex picks up the bare word in description text.
   "VACUUM",
+  // Source-code constant (open-sse/services/combo/comboPredicates.ts:35 —
+  // `export const COMBO_LOOP_SAFETY_TIMEOUT_MS = 10 * 60 * 1000`), cited in the
+  // comboTimeoutMs narrative added by #13857. Not operator-configurable.
+  "COMBO_LOOP_SAFETY_TIMEOUT_MS",
 ]);
 
 // Vars present in .env.example but intentionally absent from ENVIRONMENT.md.