@alexeiled/claude-router 0.2.2 → 0.4.0

package/lib/gateway.mjs

@@ -1,69 +1,119 @@
 // Local Anthropic Messages gateway: byte-for-byte passthrough, except a routed request gets its
 // model, effort and thinking rewritten. Never re-serializes responses; reads usage on a tee.
+// Upstream errors (429, 529, 5xx) pass through unchanged: Claude Code owns retries and backoff.
 import { createServer, request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
+import { pipeline } from 'node:stream';
+import { IdleTracker } from './idle.mjs';
 import { UsageReader } from './sse.mjs';
 import { ROUTER_DISPLAY_NAME, STATUS_PATH, statusSnapshot } from './status.mjs';
 
 const HOP_BY_HOP = new Set(['host', 'connection', 'content-length', 'accept-encoding', 'transfer-encoding']);
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]']);
+const MESSAGES_PATH = '/v1/messages';
 
-export function createGateway({ router, upstream = 'https://api.anthropic.com', onError = () => {} }) {
+export function createGateway({
+  router,
+  upstream = 'https://api.anthropic.com',
+  onError = () => {},
+  activity = new IdleTracker(),
+}) {
   const target = new URL(upstream);
   const send = target.protocol === 'https:' ? httpsRequest : httpRequest;
 
   return createServer((req, res) => {
+    activity.requestStarted();
+    res.once('close', () => activity.requestEnded());
+    if (!isLocalClient(req))
+      return reply(res, 403, errorBody('permission_error', 'router: the gateway serves local clients only'));
     if (req.method === 'GET' && req.url.startsWith('/v1/models')) return discovery(router, res);
     if (req.method === 'GET' && req.url.startsWith(STATUS_PATH)) return status(router, req, res);
+    let up = null;
+    let closedEarly = false;
+    // The client left before its response was complete (Esc in Claude Code, a client timeout). Before the upstream
+    // answers, abort the upstream request here; after, pipeline() below does it. Either way the model stops generating.
+    res.on('close', () => {
+      if (res.writableFinished) return;
+      closedEarly = true;
+      if (!res.headersSent) up?.destroy();
+    });
     const chunks = [];
     req.on('data', (c) => chunks.push(c));
     req.on('end', async () => {
-      let body = Buffer.concat(chunks);
-      let parsed = null;
       try {
-        parsed = body.length ? JSON.parse(body.toString('utf8')) : null;
-      } catch {
-        parsed = null;
-      }
-      const session = sessionKey(req, parsed);
-      let routed = null;
-      if (parsed && router.isRouted(parsed)) {
-        try {
-          routed = await router.route(parsed, {
-            sessionId: session,
-            requestClass: req.headers['x-claude-code-request-class'] ?? null,
-          });
-        } catch (error) {
-          onError(error);
-          routed = router.fallback(parsed); // never forward the alias upstream
+        let body = Buffer.concat(chunks);
+        const parsed = parseJson(body);
+        const session = sessionKey(req, parsed);
+        const turn = isMessagesCall(req);
+        if (turn) activity.turnResumed(session);
+        let routed = null;
+        if (parsed && router.isRouted(parsed)) {
+          if (turn) {
+            try {
+              routed = await router.route(parsed, {
+                sessionId: session,
+                requestClass: req.headers['x-claude-code-request-class'] ?? null,
+              });
+            } catch (error) {
+              onError(error);
+              routed = router.fallback(parsed); // never forward the alias upstream
+            }
+          } else routed = router.resolveModel(parsed, session);
+          body = Buffer.from(JSON.stringify(routed.body));
         }
-        body = Buffer.from(JSON.stringify(routed.body));
+        if (closedEarly) return; // the client left while the route was decided
+        const headers = {};
+        for (const [name, value] of Object.entries(req.headers)) if (!HOP_BY_HOP.has(name)) headers[name] = value;
+        headers.host = target.host;
+        headers['content-length'] = String(body.length);
+        up = send(
+          { host: target.hostname, port: target.port || undefined, path: req.url, method: req.method, headers },
+          (upRes) => relay(upRes, res, { routed, session, turn, clientLeft: () => closedEarly }),
+        );
+        up.on('error', (error) => {
+          if (closedEarly) return; // aborted above because the client left
+          fail(res, new Error(`upstream: ${error.message}`));
+        });
+        up.end(body);
+      } catch (error) {
+        fail(res, error);
       }
-      const headers = {};
-      for (const [name, value] of Object.entries(req.headers)) if (!HOP_BY_HOP.has(name)) headers[name] = value;
-      headers.host = target.host;
-      headers['content-length'] = String(body.length);
-      const up = send(
-        { host: target.hostname, port: target.port || undefined, path: req.url, method: req.method, headers },
-        (upRes) => {
-          const reader = routed && !routed.auxiliary ? new UsageReader() : null;
-          res.writeHead(upRes.statusCode, upRes.headers);
-          upRes.on('data', (c) => {
-            if (reader) reader.feed(c.toString('utf8'));
-          });
-          upRes.on('end', () => {
-            if (reader && upRes.statusCode < 300) router.recordResponse(session, routed.tier, reader.end());
-          });
-          upRes.pipe(res);
-        },
-      );
-      up.on('error', (error) => {
-        onError(error);
-        if (!res.headersSent) res.writeHead(502);
-        res.end();
-      });
-      up.end(body);
     });
   });
+
+  function relay(upRes, res, { routed, session, turn, clientLeft }) {
+    const reader = turn ? new UsageReader() : null;
+    // pipeline() reports ECONNRESET for both kinds of failure; only the side that closed first says whose it was.
+    let upstreamBroke = false;
+    upRes.once('close', () => {
+      upstreamBroke = !upRes.complete && !clientLeft();
+    });
+    res.writeHead(upRes.statusCode, upRes.headers);
+    if (reader) upRes.on('data', (c) => reader.feed(c.toString('utf8')));
+    // pipeline() tears down both sides on failure. An upstream reset reaches the client as a reset it retries at once,
+    // where pipe() left it waiting for bytes that never came; a client that leaves stops the upstream response.
+    pipeline(upRes, res, (error) => {
+      if (error) {
+        if (upstreamBroke) onError(new Error(`upstream stream: ${error.message}`));
+        return;
+      }
+      if (!reader || upRes.statusCode >= 300) return;
+      const usage = reader.end();
+      if (reader.stopReason === 'tool_use') activity.turnPaused(session);
+      if (!routed || routed.auxiliary) return;
+      try {
+        router.recordResponse(session, routed.tier, usage);
+      } catch (recordError) {
+        onError(recordError);
+      }
+    });
+  }
+
+  function fail(res, error) {
+    onError(error);
+    if (!res.headersSent) res.writeHead(502);
+    res.end();
+  }
 }
 
 // Claude Code sends its session id as a header; the metadata field is the fallback.
@@ -77,29 +127,64 @@ export function sessionKey(req, body) {
   }
 }
 
+// A web page can reach a loopback port too: by DNS rebinding (a foreign Host) or by a cross-site request (a foreign
+// Origin). Claude Code sends a loopback Host and no Origin.
+function isLocalClient(req) {
+  if (!LOOPBACK.has(hostOf(req.headers.host))) return false;
+  const origin = req.headers.origin;
+  if (origin === undefined) return true;
+  try {
+    return LOOPBACK.has(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+
+function hostOf(host = '') {
+  return host.replace(/:\d+$/, '').toLowerCase();
+}
+
+// Only a Messages call is a turn. Side endpoints such as count_tokens carry the alias too, but no decision.
+function isMessagesCall(req) {
+  return req.method === 'POST' && req.url.split('?')[0] === MESSAGES_PATH;
+}
+
+function parseJson(buffer) {
+  if (!buffer.length) return null;
+  try {
+    return JSON.parse(buffer.toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
 function discovery(router, res) {
   const { alias } = router.config.gateway;
-  res.writeHead(200, { 'content-type': 'application/json' });
-  res.end(
-    JSON.stringify({
-      data: [
-        {
-          id: alias,
-          display_name: ROUTER_DISPLAY_NAME,
-          description: routesDescription(router.config),
-        },
-      ],
-    }),
-  );
+  reply(res, 200, {
+    data: [{ id: alias, display_name: ROUTER_DISPLAY_NAME, description: routesDescription(router.config) }],
+  });
 }
 
 function status(router, req, res) {
   const session = new URL(req.url, 'http://localhost').searchParams.get('session');
-  res.writeHead(200, { 'content-type': 'application/json' });
-  res.end(JSON.stringify(statusSnapshot(router.config, session ? router.memory(session) : null)));
+  const pausedUntil = router.jevPausedUntil > router.now() ? new Date(router.jevPausedUntil).toISOString() : null;
+  reply(res, 200, {
+    ...statusSnapshot(router.config, session ? router.memory(session) : null),
+    pid: process.pid,
+    jevPausedUntil: pausedUntil,
+  });
+}
+
+function reply(res, statusCode, payload) {
+  res.writeHead(statusCode, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(payload));
+}
+
+function errorBody(type, message) {
+  return { type: 'error', error: { type, message } };
 }
 
-// "Picks claude-opus-5-5 / claude-sonnet-4-6 / claude-haiku-4-5 and the effort for each turn"
+// "Picks claude-opus-5-5 / claude-sonnet-5 / claude-haiku-4-5 and the effort for each turn"
 export function routesDescription(config) {
   const ids = [...new Set(Object.values(config.routes).map((r) => config.models[r.model].id))];
   return `Picks ${ids.join(' / ')} and the effort for each turn`;

package/lib/idle.mjs

@@ -0,0 +1,41 @@
+// When the gateway may exit on its own. Claude Code holds no connection open between requests, so an idle session
+// and a closed one look the same here: the signal is time without requests. Two cases must still keep the gateway:
+// a request in flight, and a turn that waits for a tool result (a permission prompt or a question nobody answered
+// yet), whose next request comes without a prompt and so without the hook that would start a gateway again.
+// A session killed mid-turn stops counting after TURN_WAIT_MS.
+export const TURN_WAIT_MS = 24 * 3_600_000;
+
+export class IdleTracker {
+  constructor({ now = Date.now } = {}) {
+    this.now = now;
+    this.inFlight = 0;
+    this.lastActive = now();
+    this.waiting = new Map(); // session -> when its last response asked for a tool
+  }
+
+  requestStarted() {
+    this.inFlight += 1;
+    this.lastActive = this.now();
+  }
+
+  requestEnded() {
+    this.inFlight -= 1;
+    this.lastActive = this.now();
+  }
+
+  // A Messages request for the session: whatever it waited for has arrived.
+  turnResumed(session) {
+    this.waiting.delete(session);
+  }
+
+  turnPaused(session) {
+    this.waiting.set(session, this.now());
+  }
+
+  idle(idleMs) {
+    const now = this.now();
+    if (this.inFlight > 0 || now - this.lastActive < idleMs) return false;
+    for (const [session, at] of this.waiting) if (now - at >= TURN_WAIT_MS) this.waiting.delete(session);
+    return this.waiting.size === 0;
+  }
+}

package/lib/jev.mjs

@@ -34,6 +34,8 @@ const ROUTE_INSTRUCTIONS = {
 const CONTINUATION_INSTRUCTIONS =
   'Is `currentRequest.text` a continuation of the task in `recentDialogue` (for example "continue", "yes", "now fix the tests"), rather than a new task?';
 const TRANSIENT = new Set([408, 429, 500, 502, 503, 504]);
+const RETRY_DELAY_MS = 100;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 export function buildRequest(config, prompt, turns) {
   const criteria = {};
@@ -49,25 +51,44 @@ export function buildRequest(config, prompt, turns) {
   };
 }
 
-// Returns { choice, confidence, probabilities, continuation } or throws. One retry on a transient status within the budget.
-export async function askJev({ fetchFn, config, apiKey, prompt, turns, now = Date.now }) {
+// Returns { choice, confidence, probabilities, continuation } or throws. One retry on a network error or a transient
+// status, after Retry-After when the server sends one; a wait that would not fit the budget is not taken.
+export async function askJev({ fetchFn, config, apiKey, prompt, turns, now = Date.now, sleep = delay }) {
   const deadline = now() + config.jev.timeoutMs;
   const body = JSON.stringify(buildRequest(config, prompt, turns));
   for (let attempt = 0; attempt < 2; attempt += 1) {
     const remaining = deadline - now();
     if (remaining <= 0) throw new Error('jev timeout');
-    const response = await fetchFn(config.jev.endpoint, {
-      method: 'POST',
-      headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
-      body,
-      signal: AbortSignal.timeout(remaining),
-    });
+    let response;
+    try {
+      response = await fetchFn(config.jev.endpoint, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+        body,
+        signal: AbortSignal.timeout(remaining),
+      });
+    } catch (error) {
+      if (error.name === 'TimeoutError') throw new Error('jev timeout');
+      if (attempt === 1) throw new Error(`jev unreachable: ${error.message}`);
+      await sleep(RETRY_DELAY_MS);
+      continue;
+    }
     if (response.ok) return parseAnswers(await response.json());
     if (!TRANSIENT.has(response.status) || attempt === 1) throw new Error(`jev http ${response.status}`);
+    const wait = retryAfterMs(response.headers) ?? RETRY_DELAY_MS;
+    if (wait >= deadline - now()) throw new Error(`jev http ${response.status}, retry-after beyond the budget`);
+    await sleep(wait);
   }
   throw new Error('jev unreachable');
 }
 
+function retryAfterMs(headers) {
+  const value = headers?.get?.('retry-after');
+  if (value === null || value === undefined || value === '') return null;
+  const seconds = Number(value);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
+}
+
 export function parseAnswers(json) {
   const route = json?.answers?.route;
   if (route?.type !== 'choice' || typeof route.probabilities !== 'object') throw new Error('jev malformed answer');

package/lib/policy.mjs

@@ -56,6 +56,23 @@ export function decide({ config, facts, advice, state, baseline, now }) {
   return stay('downgrade-pending', estimate);
 }
 
+// Share of a model's window the next request may fill. The estimate leaves out the new prompt and tool
+// results, so a model drops out before the conversation reaches its limit.
+const CONTEXT_FILL = 0.8;
+
+// The lowest tier at or above `tier` whose model fits `tokens` of context. Routes need not grow in window
+// with rank, so the search falls back to any tier that fits, then to the largest window, keeping `tier` on a tie.
+export function fitTier(config, tier, tokens) {
+  const windowOf = (t) => config.models[config.routes[t].model].contextWindow;
+  const fits = (t) => tokens <= windowOf(t) * CONTEXT_FILL;
+  if (fits(tier)) return tier;
+  return (
+    TIERS.slice(rank(tier)).find(fits) ??
+    TIERS.find(fits) ??
+    TIERS.reduce((best, t) => (windowOf(t) > windowOf(best) ? t : best), tier)
+  );
+}
+
 // Automatic routing to a credits-billed model must fit the cash cap unless its cache is warm.
 function cashGate(config, tier, facts, now) {
   const alias = config.routes[tier].model;

package/lib/router.mjs

@@ -1,23 +1,40 @@
 // Per-request orchestration: facts -> advice -> policy -> rewritten body. Knows nothing about HTTP.
+import { nextContextTokens } from './cost.mjs';
 import { factsFromRequest } from './facts.mjs';
 import { askJev } from './jev.mjs';
-import { decide, initialState } from './policy.mjs';
+import { decide, fitTier, initialState } from './policy.mjs';
 import { rewriteRequest } from './rewrite.mjs';
 import { appendLog, loadMemory, saveMemory } from './store.mjs';
 
 const COMPACTION_SHRINK = 0.8;
+// Jev down: after this many failures in a row, new turns skip it for the cooldown instead of waiting out its timeout.
+export const JEV_FAILURES_TO_PAUSE = 3;
+export const JEV_PAUSE_MS = 60_000;
+// Reasons that reuse the route of the turn and must not replace the reason that chose it.
+const REUSED_ROUTE = new Set(['tool-continuation', 'retry']);
 
 export function emptyMemory() {
-  return { lastRoute: null, lastReason: null, lastEffort: null, lastRequest: null, models: {}, state: null };
+  return {
+    lastRoute: null,
+    lastReason: null,
+    lastEffort: null,
+    lastRequest: null,
+    lastTurnKey: null,
+    models: {},
+    state: null,
+  };
 }
 
 export class Router {
-  constructor({ config, fetchFn, dataDir, now = Date.now }) {
+  constructor({ config, fetchFn, dataDir, now = Date.now, onError = () => {} }) {
     this.config = config;
     this.fetchFn = fetchFn;
     this.dataDir = dataDir;
     this.now = now;
+    this.onError = onError;
     this.memories = new Map();
+    this.jevFailures = 0;
+    this.jevPausedUntil = 0;
   }
 
   isRouted(body) {
@@ -34,13 +51,20 @@ export class Router {
     if (auxiliary) decision = { tier: this.config.gateway.auxiliaryTier, reason: 'auxiliary', state: memory.state };
     else if (facts.continuation && memory.lastRoute)
       decision = { tier: memory.lastRoute, reason: 'tool-continuation', state: memory.state };
+    else if (facts.turnKey && facts.turnKey === memory.lastTurnKey && memory.lastRoute)
+      decision = { tier: memory.lastRoute, reason: 'retry', state: memory.state };
     else decision = await this.decideTurn(facts, memory);
+    // Main turns and compaction carry the main conversation; other side requests have their own, unknown size.
+    if (!auxiliary || requestClass === 'compaction') {
+      const tier = fitTier(this.config, decision.tier, nextContextTokens(facts));
+      if (tier !== decision.tier) decision = { ...decision, tier, reason: 'context-fit' };
+    }
     const rewritten = rewriteRequest(body, decision.tier, this.config);
     if (!auxiliary) {
       memory.lastRoute = decision.tier;
       memory.lastEffort = rewritten.output_config?.effort ?? null;
-      // A tool continuation keeps the reason of the decision that started the turn.
-      if (decision.reason !== 'tool-continuation') memory.lastReason = decision.reason;
+      memory.lastTurnKey = facts.turnKey;
+      if (!REUSED_ROUTE.has(decision.reason)) memory.lastReason = decision.reason;
       memory.state = decision.state;
       this.persist(sessionId, memory);
     }
@@ -68,6 +92,12 @@ export class Router {
     return { body: rewriteRequest(body, tier, this.config), tier, reason: 'error', auxiliary: true };
   }
 
+  // Side endpoints (count_tokens) name the alias too. They get the session's current model: no Jev call, no vote.
+  resolveModel(body, sessionId) {
+    const tier = this.memory(sessionId).lastRoute ?? this.config.gateway.baselineTier;
+    return { body: rewriteRequest(body, tier, this.config), tier, reason: 'side-endpoint', auxiliary: true };
+  }
+
   async decideTurn(facts, memory) {
     const state = memory.state ?? initialState();
     const { forcedTier, apiKey, gateway } = this.config;
@@ -75,17 +105,22 @@ export class Router {
     let advice = null;
     let adviceError = null;
     if (apiKey && facts.prompt) {
-      try {
-        advice = await askJev({
-          fetchFn: this.fetchFn,
-          config: this.config,
-          apiKey,
-          prompt: facts.prompt,
-          turns: facts.turns,
-          now: this.now,
-        });
-      } catch (error) {
-        adviceError = error.message;
+      if (this.now() < this.jevPausedUntil) adviceError = 'jev paused after repeated failures';
+      else {
+        try {
+          advice = await askJev({
+            fetchFn: this.fetchFn,
+            config: this.config,
+            apiKey,
+            prompt: facts.prompt,
+            turns: facts.turns,
+            now: this.now,
+          });
+          this.jevSucceeded();
+        } catch (error) {
+          adviceError = error.message;
+          this.jevFailed(error);
+        }
       }
     }
     const decision = decide({
@@ -99,6 +134,25 @@ export class Router {
     return { ...decision, advice, adviceError };
   }
 
+  jevSucceeded() {
+    if (this.jevFailures >= JEV_FAILURES_TO_PAUSE) this.onError(new Error('jev answers again, routing resumed'));
+    this.jevFailures = 0;
+    this.jevPausedUntil = 0;
+  }
+
+  // The count stays at or above the threshold while Jev keeps failing: after a pause, one failed try pauses again.
+  jevFailed(error) {
+    this.jevFailures += 1;
+    if (this.jevFailures < JEV_FAILURES_TO_PAUSE) return;
+    this.jevPausedUntil = this.now() + JEV_PAUSE_MS;
+    if (this.jevFailures === JEV_FAILURES_TO_PAUSE)
+      this.onError(
+        new Error(
+          `jev failed ${JEV_FAILURES_TO_PAUSE} times in a row (${error.message}): new turns use the baseline, one try every ${JEV_PAUSE_MS / 1000}s`,
+        ),
+      );
+  }
+
   // Called with the usage the gateway read from a forwarded main-conversation response.
   recordResponse(sessionId, tier, usage) {
     if (!usage) return;
@@ -125,12 +179,22 @@ export class Router {
     return this.memories.get(sessionId);
   }
 
+  // Disk trouble (full, read-only) must not cost the routing decision: the in-memory state stays authoritative.
   persist(sessionId, memory) {
-    saveMemory(this.dataDir, sessionId, memory);
+    try {
+      saveMemory(this.dataDir, sessionId, memory);
+    } catch (error) {
+      this.onError(error);
+    }
   }
 
   log(entry) {
-    if (this.config.log) appendLog(this.dataDir, { at: new Date(this.now()).toISOString(), ...entry });
+    if (!this.config.log) return;
+    try {
+      appendLog(this.dataDir, { at: new Date(this.now()).toISOString(), ...entry });
+    } catch (error) {
+      this.onError(error);
+    }
   }
 }
 

package/lib/sse.mjs

@@ -1,9 +1,10 @@
-// Incremental usage reader for a Messages response: streaming SSE or a plain JSON body.
+// Incremental usage and stop-reason reader for a Messages response: streaming SSE or a plain JSON body.
 export class UsageReader {
   constructor() {
     this.buffer = '';
     this.usage = null;
     this.model = null;
+    this.stopReason = null;
   }
 
   feed(chunk) {
@@ -34,7 +35,11 @@ export class UsageReader {
       this.model = message.model ?? this.model;
       this.usage = { ...(this.usage ?? {}), ...message.usage };
     }
-    if (event.type === 'message_delta' && event.usage) this.usage = { ...(this.usage ?? {}), ...event.usage };
+    if (message?.stop_reason) this.stopReason = message.stop_reason;
+    if (event.type === 'message_delta') {
+      if (event.usage) this.usage = { ...(this.usage ?? {}), ...event.usage };
+      if (event.delta?.stop_reason) this.stopReason = event.delta.stop_reason;
+    }
   }
 
   result() {

package/lib/status.mjs

@@ -1,8 +1,20 @@
 // Router status: the snapshot the gateway serves at GET /router/status, and its text forms for the
 // status line and /router:status. The snapshot never carries the API key, only whether one is set.
+import { createRequire } from 'node:module';
 import { TIERS } from './config.mjs';
 import { clampEffort } from './rewrite.mjs';
 
+const _require = createRequire(import.meta.url);
+export const ROUTER_VERSION = _require('../package.json').version;
+
+// True when `running` is older than `current`. Gateways before 0.3.0 report no version: they count as older.
+export function isOlderVersion(running, current) {
+  const parse = (v) => (/^\d+\.\d+\.\d+/.test(v ?? '') ? v.split('.').map((n) => Number.parseInt(n, 10)) : [0, 0, 0]);
+  const [a, b] = [parse(running), parse(current)];
+  for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] < b[i];
+  return false;
+}
+
 export const STATUS_PATH = '/router/status';
 // The name of the alias in the /model picker and in discovery.
 export const ROUTER_DISPLAY_NAME = 'Router (auto)';
@@ -11,6 +23,7 @@ const FETCH_TIMEOUT_MS = 300;
 export function statusSnapshot(config, memory) {
   const { alias, port, baselineTier } = config.gateway;
   return {
+    version: ROUTER_VERSION,
     alias,
     port,
     keySet: Boolean(config.apiKey),
@@ -38,23 +51,24 @@ function routeRow(config, tier) {
   return { tier, model: model.id, effort };
 }
 
-// One status-line segment, e.g. "router ▸ opus-5-5 · xhigh (high)".
+// One status-line segment, e.g. "router ▸ opus-5-5 · xhigh".
 export function statusSegment(status) {
-  if (!status) return 'router: gateway down';
+  if (!status) return 'router: gateway off, the next prompt starts it';
   const last = status.session;
   if (!last) return `${status.alias}: no turn yet`;
   const model = shortModel(last.model ?? status.routes.find((r) => r.tier === last.tier)?.model);
   const effort = last.effort ? ` · ${last.effort}` : '';
-  return `${status.alias} ▸ ${model}${effort} (${last.tier})`;
+  return `${status.alias} ▸ ${model}${effort}`;
 }
 
 // Markdown for /router:status.
 export function statusReport(status) {
-  if (!status) return 'The router gateway does not answer. Start a new session, or run `node scripts/gateway.mjs`.';
+  if (!status)
+    return 'The router gateway is not running. The next prompt starts it. If it does not start, read `gateway.log` in the plugin data directory.';
   const lines = [
-    `Gateway: http://127.0.0.1:${status.port}, alias \`${status.alias}\`.`,
-    `Jev key: ${status.keySet ? 'set' : 'not set, every turn runs on the baseline tier'}.`,
-    `Baseline tier: ${status.baselineTier}.${status.forcedTier ? ` Forced tier: ${status.forcedTier}.` : ''}`,
+    `Router v${status.version}, gateway: http://127.0.0.1:${status.port}, alias \`${status.alias}\`.`,
+    `Jev routing: ${jevState(status)}.`,
+    `Default tier: ${status.baselineTier}.${status.forcedTier ? ` Forced tier: ${status.forcedTier}.` : ''}`,
     '',
     '| Tier | Model | Effort |',
     '| ---- | ----- | ------ |',
@@ -85,6 +99,12 @@ export async function fetchStatus(port, sessionId) {
   }
 }
 
+function jevState(status) {
+  if (!status.keySet) return 'inactive, no key: every turn runs on the default tier';
+  if (status.jevPausedUntil) return `paused after repeated failures, next try at ${status.jevPausedUntil}`;
+  return 'active';
+}
+
 function shortModel(id) {
   return id ? id.replace(/^claude-/, '') : 'unknown';
 }