lynkr 9.13.0 → 9.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkr",
-  "version": "9.13.0",
+  "version": "9.14.0",
   "files": [
     "index.js",
     "install.sh",
@@ -35,6 +35,7 @@
     "start": "node index.js 2>&1 | npx pino-pretty --sync",
     "stop": "node -e \"if(process.env.HEADROOM_ENABLED==='true'&&process.env.HEADROOM_DOCKER_ENABLED!=='false'){process.exit(0)}else{process.exit(1)}\" && docker compose --profile headroom down || echo 'Headroom skipped (disabled or Docker not running)'",
     "dev": "nodemon index.js",
+    "start:supervised": "while true; do node index.js 2>&1 | npx pino-pretty --sync; code=$?; echo \"[supervisor] lynkr exited ($code) — restarting in 3s\"; sleep 3; done",
     "lint": "eslint src index.js",
     "test": "npm run test:unit && npm run test:performance",
     "test:unit": "DATABRICKS_API_KEY=test-key DATABRICKS_API_BASE=http://test.com LOG_FILE_ENABLED=false node --test test/routing.test.js test/hybrid-routing-integration.test.js test/retry-logic.test.js test/sse-transformer.test.js test/passthrough-stream.test.js test/passthrough-mode.test.js test/openrouter-error-resilience.test.js test/format-conversion.test.js test/azure-openai-config.test.js test/azure-openai-format-conversion.test.js test/azure-openai-routing.test.js test/azure-openai-streaming.test.js test/azure-openai-error-resilience.test.js test/azure-openai-integration.test.js test/openai-integration.test.js test/atlas-integration.test.js test/toon-compression.test.js test/gcf-compression.test.js test/llamacpp-integration.test.js test/resilience.test.js test/telemetry-routing.test.js test/memory/store.test.js test/memory/surprise.test.js test/memory/extractor.test.js test/memory/search.test.js test/memory/retriever.test.js test/memory/distiller.test.js test/memory/distiller-freeze.test.js test/memory/wiki.test.js test/memory/skills-cache.test.js test/memory/tencentdb-launcher.test.js test/distill.test.js test/large-payload.test.js test/prompt-cache-injection.test.js test/risk-analyzer.test.js test/interaction-block.test.js test/preflight.test.js test/token-reduction.test.js test/session-affinity.test.js test/cache-state.test.js test/cache-switch-cost.test.js test/lens-recommendations.test.js test/model-registry-cost.test.js test/output-format-guard.test.js test/tier-fallback.test.js test/wrap.test.js test/init.test.js test/tool-call-response-metadata.test.js test/degradation.test.js test/routing-telemetry-columns.test.js test/sticky-routing.test.js test/knn-ambiguous-escalate.test.js test/deescalator.test.js test/client-profiles.test.js test/strip-internal-fields.test.js test/complexity-tool-subtraction.test.js test/bandit.test.js test/routing-propensity.test.js test/reward-pipeline.test.js test/knn-cold-start.test.js test/calibration.test.js test/feedback-loop.test.js test/session-fingerprint.test.js test/side-request-guards.test.js test/verifier.test.js test/intent-score.test.js test/difficulty-classifier.test.js test/classifier-setup.test.js test/usage-stats.test.js test/loop-guard.test.js test/moonshot-model-mapping.test.js test/baidu-model-mapping.test.js",

package/scripts/convert-routellm.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+Convert routellm/gpt4_dataset (train.jsonl) → Lynkr kNN bootstrap JSONL.
+
+Stream-downloads from HuggingFace and maps mixtral_score (1-5) to your
+TIER_* model config so the kNN index learns to recommend YOUR real models,
+not RouteLLM's pool (mixtral / gpt-4).
+
+Output format matches scripts/build-knn-index.js bootstrap input:
+    {"query": "...", "provider": "ollama", "model": "minimax-m2.5:cloud",
+     "quality": 95, "cost": 0.001, "latency": 200, "tier": "SIMPLE"}
+
+Usage:
+    .venv/bin/python scripts/convert-routellm.py [--limit 30000] -o routellm.jsonl
+"""
+import argparse
+import json
+import sys
+import urllib.request
+import ssl
+
+# Map mixtral_score → user's tier config.
+# Spread is intentionally aggressive: only score=5 (Mixtral truly nailed it)
+# stays SIMPLE; score=4 escalates to MEDIUM so the kNN index has enough MEDIUM
+# examples to actually recommend non-SIMPLE tiers (vs the previous mapping
+# where 86% of records were SIMPLE and kNN never disagreed with the heuristic).
+SCORE_TO_ROUTE = {
+    5: {"tier": "SIMPLE",    "provider": "ollama",          "model": "minimax-m2.5:cloud", "quality": 95, "cost": 0.001, "latency": 200},
+    4: {"tier": "MEDIUM",    "provider": "azure-anthropic", "model": "claude-sonnet-4-6",  "quality": 80, "cost": 0.003, "latency": 1500},
+    3: {"tier": "MEDIUM",    "provider": "azure-anthropic", "model": "claude-sonnet-4-6",  "quality": 70, "cost": 0.003, "latency": 1500},
+    2: {"tier": "COMPLEX",   "provider": "azure-anthropic", "model": "claude-sonnet-4-6",  "quality": 55, "cost": 0.003, "latency": 1500},
+    1: {"tier": "REASONING", "provider": "azure-anthropic", "model": "claude-opus-4-8",    "quality": 40, "cost": 0.015, "latency": 3500},
+}
+
+URL = "https://huggingface.co/datasets/routellm/gpt4_dataset/resolve/main/train.jsonl"
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--output", "-o", default="data/routellm-bootstrap.jsonl")
+    p.add_argument("--limit", type=int, default=None,
+                   help="Only convert first N rows")
+    args = p.parse_args()
+
+    print(f"Streaming {URL} …", file=sys.stderr)
+    # Some macOS Python builds have SSL issues with huggingface.co — fall back
+    # to unverified context if needed. The data is public, no auth.
+    ctx = ssl.create_default_context()
+    try:
+        with urllib.request.urlopen(URL, context=ctx, timeout=60) as resp:
+            _stream(resp, args.output, args.limit)
+    except (ssl.SSLError, OSError) as e:
+        print(f"SSL strict failed ({e}); retrying with unverified context", file=sys.stderr)
+        ctx = ssl._create_unverified_context()
+        with urllib.request.urlopen(URL, context=ctx, timeout=60) as resp:
+            _stream(resp, args.output, args.limit)
+
+
+def _stream(resp, out_path, limit):
+    written = 0
+    by_score = {s: 0 for s in SCORE_TO_ROUTE}
+    skipped = 0
+    with open(out_path, "w") as out:
+        for line in resp:
+            if limit and written >= limit:
+                break
+            try:
+                row = json.loads(line)
+            except Exception:
+                skipped += 1
+                continue
+            score = row.get("mixtral_score")
+            if score not in SCORE_TO_ROUTE:
+                skipped += 1
+                continue
+            route = SCORE_TO_ROUTE[score]
+            rec = {
+                "query": row.get("prompt", ""),
+                "provider": route["provider"],
+                "model": route["model"],
+                "quality": route["quality"],
+                "cost": route["cost"],
+                "latency": route["latency"],
+                "tier": route["tier"],
+            }
+            if not rec["query"]:
+                skipped += 1
+                continue
+            out.write(json.dumps(rec) + "\n")
+            written += 1
+            by_score[score] += 1
+            if written % 5000 == 0:
+                print(f"  {written} written…", file=sys.stderr)
+
+    print(f"\nWrote {written} records to {out_path} ({skipped} skipped)", file=sys.stderr)
+    print(f"By mixtral_score: {by_score}", file=sys.stderr)
+    print(f"\nTier distribution:", file=sys.stderr)
+    for score, route in SCORE_TO_ROUTE.items():
+        n = by_score[score]
+        if n:
+            print(f"  {route['tier']:>10}  {route['provider']}:{route['model']:30s}  n={n}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/src/api/middleware/load-shedding.js

@@ -1,4 +1,5 @@
 const os = require("os");
+const v8 = require("v8");
 const logger = require("../../logger");
 const { ServiceUnavailableError } = require("./error-handling");
 
@@ -18,11 +19,31 @@ class LoadShedder {
     this.memoryThreshold = options.memoryThreshold || 0.85; // 85%
     this.heapThreshold = options.heapThreshold || 0.95; // 95% (increased from 90% to prevent false positives from temporary allocation spikes)
     this.activeRequestsThreshold = options.activeRequestsThreshold || 1000;
+    // Absolute free-heap floor. Percent-of-heapTotal is unreliable in both
+    // directions: heapTotal is V8's CURRENTLY allocated heap (grows on
+    // demand toward the real limit), and at the limit "99%" leaves ~40MB on
+    // a 4GB heap — nowhere near enough to parse one multi-MB request body.
+    // 2026-08-19 OOM: a 5MB compact request passed the percent check and
+    // died allocating during JSON.parse. Shed while there is still room to
+    // finish in-flight work.
+    this.headroomMB = options.headroomMB || 512;
+    this.heapLimitMB = v8.getHeapStatistics().heap_size_limit / (1024 * 1024);
+
+    // Watchdog: how long the heap may stay below the headroom floor with
+    // zero active requests before the process self-restarts. Retained
+    // memory GC can't reclaim never recovers on its own — without this the
+    // server sheds 100% of traffic until someone restarts it by hand.
+    this.wedgedRestartMs = options.wedgedRestartMs || 60000;
+    this.selfRestart = options.selfRestart !== false;
+    this.wedgedSince = null;
 
     // State
     this.activeRequests = 0;
     this.totalShed = 0;
-    this.lastCheck = Date.now();
+    // 0, not Date.now(): the first isOverloaded() call must actually
+    // evaluate instead of returning the constructor's cached "false"
+    // for the first checkInterval window.
+    this.lastCheck = 0;
     this.checkInterval = options.checkInterval || 1000; // Check every second
     this.cachedOverloadState = false;
   }
@@ -42,26 +63,32 @@ class LoadShedder {
 
     // Check memory usage
     const memUsage = process.memoryUsage();
-    const heapUsedPercent = memUsage.heapUsed / memUsage.heapTotal;
-
-    // FIX: Only trigger if BOTH percentage is high AND actual usage is significant
-    // This prevents false positives on startup when heapTotal is small but will grow
-    const heapUsedMB = memUsage.heapUsed / (1024 * 1024);
-    const minHeapThresholdMB = 500; // Only shed load if using more than 500MB
 
-    if (heapUsedPercent > this.heapThreshold && heapUsedMB > minHeapThresholdMB) {
+    // Absolute headroom against the true V8 limit — the primary guard.
+    const heapStats = v8.getHeapStatistics();
+    const freeMB = (heapStats.heap_size_limit - heapStats.used_heap_size) / (1024 * 1024);
+    if (freeMB < this.headroomMB) {
       logger.warn(
         {
-          heapUsedPercent: (heapUsedPercent * 100).toFixed(2),
-          heapUsedMB: heapUsedMB.toFixed(2),
-          threshold: (this.heapThreshold * 100).toFixed(2),
-          minThresholdMB: minHeapThresholdMB,
+          freeMB: freeMB.toFixed(0),
+          headroomMB: this.headroomMB,
+          heapLimitMB: this.heapLimitMB.toFixed(0),
+          usedMB: (heapStats.used_heap_size / (1024 * 1024)).toFixed(0),
         },
-        "Load shedding: Heap usage exceeded threshold"
+        "Load shedding: heap headroom below floor"
       );
+      this._trackWedged(now);
       this.cachedOverloadState = true;
       return true;
     }
+    this.wedgedSince = null;
+
+    // NOTE: the old heapUsed/heapTotal percent check is gone. heapTotal is
+    // V8's *currently allocated* heap, which it keeps close to usage, so the
+    // ratio reads ~99% during perfectly normal operation — it shed all
+    // traffic at 755MB used with gigabytes of real headroom remaining
+    // (2026-08-20 false-positive incident). The absolute-headroom check
+    // against heap_size_limit above is the correct form of this guard.
 
     // Check RSS / system memory
     const rssPercent = memUsage.rss / os.totalmem();
@@ -94,6 +121,32 @@ class LoadShedder {
     return false;
   }
 
+  /**
+   * Track how long the heap has been wedged below the headroom floor.
+   * If it persists past wedgedRestartMs with no in-flight requests, the
+   * memory is retained (not transient) and GC cannot recover it — exit so
+   * the supervisor restarts a clean process instead of shedding forever.
+   */
+  _trackWedged(now) {
+    if (!this.selfRestart) return;
+    if (this.wedgedSince === null) {
+      this.wedgedSince = now;
+      return;
+    }
+    if (now - this.wedgedSince >= this.wedgedRestartMs && this.activeRequests === 0) {
+      logger.fatal(
+        {
+          wedgedForMs: now - this.wedgedSince,
+          totalShed: this.totalShed,
+          heapLimitMB: this.heapLimitMB.toFixed(0),
+        },
+        "Load shedding: heap wedged below headroom floor with no active requests — exiting for supervisor restart"
+      );
+      // Give the fatal log a moment to flush, then exit non-zero.
+      setTimeout(() => process.exit(1), 250).unref();
+    }
+  }
+
   /**
    * Get current metrics
    */
@@ -107,10 +160,15 @@ class LoadShedder {
       heapTotalMB: (memUsage.heapTotal / (1024 * 1024)).toFixed(2),
       rssMB: (memUsage.rss / (1024 * 1024)).toFixed(2),
       rssPercent: ((memUsage.rss / os.totalmem()) * 100).toFixed(2),
+      heapLimitMB: this.heapLimitMB.toFixed(2),
+      freeHeadroomMB: ((v8.getHeapStatistics().heap_size_limit - v8.getHeapStatistics().used_heap_size) / (1024 * 1024)).toFixed(2),
       thresholds: {
         heapThreshold: (this.heapThreshold * 100).toFixed(2),
         memoryThreshold: (this.memoryThreshold * 100).toFixed(2),
         activeRequestsThreshold: this.activeRequestsThreshold,
+        headroomMB: this.headroomMB,
+        wedgedRestartMs: this.wedgedRestartMs,
+        selfRestart: this.selfRestart,
       },
     };
   }
@@ -129,6 +187,11 @@ function getLoadShedder(options) {
         process.env.LOAD_SHEDDING_ACTIVE_REQUESTS_THRESHOLD || "1000",
         10
       ),
+      // Not env-configurable by design: these are crash-prevention floors,
+      // and there is no deployment where turning them off is correct.
+      headroomMB: 512,
+      wedgedRestartMs: 60000,
+      selfRestart: true,
     };
     instance = new LoadShedder({ ...defaultOptions, ...options });
   }

package/src/api/openai-router.js

@@ -426,22 +426,42 @@ async function forwardAnthropicStreamAsOpenAIChunks(res, stream, requestedModel)
             res.write("data: [DONE]\n\n");
             res.end();
             return;
+          case "error":
+            // Forward upstream stream errors in OpenAI wire shape
+            // (data: {"error": ...}) and terminate WITHOUT finish_reason or
+            // [DONE]. Writing "stop" here told agent clients the model chose
+            // to end its turn — they stopped mid-task instead of retrying
+            // (2026-08-19 incident: opencode stalled between tool calls).
+            logger.warn({ error: ev.error?.message }, "Forwarding upstream stream error to OpenAI-surface client");
+            res.write(`data: ${JSON.stringify({ error: { message: ev.error?.message || "upstream stream error", type: ev.error?.type || "server_error", code: null } })}\n\n`);
+            res.end();
+            return;
           default:
             break; // ping, thinking deltas, unknown events — skip
         }
         if (res.writableEnded || res.destroyed) return;
       }
     }
-    // Upstream closed without message_stop — still terminate the client stream cleanly.
+    // Upstream closed without message_stop. If a stop_reason already arrived
+    // the turn is materially complete — finish normally. Otherwise this is a
+    // truncated stream: send an error chunk, never a fabricated "stop".
     if (!res.writableEnded) {
-      res.write(chunk({}, finishReason || "stop"));
-      res.write("data: [DONE]\n\n");
+      if (finishReason) {
+        res.write(chunk({}, finishReason));
+        res.write("data: [DONE]\n\n");
+      } else {
+        logger.warn("Upstream stream ended without message_stop — sending error chunk to OpenAI-surface client");
+        res.write(`data: ${JSON.stringify({ error: { message: "Lynkr: upstream stream truncated — retry", type: "server_error", code: null } })}\n\n`);
+      }
       res.end();
     }
   } catch (err) {
     logger.warn({ err: err.message }, "OpenAI-surface stream forward failed mid-flight");
     if (!res.writableEnded) {
-      try { res.write(chunk({}, "stop")); res.write("data: [DONE]\n\n"); res.end(); } catch { /* client gone */ }
+      try {
+        res.write(`data: ${JSON.stringify({ error: { message: `Lynkr: stream forward failed — retry (${err.message})`, type: "server_error", code: null } })}\n\n`);
+        res.end();
+      } catch { /* client gone */ }
     }
   }
 }
@@ -594,13 +614,25 @@ router.post("/chat/completions", async (req, res) => {
         // "task complete" and terminate mid-task. Killing the stream without
         // a finish chunk makes the client retry instead.
         if (!content && (!toolCalls || toolCalls.length === 0)) {
+          const upstreamErr = result.body?.error || {};
           logger.error({
             finishReason: openaiResponse.choices[0]?.finish_reason,
             terminationReason: result?.terminationReason,
             status: result?.status,
-          }, "Empty completion reached serving path — aborting stream to force client retry");
-          res.write(`data: ${JSON.stringify({ error: { message: "Upstream returned an empty completion; retry.", type: "server_error", code: "empty_completion" } })}\n\n`);
-          res.destroy();
+            upstreamError: upstreamErr.message || null,
+          }, "Empty completion reached serving path — sending error chunk to client");
+          // res.destroy() here surfaced as ECONNRESET ("connection reset by
+          // server") in clients, and the error chunk raced the teardown so
+          // it often never arrived. A cleanly-ended SSE error chunk (no
+          // finish chunk, no [DONE]) delivers the real upstream error and
+          // still reads as a failed request that agent clients retry.
+          res.write(`data: ${JSON.stringify({ error: {
+            message: upstreamErr.message || "Upstream returned an empty completion; retry.",
+            type: upstreamErr.type || "server_error",
+            code: upstreamErr.code || "empty_completion",
+            ...(result?.status ? { status: result.status } : {}),
+          } })}\n\n`);
+          res.end();
           return;
         }
 

package/src/clients/databricks.js

@@ -3541,12 +3541,101 @@ async function invokeModel(body, options = {}) {
 
       const fallbackStart = Date.now();
 
+      // Strip the failed primary's routing stamps before re-dispatch: every
+      // provider client prefers body._tierModel over its own configured
+      // model, so leaving the failed tier's model on the body makes the
+      // fallback provider serve a model it doesn't have — azure-openai
+      // treats it as the deployment id and 404s with DeploymentNotFound
+      // (live incident 2026-08-19). The fallback provider must fall through
+      // to its own configured model.
+      const fallbackBody = { ...body };
+      delete fallbackBody._tierModel;
+      delete fallbackBody._suggestionModeModel;
+
       const fallbackResult = await fallbackBreaker.execute(async () => {
-        return await invokeProvider(fallbackProvider, body, incomingHeaders);
+        return await invokeProvider(fallbackProvider, fallbackBody, incomingHeaders);
       });
 
       const fallbackLatency = Date.now() - fallbackStart;
 
+      // Provider clients return {ok:false} on 4xx/5xx instead of throwing,
+      // so a fallback rung that answered with an error body used to sail
+      // through the success path below — logging "Fallback to cloud
+      // provider succeeded" and recording status_code:200 telemetry for
+      // what was actually a double failure. Treat it as one.
+      if (fallbackResult?.ok === false) {
+        const fbErrMessage = fallbackResult.json?.error?.message || String(fallbackResult.text || "").slice(0, 120) || "error response";
+
+        metricsCollector.recordFallbackFailure();
+        metricsCollector.recordDatabricksRequest(false, retries);
+        healthTracker.recordFailure(fallbackProvider, new Error(fbErrMessage), fallbackResult.status);
+
+        logger.warn({
+          originalProvider: initialProvider,
+          fallbackProvider,
+          status: fallbackResult.status,
+          error: fbErrMessage,
+        }, "Fallback provider answered with an error response");
+
+        // Thread the whole trail into the error payload so the client sees
+        // every failure, not just this one (e.g. "moonshot: quota" matters
+        // more than "azure: 404").
+        failureTrail.push(`${fallbackProvider}: HTTP ${fallbackResult.status} — ${fbErrMessage}`);
+        if (fallbackResult.json && typeof fallbackResult.json === "object") {
+          fallbackResult.json._lynkr_failure_trail = failureTrail;
+        }
+
+        const fbFailLatency = Date.now() - startTime;
+        telemetry.record({
+          request_id: crypto.randomUUID(),
+          session_id: body._sessionId || null,
+          timestamp: Date.now(),
+          complexity_score: routingResult.score ?? null,
+          tier: routingDecision.tier,
+          provider: fallbackProvider,
+          model: routingDecision.model ?? body._tierModel ?? null,
+          routing_method: "fallback",
+          was_fallback: true,
+          latency_ms: fbFailLatency,
+          status_code: fallbackResult.status || null,
+          error_type: "fallback_error_response",
+          quality_score: 0,
+          base_tier: routingResult.base_tier ?? null,
+          escalation_source: routingResult.escalation_source ?? null,
+          propensity: routingResult.propensity ?? null,
+          candidates: routingResult.candidates ?? null,
+          pinned: routingResult.pinned ? 1 : 0,
+          switch_reason: routingResult.switch_reason ?? null,
+          cache_decision: routingResult._cacheDecision ?? null,
+        });
+
+        // WS5.4 — feedback loop (fallback answered with an error). Same
+        // hard-negative signal as a double failure.
+        recordFeedbackOutcome({
+          routingResult,
+          body,
+          outcome: {
+            qualityScore: 0,
+            costUsd: null,
+            latencyMs: fbFailLatency,
+            statusCode: fallbackResult.status || null,
+            errorType: "fallback_error_response",
+            wasFallback: true,
+          },
+        });
+
+        return {
+          ...fallbackResult,
+          actualProvider: fallbackProvider,
+          routingDecision: {
+            ...routingDecision,
+            provider: fallbackProvider,
+            method: 'fallback',
+            fallbackReason: reason,
+          },
+        };
+      }
+
       metricsCollector.recordFallbackSuccess(fallbackLatency);
       metricsCollector.recordDatabricksRequest(true, retries);
       healthTracker.recordSuccess(fallbackProvider, fallbackLatency);
@@ -3635,16 +3724,6 @@ async function invokeModel(body, options = {}) {
         },
       });
 
-      // The last rung also answered with an error — thread the whole trail
-      // into the error payload so the client sees every failure, not just
-      // this one (e.g. "moonshot: quota" matters more than "azure: 404").
-      if (fallbackResult?.ok === false) {
-        failureTrail.push(`${fallbackProvider}: HTTP ${fallbackResult.status} — ${fallbackResult.json?.error?.message || String(fallbackResult.text || "").slice(0, 120) || "error response"}`);
-        if (fallbackResult.json && typeof fallbackResult.json === "object") {
-          fallbackResult.json._lynkr_failure_trail = failureTrail;
-        }
-      }
-
       return {
         ...fallbackResult,
         actualProvider: fallbackProvider,

package/src/clients/resilience.js

@@ -381,6 +381,15 @@ async function withCockatielRetry(fn, options = {}) {
               const retryAfterDate = new Date(retryAfter);
               delay = retryAfterDate.getTime() - Date.now();
             }
+            // Retry-After is a floor, not the full answer: Azure sends
+            // "Retry-After: 1" on token-window 429s that need far longer to
+            // drain, so honoring it literally re-hammers the window every
+            // second and it never recovers (2026-08-19 incident). Back off
+            // exponentially on top of the header, with jitter.
+            const floorMs = Math.max(0, delay || 0);
+            const backoffMs = 2000 * Math.pow(config.backoffMultiplier, attempt);
+            const cappedMs = Math.min(Math.max(floorMs, backoffMs), 60000);
+            delay = cappedMs + cappedMs * config.jitterFactor * Math.random();
           } else {
             // Exponential backoff with longer delays for rate limiting
             const baseDelay = 2000 * Math.pow(config.backoffMultiplier, attempt);

package/src/orchestrator/index.js

@@ -1356,6 +1356,18 @@ function buildNonJsonResponse(databricksResponse) {
   };
 }
 
+/**
+ * Visible routing badge for live-streamed responses, built from the actual
+ * post-routing decision (tier fallbacks included). Matches the format of
+ * openai-router's lynkrBadge and the Anthropic router's intent badge so
+ * LYNKR_BADGE_PREFIX_RE strips all three identically from replayed history.
+ */
+function buildRoutingBadge(rd) {
+  if (!rd || !rd.tier) return null;
+  const score = typeof rd.score === "number" ? ` · score ${rd.score}` : "";
+  return `*[Lynkr] ${rd.tier} → ${rd.model || "—"} (${rd.provider || "—"})${score}*\n\n`;
+}
+
 function buildStreamingResponse(databricksResponse) {
   return {
     status: databricksResponse.status,
@@ -1755,7 +1767,24 @@ IMPORTANT TOOL USAGE RULES:
   };
   const headroomProvider = process.env.HEADROOM_PROVIDER || 'anthropic';
   const headroomSafeProviders = headroomProviderMap[headroomProvider] || new Set();
-  const headroomCompatible = headroomSafeProviders.has(providerType);
+  // Under tier routing the static providerType is just the MODEL_PROVIDER
+  // default (usually "databricks") — the real provider is chosen per-request
+  // later in invokeModel, AFTER this compression point, so gating on it
+  // silently disabled Headroom for every tier-routed setup. Gate on the
+  // configured tier fleet instead: compress only when every routable tier
+  // provider is format-safe, since any request may land on any tier.
+  let headroomCompatible = headroomSafeProviders.has(providerType);
+  if (!headroomCompatible) {
+    try {
+      const { getModelTierSelector } = require('../routing/model-tiers');
+      const sel = getModelTierSelector();
+      const tierProviders = ['SIMPLE', 'MEDIUM', 'COMPLEX', 'REASONING']
+        .map((t) => { try { return sel.selectModel(t)?.provider; } catch { return null; } })
+        .filter(Boolean)
+        .map((p) => (p === 'z-ai' ? 'zai' : p));
+      headroomCompatible = tierProviders.length > 0 && tierProviders.every((p) => headroomSafeProviders.has(p));
+    } catch { /* tier routing not configured — keep the static gate result */ }
+  }
 
   if (isHeadroomEnabled() && headroomCompatible && cleanPayload.messages && cleanPayload.messages.length > 0) {
     try {
@@ -2053,7 +2082,16 @@ IMPORTANT TOOL USAGE RULES:
         const routingDecision = databricksResponse.routingDecision || {};
         const transformed = sseTransform.openaiToAnthropicSSE(databricksResponse.stream, {
           model: requestedModel,
-          badgeText: config.routing?.visibleInteraction ? options?.streamBadgeText || null : null,
+          // Badge precedence: an explicit streamBadgeText (Anthropic router's
+          // pre-computed intent badge) wins; otherwise build one from the
+          // ACTUAL post-routing decision so OpenAI-surface live streams
+          // (opencode et al.) show which model served the response —
+          // previously this path silently dropped the badge entirely.
+          // History pollution is covered: stripLynkrBadges in invokeModel
+          // removes resubmitted badges before anything reaches a provider.
+          badgeText: config.routing?.visibleInteraction
+            ? (options?.streamBadgeText || buildRoutingBadge(routingDecision))
+            : null,
           onClose: (stats) => {
             try {
               const telemetry = require("../routing/telemetry");
@@ -2080,6 +2118,7 @@ IMPORTANT TOOL USAGE RULES:
               logger.info({
                 provider: routingDecision.provider || _streamProvider,
                 stopReason: stats.stopReason,
+                finishReason: stats.finishReason ?? null,
                 toolCalls: stats.toolCalls.map((t) => t.name),
                 outputTokens: stats.usage.output_tokens,
               }, "[SSETransform] Stream closed");
@@ -3191,4 +3230,6 @@ module.exports = {
   toAnthropicResponse,
   // Exported for unit testing of loop trimming (task-preservation contract).
   trimLoopMessages,
+  // Exported for unit testing of the live-stream routing badge.
+  buildRoutingBadge,
 };

package/src/orchestrator/sse-transformer.js

@@ -256,6 +256,7 @@ async function* _openaiToAnthropicEvents(upstream, opts = {}) {
       error: { type: "overloaded_error", message: `Lynkr: upstream stream failed — retry (${err.message})` },
     });
     stats.stopReason = "stream_error";
+    stats.finishReason = finishReason ?? null;
     if (opts.onClose) { try { opts.onClose(stats); } catch { /* non-fatal */ } }
     return;
   }
@@ -263,10 +264,36 @@ async function* _openaiToAnthropicEvents(upstream, opts = {}) {
   // Normal end of stream ([DONE] or upstream EOF).
   yield* startMessage();
   yield* closeTextBlock();
+
+  // An EOF with no finish_reason is a dropped upstream, not a completed
+  // turn. Mapping it to end_turn hands the client a success-shaped stop —
+  // agent loops halt mid-task believing the model chose to stop (live
+  // incident 2026-08-19: opencode stalled between tool calls; the stream
+  // closed as end_turn with null output tokens). Spec-compliant upstreams
+  // always send finish_reason on the last choice chunk, so signal an error
+  // and let the client retry, mirroring the mid-flight failure path above.
+  // Accumulated tool fragments are NOT flushed: without finish_reason their
+  // argument JSON may be truncated mid-string.
+  if (!finishReason) {
+    logger.warn(
+      { droppedToolFragments: toolAcc.size, outputTokens: stats.usage.output_tokens },
+      "[SSETransform] Upstream ended without finish_reason — signaling stream error"
+    );
+    yield _sse("error", {
+      type: "error",
+      error: { type: "overloaded_error", message: "Lynkr: upstream ended without finish_reason — retry" },
+    });
+    stats.stopReason = "stream_error";
+    stats.finishReason = null;
+    if (opts.onClose) { try { opts.onClose(stats); } catch { /* non-fatal */ } }
+    return;
+  }
+
   yield* flushToolBlocks();
 
   const stopReason = _mapFinishReason(finishReason);
   stats.stopReason = stopReason;
+  stats.finishReason = finishReason;
   yield _sse("message_delta", {
     type: "message_delta",
     delta: { stop_reason: stopReason, stop_sequence: null },