@miller-tech/uap 2.16.7 → 2.20.0

package/tools/agents/scripts/anthropic_proxy.py

@@ -64,6 +64,37 @@ Configuration (Environment Variables)
                                     conversation pruning activates (0.0-1.0)
                                     Default: 0.85
 
+    PROXY_PRUNE_SPIRAL_STREAK       Consecutive above-threshold prunes with a
+                                    RISING post-prune floor required before the
+                                    prune circuit breaker fires. A tool-heavy
+                                    client's fixed overhead (system + tool
+                                    schemas) can sit above the threshold
+                                    permanently; a flat floor is NOT a death
+                                    spiral. Default: 3
+
+    PROXY_PRUNE_SPIRAL_EPSILON      Minimum post-prune utilization rise
+                                    (fraction of window, e.g. 0.01 = 1 point)
+                                    for a prune to count toward the spiral
+                                    streak. Default: 0.01
+
+    PROXY_FINAL_ANSWER_CHARS         Content reaching this many characters
+                                    is a legitimate final answer: the
+                                    unexpected-end-turn retry is skipped
+                                    and the client's loop ends naturally,
+                                    a `required` tool turn returning such
+                                    content is exempt from the
+                                    required_tool_miss streak, retries, and
+                                    forced-tool dampener, and the
+                                    recon-convergence no-write streak does
+                                    not advance on it (a finished model's
+                                    summary is a completion, not a miss).
+                                    Content matching the deferral
+                                    phrases stays retried even when long —
+                                    a capitulation is not a final answer.
+                                    Env alias: PROXY_END_TURN_FINAL_CHARS
+                                    (deprecated spelling, same knob).
+                                    0 = always retry. Default: 800
+
 Usage
 -----
     # Basic usage (connects to llama.cpp on default port):
@@ -75,6 +106,10 @@ Usage
     # Custom proxy port:
     PROXY_PORT=5000 python anthropic_proxy.py
 
+    # Ollama-compatible surface on the well-known port (default; 0 disables —
+    # set that on a box running a real Ollama, which owns 11434):
+    PROXY_OLLAMA_PORT=11434 python anthropic_proxy.py
+
     # Via npx (after npm install):
     npx uap-anthropic-proxy
 
@@ -95,6 +130,8 @@ import json
 import logging
 import os
 import re
+import socket
+import stat
 import sys
 import time
 import uuid
@@ -108,7 +145,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 import httpx
-from contextlib import asynccontextmanager
+from contextlib import asynccontextmanager, contextmanager
 from fastapi import FastAPI, Request, Response
 from fastapi.responses import StreamingResponse
 import uvicorn
@@ -256,6 +293,12 @@ ANTHROPIC_API_BASE = os.environ.get(
 ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY", "")
 ANTHROPIC_PASSTHROUGH_MODELS = os.environ.get("ANTHROPIC_PASSTHROUGH_MODELS", "")
 PROXY_PORT = int(os.environ.get("PROXY_PORT", "4000"))
+# The Ollama-compatible surface: the SAME app served on a SECOND port so
+# Ollama-native tooling (which auto-discovers localhost:11434 and cannot be
+# pointed at a path-prefixed alternative) works against this proxy. 0 disables
+# it — set that on a box running a real Ollama, which owns 11434 by convention.
+# See the "Ollama-compatible surface" section near the end of this file.
+PROXY_OLLAMA_PORT = int(os.environ.get("PROXY_OLLAMA_PORT", "11434"))
 # Bind loopback by DEFAULT (security audit: an unauthenticated 0.0.0.0 listener
 # let any LAN host drive the local model and reach cloud passthrough). To run
 # the proxy as a shared LAN service, set PROXY_HOST=0.0.0.0 AND set
@@ -299,6 +342,54 @@ 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")
 )
+# Prune circuit-breaker floor-trend discrimination (2026-09-30): a tool-heavy
+# client's FIXED overhead (system prompt + tool schemas — observed live:
+# opencode's 99 tools ≈ 66k est tokens in a 114,688-token window) can sit
+# permanently ABOVE PROXY_CONTEXT_PRUNE_THRESHOLD (0.42 in production), so
+# post-prune utilization can never get below the threshold no matter how many
+# messages are dropped. The breaker's old condition — "3+ consecutive prunes
+# and still above threshold" — read that permanent flat floor as a death
+# spiral and force-finalized healthy ~44% sessions every few turns (observed
+# live: 8 breaker fires in 10 minutes, each one ending the client's turn; the
+# operator symptom was "the client keeps stopping"). A REAL death spiral shows
+# a RISING post-prune floor turn over turn; a fixed-overhead floor is flat.
+# The breaker now fires only after PROXY_PRUNE_SPIRAL_STREAK consecutive
+# above-threshold prunes whose post-prune utilization rose by more than
+# PROXY_PRUNE_SPIRAL_EPSILON (fraction of the window). Slow sub-epsilon
+# spirals do not trip this breaker; they escalate to the >=90% critical
+# prune and the catastrophic raw-ctx finalize backstops instead.
+PROXY_PRUNE_SPIRAL_STREAK = int(
+    os.environ.get("PROXY_PRUNE_SPIRAL_STREAK", "3")
+)
+PROXY_PRUNE_SPIRAL_EPSILON = float(
+    os.environ.get("PROXY_PRUNE_SPIRAL_EPSILON", "0.01")
+)
+# Substantive-final-answer exemption for the unexpected-end-turn retry
+# (2026-10-03): the retry exists for thinking-runaway stalls — an end_turn
+# with EMPTY or near-empty content mid-loop (reproduced 2026-09-17: 5917
+# reasoning chars, finish=length, 0 tool_calls). It had NO completion signal,
+# so a model that GENUINELY finished and wrote its final answer was also
+# "unexpected": the retry coerced it back into a tool call, and a finished
+# model under coercion emits a degenerate no-op call (observed live
+# 2026-10-03 01:00-03:00: "Task complete — recap delivered and one concrete
+# defect fixed", 2211 chars, followed by 96 retry cycles each producing the
+# identical `git status` no-op — two hours of churn the operator saw as
+# "keeps stopping or looping"). Content reaching this many characters is a
+# legitimate final answer: let the client's loop end. The runaway case has
+# empty content, so the threshold separates the two classes cleanly. The
+# threshold now gates a family of exemptions — the end-turn retry, the
+# stream-path malformed-streak counter, the required-tool-miss classification
+# (2026-10-03 13:24-13:40 incident), and the recon-convergence no-write streak
+# — hence the rename from PROXY_END_TURN_FINAL_CHARS (still accepted as a
+# deprecated env alias). 0 restores the old always-retry behavior.
+PROXY_FINAL_ANSWER_CHARS = int(
+    os.environ.get("PROXY_FINAL_ANSWER_CHARS")
+    or os.environ.get("PROXY_END_TURN_FINAL_CHARS")
+    or "800"
+)
+# Deprecated alias (2026-10-03): existing env files and older tooling still
+# use the end-turn spelling; both knobs control the same threshold.
+PROXY_END_TURN_FINAL_CHARS = PROXY_FINAL_ANSWER_CHARS
 # Verbatim decision compaction (uplift 1.2): when context pressure triggers a
 # prune, first try per-tool-call keep/truncate/drop decisions that keep all
 # retained content VERBATIM; fall back to the lossy breadcrumb pruner only
@@ -1748,6 +1839,21 @@ try:
     )
 except ValueError:
     PROXY_STREAM_HEARTBEAT_SECS = 0.0
+# Journal progress cadence for the same buffered wait. The heartbeat keeps the
+# CLIENT alive; this keeps the OPERATOR alive: a no-tool streaming turn served
+# via the guarded path (confidence-escalation buffering, tools-stripped breaker
+# turns, forced non-stream) can generate for minutes with zero journal output —
+# live 2026-10-04, opencode's client-side compaction summary (msgs=1, tools=0,
+# stream=True) buffered 11,099 output tokens over 281 s: the proxy looked idle,
+# the client looked hung, and nothing in the log distinguished a bug from a
+# long generation until the RESP line finally landed. One INFO line per this
+# many seconds of waiting. 0 disables.
+try:
+    PROXY_GUARDED_WAIT_LOG_SECS = float(
+        os.environ.get("PROXY_GUARDED_WAIT_LOG_SECS", "60")
+    )
+except ValueError:
+    PROXY_GUARDED_WAIT_LOG_SECS = 60.0
 PROXY_FORCED_TOOL_DAMPENER = os.environ.get(
     "PROXY_FORCED_TOOL_DAMPENER", "on"
 ).lower() not in {
@@ -2410,6 +2516,14 @@ class SessionMonitor:
     pre_prune_input_tokens: int = 0
     prune_count: int = 0  # How many times pruning was triggered
     overflow_count: int = 0  # How many context overflow errors caught
+    # Prune circuit-breaker floor trend (2026-09-30): consecutive
+    # above-threshold prunes whose post-prune utilization ROSE (a real death
+    # spiral regrows faster than the pruner can cut), and the last post-prune
+    # utilization seen, to compute the delta. A flat floor is fixed overhead,
+    # not a spiral — see _prune_breaker_should_fire.
+    prune_spiral_streak: int = 0
+    last_post_prune_util: float = -1.0
+    prune_floor_logged: bool = False  # one-shot "floor is flat" operator notice
     # Monotonic: # of oldest middle msgs pruned (B3). Only meaningful for
     # legacy lossy-path turns — a successful verbatim compaction (uplift 1.2)
     # re-indexes the middle non-contiguously and RESETS this to 0, since a
@@ -2457,7 +2571,7 @@ class SessionMonitor:
     session_id: str = ""  # owning session id (set by get_session_monitor)
     mandate_deliver_fires: int = 0  # monotonic count of forced deliver-routings (mandate)
     mandate_deliver_active: bool = False  # THIS turn is pinned to deliver (beats recon convergence)
-    tool_starvation_streak: int = 0  # Consecutive forced turns with no tool_calls produced
+    tool_starvation_streak: int = 0  # breaker FIRES since the last compaction reset (not per turn)
     last_request_msg_count: int = 0  # Message count of the previous request (compaction-boundary detection)
     malformed_tool_streak: int = 0  # consecutive malformed pseudo tool payloads
     invalid_tool_call_streak: int = 0  # consecutive invalid tool arg payloads
@@ -3038,6 +3152,61 @@ class SessionMonitor:
         """Highest current streak among malformed/invalid tool outputs."""
         return max(self.malformed_tool_streak, self.invalid_tool_call_streak)
 
+    def reset_forcing_loop(self) -> None:
+        """Reset the forcing-loop family to a clean per-turn baseline.
+
+        2026-10-04 follow-up to the starvation-breaker fix (PR #830): the
+        membership of this family lives HERE, not in four hand-maintained
+        reset blocks (fresh user text, no-tool-result conversations, the
+        compaction boundary, the contamination hard reset). Members and why:
+
+          consecutive_forced_count, no_progress_streak -- the forcing loop
+          is PER-TURN state; a stale count crossing a fresh user text
+          false-fired the TOOL STARVATION BREAKER ~once per user turn for
+          hours (fixed 2026-10-04).
+
+        Deliberately NOT members (each with its own lifecycle):
+          consecutive_no_write_turns -- PER-TASK state (recon exploration
+          streak), reset at the same four boundary sites INLINE, not here:
+          it is not forcing-loop state, and an ack-shaped fresh text must
+          not clear it (see the fresh_user_text branch). Its four reset
+          sites and rationale are documented at those sites.
+          malformed/invalid/required_tool_miss streaks -- output QUALITY is
+          cross-turn evidence; a new user message says nothing about the
+          model's tool-call formatting.
+          forced_auto_cooldown_turns -- the dampener is a REMEDY for the
+          quality streaks, and quality is cross-turn, so the cooldown
+          carries across mid-episode user acks ("keep going" must not cut
+          the recovery window short). It also cannot re-arm right after a
+          reset: activation needs consecutive_forced_count >= min_forced,
+          which the reset just zeroed. It clears only at a brand-new
+          conversation (the n_msgs <= 1 block) and the emergency
+          contamination reset.
+          deferral_streak -- the capitulation loop it breaks SPANS user
+          acks (model asks for more cycles, user says yes, model asks
+          again), so a per-turn reset would make that breaker unreachable
+          in exactly its true-positive case.
+          tool_starvation_streak -- per-EPOCH session telemetry: counts
+          breaker fires since the last compaction reset (the compaction
+          boundary clears it), not per-turn severity.
+          recon_hard_fires -- monotonic session counter, never reset.
+          catastrophic_ctx_streak -- consecutive-turn utilization streak;
+          resets the moment utilization drops below the finalize ratio,
+          so it is per-turn-consecutive, not monotonic.
+
+        Two more semantic classes reset the member pair INLINE by design,
+        and a grep for "consecutive_forced_count = 0" will find them:
+        consequence/consume-on-fire clears (breaker fire, dampener
+        release, finalize paths, analysis routing) zero the pair after an
+        ACTION was taken, which is a different event from a boundary reset.
+        And the four boundary call sites here are gated behind
+        PROXY_TOOL_STATE_MACHINE (pre-existing posture, unchanged): with
+        the state machine off, the consumers still run and the stale-state
+        false-fire class returns.
+        """
+        self.consecutive_forced_count = 0
+        self.no_progress_streak = 0
+
     def consume_forced_auto_turn(self) -> bool:
         """Consume one dampener turn that temporarily sets tool_choice=auto."""
         if self.forced_auto_cooldown_turns <= 0:
@@ -3529,6 +3698,39 @@ def _prune_overhead_tokens(anthropic_body: dict) -> int:
     return int(overhead_tokens * 1.5)  # Safety factor for template overhead
 
 
+def _prune_breaker_should_fire(post_util: float, monitor) -> bool:
+    """Death-spiral discriminator for the prune circuit breaker (2026-09-30).
+
+    Called once per request AFTER all prune passes, with the post-prune
+    utilization. Updates the monitor's floor-trend streak and returns whether
+    the breaker should fire.
+
+    Why trend, not just "still above threshold": a tool-heavy client's fixed
+    overhead (system + tool schemas; observed: ~66k est tokens of a 114,688
+    window against a 42% threshold) puts the post-prune floor PERMANENTLY
+    above the threshold. The old breaker condition (3+ consecutive prunes and
+    still above threshold) fired every few turns on that flat floor, forcing
+    finalize on healthy ~44% sessions — the operator-visible "the client
+    keeps stopping". A real death spiral (auto-compact transcript regrowth,
+    exploding tool results) shows a post-prune floor that RISES turn over turn
+    even as the pruner cuts; only that counts. Flat or falling floors reset
+    the streak.
+    """
+    prev = monitor.last_post_prune_util
+    monitor.last_post_prune_util = post_util
+    if post_util < PROXY_CONTEXT_PRUNE_THRESHOLD:
+        # Back under the threshold (real headroom recovered): reset the trend.
+        monitor.prune_spiral_streak = 0
+        return False
+    if prev >= 0 and post_util > prev + PROXY_PRUNE_SPIRAL_EPSILON:
+        monitor.prune_spiral_streak += 1
+    else:
+        # Flat (within epsilon), falling, or the first observation above the
+        # threshold: not spiral evidence.
+        monitor.prune_spiral_streak = 0
+    return monitor.prune_spiral_streak >= PROXY_PRUNE_SPIRAL_STREAK
+
+
 def _truncate_oversized_message_content(messages: list, budget_tokens: int) -> bool:
     """Truncate the largest message content in-place until the total fits
     budget_tokens. Used when message-DROPPING cannot reduce below the window —
@@ -5559,7 +5761,14 @@ async def _pool_timeout_handler(request: Request, exc: httpx.PoolTimeout):
 
 # 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.
-_PROXY_AUTH_OPEN_PATHS = frozenset({"/health", "/", "/v1/models"})
+# /api/version, /api/tags and /api/ps stay open for the same reason /v1/models
+# does: Ollama clients probe them BEFORE their first real request, and a 401 on
+# discovery breaks them before any credential could even be presented. The
+# model-serving /api routes (/api/chat, /api/generate, /api/show) are NOT open
+# — they carry the same content as /v1/messages and gate identically.
+_PROXY_AUTH_OPEN_PATHS = frozenset(
+    {"/health", "/", "/v1/models", "/api/version", "/api/tags", "/api/ps"}
+)
 
 
 # OUTERMOST — and it must be registered AFTER the auth middleware below to BE
@@ -6837,10 +7046,35 @@ def _resolve_state_machine_tool_choice(
     if latest_user_text and not last_user_has_tool_result:
         monitor.tool_call_history = []
         monitor.reset_doubling()
+        # 2026-10-04 fix (recurring false TOOL STARVATION BREAKER, fired ~once
+        # per user turn for hours): the forcing loop is PER-TURN state. The
+        # family membership and each member's lifecycle live in
+        # SessionMonitor.reset_forcing_loop -- reset there, never here.
+        monitor.reset_forcing_loop()
+        # The recon exploration streak is PER-TASK, not per-turn (added
+        # 2026-10-04 with the reset_forcing_loop extraction): the previous
+        # task's read-forever streak is not evidence about the NEW
+        # deliverable, and a stale streak fired the recon convergence
+        # directive on the new task's first request -- the same
+        # stale-state-crossing-a-boundary class as the breaker fix above.
+        # Agent-driven resends carry tool_results and cannot reach this
+        # branch, so genuine same-task recon loops keep counting. One
+        # accepted trade-off: a MID-TASK human ack ("ok", "standing by")
+        # also lands here and would clear a same-task streak — so the
+        # existing _is_no_task_user_text classifier gates the reset: only
+        # fresh text that plausibly starts NEW work clears the streak.
+        # Reviewer P3 (security, 2026-10-04): without the gate, a model
+        # could end each threshold-1 turn soliciting an ack and keep the
+        # convergence directive unreachable forever.
+        if not _is_no_task_user_text(latest_user_text):
+            monitor.consecutive_no_write_turns = 0
         if n_msgs <= 1:
+            # Brand-new conversation only. forced_auto_cooldown_turns is
+            # sticky across mid-episode acks on purpose (see
+            # reset_forcing_loop's docstring) but a 1-message request is a
+            # fresh conversation surface, where the old cooldown describes
+            # a model state that no longer applies.
             monitor.forced_auto_cooldown_turns = 0
-            monitor.consecutive_forced_count = 0
-            monitor.no_progress_streak = 0
             monitor.malformed_tool_streak = 0
             monitor.invalid_tool_call_streak = 0
             monitor.required_tool_miss_streak = 0
@@ -6870,10 +7104,24 @@ def _resolve_state_machine_tool_choice(
         if not has_tool_results:
             monitor.tool_call_history = []
             monitor.reset_doubling()
+            # Same per-turn reset as fresh_user_text (see the 2026-10-04 fix
+            # there, and SessionMonitor.reset_forcing_loop for the family
+            # membership): a conversation with no tool results cannot host a
+            # MID-LOOP starvation episode -- genuine ones resend with
+            # tool_results and never reach this branch -- so a stale forcing
+            # count from a prior turn carries no signal here, only the
+            # false-fire. The recon streak resets under the same ack gate as
+            # fresh_user_text (latest_user_text is empty in most
+            # no-tool-result conversations, and an empty text is not an ack,
+            # so the gate usually passes here). Output-quality streaks stay
+            # sticky under the n_msgs guard.
+            monitor.reset_forcing_loop()
+            if not _is_no_task_user_text(latest_user_text):
+                monitor.consecutive_no_write_turns = 0
             if n_msgs <= 1:
+                # Brand-new conversation only (see the fresh_user_text
+                # branch for why the cooldown is otherwise sticky).
                 monitor.forced_auto_cooldown_turns = 0
-                monitor.consecutive_forced_count = 0
-                monitor.no_progress_streak = 0
                 monitor.malformed_tool_streak = 0
                 monitor.invalid_tool_call_streak = 0
                 monitor.required_tool_miss_streak = 0
@@ -8657,7 +8905,7 @@ def build_openai_request(
             monitor.no_progress_streak = 0
             monitor.reset_tool_turn_state(reason="tool_starvation_breaker")
             logger.warning(
-                "TOOL STARVATION BREAKER: stripped tools after %d forced turns with no tool output (starvation_streak=%d)",
+                "TOOL STARVATION BREAKER: stripped tools after %d forced turns with no tool output (starvation_streak=%d; the streak counts fires since the last compaction reset, not per-turn severity)",
                 PROXY_TOOL_STARVATION_THRESHOLD,
                 monitor.tool_starvation_streak,
             )
@@ -9121,12 +9369,14 @@ def _record_last_assistant_tool_calls(
     tool_fingerprints = []
     tool_targets: dict[str, str] = {}
     assistant_had_text = False  # Fix B: did the last assistant turn emit prose?
+    assistant_prose = ""  # raw text of that prose, for the completion gate
     for msg in reversed(messages):
         if msg.get("role") != "assistant":
             continue
         content = msg.get("content")
         if isinstance(content, str) and content.strip():
             assistant_had_text = True
+            assistant_prose = content
         if isinstance(content, list):
             for block in content:
                 if (
@@ -9135,6 +9385,11 @@ def _record_last_assistant_tool_calls(
                     and str(block.get("text", "")).strip()
                 ):
                     assistant_had_text = True
+                    # Accumulate, never overwrite: a completion split across
+                    # several sub-threshold text blocks is still one
+                    # completion (parity with _final_answer_content_exempt's
+                    # own list handling, which joins text parts).
+                    assistant_prose += str(block.get("text", ""))
                 if isinstance(block, dict) and block.get("type") == "tool_use":
                     tool_fingerprints.append(_tool_call_fingerprint(block))
                     # Extract target key for read-only dedup (Option 3)
@@ -9165,8 +9420,12 @@ def _record_last_assistant_tool_calls(
     # Fix B: no tool call in the last assistant turn. A plain-text turn is still
     # a non-write turn, so advance the recon-convergence streak (previously it
     # only moved on tool turns, freezing the counter through prose-only stalls).
-    # Guard on real prose so an empty/absent assistant turn never inflates it.
-    if assistant_had_text:
+    # Guard on real prose so an empty/absent assistant turn never inflates it —
+    # EXCEPT a substantive final answer (architect follow-up 2026-10-03): a
+    # finished model's completion is not a stall signal, and counting it was
+    # the last site in the false-positive family that treats a completion as a
+    # miss. Same gate as the end-turn and required-miss exemptions.
+    if assistant_had_text and not _final_answer_content_exempt(assistant_prose):
         monitor.note_no_tool_turn()
     monitor.note_doubling_signal(
         "", _latest_tr, msg_count=len(messages), result_error=_latest_err
@@ -9174,6 +9433,77 @@ def _record_last_assistant_tool_calls(
     return ""
 
 
+def _final_answer_content_exempt(content) -> bool:
+    """True when an end_turn's content is a substantive final answer.
+
+    Shared by the unexpected-end-turn classifier (skip the retry so the
+    client's loop ends naturally), the stream-path malformed_tool_streak
+    counter (a legitimate completion must not feed the forced-tool dampener
+    via the `end_turn + long text` branch), and the required-tool-miss
+    classifier (a finished model's summary is a completion, not a miss).
+    2026-10-03.
+    """
+    if PROXY_FINAL_ANSWER_CHARS <= 0:
+        return False
+    if not isinstance(content, str):
+        # OpenAI content-parts list: count only the text parts, never the
+        # repr of the list (which would always exceed the threshold). A
+        # part whose "text" is not a str is skipped, not joined — a
+        # malformed backend payload must not abort the turn with a
+        # TypeError mid-classification.
+        if not isinstance(content, list):
+            return False
+        content = " ".join(
+            part.get("text", "")
+            for part in content
+            if isinstance(part, dict)
+            and isinstance(part.get("text", ""), str)
+        )
+    if len(content.strip()) < PROXY_FINAL_ANSWER_CHARS:
+        return False
+    # BUT a LONG DEFERRAL is not a final answer: a model that wrote 800+ chars
+    # of "I need more cycles before acting" is stalling, not finishing, and
+    # must still be herded back to work. The deferral regex already exists
+    # (and already accepts its false-positive risk on no-tool turns), so the
+    # exemption is gated on it rather than on new vocabulary.
+    return not _DEFERRAL_PHRASE_RE.search(content)
+
+
+def _required_tool_miss_exempt(openai_resp: dict) -> bool:
+    """True when a required tool turn returned no tool calls but the response
+    is a substantive final answer, not a miss.
+
+    Same false-positive family as the unexpected-end-turn retry (mechanism #3)
+    and the garbled-args classifier (mechanism #4), observed live
+    2026-10-03 13:24-13:40: the tool state machine had forced
+    tool_choice=required for 32 consecutive turns; the model had FINISHED the
+    task (session summaries, "234 tests passing") and kept emitting exactly
+    that. Each summary was counted as required_tool_miss, retries demanded a
+    tool call, the streak fed the contamination breaker (3 resets), and the
+    forced-finalize branch — which clears malformed/invalid streaks but did
+    not clear required_tool_miss_streak — re-fired finalize on EVERY
+    subsequent request (contamination_resets 3→6, ~4 min of GPU burn) until
+    the client gave up. A finished model must be allowed to hand its summary
+    to the client: the loop ends naturally, exactly as with the end-turn
+    exemption.
+    """
+    if _openai_has_tool_calls(openai_resp):
+        return False
+    # A response truncated by max_tokens did not FINISH — its length says
+    # nothing about intent, and the truncation paths (truncated_tool_args
+    # downgrade, empty-max-tokens recovery) own that class. Mirrors
+    # _is_unexpected_end_turn, which only accepts stop/end_turn finishes.
+    choice, _ = _extract_openai_choice(openai_resp)
+    if (choice.get("finish_reason") or "").lower() == "length":
+        return False
+    # Pass the RAW content (not _openai_message_text, whose str() fallback
+    # would stringify a list-parts content to its repr and defeat
+    # _final_answer_content_exempt's count-only-text-parts guard — a 400-char
+    # list payload measured as a 700-char repr). Mirrors _is_unexpected_end_turn.
+    _, message = _extract_openai_choice(openai_resp)
+    return _final_answer_content_exempt(message.get("content", ""))
+
+
 def _is_unexpected_end_turn(openai_resp: dict, anthropic_body: dict) -> bool:
     choices = openai_resp.get("choices") or []
     if not choices:
@@ -9191,6 +9521,16 @@ def _is_unexpected_end_turn(openai_resp: dict, anthropic_body: dict) -> bool:
     if "tools" not in anthropic_body:
         return False
 
+    # Substantive-final-answer exemption (2026-10-03): an end_turn that CARRIES
+    # a real final answer is the agentic loop's natural end, not a stall. The
+    # thinking-runaway this retry exists for produces empty content, so content
+    # length separates the classes. Without this, a finished model gets coerced
+    # back into a degenerate no-op tool call every turn (observed live:
+    # "Task complete ... Summary:" 2211 chars -> 96 retry cycles of the
+    # identical `git status` no-op over two hours).
+    if _final_answer_content_exempt(msg.get("content", "")):
+        return False
+
     has_tool_results = _conversation_has_tool_results(anthropic_body)
 
     return has_tool_results or _last_assistant_was_text_only(anthropic_body)
@@ -10080,16 +10420,14 @@ def _is_garbled_tool_arguments(arguments_str: str) -> bool:
     """Detect garbled/degenerate tool call arguments.
 
     Returns True if the arguments string shows signs of degenerate generation:
-    - Runaway closing braces (}}}}})
-    - Repetitive digit patterns (000000, 398859738398859738)
-    - Extremely long digit strings
-    - Unbalanced braces suggesting truncated/corrupt JSON
+    - Repetitive digit patterns (000000, 398859738398859738) and long digit
+      runs (degenerate CONTENT, meaningful even inside valid JSON values)
+    - Structural corruption — runaway closing braces (}}}}}) and unbalanced
+      braces — only when the payload does not parse as JSON
     """
     if not arguments_str or arguments_str == "{}":
         return False
 
-    if _GARBLED_RUNAWAY_BRACES_RE.search(arguments_str):
-        return True
     if _GARBLED_REPETITIVE_DIGITS_RE.search(arguments_str):
         return True
     if _GARBLED_ZEROS_RE.search(arguments_str):
@@ -10097,11 +10435,31 @@ def _is_garbled_tool_arguments(arguments_str: str) -> bool:
     if _GARBLED_LONG_DIGITS_RE.search(arguments_str):
         return True
 
-    # Check brace balance — more than 2 unmatched braces suggests corruption
-    open_count = arguments_str.count("{")
-    close_count = arguments_str.count("}")
-    if abs(open_count - close_count) > 2:
-        return True
+    # Structural checks — ONLY meaningful for a payload that does not parse
+    # as JSON: a clean json.loads proves the arguments are not truncated, and
+    # braces inside JSON string VALUES are payload content, not structure.
+    # edit/write tool args legitimately carry partial code excerpts with
+    # unbalanced braces (observed live 2026-10-03: a Rust tail snippet with
+    # 3 closing braces and no opening braces in oldString tripped the raw
+    # balance check on a perfectly valid payload; the reject-retry loop that
+    # followed burned three session-contamination resets and a forced
+    # finalize mid-task). Runaway `}}}}}` gets the same gate: four or more
+    # consecutive closing braces are common inside minified JS/JSON string
+    # values, while the classic degenerate form (runaway closers appended
+    # after the JSON) does not parse and is still caught here.
+    try:
+        json.loads(arguments_str)
+    except (ValueError, TypeError, RecursionError):
+        # Unparseable: brace imbalance and runaway closers are genuine
+        # truncation/corruption signals here. RecursionError covers deeply
+        # nested degenerate input (the exact artifact family this classifier
+        # absorbs) that the C scanner rejects without raising ValueError.
+        if _GARBLED_RUNAWAY_BRACES_RE.search(arguments_str):
+            return True
+        open_count = arguments_str.count("{")
+        close_count = arguments_str.count("}")
+        if abs(open_count - close_count) > 2:
+            return True
 
     return False
 
@@ -10373,6 +10731,11 @@ class ToolResponseIssue:
     kind: str = ""
     reason: str = ""
     retry_hint: str = ""
+    # True when the response was exempted from required_tool_miss by the
+    # substantive-completion gate — set by _classify_tool_response_issue so
+    # the streak/dampener/retry sites read ONE evaluation instead of re-running
+    # the gate and risking site drift (2026-10-03, code-review follow-up).
+    exempt: bool = False
 
     def has_issue(self) -> bool:
         return bool(self.kind)
@@ -11195,6 +11558,14 @@ def _classify_tool_response_issue(
     has_tool_calls = _openai_has_tool_calls(openai_resp)
     if not has_tool_calls:
         if required_tool_choice:
+            # Substantive-final-answer exemption (2026-10-03): a required turn
+            # that carries a real completion is the loop's natural end, not a
+            # miss — see _required_tool_miss_exempt. Passing it through lets
+            # the client finish instead of retrying the model into the
+            # contamination breaker. exempt=True carries the single evaluation
+            # to the streak/dampener/retry sites.
+            if _required_tool_miss_exempt(openai_resp):
+                return ToolResponseIssue(exempt=True)
             return ToolResponseIssue(
                 kind="required_tool_miss",
                 reason="required tool turn returned no tool calls",
@@ -11948,16 +12319,24 @@ async def _apply_malformed_tool_guardrail(
 
     required_tool_choice = openai_body.get("tool_choice") == "required"
     has_tool_calls = _openai_has_tool_calls(working_resp)
-    if required_tool_choice and not has_tool_calls:
-        monitor.required_tool_miss_streak += 1
 
     issue = _classify_tool_response_issue(
         working_resp,
         anthropic_body,
         required_tool_choice=required_tool_choice,
     )
+    # The streak and dampener gates read issue.exempt — the ONE evaluation of
+    # the substantive-completion gate, done inside classification. Re-running
+    # the gate at each site risks evaluation drift, which is how this
+    # false-positive family propagates (one site fixed, another missed).
+    if required_tool_choice and not has_tool_calls and not issue.exempt:
+        monitor.required_tool_miss_streak += 1
+
     if not issue.has_issue():
-        if required_tool_choice and not has_tool_calls:
+        # A substantive completion is exempt from the miss classification, so
+        # it must not activate the forced-tool dampener either: relaxing
+        # tool_choice for a finished model is at best noise.
+        if required_tool_choice and not has_tool_calls and not issue.exempt:
             monitor.maybe_activate_forced_tool_dampener("required_tool_miss")
         if has_tool_calls:
             monitor.malformed_tool_streak = 0
@@ -12099,14 +12478,20 @@ async def _apply_malformed_tool_guardrail(
 
         retry_has_tool_calls = _openai_has_tool_calls(retry_working)
         retry_required = retry_body.get("tool_choice") == "required"
-        if retry_required and not retry_has_tool_calls:
-            monitor.required_tool_miss_streak += 1
-
         retry_issue = _classify_tool_response_issue(
             retry_working,
             anthropic_body,
             required_tool_choice=retry_required,
         )
+        # Same substantive-completion exemption as the primary path, read from
+        # the single classification evaluation (retry_issue.exempt) — a retry
+        # that produced a real final answer is not a miss.
+        if (
+            retry_required
+            and not retry_has_tool_calls
+            and not retry_issue.exempt
+        ):
+            monitor.required_tool_miss_streak += 1
 
         if not retry_issue.has_issue():
             # 2026-05-12: Fix #2 — do NOT reset malformed/invalid/miss streaks
@@ -12365,6 +12750,13 @@ def _maybe_apply_session_contamination_breaker(
         monitor.contamination_resets += 1
         monitor.malformed_tool_streak = 0
         monitor.invalid_tool_call_streak = 0
+        # 2026-10-03: the finalize branch cleared the malformed/invalid streaks
+        # but NOT required_tool_miss_streak — and that very streak is a
+        # should_reset trigger, so once condemned, EVERY subsequent request
+        # re-forced finalize (observed: contamination_resets 3→6, four
+        # finalize turns in a row, each burning a full generation). Clear it
+        # so finalize fires ONCE per contamination episode.
+        monitor.required_tool_miss_streak = 0
         # Remove tools to force text-only response
         updated = dict(anthropic_body)
         updated.pop("tools", None)
@@ -12478,12 +12870,21 @@ def _maybe_apply_session_contamination_breaker(
     forced_before = monitor.consecutive_forced_count
     required_miss_before = monitor.required_tool_miss_streak
     monitor.contamination_resets += 1
+    # Emergency tier: the conversation itself is rewritten, so BOTH the
+    # forcing-loop family (via its one policy point) and the output-quality
+    # streaks clear -- the n_msgs stickiness that protects quality streaks
+    # at ordinary turn boundaries does not apply to a hard reset. The
+    # dampener cooldown clears with them: the model state it was remedying
+    # belonged to the collapsed transcript.
+    monitor.reset_forcing_loop()
+    monitor.forced_auto_cooldown_turns = 0
     monitor.malformed_tool_streak = 0
     monitor.invalid_tool_call_streak = 0
     monitor.required_tool_miss_streak = 0
-    monitor.no_progress_streak = 0
-    monitor.consecutive_forced_count = 0
-    monitor.forced_auto_cooldown_turns = 0
+    # The recon streak belongs to the collapsed transcript (per-TASK state,
+    # reset at turn boundaries since 2026-10-04); the rewritten conversation
+    # is a fresh task surface.
+    monitor.consecutive_no_write_turns = 0
     monitor.reset_tool_turn_state(reason=f"contamination_guardrail_reset_{log_reason}")
     if attractor_detected:
         logger.warning(
@@ -13232,6 +13633,12 @@ async def _heartbeat_then_buffered(produce_coro, model: str, input_tokens: int =
     interval = PROXY_STREAM_HEARTBEAT_SECS if PROXY_STREAM_HEARTBEAT_SECS > 0 else 15.0
     thinking_heartbeat = PROXY_STREAM_THINKING_DELTAS and PROXY_PREFILL_HEARTBEAT_SECS > 0
     hb_thinking_open = False
+    # Operator-visible progress for the same wait the client heartbeats mask
+    # (2026-10-04 incident: a 281 s buffered compaction summary left the
+    # journal silent from REQ to RESP, reading as a hung proxy). One INFO line
+    # per PROXY_GUARDED_WAIT_LOG_SECS boundary crossed, never more.
+    waited_secs = 0.0
+    last_wait_log_boundary = 0
     task = asyncio.ensure_future(produce_coro)
     try:
         while True:
@@ -13241,6 +13648,17 @@ async def _heartbeat_then_buffered(produce_coro, model: str, input_tokens: int =
                 produced = await asyncio.wait_for(asyncio.shield(task), timeout=interval)
                 break
             except asyncio.TimeoutError:
+                waited_secs += interval
+                if PROXY_GUARDED_WAIT_LOG_SECS > 0:
+                    boundary = int(waited_secs // PROXY_GUARDED_WAIT_LOG_SECS)
+                    if boundary > last_wait_log_boundary:
+                        last_wait_log_boundary = boundary
+                        logger.info(
+                            "GUARDED-BUFFER WAIT: buffered non-stream turn still "
+                            "generating after %ds (model=%s input_tokens=%d) — "
+                            "client is receiving heartbeats, not hung",
+                            int(waited_secs), model, input_tokens,
+                        )
                 if thinking_heartbeat:
                     if not hb_thinking_open:
                         hb_thinking_open = True
@@ -13942,7 +14360,14 @@ async def stream_anthropic_response(
         and not tool_calls_by_index
         and (
             finish_reason == "max_tokens"
-            or (finish_reason == "end_turn" and len(accumulated_text) > 512)
+            or (
+                finish_reason == "end_turn"
+                and len(accumulated_text) > 512
+                # A substantive final answer is a completion, not a malformed
+                # payload: don't feed it to the forced-tool dampener (the
+                # same exemption the unexpected-end-turn retry uses).
+                and not _final_answer_content_exempt(accumulated_text)
+            )
         )
     ):
         monitor.malformed_tool_streak += 1
@@ -14425,10 +14850,23 @@ async def messages(request: Request):
     prev_msg_count = getattr(monitor, "last_request_msg_count", 0)
     if prev_msg_count >= 8 and n_messages <= prev_msg_count // 2:
         monitor.reset_tool_turn_state(reason="compaction_boundary")
-        monitor.consecutive_forced_count = 0
-        monitor.no_progress_streak = 0
+        # The forcing-loop family via its one policy point (2026-10-04
+        # extraction). forced_auto_cooldown_turns deliberately does NOT
+        # clear here -- the dampener remedies cross-turn output quality,
+        # which survives a compaction (see reset_forcing_loop's
+        # docstring). Test coverage note: this site is inline in the
+        # request handler and unreachable from the build_openai_request
+        # test seam, so its wiring is inspection-verified -- the method
+        # it calls IS pinned by test_reset_forcing_loop_membership_is_exact.
+        monitor.reset_forcing_loop()
         monitor.tool_starvation_streak = 0
         monitor.consecutive_no_write_turns = 0
+        # Prune-breaker floor trend too (2026-09-30, reviewer P2-1): a stale
+        # pre-compaction floor baseline must not contribute a phantom "rise"
+        # to the fresh epoch — the exact breaker false-positive class
+        # _prune_breaker_should_fire exists to prevent.
+        monitor.prune_spiral_streak = 0
+        monitor.last_post_prune_util = -1.0
         logger.info(
             "COMPACTION BOUNDARY: message count collapsed %d -> %d; reset "
             "tool-turn/anti-spin state for the fresh epoch",
@@ -14527,18 +14965,42 @@ async def messages(request: Request):
                     n_messages,
                     post_util * 100,
                 )
-            # Option 2: Circuit breaker — if 3+ consecutive prunes and still above,
-            # force finalize (drop tools, let model wrap up)
-            if monitor.prune_count >= 3 and post_util >= PROXY_CONTEXT_PRUNE_THRESHOLD:
+            # Option 2: Circuit breaker — fires only on a RISING post-prune
+            # floor (_prune_breaker_should_fire, 2026-09-30). The old "3+
+            # consecutive prunes and still above threshold" condition fired
+            # every few turns on tool-heavy clients whose fixed system+tools
+            # overhead alone exceeds the threshold (observed live: 66k est
+            # tokens of a 114,688 window at a 42% threshold), force-finalizing
+            # healthy ~44% sessions.
+            if _prune_breaker_should_fire(post_util, monitor):
                 logger.error(
-                    "PRUNE CIRCUIT BREAKER: %d consecutive prunes, still at %.1f%%. "
-                    "Forcing finalize to prevent death spiral.",
-                    monitor.prune_count,
+                    "PRUNE CIRCUIT BREAKER: post-prune floor rising for %d consecutive prunes "
+                    "(now %.1f%%, threshold %.1f%%). Forcing finalize to prevent death spiral.",
+                    monitor.prune_spiral_streak,
                     post_util * 100,
+                    PROXY_CONTEXT_PRUNE_THRESHOLD * 100,
                 )
                 monitor.set_tool_turn_phase("finalize", reason="prune_circuit_breaker")
                 monitor.tool_state_auto_budget_remaining = 1
                 monitor.reset_completion_recovery()
+            elif (
+                post_util >= PROXY_CONTEXT_PRUNE_THRESHOLD
+                and monitor.prune_spiral_streak == 0
+                and not monitor.prune_floor_logged
+            ):
+                # Above threshold with a FLAT floor (no rise this turn): fixed
+                # overhead, not a spiral. Tell the operator ONCE per session —
+                # the per-turn prune above still logs its own warning lines.
+                monitor.prune_floor_logged = True
+                logger.warning(
+                    "Post-prune utilization %.1f%% stays above the %.1f%% threshold "
+                    "with a FLAT floor — fixed system+tools overhead, not a death "
+                    "spiral; circuit breaker held. Consider raising "
+                    "PROXY_CONTEXT_PRUNE_THRESHOLD above the overhead floor for "
+                    "this client.",
+                    post_util * 100,
+                    PROXY_CONTEXT_PRUNE_THRESHOLD * 100,
+                )
 
     # Whether this upstream accepts chat_template_kwargs decides what
     # _set_thinking is allowed to write, so it must be answered BEFORE the body
@@ -14587,6 +15049,13 @@ async def messages(request: Request):
     use_guarded_non_stream = _should_buffer_turn(is_stream, body, openai_body, monitor)
     if use_guarded_non_stream:
         async def _produce_guarded():
+            # Covers the full buffered lifetime including any concurrency-queue
+            # wait: from the first upstream attempt to the served response.
+            # Reported in the "served ... (buffered %ds)" log line below so a
+            # long buffered turn is legible after the fact (2026-10-04: a
+            # client-compaction summary buffered 281 s and the only end-line
+            # evidence was the RESP timestamp).
+            t_guarded = time.monotonic()
             strict_body = dict(openai_body)
             strict_body["stream"] = False
 
@@ -14813,15 +15282,18 @@ async def messages(request: Request):
             )
             if PROXY_FORCE_NON_STREAM:
                 logger.info(
-                    "FORCED NON-STREAM: served stream response via guarded non-stream path"
+                    "FORCED NON-STREAM: served stream response via guarded non-stream path (buffered %ds)",
+                    int(time.monotonic() - t_guarded),
                 )
             elif PROXY_MALFORMED_TOOL_STREAM_STRICT and _has_tool_definitions(body):
                 logger.info(
-                    "STRICT STREAM GUARDRAIL: served stream response via guarded non-stream path"
+                    "STRICT STREAM GUARDRAIL: served stream response via guarded non-stream path (buffered %ds)",
+                    int(time.monotonic() - t_guarded),
                 )
             else:
                 logger.info(
-                    "REQUIRED TOOL STREAM GUARDRAIL: served stream response via guarded non-stream path"
+                    "REQUIRED TOOL STREAM GUARDRAIL: served stream response via guarded non-stream path (buffered %ds)",
+                    int(time.monotonic() - t_guarded),
                 )
 
             anthropic_resp = await _maybe_apply_recipe(anthropic_resp, body, openai_body, client)
@@ -15274,47 +15746,29 @@ async def messages_anthropic(request: Request):
     return await messages(request)
 
 
-@app.post("/v1/chat/completions")
-async def chat_completions(request: Request):
-    """OpenAI-compatible chat/completions endpoint for clients like Forge
-    that require the OpenAI API shape.
+async def _guarded_openai_completion(
+    request: Request, openai_body: dict
+) -> tuple[dict | None, int, str | None]:
+    """Run an OpenAI Chat Completions body through the guarded Anthropic
+    pipeline and return the OpenAI-shaped response.
 
-    FULL GUARDRAIL PATH: Converts the OpenAI request to Anthropic format,
-    runs the full /v1/messages pipeline (loop detection, tool narrowing,
-    cycle breaking, malformed tool retry, context pruning, etc.), then
-    converts the Anthropic response back to OpenAI format.
+    Shared core of BOTH dual-protocol inbound surfaces: the OpenAI route
+    (/v1/chat/completions) and the Ollama surface (/api/chat, /api/generate).
+    Everything except the protocol framing lives here, so the surfaces cannot
+    drift apart in guardrail coverage — an Ollama client gets the same
+    admission control, rail budgeting, loop detection, tool narrowing,
+    malformed-tool retry and context pruning an Anthropic client gets.
 
-    Streaming is down-converted to a single final OpenAI SSE chunk sequence
-    built from the completed Anthropic response (not token-by-token from
-    upstream). This preserves guardrails at the cost of stream granularity.
+    Returns (openai_response, http_status, error_message). On failure the
+    response is None and exactly one of status/error carries the cause.
     """
-    body_bytes = await request.body()
-    try:
-        openai_body = json.loads(body_bytes) if body_bytes else {}
-    except (ValueError, TypeError):
-        return Response(
-            content=b'{"error":{"message":"invalid JSON","type":"invalid_request_error"}}',
-            status_code=400,
-            media_type="application/json",
-        )
-
-    requested_stream = bool(openai_body.get("stream", False))
     model = openai_body.get("model", "default")
-    client_id = resolve_client_id(request)
-
-    logger.info(
-        "CHAT (guarded): client=%s model=%s stream=%s msgs=%d tools=%d",
-        client_id,
-        model,
-        requested_stream,
-        len(openai_body.get("messages", [])),
-        len(openai_body.get("tools", []) or []),
-    )
 
     # Convert OpenAI request -> Anthropic request
     anthropic_body = openai_to_anthropic_request(openai_body)
-    # Force non-streaming through the pipeline; we re-stream at the end if the
-    # client wanted streaming. This keeps guardrail logic simpler/consistent.
+    # Force non-streaming through the pipeline; callers re-stream from the
+    # completed response in whatever dialect they serve. This keeps guardrail
+    # logic simpler/consistent.
     anthropic_body["stream"] = False
 
     # Build a synthetic Request that the existing messages() handler can consume
@@ -15366,19 +15820,63 @@ async def chat_completions(request: Request):
         anthropic_resp_dict = inner_resp
 
     if anthropic_resp_dict is None or "content" not in anthropic_resp_dict:
-        # Upstream error: forward as-is in OpenAI error shape
         err_msg = "upstream returned no message"
         if isinstance(anthropic_resp_dict, dict) and "error" in anthropic_resp_dict:
             err_msg = anthropic_resp_dict["error"].get("message", err_msg)
+        return None, status_code, err_msg
+
+    anthropic_resp_dict.setdefault("model", model)
+    return anthropic_to_openai_response(anthropic_resp_dict), 200, None
+
+
+@app.post("/v1/chat/completions")
+async def chat_completions(request: Request):
+    """OpenAI-compatible chat/completions endpoint for clients like Forge
+    that require the OpenAI API shape.
+
+    FULL GUARDRAIL PATH: Converts the OpenAI request to Anthropic format,
+    runs the full /v1/messages pipeline (loop detection, tool narrowing,
+    cycle breaking, malformed tool retry, context pruning, etc.), then
+    converts the Anthropic response back to OpenAI format.
+
+    Streaming is down-converted to a single final OpenAI SSE chunk sequence
+    built from the completed Anthropic response (not token-by-token from
+    upstream). This preserves guardrails at the cost of stream granularity.
+    """
+    body_bytes = await request.body()
+    try:
+        openai_body = json.loads(body_bytes) if body_bytes else {}
+    except (ValueError, TypeError):
         return Response(
-            content=json.dumps({"error": {"message": err_msg, "type": "upstream_error"}}).encode(),
-            status_code=status_code if status_code >= 400 else 502,
+            content=b'{"error":{"message":"invalid JSON","type":"invalid_request_error"}}',
+            status_code=400,
             media_type="application/json",
         )
 
-    # Ensure model field is set for response
-    anthropic_resp_dict.setdefault("model", model)
-    openai_resp = anthropic_to_openai_response(anthropic_resp_dict)
+    requested_stream = bool(openai_body.get("stream", False))
+    model = openai_body.get("model", "default")
+    client_id = resolve_client_id(request)
+
+    logger.info(
+        "CHAT (guarded): client=%s model=%s stream=%s msgs=%d tools=%d",
+        client_id,
+        model,
+        requested_stream,
+        len(openai_body.get("messages", [])),
+        len(openai_body.get("tools", []) or []),
+    )
+
+    openai_resp, status_code, err_msg = await _guarded_openai_completion(
+        request, openai_body
+    )
+    if openai_resp is None:
+        return Response(
+            content=json.dumps(
+                {"error": {"message": err_msg, "type": "upstream_error"}}
+            ).encode(),
+            status_code=status_code if status_code >= 400 else 502,
+            media_type="application/json",
+        )
 
     if not requested_stream:
         return Response(
@@ -15638,6 +16136,557 @@ def _model_entry(model_id: str) -> dict:
     return entry
 
 
+# ===========================================================================
+# Ollama-compatible surface (/api/*) — PROXY_OLLAMA_PORT, default 11434
+# ===========================================================================
+# The proxy already speaks two inbound dialects (Anthropic Messages on
+# /v1/messages, OpenAI Chat Completions on /v1/chat/completions), both
+# normalised through the same guarded pipeline. Ollama clients are a third
+# dialect: their own discovery handshake (/api/version, /api/tags, /api/show),
+# their own NDJSON streaming, and their own field vocabulary — but the
+# semantics underneath are identical. So this surface is a pure translation
+# layer: Ollama request -> OpenAI request -> _guarded_openai_completion ->
+# OpenAI response -> Ollama response. Every guardrail (admission, rail
+# budgeting, loop detection, tool narrowing, malformed-tool retry, context
+# pruning) therefore applies to Ollama clients too.
+#
+# The known tradeoff, identical to the OpenAI inbound surface: streaming is
+# buffered through the guardrails and re-emitted as Ollama NDJSON afterwards
+# (one content line + one final line), not token-by-token from upstream. A
+# client sees its reply appear all at once; correctness of the guardrails is
+# preserved. Token-granular streaming would require bypassing the pipeline.
+#
+# Served from the SAME process on a SECOND port (Ollama's well-known 11434)
+# because Ollama tooling auto-discovers localhost:11434 and offers no way to
+# point it at a path-prefixed alternative. Same process, not a second one, is
+# the whole point: a second process would carry its own admission table and
+# rail semaphore, silently doubling the concurrency budget the backend was
+# sized for.
+
+_OLLAMA_API_VERSION = "0.12.6"  # the Ollama release whose wire shape this mirrors
+_OLLAMA_START_ISO = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _ollama_error(status: int, message: str) -> Response:
+    return Response(
+        content=json.dumps({"error": message}).encode(),
+        status_code=status,
+        media_type="application/json",
+    )
+
+
+def _ollama_content_to_text(content) -> str:
+    """Ollama message content: a plain string, or (newer clients) a list of
+    typed parts. Images have no rail in this pipeline — extract text only."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "".join(
+            p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") == "text"
+        )
+    return "" if content is None else str(content)
+
+
+def _ollama_options_to_openai(options) -> dict:
+    """Translate Ollama's `options` object to OpenAI Chat Completions fields.
+
+    Deliberately minimal: only what survives BOTH translation hops. The second
+    hop (openai_to_anthropic_request) forwards temperature/top_p/top_k/stop/
+    max_tokens, so those are mapped and NOTHING else — an Ollama client's
+    min_p/repeat_penalty/seed are dropped here rather than accepted and
+    silently ignored mid-pipeline (the honest drop also keeps this function
+    truthful about what it claims to do). num_ctx is dropped for a different
+    reason: the rail budget owns context sizing, and forwarding a client's
+    num_ctx would silently fight the admission controller."""
+    if not isinstance(options, dict) or not options:
+        return {}
+    out: dict = {}
+    for src, dst in (("temperature", "temperature"), ("top_p", "top_p"), ("top_k", "top_k")):
+        if src in options:
+            out[dst] = options[src]
+    if "num_predict" in options:
+        try:
+            out["max_tokens"] = max(1, int(options["num_predict"]))
+        except (TypeError, ValueError):
+            pass
+    stop = options.get("stop")
+    if isinstance(stop, str) and stop:
+        out["stop"] = [stop]
+    elif isinstance(stop, list) and stop:
+        out["stop"] = [str(s) for s in stop]
+    return out
+
+
+def _finish_common_ollama_fields(body: dict) -> dict:
+    """Fields shared by the /api/chat and /api/generate request builders:
+    option mapping, tools passthrough, and the buffered stream decision (the
+    pipeline always runs non-stream; callers re-emit)."""
+    fields: dict = {}
+    fields.update(_ollama_options_to_openai(body.get("options")))
+    if isinstance(body.get("tools"), list) and body["tools"]:
+        fields["tools"] = body["tools"]
+        fields["tool_choice"] = body.get("tool_choice") or "auto"
+    # Ollama's `format` field (structured output) is accepted and DROPPED:
+    # the second translation hop (openai_to_anthropic_request) does not carry
+    # response_format, so wiring it through is a pipeline contract change that
+    # deserves its own schema-diff pass — not something to fake acceptance of.
+    # keep_alive / raw / template are Ollama lifecycle features with no local
+    # equivalent: the backend stays loaded (capacity policy owns that) and the
+    # chat template is the backend's own.
+    fields["stream"] = False
+    return fields
+
+
+def ollama_chat_to_openai_request(body: dict) -> dict:
+    """Ollama /api/chat body -> OpenAI Chat Completions body."""
+    messages = []
+    # Deterministic tool-call ids for replayed assistant turns. Ollama
+    # associates a tool result with its call by ORDER within the message list;
+    # OpenAI (and the Anthropic hop after it) pairs by id. Without explicit
+    # ids, the second hop mints random ids while the tool results carry "" —
+    # pairs that can never match.
+    pending_call_ids: list[str] = []
+    for m in body.get("messages") or []:
+        if not isinstance(m, dict):
+            continue
+        role = m.get("role") or "user"
+        content = _ollama_content_to_text(m.get("content"))
+        # Ollama roles map onto the OpenAI four. An unknown role is demoted
+        # to user rather than rejected — clients invent roles, and dropping
+        # the text would silently lose conversation history.
+        if role not in ("system", "user", "assistant", "tool"):
+            role = "user"
+        entry: dict = {"role": role, "content": content}
+        if role == "assistant" and isinstance(m.get("tool_calls"), list) and m["tool_calls"]:
+            # Conversation replay of a prior tool call. Ollama carries the
+            # arguments as an object; OpenAI as a JSON string.
+            rebuilt = []
+            pending_call_ids = []
+            for i, tc in enumerate(m["tool_calls"]):
+                fn = (tc or {}).get("function", {}) or {}
+                args = fn.get("arguments", "")
+                if not isinstance(args, str):
+                    try:
+                        args = json.dumps(args)
+                    except (TypeError, ValueError):
+                        args = "{}"
+                call_id = f"call_{len(messages)}_{i}"
+                pending_call_ids.append(call_id)
+                rebuilt.append(
+                    {
+                        "id": call_id,
+                        "function": {"name": fn.get("name", ""), "arguments": args},
+                    }
+                )
+            entry["tool_calls"] = rebuilt
+        elif role == "tool" and pending_call_ids:
+            # Consume the ids in order: this tool result answers the oldest
+            # still-unpaired call, which is how Ollama ordered them.
+            entry["tool_call_id"] = pending_call_ids.pop(0)
+        messages.append(entry)
+    openai_body: dict = {
+        "model": body.get("model") or FALLBACK_LOCAL_MODEL_ID,
+        "messages": messages,
+    }
+    openai_body.update(_finish_common_ollama_fields(body))
+    return openai_body
+
+
+def ollama_generate_to_openai_request(body: dict) -> dict:
+    """Ollama /api/generate body -> OpenAI Chat Completions body.
+
+    generate() has no messages array — just prompt (+ optional system). The
+    pipeline has no notion of raw completion mode, so the prompt rides as a
+    user turn. Tools are accepted because some clients pass them to generate;
+    a tool-call finish then surfaces in the Ollama response text as the
+    serialized call rather than being dropped."""
+    messages = []
+    system = body.get("system")
+    if isinstance(system, str) and system.strip():
+        messages.append({"role": "system", "content": system})
+    prompt = body.get("prompt")
+    messages.append({"role": "user", "content": "" if prompt is None else str(prompt)})
+    openai_body: dict = {
+        "model": body.get("model") or FALLBACK_LOCAL_MODEL_ID,
+        "messages": messages,
+    }
+    openai_body.update(_finish_common_ollama_fields(body))
+    return openai_body
+
+
+def _ollama_done_reason(finish_reason) -> str:
+    return "length" if finish_reason == "length" else "stop"
+
+
+def _ollama_now_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _ollama_usage_lines(usage: dict, duration_ns: int) -> dict:
+    """The trailing count block shared by every Ollama response shape.
+    Real Ollama reports nanosecond durations and token counts; our numbers
+    come from the guarded pipeline's usage accounting."""
+    usage = usage or {}
+    return {
+        "total_duration": duration_ns,
+        "load_duration": 0,
+        "prompt_eval_count": usage.get("prompt_tokens", 0),
+        "prompt_eval_duration": 0,
+        "eval_count": usage.get("completion_tokens", 0),
+        "eval_duration": duration_ns,
+    }
+
+
+def openai_to_ollama_chat_response(
+    openai_resp: dict, requested_model: str, duration_ns: int
+) -> dict:
+    """OpenAI Chat Completions response -> Ollama /api/chat response."""
+    choice = (openai_resp.get("choices") or [{}])[0] or {}
+    message = choice.get("message", {}) or {}
+    ollama_message: dict = {
+        "role": "assistant",
+        "content": message.get("content") or "",
+    }
+    if isinstance(message.get("tool_calls"), list) and message["tool_calls"]:
+        tool_calls = []
+        for tc in message["tool_calls"]:
+            fn = (tc or {}).get("function", {}) or {}
+            args = fn.get("arguments", "")
+            if isinstance(args, str):
+                # Ollama carries arguments as an object; OpenAI as a string.
+                # An unparseable string stays a string — a mangled call beats
+                # a silently dropped one.
+                try:
+                    args = json.loads(args) if args.strip() else {}
+                except (ValueError, TypeError):
+                    pass
+            tool_calls.append(
+                {"function": {"name": fn.get("name", ""), "arguments": args}}
+            )
+        ollama_message["tool_calls"] = tool_calls
+    resp = {
+        "model": requested_model,
+        "created_at": _ollama_now_iso(),
+        "message": ollama_message,
+        "done": True,
+        "done_reason": _ollama_done_reason(choice.get("finish_reason")),
+    }
+    resp.update(_ollama_usage_lines(openai_resp.get("usage"), duration_ns))
+    return resp
+
+
+def openai_to_ollama_generate_response(
+    openai_resp: dict, requested_model: str, duration_ns: int
+) -> dict:
+    """OpenAI Chat Completions response -> Ollama /api/generate response."""
+    choice = (openai_resp.get("choices") or [{}])[0] or {}
+    message = choice.get("message", {}) or {}
+    text = message.get("content") or ""
+    if isinstance(message.get("tool_calls"), list) and message["tool_calls"]:
+        # generate() has no tool contract; surface the call as text rather
+        # than lose it.
+        text += "\n" + json.dumps({"tool_calls": message["tool_calls"]})
+    resp = {
+        "model": requested_model,
+        "created_at": _ollama_now_iso(),
+        "response": text,
+        "done": True,
+        "done_reason": _ollama_done_reason(choice.get("finish_reason")),
+    }
+    resp.update(_ollama_usage_lines(openai_resp.get("usage"), duration_ns))
+    return resp
+
+
+async def _emit_ollama_ndjson(resp: dict, chunk_fields: dict):
+    """Buffered Ollama streaming: one content line, then the final line.
+
+    The pipeline completed before this generator starts, so both lines are
+    emitted back-to-back — a client sees the reply arrive at once. The line
+    split exists so stream-mode clients (which parse NDJSON line-by-line and
+    wait for done:true) terminate correctly.
+
+    chunk_fields names the payload key(s) of this dialect ("message" for
+    /api/chat, "response" for /api/generate). The final line carries the same
+    key EMPTY, exactly like real Ollama — a client concatenating payload
+    fields across lines sees the content exactly once."""
+    chunk = {"model": resp["model"], "created_at": resp["created_at"], "done": False}
+    chunk.update(chunk_fields)
+    yield (json.dumps(chunk) + "\n").encode()
+    final = dict(resp)
+    for k in chunk_fields:
+        if k == "message":
+            final["message"] = {"role": "assistant", "content": ""}
+        else:
+            final[k] = ""
+    final["done"] = True
+    yield (json.dumps(final) + "\n").encode()
+
+
+_OLLAMA_META_CACHE: "OrderedDict[str, tuple[float, dict]]" = OrderedDict()
+_OLLAMA_META_TTL_SECS = 60.0
+
+
+async def _ollama_model_meta(model_id: str) -> dict:
+    """Best-effort card data for /api/tags, /api/show, /api/ps.
+
+    Real Ollama reads these from its blob store. We mirror what the backend
+    actually exposes (llama.cpp /props: model path -> file size + mtime) and
+    leave unknowables as stable placeholders instead of inventing
+    plausible-looking numbers — a fabricated parameter_size would show up in
+    clients' model pickers as fact.
+
+    The result is cached per model id (60s): these are discovery endpoints,
+    some of them unauthenticated, and a 1:1 request -> upstream probe would
+    make them an amplifier against the backend. The upstream-provided path is
+    validated as an existing regular FILE before stat results are reflected
+    to clients — the backend is inside the trust boundary, but an open
+    endpoint should not become a generic filesystem oracle for it."""
+    now = time.monotonic()
+    hit = _OLLAMA_META_CACHE.get(model_id)
+    if hit is not None and now - hit[0] < _OLLAMA_META_TTL_SECS:
+        return hit[1]
+    meta = {"modified_at": _OLLAMA_START_ISO, "size": 0}
+    try:
+        if http_client:
+            r = await http_client.get(
+                LLAMA_CPP_BASE.replace("/v1", "/props"), timeout=5.0
+            )
+            if r.status_code == 200:
+                props = r.json() or {}
+                path = props.get("model_path") or ""
+                if isinstance(path, str) and path:
+                    st = os.stat(path)
+                    if stat.S_ISREG(st.st_mode):
+                        meta["size"] = st.st_size
+                        meta["modified_at"] = time.strftime(
+                            "%Y-%m-%dT%H:%M:%SZ", time.gmtime(st.st_mtime)
+                        )
+    except Exception as exc:
+        # Best-effort by design (the card degrades to placeholders), but a
+        # silently misconfigured upstream is invisible without this line —
+        # e.g. an LLAMA_CPP_BASE without the /v1 suffix breaks the .replace.
+        logger.debug("OLLAMA: /props metadata miss for %s: %s", model_id, exc)
+    _OLLAMA_META_CACHE[model_id] = (now, meta)
+    while len(_OLLAMA_META_CACHE) > 16:
+        _OLLAMA_META_CACHE.popitem(last=False)
+    return meta
+
+
+def _ollama_digest(model_id: str) -> str:
+    """Stable pseudo-digest. Real Ollama's digest addresses a content blob;
+    the equivalent truth here is 'this backend serving this model id'. The
+    sha256: prefix matches real Ollama — some clients parse on the colon."""
+    return "sha256:" + hashlib.sha256(f"uap-strata::{model_id}".encode()).hexdigest()
+
+
+def _ollama_family(model_id: str) -> str:
+    lower = (model_id or "").lower()
+    for fam in (
+        "qwen3",
+        "qwen2",
+        "qwen",
+        "llama3",
+        "llama",
+        "gemma",
+        "mistral",
+        "phi",
+        "deepseek",
+        "codestral",
+    ):
+        if lower.startswith(fam):
+            return fam
+    return "llama"
+
+
+def _ollama_quantization_level(model_id: str) -> str:
+    m = re.search(
+        r"(iq\d+[a-z0-9_]*|q\d+_[a-z0-9]+|f16|bf16|fp16|f32)", model_id or "", re.IGNORECASE
+    )
+    return m.group(1).upper() if m else ""
+
+
+def _ollama_details(model_id: str) -> dict:
+    return {
+        "parent_model": "",
+        "format": "gguf",
+        "family": _ollama_family(model_id),
+        "families": [_ollama_family(model_id)],
+        "parameter_size": "",
+        "quantization_level": _ollama_quantization_level(model_id),
+    }
+
+
+async def _ollama_served_model_ids() -> tuple[str, ...]:
+    """Backend-served ids only. The Claude contract ids that /v1/models
+    advertises for Anthropic-protocol SDK compatibility are protocol fictions
+    — they must not leak into an Ollama client's model picker, where a client
+    would select them and send them to /api/chat as if they were real."""
+    served = await _upstream_model_ids_cached() or ()
+    local = tuple(m for m in served if m not in ADVERTISED_CLAUDE_MODEL_IDS)
+    return local or (FALLBACK_LOCAL_MODEL_ID,)
+
+
+@app.get("/api/version")
+async def ollama_version():
+    return {"version": _OLLAMA_API_VERSION}
+
+
+@app.get("/api/tags")
+async def ollama_tags():
+    """Ollama model discovery. Served ids only — see _ollama_served_model_ids."""
+    # Same rationale as /v1/models: refresh the rail before answering, because
+    # this is the first thing Ollama clients call and they cache the list.
+    await _maybe_recheck_context_window()
+    models_out = []
+    for mid in await _ollama_served_model_ids():
+        meta = await _ollama_model_meta(mid)
+        models_out.append(
+            {
+                "name": mid,
+                "model": mid,
+                "modified_at": meta["modified_at"],
+                "size": meta["size"],
+                "digest": _ollama_digest(mid),
+                "details": _ollama_details(mid),
+            }
+        )
+    return {"models": models_out}
+
+
+@app.post("/api/show")
+async def ollama_show(request: Request):
+    """Ollama model card. An unknown model 404s like real Ollama, because
+    clients use this to validate a model id they remembered."""
+    try:
+        body = json.loads(await request.body() or b"{}")
+    except (ValueError, TypeError):
+        return _ollama_error(400, "invalid JSON body")
+    if not isinstance(body, dict):
+        return _ollama_error(400, "body must be a JSON object")
+    requested = body.get("model") or ""
+    served = await _ollama_served_model_ids()
+    if requested and requested not in served:
+        return _ollama_error(404, f"model '{requested}' not found")
+    model_id = requested or served[0]
+    meta = await _ollama_model_meta(model_id)
+    details = _ollama_details(model_id)
+    parameters: dict = {}
+    window = _effective_context_window() if _context_window_measured else 0
+    if window > 0:
+        # The honest number: the measured rail, not the backend's raw n_ctx.
+        parameters["num_ctx"] = window
+    family = details["family"]
+    return {
+        "modelfile": (
+            "# Modelfile synthesised by the UAP proxy for the live backend.\n"
+            f"FROM {model_id}\n"
+        ),
+        "parameters": parameters,
+        "template": "{{ .System }} {{ .Prompt }}",
+        "details": details,
+        "model_info": {
+            "general.architecture": family,
+            f"{family}.context_length": window or 0,
+            "general.file_size": meta["size"],
+        },
+    }
+
+
+@app.get("/api/ps")
+async def ollama_ps():
+    """Running-model list. The backend stays loaded (capacity policy owns
+    that), so a far-future expiry is the honest answer — models do not
+    unload after Ollama's default keep_alive here."""
+    models_out = []
+    for mid in await _ollama_served_model_ids():
+        meta = await _ollama_model_meta(mid)
+        entry = {
+            "name": mid,
+            "model": mid,
+            "size": meta["size"],
+            "digest": _ollama_digest(mid),
+            "details": _ollama_details(mid),
+            "expires_at": time.strftime(
+                "%Y-%m-%dT%H:%M:%SZ", time.gmtime(time.time() + 86400)
+            ),
+            "size_vram": meta["size"],
+        }
+        models_out.append(entry)
+    return {"models": models_out}
+
+
+@app.post("/api/chat")
+async def ollama_chat(request: Request):
+    """Ollama /api/chat: full guardrail path, Ollama wire shape."""
+    try:
+        body = json.loads(await request.body() or b"{}")
+    except (ValueError, TypeError):
+        return _ollama_error(400, "invalid JSON body")
+    if not isinstance(body, dict):
+        return _ollama_error(400, "body must be a JSON object")
+    # Ollama defaults to streaming.
+    requested_stream = bool(body.get("stream", True))
+    requested_model = body.get("model") or FALLBACK_LOCAL_MODEL_ID
+    client_id = resolve_client_id(request)
+    openai_body = ollama_chat_to_openai_request(body)
+    logger.info(
+        "OLLAMA chat: client=%s model=%s stream=%s msgs=%d tools=%d",
+        client_id,
+        requested_model,
+        requested_stream,
+        len(openai_body.get("messages", [])),
+        len(openai_body.get("tools", []) or []),
+    )
+    t0 = time.monotonic()
+    openai_resp, status, err = await _guarded_openai_completion(request, openai_body)
+    duration_ns = int((time.monotonic() - t0) * 1e9)
+    if openai_resp is None:
+        return _ollama_error(status if status >= 400 else 502, err or "upstream returned no message")
+    resp = openai_to_ollama_chat_response(openai_resp, requested_model, duration_ns)
+    if not requested_stream:
+        return Response(content=json.dumps(resp).encode(), media_type="application/json")
+    return StreamingResponse(
+        _emit_ollama_ndjson(resp, {"message": resp["message"]}),
+        media_type="application/x-ndjson",
+        headers={"Cache-Control": "no-cache"},
+    )
+
+
+@app.post("/api/generate")
+async def ollama_generate(request: Request):
+    """Ollama /api/generate: full guardrail path, Ollama wire shape."""
+    try:
+        body = json.loads(await request.body() or b"{}")
+    except (ValueError, TypeError):
+        return _ollama_error(400, "invalid JSON body")
+    if not isinstance(body, dict):
+        return _ollama_error(400, "body must be a JSON object")
+    requested_stream = bool(body.get("stream", True))
+    requested_model = body.get("model") or FALLBACK_LOCAL_MODEL_ID
+    client_id = resolve_client_id(request)
+    openai_body = ollama_generate_to_openai_request(body)
+    logger.info(
+        "OLLAMA generate: client=%s model=%s stream=%s prompt_len=%d",
+        client_id,
+        requested_model,
+        requested_stream,
+        len(str(body.get("prompt") or "")),
+    )
+    t0 = time.monotonic()
+    openai_resp, status, err = await _guarded_openai_completion(request, openai_body)
+    duration_ns = int((time.monotonic() - t0) * 1e9)
+    if openai_resp is None:
+        return _ollama_error(status if status >= 400 else 502, err or "upstream returned no message")
+    resp = openai_to_ollama_generate_response(openai_resp, requested_model, duration_ns)
+    if not requested_stream:
+        return Response(content=json.dumps(resp).encode(), media_type="application/json")
+    return StreamingResponse(
+        _emit_ollama_ndjson(resp, {"response": resp["response"]}),
+        media_type="application/x-ndjson",
+        headers={"Cache-Control": "no-cache"},
+    )
+
+
 @app.get("/v1/models")
 async def models():
     """Return available model list.
@@ -15812,21 +16861,154 @@ def _assert_bind_is_authenticated(host: str, token: str) -> None:
     )
 
 
+def _ollama_port_bindable(host: str, port: int) -> bool:
+    """True when the Ollama surface can bind its port.
+
+    A real Ollama is the likeliest collision (it owns 11434 by convention),
+    and uvicorn exits the whole process on a bind failure — which must never
+    take the primary Anthropic surface down with it. This check is advisory;
+    the race after it (a port grabbed between this check and the companion's
+    bind) is contained by _serve_companion_guarded below, which turns a
+    companion SystemExit into a log line and keeps the primary serving."""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind((host, port))
+        return True
+    except OSError:
+        return False
+
+
+class _CompanionListener(uvicorn.Server):
+    """The second uvicorn server for the Ollama port.
+
+    uvicorn installs signal handlers per Server.serve() call: two servers would
+    hand SIGTERM to whichever installed last and leave the other listening,
+    hanging systemd stops. The companion installs none and instead mirrors
+    the primary's should_exit, so one SIGTERM stops both ports. lifespan="off"
+    (set by the caller) matters even more — the app's startup handlers own the
+    http client and the session monitors, and a second lifespan would run
+    them twice against shared state."""
+
+    @contextmanager
+    def capture_signals(self):
+        yield
+
+
+async def _run_proxy_servers() -> None:
+    """Serve the app on PROXY_PORT, plus the Ollama surface port when enabled.
+
+    One process, two listeners, one asyncio loop: the Ollama surface shares
+    the app object — and with it the admission table, rail semaphore and every
+    guardrail — with the Anthropic surface."""
+    primary = uvicorn.Server(
+        uvicorn.Config(
+            app, host=PROXY_HOST, port=PROXY_PORT, log_level=PROXY_LOG_LEVEL.lower()
+        )
+    )
+    primary_task = asyncio.ensure_future(primary.serve())
+    tasks: list = [primary_task]
+    ollama_enabled = PROXY_OLLAMA_PORT > 0
+    if ollama_enabled and PROXY_OLLAMA_PORT == PROXY_PORT:
+        # The advisory bind check cannot catch this one: it runs before the
+        # primary has bound, so it would pass for the primary's own port and
+        # the companion would later die on EADDRINUSE.
+        logger.error(
+            "OLLAMA: PROXY_OLLAMA_PORT=%d equals PROXY_PORT — Ollama surface "
+            "disabled. Pick a different port or set 0.",
+            PROXY_OLLAMA_PORT,
+        )
+        ollama_enabled = False
+    if ollama_enabled:
+        if not _ollama_port_bindable(PROXY_HOST, PROXY_OLLAMA_PORT):
+            logger.error(
+                "OLLAMA: port %d is busy (a real Ollama?) — Ollama surface "
+                "disabled, Anthropic/OpenAI surface unaffected. Set "
+                "PROXY_OLLAMA_PORT=0 to silence this.",
+                PROXY_OLLAMA_PORT,
+            )
+        else:
+            companion = _CompanionListener(
+                uvicorn.Config(
+                    app,
+                    host=PROXY_HOST,
+                    port=PROXY_OLLAMA_PORT,
+                    log_level=PROXY_LOG_LEVEL.lower(),
+                    log_config=None,  # the primary already owns logging config
+                    lifespan="off",  # app startup must not run twice
+                )
+            )
+
+            async def _serve_companion_guarded() -> None:
+                # uvicorn handles a bind failure with sys.exit(1) INSIDE
+                # serve(). SystemExit is a BaseException: it is NOT contained
+                # by gather(return_exceptions=True) — it tears the process
+                # down and takes the primary with it. Contain it here so a
+                # companion failure only ever disables the Ollama surface.
+                try:
+                    await companion.serve()
+                except BaseException as exc:  # containment is the point
+                    logger.error(
+                        "OLLAMA: companion listener died (%s: %s) — Ollama "
+                        "surface disabled, Anthropic/OpenAI surface "
+                        "unaffected.",
+                        type(exc).__name__,
+                        exc,
+                    )
+
+            companion_task = asyncio.ensure_future(_serve_companion_guarded())
+
+            async def _tie_companion() -> None:
+                # The companion cannot see signals (it installs no handlers).
+                # Mirror the primary two ways: when SIGTERM sets the primary's
+                # should_exit, and when the primary task ENDS for any other
+                # reason (crash) — one surface must never outlive the other,
+                # or the process would hang half-alive on systemd stops.
+                while not primary_task.done() and not primary.should_exit:
+                    await asyncio.sleep(0.25)
+                companion.should_exit = True
+
+            logger.info(
+                "OLLAMA: serving /api/* on %s:%d (guarded, same process)",
+                PROXY_HOST,
+                PROXY_OLLAMA_PORT,
+            )
+            tasks.append(companion_task)
+            tasks.append(_tie_companion())
+    # return_exceptions: a companion bind failure (the advisory check raced)
+    # must not cancel the primary. A primary failure still exits the process,
+    # because _tie_companion flags the companion and every task then ends —
+    # and the raise below restores the pre-change contract that a dead
+    # primary aborts startup non-zero (Restart=on-failure reads that).
+    await asyncio.gather(*tasks, return_exceptions=True)
+    if not primary_task.cancelled() and primary_task.exception() is not None:
+        raise primary_task.exception()
+
+
 if __name__ == "__main__":
     # Config discovery is silent by design (it fails open so a missing file can
     # never stop the proxy). Say what it found, so a miss is visible in the
     # journal instead of showing up later as unexplained default behaviour.
     logger.info(
-        "proxy env: %s | auth=%s | bind=%s:%d",
+        "proxy env: %s | auth=%s | bind=%s:%d | ollama=%s",
         f"loaded {_PROXY_ENV_FILE_LOADED}" if _PROXY_ENV_FILE_LOADED else "no proxy.env found",
         "enabled" if PROXY_AUTH_TOKEN else "DISABLED",
         PROXY_HOST,
         PROXY_PORT,
+        f"port {PROXY_OLLAMA_PORT}" if PROXY_OLLAMA_PORT > 0 else "off",
     )
     _assert_bind_is_authenticated(PROXY_HOST, PROXY_AUTH_TOKEN)
-    uvicorn.run(
-        app,
-        host=PROXY_HOST,
-        port=PROXY_PORT,
-        log_level=PROXY_LOG_LEVEL.lower(),
-    )
+    if PROXY_OLLAMA_PORT > 0:
+        asyncio.run(_run_proxy_servers())
+    else:
+        # Legacy single-port path kept byte-identical to the pre-Ollama
+        # launcher ON PURPOSE: PROXY_OLLAMA_PORT=0 deployments must not
+        # start exercising the gather/tie machinery just because it exists
+        # (blast-radius minimization; a lifecycle regression in the dual path
+        # must not reproduce in single-port setups).
+        uvicorn.run(
+            app,
+            host=PROXY_HOST,
+            port=PROXY_PORT,
+            log_level=PROXY_LOG_LEVEL.lower(),
+        )