@monster-orange/den 0.4.3 → 0.4.5

package/src/shared/cli-command.ts

@@ -0,0 +1,186 @@
+/**
+ * SEC-2a: the commands a page prints for a person to run, and the names it
+ * gives the machines involved (the signed-out page, SEC-2 spec "exact
+ * copy"). One helper builds every printed command, so none is ever a bare
+ * `<cli>` that the server's user can't run:
+ *
+ *  - `<cli>` when the first `<cli>` on PATH is this distribution's own
+ *    (its bin/<cli> shim, or Den's bin/den in Den's own checkout), else the
+ *    shim's absolute path;
+ *  - each argument shell-quoted only when it needs it;
+ *  - an ssh one-liner quotes the remote command once more, for the shell
+ *    on the far side.
+ *
+ * Two host values (Vision): the label people read (`web.machine_name`, else
+ * the short os.hostname()) and the ssh target (the Host the browser used,
+ * minus the port). The browser's Host is never the label: it is often a
+ * service name, not a machine.
+ *
+ * Pure but for the filesystem probes, which are injectable for tests.
+ */
+import * as fs from "fs";
+import * as net from "net";
+import * as path from "path";
+
+export interface CliResolveDeps {
+  /** The PATH to search (the server's own: its user's). */
+  pathEnv?: string;
+  isExecutable?: (file: string) => boolean;
+  realpath?: (file: string) => string | null;
+}
+
+const defaultExecutable = (file: string): boolean => {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+const defaultRealpath = (file: string): string | null => {
+  try {
+    return fs.realpathSync(file);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * This distribution's command: its bin/<cli> shim, or (Den's own checkout,
+ * or a distribution without a shim) the engine's bin/den. Null when
+ * neither exists.
+ */
+export function distributionBin(
+  cli: string,
+  distRoot: string,
+  engineRoot: string,
+  isExecutable: (file: string) => boolean = defaultExecutable,
+): string | null {
+  for (const f of [
+    path.join(distRoot, "bin", cli),
+    path.join(engineRoot, "bin", "den"),
+  ])
+    if (isExecutable(f)) return f;
+  return null;
+}
+
+/** The first `name` on `pathEnv` that is executable, or null. */
+export function findOnPath(
+  name: string,
+  pathEnv: string,
+  isExecutable: (file: string) => boolean = defaultExecutable,
+): string | null {
+  for (const dir of pathEnv.split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir)) continue;
+    const f = path.join(dir, name);
+    if (isExecutable(f)) return f;
+  }
+  return null;
+}
+
+/**
+ * What a printed command starts with: `cli` when the first `cli` on PATH
+ * resolves to this distribution's bin, else that bin's absolute path. With
+ * no bin found at all, `cli` (there is nothing better to print).
+ */
+export function cliPrefix(
+  cli: string,
+  distRoot: string,
+  engineRoot: string,
+  deps: CliResolveDeps = {},
+): string {
+  const isExec = deps.isExecutable ?? defaultExecutable;
+  const real = deps.realpath ?? defaultRealpath;
+  const bin = distributionBin(cli, distRoot, engineRoot, isExec);
+  if (!bin) return cli;
+  const hit = findOnPath(cli, deps.pathEnv ?? process.env.PATH ?? "", isExec);
+  if (hit) {
+    const a = real(hit);
+    const b = real(bin);
+    if (a !== null && a === b) return cli;
+  }
+  return bin;
+}
+
+/** `s` as one word for a POSIX shell: as it is when safe, else single-quoted. */
+export function shellQuote(s: string): string {
+  if (s !== "" && /^[A-Za-z0-9_@%+=:,./-]+$/.test(s)) return s;
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** A command line: `prefix` (cliPrefix) and its arguments, each quoted as needed. */
+export function cliCommand(prefix: string, ...args: string[]): string {
+  return [prefix, ...args].map(shellQuote).join(" ");
+}
+
+/** `ssh <target> '<remote>'`: the remote command quoted once more, for the far shell. */
+export function sshCommand(target: string, remote: string): string {
+  return `ssh ${shellQuote(target)} ${shellQuote(remote)}`;
+}
+
+/** A Host header's hostname: lowercase, no port, no IPv6 brackets. "" when none. */
+export function hostOfHeader(host: string | undefined): string {
+  const h = String(host ?? "")
+    .trim()
+    .toLowerCase();
+  if (!h) return "";
+  const v6 = /^\[([^\]]+)\](?::\d+)?$/.exec(h);
+  if (v6) return v6[1];
+  return h.replace(/:\d+$/, "").replace(/\.$/, "");
+}
+
+/** Whether `host` is an IP address literal (v4 or v6), not a name. */
+export function isIpLiteral(host: string): boolean {
+  return net.isIP(host.replace(/^\[|\]$/g, "")) !== 0;
+}
+
+/** The ssh target: the Host the browser used, minus the port; else `fallback`. */
+export function sshTarget(
+  hostHeader: string | undefined,
+  fallback: string,
+): string {
+  const h = hostOfHeader(hostHeader);
+  return /^[a-z0-9._:-]+$/.test(h) && !h.startsWith("-") ? h : fallback;
+}
+
+/** `Mac-Studio.localdomain` → `Mac-Studio`; an IP literal stays whole. */
+export function shortHostname(hostname: string): string {
+  const h = hostname.trim();
+  if (!h || isIpLiteral(h)) return h;
+  return h.split(".")[0] || h;
+}
+
+/** The longest `web.machine_name` accepted. */
+export const MACHINE_NAME_MAX = 64;
+
+/**
+ * `web.machine_name` as stored: a trimmed one-line label of printable
+ * characters, at most MACHINE_NAME_MAX long; null when unset or blank.
+ * Throws naming the key for anything else.
+ */
+export function parseMachineName(v: unknown): string | null {
+  if (v === undefined || v === null) return null;
+  if (typeof v !== "string")
+    throw new Error(
+      `web.machine_name must be a name (text), got ${JSON.stringify(v)}`,
+    );
+  const s = v.trim();
+  if (!s) return null;
+  if (
+    s.length > MACHINE_NAME_MAX ||
+    [...s].some((c) => c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f)
+  )
+    throw new Error(
+      `web.machine_name must be one line of at most ${MACHINE_NAME_MAX} characters`,
+    );
+  return s;
+}
+
+/** The label people read: `web.machine_name`, else the short hostname. */
+export function machineLabel(
+  machineName: string | null | undefined,
+  hostname: string,
+): string {
+  const m = (machineName ?? "").trim();
+  return m || shortHostname(hostname) || "this machine";
+}

package/src/shared/confirm-code.ts

@@ -0,0 +1,34 @@
+/**
+ * SEC-2a: the short codes people read and type, in Crockford's base32.
+ * Pure helpers, shared by the CLI (`web login` makes the confirmation
+ * code) and the server (login-waits.ts checks it; pair-requests.ts makes
+ * pairing codes), so the CLI imports no server module.
+ */
+import { randomInt } from "crypto";
+
+/** Crockford's base32: no I, L, O or U. */
+export const PAIR_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/** A `web login` confirmation code's length, without its dash. */
+export const CONFIRM_CODE_LEN = 8;
+
+/** A fresh confirmation code: `ABCD-EFGH` (Crockford base32, 40 bits). */
+export function newConfirmCode(
+  rand: (n: number) => number = randomInt,
+): string {
+  let s = "";
+  for (let i = 0; i < CONFIRM_CODE_LEN; i++) s += PAIR_ALPHABET[rand(32)];
+  return `${s.slice(0, 4)}-${s.slice(4)}`;
+}
+
+/** A typed confirmation code: any case, dashes and spaces ignored, O as 0, I and L as 1. */
+export function normalizeConfirmCode(input: string): string | null {
+  const s = String(input ?? "")
+    .toUpperCase()
+    .replace(/[\s-]/g, "")
+    .replace(/O/g, "0")
+    .replace(/[IL]/g, "1");
+  if (s.length !== CONFIRM_CODE_LEN) return null;
+  for (const c of s) if (!PAIR_ALPHABET.includes(c)) return null;
+  return s;
+}

package/src/shared/den-config.ts

@@ -18,6 +18,7 @@ import type { SecretsConfig } from "./secrets/index.js";
 import type { OrgConfig } from "./org.js";
 import { validateOrgSources, type WorkOrgsConfig } from "./org-sources.js";
 import { ConfigError, isConfigError } from "./config-error.js";
+import { validateCatalog, type CatalogEntry } from "./agents/catalog.js";
 import type { TestAccountsConfig } from "./auth/test-accounts.js";
 
 import { product } from "./product.js";
@@ -385,7 +386,18 @@ export interface UserConfig {
    * install directories). Per machine, so user.yml only: the distribution's
    * config never sets a path. See shared/agents/runtime-search.ts.
    */
-  agents?: { runtimes?: Record<string, { bin?: unknown } | null> };
+  agents?: {
+    runtimes?: Record<string, { bin?: unknown } | null>;
+    /** More runtime catalog entries (AG-0.5, agents/catalog.ts). */
+    runtime_catalog?: unknown;
+  };
+  /**
+   * The web server's per-machine keys (src/shared/web-session.ts
+   * readWebAuthConfig): allow_plain_http_remote, edge_unattested,
+   * github_client_id, and (SEC-2a) machine_name, the name the signed-out
+   * page gives this machine.
+   */
+  web?: Record<string, unknown>;
 }
 
 const ALL_ENVIRONMENTS: Environment[] = [
@@ -436,6 +448,40 @@ export function configuredRuntimeBin(
   }
 }
 
+/**
+ * user.yml's `agents.runtime_catalog`, checked (agents/catalog.ts), after
+ * the built-in entries and the distribution's (`taken`). Throws naming
+ * the key when malformed.
+ */
+export function configuredRuntimeCatalog(
+  taken: readonly string[],
+  read: () => UserConfig = readUserConfig,
+): CatalogEntry[] {
+  return validateCatalog(
+    read().agents?.runtime_catalog,
+    `agents.runtime_catalog (${path.basename(USER_CONFIG_PATH)})`,
+    taken,
+  );
+}
+
+/**
+ * Set (a path) or clear (null) `agents.runtimes.<id>.bin` in user.yml,
+ * keeping everything else there. The caller checks the path first.
+ */
+export function setUserRuntimeBin(id: string, bin: string | null): void {
+  const cfg = readUserConfig();
+  const agents = { ...(cfg.agents ?? {}) };
+  const runtimes = { ...(agents.runtimes ?? {}) };
+  if (bin === null) delete runtimes[id];
+  else runtimes[id] = { ...(runtimes[id] ?? {}), bin };
+  if (Object.keys(runtimes).length) agents.runtimes = runtimes;
+  else delete agents.runtimes;
+  const next: UserConfig = { ...cfg };
+  if (Object.keys(agents).length) next.agents = agents;
+  else delete next.agents;
+  writeUserConfig(next);
+}
+
 /** Read the per-engineer user config (config/local/user.yml). Returns {} if absent. */
 export function readUserConfig(): UserConfig {
   try {
@@ -790,6 +836,11 @@ export interface AgentsConfig {
    * persona replaces one of the same id.
    */
   persona_packs?: string[];
+  /**
+   * More runtime catalog entries (AG-0.5, agents/catalog.ts): a vendor CLI
+   * Den doesn't ship, with the same fields and checks as a built-in one.
+   */
+  runtime_catalog?: unknown[];
   /**
    * Any other key is an agent id: `agents.<id>.grants` widens that agent's
    * MCP scope to other workspaces (AG spec §5b). Config only: an agent
@@ -801,7 +852,11 @@ export interface AgentsConfig {
 export const DEFAULT_AGENTS_MAX_CONCURRENT = 4;
 
 /** The keys of `agents:` that are not an agent id. */
-export const AGENTS_RESERVED_KEYS = ["max_concurrent", "persona_packs"];
+export const AGENTS_RESERVED_KEYS = [
+  "max_concurrent",
+  "persona_packs",
+  "runtime_catalog",
+];
 
 /** One agent's own block, `agents.<id>`. */
 export interface AgentGrantsConfig {
@@ -816,6 +871,8 @@ export interface ResolvedAgentsConfig {
   personaPacks: string[];
   /** `agents.<id>` blocks, by agent id. */
   agents: Record<string, AgentGrantsConfig>;
+  /** The distribution's runtime catalog entries (AG-0.5), checked. */
+  runtimeCatalog: CatalogEntry[];
 }
 
 /** An agent id or workspace name: what WORKSPACE_NAME_RE accepts. */
@@ -838,6 +895,10 @@ export function readAgentsConfig(
     maxConcurrent: DEFAULT_AGENTS_MAX_CONCURRENT,
     personaPacks: [],
     agents: {},
+    runtimeCatalog: validateCatalog(
+      raw.runtime_catalog,
+      "agents.runtime_catalog",
+    ),
   };
   const max = raw.max_concurrent;
   if (max !== undefined) {
@@ -866,7 +927,7 @@ export function readAgentsConfig(
     const where = `agents.${id}`;
     if (!AGENT_KEY_RE.test(id) || !isMapping(block))
       throw new Error(
-        `${where}: unknown key (agents: takes max_concurrent, persona_packs, ` +
+        `${where}: unknown key (agents: takes max_concurrent, persona_packs, runtime_catalog, ` +
           `or an agent id mapping to { grants: [...] })`,
       );
     for (const k of Object.keys(block))

package/src/shared/dev-metrics/emit.ts

@@ -11,7 +11,13 @@
  * dev-metrics.emit.test.ts against golden envelopes captured via
  * DEV_METRICS_ENVELOPE_OUT):
  *   1. ALWAYS append one compact JSON line to <repoRoot>/.dev-metrics/events.jsonl.
- *   2. THEN best-effort ship to Sentry (Tier-1 -> log item, Tier-2 -> event item).
+ *   2. THEN, only when the engineer opted in, best-effort ship to Sentry
+ *      (Tier-1 -> log item, Tier-2 -> event item).
+ *
+ * Local only by default (den#2): nothing leaves the machine unless
+ * config/local/user.yml says `metrics: { share: true }` (the boolean, nothing
+ * else). A DSN, in the env or a synced dev-metrics.config, is where to send
+ * once opted in; on its own it never sends.
  *
  * Guarantees: never throws, never blocks the caller (the Sentry ship is
  * fire-and-forget, bounded to ~2s). CI=true / DEV_METRICS_DISABLED=1 suppress
@@ -27,6 +33,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { execFileSync } from "child_process";
 import { createHash, randomUUID } from "crypto";
+import * as yaml from "yaml";
 import { getDistRoot } from "../paths.js";
 
 import { product } from "../product.js";
@@ -116,6 +123,28 @@ function suppressShip(): boolean {
   return process.env.CI === "true" || process.env.DEV_METRICS_DISABLED === "1";
 }
 
+/**
+ * The opt-in (den#2): `metrics.share` is exactly `true` in the engineer's
+ * config/local/user.yml under the repo root. Read on each ship, so turning
+ * it off takes effect at once; any error reads as "not opted in".
+ */
+export function shareOptedIn(root: string = repoRoot()): boolean {
+  try {
+    const raw = fs.readFileSync(
+      path.join(root, "config", "local", "user.yml"),
+      "utf-8",
+    );
+    const doc = yaml.parse(raw) as unknown;
+    if (!doc || typeof doc !== "object") return false;
+    const m = (doc as { metrics?: unknown }).metrics;
+    return (
+      !!m && typeof m === "object" && (m as { share?: unknown }).share === true
+    );
+  } catch {
+    return false;
+  }
+}
+
 function resolveDsn(root: string): string {
   const env = process.env.DEV_METRICS_SENTRY_DSN;
   if (env) return env;
@@ -217,6 +246,7 @@ function ship(
   epoch: number,
   root: string,
 ): void {
+  if (!shareOptedIn(root)) return;
   const dsn = resolveDsn(root);
   if (!dsn) return;
   const parsed = parseDsn(dsn);

package/src/shared/edge/config.ts

@@ -29,10 +29,13 @@
  *     mounts: { <host path>: <container path> }   # read-only
  *     networks: [<external network>]
  *     args: [--accesslog=true]
+ *     proxy_protocol:               # a TCP-passthrough front proxy that
+ *       trusted_ips: [172.18.0.5]   # sends the PROXY protocol (SEC-2a)
  *   web:
  *     port: 7777             # the web UI; routed as `<brand name>`
  */
 import * as fs from "fs";
+import * as net from "net";
 import * as os from "os";
 import * as path from "path";
 import * as yaml from "yaml";
@@ -69,6 +72,7 @@ interface RawEdge {
   mounts?: Record<string, string>;
   networks?: string[];
   args?: string[];
+  proxy_protocol?: { trusted_ips?: unknown } | null;
 }
 
 function readYaml(file: string): Record<string, unknown> {
@@ -367,5 +371,40 @@ function computeEdgeConfig(root: string): EdgeConfig {
       ]),
     ],
     args: [...list(team.args, "args"), ...list(user.args, "args")],
+    proxyProtocolTrustedIps: proxyProtocolIps(
+      user.proxy_protocol ?? team.proxy_protocol,
+    ),
   };
 }
+
+/**
+ * `edge.proxy_protocol.trusted_ips`: a list of IPs or CIDRs (SEC-2a), or
+ * none. Throws naming the key on anything else.
+ */
+export function proxyProtocolIps(v: RawEdge["proxy_protocol"]): string[] {
+  if (v === undefined || v === null) return [];
+  if (typeof v !== "object" || Array.isArray(v))
+    throw new Error(
+      "edge.proxy_protocol must be a map: { trusted_ips: [...] }",
+    );
+  for (const k of Object.keys(v))
+    if (k !== "trusted_ips")
+      throw new Error(
+        `edge.proxy_protocol: unknown key "${k}" (known: trusted_ips)`,
+      );
+  const ips = list(v.trusted_ips, "proxy_protocol.trusted_ips");
+  for (const ip of ips) {
+    const [addr, bits, more] = ip.split("/");
+    const fam = net.isIP(addr);
+    const max = fam === 6 ? 128 : 32;
+    if (
+      !fam ||
+      more !== undefined ||
+      (bits !== undefined && (!/^\d{1,3}$/.test(bits) || Number(bits) > max))
+    )
+      throw new Error(
+        `edge.proxy_protocol.trusted_ips: "${ip}" is not an IP address or CIDR`,
+      );
+  }
+  return ips;
+}

package/src/shared/edge/render.ts

@@ -220,6 +220,97 @@ export const EDGE_ORG_LABEL = "den.edge.org";
  * `den.edge.org` (0.3.0-dev.40): edgeUp and `edge down` touch an existing
  * edge only when its root is theirs.
  */
+/**
+ * The addresses the edge's entrypoints believe X-Forwarded-* headers from
+ * (SEC-2a, in place of `forwardedHeaders.insecure`): loopback and the
+ * Docker networks the edge and its own proxies run on (Docker's
+ * 172.16.0.0/12, Docker Desktop's VM network). From anyone else Traefik
+ * drops the client's headers and writes its own; either way the right-most
+ * X-Forwarded-For entry is the peer it saw, which is all Den believes.
+ */
+export const EDGE_FORWARDED_TRUSTED_IPS: readonly string[] = [
+  "127.0.0.1/32",
+  "::1/128",
+  "172.16.0.0/12",
+  "192.168.65.0/24",
+];
+
+/** An `args` entry that sets what Den owns: the entrypoints' header or PROXY trust. */
+const OWNED_ARG =
+  /^--entrypoints\.[^.=]+\.(forwardedheaders\.(insecure|trustedips)|proxyprotocol\.)/i;
+
+/** The `edge.args` entries Den drops (SEC-2a): forwarded-header or PROXY trust. */
+export function droppedEdgeArgs(cfg: Pick<EdgeConfig, "args">): string[] {
+  return cfg.args.filter((a) => OWNED_ARG.test(a));
+}
+
+/** The edge entrypoints' trust (SEC-2a): forwarded headers, and the PROXY protocol when set. */
+export function edgeTrustArgs(cfg: EdgeConfig): string[] {
+  const eps = ["web", ...(edgeHttps(cfg) ? ["websecure"] : [])];
+  const pp = cfg.proxyProtocolTrustedIps ?? [];
+  return eps.flatMap((ep) => [
+    `--entrypoints.${ep}.forwardedHeaders.trustedIPs=${EDGE_FORWARDED_TRUSTED_IPS.join(",")}`,
+    ...(pp.length
+      ? [`--entrypoints.${ep}.proxyProtocol.trustedIPs=${pp.join(",")}`]
+      : []),
+  ]);
+}
+
+/** The edge container's command (its Traefik static config). */
+export function edgeCommand(cfg: EdgeConfig): string[] {
+  const https = edgeHttps(cfg);
+  const proxy = dockerProxyName(cfg.org);
+  const labels = cfg.dockerLabels;
+  return [
+    "--entrypoints.web.address=:80",
+    ...(https ? ["--entrypoints.websecure.address=:443"] : []),
+    ...edgeTrustArgs(cfg),
+    "--providers.file.directory=/etc/edge/dynamic",
+    "--providers.file.watch=true",
+    ...(labels
+      ? [
+          "--providers.docker=true",
+          `--providers.docker.endpoint=tcp://${proxy}:2375`,
+          "--providers.docker.exposedbydefault=false",
+          `--providers.docker.network=${labels.network}`,
+        ]
+      : []),
+    "--api.dashboard=true",
+    "--ping=true",
+    "--log.level=WARN",
+    ...cfg.args.filter((a) => !OWNED_ARG.test(a)),
+  ];
+}
+
+/**
+ * What changed between a running edge's command and the one `edge up`
+ * renders now, as words for its one-line notice; [] when nothing did (or
+ * the running one isn't known).
+ */
+export function edgeCommandDrift(
+  running: readonly string[] | null,
+  rendered: readonly string[],
+): string[] {
+  if (!running) return [];
+  const a = new Set(running);
+  const b = new Set(rendered);
+  const changed = [
+    ...rendered.filter((x) => !a.has(x)),
+    ...running.filter((x) => !b.has(x)),
+  ];
+  if (!changed.length) return [];
+  const what = new Set<string>();
+  for (const c of changed)
+    what.add(
+      /forwardedheaders/i.test(c)
+        ? "forwarded-header trust"
+        : /proxyprotocol/i.test(c)
+          ? "PROXY protocol"
+          : "its command",
+    );
+  return [...what];
+}
+
 export function renderEdgeCompose(
   cfg: EdgeConfig,
   ownerRoot: string = cfg.stateDir,
@@ -239,24 +330,7 @@ export function renderEdgeCompose(
       restart: "unless-stopped",
       labels: { [EDGE_ROOT_LABEL]: ownerRoot, [EDGE_ORG_LABEL]: cfg.org },
       ...(labels ? { depends_on: ["docker-proxy"] } : {}),
-      command: [
-        "--entrypoints.web.address=:80",
-        ...(https ? ["--entrypoints.websecure.address=:443"] : []),
-        "--providers.file.directory=/etc/edge/dynamic",
-        "--providers.file.watch=true",
-        ...(labels
-          ? [
-              "--providers.docker=true",
-              `--providers.docker.endpoint=tcp://${proxy}:2375`,
-              "--providers.docker.exposedbydefault=false",
-              `--providers.docker.network=${labels.network}`,
-            ]
-          : []),
-        "--api.dashboard=true",
-        "--ping=true",
-        "--log.level=WARN",
-        ...cfg.args,
-      ],
+      command: edgeCommand(cfg),
       ...(cfg.ports
         ? {
             ports: [

package/src/shared/edge/runtime.ts

@@ -7,7 +7,10 @@ import * as net from "net";
 import * as path from "path";
 import { must, sh } from "./exec.js";
 import {
+  droppedEdgeArgs,
   EDGE_ROOT_LABEL,
+  edgeCommand,
+  edgeCommandDrift,
   edgeNames,
   renderEdgeCompose,
   renderEdgeDynamic,
@@ -226,9 +229,58 @@ export function assertEdgeOwnedHere(
   );
 }
 
+/** A container's command (`docker inspect .Config.Cmd`), or null. */
+export function runningEdgeCommand(name: string): string[] | null {
+  const r = sh("docker", [
+    "inspect",
+    "--type",
+    "container",
+    "-f",
+    "{{json .Config.Cmd}}",
+    name,
+  ]);
+  if (r.code !== 0) return null;
+  try {
+    const v: unknown = JSON.parse(r.out);
+    return Array.isArray(v) && v.every((x) => typeof x === "string")
+      ? (v as string[])
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What `edge up` says before it writes compose.yml (SEC-2a): the `edge.args`
+ * it drops (Den owns the entrypoints' trust), and, when the running edge's
+ * command differs from the new one, that it recreates the edge once and
+ * why. Pure: `running` is the running container's command, or null.
+ */
+export function edgeUpNotices(
+  cfg: EdgeConfig,
+  running: readonly string[] | null,
+): string[] {
+  const out: string[] = [];
+  const dropped = droppedEdgeArgs(cfg);
+  if (dropped.length)
+    out.push(
+      `edge.args: ignoring ${dropped.join(", ")}: Den sets the entrypoints' ` +
+        "forwarded-header trust itself (its own networks and loopback), and " +
+        "PROXY protocol trust from edge.proxy_protocol.trusted_ips. Remove it " +
+        "from the config to silence this.",
+    );
+  const drift = edgeCommandDrift(running, edgeCommand(cfg));
+  if (drift.length)
+    out.push(
+      `${edgeNames(cfg.org).container}'s settings changed (${drift.join(", ")}): ` +
+        "recreating it once. Routes drop only while it restarts.",
+    );
+  return out;
+}
+
 export async function edgeUp(
   cfg: EdgeConfig,
-  opts: { takeOver?: boolean } = {},
+  opts: { takeOver?: boolean; log?: (line: string) => void } = {},
 ) {
   // Before anything is written or started: an edge of this name that
   // another state dir owns is never replaced.
@@ -261,6 +313,10 @@ export async function edgeUp(
   const included = syncIncluded(cfg);
   write(path.join(cfg.stateDir, "dynamic", GENERATED), renderEdgeDynamic(cfg));
   const compose = path.join(cfg.stateDir, "compose.yml");
+  // SEC-2a: say what changed before compose recreates the edge for it.
+  const log = opts.log ?? ((l: string) => console.log(l));
+  for (const line of edgeUpNotices(cfg, runningEdgeCommand(n.container)))
+    log(line);
   write(compose, renderEdgeCompose(cfg, realOrSelf(cfg.stateDir)));
   must("docker", ["compose", "-f", compose, "up", "-d", "--remove-orphans"]);
   return { certs, included };