@goodandready/dsh-key-rotation 0.8.86 → 0.8.88

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.8.88 (2026-11-03)
+
+### Subagent Concurrency Partitions & Task Isolation (Block 15 Release)
+- **Subagent Partitions Module (Issue #575)**: Introduced `src/subagent-partitions.js` to detect child tasks and background subagents (`extractSubagentContext`) and partition pool capacity (`partitionPoolKeys`).
+- **Primary Chat Immunity**: Protects main user conversations from rate limit spikes and concurrency starvation caused by parallel background tasks by reserving dedicated subagent keys (`subagentReservedKeysCount`) or applying isolated partitioning (`subagentPartitionStrategy: 'isolated' | 'shared-burst'`).
+- **Per-Key Subagent Concurrency Caps**: Implemented `subagentMaxConcurrencyPerKey` (default: 2) to cap parallel subagent calls per key, preventing sudden RPM/TPM exhaustion.
+- **Config & Schemastery Support**: Added `subagentPartitionsEnabled`, `subagentReservedKeysCount`, `subagentPartitionStrategy`, and `subagentMaxConcurrencyPerKey` across Schemastery configuration, pool builders, and TypeScript types.
+
+## 0.8.87 (2026-11-03)
+
+### Cache-Affinity Router for Hot Prompt Cache (Block 14 Release)
+- **Cache-Affinity Module (Issue #573)**: Introduced `src/cache-affinity.js` with deterministic FNV-1a prompt prefix hashing (`extractPromptPrefixKey`) and LRU-managed `CacheAffinityRouter`.
+- **Hot Prompt Cache Affinity**: Binds stable system prompts and context prefixes to the provider key that has already warmed the upstream prompt cache, maintaining high hit-rates (>80%) across conversation sessions and multi-step tool calls.
+- **Synergistic Proactive Routing**: Cooperates with `applyPreemptiveYield` to ensure that hot-cache keys are prioritized only when they have safe token/request headroom, preventing cache optimization from triggering 429 rate limit failures.
+- **Config & Schemastery Support**: Added `cacheAffinityEnabled`, `cacheAffinityTtlMs` (default: 5 minutes), and `cacheAffinityPrefixChars` (default: 2048 chars) across Schemastery configuration, pool builders, and TypeScript types.
+
 ## 0.8.86 (2026-11-03)
 
 ### Pre-emptive Token & Request Yield before 429 (Block 13 Release)

package/lib/cache-affinity.js

@@ -0,0 +1,237 @@
+// src/cache-affinity.js — Cache-Affinity Router for hot prompt cache (#573).
+// Pure module: zero runtime dependencies, strictly < 600 lines.
+
+export const DEFAULT_CACHE_AFFINITY_TTL_MS = 300000; // 5 minutes
+export const DEFAULT_CACHE_AFFINITY_PREFIX_CHARS = 2048;
+export const MIN_CACHE_PREFIX_CHARS = 32;
+
+/**
+ * 32-bit FNV-1a hash algorithm for fast, deterministic string hashing.
+ * @param {string} str
+ * @returns {string} Hexadecimal hash representation
+ */
+export function fnv1a(str) {
+  if (typeof str !== 'string') return '0';
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16);
+}
+
+/**
+ * Extracts and hashes a deterministic prompt prefix key from request options.
+ * Inspects system prompt, conversation messages, prompt string, or contents.
+ * @param {object} options - Request options (messages, prompt, system, model)
+ * @param {number} [maxChars=2048]
+ * @returns {string|null} Cache prefix key or null if insufficient content
+ */
+export function extractPromptPrefixKey(options, maxChars = DEFAULT_CACHE_AFFINITY_PREFIX_CHARS) {
+  if (!options || typeof options !== 'object') return null;
+
+  let text = '';
+
+  // 1. Explicit system prompt option
+  if (typeof options.system === 'string' && options.system.trim()) {
+    text += options.system.trim() + '\n';
+  }
+
+  // 2. Messages array (OpenAI / Anthropic format)
+  if (Array.isArray(options.messages) && options.messages.length > 0) {
+    for (const msg of options.messages) {
+      if (!msg) continue;
+      const role = String(msg.role ?? '').toLowerCase();
+      let content = '';
+
+      if (typeof msg.content === 'string') {
+        content = msg.content;
+      } else if (Array.isArray(msg.content)) {
+        // Multipart content (e.g. [{ type: 'text', text: '...' }])
+        content = msg.content
+          .map(part => (typeof part === 'string' ? part : (part?.text ?? '')))
+          .filter(Boolean)
+          .join('\n');
+      }
+
+      if (content.trim()) {
+        text += `[${role}] ${content.trim()}\n`;
+      }
+
+      // Stop once we have reached or exceeded maxChars
+      if (text.length >= maxChars) break;
+    }
+  }
+
+  // 3. Raw prompt string
+  if (!text && typeof options.prompt === 'string' && options.prompt.trim()) {
+    text = options.prompt.trim();
+  }
+
+  // 4. Contents array (Gemini format)
+  if (!text && Array.isArray(options.contents) && options.contents.length > 0) {
+    for (const item of options.contents) {
+      const parts = item?.parts ?? [];
+      for (const p of parts) {
+        if (typeof p?.text === 'string' && p.text.trim()) {
+          text += p.text.trim() + '\n';
+          if (text.length >= maxChars) break;
+        }
+      }
+      if (text.length >= maxChars) break;
+    }
+  }
+
+  text = text.trim();
+  if (text.length < MIN_CACHE_PREFIX_CHARS) {
+    return null;
+  }
+
+  const slice = text.slice(0, maxChars);
+  const hash = fnv1a(slice);
+  const model = options.model ? String(options.model).trim() : '';
+
+  return model ? `${model}:${hash}` : hash;
+}
+
+/**
+ * CacheAffinityRouter tracks which key has warmed the upstream prompt cache.
+ */
+export class CacheAffinityRouter {
+  constructor(options = {}) {
+    this.ttlMs = options.ttlMs ?? DEFAULT_CACHE_AFFINITY_TTL_MS;
+    this.maxEntries = options.maxEntries ?? 1000;
+    this.entries = new Map();
+  }
+
+  resolveAffinity(cacheKey, candidateRefs, now = Date.now()) {
+    if (!cacheKey || !this.entries.has(cacheKey) || !Array.isArray(candidateRefs) || candidateRefs.length === 0) {
+      return null;
+    }
+
+    const entry = this.entries.get(cacheKey);
+    if (!entry) return null;
+
+    if (now >= entry.expiresAt) {
+      this.entries.delete(cacheKey);
+      return null;
+    }
+
+    if (!candidateRefs.includes(entry.ref)) {
+      return null;
+    }
+
+    entry.hits = (entry.hits || 0) + 1;
+    return {
+      ref: entry.ref,
+      hits: entry.hits,
+      warmedAt: entry.warmedAt,
+      expiresAt: entry.expiresAt,
+      ttlRemainingMs: Math.max(0, entry.expiresAt - now),
+    };
+  }
+
+  recordAffinity(cacheKey, ref, options = {}) {
+    if (!cacheKey || !ref) return;
+    const now = options.now ?? Date.now();
+    const ttlMs = options.ttlMs ?? this.ttlMs;
+
+    if (this.entries.size >= this.maxEntries && !this.entries.has(cacheKey)) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey) this.entries.delete(oldestKey);
+    }
+
+    const existing = this.entries.get(cacheKey);
+    const hits = existing ? (existing.hits || 0) : 0;
+
+    this.entries.set(cacheKey, {
+      ref,
+      warmedAt: existing?.warmedAt ?? now,
+      lastSeenAt: now,
+      expiresAt: now + ttlMs,
+      hits,
+      model: options.model,
+    });
+  }
+
+  deleteAffinity(cacheKey) {
+    if (cacheKey) this.entries.delete(cacheKey);
+  }
+
+  clear() {
+    this.entries.clear();
+  }
+
+  get size() {
+    return this.entries.size;
+  }
+}
+
+/**
+ * Obtains or lazily creates a CacheAffinityRouter on a pool state.
+ * @param {object} pool
+ * @returns {CacheAffinityRouter}
+ */
+export function getOrCreateCacheAffinityRouter(pool) {
+  if (!pool) return new CacheAffinityRouter();
+  if (!pool.state) pool.state = {};
+  if (!pool.state.cacheAffinityRouter || !(pool.state.cacheAffinityRouter instanceof CacheAffinityRouter)) {
+    pool.state.cacheAffinityRouter = new CacheAffinityRouter({
+      ttlMs: pool.cacheAffinityTtlMs ?? DEFAULT_CACHE_AFFINITY_TTL_MS,
+    });
+  }
+  return pool.state.cacheAffinityRouter;
+}
+
+/**
+ * Applies prompt cache affinity ordering to candidate attempt list.
+ * @param {string[]} attemptList
+ * @param {object} pool
+ * @param {object} [options]
+ * @returns {string[]}
+ */
+export function applyCacheAffinity(attemptList, pool, options = {}) {
+  if (!Array.isArray(attemptList) || attemptList.length <= 1 || !pool) {
+    return (attemptList ?? []).slice();
+  }
+
+  const enabled = options.enabled ?? pool.cacheAffinityEnabled ?? true;
+  if (!enabled) return attemptList.slice();
+
+  const cacheKey = options.cacheKey;
+  if (!cacheKey) return attemptList.slice();
+
+  // If a pinned key is configured and already first, keep pinned priority
+  if (pool.pinnedRef && attemptList[0] === pool.pinnedRef && options.preservePinned !== false) {
+    return attemptList.slice();
+  }
+
+  const router = getOrCreateCacheAffinityRouter(pool);
+  const now = options.now ?? Date.now();
+  const affinity = router.resolveAffinity(cacheKey, attemptList, now);
+
+  if (!affinity || !affinity.ref) {
+    return attemptList.slice();
+  }
+
+  const targetRef = affinity.ref;
+  const list = attemptList.slice();
+  const idx = list.indexOf(targetRef);
+
+  if (idx > 0) {
+    list.splice(idx, 1);
+    list.unshift(targetRef);
+
+    if (options.trace && typeof options.trace.addStep === 'function') {
+      options.trace.addStep(targetRef, 'PRIORITIZED', 'CACHE_AFFINITY', `Prompt cache hit affinity (key ${targetRef}, hits: ${affinity.hits})`);
+    }
+    if (options.pushEvent && typeof options.pushEvent === 'function') {
+      options.pushEvent(pool, targetRef, 'CACHE_AFFINITY_HIT', { cacheKey, hits: affinity.hits });
+    }
+    if (pool.state) {
+      pool.state.cacheAffinityHits = (pool.state.cacheAffinityHits ?? 0) + 1;
+    }
+  }
+
+  return list;
+}

package/lib/index.js

@@ -143,6 +143,13 @@ const SettingsSchema = Schema.object({
   preemptiveRotationEnabled: Schema.boolean().default(true),
   preemptiveSafetyMarginTokens: Schema.number().default(4000),
   preemptiveSafetyMarginRequests: Schema.number().default(2),
+  cacheAffinityEnabled: Schema.boolean().default(true),
+  cacheAffinityTtlMs: Schema.number().default(300000),
+  cacheAffinityPrefixChars: Schema.number().default(2048),
+  subagentPartitionsEnabled: Schema.boolean().default(true),
+  subagentReservedKeysCount: Schema.number().default(0),
+  subagentPartitionStrategy: Schema.union(['shared-burst', 'isolated']).default('shared-burst'),
+  subagentMaxConcurrencyPerKey: Schema.number().default(2),
   providers: Schema.array(Schema.object({
     provider: Schema.string().required(),
     keys: Schema.array(Schema.string()).default([]),
@@ -178,6 +185,13 @@ const SettingsSchema = Schema.object({
     preemptiveRotationEnabled: Schema.boolean(),
     preemptiveSafetyMarginTokens: Schema.number(),
     preemptiveSafetyMarginRequests: Schema.number(),
+    cacheAffinityEnabled: Schema.boolean(),
+    cacheAffinityTtlMs: Schema.number(),
+    cacheAffinityPrefixChars: Schema.number(),
+    subagentPartitionsEnabled: Schema.boolean(),
+    subagentReservedKeysCount: Schema.number(),
+    subagentPartitionStrategy: Schema.union(['shared-burst', 'isolated']),
+    subagentMaxConcurrencyPerKey: Schema.number(),
   })).default([...DEFAULT_PROVIDERS]),
 });
 

package/lib/pool-builder.js

@@ -47,6 +47,13 @@ export function buildPoolItem({
   preemptiveRotationEnabled = true,
   preemptiveSafetyMarginTokens = 4000,
   preemptiveSafetyMarginRequests = 2,
+  cacheAffinityEnabled = true,
+  cacheAffinityTtlMs = 300000,
+  cacheAffinityPrefixChars = 2048,
+  subagentPartitionsEnabled = true,
+  subagentReservedKeysCount = 0,
+  subagentPartitionStrategy = 'shared-burst',
+  subagentMaxConcurrencyPerKey = 2,
 }) {
   const seen = new Set();
   const indexed = (Array.isArray(keys) ? keys : []).map((key, index) => ({ ref: typeof key === 'string' ? key.trim() : '', index }))
@@ -163,6 +170,13 @@ const weightsMap = {};
     preemptiveRotationEnabled: preemptiveRotationEnabled ?? true,
     preemptiveSafetyMarginTokens: typeof preemptiveSafetyMarginTokens === 'number' && Number.isFinite(preemptiveSafetyMarginTokens) && preemptiveSafetyMarginTokens >= 0 ? Math.floor(preemptiveSafetyMarginTokens) : 4000,
     preemptiveSafetyMarginRequests: typeof preemptiveSafetyMarginRequests === 'number' && Number.isFinite(preemptiveSafetyMarginRequests) && preemptiveSafetyMarginRequests >= 0 ? Math.floor(preemptiveSafetyMarginRequests) : 2,
+    cacheAffinityEnabled: cacheAffinityEnabled ?? true,
+    cacheAffinityTtlMs: typeof cacheAffinityTtlMs === 'number' && Number.isFinite(cacheAffinityTtlMs) && cacheAffinityTtlMs > 0 ? Math.floor(cacheAffinityTtlMs) : 300000,
+    cacheAffinityPrefixChars: typeof cacheAffinityPrefixChars === 'number' && Number.isFinite(cacheAffinityPrefixChars) && cacheAffinityPrefixChars > 0 ? Math.floor(cacheAffinityPrefixChars) : 2048,
+    subagentPartitionsEnabled: subagentPartitionsEnabled ?? true,
+    subagentReservedKeysCount: typeof subagentReservedKeysCount === 'number' && Number.isFinite(subagentReservedKeysCount) && subagentReservedKeysCount >= 0 ? Math.floor(subagentReservedKeysCount) : 0,
+    subagentPartitionStrategy: subagentPartitionStrategy === 'isolated' ? 'isolated' : 'shared-burst',
+    subagentMaxConcurrencyPerKey: typeof subagentMaxConcurrencyPerKey === 'number' && Number.isFinite(subagentMaxConcurrencyPerKey) && subagentMaxConcurrencyPerKey > 0 ? Math.floor(subagentMaxConcurrencyPerKey) : 2,
     preemptiveRotationEnabled: preemptiveRotationEnabled ?? true,
     preemptiveSafetyMarginTokens: typeof preemptiveSafetyMarginTokens === 'number' && Number.isFinite(preemptiveSafetyMarginTokens) && preemptiveSafetyMarginTokens >= 0 ? Math.floor(preemptiveSafetyMarginTokens) : 4000,
     preemptiveSafetyMarginRequests: typeof preemptiveSafetyMarginRequests === 'number' && Number.isFinite(preemptiveSafetyMarginRequests) && preemptiveSafetyMarginRequests >= 0 ? Math.floor(preemptiveSafetyMarginRequests) : 2,
@@ -219,6 +233,13 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
       preemptiveRotationEnabled: p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
       preemptiveSafetyMarginTokens: p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
       preemptiveSafetyMarginRequests: p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,
+      cacheAffinityEnabled: p.cacheAffinityEnabled ?? cfg.cacheAffinityEnabled ?? true,
+      cacheAffinityTtlMs: p.cacheAffinityTtlMs ?? cfg.cacheAffinityTtlMs ?? 300000,
+      cacheAffinityPrefixChars: p.cacheAffinityPrefixChars ?? cfg.cacheAffinityPrefixChars ?? 2048,
+      subagentPartitionsEnabled: p.subagentPartitionsEnabled ?? cfg.subagentPartitionsEnabled ?? true,
+      subagentReservedKeysCount: p.subagentReservedKeysCount ?? cfg.subagentReservedKeysCount ?? 0,
+      subagentPartitionStrategy: p.subagentPartitionStrategy ?? cfg.subagentPartitionStrategy ?? 'shared-burst',
+      subagentMaxConcurrencyPerKey: p.subagentMaxConcurrencyPerKey ?? cfg.subagentMaxConcurrencyPerKey ?? 2,
       preemptiveRotationEnabled: p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
       preemptiveSafetyMarginTokens: p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
       preemptiveSafetyMarginRequests: p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,
@@ -260,6 +281,13 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
         preemptiveRotationEnabled: mp.preemptiveRotationEnabled ?? p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
         preemptiveSafetyMarginTokens: mp.preemptiveSafetyMarginTokens ?? p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
         preemptiveSafetyMarginRequests: mp.preemptiveSafetyMarginRequests ?? p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,
+        cacheAffinityEnabled: mp.cacheAffinityEnabled ?? p.cacheAffinityEnabled ?? cfg.cacheAffinityEnabled ?? true,
+        cacheAffinityTtlMs: mp.cacheAffinityTtlMs ?? p.cacheAffinityTtlMs ?? cfg.cacheAffinityTtlMs ?? 300000,
+        cacheAffinityPrefixChars: mp.cacheAffinityPrefixChars ?? p.cacheAffinityPrefixChars ?? cfg.cacheAffinityPrefixChars ?? 2048,
+        subagentPartitionsEnabled: mp.subagentPartitionsEnabled ?? p.subagentPartitionsEnabled ?? cfg.subagentPartitionsEnabled ?? true,
+        subagentReservedKeysCount: mp.subagentReservedKeysCount ?? p.subagentReservedKeysCount ?? cfg.subagentReservedKeysCount ?? 0,
+        subagentPartitionStrategy: mp.subagentPartitionStrategy ?? p.subagentPartitionStrategy ?? cfg.subagentPartitionStrategy ?? 'shared-burst',
+        subagentMaxConcurrencyPerKey: mp.subagentMaxConcurrencyPerKey ?? p.subagentMaxConcurrencyPerKey ?? cfg.subagentMaxConcurrencyPerKey ?? 2,
         preemptiveRotationEnabled: mp.preemptiveRotationEnabled ?? p.preemptiveRotationEnabled ?? cfg.preemptiveRotationEnabled ?? true,
         preemptiveSafetyMarginTokens: mp.preemptiveSafetyMarginTokens ?? p.preemptiveSafetyMarginTokens ?? cfg.preemptiveSafetyMarginTokens ?? 4000,
         preemptiveSafetyMarginRequests: mp.preemptiveSafetyMarginRequests ?? p.preemptiveSafetyMarginRequests ?? cfg.preemptiveSafetyMarginRequests ?? 2,

package/lib/resolver.js

@@ -12,6 +12,8 @@ import { bucketAllow, bucketRetryMs, tpmAllow, tpmRetryMs } from './bucket.js';
 import { envValue, sortAttemptList, isKeyPaused, isKeyRevoked, isKeyBroken, costForDay, costForWeek, budgetVerdict, getSessionSticky, setSessionSticky } from './pool.js';
 import { decryptSecret } from './crypto-storage.js';
 import { applyPreemptiveYield } from './preemptive-yield.js';
+import { extractPromptPrefixKey, applyCacheAffinity } from './cache-affinity.js';
+import { partitionPoolKeys } from './subagent-partitions.js';
 import { resolveRefPool, isQuotaManagedRequest, providerOfBase, basePoolForBase } from './pool-index.js';
 import {
   isModelQuotaAvailable,
@@ -133,6 +135,13 @@ export function createResolver({
         lastUsed: pool.state.lastUsed,
       });
     }
+    // Issue #573: Cache-Affinity Router
+    const cacheKey = extractPromptPrefixKey(resolveOpts, pool.cacheAffinityPrefixChars);
+    if (cacheKey) {
+      list = applyCacheAffinity(list, pool, { cacheKey, now: Date.now() });
+    }
+    // Issue #575: Subagent Concurrency Partitions
+    list = partitionPoolKeys(list, pool, { reqOptions: resolveOpts, concurrencyTracker, now: Date.now() });
     // Issue #571: Pre-emptive Token & Request Yield before 429
     list = applyPreemptiveYield(list, pool, { now: Date.now() });
     // Fail closed: when this request is managed by a model pool that has local

package/lib/rotate.js

@@ -28,6 +28,8 @@ import { LOCAL_POOL_EXHAUSTED_CODE, resolveKeyDirectly } from './resolver.js';
 import { recordStreamSuccessMetrics, preserveDispatchContext } from './stream-metrics.js';
 import { withStreamWatchdog, StreamStallError } from './stream-watchdog.js';
 import { applyPreemptiveYield } from './preemptive-yield.js';
+import { extractPromptPrefixKey, applyCacheAffinity } from './cache-affinity.js';
+import { partitionPoolKeys } from './subagent-partitions.js';
 import { penalizeKey } from './rotate-penalty.js';
 import { recordPromptCache } from './prompt-cache.js';
 import { recordRequestOutcome, recordFailureCategory } from './ops-analytics.js';
@@ -109,7 +111,8 @@ export function createRotate(deps) {
       const breaker = runtime0.circuitBreakerEnabled === false ? null : circuitBreaker;
       let activePermit = null;
       const sessionId = options?.sessionId ?? options?.session ?? options?.metadata?.sessionId ?? options?.chatId ?? options?.conversationId;
-      const reqStore = { pool, pickedRef: undefined, concurrencyRef: undefined, startMs: now(), sessionId, model: options.model };
+      const cacheKey = extractPromptPrefixKey(options, pool.cacheAffinityPrefixChars);
+      const reqStore = { pool, pickedRef: undefined, concurrencyRef: undefined, startMs: now(), sessionId, model: options.model, cacheKey };
       setRotateStartMs(reqStore.startMs);
       const wallNow = Date.now();
       const quotaManaged = hasModelQuotaConfig(pool);
@@ -204,6 +207,13 @@ export function createRotate(deps) {
         }
       }
 
+      // Issue #573: Cache-Affinity Router
+      if (reqStore.cacheKey) {
+        attemptList = applyCacheAffinity(attemptList, pool, { cacheKey: reqStore.cacheKey, now: wallNow, trace, pushEvent });
+      }
+      // Issue #575: Subagent Concurrency Partitions
+      attemptList = partitionPoolKeys(attemptList, pool, { reqOptions: options, concurrencyTracker, now: wallNow, trace });
+
       // Issue #571: Pre-emptive Token & Request Yield before 429
       attemptList = applyPreemptiveYield(attemptList, pool, {
         now: wallNow,
@@ -448,6 +458,7 @@ export function createRotate(deps) {
                       rawHdrs,
                       pushEvent,
                       quotaStore,
+                      cacheKey: reqStore?.cacheKey,
                     });
                   }
                   recordLatency(pool, reqStore);

package/lib/stream-metrics.js

@@ -3,6 +3,7 @@
 
 import { recordSuccess, setSessionSticky, recordFailure, extractRateLimit, isRateLimited } from './pool.js';
 import { recordPromptCache } from './prompt-cache.js';
+import { getOrCreateCacheAffinityRouter } from './cache-affinity.js';
 import { recordRequestOutcome } from './ops-analytics.js';
 import { tpmRecord } from './bucket.js';
 import { extractUsageTokens, consumeModelTokens } from './model-quota.js';
@@ -49,6 +50,7 @@ export function recordStreamSuccessMetrics(pool, activeRef, options, chunk, deps
     rawHdrs,
     pushEvent,
     quotaStore,
+    cacheKey,
   } = deps;
 
   const nowMs = typeof now === 'function' ? now() : Date.now();
@@ -61,6 +63,10 @@ export function recordStreamSuccessMetrics(pool, activeRef, options, chunk, deps
   // 2. Prompt cache and analytics outcome
   const usagePayload = chunk?.usage ?? chunk?.metadata?.usage;
   recordPromptCache(pool, activeRef, options.model, usagePayload, wallNow);
+  if (cacheKey) {
+    const affinityRouter = getOrCreateCacheAffinityRouter(pool);
+    affinityRouter.recordAffinity(cacheKey, activeRef, { now: wallNow, model: options.model });
+  }
   recordRequestOutcome(pool, {
     ref: activeRef,
     success: true,

package/lib/subagent-partitions.js

@@ -0,0 +1,163 @@
+// src/subagent-partitions.js — Subagent Concurrency Partitions & Isolation (#575).
+// Pure module: zero runtime dependencies, strictly < 600 lines.
+
+export const DEFAULT_SUBAGENT_MAX_CONCURRENCY_PER_KEY = 2;
+
+/**
+ * Extracts subagent or background task context from request options and metadata.
+ * @param {object} options
+ * @returns {{ isSubagent: boolean, subagentId?: string, parentSessionId?: string }}
+ */
+export function extractSubagentContext(options) {
+  if (!options || typeof options !== 'object') return { isSubagent: false };
+  const meta = options.metadata || options.meta || {};
+  const parentSessionId = typeof meta.parentSessionId === 'string' && meta.parentSessionId.trim() ? meta.parentSessionId.trim() : undefined;
+
+  let isSubagent = false;
+  let subagentId = undefined;
+
+  if (options.isSubagent === true || meta.isSubagent === true) {
+    isSubagent = true;
+    subagentId = options.subagentId || meta.subagentId;
+  } else if (typeof options.subagentId === 'string' && options.subagentId.trim()) {
+    isSubagent = true;
+    subagentId = options.subagentId.trim();
+  } else if (typeof meta.subagentId === 'string' && meta.subagentId.trim()) {
+    isSubagent = true;
+    subagentId = meta.subagentId.trim();
+  } else if (typeof options.subagent === 'string' && options.subagent.trim()) {
+    isSubagent = true;
+    subagentId = options.subagent.trim();
+  } else if (options.subagent === true) {
+    isSubagent = true;
+  } else if (parentSessionId) {
+    isSubagent = true;
+    subagentId = meta.childSessionId;
+  } else {
+    // Check sessionId prefixes
+    const sid = String(options.sessionId || options.session || options.chatId || options.conversationId || '').trim();
+    if (
+      sid.startsWith('subagent:') ||
+      sid.startsWith('subagent-') ||
+      sid.startsWith('subtask:') ||
+      sid.startsWith('subtask-') ||
+      sid.startsWith('agent:sub:')
+    ) {
+      isSubagent = true;
+      subagentId = sid;
+    } else {
+      // Check tags
+      const tags = Array.isArray(options.tags) ? options.tags : (Array.isArray(meta.tags) ? meta.tags : []);
+      if (tags.some(t => typeof t === 'string' && (t === 'subagent' || t === 'subtask' || t === 'background'))) {
+        isSubagent = true;
+        subagentId = options.subagentId || meta.subagentId;
+      }
+    }
+  }
+
+  if (isSubagent) {
+    const res = { isSubagent: true };
+    if (subagentId) res.subagentId = subagentId;
+    if (parentSessionId) res.parentSessionId = parentSessionId;
+    return res;
+  }
+
+  return { isSubagent: false };
+}
+
+/**
+ * Partitions or reorders candidate keys according to subagent isolation rules.
+ * @param {string[]} attemptList
+ * @param {object} pool
+ * @param {object} [options]
+ * @returns {string[]}
+ */
+export function partitionPoolKeys(attemptList, pool, options = {}) {
+  if (!Array.isArray(attemptList) || attemptList.length <= 1 || !pool) {
+    return (attemptList ?? []).slice();
+  }
+
+  const enabled = options.enabled ?? pool.subagentPartitionsEnabled ?? true;
+  if (!enabled) return attemptList.slice();
+
+  const subCtx = options.subagentContext ?? extractSubagentContext(options.reqOptions);
+  const isSubagent = Boolean(subCtx.isSubagent);
+  const reservedCount = pool.subagentReservedKeysCount ?? 0;
+  const strategy = pool.subagentPartitionStrategy ?? 'shared-burst';
+  const labels = pool.labels || {};
+
+  const explicitSubagentRefs = new Set();
+  const explicitPrimaryRefs = new Set();
+
+  for (const [ref, label] of Object.entries(labels)) {
+    const lbl = String(label).toLowerCase();
+    if (lbl === 'subagent' || lbl === 'subtask' || lbl === 'worker') explicitSubagentRefs.add(ref);
+    if (lbl === 'primary' || lbl === 'main' || lbl === 'user') explicitPrimaryRefs.add(ref);
+  }
+
+  // If reservedCount > 0, reserve the last reservedCount keys of pool.refs if not already labelled primary
+  if (reservedCount > 0 && pool.refs && pool.refs.length > reservedCount) {
+    const reservedSlice = pool.refs.slice(pool.refs.length - reservedCount);
+    for (const r of reservedSlice) {
+      if (!explicitPrimaryRefs.has(r)) explicitSubagentRefs.add(r);
+    }
+  }
+
+  const hasPartitioning = explicitSubagentRefs.size > 0;
+  let list = attemptList.slice();
+
+  if (isSubagent) {
+    // SUBAGENT REQUEST
+    if (hasPartitioning) {
+      const dedicated = list.filter(r => explicitSubagentRefs.has(r));
+      const shared = list.filter(r => !explicitSubagentRefs.has(r));
+
+      if (strategy === 'isolated') {
+        if (dedicated.length > 0) list = dedicated;
+      } else {
+        list = dedicated.concat(shared);
+      }
+    }
+  } else {
+    // PRIMARY / USER REQUEST
+    if (hasPartitioning) {
+      const primary = list.filter(r => !explicitSubagentRefs.has(r));
+      const subOnly = list.filter(r => explicitSubagentRefs.has(r));
+
+      if (primary.length > 0) {
+        list = strategy === 'isolated' ? primary : primary.concat(subOnly);
+      }
+    }
+  }
+
+  // Apply subagent per-key concurrency cap
+  const tracker = options.concurrencyTracker;
+  const maxSubConcurrency = pool.subagentMaxConcurrencyPerKey ?? DEFAULT_SUBAGENT_MAX_CONCURRENCY_PER_KEY;
+  if (isSubagent && tracker && typeof tracker.getActive === 'function' && maxSubConcurrency > 0) {
+    const now = options.now ?? Date.now();
+    const withinCap = [];
+    const saturated = [];
+    for (const r of list) {
+      const active = tracker.getActive(r, now) ?? 0;
+      if (active >= maxSubConcurrency) {
+        saturated.push(r);
+      } else {
+        withinCap.push(r);
+      }
+    }
+    if (withinCap.length > 0 && saturated.length > 0) {
+      list = withinCap.concat(saturated);
+    }
+  }
+
+  if (options.trace && typeof options.trace.addStep === 'function' && list[0] !== attemptList[0]) {
+    options.trace.addStep(
+      list[0],
+      'PRIORITIZED',
+      'SUBAGENT_PARTITION',
+      isSubagent ? 'Subagent partition key allocated' : 'Primary chat partition prioritized'
+    );
+  }
+
+  return list;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.86",
+  "version": "0.8.88",
   "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": [