@gethelio/proxy 0.13.1 → 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 randomBytes3 } from "crypto";
-import { dirname, resolve } from "path";
+import { dirname, join as join2, resolve } from "path";
 import { fileURLToPath } from "url";
 
 // src/version.ts
@@ -995,7 +995,7 @@ function interpolateTracked(value, env, path, out) {
   }
   return value;
 }
-async function loadConfigWithMeta(filePath, env) {
+async function readConfigSource(filePath) {
   let bytes;
   try {
     bytes = await readFile(filePath);
@@ -1003,10 +1003,12 @@ async function loadConfigWithMeta(filePath, env) {
     throw new ConfigError(`Cannot read config file: ${filePath}`);
   }
   const sha256 = createHash("sha256").update(bytes).digest("hex");
-  const raw = bytes.toString("utf-8");
+  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}`);
@@ -1024,12 +1026,43 @@ async function loadConfigWithMeta(filePath, env) {
       details
     );
   }
-  return { config: result.data, sha256, interpolatedPaths };
+  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
 import { watch } from "chokidar";
 
@@ -1458,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() {
@@ -1486,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() {
@@ -1513,18 +1601,55 @@ 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
+      });
     }
   }
 };
@@ -1549,6 +1674,247 @@ function verifyBearer(authHeader, expected) {
   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";
@@ -7169,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 = `
@@ -7202,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 = `
@@ -7215,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 (
@@ -7224,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,
@@ -7232,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 = [
@@ -7252,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 {
@@ -7288,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
   };
 }
@@ -7368,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;
@@ -7412,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);
@@ -7524,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;
@@ -7611,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}
@@ -7696,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;
@@ -7705,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(() => {
@@ -7725,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) {
@@ -7741,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.
    */
@@ -7842,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;
@@ -8136,70 +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";
+import { z as z6 } from "zod";
 
 // src/sideband/governance-api.ts
 import { Hono as Hono4 } from "hono";
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 import { createHash as createHash3 } 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({
+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) {
@@ -8314,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();
@@ -10392,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;
@@ -10458,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 {
@@ -10593,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",
@@ -10616,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) {
@@ -11651,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) {
@@ -11726,7 +12219,7 @@ import { join } from "path";
 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";
@@ -11824,24 +12317,24 @@ var DashboardSessionStore = class {
 };
 
 // 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
@@ -11851,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,
@@ -11872,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,
@@ -11894,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;
@@ -12390,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();
@@ -12459,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,
@@ -12482,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));
@@ -12499,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";
 }
@@ -12585,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) {
@@ -12782,10 +13302,12 @@ async function governUpstream(options) {
 async function startCommand(configPath, options) {
   let config;
   let interpolatedPaths = [];
+  let configSha256 = "";
   try {
     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}`);
@@ -12794,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(
@@ -12844,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 {
@@ -13084,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" : ""}`
@@ -13129,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();
@@ -13144,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),
@@ -13180,11 +13748,51 @@ async function initCommand(outputPath, force) {
   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 {
     const config = await loadConfig(configPath);
@@ -13367,10 +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();