@goodandready/dsh-key-rotation 0.8.83 → 0.8.85

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.8.85 (2026-11-03)
+
+### Inter-Token Stall & Zombie Stream Detector (Block 12 Release)
+- **Watchdog Stream Protection (Issue #569)**: Added `withStreamWatchdog` and `StreamStallError` (`src/stream-watchdog.js`) to continuously monitor active token streams and protect against zombie HTTP connections and provider gateway hangs.
+- **Differentiated Reasoning & Inter-Token Timeouts**: Configurable `stallInitialTimeoutMs` (default: 30s) prevents false positives during initial reasoning generation for DeepSeek R1 and OpenAI o1/o3, while `stallTimeoutMs` (default: 15s) immediately aborts stalled streams when tokens stop arriving mid-response.
+- **Failover & Cooldown Integration (`src/rotate.js`)**: If a stall occurs before any token has yielded, the key is penalized and failover immediately rotates to the next available provider candidate. If a mid-stream stall occurs after partial output, the key is penalized and a structured `STREAM_STALLED` terminal chunk is delivered, keeping the conversation from hanging.
+- **Config & Taxonomy Support**: Added `stallDetectionEnabled`, `stallTimeoutMs`, and `stallInitialTimeoutMs` to Schemastery `SettingsSchema` and `PoolConfig` types, and integrated `STREAM_STALLED` into error taxonomy and 24-hour operations analytics as a recoverable `TIMEOUT`.
+
+## 0.8.84 (2026-10-31)
+
+### DSH 0.2.2 Cordis Service Isolation Compatibility (Hotfix Release)
+- **DSH 0.2.2 Strict Isolation (Issue #567, #568, GitHub #27)**: Resolved Cordis service access without explicit inject by introducing scoped inject guards for `webServer`, `settings`, and optional services across all HTTP routes, lifecycle hooks, and plugin updater.
+- **Zero-Breakage Backward Compatibility**: Retained full compatibility with DSH 0.2.1 and headless environments while ensuring strict adherence to Cordis 0.2.2+ isolation rules.
+
 ## 0.8.83 (2026-10-31)
 
 ### TypeScript Migration & Type-Safe Core Architecture (Block 11 Release)

package/lib/error-taxonomy.js

@@ -95,7 +95,7 @@ export function classifyFailure(failureOrPayload) {
   if (SURFACE_STATUS.has(status)) {
     return { action: 'surface', code: String(status), soft: false, reason: 'client' };
   }
-  if (code === 'TIMEOUT' || code === 'DEADLINE_EXCEEDED' || /timeout/i.test(message)) {
+  if (code === 'TIMEOUT' || code === 'DEADLINE_EXCEEDED' || code === 'STREAM_STALLED' || /timeout|stream stalled/i.test(message)) {
     return { action: 'switch', code: 'TIMEOUT', soft: true, reason: 'timeout' };
   }
   if (SOCKET_SWITCH.has(code) || /ECONNRESET|ECONNREFUSED|ETIMEDOUT|socket hang up|premature close/i.test(message)) {

package/lib/index.js

@@ -36,6 +36,7 @@ import { CircuitBreaker } from './circuit-breaker.js';
 import { NotifyQueue } from './notify-queue.js';
 import { classifyFailure } from './error-taxonomy.js';
 import { registerOpsRoutes } from './routes-ops.js';
+import { getWebServer } from './routes/guard.js';
 import { registerPluginUpdater } from './plugin-updater.js';
 import { notifySwitch, notifyExhaustion, notifyEarlyWarning, pushEvent } from './notify-events.js';
 import { QUOTA_WINDOW_TYPES } from './quota-window.js';
@@ -136,6 +137,9 @@ const SettingsSchema = Schema.object({
   warnBelowHealthy: Schema.number().default(0),
   latencySloMs: Schema.number().default(0),
   showChatHeaderChip: Schema.boolean().default(true),
+  stallDetectionEnabled: Schema.boolean().default(true),
+  stallTimeoutMs: Schema.number().default(15000),
+  stallInitialTimeoutMs: Schema.number().default(30000),
   providers: Schema.array(Schema.object({
     provider: Schema.string().required(),
     keys: Schema.array(Schema.string()).default([]),
@@ -165,6 +169,9 @@ const SettingsSchema = Schema.object({
     proactiveRateLimitGuard: Schema.boolean(),
     rpmLimit: Schema.number(),
     tpmLimit: Schema.number(),
+    stallDetectionEnabled: Schema.boolean(),
+    stallTimeoutMs: Schema.number(),
+    stallInitialTimeoutMs: Schema.number(),
   })).default([...DEFAULT_PROVIDERS]),
 });
 
@@ -178,7 +185,7 @@ export const Config = typeof Schema.number().volatile === 'function'
   : SettingsSchema;
 
 function registerConfigBridge(ctx, getCloneIds) {
-  return ctx.webServer.register({
+  return getWebServer(ctx).register({
     kind: 'exact',
     path: CONFIG_PATH,
     handler: (req, res) => {
@@ -246,9 +253,11 @@ export function apply(ctx, config = {}) {
 
   setupAutoUnbreakEffect(ctx, getConfig, buildRuntime, ensureSandboxRunner, logger);
 
-  // Dynamic webServer registration (#528)
+  // Dynamic webServer registration (#528, #567)
   const setupWebRoutes = (webCtx = ctx) => {
-    const target = webCtx?.webServer ? webCtx : ctx;
+    const target = getWebServer(webCtx) ? webCtx : ctx;
+    const ws = getWebServer(target);
+    if (!ws) return;
     registerConfigBridge(target, () => buildRuntime().cloneIds);
     registerOpsRoutes(target, {
       buildRuntime,
@@ -265,7 +274,7 @@ export function apply(ctx, config = {}) {
       selectionTraceStore,
       diagBuffer,
     });
-    if (typeof target.webServer?.register === 'function') {
+    if (typeof ws?.register === 'function') {
       registerPluginUpdater(target, {
         endpoint: '/api/dsh-key-rotation/update',
         packageName: '@goodandready/dsh-key-rotation',
@@ -274,10 +283,12 @@ export function apply(ctx, config = {}) {
     }
   };
 
-  if (ctx.webServer) {
+  if (Object.prototype.hasOwnProperty.call(ctx, 'webServer') && ctx.webServer) {
     setupWebRoutes(ctx);
   } else if (typeof ctx.inject === 'function') {
     ctx.inject(['webServer'], setupWebRoutes);
+  } else if (getWebServer(ctx)) {
+    setupWebRoutes(ctx);
   }
 
   // Periodic sweep of expired cooldowns

package/lib/lifecycle.js

@@ -45,7 +45,7 @@ export function setupAutoUnbreakEffect(ctx, getConfig, buildRuntime, ensureSandb
         await autoUnbreakBrokenKeys(pools, async (ref) => {
           // A rotating resolver can substitute a healthy neighbor for this
           // quarantined ref, falsely proving that the broken key recovered.
-          const credentials = ctx.get?.('credentials') ?? ctx.credentials;
+          const credentials = (typeof ctx?.get === 'function' ? ctx.get('credentials') : undefined) ?? (ctx && Object.prototype.hasOwnProperty.call(ctx, 'credentials') ? ctx.credentials : undefined);
           const resolve = credentials?.__dshKeyRotationOriginalResolve ?? credentials?.resolve;
           const hit = await resolve?.call(credentials, ref);
           const raw = typeof hit?.value === 'string' && hit.value.length > 0
@@ -197,7 +197,7 @@ export function setupProactiveHealthProbeEffect(ctx, getConfig, buildRuntime, en
           for (const ref of candidates) {
             if (disposed) break;
             try {
-              const credentials = ctx.get?.('credentials') ?? ctx.credentials;
+              const credentials = (typeof ctx?.get === 'function' ? ctx.get('credentials') : undefined) ?? (ctx && Object.prototype.hasOwnProperty.call(ctx, 'credentials') ? ctx.credentials : undefined);
               const resolve = credentials?.__dshKeyRotationOriginalResolve ?? credentials?.resolve;
               const hit = await resolve?.call(credentials, ref);
               const raw = typeof hit?.value === 'string' && hit.value.length > 0 ? hit.value : envValue(ref);

package/lib/ops-analytics.js

@@ -18,7 +18,7 @@ export function classifyErrorCategory(code, message = '') {
   if (/^5\d\d$/.test(c) || c === 'SERVER' || c === 'BAD_GATEWAY' || c === 'SERVICE_UNAVAILABLE' || m.includes('internal server error')) {
     return 'server';
   }
-  if (c.includes('TIMEOUT') || c === 'ETIMEDOUT' || c === 'ESOCKETTIMEDOUT' || m.includes('timeout') || m.includes('timed out')) {
+  if (c.includes('TIMEOUT') || c.includes('STALL') || c === 'ETIMEDOUT' || c === 'ESOCKETTIMEDOUT' || m.includes('timeout') || m.includes('timed out') || m.includes('stalled')) {
     return 'timeout';
   }
   if (c === 'QUOTA' || c === '402' || c.includes('QUOTA') || m.includes('quota') || m.includes('credit') || m.includes('insufficient_quota')) {

package/lib/plugin-updater.js

@@ -314,7 +314,10 @@ function json(response, statusCode, value) {
 
 export function registerPluginUpdater(ctx, options) {
   let installing = false
-  return ctx.webServer.register({
+  const viaOwn = ctx && Object.prototype.hasOwnProperty.call(ctx, 'webServer') && typeof ctx.webServer?.register === 'function' ? ctx.webServer : undefined
+  const viaGet = typeof ctx?.get === 'function' ? ctx.get('webServer') : undefined
+  const ws = viaOwn ?? (typeof viaGet?.register === 'function' ? viaGet : undefined) ?? ctx?.webServer
+  return ws.register({
     kind: 'exact',
     path: options.endpoint,
     handler: async (request, response) => {

package/lib/pool-builder.js

@@ -41,6 +41,9 @@ export function buildPoolItem({
   maxQueueWaitMs = null,
   maxAttempts = null,
   maxDurationMs = null,
+  stallDetectionEnabled = true,
+  stallTimeoutMs = 15000,
+  stallInitialTimeoutMs = 30000,
 }) {
   const seen = new Set();
   const indexed = (Array.isArray(keys) ? keys : []).map((key, index) => ({ ref: typeof key === 'string' ? key.trim() : '', index }))
@@ -151,6 +154,9 @@ const weightsMap = {};
     maxDurationMs: typeof maxDurationMs === 'number' && Number.isFinite(maxDurationMs) && maxDurationMs > 0
       ? Math.floor(maxDurationMs)
       : 0,
+    stallDetectionEnabled: stallDetectionEnabled ?? true,
+    stallTimeoutMs: typeof stallTimeoutMs === 'number' && Number.isFinite(stallTimeoutMs) && stallTimeoutMs > 0 ? Math.floor(stallTimeoutMs) : 15000,
+    stallInitialTimeoutMs: typeof stallInitialTimeoutMs === 'number' && Number.isFinite(stallInitialTimeoutMs) && stallInitialTimeoutMs > 0 ? Math.floor(stallInitialTimeoutMs) : 30000,
   };
 }
 
@@ -198,6 +204,9 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
       maxQueueWaitMs: p.maxQueueWaitMs ?? cfg.maxQueueWaitMs,
       maxAttempts: poolAttempts,
       maxDurationMs: poolDuration,
+      stallDetectionEnabled: p.stallDetectionEnabled ?? cfg.stallDetectionEnabled ?? true,
+      stallTimeoutMs: p.stallTimeoutMs ?? cfg.stallTimeoutMs ?? 15000,
+      stallInitialTimeoutMs: p.stallInitialTimeoutMs ?? cfg.stallInitialTimeoutMs ?? 30000,
     }, provRpm, provTpm, provConcurrency);
     if (pool) {
       for (const ref of pool.refs) {
@@ -230,6 +239,9 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
         maxQueueWaitMs: mp.maxQueueWaitMs ?? p.maxQueueWaitMs ?? cfg.maxQueueWaitMs,
         maxAttempts: typeof mp.maxAttempts === 'number' ? mp.maxAttempts : poolAttempts,
         maxDurationMs: typeof mp.maxDurationMs === 'number' ? mp.maxDurationMs : poolDuration,
+        stallDetectionEnabled: mp.stallDetectionEnabled ?? p.stallDetectionEnabled ?? cfg.stallDetectionEnabled ?? true,
+        stallTimeoutMs: mp.stallTimeoutMs ?? p.stallTimeoutMs ?? cfg.stallTimeoutMs ?? 15000,
+        stallInitialTimeoutMs: mp.stallInitialTimeoutMs ?? p.stallInitialTimeoutMs ?? cfg.stallInitialTimeoutMs ?? 30000,
       }, modelRpm, modelTpm, modelConcurrency);
       if (!mpool) continue;
       mpool.basePool = pool;

package/lib/pool.js

@@ -491,6 +491,7 @@ export function isSwitchableError(failureOrPayload, switchCodes = new Set(DEFAUL
   let rawCode = String(failure.code ?? failure.reason ?? '').trim();
   let code = rawCode.toUpperCase();
   if (code && SOCKET_TRANSPORT_CODES.has(code)) code = 'TRANSPORT';
+  if (code === 'STREAM_STALLED' || code === 'STALL_TIMEOUT' || code === 'INTER_TOKEN_STALL') code = 'TIMEOUT';
   const message = String(failure.message ?? failureOrPayload.message ?? '');
 
   // Treat numeric failure.code (e.g. code: "429") as HTTP status if status was not set (#545)

package/lib/rotate.js

@@ -26,6 +26,7 @@ import {
 
 import { LOCAL_POOL_EXHAUSTED_CODE, resolveKeyDirectly } from './resolver.js';
 import { recordStreamSuccessMetrics, preserveDispatchContext } from './stream-metrics.js';
+import { withStreamWatchdog, StreamStallError } from './stream-watchdog.js';
 import { penalizeKey } from './rotate-penalty.js';
 import { recordPromptCache } from './prompt-cache.js';
 import { recordRequestOutcome, recordFailureCategory } from './ops-analytics.js';
@@ -310,8 +311,33 @@ export function createRotate(deps) {
           }
 
           const _pickedRef = reqStore.pickedRef ?? pool.state.lastUsed;
+          let stallAbort = null;
+          if (typeof AbortController !== 'undefined') {
+            stallAbort = new AbortController();
+            if (budget?.signal) {
+              if (budget.signal.aborted) {
+                try { stallAbort.abort(budget.signal.reason); } catch {}
+              } else {
+                budget.signal.addEventListener('abort', () => {
+                  try { stallAbort?.abort(budget.signal.reason); } catch {}
+                }, { once: true });
+              }
+            }
+          }
+          const guardedStream = withStreamWatchdog(
+            preserveDispatchContext(inner, dispatchStorage, reqStore),
+            {
+              stallDetectionEnabled: pool.stallDetectionEnabled ?? runtime0.stallDetectionEnabled ?? true,
+              stallTimeoutMs: pool.stallTimeoutMs ?? runtime0.stallTimeoutMs ?? 15000,
+              stallInitialTimeoutMs: pool.stallInitialTimeoutMs ?? runtime0.stallInitialTimeoutMs ?? 30000,
+              abortController: stallAbort,
+              onStall: (err) => {
+                logWarn(`[dsh-key-rotation] ${options.provider}: key ${String(_pickedRef ?? '?')} stalled (${err.message})`);
+              },
+            }
+          );
           try {
-            for await (const chunk of preserveDispatchContext(inner, dispatchStorage, reqStore)) {
+            for await (const chunk of guardedStream) {
                 if (!reqStore.concurrencyRef && typeof concurrencyTracker?.acquire === 'function') {
                   const fallbackRef = reqStore.pickedRef ?? _pickedRef;
                   if (fallbackRef) {
@@ -434,33 +460,36 @@ export function createRotate(deps) {
             } catch (e) {
               const effectiveSwitchCodes = pool.switchCodes ?? switchCodes;
               const activeRef = _pickedRef ?? reqStore.pickedRef ?? pool.state.lastUsed ?? attemptList[attempt];
+              const isStall = e instanceof StreamStallError || e?.code === 'STREAM_STALLED' || e?.isStall;
               if (!yielded && isSwitchableError(e, effectiveSwitchCodes)) {
+                const failCode = isStall ? 'STREAM_STALLED' : (e?.code ?? 'TRANSPORT');
+                const catCode = isStall ? 'TIMEOUT' : failCode;
                 preTokenBuffer.length = 0; // Discard metadata from failed attempt (#527)
-                penalizeRef(activeRef, e?.code ?? 'TRANSPORT', String(e?.message ?? e), e?.headers ?? e?.response?.headers ?? pool.state.detectedLimits?.get?.(activeRef));
-                recordFailureCategory(pool, e?.code ?? 'TRANSPORT', String(e?.message ?? e), activeRef, now());
+                penalizeRef(activeRef, catCode, String(e?.message ?? e), e?.headers ?? e?.response?.headers ?? pool.state.detectedLimits?.get?.(activeRef));
+                recordFailureCategory(pool, catCode, String(e?.message ?? e), activeRef, now());
                 pool.state.switches = (pool.state.switches ?? 0) + 1;
-                pool.state.lastReason = String(e?.code ?? 'TRANSPORT');
+                pool.state.lastReason = failCode;
                 pool.state.lastSwitchAt = now();
-                lastFailure = finishError(e?.code ?? 'TRANSPORT', String(e?.message ?? e));
-                logWarn(`[dsh-key-rotation] ${options.provider}: key ${String(activeRef ?? '?')} stream threw before first token ${String(e?.code ?? e?.message ?? e)} - failover to next key`);
+                lastFailure = finishError(failCode, String(e?.message ?? e));
+                logWarn(`[dsh-key-rotation] ${options.provider}: key ${String(activeRef ?? '?')} stream threw before first token ${failCode} - failover to next key`);
                 if (switchNotify && activeRef) {
                   notifySwitch(runtime0, pool, {
                     provider: options.provider,
                     from: activeRef,
-                    code: String(e?.code ?? 'TRANSPORT'),
+                    code: failCode,
                     at: pool.state.lastSwitchAt,
                   });
                 }
                 continue; // Failover to next key!
               }
-              if (yielded && isSwitchableError(e, effectiveSwitchCodes)) {
-                penalizeRef(activeRef, e?.code ?? 'TRANSPORT', String(e?.message ?? e), e?.headers ?? e?.response?.headers ?? pool.state.detectedLimits?.get?.(activeRef));
+              if (yielded && (isStall || isSwitchableError(e, effectiveSwitchCodes))) {
+                penalizeRef(activeRef, isStall ? 'TIMEOUT' : (e?.code ?? 'TRANSPORT'), String(e?.message ?? e), e?.headers ?? e?.response?.headers ?? pool.state.detectedLimits?.get?.(activeRef));
               }
               if (!yielded) {
                 for (const prev of preTokenBuffer) yield prev;
                 preTokenBuffer.length = 0;
               }
-              yield finishError(e?.code ?? 'TRANSPORT', String(e?.message ?? e));
+              yield finishError(isStall ? 'STREAM_STALLED' : (e?.code ?? 'TRANSPORT'), String(e?.message ?? e));
               return;
             }
 

package/lib/routes/balance.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-balance.js — operational HTTP routes for balance inspection (#495).
 
 import {
@@ -18,7 +19,7 @@ export function registerBalanceRoutes(ctx, deps) {
     buildRuntime,
   } = deps;
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: BALANCE_PATH,
     handler: async (req, res) => {

package/lib/routes/config.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-config-io.js — full configuration export and import (#504).
 import crypto from 'node:crypto';
 import { readFileSync } from 'node:fs';
@@ -187,7 +188,7 @@ export function diffConfigs(currentConfig, incomingConfig, mode = 'merge') {
 
 export function registerConfigIoRoutes(ctx, deps) {
   // ── GET & POST /dsh-key-rotation/export (#552: support POST for safe passphrase transmission) ──
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: CONFIG_EXPORT_PATH,
     handler: async (req, res) => {
@@ -448,7 +449,7 @@ export function registerConfigIoRoutes(ctx, deps) {
     });
   };
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: CONFIG_IMPORT_PATH,
     handler: handleImport,

package/lib/routes/guard.js

@@ -11,3 +11,26 @@ export {
   json,
   readJson,
 } from '../http-bridge.js';
+
+/**
+ * Safely resolve webServer from a Cordis context or test mock without
+ * triggering Cordis's Proxy trap (`cannot get property "webServer" without inject`)
+ * when `webServer` is provided by a sibling plugin and not in static `inject`.
+ */
+export function getWebServer(ctx) {
+  if (!ctx) return undefined;
+  if (Object.prototype.hasOwnProperty.call(ctx, 'webServer') && typeof ctx.webServer?.register === 'function') {
+    return ctx.webServer;
+  }
+  if (typeof ctx.get === 'function') {
+    const viaGet = ctx.get('webServer');
+    if (typeof viaGet?.register === 'function') return viaGet;
+  }
+  try {
+    const ws = ctx.webServer;
+    if (typeof ws?.register === 'function') return ws;
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}

package/lib/routes/keys.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 import { decryptSecret, encryptSecret } from '../crypto-storage.js';
 // lib/ops-keys.js — key store + cooldown reset + import routes (#312 split from routes-ops.js).
 import {
@@ -156,7 +157,7 @@ export async function discoverUnconfiguredKeys(ctx, runtimePools = []) {
 
 export function registerKeyRoutes(ctx, deps) {
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: DRAIN_PATH,
   handler: async (req, res) => {
@@ -219,7 +220,7 @@ ctx.effect(() => ctx.webServer.register({
 // it is never sent back, only its last few characters are (see the status
 // route) — and the route is loopback- and same-origin-gated like the config
 // bridge next to it.
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: KEY_PATH,
   handler: async (req, res) => {
@@ -289,7 +290,7 @@ ctx.effect(() => ctx.webServer.register({
 
 
 // ── reset route: clear cooldown for a provider (or a single ref) ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: RESET_PATH,
   handler: async (req, res) => {
@@ -374,7 +375,7 @@ ctx.effect(() => ctx.webServer.register({
 }), 'dsh-key-rotation: reset route');
 
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: IMPORT_PATH,
   handler: async (req, res) => {
@@ -411,7 +412,7 @@ ctx.effect(() => ctx.webServer.register({
 // Health for external panels (Beszel/Uptime)
 
 // ── discover unconfigured keys route (#491) ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: DISCOVER_PATH,
   handler: async (req, res) => {
@@ -434,7 +435,7 @@ ctx.effect(() => ctx.webServer.register({
 }), 'dsh-key-rotation: discover route');
 
 // ── auto-import discovered keys into pools (#491) ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: AUTO_IMPORT_PATH,
   handler: async (req, res) => {
@@ -528,7 +529,7 @@ ctx.effect(() => ctx.webServer.register({
   },
 }), 'dsh-key-rotation: auto-import route');
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: PRESET_LIMITS_PATH,
     handler: async (req, res) => {

package/lib/routes/metrics.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-metrics.js — Prometheus / OpenMetrics export route (#373).
 import { METRICS_PATH } from './paths.js';
 import { isTrustedBridgeRequest, isKeyPaused, isKeyRevoked } from '../pool.js';
@@ -10,7 +11,7 @@ import { hasModelQuotaConfig, isModelQuotaAvailable } from '../model-quota.js';
 export function registerMetricsRoutes(ctx, deps) {
   const { buildRuntime, poolState } = deps;
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: METRICS_PATH,
     handler: async (req, res) => {

package/lib/routes/quick-action.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 import { json, readJson, isTrustedBridgeRequest } from '../http-bridge.js';
 import { QUICK_ACTION_PATH } from './paths.js';
 import { keyTail, isKeyPaused } from '../pool.js';
@@ -9,7 +10,7 @@ import { keyTail, isKeyPaused } from '../pool.js';
 export function registerQuickActionRoutes(ctx, deps) {
   const { buildRuntime, pushEvent, circuitBreaker } = deps;
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: QUICK_ACTION_PATH,
     handler: async (req, res) => {

package/lib/routes/status.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 import { getModelQuotaStatus, isModelQuotaAvailable, hasModelQuotaConfig } from '../model-quota.js';
 import { providerOfBase, basePoolForBase, modelPoolsForRef } from '../pool-index.js';
 import { decryptSecret } from '../crypto-storage.js';
@@ -44,7 +45,7 @@ export function registerStatusRoutes(ctx, deps) {
 // (a typo is otherwise silent), and how often rotation has fired.
 //
 // Key VALUES never leave the host — only the boolean fact that one exists.
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: STATUS_PATH,
   handler: async (req, res) => {
@@ -204,7 +205,7 @@ ctx.effect(() => ctx.webServer.register({
 // #209: usage report - per-key requests/cost over the last N days.
 // ?format=csv returns text/csv; ?days=N window (1..90, default 7).
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: HEALTH_PATH,
   handler: async (req, res) => {

package/lib/routes/telemetry.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-telemetry.js — usage + snapshot operational routes (#312 split from routes-ops.js).
 import {
   json,
@@ -71,7 +72,7 @@ export function registerTelemetryRoutes(ctx, deps) {
     buildRuntime,
   } = deps;
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: USAGE_PATH,
   handler: (req, res) => {
@@ -116,7 +117,7 @@ ctx.effect(() => ctx.webServer.register({
 // Secret values never travel: only credential/env names. Token fields are
 // exported as empty strings; on import they keep existing values when empty.
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: SNAPSHOT_PATH,
   handler: async (req, res) => {
@@ -162,7 +163,7 @@ ctx.effect(() => ctx.webServer.register({
 }), 'dsh-key-rotation: snapshot route');
 
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: TRACE_PATH,
   handler: (req, res) => {
@@ -187,7 +188,7 @@ ctx.effect(() => ctx.webServer.register({
 }), 'dsh-key-rotation: trace route');
 
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: SIMULATE_PATH,
   handler: async (req, res) => {
@@ -243,7 +244,7 @@ ctx.effect(() => ctx.webServer.register({
   },
 }), 'dsh-key-rotation: simulate route');
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: DIAG_PATH,
   handler: async (req, res) => {

package/lib/routes/testing.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-test.js — sandbox test + sandbox cache routes (#312 split from routes-ops.js).
 import {
   json,
@@ -29,7 +30,7 @@ export function registerTestRoutes(ctx, deps) {
   } = deps;
 
 // ── test route: dry-run a single key without rotation ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: TEST_PATH,
   handler: async (req, res) => {
@@ -105,7 +106,7 @@ ctx.effect(() => ctx.webServer.register({
 // straight through.
 // Read-only cache snapshot for clients (badge polling).
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: SANDBOX_CACHE_PATH,
   handler: (req, res) => {
@@ -125,7 +126,7 @@ ctx.effect(() => ctx.webServer.register({
 // cannot be same-origin, so a shared secret is the gate).
 
 // ── test matrix route: batch probe all configured keys (#490) ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: TEST_MATRIX_PATH,
   handler: async (req, res) => {

package/lib/routes/webhook.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 import crypto from 'node:crypto';
 // lib/ops-webhook.js — webhook interactive action route (#312 split from routes-ops.js, #388 telegram secret-token & answerCallbackQuery).
 import {
@@ -36,7 +37,7 @@ export function registerWebhookActionRoute(ctx, deps) {
     circuitBreaker,
   } = deps;
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: WEBHOOK_ACTION_PATH,
   handler: async (req, res) => {

package/lib/stream-watchdog.js

@@ -0,0 +1,99 @@
+// lib/stream-watchdog.js — Inter-token stall & zombie stream detector (#569).
+// Monitors streaming chunk intervals and TTFT to prevent infinite agent hangs.
+
+export class StreamStallError extends Error {
+  constructor(message, elapsedMs, chunkCount) {
+    super(message || `Stream stalled: no tokens received for ${elapsedMs}ms`);
+    this.name = 'StreamStallError';
+    this.code = 'STREAM_STALLED';
+    this.elapsedMs = elapsedMs;
+    this.chunkCount = chunkCount;
+    this.isStall = true;
+  }
+}
+
+/**
+ * Wraps an async iterable stream with an inter-chunk stall watchdog.
+ *
+ * @param {AsyncIterable<any>} innerStream
+ * @param {object} [options]
+ * @param {number} [options.stallTimeoutMs=15000]
+ * @param {number} [options.stallInitialTimeoutMs=30000]
+ * @param {boolean} [options.stallDetectionEnabled=true]
+ * @param {AbortController} [options.abortController]
+ * @param {Function} [options.onStall]
+ * @returns {AsyncGenerator<any>}
+ */
+export async function* withStreamWatchdog(innerStream, options = {}) {
+  const {
+    stallTimeoutMs = 15000,
+    stallInitialTimeoutMs = 30000,
+    stallDetectionEnabled = true,
+    abortController = null,
+    onStall = null,
+  } = options;
+
+  if (!stallDetectionEnabled || (!stallTimeoutMs && !stallInitialTimeoutMs)) {
+    yield* innerStream;
+    return;
+  }
+
+  const iterator = innerStream[Symbol.asyncIterator]();
+  let chunksCount = 0;
+
+  try {
+    while (true) {
+      const currentTimeout = chunksCount === 0
+        ? (stallInitialTimeoutMs || stallTimeoutMs || 30000)
+        : (stallTimeoutMs || 15000);
+
+      let timerId = null;
+
+      const timerPromise = new Promise((_, reject) => {
+        timerId = setTimeout(() => {
+          const err = new StreamStallError(
+            `Stream stalled: no tokens received for ${currentTimeout}ms (chunks: ${chunksCount})`,
+            currentTimeout,
+            chunksCount
+          );
+          if (abortController && typeof abortController.abort === 'function') {
+            try { abortController.abort(err); } catch {}
+          }
+          if (typeof onStall === 'function') {
+            try { onStall(err); } catch {}
+          }
+          reject(err);
+        }, currentTimeout);
+      });
+
+      // Suppress unhandled rejection if iterator.next() finishes first
+      timerPromise.catch(() => {});
+
+      let result;
+      try {
+        result = await Promise.race([
+          iterator.next(),
+          timerPromise,
+        ]);
+      } finally {
+        if (timerId !== null) {
+          clearTimeout(timerId);
+          timerId = null;
+        }
+      }
+
+      if (result.done) {
+        break;
+      }
+
+      chunksCount++;
+      yield result.value;
+    }
+  } finally {
+    if (typeof iterator.return === 'function') {
+      try {
+        await iterator.return();
+      } catch {}
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.83",
+  "version": "0.8.85",
   "packageManager": "pnpm@10.33.2",
   "description": "Per-provider API key rotation for DeepSeek Harness: a key pool per provider, auto-created clone routes, and switching to the next key on quota/rate-limit errors. Includes a Settings section (Key Rotation) to edit the key pools, cooldown and switch codes.",
   "keywords": [
@@ -63,9 +63,9 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || >=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-alpha.1 <0.2.2-0",
-    "@deepseek-ai/schemastery": "^3.18.4"
+    "@deepseek-ai/cordis": "^4.0.1 || >=4.0.6-alpha.1 <5.0.0-0",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || >=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-alpha.1 <0.2.2-0 || >=0.2.2-alpha.1 <0.2.3-0",
+    "@deepseek-ai/schemastery": "^3.18.4 || >=3.18.6-alpha.1 <4.0.0-0"
   },
   "scripts": {
     "test": "node tools/test.mjs",