@gethelio/proxy 0.11.1 → 0.13.0

package/dist/index.d.ts

@@ -6,10 +6,18 @@ import { KnownBlock } from '@slack/web-api';
 
 declare const VERSION: string;
 
+declare const sessionIdentitySourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    source: z.ZodLiteral<"header">;
+    name: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string, string>>;
+}, z.core.$strict>, z.ZodObject<{
+    source: z.ZodLiteral<"meta">;
+}, z.core.$strict>, z.ZodObject<{
+    source: z.ZodLiteral<"legacy_header">;
+}, z.core.$strict>], "source">;
 declare const policiesSchema: z.ZodObject<{
     default: z.ZodDefault<z.ZodEnum<{
-        allow: "allow";
         deny: "deny";
+        allow: "allow";
     }>>;
     flag_destructive: z.ZodOptional<z.ZodEnum<{
         require_approval: "require_approval";
@@ -43,10 +51,11 @@ declare const policiesSchema: z.ZodObject<{
                 contains: z.ZodOptional<z.ZodString>;
                 regex: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>]>>>;
+            upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>;
         action: z.ZodEnum<{
-            allow: "allow";
             deny: "deny";
+            allow: "allow";
             require_approval: "require_approval";
             rate_limit: "rate_limit";
             spend_limit: "spend_limit";
@@ -92,8 +101,8 @@ declare const policiesSchema: z.ZodObject<{
     }, z.core.$strict>>>;
     install: z.ZodOptional<z.ZodObject<{
         default: z.ZodDefault<z.ZodEnum<{
-            allow: "allow";
             deny: "deny";
+            allow: "allow";
         }>>;
         rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodOptional<z.ZodString>;
@@ -122,6 +131,11 @@ declare const policiesSchema: z.ZodObject<{
         log: "log";
         block: "block";
     }>>;
+    tool_revalidation: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        interval: z.ZodDefault<z.ZodString>;
+        max_advertised_ttl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     hot_reload: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 declare const budgetSchema: z.ZodObject<{
@@ -158,6 +172,7 @@ declare const budgetSchema: z.ZodObject<{
                 contains: z.ZodOptional<z.ZodString>;
                 regex: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>>;
+            upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>;
         field: z.ZodString;
     }, z.core.$strict>>>;
@@ -177,16 +192,247 @@ declare const approvalChannelSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"dashboard">;
     name: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "type">;
-/** Zod schema for the complete `helio.yaml` configuration file. */
-declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodObject<{
+declare const singularConfigSchema: z.ZodObject<{
+    listen: z.ZodPrefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+        allowed_origins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    environment: z.ZodOptional<z.ZodString>;
+    session: z.ZodPrefault<z.ZodObject<{
+        identity: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            source: z.ZodLiteral<"header">;
+            name: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string, string>>;
+        }, z.core.$strict>, z.ZodObject<{
+            source: z.ZodLiteral<"meta">;
+        }, z.core.$strict>, z.ZodObject<{
+            source: z.ZodLiteral<"legacy_header">;
+        }, z.core.$strict>], "source">>>;
+        on_unresolved: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            anonymous: "anonymous";
+        }>>;
+    }, z.core.$strict>>;
+    policies: z.ZodPrefault<z.ZodObject<{
+        default: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            allow: "allow";
+        }>>;
+        flag_destructive: z.ZodOptional<z.ZodEnum<{
+            require_approval: "require_approval";
+            log: "log";
+        }>>;
+        dry_run: z.ZodDefault<z.ZodBoolean>;
+        rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            match: z.ZodObject<{
+                tool: z.ZodOptional<z.ZodString>;
+                annotations: z.ZodOptional<z.ZodObject<{
+                    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+                    destructiveHint: z.ZodOptional<z.ZodBoolean>;
+                    idempotentHint: z.ZodOptional<z.ZodBoolean>;
+                    openWorldHint: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strict>>;
+                input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    eq: z.ZodOptional<z.ZodUnknown>;
+                    neq: z.ZodOptional<z.ZodUnknown>;
+                    gt: z.ZodOptional<z.ZodNumber>;
+                    gte: z.ZodOptional<z.ZodNumber>;
+                    lt: z.ZodOptional<z.ZodNumber>;
+                    lte: z.ZodOptional<z.ZodNumber>;
+                    contains: z.ZodOptional<z.ZodString>;
+                    regex: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+                environment: z.ZodOptional<z.ZodString>;
+                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    eq: z.ZodOptional<z.ZodString>;
+                    neq: z.ZodOptional<z.ZodString>;
+                    contains: z.ZodOptional<z.ZodString>;
+                    regex: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>]>>>;
+                upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+            action: z.ZodEnum<{
+                deny: "deny";
+                allow: "allow";
+                require_approval: "require_approval";
+                rate_limit: "rate_limit";
+                spend_limit: "spend_limit";
+                dry_run: "dry_run";
+            }>;
+            approval: z.ZodOptional<z.ZodObject<{
+                channel: z.ZodString;
+                timeout: z.ZodOptional<z.ZodString>;
+                delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                escalation_after: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            evidence: z.ZodOptional<z.ZodObject<{
+                requires: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+            requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            requires_success: z.ZodOptional<z.ZodBoolean>;
+            limits: z.ZodOptional<z.ZodObject<{
+                max_calls: z.ZodOptional<z.ZodNumber>;
+                window: z.ZodOptional<z.ZodString>;
+                key: z.ZodOptional<z.ZodEnum<{
+                    tool: "tool";
+                    agent: "agent";
+                    session: "session";
+                    sender_id: "sender_id";
+                }>>;
+                max_spend: z.ZodOptional<z.ZodObject<{
+                    field: z.ZodString;
+                    limit: z.ZodNumber;
+                    currency: z.ZodString;
+                    window: z.ZodString;
+                    key: z.ZodOptional<z.ZodEnum<{
+                        tool: "tool";
+                        agent: "agent";
+                        session: "session";
+                        sender_id: "sender_id";
+                    }>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            feedback: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+                suggestion: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+        install: z.ZodOptional<z.ZodObject<{
+            default: z.ZodDefault<z.ZodEnum<{
+                deny: "deny";
+                allow: "allow";
+            }>>;
+            rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
+                match: z.ZodObject<{
+                    name: z.ZodOptional<z.ZodString>;
+                    source: z.ZodOptional<z.ZodString>;
+                    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        eq: z.ZodOptional<z.ZodString>;
+                        neq: z.ZodOptional<z.ZodString>;
+                        contains: z.ZodOptional<z.ZodString>;
+                        regex: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>]>>>;
+                }, z.core.$strict>;
+                action: z.ZodEnum<{
+                    allow: "allow";
+                    deny_install: "deny_install";
+                }>;
+                feedback: z.ZodOptional<z.ZodObject<{
+                    message: z.ZodString;
+                    suggestion: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        on_tool_drift: z.ZodOptional<z.ZodEnum<{
+            require_approval: "require_approval";
+            log: "log";
+            block: "block";
+        }>>;
+        tool_revalidation: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            interval: z.ZodDefault<z.ZodString>;
+            max_advertised_ttl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        hot_reload: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    budgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        limit: z.ZodNumber;
+        currency: z.ZodString;
+        window: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"session">]>;
+        key: z.ZodDefault<z.ZodEnum<{
+            session: "session";
+            sender_id: "sender_id";
+            global: "global";
+        }>>;
+        on_exceed: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            require_approval: "require_approval";
+        }>>;
+        approval: z.ZodOptional<z.ZodObject<{
+            channel: z.ZodString;
+            timeout: z.ZodOptional<z.ZodString>;
+            delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            escalation_after: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        idle_ttl: z.ZodOptional<z.ZodString>;
+        contributors: z.ZodArray<z.ZodPipe<z.ZodUnknown, z.ZodObject<{
+            match: z.ZodObject<{
+                tool: z.ZodString;
+                input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    eq: z.ZodOptional<z.ZodUnknown>;
+                    neq: z.ZodOptional<z.ZodUnknown>;
+                    gt: z.ZodOptional<z.ZodNumber>;
+                    gte: z.ZodOptional<z.ZodNumber>;
+                    lt: z.ZodOptional<z.ZodNumber>;
+                    lte: z.ZodOptional<z.ZodNumber>;
+                    contains: z.ZodOptional<z.ZodString>;
+                    regex: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+                upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+            field: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+    approval: z.ZodPrefault<z.ZodObject<{
+        timeout: z.ZodDefault<z.ZodString>;
+        default_on_timeout: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            allow: "allow";
+        }>>;
+        channels: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"slack">;
+            name: z.ZodOptional<z.ZodString>;
+            bot_token: z.ZodString;
+            signing_secret: z.ZodString;
+            channel: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"webhook">;
+            name: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            secret: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"dashboard">;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "type">>>;
+    }, z.core.$strict>>;
+    audit: z.ZodPrefault<z.ZodObject<{
+        storage: z.ZodDefault<z.ZodEnum<{
+            sqlite: "sqlite";
+        }>>;
+        path: z.ZodDefault<z.ZodString>;
+        retention: z.ZodDefault<z.ZodString>;
+        include_responses: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    dashboard: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+        api_secret: z.ZodOptional<z.ZodString>;
+        allow_open_mode: z.ZodDefault<z.ZodBoolean>;
+        sse_heartbeat_interval: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
+    sdk: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+        evaluation_ttl: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
     version: z.ZodLiteral<"1">;
     upstream: z.ZodObject<{
-        url: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
         transport: z.ZodDefault<z.ZodEnum<{
             "streamable-http": "streamable-http";
             sse: "sse";
             stdio: "stdio";
         }>>;
+        protocol_version: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            "2025-06-18": "2025-06-18";
+            "2026-07-28": "2026-07-28";
+        }>>;
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
         connect_timeout: z.ZodDefault<z.ZodString>;
@@ -194,15 +440,32 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
         forward_headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
         headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>;
+}, z.core.$strict>;
+declare const namedConfigSchema: z.ZodObject<{
     listen: z.ZodPrefault<z.ZodObject<{
         port: z.ZodDefault<z.ZodNumber>;
         host: z.ZodDefault<z.ZodString>;
+        allowed_origins: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     environment: z.ZodOptional<z.ZodString>;
+    session: z.ZodPrefault<z.ZodObject<{
+        identity: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            source: z.ZodLiteral<"header">;
+            name: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string, string>>;
+        }, z.core.$strict>, z.ZodObject<{
+            source: z.ZodLiteral<"meta">;
+        }, z.core.$strict>, z.ZodObject<{
+            source: z.ZodLiteral<"legacy_header">;
+        }, z.core.$strict>], "source">>>;
+        on_unresolved: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            anonymous: "anonymous";
+        }>>;
+    }, z.core.$strict>>;
     policies: z.ZodPrefault<z.ZodObject<{
         default: z.ZodDefault<z.ZodEnum<{
-            allow: "allow";
             deny: "deny";
+            allow: "allow";
         }>>;
         flag_destructive: z.ZodOptional<z.ZodEnum<{
             require_approval: "require_approval";
@@ -236,10 +499,11 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
                     contains: z.ZodOptional<z.ZodString>;
                     regex: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>]>>>;
+                upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>;
             action: z.ZodEnum<{
-                allow: "allow";
                 deny: "deny";
+                allow: "allow";
                 require_approval: "require_approval";
                 rate_limit: "rate_limit";
                 spend_limit: "spend_limit";
@@ -285,8 +549,8 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
         }, z.core.$strict>>>;
         install: z.ZodOptional<z.ZodObject<{
             default: z.ZodDefault<z.ZodEnum<{
-                allow: "allow";
                 deny: "deny";
+                allow: "allow";
             }>>;
             rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 name: z.ZodOptional<z.ZodString>;
@@ -315,6 +579,11 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
             log: "log";
             block: "block";
         }>>;
+        tool_revalidation: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            interval: z.ZodDefault<z.ZodString>;
+            max_advertised_ttl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         hot_reload: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     budgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -351,6 +620,7 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
                     contains: z.ZodOptional<z.ZodString>;
                     regex: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>>>;
+                upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>;
             field: z.ZodString;
         }, z.core.$strict>>>;
@@ -358,8 +628,8 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
     approval: z.ZodPrefault<z.ZodObject<{
         timeout: z.ZodDefault<z.ZodString>;
         default_on_timeout: z.ZodDefault<z.ZodEnum<{
-            allow: "allow";
             deny: "deny";
+            allow: "allow";
         }>>;
         channels: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"slack">;
@@ -399,13 +669,44 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
         host: z.ZodDefault<z.ZodString>;
         evaluation_ttl: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>>;
-}, z.core.$strict>>;
-/** Fully validated and defaulted Helio configuration. */
-type HelioConfig = z.infer<typeof helioConfigSchema>;
+    version: z.ZodLiteral<"1">;
+    upstreams: z.ZodArray<z.ZodObject<{
+        url: z.ZodOptional<z.ZodString>;
+        transport: z.ZodDefault<z.ZodEnum<{
+            "streamable-http": "streamable-http";
+            sse: "sse";
+            stdio: "stdio";
+        }>>;
+        protocol_version: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            "2025-06-18": "2025-06-18";
+            "2026-07-28": "2026-07-28";
+        }>>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        connect_timeout: z.ZodDefault<z.ZodString>;
+        request_timeout: z.ZodDefault<z.ZodString>;
+        forward_headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A fully validated and defaulted singular-mode (`upstream:`) configuration. */
+type SingularHelioConfig = z.output<typeof singularConfigSchema>;
+/** A fully validated and defaulted named-mode (`upstreams:`) configuration. */
+type NamedHelioConfig = z.output<typeof namedConfigSchema>;
+/** Fully validated and defaulted Helio configuration — one of the two mode arms. */
+type HelioConfig = SingularHelioConfig | NamedHelioConfig;
+/** Narrow a parsed config to the singular-mode (`upstream:`) arm. */
+declare function isSingularConfig(config: HelioConfig): config is SingularHelioConfig;
+/** Narrow a parsed config to the named-mode (`upstreams:`) arm. */
+declare function isNamedConfig(config: HelioConfig): config is NamedHelioConfig;
 /** An approval channel configuration (slack, webhook, or dashboard). */
 type ApprovalChannel$1 = z.infer<typeof approvalChannelSchema>;
 /** The policies section of the config. */
 type PoliciesConfig = z.infer<typeof policiesSchema>;
+/** A single identity source from `session.identity`. */
+type SessionIdentitySource = z.infer<typeof sessionIdentitySourceSchema>;
 /** A single named budget from the `budgets` array (issue #14). */
 type BudgetConfig = z.infer<typeof budgetSchema>;
 /** The `budgets` section of the config. */
@@ -490,6 +791,8 @@ interface CompiledMatch {
     readonly environment?: string;
     /** Flattened list of metadata conditions (one entry per key+operator pair). */
     readonly metadata?: readonly MetadataCondition[];
+    /** Configured upstream names the rule is scoped to, OR within the list (issue #293). */
+    readonly upstreams?: readonly string[];
 }
 /** Compiled approval configuration with durations as milliseconds. */
 interface CompiledApproval {
@@ -513,6 +816,12 @@ interface CompiledLimits {
     readonly key?: 'tool' | 'agent' | 'session' | 'sender_id';
     readonly maxSpend?: CompiledSpendLimit;
 }
+/** Compiled tool revalidation settings with durations as milliseconds. */
+interface CompiledToolRevalidation {
+    readonly enabled: boolean;
+    readonly intervalMs: number;
+    readonly maxAdvertisedTtlMs: number;
+}
 /** Policy action types. */
 type PolicyAction = 'allow' | 'deny' | 'require_approval' | 'rate_limit' | 'spend_limit' | 'dry_run';
 /** A fully compiled policy rule ready for engine evaluation. */
@@ -576,6 +885,8 @@ interface CompiledPolicy {
      * at the use site — conservative by default.
      */
     readonly onToolDrift?: 'block' | 'require_approval' | 'log';
+    /** Always set by compilePolicies; absent only in hand-built fixtures (treated as disabled). */
+    readonly toolRevalidation?: CompiledToolRevalidation;
     readonly rules: readonly CompiledPolicyRule[];
     /** Install-time policy (issue #13 — deny_install). Undefined ⇒ observational. */
     readonly install?: CompiledInstallPolicy;
@@ -625,6 +936,12 @@ interface MatchContext {
      * request column) is merged in by the decision pipeline, not stored here twice.
      */
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * The governed door's configured upstream name (issue #295). A string only on
+     * the MCP path when a name is configured; undefined on the sideband and in
+     * singular mode, so upstream-scoped rules are inert there by construction.
+     */
+    readonly upstream?: string;
 }
 
 /** One compiled contributor: which calls feed the budget, and from which field. */
@@ -634,6 +951,13 @@ interface CompiledBudgetContributor {
         /** Flattened conditions (one per path+operator); absent when unconditioned. */
         readonly input?: readonly InputCondition[];
     };
+    /**
+     * Configured upstream names the contributor is scoped to (issue #293);
+     * absent means every door contributes. A scoped contributor never
+     * participates when the charge context carries no upstream (sideband,
+     * singular mode).
+     */
+    readonly upstreams?: readonly string[];
     /** Dot-path into the tool arguments (e.g. "$.amount"), resolved per call. */
     readonly field: string;
 }
@@ -679,15 +1003,63 @@ interface JsonRpcRequest {
     method: string;
     params?: unknown;
 }
+/** Resolved governance session identity (issue #218). */
+interface ResolvedSession {
+    readonly id: string;
+    /** Strategy that produced it — recorded in the audit trail. */
+    readonly source: 'header' | 'meta' | 'legacy_header' | 'transport';
+}
 /** A parsed MCP request enriched with session context. */
 interface McpRequest extends JsonRpcRequest {
-    /** MCP session ID extracted from the `Mcp-Session-Id` header. */
-    sessionId?: string;
+    /** Proxy-resolved governance session identity (undefined when no strategy matched). */
+    session?: ResolvedSession;
+    /** Verbatim Mcp-Session-Id from the wire. Transport relay ONLY — never governance. */
+    transportSessionId?: string;
+    /**
+     * The client's verbatim MCP-Protocol-Version wire claim (issue #219) —
+     * captured raw, with no normalization, for the audit trail. It is the
+     * CLIENT'S claim, not the upstream era. Since issue #226 the
+     * streamable-http route validates header/body agreement before
+     * forwarding, so on a FORWARDED request a claim of `2026-07-28` has
+     * passed the agreement door; tier-2 claims (legacy, unknown, malformed)
+     * and notification claims remain unvalidated as captured. Streamable
+     * HTTP only: the header postdates the deprecated SSE transport, and
+     * stdio has no headers, so both leave it unset.
+     */
+    protocolVersion?: string;
     /** Per-request headers to forward to upstream (e.g. Authorization, X-* headers). */
     headers?: Record<string, string>;
     /** Abort signal tied to the downstream client request lifecycle. */
     signal?: AbortSignal;
 }
+/**
+ * An inbound request rejected by the header/body agreement door (issue
+ * #226), as protocol facts: what the body said, what the headers claimed,
+ * and why they disagree. Deliberately camelCase and transport-free (no Hono
+ * types, no audit field names) — the audit-record mapping lives solely in
+ * `buildHeaderMismatchAuditRecord` on the audit side.
+ */
+interface HeaderMismatchRejection {
+    /** Human-readable mismatch reason; echoed values are display-capped. */
+    readonly reason: string;
+    /** The body's JSON-RPC method. */
+    readonly method: string;
+    /** The body's params, verbatim as parsed. */
+    readonly params?: unknown;
+    /**
+     * The body's name-bearing string field (`params.name` / `params.uri`),
+     * when the method defines one and the body carries a string value.
+     */
+    readonly bodyName?: string;
+    /** The client's verbatim MCP-Protocol-Version wire claim, if any. */
+    readonly protocolVersion?: string;
+    /** The inbound marker headers that were present, verbatim as received. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Proxy-resolved governance session identity, when a strategy matched. */
+    readonly session?: ResolvedSession;
+    /** Time from route-handler entry to rejection, in milliseconds. */
+    readonly durationMs: number;
+}
 /** The response returned by an MCP forwarder. */
 interface McpResponse {
     status: number;
@@ -724,6 +1096,13 @@ interface ServerHandle {
 interface CreateAppOptions {
     /** Slack interactive action handler (mounted at /slack/actions). */
     slackActionApp?: Hono;
+    /**
+     * Recorder for inbound header/body agreement rejections (issue #226) on
+     * the streamable-http route. Enforcement does not depend on it — with no
+     * recorder the request is still rejected and no record is written (the
+     * library-embedding posture `missing_tool_name` also takes).
+     */
+    onHeaderMismatch?: (rejection: HeaderMismatchRejection) => void;
 }
 /**
  * Create a Hono app configured with the MCP proxy routes.
@@ -733,6 +1112,47 @@ interface CreateAppOptions {
  * @param options - Optional sub-apps to mount.
  */
 declare function createApp(config: HelioConfig, forwarder: McpForwarder, options?: CreateAppOptions): Hono;
+/**
+ * Optional sub-apps and callbacks for the multi-upstream composition.
+ * The main-port posture is `createApp`'s (see CreateAppOptions): only the
+ * Slack webhook callback belongs beside the MCP doors.
+ */
+interface CreateMultiAppOptions {
+    /** Slack interactive action handler (mounted at /slack/actions, global). */
+    slackActionApp?: Hono;
+    /**
+     * Recorder for inbound header/body agreement rejections (issue #226),
+     * called with the name of the door that rejected so the audit record can
+     * attribute it. Enforcement does not depend on it.
+     */
+    onHeaderMismatch?: (rejection: HeaderMismatchRejection, upstreamName: string) => void;
+    /**
+     * @internal Test seam for the per-door concurrent-session cap on the
+     * `/sse/<name>` mounts (issue #232's cap, per-route by construction), so
+     * tests need not mint 1024 real streams per door. The same value goes to
+     * every door's route; the session maps stay per-route-instance. Not wired
+     * to config — absent means the hardcoded 1024.
+     */
+    sse?: {
+        readonly maxConcurrentSessions?: number;
+    };
+}
+/**
+ * Create a Hono app serving every named upstream at its own pair of mounts,
+ * `/mcp/<name>` and `/sse/<name>`, each a fresh route stack wrapping that
+ * entry's forwarder. `/healthz` and `/slack/actions` stay global. There is
+ * NO bare-path default: bare `/mcp`, `/sse`, and unknown names get an
+ * explicit 404 catch-all whose JSON-RPC envelope states the path shape and
+ * never enumerates configured names.
+ *
+ * @param config - The validated named-mode Helio configuration.
+ * @param forwarders - One forwarder per configured entry, keyed by name.
+ *   Must cover the configured names exactly; missing or extra keys throw
+ *   (a missing key would silently mount a dead door, an extra one means the
+ *   record drifted from the config — fail at composition, not per request).
+ * @param options - Optional sub-apps and callbacks.
+ */
+declare function createMultiApp(config: HelioConfig, forwarders: Record<string, McpForwarder>, options?: CreateMultiAppOptions): Hono;
 /**
  * Start the HTTP server on the configured host and port.
  *
@@ -748,6 +1168,12 @@ declare function startServer(app: Hono, config: HelioConfig): ServerHandle;
  */
 declare function startSidebandServer(app: Hono, port: number, host?: string): ServerHandle;
 
+/**
+ * `upstream.protocol_version`: `auto` probes and caches; a dated pin is a
+ * constant — never probed, never cached, never cleared.
+ */
+type UpstreamProtocolVersionPin = 'auto' | '2025-06-18' | '2026-07-28';
+
 interface StreamableHttpForwarderOptions {
     /** The upstream MCP server URL (e.g. "http://localhost:8080/mcp"). */
     url: string;
@@ -755,6 +1181,13 @@ interface StreamableHttpForwarderOptions {
     headers?: Record<string, string>;
     /** Maximum time to wait for an upstream request before aborting. */
     requestTimeoutMs?: number;
+    /** `upstream.protocol_version`: `auto` (default) probes; a dated pin skips it. */
+    protocolVersion?: UpstreamProtocolVersionPin;
+    /**
+     * The operator-chosen upstream entry name (issue #295), threaded to the
+     * session manager's era lifecycle lines. Unset in singular mode.
+     */
+    upstreamName?: string;
 }
 /**
  * Spec-compliant upstream MCP Streamable HTTP client.
@@ -775,11 +1208,35 @@ declare class StreamableHttpForwarder implements McpForwarder {
     /** Lifecycle parity with sse/stdio. */
     close(): Promise<void>;
     forward(request: McpRequest): Promise<ForwardResult>;
+    /**
+     * The dual-era bridge (relay leg, modern era): a modern-only server
+     * answers the retired `initialize` handshake with 404/-32601, so Helio
+     * synthesizes the legacy InitializeResult locally from the upstream's own
+     * probe-time DiscoverResult. No `mcp-session-id` response header — the
+     * legacy spec permits sessionless servers, and the downstream stays
+     * sessionless. The synthesized protocolVersion is always the current
+     * legacy revision, even for a client that offered an older one.
+     */
+    private synthesizeInitializeResult;
+    /**
+     * The modern upstream removed `notifications/initialized`; answer the
+     * same minimal success envelope the SSE-notification path returns.
+     */
+    private swallowInitializedNotification;
+    /**
+     * The relay-side era falsification door (issue #219): a legacy-leg relay whose answer only a
+     * modern server gives clears the cached legacy era (the manager no-ops on
+     * pins, uncached eras, and cached modern). The response still flows to the
+     * client unchanged — no in-place retry.
+     */
+    private inspectLegacyRelayOutcome;
     /**
      * Helio-internal execution path (startup prime / internal maintenance) that
      * may borrow the proxy-managed internal session.
      */
     forwardInternal(request: McpRequest): Promise<ForwardResult>;
+    /** Drop the managed internal session AND the cached era; next internal call re-probes. */
+    resetInternalSession(): void;
     private send;
 }
 
@@ -849,6 +1306,11 @@ interface StdioForwarderOptions {
     retryDelayMs?: number;
     /** Timeout in milliseconds for individual requests. */
     requestTimeoutMs?: number;
+    /**
+     * The operator-chosen upstream entry name (multi-upstream mode). Unset in
+     * singular mode — the death line then keeps its bare `[helio]` tag.
+     */
+    upstreamName?: string;
 }
 /**
  * Forward MCP requests to an upstream server via stdio.
@@ -862,6 +1324,7 @@ declare class StdioForwarder implements McpForwarder {
     private readonly maxRetries;
     private readonly retryDelayMs;
     private readonly pending;
+    private readonly logTag;
     private child;
     private buffer;
     private retryCount;
@@ -939,8 +1402,14 @@ interface AuditRecord {
     readonly id: string;
     /** ISO 8601 timestamp of when the tool call was received by the proxy. */
     readonly timestamp: string;
-    /** MCP session ID from the Mcp-Session-Id header, if present. */
+    /** Resolved governance session id, or the adapter-supplied id on sideband records. */
     readonly session_id: string | null;
+    /**
+     * Which identity strategy produced session_id (issue #218): `header`,
+     * `meta`, `legacy_header`, or `transport` on the MCP door, `sideband` for
+     * adapter-supplied ids. Null when no session resolved.
+     */
+    readonly session_source: string | null;
     /** Agent identifier from config or request header, if present. */
     readonly agent_id: string | null;
     /** Runtime environment label configured on proxy startup, if set. */
@@ -1007,6 +1476,22 @@ interface AuditRecord {
      * `match.metadata.*` (#13) and the dashboard metadata columns (#16).
      */
     readonly metadata: Record<string, unknown> | null;
+    /**
+     * The client's verbatim MCP-Protocol-Version wire claim on the inbound
+     * request (issue #219) — the CLIENT'S claim, not the upstream era, and not
+     * a validated fact. Recorded uncapped: truncation would manufacture a
+     * false claim in an audit record. Null when the request carried no header
+     * and on records with no MCP wire (drift events, sideband records).
+     */
+    readonly protocol_version: string | null;
+    /**
+     * Name of the upstream MCP server this record is attributed to (issue
+     * #292). Null in singular mode (no named upstreams configured), on
+     * sideband records (no MCP door), and on rows that predate the column.
+     * Required-nullable like session_source/protocol_version: a producer that
+     * could silently omit it would exempt that door from attribution.
+     */
+    readonly upstream: string | null;
     /** ISO 8601 timestamp of when the record was persisted. */
     readonly created_at: string;
 }
@@ -1022,6 +1507,18 @@ interface AuditQueryFilters {
     readonly blocked?: boolean;
     /** Filter by session ID (exact match). */
     readonly session_id?: string;
+    /**
+     * Filter by session identity source (exact match — the five-value
+     * `header` / `meta` / `legacy_header` / `transport` / `sideband`
+     * vocabulary, issue #250). SQL equality: rows whose session_source is
+     * NULL never match any filter value.
+     */
+    readonly session_source?: string;
+    /**
+     * Filter by upstream name (exact match). SQL equality: rows whose
+     * upstream is NULL never match any filter value.
+     */
+    readonly upstream?: string;
     /** Filter by agent ID (exact match). */
     readonly agent_id?: string;
     /** Include only records created at or after this ISO 8601 timestamp. */
@@ -1090,9 +1587,15 @@ interface AuditAggregateStats {
         readonly reason: string;
         readonly count: number;
     }>;
-    /** Top tools by call count (max 10). */
+    /**
+     * Top tools by call count (max 10 rows). Each row is a (tool, upstream)
+     * pair (issue #297): same-named tools on different upstreams stay
+     * distinct. Upstream is null in singular mode, so all-null groups reduce
+     * to exactly the pre-#297 per-tool rows.
+     */
     readonly top_tools: ReadonlyArray<{
         readonly tool_name: string;
+        readonly upstream: string | null;
         readonly count: number;
     }>;
     /** Approval rate (approved / total require_approval decisions), or null if none. */
@@ -1215,8 +1718,15 @@ declare class AuditStore {
     private query;
     /** Count records matching the given filters. */
     count(filters?: AuditQueryFilters): number;
-    /** Get aggregate statistics for a time range. */
-    aggregate(from?: string, to?: string): AuditAggregateStats;
+    /**
+     * 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?: string, to?: string, filters?: {
+        upstream?: string;
+    }): AuditAggregateStats;
     /** Delete records older than the retention period. Returns the count of deleted records. */
     purgeExpired(): number;
     private purgeBefore;
@@ -1504,6 +2014,18 @@ interface ApprovalTicket {
     readonly rule_index: number | null;
     readonly channel_name: string;
     readonly session_id: string | null;
+    /**
+     * Which identity strategy produced session_id (issue #251): the MCP
+     * resolver's vocabulary on proxy tickets, `sideband` on adapter tickets.
+     * OPTIONAL-ABSENT, not nullable: the ticket is the wire object, and an
+     * unattributed ticket omits the key rather than emitting null.
+     */
+    readonly session_source?: string;
+    /**
+     * Upstream attribution (issue #292). Absent in singular mode and on
+     * native (sideband) tickets — same wire-additive optional spelling.
+     */
+    readonly upstream?: string;
     readonly requested_at: string;
     readonly timeout_at: string;
     readonly timeout_ms: number;
@@ -1599,6 +2121,10 @@ declare class ApprovalQueue {
         timeout_ms: number;
         /** Breached budget context on break-glass / merged tickets (issue #14). */
         breached_budgets?: readonly BudgetBreachContext[];
+        /** Identity-strategy attribution for session_id (issue #251). */
+        session_source?: string | null;
+        /** Upstream attribution (issue #292); absent in singular mode. */
+        upstream?: string | null;
     }): ApprovalTicket;
     /** Get a ticket by ID. Returns undefined if not found. */
     get(id: string): ApprovalTicket | undefined;
@@ -1654,6 +2180,13 @@ interface ApprovalSubmitParams {
     readonly tool_input: Record<string, unknown>;
     readonly matched_rule: CompiledPolicyRule | undefined;
     readonly session_id: string | null;
+    /**
+     * Identity-strategy attribution for session_id (issue #251).
+     * Required-nullable so no submit site can silently forget it.
+     */
+    readonly session_source: string | null;
+    /** Upstream attribution (issue #292); null in singular mode. */
+    readonly upstream: string | null;
     /** Breached budget context; marks the ticket as break-glass (issue #14). */
     readonly breached_budgets?: readonly BudgetBreachContext[];
     /**
@@ -1861,12 +2394,21 @@ declare class RateLimiter {
      * 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 anywhere in `validConfigs`.
+     * `{ 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.
@@ -1874,6 +2416,7 @@ declare class RateLimiter {
     reconcile(validConfigs: Iterable<{
         maxCalls: number;
         windowMs: number;
+        ruleIndex?: number;
     }>): void;
     /** Stop the cleanup timer and mark as closed. */
     /**
@@ -2002,12 +2545,14 @@ declare class SpendLimiter {
      * 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
+     * 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.
+     * 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
@@ -2032,13 +2577,37 @@ declare class SpendLimiter {
     close(): void;
 }
 
+declare const GATED_SESSION: unique symbol;
+/** A session bucket value that provably passed the identity gate. */
+type GatedSession = string & {
+    readonly [GATED_SESSION]: true;
+};
+declare const GATED_CHARGES: unique symbol;
+/** Budget charges that provably passed the session engagement check. */
+type GatedCharges = readonly BudgetCharge[] & {
+    readonly [GATED_CHARGES]: true;
+};
+
 /** Everything the engine needs about one tool call to resolve its charges. */
 interface BudgetChargeContext {
     readonly toolName: string;
     readonly toolArguments: Record<string, unknown> | undefined;
-    readonly sessionId: string | null;
+    /**
+     * Gate-minted session bucket value (issue #218), or null when identity is
+     * unresolved — `bucketKey` builds `session:unknown` from null, which is
+     * legal ONLY because `gateBudgetCharges` denies unresolved session-keyed
+     * engagement before `peekAll`/`recordAll` can run.
+     */
+    readonly sessionId: GatedSession | null;
     /** Adapter-supplied sender id (sideband only); null on the MCP path. */
     readonly senderId: string | null;
+    /**
+     * The governed door's configured upstream name (issue #295); null on the
+     * sideband and in singular mode. Required so every door states its
+     * upstream: a silently-missing value would exempt that door's calls from
+     * upstream-scoped contributors once those exist.
+     */
+    readonly upstream: string | null;
 }
 /** One budget's share of a call: which bucket, how much. */
 interface BudgetCharge {
@@ -2052,6 +2621,12 @@ interface BudgetCharge {
      * NOT repopulate the new pot with old-config spend — recordAll skips it.
      */
     readonly generation: number;
+    /**
+     * The charge context's upstream name, stamped only when the door set one
+     * (issue #295). Optional is the honest type: `remintDeferredCharges`
+     * rebuilds charges without it, so deferred commits snapshot null.
+     */
+    readonly upstream?: string;
 }
 /** A budget whose contributor matched but whose amount was unusable. */
 interface BudgetChargeFailure {
@@ -2076,6 +2651,11 @@ interface BudgetPeekEntry {
     readonly remaining: number;
     /** Epoch ms when the oldest entry ages out (duration); null for session pots. */
     readonly resetAtMs: number | null;
+    /**
+     * The charge's upstream label, or null: sideband calls, singular mode, and
+     * reminted deferred commits all snapshot null (issue #295).
+     */
+    readonly upstream: string | null;
     /**
      * Set on recordAll snapshots for charges frozen before a tuple-changing
      * reload: the executed spend was ledgered under its evaluate-time
@@ -2140,6 +2720,12 @@ interface BudgetCommitEvent {
     readonly limit: number;
     readonly currency: string;
     readonly utilization: number;
+    /**
+     * Upstream attribution from the charge context (issue #292), or null.
+     * Reminted frozen-plan charges drop the label by design, so deferred
+     * sideband commits always emit null here.
+     */
+    readonly upstream: string | null;
 }
 /**
  * Payload for the per-budget breach callback (dashboard event bus). Fired
@@ -2156,6 +2742,8 @@ interface BudgetBreachEvent {
     readonly spent: number;
     readonly limit: number;
     readonly currency: string;
+    /** Upstream attribution from the peek entry's context (issue #292), or null. */
+    readonly upstream: string | null;
 }
 /** Wire-ready bucket state for `GET /api/budgets` (snake_case DTO). */
 interface BudgetBucketState {
@@ -2207,21 +2795,29 @@ declare class BudgetEngine {
     /**
      * 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: BudgetChargeContext): {
         charges: BudgetCharge[];
         failures: BudgetChargeFailure[];
     };
-    /** Check every charge without mutating. All-or-nothing: one deny flips `allowed`. */
-    peekAll(charges: readonly BudgetCharge[]): {
+    /**
+     * Check every charge without mutating. All-or-nothing: one deny flips
+     * `allowed`. Accepts only gate-branded charges (issue #218) — a caller
+     * cannot peek budget state without having run the session engagement check.
+     */
+    peekAll(charges: GatedCharges): {
         allowed: boolean;
         entries: BudgetPeekEntry[];
     };
@@ -2232,7 +2828,7 @@ declare class BudgetEngine {
      * Recording is unconditional past the sink (an approved overage
      * legitimately pushes a bucket past its limit).
      */
-    recordAll(charges: readonly BudgetCharge[], meta: BudgetCommitMeta): BudgetPeekEntry[];
+    recordAll(charges: GatedCharges, meta: BudgetCommitMeta): BudgetPeekEntry[];
     /**
      * Fire one `onBreach` event per breached entry. Called by the doors at the
      * moment a peek outcome actually denies the call or raises the composite
@@ -2329,6 +2925,18 @@ declare class BudgetEngine {
     private snapshot;
 }
 
+/** Compiled session config, wired into the route factories at startup. */
+interface CompiledSessionIdentity {
+    /** The configured identity chain, in order; first match wins. */
+    readonly sources: readonly SessionIdentitySource[];
+    readonly onUnresolved: 'deny' | 'anonymous';
+    /**
+     * Human-readable strategy list (e.g. `header "x-helio-session-id",
+     * legacy_header`) — deny messages name the strategies that were tried.
+     */
+    readonly strategySummary: string;
+}
+
 /** Options for constructing a GovernedForwarder. */
 interface GovernedForwarderOptions {
     /** The current environment label (e.g. "production", "staging"). */
@@ -2345,6 +2953,19 @@ interface GovernedForwarderOptions {
     spendLimiter?: SpendLimiter;
     /** Budget engine for named cross-tool budgets (issue #14). */
     budgetEngine?: BudgetEngine;
+    /**
+     * Compiled session identity config (issue #218): the `on_unresolved` mode
+     * and the strategy summary deny messages name. Defaults to the schema
+     * default chain (deny mode) for direct/library construction.
+     */
+    session?: CompiledSessionIdentity;
+    /**
+     * The operator-chosen upstream entry name (issue #295, multi-upstream
+     * substrate). Unset in singular mode — every governance surface then
+     * behaves exactly as today. The multi-upstream composition loop (issue
+     * #294) passes each entry's name.
+     */
+    upstreamName?: string;
 }
 /** Result of attempting to prime the tool annotation cache. */
 interface AnnotationCachePrimeResult {
@@ -2367,12 +2988,14 @@ declare class GovernedForwarder implements McpForwarder {
     private readonly inner;
     private policy;
     private readonly environment;
+    private readonly session;
     private readonly auditWriter;
     private readonly evidenceStore;
     private readonly approvalRouter;
     private readonly rateLimiter;
     private readonly spendLimiter;
     private readonly budgetEngine;
+    private readonly upstreamName;
     private readonly annotationCache;
     private agentKeyWarned;
     private senderKeyWarned;
@@ -2406,6 +3029,20 @@ declare class GovernedForwarder implements McpForwarder {
      */
     primeAnnotationCache(): Promise<AnnotationCachePrimeResult>;
     forward(request: McpRequest): Promise<ForwardResult>;
+    /**
+     * Clamp an over-long `result.ttlMs` on a `tools/list` response to
+     * `policies.tool_revalidation.max_advertised_ttl` (issue #221, D7).
+     *
+     * Downward-only: a `ttlMs` at or below the cap is left untouched, and a
+     * response with no `ttlMs` never gains one — Helio does not manufacture a
+     * cache hint the upstream never advertised. Non-numeric values are left
+     * alone rather than coerced. `cacheScope` passes through untouched: Helio
+     * baselines and vouches for tool *definitions* only, and its own
+     * `tools/list` view is not caller-varying, so it has no basis to alter a
+     * scope hint the upstream set. No-op when tool revalidation is disabled
+     * (including hand-built `CompiledPolicy` fixtures that omit the field).
+     */
+    private clampCacheHints;
     /**
      * Apply a tools/list response to the definition cache and surface any
      * drift: console warning + immediate audit record per event. Single entry
@@ -2469,14 +3106,22 @@ declare class GovernedForwarder implements McpForwarder {
      * or consuming any resources. Returns an MCP-compliant synthetic response.
      */
     private handleDryRun;
-    /** Construct a limit bucket key based on the configured key type. */
+    /**
+     * 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'`.
+     */
     private buildLimitKey;
     /**
-     * Construct a spend bucket key via the shared {@link spendBucketKey}
-     * composer — see its doc for why spend buckets are rule-discriminated.
-     * Rate buckets keep the undiscriminated keys.
+     * Gate a session-keyed limit at its key-build site (issue #218). Returns
+     * the bucket key, or null when identity is unresolved under deny mode —
+     * the caller denies (enforce) or reports the marker (dry-run).
      */
-    private buildSpendLimitKey;
+    private gateSessionLimitKey;
+    private makeSessionUnresolvedResult;
     private writeAuditRecord;
     private makeDriftBlockResult;
     private makeDenyResult;
@@ -2521,6 +3166,13 @@ interface BudgetEventRecord {
     readonly timestamp: string;
     readonly timestamp_ms: number;
     readonly created_at: string;
+    /**
+     * Upstream attribution read from the referenced audit record via LEFT
+     * JOIN (issue #292) — never a stored ledger column. Null on singular-mode
+     * records, dangling or null `audit_record_id`, and rows predating the
+     * audit column; a null renders as empty/absent, never a made-up label.
+     */
+    readonly upstream: string | null;
 }
 /** One page of a budget's event history plus the unpaginated total. */
 interface BudgetEventsPage {
@@ -2611,6 +3263,13 @@ interface GovernanceServiceOptions {
     readonly spendLimiter?: SpendLimiter;
     /** Budget engine for named cross-tool budgets (issue #14). */
     readonly budgetEngine?: BudgetEngine;
+    /**
+     * Compiled session identity config (issue #218): the sideband door gets
+     * the SAME on_unresolved policy as the MCP door — an adapter omitting
+     * session_id while a session-keyed control is engaged is denied under
+     * `deny`, pools under `anonymous`. Defaults to the schema default chain.
+     */
+    readonly session?: CompiledSessionIdentity;
     readonly auditWriter?: AuditWriter;
     /** Default approval timeout (ms) when a rule sets none. */
     readonly approvalTimeoutMs?: number;
@@ -2630,6 +3289,7 @@ interface GovernanceServiceOptions {
 declare class GovernanceService {
     private policy;
     private readonly environment;
+    private readonly session;
     private readonly evidenceStore;
     private readonly approvalRouter;
     private readonly rateLimiter;
@@ -2789,6 +3449,22 @@ declare class GovernanceConfigError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Map a header/body agreement rejection (issue #226) onto the audit record
+ * shape, mirroring the `missing_tool_name` precedent: `policy_decision:
+ * 'rejected'`, no rule evaluated, nothing forwarded, written by the caller
+ * via `pushImmediate`. The snake_case mapping lives here alone — the
+ * rejection payload itself stays camelCase protocol facts (`mcp/types.ts`).
+ *
+ * `record_kind` stays `'tool_call'` for the whole class, non-tool methods
+ * included: it is the MCP-door request bucket, and `block_reason` is the
+ * query key. `tool_name` carries the body's name-bearing field (the body
+ * truth an investigator filters for) when the method has one, else the
+ * reserved `'<header_mismatch>'` sentinel — either way `top_tools` already
+ * excludes rejected records, so these rows never pollute tool rankings.
+ */
+declare function buildHeaderMismatchAuditRecord(rejection: HeaderMismatchRejection, environment?: string, upstream?: string): Omit<AuditRecord, 'id' | 'created_at'>;
+
 /** @internal Exported for testing only. */
 declare class QueueChannel implements ApprovalChannel {
     readonly type = "dashboard";
@@ -2915,6 +3591,10 @@ interface ActionEvent {
     readonly block_reason: string | null;
     readonly approval_status: string | null;
     readonly session_id: string | null;
+    /** Identity strategy that produced session_id (issue #218), or null. */
+    readonly session_source: string | null;
+    /** The client's verbatim MCP-Protocol-Version wire claim (issue #219), or null. */
+    readonly protocol_version: string | null;
     readonly agent_id: string | null;
     readonly environment: string | null;
     readonly timestamp: string;
@@ -2927,6 +3607,8 @@ interface ActionEvent {
     readonly matched_rule_index: number | null;
     readonly record_kind: AuditRecord['record_kind'];
     readonly origin: string;
+    /** Upstream attribution from the audit record (issue #292), or null. */
+    readonly upstream: string | null;
 }
 /** Payload for an approval_requested event. */
 interface ApprovalRequestedEvent {
@@ -2934,6 +3616,8 @@ interface ApprovalRequestedEvent {
     readonly tool_name: string;
     readonly channel: string;
     readonly requested_at: string;
+    /** Upstream attribution from the ticket (issue #292), or null. */
+    readonly upstream: string | null;
 }
 /** Payload for an approval_resolved event. */
 interface ApprovalResolvedEvent {
@@ -2949,6 +3633,11 @@ interface LimitWarningEvent {
     readonly current: number;
     readonly limit: number;
     readonly utilization: number;
+    /**
+     * Upstream name parsed from a partitioned bucket key (issue #292), or
+     * null — session keys, singular tool keys, and sideband keys have no door.
+     */
+    readonly upstream: string | null;
 }
 /** Payload for approval notification delivery failures. */
 interface ApprovalNotificationFailedEvent {
@@ -3052,6 +3741,20 @@ interface DashboardAppOptions {
     readonly staticDir?: string;
     /** SSE heartbeat interval in milliseconds. Defaults to 30 000 (30s). */
     readonly sseHeartbeatMs?: number;
+    /**
+     * @internal Test seam for the concurrent-connection cap (issue #285), so
+     * tests need not mint 256 real streams. Not wired to config — the cap is
+     * a hardcoded invariant (see MAX_SSE_CONNECTIONS).
+     */
+    readonly maxSseConnections?: number;
+    /**
+     * @internal Test seam for the stale-connection sweep cadence (issue
+     * #327), so sweeper tests need not wait out the production floor. `0`
+     * DISABLES the sweeper entirely (the repo-wide sweep-interval
+     * convention). Not wired to config — the 10 s floor stays the
+     * production default.
+     */
+    readonly sweepIntervalMs?: number;
 }
 /**
  * Create a Hono app for the dashboard REST + SSE API.
@@ -3061,4 +3764,4 @@ interface DashboardAppOptions {
  */
 declare function createDashboardApp(deps: DashboardAppDeps, options?: DashboardAppOptions): Hono;
 
-export { type AdapterLivenessEntry, type ApprovalAppOptions, type ApprovalChannel, type ApprovalOutcome, ApprovalQueue, type ApprovalQueueOptions, ApprovalRouter, type ApprovalRouterOptions, type ApprovalStatus, type ApprovalTicket, type AuditAggregateStats, type AuditInput, type AuditListResult, type AuditPaginationOptions, type AuditQueryFilters, type AuditRecord, AuditStore, type AuditStoreOptions, type AuditTimeBucket, AuditWriter, type AuditWriterOptions, type BudgetBreachContext, type BudgetBreachEvent, type BudgetBucketState, type BudgetCommitEvent, BudgetEngine, type BudgetEventRecord, type BudgetEventsPage, type BudgetLedgerRow, type BudgetLedgerSink, BudgetParseError, type BudgetState, type CompilePoliciesResult, type CompiledBudget, type CompiledBudgetContributor, type CompiledBudgetWindow, type CompiledPolicy, type CompiledPolicyRule, ConfigError, type CreateAppOptions, type DashboardAppDeps, type DashboardAppOptions, DashboardEventBus, type DashboardEventType, type DashboardEvents, EXPORT_MAX_RECORDS, type EvaluateInput, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernanceConfigError, GovernanceService, type GovernanceServiceOptions, GovernedForwarder, type GovernedForwarderOptions, type HelioConfig, type InstallScanInput, LIST_MAX_PAGE_SIZE, type MatchContext, type PolicyDecision, PolicyParseError, QueueChannel, type RateLimitCheckParams, type RateLimitKeyState, type RateLimitResult, RateLimiter, type RateLimiterOptions, type ResolveApprovalInput, type ServerHandle, type SessionState, type SlackActionAppOptions, SlackChannel, type SlackChannelOptions, type SpendLimitCheckParams, type SpendLimitKeyState, type SpendLimitResult, SpendLimiter, type SpendLimiterOptions, SseUpstreamForwarder, type SseUpstreamForwarderOptions, StdioForwarder, type StdioForwarderOptions, StreamableHttpForwarder, type StreamableHttpForwarderOptions, UpstreamForwarder, type UpstreamForwarderOptions, VERSION, WebhookChannel, type WebhookChannelOptions, type WireDecision, compileBudgets, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createSidebandApp, createSlackActionApp, evaluatePolicy, loadConfig, matchRule, startServer, startSidebandServer };
+export { type AdapterLivenessEntry, type ApprovalAppOptions, type ApprovalChannel, type ApprovalOutcome, ApprovalQueue, type ApprovalQueueOptions, ApprovalRouter, type ApprovalRouterOptions, type ApprovalStatus, type ApprovalTicket, type AuditAggregateStats, type AuditInput, type AuditListResult, type AuditPaginationOptions, type AuditQueryFilters, type AuditRecord, AuditStore, type AuditStoreOptions, type AuditTimeBucket, AuditWriter, type AuditWriterOptions, type BudgetBreachContext, type BudgetBreachEvent, type BudgetBucketState, type BudgetCommitEvent, BudgetEngine, type BudgetEventRecord, type BudgetEventsPage, type BudgetLedgerRow, type BudgetLedgerSink, BudgetParseError, type BudgetState, type CompilePoliciesResult, type CompiledBudget, type CompiledBudgetContributor, type CompiledBudgetWindow, type CompiledPolicy, type CompiledPolicyRule, ConfigError, type CreateAppOptions, type CreateMultiAppOptions, type DashboardAppDeps, type DashboardAppOptions, DashboardEventBus, type DashboardEventType, type DashboardEvents, EXPORT_MAX_RECORDS, type EvaluateInput, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernanceConfigError, GovernanceService, type GovernanceServiceOptions, GovernedForwarder, type GovernedForwarderOptions, type HeaderMismatchRejection, type HelioConfig, type InstallScanInput, LIST_MAX_PAGE_SIZE, type MatchContext, type NamedHelioConfig, type PolicyDecision, PolicyParseError, QueueChannel, type RateLimitCheckParams, type RateLimitKeyState, type RateLimitResult, RateLimiter, type RateLimiterOptions, type ResolveApprovalInput, type ServerHandle, type SessionState, type SingularHelioConfig, type SlackActionAppOptions, SlackChannel, type SlackChannelOptions, type SpendLimitCheckParams, type SpendLimitKeyState, type SpendLimitResult, SpendLimiter, type SpendLimiterOptions, SseUpstreamForwarder, type SseUpstreamForwarderOptions, StdioForwarder, type StdioForwarderOptions, StreamableHttpForwarder, type StreamableHttpForwarderOptions, UpstreamForwarder, type UpstreamForwarderOptions, VERSION, WebhookChannel, type WebhookChannelOptions, type WireDecision, buildHeaderMismatchAuditRecord, compileBudgets, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createMultiApp, createSidebandApp, createSlackActionApp, evaluatePolicy, isNamedConfig, isSingularConfig, loadConfig, matchRule, startServer, startSidebandServer };