@gethelio/proxy 0.4.0 → 0.5.0

package/dist/index.js

@@ -105,11 +105,23 @@ var annotationsMatchSchema = z.object({
   idempotentHint: z.boolean().optional(),
   openWorldHint: z.boolean().optional()
 }).strict();
+var metadataConditionSchema = z.union([
+  z.string(),
+  z.object({
+    eq: z.string().optional(),
+    neq: z.string().optional(),
+    contains: z.string().optional(),
+    regex: z.string().optional()
+  }).strict().refine((obj) => Object.keys(obj).length > 0, {
+    message: "At least one metadata condition operator is required"
+  })
+]);
 var matchSchema = z.object({
   tool: z.string().optional(),
   annotations: annotationsMatchSchema.optional(),
   input: z.record(z.string(), inputConditionSchema).optional(),
-  environment: z.string().optional()
+  environment: z.string().optional(),
+  metadata: z.record(z.string(), metadataConditionSchema).optional()
 }).strict();
 var policyActionSchema = z.enum([
   "allow",
@@ -133,12 +145,12 @@ var spendLimitSchema = z.object({
   limit: z.number(),
   currency: z.string(),
   window: durationSchema,
-  key: z.enum(["tool", "agent", "session"]).optional()
+  key: z.enum(["tool", "agent", "session", "sender_id"]).optional()
 }).strict();
 var limitsSchema = z.object({
   max_calls: z.number().int().positive().optional(),
   window: durationSchema.optional(),
-  key: z.enum(["tool", "agent", "session"]).optional(),
+  key: z.enum(["tool", "agent", "session", "sender_id"]).optional(),
   max_spend: spendLimitSchema.optional()
 }).strict();
 var feedbackSchema = z.object({
@@ -156,11 +168,30 @@ var policyRuleSchema = z.object({
   limits: limitsSchema.optional(),
   feedback: feedbackSchema.optional()
 }).strict();
+var installMatchSchema = z.object({
+  name: z.string().optional(),
+  // glob, picomatch (same engine as match.tool)
+  source: z.string().optional(),
+  // exact ecosystem match (npm | pip | …)
+  metadata: z.record(z.string(), metadataConditionSchema).optional()
+}).strict();
+var installRuleSchema = z.object({
+  name: z.string().optional(),
+  match: installMatchSchema,
+  action: z.enum(["deny_install", "allow"]),
+  feedback: feedbackSchema.optional()
+}).strict();
+var installSchema = z.object({
+  default: z.enum(["allow", "deny"]).default("allow"),
+  rules: z.array(installRuleSchema).default([])
+}).strict();
 var policiesSchema = z.object({
   default: z.enum(["allow", "deny"]).default("allow"),
   flag_destructive: z.enum(["log", "require_approval"]).optional(),
   dry_run: z.boolean().default(false),
   rules: z.array(policyRuleSchema).default([]),
+  /** Install-time policy (issue #13 — deny_install). Optional; absent ⇒ observational. */
+  install: installSchema.optional(),
   /**
    * How to treat calls to a tool whose definition (annotations, schemas,
    * description) has drifted from the baseline Helio captured on first
@@ -221,7 +252,14 @@ var auditSchema = z.object({
 var sdkSchema = z.object({
   enabled: z.boolean().default(false),
   port: z.number().int().min(1).max(65535).default(3200),
-  host: z.string().default("127.0.0.1")
+  host: z.string().default("127.0.0.1"),
+  /**
+   * How long a sideband `/evaluate` decision waits for its `/audit` before the
+   * proxy finalizes it as `evaluation_expired` (issue #12, D4). Bounds the
+   * pending-evaluation registry; an adapter crash cannot silently drop a
+   * decided-allowed call from the trail.
+   */
+  evaluation_ttl: durationSchema.default("10m")
 });
 var helioConfigBaseSchema = z.object({
   version: z.literal("1"),
@@ -284,6 +322,22 @@ var helioConfigSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
         message: `Rule sets match.environment="${rule.match.environment}" but top-level \`environment\` is not configured. Set top-level environment to enable env-scoped rules.`
       });
     }
+    if (!cfg.sdk.enabled) {
+      if (rule.limits?.key === "sender_id") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["policies", "rules", ruleIndex, "limits", "key"],
+          message: 'limits.key "sender_id" requires the SDK sideband (sdk.enabled: true) \u2014 sender_id is supplied by hook adapters and is absent on the MCP path.'
+        });
+      }
+      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" requires the SDK sideband (sdk.enabled: true) \u2014 sender_id is supplied by hook adapters and is absent on the MCP path.'
+        });
+      }
+    }
     if (rule.action === "rate_limit") {
       if (rule.limits?.max_calls === void 0) {
         ctx.addIssue({
@@ -425,6 +479,7 @@ var PolicyParseError = class extends Error {
 
 // src/policy/parser.ts
 var INPUT_OPERATORS = ["eq", "neq", "gt", "gte", "lt", "lte", "contains", "regex"];
+var METADATA_OPERATORS = ["eq", "neq", "contains", "regex"];
 function compilePolicies(config) {
   const warnings = [];
   const rules = config.rules.map((rule, index) => compileRule(rule, index, warnings));
@@ -433,10 +488,36 @@ function compilePolicies(config) {
     flagDestructive: config.flag_destructive,
     ...config.dry_run && { dryRun: true },
     ...config.on_tool_drift && { onToolDrift: config.on_tool_drift },
-    rules
+    rules,
+    ...config.install && { install: compileInstallPolicy(config.install) }
   };
   return { policy, warnings };
 }
+function compileInstallPolicy(install) {
+  return {
+    defaultAction: install.default,
+    rules: install.rules.map((rule, index) => {
+      const name = rule.match.name !== void 0 ? compileToolMatcher(rule.match.name, index, rule.name) : void 0;
+      const metadata = rule.match.metadata !== void 0 ? flattenMetadataConditions(rule.match.metadata, index, rule.name) : void 0;
+      return {
+        index,
+        ...rule.name !== void 0 && { name: rule.name },
+        match: {
+          ...name !== void 0 && { name },
+          ...rule.match.source !== void 0 && { source: rule.match.source },
+          ...metadata !== void 0 && { metadata }
+        },
+        action: rule.action,
+        ...rule.feedback !== void 0 && {
+          feedback: {
+            message: rule.feedback.message,
+            ...rule.feedback.suggestion !== void 0 && { suggestion: rule.feedback.suggestion }
+          }
+        }
+      };
+    })
+  };
+}
 function compileRule(rule, index, warnings) {
   const match = compileMatch(rule.match, index, rule.name);
   const approval = compileApproval(rule.approval);
@@ -469,7 +550,10 @@ function compileMatch(match, ruleIndex, ruleName) {
     ...match.input !== void 0 && {
       input: flattenInputConditions(match.input, ruleIndex, ruleName)
     },
-    ...match.environment !== void 0 && { environment: match.environment }
+    ...match.environment !== void 0 && { environment: match.environment },
+    ...match.metadata !== void 0 && {
+      metadata: flattenMetadataConditions(match.metadata, ruleIndex, ruleName)
+    }
   };
 }
 function compileToolMatcher(pattern, ruleIndex, ruleName) {
@@ -521,6 +605,43 @@ function flattenInputConditions(input, ruleIndex, ruleName) {
   }
   return conditions;
 }
+function flattenMetadataConditions(metadata, ruleIndex, ruleName) {
+  const conditions = [];
+  for (const [key, raw] of Object.entries(metadata)) {
+    if (typeof raw === "string") {
+      conditions.push({ key, operator: "eq", value: raw });
+      continue;
+    }
+    for (const op of METADATA_OPERATORS) {
+      const value = raw[op];
+      if (value === void 0) continue;
+      if (op === "regex") {
+        if (!safeRegex(value)) {
+          throw new PolicyParseError(
+            `catastrophic regex "${value}" for metadata key "${key}": pattern is vulnerable to ReDoS and has been rejected. Rewrite with bounded quantifiers (e.g. {1,100}) or split into simpler rules.`,
+            ruleIndex,
+            ruleName
+          );
+        }
+        let compiledRegex;
+        try {
+          compiledRegex = new RegExp(value);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          throw new PolicyParseError(
+            `invalid regex "${value}" for metadata key "${key}": ${msg}`,
+            ruleIndex,
+            ruleName
+          );
+        }
+        conditions.push({ key, operator: op, value, regex: compiledRegex });
+      } else {
+        conditions.push({ key, operator: op, value });
+      }
+    }
+  }
+  return conditions;
+}
 function compileApproval(approval) {
   if (!approval) return void 0;
   return {
@@ -2155,12 +2276,31 @@ function matchEnvironment(required, ctx) {
   if (ctx.environment === void 0) return false;
   return ctx.environment === required;
 }
+function matchMetadata(conditions, ctx) {
+  if (conditions.length === 0) return true;
+  if (ctx.metadata === void 0) return false;
+  for (const condition of conditions) {
+    const value = ctx.metadata[condition.key];
+    const matched = evaluateCondition(
+      {
+        path: condition.key,
+        operator: condition.operator,
+        value: condition.value,
+        regex: condition.regex
+      },
+      value
+    );
+    if (!matched) return false;
+  }
+  return true;
+}
 function matchRule(rule, ctx) {
   const { match } = rule;
   if (match.tool !== void 0 && !matchTool(match.tool, ctx)) return false;
   if (match.annotations !== void 0 && !matchAnnotations(match.annotations, ctx)) return false;
   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;
   return true;
 }
 
@@ -2183,6 +2323,197 @@ function evaluatePolicy(policy, ctx) {
   };
 }
 
+// src/evidence/grounding.ts
+function checkEvidence(store, sessionId, requirements) {
+  if (requirements.length === 0) {
+    return { satisfied: true, missing: [], expired: [], found: [] };
+  }
+  const found = [];
+  const missing = [];
+  const expired = [];
+  for (const key of requirements) {
+    const valid = store.getEvidence(sessionId, key);
+    if (valid) {
+      found.push(key);
+    } else if (store.hasSeenEvidence(sessionId, key)) {
+      expired.push(key);
+    } else {
+      missing.push(key);
+    }
+  }
+  return {
+    satisfied: missing.length === 0 && expired.length === 0,
+    missing,
+    expired,
+    found
+  };
+}
+function checkDependencies(store, sessionId, requirements, options = {}) {
+  if (requirements.length === 0) {
+    return { satisfied: true, missing: [] };
+  }
+  const requireSuccess = options.requireSuccess ?? true;
+  const missing = [];
+  for (const toolName of requirements) {
+    const satisfied = requireSuccess ? store.hasSuccessfulTool(sessionId, toolName) : store.hasCompletedTool(sessionId, toolName);
+    if (!satisfied) {
+      missing.push(toolName);
+    }
+  }
+  return {
+    satisfied: missing.length === 0,
+    missing
+  };
+}
+
+// src/policy/decision-pipeline.ts
+function decide(input) {
+  const { toolName, toolArguments, sessionId, policy, environment, evidenceStore } = input;
+  const annotations = input.baselineAnnotations;
+  const driftEvent = input.driftEvent;
+  const driftMode = policy.onToolDrift ?? "block";
+  const metadata = buildMetadataView(input.metadata, input.agentId);
+  let decision = evaluatePolicy(policy, {
+    toolName,
+    annotations,
+    toolArguments,
+    environment,
+    metadata
+  });
+  if (driftEvent && driftMode === "log") {
+    const currentDecision = evaluatePolicy(policy, {
+      toolName,
+      annotations: input.currentAnnotations,
+      toolArguments,
+      environment,
+      metadata
+    });
+    decision = stricterDecision(decision, currentDecision);
+  }
+  const baselineDestructive = annotations?.destructiveHint ?? true;
+  const currentDestructive = driftEvent && driftMode === "log" ? input.currentAnnotations?.destructiveHint ?? true : false;
+  const isDestructive = baselineDestructive || currentDestructive;
+  let flaggedDestructive = false;
+  if (isDestructive && !decision.matchedRule && policy.flagDestructive) {
+    flaggedDestructive = true;
+    if (policy.flagDestructive === "log") {
+      console.error(`[helio] Destructive tool detected: ${toolName} (no matching rule)`);
+    } else {
+      decision = {
+        action: "require_approval",
+        matchedRule: void 0,
+        reason: `Destructive tool "${toolName}" auto-escalated by flag_destructive policy`
+      };
+    }
+  }
+  let driftBlocked = false;
+  if (driftEvent && driftMode !== "log") {
+    driftBlocked = driftMode === "block";
+    decision = {
+      action: driftMode === "block" ? "deny" : "require_approval",
+      matchedRule: void 0,
+      reason: `Tool "${toolName}" definition drifted from baseline (${driftEvent.changes.map((change) => change.aspect).join(", ")})`
+    };
+  }
+  const originalAction = decision.action;
+  let evidenceResult;
+  let dependencyResult;
+  let evidenceBlocked = false;
+  let sessionBlocked = false;
+  const requiresGroundedSession = decision.action !== "deny" && !!decision.matchedRule && ((decision.matchedRule.evidence?.requires.length ?? 0) > 0 || (decision.matchedRule.requires?.length ?? 0) > 0);
+  if (requiresGroundedSession && !sessionId) {
+    sessionBlocked = true;
+    evidenceBlocked = true;
+    decision = {
+      action: "deny",
+      matchedRule: decision.matchedRule,
+      reason: "Mcp-Session-Id is required for evidence/dependency-gated policy rules"
+    };
+  }
+  if (decision.action !== "deny" && evidenceStore && sessionId && decision.matchedRule) {
+    const rule = decision.matchedRule;
+    if (rule.evidence?.requires.length) {
+      evidenceResult = checkEvidence(evidenceStore, sessionId, rule.evidence.requires);
+      if (!evidenceResult.satisfied) {
+        evidenceBlocked = true;
+        const problemKeys = [...evidenceResult.missing, ...evidenceResult.expired];
+        decision = {
+          action: "deny",
+          matchedRule: rule,
+          reason: `Required evidence not satisfied: ${problemKeys.join(", ")}`
+        };
+      }
+    }
+    if (!evidenceBlocked && rule.requires?.length) {
+      dependencyResult = checkDependencies(evidenceStore, sessionId, rule.requires, {
+        requireSuccess: rule.requiresSuccess ?? true
+      });
+      if (!dependencyResult.satisfied) {
+        evidenceBlocked = true;
+        decision = {
+          action: "deny",
+          matchedRule: rule,
+          reason: `Required tool calls not completed: ${dependencyResult.missing.join(", ")}`
+        };
+      }
+    }
+  }
+  const isPerRuleDryRun = originalAction === "dry_run";
+  const isGlobalDryRun = policy.dryRun === true;
+  const isDryRun = (isPerRuleDryRun || isGlobalDryRun) && !sessionBlocked;
+  return {
+    decision,
+    originalAction,
+    driftEvent,
+    driftMode,
+    driftBlocked,
+    flaggedDestructive,
+    evidenceResult,
+    dependencyResult,
+    evidenceBlocked,
+    sessionBlocked,
+    isDryRun
+  };
+}
+var ACTION_SEVERITY = {
+  deny: 5,
+  require_approval: 4,
+  dry_run: 3,
+  spend_limit: 2,
+  rate_limit: 1,
+  allow: 0
+};
+function stricterDecision(a, b) {
+  return ACTION_SEVERITY[b.action] > ACTION_SEVERITY[a.action] ? b : a;
+}
+function buildMetadataView(metadata, agentId) {
+  if (agentId === void 0) return metadata;
+  return { ...metadata ?? {}, agent_id: agentId };
+}
+
+// src/util/canonical-json.ts
+function canonicalize(value) {
+  const encoded = JSON.stringify(sortKeysDeep(value));
+  return encoded ?? "";
+}
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value !== null && typeof value === "object") {
+    const source = value;
+    const out = {};
+    for (const key of Object.keys(source).sort()) {
+      Object.defineProperty(out, key, {
+        value: sortKeysDeep(source[key]),
+        enumerable: true,
+        writable: true,
+        configurable: true
+      });
+    }
+    return out;
+  }
+  return value;
+}
+
 // src/policy/annotation-cache.ts
 var ASPECT_FIELDS = [
   "annotations",
@@ -2285,6 +2616,74 @@ var ToolAnnotationCache = class {
     this.currentAnnotations = currentAnnotations;
     return { updated: true, baselined, drifted, reverted };
   }
+  /**
+   * Incrementally merge a single tool definition into the cache (issue #12, D6).
+   *
+   * Unlike {@link update}, this touches only the named tool: it adds to (never
+   * rebuilds) the `present` set and `currentAnnotations` map. The sideband
+   * governance path feeds adapter-origin tools one definition at a time (each
+   * `/evaluate` carries at most one), so routing them through the whole-list
+   * `update()` would wipe every other tool's current-annotation snapshot on
+   * each call and silently degrade the stricter-of-both log-mode drift
+   * evaluation. The MCP whole-list path is unaffected — it keeps calling
+   * `update()`. Each origin owns its own cache instance, so the accumulate
+   * semantics here never mix with update()'s replace semantics.
+   *
+   * `toolDefinition` must already be in MCP shape (`inputSchema`/`outputSchema`
+   * camelCase); the governance service maps the wire `tool` object before
+   * calling. Returns the same result shape as `update()` (for one tool).
+   */
+  updateSingle(toolDefinition) {
+    if (typeof toolDefinition !== "object" || toolDefinition === null) {
+      return { updated: false, baselined: [], drifted: [], reverted: [] };
+    }
+    const t = toolDefinition;
+    const name = t["name"];
+    if (typeof name !== "string") {
+      return { updated: false, baselined: [], drifted: [], reverted: [] };
+    }
+    const baselined = [];
+    const drifted = [];
+    const reverted = [];
+    this.present.add(name);
+    const annotations = extractAnnotations(t);
+    this.currentAnnotations.set(name, annotations);
+    const definitionKey = canonicalize(t);
+    const baseline = this.baselines.get(name);
+    if (!baseline) {
+      this.baselines.set(name, { definition: t, definitionKey, annotations });
+      baselined.push(name);
+      if (this.driftedTools.has(name)) {
+        this.driftedTools.delete(name);
+        reverted.push(name);
+      }
+      return { updated: true, baselined, drifted, reverted };
+    }
+    if (definitionKey === baseline.definitionKey) {
+      if (this.driftedTools.has(name)) {
+        this.driftedTools.delete(name);
+        reverted.push(name);
+      }
+      return { updated: true, baselined, drifted, reverted };
+    }
+    const changes = [];
+    for (const field of ASPECT_FIELDS) {
+      const baselineValue = baseline.definition[field];
+      const currentValue = t[field];
+      if (canonicalize(baselineValue) !== canonicalize(currentValue)) {
+        changes.push({ aspect: field, baseline: baselineValue, current: currentValue });
+      }
+    }
+    if (changes.length === 0) {
+      changes.push({ aspect: "other", baseline: baseline.definition, current: t });
+    }
+    const event = { toolName: name, changes };
+    const existing = this.driftedTools.get(name);
+    const isNewDrift = !existing || canonicalize(existing.changes) !== canonicalize(changes);
+    this.driftedTools.set(name, event);
+    if (isNewDrift) drifted.push(event);
+    return { updated: true, baselined, drifted, reverted };
+  }
   /**
    * Get the **baseline** annotations for a tool — the definition first seen,
    * not the latest upstream claim. Returns `undefined` if the tool has no
@@ -2318,27 +2717,6 @@ function extractAnnotations(tool) {
   const annotations = tool["annotations"];
   return annotations && typeof annotations === "object" ? annotations : void 0;
 }
-function canonicalize(value) {
-  const encoded = JSON.stringify(sortKeysDeep(value));
-  return encoded ?? "";
-}
-function sortKeysDeep(value) {
-  if (Array.isArray(value)) return value.map(sortKeysDeep);
-  if (value !== null && typeof value === "object") {
-    const source = value;
-    const out = {};
-    for (const key of Object.keys(source).sort()) {
-      Object.defineProperty(out, key, {
-        value: sortKeysDeep(source[key]),
-        enumerable: true,
-        writable: true,
-        configurable: true
-      });
-    }
-    return out;
-  }
-  return value;
-}
 function extractTools(body) {
   if (typeof body !== "object" || body === null) return null;
   const b = body;
@@ -2350,49 +2728,6 @@ function extractTools(body) {
   return tools;
 }
 
-// src/evidence/grounding.ts
-function checkEvidence(store, sessionId, requirements) {
-  if (requirements.length === 0) {
-    return { satisfied: true, missing: [], expired: [], found: [] };
-  }
-  const found = [];
-  const missing = [];
-  const expired = [];
-  for (const key of requirements) {
-    const valid = store.getEvidence(sessionId, key);
-    if (valid) {
-      found.push(key);
-    } else if (store.hasSeenEvidence(sessionId, key)) {
-      expired.push(key);
-    } else {
-      missing.push(key);
-    }
-  }
-  return {
-    satisfied: missing.length === 0 && expired.length === 0,
-    missing,
-    expired,
-    found
-  };
-}
-function checkDependencies(store, sessionId, requirements, options = {}) {
-  if (requirements.length === 0) {
-    return { satisfied: true, missing: [] };
-  }
-  const requireSuccess = options.requireSuccess ?? true;
-  const missing = [];
-  for (const toolName of requirements) {
-    const satisfied = requireSuccess ? store.hasSuccessfulTool(sessionId, toolName) : store.hasCompletedTool(sessionId, toolName);
-    if (!satisfied) {
-      missing.push(toolName);
-    }
-  }
-  return {
-    satisfied: missing.length === 0,
-    missing
-  };
-}
-
 // src/feedback/self-repair.ts
 function ruleInfo(rule) {
   return {
@@ -2604,6 +2939,7 @@ var GovernedForwarder = class {
   spendLimiter;
   annotationCache = new ToolAnnotationCache();
   agentKeyWarned = false;
+  senderKeyWarned = false;
   constructor(inner, policy, options) {
     this.inner = inner;
     this.policy = policy;
@@ -2765,7 +3101,10 @@ var GovernedForwarder = class {
       approval_wait_ms: 0,
       proxy_compute_ms: 0,
       flagged_destructive: false,
-      dry_run: false
+      dry_run: false,
+      record_kind: "drift_event",
+      origin: "mcp",
+      metadata: null
     });
   }
   async handleToolsCall(request) {
@@ -2777,99 +3116,28 @@ var GovernedForwarder = class {
       return this.inner.forward(request);
     }
     const toolArguments = params?.["arguments"] && typeof params["arguments"] === "object" ? params["arguments"] : void 0;
-    const annotations = this.annotationCache.get(toolName);
-    const driftEvent = this.annotationCache.getDrift(toolName);
-    const driftMode = this.policy.onToolDrift ?? "block";
-    let decision = evaluatePolicy(this.policy, {
-      toolName,
-      annotations,
+    const {
+      decision,
+      driftEvent,
+      driftMode,
+      driftBlocked,
+      flaggedDestructive,
+      evidenceResult,
+      dependencyResult,
+      evidenceBlocked,
+      sessionBlocked,
+      isDryRun
+    } = decide({
+      toolName,
       toolArguments,
-      environment: this.environment
+      sessionId: request.sessionId,
+      policy: this.policy,
+      environment: this.environment,
+      evidenceStore: this.evidenceStore,
+      baselineAnnotations: this.annotationCache.get(toolName),
+      currentAnnotations: this.annotationCache.getCurrent(toolName),
+      driftEvent: this.annotationCache.getDrift(toolName)
     });
-    if (driftEvent && driftMode === "log") {
-      const currentDecision = evaluatePolicy(this.policy, {
-        toolName,
-        annotations: this.annotationCache.getCurrent(toolName),
-        toolArguments,
-        environment: this.environment
-      });
-      decision = stricterDecision(decision, currentDecision);
-    }
-    const baselineDestructive = annotations?.destructiveHint ?? true;
-    const currentDestructive = driftEvent && driftMode === "log" ? this.annotationCache.getCurrent(toolName)?.destructiveHint ?? true : false;
-    const isDestructive = baselineDestructive || currentDestructive;
-    let flaggedDestructive = false;
-    if (isDestructive && !decision.matchedRule && this.policy.flagDestructive) {
-      flaggedDestructive = true;
-      if (this.policy.flagDestructive === "log") {
-        console.error(`[helio] Destructive tool detected: ${toolName} (no matching rule)`);
-      } else {
-        decision = {
-          action: "require_approval",
-          matchedRule: void 0,
-          reason: `Destructive tool "${toolName}" auto-escalated by flag_destructive policy`
-        };
-      }
-    }
-    let driftBlocked = false;
-    if (driftEvent && driftMode !== "log") {
-      driftBlocked = driftMode === "block";
-      decision = {
-        action: driftMode === "block" ? "deny" : "require_approval",
-        matchedRule: void 0,
-        reason: `Tool "${toolName}" definition drifted from baseline (${driftEvent.changes.map((change) => change.aspect).join(", ")})`
-      };
-    }
-    const originalAction = decision.action;
-    let evidenceResult;
-    let dependencyResult;
-    let evidenceBlocked = false;
-    let sessionBlocked = false;
-    const requiresGroundedSession = decision.action !== "deny" && !!decision.matchedRule && ((decision.matchedRule.evidence?.requires.length ?? 0) > 0 || (decision.matchedRule.requires?.length ?? 0) > 0);
-    if (requiresGroundedSession && !request.sessionId) {
-      sessionBlocked = true;
-      evidenceBlocked = true;
-      decision = {
-        action: "deny",
-        matchedRule: decision.matchedRule,
-        reason: "Mcp-Session-Id is required for evidence/dependency-gated policy rules"
-      };
-    }
-    if (decision.action !== "deny" && this.evidenceStore && request.sessionId && decision.matchedRule) {
-      const rule = decision.matchedRule;
-      if (rule.evidence?.requires.length) {
-        evidenceResult = checkEvidence(
-          this.evidenceStore,
-          request.sessionId,
-          rule.evidence.requires
-        );
-        if (!evidenceResult.satisfied) {
-          evidenceBlocked = true;
-          const problemKeys = [...evidenceResult.missing, ...evidenceResult.expired];
-          decision = {
-            action: "deny",
-            matchedRule: rule,
-            reason: `Required evidence not satisfied: ${problemKeys.join(", ")}`
-          };
-        }
-      }
-      if (!evidenceBlocked && rule.requires?.length) {
-        dependencyResult = checkDependencies(this.evidenceStore, request.sessionId, rule.requires, {
-          requireSuccess: rule.requiresSuccess ?? true
-        });
-        if (!dependencyResult.satisfied) {
-          evidenceBlocked = true;
-          decision = {
-            action: "deny",
-            matchedRule: rule,
-            reason: `Required tool calls not completed: ${dependencyResult.missing.join(", ")}`
-          };
-        }
-      }
-    }
-    const isPerRuleDryRun = originalAction === "dry_run";
-    const isGlobalDryRun = this.policy.dryRun === true;
-    const isDryRun = (isPerRuleDryRun || isGlobalDryRun) && !sessionBlocked;
     let result;
     let approvalOutcome;
     let approvalWaitMs = 0;
@@ -3166,6 +3434,14 @@ var GovernedForwarder = class {
           );
         }
         return `tool:${toolName}`;
+      case "sender_id":
+        if (!this.senderKeyWarned) {
+          this.senderKeyWarned = true;
+          console.error(
+            '[helio] Warning: limits.key "sender_id" has no sender on the MCP path, falling back to "tool"'
+          );
+        }
+        return `tool:${toolName}`;
       case "tool":
       default:
         return `tool:${toolName}`;
@@ -3267,7 +3543,10 @@ var GovernedForwarder = class {
       approval_wait_ms: approvalWaitMs,
       proxy_compute_ms: proxyComputeMs,
       flagged_destructive: flaggedDestructive,
-      dry_run: isDryRun ?? false
+      dry_run: isDryRun ?? false,
+      record_kind: "tool_call",
+      origin: "mcp",
+      metadata: null
     };
     const isEnforcementDecision = !isDryRun && (!wasForwarded || approvalOutcome !== void 0);
     if (isEnforcementDecision) {
@@ -3373,17 +3652,6 @@ function collectAllowedEvidenceKeys(policy) {
   }
   return [...keys];
 }
-var ACTION_SEVERITY = {
-  deny: 5,
-  require_approval: 4,
-  dry_run: 3,
-  spend_limit: 2,
-  rate_limit: 1,
-  allow: 0
-};
-function stricterDecision(a, b) {
-  return ACTION_SEVERITY[b.action] > ACTION_SEVERITY[a.action] ? b : a;
-}
 function makeErrorResult(request, code, message, data) {
   const body = {
     jsonrpc: "2.0",
@@ -3516,6 +3784,46 @@ var RateLimiter = class {
       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.onWarning({ 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).
    *
@@ -3730,6 +4038,57 @@ var SpendLimiter = class {
       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.onWarning({
+        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).
    *
@@ -4175,8 +4534,9 @@ var EvidenceStore = class _EvidenceStore {
 };
 
 // src/evidence/api.ts
-import { Hono as Hono4 } from "hono";
-import { z as z4 } from "zod";
+import { Hono as Hono5 } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { z as z5 } from "zod";
 
 // src/auth/bearer.ts
 import { createHash, timingSafeEqual } from "crypto";
@@ -4188,22 +4548,176 @@ function verifyBearer(authHeader, expected) {
   return timingSafeEqual(actualDigest, expectedDigest);
 }
 
+// src/sideband/governance-api.ts
+import { Hono as Hono4 } from "hono";
+import { z as z4 } from "zod";
+import { createHash as createHash2 } from "crypto";
+var originSchema = z4.string().regex(/^[a-z0-9_-]{1,64}$/, "origin must match ^[a-z0-9_-]{1,64}$").default("sideband");
+var metadataSchema = z4.record(z4.string(), z4.unknown()).nullish();
+var toolDefinitionSchema = z4.object({
+  name: z4.string().min(1),
+  description: z4.string().optional(),
+  input_schema: z4.unknown().optional(),
+  output_schema: z4.unknown().optional(),
+  title: z4.string().optional(),
+  annotations: z4.record(z4.string(), z4.unknown()).optional()
+});
+var evaluateBody = z4.object({
+  origin: originSchema,
+  adapter_version: z4.string().max(64).optional(),
+  agent_id: z4.string().nullish(),
+  session_id: z4.string().nullish(),
+  tool: toolDefinitionSchema,
+  arguments: z4.record(z4.string(), z4.unknown()).optional(),
+  metadata: metadataSchema
+});
+var installScanBody = z4.object({
+  origin: originSchema,
+  agent_id: z4.string().nullish(),
+  session_id: z4.string().nullish(),
+  package: z4.object({
+    name: z4.string().min(1),
+    version: z4.string().optional(),
+    source: z4.string().max(64).optional(),
+    spec: z4.string().optional(),
+    url: z4.string().optional()
+  }),
+  metadata: metadataSchema
+});
+var auditBody = z4.object({
+  evaluation_id: z4.string().min(1),
+  status: z4.enum(["success", "error", "not_executed"]),
+  error: z4.string().optional(),
+  duration_ms: z4.number().optional(),
+  result: z4.unknown().optional(),
+  actual_amount: z4.number().optional()
+});
+var resolveBody = z4.object({
+  resolution: z4.enum(["approved", "denied", "timeout", "cancelled"]),
+  resolved_by: z4.string().optional(),
+  reason: z4.string().optional(),
+  scope: z4.enum(["once", "always"]).optional()
+});
+var MAX_METADATA_BYTES = 4 * 1024;
+function createGovernanceApp(service) {
+  const app = new Hono4();
+  const unavailable = () => ({ error: "governance_unavailable" });
+  app.post("/evaluate", async (c) => {
+    if (!service) return c.json(unavailable(), 503);
+    const parsed = await parseJson(c);
+    if ("error" in parsed) return c.json(parsed.error, 400);
+    const result = evaluateBody.safeParse(parsed.body);
+    if (!result.success) {
+      return c.json({ error: "Validation error", details: formatZodErrors(result.error) }, 400);
+    }
+    if (metadataTooLarge(result.data.metadata)) {
+      return c.json({ error: "metadata_too_large" }, 413);
+    }
+    const r = service.evaluate({
+      origin: result.data.origin,
+      adapter_version: result.data.adapter_version,
+      agent_id: result.data.agent_id ?? null,
+      session_id: result.data.session_id ?? null,
+      tool: result.data.tool,
+      arguments: result.data.arguments,
+      metadata: result.data.metadata ?? null
+    });
+    return c.json(r.body, asStatus(r.status));
+  });
+  app.post("/audit", async (c) => {
+    if (!service) return c.json(unavailable(), 503);
+    const parsed = await parseJson(c);
+    if ("error" in parsed) return c.json(parsed.error, 400);
+    const result = auditBody.safeParse(parsed.body);
+    if (!result.success) {
+      return c.json({ error: "Validation error", details: formatZodErrors(result.error) }, 400);
+    }
+    const hash = auditPayloadHash(result.data);
+    const r = service.audit(result.data, hash);
+    return c.json(r.body, asStatus(r.status));
+  });
+  app.post("/install-scan", async (c) => {
+    if (!service) return c.json(unavailable(), 503);
+    const parsed = await parseJson(c);
+    if ("error" in parsed) return c.json(parsed.error, 400);
+    const result = installScanBody.safeParse(parsed.body);
+    if (!result.success) {
+      return c.json({ error: "Validation error", details: formatZodErrors(result.error) }, 400);
+    }
+    if (metadataTooLarge(result.data.metadata)) {
+      return c.json({ error: "metadata_too_large" }, 413);
+    }
+    const r = service.installScan({
+      origin: result.data.origin,
+      agent_id: result.data.agent_id ?? null,
+      session_id: result.data.session_id ?? null,
+      package: result.data.package,
+      metadata: result.data.metadata ?? null
+    });
+    return c.json(r.body, asStatus(r.status));
+  });
+  app.post("/approval/:id/resolve", async (c) => {
+    if (!service) return c.json(unavailable(), 503);
+    const parsed = await parseJson(c);
+    if ("error" in parsed) return c.json(parsed.error, 400);
+    const result = resolveBody.safeParse(parsed.body);
+    if (!result.success) {
+      return c.json({ error: "Validation error", details: formatZodErrors(result.error) }, 400);
+    }
+    if ((result.data.resolution === "approved" || result.data.resolution === "denied") && !result.data.resolved_by) {
+      return c.json({ error: "resolved_by is required for approved/denied" }, 400);
+    }
+    const r = service.resolveApproval(c.req.param("id"), result.data);
+    return c.json(r.body, asStatus(r.status));
+  });
+  return app;
+}
+function isGovernancePath(path) {
+  return path === "/evaluate" || path === "/audit" || path === "/install-scan" || path.startsWith("/approval/");
+}
+async function parseJson(c) {
+  try {
+    return { body: await c.req.json() };
+  } catch {
+    return { error: { error: "Invalid JSON" } };
+  }
+}
+function metadataTooLarge(metadata) {
+  if (metadata == null) return false;
+  return Buffer.byteLength(canonicalize(metadata), "utf8") > MAX_METADATA_BYTES;
+}
+function auditPayloadHash(data) {
+  const semantic = {
+    status: data.status,
+    error: data.error ?? null,
+    duration_ms: data.duration_ms ?? null,
+    result: data.result ?? null,
+    actual_amount: data.actual_amount ?? null
+  };
+  return createHash2("sha256").update(canonicalize(semantic)).digest("hex");
+}
+function asStatus(status) {
+  return status;
+}
+
 // src/evidence/api.ts
-var postEvidenceBody = z4.object({
-  session_id: z4.string().min(1),
-  tool_name: z4.string().min(1),
-  evidence_key: z4.string().min(1),
-  evidence_data: z4.unknown().refine((v) => v !== void 0, { message: "Required" }),
-  ttl_seconds: z4.number().int().positive().optional()
+var SIDEBAND_BODY_LIMIT_BYTES = 1 * 1024 * 1024;
+var postEvidenceBody = z5.object({
+  session_id: z5.string().min(1),
+  tool_name: z5.string().min(1),
+  evidence_key: z5.string().min(1),
+  evidence_data: z5.unknown().refine((v) => v !== void 0, { message: "Required" }),
+  ttl_seconds: z5.number().int().positive().optional()
 });
-var postContextBody = z4.object({
-  session_id: z4.string().min(1),
-  key: z4.string().min(1),
-  value: z4.unknown().refine((v) => v !== void 0, { message: "Required" })
+var postContextBody = z5.object({
+  session_id: z5.string().min(1),
+  key: z5.string().min(1),
+  value: z5.unknown().refine((v) => v !== void 0, { message: "Required" })
 });
 function createSidebandApp(store, options = {}) {
-  const app = new Hono4();
-  const token = options.token && options.token.length > 0 ? options.token : void 0;
+  const app = new Hono5();
+  const sdkToken = options.token && options.token.length > 0 ? options.token : void 0;
+  const adapterToken = options.adapterToken && options.adapterToken.length > 0 ? options.adapterToken : void 0;
   app.use("*", async (c, next) => {
     const origin = c.req.header("origin");
     if (origin) {
@@ -4214,20 +4728,26 @@ function createSidebandApp(store, options = {}) {
     }
     await next();
   });
-  if (token) {
-    app.use("*", async (c, next) => {
-      if (c.req.path === "/healthz") {
-        await next();
-        return;
-      }
-      const authHeader = c.req.header("authorization");
-      if (!verifyBearer(authHeader, token)) {
-        return c.json({ error: "Unauthorized" }, 401);
-      }
+  app.use(
+    "*",
+    bodyLimit({
+      maxSize: SIDEBAND_BODY_LIMIT_BYTES,
+      onError: (c) => c.json({ error: "request_body_too_large" }, 413)
+    })
+  );
+  app.use("*", async (c, next) => {
+    if (c.req.path === "/healthz") {
       await next();
-    });
-  }
+      return;
+    }
+    const expected = isGovernancePath(c.req.path) ? adapterToken : sdkToken;
+    if (expected && !verifyBearer(c.req.header("authorization"), expected)) {
+      return c.json({ error: "Unauthorized" }, 401);
+    }
+    await next();
+  });
   app.get("/healthz", (c) => c.json({ status: "ok" }));
+  app.route("/", createGovernanceApp(options.governance));
   app.post("/evidence", async (c) => {
     let body;
     try {
@@ -4290,9 +4810,805 @@ function createSidebandApp(store, options = {}) {
   return app;
 }
 
+// src/sideband/governance-service.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/sideband/errors.ts
+var GovernanceConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GovernanceConfigError";
+  }
+};
+
+// src/sideband/governance-service.ts
+var MAX_ORIGINS = 32;
+var MAX_TOOLS_PER_ORIGIN = 1024;
+var MAX_TOOL_INPUT_BYTES = 64 * 1024;
+var MAX_PENDING_COUNT = 1e4;
+var MAX_PENDING_BYTES = 64 * 1024 * 1024;
+var MAX_SENDER_KEYS = 5e4;
+var SWEEP_INTERVAL_MS2 = 3e4;
+var GovernanceService = class {
+  policy;
+  environment;
+  evidenceStore;
+  approvalRouter;
+  rateLimiter;
+  spendLimiter;
+  auditWriter;
+  approvalTimeoutMs;
+  ttlMs;
+  now;
+  maxPending;
+  maxPendingBytes;
+  maxSenderKeys;
+  /** Distinct sender_id limit keys with live state (reservation registry, issue #13). */
+  senderKeys = /* @__PURE__ */ new Set();
+  pending = /* @__PURE__ */ new Map();
+  tombstones = /* @__PURE__ */ new Map();
+  caches = /* @__PURE__ */ new Map();
+  /** Native approval ticket id → its pending evaluation id, for on-access
+   * deadline enforcement on the resolve path. */
+  ticketToEvaluation = /* @__PURE__ */ new Map();
+  pendingBytes = 0;
+  sweepTimer = null;
+  closed = false;
+  constructor(options) {
+    this.policy = options.policy;
+    this.environment = options.environment;
+    this.evidenceStore = options.evidenceStore;
+    this.approvalRouter = options.approvalRouter;
+    this.rateLimiter = options.rateLimiter;
+    this.spendLimiter = options.spendLimiter;
+    this.auditWriter = options.auditWriter;
+    this.approvalTimeoutMs = options.approvalTimeoutMs ?? 3e5;
+    this.ttlMs = options.ttlMs ?? 6e5;
+    this.now = options.now ?? Date.now;
+    this.maxPending = options.maxPending ?? MAX_PENDING_COUNT;
+    this.maxPendingBytes = options.maxPendingBytes ?? MAX_PENDING_BYTES;
+    this.maxSenderKeys = options.maxSenderKeys ?? MAX_SENDER_KEYS;
+    this.assertApprovalRouter(this.policy);
+    const sweepMs = options.sweepIntervalMs ?? SWEEP_INTERVAL_MS2;
+    if (sweepMs > 0) {
+      this.sweepTimer = setInterval(() => {
+        this.sweep();
+      }, sweepMs);
+      this.sweepTimer.unref();
+    }
+  }
+  /** Swap the compiled policy on hot-reload (mirrors GovernedForwarder). */
+  updatePolicy(policy) {
+    this.assertApprovalRouter(policy);
+    this.policy = policy;
+  }
+  // -------------------------------------------------------------------------
+  // POST /evaluate
+  // -------------------------------------------------------------------------
+  evaluate(req) {
+    const reserved = reservedMetadataKey(req.metadata);
+    if (reserved) {
+      return { status: 400, body: { error: "reserved_metadata_key", key: reserved } };
+    }
+    const inputBytes = byteLength(req.arguments ?? {});
+    if (inputBytes > MAX_TOOL_INPUT_BYTES) {
+      return { status: 413, body: { error: "tool_input_too_large" } };
+    }
+    const entryBytes = inputBytes + byteLength(req.metadata ?? {});
+    if (!this.caches.has(req.origin) && this.caches.size >= MAX_ORIGINS) {
+      return { status: 400, body: { error: "origin_limit_exceeded" } };
+    }
+    if (this.pending.size >= this.maxPending || this.pendingBytes + entryBytes > this.maxPendingBytes) {
+      return { status: 503, body: { error: "evaluation_backlog_full" } };
+    }
+    const cache = this.cacheFor(req.origin);
+    const toolName = req.tool.name;
+    const hasDefinition = definitionProvided(req.tool);
+    if (hasDefinition) {
+      if (!cache.has(toolName) && cache.size >= MAX_TOOLS_PER_ORIGIN) {
+        return { status: 400, body: { error: "tool_baseline_limit" } };
+      }
+      cache.updateSingle(toMcpToolDef(req.tool));
+    }
+    const pipeline = decide({
+      toolName,
+      toolArguments: req.arguments,
+      sessionId: req.session_id ?? void 0,
+      policy: this.policy,
+      environment: this.environment,
+      evidenceStore: this.evidenceStore,
+      baselineAnnotations: cache.get(toolName),
+      currentAnnotations: cache.getCurrent(toolName),
+      driftEvent: cache.getDrift(toolName),
+      metadata: req.metadata ?? void 0,
+      agentId: req.agent_id ?? void 0
+    });
+    const { decision } = pipeline;
+    const evaluationId = randomUUID2();
+    const timestampIso = new Date(this.now()).toISOString();
+    let wire;
+    let limitPlan;
+    let limitsBlock;
+    const senderId = senderIdOf(req.metadata);
+    if (pipeline.isDryRun) {
+      wire = "dry_run";
+    } else if (decision.action === "deny") {
+      wire = "deny";
+    } else if (decision.action === "require_approval") {
+      wire = "require_approval";
+    } else if (decision.action === "rate_limit") {
+      const planned = this.planRate(decision, toolName, req.session_id, senderId);
+      if (planned?.plan && !this.reserveSenderKey(planned.plan.key)) {
+        return { status: 503, body: { error: "limit_capacity_exhausted" } };
+      }
+      limitPlan = planned?.plan;
+      limitsBlock = planned?.block ? { rate: planned.block } : void 0;
+      wire = planned?.allowed ? "allow" : "rate_limited";
+    } else if (decision.action === "spend_limit") {
+      const planned = this.planSpend(decision, toolName, req.session_id, req.arguments, senderId);
+      if (planned?.plan && !this.reserveSenderKey(planned.plan.key)) {
+        return { status: 503, body: { error: "limit_capacity_exhausted" } };
+      }
+      limitPlan = planned?.plan;
+      limitsBlock = planned?.block ? { spend: planned.block } : void 0;
+      wire = planned?.allowed ? "allow" : "spend_limited";
+    } else {
+      wire = "allow";
+    }
+    const matchedRuleName = decision.matchedRule?.name ?? null;
+    const matchedRuleIndex = decision.matchedRule?.index ?? null;
+    const responseBody = {
+      evaluation_id: evaluationId,
+      decision: wire,
+      reason: decision.reason,
+      matched_rule: matchedRuleName,
+      matched_rule_index: matchedRuleIndex
+    };
+    if (isBlocking(wire)) {
+      responseBody["feedback"] = buildFeedback(decision.matchedRule, decision.reason);
+    }
+    if (limitsBlock) responseBody["limits"] = limitsBlock;
+    if (wire === "dry_run") {
+      responseBody["dry_run"] = {
+        would_forward: decision.action === "allow" && !pipeline.evidenceBlocked,
+        evidence_satisfied: !pipeline.evidenceBlocked,
+        limits_ok: true
+      };
+    }
+    if (pipeline.driftEvent) {
+      responseBody["tool_drift"] = { changes: pipeline.driftEvent.changes };
+    }
+    if (isTerminalAtEvaluate(wire)) {
+      const auditId = this.writeAudit({
+        timestampIso,
+        origin: req.origin,
+        agentId: req.agent_id,
+        sessionId: req.session_id,
+        toolName,
+        toolInput: req.arguments ?? {},
+        metadata: req.metadata,
+        action: decision.action,
+        wire,
+        matchedRuleName,
+        matchedRuleIndex,
+        flaggedDestructive: pipeline.flaggedDestructive,
+        dryRun: wire === "dry_run",
+        recordKind: "tool_call",
+        limitsChain: limitsBlock
+      });
+      this.tombstones.set(evaluationId, {
+        auditRecordId: auditId,
+        payloadHash: null,
+        finalizedBy: "evaluate",
+        expiresAtMs: this.now() + this.ttlMs
+      });
+      return { status: 200, body: responseBody };
+    }
+    let approvalTicketId;
+    let ticketTimeoutAtMs;
+    if (wire === "require_approval") {
+      const router = this.approvalRouter;
+      if (!router) {
+        throw new GovernanceConfigError(
+          "[helio] invariant violation: require_approval decision without an approvalRouter"
+        );
+      }
+      const timeoutMs = decision.matchedRule?.approval?.timeoutMs ?? this.approvalTimeoutMs;
+      const ticket = router.createNativeTicket({
+        tool_name: toolName,
+        tool_input: req.arguments ?? {},
+        matched_rule: decision.matchedRule,
+        session_id: req.session_id,
+        origin: req.origin,
+        timeout_ms: timeoutMs
+      });
+      approvalTicketId = ticket.id;
+      ticketTimeoutAtMs = this.now() + timeoutMs;
+      responseBody["approval"] = {
+        id: ticket.id,
+        timeout_ms: timeoutMs,
+        resolve_path: `/approval/${ticket.id}/resolve`
+      };
+    }
+    const entry = {
+      evaluationId,
+      origin: req.origin,
+      agentId: req.agent_id,
+      sessionId: req.session_id,
+      toolName,
+      toolInput: req.arguments ?? {},
+      metadata: req.metadata,
+      action: decision.action,
+      matchedRuleName,
+      matchedRuleIndex,
+      flaggedDestructive: pipeline.flaggedDestructive,
+      limitPlan,
+      approvalTicketId,
+      timestampIso,
+      createdAtMs: this.now(),
+      evaluationExpiresAtMs: this.now() + this.ttlMs,
+      ticketTimeoutAtMs,
+      bytes: entryBytes
+    };
+    this.pending.set(evaluationId, entry);
+    this.pendingBytes += entryBytes;
+    if (approvalTicketId) this.ticketToEvaluation.set(approvalTicketId, evaluationId);
+    return { status: 200, body: responseBody };
+  }
+  // -------------------------------------------------------------------------
+  // POST /audit
+  // -------------------------------------------------------------------------
+  audit(req, payloadHash) {
+    const id = req.evaluation_id;
+    const tomb = this.tombstones.get(id);
+    if (tomb) {
+      if (tomb.finalizedBy === "expired") {
+        return { status: 404, body: { error: "evaluation_expired" } };
+      }
+      if (tomb.finalizedBy === "evaluate") {
+        return {
+          status: 200,
+          body: {
+            ok: true,
+            audit_record_id: tomb.auditRecordId,
+            already_finalized: true,
+            finalized_by: "evaluate"
+          }
+        };
+      }
+      if (tomb.payloadHash === payloadHash) {
+        return {
+          status: 200,
+          body: { ok: true, audit_record_id: tomb.auditRecordId, already_finalized: true }
+        };
+      }
+      return { status: 409, body: { error: "evaluation_conflict" } };
+    }
+    const entry = this.pending.get(id);
+    if (!entry) {
+      return { status: 404, body: { error: "evaluation_unknown" } };
+    }
+    if (this.enforceDeadlines(entry) === "expired") {
+      return { status: 404, body: { error: "evaluation_expired" } };
+    }
+    let approvalStatus = null;
+    let approvedBy = null;
+    if (entry.approvalTicketId) {
+      const ticket = this.getTicketStatus(entry.approvalTicketId);
+      const status = ticket?.status;
+      if (!status || status === "pending") {
+        return { status: 409, body: { error: "approval_unresolved" } };
+      }
+      approvalStatus = status;
+      approvedBy = ticket.resolved_by ?? null;
+    }
+    if (req.actual_amount !== void 0) {
+      if (!Number.isFinite(req.actual_amount) || req.actual_amount < 0) {
+        return { status: 400, body: { error: "invalid_actual_amount" } };
+      }
+      if (entry.limitPlan?.kind !== "spend") {
+        return { status: 400, body: { error: "no_spend_rule" } };
+      }
+    }
+    const callHappened = req.status === "success" || req.status === "error";
+    let limitsChain;
+    if (callHappened && entry.limitPlan) {
+      limitsChain = this.commitLimit(entry.limitPlan, req.actual_amount);
+    }
+    if (callHappened && this.evidenceStore && entry.sessionId) {
+      this.evidenceStore.recordToolCall(entry.sessionId, entry.toolName, req.status === "success");
+    }
+    const auditId = this.writeAudit({
+      timestampIso: entry.timestampIso,
+      origin: entry.origin,
+      agentId: entry.agentId,
+      sessionId: entry.sessionId,
+      toolName: entry.toolName,
+      toolInput: entry.toolInput,
+      metadata: entry.metadata,
+      action: entry.action,
+      wire: entry.action === "require_approval" ? "require_approval" : "allow",
+      matchedRuleName: entry.matchedRuleName,
+      matchedRuleIndex: entry.matchedRuleIndex,
+      flaggedDestructive: entry.flaggedDestructive,
+      dryRun: false,
+      recordKind: "tool_call",
+      limitsChain,
+      approvalStatus,
+      approvedBy,
+      upstreamError: req.status === "error" ? req.error ?? "tool call failed" : null,
+      upstreamResponse: req.result ?? null,
+      upstreamLatencyMs: req.duration_ms ?? null
+    });
+    this.discardPending(entry);
+    this.tombstones.set(id, {
+      auditRecordId: auditId,
+      payloadHash,
+      finalizedBy: "audit",
+      expiresAtMs: this.now() + this.ttlMs
+    });
+    return { status: 201, body: { ok: true, audit_record_id: auditId } };
+  }
+  // -------------------------------------------------------------------------
+  // POST /install-scan — evaluates install-time policy (issue #13)
+  // -------------------------------------------------------------------------
+  installScan(req) {
+    const reserved = reservedMetadataKey(req.metadata);
+    if (reserved) {
+      return { status: 400, body: { error: "reserved_metadata_key", key: reserved } };
+    }
+    const evaluationId = randomUUID2();
+    const toolName = `install:${req.package.source ?? "pkg"}:${req.package.name}`;
+    const verdict = this.evaluateInstall(req);
+    const denied = verdict.decision === "deny";
+    const auditId = this.writeAudit({
+      timestampIso: new Date(this.now()).toISOString(),
+      origin: req.origin,
+      agentId: req.agent_id,
+      sessionId: req.session_id,
+      toolName,
+      toolInput: { ...req.package },
+      metadata: req.metadata,
+      // policy_decision is 'deny' (NOT 'deny_install') so the dashboard renders a
+      // blocked install as a block, not an allow. The install context lives in
+      // record_kind + block_reason.
+      action: denied ? "deny" : "allow",
+      wire: denied ? "deny" : "allow",
+      matchedRuleName: verdict.matchedRule?.name ?? null,
+      matchedRuleIndex: verdict.matchedRule?.index ?? null,
+      flaggedDestructive: false,
+      dryRun: false,
+      recordKind: "install_scan"
+    });
+    this.tombstones.set(evaluationId, {
+      auditRecordId: auditId,
+      payloadHash: null,
+      finalizedBy: "evaluate",
+      expiresAtMs: this.now() + this.ttlMs
+    });
+    const body = {
+      evaluation_id: evaluationId,
+      decision: verdict.decision,
+      reason: verdict.reason,
+      matched_rule: verdict.matchedRule?.name ?? null,
+      matched_rule_index: verdict.matchedRule?.index ?? null
+    };
+    if (denied) {
+      body["feedback"] = buildFeedback(verdict.matchedRule, verdict.reason);
+    }
+    return { status: 200, body };
+  }
+  /** First-match-wins evaluation of the compiled install policy (issue #13). */
+  evaluateInstall(req) {
+    const install = this.policy.install;
+    if (!install) {
+      return { decision: "allow", reason: "no install-time rules defined" };
+    }
+    const metadataView = req.agent_id != null ? { ...req.metadata ?? {}, agent_id: req.agent_id } : req.metadata ?? void 0;
+    for (const rule of install.rules) {
+      if (matchInstallRule(rule, req.package, metadataView)) {
+        const label = rule.name ? `"${rule.name}"` : `install_rule[${String(rule.index)}]`;
+        return {
+          decision: rule.action === "deny_install" ? "deny" : "allow",
+          matchedRule: rule,
+          reason: `Matched ${label} \u2192 ${rule.action}`
+        };
+      }
+    }
+    return {
+      decision: install.defaultAction,
+      reason: `No matching install rule; default ${install.defaultAction}`
+    };
+  }
+  // -------------------------------------------------------------------------
+  // POST /approval/:id/resolve
+  // -------------------------------------------------------------------------
+  resolveApproval(ticketId, req) {
+    if (!this.approvalRouter) {
+      return { status: 503, body: { error: "governance_unavailable" } };
+    }
+    const ticket = this.getTicketStatus(ticketId);
+    if (!ticket) {
+      return { status: 404, body: { error: "ticket_not_found" } };
+    }
+    if (!ticket.channel_name.startsWith("native:")) {
+      return { status: 409, body: { error: "not_a_native_ticket" } };
+    }
+    const evaluationId = this.ticketToEvaluation.get(ticketId);
+    const entry = evaluationId ? this.pending.get(evaluationId) : void 0;
+    if (entry) this.enforceDeadlines(entry);
+    const current = this.getTicketStatus(ticketId);
+    if (!current || current.status !== "pending") {
+      return { status: 409, body: { error: "already_resolved", status: current?.status } };
+    }
+    const resolved = this.approvalRouter.resolveNativeTicket(
+      ticketId,
+      req.resolution,
+      req.resolved_by,
+      { denial_reason: req.resolution === "denied" ? req.reason : void 0 }
+    );
+    if (!resolved) {
+      return { status: 409, body: { error: "already_resolved" } };
+    }
+    return { status: 200, body: { ok: true } };
+  }
+  // -------------------------------------------------------------------------
+  // Sweep — GC backstop for callers that never return
+  // -------------------------------------------------------------------------
+  sweep() {
+    for (const entry of [...this.pending.values()]) {
+      this.enforceDeadlines(entry);
+    }
+    const now = this.now();
+    for (const [id, tomb] of this.tombstones) {
+      if (tomb.expiresAtMs <= now) this.tombstones.delete(id);
+    }
+    this.pruneSenderKeys();
+  }
+  /**
+   * Reserve a cardinality slot for a sender-keyed limit (issue #13).
+   *
+   * Only `sender:*` keys are gated — tool/session families are bounded by upstream
+   * cardinality, and the MCP path never reaches here, so structural traffic cannot
+   * be starved. A key already backed by live state (registry or a live limiter
+   * bucket) costs no new slot. At capacity we lazily prune dead keys before failing
+   * closed, so an emptied bucket frees its slot without waiting for the sweep.
+   */
+  reserveSenderKey(key) {
+    if (!key.startsWith("sender:")) return true;
+    if (this.senderKeys.has(key)) return true;
+    if (this.hasLiveBucket(key)) {
+      this.senderKeys.add(key);
+      return true;
+    }
+    if (this.senderKeys.size >= this.maxSenderKeys) {
+      this.pruneSenderKeys();
+      if (this.senderKeys.size >= this.maxSenderKeys) return false;
+    }
+    this.senderKeys.add(key);
+    return true;
+  }
+  /** Drop registry keys with no pending evaluation AND no live limiter bucket. */
+  pruneSenderKeys() {
+    if (this.senderKeys.size === 0) return;
+    const inUse = /* @__PURE__ */ new Set();
+    for (const entry of this.pending.values()) {
+      if (entry.limitPlan && entry.limitPlan.key.startsWith("sender:")) {
+        inUse.add(entry.limitPlan.key);
+      }
+    }
+    for (const key of this.senderKeys) {
+      if (inUse.has(key)) continue;
+      if (this.hasLiveBucket(key)) continue;
+      this.senderKeys.delete(key);
+    }
+  }
+  /**
+   * Whether either limiter still holds a live bucket for `key`. Uses the public
+   * `getKeyState()` — never the limiters' private maps — and its lazy eviction of
+   * an emptied bucket IS the prune-on-touch mechanism.
+   */
+  hasLiveBucket(key) {
+    return this.rateLimiter?.getKeyState(key) !== void 0 || this.spendLimiter?.getKeyState(key) !== void 0;
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
+    this.pending.clear();
+    this.tombstones.clear();
+    this.caches.clear();
+    this.senderKeys.clear();
+    this.pendingBytes = 0;
+  }
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  /** Apply crossed deadlines to one pending entry. Returns its post-state. */
+  enforceDeadlines(entry) {
+    const now = this.now();
+    if (now >= entry.evaluationExpiresAtMs) {
+      if (entry.approvalTicketId) {
+        this.approvalRouter?.resolveNativeTicket(entry.approvalTicketId, "timeout");
+      }
+      const auditId = this.writeAudit({
+        timestampIso: entry.timestampIso,
+        origin: entry.origin,
+        agentId: entry.agentId,
+        sessionId: entry.sessionId,
+        toolName: entry.toolName,
+        toolInput: entry.toolInput,
+        metadata: entry.metadata,
+        action: entry.action,
+        wire: entry.action === "require_approval" ? "require_approval" : "allow",
+        matchedRuleName: entry.matchedRuleName,
+        matchedRuleIndex: entry.matchedRuleIndex,
+        flaggedDestructive: entry.flaggedDestructive,
+        dryRun: false,
+        recordKind: "evaluation_expired",
+        sidebandUnreported: true
+      });
+      this.discardPending(entry);
+      this.tombstones.set(entry.evaluationId, {
+        auditRecordId: auditId,
+        payloadHash: null,
+        finalizedBy: "expired",
+        expiresAtMs: now + this.ttlMs
+      });
+      console.error(
+        `[helio] Sideband evaluation ${entry.evaluationId} expired without /audit (origin=${entry.origin}, tool=${entry.toolName}) \u2014 recorded as evaluation_expired`
+      );
+      return "expired";
+    }
+    if (entry.approvalTicketId && entry.ticketTimeoutAtMs !== void 0 && now >= entry.ticketTimeoutAtMs) {
+      this.approvalRouter?.resolveNativeTicket(entry.approvalTicketId, "timeout");
+    }
+    return "active";
+  }
+  cacheFor(origin) {
+    let cache = this.caches.get(origin);
+    if (!cache) {
+      cache = new ToolAnnotationCache();
+      this.caches.set(origin, cache);
+    }
+    return cache;
+  }
+  discardPending(entry) {
+    if (this.pending.delete(entry.evaluationId)) {
+      this.pendingBytes -= entry.bytes;
+    }
+    if (entry.approvalTicketId) this.ticketToEvaluation.delete(entry.approvalTicketId);
+  }
+  getTicketStatus(ticketId) {
+    return this.approvalRouter?.getTicket(ticketId);
+  }
+  planRate(decision, toolName, sessionId, senderId) {
+    const limits = decision.matchedRule?.limits;
+    if (!this.rateLimiter || !limits?.maxCalls || !limits.windowMs) {
+      return { allowed: true };
+    }
+    const key = buildLimitKey(limits.key, toolName, sessionId, senderId);
+    const peek = this.rateLimiter.peek({
+      key,
+      maxCalls: limits.maxCalls,
+      windowMs: limits.windowMs
+    });
+    return {
+      plan: { kind: "rate", key, limits },
+      block: {
+        current: peek.current,
+        limit: peek.limit,
+        window_ms: peek.windowMs,
+        reset_at_ms: peek.resetAtMs
+      },
+      allowed: peek.allowed
+    };
+  }
+  planSpend(decision, toolName, sessionId, args, senderId) {
+    const maxSpend = decision.matchedRule?.limits?.maxSpend;
+    if (!this.spendLimiter || !maxSpend) return { allowed: true };
+    const key = buildLimitKey(maxSpend.key, toolName, sessionId, senderId);
+    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 } };
+    }
+    const peek = this.spendLimiter.peek({
+      key,
+      amount: rawAmount,
+      limit: maxSpend.limit,
+      windowMs: maxSpend.windowMs
+    });
+    return {
+      plan: {
+        kind: "spend",
+        key,
+        limits: decision.matchedRule.limits,
+        amount: rawAmount,
+        currency: maxSpend.currency
+      },
+      block: {
+        current_spend: peek.currentSpend,
+        limit: peek.limit,
+        currency: maxSpend.currency,
+        window_ms: peek.windowMs,
+        reset_at_ms: peek.resetAtMs
+      },
+      allowed: peek.allowed
+    };
+  }
+  /** Commit a limit plan at /audit time and return the evidence_chain block. */
+  commitLimit(plan, actualAmount) {
+    if (plan.kind === "rate" && this.rateLimiter && plan.limits.maxCalls && plan.limits.windowMs) {
+      const r = this.rateLimiter.record({
+        key: plan.key,
+        maxCalls: plan.limits.maxCalls,
+        windowMs: plan.limits.windowMs
+      });
+      return {
+        rate_limit: {
+          allowed: r.allowed,
+          current: r.current,
+          limit: r.limit,
+          window_ms: r.windowMs,
+          reset_at_ms: r.resetAtMs
+        }
+      };
+    }
+    if (plan.kind === "spend" && this.spendLimiter && plan.limits.maxSpend) {
+      const amount = actualAmount ?? plan.amount ?? 0;
+      const r = this.spendLimiter.record({
+        key: plan.key,
+        amount,
+        limit: plan.limits.maxSpend.limit,
+        windowMs: plan.limits.maxSpend.windowMs
+      });
+      this.spendLimiter.setCurrency(plan.key, plan.limits.maxSpend.currency);
+      return {
+        spend_limit: {
+          allowed: r.allowed,
+          current_spend: r.currentSpend,
+          limit: r.limit,
+          window_ms: r.windowMs,
+          reset_at_ms: r.resetAtMs
+        }
+      };
+    }
+    return void 0;
+  }
+  writeAudit(args) {
+    const id = randomUUID2();
+    if (!this.auditWriter) return id;
+    const blockReason = deriveBlockReason(args);
+    let evidenceChain = args.limitsChain ?? null;
+    if (args.sidebandUnreported) {
+      evidenceChain = { ...evidenceChain ?? {}, sideband: { unreported: true } };
+    }
+    const record = {
+      timestamp: args.timestampIso,
+      session_id: args.sessionId,
+      agent_id: args.agentId,
+      environment: this.environment ?? null,
+      tool_name: args.toolName,
+      tool_input: args.toolInput,
+      policy_decision: args.action,
+      block_reason: blockReason,
+      matched_rule: args.matchedRuleName,
+      matched_rule_index: args.matchedRuleIndex,
+      evidence_chain: evidenceChain,
+      approval_status: args.approvalStatus ?? null,
+      approved_by: args.approvedBy ?? null,
+      upstream_response: args.upstreamResponse ?? null,
+      upstream_error: args.upstreamError ?? null,
+      upstream_http_status: null,
+      upstream_latency_ms: args.upstreamLatencyMs ?? null,
+      total_duration_ms: 0,
+      approval_wait_ms: 0,
+      proxy_compute_ms: 0,
+      flagged_destructive: args.flaggedDestructive,
+      dry_run: args.dryRun,
+      record_kind: args.recordKind,
+      origin: args.origin,
+      metadata: args.metadata
+    };
+    const isEnforcement = args.recordKind === "evaluation_expired" || blockReason !== null || args.approvalStatus != null;
+    if (isEnforcement) this.auditWriter.pushImmediate(record, id);
+    else this.auditWriter.push(record, id);
+    return id;
+  }
+  assertApprovalRouter(policy) {
+    if (!policyCanRequireApproval(policy) || this.approvalRouter) return;
+    throw new GovernanceConfigError(
+      "[helio] GovernanceService misconfiguration: approval-capable policy (a require_approval rule, or flag_destructive/on_tool_drift set to require_approval) requires an approvalRouter"
+    );
+  }
+};
+function deriveBlockReason(args) {
+  if (args.recordKind === "evaluation_expired") return null;
+  if (args.recordKind === "install_scan") return args.wire === "deny" ? "install_denied" : null;
+  if (args.dryRun) return null;
+  if (args.approvalStatus === "denied") return "approval_denied";
+  if (args.approvalStatus === "timeout") return "approval_timeout";
+  if (args.approvalStatus === "cancelled") return "cancelled";
+  switch (args.wire) {
+    case "deny":
+      return "policy_denied";
+    case "rate_limited":
+      return "rate_limited";
+    case "spend_limited":
+      return "spend_limited";
+    default:
+      return null;
+  }
+}
+function buildFeedback(rule, reason) {
+  const message = rule?.feedback?.message ?? reason;
+  const suggestion = rule?.feedback?.suggestion;
+  return suggestion ? { message, suggestion } : { message };
+}
+function isBlocking(wire) {
+  return wire === "deny" || wire === "rate_limited" || wire === "spend_limited";
+}
+function isTerminalAtEvaluate(wire) {
+  return wire === "deny" || wire === "rate_limited" || wire === "spend_limited" || wire === "dry_run";
+}
+function policyCanRequireApproval(policy) {
+  if (policy.flagDestructive === "require_approval" || policy.onToolDrift === "require_approval") {
+    return true;
+  }
+  return policy.rules.some((rule) => rule.action === "require_approval");
+}
+function buildLimitKey(keyType, toolName, sessionId, senderId) {
+  switch (keyType) {
+    case "session":
+      return `session:${sessionId ?? "unknown"}`;
+    case "sender_id":
+      return `sender:${senderId ?? "unknown"}`;
+    case "agent":
+    case "tool":
+    default:
+      return `tool:${toolName}`;
+  }
+}
+function senderIdOf(metadata) {
+  const v = metadata?.["sender_id"];
+  return typeof v === "string" ? v : null;
+}
+function matchInstallRule(rule, pkg2, metadataView) {
+  if (rule.match.name && !rule.match.name.test(pkg2.name)) return false;
+  if (rule.match.source !== void 0 && rule.match.source !== pkg2.source) return false;
+  if (rule.match.metadata && !matchMetadata(rule.match.metadata, { metadata: metadataView })) {
+    return false;
+  }
+  return true;
+}
+function reservedMetadataKey(metadata) {
+  if (metadata && Object.prototype.hasOwnProperty.call(metadata, "agent_id")) {
+    return "agent_id";
+  }
+  return null;
+}
+function definitionProvided(tool) {
+  return tool.description !== void 0 || tool.input_schema !== void 0 || tool.output_schema !== void 0 || tool.title !== void 0 || tool.annotations !== void 0;
+}
+function toMcpToolDef(tool) {
+  const def = { name: tool.name };
+  if (tool.description !== void 0) def["description"] = tool.description;
+  if (tool.input_schema !== void 0) def["inputSchema"] = tool.input_schema;
+  if (tool.output_schema !== void 0) def["outputSchema"] = tool.output_schema;
+  if (tool.title !== void 0) def["title"] = tool.title;
+  if (tool.annotations !== void 0) def["annotations"] = tool.annotations;
+  return def;
+}
+function byteLength(value) {
+  return Buffer.byteLength(canonicalize(value), "utf8");
+}
+
 // src/audit/store.ts
 import Database from "better-sqlite3";
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import { chmodSync } from "fs";
 
 // src/upstream/response-summary.ts
@@ -4381,6 +5697,9 @@ CREATE TABLE IF NOT EXISTS audit_records (
   proxy_compute_ms  REAL NOT NULL,
   flagged_destructive INTEGER NOT NULL DEFAULT 0,
   dry_run           INTEGER NOT NULL DEFAULT 0,
+  record_kind       TEXT NOT NULL DEFAULT 'tool_call',
+  origin            TEXT NOT NULL DEFAULT 'mcp',
+  metadata          TEXT,
   created_at        TEXT NOT NULL
 );
 `;
@@ -4391,6 +5710,8 @@ CREATE INDEX IF NOT EXISTS idx_audit_policy_decision  ON audit_records (policy_d
 CREATE INDEX IF NOT EXISTS idx_audit_session_id       ON audit_records (session_id);
 CREATE INDEX IF NOT EXISTS idx_audit_block_reason     ON audit_records (block_reason);
 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);
 `;
 var INSERT_SQL = `
 INSERT INTO audit_records (
@@ -4399,14 +5720,14 @@ 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, created_at
+  flagged_destructive, dry_run, record_kind, origin, metadata, created_at
 ) VALUES (
   @id, @timestamp, @session_id, @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, @created_at
+  @flagged_destructive, @dry_run, @record_kind, @origin, @metadata, @created_at
 )
 `;
 var REQUIRED_AUDIT_COLUMNS = [
@@ -4416,7 +5737,10 @@ var REQUIRED_AUDIT_COLUMNS = [
   "total_duration_ms",
   "approval_wait_ms",
   "proxy_compute_ms",
-  "upstream_http_status"
+  "upstream_http_status",
+  "record_kind",
+  "origin",
+  "metadata"
 ];
 function deserializeRow(row) {
   return {
@@ -4443,6 +5767,9 @@ function deserializeRow(row) {
     proxy_compute_ms: row.proxy_compute_ms,
     flagged_destructive: row.flagged_destructive === 1,
     dry_run: row.dry_run === 1,
+    record_kind: row.record_kind,
+    origin: row.origin,
+    metadata: row.metadata ? JSON.parse(row.metadata) : null,
     created_at: row.created_at
   };
 }
@@ -4464,6 +5791,22 @@ function buildWhereClause(filters) {
   if (filters.blocked !== void 0) {
     conditions.push(filters.blocked ? "block_reason IS NOT NULL" : "block_reason IS NULL");
   }
+  if (filters.record_kind !== void 0) {
+    conditions.push("record_kind = ?");
+    params.push(filters.record_kind);
+  }
+  if (filters.origin !== void 0) {
+    conditions.push("origin LIKE ?");
+    params.push(`%${filters.origin}%`);
+  }
+  if (filters.channel_id !== void 0) {
+    conditions.push("json_extract(metadata, '$.channel_id') LIKE ?");
+    params.push(`%${filters.channel_id}%`);
+  }
+  if (filters.sender_id !== void 0) {
+    conditions.push("json_extract(metadata, '$.sender_id') LIKE ?");
+    params.push(`%${filters.sender_id}%`);
+  }
   if (filters.session_id !== void 0) {
     conditions.push("session_id = ?");
     params.push(filters.session_id);
@@ -4564,7 +5907,7 @@ var AuditStore = class {
    * @param id - Optional pre-generated ID (used by AuditWriter to share ID with SSE event bus).
    */
   insert(record, createdAt, id) {
-    const resolvedId = id ?? randomUUID2();
+    const resolvedId = id ?? randomUUID3();
     const now = createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
     this.insertStmt.run({
       id: resolvedId,
@@ -4590,6 +5933,9 @@ var AuditStore = class {
       proxy_compute_ms: record.proxy_compute_ms,
       flagged_destructive: record.flagged_destructive ? 1 : 0,
       dry_run: record.dry_run ? 1 : 0,
+      record_kind: record.record_kind,
+      origin: record.origin,
+      metadata: record.metadata ? JSON.stringify(record.metadata) : null,
       created_at: now
     });
     return resolvedId;
@@ -4736,7 +6082,7 @@ var AuditStore = class {
 };
 
 // src/audit/writer.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 var AuditWriter = class {
   store;
   bufferSize;
@@ -4771,9 +6117,8 @@ var AuditWriter = class {
    * is scheduled. This keeps request-path latency bounded even under bursty
    * write load.
    */
-  push(record) {
+  push(record, id = randomUUID4()) {
     if (this.closed) return;
-    const id = randomUUID3();
     this.buffer.push({ id, record });
     this.onPush?.(record, id);
     if (this.buffer.length >= this.bufferSize) {
@@ -4788,9 +6133,8 @@ var AuditWriter = class {
    * A fatal-process crash still invokes the crash-drain hook, which calls
    * `flush()` synchronously before exit.
    */
-  pushImmediate(record) {
+  pushImmediate(record, id = randomUUID4()) {
     if (this.closed) return;
-    const id = randomUUID3();
     this.buffer.push({ id, record });
     this.onPush?.(record, id);
     this.scheduleFlushSoon();
@@ -4846,7 +6190,7 @@ var AuditWriter = class {
 };
 
 // src/approval/queue.ts
-import { randomUUID as randomUUID4 } from "crypto";
+import { randomUUID as randomUUID5 } from "crypto";
 var ApprovalQueue = class {
   tickets = /* @__PURE__ */ new Map();
   now;
@@ -4876,7 +6220,7 @@ var ApprovalQueue = class {
     if (this.closed) throw new Error("ApprovalQueue is closed");
     const now = this.now();
     const ticket = {
-      id: randomUUID4(),
+      id: randomUUID5(),
       tool_name: params.tool_name,
       tool_input: params.tool_input,
       matched_rule: params.matched_rule,
@@ -4955,6 +6299,7 @@ var ApprovalQueue = class {
 };
 
 // src/approval/router.ts
+var NATIVE_CHANNEL_PREFIX = "native:";
 var ApprovalRouter = class {
   defaultTimeoutMs;
   defaultOnTimeout;
@@ -5067,6 +6412,59 @@ var ApprovalRouter = class {
     });
     return outcome;
   }
+  /**
+   * Create a native (adapter-owned) approval ticket without holding a Promise.
+   *
+   * Used by the sideband governance path (issue #12, D10): when `/evaluate`
+   * yields `require_approval`, the adapter runs the approval in its own UI
+   * (e.g. OpenClaw's Telegram dialog), so Helio must NOT block, start
+   * timeout/escalation timers, or notify a channel — doing so would
+   * double-notify. We still create the queue ticket and fire `onSubmit` so the
+   * dashboard's `approval_requested` SSE event flows and the ticket is visible.
+   *
+   * The ticket's `channel_name` is `native:<origin>`, which marks it as
+   * adapter-owned: the dashboard approve/deny endpoints refuse it (it can only
+   * be resolved through the adapter), and {@link resolveNativeTicket} is the
+   * resolution path.
+   */
+  createNativeTicket(params) {
+    const rule = params.matched_rule;
+    const timeoutMs = params.timeout_ms ?? rule?.approval?.timeoutMs ?? this.defaultTimeoutMs;
+    const ticket = this.queue.add({
+      tool_name: params.tool_name,
+      tool_input: params.tool_input,
+      matched_rule: rule?.name ?? null,
+      rule_index: rule?.index ?? null,
+      channel_name: `${NATIVE_CHANNEL_PREFIX}${params.origin}`,
+      session_id: params.session_id,
+      timeout_ms: timeoutMs
+    });
+    this.onSubmit?.(ticket);
+    return ticket;
+  }
+  /**
+   * Resolve a native ticket created by {@link createNativeTicket}.
+   *
+   * Resolves the queue ticket and fires `onResolve` (→ `approval_resolved`
+   * SSE), with no held Promise to settle. Refuses tickets that have a pending
+   * router Promise (those are MCP-path tickets; resolving them here would leave
+   * the held request hanging) and tickets that are not `native:`-prefixed.
+   *
+   * @returns `true` if resolved, `false` if not found, already resolved, not a
+   *          native ticket, or router-managed.
+   */
+  resolveNativeTicket(ticketId, status, resolvedBy, options) {
+    if (this.pending.has(ticketId)) return false;
+    const ticket = this.queue.get(ticketId);
+    if (!ticket || !ticket.channel_name.startsWith(NATIVE_CHANNEL_PREFIX)) return false;
+    const resolved = this.queue.resolve(ticketId, status, resolvedBy, {
+      denial_reason: options?.denial_reason
+    });
+    if (!resolved) return false;
+    const updated = this.queue.get(ticketId);
+    if (updated) this.onResolve?.(updated);
+    return true;
+  }
   /**
    * Approve a pending ticket. Resolves the held Promise so the governed
    * forwarder can forward the request upstream.
@@ -5111,6 +6509,10 @@ var ApprovalRouter = class {
       ticketId
     });
   }
+  /** Look up a ticket by id (delegates to the queue). */
+  getTicket(ticketId) {
+    return this.queue.get(ticketId);
+  }
   /** Clean up all pending timers and resolve all pending promises. */
   close() {
     this.closed = true;
@@ -5373,8 +6775,8 @@ function createChannels(channels) {
 
 // src/approval/slack-actions.ts
 import { createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
-import { Hono as Hono5 } from "hono";
-import { z as z5 } from "zod";
+import { Hono as Hono6 } from "hono";
+import { z as z6 } from "zod";
 var MAX_TIMESTAMP_AGE_S = 300;
 var REJECTION_LOG_WINDOW_MS = 6e4;
 var REJECTION_LOG_SAMPLE_EVERY = 25;
@@ -5440,12 +6842,12 @@ function verifySlackSignature(secrets, timestamp, rawBody, signature) {
   }
   return false;
 }
-var slackActionPayloadSchema = z5.object({
-  type: z5.string(),
-  user: z5.object({ id: z5.string(), username: z5.string() }),
-  actions: z5.array(z5.object({ action_id: z5.string() })),
-  channel: z5.object({ id: z5.string() }),
-  message: z5.object({ ts: z5.string() })
+var slackActionPayloadSchema = z6.object({
+  type: z6.string(),
+  user: z6.object({ id: z6.string(), username: z6.string() }),
+  actions: z6.array(z6.object({ action_id: z6.string() })),
+  channel: z6.object({ id: z6.string() }),
+  message: z6.object({ ts: z6.string() })
 });
 function parseActionPayload(rawBody) {
   try {
@@ -5475,7 +6877,7 @@ Ticket \`${ticketId}\``
 }
 function createSlackActionApp(options) {
   const { router, channels } = options;
-  const app = new Hono5();
+  const app = new Hono6();
   const rejectionLogBuckets = /* @__PURE__ */ new Map();
   const rejectUnauthorized = (c, reason, context) => {
     logRejectedSlackCallback(rejectionLogBuckets, {
@@ -5574,18 +6976,18 @@ function createSlackActionApp(options) {
 }
 
 // src/approval/api.ts
-import { Hono as Hono6 } from "hono";
-import { z as z6 } from "zod";
-var approveBody = z6.object({
-  approved_by: z6.string().min(1)
+import { Hono as Hono7 } from "hono";
+import { z as z7 } from "zod";
+var approveBody = z7.object({
+  approved_by: z7.string().min(1)
 });
-var denyBody = z6.object({
-  denied_by: z6.string().min(1),
-  reason: z6.string().optional()
+var denyBody = z7.object({
+  denied_by: z7.string().min(1),
+  reason: z7.string().optional()
 });
-var breakGlassBody = z6.object({
-  approved_by: z6.string().min(1),
-  reason: z6.string().min(1)
+var breakGlassBody = z7.object({
+  approved_by: z7.string().min(1),
+  reason: z7.string().min(1)
 });
 var APPROVAL_STATUSES = [
   "pending",
@@ -5594,25 +6996,26 @@ var APPROVAL_STATUSES = [
   "timeout",
   "break_glass",
   "client_disconnected",
-  "shutdown_cancelled"
+  "shutdown_cancelled",
+  "cancelled"
 ];
 var approvalStatusSet = new Set(APPROVAL_STATUSES);
-var listApprovalsQuery = z6.object({
-  status: z6.preprocess(
+var listApprovalsQuery = z7.object({
+  status: z7.preprocess(
     (value) => typeof value === "string" && approvalStatusSet.has(value) ? value : void 0,
-    z6.enum(APPROVAL_STATUSES).optional()
+    z7.enum(APPROVAL_STATUSES).optional()
   ),
-  limit: z6.preprocess(
+  limit: z7.preprocess(
     (value) => clampInt(typeof value === "string" ? value : void 0, 50, 1, 1e3),
-    z6.number().int()
+    z7.number().int()
   ),
-  offset: z6.preprocess(
+  offset: z7.preprocess(
     (value) => clampInt(typeof value === "string" ? value : void 0, 0, 0, Number.MAX_SAFE_INTEGER),
-    z6.number().int()
+    z7.number().int()
   )
 });
 function createApprovalApp(router, queue, options) {
-  const app = new Hono6();
+  const app = new Hono7();
   const apiSecret = options?.apiSecret;
   if (apiSecret) {
     app.use("*", async (c, next) => {
@@ -5658,6 +7061,15 @@ function createApprovalApp(router, queue, options) {
     if (!ticket) {
       return c.json({ error: "Ticket not found" }, 404);
     }
+    if (ticket.channel_name.startsWith(NATIVE_CHANNEL_PREFIX)) {
+      return c.json(
+        {
+          error: "native_ticket",
+          resolve_in: ticket.channel_name.slice(NATIVE_CHANNEL_PREFIX.length)
+        },
+        409
+      );
+    }
     if (ticket.status !== "pending") {
       return c.json({ error: "Ticket already resolved", status: ticket.status }, 409);
     }
@@ -5683,6 +7095,15 @@ function createApprovalApp(router, queue, options) {
     if (!ticket) {
       return c.json({ error: "Ticket not found" }, 404);
     }
+    if (ticket.channel_name.startsWith(NATIVE_CHANNEL_PREFIX)) {
+      return c.json(
+        {
+          error: "native_ticket",
+          resolve_in: ticket.channel_name.slice(NATIVE_CHANNEL_PREFIX.length)
+        },
+        409
+      );
+    }
     if (ticket.status !== "pending") {
       return c.json({ error: "Ticket already resolved", status: ticket.status }, 409);
     }
@@ -5708,6 +7129,15 @@ function createApprovalApp(router, queue, options) {
     if (!ticket) {
       return c.json({ error: "Ticket not found" }, 404);
     }
+    if (ticket.channel_name.startsWith(NATIVE_CHANNEL_PREFIX)) {
+      return c.json(
+        {
+          error: "native_ticket",
+          resolve_in: ticket.channel_name.slice(NATIVE_CHANNEL_PREFIX.length)
+        },
+        409
+      );
+    }
     if (ticket.status !== "pending") {
       return c.json({ error: "Ticket already resolved", status: ticket.status }, 409);
     }
@@ -5723,9 +7153,9 @@ function createApprovalApp(router, queue, options) {
 // src/dashboard/api.ts
 import { readFileSync } from "fs";
 import { join } from "path";
-import { randomUUID as randomUUID5 } from "crypto";
-import { Hono as Hono7 } from "hono";
-import { z as z7 } from "zod";
+import { randomUUID as randomUUID6 } from "crypto";
+import { Hono as Hono8 } from "hono";
+import { z as z8 } from "zod";
 import { cors } from "hono/cors";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { streamSSE } from "hono/streaming";
@@ -5786,7 +7216,7 @@ function recordsToCsv(records) {
 }
 
 // src/dashboard/session.ts
-import { createHash as createHash2, createHmac as createHmac3, randomBytes, timingSafeEqual as timingSafeEqual3 } from "crypto";
+import { createHash as createHash3, createHmac as createHmac3, randomBytes, timingSafeEqual as timingSafeEqual3 } from "crypto";
 var DashboardSessionStore = class {
   secret;
   ttlMs;
@@ -5867,8 +7297,8 @@ var DashboardSessionStore = class {
     const id = token.slice(0, dot);
     const signature = token.slice(dot + 1);
     const expected = this.sign(id);
-    const actualDigest = createHash2("sha256").update(signature).digest();
-    const expectedDigest = createHash2("sha256").update(expected).digest();
+    const actualDigest = createHash3("sha256").update(signature).digest();
+    const expectedDigest = createHash3("sha256").update(expected).digest();
     if (!timingSafeEqual3(actualDigest, expectedDigest)) return void 0;
     return id;
   }
@@ -5878,29 +7308,29 @@ var DashboardSessionStore = class {
 };
 
 // src/dashboard/api.ts
-var optionalQueryString = z7.preprocess(
+var optionalQueryString = z8.preprocess(
   (value) => typeof value === "string" && value.length > 0 ? value : void 0,
-  z7.string().optional()
+  z8.string().optional()
 );
-var optionalQueryInt = z7.preprocess((value) => {
+var optionalQueryInt = z8.preprocess((value) => {
   if (typeof value !== "string" || value.length === 0) return void 0;
   const parsed = Number.parseInt(value, 10);
   return Number.isFinite(parsed) ? parsed : void 0;
-}, z7.number().int().optional());
-var queryBoolean = z7.preprocess(
+}, z8.number().int().optional());
+var queryBoolean = z8.preprocess(
   (value) => value === "true" ? true : value === "false" ? false : void 0,
-  z7.boolean().optional()
+  z8.boolean().optional()
 );
-var clampedQueryInt = (fallback, min, max) => z7.preprocess(
+var clampedQueryInt = (fallback, min, max) => z8.preprocess(
   (value) => clampInt(typeof value === "string" ? value : void 0, fallback, min, max),
-  z7.number().int()
+  z8.number().int()
 );
-var feedQuerySchema = z7.object({
+var feedQuerySchema = z8.object({
   limit: clampedQueryInt(50, 1, 200),
   offset: clampedQueryInt(0, 0, Number.MAX_SAFE_INTEGER)
 });
-var auditExportQuerySchema = z7.object({
-  format: z7.preprocess((value) => value === "csv" ? "csv" : "json", z7.enum(["json", "csv"])),
+var auditExportQuerySchema = z8.object({
+  format: z8.preprocess((value) => value === "csv" ? "csv" : "json", z8.enum(["json", "csv"])),
   limit: clampedQueryInt(1e4, 1, 1e4),
   tool: optionalQueryString,
   decision: optionalQueryString,
@@ -5912,9 +7342,13 @@ var auditExportQuerySchema = z7.object({
   from: optionalQueryString,
   to: optionalQueryString,
   upstream_status_min: optionalQueryInt,
-  upstream_status_max: optionalQueryInt
+  upstream_status_max: optionalQueryInt,
+  origin: optionalQueryString,
+  record_kind: optionalQueryString,
+  channel_id: optionalQueryString,
+  sender_id: optionalQueryString
 });
-var auditQuerySchema = z7.object({
+var auditQuerySchema = z8.object({
   limit: clampedQueryInt(50, 1, 1e3),
   offset: clampedQueryInt(0, 0, Number.MAX_SAFE_INTEGER),
   tool: optionalQueryString,
@@ -5928,14 +7362,18 @@ var auditQuerySchema = z7.object({
   destructive: queryBoolean,
   dry_run: queryBoolean,
   upstream_status_min: optionalQueryInt,
-  upstream_status_max: optionalQueryInt
+  upstream_status_max: optionalQueryInt,
+  origin: optionalQueryString,
+  record_kind: optionalQueryString,
+  channel_id: optionalQueryString,
+  sender_id: optionalQueryString
 });
-var analyticsQuerySchema = z7.object({
+var analyticsQuerySchema = z8.object({
   from: optionalQueryString,
   to: optionalQueryString
 });
-var authSessionBodySchema = z7.object({
-  secret: z7.string()
+var authSessionBodySchema = z8.object({
+  secret: z8.string()
 });
 var SESSION_COOKIE = "helio_session";
 var SESSION_TTL_MS = 8 * 60 * 60 * 1e3;
@@ -5995,7 +7433,7 @@ function createDashboardAppWithLifecycle(deps, options) {
   } = deps;
   const apiSecret = options?.apiSecret;
   const sessionStore = apiSecret ? new DashboardSessionStore({ secret: apiSecret, ttlMs: SESSION_TTL_MS }) : void 0;
-  const app = new Hono7();
+  const app = new Hono8();
   app.use(
     "*",
     cors({
@@ -6135,7 +7573,11 @@ function createDashboardAppWithLifecycle(deps, options) {
       from: query.from,
       to: query.to,
       upstream_status_min: query.upstream_status_min,
-      upstream_status_max: query.upstream_status_max
+      upstream_status_max: query.upstream_status_max,
+      origin: query.origin,
+      record_kind: query.record_kind,
+      channel_id: query.channel_id,
+      sender_id: query.sender_id
     };
     const result = auditStore.list(filters, { limit, order: "asc" });
     if (format === "csv") {
@@ -6177,7 +7619,11 @@ function createDashboardAppWithLifecycle(deps, options) {
       flagged_destructive: query.destructive,
       dry_run: query.dry_run,
       upstream_status_min: query.upstream_status_min,
-      upstream_status_max: query.upstream_status_max
+      upstream_status_max: query.upstream_status_max,
+      origin: query.origin,
+      record_kind: query.record_kind,
+      channel_id: query.channel_id,
+      sender_id: query.sender_id
     };
     const result = auditStore.list(filters, { limit, offset, order: "desc" });
     return c.json({
@@ -6238,7 +7684,7 @@ function createDashboardAppWithLifecycle(deps, options) {
   app.get("/api/events", (c) => {
     return streamSSE(c, async (stream) => {
       if (closed) return;
-      const connId = randomUUID5();
+      const connId = randomUUID6();
       let streamClosed = false;
       let stopHeartbeat = () => {
       };
@@ -6267,7 +7713,7 @@ function createDashboardAppWithLifecycle(deps, options) {
         void stream.writeSSE({
           event: eventType,
           data: JSON.stringify(data),
-          id: randomUUID5()
+          id: randomUUID6()
         }).then(() => {
           const conn = activeConnections.get(connId);
           if (conn) conn.lastWrite = Date.now();
@@ -6368,6 +7814,8 @@ export {
   ConfigError,
   DashboardEventBus,
   EvidenceStore,
+  GovernanceConfigError,
+  GovernanceService,
   GovernedForwarder,
   PolicyParseError,
   QueueChannel,