@gethelio/proxy 0.12.0 → 0.13.0

package/dist/index.js

@@ -35,6 +35,11 @@ var RESERVED_TRANSPORT_HEADERS = /* @__PURE__ */ new Set([
   "content-type",
   "content-length",
   "host",
+  // The Accept is Helio-owned per HTTP upstream leg: where Helio
+  // advertises at all it advertises its own response parsing (the SSE
+  // message POSTs assert none), so an operator value could only
+  // misadvertise it, never extend it (issue #304).
+  "accept",
   // Modern (2026-07-28) transport headers Helio owns on the wire for every
   // Streamable HTTP POST it sends upstream — relayed client traffic and
   // proxy-initiated requests (era probe, revalidation) alike — see
@@ -44,8 +49,8 @@ var RESERVED_TRANSPORT_HEADERS = /* @__PURE__ */ new Set([
 ]);
 var transportSchema = z.enum(["streamable-http", "sse", "stdio"]);
 var protocolVersionSchema = z.enum(["auto", "2025-06-18", "2026-07-28"]);
-var upstreamSchema = z.object({
-  url: z.string(),
+var upstreamObjectSchema = z.object({
+  url: z.string().optional(),
   transport: transportSchema.default("streamable-http"),
   protocol_version: protocolVersionSchema.default("auto"),
   command: z.string().optional(),
@@ -54,10 +59,22 @@ var upstreamSchema = z.object({
   request_timeout: durationSchema.default("30s"),
   forward_headers: z.array(z.string().min(1)).default([]),
   headers: z.record(z.string(), z.string()).default({})
-}).strict().refine((data) => data.transport !== "stdio" || data.command !== void 0, {
-  message: '"command" is required when transport is "stdio"',
-  path: ["command"]
-}).superRefine((data, ctx) => {
+}).strict();
+function upstreamEntryChecks(data, ctx) {
+  if (data.transport === "stdio" && data.command === void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["command"],
+      message: '"command" is required when transport is "stdio"'
+    });
+  }
+  if (data.transport !== "stdio" && data.url === void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["url"],
+      message: `"url" is required when transport is "${data.transport}"`
+    });
+  }
   if (data.protocol_version === "2026-07-28" && data.transport !== "streamable-http") {
     ctx.addIssue({
       code: "custom",
@@ -83,6 +100,26 @@ var upstreamSchema = z.object({
       });
     }
   }
+}
+var upstreamSchema = upstreamObjectSchema.superRefine(upstreamEntryChecks);
+var upstreamNameSchema = z.string().min(1).max(64).regex(/^[a-zA-Z0-9_-]+$/, {
+  message: 'Upstream names may only contain letters, digits, "_" and "-"'
+});
+var namedUpstreamEntrySchema = z.object({ name: upstreamNameSchema, ...upstreamObjectSchema.shape }).strict().superRefine(upstreamEntryChecks);
+var upstreamsListSchema = z.array(namedUpstreamEntrySchema).min(1, {
+  message: 'upstreams: must declare at least one upstream \u2014 an empty list would serve nothing. For a single upstream you can keep the "upstream:" form.'
+}).superRefine((entries, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, entry] of entries.entries()) {
+    if (seen.has(entry.name)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "name"],
+        message: `Duplicate upstream name "${entry.name}". Upstream names embed in mount paths, limiter keys, and audit records \u2014 each upstream needs its own.`
+      });
+    }
+    seen.add(entry.name);
+  }
 });
 var listenSchema = z.object({
   port: z.number().int().min(1).max(65535).default(3e3),
@@ -241,7 +278,11 @@ var matchSchema = z.object({
   annotations: annotationsMatchSchema.optional(),
   input: z.record(z.string(), inputConditionSchema).optional(),
   environment: z.string().optional(),
-  metadata: z.record(z.string(), metadataConditionSchema).optional()
+  metadata: z.record(z.string(), metadataConditionSchema).optional(),
+  /** Configured upstream names the rule is scoped to (issue #293). */
+  upstreams: z.array(z.string().min(1)).min(1, {
+    message: "match.upstreams must name at least one upstream \u2014 an empty list matches nothing."
+  }).optional()
 }).strict();
 var policyActionSchema = z.enum([
   "allow",
@@ -364,7 +405,11 @@ var budgetContributorMatchSchema = z.object({
   // Same operators and AND-combination as rule `match.input`. Other rule
   // matchers (annotations, environment, metadata) stay strict-rejected
   // until the budget charge context can actually evaluate them.
-  input: z.record(z.string(), inputConditionSchema).optional()
+  input: z.record(z.string(), inputConditionSchema).optional(),
+  /** Configured upstream names the contributor is scoped to (issue #293). */
+  upstreams: z.array(z.string().min(1)).min(1, {
+    message: "match.upstreams must name at least one upstream \u2014 an empty list matches nothing."
+  }).optional()
 }).strict();
 var modernBudgetContributorSchema = z.object({
   match: budgetContributorMatchSchema,
@@ -476,9 +521,7 @@ var sdkSchema = z.object({
    */
   evaluation_ttl: durationSchema.default("10m")
 }).strict();
-var helioConfigBaseSchema = z.object({
-  version: z.literal("1"),
-  upstream: upstreamSchema,
+var rootSectionSchemas = {
   listen: listenSchema.prefault({}),
   environment: z.string().optional(),
   // Session precedes policies deliberately: upstream/listen/environment say
@@ -495,6 +538,16 @@ var helioConfigBaseSchema = z.object({
   // the request path (canonical section order, #89/#163).
   dashboard: dashboardSchema.prefault({}),
   sdk: sdkSchema.prefault({})
+};
+var singularConfigBase = z.object({
+  version: z.literal("1"),
+  upstream: upstreamSchema,
+  ...rootSectionSchemas
+}).strict();
+var namedConfigBase = z.object({
+  version: z.literal("1"),
+  upstreams: upstreamsListSchema,
+  ...rootSectionSchemas
 }).strict();
 function stripRootExtensionKeys(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
@@ -502,7 +555,7 @@ function stripRootExtensionKeys(value) {
     Object.entries(value).filter(([key]) => !key.startsWith("x-"))
   );
 }
-var helioConfigRefinedSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
+function rootConfigChecks(cfg, ctx) {
   const hasConfiguredEnvironment = typeof cfg.environment === "string" && cfg.environment.trim().length > 0;
   const requiresSecret = cfg.policies.flag_destructive === "require_approval" || cfg.policies.on_tool_drift === "require_approval" || cfg.policies.rules.some((rule) => rule.action === "require_approval") || cfg.budgets.some((budget) => budget.on_exceed === "require_approval");
   const hasSecret = hasDashboardApiSecret(cfg.dashboard.api_secret);
@@ -722,8 +775,166 @@ var helioConfigRefinedSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
       }
     }
   }
+}
+function upstreamVocabularyChecks(cfg, ctx, configuredNames) {
+  for (const [ruleIndex, rule] of cfg.policies.rules.entries()) {
+    const upstreams = rule.match.upstreams;
+    if (upstreams === void 0) continue;
+    if (configuredNames === null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["policies", "rules", ruleIndex, "match", "upstreams"],
+        message: 'Rule sets match.upstreams but the config declares a single "upstream:", which has no name on purpose. Upstream-scoped rules require the named "upstreams:" list.'
+      });
+    } else {
+      for (const [entryIndex, name] of upstreams.entries()) {
+        if (!configuredNames.has(name)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["policies", "rules", ruleIndex, "match", "upstreams", entryIndex],
+            message: `Rule names upstream "${name}" in match.upstreams but no configured upstream has that name. Every entry must name an upstream from the upstreams: list.`
+          });
+        }
+      }
+    }
+    if (rule.match.metadata !== void 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["policies", "rules", ruleIndex, "match", "upstreams"],
+        message: "match.upstreams cannot be combined with match.metadata \u2014 metadata rules only match on the sideband (host) path and upstream-scoped rules only on the MCP path, so the combination can never match. Split it into two rules."
+      });
+    }
+    if (rule.limits?.key === "sender_id") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["policies", "rules", ruleIndex, "limits", "key"],
+        message: 'limits.key "sender_id" cannot be combined with match.upstreams \u2014 an upstream-scoped rule only matches on the MCP path, where sender_id is absent and the key would silently collapse to tool scope.'
+      });
+    }
+    if (rule.limits?.max_spend?.key === "sender_id") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["policies", "rules", ruleIndex, "limits", "max_spend", "key"],
+        message: 'limits.max_spend.key "sender_id" cannot be combined with match.upstreams \u2014 an upstream-scoped rule only matches on the MCP path, where sender_id is absent and the key would silently collapse to tool scope.'
+      });
+    }
+  }
+  for (const [budgetIndex, budget] of cfg.budgets.entries()) {
+    let hasUnscopedContributor = false;
+    for (const [contributorIndex, contributor] of budget.contributors.entries()) {
+      const upstreams = contributor.match?.upstreams;
+      if (upstreams === void 0) {
+        hasUnscopedContributor = true;
+        continue;
+      }
+      if (configuredNames === null) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["budgets", budgetIndex, "contributors", contributorIndex, "match", "upstreams"],
+          message: 'Contributor sets match.upstreams but the config declares a single "upstream:", which has no name on purpose. Upstream-scoped contributors require the named "upstreams:" list.'
+        });
+      } else {
+        for (const [entryIndex, name] of upstreams.entries()) {
+          if (!configuredNames.has(name)) {
+            ctx.addIssue({
+              code: "custom",
+              path: [
+                "budgets",
+                budgetIndex,
+                "contributors",
+                contributorIndex,
+                "match",
+                "upstreams",
+                entryIndex
+              ],
+              message: `Contributor names upstream "${name}" in match.upstreams but no configured upstream has that name. Every entry must name an upstream from the upstreams: list.`
+            });
+          }
+        }
+      }
+    }
+    if (budget.key === "sender_id" && !hasUnscopedContributor) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["budgets", budgetIndex, "key"],
+        message: 'budget key "sender_id" requires at least one contributor without an "upstreams" scope \u2014 upstream-scoped contributors only match MCP calls, which never carry a sender, so every charge would land in the shared "unknown" pot while sideband calls (the only ones with real senders) never feed this budget.'
+      });
+    }
+  }
+  if (configuredNames !== null) {
+    const hasEvidenceGatedRule = cfg.policies.rules.some(
+      (rule) => (rule.evidence?.requires.length ?? 0) > 0 || (rule.requires?.length ?? 0) > 0
+    );
+    if (hasEvidenceGatedRule) {
+      const legacyIndex = cfg.session.identity.findIndex(
+        (source) => source.source === "legacy_header"
+      );
+      if (legacyIndex !== -1) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["session", "identity", legacyIndex],
+          message: `session.identity includes "legacy_header" while named upstreams and evidence-gated rules ("evidence"/"requires") are configured. On the legacy relay flow the Mcp-Session-Id a client echoes was minted by the upstream itself, so with multiple upstreams a hostile server could collide session identities across doors and pollute another door's evidence gates. Remove legacy_header from session.identity and use a caller-owned source such as the default "x-helio-session-id" header.`
+        });
+      }
+    }
+  }
+}
+var singularConfigSchema = singularConfigBase.superRefine((cfg, ctx) => {
+  rootConfigChecks(cfg, ctx);
+  upstreamVocabularyChecks(cfg, ctx, null);
+});
+var namedConfigSchema = namedConfigBase.superRefine((cfg, ctx) => {
+  rootConfigChecks(cfg, ctx);
+  upstreamVocabularyChecks(cfg, ctx, new Set(cfg.upstreams.map((entry) => entry.name)));
 });
-var helioConfigSchema = z.preprocess(stripRootExtensionKeys, helioConfigRefinedSchema);
+var objectRootSchema = z.object({});
+function dispatchByMode(raw, ctx) {
+  const isObject2 = raw !== null && typeof raw === "object" && !Array.isArray(raw);
+  if (!isObject2) {
+    const typeResult = objectRootSchema.safeParse(raw);
+    if (!typeResult.success) {
+      for (const issue of typeResult.error.issues) {
+        ctx.addIssue(issue);
+      }
+    }
+    return z.NEVER;
+  }
+  const hasUpstream = "upstream" in raw;
+  const hasUpstreams = "upstreams" in raw;
+  if (hasUpstream && hasUpstreams) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["upstreams"],
+      message: 'Set exactly one of "upstream:" (single upstream) or "upstreams:" (named multi-upstream list) \u2014 not both. To migrate, move the upstream: fields into an upstreams: entry and give it a name.'
+    });
+    return z.NEVER;
+  }
+  if (!hasUpstream && !hasUpstreams) {
+    ctx.addIssue({
+      code: "custom",
+      message: 'Missing upstream configuration: set exactly one of "upstream:" (single upstream) or "upstreams:" (named multi-upstream list).'
+    });
+    return z.NEVER;
+  }
+  const result = hasUpstreams ? namedConfigSchema.safeParse(raw) : singularConfigSchema.safeParse(raw);
+  if (!result.success) {
+    for (const issue of result.error.issues) {
+      ctx.addIssue(issue);
+    }
+    return z.NEVER;
+  }
+  return result.data;
+}
+var helioConfigSchema = z.preprocess(
+  stripRootExtensionKeys,
+  z.unknown().transform(dispatchByMode)
+);
+function isSingularConfig(config) {
+  return !("upstreams" in config);
+}
+function isNamedConfig(config) {
+  return "upstreams" in config;
+}
 
 // src/config/loader.ts
 import { readFile } from "fs/promises";
@@ -904,7 +1115,8 @@ function compileMatch(match, ruleIndex, ruleName) {
     ...match.environment !== void 0 && { environment: match.environment },
     ...match.metadata !== void 0 && {
       metadata: flattenMetadataConditions(match.metadata, ruleIndex, ruleName)
-    }
+    },
+    ...match.upstreams !== void 0 && { upstreams: [...match.upstreams] }
   };
 }
 function compileToolMatcher(pattern, ruleIndex, ruleName) {
@@ -1107,6 +1319,9 @@ function compileContributor(contributor, budgetName, index) {
   ) : void 0;
   return {
     match: { tool, ...input !== void 0 && { input } },
+    ...contributor.match.upstreams !== void 0 && {
+      upstreams: [...contributor.match.upstreams]
+    },
     field: contributor.field
   };
 }
@@ -1371,6 +1586,8 @@ function buildStandardRequestHeaders(method, params) {
 }
 
 // src/upstream/merge-headers.ts
+var UPSTREAM_POST_ACCEPT = "application/json, text/event-stream";
+var UPSTREAM_SSE_CONNECT_ACCEPT = "text/event-stream";
 function mergeUpstreamHeaders(base, forwarded, staticHeaders) {
   const out = {};
   const apply = (headers) => {
@@ -1384,6 +1601,11 @@ function mergeUpstreamHeaders(base, forwarded, staticHeaders) {
   return out;
 }
 
+// src/util/log-label.ts
+function helioLogTag(upstreamName) {
+  return upstreamName ? `[helio][${upstreamName}]` : "[helio]";
+}
+
 // src/upstream/connection-error.ts
 var UPSTREAM_DOCS_URL = "https://github.com/gethelio/helio/blob/main/docs/getting-started.md";
 var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
@@ -1419,7 +1641,7 @@ function describeUnreachableUpstream(error, url) {
   }
   const codeSuffix = code ? ` (${code})` : "";
   return new Error(
-    `Upstream MCP server at ${url} is unreachable${codeSuffix} \u2014 is it running? Helio proxies an existing MCP server: set upstream.url in helio.yaml to a reachable server, or start the server it points at. See ${UPSTREAM_DOCS_URL}`
+    `Upstream MCP server at ${url} is unreachable${codeSuffix} \u2014 is it running? Helio proxies an existing MCP server: set upstream.url (or upstreams[].url) in helio.yaml to a reachable server, or start the server it points at. See ${UPSTREAM_DOCS_URL}`
   );
 }
 
@@ -1526,11 +1748,13 @@ var UpstreamSessionManager = class {
   inflight;
   inflightProbe;
   probeBackoffUntil = 0;
+  logTag;
   constructor(options) {
     this.url = options.url;
     this.staticHeaders = options.staticHeaders;
     this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
     this.pin = options.protocolVersion ?? "auto";
+    this.logTag = helioLogTag(options.upstreamName);
   }
   /** Return the internal session, establishing it once if needed. */
   ensureInternalSession() {
@@ -1662,7 +1886,7 @@ var UpstreamSessionManager = class {
     this.capture = void 0;
     this.probeBackoffUntil = Date.now() + ERA_PROBE_BACKOFF_MS;
     console.error(
-      `[helio] Upstream MCP era cleared: ${door}; relays presume legacy and re-probing is throttled for ${String(ERA_PROBE_BACKOFF_MS / 1e3)}s`
+      `${this.logTag} Upstream MCP era cleared: ${door}; relays presume legacy and re-probing is throttled for ${String(ERA_PROBE_BACKOFF_MS / 1e3)}s`
     );
   }
   /** Convert a fetch failure into an actionable error for the given step. */
@@ -1706,7 +1930,7 @@ var UpstreamSessionManager = class {
     if (this.era === era) return;
     this.era = era;
     console.error(
-      era === "modern" ? `[helio] Upstream MCP era detected: modern (${HELIO_MCP_MODERN_PROTOCOL_VERSION}, via server/discover)` : "[helio] Upstream MCP era detected: legacy (initialize handshake)"
+      era === "modern" ? `${this.logTag} Upstream MCP era detected: modern (${HELIO_MCP_MODERN_PROTOCOL_VERSION}, via server/discover)` : `${this.logTag} Upstream MCP era detected: legacy (initialize handshake)`
     );
   }
   /** A modern upstream neither mints nor echoes session ids — nothing to hold. */
@@ -1730,7 +1954,7 @@ var UpstreamSessionManager = class {
     const headers = mergeUpstreamHeaders(
       {
         "content-type": "application/json",
-        accept: "application/json, text/event-stream",
+        accept: UPSTREAM_POST_ACCEPT,
         "mcp-protocol-version": HELIO_MCP_MODERN_PROTOCOL_VERSION,
         "mcp-method": "server/discover"
       },
@@ -1739,6 +1963,7 @@ var UpstreamSessionManager = class {
     );
     headers["mcp-method"] = "server/discover";
     delete headers["mcp-name"];
+    headers["accept"] = UPSTREAM_POST_ACCEPT;
     const probeBody = {
       jsonrpc: "2.0",
       id: ERA_PROBE_REQUEST_ID,
@@ -1811,13 +2036,14 @@ var UpstreamSessionManager = class {
     const headers = mergeUpstreamHeaders(
       {
         "content-type": "application/json",
-        accept: "application/json, text/event-stream"
+        accept: UPSTREAM_POST_ACCEPT
       },
       {},
       this.staticHeaders
     );
     delete headers["mcp-method"];
     delete headers["mcp-name"];
+    headers["accept"] = UPSTREAM_POST_ACCEPT;
     const initBody = {
       jsonrpc: "2.0",
       id: 0,
@@ -2431,6 +2657,7 @@ function createSseRoute(forwarder, options = {}) {
   const forwardHeaderAllowlist = options.forwardHeadersAllowlist ?? [];
   const sessionIdentity = options.session ?? DEFAULT_SESSION_IDENTITY;
   const maxConcurrentSessions = options.maxConcurrentSessions ?? MAX_CONCURRENT_SESSIONS;
+  const routeLabel = options.routeLabel ?? "/sse";
   let refusalCount = 0;
   let lastRefusalLogAt = null;
   const logRefusal = () => {
@@ -2439,7 +2666,7 @@ function createSseRoute(forwarder, options = {}) {
     if (lastRefusalLogAt !== null && now - lastRefusalLogAt < REFUSAL_LOG_WINDOW_MS) return;
     lastRefusalLogAt = now;
     console.error(
-      `[helio] /sse at session cap (${String(maxConcurrentSessions)}); refusing new streams (${String(refusalCount)} refusals so far).`
+      `[helio] ${routeLabel} at session cap (${String(maxConcurrentSessions)}); refusing new streams (${String(refusalCount)} refusals so far).`
     );
   };
   app.use("*", createOriginGuard(options.allowedOrigins ?? []));
@@ -2645,6 +2872,11 @@ function createServerHandle(server) {
   };
 }
 function createApp(config, forwarder, options) {
+  if (isNamedConfig(config)) {
+    throw new Error(
+      "createApp serves a single-upstream (upstream:) config only. Named multi-upstream configs are composed by createMultiApp."
+    );
+  }
   const app = new Hono3();
   const forwardHeadersAllowlist = config.upstream.forward_headers;
   const allowedOrigins = config.listen.allowed_origins;
@@ -2665,6 +2897,77 @@ function createApp(config, forwarder, options) {
   }
   return app;
 }
+function createMultiApp(config, forwarders, options) {
+  if (!isNamedConfig(config)) {
+    throw new Error(
+      "createMultiApp composes a named multi-upstream (upstreams:) config only. Singular configs are served by createApp."
+    );
+  }
+  const doors = [];
+  const missing = [];
+  for (const entry of config.upstreams) {
+    const forwarder = forwarders[entry.name];
+    if (forwarder === void 0) missing.push(entry.name);
+    else doors.push({ entry, forwarder });
+  }
+  const configured = new Set(config.upstreams.map((entry) => entry.name));
+  const unexpected = Object.keys(forwarders).filter((name) => !configured.has(name));
+  if (missing.length > 0 || unexpected.length > 0) {
+    throw new Error(
+      `createMultiApp forwarders must match the configured upstream names exactly \u2014 missing: [${missing.join(", ")}], unexpected: [${unexpected.join(", ")}].`
+    );
+  }
+  const app = new Hono3();
+  const allowedOrigins = config.listen.allowed_origins;
+  const session = compileSessionIdentity(config.session);
+  app.get("/healthz", (c) => c.json({ status: "ok" }));
+  for (const { entry, forwarder } of doors) {
+    const name = entry.name;
+    app.route(
+      `/mcp/${name}`,
+      createStreamableHttpRoute(forwarder, {
+        forwardHeadersAllowlist: entry.forward_headers,
+        allowedOrigins,
+        session,
+        onHeaderMismatch: options?.onHeaderMismatch ? (rejection) => options.onHeaderMismatch?.(rejection, name) : void 0
+      })
+    );
+    app.route(
+      `/sse/${name}`,
+      createSseRoute(forwarder, {
+        forwardHeadersAllowlist: entry.forward_headers,
+        allowedOrigins,
+        session,
+        routeLabel: `/sse/${name}`,
+        maxConcurrentSessions: options?.sse?.maxConcurrentSessions
+      })
+    );
+  }
+  if (options?.slackActionApp) {
+    app.route("/slack/actions", options.slackActionApp);
+  }
+  app.all(
+    "/mcp/*",
+    (c) => c.json(
+      makeJsonRpcErrorWithoutId(
+        INVALID_REQUEST,
+        "No MCP endpoint answers this request: this Helio serves named upstreams at /mcp/<name>."
+      ),
+      404
+    )
+  );
+  app.all(
+    "/sse/*",
+    (c) => c.json(
+      makeJsonRpcErrorWithoutId(
+        INVALID_REQUEST,
+        "No MCP endpoint answers this request: this Helio serves named upstreams at /sse/<name>."
+      ),
+      404
+    )
+  );
+  return app;
+}
 function startServer(app, config) {
   const server = serve({
     fetch: app.fetch,
@@ -2718,7 +3021,8 @@ var StreamableHttpForwarder = class {
       url: this.url,
       staticHeaders: this.staticHeaders,
       requestTimeoutMs: this.requestTimeoutMs,
-      protocolVersion: options.protocolVersion
+      protocolVersion: options.protocolVersion,
+      upstreamName: options.upstreamName
     });
   }
   /** Lifecycle parity with sse/stdio. No eager connect — sessions are lazy. */
@@ -2891,11 +3195,15 @@ var StreamableHttpForwarder = class {
     const headers = mergeUpstreamHeaders(
       {
         "content-type": "application/json",
-        accept: "application/json, text/event-stream"
+        accept: UPSTREAM_POST_ACCEPT
       },
       request.headers ?? {},
       this.staticHeaders
     );
+    headers["content-type"] = "application/json";
+    delete headers["content-length"];
+    headers["accept"] = UPSTREAM_POST_ACCEPT;
+    delete headers["mcp-session-id"];
     if (session.sessionId) headers["mcp-session-id"] = session.sessionId;
     if (modern) {
       delete headers["mcp-session-id"];
@@ -3070,13 +3378,16 @@ var SseUpstreamForwarder = class {
   connect() {
     const controller = new AbortController();
     this.abortController = controller;
+    const headers = mergeUpstreamHeaders(
+      { accept: UPSTREAM_SSE_CONNECT_ACCEPT },
+      {},
+      this.staticHeaders
+    );
+    headers["accept"] = UPSTREAM_SSE_CONNECT_ACCEPT;
     return new Promise((resolve, reject) => {
       let resolved = false;
       fetch(this.url, {
-        headers: {
-          accept: "text/event-stream",
-          ...this.staticHeaders
-        },
+        headers,
         signal: AbortSignal.any([controller.signal, AbortSignal.timeout(this.connectTimeoutMs)])
       }).then((res) => {
         if (!res.ok) {
@@ -3128,9 +3439,12 @@ var SseUpstreamForwarder = class {
       request.headers ?? {},
       this.staticHeaders
     );
+    headers["content-type"] = "application/json";
+    delete headers["content-length"];
     delete headers["mcp-method"];
     delete headers["mcp-name"];
     delete headers["mcp-session-id"];
+    delete headers["accept"];
     if (request.transportSessionId) {
       headers["mcp-session-id"] = request.transportSessionId;
     }
@@ -3297,6 +3611,7 @@ var StdioForwarder = class {
   maxRetries;
   retryDelayMs;
   pending;
+  logTag;
   child = null;
   buffer = "";
   retryCount = 0;
@@ -3308,6 +3623,7 @@ var StdioForwarder = class {
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
     this.pending = new PendingRequests(options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS2);
+    this.logTag = helioLogTag(options.upstreamName);
   }
   /** Spawn the child process and set up event handlers. */
   start() {
@@ -3436,7 +3752,9 @@ var StdioForwarder = class {
       }, this.retryDelayMs);
     } else {
       this.dead = true;
-      console.error(`[helio] Stdio forwarder: max retries (${String(this.maxRetries)}) exceeded`);
+      console.error(
+        `${this.logTag} Stdio forwarder: max retries (${String(this.maxRetries)}) exceeded`
+      );
       this.pending.rejectAll(new Error("stdio forwarder is dead (max retries exceeded)"));
     }
   }
@@ -3511,6 +3829,10 @@ function matchEnvironment(required, ctx) {
   if (ctx.environment === void 0) return false;
   return ctx.environment === required;
 }
+function matchUpstreams(required, ctx) {
+  if (ctx.upstream === void 0) return false;
+  return required.includes(ctx.upstream);
+}
 function matchMetadata(conditions, ctx) {
   if (conditions.length === 0) return true;
   if (ctx.metadata === void 0) return false;
@@ -3536,6 +3858,7 @@ function matchRule(rule, ctx) {
   if (match.input !== void 0 && !matchInput(match.input, ctx)) return false;
   if (match.environment !== void 0 && !matchEnvironment(match.environment, ctx)) return false;
   if (match.metadata !== void 0 && !matchMetadata(match.metadata, ctx)) return false;
+  if (match.upstreams !== void 0 && !matchUpstreams(match.upstreams, ctx)) return false;
   return true;
 }
 
@@ -3690,7 +4013,8 @@ function decide(input) {
     annotations,
     toolArguments,
     environment,
-    metadata
+    metadata,
+    upstream: input.upstream
   });
   if (driftEvent && driftMode === "log") {
     const currentDecision = evaluatePolicy(policy, {
@@ -3698,7 +4022,8 @@ function decide(input) {
       annotations: input.currentAnnotations,
       toolArguments,
       environment,
-      metadata
+      metadata,
+      upstream: input.upstream
     });
     decision = stricterDecision(decision, currentDecision);
   }
@@ -4311,406 +4636,101 @@ function buildBudgetApprovalTimeoutFeedback(decision, breaches, timeoutMs) {
   };
 }
 
-// src/policy/spend-limiter.ts
-function spendBucketKey(baseKey, ruleIndex) {
+// src/policy/bucket-key.ts
+function ruleBucketKey(baseKey, ruleIndex) {
   return `${baseKey}:rule:${String(ruleIndex)}`;
 }
 var RULE_SUFFIX_RE = /:rule:(\d+)$/;
-var SpendLimiter = class {
-  buckets = /* @__PURE__ */ new Map();
-  now;
-  onWarning;
-  warningThreshold;
-  timer = null;
-  closed = false;
-  constructor(options = {}) {
-    this.now = options.now ?? Date.now;
-    this.onWarning = options.onWarning;
-    this.warningThreshold = options.warningThreshold ?? 0.8;
-    const intervalMs = options.cleanupIntervalMs ?? 6e4;
-    if (intervalMs > 0) {
-      this.timer = setInterval(() => {
-        this.cleanup();
-      }, intervalMs);
-      this.timer.unref();
+function parseRuleIndex(key) {
+  const match = RULE_SUFFIX_RE.exec(key);
+  return match ? Number(match[1]) : void 0;
+}
+function toolLimitKey(toolName, upstreamName) {
+  return upstreamName ? `upstream:${upstreamName}:tool:${toolName}` : `tool:${toolName}`;
+}
+
+// src/policy/governed-forwarder.ts
+var POLICY_DENIED = -32001;
+function blocked(result) {
+  return { proceed: false, result, approvalWaitMs: 0 };
+}
+function budgetChainBlock(entry, kind) {
+  return {
+    name: entry.budget.name,
+    bucket_key: entry.bucketKey,
+    allowed: entry.allowed,
+    amount: entry.amount,
+    spent: entry.spent,
+    limit: entry.budget.limit,
+    remaining: entry.remaining,
+    currency: entry.budget.currency,
+    ...kind ? { kind } : {},
+    ...entry.stale ? { stale: true } : {}
+  };
+}
+var GovernedForwarder = class {
+  inner;
+  policy;
+  environment;
+  session;
+  auditWriter;
+  evidenceStore;
+  approvalRouter;
+  rateLimiter;
+  spendLimiter;
+  budgetEngine;
+  upstreamName;
+  annotationCache = new ToolAnnotationCache();
+  agentKeyWarned = false;
+  senderKeyWarned = false;
+  constructor(inner, policy, options) {
+    this.inner = inner;
+    this.policy = policy;
+    this.environment = options?.environment;
+    this.auditWriter = options?.auditWriter;
+    this.evidenceStore = options?.evidenceStore;
+    this.approvalRouter = options?.approvalRouter;
+    this.rateLimiter = options?.rateLimiter;
+    this.spendLimiter = options?.spendLimiter;
+    this.budgetEngine = options?.budgetEngine;
+    this.upstreamName = options?.upstreamName;
+    this.session = options?.session ?? DEFAULT_SESSION_IDENTITY;
+    if (this.evidenceStore) {
+      this.evidenceStore.setAllowedEvidenceKeys(collectAllowedEvidenceKeys(policy));
     }
   }
-  // -------------------------------------------------------------------------
-  // Core operations
-  // -------------------------------------------------------------------------
   /**
-   * Check and optionally record a spend against the limit.
+   * Swap the compiled policy atomically and reconcile limit bucket state
+   * against the new configuration.
    *
-   * Evicts expired entries, sums remaining amounts, then checks:
-   * - Under limit (currentSpend + amount <= limit): records and returns `allowed: true`
-   * - Would exceed: does NOT record (rejected spends don't consume budget)
+   * Rate and spend limit buckets are preserved when their underlying rule
+   * config is unchanged — this is what makes a benign hot-reload (e.g. a
+   * `vim :w` with no real edits, or a whitespace-only config change) safe:
+   * operators do not get a surprise zero of their live rate/spend state
+   * mid-window. Buckets whose config changed or whose rule was removed are
+   * evicted by the limiters' `reconcile()` methods, so the next check
+   * lazy-creates a fresh bucket under the new config.
+   *
+   * See `packages/proxy/src/policy/rate-limiter.ts` and `spend-limiter.ts`
+   * for the per-bucket compare-and-evict semantics.
    */
-  check(params) {
-    const { key, amount, limit, windowMs } = params;
-    const now = this.now();
-    const windowStart = now - windowMs;
-    if (!Number.isFinite(amount) || amount < 0) {
-      const existing = this.buckets.get(key);
-      const activeEntries = existing ? existing.entries.filter((e) => e.timestamp > windowStart) : [];
-      const currentSpend2 = activeEntries.reduce((sum, e) => sum + e.amount, 0);
-      const oldest = activeEntries[0];
-      return {
-        allowed: false,
-        currentSpend: currentSpend2,
-        limit,
-        windowMs,
-        resetAtMs: oldest ? oldest.timestamp + windowMs : 0,
-        reason: "invalid_amount"
-      };
-    }
-    let bucket = this.buckets.get(key);
-    if (!bucket) {
-      bucket = { entries: [], limit, currency: "", windowMs };
-      this.buckets.set(key, bucket);
-    }
-    bucket.limit = limit;
-    bucket.windowMs = windowMs;
-    bucket.entries = bucket.entries.filter((e) => e.timestamp > windowStart);
-    const currentSpend = bucket.entries.reduce((sum, e) => sum + e.amount, 0);
-    if (currentSpend + amount > limit) {
-      const oldest = bucket.entries[0];
-      return {
-        allowed: false,
-        currentSpend,
-        limit,
-        windowMs,
-        resetAtMs: oldest ? oldest.timestamp + windowMs : 0
-      };
-    }
-    bucket.entries.push({ timestamp: now, amount });
-    const newSpend = currentSpend + amount;
-    const resetAtMs = (bucket.entries[0]?.timestamp ?? now) + windowMs;
-    if (this.onWarning && newSpend / limit >= this.warningThreshold) {
-      this.safeWarn({
-        key,
-        current_spend: newSpend,
-        limit,
-        currency: bucket.currency,
-        window_ms: windowMs,
-        reset_at_ms: resetAtMs
-      });
-    }
-    return {
-      allowed: true,
-      currentSpend: newSpend,
-      limit,
-      windowMs,
-      resetAtMs
-    };
-  }
-  /**
-   * Unconditionally record a spend against the limit.
-   *
-   * Unlike check(), this always appends the amount — even when it pushes the
-   * window past the limit — because the spend it represents has already been
-   * incurred. The sideband peeks at /evaluate and commits here at /audit once
-   * the external call ran (issue #12, D3).
-   *
-   * Throws on a negative or non-finite amount: such amounts are rejected at
-   * /evaluate, so one reaching record() is a logic bug we surface loudly rather
-   * than silently corrupt the sliding-window sum. Warnings fire only while the
-   * post-append spend stays within the limit (parity with check()).
-   */
-  record(params) {
-    const { key, amount, limit, windowMs } = params;
-    if (!Number.isFinite(amount) || amount < 0) {
-      throw new RangeError(
-        `SpendLimiter.record() received an invalid amount (${String(amount)}); invalid amounts must be rejected at /evaluate, never committed`
-      );
-    }
-    const now = this.now();
-    const windowStart = now - windowMs;
-    let bucket = this.buckets.get(key);
-    if (!bucket) {
-      bucket = { entries: [], limit, currency: "", windowMs };
-      this.buckets.set(key, bucket);
-    }
-    bucket.limit = limit;
-    bucket.windowMs = windowMs;
-    bucket.entries = bucket.entries.filter((e) => e.timestamp > windowStart);
-    bucket.entries.push({ timestamp: now, amount });
-    const currentSpend = bucket.entries.reduce((sum, e) => sum + e.amount, 0);
-    const resetAtMs = (bucket.entries[0]?.timestamp ?? now) + windowMs;
-    if (this.onWarning && currentSpend <= limit && currentSpend / limit >= this.warningThreshold) {
-      this.safeWarn({
-        key,
-        current_spend: currentSpend,
-        limit,
-        currency: bucket.currency,
-        window_ms: windowMs,
-        reset_at_ms: resetAtMs
-      });
-    }
-    return {
-      allowed: currentSpend <= limit,
-      currentSpend,
-      limit,
-      windowMs,
-      resetAtMs
-    };
-  }
-  /**
-   * Check the spend limit without recording the spend (non-destructive).
-   *
-   * Used by dry-run mode to determine what would happen without consuming
-   * budget in the bucket.
-   */
-  peek(params) {
-    const { key, amount, limit, windowMs } = params;
-    const now = this.now();
-    const windowStart = now - windowMs;
-    const bucket = this.buckets.get(key);
-    if (!Number.isFinite(amount) || amount < 0) {
-      const activeEntries2 = bucket ? bucket.entries.filter((e) => e.timestamp > windowStart) : [];
-      const currentSpend2 = activeEntries2.reduce((sum, e) => sum + e.amount, 0);
-      const oldest2 = activeEntries2[0];
-      return {
-        allowed: false,
-        currentSpend: currentSpend2,
-        limit,
-        windowMs,
-        resetAtMs: oldest2 ? oldest2.timestamp + windowMs : 0,
-        reason: "invalid_amount"
-      };
-    }
-    if (!bucket) {
-      const wouldExceed = amount > limit;
-      return {
-        allowed: !wouldExceed,
-        currentSpend: wouldExceed ? 0 : amount,
-        limit,
-        windowMs,
-        resetAtMs: now + windowMs
-      };
-    }
-    const activeEntries = bucket.entries.filter((e) => e.timestamp > windowStart);
-    const currentSpend = activeEntries.reduce((sum, e) => sum + e.amount, 0);
-    if (currentSpend + amount > limit) {
-      const oldest2 = activeEntries[0];
-      return {
-        allowed: false,
-        currentSpend,
-        limit,
-        windowMs,
-        resetAtMs: oldest2 ? oldest2.timestamp + windowMs : 0
-      };
-    }
-    const newSpend = currentSpend + amount;
-    const oldest = activeEntries[0];
-    return {
-      allowed: true,
-      currentSpend: newSpend,
-      limit,
-      windowMs,
-      resetAtMs: oldest ? oldest.timestamp + windowMs : now + windowMs
-    };
-  }
-  /**
-   * Set the display currency for a key. Called by the governed forwarder
-   * after check() so dashboard reads include the currency label.
-   */
-  setCurrency(key, currency) {
-    const bucket = this.buckets.get(key);
-    if (bucket) bucket.currency = currency;
-  }
-  // -------------------------------------------------------------------------
-  // Read operations (for dashboard API)
-  // -------------------------------------------------------------------------
-  /** Get the current state of a single key. Returns undefined if not tracked. */
-  getKeyState(key) {
-    const bucket = this.buckets.get(key);
-    if (!bucket) return void 0;
-    const windowStart = this.now() - bucket.windowMs;
-    bucket.entries = bucket.entries.filter((e) => e.timestamp > windowStart);
-    if (bucket.entries.length === 0) {
-      this.buckets.delete(key);
-      return void 0;
-    }
-    const currentSpend = bucket.entries.reduce((sum, e) => sum + e.amount, 0);
-    return {
-      key,
-      current_spend: currentSpend,
-      limit: bucket.limit,
-      currency: bucket.currency,
-      window_ms: bucket.windowMs,
-      reset_at_ms: (bucket.entries[0]?.timestamp ?? 0) + bucket.windowMs
-    };
-  }
-  /** List all tracked keys with their current state. */
-  listKeyStates() {
-    const states = [];
-    for (const key of [...this.buckets.keys()]) {
-      const state = this.getKeyState(key);
-      if (state) states.push(state);
-    }
-    return states;
-  }
-  // -------------------------------------------------------------------------
-  // Maintenance
-  // -------------------------------------------------------------------------
-  /** Sweep all buckets: remove expired entries, delete empty buckets. */
-  cleanup() {
-    const now = this.now();
-    for (const [key, bucket] of this.buckets) {
-      const windowStart = now - bucket.windowMs;
-      bucket.entries = bucket.entries.filter((e) => e.timestamp > windowStart);
-      if (bucket.entries.length === 0) {
-        this.buckets.delete(key);
-      }
-    }
-  }
-  /** Clear all spend limit state. Called on policy hot-reload. */
-  reset() {
-    this.buckets.clear();
-  }
-  /**
-   * Reconcile bucket state against a new policy's spend configuration.
-   *
-   * Walks every existing bucket and checks whether its last-seen
-   * `{ limit, currency, windowMs }` tuple still appears in `validConfigs`.
-   * Buckets whose config is unchanged are left untouched — cumulative spend
-   * and elapsed-window progress are preserved across hot-reloads. Buckets
-   * whose config is gone (rule changed or removed) are evicted so the next
-   * check lazy-creates a fresh bucket under the new config.
-   *
-   * Keys built by {@link spendBucketKey} carry the owning rule's index, and
-   * for those the tuple must match at THAT index (`config.ruleIndex`): a
-   * reorder that shifts a spend rule's index evicts its old-index bucket
-   * instead of leaving an orphan no rule reads again — or worse, letting
-   * whatever rule now sits at that index adopt another rule's accrued spend.
-   * Un-suffixed keys keep the tuple-anywhere match.
-   *
-   * Currency is part of the tuple because a USD→EUR switch is a meaningful
-   * policy change — the same numeric limit buys a different amount of real
-   * spend, so the bucket must reset. This replaces the old `reset()` call
-   * on every hot-reload, which wiped all state even when the matching rule
-   * was unchanged.
-   */
-  reconcile(validConfigs) {
-    const valid = /* @__PURE__ */ new Set();
-    const byIndex = /* @__PURE__ */ new Map();
-    for (const config of validConfigs) {
-      const tuple = `${String(config.limit)}|${config.currency}|${String(config.windowMs)}`;
-      if (config.ruleIndex === void 0) {
-        valid.add(tuple);
-      } else {
-        byIndex.set(config.ruleIndex, tuple);
-      }
-    }
-    for (const [key, bucket] of this.buckets) {
-      const tuple = `${String(bucket.limit)}|${bucket.currency}|${String(bucket.windowMs)}`;
-      const suffix = RULE_SUFFIX_RE.exec(key);
-      const survives = suffix ? byIndex.get(Number(suffix[1])) === tuple : valid.has(tuple);
-      if (!survives) {
-        this.buckets.delete(key);
-      }
-    }
-  }
-  /** Stop the cleanup timer and mark as closed. */
-  /**
-   * Invoke the warning callback without letting a subscriber throw into the
-   * limiter's caller: a warning fires after state has already mutated, and a
-   * governed call must not be blocked (or double-charged on retry) by an
-   * observability bug.
-   */
-  safeWarn(state) {
-    if (!this.onWarning) return;
-    try {
-      this.onWarning(state);
-    } catch (err) {
-      console.error("[helio] limit warning subscriber threw:", err);
-    }
-  }
-  close() {
-    if (this.closed) return;
-    this.closed = true;
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
-    this.buckets.clear();
-  }
-};
-
-// src/policy/governed-forwarder.ts
-var POLICY_DENIED = -32001;
-function blocked(result) {
-  return { proceed: false, result, approvalWaitMs: 0 };
-}
-function budgetChainBlock(entry, kind) {
-  return {
-    name: entry.budget.name,
-    bucket_key: entry.bucketKey,
-    allowed: entry.allowed,
-    amount: entry.amount,
-    spent: entry.spent,
-    limit: entry.budget.limit,
-    remaining: entry.remaining,
-    currency: entry.budget.currency,
-    ...kind ? { kind } : {},
-    ...entry.stale ? { stale: true } : {}
-  };
-}
-var GovernedForwarder = class {
-  inner;
-  policy;
-  environment;
-  session;
-  auditWriter;
-  evidenceStore;
-  approvalRouter;
-  rateLimiter;
-  spendLimiter;
-  budgetEngine;
-  annotationCache = new ToolAnnotationCache();
-  agentKeyWarned = false;
-  senderKeyWarned = false;
-  constructor(inner, policy, options) {
-    this.inner = inner;
-    this.policy = policy;
-    this.environment = options?.environment;
-    this.auditWriter = options?.auditWriter;
-    this.evidenceStore = options?.evidenceStore;
-    this.approvalRouter = options?.approvalRouter;
-    this.rateLimiter = options?.rateLimiter;
-    this.spendLimiter = options?.spendLimiter;
-    this.budgetEngine = options?.budgetEngine;
-    this.session = options?.session ?? DEFAULT_SESSION_IDENTITY;
-    if (this.evidenceStore) {
-      this.evidenceStore.setAllowedEvidenceKeys(collectAllowedEvidenceKeys(policy));
-    }
-  }
-  /**
-   * Swap the compiled policy atomically and reconcile limit bucket state
-   * against the new configuration.
-   *
-   * Rate and spend limit buckets are preserved when their underlying rule
-   * config is unchanged — this is what makes a benign hot-reload (e.g. a
-   * `vim :w` with no real edits, or a whitespace-only config change) safe:
-   * operators do not get a surprise zero of their live rate/spend state
-   * mid-window. Buckets whose config changed or whose rule was removed are
-   * evicted by the limiters' `reconcile()` methods, so the next check
-   * lazy-creates a fresh bucket under the new config.
-   *
-   * See `packages/proxy/src/policy/rate-limiter.ts` and `spend-limiter.ts`
-   * for the per-bucket compare-and-evict semantics.
-   */
-  updatePolicy(policy) {
-    this.policy = policy;
-    if (this.evidenceStore) {
-      this.evidenceStore.setAllowedEvidenceKeys(collectAllowedEvidenceKeys(policy));
+  updatePolicy(policy) {
+    this.policy = policy;
+    if (this.evidenceStore) {
+      this.evidenceStore.setAllowedEvidenceKeys(collectAllowedEvidenceKeys(policy));
     }
     if (this.rateLimiter) {
       const rateConfigs = [];
       for (const rule of policy.rules) {
         const limits = rule.limits;
         if (limits?.maxCalls !== void 0 && limits.windowMs !== void 0) {
-          rateConfigs.push({ maxCalls: limits.maxCalls, windowMs: limits.windowMs });
+          rateConfigs.push({
+            maxCalls: limits.maxCalls,
+            windowMs: limits.windowMs,
+            // Rate bucket keys are rule-discriminated (ruleBucketKey), so
+            // reconcile must match tuples at the owning rule's index.
+            ruleIndex: rule.index
+          });
         }
       }
       this.rateLimiter.reconcile(rateConfigs);
@@ -4724,7 +4744,7 @@ var GovernedForwarder = class {
             limit: maxSpend.limit,
             currency: maxSpend.currency,
             windowMs: maxSpend.windowMs,
-            // Spend bucket keys are rule-discriminated (spendBucketKey), so
+            // Spend bucket keys are rule-discriminated (ruleBucketKey), so
             // reconcile must match tuples at the owning rule's index.
             ruleIndex: rule.index
           });
@@ -4870,7 +4890,8 @@ var GovernedForwarder = class {
       origin: "mcp",
       metadata: null,
       // Drift is a cache event, not a request: no protocol claim exists.
-      protocol_version: null
+      protocol_version: null,
+      upstream: this.upstreamName ?? null
     });
   }
   async handleToolsCall(original) {
@@ -4914,7 +4935,8 @@ var GovernedForwarder = class {
       evidenceStore: this.evidenceStore,
       baselineAnnotations: this.annotationCache.get(toolName),
       currentAnnotations: this.annotationCache.getCurrent(toolName),
-      driftEvent: this.annotationCache.getDrift(toolName)
+      driftEvent: this.annotationCache.getDrift(toolName),
+      upstream: this.upstreamName
     });
     const auditRecordId = randomUUID2();
     let result;
@@ -5057,6 +5079,8 @@ var GovernedForwarder = class {
         tool_input: toolArguments ?? {},
         matched_rule: decision.matchedRule,
         session_id: request.session?.id ?? null,
+        session_source: request.session?.source ?? null,
+        upstream: this.upstreamName ?? null,
         breached_budgets: gate.breachContexts,
         approval: gate.approval
       },
@@ -5204,8 +5228,9 @@ var GovernedForwarder = class {
       toolName,
       toolArguments,
       sessionId: sessionGate.ok ? sessionGate.session : null,
-      senderId: null
+      senderId: null,
       // adapter context; absent on the MCP path
+      upstream: this.upstreamName ?? null
     });
     if (charges.length === 0 && failures.length === 0) return { kind: "proceed" };
     const gated = gateBudgetCharges({ charges, failures }, sessionGate);
@@ -5351,7 +5376,8 @@ var GovernedForwarder = class {
         record_kind: "tool_call",
         origin: "mcp",
         metadata: null,
-        protocol_version: request.protocolVersion ?? null
+        protocol_version: request.protocolVersion ?? null,
+        upstream: this.upstreamName ?? null
       });
     }
     return result;
@@ -5364,7 +5390,9 @@ var GovernedForwarder = class {
         tool_name: toolName,
         tool_input: toolArguments ?? {},
         matched_rule: decision.matchedRule,
-        session_id: request.session?.id ?? null
+        session_id: request.session?.id ?? null,
+        session_source: request.session?.source ?? null,
+        upstream: this.upstreamName ?? null
       },
       request.signal
     );
@@ -5446,8 +5474,9 @@ var GovernedForwarder = class {
   }
   handleRateLimit(request, decision, toolName) {
     const limiter = this.rateLimiter;
-    const limits = decision.matchedRule?.limits;
-    if (!limits?.maxCalls || !limits.windowMs) {
+    const matchedRule = decision.matchedRule;
+    const limits = matchedRule?.limits;
+    if (!matchedRule || !limits?.maxCalls || !limits.windowMs) {
       const result = this.makePolicyMisconfiguredResult(
         request,
         decision,
@@ -5460,7 +5489,7 @@ var GovernedForwarder = class {
         rateLimitResult: { allowed: false, current: 0, limit: 0, windowMs: 0, resetAtMs: 0 }
       };
     }
-    let key;
+    let baseKey;
     if (limits.key === "session") {
       const sessionKey = this.gateSessionLimitKey(request);
       if (sessionKey === null) {
@@ -5470,15 +5499,16 @@ var GovernedForwarder = class {
           approvalWaitMs: 0
         };
       }
-      key = sessionKey;
+      baseKey = sessionKey;
     } else {
-      key = this.buildLimitKey(limits.key, toolName);
+      baseKey = this.buildLimitKey(limits.key, toolName);
     }
+    const key = ruleBucketKey(baseKey, matchedRule.index);
     const params = { key, maxCalls: limits.maxCalls, windowMs: limits.windowMs };
     const rateLimitResult = limiter.peek(params);
     if (!rateLimitResult.allowed) {
       const feedback = buildRateLimitedFeedback(decision, rateLimitResult);
-      const message = decision.matchedRule?.feedback?.message ?? `Rate limit exceeded for ${key}`;
+      const message = matchedRule.feedback?.message ?? `Rate limit exceeded for ${key}`;
       return {
         proceed: false,
         result: makeErrorResult(request, POLICY_DENIED, message, { ...feedback }),
@@ -5525,7 +5555,7 @@ var GovernedForwarder = class {
     } else {
       baseKey = this.buildLimitKey(maxSpend.key, toolName);
     }
-    const key = spendBucketKey(baseKey, decision.matchedRule.index);
+    const key = ruleBucketKey(baseKey, decision.matchedRule.index);
     const rawAmount = resolvePath(maxSpend.field, toolArguments ?? {});
     if (typeof rawAmount !== "number") {
       console.error(
@@ -5598,14 +5628,14 @@ var GovernedForwarder = class {
         case "rate_limit":
           if (this.rateLimiter && decision.matchedRule?.limits?.maxCalls && decision.matchedRule.limits.windowMs) {
             const limits = decision.matchedRule.limits;
-            const key = limits.key === "session" ? this.gateSessionLimitKey(request) : this.buildLimitKey(limits.key, toolName);
-            if (key === null) {
+            const baseKey = limits.key === "session" ? this.gateSessionLimitKey(request) : this.buildLimitKey(limits.key, toolName);
+            if (baseKey === null) {
               wouldForward = false;
               limitsOk = false;
               sessionUnresolved = true;
             } else {
               const peekResult = this.rateLimiter.peek({
-                key,
+                key: ruleBucketKey(baseKey, decision.matchedRule.index),
                 maxCalls: decision.matchedRule.limits.maxCalls,
                 windowMs: decision.matchedRule.limits.windowMs
               });
@@ -5638,7 +5668,7 @@ var GovernedForwarder = class {
                 sessionUnresolved = true;
               } else {
                 const peekResult = this.spendLimiter.peek({
-                  key: spendBucketKey(baseKey, decision.matchedRule.index),
+                  key: ruleBucketKey(baseKey, decision.matchedRule.index),
                   amount: rawAmount,
                   limit: maxSpend.limit,
                   windowMs: maxSpend.windowMs
@@ -5658,7 +5688,8 @@ var GovernedForwarder = class {
         toolName,
         toolArguments,
         sessionId: sessionGate.ok ? sessionGate.session : null,
-        senderId: null
+        senderId: null,
+        upstream: this.upstreamName ?? null
       });
       if (failures.length > 0 || charges.length > 0) {
         const gated = gateBudgetCharges({ charges, failures }, sessionGate);
@@ -5699,7 +5730,9 @@ var GovernedForwarder = class {
     );
   }
   /**
-   * Construct a non-session limit bucket key. Session keys are deliberately
+   * Construct a non-session limit bucket key. Tool-scope keys route through
+   * the shared `toolLimitKey` leaf, which prefixes them with the configured
+   * upstream name when one is set (issue #295). Session keys are deliberately
    * NOT built here: they come only from the gate module's `sessionLimitKey`,
    * whose `GatedSession` parameter makes skipping the identity gate a
    * compile error (issue #218) — call sites branch on `key === 'session'`.
@@ -5713,7 +5746,7 @@ var GovernedForwarder = class {
             '[helio] Warning: limits.key "agent" is not yet supported, falling back to "tool"'
           );
         }
-        return `tool:${toolName}`;
+        return toolLimitKey(toolName, this.upstreamName);
       case "sender_id":
         if (!this.senderKeyWarned) {
           this.senderKeyWarned = true;
@@ -5721,10 +5754,10 @@ var GovernedForwarder = class {
             '[helio] Warning: limits.key "sender_id" has no sender on the MCP path, falling back to "tool"'
           );
         }
-        return `tool:${toolName}`;
+        return toolLimitKey(toolName, this.upstreamName);
       case "tool":
       default:
-        return `tool:${toolName}`;
+        return toolLimitKey(toolName, this.upstreamName);
     }
   }
   /**
@@ -5879,7 +5912,8 @@ var GovernedForwarder = class {
       record_kind: "tool_call",
       origin: "mcp",
       metadata: null,
-      protocol_version: request.protocolVersion ?? null
+      protocol_version: request.protocolVersion ?? null,
+      upstream: this.upstreamName ?? null
     };
     const isEnforcementDecision = !isDryRun && (!forwarded || approvalOutcome !== void 0 || budgetApproval !== void 0);
     if (isEnforcementDecision) {
@@ -5950,113 +5984,376 @@ var GovernedForwarder = class {
       headers: { "content-type": "application/json" },
       body
     };
-    return { response, durationMs: 0 };
-  }
-  makeEvidenceBlockResult(request, decision, evidenceResult, dependencyResult) {
-    const reason = evidenceResult && !evidenceResult.satisfied ? evidenceResult.expired.length > 0 ? "evidence_expired" : "evidence_missing" : "dependency_missing";
-    const builder = reason === "evidence_expired" ? buildEvidenceExpiredFeedback : reason === "evidence_missing" ? buildEvidenceMissingFeedback : buildDependencyMissingFeedback;
-    const feedback = builder(decision, evidenceResult, dependencyResult);
-    return makeErrorResult(
-      request,
-      POLICY_DENIED,
-      `Evidence grounding failed: ${decision.reason}`,
-      { ...feedback }
-    );
-  }
-  makeSessionRequiredBlockResult(request, decision) {
-    const feedback = buildPolicyDeniedFeedback(decision);
-    return makeErrorResult(request, POLICY_DENIED, decision.reason, {
-      ...feedback,
-      retry_allowed: true
-    });
+    return { response, durationMs: 0 };
+  }
+  makeEvidenceBlockResult(request, decision, evidenceResult, dependencyResult) {
+    const reason = evidenceResult && !evidenceResult.satisfied ? evidenceResult.expired.length > 0 ? "evidence_expired" : "evidence_missing" : "dependency_missing";
+    const builder = reason === "evidence_expired" ? buildEvidenceExpiredFeedback : reason === "evidence_missing" ? buildEvidenceMissingFeedback : buildDependencyMissingFeedback;
+    const feedback = builder(decision, evidenceResult, dependencyResult);
+    return makeErrorResult(
+      request,
+      POLICY_DENIED,
+      `Evidence grounding failed: ${decision.reason}`,
+      { ...feedback }
+    );
+  }
+  makeSessionRequiredBlockResult(request, decision) {
+    const feedback = buildPolicyDeniedFeedback(decision);
+    return makeErrorResult(request, POLICY_DENIED, decision.reason, {
+      ...feedback,
+      retry_allowed: true
+    });
+  }
+  makeClientDisconnectedBlockResult(request, decision) {
+    const feedback = buildClientDisconnectedFeedback(decision);
+    return makeErrorResult(request, POLICY_DENIED, "Client disconnected before completion", {
+      ...feedback
+    });
+  }
+};
+function collectAllowedEvidenceKeys(policy) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const rule of policy.rules) {
+    for (const key of rule.evidence?.requires ?? []) {
+      keys.add(key);
+    }
+  }
+  return [...keys];
+}
+function makeErrorResult(request, code, message, data) {
+  const body = {
+    jsonrpc: "2.0",
+    id: request.id ?? null,
+    error: { code, message, data }
+  };
+  const response = {
+    status: 200,
+    headers: { "content-type": "application/json" },
+    body
+  };
+  return { response, durationMs: 0 };
+}
+function approvedByOf(outcome) {
+  return outcome && "resolvedBy" in outcome ? outcome.resolvedBy : null;
+}
+function hasJsonRpcError(result) {
+  const body = result.response.body;
+  return body?.["error"] !== void 0;
+}
+function classifyPrimeFailure(response) {
+  if (response.status >= 400) {
+    return `upstream returned HTTP ${String(response.status)} to tools/list (session/initialize may be required)`;
+  }
+  const rawBody = response.body;
+  if (typeof rawBody !== "object" || rawBody === null) {
+    return `upstream tools/list returned a non-JSON body (content-type ${response.headers["content-type"] ?? "unknown"})`;
+  }
+  const body = rawBody;
+  const error = body["error"];
+  if (typeof error === "string") {
+    return `upstream tools/list returned a JSON-RPC error: ${error}`;
+  }
+  if (error !== null && typeof error === "object") {
+    const message = error["message"];
+    if (typeof message === "string") {
+      return `upstream tools/list returned a JSON-RPC error: ${message}`;
+    }
+  }
+  return "upstream tools/list response was missing result.tools";
+}
+function extractBlockReason(result) {
+  const body = result.response.body;
+  const error = body?.["error"];
+  if (!error || typeof error !== "object") return null;
+  const data = error["data"];
+  if (!data || data["blocked"] !== true) return null;
+  return typeof data["reason"] === "string" ? data["reason"] : null;
+}
+function buildEvidenceChain(evidenceResult, dependencyResult, blocked2) {
+  if (!evidenceResult && !dependencyResult) return null;
+  const chain = { blocked: blocked2 ?? false };
+  if (evidenceResult) {
+    chain["evidence"] = {
+      required: [...evidenceResult.found, ...evidenceResult.missing, ...evidenceResult.expired],
+      found: evidenceResult.found,
+      missing: evidenceResult.missing,
+      expired: evidenceResult.expired
+    };
+  }
+  if (dependencyResult) {
+    chain["dependencies"] = {
+      satisfied: dependencyResult.satisfied,
+      missing: dependencyResult.missing
+    };
+  }
+  return chain;
+}
+
+// src/policy/rate-limiter.ts
+var RateLimiter = class {
+  buckets = /* @__PURE__ */ new Map();
+  now;
+  onWarning;
+  warningThreshold;
+  timer = null;
+  closed = false;
+  constructor(options = {}) {
+    this.now = options.now ?? Date.now;
+    this.onWarning = options.onWarning;
+    this.warningThreshold = options.warningThreshold ?? 0.8;
+    const intervalMs = options.cleanupIntervalMs ?? 6e4;
+    if (intervalMs > 0) {
+      this.timer = setInterval(() => {
+        this.cleanup();
+      }, intervalMs);
+      this.timer.unref();
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Core operations
+  // -------------------------------------------------------------------------
+  /**
+   * Check and optionally record a call against the rate limit.
+   *
+   * Evicts expired timestamps, then checks the count:
+   * - Under limit: records the timestamp and returns `allowed: true`
+   * - At/over limit: does NOT record (blocked calls don't consume a slot)
+   */
+  check(params) {
+    const { key, maxCalls, windowMs } = params;
+    const now = this.now();
+    const windowStart = now - windowMs;
+    let bucket = this.buckets.get(key);
+    if (!bucket) {
+      bucket = { timestamps: [], maxCalls, windowMs };
+      this.buckets.set(key, bucket);
+    }
+    bucket.maxCalls = maxCalls;
+    bucket.windowMs = windowMs;
+    bucket.timestamps = bucket.timestamps.filter((ts) => ts > windowStart);
+    if (bucket.timestamps.length >= maxCalls) {
+      const oldest = bucket.timestamps[0] ?? 0;
+      return {
+        allowed: false,
+        current: bucket.timestamps.length,
+        limit: maxCalls,
+        windowMs,
+        resetAtMs: oldest + windowMs
+      };
+    }
+    bucket.timestamps.push(now);
+    const current = bucket.timestamps.length;
+    const resetAtMs = (bucket.timestamps[0] ?? now) + windowMs;
+    if (this.onWarning && current / maxCalls >= this.warningThreshold) {
+      this.safeWarn({ key, current, limit: maxCalls, window_ms: windowMs, reset_at_ms: resetAtMs });
+    }
+    return {
+      allowed: true,
+      current,
+      limit: maxCalls,
+      windowMs,
+      resetAtMs
+    };
+  }
+  /**
+   * Unconditionally record a call against the rate limit.
+   *
+   * Unlike check(), this always appends the timestamp — even when the bucket
+   * is already at/over the limit — because the call it represents has already
+   * executed. The sideband splits decision from execution: /evaluate peeks
+   * (non-destructive), and /audit calls record() once the external call ran,
+   * so refusing to record at the limit (as check() does) would let real calls
+   * escape accounting and under-count subsequent peeks. (issue #12, D3.)
+   *
+   * Warnings fire only while the post-append count stays within the limit —
+   * exact parity with check(), which never warns on its over-limit path — so a
+   * burst of over-limit audits cannot flood the dashboard's limit_warning feed.
+   */
+  record(params) {
+    const { key, maxCalls, windowMs } = params;
+    const now = this.now();
+    const windowStart = now - windowMs;
+    let bucket = this.buckets.get(key);
+    if (!bucket) {
+      bucket = { timestamps: [], maxCalls, windowMs };
+      this.buckets.set(key, bucket);
+    }
+    bucket.maxCalls = maxCalls;
+    bucket.windowMs = windowMs;
+    bucket.timestamps = bucket.timestamps.filter((ts) => ts > windowStart);
+    bucket.timestamps.push(now);
+    const current = bucket.timestamps.length;
+    const resetAtMs = (bucket.timestamps[0] ?? now) + windowMs;
+    if (this.onWarning && current <= maxCalls && current / maxCalls >= this.warningThreshold) {
+      this.safeWarn({ key, current, limit: maxCalls, window_ms: windowMs, reset_at_ms: resetAtMs });
+    }
+    return {
+      allowed: current <= maxCalls,
+      current,
+      limit: maxCalls,
+      windowMs,
+      resetAtMs
+    };
   }
-  makeClientDisconnectedBlockResult(request, decision) {
-    const feedback = buildClientDisconnectedFeedback(decision);
-    return makeErrorResult(request, POLICY_DENIED, "Client disconnected before completion", {
-      ...feedback
-    });
+  /**
+   * Check the rate limit without recording the call (non-destructive).
+   *
+   * Used by dry-run mode to determine what would happen without consuming
+   * a slot in the bucket.
+   */
+  peek(params) {
+    const { key, maxCalls, windowMs } = params;
+    const now = this.now();
+    const windowStart = now - windowMs;
+    const bucket = this.buckets.get(key);
+    if (!bucket) {
+      return {
+        allowed: true,
+        current: 1,
+        limit: maxCalls,
+        windowMs,
+        resetAtMs: now + windowMs
+      };
+    }
+    const activeCount = bucket.timestamps.filter((ts) => ts > windowStart).length;
+    if (activeCount >= maxCalls) {
+      const oldest2 = bucket.timestamps.find((ts) => ts > windowStart) ?? 0;
+      return {
+        allowed: false,
+        current: activeCount,
+        limit: maxCalls,
+        windowMs,
+        resetAtMs: oldest2 + windowMs
+      };
+    }
+    const oldest = bucket.timestamps.find((ts) => ts > windowStart) ?? now;
+    return {
+      allowed: true,
+      current: activeCount + 1,
+      limit: maxCalls,
+      windowMs,
+      resetAtMs: oldest + windowMs
+    };
   }
-};
-function collectAllowedEvidenceKeys(policy) {
-  const keys = /* @__PURE__ */ new Set();
-  for (const rule of policy.rules) {
-    for (const key of rule.evidence?.requires ?? []) {
-      keys.add(key);
+  // -------------------------------------------------------------------------
+  // Read operations (for dashboard API)
+  // -------------------------------------------------------------------------
+  /** Get the current state of a single key. Returns undefined if not tracked. */
+  getKeyState(key) {
+    const bucket = this.buckets.get(key);
+    if (!bucket) return void 0;
+    const windowStart = this.now() - bucket.windowMs;
+    bucket.timestamps = bucket.timestamps.filter((ts) => ts > windowStart);
+    if (bucket.timestamps.length === 0) {
+      this.buckets.delete(key);
+      return void 0;
     }
+    return {
+      key,
+      current: bucket.timestamps.length,
+      limit: bucket.maxCalls,
+      window_ms: bucket.windowMs,
+      reset_at_ms: (bucket.timestamps[0] ?? 0) + bucket.windowMs
+    };
   }
-  return [...keys];
-}
-function makeErrorResult(request, code, message, data) {
-  const body = {
-    jsonrpc: "2.0",
-    id: request.id ?? null,
-    error: { code, message, data }
-  };
-  const response = {
-    status: 200,
-    headers: { "content-type": "application/json" },
-    body
-  };
-  return { response, durationMs: 0 };
-}
-function approvedByOf(outcome) {
-  return outcome && "resolvedBy" in outcome ? outcome.resolvedBy : null;
-}
-function hasJsonRpcError(result) {
-  const body = result.response.body;
-  return body?.["error"] !== void 0;
-}
-function classifyPrimeFailure(response) {
-  if (response.status >= 400) {
-    return `upstream returned HTTP ${String(response.status)} to tools/list (session/initialize may be required)`;
+  /** List all tracked keys with their current state. */
+  listKeyStates() {
+    const states = [];
+    for (const key of [...this.buckets.keys()]) {
+      const state = this.getKeyState(key);
+      if (state) states.push(state);
+    }
+    return states;
   }
-  const rawBody = response.body;
-  if (typeof rawBody !== "object" || rawBody === null) {
-    return `upstream tools/list returned a non-JSON body (content-type ${response.headers["content-type"] ?? "unknown"})`;
+  // -------------------------------------------------------------------------
+  // Maintenance
+  // -------------------------------------------------------------------------
+  /** Sweep all buckets: remove expired timestamps, delete empty buckets. */
+  cleanup() {
+    const now = this.now();
+    for (const [key, bucket] of this.buckets) {
+      const windowStart = now - bucket.windowMs;
+      bucket.timestamps = bucket.timestamps.filter((ts) => ts > windowStart);
+      if (bucket.timestamps.length === 0) {
+        this.buckets.delete(key);
+      }
+    }
   }
-  const body = rawBody;
-  const error = body["error"];
-  if (typeof error === "string") {
-    return `upstream tools/list returned a JSON-RPC error: ${error}`;
+  /** Clear all rate limit state. Called on policy hot-reload. */
+  reset() {
+    this.buckets.clear();
   }
-  if (error !== null && typeof error === "object") {
-    const message = error["message"];
-    if (typeof message === "string") {
-      return `upstream tools/list returned a JSON-RPC error: ${message}`;
+  /**
+   * Reconcile bucket state against a new policy's limit configuration.
+   *
+   * Walks every existing bucket and checks whether its last-seen
+   * `{ maxCalls, windowMs }` tuple still appears in `validConfigs`.
+   * Buckets whose config is still present are left untouched — counters and
+   * elapsed-window progress are preserved across hot-reloads. Buckets whose
+   * config is gone (rule changed or removed) are evicted so the next check
+   * lazy-creates a fresh bucket under the new config.
+   *
+   * Keys built by `ruleBucketKey` (bucket-key.ts) carry the owning rule's
+   * index, and for those the tuple must match at THAT index
+   * (`config.ruleIndex`): a reorder that shifts a rate rule's index evicts
+   * its old-index bucket instead of leaving an orphan no rule reads again —
+   * or worse, letting whatever rule now sits at that index adopt another
+   * rule's accrued calls. Un-suffixed keys keep the tuple-anywhere match,
+   * but only against index-less configs — a caller that passes only indexed
+   * configs (as the proxy does) evicts every un-suffixed bucket, fail-closed.
+   *
+   * This is the compare-and-evict semantic that replaces the old `reset()`
+   * call on every hot-reload, which wiped all state even when the matching
+   * rule was unchanged.
+   */
+  reconcile(validConfigs) {
+    const valid = /* @__PURE__ */ new Set();
+    const byIndex = /* @__PURE__ */ new Map();
+    for (const config of validConfigs) {
+      const tuple = `${String(config.maxCalls)}|${String(config.windowMs)}`;
+      if (config.ruleIndex === void 0) {
+        valid.add(tuple);
+      } else {
+        byIndex.set(config.ruleIndex, tuple);
+      }
+    }
+    for (const [key, bucket] of this.buckets) {
+      const tuple = `${String(bucket.maxCalls)}|${String(bucket.windowMs)}`;
+      const ruleIndex = parseRuleIndex(key);
+      const survives = ruleIndex === void 0 ? valid.has(tuple) : byIndex.get(ruleIndex) === tuple;
+      if (!survives) {
+        this.buckets.delete(key);
+      }
     }
   }
-  return "upstream tools/list response was missing result.tools";
-}
-function extractBlockReason(result) {
-  const body = result.response.body;
-  const error = body?.["error"];
-  if (!error || typeof error !== "object") return null;
-  const data = error["data"];
-  if (!data || data["blocked"] !== true) return null;
-  return typeof data["reason"] === "string" ? data["reason"] : null;
-}
-function buildEvidenceChain(evidenceResult, dependencyResult, blocked2) {
-  if (!evidenceResult && !dependencyResult) return null;
-  const chain = { blocked: blocked2 ?? false };
-  if (evidenceResult) {
-    chain["evidence"] = {
-      required: [...evidenceResult.found, ...evidenceResult.missing, ...evidenceResult.expired],
-      found: evidenceResult.found,
-      missing: evidenceResult.missing,
-      expired: evidenceResult.expired
-    };
+  /** Stop the cleanup timer and mark as closed. */
+  /**
+   * Invoke the warning callback without letting a subscriber throw into the
+   * limiter's caller: a warning fires after state has already mutated, and a
+   * governed call must not be blocked (or double-charged on retry) by an
+   * observability bug.
+   */
+  safeWarn(state) {
+    if (!this.onWarning) return;
+    try {
+      this.onWarning(state);
+    } catch (err) {
+      console.error("[helio] limit warning subscriber threw:", err);
+    }
   }
-  if (dependencyResult) {
-    chain["dependencies"] = {
-      satisfied: dependencyResult.satisfied,
-      missing: dependencyResult.missing
-    };
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.buckets.clear();
   }
-  return chain;
-}
+};
 
-// src/policy/rate-limiter.ts
-var RateLimiter = class {
+// src/policy/spend-limiter.ts
+var SpendLimiter = class {
   buckets = /* @__PURE__ */ new Map();
   now;
   onWarning;
@@ -6079,128 +6376,185 @@ var RateLimiter = class {
   // Core operations
   // -------------------------------------------------------------------------
   /**
-   * Check and optionally record a call against the rate limit.
+   * Check and optionally record a spend against the limit.
    *
-   * Evicts expired timestamps, then checks the count:
-   * - Under limit: records the timestamp and returns `allowed: true`
-   * - At/over limit: does NOT record (blocked calls don't consume a slot)
+   * Evicts expired entries, sums remaining amounts, then checks:
+   * - Under limit (currentSpend + amount <= limit): records and returns `allowed: true`
+   * - Would exceed: does NOT record (rejected spends don't consume budget)
    */
   check(params) {
-    const { key, maxCalls, windowMs } = params;
+    const { key, amount, limit, windowMs } = params;
     const now = this.now();
     const windowStart = now - windowMs;
+    if (!Number.isFinite(amount) || amount < 0) {
+      const existing = this.buckets.get(key);
+      const activeEntries = existing ? existing.entries.filter((e) => e.timestamp > windowStart) : [];
+      const currentSpend2 = activeEntries.reduce((sum, e) => sum + e.amount, 0);
+      const oldest = activeEntries[0];
+      return {
+        allowed: false,
+        currentSpend: currentSpend2,
+        limit,
+        windowMs,
+        resetAtMs: oldest ? oldest.timestamp + windowMs : 0,
+        reason: "invalid_amount"
+      };
+    }
     let bucket = this.buckets.get(key);
     if (!bucket) {
-      bucket = { timestamps: [], maxCalls, windowMs };
+      bucket = { entries: [], limit, currency: "", windowMs };
       this.buckets.set(key, bucket);
     }
-    bucket.maxCalls = maxCalls;
+    bucket.limit = limit;
     bucket.windowMs = windowMs;
-    bucket.timestamps = bucket.timestamps.filter((ts) => ts > windowStart);
-    if (bucket.timestamps.length >= maxCalls) {
-      const oldest = bucket.timestamps[0] ?? 0;
+    bucket.entries = bucket.entries.filter((e) => e.timestamp > windowStart);
+    const currentSpend = bucket.entries.reduce((sum, e) => sum + e.amount, 0);
+    if (currentSpend + amount > limit) {
+      const oldest = bucket.entries[0];
       return {
         allowed: false,
-        current: bucket.timestamps.length,
-        limit: maxCalls,
+        currentSpend,
+        limit,
         windowMs,
-        resetAtMs: oldest + windowMs
+        resetAtMs: oldest ? oldest.timestamp + windowMs : 0
       };
     }
-    bucket.timestamps.push(now);
-    const current = bucket.timestamps.length;
-    const resetAtMs = (bucket.timestamps[0] ?? now) + windowMs;
-    if (this.onWarning && current / maxCalls >= this.warningThreshold) {
-      this.safeWarn({ key, current, limit: maxCalls, window_ms: windowMs, reset_at_ms: resetAtMs });
+    bucket.entries.push({ timestamp: now, amount });
+    const newSpend = currentSpend + amount;
+    const resetAtMs = (bucket.entries[0]?.timestamp ?? now) + windowMs;
+    if (this.onWarning && newSpend / limit >= this.warningThreshold) {
+      this.safeWarn({
+        key,
+        current_spend: newSpend,
+        limit,
+        currency: bucket.currency,
+        window_ms: windowMs,
+        reset_at_ms: resetAtMs
+      });
     }
     return {
       allowed: true,
-      current,
-      limit: maxCalls,
+      currentSpend: newSpend,
+      limit,
       windowMs,
       resetAtMs
     };
   }
   /**
-   * Unconditionally record a call against the rate limit.
+   * Unconditionally record a spend against the limit.
    *
-   * Unlike check(), this always appends the timestamp — even when the bucket
-   * is already at/over the limit — because the call it represents has already
-   * executed. The sideband splits decision from execution: /evaluate peeks
-   * (non-destructive), and /audit calls record() once the external call ran,
-   * so refusing to record at the limit (as check() does) would let real calls
-   * escape accounting and under-count subsequent peeks. (issue #12, D3.)
+   * Unlike check(), this always appends the amount — even when it pushes the
+   * window past the limit — because the spend it represents has already been
+   * incurred. The sideband peeks at /evaluate and commits here at /audit once
+   * the external call ran (issue #12, D3).
    *
-   * Warnings fire only while the post-append count stays within the limit —
-   * exact parity with check(), which never warns on its over-limit path — so a
-   * burst of over-limit audits cannot flood the dashboard's limit_warning feed.
+   * Throws on a negative or non-finite amount: such amounts are rejected at
+   * /evaluate, so one reaching record() is a logic bug we surface loudly rather
+   * than silently corrupt the sliding-window sum. Warnings fire only while the
+   * post-append spend stays within the limit (parity with check()).
    */
   record(params) {
-    const { key, maxCalls, windowMs } = params;
+    const { key, amount, limit, windowMs } = params;
+    if (!Number.isFinite(amount) || amount < 0) {
+      throw new RangeError(
+        `SpendLimiter.record() received an invalid amount (${String(amount)}); invalid amounts must be rejected at /evaluate, never committed`
+      );
+    }
     const now = this.now();
     const windowStart = now - windowMs;
     let bucket = this.buckets.get(key);
     if (!bucket) {
-      bucket = { timestamps: [], maxCalls, windowMs };
+      bucket = { entries: [], limit, currency: "", windowMs };
       this.buckets.set(key, bucket);
     }
-    bucket.maxCalls = maxCalls;
+    bucket.limit = limit;
     bucket.windowMs = windowMs;
-    bucket.timestamps = bucket.timestamps.filter((ts) => ts > windowStart);
-    bucket.timestamps.push(now);
-    const current = bucket.timestamps.length;
-    const resetAtMs = (bucket.timestamps[0] ?? now) + windowMs;
-    if (this.onWarning && current <= maxCalls && current / maxCalls >= this.warningThreshold) {
-      this.safeWarn({ key, current, limit: maxCalls, window_ms: windowMs, reset_at_ms: resetAtMs });
+    bucket.entries = bucket.entries.filter((e) => e.timestamp > windowStart);
+    bucket.entries.push({ timestamp: now, amount });
+    const currentSpend = bucket.entries.reduce((sum, e) => sum + e.amount, 0);
+    const resetAtMs = (bucket.entries[0]?.timestamp ?? now) + windowMs;
+    if (this.onWarning && currentSpend <= limit && currentSpend / limit >= this.warningThreshold) {
+      this.safeWarn({
+        key,
+        current_spend: currentSpend,
+        limit,
+        currency: bucket.currency,
+        window_ms: windowMs,
+        reset_at_ms: resetAtMs
+      });
     }
     return {
-      allowed: current <= maxCalls,
-      current,
-      limit: maxCalls,
+      allowed: currentSpend <= limit,
+      currentSpend,
+      limit,
       windowMs,
       resetAtMs
     };
   }
   /**
-   * Check the rate limit without recording the call (non-destructive).
+   * Check the spend limit without recording the spend (non-destructive).
    *
    * Used by dry-run mode to determine what would happen without consuming
-   * a slot in the bucket.
+   * budget in the bucket.
    */
   peek(params) {
-    const { key, maxCalls, windowMs } = params;
+    const { key, amount, limit, windowMs } = params;
     const now = this.now();
     const windowStart = now - windowMs;
     const bucket = this.buckets.get(key);
+    if (!Number.isFinite(amount) || amount < 0) {
+      const activeEntries2 = bucket ? bucket.entries.filter((e) => e.timestamp > windowStart) : [];
+      const currentSpend2 = activeEntries2.reduce((sum, e) => sum + e.amount, 0);
+      const oldest2 = activeEntries2[0];
+      return {
+        allowed: false,
+        currentSpend: currentSpend2,
+        limit,
+        windowMs,
+        resetAtMs: oldest2 ? oldest2.timestamp + windowMs : 0,
+        reason: "invalid_amount"
+      };
+    }
     if (!bucket) {
+      const wouldExceed = amount > limit;
       return {
-        allowed: true,
-        current: 1,
-        limit: maxCalls,
+        allowed: !wouldExceed,
+        currentSpend: wouldExceed ? 0 : amount,
+        limit,
         windowMs,
         resetAtMs: now + windowMs
       };
     }
-    const activeCount = bucket.timestamps.filter((ts) => ts > windowStart).length;
-    if (activeCount >= maxCalls) {
-      const oldest2 = bucket.timestamps.find((ts) => ts > windowStart) ?? 0;
+    const activeEntries = bucket.entries.filter((e) => e.timestamp > windowStart);
+    const currentSpend = activeEntries.reduce((sum, e) => sum + e.amount, 0);
+    if (currentSpend + amount > limit) {
+      const oldest2 = activeEntries[0];
       return {
         allowed: false,
-        current: activeCount,
-        limit: maxCalls,
+        currentSpend,
+        limit,
         windowMs,
-        resetAtMs: oldest2 + windowMs
+        resetAtMs: oldest2 ? oldest2.timestamp + windowMs : 0
       };
     }
-    const oldest = bucket.timestamps.find((ts) => ts > windowStart) ?? now;
+    const newSpend = currentSpend + amount;
+    const oldest = activeEntries[0];
     return {
       allowed: true,
-      current: activeCount + 1,
-      limit: maxCalls,
+      currentSpend: newSpend,
+      limit,
       windowMs,
-      resetAtMs: oldest + windowMs
+      resetAtMs: oldest ? oldest.timestamp + windowMs : now + windowMs
     };
   }
+  /**
+   * Set the display currency for a key. Called by the governed forwarder
+   * after check() so dashboard reads include the currency label.
+   */
+  setCurrency(key, currency) {
+    const bucket = this.buckets.get(key);
+    if (bucket) bucket.currency = currency;
+  }
   // -------------------------------------------------------------------------
   // Read operations (for dashboard API)
   // -------------------------------------------------------------------------
@@ -6209,17 +6563,19 @@ var RateLimiter = class {
     const bucket = this.buckets.get(key);
     if (!bucket) return void 0;
     const windowStart = this.now() - bucket.windowMs;
-    bucket.timestamps = bucket.timestamps.filter((ts) => ts > windowStart);
-    if (bucket.timestamps.length === 0) {
+    bucket.entries = bucket.entries.filter((e) => e.timestamp > windowStart);
+    if (bucket.entries.length === 0) {
       this.buckets.delete(key);
       return void 0;
     }
+    const currentSpend = bucket.entries.reduce((sum, e) => sum + e.amount, 0);
     return {
       key,
-      current: bucket.timestamps.length,
-      limit: bucket.maxCalls,
+      current_spend: currentSpend,
+      limit: bucket.limit,
+      currency: bucket.currency,
       window_ms: bucket.windowMs,
-      reset_at_ms: (bucket.timestamps[0] ?? 0) + bucket.windowMs
+      reset_at_ms: (bucket.entries[0]?.timestamp ?? 0) + bucket.windowMs
     };
   }
   /** List all tracked keys with their current state. */
@@ -6234,43 +6590,62 @@ var RateLimiter = class {
   // -------------------------------------------------------------------------
   // Maintenance
   // -------------------------------------------------------------------------
-  /** Sweep all buckets: remove expired timestamps, delete empty buckets. */
+  /** Sweep all buckets: remove expired entries, delete empty buckets. */
   cleanup() {
     const now = this.now();
     for (const [key, bucket] of this.buckets) {
       const windowStart = now - bucket.windowMs;
-      bucket.timestamps = bucket.timestamps.filter((ts) => ts > windowStart);
-      if (bucket.timestamps.length === 0) {
+      bucket.entries = bucket.entries.filter((e) => e.timestamp > windowStart);
+      if (bucket.entries.length === 0) {
         this.buckets.delete(key);
       }
     }
   }
-  /** Clear all rate limit state. Called on policy hot-reload. */
+  /** Clear all spend limit state. Called on policy hot-reload. */
   reset() {
     this.buckets.clear();
   }
   /**
-   * Reconcile bucket state against a new policy's limit configuration.
+   * Reconcile bucket state against a new policy's spend configuration.
    *
    * Walks every existing bucket and checks whether its last-seen
-   * `{ maxCalls, windowMs }` tuple still appears anywhere in `validConfigs`.
-   * Buckets whose config is still present are left untouched — counters and
-   * elapsed-window progress are preserved across hot-reloads. Buckets whose
-   * config is gone (rule changed or removed) are evicted so the next check
-   * lazy-creates a fresh bucket under the new config.
+   * `{ limit, currency, windowMs }` tuple still appears in `validConfigs`.
+   * Buckets whose config is unchanged are left untouched — cumulative spend
+   * and elapsed-window progress are preserved across hot-reloads. Buckets
+   * whose config is gone (rule changed or removed) are evicted so the next
+   * check lazy-creates a fresh bucket under the new config.
    *
-   * This is the compare-and-evict semantic that replaces the old `reset()`
-   * call on every hot-reload, which wiped all state even when the matching
-   * rule was unchanged.
+   * Keys built by `ruleBucketKey` (bucket-key.ts) carry the owning rule's
+   * index, and for those the tuple must match at THAT index (`config.ruleIndex`): a
+   * reorder that shifts a spend rule's index evicts its old-index bucket
+   * instead of leaving an orphan no rule reads again — or worse, letting
+   * whatever rule now sits at that index adopt another rule's accrued spend.
+   * Un-suffixed keys keep the tuple-anywhere match, but only against
+   * index-less configs — a caller that passes only indexed configs (as the
+   * proxy does) evicts every un-suffixed bucket, fail-closed.
+   *
+   * Currency is part of the tuple because a USD→EUR switch is a meaningful
+   * policy change — the same numeric limit buys a different amount of real
+   * spend, so the bucket must reset. This replaces the old `reset()` call
+   * on every hot-reload, which wiped all state even when the matching rule
+   * was unchanged.
    */
   reconcile(validConfigs) {
     const valid = /* @__PURE__ */ new Set();
+    const byIndex = /* @__PURE__ */ new Map();
     for (const config of validConfigs) {
-      valid.add(`${String(config.maxCalls)}|${String(config.windowMs)}`);
+      const tuple = `${String(config.limit)}|${config.currency}|${String(config.windowMs)}`;
+      if (config.ruleIndex === void 0) {
+        valid.add(tuple);
+      } else {
+        byIndex.set(config.ruleIndex, tuple);
+      }
     }
     for (const [key, bucket] of this.buckets) {
-      const tuple = `${String(bucket.maxCalls)}|${String(bucket.windowMs)}`;
-      if (!valid.has(tuple)) {
+      const tuple = `${String(bucket.limit)}|${bucket.currency}|${String(bucket.windowMs)}`;
+      const ruleIndex = parseRuleIndex(key);
+      const survives = ruleIndex === void 0 ? valid.has(tuple) : byIndex.get(ruleIndex) === tuple;
+      if (!survives) {
         this.buckets.delete(key);
       }
     }
@@ -6350,14 +6725,18 @@ var BudgetEngine = class {
   /**
    * Resolve which budgets a call feeds and how much it charges each.
    *
-   * A contributor participates when its tool glob matches the tool name AND
-   * every `match.input` condition holds (absent conditions means the glob
-   * alone decides); the FIRST participating contributor (config order, over
-   * that combined predicate) supplies the amount field. A call that matches
-   * the glob but not the conditions simply does not feed the budget — no
-   * charge, no failure. Once a contributor is selected, a missing,
-   * non-numeric, negative, or non-finite amount fails closed as a `failures`
-   * entry — the caller must deny the call.
+   * A contributor participates when its upstream scope admits the call's
+   * door (absent scope admits every door; a scoped contributor never
+   * participates when `ctx.upstream` is null — sideband, singular mode) AND
+   * its tool glob matches the tool name AND every `match.input` condition
+   * holds (absent conditions means the glob alone decides); the FIRST
+   * participating contributor (config order, over that combined predicate)
+   * supplies the amount field. A call that matches the glob but not the
+   * conditions or the scope simply does not feed the budget — no charge, no
+   * failure — and a later contributor may still participate. Once a
+   * contributor is selected, a missing, non-numeric, negative, or non-finite
+   * amount fails closed as a `failures` entry — the caller must deny the
+   * call.
    */
   resolveCharges(ctx) {
     const charges = [];
@@ -6368,7 +6747,7 @@ var BudgetEngine = class {
     };
     for (const budget of this.budgets.values()) {
       const contributor = budget.contributors.find(
-        (c) => c.match.tool.test(ctx.toolName) && (c.match.input === void 0 || matchInput(c.match.input, matchCtx))
+        (c) => (c.upstreams === void 0 || ctx.upstream !== null && c.upstreams.includes(ctx.upstream)) && c.match.tool.test(ctx.toolName) && (c.match.input === void 0 || matchInput(c.match.input, matchCtx))
       );
       if (!contributor) continue;
       const raw = resolvePath(contributor.field, ctx.toolArguments ?? {});
@@ -6393,7 +6772,8 @@ var BudgetEngine = class {
         budget,
         bucketKey: this.bucketKey(budget, ctx),
         amount: raw,
-        generation: this.generations.get(budget.name) ?? 0
+        generation: this.generations.get(budget.name) ?? 0,
+        ...ctx.upstream !== null && { upstream: ctx.upstream }
       });
     }
     return { charges, failures };
@@ -6473,7 +6853,8 @@ var BudgetEngine = class {
           remaining: snapshot.remaining,
           limit: charge.budget.limit,
           currency: charge.budget.currency,
-          utilization: snapshot.spent / charge.budget.limit
+          utilization: snapshot.spent / charge.budget.limit,
+          upstream: charge.upstream ?? null
         });
       } catch (err) {
         console.error("[helio] budget onCommit subscriber threw:", err);
@@ -6499,7 +6880,8 @@ var BudgetEngine = class {
           attempted_amount: entry.amount,
           spent: entry.spent,
           limit: entry.budget.limit,
-          currency: entry.budget.currency
+          currency: entry.budget.currency,
+          upstream: entry.upstream
         });
       } catch (err) {
         console.error("[helio] budget onBreach subscriber threw:", err);
@@ -6809,7 +7191,8 @@ var BudgetEngine = class {
       allowed: checkedAgainst + charge.amount <= charge.budget.limit,
       spent,
       remaining: Math.max(0, charge.budget.limit - spent),
-      resetAtMs
+      resetAtMs,
+      upstream: charge.upstream ?? null
     };
   }
 };
@@ -6839,6 +7222,14 @@ import Database from "better-sqlite3";
 import { randomUUID as randomUUID3 } from "crypto";
 import { chmodSync } from "fs";
 
+// src/startup-error.ts
+var StartupError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StartupError";
+  }
+};
+
 // src/upstream/response-summary.ts
 function extractResponseSummary(body) {
   if (body == null || typeof body !== "object") {
@@ -6933,7 +7324,8 @@ CREATE TABLE IF NOT EXISTS audit_records (
   origin            TEXT NOT NULL DEFAULT 'mcp',
   metadata          TEXT,
   protocol_version  TEXT,
-  created_at        TEXT NOT NULL
+  created_at        TEXT NOT NULL,
+  upstream          TEXT
 );
 `;
 var CREATE_INDEX_DDL = `
@@ -6945,6 +7337,7 @@ CREATE INDEX IF NOT EXISTS idx_audit_block_reason     ON audit_records (block_re
 CREATE INDEX IF NOT EXISTS idx_audit_upstream_status_created_at ON audit_records (upstream_http_status, created_at);
 CREATE INDEX IF NOT EXISTS idx_audit_record_kind     ON audit_records (record_kind);
 CREATE INDEX IF NOT EXISTS idx_audit_origin          ON audit_records (origin);
+CREATE INDEX IF NOT EXISTS idx_audit_upstream        ON audit_records (upstream);
 `;
 var INSERT_SQL = `
 INSERT INTO audit_records (
@@ -6953,14 +7346,16 @@ INSERT INTO audit_records (
   approved_by, upstream_response, upstream_error, upstream_latency_ms,
   upstream_http_status,
   total_duration_ms, approval_wait_ms, proxy_compute_ms,
-  flagged_destructive, dry_run, record_kind, origin, metadata, protocol_version, created_at
+  flagged_destructive, dry_run, record_kind, origin, metadata, protocol_version, created_at,
+  upstream
 ) VALUES (
   @id, @timestamp, @session_id, @session_source, @agent_id, @environment, @tool_name, @tool_input,
   @policy_decision, @block_reason, @matched_rule, @matched_rule_index, @evidence_chain, @approval_status,
   @approved_by, @upstream_response, @upstream_error, @upstream_latency_ms,
   @upstream_http_status,
   @total_duration_ms, @approval_wait_ms, @proxy_compute_ms,
-  @flagged_destructive, @dry_run, @record_kind, @origin, @metadata, @protocol_version, @created_at
+  @flagged_destructive, @dry_run, @record_kind, @origin, @metadata, @protocol_version, @created_at,
+  @upstream
 )
 `;
 var REQUIRED_AUDIT_COLUMNS = [
@@ -6979,7 +7374,11 @@ var REQUIRED_AUDIT_COLUMNS = [
   "session_source",
   // Same clean break, same unreleased cycle (issue #219): released users see
   // ONE break, at v0.12.0.
-  "protocol_version"
+  "protocol_version",
+  // The one ratified exception to the clean break (issue #292): a
+  // v0.12.0-complete database missing ONLY this column is migrated in place
+  // by migrateAuditUpstreamColumn instead of failing the assertion.
+  "upstream"
 ];
 function deserializeRow(row) {
   return {
@@ -7011,6 +7410,7 @@ function deserializeRow(row) {
     origin: row.origin,
     metadata: row.metadata ? JSON.parse(row.metadata) : null,
     protocol_version: row.protocol_version,
+    upstream: row.upstream,
     created_at: row.created_at
   };
 }
@@ -7052,6 +7452,14 @@ function buildWhereClause(filters) {
     conditions.push("session_id = ?");
     params.push(filters.session_id);
   }
+  if (filters.session_source !== void 0) {
+    conditions.push("session_source = ?");
+    params.push(filters.session_source);
+  }
+  if (filters.upstream !== void 0) {
+    conditions.push("upstream = ?");
+    params.push(filters.upstream);
+  }
   if (filters.agent_id !== void 0) {
     conditions.push("agent_id = ?");
     params.push(filters.agent_id);
@@ -7083,6 +7491,22 @@ function buildWhereClause(filters) {
   const clause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   return { clause, params };
 }
+function migrateAuditUpstreamColumn(db) {
+  const probe = () => {
+    const rows = db.pragma("table_info(audit_records)");
+    return new Set(rows.map((row) => row.name));
+  };
+  const existing = probe();
+  const missing = REQUIRED_AUDIT_COLUMNS.filter((name) => !existing.has(name));
+  if (missing.length !== 1 || missing[0] !== "upstream") return false;
+  try {
+    db.exec("ALTER TABLE audit_records ADD COLUMN upstream TEXT");
+  } catch (err) {
+    if (probe().has("upstream")) return false;
+    throw err;
+  }
+  return true;
+}
 function restrictAuditFilePerms(dbPath) {
   if (dbPath === ":memory:" || process.platform === "win32") return;
   try {
@@ -7111,6 +7535,9 @@ var AuditStore = class {
     this.retentionMs = parseDuration(options.retention);
     this.includeResponses = options.includeResponses;
     this.db.exec(CREATE_TABLE_DDL);
+    if (migrateAuditUpstreamColumn(this.db)) {
+      console.error('[helio] Audit DB migrated: added column "upstream"');
+    }
     this.assertRequiredSchema(options.path);
     this.db.exec(CREATE_INDEX_DDL);
     this.insertStmt = this.db.prepare(INSERT_SQL);
@@ -7176,7 +7603,7 @@ var AuditStore = class {
     const missing = REQUIRED_AUDIT_COLUMNS.filter((name) => !existing.has(name));
     if (missing.length === 0) return;
     const quotedColumns = missing.map((name) => `"${name}"`).join(", ");
-    throw new Error(
+    throw new StartupError(
       `[helio] Audit DB schema mismatch: missing required columns ${quotedColumns}. This local database was created by an older Helio build. Delete "${dbPath}", "${dbPath}-wal", and "${dbPath}-shm", then restart Helio.`
     );
   }
@@ -7219,6 +7646,7 @@ var AuditStore = class {
       origin: record.origin,
       metadata: record.metadata ? JSON.stringify(record.metadata) : null,
       protocol_version: record.protocol_version,
+      upstream: record.upstream ?? null,
       created_at: now
     });
     return resolvedId;
@@ -7294,9 +7722,14 @@ var AuditStore = class {
     const result = this.db.prepare(`SELECT COUNT(*) as total FROM audit_records ${clause}`).get(...params);
     return result.total;
   }
-  /** Get aggregate statistics for a time range. */
-  aggregate(from, to) {
-    const rangeFilters = { from, to };
+  /**
+   * Get aggregate statistics for a time range. The optional upstream filter
+   * scopes EVERY sub-aggregate (totals, by_decision, by_block_reason,
+   * top_tools, approval_rate, per_hour) — "analytics for this door", not one
+   * filtered chart. Exact match: null-upstream rows never match any value.
+   */
+  aggregate(from, to, filters = {}) {
+    const rangeFilters = { from, to, upstream: filters.upstream };
     const { clause, params } = buildWhereClause(rangeFilters);
     const totals = this.db.prepare(
       `SELECT
@@ -7322,9 +7755,9 @@ var AuditStore = class {
     ).all(...params);
     const toolsClause = clause ? `${clause} AND policy_decision NOT IN ${NON_TOOL_DECISIONS_SQL}` : `WHERE policy_decision NOT IN ${NON_TOOL_DECISIONS_SQL}`;
     const top_tools = this.db.prepare(
-      `SELECT tool_name, COUNT(*) as count
+      `SELECT tool_name, upstream, COUNT(*) as count
          FROM audit_records ${toolsClause}
-         GROUP BY tool_name
+         GROUP BY tool_name, upstream
          ORDER BY count DESC
          LIMIT 10`
     ).all(...params);
@@ -7408,10 +7841,11 @@ var CSV_HEADERS = [
   "record_kind",
   "origin",
   "metadata",
-  // Appended LAST (issues #218, #219): positional consumers of the existing
-  // columns keep working — new columns always go at the end.
+  // Appended LAST (issues #218, #219, #292): positional consumers of the
+  // existing columns keep working — new columns always go at the end.
   "session_source",
-  "protocol_version"
+  "protocol_version",
+  "upstream"
 ];
 var FORMULA_PREFIXES = /^[=+\-@\t\r]/;
 function csvEscape(value) {
@@ -7454,7 +7888,10 @@ var BUDGET_EVENT_CSV_HEADERS = [
   "audit_record_id",
   "timestamp",
   "timestamp_ms",
-  "created_at"
+  "created_at",
+  // Appended LAST (issue #292): positional consumers of the existing
+  // columns keep working — new columns always go at the end.
+  "upstream"
 ];
 function eventToRow(event) {
   return BUDGET_EVENT_CSV_HEADERS.map((h) => {
@@ -8285,7 +8722,9 @@ var GovernanceService = class {
         toolName,
         toolArguments: req.arguments,
         sessionId: budgetSessionGate.ok ? budgetSessionGate.session : null,
-        senderId
+        senderId,
+        upstream: null
+        // a sideband call has no upstream (issue #295)
       });
       const gatedCharges = charges.length > 0 || failures.length > 0 ? gateBudgetCharges({ charges, failures }, budgetSessionGate) : void 0;
       if (gatedCharges && !gatedCharges.ok) {
@@ -9007,11 +9446,12 @@ var GovernanceService = class {
     };
   }
   planRate(decision, toolName, sessionId, senderId) {
-    const limits = decision.matchedRule?.limits;
-    if (!this.rateLimiter || !limits?.maxCalls || !limits.windowMs) {
+    const matchedRule = decision.matchedRule;
+    const limits = matchedRule?.limits;
+    if (!this.rateLimiter || !matchedRule || !limits?.maxCalls || !limits.windowMs) {
       return { allowed: true };
     }
-    let key;
+    let baseKey;
     if (limits.key === "session") {
       const gate = gateSession(sessionId, this.session.onUnresolved);
       if (!gate.ok) {
@@ -9019,10 +9459,11 @@ var GovernanceService = class {
         return { allowed: false, sessionUnresolved: true };
       }
       if (gate.anonymous) warnAnonymousPoolingOnce();
-      key = sessionLimitKey(gate.session);
+      baseKey = sessionLimitKey(gate.session);
     } else {
-      key = buildLimitKey(limits.key, toolName, senderId);
+      baseKey = buildLimitKey(limits.key, toolName, senderId);
     }
+    const key = ruleBucketKey(baseKey, matchedRule.index);
     const peek = this.rateLimiter.peek({
       key,
       maxCalls: limits.maxCalls,
@@ -9054,7 +9495,7 @@ var GovernanceService = class {
     } else {
       baseKey = buildLimitKey(maxSpend.key, toolName, senderId);
     }
-    const key = spendBucketKey(baseKey, decision.matchedRule.index);
+    const key = ruleBucketKey(baseKey, decision.matchedRule.index);
     const rawAmount = resolvePath(maxSpend.field, args ?? {});
     if (typeof rawAmount !== "number" || !Number.isFinite(rawAmount) || rawAmount < 0) {
       return { allowed: false, block: { reason: "invalid_amount", limit: maxSpend.limit } };
@@ -9213,7 +9654,9 @@ var GovernanceService = class {
       origin: args.origin,
       metadata: args.metadata,
       // The sideband has no MCP wire, so no protocol claim exists.
-      protocol_version: null
+      protocol_version: null,
+      // No door on the sideband either: upstream attribution is MCP-only.
+      upstream: null
     };
     const isEnforcement = args.recordKind === "evaluation_expired" || blockReason !== null || args.approvalStatus != null;
     if (isEnforcement) this.auditWriter.pushImmediate(record, id);
@@ -9278,7 +9721,7 @@ function buildLimitKey(keyType, toolName, senderId) {
     case "agent":
     case "tool":
     default:
-      return `tool:${toolName}`;
+      return toolLimitKey(toolName);
   }
 }
 function senderIdOf(metadata) {
@@ -9477,7 +9920,7 @@ var AuditWriter = class {
 };
 
 // src/audit/header-mismatch.ts
-function buildHeaderMismatchAuditRecord(rejection, environment) {
+function buildHeaderMismatchAuditRecord(rejection, environment, upstream) {
   return {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     session_id: rejection.session?.id ?? null,
@@ -9514,7 +9957,10 @@ function buildHeaderMismatchAuditRecord(rejection, environment) {
     record_kind: "tool_call",
     origin: "mcp",
     metadata: null,
-    protocol_version: rejection.protocolVersion ?? null
+    protocol_version: rejection.protocolVersion ?? null,
+    // The door context lives with the caller (the composition root), not
+    // the rejection payload; singular composition passes nothing.
+    upstream: upstream ?? null
   };
 }
 
@@ -9556,6 +10002,9 @@ var ApprovalQueue = class {
       rule_index: params.rule_index,
       channel_name: params.channel_name,
       session_id: params.session_id,
+      // Wire-darkness spelling: set only when attributed, never null.
+      ...params.session_source != null && { session_source: params.session_source },
+      ...params.upstream != null && { upstream: params.upstream },
       requested_at: new Date(now).toISOString(),
       timeout_at: new Date(now + params.timeout_ms).toISOString(),
       timeout_ms: params.timeout_ms,
@@ -9675,6 +10124,8 @@ var ApprovalRouter = class {
       rule_index: rule?.index ?? null,
       channel_name: channelName,
       session_id: params.session_id,
+      session_source: params.session_source,
+      upstream: params.upstream,
       timeout_ms: timeoutMs,
       breached_budgets: params.breached_budgets
     });
@@ -9771,6 +10222,10 @@ var ApprovalRouter = class {
       rule_index: rule?.index ?? null,
       channel_name: `${NATIVE_CHANNEL_PREFIX}${params.origin}`,
       session_id: params.session_id,
+      // Adapter-supplied ids are sideband-attributed by definition (issue
+      // #251); deriving it at this single choke point means no future
+      // adapter can forget it. Upstream stays absent: no MCP door here.
+      session_source: params.session_id != null ? "sideband" : null,
       timeout_ms: timeoutMs,
       breached_budgets: params.breached_budgets
     });
@@ -9940,15 +10395,22 @@ function buildApprovalBlocks(ticket) {
   const safeName = sanitizeCodeSpanContent(ticket.tool_name);
   const rawInput = truncate(JSON.stringify(ticket.tool_input), MAX_INPUT_LENGTH);
   const safeInput = sanitizeForCodeBlock(rawInput);
-  const detailLines = [`*Tool:* \`${safeName}\``, `*Input:*
+  const detailLines = [`*Tool:* \`${safeName}\``];
+  if (ticket.upstream) {
+    detailLines.push(`*Upstream:* \`${sanitizeCodeSpanContent(ticket.upstream)}\``);
+  }
+  detailLines.push(`*Input:*
 \`\`\`
 ${safeInput}
-\`\`\``];
+\`\`\``);
   if (ticket.matched_rule) {
     detailLines.push(`*Rule:* ${sanitizeMrkdwnText(ticket.matched_rule)}`);
   }
   if (ticket.session_id) {
-    detailLines.push(`*Session:* \`${sanitizeCodeSpanContent(ticket.session_id)}\``);
+    const sessionLine = `*Session:* \`${sanitizeCodeSpanContent(ticket.session_id)}\``;
+    detailLines.push(
+      ticket.session_source ? `${sessionLine} (${sanitizeMrkdwnText(ticket.session_source)})` : sessionLine
+    );
   }
   const budgetBlocks = buildBudgetBlocks(ticket);
   return [
@@ -10658,7 +11120,13 @@ var clampedQueryInt = (fallback, min, max) => z8.preprocess(
 );
 var feedQuerySchema = z8.object({
   limit: clampedQueryInt(50, 1, 200),
-  offset: clampedQueryInt(0, 0, Number.MAX_SAFE_INTEGER)
+  offset: clampedQueryInt(0, 0, Number.MAX_SAFE_INTEGER),
+  // The feed's server-side filters (issues #292, #316): attribution and
+  // session identity source must narrow the fetch window itself, because
+  // slicing an unfiltered newest-N window client-side would miss rare
+  // matches on a busy stream.
+  upstream: optionalQueryString,
+  session_source: optionalQueryString
 });
 var auditExportQuerySchema = z8.object({
   format: z8.preprocess((value) => value === "csv" ? "csv" : "json", z8.enum(["json", "csv"])),
@@ -10677,7 +11145,9 @@ var auditExportQuerySchema = z8.object({
   origin: optionalQueryString,
   record_kind: optionalQueryString,
   channel_id: optionalQueryString,
-  sender_id: optionalQueryString
+  sender_id: optionalQueryString,
+  upstream: optionalQueryString,
+  session_source: optionalQueryString
 });
 var auditQuerySchema = z8.object({
   limit: clampedQueryInt(50, 1, LIST_MAX_PAGE_SIZE),
@@ -10697,7 +11167,9 @@ var auditQuerySchema = z8.object({
   origin: optionalQueryString,
   record_kind: optionalQueryString,
   channel_id: optionalQueryString,
-  sender_id: optionalQueryString
+  sender_id: optionalQueryString,
+  upstream: optionalQueryString,
+  session_source: optionalQueryString
 });
 var budgetEventsQuerySchema = z8.object({
   limit: clampedQueryInt(50, 1, LIST_MAX_PAGE_SIZE),
@@ -10709,7 +11181,8 @@ var budgetEventsExportQuerySchema = z8.object({
 });
 var analyticsQuerySchema = z8.object({
   from: optionalQueryString,
-  to: optionalQueryString
+  to: optionalQueryString,
+  upstream: optionalQueryString
 });
 var authSessionBodySchema = z8.object({
   secret: z8.string()
@@ -10770,6 +11243,8 @@ function isPrivateIpv4(host) {
   if (a > 255 || b > 255 || c > 255 || d > 255) return false;
   return a === 10 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168;
 }
+var MAX_SSE_CONNECTIONS = 256;
+var REFUSAL_LOG_WINDOW_MS2 = 1e4;
 function createDashboardAppWithLifecycle(deps, options) {
   const {
     auditStore,
@@ -10906,7 +11381,10 @@ function createDashboardAppWithLifecycle(deps, options) {
     const query = feedQuerySchema.parse(c.req.query());
     const limit = query.limit;
     const offset = query.offset;
-    const result = auditStore.list({}, { limit, offset, order: "desc" });
+    const result = auditStore.list(
+      { upstream: query.upstream, session_source: query.session_source },
+      { limit, offset, order: "desc" }
+    );
     return c.json({
       data: result.records,
       total: result.total,
@@ -10933,7 +11411,9 @@ function createDashboardAppWithLifecycle(deps, options) {
       origin: query.origin,
       record_kind: query.record_kind,
       channel_id: query.channel_id,
-      sender_id: query.sender_id
+      sender_id: query.sender_id,
+      upstream: query.upstream,
+      session_source: query.session_source
     };
     const result = auditStore.listForExport(filters, limit);
     if (format === "csv") {
@@ -10979,7 +11459,9 @@ function createDashboardAppWithLifecycle(deps, options) {
       origin: query.origin,
       record_kind: query.record_kind,
       channel_id: query.channel_id,
-      sender_id: query.sender_id
+      sender_id: query.sender_id,
+      upstream: query.upstream,
+      session_source: query.session_source
     };
     const result = auditStore.list(filters, { limit, offset, order: "desc" });
     return c.json({
@@ -11045,7 +11527,7 @@ function createDashboardAppWithLifecycle(deps, options) {
     const defaultFrom = new Date(now.getTime() - 24 * 60 * 60 * 1e3).toISOString();
     const from = query.from ?? defaultFrom;
     const to = query.to ?? now.toISOString();
-    const stats = auditStore.aggregate(from, to);
+    const stats = auditStore.aggregate(from, to, { upstream: query.upstream });
     return c.json(stats);
   });
   app.get("/api/evidence/:session_id", (c) => {
@@ -11057,17 +11539,22 @@ function createDashboardAppWithLifecycle(deps, options) {
   let closed = false;
   const heartbeatMs = Math.max(options?.sseHeartbeatMs ?? 3e4, 1e3);
   const staleThresholdMs = heartbeatMs * 3;
-  const sweepIntervalMs = Math.max(heartbeatMs * 2, 1e4);
-  const sweepInterval = setInterval(() => {
-    const now = Date.now();
-    for (const [id, conn] of activeConnections) {
-      if (now - conn.lastWrite > staleThresholdMs) {
-        conn.cleanup();
-        activeConnections.delete(id);
+  const sweepIntervalMs = options?.sweepIntervalMs ?? Math.max(heartbeatMs * 2, 1e4);
+  const maxSseConnections = options?.maxSseConnections ?? MAX_SSE_CONNECTIONS;
+  let sweepInterval;
+  if (sweepIntervalMs > 0) {
+    sweepInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [id, conn] of activeConnections) {
+        if (now - conn.lastWrite > staleThresholdMs) {
+          conn.cleanup();
+          conn.sever();
+          activeConnections.delete(id);
+        }
       }
-    }
-  }, sweepIntervalMs);
-  sweepInterval.unref();
+    }, sweepIntervalMs);
+    sweepInterval.unref();
+  }
   const close = () => {
     if (closed) return;
     closed = true;
@@ -11077,7 +11564,22 @@ function createDashboardAppWithLifecycle(deps, options) {
     }
     activeConnections.clear();
   };
+  let refusalCount = 0;
+  let lastRefusalLogAt = null;
+  const logRefusal = () => {
+    refusalCount += 1;
+    const now = Date.now();
+    if (lastRefusalLogAt !== null && now - lastRefusalLogAt < REFUSAL_LOG_WINDOW_MS2) return;
+    lastRefusalLogAt = now;
+    console.error(
+      `[helio] /api/events at connection cap (${String(maxSseConnections)}); refusing new streams (${String(refusalCount)} refusals so far).`
+    );
+  };
   app.get("/api/events", (c) => {
+    if (activeConnections.size >= maxSseConnections) {
+      logRefusal();
+      return c.json({ error: "connection capacity reached" }, 503);
+    }
     return streamSSE(c, async (stream) => {
       if (closed) return;
       const connId = randomUUID8();
@@ -11098,7 +11600,12 @@ function createDashboardAppWithLifecycle(deps, options) {
         activeConnections.delete(connId);
         releaseStream();
       };
-      activeConnections.set(connId, { cleanup, lastWrite: Date.now() });
+      const sever = () => {
+        stream.abort();
+        c.env?.outgoing?.destroy();
+      };
+      if (activeConnections.size >= maxSseConnections) return;
+      activeConnections.set(connId, { cleanup, sever, lastWrite: Date.now() });
       try {
         await stream.writeSSE({ data: "", event: "heartbeat" });
       } catch {
@@ -11237,9 +11744,12 @@ export {
   createApprovalApp,
   createChannels,
   createDashboardApp,
+  createMultiApp,
   createSidebandApp,
   createSlackActionApp,
   evaluatePolicy,
+  isNamedConfig,
+  isSingularConfig,
   loadConfig,
   matchRule,
   startServer,