@gethelio/proxy 0.12.0 → 0.13.0

package/dist/cli.js

@@ -45,6 +45,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
@@ -54,8 +59,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(),
@@ -64,10 +69,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",
@@ -93,6 +110,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),
@@ -251,7 +288,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",
@@ -374,7 +415,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,
@@ -486,9 +531,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
@@ -505,6 +548,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;
@@ -512,7 +565,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);
@@ -732,8 +785,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";
@@ -815,8 +1026,16 @@ import { watch } from "chokidar";
 import { isDeepStrictEqual } from "util";
 function diffReloadBoundary(previous, next) {
   const restartRequiredPaths = [];
-  if (!isDeepStrictEqual(previous.upstream, next.upstream)) {
-    restartRequiredPaths.push("upstream");
+  if (isSingularConfig(previous) !== isSingularConfig(next)) {
+    restartRequiredPaths.push("upstream", "upstreams");
+  } else if (isSingularConfig(previous) && isSingularConfig(next)) {
+    if (!isDeepStrictEqual(previous.upstream, next.upstream)) {
+      restartRequiredPaths.push("upstream");
+    }
+  } else if (isNamedConfig(previous) && isNamedConfig(next)) {
+    if (!isDeepStrictEqual(previous.upstreams, next.upstreams)) {
+      restartRequiredPaths.push("upstreams");
+    }
   }
   if (!isDeepStrictEqual(previous.listen, next.listen)) {
     restartRequiredPaths.push("listen");
@@ -1016,7 +1235,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) {
@@ -1219,6 +1439,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
   };
 }
@@ -1555,6 +1778,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) => {
@@ -1568,6 +1793,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([
@@ -1603,7 +1833,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}`
   );
 }
 
@@ -1710,11 +1940,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() {
@@ -1846,7 +2078,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. */
@@ -1890,7 +2122,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. */
@@ -1914,7 +2146,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"
       },
@@ -1923,6 +2155,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,
@@ -1995,13 +2228,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,
@@ -2615,6 +2849,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 = () => {
@@ -2623,7 +2858,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 ?? []));
@@ -2829,6 +3064,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;
@@ -2849,6 +3089,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,
@@ -2866,6 +3177,14 @@ function startSidebandServer(app, port, host = "127.0.0.1") {
   return createServerHandle(server);
 }
 
+// src/reload-fanout.ts
+function applyReloadedPolicy(stacks, newPolicy) {
+  for (const stack of stacks) {
+    stack.governedForwarder.updatePolicy(newPolicy);
+    stack.annotationPrime.reconfigure(newPolicy.toolRevalidation);
+  }
+}
+
 // src/upstream/response.ts
 async function parseUpstreamResponse(res) {
   const headers = {};
@@ -2902,7 +3221,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. */
@@ -3075,11 +3395,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"];
@@ -3250,13 +3574,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((resolve2, 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) {
@@ -3308,9 +3635,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;
     }
@@ -3477,6 +3807,7 @@ var StdioForwarder = class {
   maxRetries;
   retryDelayMs;
   pending;
+  logTag;
   child = null;
   buffer = "";
   retryCount = 0;
@@ -3488,6 +3819,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() {
@@ -3616,25 +3948,28 @@ 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)"));
     }
   }
 };
 
 // src/cli-forwarder.ts
-async function createForwarderFromConfig(config) {
+async function createForwarderFromConfig(config, upstreamName) {
   switch (config.upstream.transport) {
     case "streamable-http": {
       const http = new StreamableHttpForwarder({
         url: config.upstream.url,
         headers: config.upstream.headers,
         requestTimeoutMs: parseDuration(config.upstream.request_timeout),
-        protocolVersion: config.upstream.protocol_version
+        protocolVersion: config.upstream.protocol_version,
+        upstreamName
       });
       if (config.upstream.protocol_version !== "auto") {
         console.error(
-          `[helio] Upstream MCP protocol version pinned: ${config.upstream.protocol_version} (upstream.protocol_version)`
+          `${helioLogTag(upstreamName)} Upstream MCP protocol version pinned: ${config.upstream.protocol_version} (upstream.protocol_version)`
         );
       }
       await http.connect();
@@ -3654,7 +3989,8 @@ async function createForwarderFromConfig(config) {
       const stdio = new StdioForwarder({
         command: config.upstream.command,
         args: config.upstream.args,
-        requestTimeoutMs: parseDuration(config.upstream.request_timeout)
+        requestTimeoutMs: parseDuration(config.upstream.request_timeout),
+        upstreamName
       });
       await stdio.start();
       return { forwarder: stdio, close: () => stdio.close() };
@@ -3731,6 +4067,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;
@@ -3756,6 +4096,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;
 }
 
@@ -3910,7 +4251,8 @@ function decide(input) {
     annotations,
     toolArguments,
     environment,
-    metadata
+    metadata,
+    upstream: input.upstream
   });
   if (driftEvent && driftMode === "log") {
     const currentDecision = evaluatePolicy(policy, {
@@ -3918,7 +4260,8 @@ function decide(input) {
       annotations: input.currentAnnotations,
       toolArguments,
       environment,
-      metadata
+      metadata,
+      upstream: input.upstream
     });
     decision = stricterDecision(decision, currentDecision);
   }
@@ -4531,394 +4874,88 @@ 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}`;
+}
+var UPSTREAM_PREFIX_RE = /^upstream:([^:]+):/;
+function upstreamFromLimitKey(key) {
+  const match = UPSTREAM_PREFIX_RE.exec(key);
+  return match?.[1] ?? null;
+}
+
+// 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)
-   */
-  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.
+   * 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;
@@ -4930,7 +4967,13 @@ var GovernedForwarder = class {
       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);
@@ -4944,7 +4987,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
           });
@@ -5090,7 +5133,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) {
@@ -5134,7 +5178,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;
@@ -5277,6 +5322,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
       },
@@ -5424,8 +5471,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);
@@ -5571,7 +5619,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;
@@ -5584,7 +5633,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
     );
@@ -5666,8 +5717,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,
@@ -5680,7 +5732,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) {
@@ -5690,15 +5742,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 }),
@@ -5745,7 +5798,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(
@@ -5818,14 +5871,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
               });
@@ -5858,7 +5911,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
@@ -5878,7 +5931,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);
@@ -5919,7 +5973,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'`.
@@ -5933,7 +5989,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;
@@ -5941,10 +5997,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);
     }
   }
   /**
@@ -6099,7 +6155,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) {
@@ -6204,79 +6261,342 @@ function collectAllowedEvidenceKeys(policy) {
       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"})`;
+  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
+    };
+  }
+  /**
+   * 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
+    };
+  }
+  // -------------------------------------------------------------------------
+  // 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
+    };
+  }
+  /** 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 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;
@@ -6299,128 +6619,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)
   // -------------------------------------------------------------------------
@@ -6429,17 +6806,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. */
@@ -6454,43 +6833,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);
       }
     }
@@ -6526,6 +6924,13 @@ var ANNOTATION_PRIME_INITIAL_WAIT_MS = 1500;
 var ANNOTATION_PRIME_RETRY_BASE_MS = 1e3;
 var ANNOTATION_PRIME_RETRY_MAX_MS = 3e4;
 var ANNOTATION_PRIME_RETRY_JITTER_MS = 250;
+function sameRevalidation(a, b) {
+  if (a === void 0 || b === void 0) return a === b;
+  return a.enabled === b.enabled && a.intervalMs === b.intervalMs && a.maxAdvertisedTtlMs === b.maxAdvertisedTtlMs;
+}
+function describeRejection(reason) {
+  return reason instanceof Error ? reason.message : String(reason);
+}
 function computePrimeRetryDelayMs(attempt) {
   const exponent = Math.max(0, attempt - 1);
   const baseDelay = Math.min(
@@ -6535,7 +6940,8 @@ function computePrimeRetryDelayMs(attempt) {
   const jitter = Math.floor(Math.random() * ANNOTATION_PRIME_RETRY_JITTER_MS);
   return Math.min(ANNOTATION_PRIME_RETRY_MAX_MS, baseDelay + jitter);
 }
-async function startAnnotationPrimeLoop(forwarder, revalidation) {
+async function startAnnotationPrimeLoop(forwarder, revalidation, upstreamName) {
+  const tag = helioLogTag(upstreamName);
   let stopped = false;
   let primed = false;
   let retryAttempt = 0;
@@ -6563,10 +6969,16 @@ async function startAnnotationPrimeLoop(forwarder, revalidation) {
         if (epoch !== revalidateEpoch) return;
         if (!result.success) {
           console.error(
-            `[helio] Tool revalidation failed: ${result.reason ?? "unknown reason"} \u2014 keeping the last baselines; next attempt in ${String(rv.intervalMs)}ms`
+            `${tag} Tool revalidation failed: ${result.reason ?? "unknown reason"} \u2014 keeping the last baselines; next attempt in ${String(rv.intervalMs)}ms`
           );
         }
         scheduleRevalidation();
+      }).catch((reason) => {
+        if (epoch !== revalidateEpoch) return;
+        console.error(
+          `${tag} Tool revalidation attempt failed unexpectedly: ${describeRejection(reason)} \u2014 keeping the cadence`
+        );
+        scheduleRevalidation();
       });
     }, rv.intervalMs);
     revalidateTimer.unref();
@@ -6578,6 +6990,7 @@ async function startAnnotationPrimeLoop(forwarder, revalidation) {
     clearRevalidateTimer();
   };
   const reconfigure = (next) => {
+    if (sameRevalidation(current, next)) return;
     current = next;
     revalidateEpoch += 1;
     clearRevalidateTimer();
@@ -6588,7 +7001,7 @@ async function startAnnotationPrimeLoop(forwarder, revalidation) {
     retryAttempt += 1;
     const delayMs = computePrimeRetryDelayMs(retryAttempt);
     console.error(
-      `[helio] Annotation cache prime retry ${String(retryAttempt)} scheduled in ${String(delayMs)}ms`
+      `${tag} Annotation cache prime retry ${String(retryAttempt)} scheduled in ${String(delayMs)}ms`
     );
     retryTimer = setTimeout(() => {
       retryTimer = void 0;
@@ -6601,7 +7014,7 @@ async function startAnnotationPrimeLoop(forwarder, revalidation) {
     if (result.success) {
       primed = true;
       clearRetryTimer();
-      const prefix = phase === "initial" ? "[helio] Annotation cache primed" : `[helio] Annotation cache primed after retry ${String(retryAttempt)}`;
+      const prefix = phase === "initial" ? `${tag} Annotation cache primed` : `${tag} Annotation cache primed after retry ${String(retryAttempt)}`;
       console.error(
         `${prefix}: ${String(result.toolsCached)} tool definitions baselined for drift detection (baselines are per-process; a restart re-baselines \u2014 review tool_drift audit records before restarting)`
       );
@@ -6611,18 +7024,26 @@ async function startAnnotationPrimeLoop(forwarder, revalidation) {
     const reason = result.reason ?? "unknown reason";
     if (phase === "initial") {
       console.error(
-        `[helio] Annotation cache priming failed: ${reason} \u2014 undocumented tools will be denied (fail-closed) until priming succeeds`
+        `${tag} Annotation cache priming failed: ${reason} \u2014 undocumented tools will be denied (fail-closed) until priming succeeds`
       );
     } else {
       console.error(
-        `[helio] Annotation cache prime retry ${String(retryAttempt)} failed: ${reason} \u2014 still fail-closed`
+        `${tag} Annotation cache prime retry ${String(retryAttempt)} failed: ${reason} \u2014 still fail-closed`
       );
     }
     scheduleRetry();
   };
   const runPrimeAttempt = async (phase) => {
-    const result = await forwarder.primeAnnotationCache();
-    handlePrimeResult(phase, result);
+    try {
+      const result = await forwarder.primeAnnotationCache();
+      handlePrimeResult(phase, result);
+    } catch (reason) {
+      if (stopped || primed) return;
+      console.error(
+        `${tag} Tool revalidation attempt failed unexpectedly: ${describeRejection(reason)} \u2014 keeping the cadence`
+      );
+      scheduleRetry();
+    }
   };
   const initialAttempt = runPrimeAttempt("initial");
   const initialOutcome = await Promise.race([
@@ -6635,7 +7056,7 @@ async function startAnnotationPrimeLoop(forwarder, revalidation) {
   ]);
   if (initialOutcome === "timeout") {
     console.error(
-      `[helio] Annotation cache priming did not complete within ${String(ANNOTATION_PRIME_INITIAL_WAIT_MS)}ms; continuing startup fail-closed and retrying in background`
+      `${tag} Annotation cache priming did not complete within ${String(ANNOTATION_PRIME_INITIAL_WAIT_MS)}ms; continuing startup fail-closed and retrying in background`
     );
     scheduleRetry();
   }
@@ -6647,6 +7068,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") {
@@ -6741,7 +7170,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 = `
@@ -6753,6 +7183,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 (
@@ -6761,14 +7192,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 = [
@@ -6787,7 +7220,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 {
@@ -6819,6 +7256,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
   };
 }
@@ -6860,6 +7298,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);
@@ -6891,6 +7337,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 {
@@ -6919,6 +7381,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);
@@ -6984,7 +7449,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.`
     );
   }
@@ -7027,6 +7492,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;
@@ -7102,9 +7568,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
@@ -7130,9 +7601,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);
@@ -7296,7 +7767,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,
@@ -7333,7 +7804,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
   };
 }
 
@@ -8149,7 +8623,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) {
@@ -8871,11 +9347,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) {
@@ -8883,10 +9360,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,
@@ -8918,7 +9396,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 } };
@@ -9077,7 +9555,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);
@@ -9142,7 +9622,7 @@ function buildLimitKey(keyType, toolName, senderId) {
     case "agent":
     case "tool":
     default:
-      return `tool:${toolName}`;
+      return toolLimitKey(toolName);
   }
 }
 function senderIdOf(metadata) {
@@ -9270,6 +9750,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,
@@ -9389,6 +9872,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
     });
@@ -9485,6 +9970,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
     });
@@ -9654,15 +10143,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 [
@@ -10298,14 +10794,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 = [];
@@ -10316,7 +10816,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 ?? {});
@@ -10341,7 +10841,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 };
@@ -10421,7 +10922,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);
@@ -10447,7 +10949,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);
@@ -10757,7 +11260,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
     };
   }
 };
@@ -10866,11 +11370,16 @@ GROUP BY e.bucket_key
 ORDER BY e.bucket_key ASC
 `;
 var LIST_EVENTS_SQL = `
-SELECT id, budget_name, bucket_key, kind, amount, currency, tool_name,
-       origin, audit_record_id, timestamp, timestamp_ms, created_at
-FROM budget_events
-WHERE budget_name = ?
-ORDER BY timestamp_ms DESC, rowid DESC
+SELECT e.id AS id, e.budget_name AS budget_name, e.bucket_key AS bucket_key,
+       e.kind AS kind, e.amount AS amount, e.currency AS currency,
+       e.tool_name AS tool_name, e.origin AS origin,
+       e.audit_record_id AS audit_record_id, e.timestamp AS timestamp,
+       e.timestamp_ms AS timestamp_ms, e.created_at AS created_at,
+       a.upstream AS upstream
+FROM budget_events e
+LEFT JOIN audit_records a ON a.id = e.audit_record_id
+WHERE e.budget_name = ?
+ORDER BY e.timestamp_ms DESC, e.rowid DESC
 LIMIT ? OFFSET ?
 `;
 var COUNT_EVENTS_SQL = "SELECT COUNT(*) AS total FROM budget_events WHERE budget_name = ?";
@@ -11121,10 +11630,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) {
@@ -11167,7 +11677,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) => {
@@ -11309,7 +11822,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"])),
@@ -11328,7 +11847,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),
@@ -11348,7 +11869,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),
@@ -11360,7 +11883,8 @@ var budgetEventsExportQuerySchema = z8.object({
 });
 var analyticsQuerySchema = z8.object({
   from: optionalQueryString,
-  to: optionalQueryString
+  to: optionalQueryString,
+  upstream: optionalQueryString
 });
 var authSessionBodySchema = z8.object({
   secret: z8.string()
@@ -11421,6 +11945,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,
@@ -11557,7 +12083,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,
@@ -11584,7 +12113,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") {
@@ -11630,7 +12161,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({
@@ -11696,7 +12229,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) => {
@@ -11708,17 +12241,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;
@@ -11728,7 +12266,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();
@@ -11749,7 +12302,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 {
@@ -11852,6 +12410,69 @@ var DashboardEventBus = class {
     this.emitter.removeAllListeners();
   }
 };
+function actionEventFromRecord(record, id) {
+  return {
+    id,
+    tool_name: record.tool_name,
+    policy_decision: record.policy_decision,
+    block_reason: record.block_reason,
+    approval_status: record.approval_status,
+    session_id: record.session_id,
+    session_source: record.session_source,
+    protocol_version: record.protocol_version,
+    agent_id: record.agent_id,
+    environment: record.environment,
+    timestamp: record.timestamp,
+    total_duration_ms: record.total_duration_ms,
+    approval_wait_ms: record.approval_wait_ms,
+    proxy_compute_ms: record.proxy_compute_ms,
+    flagged_destructive: record.flagged_destructive,
+    dry_run: record.dry_run,
+    matched_rule: record.matched_rule,
+    matched_rule_index: record.matched_rule_index,
+    record_kind: record.record_kind,
+    origin: record.origin,
+    upstream: record.upstream
+  };
+}
+function approvalRequestedEvent(ticket) {
+  return {
+    ticket_id: ticket.id,
+    tool_name: ticket.tool_name,
+    channel: ticket.channel_name,
+    requested_at: ticket.requested_at,
+    upstream: ticket.upstream ?? null
+  };
+}
+function limitWarningEvent(type, key, current, limit) {
+  return {
+    key,
+    type,
+    current,
+    limit,
+    utilization: current / limit,
+    upstream: upstreamFromLimitKey(key)
+  };
+}
+function dashboardEventCallbacks(bus) {
+  return {
+    onPersist: (record, id) => {
+      bus.emit("action", actionEventFromRecord(record, id));
+    },
+    onApprovalSubmit: (ticket) => {
+      bus.emit("approval_requested", approvalRequestedEvent(ticket));
+    },
+    onRateWarning: (state) => {
+      bus.emit("limit_warning", limitWarningEvent("rate", state.key, state.current, state.limit));
+    },
+    onSpendWarning: (state) => {
+      bus.emit(
+        "limit_warning",
+        limitWarningEvent("spend", state.key, state.current_spend, state.limit)
+      );
+    }
+  };
+}
 
 // src/startup-warnings.ts
 function isLoopbackHost2(host) {
@@ -11871,6 +12492,32 @@ function warnIfBudgetWindowExceedsRetention(config, log = console.error) {
   }
   return warned;
 }
+function warnIfManyUpstreams(config, log = console.error) {
+  const count = config.upstreams.length;
+  if (count <= 16) return false;
+  log(
+    `[helio] Warning: ${String(count)} upstreams configured. Each upstream runs its own upstream connection or child process plus an annotation prime loop; consider whether one proxy should govern this many.`
+  );
+  return true;
+}
+function warnIfStdioUrlIgnored(config, log = console.error) {
+  let warned = false;
+  const warn = (path) => {
+    log(
+      `[helio] Warning: ${path} is ignored when transport is "stdio" (the stdio forwarder spawns "command"). Remove the field to silence this warning.`
+    );
+    warned = true;
+  };
+  if (config.upstream?.transport === "stdio" && config.upstream.url !== void 0) {
+    warn("upstream.url");
+  }
+  config.upstreams?.forEach((entry, index) => {
+    if (entry.transport === "stdio" && entry.url !== void 0) {
+      warn(`upstreams.${String(index)}.url`);
+    }
+  });
+  return warned;
+}
 function warnIfWebhookChannelUnreachable(config, log = console.error) {
   const hasWebhookChannel = config.approval.channels.some((ch) => ch.type === "webhook");
   const localOnlyDashboard = config.dashboard.enabled && isLoopbackHost2(config.dashboard.host);
@@ -11906,7 +12553,7 @@ function warnIfNoEnforcement(policy, log = console.error) {
 
 // src/shutdown.ts
 async function closeResources(resources) {
-  resources.annotationPrime?.stop();
+  for (const prime of resources.annotationPrimes ?? []) prime.stop();
   resources.configWatcher?.close();
   resources.approvalRouter?.close();
   resources.approvalQueue?.close();
@@ -11921,7 +12568,7 @@ async function closeResources(resources) {
   resources.budgetEngine?.close();
   resources.evidenceStore?.close();
   resources.auditWriter?.close();
-  if (resources.closeForwarder) await resources.closeForwarder();
+  for (const close of resources.closeForwarders ?? []) await close();
 }
 
 // src/crash-drain.ts
@@ -11995,6 +12642,12 @@ upstream:
 #   headers:
 #     Authorization: "Bearer \${UPSTREAM_TOKEN}"
 
+# Multiple named upstreams (multi-upstream mode) replace \`upstream:\` \u2014
+# set exactly one of the two. See docs/configuration.md.
+# upstreams:
+#   - name: files
+#     url: "http://localhost:8081/mcp"
+
 # listen:
 #   port: 3000
 #   host: 127.0.0.1
@@ -12067,6 +12720,28 @@ function printConfigErrorDetails(error, prefix = "") {
     console.error(`${prefix}  ${detail.path}: ${detail.message}`);
   }
 }
+async function connectUpstream(upstream, upstreamName) {
+  try {
+    return await createForwarderFromConfig({ upstream }, upstreamName);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new StartupError(
+      upstreamName === void 0 ? message : `upstream "${upstreamName}": ${message}`
+    );
+  }
+}
+async function governUpstream(options) {
+  const governedForwarder = new GovernedForwarder(options.forwarder, options.policy, {
+    ...options.governance,
+    upstreamName: options.upstreamName
+  });
+  const annotationPrime = await startAnnotationPrimeLoop(
+    governedForwarder,
+    options.policy.toolRevalidation,
+    options.upstreamName
+  );
+  return { governedForwarder, annotationPrime };
+}
 async function startCommand(configPath, options) {
   let config;
   try {
@@ -12086,7 +12761,29 @@ async function startCommand(configPath, options) {
     );
     process.exit(1);
   }
-  const { forwarder, close: closeForwarder } = await createForwarderFromConfig(config);
+  if (isNamedConfig(config)) {
+    warnIfManyUpstreams(config);
+  }
+  warnIfStdioUrlIgnored(config);
+  const upstreamSections = isNamedConfig(config) ? config.upstreams.map((entry) => ({ name: entry.name, upstream: entry })) : [{ name: void 0, upstream: config.upstream }];
+  const doors = [];
+  for (const { name, upstream } of upstreamSections) {
+    try {
+      const built = await connectUpstream(upstream, name);
+      doors.push({ name, forwarder: built.forwarder, close: built.close });
+    } catch (err) {
+      for (const door of doors) {
+        try {
+          await door.close?.();
+        } catch (closeErr) {
+          console.error(
+            `[helio] Ignoring a forwarder close failure while aborting startup: ${String(closeErr)}`
+          );
+        }
+      }
+      throw err;
+    }
+  }
   const { policy, warnings } = compilePolicies(config.policies);
   for (const w of warnings) {
     const label = w.ruleName ? `rule "${w.ruleName}"` : `rule ${String(w.ruleIndex)}`;
@@ -12094,6 +12791,7 @@ async function startCommand(configPath, options) {
   }
   const budgets = compileBudgets(config.budgets);
   const eventBus = new DashboardEventBus();
+  const cbs = dashboardEventCallbacks(eventBus);
   const auditStore = new AuditStore({
     path: config.audit.path,
     retention: config.audit.retention,
@@ -12106,30 +12804,7 @@ async function startCommand(configPath, options) {
   auditStore.runRetentionSweep();
   const auditWriter = new AuditWriter({
     store: auditStore,
-    onPersist: (record, id) => {
-      eventBus.emit("action", {
-        id,
-        tool_name: record.tool_name,
-        policy_decision: record.policy_decision,
-        block_reason: record.block_reason,
-        approval_status: record.approval_status,
-        session_id: record.session_id,
-        session_source: record.session_source,
-        protocol_version: record.protocol_version,
-        agent_id: record.agent_id,
-        environment: record.environment,
-        timestamp: record.timestamp,
-        total_duration_ms: record.total_duration_ms,
-        approval_wait_ms: record.approval_wait_ms,
-        proxy_compute_ms: record.proxy_compute_ms,
-        flagged_destructive: record.flagged_destructive,
-        dry_run: record.dry_run,
-        matched_rule: record.matched_rule,
-        matched_rule_index: record.matched_rule_index,
-        record_kind: record.record_kind,
-        origin: record.origin
-      });
-    }
+    onPersist: cbs.onPersist
   });
   registerCrashDrainHook(() => {
     try {
@@ -12147,14 +12822,7 @@ async function startCommand(configPath, options) {
     defaultOnTimeout: config.approval.default_on_timeout,
     channels,
     queue: approvalQueue,
-    onSubmit: (ticket) => {
-      eventBus.emit("approval_requested", {
-        ticket_id: ticket.id,
-        tool_name: ticket.tool_name,
-        channel: ticket.channel_name,
-        requested_at: ticket.requested_at
-      });
-    },
+    onSubmit: cbs.onApprovalSubmit,
     onResolve: (ticket) => {
       eventBus.emit("approval_resolved", {
         ticket_id: ticket.id,
@@ -12168,26 +12836,10 @@ async function startCommand(configPath, options) {
     }
   });
   const rateLimiter = new RateLimiter({
-    onWarning: (state) => {
-      eventBus.emit("limit_warning", {
-        key: state.key,
-        type: "rate",
-        current: state.current,
-        limit: state.limit,
-        utilization: state.current / state.limit
-      });
-    }
+    onWarning: cbs.onRateWarning
   });
   const spendLimiter = new SpendLimiter({
-    onWarning: (state) => {
-      eventBus.emit("limit_warning", {
-        key: state.key,
-        type: "spend",
-        current: state.current_spend,
-        limit: state.limit,
-        utilization: state.current_spend / state.limit
-      });
-    }
+    onWarning: cbs.onSpendWarning
   });
   const budgetEngine = new BudgetEngine({
     budgets,
@@ -12201,7 +12853,7 @@ async function startCommand(configPath, options) {
   });
   budgetEngine.hydrate();
   const session = compileSessionIdentity(config.session);
-  const governedForwarder = new GovernedForwarder(forwarder, policy, {
+  const governance = {
     environment: config.environment,
     auditWriter,
     evidenceStore,
@@ -12210,16 +12862,47 @@ async function startCommand(configPath, options) {
     spendLimiter,
     budgetEngine,
     session
-  });
-  const annotationPrime = await startAnnotationPrimeLoop(governedForwarder, policy.toolRevalidation);
+  };
+  const stacks = [];
+  for (const door of doors) {
+    stacks.push({
+      name: door.name,
+      ...await governUpstream({
+        forwarder: door.forwarder,
+        policy,
+        governance,
+        upstreamName: door.name
+      })
+    });
+  }
   const hasSlackChannels = [...channels.values()].some((ch) => ch.type === "slack");
   const slackActionApp = hasSlackChannels ? createSlackActionApp({ router: approvalRouter, channels }) : void 0;
-  const app = createApp(config, governedForwarder, {
-    slackActionApp,
-    onHeaderMismatch: (rejection) => {
-      auditWriter.pushImmediate(buildHeaderMismatchAuditRecord(rejection, config.environment));
+  let app;
+  if (isNamedConfig(config)) {
+    const forwarders = {};
+    for (const stack of stacks) {
+      if (stack.name !== void 0) forwarders[stack.name] = stack.governedForwarder;
+    }
+    app = createMultiApp(config, forwarders, {
+      slackActionApp,
+      onHeaderMismatch: (rejection, upstreamName) => {
+        auditWriter.pushImmediate(
+          buildHeaderMismatchAuditRecord(rejection, config.environment, upstreamName)
+        );
+      }
+    });
+  } else {
+    const stack = stacks[0];
+    if (stack === void 0) {
+      throw new Error("unreachable: singular mode connects exactly one upstream");
     }
-  });
+    app = createApp(config, stack.governedForwarder, {
+      slackActionApp,
+      onHeaderMismatch: (rejection) => {
+        auditWriter.pushImmediate(buildHeaderMismatchAuditRecord(rejection, config.environment));
+      }
+    });
+  }
   const handle = startServer(app, config);
   let sidebandHandle;
   let sidebandToken;
@@ -12308,10 +12991,18 @@ async function startCommand(configPath, options) {
     `Policies: ${String(ruleCount)} rule${ruleCount !== 1 ? "s" : ""} loaded (default: ${policy.defaultAction})`
   );
   warnIfNoEnforcement(policy);
-  if (config.upstream.transport === "stdio") {
+  if (isNamedConfig(config)) {
+    for (const entry of config.upstreams) {
+      if (entry.transport === "stdio") {
+        console.error(`Upstream[${entry.name}]: ${entry.command ?? ""} (stdio)`);
+      } else {
+        console.error(`Upstream[${entry.name}]: ${entry.url ?? ""} (${entry.transport})`);
+      }
+    }
+  } else if (config.upstream.transport === "stdio") {
     console.error(`Upstream: ${config.upstream.command ?? ""} (stdio)`);
   } else {
-    console.error(`Upstream: ${config.upstream.url} (${config.upstream.transport})`);
+    console.error(`Upstream: ${config.upstream.url ?? ""} (${config.upstream.transport})`);
   }
   console.error(`Audit: ${config.audit.path} (retention: ${config.audit.retention})`);
   if (sidebandHandle) {
@@ -12373,8 +13064,7 @@ async function startCommand(configPath, options) {
           );
         }
         budgetEngine.reconcile(newBudgets);
-        governedForwarder.updatePolicy(newPolicy);
-        annotationPrime.reconfigure(newPolicy.toolRevalidation);
+        applyReloadedPolicy(stacks, newPolicy);
         governanceService?.updatePolicy(newPolicy);
         const budgetTotal = newBudgets.length;
         console.error(
@@ -12415,8 +13105,8 @@ async function startCommand(configPath, options) {
   }
   registerShutdown(
     handle,
-    annotationPrime,
-    closeForwarder,
+    stacks.map((stack) => stack.annotationPrime),
+    doors.flatMap((door) => door.close ? [door.close] : []),
     auditWriter,
     configWatcher,
     sidebandHandle,
@@ -12456,6 +13146,10 @@ async function validateCommand(configPath) {
       console.error(`Warning: policy ${label}: ${w.message}`);
     }
     compileBudgets(config.budgets);
+    if (isNamedConfig(config)) {
+      warnIfManyUpstreams(config);
+    }
+    warnIfStdioUrlIgnored(config);
     if (config.dashboard.enabled && !getBundledDashboardDistPath()) {
       console.error(
         "Invalid config: dashboard.enabled is true but bundled dashboard assets are missing. " + DASHBOARD_ASSETS_RECOVERY_MESSAGE_FOR_VALIDATE
@@ -12496,6 +13190,7 @@ async function exportCommand(opts) {
       ["--decision", opts.decision],
       ["--reason", opts.reason],
       ["--session", opts.session],
+      ["--upstream", opts.upstream],
       ["--from", opts.from],
       ["--to", opts.to]
     ].filter(([, value]) => value !== void 0);
@@ -12542,6 +13237,7 @@ async function exportCommand(opts) {
         policy_decision: opts.decision,
         block_reason: opts.reason,
         session_id: opts.session,
+        upstream: opts.upstream,
         from: opts.from,
         to: opts.to
       },
@@ -12571,7 +13267,7 @@ function writeCsv(records) {
     console.log(values.join(","));
   }
 }
-function registerShutdown(handle, annotationPrime, closeForwarder, auditWriter, configWatcher, sidebandHandle, evidenceStore, approvalRouter, approvalQueue, rateLimiter, spendLimiter, budgetEngine, closeDashboardApp, dashboardHandle, eventBus, governanceService) {
+function registerShutdown(handle, annotationPrimes, closeForwarders, auditWriter, configWatcher, sidebandHandle, evidenceStore, approvalRouter, approvalQueue, rateLimiter, spendLimiter, budgetEngine, closeDashboardApp, dashboardHandle, eventBus, governanceService) {
   let isShuttingDown = false;
   const shutdown = () => {
     if (isShuttingDown) return;
@@ -12584,8 +13280,8 @@ function registerShutdown(handle, annotationPrime, closeForwarder, auditWriter,
     forceShutdownTimer.unref();
     void closeResources({
       handle,
-      annotationPrime,
-      closeForwarder,
+      annotationPrimes,
+      closeForwarders,
       auditWriter,
       configWatcher,
       sidebandHandle,
@@ -12613,9 +13309,17 @@ function registerShutdown(handle, annotationPrime, closeForwarder, auditWriter,
 }
 var program = new Command().name("helio").description("Helio MCP governance proxy").version(VERSION);
 program.command("start").description("Load config and start the proxy server").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).option("--no-hot-reload", "Disable policy hot-reload \u2014 config edits will require a restart").action(
-  (opts) => startCommand(opts.config, { config: opts.config, noHotReload: opts.hotReload === false })
+  (opts) => startCommand(opts.config, { config: opts.config, noHotReload: opts.hotReload === false }).catch(
+    (err) => {
+      if (err instanceof StartupError) {
+        console.error(err.message);
+        process.exit(1);
+      }
+      throw err;
+    }
+  )
 );
 program.command("init").description("Scaffold a helio.yaml config file with commented defaults").option("-o, --output <path>", "Output file path", DEFAULT_CONFIG_PATH).option("-f, --force", "Overwrite existing file", false).action((opts) => initCommand(opts.output, opts.force));
 program.command("validate").description("Validate a helio.yaml config file").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).action((opts) => validateCommand(opts.config));
-program.command("export").description("Export audit records or a budget ledger to JSON or CSV").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).option("-f, --format <format>", "Output format: json or csv", "json").option("--budgets <name>", "Export the named budget ledger instead of the audit trail").option("--tool <name>", "Filter by tool name").option("--decision <decision>", "Filter by policy decision").option("--reason <reason>", "Filter by block reason").option("--session <id>", "Filter by session ID").option("--from <iso>", "Start time (ISO 8601)").option("--to <iso>", "End time (ISO 8601)").option("--limit <n>", "Max records to export (up to 10000)", "1000").action((opts) => exportCommand(opts));
+program.command("export").description("Export audit records or a budget ledger to JSON or CSV").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).option("-f, --format <format>", "Output format: json or csv", "json").option("--budgets <name>", "Export the named budget ledger instead of the audit trail").option("--tool <name>", "Filter by tool name").option("--decision <decision>", "Filter by policy decision").option("--reason <reason>", "Filter by block reason").option("--session <id>", "Filter by session ID").option("--upstream <name>", "Filter by upstream name").option("--from <iso>", "Start time (ISO 8601)").option("--to <iso>", "End time (ISO 8601)").option("--limit <n>", "Max records to export (up to 10000)", "1000").action((opts) => exportCommand(opts));
 program.parse();