@gethelio/proxy 0.13.0 → 0.14.0

package/dist/cli.js

@@ -2,10 +2,10 @@
 
 // src/cli.ts
 import { Command } from "commander";
-import { writeFile } from "fs/promises";
+import { mkdir, writeFile } from "fs/promises";
 import { existsSync } from "fs";
-import { randomBytes as randomBytes2 } from "crypto";
-import { dirname, resolve } from "path";
+import { randomBytes as randomBytes3 } from "crypto";
+import { dirname, join as join2, resolve } from "path";
 import { fileURLToPath } from "url";
 
 // src/version.ts
@@ -574,7 +574,7 @@ function rootConfigChecks(cfg, ctx) {
       ctx.addIssue({
         code: "custom",
         path: ["dashboard", "api_secret"],
-        message: 'dashboard.api_secret is required when any rule uses require_approval, any budget uses on_exceed: require_approval, or policies.flag_destructive or policies.on_tool_drift is "require_approval". Generate one with: `openssl rand -hex 32` and set it under `dashboard.api_secret` in your helio.yaml. (See docs/approvals.md.)'
+        message: 'dashboard.api_secret is required when any rule uses require_approval, any budget uses on_exceed: require_approval, or policies.flag_destructive or policies.on_tool_drift is "require_approval". Run `helio secret` and set the printed digest under `dashboard.api_secret` in your helio.yaml (a plaintext value is accepted but warned about at startup). (See docs/approvals.md.)'
       });
     }
   }
@@ -582,7 +582,7 @@ function rootConfigChecks(cfg, ctx) {
     ctx.addIssue({
       code: "custom",
       path: ["dashboard", "api_secret"],
-      message: "dashboard.api_secret is required when dashboard.enabled is true unless dashboard.allow_open_mode is explicitly set to true. Generate one with `openssl rand -hex 32` and set it under dashboard.api_secret in helio.yaml."
+      message: "dashboard.api_secret is required when dashboard.enabled is true unless dashboard.allow_open_mode is explicitly set to true. Run `helio secret` and set the printed digest under dashboard.api_secret in helio.yaml."
     });
   }
   if (!requiresSecret && cfg.dashboard.enabled && !hasSecret && cfg.dashboard.allow_open_mode && !isLoopbackHost(cfg.dashboard.host)) {
@@ -948,6 +948,7 @@ function isNamedConfig(config) {
 
 // src/config/loader.ts
 import { readFile } from "fs/promises";
+import { createHash } from "crypto";
 import yaml from "js-yaml";
 
 // src/util/format-zod-errors.ts
@@ -967,44 +968,53 @@ var ConfigError = class extends Error {
   }
 };
 var ENV_VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
-function interpolateEnvVars(value, env = process.env) {
+function interpolateTracked(value, env, path, out) {
   if (typeof value === "string") {
-    return value.replace(ENV_VAR_PATTERN, (_match, varName) => {
+    let substitutions = 0;
+    const result = value.replace(ENV_VAR_PATTERN, (_match, varName) => {
       const envValue = env[varName];
       if (envValue === void 0) {
         throw new ConfigError(`Environment variable "${varName}" is not set`);
       }
+      substitutions += 1;
       return envValue;
     });
+    if (substitutions > 0 && out !== void 0) out.push(path.join("."));
+    return result;
   }
   if (Array.isArray(value)) {
-    return value.map((item) => interpolateEnvVars(item, env));
+    return value.map((item, index) => interpolateTracked(item, env, [...path, String(index)], out));
   }
   if (value !== null && typeof value === "object") {
     return Object.fromEntries(
       Object.entries(value).map(([k, v]) => [
         k,
-        interpolateEnvVars(v, env)
+        interpolateTracked(v, env, [...path, k], out)
       ])
     );
   }
   return value;
 }
-async function loadConfig(filePath, env) {
-  let raw;
+async function readConfigSource(filePath) {
+  let bytes;
   try {
-    raw = await readFile(filePath, "utf-8");
+    bytes = await readFile(filePath);
   } catch {
     throw new ConfigError(`Cannot read config file: ${filePath}`);
   }
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  return { raw: bytes.toString("utf-8"), sha256 };
+}
+function parseConfigSource(source, filePath, env) {
   let parsed;
   try {
-    parsed = yaml.load(raw);
+    parsed = yaml.load(source.raw);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     throw new ConfigError(`YAML parse error in ${filePath}: ${message}`);
   }
-  const interpolated = interpolateEnvVars(parsed, env);
+  const interpolatedPaths = [];
+  const interpolated = interpolateTracked(parsed, env ?? process.env, [], interpolatedPaths);
   const result = helioConfigSchema.safeParse(interpolated);
   if (!result.success) {
     const details = formatZodErrors(result.error).map(
@@ -1016,7 +1026,41 @@ async function loadConfig(filePath, env) {
       details
     );
   }
-  return result.data;
+  return { config: result.data, interpolatedPaths };
+}
+async function loadConfigWithMeta(filePath, env) {
+  const source = await readConfigSource(filePath);
+  const { config, interpolatedPaths } = parseConfigSource(source, filePath, env);
+  return { config, sha256: source.sha256, interpolatedPaths };
+}
+async function loadConfig(filePath, env) {
+  return (await loadConfigWithMeta(filePath, env)).config;
+}
+
+// src/config/reload-outcomes.ts
+var POLICY_RELOAD_OUTCOMES = [
+  "applied",
+  "rejected_invalid",
+  "rejected_unroutable",
+  "rejected_budget_flush",
+  "rejected_pinned",
+  "watch_failed"
+];
+
+// src/config/pin.ts
+var CONFIG_PIN_ENV = "HELIO_CONFIG_SHA256";
+var SHA256_HEX = /^[0-9a-f]{64}$/;
+function normalizeConfigPin(raw) {
+  const trimmed = raw.trim();
+  const unprefixed = /^sha256:/i.test(trimmed) ? trimmed.slice("sha256:".length) : trimmed;
+  const hex = unprefixed.toLowerCase();
+  return SHA256_HEX.test(hex) ? hex : null;
+}
+function readConfigPin(env = process.env) {
+  const raw = env[CONFIG_PIN_ENV];
+  if (raw === void 0) return { status: "unset" };
+  const sha256 = normalizeConfigPin(raw);
+  return sha256 === null ? { status: "invalid", raw } : { status: "set", sha256 };
 }
 
 // src/config/watcher.ts
@@ -1447,24 +1491,56 @@ function compileContributor(contributor, budgetName, index) {
 }
 
 // src/config/watcher.ts
+var PolicyReloadRejectedError = class extends Error {
+  outcome;
+  constructor(outcome, message, options) {
+    super(message, options);
+    this.name = "PolicyReloadRejectedError";
+    this.outcome = outcome;
+  }
+};
+function beforeFacts(baseline) {
+  return {
+    sha256Before: baseline.sha256,
+    ruleCountBefore: baseline.config.policies.rules.length,
+    defaultActionBefore: baseline.config.policies.default,
+    budgetCountBefore: baseline.config.budgets.length
+  };
+}
+function rulesRemovedBetween(previous, next) {
+  const kept = new Set(
+    next.policies.rules.flatMap((rule) => rule.name === void 0 ? [] : [rule.name])
+  );
+  return previous.policies.rules.flatMap(
+    (rule) => rule.name === void 0 || kept.has(rule.name) ? [] : [rule.name]
+  );
+}
 var ConfigWatcher = class {
   configPath;
   onReload;
   onError;
   onReady;
-  initialConfig;
+  initial;
   env;
   debounceMs;
+  /** When set, a reload whose bytes hash differently is refused before parsing (issue #341). */
+  pinnedSha256;
+  /** The last configuration that applied: the "before" side of the next attempt. */
+  lastGood;
   watcher = null;
   debounceTimer = null;
+  /** Set once the watch itself has failed; later change events and in-flight reloads are ignored (issue #351). */
+  watchFailed = false;
   constructor(options) {
     this.configPath = options.configPath;
     this.onReload = options.onReload;
     this.onError = options.onError;
     this.onReady = options.onReady;
-    this.initialConfig = options.initialConfig;
+    this.initial = options.initial;
+    this.lastGood = options.initial;
     this.env = options.env;
     this.debounceMs = options.debounceMs ?? 200;
+    this.pinnedSha256 = options.pinnedSha256;
   }
   /** Start watching the config file for changes. */
   start() {
@@ -1475,11 +1551,34 @@ var ConfigWatcher = class {
       awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 10 }
     });
     this.watcher.on("change", () => {
+      if (this.watchFailed) return;
       this.scheduleReload();
     });
     this.watcher.on("ready", () => {
       if (this.watcher && this.onReady) this.onReady();
     });
+    this.watcher.on("error", (err) => {
+      const error = err instanceof Error ? err : new Error(String(err));
+      if (this.watchFailed) return;
+      this.watchFailed = true;
+      if (this.debounceTimer !== null) {
+        clearTimeout(this.debounceTimer);
+        this.debounceTimer = null;
+      }
+      const before = beforeFacts(this.lastGood);
+      this.onError(error, {
+        configPath: this.configPath,
+        outcome: "watch_failed",
+        ...before,
+        sha256After: null,
+        ruleCountAfter: null,
+        defaultActionAfter: null,
+        budgetCountAfter: null,
+        rulesRemoved: [],
+        restartRequiredPaths: [],
+        error: error.message
+      });
+    });
   }
   /** Stop watching and clean up resources. */
   close() {
@@ -1502,22 +1601,320 @@ var ConfigWatcher = class {
     }, this.debounceMs);
   }
   async reload() {
+    const before = beforeFacts(this.lastGood);
+    let sha256After = null;
+    let parsed = null;
+    let restartRequiredPaths = [];
     try {
-      const config = await loadConfig(this.configPath, this.env);
+      const source = await readConfigSource(this.configPath);
+      sha256After = source.sha256;
+      if (this.pinnedSha256 !== void 0 && source.sha256 !== this.pinnedSha256) {
+        throw new PolicyReloadRejectedError(
+          "rejected_pinned",
+          `config hash sha256:${source.sha256} does not match the pinned sha256:${this.pinnedSha256}`
+        );
+      }
+      const { config } = parseConfigSource(source, this.configPath, this.env);
+      parsed = config;
       const { policy, warnings } = compilePolicies(config.policies);
       const budgets = compileBudgets(config.budgets);
-      const restartRequiredPaths = this.initialConfig !== void 0 ? diffReloadBoundary(this.initialConfig, config).restartRequiredPaths : [];
-      this.onReload(policy, warnings, restartRequiredPaths, budgets);
+      restartRequiredPaths = diffReloadBoundary(this.initial.config, config).restartRequiredPaths;
+      const facts = {
+        configPath: this.configPath,
+        outcome: "applied",
+        ...before,
+        sha256After: source.sha256,
+        ruleCountAfter: config.policies.rules.length,
+        defaultActionAfter: config.policies.default,
+        budgetCountAfter: config.budgets.length,
+        rulesRemoved: rulesRemovedBetween(this.lastGood.config, config),
+        restartRequiredPaths,
+        error: null
+      };
+      if (this.watchFailed) return;
+      this.onReload(policy, warnings, restartRequiredPaths, budgets, facts);
+      this.lastGood = { config, sha256: source.sha256 };
     } catch (err) {
-      if (err instanceof Error) {
-        this.onError(err);
-      } else {
-        this.onError(new Error(String(err)));
-      }
+      const error = err instanceof Error ? err : new Error(String(err));
+      const outcome = error instanceof PolicyReloadRejectedError ? error.outcome : "rejected_invalid";
+      if (this.watchFailed) return;
+      this.onError(error, {
+        configPath: this.configPath,
+        outcome,
+        ...before,
+        sha256After,
+        ruleCountAfter: parsed === null ? null : parsed.policies.rules.length,
+        defaultActionAfter: parsed === null ? null : parsed.policies.default,
+        budgetCountAfter: parsed === null ? null : parsed.budgets.length,
+        rulesRemoved: parsed === null ? [] : rulesRemovedBetween(this.lastGood.config, parsed),
+        restartRequiredPaths,
+        error: error.message
+      });
     }
   }
 };
 
+// src/auth/bearer.ts
+import { createHash as createHash2, timingSafeEqual } from "crypto";
+var BEARER_PREFIX = "Bearer ";
+var DIGEST_PATTERN = /^sha256:([0-9a-f]{64})$/;
+function isSecretDigest(value) {
+  return DIGEST_PATTERN.test(value);
+}
+function secretDigest(plaintext) {
+  return `sha256:${createHash2("sha256").update(plaintext, "utf-8").digest("hex")}`;
+}
+function verifyBearer(authHeader, expected) {
+  if (!authHeader || !expected) return false;
+  if (!authHeader.startsWith(BEARER_PREFIX)) return false;
+  const presented = authHeader.slice(BEARER_PREFIX.length);
+  const storedHex = DIGEST_PATTERN.exec(expected)?.[1];
+  const expectedDigest = storedHex !== void 0 ? Buffer.from(storedHex, "hex") : createHash2("sha256").update(expected, "utf-8").digest();
+  const actualDigest = createHash2("sha256").update(presented, "utf-8").digest();
+  return timingSafeEqual(actualDigest, expectedDigest);
+}
+
+// src/sandbox-scaffold.ts
+var SANDBOX_DEFAULT_DIR = "helio-sandbox";
+var SANDBOX_FILES = ["compose.yaml", "helio/helio.yaml", "helio/README.md"];
+var SANDBOX_FORWARDER_IMAGE = "nginx:1.30-alpine";
+var SANDBOX_AGENT_PLACEHOLDER_IMAGE = "curlimages/curl:8.22.0";
+function sandboxImageTag(version) {
+  return version === "0.0.0" ? "latest" : version;
+}
+function renderSandboxCompose(options) {
+  const { imageTag } = options;
+  return `# Helio sidecar layout: four services on three networks. The sidecar
+# guide (docs/deployment-sidecar.md) explains every line and carries the
+# checks that prove the layout from inside the agent container.
+#
+#   agent        edge              your coding agent (placeholder below)
+#   helio-edge   edge + plane      forwards :3000 to Helio; the only thing the agent can reach
+#   helio        plane + internal  the proxy; attached to no network the agent is on
+#   mcp-server   internal          your MCP server (placeholder below)
+services:
+  agent:
+    # Placeholder: a shell with curl, so the verification checks run
+    # before you wire your own dev container in. Replace \`image:\` with
+    # your agent image or a \`build:\`; keep \`networks: [edge]\`; mount your
+    # project from a sibling directory (./workspace:/workspace). Never
+    # mount this directory, ./helio, a .env file, or the Docker socket
+    # into it.
+    image: ${SANDBOX_AGENT_PLACEHOLDER_IMAGE}
+    command: ['sleep', 'infinity']
+    networks: [edge]
+
+  helio-edge:
+    # TCP forwarder for the MCP edge. Point the agent's MCP client at
+    # http://helio-edge:3000/mcp. It relays port 3000 and nothing else.
+    image: ${SANDBOX_FORWARDER_IMAGE}
+    configs:
+      - source: helio_edge_conf
+        target: /etc/nginx/nginx.conf
+    networks: [edge, plane]
+    depends_on: [helio]
+    restart: unless-stopped
+
+  helio:
+    image: ghcr.io/gethelio/helio:${imageTag}
+    networks: [plane, internal]
+    environment:
+      # Put HELIO_DASHBOARD_SECRET=<secret or sha256:digest> in ./.env
+      # (this directory is never mounted into agent) or export it.
+      # \`helio secret\` prints a fresh pair.
+      HELIO_DASHBOARD_SECRET: '\${HELIO_DASHBOARD_SECRET:?put it in ./.env or export it; generate with: helio secret}'
+    volumes:
+      - ./helio:/config:ro
+      - helio-data:/data
+    ports:
+      # The dashboard, the operator control plane: host loopback only.
+      - '127.0.0.1:3100:3100'
+    depends_on: [mcp-server]
+    restart: unless-stopped
+
+  mcp-server:
+    # Your MCP server. Set the image first: \`docker compose up\` fails at
+    # the image pull until you do. Keep it on \`internal\` only. To try the
+    # layout without one, save
+    # https://raw.githubusercontent.com/gethelio/helio/main/docker/mcp-echo-server.mjs
+    # as ./mcp-server/server.mjs and use the three commented lines
+    # instead of the image line.
+    image: your-org/your-mcp-server:latest
+    # image: node:24-slim
+    # command: ['node', '/srv/server.mjs']
+    # volumes: ['./mcp-server/server.mjs:/srv/server.mjs:ro']
+    networks: [internal]
+    restart: unless-stopped
+
+configs:
+  helio_edge_conf:
+    content: |
+      events {}
+      stream {
+        resolver 127.0.0.11 valid=1s;
+        server {
+          listen 3000;
+          proxy_timeout 1h;
+          set $$helio helio:3000;
+          proxy_pass $$helio;
+        }
+      }
+
+networks:
+  edge: {} # agent + helio-edge; an ordinary bridge with internet egress
+  plane: {} # helio-edge + helio; Helio's route out for internet upstreams
+  internal:
+    internal: true # helio + mcp-server; no route anywhere else
+
+volumes:
+  helio-data: {}
+`;
+}
+function renderSandboxConfig() {
+  return `# Helio sidecar config. This directory is mounted read-only into the
+# helio service and never into the agent. Edit it on the host; policy
+# changes reload live.
+version: '1'
+
+upstream:
+  url: 'http://mcp-server:8080/mcp' # compose service name on the internal network
+  transport: streamable-http
+  # For an upstream that needs a credential, keep the only copy in this
+  # service's environment; the agent never holds it:
+  # headers:
+  #   Authorization: 'Bearer \${UPSTREAM_TOKEN}'
+
+listen:
+  port: 3000
+  host: '0.0.0.0' # inside the container; reached only through helio-edge
+
+policies:
+  default: allow
+  rules:
+    # Deny anything the tool marks as destructive.
+    - name: block-destructive
+      match:
+        annotations:
+          destructiveHint: true
+      action: deny
+      feedback:
+        message: 'Destructive actions are blocked by policy.'
+        suggestion: 'Use a non-destructive alternative or request approval.'
+    # Allow read-only tools.
+    - name: allow-reads
+      match:
+        annotations:
+          readOnlyHint: true
+      action: allow
+
+audit:
+  storage: sqlite
+  path: /data/helio-audit.db
+  retention: 90d
+  include_responses: true
+
+dashboard:
+  enabled: true
+  port: 3100
+  host: '0.0.0.0' # inside the container; the agent is on no network this container is on
+  # The variable may hold the secret or the sha256: digest \`helio secret\` prints.
+  api_secret: '\${HELIO_DASHBOARD_SECRET}'
+`;
+}
+function renderSandboxReadme() {
+  return `# Helio sidecar layout
+
+Written by \`helio init --sandbox\`. This directory is the Compose
+project directory. The agent container never mounts it.
+
+## What this layout guarantees
+
+From inside the \`agent\` container there is no route to the upstream
+except through Helio, no mount holding Helio's config, no route to
+Helio's dashboard by service name or address, and no copy of an
+upstream credential. Helio is attached to no network the agent is on;
+\`helio-edge\` forwards TCP port 3000 to it and nothing else.
+
+## Make it yours
+
+1. \`compose.yaml\`: set the \`agent\` image (or \`build:\`) and the
+   \`mcp-server\` image. \`docker compose up\` fails at the image pull until
+   the \`mcp-server\` image is set. Keep \`agent\` on \`edge\` only and
+   \`mcp-server\` on \`internal\` only.
+2. Run \`helio secret\`. Put \`HELIO_DASHBOARD_SECRET=sha256:<digest>\` in
+   \`./.env\` next to \`compose.yaml\` (or export it). The variable may hold
+   the secret itself or its \`sha256:\` digest; the dashboard login and the
+   Bearer header always take the secret.
+3. \`docker compose up -d\`, then run the checks below from inside the
+   agent container (\`docker compose exec agent sh\`).
+4. Point the agent's MCP client at \`http://helio-edge:3000/mcp\`. The
+   dashboard is on the host at \`http://127.0.0.1:3100\`.
+
+## Hard constraints
+
+- Never mount \`.\` or \`.env\` into the \`agent\` service.
+- Never mount \`docker.sock\` into it; an agent with the socket is the host.
+- Secrets only on the \`helio\` service.
+- \`./helio/\` is never mounted into \`agent\`.
+- \`edge\` has internet egress, so an upstream the agent could reach on
+  its own is protected only by Helio holding the sole copy of its
+  credential (\`upstream.headers\` with \`\${VAR}\` in \`helio/helio.yaml\`).
+
+## Verify from inside the agent container
+
+\`\`\`sh
+# 1. No route to the upstream: must fail (exit 6 or 7).
+curl -s -m 3 http://mcp-server:8080/mcp; echo "exit: $?"
+# 2. No mount holding the config: both paths must be missing.
+ls /config /workspace/helio 2>&1; echo "exit: $?"
+# 3. No route to the dashboard: must fail (exit 6; helio-edge:3100 gives 7).
+curl -s -m 3 http://helio:3100/api/health; echo "exit: $?"
+# 4. No credential in the environment: must print nothing.
+env | grep -iE 'helio|upstream|secret'; echo "exit: $?"
+# Through Helio it works and is audited:
+curl -s -m 5 -X POST http://helio-edge:3000/mcp \\
+  -H 'Content-Type: application/json' \\
+  -H 'Accept: application/json, text/event-stream' \\
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+\`\`\`
+
+On Docker Desktop (macOS and Windows) every port published to the host
+is reachable from every container through the Desktop host gateway:
+\`curl -s -m 3 http://host.docker.internal:3100/api/health\` answers from
+the agent there. Run the same probe on your own host and believe its
+answer. The dashboard's control-plane routes stay behind its secret,
+which the agent does not hold; \`/api/health\` answers without it. If that
+is not acceptable, front the dashboard with an
+authenticating reverse proxy or do not publish it while an untrusted
+agent runs.
+
+## Editing the config
+
+\`./helio/\` is mounted read-only into the \`helio\` service, so edit
+\`helio/helio.yaml\` on the host; policy changes reload live. Change it
+from the host only. The agent container has no path to it, and that is
+the point.
+
+## Dev container
+
+\`workspace/.devcontainer/devcontainer.json\`:
+
+\`\`\`jsonc
+{
+  "name": "agent-workspace",
+  "dockerComposeFile": "../../compose.yaml",
+  "service": "agent",
+  "workspaceFolder": "/workspace"
+}
+\`\`\`
+
+and in \`compose.yaml\` give \`agent\` the mount \`./workspace:/workspace:cached\`
+(a sibling of \`helio/\`, never this directory itself). Do not add a
+\`forwardPorts\` entry for the dashboard: it is published to the host by
+the \`helio\` service, and the agent has no route to \`helio\` by design.
+`;
+}
+
 // src/server.ts
 import { Hono as Hono3 } from "hono";
 import { serve } from "@hono/node-server";
@@ -7138,6 +7535,7 @@ function clampInt(value, fallback, min, max) {
 // src/audit/store.ts
 var DRIFT_EVENT_DECISIONS_SQL = "('tool_drift', 'tool_drift_reverted')";
 var NON_TOOL_DECISIONS_SQL = "('tool_drift', 'tool_drift_reverted', 'rejected')";
+var POLICY_RELOAD_KIND_SQL = "'policy_reload'";
 var EXPORT_MAX_RECORDS = 1e4;
 var LIST_MAX_PAGE_SIZE = 1e3;
 var CREATE_TABLE_DDL = `
@@ -7171,7 +7569,8 @@ CREATE TABLE IF NOT EXISTS audit_records (
   metadata          TEXT,
   protocol_version  TEXT,
   created_at        TEXT NOT NULL,
-  upstream          TEXT
+  upstream          TEXT,
+  config_sha256     TEXT
 );
 `;
 var CREATE_INDEX_DDL = `
@@ -7184,6 +7583,7 @@ CREATE INDEX IF NOT EXISTS idx_audit_upstream_status_created_at ON audit_records
 CREATE INDEX IF NOT EXISTS idx_audit_record_kind     ON audit_records (record_kind);
 CREATE INDEX IF NOT EXISTS idx_audit_origin          ON audit_records (origin);
 CREATE INDEX IF NOT EXISTS idx_audit_upstream        ON audit_records (upstream);
+CREATE INDEX IF NOT EXISTS idx_audit_config_sha256   ON audit_records (config_sha256);
 `;
 var INSERT_SQL = `
 INSERT INTO audit_records (
@@ -7193,7 +7593,7 @@ INSERT INTO audit_records (
   upstream_http_status,
   total_duration_ms, approval_wait_ms, proxy_compute_ms,
   flagged_destructive, dry_run, record_kind, origin, metadata, protocol_version, created_at,
-  upstream
+  upstream, config_sha256
 ) VALUES (
   @id, @timestamp, @session_id, @session_source, @agent_id, @environment, @tool_name, @tool_input,
   @policy_decision, @block_reason, @matched_rule, @matched_rule_index, @evidence_chain, @approval_status,
@@ -7201,7 +7601,7 @@ INSERT INTO audit_records (
   @upstream_http_status,
   @total_duration_ms, @approval_wait_ms, @proxy_compute_ms,
   @flagged_destructive, @dry_run, @record_kind, @origin, @metadata, @protocol_version, @created_at,
-  @upstream
+  @upstream, @config_sha256
 )
 `;
 var REQUIRED_AUDIT_COLUMNS = [
@@ -7221,10 +7621,14 @@ var REQUIRED_AUDIT_COLUMNS = [
   // Same clean break, same unreleased cycle (issue #219): released users see
   // ONE break, at v0.12.0.
   "protocol_version",
-  // The one ratified exception to the clean break (issue #292): a
-  // v0.12.0-complete database missing ONLY this column is migrated in place
-  // by migrateAuditUpstreamColumn instead of failing the assertion.
-  "upstream"
+  // The ratified exception to the clean break (issue #292): a database that
+  // is complete except for this column is migrated in place by
+  // migrateAdditiveAuditColumns instead of failing the assertion.
+  "upstream",
+  // The second additive column under the same exception (issue #341): a
+  // v0.13 database missing only this one, or a v0.12.0 database missing
+  // both, migrates in place; anything older still clean-breaks.
+  "config_sha256"
 ];
 function deserializeRow(row) {
   return {
@@ -7257,6 +7661,7 @@ function deserializeRow(row) {
     metadata: row.metadata ? JSON.parse(row.metadata) : null,
     protocol_version: row.protocol_version,
     upstream: row.upstream,
+    config_sha256: row.config_sha256,
     created_at: row.created_at
   };
 }
@@ -7337,21 +7742,34 @@ function buildWhereClause(filters) {
   const clause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   return { clause, params };
 }
-function migrateAuditUpstreamColumn(db) {
+var ADDITIVE_AUDIT_COLUMNS = [
+  { name: "upstream", ddl: "upstream TEXT" },
+  { name: "config_sha256", ddl: "config_sha256 TEXT" }
+];
+function migrateAdditiveAuditColumns(db) {
   const probe = () => {
     const rows = db.pragma("table_info(audit_records)");
     return new Set(rows.map((row) => row.name));
   };
   const existing = probe();
-  const missing = REQUIRED_AUDIT_COLUMNS.filter((name) => !existing.has(name));
-  if (missing.length !== 1 || missing[0] !== "upstream") return false;
-  try {
-    db.exec("ALTER TABLE audit_records ADD COLUMN upstream TEXT");
-  } catch (err) {
-    if (probe().has("upstream")) return false;
-    throw err;
+  const missing = new Set(REQUIRED_AUDIT_COLUMNS.filter((name) => !existing.has(name)));
+  if (missing.size === 0) return [];
+  const additive = new Set(ADDITIVE_AUDIT_COLUMNS.map((column) => column.name));
+  for (const name of missing) {
+    if (!additive.has(name)) return [];
+  }
+  const added = [];
+  for (const column of ADDITIVE_AUDIT_COLUMNS) {
+    if (!missing.has(column.name)) continue;
+    try {
+      db.exec(`ALTER TABLE audit_records ADD COLUMN ${column.ddl}`);
+    } catch (err) {
+      if (probe().has(column.name)) continue;
+      throw err;
+    }
+    added.push(column.name);
   }
-  return true;
+  return added;
 }
 function restrictAuditFilePerms(dbPath) {
   if (dbPath === ":memory:" || process.platform === "win32") return;
@@ -7381,8 +7799,8 @@ var AuditStore = class {
     this.retentionMs = parseDuration(options.retention);
     this.includeResponses = options.includeResponses;
     this.db.exec(CREATE_TABLE_DDL);
-    if (migrateAuditUpstreamColumn(this.db)) {
-      console.error('[helio] Audit DB migrated: added column "upstream"');
+    for (const name of migrateAdditiveAuditColumns(this.db)) {
+      console.error(`[helio] Audit DB migrated: added column "${name}"`);
     }
     this.assertRequiredSchema(options.path);
     this.db.exec(CREATE_INDEX_DDL);
@@ -7493,6 +7911,7 @@ var AuditStore = class {
       metadata: record.metadata ? JSON.stringify(record.metadata) : null,
       protocol_version: record.protocol_version,
       upstream: record.upstream ?? null,
+      config_sha256: record.config_sha256 ?? null,
       created_at: now
     });
     return resolvedId;
@@ -7580,26 +7999,27 @@ var AuditStore = class {
     const totals = this.db.prepare(
       `SELECT
            COUNT(*) as total,
-           COALESCE(SUM(CASE WHEN block_reason IS NULL AND policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL} THEN 1 ELSE 0 END), 0) as allowed_total,
-           COALESCE(SUM(CASE WHEN block_reason IS NOT NULL THEN 1 ELSE 0 END), 0) as blocked_total,
-           COALESCE(SUM(CASE WHEN dry_run = 1 THEN 1 ELSE 0 END), 0) as dry_run_total,
-           COALESCE(SUM(CASE WHEN dry_run = 0 THEN 1 ELSE 0 END), 0) as applied_total
+           COALESCE(SUM(CASE WHEN block_reason IS NULL AND policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL} AND record_kind <> ${POLICY_RELOAD_KIND_SQL} THEN 1 ELSE 0 END), 0) as allowed_total,
+           COALESCE(SUM(CASE WHEN block_reason IS NOT NULL AND record_kind <> ${POLICY_RELOAD_KIND_SQL} THEN 1 ELSE 0 END), 0) as blocked_total,
+           COALESCE(SUM(CASE WHEN dry_run = 1 AND record_kind <> ${POLICY_RELOAD_KIND_SQL} THEN 1 ELSE 0 END), 0) as dry_run_total,
+           COALESCE(SUM(CASE WHEN dry_run = 0 AND record_kind <> ${POLICY_RELOAD_KIND_SQL} THEN 1 ELSE 0 END), 0) as applied_total
          FROM audit_records ${clause}`
     ).get(...params);
+    const decisionClause = clause ? `${clause} AND record_kind <> ${POLICY_RELOAD_KIND_SQL}` : `WHERE record_kind <> ${POLICY_RELOAD_KIND_SQL}`;
     const by_decision = this.db.prepare(
       `SELECT policy_decision as decision, COUNT(*) as count
-         FROM audit_records ${clause}
+         FROM audit_records ${decisionClause}
          GROUP BY policy_decision
          ORDER BY count DESC`
     ).all(...params);
-    const blockedClause = clause ? `${clause} AND block_reason IS NOT NULL` : "WHERE block_reason IS NOT NULL";
+    const blockedClause = clause ? `${clause} AND block_reason IS NOT NULL AND record_kind <> ${POLICY_RELOAD_KIND_SQL}` : `WHERE block_reason IS NOT NULL AND record_kind <> ${POLICY_RELOAD_KIND_SQL}`;
     const by_block_reason = this.db.prepare(
       `SELECT block_reason as reason, COUNT(*) as count
          FROM audit_records ${blockedClause}
          GROUP BY block_reason
          ORDER BY count DESC`
     ).all(...params);
-    const toolsClause = clause ? `${clause} AND policy_decision NOT IN ${NON_TOOL_DECISIONS_SQL}` : `WHERE policy_decision NOT IN ${NON_TOOL_DECISIONS_SQL}`;
+    const toolsClause = clause ? `${clause} AND policy_decision NOT IN ${NON_TOOL_DECISIONS_SQL} AND record_kind <> ${POLICY_RELOAD_KIND_SQL}` : `WHERE policy_decision NOT IN ${NON_TOOL_DECISIONS_SQL} AND record_kind <> ${POLICY_RELOAD_KIND_SQL}`;
     const top_tools = this.db.prepare(
       `SELECT tool_name, upstream, COUNT(*) as count
          FROM audit_records ${toolsClause}
@@ -7665,6 +8085,15 @@ var AuditWriter = class {
   bufferSize;
   onPush;
   onPersist;
+  /**
+   * The hash of the config file in force (issue #341), stamped onto every
+   * record whose builder left `config_sha256` nullish. Seeded at
+   * construction so no record is pushed unstamped before the first
+   * `setConfigSha256`; replaced by the reload path once the new policy is
+   * in force. Null only when the caller never had a hash (library
+   * embeddings without a config file).
+   */
+  configSha256;
   buffer = [];
   timer = null;
   flushSoonTimer = null;
@@ -7674,6 +8103,7 @@ var AuditWriter = class {
     this.bufferSize = options.bufferSize ?? 50;
     this.onPush = options.onPush;
     this.onPersist = options.onPersist;
+    this.configSha256 = options.configSha256 ?? null;
     const intervalMs = options.flushIntervalMs ?? 100;
     if (intervalMs > 0) {
       this.timer = setInterval(() => {
@@ -7694,8 +8124,9 @@ var AuditWriter = class {
    * is scheduled. This keeps request-path latency bounded even under bursty
    * write load.
    */
-  push(record, id = randomUUID4()) {
+  push(input, id = randomUUID4()) {
     if (this.closed) return;
+    const record = this.stamp(input);
     this.buffer.push({ id, record });
     this.onPush?.(record, id);
     if (this.buffer.length >= this.bufferSize) {
@@ -7710,12 +8141,30 @@ var AuditWriter = class {
    * A fatal-process crash still invokes the crash-drain hook, which calls
    * `flush()` synchronously before exit.
    */
-  pushImmediate(record, id = randomUUID4()) {
+  pushImmediate(input, id = randomUUID4()) {
     if (this.closed) return;
+    const record = this.stamp(input);
     this.buffer.push({ id, record });
     this.onPush?.(record, id);
     this.scheduleFlushSoon();
   }
+  /**
+   * Replace the config hash every later record is stamped with. Called by
+   * the reload path after the new policy is in force, before the reload's
+   * own record is pushed, so the reload record and every call it governs
+   * carry the new hash.
+   */
+  setConfigSha256(hash) {
+    this.configSha256 = hash;
+  }
+  /**
+   * Stamp the active config hash onto a record whose builder left the field
+   * nullish; a record that already carries a hash is passed through. The
+   * stamped record is what `onPush`, the store, and `onPersist` see.
+   */
+  stamp(record) {
+    return record.config_sha256 == null ? { ...record, config_sha256: this.configSha256 } : record;
+  }
   /**
    * Schedule a flush on the next tick, coalescing multiple calls into one.
    */
@@ -7811,6 +8260,80 @@ function buildHeaderMismatchAuditRecord(rejection, environment, upstream) {
   };
 }
 
+// src/audit/policy-reload.ts
+import { basename } from "path";
+import { z as z4 } from "zod";
+var POLICY_RELOAD_DECISION = "policy_reload";
+function policyReloadEvidence(facts) {
+  return {
+    outcome: facts.outcome,
+    config_path: facts.configPath,
+    sha256_before: facts.sha256Before,
+    sha256_after: facts.sha256After,
+    rule_count_before: facts.ruleCountBefore,
+    rule_count_after: facts.ruleCountAfter,
+    default_action_before: facts.defaultActionBefore,
+    default_action_after: facts.defaultActionAfter,
+    budget_count_before: facts.budgetCountBefore,
+    budget_count_after: facts.budgetCountAfter,
+    rules_removed: [...facts.rulesRemoved],
+    restart_required_paths: [...facts.restartRequiredPaths],
+    error: facts.error
+  };
+}
+function buildPolicyReloadRecord(facts, environment) {
+  return {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    session_id: null,
+    session_source: null,
+    agent_id: null,
+    environment,
+    tool_name: basename(facts.configPath),
+    tool_input: {},
+    policy_decision: POLICY_RELOAD_DECISION,
+    block_reason: facts.outcome === "applied" ? null : facts.outcome,
+    matched_rule: null,
+    matched_rule_index: null,
+    evidence_chain: { policy_reload: policyReloadEvidence(facts) },
+    approval_status: null,
+    approved_by: null,
+    upstream_response: null,
+    upstream_error: null,
+    upstream_http_status: null,
+    upstream_latency_ms: null,
+    total_duration_ms: 0,
+    approval_wait_ms: 0,
+    proxy_compute_ms: 0,
+    flagged_destructive: false,
+    dry_run: false,
+    record_kind: "policy_reload",
+    origin: "config",
+    metadata: null,
+    protocol_version: null,
+    upstream: null
+  };
+}
+var policyReloadEvidenceSchema = z4.object({
+  outcome: z4.enum(POLICY_RELOAD_OUTCOMES),
+  config_path: z4.string(),
+  sha256_before: z4.string(),
+  sha256_after: z4.string().nullable(),
+  rule_count_before: z4.number(),
+  rule_count_after: z4.number().nullable(),
+  default_action_before: z4.enum(["allow", "deny"]),
+  default_action_after: z4.enum(["allow", "deny"]).nullable(),
+  budget_count_before: z4.number(),
+  budget_count_after: z4.number().nullable(),
+  rules_removed: z4.array(z4.string()),
+  restart_required_paths: z4.array(z4.string()),
+  error: z4.string().nullable()
+}).strict();
+function readPolicyReloadEvidence(record) {
+  if (record.record_kind !== "policy_reload") return null;
+  const parsed = policyReloadEvidenceSchema.safeParse(record.evidence_chain?.["policy_reload"]);
+  return parsed.success ? parsed.data : null;
+}
+
 // src/evidence/store.ts
 var EvidenceStore = class _EvidenceStore {
   static EVIDENCE_ALLOWLIST_PREVIEW_LIMIT = 20;
@@ -8105,80 +8628,70 @@ var EvidenceStore = class _EvidenceStore {
 import { Hono as Hono5 } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { HTTPException } from "hono/http-exception";
-import { z as z5 } from "zod";
-
-// src/auth/bearer.ts
-import { createHash, timingSafeEqual } from "crypto";
-function verifyBearer(authHeader, expected) {
-  if (!authHeader || !expected) return false;
-  const expectedHeader = `Bearer ${expected}`;
-  const actualDigest = createHash("sha256").update(authHeader).digest();
-  const expectedDigest = createHash("sha256").update(expectedHeader).digest();
-  return timingSafeEqual(actualDigest, expectedDigest);
-}
+import { z as z6 } from "zod";
 
 // 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({
+import { z as z5 } from "zod";
+import { createHash as createHash3 } from "crypto";
+var originSchema = z5.string().regex(/^[a-z0-9_-]{1,64}$/, "origin must match ^[a-z0-9_-]{1,64}$").default("sideband");
+var metadataSchema = z5.record(z5.string(), z5.unknown()).nullish();
+var toolDefinitionSchema = z5.object({
   // Stored verbatim in pending entries and audit rows; capped so a
   // caller-minted name cannot inflate the pending-entry footprint.
-  name: z4.string().min(1).max(256),
-  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()
+  name: z5.string().min(1).max(256),
+  description: z5.string().optional(),
+  input_schema: z5.unknown().optional(),
+  output_schema: z5.unknown().optional(),
+  title: z5.string().optional(),
+  annotations: z5.record(z5.string(), z5.unknown()).optional()
 });
-var evaluateBody = z4.object({
+var evaluateBody = z5.object({
   origin: originSchema,
-  adapter_version: z4.string().max(64).optional(),
+  adapter_version: z5.string().max(64).optional(),
   // Stored in pending entries and limit bucket keys; capped (like origin and
   // adapter_version) so caller-minted ids cannot inflate memory unaccounted.
-  agent_id: z4.string().max(128).nullish(),
-  session_id: z4.string().max(256).nullish(),
+  agent_id: z5.string().max(128).nullish(),
+  session_id: z5.string().max(256).nullish(),
   tool: toolDefinitionSchema,
-  arguments: z4.record(z4.string(), z4.unknown()).optional(),
+  arguments: z5.record(z5.string(), z5.unknown()).optional(),
   metadata: metadataSchema
 });
-var installScanBody = z4.object({
+var installScanBody = z5.object({
   origin: originSchema,
-  agent_id: z4.string().max(128).nullish(),
-  session_id: z4.string().max(256).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()
+  agent_id: z5.string().max(128).nullish(),
+  session_id: z5.string().max(256).nullish(),
+  package: z5.object({
+    name: z5.string().min(1),
+    version: z5.string().optional(),
+    source: z5.string().max(64).optional(),
+    spec: z5.string().optional(),
+    url: z5.string().optional()
   }),
   metadata: metadataSchema
 });
-var evidenceEntrySchema = z4.object({
-  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 evidenceEntrySchema = z5.object({
+  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 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 auditBody = z5.object({
+  evaluation_id: z5.string().min(1),
+  status: z5.enum(["success", "error", "not_executed"]),
+  error: z5.string().optional(),
+  duration_ms: z5.number().optional(),
+  result: z5.unknown().optional(),
+  actual_amount: z5.number().optional(),
   // No `.max()` / size refinement here on purpose (issue #11): caps are
   // enforced per-entry in GovernanceService.populateEvidence as soft-drops, so
   // an over-cap entry never 400s away the audit row for a call that already ran.
-  evidence: z4.array(evidenceEntrySchema).optional()
+  evidence: z5.array(evidenceEntrySchema).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 resolveBody = z5.object({
+  resolution: z5.enum(["approved", "denied", "timeout", "cancelled"]),
+  resolved_by: z5.string().optional(),
+  reason: z5.string().optional(),
+  scope: z5.enum(["once", "always"]).optional()
 });
 var MAX_METADATA_BYTES = 4 * 1024;
 function createGovernanceApp(service) {
@@ -8277,7 +8790,7 @@ function auditPayloadHash(data) {
     actual_amount: data.actual_amount ?? null,
     evidence: canonicalEvidence(data.evidence)
   };
-  return createHash2("sha256").update(canonicalize(semantic)).digest("hex");
+  return createHash3("sha256").update(canonicalize(semantic)).digest("hex");
 }
 function canonicalEvidence(evidence) {
   if (!evidence || evidence.length === 0) return null;
@@ -8293,20 +8806,20 @@ function asStatus(status) {
 
 // src/evidence/api.ts
 var SIDEBAND_BODY_LIMIT_BYTES = 1 * 1024 * 1024;
-var sessionIdSchema = z5.string().min(1).refine((value) => value.trim() !== "", {
+var sessionIdSchema = z6.string().min(1).refine((value) => value.trim() !== "", {
   message: "session_id must not be whitespace-only"
 });
-var postEvidenceBody = z5.object({
+var postEvidenceBody = z6.object({
   session_id: sessionIdSchema,
-  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()
+  tool_name: z6.string().min(1),
+  evidence_key: z6.string().min(1),
+  evidence_data: z6.unknown().refine((v) => v !== void 0, { message: "Required" }),
+  ttl_seconds: z6.number().int().positive().optional()
 });
-var postContextBody = z5.object({
+var postContextBody = z6.object({
   session_id: sessionIdSchema,
-  key: z5.string().min(1),
-  value: z5.unknown().refine((v) => v !== void 0, { message: "Required" })
+  key: z6.string().min(1),
+  value: z6.unknown().refine((v) => v !== void 0, { message: "Required" })
 });
 function createSidebandApp(store, options = {}) {
   const app = new Hono5();
@@ -10371,7 +10884,7 @@ function createChannels(channels) {
 // src/approval/slack-actions.ts
 import { createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
 import { Hono as Hono6 } from "hono";
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var MAX_TIMESTAMP_AGE_S = 300;
 var REJECTION_LOG_WINDOW_MS = 6e4;
 var REJECTION_LOG_SAMPLE_EVERY = 25;
@@ -10437,12 +10950,12 @@ function verifySlackSignature(secrets, timestamp, rawBody, signature) {
   }
   return false;
 }
-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() })
+var slackActionPayloadSchema = z7.object({
+  type: z7.string(),
+  user: z7.object({ id: z7.string(), username: z7.string() }),
+  actions: z7.array(z7.object({ action_id: z7.string() })),
+  channel: z7.object({ id: z7.string() }),
+  message: z7.object({ ts: z7.string() })
 });
 function parseActionPayload(rawBody) {
   try {
@@ -10572,17 +11085,17 @@ function createSlackActionApp(options) {
 
 // src/approval/api.ts
 import { Hono as Hono7 } from "hono";
-import { z as z7 } from "zod";
-var approveBody = z7.object({
-  approved_by: z7.string().min(1)
+import { z as z8 } from "zod";
+var approveBody = z8.object({
+  approved_by: z8.string().min(1)
 });
-var denyBody = z7.object({
-  denied_by: z7.string().min(1),
-  reason: z7.string().optional()
+var denyBody = z8.object({
+  denied_by: z8.string().min(1),
+  reason: z8.string().optional()
 });
-var breakGlassBody = z7.object({
-  approved_by: z7.string().min(1),
-  reason: z7.string().min(1)
+var breakGlassBody = z8.object({
+  approved_by: z8.string().min(1),
+  reason: z8.string().min(1)
 });
 var APPROVAL_STATUSES = [
   "pending",
@@ -10595,18 +11108,18 @@ var APPROVAL_STATUSES = [
   "cancelled"
 ];
 var approvalStatusSet = new Set(APPROVAL_STATUSES);
-var listApprovalsQuery = z7.object({
-  status: z7.preprocess(
+var listApprovalsQuery = z8.object({
+  status: z8.preprocess(
     (value) => typeof value === "string" && approvalStatusSet.has(value) ? value : void 0,
-    z7.enum(APPROVAL_STATUSES).optional()
+    z8.enum(APPROVAL_STATUSES).optional()
   ),
-  limit: z7.preprocess(
+  limit: z8.preprocess(
     (value) => clampInt(typeof value === "string" ? value : void 0, 50, 1, 1e3),
-    z7.number().int()
+    z8.number().int()
   ),
-  offset: z7.preprocess(
+  offset: z8.preprocess(
     (value) => clampInt(typeof value === "string" ? value : void 0, 0, 0, Number.MAX_SAFE_INTEGER),
-    z7.number().int()
+    z8.number().int()
   )
 });
 function createApprovalApp(router, queue, options) {
@@ -11630,11 +12143,12 @@ var CSV_HEADERS = [
   "record_kind",
   "origin",
   "metadata",
-  // Appended LAST (issues #218, #219, #292): positional consumers of the
-  // existing columns keep working — new columns always go at the end.
+  // Appended LAST (issues #218, #219, #292, #341): positional consumers of
+  // the existing columns keep working — new columns always go at the end.
   "session_source",
   "protocol_version",
-  "upstream"
+  "upstream",
+  "config_sha256"
 ];
 var FORMULA_PREFIXES = /^[=+\-@\t\r]/;
 function csvEscape(value) {
@@ -11702,25 +12216,25 @@ function budgetEventsToCsv(events) {
 // src/dashboard/api.ts
 import { readFileSync } from "fs";
 import { join } from "path";
-import { randomUUID as randomUUID8 } from "crypto";
+import { randomBytes as randomBytes2, randomUUID as randomUUID8 } from "crypto";
 import { Hono as Hono8 } from "hono";
 import { HTTPException as HTTPException2 } from "hono/http-exception";
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 import { cors } from "hono/cors";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { streamSSE } from "hono/streaming";
 
 // src/dashboard/session.ts
-import { createHash as createHash3, createHmac as createHmac3, randomBytes, timingSafeEqual as timingSafeEqual3 } from "crypto";
+import { createHash as createHash4, createHmac as createHmac3, randomBytes, timingSafeEqual as timingSafeEqual3 } from "crypto";
 var DashboardSessionStore = class {
-  secret;
+  signingKey;
   ttlMs;
   now;
   records = /* @__PURE__ */ new Map();
   timer = null;
   closed = false;
   constructor(options) {
-    this.secret = options.secret;
+    this.signingKey = options.signingKey;
     this.ttlMs = options.ttlMs ?? 8 * 60 * 60 * 1e3;
     this.now = options.now ?? Date.now;
     const cleanupIntervalMs = options.cleanupIntervalMs ?? 6e4;
@@ -11792,35 +12306,35 @@ var DashboardSessionStore = class {
     const id = token.slice(0, dot);
     const signature = token.slice(dot + 1);
     const expected = this.sign(id);
-    const actualDigest = createHash3("sha256").update(signature).digest();
-    const expectedDigest = createHash3("sha256").update(expected).digest();
+    const actualDigest = createHash4("sha256").update(signature).digest();
+    const expectedDigest = createHash4("sha256").update(expected).digest();
     if (!timingSafeEqual3(actualDigest, expectedDigest)) return void 0;
     return id;
   }
   sign(id) {
-    return createHmac3("sha256", this.secret).update(id).digest("base64url");
+    return createHmac3("sha256", this.signingKey).update(id).digest("base64url");
   }
 };
 
 // src/dashboard/api.ts
-var optionalQueryString = z8.preprocess(
+var optionalQueryString = z9.preprocess(
   (value) => typeof value === "string" && value.length > 0 ? value : void 0,
-  z8.string().optional()
+  z9.string().optional()
 );
-var optionalQueryInt = z8.preprocess((value) => {
+var optionalQueryInt = z9.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;
-}, z8.number().int().optional());
-var queryBoolean = z8.preprocess(
+}, z9.number().int().optional());
+var queryBoolean = z9.preprocess(
   (value) => value === "true" ? true : value === "false" ? false : void 0,
-  z8.boolean().optional()
+  z9.boolean().optional()
 );
-var clampedQueryInt = (fallback, min, max) => z8.preprocess(
+var clampedQueryInt = (fallback, min, max) => z9.preprocess(
   (value) => clampInt(typeof value === "string" ? value : void 0, fallback, min, max),
-  z8.number().int()
+  z9.number().int()
 );
-var feedQuerySchema = z8.object({
+var feedQuerySchema = z9.object({
   limit: clampedQueryInt(50, 1, 200),
   offset: clampedQueryInt(0, 0, Number.MAX_SAFE_INTEGER),
   // The feed's server-side filters (issues #292, #316): attribution and
@@ -11830,8 +12344,8 @@ var feedQuerySchema = z8.object({
   upstream: optionalQueryString,
   session_source: optionalQueryString
 });
-var auditExportQuerySchema = z8.object({
-  format: z8.preprocess((value) => value === "csv" ? "csv" : "json", z8.enum(["json", "csv"])),
+var auditExportQuerySchema = z9.object({
+  format: z9.preprocess((value) => value === "csv" ? "csv" : "json", z9.enum(["json", "csv"])),
   limit: clampedQueryInt(EXPORT_MAX_RECORDS, 1, EXPORT_MAX_RECORDS),
   tool: optionalQueryString,
   decision: optionalQueryString,
@@ -11851,7 +12365,7 @@ var auditExportQuerySchema = z8.object({
   upstream: optionalQueryString,
   session_source: optionalQueryString
 });
-var auditQuerySchema = z8.object({
+var auditQuerySchema = z9.object({
   limit: clampedQueryInt(50, 1, LIST_MAX_PAGE_SIZE),
   offset: clampedQueryInt(0, 0, Number.MAX_SAFE_INTEGER),
   tool: optionalQueryString,
@@ -11873,21 +12387,21 @@ var auditQuerySchema = z8.object({
   upstream: optionalQueryString,
   session_source: optionalQueryString
 });
-var budgetEventsQuerySchema = z8.object({
+var budgetEventsQuerySchema = z9.object({
   limit: clampedQueryInt(50, 1, LIST_MAX_PAGE_SIZE),
   offset: clampedQueryInt(0, 0, Number.MAX_SAFE_INTEGER)
 });
-var budgetEventsExportQuerySchema = z8.object({
-  format: z8.preprocess((value) => value === "csv" ? "csv" : "json", z8.enum(["json", "csv"])),
+var budgetEventsExportQuerySchema = z9.object({
+  format: z9.preprocess((value) => value === "csv" ? "csv" : "json", z9.enum(["json", "csv"])),
   limit: clampedQueryInt(EXPORT_MAX_RECORDS, 1, EXPORT_MAX_RECORDS)
 });
-var analyticsQuerySchema = z8.object({
+var analyticsQuerySchema = z9.object({
   from: optionalQueryString,
   to: optionalQueryString,
   upstream: optionalQueryString
 });
-var authSessionBodySchema = z8.object({
-  secret: z8.string()
+var authSessionBodySchema = z9.object({
+  secret: z9.string()
 });
 var SESSION_COOKIE = "helio_session";
 var SESSION_TTL_MS = 8 * 60 * 60 * 1e3;
@@ -11960,7 +12474,10 @@ function createDashboardAppWithLifecycle(deps, options) {
     budgets
   } = deps;
   const apiSecret = options?.apiSecret;
-  const sessionStore = apiSecret ? new DashboardSessionStore({ secret: apiSecret, ttlMs: SESSION_TTL_MS }) : void 0;
+  const sessionStore = apiSecret ? new DashboardSessionStore({
+    signingKey: randomBytes2(32).toString("hex"),
+    ttlMs: SESSION_TTL_MS
+  }) : void 0;
   const app = new Hono8();
   app.onError((err, c) => {
     if (err instanceof HTTPException2) return err.getResponse();
@@ -12366,7 +12883,8 @@ var EVENT_TYPES = [
   "limit_warning",
   "approval_notification_failed",
   "budget_update",
-  "budget_breached"
+  "budget_breached",
+  "policy_reload"
 ];
 var DashboardEventBus = class {
   emitter = new EventEmitter();
@@ -12435,6 +12953,10 @@ function actionEventFromRecord(record, id) {
     upstream: record.upstream
   };
 }
+function policyReloadEventFromRecord(record, id) {
+  const evidence = readPolicyReloadEvidence(record);
+  return evidence === null ? null : { ...evidence, id, at: record.timestamp };
+}
 function approvalRequestedEvent(ticket) {
   return {
     ticket_id: ticket.id,
@@ -12458,6 +12980,10 @@ function dashboardEventCallbacks(bus) {
   return {
     onPersist: (record, id) => {
       bus.emit("action", actionEventFromRecord(record, id));
+      if (record.record_kind === "policy_reload") {
+        const event = policyReloadEventFromRecord(record, id);
+        if (event !== null) bus.emit("policy_reload", event);
+      }
     },
     onApprovalSubmit: (ticket) => {
       bus.emit("approval_requested", approvalRequestedEvent(ticket));
@@ -12475,6 +13001,7 @@ function dashboardEventCallbacks(bus) {
 }
 
 // src/startup-warnings.ts
+import { accessSync, constants } from "fs";
 function isLoopbackHost2(host) {
   return host === "127.0.0.1" || host === "localhost" || host === "::1";
 }
@@ -12543,6 +13070,17 @@ function warnIfDashboardOpenMode(config, log = console.error) {
   );
   return true;
 }
+function warnIfDashboardSecretLiteral(config, source, log = console.error) {
+  const secret = config.dashboard.api_secret;
+  if (!config.dashboard.enabled) return false;
+  if (typeof secret !== "string" || secret.length === 0) return false;
+  if (isSecretDigest(secret)) return false;
+  if (source.interpolatedPaths.includes("dashboard.api_secret")) return false;
+  log(
+    `[helio] Warning: dashboard.api_secret is stored as plaintext in ${source.configPath}. Anyone who can read this file holds the operator credential and can approve tickets. Run \`helio secret\`, store the printed digest as dashboard.api_secret, and restart.`
+  );
+  return true;
+}
 function warnIfNoEnforcement(policy, log = console.error) {
   if (policy.rules.length > 0 || policy.defaultAction !== "allow" || policy.dryRun) return false;
   log(
@@ -12550,6 +13088,23 @@ function warnIfNoEnforcement(policy, log = console.error) {
   );
   return true;
 }
+function defaultIsWritable(path) {
+  try {
+    accessSync(path, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function warnIfConfigWritableByProxyUser(input, log = console.error) {
+  const isWritable = input.isWritable ?? defaultIsWritable;
+  if (!isWritable(input.configPath)) return false;
+  const exposure = input.pinned ? "Reloads are pinned, so a changed file is refused, but a restart by this user can still drop the pin. Run the proxy as its own user to move up a tier" : input.hotReload ? "Any same-user process, including your agent, can change policy live. Run the proxy as its own user, or set HELIO_CONFIG_SHA256, to move up a tier" : "Hot reload is off, so the next restart loads whatever is in the file. Run the proxy as its own user, or set HELIO_CONFIG_SHA256, to move up a tier";
+  log(
+    `[helio] Enforcement posture: ${input.configPath} is writable by this user. ${exposure} (SECURITY.md, Process and filesystem boundaries).`
+  );
+  return true;
+}
 
 // src/shutdown.ts
 async function closeResources(resources) {
@@ -12628,7 +13183,7 @@ function getBundledDashboardDistPath() {
   const assetsSubdirPath = resolve(assetsDir, "assets");
   return existsSync(indexPath) && existsSync(assetsSubdirPath) ? assetsDir : null;
 }
-function renderConfigTemplate(apiSecret) {
+function renderConfigTemplate(apiSecretDigest) {
   return `# Helio MCP Governance Proxy configuration
 # Docs: https://github.com/gethelio/helio
 
@@ -12693,17 +13248,19 @@ upstream:
 #   retention: 90d
 #   include_responses: true
 
-# Operator dashboard + approval REST API. Bound to 127.0.0.1 by default \u2014 do
+# Operator dashboard + approval REST API. Bound to 127.0.0.1 by default. Do
 # not change to 0.0.0.0 without putting an authenticating reverse proxy in
-# front. dashboard.api_secret is the manual dashboard login secret and also
-# supports machine Bearer auth for sideband API clients. Store it safely; it
-# stays valid until you rotate it. Rotate by editing this file and restarting
-# the proxy. Rotation invalidates active dashboard sessions.
+# front. dashboard.api_secret holds the SHA-256 digest of the dashboard
+# secret, never the secret itself: log in to the dashboard and authenticate
+# sideband API clients with the secret that \`helio init\` printed once. To
+# rotate, run \`helio secret\`, paste the new digest here, and restart the
+# proxy; active dashboard sessions are invalidated. A plaintext value is
+# still accepted.
 dashboard:
   enabled: true
   port: 3100
   host: 127.0.0.1
-  api_secret: "${apiSecret}"
+  api_secret: "${apiSecretDigest}"
 
 # sdk:
 #   enabled: false
@@ -12744,8 +13301,13 @@ async function governUpstream(options) {
 }
 async function startCommand(configPath, options) {
   let config;
+  let interpolatedPaths = [];
+  let configSha256 = "";
   try {
-    config = await loadConfig(configPath);
+    const loaded = await loadConfigWithMeta(configPath);
+    config = loaded.config;
+    interpolatedPaths = loaded.interpolatedPaths;
+    configSha256 = loaded.sha256;
   } catch (err) {
     if (err instanceof ConfigError) {
       console.error(`Error: ${err.message}`);
@@ -12754,6 +13316,20 @@ async function startCommand(configPath, options) {
     }
     throw err;
   }
+  const configPin = readConfigPin();
+  if (configPin.status === "invalid") {
+    console.error(
+      `Error: HELIO_CONFIG_SHA256 is set but is not a SHA-256 hex digest (64 hex characters, with or without a sha256: prefix): "${configPin.raw.slice(0, 80)}"`
+    );
+    process.exit(1);
+  }
+  if (configPin.status === "set" && configPin.sha256 !== configSha256) {
+    console.error(
+      `Error: HELIO_CONFIG_SHA256 does not match ${configPath}: pinned sha256:${configPin.sha256}, file sha256:${configSha256}. Review the change and re-pin it with helio config hash.`
+    );
+    process.exit(1);
+  }
+  const pinnedSha256 = configPin.status === "set" ? configPin.sha256 : void 0;
   const bundledDashboardDistPath = config.dashboard.enabled ? getBundledDashboardDistPath() : null;
   if (config.dashboard.enabled && !bundledDashboardDistPath) {
     console.error(
@@ -12804,7 +13380,10 @@ async function startCommand(configPath, options) {
   auditStore.runRetentionSweep();
   const auditWriter = new AuditWriter({
     store: auditStore,
-    onPersist: cbs.onPersist
+    onPersist: cbs.onPersist,
+    // Seed the config hash at construction so no record is written unstamped
+    // between here and the first reload; the reload path replaces it.
+    configSha256
   });
   registerCrashDrainHook(() => {
     try {
@@ -12913,7 +13492,7 @@ async function startCommand(configPath, options) {
   if (config.sdk.enabled) {
     sidebandToken = process.env["HELIO_SDK_TOKEN"];
     if (!sidebandToken || sidebandToken.length === 0) {
-      sidebandToken = randomBytes2(32).toString("hex");
+      sidebandToken = randomBytes3(32).toString("hex");
       process.env["HELIO_SDK_TOKEN"] = sidebandToken;
       sidebandTokenSource = "generated";
     } else {
@@ -12921,7 +13500,7 @@ async function startCommand(configPath, options) {
     }
     adapterToken = process.env["HELIO_ADAPTER_TOKEN"];
     if (!adapterToken || adapterToken.length === 0) {
-      adapterToken = randomBytes2(32).toString("hex");
+      adapterToken = randomBytes3(32).toString("hex");
       process.env["HELIO_ADAPTER_TOKEN"] = adapterToken;
       adapterTokenSource = "generated";
     } else {
@@ -13028,6 +13607,7 @@ async function startCommand(configPath, options) {
   warnIfWebhookChannelUnreachable(config);
   warnIfSdkSidebandExposed(config);
   warnIfDashboardOpenMode(config);
+  warnIfDashboardSecretLiteral(config, { configPath, interpolatedPaths });
   warnIfBudgetWindowExceedsRetention(config);
   const channelCount = config.approval.channels.length;
   console.error(
@@ -13043,29 +13623,46 @@ async function startCommand(configPath, options) {
     console.error(`Dry-run: ENABLED (no requests will be forwarded to upstream)`);
   }
   console.error(`Config: ${configPath}`);
+  if (pinnedSha256 !== void 0) {
+    console.error(
+      `[helio] Config pinned to sha256:${pinnedSha256.slice(0, 12)}: reloads with a different hash will be refused`
+    );
+  }
   const hotReloadEnabled = options.noHotReload === true ? false : config.policies.hot_reload ?? true;
   let configWatcher;
   if (hotReloadEnabled) {
     configWatcher = new ConfigWatcher({
       configPath,
-      initialConfig: config,
+      initial: { config, sha256: configSha256 },
+      pinnedSha256,
       onReady: () => {
         console.error(`Watching ${configPath} for policy changes`);
       },
-      onReload: (newPolicy, reloadWarnings, restartRequiredPaths, newBudgets) => {
+      onReload: (newPolicy, reloadWarnings, restartRequiredPaths, newBudgets, facts) => {
         const unroutable = findUnroutableApprovalReferences(newPolicy, newBudgets, {
           channelTypes: runtimeChannelTypes,
           dashboardEnabled: config.dashboard.enabled,
           defaultApprovalTimeoutMs: parseDuration(config.approval.timeout)
         });
         if (unroutable.length > 0) {
-          throw new Error(
+          throw new PolicyReloadRejectedError(
+            "rejected_unroutable",
             `approval routing is not available in the running process (restart required to apply approval.channels/dashboard changes): ${unroutable.join("; ")}`
           );
         }
-        budgetEngine.reconcile(newBudgets);
+        try {
+          budgetEngine.reconcile(newBudgets);
+        } catch (err) {
+          throw new PolicyReloadRejectedError(
+            "rejected_budget_flush",
+            `budget epoch flush failed: ${err instanceof Error ? err.message : String(err)}`,
+            { cause: err }
+          );
+        }
+        auditWriter.setConfigSha256(facts.sha256After);
         applyReloadedPolicy(stacks, newPolicy);
         governanceService?.updatePolicy(newPolicy);
+        auditWriter.pushImmediate(buildPolicyReloadRecord(facts, config.environment ?? null));
         const budgetTotal = newBudgets.length;
         console.error(
           `[helio] Budgets reloaded: ${String(budgetTotal)} budget${budgetTotal !== 1 ? "s" : ""}`
@@ -13088,13 +13685,20 @@ async function startCommand(configPath, options) {
           );
         }
       },
-      onError: (error) => {
-        console.error(
-          `[helio] Config reload failed (keeping current configuration): ${error.message}`
-        );
-        if (error instanceof ConfigError) {
-          printConfigErrorDetails(error, "[helio] ");
+      onError: (error, facts) => {
+        if (facts.outcome === "watch_failed") {
+          console.error(
+            `[helio] Config watch failed (keeping current configuration; edits will not be observed until restart): ${error.message}`
+          );
+        } else {
+          console.error(
+            `[helio] Config reload failed (keeping current configuration): ${error.message}`
+          );
+          if (error instanceof ConfigError) {
+            printConfigErrorDetails(error, "[helio] ");
+          }
         }
+        auditWriter.pushImmediate(buildPolicyReloadRecord(facts, config.environment ?? null));
       }
     });
     configWatcher.start();
@@ -13103,6 +13707,11 @@ async function startCommand(configPath, options) {
       `[helio] Hot-reload disabled \u2014 config changes to ${configPath} will require a restart`
     );
   }
+  warnIfConfigWritableByProxyUser({
+    configPath,
+    hotReload: hotReloadEnabled,
+    pinned: pinnedSha256 !== void 0
+  });
   registerShutdown(
     handle,
     stacks.map((stack) => stack.annotationPrime),
@@ -13127,15 +13736,62 @@ async function initCommand(outputPath, force) {
     console.error(`Error: ${outputPath} already exists. Use --force to overwrite.`);
     process.exit(1);
   }
-  const apiSecret = randomBytes2(32).toString("hex");
-  await writeFile(outputPath, renderConfigTemplate(apiSecret), "utf-8");
+  const secret = randomBytes3(32).toString("hex");
+  await writeFile(outputPath, renderConfigTemplate(secretDigest(secret)), "utf-8");
   console.error(`Created ${outputPath}`);
   console.error("");
-  console.error("Generated dashboard.api_secret (also stored in the file above):");
-  console.error(`  ${apiSecret}`);
+  console.error("Dashboard secret (shown once; the file stores only its SHA-256 digest):");
+  console.error(`  ${secret}`);
   console.error("");
-  console.error("Use this as the dashboard login secret (and optional Bearer credential");
-  console.error("for sideband API clients at default 127.0.0.1:3100). Rotate in-file.");
+  console.error("Store it in your password manager. Use it to log in to the dashboard and");
+  console.error("as the Bearer credential for sideband API clients (127.0.0.1:3100 by");
+  console.error("default). If you lose it, run `helio secret`, paste the new digest into");
+  console.error("dashboard.api_secret, and restart the proxy.");
+}
+async function sandboxCommand(dir, force) {
+  const root = resolve(dir);
+  const targets = SANDBOX_FILES.map((rel) => join2(root, rel));
+  const existing = targets.find((path) => existsSync(path));
+  if (existing !== void 0 && !force) {
+    console.error(`Error: ${existing} already exists. Use --force to overwrite.`);
+    process.exit(1);
+  }
+  await mkdir(join2(root, "helio"), { recursive: true });
+  const contents = {
+    "compose.yaml": renderSandboxCompose({ imageTag: sandboxImageTag(VERSION) }),
+    "helio/helio.yaml": renderSandboxConfig(),
+    "helio/README.md": renderSandboxReadme()
+  };
+  for (const rel of SANDBOX_FILES) await writeFile(join2(root, rel), contents[rel], "utf-8");
+  for (const path of targets) console.error(`Created ${path}`);
+  console.error("");
+  console.error("Next steps:");
+  console.error("  1. In compose.yaml, set the agent image (or build:) and the mcp-server image.");
+  console.error(
+    "  2. Run `helio secret` and put HELIO_DASHBOARD_SECRET=<digest> in ./.env next to compose.yaml."
+  );
+  console.error(`  3. cd ${dir} && docker compose up -d`);
+  console.error("  4. docker compose exec agent sh, then run the checks in helio/README.md.");
+  console.error(
+    "Never mount this directory, ./helio, .env, or the Docker socket into the agent service."
+  );
+}
+function secretCommand() {
+  const secret = randomBytes3(32).toString("hex");
+  console.log(`secret: ${secret}`);
+  console.log(`digest: ${secretDigest(secret)}`);
+}
+async function configHashCommand(configPath) {
+  try {
+    const source = await readConfigSource(configPath);
+    console.log(source.sha256);
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
 }
 async function validateCommand(configPath) {
   try {
@@ -13319,7 +13975,24 @@ program.command("start").description("Load config and start the proxy server").o
     }
   )
 );
-program.command("init").description("Scaffold a helio.yaml config file with commented defaults").option("-o, --output <path>", "Output file path", DEFAULT_CONFIG_PATH).option("-f, --force", "Overwrite existing file", false).action((opts) => initCommand(opts.output, opts.force));
+program.command("init").description("Scaffold a helio.yaml config file with commented defaults").option("-o, --output <path>", "Output file path", DEFAULT_CONFIG_PATH).option("-f, --force", "Overwrite existing file", false).option(
+  "--sandbox [dir]",
+  `Write the sidecar layout (compose.yaml, helio/helio.yaml, helio/README.md) into <dir> (default: ${SANDBOX_DEFAULT_DIR}) instead of a helio.yaml`
+).action((opts, command) => {
+  if (opts.sandbox === void 0) return initCommand(opts.output, opts.force);
+  if (command.getOptionValueSource("output") === "cli") {
+    console.error(
+      "Error: --output does not apply to --sandbox; pass the directory as --sandbox <dir>."
+    );
+    process.exit(1);
+  }
+  return sandboxCommand(opts.sandbox === true ? SANDBOX_DEFAULT_DIR : opts.sandbox, opts.force);
+});
 program.command("validate").description("Validate a helio.yaml config file").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).action((opts) => validateCommand(opts.config));
+program.command("secret").description("Generate a dashboard secret and the digest to store as dashboard.api_secret").action(() => {
+  secretCommand();
+});
 program.command("export").description("Export audit records or a budget ledger to JSON or CSV").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).option("-f, --format <format>", "Output format: json or csv", "json").option("--budgets <name>", "Export the named budget ledger instead of the audit trail").option("--tool <name>", "Filter by tool name").option("--decision <decision>", "Filter by policy decision").option("--reason <reason>", "Filter by block reason").option("--session <id>", "Filter by session ID").option("--upstream <name>", "Filter by upstream name").option("--from <iso>", "Start time (ISO 8601)").option("--to <iso>", "End time (ISO 8601)").option("--limit <n>", "Max records to export (up to 10000)", "1000").action((opts) => exportCommand(opts));
+var configCommand = program.command("config").description("Inspect a helio.yaml config file");
+configCommand.command("hash").description("Print the SHA-256 of the config file bytes, the value HELIO_CONFIG_SHA256 pins").option("-c, --config <path>", "Path to helio.yaml", DEFAULT_CONFIG_PATH).action((opts) => configHashCommand(opts.config));
 program.parse();