feat(cpg): add an explicit environment switch for the engine session (M2 11.3)

A measured run needs to enable the transport without changing any default. The
switch reads as enabled only for the exact value "1"; unset, empty, "0", "true"
and anything else leave the disposable path in place, and an explicit constructor
argument still wins in both directions.

1,396 tests passed, nine skipped.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo

src/openultrasast/cpg/backend.py

@@ -58,6 +58,8 @@ QUERY_TIMEOUT_ENV = "OPENULTRASAST_CPG_QUERY_TIMEOUT"
 # first repository measurements unreproducible: runs were killed under memory pressure at different
 # points, so the numbers described the host, not the engine. Bound it, and let the operator raise it.
 CPG_HEAP_MB = 2048
+# Explicit opt-in for the transaction-owned engine session (M2). Unset means the disposable path.
+SESSION_ENV = "OUSAST_ENGINE_SESSION"
 HEAP_ENV = "OPENULTRASAST_CPG_HEAP_MB"
 
 # `joern-parse` detects the language and then shells out to a frontend, and on a large tree it can fail where
@@ -324,7 +326,9 @@ class JoernBackend:
     # M2 11.3: opt-in transport. Off by default, so shipped behaviour stays the disposable
     # invocation this project has measured. A session that cannot answer falls back to it rather
     # than reporting a zero, and what a session returns is the same payload or nothing at all.
-    session_transport: bool = False
+    # The environment switch exists so a measured run can enable it without changing any default;
+    # anything other than "1" leaves it off.
+    session_transport: bool = field(default_factory=lambda: os.environ.get(SESSION_ENV, "").strip() == "1")
     _diagnostics: list[str] = field(default_factory=list, init=False, repr=False)
     _scratch: list[Path] = field(default_factory=list, init=False, repr=False)
     _cancel_deadline: float | None = field(default=None, init=False, repr=False)