@miller-tech/uap 1.136.1 → 1.137.1

package/tools/agents/scripts/anthropic_proxy.py

@@ -180,6 +180,19 @@ PROXY_SLOT_HANG_TIMEOUT = float(os.environ.get("PROXY_SLOT_HANG_TIMEOUT", "120")
 PROXY_UPSTREAM_RETRY_MAX = int(os.environ.get("PROXY_UPSTREAM_RETRY_MAX", "3"))
 PROXY_UPSTREAM_RETRY_DELAY_SECS = float(os.environ.get("PROXY_UPSTREAM_RETRY_DELAY_SECS", "5"))
 PROXY_MAX_CONNECTIONS = int(os.environ.get("PROXY_MAX_CONNECTIONS", "20"))
+# CLOSE-WAIT reaper: abandoned upstream connections (a cancelled request
+# whose httpx connection is never closed — llama's response sits unread in
+# the socket, CLOSE-WAIT) accrue and saturate the pool. The reaper reads
+# /proc/net/tcp, counts CLOSE-WAIT sockets to the upstream, and triggers a
+# (safe, stream-preserving) pool self-heal when they exceed the threshold.
+PROXY_CLOSEWAIT_REAP_THRESHOLD = int(os.environ.get("PROXY_CLOSEWAIT_REAP_THRESHOLD", "30"))
+# Reaper is OPT-IN (default 0 = off): live 2026-07-12 under a SATURATED
+# upstream (llama at 3/3 slots), its pool-swap mechanism turned a slow
+# abandoned-connection leak into ReadError->500 bursts (74 500s/16min) —
+# constant swaps churned in-flight connections. The graceful path
+# (PoolTimeout -> 529 backoff + a large PROXY_MAX_CONNECTIONS) handles the
+# leak without client-visible errors. Set >0 to re-enable the reaper.
+PROXY_CLOSEWAIT_REAP_INTERVAL = float(os.environ.get("PROXY_CLOSEWAIT_REAP_INTERVAL", "0"))
 PROXY_CONTEXT_WINDOW = int(os.environ.get("PROXY_CONTEXT_WINDOW", "0"))
 PROXY_CONTEXT_PRUNE_THRESHOLD = float(
     os.environ.get("PROXY_CONTEXT_PRUNE_THRESHOLD", "0.85")
@@ -2283,8 +2296,28 @@ def prune_conversation(
     # Budget for messages
     message_budget = target_tokens - overhead_tokens
     if message_budget <= 0:
-        logger.error("System prompt + tools alone exceed target budget!")
-        return anthropic_body
+        # Tool-heavy clients (observed: 37 MCP tools whose schema estimate x1.5
+        # safety factor exceeds the whole 40% critical-prune target) used to
+        # ERROR-RETURN here with the body untouched — no pruning at all, so the
+        # session pinned at 115%+, Option E clamped every output to 1024 tokens,
+        # and all substantial writes truncated forever (24+ consecutive no-op
+        # prunes + circuit breaker every turn). The schemas are client-fixed
+        # and non-droppable; give MESSAGES a minimal floor and prune into it
+        # best-effort instead of giving up.
+        message_budget = max(1, int(context_window * 0.20))
+        # The condition is PERMANENT for a tool-heavy client (fires per
+        # request, observed every ~2s) — warn once per session, then debug.
+        already = bool(monitor is not None and getattr(monitor, "floor_budget_logged", False))
+        log = logger.debug if already else logger.warning
+        if monitor is not None:
+            monitor.floor_budget_logged = True
+        log(
+            "System+tools overhead (~%d est tokens) consumes the %.0f%% prune "
+            "target — pruning messages into a floor budget of %d tokens instead",
+            overhead_tokens,
+            target_fraction * 100,
+            message_budget,
+        )
 
     # Always keep the first user message and the last N messages
     KEEP_LAST = keep_last
@@ -2386,6 +2419,180 @@ def prune_conversation(
 # Module-level httpx.AsyncClient for connection reuse + keep-alive.
 # Granular timeouts: short connect, long read for streaming LLM output.
 http_client: httpx.AsyncClient | None = None
+_last_pool_reset_ts: float = 0.0
+
+# Transient upstream failures that are safe to retry (a fresh POST re-runs
+# the request). Single source of truth — used by BOTH the buffered
+# _post_with_retry_inner AND the streaming send loop, which previously had
+# divergent copies (the streaming copy lacked ReadError, so a mid-setup
+# connection reset on a streamed turn 500'd; live 2026-07-11).
+_UPSTREAM_RETRY_EXCEPTIONS = (
+    httpx.ConnectError,
+    httpx.ConnectTimeout,
+    httpx.RemoteProtocolError,
+    httpx.ReadTimeout,
+    httpx.ReadError,
+    httpx.WriteError,
+)
+
+
+def _upstream_port() -> int:
+    """The upstream (llama) TCP port, for CLOSE-WAIT accounting."""
+    try:
+        return int(LLAMA_CPP_BASE.rsplit(":", 1)[1].split("/")[0])
+    except Exception:
+        return 8080
+
+
+def _count_upstream_close_wait() -> int:
+    """Count CLOSE-WAIT sockets to the upstream port via /proc/net/tcp.
+
+    Cheap (one file read), no subprocess. TCP state 08 == CLOSE_WAIT; the
+    remote port is hex in the 3rd column's ':PORT' suffix.
+    """
+    port_hex = f"{_upstream_port():04X}"
+    n = 0
+    try:
+        with open("/proc/net/tcp", "r") as fh:
+            next(fh, None)
+            for line in fh:
+                parts = line.split()
+                if len(parts) < 4:
+                    continue
+                if parts[3] == "08" and parts[2].endswith(":" + port_hex):
+                    n += 1
+    except Exception:
+        return 0
+    return n
+
+
+async def _closewait_reaper() -> None:
+    """Periodic: reap abandoned upstream CLOSE-WAIT connections.
+
+    When they exceed the threshold, replace the pool (safe self-heal) — the
+    retired pool's aclose (once its legit in-flight drains) force-closes the
+    abandoned connections, which have no in-flight coroutine of their own.
+    """
+    if PROXY_CLOSEWAIT_REAP_INTERVAL <= 0:
+        return
+    while True:
+        try:
+            await asyncio.sleep(PROXY_CLOSEWAIT_REAP_INTERVAL)
+            cw = _count_upstream_close_wait()
+            if cw >= PROXY_CLOSEWAIT_REAP_THRESHOLD:
+                _maybe_reset_http_client(f"CLOSE-WAIT reaper ({cw} abandoned upstream connections)")
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.warning("CLOSE-WAIT reaper error: %s", exc)
+
+
+def _inflight_inc(client) -> None:
+    try:
+        client._uap_inflight += 1
+    except Exception:
+        pass
+
+
+def _inflight_dec(client) -> None:
+    try:
+        client._uap_inflight -= 1
+    except Exception:
+        pass
+
+
+def _detach_aclose(closeable) -> None:
+    """Close an upstream stream/response on a DETACHED task so it completes
+    even when the requesting ASGI task is being cancelled (client disconnect).
+    An in-line ``await x.aclose()`` in a streaming finally can itself be
+    cancelled before it closes the socket, leaking the upstream connection —
+    it accrues as CLOSE-WAIT and eventually saturates the pool (live
+    2026-07-11: CW climbed 26→52 with zero client errors after the cascade was
+    fixed). ensure_future schedules the close independently of the dying task.
+    """
+    async def _run() -> None:
+        try:
+            await closeable.aclose()
+        except Exception:
+            pass
+    try:
+        asyncio.ensure_future(_run())
+    except RuntimeError:
+        pass  # no running loop — nothing to detach onto
+
+
+def _build_http_client() -> httpx.AsyncClient:
+    """Upstream client factory — used at startup AND by pool self-healing."""
+    c = httpx.AsyncClient(
+        timeout=httpx.Timeout(
+            connect=10.0,  # 10s to establish connection
+            read=PROXY_READ_TIMEOUT,  # configurable (default 10 min)
+            write=30.0,  # 30s to send the request body
+            pool=10.0,  # 10s to acquire a pool connection
+        ),
+        limits=httpx.Limits(
+            max_connections=PROXY_MAX_CONNECTIONS,
+            # No upstream keepalive: llama.cpp closes idle keepalive
+            # connections faster than a 120s expiry, so they piled as
+            # CLOSE-WAIT and exhausted the pool (live: 51 zombies, PoolTimeout
+            # 500-storm). The upstream is localhost at low concurrency —
+            # connection reuse saves microseconds and is not worth the leak
+            # class. Each request opens and cleanly closes its own connection.
+            max_keepalive_connections=0,
+            keepalive_expiry=0,
+        ),
+    )
+    # Per-CLIENT in-flight counter: a retired pool must drain on ITS OWN
+    # requests (a global counter can't isolate it — new-pool traffic keeps a
+    # global high, so the retire waited the full backstop and never reaped;
+    # live 2026-07-11: reaper fired 7x, CLOSE-WAIT still climbed 30→50).
+    c._uap_inflight = 0  # type: ignore[attr-defined]
+    return c
+
+
+def _maybe_reset_http_client(reason: str) -> bool:
+    """Pool self-healing: swap in a fresh AsyncClient, retiring the old one.
+
+    Rare cancellation races (asyncio.wait_for cutting an httpx send mid-
+    response — the guarded non-stream path every tool turn uses) leak
+    connections the pool counts as busy forever; observed live as 12
+    CLOSE-WAIT zombies out of a 20-connection pool and a 205-request
+    PoolTimeout 500-storm. There is no public API to reap them, so on
+    saturation we REPLACE the client: new requests get a fresh pool
+    immediately (handlers snapshot the global per request), in-flight
+    requests finish on the old object, which is closed after a grace period.
+    Cooldown-guarded so a burst cannot thrash clients.
+    """
+    global http_client, _last_pool_reset_ts
+    now = time.time()
+    if now - _last_pool_reset_ts < 60:
+        return False
+    if http_client is None:
+        return False
+    _last_pool_reset_ts = now
+    old_client = http_client
+    http_client = _build_http_client()
+    logger.error(
+        "POOL SELF-HEAL: replaced upstream connection pool (%s); old pool closes after grace period",
+        reason,
+    )
+
+    async def _retire() -> None:
+        # Close the old pool once ITS OWN in-flight requests (per-client
+        # counter — streaming + buffered) drain to zero: no live request
+        # remains on the old client, so aclose() force-closes only its
+        # ABANDONED CLOSE-WAIT connections and never a live stream. Capped at
+        # GENERATION_TIMEOUT as a backstop.
+        deadline = time.time() + max(60.0, PROXY_GENERATION_TIMEOUT)
+        while time.time() < deadline and getattr(old_client, "_uap_inflight", 0) > 0:
+            await asyncio.sleep(1.0)
+        try:
+            await old_client.aclose()
+        except Exception:
+            pass
+
+    asyncio.ensure_future(_retire())
+    return True
 
 # ---------------------------------------------------------------------------
 # Concurrency Control
@@ -2870,7 +3077,11 @@ async def _post_with_retry_inner(
     last_exc: Exception | None = None
     for attempt in range(PROXY_UPSTREAM_RETRY_MAX):
         try:
-            resp = await client.post(url, json=payload, headers=headers)
+            _inflight_inc(client)
+            try:
+                resp = await client.post(url, json=payload, headers=headers)
+            finally:
+                _inflight_dec(client)
             # Cycle 19 Option 1: if 503 "Loading model", wait for health then retry
             if _is_loading_model_503(resp):
                 logger.warning(
@@ -2883,11 +3094,11 @@ async def _post_with_retry_inner(
                     continue  # retry the request now that upstream is healthy
                 return resp  # return the 503 if health wait timed out
             return resp
-        except (httpx.ConnectError, httpx.RemoteProtocolError, httpx.ReadTimeout) as exc:
+        except _UPSTREAM_RETRY_EXCEPTIONS as exc:
             last_exc = exc
             if attempt < PROXY_UPSTREAM_RETRY_MAX - 1:
                 logger.warning(
-                    "Upstream connect failed (attempt %d/%d): %s – retrying in %.0fs",
+                    "Upstream transient error (attempt %d/%d): %s – retrying in %.0fs",
                     attempt + 1,
                     PROXY_UPSTREAM_RETRY_MAX,
                     type(exc).__name__,
@@ -2996,19 +3207,7 @@ async def lifespan(app: FastAPI):
         PROXY_CONCURRENCY_QUEUE_TIMEOUT,
     )
     _prepare_slot_save_dir()
-    http_client = httpx.AsyncClient(
-        timeout=httpx.Timeout(
-            connect=10.0,  # 10s to establish connection
-            read=PROXY_READ_TIMEOUT,  # configurable (default 10 min)
-            write=30.0,  # 30s to send the request body
-            pool=10.0,  # 10s to acquire a pool connection
-        ),
-        limits=httpx.Limits(
-            max_connections=PROXY_MAX_CONNECTIONS,
-            max_keepalive_connections=PROXY_MAX_CONNECTIONS // 2,
-            keepalive_expiry=120,
-        ),
-    )
+    http_client = _build_http_client()
     logger.info(
         "Proxy started: listening on %s:%d -> upstream %s",
         PROXY_HOST,
@@ -3016,6 +3215,8 @@ async def lifespan(app: FastAPI):
         LLAMA_CPP_BASE,
     )
 
+    _reaper_task = asyncio.ensure_future(_closewait_reaper())
+
     # Auto-detect context window from upstream server
     default_context_window = await detect_context_window(http_client)
     for mon in session_monitors.values():
@@ -3082,6 +3283,7 @@ async def lifespan(app: FastAPI):
     )
 
     yield
+    _reaper_task.cancel()
     await http_client.aclose()
     http_client = None
     if upstream_semaphore is not None:
@@ -3098,6 +3300,37 @@ app = FastAPI(
     lifespan=lifespan,
 )
 
+@app.exception_handler(httpx.PoolTimeout)
+async def _pool_timeout_handler(request: Request, exc: httpx.PoolTimeout):
+    """Saturated upstream pool: answer 529 overloaded (Anthropic semantics —
+    clients back off with jitter instead of fast-retrying a 500 traceback,
+    which amplified the storm).
+
+    NOTE: this deliberately does NOT swap the pool. Under a saturated upstream
+    (llama at 3/3 slots) the pool-swap self-heal churned in-flight connections
+    into ReadError→500 bursts (live 2026-07-12) — the same mechanism the
+    reaper was disabled for. Pure backpressure (529 + a large
+    PROXY_MAX_CONNECTIONS) is the graceful posture; leaked connections are
+    cleared by the periodic proxy restart, not by mid-load pool churn. Set
+    PROXY_POOL_SWAP_ON_SATURATION=1 to restore the swap."""
+    if os.environ.get("PROXY_POOL_SWAP_ON_SATURATION") == "1":
+        _maybe_reset_http_client("PoolTimeout on " + request.url.path)
+    return Response(
+        content=json.dumps(
+            {
+                "type": "error",
+                "error": {
+                    "type": "overloaded_error",
+                    "message": "Upstream connection pool saturated — retry shortly.",
+                },
+            }
+        ),
+        status_code=529,
+        media_type="application/json",
+        headers={"retry-after": "10"},
+    )
+
+
 
 # Open paths that never require the shared secret (liveness / discovery), so a
 # LAN health check or an SDK model-list probe works without the token.
@@ -5881,6 +6114,52 @@ def _openai_has_tool_calls(openai_resp: dict) -> bool:
     return bool(_extract_openai_tool_calls(openai_resp))
 
 
+def _json_close_suffix(fragment: str) -> str:
+    """Minimal suffix that closes a truncated JSON fragment so it parses.
+
+    Streamed tool-call arguments cut off by the token limit (finish_reason=
+    length) used to reach the client as unterminated JSON — Claude Code then
+    throws InputValidationError ("could not be parsed as JSON ... first 200 of
+    N bytes") and retries into the same wall. Scanning with the same
+    in-string/escape/nesting rules a JSON parser uses, this returns the
+    characters needed to terminate the fragment: a visible truncation marker +
+    closing quote when cut mid-string, then closers for every open object /
+    array. Returns '' when the fragment already parses (or is empty).
+    """
+    if not fragment:
+        return ""
+    try:
+        json.loads(fragment)
+        return ""
+    except Exception:
+        pass
+    stack: list[str] = []
+    in_string = False
+    escaped = False
+    for ch in fragment:
+        if in_string:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            continue
+        if ch == '"':
+            in_string = True
+        elif ch in "{[":
+            stack.append("}" if ch == "{" else "]")
+        elif ch in "}]" and stack:
+            stack.pop()
+    suffix = ""
+    if in_string:
+        if escaped:
+            suffix += "\\"  # complete the dangling escape as a literal backslash
+        suffix += "\u2026[TRUNCATED BY TOKEN LIMIT]\""
+    suffix += "".join(reversed(stack))
+    return suffix
+
+
 def _parse_openai_function_arguments(raw_args) -> tuple[dict | None, str | None]:
     if isinstance(raw_args, dict):
         return raw_args, None
@@ -9110,8 +9389,17 @@ async def _heartbeat_then_buffered(produce_coro, model: str, input_tokens: int =
             except asyncio.TimeoutError:
                 yield 'event: ping\ndata: {"type": "ping"}\n\n'
     except asyncio.CancelledError:
-        # Client disconnected — cancel the in-flight produce and propagate.
+        # Client disconnected — cancel the in-flight produce AND await its
+        # cleanup so httpx returns/closes the upstream connection before we
+        # unwind. Without the await, the cancel is merely requested and the
+        # socket strands in CLOSE-WAIT (the connection-leak → PoolTimeout 500
+        # storm root cause). Shielded + time-boxed so a stuck close can't hang
+        # the disconnect path.
         task.cancel()
+        try:
+            await asyncio.wait_for(asyncio.shield(task), timeout=5.0)
+        except (asyncio.CancelledError, asyncio.TimeoutError, Exception):
+            pass
         raise
     except Exception as exc:
         logger.error("heartbeat produce failed: %s", exc)
@@ -9232,6 +9520,8 @@ async def stream_anthropic_response(
     - Graceful error recovery on upstream connection drops
     - Proper upstream response closure on client disconnect
     """
+    _sr_client = getattr(openai_stream, "_uap_client", None)
+    _inflight_inc(_sr_client) if _sr_client is not None else None
     msg_id = f"msg_{uuid.uuid4().hex[:24]}"
     stream_started = time.monotonic()
 
@@ -9375,14 +9665,36 @@ async def stream_anthropic_response(
         logger.error("Unexpected stream error: %s: %s", type(exc).__name__, exc)
         finish_reason = "end_turn"
     finally:
-        # Always close the upstream response to stop LLM generation
-        await openai_stream.aclose()
+        if _sr_client is not None:
+            _inflight_dec(_sr_client)
+        # Detached close: a bare 'await aclose()' here is itself cancellable
+        # when the client disconnected (the common case), leaving the upstream
+        # connection un-closed → CLOSE-WAIT leak. Detaching guarantees it runs.
+        _detach_aclose(openai_stream)
 
     # Close any open tool call blocks (skip if XML recovery already emitted them)
     xml_recovered = tool_calls_by_index.pop("_xml_recovered", False)
     if tool_calls_by_index and not xml_recovered:
         for tc in tool_calls_by_index.values():
             if isinstance(tc, dict) and "block_index" in tc:
+                # Truncation repair: if the accumulated arguments do not parse
+                # (token-limit cut mid-JSON), stream one final fragment that
+                # closes the JSON validly — with a visible marker when cut
+                # inside a string — so the client can always parse the block.
+                # stop_reason still reports max_tokens; the marker makes the
+                # truncation visible in whatever the tool writes.
+                repair = _json_close_suffix(tc.get("arguments", ""))
+                if repair:
+                    tc["arguments"] = tc.get("arguments", "") + repair
+                    logger.warning(
+                        "STREAM TOOL-CALL REPAIR: closed truncated '%s' arguments (+%d chars) — client would otherwise fail to parse",
+                        tc.get("name", "?"),
+                        len(repair),
+                    )
+                    yield (
+                        f"event: content_block_delta\n"
+                        f"data: {json.dumps({'type': 'content_block_delta', 'index': tc['block_index'], 'delta': {'type': 'input_json_delta', 'partial_json': repair}})}\n\n"
+                    )
                 yield (
                     f"event: content_block_stop\n"
                     f"data: {json.dumps({'type': 'content_block_stop', 'index': tc['block_index']})}\n\n"
@@ -9633,9 +9945,16 @@ def _build_passthrough_headers(request: Request) -> dict | None:
 
 
 async def _stream_passthrough(resp: httpx.Response):
-    async for chunk in resp.aiter_bytes():
-        yield chunk
-    await resp.aclose()
+    _pt_client = getattr(resp, "_uap_client", None)
+    if _pt_client is not None:
+        _inflight_inc(_pt_client)
+    try:
+        async for chunk in resp.aiter_bytes():
+            yield chunk
+    finally:
+        if _pt_client is not None:
+            _inflight_dec(_pt_client)
+        _detach_aclose(resp)
 
 
 async def _passthrough_anthropic_request(
@@ -9676,6 +9995,7 @@ async def _passthrough_anthropic_request(
         resp = await client.send(
             client.build_request("POST", url, json=body, headers=headers, timeout=pt_timeout)
         )
+        setattr(resp, "_uap_client", client)
         if resp.status_code != 200:
             return Response(
                 content=resp.text,
@@ -10235,12 +10555,14 @@ async def messages(request: Request):
                 # Without tools (finalize): retry with capped max_tokens for clean text.
                 has_tools = bool(strict_body.get("tools"))
                 retry_body = dict(strict_body)
-                retry_body["max_tokens"] = 2048
+                # Tool retries need room for Qwen's mandatory thinking PLUS
+                # complete tool-call arguments — 2048 produced truncated JSON.
+                retry_body["max_tokens"] = 8192 if has_tools else 2048
                 retry_body["temperature"] = 0.1
                 retry_body["stream"] = False
                 if has_tools:
                     retry_body["tool_choice"] = "required"
-                    logger.warning("DEGENERATE RETRY: retrying with tool_choice=required max_tokens=2048")
+                    logger.warning("DEGENERATE RETRY: retrying with tool_choice=required max_tokens=8192")
                 else:
                     logger.warning("DEGENERATE RETRY: retrying text-only with max_tokens=2048 temp=0.1")
                 try:
@@ -10353,10 +10675,11 @@ async def messages(request: Request):
                     ),
                     stream=True,
                 )
+                setattr(resp, "_uap_client", client)
                 # Connection succeeded – break out of retry loop
                 last_exc = None
                 break
-            except (httpx.ConnectError, httpx.RemoteProtocolError, httpx.ReadTimeout) as exc:
+            except _UPSTREAM_RETRY_EXCEPTIONS as exc:
                 last_exc = exc
                 if attempt < MAX_UPSTREAM_RETRIES - 1:
                     logger.warning(
@@ -10427,6 +10750,7 @@ async def messages(request: Request):
                     ),
                     stream=True,
                 )
+                setattr(resp, "_uap_client", client)
                 if resp.status_code == 200:
                     return StreamingResponse(
                         stream_anthropic_response(resp, model, monitor, body),
@@ -10451,6 +10775,7 @@ async def messages(request: Request):
                     ),
                     stream=True,
                 )
+                setattr(resp, "_uap_client", client)
                 if resp.status_code == 200:
                     return StreamingResponse(
                         stream_anthropic_response(resp, model, monitor, body),
@@ -10689,10 +11014,11 @@ async def messages(request: Request):
         openai_resp, was_degenerate = _detect_and_truncate_degenerate_repetition(openai_resp)
         # Degenerate retry for non-guarded stream path
         if was_degenerate and openai_body.get("tools"):
-            logger.warning("DEGENERATE RETRY (stream): retrying with tool_choice=required max_tokens=2048")
+            logger.warning("DEGENERATE RETRY (stream): retrying with tool_choice=required max_tokens=8192")
             retry_body = dict(openai_body)
             retry_body["tool_choice"] = "required"
-            retry_body["max_tokens"] = 2048
+            # See non-stream site: 2048 starves thinking + tool args.
+            retry_body["max_tokens"] = 8192
             retry_body["temperature"] = 0.1
             retry_body["stream"] = False
             try:

package/tools/agents/scripts/confidence_escalation.py

@@ -239,6 +239,54 @@ def load_reactor_signal(prompt_text, signal_dir=None, ttl=180.0, now=None):
     return None
 
 
+# ---- cross-process: consume the LLM-Self-Tuning real-time adaptor (P4) --------
+# The offline tuner finds a good STATIC config; the real-time adaptor writes a
+# per-session adjustment (escalate / recipe / recon threshold / force-synthesis)
+# from LIVE signals it observes out-of-band (tool-failure rate, per-turn quality,
+# context pressure). The proxy freezes PROXY_* at startup and has no reload
+# endpoint, so — exactly like the recipe signal — this is a file-signal read per
+# request. OPT-IN via PROXY_REALTIME_ADAPT so default behavior is unchanged.
+def _adaptation_signal_dir() -> str:
+    return os.environ.get("UAP_ADAPTATION_SIGNAL_DIR") or os.path.join(
+        os.path.expanduser("~"), ".cache", "uap", "adaptation-signals"
+    )
+
+
+def realtime_adapt_enabled() -> bool:
+    # Auto-on: honor a fresh adaptation signal by default. Opt out with
+    # PROXY_REALTIME_ADAPT=0/false/off. (The emitter is the real master switch —
+    # with it off, no signal exists to honor.)
+    return str(os.environ.get("PROXY_REALTIME_ADAPT", "")).strip().lower() not in (
+        "0",
+        "false",
+        "off",
+        "no",
+    )
+
+
+def load_adaptation_signal(session_id=None, signal_dir=None, ttl=180.0, now=None):
+    """Return the fresh real-time adaptation signal dict, or None. Per-session
+    file first when session_id is given, then a rolling latest.json (single-
+    session common case). Fresh within ttl seconds. Never raises."""
+    d = signal_dir or _adaptation_signal_dir()
+    now = time.time() if now is None else now
+    candidates = []
+    if session_id:
+        safe = "".join(c if (c.isalnum() or c in "_-") else "_" for c in str(session_id)) or "session"
+        candidates.append(os.path.join(d, safe + ".json"))
+    candidates.append(os.path.join(d, "latest.json"))
+    for path in candidates:
+        try:
+            if os.path.exists(path):
+                with open(path) as f:
+                    sig = json.load(f)
+                if now - float(sig.get("ts", 0)) <= ttl:
+                    return sig
+        except Exception:
+            continue
+    return None
+
+
 def select_recipe(anthropic_body: dict, settings: Settings, has_tools: bool) -> str:
     if not settings.enabled or has_tools:
         return "single"
@@ -261,10 +309,18 @@ def select_recipe(anthropic_body: dict, settings: Settings, has_tools: bool) ->
         complexity = query_complexity(text)
         shape = task_shape(text)
     if settings.judge_available(pm) and (complexity == "complex" or shape == "reasoning"):
-        return "fusion"
-    if settings.judge_available(pm) and len(text) >= settings.auto_fusion_chars:
-        return "fusion"
-    return "confidence"
+        chosen = "fusion"
+    elif settings.judge_available(pm) and len(text) >= settings.auto_fusion_chars:
+        chosen = "fusion"
+    else:
+        chosen = "confidence"
+    # Real-time adaptation (opt-in): a fresh per-session signal may escalate this
+    # turn to the judge (e.g. tool-failure spike or a quality dip observed live).
+    if realtime_adapt_enabled() and settings.judge_available(pm):
+        asig = load_adaptation_signal()
+        if asig and (asig.get("escalate") or asig.get("recipe") == "fusion"):
+            chosen = "fusion"
+    return chosen
 
 
 # ---- #1/#5 confidence signal ----------------------------------------------