@intentius/behold 0.20.0 → 0.22.0

package/dist/cli.js

@@ -118,17 +118,17 @@ var init_read_scheduler = __esm({
             recordRefused();
             return Promise.reject(new Error("Chant read queue is full; retry after current reads finish"));
           }
-          let resolve18;
+          let resolve19;
           let reject;
           const promise = new Promise((yes, no) => {
-            resolve18 = yes;
+            resolve19 = yes;
             reject = no;
           });
           job = {
             key,
             run: run3,
             promise,
-            resolve: resolve18,
+            resolve: resolve19,
             reject,
             controller: new AbortController(),
             users: 0,
@@ -142,7 +142,7 @@ var init_read_scheduler = __esm({
         }
         const shared2 = job;
         shared2.users++;
-        const result = new Promise((resolve18, reject) => {
+        const result = new Promise((resolve19, reject) => {
           let done = false;
           const finish = (error, value, failed = false) => {
             if (done) return;
@@ -150,7 +150,7 @@ var init_read_scheduler = __esm({
             signal?.removeEventListener("abort", abort);
             shared2.users--;
             if (failed) reject(error);
-            else resolve18(value);
+            else resolve19(value);
           };
           const abort = () => {
             finish(signal?.reason, void 0, true);
@@ -1038,11 +1038,11 @@ async function createK8sClient(options = {}) {
     }
     return void 0;
   }
-  async function resolve18(selector, signal) {
+  async function resolve19(selector, signal) {
     return "apiVersion" in selector ? resolveByGvk(selector.apiVersion, selector.kind, signal) : resolveByResourceString(selector.resource, selector.group, signal);
   }
   async function resolveOrThrow(selector, signal) {
-    const info = await resolve18(selector, signal);
+    const info = await resolve19(selector, signal);
     if (!info) throw new UnknownResourceError(selectorText(selector));
     return info;
   }
@@ -1054,7 +1054,7 @@ async function createK8sClient(options = {}) {
     return parts.join("/");
   }
   async function pathFor(ref, signal) {
-    const info = await resolve18({ apiVersion: ref.apiVersion, kind: ref.kind }, signal);
+    const info = await resolve19({ apiVersion: ref.apiVersion, kind: ref.kind }, signal);
     if (!info) return void 0;
     return objectPath(info, ref.name, ref.namespace);
   }
@@ -1168,8 +1168,8 @@ async function createK8sClient(options = {}) {
           const { lines } = await openStream(listPath, query, controller.signal, target);
           let expired = false;
           const iterator = lines[Symbol.asyncIterator]();
-          const stopped = new Promise((resolve19) => {
-            const finish = () => resolve19({ done: true, value: void 0 });
+          const stopped = new Promise((resolve20) => {
+            const finish = () => resolve20({ done: true, value: void 0 });
             if (controller.signal.aborted) finish();
             else controller.signal.addEventListener("abort", finish, { once: true });
           });
@@ -1196,11 +1196,11 @@ async function createK8sClient(options = {}) {
             resourceVersion = await listResourceVersion();
             continue;
           }
-          await new Promise((resolve19) => {
-            const timer = setTimeout(resolve19, reopenDelayMs);
+          await new Promise((resolve20) => {
+            const timer = setTimeout(resolve20, reopenDelayMs);
             controller.signal.addEventListener("abort", () => {
               clearTimeout(timer);
-              resolve19(void 0);
+              resolve20(void 0);
             }, { once: true });
           });
         }
@@ -1318,7 +1318,7 @@ async function createK8sClient(options = {}) {
   return {
     provenance,
     defaultNamespace,
-    resolve: resolve18,
+    resolve: resolve19,
     read,
     pathFor,
     readIfPresent,
@@ -4384,7 +4384,7 @@ var init_chant = __esm({
 });
 
 // src/cli.ts
-import { resolve as resolve17, dirname as dirname10, join as join29 } from "node:path";
+import { resolve as resolve18, dirname as dirname10, join as join29 } from "node:path";
 import { realpathSync as realpathSync2, existsSync as existsSync21, readFileSync as readFileSync22, rmSync as rmSync4 } from "node:fs";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
 import { spawn as spawn7, spawnSync as spawnSync3 } from "node:child_process";
@@ -4444,7 +4444,7 @@ import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { execFile as execFile3 } from "node:child_process";
 import { promisify as promisify3 } from "node:util";
 import { existsSync as existsSync18, readFileSync as readFileSync19 } from "node:fs";
-import { basename as basename3, dirname as dirname7, join as join26, relative as relative8, resolve as resolve15, sep as sep7 } from "node:path";
+import { basename as basename3, dirname as dirname7, join as join26, relative as relative8, resolve as resolve16, sep as sep7 } from "node:path";
 
 // src/recents.ts
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
@@ -4686,19 +4686,19 @@ function finishPipelineProgress(state, exitCode) {
 }
 
 // src/gh-run.ts
-var defaultGhExec = (args) => new Promise((resolve18) => {
+var defaultGhExec = (args) => new Promise((resolve19) => {
   let out = "";
   let proc;
   try {
     proc = spawn3("gh", args, { stdio: ["ignore", "pipe", "pipe"] });
   } catch {
-    resolve18({ code: 127, out: "" });
+    resolve19({ code: 127, out: "" });
     return;
   }
   proc.stdout.on("data", (d) => out += d);
   proc.stderr.on("data", (d) => out += d);
-  proc.on("error", () => resolve18({ code: 127, out }));
-  proc.on("close", (code) => resolve18({ code: code ?? 1, out }));
+  proc.on("error", () => resolve19({ code: 127, out }));
+  proc.on("close", (code) => resolve19({ code: code ?? 1, out }));
 });
 async function ghReady(exec = defaultGhExec) {
   const { code, out } = await exec(["auth", "status"]);
@@ -6600,14 +6600,30 @@ function forMember(dir, opts) {
 }
 var memberSource = (dir, opts) => memberIr(dir, forMember(dir, opts), memberViaFor(dir));
 var memberLive = (dir, opts, fresh) => overlayIr(dir, forMember(dir, opts), memberViaFor(dir), fresh);
+async function memberSourceOrBox(dir, opts) {
+  try {
+    return joinCarvedSources(await memberSource(dir, opts), (await carveStatesFor(dir)).values(), dir).ir;
+  } catch (err) {
+    const box = declaredMemberBox(dir, err);
+    if (!box) throw err;
+    return box;
+  }
+}
+function declaredMemberBox(dir, err) {
+  const m = servedWorkspace() ? workspaceMemberOf(dir) : void 0;
+  if (!m) return void 0;
+  const said4 = (e) => {
+    const msg = e instanceof Error ? e.message : String(e);
+    return (msg.match(/exited \d+:\s*([\s\S]*)/)?.[1] ?? msg).trim().slice(0, 600);
+  };
+  const reason = err instanceof WorkspaceMemberError ? err.reason : { code: "command-failed", message: said4(err) };
+  return unreadableMemberIr({ ...m, reason: { ...reason, message: reason.message.replace(/\u001b\[[0-9;]*m/g, "") } });
+}
 async function composeEstate(projectDirs, opts = {}) {
   const names = estateMemberNames(projectDirs);
   const stacks = await mapPool(projectDirs, estateReadPool(projectDirs.length), async (dir, i) => ({
     name: names[i],
-    // chant#2040: the manifests a member holds name the files its carved
-    // entities were emitted into — joined here, where the member's root is
-    // known, onto a COPY (the member IR is the #312 cache's own object).
-    ir: joinCarvedSources(await memberSource(dir, opts), (await carveStatesFor(dir)).values(), dir).ir
+    ir: await memberSourceOrBox(dir, opts)
   }));
   return composeStacks([...stacks, ...unreadableStacks(projectDirs)]);
 }
@@ -6615,8 +6631,8 @@ async function composeEstatePending(projectDirs, opts = {}) {
   const names = estateMemberNames(projectDirs);
   const { env: _env, live: _live, overlay: _overlay, ...srcOpts } = opts;
   const stacks = await mapPool(projectDirs, estateReadPool(projectDirs.length), async (dir, i) => {
-    const ir = joinCarvedSources(await memberSource(dir, srcOpts), (await carveStatesFor(dir)).values(), dir).ir;
-    for (const n of ir.nodes) n.attrs = { ...n.attrs, _pendingRead: true };
+    const ir = await memberSourceOrBox(dir, srcOpts);
+    for (const n of ir.nodes) if (n.kind !== "UnreadableMember") n.attrs = { ...n.attrs, _pendingRead: true };
     return { name: names[i], ir };
   });
   return composeStacks([...stacks, ...unreadableStacks(projectDirs)]);
@@ -6757,7 +6773,11 @@ async function composeEstateOverlay(projectDirs, opts, classify, observe = {}) {
         observe.onMember?.({ name, dir, ir: src, unobserved: reason });
         unobserved.push({ name, reason });
       } catch (err2) {
-        dropped.push({ name, reason: firstLine2(err2) });
+        const box = declaredMemberBox(dir, err2);
+        if (box) {
+          stacks[i] = { name, ir: box };
+          observe.onMember?.({ name, dir, ir: box });
+        } else dropped.push({ name, reason: firstLine2(err2) });
       }
     }
   });
@@ -11502,19 +11522,19 @@ import { join as join20 } from "node:path";
 import { platform } from "node:os";
 var DOCKER_DOWN_DETAIL = "docker is down";
 function probe(cmd, args) {
-  return new Promise((resolve18) => {
+  return new Promise((resolve19) => {
     let out = "";
     let proc;
     try {
       proc = spawn5(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     } catch {
-      resolve18({ code: 127, out: "" });
+      resolve19({ code: 127, out: "" });
       return;
     }
     proc.stdout.on("data", (d) => out += d);
     proc.stderr.on("data", (d) => out += d);
-    proc.on("error", () => resolve18({ code: 127, out }));
-    proc.on("close", (code) => resolve18({ code: code ?? 1, out }));
+    proc.on("error", () => resolve19({ code: 127, out }));
+    proc.on("close", (code) => resolve19({ code: code ?? 1, out }));
   });
 }
 async function dockerAvailable(run3) {
@@ -12611,6 +12631,142 @@ async function moveReceipt(plan, members, run3 = captureChoudoufu) {
   };
 }
 
+// src/workspace-gates.ts
+init_chant();
+import { resolve as resolve13 } from "node:path";
+var isRecord11 = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+var str7 = (v) => typeof v === "string" && v ? v : null;
+function gateKey(member, op, gate) {
+  return `${member}/${op}/${gate}`;
+}
+function approveArgs(g) {
+  return ["approve", g.op, g.gate, ...g.env ? ["--env", g.env] : [], ...g.planDigest ? ["--plan", g.planDigest] : []];
+}
+function parseWorkspaceStatus(text, root) {
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    return { ok: false, refusal: { error: "chant workspace status printed something that is not JSON.", code: "workspace-status", remedy: "Run `chant workspace status <env> --json` in the workspace root to see what it says." } };
+  }
+  if (!isRecord11(doc)) return { ok: false, refusal: { error: "chant workspace status printed JSON that is not an object.", code: "workspace-status", remedy: "Run `chant workspace status <env> --json` in the workspace root." } };
+  const contract = contractRefusal(doc, "status");
+  if (contract) return { ok: false, refusal: contract };
+  if (isRecord11(doc.error)) {
+    const code = String(doc.error.code ?? "unknown");
+    return { ok: false, refusal: { error: `chant could not read the workspace's status: ${code}: ${String(doc.error.message ?? "")}`, code, remedy: "`chant workspace check` names the problem and where it is." } };
+  }
+  const gates = [];
+  for (const m of Array.isArray(doc.members) ? doc.members : []) {
+    if (!isRecord11(m) || typeof m.name !== "string") continue;
+    const dir = typeof m.dir === "string" ? m.dir === "." ? resolve13(root) : resolve13(root, m.dir) : resolve13(root);
+    for (const g of Array.isArray(m.gates) ? m.gates : []) {
+      if (!isRecord11(g)) continue;
+      if (g.state !== void 0 && g.state !== "pending") continue;
+      const op = str7(g.component);
+      const gate = str7(g.name);
+      if (!op || !gate) continue;
+      const env = str7(g.env);
+      const planDigest = str7(g.planDigest);
+      const approvals = (Array.isArray(g.approvals) ? g.approvals : []).filter(isRecord11).map((a) => ({
+        principal: String(a.principal ?? "unknown"),
+        at: str7(a.at),
+        channel: str7(a.channel)
+      }));
+      gates.push({
+        key: gateKey(m.name, op, gate),
+        member: m.name,
+        dir,
+        op,
+        gate,
+        env,
+        planDigest,
+        approvals,
+        needed: typeof g.needed === "number" ? g.needed : 1,
+        recordedAt: str7(g.recordedAt),
+        expiresAt: str7(g.expiresAt),
+        signed: isRecord11(g.signed),
+        // status's line already carries --sign for a signed gate; only the
+        // line built here needs it added.
+        approve: str7(g.approve) ?? ["chant", ...approveArgs({ op, gate, env, planDigest }), ...isRecord11(g.signed) ? ["--sign"] : []].join(" ")
+      });
+    }
+  }
+  return { ok: true, env: String(doc.env ?? ""), gates };
+}
+async function readWorkspaceGates(ws, env) {
+  const run3 = await runChantRaw(["workspace", "status", env, "--json"], ws.root);
+  if (!run3.stdout.trim()) {
+    return {
+      ok: false,
+      refusal: {
+        error: `chant workspace status ${env} failed in ${ws.root} (exit ${run3.code}): ${run3.stderr.trim().split("\n").slice(-3).join(" ")}`,
+        code: "workspace-status",
+        remedy: "Run `chant workspace status <env>` in the workspace root."
+      }
+    };
+  }
+  return parseWorkspaceStatus(run3.stdout, ws.root);
+}
+function isEnvName(env) {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(env);
+}
+function localApprover(env = process.env) {
+  return env.GITHUB_ACTOR ?? env.GITLAB_USER_LOGIN ?? env.USER ?? "unknown";
+}
+
+// src/request-guard.ts
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+var SAFE = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+function hostName(hostport) {
+  const h = hostport.trim().toLowerCase();
+  if (h.startsWith("[")) {
+    const end = h.indexOf("]");
+    return end >= 0 ? h.slice(0, end + 1) : h;
+  }
+  const colon = h.lastIndexOf(":");
+  return colon >= 0 && h.indexOf(":") === colon ? h.slice(0, colon) : h;
+}
+function isLoopbackName(name) {
+  return LOOPBACK.has(name) || name.endsWith(".localhost");
+}
+function allowedName(name, cfg) {
+  if (isLoopbackName(name)) return true;
+  if (cfg.boundHost && !isWildcard(cfg.boundHost) && hostName(cfg.boundHost) === name) return true;
+  return cfg.allowedHosts.some((h) => hostName(h) === name);
+}
+function isWildcard(h) {
+  return h === "0.0.0.0" || h === "::" || h === "[::]";
+}
+function guardRequest(req, cfg) {
+  const name = hostName(req.host);
+  if (!allowedName(name, cfg)) {
+    return { ok: false, status: 421, error: `behold doesn't answer to host ${name}. Start it with --allow-host ${name} if a proxy of yours sends that name.` };
+  }
+  if (SAFE.has(req.method.toUpperCase())) return { ok: true };
+  if ((req.secFetchSite || "").toLowerCase() === "cross-site") {
+    return { ok: false, status: 403, error: "a cross-site page can't write to behold" };
+  }
+  if (req.origin && req.origin !== "null") {
+    let originHost;
+    try {
+      originHost = new URL(req.origin).host.toLowerCase();
+    } catch {
+      return { ok: false, status: 403, error: "a write with an unreadable Origin is refused" };
+    }
+    const same2 = originHost === req.host.trim().toLowerCase();
+    if (!same2 && !cfg.allowedHosts.some((h) => hostName(h) === hostName(originHost))) {
+      return { ok: false, status: 403, error: `a page from ${originHost} can't write to behold` };
+    }
+  } else if (req.origin === "null") {
+    return { ok: false, status: 403, error: "a write from an opaque origin is refused" };
+  }
+  return { ok: true };
+}
+function allowedHostsFrom(flag = [], env = process.env.BEHOLD_ALLOWED_HOSTS) {
+  return [...flag, ...(env || "").split(",")].map((s) => s.trim()).filter(Boolean);
+}
+
 // src/server.ts
 init_member_kind();
 init_terraform_member();
@@ -12620,7 +12776,7 @@ init_chant();
 init_member_kind();
 init_choudoufu_member();
 init_project();
-import { relative as relative6, resolve as resolve13 } from "node:path";
+import { relative as relative6, resolve as resolve14 } from "node:path";
 init_terraform_member();
 init_targets();
 var list2 = (xs) => xs.join(", ");
@@ -12870,7 +13026,7 @@ function workspaceCheck(ws, beholdMembers) {
   return { name: "project", status: warn ? "warn" : "pass", detail: parts.join("; "), ...warn ? { fix } : {} };
 }
 async function diagnose(dir, probes = {}) {
-  const root = resolve13(dir);
+  const root = resolve14(dir);
   const behold = beholdVersion();
   const listing = hasDeclaration(root) ? await (probes.readWorkspace ?? readWorkspace)(root) : void 0;
   if (listing && !listing.ok) {
@@ -12909,7 +13065,7 @@ async function diagnose(dir, probes = {}) {
     };
   }
   const estate = shape.kind === "estate";
-  const members = (shape.members ?? []).map((m) => ({ ...m, abs: resolve13(root, m.dir) }));
+  const members = (shape.members ?? []).map((m) => ({ ...m, abs: resolve14(root, m.dir) }));
   const targets = estate ? members.map((m) => m.abs) : [root];
   const primary = targets[0];
   const chantTargets = estate ? members.filter((m) => m.kind === "chant").map((m) => m.abs) : [root];
@@ -13294,7 +13450,7 @@ async function emulatorDown(projectDir) {
 
 // src/demos.ts
 import { readFileSync as readFileSync18, existsSync as existsSync17, cpSync, mkdirSync as mkdirSync6 } from "node:fs";
-import { dirname as dirname6, isAbsolute as isAbsolute4, join as join25, relative as relative7, resolve as resolve14, sep as sep6 } from "node:path";
+import { dirname as dirname6, isAbsolute as isAbsolute4, join as join25, relative as relative7, resolve as resolve15, sep as sep6 } from "node:path";
 import { spawn as spawn6, spawnSync as spawnSync2 } from "node:child_process";
 function readCatalog(file, catalog) {
   let raw;
@@ -13305,7 +13461,7 @@ function readCatalog(file, catalog) {
   }
   const list3 = raw?.demos;
   if (!Array.isArray(list3)) return [];
-  const catalogDir = dirname6(resolve14(file));
+  const catalogDir = dirname6(resolve15(file));
   return list3.filter((e) => validEntry(e)).map((e) => ({ ...e, catalog, catalogDir }));
 }
 function validEntry(e) {
@@ -13342,7 +13498,7 @@ function loadDemoRegistry(pkgRoot3) {
   const merged = readCatalog(join25(pkgRoot3, "demos.json"), "demos");
   const seen = new Set(merged.map((e) => e.name));
   const named = process.env.BEHOLD_WORKBENCH;
-  for (const e of [...readCatalog(join25(pkgRoot3, "workbench.json"), "workbench"), ...named ? readCatalog(resolve14(named), "workbench") : []]) {
+  for (const e of [...readCatalog(join25(pkgRoot3, "workbench.json"), "workbench"), ...named ? readCatalog(resolve15(named), "workbench") : []]) {
     if (seen.has(e.name)) {
       process.stderr.write(`behold: workbench entry "${e.name}" collides with a demo already in the catalog \u2014 dropped
 `);
@@ -13355,7 +13511,7 @@ function loadDemoRegistry(pkgRoot3) {
 }
 function demoLocalPath(entry) {
   if (entry.source !== "local" || !entry.path) return void 0;
-  return isAbsolute4(entry.path) ? entry.path : resolve14(entry.catalogDir ?? process.cwd(), entry.path);
+  return isAbsolute4(entry.path) ? entry.path : resolve15(entry.catalogDir ?? process.cwd(), entry.path);
 }
 function missingRequirements(entry) {
   const bins = entry.source === "git" && !entry.requires.includes("git") ? [...entry.requires, "git"] : entry.requires;
@@ -13374,9 +13530,9 @@ function fetchesFromNetwork(entry) {
 function demoTargetDir(entry, cwd = process.cwd()) {
   const inPlace = entry.inPlace ? demoLocalPath(entry) : void 0;
   if (inPlace) return inPlace;
-  const legacy = resolve14(cwd, "behold-demo");
+  const legacy = resolve15(cwd, "behold-demo");
   if (entry.name === "writes" && existsSync17(legacy)) return legacy;
-  return resolve14(cwd, "behold-demos", entry.name);
+  return resolve15(cwd, "behold-demos", entry.name);
 }
 async function loadDemo(entry, opts) {
   const { pkgRoot: pkgRoot3, target } = opts;
@@ -13785,6 +13941,20 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
   onDone: (opEnv) => captureFrame(cfg.projectDir, opEnv ?? cfg.env, frames, broadcaster)
 })) {
   const app = new Hono();
+  const guard = { allowedHosts: allowedHostsFrom(cfg.allowedHosts ?? []), ...cfg.host ? { boundHost: cfg.host } : {} };
+  app.use("*", async (c, next) => {
+    const verdict = guardRequest(
+      {
+        method: c.req.method,
+        host: c.req.header("host") ?? new URL(c.req.url).host,
+        origin: c.req.header("origin") ?? null,
+        secFetchSite: c.req.header("sec-fetch-site") ?? null
+      },
+      guard
+    );
+    if (!verdict.ok) return c.json({ error: verdict.error, code: "request-refused" }, verdict.status);
+    await next();
+  });
   setChoudoufuRunner(cfg.choudoufu?.run);
   setEstateLexiconRead(cfg.choudoufu ? cfg.choudoufu.lexicon ?? null : void 0);
   setServedWorkspace(cfg.workspace);
@@ -14006,6 +14176,7 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     return c.json({ history });
   });
   app.post("/api/operator/approve/:op/:gate", async (c) => {
+    if (cfg.previewMode) return c.json({ error: "approving is disabled in preview mode", code: "preview" }, 403);
     const { op, gate } = c.req.param();
     const info = estateOps().find((o) => o.name === op);
     broadcaster.emit("op", `\u270E approve ${op} ${gate} \u2014 records a fact; the next tick acts on it`);
@@ -14016,6 +14187,7 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     return c.json({ recorded: true, op, gate, semantics: APPROVE_SEMANTICS });
   });
   app.post("/api/ops/:name/signal/:gate", async (c) => {
+    if (cfg.previewMode) return c.json({ error: "approving is disabled in preview mode", code: "preview" }, 403);
     const { name, gate } = c.req.param();
     const info = estateOps().find((o) => o.name === name);
     broadcaster.emit("op", `\u270E signal ${name} ${gate}`);
@@ -14023,6 +14195,38 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     if (code !== 0) return c.json({ error: stderr.trim() || `signal exited ${code}` }, 500);
     return c.json({ signalled: true });
   });
+  app.get("/api/workspace/gates", async (c) => {
+    const ws = servedWorkspace();
+    const env = c.req.query("env") || cfg.env || "local";
+    if (!isEnvName(env)) return c.json({ error: `${JSON.stringify(env)} isn't an env name`, code: "env" }, 400);
+    if (!ws) return c.json({ workspace: false, env, gates: [], approver: localApprover() });
+    const read = await readWorkspaceGates(ws, env);
+    if (!read.ok) return c.json({ workspace: true, env, gates: [], refusal: read.refusal, approver: localApprover() });
+    return c.json({ workspace: true, env, gates: read.gates.map(({ dir: _dir, ...g }) => g), approver: localApprover() });
+  });
+  app.post("/api/workspace/gates/approve", async (c) => {
+    if (cfg.previewMode) return c.json({ error: "approving is disabled in preview mode", code: "preview" }, 403);
+    if (!(c.req.header("content-type") ?? "").toLowerCase().startsWith("application/json")) {
+      return c.json({ error: "send the body as application/json", code: "content-type" }, 415);
+    }
+    const ws = servedWorkspace();
+    if (!ws) return c.json({ error: "behold isn't serving a declared workspace", code: "no-workspace" }, 404);
+    const body = await c.req.json().catch(() => ({}));
+    const key = typeof body?.key === "string" ? body.key : "";
+    const env = typeof body?.env === "string" && body.env ? body.env : cfg.env || "local";
+    if (!isEnvName(env)) return c.json({ error: `${JSON.stringify(env)} isn't an env name`, code: "env" }, 400);
+    const read = await readWorkspaceGates(ws, env);
+    if (!read.ok) return c.json({ error: read.refusal.error, code: read.refusal.code }, 422);
+    const g = read.gates.find((x) => x.key === key);
+    if (!g) return c.json({ error: `no gate ${key} is waiting in ${env}`, code: "no-gate" }, 404);
+    if (g.signed) return c.json({ error: `${key} wants a signed approval, which behold can't make. Run: ${g.approve}`, code: "signed" }, 422);
+    const approver = localApprover();
+    broadcaster.emit("op", `\u270E approve ${g.key} as ${approver}`);
+    const { code, stderr, stdout } = await runChantRaw(approveArgs(g), g.dir);
+    if (code !== 0) return c.json({ error: stderr.trim() || stdout.trim() || `approve exited ${code}`, code: "approve" }, 500);
+    broadcaster.emit("changed", "");
+    return c.json({ recorded: true, key: g.key, approver });
+  });
   app.get(
     "/api/events",
     (c) => streamSSE(c, async (stream) => {
@@ -14089,6 +14293,9 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
       currentEnv: cfg.env ?? null,
       // v0.1.0 preview: the SPA hides git/PR ops + arbitrary-project affordances.
       ...cfg.previewMode ? { previewMode: true } : {},
+      // #477: who `chant approve` records when behold runs it. The approve
+      // buttons say it before the click.
+      approver: localApprover(),
       // The tier picker's options (M2 #54, sourced #70): gated on the served
       // project's `.behold.json` declaring a `tiers` block at all — NOT on
       // whether its env var happens to be set in behold's own launch env
@@ -14139,7 +14346,7 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
   app.post("/api/project/open", async (c) => {
     if (cfg.previewMode) return c.json({ error: "switching projects is locked in preview mode" }, 403);
     const body = await c.req.json().catch(() => ({}));
-    const dir = typeof body.dir === "string" && body.dir.trim() ? resolve15(body.dir.trim()) : "";
+    const dir = typeof body.dir === "string" && body.dir.trim() ? resolve16(body.dir.trim()) : "";
     if (!dir || !existsSync18(dir)) return c.json({ error: `no such directory: ${dir || "(no dir given)"}` }, 400);
     if (!existsSync18(join26(dir, "chant.config.ts"))) {
       return c.json({ error: `${dir} doesn't look like a chant project \u2014 no chant.config.ts` }, 400);
@@ -14164,7 +14371,7 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
   };
   app.post("/api/project/reveal", async (c) => {
     const body = await c.req.json().catch(() => ({}));
-    const dir = typeof body.dir === "string" && body.dir.trim() ? resolve15(body.dir.trim()) : cfg.projectDir;
+    const dir = typeof body.dir === "string" && body.dir.trim() ? resolve16(body.dir.trim()) : cfg.projectDir;
     const known = /* @__PURE__ */ new Set([cfg.projectDir, ...cfg.projectDirs ?? [], ...listRecents().map((r) => r.dir)]);
     if (!known.has(dir)) return c.json({ error: "not a served or recent project directory" }, 400);
     const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
@@ -14375,10 +14582,12 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
         { method: "GET", path: "/api/history", desc: "recent source commits (rollback targets)" },
         { method: "GET", path: "/api/frames", desc: "captured lanes frames" },
         { method: "GET", path: "/api/events", desc: "SSE: changed / op / apply / run / pr" },
-        { method: "POST", path: "/api/refresh", desc: "re-observe live now (?env=) \u2014 returns the fresh graph" },
+        { method: "POST", path: "/api/refresh", desc: "re-observe live now (?env=) \u2014 returns the fresh graph. With ?notify=1 it is a host's notice that the workspace changed: cached reads are dropped and every open page re-pulls (#476)" },
         { method: "POST", path: "/api/apply", desc: "delegated apply: ?env=&component=<name|all> (guarded, preview-locked)" },
         { method: "POST", path: "/api/ops/:name/run", desc: "run a committed Op (delegated write)" },
         { method: "POST", path: "/api/ops/:name/signal/:gate", desc: "approve an Op's gate (releases the waiting run)" },
+        { method: "GET", path: "/api/workspace/gates", desc: "a declared workspace's waiting gates from chant workspace status <env> --json (?env=), keyed member/op/gate, with the approver behold would record (#477)" },
+        { method: "POST", path: "/api/workspace/gates/approve", desc: "approve one workspace gate: JSON body {key, env}; env and plan come from a fresh status read; recorded as the user running behold; preview-locked (#477)" },
         { method: "POST", path: "/api/operator/approve/:op/:gate", desc: "record a converge gate's resolution (chant approve \u2014 a fact for the next tick, not an unblock)" },
         { method: "POST", path: "/api/rollback", desc: "open a rollback PR: ?to=<sha>" },
         { method: "POST", path: "/api/substrates/:name/up", desc: "bring a substrate up" },
@@ -14984,7 +15193,14 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     }
   });
   app.post("/api/refresh", async (c) => {
-    const env = optsFromQuery(new URL(c.req.url)).env ?? cfg.env;
+    const url = new URL(c.req.url);
+    if (url.searchParams.get("notify") === "1") {
+      invalidateMember();
+      invalidateOverlay();
+      broadcaster.emit("changed", "");
+      return c.json({ notified: true });
+    }
+    const env = optsFromQuery(url).env ?? cfg.env;
     const result = await captureFrame(cfg.projectDir, env, frames, broadcaster);
     if (!result) return c.json({ error: "refresh failed \u2014 see server log" }, 500);
     if (env) reclassifyOverlay(result.ir);
@@ -15064,9 +15280,9 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
   });
   const choudoufuPlanPath = (plan) => {
     if (!plan) return { error: "no plan named", code: "choudoufu_no_plan", remedy: "pass ?plan=<path to a carve.json inside a served choudoufu member> \u2014 GET /api/project lists the ones found" };
-    const abs = resolve15(cfg.projectDir, plan);
+    const abs = resolve16(cfg.projectDir, plan);
     const members = (cfg.projectDirs ?? [cfg.projectDir]).filter((d) => memberKindOf(d) === "choudoufu");
-    const inside = members.some((d) => abs.startsWith(resolve15(d) + sep7));
+    const inside = members.some((d) => abs.startsWith(resolve16(d) + sep7));
     if (!inside) return { error: `${plan} is not inside a served choudoufu member`, code: "choudoufu_plan_outside", remedy: "a plan lives in the estate it moves; point ?plan= at a carve.json under one of the served members" };
     return { path: abs };
   };
@@ -15197,6 +15413,10 @@ function createApp(cfg, broadcaster = new Broadcaster(), frames = new FrameBuffe
     return c.json({ started: true, component, env });
   });
   const rel = relative8(process.cwd(), webRoot) || ".";
+  app.use("/*", async (c, next) => {
+    await next();
+    if (!c.req.path.startsWith("/api/") && c.res.ok && !c.res.headers.has("cache-control")) c.res.headers.set("cache-control", "no-cache");
+  });
   app.use("/*", serveStatic({ root: rel }));
   app.get("/", serveStatic({ path: join26(rel, "index.html") }));
   return app;
@@ -15236,6 +15456,7 @@ async function startServer(cfg) {
     broadcaster,
     onDone: (opEnv) => captureFrame(cfg.projectDir, opEnv ?? cfg.env, frames, broadcaster)
   });
+  if (!cfg.host && process.env.BEHOLD_HOST) cfg.host = process.env.BEHOLD_HOST;
   const app = createApp(cfg, broadcaster, frames, runner);
   const autoSync = cfg.autoSync ?? "off";
   if (!cfg.carveReport) {
@@ -15343,7 +15564,8 @@ async function startServer(cfg) {
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
-  const server = serve({ fetch: app.fetch, port: cfg.port }, (info) => {
+  const hostname = cfg.host ?? process.env.BEHOLD_HOST ?? "127.0.0.1";
+  const server = serve({ fetch: app.fetch, port: cfg.port, hostname }, (info) => {
     if (carve) {
       process.stdout.write(
         `behold \u2192 http://localhost:${info.port}
@@ -15394,7 +15616,7 @@ init_chant();
 // src/workspace-convert.ts
 init_chant();
 import { existsSync as existsSync19, mkdirSync as mkdirSync7, readFileSync as readFileSync20, renameSync as renameSync2, writeFileSync as writeFileSync6 } from "node:fs";
-import { basename as basename4, dirname as dirname8, join as join27, relative as relative9, resolve as resolve16, sep as sep8 } from "node:path";
+import { basename as basename4, dirname as dirname8, join as join27, relative as relative9, resolve as resolve17, sep as sep8 } from "node:path";
 import { shortStackNames as shortStackNames2 } from "@intentius/pinhole";
 init_project();
 init_terraform_member();
@@ -15411,7 +15633,7 @@ function unique(name, taken) {
 }
 var posix = (p) => p.split(sep8).join("/");
 function installedVersion(pkg, dir) {
-  for (let at = resolve16(dir); ; at = dirname8(at)) {
+  for (let at = resolve17(dir); ; at = dirname8(at)) {
     const manifest = join27(at, "node_modules", ...pkg.split("/"), "package.json");
     if (existsSync19(manifest)) {
       try {
@@ -15425,14 +15647,14 @@ function installedVersion(pkg, dir) {
   }
 }
 function planConversion(rootArg) {
-  const root = resolve16(rootArg);
+  const root = resolve17(rootArg);
   const existing = DECLARATION_FILES.find((f) => existsSync19(join27(root, f)));
   if (existing) return { ok: false, error: `${root} already has ${existing}; there is nothing to convert.` };
   const shape = detectProjectShape(root);
   if (shape.kind !== "estate" || !shape.members?.length || shape.membersFrom === "itself") {
     return { ok: false, error: `${root} is not an estate root with a member list, so there is no member list to convert.` };
   }
-  const abs = shape.members.map((m) => resolve16(root, m.dir));
+  const abs = shape.members.map((m) => resolve17(root, m.dir));
   const shorts = shortStackNames2(abs);
   const taken = /* @__PURE__ */ new Set();
   const members = [];
@@ -15500,7 +15722,7 @@ function applyConversion(plan) {
   let layout;
   const target = layoutPath(plan.root);
   if (!plan.layoutFrom) layout = { skipped: "no saved layout to move" };
-  else if (resolve16(plan.layoutFrom) === resolve16(target)) layout = { skipped: "the saved layout is already in the root" };
+  else if (resolve17(plan.layoutFrom) === resolve17(target)) layout = { skipped: "the saved layout is already in the root" };
   else if (existsSync19(target)) layout = { skipped: `${target} already exists; the layout in ${plan.layoutFrom} was left alone` };
   else {
     const moved = moveLayoutIds(readLayoutFile(dirname8(dirname8(plan.layoutFrom))), plan.moves);
@@ -15694,7 +15916,7 @@ Usage:
   behold doctor [project-dir] [--json] [--fix]
   behold preview [project-dir] [--port <n>] [--emulator]
   behold export [project-dir] [--out <dir>] [--env <name>] [--name <worker>] [--emulator]
-  behold serve <project-dir\u2026> [--port <n>] [--env <name>] [--poll <secs>] [--local]
+  behold serve <project-dir\u2026> [--port <n>] [--host <addr>] [--allow-host <name,\u2026>] [--env <name>] [--poll <secs>] [--local]
   behold carve <report.json> [--port <n>]
 
   carve   Render a chant Terraform peelability report \u2014 the JSON from
@@ -15753,6 +15975,12 @@ Usage:
 
 Options:
   --port <n>          Port (default 4600). preview/serve/carve.
+  --host <addr>       serve only: the address to bind (default 127.0.0.1, or
+                      BEHOLD_HOST). behold runs writes with your credentials,
+                      so it answers this machine unless you say otherwise.
+  --allow-host <n,\u2026>  serve only: names besides loopback behold answers to, and
+                      whose pages may write (BEHOLD_ALLOWED_HOSTS too). For a
+                      proxy that frames behold, or --host 0.0.0.0.
   --env <name>        Environment name \u2014 turns on the live drift overlay.
                       export/serve.
   --poll <secs>       Re-query live drift every <secs> and push updates (needs --env).
@@ -15837,9 +16065,13 @@ ${USAGE}`);
   let pollSecs;
   let autoSync = "off";
   let local = false;
+  let host;
+  const allowHosts = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--port") port = Number(rest[++i]);
+    else if (a === "--host") host = rest[++i];
+    else if (a === "--allow-host") allowHosts.push(...(rest[++i] ?? "").split(","));
     else if (a === "--env") env = rest[++i];
     else if (a === "--poll") pollSecs = Number(rest[++i]);
     else if (a === "--local") local = true;
@@ -15880,7 +16112,7 @@ ${USAGE}`);
     process.stderr.write("behold serve: --auto-sync needs --env and --poll (it acts on polled drift)\n");
     process.exit(2);
   }
-  const dirs = projectDirs.map((d) => resolve17(d));
+  const dirs = projectDirs.map((d) => resolve18(d));
   const workspace = dirs.length === 1 && hasDeclaration(dirs[0]) ? await declaredWorkspace(dirs[0]) : void 0;
   if (workspace) {
     const drawn = drawnMembers(workspace).map((m) => m.abs);
@@ -15892,7 +16124,9 @@ ${USAGE}`);
       ...env ? { env } : {},
       ...pollSecs !== void 0 ? { pollSecs } : {},
       ...autoSync !== "off" ? { autoSync } : {},
-      ...local ? { local: true } : {}
+      ...local ? { local: true } : {},
+      ...host ? { host } : {},
+      ...allowHosts.length ? { allowedHosts: allowHosts } : {}
     });
     return;
   }
@@ -15909,7 +16143,9 @@ ${USAGE}`);
     ...env ? { env } : {},
     ...pollSecs !== void 0 ? { pollSecs } : {},
     ...autoSync !== "off" ? { autoSync } : {},
-    ...local ? { local: true } : {}
+    ...local ? { local: true } : {},
+    ...host ? { host } : {},
+    ...allowHosts.length ? { allowedHosts: allowHosts } : {}
   });
 }
 async function declaredWorkspace(root) {
@@ -15976,7 +16212,7 @@ async function runCarve(rest) {
     );
     process.exit(2);
   }
-  const reportPath = resolve17(fileArg);
+  const reportPath = resolve18(fileArg);
   const parsed = readCarveReport(reportPath, (p) => readFileSync22(p, "utf8"));
   if (!parsed.ok) {
     process.stderr.write(`behold carve: ${parsed.refusal.error}
@@ -16006,8 +16242,8 @@ async function runDoctor(rest) {
     }
   }
   const dir = dirArg ?? ".";
-  if (!existsSync21(resolve17(dir))) {
-    process.stderr.write(`behold doctor: no such directory: ${resolve17(dir)}
+  if (!existsSync21(resolve18(dir))) {
+    process.stderr.write(`behold doctor: no such directory: ${resolve18(dir)}
 `);
     process.exit(2);
   }
@@ -16106,7 +16342,7 @@ async function runDemo(rest) {
 `);
     process.exit(2);
   }
-  const target = dirArg ? resolve17(dirArg) : demoTargetDir(entry);
+  const target = dirArg ? resolve18(dirArg) : demoTargetDir(entry);
   const loaded = await loadDemo(entry, { pkgRoot: pkgRoot3, target, log: (line) => process.stdout.write(line + "\n") });
   if (!loaded.ok) {
     process.stderr.write(`behold demo ${entry.name}: ${loaded.error}
@@ -16138,7 +16374,7 @@ function spawnStep(cmd, args, cwd) {
   });
 }
 async function serveCarveDemo(target, carve, port, live2 = false) {
-  const at = (rel) => resolve17(target, rel);
+  const at = (rel) => resolve18(target, rel);
   const project = at(carve.project);
   const from = at(carve.from);
   const state = carve.state ? at(carve.state) : void 0;
@@ -16259,7 +16495,7 @@ async function runPreview(rest) {
     process.stderr.write("behold preview: --port must be a number\n");
     process.exit(2);
   }
-  const projectDir = resolve17(dirArg ?? process.cwd());
+  const projectDir = resolve18(dirArg ?? process.cwd());
   if (!existsSync21(projectDir)) {
     process.stderr.write(`behold preview: project not found at ${projectDir}
 `);
@@ -16280,21 +16516,21 @@ async function runPreview(rest) {
   await startServer({ projectDir, port, env: "local", previewMode: true });
 }
 async function runExportCmd(rest) {
-  let outDir = resolve17("behold-export");
+  let outDir = resolve18("behold-export");
   let env;
   let name;
   let dirArg;
   let emulator = false;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
-    if (a === "--out") outDir = resolve17(rest[++i]);
+    if (a === "--out") outDir = resolve18(rest[++i]);
     else if (a === "--env") env = rest[++i];
     else if (a === "--name") name = rest[++i];
     else if (a === "--emulator") emulator = true;
     else if (a === "-h" || a === "--help") return void process.stdout.write(USAGE);
     else if (!a.startsWith("-")) dirArg = a;
   }
-  const projectDir = resolve17(dirArg ?? process.cwd());
+  const projectDir = resolve18(dirArg ?? process.cwd());
   if (emulator) {
     injectEmulatorEnv(env);
     env ??= "local";